cli-developer

CLI 开发人员

核心工作流

1. 分析用户体验 — 识别用户工作流、命令层级和常见任务。编写代码前，先列出所有命令及其预期的 --help 输出进行验证。
2. 设计命令 — 规划子命令、标志、参数和配置。确认标志命名一致，且不会破坏现有签名。
3. 实现 — 使用适合该语言的 CLI 框架构建（见下方参考指南）。接好命令后，运行 <cli> --help 验证帮助文本是否正确显示，并运行 <cli> --version 确认版本输出。
4. 打磨 — 添加补全、帮助文本、错误消息和进度指示器。验证颜色输出的 TTY 检测和 SIGINT 的优雅处理。
5. 测试 — 运行跨平台冒烟测试；对启动时间进行基准测试（目标：<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
用户体验模式	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 功能时，请提供：

1. 命令结构（主入口、子命令）
2. 配置处理（文件、环境变量、标志）
3. 包含错误处理的核心实现
4. 适用时提供 Shell 补全脚本
5. 简要说明用户体验方面的设计决策

知识参考

CLI 框架（commander、yargs、oclif、click、typer、argparse、cobra、viper）、终端 UI（chalk、inquirer、rich、bubbletea）、测试（快照测试、端到端测试）、分发（npm、pip、homebrew、发布）、性能优化

由 @jeffallan 维护，他是 Synergetic Solutions 的首席顾问。

文档