b3sty-skill

b3sty 技能

在处理 b3sty RedM/FiveM 资源或相关 Lua 代码时使用此技能。以下默认规则适用于高频任务；只有任务涉及相应内容时，才打开参考文件。

工作流程

1. 编辑前先确定目标：RedM、FiveM 或共享；客户端、服务器、NUI、数据库或跨资源；资源名称；框架/依赖假设。
2. 先检查本地项目，并遵循其现有模式，除非这些模式与以下规则冲突。
3. 仅加载此技能中的相关参考文件。进行广泛审查时，先检查有改动的部分，再打开下方列出的匹配文件。
4. 将公共服务器事件、回调、命令、导出、NUI 回调和资源间调用视为不可信边界。
5. 对不确定的原生函数行为，在依赖这些行为前，先根据相应原生函数参考核实名称、哈希值、签名和游戏特定行为。
6. 最后进行具体验证：资源启动/加载顺序、事件名称、服务器验证、清理路径、性能热点以及任何手动复现步骤。
7. 在正确的 memory/ 命名空间中记录反复出现的修复或新近验证的引擎特性，并注明日期和游戏构建版本。

任务路由

• 清单、加载顺序、依赖列表、UI 文件或资源布局发生变化时，从 skills/common/fxserver.md 开始。
• 涉及任何服务器事件、回调、命令、导出、NUI 回调、状态同步、数据库变更、奖励、物品、金钱、权限、冷却时间或高频循环时，从 skills/common/security-performance.md 开始。
• 对商店、库存、给予物品和经济事件进行加固、反作弊、管理员/ACE 权限控制、机密信息、SQL 注入、给予物品检查清单、SetHttpHandler 端点、加固 convar 和第三方资源审查时，添加 skills/common/security-performance.md -> Event Trust Boundary、Give-Value Event Hardening、ACE Permissions、Built-in Client Events、Config/Convars/Secrets、Identifier Trust，以及 Server Hardening And Operations。
• 功能会创建联网实体、依赖实体所有权、使用 routing bucket/实例、向客户端广播、响应玩家作用范围变化，或处理内置客户端事件（weaponDamageEvent、startProjectileEvent、ptFxEvent 等）时，添加 skills/common/networking.md。
• 资源包含游戏内浏览器 UI（HTML/CSS/JS、React/Svelte/Vue）、SendNUIMessage、RegisterNUICallback、SetNuiFocus，或清单中有 ui_page 时，添加 skills/common/nui.md。
• 涉及线程/等待、source 变量、导出和过期引用、标识符、convar、资源生命周期、让出执行的风险或游戏版本限制时，添加 skills/common/runtime.md。
• 涉及 SQL、OxMySQL/mysql-async、架构、事务、迁移、脏数据保存或持久化状态时，添加 skills/common/database.md。
• 代码调用原生函数、处理实体、武器、弹药、载具、马匹、行人、blip、道具或 routing bucket 时，添加 skills/common/native-rules.md 和对应的游戏规则。
• 将原生函数参考条目转换为 Lua 调用、通过 Citizen.InvokeNative 使用哈希调用、处理输出指针参数、打包 RDR3 结构体参数，或按游戏版本限制原生函数时，添加 skills/common/native-usage.md。
• 仅在需要核实特定原生函数名称、哈希、命名空间、签名、参数行为或游戏差异时，搜索对应的原生函数参考。
• 任务涉及诊断、复现、跟踪记录、NUI 错误、数据库故障、原生函数错误或性能调查时，添加 skills/common/debugging.md 和相关的 memory/ 文件。
• 仅当资源已使用 ox_lib，或用户明确同意添加时，才添加 skills/common/ox-lib.md。
• 功能通过导出、事件、回调、依赖、共享脚本、convar、状态袋或框架集成跨越多个资源时，添加 skills/common/multi-resource.md。
• 资源特定于某款游戏，或共享行为可能存在差异时，添加 skills/fivem/rules.md 或 skills/redm/rules.md。
• 编辑此技能包后、发布前，运行 scripts/validate_b3sty_skill.py。

审查优先级

• 先检查服务器权威性，再检查风格。
• 先检查公共输入边界，再检查内部辅助函数。
• 添加缓存、计时器、回调、实体、区域或状态前，先检查清理逻辑和生命周期。
• 将代码移入共享文件前，先检查 RedM/FiveM 可移植性。
• 保持修复局部且直接，除非重复使用确有必要，否则不要添加辅助函数或更新参考资料。

