DSH Plugins Marketplace

DSH Plugins

Plugins

/

dsh-handoff

G

dsh-handoff

Manifest valid

Model-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.

UI (client)hasBundlePatchMachine translated

dsh-handoff

给 DeepSeek Harness(DSH)的会话交接插件:Agent 在对话里就能把当前会话交接到另一个工作区。新会话在目标工作区里热创建(不重启、不刷新),并带着一份交接简报。

交接有两种历史策略:

模式history新会话里有什么什么时候用
全文复制(默认)full完整事件历史 + 交接简报新会话需要精确上下文,且源会话还健康
仅摘要summary只有交接简报源会话已经很大、上下文快撑爆,或用了不支持主动压缩的插件

原会话始终保持不变(mode: "copy" 时)。

不需要点按钮,也不需要退出重开——你对 Agent 说一句:

把这个会话交接给 ~/Project/foo,新会话里写清楚我们做到哪了

它就会调用 handoff_session 工具,在 ~/Project/foo 里生成一个新会话。也可以直接敲 /handoff 或 /handoff-summary,由插件向同一个模型发一次侧路请求把简报写出来,再创建会话。

它解决什么

手工「换个工作区继续」通常会丢三件事:历史、结论、下一步。复制文件不会带上对话;新开一个空会话等于让模型从零开始;把整段记录粘进输入框既超长又失真。

dsh-handoff 用 DSH 自己的能力做三件事:

  1. fork — sessionController.fork() 把当前会话的事件前缀复制成一个独立的新会话(不写 parentSession,所以侧栏和可恢复集合都认它);
  2. relocate — 把新会话的存储迁到目标工作区:重写日志头行的 cwd、重绑活动写句柄、切换工作区账本。全程不重启;
  3. 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 系列后面跟的是一段自然语言,不是路径参数。你同时在里面说清楚两件事:

  1. 交接去哪里(可以只写「接手 agent-skills 那边的工作」,让模型自己找);
  2. 简报要重点写什么(下一阶段的重心、必须带过去的决定、不要再碰的东西)。

例如:

/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 路径只写一条 surface user/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

dsh-session-handoff

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.

Terminal & ClientsSessions & MessagesManifest valid

★ 3

MIT

JavaScript

Oct 20, 2026

dsh plugin --profile web add dsh-session-handoff

by IKEASven69

DSH 会话接力插件:拉取六家 agent 会话(/resume-*)、寄存当前会话(/handoff)、开局取件(/inbox),落在 handoff: 1 开放协议上

Sessions & MessagesManifest valid

★ 0

MIT

TypeScript

Oct 26, 2026

dsh plugin --profile web add dsh-takeover

by 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.

Workflow & AutomationSessions & MessagesManifest valid

★ 2

MIT

TypeScript

Aug 18, 2026

dsh plugin --profile web add dsh-task-relay

by 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.

UI & ExperienceManifest valid

★ 6

MIT

JavaScript

Aug 28, 2026

dsh plugin --profile web add dsh-session-handoff

Session context handoff for DeepSeek Harness — stop re-reading and re-deriving context every session. A single skill (layer ①) that keeps the next session warm.

Tools & CapabilitiesManifest valid

★ 0

dsh plugin --profile web add dsh-token-handoff

by 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.

Sessions & MessagesManifest valid

★ 0

MIT

TypeScript

Sep 28, 2026

dsh plugin --profile web add dsh-auto-handoff