开发者文档 · v1

上传与发布

从构建目录或 ZIP 到工作稿、候选预览与正式上架。

完整游戏包通过 MCP 上传，站主后台支持管理资料、封面、预览和发布。以下流程使用已授权的 MCP 客户端。JSON 是对应工具的参数；UUID、修订号与本机路径需要替换为真实返回值。

准备发布文件

在游戏项目内使用自己的 Node.js / pnpm 等工具完成构建，得到包含入口 HTML 和完整资源的目录，也可以打包为 ZIP。独立 MCP 客户端使用 Node.js 24.x 或 26.x，已包含运行依赖，不要求游戏项目降级或使用平台的 pnpm 版本。入口默认为 index.html；ZIP 根目录应直接包含该入口，或显式指定实际入口路径。相对资源路径需保持完整。

平台读取并上传实际文件，不运行构建脚本、不解释远端客户端的本地路径。先完成游戏适配器接入，再提交发布包。

封面上限为 512000 字节（500 × 1024）。平台保留上传原图，公开页面使用最长边不超过 640px 的 WebP 缩略图；浏览器缓存通过 ETag 重新验证，下架或替换封面后旧地址停止公开访问。

拒绝路径穿越、符号链接、歧义重名、损坏 ZIP 和内部保留路径。上传前确认包里没有 .env、私钥、授权凭据或开发环境配置。

创建游戏工作稿

调用 create_game。slug 为 1–80 个小写字母或数字及单个分隔连字符；用作稳定访问标识。分类 ID 必须来自已发布站点分类，尚无分类时可传空数组。

{
  "input": {
    "slug": "my-web-game",
    "snapshot": {
      "title": "我的网页游戏",
      "summary": "一句话介绍玩法。",
      "description": "游戏介绍。",
      "instructions": "点击开始，使用方向键移动。",
      "devices": ["desktop", "mobile"],
      "categories": [],
      "coverId": null
    }
  },
  "idempotencyKey": "my-web-game-create-001"
}

保存写入结果中的 data.gameId、data.draftRevision 和 data.stateRevision。只声明实际支持的设备；更新现有游戏时先用 get_game 获取工作稿和修订号，再调用 save_game_draft，不要反复创建同一 slug。

上传游戏文件

调用 submit_game_files。它直接接收参数，不使用 input 包装。下面假设初始工作稿修订仍为 0；如果已修改资料或封面，需要使用最新修订。

{
  "gameId": "11111111-1111-4111-8111-111111111111",
  "expectedDraftRevision": 0,
  "localPath": "/ABSOLUTE/PATH/my-game/dist",
  "entry": "index.html",
  "idempotencyKey": "my-web-game-files-001"
}

localPath 也可指向 ZIP。成功完成后保存 data.draftRevision。上传会更新工作稿修订，不会自动生成候选或发布。文件传输中断且内容未变化时可用同一幂等键重试；若包内容改变或上传会话已失效，应重新读取修订并开始新上传，使用新键。

封面可在站主后台上传。上传封面也会更新工作稿修订；之后创建候选时再次读取最新修订。HTTP 上传方式见平台 API。

冻结候选并检查预览

调用 create_game_preview，将当前资料与文件冻结为不可变候选。假设上传后修订为 1：

{
  "input": {
    "gameId": "11111111-1111-4111-8111-111111111111",
    "expectedDraftRevision": 1
  },
  "idempotencyKey": "my-web-game-preview-001"
}

结果包含 data.candidateId、data.baseStateRevision 和 data.previewPath。站主在正式平台打开返回的预览路径，核对资料差异、入口、资源与实际玩法。私有文件预览需要有效网页会话，最长 15 分钟；分享资源 URL 不会授予预览权限。

候选创建后再改工作稿，不会改变已经冻结的候选。若检查后修改了文件或资料，需要重新创建并检查新候选；发布时明确使用自己检查过的候选 ID。

明确发布

确认候选后调用 publish_game，使用候选返回的 baseStateRevision 作为预期状态修订。下面的 0 只是首次发布示例：

{
  "input": {
    "gameId": "11111111-1111-4111-8111-111111111111",
    "candidateId": "22222222-2222-4222-8222-222222222222",
    "expectedStateRevision": 0
  },
  "idempotencyKey": "my-web-game-publish-001"
}

发布成功后检查 /games/my-web-game 和 /play/my-web-game，验证外壳内的身份、侧栏、防 Boss、音频、移动端和本机存档。首次正式游戏还需要验证独立游戏子域的 HTTPS 访问。若游戏此前已下架，更新或回退不会自动恢复上架，需要明确调用 set_game_availability。

修改、下架和回退

• 修改游戏：get_game → save_game_draft 或上传新文件 → 创建新候选 → 检查 → 发布。
• 下架或恢复：set_game_availability，提供 available 与最新 expectedStateRevision。
• 历史回退：rollback_game，只能选择曾经正式发布的 versionId；它不会恢复下架状态。
• 站点介绍、分类、精选和排序：get_site_config → save_site_draft → create_site_preview → publish_site_config，使用独立的站点修订与候选。

遇到 REVISION_CONFLICT，先重新读取并检查其他连接的新改动，重新生成候选，不盲目替换修订号后重发发布。相同连接、相同幂等键和相同输入会返回原成功结果；不同请求复用同键会产生 IDEMPOTENCY_CONFLICT。

授权边界

普通玩家不能上传和发布。多个 agent 可以由同一站主授权为不同管理连接，各自保存凭据、独立撤销；也可以由主管理员在后台账号管理将已验证邮箱的玩家添加为站主，各站主使用自己的账号和独立 MCP 连接。站主可以管理全站内容，操作记录显示实际操作账号及网页或 MCP 来源。上传、生成候选和正式发布是分开的步骤，给 agent 安排任务时请明确需要做到哪一步。