# Harness Schedule Parallel Agents

> 主会话批量生成子代理，调度并行执行（一个子代理一个功能）

- Skill: `konglong87/harness-schedule-parallel-agents` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add konglong87/harness-schedule-parallel-agents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-schedule-parallel-agents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: konglong87 (https://skillmd.com/u/konglong87)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konglong87/harness-schedule-parallel-agents

---


# 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

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

### Step 2: 筛选未完成功能

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

Token 消耗: ~500 tokens
```

### Step 3: 按优先级排序

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

Token 消耗: ~500 tokens
```

### Step 4: 选择下一批功能

```yaml
选择逻辑:
  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

```yaml
工具: 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

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

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

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

### Step 8: 输出调度报告

```yaml
输出格式:
  🚀 并行调度完成
  子代理数量: 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: 功能清单文件不存在

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

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

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

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

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

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

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

## Relationships

### Triggers (触发下游)

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

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

### Triggered By (被谁触发)

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

### Dependencies (前置依赖)

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

## Token 消耗分析

```yaml
小型项目（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 个子代理

```yaml
输入:
  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: 无未完成功能

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

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

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

  下一步：生成最终报告
```

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

```yaml
输入:
  选择 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. **失败不阻塞**
   - 某个子代理失败 → 继续生成其他子代理
   - 提高成功率
   - 记录错误日志

### 性能优化

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

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