前言¶
在 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 適合在會話結束、切換上下文或需要向接手者移交工作時使用。它提供了一份基於事實的靜態交接文檔。
