如何在Reaonix中使用CodeGraph以及CodeGraph效果实测经验分享

如何在 Reasonix 中使用 CodeGraph 以及 CodeGraph 效果实测经验分享

实测日期：2026-05-31
项目：星火甄选系统（基于 RuoYi-Vue 二次开发，~1,300 个源文件）
AI 客户端：Reasonix Code

---

一、什么是 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 接口的完整后端调用链路。

需要回答：

1. HTTP 请求从进入 Spring Boot 到最终响应，经过了哪些拦截器/过滤器？
2. Controller → Service → Mapper 的每一层调用了什么方法？
3. 当 isSyncProduct=Y 时，RocketMQ 消息是如何被发出的？
4. 涉及哪些异常/校验逻辑？
5. 操作日志如何被记录？

衡量指标

• 工具调用次数
• 实际文件读取数
• 答案完整性与准确性

基线流程（未安装 CodeGraph）

1. 阅读 SysColonelActivityController.java → 发现调用了 colonelActivityService.changeSyncProduct()
2. 阅读 ISysColonelActivityService.java → 发现接口定义
3. 阅读 SysColonelActivityServiceImpl.java → 理解业务逻辑、事务、校验、分支路径
4. 发现调用 productSyncService.sendNonPendingActivityProductSyncMessage() → 阅读 DoudianColonelActivityProductSyncService.java
5. 发现调用 mqProducer.sendAsyncMessage() → 阅读 MqProducer.java
6. 查看 MqTopicConstant.java → 确认 Topic 名称
7. 查看 SecurityConfig.java → 理解过滤器链
8. 查看 JwtAuthenticationTokenFilter.java → JWT 认证流程
9. 查看 PermissionService.java → @PreAuthorize 权限校验
10. 查看 LogAspect.java → @Log 操作日志 AOP
11. 查看 GlobalExceptionHandler.java → 异常处理
12. 查看 BaseController.java → getUsername() / toAjax() 父类方法
13. 查看 SysColonelActivityMapper.java → MyBatis-Plus Mapper
14. 查看 ColonelActivitySyncProductUpdateParam.java → 参数校验注解
15. 手动整合各层调用关系

CodeGraph 流程

1. codegraph_context — 输入任务描述，自动返回入口点 + 相关符号 + 代码片段（覆盖 3 个文件源码）
2. codegraph_trace("changeSyncProduct", "sendNonPendingActivityProductSyncMessage") — 自动输出完整调用路径
3. codegraph_explore — 一次查询返回 8 个关键文件的完整源码（SecurityConfig、PermissionService、MqProducer、BaseController 等）
4. 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 ColonelActivitySyncProductUpdateParamactivityRecordId: @NotNull(message = "活动记录ID不能为空")isSyncProduct: @NotBlank + @Pattern(regexp = "^[YN]$")└─ 校验失败 → 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. ​首次索引需要时间​：本项目 1,300 个文件索引约需 1-2 分钟
2. ​文件变更后自动同步​：OS 文件监听有 2 秒去抖窗口，期间有脏读风险（CodeGraph 会显示 ⚠️ 横幅提醒）
3. ​Reasonix 不在自动配置列表​：需手动通过 add_mcp_server 注册
4. ​CodeGraph 与项目 .gitignore​：.codegraph/ 目录建议加入 .gitignore（避免提交数据库文件）
5. ​工具调用次数不是唯一指标​：虽然从 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 将成为首选工具，因为它在人工推理中很容易遗漏间接调用者。

总的来说，CodeGraph 不会完全替代现有的文件读写工具，但在需要理解代码关系和调用结构的场景下，它会成为工作的主力工具。