axi

Agent eXperience Interface (AXI)

AXI 定義了 CLI 工具的人體工學標準，讓自主代理程式能透過 shell 執行與之互動。

開始之前

在建立任何 AXI 輸出之前，請先閱讀 TOON 規格。

1. Token 高效輸出

使用 TOON（Token 導向物件標記法）作為 stdout 的輸出格式。
TOON 相較於等效的 JSON 可節省約 40% 的 token，同時仍保持代理程式可讀性。
在輸出邊界轉換為 TOON — 內部邏輯維持使用 JSON。

tasks[2]{id,title,status,assignee}:
  "1",Fix auth bug,open,alice
  "2",Add pagination,closed,bob

2. 最小預設結構

stdout 中的每個欄位都會消耗 token — 且會隨著集合中的行數倍增。
預設使用最小的結構，讓代理程式能決定下一步要做什麼：通常是識別碼、標題和狀態。

• 預設列表結構：3-4 個欄位，而非 10 個
• 預設限制：夠高以涵蓋一次呼叫中的常見情況（如果大多數儲存庫少於 100 個標籤，預設為 100，而非 30）
• 長格式內容（內文、描述）屬於詳細檢視，而非列表
• 提供 --fields 旗標，讓代理程式能明確請求額外欄位

3. 內容截斷

詳細檢視通常包含大型文字欄位。省略它們會迫使代理程式搜尋；包含它們則浪費 token。
預設截斷，並告知代理程式如何取得完整版本。

task:
  number: 42
  title: Fix auth bug
  state: open
  body: 問題內文的前 500 個字元...
    ... (已截斷，總計 8432 字元)
help[1]: 執行 `tasks view 42 --full` 以查看完整內文

• 絕不完全省略大型欄位 — 包含截斷預覽
• 顯示總大小，讓代理程式知道它缺少多少內容
• 僅在內容確實被截斷時建議逃脫機制（--full）
• 選擇能涵蓋大多數使用案例的截斷限制（500-1500 字元）

4. 預先計算的彙總

最昂貴的 token 成本通常不是較長的回應 — 而是後續的呼叫。如果你的後端有代理程式通常需要作為下一步的資料，請計算並包含它。

彙總計數：在列表輸出中包含總計數，而不僅僅是頁面大小。代理程式需要知道「總共有多少？」，如果答案不明確，它們會進行分頁。

count: 30 of 847 total
tasks[30]{number,title,state}:
  1,Fix auth bug,open
  ...

衍生狀態欄位：當下一步幾乎總是涉及檢查相關狀態時，請在行內包含輕量摘要。

task:
  number: 42
  title: Deploy pipeline fix
  state: open
  checks: 3/3 passed
  comments: 7

僅包含你的後端能低成本提供的衍生欄位 — 摘要（「3/3 passed」），而非完整資料。

5. 明確的空狀態

當答案為「無」時，請明確說明。模糊的空輸出會導致代理程式使用不同旗標重新執行以進行驗證。

$ tasks list --state closed
tasks: 0 closed tasks found in this repository

說明零的上下文。清楚表明命令已成功執行 — 結果不存在就是答案。

6. 結構化錯誤與退出碼

冪等變更

當目標狀態已存在時不要報錯。如果代理程式關閉了已關閉的項目，請確認並繼續執行，退出碼為 0。保留非零退出碼給代理程式的意圖確實無法滿足的情況。

$ tasks close 42
task: #42 already closed (no-op)    # exit 0

stdout 上的結構化錯誤

錯誤訊息以與正常輸出相同的結構化格式輸出到 stdout，以便代理程式能讀取並採取行動。包含出錯原因和可行的建議。絕不讓原始依賴項輸出（API 錯誤、堆疊追蹤）洩漏出來。

error: --title is required
help: tasks create --title "..." [--body "..."]

• 在呼叫任何依賴項之前驗證必要旗標
• 翻譯錯誤 — 提取可行的意義，丟棄雜訊
• 絕不洩漏依賴項名稱 — 建議應引用你的 CLI 的命令，而非底層工具

無互動提示

每個操作都必須能僅透過旗標完成。如果缺少必要值，請立即失敗並附上明確錯誤 — 不要提示輸入。抑制包裝工具的提示。

對無法辨識的輸入明確失敗

