120 lines
3.5 KiB
Markdown
120 lines
3.5 KiB
Markdown
|
---
|
|||
|
|
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` 主文件
|