# 10分钟内构建一个适用于人工智能代理和人类用户的命令行界面
**作者**: Google Cloud Tech
**日期**: 2026-03-31T00:39:10.000Z
**来源**: [https://x.com/GoogleCloudTech/status/2038778093104779537](https://x.com/GoogleCloudTech/status/2038778093104779537)
---

今年开发的所有命令行界面(CLI)迟早都会被客服人员调用。但大多数客服人员还没有做好准备。
交互式提示、彩色输出和终端用户界面这些已成为命令行界面设计标准配置的元素,一旦自动化代理尝试解析结果,所有这些功能都会失效。但移除这些功能又会降低用户在使用命令行界面时的体验。
要解决这个问题,你不需要在两个受众群体之间做出选择。你可以同时面向这两个群体设计你的命令行界面 (CLI)。
## 为人类和人工智能代理进行设计
核心理念很简单: 将数据与呈现方式解耦 。当代理或脚本调用您的命令行界面 (CLI) 时,它需要原始的结构化数据(例如 JSON)。而当用户调用它时,他们需要将这些数据渲染成易于阅读和交互的格式(例如终端用户界面)。通过将 CLI 的内部逻辑视为一个数据引擎,并将终端用户界面视为一个可能的“客户端”,您可以无缝地同时服务于两者。

同样的“watch”命令应该为用户提供一个实时更新的 TUI 界面,并为代理提供一个 NDJSON 事件流:
您无需维护两套独立的代码库即可实现这种无缝的双受众体验。相反,您可以采用以下精心设计模式,使您的命令行界面对机器来说易于预测,同时又能保持对人类用户的愉悦体验:
## 1. 结构化可发现性
命令行界面 (CLI) 的入口点应该清晰地列出其功能。无论是代理还是用户,都会从 `--help` 命令开始操作。
按功能而非字母顺序对命令进行分组。 诸如“任务管理”、“信息”、“配置”之类的类别可以避免根帮助输出中出现大量文本。
明确标记入口点。 在帮助描述中添加类似 `(从这里开始)` 或 `(典型的第一步)` 的提示。代理程序会根据这些提示来决定首先调用哪个命令。
每个命令需要填写三个字段:
- 简短(快速浏览):一行摘要,5-10 个字,以动作动词开头。
- 深入理解:命令的作用、用途、与其他类似命令的区别。
- 示例(立即生效):3-5 个可复制粘贴的具体示例。
示例比描述更重要。开发人员会在阅读之前复制粘贴。而代理会解析示例以推断标志模式。
外部代理指令
可发现性不仅仅体现在“--help”命令上。不要想当然地认为法学硕士(LLM)天生就会使用你的工具——要明确地教他们如何使用。
在您的代码库根目录下添加一个 `AGENTS.md` 文件,用于定义交互规则、默认工作流程以及面向 AI 开发人员的架构标准。对于复杂的命令,请包含一个 `skills/` 目录,其中包含外部代理可以直接使用的专用提示文件。
## 2. 代理优先互操作性
为了便于代理使用,CLI 必须是可解析的且可预测的。

所有操作都使用 `--json` 参数
所有生成数据的命令都应该支持 `--json` 或 `--no-tui` 标志。输出应为有效的 JSON 或 NDJSON 格式。
如果代理无法解析您的输出,则您的 CLI 在代理世界中不存在。
自动检测您的受众群体
支持 `NO_COLOR` 和 `[APP]_NO_TUI` 环境变量。设置这些变量或通过管道输出标准输出时,将完全跳过交互元素。不显示提示、不显示加载指示器、不显示颜色代码。
非交互式回退方案
使用 TUI 的命令(例如珍珠奶茶应该有一个纯文本模式,可以将标准文本或 JSON 输出到标准输出。TUI 是人机交互界面。JSON 输出是代理界面。同一个命令,两种不同的渲染方式。
保护上下文窗口
代理程序对令牌数量有严格的限制。请主动截断大量文本并屏蔽默认输出中的敏感信息,以免超出代理程序的上下文窗口容量或将 API 密钥泄露到对话日志中。如果代理程序确实需要原始的、未经过滤的有效负载,则需要使用 `--full` 或 `--verbose` 等显式启用标志。
数据预处理和排序
代理程序不应该需要编写复杂的数据处理逻辑来查找重要信息。自动预先排序 CLI 输出,使最关键、最可操作的项目(例如,严重漏洞、未受限密钥、待处理任务)始终显示在响应的最上方。
委托状态管理
不要让代理陷入 CLI 进程中的交互式状态循环。使用引用标识符(例如 `--task`)保持 CLI 完全无状态。<ID> `).让后端服务维护长期运行的令牌上下文和会话历史记录,而 CLI 仅充当快速传输机制。
## 3. 配置和上下文
CLI 应该能够理解其运行环境,而无需在每次调用时都添加过多的标志。

关注 XDG
配置文件位于 `~/.config/app/config.yaml` 目录下。主目录中不应包含任何点文件。不应包含任何使用专有格式的隐藏文件夹。
命名环境
使用简单的 `--env` 标志即可支持多种配置(本地、测试、生产):
这一点对代理尤其重要。编排器可以在不知道 URL 或令牌的情况下设置 `--env prod`。
## 4. 错误指导
不要只报告错误,还要提供解决问题的方案。
上下文提示
当命令因缺少先决条件而失败时,请添加 `Hint:` 行:
智能体会解析这些提示进行自我纠错。人们也乐于不必再去查阅文档。
快速失败
在执行复杂逻辑之前,请先验证配置和连接。不要让代理等待 30 秒 API 调用后才发现缺少身份验证令牌。
确定性退出代码
- 0:成功
- 1:一般错误
- 2:无效用法/错误标志
- 3:连接/身份验证失败
如果你的 CLI 在操作失败时返回 0,原因是“命令本身已运行”,那么所有调用该命令的自动化流程都会失效。
## 5. 标志和参数一致性
命令行界面的语法应该具有内在的可预测性。如果用户(或代理)学会了如何使用某个命令,这种直觉应该能够无缝地迁移到应用程序的其他部分。
- 规范简写: 如果 `-o` 在一个命令中表示 `--out-dir`,那么它在另一个命令中绝不能表示 `--output`。不一致会破坏智能体的推理,并令开发人员感到沮丧。
- 位置参数与可选参数: 对核心必需实体使用位置参数(例如,a2acli get <task-id>),而对可选修饰符严格使用 --flags。
- 安全默认设置: 默认行为应始终是最安全、最常用的路径。破坏性操作应强制执行,并需明确设置标志。

## 6. 终端的视觉设计
颜色应该服务于功能目的,而不是美观目的。
语义颜色标记
使用基于含义的标记,而不是原始的颜色名称。这样可以保持调色板的一致性,并方便地支持浅色和深色终端。
- 强调(地标):标题、组标题、章节标签
- 命令(扫描目标):命令名称、标志
- 通过(成功):已完成的任务,成功状态
- 警告(瞬态):活动任务、警告、待处理状态
- 失败(错误):失败的任务、错误、被拒绝的状态
- 静音(弱化):元数据、类型、默认值、预览
- ID(标识符):唯一标识符(任务 ID、技能 ID)
经验法则
- 状态颜色使用默认颜色。绿色代表成功,黄色代表警告,红色代表错误。元数据使用柔和的灰色。
- 不要给描述或帮助文本着色。过度着色会导致输出结果杂乱无章,反而失去重点。
- 留白比颜色更能体现层次结构。位置和对齐方式比颜色更能传达结构。
- 同时支持浅色和深色终端。使用自适应颜色,无论用户使用何种主题,都能保持对比度。
## 7. 版本控制和生命周期
命令行工具并非静态组件。它以动态序列运行,版本会发生变化,操作会突然中断,安全工作流程也需要审计跟踪。智能地处理这些生命周期事件可以防止自动化系统中出现静默故障。
- CLI 应该知道它自己的版本(`--version`),并且可以选择通知用户自上次运行以来的重大更新。
- 妥善处理 `SIGINT` 信号(Ctrl+C)。当有人或代理终止正在运行的进程时,不会造成数据损坏。
- 跟踪写入操作中的“Actor”(源自 `git config`)。 用户名 `或`$USER`)用于审计。
面向人类的命令行界面速查表

代理 CLI 速查表
虽然人类可以使用上面的可视化速查表,但智能体需要一套自己的结构化规则。我们可以使用以下方式定义这些交互: 代理人技能格式 。
请查看 CLI 代理技能有关如何明确地教编码代理主动和确定性地导航双受众 CLI 的完整示例。
端到端工作演示:YouTube CLI
拿 YouTube CLI 举个例子。现在您可以与经纪人协作管理和审核您的 YouTube 频道。通过利用支持经纪人功能的命令行界面 (CLI) 技能,您和您的经纪人可以从 YouTube API 构建所需的工具集,用于检索频道统计信息、切换视频可见性或上传新内容。
以前,这需要寻找特定的 MCP 服务器或手动解析冗长的 YouTube API 文档。
以下是完整的演示视频:

但要让 AI 代理可靠地执行此类工作流程,底层命令行界面 (CLI) 必须针对此进行专门设计。如果 `yt-cli` 使用交互式的“确定要上传吗?(Y/n)”提示符阻止代理,或者返回无法解析的彩色终端文本,则整个自动化流程都会失败。
## 参考
- 受……启发 https://github.com/steveyegge/beads/blob/main/docs/UI_PHILOSOPHY.md
- 向这个了不起的社区致敬:https://clig.dev/
2026 年最好的命令行界面并非拥有最漂亮终端界面的那些,而是无论用户手动输入命令还是通过程序调用,都能同样流畅运行的那些。
## 相关链接
- [Google Cloud Tech](https://x.com/GoogleCloudTech)
- [@GoogleCloudTech](https://x.com/GoogleCloudTech)
- [46K](https://x.com/GoogleCloudTech/status/2038778093104779537/analytics)
- [珍珠奶茶](https://github.com/charmbracelet/bubbletea)
- [用户名](https://user.name/)
- [代理人技能格式](https://agentskills.io/)
- [CLI 代理技能](https://github.com/GoogleCloudPlatform/vertex-ai-creative-studio/tree/main/experiments/mcp-genmedia/skills/agent-aware-cli)
- [YouTube CLI](https://github.com/ghchinoy/yt-cli)
- [https://github.com/steveyegge/beads/blob/main/docs/UI_PHILOSOPHY.md](https://github.com/steveyegge/beads/blob/main/docs/UI_PHILOSOPHY.md)
- [https://clig.dev/](https://clig.dev/)
- [升级至高级版](https://x.com/i/premium_sign_up)
- [8:39 AM · Mar 31, 2026](https://x.com/GoogleCloudTech/status/2038778093104779537)
- [46.9K Views](https://x.com/GoogleCloudTech/status/2038778093104779537/analytics)
- [View quotes](https://x.com/GoogleCloudTech/status/2038778093104779537/quotes)
---
*导出时间: 2026/4/1 02:06:41*