# Harness Monitor Subharness Agent

> 监控子代理状态技能，实时追踪子代理执行进度、Token消耗、错误计数，支持熔断触发

- Skill: `konglong87/harness-monitor-subharness-agent` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add konglong87/harness-monitor-subharness-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-monitor-subharness-agent/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-subharness-agent

---


# harness-monitor-subharness-agent 监控子代理技能

## 核心能力
1. 检查前置条件（harness-spawn-subharness-agent）
2. 读取子代理状态文件（STATUS.md）
3. 监控执行进度（节点完成情况）
4. 追踪Token消耗（实时计数）
5. 记录错误计数（失败次数）
6. 触发熔断机制（超限自动停止）

## 前置条件
- harness-spawn-subharness-agent 已完成
- 子代理目录存在（.subharness/{task-id}/）

## 执行步骤

### Step 1: 检查前置条件

使用 Read 工具读取：`.EnjoyHarness/SKILL_REGISTRY.md`

检查条件：
- harness-spawn-subharness-agent 已标记为完成

如果未完成：
```
❌ 错误: 子代理未生成
💡 请先运行: harness-spawn-subharness-agent
```

### Step 2: 获取活跃子代理列表

使用 Read 工具读取：`.EnjoyHarness/GLOBAL_STATE.md`

提取 `active_subagents` 列表。

如果没有活跃子代理：
```
⚠️ 警告: 无活跃子代理
💡 请先运行: harness-spawn-subharness-agent
```

### Step 3: 遍历监控每个子代理

对于每个子代理 `{task-id}`：

#### 3.1 读取子代理状态

使用 Read 工具读取：`.subharness/{task-id}/STATUS.md`

提取关键信息：
- 状态（status）
- 迭代次数（iteration_count）
- 错误次数（error_count）
- Token消耗（已使用/剩余）

#### 3.2 检查熔断条件

**条件1: 错误计数熔断**
```yaml
检查: error_count ≥ 3
动作: 标记状态为 CIRCUIT_BREAKER_TRIGGERED
输出: "⚠️ 子代理 {task-id} 错误次数达到上限（3次），触发熔断"
```

**条件2: Token超限熔断**
```yaml
检查: 已使用Token > 5000
动作: 标记状态为 TOKEN_LIMIT_EXCEEDED
输出: "⚠️ 子代理 {task-id} Token超限（>5000 tokens），终止执行"
```

**条件3: 执行超时熔断**
```yaml
检查: 执行时长 > 30分钟
动作: 标记状态为 TIMEOUT_EXCEEDED
输出: "⚠️ 子代理 {task-id} 执行超时（>30分钟），终止执行"
```

#### 3.3 更新子代理状态

使用 Edit 工具更新：`.subharness/{task-id}/STATUS.md`

如果触发熔断：
```markdown
## 执行状态
- 状态: CIRCUIT_BREAKER_TRIGGERED / TOKEN_LIMIT_EXCEEDED / TIMEOUT_EXCEEDED
- 完成时间: {当前时间}
```

#### 3.4 记录监控事件

使用 Edit 工具追加内容到：`.EnjoyHarness/EVENT_LOG.md`

```markdown
{当前时间} | SUBAGENT_MONITOR | harness-monitor-subharness-agent | 监控子代理 {task-id}: {状态} | {SUCCESS/WARNING}
```

### Step 4: 生成监控报告

使用 Write 工具创建文件：`.EnjoyHarness/SUBAGENT_MONITOR_REPORT.md`

内容：

```markdown
---
generated_at: {当前时间}
total_subagents: {总数}
active: {活跃数}
completed: {完成数}
failed: {失败数}
---

# SubAgent Monitor Report

## 总体状态
- 监控时间: {当前时间}
- 子代理总数: {总数}
- 活跃中: {活跃数}
- 已完成: {完成数}
- 已失败: {失败数}

## 子代理详情

### 子代理: {task-id-1}
- 状态: {status}
- 迭代次数: {iteration_count}
- 错误次数: {error_count}
- Token消耗: {已使用} / 5000 tokens ({占比}%)
- 执行时长: {时长}分钟
- 健康状态: ✅ 正常 / ⚠️ 警告 / ❌ 异常

### 子代理: {task-id-2}
...

## 熔断触发情况
- 错误熔断: {数量}个子代理
- Token熔断: {数量}个子代理
- 超时熔断: {数量}个子代理

## 建议操作
- {具体建议，如"子代理xxx进入自动恢复流程"或"继续执行"}
```

