在一个陌生仓库里找「这个函数被谁调用、这个类继承了什么」,以前我只能 grep 加肉眼看。看一个还行,看一个十几万行的 monorepo,就是纯体力活。
code-graph-rag 干的事是把代码解析成知识图谱,函数、类、模块是节点,调用、导入、继承是边。存进一个嵌入式 SQLite,没有服务器。我装了一遍,建了个小图试试。
先交代我为什么要试它。我手头常要翻别人的仓库,grep 找定义还行,找「谁调用了谁」就得来回搜。如果有个工具能把调用关系建成网,查起来就快。
我的预期不算高。只希望它把我写的 6 个函数和调用关系抓出来,别漏、别错。这个预期后来被验证了。
装出来是 0.1.90
它发布在 PyPI,装的时候要带 extra。treesitter-full 装各语言语法树,ast-grep 管 Ruby、Kotlin 那些结构型语言,semantic 管向量检索。本机是 macOS arm64,Python 3.13.12。
uv venv cgr-venv --python 3.13
UV_HTTP_TIMEOUT=180 uv pip install --python cgr-venv/bin/python "code-graph-rag[treesitter-full,ast-grep,semantic]" --index-url https://pypi.tuna.tsinghua.edu.cn/simple
装完 cgr --version 输出 code-graph-rag version 0.1.90。它带了个原生扩展 cgr-graph-rs,README 说只支持 CPython 3.12 以上,我的 3.13.12 没问题。它还要求 ripgrep,我这台机器没装 rg,不过后面建图时没用到。
cgr index 建图,3 个文件出 14 个节点
我建了个最小 demo 仓库,三个文件。main.py 里 run_pipeline 调 add 和 multiply,report 调 greet,utils 下面两个文件各自定义函数。然后跑离线建图。
cgr index --repo-path /tmp/src1118/demo_repo -o /tmp/src1118/demo_index
跑出来的日志有几行值得记。先是 Successfully loaded python grammar,说明 Tree-sitter 的 Python 语法树加载成功。然后 Found 6 functions/methods in codebase,跟我写的 6 个函数对得上。接着 Emitted 3 verified IMPORTS edges,正好是 main.py 里的三条 import。最后 Flushed 14 unique nodes and 21 unique relationships。
我打开它的 manifest.json 核了一遍。node_labels 有 17 种,Class、Function、Method、Module、Package、ExternalModule、Interface、Enum 这些都在。relationships 有 21 种,CALLS、IMPORTS、DEFINES、OVERRIDES、INHERITS、REFERENCES、RETURNS 这些也在。也就是说,它不是只抓函数名,调用、导入、继承、重写、返回值这些关系全建了边。
这里有个点我想说清楚。它跟 grep 的区别就在这。grep 按文本匹配,它按结构关系连网。你要查「谁调用了这个函数」,grep 只能搜函数名字符串,它直接给你调用的边。这比 grep 强。
建图快,卡在 Docker 那一步
建图是离线的,写成一个 protobuf 索引,很快。但我想走 README 里的交互式路径,cgr start --update-graph 把图写进 SQLite 再问问题,它就报错了。
docker is installed but the daemon is not responding. Start Docker and retry.
我查了原因。semantic 这个 extra 装了向量检索,交互式问问题那步要起 Qdrant 和 Memgraph 的容器。我本机 docker 29.4.0 装了,但 daemon 没起。这条报错说明了一件事:README 说的「无需 Docker」,只对离线建图成立,交互式语义检索那半边还是得靠容器。
纯结构查询有另一条路,cgr graph 子命令。我在终端跑了 cgr graph --help,下面有 callers、callees、definition、importers、overrides、implementors 这些确定性查询,走 JSON 输出,不调 LLM。README 说图默认存嵌入式 SQLite,用 Cypher 也能直接查。
这里有个细节值得说。这些 graph 查询查的是 SQLite 里的共享图,而我刚才 cgr index 写的是 protobuf 离线索引,两条路不是同一个东西。要让 graph 子命令有东西可查,得先走 cgr start 把图写进 SQLite。而 cgr start 又绕回 Docker。所以在我这台 docker daemon 没起的机器上,离线建图能跑,结构查询这条路就断在中间。
这是第二个教训。别把离线建图和结构查询当成一条路,它们中间隔着 Docker。
值不值得用它换掉 grep
给个判断。你要在陌生仓库里快速摸清结构,尤其是跨语言的 monorepo,cgr index 加 cgr graph 比 grep 强得多。grep 按文本匹配,它按调用关系、继承关系连成网。代价是要装原生扩展,还得要 Python 3.12 以上的解释器。
你只是想找某个函数定义在哪一行,grep 加 IDE 跳转就够了,别为这个上一套图。等你开始做死代码检测、要顺着入口点找哪些函数根本没人调用,或者要给 Agent 接一个能查代码结构的工具,这套图的价值才显出来。
还有个 cgr trace 我没试。它能把运行时真实发生的调用合并进图,静态分析看不到的动态分派它能抓到。这是后话,先把静态建图跑通。
一句话。code-graph-rag 真正有用的地方,是它把「调用、导入、继承」这些 grep 抓不住的关系建成了可查询的边。离线建图那条路走得通,语义检索那半边得先备好 Docker。