Codegraph

CodeGraph — 语义代码智能

CodeGraph 是基于 tree-sitter 的本地代码知识图谱工具，为 AI 编码代理（Claude Code、Cursor、Codex、Gemini 等）提供符号关系、调用图和代码结构的即时查询能力。

核心收益：平均节省 ~16% 成本、~58% 减少工具调用、~47% 减少 token 消耗、~22% 加速响应。

100% 本地 — 无数据离开机器，无 API 密钥，无外部服务，仅 SQLite 数据库。

Capability Boundaries

✅ Strong Suits

1. 代码结构查询 — "X 如何工作"、"X 如何到达 Y" 2. 符号搜索与调用链追踪 — 查找函数/类的调用者与被调用者 3. 变更影响分析 — 修改某符号前分析影响范围（blast radius） 4. 框架路由识别 — Django/Express/NestJS/Spring/Gin 等 14 个框架的路由绑定 5. 跨语言桥接 — iOS（Swift↔ObjC）、React Native（JS↔原生）、Expo Modules 6. 自动同步 — 文件监听器 + 防抖自动同步，索引随代码实时更新 7. 全文搜索 — 基于 FTS5 的符号名即时搜索 8. 受影响测试文件追踪 — codegraph affected 溯源变更影响的测试文件

⚠️ Requirements

1. 项目需运行 codegraph init -i 初始化知识图谱索引 2. MCP 服务器需通过 codegraph install 配置到目标 Agent 3. 配置后需重启 Agent 才能加载 MCP 服务器 4. 首次索引可能需要几分钟（取决于代码库大小）

❌ Out of Scope（附替代方案）

1. 实时调试 / 运行时动态分析 → 使用调试器（如 GDB、Chrome DevTools） 2. 非文件系统项目（如远程仓库未检出）→ 先 clone 到本地 3. 代码编辑/生成 → 使用 Agent 自身的编辑能力 4. CI/CD 流水线管理 → 使用专用 CI 工具

When to Use This Skill

Use this skill when the agent needs to:

• 理解代码库架构："X 如何工作"、"请求如何到达数据库"
• 追踪符号依赖："谁调用了 X"、"X 调用了谁"
• 分析变更影响："修改 X 会影响什么"
• 查找调用链："从 A 到 B 的完整路径"
• 审查代码结构：获取项目文件结构、符号索引
• 确定受影响的测试文件：codegraph affected

Data Privacy

CodeGraph 不收集、存储或传输任何用户数据。所有索引存储在项目本地的 .codegraph/ 目录中，SQLite 数据库不会离开你的机器。无 API 密钥，无外部服务。

How It Works

Agent → CodeGraph MCP Server (explore/search/callers/callees/impact/node)
         → SQLite 知识图谱 (符号 · 边 · 文件 · FTS5)

1. Extraction — tree-sitter 解析源代码为 AST，提取节点和边 2. Storage — 存入本地 SQLite 数据库（.codegraph/codegraph.db），支持 FTS5 3. Resolution — 解析引用关系：调用→定义、导入→源文件、框架路由 4. Auto-Sync — 原生 OS 文件事件监听 + 防抖同步（默认 2s），索引实时更新

Quick Start

# Step 1: 安装 CLI（无需 Node.js）
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# Step 2: 配置 Agent
codegraph install
# Step 3: 初始化项目
cd your-project
codegraph init -i

Workflow

Step 1. 初始化项目 — 确认 .codegraph/ 存在，若不存在则运行 codegraph init -i

Step 2. 选择合适工具 — 根据查询意图选择 MCP 工具（见工具选择矩阵）

Step 3. 执行查询 — 调用 MCP 工具获取结果。关键约束：

• 绝不在不熟悉的 API 或不确定的符号关系上胡编乱造；如果 CodeGraph 返回空结果或无法确认，直接告诉用户"未找到该符号/关系"，不强加虚构信息
• 信息不足时：先输出基于已有信息的假设版本，再列出具体缺少的 N 项内容，引导用户补充。禁止笼统提示"请提供更多信息"

