rust

此技能是 Rust 参考资料集的路由外壳，并非完整的系统编程手册。

不可妥协的规则：

1. 编码前先确定子系统。只加载相关参考资料。
2. 默认使用安全 Rust。 只有在理由充分时才使用 unsafe——每个 unsafe 代码块都必须附带 // SAFETY: 注释。
3. 尽可能零拷贝。 使用 mmap 映射的段，以及指向页面的 &str/&[u8] 引用。没有理由时绝不复制数据。
4. 每个 crate 使用自己的错误类型。 库 crate 使用 thiserror 枚举。库中绝不使用 anyhow——仅限二进制程序和测试。
5. 使用 tokio 进行异步处理。 所有 I/O 都是异步的。CPU 密集型工作放到 spawn_blocking 中。绝不阻塞 tokio 运行时。
6. 遵循工作区 crate 结构。 每个子系统对应一个 crate。依赖关系只能向下，绝不循环依赖。
7. 针对不变量编写属性测试。 使用 proptest 测试往返转换、类型强制转换和二进制解析。

rust

输入

• $request：目标 crate、子系统、错误、功能或审查对象

目标

根据正确的子系统惯例处理 Rust 工作，使更改遵循工作区的系统编程模式，而非通用的 Rust 默认做法。

步骤 0：确定子系统

判断任务涉及 Rust 代码的哪一部分：

• 存储引擎
• 二进制格式
• 类型系统
• Arrow 或 DataFusion
• 线协议
• 搜索或向量
• arena 或图代码
• 地理索引
• 异步或并发
• 测试
• unsafe 或错误设计

成功标准：加载参考资料前，先将任务归入正确的子系统。

步骤 1：仅加载相关参考资料

使用路由表选择匹配的文件。不要批量加载整个参考资料树。

任务 / 领域	阅读
工具链、工作区布局、关键 crate、Cargo 约定	references/stack.md
WAL、mmap、段、MVCC、压实、io_uring、后端	references/storage-engine.md
自定义磁盘格式、零拷贝解析、打包结构体	references/binary-formats.md
数据库类型系统、磁盘 / 执行类型、Arrow 互操作	references/type-system.md
DataFusion 表提供程序、UDF、Arrow RecordBatch、规划	references/datafusion-arrow.md
pgwire 服务端、MySQL 协议、方言映射、ORM 兼容性	references/wire-protocols.md
tantivy 全文搜索、HNSW 向量、SIMD 距离、混合搜索	references/search-vector.md
bumpalo arena、图邻接、遍历算法	references/arena-graph.md
R-tree 空间索引、地理谓词、WGS84 距离	references/geo-rtree.md
tokio 异步、io_uring、crossbeam、无锁结构、MVCC	references/async-concurrency.md
proptest、确定性测试、集成测试模式	references/testing.md
thiserror 层级、unsafe 模式、安全不变量	references/error-unsafe.md

多个任务？阅读多个文件。

成功标准：仅启用与子系统相关的 Rust 指南。

步骤 2：遵循 Rust 核心防护规则进行实现

始终遵循以下规则：

• 默认使用安全 Rust；只有理由充分时才使用 unsafe，并附上 // SAFETY: 注释
• 错误类型应符合 crate 边界（库使用 thiserror，anyhow 仅限二进制程序和测试）
• 异步代码不得阻塞运行时；CPU 密集型工作放到 spawn_blocking 中
• 明确选择拥有或借用数据；签名中优先使用 &[u8]，而非 Vec<u8>
• 显式导入 use；除测试模块外，不使用通配符导入
• 对返回 Result 或计算值的函数添加 #[must_use]
• 仅在热循环中的小函数上使用 #[inline]，绝不用于公共 API
• 跨越异步边界的 trait 对象必须满足 Send + Sync 约束
• 所有公共类型都派生 #[derive(Debug)]；仅在克隆开销低时才派生 #[derive(Clone)]
• 可选 crate 依赖使用功能标志：#[cfg(feature = "...")]
• 根据风险选择匹配的测试：单元测试、集成测试、属性测试、快照测试或领域专用验证

成功标准：实现符合工作区的系统级质量标准。

步骤 3：验证更改

使用范围最小且相关的验证流程：

• cargo fmt
• cargo clippy -- -D warnings
• 针对性 crate 测试
• 适用时运行子系统专属测试，例如 proptest 或快照测试

成功标准：Rust 接口已按此工作区的预期完成验证。

防护准则

• 不要将整本 Rust 手册内联到 SKILL.md 中。
• 不要跳过子系统识别。
• 除非项目明确允许，否则不要在库 crate 中使用 anyhow。
• 不要添加 disable-model-invocation；这是一个常规领域技能。
• 不要让不安全代码的不变量缺少文档说明。

何时加载参考资料

• references/stack.md 用于了解工作区和工具链背景。

• 此后仅加载 references/ 下与任务相关的子系统文件

输出约定

报告以下内容：

1. 加载了哪些 Rust 参考资料
2. 应用了哪种子系统模式
3. 所做的更改
4. 运行的验证