CodeGraph：基于SQLite的本地代码知识图谱工具

1. 为什么你需要一张“本地代码地图”——CodeGraph 不是锦上添花，而是重构 AI 编程的底层逻辑

你有没有过这种体验：在 Cursor 或 Claude Code 里问一句“这个登录流程是怎么串起来的？”，AI 就开始疯狂调用grep、find、read工具，在几千行代码里逐个扫描、打开、读取、再丢弃——等它终于理清头绪，你已经喝完两杯咖啡，Token 账单也悄悄涨了三成。这不是 AI 不够聪明，而是它被逼着用最原始的方式“摸黑找路”。CodeGraph 的出现，不是给 AI 多装一个插件，而是直接在你的项目根目录下，铺开一张由 SQLite 驱动、实时更新、覆盖全语言的本地代码地图。这张地图不依赖网络、不上传代码、不走 API，它就安静地躺在.codegraph/codegraph.db里，像一个永远在线、从不打盹的资深架构师，随时准备回答“谁调用了谁”“改这个函数会影响哪些地方”“路由/api/login最终落到哪个文件的哪个方法”。

关键词CodeGraph、Claude Code、Cursor、TypeScript、SQLite，这五个词组合在一起，指向的是一场静默却深刻的生产力革命。它解决的不是“能不能用 AI 写代码”的问题，而是“AI 写代码时，为什么总在低效重复劳动”的根本症结。CodeGraph 的核心价值，藏在它那句看似平淡的标语里：“100% local”。这意味着你不需要配置 API Key，不需要等待云端索引，不需要担心代码泄露——所有符号关系、调用链、继承树、路由映射，都在你本地磁盘上完成解析与存储。而SQLite，这个被无数人低估的嵌入式数据库，恰恰是这场革命最可靠的基石：它轻量（单文件）、可靠（ACID 事务）、跨平台（Windows/macOS/Linux 无缝运行），更重要的是，它原生支持 FTS5 全文搜索，让“查一个函数名”这种操作，从秒级降为毫秒级。

我第一次在 Vue 3 + TypeScript + Vite 项目里跑通 CodeGraph，是在一个周五下午。当时正被一个跨模块的状态同步 bug 折磨得焦头烂额，传统调试要手动翻store、composables、components三个目录，而用codegraph explore "useAuthStore"，不到两秒，它就把所有调用点、相关状态变更、甚至onMounted里触发的副作用都列在了一个结构化响应里。那一刻我意识到，CodeGraph 不是工具，它是把“代码理解”这件事，从 AI 的负担，变成了开发者的资产。它不改变你写代码的方式，但彻底改变了你阅读、导航、推理代码的方式。对于任何使用TypeScript这类强类型语言的团队，CodeGraph 的价值更是指数级放大——类型定义、接口实现、泛型约束，这些静态信息被精准提取并建模，让 AI 的“理解”不再是模糊的语义猜测，而是基于 AST 的确定性图谱。所以，如果你还在用Ctrl+Click在 VS Code 里跳转，或者靠记忆和文档来维护大型代码库的认知负荷，那么这张“本地代码地图”，就是你此刻最该铺开的基础设施。

2. CodeGraph 的底层引擎拆解：从 AST 解析到 SQLite 图谱的完整闭环

要真正驾驭 CodeGraph，不能只把它当黑盒。它的强大，源于一套精密、分层、且高度工程化的数据处理流水线。这条流水线始于源码文本，终于 SQLite 数据库中的图节点与边，中间每一步都经过千锤百炼。理解它，才能避开那些“为什么我的函数没被索引”“为什么调用链断了”的典型陷阱。

2.1 核心三步：解析（Parse）、存储（Store）、解析（Resolve）

CodeGraph 的工作流可以清晰地划分为三个阶段，它们共同构成了一个自洽的闭环：

1. AST 解析（Parse）：这是整个系统的“眼睛”。CodeGraph 不用正则表达式去“猜”代码结构，而是采用Tree-sitter这一工业级语法解析器。Tree-sitter 为每种语言（TypeScript、Python、Rust 等）提供精确、增量、且快速的抽象语法树（AST）生成能力。当你执行codegraph init，它会遍历项目中所有源文件（自动跳过node_modules、dist等），对每个.ts文件，Tree-sitter 会生成一棵包含所有FunctionDeclaration、ClassDeclaration、MethodDefinition、ImportDeclaration等节点的树。这棵树的精度，远超任何基于文本的简单匹配，它能准确识别出async function foo() {}是一个异步函数声明，而不是一个普通变量赋值。

