# hermes-pitfalls-learned — details

## 详细资料（按需查阅）

> 以下文件不在本 SKILL.md 内，需要时再读；正文只保留每次都会用到的部分。

- **`references/archive-changelog.md`** — 含 11 节：1. 比较两个 key 是否一致、1. 确认 Ollama 运行并列出模型、3. 验证 API、2. 写入 .env、3. 验证 Key 有效性、4. 启用 web 工具集
- **`references/auth-permission.md`** — 含 1 节：重启（推荐 tmux 隔离，避免被 hermes update 的 Gateway 重启波及 SIGTERM）：
- **`references/data-pipeline.md`** — 含 6 节：❌ 错误: 按产品years字段分摊、✅ 正确: 从原始订单按年汇总、方案A（推荐）：生成内嵌数据时同时添加 customer 字段、步骤1：同步 config.yaml 中 provider key 为有效的 model key、3. 检查 JSONL 备份、前提：~/.hermes/sessio…
- **`references/details.md`** — 含 37 节：等待加载后提取内容、查看断连频率、方案B：JS 侧兼容、一次性任务、指定工具集、直接用 restart 通常可以绕过 bootstrap 错误
- **`references/feishu-api.md`** — 含 15 节：查看最近一次成功接收消息的时间、停掉现有 gateway 进程、2. 查看 state.db 中该飞书会话的 model 列是否为 null、3. 看 Gateway 日志中是否有连续的 "Agent error"、步骤2：设置环境变量（Gateway Agent 的 resolve_provide…

### 既有参考文件（原正文未引用，此处补齐索引）

- **`references/contract-review-checklist.md`** — 合同审核速查清单
- **`references/contract-review-workflow.md`** — 合同审核工作流（给法务/销售管理）
- **`references/data-source-labeling.md`** — 宝锐工作台数据来源标注规范
- **`references/feishu-api-integration.md`** — 飞书 API 接入指南（宝锐定制 · 2026-07-08 实测）
- **`references/feishu-integration.md`** — 飞书集成参考
- **`references/feishu-mcp-catalog.md`** — 飞书项目MCP工具速查
- **`references/feishu-mcp-guide.md`** — 飞书项目 MCP 接入完整指南
- **`references/feishu-mcp-integration.md`** — 飞书项目 MCP 集成完整指南
- **`references/feishu-mcp-urls.md`** — 飞书项目URL构造速查
- **`references/feishu-project-mcp.md`** — 飞书项目 MCP 接入手册
- **`references/feishu-project-setup.md`** — 飞书项目 (Meegle) 接入流程
- **`references/feishu-session-bloat-and-statedb-repair.md`** — 飞书会话膨胀 + state.db 损坏修复（2026-07-28）
- **`references/gateway-model-empty-config.md`** — Gateway Model Provider 空配置排查（2026-07-28）
- **`references/gateway-model-switch-fix.md`** — Gateway 模型切换后飞书全部 Agent error 的修复
- **`references/gateway-stability-pattern.md`** — Gateway 稳定性故障模式分类（2026-08-01）
- **`references/pptx-template-workflow.md`** — python-pptx 使用公司模板生成 PPT
- **`references/tailscale-port-conflict.md`** — Tailscale Serve/Funnel 端口冲突（2026-07-28）

# 重启（推荐 tmux 隔离，避免被 hermes update 的 Gateway 重启波及 SIGTERM）：
tmux new-session -d -s workbench -x 120 -y 10 \
  'cd /Users/liuxinyuan/Desktop/Hermes输出-工作类 && python3 脚本/销售工作台服务.py 8765'