前言¶
DeepSeek Harness（DSH）裏，一段會話並不只是聊天日誌：sessionId 落在 ~/.dsh/sessions/<projectKey(cwd)>/<sessionId>/ 下，日誌 frame 1 裏又寫了一份 cwd，~/.dsh/storages/workspace.json 裏的 workspace.sessionIds 再決定它出現在哪個工作區列表。想換目錄或合併工作區時，手改文件夾或 registry 很容易撞上三類實際問題：複製而非移動導致重複 sessionId、registry 指向已刪除數據使整個工作區打不開、或在 DSH 運行時直接改 workspace.json 被內存中的 registry 覆蓋。下面介紹社區插件 dsh-session-migration（維護者 Alvin070911），在會話頭提供一個按鈕，按 DSH 自身的存儲約定做遷移、備份與健康檢查。
這是什麼¶
dsh-session-migration 是 DSH 客戶端插件：在任意會話頭部的 utilities 區出現一個圖標按鈕（雙面板加箭頭），打開遷移面板。它把整段會話的 log、header.cwd、工作區歸屬 一併遷到目標工作區或自定義目錄，並附帶會話瀏覽、一鍵導出備份、工作區健康檢查。實現上只調用 DSH 自帶服務，遵循「移動而非複製」、只改 frame 1、通過 live workspaceRegistry 寫註冊表等約定。當前 GitHub 星標爲 0；package.json 版本爲 0.1.0，許可證 MIT。
生態上，DSH 以「一切皆插件」組織能力；SkillHub 目錄頁 是社區站點，與 DeepSeek / 幻方無官方從屬關係。
核心功能¶
資料中列出的能力如下，寫入正文前已與 README 對齊。
會話遷移¶
- 遷到已有工作區，或通過「custom path」瀏覽/輸入任意目錄。
- 先 preflight，再執行；自動備份、字節級校驗、失敗自動回滾，並輸出可複製的手動回滾命令。
- 可選把源工作區 頂層文件/目錄 一併挪到目標；若目標存在同名項則拒絕；源目錄保留爲空目錄，以免同目錄下其他會話失效。
- 當前正在使用的會話不能遷移自身（日誌仍被打開，插件會拒絕）。
會話列表與健康檢查¶
- 列表展示：id、工作目錄、日誌大小、frame 數、最後寫入、當前歸屬、問題標記。
- 健康檢查覆蓋：懸空引用、重複 id、header 與目錄不一致、空日誌、工作區目錄缺失、未註冊會話等；其中 dangling-reference 可通過 live registry 一鍵清理，無需關閉 DSH。
導出備份¶
將 session 目錄複製到你指定的目的地，並附帶 migration-export.json 清單，不修改 registry。
安裝與啓用¶
安裝命令以倉庫 README 爲準，不要用名稱自行拼接 dsh plugin add。
本地目錄（自託管常用）：
plugin_manager install_bundle target = C:\path\to\dsh-session-migration
從 GitHub：
plugin_manager install_bundle target = git+https://github.com/Alvin070911/dsh-session-migration.git
也可在 profile 的 cordis.patch.yml 中自行插入：
- insert:
- id: session-migration
name: dsh-session-migration
瀏覽器端由 dsh.client 聲明自動加載。若按鈕未出現，刷新頁面一次——新裝的客戶端 bundle 需要頁面重新遍歷模塊圖。
插件在 cordis.patch.yml 中支持 config（默認值見下）。數據目錄位於 <dshHome>/plugin-data/dsh-session-migration/（pending.json、自動備份、手動導出等）。
- id: session-migration
name: dsh-session-migration
config:
backupBeforeMove: true
keepBackups: 10
tryImmediateAttach: true
pendingApplyDelayMs: 2500
dshHome: ''
sessionsRoot: ''
dshHome 默認爲 $DSH_HOME，否則 ~/.dsh；sessionsRoot 默認爲 <dshHome>/sessions。
安裝前建議在 GitHub 倉庫 閱讀源碼與 MIT 許可證。插件以當前 DSH 進程權限訪問會話與 registry，僅在可信環境安裝。
典型用法¶
按 README 的可復現流程操作：
- 打開任意會話，在頭部 utilities 找到遷移圖標。
- 在左欄選擇要遷移的會話（不能選當前正在使用的會話）。
- 選擇目標工作區，或切換到「custom path」輸入/瀏覽目錄。
- 閱讀 preflight：project-key 變化、目標 session 路徑、是否會新建工作區、可選文件遷移的數量與衝突。
- 點擊「Start migration」，再「Confirm migration」。
- 結果按步驟列出：backup → data move → header rewrite → verification → file move → workspace membership。
關於「需要重啓」¶
工作區歸屬寫入可能報告 pending-restart，這是設計行爲而非失敗：live workspace registry 是啓動時從 session header 建的快照，插件無法在運行時原地刷新；運行中手寫 workspace.json 屬於資料中的 crash mode C。membership 會進入隊列 ~/.dsh/plugin-data/dsh-session-migration/pending.json，在下次 DSH 啓動後應用並寫日誌。一般只需重啓一次，會話即出現在新工作區；「Pending」頁也可嘗試更早重試。
安全模型與日誌處理（簡要）¶
README 強調的不變量包括：只移動不復制；registry 僅通過 workspaceRegistry 且在數據就位後寫入；只改 frame 1 的 cwd；frame 1 之後內容做完整性比對；重複遷到同一目標爲 same-target 無操作；失敗會回滾數據與 .bak，並打印回滾命令。
另一點對開發者重要：不要用 zlib.zstdDecompressSync(log) 當整文件解壓——它通常只返回第一幀 header，誤判爲空會話可能刪掉真實歷史。本插件按 RFC 8878 走幀邊界（必要時 magic 掃描），分塊計幀，僅替換 frame 1。
手動回滾時，須在 DSH 完全退出 後按遷移輸出中的命令操作；目錄內 session.v4.jsonl.zstd.bak 是改寫前的日誌，DSH 不會把它當作正式代次。若要撤銷排隊中的 membership，還需從 pending.json 刪除對應項。
適用場景與注意¶
適合： 需要把某段會話連同 cwd 與工作區歸屬遷到新目錄；希望批量瀏覽會話、做 registry/磁盤一致性檢查；遷前自動備份或單獨導出備份。
注意：
duplicate-session、cwd-mismatch、id-mismatch、空/缺失日誌等需按健康檢查說明人工處理，不能一鍵修。- 可選「搬走源目錄頂層文件」遇重名會直接拒絕。
- membership 變更常需一次 DSH 重啓纔在 UI 中完全體現。
結尾¶
dsh-session-migration 把「遷 session 目錄 + 改 header + 改工作區註冊」收成會話頭的一個面板，並圍繞 DSH 真實的三處綁定關係做了 preflight、備份與回滾。若你在多工作區、多目錄間整理會話，可先裝 bundle、刷新頁面，再用健康檢查摸清現場，再做單次遷移。
