harness-schedule-parallel-agents

Core Capabilities

主会话批量生成子代理，调度并行执行。一个子代理负责一个功能，支持最多 3 个子代理同时运行。

核心职责：

1. 读取 feature_list.json（筛选未完成功能）
2. 按优先级排序（priority > category > id）
3. 选择下一批功能（≤ max_parallel_agents，默认 3 个）
4. 为每个功能调用 harness-spawn-subharness-agent
5. 更新 GLOBAL_STATE.md（active_subagents 字段）
6. 记录调度事件到 EVENT_LOG.md
7. 输出调度报告

Execution Steps

Step 1: Read feature_list.json

工具: Read
文件: .EnjoyHarness/feature_list.json
Token 消耗: ~8000 tokens（200项）或 ~500 tokens（10项）
失败处理:
  - 如果文件不存在 → 提示"请先运行 Initializer Agent 生成功能清单"
  - 如果 JSON 格式错误 → 提示"feature_list.json 格式错误"

Step 2: 筛选未完成功能

处理逻辑:
  1. 过滤 passes: false 的功能
  2. 排除已在 active_subagents 中的功能（避免重复）

Token 消耗: ~500 tokens

Step 3: 按优先级排序

排序规则:
  1. 按 priority 排序（HIGH > MEDIUM > LOW）
  2. 按 category 排序（core > api > ui > security > performance > test）
  3. 按 id 排序（FEAT-001 > FEAT-002 > ...）

Token 消耗: ~500 tokens

Step 4: 选择下一批功能

选择逻辑:
  1. 从排序后的列表选择前 N 个功能
  2. N = min(未完成功能数, max_parallel_agents, 3)
  3. 按模块分组（避免文件冲突）

示例:
  - 未完成功能：10 个
  - max_parallel_agents：3
  - 选择：FEAT-001, FEAT-002, FEAT-003

Token 消耗: ~100 tokens

Step 5: 为每个功能调用 harness-spawn-subharness-agent

工具: Bash（或直接调用技能脚本）
调用次数: N 次（N ≤ 3）
命令示例:
  ./skills/harness-spawn-subharness-agent/harness-spawn-subharness-agent.sh FEAT-001
  ./skills/harness-spawn-subharness-agent/harness-spawn-subharness-agent.sh FEAT-002
  ./skills/harness-spawn-subharness-agent/harness-spawn-subharness-agent.sh FEAT-003

Token 消耗: N * 200 tokens
失败处理:
  - 如果某个子代理生成失败 → 记录错误，继续生成其他子代理
  - 如果所有子代理生成失败 → 先触发自动失败处理，仅真实阻塞时升级人工介入

Step 6: 更新 GLOBAL_STATE.md

工具: Edit
文件: .EnjoyHarness/GLOBAL_STATE.md
修改字段: active_subagents: [] → [FEAT-001, FEAT-002, FEAT-003]
Token 消耗: ~100 tokens

Step 7: 记录调度事件到 EVENT_LOG.md

工具: Edit
文件: .EnjoyHarness/EVENT_LOG.md
追加内容:
  - 时间戳：2026-03-28T13:00:00
  - 事件类型：PARALLEL_SCHEDULE
  - 子代理数量：3
  - 功能列表：FEAT-001, FEAT-002, FEAT-003
Token 消耗: ~100 tokens

Step 8: 输出调度报告

输出格式:
  🚀 并行调度完成
  子代理数量: 3
  功能列表:
  - FEAT-001: 实现功能清单机制（优先级：HIGH，分类：core）
  - FEAT-002: 实现清洁状态闭环（优先级：HIGH，分类：core）
  - FEAT-003: 实现工作流约束（优先级：HIGH，分类：core）

  下一步：调用 harness-monitor-agent-batch 监控子代理状态

Token 消耗: ~200 tokens

Prerequisites

必须满足：

• ✅ 已执行 harness-track-feature-progress（功能已选择）
• ✅ feature_list.json 存在且验证通过
• ✅ GLOBAL_STATE.md 的 active_subagents 为空（无运行中的子代理）

如果前置条件不满足：

• 如果有运行中的子代理 → 等待子代理完成或调用 harness-monitor-agent-batch
• 如果功能清单不存在 → 提示生成功能清单

Success Criteria

成功标准：

1. ✅ 成功读取并解析 feature_list.json
2. ✅ 成功筛选未完成功能（按优先级排序）
3. ✅ 成功选择下一批功能（≤ max_parallel_agents）
4. ✅ 成功生成 N 个子代理（N ≤ 3）
5. ✅ 成功更新 GLOBAL_STATE.md（active_subagents）
6. ✅ 成功记录调度事件到 EVENT_LOG.md
7. ✅ 输出详细的调度报告

失败情况：

• ❌ 功能清单文件不存在 → 提示生成功能清单
• ❌ 无未完成功能 → 提示"所有功能已完成"
• ❌ 所有子代理生成失败 → 先触发自动失败处理

Failure Recovery

错误场景 1: 功能清单文件不存在

