附录 C：CLI 设计 Checklist

发布前自检清单。逐项核对，打勾的项目表示已完成。

命令设计

• 命名一致性：所有子命令使用同一种风格（kebab-case 或 camelCase，不混用）
• 动词开头：子命令名是动词或动词短语（scan、review、init），不是名词
• help 信息完整：每个命令和选项都有 description，--help 输出可以作为用户文档
• usage 示例：help 信息中包含至少一个使用示例（Examples: 段落）
• 版本号：--version 或 -v 正确输出当前版本
• 无参数行为：直接运行不带参数时显示帮助信息，而不是报错或无输出
• 拼写错误提示：用户输入错误的子命令名时，提示最接近的正确命令
• 选项缩写不冲突：单字母缩写（-f、-v）没有歧义
• 默认值合理：常用选项有合理的默认值，大部分场景不需要手动指定

交互体验

• 非 TTY 降级：当 stdout 不是 TTY 时（管道、重定向），自动禁用颜色、spinner 和交互式提示
• Ctrl+C 处理：响应 SIGINT，清理临时文件和进程，给出友好提示
• SIGTERM 处理：响应 SIGTERM，优雅退出
• 进度反馈：耗时超过 1 秒的操作有进度指示（spinner 或进度条）
• 长时间操作可中断：大型操作（扫描、分析）支持中途取消，不是只能等完成或强杀
• 错误信息可操作：错误提示不只说”出错了”，而是告诉用户下一步该怎么做
• 确认破坏性操作：删除、覆盖等不可逆操作前要求确认（--force 跳过确认）
• 静默模式：--quiet 或 -q 选项，只输出最终结果，不输出过程信息

输出

• stdout / stderr 分离：正常输出走 stdout，错误和日志走 stderr
• NO_COLOR 支持：设置环境变量 NO_COLOR=1 时禁用所有颜色输出
• FORCE_COLOR 支持：设置 FORCE_COLOR=1 时强制启用颜色（即使在管道中）
• JSON 输出：--format json 或 --json 选项，输出机器可读的 JSON
• JSON 输出到 stdout：JSON 模式下，进度信息和日志仍然走 stderr，只有数据走 stdout
• 退出码规范：0 = 成功，1 = 一般错误，2 = 参数错误，130 = 被 SIGINT 中断
• UTF-8 输出：正确处理中文和 emoji，不出现乱码
• 宽字符对齐：表格中的中文和英文正确对齐（中文字符占 2 列）

配置

• XDG 规范：配置文件存放在 $XDG_CONFIG_HOME/appname/（默认 ~/.config/appname/）
• 数据目录：持久数据存放在 $XDG_DATA_HOME/appname/（默认 ~/.local/share/appname/）
• 缓存目录：缓存文件存放在 $XDG_CACHE_HOME/appname/（默认 ~/.cache/appname/）
• 环境变量覆盖：每个配置项都可以通过环境变量覆盖（如 REPOX_MODEL、REPOX_VERBOSE）
• 环境变量前缀：所有环境变量使用统一前缀（如 REPOX_），避免和其他工具冲突
• .env 支持：自动加载项目目录下的 .env 文件（可选，对开发者友好）
• 配置优先级清晰：文档中说明配置的优先级顺序（默认值 < 配置文件 < 环境变量 < 命令行参数）
• 配置文件格式一致：使用一种格式（JSON / YAML / TOML），不要混用
• 配置文件可选：没有配置文件时使用默认值正常运行，不报错

安全

• 不硬编码密钥：API key、token 等通过环境变量或配置文件传入，不出现在代码中
• credentials 文件权限：存储凭证的文件权限设为 0600（仅所有者可读写）
• 创建文件时设权限：fs.writeFile 时明确指定 mode，不依赖 umask
• 不输出密钥：--verbose 和 --debug 模式下不打印完整的 API key（只显示前 4 位 + ***）
• 输入校验：所有用户输入在使用前校验，特别是文件路径（防止路径穿越）和 shell 命令参数（防止注入）
• 子进程参数转义：调用 child_process 时使用 execFile（参数数组）而不是 exec（字符串拼接）
• 依赖审计：npm audit 无 high/critical 级别漏洞
• 不发布敏感文件：.npmignore 或 package.json#files 排除 .env、测试 fixture、本地配置

发布

• 语义化版本号：遵循 semver——patch 修 bug、minor 加功能、major 有 breaking change
• CHANGELOG：每个版本的变更有记录，分类清晰（Added / Changed / Fixed / Removed）
• README 完整：安装方法、基本用法、配置说明、示例
• LICENSE 文件：明确开源协议
• bin 字段正确：package.json 的 bin 指向正确的构建产物
• shebang 正确：产物第一行是 #!/usr/bin/env node
• 可执行权限：产物文件有可执行权限（chmod +x）
• engines 字段：声明最低 Node.js 版本要求
• 不发布 devDependencies：构建产物不包含开发依赖
• 包体积合理：npm pack 后检查发布包大小，排除不必要的文件
• 发布前本地验证：npm pack && npm install -g ./appname-x.x.x.tgz 在本地测试安装

测试

• 单元测试：核心逻辑（参数解析、数据处理、格式化）有单元测试覆盖
• 集成测试：关键命令的端到端测试（spawn 子进程运行 CLI，检查输出和退出码）
• 快照测试：help 信息和格式化输出用快照测试防止意外变更
• CI 配置：push 和 PR 自动运行测试
• 跨平台验证：CI 中至少覆盖 Linux 和 macOS，条件允许加上 Windows
• Node.js 版本矩阵：CI 中测试 engines 字段声明的最低版本和当前 LTS 版本
• 管道模式测试：测试通过管道传入数据和输出数据的场景
• 错误场景测试：测试无效参数、文件不存在、网络错误等异常路径

可访问性

• 不依赖颜色传达信息：除了颜色，还用符号（✓ ✗ ⚠）或文字标记状态
• 屏幕阅读器友好：重要信息不依赖动态效果（spinner 有文本 fallback）
• 宽度适配：在 80 列的窄终端中也能正常显示（不截断关键信息）