# Harness Session Handoff

> 自动会话交接机制，在完成N个任务后创建交接文件并通过 tmux 会话接力，防止上下文超载

- Skill: `konglong87/harness-session-handoff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add konglong87/harness-session-handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-session-handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: konglong87 (https://skillmd.com/u/konglong87)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konglong87/harness-session-handoff

---


# harness-session-handoff 自动会话交接技能

## 核心能力

1. **任务计数监控**：实时监控已完成的任务数量
2. **交接文件生成**：在达到阈值（默认2个任务）时自动生成详细的交接提示词
3. **会话状态保存**：将剩余任务清单、上下文摘要、重要决策保存到交接文件
4. **新会话触发**：创建NEXT_SESSION_PROMPT.md，触发守护进程通过 tmux 启动新会话
5. **ACK 确认**：新会话写入 HANDOFF_ACK.md，旧会话确认后才退出
6. **失败恢复**：如交接失败，先记录到ERROR_HANDBOOK.md并尝试自动恢复，仅真实阻塞时再人工升级

## 触发条件

- 每完成N个任务（默认N=2）
- 任务执行过程中自动检测
- 无需用户手动干预

## 配置参数

```bash
# 环境变量配置
TASKS_PER_SESSION=2  # 每N个任务切换会话（默认2）
NEXT_PROMPT_FILE=".EnjoyHarness/NEXT_SESSION_PROMPT.md"
GLOBAL_STATE=".EnjoyHarness/GLOBAL_STATE.md"
TMUX_SESSION_STATE=".EnjoyHarness/TMUX_SESSION_STATE.md"
HANDOFF_ACK=".EnjoyHarness/HANDOFF_ACK.md"
HANDOFF_LOCK=".EnjoyHarness/HANDOFF_LOCK.md"
ERROR_HANDBOOK=".EnjoyHarness/ERROR_HANDBOOK.md"
TMUX_SESSION_PREFIX="eh-loop"
TMUX_ACK_TIMEOUT_SECONDS=60
```

## 执行步骤

### Step 1: 读取当前任务状态

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

提取信息：
- 已完成任务数量：`completed_tasks`
- 剩余任务列表：`pending_tasks`
- 当前执行阶段：`current_phase`
- 项目目标：`project_goal`

### Step 2: 检查是否达到切换阈值

```bash
# 计算是否需要切换会话
COMPLETED=$(grep -c "status: completed" .EnjoyHarness/GLOBAL_STATE.md)
THRESHOLD=${TASKS_PER_SESSION:-2}

if [ $COMPLETED -ge $THRESHOLD ]; then
    echo "已达到切换阈值：$COMPLETED >= $THRESHOLD"
    # 触发会话交接
fi
```

### Step 3: 生成剩余任务清单

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

提取剩余任务：
```markdown
- [ ] Task-051: 实现用户认证模块 (P0)
- [ ] Task-052: 编写API文档 (P1)
- [ ] Task-053: 单元测试 (P0)
...
```

### Step 4: 提取上下文摘要

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

提取关键信息：
- 重要决策
- 技术方案选择
- 风险识别
- 依赖关系

### Step 5: 生成详细交接提示词

使用 Write 工具创建：`.EnjoyHarness/NEXT_SESSION_PROMPT.md`

交接提示词模板：

```markdown
---
created: {TIMESTAMP}
previous_session: {SESSION_ID}
completed_tasks: {COMPLETED_COUNT}
remaining_tasks: {REMAINING_COUNT}
---

# 会话续接提示

我们正在为 {PROJECT_NAME} 项目执行 {PROJECT_GOAL}。

## 背景信息

**已完成工作**：
- 已完成任务数：{COMPLETED_COUNT}
- 已完成阶段：{COMPLETED_PHASES}
- 关键成果：{KEY_DELIVERABLES}

**当前进度**：
- 剩余任务数：{REMAINING_COUNT}
- 当前进度：{PROGRESS_PERCENTAGE}%
- 预计剩余时间：{ESTIMATED_TIME}

## 本次会话目标

**质量第一原则**：宁可慢，不可乱。优先保证代码质量和系统稳定性，不追求速度而牺牲质量。

继续执行剩余的 {REMAINING_COUNT} 个任务，从 Task-{NEXT_TASK_ID} 开始，确保每个任务都经过充分测试和验证。

