前言¶

在多 AI 獨立協作的場景中，讓某個 AI 專注於特定 GitHub 倉庫的 PR 與 issue 變動（新建、push、評論、合併等）是一個常見需求。手動反覆去 GitHub 刷新頁面效率低下，而直接讓 AI 去輪詢 GitHub API 又容易觸發限流。

gh-watch 是 DeepSeek Harness (DSH) 的一個插件，旨在解決這一問題。它負責在後臺輪詢目標倉庫，一旦檢測到變更，就生成通知並注入 AI 的對話中。設計上，它嚴格區分“監視”與“行動”的邊界：插件只負責發現並通知，不進行代碼審查、不自動回帖、也不執行合併操作。

核心功能¶

gh-watch 提供了一套完整的監視與通知機制，主要包含以下能力：

• 會話級獨立配置：每個 AI 會話可以擁有獨立的監視器，互不干擾。你可以爲每個會話配置不同的倉庫列表、輪詢間隔、通知模式以及推送目標。
• 自動輪詢與變更識別：插件自動輪詢 GitHub 的 PR 與 issue 接口。它能識別 9 種變更類型：新建、新 push、新評論、評論變化、已合併、已關閉、重新打開、有更新、主動查詢。
• 基線快照機制：當首次監視某個倉庫時，插件會建立游標快照，不會推送歷史數據，避免因歷史記錄過多造成刷屏。
• 指數退避重試：輪詢失敗時，採用 2x→4x→8x 的指數退避策略推後下一次輪詢，直至某次完全成功後重置，有效降低撞 GitHub API 限流的風險。
• 狀態持久化：監視器的配置與游標快照會持久化到 $DSH_HOME/gh-watch/state，重啓進程後可恢復。

安裝與啓用¶

作爲 DSH 用戶插件，gh-watch 需要通過 cordis.patch.yml 掛載到你的 profile 中。

1. 安裝依賴：

    npm install
    # 或 pnpm install

2. 掛載插件：
   在你的 cordis.patch.yml 中插入以下內容，將插件加入 layer 棧：

    - insert:
        - id: gh-watch
          name: 'gh-watch'
          config: {}

3. 配置 Token：
   插件需要訪問 api.github.com。推薦使用只讀 Personal Access Token (PAT) 並通過環境變量或 DSH credentials 傳入。設置環境變量 GH_TOKEN 或 GITHUB_TOKEN 即可。

典型用法¶

gh-watch 向會話上下文註冊了四個工具，通過這些工具可以配置、管理監視器以及處理通知。

1. 配置監視器¶

調用 gh_watch_configure 來啓動對指定倉庫的監視。參數 repos 爲必填，intervalMin 爲輪詢間隔（分鐘），notifyMode 控制通知模式，pushTarget 控制通知落點。

// 通知模式：inform=僅告知，auto=通知並請AI檢查
// 推送目標：current=回當前對話，new=新開對話
gh_watch_configure({
  repos: ['psenY/gh-watch'],
  intervalMin: 10,
  notifyMode: 'inform',
  pushTarget: 'current'
})

2. 主動查詢¶

如果需要立即獲取某個 PR 或 issue 的最新狀態，可以調用 gh_watch_act。

gh_watch_act({
  repo: 'psenY/gh-watch',
  id: 123,
  kind: 'pull', // 或 'issue'
  target: 'current'
})

3. 確認通知（Ack）¶

插件推送的通知會附帶一個 ID（如 gw-xxxxx-1），處理完該條變更後，請調用 gh_watch_ack 確認，以便插件移除該條待辦。

gh_watch_ack({ id: 'gw-xxxxx-1' })

4. 查看狀態與停止¶

使用 gh_watch_status 可以查看當前會話的監視器配置與運行狀態（包括待確認的通知數量）。若需停止監視，可調用 gh_watch_stop。

// 查看配置與狀態
gh_watch_status()

通知確認與超時重推¶

gh-watch 引入了確認機制，以防止 AI 忙碌時遺漏通知。

• 確認機制：每條通知末尾都有 【本條 id: xxx】 標識。AI 處理完後需調用 gh_watch_ack。如果 15 分鐘內未確認，插件會再次提醒（最多 2 次），之後在日誌留痕。
• 配置：確認超時時間 ackTimeoutMin 和最大重試次數 ackMaxRetries 可在 gh_watch_configure 中配置（默認爲 15 分鐘和 2 次）。

適用場景與注意¶

gh-watch 適用於需要讓 AI 保持對特定代碼庫實時關注的場景，例如代碼審查助手、Issue 自動回覆機器人等。

注意事項：
* 權限分離：插件本身不執行任何審查或回帖操作，僅做通知。請確保 AI 或用戶具備相應的 GitHub 權限去處理這些變更。
* 網絡環境：插件運行環境需能訪問 api.github.com。
* 狀態文件：監視狀態存儲在 $DSH_HOME/gh-watch/state.json，修改該文件可能影響插件運行，不建議手動編輯。

結語¶

gh-watch 通過將“發現”與“決策”分離，降低了 DSH 插件開發的複雜度，也避免了 AI 無休止的刷屏。通過獨立的配置與完善的 Ack 機制，它爲多 AI 協作場景提供了穩定的 GitHub 監視能力。

• 插件目錄頁
• GitHub 倉庫