codegraph

CodeGraph

面向 AI Agent 和开发者的跨语言代码智能。

CodeGraph 为你的代码库构建语义图谱——包括函数、类、导入和调用链——并通过 42 个 MCP 工具、VS Code 扩展、JetBrains IDE 插件和持久化记忆层提供访问。通过 tree-sitter 解析 38 种语言。AI Agent 能获得结构化的代码理解，而不必在文件中搜索。

快速开始

MCP 服务（Claude Code、Cursor 及任何 MCP 客户端）

添加到 ~/.claude.json（或你的 MCP 客户端配置）：

{
  "mcpServers": {
    "codegraph": {
      "command": "/path/to/codegraph-server",
      "args": ["--mcp"]
    }
  }
}

服务会自动索引当前工作目录。

VS Code 扩展

安装 VSIX：

code --install-extension codegraph-0.21.0.vsix

一个 VSIX 适用于所有平台。 扩展中不包含分析引擎：首次激活时，扩展会提示下载适用于你平台的引擎，根据已发布的校验和验证后，将其安装到 ~/.codegraph/bin——JetBrains 插件也使用相同位置，因此一次下载即可供两者使用。 由于引擎是以你的权限运行的原生二进制文件，因此扩展会提供下载选项，而不会自动下载。 如果暂不下载，可在准备好时从命令面板运行 CodeGraph: Download Analysis Engine。

安装引擎后，扩展会自动启动它，并将所有工具注册为 Copilot 的语言模型工具。

JetBrains IDE

适用于 IntelliJ IDEA、PyCharm、GoLand、Android Studio 和其他 JetBrains 系列 IDE 的插件通过 LSP 驱动同一引擎：Code Vision、Symbols 和 Memories 工具 窗口、图谱面板，以及一键为 AI Assistant 注册 MCP。 它与 VS Code 扩展一样解析或下载引擎， 并共享 ~/.codegraph/bin。

→ jetbrains/README.md，了解功能、引擎 解析顺序以及如何从源代码构建。

AI Agent 规则

预配置的规则文件可指导 AI 编码 Agent（Claude、Cursor、 Windsurf、Codex、Cline）在回退到 grep / 多文件读取之前使用 CodeGraph MCP 工具。将自然语言意图映射到合适的 codegraph_* 工具。

→ codegraph-ai/codegraph-rules-for-agents

设置命令为 cp <agent>/codegraph.md ~/<agent>/（每个 Agent 一行——参见 规则仓库的 README）。

GitHub Action — 在 CI 中审查 PR

在仓库中添加一个工作流，即可在每个 PR 上自动发布代码图谱分析 评论——包括影响范围、测试缺口、过时文档和建议的 审查者。仅运行图谱模式（不使用嵌入、不使用 ONNX 模型），因此速度 快且无需 API 密钥——只需内置的 GITHUB_TOKEN。

将 .github/workflows/codegraph-pr.yml 复制到你的仓库中。核心调用只需一条命令：

codegraph-server --graph-only \
  --run-tool codegraph_pr_context \
  --tool-args '{"baseBranch":"main","format":"markdown"}'

此命令会输出一条可直接发布的 Markdown 评论。--graph-only 标志 会跳过嵌入生成（索引速度快 10–50 倍）；--run-tool 会运行 一个工具后退出，不进行 MCP stdio 握手——非常适合编写脚本。

---

升级到 0.21

每个项目在首次由 0.21 打开时，都会在后台重新生成一次嵌入。 现在，存储的向量会记录用于生成它们的模型和设置，而来自 0.20.1 或更早版本的索引不包含这些信息。 运行期间，关键词搜索仍可使用。

升级后请重启所有 --watch 守护进程。 仍在运行的守护进程会继续写入 0.21 不会加载的向量，而连接到它的会话在守护进程重启前无法使用语义搜索。

现在也会对 getUserById 这类连写的标识符按拆分后的单词形式生成嵌入。 这主要有助于在 TypeScript、Java 和 C# 等 camelCase 语言中进行自然语言搜索。 传入 --split-identifiers=false 可保留旧行为。

现在 --full-body-embedding=false 会生效；在 0.20.1 中，此标志始终处于启用状态。

---

配置

