# Context Handoff

> 上下文迁移/任务交接技能。当对话上下文将满或已满（提示"达到输出token上限"、输出被截断、用户说"交接一下/上下文满了/换新对话/续命/保存进度"）时，把当前工作区状态与待办任务保存为交接文档，并生成"新对话引导消息"，让任务在上下文重新计算后无缝继续。适用于任何工作区，核心原则：产物全部落文件、交接文档用几百 token 压缩摘要替代几万 token 历史、绝不读取旧 session 文件。

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

---


# 上下文迁移 · 任务交接（context-handoff）

> 解决"上下文满 → 任务怎么办"的通用方案。
> **窗口不变、历史不删、上下文清零重算、记忆靠文件交接。**

## 何时使用

- 提示"已达到输出 token 上限"、回答被截断
- 用户说：交接一下 / 上下文满了 / 换新对话继续 / 续命 / 保存进度 / 开新对话
- 感觉上下文将满（长任务进行到后半段）
- 后台任务在跑、需要跨会话延续（如数据下载）

## 核心机制（先讲清楚，执行才不走偏）

| 概念 | 事实 |
|------|------|
| 对话窗口 | 同一个，不换（DSH 在原窗口续命=开新 session） |
| 旧对话记录 | 磁盘 session 文件永久保留，可回看，**不占新上下文** |
| 新 session 上下文 | 从 0 token 重新计算 |
| 新 session 的记忆 | **空白**——必须靠交接文档恢复 |
| 后台任务 | 照常跑，归属旧 session；新 session 用 job_list / 日志文件确认状态 |
| 禁忌 | **绝不读旧 session.jsonl.zstd**（几万条消息会瞬间撑爆新上下文） |

## 工作流（5 步）

```
1. 保存交接文档 → 写 <工作区>/docs/任务交接-新对话引导.md（模板见下）
2. 汇报后台任务 → job_list + 日志 tail，说明哪些在跑、归属哪个会话
3. 生成引导消息 → 按模板生成可复制粘贴的一段话（含文档路径+优先任务）
4. 交还给用户   → 用户在新对话/原窗口续命时粘贴引导消息
5. 新对话接管   → 读交接文档 → 逐项汇报状态 → 继续执行
```

## 交接文档模板（<工作区>/docs/任务交接-新对话引导.md）

```markdown
# 任务交接 · 新对话引导（<日期>）

## 一、工作区速览
| 项 | 位置 |
|----|------|
| 工作区根目录 | <绝对路径> |
| 关键数据/产物 | <路径清单> |
| 配置 | <config 路径> |
| 技能/依赖 | <相关技能名> |

## 二、当前状态快照（<日期时间>）
- <正在进行的任务：后台任务 id、日志路径、预计时长>
- <已完成的关键成果，1-3 条>
- <环境/网络等注意事项>

## 三、待办清单（按优先级）
- [ ] 1. ...
- [ ] 2. ...

## 四、常用命令
```powershell
<工作区关键命令，每行一条>
```

## 五、新对话引导消息（复制粘贴到新对话）
<见下方模板>
```

## 新对话引导消息模板

```
我是从<工作区名>上一段对话交接过来的。请先读：
1. <工作区>/docs/任务交接-新对话引导.md
2. <若有补充文档，列出>

当前优先任务（按序）：
A. 确认后台任务状态（job_list；日志 <路径>），完成后校验<关键产物>
B. <待用户确认的事项>
C. <每日/定期任务>

工作区根目录：<绝对路径>
<关键约束/依赖说明，如数据源、只能本地执行等>
请先读完交接文档，然后逐项汇报当前状态。
```

## 执行规范（铁律）

