kunchenguid/gh-axi

gh‑axi – 為自主AI代理設計的GitHub CLI封裝工具

是什麼

• gh‑axi 是建構於官方 GitHub CLI（gh）之上的 Node 基底命令列工具。
• 專為需要以程式化方式與 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。