
使用方式
关于
构建 CLI 工具、实现参数解析或添加交互式提示时使用。用于解析标志和子命令、显示进度条和加载动画、生成 bash/zsh/fish 补全脚本、CLI 设计、Shell 补全和跨平台终端应用。
CLI 开发者
核心工作流
- 分析用户体验 — 识别用户工作流、命令层次结构、常见任务。在编写代码之前,通过列出所有命令及其预期的
--help输出进行验证。 - 设计命令 — 规划子命令、标志、参数、配置。确认标志命名一致且不破坏现有签名。
- 实现 — 使用适合该语言的 CLI 框架构建(参见下方参考指南)。连接命令后,运行
<cli> --help验证帮助文本正确渲染,运行<cli> --version确认版本输出。 - 打磨 — 添加补全、帮助文本、错误消息、进度指示器。验证 TTY 检测的颜色输出和优雅的 SIGINT 处理。
- 测试 — 运行跨平台冒烟测试;基准测试启动时间(目标:<50ms)。
参考指南
根据上下文加载详细指导:
| 主题 | 参考文档 | 加载时机 |
|------|----------|----------|
| 设计模式 | references/design-patterns.md | 子命令、标志、配置、架构 |
| Node.js CLI | references/node-cli.md | commander、yargs、inquirer、chalk |
| Python CLI | references/python-cli.md | click、typer、argparse、rich |
| Go CLI | references/go-cli.md | cobra、viper、bubbletea |
| UX 模式 | references/ux-patterns.md | 进度条、颜色、帮助文本 |
快速入门示例
Node.js (commander)
#!/usr/bin/env node
// npm install commander
const { program } = require('commander');
program
.name('mytool')
.description('Example CLI')
.version('1.0.0');
program
.command('greet <name>')
.description('Greet a user')
.option('-l, --loud', 'uppercase the greeting')
.action((name, opts) => {
const msg = \`Hello, \${name}!\`;
console.log(opts.loud ? msg.toUpperCase() : msg);
});
program.parse();
Python(click/typer)和 Go(cobra)的快速入门示例,请参见 references/python-cli.md 和 references/go-cli.md。
约束条件
必须做
- 保持启动时间在 50ms 以内
- 提供清晰、可操作的错误消息
- 支持
--help和--version标志 - 使用一致的标志命名约定
- 优雅处理 SIGINT(Ctrl+C)
- 尽早验证用户输入
- 支持交互式和非交互式模式
- 在 Windows、macOS 和 Linux 上测试
禁止做
- 不必要地阻塞同步 I/O — 改用异步读取或流处理。
- 当输出将被管道传输时打印到 stdout — 将日志/诊断信息写入 stderr。
- 当输出不是 TTY 时使用颜色 — 应用颜色前先检测:
// Node.js const useColor = process.stdout.isTTY;# Python import sys use_color = sys.stdout.isatty()// Go import "golang.org/x/term" useColor := term.IsTerminal(int(os.Stdout.Fd())) - 破坏现有命令签名 — 将标志/子命令重命名视为破坏性变更。
- 在 CI/CD 环境中要求交互式输入 — 始终通过标志或环境变量提供非交互式回退。
- 硬编码路径或平台特定逻辑 — 改用
os.homedir()/os.UserHomeDir()/Path.home()。 - 不提供 shell 补全就发布 — 上述三个框架都有内置的补全生成功能。
输出模板
实现 CLI 功能时,提供:
- 命令结构(主入口点、子命令)
- 配置处理(文件、环境变量、标志)
- 带错误处理的核心实现
- Shell 补全脚本(如适用)
- UX 决策的简要说明
知识参考
CLI 框架(commander、yargs、oclif、click、typer、argparse、cobra、viper)、终端 UI(chalk、inquirer、rich、bubbletea)、测试(快照测试、E2E)、分发(npm、pip、homebrew、releases)、性能优化
兼容工具
Claude CodeCursor
标签
前端开发
