設計 Agent-Native CLI：AI 時代的 10 項原則

數十年來，命令列介面 (CLI) 的設計一直是以終端機前的真人為主要使用者。我們針對視覺對齊、ANSI 色彩和互動式提示進行了優化——這些元素對人類來說很直觀，但對 AI agent 來說卻往往是阻礙。隨著 agent 越來越成為我們 API 的主要消費者，設計理念必須轉變。

Trevin Chow 最近提出了一個「Agent-Native CLI」的框架，其靈感來自於他自己的工作以及 Cloudflare 和 HeyGen 等公司的實作。其核心論點很簡單：當你優先為 agent 設計時，人類實際上會從隨之而來的嚴謹性和一致性中受益。

第一層級：不要破壞 Agent

第一層級的原則專注於防禦性設計。這些是確保 agent 不會掛起、陷入無限迴圈或靜默失敗的基準要求。

1. 預設為非互動式

Agent 無法回答「您確定嗎？[y/N]」這樣的提示。如果一個指令在等待輸入時掛起，agent 就會直接停止。

• 標準： 每個可能需要提示的指令都必須具備 --no-input 或 --yes 旗標。
• 優化： Cloudflare 將破壞性操作的繞過標準化為 --force，並明確禁止使用 --skip-confirmations 以維持可預測的詞彙表。

2. 結構化、可解析的輸出

雖然人類喜歡表格，但 agent 需要可以可靠提取的數據。

• 標準： 在每個回傳數據的指令上提供 --json 旗標。
• 優化： 維持嚴格的一致性。避免混合使用 --format=json 和 --output json。使用 stdout 用於數據，使用 stderr 用於診斷資訊。

3. 具備教學與列舉功能的錯誤訊息

「invalid visibility」這樣的錯誤對 agent 來說是死路一條。而說著「--visibility 必須是以下其中之一：public, private, unlisted」的錯誤訊息，則能讓 agent 在單次重試中自我修正。

• 標準： 當拒絕不符合 enum 或 schema 的輸入時，直接在錯誤訊息中呈現有效的數值集合。

4. 安全的重試與明確的變更邊界

Agent 經常進行重試。如果沒有冪等性 (idempotency)，重試的「create」指令會導致重複的資源。

• 標準： 使用冪等性權杖 (idempotency tokens) 或自然鍵 (natural keys)。
• 優化： 為具備後果的操作實作 Implement --dry-run，並確保破壞性動作需要一個明確的、非預設的旗標。

5. 受限的響應內容

無限制的輸出會浪費 token 並可能撐爆 agent 的上下文窗口 (context window)。

• 標準： 在所有列表類型的指令上實作分頁、限制與過濾功能。
• 優化： 提供截斷訊息，明確教導 agent 如何縮小下一次查詢的範圍（例如：「add --limit=N to see more」）。

第二層級：賦能 Agent

一旦 CLI 穩定下來，下一個目標是隨著使用頻率的增加而使其變得更有用。這一層通常透過程式碼生成 (codegen) 或 schema 而非手動編碼來實作效果最佳。

6. 跨 CLI 詞彙一致性

Agent 會建立一個關於 CLI 如何運作的通用模型。如果大多數工具都使用 get 但你的工具使用 info，agent 就會消耗 token 和重試次數來搞清楚這件事。

• 標準： 隨社群慣例（例如 get, list, create, update, delete）。
• 優化： 在 schema 層級強制執行此規則，以防止因人工審核而產生的「瑞士乳酪式」一致性。

7. 三層內省機制

漸進式的幫助發現對 agent 來說是不夠的。它們需要工具能力的機器可讀地圖。

• 第一層： 給人類使用的標準 --help。
• 第二層： agent-context——一個版本化的、機器可讀的 JSON，描述了 CLI 的完整形狀。
• 第三層： 技能清單 (例如 SKILL.md)——長篇散文，教導 agent 如何將操作組合進複雜的工作流中。

8. 非同步感知執行

強迫 agent 為非同步任務撰寫自己的輪詢 (polling) 迴圈是非常耗費 token 且容易出錯的。

• 標準： 提供一個會阻塞直到完成的 --wait 旗標。
• 優化： 維持一個本地任務帳本 (例如 ~/.cli/jobs.jsonl)，這樣如果 agent 在輪詢中斷線，下一次調用可以恢復正在進行的任務，而不是重新開始一個個新任務。

9. 透過 Profile 實現持久化身份

無狀態的 CLI 會強迫 agent 每次都重新指定相同的配置旗標。

• 標準： 實作一個 profile 系統（profile save, profile use）來封裝配置。
• 優化： 在 agent-context 中呈現可用的 profiles，以便 agent 可以直接發現現有的身份，而無需解析設定檔。

10. 雙向 I/O

Agent 經常需要將產出物（例如生成的影片或日誌）移動到特定目的地。

• 標準： 實作一個支援 stdout, file:<path>, 和 webhook:<url> 的 --deliver 旗標。
• 優化： 包含一個 feedback 指令，允許 agent 直接向維護者回報摩擦點（例如：「這個旗標有文件說明但被拒絕了」）。

辯論：Agent-Native vs. Unix-Native

並非所有開發者都認同「agent-native」這個標籤。有些人認為這些原則僅僅是「良好的 CLI 設計」，應該從一開始就遵循。

「如果你曾遇過 jq，你就不需要任何人告訴你 --json 是非常寶貴的東西... 這只是將命令列介面視為嚴謹的介面來對待。除了在邊緣情況之外，這與 AI 幾乎沒有關係。」

其他人則警告不要為了 agent 而進行過度工程，以免犧牲人類的使用性，並建議如果給予足夠好的「LLM 版 manpage」，agent 就足以應對混亂的 CLI。

無論哲學上的分歧，實際結果是一樣的：一個可預測、結構化且一致的 CLI 對於每一位使用者來說都是卓越的，無論他們是由碳基還是矽基構成的。