cli-design

CLI 设计：支持 Unix 组合的命令行界面

本技能介绍语言无关的 CLI 设计原则。无论使用哪种实现语言，关于流分离、退出码、格式标志和可组合性的规则都适用。

本套内容改编自 CC BY-SA 4.0 许可的命令行界面指南。 来源固定信息、修改说明和许可范围记录在 resources/source-notes.md 和 LICENSE 中。

有关 API 契约稳定性和 Hyrum 定律，请参阅 api-design 技能。有关配置、环境变量和优雅关闭，请参阅 twelve-factor 技能。

TypeScript 实现模式位于 resources/ 目录中。使用 TypeScript 构建 CLI 时，可按需加载：

资源	加载时机……
output-architecture.md	实现 Result 类型、入口接线、格式化器、日志记录器、JSON 信封架构时
testing-cli.md	为 CLI 行为（流、退出码、管道、契约测试）编写 Vitest 测试时
stream-contracts.md	了解 Node.js 缓冲、NDJSON、信号处理、仅崩溃设计时
composability.md	设计或测试管道行为时——包含完整的 shell 示例（jq 过滤、NDJSON 流式处理、stdin、链式调用、--fields、并行 xargs）

---

适用场景

• 构建任何命令行工具（任何语言）
• 设计命令树、标志和 I/O 契约
• 实现输出层（格式检测、流路由）
• 测试 CLI 行为（stdout/stderr 分离、退出码）
• 审查 CLI 的 Unix 可组合性

---

核心原则

stdout 只用于数据——也就是用户请求的内容。 stderr 用于其他所有内容——诊断信息、进度、旋转指示器、警告和错误。

这种分离让 mycli --json | jq ... 能够正常工作。在 stdout 中输出一个旋转指示器字符，就会破坏所有下游管道。

“无论你在构建什么软件，都可以完全确定，人们会以你意想不到的方式使用它。你的软件会成为更大系统的一部分——你唯一能选择的，是让它成为一个行为良好的部分，还是一个不守规矩的部分。” — clig.dev

---

Unix 流契约

内容	流	原因
主要输出（数据、结果、JSON）	stdout	可通过管道传递，可通过缓冲提高吞吐量
进度条、旋转指示器、状态	stderr，且仅在 stderr 是 TTY（process.stderr.isTTY）时输出——经管道传递的 stderr 只承载警告和错误，不承载其他内容	这些不是数据——不得破坏管道，而且管道的接收方不会想要旋转指示器
警告、错误、诊断信息	stderr	即使 stdout 通过管道传递，用户也能看到
调试/详细输出	stderr	属于诊断信息，绝不是数据

流行为：

• 独立检查 stdout 和 stderr；stdout 通过管道传递不代表 stderr 也通过管道传递
• 不要假设 C stdio 的行缓冲/块缓冲/无缓冲规则能描述所有语言运行时
• 在 Node.js 中，同步/异步进程流行为会因操作系统和目标位置而异；高流量输出时，始终遵循 .write() 的背压机制

stdout 通过管道传递时，用户不希望状态消息混入数据。所有非数据输出都必须写入 stderr。

有关缓冲行为及其对性能的影响，请参阅 resources/stream-contracts.md。

---

保持处理函数纯粹

实用原则：负责执行操作的函数应返回数据，而不是写入 stdout。 CLI 入口点负责所有 I/O。

Entry point (CLI main)              Your logic (handlers)
─────────────────────               ─────────────────────
parse args                          (input) → structured result
detect format (json/plain/human)    no printing to stdout
call handler                        no writing to stderr
format the result                   no calling exit
write to correct stream             just returns data
set exit code

这不是架构上的硬性要求——这只是整洁的函数设计，但有一条明确的界限：只有入口点文件可以写入流或结束进程。 扩展或编辑一个已经会打印或退出的模块时，应在同一次修改中将写入操作移到入口点——不要让它继续留在那里，也绝不要因为“那个函数本来就会这么做”而在旁边再添加更多打印。这样做有切实的好处：

• 无需启动子进程即可测试——调用处理函数，并断言其返回值
• 轻松支持多种格式——只需替换一个函数，同一份数据就能渲染为 JSON、纯文本或彩色表格
• 可复用——同一个处理函数可用于 CLI、MCP 服务、HTTP API 或程序化导入

