AI 查 GitHub 太烧 Token？gh-cli-readonly-agent 给 Agent 装上只读省流阀

你有没有算过这样一笔账：让 AI 帮你「看看某个开源库最近在忙啥」，它老老实实跑了一条 gh api repos/xxx/yyy，返回一大坨 JSON，光那一次调用的原始输出就够你写三篇小作文。

更离谱的是，它顺手还想帮你「优化」一下——gh pr create、gh issue close、gh api -X DELETE 全给你安排上。你只是想看一眼，它想给你改个仓库。

SkillHub 上的 gh-cli-readonly-agent（GitHub CLI 省 Token 只读工具集），就是来管这俩毛病的。一句话概括：给 AI Agent 配一套「只能看、不能动、还特别省」的 GitHub CLI 使用规范。目前下载量已经过了 510 万。

它不是工具，是一本「使用说明书 + 护栏」

先说清楚定位，免得你误会。

这个 Skill 本身不装什么新二进制，它是一份写给 Agent 的行为契约。核心就四条硬规矩（原文叫 HARD RULES）：

• 只读：任何写入、创建、合并、评论、删除操作，一律禁止
• 省 Token：gh 命令必带 --json 裁剪字段，必带 --limit（默认不超过 10），必用 | jq -c 输出紧凑格式
• 超时：所有 gh api 调用必须走预置函数 gh_timed
• 缓存：高频查询必须走 gh_cached

翻译成人话就是：能少要字段就少要，能少要几条就少要几条，能缓存就别重复问，能超时就别干等。

你可能觉得这不就是常识吗？问题在于，Agent 恰恰最容易在这几件事上「没常识」——它默认拉全量、默认不裁剪、默认不缓存。你把规矩写死，它才老实。

七个预置函数，把「省」做成肌肉记忆

真正让我眼前一亮的是这一层：这个 Skill 假设运行环境里已经预置好 7 个函数，让 Agent 直接调用，而不是每次现场手搓。

函数	作用
gh_timed <args>	带 30 秒超时保护的 gh 调用
gh_cached <args>	带 30 分钟 TTL 的脚本层缓存
retry <args>	指数退避重试（最多 3 次）
gh_read O/R path [ref]	读取文件内容并自动 base64 解码
gh_tree O/R [depth]	获取目录树，默认限深 3 层，输出去重路径
truncate_by_quota O/R path	按剩余 Token 配额自适应截断大文件
gh_default_branch O/R	探测默认分支（main → master → API 兜底）

别小看这几个封装。gh_read 顺手帮你把 GitHub Contents API 那层 base64 解码处理掉了——就是那个每次都要 jq -r '.content | @base64d'、不写就返回一堆乱码的经典坑。truncate_by_quota 更有意思，它根据 TOKEN_QUOTA 环境变量动态决定读多少行，配额紧就少读点，配额松就多读点，让截断这件事变得自适应。

gh_default_branch 则是专治 404 的。很多仓库默认分支不叫 main 而叫 master，硬编码 main 就会扑空；这个函数把「先猜 main、再试 master、最后查 API」的兜底逻辑包好了。

省 Token 的实战姿势

规矩立完了，具体怎么省？看几个原文里的典型写法。

读单个文件，推荐直接用预置函数：

gh_read O/R src/utils/parser.rs
gh_read O/R config.yaml v2.1.0   # 指定 tag 或 branch

读大文件就截断，别整份往上下文里灌：

gh_read O/R large_file.py | head -200
gh_read O/R large_file.py | sed -n '50,150p'
truncate_by_quota O/R large_file.py   # 按配额动态截断

搜索仓库时，--json 只留你真正要的字段：

gh search repos --stars:>500 --language=python --sort=stars \
  --limit 10 --json fullName,description,stargazersCount | jq -c '.'

这里有个很细节的提醒值得单独拎出来：Search API 限流是每分钟 10 次。所以高频搜索必须套 gh_cached，否则你会发现自己被 GitHub 礼貌地请去喝茶。

还有一个容易被忽略的安全细节——读取配置类文件后，可以顺手做一次脱敏：

gh_read O/R config.py | sed -E 's/(api[_-]?key|token|secret|password)\s*[=:]\s*["\x27][^"\x27]+["\x27]/\1="***"/gi'

Agent 读到了密钥，不代表它该把密钥写进聊天记录里。

写操作黑名单：正则拦得死死的

只读不是靠自觉，是靠拦截。Skill 里明确列了一份黑名单：

• 正则拦截：gh (pr|issue|repo|release|workflow|gist) (create|merge|comment|edit|close|delete|fork|run|disable|review)
• API 拦截：gh api -X (POST|PUT|DELETE|PATCH)
• 文件写入：对 contents/PATH 的 PUT / POST / DELETE

