CodeGraph 简介：本地优先的代码知识图谱，让 AI 编程代理免扫描文件回答结构问题

本文基于 CodeGraph 官方文档站中的 Introduction 页面（site/src/content/docs/getting-started/introduction.md）展开，讲清 CodeGraph 是什么、它要解决 AI 编程代理（Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro 等）的哪类效率问题、图里到底存了什么，以及"100% 本地"的具体含义。读完之后，你可以判断 CodeGraph 是否适合自己的仓库，并按文中的命令把 CLI、MCP 服务与项目索引跑起来。

一、CodeGraph 是什么：一个 local-first 的代码智能工具

原文档的第一段定义就是全文的骨架，直接引用其要点：

CodeGraph is a local-first code-intelligence tool. It parses your codebase with tree-sitter, stores every symbol, edge, and file in a local SQLite database, and exposes the result as a queryable knowledge graph — over the Model Context Protocol (MCP), a CLI, and a TypeScript library.

拆成三句话：

1. 解析：用 tree-sitter 把整个代码库解析成 AST，再从中提取符号、关系与文件信息；
2. 存储：所有节点（symbols）、边（edges）、文件（files）全部落进本地 SQLite 数据库；
3. 暴露：同一份索引通过三种接口对外提供——MCP 服务器、codegraph CLI、TypeScript 库。

它存在的目的，是让 AI 编程代理不用扫描文件就能回答结构性问题（structural questions without scanning files）。原文档点出了对照场景：没有索引时，代理要靠 grep、glob、Read 扇出展开，逐个文件重建"代码是怎么连起来的"；有了 CodeGraph 之后，代理直接查询预建索引，"在少数几次调用内拿到答案"（gets the answer in a handful of calls）。

这个目标在仓库 README 的"Agent Tool Guidance"一节里被进一步落实为对代理的指令——MCP 服务器在 initialize 响应中自动下发使用说明，要求代理"用 CodeGraph 直接回答结构性问题，把返回的源码视为已经读过，不要再用 grep 复核"。这段指令的单一事实来源在 src/mcp/server-instructions.ts。

二、Why it matters：把代理的预算从"发现"转到"作答"

原文档"Why it matters"一节的核心论断是：

When an agent explores a codebase, it spends most of its budget on discovery — finding the right files before it can read them.

即代理的开销大头不是"改代码"，而是发现——在真正读文件之前，先花大量工具调用找对文件。CodeGraph 把这个步骤整个拿掉：一次调用交付出需要的精确代码，符号关系、调用图、结构都不必逐文件重建。

原文档给出的基准数据是（"Tested across 7 real-world open-source codebases (median of 4 runs per arm)"，在 7 个真实开源代码库上、每臂 4 次运行的中位数）：

• 工具调用减少 58%
• 提速 22%
• 文件读取降到接近零

同时原文档对"省 token / 省钱"持克制态度：这是随规模才显现的附加收益（scale-dependent bonus）——在小型仓库上收益小且噪声大，只有当代码库（和团队）变大、批量运行时才真正可观。

仓库 README 中记录了一轮更新的、方法更严格的实测，可以作为对上述数字的延伸佐证（见 README.md 的 Benchmark Results 一节）。其要点：

• 2026-08-05 用 Claude Opus 4.8 无头运行，7 个覆盖 7 种语言的开源仓库，每臂 4 次取中位数；
• 测试架子在两臂都屏蔽了 codegraph CLI（净化 PATH + PreToolUse 钩子拒绝 Bash 调用 CLI），否则对照组会通过 Bash 摸到 CLI，污染对比——README 明确提到在未屏蔽的旧架子上，对照臂 28 次运行中有 26 次找到了 CLI；
• 结果：工具调用减少 88%、提速 53%、token 减少 62%、成本降低 44%，7 个仓库的文件读取全部降为 0。

分仓库明细（WITH vs WITHOUT，中位数）：

