# Maguyva 對 Ruby 的支援：Rails 與 Ruby 應用程式的程式碼圖譜

Canonical source: https://maguyva.ai/zh-hant/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 單體應用程式，model、service object、job 與 concern 在許多目錄之間彼此呼叫。
- 具有深層模組命名空間與共用基底類別的 gem 與 Ruby 服務。
- 在動到半個應用程式都依賴的 model 或服務之前，想先用 AI 代理界定修改範圍的團隊。

## 代理工作流程

- 在變更 service object 或 model 方法的行為之前，找出它的所有呼叫端。
- 追蹤某個類別在哪裡以 `.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::` 型別輔助工具，以及常見的 Enumerable 呼叫（`each`、`collect`、`reject` 等）會從關係中過濾掉，讓應用程式碼更加突出。

## 代理提示範例

- 「誰呼叫了 `Billing::ChargeCustomer.call`，來自哪些 job 與 controller？」（先用 `find_symbol`，再用 `dependency_search` 的 incoming 方向）
- 「哪些 model 繼承自 `ApplicationRecord` 並引入了 `Auditable`？」（`dependency_search`）
- 「追蹤訂單被標記為已付款之後會發生什麼事。」（`get_task_context`）

## 已知限制

- 在 Ruby 中，`require` 與 `load` 是一般的方法呼叫，因此 `structural_search` 中的 `imports` 預設不會選取任何內容。要列出它們，請使用 `text_pattern_search`。
- 透過 `define_method` 在執行階段建立、或由 `method_missing` 處理的方法不會被擷取為符號，這些呼叫也會被視為後設程式設計雜訊而過濾掉。
- Ruby 沒有裝飾器語法，因此裝飾器關係被標記為不適用。

## 下一步

透過[快速入門](/zh-hant/docs/quickstart)連接儲存庫，然後在[相容性頁面](/zh-hant/docs/compatibility)查看支援矩陣。其他動態語言的儲存庫，請對照閱讀 [Python 指南](/zh-hant/languages/python)。

## 引擎細節

- Ruby 支援涵蓋 `.rb`、`.rbw`、`.rake`、`.gemspec`、`Gemfile` 與 `Rakefile`。單例方法會標記為 static，`attr_*` 宣告會視為存取器方法。
- `ClassName.new` 視為實例化，接收者型別推斷會追蹤區域指派與實例變數。
- `define_method`、`send` 等後設程式設計呼叫、Sorbet 的 `T::` 輔助工具，以及常見的 Enumerable 呼叫會從關係中過濾掉。

## 實用的 MCP 進入點

- `find_symbol`: 用於查找帶命名空間的類別、模組或方法，例如 `Billing::ChargeCustomer.call`。
- `dependency_search`: 變更之前，對 model 或 service object 使用 incoming 走訪，查看呼叫端與子類別。
- `text_pattern_search`: 用於查找 `require` 路徑、路由字串，以及圖譜看不到的動態定義方法。