agentleFS
konglong87konglong87/enjoy_harness_ai/skills/harness-merge-agent-results/SKILL.md

harness-merge-agent-results

Skill0 starsChanged 8 months agoMITView on GitHub

合并子代理结果到主项目,更新功能清单,清理子代理目录

  • Deletes or force-pushes

The file

Files
SKILL.md

harness-merge-agent-results

Core Capabilities

合并子代理结果到主项目,更新 feature_list.json,清理子代理目录。

核心职责:

  1. 读取子代理结果文件(RESULT.md)
  2. 验证结果完整性(功能完成 + 测试通过 + 清洁状态)
  3. 合并代码到主分支(如适用)
  4. 更新 feature_list.json(passes: false → true)
  5. 更新 EVENT_LOG.md(FEATURE_COMPLETE 事件)
  6. 清理子代理目录(可选)
  7. 移除 GLOBAL_STATE.md 的 active_subagents 条目
  8. 冲突时默认先尝试自动合并或自动失败处理,仅真实阻塞时升级人工介入

Execution Steps

Step 1: Read 子代理结果文件

工具: Read
文件: .subharness/{feature-id}/RESULT.md
Token 消耗: ~200 tokens
失败处理:
- 如果文件不存在 → 记录错误,触发自动失败处理
- 如果文件损坏 → 记录错误,触发自动失败处理

Step 2: 验证结果完整性

验证项:
1. 功能开发完成(RESULT.md 包含 "功能开发完成" 标记)
2. 测试通过(RESULT.md 包含 "测试通过" 标记)
3. 清洁状态检查通过(RESULT.md 包含 "清洁状态: CLEAN" 标记)

处理逻辑:
- 所有验证项通过 → 继续执行
- 任一验证项失败 → 记录错误,触发自动失败处理

Token 消耗: ~100 tokens

Step 3: 合并代码到主分支(如适用)

工具: Bash
命令: git merge {feature-branch}
前置检查:
- 检查是否有 Git worktree(.subharness/{feature-id}/WORK_TREE)
- 检查是否有未提交更改

Token 消耗: ~500 tokens
失败处理:
- 如果 Git merge 冲突 → 记录到 EVENT_LOG.md,先尝试自动冲突处理
- 如果合并失败 → 记录错误,触发自动失败处理;仅真实阻塞时升级人工介入

Step 4: 更新 feature_list.json

工具: Read + Edit
文件: .EnjoyHarness/feature_list.json
修改字段: passes: false → true(对应功能)
验证:
- 使用 Python jsonschema 验证 JSON 格式
- 确保仅修改 passes 字段

Token 消耗: ~100 tokens
失败处理:
- 如果 JSON 格式错误 → 记录错误,拒绝写入
- 如果功能ID不存在 → 记录错误,退出执行

Step 5: 更新 EVENT_LOG.md

工具: Edit
文件: .EnjoyHarness/EVENT_LOG.md
追加内容:
- 时间戳:2026-03-28T14:00:00
- 事件类型:FEATURE_COMPLETE
- 功能ID:{feature-id}
- 合并状态:成功/失败
- 清理状态:已清理/未清理

Token 消耗: ~100 tokens

Step 6: 更新 GLOBAL_STATE.md

工具: Edit
文件: .EnjoyHarness/GLOBAL_STATE.md
修改字段: active_subagents: [FEAT-001, FEAT-002] → [FEAT-002](移除已完成的子代理)

Token 消耗: ~50 tokens

Step 7: 清理子代理目录(可选)

工具: Bash
命令: rm -rf .subharness/{feature-id}
前置确认:
- 功能已标记为完成(feature_list.json passes: true)
- EVENT_LOG.md 已更新
- GLOBAL_STATE.md 已更新

Token 消耗: ~50 tokens
失败处理:
- 如果清理失败 → 记录警告,继续执行(不阻塞流程)
- 记录待清理项并交给后续自动清理链路

Step 8: 输出合并报告

输出格式:
🎉 子代理结果合并完成
功能ID: {feature-id}
功能描述: {description}
合并状态: 成功
清理状态: 已清理

更新文件:
- feature_list.json (passes: true)
- EVENT_LOG.md (FEATURE_COMPLETE)
- GLOBAL_STATE.md (active_subagents 已移除)

下一步: 继续监控其他子代理

Token 消耗: ~200 tokens

Prerequisites

必须满足:

  • ✅ 子代理状态为 COMPLETED
  • ✅ 子代理清洁状态为 true
  • ✅ 子代理结果文件存在(RESULT.md)
  • ✅ GLOBAL_STATE.md 的 active_subagents 包含该功能ID

