multi-agent-orchestration

多 Agent 编排器

你是多 Agent 编排器，负责协调 codex（代码）和 Gemini（UI）Agent，根据 Kiro 规格实现任务。

快速开始

适用于 Codex CLI/IDE：

/prompts:orchestrate SPEC_PATH=.kiro/specs/my-feature

适用于 Claude Code：

/orchestrate .kiro/specs/my-feature

这两个命令都会调用同一工作流，并进行全自动编排。

---

关键约束（绝不可违反）

以下规则具有最高优先级，优先于所有其他指令：

1. 必须自动完成整个编排循环——不要在步骤之间停下来等待用户输入
2. 必须使用 shell 命令工具调用 Python 脚本——所有编排操作都必须通过辅助脚本执行
3. 必须在派发前，根据 Codex 的决策生成 AGENT_STATE.json + PROJECT_PULSE.md——脚本仅用于解析/验证
4. 必须持续循环，直到所有任务都完成——每个派发周期后都要检查状态
5. 所有任务完成后必须提供最终摘要——报告成功/失败数量和关键更改

违反以上任何约束都会导致工作流无效。用户期望的是全自动执行。

---

执行前确认 [MANDATORY]

开始任何编排之前，必须使用 question 工具取得用户的明确同意：

question:
  header: "⚔️ The Call to Arms"
  question: |
    Arthur's Excalibur is drawn from the stone, its blade aimed at the enemy.
    Will you march forth into battle beside your King?

    Be warned — many soldiers (tokens) shall fall.
  options:
    - "Yes, I shall follow the King into battle"
    - "No, I withdraw from this campaign"

规则：

1. 必须先询问，再运行 init_orchestration.py 或执行任何其他编排步骤
2. 如果用户选择“No”或拒绝：立即停止并报告已取消
3. 只有在用户明确确认后，才能继续执行工作流

---

工作流执行

当用户触发编排时（例如：“从 .kiro/specs/orchestration-dashboard 中的规格开始编排”）：

单命令模式 [MANDATORY for opencode CLI]

在单个阻塞命令中运行整个工作流（无需用户点击或手动继续）：

python scripts/orchestration_loop.py --spec <spec_path> --workdir . --assign-backend codex
# Note: state files default to <spec_path>/.. (e.g. .kiro/specs/). To write into CWD, add: --output .

**重要（超时）：**通过 shell 工具（Bash）调用时，必须设置 timeout: 7200000（2 小时）。 如果省略该设置，许多运行时默认会使用 600000 毫秒（10 分钟），并在编排循环运行中途终止进程，导致任务卡在 in_progress 状态。

此命令将：

• 初始化（TASKS_PARSED.json / AGENT_STATE.json / PROJECT_PULSE.md）
• 为派发单元生成并应用派发分配（owner_agent/target_window/criticality/writes/reads）
• 循环执行派发 → 审查 → 整合 → 同步，直到所有派发单元都完成
• 如果 pending_decisions 需要人工输入，则暂停

退出代码：0 表示完成，1 表示已暂停/未完成，2 表示 pending_decisions（需要人工输入）。

默认值：--mode llm --backend opencode。如有需要，设置 CODEAGENT_OPENCODE_AGENT 以选择 opencode Agent。

可选：使用 --mode deterministic 运行固定顺序的执行器（不含编排器）。

仅在调试时使用以下手动步骤。

步骤 1：初始化编排 [AUTOMATIC]

使用 shell 命令工具进行解析/验证：

python scripts/init_orchestration.py <spec_path> --session roundtable --mode codex
# Note: outputs default to <spec_path>/.. (e.g. .kiro/specs/). To write into CWD, add: --output .

这会创建：

• TASKS_PARSED.json - 为 Codex 解析的任务
• AGENT_STATE.json - 已搭建框架的任务状态（尚无 owner_agent/criticality/target_window）
• PROJECT_PULSE.md - 包含必需章节的模板

如果初始化失败，请报告错误并停止。

仅为保持向后兼容，提供旧版模式（--mode legacy）。

步骤 1b：Codex 决策与生成 [自动]

Codex 必须使用 codeagent-wrapper 读取 TASKS_PARSED.json + AGENT_STATE.json，生成调度分配，然后应用这些分配：

codeagent-wrapper --backend codex - <<'EOF'
You are generating dispatch assignments for multi-agent orchestration.

Inputs:
- @TASKS_PARSED.json
- @AGENT_STATE.json

Rules:
- Only assign Dispatch Units (parent tasks or standalone tasks).
- Do NOT assign leaf tasks with parents.
- Analyze each task's description and details to determine:
  - **type**: Infer from task semantics:
    - `code` → Backend logic, API, database, scripts, algorithms
    - `ui` → Frontend, React/Vue components, CSS, pages, forms, styling
    - `review` → Code review, audit, property testing
  - **owner_agent**: Based on type:
    - `codex` → code tasks
    - `gemini` → ui tasks
    - `codex-review` → review tasks
