# hermes-pitfalls-learned — archive changelog

## Pitfall 1: file:// 协议下 fetch() 全部失败

**症状**：从 `file:///Users/.../xxx.html` 打开的页面中所有 `fetch()` 返回404或CORS错误。

**根因**：`file://` 协议下 `fetch('/路径')` 解析为 `file:///路径`（文件系统），非HTTP请求。且 `file://` → `http://` 被浏览器CORS拦截。

**解决方案**：大数据内嵌HTML；轻量数据用 `httpBase` 拼接；文件清单用Python扫描→JSON→页面fetch。


## Pitfall 2: 文件被误删 / symlink断链

**症状**：生成的HTML文件失踪，`ls` 显示 "broken symbolic link"。

**解决方案**：写入前 `~/.hermes/scripts/safe_write.sh <filepath>` 自动备份（保留5版）；Symlink仅用于命名兼容。


## Pitfall 3: MEMORY.md 超限

**症状**：MEMORY.md 超过2200字符，Agent写入受限。

**解决方案**：定期精简，只保留稳定业务事实；过程性知识放skills。完整精简方案和 Hermes 体检流程见 `references/hermes-health-check.md`。


## Pitfall 4: HTML生成中JS语法错误高频

**症状**：`node --check` 报错，页面空白。

**解决方案**：用 `write_file` 写完整HTML（不用patch拼接）；写完必须 `node --check`。


## Pitfall 5: 归档检测不工作

**症状**：访前准备中心文件状态始终"待生成"。

**当前方案**：Python扫描→`file_manifest.json`→页面fetch+模糊匹配。`custShort`算法：去括号→去后缀→迭代剥离。


## Pitfall 6: 长时间会话效率下降

**应对**：`max_turns: 60`, `temperature: 0.3`, `tool_use_enforcement: strict`，50轮+拆分到子Agent。


## Pitfall 7: 合同/声明文件审核

**触发**：文件放入 `~/Desktop/hermes输入/合同审核/`。

**流程**：提取全文→四级风险标注(🔴P0/🟡P1/🟢P2)→逐条修改建议→修订版docx。输出到 `~/Desktop/Hermes输出-工作类/合同/`。

**常见检查点**：价格锁死无调价出口、知识产权归属模糊、授权范围过度、保密期过短、争议管辖不利。


## Pitfall 16: list_related_workitem间歇超时（2026-07-09）

**修复**：超时设30s（非15s），加3次重试，建`{wid: customer}`缓存避免重复查询。客户名补全失败时不应阻塞整体管道——继续输出已拉取的订单，客户列留空待下次补全。


## Pitfall 20: 功能交付不完整导致用户挫败（2026-07-09）

**症状**：用户说"你真的把我要的功能更新了吗？排序没有、按月季度分组没有"。添加了 `dateKey` 但没有同步配置 `sumKeys` 和聚合列渲染逻辑。

**根因**：只完成了基础设施（参数传递），没完成端到端功能（用户可见的效果）。`HermesTable.render({dateKey:'date'})` 只加了日期筛选栏，聚合模式需要 `sumKeys` + `renderCols` 动态交换才能正确显示。

**铁律**：用户说"要做A+B+C"，验收标准是A+B+C全部能用，不是"框架支持A+B+C但没调通"。

**自查清单**（每次改完页面后）：
1. `node --check` JS语法 ✅
2. 打开浏览器点每个按钮 → 确认有响应
3. 切换周期（日/周/月/季/年）→ 确认数据正确聚合
4. 点列头排序 → 确认升/降/取消三态切换
5. 搜关键词 → 确认筛选结果正确
6. CSV导出 → 确认文件可打开
1. 写入前备份：`~/.hermes/scripts/safe_write.sh <filepath>`
2. 写入后验证：`ls -la` + HTTP HEAD
3. 不创建symlink链

