前言¶

DeepSeek Harness（DSH）把智能體能力按模塊拆分成插件。在用 DSH 寫自動化或代理應用時，常會遇到需要與 GitHub 倉庫保持一致的場景：本地代碼要推到遠端，遠端變更要拉下來合併，CI 流水線要自動觸發和監控，這些操作分散在 git 命令、GitHub API 調用和 CI 配置裏，容易在多倉庫、多分支下出問題。

dsh-github-sync 插件提供一套統一的倉庫同步與 CI 監控能力。它把雙向 git 同步、Actions/CI 監控、倉庫管理、本地文件瀏覽這些能力同時暴露給 Agent 工具、Web 面板和定時器，讓這些操作可以在一個地方完成。

這是什麼¶

dsh-github-sync 是一個 DSH 插件，用於 GitHub 倉庫的雙向同步、Actions/CI 流水線監控、倉庫增刪改名、本地文件瀏覽與推送前檢查。插件本身零運行時依賴，需要 dsh 自帶的 pnpm。

插件維護者是 wzw4429-crypto，歸類爲「聯網工具」。

核心功能¶

雙向同步¶

插件對每個倉庫執行以下步驟：

1. fetch 遠端變更
2. 計算本地與遠端的關係（ahead/behind）
3. 合併入遠端（支持快進 / merge / rebase，衝突時回滾）
4. 運行推送前檢查
5. push 到遠端

同步結果分爲幾種狀態：up-to-date、pulled、pushed、synced 表示成功；dirty、diverged-report、conflict、checks-blocked 表示因工作樹狀態或檢查未通過而停住；error 表示 git 或環境失敗。

衝突策略¶

插件支持多種衝突處理策略：

• report（默認）：只報告衝突，不執行合併操作
• merge：嘗試合併
• rebase：嘗試變基
• prefer-remote：以遠端爲準
• prefer-local：以本地爲準

無論哪種策略，任何衝突都會中止操作並回滾，不會留下半合併狀態。

推送前檢查¶

可以爲倉庫配置一組 shell 檢查命令。每個檢查可以指定失敗時的行爲：

• block：阻止推送
• warn：記一筆日誌後繼續

檢查未單獨聲明 onFail 時，使用全局默認配置 onCheckFailure。

Actions/CI 監控¶

插件會自動補全或更新 .github/workflows/dsh-ci.yml（默認路徑）。工作流支持通過 workflow_dispatch 手動觸發，也支持在同步後自動觸發 CI 並輪詢運行狀態。

在 Web 面板中可以查看倉庫的 Actions 運行列表、某次運行的 jobs 與每一步的結論，並提供跳轉到 GitHub 對應頁面的鏈接。

Web 面板¶

側欄「GitHub Sync」面板提供以下功能：

• 倉庫卡片：顯示狀態、最近同步時間、CI runs
• 文件瀏覽器：直接讀取本地克隆磁盤的目錄/文件樹與文本預覽（文本 ≤128KB，二進制只顯示元數據）
• 一鍵操作：同步倉庫、觸發 CI、補 CI 文件
• 全部倉庫列表：顯示所有已註冊倉庫，支持一鍵加入同步、手動添加、移除
• 15 秒自動刷新

倉庫管理¶

插件會緩存用戶的 /user/repos 列表（5 分鐘）。要列出全部倉庫，需要在配置中提供 PAT。

「加入同步」會將倉庫克隆到 cloneRoot/<owner>/<name>（可指定本地路徑；若是已存在的 git 倉庫路徑，則直接註冊爲同步對象）。運行時加入的倉庫會持久化在狀態文件裏。「移除」只從列表中刪除，不會刪除磁盤上的文件。

改名同步¶

在面板或通過 Agent 工具對倉庫改名後，插件會調用 GitHub PATCH /repos API（需要 admin 權限）更新遠端，並在本地執行 git remote set-url。配置文件中的倉庫改名記錄會保存在狀態文件的映射裏，不改動 cordis.patch.yml。歷史提交與 CI 緩存會跟隨新的倉庫名。

活躍倉庫置頂¶

插件根據以下指標對倉庫排序：

• 未提交的改動（權重 1000）
• 頂層文件最新修改時間（權重 100）
• 最近提交時間（權重 60）

活躍倉庫會自動排在前面的位置，卡片上會顯示「使用中 / N 分鐘前」的徽章。

Agent 工具¶

插件暴露一組工具供 Agent 調用：

• github_sync：執行同步
• github_status：查看倉庫狀態
• github_ci：查看 CI runs / checks / status / run-detail
• github_workflow：列出或觸發工作流
• github_repos：列出、添加、移除、改名倉庫
• github_files：瀏覽本地或 GitHub 上的文件（默認 source: local）

