roblox-best-practices-skill

# Roblox 最佳实践技能 一种为 AI 编码助手提供 Roblox 和 Luau 开发工作标准的代理技能。它涵盖了每个脚本的编写方式、系统的组装方式以及平台的实际限制，而不假设任何关于框架、文件夹布局或游戏类型的特定信息。 与 Claude Code、Cursor、Codex、Gemini、Windsurf、Cline、Zed 等任何其他读取 [Agent Skills](https://agentskills.io) 标准的工具配合使用。 --- ## 为您的代理提供的内容 **实施蓝图，而不仅仅是规则。** 针对 Roblox 开发人员实际构建的系统提供了 22 个配方：玩家数据、货币、库存、交易、开发者产品、抽奖、排行榜、伤害验证、能力、弹丸、NPC AI（大规模）、回合生命周期、匹配系统、放置系统、宠物、HUD 同步、速率限制等。每个都带有其组装顺序、特定情况下的故障模式、预算限制以及如何证明其有效。 **不会误报的审查。** 严重性分类法（Blocker、Correctness、Advisory）和不标记的目录：哪些分配实际上是热的，什么不会泄漏，什么不是信任边界，以及在哪里不使用已弃用的 API。发现必须通过四步置信门户才能报告。 **截至 2026 年 7 月的引擎。** 服务器权限、Character Controller Library、新 Luau 类型求解器、`InstanceHandle` 属性、统一数据存储限制和 2026 Luau 标准库。每个功能都标有成熟度，任何技能无法确认的内容都标记为未经验证，而不是断言。 **一站式平台上限。** 数据存储大小和请求预算、内存存储配额、消息大小上限、属性窗口、动画轨道限制。代理在设计时检查这些，而不是在生产中发现。 **Studio MCP 安全。** 当代理直接驱动 Studio 时，它会识别连接到的 MCP 变体，从实际存在的工具开始，在第一次写入之前运行预飞行检查，并知道哪些操作无法撤销：播放模式丢弃工作、错误输入路径静默创建新脚本、插入的资产带有后门脚本。它还知道哪些调用会悄悄消耗您的预算，并避免它们。 **保持上下文廉价。** 该技能有 22 个文件，但只有入口点在激活时加载。其余部分按需路由，因此任务会提取所需的引用，而不会提取更多内容。 --- ## 安装 ### Windows（PowerShell） ```powershell irm https://raw.githubusercontent.com/andrian-syh/roblox-best-practices-skill/main/install.ps1 | iex ``` ### macOS 和 Linux ```bash curl -fsSL https://raw.githubusercontent.com/andrian-syh/roblox-best-practices-skill/main/install.sh | bash ``` 这两个脚本都会在 Node 可用时启动 Node 安装程序，并在不可用时回退到原生菜单。 ### 直接 npx ```bash npx --allow-git=all github:andrian-syh/roblox-best-practices-skill ``` `--allow-git=all` 标志在 npm v12 及更高版本中是必需的，因为默认情况下会阻止 Git 获取。上面的单行命令为您处理此问题。 ### 标志 | 标志 | 效果 | |---|---| | `--all`, `-a` | 为通用路径和每个支持的代理安装 | | `--tag <tag>`, `-t <tag>` | 安装特定的已发布版本，例如 `v1.0.0` | | `--help`, `-h` | 显示 CLI 帮助 | --- ## 安装方式 **版本选择。** 安装程序从 GitHub 获取已发布的标签，并提供捆绑版本以及最近的五个版本。较旧的版本可以通过手动输入选项或 `--tag` 标志继续安装。 **通用目的地。** 该技能始终安装到 `./.agents/skills/roblox-best-practices/`，使其可用于任何读取标准工作区路径的工具。 **附加代理。** 安装程序扫描您的主目录以查找已知的代理配置文件夹，预选它找到的文件夹，并允许您在输入时过滤列表。 不存在的目录将被跳过。 ### 支持的代理 | 范围 | 目录 | 工具 | |---|---|---| | 通用（始终） | `./.agents/skills/` | Antigravity、Amp、Cline、Codex、Kimi Code CLI、OpenCode、Warp、Zed 等 | | 全局 | `~/.claude/skills/` | Claude Code | | 全局 | `~/.cursor/skills/` | Cursor | | 全局 | `~/.gemini/config/skills/` | Gemini | | 全局 | `~/.codex/skills/` | Codex | | 全局 | `~/.windsurf/skills/` | Windsurf 和 Cascade | | 全局 | `~/.roo/skills/` | Roo Code | | 全局 | `~/.trae/skills/` | Trae AI | | 全局 | *(还有更多)* | 总共 63 个代理，列在 [`bin/agents.txt`](bin/agents.txt) 中 | --- ## 技能行为 ### 两种模式 **默认。** 应用此技能的约定（写法）。适合新的或全新的工作。 **自适应。** 首先研究项目的现有约定，展示其发现的内容以及提出的标准，并在编写代码之前等待您的批准。安全规则仍然完全适用；只有样式和结构约定会适应。 ### 三个监督级别 | 代币 | 级别 | 行为 | |---|---|---| | `!ask` | 有监督 | 在每个有意义的决定之前确认 | | `!bal` | 平衡（默认） | 正常进行，停止真正的歧义或影响广泛的变化 | | `!go` | 自主 | 决定并在摘要中记录每个假设 | ### 确认门户 代理在一会话中解决这些问题，而不是假设：哪些社区库拥有一个关注点（ProfileStore、Packet、Trove、Knit、Fusion），以及该位置实际上是否运行服务器权限。Roblox 默认情况下不启用服务器权限，假设错误的模式会使输入、摄像头、模拟步骤和移动验证的正确答案失效。 --- ## 参考地图 只有入口点默认加载。以下所有内容均按需读取。 **创作** | 参考 | 涵盖 | |---|---| | [templates.md](roblox-best-practices/references/templates.md) | 脚本、LocalScripts 和 ModuleScripts 的注释布局 | | [adaptive-mode.md](roblox-best-practices/references/adaptive-mode.md) | 分析和采用现有项目的约定 | | [community-libraries.md](roblox-best-practices/references/community-libraries.md) | ProfileStore、Packet、ByteNet、Trove、Knit、Fusion 等 | | [luau-language.md](roblox-best-practices/references/luau-language.md) | 类型、新的类型求解器、调度、延迟事件、时间 API | **实施蓝图** | 参考 | 涵盖 | |---|---| | [cases/data-economy.md](roblox-best-practices/references/cases/data-economy.md) | 玩家数据、货币、库存、交易 | | [cases/monetization.md](roblox-best-practices/references/cases/monetization.md) | 开发者产品、通行证、订阅、抽奖 | | [cases/progression.md](roblox-best-practices/references/cases/progression.md) | 排行榜、每日奖励、连胜、离线进度 | | [cases/combat.md](roblox-best-practices/references/cases/combat.md) | 伤害验证、能力、弹丸、大规模 NPC AI | | [cases/session-flow.md](roblox-best-practices/references/cases/session-flow.md) | 回合生命周期、匹配系统、跨服务器事件 | | [cases/world-interaction.md](roblox-best-practices/references/cases/world-interaction.md) | 可交互对象、放置和建造、宠物 | | [cases/client-infra.md](roblox-best-practices/references/cases/client-infra.md) | HUD 同步、速率限制和防欺诈、分析 | **深度和防护** | 参考 | 涵盖 | |---|---| | [performance.md](roblox-best-practices/references/performance.md) | 热点循环、内存、网络、渲染、分析 | | [patterns.md](roblox-best-practices/references/patterns.md) | 数据存储、远程调用、清理、对象池、流媒体、角色生命周期 | | [security-monetization.md](roblox-best-practices/references/security-monetization.md) | 威胁模型、验证层、购买、文本过滤、策略 | | [server-authority.md](roblox-best-practices/references/server-authority.md) | 权威模拟，有它和没有它 | | [limits-budgets.md](roblox-best-practices/references/limits-budgets.md) | 数据、消息、属性、动画的平台上限 | | [ui-ux-testing.md](roblox-best-practices/references/ui-ux-testing.md) | UI 构建、跨平台输入、可测试的架构 | | [genres.md](roblox-best-practices/references/genres.md) | 按类型划分的风险配置文件，从模拟器到恐怖游戏 | | [false-positives.md](roblox-best-practices/references/false-positives.md) | 严重性分类法和不标记的目录 | | [api-currency.md](roblox-best-practices/references/api-currency.md) | 已确认的引擎和 Luau API 的基准 | | [verification.md](roblox-best-practices/references/verification.md) | 证明更改有效，以及命令栏 VM 陷阱 | | [studio-mcp.md](roblox-best-practices/references/studio-mcp.md) | 安全运行 Studio MCP 连接，无需浪费令牌 | 完整入口点：[SKILL.md](roblox-best-practices/SKILL.md)。 --- ## 脚本布局 每个脚本分为三个顶级部分，带有五级标题层次结构用于细分。 ```lua -- // 变量 // -- | 服务 | -- -- | 模块 | -- -- | 对象 | -- -- | 配置 | -- -- | 状态管理 | -- -- // 函数 // -- | 私有 | -- -- | 公共 | -- -- // 初始化 // ``` 仪式扩展到脚本。小型文件仅使用三个标题，而纯数据或类型模块则完全免除。 ## 不可协商的运行时规则 1. **服务器是权威的。** 验证每个远程参数的类型、范围、所有权和速率。 2. **清理您创建的所有内容。** 每个连接都有所有者和拆除路径。 3. **无可避免的每帧垃圾。** 将可以提升的内容提升到真正的热路径之外。 4. **反应，不要轮询。** 使用信号而不是监视条件的循环。 5. **安全保存数据。** `UpdateAsync` 带回退，保存后离开，关闭后刷新。 6. **预算网络。** 批处理，发送增量，使用不可靠事件处理容错数据。 7. **每次 yield 后重新验证。** 玩家可能已经离开，实例可能已经消失。 每个规则都有作用域异常，这些异常有文档记录，以便合法代码不会被报告为违规。 --- ## 维护 Roblox 持续发布更改，一年前的指导原则会悄悄失效。本技能针对此问题进行维护。 目标是 **每月末** 更新一次，根据 Roblox 在两个方面实际发布的内容： - **Luau**，语言本身：新的语法和标准库添加、类型求解器行为、编译器和运行时更改。 - **Roblox Studio 和引擎**：新的和已弃用的 API、系统在 beta 和正式发布之间移动、更改的平台限制，以及影响代理工作的 Studio 工具。 每个周期还会带来改进：更严格的防护、新的实施蓝图，以及对实际变更的纠正。如果无法确认任何内容，则标记为未经验证，而不是断言，因此该技能对其自身的边界保持诚实。 已发布的版本在 [CHANGELOG.md](CHANGELOG.md) 中标记和记录。 ## 贡献 问题和拉取请求欢迎在 [仓库](https://github.com/andrian-syh/roblox-best-practices-skill/issues) 中提出。修正尤其宝贵：如果技能声明了引擎不再执行的内容，那就是一个值得报告的错误。 ## 许可证 [MIT](LICENSE)。