oma-coordination

多 Agent 工作流指南

调度

目标

指导如何手动协调多个 Agent，处理涉及 PM、前端、后端、移动端和 QA 职责的复杂工作。

意图特征

• 用户希望获得分步协调指导、手动启动 Agent，或规划跨领域工作，而不需要完全自动化。
• 任务涉及多个专业 Agent，需要对齐契约。

适用场景

• 涉及多个领域的复杂功能（全栈、移动端）
• 需要协调前端、后端、移动端和 QA
• 用户希望获得多 Agent 协调的分步指导

不适用场景

• 简单的单领域任务 -> 直接使用相应的 Agent
• 用户希望自动执行 -> 使用 orchestrator
• 快速修复错误或小幅更改

预期输入

• 复杂功能或项目目标
• 所需领域和优先级层级
• 工作区/会话约束以及 API/数据契约需求

预期输出

• 手动协调流程
• PM 任务拆解、Agent 启动顺序、监控指导和 QA 审查步骤
• API/数据契约对齐检查点

依赖项

• PM、前端、后端、移动端、QA 和 orchestrator 技能
• CLI oma agent spawn 以及进度/结果记忆约定

控制流特性

• 根据任务复杂度、优先级层级、依赖顺序以及是否需要自动化进行分支处理
• 适当时并行启动优先级相同且相互独立的任务
• 监控进度文件和契约对齐情况

结构化流程

入口

1. 确认任务是否复杂到需要多个 Agent 协调。
2. 复用当前计划和交接状态；如果需要拆解任务或更改契约，则使用 PM。
3. 确定优先级层级和共享契约。
4. 在分配并行工作或协调所有权交接和结果收集之前，应用共享协作策略。

阶段

1. 准备：定义会话、领域和任务拆解需求。
2. 执行：按优先级使用独立工作区启动 Agent。
3. 验证：监控进度以及 API/数据契约对齐情况。
4. 收尾：进行 QA 审查并协调修复工作。

转换

• 如果任务简单，则交由一位专家处理。
• 如果用户希望自动执行，则使用 orchestrator。
• 如果 QA 报告阻塞性缺陷或必要的验证缺口，则在现有恢复预算内，将受影响的工作交由负责的 Agent 处理。

失败与恢复

• 如果契约不一致，则暂停后续前端/移动端工作，直到后端/API 契约得到协调。
• 如果 Agent 工作区发生冲突，则划分所有权边界。
• 如果进度停滞，则检查进度文件并重新下达有针对性的指令。

退出

• 成功：专家输出已协调并经过 QA 审查。
• 部分成功：明确说明受阻的 Agent、契约冲突或 QA 失败。

逻辑操作

操作

操作	SSL 基元	依据
阅读请求和领域	READ	用户提示词和项目上下文
选择 Agent 方案	SELECT	PM 任务拆解和优先级层级
启动 Agent	CALL_TOOL	oma agent spawn
监控进度	READ	注入的任务/运行范围内的进度、认领和回执
验证契约	VALIDATE	API/数据模型对齐情况
通知协调状态	NOTIFY	最终协调摘要

工具和辅助资源

• oma agent spawn、PM/前端/后端/移动端/QA Agent
• 记忆/进度/结果文件
• 已配置的代码智能功能；原生回退方案见 ../_shared/core/code-intelligence.md

规范命令路径

# If planning is required, dispatch the declared PM task first; otherwise reuse the current plan.
oma agent spawn pm <pm-prompt-file> <session-id> --task-id <plan.pm_task.id> -w ./pm
oma agent spawn backend <backend-prompt-file> <session-id> --task-id <plan.backend_task.id> -w ./backend &
oma agent spawn frontend <frontend-prompt-file> <session-id> --task-id <plan.frontend_task.id> -w ./frontend &
wait

当可使用原生运行时分派时（每个 Agent 的目标供应商等于当前运行时供应商），优先使用运行时的原生子 Agent 路径，并将 oma agent spawn 作为跨供应商回退方案——解析规则与 oma-orchestration 相同。

agent spawn 的实用选项：--vendor <vendor>（CLI 供应商覆盖），--isolation worktree（每次生成使用一个 git worktree，防止文件冲突），--read-only（仅使用非破坏性工具，例如用于审查/QA 阶段）。

资源范围

范围	资源目标
LOCAL_FS	进度/结果文件和工作区
PROCESS	Agent 生成命令
MEMORY	会话状态和任务看板
CODEBASE	共享契约和实现区域

前提条件

• 任务涉及多个领域。
• 当前计划明确了任务负责人、验收检查、依赖关系和优先级层级。

影响和副作用

• 生成或指导多个 Agent。
• 协调工作区所有权和 QA 反馈。

防护措施

1. 重用有效计划；只有在需要调整任务拆分或契约时才调用 PM
2. 并行执行互不依赖的任务（同一优先级层级）
3. 在依赖它的前端/移动端工作开始前，重用或更新已变更 API 边界的契约
4. QA 审查始终是最后一步
5. 分配独立工作区以避免文件冲突（或者为每次生成使用 --isolation worktree 创建一个 git worktree）
6. 遵循 ../_shared/core/code-intelligence.md：发现已配置的工具，不要自动安装或跟踪；仅当项目外路径或已忽略路径无法使用原生搜索，或原生搜索超时时，才使用原生搜索
7. 从当前交接状态继续，并按依赖顺序执行适用步骤；记录分支不适用的原因

工作流

步骤 1：与 PM Agent 制定计划

重用现有的有效计划。否则，由 PM 分析需求并创建任务拆分、验收检查、契约和优先级。保留注入的会话/任务/运行 ID；不要重新生成已由分派冻结的计划。

步骤 2：按优先级生成 Agent

解析每个 Agent 的分派路径，然后生成：

1. 从 oma-config.yaml 确定每个 Agent 的目标供应商（agents: 覆盖项，否则使用 model_preset）
2. 如果目标供应商与当前运行时供应商相同，且存在原生子 Agent 路径，则使用原生分派
3. 否则，为该 Agent 使用 oma agent spawn
4. 使用后台进程并行生成所有同优先级任务

# Example: spawn backend and frontend in parallel
oma agent spawn backend backend-prompt.md session-id --task-id plan.backend_task.id -w ./backend &
oma agent spawn frontend frontend-prompt.md session-id --task-id plan.frontend_task.id -w ./frontend &
wait

步骤 3：监控与协调

• 根据 ../_shared/core/execution-policy.md 处理执行期限、资源所有权和取消。优先使用宿主完成通知；否则，由单个协调器进行有界退避轮询。取消或期限耗尽后，停止新的分派、审查和恢复；使用有界终止检查，并在交接中报告仍在运行的任务或不支持取消的情况。
• 读取注入的运行产物和回执。人类可读的进度/结果使用 {memoryConfig.basePath}/progress-{agentId}-{taskId}-{runId}-{sessionId}.md 和对应的 result- 名称；参见 ../_shared/runtime/memory-protocol.md。保持结构化声明路径不变。
• 验证各 Agent 的 API 契约是否一致
• 确保共享数据模型一致

步骤 4：QA 审查

与 QA 一起审查协调后的交付成果。通过相应 Agent 解决阻塞缺陷和必需的验证缺口；在最终定稿前重新运行受影响的检查。

自动化替代方案

如需在不手动生成 Agent 的情况下完全自动执行，请改用 orchestrator 技能。

参考资料

• 并行工作者协作：../_shared/core/collaboration-policy.md（在分配并行工作，或协调同伴问题、所有权交接和结果收集之前阅读）