harness-monitor-subharness-agent

name	harness-monitor-subharness-agent
description	监控子代理状态技能，实时追踪子代理执行进度、Token消耗、错误计数，支持熔断触发
trigger_words	["harness-monitor-subharness-agent","监控子代理","monitor-subagent","子代理状态"]
priority	HIGH
dependencies	["harness-spawn-subharness-agent"]
version	v3.0.0

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: 错误计数熔断

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

条件2: Token超限熔断

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

条件3: 执行超时熔断

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

3.3 更新子代理状态

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

如果触发熔断：

## 执行状态
- 状态: CIRCUIT_BREAKER_TRIGGERED / TOKEN_LIMIT_EXCEEDED / TIMEOUT_EXCEEDED
- 完成时间: {当前时间}

3.4 记录监控事件

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

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

Step 4: 生成监控报告

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

内容：

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

更新子代理状态列表：

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 工具输出：

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: 执行进度

节点完成率 = 已完成节点数 / 总节点数
示例: 5/10节点完成 → 50%进度
状态: IN_PROGRESS

指标 2: Token消耗

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

指标 3: 错误计数

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

指标 4: 执行时长

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

监控策略

策略 1: 轮询监控

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

策略 2: 事件驱动监控

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

策略 3: 定点监控

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

使用示例

示例 1: 监控单个子代理

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

示例 2: 监控多个子代理

子代理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: 触发熔断处理

子代理: 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

协作示例

阶段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的超限）