夜雨聆风摘要：code-review-graph 用 Tree-sitter、知识图谱和 MCP，让 AI 只读与当前问题相关的代码。它本周登上 GitHub Trending，也把自己的局限写得很清楚。
过去一年，AI 编程工具越来越会写代码，但在真正的大项目里，一个更朴素的问题反复出现：它到底该读什么？
为了回答“这个改动会影响哪里”，Agent 往往先搜索关键词，再打开一批文件，接着沿着 import、函数调用和测试继续追。下一轮对话，它可能又从头来一遍。模型并不一定变笨了，真正稀缺的是上下文窗口、等待时间，以及人类判断它有没有漏读关键路径的耐心。
这周的 GitHub Trending 上，一个叫 code-review-graph 的项目快速上升。它的思路很直接：不要每次都让 AI 临时翻仓库，先把代码结构整理成一张可以持续更新的图。
热度口径说明：北京时间 2026 年 7 月 25 日 22:33 查询 GitHub Trending「This week」时，页面显示该项目获得 6,565 stars this week、总 Star 约 26.3k。GitHub 没有说明该数字是否严格按北京时间自然周切分，因此本文把它视为周榜快照，不当作精确的周一零点至今净增。
它解决的不是“生成代码”，而是“少读错代码”
code-review-graph 由 AI/ML 工程师 Tirth Kanani（GitHub：tirth8205） 创建，采用 MIT 许可证。项目当前版本为 2.3.7，要求 Python 3.10 及以上。
它不提供一个新的大模型，也不试图替代 IDE。它更像是给 Codex、Claude Code、Cursor、Gemini CLI 等工具加一层“仓库地图”：函数在哪里、谁调用了谁、某个类被哪些模块依赖、一个改动可能波及哪些执行流、相关测试在哪里。
区别在于，这张地图不是每次临时搜索出来的，而是持久保存在本地。
原创示意图：左边是反复读取大量文件，右边是从结构图中挑出与问题有关的节点。
它是怎么工作的？
第一步是解析。项目使用 Tree-sitter 读取多种语言的抽象语法树，识别文件、函数、类、导入、调用和测试等结构。它覆盖 Python、JavaScript/TypeScript、Go、Rust、Java、C/C++、C#、PHP、Kotlin、Swift、SQL、Terraform、Jupyter Notebook 等常见类型，也允许通过配置补充语言映射。
第二步是建图。代码实体变成节点，调用、导入、继承、测试等关系变成边。项目还会寻找执行流、通过 Leiden 算法聚类相关代码，并把结果写入仓库里的 .code-review-graph/graph.db。底层是 SQLite，不需要额外部署图数据库。
第三步是增量更新。首次构建后，后续只重新解析变化的文件；项目提供 watch 模式、Git hooks 和多仓库守护进程，让这张图跟着代码一起变化。
第四步是把图交给 AI。项目通过 MCP 暴露 30 个工具，例如最小上下文、影响半径、调用关系、受影响执行流、测试缺口和架构热点。AI 不必把整个仓库塞进提示词，而是先问图：“与这个改动最相关的节点有哪些？”
原创示意图：仓库经语法解析形成 AST 和本地图谱，再通过窄接口把相关上下文交给 AI。
真正吸引人的地方：它没有把最佳案例当平均水平
项目 README 给出的 headline 是：在 6 个真实开源仓库的样本问题上，相比“读取整个代码库”的上限基线，图查询每个问题的 token 中位缩减约 82 倍，范围从 38 倍到 528 倍。
528 倍很醒目，但维护者主动说明，那只是 FastAPI 这个最大样本上的最佳情况，不是典型结果。更重要的是，“读取整个仓库”本身也是一个偏宽松的对照：成熟 Agent 通常会先 grep，再读少量文件。因此项目又加入了更现实的 grep-and-read 基线，并把固定仓库 SHA、固定随机种子和复现实验写进文档。
这并不能证明它在所有仓库里都能省 82 倍上下文，但至少说明维护者愿意把营销数字拆开，让读者看到测量对象和边界。
怎么体验？
最短路径只有三步：
pip install code-review-graph code-review-graph install --platform codex code-review-graph buildinstall 会写入对应 AI 工具的 MCP 配置，并在支持的平台安装 hooks、skills 或规则文件；完成后需要重启编辑器或工具。若不想一次配置所有平台，可以像上面那样指定 --platform codex、cursor 或 claude-code。
构建完成后，可以先运行 code-review-graph status 检查图规模，再用 detect-changes --brief 看当前改动的风险、相关函数、测试和上下文节省估算。它也能导出交互式 HTML、SVG、GraphML、Obsidian vault 或 Neo4j Cypher，用来做架构梳理和新人入门。
为什么“本地优先”很重要？
根据项目的安全策略，正常的建图和评审流程只读取已校验仓库根目录内的文件，数据写入本地 SQLite，默认不发起网络请求。对于不能把商业代码上传到外部服务的团队，这是一个实际优势。
但“本地优先”不等于永远离线。语义搜索可选用本地 sentence-transformers，也能连接 OpenAI 兼容接口、Google Gemini 或 MiniMax。开启云嵌入时，项目会发送由标识符、函数签名、结构上下文和受限的注释摘要组成的源代码衍生文本；官方称不发送函数体，但它仍可能包含敏感信息，并产生 API 费用。企业仓库应先审查配置和数据边界。
原创示意图：常规路径留在本地；云嵌入属于需要显式选择的可选路径。
哪些人适合用？
它最适合三类场景：一是模块多、调用链长的中大型仓库；二是经常做 PR 评审、影响分析和测试补齐的团队；三是同时使用多个 AI 编程工具，希望共享同一份仓库结构索引的人。
它也适合接手陌生项目的人。相比让 AI 泛泛总结目录，直接询问架构社区、中心节点、跨模块桥接点和关键执行流，往往更接近“这个系统为什么这样组织”。
但别把它当成静态分析的终局
项目官方列出的弱点值得认真看：小仓库或单文件改动时，图的结构元数据可能比直接读文件更重；搜索 MRR 约 0.35，排序仍需改进；流程检测召回率约 33%，目前对 Python 和 PHP/Laravel 的框架模式更强，JavaScript 与 Go 仍需完善；影响分析为了少漏报，会在大型依赖图中产生误报。
此外，它的 Python 包状态仍标记为 Beta。安装器会修改 MCP 配置、hooks 和平台规则，最好先在非关键仓库试用，并在变更前备份相关配置。项目还明确表示 2.3 之前的版本不再受支持，使用时应保持在受支持版本并关注安全更新。
原创示意图：大仓库的多跳问题更能体现图的价值；小改动可能付出不必要的建图开销。
总结
code-review-graph 最值得关注的，不是又给 AI 编程工具加了几十个命令，而是改变了“上下文从哪里来”的方式：从每次临时翻文件，变成维护一份可查询、可增量更新的结构记忆。
这条路线不会替代 grep、LSP、测试和人工评审。对一次性的简单问题，直接搜索更快；对需要跨模块追踪调用、影响和测试的大仓库，图才可能真正省下上下文。
如果你正在抱怨 AI “总是读错文件”，不妨先别换模型。也许它缺的不是更强的大脑，而是一张更可靠的地图。
官方仓库：https://github.com/tirth8205/code-review-graph