DiffContext

只向 AI 编程助手展示它正在进行的更改所真正相关的代码。

[)(https://github.com/trakshan-mishra/Diffontext/actions) !License: MIT LICENSE

DiffContext 是一个面向 LLM 编码代理的上下文编译器。给它一个 Python 仓库和一个更改——一个 git diff、一个分支或一个函数名称——它就会返回模型安全地做出该更改真正需要的一小组函数：会出错的调用方、覆盖它的子类、以及与它相关的测试。它会配您拥有的任何 token 预算，并告诉模型它必须丢弃什么。

它的构建目标是那些将 LLM 接入真实代码库的人——代理循环、PR 审查机器人、CI 检查——凡是需要决定要把什么代码放入提示词而仓库又太大无法全部发送的场景。

而且它能自我评估：将工具指向你的仓库，它会挖掘你的 git 历史，针对真实共同变更对运行检索，并在不符合时打印 NULL RESULT——而这正是该功能。

这个问题

假设你让助手修改一个 50,000 行项目中的某个函数，你有三种糟糕的选择：粘贴整个仓库（它放不下，而且模型在非常长的上下文中表现更差），只粘贴该函数（模型将破坏它从未见过的三个调用方），或通过名称搜索（grep 无法找到覆盖其行为的子类，或通过 functools.partial 接收它的处理函数——无论给多少预算，其检索召回率都会停滞）。

DiffContext 是第四种选择。将仓库一当性解析为真正的依赖图，然后针对任意更改选择真正重要的少数函数，并将它们打包到最小有效的提示词中。

git change ──► changed functions ──► hybrid retrieval ──► token budget ──► LLM-ready context
                                      graph ∪ BM25 ∪ file      top-k + tokens

Related MCP server: Serena

安装

pip install diffcontext

零运行依赖项，Python 39+。

用于 MCP 集成（Claude Code / Cursor / Windsurf）：

pip install "diffcontext[mcp]"

配置参见 docs/MCP.md。

从源代码进行开发：

git clone https://github.com/trakshan-mishra/Diffcontext.git
cd Diffcontext && pip install -e .

快速开始

diffcontext index /path/to/project              # cold: seconds; warm: ~0.02s
diffcontext compile --ref HEAD~1 --max-tokens 8000
diffcontext verify --from-history 20 --calibrate

更多命令：USAGE.md。生产环境配方：docs/USE_CASES.md。

不要相信我们的基准——跑你自己的（2分钟）

diffcontext verify --from-history 20 --calibrate 从 你的 仓库的 git 历史中挖掘真正案例并评估检索质量；不匹配时打印 NULL RESULT，而非返回一个没有意义（无意义）数字。正如提示的：发现“不匹配”本身就是特性。

它真的让模型变更好吗？

是的——通过端到端衡量，而非间接。在由每个仓库自己的测试套件（而非 LLM 判定）判定的 128 个 ContextBench Python 任务上，传递率约增加一倍：5.5%→25.8%，exact McNemar p < 0.0001。

另外有两个限定，一书于 benchmarks/contextbench/RESULTS.md §6：(a) 给每个参与组的种子函数是 oracle（来自正确答案补丁）——因此检验的是“给定正确的本地化，上下文质量是否重要？”，而非端到端任务解决能力（本地化对每个组是不免费的）；(b) 128 个有效任务中有 121 个是 django，所以这基本上是 django 的结果。“”

诚实的对照同样是可靠：三种上下文变体（default / gap / depboost）在统计上是不可区分的，p=0.36–0.81。最大优势是“有上下文 vs 没有上下文”，而不是“这个选择器 vs 那个选择器”。完整结果：benchmarks/contextbench/RESULTS.md。

这不是什么

• 不是代码生成器。它选择与打包上下文，由模型写代码。

• 不是说优先精度。它建的网很广——默认 top-k 下平均精度在 0.1 以下。若你按 token 付费，则可 --cutoff gap。

• 还不支持多语言。Python 已完全支持。TypeScript/JS (ESM) 是可用原型，CommonJS 是已测出失败模式。

• .cont not a replacement for reading the code. 静态分析有盲区，见下文和 docs/BENCHMARKS.md。

检索质量（一个个测出，而不是声称）

Ground truth 由 git 历史挖掘——*开发者在同一提交中更改了these这些函数；给定`` s不依靠一个，能试探出其他吗？已在 9 个 Python 仓库的 701 个真实提交上测量震，每次 push 时都会在 CI 中重新运行，因此质量不能悄悄衰退。

对真实 co-change 对按提交进行的命中 / 召回，混合检索：

*验证性仓库，从未用于调参。完整表表（覆盖全部 9 个仓库）：benchmarks/README.md。

头-向—vs 对等预算下：grep 在 4k tokens 之后召回停滞在 0.215，而 DiffContext 在8k 达到0.576（2.7×）。诚实的另一面：默认 top-k 下平均 拼精度低于 0.1 的符节号主要是支持性上下文，非准确 co-赶change集。--cutoff gap 在最大得分跳跃处截断，精度大约 4×，仍回归约 30%（co-赶 change evaluate；在 Co撞bench 上 2.2× /约 14%）。

我审查了我自己的benchmark、然后三个声称受到了危害

2026 年 7 月一项审查针对评估而不是工具本身。三个已发布数字未通过：

• 校准——唯一可引用的数字（r=0.274， n≈25）测量在不污染索引上施加。重新测量 n=1,080 后，旧得 0.016（p=0.低），即无关。通过向“不确定”收缩修后；得到 r=0.287 (p=0.0001) 它是排名信号，不是概率。

• 混合权重}——当前 [0.5,0.35,0.15] 未通过留仓库验证； 每个除以获得组合：新的偏ep 视。修复 （现在为 [0.3,0.5,0.2]）。

• Dense 基线——TF-IDF 替代者篡改性的；Dese 检索 (0.6656，5/5 全面超过 BM25)。基于真MiniLM 编码器只有 0.597，且只 2/5 次超过。两点先前结论已经更正。

完整说明：docs/auditing-my-own-benchmark.md · 原始报告：benchmarks/RIGOR_REPORT_2026-07.md。

用作库

from diffcontext.pipeline import index_repository, analyze_impact, compile

idx = index_repository("/path/to/repo")
impact = analyze_impact(idx, ["./src/auth.py:validate_jwt"])
ctx = compile(idx, impact, max_tokens=8000, top_k=20)
print(ctx.text)  # paste-ready, meta-header discloses what was dropped

增量 API（idx.update([...])）、结构化输出、可插拔 tokenizer：docs/ARCHITECTURE.md。

语言支持

已知限制（实测，而非猜测）

静态分析有一上限：不存在调用关系的同主题兄弟代码、跨子系统的概念连接（比如所有方法得分 5/20）、以及动态分发，反映出这些是衡量出来的盲区——在 docs/BENCHMARKS.md 中有详细列出。 有疑问处，先运行 grep -rn "function_name(" --include="*.py" . 之后再完全信任“没有调用方”的结论。

更多

• docs/ARCHITECTURE.md — 流水线、模块图、代理 API

• docs/BENCHMARKS.md — 全部数字、下游 pass@1、限制

• docs/MCP.md — Claude Code / Cursor / Windsurf 的 MCP 服务器

• docs/ROADMAP.md — 排序更优先的计划。

• diffcontext-service — FastAPI 服务 + Web UI

• observability — 检索管线追踪

• CONTRIBUTING.md — 设置、CI 检验、适配器开发

许可证

MIT