# hermes-pitfalls-learned — feishu api

## Pitfall 10: 审批流转前必须确认实际阻塞节点

**症状**：`list_todo`显示"大区/部门经理审核"，尝试批量流转失败。

**根因**：`list_todo.node_name`是流程标签，不等于当前实际阻塞节点。

**正确方案**：逐条`get_node_detail`→过滤`status:"in_progress"`→确认当前用户是owner→`transition_node(action:"confirm")`。


## Pitfall 11: MQL语法和list_todo陷阱

**MQL**：project_key为独立参数；FROM格式`` `空间`.`类型` ``；不支持`SELECT *`；OFFSET分页可靠无重复。

**list_todo陷阱**：`node_name`是角色标签非当前活跃节点。业务线分类：含「课题组」=生命科学，其余=诊断原料。


## Pitfall 12: 飞书项目URL中 work_item_type 必须用 `story` 非 `sj`

**症状**：生成的URL `xsguanli/sj/detail/xxx` 点开显示"无对应工作项"。

**根因**：导出模板用 `sj`（商机缩写），前端路由用 `story`（type key）。

**修复**：所有URL `sj/detail` → `story/detail`。URL模板：`https://project.feishu.cn/{simple_name}/story/detail/{id}`。


## Pitfall 17: MQL WHERE + 大OFFSET超时（2026-07-09）

**症状**：`SELECT ... WHERE 创建时间 >= "2026-07-01" LIMIT 50 OFFSET 250` 超时。

**根因**：MCP服务器对WHERE+大OFFSET组合查询慢。

**正确方案**：先在销售管道中拉取全量订单并聚合到 `daily_sales_mcp.json` 的 `daily_summary` 中。KPI管道从 `daily_summary` 读取月度总额，避免重复调MCP做WHERE查询。


## Pitfall 19: 飞书项目URL work_item_type必须用`story`（2026-07-09）

**症状**：`xsguanli/sj/detail/{id}` 点击显示"无对应工作项"。

**根因**：导出模板用`sj`(商机)，但前端路由用 type key `story`。

**正确URL模板**：`https://project.feishu.cn/{simple_name}/story/detail/{work_item_id}`。验证：`meegle url decode --url "..."`。


## Pitfall 27: 客诉无法按人分权——需客户清单交叉匹配（2026-07-10）

**症状**：客诉只有 `id/name/days/url`，无owner字段。选销售员后无法过滤。

**解决方案**：客户清单Excel → `{客户名: 销售员}` 映射。客诉名称含客户名，前缀匹配。24/24全部成功。


## Pitfall 46: model.api_key 与 providers.<name>.api_key 不一致导致 Gateway Agent 全部报错（2026-07-19）

**症状**：CLI 会话一切正常，但飞书/微信 Gateway 每条消息都报 "Agent error"（或 "Sorry, I encountered an unexpected error"），即使 `/reset` 后也不行。Gateway 状态显示正常（feishu connected），且消息能被 Gateway 接收，但 Agent 处理时崩溃。

**根因**：`config.yaml` 中 `model.api_key` 和 `providers.<provider>.api_key` 是两个独立的值，可能不同步：
- CLI Agent 使用 `model.api_key`
- Gateway 的 api_server（监听 `127.0.0.1:8642`）使用 `providers.<provider>.api_key`

切换模型或手动修改配置时容易只更新一处而遗漏另一处。当 provider 级别的 key 失效或过期时，Gateway 每次调用 DeepSeek（或其他 provider）都返回 `Invalid API key`，导致所有会话崩溃。

**诊断**：
```bash
# ✅ 正确：shell-first 模式
tmux new-session -d -s turing -x 160 -y 50          # 1. 启动 shell
tmux send-keys -t turing "hermes --provider kimi-coding --model kimi-k2 --toolsets terminal,file,browser" Enter  # 2. 注入命令
sleep 10                                              # 3. 等待初始化完成

# 2. 注册为 Hermes provider（Ollama 提供 OpenAI 兼容的 /v1 端点）
hermes config set providers.local.api_key "ollama"
hermes config set providers.local.base_url "http://localhost:11434/v1"
hermes config set providers.local.default_model "qwen3:4b-16k"

# 1. 注册获取免费 API Key（1000次/月）
# 打开 https://app.tavily.com → Google/GitHub 登录 → Dashboard → 复制 Key（格式：tvly-...）

# 注册 https://brave.com/search/api/ → 获取 Key → 写入 .env
echo "BRAVE_SEARCH_API_KEY=BSA-your-key" >> ~/.hermes/.env
hermes tools enable web
```

