前言¶
DeepSeek Harness（DSH）運行時會在 home 目錄下寫入會話記錄、記憶文件、配置以及 profile 插件及其依賴樹。這些內容是用戶在 DSH 中的工作成果與狀態，通常沒有納入版本控制。手動備份這些文件容易遺漏或出錯，而依賴應用退出時的文件系統快照往往不夠可靠。
dsh-auto-sync 插件將 DSH home 目錄自動納入版本控制，並推送到用戶自有的私有 git 倉庫。它把 DSH 寫入 home 的內容作爲工作樹管理，支持跨平臺、可配置，且不對失敗保持沉默。
是什麼¶
dsh-auto-sync 是一個 DeepSeek Harness 插件，由維護者 wwwangzilin 開發，歸類爲聯網工具。它將 DSH home 目錄與用戶指定的 git 遠端關聯，自動同步變化並持久化歷史版本。
插件不連接本項目運營的任何服務器，也不攜帶任何憑據，遠端由用戶指定（可以是私有 GitHub/GitLab 倉庫、內網服務器或 NAS 上的裸倉庫）。
備份範圍¶
插件默認備份以下內容：
- 會話記錄：
<home>/sessions/** - 記憶文件：
<home>/memories/**、<home>/memory/** - 配置：
<home>/settings.yaml - Profile 插件：
<home>/profiles/<name>/ - 項目工作：用戶指定的目錄（可選）
憑據文件 <home>/.credentials.yaml 默認被排除，見安全模型。
工作原理¶
插件經 profile 的 bundle 層註冊，運行在宿主進程中，只負責調度。備份分爲兩條線：
熱備份線（進程內）
- 在對話結束時觸發，複製、提交、推送到分支
dsh-hot。 - 每輪對話結束後 30 秒觸發，並有 15 分鐘下限，保證長時間工具調用期間狀態仍能落盤。
完整快照（分離進程）
- 以分離進程運行，避免應用退出截斷快照。
- 定時執行（默認每日一次）以及退出時執行，提交到分支
dsh-snapshot。 - 包含 home 完整鏡像、profile 依賴清單與依賴樹。
兩條備份線獨佔一個分支和一份獨立的 git 工作區副本，避免併發備份時出現 index.lock: File exists 衝突。
環境要求¶
| 組件 | 版本 |
|---|---|
| DeepSeek Harness | >= 0.2.0-rc.2 |
| Node.js | ^22.19 \|\| >=24 |
| git | 2.30+ |
git 須在 PATH 中，啓動時探測。
安裝與啓用¶
從桌面應用安裝¶
- 在側欄打開插件頁。
- 選擇添加插件，填入本目錄的絕對路徑。
- 啓用
dsh-auto-sync組合包。 - 重啓 DeepSeek Harness。
從命令行安裝¶
dsh plugin --profile desktop add link:/path/to/dsh-auto-sync
首次運行¶
首次啓動且無配置時，插件寫入一份帶說明的模板到 <home>/sync-plugin/config.json，並記錄一條警告：在設置 remote 之前備份處於暫停狀態。
設置遠端有兩種方式：
命令方式（無需重啓）
/dsh-sync setup git@github.com:you/dsh-backup.git
編輯配置文件後重啓
{
"remote": "git@github.com:you/dsh-backup.git"
}
下次啓動時，插件初始化倉庫、爲每條啓用的備份線創建分支與工作區副本，並開始備份。
/dsh-sync 命令¶
需要 profile 提供 commands 服務（Web 與桌面 profile 提供，headless 與 ACP profile 不提供）。
| 命令 | 行爲 |
|---|---|
/dsh-sync |
報告遠端、各備份線及上次成功時間 |
/dsh-sync setup [地址] |
設置遠端並執行首次初始化 |
/dsh-sync remote <地址> |
僅修改遠端，不改動分支 |
/dsh-sync lines |
列出備份線及其分支 |
/dsh-sync workspace <路徑> |
啓用項目線並指定目錄 |
/dsh-sync workspace off |
關閉項目線 |
/dsh-sync run |
立即安排一次快照 |
/dsh-sync doctor |
診斷 git、倉庫、分支與工作區副本 |
命令產生的修改均寫回配置文件，結果可 diff。
設置頁¶
桌面版與 Web 版的「設置 → 插件」提供自動備份頁籤，與斜槓命令讀寫同一份配置文件：
- 填寫或修改遠端地址；首次配置保存後立即執行初始化，無需重啓。
- 查看各備份線的分支、啓用狀態、上次成功時間與最後一次錯誤。
- 指定同時備份的項目目錄，清空即關閉項目線。
- 手動觸發一次快照。
配置¶
配置文件位於 <home>/sync-plugin/config.json。
頂層鍵¶
| 鍵 | 類型 | 默認值 | 說明 |
|---|---|---|---|
remote |
string |
"" |
備份遠端地址，必填。支持 SSH 與 HTTPS。 |
remoteName |
string |
"origin" |
origin 已指向其他倉庫時使用的遠端名。 |
worktree |
string |
<home>-backup |
各備份線工作區副本的父目錄，須位於 home 之外。 |
locale |
string |
"zh" |
命令與引導語言：zh 或 en。 |
exclude |
string[] |
見下文 | 追加到 home .gitignore 的忽略規則。 |
userName |
string |
"dsh-auto-sync" |
git 未配置身份時使用的提交者名稱。 |
userEmail |
string |
"dsh-auto-sync@localhost" |
同上，郵箱。 |
home |
string |
$DSH_HOME 或 ~/.dsh |
覆蓋 home 目錄；顯式 --home 優先於環境變量。 |
默認忽略規則：
.credentials.yaml
**/node_modules/
*.log
.DS_Store
Thumbs.db
sync-plugin/.sync-status.json
memory/memory.db-shm
memory/memory.db-wal
備份線鍵¶
每條線均接受 enabled 與 branch。
lines.hot
| 鍵 | 默認值 | 說明 |
|---|---|---|
paths |
[".sync-status.json"] |
每輪對話後提交的文件，相對 home；解析到 home 之外的路徑會被拒絕。 |
debounceMs |
30000 |
最後一輪對話結束後的靜默期。 |
intervalMs |
900000 |
無條件刷新間隔，保證長時間工具調用期間狀態仍能落盤。 |
lines.snapshot
| 鍵 | 默認值 | 說明 |
|---|---|---|
intervalMs |
86400000 |
完整快照間隔。 |
profile |
"desktop" |
納入依賴樹的 profile。 |
includeNodeModules |
true |
在快照中重新納入該 profile 的 node_modules。 |
files |
清單文件列表 | 與依賴樹一同鏡像的 profile 文件。 |
lines.workspace
| 鍵 | 默認值 | 說明 |
|---|---|---|
enabled |
false |
未設置 source 時該線保持空閒。 |
source |
"" |
要鏡像的項目目錄絕對路徑。 |
exclude |
[".git", "node_modules", "dist", "build", "target", ".cache"] |
遞歸時跳過的目錄或文件；設置後完全取代默認值。 |
release 備份線¶
完整備份的另一種形態：將 home 打包爲 tar.gz 並作爲 release 資產發佈。
| 鍵 | 默認值 | 說明 |
|---|---|---|
enabled |
false |
是否啓用。 |
repo |
"" |
GitHub 倉庫，爲空時由 git 遠端推導爲 owner/name。 |
tagPrefix |
"dsh-backup-" |
tag 前綴。 |
keep |
5 |
保留最近 N 份。 |
intervalMs |
604800000 |
發佈間隔（7 天）。 |
includeNodeModules |
false |
是否包含 node_modules。 |
includeSecrets |
false |
是否包含憑據文件。 |
partSizeBytes |
1500000000 |
分片大小（約 1.5 GB）。 |
備份線類型¶
hot → dsh-hot¶
頻繁變化的小文件。文件複製進該線的工作區副本後提交併推送。默認在對話輪結束後 30 秒觸發，並有 15 分鐘下限。
snapshot → dsh-snapshot¶
home 的完整鏡像，附帶所配置 profile 的依賴清單與依賴樹。運行時機：每日一次、退出時一次，以及啓動時發現上次快照早於間隔的補跑。
workspace → dsh-workspace¶
鏡像指定的項目目錄，使代碼與其描述狀態一同版本化。默認關閉。構建產物與依賴緩存被排除，排除列表可配置。
release → GitHub Release 資產¶
將 home 打包爲 tar.gz 並作爲 release 資產發佈。適合長期歸檔與災難恢復，存儲爲壓縮包而非 git 歷史。
恢復¶
恢復整個 home
git clone <遠端地址> ~/.dsh
cd ~/.dsh
git checkout dsh-snapshot
dsh plugin --profile desktop install
恢復單個文件
git show dsh-snapshot:sessions/2026-01-01/....jsonl > restored.jsonl
恢復項目
git clone --branch dsh-workspace <遠端地址> project
git log dsh-snapshot -- <路徑> 給出單個文件的修訂歷史。
安全模型¶
默認排除憑據。首次運行時插件把 .credentials.yaml 及以上規則寫入 home 的 .gitignore。該文件保存服務商 API Key，不應推送。
插件接管而非覆蓋已有倉庫。如果遠端已存在內容，插件會將其視爲初始歷史，不再清空。
適用場景與注意¶
該插件適合需要爲 DSH home 目錄提供版本化備份的用戶，尤其是需要長期保留歷史狀態或進行災難恢復的場景。
插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證。配置文件與命令輸出均支持中文與英文，可通過 locale 字段或環境變量 DSH_AUTO_SYNC_LOCALE 控制。
總結¶
dsh-auto-sync 通過兩條備份線（熱備份線與完整快照）將 DSH home 目錄納入版本控制，支持增量更新與完整鏡像，並提供 release 資產歸檔選項。備份線獨立分支與工作區副本的設計避免了併發衝突，失敗可見的機制避免了靜默失敗。配合配置文件與設置頁，用戶可以靈活控制備份範圍與策略。
插件目錄頁：https://www.skillhub.cn/plugins/wwwangzilin/dsh-auto-sync
GitHub：https://github.com/wwwangzilin/dsh-auto-sync
