🛠️ 团队失败模式手册
Team Failure Mode Handbook · 源自《深入理解AI Agent》读书建议5（魔形女）· 博士牵头 · 2026-08
FM-01
知识图谱"假同步"
高 · 已发生2次
症状主版 kg-data.json 有数据，但页面实际加载的 kg-data-compact.json 未同步——edges 指向超界索引（concepts 数量不足），页面渲染出"书没有知识点"。
真实案例《深入理解AI Agent》P0：compact版 b38 的 15 条 edges 全部指向 c135-c149（concepts 仅 115 个），北极星验证时页面确实显示 0 知识点。修复后 17:37 又被其他实例覆盖回超界状态。
根因知识图谱有两个数据文件（主版+compact版），更新时只改了一个；compact版是页面加载源，却常被忽略；且 edges 用数字索引引用 concepts，索引漂移时无校验。
规则更新kg-data.json后必须：① 同步compact版 ② 校验全部edges索引 < concepts长度 ③ curl验证页面数据 ④ grep验证书籍名称出现。任何一步不过=没完成。
FM-02
文件权限导致的假成功
高 · 已发生2次
症状patch 报 Permission denied，但汇报里写"部署验证全部通过"——文件实际未写入，入口缺失。
真实案例内容矩阵#002：第一次 patch index.html 因文件归 root 所有失败，但汇报"部署验证全部通过"。核实后改用"读取→修改→写/tmp→sudo cp"方式才真正写入。
根因网页目录多归 root 所有，patch 工具以 admin 身份写失败；汇报时只报"计划中的结果"没报"实际执行结果"。
规则部署后必须贴证据：① grep 确认写入 ② ls -la 确认权限 ③ curl 确认 HTTP 200 ④ 明确"实际执行了X"而非"计划做X"。文件存在≠完成，有入口可点才算。
FM-03
相似文件名混淆
中 · 已发生1次
症状两个文件名只差一个空格/下划线（`深入理解AI Agent_蒸馏.html` vs `深入理解AI_Agent_深度蒸馏.html`），导致北极星检查了旧版（73KB深色），误判新版不合格。
真实案例《深入理解AI Agent》P1误判：73.6KB深色旧版 vs 200.6KB暖色新版，文件名仅空格位置不同。北极星按错误文件名检查，得出"风格不合格/规模不够"结论，实际新版全达标。
根因交付时文件名不统一（有的带空格、有的带下划线、有的带"蒸馏"有的带"深度蒸馏"）；审核方按记忆中的文件名找文件。
规则交付文件命名统一：① 最终交付用唯一规范名（下划线，无空格）② 交付消息里写完整路径+文件大小+行数（便于核对是不是同一个文件）③ 审核前先 ls -la 确认文件大小与汇报一致。
FM-04
日期误判（写错日志日期）
中 · 已发生1次
症状凌晨 cron 触发写日志时，误以为写"今天"的日志，实际应写"昨天"——导致 8/2 日志缺失（大家都在验证 8/1，没人写 8/2）。
真实案例8/2 日志缺失：cron 1:00 触发时群里误以为是写 8/1（已存在），回复"上一轮已部署完成"——实际 8/2 文件不存在。修复：cron prompt 加"日期铁律"（今天减1天+举例）。
根因凌晨执行时对"今天/昨天"的语义判断失误；多人接力时都假设别人写过了。
规则写日志前先验证：① date 确认当前日期 ② ls 日志目录确认目标文件是否存在 ③ 存在则检查内容完整性（5角色覆盖），不存在才全新写。部署前必须自查日期。
FM-05
错误级联放大（审核依赖单点）
中 · 持续观察
症状一个环节的错误（如文件名记错）传导到下游，导致审核结论错误；且审核方只依赖单一信息来源（汇报文本），未独立验证。
真实案例《深入理解AI Agent》P0+P1：北极星依据"汇报里的数字"下结论（0知识点/181小节声明），未独立打开文件核实——实际主版知识图谱已有15条edges。审核结论与事实不符。
根因书中第10章"错误级联放大"的多Agent失败模式：提议者-审核者链路中，审核方基于提议方的表述而非原始事实做判断。
规则审核必须独立验证：① 打开实际文件/数据读一遍（不看汇报）② 关键结论用命令复现（grep/curl/python）③ 汇报与事实冲突时以事实为准并指出差异。对应书中"评估对象=模型+Harness"——审核对象=产出+汇报。
FM-06
并行写文件互相覆盖
高 · 已发生1次
症状多个agent同时写同一个线上文件，后写者覆盖先写者——内容回滚、版本倒退、已部署的正确数据被旧版/虚构数据替换。
真实案例day20/data.js：幻视嵌入D1 v3合并版后，并行agent回滚了data.js（把文案换回旧版+虚构"江畔民宿"）。幻视发现后做三方合并才恢复。此前kg-data-compact.json也被多次覆盖（FM-01同源）。
根因多个agent对同一文件有写权限；群聊消息异步，写文件动作并行发生，无锁无排他。
规则单文件单agent维护：① 每个线上文件指定唯一owner（day20归幻视）② 其他角色产出写到/tmp交接，不直接写/var/www ③ 变更一律群里@交接（天然串行）④ 临时防护用444只读锁定，要写时chmod 644，写完锁回。
FM-07
同角色多实例交付冲突
高 · 已发生多次
症状同一角色的多个session（多实例）对同一任务交付不同版本内容——部署者不知采用哪个，线上反复横跳、返工多轮。
真实案例短线自驾3条：两个魔形女session分别交付韶关乳源版/江门版；省外高铁游出现桂林/长沙/龙岩版与郴州/贺州/赣州版并存；云海5地点经历3轮方案切换（阳春/师爷山/金象山版→北岭山/天露山/飞霞山版）。
根因同一任务被多个session并行处理，无交付串行协议；部署者缺少"以最新时间戳为准"的统一规则。
规则单session交付协议：① 同一任务只允许一个session交付 ② 收到任务先查/tmp最新交付时间戳再动手 ③ 交付前群里声明"本任务由我交付"占位 ④ 部署者按最新时间戳采用，冲突公示让全员对齐 ⑤ 废弃版本明确标记（废弃初版后缀），避免抓错文件。
FM-08
需求未对齐就批量生产
高 · 已发生1次
症状图片/设计类任务未确认需求就批量产出，叶师父反馈"完全没有理解到我的需求，照片乱套了"；5张图仅1张合格。
真实案例2026-08-16 手串电商图任务——需求未确认就闷头开干（脑补5种风格超出需求）、没先出样图确认直接批量生产、群内技术刷屏14条迭代7轮、未验收就部署、北极星查出背景文件与文件名不符（P0）+并行写覆盖（FM-06）。
根因①需求未确认（接任务没回读确认）②无样图确认环节 ③群内讨论过度 ④未验收就部署。
规则先样图后批量：① 图片/设计类任务：先出1张样图→叶师父确认→再批量，确认前禁止批量 ② 群里只发关键产出+结论；技术讨论/迭代细节/质检过程走私聊或静默执行 ③ 产出先放/tmp，叶师父验收通过后博士才部署 ④ 接任务先回读确认需求 ⑤ 交付目录加锁防并行写覆盖（FM-06）。
📝 三句话总结
第一句：文件存在≠完成——入口可点、证据可查、命令可复现，三者齐备才算交付。
第二句：审核不是读汇报，是读事实——独立打开文件、用命令复现结论，才能拦住错误级联。
第三句：每次失败都提炼成"失败模式卡"（症状/案例/根因/规则），团队才能持续进化，不重复趟坑。