跳至主要內容
cd /languages
  • 嵌入式腳本
  • 程式語言
  • AST 與符號支援

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

Maguyva 以 AST、符號和圖譜支援 Lua,讓 AI 代理在 Lua 程式碼中追蹤模組、冒號方法、元表類別和 require 鏈。

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 沒有介面,也沒有型別註解,因此介面實作和型別參照關係被標記為不適用。

下一步

透過快速入門連接儲存庫,然後在相容性頁面檢視支援矩陣。對於把 Lua 嵌入原生程式碼的引擎,也請閱讀 C 指南。

最適合的情境

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

代理工作流程

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

引擎細節

  • > 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.*` 或標準函式庫的呼叫,這些呼叫已從圖譜中過濾掉。