CodeGraph 深度调研报告

🎉 最新版本：v1.0.1（2026-06-13 发布，1.0 正式版） 入口地址：https://github.com/colbymchenry/codegraph 官网/文档：https://colbymchenry.github.io/codegraph/ npm 包：npx @colbymchenry/codegraph Stars：53,202 ⭐ （+6,761 / +14.6% 同比上次）| Forks：3,246 | License：MIT | 语言：TypeScript 商业化：getcodegraph.com Cloud Platform waitlist 开放 Twitter：@getcodegraph 日期：2026-06-23 | 上次更新：2026-06-10 | 调研人：小K ✨

一、项目概览

CodeGraph 是一个本地优先的代码智能工具，将任意代码库转换为可查询的知识图谱，通过 MCP 协议暴露给 AI Coding 代理。

🚀 里程碑更新（2026-06-12）：从 0.9.x Beta 正式发布 v1.0.0（06-12），次日发布 v1.0.1（06-13）。1.0 版本标志着生产就绪。

核心价值主张（7 个代码库中位数）： - ~58% 更少 tool calls（file reads 降至近零） - ~22% 更快（执行时间） - ~47% 更少 tokens - ~16% 更便宜（成本）

100% 本地运行：数据不离开你的机器，不需要 API key，不需要外部服务。SQLite 数据库 + FTS5 全文索引。

支持的代理（8 个）：Claude Code · Cursor · Codex CLI · opencode · Hermes Agent · Gemini CLI · Antigravity IDE · Kiro

支持的语言（24 种）：TypeScript · JavaScript · Python · Go · Rust · Java · C# · PHP · Ruby · C · C++ · Objective-C · Swift · Kotlin · Scala · Dart · Svelte · Vue · Astro · Liquid · Pascal/Delphi · Lua · Luau · R

支持的 Web 框架（17 种）：Django · Flask · FastAPI · Express · NestJS · Laravel · Drupal · Rails · Spring · Play · Gin/chi/gorilla/mux · Axum/actix/Rocket · ASP.NET · Vapor · React Router/SvelteKit · Vue Router/Nuxt · Astro

二、入口地址一览

三、实现原理

3.1 整体架构

files → ExtractionOrchestrator (tree-sitter) → DB (nodes/edges/files)
              ↓
       ReferenceResolver (imports, name-matching, framework patterns)
              ↓
       GraphQueryManager / GraphTraverser (callers, callees, impact)
              ↓
       ContextBuilder (markdown/JSON for AI consumption)

四层流水线：

1. Extraction Layer：tree-sitter 解析源码为 AST，语言特定提取器抽取节点和边
2. Resolution Layer：解析引用——导入→源文件、函数调用→定义、类继承、框架特定模式
3. Graph Layer：图遍历（ callers/callees/impact/trace）
4. Context Layer：为 AI 消费构建上下文（markdown/JSON）

3.2 模块结构（src/）

3.3 数据模型：NodeKind 和 EdgeKind

NodeKind（节点类型）：

file, module, class, struct, interface, trait, protocol, function, method, property, field, variable, constant, enum, enum_member, type_alias, namespace, parameter, import, export, route, component

EdgeKind（边类型）：

contains, calls, imports, exports, extends, implements, references, type_of, returns, instantiates, overrides, decorates

3.4 核心技术：tree-sitter 解析

• 为什么用 tree-sitter：增量解析、跨语言支持、AST 精确提取
• 解析引擎：tree-sitter 使用 WASM 格式的语法解析器（.wasm 文件），每个语言一个 grammar
• Worker 线程：parse-worker.ts 将重型解析任务移出主线程，避免阻塞
• 增量同步：FileWatcher 监听文件变化，防抖 2 秒窗口，只对变更文件增量更新

3.5 数据库：SQLite + FTS5

• 后端：better-sqlite3（原生 Node.js 绑定），回退到 node-sqlite3-wasm（WebAssembly）
• WAL 模式：Write-Ahead Logging，支持高并发读取，写入不阻塞读取
• FTS5：全文搜索索引，支持按名称模糊搜索符号
• 数据文件：.codegraph/codegraph.db（项目级，每项目独立）

