oma-orchestration

编排 - 自动化多 Agent 协调

调度

目标

自动编排多 Agent 执行，包括任务分解、本机/回退分派、记忆协调、进度监控、验证、QA 交叉审查、重试和结果收集。

意图特征

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

适用场景

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

不适用场景

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

预期输入

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

预期输出

• 编排器会话状态、任务看板、进度文件、结果文件和最终摘要
• 专业 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. 为每项任务选择所需的参考资料。若能有把握地匹配到一个技能，则该技能已足够；如果分类不确定或依赖项需要其他领域，则扩展参考资料集合。
5. 在任务看板中记录所选领域、参考资料以及任何回退原因。这些是协调器备注，而非启动器强制执行的上下文暴露字段；仅使用当前分派路径支持的参考资料/上下文控制方式。
6. 分派前应用通用协作策略：分配编辑所有权、同伴联系渠道和结果收集负责人。

阶段

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

转换

• 如果当前运行时/供应商支持本机分派，则使用本机分派。
• 如果供应商不同或本机路径不可用，则使用回退启动方式。
• 如果验证或 QA 未通过，则将反馈交还实现 Agent。
• 如果超出恢复限制，则保留审查历史并返回 partial 或 failed；绝不强制完成。
• 如果恢复过程发现缺少必需的领域参考资料，则更新任务的参考资料选择，但不得更改已冻结的验收约定；通过支持的上下文机制提供该资料。

失败与恢复

• 在配置的限制范围内重试失败的 Agent。
• 审查循环耗尽时，携带审查历史重新启动。
• 记录重要修正后，继续独立工作；仅在缺少重要决策时提问。

退出

• 成功：所有任务均已完成，验证／审查通过，且结果已汇总。
• 部分成功：明确说明失败的 Agent、耗尽的审查循环或缺失的验证。

逻辑操作

操作

操作	SSL 原语	依据
读取配置和任务上下文	READ	oma 配置、路由、请求
将任务分类为领域标签	INFER	任务文本与各项技能的 Intent signature 对比
选择任务参考资料	SELECT	匹配度高的领域、依赖项以及支持的上下文控制
选择分发路径	SELECT	原生或回退
写入会话状态	WRITE	任务看板和记忆文件
启动 Agent	CALL_TOOL	暴露的原生角色子 Agent 工具或 oma agent spawn
轮询进度	READ	进度／结果文件
运行验证	CALL_TOOL	oma verify、测试、QA
更新重试状态	UPDATE_STATE	循环计数器和 CD 指标
报告最终结果	NOTIFY	汇总后的摘要

工具与仪器

• 暴露的原生角色子 Agent 工具、回退启动脚本、记忆工具、验证脚本、QA Agent
• 会话指标、提示词模板、任务模板

标准命令路径

oma agent spawn <agent-type> <prompt-file> <session-id> --task-id <task.id> -w <workspace>
oma verify agent <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. 保持会话状态、任务看板状态、进度文件、声明和凭据一致。每次启动以及原生 begin／finish 路径都使用计划任务 ID。
6. 根据任务需求和置信度选择参考资料。不要仅因某项技能匹配就扩展到所有技能，也不要假设任务看板元数据会强制运行时暴露。

当前原生执行器路径：

