目录

• 开始使用
• 语言支持
• 为什么选择 CodeGraph?
• 关键特性
• 框架感知路由
• 混合 iOS / React Native / Expo 桥接
• 快速入门
• 工作原理
• CLI 参考
• MCP 工具
• 库使用
• 配置
• 遥测
• 支持平台
• 支持代理
• 支持语言
• 测量的跨文件覆盖率
• 故障排除
• Star 历史
• 许可证

开始使用

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 本身——它会发现所有安装（独立 bundle、npm 全局包、启动器链接），并在删除任何内容之前向你显示：

codegraph uninstall

传递 --keep-cli 仅移除代理配置并保留已安装的 CLI。

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

语言支持

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

_{每种语言的详细信息（扩展、框架以及具体提取内容）见支持的语言。}

为什么选择 CodeGraph？

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

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

关于成本的说明： CodeGraph 在每个代码库上的优势是精确性和速度——更少的工具调用，更快的回答。它也能降低 token 和美元成本，但这些节省是规模相关的：在中等规模的代码库上微小且不显著，只有当仓库庞大且复杂时——例如 Google 或 Microsoft 的单一仓库规模，再乘以整个团队日常代理使用量——这些节省才会累积成真正的成本项。对于一个 500 文件的项目，为速度采用 CodeGraph；当代码库（和团队）变大时，成本节省才会显现。

基准测试结果

在 7 个真实世界的开源代码库（涵盖 7 种语言）上进行了测试，比较了代理（Claude Code，无头模式）在使用和未使用 CodeGraph 的情况下回答一个架构问题，取每支 4 次运行的中位数。在 Opus 4.8（2026-06-02）上，使用当前构建版本（以 codegraph_explore 为主要工具）重新验证。

普遍性优势——每个仓库，任何规模：工具调用减少 58% · 速度提升 22% · 文件读取降至接近零。

稳定且普遍的回报是精确上下文和速度：CodeGraph 将代理的 grep/find/Read 爬取压缩为几次直接查询——即使你询问的精确方法隐藏在数千行的文件中，也能返回结果——因此代理以近乎零文件读取的方式回答，而未使用 CodeGraph 的代理则将其预算花费在发现上。Tokens 和 Cost 列也是真实的，但——如上所述——它们是规模相关的：每次查询微小且不显著，只有在大型代码库、高使用量规模下才会累积成实际成本。

_{文件读取 = 代理使用与未使用 CodeGraph 时打开文件的中位数——这是精确上下文优势在一列中的体现。Tokens 和 Cost 是相同的有/无增量；它们具有方向性（随运行而变化），并且每次查询在绝对值上很小——这就是为什么它们只有在规模下才成为成本项。此外，codegraph_explore 还会将冗余的可互换实现折叠为签名，因此响应的大小取决于答案而非文件数量。}

Queries:

为何 CodeGraph 胜出：有了索引，智能体可以直接回答——通常一次 codegraph_explore 就能返回相关源码并停止，几乎不需读取文件。没有索引时，智能体在读取正确代码前，大部分预算都花在探索（find/ls/grep）上。CodeGraph 仅在直接查询时才起作用，因此其指令引导智能体直接回答，而不是将探索委托给文件读取子智能体——否则子智能体无论如何都会读取文件，CodeGraph 反而成了开销。

关键特性

智能体写入 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 能够端到端地跨越间隙连接流程——调用路径和影响范围可以跨越边界，而不是在边界处停止。

| 边界 | JS/Swift 端 | 原生端 | 方式 | |---|---|---|---|---| | Swift → ObjC | Swift obj.foo(bar:) | ObjC 选择子 -fooWithBar: | @objc 自动桥接规则（包括 init/property/protocol 形式）+ Cocoa 介词前缀（With/For/By/In/On/At/…） | | ObjC → Swift | ObjC [obj fooWithBar:] | Swift @objc func foo(bar:) | 反向桥接名称候选；验证源端的 @objc 暴露声明 | | React Native 传统桥接 | JS NativeModules.X.fn(...) | ObjC RCT_EXPORT_METHOD / RCT_REMAP_METHOD · Java/Kotlin @ReactMethod | 解析宏/注解声明，构建 JS 名称 → 原生方法映射 | | React Native TurboModules | JS import M from './NativeM'; M.fn(...) | 匹配 Codegen 规范的原生实现 | 将 Native<X>.ts 规范接口视为事实来源 | | RN 原生 → JS 事件 | JS new NativeEventEmitter(...).addListener('e', cb) | ObjC [self sendEventWithName:@"e" body:...] · Swift sendEvent(withName: "e", ...) · Java/Kotlin .emit("e", ...) | 以字面事件名键控的合成跨语言事件通道 | | Expo Modules | JS requireNativeModule('X').fn(...) | Swift / Kotlin Module { Name("X"); AsyncFunction("fn") { ... } } | 解析 Expo DSL 字面量；合成方法节点通过现有名称匹配进行解析 | | Fabric 视图组件 | JSX <MyView prop={v}/> | TS Codegen 规范 + 原生实现类 | 规范 → component 节点；基于约定的名称+后缀查找（View/ComponentView/Manager/ViewManager）桥接到原生 | | 传统 Paper 视图管理器 | JSX <MyView prop={v}/> | ObjC RCT_EXPORT_VIEW_PROPERTY · Java/Kotlin @ReactProp | 与 Fabric 相同 — Paper 时代的声明也会生成 component + property 节点 |

