修改 Rust 库与 CLI 工作区，并与参考工具对比结果

## 把更改放进负责的 crate，让底层 API 保持轻量 将该仓库视为同时服务于库用户和命令行用户的多 crate 工作区。编辑前先阅读工作区清单，了解最低支持的 Rust 版本、feature 图、各 crate 的职责以及公开入口点。 将底层机制 API（plumbing）与高层便捷 API（porcelain）分开： - 底层机制 API 应优先使用引用，明确公开可变的工作状态，并避免仅为方便而进行 clone； - 高层便捷 API 可以为易用性牺牲一定的分配或所有权成本； - 轻量级平台对象通常应借用仓库； - 如果生命周期会过度支配 API，开销较大的缓存可以拥有或 clone 仓库状态。 对于可以设置默认值的分支行为，使用 `Options`。对于执行操作所必需、因而无法安全设置默认值的数据，使用 `Context`。 将更改放在拥有相关数据结构或操作的 crate 中。将共享的命令行行为保留在共享 CLI 层，不要在多个二进制程序中重复实现。 更改公开接口之前，同时考虑直接调用库的用户和命令行行为。 ## 先写失败的测试，再与参考工具对比 更改行为时，先编写一个会因预期原因而失败的回归测试。让测试专注于可观察行为；常规的类型和所有权错误交由 Rust 编译器检查。 实现已确立的协议或文件格式时，在可行的情况下将主流参考实现作为判定标准。对两个实现运行等价用例，并调查任何语义差异，而不要直接假定二者兼容。 编辑前运行现有测试，以免将原有失败归因于本次更改。使用： - 单元测试验证局部算法和数据转换； - 集成测试验证 crate 边界； - journey 测试验证端到端命令行行为； - 真实仓库或贴近实际的数据集验证对兼容性敏感的路径。 每条断言消息都应说明正在检查的不变量，而不应只表示断言失败。 添加清晰的 fixture 文档，说明受测行为以及哪些细节不可或缺。如果 fixture 系统支持文档字符串，则优先使用文档字符串。 ## 不用 unwrap()，让错误说明在哪里、因何失败 绝不要在生产代码中使用 `unwrap()`。测试中也应避免；优先使用 `?`，只有在能简要说明该条件为何必定成立时才使用 `expect()`。 保留完整的错误链，使用户能够了解何处发生了什么失败。命令行二进制程序可以使用灵活的顶层错误类型，但底层 crate 应遵循工作区的结构化错误约定。 添加错误之前，先检查该 crate 的清单和附近代码： - 如果该 crate 已使用较新的上下文携带型错误框架，则延续该模式； - 如果仍使用旧式的 derive 错误枚举，则除非迁移被明确纳入范围，否则应在该 crate 内保持一致。 使用上下文携带型模式时： - 通过项目辅助函数创建静态消息或格式化消息； - 传播被调用方错误时添加上下文； - 不存在被调用方错误时抛出独立消息； - 仅在回调边界要求时擦除类型化错误； - 仅在互操作边界将项目异常包装器转换为标准错误。 如果项目异常包装器有意不实现标准错误 trait，就不要强行将其传入通用错误 API。请使用项目提供的边界方法进行转换。返回装箱标准错误的测试必须先映射该包装器，之后才能使用 `?`。 使用已有的错误扩展 trait 和 import，不要手动重建错误链。 ## 避免多余的 clone，并把仓库路径当作字节处理 底层 crate 应优先使用引用，以避免开销较大的 clone。除非明确需要拥有值且 API 无法接受仍与仓库关联的形式，否则不要分离由仓库支持的句柄。 使用工作区的并发抽象实现内部可变性。未检查 feature 兼容性和平台行为前，不要换用无关的同步原语。 将版本控制路径视为面向字节的数据，包括原生路径 API 使用其他编码的平台。只能通过项目的路径实用工具或专用边界类型，将仓库路径转换为操作系统路径。 不要假定有效的仓库路径就是有效的 Unicode。解析、比较、存储和协议代码中应避免有损转换。 添加所有权、缓存或分配之前，先测量热点路径。便利性应位于高层；底层原语应保留控制能力和可预测的成本。 ## 测试所有 feature 组合，而不只是默认构建 使用仓库任务运行器执行综合测试命令、工作区配置检查、lint、journey 测试和文档构建。只有在刻意确认仅运行单元测试已经足够时，才直接使用 `cargo test`。 验证受支持的发布变体，包括默认构建以及所有精简或最小依赖集合。如果更改仅在默认 feature 下工作，则该更改尚未完成。 运行工作区文档中规定的 feature 组合，包括存在的 small、lean、maximal 和 pure 变体。检查可选依赖项和平台抽象能否在每个受影响的组合中编译。 在生成的 fixture 内容会因平台而异的平台上，使用仓库的归档稳定机制。当逐字节稳定性很重要时，优先使用打包的 fixture 归档，而不是在本地平台生成。 如果仓库为 macOS 或 Windows 上的归档测试定义了平台专用环境标志，请严格按照文档应用。不要在其他平台上悄悄跳过受影响的测试。 对于用户可见的 CLI 更改，运行端到端命令测试，并在可行时与参考实现比较。 ## 写能用于 changelog 的提交，并标出破坏性变更 使用目的明确的 conventional commit： - 仅当更改应进入 changelog 时添加 conventional 前缀； - 对用户可见的功能和修正使用 `feat:` 与 `fix:`； - 内部重构和杂务不使用前缀； - 每项破坏性更改都以 `!` 作为后缀标记。 提交主题应说明面向用户的目的，并在项目要求时包含 issue 或评审引用。 当一项破坏性更改影响多个 crate，且一条提交消息无法准确描述所有影响时，应按 crate 拆分。将破坏性 API 更改放在第一个提交中，将下游适配放在后续提交中。 如果发布自动化会依据提交消息生成版本号或 changelog，应将提交消息视为发布输入。 只要代码更改直接影响高级指南、贡献说明、开发备注、crate 状态记录或稳定性文档，就更新这些内容。 除非项目规定了更严格的目标，否则以主 CI 环境中可用的参考工具版本作为兼容性基线。 ## 完成前用清单检查，从 crate 层级到提交信息 完成前： 1. 确定更改属于底层机制还是高层便捷层； 2. 检查相似 crate 中已确立的模式； 3. 确认错误处理符合该 crate 当前使用的框架； 4. 验证没有引入生产代码中的 `unwrap()`； 5. 检查所有受影响的 feature 组合和发布变体； 6. 分别考虑库调用方和命令行用户； 7. 根据需要运行聚焦测试、工作区测试、journey 测试和兼容性测试； 8. 确认面向字节的路径在跨平台时不会丢失信息； 9. 评审新增的 clone、分离、缓存和同步是否有可测量的必要性； 10. 更新直接相关的文档； 11. 确认提交消息正确描述对 changelog 和破坏性更改的影响。 如有未测试的 feature 集、平台、参考实现比较或发布变体，请准确报告缺失的前提条件。不要根据一次默认 feature 的单元测试运行就声称整个工作区兼容。