# Harness Spawn Subharness Agent

> 生成子代理技能，实现完全隔离的子任务执行环境，防止上下文污染

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

---


# harness-spawn-subharness-agent 生成子代理技能

## 核心能力
1. 检查前置条件（harness-build-deterministic-workflow）
2. 创建子代理隔离目录（.subharness/{task-id}/）
3. 初始化子代理文件（SUBTASK_MANIFEST.md, CONTEXT_INDEX.md, STATUS.md）
4. 创建 Git worktree 隔离环境
5. 注册子代理到全局状态

## 前置条件
- harness-build-deterministic-workflow 已完成
- WORKFLOW_TEMPLATES.md 存在

## 执行步骤

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

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

检查条件：
- harness-build-deterministic-workflow 已标记为完成

如果未完成：
```
❌ 错误: 工作流未构建
💡 请先运行: harness-build-deterministic-workflow
```

### Step 2: 生成任务ID

使用 Bash 工具生成唯一任务ID：

```bash
TASK_TYPE="feature"  # 或 "fix" / "refactor" / "docs"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
TASK_ID="${TASK_TYPE}-${TIMESTAMP}"
echo "任务ID: ${TASK_ID}"
```

### Step 3: 创建子代理目录

使用 Bash 工具创建目录：

```bash
mkdir -p .subharness/${TASK_ID}
mkdir -p .subharness/${TASK_ID}/WORK_TREE

echo "✅ 子代理目录创建完成: .subharness/${TASK_ID}"
```

### Step 4: 创建 SUBTASK_MANIFEST.md

使用 Write 工具创建文件：`.subharness/${TASK_ID}/SUBTASK_MANIFEST.md`

内容：

```markdown
---
task_id: {TASK_ID}
parent_task: none
created_at: {TIMESTAMP}
status: pending
priority: MEDIUM
---

# SubTask Manifest

## 任务信息
- 任务ID: {TASK_ID}
- 父任务: 无（根任务）
- 创建时间: {TIMESTAMP}
- 状态: 待执行
- 优先级: 中等

## 任务描述
{任务描述占位符}

## 技能调用链
{待填充}

## 依赖关系
- 上游依赖: 无
- 下游触发: 无

## 成功标准
- [ ] 任务完成
- [ ] 测试通过
- [ ] 输出校验通过

## 失败兜底
- 失败次数 ≥ 3次 → 触发熔断
- 超时 ≥ 30分钟 → 终止执行
```

### Step 5: 创建 CONTEXT_INDEX.md

使用 Write 工具创建文件：`.subharness/${TASK_ID}/CONTEXT_INDEX.md`

内容：

```markdown
---
task_id: {TASK_ID}
context_priority: P1
loaded_at: null
---

# SubTask Context Index

## 上下文加载策略

### P0级（必需）
- [ ] SUBTASK_MANIFEST.md（本文件）
- [ ] AGENTS_MANIFEST.md（核心规则）
- [ ] ARCHITECTURE_GUARDRAILS.md（架构约束）

### P1级（按任务类型）
- [ ] WORKFLOW_TEMPLATES.md（工作流模板）
- [ ] TOOLSET_SPEC.md（工具配置）

### P2级（按需）
- [ ] ERROR_HANDBOOK.md（错误处理）
- [ ] 相关代码文件

## 上下文隔离规则
1. **禁止访问**: 其他子代理的上下文
2. **仅访问**: 本任务相关文件 + 全局规则
3. **写入限制**: 仅写入本任务目录

## Token预算
- 最大Token: 5000 tokens
- 当前使用: 0 tokens
```

### Step 6: 创建 STATUS.md

使用 Write 工具创建文件：`.subharness/${TASK_ID}/STATUS.md`

内容：

```markdown
---
task_id: {TASK_ID}
status: pending
started_at: null
completed_at: null
iteration_count: 0
error_count: 0
---

# SubTask Status

## 执行状态
- 状态: 待执行
- 开始时间: 未开始
- 完成时间: 未完成
- 迭代次数: 0
- 错误次数: 0

## 执行进度
- [ ] 初始化完成
- [ ] 工作流开始
- [ ] 节点执行中
- [ ] 结果验证
- [ ] 任务完成

## 事件记录
等待第一个事件...

## Token消耗
- 已使用: 0 tokens
- 剩余: 5000 tokens
- 占比: 0%

## 错误记录
无错误
```

### Step 7: 创建 Git Worktree（可选）

如果需要完全隔离的 Git 环境：

```bash
# 创建新分支
git checkout -b subtask/${TASK_ID}

# 创建 worktree
git worktree add .subharness/${TASK_ID}/WORK_TREE subtask/${TASK_ID}

echo "✅ Git worktree 创建完成"
```

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

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

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

在 `active_subagents` 列表中添加：

```yaml
active_subagents:
  - task_id: {TASK_ID}
    status: pending
    created_at: {TIMESTAMP}
```

### Step 9: 更新事件日志

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

追加内容：

```markdown
{TIMESTAMP} | SUBAGENT_SPAWN | harness-spawn-subharness-agent | 生成子代理 {TASK_ID} | SUCCESS
```

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

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

