OMC - 06 从“大模型管家”到“十九人专家团队”：oh-my-claudecode 的多 Agent 工程实践

Pre

OMC - 01 用 19 个 Agent 打造你的 Claude Code“工程团队”：oh-my-claudecode 深度解析与实战指南

OMC - 02 五分钟起步，走向多智能体协作：深入解析 oh-my-claudecode 快速开始与架构设计

OMC - 03 从 0 到高效：Oh My ClaudeCode 安装与实践全指南

OMC - 04 用好 Oh-My-ClaudeCode 的 30 个会话技能：从“帮我写点代码”到端到端自动交付

OMC - 05 从单人到多 Agent：Oh-my-claudecode 的插件架构解析

在大模型开发工具遍地开花的当下，许多项目仍停留在「一个强模型 + 一堆提示词」的阶段：所有需求都丢给同一个模型，靠长提示词和人肉经验去兜底，结果往往是行为不可控、输出质量不稳定、难以调试与演进。

oh-my-claudecode（下文简称 OMC）走了一条截然不同的路：不是堆一个超级提示词，而是搭建了由十九个专用 Agent 组成的多智能体系统，让大模型更像一个结构化的软件工程团队——有人探索代码库，有人写计划，有人做安全审查，有人专门简化代码，还有人负责 Git 提交流程。

本文将从架构、角色设计、模型分层策略、推荐工作流和可扩展性等几个维度，系统拆解这套「十九人专家团队」，并结合实际开发场景，讨论如何把这些理念迁移到你自己的多 Agent 系统中。

一、为什么需要「十九个专用 Agent」

1.1 单一大模型的瓶颈

在典型的「一个大模型干所有」的方案里，常见痛点包括：

• 上下文混乱：需求、计划、实现、审查全混在一次长对话里，模型很难保持角色边界。
• 结果不可审计：谁在什么前提下做了什么决策，几乎没有结构化记录。
• 难以稳定运维：任何一点指令调整都有可能连锁影响一大堆行为。
• 资源浪费：简单任务也用最贵的模型，复杂任务却因为成本考虑被迫降级。

本质问题在于：「角色」与「任务」没有被结构化表达，只能靠提示词堆砌来隐式表达期望行为，系统缺少真正的职责划分与协作机制。

1.2 OMC 的回答：四条泳道、十九个 Agent

OMC 将整个智能系统拆分成四条功能泳道，下辖十九个职责边界清晰的 Agent：

• 构建 / 分析泳道：从代码库探索、需求分析，到计划制定、架构评审、调试、实现与验证。
• 审查泳道：安全审查、安全边界评估、全面代码审查。
• 领域专家泳道：测试工程、设计、文档、数据分析、Git 流程、代码简化、外部文档调研等。
• 协调泳道：元级监督与计划审查。

每个 Agent 都通过四个维度来定义：

1. 角色：负责什么，不负责什么。
2. 模型层级：使用 Haiku、Sonnet 或 Opus 中的哪一档模型。
3. 工具权限：只读还是读写；能不能修改代码、运行命令等。
4. 在工作流中的位置：接收谁的产物，又把产物交给谁。

这套设计让大模型从一个“万能管家”，变成了一支“专业分工明确的工程团队”。

二、架构总览：四条泳道的 Agent 拓扑

2.1 顶层拓扑：从探索到质量关卡

从架构上看，十九个 Agent 并不是平铺在一个列表中，而是按软件开发生命周期拆分到不同泳道：

• 构建 / 分析泳道：从「我手上这堆代码是什么」到「改动真正落实并被验证」的全过程：
  • explore、analyst、planner、architect、debugger、executor、verifier、tracer。
• 审查泳道：
  • security-reviewer：安全视角的专业审查。
  • code-reviewer：逻辑、设计、性能、质量策略等全面审查。
• 领域专家泳道：
  • test-engineer、designer、writer、qa-tester、scientist、git-master、code-simplifier、document-specialist。
• 协调泳道：
  • critic：专门负责计划质量审查与缺失项识别。

在 UI 或日志层面，这种拓扑能被可视化为一张团队结构图：构建/分析在左，审查在上，领域专家在下，协调在右，整体构成一个围绕「改动」的闭环。

2.2 顾问型 Agent 全部只读：安全与可审计性的核心

一个极其关键但经常被忽视的设计：所有顾问型 Agent 均为只读。

包括：

