Riskratchet：用风险棘轮阻止 AI 生成代码拖垮代码库

AI 编程代理越来越擅长写出能编译、能运行、能让自带的测试通过的代码，但它们在另一些事情上仍然薄弱：为新代码补充有意义的测试、注意到一个 30 行的函数悄悄膨胀到 130 行、发现公共 API 暴露了一个在测试中无人调用的函数、或者把一个 if 阶梯重构成了 14 路圈复杂度的怪物。近日在 Hacker News 上亮相的 Python 工具 riskratchet 正是为了解决这类问题。

设计思路：只许下降的风险基线

Riskratchet 的核心理念借鉴了 Rust 生态中 cargo-crap 的「棘轮」做法：当代码的整体风险分数（基于覆盖率缺口、圈复杂度、变更频率、公开接口暴露、代码蔓延等信号计算）相对基线出现增长时，就在 CI 阶段直接失败、阻止合并。换句话说，门槛只能往下调，代码库的风险分数只能越来越低。

作者强调，riskratchet 既不是 cargo-crap 的 Python 移植版，也不是 Cursor 那种「核弹级代码质量审查」代理提示词。它以 CRAP 指标为基础，并叠加了 Python 特有的信号——分支覆盖缺口、文件变更频率、公开 API 暴露面和函数蔓延程度。

工作流与命令

工具可通过 pip 或 uvx 直接使用，配合 pytest 的覆盖率数据工作，典型流程分为四步：

• 用 pytest --cov --cov-report=json:coverage.json 生成覆盖率报告；
• 用 riskratchet baseline 快照当前的风险画像，写入 .riskratchet.json；
• 用 riskratchet scan 查看每个函数的具体风险项；
• 用 riskratchet check 在 CI 中把关，回归即失败。

退出码方面，回归为 1，使用错误为 2，其余情况为 0。对于还没有基线的小项目，工具也提供了 --fail-above N 的绝对阈值模式作为过渡；当同时指定基线和阈值时，以基线为准。

配套脚手架与 GitHub Action

Riskratchet 提供 init 命令，在 pyproject.toml 中写入 [tool.riskratchet] 配置段并打印可粘贴的 CI 片段；带上 --with-baseline 还能一键完成测试与基线创建。doctor 子命令则像一个六项的飞行前自检：能明确指出缺失的路径、格式错误的基线、过期或缺失的覆盖率、缺少 git 历史、未知配置键或非法抑制规则，并对应输出修复命令。

官方还提供 composite GitHub Action（KayhanB21/riskratchet@v0.2.13），无需复制 workflow 文件即可在 PR 中以 PR 评论形式呈现检查结果，并把基线模式与无基线模式统一在同一个 action 里。作者也准备了一个 wrapper 仓库以方便 GitHub Marketplace 检索，底层共享同一份 action.yml。

供应链与典型场景

每个发布版本都附带供应链溯源材料：wheel 的运行时依赖闭包 CycloneDX SBOM、wheel 与 sdist 的签名构建证明，以及基于 Trusted Publishing 的 PEP 740 PyPI 证明，可通过 gh attestation verify 命令验证下载的产物确实来自该仓库。

作者给出的典型场景是：一个用 AI 代理 vibe-coding 了八个月的 FastAPI 后端，测试覆盖率 62%，忽然发现 services/billing.py::reconcile_subscriptions 静悄悄长到了 180 行，还藏着一段自己毫无印象的 11 路 match 语句。装上 riskratchet 跑一遍 scan --top 10，问题函数就会自动浮出水面。