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('示例CLI')
  .version('1.0.0');

program
  .command('greet <name>')
  .description('向用户打招呼')
  .option('-l, --loud', '将问候语转为大写')
  .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, 发布），性能优化

文档