MCP 服务标志

标志	默认值	描述
--workspace <path>	当前目录	要索引的目录（可重复使用以支持多个项目）
--exclude <dir>	—	要跳过的目录（可重复使用）
--embedding-model <model>	bge-small	bge-small（384d，快速）、jina-code-v2（768d，慢 6 倍）、granite-97m（384d，32K 上下文，慢约 3 倍）或 static（model2vec，256d——索引速度快约 100 倍，无需 ONNX；需要本地模型目录，见下文）
--full-body-embedding	true	对完整函数体（约 50 行）进行嵌入，以改善语义搜索和重复项检测。需要指定值：--full-body-embedding=false 可关闭此功能
--split-identifiers	true	同时嵌入连写标识符的按词拆分形式，因此 getUserById 也会以 "get user by id" 的形式嵌入。已使用 _ 或 - 分隔的名称会保持原样，因为它们会被分词为相同的词；开头或结尾的分隔符不会分隔出任何内容，因此 _handleClick 会像 handleClick 一样拆分。需要指定值：--split-identifiers=false 会嵌入原始名称，与 0.20.1 及更早版本的行为一致
--max-files <n>	5000	要索引的最大文件数
--profile <name>	all	将公开的 MCP 工具范围限制为指定子集（见下文）
--graph-only	关闭	跳过嵌入生成——仅构建图并提供结构化工具。无需加载 ONNX 模型，索引速度快 10–50 倍。语义搜索和记忆工具不可用。适用于 CI／一次性图查询。
--run-tool <name>	—	一次性模式：建立索引、运行单个工具、打印结果并退出。无需 MCP 握手。与 --tool-args '<json>' 搭配使用。

--split-identifiers 和 --full-body-embedding 都会改变每个符号用于嵌入的文本，而基于不同文本生成的向量无法相互比较排名。 因此，项目存储的向量会标记生成它们时所用的设置（包括 --embedding-model，因为不同模型的维度不同），并且任何配置不同的进程都会忽略这些向量。 更改这三项设置中的任意一项时，系统会在后台重新生成嵌入，而无需手动重新索引。 运行 --watch 时，请使用与读取该项目的会话相同的标志，这样两边就会共用同一组向量，而不会相互覆盖并重复生成嵌入。 有关从 0.20.1 或更早版本升级时的影响，请参阅升级到 0.21。

--embedding-model static — model2vec 快速索引

静态（model2vec）嵌入会以 token→向量查找表取代 ONNX Transformer：索引速度快约 100 倍（此仓库的 5,873 个符号约 1 秒即可完成嵌入，而使用 BGE 则需约 3.4 分钟），并且无需 ONNX 运行时，也没有 1.5 GB 内存限制。 检索仍采用混合方式（BM25 + 语义），因此端到端质量约为 BGE 的 90%。 模型不会随任何客户端打包——需要在 ~/.codegraph/static_models/jina-code-static-256（或 CODEGRAPH_STATIC_MODEL 指向的位置）准备本地模型目录，其中包含 config.json、tokenizer.json 和 model.safetensors：

• 从 npm 安装 @astudioplus/codegraph-mcp 时，会将模型下载到该默认位置（尽力而为；设置 CODEGRAPH_SKIP_MODEL_FETCH=1 可跳过，且安装绝不会因此失败）。
• 也可以使用 scripts/fetch-static-model.sh 获取预构建模型，或从任意 sentence-transformer 蒸馏自己的模型（默认使用 Apache-2.0 许可的 Jina-Code），在 CPU 上约需 30 秒：python scripts/distill_static_model.py。
• 默认位置中的模型无需 IDE 设置：两个 IDE 客户端都会将 CODEGRAPH_STATIC_MODEL 保持为未设置状态，并由引擎解析该路径。若要使用存放在其他位置的模型，请在 VS Code 中设置 codegraph.staticModelPath，或在 JetBrains 中设置 Settings → Tools → CodeGraph → Embeddings → Static model directory；随后每个客户端都会将该路径作为 CODEGRAPH_STATIC_MODEL 传入。

CODEGRAPH_SKIP_MEMORY_CHECK — 强制嵌入模型绕过 RAM 检查

