roblox-studio-workflow

Roblox Studio 工作流

在现有场景中作为协作者开展工作，而不是把它当作一个空白文本仓库。面向当前的 Roblox Studio 和持续更新的平台 API。

使用场景

• 在对 Roblox 场景、Studio DataModel 或 Rojo 支持的项目进行大幅修改前使用。
• 用于规划执行位置、查找并复用系统、创建可编辑的 Instance，以及收集真实可信的 Studio 验证证据。

**不适用场景：**此技能负责项目操作，而非领域实现。请根据需要搭配 roblox-ui、roblox-networking、roblox-characters、roblox-physics、roblox-luau 或 roblox-datastores 使用。

工作流

1. **确定事实来源。**判断 Studio、Rojo 文件、包管理器或生成的构建产物分别负责哪些子树。不要手动编辑生成的输出，也不要创建会在下次同步时被覆盖的 Studio 独有改动。
2. **先盘点，再提出结构方案。**检查 Explorer，搜索脚本、模块、远程对象和标签，阅读项目映射及命名规范，并运行一次以观察现有警告。找到该功能当前的归属模块及其依赖项。
3. **规划兼容性最佳的最小改动。**列出要修改的 Instance 和执行位置。复用现有远程对象、组件模块、清理工具、标签、Attributes、文件夹和配置模式。说明尚未明确的归属边界。
4. **创建真实且有意义的对象。**常规设计的 UI、文件夹、附件、约束、远程对象和配置都应能在 Explorer 中检查。使用脚本处理行为和真正动态的重复内容，而不是通过运行时构建来隐藏整个功能。
5. **遵守执行与复制规则。**权威逻辑放在服务器容器中，持久客户端逻辑放在 StarterPlayerScripts 中，角色专属客户端逻辑放在 StarterCharacterScripts 中，UI 模板放在 StarterGui 中，共享资源、模块和远程对象放在 ReplicatedStorage 中，机密信息和服务器资源放在仅服务器可访问的容器中。
6. **测试实际风险。**根据行为选择 Play、Play Here、Run、Server & Clients、Device Emulator、Controller Emulator 或脚本化 Studio 测试。检查服务器和客户端的 Output，而不仅是视口。
7. **清理实验内容。**移除临时部件、测试远程对象、命令栏脚本、调试 UI、打印语句、已禁用的重复脚本、占位资源，以及仅为诊断而创建的标签和 Attributes。停止会话，并确认编辑模式下的层级结构干净。
8. **准确报告证据。**列出修改的 Instance/文件、测试模式和客户端数量、执行的测试用例、观察到的 Output、故障及其修复方式，以及任何未运行的内容。绝不要把“看起来合理”或静态检查说成“已在 Studio 中测试”。

执行位置对照表

位置	典型用途	主要限制
ServerScriptService	权威服务器 Scripts/模块	不会复制到客户端
ServerStorage	仅服务器可用的资源/数据	客户端无法访问
ReplicatedStorage	共享模块/资源/远程对象	客户端可见；不要存储机密信息
StarterPlayerScripts	跨重生持续运行的客户端系统	会克隆到 PlayerScripts
StarterCharacterScripts	角色专属客户端行为	每个角色都会重新创建
StarterGui	设计好的 UI 模板	会克隆到 PlayerGui；生命周期取决于 GUI 策略
Workspace	复制到客户端的世界和活动角色	流式加载/所有权可能影响客户端视图

确认实际的 Script RunContext 和项目规范；不能以类/位置的简写为由，不检查现有的自定义设置。

添加前先复用

创建 RemoteEvent 前，先按用途搜索并检查两端。添加“manager”或服务模块前，先确定当前功能的负责人。引入文件夹/标签前，先检查命名和检索模式。重复系统尤其危险，尤其是两者同时运行时：它们会重复绑定输入、重复保存、创建两个 UI 克隆，或重复应用游戏逻辑。

对于属于某个 Instance 的少量、类型明确且可由设计人员编辑的元数据，使用 Attributes。使用 CollectionService 标签来发现跨层级的 Instance 集合。文件夹用于归属/导航，而不是作为语义标签的替代品。保留已确立的架构，并在系统边界验证缺失或格式错误的 Attributes。

local CollectionService = game:GetService("CollectionService")

local function setupDoor(instance: Instance)
    if not instance:IsA("Model") then return end
    local accessLevel = instance:GetAttribute("AccessLevel")
    if type(accessLevel) ~= "number" then
        warn(`Door {instance:GetFullName()} needs numeric AccessLevel`)
        return
    end
    attachDoorBehavior(instance, accessLevel)
end

for _, door in CollectionService:GetTagged("Door") do setupDoor(door) end
CollectionService:GetInstanceAddedSignal("Door"):Connect(setupDoor)

