rust-sota-arsenal

Rust SOTA 工具集

用于重构、性能分析、基准测试、测试和 SIMD 优化的前沿 Rust 工具知识——大模型通常缺乏这些工具的深度训练数据。

自我演进的技能：此技能会在使用过程中不断改进。如果说明有误、参数发生变化，或需要采用变通方案，请立即修正此文件，不要拖延。仅针对真实、可复现的问题进行更新。

关键：行动前先通过网络核实

此技能中的参考文档只是起点，并非事实依据。 工具版本、兼容性矩阵和 API 范围的变化速度比静态文档快。在推荐特定版本或决定是否升级之前：

1. 在 crates.io 上检查最新版本：使用 WebFetch 获取 crates.io API 中的当前版本信息

   WebFetch: https://crates.io/api/v1/crates/{crate_name}
   Prompt: "What is the latest version? List recent versions."
   

2. 检查依赖项兼容性：升级时（例如 PyO3），验证下游 crate 的兼容性

   WebFetch: https://crates.io/api/v1/crates/{crate_name}/{version}/dependencies
   Prompt: "What version of {dependency} does this require?"
   

3. 搜索破坏性变更：使用 WebSearch 查找变更日志和迁移指南

   WebSearch: "{crate_name} latest version changelog migration"
   

4. 备用方案：使用 Firecrawl 抓取（如果 WebFetch 失败或返回的数据不完整，例如页面大量依赖 JS 或触发速率限制）：

   curl -s -X POST https://api.firecrawl.dev/v2/scrape \
     -H "Content-Type: application/json" \
     -d '{"url": "https://crates.io/crates/{crate_name}", "formats": ["markdown"], "waitFor": 0}' \
     | jq -r '.data.markdown'
   

   公开 API——无需密钥，也无需 tailnet。完整 API 参考请参阅 /devops-tools:firecrawl-research-patterns。

原因：opendeviationbar 会话通过网络搜索才发现 PyO3 的版本是 0.28.2（而不是 0.28），且 pyo3-arrow 只有 0.17.0——静态文档会导致错误的升级决策。

适用场景

• 重构 Rust 代码（基于 AST 的搜索/替换、API 兼容性）
• 性能优化（性能分析、PGO、Cargo 配置调优）
• 基准测试（选择 divan 或 Criterion、设置基准测试）
• 测试（更快的测试运行器、变异测试、功能标志测试）
• SIMD 优化（稳定版 Rust 上的可移植 SIMD）
• 迁移 PyO3 绑定（0.22+）

快速参考

工具	安装	一句话介绍	类别
ast-grep	cargo install ast-grep	面向 AST 的 Rust 搜索/重写	重构
cargo-semver-checks	cargo install cargo-semver-checks	API 兼容性检查（数百条 lint）	重构
samply	cargo install samply	Profile → Firefox Profiler 界面	性能
cargo-pgo	cargo install cargo-pgo	PGO + BOLT 优化	性能
cargo-wizard	cargo install cargo-wizard	自动配置 Cargo 配置文件	性能
divan	divan = "<version>" in dev-deps	#[divan::bench] 属性 API	基准测试
criterion	criterion = "<version>" in dev-deps	由统计数据驱动，生成 Gnuplot 报告	基准测试
cargo-nextest	cargo install cargo-nextest	快 3 倍，每个测试单独运行进程	测试
cargo-mutants	cargo install cargo-mutants	变异测试（未发现/已捕获）	测试
cargo-hack	cargo install cargo-hack	特性幂集测试	测试
macerator	macerator = "<version>" in deps	类型泛化 SIMD + 多版本化	SIMD
cargo-audit	cargo install cargo-audit	RUSTSEC 漏洞扫描	依赖项
cargo-deny	cargo install cargo-deny	许可证 + 公告 + 禁用项	依赖项
cargo-vet	cargo install cargo-vet	Mozilla 供应链审计	依赖项
cargo-outdated	cargo install cargo-outdated	检查依赖项是否过时	依赖项
cargo-geiger	cargo install cargo-geiger	检测依赖项中的不安全代码	依赖项
cargo-machete	cargo install cargo-machete	查找未使用的依赖项	依赖项

重构工作流

ast-grep：面向 AST 的搜索与重写

适用场景：跨代码库重构模式——比正则表达式更安全，因为它能理解 Rust 语法。

# Search for .unwrap() calls
ast-grep --pattern '$X.unwrap()' --lang rust

# Replace unwrap with expect
ast-grep --pattern '$X.unwrap()' --rewrite '$X.expect("TODO: handle error")' --lang rust

# Find unsafe blocks
ast-grep --pattern 'unsafe { $$$BODY }' --lang rust

# Convert match to if-let (single-arm + wildcard)
ast-grep --pattern 'match $X { $P => $E, _ => () }' --rewrite 'if let $P = $X { $E }' --lang rust

对于复杂的多规则转换，请使用 YAML 规则文件。参见 ast-grep 参考。

cargo-semver-checks：API 兼容性

适用场景：发布 crate 版本前——可捕获意外的破坏性变更。

# Check current changes against last published version
cargo semver-checks check-release