Step 4. 处理结果 — 将返回的符号源码视为已读，无需再用 grep/read 验证

Step 5. 检查时效性 — 编辑文件后检查响应中的 ⚠️ staleness banner，若有则直接 Read 对应文件

MCP 工具选择矩阵

各工具参数详解见 references/mcp-tools.md

CLI 命令速查

codegraph install/uninstall         # 安装/移除 Agent 配置
codegraph init/uninit [path]        # 初始化/移除项目索引
codegraph index/sync [path]         # 索引/增量同步
codegraph status/query/files        # 状态查询
codegraph callers/callees/impact    # 调用链/影响分析
codegraph affected [files...]       # 受影响测试文件
codegraph serve --mcp               # 启动 MCP 服务器
codegraph upgrade [version]         # 升级

完整参考见 references/cli-reference.md

安装速查

自动安装（推荐）：

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
codegraph install

手动配置 Claude Code 见 references/installation.md

Gotchas

1. 先连接 MCP 服务器 — codegraph install 仅配置 Agent，不会自动启动 MCP；需重启 Agent 才能加载 2. `codegraph init -i` 是必需的 — 每个项目首次使用前必须初始化索引，否则所有 MCP 工具失败 3. 防抖窗口（2s）内的数据可能过时 — 编辑后立即查询可能返回旧数据，检查 ⚠️ banner 4. WSL/Windows 共享检出 — 不要共享同一 .codegraph/，使用 CODEGRAPH_DIR 区分 5. MCP 服务器自行交付使用指南 — 无需手动编辑 CLAUDE.md，指南通过 MCP initialize 自动交付 6. 排除目录 — node_modules、dist、build 等默认排除，通过 .gitignore 管理 7. 信息不足时不要笼统提问 — 先输出假设版本，再列具体缺少项（见 Workflow Step 3 模板）

Quick Fixes

详见 references/troubleshooting.md

FAQ

Q: CodeGraph 和 grep/find 有什么区别？ A: CodeGraph 构建完整的符号关系图谱，理解调用链、继承关系和框架路由；grep 只能做文本匹配，无法理解代码语义。

Q: 索引会占用多少空间？ A: 取决于代码库大小。典型项目（~1000 文件）约几 MB；大型项目（~10k 文件）约几十 MB。

Q: 支持 monorepo 吗？ A: 支持。在 monorepo 的各子项目目录中分别运行 codegraph init -i 即可。

Q: 如何更新索引？ A: MCP 服务器运行时自动同步。手动可运行 codegraph sync 增量更新或 codegraph index --force 重建。

Q: 可以离线使用吗？ A: 完全离线。所有数据存储在本地 SQLite 数据库中，无任何网络请求。

Q: 如何卸载？ A: 运行 codegraph uninstall 移除所有 Agent 配置；codegraph uninit 移除项目索引。

Q: 我的项目是 Java/Python/Rust，CodeGraph 支持吗？ A: 支持 20+ 语言，包括 Java、Python、Rust、Go、TypeScript 等。完整列表见 references/supported-languages.md

Q: 框架路由识别有什么用？ A: CodeGraph 能自动识别 Django、Express、Spring、Gin 等 14 个 Web 框架的路由绑定，将 URL 路径直接关联到处理器函数，方便追踪请求流转。

Q: 跨语言桥接覆盖哪些场景？ A: 支持 Swift↔ObjC 自动桥接、React Native 旧桥/TurboModules/Fabric、Expo Modules、以及原生→JS 事件通道。

Q: 索引失败或卡住怎么办？ A: 运行 codegraph status 查看状态；检查是否有大文件（>1MB 被跳过）；确认目录不在排除列表中；可尝试 codegraph index --force 重建。

Official Sources

• CodeGraph 官方文档
• GitHub 仓库
• npm 包

References

