Code-Graph-RAG 完整指南用知识图谱对多语言 Monorepo 进行查询、编辑与优化【免费下载链接】code-graph-ragThe ultimate RAG for your monorepo. Query, understand, and edit multi-language codebases with the power of AI and knowledge graphs项目地址: https://gitcode.com/GitHub_Trending/co/code-graph-rag导读Code-Graph-RAG 是一个基于 Tree-sitter 解析多语言代码库、在 Memgraph 中构建代码知识图谱并允许你用自然语言查询、编辑与优化代码的开源工具。本文以官方 PyPI 文档PYPI_README.md为骨架结合仓库源码入口见 cgr/init.py、CLI 实现在 codebase_rag/cli.py展开帮助你完成从安装、建图、查询、动态追踪到 MCP 集成的完整上手并深入理解其底层实现原理。一、Code-Graph-RAG 是什么Code-Graph-RAG 的核心流程是用 Tree-sitter 解析多语言代码库 → 提取函数、类、方法、模块及其相互关系 → 在 Memgraph 中构建统一 schema 的知识图谱。它面向混合语言的 Monorepo 工作场景所有语言共享同一套图模型。在图构建完成后你可以获得以下能力自然语言提问用自然语言询问代码库的任何问题回答以真实代码结构为依据按名称或意图检索源码按名称或语义意图获取任意函数、类、方法的实际源码AI 驱动的结构化编辑基于 AST 的精准打补丁surgical patching改动前先预览 diffAST 结构化搜索与重写使用 ast-grep 按 AST 模式而非文本或正则搜索和改写代码数据流追踪通过FLOWS_TO污点边追踪赋值、调用和 I/O 出口之间的数据流代码优化对照语言最佳实践或你自己的编码规范优化代码死代码检测从入口点沿调用边与引用边遍历找出不可达代码运行时行为叠加追踪测试运行或拉取生产环境 eBPF profile把真实发生的调用合并进图谱暴露静态分析看不到的动态分派多仓库工作区把多个仓库归入一个命名工作区像查询一个图一样联合查询跨微服务调用追踪路由装饰器变成端点模板HTTP 客户端 URL 解析到提供服务端的 handler跨项目边界串联服务。在仓库源码中这两个核心组件分别对应多语言解析器基于 Tree-sitter 的解析器读取代码库将函数、类、方法、模块及其关系以统一的语言无关 schema 写入 MemgraphRAG 系统codebase_rag/交互式 CLI把自然语言转成 Cypher 查询、检索匹配代码并驱动 AI 编辑与优化。cgr与code-graph-rag两个命令入口都注册在 pyproject.toml 的[project.scripts]中指向codebase_rag.cli:app。二、支持的语言以下语言完整支持含语义级解析Python、TypeScript、TSX、JavaScript、Rust、Go、Java、C、C、C#、PHP、Lua、Dart。开发中的语言Scala在 pyproject.toml 的treesitter-fullextra 中已包含tree-sitter-scala。以下语言通过可插拔的 ast-grep tier提供结构化支持模块、函数、类及 import 等需要额外安装ast-grepextraRuby、Kotlin、Swift、Elixir、Haskell、Solidity、Bash、Nix。pip install code-graph-rag[ast-grep]从源码结构看语言前端frontend按目录组织在 codebase_rag/parsers/ 下例如py/、js_ts/、rs/、go/、java/、cpp/、csharp/、dart/、lua/等cpp_frontend/、go_frontend/、java_frontend/、csharp_frontend/等目录则承载了各语言的可选语义层如 libclang、go/packages、javac、Roslyn。三、安装3.1 基础安装pip install code-graph-rag3.2 按需安装 extra安装目标命令说明全部 Tree-sitter 语法pip install code-graph-rag[treesitter-full]Python、JS、TS、Rust、Go、Java、Scala、C、C、C#、PHP、Lua、Dart语义代码搜索pip install code-graph-rag[semantic]引入 UniXcoder 嵌入依赖qdrant-client、torch、transformers见 pyproject.tomlMilvus Lite 向量后端pip install code-graph-rag[semantic,milvus]替代默认的 Qdrantast-grep 结构化搜索pip install code-graph-rag[ast-grep]structural_search/structural_replace及弱结构化语言支持3.3 向量存储与嵌入配置Qdrant是语义搜索的默认向量库。若改用Milvus Lite安装code-graph-rag[semantic,milvus]后在索引前设置export CGR_VECTOR_STORE_BACKENDmilvus export MILVUS_URI./.milvus_code_embeddings.db在 OpenAI 兼容端点计算嵌入OpenAI、Ollama、vLLM替代本地 torch/transformersexport CGR_EMBEDDING_PROVIDERopenai export OPENAI_EMBEDDING_BASE_URLendpoint export OPENAI_EMBEDDING_MODELmodel本地机器将不再需要安装 torch 和 transformers。从源码看嵌入层实现在 codebase_rag/embedder.pyEmbeddingCache会对内容做 SHA-256 哈希并按键命名空间provider:model:dimensions缓存向量避免切换模型后回放错误向量空间的旧数据见 embedder.py本地默认使用 UniXcoder 模型维度默认 768对应配置QDRANT_VECTOR_DIM: int 768见 codebase_rag/config.py。3.4 版本策略你装到的是哪个版本pip install code-graph-rag拿到的是最新的 PyPI 发布版而非最新 commit。版本线按设计有意错开发布渠道追踪内容Git tag每个版本一个每次 merge 打一个PyPI 上传与 GitHub Release 二进制每 50 个版本一次另加任何安全修复main分支 tag通常领先于已发布版本数十个补丁版本安全修复是例外立即发布不等待节奏。要运行比最新发布更新的代码从 git 安装pip install code-graph-rag[treesitter-full] githttps://github.com/vitali87/code-graph-ragmain3.5 环境前置条件Python 3.12pyproject.toml中requires-python 3.12classifiers 覆盖 3.12/3.13/3.14Docker用于运行 Memgraphcmake用于编译pymgclient这是 Memgraph 的 Python 驱动ripgreprg用于 shell 命令文本搜索。关于纯 Python wheel 的说明wheel 是py3-none-any纯 Python 包因此包本身可装在任意 Python 3.12 平台依赖可能仍需要平台 wheel 或构建工具例如pymgclient需要cmake。Debian Bookworm 的 piwheels 构建显示失败是因为 Bookworm 系统 Python 是 3.11低于项目的最低版本要求。在 Raspberry Pi OS Bookworm 上请装进 Python 3.12 环境uv venv --python 3.12 --seed source .venv/bin/activateuv 会自动下载 3.12--seed会把 pip 放进环境也可以自行安装 CPython 3.12 后用python3.12 -m pip install ...。四、CLI 快速上手安装后包会提供cgr命令同时也有code-graph-rag别名。4.1 启动、建图、查询cgr daemon up # 启动 Memgraph Qdrant cgr start --repo-path ./my-project \ --update-graph --clean # 解析并启动交互式聊天--update-graph同步/更新图谱--clean清空重建——注意它会删除共享图谱中的所有项目不只当前项目当其他项目会被销毁时会先要求确认。重复对每个想索引的仓库执行cgr start --repo-path repo --update-graph图谱是共享的同步一个项目不会动其他项目。4.2 离线 protobuf 索引cgr index -o ./index-output --repo-path ./my-project4.3 导出知识图谱为 JSONcgr export -o graph.json4.4 AI 引导的代码优化cgr optimize python --repo-path ./my-project4.5 死代码检测cgr dead-code # 扫描已索引项目 cgr dead-code -e main --exclude *.gen.* # 追加根节点跳过生成代码 cgr dead-code --format json --fail-on-found # CI 友好报告对应的 CLI 参数实现在 codebase_rag/cli.py-e/--entry-roots追加入口根、--exclude排除模式如*.gen.*、--format支持table等输出格式、--fail-on-found用于 CI 中让管道失败。重要检测结果只是待人工复核的候选不是保证可删除的清单。动态边缺失绝不等于死代码只代表被追踪的工作负载没有走到那条路径。4.6 工作区多仓库联合查询cgr workspace create my-platform cgr workspace add-repo my-platform ./service-a cgr workspace add-repo my-platform ./service-b cgr start --workspace my-platform工作区把多个仓库归为一组作为一个图谱查询——适合微服务或多包 Monorepo 场景。4.7 检查图谱与运行环境cgr stats # 节点与关系计数 cgr status # 栈状态与每个项目的最后同步情况 cgr doctor # 检查依赖与配置从源码看stats通过cypher_queries中的CYPHER_STATS_NODE_COUNTS与CYPHER_STATS_RELATIONSHIP_COUNTS查询节点/关系计数codebase_rag/cli.pydoctor由HealthChecker().run_all_checks()驱动codebase_rag/cli.pystatus读取StackManager().status()codebase_rag/cli.py。五、运行时调用追踪Runtime Call Tracing静态分析无法看到经接口、反射、注册表或框架路由发生的调用。cgr trace记录代码运行时通常是测试套件中哪些函数实际调用了哪些函数并把观测结果以CALLS边合入图谱附带动态来源信息dynamic: true、观测到的调用次数、每条边由哪些工作负载测试触发以及静态分析不存在对应边时的static_missed: true。先索引仓库cgr start --repo-path ./my-project --update-graph再按语言执行Python包内附带 pytest 插件默认关闭、需显式启用入口注册在 pyproject.toml 的[project.entry-points.pytest11]cd ./my-project pytest --cgr-trace # 写出 cgr-trace.jsonl cgr trace ingest cgr-trace.jsonl --repo-path . # 合入图谱Node.js / TypeScript使用 V8 内置 profiler无需 agentsource map 会回溯到原始 TypeScriptnode --cpu-prof --cpu-prof-namerun.cpuprofile app.js cgr trace convert run.cpuprofile --repo-path ./my-project --workload smoke cgr trace ingest cgr-trace.jsonl --repo-path ./my-project生产环境叠加eBPF 持续 profilerParca、Pyroscope、OpenTelemetry通过 HTTP 拉取 pprof 并一步完成转换同时把构建路径重新锚定到你的 checkoutcgr trace pull https://parca.example/query?...formatpprof \ --repo-path ./my-project --language go \ --path-map /build/src/./my-project/src/ \ --label endpoint --header AuthorizationBearer $TOKEN cgr trace ingest cgr-trace.jsonl --repo-path ./my-projectJVMJava、Scala、.NET、PHP、Lua、Dart、Go、Rust、C/C 各有对应的录制方案。Ingest 是幂等的所以用 cron 定时执行pullingest就能持续刷新生产环境叠加层。相关的 trace 实现位于 codebase_rag/trace/pytest 插件在codebase_rag.trace.pytest_plugin。六、MCP Server 集成运行cgr mcp-server即可通过 stdio 或 HTTP 向 Claude Code 等 MCP 客户端提供服务。MCP 工具面注册在 codebase_rag/mcp/tools.py类别工具依赖问答与检索ask_agent、query_code_graph、get_code_snippet、semantic_searchsemantic_search需要semanticextra结构化编辑surgical_replace_code、structural_search、structural_replace后两者需要ast-grepextra文件与项目read_file、write_file、list_directory、list_projects、index_repository、update_repository、delete_project、wipe_database无从源码看这些工具的异步实现如list_projects、delete_project、wipe_database、index_repository、update_repository、semantic_search、structural_search、ask_agent、query_code_graph、get_code_snippet、surgical_replace_code、read_file、write_file、list_directory等均定义在 codebase_rag/mcp/tools.py。HTTP 传输默认只绑定127.0.0.1:8080MCP_HTTP_HOST/MCP_HTTP_PORT见 codebase_rag/config.py对外暴露需显式配置MCP_HTTP_AUTH_TOKEN。七、Python SDKcgr包提供简短导入定义在 cgr/init.py供程序化使用。7.1 加载并查询导出的图谱from cgr import load_graph graph load_graph(graph.json) print(graph.summary()) functions graph.find_nodes_by_label(Function) for fn in functions[:5]: rels graph.get_relationships_for_node(fn.node_id) print(f{fn.properties[name]}: {len(rels)} relationships)load_graph与GraphLoader实现在 codebase_rag/graph_loader.py。7.2 用 Cypher 查询 Memgraphfrom cgr import MemgraphIngestor with MemgraphIngestor(hostlocalhost, port7687) as db: rows db.fetch_all(MATCH (f:Function) RETURN f.name LIMIT 10) for row in rows: print(row)MemgraphIngestor是 Memgraph 的图服务封装位于 codebase_rag/services/graph_service.py。7.3 从自然语言生成 Cypherimport asyncio from cgr import CypherGenerator async def main(): gen CypherGenerator() cypher await gen.generate(Find all classes that inherit from BaseModel) print(cypher) asyncio.run(main())CypherGenerator的 LLM 实现在 codebase_rag/services/llm.py。7.4 语义代码搜索需要semanticextrafrom cgr import embed_code embedding embed_code(def authenticate(user, password): ...) print(fEmbedding dimension: {len(embedding)})embed_code实现在 codebase_rag/embedder.py。7.5 程序化配置from cgr import settings settings.set_orchestrator(openai, gpt-5.6-terra, api_keysk-...) settings.set_cypher(google, gemini-3.5-flash-lite, api_keyyour-key)s配置对象是AppConfig的全局单例codebase_rag/config.pyset_orchestrator/set_cypher会写入活跃的ModelConfigcodebase_rag/config.py。八、环境变量可通过.env文件或环境变量配置注意 codebase_rag/config.py 只加载调用目录下的.env避免从无关工作区悄悄引入凭据变量默认值说明MEMGRAPH_HOSTlocalhostMemgraph 主机名MEMGRAPH_PORT7687Memgraph 端口ORCHESTRATOR_PROVIDER提供商google、openai、anthropic、azure、ollama、minimax、litellm_proxyORCHESTRATOR_MODEL模型 ID如gpt-5.6-terra、gemini-3.6-flash、claude-sonnet-5、qwen2.5-coderORCHESTRATOR_API_KEY提供商 API keyollama不需要CYPHER_PROVIDERCypher 生成的提供商CYPHER_MODELCypher 生成的模型 ID如qwen2.5-coder、gpt-5.6-luna、gemini-3.5-flash-liteCYPHER_API_KEYCypher 提供商的 API keyollama不需要TARGET_REPO_PATH.默认仓库路径这些字段都定义在AppConfigcodebase_rag/config.py中。补充几个源码中可确认的要点模型回退当某个角色的PROVIDER与MODEL未配置时默认回退到本地 Ollama 端点http://localhost:11434可通过OLLAMA_BASE_URL修改见_get_default_configcodebase_rag/config.py本地模型免 keyollama属于LOCAL_PROVIDERS不需要 API keycodebase_rag/config.py图谱后端校验GRAPH_BACKEND在启动时校验未知引擎名会直接报错而不是默默回退codebase_rag/config.py嵌入缓存命名空间切换嵌入提供商/模型/维度会改变缓存命名空间防止旧向量被误用codebase_rag/embedder.py。九、架构速览Source Code - Tree-sitter Parser - AST Analysis - Memgraph Knowledge Graph | User Query - AI Model (Cypher Gen) - Cypher Query - Graph Results - Response系统两大组件多语言解析器Tree-sitter 解析器读取代码库把函数、类、方法、模块及其关系以单一语言无关 schema 写入 MemgraphRAG 系统codebase_rag/交互式 CLI将自然语言转成 Cypher检索匹配代码驱动 AI 编辑与优化。图谱写入/更新相关代码位于 codebase_rag/graph_updater.py、codebase_rag/graph_loader.py、codebase_rag/schemas.pyCypher 查询模板集中在 codebase_rag/cypher_queries.py。更完整的架构与图 schema 说明可参考 docs/architecture/overview.md 与 docs/architecture/graph-schema.md。十、许可与文档Code-Graph-RAG 以MIT协议开源见 LICENSE。更多文档、架构细节与贡献指南可在仓库的 docs/ 目录中查阅快速上手docs/getting-started/installation.md、docs/getting-started/quickstart.md、docs/getting-started/configuration.mdCLI 参考docs/guide/cli-reference.md专项指南docs/guide/dynamic-tracing.md、docs/guide/dead-code.md、docs/guide/mcp-server.md、docs/guide/code-optimization.md【免费下载链接】code-graph-ragThe ultimate RAG for your monorepo. Query, understand, and edit multi-language codebases with the power of AI and knowledge graphs项目地址: https://gitcode.com/GitHub_Trending/co/code-graph-rag创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考