代码库	语言 · 规模	工具调用	耗时	文件读取	Token	成本
VS Code	TypeScript · ~11k 文件	2 vs 28	2.2×（58s vs 2m 10s）	0 vs 12	少 77%	省 71%
Excalidraw	TypeScript · ~640	2 vs 43	3.6×（45s vs 2m 42s）	0 vs 18	少 84%	省 78%
Django	Python · ~3k	3 vs 14	35%（54s vs 1m 23s）	0 vs 8.5	少 41%	省 13%
Tokio	Rust · ~790	3 vs 29	2.6×（1m 3s vs 2m 43s）	0 vs 19	少 65%	省 64%
OkHttp	Java · ~645	1 vs 6	43%（33s vs 58s）	0 vs 2	少 54%	省 21%
Gin	Go · ~110	1 vs 7	39%（28s vs 46s）	0 vs 4	少 52%	大致持平
Alamofire	Swift · ~110	4 vs 33	2.6×（54s vs 2m 22s）	0 vs 16.5	少 59%	省 57%

README 还给出一个重要补充，和原文档的克制表述一致：成本节省主要跟随"问题需要多少发现工作"，而不是单纯跟随仓库体积——需要 28–43 次工具调用才能答出的问题上省 57–78%，而 7 次调用就能到达答案的问题上收益就很平。此外 README 也如实披露了"吞吐换驻留"的代价：CodeGraph 一次性回传稠密原文并保持在工作窗口中，多轮会话结束时残留的检索上下文比逐文件 grep 的代理多约 80%（详见 docs/benchmarks/residual-context-occupancy.md）。

三、图里到底有什么：Symbols、Edges、Files

原文档"What's in the graph"一节列出三类内容：

• Symbols（符号） — 函数、类、方法、类型、路由、组件等；
• Edges（边） — 调用、导入、继承、引用，以及框架特定的关系；
• Files（文件） — 文件结构 + FTS5 全文搜索。

并强调一点：提取是确定性的（deterministic）——一律从 AST 推导，绝不用 LLM 摘要。这决定了图的内容可复现、可审计。

仓库中的 site/src/content/docs/core-concepts/knowledge-graph.md 给出了固定的 kind 词表，与原文档描述一一对应：

节点 kind：file、module、class、struct、interface、trait、protocol、function、method、property、field、variable、constant、enum、enum_member、type_alias、namespace、parameter、import、export、route、component。

边 kind：contains、calls、imports、exports、extends、implements、references、type_of、returns、instantiates、overrides、decorates。

来源标注（Provenance）：多数边直接来自 AST；少数在动态分发边界（静态解析跟不下去的地方，如回调、观察者、React 重渲染）由合成器补出，并打上 provenance: 'heuristic' 标记及产生它的接线位置，explore 输出与 node 轨迹里会内联展示，让代理看清每条连接从哪来。

从源码结构看，这套模型直接对应 src/db/schema.sql 的三张核心表：nodes（含 kind、qualified_name、起止行列、docstring、signature、可见性、装饰器等字段）、edges（source/target/kind/metadata/line/col/provenance）、files（path、content_hash、language、node_count、generated 等）。全文搜索由 nodes_fts 虚拟表（FTS5）承载，索引 name、qualified_name、docstring、signature 四个字段，并通过触发器与 nodes 表保持同步——这就是原文档"Files — structure plus full-text search (FTS5)"的落点。另外还有一张 name_segment_vocab 表，把符号名拆成小写词段（如 OrderStateMachine → order/state/machine），用于把自然语言提问里的词与图内符号名做校验。

查询侧同样对应原文档的三类内容：codegraph query（按名搜索，走 FTS5）、codegraph callers / callees（沿调用图单跳游走）、codegraph impact（计算传递性影响半径）、codegraph explore（一次调用返回多个相关符号的按文件分组源码 + 符号间调用路径 + 影响半径摘要）。

四、实现路径：提取、存储、解析、自动同步四段流水线

README 与 site/src/content/docs/core-concepts/how-it-works.md 描述了与"100% 本地"承诺配套的完整流水线，可作为理解上述三类内容的纵深材料：

