一、什么是 CodeGraph
CodeGraph 是一个开源的代码知识图谱 MCP 服务器（34k+ Stars），核心思路是：​提前把代码的符号关系建好索引​，让 AI 代理直接查询图谱，而不是每次从头扫描文件。

工作原理：

AI Agent (Reasonix Code)
│ codegraph_context / codegraph_trace / codegraph_explore
▼
CodeGraph MCP Server
│ SQLite 知识图谱（符号 + 边 + 全文索引）
▼
Tree-sitter 解析 AST → 提取函数/类/方法/调用/继承关系
│
▼
项目源代码（Java / Vue / JS / XML / YAML 等）
关键特性：

支持 20+ 语言（包括 Java、JavaScript、TypeScript、Vue 等）
完整的调用图（callers / callees / trace）
影响范围分析（impact）
文件监听自动同步（OS 原生事件，2 秒去抖）
100% 本地运行，无外部 API
二、安装步骤
2.1 全局安装

使用 npx 零安装（推荐）

npx @colbymchenry/codegraph
安装器会交互式选择要配置的 AI 客户端。目前支持：Claude Code、Cursor、Codex CLI、Gemini CLI、OpenCode、Hermes Agent 等。​Reasonix Code 不在自动配置列表中​，需手动注册。

2.2 在项目根目录创建索引
cd your-project
codegraph init -i
-i 参数表示初始化后立即建索引。执行后在项目根目录生成 .codegraph/ 目录，其中包含 SQLite 数据库（codegraph.db）。

2.3 在 Reasonix Code 中手动注册 MCP 服务
由于 Reasonix Code 未被自动配置工具识别，需要手动添加 MCP 服务配置。Reasonix Code 的 add_mcp_server 工具可以自动完成此操作：

{
“name”: “codegraph”,
“transport”: “stdio”,
“command”: “codegraph”,
“args”: [“serve”, “–mcp”]
}
注册成功后，重启 Reasonix Code 即可生效。可通过 codegraph_codegraph_status 工具验证索引状态。

三、CodeGraph 提供的工具集
CodeGraph 注册后暴露以下 MCP 工具：

工具名 用途 对标传统操作
codegraph_context 首要调用— 输入任务描述，返回入口点 + 相关符号 + 代码 相当于 search_content+read_file 组合
codegraph_trace 追踪两个符号之间的调用路径 需要手动逐层阅读代码推理
codegraph_explore 一次查询获取多个文件的源码（内联返回，行号精确） 单个 read_file× N
codegraph_search 按符号名快速搜索 search_files
codegraph_callers 列出调用某个函数的所有调用者 search_content 搜方法名
codegraph_callees 列出某个函数调用的所有子函数 逐行阅读代码
codegraph_impact 修改某个符号前分析影响范围 手动 grep + 推理
codegraph_node 获取单个符号的详细信息 read_file 定位
codegraph_files 展示项目文件树 directory_tree
codegraph_status 查看索引健康状态 —
四、实测对比方案
测试任务
追踪 PUT /system/colonelActivity/changeSyncProduct 接口的完整后端调用链路。

需要回答：

HTTP 请求从进入 Spring Boot 到最终响应，经过了哪些拦截器/过滤器？
Controller → Service → Mapper 的每一层调用了什么方法？
当 isSyncProduct=Y 时，RocketMQ 消息是如何被发出的？
涉及哪些异常/校验逻辑？
操作日志如何被记录？
衡量指标
工具调用次数
实际文件读取数
答案完整性与准确性
基线流程（未安装 CodeGraph）
阅读 SysColonelActivityController.java → 发现调用了 colonelActivityService.changeSyncProduct()
阅读 ISysColonelActivityService.java → 发现接口定义
阅读 SysColonelActivityServiceImpl.java → 理解业务逻辑、事务、校验、分支路径
发现调用 productSyncService.sendNonPendingActivityProductSyncMessage() → 阅读 DoudianColonelActivityProductSyncService.java
发现调用 mqProducer.sendAsyncMessage() → 阅读 MqProducer.java
查看 MqTopicConstant.java → 确认 Topic 名称
查看 SecurityConfig.java → 理解过滤器链
查看 JwtAuthenticationTokenFilter.java → JWT 认证流程
查看 PermissionService.java → @PreAuthorize 权限校验
查看 LogAspect.java → @Log 操作日志 AOP
查看 GlobalExceptionHandler.java → 异常处理
查看 BaseController.java → getUsername() / toAjax() 父类方法
查看 SysColonelActivityMapper.java → MyBatis-Plus Mapper
查看 ColonelActivitySyncProductUpdateParam.java → 参数校验注解
手动整合各层调用关系
CodeGraph 流程
codegraph_context — 输入任务描述，自动返回入口点 + 相关符号 + 代码片段（覆盖 3 个文件源码）
codegraph_trace(“changeSyncProduct”, “sendNonPendingActivityProductSyncMessage”) — 自动输出完整调用路径
codegraph_explore — 一次查询返回 8 个关键文件的完整源码（SecurityConfig、PermissionService、MqProducer、BaseController 等）
codegraph_explore — 另一次查询补充 LogAspect、GlobalExceptionHandler、SysColonelActivityServiceImpl、SysColonelActivityMapper
五、实测数据对比
指标 未安装 CodeGraph（基线） 已安装 CodeGraph 提升幅度
工具调用总数 16 次 5 次 ↓69%
read_file 调用 12 次 0 次 ↓100%
search_content 调用 1 次 0 次 ↓ 100%
search_files 调用 3 次 0 次 ↓ 100%
codegraph_* 调用 0 次 5 次 —
文件读取数 12 个 0 个（源码内联） ↓100%
调用链串联方式 手动逐层推理 trace 一键自动输出 🚀
答案完整性 覆盖 7 层 覆盖 7 层 持平 ✅
文件行号准确性 全部精确 全部精确 持平 ✅
核心体验差异

