ali-ali18/agent-skills

使用 Rojo 进行 Roblox 开发 (Luau)

您可以在虚拟机内以纯文本文件的形式构建 Roblox 体验，使用 Rojo 编译为地点文件，并且仅在用户要求时，通过 Roblox Open Cloud 将该文件上传到测试地点。请以用户的语言回复（默认为 pt-BR）。

0. 基本规则

• 切勿打印、回显、记录或写入 API 密钥。仅在 shell 调用中使用保管库标记 {{secret:<name>}}；运行时会在输出中替换该值并将其隐藏。
• 仅发布到用户给您的测试地点（universeId + placeId）。切勿猜测 ID，也不要重复使用其他对话中的 ID。如果用户提供了生产/正式地点，请停止操作并确认用户意图。
• 默认 versionType 为 Saved（在版本历史中创建新版本，不会上线）。只有当用户明确要求上线时，才使用 Published。
• 缺少 universeId、placeId 或 secret 名称？请使用 propose_questionnaire 提问（一个简短的表单）。完全缺少 secret？请调用 secret_request（建议名称：ROBLOX_API_KEY）。切勿在聊天中询问密钥。

1. 安装 Rojo（每个 VM 一次）

固定版本：Rojo 7.7.1（请检查 https://github.com/rojo-rbx/rojo/releases 是否有更新的 7.x 版本，并在更改固定版本前告知用户）。将预编译的 Linux x86_64 二进制文件安装到 home 文件夹，无需 root 权限：

mkdir -p "$HOME/.local/bin" && cd "$(mktemp -d)"
curl -fsSL -o rojo.zip https://github.com/rojo-rbx/rojo/releases/download/v7.7.1/rojo-7.7.1-linux-x86_64.zip
unzip -o rojo.zip && install -m 0755 rojo "$HOME/.local/bin/rojo"
export PATH="$HOME/.local/bin:$PATH"
rojo --version   # 期望输出：rojo 7.7.1

首先使用 command -v rojo 检查；如果已安装 7.x 版本，则跳过安装。在 ARM VM 上，请使用 linux-aarch64 资源。如果已存在工具链管理器，备选方案：rokit add rojo-rbx/rojo && rokit install。请勿从其他任何 URL 运行安装程序。

2. 项目结构

my-game/
  default.project.json
  src/
    server/     -> ServerScriptService.Server   （仅服务端代码）
    client/     -> StarterPlayer.StarterPlayerScripts.Client
    shared/     -> ReplicatedStorage.Shared      （双方模块均可引用的模块）

default.project.json：

{
  "name": "my-game",
  "tree": {
    "$className": "DataModel",
    "ServerScriptService": { "Server": { "$path": "src/server" } },
    "ReplicatedStorage": { "Shared": { "$path": "src/shared" } },
    "StarterPlayer": {
      "$className": "StarterPlayer",
      "StarterPlayerScripts": { "Client": { "$path": "src/client" } }
    }
  }
}

Rojo 能理解的文件命名规则：init.server.luau（文件夹对应的 Script），*.server.luau（Script），*.client.luau（LocalScript），纯 *.luau（ModuleScript），init.luau（文件夹变成 ModuleScript）。添加一个包含 *.rbxl、*.rbxlx、Packages/ 的 .gitignore 文件。仅当文件夹中没有 default.project.json 时才创建项目；切勿覆盖现有布局，应适应它。

3. 编码规范

• 每个文件顶部使用 --!strict 的 Luau。为函数签名和导出表添加类型。
• 每个 ModuleScript 负责单一职责，返回一个表。禁止使用全局变量、_G、shared。使用 require 和直接引用（script.Parent.Module 或 ReplicatedStorage.Shared.Module）。
• 入口点保持精简：一个 init.server.luau 和一个客户端入口点，按顺序 require 服务/控制器并启动它们。
• 在文件顶部获取服务：local Players = game:GetService("Players")。优先使用 task.wait、task.spawn、task.delay 代替 wait/spawn/delay。在 Players.PlayerRemoving 上断开每个玩家的连接。
• 永远不要信任客户端。服务器拥有游戏状态（货币、背包、伤害、传送、进度）。客户端仅发送意图并渲染结果。

