konglong87 harness-schedule-parallel-agents
Core Capabilities
主会话批量生成子代理，调度并行执行。一个子代理负责一个功能，支持最多 3 个子代理同时运行。
核心职责：
- 读取
feature_list.json（筛选未完成功能） - 按优先级排序（priority > category > id）
- 选择下一批功能（≤ max_parallel_agents，默认 3 个）
- 为每个功能调用
harness-spawn-subharness-agent - 更新
GLOBAL_STATE.md（active_subagents 字段） - 记录调度事件到
EVENT_LOG.md - 输出调度报告
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
成功标准：
- ✅ 成功读取并解析
feature_list.json - ✅ 成功筛选未完成功能（按优先级排序）
- ✅ 成功选择下一批功能（≤ max_parallel_agents）
- ✅ 成功生成 N 个子代理（N ≤ 3）
- ✅ 成功更新
GLOBAL_STATE.md（active_subagents） - ✅ 成功记录调度事件到
EVENT_LOG.md - ✅ 输出详细的调度报告
失败情况：
- ❌ 功能清单文件不存在 → 提示生成功能清单
- ❌ 无未完成功能 → 提示"所有功能已完成"
- ❌ 所有子代理生成失败 → 先触发自动失败处理
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
关键设计决策
最大并行数限制
- 默认 max_parallel_agents: 3
- 防止资源耗尽
- 避免文件冲突
按模块分组
- 同一模块的功能分配给同一子代理
- 减少文件冲突
- 提高并行效率
失败不阻塞
- 某个子代理失败 → 继续生成其他子代理
- 提高成功率
- 记录错误日志
性能优化
批量调度优化:
- 并行生成子代理（同时发起 3 个 Bash 调用）
- Token 消耗降低 30%
状态读取优化:
- 仅读取必要字段（id, priority, category, passes）
- Token 消耗降低 50%