# Harness Monitor Agent Batch

> 主会话批量监控子代理状态（合并原 harness-monitor-subharness-agent），检测子代理完成，触发结果合并

- Skill: `konglong87/harness-monitor-agent-batch` (Agent Skill)
- Install (CLI): `npx skillmds@latest add konglong87/harness-monitor-agent-batch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-monitor-agent-batch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: konglong87 (https://skillmd.com/u/konglong87)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konglong87/harness-monitor-agent-batch

---


# 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）

```yaml
工具: Read
文件: .EnjoyHarness/GLOBAL_STATE.md
Token 消耗: ~200 tokens
目的: 获取 active_subagents 字段（运行中的子代理列表）
```

### Step 2: 批量检查子代理状态（增量式状态摘要）

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

```yaml
处理:
  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

```yaml
处理:
  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

```yaml
处理:
  1. 检查运行时间（started_at 字段）
  2. 如果超过 estimated_completion → 记录警告（可能超时）
  3. 继续监控

Token 消耗: ~100 tokens
```

### Step 4: 输出状态报告

```yaml
输出格式:
  📊 子代理状态监控
  总子代理数: 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 秒（避免频繁轮询）

```yaml
工具: Bash
命令: sleep 30
Token 消耗: ~0 tokens

性能优化:
  - 轮询间隔：30 秒（而非 5 秒）
  - 降低 Token 消耗 6 倍
  - 降低 CPU 占用
```

### Step 6: 返回 Step 1（循环监控）

```yaml
循环条件:
  - 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）

```yaml
检测: 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）

```yaml
检测: status: FAILED, error_count >= 3
处理:
1. 记录到 EVENT_LOG.md（ERROR | SUBAGENT_FAILED_3_TIMES）
2. 触发熔断与自动失败处理
3. 移除 active_subagents
4. 退出监控
```

### 错误场景 3: 子代理超时

```yaml
检测: 运行时间超过 estimated_completion（默认 30 分钟）
处理:
1. 记录到 EVENT_LOG.md（WARNING | SUBAGENT_TIMEOUT）
2. 先触发 harness-handle-failure；仅真实阻塞时升级人工介入
```

### 错误场景 4: 结果合并失败

```yaml
检测: harness-merge-agent-results 返回错误
处理:
1. 记录到 EVENT_LOG.md（ERROR | MERGE_FAILED）
2. 触发 harness-handle-failure
```

## Relationships

### Triggers (触发下游)

```yaml
子代理完成:
  - 触发 harness-merge-agent-results（合并结果）

子代理失败:
  - 触发 harness-handle-failure（默认）
  - 仅真实阻塞时触发 harness-escalate-to-human

所有子代理完成:
  - 返回主会话（继续选择下一批功能）
```

### Triggered By (被谁触发)

```yaml
触发时机:
  - harness-schedule-parallel-agents 完成后
  - 用户显式调用："监控子代理状态"
```

### Dependencies (前置依赖)

```yaml
必须依赖:
  - harness-schedule-parallel-agents（子代理生成）
  - harness-merge-agent-results（结果合并）
```

## Token 消耗分析

```yaml
单次轮询（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: 批量监控子代理（标准场景）

```yaml
输入:
  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: 子代理失败并重试

```yaml
输入:
  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: 所有子代理完成

```yaml
输入:
  active_subagents: []
  所有子代理已完成

处理:
  1. Read GLOBAL_STATE.md（active_subagents 为空）
  2. 输出"所有子代理已完成"
  3. 返回主会话

输出:
  🎉 所有子代理已完成！
  已完成功能数: 3
  总功能数: 10
  完成率: 30%

  下一步：返回主会话，选择下一批功能
```

### 示例 4: 子代理失败 3 次触发熔断

```yaml
输入:
  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 → 触发熔断
   - 避免无限重试

### 性能优化

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

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