工作区管理：从一个可编译的工具链开始整理

工作区管理：从一个可编译的工具链开始整理

工作区起步只放两个 crate：core 放纯解析逻辑，cli 负责参数和输出。这样解析函数能脱离终端单测，命令层也不必知道内部结构。

[workspace]
members = ["crates/core", "crates/cli"]
resolver = "2"

我用 cargo test --workspace 验证整个工作区，再用一份公开的示例文件跑 CLI。配置文件里不写本机绝对路径，也不提交 .env。最小方案的限制很明确：还没有插件机制和并行执行，先把错误出口和退出码稳定下来。

先固定 crate 之间的方向

cli 可以依赖 core，反过来不行。纯解析逻辑不读取环境变量、不打印终端信息，测试才能稳定地给它不同输入。命令层只负责参数解析、文件读取和退出码映射。遇到错误时先保留错误类别，再决定面向用户的文案，不把底层路径或内容直接回显。

新能力放在验证之后

准备加插件或并行前，先给现有命令补上无文件、无权限和格式错误的用例。工作区越早把边界固定住，后面拆 crate 越少依赖偶然的目录结构。公开示例文件也应跟测试一起维护，避免文档能跑、CI 却覆盖不到。

公共类型不该服务终端格式

core 输出的是标题、层级和位置，不应为了 CLI 的彩色输出提前拼字符串。否则以后接编辑器或 HTTP 接口，调用者还得先拆终端转义符。错误也一样：核心层返回读取失败或语法不完整等类别，命令层再决定用户可见文案和退出码。两个 crate 已经够验证方向，没必要一开始拆出很多层。

若 cli 频繁需要访问 core 的私有细节，先判断是否少了清晰的公开函数，不要立刻把字段全部设成 public。core 不依赖参数库，cli 不复制解析规则，这条方向一旦被临时需求打穿，后面很难收回。

手动试跑和 CI 用同一批夹具

公开样例文件应短小，却要包含正常标题、空段落、代码围栏和格式错误。手动跑 CLI 用它，测试也用它，README 与 CI 才不会各自验证不同输入。生成物留在 target，临时文件放进测试夹具或系统临时目录，别让命令在仓库根目录随手创建文件。并行测试时不互相覆盖，清理规则也更简单。

退出码是 CLI 的公开契约

交互使用时，一句错误提示可能够用；脚本调用时，退出码才是可靠信号。参数不合法、目标文件不可读、内容无法解析和内部异常应有稳定分类。CLI 层把 core 的错误映射到这些类别，测试同时断言标准错误与退出状态。这样外层脚本无需从中文文案里匹配关键词，也不会因为改了一句提示就误判任务成功。

工作区新增 crate 前，我会先问现有 core 是否已经承担了清晰职责。只有当某块功能有独立依赖方向、测试方式或发布节奏时才拆出来。为一段二十行辅助函数建立新 crate，会带来版本、可见性和构建配置的额外负担，反而模糊最初想得到的结构。

工作区根部的配置也保持少量明确项：成员列表、resolver 和统一的 lint 规则。包级别的描述、二进制入口和测试依赖留在各自 crate 中。配置放错层级时，新成员往往不知道该改哪里；按职责摆放比集中成一个巨型清单更容易维护。

新同事克隆仓库后，应能按 README 的一条命令完成构建和测试。若必须先创建本地目录、设置隐藏环境变量或手动下载样例，说明工作区起步条件没有写清。把这些前置条件显式列出，能减少“我这里能跑”的沟通成本。