前提：需要 Node.js ≥ 20.0.0 环境。

# 零安装运行（推荐）
npx @xuefadevdev/codegraph

# 或全局安装
npm i -g @xuefadevdev/codegraph

_{CodeGraph 自带运行时 — 无需编译、无需原生构建，在任何平台都一样工作。交互式安装程序会自动为你的 AI Agent 配置 MCP 服务器 — 支持 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent 和 CodeBuddy IDE。}

cd your-project
codegraph init -i

当 Claude Code 探索一个代码库时，它会启动 Explore 子代理，通过 grep、glob 和 Read 扫描文件——每一步工具调用都在消耗 Token。

CodeGraph 给这些代理提供一个预索引的知识图谱——包含符号关系、调用图和代码结构，代理直接查询图谱而无需逐文件扫描。

在 7 个真实开源代码库（覆盖 7 种语言）上测试，对比同一个代理（Claude Code，无头模式）在有和没有 CodeGraph 的情况下回答一条架构问题。每个单元格是每组 4 次运行取中位数的节省比例。

平均值：35% 更省钱 · 59% 更少 Token · 49% 更快 · 70% 更少工具调用

规律：收益随代码库规模递增——在大仓库上代理通过几次索引查询即可给出答案，零文件读取；而没有 CodeGraph 的代理（及其产生的子代理）会把大部分 Token 预算花在文件发现上（find/ls/grep）。在小仓库（如 Gin 约 150 文件）上原生搜索本就便宜，因此收益边际收窄。

⚠️ 重要说明：成本节省（平均 35%）远小于 Token 节省（平均 59%），原因是 CodeGraph 的 instructions 本身会常驻 context、Claude 的 prompt caching 有折扣。Token 节省 70% 仅在大型仓库 + 架构级问题上出现（如 VS Code 场景），不代表所有场景。

CodeGraph 检测 Web 框架路由文件，产生 route 节点，通过 references 边连接到处理类或函数。查询某视图/控制器的调用者时，会直接显示与之绑定的 URL 模式。

npx @xuefadevdev/codegraph

安装程序会：

• 询问要为哪些 Agent 配置 — 自动检测已安装的：Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, CodeBuddy IDE
• 提示将 codegraph 安装到 PATH（以便 Agent 能启动 MCP 服务器）
• 询问配置应用于所有项目还是仅当前项目
• 为每个选中的 Agent 写入 MCP 服务器配置 + 指令文件（例如 CLAUDE.md、.cursor/rules/codegraph.mdc、~/.codex/AGENTS.md、~/.codebuddy/rules/codegraph/RULE.mdc）
• 当目标是 Claude Code 时自动设置权限白名单
• 初始化当前项目（本地安装场景下）

非交互式（脚本/CI）：

codegraph install --yes                              # 自动检测 Agent，全局安装
codegraph install --target=cursor,claude --yes       # 明确指定目标列表
codegraph install --target=auto --location=local     # 检测到的 Agent，项目级
codegraph install --print-config codex               # 打印配置片段，不写入文件

重启你的 Agent（Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / CodeBuddy IDE），MCP 服务器才会加载。

cd your-project
codegraph init -i

构建每个项目的知识图谱索引。同时也会接入项目级的 Agent 配置（如 Cursor 的 .cursor/rules/codegraph.mdc），使得一个全局 codegraph install 就可以覆盖所有项目 — 不需要每个项目重新跑安装程序。

就这样 — 只要项目里存在 .codegraph/ 目录，你的 Agent 就会自动使用 CodeGraph 工具。

CodeGraph 支持 CodeBuddy IDE，自动写入 MCP 配置和双语指令文件：

⚠️ 注意：全局 ~/.codebuddy/mcp.json 需要你在 CodeBuddy IDE 的"设置 → MCP"标签页中手动确认一次，IDE 才会识别。

npm install -g @xuefadevdev/codegraph

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

{
  "permissions": {
    "allow": [
      "mcp__codegraph__codegraph_search",
      "mcp__codegraph__codegraph_context",
      "mcp__codegraph__codegraph_callers",
      "mcp__codegraph__codegraph_callees",
      "mcp__codegraph__codegraph_impact",
      "mcp__codegraph__codegraph_node",
      "mcp__codegraph__codegraph_status",
      "mcp__codegraph__codegraph_files"
    ]
  }
}

## CodeGraph

CodeGraph builds a semantic knowledge graph of codebases for faster, smarter code exploration.

### If `.codegraph/` exists in the project

**NEVER call `codegraph_explore` or `codegraph_context` directly in the main session.** These tools return large amounts of source code that fills up main session context. Instead, ALWAYS spawn an Explore agent for any exploration question (e.g., "how does X work?", "explain the Y system", "where is Z implemented?").

