oma-orchestrator

Orchestrator - 自动化多 Agent 协调器

调度

目标

自动协调多 Agent 执行，包括任务分解、原生／备用派发、记忆协调、进度监控、验证、QA 交叉审查、重试和结果收集。

意图特征

• 用户要求进行协调、并行运行、自动化多 Agent 执行，或端到端协调全栈工作。
• 任务需要多个专业 Agent，以及持续的审查与修复循环。

适用场景

• 复杂功能需要多个专业 Agent 并行协作
• 用户希望自动执行，而不手动启动 Agent
• 涉及后端、前端、移动端和 QA 的全栈实现
• 用户提出“自动运行”“并行运行”或类似的自动化请求

不适用场景

• 简单的单领域任务 → 直接使用对应的 Agent
• 用户希望逐步手动控制 → 使用 oma-coordination
• 快速修复 Bug 或小幅修改

预期输入

• 复杂功能或工作流请求
• 项目配置、模型／供应商路由、Agent 类型、任务约束和工作区／会话需求
• 验收标准和验证预期

预期输出

• Orchestrator 会话状态、任务看板、进度文件、结果文件和最终摘要
• 专业 Agent 的输出，以及机械检查、自动验证和 QA 交叉审查结果
• 审查循环失败时的审查历史和重试／修复状态

依赖项

• .agents/oma-config.yaml、.codex/agents/*.toml、.gemini/agents/*.md，或备用 oma agent:spawn
• 记忆提供方配置、子 Agent 提示词模板、脚本、任务模板、验证脚本和会话指标

控制流功能

• 根据供应商／原生派发可用性、优先级层级、Agent 完成／失败状态、验证状态、QA 结论、重试限制和待澄清事项进行分支处理
• 启动进程／Agent，并读取／写入记忆／结果文件
• 在持续工作流完成之前阻止终止

结构流程

入口

1. 解析 Agent 供应商路由和运行时派发路径。
2. 将请求分解为按优先级分层的任务。
3. 对每项任务，将其与每个已安装 .agents/skills/oma-*/SKILL.md 的 Intent signature 区块进行匹配，归类到一个或多个 domain_tags。无法可靠匹配到任何领域的任务，将继承其父级功能的标签并集。
4. 为每项任务构建 exposed_skill_set，其中包含名称属于 domain_tags 的技能。分类后如果 |exposed_skill_set| < 2，则回退到完整的已安装技能集合（平铺暴露），并在任务看板中记录 exposure_fallback: true。
5. 创建会话记忆和任务看板，并为每项任务记录 exposed_skill_set 和 exposure_fallback。

阶段

1. PREPARE：规划、设置会话 ID，并初始化记忆文件。
2. ACT：在并行度限制内按优先级层级启动 Agent。
3. VERIFY：运行自检、oma verify 和 QA 交叉审查循环。
4. RECOVER：在限制允许时，根据审查历史重试失败的 Agent。
5. FINALIZE：收集结果文件、汇总摘要并清理进度文件。

转换

• 如果当前运行时／供应商支持原生派发，则使用原生派发。
• 如果供应商不同或原生路径不可用，则使用备用启动方式。
• 如果验证或 QA 失败，则将反馈交给实现 Agent。
• 如果超出审查循环限制，则报告审查历史并发出质量警告。
• 如果任务的 exposed_skill_set 未包含某项技能，而恢复失败的结果表明该技能是必需的，则重新分类任务，并使用扩展后的技能集合重新派发，而不是基于原来的狭窄集合重试。

失败与恢复

• 在配置的限制内重试失败的 Agent。
• 审查循环耗尽时，附上审查历史重新启动 Agent。
• 待澄清事项超过阈值时暂停或请求重新说明。

退出

• 成功：所有任务均已完成，验证和审查均已通过，并已汇总结果。
• 部分成功：明确说明失败的 Agent、审查循环耗尽或待澄清事项。

逻辑操作

操作

操作	SSL 原语	证据
读取配置和任务上下文	READ	oma 配置、路由、请求
将任务归类为领域标签	INFER	任务文本与各技能的 Intent signature 对比
计算可用技能集	SELECT	领域标签与已安装技能的交集
选择分派路径	SELECT	原生路径与回退路径
写入会话状态	WRITE	任务板和记忆文件
启动 Agent	CALL_TOOL	原生 CLI 或 oma agent:spawn
轮询进度	READ	进度／结果文件
运行验证	CALL_TOOL	oma verify、测试、QA
更新重试状态	UPDATE_STATE	循环计数器和 CD 指标
报告最终结果	NOTIFY	汇总结果

