# Context Handoff

> 对话上下文交接与资产化管理。当用户需要压缩当前对话上下文、切换到新对话继续、或加载之前的交接文档时触发。触发关键词："/handoff"、"交接"、"上下文压缩"、"压缩上下文"、"切换对话"、"恢复上下文"。

- Skill: `newyounghe-design/context-handoff` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add newyounghe-design/context-handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/newyounghe-design/context-handoff/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: newyounghe-design (https://skillmd.com/u/newyounghe-design)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/newyounghe-design/context-handoff

---


# 对话上下文交接操作手册

当用户触发此 skill 时，根据子命令执行对应操作。

---

## ⚙️ 配置（使用前请确认路径）

| 配置项 | 当前值 | 说明 |
|--------|--------|------|
| 交接文档根目录 | `/Users/shakely2020/Documents/obsidian笔记库/Claude-Workspace/Conversation-Handoff/` | 交接文档保存位置 |
| Daily-Log 根目录 | `/Users/shakely2020/Documents/obsidian笔记库/Claude-Workspace/Daily-Logs/` | 工作日志位置 |
| 快速恢复文件 | `~/.claude/last_handoff.txt` | 记录最近一次交接文档路径 |

> **分享给他人时**：请修改上述路径为目标系统的实际路径

---

## 命令一览

| 命令 | 功能 | 示例 |
|------|------|------|
| `/handoff` | 生成当前对话的交接文档 | `/handoff` |
| `/handoff resume` | 快速恢复最近一次交接 | `/handoff resume` |
| `/handoff load <文件名或关键词>` | 加载指定交接文档恢复上下文 | `/handoff load context-handoff设计` |
| `/handoff list` | 列出最近的交接文档 | `/handoff list` |
| `/handoff list <关键词>` | 按关键词搜索交接文档 | `/handoff list 音频` |

---

## 何时使用

以下情况建议运行 `/handoff`：

1. **对话变长时**：当你感觉对话已经很长，或者 Claude 开始「忘记」之前讨论的内容
2. **任务中断时**：需要暂停当前任务，稍后继续
3. **切换话题前**：当前任务告一段落，准备开始新话题
4. **主动存档**：重要决策达成后，想保留完整记录

---

## 操作流程

### `/handoff` — 生成交接文档

#### Step 1：信息提取

从当前对话中提取以下信息（如有缺失，向用户确认）：

1. **任务主题**：一句话概括本次对话的核心任务
2. **当前状态**：进行中 / 已完成 / 已暂停 / 遇阻
3. **已完成步骤**：按时间顺序列出关键里程碑
4. **待办事项**：尚未完成的任务（标记优先级）
5. **当前阻塞项**：卡住的原因、等待什么
6. **尝试记录**：走通的路径、确认的死路、暂时搁置的方案
7. **关键决策**：重要的技术/方案选择及其理由
8. **被否决的方案**：讨论过但没采用的方案及原因
9. **沟通共识**：用户偏好、约定的术语、沟通风格
10. **相关文件**：本次对话涉及的文件路径
11. **标签**：便于后续搜索的关键词

#### Step 2：确认环节（防误触发）

**版本号自动检测**：在确认前，先搜索 `Conversation-Handoff/` 目录，检查是否存在同主题的历史交接文档（按主题关键词匹配文件名）。如果找到，自动建议递增版本号。

展示提取的关键点，让用户确认或补充：

```
检测到交接请求，我提取了以下关键点：

📋 任务主题：{主题}
📊 当前状态：{状态}

✅ 已完成：
1. {步骤1}
2. {步骤2}

⏳ 待办：
- 🔴 {高优先级}
- 🟡 {中优先级}
- 🟢 {低优先级}

🛑 当前阻塞项：
- {阻塞项1}：{原因/等待什么}

🔬 尝试记录：
- ✅ 走通：{方法A} → {为什么能走通}
- ❌ 死路：{方法B} → {失败原因}
- ⏸️ 搁置：{方法C} → {卡在哪里}

🎯 关键决策：
1. {决策1}：选择了 X 方案，因为...

❌ 被否决的方案：
- {方案A}：因为...

🤝 沟通共识：
- {偏好1}
- {偏好2}

📂 建议文件名：{YYYY-MM-DD}_{主题简称}_v{N}.md
   ⚠️ 检测到同主题历史版本：{历史文件名}，已自动递增版本号
   （如无历史版本则不显示此行）

---
确认生成交接文档吗？有遗漏可以补充，文件名也可以修改。
```

**用户确认后才正式生成并保存。**

#### Step 3：生成交接文档

按以下模板生成 Markdown 文件：

```markdown
---
date: {YYYY-MM-DD}
time: {HH:MM}
topic: {任务主题}
status: {进行中|已完成|已暂停|遇阻}
tags: [handoff, {相关标签}]
related_checkpoint: {如有关联的 _checkpoint.md 任务，填写任务名}
previous_handoff: {前序交接文档文件名，如无则留空}
---

# 对话交接：{任务主题}

## 📋 任务概览
- **开始时间**: {首次讨论时间}
- **交接时间**: {当前时间}
- **状态**: {状态}
- **关联检查点**: {如有}
- **前序交接**: [[{如有}]]

---

<ai_context>
## ⏳ 待办事项

### 高优先级 🔴
- [ ] {任务描述}

### 中优先级 🟡
- [ ] {任务描述}

### 低优先级 🟢
- [ ] {任务描述}

---

## 🛑 当前阻塞项

- **{阻塞项1}**: {原因/等待什么}
- **{阻塞项2}**: {原因/等待什么}

---

## 🔬 尝试记录

### ✅ 走通的路径
| 方法 | 结果 | 关键点 |
|------|------|--------|
| {方法A} | 成功 | {为什么能走通、关键配置} |

### ❌ 确认的死路
| 方法 | 失败原因 | 报错/现象 | 为什么是死路 |
|------|----------|-----------|--------------|
| {方法B} | {原因} | {具体报错信息} | {不可行的根本原因} |

### ⏸️ 暂时搁置（可能有戏）
| 方法 | 当前状态 | 卡在哪里 | 后续可尝试 |
|------|----------|----------|------------|
| {方法C} | 部分成功 | {卡点} | {下次可以试的方向} |

---

## 🎯 关键决策

### 决策 1：{决策标题}
- **背景**: {为什么需要做这个决策}
- **选项**:
  - A: {方案A描述}
  - B: {方案B描述}
- **选择**: {最终选择}
- **理由**: {为什么选择这个方案}
- **影响**: {这个决策对后续工作的影响}

---

## ❌ 被否决的方案

### {方案名称}
- **描述**: {方案内容}
- **否决原因**: {为什么没采用}

---

## 🤝 沟通共识

### 用户偏好
- {偏好1}
- {偏好2}

### 约定术语
| 术语 | 含义 |
|------|------|
| {术语1} | {解释} |

### 注意事项
- ⚠️ {注意事项1}
- ⚠️ {注意事项2}

---

## ✅ 已完成步骤

1. **{步骤标题}** — {简要说明}
   - 关键产出：{文件/结果}
2. **{步骤标题}** — {简要说明}
   - 关键产出：{文件/结果}
</ai_context>

---

## 📜 对话历程

### {YYYY-MM-DD}
- [{HH:MM}] {关键节点描述}
  > 用户原话：「{重要讨论原文引用}」
- [{HH:MM}] {关键节点描述}
  > 关键讨论：{讨论要点}

---

## 📁 相关文件

| 文件路径 | 类型 | 说明 |
|---------|------|------|
| `{绝对路径1}` | {代码/文档/配置} | {说明} |

---

## 🔗 关联链接

- **今日日志**: [[Daily-Logs/2026/{月份}/{日期}.md]]
- **检查点**: [[_checkpoint.md]]
- **前序交接**: [[{前序文件名}]]

---

## 💡 恢复提示

新对话开始时，请先阅读此文档，然后告诉我：
1. 关于阻塞项 {X}，现在有进展了吗？
2. 你想从哪个待办事项继续？
3. 有什么新的想法或变更？

---
**创建时间**: {YYYY-MM-DD HH:MM}
**文档版本**: v{N}
```

#### Step 4：保存文件

**文件命名规范**：`{YYYY-MM-DD}_{主题简称}_v{版本号}.md`

示例：
- `2026-03-10_context-handoff设计_v1.md`
- `2026-03-10_音频排障_v1.md`

**保存路径**：`/Users/shakely2020/Documents/obsidian笔记库/Claude-Workspace/Conversation-Handoff/{YYYY}/{MM-Month}/`

示例：`Claude-Workspace/Conversation-Handoff/2026/03-March/2026-03-10_context-handoff设计_v1.md`

**版本管理**：同一主题的多次交接，版本号递增，不覆盖旧版本。

#### Step 5：更新 Daily-Log

在当天的 Daily-Log（路径：`obsidian笔记库/Claude-Workspace/Daily-Logs/2026/{月份}/{日期}.md`）中添加交接记录：

```markdown
### [{HH:MM}] 对话交接：{主题}
**问题/任务**: 压缩当前对话上下文，生成交接文档
**交接文档**: [[Conversation-Handoff/2026/{月份}/{文件名}]]
**状态**: {进行中|已完成|已暂停|遇阻}
**待办摘要**:
- 🔴 {高优先级待办1}
- 🟡 {中优先级待办1}
**阻塞项**: {如有}
**标签**: #handoff #{主题标签}
**结果**: ✅ 交接文档已生成
```

#### Step 6：输出确认

向用户展示：
1. 交接文档已保存的路径
2. 关键待办事项摘要
3. 恢复指令（独立代码块，方便复制）

**同时写入快速恢复文件**：将完整文件路径写入 `~/.claude/last_handoff.txt`，供 `/handoff resume` 使用。

输出格式：

```
✅ 交接文档已生成！

📂 保存路径：`{完整文件路径}`
🔖 快速恢复：下次新对话直接输入 `/handoff resume` 即可

⏳ 待办摘要：
- 🔴 {高优先级}
- 🟡 {中优先级}

---
📋 **手动恢复指令**（复制下方内容，粘贴到新对话即可）：
```

然后输出一个**独立的代码块**，只包含恢复指令文本：

```
请读取 /Users/shakely2020/Documents/obsidian笔记库/Claude-Workspace/Conversation-Handoff/2026/03-March/{实际文件名}.md 恢复上下文，然后告诉我摘要和待办。
```

**重要**：
- 代码块内必须是完整绝对路径，填入实际值
- 不要用 `{变量}` 占位符
- 注：pbcopy 在沙盒环境中无法访问系统剪贴板，所以改用代码块输出

---

### `/handoff resume` — 快速恢复最近交接

读取 `~/.claude/last_handoff.txt` 获取最近一次交接文档路径，然后执行与 `/handoff load` 相同的恢复流程。

如果文件不存在或为空，提示用户：
```
未找到最近的交接记录。请使用 `/handoff list` 查看可用的交接文档，或使用 `/handoff load <关键词>` 加载指定文档。
```

---

### `/handoff load <文件名或关键词>` — 加载交接文档

#### Step 1：定位文件

搜索路径：`Claude-Workspace/Conversation-Handoff/`

支持的输入格式：
- 完整文件名：`2026-03-10_context-handoff设计_v1.md`
- 不带扩展名：`2026-03-10_context-handoff设计_v1`
- 主题关键词：`context-handoff` → 自动匹配最新版本

#### Step 2：读取并解析

读取交接文档，**优先解析 `<ai_context>` 标签内的内容**：
- 待办事项
- 当前阻塞项
- 尝试记录（走通的路径、死路、搁置的方案）
- 关键决策
- 沟通共识

#### Step 3：上下文恢复

向用户报告：
```
已加载交接文档：{文件名}

📋 任务：{任务主题}
📊 状态：{状态}

🛑 上次的阻塞项：
- {阻塞项1}：{原因}

🔬 尝试记录：
- ✅ 走通：{方法A}
- ❌ 死路：{方法B}（别再试了）
- ⏸️ 搁置：{方法C}（可以再试）

⏳ 待办事项：
- 🔴 {高优先级}
- 🟡 {中优先级}

🎯 上次的关键决策：
- {决策1简述}

📁 相关文件已定位：
- {文件1}
- {文件2}

---
关于上次卡住的「{阻塞项1}」，现在有进展了吗？
```

#### Step 4：更新 Daily-Log

在当天日志中记录恢复事件：
```markdown
### [{HH:MM}] 恢复对话上下文
**问题/任务**: 从交接文档恢复上下文，继续之前的工作
**来源文档**: [[Conversation-Handoff/2026/{月份}/{文件名}]]
**任务**: {任务主题}
**恢复状态**: {状态}
**标签**: #handoff #context-restore #{主题标签}
**结果**: ✅ 上下文已恢复
```

---

### `/handoff list` — 列出交接文档

#### 无参数：列出最近 10 个

搜索 `Claude-Workspace/Conversation-Handoff/` 目录，按修改时间倒序列出。

输出格式：
```
最近的交接文档：

| 日期 | 主题 | 状态 | 版本 |
|------|------|------|------|
| 2026-03-10 | context-handoff设计 | 进行中 | v2 |
| 2026-03-09 | 音频排障 | 已完成 | v1 |
...

使用 `/handoff load <文件名>` 加载指定文档
```

#### 带关键词：搜索匹配

在文件名和内容中搜索关键词，返回匹配的文档列表。

---

## 与现有系统的协调

| 系统 | 定位 | 关系 |
|------|------|------|
| `_checkpoint.md` | 单一任务进度追踪 | 交接文档可引用，互补不冲突 |
| Daily-Log | 按天记录工作流水账 | 双向记录 + 对话历程同步 |
| auto-memory | 跨会话精简记忆 | 交接文档是详细版，memory 是精简版 |

**协调规则**：
- 如果当前对话涉及 `_checkpoint.md` 中的任务，交接文档中添加 `related_checkpoint` 字段
- 交接文档不替代 `_checkpoint.md`，两者互补

---

## 核心原则

### 细节保留原则

**压缩目的是「快速恢复沟通状态」，不是「缩短文档长度」**

保留优先级：
1. 决策的完整推理链（不只是结论）
2. 讨论过但被否决的方案（避免重复踩坑）
3. 用户表达过的偏好和顾虑
4. 未成文的口头约定
5. 关键对话片段直接引用，不做二次概括

### AI 专属解析标签

- 核心信息（待办、阻塞项、决策、共识）用 `<ai_context>` 标签包裹
- `/handoff load` 时优先解析这部分，减少 token 消耗
- 人类阅读时标签不影响 Obsidian 渲染

---

## 目录结构

```
Claude-Workspace/
└── Conversation-Handoff/
    └── {YYYY}/
        └── {MM-Month}/
            └── {YYYY-MM-DD}_{主题简称}_v{N}.md
```

示例：
```
Conversation-Handoff/
└── 2026/
    └── 03-March/
        ├── 2026-03-08_婚礼照片分拣_v1.md
        ├── 2026-03-10_婚礼照片分拣_v2.md
        └── 2026-03-09_音频排障_v1.md
```