1. 零文件读取 — 从 12 次 read_file 降为 0
   基线时需要逐个文件打开阅读：

SysColonelActivityController.java → ISysColonelActivityService.java →
SysColonelActivityServiceImpl.java → DoudianColonelActivityProductSyncService.java →
MqProducer.java → SecurityConfig.java → JwtAuthenticationTokenFilter.java →
PermissionService.java → LogAspect.java → GlobalExceptionHandler.java →
BaseController.java → SysColonelActivityMapper.java
CodeGraph 通过 codegraph_explore 批量将源码内联到工具响应中，无需手动 read_file。

2. 调用链一键追踪
   基线时需手动推理每层的调用关系。codegraph_trace 一个调用自动输出：

changeSyncProduct (Controller:62)
↓ @71 calls
sendNonPendingActivityProductSyncMessage (Service:103)
↓ @105 calls
sendActivityProductSyncMessage (Service:120)
↓ @123 calls
MqProducer.sendAsyncMessage (MqProducer:58-81)
↓ calls
RocketMQTemplate.asyncSend(topic, message, callback)
→ Topic: “ruoyi-doudian-colonel-activity-product-sync-topic”
3. 调用关系一目了然
codegraph_context 自动列出 changeSyncProduct 调用的所有子方法路径，无需逐行扫描。