1. 提取（Extraction）：tree-sitter 把源码解析为 AST，按语言特定查询提取节点与边。CodeGraph 的核心解析引擎是原生 Rust kernel（仓库中为 codegraph-kernel/ 下的 Cargo 项目），20 种语言在编译后的代码里解析、每文件一次边界跨越；其余语言与单文件降级（平台无预编译二进制、文件有语法错误时）走可移植引擎，产出逐字节一致的图。
2. 存储（Storage）：全部写入本地 SQLite 数据库 .codegraph/codegraph.db，带 FTS5 全文搜索，WAL 模式。
3. 解析（Resolution）：提取之后做引用解析——函数调用 → 定义、导入 → 源文件、类继承、框架特定模式（17 种 Web 框架的路由文件识别、iOS / React Native / Expo 跨语言桥接等，见 site/src/content/docs/core-concepts/resolution.md）。解析不了的引用会落到 unresolved_refs 表（状态 pending/failed），下次同步时可重试。
4. 自动同步（Auto-Sync）：MCP 服务器用原生 OS 文件事件（FSEvents / inotify / ReadDirectoryChangesW）监听项目，变更经防抖窗口（默认 2000ms）后增量同步；代理刚改完文件、同步窗口还没过的短暂间隙里，涉及待同步文件的 MCP 响应会加"陈旧警告"横幅提示代理直接 Read 该文件；MCP 重连时还会做一次基于 (size, mtime) + 内容哈希的对账，吸收上次会话期间的改动。从源码结构看，这部分分别落在 src/sync/watcher.ts、src/mcp/staleness 相关文件与 src/mcp/daemon-manager.ts 等模块中。

工程上的两个值得注意的点：解析池、并行解析 worker 池、分析缓存都按机器实际资源自适应（容器感知的真实核心数、实测可用内存、本项目解析成本的实测值）；README 给出的量级参考是 27k 文件 Swift 编译器仓库全量索引约 100 秒、单文件编辑重新同步约 4 秒，Linux 内核（70k 文件、2M 符号）在 2 核 6GB VPS 上 12 分钟内索引完成。

五、100% 本地：具体边界在哪

原文档"100% local"一节的承诺是：

No data leaves your machine. No API keys, no external services — just a SQLite database in .codegraph/.

落到仓库证据上：

• 项目索引就是 .codegraph/ 目录下的 SQLite 数据库（.codegraph/codegraph.db），无外部服务依赖；
• 包依赖面很小，package.json 的运行期依赖主要是 CLI/解析相关库（commander、tree-sitter-wasms、web-tree-sitter 等），没有任何模型/云 API 客户端；
• 唯一"出网"的可选行为是匿名使用遥测（只上报工具/命令使用与语言统计，不含代码、路径、文件/符号名、查询、IP，本地先聚合成每日总量），且安装时即询问、可随时关闭：codegraph telemetry off，或 CODEGRAPH_TELEMETRY=0、DO_NOT_TRACK=1。字段清单见 TELEMETRY.md。

也就是说，"100% 本地"指的是索引与查询链路完全在本机；遥测是唯一显式声明的可选例外，且默认由安装交互确认。

六、快速上手：从安装到第一个图

原文档的结尾指向 Quickstart 页（site/src/content/docs/getting-started/quickstart.md），完整流程分三步，以下命令以该页与 README.md 为准：

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

已有 Node 的话也可以 npm i -g @colbymchenry/codegraph。注意安装器只把 codegraph 放进 PATH、不改当前 shell——开一个新终端再继续。

2. 接入你的代理：

codegraph install

该命令自动检测并配置已安装的代理（Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro、GitHub Copilot 等），把 CodeGraph 的 MCP 服务器写进各自的配置，并在代理的指令文件（CLAUDE.md / AGENTS.md / GEMINI.md）里写入一小段带标记的 CodeGraph 说明，让子代理也能学会用 codegraph explore。注意：这一步只接线，不索引代码。脚本/CI 场景有非交互形式，如 codegraph install --yes --init（接线后顺手对当前项目建索引）、codegraph install --target=cursor,claude --yes、codegraph install --print-config codex（只打印片段不落盘）。

3. 每个项目初始化：

cd your-project
codegraph init

codegraph init 一步完成创建 .codegraph/ 并构建全量图。之后代理只要发现项目里有 .codegraph/ 目录就会自动使用 CodeGraph 工具，自动同步默认开启，索引不会过期、无需手动重跑。

