前言¶
在 DeepSeek Harness（DSH）裏做長任務時，上下文窗口遲早會頂滿。常見做法是壓縮歷史，或在 Step 邊界把狀態「簡報」成一條消息交給新會話。上一類方案 dsh-session-handoff 能跑，但簡報是散文式消息：沒有有效期、已完成與未完成容易打架，且每次交接都在上一條之上疊加，接手方越讀越長，往往還得回去翻日誌。下面介紹後繼插件 dsh-handoff-doc：在安全的 Step 邊界停住，由當前會話的模型寫一份帶有效期的快照文件，歸檔舊版，新會話只收到指向該文件的短指令。
這是什麼¶
dsh-handoff-doc（GitHub：ElioFanyu/dsh-handoff-doc，維護者 ElioFanyu）是 DSH 社區插件，當前 package 版本爲 0.2.0，MIT 許可。定位是：把長會話交接成一份文件，而不是一條消息。上下文快滿時，會話在 Step 邊界停下，生成 HANDOFF.md，上一版寫入 CHANGELOG.md 與 history/<月份>.md，在同一工作區開新會話並繼承 preset、模型、權限、Plan 模式，最後只投遞一條約 200 token 的指針消息。
與 dsh-session-handoff 的差異¶
這一版把內容搬進工作區文件，並立了幾條硬規矩：
| 規矩 | 機制 |
|---|---|
| 只留「現在仍然成立」 | 提示詞規則 + §9 只允許一行指針 |
| 不允許追加 | 每次交接整份重寫 HANDOFF.md |
| 歷史不能丟 | 覆蓋前歸檔進 CHANGELOG.md + history/<YYYY-MM>.md |
| 必須有有效期 | 頂部寫「到下一次提交爲止（HEAD xxxxxxxx）」 |
| 長度必須可控 | 按字符預算裁剪，先刪整節，再刪長節末尾，並留省略說明 |
缺任一必需小節（§0/§1/§2/§4/§6/§8）則放棄交接，不創建新會話；寫文檔失敗時原會話不動，零寫操作。
工作區裏的目錄與文檔骨架¶
默認目錄（<項目> 取工作區最後一級目錄名；monorepo 等場景用 handoffProjectFolder 指定）：
<工作區>/docs/handoff/<項目>/
├── HANDOFF.md # 當前快照，唯一要讀的文件
├── CHANGELOG.md # 每次交接一行條目
└── history/
└── 2026-10.md # 被覆蓋掉的交接文檔原文，按月份歸檔
固定十節：§0 30 秒自檢（命令由程序讀）、§1 目標與驗收、§2 當前有效事實、§3 卡點與阻塞、§4 下一步 + 驗證映射、§5 硬約束、§6 文件地圖（不寫行號）、§7 已否決方案、§8 已驗證 vs 未驗證、§9 歷史（一行指向 CHANGELOG，程序寫）。
新會話第一條消息不是正文，而是讀取順序指引：先跑 §0 裏的命令；自檢通過再讀 §2、§3、§4；自檢失敗或有效期已過則告知用戶文檔已過期，整份重寫後再開工。
命令與自動觸發¶
命令不進入模型可見歷史：
| 命令 | 行爲 |
|---|---|
/handoff |
立即交接成文檔並交給新會話 |
/handoff status |
階段、上下文佔用率、累計消費、閾值、最近結果 |
/handoff where（別名 doc） |
文檔路徑、大小、HEAD、是否已歸檔 |
/handoff cancel |
取消進行中的動作（下一安全檢查點生效） |
/handoff retry |
重試最近一次失敗 |
自動觸發字段與上一版 handoff 系列一致，例如 autoHandoffEnabled（默認 false）、autoHandoffTrigger（context / cumulative / either）、autoHandoffAtContextPercent（默認 85）等。文檔相關新增項包括 handoffDir（默認 docs/handoff）、handoffDocMaxChars（默認 24000）、archivePreviousHandoff、reusePreviousHandoff 等。交接與壓縮同時開啓時，autoCompactAtContextPercent 必須低於 autoHandoffAtContextPercent，否則拒絕保存。
插件聲明：不中斷正在執行的工作（等 whenIdle()）、不吞用戶消息、不刪改原會話日誌、失敗不假裝成功、不寫工作區外路徑（經 workspace-fs.ts 的 resolveInside 校驗）。
安裝與啓用¶
安裝命令以 README 爲準（本地路徑示例，需換成你本機克隆或下載後的目錄）：
dsh plugin --profile <profile> add "file:D:/path/to/dsh-handoff-doc"
安裝後重啓 DSH。宿主與瀏覽器端 UI 在同一包內。運行環境要求 Node ^22.19.0 || >=24.0.0，peer 依賴含 @deepseek-ai/cordis、@deepseek-ai/dsh-host-webserver 等（見倉庫 package.json）。
DSH 生態是「一切皆插件」；社區目錄 skillhub.cn 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。插件以當前 dsh 進程權限運行，安裝前應自行審閱源碼與 MIT 許可證。
典型用法¶
- 在長會話中執行
/handoff，等待 Step 邊界完成文檔寫入與新會話創建。 - 用
/handoff where確認docs/handoff/<項目>/HANDOFF.md路徑與對應 git HEAD。 - 在新會話中按指針消息：只讀 §0 跑命令，再讀 §2–§4 從 §4 第一條動作開始。
- 需要觀測觸發與佔用時執行
/handoff status；與dsh-session-handoff同時安裝時，不要對同一會話同時開自動觸發，否則會搶同一 Step 邊界。
倉庫自述驗證情況見 docs/handoff/dsh-handoff-doc/HANDOFF.md。
適用場景與已知限制¶
適合：單倉庫或多會話協作、需要可版本化、可重讀的交接快照，且希望接手方先跑自檢命令再讀事實的場景。
限制（來自 README）：協調狀態（階段、閂鎖、計數）僅在內存中，重啓後丟失；設置與已寫文檔不受影響。無工作目錄的會話無法交接。非 git 倉庫時 git 事實自動跳過。模型不上報 contextWindow 時佔用率觸發不可用（累計觸發仍可用）。custom 權限預設無名字可重放，只繼承審批策略。
結尾¶
dsh-handoff-doc 把會話交接從「越來越長的消息」改成「整份重寫 + 歸檔 + 字符預算」的單文件快照，並用短指針引導新會話先自檢再動手。目錄頁：https://www.skillhub.cn/plugins/ElioFanyu/dsh-handoff-doc；源碼與完整配置表：https://github.com/ElioFanyu/dsh-handoff-doc。
