用途
Luau 专家技能用于在编写、审查或修复 Luau 代码时提供一致的语言层规范。它聚焦 Luau 语言本身,涵盖 ModuleScripts、ServerScripts、LocalScripts 的写法,不处理 Roblox 引擎 API(如 RemoteEvent、DataStore、Instance、服务等交由 roblox-dev 技能)。
主要能力
严格类型化
新增文件默认使用 --!strict,标记任何可能在运行时失败的地方。存量代码逐步迁移,绝不削弱曾经严格的文件。项目级可通过 .luaurc 配置 { "languageMode": "strict" }。
现代语法
推荐使用字符串插值 Player {name}、if-then-else 表达式、广义迭代 for k, v in t 替代 pairs/ipairs、复合赋值 count += 1、continue 提前跳过、整除 //、const 绑定、数字分隔符 1_000_000、函数属性 @native。仅在需要对稀疏数组实现遇到首个 nil 即停止的语义时才使用 ipairs。
类型系统要点
可选类型 T?、标签联合(推荐用于结果类型)、索引映射在键可能缺失时使用 { [K]: V? } 以强制处理 nil、可选参数类型在外层加 ?、不可信输入使用 unknown 并在使用前收窄、尽量避免 any。
惯用写法
守卫子句优先于金字塔嵌套;显式写出 nil 检查而非含糊的真值判断;用 or 提供默认值,绝不用 and/or 模拟三元(中间值为假时会出错);不隐藏内置函数;不用调用糖 call "x";会挂起的函数加 Async 后缀;pcall 方法简写需用匿名函数包裹。
模块与不可变
始终赋值并返回具名局部变量,不用匿名函数直接返回;table.freeze 冻结导出表;不可变更新时只克隆被修改的路径,不做深拷贝;循环依赖可临时 cast 为 any 打破并注释原因;require 保持一个字母序代码块,不做动态 require。
OOP 取舍
优先纯数据加自由函数,避免元表与类型检查器冲突;除 __index、__tostring 与罕见的 __mode 弱表外避免一切元方法,不使用 __call、__add 或运算符重载。
字符串枚举与穷尽匹配
仅使用字符串联合类型定义枚举,配合 exhaustiveMatch 助手在遗漏分支时产生类型错误,不引入 makeEnum 之类库或冗余包装。
断言规范
始终提供错误信息且为常量字符串;需要格式化时改用 if not cond then error(...) end;不要用 assert(typeof(x) == ...) 来修补类型,应修复上游类型。在信任边界(RemoteEvents、JSON、插件输入)把入参类型标为 unknown 再收窄。
验证规则
不假设 Lua API 在 Luau 中存在:setfenv / getfenv 已移除,全局 unpack 移至 table.unpack,loadstring 已移除,bit32 存在但可考虑原生位运算符,不支持 goto / 标签。不确定某特性是否存在或稳定时应查阅 luau.org 并说明不确定性,不臆造语法。
反模式对照
提供完整对照表,例如 pairs(t)/ipairs(t) 对应 for k, v in t;string.format 对应插值字符串;a and b or c 对应 if-then-else;含糊真值判断对应显式 ~= nil;隐藏内置对应内联调用;可重赋值常量对应 const;全局变量对应局部或 const;any 对应 unknown 加收窄;用 assert 修补类型对应修复上游类型;索引映射用 { [K]: V } 对应 { [K]: V? };T? 函数裸 return 对应显式 return nil;动态 require 对应静态 require;分节 require 对应单一字母序块;挂起函数缺 Async 后缀对应补后缀;__call/__add 元方法对应普通函数;匿名模块返回对应具名局部;TableUtil 大模块对应单函数单文件;深拷贝对应路径克隆;math.floor(a/b) 对应 a // b;修改模块表对应 table.freeze 返回;金字塔嵌套对应早返回与 continue。
集成政策
技能描述的是首选模式,不授权重写既有代码。规则仅应用于新代码和用户明确要求重构的代码。应用默认规则前先匹配代码库既有风格(大小写、缩进、引号、模块形态)。不削弱更严格的文件,不引入项目未使用的工具,冲突只提示一次并默认沿用既有模式。
使用方式
随附参考资料包括 references/type-system.md(类型系统深入)、references/typed-class-recipe.md(setmetatable + __index 类模式)、references/type-functions-api.md(分析期类型库)、references/type-patterns.md(品牌类型、递归类型、重载、只读表)。示例文件包括 examples/good.luau、examples/bad.luau、examples/exhaustive-match.luau、examples/remote-validation.luau、examples/module-pattern.luau。
适用场景
适用于编写、审查或修复 Luau 代码的语言层工作,包括类型标注、语法现代化、模块组织、惯用法校正。
限制
不涉及 Roblox 引擎 API,相关主题应转交 roblox-dev 技能。具体安装命令与收费方式暂未提供。