CodeGraph

为 AI 编程 Agent 预先构建本地代码关系图，并通过 MCP 按需返回精确源码、调用链与改动影响范围的代码智能工具。

#type / resource #status / growing #tech / ai #resource / codegraph #purpose / development #media / tool #interface / ai #interface / cli

[!abstract] 一句话结论 CodeGraph 解决的是 Agent 为理解代码而反复 grep → 打开文件 → 猜调用关系 的上下文浪费：它把仓库预索引为本地关系图，再通过一个 MCP 查询按需交付最相关的真实源码和关系路径。

[!info] related notes

CodeGraph

它解决的不是“把整个仓库塞给模型”

没有 CodeGraph 时，Agent 常用文本搜索和逐文件阅读自己重建项目结构。它能找到关键词，却很难可靠地回答“谁调用这个函数”“这项修改会影响哪里”“路由最终落到哪个处理器”。大仓库中，这会产生很多工具调用、无关代码和重复推理。

CodeGraph 是面向编程 Agent 的本地语义代码索引器与 MCP Server。它预先记录符号、导入、引用和调用等关系；查询时只返回回答当前问题所需的代码窗口与图关系。因此它适合日常定位、调用链追踪、影响范围分析，而不是替代完整架构文档或运行时调试器。

从源码到 Agent 上下文的工作原理

源码文件
  → 解析与符号/关系提取
  → 本地 SQLite + 全文索引中的代码图
  → 名称检索、关系遍历、影响范围分析
  → codegraph_explore
  → Agent 得到带行号的源码、调用路径和相关文件

官方当前实现以原生 Rust 内核解析主要语言，并在无法使用该内核的个别文件上回退。图数据库保存在项目的 .codegraph/，不需要部署独立的图数据库，也不把代码上传给云端服务。

查询不是向量 RAG：它先依据符号、限定名、签名、文件名等文本索引找候选，再沿调用、引用、导入或继承等关系扩展，最后按输出预算聚合真实源码。这种“查询时组装上下文”的方式被官方称为 surgical context。

[!warning] 静态分析的边界 动态分发、反射、运行时生成代码和高度间接的回调并不总能被静态图准确还原。CodeGraph 可能用启发式补边，但查询结果是高价值线索，不是运行时真相；关键改动仍要读当前文件并跑测试。

为什么 MCP 只暴露少量工具

CodeGraph 的默认工作流以 codegraph_explore 为主：一次查询可组合符号定位、源码片段、callers/callees 和影响范围。工具少不是功能少，而是避免 Agent 先在多个相近工具中选错、再退回到逐文件搜索。

适合这样问：

从 Web 路由入口追踪到保存记录的调用链，并说明改动该 service 会影响哪些调用方。

不适合只问“项目有哪些业务模块”；那是架构归纳问题，通常应与 Repomix、项目文档或人工阅读结合。

配置与启动：serve --mcp 到底做了什么

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

这不是启动一个 HTTP 网站。支持 stdio 的 MCP Host 会把 codegraph serve --mcp 启成子进程，通过它的 stdin / stdout 交换逐行 JSON-RPC；CodeGraph 再按工作区根目录打开或建立 .codegraph 索引。详细通信模型见 本地 MCP Server。

常规生命周期：

  1. codegraph install：为所选 Agent 写入其客户端配置；它本身不建立项目索引。
  2. 在项目根目录执行 codegraph init：生成 .codegraph/ 并完成首次建图。
  3. Agent 会话启动 MCP Server：服务在连接时追赶未索引的变更，并在运行时监听文件变动、增量同步。
  4. 需要时用 codegraph status 验证索引是否可读、是否仍有待同步文件。

dailyuse 本地核查（2026-07-23）

D:\home\projects\dailyuse 已具备项目级 .mcp.json、.codegraph/codegraph.db、.gitignore 排除规则，并在 AGENT.md 中要求日常代码探索优先使用 CodeGraph。这些结构是合理的。

但当前验证没有通过：本机 CLI 为 0.9.9，而官方最新 release 为 1.5.0；从该项目根目录运行 codegraph status 与 codegraph query 均报 unable to open database file。因此当前索引不能视为健康，也不能仅凭历史 daemon.log 断言 MCP 可用。

另外，当前 Codex 用户配置只有 nx-mcp，未见 codegraph 条目；项目的 .mcp.json 是否被读取取决于具体 Host。若要让 Codex 使用它，应以 Codex 的 MCP 配置方式单独注册，或用 CodeGraph 的 install 针对 Codex 安装。不要把某个客户端的 JSON 配置格式复制给所有客户端。

推荐恢复顺序（会改动本地工具或索引，应在项目中单独执行）：

  1. codegraph upgrade --check，确认升级路径与版本。
  2. 在 dailyuse 根目录重新运行 codegraph status；若仍失败，先保存现有诊断信息，再按官方文档重新初始化索引。
  3. 在目标 Agent 中确认已出现 CodeGraph 工具，并实际发起一次符号/调用链查询。
  4. 修改一个小文件后再次查询，确认自动同步真实发生。

选择边界

需求更合适的工具
某函数在哪里、谁调用它、改它影响什么CodeGraph
第一次理解陌生仓库、产出架构知识图谱GitNexus 或项目文档
将仓库高质量打包给模型、制作阶段性快照Repomix
Nx project、target、affected 与任务依赖Nx MCP

官方入口

创建于 2026/7/23 更新于 2026/7/23