六、CodeGraph 完整的 7 层调用链路（测试答案）
第 1 层：Spring Security 过滤器链
SecurityConfig.filterChain() [SecurityConfig.java:97]
├─ CorsFilter (跨域) [line 162-163]
├─ JwtAuthenticationTokenFilter (JWT 认证) [JwtAuthenticationTokenFilter.java:31]
│ └─ TokenService.getLoginUser(request) → 解析 JWT Token
│ └─ TokenService.verifyToken(loginUser) → 刷新 Token 有效期
│ └─ 设置 SecurityContextHolder → 注入 LoginUser
└─ @PreAuthorize 拦截 [SecurityConfig.java:29 @EnableMethodSecurity]
第 2 层：权限校验
@PreAuthorize(“@ss.hasPermi(‘system:colonelActivity:edit’)”)
└─ PermissionService.hasPermi() [PermissionService.java:27]
└─ SecurityUtils.getLoginUser() → 从 SecurityContext 获取
└─ loginUser.getPermissions() → 获取用户权限集
└─ hasPermissions(permissions, permission) → 检查是否包含（含 ALL_PERMISSION 超级权限）
└─ 失败 → AccessDeniedException
└─ GlobalExceptionHandler.handleAccessDeniedException() → 403
第 3 层：参数校验
@Validated @RequestBody ColonelActivitySyncProductUpdateParam
activityRecordId: @NotNull(message = “活动记录ID不能为空”)
isSyncProduct: @NotBlank + @Pattern(regexp = “¹$”)
└─ 校验失败 → MethodArgumentNotValidException
└─ GlobalExceptionHandler.handleMethodArgumentNotValidException() → 返回错误信息
第 4 层：Controller 入口
SysColonelActivityController.changeSyncProduct() [Controller.java:62]
├─ @PreAuthorize(“@ss.hasPermi(‘system:colonelActivity:edit’)”)
├─ @Log(title = “团长活动管理”, businessType = BusinessType.UPDATE)
├─ @PutMapping(“/changeSyncProduct”)
├─ int rows = colonelActivityService.changeSyncProduct(param, getUsername())
├─ if (rows > 0 && YES.equals(param.getIsSyncProduct()))
│ └─ productSyncService.sendNonPendingActivityProductSyncMessage(activityRecordId)
└─ return toAjax(rows) → BaseController.toAjax() [BaseController.java:161]
第 5 层：Service 业务逻辑
SysColonelActivityServiceImpl.changeSyncProduct() [ServiceImpl.java:64]
├─ @Transactional(rollbackFor = Exception.class)
├─ requireActivity(activityRecordId) → 校验活动记录存在 + authId/activityId 非空
├─ assertSelfOwnedColonel(activity) → [Y 路径] 校验授权未过期 + 自有团长
│ └─ colonelAuthService.getById(authId)
├─ updateById(activity) → 写入 DB（update_time, update_by）
└─ [Y→N 转换路径] 清理关联数据：
├─ colonelActivityProductService.deleteByActivityRecordId()
├─ talentProductDetailService.deleteByActivityRecordId()
├─ productSkuService.clearProductSkus()
└─ pendingProductService.deleteByActivityRecordId()
第 6 层：RocketMQ 消息发送（Y 路径）
DoudianColonelActivityProductSyncService
└─ sendNonPendingActivityProductSyncMessage(id) [SyncService.java:103]
└─ sendActivityProductSyncMessage(id, NON_PENDING) [SyncService.java:120]
└─ mqProducer.sendAsyncMessage(topic, jsonMsg) [SyncService.java:123]
└─ MqProducer.sendAsyncMessage() [MqProducer.java:58]
└─ rocketMQTemplate.asyncSend(topic, message, callback)
└─ Topic: “ruoyi-doudian-colonel-activity-product-sync-topic”
第 7 层：操作日志（AOP 切面）
LogAspect [LogAspect.java]
├─ @Before: doBefore() → 记录开始时间 (ThreadLocal)
├─ @AfterReturning: doAfterReturning()
└─ handleLog() → 构建 SysOperLog
├─ 获取用户、IP、URL、方法名
├─ 读取 @Log 注解（title=团长活动管理, businessType=UPDATE）
├─ 序列化请求参数 / 返回值
└─ AsyncManager.me().execute(AsyncFactory.recordOper(operLog))
→ 异步写入数据库
七、经验总结
适合 CodeGraph 的场景
场景 效果
大项目（500+ 文件） 🚀 显著，节省 70%+ 工具调用
跨模块追踪调用链 🚀trace 比手动推理高效数倍
修改前的影响分析 🚀impact 自动输出影响半径
理解不熟悉的模块架构 🚀context 一次性给出全景
小的独立模块（50- 文件） ⚠️ 收益有限，当前工具已够用
首次建立索引（冷启动） ⚠️ 需要几分钟建索引时间
注意事项
​首次索引需要时间​：本项目 1,300 个文件索引约需 1-2 分钟
​文件变更后自动同步​：OS 文件监听有 2 秒去抖窗口，期间有脏读风险（CodeGraph 会显示 ⚠️ 横幅提醒）
​Reasonix 不在自动配置列表​：需手动通过 add_mcp_server 注册
​CodeGraph 与项目 .gitignore​：.codegraph/ 目录建议加入 .gitignore（避免提交数据库文件）
​工具调用次数不是唯一指标​：虽然从 16 次降到 5 次，但每次 codegraph_explore 返回的数据量更大
八、总结
CodeGraph 在本次实测中对 Reasonix Code 的代码探索效率有显著提升：

​工具调用减少 69%​，其中文件读取从 12 次降为 0 次
调用链追踪从手动推理变为一键输出
​代码覆盖面更广​（一次 explore 覆盖约 6 个文件的完整源码）
​答案质量完全持平甚至更优​（图谱结构确保不会遗漏关键路径）
对于星火甄选这样的中大型项目（1,300 文件、多模块依赖、跨语言），CodeGraph 的收益是明确的。

九、后续使用计划回答

1. 在后续使用 Reasonix 开发的过程中会自动使用 CodeGraph 吗？
   会，但策略性地使用。

具体来说：

​当遇到需要跨模块/跨文件追踪的问题时​（如"这个 Controller 的请求最终调用了哪个 Mapper 的什么方法"、“修改这个 Service 会影响哪些前端页面”），我会优先使用 codegraph_context 和 codegraph_trace，因为它们比手动 read_file 串联高效得多。
​当需要理解不熟悉的模块架构时​，我会用 codegraph_context 快速获取全景图，而不是先 grep 再逐个读文件。
​但在简单场景下​（如"某个类里有什么方法"、“某个文件的全部内容是什么”），直接使用 read_file 和 get_symbols 可能更直接，因为调用 codegraph_explore 有一次额外的索引查询开销。
​对于影响范围分析​（“如果修改 X 函数，哪些地方需要同步修改？”），codegraph_impact 将成为首选工具，因为它在人工推理中很容易遗漏间接调