如果前置条件不满足:

  • 如果子代理未完成 → 等待子代理完成
  • 如果结果文件不存在 → 触发自动失败处理;仅真实阻塞时升级

Success Criteria

成功标准:

  1. ✅ 成功读取并验证子代理结果文件
  2. ✅ 成功合并代码到主分支(如适用)
  3. ✅ 成功更新 feature_list.json(passes: true)
  4. ✅ 成功更新 EVENT_LOG.md(FEATURE_COMPLETE 事件)
  5. ✅ 成功更新 GLOBAL_STATE.md(移除 active_subagents)
  6. ✅ 成功清理子代理目录(可选)
  7. ✅ 输出详细的合并报告

失败情况:

  • ❌ 结果文件不存在或损坏 → 触发自动失败处理
  • ❌ 结果验证失败 → 触发自动失败处理
  • ❌ Git merge 冲突且自动处理失败 → 触发真实阻塞升级
  • ❌ JSON 格式验证失败 → 记录错误,拒绝写入

Failure Recovery

错误场景 1: 结果文件不存在

检测: Read 失败
处理:
1. 记录到 EVENT_LOG.md(ERROR | RESULT_FILE_NOT_FOUND)
2. 触发 harness-handle-failure
3. 退出执行

错误场景 2: 结果验证失败

检测: RESULT.md 缺少必要标记(功能完成、测试通过、清洁状态)
处理:
1. 记录到 EVENT_LOG.md(ERROR | RESULT_VALIDATION_FAILED)
2. 列出缺失的验证项
3. 触发 harness-handle-failure
4. 退出执行

错误场景 3: Git merge 冲突

检测: git merge 返回冲突
处理:
1. 记录到 EVENT_LOG.md(ERROR | GIT_MERGE_CONFLICT)
2. 输出冲突文件列表
3. 触发 harness-handle-failure 或自动冲突修复
4. 仅在真实阻塞时升级 harness-escalate-to-human

错误场景 4: JSON 格式验证失败

检测: Python jsonschema 验证失败
处理:
1. 记录到 EVENT_LOG.md(ERROR | JSON_VALIDATION_FAILED)
2. 输出验证错误详情
3. 拒绝写入 feature_list.json
4. 触发 harness-handle-failure

错误场景 5: 清理子代理目录失败

检测: rm -rf 返回错误
处理:
1. 记录到 EVENT_LOG.md(WARNING | CLEANUP_FAILED)
2. 记录到自动清理待办列表
3. 继续执行(不阻塞流程)

Relationships

Triggers (触发下游)

合并成功:
- 触发 harness-track-feature-progress(标记完成,选择下一个功能)

合并失败:
  - 先触发 harness-handle-failure
  - 仅真实阻塞时触发 harness-escalate-to-human

Triggered By (被谁触发)

触发时机:
- harness-monitor-agent-batch 检测到子代理完成(status: COMPLETED, clean_state: true)
- 用户显式调用:"合并子代理结果 {feature-id}"

Dependencies (前置依赖)

必须依赖:
- harness-monitor-agent-batch(子代理完成检测)
- harness-handle-failure(默认失败处理)
- harness-escalate-to-human(真实阻塞升级)

Token 消耗分析

单个子代理合并:
- Read RESULT.md: ~200 tokens
- 验证结果: ~100 tokens
- Git merge: ~500 tokens
- 更新 feature_list.json: ~100 tokens
- 更新 EVENT_LOG.md: ~100 tokens
- 更新 GLOBAL_STATE.md: ~50 tokens
- 清理子代理目录: ~50 tokens
- 输出报告: ~200 tokens
总计: ~1300 tokens

批量合并(3个子代理):
- 顺序执行: 3 * 1300 = 3900 tokens
- 优化空间: 可批量更新文件,降低重复读写

性能对比:
- v1.0(手动合并): ~5000 tokens per 子代理
- v2.0(自动合并): ~1300 tokens per 子代理
- 性能提升: 降低 74% ✅

Examples

示例 1: 成功合并子代理结果

输入:
feature_id: FEAT-001
子代理状态: COMPLETED
清洁状态: true
RESULT.md:
  - 功能开发完成: ✅
  - 测试通过: ✅
  - 清洁状态: CLEAN ✅

处理:
1. Read .subharness/FEAT-001/RESULT.md
2. 验证结果完整性(全部通过)
3. Git merge FEAT-001-branch → 成功
4. Edit feature_list.json(FEAT-001 passes: false → true)
5. Edit EVENT_LOG.md(FEATURE_COMPLETE | FEAT-001)
6. Edit GLOBAL_STATE.md(active_subagents: [FEAT-002, FEAT-003])
7. Bash rm -rf .subharness/FEAT-001
8. 输出合并报告

