dsh-handoff-button

dsh plugin --profile web add dsh-handoff-button

dsh-handoff-button

DeepSeek Harness 插件：在每条 AI 回复的底部操作行添加一个 Handoff 按钮，

点击后把当前会话压缩成 handoff 文档，写入该会话工作区的 handoff/ 目录。

功能

• 按钮：每条已完成的 AI 回复操作组最右侧（复制/反馈按钮之后）的圆形图标按钮

（assets/write.png，Magnific/Freepik 的「文档+笔」图标，由 Host 路由同源提供，无外部网络依赖），

悬停有 Tooltip 提示。想换图标：直接替换 assets/write.png 后重启即可

（图标响应带 24h 浏览器缓存，替换后如未变化请强刷页面）。无论点的是哪条消息，handoff 永远针对整段会话

• 生成：点击后调用 LLM（当前默认模型）按原版 handoff skill 要求

生成总结式文档：Status / Goal / Progress / Next Steps / Suggested Skills 五段结构，

让一个全新 agent 能接手整段工作（不是只压缩最近几轮）。Goal 取自第一轮目标与之后的明确改口；

Progress 为紧凑总结而非对话实录；中段助手长文默认视为已落入 References 中的工件（specs / plans / ADRs），

用路径引用、不复述。LLM 不可用时自动降级为启发式摘要（同样保留第一轮目标）。

Alt+点击可填写「下一会话关注点」（对应 skill 的参数，最长 500 字符，写入前同样脱敏），Next Steps 会偏向该焦点，但不替换原始 Goal

• 状态反馈：生成中变暗 → 完成显示绿色 ✓（2 秒自动复原）→ 失败显示红色 ⚠（悬停可见原因，点击可重试）
• 打开文件：完成状态（✓ 期间）再次点击，通过 DSH openWorkspacePath 在软件内打开（安装了 better-sidebar 时进侧边栏编辑器；否则走系统默认应用）。不再打开浏览器原始 URL。
• 文件名：handoff-{yyyymmddhhmmss}-{会话标题}.md（非法字符替换为 -，最长 60 字符），

handoff/ 目录不存在时自动创建

• 脱敏：API key、token、密码等常见敏感信息在写入前自动打码
• References：自动收集会话中实际触碰过的文件路径，只保留工作区内的文件，统一转换为相对工作区根目录的相对路径（跨机器/多人协作可读；工作区外的系统路径、临时目录、本机配置等一律不收录，上限 30 条）；Suggested Skills 在降级摘要中列出会话中实际调用过的技能（上限 15 个），LLM 模式下由模型以这些技能为线索给出 2–5 个建议
• 生成管线：转录按轮压缩（用户消息全留，助手每轮只留最后一条 text 块、跳过 reasoning 以防泄露思维链），默认取 24 行、尾部优先，中间省略处插入标记；LLM 使用当前默认模型（maxTokens 4096、purpose handoff），产出 500 词以内的五段文档；文档头部带引用块（生成方式 / 时间 / sessionId / focus），降级时文末附 LLM 失败原因注释
• 落盘位置：原版 skill 写到系统临时目录以免 agent 污染仓库；本插件是用户点击的持久交接件，写入该会话工作区的 handoff/，以便 openWorkspacePath 在软件内打开、跨会话复用
• 沙箱：写入围栏钉在该会话工作区，而不是 host 默认根目录，因此不会出现 file access denied under workspace-write mode；若会话 approval 为 never（无法升级沙箱），仍会写入 handoff/

安装

发布到 npm 后（或本地包目录）：

dsh plugin --profile <name> add dsh-handoff-button

本地开发版：

dsh plugin --profile <name> add /绝对路径/dsh-handoff-button

[!IMPORTANT]

启动顺序决定是否需要重启。 DSH 的插件 bundle 组合发生在进程启动时（Loader 读取

profile 的 package.json 生成插件树和 client 模块图），安装命令只改磁盘上的 profile 文件，

不会热插进已在运行的进程：

