culprit 是一个面向智能体驱动开发的根因分析工具，目标是让编码智能体在提交之前，能够找出是什么引入了 bug，并验证自己的修复是否完整。
用途
编码智能体虽然可以自己翻 git 历史找到问题，但它不会每次都在上面花十几次工具调用，也不一定会在提交前停下来检查刚改的辅助函数是否还有其他调用方。culprit 把这两件事变成一次确定性的调用，并返回结构化的 JSON 供智能体直接使用。它的定位是智能体的加速器，而不是替代品，也不是比智能体更聪明的 blame 工具。
主要能力
- 即时：不运行测试、不做 bisect。基准测试显示智能体工具调用减少 41%。
- 只读且离线：不会写入仓库或 PR，无需 API Key，无需网络。
- MCP 原生：通过 stdio 提供 11 个工具，已上架官方 MCP 注册表，并有一键插件。
- 语言无关：嫌疑提交分析适用于任何 git 可用的地方；爆炸半径分析支持 12 个语言家族。
- verify_fix 预提交门禁：在提交前对智能体自己的 diff 运行，返回 complete（没有遗留未改动的调用点）、partial（漏掉了一个）或 risky（风险高）等 verdict，并给出 untouched_references（仍在使用被修改符号的具体文件）、skipped_symbols、adds_test、notes 等信息。循环直到 complete 再提交。
- HTML 报告：--html 写出一个自包含文件，无需 CDN，可离线打开，开头呈现 verdict 与风险因素，以及首要嫌疑提交和 bug 存活时长，并重建 bug 产生的过程：每个触碰过问题行的提交，从创建到破坏（红色，附精确 diff）再到修复（绿色）。
- 可选 bisect 确认：--bisect "<cmd>" 在一次性 git worktree 中运行真实 bisect，不触碰你的工作副本。当第一个失败提交与嫌疑提交匹配时，报告会标记为 git bisect 确认。
- CI 门禁：仅通过退出码体现风险，不写 PR 评论、不写入。
使用方式
需要 Python 3.10+ 和 uv 运行 MCP 服务器；CLI 可在 3.9+ 运行。
Claude Code 插件会安装 MCP 服务器以及一个告诉智能体何时使用它的技能。支持任何 MCP 客户端，如 Cursor、Windsurf、VS Code、Codex CLI、Zed、Continue、Cline、Amazon Q、Goose。也可使用 CLI，无需智能体。
基准复现命令：python benchmarks/run.py，它会克隆仓库并对每个案例评分。
CI 配置：将 examples/github-actions/culprit-pr.yml 复制到 .github/workflows/ 中。
基础分支解析顺序为：--base 标志、CULPRIT_BASE 环境变量、.culprit.toml（base = "origin/main"）、最后是 HEAD~1。--last 强制使用最新提交视图。
PR 标题和标签在存在 GitHub CLI 时使用它，否则对公共仓库使用未认证的 REST API（可设置 GITHUB_TOKEN 或 GITLAB_TOKEN 提高限额）。深链接覆盖 GitHub、GitLab、Bitbucket、Gitea。
准确性说明
在 50 个真实回归案例上做了基准测试，其中 25 个来自 git、25 个来自 systemd，引入提交由每个修复的 Fixes: trailer 确认（作者验证的 ground truth）。仅给定修复提交，culprit 通过把被移除的行归因来排序引入 bug 的提交。
对 10 个回归案例的对比测试显示：智能体在准确性上胜出，culprit 并不会让它更准确。culprit 的价值在于用大约一半的步骤完成调查，每次调查减少约 8000 token。10 个案例中工具调用全部下降，7 个案例 token 下降。最难的案例中，单独智能体需要 42 次工具调用和 124k token，配合 culprit 则为 16 次调用和 84k token。这些节省已经扣除了阅读 culprit 输出的开销。culprit 自身运行是一次确定性调用，无模型，不到一秒。
适用场景
- 编码智能体在提交前验证修复完整性。
- CI 中作为风险门禁。
- 对大型 C 代码库等未见过的代码库进行离线根因分析。
- 跨语言代码库的改动爆炸半径分析。
限制
- 对比测试样本为 n=10，且该切片比完整的 50 个案例更容易。
- 准确性上不优于使用 git 的智能体，定位是加速器而非替代。
- 可选 LLM 叙述是唯一非确定性步骤，被隔离在适配器之后，因此引擎自身不需要 API Key。
- MCP 服务器需要 Python 3.10+ 和 uv；CLI 需要 3.9+。
