culprit

culprit

面向 Agent 驱动开发的根因分析。
你的编码 Agent 能找出引入 Bug 的变更，并在提交前验证自己的修复是否完整。

快速开始 · 工具 · 准确性 · 架构 · MCP 注册表

一次真实运行。修复只修改了 parse_config 的一个调用方，漏掉了另外两个，因此得分为 partial。

为什么 Agent 需要它

Agent 可以翻查 git 历史来找出故障原因，而且很擅长这件事。但它不会每次都可靠地花十几次工具调用来完成这项工作，也不会在提交前停下来检查刚修改的辅助函数是否还有另外三个调用方。culprit 将这两项工作合并为一次确定性调用，返回可供处理的结构化 JSON：

Agent 的问题	culprit 的回答
“是什么引入了这个 Bug？”	按优先级排序的可疑提交、作者意图，以及该变更出现在哪些版本中
“我的修复完整吗？”	verify_fix：遗漏的调用点、是否随版本发布了测试，以及风险等级
“这项改动可能会破坏什么？”	反向导入的依赖项、覆盖这些依赖项的测试，以及高风险共享模块

• ⚡️ 即时响应。 不运行测试，也不执行二分查找。基准测试显示，Agent 的工具调用减少了 41%。
• 🔒 只读且离线。 从不写入你的仓库或 PR。无需 API 密钥，也无需联网。
• 🔌 原生支持 MCP。 通过 stdio 提供 11 个工具，已上架官方 MCP 注册表，另有一条命令即可安装的插件。
• 🗣️ 语言无关。 只要 git 能处理的项目，都能查找可疑变更。影响范围分析支持 12 类语言。

它真的有效吗？

使用 50 个真实回归案例进行基准测试，其中 25 个来自 git，25 个来自 systemd。每个案例的引入提交都可以通过修复提交中的 Fixes: 标记确认（由作者验证的真实情况）。只提供修复提交时，culprit 会对被删除的代码行进行 blame 分析，以便为引入 Bug 的提交排序。

指标	结果
引入提交排在第 1 位	50%（25/50）
引入提交位于前 5 个可疑提交之中	66%（33/50）

该引擎从未见过这些大型 C 代码库，却能确定性地离线运行。运行 python benchmarks/run.py 即可复现，它会克隆这些仓库并评估所有案例。

但 Agent 可以自己运行 git blame

确实如此，而且它很擅长。因此，真正值得探讨的不是 culprit 是否准确，而是它能否胜过或帮助一个拥有 git、但没有 culprit 的 Agent。对同样的 10 个回归问题，分成三组测试，并相互隔离，确保任何一组都无法从修复提交中读取答案：

	仅使用 culprit	仅使用 Agent	Agent + culprit
引入问题的提交排名第 1	80%	90%	90%
引入问题的提交进入前 5	90%	100%	100%
平均工具调用次数	1	14.9	8.8（-41%）
平均消耗 token 数	~0	55,534	47,616（-14%）

Agent 的准确率更高，而 culprit 并不会让它更准确。culprit 的作用是让 Agent 大约用一半的步骤找到答案，每次调查少用约 8,000 个 token。 在 10 个案例中，工具调用次数有 10 个减少，token 数有 7 个减少。最难的案例中，Agent 单独处理需要 42 次工具调用和 124k 个 token，而使用 culprit 时只需 16 次调用和 84k 个 token。

这些节省已扣除读取 culprit 输出的开销，该开销计入第三列。culprit 自身只需一次确定性调用，不使用模型，耗时不到一秒。

因此，culprit 是 Agent 的加速器，而非替代品，也不是比 Agent 更聪明的代码归责工具。方法、注意事项（n=10，且这一组测试比完整的 50 个案例更简单）和复现说明：benchmarks/agent/。

快速开始

Claude Code 插件（安装 MCP 服务及一个指导 Agent 何时使用它的技能）：

/plugin marketplace add noordeen123/culprit
/plugin install culprit@culprit

任意 MCP 客户端（Cursor、Windsurf、VS Code、Codex CLI、Zed、Continue、Cline、Amazon Q、Goose）：

{
  "mcpServers": {
    "culprit": {
      "command": "uvx",
      "args": ["--from", "culprit[mcp]", "culprit-mcp"]
    }
  }
}

CLI，无需 Agent：

uvx culprit                     # run from PyPI on demand
rca --verify-fix patch.diff     # exit 0 if complete, 1 otherwise

MCP 服务需要 Python 3.10+ 和 uv。CLI 可在 3.9+ 上运行。

工具

