面向 Agent 的命令行工具（CLI）最佳设计实践

从 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 适合做权限治理、工具注册、上下文注入和多工具编排，但并不是所有事情都值得单独做成 MCP Server。很多 MCP 本质上只是把已有 CLI 再包一层。如果底层 CLI 已经设计得足够好，直接调用 CLI 常常更便宜、更快，也更符合 Unix 的组合哲学。

Mario Zechner 在 MCP vs CLI 基准测试中对比了 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 往往不够。

坏报错：

Error: missing required arguments

好报错：

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 设计必须考虑这一点。

推荐做法：

幂等化创建/更新类操作
提供 --dry-run
危险操作必须显式确认
返回可审计标识，如资源 ID、任务 ID、变更摘要

5. 帮助系统要支持渐进发现

Agent 通常不会先读完整文档，而是这样探索：

tool --help
tool subcommand --help
看一两个例子再尝试执行

因此好的 --help 至少要包含：

命令用途
用法形状
必选参数
常用例子

6. 命令结构要一致，可组合

Agent 很依赖模式学习。如果 posts list 用 --limit，comments list 又换成 --max-results，模型就要多记一个例外。

推荐做法：

相关命令复用同一套 flag 命名
支持 stdin / stdout 管道
保持子命令层级稳定

7. 输出要有边界，默认高信号

人类能滚动看 500 行日志，Agent 会把这 500 行一股脑放进上下文窗口。

推荐做法：

默认分页/限量
支持 --limit、--page、--since
截断时告诉用户如何继续缩小范围

这不是“抠 token”，而是让模型把注意力放在真正重要的信息上。

CLI-Anything：把任何软件转换为 Agent 原生 CLI

CLI-Anything 是最近最有代表性的项目之一。它的目标是解决一个更底层的问题：现实世界里大量软件只有 GUI、插件接口或内部代码结构，并没有一套真正适合 Agent 消费的命令行面。

CLI-Anything 的做法，是把为现有软件生成一个 Agent 友好的 CLI这件事流程化、工程化。

CLI-Anything 是什么

CLI-Anything 可以把软件转化为 Agent 可控的 CLI 工具，生成一套可以安装、测试、调用、维护的正式 CLI 包，并强调所有生成出的命令都支持 --help 与 --json，目标是兼容 Claude Code、Cursor 等主流 Agent 框架。

CLI-Anything 怎么工作

CLI-Anything 官网把它总结为全自动 7 阶段流水线：

分析：扫描目标代码库，识别可暴露的能力和内部调用路径
设计：规划命令组、状态模型、输入输出约定
实现：生成带 REPL、--help、--json 的 CLI
规划测试：生成测试计划
编写测试：补齐单元测试和端到端测试
文档：生成命令文档与说明
发布：把结果打包成可安装 CLI

从官网 FAQ 可以看出，它优先直接对接真实软件后端。也就是说，CLI-Anything 理想中的转换路径不是：

用户动作 -> 录制鼠标键盘 -> 回放

而是：

用户动作 -> 映射为软件已有内部能力 -> 生成稳定 CLI 命令

这也是它比 RPA 更适合 Agent 的原因：输出可预测、命令可复用、测试可自动化。

CLI-Anything 的核心优势

很多专业软件并不是没有能力，而是缺少适合 Agent 消费面。CLI-Anything 等于给这些软件补了一层标准执行面。
其生成结果不仅可运行，而且配套测试、文档和安装结构。这比单纯让模型临时写个 wrapper 稳定得多。
把 Agent 友好性写进了产物，生成出的 CLI 默认带：

--help
--json
REPL/会话支持
可安装包结构
测试套件

也就是说，CLI-Anything 的目标是把软件暴露给 Agent。

CLI-Anything 转换案例：从 GUI 软件到命令接口

官网列出的覆盖面很广，包括 GIMP、Blender、LibreOffice、Audacity、Kdenlive、OBS Studio、JupyterLab 等。可以把它理解为几类典型转换。

案例 1：LibreOffice

传统流程里，让 Agent 生成 Word/PDF 往往只能停留在帮你写一段文案。如果需要真正创建文件、导出 PDF、批量处理文档，就得接系统级能力。

