konglong87 harness-monitor-agent-batch
Core Capabilities
主会话批量监控子代理状态（合并原 harness-monitor-subharness-agent），检测子代理完成，触发结果合并。
核心职责：
- 读取
GLOBAL_STATE.md（获取 active_subagents） - 批量检查子代理状态（增量式状态摘要）
- 检测子代理完成（status: COMPLETED）
- 调用
harness-merge-agent-results合并结果 - 更新
feature_list.json（passes: false → true） - 移除已完成的子代理（active_subagents）
- 输出状态报告
- Sleep 30 秒（避免频繁轮询）
- 循环监控（直到所有子代理完成）
Execution Steps
Step 1: Read GLOBAL_STATE.md（获取 active_subagents）
工具: Read
文件: .EnjoyHarness/GLOBAL_STATE.md
Token 消耗: ~200 tokens
目的: 获取 active_subagents 字段（运行中的子代理列表）
Step 2: 批量检查子代理状态（增量式状态摘要）
工具: Bash + grep
命令: grep -E "^status:|^clean_state:" .subharness/*/STATUS.md
Token 消耗: ~50 tokens per 子代理（性能优化版）
示例输出:
.subharness/FEAT-001/STATUS.md:status: COMPLETED
.subharness/FEAT-001/STATUS.md:clean_state: true
.subharness/FEAT-002/STATUS.md:status: RUNNING
.subharness/FEAT-002/STATUS.md:clean_state: false
.subharness/FEAT-003/STATUS.md:status: FAILED
.subharness/FEAT-003/STATUS.md:clean_state: false
性能优化:
- 仅读取关键字段（status, clean_state）
- 不读取完整 STATUS.md
- Token 消耗降低 90%
Step 3: 处理每个子代理状态
3.1 如果 status == COMPLETED
处理:
1. 调用 harness-merge-agent-results（合并结果）
2. 更新 feature_list.json（passes: false → true）
3. 移除 active_subagents（从 GLOBAL_STATE.md）
4. 清理子代理目录（可选）
5. 记录到 EVENT_LOG.md（SUBAGENT_COMPLETE）
Token 消耗: ~1000 tokens per 子代理
3.2 如果 status == FAILED
处理:
1. 检查 error_count（从 STATUS.md）
2. 如果 error_count < 3 → 触发重试（harness-handle-failure）
3. 如果 error_count >= 3 → 先触发熔断与自动恢复；仅真实阻塞时升级 harness-escalate-to-human
4. 记录到 EVENT_LOG.md（SUBAGENT_FAILED）
Token 消耗: ~500 tokens
3.3 如果 status == RUNNING
处理:
1. 检查运行时间（started_at 字段）
2. 如果超过 estimated_completion → 记录警告（可能超时）
3. 继续监控
Token 消耗: ~100 tokens
Step 4: 输出状态报告
输出格式:
📊 子代理状态监控
总子代理数: 3
已完成: 1 (FEAT-001)
运行中: 1 (FEAT-002)
失败: 1 (FEAT-003, error_count: 2/3)
下一步:
- FEAT-001: 合并结果
- FEAT-002: 继续监控
- FEAT-003: 重试（失败次数 < 3）
Token 消耗: ~200 tokens
Step 5: Sleep 30 秒（避免频繁轮询）
工具: Bash
命令: sleep 30
Token 消耗: ~0 tokens
性能优化:
- 轮询间隔：30 秒（而非 5 秒）
- 降低 Token 消耗 6 倍
- 降低 CPU 占用
Step 6: 返回 Step 1（循环监控）
循环条件:
- active_subagents 不为空
- 或者有子代理正在重试
退出条件:
- 所有子代理已完成（active_subagents 为空）
- 或者触发熔断（error_count >= 3）
Prerequisites
必须满足：
- ✅ 已执行
harness-schedule-parallel-agents（子代理已生成） - ✅
GLOBAL_STATE.md的active_subagents不为空
如果前置条件不满足：
- 如果无运行中的子代理 → 提示"无运行中的子代理"
- 如果子代理已全部完成 → 输出"所有子代理已完成"
Success Criteria
成功标准：
- ✅ 成功读取
GLOBAL_STATE.md（获取 active_subagents） - ✅ 成功批量检查子代理状态（增量式状态摘要）
- ✅ 正确处理不同状态（COMPLETED/FAILED/RUNNING）
- ✅ 成功合并已完成的子代理结果
- ✅ 成功更新
feature_list.json和GLOBAL_STATE.md - ✅ 输出详细的状态报告
失败情况：
- ❌ GLOBAL_STATE.md 读取失败 → 记录错误，退出监控
- ❌ 子代理状态检查失败 → 记录错误，继续监控其他子代理
- ❌ 结果合并失败 → 先触发自动失败处理
Failure Recovery
错误场景 1: 子代理失败（error_count < 3）
检测: status: FAILED, error_count < 3
处理:
1. 记录到 EVENT_LOG.md（WARNING | SUBAGENT_FAILED）
2. 触发重试（harness-handle-failure）
3. error_count +1
4. 继续监控
错误场景 2: 子代理失败 3 次（error_count >= 3）
检测: status: FAILED, error_count >= 3
处理:
1. 记录到 EVENT_LOG.md（ERROR | SUBAGENT_FAILED_3_TIMES）
2. 触发熔断与自动失败处理
3. 移除 active_subagents
4. 退出监控
错误场景 3: 子代理超时
检测: 运行时间超过 estimated_completion（默认 30 分钟）
处理:
1. 记录到 EVENT_LOG.md（WARNING | SUBAGENT_TIMEOUT）
2. 先触发 harness-handle-failure；仅真实阻塞时升级人工介入
错误场景 4: 结果合并失败
检测: harness-merge-agent-results 返回错误
处理:
1. 记录到 EVENT_LOG.md（ERROR | MERGE_FAILED）
2. 触发 harness-handle-failure
Relationships
Triggers (触发下游)
子代理完成:
- 触发 harness-merge-agent-results（合并结果）
子代理失败:
- 触发 harness-handle-failure（默认）
- 仅真实阻塞时触发 harness-escalate-to-human
所有子代理完成:
- 返回主会话（继续选择下一批功能）
Triggered By (被谁触发)
触发时机:
- harness-schedule-parallel-agents 完成后
- 用户显式调用："监控子代理状态"
Dependencies (前置依赖)
必须依赖:
- harness-schedule-parallel-agents（子代理生成）
- harness-merge-agent-results（结果合并）
Token 消耗分析
单次轮询（3个子代理）:
- Read GLOBAL_STATE.md: ~200 tokens
- 增量式状态摘要: ~150 tokens（3 * 50 tokens）
- 处理状态: ~100 tokens
- 输出报告: ~200 tokens
总计: ~650 tokens
每小时轮询（30秒间隔）:
- 轮询次数: 120 次
- Token 消耗: 650 * 120 = 78,000 tokens
性能对比:
- v1.0（5秒间隔，完整 STATUS.md）: 360,000 tokens/小时
- v2.0（30秒间隔，增量式摘要）: 78,000 tokens/小时
- 性能提升: 降低 78% ✅
Examples
示例 1: 批量监控子代理（标准场景）
输入:
active_subagents: [FEAT-001, FEAT-002, FEAT-003]
子代理状态:
- FEAT-001: COMPLETED, clean_state: true
- FEAT-002: RUNNING, clean_state: false
- FEAT-003: RUNNING, clean_state: false
处理:
1. Read GLOBAL_STATE.md
2. 批量检查状态（Bash + grep）
3. 处理 FEAT-001（COMPLETED）:
- 调用 harness-merge-agent-results
- 更新 feature_list.json
- 移除 active_subagents
4. 处理 FEAT-002, FEAT-003（RUNNING）:
- 继续监控
5. 输出状态报告
6. Sleep 30 秒
7. 返回 Step 1（继续监控）
输出:
📊 子代理状态监控
总子代理数: 3
已完成: 1 (FEAT-001) ✅
运行中: 2 (FEAT-002, FEAT-003)
已处理:
- FEAT-001: 结果已合并，功能标记为完成
下一步：继续监控 FEAT-002, FEAT-003
示例 2: 子代理失败并重试
输入:
active_subagents: [FEAT-001]
子代理状态:
- FEAT-001: FAILED, error_count: 1/3
处理:
1. 检测到 FAILED 状态
2. 检查 error_count: 1（< 3）
3. 触发重试（harness-handle-failure）
4. error_count +1 → 2
5. 记录到 EVENT_LOG.md
6. 继续监控
输出:
⚠️ 子代理失败检测
功能ID: FEAT-001
失败次数: 1/3
处理: 触发重试（harness-handle-failure）
下一步：继续监控重试结果
示例 3: 所有子代理完成
输入:
active_subagents: []
所有子代理已完成
处理:
1. Read GLOBAL_STATE.md（active_subagents 为空）
2. 输出"所有子代理已完成"
3. 返回主会话
输出:
🎉 所有子代理已完成！
已完成功能数: 3
总功能数: 10
完成率: 30%
下一步：返回主会话，选择下一批功能
示例 4: 子代理失败 3 次触发熔断
输入:
active_subagents: [FEAT-001]
子代理状态:
- FEAT-001: FAILED, error_count: 3/3
处理:
1. 检测到 FAILED 状态
2. 检查 error_count: 3（>= 3）
3. 触发熔断与自动恢复
4. 记录到 EVENT_LOG.md（ERROR | SUBAGENT_FAILED_3_TIMES）
5. 移除 active_subagents
6. 退出监控
输出:
🔴 子代理失败 3 次，触发熔断
功能ID: FEAT-001
失败次数: 3/3
处理: 先触发 harness-handle-failure；真实阻塞时再升级 harness-escalate-to-human
下一步：进入自动恢复或阻塞升级流程
Implementation Notes
关键设计决策
增量式状态摘要
- 仅读取关键字段（status, clean_state）
- 使用 Bash + grep 提取
- Token 消耗降低 90%
批量合并检查
- 轮询间隔：30 秒（而非 5 秒）
- 降低轮询频率 6 倍
- Token 消耗降低 78%
失败重试机制
- 失败次数 < 3 → 自动重试
- 失败次数 >= 3 → 触发熔断
- 避免无限重试
性能优化
Token 优化:
- 增量式状态摘要: 降低 90%
- 批量合并检查: 降低 82%
- 总体 Token 优化: 降低 78%
轮询优化:
- 轮询间隔: 30 秒（而非 5 秒）
- CPU 占用: 降低 83%
- I/O 频率: 降低 83%