16 · 常见坑速查
全模块的坑总表：22 条，每条 = 症状 → 根源 → 对策，按设计期 / 运行期 / 质量与成本安全分组。 用法：出问题按症状查表，查到后回读对应章节的机制——速查表是索引，不是替代品。
A. 设计期（拆分与选型）
| # | 坑 | 症状 | 根源 | 对策 |
|---|---|---|---|---|
| A1 | 在可预知流程上上多 agent | 系统复杂但 nothing 增值 | 没过「该不该协同」决策树（01 章） | 写成 workflow；多 agent 留给上下文隔离刚需 |
| A2 | 按逻辑关注点横切同一批文件 | 两个 worker 反复改同一处 | 拆分没按物理边界（08 章） | 按文件/目录切；要横切就串行流水线 |
| A3 | 任务书不自包含 | worker 频繁回头问 / 自由发挥 | 引用了不存在的共享上下文（07 章） | 自包含测试：单独发一份看能否读懂 |
| A4 | 依赖不落字段 | 死锁、拿到空素材 | 「先 A 后 B」只在脑内（08 章） | DAG 显式化 + 等待必超时 |
| A5 | 粒度拍脑袋 | 通信占比过半 / 单点失败重做半天 | 按「想开几个 worker」倒推（08 章） | 粒度 = 一个可验收交付物 |
| A6 | 框架当架构 | 框架默认模型与业务拧着 | 先选框架后答四子问题（03/12 章） | 先答分配/通信/状态/质量四题，再挑框架 |
| A7 | 协议用错层 | 同系统子代理套 A2A / 跨系统裸调函数 | 协议价值在信任边界处没想清（12 章） | 边界内消息总线，跨边界才上协议 |
B. 运行期（协同行为）
| # | 坑 | 症状 | 根源 | 对策 |
|---|---|---|---|---|
| B1 | worker 直连互聊 | 协调成本爆炸、无人负责全局 | 破坏星形纪律（04 章） | worker 之间零直连，分歧回传编排者裁决 |
| B2 | 编排者亲自干活 | 全局视图被细节淹没 | 注意力预算错配（04 章） | 编排者只调度与合并；想亲自干就换角色 |
| B3 | 递归委派失控 | worker 树指数生长（11 章） | worker 有委派工具、无深度上限 | 深度硬上限 ≤2；不给 worker 委派工具 |
| B4 | 电话游戏 | 下游理解走样、「可能」变「确认」 | 无证据直通、置信度膨胀（07/11 章） | 证据直达合并者；置信度随链只降不升 |
| B5 | 活锁震荡 | 同一文件反复被互相修正 | 所有权不清 + 都被设定「见不一致就修」（09/11 章） | 所有权切分；修正须经编排者裁决 |
| B6 | 黑板量子态 | 「这任务到底谁在做？」 | 无状态机、认领不互斥、无租约（05/09 章） | 状态字段化 + 原子认领 + 租约回收 |
| B7 | 长任务目标漂移 | 产物越到后期越偏 | 任务书只在开头出现（11 章） | 目标白名单 + 周期重锚自报 |
C. 质量与成本安全
| # | 坑 | 症状 | 根源 | 对策 |
|---|---|---|---|---|
| C1 | 回声室 | 全员一致地错、验证异常顺利 | 验证者共享了生成者上下文（10/11 章） | 生成/验证物理隔离——唯一及格线 |
| C2 | 复核形同虚设 | 复核拦截率长期为 0 | 复核只查自洽不查事实（10 章） | 复核必须触达原始证据（diff/官方源/跑测试） |
| C3 | 多数暴政 | 高票通过错结论 | 投票用在系统性偏差上（06/10 章） | 换独立来源再验，不加票数 |
| C4 | 子代理报告直信 | 假阳性直接进定级 | 合并者跳过复核（10 章） | 以 diff/原始证据逐条复核后才定级 |
| C5 | 无预算护栏 | 账单穿透；「要不要再加个 worker」永远是要 | 只设全局或干脆没设（13/14 章） | 三级预算（全局/任务/worker）+ 熔断收缩 |
| C6 | 权限人人平等 | 一个 worker 出事全体遭殃 | 没做权限衰减（13 章） | 编排者>专项>只读>审计；凭证短时效按任务发 |
| C7 | 注入横移 | 一个 worker 被毒，全体被带偏 | 黑板无准入、报告未消毒（13 章） | 黑板分区准入 + 报告当数据处理 + 合并点闸门 |
| C8 | 只算生成 token | 预算永远穿到 2-3 倍 | 漏算通信/复核/重试/编排循环（14 章） | 四项成本全进账 + 倍增系数定预算 |
使用建议
- 按症状查表 → 回读机制：每条对策都指向章节，速查只给结论不给机制——跳过回读，
下次换个马甲的坑还会踩。
- 与失败模式图鉴配套：第 11 章是机制版（为什么），本表是速查版（怎么办）。
- 保持生长：站长自己的规矩是「每个新事故补一条」——本表的价值随事故复盘数增长，
不随字数增长。