用途
cli-design 是一个将《命令行界面指南》(clig.dev)转化为实践操作的 AI 技能。它用于在编写 CLI 代码时直接应用设计规范,而不仅仅是在审查时使用。其核心价值在于在问题被察觉之前,就把小默认值做对,例如输出流向、退出码、无 TTY 时的行为等。
主要能力
该技能围绕两个受众展开:终端前的人类用户和管道脚本。它提供以下方面的指导:
- 以人为先:清晰说明发生了什么、建议下一步、用平实语言重写错误、显示进度、帮助以示例开头。
- 可组合性:主输出到 stdout,杂项信息到 stderr,有意义的退出码,稳定的 --json/--plain 输出,无 TTY 时不提示、不上色、不播放动画。
- 一致性:使用用户熟悉的标志名(-h、--force、--dry-run、-o),跨子命令行为一致。
- 健壮与尊重:尽早验证、设置超时、响应 Ctrl-C、未经同意不回传数据、不泄露机密。
使用方式
构建新 CLI 或添加命令时:
- 选择参数解析库,而非手动解析 sys.argv。
- 先勾勒接口:命令名、子命令、位置参数与标志、破坏性操作。设计非平凡时向用户展示草图。
- 从第一次提交就内置基本规则。
- 阅读相关参考文件(帮助文档、输出与错误、参数与标志、子命令健壮性兼容性、配置环境命名分发、语言片段)。
- 对构建好的命令运行
python3 scripts/audit_cli.py -- mycmd并修复标记的问题。
审查或修复现有 CLI 时:走查审查清单,运行 audit_cli.py,按影响排序报告发现(先脚本破坏和数据丢失,后润色),引用具体代码并提出具体差异。
适用场景
- 开发新的命令行工具。
- 为现有 CLI 添加子命令或功能。
- 审查或修复现有 CLI 的设计与实现。
- 在 CI 中集成机械性检查(audit_cli.py 在检查失败时以非零退出)。
限制
- audit_cli.py 仅覆盖可从外部检查的规则(帮助、版本、未知标志处理、退出码、stdout/stderr 分离、管道中无 ANSI 转义、伪 TTY 下 NO_COLOR、缺少输入不挂起),仍需人工阅读代码完成审查清单。
- 指南是默认值而非法律,若某规则不适用于特定程序,可有意打破并说明原因。
- 该技能文本基于 CC BY-SA 4.0 许可共享。