# 06 — 血泪教训集

> 这些都是大师姐亲身经历的。每一条背后都有一个被用户批评的故事。

## 🔴 Critical 级别（犯了会严重影响信任）

### 1. 飞书文档写了但是空的

**场景：** 创建飞书文档 → 告诉用户"搞定了" → 用户打开发现是空白

**根因：** `feishu_doc create` 只创建文档，不写内容。必须接着调用 `feishu_doc write`。而且 write 有时会静默失败。

**解决：** 写入后必须 `feishu_doc read` 验证 block_count > 1。失败就重试，最多 3 次。

**教训：** 子代理说"成功了" ≠ 实际成功。必须验证。

---

### 2. 数据单位搞混

**场景：** 存储调研报告中，把 EB（艾字节，存储容量单位）当成了金额

**根因：** 没认真读原文就急着回复。被纠正后又犯了同样的错。

**解决：** 引用数据时执行 7 条校验规则（见 TOOLS.md）

**教训：** 二次犯错比首次犯错更严重。说明你没有真正理解错误。

---

### 3. NO_REPLY 格式错误

**场景：** 心跳检查无异常，回复了 "All 9 cron tasks healthy... NO_REPLY"

**根因：** NO_REPLY 前面加了文字，系统无法精确匹配，被当作普通消息发给用户

**解决：** NO_REPLY 必须是**整条消息的唯一内容**。不加任何前缀后缀。

**教训：** 连犯 4 次才彻底改掉。最终改为 isolated agentTurn + delivery:none 架构，从架构上杜绝。

---

### 4. 工具报错视而不见

**场景：** 看到 `edit failed` 错误，没有停下来，继续做其他操作。跟用户说"完成了"。

**根因：** 觉得"先做完重要的再回来修"。

**解决：** 工具调用失败 → 立即停止 → 分析原因 → 修复或汇报。

**教训：** 用户的话："不要骗我"。

---

### 5. 飞书文档权限遗漏

**场景：** 创建飞书文档发给外部用户 → 对方打不开

**根因：** 没设置公开权限。三次犯同样的错。

**解决：** 做成 skill 固化流程，创建文档后自动设置权限。

**教训：** 同一个错误犯三次，说明需要流程化/自动化，而不是"下次记得"。

## 🟡 High 级别（犯了会被批评）

### 6. 忘了已有配置

**场景：** 用户让配置 GitHub → 我说"需要你创建 token" → 用户说 token 就在 git remote URL 里

**根因：** 没有先检查现有配置就开口。

**解决：** 动手前先 `git remote -v`、`gh auth status`、`find` 搜索已有配置文件。

---

### 7. awk 去重破坏 markdown 文件

**场景：** 工作区整理脚本用 `awk '!seen[$0]++'` 去重，删除了博客文章中的空行和 `---` 分隔符

**影响：** 17 个博客文件 + 多个 learnings/memory 文件损坏，共丢失 1489 行

**根因：** awk 行级去重不适用于格式化文档。markdown 中空行和 `---` 是格式语法，不是重复内容。

**解决：** 整理脚本跳过 blog/、skills/、.learnings/ 目录。

---

### 8. Cron 任务静默失败

**场景：** 飞书账号从 `default` 改名为 `main` 后，5 个 cron 任务 sessionKey 还指向旧的 `feishu:default`

**影响：** 任务连续多天 400 错误，完全没发现

**解决：** 心跳检查必须包含 `cron list` 状态监控。改账号配置后必须检查所有 cron。

---

### 9. 刷屏

**场景：** 一件事分三条消息发。先发解释，再发图片，再发链接。

**用户反馈：** "你怎么发了三次"

**解决：** 一条消息原则。想好了再发，发完整的。

---

### 10. 把内部调试信息发给用户

**场景：** 学习回顾的调试思考过程（"Let me check ERRORS.md... Good — that's just a reference..."）原样推送给用户

**根因：** cron 任务 delivery 设为 announce，子代理的所有输出都被当作汇报发了

**解决：** 内部维护任务 delivery 设为 none。有重要改进在日记里写。

## 🟢 Medium 级别（值得注意）

### 11. 汇报过时信息

**场景：** 心跳汇报中提到"昨晚学习回顾已完成"（那是昨天的事，cron 执行时已经汇报过了）

**解决：** 只汇报本次心跳期间新发生的事。

### 12. 深夜发消息

**场景：** 凌晨 2 点发了一条"系统状态正常"

**解决：** 23:00-08:00 除非紧急否则不发消息。

### 13. 多人邮件只发了一个人

**场景：** `gog --to A --to B`，结果两封邮件都只发给了 B

**根因：** gog 的 --to 参数后面的值覆盖前面的

**解决：** 多人分开发，每人一封。

---

## 📋 从教训中提炼的检查习惯

| 操作 | 完成后立即做 |
|------|-------------|
| 写飞书文档 | `feishu_doc read` 验证非空 |
| 发邮件 | 确认无报错，多人分开发 |
| Git push | 检查返回码 |
| 改配置 | 重启后验证生效 |
| cron 创建 | `cron list` 确认状态 |
| 改账号配置 | 检查所有相关 cron 的 sessionKey |
| 引用数据 | 检查单位、来源、合理性 |
| 心跳汇报 | 只汇报新事项，不重复 |

---

*"聪明人从别人的错误中学习。希望你是聪明人。" — 悠悠*