用途
cli-design 是一套与语言无关的 CLI 设计原则技能，适用于构建任何命令行工具、设计命令树与标志、实现输出层（格式检测与流路由）、测试 CLI 行为（stdout/stderr 分离、退出码），以及审查 CLI 的 Unix 可组合性。它改编自 CC BY-SA 4.0 的 Command Line Interface Guidelines（clig.dev），来源与许可范围记录在 resources/source-notes.md 与 LICENSE 中。
核心原则
stdout 只用于数据——即用户请求的产物；stderr 用于其他一切——诊断、进度、加载动画、警告与错误。这一分离是 mycli --json | jq ... 能正常工作的前提，stdout 上出现一个加载动画字符就会破坏所有下游管道。
主要能力
Unix 流契约
- 主要输出（数据、结果、JSON）写入 stdout，可管道化。
- 进度条、加载动画、状态仅在 stderr 是 TTY 时写入 stderr；被管道化的 stderr 只承载警告与错误。
- 警告、错误、诊断写入 stderr，即使 stdout 被管道化用户仍可见。
- 调试/详细输出写入 stderr。
- 独立检查 stdout 与 stderr；stdout 被管道化不代表 stderr 也被管道化。
- 在 Node.js 中，同步/异步进程流行为因操作系统与目标而异；高容量输出需尊重
.write()背压。
保持处理函数纯净
执行工作的函数应返回数据，而不是写入 stdout。CLI 入口点负责所有 I/O：解析参数、检测格式、调用处理函数、格式化结果、写入正确流、设置退出码。入口点文件是唯一写入流或结束进程的文件。好处包括：无需子进程即可测试、格式灵活、可复用（CLI、MCP 服务器、HTTP API 或程序化导入）。
格式标志契约
三层输出层级：
- 默认：人类可读，含颜色、表格、格式化文本，进度条与加载动画在 stderr，可能随版本变化，不是契约。
--plain：适合 grep/awk，每行一条记录，无格式无颜色，次要版本间稳定，是契约。--json：结构化数据。成功时 stdout 仅含有效 JSON；任何非零退出时 stdout 保持为空，最后一条非空 stderr 行是结构化 JSON 错误信封。JSON 模式隐含非交互。
成功信封：{ "ok": true, "data": { ... } }；失败信封：{ "ok": false, "error": { "code": "CONFIG_MISSING", "message": "...", "fix": "..." } }。
流式大数据使用 NDJSON（每条记录一个 JSON 文本，以 \n 结尾），每行可独立解析。
退出码
- 0：成功
- 1：领域失败（如质量阈值未满足）
- 2：无效用法（错误标志、缺少必需参数、验证错误）
- 78：配置错误
- 75：临时、可安全重试的失败（仅在未派发变更或已确立重试安全时使用）
- 130：SIGINT（128 + 2）
- 143：SIGTERM 风格状态（可选，128 + 15）
规则：非零退出码必须有 stderr 解释；在 --help 中记录退出码；应用错误不使用高于 125 的码；调用者未传的标志不算无效用法。
TTY 检测
按优先级顺序（首个匹配生效）：--format json/--json 标志、--no-color 标志、FORCE_COLOR 环境变量、NO_COLOR/NODE_DISABLE_COLORS、TERM=dumb、CI=true、stdout 非 TTY、默认完整交互。在入口点一次性解析输出模式。独立检查 stdout 与 stderr；提示需独立以 stdin 为门控。
输入设计
- 优先使用标志而非位置参数；1 个位置参数可接受，2 个可疑，3 个以上优先命名标志（同类型可变参数与通用惯用法除外）。
- 标准标志：
-h/--help、--version、-q/--quiet、-v/--verbose、-d/--debug、-f/--force、-n/--dry-run、--json、--plain、--no-color、--no-input、-o/--output、--fields。 - 所有提示必须可通过标志绕过；stdin 非 TTY 时绝不提示；密钥绝不通过标志值传递，优先 OS 钥匙串或 0600 凭据文件，其次 stdin，再次仅平台注入的环境变量。
- 支持
--停止标志解析、-表示 stdin/stdout、--flag=value与--flag value。
配置优先级
从高到低：标志、环境变量（MYCLI_* 前缀）、项目配置、用户配置（遵循 XDG 规范）、默认值。
使用方式
该技能以文档形式提供设计原则，TypeScript 实现模式位于 resources/ 目录，按需加载：output-architecture.md（Result 类型、入口点接线、格式化器、日志器、JSON 信封模式）、testing-cli.md（Vitest 测试 CLI 行为）、stream-contracts.md（Node.js 缓冲、NDJSON、信号处理、崩溃设计）、composability.md（管道行为设计与测试，含 jq 过滤、NDJSON 流、stdin、链式、--fields、并行 xargs 示例）。
适用场景
构建任何语言的命令行工具、设计命令树与 I/O 契约、实现输出层、测试 CLI 行为、审查 Unix 可组合性。
限制
本技能聚焦 CLI 设计原则；API 契约稳定性参见 api-design 技能，配置、环境变量与优雅关闭参见 twelve-factor 技能。TypeScript 实现模式为可选资源。具体安装命令、收费与价格信息暂未提供。