# 从三个开源项目提取的 Rust 评审规则

提取日期：2026-11-12。目标是让 Rust 代码质量审查拥有可追溯的规则，供人工、Claude Code 或 OCR 使用。规则是自然语言审查清单；执行仍依赖审查者/LLM 及实际编译、测试等工具。

## 文件入口

| 文件 | 用途 |
|---|---|
| [trailofbits.md](trailofbits.md) | 完整覆盖固定版本 manifest 的 15 类、69 个检查项，保留原规则前缀和原文链接 |
| [awesome-skills.md](awesome-skills.md) | Rust 专项及关联通用指南，归纳为 23 组，偏所有权、异步取消、错误处理和代码质量 |
| [beautiful-rust.md](beautiful-rust.md) | 通用 Rust review/best-practices 内容，归纳为 29 组，偏 API、类型设计、可维护性与测试 |
| [rules.md](rules.md) | 去重后的 38 条通用规则，加 7 条 IDPS 项目约束；适合直接给审查者阅读 |
| [ocr-rule.json](ocr-rule.json) | 从合并规则生成的 OCR 配置，分别匹配 Rust 文件和 Cargo.toml，保留 OCR 内置规则 |
| [sources.lock.json](sources.lock.json) | 三个来源的完整提交 SHA、输入文件路径、原文件 SHA-256 和固定版本 URL |
| [licenses/](licenses/) | 原始许可证文本与版权声明 |

23 组、29 组及 R/I 编号是本次整理方式，不是上游官方规则数量。三个清单均有压缩与改写；仅 Trail of Bits 的 69 个 manifest 检查项逐一保留，不声称收录三个仓库的所有 skill、示例或子规则。

另有 [OCR 内置 Rust/Cargo 规则独立提取](ocr-builtins/README.md)：保存 OCR v1.13.8 的 41 项 Rust 规则和 12 项 Cargo.toml 规则，提供中文提取及英文原文。它单独采用 Apache-2.0 许可，未合入本目录的 `rules.md` 或 `ocr-rule.json`。

## 固定版本和来源