核心默认规范

除非任务另有说明，否则每个 b3sty Lua 任务都应遵循以下规范。

风格

• 优先使用直接、易读的代码，避免过度抽象。小型资源不要使用框架、分发器或类系统。
• 使用 4 个空格缩进。调用、参数和表格中的逗号后加空格。
• 将硬编码值直接写在代码中（模型名称、位置、事件名称）没有问题，只要这样能让值更贴近相关逻辑、更加清晰。
• 对只用一次的值，不要创建辅助函数或临时局部变量；硬编码值能让流程更易读时，就直接内联。
• 仅当局部变量会被重复使用、计算开销较大、需要验证，或比内联表达式更清晰时，才为其命名。
• 控制器模式：使用一个局部表，并采用 function Controller:Method() ... end 的形式。

事件

• 每个自定义事件都使用 resource_name:server:action 或 resource_name:client:action。
• 服务端是金钱、物品、职业、权限、所有权、奖励、冷却时间和已保存状态的唯一可信来源。
• 将公开的服务端事件、回调、命令和导出视为不可信输入；在服务端验证载荷和权限。
• 在每个服务端处理程序的顶部、任何让出执行权之前，捕获 local source = source；之后重新验证。完整机制见 skills/common/runtime.md。
• 内置客户端事件（weaponDamageEvent、startProjectileEvent、ptFxEvent 等）可由客户端调用；像验证任何 :server: 事件一样验证它们。完整列表见 skills/common/networking.md。

CfxLua

• 在 RedM/FiveM 代码中，如果能让代码更清晰，可以使用受支持的复合运算符（+=、-=、*=、/=、<<=、>>=、&=、|=、^=）。不要使用 ++/--。
• 这些运算符仅适用于 CfxLua——标准 Lua 或独立 Lua 工具中绝不能使用。

原生函数

• 文档中的 GET_ENTITY_HEALTH 对应 Lua 全局函数 GetEntityHealth；去掉名称开头的下划线；仅有哈希值的原生函数使用 Citizen.InvokeNative(hash, ...)，并添加 --[[NAME]] 注释。
• Citizen.InvokeNative 的 BOOL 结果为 1/0，而 Lua 会将 0 视为真值——使用 == 1 进行比较，绝不要在 if 中直接使用原始结果。
• 哈希调用中的浮点参数必须是浮点子类型的数字——写作 1.0，对计算得出的值使用 + 0.0 进行强制转换。
• 哈希常量优先使用反引号字面量或 joaat；哈希应与哈希比较，绝不要与十六进制字符串比较。
• 完整机制（输出参数、封送、RDR3 结构体、构建版本、置信度）见 skills/common/native-usage.md。

配置

