SuperAPI AI 工具集

cli-design

编程与开发

查看项目

更新于 10-16 00:03

技能介绍

CLI 设计技能:构建直观、可组合、自解释的命令行工具。触发场景:新建 CLI 或添加子命令、解析参数与选项、帮助文本与用法字符串格式、交互式提示与确认菜单、配置文件管理(dotfiles、rc 文件、XDG 目录)、通过 npm/pip/cargo/brew 或独立二进制分发、shell 补全、stdin/stdout 管道与退出码。不适用于 GUI/Web UI 或与可分发 CLI 无关的 shell 脚本语法问题。

核心原则:可预测性(遵循 POSIX:-v、--verbose、-- 结束解析);默认自解释(每个命令有 --help,含用法、全部标志说明和至少一个示例);失败要显式(错误写入 stderr,失败用非零退出码,附失败输入与修复建议);可组合(接收 stdin、输出干净 stdout、诊断走 stderr,支持 --json);渐进披露(先展示最简用法,高级标志放入扩展帮助)。

要点:参数分四类——子命令、位置参数、布尔标志、带值选项;短标志可合并(-abc 等于 -a -b -c),选项可用 --out=file 或 --out file。配置优先级:内置默认值 < 系统配置 < 用户配置 < 项目配置 < 环境变量 < CLI 标志。退出码:0 成功、1 一般错误、2 用法错误、126 不可执行、127 命令未找到、128+N 被信号 N 终止。

常见任务提供示例:Node.js 用 Commander.js 声明式定义命令;Python 用 click 装饰器;交互提示用 @inquirer/prompts,且在提示前检查 process.stdout.isTTY,并为脚本提供 --yes/-y;配置用 cosmiconfig 支持多格式;帮助文本模板(Usage 在前、单行描述、选项分组、--help 与 --version 置后、底部 2-3 个真实示例);无文件参数时支持 stdin 管道;分发布局各生态(package.json 的 bin 与 shebang、pyproject.toml 的 [project.scripts]、go install、cargo install);shell 补全(Click 内置、Rust 用 clap_complete)。

反模式与易错点:错误打到 stdout 会污染管道;失败仍返回 0 破坏 && 链与 CI;强制交互会挂起 CI;子命令缺 --help;标志命名不一致(应用 kebab-case);帮助文本过于庞大;非 POSIX 标志语法;静默吞错;缺 --version。Gotcha:CI 中交互提示会无限阻塞,需 isTTY 检查与 -y;部分失败须非零退出;Node 缺 shebang 或错误;解析器错误被吞掉。

参考文件(按需加载):references/argument-parsing-patterns.md 与 references/config-file-patterns.md。首次激活时会检查并建议安装配套技能(npx skills add AbsolutelySkilled/AbsolutelySkilled --skill <name>)。