codegraph - 先给 AI 编码代理一张本地代码地图

AI 编码代理越来越像一个新同事：它能改代码、跑命令、写测试，但如果一开始拿到的是一堆散落的文件，它也会像新人一样误判结构。常见情况是，代理先 grep，再读几个大文件，然后凭上下文猜某个函数的调用范围。小项目还能接受，到了中型代码库，猜错一个 helper 的边界，就可能把影响面留给 code review 或 CI 才发现。

今天推荐的 optave/ops-codegraph-tool 就是为这个问题设计的本地代码图工具。它发布到 npm 的包名是 @optave/codegraph，提供 codegraph CLI 和 MCP server，把代码库解析成函数级依赖图，让 AI agent 或开发者在修改前先查询“这个符号在哪里、谁调用它、它会影响哪些函数”。GitHub 搜索结果当前显示项目约有 64 stars、12 forks，主要语言为 TypeScript 和 Rust，许可为 Apache-2.0。npm 最新版本显示为 3.11.1。

项目概览

属性	详情
仓库	optave/ops-codegraph-tool
npm 包	@optave/codegraph
Stars	约 64
Forks	12
主要语言	TypeScript、Rust
许可	Apache-2.0
当前版本	v3.11.1

它解决的是结构上下文问题

普通 AI 编码流程里，代理最缺的不是“会不会写代码”，而是“在写之前知不知道代码结构”。如果它只读了一个文件，很容易不知道某个函数还有十几个上游调用者；如果它为了安全把相关文件都读一遍，又会快速消耗上下文窗口。

codegraph 的切入点是把这类结构信息提前索引好。README 里介绍，它会用 tree-sitter 解析代码，构建函数、调用、导入、导出、角色、复杂度、控制流和数据流等信息，再存在本地 SQLite 数据库里。代理需要上下文时，不必连续跑二十次 grep、find 和 cat，而是可以直接问图数据库。

这类工具的价值不在于替代类型系统或测试，而是减少“盲改”。比如你准备修改 parseConfig，可以先查它在哪个文件、调用了谁、被谁调用、变更会影响哪些函数。对 AI agent 来说，这比只把一段源代码塞进 prompt 更接近真实工程判断。

CLI 和 MCP 是两个入口

codegraph 同时面向人和 agent。人可以直接用 CLI：

npm install -g @optave/codegraph
cd your-project
codegraph build
codegraph where handleAuth
codegraph context handleAuth -T
codegraph diff-impact --staged -T

这些命令覆盖了几个高频动作：定位符号、查看函数上下文、查调用链、看文件依赖、分析变更影响、检查循环依赖和复杂度。

对 AI agent 来说，更关键的是 MCP server：

codegraph mcp

README 里写到，它提供三十多个 MCP tools。这样 Claude Code、Cursor、其他支持 MCP 的编码代理就可以直接查询本地代码图，而不是把所有导航都退化成 shell 命令和全文读取。默认 single-repo 模式只操作当前项目的 .codegraph/graph.db，multi-repo 需要显式打开，这个默认边界比较重要。

函数级影响分析比文件级更细

很多代码浏览工具能告诉你“这个文件 import 了什么”。codegraph 更关注函数级关系：一个函数调用了哪些函数，哪些函数会调用它，改动它以后会传导到哪些上游节点。

这对重构很实用。文件级依赖图在大模块里容易太粗，比如一个工具文件里有几十个函数，你只改其中一个函数时，不一定需要把整个文件的所有 importers 都看成风险。函数级图至少能把影响面缩小到具体符号，方便代理先审查真正相关的调用链。

README 里还提到 role classification，会把符号归类为 entry、core、utility、adapter、dead、leaf 等角色。这个设计很适合给 agent 做风险提示：同样是一行改动，改 leaf 函数和改高 fan-in 的 core 函数，审查方式不应该一样。

Diff impact 适合放进提交前流程

我觉得 codegraph 最值得尝试的场景是提交前检查。diff-impact 会分析当前 git diff，找出改动覆盖到的函数，再追踪它们的调用者和影响面。

这对人也有用，但对 AI agent 尤其有用。很多代理能完成“把代码改到测试通过”，却不一定会主动问“这次修改的 blast radius 有多大”。如果把 codegraph diff-impact --staged -T 放进 agent 指令或 hook，就能在 commit 前得到一份结构化提醒。

