CodeGraph

已经安装了吗？运行 codegraph upgrade

在 X 上关注 @getcodegraph 获取更新。

使用语义代码智能增强 Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity 和 Kiro

最快的完整代码图 · 精准上下文 · 专为智能体实际工作方式构建 · 100% 本地

  **内核由 Rust 驱动**

文档与网站 →

CodeGraph 平台即将推出 — 针对每个 PR，准确知道要测试什么、可能破坏什么、哪些流程受影响、以及业务逻辑是否被损害。

_{获取托管产品的早期测试权限 · getcodegraph.com}

目录

• 开始使用
• 语言支持
• 为什么选择 CodeGraph?
• 主要特性
• 框架感知路由
• 混合 iOS / React Native / Expo 桥接
• 快速开始
• 工作原理
• CLI 参考
• MCP 工具
• 库使用
• 配置
• 遥测
• 已验证发布
• 支持平台
• 支持智能体
• 支持语言
• 测量跨文件覆盖
• 故障排除
• 许可

开始使用

1. 安装 CLI

无需 Node.js — 一条命令获取适合你操作系统的构建版本：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

npm i -g @colbymchenry/codegraph

2. 连接你的智能体

在新终端中，运行安装程序将 CodeGraph 连接到你所使用的智能体：

codegraph install

_{检测并自动配置 Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE 和 Kiro — 将 CodeGraph MCP 服务器连接到每个智能体。这是将 CodeGraph 连接到你的智能体的步骤； 第 1 步安装 CLI 本身并不会完成这一步。它只连接你的智能体 — 它不会索引任何代码；构建每个项目的图是第 3 步中单独的 codegraph init 命令。（快捷方式：npx @colbymchenry/codegraph 一次下载并运行。）}

3. 初始化每个项目

cd your-project
codegraph init

_{codegraph init 会创建本地 .codegraph/ 目录并在同一步骤构建完整图 — 一条命令，完成。}

4. 无需再同步！

自动同步默认启用。CodeGraph 会监视项目，并在每次文件变更时更新图 — 当你的智能体编辑代码，或你添加、修改、删除文件时。索引永远不会过时，无需重新运行任何东西。

卸载

改变主意了？一条命令即可从所有已配置的智能体中移除 CodeGraph，以及 CLI 本身 — 它会找到每一个安装（独立包、npm 全局包、启动器链接），在删除任何内容之前展示给你：

codegraph uninstall

传递 --keep-cli 仅移除智能体配置并保留 CLI 安装。

_{逆转安装程序 — 从每个已配置的智能体中移除 CodeGraph 的 MCP 服务器配置、指令和权限。你的项目索引（.codegraph/）保持不变；使用 codegraph uninit 按项目移除。使用 --target 从特定智能体移除，或使用 --yes 以非交互方式运行。}

语言支持

以下每种语言都获得相同的处理 — 完整结构提取和跨文件解析为一个图，无需按语言配置：

_{各语言详情——扩展、框架以及具体提取内容——见支持的语言。}

为什么选择 CodeGraph？

当 AI 代理需要理解代码——回答问题或进行修改时——它只能通过缓慢的方式发现结构：grep、glob 和 Read，一次一个文件，手动重建调用路径和依赖关系。在真正开始工作之前，这已经是一大堆工具调用和往返。

CodeGraph 通过一次调用将 AI 代理所需的精确代码交给它。 它是一个预构建的知识图谱，包含代码库中的每个符号、调用边和依赖关系——因此，AI 代理无需爬取文件，只需问一个问题，就能得到相关源代码、这些符号之间的调用路径（包括 grep 无法追踪的动态分发跳转）以及变更的影响范围。精确的上下文，而非按文件搜索——这意味着更少的工具调用，无论代码库大小，都能更快得到答案。

