為 Agent 設計命令列的 10 大黃金原則 (10 Principles for Agent-Native CLIs)

原始來源與檔名：20260512_2026-05-05T093915+0800-10 Principles for Agent-Native CLIs.md

來源：[[@trevin]] / X (Twitter) — 2026-05-04 原始檔名：2026-05-05T093915+0800-10 Principles for Agent-Native CLIs.md

NAPKIN | 餐巾紙

餐巾紙公式

Agent-Native CLI = Tier 1 (Defensive) + Tier 2 (Compounding). Tier 1 = Non-interactive + JSON + Actionable Errors + Safe Retries + Bounded. Tier 2 = Vocabulary Consistency + Introspection + Async --wait + Profiles + 2-way I/O.

越來越多的 CLI 工具（如 Cloudflare Wrangler, HeyGen CLI）開始將「Agent (AI代理)」視為第一級使用者，而不僅僅是人類。這篇文章總結了設計 Agent-Native CLI 的 10 大原則。它分為兩層：第一層是「防禦性」，確保 Agent 不會在執行時卡死（如避免互動式按 Y/N、確保輸出 JSON）；第二層是「複利效應」，透過統一命名詞彙、版本化內省 (Introspection) 和處理非同步任務 (--wait)，讓 Agent 越用越順手，並大幅降低 Token 消耗與重試錯誤。

一句話

如果你的命令列工具 (CLI) 是設計給 AI 使用的，請拋棄人類中心主義的設計。Agent 看不懂漂亮的 ANSI 彩色表格，也會因為一個預期外的互動式選項 [y/N] 而永遠卡死。這篇指南詳細列出了 10 個核心原則：從強制支援無頭模式 (--force)、結構化輸出 (--json)、到提供自我描述 API (agent-context) 以及針對非同步任務的同步等待機制 (--wait)。設計給 Agent 用的 CLI，最終也會成為對人類最友善的 CLI。

餐巾紙草圖

[ Human CLI vs Agent-Native CLI ]

Human CLI:
$ deploy
> Are you sure? [y/N]: y
> [Loading Bar...] Success!

Agent CLI (Tier 1 & 2):
$ deploy --force --wait --json --profile=prod
{"status": "success", "job_id": "8f2a", "url": "..."}

If Error:
Human CLI: "Invalid option."
Agent CLI: "Error: --visibility must be one of: public, private (got: secret)"

ROUND 1: SKELETON | 骨架掃描

“這篇文章在說什麼”

ROUND 2: DISSECTION | 血肉解剖

“憑什麼這麼說”

核心論證鏈

  1. 成本與上下文的浪費: Agent 在 CLI 前的每一次「卡死」、每一次解析錯誤的表格、每一次猜測 --help 中的變數，燃燒的都是使用者的 API 費用與上下文額度。Agent-Native 設計的本質是「為 Token 經濟學做最佳化」。
  2. 手動維護無法保證一致性: 第 6 點和第 7 點指出，人類在 PR 審查時一定會漏掉命名不一致（例如 info vs get）。唯一的解法是基於統一的 Schema 生成 CLI，這樣才能保證所有子指令的 --json 行為與命名詞彙絕對統一。

關鍵證據

邊界條件

ROUND 3: SOUL | 靈魂提取

“還能怎么用”