远程通信安全检查清单

• 在服务器端的 ReplicatedStorage 下创建具有固定名称的 RemoteEvent/RemoteFunction 实例；切勿从客户端创建。
• 在每个 OnServerEvent/OnServerInvoke 上：验证参数数量和类型（typeof），限制范围，拒绝 NaN/inf，限制字符串长度，检查玩家是否允许（冷却、所有权、距离、存活）。
• 按玩家进行速率限制（令牌桶或最后调用时间戳）。远程通信绝不应携带价格、伤害值或任何客户端可能利用以获得优势的值。
• RemoteFunction：切勿 InvokeClient（恶意客户端可能挂起服务器线程）。
• DataStore：使用 pcall 包裹，重试时使用退避策略，在 PlayerRemoving 和 game:BindToClose 时保存；对有价值的数据进行会话锁定。
• 机密和调节参数仅存在于 ServerScriptService/ServerStorage 中，切勿放在 ReplicatedStorage 中。

4. 构建

rojo build default.project.json -o place.rbxl
ls -l place.rbxl

首先修复构建错误（缺少 $path、JSON 错误、重复名称）。不要提交 place.rbxl。selene / stylua --check 是可选的；除非被要求，否则不要安装它们。仅由文件构建的地点是一个脚本骨架：在 Studio 中制作的资源、地形和 UI 存在于已存在的地点中，因此上传会替换目标版本的内容。这正是目标必须是测试地点的原因。

5. 通过 Open Cloud 发布（测试地点）

端点（Roblox Open Cloud 地点发布，universes v1）：

POST https://apis.roblox.com/universes/v1/{universeId}/places/{placeId}/versions?versionType=Saved|Published

• 标头 x-api-key: <key>；Content-Type: application/octet-stream（用于 .rbxl，二进制），application/xml（用于 .rbxlx）。
• 请求体：原始地点文件。成功响应：{ "versionNumber": 7 }。
• API 密钥需要目标体验的 universe-places 权限，并具有写入权限（在 Creator Dashboard 中创建）。
• 仅支持 HTTPS。该 API 不会更新某些实例类型（EditableImage、EditableMesh、PartOperation、SurfaceAppearance、BaseWrap）：告知用户从 Studio 发布这些内容。
• 文档：https://create.roblox.com/docs/en-us/cloud/guides/usage-place-publishing

使用保管库标记运行（标记放在 shell 命令内部，切勿放在您的消息文本中）：

curl -sS -X POST \
  "https://apis.roblox.com/universes/v1/$UNIVERSE_ID/places/$PLACE_ID/versions?versionType=Saved" \
  -H "x-api-key: {{secret:ROBLOX_API_KEY}}" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @place.rbxl

将 $UNIVERSE_ID 和 $PLACE_ID 替换为用户提供的数字，并将 secret 名称替换为实际的保管库名称（secret_list 仅显示名称）。处理错误时不要暴露密钥：401/403 = 密钥无效或缺少权限/体验；404 = universe/place 对错误；400 = 文件损坏（重新构建）；429 = 等待并重试一次。仅引用 HTTP 状态码和响应体，其中绝不包含密钥。

6. 报告

在每次任务结束时，用用户的语言生成一份简短报告：

1. 更改的内容（文件和功能），用通俗文字说明。
2. rojo build 的结果，如果已发布，还包括 versionNumber、使用的 versionType 以及发布到测试地点 <placeId> 的信息。
3. 如何在 Studio 中测试：打开测试地点，打开版本历史以加载新的 Saved 版本，按播放 (F5)，并列出要尝试的具体操作以及预期的输出信息。
4. 您没有执行的操作（上线发布、需要 Studio 的资源或地形）。

7. 本地同步选项

为了进行实时编辑，用户可以在自己的计算机上运行 rojo serve，并配合 Rojo Studio 插件（https://rojo.space/docs/v7/getting-started/installation/）。无法从用户的 Studio 访问 VM，因此在 VM 内部继续使用构建加 Open Cloud 上传的方式。