对于“处理函数”只是调用一个库的简单 CLI，这种分离本来就自然存在——库返回数据，CLI 负责格式化。无需额外增加层级。

如果你的项目采用六边形架构，这种映射很直接：CLI 入口点是一个驱动适配器，处理函数则是通过端口返回结果的用例。请参阅 hexagonal-architecture 技能——这些模式可以相互强化，但要从保持处理函数纯粹中获益，并不要求使用六边形架构。

TypeScript 实现模式（Result 类型、入口点连接、格式化器、日志记录器接口）请参阅 resources/output-architecture.md。

---

选择 TypeScript 技术栈

如果仓库已有的命令和提示词库能够满足本技能的约定，优先使用它们。要引入重要的新依赖时，请检查当前版本和项目限制，并使用 evaluate-existing-solutions；不要根据对流行度的记忆或过时的包特性来选择。

Stricli 适用于类型化、注入式的命令处理函数，@clack/prompts 则适用于可选的、受 TTY 控制的交互。将它们视为候选项，而非默认选项。请结合现有技术栈和其他方案，从处理函数可测试性、类型安全、目标运行时中测得的启动成本、维护性、依赖体量、非交互行为和迁移成本等方面进行比较。

---

格式标志约定

三级输出层级：

默认：面向人的可读格式

• 颜色、表格、格式化文本
• 在 stderr 上显示进度条和旋转指示器
• 输出适配终端宽度
• 不同版本之间可能变化——这不是一项约定

--plain：便于 Grep/Awk 处理

• 每行一条记录，不做格式化，不使用颜色
• 在次要版本之间保持稳定——这是一项约定
• 表格行平铺显示，不带边框，不按分组划分区块
• 支持：mycli list --plain | grep error | wc -l

“鼓励用户在脚本中使用 --plain 或 --json，以保持输出稳定。”——clig.dev

--json：结构化数据

• 成功时，stdout 仅包含有效 JSON——不显示加载动画、颜色或进度
• 任何非零退出时，stdout 均为空，stderr 最后一条非空行是结构化 JSON 错误封装
• 这也包括领域失败（退出码 1）：运行已完成且数据已存在，但未达到阈值、门槛或预算。这属于失败，而不是在成功封装中携带一个 false 标志。如果调用方仍需要这些数据，请将其放入 error（details 字段），绝不能输出到 stdout
• 其他诊断信息可以出现在 stderr 的最后一行之前，且绝不会污染 stdout；使用方应解析最后一条非空行，而不是整个诊断流
• Schema 有版本管理——JSON 输出的破坏性变更也属于 CLI 的破坏性变更
• 无论 TTY 状态如何，--json 都表示非交互模式

统一的封装：

stdout 中的成功响应：

{ "ok": true, "data": { ... } }

封装不可省略，也不会重命名任何内容：使用方要求的字段名应在 data 中保持不变；记录列表应放在 data 中，而不是用裸数组取代封装。

stderr 中的失败响应：

{ "ok": false, "error": { "code": "CONFIG_MISSING", "message": "...", "fix": "..." } }

用于流式传输的 NDJSON

对于大型数据集，请使用 NDJSON（每条记录对应一个 JSON 文本，以 \n 结尾）：

• 每一行都可以独立解析
• 任何 JSON 值都是有效的 NDJSON 语法；其 Schema 由应用程序的解码器负责
• 本技能中的示例使用一种可选的本地事件配置，其中包含 type 判别字段和可选的最终摘要记录；NDJSON 并不要求这些内容
• 说明读取方是忽略还是拒绝空行
• 支持：mycli run --format ndjson | while read -r line; do ...; done

NDJSON 规范详情请参阅 resources/stream-contracts.md。

---

退出码

代码	含义	适用情况
0	成功	操作按预期完成
1	领域失败	工具特定的失败（例如未达到质量阈值）
2	用法无效	标志错误、缺少必需参数、验证错误
78	配置错误	配置文件无效、缺少必需配置
75	临时且可安全重试的失败	失败发生在派发之前，或有文档说明且可证明操作可安全重试
130	SIGINT	用户按下了 Ctrl-C（128 + 2）
143	SIGTERM 风格的状态	保留信号终止状态时使用的可选文档化状态（128 + 15）；经过处理的正常关停也可以返回 0

