如何把 CodeGraph 作为 TypeScript 库嵌入 Node.js/Electron 应用？
【免费下载链接】codegraphPre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, CoPilot, and Hermes Agent — fewer tokens, fewer tool calls, 100% local项目地址: https://gitcode.com/GitHub_Trending/co0degr/codegraph
如果你的应用需要直接查询代码知识图谱——比如在 Electron 主进程里做符号搜索、调用链分析、影响面评估——而不是通过 CLI 或 MCP server 调用 CodeGraph，可以把@colbymchenry/codegraph作为 TypeScript 库嵌入自己的运行时。npm 包会重新导出它的编程式 API，import和require都能在你的进程里解析出CodeGraph类。本文覆盖安装、初始化索引、核心方法调用、验证和嵌入限制。前提是你的运行环境满足文档要求的 Node 22.5+（依赖内置node:sqlite模块）。
环境要求：先看运行时的 Node 版本
嵌入 API 与 CLI/MCP server 的运行方式不同：API 跑在你自己的运行时上，而不是 CodeGraph 自带的打包运行时。据 API 参考 和 README.md 的 Library Usage 一节：
- 需要Node 22.5+，因为依赖 Node 内置的
node:sqlite模块； - Electron 主进程同样适用，条件是其捆绑的 Node 版本为 22.5+；
- CLI 和 MCP server 不受此限制——它们自带完整打包运行时，不依赖宿主 Node。
嵌入 API 是较早期版本曾中断、后来恢复的能力（CHANGELOG.md 中记录了 #354：require("@colbymchenry/codegraph")和import重新解析到编程式 API，可从自己的应用——例如 Electron 进程——直接驱动图谱）。如果你的 Electron 捆绑 Node 低于 22.5，嵌入这条路走不通，这是文档明确给出的硬性前提。
TypeScript 方面：包内自带类型声明，文档要求保持@types/node可用，并且skipLibCheck: true（这也是常见的默认设置）。
安装：从 npm 安装以拉取对应平台的包
npm i @colbymchenry/codegraphREADME.md 说明这样安装的原因：与主包匹配的 per-platform 包会随 shim 一起被 npm 拉下来，该 per-platform 包携带编译好的库及其依赖。per-platform 包以optionalDependencies形式分发（命名形如@colbymchenry/codegraph-<target>，带os/cpu字段），npm 只会安装匹配当前系统的那个，这一点在 BUNDLING.md 中有完整说明。
如果你的 registry 镜像尚未同步对应的 per-platform 包，安装可能报no prebuilt bundle for <platform>。CHANGELOG.md 记录了 #303 的修复：launcher 会改为从 GitHub Releases 下载 bundle 并缓存，可用CODEGRAPH_NO_DOWNLOAD=1关闭该回退，或用CODEGRAPH_DOWNLOAD_BASE指向自己的镜像。
初始化索引并调用核心方法
以下示例取自 API 参考，其中/path/to/project是占位路径，替换为你要索引的项目根目录：
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(); // 文件变更时自动同步 cg.unwatch(); // 停止监听 cg.close(); // 关闭数据库连接文档给出的方法表（完整表格见 api.md）：
| 方法 | 用途 |
|---|---|
CodeGraph.init(path)/CodeGraph.open(path) | 创建或打开项目索引 |
indexAll(opts) | 全量索引，带进度回调 |
sync() | 增量更新 |
searchNodes(query) | 全文符号搜索 |
getCallers(id)/getCallees(id) | 遍历调用图 |
getImpactRadius(id, depth) | 变更的传递影响面 |
buildContext(task, opts) | 生成给 AI 的 Markdown / JSON 上下文 |
watch()/unwatch() | 启动 / 停止文件监听 |
close() | 关闭数据库连接 |
CommonJS 环境同样可用：const { CodeGraph } = require('@colbymchenry/codegraph');。
init与open的区别是创建新索引还是打开已有索引；如果你的应用启动时索引已存在（比如由codegraph initCLI 建立），用open跳过重复建库，用indexAll做首次或全量重建，sync()做后续增量更新。
直接使用底层构件
如果你不走CodeGraph门面类，而要自己驱动图谱，同一入口还导出一组底层构件（api.md）：DatabaseConnection、QueryBuilder、getDatabasePath、initGrammars/loadGrammarsForLanguages、FileLock。
import { CodeGraph, DatabaseConnection, QueryBuilder, getDatabasePath, initGrammars, loadGrammarsForLanguages, FileLock, } from '@colbymchenry/codegraph';文档只列出了这些导出的名称和用途定位，没有逐一举例；需要细粒度控制数据库连接或语法加载时，从这一组导出入手，具体行为以 src/db 等源码为准。
验证嵌入是否正常工作
文档展示的可观察行为如下，按代码顺序对应：
indexAll的onProgress回调会打印进度（格式为${p.phase}: ${p.current}/${p.total}，例如阶段名加当前/总数）——回调有输出即说明索引过程在推进；searchNodes('UserService')返回结果数组，results[0].node.id可作为后续调用的入参——能取到带node.id的结果说明符号搜索通了；getCallers、getImpactRadius、buildContext依次基于该 id 产出调用方、影响面和上下文内容，是端到端跑通的最小验证链。
文档没有给出固定输出样例或判定阈值，上述回调与返回值就是文档展示的成功路径；若searchNodes返回空，先确认传入的是已建索引的项目路径（init指向的目录与searchNodes查询的符号是否属于同一项目）。
限制与边界
- 运行时限制只作用于嵌入 API：CLI 和 MCP server 跑在自带打包运行时上，无需宿主 Node，不受 Node 22.5 限制约束（BUNDLING.md 解释了打包时机的动机：零原生插件、无版本依赖）。
- 数据库是本地 SQLite（
.codegraph/codegraph.db，FTS5 全文检索），索引状态与文件路径绑定，嵌入应用与 CLI 操作的是同一份索引文件。 - 文档未提及 Electron 渲染进程直接嵌入的场景，示例与要求都针对主进程一类拥有完整 Node 运行时的环境。
- 若要嵌入 CodeGraph 的可视化界面而非引擎，那是另一个包
@colbymchenry/codegraph-ui（组件库，见 CHANGELOG.md 的记录），不在本文的嵌入 API 范围内。
完成嵌入后，应用内通过CodeGraph类即可执行搜索、调用图遍历与影响面分析，索引由watch()在文件变更时保持同步，应用退出前调用close()释放数据库连接。
【免费下载链接】codegraphPre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, CoPilot, and Hermes Agent — fewer tokens, fewer tool calls, 100% local项目地址: https://gitcode.com/GitHub_Trending/co0degr/codegraph
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