2. 图谱存储（Store）：这是系统的“心脏”与“记忆”。解析得到的 AST 节点，不会被丢弃，而是被转化为图数据库中的实体。CodeGraph 使用SQLite作为其唯一的持久化后端，所有数据都存放在项目根目录下的.codegraph/codegraph.db文件中。这个数据库并非简单的键值对，而是一个精心设计的图模型：

   • nodes表：存储所有“事物”，如函数、类、方法、接口、变量、文件等。每一行代表一个节点，拥有唯一 ID、类型（function,class,file）、名称、所在文件路径、起始/结束行号等元数据。
   • edges表：存储所有“关系”，即节点之间的连接。例如，call边连接一个调用者函数节点和一个被调用者函数节点；import边连接一个导入语句节点和一个被导入的模块节点；extend边连接一个子类节点和一个父类节点。每条边都带有source_id和target_id，以及一个kind字段（如call,import,extends）来标识关系类型。
   • fts_nodes表：这是 SQLite 的 FTS5（Full-Text Search）虚拟表，它为nodes表中的name和content字段建立全文索引。这正是codegraph search "UserService"如此之快的原因——它不是在字符串里模糊匹配，而是在一个专门为搜索优化的倒排索引中查找。

3. 引用解析（Resolve）：这是系统的“大脑”。仅仅知道“这里有个foo()调用”是不够的，AI 需要知道“这个foo()到底是哪个foo()？它定义在哪里？”。这一步就是Resolution。CodeGraph 会分析 AST 中的引用节点（如CallExpression.callee），然后在nodes表中，根据作用域规则、导入路径、类型定义等，精确地找到它所指向的目标节点 ID，并在edges表中创建一条call边。这个过程极其复杂，尤其在 TypeScript 中，它需要处理类型别名、接口实现、泛型推导、模块解析（moduleResolution: node）等。CodeGraph 的强大之处在于，它内置了对 TypeScript 编译器选项（如moduleResolution）的模拟，确保其解析结果与tsc的行为高度一致。这也是为什么它能正确处理import { UserService } from '@/services';这样的路径别名——它读取了你的tsconfig.json，并复现了 TypeScript 的模块解析逻辑。

提示：codegraph status命令是检验这个闭环是否健康的关键。它会输出类似Nodes: 12,456 | Edges: 38,921 | FTS5 Index: OK | Journal: wal的信息。其中Journal: wal至关重要，它表示 SQLite 正在使用 Write-Ahead Logging 模式，这是保证高并发读写（如 AI 查询与文件监听同步）不锁死的基石。如果这里显示other than wal，说明你的项目可能在 WSL2 的/mnt目录或网络共享盘上，必须将项目移到本地磁盘，否则会频繁遇到“database is locked”错误。

2.2 自动同步（Auto-Sync）：让地图永远“活”着

一张静态的地图，价值有限。CodeGraph 的灵魂在于其零配置、全自动的实时同步机制。它不是让你在每次修改后手动敲codegraph sync，而是像一个隐形的守护进程，时刻保持图谱与代码的一致性。

其工作原理是一套精妙的三层保障：

1. 原生文件监听（Native File Watcher）：CodeGraph 的 MCP 服务器启动后，会立即在操作系统层面注册监听。在 macOS 上，它使用FSEvents；在 Linux 上，使用inotify；在 Windows 上，使用ReadDirectoryChangesW。这些是操作系统提供的、最底层、最高效的文件系统事件通知机制，延迟通常在毫秒级。当你在编辑器里保存一个.ts文件，操作系统几乎立刻就会通知 CodeGraph：“嘿，src/api/auth.ts被修改了”。

2. 防抖同步（Debounced Sync）：一个文件的保存，往往伴随着多个小文件的写入（如.ts和对应的.js.map）。为了避免为每一次微小的磁盘写入都触发一次完整的、耗时的重新索引，CodeGraph 引入了防抖（Debounce）机制。默认情况下，它会等待 2 秒钟的“安静期”（可通过CODEGRAPH_WATCH_DEBOUNCE_MS环境变量调整）。只有在这 2 秒内，没有任何新的文件变更事件发生，它才会启动一次增量索引。这就像电梯的“关门等待”——它不会因为一个人按了按钮就立刻关门，而是等几秒，看是否还有其他人进来。