MCP 侧的暴露面值得单独说明：服务器默认只列一个工具 codegraph_explore——README 的理由是"一个强工具比一篮窄工具更能引导代理"，误选更少、每轮省上下文。其余工具（codegraph_node、codegraph_search、codegraph_callers、codegraph_callees、codegraph_impact、codegraph_files、codegraph_status）功能完整但默认不列出，因为它们的返回内容已经内联在 codegraph_explore 里；需要时可用环境变量重新启用（如 CODEGRAPH_MCP_TOOLS=explore,node,search,callers）。跨项目查询时，工具支持传 projectPath，可在同一会话里查任意有索引的项目（monorepo 子服务、第二个仓库）；无索引的路径会返回干净提示让代理改用内建工具，而不是报错。工具清单与参数的完整参考见 site/src/content/docs/reference/mcp-server.md 和 site/src/content/docs/reference/cli.md。

CLI 常用命令（摘自 README 的 CLI Reference）：

codegraph status [path]        # 查看索引统计
codegraph query <search>       # 按名搜索符号（--kind, --limit, --json）
codegraph explore <query>      # 相关符号源码 + 调用路径，一次到位
codegraph node <symbol|file>   # 单符号源码与调用方，或按行号读文件
codegraph callers <symbol>     # 谁调用它
codegraph callees <symbol>     # 它调用谁
codegraph impact <symbol>      # 改动影响半径（--depth, --json）
codegraph affected [files...]  # 变更影响了哪些测试文件（支持 --stdin 接 git diff）
codegraph sync [path]          # 增量更新（一般由 watcher 自动完成）

七、配置面：零配置，外加一个可选的 codegraph.json

与"100% 本地、开箱即用"的定位一致，CodeGraph 是零配置的：语言支持按文件扩展名自动生效；默认跳过依赖/构建/缓存目录（node_modules、dist、build、.venv、Pods 等，即便没有 .gitignore 也生效）、.gitignore 中的内容、以及大于 1 MB 的文件。

需要微调时，项目根目录可放一个可选的 codegraph.json：

{
  "extensions": { ".dota_lua": "lua", ".tpl": "php" },
  "exclude": ["static/"],
  "include": ["Tools/"],
  "deprioritize": ["scripts/"]
}

• extensions：把自定义扩展名映射到支持的语言 id，覆盖内置默认；
• exclude：gitignore 风格的排除（用于已提交进仓库、.gitignore 删不掉的目录），显式 exclude 优先级最高，内建跳过项（node_modules、dist、.git）不可被重新包含；
• include：把被 .gitignore 挡掉的真实源码强制收进来（如使用 SVN/Perforce 的仓库）；
• deprioritize：只降排名、不过滤——文件仍可被搜到，只是不再压过第一方代码。

更细的配置与排错见 site/src/content/docs/getting-started/configuration.md 与 site/src/content/docs/troubleshooting.md。

八、作为 TypeScript 库嵌入

原文档把 TypeScript library 列为三大接口之一。npm 包直接再导出编程 API（site/src/content/docs/reference/api.md 有完整参考），最小用法：

import CodeGraph from '@colbymchenry/codegraph';

const cg = await CodeGraph.init('/path/to/project');   // 或 CodeGraph.open(...)
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();

适用前提（来自 README 的 Embedding requirements）：需从 npm 安装以便拉取对应平台的预编译包；API 运行在你自己的 Node 运行时上，要求 Node 22.5+（内置 node:sqlite）；CLI 与 MCP 服务器不受此限，跑在自带运行时上。

小结

回到 Introduction 页给出的定位：CodeGraph 用 tree-sitter 做确定性提取，把符号、边、文件放进本地 SQLite（含 FTS5），再以 MCP、CLI、库三种接口暴露成可查询的知识图谱；它针对的是代理"发现"阶段的高开销，官方文档声明的通用收益是更少的工具调用、更快的回答、接近零的文件读取，而 token/成本节省是随规模放大的附加项。整条链路——提取、解析、存储、同步——都发生在 .codegraph/ 这一个本地目录里，没有 API key、没有外部服务。

延伸阅读：快速开始、Your First Graph、How It Works、知识图谱结构、Resolution & Frameworks、CLI 参考、MCP Server 参考、下一步。