有意思的是它还很贴心地澄清了一句：gh run list、gh run view、gh pr checks、gh pr diff 都属于只读，黑名单正则只拦「第二组动词」，不会误伤这些查询命令。

这个细节说明作者是真踩过坑的——拦得太粗，会把正常的「看 CI 日志」也给拦了。

出错会自愈，不会一路错到底

Agent 跑命令最怕的不是报错，是报错之后还硬着头皮往下跑。这个 Skill 内置了一张错误自愈与熔断表：

错误码 / 条件	自动动作
401	触发 gh auth login 重新认证
403（限流）	retry 指数退避，连续 3 次则暂停 5 分钟
404	检查仓库名拼写、可见性，以及认证 scope
5xx	指数退避，连续 5 次暂停 10 分钟并告警
返回文本 > 5000 字符	自动截断并标注 [已截断]
单轮工具调用 > 20 条	暂停 30 秒，防 Token 爆炸

其中有一句特别值得玩味：404 场景下明确写着「勿主动 gh auth refresh --scopes repo」，理由是避免给只读的 Agent 授予写权限。

这就是安全设计的克制感——宁可让你重新登录，也不为了图方便把写权限塞给一个本该只读的角色。

跨平台这件事，它是认真的

很多 Skill 在 macOS / Linux 上写得好好的，一到 Windows 就翻车。这个 Skill 少见地给了三套适配：

• bash：标准写法，jq 用单引号包裹表达式
• Windows CMD：jq 表达式改双引号，且 |、> 等特殊符号要用 ^ 转义
• PowerShell（pwsh 7）：推荐单引号包裹 jq 表达式，里面可直接写双引号无需转义

连「date 在 Windows 上是 Get-Date 的别名，取近一年要用 (Get-Date).AddYears(-1).ToString('yyyy-MM-dd')」这种细节都写进去了。写过多平台脚本的人看到这里应该会心一笑——这些坑，一个都躲不掉。

连自检脚本都给了

最让我觉得「这作者是真干活的人」的地方，是第 10 节：一套纯静态的验证测试。

九个测试项 T1 到 T9，覆盖写操作拦截、认证状态、超时机制、读文件解码、目录树限深、动态截断、curl 降级、PowerShell 可用性、函数加载。全部只读断言，零写风险，exit 0 即通过。原文还给了一键自检脚本：

t() { eval "$1" >/dev/null 2>&1 && echo "PASS $2" || echo "FAIL $2"; }
t 'echo "gh pr create" | grep -Eq "gh (pr|issue|repo|release|workflow|gist) (create|merge|comment|edit|close|delete|fork|run|disable|review)"' T1_blacklist
t 'gh auth status' T2_auth
t 'timeout 1 sleep 2; test $? -eq 124' T3_timeout
t 'gh_read cli/cli README.md | grep -q "GitHub CLI"' T4_read
# …… 其余见原文

一个「用说明书」级别的 Skill，还自带验收标准——这在开源生态里并不常见。

gh 彻底不可用怎么办？

还有降级方案。当 gh 命令本身不可用时，回退到 curl 直连 GitHub REST API：

curl -s --max-time 30 -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  "https://api.github.com/repos/O/R/contents/README.md" \
  | jq -c '.content | @base64d'

永远留一条退路，是工程靠谱的标志。

它适合谁

如果你符合下面任意一条，这个 Skill 基本就是为你准备的：

• 经常让 AI 帮你看开源仓库、读源码、翻 PR 和 Issue
• 被 Agent 的 Token 账单吓到过
• 担心 Agent 手滑对仓库做出写操作
• 在 Windows 和 macOS 之间来回横跳，受够了脚本不通用

项目信息

• SkillHub：skillhub.cn/skills/indiv-yaoyao/gh-cli-readonly-agent
• 作者：@indiv-yaoyao
• 分类：开发编程
• 下载量：510 万+
• 依赖：gh（GitHub CLI）+ jq

最后说句实在话：这个 Skill 最打动我的地方，不是它省了多少 Token，而是它把「Agent 该有什么样的边界感」这件事，写成了一套可执行的规范。只读、限流、脱敏、熔断、降级、自检——每一条都在告诉你：一个靠谱的智能体，不是能力越大越好，而是知道什么时候该停手。

在这个人人都想给 AI 更大权限的年代，愿意花力气教它「少动手」的工具，反而显得格外清醒。对经常和 Agent 打交道的开发者来说，这类约束比单纯堆能力更值得放进工具箱。