SuperAPI AI 工具集

gh-cli

编程与开发

查看项目

更新于 11-03 11:03

技能介绍

此条目是面向智能体的 GitHub CLI(gh)使用模式集,依据官方 gh v2.103.3 与 cli/cli 主干整理,目标是让智能体在非交互环境中可预测、可复现且安全地调用 gh,而不是用裸 curl 或手写 API 请求。

一、总体原则 优先使用 gh 而非 curl 或 gh api,因为 gh 自动处理认证、分页和 JSON 输出。gh 在非 TTY 环境下会自动跳过分页器、去除 ANSI 颜色、快速报错而非弹出交互提示。

二、安全要点 资料列出多项安全公告与应对规则:v2.97.0 修复了 4 个转义序列注入漏洞,涉及 gh gist view、gh api、gh pr diff、gh release download --output -、gh codespace logs、gh agent-task view/create 等命令,可能注入 ANSI 控制序列。规则是:不把输出管道给终端渲染器,优先用 --json;原始内容写入文件;绝不使用 gh release download --output -。v2.96.0/v2.97.0 还修复了 gh auth status 打印令牌片段、attestation verify 正则未转义、REST URL 路径穿越、codespace jupyter 未校验 URL 等问题。v2.99.0 修复了 codespace 端口转发默认绑定 0.0.0.0 的问题,提醒不要转发含敏感内容的开发服务器。

三、非交互策略 设置 GH_PROMPT_DISABLED=1 使 gh 直接失败而非提示;部分命令需显式标志(如 gh pr merge 需指定合并方式、gh release create 需 --notes 或 --generate-notes、gh pr create 需 --fill 或显式标题正文)。退出码含义:0 成功、1 失败、2 取消、4 需认证。资料还列出 GH_PAGER、GH_NO_UPDATE_NOTIFIER、NO_COLOR、GH_DEBUG、GH_FORCE_TTY、GH_TELEMETRY 等环境变量的作用。

四、输出解析与分页 用 --json 获取结构化输出,无字段列表时先打印可用字段;用 --jq 过滤,--template 输出模板化文本(注意 -T 与创建命令的模板标志冲突)。列表命令默认限制 30 条,需用 -L 调整;gh api --paginate 需配 --slurp 合并数组;gh api --cache 可缓存响应。

五、仓库定位与搜索 gh 从当前目录 git 远程推断仓库,可用 --repo 覆盖或设置 GH_REPO。gh search 使用 GitHub 搜索索引,各限定符须作为独立裸词传入不可整体加引号;机器人作者需用 --app;可用 -- 排除限定符;v2.98.0+ 支持 --search-type 语义搜索(仅议题、单页、限 github.com 与 GHEC)。

六、PR 评审 gh pr review 只提交顶层评审,没有行内评论标志;行内评论需通过 REST API 传 comments[] 数组。智能体不应自动批准,评审结论留给人类。

七、gh api 作为通用兜底 提供 GraphQL 与 REST 示例,说明 -f 发送字符串、-F 解析数字/布尔/@文件、{owner}/{repo} 自动填充等。

八、其它能力 包括认证与速率限制、gh skill(搜索/安装/更新/发布,需指定 --agent)、gh aw 智能体 CI 扩展(需先安装,注意版本绕过计费缺陷)、发布验证(Sigstore 链)、附件上传(仅 GitHub.com 与 GHEC)、以及 project、ruleset、cache、read-file、discussion、gist、codespace 等子命令速查。

九、适用场景与限制 适用于智能体自动化处理议题、PR、发布、Actions、代码搜索等 GitHub 任务;限制在于部分功能为实验性或仅限特定平台(如 GHES 不支持附件、语义搜索不适用于单租户 GHES),且资料未提供完整安装步骤与价格信息。