---
name: handoff
description: >
  上下文交接技能。在上下文压力达到 CRITICAL 或用户主动调用时，
  自动捕获当前会话进度、关键决策和待办事项，写入 .bookworm-progress.md，
  生成下一会话的继续提示词，并清理过期 handoff 文件。
  触发词: handoff, 交接, 保存进度, 上下文交接, context handoff, save progress
allowed-tools: Read, Glob, Grep, Bash, Write, Edit
maturity: stable
last-reviewed: 2026-04-26
---

# 上下文交接 (Handoff)

> **触发**: `/handoff` 手动调用，或 CRITICAL 上下文压力信号后模型自动调用

## 目的

在上下文即将耗尽（CRITICAL）或用户主动请求时，将当前会话的完整工作状态结构化保存到
`.bookworm-progress.md`，确保 `/clear` 后下一会话能无缝接续，零信息丢失。

## 执行流程

### Step 1: 环境探测

1. 获取当前工作目录 `cwd`
2. 检查是否为 git 仓库:
   - 是 → 执行 `git log --oneline -10` + `git diff --stat` + `git status -s` + `git branch --show-current`
   - 否 → 记录 "(非 git 仓库)"
3. 读取 `<cwd>/.bookworm-progress.md`（若存在，作为基础模板保留结构）

### Step 2: 会话摘要

回顾当前会话的全部工具调用和对话，提取以下信息:

- **本次已完成**: 会话内完成了哪些工作（简明列表，≤10 条）
- **关键决策**: 重要的技术/业务决策及原因（为什么选 A 不选 B）
- **当前阻塞**: 外部依赖、待确认项、需要用户输入的项
- **剩余待办**: 未完成的工作清单，按优先级排序

### Step 3: 更新 .bookworm-progress.md

增量更新（或创建）`<cwd>/.bookworm-progress.md`。遵循以下结构:

```
# {项目名} · 进度盘 (交接文档)

> 最后更新: {YYYY-MM-DD HH:mm}

## 当前状态

**仓库**: `{cwd}`
**分支**: `{branch}` | **HEAD**: `{short_hash}` ({N} commits, {clean/dirty})
**构建**: {最近构建状态，如有}
**公网**: {部署 URL，如有}

## 业务锁定 (永久,不可改)

{从既有文件原封不动保留。如无则留空或标 "无"}

## ✅ 全部已完成

{累积列表。合并既有 + 本次新增。按里程碑/时间分组}

## 🔲 剩余待办

{更新后的待办。已完成的标 ✅ 并移到上方。新发现的追加在此}

## 关键文件位置

{项目中重要文件/目录的速查表}

## Git 提交历史

{git log --oneline 最近 10-15 条}

## /clear 后继续提示词

​```
{自包含提示词，包含:
 - 仓库路径 + 分支 + HEAD
 - 已完成摘要（一句话）
 - 待办列表
 - 永久约束（如有）
 - 关键路径提示}
​```
```

**合并规则**:
- "业务锁定" 节绝对不可删除或修改，只能原样保留
- "已完成" 节只追加不删除
- "待办" 节可增删改
- "继续提示词" 每次重新生成

### Step 4: 清理过期 handoff

执行清理:
```bash
# 列出 ~/.claude/session-state/handoff-*.json
# 按修改时间排序，保留最新 5 个，删除其余
```

### Step 5: 完成通知

输出:

```
✅ Handoff 完成
- 进度文件: {cwd}/.bookworm-progress.md (已更新)
- 清理: 删除 {N} 个过期 handoff，保留 {M} 个
- 下一步: /clear → 粘贴「继续提示词」即可无缝接续
```

## 安全约束

- 不在 progress 文件中写入密钥、密码、Token
- 不修改 "业务锁定" 节的任何内容
- "继续提示词" 中不包含完整代码，只引用文件路径
- 清理 handoff 文件时只删除 `handoff-*.json` 时间戳格式文件，不删 `handoff.json` 主文件