规则：

• 非零退出码必须附带 stderr 说明
• 在 --help 中记录退出码
• 应用程序错误绝不使用大于 125 的代码（此范围保留给信号：128 + 信号编号）
• 仅在未派发任何变更，或已通过幂等性／对账确立可安全重试时，才使用退出码 75；仅仅是暂时性原因并不足够
• 如果变更请求可能已到达目标位置，应报告结果不确定，并引导用户使用 status／对账，而不是鼓励用户盲目重试
• 经过处理的 SIGTERM 可以返回 0，也可以返回文档化的应用程序状态（例如 143）；Docker 和 Kubernetes 并不要求正常关停必须返回 143
• 将非零代码映射到工具最重要的失败模式
• 调用方只是没有传入某个标志，并不属于用法无效。退出码 2 用于工具无法处理的输入；新增的门槛、阈值或筛选标志应为可选项——缺少这些标志意味着关闭相应检查，命令仍以 0 成功退出。只有在没有该标志命令便毫无意义时，才将新标志设为必需；否则，所有普通调用都会变成用法错误，掩盖这些退出码原本要区分的失败
• 按顺序安排检查，确保每种失败都对应到说明该失败的代码：后续验证不得拦截配置或数据错误，并将其报告为用法错误

---

TTY 检测

检查优先级顺序（匹配第一项即停止）：

优先级	条件	效果
1	--format json 或 --json 标志	非交互模式、无颜色、无动画
2	--no-color 标志	禁用颜色（输出仍可能是交互式的）
3	FORCE_COLOR 环境变量	空值、1、2、3 或 true 启用颜色；其他所有值（包括 0）均禁用颜色。受支持的值会覆盖 NO_COLOR 和 NODE_DISABLE_COLORS
4	NO_COLOR（非空）或 NODE_DISABLE_COLORS（已定义），且 FORCE_COLOR 未设置	禁用颜色
5	TERM=dumb	禁用颜色和动画
6	CI=true	不显示交互提示
7	stdout 不是 TTY（!isatty(stdout)）	输出纯文本，stdout 上不显示动画
8	默认	完整交互模式，带颜色

在入口点中一次性解析输出模式，并在写入任何内容之前完成。 按照上表检查格式标志、--no-color、FORCE_COLOR、NO_COLOR、TERM、CI 以及每个流的 TTY 状态（isatty/isTTY），将结果归为一个模式值并传给格式化器。即使当前输出还没有颜色和动画，也要写好这项检查：无论哪天添加其中一项，都能确保决策集中在一处。

分别检查 stdout 和 stderr。 当 stdout 被重定向，而 stderr 是 TTY 时，仍可在 stderr 上显示旋转指示器，同时保持 stdout 干净，供管道的下游程序使用。状态行、旋转指示器和进度信息仅在承载它们的流是 TTY 时写入；stderr 被重定向到管道时，只输出警告和错误，不输出其他内容。

独立根据 stdin 判断是否显示提示。 仅当 stdin 和提示的输出流都是 TTY 时才显示提示；stdout 的 TTY 状态决定数据格式，而不是决定是否可以安全地请求输入。

可选择支持 MYCLI_NO_COLOR，用于应用专属的颜色覆盖设置。

---

输入设计

优先使用标志，而非位置参数

• 1 个位置参数：可以接受（“主要对象”）
• 2 个位置参数：值得警惕——考虑改用标志
• 3 个或更多位置参数：优先使用命名标志，除非熟悉的命令语法能让参数位置一目了然
• 例外：同一类型的可变参数可以接受（rm a.txt b.txt c.txt），通用惯例也可以接受（cp source dest）

标志具有自描述性，不受顺序影响，也更易于扩展。

# Bad — which is source, which is destination?
mycli copy myapp backup

# Good — explicit
mycli copy --from myapp --to backup

标准标志

始终提供长格式。仅为最常见的操作提供短格式。

