harness-session-handoff

name	harness-session-handoff
description	自动会话交接机制，在完成N个任务后创建交接文件并通过 tmux 会话接力，防止上下文超载
trigger_words	["session handoff","会话交接","自动切换会话","prevent context overflow"]
priority	HIGHEST
dependencies	["harness-auto-full-execution"]
version	v1.0.0

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）
• 任务执行过程中自动检测
• 无需用户手动干预

配置参数

# 环境变量配置
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: 检查是否达到切换阈值

# 计算是否需要切换会话
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

提取剩余任务：

- [ ] 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

交接提示词模板：

---
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

内容：

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

Step 7: 记录交接事件

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

事件记录：

{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 工具输出：

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秒）

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

完整流程图

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 工具返回错误

处理：

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

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

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

处理：

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

失败场景3: GLOBAL_STATE损坏

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

处理：

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

与守护进程的协作

守护进程监控流程

# 守护进程每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中集成

在任务执行循环中添加：

# 每完成一个任务后检查
{TIMESTAMP} | TRIGGER_DOWNSTREAM | harness-session-handoff | 检查会话切换 | PENDING

方式2: 独立skill自动触发

在GLOBAL_STATE.md中添加触发条件：

session_handoff:
  enabled: true
  tasks_per_session: 2
  auto_trigger: true

方式3: Hook集成

在CLAUDE.md中添加：

## 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