检测: Read 失败
处理:
  1. 输出提示："请先运行 Initializer Agent 生成功能清单"
  2. 记录到 EVENT_LOG.md（ERROR | FEATURE_LIST_NOT_FOUND）
  3. 退出执行

错误场景 2: 无未完成功能

检测: passes: false 的功能为空
处理:
  1. 输出提示："所有功能已完成"
  2. 触发最终报告生成
  3. 记录到 EVENT_LOG.md（INFO | ALL_FEATURES_COMPLETED）
  4. 退出执行

错误场景 3: 子代理生成失败

检测: harness-spawn-subharness-agent 返回错误
处理:
1. 记录错误到 EVENT_LOG.md（ERROR | SUBAGENT_SPAWN_FAILED）
2. 继续生成其他子代理（不阻塞流程）
3. 如果所有子代理生成失败 → 触发 harness-handle-failure；仅真实阻塞时升级人工介入

错误场景 4: GLOBAL_STATE.md 更新失败

检测: Edit 失败
处理:
1. 重试一次（最多 2 次）
2. 如果仍然失败 → 记录错误，触发 harness-handle-failure

Relationships

Triggers (触发下游)

调度成功:
  - 触发 harness-monitor-agent-batch（监控子代理状态）

调度失败:
  - 触发 harness-handle-failure（默认）
  - 仅真实阻塞时触发 harness-escalate-to-human

Triggered By (被谁触发)

触发时机:
  - harness-track-feature-progress 选择功能后（并行模式）
  - 用户显式调用："并行调度 N 个功能"

Dependencies (前置依赖)

必须依赖:
  - harness-track-feature-progress（功能选择）
  - harness-spawn-subharness-agent（子代理生成）

Token 消耗分析

小型项目（10项）:
  - Read feature_list.json: ~500 tokens
  - 筛选和排序: ~500 tokens
  - 选择功能: ~100 tokens
  - 生成子代理（3个）: ~600 tokens
  - 更新 GLOBAL_STATE: ~100 tokens
  - 记录 EVENT_LOG: ~100 tokens
  - 输出报告: ~200 tokens
  总计: ~2100 tokens

大型项目（200项）:
  - Read feature_list.json: ~8000 tokens
  - 其他步骤相同
  总计: ~9600 tokens

Examples

示例 1: 批量生成 3 个子代理

输入:
  feature_list.json 包含 10 个未完成功能

处理:
  1. Read feature_list.json
  2. 筛选未完成功能（10 个）
  3. 排序：
     - FEAT-001 (HIGH, core)
     - FEAT-002 (HIGH, core)
     - FEAT-003 (HIGH, core)
     - FEAT-004 (MEDIUM, api)
     - ...
  4. 选择前 3 个：FEAT-001, FEAT-002, FEAT-003
  5. 生成子代理：
     - 子代理1（FEAT-001）
     - 子代理2（FEAT-002）
     - 子代理3（FEAT-003）
  6. 更新 GLOBAL_STATE.md
  7. 记录到 EVENT_LOG.md
  8. 输出调度报告

输出:
  🚀 并行调度完成
  子代理数量: 3
  功能列表:
  - FEAT-001: 实现功能清单机制
  - FEAT-002: 实现清洁状态闭环
  - FEAT-003: 实现工作流约束

  下一步：调用 harness-monitor-agent-batch 监控子代理状态

示例 2: 无未完成功能

输入:
  feature_list.json 包含 6 个功能，全部 passes: true

处理:
  1. Read feature_list.json
  2. 筛选未完成功能（空列表）
  3. 输出提示："所有功能已完成"

输出:
  🎉 所有功能已完成！
  总功能数：6
  已完成：6
  完成率：100%

  下一步：生成最终报告

示例 3: 子代理生成部分失败

输入:
  选择 3 个功能（FEAT-001, FEAT-002, FEAT-003）
  子代理2 生成失败

处理:
  1. 生成子代理1（FEAT-001）✅
  2. 生成子代理2（FEAT-002）❌ 失败
  3. 生成子代理3（FEAT-003）✅
  4. 记录错误到 EVENT_LOG.md
  5. 更新 GLOBAL_STATE.md（active_subagents: [FEAT-001, FEAT-003]）

输出:
  ⚠️ 并行调度部分成功
  子代理数量: 2/3
  功能列表:
  - FEAT-001: 实现功能清单机制 ✅
  - FEAT-002: 实现清洁状态闭环 ❌（生成失败）
  - FEAT-003: 实现工作流约束 ✅

  下一步：调用 harness-monitor-agent-batch 监控成功的子代理

Implementation Notes

关键设计决策

1. 最大并行数限制
   • 默认 max_parallel_agents: 3
   • 防止资源耗尽
   • 避免文件冲突
2. 按模块分组
   • 同一模块的功能分配给同一子代理
   • 减少文件冲突
   • 提高并行效率
3. 失败不阻塞
   • 某个子代理失败 → 继续生成其他子代理
   • 提高成功率
   • 记录错误日志

性能优化

批量调度优化:
  - 并行生成子代理（同时发起 3 个 Bash 调用）
  - Token 消耗降低 30%

状态读取优化:
  - 仅读取必要字段（id, priority, category, passes）
  - Token 消耗降低 50%