前言¶
在 DSH 插件生态中，开发者常需在多轮会话中快速总结当前进度。手动整理目标、已完成任务和关键文件不仅耗时，还容易遗漏细节。dsh-handoff 旨在解决这个问题，它通过解析会话事件流，生成一份确定性的 Markdown 交接文档。与记忆插件不同，它是一次性快照，不消耗 LLM 资源。
插件定位¶
这是一个由 ZhijiangTang 维护的 DSH 插件，许可证为 MIT。它专注于将当前会话状态“冻结”为一份静态的交接文档，供人阅读或供下一会话参考。
核心功能¶
- 确定性导出与零成本：基于会话事件流（用户消息、工具调用、结果、todo 等）生成文档，不调用 LLM，无额外推理成本。
- 自动收集：自动整理目标、已完成/未完成任务、关键文件路径及会话统计信息。
- 安全与自检：内置路径围栏保护，确保导出路径在工作区根目录内；支持自检机制验证功能可用性。
安装与启用¶
在 DSH 环境中，通过 profile 安装插件：
dsh plugin --profile <你的 profile> add file:./plugins/dsh-handoff
安装后，在会话中调用 handoff 工具。
典型用法¶
调用 handoff 工具时，可指定导出路径和覆盖行为：
dsh plugin --profile <profile> add dsh-handoff
参数说明：
* dest：导出文件路径，默认为 HANDOFF.md。路径必须相对于工作区根目录。
* overwrite：是否覆盖已存在的文件，默认为 false。
返回值：
* 成功：{ ok: true, path, sections, eventCount, chars, skipped, note }
* 失败：{ ok: false, error }
生成内容结构：
导出的 Markdown 文档包含以下章节：
* # 会话交接：包含会话 ID 和时间范围
* ## 目标：最近 3 条用户消息摘要及最新目标状态
* ## 已完成：文件写入/编辑、Git 提交及成功工具结果
* ## 未完成：错误工具及 pending/in_progress 的 todo 项
* ## 下一步建议：模板（当前留空）
* ## 关键文件：出现过的路径去重前 15 个
* ## 会话统计：事件、消息、工具、Token 及 Goal 计数
技术细节与注意事项¶
- 纯 ESM：无构建步骤，依赖
@deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-llm。 - 降级策略：当
session.events缺失或结构异常时，工具返回ok: true且skipped: true，仅输出模板骨架和降级说明，不抛出异常。 - 安全限制：
dest参数必须解析在工作区根目录内，否则返回错误。
总结¶
dsh-handoff 适合在会话结束、切换上下文或需要向接手者移交工作时使用。它提供了一份基于事实的静态交接文档。