README 还展示了 GitHub Actions 的使用方式：PR 里生成影响分析评论，或者设置阈值，当影响函数数超过某个值时失败。它不是传统 lint，而是把结构风险变成 CI 可以消费的信号。

多语言和本地优先

codegraph 的 README 宣称支持 34 种语言，覆盖 JavaScript、TypeScript、Python、Go、Rust、Java、C#、PHP、Ruby、C/C++、Kotlin、Swift、Scala、Bash、HCL、Elixir、Lua、Dart、Zig 等。对于多语言 monorepo，这比只支持某一门语言的工具更容易统一接入。

实现上，它有两条解析路径：Rust native addon 和 WASM tree-sitter fallback。package.json 里可以看到 TypeScript 主体、Rust 原生包、SQLite 依赖以及可选的 MCP SDK。README 还强调默认本地运行、无 telemetry、不需要 API key；语义搜索和更深的 LLM 能力则是可选能力。

这个边界值得肯定。代码结构索引本身不应该默认把源码发到远端服务。对企业仓库或私有项目来说，先在本地构建 SQLite 图，再按需决定是否接 LLM provider，比“上传代码再分析”的模型更容易接受。

不只是搜索，也在做架构约束

codegraph 的功能列表很长，除了 where、context、query 这类导航命令，还包括 complexity metrics、cycles、co-change analysis、CODEOWNERS integration、architecture boundaries、manifesto rules、triage queue 和 graph export。

这些功能说明它不是单纯的代码搜索器，而是试图把结构分析、影响分析和质量门禁放进一个工具里。例如：

• cycles 用来找循环依赖；
• complexity 统计函数复杂度；
• roles --role dead 查未引用符号；
• check --staged 可以作为 CI 或 pre-commit 的 pass/fail 信号；
• owners 能把 CODEOWNERS 信息映射到符号层面；
• plot 可以生成交互式图视图。

对团队来说，最现实的采用方式不是一次打开所有功能，而是先选一条窄路径：比如只把 build、where、context、fn-impact 和 diff-impact 给 agent 使用。等图数据稳定后，再考虑 CI gates 和边界规则。

适合什么工作流

我会把 codegraph 推荐给几类人先试：

• 正在用 Claude Code、Codex、Cursor 或其他 AI coding agent 改真实代码库；
• 代理经常因为读错调用关系而产生返工；
• 代码库跨多语言，普通 grep 和 LSP 视角不够统一；
• 团队想在 PR 里展示结构影响面，而不只是跑 lint 和 test；
• 希望 MCP 工具默认本地运行，避免把源码结构上传给第三方服务；
• 想给 agent 写更具体的工程约束，例如“修改前先查 fn-impact，提交前跑 diff-impact”。

如果你的项目很小，或者主要问题只是“搜索某个函数在哪里”，LSP、ripgrep 和 IDE 已经足够。codegraph 的价值会在代码库变大、调用关系变深、agent 参与修改变频繁时更明显。

需要注意的边界

这类静态分析工具一定有边界。README 自己也列出了限制：TypeScript 解析不等于完整调用 tsc 类型检查；动态调用是 best-effort；Python import 不会完整跟随所有 sys.path 或虚拟环境包；数据流分析是函数内范围，不是跨函数全程序分析。

所以不要把它当成“绝对正确的调用真相”。更合理的定位是：它给 agent 和 reviewer 一张足够有用的地图，帮助先发现明显的影响面和结构风险。地图不等于现场，但没有地图时，代理很容易只靠局部视野行动。

另外，图数据库需要保持新鲜。README 提供了 watch mode、incremental build、hook 示例和 CI 缓存建议。真正放进团队流程时，要确认 .codegraph/graph.db 什么时候重建、什么时候缓存、什么时候强制全量 rebuild。否则 agent 查询到过期图，反而会增加误导。

总结

optave/ops-codegraph-tool 是一个很适合 AI 编码时代的小众开发者工具。它抓住了一个真实问题：AI agent 不应该每次都从零开始摸代码结构，也不应该只靠几次 grep 猜影响面。

它的路线是本地构建函数级依赖图，再通过 CLI、MCP server、CI gate 和 hook 把这张图交给人和 agent 使用。对已经让 AI agent 参与真实开发的团队来说，这类“结构上下文层”会越来越重要。codegraph 还在快速演进，但它给出的方向很清楚：在让代理动手之前，先让它看见代码库的地图。

项目地址：https://github.com/optave/ops-codegraph-tool