前言¶

DSH 插件開發者需要將代碼發佈到 GitHub。dsh-github-sync 插件將本地工作區的 DSH 插件作爲“乾淨副本”推送到獨立的 GitHub 倉庫。它按需觸發，平時不注入系統提示詞，且 Token 僅存本地一次。

核心設計¶

安全機制¶

插件採用雙階段安全確認機制（Tool Guard）。Token 存放在 %USERPROFILE%\.dsh\github-sync\config.，絕不進 git，密鑰掃描會阻斷敏感文件上傳。Token 權限需配置正確：經典 Token 需勾 repo，細粒度 Token 需 Contents: Read and write 和 Administration: write。

乾淨副本與增量同步¶

自動排除運行時文件（.git、node_modules、cache、dist、.env* 等）。符號鏈接不跟隨。智能增量同步對比工作樹與乾淨副本，未變動文件不擦寫磁盤，避免 Windows 文件句柄佔用衝突（EBUSY）。

標準 Git 流程¶

每個插件一個本地鏡像倉庫，存放在 %USERPROFILE%\.dsh\github-sync\mirrors。支持增量提交、真實歷史和普通 push。不強制覆蓋遠端，遠端有衝突會如實報錯。force 選項保留爲顯式操作，用於替換遠端歷史。

安裝與配置¶

DSH 插件加載時會自動生成配置模板。編輯用戶配置文件（不在任何倉庫裏）：
%USERPROFILE%\.dsh\github-sync\config.json

{
  "github": {
    "owner": "你的GitHub用戶名",
    "token": "ghp_xxxx 或 github_pat_xxxx",
    "topics": ["dsh-plugin"],
    "license": "MIT",
    "copyright": "你的署名或組織名"
  },
  "git": {
    "userName": "你的名字",
    "userEmail": "你的郵箱"
  }
}

提交署名默認按 token 所屬賬號派生，使用 GitHub noreply 郵箱。若使用自定義郵箱，需確保該郵箱已在 GitHub 賬號裏驗證過。

典型用法¶

命令與工具¶

• /git：快捷觸發入口，留空只讀調查，帶意圖發起同步。
• github_sync_status：只讀查看配置、token 來源、目標清單與判定結果。
• github_sync_plan：試運行（Dry Run），列出將提交/排除的文件與原因。
• github_sync_push：真正執行推送，需 confirm: true 確認參數或前置授權。

自然語言驅動¶

支持自然語言表達同步意圖，無需死板地連發兩次特定 /git 語法。

注意事項¶

• 插件自身絕不自動上傳，也沒有任何後臺輪詢/保存即上傳的鉤子。
• 單文件大小上限爲 100 MiB，超過 GitHub 硬上限會阻斷。
• 提交的作者署名默認關聯到你的頭像，但前提是郵箱已驗證。
• 若插件目錄含 .github/workflows/*.yml，推送時需額外勾選 Token 權限中的 workflow。