## 接手要求

1. 先读取 `.EnjoyHarness/GLOBAL_STATE.md`、`.EnjoyHarness/EVENT_LOG.md` 和 `.EnjoyHarness/TMUX_SESSION_STATE.md`
2. 确认当前 tmux session 与交接单一致
3. 在 `.EnjoyHarness/HANDOFF_ACK.md` 中写入 `status: accepted`
4. 如果状态不一致或提示过期，写入 `status: failed`，记录错误并先尝试自动恢复

## 剩余任务清单

### P0 优先级（必须完成）
1. **Task-{ID}**: {TITLE}
   - 描述：{DESCRIPTION}
   - 状态：pending
   - 依赖：{DEPENDENCIES}

2. **Task-{ID}**: {TITLE}
   ...

### P1 优先级（重要）
...

### P2 优先级（可选）
...

## 上下文摘要

### 重要决策
1. {DECISION_1}
2. {DECISION_2}
3. ...

### 技术方案
- 架构选择：{ARCHITECTURE_CHOICE}
- 技术栈：{TECH_STACK}
- 关键依赖：{KEY_DEPENDENCIES}

### 已识别风险
1. {RISK_1} - {MITIGATION}
2. {RISK_2} - {MITIGATION}

### 会话健康状态
- Token 使用率估算：{TOKEN_USAGE}%
- 任务复杂度平均值：{AVG_COMPLEXITY}/10
- 错误率：{ERROR_RATE}%
- 累计任务数：{TOTAL_TASKS}

### 性能指标
- 平均任务完成时间：{AVG_TASK_TIME}分钟
- 代码质量评分：{CODE_QUALITY_SCORE}/10
- 测试覆盖率：{TEST_COVERAGE}%

### 环境信息
- 工作目录：{WORK_DIR}
- Git 分支：{GIT_BRANCH}
- 最新提交：{LAST_COMMIT}
- 系统平台：{PLATFORM}

## 启动指令

**请你首先**：
1. 读取全局状态文件：`.EnjoyHarness/GLOBAL_STATE.md`
2. 阅读设计文档：`docs/plans/{DESIGN_DOC}.md`
3. 阅读实施计划：`docs/plans/{IMPLEMENTATION_PLAN}.md`
4. 创建任务清单（使用 TaskCreate 工具）
5. 从 Task-{NEXT_TASK_ID} 开始实施

**详细实施步骤见实施计划文档第 {CHAPTER} 章"实施路线图"**

请先阅读相关文档，然后告诉我你准备好继续实施了！

---

## 详细实施指南

我已经为你准备了：
1. ✅ 剩余任务完整清单（上面列出）
2. ✅ 上下文摘要（重要决策、技术方案、风险）
3. ✅ 启动指令（清晰的第一步）
4. ✅ 参考文档路径

## 预期产出