**When spawning Explore agents**, include this instruction in the prompt:

> This project has CodeGraph initialized (.codegraph/ exists). Use `codegraph_explore` as your PRIMARY tool — it returns full source code sections from all relevant files in one call.
>
> **Rules:**
> 1. Follow the explore call budget in the `codegraph_explore` tool description — it scales automatically based on project size.
> 2. Do NOT re-read files that codegraph_explore already returned source code for. The source sections are complete and authoritative.
> 3. Only fall back to grep/glob/read for files listed under "Additional relevant files" if you need more detail, or if codegraph returned no results.

**The main session may only use these lightweight tools directly** (for targeted lookups before making edits, not for exploration):

| Tool | Use For |
|------|---------|
| `codegraph_search` | Find symbols by name |
| `codegraph_callers` / `codegraph_callees` | Trace call flow |
| `codegraph_impact` | Check what's affected before editing |
| `codegraph_node` | Get a single symbol's details |

### If `.codegraph/` does NOT exist

At the start of a session, ask the user if they'd like to initialize CodeGraph:

"I notice this project doesn't have CodeGraph initialized. Would you like me to run `codegraph init -i` to build a code knowledge graph?"

┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code                               │
│                                                                  │
│  "实现用户认证功能"                                                │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────┐      ┌─────────────────┐                   │
│  │  Explore Agent  │ ──── │  Explore Agent  │                   │
│  └────────┬────────┘      └────────┬────────┘                   │
│           │                        │                             │
└───────────┼────────────────────────┼─────────────────────────────┘
            │                        │
            ▼                        ▼
┌───────────────────────────────────────────────────────────────────┐
│                     CodeGraph MCP Server                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │
│  │   Search    │  │   Callers   │  │   Context   │               │
│  │  "auth"     │  │  "login()"  │  │  for task   │               │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘               │
│         │                │                │                       │
│         └────────────────┼────────────────┘                       │
│                          ▼                                        │
│              ┌───────────────────────┐                            │
│              │   SQLite Graph DB     │                            │
│              │   • 387 个符号         │                            │
│              │   • 1,204 条边         │                            │
│              │   • 即时查询           │                            │
│              └───────────────────────┘                            │
└───────────────────────────────────────────────────────────────────┘

L1 提取 ──→ L2 存储 ──→ L3 解析 ──→ L4 图谱遍历 ──→ L5 上下文构建
  │            │            │             │               │
tree-sitter  SQLite+     4级名字匹配   BFS/DFS       NLQ→符号
AST解析      FTS5索引     13种框架     调用图         →markdown
                          resolver      遍历           包装输出

1. 提取（L1） — tree-sitter 将源代码解析为 AST。各语言专用查询器提取节点（函数、类、方法）和边（调用、导入、继承、实现）。同时标记每条边的"产地"（provenance）：tree-sitter（AST 精确解析）或 heuristic（启发式名字匹配）或 scip（语义索引预留）。

2. 存储（L2） — 全部写入本地 SQLite 数据库（.codegraph/codegraph.db），包含 FTS5 全文搜索索引。核心四张表：nodes（~22 种节点类型）/ edges（~12 种边类型，含 provenance 和 confidence 字段）/ files / unresolved_refs。

3. 解析（L3） — 提取完成后进行引用解析：函数调用 → 定义、导入 → 源文件、类继承，以及框架特有模式（Django 路由、Spring 注解、NestJS 控制器等 13 种框架 resolver）。

4. 自动同步 — MCP 服务器使用原生 OS 文件事件监控你的项目。变更有 2 秒防抖窗口，仅过滤源码文件，增量同步。图谱随编码实时更新 — 无需任何配置。watcher 失效时（WSL2、网络盘等场景）MCP 启动即告警。

5. 🔴 信任信号 — 每条边都带 provenance（来源）和 confidence（置信度 0.3–0.95）标签，AI 工具响应中直接展示。回答末尾标出索引时效（"Index updated X minutes ago"）。所有安装器的指令文件含中英双语强制规则。

codegraph                         # 运行交互式安装程序
codegraph install                 # 运行安装程序（显式）
codegraph init [path]             # 在项目中初始化（--index 同时索引）
codegraph uninit [path]           # 从项目中移除 CodeGraph（--force 跳过提示）
codegraph index [path]            # 完整索引（--force 重新索引，--quiet 减少输出）
codegraph sync [path]             # 增量更新
codegraph status [path]           # 显示统计信息
codegraph query <search>          # 搜索符号（--kind, --limit, --json）
codegraph files [path]            # 显示文件结构（--format, --filter, --max-depth, --json）
codegraph context <task>          # 为 AI 构建上下文（--format, --max-nodes）
codegraph affected [files...]     # 找出受影响的测试文件（见下）
codegraph serve --mcp             # 启动 MCP 服务器

