dsh-handoff
Manifest validModel-facing session handoff for DeepSeek Harness: copy a session's full history into another workspace with a written brief. Hand off the current session completely to another workspace within the conversation.
dsh-handoff
给 DeepSeek Harness(DSH)的会话交接插件:Agent 在对话里就能把当前会话交接到另一个工作区。新会话在目标工作区里热创建(不重启、不刷新),并带着一份交接简报。
交接有两种历史策略:
| 模式 | history | 新会话里有什么 | 什么时候用 |
|---|---|---|---|
| 全文复制(默认) | full | 完整事件历史 + 交接简报 | 新会话需要精确上下文,且源会话还健康 |
| 仅摘要 | summary | 只有交接简报 | 源会话已经很大、上下文快撑爆,或用了不支持主动压缩的插件 |
原会话始终保持不变(mode: "copy" 时)。
不需要点按钮,也不需要退出重开——你对 Agent 说一句:
把这个会话交接给 ~/Project/foo,新会话里写清楚我们做到哪了
它就会调用 handoff_session 工具,在 ~/Project/foo 里生成一个新会话。也可以直接敲 /handoff 或 /handoff-summary,由插件向同一个模型发一次侧路请求把简报写出来,再创建会话。
它解决什么
手工「换个工作区继续」通常会丢三件事:历史、结论、下一步。复制文件不会带上对话;新开一个空会话等于让模型从零开始;把整段记录粘进输入框既超长又失真。
dsh-handoff 用 DSH 自己的能力做三件事:
- fork —
sessionController.fork()把当前会话的事件前缀复制成一个独立的新会话(不写parentSession,所以侧栏和可恢复集合都认它); - relocate — 把新会话的存储迁到目标工作区:重写日志头行的
cwd、重绑活动写句柄、切换工作区账本。全程不重启; - brief — 把交接简报追加成新会话的第一条消息。简报按固定六节骨架写(目标 / 决策 / 已完成 / 剩余 / 关键上下文 / 下一步),可以由模型在工具调用里写,也可以由插件用一次侧路请求独立生成。
为什么需要「仅摘要」
fork 是事实复制,不是压缩:源会话如果已经被上下文压力拖到边缘,复制出来的会话会继承同样的压力。最典型的例子是同装了不做主动 compact 的上下文插件——源会话压不下去,新会话同样压不下去,于是「交接」只是把一个快废掉的会话再复制一份。
history: "summary" 于是干脆不复制事件:直接在目标工作区新建一个空白会话,把简报写进去。新会话的上下文压力从零开始,代价是丢掉了原始对话里的细节(工具输出、文件内容、原话)。
仅摘要交接出来的会话需要至少一个回合才能出现在侧边栏里:GUI 用 sessionListMetadata.blank 判断「这个会话是否已经开张」,而该投影只在遇到 turn/start 时才翻成 false;没有回合的会话只是一个隐藏的「未开始」占位。
这个空回合由 agent loop 自己开,不是插件手写。插件把简报当普通 prompt 入队,在 agent/pre-step 里把该回合 claim 到的消息放回 next-step,并返回 { kind: "enter", messages: [] };loop 自己的规则(phase.step === 0 && decision.messages.length === 0)随即把回合以 completed 关闭——没有 step、不调用模型、不跑工具,日志里只会多一条 turn/start/turn/end。简报留在 inbox 里,等用户的第一条真实消息把它一起带进下一个回合。
不要手写这个回合。 0.6.2 及更早版本直接
append("turn/start", { turn: 1 }),随后用户发消息时 loop 又写了一次turn=1(loop 构造时缓存了lastTurn,看不到插件后补的回合),读取器便以turn/start does not open the expected turn判定日志损坏、整个会话打不开。若简报写成 surface 消息、排在 loop 的第一条system/message之前,还会触发system/message requires a protected first surface head。两条约束的完整说明与排查方法见docs/session-log-invariants.md。
超限的会话不复制
outbound body measures ~2,855,805 tokens … the body ITSELF exceeds the window 这类报错不是交接逻辑坏了,而是被交接的那个会话本身已经装不下一次请求:provider 在发送前把整个 body 量和窗口比一遍,超了就整包退回。全文复制会把同样的体积原样搬进新会话,于是新会话第一轮就死在同一个地方——你花了很久跑完的交接,换来的还是一个跑不动的会话。
所以插件在动手之前先量一遍(lib/context-size.js):文字按 CJK 加权、图片按视觉预算(像素/750)折算成 token,再和会话的窗口比。
- ≥ 80%:直接拒绝,报错里给出具体数字和该走的路,不 fork、不建目录、不花时间。
- 50%–80%:照做,但在结果里提醒余量不多。
- 斜杠命令不能反问,所以
/handoff撞上 80% 时自动降级成仅摘要,并在卡片和结果里写明降级原因。
| 源会话占用 | handoff_session(模型调用) | /handoff(斜杠命令) |
|---|---|---|
| < 50% | 复制 | 复制 |
| 50%–80% | 复制,附余量提醒 | 复制,附余量提醒 |
| ≥ 80% | 拒绝,提示改用 history:"summary" | 自动降级为仅摘要 |
安装
# 从 npm
dsh plugin --profile <profile> add @garinz/dsh-handoff
# 或直接从 GitHub
dsh plugin --profile <profile> add github:GarinZ/dsh-handoff
从本地检出的源码安装:
dsh plugin --profile <profile> add /path/to/dsh-handoff
# 或在该目录里
dsh plugin --profile desktop add .
宿主半热加载,装完即可用;不需要客户端插件,因此也不用刷新页面。
仓库:https://github.com/GarinZ/dsh-handoff · npm:https://www.npmjs.com/package/@garinz/dsh-handoff
使用
斜杠命令
插件注册了三个命令,输入 / 就能看到:
/handoff [自然语言]— 全文复制模式/handoff-summary [自然语言]— 仅摘要模式/btw <问题>— 旁问:就当前对话问一句,答案稍后更新在这条命令下,不写进会话记忆
后面那段自然语言不是必填的。 什么都不写,就默认交接回当前工作区——这正是「这个会话满了,给我一个带摘要的新会话」的用法,新会话和原会话并排出现在同一个工作区里。写了、但里面认不出任何目标(比如「交接给之前说的那个仓库」),命令会直接报错要求给出路径/标题/id,而不是猜一个地方。
命令本身是秒回的:侧路请求要把整段对话发上去,几秒到几十秒不等,如果卡在命令里等,输入框会一直占着草稿、看起来像卡死。所以命令先回一句「旁问中…」/「正在生成简报并交接…」,把输入框让出来;等答案回来,再用同一条命令的结果把它替换掉。
/handoff 系列后面跟的是一段自然语言,不是路径参数。你同时在里面说清楚两件事:
- 交接去哪里(可以只写「接手 agent-skills 那边的工作」,让模型自己找);
- 简报要重点写什么(下一阶段的重心、必须带过去的决定、不要再碰的东西)。
例如:
/handoff-summary 交接给 ~/Project/llm/agent-skills。ESP32 那摊活先放下,下一阶段只做 skill 仓库整理:重点写清楚哪些 skill 已经沉淀、哪些还只是草稿,以及"别自动入库"这条约束。
(写成一行即可,命令的输入框是单行的。)
简报怎么来。 命令优先走侧路请求:插件取当前会话的消息快照(含 system prompt),追加一条「请按六节骨架写交接简报」的指令,用同一个 provider/model 单独请求一次,拿到简报后直接调用 handoff_session。这条请求不开启回合、不往对话里写任何事件,简报也不会被复述到聊天里。命令从不退回「往输入框排一条指令」的路径:那等于把整段对话再喂给主模型一次,正是超限会话在 egress fuse 上炸掉的原因。条件不满足时它直接把原因说清楚——没写目标就提示 /handoff-summary ~/work/some-repo,认不出目标就要求给出路径/标题/id,没有 llm 或请求记录就报服务缺失。
简报骨架是固定的六节,两种模式都一样:
## 目标 这一段要达成什么
## 决策 决定了什么 + 为什么(理由比结论重要)
## 已完成 带产物:文件路径、跑过的命令、测试结果
## 剩余 还没做的
## 关键上下文 路径、符号、报错原文、配置值
## 下一步 新会话第一条该做什么
写作规则对齐了 oh-my-pi 与 pi-handoff:只用对话里出现过的事实、不臆造路径与行号;关键细节不知道就写「未知」并给出最小验证步骤;用祈使句对下一任说话,不用第一人称;不把「写这份简报」本身写进进度或下一步。
旁问 /btw
/btw 刚才那个 403 是哪个开关没开?
它复用简报用的同一个侧路请求原语:快照 + 一句问题 → 一次独立模型调用。不开启回合、不写事件、不占会话记忆,也不会打断正在进行的工作,更不会阻塞输入框。
侧路请求发的是扁平文本,不是结构化历史:把会话压成 ## 用户 / ## 助手 / ## 工具结果 的对话记录,塞进一条 user 消息,规则走 system。原因很实际——请求里不声明 tools 时,provider 会拒绝带 tool-call 块和图片的原始历史;这也是市场里 BTW 插件清一色这么做的原因。预算按字符算:旁问 20 万字符、简报 40 万字符,超了从最旧的整条丢起,并在开头注明「更早的 N 条消息已省略」;图片一律变 [图片]。
侧路请求不传 sessionId:一旦请求里带了会话 id,适配器会把该会话的整个附件库(这个仓库里那条会话是 977 张截图、13.5 MB)附在请求上,provider 的计量里表现为 other ~1,574,608 tokens,请求直接撞 egress fuse——而模型根本没机会读这些附件。旁问和简报都只需要我们自己拼好的那段文字,所以按无状态请求发出。
失败时显示 provider 原文(message (CODE) HTTP 400),不再是 [object Object]。侧路请求不写死 maxTokens:留空时 ctx.llm 会填上该模型自己声明的 defaultMaxTokens,和普通回合的上限一致,也就不会出现「聊天能写完、旁问却被截在半句」这种事。万一仍以 max-tokens 结束,卡片和命令结果会明确标注「已达输出长度上限,已截断」,而不是把半句话当成完整答案。
进度面板
/btw 和 /handoff* 的快路径都会在右下角弹出一张固定的进度卡:标题、状态(思考中 / 输出中 / 创建会话中)、已经跑了多少秒、流式正文,以及「停止」。它走的是独立的宿主路由 GET /handoff/activity?session=<id>(?cancel=1 中止),不依赖聊天流,所以会话正在跑回合、正文还在滚的时候照样看得见。
底部的输入框就是追问口:敲一句、回车,卡片会 POST /handoff/ask({session, question})把问题交给宿主,答案直接流回同一张卡,不用再回输入框敲命令。这条路由不走客户端的命令服务,所以追问既不会在对话里留下命令节点,也不会因为某个客户端服务没挂载而静默失效。追问时模型能看到这次会话里最近 12 组旁问问答(原文不截断,只存在内存里,重启即失),所以「那第二步呢?」这类指代接得上——旁问答案从不进入会话历史,没有这层记忆每次都得从零问起。
卡片通过 ctx.slots.inject('conversation.input.overlay', …) 注册——这是把浮层绑到槽位生命周期的写法,和市场的 BTW 插件一致;用裸的 ctx.inject(['slots'], …) 注册在部分壳里会时有时无。
下面这张命令卡仍然会留在对话里做归档:命令秒回一句「旁问中…」,答案落地后替换成完整结果。两条通道是同一次侧路请求的两个视图——有面板时看面板,没有客户端半(headless、老版本 shell)时看命令卡。
客户端半是
client.js,装/升级后需要刷新一次页面才会加载。dsh 自带的 Web 壳刷新方式是 ⌘⌥I 打开开发者工具后执行location.reload()(生产版没有 ⌘R)。
如果你已经装了市场里的 BTW 插件(dsh-btw-plugin、dsh-command-btw 等),它们的浮层和这张卡互不干扰;本插件只提供最小的纯文本版本。
直接说人话
- 「把这个会话交接给
/Users/me/Project/new-repo」 - 「我们换个工作区继续,搬到
~/work/another-project,只写总结别复制历史」 - 「hand this off to the agent-skills repo and summarize where we are」
Agent 会调用:
{
"target": "/Users/me/Project/new-repo",
"summary": "## 目标\n…\n## 决策\n…\n## 已完成\n…\n## 剩余\n…\n## 关键上下文\n…\n## 下一步\n…",
"history": "full",
"title": "可选:给新会话一个能认出来的标题",
"start_turn": false
}
target:工作区绝对路径(或~开头)、工作区 id、或工作区标题。目录存在但没有工作区记录时会自动注册;目录不存在时会先创建再注册(mkdir -p),所以「交接给~/proj/新项目」可以直接开一个新工作区。这一项由模型根据你的自然语言描述解析,通常不需要你操心。summary:交接简报,六节骨架,由模型撰写。history: "full"时它是补充;history: "summary"时它是新会话唯一的上下文,所以要写全:目标、决定及理由、已完成、待办、要重新打开的文件、验证步骤。history:full(默认)复制完整历史;summary不复制任何事件,只开一个带简报的空白会话。title:可选,避免目标工作区里出现两个同名会话。start_turn:为true时立刻在新会话里跑一轮(它会读到简报并回应);默认只记录,不消耗模型调用。mode:copy(默认)复制出一个新会话,原会话不动;move把当前会话本身在回合结束后迁到目标工作区(id 不变、历史全保留),并在新位置写入简报——适合「这个对话本身就该在那边继续」。move只能搭配history: "full"。
对工作量的兜底:会话里连一问一答都没有时,工具会直接拒绝(这次会话还没有可交接的对话),免得留下一个空壳会话。
两种模式各自的落盘结果
history: "full":
<目标工作区>/…/session-<new>/session.v4.jsonl.zstd
header.cwd = 目标工作区
事件 = 源会话的完整前缀 + 简报
history: "summary":
<目标工作区>/…/session-<new>/session.v4.jsonl.zstd
header.cwd = 目标工作区
事件 = 标题 + 简报(没有别的)
行为细节
- 复制而不是移动(
mode: "copy"):源会话的日志、标题、工作区归属都不变;新会话是独立的一份。 - 热创建:新会话出现在目标工作区的侧栏里,无需重启 DSH。
- 来源约束:subagent 会话不能交接;没有记录
cwd的会话不能交接。 - 工作目录:新会话的
header.cwd是目标工作区路径,因此沙箱根、AGENTS.md、skills 发现都跟着走。 - 损坏保护:存储迁移先写临时目录、读回校验,再改内存态与账本;任一步失败都会回滚并保留原会话。
mode: "move"(beta):迁移推迟到当前回合结束(turn/end)执行,避免在工具调用中途改写正在写入的日志;工具当时只返回queued: true。如果目标路径与当前工作区相同,则只补写简报、不搬文件。
已知边界
- 全文模式交接过来的是 fork 语义:新会话的
isSeeded为true,历史标记为继承(session/end-seed)。它可正常打开、继续对话,但依赖「自身事件」的功能(例如按会话统计 token 用量)会把继承部分算作前人历史。 - 摘要模式的新会话没有继承历史,因此也不会有这些问题;反过来说,它只知道简报里写了的东西。
- 侧栏刷新时机由 DSH 客户端决定;工作区账本与日志是即时写好的,个别界面状态可能需要切一下工作区或刷新页面才显示。
- 依赖若干 DSH 内部接口(
sessionPersistence.tracker.writers、workspaceRegistry.indexHeader/attachSession、commands.register)。DSH 升级后请先在一个临时会话上验证。
兼容性
- 开发与验证环境:DSH
0.2.2-rc.1(macOS 桌面版),Node 24。 - 需要 hosting 暴露
sessionController、workspaceRegistry、sessionPersistence三个服务(官方dsh-base都有);有commands服务时才会注册斜杠命令,没有也不影响工具。
开发与测试
npm test # node --test test/*.test.mjs
test/relocate.test.mjs— 存储布局编码(projectKey/encodeSegment)、头部帧重写、事件帧逐字节保留、重复目标拒绝、同目录 no-op。test/prompts.test.mjs— 六节骨架、写作规则(不臆造 / 未知标注 / 祈使句 / 机制不可见)、summary 与 full 的模式差异、空请求兜底。test/side-request.test.mjs— 路由解析、消息计数、侧路请求的文本拼接与错误分支。test/activity.test.mjs— 进度槽的流式写入、过期回调防覆盖、/handoff/activity路由与取消。test/client.test.mjs— 通过window.__ModuleLoader__.load加载客户端半并 apply,验证浮层(slots.inject)与命令监听注册。test/plugin.test.mjs— 三个命令的注册、/btw的侧路回答与延迟回填、后台交接成功/失败的回填、控制器缺失时的错误返回、尚不存在的目标目录走快路径。test/brief-append.test.mjs— fork 路径只写一条 surfaceuser/message,任何情况下都不伪造回合。test/visible-turn.test.mjs— 空回合由 loop 关闭、简报回到next-step、钩子与监听器全部释放、他人会话放行、超时与 prompt 被拒的分支。
单元测试只覆盖宿主半的编排,碰不到真实浏览器。客户端链路(浮层是否出现、追问按钮的 POST)用 docs/smoke-ui.md 里的一套隔离宿主 + agent-browser 流程手工验证,改动客户端半后请按它跑一遍。
往会话里写事件之前,先读 docs/session-log-invariants.md:回合号必须由 agent loop 连续分配,surface 的第一个节点必须是 loop 的 system/message。违反任何一条都会让整个会话在下次加载时被判损坏(0.6.2 的教训)。
许可与致谢
MIT。lib/relocate.js 改编自 dsh-cd(MIT)的 dist/relocate.js;会话存储布局的编码规则(projectKey / encodeSegment)取自 DSH 的 JSONL 持久化后端,同一份代码也出现在 dsh-session-manager(MIT)中。
Comments
Loading…
Similar plugins
by MountBatten718
Hand your long DSH session over to a fresh one: /handoff summarizes the recent conversation with an LLM, creates a clean new session in the same workspace, injects the summary as its first message, and auto-opens it. The origin session is unchanged.
★ 3
MIT
JavaScript
Oct 20, 2026
dsh plugin --profile web add dsh-session-handoffby IKEASven69
DSH 会话接力插件:拉取六家 agent 会话(/resume-*)、寄存当前会话(/handoff)、开局取件(/inbox),落在 handoff: 1 开放协议上
★ 0
MIT
TypeScript
Oct 26, 2026
dsh plugin --profile web add dsh-takeoverby LeslieWylie
Cross-session task queue with handoff notes: sessions and subagents push, claim, complete and cancel tasks on a shared file-backed queue, and leave a handoff summary for whoever picks up next.
★ 2
MIT
TypeScript
Aug 18, 2026
dsh plugin --profile web add dsh-task-relayby WeiYe6
Hand your long DSH session over to a clean one: /handoff summarizes the conversation with an LLM, creates a new session+agent in the same workspace, injects the handoff document, and auto-opens it.
★ 6
MIT
JavaScript
Aug 28, 2026
dsh plugin --profile web add dsh-session-handoffSession context handoff for DeepSeek Harness — stop re-reading and re-deriving context every session. A single skill (layer ①) that keeps the next session warm.
★ 0
dsh plugin --profile web add dsh-token-handoffby qingyou002
DSH plugin: hands a long session over to a fresh session in the same workspace on /handoff or at a token threshold, carrying the preset, model, permissions and plan mode across; the brief is written by the session's own model and the switch waits for a step boundary instead of interrupting running work.
★ 0
MIT
TypeScript
Sep 28, 2026
dsh plugin --profile web add dsh-auto-handoff