oma-coordination

多 Agent 工作流指南

调度

目标

指导人工协调多个 Agent，共同处理涉及产品经理、前端、后端、移动端和 QA 职责的复杂工作。

意图特征

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

适用场景

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

不适用场景

• 简单的单领域任务 → 直接使用相应的 Agent
• 用户希望自动执行 → 使用编排器
• 快速修复 bug 或小幅改动

预期输入

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

预期输出

• 人工协调流程
• 产品经理的任务拆解、Agent 启动顺序、进度监控指南和 QA 审查步骤
• API／数据约定对齐检查点

依赖项

• 产品经理、前端、后端、移动端、QA 和编排器技能
• CLI oma agent spawn 和进度／结果记忆约定

控制流特性

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

结构化流程

入口

1. 确认任务是否足够复杂，需要多 Agent 协调。
2. 复用当前计划和交接状态；需要任务拆解或约定变更时使用产品经理。
3. 确定优先级层级和共享约定。

阶段

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

转换

• 如果任务简单，则转交给一名专业 Agent。
• 如果用户希望自动执行，则使用编排器。
• 如果 QA 报告了阻塞性缺陷或必要的验证缺口，则在现有恢复预算内，将相关工作转交给负责的 Agent。

失败与恢复

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

出口

• 成功：专业 Agent 的产出已协调一致并通过 QA 审查。
• 部分成功：明确说明受阻的 Agent、约定冲突或 QA 失败。

逻辑操作

操作

操作	SSL 原语	依据
读取请求和领域	READ	用户提示词和项目上下文
选择 Agent 计划	SELECT	产品经理的任务拆解和优先级层级
启动 Agent	CALL_TOOL	oma agent spawn
监控进度	READ	注入的、限定于任务／运行范围的进度、认领记录和回执
验证约定	VALIDATE	API／数据模型对齐情况
通知协调状态	NOTIFY	最终协调摘要

工具与手段

• oma agent spawn，产品经理／前端／后端／移动端／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 工作树，避免文件冲突），--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. 否则，使用 oma agent spawn 启动该 Agent
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：监控与协调

• 读取注入的运行产物和回执。人类可读的进度／结果使用 {memoryConfig.basePath}/progress-{agentId}-{taskId}-{runId}-{sessionId}.md 以及对应的 result- 名称；参见 ../_shared/runtime/memory-protocol.md。保持结构化声明路径不变。
• 验证各 Agent 之间的 API 契约是否一致
• 确保共享数据模型保持一致

步骤 4：QA 审查

与 QA 一起审查协调后的交付成果。通过相关 Agent 解决阻塞性缺陷和必须完成的验证缺口；完成前重新运行受影响的检查。

自动化替代方案

如需在无需手动启动的情况下全自动执行，请改用 orchestrator 技能。

参考资料