• analyst、architect、critic、security-reviewer、code-reviewer、scientist、document-specialist、explore。

这些 Agent 在配置层面，Write与Edit工具被显式禁用，只允许：

• 读取代码文件、配置、日志。
• 阅读外部文档、规范。
• 生成分析报告、建议和审查意见。

但绝不直接修改代码或执行命令。

这有两个非常实用的好处：

1. 可审计性：任何改动都只能来自有限的几个「执行型」 Agent，修改行为更容易追踪。
2. 思考与执行解耦：分析、需求澄清、架构评估不会掺杂「顺手把代码也改了」这种隐式副作用。

在你自己的多 Agent 系统中，这一条可以说是最值得直接照搬的原则之一。

三、构建 / 分析泳道：从「看懂」到「改对」

这一泳道基本覆盖了「一个工程需求从进入系统，到被真正实现并验证」的主干路径。

3.1 explore：代码库向导

• 模型：Haiku（快 & 便宜）。
• 权限：只读。
• 角色：快速检索代码库、建立文件 / 符号 / 模块的映射关系，帮助后续 Agent 以低成本对齐上下文。

典型任务：

• 给出「项目中的配置入口在哪里」「鉴权逻辑在哪些模块里」之类的问题的结构化答复。
• 输出「代码地图」：重要子系统、关键文件路径、主要依赖关系等。

可以把它理解为：给后续所有人铺路的“向导型工程师”。

3.2 analyst：需求与验收标准的守门人

• 模型：Opus（深度推理）。
• 权限：只读。
• 角色：澄清需求、发现隐藏约束、明确验收标准。

它关心的是：

• 需求里有哪些不清楚、互相矛盾或尚未决定的地方？
• 从用户视角看，什么才算「做完」？
• 有无非功能性约束（性能、安全、兼容性）需要显式记录？

输出通常包括：

• 需求拆解。
• 验收标准列表。
• 建议补充的问题清单。

一个重要边界是：它不分析代码、不写计划、不审查计划。

3.3 planner：把需求变成可执行计划

• 模型：Opus。
• 权限：读写（可以写计划文件等结构化产物）。
• 角色：基于 analyst 的结论和 explore/architect 提供的上下文，输出结构化工作计划（RALPLAN-DR 结构）。

核心要求：

• 计划要分解成 3–6 个高质量步骤，而不是几十个微小碎片。
• 每一步都要清晰指向具体模块、文件或子系统。
• 标明依赖关系、潜在风险、需要进一步验证的假设。

但它不做的事情也很清晰：

• 不负责重新分析需求（依赖 analyst）。
• 不负责审查自己写的计划（交给 critic）。
• 不直接碰代码实现。

3.4 architect：系统级思考

• 模型：Opus。
• 权限：只读。
• 角色：围绕系统设计、边界划分、接口设计以及长期权衡进行分析，必要时参与调试诊断。

它更关注：

• 这次改动会不会破坏已有的架构边界？
• 有没有更符合系统整体演进方向的实现方式？
• 在性能、可扩展性、可维护性上有什么关键 trade-off？

表格中的职责划分明确指出：architect不负责收集需求、创建计划、审查计划。

3.5 debugger：从「出错了」到「找到根因」

• 模型：Sonnet（均衡，适合工程任务）。
• 权限：读写。
• 角色：根因分析、回归隔离、构建 / 编译错误解决。常见场景包括 CI 失败、单元测试挂掉、构建无法通过等。

它的输出往往是：

• 复现路径。
• 根因定位过程（包含尝试过的假设）。
• 修复建议或直接的修复补丁。

3.6 executor：真正动手写代码的人

• 模型：默认 Sonnet，遇到复杂多文件任务时可动态升级为 Opus。
• 权限：读写。
• 角色：根据已通过审查的计划，进行代码实现、重构和功能开发。

关键特性：

• 不必须、也不应该自己去理解需求细节，而是以 plan + 验收标准为主输入。
• 对于跨多个模块、涉及复杂协作的任务，编排器可以在运行时把它的模型升级到 Opus，以获得更强的推理能力。

3.7 verifier：用证据说话的「收尾人」

• 模型：Sonnet。
• 权限：读写。
• 角色：验证 executor 的实现是否满足 planner 定义的验收标准，同时评估测试是否充分。

它会：

