前言¶

在多 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 仓库