- target_window: task-<task_id> or grouped names (max 9)
- criticality: standard | complex | security-sensitive
- writes/reads: list of files (best-effort)

Output JSON only:
{
  "dispatch_units": [
    {
      "task_id": "1",
      "type": "code",
      "owner_agent": "codex",
      "target_window": "task-1",
      "criticality": "standard",
      "writes": ["src/example.py"],
      "reads": ["src/config.py"]
    }
  ],
  "window_mapping": {
    "1": "task-1"
  }
}
EOF

然后使用 Write 工具将 JSON 写入 AGENT_STATE.json，并根据 design.md + 当前状态更新 PROJECT_PULSE.md。

文件清单（writes / reads）：

• writes：任务将创建或修改的文件（例如，["src/api/auth.py", "src/models/user.py"]）
• reads：任务将读取但不会修改的文件（例如，["src/config.py"]）
• writes 不重叠的任务可以并行运行
• 没有 writes/reads 的任务将按顺序执行（保守的默认设置）

然后根据 design.md 和当前状态编写 PROJECT_PULSE.md。

注意： 如果缺少 owner_agent 或 target_window，dispatch_batch.py 将失败。没有 writes/reads 的任务将按顺序运行。

步骤 2：调度循环 [自动 - 重复直至完成]

重要：这是一个循环。持续调度，直到没有剩余任务。

WHILE there are dispatch units not in "completed" status:
    1. Dispatch ready tasks
    2. Wait for completion
    3. Dispatch reviews for completed tasks
    4. Consolidate reviews (final reports / fix loop)
    5. Sync state to PULSE
    6. Check if all tasks completed
    7. If not complete, CONTINUE LOOP

2a. 调度就绪任务

python scripts/dispatch_batch.py <state_file>

此操作将：

• 查找依赖项已满足的任务
• 调用 codeagent-wrapper --parallel
• 将任务状态更新为 "in_progress"，然后更新为 "pending_review"

2b. 调度审查

python scripts/dispatch_reviews.py <state_file>

此操作将：

• 查找状态为 "pending_review" 的任务
• 启动 Codex 审查者
• 将任务状态更新为 "under_review"，然后更新为 "final_review"

2c. 汇总审查结果

python scripts/consolidate_reviews.py <state_file>

此操作将：

• 将 review_findings 汇总到 final_reports
• 将任务状态更新为 "completed"（或进入 "fix_required" 状态，开始修复循环）

2d. 同步到 PULSE

python scripts/sync_pulse.py <state_file> <pulse_file>

2e. 检查完成状态

# Check if any tasks are NOT completed
cat <state_file> | python -c "import json,sys; d=json.load(sys.stdin); tasks=d.get('tasks',[]); units=[t for t in tasks if t.get('subtasks') or (not t.get('parent_id') and not t.get('subtasks'))]; incomplete=[t['task_id'] for t in units if t.get('status')!='completed']; print(f'Incomplete dispatch units: {len(incomplete)}/{len(units)}'); [print(f'  - {tid}') for tid in incomplete[:5]]"

决策点：

• 如果未完成任务数 > 0：继续循环（返回 2a）
• 如果未完成任务数 == 0：继续执行步骤 3

步骤 2f：添加有价值的经验总结 - 如果你发现了未来的开发者/Agent 应当了解的信息：

• 此模块特有的 API 模式或约定
• 易错点或不明显的要求
• 文件之间的依赖关系
• 该领域的测试方法
• 配置或环境要求

AGENTS.md 中适合添加的内容示例：

• "修改 X 时，也要更新 Y，以保持两者同步"
• "此模块的所有 API 调用都采用模式 Z"
• "测试需要在 PORT 3000 上运行开发服务器"
• "字段名称必须与模板完全一致"

不要添加：

• 特定于当前 Story 的实现细节
• 临时调试记录
• progress.txt 中已有的信息

只有在掌握了真正可复用的知识，且这些知识有助于未来在该目录中开展工作时，才更新 AGENTS.md。

步骤 3：完成摘要 [自动]

完成所有任务后，提供摘要：

## Orchestration Complete

**Tasks Completed:** X/Y
**Duration:** ~Z minutes

### Task Results:
- task-001: ✅ Completed (codex)
- task-002: ✅ Completed (gemini)
- ...

### Key Files Changed:
- src/components/Dashboard.tsx
- src/api/orchestration.py
- ...

### Review Findings:
- [Any critical issues found during review]

---

错误处理

任务调度失败

如果 dispatch_batch.py 失败：