加载 ONNX 模型前，服务会检查可用内存；如果低于 约 1.5 GB，就会跳过模型，以避免被 OOM-kill（改为仅运行图分析）。 设置 CODEGRAPH_SKIP_MEMORY_CHECK=1（也接受 true/yes）即可绕过该 检查，并始终加载模型。

如果机器有充足的可用 RAM，但嵌入功能仍被禁用，请使用此设置。 如果读数为 0 MB available，系统会将其视为检测失败，并仍然加载模型（macOS 会将可回收内存放在非活跃／推测性页面中， 某些内存读取工具不会将其计为可用内存），因此此覆盖设置主要适用于其他报告数值偏低但不准确的情况。 MCP 和一次性 --run-tool 模式均支持此设置。

--profile — 精简 MCP 工具范围

完整的 42 个工具虽然方便，但会增加 Agent 的提示上下文成本。配置文件只会显示你需要的工具集（也可通过 CODEGRAPH_TOOL_PROFILE 环境变量设置）：

配置文件	工具	适用场景
all （默认）	所有工具（社区版 + Pro）	常规会话
core	8 个 — 搜索 + 符号信息 + AI 上下文	只需要查询的对话密集型 Agent 会话
graph	17 个 — 调用方／被调用方／依赖项／影响范围／遍历／PR 上下文	重构 + 结构分析
memory	14 个 — codegraph_memory_* 加文档工具	笔记记录／知识库工作流
security	仅 Pro 安全工具（社区版中为空）	Pro 安全审计

VS Code 设置

codegraph.* 设置的文档集中放在读取这些设置的扩展旁边：

→ vscode/README.md — 配置

默认启用完整函数体嵌入。解析时会捕获函数体文本，不产生任何 I/O 开销。

内置排除项（始终跳过）涵盖三大类中的约 47 个目录：

• 构建／缓存：node_modules、target、dist、build、out、.git、__pycache__、vendor、.venv、venv、.tox、.pytest_cache、.mypy_cache、.ruff_cache、.next、.nuxt、.svelte-kit、.parcel-cache、.npm、.yarn、.pnpm-store、.cache、.cargo、.bundle、.gradle、DerivedData、Pods、xcuserdata、cmake-build-*
• IDE／IaC 状态：.idea、.vscode-test、.fleet、.terraform、.terragrunt-cache、.serverless
• 敏感凭据目录：.aws、.ssh、.gnupg、.kube、.docker

此外，还会排除二进制归档文件、原生库、操作系统元数据，以及机密文件扩展名（*.pem、*.key、*.p12、*.pfx、*.crt、*.gpg、*.kdbx、id_rsa 等 SSH 密钥约定文件）对应的 glob 模式，以纵深防御，避免意外嵌入凭据。

索引结果为零个文件，或发现其他异常？请参阅 docs/troubleshooting.md。

---

工具

社区版提供 42 个工具，CodeGraph Pro 另提供 27 个工具（其中 17 个是安全分析器）。

代码分析（11）

工具	功能说明
get_ai_context	主要上下文工具。 根据意图（解释／修改／调试／测试）提供上下文，并控制 token 预算。返回源代码、相关符号、导入项、同级项和调试提示。
get_edit_context	编辑前所需的一切信息：源代码、调用者、测试、记忆和 Git 历史
get_curated_context	针对自然语言查询（“身份验证是如何工作的？”）提供跨代码库上下文
analyze_impact	预测影响范围——修改、删除或重命名后会有哪些内容受影响
analyze_complexity	提供圈复杂度及详细分解（分支、循环、嵌套、异常、提前返回）
find_circular_deps	检测跨文件的循环导入／依赖链
find_hot_paths	按传递调用者数量排列被调用最多的函数
find_dead_imports	查找未使用的导入项——已导入但从未引用的模块
get_module_summary	目录概览：文件数量、函数、语言分布、复杂度最高的函数
search_by_pattern	使用正则表达式搜索函数体、签名、名称和文档字符串
search_by_error	查找会抛出、捕获或处理特定错误类型的函数

代码导航（13）

