文章总结了构建面向智能代理(agent)的命令行界面(CLI)的10项原则，包括基础防御性设计(如确保JSON输出、可操作的错误信息)和进阶优化(如统一命名规则、支持代码模式API)，并以Cloudflare Wrangler和Runway CLI为例，说明如何通过一致性设计和开发者体验提升代理使用效率。

专为智能代理设计的CLI十大原则

核心观点：
CLI（命令行工具）的设计需优先考虑智能代理（AI Agent）的使用体验，传统以人类用户为中心的设计已无法满足需求。本文基于Cloudflare和HeyGen的实践，提出10项原则，分为两个层级：基础层确保代理不被破坏，增强层使CLI随代理使用频率提升而变得更高效。

基础层：避免破坏代理

1. 默认非交互式

   • 代理调用命令时需跳过交互提示，例如通过--force或--yes绕过确认。不一致的提示绕过规则会增加代理的调用成本。
   • 优化目标：全命令统一的非交互模式，支持结构化输入（如文件或标志）。

2. 结构化输出

   • 代理需直接解析JSON格式数据，错误信息输出到stderr，并通过退出代码分类。
   • 优化目标：全命令支持--json，禁止混用--format=json等变体。

3. 可教学的错误

   • 错误信息需包含有效枚举值（如--visibility必须是public/private/unlisted），避免代理反复尝试。
   • 优化目标：错误中直接提供解决方案和示例。

4. 安全重试与显式操作边界

   • 支持幂等操作（如重复创建返回现有资源），并通过--dry-run预览变更。异步任务需持久化状态以支持断点续传。
   • 优化目标：所有变更操作返回唯一标识符，便于代理追踪。

5. 限制输出规模

   • 默认分页或过滤结果，避免返回过量数据。API描述层（如MCP）也需精简，减少代理的解析负担。
   • 优化目标：默认返回摘要信息，并提供明确的缩小查询提示。

增强层：赋能代理

6. 跨CLI词汇一致性

   • 采用通用术语（如get/list而非info/ls），禁止--skip-confirmations等非标参数。
   • 优化目标：通过代码生成强制统一词汇，避免人工审查疏漏。

7. 三层自省机制

   • 1）传统--help；2）结构化元数据（如agent-context）；3）技能文档（如SKILL.md）。
   • 优化目标：所有层通过自动化生成保持同步。

8. 异步感知执行

   • 提供--wait选项自动轮询异步任务，并持久化任务状态（如~/.cli/jobs.jsonl）。
   • 优化目标：代理无需自行实现轮询逻辑。

9. 通过配置档案持久化身份

   • 支持保存常用配置（如--profile=my-config），并通过agent-context暴露可用档案。
   • 优化目标：代理无需重复指定固定参数。

10. 双向I/O通道

    • 支持--deliver直接输出到文件或Webhook，并通过feedback子命令收集代理的摩擦反馈。
    • 优化目标：提供可发现的反馈渠道，避免问题被忽略。

关键洞见：
- 代码生成优于人工维护：Cloudflare通过TypeScript schema统一生成CLI、SDK和API描述，确保千级操作的一致性。
- 代理优先设计惠及人类用户：例如非交互模式和结构化错误同样提升人类使用效率。

延伸阅读：
- Cloudflare的API schema实践
- HeyGen CLI设计文档

作者注：本文为早期7项原则的升级版，未来可能继续迭代。

以下是评论内容的总结，平衡呈现不同观点并保留关键引用：

支持"Agent-Native CLI"的观点

1. AI能突破传统CLI限制

   • debarshri举例：AI通过创建伪shell绕过设计限制完成数据库连接
     "It create a pseudo shell in python... acheived the goal"
   • pseudosavant认为优先考虑AI的CLI对人类也更友好
     "The CLIs I've been building... easier to use for me as a human"

2. 结构化输出价值

   • glenngillen通过实验发现JSON虽有用，但AI常依赖传统Unix工具处理数据
     "it'd make heavy use of piping JSON data to jq, cut..."
   • BobbyJo期待AI推动工具语义统一
     "cross industry semantic consistency in public tooling"

反对"Agent-Native CLI"的观点

1. 违背Unix设计哲学

   • tfrancisl警告过度适配AI会导致CLI质量下降
     "Too many tools stray so wildly from UNIX principles"
   • zbentley建议保持传统CLI设计，单独提供AI使用指南
     ""manpage for LLMs" or "manpage-as-skill""

2. 自然语言处理优势

   • Reubend指出AI更擅长处理自然语言而非JSON
     "natural language output... better than JSON for small data"
   • lighthue1批评结构化输出浪费token
     "JSON is extremely wasteful in terms of tokens"

3. 基础设计问题

   • isityettime认为现有CLI问题源于设计不严谨，与AI无关
     "When command-line tools are shit... nobody is taking the design seriously"
   • qudat质疑AI开发能力不足才需要特殊适配
     "tell us how far away they are from being junior devs"

中立/改进建议

1. 交互设计经验

   • lacymorrow强调误操作预防比语法约定更重要
     "false positives are much worse than false negatives"
   • wolttam建议用--yes替代危险的--force参数
     "--yes-do-the-dangerous-thing is leagues better"

2. 输出格式权衡

   • glenggillen尝试TOON格式但发现综合表现不如预期
     "TOON performed worse than both JSON and human output"
   • jiehong指出AI处理heredoc存在效率问题
     "waste tokens retrying with a file"

核心争议点：是否应该为AI改变CLI设计范式，以及自然语言处理与机器可读格式的优劣。支持者强调AI带来的新可能性，反对者则认为这会破坏现有设计原则且AI本应适应人类工具。