已在真实代码库上验证（每个桥接的小型/中型/大型示例）：

每个桥接发出的边都带有 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 —— 主代理的唯一真实来源。因为子代理和非 MCP 工具永远看不到 MCP 指南，安装程序还会在代理的指令文件中写入一个简短的标记围栏部分，指向对应的 codegraph explore CLI 命令。

工作原理

┌───────────────────────────────────────────────────────────────────┐
│                            Claude Code                            │
│                                                                   │
│   "How does a request reach the database?"                        │
│       calls CodeGraph tools directly — no Explore sub-agent       │
│                                 │                                 │
└─────────────────────────────────┬─────────────────────────────────┘
                                  │
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│                        CodeGraph MCP Server                       │
│                                                                   │
│ explore  ·  one call → verbatim source + call flow + blast radius │
│                                 │                                 │
│                                 ▼                                 │
│                       SQLite knowledge graph                      │
│          symbols · edges · files · FTS5 full-text search          │
└───────────────────────────────────────────────────────────────────┘

1. 提取 — tree-sitter 将源代码解析为 AST。语言特定的查询提取节点（函数、类、方法）和边（调用、导入、继承、实现）。

2. 存储 — 所有内容进入本地 SQLite 数据库（.codegraph/codegraph.db），支持 FTS5 全文搜索。

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

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

CLI 参考

codegraph                         # 运行交互式安装程序
codegraph install                 # 运行安装程序（显式）
codegraph uninstall               # 从代理和 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。实测代理行为表明，一个强大的工具比一组较窄的工具能更好地引导代理——更少误选，并且每次会话节省上下文：

其他工具（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 works too:
//   const { CodeGraph } = require('@colbymchenry/codegraph');

const cg = await CodeGraph.init('/path/to/project');
// Or: 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();   // auto-sync on file changes
cg.unwatch(); // stop watching
cg.close();

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

嵌入需求

• 通过 npm (npm i @colbymchenry/codegraph) 安装，以便匹配的按平台分发包（包含编译后的库及其依赖）与 shim 一同获取。
• 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 的文件 —— 生成的 bundle、压缩后的 JS、第三方 blob。

若要排除其他内容，请将其添加到 .gitignore。若要重新包含某个默认排除的目录（例如，你确实希望索引一个第三方依赖），请添加否定模式 —— !vendor/。默认设置统一适用，因此提交依赖或构建目录不会强制其进入图；.gitignore 否定模式是显式的选择加入。

不过，.gitignore 无法取消已提交的目录。对于已检入仓库的第三方主题或 SDK（例如 static/ 下的 Metronic 主题），请在 codegraph.json 的 exclude 下列出它们 —— 使用 gitignore 风格的模式，相对于仓库根目录匹配，并在索引、同步和监视时生效：

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

相反，当真实源代码被故意 gitignored 时（例如，一个项目使用了第二种版本控制系统（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"
  }
}

每个值都是一个支持的语言标识符。映射会合并到内置默认值之上，并在冲突时获胜，因此你也可以重新映射内置扩展（例如 ".h": "cpp"）。提交该文件以与团队成员共享映射。如果语言拼写错误或文件格式错误，会发出警告并跳过 —— 绝不会破坏索引 —— 没有 codegraph.json 的项目行为与之前完全一致。添加或更改映射后，请重新索引（codegraph index）。

遥测

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

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

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

支持的平台

每个版本都会为所有三大桌面操作系统（Intel/AMD x64 和 ARM arm64）发布一个自包含的构建（捆绑了 Node 运行时 —— 无需编译）：

参见 开始入门 了解一键安装命令。

支持的代理

交互式安装程序会自动检测并配置以下每种代理 —— 配置好 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-*，因此两者不会相互干扰。

Star 历史

许可证

MIT