01 · Motivation

为什么需要代码索引?

当你把代码丢给 AI 编程助手时,它面临两个核心问题:窗口限制与上下文稀疏。代码库里 99% 的文件对你当前任务都是无关的——但大模型并不知道哪些是关键入口。一个粗糙的 rag-over-files 往往把错误的模块塞进上下文,导致生成代码不可用。

CodeGraph 的思路是:先把代码理解为结构 + 关系图,再让 AI 根据查询去检索这个图,而不是盲目扫描所有文件。

核心观察: 如果一个工程师读代码需要 3 小时——从入口函数开始,追踪调用链,检查依赖,跳转到配置文件——那么 AI 编程代理也需要同样的能力,只是以毫秒为单位。
02 · What It Does

四个核心能力

能力 做什么 典型场景
架构关系 · Architecture 识别模块边界、包/目录分层、数据流 "这个项目是怎么组织的?"
依赖图谱 · Dependency 构建 import / call graph、模块依赖拓扑 "改这个文件会影响谁?"
符号检索 · Symbol 函数/类/变量的定义、引用、类型签名 "查找某个函数所有调用位置"
变更影响 · Impact 根据 git diff 自动计算受影响范围与测试 "本次 PR 需要跑哪些单测?"
03 · Architecture

工作原理(简化版)

CodeGraph 把一个工程的"理解"拆成三步:

① 静态解析:针对不同语言(TS/Python/Rust/Go/Java…)使用轻量级 AST 解析器与语言服务器协议(LSP)索引,提取文件中的符号、类型签名、import 依赖。

② 图构建:将函数/类/模块抽象为节点,调用 / 导入 / 继承关系抽象为边;同时计算节点的"中心性"与"分层等级",识别入口 / 核心 / 边缘模块。

③ 语义搜索:把代码摘要与描述向量化,结合图结构做混合检索——让一次自然语言查询同时命中符号与语义相关的代码段。

# 最简单的使用:在项目根目录执行
codegraph index .
codegraph query "登录流程中哪些函数负责写数据库?"
04 · Integration

与 AI 编程代理协同

CodeGraph 的输出可以直接 feed 给 Claude、Cursor、OpenClaw 等工具作为 RAG 上下文。典型接入方式有三种:

1 · CLI 管道:把 `codegraph query --json "..."` 的 JSON 结果通过 shell/函数调用喂给 Agent;

2 · IDE 插件:在 VSCode / Cursor 中安装 CodeGraph 插件,它会在"Ask AI"时自动把相关代码段作为上下文注入;

3 · 本地 HTTP 服务:`codegraph serve` 起一个 REST 服务,你的 AI 代理可以按 LSP 风格查询符号与依赖。
05 · Why It Matters

它解决了什么真正的问题?

在日常工程中,AI 编程助手失败的原因往往不是模型能力不够,而是它拿到的上下文"不全、不准、也不聚焦"。常见三类错误:

过度猜测: AI 只看到冰山一角的文件,便推断整个系统的数据模型,生成的代码与实际约定不一致。
遗漏副作用: 修改函数签名时,AI 没有更新所有调用点——因为它根本没见过被调用方的文件。
无法定位: 面对一个 bug 描述,AI 不知道应该先看哪些模块的代码,只能让你手动找。

CodeGraph 的索引是一种"让 AI 站在工程师肩膀上"的做法:把代码库里最关键的关系信息预先计算好,再按需提供给 AI 作为压缩后的上下文。

06 · Alternatives

同类工具对比

工具 定位 典型工作流
CodeGraph 本地代码索引 + 图检索 配合任意 Agent / IDE
Sourcegraph Cody 云/本地混合,IDE 深度集成 Cody: 聊天 + 多文件编辑
OpenClaw / Harness AI Agent 框架 任务执行 + 多技能组合
tree-sitter + grep DIY 管线 脚本化定制检索
07 · Resources

相关资源与链接

CodeGraph 官方网站 GitHub · 开源仓库 Sourcegraph / Cody 文档 Language Server Protocol Tree-sitter · 语法解析 Cursor · AI IDE

相关阅读

国内服务器部署 OpenClaw DeepSeek 生态导航
CodeGraph AI 编程代理 代码索引 LSP RAG