### HTML卡片规范
1. 顶栏：48px白底，BIORI BIOTECH
2. 配色：`--pri:#1a73e8` 白蓝科技风
3. JS语法：`node --check` 必过
4. 编辑栏：右下角 ✏️编辑/💾保存/↩恢复 float bar
5. contentEditable + localStorage 持久化


## Pitfall 24: 功能交付前必须端到端验证（2026-07-09）

**教训**：用户说"你真的把我要的功能更新了吗？排序没有、按月季度分组没有"——只加了 `dateKey` 参数但没配 `sumKeys` 和聚合列渲染。

**自查清单**：每次改完页面 → 1) JS语法 2) 每个按钮有响应 3) 周期切换正确 4) 排序三态 5) 搜索筛选 6) CSV导出


## Pitfall 30: macOS screencapture 对 Chrome 窗口失败（2026-07-11）

**症状**：`screencapture -l <Chrome WindowID>` 返回 "could not create image from window"。

**根因**：macOS 26.5 的 screencapture 无法截取 Chrome 窗口。System Events 辅助功能也需手动授权。

**替代方案**：
1. Chrome AppleScript + `execute javascript` 获取 innerText（需先开启：Chrome → 查看 → 开发者 → 允许 Apple 事件中的 JavaScript）
2. `computer_use` 工具（需 `cua-driver` 安装，但国内网络下载 GitHub release 超时）
3. 用户手动截图/导出


## Pitfall 67: 端口被 Tailscale Serve 占用——8765 不通（2026-07-27）

**症状**：`python3 销售工作台服务.py 8765` 反复失败 `OSError: [Errno 48] Address already in use`。`lsof -i :8765` 有时不显示进程，但 `netstat -anv | grep 8765` 显示 `io.tailscale.ipn` 绑定。换成 8766 立即正常。

**根因**：**Tailscale Serve** 之前配置了 `tailscale serve --https=8765 / http://127.0.0.1:8000`，在 8765 端口做了代理。即使用 `kill` 杀进程，Tailscale 也会重新绑定。

**诊断**：
```bash
# 确认 Tailscale Serve 配置
tailscale serve status

## Pitfall 1: file:// 协议下 fetch() 全部失败

**症状**：从 `file:///Users/.../xxx.html` 打开的页面中所有 `fetch()` 返回404或CORS错误。

**根因**：`file://` 协议下 `fetch('/路径')` 解析为 `file:///路径`（文件系统），非HTTP请求。且 `file://` → `http://` 被浏览器CORS拦截。

**解决方案**：大数据内嵌HTML；轻量数据用 `httpBase` 拼接；文件清单用Python扫描→JSON→页面fetch。


## Pitfall 2: 文件被误删 / symlink断链

**症状**：生成的HTML文件失踪，`ls` 显示 "broken symbolic link"。

**解决方案**：写入前 `~/.hermes/scripts/safe_write.sh <filepath>` 自动备份（保留5版）；Symlink仅用于命名兼容。


## Pitfall 3: MEMORY.md 超限

**症状**：MEMORY.md 超过2200字符，Agent写入受限。

**解决方案**：定期精简，只保留稳定业务事实；过程性知识放skills。完整精简方案和 Hermes 体检流程见 `references/hermes-health-check.md`。


## Pitfall 4: HTML生成中JS语法错误高频

**症状**：`node --check` 报错，页面空白。

**解决方案**：用 `write_file` 写完整HTML（不用patch拼接）；写完必须 `node --check`。


## Pitfall 5: 归档检测不工作

**症状**：访前准备中心文件状态始终"待生成"。

**当前方案**：Python扫描→`file_manifest.json`→页面fetch+模糊匹配。`custShort`算法：去括号→去后缀→迭代剥离。


## Pitfall 6: 长时间会话效率下降

**应对**：`max_turns: 60`, `temperature: 0.3`, `tool_use_enforcement: strict`，50轮+拆分到子Agent。


## Pitfall 7: 合同/声明文件审核

**触发**：文件放入 `~/Desktop/hermes输入/合同审核/`。