3.6 引用解析（Reference Resolution）

ReferenceResolver 负责把字符串引用解析为真实图节点：

• import-resolver.ts：解析模块导入路径，支持 tsconfig path aliases 和 Cargo workspace member globs
• name-matcher.ts：按名称匹配符号（处理重载、歧义）
• frameworks/：14+ 种框架的特定路由识别（Express, Django, Flask, FastAPI, NestJS, Laravel, Rails, Spring, Gin, Axum, ASP.NET, Vapor, React Router, SvelteKit, Drupal）

3.7 动态派发桥接（Dynamic Dispatch Synthesis）

tree-sitter 只能提取静态调用边，动态派发（回调、EventEmitter、React setState→render）没有静态边。CodeGraph 通过合成边来桥接：

• src/resolution/callback-synthesizer.ts：合成 callback/observer 调用边
• React re-render：追踪 setState → render → JSX child component 的流程
• JSX child：追踪 render → child component 的隐式调用
• Django ORM descriptor：追踪 QuerySet 链式调用
• 合成边元数据：provenance:'heuristic' + metadata.synthesizedBy + registeredAt
• 原则：部分桥接比不桥接更糟——半完成的流会让 AI 读文件来补全，导致更多读取

3.8 MCP 协议实现

MCP server 通过 stdio 通信，暴露 10 个工具：

codegraph_search       # 按名称搜索符号
codegraph_context      # 构建任务上下文
codegraph_trace       # 追踪两个符号之间的路径（含动态派发）
codegraph_callers      # 查找调用者
codegraph_callees      # 查找被调用者
codegraph_impact       # 影响半径分析
codegraph_node         # 符号详情（含源码）
codegraph_explore      # 一次性探索多个相关符号
codegraph_files        # 文件结构（比文件系统扫描快）
codegraph_status       # 索引健康度

3.9 多代理安装器

支持 8 种 AI 代理的自动配置：

安装器自动检测已安装的代理，写入 MCP 配置。

3.10 探索预算（Explore Budget）

CodeGraph 的 codegraph_explore 工具根据仓库文件数动态调整输出预算：

原则：更大的层级永远不能比更小的层级获得更少的每文件输出。

四、使用场景

4.1 架构理解

场景：新加入项目，需要理解"请求如何从入口到达数据库"

codegraph_trace from=handleRequest to=getDataFromDB

输出完整的调用路径，每一跳显示源码内联，包括动态派发链。

4.2 影响分析

场景：修改一个底层函数，需要评估影响范围

codegraph_impact symbol=validateToken depth=2

追踪所有调用者，展开两跳影响半径，列出需要同步修改的文件。

4.3 测试影响评估

场景：代码变更后，找出需要运行的测试文件

git diff --name-only HEAD | codegraph affected --stdin --quiet

追踪 import 依赖传递链，找出受影响的测试文件，可接入 CI 钩子。

4.4 路由追踪

场景：了解某个 URL pattern 对应哪个处理器

codegraph callers /api/users

自动识别 Django/Flask/Rails 等框架的路由配置，找出绑定到 URL 的处理器。

4.5 大型代码库探索

场景：VS Code 级的大型代码库（~10k 文件）问架构问题

五、使用案例详解

5.1 Excalidraw 案例（TypeScript/React，643 文件）

问题："Excalidraw 如何渲染和更新画布元素？"

完整流程跨越三个 React 边界：

mutateElement
  → triggerUpdate（callback 合成边）
    → triggerRender（React re-render 合成边）
      → render（JSX child 合成边）
        → StaticCanvas
          → renderStaticScene

5.2 Tokio 案例（Rust，790 文件）

问题："Tokio 如何调度和运行异步任务？"

5.3 VS Code 案例（TypeScript，~10k 文件）

问题："扩展主机如何与主进程通信？"

六、Benchmark 数据汇总