# Check against specific baseline
cargo semver-checks check-release --baseline-version 1.2.0

# Workspace mode
cargo semver-checks check-release --workspace

数百条内置 lint 涵盖函数移除、类型变更、trait 实现变更等（lint 数量随每次发布而增长）。参见 cargo-semver-checks 参考。

性能工作流

步骤 1：使用 samply 进行性能分析

# Build with debug info (release speed + symbols)
cargo build --release

# Profile (macOS — uses dtrace, needs SIP consideration)
samply record ./target/release/my-binary

# Opens Firefox Profiler UI in browser automatically
# Look for: hot functions, call trees, flame graphs

macOS dtrace 设置和火焰图解读请参见 samply 参考。

步骤 2：使用 cargo-wizard 自动配置配置文件

# Interactive — choose optimization goal
cargo wizard

# Templates:
# 1. "fast-compile" — minimize build time (incremental, low opt)
# 2. "fast-runtime" — maximize performance (LTO, codegen-units=1)
# 3. "min-size"     — minimize binary size (opt-level="z", LTO, strip)

cargo-wizard 会直接写入 Cargo.toml 的 [profile.*] 区段。该工具获得 Cargo 团队认可。参见 cargo-wizard 参考。

步骤 3：使用 cargo-pgo 执行 PGO + BOLT

实现最高性能的三阶段工作流：

# Phase 1: Instrument
cargo pgo build

# Phase 2: Collect profiles (run representative workload)
./target/release/my-binary < typical_input.txt

# Phase 3: Optimize with collected profiles
cargo pgo optimize

# Optional Phase 4: BOLT (post-link optimization, Linux only)
cargo pgo bolt optimize

对于 CPU 密集型代码，PGO 通常可带来 10-20% 的速度提升。参见 cargo-pgo 参考。

基准测试工作流

divan 与 Criterion 对比——如何选择

方面	divan	Criterion
API 风格	#[divan::bench] 属性	criterion_group! + criterion_main! 宏
设置	添加依赖 + #[divan::bench]	添加依赖 + benches/ 目录 + Cargo.toml [[bench]]
泛型基准测试	内置 #[divan::bench(types = [...])]	使用宏手动实现
分配分析	内置 AllocProfiler	需要外部工具
报告	终端（彩色）	HTML + Gnuplot 图表
CI 集成	CodSpeed（原生支持）	CodSpeed + criterion-compare
维护情况	有维护（查看 crates.io 了解更新频率）	活跃（criterion-rs 组织维护）

建议：新项目使用 divan（API 更简单）；现有项目或需要 HTML 报告时使用 Criterion。参见 divan-and-criterion 参考文档。

divan 快速入门

fn main() {
    divan::main();
}

#[divan::bench]
fn my_benchmark(bencher: divan::Bencher) {
    bencher.bench(|| {
        // code to benchmark
    });
}

Criterion 快速入门

use criterion::{criterion_group, criterion_main, Criterion};

fn my_benchmark(c: &mut Criterion) {
    c.bench_function("name", |b| {
        b.iter(|| {
            // code to benchmark
        });
    });
}

criterion_group!(benches, my_benchmark);
criterion_main!(benches);

测试工作流

cargo-nextest：更快的测试运行器

# Run all tests (3x faster than cargo test)
cargo nextest run

# Run with specific profile
cargo nextest run --profile ci

# Retry flaky tests
cargo nextest run --retries 2

# JUnit XML output (for CI)
cargo nextest run --profile ci --message-format libtest-json

配置文件：.config/nextest.toml。参见 cargo-nextest 参考文档。

cargo-mutants：变异测试

# Run mutation testing on entire crate
cargo mutants

# Filter to specific files/functions
cargo mutants --file src/parser.rs
cargo mutants --regex "parse_.*"

# Use nextest as test runner (faster)
cargo mutants -- --test-tool nextest

# Check results
cat mutants.out/missed.txt     # Tests that didn't catch mutations
cat mutants.out/caught.txt     # Tests that caught mutations

结果类别：caught（良好）、missed（测试较弱）、timeout（超时）、unviable（无法编译）。参见 cargo-mutants 参考文档。

cargo-hack：功能标志测试

# Test every feature individually
cargo hack test --each-feature

# Test all feature combinations (powerset)
cargo hack test --feature-powerset

# Exclude dev-dependencies (check only)
cargo hack check --feature-powerset --no-dev-deps

# CI: verify no feature combination breaks compilation
cargo hack check --feature-powerset --depth 2

对于包含多个功能的库 Crate，这项工具必不可少。参见 cargo-hack 参考文档。

SIMD 决策矩阵

Crate	稳定版 Rust	类型泛型	多版本化	维护情况
macerator	是	是	是（稳定版）	活跃
wide	是	否（具体类型）	否	活跃
pulp	是	是	是	已被 macerator 取代
std::simd	仅限 Nightly	是	否	仅限 Nightly（跟踪问题：rust-lang/rust#86656）

建议：在稳定版 Rust 上进行新的 SIMD 开发时使用 macerator。它是 pulp 的分支，支持类型泛型操作和运行时多版本分派（SSE4.2 → AVX2 → AVX-512）。参见 macerator 参考文档。

