前言¶
在 DSH 中移動一套完整配置到另一臺機器時，有三個常見痛點：profile 不是單個文件，而是由多個目錄和文件組成的樹；插件通過 pnpm 網絡安裝，離線環境或受限網絡無法安裝；配置文件內嵌絕對路徑，直接複製後路徑失效。dsh-portable 針對這些問題，提供一套打包、遷移、還原的方案。
是什麼¶
dsh-portable 是一個 DeepSeek Harness 插件，由維護者 wjf1 開發。它把當前 DSH home 中選定的內容打包成單個 .dshpkg 文件，包含 profile（含插件及其 node_modules）、skills、hooks、task boards、AGENTS.md 等內容，在另一臺機器上還原時自動修正路徑，無需網絡、無需 pnpm install，也不需要手動修復配置。
核心功能¶
打包與導出¶
插件在 DSH 設置中提供「便攜遷移」面板，導出時選擇要包含的根目錄，命名後導出。打包過程在後臺線程運行，約 14000 條目、20 MB 的包約 3 秒。可選項包括：
- sessions：會話日誌
- runtimes：已下載運行時
- credentials：.credentials.yaml
- source maps：*.map 文件
- backups：配置文件旁的 .bak- 文件
不包含在列表中的內容不會被收集，代碼中沒有遞歸複製整個 home 目錄的邏輯。
包管理¶
導出的文件保存在 <DSH_HOME>/dsh-portable/exports/ 下，面板中顯示文件名、大小、修改時間，提供選擇、下載、分享、刪除操作。選擇後用於導入卡片，下載將文件流出到瀏覽器，可在局域網共享或通過 U 盤傳遞。
導入與合併¶
導入支持「合併」或「替換」兩種模式。選擇後先預覽，零寫入，再確認後執行導入。導入結果以鍵值對展示：應用項、重寫的路徑、備份目錄、警告信息，以及插件列表合併情況（本地已有的 bundles 與包中需要的 bundles）。導入後需重啓 DSH 使配置生效。
局域網分享¶
LAN share 卡片可生成一次性下載鏈接，格式爲 http://<lan-ip>:<port>/d/<token>。默認限制爲 1 次下載、60 分鐘有效，支持 Range/HEAD 請求，過期或用盡後返回 410。鏈接複製到剪貼板時會校驗是否真正寫入成功。不使用中繼或雲服務，無賬號。
自動備份¶
在導入前，插件會自動在 <DSH_HOME>/portable-backups/<時間戳>/ 保存一份當前配置的副本，保留最近 5 個。每個備份提供「恢復」按鈕，恢復前會將當前版本保存爲 <時間戳>-pre-restore，恢復後同樣需要重啓 DSH。
HTTP API¶
插件提供 REST API，基礎路徑爲 /dsh-portable/api。所有響應爲 JSON，除下載和上傳文件流外。認證複用 DSH 的 connection.requestRejection 防護機制，無服務時回退到僅本地請求。
主要端點包括：
- GET
/status：主機信息、包數量、活躍任務、分享服務器狀態 - GET
/profiles：當前 DSH home 中的 profile 列表 - GET
/jobs：最近導出/預覽/導入任務 - GET
/jobs/detail?id=：單個任務及實時進度 - POST
/jobs/cancel：取消運行中的任務 - POST
/export：開始導出 - GET
/artifacts：可用於導入的包列表 - GET
/artifacts/meta?id=：單個包的清單 - GET
/artifacts/download?id=：以附件形式流式下載包 - POST
/artifacts/delete：刪除包（需 UI 確認） - PUT
/upload/<name>：流式上傳包到磁盤 - POST
/import/preview：預覽（零寫入） - POST
/import：執行導入（需 confirm:true） - GET
/backups：自動備份列表 - POST
/backups/restore：恢復備份 - POST
/share：創建一次性分享鏈接 - GET
/share：列出活躍鏈接 - POST
/share/remove：撤銷鏈接
所有接口使用 artifactId 而非文件路徑，拒絕 /、\\、.. 及控制字符，避免任意文件讀寫。
模型工具¶
插件在 host tools 服務註冊了三個工具：
portable_export：打包當前 profile，返回 id、大小、條目數、各根目錄的拆分portable_inspect：讀取包清單但不導入portable_import：dry run 模式下不寫入，帶confirm:true時執行兩階段安裝portable_share：創建一次性 LAN 鏈接（1 次下載、60 分鐘）
安裝與啓用¶
在 DSH 中執行以下命令安裝：
dsh plugin --profile desktop add dsh-portable
安裝後，在 DSH 設置中找到「便攜遷移」面板（順序 70，中英文雙語）。面板顯示前才進行寫入。
典型用法¶
離線遷移¶
在開發機器上導出包，通過 U 盤或局域網拷貝到目標機器。在目標機器的 DSH 設置中導入，選擇合併或替換模式，預覽後執行。導入後重啓 DSH，整套配置即可使用。
局域網快速分享¶
在兩臺同網段機器上啓動 DSH，在「LAN share」卡片中點擊複製，將鏈接發送給另一臺機器，即可直接下載包進行導入。
回滾操作¶
在導入前，插件已在 <DSH_HOME>/portable-backups/ 創建時間戳備份。若導入結果不理想，可在「Backups」卡片中選擇備份並恢復，恢復前會保存當前版本。
適用場景與注意¶
適合需要在多臺機器間同步或遷移 DSH 配置、在離線或受限網絡環境下部署 DSH、需要定期備份並快速回滾的場景。
注意：插件以當前 DSH 進程權限運行，安裝前建議檢查源碼與許可證（MIT）。所有文件操作均受限於配置的根目錄白名單，避免任意文件訪問。
結尾¶
dsh-portable 提供了一套從打包、傳輸到還原的完整流程，把 DSH 的配置管理從手動複製和路徑修復中解放出來。更多細節可查閱插件目錄頁與 GitHub 倉庫。
