用途
DiffContext 是一个面向 LLM 编程智能体的上下文编译器。当你要求助手修改一个 5 万行项目中的某个函数时，通常面临三种糟糕选择：粘贴整个仓库（放不下，且模型在超大上下文中表现变差）、只粘贴那一个函数（模型会破坏它从未见过的三个调用方）、或者用名字 grep（grep 找不到重写它的子类，也找不到通过 functools.partial 接收它的处理器）。DiffContext 是第四种选择：将仓库一次性解析为真实的依赖图，然后针对任意变更选出少数真正重要的函数，并将它们打包成最小可用提示。
它面向将 LLM 接入真实代码库的人群——智能体循环、PR 审查机器人、CI 检查——即在必须决定提示中放什么、而仓库太大无法整体发送的场景。
主要能力
- 给定 Python 仓库和一次变更（git diff、分支或单个函数名），返回完成变更所需的函数集合，包括会破坏的调用方、重写该函数的子类、覆盖它的测试。
- 将选出的代码适配到指定 token 预算内，并告知模型省略了什么。
- 自我评估：通过
diffcontext verify --from-history 20 --calibrate从仓库 git 历史挖掘测试用例，对检索进行评分，当工具不适合你的仓库时打印 NULL RESULT 而非装饰性数字。 - 检索质量基于 git 历史挖掘的真实共同变更对衡量，并在每次推送时作为 CI 门禁重跑，防止质量静默退化。
- 可作为库使用，提供增量 API（
idx.update([...])）、结构化输出和可插拔分词器，详见 docs/ARCHITECTURE.md。 - 提供 MCP 集成（Claude Code / Cursor / Windsurf），配置见 docs/MCP.md；提供 FastAPI 服务与 Web UI（diffcontext-service/）；提供检索管道追踪（observability/）。
使用方式
无运行时依赖，支持 Python 3.9+。
MCP 集成（Claude Code / Cursor / Windsurf）：参见 docs/MCP.md 获取服务器配置。
从源码安装用于开发：（此处安装命令资料未完整提供，暂未提供具体命令）。
更多命令见 USAGE.md。生产配方见 docs/USE_CASES.md。
自我评估：不要相信其基准测试，运行你自己的（2 分钟）：
diffcontext verify --from-history 20 --calibrate
该命令从你的仓库 git 历史挖掘测试用例，对检索进行评分，当工具不适合你的仓库时打印 NULL RESULT 而非装饰性数字。
作为库使用：增量 API（idx.update([...])）、结构化输出、可插拔分词器见 docs/ARCHITECTURE.md。
适用场景
- 将 LLM 接入真实代码库：智能体循环、PR 审查机器人、CI 检查。
- 需要在提示中只放入与变更相关的代码，同时受 token 预算约束。
- Python 项目的代码上下文选择与打包。
限制
- 不是代码生成器。它选择并打包上下文；模型编写代码。
- 不是精度优先。默认 top-k 下平均精度低于 0.1。若按 token 付费，可使用
--cutoff gap。 - 尚未支持多语言。完全支持 Python。TypeScript/JS（ESM）为工作原型；CommonJS 是已测量的失败模式。
- 不能替代阅读代码。静态分析有盲点，详见下文与 docs/BENCHMARKS.md。
- 静态分析存在上限：没有调用关系的主题兄弟函数、跨子系统的概念链接（所有方法得分 0/20）、动态分派是已测量的盲点。
- 当心存疑虑时，在完全信任“未找到调用方”之前，先运行
grep -rn "function_name(" --include="*.py" .。
效果说明（资料中的测量结果）
在 128 个 ContextBench Python 任务上，由各仓库自己的测试套件判定（无 LLM-as-judge），上下文大致使 pass@1 翻四倍：5.5% → 25.8%，精确 McNemar p < 0.0001。两个限定条件均见于 benchmarks/contextbench/RESULTS.md §6：(a) 提供给各组的种子函数是 oracle——从黄金补丁中提取——因此这衡量的是“给定正确本地化，上下文质量是否重要”，而非端到端问题解决（本地化对所有组免费提供）；(b) 128 个有效任务中有 121 个是 django，因此这很大程度上是 django 结果。诚实的伴生结论：三种上下文变体（default / gap / depboost）在统计上彼此无法区分，p = 0.36–0.81。胜利在于有上下文对无上下文，而非这个选择器对那个选择器。
检索质量基于 701 个真实提交、跨 9 个 Python 仓库测量，并在每次推送时作为 CI 门禁重跑。在相同 token 预算下与 grep 对比，grep 在超过 4k token 后召回率停在 0.215，而 DiffContext 在 8k 时达到 0.576（2.7 倍）。诚实的另一面：默认 top-k 下平均精度低于 0.1——大多数检索到的符号是支持性上下文，而非确切的共同变更集合。--cutoff gap 在最大得分下降处截断，以约 30% 召回代价换取约 4 倍精度（共同变更基准；在 ContextBench 上为 2.2 倍 / 约 14%）。
作者审计了自己的基准，三项声明未通过：校准——唯一可引用的数字（r=0.274, n≈25）是在受污染索引上测量的，在 n=1,080 干净重测后旧分数得到 r=0.016（p=0.60）：完全没有关系；通过向“不知道”收缩修复 → r=0.287（p=0.0001），是排序信号而非概率。混合权重——发布的 [0.5, 0.35, 0.15] 未通过留一仓库测试；现在为 [0.3, 0.5, 0.2]。密集基线——TF-IDF 替代品夸大了密集检索（0.664，5/5 击败 BM25）；真正的 MiniLM 编码器得分 0.597，仅 2/5 击败 BM25。完整记录见 docs/auditing-my-own-benchmark.md，原始报告见 benchmarks/RIGOR_REPORT_2026-07.md。
文档
- 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 门禁、适配器开发