关于成本的说明： CodeGraph 在每个代码库上的优势在于精确性——AI 代理停止爬取文件，直接从图谱中获取答案。在当前模型上，这种精确性也带来了巨大的直接节省：2026 年 7 月重新验证的结果显示，在七个基准仓库中，平均成本降低 60%，Token 数减少 69%，因为一个强大的模型没有图谱会消耗数百万个 Token 来重新推导结构。节省成本随仓库规模和复杂性增加而扩大——在 VS-Code 规模的树上效果显著，在 100 个文件的项目上则较小——并且随着团队日常使用 AI 代理而累积。

基准测试结果

在 7 个真实世界的开源代码库（涵盖 7 种语言）上进行测试，对比一个 AI 代理（Claude Code，无头模式）在使用和不使用 CodeGraph 的情况下回答一个架构问题，每组中位数 4 次运行。2026 年 7 月 21 日使用 Claude Opus 4.8 在当前构建版本上重新验证——包括 Rust 内核以及本轮的重大改进。

普遍优胜——每个仓库，无论大小：工具调用减少 89% · 成本降低 60% · Token 数减少 69% · 七个仓库的文件读取次数全部降为零。

有索引的情况下，AI 代理通过几次 codegraph_explore 调用即可回答并停止。没有索引时，AI 代理将预算浪费在发现上——最多 57 次工具调用和 4.3M 个 Token，重新推导图谱已经知道的内容。Time 列平均快 20%，但这是最不稳定的指标：在两个小型仓库上，一个强模型的原始 grep 循环在墙上时间上更快完成，但仍消耗 5–10 倍的 Token 和资金——具体见下方每行备注。

_{¹ 小型仓库的底层效应：Opus 4.8 对小型树进行 grep 的速度足够快，在墙上时间上获胜，但消耗了约 5–10 倍的 Token 和约 4–7 倍的成本——使用图谱的版本仍从零文件读取中回答。² OkHttp 的未使用图谱版本在 5 次调用中运气较好；使用图谱版本在 1 次调用中回答，成本多约 $0.03。文件读取 = 中位数打开的文件数——精确上下文优势在一列中体现：当 CodeGraph 存在时，AI 代理在七个仓库中从未读取任何文件。}

为速度而生——Rust 内核

CodeGraph 的解析引擎是一个原生 Rust 内核：20 种语言——TypeScript、JavaScript、Java、Python、Go、C、C++、Rust、C#、Ruby、PHP、Swift、Kotlin、Scala、Dart、R、Lua、Luau（Metal 和 CUDA 走 C++ 路径）——在编译代码中解析，每个文件仅跨越一次边界。每种语言仅在其实时仓库上的图谱与参考引擎逐字节相同后才发布，从小型库到 Linux 内核；没有预构建二进制文件的平台以及包含语法错误的文件会自动逐文件回退，无论哪种方式，图谱相同。

它会根据你的机器自动调整规模。 工作池、并行解析和分析缓存都根据系统实际资源进行调节——真实的核心数（支持容器/cgroup 感知，因此一个分配了 2 核的 VPS 会按 2 核而非宿主机的 64 核进行配置）、macOS 和 Linux 上诚实测量的可用内存，以及你项目的解析工作实测成本：

• 在工作站上： 完整的并行流水线——原生解析工作器、一个在证明自身价值时立即启动的多工作器解析器池、受内存限制的分析缓存。Swift 编译器仓库（27k 个 Swift 和 C++ 文件）全新索引约需 100 秒；单文件编辑后重新同步约 4 秒。
• 在 2 核 / 6GB VPS 上： 相同的图，使用针对完成而优化的流水线——Linux 内核（70k 个文件，2M 个符号，6.4M 个关系）可在 12 分钟内完成索引，而优先考虑内存的设计在达到 1% 之前就已耗尽内存。
• 第一天之后的每一天： 保存文件后，图在远低于 1 秒的时间内更新——监视器在单次保存后 300ms 触发，并精确同步变化的内容（在 4,400 个文件的项目上约 0.3 秒，在 27,000 个文件的 Swift 编译器仓库上约 0.4 秒），从不重新扫描整个树。与最快的竞争索引器的变更后重新索引相比：在涉及 31 个仓库、30 种语言的基准测试中，对中型和大型仓库快 2–7 倍——并且差距随仓库规模扩大而增大，因为它们的成本随仓库增长，而我们的成本随变更增长。