- 先安装 → 再启动：启动时插件已在列表里，直接生效，无需重启；

- 先启动 → 再安装：装完后必须完全退出并重新启动 dsh（⌘Q 退出桌面应用或终止

Web UI 进程，不是刷新页面），让进程重新组合 profile。

安装后可用 dsh --profile <name> --dump-config | grep handoff 确认插件已进入 bundle 层。

架构

• index.js — Host 半部：注册三个路由（webServer 服务）：

POST /handoff/write（生成文档）、GET /handoff/read（只读兜底查看器，

客户端打开文件走 openWorkspacePath，不经过此路由）、

GET /handoff/icon（提供 assets/write.png 图标）。读取会话日志

（sessionQuery）并写文件（fs，自动建目录），调用 LLM 总结（llm +

agentDefaultModel）。写入把沙箱围栏钉在该会话的工作区根目录上

（用户点击，不是模型工具）；若沙箱仍拒绝（例如 approval 为 never

无法升级），则回退为 Node 直接写入同一路径。仅依赖 Node 内置模块

（node:fs/node:url/node:path），无第三方运行时依赖。

• client.js — 浏览器半部：通过 client module loader

（window.__ModuleLoader__.load）注册，向 conversation.chat.assistant-actions

槽注入按钮（order: 100，最右侧插槽条目），点击后同源 fetch 调用 Host 路由；

图标通过 CSS mask 引用 /handoff/icon，颜色跟随主题。

• assets/write.png — 按钮图标（Magnific/Freepik「文档+笔」图标），可自由替换。
• cordis.patch.yml — Bundle 补丁层：把本包作为插件行插入组合。

零用户配置项（无需任何设置）；要求 Node >= 22.19；无任何第三方运行时依赖。

卸载

dsh plugin --profile <name> remove dsh-handoff-button

验证

• 组合加载：dsh --profile <name> --dump-config | grep -A2 handoff
• 浏览器检查：http://127.0.0.1:3080/plugins/dsh-handoff-button/client.js 应返回脚本
• 回归测试：npm test

---

English

DeepSeek Harness plugin: adds a Handoff button to the action row of every

assistant message. Clicking it compresses the current conversation into a

handoff document and writes it to the handoff/ directory of that session's

workspace.

Features

• Button: a circular icon button at the far right of the action group on

every completed assistant message (after the copy/feedback buttons), with a

hover tooltip. The icon (assets/write.png, a Magnific/Freepik

"document + pen" icon) is served same-origin by a host

route — no external network dependency. **To change the icon, replace

assets/write.png and restart** (the icon response carries a 24h browser

cache; hard-refresh the page if it does not change). No matter which message

you click, the handoff always covers the entire session.

• Generation: on click, the current default LLM model writes a summary

document in the five-section structure of the original

handoff skill:

Status / Goal / Progress / Next Steps / Suggested Skills, so a **fresh

agent can continue the whole job** — not just the latest turns. Goal is

taken from the opening objective (and later explicit restatements);

Progress is a compact summary rather than a raw transcript; middle

assistant turns are treated as already captured in referenced artifacts

(specs / plans / ADRs) and are cited by path instead of quoted. Falls

back to a heuristic digest (still keeping the original goal) when the

LLM is unavailable. Alt+click sets a "next session focus" (the

skill's argument, max 500 chars, redacted before writing): Next Steps

bias toward that focus without replacing the original Goal.

• Feedback: dims while generating → green ✓ on success (auto-reverts

after 2s) → red ⚠ on failure (hover for the reason, click to retry).

• Open file: while the ✓ state is shown, click again to open the

generated document in the app via openWorkspacePath (sidebar editor

when better-sidebar is installed; otherwise the OS default app). It

no longer opens a raw browser URL.

• Filename: handoff-{yyyymmddhhmmss}-{session title}.md (illegal

characters replaced with -, max 60 chars); handoff/ is created

automatically if missing.

• Redaction: API keys, tokens, passwords and similar secrets are masked

before anything is written to disk.

• References: collects file paths actually touched in the conversation,

…(truncated)