工具和仪器

• 原生 CLI 子 Agent 分派、回退启动脚本、记忆工具、验证脚本、QA Agent
• 会话指标、提示词模板、任务模板

规范命令路径

oma agent:spawn <agent-type> "<task>" <session-id> -w <workspace>
oma verify <agent-type> --workspace <workspace> --json

当原生运行时分派可用时，优先使用此技能中列出的特定运行时原生路径，然后再回退到 oma agent:spawn。

资源范围

范围	资源目标
LOCAL_FS	会话、任务板、进度、结果、配置文件
PROCESS	Agent CLI 进程和验证脚本
MEMORY	会话状态和待澄清事项
CODEBASE	已启动 Agent 所属的工作区

前置条件

• 任务可拆分为由专用 Agent 处理的工作。
• 存在运行时／供应商分派路径或回退路径。

效果和副作用

• 启动 Agent，并写入会话／进度／结果文件。
• 专用 Agent 可能会更改代码。
• 可能触发迭代审查和重试。

防护措施

1. 启动任何 Agent 前，先根据项目配置协调各 Agent 的分派。
2. 如果 target_vendor === current_runtime_vendor 且运行时存在已验证的原生路径，则使用原生分派。
3. 否则，回退到 oma agent:spawn。
4. 切勿超出配置的并行数或重试次数限制。
5. 在整个运行过程中，确保会话状态、任务板状态、进度文件和结果文件保持一致。
6. 领域筛选必须保持灵活：优先使用范围更窄的 exposed_skill_set；但如果分类置信度较低，则回退到扁平化技能集，以免任务缺少必需的专用 Agent。

当前原生执行器路径：

