系统级工具链开发与 Cargo 工作区管理接口怎么定才不返工命令行接口先固定输入、输出和退出码。解析失败返回 2文件不存在返回 3脚本调用者不用依赖中文错误文案。tool check missing.md; echo $?库 crate 只暴露稳定的数据结构CLI 的参数解析不透到内部。先用 shell 脚本模拟两个调用者再改接口能较早发现参数名是否别扭。示例路径使用相对路径避免带出开发机目录。把命令的契约写成能被脚本验证的内容工具链最容易返工的地方往往不是实现细节而是调用方已经依赖了一个没有说清楚的行为。除了输入参数和退出码还应固定标准输出、标准错误的职责机器要读取的数据放到标准输出诊断信息放到标准错误。这样 shell 管道、CI 和人工终端可以各取所需调用者也不必从一段中文提示里猜状态。参数缺失、格式错误、找不到文件、业务检查未通过这几类情况最好在文档和测试中分开。这里的退出码不一定要追求复杂的体系但同一类错误不能今天返回一个码、明天换成另一个。若旧版本已经有人使用还要明确新参数是替代旧参数还是同时接受悄悄改变默认值比显式报错更容易造成隐蔽的构建问题。工作区边界要比目录结构更清楚Cargo workspace 方便共享依赖和构建配置却不意味着所有 crate 都能随意互相引用。评审时先看 crate 的职责核心库负责领域数据、校验和可复用流程适配层处理文件、网络或系统差异CLI 只负责解析参数、组合依赖和把结果打印出来。参数解析库的类型一旦进入核心库测试和其他调用方式都会被 CLI 的约束绑住之后想提供 API 或另一个前端就会很别扭。对外暴露的数据结构也要克制。不要因为内部暂时需要几个字段就把整个配置对象设成 public。外部需要创建的对象可以提供构造函数或明确的 builder外部只需要读取的内容提供只读方法。这样内部字段调整时破坏面会小得多。错误类型同理库可以给出可匹配的错误类别和必要上下文展示给终端用户的措辞留在 CLI 层处理。路径、环境与配置不要混成一团系统级工具常在本地、CI、容器里运行。当前工作目录、配置文件位置和缓存目录若靠隐式规则决定调用者很难复现问题。接口应明确哪些路径来自参数哪些可以从环境变量读取优先级是什么默认路径可用但需要能被覆盖。示例使用相对路径是一个好习惯测试还应在临时目录中运行避免不小心读取开发机上的真实文件。配置加载失败时不要退回一个看似可用的空配置继续执行。对于缺失的可选配置可以给出默认行为对于格式错误或权限错误应明确失败并报告文件位置。这样用户知道该修哪里自动化脚本也不会拿着半对半错的结果继续走下去。先用调用者视角审查变更改接口前准备两三个短小的 shell 用例比在脑中推演有效。一个只传必填参数一个带可选参数和管道输入一个故意失败并检查退出码与错误流。再补一个从 workspace 外部引用库 crate 的编译用例能很快发现不小心暴露了内部模块、漏导出类型或把路径假设写死的问题。这里的目标不是为每条命令堆很多快照而是让接口变动有可执行的证据。输出确实要改变时同时更新脚本和说明如果只改了文案不要让自动化依赖文案本身。工具的接口稳定后面的实现重构才有空间。