3. 连接时校准（Connect-time Catch-up）：这是最后一道保险。想象一下，你关闭了 Cursor，然后在终端里执行了一次git pull，拉取了新代码，接着再启动 Cursor。此时，MCP 服务器是“离线”的，它不知道代码已经变了。当 Cursor 重新连接到 CodeGraph 的 MCP 服务器时，服务器会在处理第一个查询之前，主动执行一次快速的“校准”：它会扫描工作目录，对比每个文件的大小、修改时间（mtime）和内容哈希（content-hash），找出所有在服务器离线期间被修改过的文件，并立即将它们纳入下一次同步队列。这确保了无论你如何修改代码（通过编辑器、命令行、Git），CodeGraph 的地图永远不会“掉队”。

这套机制的最终效果是：你几乎感觉不到它的存在，但它又无处不在。你写一行代码，保存，然后立刻在 Cursor 里问“loginUser函数现在调用了哪些新服务？”，答案就是最新的。这种“所见即所得”的体验，是传统静态分析工具无法企及的。

3. 从 CLI 到 MCP：CodeGraph 如何无缝融入 Claude Code 与 Cursor 的工作流

CodeGraph 的威力，最终要通过 AI 编程助手（如 Claude Code 或 Cursor）来释放。它不是独立运行的 IDE 插件，而是一个遵循MCP（Model Context Protocol）标准的“智能服务”。理解它如何与这些代理（Agent）协同工作，是解锁其全部潜能的关键。

3.1 MCP：AI 与工具之间的“通用语言”

MCP 是一个新兴的、旨在标准化大模型与外部工具交互的协议。你可以把它想象成 USB-C 接口——它定义了一套通用的“握手”方式、数据格式和通信规则。只要一个工具（如 CodeGraph）和一个代理（如 Claude Code）都支持 MCP，它们就能即插即用，无需为每个代理单独开发一套定制化集成。

CodeGraph 的 MCP 服务器，本质上就是一个后台进程（codegraph serve --mcp），它暴露了一组标准化的工具（Tools），供 AI 代理调用。这些工具不是随意命名的，而是有明确语义的：

• codegraph_explore:主武器。用于回答“如何工作？”、“如何流动？”这类结构性问题。例如，“how does the auth flow work?” 或 “show me all code related to payment processing”。它会返回相关的符号源码、调用路径图、影响半径（Blast Radius）等丰富上下文。
• codegraph_search:定位器。用于快速查找符号。例如，“search for 'createUser'”。它返回匹配的函数、类、变量等的列表及其位置。
• codegraph_callers:溯源者。用于找出所有调用某个函数的地方。例如，“who calls 'validateToken'?”。它特别擅长找出回调注册点（如addEventListener），这是grep无法做到的。
• codegraph_node:显微镜。用于深度查看一个符号的全部信息。例如，“show me the full source and callers of 'AuthService'”。它会返回该类的完整定义、所有构造函数、所有方法，以及每一个调用它的位置。

3.2 安装与配置：一次设置，终身受益

将 CodeGraph 接入 Claude Code 或 Cursor，流程极其简洁，官方推荐的codegraph install命令会自动化一切：

1. 全局安装 CLI：首先，你需要在系统中安装 CodeGraph 的命令行工具。最推荐的方式是使用其官方一键脚本：

   # 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.js 运行时的二进制文件，因此你完全不需要提前安装 Node.js。安装完成后，codegraph命令即可在终端中使用。

2. 运行安装向导：在终端中执行codegraph install。它会自动检测你电脑上已安装的 AI 编程助手（Claude Code、Cursor、Codex CLI 等），并询问你想为哪些工具进行配置。选择后，它会：

   • 修改对应工具的 MCP 配置文件（例如，Claude Code 的~/.claude.json），添加一个指向codegraph serve --mcp的服务器条目。
   • 向该工具的指令文件（如CLAUDE.md）中，插入一段标记化的说明文字，告诉 AI “当遇到代码理解问题时，请优先使用codegraph_explore等工具”。
   • （针对 Claude Code）自动将其添加到权限白名单中，避免每次调用工具时弹出烦人的确认框。

