前言¶
在多臺機器上跑 DeepSeek Harness（dsh）時，Profile 裏的 package.json、cordis.yml、供應商配置等文本往往需要手工拷貝或自己寫腳本。DSH 插件市場支持 dsh-profile-backup 格式的導入導出，但若要在兩臺機器之間持續對齊、並一眼看出本地與遠端是否一致，仍需要額外工具。
dsh-profile-gist-sync 由 Meta-Virgo 維護，分類爲 admin-security，當前版本 1.1.1（MIT 許可證，要求 Node >= 20）。它把本機 Profile 配置備份到 unlisted secret GitHub Gist，可在另一臺機器拉取同步，並在設置頁面對比本地與雲端是否一致；同時向 Agent 暴露 config_backup 工具。下文介紹安裝步驟、頁面用法與同步時應注意的事項。
這是什麼¶
一句話：DeepSeek Harness 插件，提供 設置 → 插件 → 配置同步 / Config sync 頁面，以及 Agent 側 config_backup 工具，通過 GitHub Gist API（api.github.com）上傳/下載 dsh-profile-backup v0.2 文檔。
Gist 以 public: false 創建，屬於 unlisted、非 private：持有鏈接者可讀，鏈接本身即祕密。Gist id 記在 <profile>/.dsh-config-sync/settings.json，該文件不參與備份，避免同步時泄露來源機器的 Gist id。
核心功能¶
設置頁三步流¶
頁面按編號分三塊，每步對應按鈕，無需手打路徑：
- 狀態 — 打開時自動檢查雲端；展示本地與雲端是否一致、當前 profile、文件數量、上次上傳/同步時間。「重新檢查」可再查一次。
- 上傳 — 「上傳到雲端」更新本 profile 已記住的 Gist（首次會創建並記住）；「另存爲本地文件」把同一份備份寫到本地文件。
- 同步 — 「從雲端同步」將雲端副本寫入本機，之後可提供「撤銷上次同步」。同卡片會列出 manifest 中點名但本機未安裝的插件，並提供一鍵安裝。
Token、Gist id、從備份文件恢復、文件列表、新機清單等放在摺疊的 高級設置 中。
Agent 工具¶
除 UI 外，插件註冊 config_backup，供 Agent 以編程方式執行備份相關動作（含文檔所述的 undo 等）。
備份內容與排除項¶
備份攜帶 Profile 目錄中的文本配置：package.json、cordis.patch.yml、cordis.yml、.npmrc、pnpm-workspace.yaml、data/*.json、suppliers/* 及 profile 內其他文本文件。格式與 DSH 插件市場讀寫的 dsh-profile-backup v0.2 相同，可與市場導入導出互通。
明確不上傳並在 UI 中列出原因的路徑包括：node_modules/、pnpm-lock.yaml、.git/、*.bak、各類隱藏目錄（含 .dsh-config-sync/）、data/auths/credentials.sqlite 等二進制、data/usage.json（可按高級選項包含計數器），以及本機纔有的 dependencies 寫法（link:、file:、portal:、workspace: 或裸路徑）。後者會從上傳用的 package.json 中去掉對應條目並報告，避免在另一臺機器用無效路徑覆蓋目標機已有 spec。
恢復爲 合併式、可撤銷：備份中的文件會寫入，僅本地存在的文件保留；package.json 的 dependencies 與 dsh.profile.bundles 做並集合並，同名依賴以 incoming spec 爲準。每次覆蓋前會把舊內容快照到 <profile>/.dsh-config-sync/undo/<stamp>/。
網絡與憑證¶
插件測試要求僅連接 api.github.com。GitHub token 不會寫入磁盤，單次請求使用，來源可爲請求體、環境變量 DSH_GITHUB_TOKEN / GITHUB_TOKEN，或已登錄的 gh CLI；設置頁提供檢查 token 的按鈕。
安裝與啓用¶
在目標 profile 下執行官方 README 中的命令（示例爲 web profile）：
dsh plugin --profile web add dsh-profile-gist-sync # from npm
dsh plugin --profile web add github:Meta-Virgo/dsh-profile-gist-sync # from source
然後 重啓 DSH。包爲純 ESM，無額外依賴、無構建步驟、無安裝腳本。
插件在當前 dsh 進程權限下運行；安裝前建議閱讀 源碼倉庫 與 MIT 許可證，自行評估是否適合本環境。
典型用法¶
單機備份與對比¶
- 安裝插件並重啓後，打開 設置 → 插件 → 配置同步。
- 在高級設置中按需配置 token（或使用環境變量 /
gh登錄）。 - 使用 上傳 將本機配置推到 Gist，或在 狀態 區確認與雲端一致。
需要本地副本時，在同一頁使用「另存爲本地文件」。
第二臺機器同步¶
README 給出的可復現流程如下：
- 在該機器安裝本插件並重啓 DSH。
- 使用 與 Gist 所有者相同 GitHub 賬號 的 token。secret Gist 僅所有者可經 API 讀取；其他賬號會得到「not found」而非單純的 forbidden 提示。
- 打開配置同步頁，點擊 從雲端同步。
- 仍缺失的插件會出現在步驟 ③；點擊「安裝缺的插件」後再次重啓 DSH。
步驟 2 與 4 是新機器上最常見的失敗點，因此新機清單與 token 報錯說明集中在高級設置與頁面文案中。
若需改用新的 Gist：在高級設置清空 Gist id 並保存以創建新 Gist，或粘貼 id/鏈接以接管已有 Gist。
適用場景與注意¶
適合誰：需要在兩臺及以上機器之間對齊 DSH Profile 文本配置、又希望用 GitHub 私有鏈路（Gist + token）而非公開倉庫的開發者；admin-security 分類也適合關注「上傳了什麼、連了誰」的運維場景。
應注意：
- 僅文本配置出境；憑證庫、二進制、
node_modules等被排除，但 Gist 鏈接本身需妥善保管。 - 同步後插件包不會自動到位，需按頁面提示安裝 manifest 中的缺失 spec；
installBundle僅爲缺失項做加法，不會刪除或改寫已有 bundle 選擇。 - 從插件市場等其他來源導入的備份文檔若含本插件不寫的路徑（例如 credentials.sqlite），導入時會跳過並列出計劃，而非一律拒絕。
- 社區插件目錄 SkillHub 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；安裝與配置責任在用戶側。
結尾¶
經過上面的步驟，可將 Profile 配置收斂到一條 Gist 鏈路：本機上傳、他機同步、狀態區對比是否一致，必要時撤銷同步並補齊插件。進一步細節以倉庫 README 爲準。
