多个编码 Agent 同时查 GitHub，怎样少打重复 API？Ghx 用缓存代理加速 gh
当 Claude Code、Copilot CLI、脚本和 MCP 服务同时围绕一个仓库工作时，它们常会重复执行 gh pr list、gh issue view 等只读查询。结果相同，网络请求却一遍遍发出，既增加等待，也更容易碰到 GitHub API 限流。Ghx 是一个面向 GitHub CLI（gh）的缓存代理：它把重复的只读调用缓存起来，并把并发的同一调用合并为一次执行。
它解决的不是“所有 GitHub 请求”
Ghx 的定位不是通用 HTTP 缓存，而是 gh 的替代入口。官方 README 将它描述为 GitHub CLI cache proxy，项目采用 MIT 许可证；文档列出的缓存对象是明确 allowlist 中的只读命令，例如 PR、Issue、仓库、运行记录和 Release 的 list/view，以及 gh api 的 GET 请求。创建 PR、关闭 Issue 等变更操作则透传给原始 gh，并使相关缓存失效。
这条边界很重要：缓存写操作会带来陈旧状态或重复副作用风险。Ghx 的规则是优先缓存安全的查询，不把 mutation 当作可复用结果。文档还指出，API 请求只有有效 HTTP 方法为 GET 时才缓存；GraphQL、带输入 body 或无法确定选项的请求绕过缓存。因此不能把它理解为“任何 gh 命令都会变快”。
安装与基本使用
macOS / Linux 可通过项目提供的安装脚本安装：
curl -fsSL https://raw.githubusercontent.com/brunoborges/ghx/main/install.sh | bash
安装脚本根据系统和架构获取发布版本。安装后，直接以 ghx 代替 gh：
ghx pr list --repo owner/repo --json number,title ghx issue view 42 --json title,state
第一次查询可能需要调用 GitHub CLI；重复的相同查询则有机会命中缓存。需要立即绕过缓存时，文档提供了 --no-cache，也可用 GHX_NO_CACHE=1；单次覆盖 TTL 可使用 --ttl 120，环境变量方式是 GHX_TTL=60。这些参数适合处理刚更新的状态，避免误把短时间内的缓存结果当作实时数据。
并发 Agent 的关键：Singleflight
如果多个 Agent 在同一仓库、分支、认证上下文和参数下同时运行同一条命令，Ghx 会进行 singleflight coalescing：只执行一次底层 gh 调用，并将响应提供给并发请求者。它与缓存命中解决的是两个不同时间尺度的问题：缓存复用已经完成的查询；singleflight 则合并“此刻同时发生”的相同查询。
缓存键不只看命令名。文档列出的组成包括 GitHub host、仓库、当前分支、认证 token 的 SHA-256 指纹，以及完整命令参数。因此不同分支、不同仓库或不同 flags 会形成不同条目；token 本身不会被存储。这样能减少跨上下文复用错误结果的风险，也意味着两个 Agent 若处于不同工作上下文，未必能共享同一个缓存项。
看得见命中，也能主动失效
Ghx 附带本机 Web dashboard，默认地址为 http://localhost:9847/，展示总体命中率、按命令统计、延迟和近期请求记录；JSON 统计端点可供脚本读取：
curl http://localhost:9847/api/stats | jq . ghx xcache stats ghx xcache flush
发生 PR 或 Issue mutation 时，Ghx 会尝试清理相关缓存，避免旧列表长期残留。故障时它也有降级路径：文档说明 daemon 无法启动时会直接运行 gh，不让代理故障阻塞 CLI 工作流。实际采用前仍建议先观察 dashboard 和命令返回，尤其在自动化流程依赖最新状态时保留 --no-cache 的应急手段。
适合哪些工作流
如果多个 Agent 频繁读取同一仓库的 PR、Issue 或 CI 状态，Ghx 值得在本地试用；若工作负载以写操作、GraphQL 或动态参数为主，缓存收益则可能有限。它还提供 Claude Code 与 Copilot CLI 的 Agent 插件，帮助 Agent 优先调用 ghx。项目文档明确指出：系统已安装真实 gh 时，安装器会跳过 gh shim，此时可以直接使用 ghx 或安装 Agent 插件，不能默认所有既有 gh 调用都自动经过缓存。
一个稳妥的试点方式是先为只读查询接入 ghx，用 dashboard 对照命中率和等待时间，再逐步覆盖更多 Agent。把 mutation 的透传与失效行为纳入测试，并对需要强一致性的查询显式禁用缓存。这样可以在不改变 GitHub 工作流语义的前提下，减少重复读取带来的开销。
相关链接