完成后你应该有以下文件：
- {EXPECTED_FILE_1}
- {EXPECTED_FILE_2}
- ...
```

### Step 6: 创建交接文件

使用 Write 工具写入：`.EnjoyHarness/NEXT_SESSION_PROMPT.md`

内容：上述模板填充后的完整交接提示词

### Step 6.5: 创建 ACK 占位文件

使用 Write 工具创建：`.EnjoyHarness/HANDOFF_ACK.md`

内容：

```markdown
---
created_at: {TIMESTAMP}
status: pending
session_name: null
session_pid: null
tmux_session: null
acknowledged_at: null
---
```

### Step 7: 记录交接事件

使用 Edit 工具写入：`.EnjoyHarness/EVENT_LOG.md`

事件记录：
```markdown
{TIMESTAMP} | SESSION_HANDOFF | harness-session-handoff | 达到任务阈值，创建交接文件 | SUCCESS
{TIMESTAMP} | SESSION_HANDOFF | harness-session-handoff | 已完成任务：{COMPLETED_COUNT} | INFO
{TIMESTAMP} | SESSION_HANDOFF | harness-session-handoff | 剩余任务：{REMAINING_COUNT} | INFO
{TIMESTAMP} | SESSION_HANDOFF | harness-session-handoff | 交接文件已创建：NEXT_SESSION_PROMPT.md | SUCCESS
```

### Step 7.5: 记录 tmux 交接锁

使用 Write 工具创建：`.EnjoyHarness/HANDOFF_LOCK.md`

内容：锁定当前交接周期，防止重复拉起多个 tmux session。

### Step 8: 输出交接信息

使用 Bash 工具输出：

```bash
echo ""
echo "🔄 会话交接触发"
echo ""
echo "📊 当前状态:"
echo " - 已完成任务：{COMPLETED_COUNT}"
echo " - 剩余任务：{REMAINING_COUNT}"
echo " - 当前进度：{PROGRESS}%"
echo ""
echo "📝 交接文件已创建:"
echo " - 文件：.EnjoyHarness/NEXT_SESSION_PROMPT.md"
echo " - 大小：{SIZE} 字节"
echo ""
echo "⏳ 等待守护进程启动新会话..."
echo ""
echo "新会话将继续执行 Task-{NEXT_TASK_ID} 及后续任务。"
echo ""
```

### Step 9: 结束当前会话

等待守护进程检测到交接文件并启动新会话（约5-10秒）

当前会话自然结束，所有状态已保存。

## 完整流程图

```dot
digraph session_handoff {
    rankdir=TB;

    "执行任务" [shape=box, style=filled, fillcolor="#c8e6c9"];
    "任务完成" [shape=box];
    "检查任务计数" [shape=diamond, style=filled, fillcolor="#bbdefb"];
    "继续执行" [shape=box, style=filled, fillcolor="#fff9c4"];
    "读取GLOBAL_STATE" [shape=box, style=filled, fillcolor="#f8bbd0"];
    "提取剩余任务" [shape=box, style=filled, fillcolor="#f8bbd0"];
    "生成上下文摘要" [shape=box, style=filled, fillcolor="#f8bbd0"];
    "创建交接文件" [shape=box, style=filled, fillcolor="#e1bee7"];
    "记录事件日志" [shape=box, style=filled, fillcolor="#e1bee7"];
    "守护进程检测" [shape=diamond, style=filled, fillcolor="#ffccbc"];
    "启动新会话" [shape=box, style=filled, fillcolor="#81c784"];
    "当前会话结束" [shape=doublecircle, style=filled, fillcolor="#81c784"];

    "执行任务" -> "任务完成";
    "任务完成" -> "检查任务计数";
    "检查任务计数" -> "继续执行" [label="< 阈值"];
    "继续执行" -> "执行任务";
    "检查任务计数" -> "读取GLOBAL_STATE" [label=">= 阈值"];
    "读取GLOBAL_STATE" -> "提取剩余任务";
    "提取剩余任务" -> "生成上下文摘要";
    "生成上下文摘要" -> "创建交接文件";
    "创建交接文件" -> "记录事件日志";
    "记录事件日志" -> "守护进程检测";
    "守护进程检测" -> "启动新会话" [label="检测到交接文件"];
    "启动新会话" -> "当前会话结束";
}
```

## 失败处理

### 失败场景1: 交接文件创建失败

检测：Write 工具返回错误

处理：
```markdown
使用 Edit 工具写入 ERROR_HANDBOOK.md：
{TIMESTAMP} | ERROR | harness-session-handoff | 交接文件创建失败 | FAILURE
原因：{ERROR_MESSAGE}
建议：检查文件权限，手动创建交接文件
```

### 失败场景2: 守护进程未运行

检测：等待10秒后未启动新会话

处理：
```bash
echo "⚠️ 守护进程未检测到交接文件"
echo ""
echo "手动启动守护进程："
echo "  ./scripts/start-daemon.sh"
echo ""
echo "或手动启动新会话："
echo "  tmux-handoff-manager.sh launch"
echo ""
```

### 失败场景3: GLOBAL_STATE损坏

检测：Read GLOBAL_STATE.md 失败或数据不完整

处理：
```markdown
使用 Edit 工具写入 ERROR_HANDBOOK.md：
{TIMESTAMP} | ERROR | harness-session-handoff | GLOBAL_STATE文件损坏 | FAILURE
建议：检查GLOBAL_STATE.md格式，或从备份恢复
```

## 与守护进程的协作

### 守护进程监控流程

```bash
# 守护进程每5秒检查一次
while true; do
    sleep 5
    if [ -f ".EnjoyHarness/NEXT_SESSION_PROMPT.md" ]; then
        # 读取交接文件
        # 通过 tmux 启动新会话
        # 等待 HANDOFF_ACK.md
        # ACK 后再归档交接文件
    fi
