Agent Reach 开发工具参考：围绕 gh CLI 构建 GitHub 仓库、Issue 与 CI 的自动化调研链路

本篇技术指南以 Agent Reach 技能参考文档 dev.md 为主体，系统讲解其「开发工具」分类中 GitHub CLI（gh）的完整命令体系——认证、仓库、Issue、PR、Actions、Release 与 API 访问，并深入 GitHubChannel 的源码实现，说明 Agent Reach 是如何在不触发副作用的前提下检测 gh 安装状态与认证配置，从而让 AI Agent 安全地以 CLI 方式读取和检索 GitHub 资源。

一、dev 分类在 Agent Reach 中的定位

Agent Reach 将 15 个平台能力按「路由表」组织，用户意图命中「GitHub/代码」时路由到 dev.md 这份参考文档（见 SKILL.md 的路由表：GitHub/代码 | dev | references/dev.md）。这份文档定义了 dev 场景下的工具集合：以 GitHub 官方命令行工具 gh 为核心，辅以外部 MCP 工具，覆盖仓库阅读、代码搜索、Issue/PR 管理、CI 状态查询等研发全流程操作。

从源码结构看，GitHub 对应的 channel 定义在 github.py：

class GitHubChannel(Channel):
    name = "github"
    description = "GitHub 仓库和代码"
    backends = ["gh CLI"]
    tier = 0

• tier = 0 表示零配置可用：对公开仓库的阅读与搜索无需任何 API Key 或 Cookie 配置；
• backends = ["gh CLI"] 表明该渠道唯一后端是 gh CLI，不存在多后端切换；
• can_handle() 通过 host_matches(url, "github.com") 判断一个 URL 是否归属该渠道。

在零配置场景下，Agent Reach 推荐的 GitHub 快速命令就是 gh search repos "query" --sort stars --limit 10（SKILL.md 的「零配置快速命令」一节），对应典型任务如「这个 GitHub 仓库是做什么的」→ gh repo view owner/repo（见 README.md 的能力说明：GitHub 渠道支持读公开仓库 + 搜索；私有仓库、提 Issue/PR、Fork 需要登录态）。

二、gh CLI：认证与基本用法

dev.md 将 GitHub CLI 定位为「用于仓库、Issue、PR、Actions、Release 以及 API 访问」的官方命令行工具。认证是整个体系的第一步：

# 认证
gh auth login
gh auth status

需要特别理解的是 Agent Reach 对 gh auth status 的刻意回避。github.py 中有一段明确的源码注释：

_GH_READ_ONLY_ENV = {
    # gh 2.92 creates ~/.local/state/gh/device-id even for `--version` unless
    # telemetry is disabled. These are documented gh environment controls.
    "GH_TELEMETRY": "false",
    "DO_NOT_TRACK": "true",
    "GH_NO_UPDATE_NOTIFIER": "1",
    "GH_NO_EXTENSION_UPDATE_NOTIFIER": "1",
}

也就是说，check() 探测 gh 时只执行 gh --version 并注入上述只读环境变量，避免 gh 2.92 在执行任何命令（哪怕 --version）时写入 ~/.local/state/gh/device-id 副作用。check() 的文档字符串同样说明：「Doctor 不执行会写 device-id 的 gh auth status」。因此 dev.md 中的 gh auth login / gh auth status 属于用户手动交互命令（Agent 引导用户完成登录），而非 Agent 体检流程的一部分。

三、完整命令速查：从 dev.md 继承的全部命令组

以下命令组完整继承自 dev.md，是 Agent 在 dev 任务中可直接调用的操作手册。

3.1 搜索

# 搜索
gh search repos "query" --sort stars --limit 10
gh search code "query" --language python

• gh search repos 支持 --sort stars 按 Star 排序、--limit 控制条数，是「帮我找某领域热门开源项目」类任务的标准入口；
• gh search code 支持 --language 过滤，用于定位某语言下的具体代码用法。

3.2 仓库

