# Maguyva 的 Lua 支持：面向游戏、插件与 OpenResty 的代码图谱

Canonical source: https://maguyva.ai/zh-hans/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-hans/docs/quickstart)连接仓库，然后在[兼容性页面](/zh-hans/docs/compatibility)查看支持矩阵。对于把 Lua 嵌入原生代码的引擎，也请阅读 [C 指南](/zh-hans/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.*` 或标准库的调用，这些调用已从图谱中过滤掉。