kunchenguid/gh-axi

gh‑axi – 面向自主AI代理的GitHub CLI封装工具

是什么

• gh‑axi 是基于 Node 的命令行工具，构建在官方 GitHub CLI（gh）之上。
• 专为需要以程序化方式与 GitHub 交互的 AI 代理 设计，提供高效的令牌输出（TOON 编码）、结构化错误消息和下一步建议。
• 该工具是 AXI（Agent eXperience Interface） 生态系统的一部分，标准化了代理发现和使用能力的方式。

对代理的重要性

• 代理在调用大型语言模型时通常面临严格的令牌预算。gh‑axi 通过压缩 CLI 输出并仅呈现代理决策所需的信息，减少了 LLM 需要处理的数据量。
• 提供 确定性、机器可读的响应（JSON、简洁的状态码），而非原始 gh CLI 的自由格式、面向人类的输出。
• 内置错误处理和验证机制，使代理无需解析模糊的终端消息即可对失败做出反应。

核心功能

领域	使用 gh‑axi 可以实现的操作
问题与PR	列出、查看、创建、编辑、评论、添加标签/分配者/审阅者、附加文件（图片、视频）——所有操作均支持重复标志以处理多个值。
堆栈	完全非交互式封装 github/gh‑stack 扩展，支持堆叠式 PR 工作流（初始化、查看、提交、合并、变基等）。
工作流与运行	列出、查看、触发、取消、下载 GitHub Actions 运行日志；日志被截断，但完整副本会保存到临时文件中供代理使用 grep。
项目（v2）	列出、查看、创建、编辑、关闭、复制、管理项目项和字段——当 OAuth 范围缺失时提供清晰指引。
密钥与变量	设置密钥（仅支持 stdin 以确保安全）、列出/删除，以及管理仓库级变量。
Gists	列出、查看、创建（公开或私有）、编辑、重命名、删除、克隆 Gists，具有严格的标志验证。
原始API	通过 gh‑axi api 直接访问任何 GitHub REST 端点，支持自定义 HTTP 方法、头信息、JSON 正文、分页、jq 过滤、模板化，以及禁用输出截断的“完整”模式。
仓库与搜索	标准仓库命令（列出、查看、克隆、分叉）和强大的问题、PR、代码、提交搜索功能。
会话钩子	可选钩子，可在每个会话开始时自动向 Claude Code、Codex 或 OpenCode 等代理展示当前仓库状态。

代理友好型设计细节

• 高效的 TOON 输出 – 紧凑的表示方式，保持 LLM 的上下文窗口较小。
• 结构化 JSON 用于需要机器可读数据的命令（如 stack view、run view）。
• 可重复标志（如 --add-label）确保每个值都传递给底层 gh 命令，避免静默丢失。
• 明确的验证错误 – 缺失或空的标志值会引发清晰错误，而非被忽略。
• 确定性退出码 – 包装器转发原始 gh 退出码，保留代理依赖的语义。
• 自动更新 – 代理可运行 gh‑axi update 以在无需外部包管理器的情况下保持工具最新。

安装与使用

1. 代理技能安装（推荐）：

   npx skills add kunchenguid/gh-axi --skill gh-axi -g
   

   此操作注册一个轻量级“技能”，指向最新的 npx -y gh-axi 仪表板。
2. 零配置 – 任何具备能力的代理只需执行 npx -y gh-axi 即可使用。
3. 全局安装（手动使用）：

   npm install -g gh-axi
   gh-axi setup hooks   # 可选会话钩子
   

   之后即可像其他 CLI 一样使用（gh‑axi <command> …）。

代理的典型工作流

1. 代理决定需要处理一个问题。
2. 执行 gh‑axi issue list --label bug --assignee @me。
3. 工具返回一个简洁、低令牌开销的问题列表。
4. 代理选择一个问题并执行 gh‑axi issue comment 42 --body-file ./reply.md。
5. 若评论包含图片，代理添加 --attach ./screenshot.png，工具通过底层 gh 二进制文件上传文件。

基准测试

• 在 AXI 基准测试中（17 个真实世界 GitHub 任务，使用 Claude‑Sonnet‑4‑6 作为代理），gh‑axi 实现了 100% 成功，平均输入令牌数（约 46k）、成本（约 $0.05/任务）和平均持续时间（约 15.7 秒）均低于原始 gh 和其他基于 GitHub‑MCP 的接口。

谁应该使用它

• 构建 自主 DevOps 代理、AI 辅助代码审查者，或任何需要可靠、低开销 GitHub 交互的 LLM 驱动工作流的开发者。
• 已使用 AXI 生态系统并希望快速集成 GitHub 操作技能的团队。

许可证: MIT。