3. 初始化项目：进入你的代码项目根目录，执行codegraph init。这一步会创建.codegraph/目录，并开始构建初始的知识图谱。对于一个中等规模的 TypeScript 项目（约 500 个文件），首次索引通常在 1-3 分钟内完成。

4. 重启代理：最后，务必重启你的 Claude Code 或 Cursor。这是最关键的一步！因为 MCP 服务器是在代理启动时加载的，不重启，新配置就不会生效。

注意：codegraph install的魔力在于它的“智能感知”。它不仅能检测到你安装了 Cursor，还能识别出你是否使用了 Cursor Pro（带 Agent 功能的版本），并自动为其配置。它甚至能区分全局安装和项目本地安装，确保配置的粒度恰到好处。如果你追求极致的控制，也可以手动编辑配置文件，但绝大多数用户，codegraph install就是最佳实践。

3.3 实战演示：在 Cursor 中用 CodeGraph 解决一个真实问题

让我们用一个具体场景，来感受 CodeGraph 如何改变工作流。假设你正在维护一个基于Vue 3 + TypeScript + Vite + Element Plus的管理后台，产品经理突然提出一个需求：“在用户列表页，点击‘重置密码’按钮后，需要弹出一个二次确认对话框。”

你打开src/views/UserList.vue，找到了按钮的@click绑定：

<el-button @click="handleResetPassword(user)">重置密码</el-button>

然后你追踪到handleResetPassword方法，它位于src/composables/useUserActions.ts：

export function useUserActions() { const api = useApi(); const message = useMessage(); const handleResetPassword = async (user: User) => { try { await api.post('/api/users/reset-password', { userId: user.id }); message.success('密码重置成功'); } catch (error) { message.error('重置失败'); } }; return { handleResetPassword }; }

现在，问题来了：api.post这个方法，到底是由哪个useApiHook 提供的？它的内部实现是什么？它是否已经集成了错误重试或请求拦截？为了搞清楚，你过去可能会：

• 在 VS Code 里Ctrl+Click，但有时会跳转到类型定义而非实现。
• 在项目里全局搜索useApi，结果可能有十几个同名 Hook。
• 打开src/composables/useApi.ts，从头开始阅读。

而有了 CodeGraph，你只需在 Cursor 的聊天窗口中，输入：

How does the `api.post` method in `useUserActions.ts` work? Show me its implementation and where it's defined.

Cursor 会立刻调用codegraph_explore工具。几秒钟后，你收到的不再是零散的代码片段，而是一个结构化的、可直接理解的响应：

• Definition:src/composables/useApi.ts中的const api = createApi(...)，其中createApi是一个工厂函数。
• Implementation:api.post的源码被完整列出，清晰地展示了它如何封装fetch、如何添加认证头、如何处理 401 错误。
• Callers: 列出了所有调用api.post的地方，包括useUserActions.ts和useOrderActions.ts。
• Blast Radius: 显示了api.post的调用链，从fetch到window.fetch，再到最终的网络请求。

你一眼就看出，这个api.post已经具备了完善的错误处理，但没有二次确认逻辑。于是，你直接在handleResetPassword方法里，加入ElMessageBox.confirm的调用，问题迎刃而解。整个过程，从发现问题到定位根源再到写出解决方案，不超过一分钟。这就是 CodeGraph 赋予你的“代码直觉”。

4. 深度避坑指南：那些官方文档不会明说，但你一定会踩的“本地地图”陷阱

即使是最优秀的工具，也有其边界和“脾气”。CodeGraph 的文档写得非常详尽，但有些坑，只有在真实项目中反复摔打过，才能总结出最有效的规避策略。以下是我亲身经历并验证过的几大高频陷阱，以及它们背后的根本原因和终极解法。

4.1 陷阱一：“我的函数明明写了，为什么codegraph search找不到？”

现象：你在src/utils/helpers.ts里定义了一个debounce函数，但在 Cursor 里用codegraph search "debounce"却一无所获。

根本原因：CodeGraph 的索引范围，严格遵循两个“默认排除”规则：