| 来源 | 固定提交 | 主要输入 | 原项目许可 |
|---|---|---|---|
| [trailofbits/skills](https://github.com/trailofbits/skills) | `e4dd0bb5b15535f7c5a0834187dffba6ac37e4ff` | `plugins/rust-review/prompts/clusters/manifest.json`、15 个 cluster、55 个 general finder，以及该插件 README | CC BY-SA 4.0 |
| [awesome-skills/code-review-skill](https://github.com/awesome-skills/code-review-skill) | `4850184dfd7765ea7b3c5c4e9b6cf8e0815ee7cb` | `reference/rust.md`、`reference/cross-cutting/error-handling-principles.md`、`reference/cross-cutting/async-concurrency-patterns.md` | MIT |
| [morganlinton/BeautifulRust](https://github.com/morganlinton/BeautifulRust) | `b9718436d77ee7bcf17cdcb6aa27628feb95d97a` | `skills/rust-review/SKILL.md`、`skills/rust-best-practices/SKILL.md` 及指南摘要索引 | MIT |

本次提取不包含 Trail of Bits 的多 agent 调度、误报裁判程序、SARIF 生成器；它们是工具执行流程。BeautifulRust 的 Bevy/ECS、移植 skill、自动重构流程和平台特定性能参数也不加入 IDPS 通用清单。因此，把这些规则交给 OCR 不等于执行了原工具全部分析阶段。

## 合并时采用的原则

1. **质量优先**：正确性、错误传播、状态一致性、资源、并发与测试先于命名和语法偏好。
2. **按适用条件检查**：没有 FFI 不制造 FFI 发现；应用代码不强套所有公共库设计建议；已有安全封装和已证明不变量要纳入判断。
3. **严重度与置信度分开**：每项提供位置、触发条件、实际影响、证据和最小修复；待验证疑点不包装成已证实漏洞。
4. **保留项目约定**：沿用 IDPS actor、消息传递、错误类型、工具链、产品差异与兼容要求；项目约束使用 I 前缀，和上游来源分开。
5. **检查技术表述**：上游的好/坏示例和检测器门槛也可能过强或有误，不作机械照搬。

值得特别注意的校正：

| 上游内容 | 合并版处理 |
|---|---|
| awesome-skills 的 `good_get_unchecked` 只用 `debug_assert!` 后执行 unchecked 访问 | 此示例不能作为安全封装；release 默认关闭 debug_assert 时会缺少保障，见 [标准库说明](https://doc.rust-lang.org/std/macro.debug_assert.html) |
| 用 transaction 命名、pin 或 spawn 说明取消安全 | 必须证明实际状态保存、回滚和任务管理；read_exact 改成 read 仍需帧缓冲，见 [Tokio select 的取消安全说明](https://docs.rs/tokio/latest/tokio/macro.select.html#cancellation-safety) |
| Trail of Bits PTRCAST 对部分指针整数往返、胖转瘦的绝对判定 | 根据 provenance、元数据和后续实际访问判断，见 [std::ptr](https://doc.rust-lang.org/std/ptr/index.html#provenance)；不因转换语法直接认定 UB |
| select 没有 biased、没有开特定 lint 就报告缺陷 | 分别证明调度/退出需求被破坏，或已有配置存在实际缺口；不把偏好当漏洞 |
| BeautifulRust 对内部不变量/锁中毒允许或建议 expect | IDPS 生产代码禁 unwrap/expect，服从项目约束 |
| 没有 SAFETY 注释、手写 Ord 配 derive PartialEq | 前者先是文档/可审计性问题；后者核对实际等价关系，不自动认定 UB 或集合错误 |

现有 [Rust 代码审查规范](../rust-code-review.md) 仍是工作区的相关文档；这里是可追溯的补充规则集。遇到旧清单中“全部禁止”的宽泛表述，仍要按真实 Rust 契约、协议兼容性和更具体的项目要求判断，例如 Tokio Mutex 可跨 await，配置未知字段是否拒绝取决于兼容约定。

## 在 OCR 全量扫描中使用

配置按已核对的 OCR **v1.13.8** `--rule` 结构整理。它包含两条规则：`**/*.rs` 使用完整 R/I 清单；`**/Cargo.toml` 使用构建、依赖、feature、MSRV 和 profile 相关检查。两条均设置 `merge_system_rule: true`。

在 `idps-server` 根目录，已有 OCR 和模型配置时先查看扫描范围：

```bash
ocr scan \
  --rule ../idps-docs/common/rust-review-rules/ocr-rule.json \
  --preview
```

正式扫描并保存 JSON：

```bash
IDPS_OCR_OUT="${TMPDIR:-/tmp}/idps-ocr-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$IDPS_OCR_OUT"

ocr scan \
  --rule ../idps-docs/common/rust-review-rules/ocr-rule.json \
  --format json \
  --output "$IDPS_OCR_OUT/result.json"
```

`ocr scan` 用于全量文件扫描。这里的 `include` 用来让测试 Rust 文件绕过某些默认排除，**不是只扫描这些路径的白名单**；其他文件是否扫描继续服从 OCR 过滤和内置规则。显式排除构建目录、vendor/repo 管理目录及本项目证书/密钥资产。执行前以 `--preview` 核对目标分支的实际文件集合。

`merge_system_rule` 只把命中的自定义项与内置语言规则合并，不会合并同一数组内的多条自定义规则；首个匹配项胜出。当前 Rust 和 Cargo.toml 两项互不重叠。现有 OCR 规则如果还承担脚本/配置检查，需要在原配置中按路径整合，避免被更前面的 `**/*` 规则遮住。

合并清单比 OCR 内置 Rust 规则长，会增加提示词长度和模型使用量。它提供检查方向，不能保证模型在单文件上下文中完成跨模块证明；跨文件、协议或持久化发现必须补读相应上下文并复核。OCR 使用自身模型配置调用 LLM，加载这份 JSON 不会自动调用 Claude Code，也不需要安装这三个项目的 skill。

本次交付只提取和验证规则文件。当前环境未找到 `ocr` 可执行文件，未运行 OCR CLI 加载/preview、模型调用或 idps-server 扫描；JSON 结构与已获取的 v1.13.8 文档核对，不把它当作 CLI 实测结果。

## 给 Claude Code 使用

可以直接提供文件路径和任务，无需先安装上游 skill。例如在工作区根目录提出：

```text
对 idps-server 做全量代码质量审查。
先读取目标分支适用的 AGENTS.md、CLAUDE.md、Cargo.toml 和架构文档。
使用 idps-docs/common/rust-review-rules/rules.md 的 R01–R38 与 I01–I07。
需要核对规则来源时读取同目录三份来源清单。
报告已有缺陷，每项包含位置、触发条件、影响、证据、最小修复和回归场景。
区分已证实、项目规范违规、待验证和改进建议。先输出评审，不修改代码。
```

这只是读取规则开展评审，不会安装或复现 Trail of Bits 的多 agent 工作流。

## 归属与许可

- Trail of Bits / rust-review 的原作者与贡献者保有权利；插件 README 列出的作者为 **Andrea Cappa（Aptos Labs）**、**Paweł Płatek（Trail of Bits）**。本次对其规则进行中文归纳、压缩、纠正过强表述和 IDPS 适配，未得到原作者背书。许可证全文见 [trailofbits-CC-BY-SA-4.0.txt](licenses/trailofbits-CC-BY-SA-4.0.txt)，许可链接为 [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)。
- awesome-skills：Copyright (c) 2025 awesome-skills。保留 [MIT 全文](licenses/awesome-skills-MIT.txt)。
- BeautifulRust：Copyright (c) 2026 Morgan Linton。保留 [MIT 全文](licenses/beautiful-rust-MIT.txt)。它引用的五份原指南/书籍仍按各自许可发布；此处提取仓库的规则摘要，不重新许可第三方原文。原始来源链接见 [BeautifulRust 清单](beautiful-rust.md)。
- `trailofbits.md`、合并衍生的 `rules.md`、`ocr-rule.json` 以及本 README 按 **CC BY-SA 4.0** 提供，继续分发改写版本应保留归属、变更说明与同方式共享要求。`awesome-skills.md` 和 `beautiful-rust.md` 的本次改写按 **MIT** 提供，沿用对应的完整许可与归属声明。
- 上述许可说明限定于本目录提取/改写的规则资料，不改变其他 IDPS 文档或产品代码的许可。
