CodeGraph

为 Claude Code 提供代码知识图谱、符号搜索、调用关系分析和可选的远程 embedding 语义搜索。

English · 简体中文

这是什么

CodeGraph 会在项目本地生成 .codegraph/codegraph.db，把代码解析成可查询的知识图谱：

• 符号：函数、方法、类、接口、模块、路由等。
• 关系：调用、导入、继承、实现、引用等。
• 查询：全文搜索、调用链、影响面、上下文构建。
• 同步：MCP server 可监听文件变化并增量更新索引。
• 语义搜索：可选启用 Gemini 或 Jina embedding；向量和索引仍保存在本地 SQLite。

默认结构索引是本地的。只有启用 semanticSearch 时，生成 embedding 和语义查询 embedding 会调用配置的远程 provider API。

安装

npm install -g @stupidloud/codegraph

也可以直接运行交互安装器：

npx @stupidloud/codegraph

交互安装器会配置 Claude Code 的 MCP server，并可选择初始化当前项目。

初始化项目

cd your-project
codegraph init -i

初始化时会询问是否启用语义搜索，并选择 Gemini 或 Jina：

Enable semantic search with remote embeddings?
Embedding provider
Gemini API key / Jina API key

如果选择启用，会写入 .codegraph/config.json：

{
  "semanticSearch": {
    "enabled": true,
    "provider": "gemini",
    "apiKey": "YOUR_GEMINI_API_KEY",
    "model": "gemini-embedding-2",
    "batchSize": 32
  }
}

Jina 示例：

{
  "semanticSearch": {
    "enabled": true,
    "provider": "jina",
    "apiKey": "YOUR_JINA_API_KEY",
    "model": "jina-embeddings-v5-text-nano",
    "batchSize": 32
  }
}

如果项目已经初始化过，也可以手动编辑 .codegraph/config.json 后重新索引：

codegraph index -f

常用命令

codegraph init [path]             # 初始化项目
codegraph index [path]            # 全量索引
codegraph index -f [path]         # 清空并重新索引
codegraph sync [path]             # 增量同步
codegraph status [path]           # 查看索引状态
codegraph query <search>          # 搜索符号
codegraph context <task>          # 为任务构建相关代码上下文
codegraph affected [files...]     # 查找受变更影响的测试文件
codegraph serve --mcp             # 启动 MCP server
codegraph visualize [path]        # 打开可视化界面

示例：

codegraph query AuthService
codegraph context "where is auth token refresh handled"
codegraph affected src/auth.ts

语义搜索如何工作

启用语义搜索后：

1. codegraph index 会为函数、方法、类、接口、模块、组件等节点生成 embedding。
2. embedding 通过配置的 provider 批量生成：Gemini 使用 batchEmbedContents，Jina 使用 Embedding API。
3. 向量保存在本地 SQLite 的 vectors 表。
4. 查询时，codegraph context 会为查询文本生成 query embedding。
5. 搜索优先使用 sqlite-vss，不可用时回退到本地 brute-force cosine。
6. 本地记录 content_hash，未变化的节点会跳过重新生成 embedding。

这个设计避免了本地模型下载和 ONNX/WASM 推理开销，但会把用于 embedding 的节点文本发送给 Gemini 或 Jina。不要在不可信项目或不允许外发源码的环境中启用语义搜索。

Claude Code MCP 使用

启动 MCP server：

codegraph serve --mcp

Claude Code 可用的主要工具：

| 工具 | 用途 | |---|---| | codegraph_search | 按名称搜索符号 | | codegraph_context | 为任务构建相关代码上下文 | | codegraph_callers | 查找谁调用了某个符号 | | codegraph_callees | 查找某个符号调用了什么 | | codegraph_impact | 分析修改影响面 | | codegraph_node | 查看单个符号详情和源码 | | codegraph_files | 查看索引后的文件结构 | | codegraph_status | 查看索引健康状态 |

作为库使用

import CodeGraph from '@stupidloud/codegraph';

const cg = await CodeGraph.init('/path/to/project', {
  config: {
    semanticSearch: {
      enabled: true,
      provider: 'jina',
      apiKey: process.env.JINA_API_KEY,
      model: 'jina-embeddings-v5-text-nano',
      batchSize: 32,
    },
  },
});

await cg.indexAll();

const results = cg.searchNodes('UserService');
const context = await cg.buildContext('fix login bug', {
  maxNodes: 20,
  includeCode: true,
  format: 'markdown',
});

cg.close();

配置

.codegraph/config.json 控制索引行为：

{
  "version": 1,
  "languages": ["typescript", "javascript"],
  "exclude": ["node_modules/**", "dist/**", "build/**", "*.min.js"],
  "frameworks": [],
  "maxFileSize": 1048576,
  "extractDocstrings": true,
  "trackCallSites": true,
  "semanticSearch": {
    "enabled": false,
    "provider": "gemini",
    "model": "gemini-embedding-2",
    "batchSize": 32
  }
}

| 配置项 | 说明 | |---|---| | languages | 要索引的语言；为空时自动检测 | | exclude | 排除的 glob 模式 | | frameworks | 框架提示，用于更好的路由/引用解析 | | maxFileSize | 跳过超过该大小的文件 | | extractDocstrings | 是否提取文档注释 | | trackCallSites | 是否记录调用位置 | | semanticSearch.enabled | 是否启用远程 embedding 语义搜索 | | semanticSearch.provider | gemini 或 jina | | semanticSearch.apiKey | Provider API key | | semanticSearch.model | Gemini 默认 gemini-embedding-2；Jina 默认 jina-embeddings-v5-text-nano | | semanticSearch.batchSize | 每批生成多少个节点 embedding |

支持语言

TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart、Svelte、Vue、Liquid、Pascal/Delphi、Scala 等。

注意事项

• Node.js 需要 >=18 <25。
• 第一次启用语义搜索后建议运行 codegraph index -f。
• sqlite-vss 是可选依赖；不可用时会自动回退到 brute-force cosine。
• npm 包名是 @stupidloud/codegraph。