测试方法：Claude Code (headless, Opus 4.8)，同一问题 WITH vs WITHOUT CodeGraph，各 4 次运行取中位数。 重新验证日期：2026-06-02

📊 注意：数据已更新！相比旧版 Opus 4.7 验证，新版 Opus 4.8 原生基线更强（主线程上直接高效执行 grep/read，而非派生出大范围 Explore 子代理），所以无 CodeGraph 对比臂也更精简，整体节省率看起来更低，但这是更强的原生基线带来的，CodeGraph 仍然在所有代码库上显著有效。

各代码库明细对比

VS Code · ~10k 文件

Excalidraw · ~640 文件

Django · ~3k 文件

Tokio · ~790 文件

OkHttp · ~645 文件

Gin · ~110 文件

Alamofire · ~110 文件

平均节省（7 个代码库）

测试问题（Queries）

七、新增特性（v1.0 重大升级）

📌 说明：本节对照 2026-06-10 版本（v0.9.x），列出 2026-06-23 版本（v1.0.1）的新增/重大升级特性。

7.1 跨语言混排支持（iOS / React Native / Expo）

CodeGraph 支持真实 iOS 和 React Native 代码库中的多语言混合场景：

🆕 v1.0 验证集（真实代码库）：

• Swift ↔ ObjC：Charts（小）/ realm-swift（中）/ Wikipedia-iOS（大）
• RN legacy bridge：AsyncStorage（小）/ react-native-svg（中）/ react-native-firebase（大）
• RN native → JS events：RNGeolocation（小）/ react-native-firebase（大）
• Expo Modules：expo-haptics（小）/ expo-camera（中）/ expo SDK sweep（大，7 包）
• Fabric / Paper views：react-native-segmented-control（小）/ react-native-screens（中）/ react-native-skia（大）

7.2 框架支持扩展

新增 Drupal 路由识别（*.routing.yml + hook_* 实现）、Play（Scala + Java）、Astro、Vue Router/Nuxt。

完整框架列表（17 种）：Django · Flask · FastAPI · Express · NestJS · Laravel · Drupal · Rails · Spring · Play · Gin/chi/gorilla/mux · Axum/actix/Rocket · ASP.NET · Vapor · React Router/SvelteKit · Vue Router/Nuxt · Astro

v1.0 框架 routing 验证覆盖率：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%。

7.3 索引新鲜度保障（Auto-Sync 升级）

三层保障机制确保图谱始终最新：

1. File watcher + 防抖自动同步：原生 OS 事件（FSEvents/inotify/ReadDirectoryChangesW），防抖窗口默认 2000ms（可通过 CODEGRAPH_WATCH_DEBOUNCE_MS 配置，范围 [100ms, 60s]）
2. 文件级过期警告（Staleness Banner）：防抖期间，MCP 响应中会附加 ⚠️ 警告，告知 Agent 哪些文件仍在等待索引，并建议直接 Read 获取实时内容
3. 连接时 Catch-up：MCP 服务器重新连接时，先进行（size + mtime）+ content-hash 对账，确保离线期间的编辑被吸收

7.4 嵌入 API（Embedding API）

CodeGraph 现已支持 Node.js 嵌入：

import CodeGraph from '@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();   // auto-sync on file changes
cg.unwatch(); // stop watching
cg.close();

// 底层构建模块（也通过同一 entry point 导出）：
// DatabaseConnection, QueryBuilder, getDatabasePath, initGrammars / loadGrammarsForLanguages, FileLock

嵌入要求：Node 22.5+（内置 node:sqlite），Electron 需捆绑 Node 22.5+。CLI 和 MCP server 不受影响（使用自包含运行时）。

7.5 Agent 工具引导（Tool Guidance）

CodeGraph 的 MCP server 在 initialize 响应中向 Agent 自动传递使用指南（无需修改 CLAUDE.md / AGENTS.md），告诉 Agent：

