cli-for-agents

面向 Agent 的 CLI 设计最佳实践

面向 AI Agent 和脚本的命令行界面设计规范与评审标准，不仅适用于在提示符处输入命令的人类用户。以人为中心的 CLI 常常会阻碍 Agent：交互式提示、开篇文档过长、帮助文本缺少可复制粘贴的示例、错误消息没有修复建议、没有试运行模式。本技能按影响范围排序规则——从“Agent 完全无法使用此 CLI”（严重）到“Agent 需要多查看一次帮助”（中等）。

构建新的 CLI 和评审现有 CLI 是否方便 Agent 使用时，都可使用本技能。

本技能包含 8 个类别的 45 条规则。

适用场景

在以下情况下，请参考这些指南：

• 为任何子命令编写 --help 文本
• 设计新的标志、参数或子命令
• 编写错误消息或设置退出码
• 添加需要试运行或确认的破坏性操作
• 在交互式提示和仅使用标志的输入方式之间做出选择
• 设计成功输出，以便 Agent 能够串联命令
• 评审现有 CLI 是否出现无头使用方面的回归

按优先级划分的规则类别

优先级	类别	影响	前缀
1	非交互式操作	严重	interact-
2	帮助文本设计	高	help-
3	错误消息	高	err-
4	破坏性操作安全性	高	safe-
5	输入处理	高	input-
6	输出格式	中高	output-
7	幂等性与重试	中高	idem-
8	命令结构	中	struct-

注意：help-examples-in-help 在高优先级的 help- 类别中被评为严重，因为其具体问题——帮助文本没有示例——会让其他所有帮助规则都失去意义。类别标签反映的是平均水平，而非最严重的情况。

快速参考

1. 非交互式操作（严重）

• interact-flags-first — 优先将每项输入都设为标志；提示仅作为 TTY 环境下的备用方式
• interact-detect-tty — 提示前检查 isatty()
• interact-no-arrow-menus — 用通过标志选择的选项替代方向键菜单
• interact-no-input-flag — 支持 --no-input 以强制进入非交互模式
• interact-no-timed-prompts — 切勿使用限时提示或“按任意键”屏幕
• interact-no-hang-on-stdin — 连接了 TTY 时，不要因等待标准输入而阻塞

2. 帮助文本设计（高）

• help-examples-in-help — 在每个 --help 中都加入可复制粘贴的示例
• help-per-subcommand — 每个子命令都应有自己的 --help
• help-no-flag-required — 不带参数调用时显示帮助
• help-layered-discovery — 顶层帮助应作为导航索引
• help-flag-summary — 列出每个标志的短格式和长格式
• help-suggest-next-steps — 在帮助和成功输出中建议接下来要运行的命令

3. 错误消息（HIGH）

• err-exit-fast-on-missing-required — 缺少必需标志时快速退出
• err-actionable-fix — 在每条错误消息中提供具体的修复方法
• err-stderr-not-stdout — 将错误发送到 stderr，而非 stdout
• err-non-zero-exit-codes — 为不同故障使用不同的非零退出码
• err-include-example-invocation — 在错误消息中提供正确的调用示例
• err-no-stack-traces-by-default — 仅在 --debug 模式下显示堆栈跟踪

4. 破坏性操作安全（HIGH）

• safe-dry-run-flag — 为每个破坏性命令提供 --dry-run
• safe-force-bypass-flag — 提供 --yes / --force 以跳过确认
• safe-confirm-by-typing-name — 对不可逆操作，要求输入资源名称以确认
• safe-no-prompts-with-no-input — 设置 --no-input 时绝不显示提示
• safe-idempotent-cleanup — 删除目标已不存在时也成功退出
• safe-crash-only-recovery — 将多步骤命令设计为仅需崩溃后恢复

5. 输入处理（HIGH）

• input-accept-stdin-dash — 接受 - 作为 stdin 和 stdout 的文件名
• input-flags-over-positional — 优先使用命名标志，而非位置参数
• input-stdin-for-secrets — 通过 stdin 或文件接收密钥，绝不将其作为标志值
• input-env-var-fallback — 支持通过环境变量传递常用标志
• input-no-prompt-fallback — 标志缺失时绝不回退到提示

6. 输出格式（MEDIUM-HIGH）

• output-json-flag — 提供 --json 以输出稳定的机器可读格式
• output-ndjson-streaming — 将大型结果集以 NDJSON 格式流式输出
• output-bounded-by-default — 使用 --limit 和 --all 限制默认输出大小
• output-machine-ids-on-success — 成功时返回可链接的值，而非仅返回“完成”
• output-respect-no-color — 设置 NO_COLOR 或非 TTY 时禁用 ANSI 颜色
• output-no-decorative-only — 避免仅依靠装饰性输出传达状态
• output-one-record-per-line — 人类可读且便于 grep 的输出中，每行输出一条记录

7. 幂等性与重试（MEDIUM-HIGH）

• idem-retry-safe — 确保同一命令重复运行是安全的
• idem-create-or-skip — 目标已存在时，创建命令应跳过
• idem-stable-output-on-skip — 无论执行操作还是跳过，均返回相同结构的输出
• idem-state-reconciliation — 优先采用“确保状态”语义，而非应用增量变更
• idem-stable-identifiers — 接受用户提供的名称，而非自动生成 ID

8. 命令结构（中）

• struct-resource-verb — 使用一致的「资源-动词」命令形式
• struct-flag-order-independent — 支持在子命令前后任意位置解析标志
• struct-no-hidden-subcommand-catchall — 避免为未知子命令设置兜底处理器
• struct-standard-flag-names — 使用标准标志名称（--help、--version、--verbose、--quiet）

使用方法

构建新的 CLI 时

从 CRITICAL 开始，逐项向下检查。前两个类别（interact- 和 help-）不可妥协——如果违反其中任何一条规则，无论其他部分做得多好，Agent 都无法使用该 CLI。完成这两类后，再依次检查 err-、safe- 和 input-——大多数实际使用中的阻碍都出现在这里。output-、idem- 和 struct- 则是锦上添花，能在多次调用中累积效果。

审查现有 CLI 时

按优先级依次检查以下清单：

1. 非交互路径 — 使用 --no-input 调用每个子命令，或通过 </dev/null 运行，检查哪些命令会挂起
2. 分层帮助 — mycli --help 是否只列出子命令，还是会输出所有内容？
3. --help 中的示例 — 每个子命令的帮助信息末尾都应包含可运行的 Examples 部分
4. 包含调用信息的错误消息 — 每条错误是否都明确告知调用方应添加哪个标志？
5. stdin/管道支持 — 能否将输出通过管道传入输入？- 是否表示 stdin？
6. 退出代码 — 用法错误（2）、运行时失败（1）和暂时性失败（69）是否彼此区分？
7. 试运行 — 每个破坏性命令是否都有 --dry-run（或等效选项）？
8. 跳过确认 — 每个破坏性命令是否都有 --yes/--force？
9. 一致的命令结构 — service list、deploy list 和 config list 是否都存在且行为一致？
10. 结构化成功输出 — deploy 是否会返回供 Agent 后续使用的 deploy_id？

单项规则

阅读各参考文件，了解详细说明和代码示例：

• 章节定义 — 类别结构和影响级别
• 规则模板 — 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息