inline-01.png图Agent 从关键词搜索转向语义代码图谱导航传统代码检索默认把仓库当作文本集合。这个假设对人还勉强够用因为人会把搜索结果、目录结构、命名习惯和经验放在一起判断。Agent 不一样它每走一步都要消耗上下文和工具调用预算。典型链路大概是这样mermaid-01.png图传统 Agent 依赖目录与关键词反复找入口问题不在 grep 本身。问题是“​结构性问题​”被降级成了“文本命中问题”。比如用户问“登录请求最终怎么写入数据库”Agent 真正需要的是路由、handler、service、repository、ORM 调用之间的关系。它不需要先看到 20 个包含 login 的文件。再比如用户问“改这个方法会影响谁”答案应该来自调用图而不是一次次全文搜索。CodeGraph 的思路更直接把这些关系提前算出来。Agent 提问时查询对象不再是“文件里有没有某个字符串”而是“图上哪些节点和边与这个问题相关”。CodeGraph 的定位本地代码图谱不是又一个搜索框CodeGraph 可以理解为一个本地优先的​代码语义索引系统​。它会解析源码抽取函数、类、路由、组件等节点再把调用、继承、导入、路由绑定、组件引用等关系写进本地 SQLite。对外它主要提供两类入口入口 更适合谁用 典型用途CLI 开发者、脚本、CI 流程 查符号、查调用方、做影响面分析MCP Server Claude、Cursor、LangChain、OpenAI Agents 等 Agent 框架 让模型直接调用结构化代码工具常用工具可以按问题类型来理解工具 解决的问题codegraph_search 某个符号、函数、类在哪里定义codegraph_context 围绕一个自然语言问题组装相关代码上下文codegraph_trace 追踪一条执行路径或调用链codegraph_callers/codegraph_callees 谁调用我、我调用谁codegraph_impact 某个变更可能影响哪些下游节点codegraph_node 查看单个符号的结构化详情codegraph_explore 同时展开多个相关实现codegraph_files 查询索引后的文件结构codegraph_status 检查索引状态和同步情况这里有个重要边界CodeGraph 不是运行时观测系统。它擅长静态结构不负责证明某条分支在线上是否真的走到。动态加载、反射、运行时注入这类场景它只能尽力推断。离线建图把“找入口”的成本前移CodeGraph 的核心收益来自一个朴素的取舍构建索引时多花一点时间查询时少让 Agent 瞎转。整体链路可以压成四层mermaid-02.png图从源码抽取到图查询再到 Agent 上下文这张图背后有三个关键动作。第一Extraction 负责把源码拆成结构化元素。CodeGraph 使用 tree-sitter 和 WASM 解析多语言代码通过 worker thread 并行处理文件。函数、类、接口、路由、组件会变成节点调用、继承、导入会变成边。解析阶段暂时无法确定的关系会先落到 unresolved_refs。第二Resolution 负责把“看起来像调用”的文本关系补成真实关系。比如 foo() 到底是当前文件里的函数、import 进来的方法还是类成员Express 的 app.post(‘/login’, loginHandler) 又该怎么连接到 handler这一步决定了图谱是否真的比全文搜索更有价值。第三Graph Query 和 Context Builder 把图转成 Agent 能直接消费的答案。Agent 不需要拿到整个仓库只需要拿到与问题有关的子图、关键代码片段和路径说明。数据模型文件、符号、关系和未决引用inline-02.png图源码经过抽取和解析后沉淀为本地语义图谱CodeGraph 的底层模型不复杂复杂的是边的质量。mermaid-03.png图文件、节点、关系和未决引用构成代码图谱几张表的职责很清楚表 保存什么 为什么重要files 路径、hash、语言、索引时间 判断文件是否变化支撑增量同步nodes 函数、类、路由、组件等符号 Agent 查询的基本对象edges 调用、继承、导入、路由绑定等关系 调用链、影响面、上下文构建都依赖它unresolved_refs 抽取阶段还没确定的引用 留给解析层补全避免过早丢信息如果只抽节点CodeGraph 只是一个更规整的符号索引。真正让它有用的是边谁依赖谁谁调用谁哪个 URL 进入哪个 handler哪个 React 组件渲染了哪个子组件。Resolution代码图谱的难点在“懂框架”AST 能告诉我们“这里有个函数调用”但很多工程语义不写在普通调用里。后端框架里路由到 handler 可能来自装饰器、注解、配置或注册函数前端框架里组件依赖藏在 JSX、模板或编译约定中跨端项目里JS 到 Native 的桥接关系更不会自然变成一条普通函数调用边。CodeGraph 的解析层要处理这些关系场景 文本搜索看到的东西 图谱应该补出的关系Express / NestJS URL 字符串、handler 名称 POST /login→loginHandlerSpring / Django / FastAPI 注解、装饰器、方法定义 Controller / route → action 方法React / Vue / Svelte JSX、模板标签、组件 import 父组件 → 子组件React Native / Expo NativeModule、Bridge 导出 JS 可调用 API → Native 实现普通模块系统 相对路径、别名、包名 import 标识符 → 真实定义这一步也是风险来源。框架规则越多覆盖面越好规则没覆盖到的动态行为就只能靠启发式补边。工程上更稳妥的做法是把边的来源和置信度一并保存Agent 回答时能区分“精确解析”和“推断结果”。Context Builder让 Agent 拿到“可回答的子图”codegraph_context 是 ​CodeGraph 最适合 Agent 的能力​。它不是简单返回搜索结果而是围绕一个自然语言问题组织上下文。一个典型流程如下mermaid-04.png图自然语言问题被压缩成可回答的相关子图这比“把搜到的文件都扔给模型”更克制。Agent 得到的是已经压缩过的结构入口点、主要链路、相关符号、关键代码块、可能的下游影响。它仍然可以继续 Read 某些文件但不必把探索路径从零开始走一遍。我的建议是问“在哪里定义”时用 search问“这个功能怎么跑起来”时用 context问“请求如何穿过系统”时用 trace问“改这里会影响什么”时用 impact已经锁定一个符号后再用 node 或直接读源码。先结构后细节。这个顺序对 Agent 很重要。索引保鲜不要让 Agent 信过期的图代码图谱最怕一件事索引刚建好代码马上变了。CodeGraph 用文件监听和增量同步降低这个问题。开发者保存文件后FileWatcher 记录 pending files通过 debounce 合并短时间内的连续修改再触发同步。同步完成前MCP 工具返回结果时会带上 stale 提示告诉 Agent 哪些文件刚改过相关结论可能过期。mermaid-05.png图文件变化后的增量同步与 stale 提示这个设计比“假装图永远正确”更诚实。Agent 可以继续信任未变更文件的结构结论对刚保存的文件直接读取源码更稳。MCP 接入把代码图谱变成 Agent 的本地工具CodeGraph 通过 MCP 暴露能力后Agent 框架不需要理解它的内部实现只要把它当作一组工具调用。mermaid-06.png图Agent 通过 MCP 查询本地代码图谱这里有两个工程点值得保留。一个是共享后台进程。Cursor、Claude Desktop、脚本工具可以连接同一个 codegraph serve --mcp 进程避免每个客户端都重新索引。另一个是同步窗口提示。文件刚变化时工具结果会明确告诉 Agent 哪些信息可能旧。这会减少“模型拿旧索引强行推理”的风险。Python Agent 的两种接入写法如果项目里已经安装了 CodeGraph可以先建索引cd /path/to/your-projectcodegraph init -i没有全局安装时也可以用 npx 启动 MCP 服务npx -y colbymchenry/codegraph serve --mcp --path /path/to/your-projectLangChain / LangGraphLangChain 体系里langchain-mcp-adapters 可以把 MCP tools 转成 LangGraph Agent 可用的工具。pip install langchain-mcp-adapters langgraph langchain-openai如果不想依赖全局命令把 MCP 启动参数改成“command”: “npx”,“args”: [ “-y”, “colbymchenry/codegraph”, “serve”, “–mcp”, “–path”, “/path/to/your-project”,]OpenAI Agents SDKOpenAI Agents SDK 支持 stdio MCP server接入方式更薄一些。pip install openai-agentsCLI 和 Skill把原子命令封成稳定动作CLI 适合开发者直接验证也适合放进自动化脚本。初始化并建立索引codegraph init -i查看索引状态codegraph status搜索符号codegraph query UserService根据问题构造上下文codegraph context “分析登录请求从路由到数据库的完整链路”查看调用者 / 被调用者codegraph callers logincodegraph callees login分析影响面codegraph impact UserService查看索引文件树codegraph files --format tree增量同步codegraph sync根据当前 diff 推断受影响测试