• MCP 工具详解
• CLI 命令参考
• 支持的语言
• 安装指南
• 故障排除
• 快速入门示例
• 官方文档索引

Audience

CodeGraph 官方文档索引

本文件索引 CodeGraph 的所有官方资源，供离线参考和快速导航。

核心资源

安装

文档导航

入门

• Get Started — 安装和配置指南
• Quick Start — 三步上手

功能

• Key Features — 核心功能列表
• Framework-aware Routes — 框架路由识别
• Mixed iOS/React Native/Expo — 跨语言桥接

参考

• CLI Reference — 命令行参考
• MCP Tools — MCP 工具列表
• Supported Languages — 支持的语言
• Supported Platforms — 支持的平台
• Supported Agents — 支持的 Agent
• Configuration — 配置说明

高级

• How It Works — 工作原理
• Library Usage — 嵌入使用
• Measured cross-file coverage — 覆盖率数据
• Benchmark Results — 性能基准

排障

• Troubleshooting — 故障排除

相关技术

许可证

MIT License — https://github.com/colbymchenry/codegraph/blob/main/LICENSE

CodeGraph 快速入门工作流示例

本文件提供完整的 CodeGraph 使用工作流示例，供 Agent 和用户参考。

示例 1：理解代码库架构

场景：用户想了解项目的整体架构。

工作流：

# 1. 确认项目已初始化
ls .codegraph/
# 如果不存在：codegraph init -i

# 2. 使用 MCP 工具查询
# Agent 调用：codegraph_explore("How is this project structured?")
# 返回：项目架构概览、主要模块、入口点

Agent 交互示例：

用户：这个代码库的架构是怎样的？

Agent：我来查询代码库的结构。
→ 调用 codegraph_explore("How is this project structured?")
→ 返回：按文件分组的符号源码、关系图、影响范围

Agent：[基于返回结果给出架构总结]

示例 2：追踪调用链

场景：用户想知道"请求如何到达数据库"。

工作流：

# Agent 调用：codegraph_explore("How does a request reach the database?")
# 返回：从路由处理器到数据库查询的完整调用链

Agent 交互示例：

用户：用户登录请求是如何处理的？

Agent：我来追踪认证流程。
→ 调用 codegraph_explore("How does the authentication flow work?")
→ 返回：路由 → 控制器 → 服务 → 数据库 的完整调用链

Agent：[基于返回结果解释认证流程]

示例 3：变更影响分析

场景：用户要修改 UserService，想知道影响范围。

工作流：

# Agent 调用：codegraph_impact(symbol="UserService", depth=3)
# 返回：所有直接和间接依赖 UserService 的符号

Agent 交互示例：

用户：我要修改 UserService，会影响什么？

Agent：我来分析影响范围。
→ 调用 codegraph_impact(symbol="UserService", depth=3)
→ 返回：受影响的符号列表和依赖链

Agent：修改 UserService 会直接影响以下模块：[列表]
建议运行以下测试：[测试文件列表]

示例 4：查找受影响的测试文件

场景：CI 中根据 git diff 找到需要运行的测试。

工作流：

# 获取变更文件
git diff --name-only HEAD

# 查找受影响的测试文件
git diff --name-only HEAD | codegraph affected --stdin --quiet

# CI 脚本示例
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

示例 5：符号搜索与详情查看

场景：用户想找 calculateTotal 函数的实现。

工作流：

# 1. 搜索符号
# Agent 调用：codegraph_search(query="calculateTotal", kind="function")
# 返回：符号位置列表

# 2. 查看详情
# Agent 调用：codegraph_node(symbol="calculateTotal")
# 返回：完整源码、定义位置、调用者/被调用者

示例 6：框架路由分析

场景：用户想知道 Express 应用有哪些 API 路由。

工作流：

# Agent 调用：codegraph_explore("What API routes are defined in this Express app?")
# 返回：所有路由定义及其处理器函数

Agent 交互示例：

用户：这个 Express 应用有哪些 API 路由？

