前言¶

DSH 本地部署沒有云端存儲：會話落在本機 $DSH_HOME/sessions/ 下，換個電腦就接不上。把會話文件拷給同事，附件、工作區路徑都不對，還得手動改格式。dsh-github-sync 解決的是這個問題：把 DSH 會話連同引用的附件推到你自己的私有 GitHub 倉庫，另一臺機器拉下來就能繼續聊。它的前提是你有 GitHub 賬號和一個私有倉庫，它不提供服務器、不提供賬號體系。

下面介紹這個插件的定位、安裝方式和日常用法。

這是什麼¶

一句話定位：一個 DSH 插件，把本地會話與（可選）工作區文件夾同步到私有 GitHub 倉庫，用於跨設備接力。

• 名稱：dsh-github-sync，版本 0.5.1，MIT 協議
• 分類：記憶
• 目錄頁歸屬：lifeng4127；package.json 中作者字段寫作 mount9527，repository 字段指向 mount9527/dsh-github-sync。兩者指向同一包名與同一份 README，安裝時以倉庫搜索結果爲準。
• 同步是純手動的：不點不動，沒有後臺定時任務

核心功能¶

幾個值得留意的機制，來自 README 的「關鍵實現」一節：

1. 會話在磁盤上就是一個文件 session.v4.jsonl.zstd，所以不需要任何服務端。
2. 改寫 cwd 時只重壓第一幀，後面的幀字節原樣保留，否則會破壞 append-only 字節鏈，前綴合並失效。
3. 衝突判定只比對頭幀之後的 body：一方是另一方的前綴則落後方補上，互不爲前綴則分叉，遠端另存 *.remote-fork-*。
4. 前綴判定不下載遠端文件，靠 manifest.json 裏記錄的 body 長度與哈希做本地切片比對（README 給的例子是一條 2MB 會話的預覽從 134 秒降到 5 秒）。

倉庫結構：

README.md                        自動生成的項目/會話索引（每次上傳重寫）
manifest.json                    權威索引：會話 id → 路徑、原始 cwd、sha、附件列表
<項目>/sessions/<id>.jsonl.zstd  會話文件本體
<項目>/attachments/<sha>.<ext>   會話引用到的附件
<項目>/files/<相對路徑>           文件夾上傳的內容

manifest.json 裏的原始 cwd 是跨機還原的關鍵：下載時它會被改寫成目標機器的工作區路徑。

安裝與啓用¶

從插件市場安裝：在 DSH 的「插件」裏搜索 dsh-github-sync，安裝後啓用即可。

從本地目錄安裝（開發或自用）：打開 DSH →「插件」→ 添加插件 → 本地目錄，選這個文件夾；或者由 agent 調用 plugin_manager install_bundle，target 填絕對路徑；或者在 profile 的 package.json 里加 "dsh-github-sync": "link:<路徑>"，並把它加進 dsh.profile.bundles。

裝完左側邊欄出現「GitHub 同步」圖標，點開是面板。

大陸網絡下如果 npm 官方源很慢，用鏡像裝，注意鏡像同步有幾分鐘到幾小時的延遲：

npm install dsh-github-sync --registry=https://registry.npmmirror.com

客戶端改動按 F5 刷新頁面即可生效；宿主代碼改動需要重載插件（重啓 DSH，或在插件管理器裏關掉再啓用）。插件沒有原生模塊，Windows 和 macOS 跑同一份代碼。

典型用法¶

首次配置¶

1. 建一個空的私有倉。GitHub 新建倉庫，不要勾 README、不要勾 .gitignore，選 Private。README 強調空倉庫很重要：首次提交若倉庫已有文件會多一次合併。
2. 建一個 fine-grained PAT。打開 https://github.com/settings/tokens?type=beta → Generate new token，Repository access 選 Only select repositories 並只勾這一個倉，Contents 給 Read and write（勾選後會自動帶上 Metadata Read-only），其它權限全部 No access。令牌只顯示一次。
3. 面板裏填。右上角 ⚙ → 倉庫地址（owner/repo 或完整 URL 都行）+ 訪問令牌 → 測試連接。成功顯示 連接正常 · owner/repo；報「倉庫是公開的」要去 Settings 改成 Private；401 多半是令牌沒粘全，404 是倉庫名錯或令牌沒授權到這個倉。

