前言¶
DeepSeek Harness 的插件化架构允许开发者根据需求扩展功能。在 Agent 开发流程中，将一段完整的会话上下文固化下来，以便后续会话接手或人工审查，是常见需求。原版 handoff skill 通常将文档写入系统临时目录，无法直接在软件内打开。
dsh-handoff-button 插件通过在每条 AI 回复的操作行底部添加一个 Handoff 按钮，点击后将当前会话压缩成结构化文档，并写入该会话工作区的 handoff/ 目录。这提供了一个持久化的交接工件，便于跨会话复用。
核心功能¶
1. 按钮与交互¶
插件会在每条已完成的 AI 回复操作组最右侧（复制/反馈按钮之后）注入一个圆形图标按钮。悬停时显示 Tooltip 提示。
- 点击生成：点击按钮后，调用当前默认模型生成文档。生成中按钮变暗，完成后显示绿色
✓（2 秒后自动复原），失败则显示红色⚠（悬停可见原因）。 - 再次点击打开：在显示
✓的状态下再次点击，通过 DSH 的openWorkspacePath接口在软件内打开生成的文档（安装 better-sidebar 时进入侧边栏编辑器，否则走系统默认应用）。 - 更换图标：图标文件为
assets/write.png（Magnific “Write” 图标），Host 路由同源提供。如需更换，直接替换该文件并重启 DSH 即可。
2. 文档生成逻辑¶
文档采用 handoff skill 的五段式结构：
* Status：当前状态
* Goal：取自第一轮目标及之后的明确改口
* Progress：紧凑总结，非对话实录
* Next Steps：后续步骤
* Suggested Skills：会话中实际调用过的技能
对于中段出现的助手长文，默认视为已落入 References 中的工件（如 specs / plans / ADRs），生成时用路径引用而不复述全文。若 LLM 不可用，自动降级为启发式摘要，但仍保留原始 Goal。
3. 关注点设置¶
普通点击生成完整文档。按住 Alt 键点击，可填写“下一会话关注点”。该参数会引导 Next Steps 的生成，但不会替换原始 Goal。
4. 文件与引用处理¶
- 文件名：
handoff-{yyyymmddhhmmss}-{会话标题}.md。非法字符替换为-，最长 60 字符。handoff/目录不存在时自动创建。 - 脱敏：写入前自动打码 API key、token、密码等敏感信息。
- References：自动收集会话中实际触碰的文件路径，仅保留工作区内部文件，并转换为相对于工作区根目录的路径。系统路径、临时目录等一律不收录。
安装与启用¶
插件已发布至 npm。安装命令如下：
dsh plugin --profile <name> add dsh-handoff-button
若使用本地开发版本：
dsh plugin --profile <name> add /绝对路径/dsh-handoff-button
注意： 启动顺序决定是否需要重启。DSH 的插件组合发生在进程启动时，安装命令仅修改磁盘配置。
- 先安装 → 再启动：插件已包含在启动列表中，直接生效，无需重启。
- 先启动 → 再安装：装完后必须完全退出并重新启动dsh（桌面应用⌘Q或终止 Web UI 进程），让进程重新组合 profile。
安装后可用 dsh --profile <name> --dump-config | grep handoff 确认插件已加载。
架构与实现¶
- Host 端 (
index.js)：注册三个路由，提供POST /handoff/write（生成）、GET /handoff/read（打开）、GET /handoff/icon（图标）服务。负责读取会话日志、调用 LLM 总结、写入文件（自动建目录）。 - Client 端 (
client.js)：通过 module loader 注入到conversation.chat.assistant-actions插槽（order: 100，最右侧），处理点击事件并调用 Host 路由。 - 沙箱限制：写入围栏钉在“该会话工作区”，而非 Host 默认根目录，避免因权限问题报错
file access denied under workspace-write mode。即使沙箱 approval 为 never，仍会尝试写入handoff/。
适用场景¶
- 需要在 DSH 内直接打开 handoff 文档的场景。
- 跨机器或多人协作时，需要引用相对路径的工件。
- 需要快速固化当前会话上下文以备后续接手。
链接¶
- GitHub: https://github.com/whiteS18/dsh-handoff-button
- Catalog: https://www.skillhub.cn/plugins/whiteS18/dsh-handoff-button