Agent：我来查询路由定义。
→ 调用 codegraph_explore("What API routes are defined in this Express app?")
→ 返回：路由列表、HTTP 方法、处理器函数、中间件

Agent：[基于返回结果列出所有路由]

示例 7：跨语言桥接追踪（React Native）

场景：用户想知道 JS 调用如何到达原生模块。

工作流：

# Agent 调用：codegraph_explore("How does the JS call reach the native module?")
# 返回：JS → NativeModule → ObjC/Swift 的完整调用链

完整工作流总结

Agent 使用规则

1. `codegraph_explore` 是首选 — 几乎所有问题都应使用它 2. 信任返回结果 — 不要用 grep/read 重复验证 3. 检查 staleness banner — 编辑后检查 ⚠️ 标记 4. 若 `.codegraph/` 不存在 — 提示用户运行 codegraph init -i

CodeGraph CLI 命令参考

官方来源：README.md

命令总览

codegraph                         # 运行交互式安装程序
codegraph install                 # 安装并配置 Agent（显式）
codegraph uninstall               # 从所有 Agent 移除配置
codegraph init [path]             # 初始化项目（加 -i 同时构建索引）
codegraph uninit [path]           # 移除项目索引（--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 callers <symbol>        # 查找调用者（--limit、--json）
codegraph callees <symbol>        # 查找被调用者（--limit、--json）
codegraph impact <symbol>         # 分析影响范围（--depth、--json）
codegraph affected [files...]     # 查找受影响的测试文件
codegraph serve --mcp             # 启动 MCP 服务器
codegraph upgrade [version]       # 升级到最新版本（--check、--force）

命令详解

codegraph install

运行安装程序，连接 CodeGraph 到你的 Agent。

codegraph install                 # 交互式
codegraph install --yes           # 非交互式，自动检测 Agent
codegraph install --target=cursor,claude --yes  # 指定 Agent
codegraph install --target=auto --location=local  # 检测到的 Agent，项目级配置
codegraph install --print-config codex          # 打印配置片段，不写入文件

标志说明：

自动检测的 Agent：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro

codegraph uninstall

移除 CodeGraph 从所有已配置的 Agent。

codegraph uninstall               # 交互式
codegraph uninstall --yes         # 非交互式
codegraph uninstall --target=cursor  # 从指定 Agent 移除

说明：

• 移除 MCP 服务器配置、指令和权限
• 项目索引（.codegraph/）保持不变
• 使用 codegraph uninit 移除项目索引

codegraph init

在项目中初始化 CodeGraph。

codegraph init                    # 仅创建 .codegraph/ 目录
codegraph init -i                 # 创建目录并构建初始索引
codegraph init -i --force         # 强制重建索引

说明：

• 仅创建本地 .codegraph/ 索引目录
• 添加 -i（--index）同时构建初始图谱
• 不加 -i 则需后续运行 codegraph index

codegraph uninit

移除项目的 CodeGraph 索引。

codegraph uninit                  # 交互式确认
codegraph uninit --force          # 跳过确认

codegraph index

完整索引项目。

codegraph index                   # 索引当前目录
codegraph index /path/to/project  # 索引指定目录
codegraph index --force           # 强制重建
codegraph index --quiet           # 减少输出

codegraph sync

增量同步索引。

codegraph sync                    # 同步当前目录
codegraph sync /path/to/project   # 同步指定目录

说明：

• 通常不需要手动运行——MCP 服务器自动同步
• 适用于：禁用文件监听器、CI 脚本、Agent 会话外操作

codegraph status

显示索引统计信息。

codegraph status                  # 显示当前目录状态
codegraph status /path/to/project # 显示指定目录状态

返回内容：

• 文件数、符号数、边数
• 健康状态
• 待同步文件列表
• Journal 模式（应为 wal）

codegraph query

搜索符号。

codegraph query "UserService"                 # 基本搜索
codegraph query "login" --kind function       # 按类型过滤
codegraph query "auth" --limit 20             # 限制结果数
codegraph query "User" --json                 # JSON 输出

