前言¶
在多臺機器上使用 DeepSeek Harness（DSH）時，Web 側配置、Cordis 補丁以及 Mnemon 記憶插件裏的內容往往只留在本機目錄裏。手工拷貝容易漏文件，也說不清哪臺是最新。社區插件 dsh-home-sync（維護者 OverDustD7，分類：記憶）把 DSH 主目錄裏允許同步的文件納入 Git 倉庫，支持拉取、推送到遠端、定時雙向同步、衝突檢測與 Web 界面操作，並附帶設備初始化時的備份與恢復說明。
這是什麼¶
dsh-home-sync 的定位是：基於 Git 的 DSH 配置與 Mnemon 記憶插件數據同步工具，具備自動雙向同步、跨設備遷移、初始化備份、衝突檢測和 Web UI。插件以 npm 包 dsh-home-sync 發佈（MIT 許可證），倉庫地址爲 OverDustD7/dsh-home-sync；社區目錄頁見 SkillHub 條目。SkillHub 上該倉庫星標爲 1。
運行環境要求 Node.js 20 及以上 與 Git；DSH 宿主需提供 webServer、timer 和 connection.requestRejection。README 記載本地驗證組合爲 DSH 0.1.2-rc.1、Node.js 24.20.0、Git 2.55.0.windows.4。
同步範圍與邊界¶
納入同步的典型路徑包括：
- 根目錄：
.gitignore、settings.yaml、cordis.patch.yml profiles/web/下：package.json、pnpm-lock.yaml、pnpm-workspace.yaml、cordis.yml、cordis.patch.yml、.dsh-market/state.jsonmnemon/下非隱藏文件，但會排除路徑組件名爲data、state、credential、credentials、secret、secrets的目錄，以及以.log、.wal、.shm結尾的文件
憑證、會話、附件和 node_modules 不會進入提交；若禁止同步的文件已被暫存或跟蹤，同步會被阻塞。推送前插件會審計即將發佈的提交及其樹（最多 1000 個提交）；審計範圍內一旦出現禁止文件，即使之後已刪除也會阻止推送。插件不會改寫允許文件內的字段——不應把不想上傳的內容寫進會同步的配置或記憶文件裏。
核心行爲¶
下面介紹 README 中描述的幾種操作方式。
Pull（拉取） 檢查遠端並嘗試 fast-forward；分支已分叉或可能覆蓋本地改動時會失敗，且不會自動生成本地提交。操作會顯式關閉 merge.autoStash，避免 stash 恢復衝突卻報告成功。
Sync to remote（同步到遠端） 會拉取並校驗遠端樹、提交允許的本地改動、整合遠端變更並推送；即使工作區乾淨，也會重試尚未推送的提交。
Automatic sync（自動同步） 按配置間隔執行完整同步週期；無本地改動時也會檢查遠端。保存開關或間隔會立即重建定時任務；同步進行中，配置保存等寫請求會返回 busy。
檢出分支須與配置分支一致；分叉分支可用常規 Git merge 整合。若出現內容衝突，插件會在推送前停止、中止未完成的 merge 並保留本地提交，需人工解決後再試，不會自動 force-push。
狀態約每 15 秒刷新，區分未提交文件、待推送/待拉取提交與讀失敗。操作結果有 toast 提示；操作歷史 默認摺疊，可展開查看備份路徑與恢復說明。最近最多 100 條手動與後臺操作記錄在 <DSH_HOME>.home-sync-history.json，不參與 Git 同步。當前 Web 界面標籤爲中文。
若跟蹤引用 refs/dsh-home-sync/branches/<branch> 因宿主進程異常而損壞，下次同步會刪除損壞的 ref 並重新 fetch，提示「已修復損壞的跟蹤引用並重新拉取。」
設備初始化¶
初始化兩種模式都會創建備份。merge 模式表示 先備份、再重置、再人工合併，不會自動合併兩套記憶。
經過上面的步驟概括，流程爲：
- 在獨立臨時倉庫 fetch 遠端，校驗目標路徑與文件類型
- 檢查本地路徑衝突，備份可能被覆蓋或刪除的文件、原有 Git 元數據與插件配置
- 確認備份期間本地文件未變，應用允許的文件，配置目標分支、origin 與 upstream
- 成功後暫停自動同步與啓動時拉取，便於檢查結果、手動合併後再開啓自動化
初始化支持新目錄、已 git init 但尚無首次提交的獨立倉庫，以及將現有環境切換到 unrelated history 的遠端。成功響應會返回實際配置，UI 會立即更新自動同步開關；初始化會重置 settings，表單會被服務端配置替換。備份位於 <DSH_HOME>.home-sync-backups/init-*，在同步範圍之外。
安裝與啓用¶
DSH 生態裏插件通過 dsh plugin 安裝；社區目錄 SkillHub 與 DeepSeek / 幻方無官方從屬關係，安裝前建議查看源碼與 MIT 許可證。插件以當前 DSH 進程權限運行，同步內容會進入你配置的 Git 遠端，請自行評估倉庫可見性與憑據安全。
從 npm 安裝（推薦）
dsh plugin --profile web add dsh-home-sync
安裝後重啓 DSH Web，並刷新瀏覽器以加載 UI。發佈包無需構建步驟或第三方依賴。
從 GitHub 安裝
dsh plugin --profile web add github:OverDustD7/dsh-home-sync
本地 link 開發
dsh plugin --profile web add link:D:/Project/DSH/dsh-home-sync
後端改動後需重啓 DSH Web，UI 改動後刷新瀏覽器。link: 會直接讀取源目錄，不要用臨時解壓目錄作爲長期 link 目標。
離線 / air-gapped 環境
在可聯網機器打包：
npm pack --pack-destination dist
在目標機、歸檔所在目錄執行：
dsh plugin --profile web add ./dsh-home-sync-0.2.3.tgz
若包管理器無法安裝本地 tarball，可解壓到固定目錄，對解壓後的 package 子目錄使用 link: 安裝。
典型用法¶
- 按上文命令以
--profile web安裝插件並重啓 Web。 - 在 Web UI 中配置 Git 遠端 URL、分支，以及是否啓用自動同步與間隔。
- 新設備或新目錄：使用初始化流程，按提示選擇模式；
merge模式下在暫停自動同步期間人工合併記憶後再開啓自動化。 - 日常在一臺機器改配置或 Mnemon 允許同步的文件後，使用「同步到遠端」；其他設備用 Pull 或依賴自動同步拉取。
- 若狀態顯示分叉或衝突，按 UI 與操作歷史中的備份路徑在本地 Git 中解決，再重試同步。
所有 HTTP 數據接口使用宿主認證與 Host/Origin 校驗；無該服務時插件不會激活。POST 僅接受 JSON。
適用場景與注意¶
適合需要在多臺電腦或重裝系統後恢復 同一套 DSH Web 配置與 Mnemon 可同步記憶文件 的開發者。不適合把密鑰、會話或未排除的敏感路徑交給 Git 遠端——插件有明確的排除與推送審計規則，但不會在允許的文件內做脫敏。
推送只更新所選分支，不自動跟隨 tag 或鏡像其他引用；多遠端推送不是單一事務，部分失敗需重試。符號鏈接、硬鏈接、子模塊、主目錄外路徑等會被拒絕。Git 子進程帶超時與非交互憑據設置；hooks 與 commit 簽名仍遵循本機 Git 配置。
結尾¶
dsh-home-sync 把 DSH 主目錄裏經過白名單與審計的配置、Mnemon 記憶數據納入 Git 工作流，用 Pull、推遠端、定時同步和初始化備份降低跨設備遷移成本。詳情以倉庫 README 爲準。