标志	含义
-h、--help	显示帮助（此标志仅用于显示帮助）
--version	将版本输出到 stdout
-q、--quiet	禁止非必要输出
-v、--verbose	在面向用户的输出中提供更多细节
-d、--debug	将诊断信息输出到 stderr
-f、--force	跳过确认提示
-n、--dry-run	显示将执行的操作，但不实际执行
--json	结构化 JSON 输出
--plain	稳定、便于 grep 的纯文本
--no-color	禁用彩色输出
--no-input	禁用所有提示和交互
-o、--output	输出文件
--fields	选择输出列

提示词与交互

• 所有提示都必须能通过标志跳过，以便用于脚本
• 确认 → --yes 或 --force
• 选择 → --type=value
• 文本输入 → --name=value
• 密码 → --password-file=path 或通过 stdin 管道传入
• 如果 stdin 不是 TTY，则绝不显示提示——应以明确的错误退出或使用默认值
• 密钥绝不能通过标志值传递（会泄漏到 ps 输出和 shell 历史中）。按以下优先顺序选择：OS 密钥链或权限为 0600 的凭据文件（~/.config/mycli/credentials），然后是 stdin（mycli login --with-token < token.txt），最后才是在平台注入时使用环境变量（CI 密钥存储）——环境变量会泄漏到子进程和崩溃报告中，因此绝不能将其作为主要文档路径
• 根据严重程度调整确认方式：轻微 → 使用 y/N 提示，可通过 --yes 跳过；中等 → 显示提示，并建议先使用 --dry-run；严重或不可逆（删除数据库、覆盖生产环境）→ 要求输入资源名称进行确认

约定

• 支持使用 -- 停止解析标志：mycli run -- --flag-for-child-process
• 支持在文件参数中使用 - 表示 stdin/stdout：curl ... | mycli process -
• 同时接受 --flag=value 和 --flag value
• 如果需要从 stdin 读取，但 stdin 是交互式终端，则立即显示帮助信息（不要像 cat 那样一直等待）

---

配置优先级

优先级从高到低：

1. 标志 — 单次调用的覆盖项
2. 环境变量 — MYCLI_* 前缀，按会话生效
3. 项目配置 — .myclirc、mycli.config.ts 或 package.json 中的配置
4. 用户配置 — ~/.config/mycli/（遵循 XDG 规范）
5. 默认值 — 合理的内置值

规则：

• 配置文件位置遵循 XDG Base Directory Specification
• 环境变量命名：使用 MYCLI_* 前缀，由大写字母、数字和下划线组成；值保持单行；不要占用 POSIX 名称
• 在相关场景下尊重通用环境变量：NO_COLOR、FORCE_COLOR、DEBUG、EDITOR、PAGER、HTTP_PROXY/HTTPS_PROXY/NO_PROXY、TMPDIR、TERM、LINES/COLUMNS
• 绝不通过标志接受密钥；优先使用密钥链/凭据文件或 stdin，仅在平台注入时（CI）使用环境变量——参见“提示词与交互”
• 适用时读取 .env，但不要用它替代正规的配置
• 如果要修改属于其他程序的配置，先征求同意

---

错误设计

每条错误都需要包含：

1. 机器可读代码 — UPPER_SNAKE_CASE（例如 CONFIG_MISSING、AUTH_EXPIRED）
2. 出了什么问题 — 上下文：涉及的资源、操作和输入
3. 如何修复 — 用户应执行的确切命令或操作
4. 参考资料 — 文档 URL 或 mycli help <topic>（可选）

人类可读模式

Error: CONFIG_MISSING — Configuration file not found
No configuration file found at ./mycli.config.ts or ~/.config/mycli/config.ts

Fix: Run `mycli init` to create a default configuration file
Docs: https://mycli.dev/docs/configuration

• 将最重要的信息放在最后（读者的视线会被末尾吸引）
• 谨慎且有意地使用红色
• 针对拼写错误建议更正（“你是不是想输入 ‘deploy’？”）
• 将类似错误归到同一个标题下——不要重复列出 50 条看起来相似的行
• 将调试日志写入文件，而不是终端（除非使用 --debug）

JSON 模式

错误也应采用结构化格式——不仅是成功响应：