codegraph files

显示文件结构。

codegraph files                              # 默认树形格式
codegraph files --format flat                # 平面格式
codegraph files --format grouped             # 按语言分组
codegraph files --filter "*.ts"              # 过滤模式
codegraph files --max-depth 3                # 限制深度
codegraph files --json                       # JSON 输出

codegraph callers

查找调用者。

codegraph callers "authenticate"             # 基本查询
codegraph callers "UserService.login" --limit 10  # 限制结果
codegraph callers "calculateTotal" --json    # JSON 输出

codegraph callees

查找被调用者。

codegraph callees "handleRequest"            # 基本查询
codegraph callees "processOrder" --limit 10  # 限制结果

codegraph impact

分析影响范围。

codegraph impact "UserService"               # 默认深度
codegraph impact "DatabaseConnection" --depth 3  # 指定深度
codegraph impact "AuthService" --json        # JSON 输出

codegraph affected

查找受影响的测试文件。

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

codegraph serve --mcp

启动 MCP 服务器（供 Agent 使用）。

codegraph serve --mcp             # 启动 MCP 服务器

说明：

• 通常由 Agent 自动启动（通过 MCP 配置）
• 包含文件监听器和自动同步
• 交付使用指南给 Agent（通过 MCP initialize 响应）

codegraph upgrade

升级 CodeGraph。

codegraph upgrade                 # 升级到最新版本
codegraph upgrade --check         # 检查是否有更新
codegraph upgrade --force         # 强制升级
codegraph upgrade 1.2.3           # 升级到指定版本

说明：

• 自动检测安装方式（bundle、npm、npx）并原地更新

CodeGraph 安装指南

官方来源：README.md

快速安装（推荐）

1. 安装 CLI

无需 Node.js — 一条命令获取适合你 OS 的构建：

# 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：

npm i -g @colbymchenry/codegraph

说明：

• CodeGraph 内置运行时——无需编译，无原生构建，在所有平台上行为一致
• 安装程序将 codegraph 放到 PATH 上，但不会改变当前 shell — 开新终端后再执行下一步
• 升级：codegraph upgrade 自动检测安装方式并原地更新

2. 配置 Agent

在新终端中运行安装程序：

codegraph install

说明：

• 自动检测并配置 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro
• 这是连接 CodeGraph 到 Agent 的步骤；仅安装 CLI 不会自动完成
• 快捷方式：npx @colbymchenry/codegraph 一步完成下载和安装

3. 初始化项目

cd your-project
codegraph init -i

说明：

• codegraph init 仅创建本地 .codegraph/ 索引目录
• 添加 -i（--index）同时构建初始图谱
• 全局 codegraph install 只需运行一次——每个项目只需运行 codegraph init

手动配置

Claude Code

在 ~/.claude.json 中添加：

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

可选：在 ~/.claude/settings.json 中添加自动允许权限：

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

其他 Agent

运行 codegraph install --print-config <agent-id> 查看指定 Agent 的配置片段。

非交互式安装（CI/脚本）

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

标志说明：

升级

codegraph upgrade                 # 升级到最新版本
codegraph upgrade --check         # 检查是否有更新
codegraph upgrade --force         # 强制升级
codegraph upgrade 1.2.3           # 升级到指定版本

卸载

codegraph uninstall               # 移除所有 Agent 配置
codegraph uninit                  # 移除项目索引

支持的平台

环境变量

嵌入使用（Library Usage）

CodeGraph 可直接嵌入到你的应用中：

import CodeGraph from '@colbymchenry/codegraph';

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

嵌入要求：

• 从 npm 安装（npm i @colbymchenry/codegraph）
• API 运行在你的运行时上，需要 Node 22.5+（内置 node:sqlite）
• TypeScript 类型随包提供

CodeGraph MCP 工具详解

官方来源：README.md

工具总览

CodeGraph 作为 MCP 服务器运行时，向 Agent 暴露以下工具：

