rust-doctor

# rust-doctor <p align="center"> <a href="https://crates.io/crates/rust-doctor"><img alt="Crates.io" src="https://img.shields.io/crates/v/rust-doctor?logo=rust"></a> <a href="https://www.npmjs.com/package/rust-doctor"><img alt="npm" src="https://img.shields.io/npm/v/rust-doctor?logo=npm"></a> <a href="https://docs.rs/rust-doctor"><img alt="docs.rs" src="https://img.shields.io/docsrs/rust-doctor?logo=docsdotrs&label=docs.rs"></a> <a href="https://github.com/ArthurDEV44/rust-doctor/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/ArthurDEV44/rust-doctor/actions/workflows/ci.yml/badge.svg"></a> <a href="https://crates.io/crates/rust-doctor"><img alt="Downloads" src="https://img.shields.io/crates/d/rust-doctor?label=downloads"></a> <a href="#license"><img alt="License" src="https://img.shields.io/crates/l/rust-doctor"></a> <img alt="MSRV" src="https://img.shields.io/badge/MSRV-1.85-blue?logo=rust"> </p> **一键式健康检查工具，适用于您的 Rust 项目。** rust-doctor 扫描安全、性能、正确性、架构和依赖问题，然后将所有问题汇总成一个 0-100 的评分，并提供可操作的诊断信息。 它在一轮扫描中运行 `cargo clippy`、`cargo-audit`、`cargo-deny`、`cargo-geiger` 和 19 条自定义 AST 规则，并以 CLI、库 crate、MCP 服务器、npm 包和 GitHub Action 的形式提供，因此它可以在您的终端、CI 和 Claude Code、Cursor 或任何 MCP 代理中使用。 ```console $ rust-doctor # rust-doctor 扫描其自身的代码库 ◠ ◠ rust-doctor ▽ 99 / 100 优秀 ████████████████████████████████████████ 安全 99 · 可靠性 99 · 可维护性 100 · 性能 99 · 依赖 99 ✓ 0 错误 ⚠ 44 警告 ℹ 42 信息 · 60 文件扫描，耗时 32.9 秒 ``` ## 快速入门 无需 Rust 工具链 — `npx` 为您的平台下载预编译的原生二进制文件： ```bash npx rust-doctor # 扫描当前目录并输出评分 ``` 更喜欢 cargo？`cargo install rust-doctor`。想在 AI 代理中使用？`npx rust-doctor setup`。其他格式请参见 [安装](#安装)。 ### 查看实际操作 → https://github.com/user-attachments/assets/6766a5d8-9a47-4eb8-892e-76c1a23eb122 ## 适用场景 Rust 已经拥有优秀的点工具。rust-doctor 将它们组合在一起，添加它们未覆盖的规则，并将结果转化为一个您可以跟踪的数字。 | 您正在使用 | 它为您提供 | rust-doctor 添加 | |---|---|---| | `cargo clippy` | 700+ 内置 lint | 分类 + 严重性映射，19 条自定义 AST 规则（安全、异步、框架、架构），以及一个 0-100 的评分 | | `cargo audit` / `cargo deny` | CVE 和供应链检查 | 一轮扫描同时运行 clippy、geiger 和 machete — 如果工具未安装，则跳过 | | 单独的 CI 步骤 | 每个工具的输出 | 一个命令，支持 `--json`、 `--sarif`、 `--diff`、 `--score` 和 PR 评论 | | Claude Code / Cursor | 代码生成 | MCP 服务器和斜杠命令技能，以便代理扫描、评分和修复代码 | ## 功能 - **700+ clippy lint**，具有明确的严重性覆盖和分类映射 - **19 条自定义 AST 规则**，通过 [syn](https://crates.io/crates/syn)：错误处理、性能、安全、异步、架构和框架反模式 - **异步反模式检测**：异步上下文中的阻塞调用和 `block_on` - **框架感知规则**：tokio、axum、actix-web — 仅在存在依赖时运行 - **供应链审计**：通过 `cargo-audit` 进行 CVE，通过 `cargo-deny` 进行禁止/许可，通过 `cargo-geiger` 进行不安全，通过 `cargo-machete` 进行未使用的依赖 - **0-100 健康评分**，跨五个加权维度，具有 ASCII 医生，对结果做出反应 - **MCP 服务器**：适用于 Claude Code、Cursor、Windsurf 或任何 MCP 客户端的 4 个只读工具 + 2 个专家审计提示 - **差异模式**： `--diff` 仅扫描更改的文件以获取快速 CI 反馈 - **工作区支持**：扫描每个 crate 或选择特定的成员 - **内联抑制**：`// rust-doctor-disable-next-line <rule>` - **输出模式**：终端、`--json`、 `--score` （CI 的裸整数）、 `--sarif` （GitHub 代码扫描） - **`--fix`**：对源文件应用机器可用的修复 - **设置向导**：`rust-doctor setup` 自动检测 Claude Code、Cursor 和 Windsurf，并通过一个命令连接 MCP 或安装技能 - **分布式**：CLI 二进制文件、库 crate、MCP 服务器、npm 包和 GitHub Action ## 安装 ### npm / npx（推荐用于 MCP 用户） ```bash npx rust-doctor --mcp ``` 或全局安装： ```bash npm install -g rust-doctor ``` 这为您的平台下载预编译的原生二进制文件 — 无需 Rust 工具链。 ### cargo 安装（从源代码） ```bash cargo install rust-doctor ``` ### cargo binstall（预编译二进制文件） ```bash cargo binstall rust-doctor ``` ### Shell 安装程序（Linux/macOS） ```bash curl -fsSL https://github.com/ArthurDEV44/rust-doctor/releases/latest/download/install.sh | bash ``` ### PowerShell 安装程序（Windows） ```powershell irm https://github.com/ArthurDEV44/rust-doctor/releases/latest/download/install.ps1 | iex ``` ### GitHub Releases 从 [GitHub Releases](https://github.com/ArthurDEV44/rust-doctor/releases) 下载预编译的二进制文件。 支持的平台： - `x86_64-unknown-linux-gnu` - `aarch64-unknown-linux-gnu` - `x86_64-apple-darwin` - `aarch64-apple-darwin` - `x86_64-pc-windows-msvc` ## 用法 ```bash # 扫描当前目录 rust-doctor # 扫描特定目录 rust-doctor /path/to/project # 获取 CI 的裸评分 rust-doctor --score # JSON 输出 rust-doctor --json # 仅扫描更改的文件 rust-doctor --diff # 扫描特定分支 rust-doctor --diff main # 在错误时失败 CI rust-doctor --fail-on error # 扫描特定工作区成员 rust-doctor --project core,api # 详细输出，包含文件：行详细信息 rust-doctor --verbose # 安装缺失的外部工具（cargo-deny、cargo-audit 等） rust-doctor --install-deps # 作为 MCP 服务器运行 rust-doctor --mcp # 设置向导 — 自动配置 AI 代理 rust-doctor setup ``` ## 退出代码 rust-doctor 返回不同的退出代码，以便 CI 管道可以将质量门故障与崩溃区分开来： | 代码 | 含义 | |------|---------| | `0` | 成功 — 扫描完成且所有质量门均通过 | | `1` | 设置错误 — MCP 服务器、设置向导或 `--install-deps` 失败 | | `2` | 扫描错误 — 项目发现/编译失败或输出渲染失败 | | `3` | 质量门失败 — 评分低于 `[score] fail_below`，或达到 `--fail-on` 阈值 | 用质量失败阻止构建，而不掩盖崩溃： ```bash rust-doctor --fail-on error if [ $? -eq 3 ]; then echo "质量门失败" exit 1 fi ``` ## AI 代理设置（推荐） 将 rust-doctor 与您的 AI 编码代理集成的最快方法： ```bash npx rust-doctor@latest setup ``` 向导自动检测已安装的代理（Claude Code、Cursor、Windsurf）并让您选择： - **CLI + 技能**（默认）— 安装一个 `SKILL.md`，教您的代理使用具有深度分析功能的 rust-doctor CLI - **MCP 服务器** — 在您的代理配置文件中配置 `rust-doctor --mcp`_stdio 服务器 向导在一个命令中处理检测、配置和验证。对于手动设置，请参见下面的章节。 ## MCP 服务器 rust-doctor 包含一个内置的 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，允许 AI 编码助手直接扫描和分析 Rust 项目。 ### 工具 | 工具 | 描述 | |------|-------------| | `scan` | 扫描 Rust 项目的代码健康问题。返回带有 0-100 健康评分的诊断信息。 | | `score` | 获取 Rust 项目的健康评分（0-100）为单个整数。 | | `explain_rule` | 获取规则的详细解释：它检查什么，为什么重要，以及如何修复违规。 | | `list_rules` | 列出所有可用的规则及其类别和严重性。 | 所有工具都是只读的（`readOnlyHint: true`）。 ### 提示 | 提示 | 描述 | |--------|-------------| | `deep-audit` | 全面的 6 阶段专家审计：代码库探索、静态分析、深度代码审查（51 项检查清单）、最佳实践研究、综合报告和补救选择（实施所有 / 生成 PRD / 手动）。 | | `health-check` | 快速扫描 + 优先级补救计划（P0-P3）+ 修复工作流。 | ### Claude Code **自动设置（推荐）：** ```bash rust-doctor setup # 检测 Claude Code 并配置 MCP 或安装技能 ``` **或一键式 MCP 安装：** ```bash claude mcp add --transport stdio rust-doctor -- npx -y rust-doctor --mcp ``` **或通过 Claude Code 插件： ``` /plugin install rust-doctor@ArthurDEV44/rust-doctor ``` **或手动添加到您的 `~/.claude/settings.json`：** ```json { "mcpServers": { "rust-doctor": { "command": "rust-doctor", "args": ["--mcp"] } } } ``` **或通过 `.mcp.json` 与您的团队共享（提交到 git）：** ```json { "mcpServers": { "rust-doctor": { "command": "npx", "args": ["-y", "rust-doctor", "--mcp"] } } } ``` ### Cursor 添加到您的 `.cursor/mcp.json：` ```json { "mcpServers": { "rust-doctor": { "command": "npx", "args": ["-y", "rust-doctor", "--mcp"] } } } ``` ### VS Code 添加到您的 `.vscode/settings.json：` ```json { "mcp": { "servers": { "rust-doctor": { "type": "stdio", "command": "npx", "args": ["-y", "rust-doctor", "--mcp"] } } } } ``` ### Windsurf 添加到您的 `~/.codeium/windsurf/mcp_config.json：` ```json { "mcpServers": { "rust-doctor": { "command": "npx", "args": ["-y", "rust-doctor", "--mcp"] } } } ``` ### 其他 MCP 客户端 rust-doctor 使用_stdio传输。任何支持_stdio的MCP客户端都可以通过运行`rust-doctor --mcp`连接。 使用 rmcp v1.x（官方 Rust MCP SDK）构建。 ## Claude Code 技能（无需 MCP） 如果您更喜欢斜杠命令而非 MCP 服务器，rust-doctor 附带了一个 Claude Code 技能。 **自动安装（推荐）：** ```bash rust-doctor setup # 选择“CLI + 技能”，选择 Claude Code ``` **或通过 npx： ```bash npx skills add https://github.com/ArthurDEV44/rust-doctor --skill rust-doctor ``` **或手动复制： ```bash cp -r skills/rust-doctor/ ~/.claude/skills/rust-doctor/ ``` **用法： ``` /rust-doctor # 扫描当前项目 /rust-doctor --diff # 仅扫描更改的文件 /rust-doctor --fix # 扫描 + 应用修复 /rust-doctor --plan # 扫描 + 补救计划 /rust-doctor src/ # 扫描特定目录 ``` 该技能在后台运行 `rust-doctor` CLI，解析输出，按优先级分类发现结果，并提供带有前后代码的可行修复指导。 ## GitHub Actions ```yaml - uses: ArthurDEV44/rust-doctor@v1 with: token: ${{ secrets.GITHUB_TOKEN }} fail-on: warning ``` 该操作发布一个 PR 评论，包含健康评分、错误/警告计数和顶级诊断信息。 ## 配置 在项目根目录中创建一个 `rust-doctor.toml`，或在 `Cargo.toml` 中添加 `[package.metadata.rust-doctor]`： ```toml # rust-doctor.toml verbose = false fail_on = "none" [ignore] rules = ["excessive-clone", "string-from-literal"] files = ["**/generated/**", "tests/**"] ``` CLI 标志覆盖配置文件值。 ## 内联抑制 ```rust // rust-doctor-disable-next-line unwrap-in-production let value = some_option.unwrap(); let x = risky_call(); // rust-doctor-disable-line ``` ## 规则 ### 自定义 AST 规则（19 条规则）— 启发式 这些规则仅分析语法树（通过 `syn`）：无类型解析，无宏展开。它们运行速度快，但离线运行，但会发出**启发式** 信号，而不是类型检查的裁决。发现结果在 `--json` 和 SARIF 输出中标记为 `heuristic`，在终端中标记为 `~heuristic`。标记为 ⚠ 的规则具有已知的结构盲点（见下文）。 | 类别 | 规则 | 严重性 | |----------|------|----------| | 错误处理 | `unwrap-in-production` ⚠ | 警告 | | 错误处理 | `panic-in-library` | 错误 | | 错误处理 | `box-dyn-error-in-public-api` | 警告 | | 错误处理 | `result-unit-error` | 警告 | | 性能 | `excessive-clone` | 警告 | | 性能 | `string-from-literal` | 信息 | | 性能 | `collect-then-iterate` | 警告 | | 性能 | `large-enum-variant` ⚠ | 警告 | | 性能 | `unnecessary-allocation` | 警告 | | 架构 | `high-cyclomatic-complexity` | 警告 | | 安全 | `hardcoded-secrets` | 错误 | | 安全 | `unsafe-block-audit` | 警告 | | 安全 | `sql-injection-risk` ⚠ | 错误 | | 异步 | `blocking-in-async` ⚠ | 错误 | | 异步 | `block-on-in-async` | 错误 | | 框架 | `tokio-main-missing` | 错误 | | 框架 | `tokio-spawn-without-move` | 错误 | | 框架 | `axum-handler-not-async` | 警告 | | 框架 | `actix-blocking-handler` | 警告 | #### 已知启发式限制（⚠） 由于这些规则没有类型信息，它们有已知的盲点。它们仍然值得关注，但发现结果是一个提示，而不是一个确认的缺陷： - `unwrap-in-production` — 语法匹配 `.unwrap()`/`.expect()`；无法分辨一个可证明的无损解包和一个有风险的解包。 - `large-enum-variant` — 计算变体的字段数，而不是字节大小；几个宽类型字段可以抵消许多小字段。 - `blocking-in-async` — 按名称标记已知的阻塞调用在异步函数内部；无法跟随调用到其他函数或解析别名导入。 - `sql-injection-risk` — 启发式地标记通过字符串构建的查询；无法确认插值的值实际上是未经信任的输入。 ### Clippy Lints（75+ 条规则）— 类型感知 rust-doctor 以谨慎、苗圃和货物 lint 组运行 `cargo clippy`。75+ 条 lint 具有明确的类别和严重性覆盖，涵盖：错误处理、性能、安全、正确性、架构、货物、异步、样式。不同于上述自定义规则，clippy 解析编译器类型，因此其发现结果更具权威性 — 它们 **不** 被标记为启发式。 ### 外部工具（可选，自动检测） 这些工具是可选的 — rust-doctor 优雅地跳过任何缺失的工具，并显示跳过了哪些工具。运行 `rust-doctor --install-deps` 一次安装所有工具。 | 工具 | 安装 | 用途 | |------|---------|-------------| | clippy | `rustup component add clippy` | 700+ lint 检查 | | cargo-deny | `cargo install cargo-deny` | 供应链检查（顾问、许可证、禁止） | | cargo-audit | `cargo install cargo-audit` | CVE 漏洞扫描 | | cargo-geiger | `cargo install cargo-geiger` | 依赖树中不安全代码审计 | | cargo-machete | `cargo install cargo-machete` | 未使用的依赖检测 | | cargo-semver-checks | `cargo install cargo-semver-checks` | Semver 违规检测 | ## 库使用 rust-doctor 可作为库 crate 使用： ```rust use std::path::Path; // 发现项目（找到 Cargo.toml，加载配置） let (dir, info, config) = rust_doctor::discovery::bootstrap_project( Path::new("/path/to/project"), false, )?; // 用默认配置解析配置 let resolved = rust_doctor::config::resolve_config_defaults(config.as_ref()); // 运行扫描 let result = rust_doctor::scan::scan_project(&info, &resolved, false, &[], true)?; println!("评分：{}/100 ({})", result.score, result.score_label); ``` 完整的 API 文档位于 [docs.rs/rust-doctor](https://docs.rs/rust-doctor)。 ## 评分计算 **将 0-100 的评分视为指南，而不是温度计。** 它指向最弱的维度；它不是精确的测量。每个维度的评分（终端框中显示，在 `--json` 中）带有真正的信号 — 它们告诉您 *在哪里* 采取行动。 ### 计算方式 该评分是跨五个加权维度的加权平均值： | 维度 | 权重 | 涵盖内容 | |-----------|--------|--------| | 安全 | ×2.0 | 安全规则（硬编码秘密、不安全、SQL 注入） | | 可靠性 | ×1.5 | 正确性、错误处理、异步、框架 | | 可维护性 | ×1.0 | 架构、样式 | | 性能 | ×1.0 | 性能 | | 依赖 | ×1.0 | 货物、依赖、咨询发现（RUSTSEC / cargo-deny） | 每个维度从 100 开始，并根据 **唯一规则** 违反情况而损失积分，按严重程度加权： `维度 = 100 − (唯一错误规则 × 1.5) − (唯一警告规则 × 0.75) − (唯一信息规则 × 0.25)` 维度被限制在 `[0, 100]` 内，整体评分是五个维度的加权平均值，也限制在 `[0, 100]` 内。 该评分计算唯一规则，而不是出现次数 — 修复一个 `.unwrap()` 不会移动它，但删除最后一个 `.unwrap()` 会使惩罚完全消失。 | 评分 | 标签 | 医生 | |-------|-------|--------| | 75–100 | 优秀 | ◠ ◠ | | 50–74 | 需要改进 | • • | | 0–49 | 严重 | x x | ### 已知限制 - **维度饱和。** 惩罚是线性的，地板是 0，所以一旦一个维度积累了大约 67 个不同的错误严重性规则（`100 ÷ 1.5`），它就会停留在 0，而该维度中进一步的不同规则不再改变数字 — 在这一点上，它是指向性的，而不是成比例的。 - **启发式输入。** 自定义 AST 规则仅限于 `syn`（无类型，无宏展开），因此部分输入评分是启发式的 — 参见 [规则](#rules)。Clippy 和外部工具发现是类型感知的。评分目前并不权衡启发式与类型感知发现的不同。 - **手动调整的权重。** 维度权重和严重性惩罚是刻意的，但并非经验性校准；谨慎对待跨项目评分比较。 - **空项目。** 没有 Rust 源文件的目录得分为 100 并发出“未找到 Rust 源文件”的消息 — 预期，而不是健康证明。 ## 贡献 欢迎贡献。阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发设置、PR 之前要运行的 CI 网关（`cargo fmt`、`cargo clippy`、`cargo test`）和编写新规则指南。通过参与，您同意 [行为准则](CODE_OF_CONDUCT.md)。有关安全问题，请遵循 [安全政策](SECURITY.md) — 请不要公开报告安全问题。 ## 许可证 根据以下任一许可： - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) 或 <http://www.apache.org/licenses/LICENSE-2.0>) - MIT 许可证 ([LICENSE-MIT](LICENSE-MIT) 或 <http://opensource.org/licenses/MIT>) 在您的选择下。 除非您明确声明，否则任何有意提交给作品的贡献，依照 Apache-2.0 许可证，将被双重许可，如上所述，且不附加任何额外条款或条件。