不花一分钱的代码智能分析：CodeGraph 入门

在 AI 编程工具里，"代码理解"一直是个奢侈功能。

Cursor 的代码索引需要闭源服务，GitHub Copilot 的代码搜索需要微软的云端索引。这些东西要么花钱，要么把代码传到别人服务器上。

Reasonix 内置的 CodeGraph 不一样——它在本地跑，用 tree-sitter 做语法解析，不调用任何 API，完全免费。

一、CodeGraph 能做什么？

简单说：让 AI 理解你的代码结构，而不只是读文件内容。

CodeGraph 提供了两类核心能力：

1. 符号查询（Symbols）

"这个文件中定义了哪些函数？"
"UserService 这个结构体有哪些方法？"
"constants.go 里导出了哪些变量？"

2. 调用关系（Callers / References）

"谁调用了这个函数？"
"这个接口有哪些实现？"
"这个变量在哪里被修改了？"

有 CodeGraph vs 没 CodeGraph

没 CodeGraph 时：

你：帮我看看谁调用了 CreateOrder 这个函数

AI：我搜一下……
    → grep "CreateOrder" internal/**/*.go
    （只能做文本匹配，如果函数名被拼接过就搜不到）
    （也分不清"调用"和"定义"）

有 CodeGraph 时：

你：帮我看看谁调用了 CreateOrder 这个函数

AI：我查一下调用关系……
    → codegraph_callers internal/service/order.go:42
    
    调用 CreateOrder 的位置有：
    1. internal/handler/order.go:88  → CreateOrderHandler（处理 HTTP 请求）
    2. internal/worker/queue.go:55   → ProcessOrderJob（异步任务）
    3. internal/test/order_test.go:120 → TestCreateOrder（单元测试）
    
    其中 handler 和 worker 是直接调用，
    test 文件中的调用来自测试用例。

区别就是"搜字符串"和"理解代码结构"的区别。

二、开启 CodeGraph

默认关闭。开启方式：

[codegraph]
enabled = true          # 开启
auto_install = true     # 自动下载运行时（约 10MB）

或者在 Chat 里通过 /mcp 面板开启。

首次开启时，Reasonix 会自动下载 CodeGraph 运行时（一次性的，约 10MB）。

你会在状态栏看到：

↓ 正在下载 CodeGraph 运行时（10MB）……
✓ CodeGraph 已就绪

之后 AI 就多了三个新工具：codegraph_symbols、codegraph_callers、codegraph_references。

三、实战场景

场景一：理解一个不熟悉的模块

你：我刚接手这个项目，帮我看看 payment 模块的结构

AI：好的，我用 CodeGraph 分析一下……

    → codegraph_symbols internal/payment/

📦 payment 模块结构

包：internal/payment

类型定义：
├── struct PaymentService         // 核心服务
│   ├── CreatePayment(orderID, amount)
│   ├── RefundPayment(paymentID)
│   ├── GetPaymentStatus(paymentID)
│   └── HandleWebhook(payload)
├── struct PaymentValidator       // 校验
│   ├── ValidateCard(number, cvv, expiry)
│   └── ValidateAmount(amount)
├── interface PaymentGateway      // 外部网关抽象
│   ├── Charge(amount, token)
│   └── Refund(transactionID)
└── enum PaymentStatus
    ├── pending
    ├── completed
    ├── failed
    └── refunded

全局变量：
├── paymentService  (*PaymentService)  // 单例
└── defaultTimeout  (time.Duration)    // 30s

这就是 CodeGraph 最常用的场景——新人接手项目时，快速了解模块结构。

不用逐文件打开看。一个命令，AI 帮你生成整个模块的"地图"。

场景二：重构前的调用链分析

你：我想重构 PaymentService.HandleWebhook，先看看谁调了它

AI：好的，我查一下调用链……

    → codegraph_callers internal/payment/service.go:88
    
    HandleWebhook 的调用者：
    1. internal/router.go:42  → POST /webhook（路由注册）
    2. internal/middleware/signature.go:55 → 签名验证后调用
    3. internal/worker/retry.go:30 → 失败重试时调用（异步）

    另外，HandleWebhook 内部调用了：
    - PaymentGateway.Charge()
    - PaymentValidator.ValidateAmount()
    - repository.SavePayment()

有了完整的调用链，你就能评估：

• 改这个函数会影响哪些调用方
• 要不要动接口签名
• 测试要覆盖哪些路径

场景三：找 bug 根源

你：用户在支付失败时看到报错 "invalid amount"，但我不知道哪里抛的

AI：让我查一下这个错误信息是在哪里定义的……

    → grep "invalid amount" internal/payment/
    （文本搜索找到字符串位置）
    
    找到 3 处引用：
    1. internal/payment/validator.go:22  → Validator 抛出的
    2. internal/payment/handler_test.go:55  → 测试用例中
    3. internal/payment/webhook_test.go:120  → 测试用例中
    
    再查一下谁调用了 ValidateAmount……
    → codegraph_callers internal/payment/validator.go:22
    
    调用链：router → handler → PaymentService.CreatePayment → ValidateAmount
    
    问题在 validator.go:22，当金额为 0 时触发。建议加上更具体的错误信息。

四、CodeGraph vs 传统搜索

五、高级用法

限制分析范围

如果你只想看某个子目录，而不是整个项目：

你：帮我看看 internal/handler/ 下有哪些 HTTP 路由

AI：→ codegraph_symbols internal/handler/

CodeGraph 只分析指定的目录，范围更小、速度更快。

结合 @ 引用使用

先引用一个文件，再做深度分析：

你：帮我看看 @internal/service/user.go 这个文件，然后查一下
    UserService 的所有调用者

AI：→ read_file internal/service/user.go
    → codegraph_callers internal/service/user.go:15 （UserService 定义的行号）

和 MCP 结合

如果接了 MCP 数据库插件，你可以：

你：帮我在数据库里查一下用户的订单，然后用 CodeGraph 看看
    订单相关的代码结构

AI：→ mcp__sqlite__query "SELECT * FROM orders LIMIT 5"
    → codegraph_symbols internal/order/

AI 同时理解"数据长什么样"和"代码怎么处理这些数据"。

六、性能说明

七、跟竞品的对比

写在最后

CodeGraph 为 Reasonix 补上了最后一块拼图。

回顾整个系列的三个篇章、12 篇文章，你应该已经看到了 Reasonix 的全貌：

入门篇：装好、配好、用起来（01-04）
  → 安装、模式、权限、配置

进阶篇：深入使用，效率翻倍（05-08）
  → MCP、斜杠命令、Skills、Plan Mode

高阶篇：高级特性，专业用法（09-12）
  → 双模型协同、桌面端、迁移、CodeGraph

从今天开始，你的终端里有了一个：

• 跟 Cursor 一样强大的 AI 编程代理
• 但成本只有 1/5
• 开源、MIT 协议
• 三层安全防护
• 可以无限扩展的 MCP 插件生态
• 完全离线的代码理解能力

整个系列到此全部完结，共 12 篇。

如果你是从第一篇一路读到这里的——谢谢你。这个系列从零开始，把一个近 2 万 Star 的开源项目掰开揉碎讲了一遍。

如果你只读了其中几篇——也没关系，每一篇都是独立的，可以随时翻看。

之后我还会持续关注 Reasonix 的更新，有新功能就继续写。 如果你对这个系列有什么建议，或者发现了什么我没写到的新功能，欢迎随时告诉我。

📌 最后留一个互动话题：这 12 篇里哪一篇对你帮助最大？还有什么 Reasonix 的话题我没写到你希望看到的？评论区告诉我。