工具选择矩阵

各工具详解

codegraph_explore

用途：回答几乎所有代码问题的主要工具。

适用场景：

• "X 如何工作"
• 从 A 到 B 的流程追踪
• 区域概览
• 理解复杂交互

返回内容：

• 相关符号的源码（按文件分组）
• 关系图
• 影响范围（blast radius）

关键特性：

• 能处理动态分发跳转（回调、React 重渲染、接口→实现），这是 grep 无法做到的
• 将冗余的可互换实现折叠为签名，响应大小基于"答案"而非文件数
• 通常一次调用即可返回完整答案，无需文件读取

参数：

• task — 查询描述（如 "How does the authentication flow work?"）
• projectPath — 可选，项目路径

使用示例：

codegraph_explore("How does a request reach the database?")
codegraph_explore("How does the payment processing flow work?")

codegraph_search

用途：按名称在代码库中搜索符号。

适用场景：

• 查找特定函数/类/方法的位置
• 确认符号是否存在

参数：

• query — 搜索查询（符号名）
• kind — 可选，过滤类型（function、class、interface、method 等）
• limit — 可选，最大结果数（默认 10）
• projectPath — 可选，项目路径

使用示例：

codegraph_search(query="UserService", kind="class")
codegraph_search(query="calculateTotal", limit=5)

codegraph_callers

用途：查找谁调用了指定函数/方法。

适用场景：

• 理解函数的使用上下文
• 重构前评估影响
• 安全审查：谁使用了这个 API

参数：

• symbol — 符号名称
• limit — 可选，最大结果数（默认 20）
• projectPath — 可选，项目路径

使用示例：

codegraph_callers(symbol="authenticate")
codegraph_callers(symbol="UserService.login", limit=10)

codegraph_callees

用途：查找指定函数/方法调用了什么。

适用场景：

• 理解函数的依赖链
• 分析函数的复杂度
• 识别潜在的副作用

参数：

• symbol — 符号名称
• limit — 可选，最大结果数（默认 20）
• projectPath — 可选，项目路径

使用示例：

codegraph_callees(symbol="handleRequest")
codegraph_callees(symbol="processOrder", limit=10)

codegraph_impact

用途：分析修改某符号的影响范围（blast radius）。

适用场景：

• 修改前评估影响
• 确定需要运行的测试
• 安全审查：变更的连锁反应

参数：

• symbol — 符号名称
• depth — 可选，依赖遍历深度（默认 2）
• projectPath — 可选，项目路径

使用示例：

codegraph_impact(symbol="UserService", depth=3)
codegraph_impact(symbol="DatabaseConnection")

codegraph_node

用途：获取单个符号的完整详情和源码。

适用场景：

• 需要查看函数的完整实现
• 确认函数签名和参数
• 查看所有重载版本

参数：

• symbol — 符号名称
• includeCode — 可选，是否包含源码（默认 true）
• projectPath — 可选，项目路径

返回内容：

• 定义位置（文件、行号）
• 完整源码
• 调用者/被调用者线索
• 所有重载版本（对歧义名称）

使用示例：

codegraph_node(symbol="UserService.login")
codegraph_node(symbol="calculateTotal", includeCode=true)

codegraph_files

用途：获取已索引的文件结构。

适用场景：

• 快速了解项目结构
• 查找特定类型的文件
• 确认文件是否被索引

参数：

• format — 可选，输出格式（tree、flat、grouped），默认 tree
• pattern — 可选，过滤模式（如 *.ts、**/*.test.ts）
• maxDepth — 可选，最大目录深度
• includeMetadata — 可选，是否包含元数据（默认 true）
• projectPath — 可选，项目路径

使用示例：

codegraph_files(format="tree", maxDepth=3)
codegraph_files(pattern="**/*.ts", format="flat")

codegraph_status

用途：检查索引健康状态和统计信息。

适用场景：

• 验证索引是否正常
• 检查待同步文件
• 诊断索引问题