old_string: `total_events: N`
new_string: `total_events: N+1`

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

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

old_string: `- [ ] harness-spawn-subharness-agent - 生成子代理技能`
new_string: `- [x] harness-spawn-subharness-agent - 生成子代理技能 ✅`

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

使用 Bash 工具输出：

```bash
echo ""
echo "✅ harness-spawn-subharness-agent 完成!"
echo ""
echo "📋 子代理信息:"
echo "  - 任务ID: ${TASK_ID}"
echo "  - 目录: .subharness/${TASK_ID}"
echo "  - 状态: 待执行"
echo ""
echo "📂 文件创建:"
echo "  - SUBTASK_MANIFEST.md（任务规则）"
echo "  - CONTEXT_INDEX.md（上下文索引）"
echo "  - STATUS.md（状态追踪）"
echo "  - WORK_TREE/（Git worktree）"
echo ""
echo "🔒 隔离机制:"
echo "  - 文件系统隔离: ✅"
echo "  - Git worktree隔离: ✅"
echo "  - Token预算隔离: 5000 tokens"
echo ""
echo "🎯 下一步:"
echo "  运行 harness-monitor-subharness-agent 开始监控子代理"
echo ""
```

## 成功标准
- [ ] 子代理目录创建完成
- [ ] SUBTASK_MANIFEST.md 文件存在
- [ ] CONTEXT_INDEX.md 文件存在
- [ ] STATUS.md 文件存在
- [ ] Git worktree 创建成功（可选）
- [ ] 全局状态已更新
- [ ] 技能注册表已更新

## 失败兜底
- harness-build-deterministic-workflow 未完成 → 终止执行，提示运行前置技能
- 目录创建失败 → 记录错误到 EVENT_LOG.md，触发重试
- Git worktree 创建失败 → 跳过 worktree，仅使用目录隔离

## 联动关系
- 前置: harness-build-deterministic-workflow
- 自动触发: harness-monitor-subharness-agent

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

## 测试用例

### 测试 1: 前置条件检查
**输入**: 在工作流未构建时运行
**期望输出**: 错误提示"工作流未构建"
**验证方式**: 删除 WORKFLOW_TEMPLATES.md 后运行

### 测试 2: 目录创建
**输入**: 执行 harness-spawn-subharness-agent
**期望输出**: .subharness/{task-id}/ 目录存在
**验证方式**: `ls -la .subharness/`

### 测试 3: 文件完整性
**输入**: 检查子代理目录
**期望输出**: 包含 SUBTASK_MANIFEST.md, CONTEXT_INDEX.md, STATUS.md
**验证方式**: `ls .subharness/{task-id}/`

### 测试 4: 全局状态更新
**输入**: 读取 GLOBAL_STATE.md
**期望输出**: active_subagents 包含新生成的任务ID
**验证方式**: `grep "{TASK_ID}" .EnjoyHarness/GLOBAL_STATE.md`

### 测试 5: 技能注册表更新
**输入**: 读取 SKILL_REGISTRY.md
**期望输出**: harness-spawn-subharness-agent 标记为完成
**验证方式**: `grep "harness-spawn-subharness-agent" .EnjoyHarness/SKILL_REGISTRY.md`

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

## 子代理隔离机制

### 隔离层级

#### 层级 1: 文件系统隔离
- 独立目录: `.subharness/{task-id}/`
- 独立文件: MANIFEST, CONTEXT, STATUS
- 写入限制: 仅本目录

#### 层级 2: Git Worktree 隔离
- 独立分支: `subtask/{task-id}`
- 独立 worktree: `.subharness/{task-id}/WORK_TREE`
- 提交隔离: 不影响主分支

#### 层级 3: Token 预算隔离
- 独立预算: 5000 tokens/子代理
- 独立计数: 不影响全局迭代计数
- 超限处理: 终止子代理，触发熔断

#### 层级 4: 上下文隔离
- 仅加载必要上下文（P0 + P1）
- 禁止访问其他子代理上下文
- 防止上下文污染

### 隔离优势

1. **防止上下文污染**: 每个子代理独立上下文，避免干扰
2. **并行执行**: 多个子代理可并行执行不同任务
3. **故障隔离**: 单个子代理失败不影响其他子代理
4. **Token控制**: 每个子代理独立Token预算，防止超限
5. **易于调试**: 每个子代理有独立的执行日志和状态

## 使用示例

### 示例 1: 生成功能开发子代理
```bash
# 任务类型: feature
# 任务ID: feature-20260328-110000
# 目录: .subharness/feature-20260328-110000/
# 状态: pending
# Token预算: 5000 tokens
```

### 示例 2: 生成Bug修复子代理
```bash
# 任务类型: fix
# 任务ID: fix-20260328-110500
# 目录: .subharness/fix-20260328-110500/
# 状态: pending
# Token预算: 5000 tokens
```

### 示例 3: 并行执行多个子代理
```yaml
子代理1: feature-20260328-110000 (用户登录功能)
子代理2: fix-20260328-110500 (修复注册Bug)
子代理3: refactor-20260328-111000 (优化数据库查询)

并行执行: 3个子代理同时运行
隔离机制: 完全隔离，互不干扰
```