工具	可回答的问题
analyze	一次调用完成完整 RCA：分类、可疑项或影响范围、风险、测试影响
verify_fix	此差异是否可以安全提交？返回 complete / partial / risky，以及遗漏的调用位置
find_suspects	对引入问题的提交进行排序
check_completeness	查找修复未涉及的已更改符号的调用位置
get_intent	引入问题的提交说明、关联的 PR、引用的问题
get_evolution	通过 git log -L 查看问题代码行按提交划分的历史
get_risk_score	QA 门禁评分（0 到 100，低/中/高）及影响因素
get_blast_radius	功能影响范围：依赖项、覆盖测试、高风险文件
get_test_impact	此更改需要运行的最小测试集
classify_change	判断是 Bug 修复还是功能变更，并提供依据
from_trace	直接根据堆栈跟踪进行 RCA，无需差异或 PR

verify_fix，提交前门禁

Agent 在提交前对自己的差异运行此工具：

• verdict：没有遗漏未触及的调用位置时为 complete，遗漏了调用位置时为 partial，风险较高时为 risky。该判定代表完整性维度；测试覆盖率则是 risk_level 上单独的置信度维度。
• untouched_references：仍在使用已更改符号的确切文件列表。Agent 会前往这些文件并打上补丁。
• skipped_symbols、adds_test、notes：哪些符号因使用范围过广而未检查、是否随更改一并添加了测试，以及后续操作建议。

循环检查，直到结果为 complete，然后提交。这就是整个思路。

CLI 和 CI

rca                            # current branch vs the configured base
rca --last                     # the latest commit only
rca --pr 16786                 # a specific PR (uses the PR's own base)
rca --trace crash.txt          # RCA from a stack trace, no fix or PR needed
rca --verify-fix patch.diff    # check a diff before committing
rca --select-tests             # print the tests to run for this change
rca --html report.html --open  # a single self-contained HTML report
rca --pr 16889 --fail-on high  # exit non-zero when QA risk is high
rca serve --repo /path         # local web UI with a base picker

CI 门禁：仅通过退出代码评估风险，不发布 PR 评论，也不写入任何内容。将 examples/github-actions/culprit-pr.yml 复制到 .github/workflows/：

- run: pip install "culprit>=0.3.0"
- env: { GH_TOKEN: "${{ github.token }}" }
  run: rca --pr ${{ github.event.pull_request.number }} --fail-on high

HTML 报告

--html 会写入一个独立文件。无需 CDN，可离线打开，也可附加到 CI。报告首先给出结论：带有影响因素的 QA 风险评分，以及主要嫌疑提交和 Bug 存续时长。

然后，报告会还原 Bug 是如何产生的。列出所有修改过 Bug 所在代码行的提交，从创建代码行到导致问题的提交（红色，附精确 diff），再到修复提交（绿色）：

展开每个节点即可查看其 diff。查看完整报告。

与 git bisect 的比较

	git bisect	culprit
输入	可靠的失败测试	修复 diff（或堆栈跟踪）
方法	检出提交并运行测试	对修复涉及的代码行执行 blame，并结合 git log -L
速度	几分钟（约运行 log2(N) 次测试）	即时
输出	首个问题提交	嫌疑提交集、意图、生命周期、完整性、风险
置信度	证明	强启发式

--bisect "<cmd>" 会运行真实的 bisect，作为可选的确认环节；操作在临时的 git worktree 中进行，因此绝不会触碰你的工作区。当首个失败提交与 blame 找出的嫌疑提交匹配时，报告会标注为经 git bisect 确认。

架构

输入一个规范化上下文，输出一个结构化 JSON 结果。唯一的非确定性步骤是可选的 LLM 叙述；它通过适配器隔离，因此引擎无需 API 密钥也能运行。

两条流程，共用一个引擎。每个模块只负责写入结果的一部分，因此无论目标来自 gh、REST API、本地 git，还是粘贴的堆栈跟踪，都不会影响处理。完整模块图： docs/ARCHITECTURE.md。

配置

基础分支按以下顺序解析：--base 标记、CULPRIT_BASE、.culprit.toml （base = "origin/main"），最后是 HEAD~1。--last 会强制显示最新提交视图。

如有 GitHub CLI，PR 标题和标签会使用它；否则，公共仓库会使用未经身份验证的 REST API（设置 GITHUB_TOKEN 或 GITLAB_TOKEN 可提高限额）。深层链接支持 GitHub、GitLab、Bitbucket 和 Gitea。影响范围会读取 JS/TS、Python、Go、Java/Kotlin、Ruby、C/C++、C#、PHP、Rust、Scala 和 Swift 中的导入关系。

参与贡献

pip install -e ".[dev]" && pytest

模块图和数据结构：docs/ARCHITECTURE.md。将 MCP 服务发布到注册表：docs/PUBLISHING.md。采用 MIT 许可证。