拥有该 Instance 的系统还必须在带标签的 Instance 被移除/销毁时清理相关行为。

Studio MCP 服务（可选的 Agent 路径）

Roblox Studio 内置了 MCP 服务。当它连接到你的 AI 客户端后，可通过其工具执行同样的检查 -> 编辑 -> 运行/验证 -> 游玩测试流程，而不必手动点击。这是可选项：若未连接，则上文和下文所述的手动 Studio + Rojo 工作流就是完整的默认路径，本技能不要求使用 MCP、Assistant 或任何其他工具。在 Studio 中依次进入 Assistant、Manage MCP Servers，然后启用 "Enable Studio as MCP server"（它通过 stdio 上的 MCP 与客户端通信）。

将工作流映射到文档中介绍的工具。每次调用还需提供 studio_id；若打开了多个 Studio 窗口，请使用 list_roblox_studios 选择目标。

流程步骤	MCP 工具
检查 / 清点	search_game_tree、inspect_instance、script_search、script_grep
编辑	script_read、multi_edit（路径不存在时会创建脚本）
运行 / 验证	execute_luau（需要 datamodel_type：Edit、Client 或 Server）、get_studio_state、start_stop_play、get_console_output、screen_capture
游玩测试	subagent（类型为 explore、playtest）、character_navigation、user_keyboard_input、user_mouse_input
Roblox 官方文档/技能	http_get（允许访问的 Roblox 文档 URL）、skill（Roblox 编写的参考资料）

使用 MCP 不会改变这些规范：multi_edit 仍会写入普通且可检查的 Scripts（而不是隐藏在运行时构建中的功能），服务端仍保持权威，你仍需编辑真实来源文件而非生成的输出，并清理实验内容。将 get_console_output 和 screen_capture 视为验证流程中适用于 Agent 的证据，并仍须检查服务端和客户端的输出。MCP 是承载同一工作流的传输方式，不是跳过流程的许可。

Roblox 还提供了独立于 MCP、可供 Agent 读取的文档：索引位于 https://create.roblox.com/docs/llms.txt，每个文档页面都有一个 .md 版本（在其 URL 后追加 .md）。已连接的客户端可通过 http_get/skill 访问这些文档；离线 Agent 可直接读取 .md 页面。

验证流程

1. **静态检查：**项目映射/JSON/XML 可解析；链接有效；如有 Luau 诊断/代码检查工具，则运行检查。
2. **单次会话：**执行上下文和层级正确；Output 中没有新增错误/警告；基本成功路径和清理正常。
3. **生命周期：**根据相关情况，测试重生、重置、重新打开/重新加入、流式加载或角色替换。
4. **服务端与客户端：**对于远程事件、复制、所有权、玩家交互、加入/离开及定向状态，至少使用两个客户端。
5. **设备/输入：**测试有代表性的设备配置、屏幕方向、触控和控制器导航。
6. **压力/故障：**测试格式错误的输入、垃圾信息、内容为空/已满、快速切换、同时执行的操作、断开连接和清理。

使用能够覆盖此次改动的最小流程级别，但绝不能用较低级别的结果替代所声称的较高级别结果。

常见故障

现象	可能原因	解决方法
Studio 编辑内容在同步后消失	编辑了生成或映射的子树	修改事实来源文件，然后重新同步
功能运行了两次	存在重复的 Script/远程对象/控制器	先检查；再整合到现有的所有者之下
客户端无法访问模块/对象	执行或存储位置不正确	有意迁移共享内容；机密信息仅保留在服务器端
在 Explorer 中难以阅读编写的界面	所有内容都由一个 LocalScript 创建	创建命名的 Instance 外壳和小型行为模块
测试仅在 Play 中通过	未测试复制/生命周期	使用 Server & Clients 和相关模拟器
“干净”的 Output 中隐藏着客户端错误	只检查了服务器 Output	检查每个客户端和服务器上下文
发布的 place 中存在 DebugFolder/打印语句	跳过了实验清理	维护清理清单，并在会话后检查层级
Attribute/tag 行为悄无声息地失效	未验证架构/类	在设置边界进行验证；发出包含完整 Instance 路径的警告

资源

• 在报告 Studio 验证情况前，或在选择测试模式、构建临时测试框架或记录自动化缺口时，请阅读 references/studio-verification.md。

相关技能

• roblox-luau — 服务、Instances、事件和基本执行模型。
• roblox-ui、roblox-networking、roblox-characters、roblox-physics — 使用此检查与验证规范的专项生产工作流。

主要参考资料

• https://create.roblox.com/docs/studio/testing-modes
• https://create.roblox.com/docs/projects/data-model
• https://create.roblox.com/docs/scripting/services
• https://create.roblox.com/docs/studio/mcp