# 仓库
gh repo view owner/repo
gh repo clone owner/repo
gh repo create my-repo --private
gh repo fork owner/repo
gh repo fork owner/repo --clone
gh repo sync owner/repo

命令	用途	是否写操作
gh repo view	查看仓库元信息（README、描述、可见性等）	否
gh repo clone	克隆仓库到本地	本地写入
gh repo create	新建仓库（--private 指定私有）	是
gh repo fork	Fork 上游仓库	是
gh repo fork --clone	Fork 并克隆	是
gh repo sync	同步 fork 与上游	是

调研类任务优先使用只读的 gh repo view；create/fork/sync 会在 GitHub 远端产生真实变更，Agent 执行前应明确获得用户授权。

3.3 Issues

# Issues
gh issue list -R owner/repo --state open
gh issue view 123 -R owner/repo
gh issue create -R owner/repo --title "Title" --body "Body"

-R owner/repo 指定目标仓库（也可用 --repo 长选项）。list --state open 是「这个项目的已知问题有哪些」类调研的常用查询；create 为写操作，需要认证。

3.4 Pull Requests

# Pull Requests
gh pr list -R owner/repo --state open
gh pr view 123 -R owner/repo
gh pr create -R owner/repo --title "Title" --body "Body"
gh pr checks 123 --repo owner/repo

gh pr checks 是 CI 联动的关键命令：在 PR 视角查看各检查项状态，配合下文的 gh run 命令可以构成「PR 失败定位」链路。

3.5 Actions / CI

# Actions / CI
gh run list --repo owner/repo --limit 10
gh run view <run-id> --repo owner/repo
gh run view <run-id> --repo owner/repo --log-failed
gh workflow list --repo owner/repo

--log-failed 只拉取失败 job 的日志，是排障场景下最小化的日志获取方式，避免下载整个 run 的全部日志。

3.6 Releases

# Releases
gh release list -R owner/repo
gh release create v1.0.0

3.7 REST API 兜底

# API
gh api /user
gh api repos/owner/repo

当结构化子命令不覆盖某个需求时，gh api 直接透传 GitHub REST API 路径，复用已有的 gh 认证与限流上下文，是最通用的兜底通道。

3.8 JSON 输出与 jq：面向 Agent 的结构化取数

# JSON 输出
gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'

这一条是 Agent 工作流中最重要的模式：--json 指定字段选择，--jq 做服务端侧（客户端 jq 引擎）的再投影。对 LLM 而言，把「100 条 Issue」压缩成「编号: 标题」两列，能显著降低上下文消耗。dev.md 中所有 list/view 类命令都可按此模式追加 --json 字段列表。

四、源码剖析：Agent Reach 如何「无副作用地」检测 gh

上面第三节的命令能跑起来的前提，是环境里有可用且认证齐全的 gh。Agent Reach 把这一前提检查封装在 GitHubChannel.check()（github.py），其判断链值得细读。

4.1 三级探测：missing / broken / ok

check() 首先调用 probe.py 的 probe_command("gh", ["--version"], timeout=10, ...)。probe 模块的设计目标是区分三种在 shutil.which() 视角下完全相同的失败形态：

• missing：PATH 上找不到 gh；
• broken：命令文件存在但执行失败（FileNotFoundError 指向 shim 本身，通常是 pipx/uv 安装的旧 venv 在系统 Python 升级后 shebang 断链），退出码 126/127 同样归类为 broken；
• timeout / error：能执行但行为异常。

对应的用户提示（见 test_channels.py 的断言）：

gh CLI 未安装。安装：<官方渠道>
gh 命令存在但无法执行——安装已损坏。重装即可修复：
  brew reinstall gh

4.2 不执行 gh，而是「读配置」确认认证

即使 gh --version 通过，认证状态仍不明确。check() 不做实时验证，而是走两条静态判断（github.py）：