**注意**：
- `hermes tools enable web` 后需要 `/reset` 新会话才能加载 web_search 工具
- Tavily Key 以 `tvly-` 开头（Dev Key）或 `tvly-dev-` 开头
- 工具生效后 `web_search` 和 `web_extract` 两个工具均可用
- 中国境内访问 Tavily API 正常，无需代理


## Pitfall 65: Gateway 飞书会话 1000+ 消息未 /reset 导致 API 超时（2026-07-28）

**症状**：飞书回复极短（3-7 字符），Gateway 日志 `APIConnectionError` 全 3 次重试失败。`hermes gateway restart` 超时（60s+），kill 旧进程后手动 start 才成功。

**根因**：同一飞书会话累积 1000+ 条消息未 `/reset`。每次 API 调用都要发送全部上下文（1000+ 条消息 = 数万 token），请求体过大导致 DeepSeek 连接超时。

**诊断**：
```bash
# 如果 DROP 报 "database disk image is malformed" → 放弃此路径，核心表已损坏
```

### 路径 B：.clone 导出/导入——本次场景失败
```bash
cp ~/.hermes/state.db ~/.hermes/state.db.bak
sqlite3 ~/.hermes/state.db ".clone /tmp/state_repaired.db"
# FTS 表可能重复创建，索引可能不存在
# 部署数据文件（1398 个 JSON/CSV）到 CloudBase
cd ~/Desktop/Hermes输出-工作类
tcb hosting deploy 数据/ 数据 -e bier-sales-d0gatbvlx288724e9
```


## Pitfall 10: 审批流转前必须确认实际阻塞节点

**症状**：`list_todo`显示"大区/部门经理审核"，尝试批量流转失败。

**根因**：`list_todo.node_name`是流程标签，不等于当前实际阻塞节点。

**正确方案**：逐条`get_node_detail`→过滤`status:"in_progress"`→确认当前用户是owner→`transition_node(action:"confirm")`。



## Pitfall 11: MQL语法和list_todo陷阱

**MQL**：project_key为独立参数；FROM格式`` `空间`.`类型` ``；不支持`SELECT *`；OFFSET分页可靠无重复。

**list_todo陷阱**：`node_name`是角色标签非当前活跃节点。业务线分类：含「课题组」=生命科学，其余=诊断原料。



## Pitfall 12: 飞书项目URL中 work_item_type 必须用 `story` 非 `sj`

**症状**：生成的URL `xsguanli/sj/detail/xxx` 点开显示"无对应工作项"。

**根因**：导出模板用 `sj`（商机缩写），前端路由用 `story`（type key）。

**修复**：所有URL `sj/detail` → `story/detail`。URL模板：`https://project.feishu.cn/{simple_name}/story/detail/{id}`。



## Pitfall 17: MQL WHERE + 大OFFSET超时（2026-07-09）

**症状**：`SELECT ... WHERE 创建时间 >= "2026-07-01" LIMIT 50 OFFSET 250` 超时。

**根因**：MCP服务器对WHERE+大OFFSET组合查询慢。

**正确方案**：先在销售管道中拉取全量订单并聚合到 `daily_sales_mcp.json` 的 `daily_summary` 中。KPI管道从 `daily_summary` 读取月度总额，避免重复调MCP做WHERE查询。



## Pitfall 19: 飞书项目URL work_item_type必须用`story`（2026-07-09）

**症状**：`xsguanli/sj/detail/{id}` 点击显示"无对应工作项"。

**根因**：导出模板用`sj`(商机)，但前端路由用 type key `story`。