关键特性

agent 写入 src/Widget.ts
  → 监视器触发 (<100ms)
  → 防抖 (默认 2s)
  → 同步；Widget.ts 已进入索引
  → 下次代理查询看到它

框架感知的路由

CodeGraph 检测 Web 框架路由文件，并输出通过 references 边链接到其处理程序类或函数的 route 节点。查询视图/控制器的调用者现在会显示绑定它的 URL 模式。

混合 iOS / React Native / Expo 桥接

真实的 iOS 与 React Native 代码库横跨多种语言——Swift 调用方调用一个已自动桥接的 Objective-C 选择器，JS 文件通过 React Native 桥接调用原生模块，JSX 组件委托给原生视图管理器。静态 tree-sitter 提取会在每个语言边界处停止。CodeGraph 将这些边界桥接起来，使得 codegraph_explore 能够跨越语言边界端到端连接调用流程——调用路径和影响范围得以跨越边界，而非止步于边界。

在真实代码库上验证（每个桥接类型均覆盖小、中、大规模）：

每个桥接类型生成的边带有 provenance:'heuristic' 标签，并设置 metadata.synthesizedBy: 为稳定的通道名称（例如 swift-objc-bridge、rn-event-channel、fabric-native-impl、expo-module-extract），以便智能体一眼就能看出该跳转是如何进入图的。

快速开始

1. 运行安装程序

npx @colbymchenry/codegraph

安装程序将：

• 询问要配置哪些智能体——自动检测已安装的智能体，包括：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro
• 提示是否将 codegraph 安装到 PATH（以便智能体启动 MCP 服务器）
• 询问配置是应用于所有项目还是仅当前项目
• 为每个选中的智能体写入 MCP 服务器配置，并在智能体的指令文件（CLAUDE.md / AGENTS.md / GEMINI.md）中添加一个带有标记围栏的 CodeGraph 小节——这样子智能体和非 MCP 智能体就能学习 codegraph explore 命令，因为 MCP 服务器自身的指导只会到达主智能体。通过 codegraph uninstall 可干净移除。
• 当 Claude Code 是目标之一时，设置自动允许权限

安装程序**仅配置你的智能体——不会索引你的代码。**安装完成后，请自行使用 codegraph init（步骤 3）构建每个项目的图。一个全局的 codegraph install 覆盖所有项目；每个项目只需运行一次 codegraph init。

非交互式（脚本/CI）：

codegraph install --yes                              # 自动检测智能体，全局安装
codegraph install --target=cursor,claude --yes       # 显式指定目标列表
codegraph install --target=auto --location=local     # 检测到的智能体，项目本地安装
codegraph install --print-config codex               # 打印配置片段，不写入文件

2. 重启你的智能体

重启你的智能体（Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro），以便 MCP 服务器加载。

3. 初始化项目

cd your-project
codegraph init

构建每个项目的知识图谱索引，之后会在每次文件变更时自动同步。一个全局的 codegraph install 在你打开的任何项目中都能工作——无需在每个项目中重新运行安装程序。

就这么简单——当存在 .codegraph/ 目录时，你的智能体将自动使用 CodeGraph 工具。

npm install -g @colbymchenry/codegraph

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

{
  "permissions": {
    "allow": [
      "mcp__codegraph__*"
    ]
  }
}

原文精确文本是 src/mcp/server-instructions.ts —— 主 agent 的唯一事实来源。由于子 agent 和非 MCP 的 harness 永远不会看到 MCP 指引，安装程序还会在 agent 的指令文件中写入一个简短的分隔标记区域，指向等效的 codegraph explore CLI 命令。