• 直接用 CodeGraph 回答结构性问题——它是预建的索引，grep/read 循环只是在重复工作
• 按意图选工具：codegraph_explore 适用于几乎所有场景；codegraph_search 仅定位符号；codegraph_callers/callees 走调用流；codegraph_impact 改前分析
• 信任结果——不要用 grep 重新验证，并留意编辑后的过期警告
• 如果 .codegraph/ 不存在，主动提示运行 codegraph init

🆕 v1.0 关键调整：MCP 工具收敛。实测发现：暴露多个工具会导致 Agent 误选更窄的工具；只暴露一个强工具反而效果更好。所以默认只暴露 codegraph_explore，其他 7 个工具（codegraph_node / codegraph_search / codegraph_callers / codegraph_callees / codegraph_impact / codegraph_files / codegraph_status）保留完整功能但默认不列出。可通过 CODEGRAPH_MCP_TOOLS=explore,node,search,callers 重新启用。它们的内容已经全部内联到 codegraph_explore 的 blast-radius、关系图、符号 body 里。

7.6 🆕 新增：GoFrame 路由支持（v1.0.1）

GoFrame（gogf/gf）的标准路由通过反射绑定（group.Bind(ctrl)）：路径和方法在 request type 的 g.Meta struct tag 中，运行时根据 request type 匹配 controller 方法——没有路径字符串、没有 route → handler 边。

解决方案：frameworks/goframe.ts 检测 gogf/gf in go.mod，将每个带路径的 g.Meta 抽取为 route 节点；goframe-synthesizer.ts 把 route 连接到 controller 方法（按 pkg.Type disambiguation）。

验证：gf-demo-user 7/7、gfast 65/68（3 个真无 handler）、hotgo 242/247（98%）—— 100% precision。

7.7 🆕 新增：C/C++ 函数指针派发（v1.0.1）

C/C++ 多态性的核心就是函数指针：struct fn-pointer field、concrete functions 通过 table 注册（{"add", cmd_add}）、designated initializer（.handler = on_open），或赋值后间接派发（p->fn(argv)）。静态提取无法捕获注册→field 绑定和间接调用，导致 dispatcher→handler 边缺失。

解决方案：resolution-layer synthesizer 以 (struct type, fn-pointer field) 为键，分 pass 处理：收集 fn-pointer typedef → 解析 struct field layouts → 收集注册（位置、designated、赋值）→ 传播 field←field 赋值 → 链接间接派发到注册的 handler。

验证：git 502 edges（run_builtin→cmd_* + git_hash_algo/archiver/reftable vtables）、redis 357（dictType.hashFunction + connection/reply-object vtables）、curl 478（Curl_cwtype.do_init → deflate/gzip/brotli/zstd）；3 个仓库全部 0 非函数目标，node-stable。

7.8 🆕 新增：Java Lombok 合成（v1.0.1）

Lombok 在编译时生成 getter/setter、builder()、equals/hashCode/toString、@Slf4j log field——它们永远不会出现在源码 AST 中。静态提取会完全漏掉它们，导致 bean.getName()、User.builder()、log.info() 解析不到方法，调用链分析静默断裂。

解决方案：在 LanguageExtractor 上加 synthesizeMembers hook（class 仍在 scope stack、真实 members 已抽取后调用），Java 实现为 @Getter、@Setter、@Data、@Value、@Builder/@SuperBuilder、@ToString、@EqualsAndHashCode、@Log* 系列合成机械成员。每个节点锚定在 field/class name-token leaf，标 lombok decorator 和生成 annotation 名称的 docstring，永远不覆盖源码已声明的 member。

验证：eladmin（274 Java 文件，Lombok 重度使用）100% accessor precision（878/878 映射到真实 field），722 个之前断链的调用现在能解析；spring-petclinic（无 Lombok）control 合成 0 个。

7.9 🆕 新增：MCP 大仓首调用优化（v1.0.1）

在大型仓库（93k 文件 / 5.7GB DB 的 Java monorepo）上，serve --mcp 后第一个 tools/call 会 hang 10+ 分钟无输出，并触发 liveness watchdog SIGKILL。根因：post-open catch-up reconcile 做 ~2*N 同步 fs.existsSync/fs.statSync 调用 + load-all-files query，两个 non-yielding loop。

