CodeGraph:符号 / 文件 / 调用关系 / 影响路径

文档摘要

CodeGraph:符号 / 文件 / 调用关系 / 影响路径本节摘要:本节讲知识引擎的第二条线——CodeGraph。它把代码库索引成四类信息的图谱:符号(函数/类/变量)、文件(组织结构)、调用关系(谁调用谁)、影响路径(改了影响哪)。本节重点讲清「影响路径(impact analysis)」这个 CodeGraph 区别于普通代码搜索的独特价值——普通搜索只告诉「代码在哪」,CodeGraph 还告诉「改了可能影响哪」。这让 Agent 在改代码前能评估风险,是「安全改代码」的关键能力。一、CodeGraph 索引的四类信息 CodeGraph 不是「代码搜索引擎」,它索引的是一个图谱的四类节点与边: 信息 | 回答的问题 | 例子符号 | 「这个函数在哪定义?

CodeGraph:符号 / 文件 / 调用关系 / 影响路径

本节摘要:本节讲知识引擎的第二条线——CodeGraph。它把代码库索引成四类信息的图谱:符号(函数/类/变量)、文件(组织结构)、调用关系(谁调用谁)、影响路径(改了影响哪)。本节重点讲清「影响路径(impact analysis)」这个 CodeGraph 区别于普通代码搜索的独特价值——普通搜索只告诉「代码在哪」,CodeGraph 还告诉「改了可能影响哪」。这让 Agent 在改代码前能评估风险,是「安全改代码」的关键能力。

一、CodeGraph 索引的四类信息

CodeGraph 不是「代码搜索引擎」,它索引的是一个图谱的四类节点与边:


CodeGraph 的四类信息
  ① 符号:函数、类、变量、接口
     (代码的「实体」)
  ② 文件:组织结构、模块划分
     (符号住在哪里)
  ③ 调用关系:谁调用谁(calls)、谁被谁调用(called by)
     (符号间的边)
  ④ 影响路径:改某个符号,会影响哪些下游
     (调用关系的反向传播)

信息	回答的问题	例子
符号	「这个函数在哪定义?」	`authMiddleware` 在 auth.js
文件	「这个模块有哪些文件?」	auth/ 下有 5 个文件
调用关系	「谁调用了它?」(callers)	`authMiddleware` 被 12 处调用
影响路径	「改了它会影响谁?」	改它会波及登录、API、移动端

关键概念:前三个(符号/文件/调用)普通代码搜索多少也能做,但第四个「影响路径」是 CodeGraph 的独特价值——它需要把调用关系「反向传播」算出影响范围,这是图谱查询才能做到的。

二、影响路径:为什么这是 CodeGraph 的杀手锏

「影响路径」是 CodeGraph 区别于所有「文本式代码搜索」的根本差异。用一个真实场景说明:


没有影响路径(普通代码搜索)
  Agent 要改 authMiddleware
    → 搜一下它在哪 → 找到了 → 改?
    → 不知道改了会影响谁 → 盲改,可能引发故障

有影响路径(CodeGraph)
  Agent 要改 authMiddleware
    → 查影响路径 → 发现它被 12 处调用,波及:
        ├─ 登录流程(核心)
        ├─ API 网关(所有 API)
        └─ 移动端(第 1 章那个「鉴权不能动」的约束!)
    → 评估风险:影响面大,要谨慎/要测兼容/或不动

这就是为什么 CodeGraph 让 Agent「安全地改代码」——它把「改动的涟漪」可视化,Agent 改之前就知道影响范围。这与第 4 章 Chat Memory 里那条「别重构鉴权,移动端在用」的约束天然呼应:CodeGraph 用图谱证实了那条约束的影响范围。

💡 技巧:让 Agent 改代码前,养成「先查影响路径」的习惯。这一步能避免大量「改了引发连锁故障」的悲剧。CodeGraph 的价值在这一步体现得最充分——它把「不可见的依赖」变成「可见的影响图」。

三、callers 与 callees:双向查询

调用关系是双向的,CodeGraph 支持两个方向的查询:

查询	回答	用途
callers(谁调用我)	上游依赖	改之前评估影响
callees(我调用谁)	下游依赖	理解这个函数做了什么


双向查询的价值
  改 authMiddleware 前:
    查 callers → 知道影响哪些上游(改之前看)
    查 callees → 知道它依赖哪些下游(改的时候别破坏)
  
  → 双向合起来 = 完整的依赖上下文

这两个方向都重要——callers 告诉你「改它会影响谁」(改前评估),callees 告诉你「它依赖谁」(改时注意别破坏下游)。普通代码搜索往往只支持「找定义」单向,CodeGraph 的双向查询让 Agent 对代码有完整理解。

四、CodeGraph 的构建与同步

CodeGraph 的构建与 Wiki 类似,是异步的,且支持随源仓库变化增量更新:


CodeGraph 构建与同步
  喂代码仓库(HTTPS) → 触发 index 任务
    → 解析符号、建调用关系图
    → 状态:ready
    
  源仓库 push 新提交 → Auto-Sync 增量更新
    → 只重 index 变化的部分
    → 图谱保持新鲜

⚠️ 注意:CodeGraph 当前首先支持公开 HTTPS 仓库;私有仓库和 SSH 凭证接入仍在完善。这是第 1 章和第 5 章都提过的限制。如果你用私有仓库构建失败,先确认是不是这个限制,而不是配置错。

构建质量方面,CodeGraph 对「有类型信息」的语言(如 TypeScript、Java)构建质量通常更好——类型让调用关系更明确;对动态类型语言(如 JavaScript、Python)的调用关系推断可能不完全准确,需要结合静态分析与运行时信息。

五、CodeGraph 复用的开源基础

CodeGraph 模块复用了开源项目 codegraph 的代码,其「预索引的代码图谱」设计是该模块实现的基础。这意味着:


复用关系(概念)
  开源 codegraph 项目
    提供:预索引的代码图谱的 core 能力
    ↓
  本系统的 CodeGraph 模块
    在其基础上:适配记忆资产模型、对接 /v3/tools 调用、加 Auto-Sync
    
  → 不是从零造,是「站在肩膀上」做工程集成

这种「复用 + 集成」是工程上的常见做法——core 能力用成熟开源,外围做业务适配。理解这一点,你就不会误以为整个 CodeGraph 都是本系统从零写的——它的图谱核心来自开源,本系统做的是把它「记忆资产化」「按需调用化」。

本节要点回顾

四类信息:符号(实体)、文件(组织)、调用关系(边)、影响路径(反向传播)——前三个普通搜索能做,第四个是独特价值。
影响路径是杀手锏:让 Agent 改代码前知道影响范围——「安全改代码」的关键,与「鉴权不能动」类约束呼应。
双向查询:callers(上游,改前评估)+ callees(下游,改时注意),完整依赖上下文。
构建与同步:异步构建 + Auto-Sync 增量;当前优先支持公开 HTTPS 仓库;类型语言构建质量更好。
复用开源:图谱核心来自开源 codegraph,本系统做记忆资产化与按需调用化的集成。

Wiki 和 CodeGraph 都讲完了,下一节看它们如何被 Agent 使用——按需调用机制 /v3/tools/list 与 /v3/tools/call。