通过传递依赖追踪来找出改动的源文件会影响哪些测试文件。

codegraph affected src/utils.ts src/api.ts         # 将文件作为参数传入
git diff --name-only | codegraph affected --stdin   # 从 git diff 管道传入
codegraph affected src/auth.ts --filter "e2e/*"     # 自定义测试文件匹配模式

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 服务器运行时，CodeGraph 暴露以下工具给 AI Agent：

🔴 信任信号：所有数据查询类工具（callers / callees / impact / context 等）的响应中，每条边都附带"产地 + 置信度"标签（如 [tree-sitter, conf:0.95] 或 [heuristic, conf:0.6 ⚠️]），响应末尾带索引时效页脚（如 —— Index updated 5 minutes ago）。超过 30 分钟会显示警告 ⚠️ Index updated 47 minutes ago — consider re-running 'codegraph sync'。

import CodeGraph from '@xuefadevdev/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();

没有配置文件 — CodeGraph 是零配置的。它索引所有扩展名对应支持语言的文件，并遵循你的 .gitignore：在 Git 仓库中通过 Git 本身，在非 Git 项目中直接读取 .gitignore 文件（根目录和嵌套目录，和 Git 的做法一致）。

实际效果：

• Git 忽略的任何内容 — node_modules、构建产物、.env 中的密钥 — 永远不会被索引。想让某些内容不出现在图谱中，把它加到 .gitignore 即可。
• 没有需要编写或保持同步的配置文件，每个语言也不需要单独配置：根据文件扩展名自动支持。
• 大于 1 MB 的文件会被跳过（生成的打包文件、压缩 JS、vendor 大文件）— 它们消耗解析预算却得不到有用的符号。

已提交但未被 gitignore 的文件会被索引，即使在 vendor/ 下或已提交的 dist/ 下。如果你提交了一个你不想要出现在图谱中的依赖或构建目录，请把它加到 .gitignore。

CodeGraph 的 calls 边（函数调用关系）使用启发式名字匹配而非真正的语义解析。因此存在以下精度上限：

1. 多态调用：svc.save() 在两个类都有 save() 方法时只能选一个 target
2. DI/IoC 容器：Spring @Autowired、NestJS constructor injection — 运行时绑定的具体实现看不到
3. 动态语言精度低：Python getattr() / Ruby method_missing / JavaScript Proxy 等运行时动态分发不识别
4. C++ 模板/宏展开：tree-sitter 看不到预处理后的代码

缓解措施：CodeGraph 已全面启用"信任信号"系统 — 每条 calls 边都带置信度分数和产地标签（[heuristic, conf:0.6 ⚠️]），AI 可以据此自行判断哪些引用可靠、哪些需要人工核实。中英双语强制规则确保 AI 不会把低置信度边当作事实。

CodeGraph 针对国产大模型做了专门优化，使中文模型能获得接近 Claude 的使用体验：

⚠️ 上表为基于公开 benchmark + 工程经验的估算，实际效果请以真实项目实测为准。

"CodeGraph not initialized" — 先在项目目录里运行 codegraph init。

索引很慢 — 确认 node_modules 和其它大目录已被排除。使用 --quiet 减少输出开销。

MCP 报 database is locked — 当前构建产物应该不会：CodeGraph 自带 Node 运行时，使用 node:sqlite + WAL 模式，并发读永远不会被写阻塞。如果仍然看到：

• 你用的是旧版本（0.10 以前）。重新安装 — npm i -g @xuefadevdev/codegraph@latest。
• codegraph status 显示 Journal: 不是 wal — 在当前文件系统上无法启用 WAL（常见于网络共享和 WSL2 /mnt），因此读可能被写阻塞。将项目（连同其 .codegraph/ 文件夹）移到本地磁盘上。

MCP 服务器无法连接 — 确保项目已初始化/已索引，验证 MCP 配置中的路径，并检查 codegraph serve --mcp 是否可以命令行正常启动。

缺少符号 — MCP 服务器会在保存时自动同步（等几秒）。如需要可手动运行 codegraph sync。检查文件语言是否在支持列表中，且未被配置模式排除。

watcher 失效时索引陈旧 — 当文件监听器因 WSL2、网络盘、Docker bind mount 等场景失效时，AI 启动时收到的 SERVER_INSTRUCTIONS 会包含 ⚠️ watcher inactive 警告。你可以手动跑 codegraph sync 刷新索引，或移项目到本地磁盘。

CodeGraph 使用插件化的 AgentTarget 接口来支持新的 Agent。新增一个 Agent（如 CodeBuddy IDE）只需要 1 个新文件（约 300 行）+ 2 行注册代码 + 20 个测试用例，零侵入现有代码。目前已支持的 Agent：

MIT