前言¶

DeepSeek Harness（DSH）的日常狀態分散在 $DSH_HOME：各 profile 的插件清單、本地 link: 插件源碼、歷史會話、工作區列表、skills 軟鏈、市場分組與停用記錄等。換電腦或重裝系統時，若只拷貝部分目錄或整包複製 ~/.dsh，常見結果是「能啓動但和舊機不一樣」：插件加載不對、會話列表空、工作區路徑對不上。

社區插件 dsh-sync（維護者 huangfuren，分類：工作流）針對的是「聲明層 + 狀態層」一起遷走，並在目標機按路徑映射改寫會話與工作區記錄。導出物是一個可移植 bundle，並附帶 apply.ps1 / apply.sh；接收方不必安裝 dsh-sync，跑一次腳本即可恢復聲明層；若需要路徑重映射、會話 cwd 改寫與一致性覈對，則在目標機使用插件提供的 dshsync_apply / dshsync_verify 工具。

這是什麼¶

dsh-sync 把本機 dsh 配置與狀態打包成 dsh-sync-bundle：包含 settings（憑據可選）、各 profile 的清單與 patch、link: 插件 vendored 源碼，以及 sessions、storages、skills 等狀態層內容。bundle 內帶整包 sha256 校驗與自安裝腳本。

插件當前版本爲 0.4.2（見倉庫 package.json），許可證 MIT。實現爲原創 JavaScript，運行時僅依賴 Node 內置模塊；在 SkillHub 插件目錄 可查看條目，源碼在 GitHub：huangfuren/dsh-sync。

兩層狀態：缺一層就不算「一致」¶

README 把遷移對象分成兩層，下面介紹各自包含什麼、缺了會怎樣。

聲明層：settings.yaml、可選憑據、home 級 cordis.patch.yml、AGENTS.md、每個 profile 的 package.json / cordis 相關文件 / pnpm-workspace.yaml / .dsh-market/state.json，以及每個 link: 插件的源碼。缺了會導致 dsh 起不來、插件未加載、停用與分組回到默認，或 agent 行爲與舊機不同。

狀態層：sessions/、storages/、skills/、attachments/、background/、dsh-market/、llm-deepseek/。缺了則 dsh 能跑，但歷史會話、工作區列表、skills、附件與背景等爲空。

profiles/<n>/package.json 同時決定「裝什麼」（dependencies）和「加載什麼」（dsh.profile.bundles）。導出時會把其中的 link: 絕對路徑改寫成 link:../../plugins/<name>，指向 bundle 內 vendored 的源碼，目標機 $DSH_HOME 位置可變。

下列內容 intentionally 不搬：node_modules（含平臺相關原生模塊）、dsh-runtimes、cache、logs、.anonymous-user-id（機器身份）。

核心功能¶

導出（源機只讀）¶

在已安裝並啓用插件的源機上調用 dshsync_export。導出過程只複製，不修改源機配置。

兩種落地路徑¶

會話改寫依賴 zstd 多幀讀寫（只替換首幀 header 中的 cwd，事件區逐字節保留）；PowerShell 腳本路徑做不了幀級改寫，因此完整遷移需 Node ≥22.15 的內建 zstd（README 已知限制中寫明低於此版本時會話不遷移並告警）。dshsync_apply 與腳本共用 lib/path-map.js 的映射規則。

軟鏈與傳輸¶

軟鏈實體不直接打進 bundle，而是寫入 state/links.json，落地時再重建，避免 zip、網盤或部分傳輸通道把符號鏈接攤平。README 提到與 dsh-localsend 的 localsend_smb_push 聯用時，打包器會跳過軟鏈，links 清單機制仍適用。

密鑰與 bundle 安全¶

默認不導出 .credentials.yaml；settings 中疑似明文密鑰會剔除並告警。推薦設置 credentialPassphrase（≥6 位），對 settings 與憑據做 AES-256-GCM 加密搬運。apply 前校驗 checksums；覆蓋前備份到 $DSH_HOME/.dsh-sync-backup-<時間戳>/。