工作原理

┌───────────────────────────────────────────────────────────────────┐
│                            Claude Code                            │
│                                                                   │
│   "请求是如何到达数据库的？"                                         │
│       直接调用 CodeGraph 工具 —— 无需 Explore 子 agent                │
│                                 │                                 │
└─────────────────────────────────┬─────────────────────────────────┘
                                  │
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│                        CodeGraph MCP 服务器                        │
│                                                                   │
│ explore  ·  一次调用 → 逐字源码 + 调用流 + 影响范围                   │
│                                 │                                 │
│                                 ▼                                 │
│                       SQLite 知识图谱                               │
│          符号 · 边 · 文件 · FTS5 全文搜索                           │
└───────────────────────────────────────────────────────────────────┘

1. 提取 —— 原生 Rust 内核 使用编译到其中的 tree-sitter 语法解析源码，提取节点（函数、类、方法）和边（调用、导入、继承、实现），支持 20 种语言；其余语言和按文件的后备方案使用可移植引擎上的相同提取逻辑，生成相同的图。

2. 存储 —— 所有内容都放入本地 SQLite 数据库（.codegraph/codegraph.db），并启用 FTS5 全文搜索。

3. 解析 —— 提取完成后，解析引用：函数调用 → 定义，导入 → 源文件，类继承，以及框架特定模式。

4. 自动同步 —— MCP 服务器使用原生操作系统文件事件监控你的项目。变更经过防抖处理（2 秒静默窗口），仅过滤到源文件，并增量同步。在你编码时图谱保持最新 —— 无需配置。

CLI 参考

codegraph                         # 运行交互式安装程序
codegraph install                 # 运行安装程序（显式）
codegraph uninstall               # 从 agent 和 CLI 中移除 CodeGraph（--keep-cli 仅保留配置）
codegraph init [path]             # 初始化项目 + 构建图谱（一步完成）
codegraph uninit [path]           # 从项目中移除 CodeGraph（--force 跳过确认）
codegraph index [path]            # 完整索引（--force 重新索引，--quiet 减少输出）
codegraph sync [path]             # 增量更新
codegraph status [path]           # 显示统计信息
codegraph unlock [path]           # 移除阻止索引的过期锁文件
codegraph query <search>          # 搜索符号（--kind, --limit, --json）
codegraph explore <query>         # 一次获取相关符号的源码 + 调用路径（与 codegraph_explore MCP 工具输出相同）
codegraph node <symbol|file>      # 单个符号的源码 + 调用者，或读取带行号的文件（与 codegraph_node 输出相同）
codegraph files [path]            # 显示文件结构（--format, --filter, --max-depth, --json）
codegraph callers <symbol>        # 查找哪些代码调用了函数/方法（--limit, --json）
codegraph callees <symbol>        # 查找函数/方法调用了哪些代码（--limit, --json）
codegraph impact <symbol>         # 分析更改符号会影响哪些代码（--depth, --json）
codegraph affected [files...]     # 查找受更改影响的测试文件（见下文）
codegraph daemon                  # 管理后台守护进程 —— 选择一个停止（别名：daemons）
codegraph telemetry [on|off]      # 显示或更改匿名使用遥测
codegraph upgrade [version]       # 更新到最新版本（--check, --force）
codegraph version                 # 打印已安装的版本（也可用 -v, --version）
codegraph help [command]          # 显示帮助，可选指定命令

codegraph affected

递归跟踪导入依赖关系，找出受更改源文件影响的测试文件。

codegraph affected src/utils.ts src/api.ts         # 将文件作为参数传递
git diff --name-only | codegraph affected --stdin   # 从 git diff 管道输入
codegraph affected src/auth.ts --filter "e2e/*"     # 自定义测试文件模式

CI/hook 示例：

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

MCP 工具