沒連上倉庫時，面板頂部會出引導條，點「開始配置」進三步向導，每步帶官方頁面鏈接。需要更細的圖文步驟（截圖位置、常見錯誤對照、令牌輪換）看倉庫裏的 TUTORIAL.md。

上傳與下載¶

面板分兩欄：左邊遠端倉庫，右邊本地會話。所有寫操作都必須先預覽，預覽會逐個文件標註 upload / skip / blocked / copy 與原因，確認後才真正執行。被 blocked 遠端更新 擋住的行，行尾直接有「先下載」按鈕。

每條會話右側有同步徽標，由本地 body 哈希與遠端索引對比得出：

也可以直接用自然語言，插件會調 github_sync_transfer：

"把這條會話推到 GitHub"
"遠端都有哪些會話"
"從遠端把某某會話拉到這個工作區"

前者先 phase=preview 出清單，確認後再 phase=execute 帶同一個 token 執行。

傳輸過程中有文件級進度條（形如 12/30 · 上傳文件 · f12.bin），點左邊的 ▸ 能展開看過每個文件 等待 / 傳輸中 / 完成 / 已跳過。每個還沒開始傳的文件都有「跳過」按鈕，跳過附件會自動從 manifest.json 裏摘掉對應引用。取消在文件之間生效，ref 不更新，倉庫裏不會留下半個提交。傳輸狀態存在宿主進程裏，面板切走再回來會自動重新接上進度條，沒確認的預覽也會恢復。

刪除與衝突¶

刪除兩邊互不影響：本機行尾的 🗑 只刪本機會話並回收不再被引用的本地附件；遠端行尾的 🗑 只刪倉庫裏的會話並回收遠端附件。兩邊都要點兩次確認（4 秒內有效）。

兩端都動過同一條會話時，預覽會標 blocked 並給出三個選擇：「先下載」「用本地覆蓋遠端」「用遠端覆蓋本地」。選覆蓋會直接執行並重新預覽。

適用場景與注意¶

適合：兩臺及以上設備之間接力同一個任務，或把某臺機器上的會話交給同事接着幹；前提是 GitHub 可達、有私有倉庫。不適合：想要自動雲端備份、多端實時同步、或者會話需要跨組織權限管理的情況——它完全手動，且每臺機器上傳前先合併遠端索引，所以不會互相覆蓋記錄，但也意味着它不做實時衝突自動合併。

幾點必須留意：

• 插件以當前 DSH 進程權限運行，能寫 $DSH_HOME、能訪問當前工作區、能訪問 GitHub API。安裝前應讀一遍源碼，確認許可證（MIT）與依賴符合你的要求。
• 默認只寫四個位置：$DSH_HOME/github-sync/、$DSH_HOME/sessions/、$DSH_HOME/attachments/v1/objects/、當前工作區（文件夾/文件同步默認關閉，未開啓時相關接口直接返回 403）。
• 只允許私有倉，公開倉直接拒絕；.env*、*.key、*.pem、id_rsa、.npmrc、.netrc 等密鑰類文件二次確認也傳不上。
• token 只存在宿主進程的 $DSH_HOME/.credentials.yaml，面板不回顯；README 聲明插件不啓動子進程、不執行外部命令、不訪問 GitHub 以外的域名，這些不變量由 tools/audit-safety.mjs 靜態檢查，發佈前必跑。
• 倉庫會變大且 GitHub 不會自動清理舊 blob。會話在倉庫裏是固定路徑，歷史版本只佔空間不影響使用；要真回收需要 git clone --mirror 後用 git filter-repo 重寫歷史，或重建空倉。按 README 的建議，主要用途是接力的話，一個項目一個倉比混在一起好清理。
• 附件按會話引用上傳，未被引用的附件不會上傳；單個附件超過 25MB 會跳過並在預覽裏告警。插件只處理 version: 4 的會話格式。

結尾¶

dsh-github-sync 的價值很明確：把 DSH 本地會話變成可以跨設備搬運的普通文件，靠一個私有倉庫和一串 fine-grained token 完成接力，沒有額外的服務端。功能不算多，但上傳前先預覽、文件級跳過、取消不影響 ref、token 只在宿主進程這幾件事，說明作者對「手動操作可能出錯」這件事考慮得比較細。如果你本來就用 GitHub 管理私有倉庫、也接受手動同步的節奏，可以試試。

目錄頁：https://www.skillhub.cn/plugins/lifeng4127/dsh-github-sync
GitHub：https://github.com/lifeng4127/dsh-github-sync