rust-cli

Rust CLI 交付

将命令行界面视为稳定的用户协议，而不是把业务逻辑直接写进 main。从确认契约、实现到真实进程验证，完成端到端闭环。

确认约束

进行更改之前，确认需求、现有帮助文本、脚本、README、测试和发布配置：

• 命令名称、子命令、参数、默认值、互斥项和兼容性要求；
• 面向用户的输出格式与机器可读输出（静默模式、详细模式、JSON、无颜色）；
• 标准输入、文件和参数的输入优先级；标准输出和文件的写入目标；
• 对应于成功、用法错误、数据错误和暂时性故障的退出码；
• 支持的平台、Shell、TTY/管道环境、MSRV、依赖版本；
• 配置文件优先级低于环境变量，环境变量优先级低于命令行选项。

如果缺少关键契约，请根据现有行为和测试推断出最小兼容方案，并明确说明假设。不要随意更改标志、输出文本或退出码。

工作流

1. 建立行为基线

检查入口点和构建边界：

rustc --version --verbose
cargo metadata --no-deps --format-version 1
cargo test --all-targets
cargo run -- --help

至少记录一次成功调用的参数、标准输出、标准错误和退出码；另记录至少一次失败调用。现有快照或 Shell 调用方都应视为兼容性约束。

2. 定义命令契约

先编写行为矩阵，再实现解析逻辑。区分：

• 必需位置参数、可选参数、可重复选项和子命令；
• 用户输入错误与运行时错误；
• 正常数据输出与诊断输出；
• 交互模式与非交互模式；
• 稳定的机器可读格式与可演进的用户可读格式。

使用 clap 等解析器时，请参考与仓库锁定版本对应的官方文档。不要凭记忆混用不同主版本的派生属性或 API。

3. 分离解析、执行和呈现

保持入口点精简：

Process parameters & environment
    -> Parse into Options/Command
    -> Call testable run(command, io, context)
    -> Map domain results to output and ExitCode

让领域逻辑返回结构化结果或错误；只在边界处决定颜色代码、换行、标准错误消息和退出码。避免在深层函数中调用 process::exit、不加区分地读取全局环境变量，或无条件打印内容。

4. 按配置优先级实现 I/O

• 使用 BufRead、Write 或显式包装器注入输入/输出适配器，以便测试管道行为；
• 正常结果写入标准输出；诊断消息和进度信息写入标准错误；
• 从标准输出读取管道时，不要混入日志、颜色或进度条；
• 仅在检测到 TTY 后启用交互式提示，并提供覆盖此行为的选项；
• 使用 Path/PathBuf；不要手动拼接特定于平台的路径。

明确优先级：CLI > 环境变量 > 配置文件 > 默认值。适用时，为冲突情况编写测试。写入文件时，请考虑部分写入、原子替换策略、现有文件处理策略和权限敏感性。如需具体的命令矩阵、标准流或配置模式，请阅读 命令契约与 I/O。

5. 设计易于处理的错误

• 针对预期故障，提供简短、结合上下文且可采取行动的错误消息；
• 默认不要向终端用户打印调试堆栈或敏感值；
• 为详细模式和日志记录保留完整错误链；
• 将错误类别映射到稳定的退出码；
• 正确处理管道破裂：下游筛选器提前关闭时，不要产生多余信息。

不要对用户输入、文件、网络操作或配置故障使用 unwrap()/expect()。

6. 使用真实进程验证

确保至少覆盖以下场景：

1. --help 和 --version；
2. 成功执行路径；
3. 未知参数、缺少参数、选项冲突；
4. stdout 和 stderr 流的分离；
5. 精确的退出码；
6. stdin 管道或临时文件行为；
7. 不支持 TTY 时的配置优先级；
8. 涉及空格、非 UTF-8 内容或平台差异的路径风险（如适用）。

优先测试编译后的二进制文件，而非仅测试解析函数。如果需要测试覆盖率和发布制品，请阅读 CLI Testing & Release。通用测试分层交由 rust-testing 处理。

7. 验证分发形式

执行仓库级检查：

cargo fmt --all -- --check
cargo check --all-targets
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
cargo build --release

如果声明了跨平台支持或特定目标支持，请在相应环境或 CI 矩阵中验证。打包、功能、工作区配置、交叉编译和发布详情由 rust-cargo-build 处理。

8. 处理守护进程、IPC 和终端模式

如果 CLI 包含持久守护进程、本地 IPC、PTY、TUI 或类似功能，请勿将所有代码都放在二进制 crate 中。相应地分离解析逻辑、协议 DTO、平台层、客户端、服务端和公共 SDK。根据 Daemon & IPC Terminal Toolkit 为握手版本、能力协商、帧大小、自动启动期间的竞态条件、信号、附加升级、关闭序列，以及按工具/边界进行的选择编写端到端测试。

完成标准

只有满足以下所有条件时，才报告已完成：

• 清晰定义命令契约和兼容性假设；
• 业务逻辑与进程边界分离；
• 已针对 stdout、stderr、退出码和配置优先级编写真实进程测试；
• fmt、check、test 和 Clippy 均通过；
• 有证据表明支持所声明的平台和分发制品；未验证的部分已明确标注。

交接边界

主要关注点	分配给
所有权、路径语义、I/O trait 定义或错误类型	rust-stable
测试分层、覆盖率、模糊测试、基准测试	rust-testing
Cargo 功能、工作区配置、交叉编译、打包、发布	rust-cargo-build
Tokio 任务、取消、信号、异步生命周期	rust-concurrency
HTTP 服务	rust-web

按需资源

• Command Contract & I/O：设计参数、标准流、配置和退出码时阅读。
• CLI Testing & Release：编写真正进程测试或准备发布前阅读。
• Daemon & IPC Terminal Toolkit：构建本地守护进程、控制协议、PTY、TUI 或跨平台终端应用时阅读。
• Example Scenarios：需要端到端任务模板时阅读。
• examples/golden-cli/：使用离线编译验证黄金示例的 stdout、stderr 和退出码。

参考资料

• Rust Command-line apps
• Command Line Applications in Rust
• std::process (https://doc.rust-lang.org/stable/std/process/)
• std::io (https://doc.rust-lang.org/stable/std/io/)
• std::path (https://doc.rust-lang.org/stable/std/path/)