当作为 MCP 服务器运行时，CodeGraph 暴露 单个工具 —— codegraph_explore。实测 agent 行为表明，一个强大工具比多个更窄的工具能更好地引导 agent —— 减少误选，并每次会话节省上下文：

其他工具（codegraph_node、codegraph_search、codegraph_callers、codegraph_callees、codegraph_impact、codegraph_files、codegraph_status）保持完全可用，但 默认不列出 —— 它们返回的所有内容都已经内联在 codegraph_explore 中（其影响范围部分、关系图、符号体作为被调用者列表）。可通过 CODEGRAPH_MCP_TOOLS 环境变量（例如 CODEGRAPH_MCP_TOOLS=explore,node,search,callers）重新启用其中任意工具供 MCP 表面使用，或使用它们的 CLI 等效命令（codegraph node / query / callers / callees / impact / files / status）。

即使服务器自身的根目录没有 .codegraph/ 索引，这些工具仍然可用：传递 projectPath 即可查询任何已索引的项目 —— 无论是单体仓库中的子服务，还是另一个仓库 —— 在同一个会话中。没有索引的路径会返回清晰的指引，建议改用内置工具，因此不会出现严重错误，是否索引仍由你决定。

库用法

CodeGraph 可以直接嵌入。npm 包重新导出了其编程 API，因此 import 和 require 都能在你自己的进程中解析出 CodeGraph 类——方便在应用（如 Electron 主进程）中嵌入。

import CodeGraph from '@colbymchenry/codegraph';
// CommonJS 同样可用：
//   const { CodeGraph } = require('@colbymchenry/codegraph');

const cg = await CodeGraph.init('/path/to/project');
// 或者：const cg = await CodeGraph.open('/path/to/project');

await cg.indexAll({
  onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
});

const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' });
const impact = cg.getImpactRadius(results[0].node.id, 2);

cg.watch();   // 文件变更时自动同步
cg.unwatch(); // 停止监听
cg.close();

从同一入口点还导出了更底层的构建块，供直接驱动图结构的调用者使用：DatabaseConnection、QueryBuilder、getDatabasePath、initGrammars / loadGrammarsForLanguages 和 FileLock。

嵌入要求

• 从 npm 安装（npm i @colbymchenry/codegraph），以便在获取填充层的同时，一并拉取匹配的平台包——其中包含编译后的库及其依赖。
• API 运行在你的运行时上，因此需要 Node 22.5+ 以使用内置的 node:sqlite（当 Electron 捆绑的 Node 版本为 22.5+ 时，它也符合条件）。CLI 和 MCP 服务器不受影响——它们运行在自包含的捆绑运行时上。
• TypeScript 类型随包一起提供。与任何面向 Node 的库一样，请确保 @types/node 可用，并且 skipLibCheck: true（这是常见默认值）。

配置

几乎不需要配置——CodeGraph 默认零配置，无需编写或同步任何内容即可开始使用。语言支持通过文件扩展名自动完成；无需为每种语言进行额外配置。唯一的可选文件用于映射自定义文件扩展名。

默认跳过的内容：

• 依赖、构建和缓存目录——node_modules、vendor、dist、build、target、.venv、Pods、.next 以及所有支持技术栈中的类似目录——因此图中只包含你的代码，不含第三方噪音。即使没有 .gitignore 也是如此。
• .gitignore 中的任何内容——在 git 仓库中通过 git 识别，在非 git 项目中通过直接读取 .gitignore（根目录及嵌套）识别。
• 大于 1 MB 的文件——生成的包、压缩后的 JS、供应商提供的二进制文件。

要排除其他内容，请将其添加到 .gitignore。要将默认排除的目录重新包含（例如你真的希望索引一个供应商提供的依赖项），请添加取反规则——!vendor/。默认规则统一应用，因此提交依赖或构建目录不会强制将其纳入图中；.gitignore 的取反规则是显式的选择加入。