1. .gitignore规则：它会读取你项目根目录下的.gitignore文件，并将其中列出的所有路径（如node_modules/,dist/,.DS_Store）自动排除在索引之外。
2. 内置排除列表：即使你的项目没有.gitignore，CodeGraph 也会硬编码排除一系列常见目录，如vendor,build,target,.next,Pods等。

排查与解法：

• 第一步，确认文件位置：运行codegraph status，它会显示Indexed files: 1245。然后执行codegraph files --max-depth 2，看看src/utils/目录是否在列表中。如果helpers.ts不在其中，说明它被排除了。
• 第二步，检查.gitignore：打开你的.gitignore，检查是否有类似src/utils/或*.ts这样过于宽泛的规则。最常见的错误是误加了*.ts，这会把所有 TypeScript 文件都排除。
• 第三步，使用--filter调试：codegraph index --filter "**/*.ts"可以强制只索引.ts文件，用于快速验证是否是过滤规则的问题。
• 终极解法：如果helpers.ts确实被.gitignore排除了，但你又希望它被索引（比如这是一个核心工具库），请在.gitignore中添加一个否定规则（Negation）：

  # .gitignore src/ !src/utils/ !src/utils/helpers.ts

  !符号表示“取消前面的忽略”，这样 CodeGraph 就会重新将其纳入索引范围。

4.2 陷阱二：“codegraph explore返回了结果，但里面的内容看起来是旧的！”

现象：你刚刚修改了src/services/authService.ts中的login方法，增加了日志，但紧接着在 Cursor 里问how does login work?，返回的源码还是修改前的版本。

根本原因：这几乎 100% 是文件监听失效导致的。CodeGraph 的自动同步依赖于操作系统原生的文件事件。在某些特定环境下，这个监听会“失聪”。

高危环境清单：

• WSL2 的/mnt目录：这是最经典的“雷区”。当你把项目放在 Windows 的C:\my-project，然后在 WSL2 里通过/mnt/c/my-project访问时，Linux 的inotify无法可靠地监听 Windows 文件系统的变更。
• Docker 容器内：如果 CodeGraph 的 MCP 服务器运行在容器里，而代码卷（volume）挂载方式不当，也可能导致监听失效。
• 某些云开发环境（如 GitHub Codespaces）：其底层文件系统抽象层可能不完全兼容inotify。

排查与解法：

• 快速诊断：运行codegraph status。如果看到### Pending sync:区块，并列出了一堆文件名和它们的“编辑年龄”（如src/services/authService.ts (2m 15s)），那就坐实了监听失效。这些文件就是“已修改但未同步”的证据。
• 临时解法：执行codegraph sync手动触发一次同步。但这只是治标。
• 终极解法：
  • 对于WSL2：绝对不要在/mnt/下开发。将你的项目克隆或移动到 WSL2 的原生 Linux 文件系统中，例如/home/username/my-project。这是唯一能获得完美体验的方案。
  • 对于Docker：确保你的 volume 挂载使用了:delegated或:cached选项（取决于宿主机 OS），并在容器内安装inotify-tools进行测试。
  • 对于云环境：查阅该平台的文档，看是否有关于文件监听的特殊配置，或直接接受手动sync作为工作流的一部分。

4.3 陷阱三：“codegraph init卡住了，CPU 占用 100%，半天没反应”

现象：在大型 monorepo（如包含多个packages/子项目的 Lerna 项目）中执行codegraph init，命令长时间无响应，htop显示codegraph进程占满一个 CPU 核心。

根本原因：CodeGraph 的默认行为是递归扫描当前目录下的所有子目录。在一个庞大的 monorepo 中，它会试图去索引node_modules（即使被.gitignore排除，扫描本身也需要时间）、packages/*/dist、packages/*/node_modules等海量垃圾目录，导致 I/O 和 CPU 爆炸。

解法：精准控制索引范围

CodeGraph 提供了强大的--include和--exclude参数，让你可以像手术刀一样精确划定战场：

• 方案一（推荐）：只索引源码目录
  如果你的 monorepo 结构是packages/<package-name>/src/，那么：

  # 进入 monorepo 根目录 codegraph init --include "packages/*/src/**/*.{ts,tsx,js,jsx}"

  这条命令告诉 CodeGraph：“只扫描所有packages下src目录里的.ts/.tsx/.js/.jsx文件，其他一概不管”。

