| name | harness-monitor-agent-batch |
| description | 主会话批量监控子代理状态(合并原 harness-monitor-subharness-agent),检测子代理完成,触发结果合并 |
| trigger_words | ["harness-monitor-agent-batch","批量监控子代理","monitor agents"] |
| priority | HIGH |
| dependencies | ["harness-schedule-parallel-agents"] |
| version | v1.0.0 |
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%