bookworm-smart-assistant/skills/handoff/SKILL.md

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

执行清理:

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

Step 5: 完成通知

输出:

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

安全约束

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