面向 Agent 的命令行工具（CLI）最佳設計實踐

作者：新一代智能化應用
日期：2026年4月16日 上午12:00
來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點 高亮

Agent 時代下 CLI 命令行工具因其天然的文本交互屬性與高穩定性，正取代 GUI 成為 AI 自動化的核心接口。

  • CLI 具備文本輸入輸出的特性，與 LLM 工作方式天然匹配，比脆弱的 GUI 自動化更穩定且易於組合。
  • 相比直接調用 API，設計良好的 CLI 封裝了複雜的認證與分頁邏輯，降低了 Agent 的調用門檻。
  • CLI 與 MCP 並非互斥，CLI 是底層執行接口，MCP 則是分發治理層，兩者結合可實現能力複用。
  • Agent 友好的 CLI 必須具備非交互性、結構化輸出（JSON）以及具備指導意義的錯誤提示。
  • 設計核心在於確保命令可安全重試且邊界清晰，讓 Agent 在出錯時能根據輸出自我修復並繼續執行。
值得記低
工具 github.com

OpenCLI / CLI-Anything

開源的 CLI 轉換與增強工具，用於將現有工具適配為 Agent 友好的接口。

開啟
連結 modelcontextprotocol.io

MCP (Model Context Protocol)

由 Anthropic 推出的模型上下文協議，用於工具註冊與多工具編排。

開啟
筆記 mariozechner.at

MCP vs CLI 基準測試報告

Mario Zechner 針對 terminalcp 進行的性能對比，證實接口質量比協議本身更重要。

開啟
整理重點

點解 Agent 時代 CLI 反而更重要？

好多人以為命令行係工程師專用嘅「老古董」，但喺 Agent 視角，CLI 先係最理想嘅執行面。佢唔單止部署成本低，仲自帶自描述性（--help），非常適合被 Agent 鏈式調用。

整理重點

Agent 友好型 CLI 嘅設計準則

要令 Agent 用得順手，CLI 唔可以再當係畀人睇嘅工具，而係要當成「機器對話協議」嚟設計。

核心原則：默認非交互（Non-interactive）、輸出結構化（JSON）、錯誤提示具備引導性。

高質量錯誤提示範例 bash 
Error: --content is required.
Usage: blog-cli publish --content <file> [--status <status>]
Available statuses: draft, published, scheduled
Example: blog-cli publish --content my-post.md
整理重點

架構策略：CLI 作為執行核心

唔好將 CLI 同 MCP 對立。正確做法係先將底層能力做成穩定嘅 CLI，再喺上面包一層 MCP 做分發。咁樣無論係人類、腳本定係 Agent，都可以複用同一套邏輯。

從 Agent 視角系統梳理命令行工具為什麼興起、如何設計 Agent 友好的命令行工具，並結合開源 CLI 轉換工具 OpenCLI、CLI-Anything 和釘釘、飛書、谷歌 Workspace、Stripe 等多家產品的官方 CLI 工具案例進行分析。

為什麼 Agent 時代反而更需要 CLI

過去很多人把 CLI 看成“給工程師手工敲命令的老工具”，而在 Agent 時代，這個判斷反而過時了。對於大模型驅動的 Agent 而言，CLI 並不是落後的接口，而是最天然的一類執行面：

  • 它是文本輸入、文本輸出，和 LLM 的工作方式天然匹配
  • 它通常自帶 --help、--version、退出碼、標準輸出/錯誤輸出，具備自描述性
  • 它容易組合，適合被 shell、腳本、CI/CD、子 Agent 鏈式調用
  • 它不要求額外協議棧，部署和運行成本低

更重要的是，Agent 不會像人一樣腦補一個 CLI 的意圖。

CLI 是 Agent 的理想接口

1. CLI 比 GUI 自動化更穩定

GUI 自動化依賴截圖、DOM、像素、焦點狀態和時序，天然脆弱。CLI 只要求明確的命令、參數和輸出，狀態面更小，可復現性更強。

2. CLI 比直接調 API 更接近 Agent 的工作流

API 本身當然重要，但 Agent 不一定擅長從零拼裝 HTTP 請求、認證方式、分頁邏輯和錯誤恢復。設計良好的 CLI 已經把這些複雜性收斂成命令語義，Agent 可以直接發現並調用。

3. CLI 比很多 MCP 包裝器更輕

MCP[1] 適合做權限治理、工具註冊、上下文注入和多工具編排，但並不是所有事情都值得單獨做成 MCP Server。很多 MCP 本質上只是把已有 CLI 再包一層。如果底層 CLI 已經設計得足夠好，直接調用 CLI 常常更便宜、更快，也更符合 Unix 的組合哲學。

Mario Zechner 在 MCP vs CLI 基準測試[2] 中對比了 terminalcp 的 MCP 版本和 CLI 版本，結果很有代表性：兩者都達到了 100% 成功率，差異更多來自工具設計本身，而不是協議名字本身。換句話說，協議只是管道，接口質量才是決定 Agent 成敗的核心。討論 CLI 和 MCP 時，一個常見誤區是把它們當成互斥方案。更準確的理解應該是：

  • CLI 是執行接口，先把底層能力做成穩定、可組合、可腳本化的 CLI
  • MCP 是工具分發與治理接口
  • API 是產品能力接口

這樣做的好處是：

  • 人類、腳本、Agent 都能複用同一套能力
  • 文檔、測試、錯誤碼、輸出契約只維護一份
  • 如果某個平台不支持 MCP，只要有 shell 就還能工作
圖片

Agent 友好 CLI 的 7 條設計原則

下面這組原則，綜合了開源社區知名的 CLI 工具通用經驗，以及 OpenCLI / CLI-Anything 的實踐。

1. 默認非交互

任何 Agent 可能自動化的命令，都不應依賴交互式 prompt。

推薦做法：

  • 支持 --yes、--force、--quiet、--no-input
  • 檢測非 TTY 時自動禁用交互
  • 必填項都能通過 flag、stdin、配置文件或環境變量傳入

原因很直接：當一個 Agent 啓動子 Agent，再由子 Agent 調起 CLI 時，中間通常沒有辦法把“請輸入 y/n”回傳到最上層用戶。

2. 為機器輸出結構化結果

如果命令返回的是數據，而不是純展示信息，就應該提供穩定的機器可讀格式。

推薦做法：

  • 提供 --json
  • 成功結果寫入 stdout
  • 警告、進度、錯誤寫入 stderr
  • 輸出字段命名穩定，不要今天叫 id 明天改成 resource_id

這是 Agent 友好的基礎，否則模型只能靠脆弱的文本解析來猜。

3. 錯誤要能指導下一步修復

對人類可接受的報錯，對 Agent 往往不夠。

壞報錯：

ounter(line
Error: missing required arguments

好報錯：

ounter(lineounter(lineounter(lineounter(line
Error: --content is required.
Usage: blog-cli publish --content <file> [--status <status>]
Available statuses: draft, published, scheduled
Example: blog-cli publish --content my-post.md

Agent 需要的不只是哪裏錯了，更是下一次怎麼改才對。

4. 可安全重試，邊界清晰

Agent 會重試、恢復、回放。對有副作用的命令，CLI 設計必須考慮這一點。

推薦做法：

繼續閲讀面向 Agent 的命令行工具（CLI）最佳設計實踐

參考資料

[1] 

MCP: https://modelcontextprotocol.io/

[2] 

MCP vs CLI 基準測試: https://mariozechner.at/posts/2025-08-15-mcp-vs-cli/