• 方案二：排除已知的巨型垃圾目录

  codegraph init --exclude "node_modules" --exclude "dist" --exclude "build" --exclude "packages/*/dist"

• 方案三（高级）：利用--index标志
  codegraph init默认只创建.codegraph/目录，不立即索引。你可以先运行codegraph init --no-index，然后手动进入每个需要的子包，再分别执行codegraph index。这对于需要为不同子包定制不同索引策略的场景非常有用。

提示：codegraph init --help会列出所有可用的过滤参数。善用--quiet可以减少大量无关的输出，让进度更清晰。记住，CodeGraph 的设计哲学是“零配置”，但这并不意味着它不能被精细配置；相反，它把配置的权力，以最符合开发者直觉的方式（即命令行参数）交还给了你。

5. 超越基础：用 CodeGraph 的 CLI 和 API 构建属于你自己的开发效能飞轮

CodeGraph 的 MCP 集成，是它面向 AI 编程助手的“前台”。而它的 CLI（命令行界面）和 Programmatic API（编程接口），则是你构建个性化、自动化开发效能工具的“后台”。掌握这两者，你就能将 CodeGraph 从一个被动的“问答工具”，升级为一个主动的、嵌入你日常开发流程的“智能引擎”。

5.1 CLI 的隐藏力量：不只是init和install

codegraph命令行工具，远比init和install丰富得多。它是一套功能完备的“本地代码图谱操作系统”，其核心价值在于将图谱查询能力，从 AI 的专属领域，解放出来，变成开发者可以直接调用的生产力命令。

• codegraph query：命令行版的codegraph_search
  这是最直接的迁移。当你在终端里快速想确认一个函数是否存在，或者想批量查找所有TODO注释时，query比打开 Cursor 再输入指令快得多：

  # 查找所有名为 "create" 的函数或方法 codegraph query "create" --kind function # 查找所有包含 "deprecated" 的注释（利用 FTS5 全文搜索） codegraph query "deprecated" --kind comment # 以 JSON 格式输出，方便后续用 jq 处理 codegraph query "UserService" --json | jq '.[0].path'

• codegraph affected：CI/CD 流水线的“智能测试筛选器”
  这是 CodeGraph 最被低估、却最具商业价值的功能。在大型项目中，每次提交后运行全部测试，是巨大的时间和资源浪费。codegraph affected可以基于代码图谱，精准计算出“本次改动，理论上会影响哪些测试文件”。

  它的工作原理是：分析你修改的源文件（如src/services/apiClient.ts），然后沿着图谱中的import边，向上追溯所有直接和间接依赖它的文件（如src/composables/useData.ts），再向下追溯所有依赖这些文件的测试文件（如src/composables/__tests__/useData.spec.ts）。最终，它只返回那些真正需要被执行的测试。

  实战 CI 脚本：

  #!/usr/bin/env bash # .github/workflows/test.yml 中的 script 步骤 set -e # 获取本次 PR/Commit 中修改的源文件列表 CHANGED_FILES=$(git diff --name-only HEAD^ HEAD -- "*.ts" "*.tsx" "*.js" "*.jsx") # 让 CodeGraph 计算受影响的测试文件 AFFECTED_TESTS=$(echo "$CHANGED_FILES" | codegraph affected --stdin --quiet) if [ -n "$AFFECTED_TESTS" ]; then echo "Running tests for changed files: $AFFECTED_TESTS" npx vitest run $AFFECTED_TESTS else echo "No test files affected by changes." exit 0 fi

  这个脚本可以将一个原本需要 10 分钟的全量测试套件，缩减为平均 2 分钟的精准测试，CI 成功率和速度会得到质的飞跃。

• codegraph impact：重构前的“安全沙盒”
  在你准备删除一个看似“没人用”的工具函数前，codegraph impact <symbol>是你的终极保险。它会返回一个完整的“影响半径”报告，不仅列出所有直接调用者，还会显示：

  • 该函数的return值被谁消费。
  • 该函数抛出的Error被谁捕获。
  • 该函数的参数对象，其属性被谁访问（深度属性访问）。
  • 该函数所在的类，其public方法被谁调用。

  这份报告，就是你发起代码审查（Code Review）时最有力的论据，也是你自信按下Delete键前的最后一道防线。