**正确URL模板**：`https://project.feishu.cn/{simple_name}/story/detail/{work_item_id}`。验证：`meegle url decode --url "..."`。



## Pitfall 27: 客诉无法按人分权——需客户清单交叉匹配（2026-07-10）

**症状**：客诉只有 `id/name/days/url`，无owner字段。选销售员后无法过滤。

**解决方案**：客户清单Excel → `{客户名: 销售员}` 映射。客诉名称含客户名，前缀匹配。24/24全部成功。



## Pitfall 46: model.api_key 与 providers.<name>.api_key 不一致导致 Gateway Agent 全部报错（2026-07-19）

**症状**：CLI 会话一切正常，但飞书/微信 Gateway 每条消息都报 "Agent error"（或 "Sorry, I encountered an unexpected error"），即使 `/reset` 后也不行。Gateway 状态显示正常（feishu connected），且消息能被 Gateway 接收，但 Agent 处理时崩溃。

**根因**：`config.yaml` 中 `model.api_key` 和 `providers.<provider>.api_key` 是两个独立的值，可能不同步：
- CLI Agent 使用 `model.api_key`
- Gateway 的 api_server（监听 `127.0.0.1:8642`）使用 `providers.<provider>.api_key`

切换模型或手动修改配置时容易只更新一处而遗漏另一处。当 provider 级别的 key 失效或过期时，Gateway 每次调用 DeepSeek（或其他 provider）都返回 `Invalid API key`，导致所有会话崩溃。

**诊断**：
```bash
# ✅ 正确：shell-first 模式
tmux new-session -d -s turing -x 160 -y 50          # 1. 启动 shell
tmux send-keys -t turing "hermes --provider kimi-coding --model kimi-k2 --toolsets terminal,file,browser" Enter  # 2. 注入命令
sleep 10                                              # 3. 等待初始化完成

# 2. 注册为 Hermes provider（Ollama 提供 OpenAI 兼容的 /v1 端点）
hermes config set providers.local.api_key "ollama"
hermes config set providers.local.base_url "http://localhost:11434/v1"
hermes config set providers.local.default_model "qwen3:4b-16k"

# 1. 注册获取免费 API Key（1000次/月）
# 打开 https://app.tavily.com → Google/GitHub 登录 → Dashboard → 复制 Key（格式：tvly-...）

# 注册 https://brave.com/search/api/ → 获取 Key → 写入 .env
echo "BRAVE_SEARCH_API_KEY=BSA-your-key" >> ~/.hermes/.env
hermes tools enable web
```

**注意**：
- `hermes tools enable web` 后需要 `/reset` 新会话才能加载 web_search 工具
- Tavily Key 以 `tvly-` 开头（Dev Key）或 `tvly-dev-` 开头
- 工具生效后 `web_search` 和 `web_extract` 两个工具均可用
- 中国境内访问 Tavily API 正常，无需代理



## Pitfall 65: Gateway 飞书会话 1000+ 消息未 /reset 导致 API 超时（2026-07-28）

**症状**：飞书回复极短（3-7 字符），Gateway 日志 `APIConnectionError` 全 3 次重试失败。`hermes gateway restart` 超时（60s+），kill 旧进程后手动 start 才成功。

**根因**：同一飞书会话累积 1000+ 条消息未 `/reset`。每次 API 调用都要发送全部上下文（1000+ 条消息 = 数万 token），请求体过大导致 DeepSeek 连接超时。

**诊断**：
```bash
# 如果 DROP 报 "database disk image is malformed" → 放弃此路径，核心表已损坏
```

### 路径 B：.clone 导出/导入——本次场景失败
```bash
cp ~/.hermes/state.db ~/.hermes/state.db.bak
sqlite3 ~/.hermes/state.db ".clone /tmp/state_repaired.db"
# FTS 表可能重复创建，索引可能不存在
# 部署数据文件（1398 个 JSON/CSV）到 CloudBase
cd ~/Desktop/Hermes输出-工作类
tcb hosting deploy 数据/ 数据 -e bier-sales-d0gatbvlx288724e9
```