# Harness Merge Agent Results

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

- Skill: `konglong87/harness-merge-agent-results` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add konglong87/harness-merge-agent-results`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-merge-agent-results/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-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 子代理结果文件

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

### Step 2: 验证结果完整性

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

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

Token 消耗: ~100 tokens
```

### Step 3: 合并代码到主分支（如适用）

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

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

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

### Step 5: 更新 EVENT_LOG.md

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

Token 消耗: ~100 tokens
```

### Step 6: 更新 GLOBAL_STATE.md

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

Token 消耗: ~50 tokens
```

### Step 7: 清理子代理目录（可选）

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

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

### Step 8: 输出合并报告

```yaml
输出格式:
🎉 子代理结果合并完成
功能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: 结果文件不存在

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

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

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

### 错误场景 3: Git merge 冲突

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

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

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

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

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

## Relationships

### Triggers (触发下游)

```yaml
合并成功:
- 触发 harness-track-feature-progress（标记完成，选择下一个功能）

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

### Triggered By (被谁触发)

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

### Dependencies (前置依赖)

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

## Token 消耗分析

```yaml
单个子代理合并:
- 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: 成功合并子代理结果

```yaml
输入:
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 冲突

```yaml
输入:
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: 结果验证失败

```yaml
输入:
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: 清理子代理目录失败

```yaml
输入:
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 格式正确

### 性能优化

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

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

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