**流程**：提取全文→四级风险标注(🔴P0/🟡P1/🟢P2)→逐条修改建议→修订版docx。输出到 `~/Desktop/Hermes输出-工作类/合同/`。

**常见检查点**：价格锁死无调价出口、知识产权归属模糊、授权范围过度、保密期过短、争议管辖不利。


## Pitfall 16: list_related_workitem间歇超时（2026-07-09）

**修复**：超时设30s（非15s），加3次重试，建`{wid: customer}`缓存避免重复查询。客户名补全失败时不应阻塞整体管道——继续输出已拉取的订单，客户列留空待下次补全。


## Pitfall 20: 功能交付不完整导致用户挫败（2026-07-09）

**症状**：用户说"你真的把我要的功能更新了吗？排序没有、按月季度分组没有"。添加了 `dateKey` 但没有同步配置 `sumKeys` 和聚合列渲染逻辑。

**根因**：只完成了基础设施（参数传递），没完成端到端功能（用户可见的效果）。`HermesTable.render({dateKey:'date'})` 只加了日期筛选栏，聚合模式需要 `sumKeys` + `renderCols` 动态交换才能正确显示。

**铁律**：用户说"要做A+B+C"，验收标准是A+B+C全部能用，不是"框架支持A+B+C但没调通"。

**自查清单**（每次改完页面后）：
1. `node --check` JS语法 ✅
2. 打开浏览器点每个按钮 → 确认有响应
3. 切换周期（日/周/月/季/年）→ 确认数据正确聚合
4. 点列头排序 → 确认升/降/取消三态切换
5. 搜关键词 → 确认筛选结果正确
6. CSV导出 → 确认文件可打开
1. 写入前备份：`~/.hermes/scripts/safe_write.sh <filepath>`
2. 写入后验证：`ls -la` + HTTP HEAD
3. 不创建symlink链

### HTML卡片规范
1. 顶栏：48px白底，BIORI BIOTECH
2. 配色：`--pri:#1a73e8` 白蓝科技风
3. JS语法：`node --check` 必过
4. 编辑栏：右下角 ✏️编辑/💾保存/↩恢复 float bar
5. contentEditable + localStorage 持久化


## Pitfall 24: 功能交付前必须端到端验证（2026-07-09）

**教训**：用户说"你真的把我要的功能更新了吗？排序没有、按月季度分组没有"——只加了 `dateKey` 参数但没配 `sumKeys` 和聚合列渲染。

**自查清单**：每次改完页面 → 1) JS语法 2) 每个按钮有响应 3) 周期切换正确 4) 排序三态 5) 搜索筛选 6) CSV导出


## Pitfall 30: macOS screencapture 对 Chrome 窗口失败（2026-07-11）

**症状**：`screencapture -l <Chrome WindowID>` 返回 "could not create image from window"。

**根因**：macOS 26.5 的 screencapture 无法截取 Chrome 窗口。System Events 辅助功能也需手动授权。

**替代方案**：
1. Chrome AppleScript + `execute javascript` 获取 innerText（需先开启：Chrome → 查看 → 开发者 → 允许 Apple 事件中的 JavaScript）
2. `computer_use` 工具（需 `cua-driver` 安装，但国内网络下载 GitHub release 超时）
3. 用户手动截图/导出


## Pitfall 67: 端口被 Tailscale Serve 占用——8765 不通（2026-07-27）

**症状**：`python3 销售工作台服务.py 8765` 反复失败 `OSError: [Errno 48] Address already in use`。`lsof -i :8765` 有时不显示进程，但 `netstat -anv | grep 8765` 显示 `io.tailscale.ipn` 绑定。换成 8766 立即正常。

**根因**：**Tailscale Serve** 之前配置了 `tailscale serve --https=8765 / http://127.0.0.1:8000`，在 8765 端口做了代理。即使用 `kill` 杀进程，Tailscale 也会重新绑定。

**诊断**：
```bash
# 确认 Tailscale Serve 配置
tailscale serve status