工具	功能说明
symbol_search	按名称或自然语言查找符号（BM25 + 语义混合搜索）
get_callers / get_callees	谁调用了此项？此项调用了什么？（支持传递深度）
get_detailed_symbol	完整的符号信息：源代码、调用者、被调用项、复杂度
get_symbol_info	快速查看元数据：签名、可见性、类型
get_dependency_graph	文件／模块导入关系，支持深度控制
get_call_graph	函数调用链（调用者和被调用项）
find_by_imports	查找导入某模块的文件
find_by_signature	按参数数量、返回类型、修饰符搜索
find_entry_points	主函数、HTTP 处理器、CLI 命令、事件处理器
find_implementors	查找所有注册为 ops struct 回调的函数
find_related_tests	测试指定函数的测试
traverse_graph	使用边／节点类型筛选器自定义遍历图

索引（3）

工具	功能说明
reindex_workspace	对工作区进行完整或增量重新索引
index_files	添加／更新指定文件，无需完整重新索引
index_directory	将目录添加到图中，并保留现有数据

记忆（7）

跨会话持久保存 AI 上下文——调试见解、架构决策、已知问题。

工具	功能说明
memory_store / memory_get / memory_search	存储、检索和搜索记忆（BM25 + 语义搜索）
memory_context	获取与文件／函数相关的记忆
memory_list / memory_invalidate / memory_stats	浏览、归档和监控记忆

可与 Tempera 配合使用。Tempera 是一个情景记忆系统，可在多个项目间捕获可迁移的调试策略和解决方案。CodeGraph 的记忆工具存储特定于项目的笔记；Tempera 则捕获跨项目的 BKM（最佳已知方法），并随时间不断改进。

PR／变更分析（1）

工具	功能说明
pr_context	一键 PR 审查。 根据基分支运行 Git diff，在图中查找已更改的函数，并报告：影响范围（调用者）、测试覆盖率及缺口、受影响的模块、感知 diff 的变更分类（签名还是函数体）、过时文档警告、复杂度、提交消息提示，以及根据 git blame 建议的审阅者。

文档（7）

持久化项目文档——为设计文档建立索引，对其进行语义搜索，验证代码是否符合设计，并根据代码图生成架构文档。

工具	功能
index_markdown	将本地 .md 文件（ARCHITECTURE.md、API_DESIGN.md 等）编入持久化文档存储。按标题树分块，并为叶节点生成嵌入向量。
search_docs	对已编入索引的文档进行语义搜索——返回匹配的章节及标题路径导航
list_doc_sources	列出所有已编入索引的源文件
remove_doc_source	从源文件中移除所有已索引的分块
verify_design	交叉比对文档中的描述与代码图。direction=forward（文档→代码）、reverse（代码→文档）或 both
design_gaps	查找文档中有描述但代码中尚不存在的标识符——根据规范生成 TODO 列表
generate_architecture_doc	根据实时代码图（模块、热点路径、复杂度、循环依赖）自动生成结构化的 ARCHITECTURE.md

所有工具名称都带有 codegraph_ 前缀（例如 codegraph_get_ai_context）。针对特定符号的工具接受 uri + line，或来自 symbol_search 结果的 nodeId。

---

使用示例

为设计文档建立索引并进行搜索：

codegraph_index_markdown(path: "/projects/myapp/docs/ARCHITECTURE.md")
codegraph_search_docs(query: "how does the auth module handle JWT refresh?")

检查代码是否符合设计：

codegraph_verify_design(source: "/projects/myapp/docs/ARCHITECTURE.md", direction: "forward")
// → "132/132 identifiers verified, 0 gaps"

查找文档中有描述但尚未实现的内容：

codegraph_design_gaps(source: "/projects/myapp/docs/API_DESIGN.md")
// → "4 of 12 identifiers not found in code: PaymentService, RefundHandler, ..."

根据代码图生成架构文档：

codegraph_generate_architecture_doc(scope: "src/", topN: 5)
// → Markdown with modules, complexity hotspots, hot paths, circular deps

保存调试心得，供未来会话使用：

codegraph_memory_store(kind: "debug_context", title: "Nginx body size limit",
  content: "The /upload endpoint fails on payloads > 1MB...",
  problem: "API returns 500 on large uploads",
  solution: "Increase nginx client_max_body_size to 10M",
  agentSource: "claude")

