从 Claude Code 到 OpenCode：我的多 Agent 协作开发实践

我之前用 Claude Code 写项目时，模式很简单：一个对话窗口，告诉它要做什么，它去找文件、读代码、写修改。能用，但随着项目复杂度增长，开始暴露一些问题。

后来发现了 OpenCode，一个开源的 AI 编程平台。它的 OhMyOpenCode 框架内置了 Sisyphus 编排器——一个专门做任务分解和多 agent 调度的「大脑」。和 Claude Code 的单 agent 模式不同，Sisyphus 会把一个请求拆成多个子任务，派发给不同的 agent 并行执行，然后再汇总结果。

这篇文章记录这次工具的迁移，更核心的是记录背后的思维转变：把 AI 编程助手从「一个万能的对话窗口」拆分成「多个专注不同任务的 agent」。

单 Agent 模式的三个问题

单 agent 能跑通大多数任务，但有三个痛点会随着项目变大而加剧：

第一，搜索不彻底。 一个 agent 同时负责「理解需求」「搜索代码」「写修改」「验证结果」，注意力被分散。当你问它「项目里有哪些地方用了 KaTeX」，它可能搜了一个目录就停下来，告诉你「只有 BaseHead.astro 里有一处」——实际上 global.css 里还有十几处样式覆盖。

第二，幻觉更频繁。 这是最致命的。单 agent 在写代码时，对项目中不存在的文件、不存在的 API、不存在的配置值，会「合理推测」。比如写 Tailwind 文章时，它编造了一套看起来完全合理的颜色值（#4fc3f7），但和项目实际使用的（#00bfff）完全不同。外行读者看不出来，但这是对读者赤裸裸的欺骗。

第三，「自己写代码」的诱惑。 单 agent 模式下，AI 倾向于自己动手——读文件、写代码、改配置一气呵成。问题是：它写的代码往往不如一个专注做这件事的 agent 写得好。同样的任务，一个只负责「改这个文件的这 3 行」的 agent，比一个同时操心 5 件事的 agent 更不易出错。

分工设计：Sisyphus 的 Agent 体系

解决思路很简单：不要有一个全能的 agent，要有一组各司其职的 agent。每个 agent 只做一件事，但做到极致。

OhMyOpenCode 的 Sisyphus 编排器内置了一套分工体系。核心角色有五个：

代码库搜索 → explore

这是使用频率最高的 agent。它的唯一职责是「在项目里找东西」：某个函数定义在哪、哪些文件引用了这个变量、某类错误处理在哪些地方出现过。

和单 agent 自己 grep 的区别在于，explore 不会被其他任务分心。你告诉它「找到所有 KaTeX 相关的代码，包括 CSS 样式、组件引用、配置文件」，它会地毯式搜索，而不是找到第一个就停。

实操中的用法：永远在后台并行启动。需要搜索 3 个不同的模式？同时启动 3 个 explore agent，而不是一个一个串行。

外部参考 → librarian

explore 搜项目内部，librarian 搜外部——官方文档、GitHub 上类似项目的用法、Stack Overflow 上的已知问题。

触发条件很明确：当你提到一个不熟悉的库或框架时，同时启动 librarian 去查。它不是「需要的时候才用」，而是「只要提到就应该用」——因为 AI 对热门库的「知识」可能是过时的。

难题求解 → oracle

explore 和 librarian 负责搜索，oracle 负责思考。它是只读的推理 agent——不能改文件，只能分析问题和给出建议。

什么时候用：两种场景。一是架构决策，比如「这两种路由方案各有什么 tradeoff」；二是卡 bug ——改了 2 次还没修好，不要再猜了，丢给 oracle 重新审视根本原因。

oracle 贵（推理 token 消耗大），但比你自己盲改一小时便宜得多。

前置分析 → metis + momus

这两个 agent 在「写代码之前」工作。metis 做的事：读需求 → 找出隐藏的歧义 → 输出明确的任务描述。momus 做的事：拿 metis 的计划 → 找漏洞 → 「这个验收标准不可验证」「那个步骤缺前置条件」。

这两个 agent 的使用频率比 explore/librarian 低，但在复杂任务上能避免「写到一半发现理解错了需求」的浪费。

除了这五个只读/分析型 agent，Sisyphus 还有一个 Category + Skills 系统来调度代码产出的 agent。不同领域的任务分配给不同的 category：前端 UI 走 visual-engineering、重构走 artistry、重逻辑任务走 ultrabrain、复杂端到端任务走 deep。每个 category 运行在领域优化的模型上，可以加载对应的 skill（如 frontend-ui-ux、git-master）。「写代码」这件事本身也被精细分拆了。

编码到规则里：AGENTS.md