• Claude Code：claude --agent <agent>
• Codex CLI：使用 .codex/agents/*.toml 的 codex exec "@agent ..."
• Gemini CLI：使用 .gemini/agents/*.md 的 gemini -p "@agent ..."

供应商特定的执行协议会自动注入回退 CLI 运行中。

配置

设置	默认值	说明
MAX_PARALLEL	3	并发子 Agent 的最大数量
MAX_RETRIES	2	每个失败任务的重试次数
POLL_INTERVAL	30s	状态检查间隔
MAX_TURNS (impl)	20	backend／frontend／mobile 的轮次限制
MAX_TURNS (review)	15	qa／debug 的轮次限制
MAX_TURNS (plan)	10	pm 的轮次限制

记忆配置

记忆提供方和工具名称可通过 mcp.json 配置：

{
  "memoryConfig": {
    "provider": "serena",
    "basePath": ".serena/memories",
    "tools": {
      "read": "read_memory",
      "write": "write_memory",
      "edit": "edit_memory"
    }
  }
}

工作流阶段

阶段 1 - 规划：分析请求 -> 分解任务 -> 生成会话 ID 阶段 1.5 - 领域门控：对每项任务，在已安装技能中交集匹配的 Intent signature，以推导出 exposed_skill_set。当交集过小、不足以发挥作用而改用扁平库时，记录 exposure_fallback: true。 阶段 2 - 设置：使用记忆写入工具创建 orchestrator-session.md + task-board.md（为每项任务包含 exposed_skill_set） 阶段 3 - 执行：按优先级层级启动 Agent（不得超过 MAX_PARALLEL）；仅将 exposed_skill_set 注入每个子 Agent 的可用专家列表 阶段 4 - 监控：每隔 POLL_INTERVAL 轮询；处理已完成、失败或崩溃的 Agent 阶段 4.5 - 验证：对每个已完成的 Agent 运行 oma verify {agent-type} 阶段 5 - 收集：读取所有 result-{agent}-{sessionId}.md，汇总结果，并清理进度文件

请参阅 resources/subagent-prompt-template.md 了解提示词构建方法。 请参阅 resources/memory-schema.md 了解记忆文件格式。

记忆文件所有权

文件	所有者	其他人员
orchestrator-session.md	编排器	只读
task-board.md	编排器	只读
progress-{agent}[-{sessionId}].md	对应 Agent	编排器读取
result-{agent}[-{sessionId}].md	对应 Agent	编排器读取

Agent 间审查循环（阶段 4.5）

每个 Agent 完成后，都应进入迭代审查循环，而非只进行一次验证。

循环流程

Agent completes work
    ↓
[1] Mechanical Self-Check: lint, type-check, tests, diff scope
    ↓
[2] Verify: Run `oma verify {agent-type} --workspace {workspace}`
    ↓ FAIL → Agent receives feedback, fixes, back to [1]
    ↓ PASS
[3] Cross-Review: QA agent reviews the changes
    ↓ FAIL → Agent receives review feedback, fixes, back to [1]
    ↓ PASS
Accept result

步骤详情

[1] 机械自检（原为“自我审查”）： 在请求外部审查之前，实现 Agent 必须：

• 在工作区运行 lint、类型检查和测试
• 确认仅修改了计划内的文件（检查 diff 范围）
• 修复所有机械性错误（编译错误、测试失败）

此步骤不进行质量评判。 设计质量、架构一致性和验收标准满足情况 仅由 [3] QA Agent 进行交叉审查评估。 原因：自我评估偏差会导致 Agent 持续高估自己的产出 （参见：Anthropic harness 设计研究）。

[2] 自动验证：

oma verify {agent-type} --workspace {workspace} --json

• 通过（退出码 0）：进入交叉审查
• 失败（退出码 1）：将验证输出反馈给 Agent，作为修正依据

[3] 交叉审查：启动 QA Agent 审查变更：

• QA Agent 阅读 diff、运行检查，并根据验收标准进行评估
• 如果存在 docs/CODE-REVIEW.md，QA Agent 将其用作审查清单
• QA Agent 输出：通过（可附带可选的小问题）或失败（列出具体问题）
• 若失败：将问题反馈给实现 Agent 修复

循环限制

计数项	上限	超出时的处理
自检 + 修复循环次数	3	无论如何都升级至交叉审查
交叉审查拒绝次数	2	向用户报告并附上审查历史
循环总迭代次数	5	强制完成并发出质量警告

审查反馈格式

将审查结果反馈给实现 Agent 时：

## Review Feedback (iteration {n}/{max})
**Reviewer**: {self / verify / qa-agent}
**Verdict**: FAIL
**Issues**:
1. {specific issue with file and line reference}
2. {specific issue}
**Fix instruction**: {what to change}

这将取代单次验证。大多数“挑刺”应由 Agent 之间完成。 人工审查用于最终批准，而非发现 lint 错误。

重试逻辑（审查循环耗尽后）

• 第 1 次重试：重新启动 Agent，并将完整审查历史作为上下文
• 第 2 次重试：重新启动 Agent，附上“尝试不同的方法”及审查历史
• 最终失败：向用户报告完整审查过程，并询问是否继续或中止

澄清债务（CD）监控

跟踪会话执行期间用户的修正。完整协议请参阅 ../_shared/core/session-metrics.md。

事件分类

用户在会话期间发送反馈时：

• 澄清（+10）：用户回答 Agent 的问题
• 纠正（+25）：用户纠正 Agent 的误解
• 重做（+40）：用户否定工作并要求重新开始

阈值操作

CD 分数	操作
CD >= 50	需要 RCA：QA Agent 必须在 lessons-learned.md 中添加条目
CD >= 80	暂停会话：请求用户重新明确需求
redo >= 2	锁定范围：继续之前，请求用户明确确认允许列表

记录

每次用户纠正事件后：

[EDIT]("session-metrics.md", append event to Events table)

会话结束时，如果 CD >= 50：

1. 在最终报告中包含 CD 摘要
2. 触发 QA Agent 生成 RCA
3. 在 lessons-learned.md 中更新预防措施

参考

• 提示词模板：resources/subagent-prompt-template.md
• 记忆架构：resources/memory-schema.md
• 配置：config/cli-config.yaml
• 脚本：scripts/spawn-agent.sh、scripts/parallel-run.sh、scripts/verify.sh
• 任务模板：templates/
• 技能到 Agent 的映射：../_shared/core/skill-routing.md
• 验证：scripts/verify.sh <agent-type>
• 会话指标：../_shared/core/session-metrics.md
• API 合约：../_shared/core/api-contracts/
• 上下文加载：../_shared/core/context-loading.md
• 难度指南：../_shared/core/difficulty-guide.md
• 推理模板：../_shared/core/reasoning-templates.md
• 澄清协议：../_shared/core/clarification-protocol.md
• 上下文预算：../_shared/core/context-budget.md
• 经验总结：../_shared/core/lessons-learned.md