16 · 常见坑速查
全模块的坑总表。每条坑 = 症状 → 根源 → 对策，按「建设期 / 运行期 / 成本与安全」分组。 建议用法：出问题时来查表；每修一个新坑，回来补一行。
A. 建设期（设计与实现）
| # | 坑 | 症状 | 根源 | 对策 |
|---|
| A1 | 无终止条件就上线 | 任务跑几十轮不停，账单暴涨 | 循环只有「模型觉得完」一个出口 | 步数/预算双上限 + 重复失败熔断（第 04 章） |
| A2 | 工具错误静默吞掉 | agent 基于错误观察继续走，产出离谱 | try/except 后返回空串 | 错误原文回注，永不返回空（第 04 章） |
| A3 | 工具描述含糊或雷同 | 模型 20% 概率选错工具、填错参数 | 描述写「是什么」没写「何时用」 | 描述写使用时机/边界/代价，参数带格式示例（第 05 章） |
| A4 | 工具数量失控 | schema 吃掉大块窗口，选错率上升 | 有什么挂什么 | 控制在 10–20 个；分组挂载/工具检索（第 05 章） |
| A5 | 把业务校验押在模型上 | 金额算错、日期越界入库 | 模型不是计算器也不是校验器 | 校验焊死在工具代码里，错误信息指引模型改（第 05 章） |
| A6 | 负面指令写法 | 「不要啰嗦」→ 更啰嗦 | 模型对「别做 X」遵循弱 | 改正面指令：「回答 ≤3 句」（第 03 章） |
| A7 | 提示对单例过拟合 | 案例一改就崩 | 对着 2–3 个样本雕提示 | 用固定评测集验证提示（第 13 章） |
| A8 | RAG 默认化 | 明明能 SQL 查的数据上了向量库，召回还错 | 把 RAG 当架构默认 | 先过「该不该用」四连问；结构化数据走查询（第 09 章） |
| A9 | 嵌入模型静默升级 | 检索质量无声崩塌 | 新旧向量不在同一空间 | 模型版本与索引版本绑定，升级即重建（第 09 章） |
| A10 | 缓存前缀里放易变内容 | 每轮成本数倍于预期 | 时间戳/随机 ID 写进 system prompt 开头 | 不变在前、易变在后（第 07 章） |
| A11 | 无沙箱执行生成代码 | 一次 rm -rf / 凭证泄露 | 「临时跑一下」心态 | 沙箱是代码执行的准入门槛（第 12 章） |
| A12 | 子代理任务书缺背景 | worker 做错方向，回收废话 | 任务书没有目标/边界/返回格式三件套 | 任务书模板化 + 结论必须带证据（第 10/11 章） |
B. 运行期（行为与状态）
| # | 坑 | 症状 | 根源 | 对策 |
|---|
| B1 | 长会话「失忆」 | 第 30 轮忘了第 3 轮的约束 | 信息已不在窗口 / context rot | 翻上下文先确认在不在；关键约束压缩时白名单保护、必要时重注入（第 02/07 章） |
| B2 | 压缩后「变笨」 | compaction 之后质量跳水 | 摘要丢了关键约束 | 压缩白名单：用户诉求、红线、决策逐字保留；压完自检（第 07 章） |
| B3 | 上下文污染 | 一个错误结论带偏全程 | 错误工具结果留在历史里 | 显式注入更正消息；已消化的大观察修剪（第 07 章） |
| B4 | 记忆记错还坚持 | 每次会话都被旧错信息带偏 | 记忆当真相源，无校验 | 记忆=缓存：使用时核对当下；带来源与绝对日期（第 08 章） |
| B5 | 记忆库变成垃圾场 | 召回信噪比暴跌 | 什么都想记、只写不删 | 「跨会话有用+repo 没有+出错代价高」三关；定期归并清理（第 08 章） |
| B6 | 相对时间入库 | 「下个月到期」半年后还在 | 无锚点时间 | 一律转绝对日期（第 08 章） |
| B7 | 反复横跳 | 两条路线来回切，40 步无进展 | 无重估触发点 | 同方向连续失败 2–3 次强制显式换路/升级（第 10 章） |
| B8 | 过度规划 | 小任务也仪式化十步 | 规划当流程装饰 | <3 步可预知任务直走；规划服务于防漂移（第 10 章） |
| B9 | GUI 自动化盲操作 | 点了一串但一事无成 | 不验证就连续执行 | 每步观察 + 状态断言 + 失败即停（第 12 章） |
| B10 | 并行写同一文件 | 多智能体互相覆盖（或并行会话互吞提交） | 无编排、黑板无锁 | 按文件/目录物理切分；共享区单人落笔（第 11 章） |
| B11 | 递归委派 | 子代理再生子代理，层级爆炸 | 无深度上限 | 委派深度硬限 1 层（第 11 章） |
C. 成本与安全
| # | 坑 | 症状 | 根源 | 对策 |
|---|
| C1 | 成本随轮数线性爆炸 | 第 40 轮单轮成本是开场 6 倍 | 全量历史每轮重复计费 | 压缩 + 缓存前缀 + 工具结果修剪；预算上限兜底（第 02/07 章） |
| C2 | 凭证长期化 | root token 配给 agent | 图省事 | 短期令牌、按任务发放、用后焚（第 14 章） |
| C3 | fail-open 兜底 | 权限服务超时就放行 | 可用性惯性 | agent 安全一律 fail-closed：拿不准即拒绝并留痕（第 14 章） |
| C4 | 弹窗疲劳 | 用户无脑点确认 | 低危操作也弹 | 分级：低危免确认，高危 diff 审批（第 14 章） |
| C5 | 外部数据当指令信 | 网页/邮件诱导 agent 外发数据 | 提示注入 | 数据打标、egress 白名单、外发人工闸门（第 14 章） |
| C6 | 第三方 server 不审即装 | 工具描述里埋毒 | MCP 生态便利性幻觉 | 描述与源码当代码审（第 06 章） |
| C7 | vibes 上线 | 「感觉变好了」就发版 | 无评测集 | 评测集三层记分卡（结果/轨迹/成本）作合入门槛（第 13 章） |
| C8 | 只看成功率 | 95% 成功率但成本 ×4 | 单指标优化 | 三层记分卡并列看（第 13 章） |
| C9 | judge 无 rubric | 评估结果随机 | 让模型发挥想象 | 先写评分判据；定期人工抽检校准（第 13 章） |
| C10 | 事故不回流 | 同类坑反复踩 | 复盘不进评测集 | 每个线上事故 → 一条新评测用例（第 13 章） |
使用建议
- 按症状查表：先定位「建设期/运行期/成本与安全」，再看症状列。
- 每条坑都带回章节：速查表只给结论，机制与推演在对应章节——查到表后务必回读该章，别让速查表变成新的「背口诀」。
- 保持生长：本表的维护方式就是第 13 章的原则——每个新事故补一条，每条都要有「症状→根源→对策」三段，写不出根源说明还没排查清楚。