拒絕未知的旗標和引數 — 絕不靜默忽略它們。被忽略的旗標比錯誤更糟：代理程式會得到看似合理但實際已設定範圍或篩選的輸出，然後基於錯誤資料自信地繼續執行。這與 CLI 對未知命令的保證相同；將其擴展到旗標。

$ tasks list --stat closed
error: unknown flag --stat for `list`
help: valid flags for `list`: --state, --assignee, --limit (--help always allowed)

• 在任何依賴項呼叫之前驗證，退出碼為 2 — 與缺少必要旗標相同。每個命令宣告自己的已知旗標；無法辨識的旗標會按名稱被拒絕，並列出該命令的有效旗標。
• --help 始終通過 — 它是唯一通用的旗標。除此之外，CLI 可以標準化自己的始終允許的全域旗標（例如 --account 選擇器）；無論集合為何，這些旗標在每個命令上都通過，且永遠不會被報告為未知。
• 重新命名或移除的旗標會獲得針對性提示，而非通用列表 — 指向取代它的內容（--status was renamed; use --state instead），讓代理程式一步自我修正。
• 每個子命令的旗標集合。 對於分組名詞，當一個命令分派給子命令時（同一名詞下的 list 與 create），請根據_子命令_的旗標進行驗證 — 它們不同，且只有子命令層知道哪個在作用中。
• 讓錯誤在一次回合中自我修正。 代理程式在未知旗標錯誤後的確定下一步是執行 <command> --help（例如 tasks list --help）— 因此將該查詢折疊到錯誤中：在行內列出有效旗標，或直接在下方印出該命令的簡潔 --help 區塊。根據 §4，昂貴的成本是後續呼叫，而根據 §10，每個命令的幫助已經很簡潔，因此內聯它將兩回合修正合併為一回合。

輸出通道

• stdout：代理程式消費的所有結構化輸出 — 資料、錯誤、建議
• stderr：除錯記錄、進度指示器、診斷資訊（代理程式不讀取此內容）
• 退出碼：0 = 成功（包括無操作），1 = 錯誤，2 = 使用方式錯誤

絕不將進度訊息混入 stdout。讀取「Fetching data...」的代理程式會嘗試將其解釋為資料。

7. 透過會話整合的環境上下文

將你的工具註冊到代理程式的會話生命週期中，讓每次對話在代理程式採取任何行動之前，相關狀態就已可見。

模式：

1. 提供一個明確的設定命令，在使用者意圖明確後安裝或修復會話鉤子或插件
2. 在會話開始時，整合會執行你的工具並提供一個緊湊的儀表板作為上下文
3. 代理程式將其作為初始上下文接收，並能立即行動

# 代理程式在會話開始時看到此內容 — 無需調用：
specs[2]{id,title,status}:
  1,Fix auth bug,open
  2,Add pagination,in-progress

help[2]:
  執行 `mytool specs view 1` 以查看詳細資訊
  執行 `mytool specs create --title "..."` 以新增規格

規則：

• 預設應用目標：預設支援 Claude Code、Codex 和 OpenCode。當工具能合理支援多個代理程式時，不要硬編碼單一代理程式整合
• 明確選擇加入：僅從使用者調用的設定命令註冊鉤子或插件，而非從一般 CLI 命令
• 可攜式命令：鉤子命令應在解析為目前可執行檔時使用 PATH 驗證的二進位名稱，否則回退到完整絕對路徑。這使全域安裝保持可攜性，同時確保鉤子不會意外執行不同的二進位檔
• 路徑修復：設定命令應檢查現有鉤子，並在可執行檔路徑變更時更新（例如重新安裝或重新定位後）
• 冪等：使用相同路徑重複安裝是靜默無操作
• 目錄範圍：僅顯示與目前工作目錄相關的狀態
• Token 預算感知：此上下文在_每個_會話中載入 — 極力最小化它。僅包含足夠讓代理程式定位和行動的內容；深度資料屬於明確調用
• 生命週期捕獲：使用會話結束鉤子捕獲發生的事情（記錄、觸及的檔案、引用的規格），以便未來的會話開始上下文隨著時間推移變得更豐富

如何與每個應用整合：