安裝與啓用¶

README 未給出固定的 dsh plugin add … 一行命令。請在 SkillHub 目錄頁 按社區說明，在源機（以及需要在目標機使用 dshsync_apply / dshsync_verify 時）安裝插件。

安裝前建議自行查看 GitHub 倉庫源碼與 MIT 許可證。插件在 當前 dsh 進程權限下運行，導出會讀取 $DSH_HOME 下的配置與會話；憑據相關選項會觸及密鑰文件，請按 README 的密鑰策略選擇加密或省略。

環境要求（來自 package.json）：Node ≥22.19；dsh 版本需滿足其 engines.dsh 範圍。peer 依賴包括 @deepseek-ai/dsh-tools 與 @deepseek-ai/cordis。

典型用法¶

1. 舊電腦：導出 bundle¶

先用預覽確認掃描結果，再去掉 preview 正式導出：

dshsync_export(profile="*", includeCredentials=true, credentialPassphrase="<你記得住的口令>", preview=true)

正式導出後得到 dsh-sync-bundle/（默認輸出目錄名，可通過 settings 命名空間 sync 的 outDir 調整），其中包括 manifest.json、checksums.json、改寫後的 profile 與 plugins/、state/、以及 apply.ps1、apply.sh 和 APPLY.md。

2. 拷貝 bundle¶

將整個文件夾拷到新機器（U 盤、網盤、局域網等均可）。

3. 新電腦：落地¶

若盤符、用戶名或項目根路徑不同，必須提供映射；建議先 dryRun=true：

dshsync_apply(bundleDir="D:/incoming/dsh-sync-bundle",
              mappings=[{"from":"D:/deepseek","to":"E:/code"}],
              dryRun=true)

確認預演無誤後設 dryRun=false 執行。兩臺機器目錄結構完全一致時可省略 mappings。映射按書寫順序應用，首條命中即返回，且命中須在路徑段邊界（README 有具體說明，勿自行改爲「最長前綴優先」）。

若只需恢復聲明層、且路徑無需改寫，可僅運行 bundle 內的 apply.sh 或 apply.ps1，無需在目標機安裝 dsh-sync。

4. 新電腦：覈對¶

dshsync_verify(bundleDir="D:/incoming/dsh-sync-bundle")

工具按 I1–I10 共 10 項不變量給出 PASS / FAIL / WARN；README 對每一項有表格說明。FAIL 表示該部分狀態 dsh 無法正確看到，不是輕微差異。

settings 命名空間 sync（節選）¶

適用場景與注意¶

適合：換機、重裝後希望新機 dsh「與舊機同一套插件、會話、工作區列表與 skills」；開發機與筆記本之間遷移本地 link: 插件與 profile 狀態；需要在目標機驗證遷移是否完整。

務必注意：

• 落地後目標機需自行 pnpm install 或 dsh plugin add 重建 node_modules，verify 的 I9 會以 WARN 提醒，不會靜默略過。
• 會話 cwd 指向的工作區代碼在 $DSH_HOME 之外；僅遷 dsh 狀態時，目標機缺少對應目錄則會話可列出但打不開，I8 會列出缺失路徑。需同步拷貝倉庫，或用 mappings 指到已有目錄。
• includeState=false 時得到的是「能用的空環境」，不帶歷史會話與工作區記錄。
• 社區目錄 SkillHub 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；插件星標以目錄頁展示爲準（當前線索爲 0）。

結尾¶

dsh-sync 解決的不是「拷貝一個文件夾」，而是按 DSH 真實數據結構導出、改寫路徑依賴、並在目標機可腳本化落地與覈對。導出端只讀；接收端可以只靠 bundle 腳本恢復聲明層，完整會話與工作區遷移則依賴 Node 側的 apply / verify 工具。

• 插件目錄：https://www.skillhub.cn/plugins/huangfuren/dsh-sync
• 源碼與詳細說明：https://github.com/huangfuren/dsh-sync