多智能体管道事后复盘

引言 #

多智能体编排是 Claude Code 中最强大——也是最安静危险——的模式。它成功时，你并行横扫代码库、获得独立审查、解决一个上下文窗口永远装不下的问题。它失败时，它安静地失败：管道报告成功，你交付，它本该捕获的 bug 已经在生产环境里。

这是我们在生产环境跑智能体管道时实际撞上的五个失败模式的事后复盘。每个都带你会看到的症状、底下的根因和修复。如果你读过 子智能体模式和 自定义智能体创作，现在在跑真实编排，这篇就是让你不掉进沟里的东西。

失败 1：信任陷阱 #

症状。 你的编排器报告"认证模块已重构，所有测试通过。“你交付。运行时立刻在"通过测试"从未覆盖的路径上崩了。

根因。 子智能体返回的是总结——它打算做什么的描述，不是它实际做了什么的验证记录。“所有测试通过"可能意味着它跑了，也可能意味着它相信会通过。编排器把散文当成了 ground truth。

修复。 对照产物验证，绝不对照总结。子智能体声称改动后，编排器读取实际 git diff、检查测试命令的退出码、或重新读文件。我们吃过这个亏——这也是为什么我们 用翻译子智能体写 4 语言文章时，跑 npm run build 作为 ground truth，而不是相信智能体的"YAML 有效：是”。总结是声明。构建是证据。

失败 2：上下文串扰 #

症状。 两个子智能体并行运行。一个的编辑消失了，或文件变成两者半合并的乱码。

根因。 两个智能体写同一个文件，或每个假设了另一个在底下改过的工作树状态。共享一个工作树的并行写者就是带额外步骤的竞态条件。

修复。 不相交作用域和 worktree 隔离。把智能体 A 限定到 /auth/、智能体 B 限定到 /payments/，零重叠。智能体做非平凡编辑时，给每个自己的 git worktree，让它们在独立 checkout 上操作，之后刻意合并。绝不让两个写者共享一棵树。

失败 3：失控扇出 #

症状。 本该花几千 token 的运行花了 10 倍。或管道永不完成——它不停派生智能体。

根因。 在没有收敛条件的循环里派生智能体，或扇出的 worker 远超工作所需。每个子智能体都是一整个上下文的 token；反射式扇出快速放大成本。

修复。 预算和停止条件。限制每阶段智能体数量。对发现循环（“找出所有 bug”），用"连续 K 轮无新发现后停止"代替开放式的"继续跑”。刻意扇出，用一个你有意选择的数字。在扩管道前，先看 token 数学实际怎么运作——看成本时这加倍重要。

失败 4：静默截断 #

症状。 管道报告"安全审计完成——未发现问题。“一周后，一个明显的注入 bug 出现在审计理应覆盖的代码里。

根因。 finder 智能体把结果封顶在前 N 条，或采样而非全量扫描——而且没人记录有任何东西被丢弃。编排器把 60% 覆盖呈现为 100%。

修复。 让截断发声。如果智能体限制了覆盖范围——top-N、采样、时间上限——它必须在报告里显式说明：“检查了 30 个端点中的 18 个；12 个未检查。“编排器浮现这个缺口而不是吞掉它。把部分结果呈现为完整，比诚实的"我没完成"更糟。

失败 5：孤儿 worktree #

症状。 陈旧 git worktree 堆积。更糟：后来的智能体把半成品 worktree 当成权威主树来读，在虚构之上构建。

根因。 为隔离创建的 worktree 从未被当作有作用域的资源。完成时无清理；哪棵树是权威的没有明确归属。

修复。 把每个 worktree 当作有生命周期的资源。智能体无改动时自动清理。有改动时，显式审查合并或丢弃——不要让它悬着。绝不让下游智能体把另一个智能体的 worktree 当 ground truth；权威状态是主树，就这么简单。（我们亲自在管道中途清理过孤儿 worktree——一条五秒的 git worktree remove 省下一小时"这个文件为什么不对”。）

原则 #

这些失败每一个共享一个根源：把智能体的声明当成验证过的现实。 未检查的总结、未隔离的作用域、未设界的循环、未记录的截断、无人拥有的 worktree。多智能体编排失败不是因为智能体笨——是因为编排器不验证就信任。在每条接缝构建验证和显式边界，管道就会变得和它强大一样可靠。

配置生产级 Claude Code #

可靠管道想要不会自己添加失败的基础设施：

1. 长管道和 CI 网关的稳定主机。 编排中途断开的 SSH 会话本身就是一种失败模式。HTStack — 香港 VPS，中国大陆低延迟访问，稳定 BGP。托管 dibi8.com 的同一家 IDC，我们就在那里跑这些管道。$5-12/月。

2. 并行扇出的云余量。 当你（刻意地、带预算地）扇出 worker 时，备用 CPU 让它们不互相争抢。DigitalOcean — 60 天 $200 免费额度，14+ 区域。

3. 技能包。 避免这五个失败主要靠提示词纪律——验证步骤、停止条件、有作用域的资源。我们把五个久经考验的技能打包成 Gumroad 上 $19 的捆绑包——见角落的浮动 CTA——包括已经内置验证接缝的编排器提示词。

相关阅读 #

• 子智能体模式 — 这些失败潜伏其中的五种工作流。
• 自定义智能体创作 — 用输出契约构建可靠 worker。
• 子智能体 vs MCP vs 技能 — 选对扩展点，避免过度构建。
• AI 编码智能体月度账单 — 失控扇出背后的 token 数学。

结论 #

当任务真正超过一个上下文窗口或需要独立验证时，多智能体编排值得——但要刻意使用，不要反射式。一个提示词良好的智能体每次都胜过有 bug 的五智能体管道。当你确实编排时，力量与灾难的区别是一个习惯：对照 ground truth 验证每个声明，给每个循环设界。 无法验证的复杂度比可以验证的简单更糟。