解决方案：(1) reconcile 改为 yield：ExtractionOrchestrator.sync() 用 yielding scanDirectoryAsync，两个 O(files) reconcile loop 每 1000 个文件 await setImmediate 一次。(2) catch-up gate 加时间盒：第一个 tools/call 最多等 CODEGRAPH_CATCHUP_GATE_TIMEOUT_MS（默认 3000ms），然后服务并让 reconcile 后台完成。=0 恢复旧的无界等待。

7.10 🆕 新增：自定义文件扩展名（v1.0.1）

ext → language 表是硬编码的，所以使用非标准扩展名（如 .dota_lua for Lua）的代码库中这些文件会被静默跳过——以前除了 patch 源码外没别的办法。

解决方案：在项目根加一个可选的 codegraph.json：

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

映射叠加在内置默认之上并优先于内置（所以可以重新指向内置，如 .h → cpp）。缺失或格式错误的配置是零配置的默认值——byte-identical 于之前行为。

7.11 🆕 新增：Telemetry 匿名统计（v1.0）

收集匿名使用统计（哪些工具/命令被用、哪些语言被索引），绝不会收集代码、路径、文件名、查询、IP 地址。本地聚合成日总和后再发送。ingest endpoint 是仓库里的公开代码（telemetry-worker/），强制执行文档化的字段列表。

关闭方式：

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

详见 TELEMETRY.md。

7.12 🆕 新增：Symlink 转出仓库支持（v1.0.1）

目录遍历有意跟随 repo 根内的 symlink 到外面的目标（标准 Dota custom-game 布局，game/ 和 content/ 链到 SDK 树）并枚举其下的文件。但读取路径通过严格的 symlink-escape guard 拒绝每一个，logging "Path traversal blocked in batch reader" 且不索引任何东西。

解决方案：给 validatePathWithinRoot 加 opt-in 的 allowSymlinkEscape，仅豁免 realpath-escape 拒绝（lexical ../ guard 仍然有效），在 3 个索引读取点（batch reader、indexFile、indexFileWithContent）传入。内容服务 sink（ContextBuilder、MCP tools）保持严格 guard。这保持 #527 模型：索引现在跟随 symlink，getCode 仍拒绝提供 out-of-root 内容。

7.13 🆕 新增：Git change detection ignore matcher（v1.0.1）

变更检测的 git fast path（collectGitStatus）用 git status 输出但只有 isSourceFile filter，假设 git 已经省略了忽略的路径。它没有：gitignore 对已 tracked 的文件不起作用，而内置默认排除（vendor/、node_modules/）根本不是 gitignore。所以 committed dependency dir 里 tracked 的文件或 .gitignored dir 下的文件，会作为"变更"被报告，而完整索引从未跟踪——codegraph status 报告幻影 pending changes，sync（filtered filesystem reconcile）永远不清除，公开的 getChangedFiles() API 返回同样错误的列表。

解决方案：每个递归层级应用 buildDefaultIgnore(repoDir)，匹配 repo-相对路径——结构上等同于完整索引路径的 ScopeIgnore，无额外 git 子进程调用。删除保持未过滤：getChangedFiles 只在路径已在 DB 中 tracked 时才动作。

7.14 🆕 新增：MCP 工具结果格式优化（v1.0.1）

MCP 工具结果对章节头用 Markdown ATX headings（##/###/####）—— Markdown 渲染客户端（如 Claude Code VSCode 扩展）会把它们放大到 H1–H4 字号，用超大行填充 transcript（在 search/explore 上最严重，噪声随结果数线性增长）。全部替换为 bold labels，保持结构但按正文大小渲染。CLI/TTY 输出（ContextBuilder）不变。

7.15 Cross-file 覆盖度量（README 新增）

影响 / blast-radius 查询的质量取决于背后的依赖图，所以覆盖度是被度量的而非断言。"Fair coverage" = 在该语言的真实 benchmark repo 上，有至少一个已解析的跨文件依赖（imports / calls / references / 框架约定路由）的符号承载源文件的比例。残余总是真实的静态分析前沿（运行时动态派发、反射 / DI 容器、框架约定入口、vendored 三方代码），不靠玩分母游戏。