### Step 5: 更新全局状态

使用 Edit 工具更新：`.EnjoyHarness/GLOBAL_STATE.md`

更新子代理状态列表：
```yaml
active_subagents:
- task_id: {task-id-1}
  status: {status}
  health: {healthy/warning/error}
- task_id: {task-id-2}
  ...
```

### Step 6: 更新事件计数

使用 Edit 工具更新：`.EnjoyHarness/EVENT_LOG.md`

old_string: `total_events: N`
new_string: `total_events: N+{监控事件数}`

### Step 7: 更新技能注册表

使用 Edit 工具更新：`.EnjoyHarness/SKILL_REGISTRY.md`

old_string: `- [ ] harness-monitor-subharness-agent - 监控子代理技能`
new_string: `- [x] harness-monitor-subharness-agent - 监控子代理技能 ✅`

### Step 8: 输出完成信息

使用 Bash 工具输出：

```bash
echo ""
echo "✅ harness-monitor-subharness-agent 完成!"
echo ""
echo "📊 监控报告:"
echo " - 子代理总数: {总数}"
echo " - 活跃中: {活跃数}"
echo " - 已完成: {完成数}"
echo " - 已失败: {失败数}"
echo ""
echo "📋 详细报告: .EnjoyHarness/SUBAGENT_MONITOR_REPORT.md"
echo ""
echo "🔒 熔断情况:"
echo " - 错误熔断: {数量}个"
echo " - Token熔断: {数量}个"
echo " - 超时熔断: {数量}个"
echo ""
echo "🎯 下一步:"
echo " - 正常: 继续执行子代理"
echo " - 异常: 运行 harness-handle-failure 处理失败"
echo ""
```

## 成功标准
- [ ] 读取所有活跃子代理状态
- [ ] 检查熔断条件（错误/Token/超时）
- [ ] 生成监控报告
- [ ] 更新全局状态
- [ ] 更新事件日志
- [ ] 技能注册表已更新

## 失败兜底
- harness-spawn-subharness-agent 未完成 → 终止执行，提示运行前置技能
- 无活跃子代理 → 输出警告，退出执行
- 子代理状态文件损坏 → 记录错误，跳过该子代理

## 联动关系
- 前置: harness-spawn-subharness-agent
- 正常触发: harness-merge-subharness-result（所有子代理完成）
- 异常触发: harness-handle-failure（触发熔断）

## 迭代计数
本技能执行预计迭代次数: 约 6 次（Read 2次 + Write 1次 + Edit 3次）

## 测试用例

### 测试 1: 前置条件检查
**输入**: 在子代理未生成时运行
**期望输出**: 错误提示"子代理未生成"
**验证方式**: 删除子代理目录后运行

### 测试 2: 状态读取
**输入**: 执行监控技能
**期望输出**: 成功读取 STATUS.md 文件
**验证方式**: 检查监控报告中包含子代理状态

### 测试 3: 熔断检测（错误计数）
**输入**: 子代理 error_count ≥ 3
**期望输出**: 触发错误熔断，状态标记为 CIRCUIT_BREAKER_TRIGGERED
**验证方式**: 手动设置 error_count=3 后运行

### 测试 4: 熔断检测（Token超限）
**输入**: 子代理已使用Token > 5000
**期望输出**: 触发Token熔断，状态标记为 TOKEN_LIMIT_EXCEEDED
**验证方式**: 手动设置 Token=5500 后运行

### 测试 5: 熔断检测（执行超时）
**输入**: 子代理执行时长 > 30分钟
**期望输出**: 触发超时熔断，状态标记为 TIMEOUT_EXCEEDED
**验证方式**: 手动修改 started_at 时间为31分钟前

### 测试 6: 监控报告生成
**输入**: 运行监控技能
**期望输出**: 生成 SUBAGENT_MONITOR_REPORT.md 文件
**验证方式**: `ls .EnjoyHarness/SUBAGENT_MONITOR_REPORT.md`

