为什么需要代码索引?
当你把代码丢给 AI 编程助手时,它面临两个核心问题:窗口限制与上下文稀疏。代码库里 99% 的文件对你当前任务都是无关的——但大模型并不知道哪些是关键入口。一个粗糙的 rag-over-files 往往把错误的模块塞进上下文,导致生成代码不可用。
CodeGraph 的思路是:先把代码理解为结构 + 关系图,再让 AI 根据查询去检索这个图,而不是盲目扫描所有文件。
四个核心能力
| 能力 | 做什么 | 典型场景 |
|---|---|---|
| 架构关系 · Architecture | 识别模块边界、包/目录分层、数据流 | "这个项目是怎么组织的?" |
| 依赖图谱 · Dependency | 构建 import / call graph、模块依赖拓扑 | "改这个文件会影响谁?" |
| 符号检索 · Symbol | 函数/类/变量的定义、引用、类型签名 | "查找某个函数所有调用位置" |
| 变更影响 · Impact | 根据 git diff 自动计算受影响范围与测试 | "本次 PR 需要跑哪些单测?" |
工作原理(简化版)
CodeGraph 把一个工程的"理解"拆成三步:
① 静态解析:针对不同语言(TS/Python/Rust/Go/Java…)使用轻量级 AST 解析器与语言服务器协议(LSP)索引,提取文件中的符号、类型签名、import 依赖。
② 图构建:将函数/类/模块抽象为节点,调用 / 导入 / 继承关系抽象为边;同时计算节点的"中心性"与"分层等级",识别入口 / 核心 / 边缘模块。
③ 语义搜索:把代码摘要与描述向量化,结合图结构做混合检索——让一次自然语言查询同时命中符号与语义相关的代码段。
# 最简单的使用:在项目根目录执行 codegraph index . codegraph query "登录流程中哪些函数负责写数据库?"
与 AI 编程代理协同
CodeGraph 的输出可以直接 feed 给 Claude、Cursor、OpenClaw 等工具作为 RAG 上下文。典型接入方式有三种:
2 · IDE 插件:在 VSCode / Cursor 中安装 CodeGraph 插件,它会在"Ask AI"时自动把相关代码段作为上下文注入;
3 · 本地 HTTP 服务:`codegraph serve` 起一个 REST 服务,你的 AI 代理可以按 LSP 风格查询符号与依赖。
它解决了什么真正的问题?
在日常工程中,AI 编程助手失败的原因往往不是模型能力不够,而是它拿到的上下文"不全、不准、也不聚焦"。常见三类错误:
CodeGraph 的索引是一种"让 AI 站在工程师肩膀上"的做法:把代码库里最关键的关系信息预先计算好,再按需提供给 AI 作为压缩后的上下文。
同类工具对比
| 工具 | 定位 | 典型工作流 |
|---|---|---|
CodeGraph |
本地代码索引 + 图检索 | 配合任意 Agent / IDE |
Sourcegraph Cody |
云/本地混合,IDE 深度集成 | Cody: 聊天 + 多文件编辑 |
OpenClaw / Harness |
AI Agent 框架 | 任务执行 + 多技能组合 |
tree-sitter + grep |
DIY 管线 | 脚本化定制检索 |