智能体指南

本页从零开始、按部就班地介绍 MoAI-ADK 使用的 13 个智能体（自驱工作的 AI 助手）目录。它把"智能体是什么、为什么要用多个、如何协作"讲得足够清楚，可以讲给朋友听。

信息

一句话总结：智能体是各领域的专家。MoAI 作为团队负责人把任务交给合适的人选，并且 制定计划的智能体与审计该计划的智能体永远不是同一个。这个设计是为了让做的人不给自己的工作打分。

智能体是专注于特定领域的 AI 任务执行者。MoAI-ADK 不是让一个巨大的 AI 包揽一切，而是按工作性质拆成多个智能体，每个智能体拥有自己的上下文窗口（记忆空间）、系统指令和工具权限。

套用到公司组织上，这个结构就自然成形了。用户是决定产品的所有者，MoAI 编排器（统筹全部工作的中央指挥者）是团队负责人，Manager 智能体是各部门主管，Evaluator 智能体是质量监察员。这个类比会原样映射到结构上。

flowchart TD
    USER["用户（开发者）
决定做什么"] --> MOAI["MoAI 编排器
团队负责人 · 任务分配"]
    MOAI --> MGR["Manager 智能体 6 个
计划 · 实现 · 文档 · PR · 设计 · 协调"]
    MOAI --> EVAL["Evaluator 智能体 2 个
计划审计 · 质量审计"]
    MOAI --> ETC["其余 5 个
团队生成 · 高推论咨询 · E2E 测试 · 任务判定 · 代码探索"]

所有智能体都运行在 Claude Code 的 Sub-agent（子智能体）系统之上。每个子智能体都拥有独立的上下文窗口、定制的系统指令、精选的工具和单独的权限。MoAI-ADK 把 13 个专业角色架在这个地基之上。

一个智能体包办一切看似方便，但在实际工作中质量和成本会一起垮掉。

第一是 质量。如果制定计划的智能体还要判定计划执行得好不好，它很容易对自己的工作手下留情。人也是一样——自己校对自己写的文章，错误往往看不出来。所以 MoAI-ADK 从设计阶段就把负责计划与实现的 Manager 系和负责检查结果的 Evaluator 系分开。

第二是 成本。每个智能体都要重新填充上下文并运行推理，每一次委派都要花代币。“越多越好"并不成立。目录在 v3 周期里经历了 22 → 17 → 8 → 10 → 12 → 13 的精炼，如今保持在各角色互不重叠的最小规模。缩减智能体数量本身就是代币经济学（把代币用在刀刃上）的一部分。

四个术语，先掰开揉碎

本页反复用到的四个词，先在这里理清。

• 智能体（自驱工作的 AI 助手）—— 承担特定领域工作的 AI 执行者
• 线束（自动化的质量检验装置）—— 让智能体好好干活的规则与门禁
• 技能（可复用的工作说明书集合）—— 智能体调用使用的领域知识集合
• SPEC（需求规格说明书）—— 写明做什么、为什么做、怎么做的文档

MoAI 编排器是最高层的协调者：接收用户请求、分析意图（Analyze-First 路由）、把工作委派给合适的智能体，然后汇拢结果并向用户汇报。它的核心规则是复杂工作不亲自做，而是委派出去。

编排器调用哪个智能体，默认由 .moai/config/sections/delegation.yaml 中的委派映射（delegation map）决定。但这张映射只是默认值而非壁垒——编排器可以根据工作语境自行判断并改变它。

MoAI-ADK 使用 13 个智能体（12 个 MoAI 自定义 + 1 个 Anthropic 内置 Explore）。以下是按角色归类的完整清单。

产出实际交付物的主力部队。各自承担 SPEC 工作流的一个阶段。

由不是做的人的智能体来检查。这道分离是质量的主心骨。

在其只读判定子角色中，manager-todo 只返回判定，自己不执行任何事。它不写文件、不跑 shell 或 Git 命令、不碰队列、不向泳道派活，也不做提交、合并、批准或审计判定。检查返回的判定并真正改变状态的，是确定性执行器（只按既定规则行动的自动处理器）。它的工具清单只有 Read、Grep、Glob、Skill 四项；一旦请求超出封存范围，或判定所需的证据缺失、过期，它就返回 blocker 判定。

信息

manager-todo 在下面的智能体选择决策树中 有意没有位置。它不是编排器挑选后调用的智能体，其判定子角色是由 GTD 自动任务工作流直接调用的判定角色。它没出现在决策树里是设计使然，并非遗漏。

模型与推理深度

按智能体逐一分配模型和 effort 的旧方式已经退役。子代理原样沿用主会话的模型与推理深度——调用子代理时不传 model 也不传 effort，MoAI 智能体定义对两者都不作声明。更改会话的 effort（/effort、ultrathink），该会话中的所有智能体都会一并跟随。

这条原则是贯穿整个目录的设计哲学。manager-spec 写完计划，plan-auditor 在另一个上下文里检查；manager-develop 完成实现，sync-auditor 打出 4 维评分。因为实现的智能体和审计的智能体不是同一个，数错 grep 结果、引用过时 baseline、漏跑一步验证这类自我报告失效，会在检查那一侧浮出水面。

审计智能体以 fresh-judgment（怀疑立场）介入——每条主张都怀疑到证据出现为止，只承认可复现的结果，不承认"看起来过了”。评分用调和平均而非简单平均计算，一个维度塌了整体分数就跟着掉。这道设计撑起了 TRUST 5 质量框架的信任。

MoAI-ADK 不为后端、前端、安全等领域各设一个智能体，而是由 manager-develop 一个智能体在被调用时按工作语境注入领域知识与技能。

• 后端工作 → manager-develop + 后端上下文 + moai-domain-backend 技能
• 前端工作 → manager-develop + 前端上下文 + moai-domain-frontend 技能
• 其他领域 → 对应语言的技能 + 专业性指令

这样目录保持在 13 个的小规模，领域深度靠技能注入来补足。不靠增加智能体数量去抬高代币成本，而是换装技能（可复用的工作说明书集合）。

这是编排器接到请求后决定调用哪个智能体的流程。大多数时候 Analyze-First 路由仅凭自然语言意图就能分类，所以用户几乎不需要亲自指定智能体。

flowchart TD
    START["用户请求"] --> Q1{"只读
代码探索?"}
    Q1 -->|"是"| EXPLORE["Explore 智能体
掌握代码结构"]
    Q1 -->|"否"| Q2{"是 SPEC 工作流
任务吗?"}
    Q2 -->|"是"| Q3{"哪个阶段?"}
    Q3 -->|"计划"| SPEC["manager-spec"]
    Q3 -->|"实现"| DEV["manager-develop"]
    Q3 -->|"文档"| DOCS["manager-docs"]
    Q2 -->|"否"| Q4{"需要质量
验证?"}
    Q4 -->|"是"| EV["plan-auditor
或 sync-auditor"]
    Q4 -->|"否"| Q5{"需要高推论
咨询?"}
    Q5 -->|"是"| ADV["super-advisor
E1-E4"]
    Q5 -->|"否"| DIRECT["编排器直接处理
简单任务"]

展示智能体实际如何衔接的基本流程。关键在于阶段与阶段之间插着独立审计。用户用 /moai plan、/moai run、/moai sync 推进这条流程。

flowchart TD
    PLAN["1 计划 (plan)
manager-spec → 编写 SPEC"] --> A1{"2 独立审计
plan-auditor"}
    A1 -->|"打回"| PLAN
    A1 -->|"通过"| RUN["3 实现 (run)
manager-develop → DDD/TDD"]
    RUN --> A2{"4 质量审计
sync-auditor（4 维）"}
    A2 -->|"打回"| RUN
    A2 -->|"通过"| SYNC["5 文档 (sync)
manager-docs → CHANGELOG/README"]
    SYNC --> PR["6 PR 创建
manager-git"]

审计打回就退回上一个阶段。这种"往回走"把返工成本提前——质量问题在各阶段刚结束就被抓住，而不是拖到 PR 前。这就避免了同一个错误流进下一个阶段、变成昂贵的代价。

过去使用的智能体名字可能还留在旧文档或复制来的消息里。以下 12 个名字已经 退役（archived），调用它们会被拒绝生成。

manager-strategy、manager-quality、manager-brain、manager-project、claude-code-guide（仅限 MoAI 自定义文件）、researcher、expert-backend、expert-frontend、expert-security、expert-devops、expert-performance、expert-refactoring。

注意

注意：如果从旧会话复制来的恢复消息里带着这些名字，编排器会拒绝生成。这时要么把同样的工作交给附带领域指令的 Agent(general-purpose)，要么改用 13 个现役智能体之一。替代路径整理在 .claude/rules/moai/workflow/archived-agent-rejection.md。

有一点容易混淆。有一个 Claude Code 内置助手与退役的 MoAI 自定义文件 claude-code-guide 同名。调用内置助手不属于拒绝对象——拒绝只作用于 MoAI 自定义文件。

manager-lead 是专门协调 Tier L 规模实现的智能体。它自己不写代码：把工作拆成里程碑交给叶子工作者（leaf worker），并在每个里程碑边界折叠上下文、交叉运行验证。叶子工作者按需通过 Agent(general-purpose) 创建，运行在 worktree 隔离的分支上，写入面互不重叠。

编排器只在下面三个条件 全部（AND） 成立时才创建 manager-lead。缺任何一项，编排器就自己按顺序处理——给不达门槛的工作配协调智能体，只会增加收不回的成本。

三个条件是 AND 而非 OR。这些门槛刻意收得很窄，为的是不把只擦到一条边的工作卷进来——比如单个里程碑的 10 文件重构。

13 个智能体中只有 manager-lead 在 tools: 列表里带有 Agent 工具。其余一律省略 Agent，以此维持扁平层级。于是编排器 → manager-lead 是第 1 层，manager-lead → 叶子工作者是第 2 层，第 3 层永远不会生成。

flowchart TD
    ORCH["编排器"] -->|"第 1 层"| LEAD["manager-lead
tools 含 Agent（唯一例外）"]
    LEAD -->|"第 2 层"| W1["叶子工作者 A
tools 无 Agent"]
    LEAD -->|"第 2 层"| W2["叶子工作者 B
tools 无 Agent"]
    W1 -.->|"阻断"| X["第 3 层递归
不会生成"]
    W2 -.->|"阻断"| X
    GUARD["CI 守卫
manager_lead_depth_test.go"] -.->|"违规时构建失败"| X

注意

这道封印是 策略不变式，不是运行时不变式。Claude Code 运行时本身允许更深的递归——自 v2.1.219 起嵌套创建默认开启，默认深度上限为 3。所以真正把深度按住的只有两样：从智能体的 tools: 里省略 Agent 的惯例，以及在叶子工作者文件里发现 Agent 就让构建失败的 CI 守卫。

一个里程碑结束后，进入下一个之前要走三步。先把每条验收标准（AC）的验证输出收进机器本地暂存区，只把决定判定的那几行写进受版本跟踪的判定书 .moai/reports/<卡片id>/verdict.md，让它们在审计时打得开——卡片目录里受跟踪的名字只有这份判定书。接着在进度记录里追加一行指名这份判定书的一行式摘要行。最后用 /compact 压缩上下文。压缩后代币下降、并落到移交阈值以下（1M 系 50%，200K 系 90%），才进入下一个里程碑——没有下降就按折叠失败处理、重新规划。

当叶子工作者把某条 AC 标记为 PASS 时，会调入一个 没有做过那份工作 的第二个工作者，以只读方式（tools: 去掉写工具）重跑同样的验证命令。第二个工作者对结果没有利害关系，自我报告失效因此原样暴露。判定不一致时里程碑停下，向编排器返回 blocker 报告——向用户提问是编排器的职责。Tier S 跳过这一步：范围小到交叉验证的成本高于收益。

它与 sync 阶段的 sync-auditor 角色不同。sync-auditor 是实现完成后给出 4 维评分的最终怀疑式判读；peer 交叉验证是实现过程中挂在每条 AC 上的二元判定。两者互不替代。

12 个 MoAI 自定义智能体全部以 Markdown 文件形式放在 .claude/agents/moai/ 目录。Explore 是 Anthropic 内置的，磁盘上没有对应文件。

定义格式

每个文件由 YAML frontmatter 和正文组成。frontmatter 写 name、description、tools（CSV 字符串）；正文用文字写明角色 · 职责 · 使用的技能。model 和 effort 不写——子代理原样沿用会话的模型与推理深度，智能体定义无需声明。要亲手创建新智能体，用 builder-harness 智能体，或遵循智能体编写规则（.claude/rules/moai/development/agent-authoring.md）。

MoAI-ADK 智能体结构的地基是 Claude Code 官方的子智能体系统。

子智能体不能直接与用户对话——所需输入缺失时返回 blocker 报告，由编排器询问用户后带着答案重新派出。这道边界守住了"单一窗口"规则。

子智能体能用哪些工具，不是由一次设置决定，而是由两级过滤决定：spawn 时的静态允许列表是第 1 级，运行时延迟加载是第 2 级。

第 1 级 — spawn 时的静态过滤。 所有智能体定义都在 frontmatter 携带 tools: 允许列表（CSV 字符串，例：tools: Read, Write, Edit），列表之外的工具无法调用。只读角色靠缩减这份列表本身来构造权限——审计者与交叉验证工作者把写工具（Write、Edit）从列表里拿掉，堵死误改文件的路径。但这是收窄不是封死——Bash 若还留在列表里，仍能从那条路写入，所以是否只读要看有没有写入 能力，而不是看有没有那几个工具名。

第 2 级 — 运行时延迟加载。 部分工具在 spawn 时不会加载 schema。AskUserQuestion（向用户询问选项的工具）和 Task*（任务列表管理）系列就是如此。这类延迟（deferred）工具必须在需要的时刻用 ToolSearch 的 select: 查询显式加载 schema 后才能调用，是在通过第 1 级的工具之上再收窄一道的第二道闸门。

这两级合在一起造就两条规则。

前文"子智能体不能直接与用户对话"这条规则，正是由这两级过滤在运行时支撑的。

先前版本的 Agent Teams 静态编排层（workflow.team.* 配置、--team 强制标志）在 v3.0.0 退役，之后作为实验性表面重新允许（仅经显式 --team 请求选择，不会被自动选择）。退役时期强制 --team 会提示 MODE_TEAM_UNAVAILABLE 并回退到 sub-agent 模式；该哨兵字符串保留为已文档化的历史。

需要并行性的调研、审查用并行 sub-agent 扇出处理；顺序编码任务用 sub-agent 链处理。CG 已停用。迁移选项请先用 moai migrate cg 确认。

• 构建器智能体与 Harness v4 —— 动态智能体团队生成
• 技能指南 —— 智能体使用的技能体系
• 基于 SPEC 的开发 —— SPEC 工作流详解
• 配置矩阵 —— 模型 · effort 如今如何由会话继承决定

信息

提示：不需要亲自指定智能体。用自然语言向 MoAI 提出请求，Analyze-First 路由会分析意图并自动挑出最合适的人选。