八、快速上手

安装

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

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

# Node.js 环境
npm install -g @colbymchenry/codegraph

# 零安装运行（一行搞定）
npx @colbymchenry/codegraph

初始化项目

cd your-project
codegraph init             # 一步：建 .codegraph/ + 构建完整 graph

配置 AI 代理（自动）

codegraph install          # 自动检测并配置 8 种 agent

# 脚本 / CI 场景（非交互）
codegraph install --yes                                # 自动检测，全局
codegraph install --target=cursor,claude --yes         # 显式指定 agent
codegraph install --target=auto --location=local   # 检测 + 项目级
codegraph install --print-config codex               # 仅打印配置，不写文件

常用命令（v1.0 完整列表）

codegraph                          # 交互式安装器
codegraph install                  # 运行安装器（显式）
codegraph uninstall                # 从所有 agent 卸载（install 的逆操作）
codegraph init [path]              # 初始化项目 + 构建 graph（一步）
codegraph uninit [path]             # 移除项目的 codegraph（--force 跳过提示）
codegraph index [path]              # 完整索引（--force 重建，--quiet 减少输出）
codegraph sync [path]                # 增量更新
codegraph status [path]              # 查看统计（wal、pending sync、节点数）
codegraph unlock [path]              # 移除阻塞索引的 stale lock 文件
codegraph query <search>          # 搜索符号（--kind, --limit, --json）
codegraph explore <query>         # 一键获取相关符号源码 + 调用路径（等同于 codegraph_explore MCP tool）
codegraph node <symbol|file>      # 单个符号源码 + 调用者，或带行号读文件
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...]    # 找出受变更影响的测试文件（CI hook）
codegraph daemon                   # 管理后台守护进程（alias: daemons）
codegraph telemetry [on|off]  # 查看或切换匿名使用统计
codegraph upgrade [version]    # 更新到最新版（--check, --force）
codegraph version                  # 打印安装版本（同 -v, --version）
codegraph help [command]         # 显示帮助，可指定某个命令

🆕 codegraph affected 详解（CI/hook 关键工具）：追溯 import 依赖传递性，找出变更源文件影响哪些测试文件。

codegraph affected src/utils.ts src/api.ts           # 文件作为参数
git diff --name-only | codegraph affected --stdin    # 从 git diff pipe
codegraph affected src/auth.ts --filter "e2e/*"      # 自定义测试文件 glob

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 手动配置

