设计 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 must be one of: public, private, unlisted”这样的错误则允许 agent 在单次重试中进行自我纠正。

  • 标准： 当拒绝不符合 enum 或 schema 的输入时，直接在错误消息中呈现有效的取值范围。

4. 安全重试与明确的变更边界

Agent 经常进行重试。如果没有幂等性，重试的“create”命令会导致重复的资源。

  • 标准： 使用幂等性 token 或自然键。
  • 优化： 为具有后果的操作实现 --dry-run，并确保破坏性操作需要一个明确的、非默认的标志。

5. 受限的响应

无限制的输出会浪费 token 并可能撑爆 agent 的上下文窗口。

  • 标准： 在所有列表类命令上实现分页、限制和过滤。
  • 优化： 提供截断消息，明确教导 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 为异步任务编写自己的轮询循环是极其耗费 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 而过度设计，从而牺牲了人类的可用性，认为如果给 agent 提供足够好的“面向 LLM 的 manpage”，它们就足以应付混乱的 CLI。

无论哲学分歧如何，实际结果是一样的：一个可预测、结构化且一致的 CLI 对每种用户都更优，无论是碳基生命还是硅基生命。

Sources