前言¶
在 DeepSeek Harness（DSH）裏，用 dsh plugin add 裝好的第三方插件都落在某個 profile 的 node_modules 下。換一臺機器或重裝環境時，profile 從零開始，只能憑記憶逐個補裝插件名、版本和安裝來源。本地目錄或已下載的 .tgz 裝上的插件，同樣沒有現成的「整包帶走」辦法。
dsh-plugin-git-sync（維護者 daoyan2142）把當前 profile 裏已安裝的第三方插件打成帶源碼的 .tgz，推到你自己控制的 GitHub 或 Gitee 倉庫；在另一臺機器上拉取清單、比對版本、校驗 SHA-256 後再安裝。倉庫裏存的是包本體而不只是名稱列表，目標機不必仍能從原始 registry 拿到同一版本。
這是什麼¶
- 名稱：
dsh-plugin-git-sync（聯網工具類插件） - 版本 / 許可：1.0.0，MIT
- 運行環境：DSH 0.2.x（需
pluginManager的listBundles、installBundle；在 0.2.2-rc.1 上開發與測試）、Node.js ≥ 22.12 - 目錄頁：skillhub.cn 插件頁
- 源碼：github.com/daoyan2142/dsh-plugin-git-sync
DSH 生態是「一切皆插件」；社區目錄（如 SkillHub）獨立於 DeepSeek / 幻方，並非官方應用商店。本插件以當前 DSH 進程權限運行，安裝前請自行審閱源碼與許可證。
核心功能¶
推送側（機器 A）¶
- 調用
listBundles()，只處理已安裝的第三方插件。 - 解析每個包目錄，打成以
package/爲根的 tar.gz。 - 對每個 tarball 計算 SHA-256；超過平臺單文件上限時拆成
.partNNN分片上傳。 - 先上傳
sync/packages/*，最後寫入sync/manifest.json，避免上傳中斷時清單裏出現尚未存在的包。
拉取側（機器 B）¶
- 下載
sync/manifest.json，與本地已裝版本對比。 - 將結果分爲 install（未安裝）、same（版本一致）、differ（版本不一致）。
- 下載對應 tarball（或拼接分片），校驗 SHA-256 後調用
pluginManager.installBundle(tgz)。 - 安裝新 Host 模塊後需重啓 DSH。
設計上的幾個要點¶
- 倉庫攜帶 tarball 與哈希，減輕對遠程 registry 的依賴；從本地路徑或
.tgz安裝的插件，源碼會一併打進包。 - 導出是增量且冪等的：每次推送會重寫相同路徑的包；不會自動刪除——在 A 上卸載的插件仍會留在倉庫裏，需在 B 手動處理，或刪除
sync/packages/中對應文件並改manifest.json。 - 插件不會讀寫倉庫中
sync/以外的路徑。 - 大文件分片上限：GitHub 單片 768 KiB，Gitee 單片 4 MiB（見 README 說明）。
安裝與啓用¶
市場（上架後）：
Plugins → Discover → 搜索 "Git Sync" → Install
npm 或 Release 中的 .tgz：
# npm 發佈後
dsh plugin --profile web add dsh-plugin-git-sync
# 本地或 Release 的 tarball
dsh plugin --profile web add ./dsh-plugin-git-sync-1.0.0.tgz
包爲純 ESM，無構建步驟、無運行時依賴。安裝後需重啓 DSH 以加載 Host 模塊；通過市場安裝時會熱掛載。
配置¶
打開 Settings → Git 插件同步，填寫下表字段：
| 字段 | 說明 |
|---|---|
| Platform | GitHub 或 Gitee；切換平臺會成組切換下方三項，且 GitHub / Gitee 各保留一套設置，互不覆蓋 |
| Token (PAT) | 存入 DSH credentials 服務；界面只顯示已配置 / 未配置。GitHub 建議 Fine-grained token，Contents: Read and write（限定倉庫）；Gitee scope projects |
| Repository | owner/repo、完整 URL 或 git@host:owner/repo.git；倉庫須已存在 |
| Branch | 如 main、master；空倉庫需先初始化（例如 README）纔有可提交分支 |
非敏感配置：<profile>/.git-sync/settings.json。令牌引用名爲 GIT_SYNC_GITHUB_TOKEN 或 GIT_SYNC_GITEE_TOKEN，寫在 ~/.dsh/.credentials.yaml，不會進入 settings.json 或遠端倉庫。建議使用私有倉庫（README Security 一節）。
示例結構（平臺切換時 platform 字段指向當前 UI 所顯示的一側）：
settings.json
platform: "gitee"
profiles:
github: { repo: "…", branch: "main" }
gitee: { repo: "…", branch: "master" }
遠端倉庫佈局：
sync/
├─ manifest.json
└─ packages/
├─ some-plugin-1.2.0.tgz
└─ @scope/name → scope__name-1.0.0.tgz
典型用法¶
機器 A：首次導出¶
- 選擇平臺，粘貼 Token，點 保存。
- 填寫
owner/repo與分支，點 保存設置。 - 點 驗證倉庫，確認 Token、倉庫名與分支可讀。
- 點 導出並推送；結果行會顯示上傳包數量。
機器 B：恢復¶
- 相同平臺、倉庫、分支；Token 可用同權限的另一枚。
- 點 拉取並對比，查看 install / same / differ 三組。
- 對 install 組點 安裝全部缺失插件。
- 對 differ 組按行 覆蓋（顯示
local → remote）。 - 重啓 DSH。
日常更新¶
在 A 上增刪或升級插件後再次 導出並推送；在 B 上 拉取並對比，對版本變化的行執行 覆蓋。插件不會在導出前讀取遠端以推斷變更，而是以本地當前安裝集爲準全量寫回。
適用場景與注意¶
適合：多臺開發機、重裝系統後快速對齊同一 DSH profile 的第三方插件；希望把插件集（含非 npm 來源的安裝）備份到自建 Git 倉庫。
注意：
- 令牌僅授予目標倉庫的 contents 寫權限即可；仍須信任插件代碼與所同步的第三方包內容。
- 卸載不會從遠端同步刪除，需手動維護
sync/與manifest.json。 - 依賴 DSH 0.2.x 的
pluginManagerAPI；版本不匹配時勿假定行爲一致。
結尾¶
dsh-plugin-git-sync 把「已裝插件集合」當作可版本化的數據，經 GitHub 或 Gitee 在多機間搬運，並用清單與 SHA-256 約束安裝過程。進一步瞭解可訪問 SkillHub 目錄頁 與 GitHub 倉庫（含 中文 README）。