// ~/.claude.json
{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

可选 — Claude Code 自动允许（~/.claude/settings.json）：

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

一个通配符自动批准所有 CodeGraph 工具——codegraph_explore 是默认唯一列出的，但如果通过 CODEGRAPH_MCP_TOOLS 重新启用其他工具，它们也已经允许，不再提示。

九、与 Hermes Agent 的关系

CodeGraph 明确支持 Hermes Agent 作为目标代理之一（v1.0 仍是 8 个 agent 中的一个）。Hermes Agent 是一个多代理协作框架，CodeGraph 为其提供代码知识图谱能力。

在 Hermes Agent 的多代理架构中，探索代理（Explore Agent）可以使用 CodeGraph 的 MCP 工具（默认 codegraph_explore）直接查询图谱，而不是派生出文件扫描子代理，从而显著降低 token 消耗和执行时间。

🔌 接入方式：运行 codegraph install，它会自动检测 Hermes Agent 并写入 MCP server 配置（~/.hermes/config.yaml 的 mcpServers 部分），加上在 AGENTS.md 中插入 marker-fenced 段指向 codegraph explore CLI 等价命令——为非 MCP 的 subagent 学习这个工具。

🆕 v1.0 关键变化：MCP 工具收敛到默认只暴露 codegraph_explore。对 Hermes Agent 而言，subagent 在没有 MCP guidance 时，AGENTS.md 中的 CLI fallback 段现在更关键。

十、总结

CodeGraph 是一个工程化程度极高的 AI Coding 辅助工具，2026-06-12 发布的 v1.0 标志着它从 Beta 走向生产就绪。核心创新：

1. 预索引知识图谱：把代码库预先索引为 SQLite 图数据库，AI 查询代替文件扫描 —— file reads 中位数降至 0
2. 动态派发桥接：合成边覆盖 React/回调/EventEmitter/Swift↔ObjC/RN Bridge/Fabric/Expo Modules 等动态调用场景
3. Framework 感知（17 种 web 框架）：URL pattern → 处理器直接映射，包括 Spring/Play/Drupal 等反射 / convention-heavy 框架
4. 零配置：语言自动检测（24 种），node_modules/vendor/.venv/dist/build 等自动过滤，无需配置文件
5. MCP 原生 + 工具收敛：为 8 种代理（Claude Code/Cursor/Codex/opencode/Hermes Agent/Gemini/Antigravity/Kiro）原生设计，默认只暴露 codegraph_explore 一个强工具，减少 Agent 误选
6. 跨语言混排（深度）：Swift↔ObjC 全套桥接、RN Legacy+TurboModules+Fabric+Paper 视图、Expo Modules DSL 解析
7. 索引新鲜度保障：三层机制（File watcher 防抖 + Staleness Banner + Connect-time Catch-up）确保 Agent 永远拿到最新索引，无需手动 sync
8. 🆕 编程语言深度支持（v1.0）：GoFrame 路由解析、C/C++ 函数指针派发（vtable/command-table/hook slot）、Java Lombok 合成成员
9. 🆕 大规模仓库优化（v1.0.1）：93k 文件 / 5.7GB Java monorepo 的 catch-up reconcile 不再 hang 10 分钟
10. 🆕 零配置扩展：codegraph.json 支持自定义扩展名（.dota_lua → lua 等），可重新指向内置（.h → cpp）
11. 🆕 Cloud Platform 启动（v1.0）：getcodegraph.com 开放 waitlist，"for every PR, know exactly what to test, what could break"
12. 🆕 Cross-file 覆盖度量（v1.0）：22 种语言在真实 benchmark repo 上的公平覆盖率公开（Python/Ruby/PHP/SvelteKit 100%，TypeScript 95.8%，Liquid 73.8%）

适用场景：

• 大型代码库（500+ 文件）—— 节省在大 repo 上才显化为 line item
• 需要理解架构和调用链的场景
• 多代理协作框架（Hermes Agent 等）
• 需要测试影响分析的开发工作流（codegraph affected + CI hook）
• iOS / Android 混合项目（Swift/ObjC/React Native/Expo Modules）
• Java/Lombok 重度项目、C/C++ 复杂派发、Go 多框架（gin/GoFrame）
• 任何"想拿到的不只是 grep 列表，而是精确上下文"的场景

v1.0 成熟度信号：

• MIT License 明确
• 商业化云平台 waitlist 已开放
• 53K stars、3.2K forks、233 open issues 表明社区活跃
• 32 个 npm 版本（含 v1.0.1）显示持续迭代
• 验证方法论公开透明（中位数 4 次运行 vs without CodeGraph 同问题对照）

报告生成时间：2026-06-23 09:42 GMT+8 上次更新：2026-06-10 18:30 GMT+8 本次更新亮点：v1.0 正式发布（2026-06-12）+ v1.0.1（2026-06-13）；新增 GoFrame/C++ 函数指针/Lombok 合成；MCP 工具收敛；商业化 Cloud Platform waitlist；Stars 53,202（+14.6%）；新增 8 种 agent、24 种语言、17 种框架 数据来源：GitHub README（2026-06-23 main 分支）+ GitHub API + npm registry + 最近 24 小时 8 个 commits 入口地址：https://github.com/colbymchenry/codegraph 官方文档：https://colbymchenry.github.io/codegraph/ 商业化云平台：https://getcodegraph.com Twitter：https://x.com/getcodegraph