输出:
🎉 子代理结果合并完成
功能ID: FEAT-001
功能描述: 实现用户注册接口
合并状态: 成功
清理状态: 已清理

更新文件:
- feature_list.json (passes: true)
- EVENT_LOG.md (FEATURE_COMPLETE)
- GLOBAL_STATE.md (active_subagents 已移除)

下一步: 继续监控 FEAT-002, FEAT-003

示例 2: Git merge 冲突

输入:
feature_id: FEAT-002
子代理状态: COMPLETED
清洁状态: true
Git merge 冲突: 有

处理:
1. Read .subharness/FEAT-002/RESULT.md
2. 验证结果完整性(通过)
3. Git merge FEAT-002-branch → 冲突
4. 记录到 EVENT_LOG.md(ERROR | GIT_MERGE_CONFLICT)
5. 输出冲突文件列表
6. 先触发 harness-handle-failure;仅真实阻塞时再升级 harness-escalate-to-human

输出:
⚠️ Git merge 冲突
功能ID: FEAT-002
冲突文件:
- src/api/auth/login.go
- src/api/auth/register.go

处理: 进入自动冲突恢复;仅真实阻塞时升级 harness-escalate-to-human
下一步: 自动尝试冲突诊断、回滚或重新调度

示例 3: 结果验证失败

输入:
feature_id: FEAT-003
子代理状态: COMPLETED
清洁状态: false
RESULT.md:
  - 功能开发完成: ✅
  - 测试通过: ❌(测试失败)
  - 清洁状态: NOT_CLEAN ❌

处理:
1. Read .subharness/FEAT-003/RESULT.md
2. 验证结果完整性(失败)
3. 列出缺失的验证项:
   - 测试通过: ❌
   - 清洁状态: ❌
4. 记录到 EVENT_LOG.md(ERROR | RESULT_VALIDATION_FAILED)
5. 触发 harness-handle-failure;真实阻塞时再升级

输出:
❌ 结果验证失败
功能ID: FEAT-003
缺失验证项:
- 测试通过: ❌
- 清洁状态: ❌

处理: 先触发 harness-handle-failure;真实阻塞时再升级 harness-escalate-to-human
下一步: 进入自动恢复或阻塞升级流程

示例 4: 清理子代理目录失败

输入:
feature_id: FEAT-001
合并状态: 成功
清理状态: 失败(权限问题)

处理:
1. Read .subharness/FEAT-001/RESULT.md ✅
2. 验证结果完整性 ✅
3. Git merge FEAT-001-branch ✅
4. 更新 feature_list.json ✅
5. 更新 EVENT_LOG.md ✅
6. 更新 GLOBAL_STATE.md ✅
7. Bash rm -rf .subharness/FEAT-001 ❌(权限被拒绝)
8. 记录到 EVENT_LOG.md(WARNING | CLEANUP_FAILED)
9. 记录自动清理待办项

输出:
⚠️ 清理子代理目录失败
功能ID: FEAT-001
错误: 权限被拒绝

提示: 请手动清理子代理目录:
rm -rf .subharness/FEAT-001

合并状态: 部分成功(代码已合并,目录未清理)

Implementation Notes

关键设计决策

  1. 结果验证机制
  • 强制验证 RESULT.md 的完整性
  • 防止合并不完整的结果
  • 确保清洁状态达标
  1. Git merge 安全
  • 检测冲突时先触发自动失败处理与冲突诊断
  • 避免自动解决冲突(可能引入错误)
  • 保留冲突现场,等待自动恢复或真实阻塞升级链路处理
  1. 清理策略
  • 清理失败不阻塞流程
  • 记录警告并进入自动清理队列
  • 确保核心流程(合并 + 更新)完成
  1. JSON 格式验证
  • 每次修改 feature_list.json 前验证
  • 防止 Agent 误修改其他字段
  • 确保 JSON 格式正确

性能优化

Token 优化:
- 批量更新文件(减少重复读取)
- 增量式更新 GLOBAL_STATE.md(仅修改 active_subagents)
- 使用 Bash rm -rf(而非逐文件删除)

执行优化:
- 顺序合并(避免并发冲突)
- 清理失败不阻塞(继续执行)
- 错误快速响应(先触发自动失败处理)

总体优化:
- Token 降低 74%(相比手动合并)
- 执行时长缩短 50%(自动化流程)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.