• 小型／共享配置放在 config.lua 中；大型数据集拆分到 configs/*.lua，每个文件都返回一个表。
• 仅在使用拆分配置的脚本中引入该配置；不要使用预先加载的聚合器。

NUI

• NUI 是客户端本地的 UX，不具备权威性。将 RegisterNUICallback 载荷视为不可信，并通过经过验证的 :server: 事件转发有价值的操作。
• 将其他玩家可以影响的任何字符串（名称、聊天内容、标签）渲染为文本——绝不要通过 innerHTML/{@html}/v-html 渲染。在 CEF 中发生 XSS，攻击者就能以受害者身份触发每个 NUI 回调。
• 在 UI 关闭、玩家离开和资源停止时清除 NUI 焦点（SetNuiFocus(false, false)）；每个回调的 cb 只调用一次。
• 完整桥接机制（manifest、SendNUIMessage、fetch helper、焦点、契约）见 skills/common/nui.md。

网络

• 在信任客户端提供的实体句柄和网络 ID 前，先验证其是否存在、类型、模型、所有者、路由桶和距离。
• 避免使用 TriggerClientEvent(name, -1) 广播；将范围限制为单个玩家或少量接收者，并优先使用状态袋复制可见状态。
• 完整 OneSync 机制（所有权、路由桶、范围、内置客户端事件）见 skills/common/networking.md。

性能与清理

• 从服务端拥有的状态在本地渲染装饰性／附着／预览道具；仅对共享的游戏实体使用网络道具。
• 将高频查找缓存到局部变量中；为重复搜索构建反向索引（Items["INDEX"][name]）。
• 除非需要逐帧工作，否则不要使用 Wait(0)；根据距离／活跃状态分阶段等待。
• 避免在加载时缓存可能因提供方资源重启而过时的导出结果。完整机制见 skills/common/runtime.md。
• 在玩家离开／资源停止时清理实体、地图标记、区域、计时器、回调、限流器和缓存。清理实体前先检查 DoesEntityExist。

参考文件

根据任务需要再打开；不要预先加载全部文件。

通用

• skills/common/style.md - 完整的风格、格式和 CfxLua 规则。
• skills/common/fxserver.md - 编辑 fxmanifest.lua 或资源布局时参考。
• skills/common/native-rules.md - 调用原生函数、处理实体／弹药或调试原生函数行为时参考。
• skills/common/native-usage.md - 将原生函数参考条目转换为 Lua 调用时参考：名称转换、Citizen.InvokeNative、结果／指针封送、RDR3 结构体原生函数、构建版本门槛、置信度策略。
• skills/common/resource-structure.md - 共享的客户端／服务端／配置／事件／状态结构。
• skills/common/networking.md - OneSync、网络 ID 与句柄、实体所有权、路由桶、范围内消息与广播消息、玩家范围、实体生命周期事件，以及内置客户端事件（weaponDamageEvent 等）。
• skills/common/nui.md - 游戏内浏览器 UI（NUI）：Lua<->浏览器桥接、SendNUIMessage、RegisterNUICallback、焦点、JSON 契约、验证、前端规范、性能和安全性。
• skills/common/runtime.md - 线程／等待、source 变量、导出和过时引用、标识符、convar、资源生命周期、让出执行的风险，以及游戏构建版本。
• skills/common/security-performance.md - 编写 :server: 事件、回调、同步、数据库写入或高频循环时参考。
• skills/common/database.md - 编写 SQL、使用 OxMySQL/mysql-async 持久化、迁移、事务或保存状态时参考。
• skills/common/debugging.md - 诊断资源故障、追踪信息、客户端／服务端／NUI 问题、数据库问题、加载顺序或性能错误时参考。
• skills/common/ox-lib.md - 资源已使用 ox_lib，或任务明确接受添加 ox_lib 时参考。
• skills/common/multi-resource.md - 资源通过导出、事件、回调、依赖项、状态包或共享库进行通信时参考。

游戏专属

• skills/fivem/rules.md - FiveM 专属默认规则、清单、GTA V 实体和兼容性检查。
• skills/redm/rules.md - RedM 专属默认规则、清单、RDR3 实体和兼容性检查。

原生函数参考

这些是大型生成式查找文件。验证原生函数名称、哈希值、签名、命名空间、参数行为或游戏专属原生函数差异时，只打开对应的文件。

• references/natives/fivem-gta5-natives.md - GTA V / FiveM 原生函数参考。
• references/natives/redm-rdr3-natives.md - RDR3 / RedM 原生函数参考。
• references/server.cfg.example - 可复制的服务器加固基线（设置或审查 server.cfg 时打开）。

记忆

仅在调试或复用已掌握的模式时阅读。记忆文件记录了从实际工作中学到的事实（每条记录都附有日期和游戏构建版本）。它们会交叉引用 skills/ 中的稳定规则，不会重复规则文本。

通用

• memory/common/native-bugs.md - 已知的通用原生函数问题和解决方法。
• memory/common/common-errors.md - 反复出现的通用 Lua／资源错误及其修复方法。
• memory/common/cfx-patterns.md - 可复用的通用 FXServer/CfxLua 实现模式（控制器、索引映射、清理、配置拆分、持久化）。
• memory/common/security-performance.md - 总结的通用安全／性能模式和速查清单。

游戏专属

• memory/fivem/README.md - FiveM 专属记忆命名空间。
• memory/fivem/native-bugs.md - FiveM 专属原生函数问题和解决方法。
• memory/redm/README.md - RedM 专属记忆命名空间。
• memory/redm/native-bugs.md - RedM 专属原生函数问题和解决方法（例如 SetPedAmmoByType 储备弹药）。