5.2 Programmatic API：将 CodeGraph 嵌入你的 Electron 应用或 VS Code 插件

对于有更高阶需求的开发者，CodeGraph 提供了完整的 TypeScript API。你可以将它作为一个 npm 包，直接集成到你自己的应用中。

npm install @colbymchenry/codegraph

然后，在你的 Node.js（或 Electron 主进程）代码中：

import CodeGraph from '@colbymchenry/codegraph'; // 初始化一个指向你项目的 CodeGraph 实例 const cg = await CodeGraph.init('/path/to/your/project'); // 执行一次完整的索引（可选，如果项目已初始化，可跳过） await cg.indexAll({ onProgress: (p) => console.log(`Indexing: ${p.current}/${p.total}`) }); // 现在，你可以像调用 CLI 一样，调用所有核心功能 const results = cg.searchNodes('useAuthStore'); // 返回 Node[] 数组 const callers = cg.getCallers(results[0].node.id); // 返回 CallSite[] 数组 // 构建一个用于 AI 的上下文（Context） const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' }); console.log(context); // 输出一个 Markdown 字符串，可直接喂给 LLM // 启动自动监听 cg.watch(); // 当你的应用关闭时，记得清理 cg.unwatch(); cg.close();

应用场景举例：

• VS Code 插件：你可以开发一个插件，在你右键点击一个函数名时，弹出一个侧边栏，里面实时显示codegraph explore的结果，无需离开编辑器。
• Electron 桌面应用：构建一个内部的“代码知识库”应用，让新入职的工程师可以通过自然语言提问，快速了解公司核心业务逻辑。
• 自定义 LSP（Language Server Protocol）：为你的团队定制一个更智能的代码补全和跳转服务，其底层依赖 CodeGraph 的精准图谱，而非传统的、容易出错的符号链接。

注意：使用 Programmatic API 需要 Node.js 22.5+，因为它依赖 Node.js 内置的node:sqlite模块。但对于 CLI 和 MCP 服务器，它们自带了运行时，完全不受此限制。这体现了 CodeGraph 架构的精妙：它把对运行时环境的强依赖，隔离在了最上层的 API 层，而核心的 CLI 和服务层，则做到了最大程度的“开箱即用”。

6. 性能与安全的终极平衡：为什么 SQLite 是 CodeGraph 不可替代的基石

在技术选型的世界里，没有银弹，只有权衡。当 CodeGraph 的作者 Colby Henry 在 2024 年决定将 SQLite 作为其核心数据库时，他放弃了很多看似更“现代”的选择：没有选择 PostgreSQL（功能强大但需要独立服务进程），没有选择 LevelDB（轻量但缺乏 SQL 查询能力），也没有选择纯内存图数据库（速度快但无法持久化）。这个选择，是 CodeGraph 能够实现“100% local”这一核心承诺的唯一可行路径。理解 SQLite 在其中扮演的角色，就是理解 CodeGraph 的灵魂。

6.1 SQLite 的四大不可替代性

1. 真正的“零依赖”部署：SQLite 的本质是一个 C 语言库，它被直接编译进 CodeGraph 的可执行文件中。当你运行codegraph init，它启动的不是一个“连接到数据库服务器”的客户端，而是直接在进程内存中加载并操作那个.codegraph/codegraph.db文件。这意味着：

   • 无需安装数据库服务：你不必在 macOS 上brew install sqlite3，也不必在 Windows 上下载安装包。它就在那里，随用随启。
   • 无端口冲突风险：PostgreSQL 默认监听 5432 端口，如果用户机器上已有其他服务占用，就会报错。SQLite 完全绕开了网络栈，不存在此类问题。
   • 无权限问题：在企业环境中，安装和运行数据库服务往往需要管理员权限。而 SQLite 的文件读写，只需要对项目目录的普通文件权限，这极大地降低了部署门槛。

2. ACID 事务与 WAL 模式的完美结合：CodeGraph 的工作负载是典型的“读多写少”，但写操作（即索引更新）必须是原子的、可靠的。SQLite 的 ACID（原子性、一致性、隔离性、持久性）特性，保证了即使在索引过程中发生断电或崩溃，数据库文件也不会损坏，下次启动时能自动恢复到一个一致的状态。而WAL（Write-Ahead Logging）模式，则是 CodeGraph