会话交接快照0mn1si2i5/dsh-handoff

dsh-handoff

在 DeepSeek Harness 会话之间传递开发上下文。
Pass development context between DeepSeek Harness sessions.

问题 / Problem — Harness 会话很长，换新会话时难以带回已确认的结论、进度与下一步。Harness sessions run long; starting fresh means losing the conclusions and progress you already reached.

- /handoff save — 把当前线程总结为 docs/handoffs/current.md。Summarize the current thread into docs/handoffs/current.md.
- /handoff load — 把这份文档作为召回节点注入新会话。Inject it into a new session as a recall node.
- 脱敏 / Redaction — 对消息、模型输出、Git 文件名和动态元数据做确定性脱敏。Deterministic redaction of messages, outputs, Git filenames, and dynamic metadata.
- Git 状态 / Git state — 捕获分支、HEAD 和变更文件列表。Captures branch, HEAD, and the changed-file list.

不保证 / Not guaranteed — 不是完整会话日志，不自动 save/load，不解决合并冲突；脱敏不是对一切秘密格式的绝对保证。Not a full session log; no auto save/load; no merge or conflict resolution; redaction is not an absolute guarantee for every secret format.

项目简介

DeepSeek Harness 的会话通常很长，换新会话时难以把上一个会话已经确认的结论、当前进度和下一步计划完整带过去。本插件提供两个命令来解决这个问题：

- /handoff save 把当前线程的有效状态总结成一份文档，写入 docs/handoffs/current.md，并让 assistant 回一句话确认。
- /handoff load 把这份文档作为 durable recall 注入一个新线程，立即显示为一条可见的召回节点，并让 assistant 回一句话确认已加载。

它是一份交接快照，不是对当前线程上下文的压缩、删除或替换。save 不修改原线程已有的消息，load 也不会删除或压缩新线程里的其他上下文。

前置条件

- DeepSeek Harness 已安装并可运行。
- Node.js 版本满足 ^22.19.0 || >=24.0.0（与 package.json 的 engines 一致）。
- 插件记录 Git 仓库状态，并生成可由用户检查和提交的交接文档。
- 安装 @deepseek-ai/* 的 rc/beta 依赖需要用户自己的 npm 权限；认证应配置在用户级 ~/.npmrc，不要把认证配置行或令牌写入仓库或文档。

安装

通过 GitHub 分发安装，无需 npm scope：

dsh plugin --profile web add github:0mn1si2i5/dsh-handoff

安装的是仓库里已提交的构建产物（lib/），无需在安装时执行构建脚本。

60秒上手 · 60-second path

1. 在原线程执行 /handoff save，生成 docs/handoffs/current.md。Run /handoff save in the source thread.
2. 查看并提交这份文档。Review and commit the document.
3. 在同一仓库的新线程执行 /handoff load，交接文档立即显示为召回节点。Run /handoff load in a new thread in the same repository.

dsh-handoff 演示：在源线程执行 /handoff save 保存交接文档，在新线程执行 /handoff load 加载它

DeepSeek Harness 仍处于 Developer Preview，本插件针对当前预览版本开发，不承诺稳定 API 兼容。

本地打包验证（开发用）

在改代码时，用本地 tarball 安装最接近真实的发布结果，而不是直接链接源码目录：

pnpm install
pnpm check
pnpm pack --pack-destination
dsh plugin --profile web add
dsh --profile web --dump-config

最后一条命令用于确认 dsh-handoff 已出现在配置中。安装的是打包后的产物，而不是源码目录，因此能验证发布包的实际内容。

快速使用

1. 在原线程执行 /handoff save。
2. 查看或提交生成的 docs/handoffs/current.md。
3. 在同一仓库的新线程执行 /handoff load。
4. load 会把交接文档作为一条可见的召回节点立即显示出来，并唤醒模型回一句话确认；之后用户发送下一条开发指令即可继续。
5. 当前代码与当前用户指令优先于历史 handoff 文档。

Commands

- /handoff save — 总结当前会话，写入 docs/handoffs/current.md，并让 assistant 确认。
- /handoff load — 把 docs/handoffs/current.md 作为 recall 上下文注入当前会话，显示为一条召回节点，并让 assistant 确认。

两个命令都要求 agent 处于 idle 状态，且不接受额外参数。

Configuration

| 字段 | 说明 |
| --- | --- |
| summarizationProvider | 保存时做总结所使用的 provider。与 summarizationModel 一起配置，二者要么都设置、要么都不设置。省略时依次回退到会话最近一次请求的 provider/model，再到 agent 的默认 provider/model。 |
| summarizationModel | 保存时做总结所使用的 model。与 summarizationProvider 一起配置。 |
| maxTokens | 总结请求的输出 token 上限。默认 4096。 |
| maxDocumentBytes | 交接文档的 UTF-8 字节上限。默认 32768。 |
| gitTimeoutMs | 捕获 Git 状态的超时时间（毫秒）。默认 10000。 |

所有数值字段必须是正整数（安全整数范围内）。未知配置键会被拒绝。

文档格式与 Git 行为

- 文档固定在 docs/handoffs/current.md（相对仓库根目录），格式为 dsh-handoff/v1。只有用户提交 current.md 后，Git 历史才会保留旧版本。
- save 会捕获当前的 Git 分支、HEAD 和变更文件列表，并据此计算一个状态摘要（state digest）。
- handoff 文档自身不计入这个 stale digest，因此一次 save/load 往返不会被误判为“仓库状态已变化”。
- load 时若仓库状态与文档记录不一致，只产生告警，不阻止注入；当前文件始终优先。
- 写入使用带版本的原子写与并发保护，旧版本不会覆盖胜出的版本。

安全边界

保存时会对输入消息、模型输出、Git 文件名和动态 Git 元数据做确定性脱敏。主要覆盖的类别包括：私钥、npm token、Authorization 值、密码、常见 API token，以及敏感环境变量的值，统一替换为  一类的占位符。

脱敏是一道安全防线，但不是对所有可能秘密格式的绝对保证。建议用户在提交 handoff 文档前自行检查一遍内容。

- Git 命令使用固定参数、有界输出和超时，不经过 shell。
- 错误、文档和告警不会回显秘密值。

Token 与模型行为

- save 会发起一次独立的总结调用，外加一次确认回复，各消耗一次输入加输出的 token；它不会减少原线程的 token 占用。
- load 会唤醒模型一次，让 assistant 确认已加载，同样消耗少量 token。
- 交接文档本体在下一轮请求开始时才进入模型上下文。
- 插件不承诺任何供应商的 KV cache 命中。

限制

- 仅文本：总结不包含图片或工具 schema。
- 只有单一固定的 current.md，没有时间戳或多个槽位。
- 除 Git 历史外没有归档或备份。
- 不会自动 save 或 load。
- 没有跨工具交接格式，也没有 UI。
- 对仓库状态变化采用保守的告警，不做合并或冲突解决。
- 不是完整会话日志的替代品。

开发与验证

pnpm install
pnpm check
pnpm pack --dry-run

License

BSD-3-Clause