Harness Merge Agent Results

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 的完整性
• 防止合并不完整的结果
• 确保清洁状态达标

2. Git merge 安全

• 检测冲突时先触发自动失败处理与冲突诊断
• 避免自动解决冲突（可能引入错误）
• 保留冲突现场，等待自动恢复或真实阻塞升级链路处理

3. 清理策略

• 清理失败不阻塞流程
• 记录警告并进入自动清理队列
• 确保核心流程（合并 + 更新）完成

4. JSON 格式验证

• 每次修改 feature_list.json 前验证
• 防止 Agent 误修改其他字段
• 确保 JSON 格式正确

性能优化

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

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

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