# Maguyva 的 Ruby 支持：面向 Rails 与 Ruby 应用的代码图谱

Canonical source: https://maguyva.ai/zh-hans/languages/ruby

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Maguyva 以 AST、符号和图谱支持 Ruby，让 AI 智能体在 Rails 和 Ruby 代码库中追踪类、模块、单例方法和构造调用。

## 支持情况速览

- 支持等级: AST 和符号支持
- 编程语言
- 扩展名: .gemfile, .gemspec, .rake, .rakefile, .rb, .rbw
- 真正的 AST 解析，支撑语法感知搜索和结构化上下文。
- 命名符号支撑语义查找和交叉引用。启用关系提取后，即可使用图谱导航。
- 该语言为图谱感知搜索提供符号和关系；支持的边类型随其原生构造而异。
- 同时支持 AST 解析和符号提取。

## 最适合场景

- Rails 单体应用，模型、服务对象、作业和 concern 在许多目录之间相互调用。
- 拥有深层模块命名空间和共享基类的 gem 与 Ruby 服务。
- 在动到半个应用都依赖的模型或服务之前，想先用 AI 智能体划定修改范围的团队。

## 智能体工作流

- 在修改服务对象或模型方法的行为之前，找出它的所有调用方。
- 追踪某个类在哪里通过 `.new` 实例化，以及接下来运行了哪些方法。
- 在重构之前，梳理哪些类继承自某个基类或混入了某个模块。

## 为什么 Ruby 仓库让浅层 AI 工具犯难

Ruby 高度依赖约定和元编程。方法由 `attr_accessor` 生成，类会在其他文件中被重新打开，命名空间嵌套好几层模块。可读的表面掩盖了一次调用实际到达的是哪个方法，而粗糙的文本搜索会返回应用里所有的 `call` 和 `perform`。

Maguyva 把类、模块、方法及其调用方作为结构交给智能体，让它沿着应用追踪一次修改，而不是靠猜。

## Maguyva 在 Ruby 中提取什么

Maguyva 覆盖 `.rb`、`.rbw`、`.rake` 和 `.gemspec` 文件，以及 `Gemfile` 和 `Rakefile`。实例方法和单例方法（`def self.call`）都会被提取，单例方法会标记为 static。`attr_reader`、`attr_writer` 和 `attr_accessor` 声明计为访问器方法，符号会以其模块和类命名空间限定。

`ClassName.new` 和 `Namespace::ClassName.new` 计为实例化，接收者类型推断会跟踪局部赋值和 `@instance_variables`，因此对已赋值对象的调用可以解析到它的类。图谱还记录继承、模块包含、重写、`raise` 和 `rescue` 边以及读写。

元编程调用（`define_method`、`send`、`method_missing`、`class_eval` 等）、Sorbet 的 `T::` 类型辅助工具，以及常见的可枚举调用（`each`、`collect`、`reject` 等）会从关系中过滤掉，让应用代码更加突出。

## 智能体提示词示例

- “谁调用了 `Billing::ChargeCustomer.call`，来自哪些作业和控制器？”（先用 `find_symbol`，再用 `dependency_search` 的 incoming 方向）
- “哪些模型继承自 `ApplicationRecord` 并包含了 `Auditable`？”（`dependency_search`）
- “追踪订单被标记为已支付之后会发生什么。”（`get_task_context`）

## 已知限制

- 在 Ruby 中，`require` 和 `load` 是普通的方法调用，因此 `structural_search` 中的 `imports` 预设不会选中任何内容。要列出它们，请使用 `text_pattern_search`。
- 通过 `define_method` 在运行时创建、或由 `method_missing` 处理的方法不会被提取为符号，这些调用也会作为元编程噪声被过滤。
- Ruby 没有装饰器语法，因此装饰器关系被标记为不适用。

## 后续步骤

通过[快速入门](/zh-hans/docs/quickstart)连接仓库，然后在[兼容性页面](/zh-hans/docs/compatibility)查看支持矩阵。其他动态语言仓库请对照阅读 [Python 指南](/zh-hans/languages/python)。

## 引擎细节

- Ruby 支持覆盖 `.rb`、`.rbw`、`.rake`、`.gemspec`、`Gemfile` 和 `Rakefile`。单例方法标记为 static，`attr_*` 声明计为访问器方法。
- `ClassName.new` 计为实例化，接收者类型推断会跟踪局部赋值和实例变量。
- `define_method`、`send` 等元编程调用、Sorbet 的 `T::` 辅助工具以及常见的可枚举调用会从关系中过滤掉。

## 常用 MCP 入口工具

- `find_symbol`: 用于查找带命名空间的类、模块或方法，例如 `Billing::ChargeCustomer.call`。
- `dependency_search`: 修改之前，对模型或服务对象使用 incoming 遍历，查看调用方和子类。
- `text_pattern_search`: 用于查找 `require` 路径、路由字符串以及图谱看不到的动态定义方法。