1. 显式凭据：环境变量 GH_TOKEN / GITHUB_TOKEN，或 Agent Reach 自身配置中的 github_token 字段；
2. hosts.yml 落盘凭据：解析 gh 的凭据文件 hosts.yml，路径解析优先级为 GH_CONFIG_DIR/hosts.yml → $XDG_CONFIG_HOME/gh/hosts.yml → Windows 的 %APPDATA%/GitHub CLI/hosts.yml → 默认的 ~/.config/gh/hosts.yml。只要 github.com 条目下存在 oauth_token、user 或 users 任一字段，即判定「已检测到显式认证配置」。

读取过程本身也做了安全约束（见 test_channels.py 中 TestGitHubChannel 用例）：

• 通过 read_small_text_no_follow 限制只读 ≤1MB 且不跟随符号链接——测试验证了把 .config 软链到别处时，check 返回「无法安全确认」而非读取链接目标；
• 输出消息绝不回显用户名或 token——测试断言注入 user: alice / oauth_token: super-secret-token 后，消息中不包含 alice 与 configured-secret；
• check 期间执行的命令参数中不含 auth（assert "auth" not in cmd），确保体检不触发 gh auth 的任何行为。

4.3 体检结果：诚实的 warn 口径

最终 check() 返回的状态语义（配合 doctor.py 的汇总输出）：

情形	status	消息要点
gh 未安装	warn	提示从官方渠道安装 gh CLI
gh 安装损坏	error	给出 brew reinstall gh 重装处方
gh 可执行 + 检测到显式认证	warn	「显式认证配置；Doctor 不执行 gh auth status，未实时验证」
gh 可执行 + 未检测到认证	warn	「运行 gh auth login 完成登录」

用户侧统一通过 agent-reach doctor --json 查看（SKILL.md 的「动手前先体检」常驻规则），每个 channel 的结果包含 status、tier、backends、active_backend 字段。注意 GitHub 渠道在认证未实时验证时 active_backend 为 None，这是有意设计：与其声称「可用」，不如如实标注「未验证」。

五、工具选择指南

dev.md 末尾给出的三工具分工表完整如下：

工具	来源	用途
gh CLI	agent-reach	Git 操作
zread	my-mcp-tools	读仓库内容
context7	my-mcp-tools	查技术文档

三者互补：gh CLI 负责仓库对象级操作（仓库、Issue、PR、CI、Release、API）；zread 与 context7 则面向内容消费场景——前者读仓库内容，后者查技术文档。从源码结构看，全仓库范围内 zread、context7 仅出现在 dev.md 的这张表中，并未在 mcporter.json 等本仓库配置中注册，可以推断它们属于外部工具集 my-mcp-tools 提供的 MCP 能力，Agent Reach 在此仅做引用推荐，实际可用性取决于用户自行安装配置。

六、实操边界与注意事项

结合仓库源码与文档，使用本命令体系时注意以下边界：

1. 只读优先：Agent 工作流默认只使用 search / repo view / issue list / pr checks / run view 等只读命令；repo create、issue create、pr create、release create 等写操作会产生远端副作用，需用户明确意图后再执行。
2. 认证是静态检测：doctor 只确认凭据「存在」，不确认凭据「有效」。凭据过期时命令会直接失败，此时按 dev.md 的认证小节引导用户重新 gh auth login。
3. 结构化输出省上下文：凡是需要把结果喂给 LLM 的查询，优先 --json 字段投影 + --jq 再格式化（3.8 节），而不是让模型处理原始表格。
4. 临时产物落 /tmp/：SKILL.md 的工作区规则要求 Agent 不在工作区创建文件，gh repo clone 等命令的落盘位置应指向 /tmp/ 或用户指定目录，持久数据放 ~/.agent-reach/。
5. CI 排障链路：gh pr checks <n> 定位失败检查 → gh run view <run-id> --log-failed 拉失败日志 → gh api 查询 Actions 元数据兜底，三步组合即可覆盖绝大多数「CI 为什么红了」类问题。

以上命令与检测逻辑均以当前仓库版本为准；若 gh CLI 版本变化（源码注释中特别处理了 gh 2.92 的 device-id 写入行为），Agent Reach 的探测策略已在 _GH_READ_ONLY_ENV 中通过官方文档化的环境变量做了前向防护。