• 对照 plan 中的每条验收标准，给出明确的「满足 / 不满足」判断。
• 指出缺失的测试用例或不足的测试覆盖。
• 对不满足标准的情况，给出详细反馈，并把任务送回 executor。

3.8 tracer：因果追踪与不确定性管理

• 模型：Sonnet。
• 权限：读写。
• 角色：围绕复杂问题构建基于证据的因果追踪，记录竞争性假设、证据链与不确定性来源。

典型使用场景包括：

• 性能问题排查。
• 间歇性故障 / 脏数据分析。
• 多系统交互导致的复杂 bug。

四、审查泳道：安全与质量的双保险

4.1 security-reviewer：安全左移的落地工具

• 模型：Opus。

• 权限：只读。

• 关注点包括：

  • 常见 OWASP 漏洞。
  • 信任边界设计。
  • 鉴权 / 授权逻辑。
  • 敏感数据处理与日志泄露风险。

它不会改代码，但会给出结构化的安全审查报告和整改建议，适合在合并前或重大改动后触发一次完整安全审查。

4.2 code-reviewer：超越「样式检查」的系统化代码评审

• 模型：Opus。

• 权限：只读。

• 评审范围涵盖：

  • 逻辑缺陷。
  • 设计原则（如 SOLID、分层原则）。
  • 反模式识别。
  • 性能与资源使用。
  • 整体质量策略是否被遵守。

可以把它看作：把经验丰富的 senior reviewer 封装成了一个 Agent，专门负责在人工 review 之前先给出一轮全面评估。

五、领域专家泳道：把「工程周边」做到极致

这一条泳道里的 Agent 并不直接改动业务逻辑，却对整体工程体验有极其关键的影响。

5.1 test-engineer：测试策略与覆盖率工程

• 模型：Sonnet。

• 权限：读写。

• 职责包括：

  • 设计单元 / 集成 / 端到端测试策略。
  • 分析当前测试覆盖的薄弱点。
  • 强化不稳定测试（flaky tests）。
  • 支持 TDD 流程，把测试写在前面。

历史上曾有tdd-guide这一单独 Agent，现已被并入test-engineer，同时保留别名保证向后兼容。

5.2 designer：UI / UX 专家

• 模型：Sonnet。

• 权限：读写。

• 负责：

  • 界面信息架构。
  • 交互流程。
  • 近生产级的视觉实现建议。

对于前端项目，可以由 designer 输出 wireframe 描述、样式约定、组件分解方案，再交给 executor 落地。

5.3 writer：技术写作者

• 模型：Haiku。

• 权限：读写。

• 专注：

  • README。
  • API 文档。
  • 内部技术文档。
  • 代码注释与变更说明。

使用成本低的模型是合理的，因为绝大部分输出遵循模板和固定结构，对推理深度要求不高。

5.4 qa-tester：交互式验证

• 模型：Sonnet。
• 权限：读写。
• 通过 tmux 会话等机制，执行 CLI 或服务的交互式验证。

它可以：

• 在真实环境中运行命令。
• 观察输出与行为。
• 记录验证过程和结果。

5.5 scientist：数据与实验的思考者

• 模型：Sonnet。

• 权限：只读。

• 用于：

  • 数据分析。
  • 实验设计与结果解读。
  • 统计推理与假设验证。

它不会直接改动代码或数据源，而是通过分析报告指导后续工程决策。

5.6 git-master：版本控制的守门人

• 模型：Sonnet。

• 权限：读写。

• 负责：

  • 设计原子提交。
  • 变基策略。
  • 提交历史规范与风格检测。

实用效果包括：

• 减少「巨型 commit」。
• 提升 git log 的可读性与可追踪性。
• 规范化分支管理。

5.7 code-simplifier：代码「减肥师」

• 模型：Opus。

• 权限：读写。

• 专注于：

  • 提升可读性与一致性。
  • 消除不必要复杂度。
  • 简化嵌套逻辑与多层抽象。

适合在功能稳定后，对关键模块进行一次「简化重构」，让后续团队维护成本下降。

5.8 document-specialist：外部知识入口

• 模型：Sonnet。

• 权限：只读。

• 主要作用：

  • 查阅外部文档（官方文档、SDK、API 说明、依赖库说明）。
  • 为其他 Agent 提供经过筛选的、与当前任务高度相关的引用。

历史上的dependency-expert、researcher等角色统一并入该 Agent，并保留别名映射。