{
  "ok": false,
  "error": {
    "code": "CONFIG_MISSING",
    "message": "No configuration file found at ./mycli.config.ts",
    "fix": "Run `mycli init` to create a default configuration file",
    "transient": false
  }
}

transient 布尔值表示原因可能会消失。它本身并不意味着可以重试：调用方还需要退出代码 75，或明确的安全重试约定。

状态变更与透明度

• 确认状态变更 — 说明发生了什么变化，并展示（或指出）变更后的状态；传统上不显示任何信息的命令在人看来就像出了问题
• 让当前状态一目了然 — 为任何状态复杂的功能提供类似 status 的命令（git status 模式）
• 明确说明隐藏操作 — 如果读取或写入了未作为参数传入的文件，或与远程服务通信，请说明（人类模式下输出到 stderr）
• 处理有歧义的变更操作 — 如果派发后传输失败，告知用户如何检查或协调状态；不要将结果标记为可安全重试
• 仅当 stdout 是 TTY 时，才通过 $PAGER 分页显示较长的输出；绝不在管道输出时分页；不要通过 shell 执行该值，并说明它是可执行文件标记，还是由经过审核的 shell 词解析器解析

---

健壮性

• 尽早验证输入 — 在产生任何副作用前失败，并给出清晰的提示
• 响应正在进行的人类操作 — 在交互式人类模式下，除非使用 --quiet，否则若操作运行超过约 100ms，应在 stderr 上显示进度；除非协议明确规定进度，否则机器模式应保持安静；交互式进度可能停滞时，应包含时间估算
• 为所有网络操作设置超时 — 超时应可配置；仅在派发前或已确认可安全重试／具备幂等性时使用退出码 75
• 可恢复操作 — 仅在安全时，才允许通过重新运行继续操作；对于结果不明确的变更操作，必须提供明确的状态或协调途径
• 仅崩溃设计 — 失败时快速退出，将清理工作推迟到下次运行；区分可见性原子替换与崩溃持久化，并让有界清理计时器保持引用，避免 Ctrl-C 绕过时间限制 — 参见 resources/stream-contracts.md
• 预料到误用情况 — 脚本封装、连接异常、并发实例，以及从未测试过的环境

---

可组合性模式

针对真实场景中的管道进行设计：使用 jq 过滤、逐行流式处理 NDJSON、从 stdin 读取输入、通过输出的标识符串联命令、使用 --fields 选择列，以及通过 xargs -P 扇出任务。

参见 resources/composability.md，其中提供了涵盖这些模式的完整 shell 示例。

关键模式：

• 创建命令应输出标识符，以便后续命令可以串联
• 列表命令支持使用 --fields 选择列（减少输出量，对提高 Agent 效率至关重要）
• 对只关心退出码的 CI 脚本使用 --quiet
• 使用 NDJSON 流式处理大型数据集，避免将所有内容缓冲到内存中
• 使用 --dry-run 和 --json，以结构化数据输出计划的变更

---

子命令设计

• 名词 + 动词模式最常见：mycli config set、mycli report generate
• 所有子命令应保持一致 — 相同用途应使用相同的标志名称
• 避免含义模糊的命令组合（update 和 upgrade 容易混淆）
• 不要使用包罗万象的子命令（否则永远无法添加名称冲突的子命令）
• 不要随意缩写 — 别名必须明确且稳定
• 不带参数时：列出子命令（多命令 CLI），或显示帮助（单命令 CLI）

帮助

• mycli --help — 顶层帮助
• mycli help <subcommand> — 子命令帮助
• mycli <subcommand> --help — 同上
• 如果运行时缺少必需参数，应显示简明帮助、1-2 个示例，以及“使用 --help 获取更多信息”
• 示例是阅读量最大的部分 — 将其放在最前面
• 列出标志类型、默认值，以及有限集合的允许值
• 在顶层帮助中加入支持／错误报告链接；尽可能在问题 URL 中预填诊断信息
• 对明显的拼写错误建议可能的命令（“您是否想输入 'deploy'？”）— 询问用户，绝不自动执行

---

输出稳定性契约

标准输出是公共 API。 更改标准输出格式属于 CLI 的破坏性更改。