获取包含图压缩统计数据和设计文档补充内容的 AI 上下文：

codegraph_get_ai_context(uri: "file:///projects/myapp/src/auth.rs", line: 42, intent: "modify")
// → Code context + graphStats: {entitiesInGraph: 13555, entitiesTraversed: 47, entitiesKept: 8}
// → design_context section from indexed docs mentioning "auth"

审查 PR——一次调用即可检查影响范围、测试缺口、过时文档和审阅者：

codegraph_pr_context(baseBranch: "main")
// → "PR changes 4 files (+263/-77, 12 functions). 37 direct callers, 8 tests, 3 untested. Risk: medium."
// → test_gaps: [refresh_token, revoke_session] — functions with 0 test callers
// → stale_docs: ["auth.rs described in ARCHITECTURE.md > Authentication — doc may need updating"]
// → suggested_reviewers: [{author: "anvanster", lines_owned: 3200}]
// → commit_hint: "feat(mcp): <describe the change>"

缩小工具范围，以适应频繁交互的会话：

codegraph-server --mcp --profile=core  # Only 8 tools: search + symbol info + AI context

---

CodeGraph Pro

CodeGraph Pro 中提供的其他工具：

工具	功能
scan_security	安全漏洞扫描：40 多种危险函数模式、从源到汇的污点追踪、HTTP 端点的身份验证覆盖率（7 种语言/框架）、架构分层违规、弱加密、硬编码密钥
analyze_coupling	模块耦合度指标和不稳定性评分
find_unused_code	死代码检测，并为结果评分可信度
find_duplicates	检测重复或近似重复的函数
find_similar / cluster_symbols / compare_symbols	基于嵌入的代码相似度分析
cross_project_search	搜索所有已索引的项目
mine_git_history / mine_git_history_for_file / search_git_history	Git 历史挖掘与语义搜索
security_control_flow	映射函数中的每条执行路径——“是否可能绕过身份验证检查并返回？”
security_trace_data_flow	追踪变量从产生到销毁的过程——“用户输入是否会传入此 SQL 查询？”
security_generate_sbom	从 8 种锁文件格式生成 CycloneDX SBOM
security_audit_deps	使用 OSV 检查依赖项漏洞
security_check_unchecked_returns / _resource_leaks / _misconfig / _input_validation / _error_exposure	5 种启发式分析器，覆盖 CWE Top 25 中约 80% 的问题
security_scan_iac	Docker / Kubernetes / Terraform 配置错误扫描
security_check_licenses	强制执行锁文件许可证策略（检测 Copyleft）
security_check_secrets_entropy	使用 Shannon 熵检测硬编码密钥
security_detect_injection	针对 SQL/XSS/cmd/path/deser/template 注入的专项检测（20 种模式）
security_check_search_path	检测不受信任的搜索路径 / DLL 劫持（CWE-426/CWE-427）
security_check_crypto	密码学误用：弱密码、哈希、PRNG、密钥、静态 IV、计时泄漏比较（CWE-208/326-330/338/916，35 种模式）
security_export_sarif	将所有发现汇总为 SARIF 2.1.0（GitHub Code Scanning、GitLab SAST）

跨工具功能（所有 security_check_* 工具）：

• include_tests / treat_as_production — 对测试/示例/供应商代码提供一流的跳过支持
• check_compile_gates — 若 CMake/Cargo/Makefile 未定义 X，则将 #ifdef X 内的 C/C++ 发现标记为 DEFENSIVE_GATED_OFF
• 支持 25 种标记的抑制机制（如 # nosec、// NOLINT、// codeql[ignore]、# rubocop:disable 等），可在行和函数级别使用
• 每次扫描的遥测信息块：path_filter（已检查/匹配/跳过）+ compile_gate（被门控关闭的数量）

---

语言

通过 tree-sitter 解析 38 种语言——函数、类、导入、调用图、复杂度指标、依赖关系图、符号搜索和影响分析：