### 测试 7: 全局状态更新
**输入**: 读取 GLOBAL_STATE.md
**期望输出**: active_subagents 包含最新的状态信息
**验证方式**: `grep "health" .EnjoyHarness/GLOBAL_STATE.md`

### 测试 8: 事件日志记录
**输入**: 读取 EVENT_LOG.md
**期望输出**: 包含 SUBAGENT_MONITOR 事件
**验证方式**: `grep "SUBAGENT_MONITOR" .EnjoyHarness/EVENT_LOG.md`

## 监控指标详解

### 指标 1: 执行进度
```yaml
节点完成率 = 已完成节点数 / 总节点数
示例: 5/10节点完成 → 50%进度
状态: IN_PROGRESS
```

### 指标 2: Token消耗
```yaml
Token消耗率 = 已使用Token / 5000
示例: 2000/5000 → 40%消耗
健康状态:
- < 70%: ✅ 正常
- 70-90%: ⚠️ 警告
- > 90%: ❌ 危险
```

### 指标 3: 错误计数
```yaml
错误率 = error_count / 3
示例: 2/3 → 67%错误率
健康状态:
- 0次: ✅ 健康
- 1-2次: ⚠️ 警告
- ≥3次: ❌ 触发熔断
```

### 指标 4: 执行时长
```yaml
时长占比 = 执行时长 / 30分钟
示例: 15分钟 → 50%时长
健康状态:
- < 20分钟: ✅ 正常
- 20-25分钟: ⚠️ 警告
- > 25分钟: ⚠️ 即将超时
- > 30分钟: ❌ 触发熔断
```

## 监控策略

### 策略 1: 轮询监控
```yaml
频率: 每5分钟监控一次
触发条件: 子代理状态为 IN_PROGRESS
动作: Read STATUS.md → 检查熔断 → 更新报告
```

### 策略 2: 事件驱动监控
```yaml
触发条件: 子代理写入事件到 EVENT_LOG.md
动作: Read EVENT_LOG → 检测到完成/失败事件 → 立即监控
```

### 策略 3: 定点监控
```yaml
触发条件: 子代理到达关键节点（如测试运行前）
动作: Read STATUS.md → 检查健康状态 → 决定是否继续
```

## 使用示例

### 示例 1: 监控单个子代理
```yaml
子代理: feature-20260328-110000
状态: IN_PROGRESS
进度: 5/10节点完成（50%）
Token: 2000/5000（40%）
错误: 0次
时长: 10分钟
健康状态: ✅ 正常
建议: 继续执行
```

### 示例 2: 监控多个子代理
```yaml
子代理1: feature-20260328-110000
状态: IN_PROGRESS
健康状态: ✅ 正常

子代理2: fix-20260328-110500
状态: COMPLETED
健康状态: ✅ 完成

子代理3: refactor-20260328-111000
状态: CIRCUIT_BREAKER_TRIGGERED
健康状态: ❌ 错误次数≥3

监控结果: 1个正常，1个完成，1个异常
建议: 对子代理3运行 harness-handle-failure
```

### 示例 3: 触发熔断处理
```yaml
子代理: feature-20260328-110000
错误计数: 3次
触发熔断: ✅

自动动作:
1. 标记状态: CIRCUIT_BREAKER_TRIGGERED
2. 记录事件: EVENT_LOG.md
3. 触发技能: harness-handle-failure
  4. 输出警告: "子代理错误次数达到上限，进入自动失败处理"
```

## 与其他技能的协作

### 协作流程
```
harness-spawn-subharness-agent（生成子代理）
↓
harness-monitor-subharness-agent（监控子代理）
↓
判断:
- 正常 → 继续执行
- 完成 → harness-merge-subharness-result
- 异常 → harness-handle-failure
```

### 协作示例
```yaml
阶段1: 生成子代理
- harness-spawn-subharness-agent → 生成子代理A和B

阶段2: 监控子代理
- harness-monitor-subharness-agent → 监控A和B的执行状态

阶段3a: 正常完成
- A完成 → harness-merge-subharness-result（合并A的结果）
- B完成 → harness-merge-subharness-result（合并B的结果）

阶段3b: 异常处理
- A错误≥3次 → harness-handle-failure（处理A的失败）
- B Token超限 → harness-handle-failure（处理B的超限）
```