但 .gitignore 无法删除已提交的目录。对于已检入仓库的供应商主题或 SDK（例如位于 static/ 下的 Metronic 主题），请在 codegraph.json 的 exclude 中列出——使用类似于 gitignore 的模式，匹配仓库根目录相对路径，在索引、同步和监听时生效：

{
  "exclude": ["static/", "**/vendor/**"]
}

相反，当真正的源代码因某种原因被 gitignore 时——例如一个项目使用了第二种 VCS（SVN、Perforce），并且它 .gitignore 了自己的源代码以使其不进入 Git——请使用 include（与 exclude 相反；includeIgnored 仅恢复嵌入的 git 仓库，不恢复普通源代码）将其强制重新包含：

{
  "include": ["Tools/", "Local/typescript/"]
}

CodeGraph 会在索引、同步和监听时从磁盘发现这些文件，覆盖 .gitignore。显式的 exclude 仍然优先，内置的跳过项（node_modules、dist、.git）永远不会被重新包含。

自定义文件扩展名

如果你的项目对支持的语言使用了非标准扩展名——例如 .dota_lua 用于 Lua，或 .tpl 用于 PHP——这些文件默认会被跳过，因为该扩展名不是 CodeGraph 识别的。通过项目根目录下可选的 codegraph.json 进行映射：

{
  "extensions": {
    ".dota_lua": "lua",
    ".tpl": "php"
  }
}

每个值都是支持的语言 ID。映射会合并到内置默认值之上，冲突时以映射为准，因此你也可以重新映射内置扩展名（例如 ".h": "cpp"）。提交该文件以与团队共享映射。语言拼写错误或格式错误的文件会收到警告并被跳过——绝不会中断索引——没有 codegraph.json 的项目行为与之前完全相同。添加或更改映射后，请重新索引（codegraph index）。

遥测

CodeGraph 收集匿名使用统计信息——哪些工具和命令被使用，哪些语言被索引——以指导语言和代理支持工作的方向。绝不收集任何代码、路径、文件或符号名称、查询或 IP 地址；使用情况会在发送前在本地聚合为每日总计，并且接收端点位于本仓库的公开代码中，该代码强制执行文档中列出的字段列表。安装程序会事先询问；随时关闭：

codegraph telemetry off    # 或：CODEGRAPH_TELEMETRY=0，或 DO_NOT_TRACK=1

TELEMETRY.md 列出了每个字段，以及关闭开关和完整的数据处理说明。

已验证的发布版本

每个工件均由公开的发布工作流构建和发布——绝不会从笔记本电脑发布——并带有加密的证明：

• npm 包通过可信发布（OIDC——不存在可能被盗用的长期 npm 令牌）发布，并带有来源证明，将每个版本链接到构建它的确切提交和工作流运行。验证已安装的包：

  npm audit signatures

• GitHub Release 包（以及 SHA256SUMS）带有签名的构建证明（SLSA v1.0 Build Level 2）。验证任何下载的包：

  gh attestation verify codegraph-darwin-arm64.tar.gz -R colbymchenry/codegraph

2026 年 7 月之前发布的版本早于该流水线，不带有证明。

支持的平台

每个版本都提供适用于所有三种桌面操作系统、Intel/AMD (x64) 和 ARM (arm64) 的自包含构建（捆绑的 Node 运行时——无需编译）：

有关一键安装命令，请参见开始使用。

支持的 Agent

交互式安装程序会自动检测并配置以下每一项——连接 MCP 服务器（该服务器自带使用指南，因此无需写入说明文件）：

• Claude Code
• Cursor
• Codex CLI
• opencode
• Hermes Agent
• Gemini CLI
• Antigravity IDE
• Kiro

支持的语言

实测跨文件覆盖率