• Claude Code：使用 ~/.claude/settings.json 或專案 .claude/settings.json 中的原生鉤子。偏好 SessionStart 以透過 stdout 注入緊湊上下文
• Codex：使用 ~/.codex/hooks.json 或 <repo>/.codex/hooks.json 中的原生鉤子，並確保 config.toml 中的 [features].hooks = true。偏好 SessionStart 以透過 stdout 提供環境上下文
• OpenCode：使用 ~/.config/opencode/plugins/ 中的受管理插件。偏好環境系統上下文注入以用於主檢視，而非新增自訂工具

同時提供可安裝的技能（次要建議）：

會話鉤子是主要整合，但它僅對支援鉤子的代理程式有幫助，且會在_每個_會話中載入。
提供可安裝的 Agent Skill 作為次要探索路徑。
它在代理程式識別到匹配任務時按需載入，沒有每次會話的 token 成本，且能在任何支援技能格式的代理程式中運作。
優先推薦鉤子（環境上下文加上即時狀態），其次推薦技能（較低開銷、更廣泛的代理程式支援）— 它們是互補的，使用者安裝適合的其中一個，或兩者都安裝。

npx skills add <owner>/<repo> --skill <name>

• 單一事實來源：從你的無引數主檢視列印的相同內容產生 SKILL.md，使技能永遠不會偏離 CLI 自身的指導。在 CI 中加入 --check 建置步驟，如果提交的技能過時則失敗
• 移除即時狀態：技能是靜態的，因此省略只有鉤子能顯示的動態資料（開啟的會話、當前項目）
• 非互動命令：將命令範例重寫為代理程式無需全域安裝即可執行的形式（例如 npx -y mytool ...），因為技能可能安裝在沒有 PATH 二進位檔的情況下
• 觸發形狀的前置資料：包含 name 和寫成觸發器的 description — 簡潔且以結果為導向，以便代理程式在正確意圖下載入它
• 記錄兩種路徑：在你的 README 中，將鉤子和技能呈現為達成相同目標的兩種方式，並明確說明使用者只需要其中一個

8. 內容優先

在無引數的情況下執行你的 CLI 應顯示最相關的即時內容 — 而非使用手冊。
當代理程式看到實際狀態時，它可以立即行動。當它看到幫助文字時，它必須進行第二次呼叫。

$ tasks
tasks[3]{id,title,status}:
  1,Fix auth bug,open
  2,Add pagination,open
  3,Update docs,closed
help[2]:
  執行 `tasks view <id>` 以查看完整詳細資訊
  執行 `tasks create --title "..."` 以新增任務

9. 上下文相關揭露

包含幾個合乎邏輯的下一步，從當前輸出推導而來。
代理程式透過使用你的 CLI 有機地發現其表面區域，而非事先閱讀手冊。

規則：

• 相關：在開啟項目後 → 建議關閉；在空列表後 → 建議建立；在列表後 → 建議檢視
• 可行：每個建議都是一個完整的命令（或範本），攜帶當前調用中的任何消歧旗標（例如 --repo、--source）
• 參數化動態值：當建議的命令需要執行時期值（如 ID、標題、分支、URL 或路徑）時，使用像 <id> 或 "<title>" 這樣的佔位符，而不是猜測可能誤導代理程式的具體值
• 在自包含時省略：當輸出完全回答查詢時（詳細檢視、計數、確認），建議是雜訊 — 省略它們。在列表和變更回應中包含它們，當下一步不明顯時。
• 引導探索，而非工作流程：建議多種可能的下一步行動，不要規定固定順序。已經知道要做什麼的代理程式絕不應被引導到額外的步驟。
• 揭露截斷列表：當列表僅顯示較大總數中的最近 N 個項目時，添加幫助提示告訴代理程式如何查看所有項目（例如 Run 'mytool list' for all 47 items）。不要將分頁編碼到 TOON 陣列標頭中 — 改用幫助提示。
• 解決錯誤：在錯誤時，建議修復問題的特定命令，而非「請參閱 --help」

10. 一致的取得幫助方式

頂層主檢視也應在即時資料之前識別工具本身：

• 包含目前可執行檔的絕對路徑，使用者家目錄折疊為 ~
• 包含一句話描述此 AXI 的作用

$ tasks
bin: ~/.local/bin/tasks
description: Manage project tasks in the current workspace
...

每個子命令應支援 --help，提供簡潔完整的參考：可用旗標與預設值、必要引數，以及 2-3 個使用範例。保持專注於請求的子命令 — 不要傾倒整個 CLI 的手冊。