CLI-Anything 的思路是把 LibreOffice 真实后端能力转成命令，例如：

cli-anything-libreoffice document create --template report --json
cli-anything-libreoffice document export --input report.odt --format pdf --json

这样 Agent 就可以真正完成导出动作，并拿到结构化结果。

案例 2：Blender

3D 软件一直是 Agent 自动化的困难区，因为 GUI 复杂、状态繁多、批处理需求强。CLI-Anything 官网明确提到 Blender 是目标之一，这类软件一旦补上 CLI，Agent 就可以围绕场景、渲染、导出、批量参数修改构建工作流。

案例 3：GIMP / Audacity

图像和音频工具往往带有大量细粒度操作。CLI-Anything 的价值在于把高频、可批处理、可参数化的动作变成稳定命令，例如：

批量裁剪、导出图片
将素材转换为指定格式
套用一组固定滤镜
对音频做统一降噪或格式转换

CLI-Anything 的局限

CLI-Anything 适合软件有代码库、有内部能力、值得沉淀成正式命令行的场景，但它并不总是最佳方案：

如果你只是临时操作一个网站，一次性的浏览器控制更快
如果目标系统根本没有可复用后端，只能做 GUI 录制，那确定性会下降
如果软件能力变化极快，生成后的 CLI 也需要持续维护

OpenCLI：把网站、桌面应用和本地工具统一成一个 CLI Hub

如果说 CLI-Anything 解决的是“没有 CLI 的软件，如何生成一个 CLI”，那么 OpenCLI 解决的是另一类问题：系统里已经有很多工具和网站，但 Agent 缺少统一、稳定、低成本的入口。

OpenCLI 是什么

OpenCLI 在 GitHub README 中把自己定义为：

universal CLI Hub
AI-native runtime
可以把网站、浏览器会话、Electron 应用、本地工具转成标准化命令接口

它不是单一产品的专用 CLI，而是一个统一入口层。

OpenCLI 怎么工作

从 README 和官方说明可以整理出 OpenCLI 的几条核心工作路径：

1. 内建适配器

OpenCLI 自带多个网站/产品适配器，Agent 可以直接用统一命令形状调用，例如：

opencli list
opencli hackernews top --limit 5
opencli bilibili hot --limit 5

这类能力的重点不是能打开网站，而是把网站动作收束成确定命令。

2. Browser Bridge + 本地守护进程

OpenCLI 通过浏览器扩展和本地 daemon 连接 Chrome/Chromium，会复用浏览器现有登录态。这样做有两个好处：

Agent 不需要重新实现复杂登录流程
凭证不直接离开浏览器环境，安全边界更清晰

它等于提供了一条浏览器自动化以 CLI 形式暴露的路线。

3. `browser` 低层控制面

对于暂时还没有稳定适配器的网站，OpenCLI 允许 Agent 直接使用浏览器控制命令，例如打开页面、点击、输入、等待、抓取、截图、执行脚本、查看网络请求等。README 中列出的能力包括：

open
click
type
select
wait
get
screenshot
scroll
network
eval

这让 OpenCLI 兼具两种模式：

已沉淀好的稳定命令模式
尚未沉淀的实时浏览器控制模式

4. 从浏览器行为反向生成适配器

OpenCLI 不只是控制浏览器，explore、synthesize、generate、cascade 等命令，还尝试把真实浏览器里的行为提炼为新适配器。这一点和 CLI-Anything 有相似性，但目标对象不同：

CLI-Anything 偏软件代码库
OpenCLI 偏网站、Electron 应用、已有本地 CLI

OpenCLI 的核心优势

1. 统一入口

对 Agent 来说，最大的成本往往不是执行，而是发现。OpenCLI 把网站适配器、本地 CLI 注册、浏览器控制、桌面应用控制放在同一个命令表面之下，降低了探索成本。

2. 登录态复用

对需要账号上下文的网站而言，认证往往是最难的部分。OpenCLI 通过复用浏览器现有登录态，把 Agent 真正带进用户已经登录的工作环境。

3. 运行期不消耗 LLM token