定時同步¶

在配置中設置 intervalMinutes，插件會按週期自動同步全部倉庫。設置 runOnStart: true 會在啓動 5 秒後先跑一輪同步。

安裝與啓用¶

插件可以從 GitHub 直接安裝：

dsh plugin --profile <profile> add https://github.com/wzw4429-crypto/dsh-github-sync

安裝後重啓 dsh 使配置生效。也可以在插件發佈到 npm 後用包名安裝：

dsh plugin --profile <profile> add dsh-github-sync

配置方式¶

插件的 cordis.patch.yml 只聲明插件模塊，不帶任何配置。你的 token、倉庫列表、定時週期等需要寫在 profile 自己的 patch 層裏，按 id + 模塊名覆蓋：

- id: github-sync
  name: dsh-github-sync
  config:
    token: 'ghp_...'
    repos:
      - name: my-repo
        path: D:\path\to\repo

這樣密鑰與機器路徑不會進插件倉庫，插件升級也不會覆蓋你的配置。面板和工具運行時加入的倉庫會保存在狀態文件裏，無需修改配置文件。

認證¶

支持兩種認證方式，二選一（token 優先）：

1. 環境變量（推薦）：設置 GITHUB_TOKEN=<PAT> 或通過 tokenEnv 指向別的變量名。PAT 需要 repo 權限（訪問私有倉庫）和 workflow 權限（觸發 Actions / 寫入 workflow 文件）。
2. 配置直填：在 config.token 中填寫 PAT。

插件不會在日誌、工具輸出、面板或錯誤消息中顯示 token（redactedConfig 會脫敏）。git 的 fetch/push 通過環境注入 http.extraheader 使用 PAT，不會出現在進程參數中。無 token 或非 github.com https 遠端時，會回退到系統憑據助手或 SSH 密鑰。

配置項¶

在 profile patch 層的 github-sync.config 中可以配置：

- id: github-sync
  name: 'dsh-github-sync'
  config:
    enabled: true            # 總開關
    runOnStart: false        # 啓動 5s 後先跑一輪
    intervalMinutes: 30      # 定時週期
    tokenEnv: 'GITHUB_TOKEN'
    notifyAgent: true
    notifyOn: [conflict, error, checks, pipeline]   # 事件：conflict/error/checks/pipeline/pull/push
    autoCommit: false        # 同步前把髒工作樹自動提交
    conflictPolicy: 'report' # report/merge/rebase/prefer-remote/prefer-local
    onCheckFailure: 'block'  # 檢查未單獨聲明 onFail 時的默認：block/warn
    repos:
      - name: my-repo
        path: D:\path\to\repo
        remote: origin        # 默認 origin
        branch: ''            # 默認當前分支
        mode: bidirectional   # bidirectional/pull/push
        githubRepo: ''        # 可選顯式 owner/name；缺省從 remote URL 推斷
        workflowFile: ''      # 可選，補 CI 文件名，默認 .github/workflows/dsh-ci.yml
        checks:
          - name: test
            run: 'npm test'
            onFail: block     # block/warn
    pipeline:
      triggerCi: true         # 同步後 dispatch CI
      waitCi: true            # 輪詢到 run 完成
      waitTimeoutMinutes: 10
      pollIntervalSeconds: 20

狀態與數據¶

狀態文件保存在 <profile>/github-sync-state.json，每個倉庫包含：

• lastSync：最近同步時間
• lastPipeline：最近 CI 運行時間
• history：尾 20 條歷史記錄
• ci：CI 緩存信息

適用場景¶

適合需要在 DSH 中統一管理 GitHub 倉庫同步與 CI 監控的開發者或團隊，尤其是需要：

• 對多個倉庫進行雙向同步
• 在同步前後執行檢查
• 監控 CI 狀態並在需要時阻斷推送
• 通過 Web 面板或 Agent 工具統一操作倉庫

插件以當前 dsh 進程的權限運行。安裝前建議檢查源碼與許可證。

短結尾¶

dsh-github-sync 把 GitHub 倉庫的同步、CI 監控與文件瀏覽能力統一到 DSH 的插件體系裏，通過 Agent 工具和 Web 面板都可以調用。安裝後按 profile 配置 token 與倉庫列表，重啓 dsh 即可使用。

插件目錄頁：https://www.skillhub.cn/plugins/wzw4429-crypto/dsh-github-sync
GitHub 倉庫：https://github.com/wzw4429-crypto/dsh-github-sync