第6章 特性详解——代码图谱、语义搜索与 MCP
第6章:特性——代码图谱、语义搜索与 MCP
深入探索:面向代码库智能的强大功能。理解、查询、编辑和优化代码库所需的一切工具。
架构
源码:Python、TypeScript、TypeScript (TSX)、JavaScript、Rust、Go、Java、C、C++、C#、PHP、Lua、Dart、Julia、Ruby、Kotlin、Swift、Elixir、Haskell、Solidity、Bash、Nix
↓ Tree-sitter AST 解析 + ast-grep 层 与语言无关的抽象语法树分析,C/C++ 和 C# 通过 libclang 与 Roslyn 语义前端支持
↓ 知识图谱(SQLite、Memgraph 或 Neo4j)
26 种节点标签:Project、Package、Folder、File、Module、Class、Function、Method、Interface、Enum、Type、Union、ModuleInterface、ModuleImplementation、ExternalPackage、ExternalModule、Resource、Section、Pattern、CodeSmell、SecurityIssue、Gloss、Parameter、Field、EnumVariant、Constant
36 种关系类型:CONTAINS_PACKAGE、CONTAINS_FOLDER、CONTAINS_FILE、CONTAINS_MODULE、CONTAINS_SECTION、DEFINES、DEFINES_METHOD、DEFINES_CONSTANT、IMPORTS、EXPORTS、EXPORTS_MODULE、IMPLEMENTS_MODULE、INHERITS、IMPLEMENTS、OVERRIDES、CALLS、REFERENCES、INSTANTIATES、DEPENDS_ON_EXTERNAL、ACCEPTS、RETURNS、OF_TYPE、HAS_PARAMETER、HAS_FIELD、HAS_VARIANT、READS_FROM、WRITES_TO、FLOWS_TO、EXPOSES、RESOLVES_TO、IMPLEMENTS_PATTERN、HAS_SMELL、HAS_VULNERABILITY、LINKS_TO、ANNOTATES、MENTIONS
↓ RAG 系统:自然语言 → Cypher → 结果 → AI 回答
Tree-sitter AST 解析
基于 Tree-sitter 语法的稳健解析,与语言无关。提取函数、类、模块、导入和调用关系,并完整追踪源码位置。
| 语言 | 状态 | 扩展名 | |---|---|---| | Python | 完全支持 | .py、.pyi | | TypeScript | 完全支持 | .ts、.mts、.cts | | TypeScript (TSX) | 完全支持 | .tsx | | JavaScript | 完全支持 | .js、.jsx、.mjs、.cjs | | Rust | 完全支持 | .rs | | Go | 完全支持 | .go | | Java | 完全支持 | .java | | C | 完全支持 | .c | | C++ | 完全支持 | .cpp、.h、.hpp、.cc、.cxx、.hxx、.hh、.ixx、.cppm、.ccm、.mxx | | C# | 完全支持 | .cs | | PHP | 完全支持 | .php | | Lua | 完全支持 | .lua | | Dart | 完全支持 | .dart | | Julia | 完全支持 | .jl | | Ruby | 结构支持 | .rb | | Kotlin | 结构支持 | .kt、.kts | | Swift | 结构支持 | .swift | | Elixir | 结构支持 | .ex、.exs | | Haskell | 结构支持 | .hs | | Solidity | 结构支持 | .sol | | Bash | 结构支持 | .sh、.bash | | Nix | 结构支持 | .nix | | Scala | 开发中 | .scala、.sc | | SQL (PostgreSQL) | 开发中 | .sql |
知识图谱架构
你的代码库存储为一张互联的图:默认使用内嵌的 SQLite 文件,也可选用 Memgraph 或 Neo4j 作为后端。节点是代码实体,边是调用、导入、定义、继承等关系。
- 26 种节点标签 - 36 种关系类型 - 22 种语言,统一 schema
节点:Function、Class、Module、File、Package、Resource、SecurityIssue 边:CALLS、IMPORTS、DEFINES、INHERITS、IMPLEMENTS、REFERENCES、FLOWS_TO 属性:qualified_name、name、path、start_line、end_line、docstring
所有语言都落到同一套 schema,一条 Cypher 查询就能横跨多语言的 monorepo。I/O、数据流和 ast-grep 结果节点为可选的捕获组。
自然语言查询
用日常语言提问。AI 将你的意图翻译成 Cypher 查询,在图上执行,并返回人类可读的答案。
提问示例
```bash # 用日常语言提问,agent 自动编写 Cypher > "What functions call UserService.create_user?" > "Show me all classes that implement the Repository interface" > "Find functions related to database operations" > "Show me Go interfaces and implementations" ```
AI 驱动的代码编辑
用 diff-match-patch 精确替换某个代码块,文件的其余部分保持原样。在已索引的项目上,每次写入都会返回结构化变更。
MCP 工具调用
```python # 只替换一个精确的代码块,文件其余部分不受影响 > surgical_replace_code( file_path="auth/login.py", target_code="...要替换的精确代码块...", replacement_code="...新代码..." ) # 在已索引的项目上,结果会附带结构化变更: # 被重命名的符号、悬空的调用方、受此次修改影响的测试。 ```
交互式代码优化
AI 依据各语言的最佳实践分析你的代码库。逐条审阅建议,放心应用。
终端
```bash $ cgr optimize python --repo-path /path/to/your/repo \ --reference-document /path/to/best_practices.md Analyzing codebase structure... Found 23 Python modules with potential optimizations Optimization Suggestion #1: File: src/data_processor.py Issue: Using list comprehension in a loop can be optimized Suggestion: Replace with generator expression for memory efficiency [y/n] Do you approve this optimization? ```
死代码检测
从入口点出发,沿着 CALLS 和 REFERENCES 边遍历,找出无法到达的函数和方法。支持 `--fail-on-found`,方便集成到 CI。
```bash # 列出没有任何调用路径可达的函数和方法 cgr dead-code # 声明仅由框架调用的根节点 cgr dead-code -e main -e cli.run -e handlers.webhook # 出现新的不可达代码时让 CI 失败 cgr dead-code --format json --output dead-code.json --fail-on-found \ --exclude '*_generated*' ```
结构化搜索与替换
基于 AST 模式用 ast-grep 查找和重写代码——按结构匹配,而非文本或正则。以 agent 工具形式暴露,写入前先提供 dry-run diff。
MCP 工具调用
```python # 按 AST 模式匹配,而非文本 > structural_search(pattern="requests.get($URL)", language="python") # 重写所有匹配项;dry_run 会先返回 diff > structural_replace( pattern="requests.get($URL)", rewrite="http_client.get($URL)", language="python", dry_run=True ) ```
I/O 与数据流追踪
启用 io 捕获组后,图中会新增 Resource 节点,覆盖文件、环境变量、网络、套接字和数据库,并附带 READS_FROM、WRITES_TO 和 FLOWS_TO 污点传播边。溯源问题转化为图上的可达性问题。
Cypher
```cypher // 环境变量中的数据是否会到达标准输出? MATCH path = (src:Resource {kind: 'ENV'}) -[:FLOWS_TO*1..5]-> (sink:Resource {kind: 'STDOUT'}) RETURN path // 哪些可调用对象从磁盘读取机密信息? MATCH (f)-[:READS_FROM]->(r:Resource {kind: 'FILE'}) WHERE r.qualified_name CONTAINS 'credentials' RETURN f.qualified_name, r.qualified_name ```
安全与代码异味发现
findings 捕获组运行内置的 ast-grep 规则包,将每条命中存储为关联到所属模块的 SecurityIssue、CodeSmell 或 Pattern 节点——审计结果与你的查询共用同一张图。
Cypher
```cypher // 安全问题和代码异味作为图节点 MATCH (m:Module)-[:HAS_VULNERABILITY]->(s:SecurityIssue) RETURN m.path, s.name, s.message, s.start_line // 某个包内部的代码异味 MATCH (m:Module)-[:HAS_SMELL]->(c:CodeSmell) WHERE m.qualified_name STARTS WITH 'payments.' RETURN m.qualified_name, c.name, c.snippet ```
语义代码搜索
通过描述功能来查找函数。按意图搜索,而不必知道确切的名称。
MCP 工具调用
```python # 按函数做什么来查找,而非按名字 > semantic_search(natural_language_query="error handling functions") > semantic_search(natural_language_query="database connection setup", top_k=10) # 返回匹配的函数及其相似度得分。 # 需要安装 "semantic" extra。 ```
MCP 服务器 / Claude Code
提供 38 个工具的 MCP 服务器,支持 Claude Code、Cursor 及任何 MCP 客户端:无需离开 agent 即可导航、重构、搜索和追踪。
list_projects、delete_project、wipe_database、index_repository、update_repository、reingest、resolve、definition、callers、callees、implementors、overrides、importers、tests_reaching、endpoints、endpoint_callers、remote_dependencies、annotate、glosses、rename、change_signature、move、context、query_code_graph、get_code_snippet、surgical_replace_code、read_file、write_file、list_directory、semantic_search、structural_search、structural_replace、find_duplicate_code、get_function_source、ask_agent、flow_verdict、explain_traceback、rank_root_causes
图谱导出与实时更新
将知识图谱数据导出,用于外部分析。带防抖的文件监视器让图谱随代码库变化保持同步,`cgr index` 还会生成 protobuf 索引供离线使用。
```bash # 将图谱导出为 JSON(节点、关系、元数据) cgr export -o my_graph.json cgr export -o my_project.json --project my-project # 工作时保持图谱同步 cgr watch --repo-path /path/to/your/repo # 生成离线 protobuf 索引 cgr index -o ./index-output --repo-path ./my-project ```
Python SDK 与打包技术栈
从 PyPI 安装。图谱默认存储于内嵌的 SQLite 文件;`cgr daemon up` 可启动可选的 Memgraph 和 Qdrant 技术栈。通过 cgr 包在 Python 中操作图谱:图谱加载器、Cypher 生成器和语义搜索。
```python from cgr import load_graph
graph = load_graph("my_graph.json") summary = graph.summary() print(f"Total nodes: {summary['total_nodes']}")
for func in graph.find_nodes_by_label("Function")[:5]: relationships = graph.get_relationships_for_node(func.node_id) print(func.properties["name"], len(relationships)) ```
可扩展的语言支持
得益于统一的 Tree-sitter 架构,添加新语言非常简单。可插拔的 ast-grep 层通过一个 YAML 模式文件即可提供结构支持——模块、函数、类和导入——无需手写解析器。每种语言都生成相同的图谱 schema,因此所有查询和编辑工具对新语言开箱即用。
```yaml # 一个 YAML 文件即可为图谱添加一种语言 language: ruby ast_grep_id: ruby extensions: - ".rb" functions: - "def self.$NAME" - "def $NAME" classes: - "class $NAME" - "module $NAME" imports: - "require $PATH" - "require_relative $PATH" ```