harness-monitor-agent-batch

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），检测子代理完成，触发结果合并。

核心职责：

1. 读取 GLOBAL_STATE.md（获取 active_subagents）
2. 批量检查子代理状态（增量式状态摘要）
3. 检测子代理完成（status: COMPLETED）
4. 调用 harness-merge-agent-results 合并结果
5. 更新 feature_list.json（passes: false → true）
6. 移除已完成的子代理（active_subagents）
7. 输出状态报告
8. Sleep 30 秒（避免频繁轮询）
9. 循环监控（直到所有子代理完成）

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

成功标准：

1. ✅ 成功读取 GLOBAL_STATE.md（获取 active_subagents）
2. ✅ 成功批量检查子代理状态（增量式状态摘要）
3. ✅ 正确处理不同状态（COMPLETED/FAILED/RUNNING）
4. ✅ 成功合并已完成的子代理结果
5. ✅ 成功更新 feature_list.json 和 GLOBAL_STATE.md
6. ✅ 输出详细的状态报告

失败情况：

• ❌ 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

关键设计决策

1. 增量式状态摘要

   • 仅读取关键字段（status, clean_state）
   • 使用 Bash + grep 提取
   • Token 消耗降低 90%

2. 批量合并检查

   • 轮询间隔：30 秒（而非 5 秒）
   • 降低轮询频率 6 倍
   • Token 消耗降低 78%

3. 失败重试机制

   • 失败次数 < 3 → 自动重试
   • 失败次数 >= 3 → 触发熔断
   • 避免无限重试

性能优化

Token 优化:
  - 增量式状态摘要: 降低 90%
  - 批量合并检查: 降低 82%
  - 总体 Token 优化: 降低 78%

轮询优化:
  - 轮询间隔: 30 秒（而非 5 秒）
  - CPU 占用: 降低 83%
  - I/O 频率: 降低 83%