参数：

• projectPath — 可选，项目路径

返回内容：

• 索引统计（文件数、符号数、边数）
• 健康状态
• 待同步文件列表（若有）
• Journal 模式（应为 wal）

使用示例：

codegraph_status()

使用规则

1. `codegraph_explore` 是首选 — 几乎所有"如何工作"类问题都应使用它 2. 信任返回结果 — 返回的源码视为已读，不要用 grep/read 重复验证 3. 检查 staleness banner — 编辑后查询结果若含 ⚠️ 标记，直接 Read 对应文件 4. 若 `.codegraph/` 不存在 — 提示用户运行 codegraph init -i

CodeGraph 支持的语言与框架路由

官方来源：README.md

支持的语言（20+）

跨文件覆盖率

影响和 blast-radius 查询的质量取决于背后的依赖图质量。公平覆盖率 = 具有至少一个已解析跨文件依赖的符号承载源文件的份额——在每个语言的真实基准仓库上测量。

框架路由识别（14 个框架）

CodeGraph 检测 Web 框架路由文件并生成 route 节点，通过 references 边链接到处理器类或函数。

框架路由覆盖率验证

跨语言桥接（iOS / React Native / Expo）

CodeGraph 桥接多语言代码库中的语言边界，使 trace、callers、callees 和 impact 能跨语言端到端连接。

每个桥接发出标记为 provenance:'heuristic' 的边，metadata.synthesizedBy 设为稳定通道名（如 swift-objc-bridge、rn-event-channel）。

CodeGraph 故障排除

官方来源：README.md

常见问题

"CodeGraph not initialized"

原因：项目目录中没有 .codegraph/ 目录。

解决：运行 codegraph init -i 初始化项目并构建索引。

cd your-project
codegraph init -i

---

索引缓慢

原因：大型目录（如 node_modules、dist、build）未被排除。

解决： 1. 确认这些目录在 .gitignore 中（CodeGraph 自动排除 .gitignore 中的内容） 2. 使用 --quiet 减少输出开销 3. 检查默认排除目录是否包含你的大型依赖目录

默认排除的目录：node_modules、vendor、dist、build、target、.venv、Pods、.next 等

---

MCP database is locked

原因：旧版本（pre-0.9）使用文件锁，新版本使用 WAL 模式不会出现此问题。

解决：

1. 检查版本 — 运行 codegraph --version，如果不是最新版，重新安装：

# 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

# 或 npm
npm i -g @colbymchenry/codegraph@latest

2. 检查 Journal 模式 — 运行 codegraph status，确认 Journal: 为 wal

• 如果不是 wal（常见于网络共享和 WSL2 /mnt），WAL 无法在此文件系统上启用，读取可能被写入阻塞
• 解决方案：将项目（含 .codegraph/ 文件夹）移到本地磁盘

---

MCP 服务器无法连接

原因：项目未初始化/索引，或 MCP 配置路径错误。

解决： 1. 确认项目已初始化：ls .codegraph/ 2. 确认项目已索引：codegraph status 3. 检查 MCP 配置中的路径是否正确 4. 验证 codegraph serve --mcp 可从命令行运行

---

符号缺失

原因：文件尚未同步到索引。

解决： 1. 等待几秒——MCP 服务器自动同步（防抖窗口默认 2 秒） 2. 手动运行 codegraph sync 3. 检查文件语言是否支持 4. 检查文件是否在 .gitignore 或默认排除目录中（如 node_modules、dist）

---

WSL/Windows 共享检出问题

原因：WSL 和 Windows 指向同一个 .codegraph/ 目录，SQLite 锁定跨 WSL2/Windows 文件系统边界不可靠。

解决：不要让两侧指向同一个 .codegraph/。使用 CODEGRAPH_DIR 环境变量为每侧设置不同目录名：

# Windows 侧
export CODEGRAPH_DIR=.codegraph-win

# WSL 侧保持默认
# .codegraph

