SuperAPI AI 工具集

cli-design

编程与开发

查看项目

更新于 11-17 18:18

技能介绍

用途

cli-design 是一个将《命令行界面指南》(clig.dev)转化为实践操作的 AI 技能。它用于在编写 CLI 代码时直接应用设计规范,而不仅仅是在审查时使用。其核心价值在于在问题被察觉之前,就把小默认值做对,例如输出流向、退出码、无 TTY 时的行为等。

主要能力

该技能围绕两个受众展开:终端前的人类用户和管道脚本。它提供以下方面的指导:

  • 以人为先:清晰说明发生了什么、建议下一步、用平实语言重写错误、显示进度、帮助以示例开头。
  • 可组合性:主输出到 stdout,杂项信息到 stderr,有意义的退出码,稳定的 --json/--plain 输出,无 TTY 时不提示、不上色、不播放动画。
  • 一致性:使用用户熟悉的标志名(-h、--force、--dry-run、-o),跨子命令行为一致。
  • 健壮与尊重:尽早验证、设置超时、响应 Ctrl-C、未经同意不回传数据、不泄露机密。

使用方式

构建新 CLI 或添加命令时:

  1. 选择参数解析库,而非手动解析 sys.argv。
  2. 先勾勒接口:命令名、子命令、位置参数与标志、破坏性操作。设计非平凡时向用户展示草图。
  3. 从第一次提交就内置基本规则。
  4. 阅读相关参考文件(帮助文档、输出与错误、参数与标志、子命令健壮性兼容性、配置环境命名分发、语言片段)。
  5. 对构建好的命令运行 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 许可共享。