done
```

### 文件约定

- **交接文件**：`.EnjoyHarness/NEXT_SESSION_PROMPT.md`
- **ACK 文件**：`.EnjoyHarness/HANDOFF_ACK.md`
- **交接锁**：`.EnjoyHarness/HANDOFF_LOCK.md`
- **tmux 状态**：`.EnjoyHarness/TMUX_SESSION_STATE.md`
- **会话PID**：`.EnjoyHarness/SESSION_PID`
- **守护进程PID**：`.EnjoyHarness/DAEMON_PID`
- **错误记录**：`.EnjoyHarness/ERROR_HANDBOOK.md`

## 成功标准

- [ ] 任务计数达到阈值时自动触发
- [ ] 成功读取GLOBAL_STATE.md
- [ ] 成功提取剩余任务清单
- [ ] 成功生成详细交接提示词
- [ ] 成功创建NEXT_SESSION_PROMPT.md
- [ ] 成功记录EVENT_LOG.md
- [ ] 守护进程成功检测并启动新会话
- [ ] 新会话能够继续执行剩余任务

## 集成方式

### 方式1: 在harness-auto-full-execution中集成

在任务执行循环中添加：
```markdown
# 每完成一个任务后检查
{TIMESTAMP} | TRIGGER_DOWNSTREAM | harness-session-handoff | 检查会话切换 | PENDING
```

### 方式2: 独立skill自动触发

在GLOBAL_STATE.md中添加触发条件：
```markdown
session_handoff:
  enabled: true
  tasks_per_session: 2
  auto_trigger: true
```

### 方式3: Hook集成

在CLAUDE.md中添加：
```markdown
## Hooks
- on_task_complete: trigger harness-session-handoff
```

## 使用示例

### 示例：P0任务执行中的会话交接

**当前状态**：
- 已完成：Task-001, Task-002（共2个任务）
- 剩余：Task-003 到 Task-100（共98个任务）
- 进度：2%

**触发交接**：
```
检测到已完成任务数：2 >= 阈值：2
创建交接文件...

✅ NEXT_SESSION_PROMPT.md 已创建

剩余任务清单：
- Task-003: 实现用户认证API (P0)
- Task-004: 编写认证测试 (P0)
- ...

守护进程将在5秒内通过 tmux 启动新会话...
```

**新会话启动**：
```
新会话ID：S1235
启动时间：2026-03-29T01:00:00+08:00
继续执行：Task-003

新会话写入 ACK 后，开始实施...
```

## 配置建议

### 任务阈值选择

| 场景 | 建议阈值 | 理由 |
|------|---------|------|
| **快速测试** | N=2 | 快速验证交接流程 |
| **正常执行** | N=10 | 平衡上下文和交接频率 |
| **大型项目** | N=50 | 避免频繁交接 |
| **简单任务** | N=20 | 任务简单，可多执行 |
| **复杂任务** | N=5 | 任务复杂，上下文增长快 |

### 交接文件大小控制

- 剩余任务清单：建议≤100行
- 上下文摘要：建议≤50行
- 总文件大小：建议≤10KB

如果超过限制：
- 仅保留P0/P1任务详情
- P2+任务仅列出标题
- 上下文摘要仅保留关键决策

## 注意事项

1. **自动触发**：无需用户手动干预，完全自动
2. **状态完整**：确保新会话能够无缝接续
3. **失败恢复**：失败时记录到ERROR_HANDBOOK.md
4. **守护进程依赖**：需要守护进程运行才能自动启动新会话
5. **文件清理**：交接完成后归档 NEXT_SESSION_PROMPT.md，不直接删除

## 迭代计数

本技能执行预计迭代次数：约 10-15 次
- Read GLOBAL_STATE：1次
- Read EVENT_LOG：1次
- Write NEXT_SESSION_PROMPT：1次
- Edit EVENT_LOG：1次
- Bash输出：1次

## 参考

- Shell守护进程实现：`scripts/harness-daemon.sh`
- tmux 交接协议管理器：`scripts/tmux-handoff-manager.sh`
- tmux 会话启动器：`scripts/tmux-session-bootstrap.sh`
- 守护进程启动脚本：`scripts/start-daemon.sh`
- tmux 交接设计文档：`docs/plans/2026-03-31-tmux-claude-loop-handoff-design.md`