OpenCLI 明确强调运行时零 LLM 成本。这意味着一旦命令适配层沉淀完成，后续大规模执行不会再持续为理解 UI付费。

OpenCLI 多个案例

案例 1：把网站变成可调用命令

对于信息获取或高频网站动作，OpenCLI 适合把“打开网页、找按钮、点几次、复制结果”变成：

opencli reddit hot --limit 10 --format json
opencli x search "agent native cli" --format json

一旦命令确定下来，Agent 不再需要每次重新读页面。

案例 2：把 Electron 应用纳入终端

README 明确提到 Cursor、Codex、ChatGPT、Notion 等 Electron 应用。对 Agent 而言，这相当于把原本只能人看着点的桌面应用，纳入统一执行面。

案例 3：把本地 CLI 纳入统一发现面

OpenCLI 也支持注册外部 CLI，比如 gh、docker。这样一个 Agent 不需要分别学习多个入口，而可以先从 opencli list 探测，再决定调用哪个子命令。

OpenCLI 与 CLI-Anything 的差异

两者容易被放在一起讨论，但它们解决的问题不一样：

维度	CLI-Anything	OpenCLI
主要对象	有代码库的软件	网站、浏览器、Electron、本地 CLI
核心动作	生成新的正式 CLI	统一调度和适配现有工具/网站
工作方式	代码分析 + 7 阶段流水线	适配器 + 浏览器桥接 + 命令发现
最适合场景	需要长期沉淀正式接口	需要快速接管现有工具生态

简单说：

你要把一个没有 CLI 的软件产品化为 CLI，更接近 CLI-Anything
你要把散落的网站和工具统一到一个 Agent 入口，更接近 OpenCLI

几个值得关注的官方 CLI 工具

为了避免把“Agent 友好 CLI”聊得过于抽象，下面按产品举一些现实世界里的代表。它们未必都从一开始就是为 Agent 设计的，但很多已经具备相当好的 Agent 可用性。

1. GitHub CLI

GitHub CLI 官方文档将其定义为开源命令行工具，可把 Pull Request、Issue、GitHub Actions 等能力带到终端里；其官方仓库是 cli/cli。

为什么它对 Agent 友好：

命令层级清晰，如 gh pr, gh issue, gh repo
帮助系统完善
很多命令支持 --json
功能语义稳定，训练数据覆盖也广

这类 CLI 是官方产品能力已经很好地命令化的典型。

2. Google Cloud CLI

Google Cloud CLI 概览明确写到：它是一组用于创建和管理 Google Cloud 资源的工具，既可在命令行中运行，也可用于脚本和自动化。

对 Agent 特别重要的点是：

支持脚本和自动化
--quiet 可关闭交互
成功输出写 stdout，提示/警告/错误写 stderr
--format 支持 json、csv、yaml、value

这几乎就是 Agent 友好 CLI 的标准答案。

3. Stripe CLI

Stripe CLI 文档把它定义为“用命令行构建、测试和管理 Stripe 集成”的工具。

它的典型 Agent 友好能力包括：

调 API 和资源管理都能命令化
本地 webhook 转发非常适合开发自动化
适合作为“支付系统的稳定执行面”

对 Agent 来说，Stripe CLI 的价值不是“替代 API”，而是把认证、请求形状、常见开发动作封装成稳定命令。

4. Cloudflare Wrangler

Cloudflare Wrangler 文档直接把 Wrangler 定义为 “Cloudflare Developer Platform CLI”，其代码位于 cloudflare/workers-sdk。

它是典型的“平台型 CLI”：

管理 Worker 项目
部署与开发调试一体化
适合脚本和 CI

这类 CLI 虽然不是为 Agent 生的，但因为结构规整，天然容易被 Agent 消费。

5. 飞书 CLI

飞书官网文章《飞书CLI安装与使用指南：让AI Agent真正接入飞书！》直接把飞书 CLI 定义为“飞书官方开源的命令行工具”，并强调它是为 AI Agent 使用方式专门设计，而不是简单包装 API。文章提到的能力范围包括：

