该技能用于编写和审查 unsafe Rust 的 # Safety 文档与 safety 注释,把每个 # Safety 段落当作英语定理、把 safety 注释(如 // SAFETY: 或 /// safety:,大小写不限)当作英语证明,目标是逻辑严密而非安慰性描述。
适用范围:unsafe fn、unsafe trait 及其方法、unsafe impl、unsafe extern 块/函数、no_mangle 等 unsafe 属性、unsafe {} 块、裸指针解引用、调用 unsafe 函数、访问 union 字段、可变/外部 static、内联汇编、FFI 边界、手工分配与布局/初始化/drop 管理、pin 投影,以及可能建立或破坏不变量的安全 API(含宏生成代码)。
核心模型:写 # Safety 文档需说明前置条件由谁负责、持续多久;写 safety 注释需证明该操作在当前位置的义务已被满足,并说明操作后的状态变化。每条证明敏感语句须可归类为公理(Rust Reference 或标准库文档)、依赖引理(有意选用的安全依赖的文档行为)、前置条件、项目内不变量、局部事实、类型事实或后置条件。
证据层级:仅 Rust Reference 与标准库文档为核心公理;非标准库依赖只能作为依赖引理,建议固定版本并给出文档链接,不得借其发明布局、别名、有效性或 UB 规则。调用方提供的安全代码(闭包、回调、迭代器、Ord、Drop 等安全 trait 实现)必须视为“对抗性但类型正确”,它可能 panic、不终止、违反 trait 语义、通过内部可变性改状态或重入;除非该 trait 为 unsafe、性质被动态检查、实现集被 crate 控制或密封严密、或类型系统独立强制该性质。安全 trait 法则不得用于记忆安全证明。排序、迭代器长度提示、回调等均属此类:不能假定调用方的 Ord 定义全序,也不能相信 size_hint 以避免越界或重复 drop。
允许的本地前提:模块/类型/表示/所有权/初始化/别名/pin/FFI/同步不变量及既有的安全契约;引用时必须精确命名,并验证所有构造器、修改器、析构器、trait 实现、FFI 入口与 panic 路径都维持它。局部事实仅在 unsafe 操作处仍成立时有效;若早前检查过,需说明未被变更、重分配、回调、panic、drop 或内部可变性失效。
写法:公开 unsafe API 用 /// # Safety 描述调用方或实现方契约;具体 unsafe 操作前用 // SAFETY: 证明。unsafe impl 上直接放置的文档注释或普通注释均可作为安全注释。Clippy 的 undocumented_unsafe_blocks lint 识别 // SAFETY:;大小写或标点差异不影响证明有效性,仅在有 lint 要求时作为工具备注提及,不视为健全性缺陷。