六、协调泳道：critic 如何当好「计划审稿人」

6.1 critic：结构化“挑毛病”的专家

• 模型：Opus。
• 权限：只读。
• 聚焦两个词：质疑和缺失项。

它会针对 planner 输出的计划进行：

• 全局一致性检查。
• 多视角差距分析（需求视角、架构视角、风险视角）。
• 结构化地指出「哪些地方明显缺了一步」，并给出改进建议。

同样，它不负责收集需求、不写计划、不分析代码——只负责审查计划本身。

6.2 角色消歧矩阵：防止「自己写自己审」

OMC 用一个清晰的矩阵，刻意避免单一 Agent 对同一产物既做「作者」又做「审查者」：

这种硬性角色拆分在工程上非常关键：

• 防止一个 Agent「一条龙服务」导致缺乏监督。
• 更容易在日志中还原「是谁在什么前提下做了什么决定」。
• 便于对单一环节做 A/B 测试或升级（例如只升级 critic 的模型）。

七、推荐工作流：用关卡函数控制质量

7.1 主干流水线：从 explore 到 verifier

标准的委派工作流，大致遵循如下顺序：

1. explore：生成代码库地图与关键文件列表。
2. analyst：澄清需求与验收标准。
3. planner：生成结构化计划（写入.omc/plans/*.md）。
4. critic：审查计划，提出修改意见。
5. executor：根据通过审查的计划实现改动。
6. verifier：验证实现是否满足验收标准，检查测试充分性。

在这个过程中，有两个关键的「关卡函数」：

• critic 关卡：计划必须经 critic 审查通过才能交给 executor。未通过则退回 planner 重写。
• verifier 关卡：实现必须经 verifier 检查通过才能被标记为完成，不通过则退回 executor 继续修改。

代码库历史数据显示：计划在达到可执行状态前，平均会被拒绝约七次，这是刻意设计的迭代机制，而不是系统失败。

7.2 Ralph 模式：强制 PRD + 测试规范先行

当$ralph持久化模式开启时，系统引入了更严格的「ralplan-first」关卡：

• 在.omc/plans/目录中，同时存在：
  • PRD 文件（prd-*.md）。
  • 测试规范文件（test-spec-*.md）。
• 之前，不允许开始实现。

这等价于在团队流程层面强制执行：

1. 明确需求（PRD）。
2. 定义验收方式与测试策略（测试规范）。
3. 再写代码。

对于习惯「边想边写」的开发者，这种严格的流程起初可能会觉得有点「烦」，但在中大型项目中，极大地减少了返工与模糊需求引发的灾难性偏离。

八、模型层级策略：为什么不是「全部上 Opus 就完事了」

8.1 认知负荷，而不是重要性

在 OMC 的设计中，模型选择不是按「任务重要性」来定，而是按认知负荷和成本效益来分配：

• Haiku：极致速度和低成本，适合高度模板化、依赖模式匹配的任务：
  • explore：代码库搜索与映射。
  • writer：文档与说明性文字生成。
• Sonnet：大多数工程任务的默认选择：
  • 如executor、debugger、verifier、test-engineer、qa-tester、designer、git-master等。
• Opus：为需要深度推理和多步综合的 Agent 保留：
  • architect、analyst、planner、critic、code-reviewer、code-simplifier、security-reviewer。

这样的分配策略在工程实践中可以带来：

• 明显可控的成本曲线。
• 对「高价值思考」任务的资源倾斜。
• 对「流水线型生成」任务的极致吞吐。

8.2 动态升级：Executor 的按需提档

一个有代表性的例子是：

• executor默认使用 Sonnet。
• 当检测到任务涉及复杂的多文件大范围变更时，系统可以在运行时把executor升级到 Opus。

这样既保证了日常小改动效率，又在关键复杂任务上提供足够的思考能力。

九、配置与扩展：如何定制属于自己的「十九人团队」

9.1 AgentConfig：一个 Agent 的完整画像

每个 Agent 都通过一个AgentConfig对象定义，核心字段包括：

• name：名称。
• description：职责描述。
• prompt：从agents/*.md中加载的提示内容。
• tools/disallowedTools：显式允许 / 禁用的工具集合（如读写文件、执行命令）。
• model/defaultModel：当前模型与默认模型。
• level：信任层级（用于区分只读顾问和可写执行者）。

内部的AGENT_CONFIG_KEY_MAP则负责：

• 将人类可读的短横线命名（如security-reviewer）映射到配置文件中的 camelCase 键（如securityReviewer）。
• 这样，用户在插件配置中可以很方便地覆盖某个 Agent 的模型或开关某个 Agent，而不必改动源码。

9.2 agents/*.md：一个文件定义一个 Agent

每个 Agent 的 Prompt 存放在agents/目录下的 Markdown 文件中，文件头部使用 YAML frontmatter 声明元数据：

• model：推荐模型层级。
• level：信任级别（如只读顾问 / 可写执行者）。
• disallowedTools：明确禁止使用的工具列表。

运行时，loadAgentPrompt()会：

1. 解析 frontmatter。
2. 把元数据与正文中的提示内容分离。
3. 生成对应的AgentConfig。

这意味着：一个 Markdown 文件就完全定义了一个 Agent 的行为和能力，非常有利于团队协作与版本管理。

9.3 AgentOverrideConfig：按需微调，不动源码

对于更高级的定制需求，可以利用AgentOverrideConfig在插件配置层面做覆盖：

可以做到例如：

• 把code-reviewer换成更强或更便宜的模型。
• 临时禁用某个 Agent。
• 为特定项目追加专用提示（如团队内部编码规范）。
• 调整温度等采样参数。

所有这些都可以在不修改核心代码的情况下完成，便于项目在不同团队、不同环境下实现差异化配置。

十、向后兼容：别名映射与渐进演化

随着架构的演进，一些早期 Agent 被合并或重命名。为了不破坏已有工作流，OMC 保留了一套别名映射表：

部分示例：

• api-reviewer/performance-reviewer/quality-reviewer/quality-strategist→ 统一映射到code-reviewer。
• dependency-expert/researcher→ 统一映射到document-specialist。
• tdd-guide→test-engineer。
• deep-executor→executor。
• build-fixer→debugger。
• harsh-critic→critic。

其中tdd-guide在 TypeScript 源码中被明确标记为@deprecated，并由tddGuideAgentAlias指向testEngineerAgent。

这种设计允许：

• 在不破坏现有插件与工作流的前提下，持续整合、精简 Agent 角色。
• 通过统一的现代 Agent，集中维护行为与提示，降低长期运维成本。

十一、如何借鉴这套设计，搭建自己的多 Agent 系统

结合上文，可以总结出几条在实践中尤其值得采纳的设计原则：

1. 角色先于模型
   在讨论用什么模型之前，先把团队需要的角色梳理清楚：谁负责需求、谁负责计划、谁负责实现、谁负责审查、谁负责安全与测试。

2. 顾问只读，执行可写
   分清「思考型」与「执行型」 Agent，严格限制顾问型 Agent 的写权限，把所有改动入口集中到极少数执行者，以保证可审计性与安全性。

3. 禁止「自己写自己审」
   像 OMC 一样，用矩阵明确约束：任何单一 Agent 不得同时担任同一产物的作者与审查者。

4. 引入关卡函数
   在关键节点设置必须通过的关卡：计划必须先过 critic，代码必须过 verifier，需求与测试规范必须先写完才能改代码（类似 Ralph 模式）。

5. 按认知负荷分配模型层级
   不要把所有任务都丢给最高级模型：对模式化任务用廉价模型，对深度推理任务用高阶模型，对工程执行用平衡档，既节省成本又保证效果。

6. 用配置管理 Agent，而不是硬编码
   将 Agent 定义抽象成配置与 Markdown 文件，利用映射表与 override 机制支持按项目、按环境的差异化定制。

7. 为演进预留别名机制
   在迭代过程中，预留别名映射以保证向后兼容，让你可以大胆重构角色体系，而不必担心一次性拆毁所有旧工作流。

结语

十九个专用 Agent 不是炫技式地「多搞几个角色」，而是一次严肃的工程实践：把长期以来在人类团队中积累出来的软件工程经验（职责划分、角色互相制衡、流程关卡、版本管理与架构演进），系统性地迁移到多 Agent 大模型系统中。

在这套体系里，模型不再只是「一个更聪明的助手」，而是被组织成一支有边界、有流程、有质量关卡的工程团队。对于正在搭建 AI 助手、AI 编程工具或多 Agent 系统的开发者而言，这套设计提供了一个非常值得参考的范本：先想清楚你要什么样的团队，再去选择用什么样的模型。