构建跨平台 CLI 工具时：设计命令、参数解析、交互提示与…

需要开发或完善命令行工具（含子命令、参数、进度条、补全、跨平台终端应用）时使用。

适用场景

解决思路

1. 分析 UX：识别用户工作流、命令层级和常见任务；在写代码前列出所有命令及其预期的 `--help` 输出以验证。
2. 设计命令：规划子命令、标志、参数和配置；确认标志命名一致且不破坏现有签名。
3. 实现：根据语言选择适当的 CLI 框架（见参考指南）；连接命令后运行 `<cli> --help` 验证帮助文本渲染正确，运行 `<cli> --version` 确认版本输出。
4. 打磨：添加补全、帮助文本、错误消息和进度指示器；验证颜色输出的 TTY 检测和优雅的 SIGINT 处理。
5. 测试：运行跨平台冒烟测试；对启动时间进行基准测试（目标：<50ms）。
6. 根据上下文加载参考指南：设计模式（子命令、标志、配置、架构）、Node.js CLIs（commander、yargs、inquirer、chalk）、Python CLIs（click、typer、argparse、rich）、Go CLIs（cobra、viper、bubbletea）、UX 模式（进度条、颜色、帮助文本）。
7. 快速示例：Node.js 使用 commander 创建 CLI：设置 `.name()`、`.description()`、`.version()`；用 `.command('greet <name>')` 定义子命令，用 `.option('-l, --loud')` 定义选项，在 `.action()` 中处理逻辑；Python 和 Go 示例参考 `references/python-cli.md` 和 `references/go-cli.md`。
8. 保持启动时间低于 50ms。
9. 提供清晰、可操作的错误消息。
10. 支持 `--help` 和 `--version` 标志。
11. 使用一致的标志命名约定。
12. 优雅地处理 SIGINT（Ctrl+C）。
13. 尽早验证用户输入。
14. 同时支持交互式和非交互式模式。
15. 在 Windows、macOS 和 Linux 上测试。
16. 不要不必要地阻塞同步 I/O——使用异步读取或流处理。
17. 当输出会被管道传递时不要打印到 stdout——将日志/诊断信息写入 stderr。
18. 当输出不是 TTY 时不要使用颜色——在应用颜色前检测：Node.js 用 `process.stdout.isTTY`，Python 用 `sys.stdout.isatty()`，Go 用 `term.IsTerminal(int(os.Stdout.Fd()))`。
19. 不要破坏现有命令签名——将标志/子命令重命名视为破坏性变更。
20. 不要在 CI/CD 环境中要求交互式输入——始终通过标志或环境变量提供非交互式回退。
21. 不要硬编码路径或平台特定逻辑——使用 `os.homedir()` / `os.UserHomeDir()` / `Path.home()` 代替。
22. 不要在没有 shell 补全的情况下发布——上述三个框架都有内置的补全生成。
23. 实现 CLI 功能时提供：命令结构（主入口点、子命令）。
24. 提供配置处理（文件、环境变量、标志）。
25. 提供带错误处理的核心实现。
26. 如适用，提供 shell 补全脚本。
27. 简要解释 UX 决策。
28. 了解 CLI 框架（commander、yargs、oclif、click、typer、argparse、cobra、viper）、终端 UI（chalk、inquirer、rich、bubbletea）、测试（快照测试、E2E）、分发（npm、pip、homebrew、releases）和性能优化。

适用边界 · 注意事项

• 项目不是 CLI 工具，不需要参数解析、交互提示或跨平台终端应用时。
• 仅需一次性简单脚本，无需子命令、标志或配置管理时。
• 无法或不需要处理终端 TTY、SIGINT、跨平台兼容性时。