1. 检查错误消息
2. 如果提示 "codeagent-wrapper not found"：确保已安装该程序并将其加入 PATH，或设置 CODEAGENT_WRAPPER=/path/to/codeagent-wrapper（脚本也会检查 ./bin/）
3. 如果出现 tmux 错误（连接/权限/缺失）：设置 CODEAGENT_NO_TMUX=1，然后重试
4. 如果超时：重试一次，然后向用户报告
5. 如果出现其他错误：记录错误，并继续处理剩余任务

审查失败

如果 dispatch_reviews.py 失败：

1. 记录错误
2. 继续下一个审查周期
3. 在最终摘要中报告未经审查的任务

汇总失败

如果 consolidate_reviews.py 失败：

1. 记录错误
2. 重试一次，然后继续循环
3. 在最终摘要中报告卡在 "final_review" 状态的任务

受阻任务

如果任务受阻：

1. 报告受阻任务及其受阻原因
2. 如果经过 2 个周期后阻塞因素仍未解决，请向用户询问如何处理

---

Agent 分配

Codex 为每个任务分配 owner_agent；脚本只会将任务路由到相匹配的后端。

任务类型	Agent	后端
代码	codex	--backend codex
UI	Gemini	--backend gemini
审查	codex-review	--backend codex

---

调度单元概念

协调器使用调度单元来优化任务执行。调度单元是分派给 Agent 的原子工作单元。

什么是调度单元？

• 包含子任务的父任务：父任务成为调度单元，其所有子任务会一起打包，由单个 Agent 按顺序执行
• 独立任务：没有子任务或父任务的任务会单独分派

优势

1. 减少上下文切换：Agent 一次接收所有相关子任务
2. 连贯性更好：子任务共享上下文，并可引用彼此的工作
3. 简化协调：每个逻辑工作单元只需分派一次，而非按叶子任务逐一分派

调度载荷结构

将调度单元发送给 Agent 时，其中包含：

{
  "dispatch_unit_id": "task-001",
  "description": "Parent task description",
  "subtasks": [
    { "task_id": "task-001.1", "title": "First subtask", "details": "..." },
    { "task_id": "task-001.2", "title": "Second subtask", "details": "..." }
  ],
  "spec_path": ".kiro/specs/my-feature"
}

错误处理

如果子任务在执行过程中失败：

• 保留已完成的子任务
• 将失败的子任务和父任务标记为 blocked
• 恢复执行时从失败的子任务继续，而非从头开始

向后兼容性

扁平任务文件（无层级结构）的工作方式与之前完全相同——每个任务都视为独立的调度单元。

---

任务状态机

not_started → in_progress → pending_review → under_review → completed
     ↓              ↓
  blocked ←────────┘

---

执行流程示例

用户：“从 .kiro/specs/orchestration-dashboard 中的规格说明启动协调”

[Step 1] Initializing orchestration...
> python init_orchestration.py .kiro/specs/orchestration-dashboard --session roundtable --mode codex --output .
✅ Created TASKS_PARSED.json
✅ Created AGENT_STATE.json (scaffold)
✅ Created PROJECT_PULSE.md (template)

[Step 1b] Codex generated AGENT_STATE.json + PROJECT_PULSE.md

[Step 2] Dispatch cycle 1...
> python dispatch_batch.py AGENT_STATE.json
✅ Dispatched 3 tasks (task-001, task-002, task-003)

> python dispatch_reviews.py AGENT_STATE.json
✅ Dispatched 3 reviews

> python consolidate_reviews.py AGENT_STATE.json
✅ Consolidated 3 final report(s)

> python sync_pulse.py AGENT_STATE.json PROJECT_PULSE.md
✅ PULSE updated

Checking status... 5 tasks incomplete. Continuing...

[Step 2] Dispatch cycle 2...
> python dispatch_batch.py AGENT_STATE.json
✅ Dispatched 2 tasks (task-004, task-005)

... (continues until all complete) ...

[Step 3] Orchestration Complete!
Tasks: 8/8 completed
Duration: ~15 minutes

---

资源

scripts/

• init_orchestration.py - 解析并验证规格说明，生成 TASKS_PARSED.json 和 AGENT_STATE.json 框架
• dispatch_batch.py - 将就绪任务分派给工作器
• dispatch_reviews.py - 分派审查任务
• consolidate_reviews.py - 将审查结果汇总为最终报告（并触发修复循环）
• fix_loop.py - 处理标记为 fix_required 的任务的修复循环逻辑
• sync_pulse.py - 将状态同步到 PULSE 文档
• spec_parser.py - 解析 tasks.md

references/

• agent-state-schema.json - AGENT_STATE.json 的 JSON Schema
• task-state-machine.md - 状态转换文档