分工需要纪律才能生效。我把这些规则写进了 AGENTS.md，而不是靠口头约定。核心规则摘几条：

「默认偏见：委托。」 AI 的失败模式是觉得自己动手更快。规则明确：任何一个可委托的子任务，都必须委托。自己动手只在「确定自己做得更好」时例外——而这种情形极少。

「永远并行。」 explore 和 librarian 的搜索任务没有依赖关系，那就同时启动。规则禁止「启动一个 agent，等它完成，再启动下一个」。

「禁止重复搜索。」 一旦把搜索任务委托给了 explore agent，自己就不能再 grep 同样的东西。这防止了「我等的 agent 还没返回，要不我先搜一下」——结果两边都在搜，浪费 token。

「结果必须验证。」 agent 返回结果后，必须检查：它有没有搜全？有没有遵循约束条件？有没有编造文件路径？agent 不是神，它也会偷懒和出错。

实际体感：变化在哪

切换到这个模式后，有几个明显的变化：

代码质量更稳定。 因为「写代码」是一个专注的 agent 在写，而不是一个同时操心搜索、理解、验证的 agent 在写。改动的文件范围更小，修改的逻辑更精准。

幻觉大幅减少。 这不是 agent 变得更聪明了，而是分工消灭了幻觉的来源——当 exploit agent 返回「没有找到这个文件」时，你不可能去编辑一个不存在的文件。信息输入是准确的，输出才可能准确。

上下文更清晰。 单 agent 模式下，长对话后 agent 会「忘记」之前的约束。多 agent 模式中，每个 agent 收到的 prompt 都重新明确：目标是什么、边界在哪、不许做什么。每一次委托都是一次「重置」。

但 token 消耗更大。 多 agent 模式下，explore 搜代码、librarian 查文档、oracle 做分析、coding agent 写代码——每个 agent 都会消耗 context。单 agent 模式可能 50K token 完成的事，多 agent 可能是 150K。这是分工的代价。

迁移的意外：旧规则与旧架构的冲突

更大的 token 浪费来自一个意料之外的地方：旧 AGENTS.md 的工作流规则在新架构下产生了冲突。

在 Claude Code 单 agent 时代，我在 AGENTS.md 里定了一套三步流程：规划 → 确认 → 执行。而且规定，必须收到我的确认词（「OJBK」）之后才能开始写代码。这个机制在单 agent 模式下很合理：一个 agent 负责全部，它先出方案、等我确认、再动手，避免了自作主张。

但迁移到 OhMyOpenCode 后，这套规则出问题了。

Sisyphus 编排器本身就会做规划——它接到一个请求后，先分析需求、拆分成子任务、分配给对应的 agent。也就是说，规划这件事已经从单个 agent 的职责变成了编排器的职责。但子 agent 收到的 AGENTS.md 里仍然有同样的三步规则。结果是：

1. 我问：给博客加一个暗色模式切换按钮
2. Sisyphus 拆出子任务，发给 visual-engineering agent
3. 子 agent 读完 AGENTS.md，按照规则开始出方案
4. 方案写完，等着我回复 「OJBK」 才肯动手
5. 而我根本没看到它的方案——消息在子 agent 的独立 session 里，我只能看到最终输出

于是出现了一个死锁：子 agent 等我确认，我等子 agent 输出，两边干耗着。等超时之后，子 agent 终于被系统拉回来，但已经浪费了大量 token 在「等待确认」的循环上。

改法也很直接：把 AGENTS.md 里的确认机制从子 agent 的规则中移除，只保留给编排器。Sisyphus 在拆解完任务后出示计划让我确认（这时候我确实需要看一眼全局），确认后分发的任务直接进入执行模式——子 agent 拿到的不再是「先规划再确认再执行」，而是「直接执行，目标明确，边界清晰」。

这一改动之后，每次请求的 token 消耗明显下降，响应时间也更短。教训是：工作流规则要区分「给编排器的」和「给执行者的」。编排器需要确认，执行者不需要——执行者收到的应该是已经确认过的、原子化的任务。

总结

从 Claude Code 到 OpenCode 的迁移，本质上是认识到了一个问题：AI 辅助开发的瓶颈不是 AI 能力，而是工作流程设计。

如果只记一条规则，我会选这条：永远不让一个 agent 同时负责「信息收集」和「代码产出」。让 agent 只做信息收集（explore / librarian）时，它不会编造数据；让 agent 只做代码产出时，它拿到的信息是经过验证的，不会基于幻觉写代码。

目前这个项目的 AGENTS.md 已经有 1400 多行——每一条规则背后，都对应着一个曾经踩过的坑。而 Sisyphus 强制执行这些规则：不并行就报错、不委托就拒绝、不验证就重来。人类会偷懒，但编排器不会。