类别	语言
系统	C、C++、Rust、Zig、Objective-C
JVM	Java、Kotlin、Scala、Groovy、Clojure
Web/脚本	TypeScript/JS、Python、Ruby、PHP、Perl、Lua、Elixir、Elm
Web/样式	CSS
移动端	Swift、Dart
函数式	Haskell、OCaml、Julia、Erlang、Elm、Clojure
企业	C#、COBOL、Fortran、Go
区块链	Solidity
Shell/配置	Bash、Dockerfile、HCL/Terraform、TOML、YAML
硬件	Verilog/SystemVerilog、Tcl
数据科学	R、Julia

HTTP 处理程序检测：Python（FastAPI/Flask/Django）、TypeScript（NestJS）、Java（Spring/JAX-RS）、Go（stdlib/Gin/Echo/Fiber）、C#（ASP.NET）、Ruby（Rails）、PHP（Laravel/Symfony）。

社区版与完整版本： COBOL、Fortran、Perl、Dart、Zig 和 R 仅在使用 --features extra-languages 编译时包含。默认社区版二进制文件不包含这些语言——遥测数据 显示它们的使用量为零，且其 tree-sitter 语法会增加约 25 MB（仅 COBOL 的解析表就有 30 MB）。 其他 32 种语言始终可用。

---

架构

MCP Client (Claude, Cursor, ...)   VS Code Extension   JetBrains Plugin
        |                                  |                  |
    MCP (stdio)                       LSP Protocol       LSP Protocol
        |                                  |                  |
        └───────────┐               ┌──────┴──────────────────┘
                    ▼               ▼
            ┌─────────────────────────────┐
            │       codegraph-server      │
            ├─────────────────────────────┤
            │  38 tree-sitter parsers     │
            │  Semantic graph engine      │
            │  AI query engine (BM25)     │
            │  Memory layer (RocksDB)     │
            │  Docs store (RocksDB+HNSW)  │
            │  Full-body embeddings (BGE) │
            │  HNSW vector index          │
            └─────────────────────────────┘

单个 Rust 二进制文件同时提供 MCP 和 LSP 协议服务。

• 索引：约 60 个文件/秒。文件更改时通过 FNV-1a 内容哈希增量重新索引。
• 持久化：图和嵌入向量持久化到 ~/.codegraph/graph.db（RocksDB）。重启后即时启动——无需重新解析或生成嵌入向量。
• 查询：不到 100 毫秒。索引时解析跨文件的导入和调用关系。
• 嵌入向量：使用完整函数体（解析时捕获函数体，无磁盘 I/O）。向量与图一同存储在 RocksDB 中。首次运行时自动下载模型。

---

支持的平台

引擎是原生二进制文件，首次运行时会下载适用于你平台的版本。

平台	架构
macOS	Apple Silicon（arm64）和 Intel（x64）
Linux	x64 和 arm64
Windows	x64（Windows on ARM 通过仿真运行 x64 版本）

Linux 需要 glibc 2.30 或更高版本，并且需要来自 GCC 11 或更高版本的 libstdc++（GLIBCXX_3.4.29）。 第二项要求是决定性条件，不能由第一项推定——引擎内嵌的 ONNX Runtime 是使用 GCC 11 构建的。

可以运行	无法运行
SLES 15 SP4	Ubuntu 20.04
Ubuntu 22.04 及更高版本	Debian 11
Debian 12 及更高版本	RHEL / CentOS 8
RHEL 9 及更高版本	Amazon Linux 2
Amazon Linux 2023

两种 Linux 架构的要求相同。如果引擎启动后立即退出，并显示类似以下内容的消息：

version `GLIBCXX_3.4.29' not found (required by codegraph-server)

则表示该发行版的 C++ 运行时版本低于引擎所需版本；安装较新的 libstdc++（例如 RHEL 8 的 gcc-toolset-11）即可解决问题，无需升级发行版。

---

从源代码构建

git clone https://github.com/codegraph-ai/codegraph
cd codegraph
cargo build --release -p codegraph-server    # Rust server
cd vscode && npm install && npm run esbuild  # VS Code extension
npx @vscode/vsce package                     # VSIX

需要 rustup（它会安装 rust-toolchain.toml 中固定的 Rust 版本）、Node.js 18+、VS Code 1.90+。

---

支持项目

CodeGraph 免费、开源，由一名独立开发者维护。 如果它为你节省了时间，可以考虑在 GitHub 上赞助——这有助于项目持续发展。

---

许可证

Apache-2.0