CodeGraph 会跳过任何兄弟 .codegraph-* 目录，两侧互不干扰。

---

诊断命令

# 检查索引状态
codegraph status

# 验证 MCP 服务器
codegraph serve --mcp

# 强制重建索引
codegraph index --force

# 手动同步
codegraph sync

# 检查版本
codegraph --version

Agent 工具指南

CodeGraph 的 MCP 服务器通过 MCP initialize 响应自动交付使用指南给 Agent，无需手动编辑 CLAUDE.md / AGENTS.md / GEMINI.md。

指南告诉 Agent：

• 使用 CodeGraph 工具直接回答结构化问题（不要用 grep/read 循环重复已索引的工作）
• 按意图选择工具：codegraph_explore 用于几乎所有问题
• 信任返回结果——不要用 grep 重新验证
• 如果 .codegraph/ 不存在，主动提示用户运行 codegraph init -i

TRACE Evaluation Report

Target: /Users/wandl/workspaces/workspace-full-statck-skills/full-stack-skills-repositories/utility-skills/skills/codegraph/

Overall Assessment

Overall Score: 4.4 / 5 Overall Rating: Good (良好)

文档体系完整，边界清晰，Gotchas 和 FAQ 覆盖到位。主要扣分项：脚本未能正确识别 Capability Boundaries 章节导致 T3/R4/A1 基分偏低，经语义校准后仍受限于 ±0.3 调幅规则；examples 为单文件含 7 个工作流但脚本按文件计数导致 C1/E2 基分偏低。

TRACE Dimension Explanation

SkillHub TRACE 评测体系从可信任度、可靠性、适用性、规范性、有效性五个维度全面评估。 了解详情

评测基于 AI 自动化检测，结果供参考。

Evaluation Details

T · Trust — 4.6 / 5

纯文档型零风险，全中文适配，数据隐私声明完整。T3 因脚本未识别 Capability Boundaries 章节导致基分偏低，经校准后仍有提升空间。

R · Reliability — 4.4 / 5

异常处理有 Gotchas 7 条覆盖核心陷阱，Quick Fixes 表格实用。降级兜底因边界检测问题基分偏低。

A · Adaptability — 4.2 / 5

场景化路由清晰，description 实际 200+ 字符但脚本解析 YAML 多行格式异常导致基分偏低。

C · Convention — 4.45 / 5

三层结构清晰（Quick Start → 功能详情 → references/），Gotchas 7 条 + FAQ 6 题。

E · Effectiveness — 4.3 / 5

Workflow + 工具选择矩阵确保不同场景有明确执行路径。examples 单文件含 7 个完整工作流但脚本按文件计数。

Improvement Suggestions (prioritized)

1. P1: 拆分 examples/ 为多个文件 — 将 7 个工作流示例拆分为独立文件（如 architecture.md、call-chain.md、impact-analysis.md 等），CLI 型阈值为 4 个 examples 文件，当前仅 1 个。C1/E2 可提升至 5.0。 2. P1: 为 references/ 添加子目录 — 如 references/mcp/、references/cli/、references/setup/ 等，CLI 型 threshold 为 ≥2 个子目录。C3 可提升至 5.0。 3. P2: 添加交互式引导模板 — 在 Gotchas 或 Workflow 中添加"信息不足时先给假设版本 + 列具体缺少项"的模板。R1 可提升至 5.0。 4. P2: 修复 YAML frontmatter description 解析 — 当前 description: > 格式导致脚本解析为长度 1。建议改为单行 description: "..." 或确保脚本正确解析多行 YAML。A2 可提升至 5.0。 5. P3: 扩充 FAQ 至 8-10 题 — 当前 6 题覆盖基础问题，建议增加边缘场景（如 monorepo 多语言项目、大型代码库性能、与 CI/CD 集成最佳实践等）。

Skill 基础画像

---

评测时间：2026-06-16

评测脚本：trace_evaluate.py

校准规则：calibration-guide.md（±0.3 调幅）