前言¶
在 DeepSeek Harness（DSH）里做长任务时，上下文窗口迟早会顶满。常见做法是压缩历史，或在 Step 边界把状态「简报」成一条消息交给新会话。上一类方案 dsh-session-handoff 能跑，但简报是散文式消息：没有有效期、已完成与未完成容易打架，且每次交接都在上一条之上叠加，接手方越读越长，往往还得回去翻日志。下面介绍后继插件 dsh-handoff-doc：在安全的 Step 边界停住，由当前会话的模型写一份带有效期的快照文件，归档旧版，新会话只收到指向该文件的短指令。
这是什么¶
dsh-handoff-doc（GitHub：ElioFanyu/dsh-handoff-doc，维护者 ElioFanyu）是 DSH 社区插件，当前 package 版本为 0.2.0，MIT 许可。定位是：把长会话交接成一份文件，而不是一条消息。上下文快满时，会话在 Step 边界停下，生成 HANDOFF.md，上一版写入 CHANGELOG.md 与 history/<月份>.md，在同一工作区开新会话并继承 preset、模型、权限、Plan 模式，最后只投递一条约 200 token 的指针消息。
与 dsh-session-handoff 的差异¶
这一版把内容搬进工作区文件，并立了几条硬规矩：
| 规矩 | 机制 |
|---|---|
| 只留「现在仍然成立」 | 提示词规则 + §9 只允许一行指针 |
| 不允许追加 | 每次交接整份重写 HANDOFF.md |
| 历史不能丢 | 覆盖前归档进 CHANGELOG.md + history/<YYYY-MM>.md |
| 必须有有效期 | 顶部写「到下一次提交为止（HEAD xxxxxxxx）」 |
| 长度必须可控 | 按字符预算裁剪，先删整节，再删长节末尾，并留省略说明 |
缺任一必需小节（§0/§1/§2/§4/§6/§8）则放弃交接，不创建新会话；写文档失败时原会话不动，零写操作。
工作区里的目录与文档骨架¶
默认目录（<项目> 取工作区最后一级目录名；monorepo 等场景用 handoffProjectFolder 指定）：
<工作区>/docs/handoff/<项目>/
├── HANDOFF.md # 当前快照，唯一要读的文件
├── CHANGELOG.md # 每次交接一行条目
└── history/
└── 2026-10.md # 被覆盖掉的交接文档原文，按月份归档
固定十节：§0 30 秒自检（命令由程序读）、§1 目标与验收、§2 当前有效事实、§3 卡点与阻塞、§4 下一步 + 验证映射、§5 硬约束、§6 文件地图（不写行号）、§7 已否决方案、§8 已验证 vs 未验证、§9 历史（一行指向 CHANGELOG，程序写）。
新会话第一条消息不是正文，而是读取顺序指引：先跑 §0 里的命令；自检通过再读 §2、§3、§4；自检失败或有效期已过则告知用户文档已过期，整份重写后再开工。
命令与自动触发¶
命令不进入模型可见历史：
| 命令 | 行为 |
|---|---|
/handoff |
立即交接成文档并交给新会话 |
/handoff status |
阶段、上下文占用率、累计消费、阈值、最近结果 |
/handoff where（别名 doc） |
文档路径、大小、HEAD、是否已归档 |
/handoff cancel |
取消进行中的动作（下一安全检查点生效） |
/handoff retry |
重试最近一次失败 |
自动触发字段与上一版 handoff 系列一致，例如 autoHandoffEnabled（默认 false）、autoHandoffTrigger（context / cumulative / either）、autoHandoffAtContextPercent（默认 85）等。文档相关新增项包括 handoffDir（默认 docs/handoff）、handoffDocMaxChars（默认 24000）、archivePreviousHandoff、reusePreviousHandoff 等。交接与压缩同时开启时，autoCompactAtContextPercent 必须低于 autoHandoffAtContextPercent，否则拒绝保存。
插件声明：不中断正在执行的工作（等 whenIdle()）、不吞用户消息、不删改原会话日志、失败不假装成功、不写工作区外路径（经 workspace-fs.ts 的 resolveInside 校验）。
安装与启用¶
安装命令以 README 为准（本地路径示例，需换成你本机克隆或下载后的目录）：
dsh plugin --profile <profile> add "file:D:/path/to/dsh-handoff-doc"
安装后重启 DSH。宿主与浏览器端 UI 在同一包内。运行环境要求 Node ^22.19.0 || >=24.0.0，peer 依赖含 @deepseek-ai/cordis、@deepseek-ai/dsh-host-webserver 等（见仓库 package.json）。
DSH 生态是「一切皆插件」；社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。插件以当前 dsh 进程权限运行，安装前应自行审阅源码与 MIT 许可证。
典型用法¶
- 在长会话中执行
/handoff，等待 Step 边界完成文档写入与新会话创建。 - 用
/handoff where确认docs/handoff/<项目>/HANDOFF.md路径与对应 git HEAD。 - 在新会话中按指针消息：只读 §0 跑命令，再读 §2–§4 从 §4 第一条动作开始。
- 需要观测触发与占用时执行
/handoff status；与dsh-session-handoff同时安装时，不要对同一会话同时开自动触发，否则会抢同一 Step 边界。
仓库自述验证情况见 docs/handoff/dsh-handoff-doc/HANDOFF.md。
适用场景与已知限制¶
适合：单仓库或多会话协作、需要可版本化、可重读的交接快照，且希望接手方先跑自检命令再读事实的场景。
限制（来自 README）：协调状态（阶段、闩锁、计数）仅在内存中，重启后丢失；设置与已写文档不受影响。无工作目录的会话无法交接。非 git 仓库时 git 事实自动跳过。模型不上报 contextWindow 时占用率触发不可用（累计触发仍可用）。custom 权限预设无名字可重放，只继承审批策略。
结尾¶
dsh-handoff-doc 把会话交接从「越来越长的消息」改成「整份重写 + 归档 + 字符预算」的单文件快照，并用短指针引导新会话先自检再动手。目录页：https://www.skillhub.cn/plugins/ElioFanyu/dsh-handoff-doc；源码与完整配置表：https://github.com/ElioFanyu/dsh-handoff-doc。
