DSH 的會話、插件清單和設置分散在多臺機器上時，恢復和遷移比較麻煩。現有的基於 Git 的方案通常需要 git 二進制支持，且處理衝突和合並比較複雜。minghuo/dsh-github-sync 插件通過 GitHub REST API 解決這些問題，把配置備份到私有倉庫，並在另一臺機器上按整機或單會話恢復。
核心能力¶
- 多機同步：支持在多臺機器間同步會話、插件清單與設置。
- 純 REST API：不依賴 git 二進制，沙箱環境也能用，token 不會落進配置文件。
- 獨立目錄：每臺機器在倉庫裏擁有獨立的
instances/<實例ID>/目錄，互不重疊，無需合併文件。 - 恢復模式：支持按整機、工作區或單會話恢復，支持 dryRun 預覽。
- 內容尋址：基於 SHA1 哈希比對，未變化的會話不重複上傳。
- 瀏覽與閱讀：本機或遠端瀏覽會話清單，支持直接閱讀 zstd 壓縮的日誌（需 Node ≥ 22.15）。
- 工作區重映射：恢復時可將遠端的工作區目錄名映射到本機路徑，確保文件落在正確的位置。
- 本地快照：支持在推送前或恢復前自動拍快照，用於快速回滾。
- 安全與私有：強制私有倉庫，令牌只寫不回讀，對狀態修改請求校驗同源。
安裝與啓用¶
在 Web UI 對應的 profile 下安裝：
dsh plugin --profile web add github:minghuo/dsh-github-sync
安裝完成後重啓 dsh web 使插件生效。
配置與備份¶
- 在 GitHub 建一個私有倉庫（插件不代建，公共倉庫會被拒絕）。
- 創建一個 fine-grained PAT，只授權該倉庫。權限勾選
Contents: Read and write（若使用 PR 模式，還需勾選Pull requests: Read and write）。 - 打開 Web UI → 設置 → GitHub 同步，填入倉庫 URL（
owner/repo或完整 URL）、分支名和令牌，保存。 - 點擊“驗證倉庫”確認可寫且爲私有，隨後點擊“立即備份”。
恢復與會話管理¶
在另一臺機器上安裝相同的插件並配置相同的倉庫後，進入“會話備份”頁面即可查看並恢復遠程內容。
- 定時備份：在“概覽 → 自動備份”中開啓。設置
autoSync爲 true，並指定intervalMinutes（最小 5 分鐘），支持啓動時備份一次。 - 瀏覽：
- 本機瀏覽：按工作區分組，顯示會話數、體積、最近修改時間及最大日誌文件名。
- 遠端瀏覽：列出每臺機器備份的工作區與會話統計信息。
- 恢復：支持整臺機器、單個工作區或 dryRun 模式。恢復前會自動拍本地快照（
pre-restore-*）。 - 工作區重映射：解決兩臺機器上同一項目路徑不同的問題，恢復時將遠端目錄名映射到本機路徑。
- 閱讀日誌：點擊會話名即可在頁面內解壓查看 zstd 日誌文本。
同步內容與限制¶
同步內容¶
插件提供三類內容的同步開關，關閉某類既不上傳也不會刪除雲端已有內容：
| 分組 | 默認 | 內容 | 排除項 |
|---|---|---|---|
sessions |
開 | $DSH_HOME/sessions/** |
*.tmp、session.lock、.dsh-mkdir* |
plugins |
開 | 各 profile 的 package.json、cordis.patch.yml、pnpm-lock.yaml、pnpm-workspace.yaml |
node_modules、cordis.yml、.dsh-market、.dsh-module-fallback |
settings |
關 | $DSH_HOME/settings.yaml |
— |
本地機密（如 .credentials.yaml、.anonymous-user-id）從不參與同步計劃。
安全與已知限制¶
- 令牌安全：令牌只寫不回讀，存儲在
settings命名空間或$DSH_HOME/dsh-github-sync/config.json。 - 私有強制：每次推送前會檢查倉庫元數據，
private !== true直接拒絕。 - 跨機恢復：不會改寫會話 header 裏的
cwd（日誌體中的絕對路徑保持原機器路徑）。 - 文件限制：GitHub 單個 blob 上限 100 MB，默認跳過超過 45 MB 的文件。
- 樹接口限制：會話目錄樹很大時，GitHub tree 接口可能返回
truncated，此時只做增量比對。 - 共存：與遺留的
~/.dshgit 倉庫並存，插件不會觸碰該目錄。 - 不參與同步項：
$DSH_HOME/storages/workspace.json（工作區註冊表）、$DSH_HOME/attachments（附件）不在同步範圍內。
生態背景¶
DSH 理念是“一切皆插件”，該插件已上架 SkillHub 插件目錄（獨立站點，與 DeepSeek 無官方從屬關係）。
