Context handoff skill

对话上下文交接操作手册

当用户触发此 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 文件：

---
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）中添加交接记录：

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

在当天日志中记录恢复事件：

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