更改	影响
添加新的可选 JSON 字段	安全（增量添加）
添加新的子命令	安全
添加默认值保持不变的新标志	安全
删除或重命名标志	破坏性更改
删除或重命名 JSON 字段	破坏性更改
更改退出码	破坏性更改
更改默认行为	破坏性更改
更改面向用户的输出	通常可以（不属于契约）

如有疑问，选择并行添加，而不要修改。移除之前，先通过标准错误发出弃用警告；等能确认用户已完成迁移后，再停止警告。

---

命名、分发与遥测

• 名称：简短、易记、全小写、易于输入；不要过于通用，以免与现有命令冲突
• 分发：优先采用单个二进制文件；语言生态工具（npm、pip）可以合理地依赖其解释器。让卸载简单易行，并提供相关文档
• 遥测：未经明确同意，绝不收集使用或崩溃数据；应采用主动选择加入的方式，并说明收集哪些数据、收集原因以及保留期限。通常，带监测功能的网页文档或下载量统计就足够了

---

反模式

#	反模式	错误原因
1	在标准输出中混合数据和诊断信息	会破坏所有管道：如果警告输出到标准输出，mycli list | jq . 就会失败
2	在管道输出中使用颜色/ANSI 转义序列	ANSI 转义序列会干扰下游解析。检查 isatty(stdout) + NO_COLOR
3	交互式提示没有标志可跳过	Agent 无法输入“y”。每个提示都需要 --yes/--force。非 TTY 环境中没有跳过选项会导致挂起
4	成功时不输出任何内容	沉默含义不明确——应显示简短确认信息。对于需要保持静默的脚本，提供 -q
5	只为人类或机器设计，而非兼顾两者	检测上下文（TTY 或管道），并自动调整
6	输出未引导下一步操作	每条输出都应指引下一步：成功时给出下一条命令，失败时给出修复命令
7	破坏现有 CLI 契约	标志名称、退出码和输出结构都是契约。应并行添加，绝不修改
8	除 CLI 适配器外，在任何位置使用 console.log	处理程序必须返回数据；只有表示层可以写入流
9	由处理程序直接退出进程	交由入口点决定。处理程序应将错误作为数据返回
10	非零退出时不通过标准错误解释原因	脚本既需要退出码，也需要原因
11	默认输出冗长	单次测试运行就可能生成 419KB。提供 --fields、--quiet、--json

---

验证清单

设计或评审 CLI 后：

• stdout 仅包含数据；其他所有内容都写入 stderr
• 每个命令都支持 --json，成功数据写入 stdout，结构化错误写入 stderr
• 退出码具有明确语义，并在 --help 中说明
• 每个提示都提供 --yes/--force/--flag 绕过选项
• 错误包含：代码、消息、修复建议
• 修改数据的命令提供 --dry-run
• 进度信息和旋转指示器写入 stderr，绝不写入 stdout
• 遵循 NO_COLOR、TERM=dumb 和 --no-color
• 管道输出不包含任何 ANSI 转义码
• 成功输出包含后续操作指引
• 绝不移除或重命名现有标志、退出码和输出字段
• JSON 架构已版本化（添加字段安全，移除字段属于破坏性更改）
• 配置遵循 flags > env > project > user > defaults
• 绝不通过标志传递密钥；优先使用钥匙串/凭据文件/stdin，仅在平台注入时（CI）使用环境变量
• 严重的破坏性操作需要输入指定内容（资源名称）进行确认，而不只是 y/N
• 网络操作具有可配置的超时时间；退出码 75 仅用于分发前失败或可明确安全重试的失败
• 交互式人工操作若运行时间超过约 100ms，除非设置了 --quiet，否则应在 stderr 显示进度；机器模式协议保持干净
• Ctrl-C 快速退出，并进行有时限的清理
• --help 包含 2-3 个切实可用的示例
• 人类可读输出可用 grep 解析（扁平行，不带表格边框）

---

快速参考

流路由、退出码和标准标志已在正文中列表说明——请参阅上文的“The Unix Stream Contract”、“Exit Codes”和“Standard Flags”。

格式层级

Default (TTY)     → colors, tables, formatted text
--plain           → one record per line, stable, grep-friendly
--json            → structured JSON, versioned schema
--format ndjson   → streaming, one JSON object per line

配置优先级

flags > env vars > project config > user config > defaults