关注列表：fearless_simd（架构支持有限——仅支持 NEON/WASM/SSE4.2）、std::simd（仅限 Nightly——查看跟踪问题了解稳定化状态）。

PyO3 升级路径

对于 Rust↔Python 绑定，自 0.22 以来，PyO3 已发生显著变化。请务必查看 PyO3 更新日志以获取最新版本：

版本	主要变化
0.22	引入 Bound<'_, T> API（取代 GIL 引用）
0.23	完全移除 GIL 引用，新增 IntoPyObject trait
0.24	支持 vectorcall，性能提升
0.25+	支持自由线程 Python（3.13t），新增 UniqueGilRef

参见 PyO3 升级指南了解迁移模式。

参考文档

• ast-grep-rust.md — 感知 AST 的重构模式
• cargo-hack.md — 功能标志测试
• cargo-mutants.md — 变异测试
• cargo-nextest.md — 新一代测试运行器
• cargo-pgo.md — 基于配置文件的优化
• cargo-semver-checks.md — API 兼容性
• cargo-wizard.md — 配置文件自动配置
• divan-and-criterion.md — 基准测试对比
• macerator-simd.md — 类型泛化 SIMD
• pyo3-upgrade-guide.md — PyO3 迁移
• samply-profiling.md — 交互式性能分析

发布流水线

plugins/rust-tools/scripts/rust-release-check.sh 中提供了一个包含 4 个阶段的发布门禁脚本。它将所有质量门禁整合到一个可执行文件中，可调整后用于任何 Rust 项目。

运行

# Full pipeline (Phases 1-3)
./plugins/rust-tools/scripts/rust-release-check.sh

# Include nightly-only checks (Phase 4)
./plugins/rust-tools/scripts/rust-release-check.sh --nightly

# Skip test suite (Phases 1-2 only)
./plugins/rust-tools/scripts/rust-release-check.sh --skip-tests

要在项目中将其用作 moon 任务，请将脚本复制到 tasks/ 并在 moon.yml 中进行配置：

cp plugins/rust-tools/scripts/rust-release-check.sh tasks/release-check

tasks:
  release-check:
    description: "4-phase Rust release pipeline"
    script: "bash tasks/release-check"

阶段概览

阶段	名称	工具	阻断构建	备注
1	快速门禁	fmt, clippy, audit, machete, geiger	是	并行运行以提高速度
2	深度门禁	deny, semver-checks, outdated	混合	outdated 仅提供建议（不会导致构建失败）
3	测试	nextest（或回退到 cargo test）	是	可通过 --skip-tests 跳过
4	仅限 Nightly	udeps, hack	是	通过 --nightly 标志启用

阶段 1 -- 快速门禁 使用后台进程并行运行所有工具。每个工具都会先检查是否已安装；缺少的工具会发出警告并跳过，而不会导致失败。

阶段 2 -- 深度门禁 按顺序运行。cargo deny 需要存在 deny.toml。cargo semver-checks 仅对库 crate 运行（通过 Cargo.toml 中的 [lib] 或 src/lib.rs 检测）。cargo outdated 仅提供建议——会报告问题，但不会阻断构建。

阶段 3 -- 测试 优先使用 cargo nextest run 以提高速度；如果未安装 nextest，则回退到 cargo test。

阶段 4 -- 仅限 Nightly 需要 --nightly 标志和 nightly 工具链。cargo +nightly udeps 会查找真正未使用的依赖项。cargo hack check --each-feature 会验证每个功能标志都能独立编译。

退出代码

• 0 -- 所有阻断构建的门禁均已通过（建议性警告不影响结果）
• 1 -- 一个或多个阻断构建的门禁失败

末尾的摘要会报告通过项、失败项和建议性警告的总数。

故障排除

问题	解决方案
ast-grep 未找到匹配项	检查 --lang rust 标志；模式必须匹配 AST 节点，而非文本
samply 权限被拒绝	macOS：运行 sudo samply record，或为 dtrace 停用 SIP
cargo-pgo 未提升速度	性能分析期间的工作负载必须能代表实际使用情况
cargo-mutants 太慢	使用 --file 或 --regex 进行筛选；使用 -- --test-tool nextest
divan 与 criterion 冲突	两者可以共存——在 Cargo.toml 中使用独立的基准测试目标
macerator 编译错误	检查 Rust 最低版本；需要 SIMD 目标特性
cargo-nextest 缺少测试	不支持文档测试；请单独使用 cargo test --doc
cargo-hack 在 powerset 模式下内存溢出	使用 --depth 2 限制组合数量

执行后反思

此技能完成后，请在结束任务前进行反思：

0. 确定所在位置。 — 在编辑前找到此 SKILL.md 的规范路径。
1. 出现了什么问题？ — 修复导致问题的指令。
2. 哪些做法比预期更有效？ — 将其列为推荐做法。
3. 有哪些内容发生了偏差？ — 修复不再符合实际情况的脚本、参考资料或依赖项。
4. 记录下来。 — 添加演进日志条目，说明触发原因、修复内容和证据。

请勿推迟处理。下一次调用会继承你留下的一切。