# Maguyva 的 Lua 支援：面向遊戲、外掛與 OpenResty 的程式碼圖譜

Canonical source: https://maguyva.ai/zh-hant/languages/lua

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、符號和圖譜支援 Lua，讓 AI 代理在 Lua 程式碼中追蹤模組、冒號方法、元表類別和 require 鏈。

## 支援概況

- 等級: AST 與符號支援
- 程式語言
- 副檔名: .lua
- 真正的 AST 剖析，支援語法感知搜尋與結構化情境。
- 具名符號支援語意查詢與交叉參照。啟用關係擷取後，即可使用圖譜導覽。
- 這個語言會為圖譜感知搜尋提供符號與關係；支援的邊類型會隨其原生構造而異。
- 同時支援 AST 剖析與符號擷取。

## 最適合的情境

- 模組、基於表的類別和事件處理器相互呼叫的遊戲程式碼與引擎腳本。
- 拆分在大量被 require 的模組中的 Neovim 外掛和編輯器設定。
- 請求處理器與共享輔助模組並排存放的 OpenResty 及其他嵌入式 Lua。

## 代理工作流程

- 在修改模組函式的參數之前，找到它的所有呼叫端。
- 在移動共享輔助模組之前，追蹤哪些模組 require 了它。
- 梳理哪些表透過 `setmetatable` 繼承了某個基底類別。

## Lua 讓淺層 AI 工具栽跟頭的地方

Lua 沒有宣告類別的關鍵字。物件就是表，方法是存放在表裡的函式，繼承則是一次 `setmetatable` 呼叫。模組就是 `require` 回傳的任何東西。結構確實存在，但它藏在文字搜尋無法理解的約定裡。

Maguyva 把這些約定讀成結構，所以代理詢問誰呼叫了某個方法、哪些表擴充了某個基底類別時，能得到直接的答案。

## Maguyva 在 Lua 中擷取什麼

Maguyva 支援 `.lua` 檔案。函式宣告、`local function` 定義和函式表示式都會被擷取，`function Account:deposit()` 這樣的冒號方法會歸屬到其所屬的表 `Account`。方法鏈會逐個呼叫地追蹤，對 `self` 的呼叫始終繫結到外層物件。

Lua 的約定會這樣對應為關係：

- `require`、`dofile` 和 `loadfile` 記錄匯入。
- 模組級的 `setmetatable` 呼叫記錄繼承。
- `ClassName:new()`、`ClassName.new()` 和 `setmetatable({...}, ClassName)` 計為實例化。
- `error()` 記錄拋出，`pcall` 和 `xpcall` 記錄捕捉。

圖譜還會記錄讀寫和控制流。

## 代理提示範例

- 「誰呼叫了 `Inventory:addItem`，來自哪些腳本？」（先用 `find_symbol`，再用 `dependency_search` 的 incoming 方向）
- 「哪些模組 require 了 `util.http`？」（`dependency_search`）
- 「追蹤玩家受到傷害時會發生什麼。」（`get_task_context`）

## 已知限制

- 約 150 個名稱會從關係中過濾掉：Lua 標準函式庫（`string`、`table`、`math`、`io`、`os`、`coroutine`、`debug` 和 `utf8`），以及 Neovim 的 `vim.*` 和 OpenResty 的 `ngx.*` API。對這些 API 的呼叫不是圖譜的邊，查詢它們請使用 `text_pattern_search`。
- 由於模組和類別是用普通呼叫和表搭建的，`structural_search` 中的 `classes` 和 `imports` 預設集對 Lua 什麼也選不到。請改用 `find_symbol` 或 `text_pattern_search`。
- Lua 沒有介面，也沒有型別註解，因此介面實作和型別參照關係被標記為不適用。

## 下一步

透過[快速入門](/zh-hant/docs/quickstart)連接儲存庫，然後在[相容性頁面](/zh-hant/docs/compatibility)檢視支援矩陣。對於把 Lua 嵌入原生程式碼的引擎，也請閱讀 [C 指南](/zh-hant/languages/c)。

## 引擎細節

- Lua 支援涵蓋 `.lua`。`function Account:deposit()` 這樣的冒號方法會歸屬到其所屬的表。
- `require`、`dofile` 和 `loadfile` 記錄匯入，模組級的 `setmetatable` 記錄繼承，`ClassName:new()` 計為實例化。
- `error()` 記錄拋出，`pcall` 記錄捕捉，約 150 個標準函式庫、`vim.*` 和 `ngx.*` 名稱會被過濾掉。

## 實用的 MCP 進入點

- `find_symbol`: 需要模組函式或冒號方法的定義和呼叫端時使用它。
- `dependency_search`: 移動共享模組之前，使用 incoming 方向走訪，檢視哪些檔案 require 了它。
- `text_pattern_search`: 用於查詢對 `vim.*`、`ngx.*` 或標準函式庫的呼叫，這些呼叫已從圖譜中過濾掉。