• Claude Code：使用 .claude/agents/{agent}.md 定义的 Agent 工具（在一条消息中调用多次 Agent 工具会并行运行；结果同步返回——无需轮询）
• OpenCode：使用原生 task 工具并设置 subagent_type: {agent-id}；同一会话中的 OpenCode 工作不要使用 oma agent spawn，因为它不会显示为原生子任务
• Codex：在受支持时，使用当前会话暴露的原生子 Agent 工具，并采用从 .codex/agents/*.toml 解析出的自定义角色；否则使用 oma agent spawn。
• Gemini：在受支持时，使用当前会话暴露的原生角色子 Agent 工具，并采用解析出的角色；否则使用 oma agent spawn。

codex exec 和 gemini -p 会启动外部 CLI 会话。提示词中的 @agent 字符串并不能建立原生分发，也不会应用自定义角色契约。

配置

设置	默认值	描述
MAX_PARALLEL	3	最大并发子 Agent 数
MAX_RECOVERY_ATTEMPTS	3	每项任务的重试次数和探索假设总数，包括首次尝试
POLL_INTERVAL	有界退避	仅在无法使用完成通知时作为后备方案
回合指导	按角色指定	检查点／恢复信号，而非硬性停止或审批边界

这些是工作流默认值。请从项目配置中解析模型／供应商、并行度和预算设置。config/cli-config.yaml 提供供应商传输注册表；它不会选择当前供应商，也不会覆盖运行时执行设置。

记忆配置

记忆提供方和工具名称可通过 .agents/mcp.json 配置（而非仓库根目录下的 .mcp.json，后者是 Claude Code 的 MCP 服务配置）：

{
  "memoryConfig": {
    "provider": "file",
    "basePath": ".agents/state/memories",
    "tools": {
      "read": "Read",
      "write": "Write",
      "edit": "Edit"
    }
  }
}

工作流阶段

阶段 1 - 规划：复用当前有效计划，或分解请求；保留注入的会话／任务／运行 ID。 阶段 1.5 - 参考资料：按照 Entry 中的说明选择任务参考资料；记录不确定性和扩展原因，不要假定运行时会强制执行。 阶段 2 - 设置：使用当前 ID 和选定的参考资料创建会话／任务看板文件。 阶段 3 - 执行：使用受支持的原生或后备上下文控制，在 MAX_PARALLEL 范围内分派就绪任务。 阶段 4 - 监控：优先使用完成通知；否则使用单一协调器，并采用有界轮询退避。遵循 ../_shared/core/execution-policy.md 中关于共享截止时间、取消、资源所有权和关闭规则的规定。取消或截止时间耗尽后，停止分派和恢复操作，然后再进行验证。 阶段 4.5 - 验证：对每个已完成的 Agent 执行机械检查；仅对 backend、frontend、mobile、qa、debug 和 pm 运行 oma verify agent {agent-type}；随后对每项已完成的实现进行 QA 交叉审查 阶段 5 - 收集：读取检查通过的计划任务的声明和本次运行范围内的报告；编写摘要，不删除证据。

记忆文件所有权

文件	所有者	其他人
orchestrator-session-{sessionId}.md	协调器	只读
task-board-{sessionId}.md	协调器	只读
progress-{agentId}-{taskId}-{runId}-{sessionId}.md	对应运行	协调器读取
result-{agentId}-{taskId}-{runId}-{sessionId}.md	对应运行	协调器读取

Agent 间审查循环（阶段 4.5）

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

循环流程

Agent completes work
    ↓
[1] Mechanical Self-Check: lint, type-check, tests, diff scope
    ↓
[2] Verify: For supported types, run `oma verify agent {agent-type} --workspace {workspace}`
    Unsupported (`db`, `refactor`, `architecture`, `tf-infra`, `docs`) → record SKIP and continue
    ↓ 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 范围）
• 修复所有机械性问题（编译错误、测试失败）

此步骤不进行质量判断。 设计质量、架构一致性以及是否满足验收标准， 仅由 QA Agent 在 [3] 交叉审查中评估。 原因：自我评估偏差会导致 Agent 一贯高估自身输出 （参考：Anthropic harness 设计研究）。

[2] 自动验证：

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

• 仅对 backend、frontend、mobile、qa、debug 和 pm 运行。
• 对于 db、refactor、architecture、tf-infra 和 docs，记录自动验证不受支持，并在完成机械检查后继续进行 QA 交叉审查。
• 通过（退出码 0）：继续交叉审查
• 失败（退出码 1）：将验证输出作为修正上下文反馈给 Agent

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

• QA Agent 阅读 diff、运行检查，并根据验收标准进行评估

• 如果存在 docs/CODE-REVIEW.md，QA Agent 会将其用作审查清单

• QA Agent 输出：通过（可附带小问题）或失败（列出具体问题）

• 失败时：将问题反馈给实现 Agent 修复

循环限制

计数器	上限	超出时的处理
自检 + 修复循环	3	无论如何都升级至交叉审查
交叉审查驳回次数	2	连同审查历史一起报告给用户
循环迭代总数	5	停止恢复；保留失败检查，并返回 partial 或 failed

审查反馈格式

将审查结果反馈给实现 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 之间完成。 交接前解决相关的自动检查问题。仅当下一步操作超出现有授权范围时，才请求批准。

恢复预算（审查循环耗尽后）

针对每条工作流谱系和逻辑目标维护一份预算：attempts_used、attempts_remaining，以及任何已配置的成本上限。初始尝试、每次普通重试以及每个探索假设都会消耗一次尝试。开始恢复前，预留下一项完整操作所需的预算；不得超出预算，也不得启动未完成的探索轮次。

使用 ../_shared/runtime/result-contract.md 中计划的稳定 lineage_id 和任务的 goal_id。新的任务、运行或会话 ID 不会重置预算。首次派发时冻结完整 JSON 计划；拒绝递归规划/审查任务以及派发后的计划修订。修改契约必须明确分离出新的会话和谱系。

重试前先对失败进行分类：PRODUCT_FAILURE 使用剩余的产品恢复预算；WORKFLOW_EVIDENCE_FAILURE 表示当前产品检查已通过，但完成声明或绑定失败。仅证据问题的重放不会自动恢复。最多允许在现有任务和冻结计划下进行一次仅限元数据的修复，并消耗同一预算；若仍未解决，则停止并进行部分交接。遇到证据失败时，不要创建 PM 任务、重新运行产品规划，也不要引入其他工作流的计划审查循环。

• 剩余的第一次尝试：附带审查历史重新启动。
• 后续尝试：选择一次不同的重试，或进行一轮包含 2–3 个假设的探索；前提是剩余尝试次数和成本足够。
• 达到上限时，保留所有检查结果、审查发现和未解决工作。 任务状态为 partial 或 failed，绝不能是 completed。

会话证据

对于实质性修正或审查发现，应在现有任务产物中保留原因、影响和证据。需要复盘或单独的会话摘要时，请使用 ../_shared/core/session-metrics.md。不要对澄清问题评分，也不要根据计数器要求进行根因分析（RCA）。解决受影响的工作，并且只询问实质性缺失的决策。

参考资料

• 并行工作者协作：../_shared/core/collaboration-policy.md（在分配并行工作，或协调同伴问题、所有权交接和结果收集之前阅读）
• 提示词模板：resources/subagent-prompt-template.md
• 记忆模式：resources/memory-schema.md
• 脚本：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 契约模板（SSOT）：../_shared/core/api-contracts/template.md；从 .agents/results/api-contracts/（运行产物）或 docs/plans/contracts/（持久化规范）读取生成的契约
• 上下文加载：../_shared/core/context-loading.md
• 任务分解：../_shared/core/difficulty-guide.md（未解决的范围或依赖项）
• 澄清协议：../_shared/core/clarification-protocol.md
• 上下文预算：../_shared/core/context-budget.md
• 代码智能：../_shared/core/code-intelligence.md
• 运行时经验：../_shared/core/lessons-learned.md（适用于反复出现的故障或请求复盘的情况）