GitHub 热榜这几天反复出现同一类东西：把代码库先做成图，再让模型在图上问、改、搜。vitali87/code-graph-rag 的定位很干脆——Tree-sitter 解析多语言 monorepo，结构进 Memgraph，用统一 schema 做问答和编辑，而不是再丢一整仓文本进向量库。
同类信号并不孤立：早些时候热过的 code-review-graph、Agent Skills 里的结构图思路，都在说同一件事：全库 embedding 太贵也太糊，符号关系才是代码的骨架。
向量 RAG 在代码上哪里别扭
聊天文档可以靠「意思相近」。代码不行。
UserService和注释里的 “user service” 可能向量很近，调用链却毫不相干- 改一个接口，要命的是实现类、测试、生成代码和 CI 配置，不是余弦相似度前 5
- monorepo 里 TS + Go + Python 混部，按文件切块会把 package 边界切碎
你丢 20 个 chunk 给模型，它仍可能编造一个「看起来合理」的 import。图至少能回答：这个符号实际被谁引用、在哪个模块、跨语言边界在哪。
我在 review Agent PR 时最怕的不是文笔，是「删了一个还在被调用的函数」。向量检索几乎帮不上这种活；grep 能找字符串，却对「接口实现」「泛型实例化」「跨语言 FFI」力不从心。结构图站在中间：比全文搜有类型，比人工翻依赖树快。
code-graph-rag 在干什么
图：符号与边构成的代码知识图，而不是碎文本堆
公开描述大致是一条流水线：
- Tree-sitter 抽 AST / 符号
- 写入图数据库（Memgraph）里的统一结构
- 用自然语言查询图：定位、解释、在约束下改代码
重点不是又一个 ChatUI，而是检索单元从「文本块」换成「节点和边」。问「登录失败会经过哪些中间件」，应走调用/依赖边，而不是全文搜 “login”。
我不会在没跑通你仓库的情况下吹它的准确率。更值得抄的是架构：解析器可插拔、图 schema 稳定、编辑路径必须能指回具体 span。任何「只能聊天不能落点到行号」的代码助手，上线后都会变成昂贵的橡皮鸭。
选型时也可以看邻域：有的项目偏 MCP 暴露图查询，有的偏本地索引 + CLI。对团队而言，接口形状（能否 symbol_at / callers_of / impact_of）比明星仓库名字重要。
和「Agent 记忆」怎么拼
前阵子 TencentDB-Agent-Memory 一类项目把 Chat Memory、Skill、Wiki、Code-Graph 拆成资产。图适合放相对稳的结构真相；会话摘要、人设、临时结论放另一层。混在一个向量集合里，过期策略会变成一团浆糊。
务实分层：
| 层 | 存什么 | 失效 |
|---|---|---|
| 结构图 | 符号、文件、依赖、测试归属 | CI / 合并后增量重建 |
| 语义索引 | 设计文档、ADR、注释叙事 | 文档变更时 |
| 会话记忆 | 当前任务、用户偏好 | 短 TTL 或任务结束清 |
Agent 改代码时：先图定位，再小范围读原文，最后生成 diff。跳过图直接「全库 RAG + 开写」，是在烧 token 赌命。
Skill 文件适合写流程（怎么开 PR、怎么跑测试），不适合当符号真相源。有人把半仓 README 塞进 Skill，Agent 倒是「懂规范」了，一问「谁实现了这个接口」仍然瞎编。规范走 Skill，结构走图，叙事走文档索引——三条线别拧成一股。
自己搭时我会守的几条
增量，不要每晚全量烧钱。 按变更文件及其一跳/二跳邻居更新子图。全量扫描留给 schema 升级。 monorepo 夜间全量解析听着踏实，账单和耗时会教训你。
边的类型要少而硬。 imports、calls、implements、tested_by 够用很久。边类型一多，查询会写成散文，没人维护。想加 maybe_related 这种软边之前，先证明硬边不够用。
编辑必须可审计。 图检索给出的应是路径和 span，apply patch 走正常 PR。不要让 Agent 凭「图上的感觉」直接推 main。图可以错，PR 和测试是最后闸门。
评测别只报 answer@k。 加：定位到正确符号的比例、错误 import 率、一次 PR 平均读了多少无关文件。结构检索的价值常体现在「少读了什么」。我们内部若只能加一个指标，我选「无关文件打开数」。
权限与密钥。 图里若含内部路径、服务名、生成代码注释，访问控制和仓库 ACL 对齐。别把「方便 Agent」做成第二条源代码泄露通道。
什么时候别上
- 单仓几千行、一个人维护：grep + 编辑器大纲就够
- 主要是配置和胶水，符号图很稀疏
- 没有 CI 钩子重建索引：图过一周就在撒谎，比没有更糟
- 语言解析器质量极差、大量宏和代码生成：图会系统性地漏边
图是基础设施。没有更新管道，就不要演示给老板看。演示用的静态导出图，三天后就是谎言艺术品。
和 coding agent 默认 Auto Mode 的关系
Claude Code 一类工具走向默认自动执行工具之后，错误上下文的杀伤力被放大。Agent 越勤快，越需要窄而真的检索。code-graph-rag 这类项目热，和「手更长了，眼睛得更尖」是同一波压力。
自动模式下列几条底线仍然值：仓库沙箱、工具白名单、短时凭证、PR 门禁。图检索是底线之上的加速器，不是替代品。没有门禁，更快的定位只意味着更快改错文件。
一周内能做的最小闭环
- 选一个服务边界清晰的子仓，跑通 Tree-sitter → 符号表（哪怕先 SQLite）
- 暴露三个只读查询：
find_symbol、callers、deps - 给 Agent 系统提示：改代码前必须先跑这三个之一
- 合并后增量更新；对比「有图 / 无图」各 10 个真实任务的翻车率
先别上复杂的自然语言改写整文件。定位准了，人写或模型写都更稳。
带走一句： 代码 RAG 的下一阶段不是更大的向量库，是可增量更新的结构图 + 少量原文。热榜项目可以当参考实现；你仓库里真正要建的，是解析、图、失效和 PR 门禁这条闭环。