读取消息和群聊记录
查询和创建日历事件
读写云文档
管理多维表格
发送和阅读邮件
搜索知识库和通讯录

这类工具非常有代表性：企业协作产品过去往往只提供 REST API，而没有真正为 Agent 打磨过的命令入口。飞书 CLI 说明，办公协作系统也开始把 Agent 当成一类一等公民消费者。

6. 企业微信 wecom-cli

企业微信这边，当前最接近“Agent 原生命令行”的是 WecomTeam/wecom-cli。其 README 与 docs.rs 页面都把它描述为“企业微信开放平台命令行工具，让人类和 AI Agent 都能在终端中操作企业微信”，并提供命令参考文档。

它覆盖的能力包括：

通讯录
待办
会议
消息
日程
文档
智能表格

安装方式为 npm install -g @wecom/cli。相关文档可见 docs.rs 页面

7. 钉钉 CLI

8. 即梦 CLI

总结

Agent 必须知道工具能做什么，所以需要：

--help
list
清晰的命令层级
可推断的命名模式

2. 执行层

Agent 必须能稳定执行，所以需要：

非交互默认
幂等或可审计副作用
标准退出码
stdout / stderr 分离

3. 解析层

Agent 必须拿到可消费结果，所以需要：

--json
稳定字段
默认高信号输出
支持分页、过滤和 limit

CLI 会成为 Agent 的基础设施

CLI 正在从给人类手工操作的界面，变成给 Agent 稳定消费的基础设施。从这个视角再看：

CLI-Anything 是在为没有 CLI 的软件补基础设施
OpenCLI 是在为分散的网站与工具统一基础设施
gh、gcloud、stripe、wrangler、飞书 CLI、wecom-cli 则说明越来越多产品开始主动把 CLI 当成正式产品面

如果你今天在设计一个面向 AI 的产品或内部工具，需要思考一下：

这项能力有没有一个稳定、可发现、可脚本化的 CLI 面？
它是否支持 --help、--json、非交互执行和可恢复错误？
如果明天接入 Claude Code、Codex、Cursor、Copilot CLI，它能否被直接消费？

很多团队会发现，真正缺的不是更聪明的 Agent，而是更像样的 CLI。

面向 Agent 的命令行工具（CLI）最佳设计实践

为什么 Agent 时代反而更需要 CLI

CLI 是 Agent 的理想接口

1. CLI 比 GUI 自动化更稳定

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

3. CLI 比很多 MCP 包装器更轻

Agent 友好 CLI 的 7 条设计原则

1. 默认非交互

2. 为机器输出结构化结果

3. 错误要能指导下一步修复

4. 可安全重试，边界清晰

5. 帮助系统要支持渐进发现

6. 命令结构要一致，可组合

7. 输出要有边界，默认高信号

CLI-Anything：把任何软件转换为 Agent 原生 CLI

CLI-Anything 是什么

CLI-Anything 怎么工作

CLI-Anything 的核心优势

CLI-Anything 转换案例：从 GUI 软件到命令接口

案例 1：LibreOffice

案例 2：Blender

案例 3：GIMP / Audacity

CLI-Anything 的局限

OpenCLI：把网站、桌面应用和本地工具统一成一个 CLI Hub

OpenCLI 是什么

OpenCLI 怎么工作

1. 内建适配器

2. Browser Bridge + 本地守护进程

3. browser 低层控制面

4. 从浏览器行为反向生成适配器

OpenCLI 的核心优势

1. 统一入口

2. 登录态复用

3. 运行期不消耗 LLM token

OpenCLI 多个案例

案例 1：把网站变成可调用命令

案例 2：把 Electron 应用纳入终端

案例 3：把本地 CLI 纳入统一发现面

OpenCLI 与 CLI-Anything 的差异

几个值得关注的官方 CLI 工具

1. GitHub CLI

2. Google Cloud CLI

3. Stripe CLI

4. Cloudflare Wrangler

5. 飞书 CLI

6. 企业微信 wecom-cli

7. 钉钉 CLI

8. 即梦 CLI

总结

2. 执行层

3. 解析层

CLI 会成为 Agent 的基础设施

参考来源

3. `browser` 低层控制面