SuperAPI AI 工具集

cli-design

编程与开发

查看项目

更新于 10-26 16:19

技能介绍

用途

cli-design 是一个用于构建命令行界面(CLI)的技能。当用户想要构建新的 CLI 工具、为现有工具添加子命令、解析参数/标志/选项/位置参数、询问帮助文本格式、添加交互式提示、管理配置文件、分发 CLI、添加 shell 补全或正确处理 stdin/stdout 管道与退出码时,可触发该技能。它不适用于 GUI 应用设计或 Web UI(应使用 frontend 或 absolute-ui 技能),也不适用于与构建可分发的 CLI 工具无关的 shell 脚本语法问题。

主要能力

技能围绕以下核心原则展开:

  • 可预测性优于取巧:遵循 POSIX 约定,单横线短标志(-v)、双横线长标志(--verbose)、-- 结束标志解析,用户无需猜测标志行为。
  • 默认自文档化:每个命令必须有 --help,展示用法、所有标志及描述,并至少包含一个示例。
  • 大声失败、优雅恢复:错误打印到 stderr 而非 stdout,失败使用非零退出码,错误信息包含失败输入和建议修复方式,绝不静默失败。
  • 可组合性:尊重 Unix 哲学,接受 stdin、产生干净的 stdout、使用 stderr 做诊断,支持 --json 或 --output=json 以便其他工具管道处理。
  • 渐进式披露:先展示最简单用法,将高级标志隐藏在 --help 子组或单独的 help <topic> 命令后。

技能涵盖的核心概念包括:参数分类(子命令、位置参数、布尔标志、带值选项)、配置层级(内置默认值、系统配置、用户配置、项目配置、环境变量、CLI 标志,后者覆盖前者)、退出码(0 成功、1 一般错误、2 命令误用、126 不可执行、127 未找到、128+N 被信号终止)。

使用方式

技能提供多个常见任务的代码示例:

  1. Node.js 参数解析(Commander.js):以声明式定义命令,由 Commander 处理帮助生成。
  2. Python 参数解析(click):使用装饰器定义命令,自动处理类型转换、帮助生成和 shell 补全。
  3. 添加交互式提示:使用 @inquirer/prompts 的 confirm、select、input,用于破坏性操作或首次设置;始终允许 --yes / -y 跳过提示;在显示提示前检查 process.stdout.isTTY。
  4. 管理配置文件:使用 cosmiconfig(Node.js)支持多种配置格式,按默认值 < 文件配置 < 环境变量 < 标志的顺序合并。
  5. 编写有效帮助文本:遵循模板,先显示 Usage:,包含 <required> 和 [optional] 参数、一行描述、逻辑分组的选项、最后是 --help 和 --version,底部包含 2-3 个真实示例。
  6. 处理 stdin/stdout 管道:无文件参数时支持 stdin,使工具可组合。
  7. 分发 CLI:Node.js 通过 npm 的 bin 字段和 shebang;Python 通过 pyproject.toml 入口点;Go 通过 go install 和交叉编译;Rust 通过 cargo install 和 cross。
  8. 添加 shell 补全:Click 内置补全支持,Clap 通过 clap_complete 生成。

适用场景

适用于需要构建或改进命令行工具的开发场景,包括参数解析、帮助文本、交互提示、配置文件管理、CLI 分发和 shell 补全等。

限制

技能明确列出反模式和注意事项,例如:错误打印到 stdout 会破坏管道;失败时退出码 0 会破坏 && 链和 CI 管道;强制交互会破坏 CI、cron 和脚本;子命令缺少 --help 导致用户无法发现选项;标志命名不一致(--dry-run vs --dryRun vs --dry_run);帮助文本过于庞大;非标准标志语法;静默吞掉错误;缺少 --version 标志。注意事项包括:CI/脚本中的交互提示可能无限挂起;部分失败仍退出 0;跨子命令标志命名不一致;Node.js shebang 缺失或错误;吞掉解析器错误。技能还引用 references/argument-parsing-patterns.md 和 references/config-file-patterns.md 两个文件,仅在任务需要时加载。首次激活时会检查伴随技能安装情况,并可通过 npx skills add AbsolutelySkilled/AbsolutelySkilled --skill <name> 安装缺失的伴随技能。