影响范围与影响半径查询的优劣取决于其背后的依赖图，因此覆盖率是实测而非声称的。良好覆盖率 = 在每种语言的真实基准仓库中，至少有一个已解析的跨文件依赖者（即导入、调用、引用或通过框架约定路由到它）的含符号源文件所占比例。剩余部分始终是真正的静态分析边界（运行时动态分发、反射/DI 容器、框架约定入口点、第三方供应商代码），绝不会通过操纵分母来隐藏。

框架路由的验证方式相同，基于每个框架的规范应用：Express 100%、FastAPI 98%、Flask 100%、NestJS 96.8%、Gin 96.5%、Axum 100%、Rocket 93.8%、Vapor 100%、Laravel 92%、Rails 89.6%、React Router 100%——而那些依赖约定/反射的框架则达到了其静态分析的上限：ASP.NET 83.9%、Spring 83.3%、Drupal 78.9%、Play 76.3%、Django 74.1%。SvelteKit、Vue/Nuxt 和 Astro 使用基于文件的路由，因此它们的页面/端点覆盖率与上表中的数值一致：Svelte/SvelteKit (100%)、Vue/Nuxt (93.5%) 和 Astro (93.0%——src/pages/ 中的每个文件都映射到两个验证仓库中的一个路由节点)。

问题排查

“CodeGraph not initialized” — 请先在项目目录中运行 codegraph init。

索引速度慢 — 检查是否已排除 node_modules 和其他大型目录。使用 --quiet 可减少输出开销。

MCP 遇到 database is locked — 当前版本不应出现此问题：CodeGraph 自带 Node 运行时，并使用 Node 内置的 node:sqlite（WAL 模式），在此模式下并发读取不会阻塞写入操作。如果仍然遇到此问题：

• 你使用的是旧版本（0.9 之前）。 重新安装以获取自带的运行时 — curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh（macOS/Linux）、irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex（Windows）或 npm i -g @colbymchenry/codegraph@latest。
• codegraph status 显示 Journal: 不是 wal — 在此文件系统上无法启用 WAL（常见于网络共享和 WSL2 的 /mnt 目录），因此读取可能会阻塞写入。请将项目（及其 .codegraph/ 文件夹）移至本地磁盘。

MCP 服务器无法连接 — 你的代理会自动启动服务器，因此你无需手动启动。请确保项目已初始化并建立索引（codegraph status），且 MCP 配置中的路径正确。如果仍然无法连接，请重新运行 codegraph install 以重写配置。

MCP 工具调用失败，显示 Transport closed，但 codegraph status/sync 正常 — 这几乎总是发生在 WSL2 中，且项目位于 Windows 驱动器上（/mnt/c 或 /mnt/d 路径），此时 CodeGraph 用于在会话间共享一个后台服务器的本地套接字不可靠。CodeGraph 现在会回退到进程内提供会话服务，而不是断开连接；但如果仍然遇到此问题，请在 MCP 服务器的环境变量中设置 CODEGRAPH_NO_DAEMON=1，以完全跳过共享服务器（每个会话在其自己的进程中运行）。将项目移到 Linux 原生文件系统（例如 ~/ 下而不是 /mnt/）即可恢复共享服务器。

缺少符号 — MCP 服务器会在保存时自动同步（等待几秒钟）。如有需要，可手动运行 codegraph sync。请检查文件的语言是否受支持，且文件不在 .gitignore 或默认排除的目录（如 node_modules、dist）中。

在 Windows 和 WSL 之间共享同一个检出目录 — 不要将两者指向同一个 .codegraph/：后台服务器锁和 SQLite 索引与写入它们的操作系统绑定，且跨 WSL2/Windows 文件系统边界的 SQLite 锁定不可靠。通过在其中一个系统上设置 CODEGRAPH_DIR 为不同的名称，让每个系统在同一目录树中拥有自己的索引——例如，在 Windows 上设置 CODEGRAPH_DIR=.codegraph-win，WSL 则使用默认的 .codegraph。CodeGraph 在索引和监视时会跳过任何同级的 .codegraph-* 目录，因此两者不会互相干扰。

许可证

MIT