设计人机双友好的命令行界面规范

系统化的 CLI 设计规范，覆盖参数设计、输出格式、错误处理、安全行为与配置优先级，适用于人机双友好的命令行工具开发。

基本信息

• 技能名称?Create Cli
• 中文名称?设计人机双友好的命令行界面规范
• 作者?steipete
• 分类?专业技能
• 版本?1.0.0
• 标签?cli, ux-design, developer-experience, interface-design, posix, scripting, specification

使用方法

使用说明
核心定位
create-cli 是一项面向 CLI 设计的 前置规范技能 ，聚焦于命令行界面的「表面区域」设计——即用户实际接触的语法、行为与交互契约，而非底层实现。其核心目标是让人类用户感到直观、让脚本调用可预测。
显著优点

1. 权威来源背书
   默认引用 clig.dev 作为上游规范，该文档由业界实践者维护，代表了现代 CLI 设计的共识标准。内置的 cli-guidelines.md 参考文件降低了认知启动成本。
2. 完整的交付物框架
   从命令树、参数表、退出码映射，到配置优先级（flags > env > 项目配置 > 用户配置 > 系统配置）、shell 补全策略，形成可直接落地的规格文档，避免设计与实现脱节。
3. 安全与鲁棒性内置
   破坏性操作强制交互确认，非交互场景需显式 --force 或 --confirm
   敏感信息禁止通过 flags 传递（防范 ps 泄漏）
   默认支持 --dry-run 、 --no-input 、 NO_COLOR 等生产环境刚需
   Ctrl-C 处理建议「快速退出 + 有界清理 + crash-only」
4. 人机双模式友好
   TTY 检测决定交互行为； --json / --plain 区分机器/人类输出；stdout/stderr 职责分离明确。
   潜在局限
   实现层留白
   文档明确声明「语言无关」，不绑定具体解析库（如 Python 的 argparse/Click、Rust 的 clap）。这对于需要即插即用代码片段的用户可能不够直接，需自行桥接规范到实现。
   场景覆盖偏向通用工具
   对特定领域 CLI（如 kubectl 式的资源操作、交互式 TUI 工具）的专项模式提及较少，深度定制需额外推导。
   适合人群
   正在从 0 设计 CLI 的开发者（避免后期大规模重构接口）
   需要统一团队/组织内多 CLI 工具风格的架构师
   开源项目维护者（追求与 Unix 哲学、现代生态的一致性）
   安全审计人员（检查 CLI 设计中的敏感信息处理、破坏性操作防护）
   常规风险
   | 风险点 | 说明 | |--------|------| | 规范被架空 | 若团队未建立「设计 → 代码审查」闭环，交付物可能沦为文档装饰 | | 过度设计 | 对简单脚本强行套用完整规范（如复杂的配置层级、shell 补全）增加维护负担 | | 跨平台假设 | 默认提及 macOS/Linux/Windows，但对 Windows 特有的路径处理、权限模型细节指引有限 | | 退出码冲突 | 自定义退出码（如 3-125）需与 shell 保留值、CI 系统预期协调，文档仅给框架未给映射建议 |