1. **交接文档 ≤ 几百 token**：状态+待办+命令精炼成摘要，细节一律指向文件，禁止大段复制旧对话内容
2. **产物全部落文件**：脚本/配置/报告/日志在工作区，新 session 靠文件恢复上下文，不靠记忆
3. **禁止读旧 session 文件**：`<DSH_HOME>/sessions/<会话>/session.jsonl.zstd` 只做磁盘档案，不加载进新上下文
4. **后台任务先确认再动手**：新 session 先 job_list；任务归属旧会话时用日志文件（而非 job_output）查进度，避免"跨会话读不到"的困惑，也避免重复启动任务（如两个下载抢限流）
5. **交接即存档**：交接文档本身就是进度档案，多次交接可累积（新文档覆盖旧文档，但历史内容留档在旧文档或改名为带日期版本）
6. **完成后确认**：新对话接管后应汇报"状态已恢复"，并逐项确认待办，用户点头再执行

## 触发示例

- 用户："上下文满了，交接一下" → 执行工作流
- 用户："换新对话继续" → 保存交接+给引导消息
- 输出被截断时 → 尽快把当前状态写进交接文档，再给引导消息

## 自动模式（模型感知 · 本地小上下文模型专用）

> 适用：Qwen3.6-35B-IQ3_S（128k）等本地模型——上下文小，容易对话到 80 轮就逼近上限。

### 模型上下文预算表（来自 settings.yaml）

| 模型 | contextWindow | 预警 70% | 完成即交接 80% | 立即交接 90% |
|------|--------------|---------|---------------|-------------|
| Qwen3.6-35B-IQ3_S (文本) | **131072** | ~92k | ~105k | ~118k |
| Ornith-1.5 9B | 262144 | ~183k | ~210k | ~236k |
| Qwen3.5-9B | 262144 | ~183k | ~210k | ~236k |

### 自动检查（每轮或每 N 轮执行一次）

```powershell
python "<skill 目录>\scripts\check_context.py" --window 131072
# 输出 CONTEXT: used≈x tokens | 轮数=n | action=OK/WARN/FINISH_THEN_HANDOFF/HANDOFF_NOW
```

### action 处理规则

| action | 处理 |
|--------|------|
| OK | 继续正常对话 |
| WARN | 提醒用户上下文将满，后续回答尽量精简 |
| **FINISH_THEN_HANDOFF** | 当前任务若能在剩余预算内完成（估算 ≤ 5k token）→ **完成任务后立即执行本技能交接流程**；否则视同 HANDOFF_NOW |
| **HANDOFF_NOW** | 立即执行交接（保存状态 → 生成引导消息 → 交还用户） |

### 触发轮数（80轮规律，用户实测）

- 轮数 ≥ 80 或 用量 ≥80% → **任务完成后立即交接**（这正是"90~100k 能完成对话→完成后再交接"的需求）
- 轮数 ≥ 100 或 用量 ≥90% → **立即交接**（不再等任务完成，防硬截断）

### 如何"只要调用该模型就自动生效"

DSH 技能系统按"描述匹配+用户触发"加载，**没有"每次调用模型即强制注入"的系统级 hook**（Modelfile SYSTEM 会被 DSH 的 agent 系统提示覆盖，不生效）。最接近"自动"的三种做法：

1. **会话开启即启用**（推荐）：在 Qwen3.6 会话的第一条消息说"开启自动续命"→ 本技能被加载，agent 每轮开始跑 check_context.py 自查，到阈值自动交接
2. **技能描述自触发**：本技能 description 已写明"本地小上下文模型（128k）自动续命"场景，agent 在 qwen3.6 会话中遇到上下文相关提问时会自动加载
3. **每轮自查纪律**：agent 一旦加载本技能，默认每轮开头运行一次检查（成本极低，一条命令），无需用户反复提醒

### 交接时务必带上的信息（自动模式）

- 当前轮数/用量（check_context 输出）
- 后台任务状态（job_list + 日志路径）
- 完成到哪一步、下一步做什么（待办清单）

## 关联

- `hermes-memory`（跨会话持久记忆方法论，可叠加）
- 各工作区自身技能（交接文档里的"常用命令"来自对应工作区技能）
- `scripts/check_context.py`（本技能自带：上下文用量/轮数检查，自动模式的执行器）