Merge branch 'master' into feat/agc-run-preview-tip

docs/project-memory/plans/【实施计划】游戏分发阶段A领域合同-2026-09-19.md

@@ -0,0 +1,123 @@
+# 【实施计划】游戏分发阶段A领域合同
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md` 阶段 A |
+| Status | in_progress |
+| Owner | Codex |
+
+## 修改边界
+
+- 允许修改：`module-game-distribution` 新领域 crate、workspace 声明、Rust shared-contracts DTO、领域单测及文档证据。
+- 明确不修改：发行域名与 CDN、旧 public work/runtime、AGC native 上传命令、网页发布表单。
+
+## 行为范围
+
+- 定义游戏身份、版本状态、包摘要、owner 权限、幂等 key 冲突和 publication revision CAS。
+- 领域服务先以纯内存仓储验证状态合同，再接入已冻结的 SpacetimeDB 游戏/版本/幂等收据表；不把内存仓储作为生产事实源。
+- 阶段 A 只提供身份、版本、真实包确认和状态回读基础，不提供“发布成功”或公开可玩状态，不绕过人工审核。
+
+## 验证命令
+
+1. `cargo test -p module-game-distribution --manifest-path server-rs/Cargo.toml`
+2. `cargo fmt --all --manifest-path server-rs/Cargo.toml -- --check`
+3. `npm run check:encoding`
+4. `git diff --check`
+
+## 风险与回滚点
+
+- API 接入前端前必须完成 SpacetimeDB facade 和 schema 门禁；任何失败都保留旧版本数据，不覆盖已有业务表。
+- 内存仓储只用于行为合同测试，不得被前端当作正式数据源。
+
+## 已完成证据（当前切片）
+
+- `module-game-distribution` 已落地游戏/版本状态机、owner 校验、幂等摘要冲突、上传确认、验证失败重试、审核 CAS、撤回和管理员暂停的纯领域服务与内存测试仓储。
+- 同一 crate 已加入不执行上传代码的 ZIP 包校验：根 `index.html`、路径穿越/大小写冲突、符号链接、加密文件、敏感文件、嵌套压缩包、单文件/总展开量/压缩比上限和逐文件 SHA-256 清单；并新增按白名单内容类型取单个发行资源的读取层。
+- Rust/TypeScript 跨端 DTO、SpacetimeDB 三张持久表、migration 白名单、生成 bindings、typed facade 和游戏分发 HTTP 路由已接入，覆盖创建、上传、送审、审核、下架、公开目录与详情。
+- `api-server` 新增发行网关 `GET /api/game-distribution/releases/{gameId}/{assetPath}`：只服务当前已公开版本，未知扩展名 404，附带 nosniff / CORP / HTML CSP，拒绝带 Cookie 请求，并按对象键做有界包缓存。
+- 重复发布复用游戏身份：游戏表末尾新增可空 `local_project_id`，`create_game_distribution_game` 在 owner + local_project_id 命中时复用既有 `gameId` 并只新增版本；`localProjectId` 经 shared-contracts（Rust/TS）透传，AGC 发布链路写入并在缺失时于发请求前失败关闭，api-server 对短标识做路径分隔符与控制字符校验。
+- 后台新增 `#game-distribution` 游戏审核页：待审列表、通过（要求 HTTPS 发行入口）、拒绝（要求理由）、幂等键与列表刷新；对应 `editor-showcase` Tab 权限映射、API client 与页面测试已加入。
+- 路由级测试证明发行网关、公开目录与登录发布路由确实挂载：带 Cookie 的发行请求 403、未知扩展名 404 且不触达对象存储、无 Bearer 的发布请求 401、目录在无数据库时返回 502 而不是 404。
+- 自动化证据：`cargo test -p module-game-distribution`（11 passed）、`cargo test -p api-server` 游戏分发模块（9 passed）与全量 `cargo test -p api-server`（1069 passed / 6 ignored）、`cargo test -p shared-contracts`、admin-web Vitest（149 passed，含新增游戏审核页与 client 用例）、前端游戏定向 Vitest（15 passed）、AGC `typecheck` 与 `local_project_export` Rust 测试（7 passed）、Vite build。
+- 版本回读、撤回与管理员安全下架闭环：新增 SpacetimeDB `get_game_distribution_version_and_return` / `cancel_game_distribution_version_and_return`（幂等收据 + 公开修订号 CAS）、`spacetime-client` façade、`GET /api/game-distribution/versions/{versionId}`（作者，未知与非 owner 一律 404）、`GET /admin/api/game-distribution/versions/{versionId}`（管理员）与 `POST /api/game-distribution/versions/{versionId}/cancel`（作者，`Idempotency-Key` + `expectedPublicationRevision`）；版本私有投影新增服务端派生的 `recoveryAction`（upload/submit/wait/none/reupload/fix_package/fix_metadata）。后台游戏审核页补齐「安全下架」入口（原因输入 + 二次确认弹窗 + 幂等键）。
+- 幂等响应语义修正：写操作 procedure 现在把「命中既有幂等收据」如实回传为 `replayed: true`（此前所有写操作都固定返回 false），覆盖创建游戏/版本、确认包、上传失败、送审、审核、撤回、下架与暂停。
+- 网页端恢复与撤回：`/games/publish` 在创建版本后写入带 owner 的发布草稿，窗口关闭或上传中断后同一账号可见「继续上传／继续送审」并复用原 `versionId`，换账号只忽略不读取；`/games/mine` 对可撤回状态提供二次确认的「撤回审核」，成功后刷新状态。
+- AGC 发布真实链路回归测试：新增 `apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts`（默认跳过，设置 `GENARRATIVE_AGC_PUBLISH_E2E_BASE_URL` 指向运行中的 api-server 才执行）。它不 mock 请求层，而是走真实的 `clientApi`/`clientHttp` 调用 `publishLocalProjectGame`，覆盖本地导出包读取、创建游戏、同 `localProjectId` 复用游戏身份、真实 ZIP 上传、送审、版本回读与 `my-games` 聚合，把「AGC 一键发布」从请求组装单测提升到真实后端链路证据。
+- AGC 客户端回归修复：导出试玩包后自动打开的发布面板是焦点陷阱模态，会让既有 `appSurface` 导出快捷操作用例静默失效；用例改为先断言面板出现、关闭后再继续，`appSurface.test.ts` 552 项（535 passed / 17 skipped）恢复全绿，并顺手补上该面板此前缺失的行为断言。同一轮修掉 `gameDistributionPublish.test.ts` 的模块 mock 缺少 `getClientServerBaseUrl` 导出的既有失败。
+- 发行来源（每游戏独立 origin）部署工件：新增 `deploy/nginx/genarrative-release-origin.conf` 与 `scripts/check-release-origin-config.mjs`（`npm run check:release-origin-config`）。模板按命名捕获 `game_id` 把 `https://<gameId>.games.<域>/` 映射到该游戏的 `index.html`、其余路径映射到发行网关前缀，边缘拒绝并清空 Cookie，不代理平台 API/后台/SPA；门禁逐条校验模板约束、交叉检查发行网关仍在设置 `nosniff`/CORP/CORS/CSP 与 Cookie 403，并在本机渲染临时配置跑 `nginx -t`。
+- AGC 发布面板组件测试：新增 `apps/ai-game-creator-shell/tests/gameDistributionPublishPanel.test.tsx`，覆盖打开时预填资料、发行包摘要、提交入参（项目路径/发行包/资料/幂等键）、连续点击只提交一次、服务端失败保留面板与无 Tauri 宿主/缺包时失败关闭。
+- 视觉与交互巡检修复：真实栈 + headless Chromium 逐页巡检 `/games`、`/games/detail`、`/games/play`、`/games/mine`、`/games/publish`（桌面 1440×900 与移动 390×844）。修掉两处：① 详情页「游玩方式」只读公开投影里恒为空的 `version.controls`，作者声明的 `inputModes` 被忽略，现在优先展示「键盘 · 鼠标 · 触屏」再退回自由文本；② 桌面端 hero 过高导致首屏看不到任何游戏卡片，改为仅桌面压缩 hero 高度，首排卡片进入 900px 视口。
+- 容量与限额边界（阶段 D 证据）：新增真实栈脚本覆盖 5 类包——① 99.0 MiB（两个 50/49 MiB 文件 + `index.html`，均在单文件/展开量/压缩比限制内）上传 200、耗时 11.8s、api-server RSS 81.6→378.0 MB（峰值 +296 MB）后回落 83.2 MB，随后送审 202 进入 `pending_review`；② 声明的 `packageBytes` 为 101 MiB 时在创建版本即被拒 413 `PAYLOAD_TOO_LARGE`（"发行包大小超出限制"，不落版本）；③ 声明合法但请求体 101 MiB 时被请求体限制拒绝 413（0.03s、内存零增长、版本保持 `awaiting_upload`/`upload`，可原版本重传）；④ 60 MiB 全零文件压到 61 KB（压缩比约 1000）拒绝 422 `PACKAGE_VALIDATION_FAILED`（0.01s，`upload_failed`/`reupload`）；⑤ 单文件 65 MiB 与 10,001 个文件同样 422（0.05s / 0.02s）。失败包都不出现在公开目录。
+- 发行包 PUT 受控重试：`platform-oss` 新增 `put_internal_object_with_retry`（复用既有 `oss_error_is_retryable` 分类：传输/超时/connect、408、429、5xx 与 400+RequestTimeout 可重试，确定性 4xx 不重试；body 只转一次 `Bytes` 供各 attempt 复用），发行包上传接入 3 次尝试 + 250/500ms 退避。触发原因：本机实测 99 MiB 单次 PUT 三次里出现过一次 `UPSTREAM_ERROR`（`请求 OSS 失败：error sending request`），客户端需要白传整包。
+- 网页端「为既有游戏发布新版本」：发布页新增 `updateGameId` 更新模式（按作者中心的最近版本回读冻结资料与公开修订号预填，提交时跳过创建游戏、直接在既有 `gameId` 下创建不可变新版本），作者中心新增「发布新版本」入口，壳层支持 `/games/publish?game=<gameId>`。浏览器真实链路：从 `/games/mine` 点「发布新版本」→ `/games/publish?game=…` 预填并显示「为《…》发布新版本 v2」→ 选包提交 → 该 `gameId` 下出现 `versions [(2, pending_review), (1, published)]`，公开入口仍指向并返回 v1 内容。此前网页端只能新建游戏，更新无法沿用 `gameId`，与里程碑「更新沿用相同 gameId」不符。
+- 全生命周期回归（真实栈，11 步）：待审公开不可见（目录不返回 + 详情 404）→ 管理员通过 v1 后目录/详情/网关可玩 V1 → v2 待审期间网关仍是 V1 → v2 被拒后仍是 V1 → 重复批准 `rejected` 版本返回 409（`rejected` 是终态，必须新建版本，与主规范一致）→ 新建 v3 通过后公开入口切换为 V3 → 作者回读被拒版本为 `rejected`/`fix_metadata` → 作者下架后目录/详情/网关全部关闭。同一轮修掉 5 条既有的壳层导航用例失败（游戏分发新增「游戏」页签与移动底栏后，测试仍断言旧导航集合）。
+- 边界、越权与隔离运行时证据（真实栈）：① 跨作者越权——作者 B 对作者 A 的版本上传 403、送审 403、撤回 404、回读 404，且 A 的版本状态未被改变；② 过期 CAS——管理员用错误 `publicationRevision` 批准返回 409，正确修订号才通过；③ 包边界——符号链接条目、`.env` 凭据文件、嵌套 ZIP 分别返回 422 `PACKAGE_VALIDATION_FAILED`，版本落到 `upload_failed`/`reupload`；④ 私有对象直取——按对象键直接 GET 私有 OSS 地址返回 **403**，发行文件只能经网关读取。
+- 浏览器沙箱隔离实测：发布一个自检探测包（内联脚本主动探测并 `postMessage` 回传结果），在 `/games/play` 里点「开始游戏」后收到 `{ origin: "http://127.0.0.1:10001", cookie: "throw:SecurityError", storage: "throw:SecurityError", parentDom: "throw:SecurityError", externalFetch: "throw:TypeError" }`——主站 Cookie、localStorage、父页面 DOM 全部不可访问，外站 fetch 被 CSP `connect-src 'self'` 阻断。键盘可达抽查：桌面端 Tab 顺序覆盖导航 → 搜索 → 下载客户端 → 账户，游戏分发自己的控件（发布游戏/我的游戏/分类页签/游戏卡片）聚焦时都有可见的浏览器默认焦点环。同一探测包还验证了音频链路：沙箱内 `fetch('assets/beep.wav')` 返回 `status:200 type:audio/wav`，WebAudio `decodeAudioData` 成功解出 `0.40s / 48000Hz`（`AudioContext.state = suspended`，与浏览器“首次播放需帧内用户手势”的策略一致，玩家进入游戏后的第一次交互即提供该手势）。游戏内真实触屏输入也已验证（见下一条）。
+- 上传中断与进程重启恢复（真实栈，两次独立实验）：60 MiB 包 PUT 进行到 ~2.5s 时 `SIGKILL` api-server，客户端拿到 `RemoteDisconnected`（等价于响应丢失）；重启后该版本仍是 `awaiting_upload`/`upload`，没有半确认状态。① 用不同字节重传返回 422 `PACKAGE_VALIDATION_FAILED`（`InvalidArchive`）并转 `upload_failed`/`reupload`；② 用固定时间戳构造的确定性 60 MiB 包重传**相同字节**返回 200（7.64s），版本转 `uploaded`/`submit`，随后送审 202 进入 `pending_review`。两次实验中游戏都未出现在公开目录。
+- 发布开关（回滚/事故能力）：新增 `game-distribution:publish` 灰度 gate（复用现役灰度配置机制与后台入口）。默认开放；`enabled=true` 时按白名单/用户标签/灰度百分比放行，`rolloutPercent=0` 且无白名单即全部关闭。关闭时作者写入与管理员批准返回 `503 GAME_DISTRIBUTION_PUBLISH_DISABLED`，而目录、详情、版本回读、发行网关、`/my-games`、审核队列读取、拒绝审核与安全下架继续可用；开关读取失败按关闭处理。路由级测试覆盖「默认放行 / 全关拦截 / 读取不受影响 / 白名单放行」，真实栈验证同口径：关闭后作者写入 503、目录/详情/网关/my-games 全 200、管理员批准 503 而拒绝 200、白名单用户可发布、重新开放后恢复。
+- 游戏内真实触屏输入（本机 Chromium + CDP `Input.dispatchTouchEvent`，390×844 视口）：在 `/games/play` 点「开始游戏」后，向 iframe 可视区域坐标派发 `touchStart`/`touchEnd`；`sandbox="allow-scripts"` 且 `ready` 的沙箱内探测包回传 `{touchstart: 1, touchend: 1, pointerdown: 1, pointerTypes: ["touch"], click: 1, target: "pad", touches: 1}`，证明真实触摸事件经平台进入游戏容器并命中目标元素。注意：触摸模拟必须在 iframe 文档创建之前启用，否则文档不会注册 touch 事件支持（首次实测只收到 pointerdown，重载后 touchstart/touchend 才出现）。
+- 可观测性（阶段 D「上传失败、校验耗时、审核积压、撤销传播」）：`api-server` 的游戏分发模块补齐结构化事件，均带 `request_id`（可 join 访问日志）与 `operation`，不记录 Token、signed URL、完整文件内容或本地路径。事件与字段：`package_confirmed`（game_id/version_id/package_bytes/file_count/sha256_prefix/oss_put_skipped/elapsed_ms）、`package_rejected`（code/reason/uploaded_bytes/elapsed_ms）、`version_submitted`、`version_cancelled`、`review_backlog_listed`（pending_versions/limit）、`review_decided`（decision/admin_user_id/publication_revision）、`game_unpublished`（visibility/publication_revision/active_version_id）、`game_suspended`（admin/reason/publication_revision）、`publish_switch_blocked`/`publish_switch_unavailable`、发行网关 `release_rejected`（debug 级：reason=cookie_present/unsupported_extension/not_public/no_active_version/version_not_published）。真实栈复跑一次完整链路后，8 类事件各出现 1-2 次，字段与耗时均可用（样例：`package_rejected … reason=InvalidArchive uploaded_bytes=9 elapsed_ms=6`、`game_unpublished … visibility=unpublished publication_revision=2 active_version_id=""`）。
+- 工程门禁：`npm run check:spacetime-schema`（147 tables）、`npm run check:server-rs-ddd`、`cargo fmt --all -- --check`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
+
+## 运行时证据（2026-09-20，真实本地栈）
+
+`npm run dev` 在无冲突端口段启动（spacetime `127.0.0.1:10004`、api-server `127.0.0.1:10001`、真实 OSS bucket `xushi-dev`），用 HTTP 全链路脚本验证：
+
+- 管理员登录 + 用户口令注册/登录均走真实路由。
+- 创建游戏后，用相同 `localProjectId` 再次创建返回**同一个 `gameId`**（去重在真实数据库上生效）。
+- 真实 ZIP（根 `index.html` + `assets/app.js`）上传私有 OSS，服务端重算 SHA-256 / 字节数 / 文件数并确认 `uploaded`。
+- 送审返回 `202` 与 `pending_review`；此时公开目录、公开详情都不返回该游戏。
+- 管理员用 HTTPS `entryUrl` 审核通过后，目录与详情出现该游戏并带当前版本 `entryUrl`。
+- 发行网关返回 `text/html` 与 `text/javascript`；带 `Cookie` 的发行请求 403，未知扩展名 404。
+- 作者下架后公开详情回到 404。
+- 更新链路：v2 送审期间与 v2 被拒后，公开入口始终停留在 v1 且 v1 内容仍可读取；v3 通过审核后才替换公开版本。
+- 真实浏览器（headless Chromium）加载发行网关的 `index.html`：文档渲染、同源 `assets/app.js` 在现役 CSP 下执行成功（`booted=1`、`window.__gd=1`），控制台只剩 favicon 404。
+- 浏览器打开 `http://127.0.0.1:10000/games` 能看到已发布游戏卡片，`/games/detail?id=<id>` 渲染标题与「立即玩」。
+- 平台页面内嵌游玩：浏览器打开 `/games/play?id=<id>`，点「开始游戏」后 iframe 以 `sandbox="allow-scripts"` 挂载发行网关地址，`game-player-frame--ready` 置位，控制台无 CSP/CORP 拦截，api-server 访问日志显示该版本 `assets/app.js` 返回 200。
+- 非生产环境允许 http 回环 `entryUrl`（与前端 `normalizeGameEntryUrl` 同口径），生产仍只接受 HTTPS；这样本地无需 TLS 即可验证内嵌游玩。
+- 作者中心 `/games/mine`：SpacetimeDB 新增 `list_owner_game_distribution_games_and_return`（owner 只从认证主体派生，每游戏最多回 10 个最近版本），`api-server` 暴露 `GET /api/game-distribution/my-games`；浏览器里用真实作者 token 打开该页，能看到「已公开」状态与「下架」按钮，点击后状态变为「未公开」、按钮消失，公开目录同步不再返回该游戏。
+- 网页端发布入口 `/games/publish`：浏览器里用真实文件选择框上传 ZIP（根 `index.html` + `assets/app.js`），api-server 访问日志记录 `POST /api/game-distribution/games` 200 → `POST /api/game-distribution/games/{gameId}/versions` 200 → `PUT /api/game-distribution/versions/{versionId}/package` 200 → `POST /api/game-distribution/versions/{versionId}/submit` 202；随后同一账号在 `/games/mine` 看到该游戏为「未公开 / 版本 v1 · 审核中」，公开目录不返回它。
+
+- 版本回读/撤回真实链路（`npm run dev`，api-server `127.0.0.1:10001`、SpacetimeDB `127.0.0.1:10004`）：作者送审后 `GET /versions/{id}` 返回 `pending_review` + `recoveryAction=wait`；其他账号与未知版本都是 404；过期修订号撤回 409；正常撤回 200 且状态变 `cancelled`、`recoveryAction=none`；同 key 同请求重放返回 `replayed=true`，同 key 不同摘要 409；撤回后公开目录不返回该游戏。
+- 主链路回归（同一真实栈）：正式发布 `replayed=false`、重复送审 `replayed=true`；待审期间目录不可见；管理员读版本 200、审核通过后状态 `published` 且目录与详情返回 `currentVersion.entryUrl`；发行网关 `index.html` 200、带 Cookie 403、未知扩展名 404。
+- AGC 发布真实链路（同一真实栈）：`GENARRATIVE_AGC_PUBLISH_E2E_BASE_URL=http://127.0.0.1:10001 npx vitest run apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts` 通过——AGC 发布函数依次完成创建游戏、创建版本、上传 ZIP、送审，返回 `pending_review`；版本回读为 `pending_review`/`wait`；不带旧幂等键的第二次发布复用同一 `gameId` 并生成 v2；`/my/games` 的 `latestVersion` 指向 v2。
+- 非法包真实链路（同一真实栈）：缺根 `index.html` 且含 `../` 条目的 ZIP 上传返回 422（包校验错误），版本进入 `upload_failed` 且 `recoveryAction=reupload`，此时送审被拒（409）、公开目录不返回该游戏，作者仍可撤回该版本重新出包。
+- 发行来源真实边缘验证（同一真实栈 + 本机 nginx 1.28.3，模板渲染到 `~/data/tmp` 后监听高位端口）：`Host: <gameId>.games.example.com` 时根路径 200 `text/html`（游戏 `index.html`）、`/assets/app.js` 200 `text/javascript`；带 `Cookie` 403；`/api/auth/me` 404（平台命名空间未暴露）；未知 gameId 404；http 301 到 https；响应头经边缘透传后仍是 `nosniff` + CORP `cross-origin` + 无凭据 CORS + HTML CSP + `Cache-Control: public, max-age=60, must-revalidate`。
+- 移动视口真实游玩：headless Chromium 以 `390x844` 打开已发布游戏 `/games/play?id=<id>`，页面显示「横屏设计，旋转设备」提示与移动端底部导航，点击「开始游戏」后 iframe 以 `sandbox="allow-scripts"` + `allow="fullscreen"` 挂载发行网关地址并 `ready`，`index.html` 与 `assets/app.js` 均返回 200，控制台无 CSP/CORP 报错；截图存于本轮验证记录（不入库）。
+本轮同时修掉三个真实缺陷：Vite dev 代理缺少 `/api/game-distribution` 前缀（本地全部 404）；详情页在「已发布但没有 controls」时误显示「暂未发布可玩版本」；发行网关的 `Cross-Origin-Resource-Policy: same-origin` 会让 opaque origin 沙箱内的游戏加载不了自己的脚本（改为 `cross-origin` + 无凭据 CORS，详见 `pitfalls.md`）。
+
+- 资料冻结与展示闭环（封面 + 截图）：游戏表末尾新增可空 `cover_object_key` / `screenshots_json`，版本表末尾新增可空 `metadata_json`；创建版本时 api-server 校验「必需封面、≤6 张截图、素材属于当前作者且 `content_type` 为 `image/`」，并从素材记录派生对象键生成冻结快照，审核通过时整体生效到游戏行。
+- 公开素材读授权：只有 `published` 且存在有效 `active_version_id` 的游戏，其封面/截图素材才在 `/api/assets/read-url` 获得匿名读授权；其余素材仍按 owner 校验。
+- 作者续发复用：版本回读（作者本人）与审核回读（管理员）的版本投影新增 `frozenMetadata`，带回 `coverAssetId` / `screenshots[].assetId`；`/games/publish` 更新模式据此预填封面与截图，不要求作者为沿用封面重新上传；快照缺素材 ID 的旧版本明确要求重新选择封面。公开投影仍只暴露对象键。
+- 网页发布资料入口：`/games/publish` 新增「封面与截图」区（封面必需、截图 ≤6、可逐张移除、上传中禁用提交），复用平台图片直传 + confirm 通道；本地校验与服务端口径对齐（缺封面/超 6 张在发请求前拦截）。
+- 网页展示：游戏广场卡片与详情页 hero 用 `useResolvedAssetReadUrl` 换签展示真实封面，详情页在存在截图时给出可点击缩略图条（封面 + 截图，选中态 + 键盘可达），换签失败或无素材时静默回退原有渐变占位，不出现空框。
+- 本切片验证：`cargo check -p api-server -p spacetime-module -p spacetime-client`；`cargo test -p api-server game_distribution`（17 passed，含新增 `version_detail_payload_exposes_frozen_metadata_to_owner`）；`npm run typecheck`；`npx vitest run src/components/game-distribution src/services/gameDistributionClient.test.ts`（46 passed）；改动文件 `eslint --max-warnings 0` 与 `npm run check:encoding`。
+
+- AGC 发布面板资料入口：新增 `apps/ai-game-creator-shell/src/services/assetDirectUpload.ts`（凭证 → 直传 → confirm，直传固定走 Tauri HTTP 插件并校验目标主机必须是平台素材存储），面板支持封面必选 + 截图 ≤6、本地预览、逐张移除、上传中禁用发布；缺封面时在创建游戏前失败关闭，服务端「封面」类错误原样展示；同一文件重复提交复用素材 ID 不重复直传。为支持直传，`src-tauri/capabilities/main.json` 的 http 作用域新增 `https://*.aliyuncs.com/*`（配合客户端主机白名单，避免把本地文件发给任意主机）。
+- AGC 测试证据：`npx vitest run apps/ai-game-creator-shell/tests/assetDirectUpload.test.ts apps/ai-game-creator-shell/tests/gameDistributionPublish.test.ts apps/ai-game-creator-shell/tests/gameDistributionPublishPanel.test.tsx apps/ai-game-creator-shell/tests/clientApi.test.ts`（27 passed）；`npm --prefix apps/ai-game-creator-shell run typecheck`；改动文件 `eslint --max-warnings 0`。
+
+- 真实本地栈媒体验证（2026-09-20，`npm run dev:api-server` + `dev:web`，api-server `127.0.0.1:12401`、SpacetimeDB `127.0.0.1:12402`、真实 dev OSS 桶）：`E2E_ADMIN_USER=… E2E_ADMIN_PASSWORD=… npm run check:game-distribution-media-e2e`（`scripts/check-game-distribution-media-e2e.mjs`）27 项全部通过——真实直传封面与 2 张截图素材、缺封面 400、截图 7 张 400、不存在素材 400（创建游戏与创建版本两处）、他人素材 403、创建游戏/版本/上传/送审（202 + `pending_review`）、作者回读拿到 `frozenMetadata` 且素材 ID 与顺序一致、待审期间公开目录不含该游戏且封面匿名读返回 404、管理员审核通过后公开投影带封面与截图对象键且不含素材 ID、匿名 `read-url` 对封面与截图都返回签名地址、发行网关 `index.html` 与 `assets/app.js` 均 200 且带 nosniff。
+- 真实浏览器展示验证（同一栈，headless Chromium `390x844` 与 `1280x900`）：`/games` 卡片渲染真实封面签名地址（无占位回退），`/games/detail?id=…` hero 显示封面、缩略图条渲染「封面 + 2 张截图」，点击第 3 张后 `aria-pressed` 与 hero 图片同步切换；移动端布局正常。截图存于 `~/data/tmp/gd3/`（不入库）。
+- 网页发布页真实上传验证（同一栈 + headless Chromium）：在 `/games/publish` 里用作者会话填写资料、选择真实 PNG 封面与 ZIP 并提交，页面返回「已提交审核」；随后 `my-games` 显示该游戏 `pending_review`，版本回读的 `frozenMetadata.coverAssetId` / `coverObjectKey` 正是本次浏览器上传的素材，证明网页端封面直传（凭证 → OSS → confirm）与冻结链路真实可用。
+- 发布资料入口交互打磨：原生 file 控件在上传后清空 value 时会显示「未选择任何文件」，与「已选择」提示互相矛盾；网页发布页与 AGC 面板都改成透明 input 覆盖自定义胶囊按钮（点击命中原生控件，文案显示「选择/更换封面图片」「添加截图」），并在验证中用 `elementFromPoint` 确认点击命中的是 `input[type=file]`。
+- AGC 直传能力作用域静态验证：用 `tauri-plugin-http` 同一套 `urlpattern` 解析逻辑验证 `capabilities/main.json` 新增的 `https://*.aliyuncs.com/*` 命中 dev 桶（`xushi-dev.oss-cn-beijing.aliyuncs.com/…`）与生产桶（`genarrative-assets.oss-cn-shanghai.aliyuncs.com/…`）、拒绝 `evil.example.com`；直传失败（含作用域拒绝/网络不可达）统一转成中文可操作文案，并有单测覆盖。桌面端真实执行仍需在装有 AGC 的机器上跑一次。
+- 创建游戏同步校验素材归属：此前 `POST /api/game-distribution/games` 只校验「封面必填 / 截图 ≤6 / ID 非空」，素材是否存在与是否属于当前作者要等到创建版本才失败，游戏行会先落一个无效素材 ID；现在创建游戏与创建版本都走 `resolve_owned_game_media`，不存在返回 400、他人素材返回 403。
+
+- 合并 master（`81e0c41f1`，含 `429f991bd` 定向回滚、Godot 原生绑定迁移与策划 Agent 模型控件）：回滚提交把混入 master 的游戏分发代码整体删掉，其中 25 个文件在本次合并里属于“双方都改动同一区域之外”的自动删除，直接合并会静默丢功能。处理方式是按“分支补回功能、master 保留迁移”逐类归位：模块注册（`spacetime-module/src/active.rs`）、api-server 路由与权限映射、后台审核页、AGC 发布命令与 payload 类型、`SelectionStage` 的 games 阶段、`ProjectSupervisorView` 的 `overlay` 挂载点、主站路由/标题、Cargo 依赖与锁、vite/vitest 代理与 tailwind source 全部取回分支版本；master 的 Godot C++ 迁移（删除旧 vendored GDExtension、新的 composer 控件样式）保留。合并后用“按文件对比 game-distribution 引用数不得下降”的脚本复核 85 个相关文件，无残留丢失。
+- 顺带修掉 master 自带的一处红灯：`src/config/viteProxyConfig.test.ts` 断言 `/api/creation-entry` 会被代理，但 master 的 `vite.config.ts` 并无该代理项，且 api-server 已把 `/api/creation-entry/config` 列入 retired 路由测试（dev 中间件按退役路径返回 404）。测试改为断言“退役路径不进入代理”，与 `isRetiredApiPath` 事实一致。
+
+- 第二次合并 master（`81e0c41f1` → `500835407`，304 个提交：DirectProject 聊天容器重构、Project Supervisor 退役、策划附件导入、CI 隔离编译缓存等）：冲突 9 个文件，其中真正需要集成决策的是 AGC 侧——master 把 `ProjectSupervisorView` / `SupervisorChatOnlyView` 整体退役（含我们此前挂 overlay 的挂载点），并且前端不再调用 `export_local_project_package`（`check-config.mjs` 把它登记为 native-only）。处理方式：接受 master 的退役与删除；把发布入口重新接到新架构上——`DirectProjectChatHeader` 新增「发布到游戏广场」按钮（没有回调时不渲染、忙态禁用），`DirectProjectChatView` 透传 `onRequestGamePublish`，`App.tsx` 用工作台壳持有试玩包导出与 `GameDistributionPublishPanel`（沿用 `project.export_package` 权限确认队列），并把该命令从 `check-config.mjs` 的 native-only 清单移回 App invoke。
+- 同轮修掉 master 自带的红灯断言：`src/config/viteProxyConfig.test.ts` 曾断言 `/api/creation-entry` 会被代理，但配置无该代理项且 api-server 已把 `/api/creation-entry/config` 列为退役路由，测试改为断言退役路径不进入代理。
+- 覆盖率与门禁（合并后）：全量 `npm test` 392 文件 / 4371 用例通过（appSurface 重构后 215 用例）、两端与 admin-web typecheck、`cargo check`（api-server / spacetime-module / spacetime-client）、`cargo test`（api-server 游戏分发 17、module-game-distribution 11）、`check:encoding`、`check:doc-index`、`check:rustfmt`、SpacetimeDB schema guard（对比 `origin/master`）。
+
+- 第三次合并 master（`500835407` → `fdc14404b`：DirectProject 回合三态、投影 memo、宿主崩溃后的回合收口、策划对话布局修复、AGC release 每日调度）：git 自动合并无冲突，但产生了**静默拼接缺陷**——新加的聊天头 CSS 被并进了 master 策划态分组选择器中间，导致 `.project-chat-topbar-status` 在策划态丢失 `font-size`（`chatDialogFrameLayout` 用例抓到）。修复方式是按 master 原文重建分组规则、把发布入口规则独立成块，并把重复的状态规则删掉。
+- 合并后复核：全量 `npm test` 393 文件 / 4374 用例通过，root / AGC / admin-web 三端 typecheck 通过，发布入口（聊天头「发布到游戏广场」→ 试玩包导出 → 发布面板）在新回合三态下保持接线。
+
+- 发布入口灰度下发：`GET /api/runtime/frontend-config` 新增 `gameDistributionPublishEnabled`，复用既有 `is_game_distribution_publish_enabled_for_user`（未配置 `game-distribution:publish` 或 `enabled=false` 时对已登录作者默认开放，显式收紧后只放行白名单/灰度命中，匿名恒为 false），避免前端入口与写入口出现两套判据。网页端 `PlatformEntryActiveFlowShell` 据此隐藏「发布游戏 / 发布新版本」入口，`/games/publish` 直接访问时渲染「发布功能正在灰度中」并提供重新检查；AGC 端 `readGamePublishAvailability` 同样读该字段，只有命中才把发布回调交给 DirectProject 聊天头。
+- 灰度验证：`cargo test -p api-server frontend_runtime_config`（6 passed，含新增的 `frontend_runtime_config_game_distribution_publish_is_scoped_to_authenticated_gate`：无 gate 行 → 登录作者 true/匿名 false；`enabled=true` 无白名单 → false；白名单命中 → true；`deny_user_ids` → false；`enabled=false` → true；`rolloutPercent=100` → true）、网页发布页 15 用例（含灰度未命中隐藏表单与「重新检查」放行）、平台壳 18 用例（含广场入口按灰度隐藏/显示）、AGC 发布服务 6 用例（含字段缺失与读取失败按不开放处理）。
+
+## 尚未完成
+
+- 真实独立发行域名、通配 TLS 与 CDN 仍属部署侧：边缘模板与门禁已就绪，本地已用真实 nginx 验证按主机映射、Cookie 403 与命名空间隔离，但仍需在真实域名/证书下跑一次“审核通过 → 游玩 → 换版 → 下架”并确认 CDN TTL 不超过 60 秒窗口。
+- 版本回读、撤回与管理员安全下架已实现；主规范 HTTP 表中不再有待落地路由。容量与限额边界、发行包 PUT 重试已有真实栈证据；仍未做的是 CDN purge 失败行为、回滚演练与清理策略（不删除仍被公开版本引用的对象）的上线验收。
+- 生产调用依赖已初始化的 editor generation runtime service identity；未初始化时 procedure 拒绝写入，不会退回 API 进程内存状态。

docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md

@@ -0,0 +1,135 @@
+# 【里程碑】游戏分发、发布与在线游玩
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 0.2 |
+| Status | accepted（用户“继续”确认按既定假设进入阶段 A；A 未验收） |
+| Date | 2026-09-18 |
+| Parent Spec | `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` |
+
+## 交付与评审边界
+
+本文件拆分主规范“AGC 游戏分发与在线游玩合同”的完整业务：真实上传、持久化发行、审核、隔离托管、AGC 发布、网页上传与游玩、上线运维。当前只授权阶段 A 实现，阶段 B/C/D 仍为 `proposed`，没有已上线/已验收结论。
+
+先完成主规范与本文件评审，再为一个获准阶段创建单独实施计划；未经该阶段验收，不进入依赖它的阶段。里程碑只规定行为与证据，不预先写代码步骤。
+
+| 阶段 | 行为切片 | 依赖 | 状态 |
+| --- | --- | --- | --- |
+| A | 真实包、游戏身份与可恢复发行 | 主规范评审及持久化合同冻结 | accepted（实现中） |
+| B | 人工审核、公开投影与隔离托管 | A 验收；发行站点/私有存储/审核策略确认 | proposed |
+| C | AGC 与网页发布、现代游戏目录和跨端游玩 | B 验收；导航与交互稿评审 | proposed |
+| D | 端到端验收、容量与撤销、上线准备 | C 验收；实际部署资源可用 | proposed |
+
+## 实现进度（2026-09-20，未验收）
+
+以下是已落地的实现与本地运行时证据，**不等于阶段验收**：B/C 的隔离托管、域名与生产验收仍缺少真实发行域名、TLS/CDN 与生产账号。
+
+- 阶段 A：真实 ZIP 上传、游戏身份、owner/幂等/CAS、状态机、DTO 与 schema 门禁已完成；真实 SpacetimeDB + 私有 OSS 的创建/上传/确认/重启恢复已有证据。
+- 阶段 B：人工审核（后台列表、通过需 HTTPS 入口、拒绝需理由）、公开投影、发行网关（按公开版本服务、扩展名白名单、`nosniff`/CORP/CSP、带 Cookie 403）与作者下架已实现；每游戏独立来源已有可执行工件 `deploy/nginx/genarrative-release-origin.conf` 与门禁 `npm run check:release-origin-config`，并已在本机用真实 nginx + 真实网关验证按主机映射、Cookie 403 与平台命名空间 404；生产域名、通配证书与 CDN TTL 仍需上线环境确认。
+- 阶段 C：AGC 客户端「发布到平台」面板与发布链路（dist 归一化根 `index.html`、摘要/字节数声明、幂等键、`localProjectId` 复用）已实现并有请求组装与 Rust 导出测试；网页 `/games/publish` 走同一服务端管道，本地已用真实文件选择验证；AGC GUI 自身的端到端发布仍待客户端环境验收。目录（关键词/分类/设备筛选、滚动与筛选恢复）、详情、游玩页（主动作后加载、超时重试、旋转提示、全屏、移动端门槛）与作者中心（状态、驳回理由、撤回、下架）已实现；本地已在桌面与 `390x844` 移动视口真实游玩。
+- 阶段 D：容量/额度、重启恢复、CDN 撤销与回滚演练尚未开始，依赖生产资源。
+
+细节与命令级证据见[实施计划【游戏分发阶段A领域合同】](【实施计划】游戏分发阶段A领域合同-2026-09-19.md)的「已完成证据」「运行时证据」「尚未完成」。
+
+## 共通范围与不做项
+
+- 正式状态来自后端，素材仍复用平台上传与归属能力；前端和 AGC 不另建公开游戏状态、owner 事实或审核结果。
+- 真实发行包具有不可变版本和 SHA-256，AGC dist 归一化为发行根 `index.html`；网页 ZIP 与 AGC 共用一条服务管道。
+- 不恢复退役玩法 API、公开作品表或专属 runtime；不把私有项目源码镜像公开。
+- 首版不包含原生/Wasm 游戏、任意外网依赖、服务端进程、多人联机、云存档、评论/评分/关注、排行榜、推荐算法和收益结算。
+- 本文件只协调本业务；不顺带改造图片编辑器、Agent Runtime 执行模型或无关项目数据。
+
+## 阶段 A：真实包、身份与可恢复发行
+
+### 前置条件
+
+- 主规范的包类型、限额、身份/幂等/CAS、状态机和内部 API 已评审。
+- 游戏、版本、审核与操作账本的完整字段、索引、唯一约束、受信服务身份及清理策略已经冻结；若涉及已有表破坏性变更，另有已确认迁移计划。
+
+### 行为与验收
+
+- [ ] 登录用户创建服务端分配的游戏，owner 不能由请求伪造；其他账号不能读取私有版本、上传、提交或撤销。
+- [ ] 服务端接收真实 ZIP 字节，重算摘要/字节数并建立展开清单；只有 metadata 的请求不能获得已上传或已发布状态。
+- [ ] 缺入口、越界/重复/大小写冲突路径、符号链接、压缩炸弹、敏感内容和额度超限均失败关闭，原私有对象和公开状态保持一致。
+- [ ] 一份版本只接受一份已确认内容；同 key 同请求重放无重复游戏/版本，不同请求冲突；同版本并发上传不混写。
+- [ ] 校验可异步恢复，响应丢失、服务进程退出和客户端重试均回到原版本；确定失败和未知结果在响应中可区分。
+- [ ] 正常及失败状态、私有查询和错误 envelope 在 Rust 与 TypeScript DTO 中一致；新增 schema、迁移、表目录与绑定一致。
+
+### 证据要求
+
+- 自动化：领域状态机、owner、幂等/CAS、包读取与错误路径、DTO 和 schema 定向测试。
+- 运行时：真实 SpacetimeDB 与私有对象存储完成上传/回读/重启恢复；`/healthz` 正常。
+- 边界：服务端记录的 ZIP 摘要与测试上传字节一致；未审核目录不能匿名读取；无凭据或本地路径泄漏。
+
+## 阶段 B：审核、公开投影与隔离托管
+
+### 前置条件
+
+- A 已验收；人工审核角色、资料检查标准与拒绝/封禁行为已确认。
+- 已确定不同可注册站点的发行域名、每游戏独立 origin、私有存储和网关能力；同源临时路径不能作为验收替代。
+
+### 行为与验收
+
+- [ ] 自动校验通过只进入待审，管理员可查看真实待审游戏并批准/拒绝；审核记录可追溯且普通作者不能提交审核动作。
+- [ ] 新游戏审核通过并核验发行文件可读后才公开；更新待审或失败不改变旧版资料、URL 与可玩性。
+- [ ] 审核激活与下架使用 `publicationRevision` CAS；过期审核、重复批准、并发更新和下架不会恢复本应关闭的游戏。
+- [ ] 游客目录、详情和启动接口只返回已公开投影；未公开和已下架状态均不可见，不返回私有快照地址。
+- [ ] 每游戏在独立 HTTPS origin 上，iframe sandbox、网关 CSP/CORS/MIME/禁止 Worker 等策略与主规范一致。
+- [ ] 实际 npm/Vite 模块和同包资源在 opaque sandbox 下可载入；外站 fetch/WebSocket、平台 Cookie/storage/DOM、顶层跳转、弹窗和敏感权限被阻断。
+- [ ] 作者下架及管理员安全下架会关闭新启动和发行读取；不能绕过网关直取公开 OSS 对象；撤销传播符合最大缓存窗口。
+
+### 证据要求
+
+- 自动化：审核权限、版本切换事务、公开投影与入口 allowlist、响应头和缓存策略测试。
+- 运行时：真实独立域名内运行至少一个代表性游戏；真实审核、更新失败、并发下架和旧 URL 回读证据。
+- 边界：外部请求阻断、匿名私有对象拒绝、跨游戏 origin 隔离及 60 秒以内缓存撤销（以获批值为准）。
+
+## 阶段 C：双端发布与现代游戏体验
+
+### 前置条件
+
+- B 已验收；网页根入口、桌面/移动导航、暖色主题交互稿及首版设备范围已评审。
+- AGC 现有 npm 构建/导出能提供完整 dist，不需要把源码同步管道改作发行管道。
+
+### 行为与验收
+
+- [ ] AGC 从已构建 dist 生成根入口为 `index.html` 的真实包，一次提交动作完成检查、资料确认、上传和送审；状态及失败原因与服务端回读一致。
+- [ ] 网页可选 ZIP、提交封面和必需资料，进入相同上传/校验/审核流程；任一客户端可以查看同账号游戏状态，更新沿用相同 `gameId`。
+- [ ] 上传中断、双击、登录失效、窗口关闭后恢复原操作；换账号不能恢复前账号私有状态；待审不能显示为已发布。
+- [ ] 目录支持真实数据、关键词/分类/设备筛选、空/错/加载态；详情提供明确主动作，搜索与返回恢复上下文。
+- [ ] 游客从目录/分享链接进入详情再启动真实已发布游戏；开始操作后才加载 iframe，加载失败可重试，退出不会自动重启游戏。
+- [ ] 桌面与移动导航、详情、上传/发布面板、旋转提示、全屏、安全区和焦点可达符合主规范；不适配移动端的游戏有明确门槛。
+- [ ] 视觉沿用现有 warm token，通用交互复用共享组件；没有固定假统计、本地演示兜底或同源 iframe 放宽。
+
+### 证据要求
+
+- 自动化：AGC 打包与操作恢复定向 Rust 测试、两端客户端/组件/路由/状态测试及类型检查。
+- 运行时：AGC 一次真实发布、网页一次真实 ZIP 上传，分别审核后从桌面和手机游玩；浏览器覆盖游戏模块、素材、音频、触屏及横竖屏。
+- 边界：未构建/失效 dist、资料缺失、换账号、迟到响应、审核拒绝、非移动游戏及真实空态。
+
+## 阶段 D：端到端、运维与上线准备
+
+### 前置条件
+
+- C 已验收；生产域名/TLS、CDN、私有存储、审核账号及保留/清理周期可用且已确认。
+
+### 行为与验收
+
+- [ ] 真实环境中完整跑通“首次上传 → 校验 → 审核 → 公开 → 游客游玩 → 更新待审旧版在线 → 新版切换 → 下架撤销”。
+- [ ] 100 MiB 包与获批文件数/展开量边界有可复核耗时、内存和失败证据；校验不会执行上传代码，服务资源有界。
+- [ ] 校验执行器重启可恢复，审核积压与失败可观测，清理不删除仍被公开版本引用的文件。
+- [ ] CDN purge 失败时仍在获批缓存 TTL 内拒绝新资源；明确已下载脚本无法远程抹除的边界。
+- [ ] 发布/回滚步骤保留当前公开版本，能关闭新提交和新版本激活；部署路由、缓存、响应头、日志脱敏和告警完成检查。
+- [ ] 主规范逐条证据矩阵齐全，未验证项明确列出；有任何核心路径未验证时不标记上线完成。
+
+### 证据要求
+
+- 自动化：范围匹配前后端、schema/契约、编码与文档索引门禁，部署配置检查。
+- 运行时：真实发行域名、真实存储、真实账号和两类客户端的完整链路证据，桌面及移动视口记录。
+- 边界：压力/额度、重启恢复、缓存撤销、误删防护和回滚演练。
+
+## 当前待审项与下一门禁
+
+主规范仍待确认人工审核策略、导航、首版能力/额度、对象保留、发行域名及运营责任；当前没有主规范与里程碑通过评审的记录，也没有任何阶段验收证据。先评审这些决策，再冻结 A 的持久化与 DTO 明细并创建仅覆盖 A 的实施计划。不得把该文档状态改为 accepted 以代替评审。
+
+所有阶段完成并验收后，稳定事实回写主规范，删除本临时里程碑与各阶段实施计划；过程记录不进入产品代码、用户文案或长期共享记忆。

docs/project-memory/shared-memory/decision-log.md

@@ -295,6 +295,42 @@ Godot 编辑器操控复用既有 AGC 插件宿主、EditorAdapter、Runner 和
 - 验证方式：`provider_transient_retry_` 7 项中重写后的档位用例与 upstream-400 用例通过（断言 `maxRetries` 直取设置值、400 与其它瞬态共用同一预算），`provider_retry_` 其余 26/28 通过；该组 2 项（`provider_transient_retry_transport_failure_closes_then_stable_retry_succeeds`、`provider_transient_retry_backoff_is_exponential_and_capped_at_thirty_seconds`）与 `provider_retry_waiting_final_reply_*` 2 项在本机改动前后同为失败（`stash` 基线复跑确认，现象是等待自动重试唤醒超时）。本机串行全量套件另有既有环境失败（`tempfile::tempdir()` 归属校验、缺少 npm 构建产物、Windows 启动失败 MessageBox 阻塞 `startup_log_slot_fail_without_path...`）；抽查其中 5 项在 `stash` 基线上同样失败，与本次改动无关。仓库 `cargo fmt --check`、`npm run check:encoding`、`git diff --check` 通过。
 - 关联文档：[AI游戏创作智能体App实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)、[踩坑记录](pitfalls.md)。
 
+## 2026-09-20 游戏分发用灰度开关承载「关闭投稿、保在线」的回滚口径
+
+- 背景：主规范要求回滚部署时“关闭新提交和新版本激活，保留当前可玩版本与状态读取”。此前只能靠改配置或停服实现。
+- 决策：复用现役灰度配置（`game-distribution:publish`，后台「灰度发布配置」可改），没有 gate 行或 `enabled=false` 时默认开放；`enabled=true` 时只有白名单/标签/灰度命中的作者能发布，`rolloutPercent=0` 且无白名单等于紧急关闭投稿。拦截范围是作者写入（创建游戏/版本、上传、送审、撤回、下架）与管理员批准；读取、发行网关、审核队列读取、拒绝审核与安全下架始终可用，避免把“关投稿”变成“停服务”或“无法处理事故”。
+- 失败姿态：开关读取失败按关闭处理（写入口 503），读取路径不受影响。
+- 关联：`server-rs/crates/module-runtime/src/application.rs`、`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/api-server/src/modules/game_distribution.rs`、[开发运维文档](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)。
+
+## 2026-09-20 游戏发行包 PUT 采用受控重试与容量边界口径
+
+- 背景：阶段 D 容量验证时实测 99.0 MiB 发行包单次 PUT 成功耗时 11.8s、api-server 峰值内存 378 MB（基线 82 MB），但三次尝试里出现过一次 `请求 OSS 失败：error sending request`。当时版本停在 `awaiting_upload`（可原版本重传），代价是作者白传一次整包。
+- 决策：`platform-oss` 新增 `put_internal_object_with_retry`，复用既有 `oss_error_is_retryable` 分类（传输/超时/connect、408、429、5xx、400+RequestTimeout 可重试；确定性 4xx 不重试），body 只转一次引用计数的 `Bytes`，各 attempt 复用同一份字节；发行包上传配置为 3 次尝试、250/500ms 退避，参数不合法（次数为 0 或缺退避）时按配置错误失败关闭。
+- 容量口径（真实栈实测，作为阶段 D 证据基线）：99.0 MiB 包 11.8s / 峰值 +296 MB；声明 101 MiB 在创建版本即 413；请求体 101 MiB 被请求体限制 413 且版本保持可重传；压缩比 1000 与单文件 65 MiB、10,001 文件都是 422 `PACKAGE_VALIDATION_FAILED` 并落到 `upload_failed`/`reupload`；失败包不进公开目录。
+- 关联：`server-rs/crates/platform-oss/src/lib.rs`、`server-rs/crates/api-server/src/modules/game_distribution.rs`、[实施计划](../plans/【实施计划】游戏分发阶段A领域合同-2026-09-19.md)。
+
+## 2026-09-20 游戏详情的“游玩方式”以版本声明的 inputModes 为准
+
+- 背景：公开投影里 `currentVersion.controls` 一直是空数组（首版没有自由文本操作说明的录入），详情页却只读它，于是所有已发布游戏都显示「未标注操作方式」，而作者其实在发布时声明过 `inputModes`。
+- 决策：展示层优先用公开投影里已有的结构化 `inputModes`（键盘 / 鼠标 / 触屏，去重后按声明顺序拼接），再退回 `controls` 自由文本，两者都为空才显示「未标注操作方式」。不改 HTTP 契约、不新增后端字段。
+- 关联：`src/components/game-distribution/GameDetailPage.tsx`、`src/components/game-distribution/GameDistributionPages.test.tsx`、[主规范](../../【玩法创作】平台入口与玩法链路-2026-05-15.md)。
+
+## 2026-09-20 游戏分发的版本回读、撤回与安全下架以服务端 recoveryAction 为准
+
+- 决策：游戏发行版本的「下一步做什么」不从客户端状态推断。`GET /api/game-distribution/versions/{versionId}`（作者）与 `/admin/api/game-distribution/versions/{versionId}`（管理员）返回版本私有投影 + 服务端派生的 `recoveryAction`（`upload` / `submit` / `wait` / `none` / `reupload` / `fix_package` / `fix_metadata`），网页发布页与作者中心只按它渲染主行动作。
+- 撤回语义：`POST /api/game-distribution/versions/{versionId}/cancel` 只能撤回未参与当前公开投影的版本，要求 `Idempotency-Key` 与 `expectedPublicationRevision` CAS；已公开版本必须走作者下架或管理员 `suspend`，不能借撤回关闭线上入口。
+- 可见性：未知版本与非 owner 的版本一律 404，不用 403 区分「别人的版本」和「不存在的版本」。
+- 幂等响应：命中既有幂等收据的写操作统一回传 `replayed: true`（此前所有写操作固定 false），客户端据此区分「本次生效」与「复用既有结果」。
+- 网页恢复：`/games/publish` 只把 `{ownerUserId, gameId, versionId, versionNumber, title}` 写入 localStorage 作为恢复标识；换账号只忽略草稿、不回读也不清除，禁止展示上一账号的私有状态。
+- 关联文档：[游戏分发实现计划](../plans/【实施计划】游戏分发阶段A领域合同-2026-09-19.md)、[主规范](../../【玩法创作】平台入口与玩法链路-2026-05-15.md)。
+
+## 2026-09-18 AGC backend 采用共享 Runtime、本地宿主与云端控制面分层
+
+- 决策：AGC backend 统一按“`agent-runtime-core`/`agent-runtime-orchestration` 共享内核 + Tauri 本地执行宿主 + `server-rs` 云端控制面 + `module-*`/`platform-*` 领域与外部适配器”整理；先建立 application facade、能力合同和跨边界状态映射，不新建第二套 Agent Runtime、会话库或业务真相。
+- 数据边界：本地项目文件、manifest、JSONL、checkpoint、锁和 Runner 状态由 AGC 本地宿主持有；认证、模型目录、编辑器资源、异步生成、计费、快照元数据和诊断由云端持有；大对象按现有 OSS 合同保存。
+- 约束：Runtime core 不依赖 Tauri/Axum/SpacetimeDB/Provider；领域规则留在 `module-*`；HTTP/SSE/BFF 留在 `api-server`；SpacetimeDB 访问统一经 `spacetime-client`；外部服务统一经 `platform-*`；前端只消费后端或本地宿主投影。
+- 权威文档：[AGC 后端框架整理与演进路线](../../technical/【技术方案】AGC后端框架整理与演进路线-2026-09-18.md)。
+
 ## 2026-09-17 AGC 抠图提交使用远端画布项目身份
 
 - 背景：AGC 已通过本地项目 ID 建立并持久化本地项目到主站远端画布项目的绑定，但 `agc_remove_background` 提交请求仍把本地 `manifest.project_id` 放入 `projectId`；`assetFolderId` 已使用远端素材目录 ID。主站因此按项目不存在或不属于当前账号返回 404，主站抠图和 BgFilter 本身均正常。

docs/project-memory/shared-memory/development-workflow.md

@@ -96,6 +96,10 @@ SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.m
 
 ## Gitea CI 依赖闭合
 
-AGC Rust 两条 lane、crates、smoke、Backend 和桌面壳测试使用镜像内可信 sccache 对象快照；Native shell release step 显式清空双 wrapper，前端/repository checks 不启用。维护者通过 `scripts/build-gitea-rust-cache.sh` 从远端 master 在限额、无宿主挂载的临时容器中按实际 cwd/profile/目标预热全部测试组，仅编译、不执行测试/应用；后端 workspace 与 spacetime-module 保持独立，AGC 的三个 cwd 入口之间清理预热 target，防止 fresh 判断漏产缓存键。最终镜像只追加 sccache、对象和来源元数据，不包含源码或 target。容量上限 4 GiB，不替代宿主旧镜像/归档清理。PR 只写当前容器层、不回传，不开放 Docker API/发布权限；继续禁用 incremental。`ci-rust-cache.sh` 在快照缺失、工具链不符或 wrapper 探测失败时直接编译，并隔离远程缓存配置和 daemon。分片日志记录编译耗时，收尾输出命中统计；两个 lane 的测试和前置检查不同，耗时差不是严格 A/B。线上存在活跃 CI 时不得重启 runner 或切换标签；全组启用前须刷新完整快照并逐组验证，详见开发运维文档。
+Gitea Rust 缓存自动维护由宿主 `genarrative-ci-cache.timer` 收集同一 master push run 六个 Rust job 的原生 V4 缓存产物，不重复执行 Cargo 预热。只传本轮新 key，命中对象只传使用时间；宿主与真实来源镜像对象合并、去重、按新近使用时间裁剪到 4 GiB，从无对象缓存基础镜像重新组装。源 run 不要求全绿，但取消、缺组、旧 attempt、未完成上传或混用来源镜像不得采用。网关暂停新 FetchTask、在途领取结束、持久化任务账本清空且内层活动容器为空才切换，不打断运行中的 CI。首次接入/升级网关需空闲窗口；Token 只需普通仓库 `write:repository`，不查管理员 API。候选装载后清理已收集 artifact，遗留项保留 7 天；真实 master CI 验证后才清理旧镜像，保留当前、一个回滚版、基础镜像及容器引用。部署入口见 `deploy/container/README.md`，合并代码不等于服务启用。
+
+修改 Gitea workflow 的 job 显示名称、ID 或缓存导出组时，必须同步维护器的 `JOBS` / `RUST_JOB_IDS`；`test_gitea_cache_maintenance.py` 直接对照实际 workflow 检查全集和导出映射，避免自动刷新或镜像验收因名单漂移长期等待。维护器 `Api.request` 的 `method` 是必填关键字参数，GET 也必须显式指定，不根据 body 推断请求方法。
+
+AGC Rust 两条 lane、crates、smoke、Backend 和桌面壳测试使用镜像内可信 sccache 对象快照；Native shell release step 显式清空双 wrapper，前端/repository checks 不启用。仅首次人工 bootstrap 时，维护者通过 `scripts/build-gitea-rust-cache.sh` 从远端 master 在限额、无宿主挂载的临时容器中按实际 cwd/profile/目标预热全部测试组，仅编译、不执行测试/应用；后端 workspace 与 spacetime-module 保持独立，AGC 的三个 cwd 入口之间清理预热 target，防止 fresh 判断漏产缓存键。最终镜像只追加 sccache、对象和来源元数据，不包含源码或 target。容量上限 4 GiB，不替代宿主旧镜像/归档清理。PR 只写当前容器层、不回传，不开放 Docker API/发布权限；继续禁用 incremental。`ci-rust-cache.sh` 在快照缺失、工具链不符或 wrapper 探测失败时直接编译，并隔离远程缓存配置和 daemon。分片日志记录编译耗时，收尾输出命中统计；两个 lane 的测试和前置检查不同，耗时差不是严格 A/B。线上存在活跃 CI 时不得重启 runner 或切换标签；全组启用前须刷新完整快照并逐组验证，详见开发运维文档。
 
 `.gitea/workflows/project-ci.yml` 的客户端门禁拆成 lane 与功能 job，每个 job 只预热自己会构建的那几份依赖：`AI game creator shell Rust lane 1/2`、`lane 2/2` 各自预取一次 AGC 壳 manifest，并顺序运行两片 Rust bin 单测；`AI game creator shell Rust smoke` 同样只预取 AGC 壳 manifest（`agent-run` smoke 会用 `src-tauri/Cargo.toml` spawn `cargo run`），`AI game creator shell Rust crates` 预取 `server-rs/Cargo.toml` 与独立 crate，`Native shell tests` 预取桌面壳与 AGC 壳 manifest，`AI game creator shell web tests` 不触碰 Cargo，不预热。两条 Rust lane、smoke job 与 crates job 只用 cargo 与 node 内建模块，因此不执行 `npm ci`。两个被 `server-rs/Cargo.toml` 排除、且没有提交 `Cargo.lock` 的独立 crate（`agent-runtime-core`、`agent-runtime-orchestration`）只能在 `AI game creator shell Rust crates` 里用不带锁标志的 fetch。AGC 壳的 bin target 单测（约 2466 条）由 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs` 编译后按 `--list` 名单分 4 片：每次分片调用用 `--shard-index=<i>` 只跑自己那片，片内保持 `--test-threads=1` 并使用独立 `TMPDIR`；两条 lane 之间并发，lane 内顺序运行两片，避免重复依赖预热和同一容器内多进程争抢。不要改回「一个 job 内多进程并行这几片」——同一容器里它们会争抢共享 `HOME`、target 目录与固定临时路径，实测比整套串行还慢。每个分片调用都会自校验「片并集等于全集且互斥」，因此改分片规则不会静默漏跑。Backend host workspace tests 使用 `cargo test --locked --workspace --exclude spacetime-module --no-fail-fast`，避免 `spacetime-module` 的 `spacetime-types` feature 统一污染普通领域 crate 的 host 测试；随后单独执行 `cargo test --locked -p spacetime-module --no-fail-fast`，由 `spacetime-module/src/active.rs` 在 host 测试构建期间提供仅测试期的 SpacetimeDB ABI 链接支持，使该 crate 的纯单元测试也纳入 Backend 门禁。`spacetime-module` 的 reducer / procedure 运行时行为仍必须通过真实 SpacetimeDB runtime/integration harness 验证，host 链接支持不得被当作运行时替身。Backend 另外执行 `cargo check --locked -p spacetime-module` 验证模块源码。AGC 壳检查还会运行 `platform-llm` 与 `shared-contracts` 的 server-rs workspace 测试，这些命令以及 AGC 壳测试必须带 `--locked`，避免在测试阶段重新解析 registry index；锁文件发生变化时应先更新受信任 CI 镜像缓存，再重跑门禁。

docs/project-memory/shared-memory/pitfalls.md

@@ -5909,6 +5909,56 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **验证**：修复后同一台机器、同一路径下 35 秒内新增 `Maximum update depth` **0 条**，renderer 工作集 **254 MB**（修复前 4.2–4.4 GB）；`apps/ai-game-creator-shell/tests/directActiveTurns.test.tsx` 断言轮询返回值不变时快照引用不变。
 - **关联**：`apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx`、`apps/ai-game-creator-shell/src/features/agent-runtime/directActiveTurns.ts`、`apps/ai-game-creator-shell/src/components/WindowChrome.tsx`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`。
 
+## 2026-09-22 自动合并"无冲突"也可能静默拼坏 CSS 分组选择器
+
+- **现象**：合并 master 时 git 报告 0 冲突，但 `apps/ai-game-creator-shell/src/styles.css` 里新加的头条规则被并进了 master 策划态分组选择器的中间——`.game-workbench-layout--design .project-chat-topbar-status,` 后面直接跟了别的选择器，策划态的 `font-size` / `color` 等声明整块丢失；类型检查与多数用例都不受影响，只有 `chatDialogFrameLayout` 这类 CSS 级联用例报"缺少生效声明"。
+- **原因**：双方在同一分组选择器附近各自插入规则时，hunk 可以"兼容"地拼在一起，git 不会报冲突，但选择器列表被拆散。
+- **处理**：改完 CSS 后按 master 原文重建分组规则、把新增规则独立成块；顺手删掉重复规则时要用带上下文的精确片段，避免删到分组选择器的第二个选择器。
+- **验证**：`npx vitest run apps/ai-game-creator-shell/tests/chatDialogFrameLayout.test.ts`（12 用例）与全量 `npm test` 通过。
+
+## 2026-09-22 合并 master 时“双方保留”不是通用解法
+
+- **现象**：把分支与 master 的同一批冲突统一按“ours + theirs 依次保留”处理后，`apps/admin-web/src/api/adminApiTypes.ts`、`api/adminApiClient.ts`、`app/adminRoutes.test.ts` 都出现语法/结构错误（接口少闭合、函数体被截断、用例少 `});`）。prettier 能通过、vitest 里被转译的纯类型文件也不报错，只有 `tsc`（admin-web typecheck）与随后单文件跑测试才暴露。
+- **原因**：冲突块可能切断一个语法结构（接口、函数、`test(...)` 调用），而双方各自的块只是在“同一位置添加内容”，拼起来会丢闭合；类型文件在 vitest 里被 esbuild 直接剥离类型，不会校验。
+- **处理**：冲突若落在语法结构内部，按“以某一侧为完整骨架、把另一侧的新增内容插到正确位置”重建，而不是简单拼接；重建后必须跑 `tsc`（含 `npm run admin-web:typecheck`）并对改动文件单独跑一次 vitest，别只看全量测试是否绿。
+- **验证**：合并后 admin-web 23 个测试文件 212 用例全绿、两端 typecheck 通过。
+
+## 2026-09-20 复用注册端口段时可能连到别的 worktree 的 SpacetimeDB
+
+- **现象**：在 `/data/dsk/Genarrative` 跑 `npm run dev:api-server` 后，日志显示端口段 `10000-10099 (dsk)`、spacetime `http://127.0.0.1:10002`，但 api-server 反复报 `ws://127.0.0.1:10002/v1/database/xushi-p4wfr/subscribe` 返回 `HTTP error: 404 Not Found`，且始终不响应 `/healthz`。
+- **原因**：该端口段是**按用户**登记的，同一用户的其他 worktree 实例已占用 `10002`；启动器只探测到端口被占用就按"已复用"继续，api-server 于是连到了另一份 data-dir 的 standalone，那里没有当前 database，发布步骤也没有落到这个实例上。api-server 在启动恢复阶段会一直重试，**accept 了连接但不返回任何响应**，所以 `curl` 表现为超时而不是连接拒绝。
+- **处理（现行口径）**：核对 `ss -ltnp | grep :10002` 的进程与 `--data-dir` 是否属于当前仓库；不属于就换用空闲端口段（`GENARRATIVE_DEV_PORT_RANGE` / `--port-range`）或先停掉确认无用的实例，不要把 404 当作 schema 缺失去改代码。排查"健康检查通过但接口 404"时不要只跑 `/healthz`。
+- **关联**：`scripts/dev.mjs`、`scripts/dev-stack-port-utils.mjs`、`/var/tmp/genarrative-dev-port-ranges/registry.json`、[`.codex/skills/genarrative-dev-stack-port-routing/SKILL.md`](../../../.codex/skills/genarrative-dev-stack-port-routing/SKILL.md)。
+
+## 2026-09-20 新增 API 命名空间在本地返回 404：Vite 代理是前缀白名单
+
+- **现象**：api-server 上 `GET /api/game-distribution/games` 直连返回 200，但浏览器里 `http://127.0.0.1:<web>/games` 报 `404`，页面显示「读取游戏目录失败」。同一 URL 换成 `curl` 直连后端却正常。
+- **原因**：`vite.config.ts` 的 `server.proxy` 是**逐个前缀白名单**（`/api/auth`、`/api/profile`、`/api/runtime`、`/api/editor`、`/api/assets`、`/api/llm`、`/api/ws`），没有兜底 `/api/`。未登记的新命名空间不会转发到 Rust 后端，而是回退到 SPA 静态资源，前端再按 JSON 解析就失败。生产 nginx 走的是通用 `location ^~ /api/`，所以症状只出现在本地 dev。
+- **处理（现行口径）**：新增任何 `/api/<namespace>` 时，同一次变更里补 `vite.config.ts` 代理项和 `src/config/viteProxyConfig.test.ts` 断言；`src/config/**` 已加入 `vitest.config.ts` 的 include，漏测会直接红。注意该测试文件里可能残留已退役前缀（例如已退役的 `/api/creation-entry`）的断言，退役命名空间按「四不写」直接删断言，不要为它补代理。
+- **关联**：`vite.config.ts`、`src/config/viteProxyConfig.test.ts`、`vitest.config.ts`、`server-rs/crates/api-server/src/app.rs`、`deploy/nginx/genarrative.conf`。
+
+## 2026-09-20 发行网关用 CORP same-origin 会让沙箱内游戏加载不了自己的脚本
+
+- **现象**：平台游玩页的 iframe 明明 `onLoad` 了（加载遮罩消失、`game-player-frame--ready`），但控制台出现 `net::ERR_BLOCKED_BY_RESPONSE.NotSameOrigin … /releases/<gameId>/assets/app.js`，游戏内的脚本从未执行；直接在新标签页打开同一个 `index.html` 却一切正常，很容易误判成「已经能玩」。
+- **原因**：按安全合同 iframe 必须只用 `sandbox="allow-scripts"`（禁止 `allow-same-origin`），文档因此是不透明来源（opaque origin）。此时它对同包资源的请求不再与网关同源，而响应上的 `Cross-Origin-Resource-Policy: same-origin` 会把请求判为跨来源并拦下；ES modules 还会额外走 CORS，需要 `Access-Control-Allow-Origin`。
+- **处理（现行口径）**：发行网关的公开静态响应使用 `Cross-Origin-Resource-Policy: cross-origin` 与不带 credentials 的 `Access-Control-Allow-Origin: *`，继续保留 `X-Content-Type-Options: nosniff`、内容类型白名单、HTML 最小权限 CSP 和「带 Cookie 一律 403」。这些都是公开静态文件，放宽 CORP/CORS 不暴露凭据；容器隔离靠沙箱、CSP 与独立来源，不靠 CORP。
+- **验证方式**：不要只用 `onLoad` 判断可玩。要在真实浏览器里点「开始游戏」，确认控制台没有 `ERR_BLOCKED_BY_RESPONSE`/CSP 报错，并核对 api-server 访问日志里该版本资源的 `http.response.status_code=200`。
+- **关联**：`server-rs/crates/api-server/src/modules/game_distribution.rs`（`release_asset_response`）、`src/components/game-distribution/GamePlayPage.tsx`、[`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`](../../【玩法创作】平台入口与玩法链路-2026-05-15.md)。
+
+## 2026-09-20 在 jsdom 里把 AGC 发布接到真实后端：Blob 没有 arrayBuffer，且跨 realm BodyInit 会被 undici 拒绝
+
+- **现象**：给 AGC 的 `publishLocalProjectGame` 写“默认跳过”的真实后端集成测试时，创建游戏、创建版本都成功，只有上传 ZIP 报“无法连接登录服务”（`networkError: true`），服务端访问日志里也没有这次上传。
+- **原因**：测试跑在 jsdom 环境，`fetch` 是 Node(undici)，但请求体是 jsdom 的 `Blob`：① 该 jsdom 版本的 `Blob` 没有 `arrayBuffer()`（`typeof blob.arrayBuffer === 'undefined'`），直接调用会抛异常；② 即便拿到字节，jsdom realm 的 `ArrayBuffer`/`Uint8Array` 也不是 undici 认得的 `BodyInit`。
+- **处理（现行口径）**：桥接层用 `FileReader.readAsArrayBuffer` 读 jsdom Blob（有 `arrayBuffer` 时才走它），再用 `Buffer.from(new Uint8Array(...))` 复制成 Node 侧 Buffer 交给 undici。参考 `apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts`。
+- **关联**：`apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts`、`apps/ai-game-creator-shell/src/services/clientHttp.ts`。
+
+## 2026-09-20 AGC 导出后自动弹发布面板：焦点陷阱会吞掉模态之外的点击，既有导出快捷操作用例变红
+
+- **现象**：给 AGC 加「导出试玩包后自动打开发布到游戏广场面板」后，`appSurface.test.ts` 的「预览快捷操作：导出确认、取消与包列表」变红——期望点消息上的「显示目录」把 `/open-project` 填进输入框，实际输入框仍是空。把发布面板的自动打开去掉，或用例先关掉面板，就恢复绿色。
+- **原因**：同目录的 `ThemedModal` 用 `createPortal` + `focus-trap-react` 渲染模态。焦点陷阱存在时，模态之外的 `click` 不会触达 React 的处理器（实测：临时把 `FocusTrap` 换成普通 `div`、其余不动，同一个被模态遮住的按钮点击立刻恢复生效），所以自动化里“点模态背后的按钮”不会报错，只是静默无效。
+- **处理（现行口径）**：① 产品行为保留“导出成功后自动打开面板”（一键发布入口），但受影响的用例必须先用 `findByRole('dialog', { name: '发布到游戏广场' })` 断言面板出现、点「关闭发布面板」再继续后续会话操作；② 给这类“新增自动弹窗”改流程时，先跑一遍相关 `appSurface` 用例，避免只跑新增用例；③ 排查同类“点了没反应”时，先看当前是否有焦点陷阱模态打开，而不是先怀疑事件绑定或状态。
+- **关联**：`apps/ai-game-creator-shell/src/App.tsx`（`setPublishPanelOpen(true)`）、`apps/ai-game-creator-shell/src/components/modal/ThemedModal.tsx`、`apps/ai-game-creator-shell/src/components/game-distribution/GameDistributionPublishPanel.tsx`、`apps/ai-game-creator-shell/tests/appSurface/project-preview/preview-shortcuts/assert-project-tools-and-preview.ts`。
+
 ## 2026-09-21 受控 Lexical 输入区的回写用被动 effect：滞后渲染的 props 会把用户草稿清空
 
 - **现象**：DirectProject 输入盒里粘贴（或连续输入）长文本，提交时 `chat_with_game_creator_direct_codex` 根本没发出去，界面停在空输入盒；`chat-composer` 用例里表现为「队列/终止/语音追加」五条一起红，但手工操作只在快速输入后偶发。
@@ -5962,5 +6012,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 处理：预热使用已核实的 Gitea 路径 `/workspace/GenarrativeAI/Genarrative`，并与分片运行器一样从 AGC `src-tauri` 启动 Cargo；保存 `workspace.txt`，路径不符时回退直接编译。wrapper 放在容器内固定路径，daemon 状态与 Unix socket 仍使用随机私有目录；预热环境与 workflow 的 Cargo 环境由定向契约测试核对。不要为命中率随意增加 `RUSTFLAGS`、改写源码路径或恢复共享可写 target。
 - 验证：相同源码、资源上限和独立干净 target 下分别记录无缓存、冷缓存、热缓存的编译耗时和 hit/miss；只有真实热命中有净收益才切换候选镜像。PR 的写入始终留在 job 容器层，公共快照仍由可信维护流程生成。
 - 统计：job 私有 daemon 设置 `SCCACHE_IDLE_TIMEOUT=0`，由 `report` 显式停止；最终测试 bin 的不可缓存编译或测试可能超过一分钟，短 idle timeout 会让 daemon 提前退出，结尾查询启动新 daemon 后误报零次请求。容器销毁仍会回收该 job 的全部进程。
-- 磁盘：快照构建拒绝含 `/opt/genarrative-ci/rust-cache` 的基础镜像，始终从无对象缓存的镜像重建；容器内删除旧对象不能释放 Docker 底层。对象缓存容量上限不涵盖宿主旧镜像及导出归档，切换验证后按运维文档人工保留当前版和一个回滚版，同时保护运行中 CI 使用的镜像。
+- 磁盘：快照构建拒绝含 `/opt/genarrative-ci/rust-cache` 的基础镜像，始终从无对象缓存的镜像重建；容器内删除旧对象不能释放 Docker 底层。对象缓存容量上限不涵盖宿主旧镜像及导出归档。自动维护只回收自己预先登记的 Image ID/tag 和专属归档，保留当前、一个回滚版、基础镜像及所有容器引用；内层按 ID 导入的镜像可能没有 tag，不能只按 tag 判断已清理。接管前历史试验版本仍需人工确认。
+- CI 产物清理：Gitea 1.26.4 的仓库 REST 仅列出 finalized/expired V4 artifact，内置到期清理不回收上传中断的 tmp-upload 分块。缓存上传块须带专属标识，宿主只清理目标仓库已结束且超过 7 天的 master run 中同样过期的自有普通文件，未知文件/符号链接保护，不改数据库或全局 prune。Artifact.workflow_run 仅含 ID/SHA，判断过期产物所属事件和状态须再读 run API，不能当作完整 run 使用。
+- 自动切换：Gitea 1.26.4 的 disabled 检查与 FetchTask 事务不原子，Runner 客户端超时不能证明服务端回滚，容器暂时为空也不能证明没有已领取任务。网关必须解析实际 Connect Protobuf/gzip，转发 FetchTask 结果前持久化任务 ID，仅在最终日志及执行清理后的最终 UpdateTask 确认后清账；取消响应不能提前释放。暂停新领取、在途为零、账本为零且内层活动容器为空才可切换，无需全局 Runner admin API。未知协议/响应或崩溃遗留标记停止切换；旧网关缺 active_tasks 不能默认零。首次接入与账本升级须空闲窗口。.runner 的 mtime 不证明地址已加载，应核验真实 FetchTask 来源及本次容器启动时间。
 - 扩展：预热所有 Rust 测试组时保留各自 cwd、profile、features 和锁策略；同一临时 target 的 Cargo fresh 不代表不同 cwd 都已生成缓存键，AGC 提示词契约、分片和 smoke 切换入口前清理预热 target。不要把 workspace 与 spacetime-module 合并成一次编译；Native shell release step 清空双 wrapper，避免将测试缓存扩展成发布缓存。当前 sccache 0.18.0 的 READ_ONLY 在 miss 后仍打包产物并产生 cache write error，不适合用来承诺“未命中无开销”。

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -658,6 +658,33 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 - 2026-09-05 修订：`/api/llm/responses` 与 `/api/llm/chat/completions` 仍在 Router provisioning 前用钱包总余额阻止零余额账号创建或续期；解析凭据后、上游调用前再执行累计额度同步，以扣除退款占用后的剩余可消费余额为准。余额为 `0` 时返回 `409 MUD_POINTS_INSUFFICIENT`；余额或额度同步失败时失败关闭。上游已成功时，后置同步失败只记录错误并留待下次调用前补结算，不把成功模型响应改写为失败。
 - Windows 私有文件准备：AGC 自有 AppData、凭据目录和 `.agent` 运行态继续使用 managed 范围；用户通过原生选择器明确选中的项目根或文件，若 owner/DACL 仅因权限不足无法读取，则由一次性 UAC helper 在严格复核普通文件/目录、非 reparse/symlink、路径类型和目标 TokenUser 后接管并收紧为当前用户私有 DACL。项目放在当前 profile 之外（例如其他磁盘）不再因为路径位置被拒绝；未经过原生选择器或 AGC 项目根入口的内部路径仍不获得任意提权资格。
 
+### `game_distribution_game`
+
+- Rust 结构体：`GameDistributionGame`
+- 源码：`server-rs/crates/spacetime-module/src/game_distribution.rs`
+- 用途：游戏分发稳定身份与公开版本指针。保存 owner、标题/简介/分类资料、设备与输入声明、`publication_revision`、当前 `active_version_id`、可见性和游玩计数；标签与输入模式按版本化 JSON 保存，展示资料由 `api-server` 通过 `spacetime-client` 归一后返回。
+- 公开素材：游戏行末尾追加可空 `cover_object_key` 与 `screenshots_json`（截图 `{assetId, objectKey}` 数组）；创建游戏时 `api-server` 就复核封面/截图素材存在且属于当前作者（不存在 400、他人素材 403），创建版本时按同一口径再次复核并派生对象键。 发布写入受灰度配置键 `game-distribution:publish` 约束：未配置或 `enabled=false` 默认开放，显式收紧后写入口（创建游戏/版本、确认包、送审、审核通过激活）返回 503 `GAME_DISTRIBUTION_PUBLISH_DISABLED`，读取与安全下架保持可用；同一判据在 `GET /api/runtime/frontend-config` 以 `gameDistributionPublishEnabled` 下发给前端入口，匿名恒为 `false`。只有可见性为 `published` 且存在有效 `active_version_id` 的游戏，其封面/截图素材才在 `/api/assets/read-url` 上获得匿名读授权。
+- 复用规则：末尾可空列 `local_project_id` 保存发布方本地项目标识（AGC 的 `manifest.projectId`）。同一 `owner_user_id` 再次以相同 `local_project_id` 创建游戏时复用既有 `game_id` 并只新增版本，避免“更新”被实现成新建游戏；该字段只是复用提示，不构成所有权或路径凭证，也不能用于跨账号匹配。
+- 索引：`by_game_distribution_game_owner_user_id` 用于作者私有游戏列表；`game_id` 为主键。公开目录只返回 `visibility = published` 且存在有效 `active_version_id` 的投影。
+
+### `game_distribution_version`
+
+- Rust 结构体：`GameDistributionVersion`
+- 源码：`server-rs/crates/spacetime-module/src/game_distribution.rs`
+- 用途：不可变发行版本与真实包确认事实。创建后冻结 `package_sha256`、字节数、文件数、根入口和版本号；后续只推进上传、校验、审核、公开、撤回状态，并记录私有对象键、文件清单、入口 URL、审核者和阶段时间。
+- 索引：`by_game_distribution_version_game_id`、`by_game_distribution_version_owner_user_id`。真实 ZIP 由 `api-server` 校验并写入私有 OSS 后，才通过 facade 确认 `uploaded`；表不保存 ZIP 正文。
+- 冻结资料：版本表末尾追加可空 `metadata_json`，保存创建版本时由 api-server 校验（标题/简介/分类/标签/设备/方向/必需封面/≤6 张截图）并从素材记录派生对象键后的资料快照；`approve_game_distribution_version_and_return` 通过审核时把该快照整体生效到游戏行，因此公开投影展示的始终是“已随版本审核通过”的资料，旧版本（无快照）保持原值。
+- 作者回读投影：版本回读（作者本人）与审核回读（管理员）在版本 payload 上追加 `frozenMetadata`（冻结快照原样 JSON，历史版本为 `null`）。只有公开投影会剥掉素材 ID，作者与管理员拿到 `coverAssetId` / `screenshots[].assetId`，因此作者续发时可以直接复用同一批封面与截图素材，不需要为了沿用封面重新上传一次；素材 ID 缺失（旧版本）时前端必须要求作者重新选择封面，不能用对象键反推素材身份。
+- 撤回与回读：`cancel_game_distribution_version_and_return` 只允许把未参与当前公开投影的版本推进到 `cancelled`，并要求 `expected_publication_revision` 与游戏公开修订号一致；`get_game_distribution_version_and_return` 供管理员按版本 ID 直读。客户端看到的 `recoveryAction` 由 `api-server` 按 `status` 派生，不落表。
+
+### `game_distribution_idempotency_receipt`
+
+- Rust 结构体：`GameDistributionIdempotencyReceipt`
+- 源码：`server-rs/crates/spacetime-module/src/game_distribution.rs`
+- 用途：创建、上传、提交、审核、撤回和下架操作的幂等收据。`owner_user_id + action + idempotency_key` 组合唯一，保存请求摘要、结果 ID、有限结果 JSON、创建/过期时间和完成时间；同 key 不同摘要必须返回冲突，收据不保存凭据或包正文。
+- 索引：owner、game、version 和 `by_game_distribution_receipt_scope` 组合索引；默认保留窗口由服务端清理策略控制。
+- 重放语义：写操作命中既有收据时，procedure 回传 `replayed = true` 并复用收据里的结果 ID，不重复创建游戏、版本或审核结论；同 key 不同请求摘要必须返回冲突。
+
 ### `llm_router_account`
 
 - 当前 AGC Router 需求由 `llm_router_account` 表单独承载：API Key 核心字段、加密凭据、Router 账号元数据、生命周期与 provisioning 状态均在该表；不依赖 `external_api_key`。api-server 每次上游调用都读取权威 `llm_router_account` active/revoked 状态并即时解密当前密文，不做 TTL 凭据缓存，避免任意实例轮换或撤销后继续使用旧 Key。

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -334,16 +334,18 @@ master 日常交付必须禁止直接 push，只允许经 PR 在最近一次 Pro
 
 #### Rust 测试组的隔离编译缓存
 
-每次生成快照必须使用不含对象缓存的原始 CI 基础镜像；构建脚本在拉取源码和预热前拒绝已存在 `/opt/genarrative-ci/rust-cache` 的基础镜像，避免重复叠加不可释放的旧对象层。切换并完成真实 CI 验证后，按 `deploy/container/README.md` 的保留规则人工定向清理旧缓存镜像及归档，保护运行中 CI 使用的版本。
+每次生成快照必须使用不含对象缓存的原始 CI 基础镜像，避免叠加不可释放的旧层。宿主自动维护器 `scripts/maintain-gitea-rust-cache.py` 收集完整 master push CI 的六组 V4 增量产物，复用其真实来源镜像对象并合并去重，总容量 4 GiB，不重复执行 Cargo 预热编译。测试失败可收集，取消、缺组、未完成上传、旧 attempt 或混用来源镜像不可发布。候选校验、导出和装载后删除已收集 artifact，遗留项保留 7 天；切换后通过真实 master CI 才定向清理受管旧镜像/归档，保护当前、一个回滚版、基础镜像及容器引用。
 
 AGC Rust 两条 lane、crates、agent-run smoke、Backend 和 Native shell 的桌面壳测试均启用 sccache。Native shell 的 release build smoke 显式清空两个 wrapper，保持发布构建原有 profile/features 与资源 staging；前端和 repository checks 不启用对象缓存。继续设置 `CARGO_INCREMENTAL=0`，不共享 target、不恢复 Actions 可写缓存。可信快照通过已有固定 Image ID 分发：镜像只增加固定版本的 sccache、编译对象和来源元数据，不包含源码、target 或凭据；容器写时复制层承接本 job 的新增对象，job 删除后丢弃，PR 没有 Docker API 或快照发布权限。该权限边界由 runner 基础设施保证，不能仅用 workflow 的分支条件替代。
 
-维护者在受信任 checkout 中运行 `bash scripts/build-gitea-rust-cache.sh <已验证基础镜像> <候选镜像tag>`。脚本从 origin 获取 master 的确定提交，在无宿主目录挂载、无凭据且有 CPU/内存上限的临时容器中预热各组实际 Cargo 目标，只编译、不执行测试或应用。后端 workspace 仍排除 spacetime-module，再单独预热该模块，禁止为缓存合并 features。AGC 独立 crate 与插件沿用各自 manifest/锁文件策略；未提交锁文件的 crate 仍可能因新版本解析产生 miss。最终镜像从原基础镜像重新组装，只导出 sccache 对象，不提交预热容器。公共快照不接受 PR 上传，也不复用 Jenkins 发布缓存。工具链或系统依赖变化时重新生成快照，缓存命中仍由 sccache 的编译输入校验决定，不能省略 Cargo 构建。
+人工 bootstrap 在没有可消费快照时使用 `bash scripts/build-gitea-rust-cache.sh <已验证基础镜像> <候选镜像tag> [完整master-SHA]`；自动维护不调用它。bootstrap 固定 master 归档，在无宿主挂载、无凭据、有资源限额的容器中只编译预热，不执行测试/应用，Cargo features 和工作目录保持实际 CI 口径。日常更新由 master CI 导出新 key，命中继承对象只传使用时间；PR 不导出、不扫描。宿主验证来源、大小和哈希，不从上传产物执行程序，只从可信来源镜像复制固定 sccache。工具链或基础镜像输入变化时重建无对象缓存基础镜像，缓存工具链必须匹配。公共快照不接受 PR，不复用 Jenkins 发布缓存。
 
 各 Rust job 在编译前执行 `scripts/ci-rust-cache.sh prepare`：检查快照与 rustc 身份，隔离 sccache 配置和 daemon，限时探测真实 wrapper。旧镜像没有快照或探测失败时保留空 wrapper，输出 fallback 原因；缓存故障不得把真实编译/测试失败改成成功，也不允许重跑整个测试组掩盖失败。结束时 `report` 输出命中统计；分片日志单独记录 Cargo 编译耗时。对象缓存上限为 4 GiB，快照构建完成后输出实际体积；最终测试 bin 的链接仍须执行。全组开启时必须生成覆盖全部目标的新快照，不能把旧 AGC 单目标快照当作后端/桌面壳的预热验收。
 
 候选镜像沿用 `gitea-ci-job-image.sh verify/export/load-runner` 验证和装载。现役 CI 正在运行时只允许准备候选镜像，不停止 job、不重启 runner、不切换标签；待确认无运行中的 job 后再按上述镜像更新顺序切换。验收分别记录独立 target 的无缓存、冷缓存和热缓存构建耗时及命中率，并检查失效/故障回退、两容器写入互不影响。未完成真实 CI 验证前不能宣称提速或推广到其它 job。
 
+自动维护首次部署及故障恢复统一见 `deploy/container/README.md`。timer 约每 5 分钟检查，文件锁串行执行，使用专属 clone/状态/归档目录；只管理 Gitea CI 测试镜像，Native shell release smoke 继续清空双 wrapper。凭据只需普通账号 `write:repository`，读取 run/job/日志/产物并定向删除缓存 artifact，不需要管理员权限。切换依赖 FetchTask 暂停与在途屏障、任务持久账本和内层 Docker 空闲；Gitea 显示 cancelled、disabled 或客户端超时都不能证明执行已经结束。网关依据最终日志与执行收尾后的最终任务上报确认释放任务。首次接入/旧网关升级须等待 CI 自然结束的空闲窗口，不在运行中的 CI 上试切；脚本合并不等于服务已部署。
+
 Rust 对象 key 包含编译工作目录。预热必须使用已核实的 Gitea checkout 路径 `/workspace/GenarrativeAI/Genarrative`：后端、独立 crate、插件、桌面壳及提示词契约从仓库根目录启动 Cargo，AGC 分片从 `apps/ai-game-creator-shell/src-tauri` 启动，agent-run smoke 从 `apps/ai-game-creator-shell` 启动。切换 AGC 编译入口前清理该临时容器的 AGC target，防止 Cargo 的 fresh 判断跳过新 cwd 所需对象；CI 各 job 的 target 本来就独立。快照保存 `workspace.txt`，job 根路径不符时直接编译。不要仅设置 `SCCACHE_BASEDIRS` 就假定 Rust 可以跨 cwd 命中，也不为缓存改写 `RUSTFLAGS` 或源码路径语义。固定 sccache `0.18.0` 的基础设施错误码 `2` 会由 wrapper 回退执行本次 rustc；其它退出码原样返回，升级 sccache/Rust 时须复核此约定。
 
 sccache `0.18.0` 还会 hash 大部分 `CARGO_*` 环境变量。因此 wrapper 固定在每个容器自己的 `/opt/genarrative-ci/rust-cache/rustc-wrapper`，prepare 重写 launcher 后才启用；daemon 状态与 socket 仍各自随机隔离。预热同步 workflow 的 `CARGO_INCREMENTAL`、`CARGO_HTTP_MULTIPLEXING`、`CARGO_NET_RETRY` 和 `CARGO_TERM_COLOR`，由现有 CI 契约测试验证一致；新增 Cargo 环境配置时须同步评估 cache key，不能只看快照文件是否存在。
@@ -638,6 +640,52 @@ Nginx 负责站点和反向代理
 Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分
 ```
 
+### 游戏发行来源（发行域名、每游戏 origin 与缓存窗口）
+
+已公开游戏运行在**独立来源**上，与主站来源隔离；这是发行网关（`api-server`）之外唯一需要的边缘配置。
+
+- 配置工件：`deploy/nginx/genarrative-release-origin.conf`。上线前替换域名、通配证书路径与 upstream 端口，并把文件安装到 Nginx 站点目录。
+- 前置资源：`*.games.<域名>` 通配 DNS 指向同一入口，以及覆盖该通配名的 TLS 证书（certbot DNS-01 或等价流程）。
+- 路由约定：`https://<gameId>.games.<域名>/` 是该游戏的入口（子域根路径映射到该游戏的 `index.html`），其余路径按原样映射到 `/api/game-distribution/releases/<gameId>/…`；平台 API、后台、SPA 与上传接口在这个来源上一律 404，命中即证明边缘多代理了命名空间。
+- 会话隔离：发行来源从不使用 Cookie。带 `Cookie` 的请求在边缘直接 403，转发前也会 `proxy_set_header Cookie ""`；发行网关自身同样对带 Cookie 的请求返回 403。
+- 响应头与缓存：`X-Content-Type-Options`、CORP（`cross-origin`）、无凭据 CORS、HTML CSP、内容类型白名单与 `Cache-Control: public, max-age=60, must-revalidate` 都由发行网关设置，边缘不覆盖。换版与下架只改变后端公开投影，因此**最迟 60 秒**内新请求不再拿到旧版本；已经下载到浏览器的脚本无法远程抹除，撤销能力以“停止继续分发”为准。
+- 审核动作：管理员审核通过时填写的 `entryUrl` 必须是该游戏的子域根地址 `https://<gameId>.games.<域名>/`（HTTPS、无凭据、无 query/fragment）；非生产环境仍按现有口径允许 http 回环地址用于本地联调。
+- 门禁与本地联调：
+
+```bash
+# 模板约束 + 发行网关响应头策略交叉检查；本机有 nginx/openssl 时还会渲染一份临时配置跑 nginx -t
+npm run check:release-origin-config
+```
+
+本地想在真实边缘语义下复验时，可以把模板渲染到 `~/data/tmp`（替换 upstream 为本地 api-server 端口、证书换成自签通配证书、监听端口换成高位端口），用 `nginx -c <渲染文件>` 起一个临时实例，再用 `curl -H 'Host: <gameId>.games.example.com'` 验证：根路径 200 `text/html`、`/assets/*` 200、带 Cookie 403、平台 API 路径 404、未知 gameId 404、http 301 到 https。
+
+#### 游戏分发可观测事件
+
+`api-server` 的游戏分发日志都带 `request_id`（与访问日志同一值）和 `operation`，可直接按游戏/版本关联；不记录 Token、signed URL、文件内容或本地路径。
+
+```bash
+# 上传与审核链路
+journalctl -u genarrative-api -o cat | grep -E 'operation="(package_confirmed|package_rejected|version_submitted|version_cancelled|review_decided|review_backlog_listed|game_unpublished|game_suspended)"'
+# 发布开关是否在拦流量
+journalctl -u genarrative-api -o cat | grep -E 'operation="publish_switch_(blocked|unavailable)"'
+# 发行网关 4xx 原因（需要 debug 级日志）
+journalctl -u genarrative-api -o cat | grep 'operation="release_rejected"'
+```
+
+关键字段：`package_confirmed.elapsed_ms` 与 `package_bytes`（校验耗时/容量）、`package_rejected.code|reason`（失败原因）、`review_backlog_listed.pending_versions`（审核积压）、`game_unpublished|game_suspended.publication_revision`（撤销传播时可与详情回读对账）。
+
+#### 发布开关（关闭投稿、保在线）
+
+发布事故或回滚窗口里用 `game-distribution:publish` 灰度开关控制写入，不需要改代码或重启：
+
+- 开关位置：后台「灰度发布配置」（`GET/PUT /admin/api/feature-gates`），`gateKey = game-distribution:publish`。
+- 语义：没有该 gate 行或 `enabled=false` 表示**默认开放**；`enabled=true` 时只有 `allowUserIds` / `allowUserTags` / `rolloutPercent` 命中的作者能发布，`rolloutPercent=0` 且无白名单即**全部关闭**（等价紧急关闭投稿）。
+- 关闭范围：创建游戏、创建版本、上传包、送审、撤回、作者下架，以及管理员**批准**（新版本激活）都返回 `503 GAME_DISTRIBUTION_PUBLISH_DISABLED`。
+- 始终可用：目录、详情、版本回读、发行网关（已公开游戏继续游玩）、`/my-games`、审核队列读取、**拒绝审核**与管理员**安全下架**。
+- 失败姿态：开关状态读取失败时按关闭处理，避免绕过运营刚下的收紧动作；本地排障时确认 SpacetimeDB 正常后再判断业务是否被误伤。
+
+上线前仍需确认的外部状态：通配 DNS 与证书已生效、upstream 端口与 `genarrative-api.service` 一致、若前面还有 CDN 需把 TTL 收敛到不超过上述 60 秒窗口，并跑一次真实域名下的“审核通过 → 游玩 → 换版 → 下架”链路。
+
 ### 生产健康巡检
 
 `Genarrative-Server-Provision` 会安装并启用 `genarrative-health-patrol.timer`，默认每 5 分钟运行一次 `genarrative-health-patrol.service`。巡检脚本随 API release 归档到 `/opt/genarrative/current/scripts/ops/production-health-patrol.mjs`，只读检查：

docs/【玩法创作】平台入口与玩法链路-2026-05-15.md

@@ -50,3 +50,129 @@
 
 - 供应商密钥、Token、Cookie 和本地私密路径不得进入前端或文档示例。
 - 生成或导入资产必须经过后端鉴权、对象确认和换签读取；上传失败或换签失败时显示可操作错误，不回退为公开裸路径。
+
+## AGC 游戏分发与在线游玩合同
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 0.2 |
+| Status | proposed（待评审，未上线） |
+| Date | 2026-09-18 |
+| 适用边界 | 本节是新增业务提案；评审与实现验收前，不改变上文现役入口和移动端合同 |
+
+### 交付目标与范围
+
+交付“AGC 一键提交游戏 / 网页上传游戏 ZIP → 后端收取真实发行包 → 校验与人工审核 → 主站发现、详情、游客在线游玩 → 更新与下架”的完整闭环。验收必须使用真实上传、真实存储、真实审核状态和隔离发行域名；静态演示卡片、metadata-only 请求或前端本地发布状态不能作为完成证据。
+
+首版支持可以离线运行的静态 Web 游戏：HTML、JavaScript、CSS、JSON 与图片、字体、音视频。AGC 首先支持现有 npm/Vite Web 工程；网页入口允许上传符合相同包合同的 ZIP，不以游戏引擎名称限制普通静态产物。Godot/Cocos 工程源码、原生可执行文件、Wasm、服务端进程、外部 API、多人联机、云存档和跨版本存档迁移不在首版内。暂不做评分、评论、关注、榜单、推荐算法、交易和创作者收入。
+
+### 入口与产品体验
+
+- 提议网页根路径 `/` 进入 `/games`；桌面一级导航为“游戏 / 创作 / 项目 / 我的”，移动端为“游戏 / 我的”。图片创作及项目编辑仍遵守原有桌面端边界，移动端不再以仅支持作品展示的欢迎遮罩阻断游戏浏览和游玩。该变更仅在本节通过评审并完成验收后生效。
+- 游戏目录 `/games`、详情 `/games/detail?id=<gameId>`、游玩 `/games/play?id=<gameId>`；作者管理 `/games/mine` 只列当前账号的游戏和发行状态。平台壳及既有账号页提供入口，不建立第二套账号或作品系统。
+- 目录使用重点推荐位和紧凑卡片网格，首版推荐位只消费后台明确设置且已公开的游戏；其余列表按发布时间排列。支持关键词、分类与设备筛选，筛选写入 URL，返回列表恢复筛选和滚动位置；没有内容时展示真实空态。
+- 详情的主动作是“立即玩”，展示封面、标题、作者、短简介、设备标识、截图和简短操作方式；不虚构评分、玩家数、排名和收藏状态。游客浏览详情及启动游戏均无需登录；上传、更新、撤回和作者管理需要当前平台登录态。
+- 游玩页先展示封面与开始按钮，用户点击后加载游戏，避免列表自动加载多个 iframe 或自动播音；提供加载、超时、重试、返回详情和全屏。iframe 的 `load` 事件只表示文档已加载，不宣称已经通过运行验证；首版不把 iframe 消息当平台业务状态。
+- 移动端优先采用全宽内容、底部主要动作、至少 44px 点击区域，覆盖安全区、横竖屏和键盘焦点。游戏声明仅支持桌面时，手机详情保留可浏览内容并禁用开始，明确显示“请在电脑上游玩”；横屏游戏提供旋转提示，但不能把系统方向锁定成功作为启动前提。
+- 视觉延续当前暖色主题 token、米白/浅暖背景、橙色主动作与现有字体；通过封面占比、留白、圆角和清晰状态层级现代化呈现，不另建配色系统。通用卡片动作、弹窗、上传、状态反馈、空态与媒体预览优先复用共享组件。发布打开独立弹窗/抽屉，不在当前页面末尾追加表单；技术信息仅在失败诊断或确需用户决策时展示。
+
+### 参考产品验证
+
+本次交互取已能核验的公开模式：TapTap 的详情主动作和阶段化审核发布（[详情示例](https://www.taptap.cn/app/29648)、[开发者创建游戏](https://developer.taptap.cn/docs/store/release/publish/create-game/)）；Astrocade 的精选/趋势分区、卡片播放量和作者入口（[首页](https://www.astrocade.com/)、[作者页](https://www.astrocade.com/creators)）；4399 的“无需下载，点开即玩”、适配设备与包体提示（[在线玩](https://h.4399.com/)、[上传中心](https://www.4399.com/gameupload.htm)）；7k7k 的分类、玩法说明、加载提示和玩家上传声明（[首页](https://www.7k7k.com/)、[上传页](https://www.7k7k.com/html/upload.htm)）。星匣仅确认其公开定位为 AI 一键生成与即点即玩，页面正文为动态应用，未把无法核验的栏目当作合同依据；限定调研内未找到可确认官方域名的“造梦工坊”，不据此推断产品行为。
+
+### 真实发行包与资料合同
+
+1. AGC 发布取当前 npm 工程已成功构建的 `dist/` 内容，重新检查入口和实际字节；ZIP 内部必须把 `dist/index.html` 归一化为根 `index.html`，其余路径相对发行根保持不变。不得上传整个项目、源码快照或仅发送本地路径。网页 ZIP 同样要求根 `index.html`，不猜测并自动剥离多层目录。
+2. 所有运行依赖都必须在发行包内。资源 URL 使用与发行版本目录兼容的相对地址；前导 `/assets`、本地文件 URL、外部脚本/样式/媒体/字体地址均不属于可接受发行合同。客户端给出可操作错误，服务器仍独立校验；静态校验不能代替运行时 CSP 阻断。
+3. 建议首版限额：压缩包 100 MiB、展开总量 250 MiB、单文件 64 MiB、最多 10,000 个文件、展开/压缩比不超过 100。服务端拒绝加密 ZIP、重复或大小写冲突路径、绝对路径、`..`、符号链接/重解析点、设备文件和嵌套压缩包；拒绝 `.agent`、版本控制目录、`node_modules`、凭据文件与源码映射文件。超限返回明确错误，不截断后继续发布。
+4. 提交声明 ZIP 的 SHA-256 与字节数，服务端对收到的真实 ZIP 重新计算，再对展开文件建立相对路径、字节数和 SHA-256 清单。摘要不一致、缺文件或入口损坏时停止；只有 metadata 而没有已确认完整对象的提交必须失败。
+5. 游戏资料随发行版本冻结：标题 2–40 字、短简介不超过 120 字、详细介绍不超过 2,000 字、一个分类、最多 5 个标签（每个不超过 20 字）、必需封面、最多 6 张截图、操作方式不超过 240 字。分类首版为休闲、益智、动作、冒险、模拟、策略、其他；封面/截图复用平台图片上传与归属校验，不接受任意外链作为审核图片。发布入口按灰度下发：后端灰度配置键固定为 `game-distribution:publish`（后台「灰度发布配置」可改，支持 `enabled` / `rolloutPercent` / `allowUserIds` / `allowUserTags`）。未配置该键、或 `enabled=false` 时对已登录作者默认开放；显式 `enabled=true` 后只有白名单或灰度命中的作者拿到开放状态，匿名恒为不开放。发布入口的开放状态随 `/api/runtime/frontend-config` 的 `gameDistributionPublishEnabled` 下发，网页广场/我的游戏入口与 AGC 聊天头「发布到游戏广场」按钮据此显示或隐藏；写入口仍独立校验，收紧期间提交返回 503 与可读文案，读接口、目录、详情、发行网关与安全下架不受影响。作者续发时按版本冻结快照回填封面与截图并复用同一批素材；公开投影只暴露对象键，素材 ID 只在作者与管理员回读时返回，快照里缺素材 ID 的旧版本必须要求作者重新选择封面。
+6. `supportedDevices` 至少包含 `desktop` 或 `mobile`；`inputModes` 来自 `keyboard`、`mouse`、`touch`；声明移动端必须包含 `touch`。`orientation` 为 `landscape`、`portrait` 或 `responsive`。这些是待人工复核的作者声明，目录只显示已经随版本审核通过的值。
+7. 原始 ZIP、未审核展开目录、审核资料均为私有对象；公开版本不暴露源码镜像键、本地路径、访问凭据或私有账号元数据。运行文件只能由发行网关按游戏、版本和文件白名单读取，不能绕过网关访问公开 OSS bucket。
+8. 现役发行网关由 `api-server` 提供：`GET /api/game-distribution/releases/{gameId}/{assetPath}` 只服务当前已公开版本包内的文件，私有 ZIP 与未公开版本不因知道 ID 而可读。响应按扩展名白名单设定内容类型，未知扩展名返回 404；全部响应带 `X-Content-Type-Options: nosniff`、`Cross-Origin-Resource-Policy: cross-origin` 与不带 credentials 的 `Access-Control-Allow-Origin: *`（发行文档运行在 `allow-scripts` 的 opaque origin 沙箱里，`same-origin` 会让游戏自己的脚本被浏览器拦下），HTML 追加最小权限 CSP。带平台 `Cookie` 的请求一律 `403`，避免发行文件被主站同源读取；发行网关必须部署在独立来源。发行包按对象键在进程内做有界缓存，单个超预算包不进入缓存。
+9. 审核通过时必须提交绝对 HTTPS `entryUrl`，且不接受凭据、query 和 fragment；服务端不根据请求 Host 或本地路径拼默认发行地址，避免把内网地址或主站来源写进公开投影。 非生产环境额外允许 http 回环地址（`127.0.0.1` / `localhost` / `[::1]`），口径与前端 `normalizeGameEntryUrl` 一致，便于本地在没有 TLS 的情况下验证内嵌游玩；生产环境只接受 HTTPS。
+
+### 身份、状态、审核与更新
+
+- `gameId` 是服务端分配的稳定游戏身份；`ownerUserId` 只从当前认证主体派生。AGC 的本地 `projectId` 只能作为作者名下的关联提示，不能证明云端游戏所有权。网页上传和 AGC 发布使用相同游戏、版本与上传记录，不建立两套发行系统。
+- 同一作者用相同 `localProjectId` 再次发布时复用既有 `gameId` 并只新增版本；游戏身份、版本号和服务端校验都不依赖客户端传来的路径或 ID 可信度。缺少 `localProjectId` 的旧客户端仍可发布，但会被视为新建游戏。
+- 每次发行分配唯一 `versionId` 与游戏内递增 `versionNumber`。版本的游戏归属、包摘要、已确认字节和送审资料冻结后不可变；改包或改送审资料必须创建新版本。版本状态可以流转，内容不能原地覆盖。
+- 游戏单独保存 `publicationRevision`、`activeVersionId` 和可见性 `unpublished | published | suspended`；正式可见性由服务端持久化事实决定。未通过审核时 `activeVersionId` 为空；`suspended` 是管理员安全下架，作者不能自行解除。
+- 版本状态为 `awaiting_upload → uploaded → validating → pending_review → published`。上传确定失败进入 `upload_failed`，验证失败进入 `validation_failed`，人工拒绝进入 `rejected`；尚未公开版本可以撤回为 `cancelled`，已公开版本可撤销为 `revoked`。已成功上传的相同字节可重新校验；内容改变或审核拒绝后的修改必须新建版本。
+- 首版建议人工审核。审核员检查游戏资料、真实桌面运行、声明移动适配、内容与外部请求被阻断的行为；自动包校验通过只进入 `pending_review`，不自动公开。审核记录保存审核者、目标版本、结论、理由和时间。后台只授权现有管理员身份，不让普通作者调用审核动作。
+- 更新送审时旧 `activeVersionId` 继续服务目录、详情与游玩。审核通过并完成对象可读验证后，一次事务切换当前公开版本和公开资料；新版本上传、校验、审核或对象安装失败均不改变旧版本。
+- 发布页先自动填入可用标题和封面，首次需要确认必需资料，此后复用上次资料；用户一次“提交发布”动作串联校验、上传和送审，并显示真实阶段。等待审核不能显示“已发布”；成功后提供查看详情和复制公开链接。
+
+### 幂等、并发与恢复
+
+- 所有创建、提交、审核、撤销和下架动作携带 `Idempotency-Key`。服务端以认证主体、动作和 key 保存请求摘要与结果；同 key 同请求返回原结果，同 key 不同请求返回 `409 IDEMPOTENCY_CONFLICT`。至少保留 30 天；客户端超出恢复窗口先回读记录，不能把未知结果自动当作失败重发。
+- 同一个版本只能确认一份 ZIP：中断重传仍使用同 `versionId` 和摘要，已确认相同字节直接返回成功，不同摘要返回 409。上传中同版本第二个写入返回 `409 UPLOAD_IN_PROGRESS`；未确认半包不会进入校验。首版整包重传，不宣称支持分片断点续传。
+- 重复提交同一次 AGC 操作不得创建第二个游戏或版本；原生端持久保存操作 ID、目标游戏/版本和 key，网页保存恢复标识并以服务端回读为准。相同 ZIP 用于不同资料修订时允许新版本，不能仅按包摘要吞掉新的发布意图。
+- 公开版本切换、作者下架和管理员审核必须带 `expectedPublicationRevision`，在持久化事务中比较并推进。并发变化返回 `409 PUBLICATION_CONFLICT`；旧送审版本不能在用户已发布更新或下架之后静默覆盖状态。审核员重新查看现状后才能提交新的明确动作。
+- 网络中断或响应丢失后先查询原操作/版本；服务端恢复 `validating` 的在途任务并按版本身份幂等续作，不另建版本。登录失效保留私有草稿和恢复标识，重新登录同账号后继续；换账号不能读取或接管原账号操作。
+
+### HTTP 与持久化边界（拟定）
+
+现役内部命名空间使用 `/api/game-distribution`；除标注为完整后台路径的行外，下表路径都带该前缀。标注「已实现」的路由已在 `api-server` 挂载并有定向测试；本表当前没有待落地路由。公开目录只消费后端投影；所有变更经过现有鉴权、限流和埋点中间件。账号内部 API 不扩展 `/api/external/v1`，后续若对外开放再同步 External OpenAPI。
+
+| 方法与路径 | 身份 | 行为 |
+| --- | --- | --- |
+| `GET /games` | 游客 | **已实现**：关键词与分类筛选，最多 48 项；仅公开可玩版本 |
+| `GET /games/{gameId}` | 游客 | **已实现**：当前公开资料与 `currentVersion.entryUrl`；不可见时 404 |
+| `GET /game-distribution/releases/{gameId}/{assetPath}` | 游客 | **已实现**：发行网关只服务当前已公开版本包内文件，按扩展名白名单设内容类型，未知扩展名 404，带 Cookie 的请求 403；游玩页的入口来自详情投影的 `currentVersion.entryUrl` |
+| `GET /my/games` | 登录作者 | **已实现**：当前账号游戏、最近版本状态与驳回理由；owner 只从认证主体派生 |
+| `POST /games` | 登录作者 | **已实现**：幂等创建游戏身份，尚不公开；带 `localProjectId` 时同一作者复用既有 `gameId` |
+| `POST /games/{gameId}/versions` | owner | **已实现**：创建不可变待上传版本，冻结包摘要/字节数/文件数与资料 |
+| `PUT /versions/{versionId}/package` | owner | **已实现**：接收真实 ZIP、重算摘要与文件清单并写入私有对象；不执行游戏代码 |
+| `GET /versions/{versionId}` | owner/管理员 | **已实现**：回读状态、错误代码、审核结论与服务端 `recoveryAction`；管理员走 `/admin/api/game-distribution/versions/{versionId}`；未知版本与别人的版本都按不可见返回 404 |
+| `POST /versions/{versionId}/submit` | owner | **已实现**：只有已确认完整包可提交，返回 202 并进入 `pending_review` |
+| `POST /versions/{versionId}/cancel` | owner | **已实现**：带 `expectedPublicationRevision` CAS 与 `Idempotency-Key`，只能撤回未参与公开投影的版本；同 key 同请求重放返回 `replayed: true`，摘要不同返回 409 |
+| `POST /games/{gameId}/unpublish` | owner | **已实现**：CAS 关闭公开游戏及其版本入口，不删除审核记录 |
+| `GET /admin/api/game-distribution/reviews` | 管理员 | **已实现**：分页获取待审版本；此行是完整后台路径 |
+| `POST /admin/api/game-distribution/versions/{versionId}/review` | 管理员 | **已实现**：批准需 HTTPS 发行入口并执行公开版本 CAS；拒绝需理由；此行是完整后台路径 |
+| `POST /admin/api/game-distribution/games/{gameId}/suspend` | 管理员 | **已实现**：安全下架整个游戏并撤销发行访问，要求 `expectedPublicationRevision` CAS 与幂等键；后台游戏审核页提供带原因输入与二次确认的入口；此行是完整后台路径 |
+
+除显式 `/admin/api/...` 外，表内路径均相对 `/api/game-distribution`。错误采用现有平台 envelope，覆盖 400 格式错误、401 未登录、403 owner/审核权限错误、404 不可见、409 幂等/状态/并发冲突、413 大小上限、422 包或资料校验失败、429 限流和明确的可重试 5xx；服务端响应不包含存储凭据和本地绝对路径。
+
+领域规则进入 `module-*`，游戏/版本/审核/操作账本和事务进入 `spacetime-module`，访问统一通过 `spacetime-client`，HTTP 与上传编排进入 `api-server`，对象存储副作用复用 `platform-*`，跨端 DTO 同步 Rust `shared-contracts` 与 `packages/shared`。新业务不复用退役玩法表或私有源码快照作为公开事实；实际表字段、索引、受信服务身份及迁移清单在持久化里程碑评审时冻结。已有表若确需加字段，只能末尾追加并给明确默认值；删除/改名/重排/改类型必须另行确认迁移计划。
+
+### 发行域名、沙箱与网络能力
+
+- 发行域名必须与平台使用不同的可注册站点（不同 eTLD+1），不能仅使用 `*.genarrative.world` 的兄弟子域；域名需在部署前确定。每个游戏有独立 HTTPS origin，例如 `https://g-<gameId>.<发行站点>`，不同游戏不能共用 origin；版本固定在 `/releases/<versionId>/index.html`。
+- 主站仅接受服务端配置允许的 HTTPS 发行 host 与发行版本路径，拒绝任意 URL、重定向目标、用户输入 URL、`javascript:` 和 `srcdoc`。发行站点不设置平台 Cookie、不接收平台 Bearer、不挂载主站 API；请求和日志也不得携带平台认证数据。
+- iframe 首版仅使用 `sandbox="allow-scripts"`，全屏通过明确的 iframe 能力授权与用户手势开放。禁止 `allow-same-origin`、顶层导航、弹窗、表单提交、下载、模态对话框、相机、麦克风、剪贴板和地理位置；不提供持久 localStorage/IndexedDB 存档保证，不启用 Service Worker。
+- 网关对所有发行 HTML 强制 CSP：默认拒绝；脚本只允许本游戏 origin 和必要内联脚本，不开放 `unsafe-eval`；样式允许本游戏 origin 与内联样式；图片/字体/音频只允许本游戏静态源及必要 `data:`/`blob:`；`connect-src` 仅为当前游戏静态 origin，`worker-src`、`frame-src`、`object-src`、`form-action` 为 `none`，`base-uri 'none'`，`frame-ancestors` 仅主站明确 origin。不能由包内 meta 放宽响应头策略。
+- 首版允许加载同游戏发行包内 JSON/二进制素材，禁止外部 API、远程分析、广告、第三方 SDK 网络依赖及任意外站 fetch/WebSocket。静态网关不代理任意外部地址。为兼容 opaque sandbox 下的 ES modules，发行静态资源提供不带 credentials 的 CORS；此能力只对获准发行文件生效，不能扩到主站或私有存储。
+- 发行响应固定正确 MIME 与 `X-Content-Type-Options: nosniff`，不把未知扩展名返回为 HTML；ZIP 校验和人工审核不能代替这些运行时隔离措施。真实浏览器验收必须确认 npm/Vite 模块、Phaser 素材加载、音频和触屏在该策略下正常，而外站请求与越权访问被阻断。
+
+### 下架、缓存与运维
+
+- 作者下架或管理员封禁成功后，公开列表、详情和启动 API 立即停止返回游戏；发行网关同步按游戏和版本授权拒绝新请求，原始对象不可绕过网关访问。管理员封禁禁止作者自行重发绕过；解除需管理员明确动作并重新审核。
+- 建议 HTML、公开状态与启动 API 使用 `no-store`；发行静态资源的浏览器与 CDN 有效期均不超过 60 秒，禁止 `stale-while-revalidate`、`stale-if-error` 和发行 Service Worker。下架主动 purge 相关 CDN 键，60 秒作为最大缓存撤销窗口，不把 purge 成功当唯一保障。旧版本被更新替代后，新启动只用当前版；旧游戏已经载入的脚本/资源不承诺远程抹除，用户退出或刷新后按当前授权重新判断。
+- 发布所需部署依赖包括独立站点域名及通配 TLS、每游戏 host 路由、私有存储、网关 CSP/CORS/MIME、CDN TTL/purge、管理员审核运营入口和可恢复校验执行器；缺少任一项不能宣布公开上线。
+- 观察上传失败、校验耗时、审核积压、发行 4xx/5xx、撤销传播时间与容量，日志按游戏/版本/操作 ID 关联，不记录 Token、完整用户文件内容或 signed URL。原始失败/撤回包建议保留 7 天后清理，公开版本和审核记录的保留周期在上线前确定；清理必须先检查引用，不能删除仍在服务的版本。
+- 回滚部署时关闭新提交和新版本激活，保留当前可玩版本与状态读取；数据库迁移不以删表回滚。安全事件通过服务端关闭游戏发行权限，不依赖前端隐藏按钮。现役实现：`game-distribution:publish` 灰度开关（后台「灰度发布配置」）控制作者写入与新版本激活——没有 gate 行或 `enabled=false` 时默认开放；`enabled=true` 时只有白名单/灰度命中的用户能发布（`rolloutPercent=0` 且无白名单即全部关闭）。关闭期间目录、详情、版本回读、发行网关、审核队列读取、拒绝审核与安全下架都不受影响；开关读取失败按关闭处理。
+
+### 验收标准与证据
+
+| 条款 | 必须获得的证据 |
+| --- | --- |
+| 真实包闭环 | 网页 ZIP 与 AGC dist 分别提交同一管道，服务端实际包 SHA-256/文件清单和发行回读一致；仅 metadata 请求被拒绝 |
+| 包与数据边界 | 缺入口、摘要不符、穿越、符号链接、压缩炸弹、超限、凭据路径及未授权对象均被拒绝且未公开 |
+| 权限与游客 | 匿名浏览/游玩成功，匿名写入 401，其他作者写入/读取私有版本被拒，伪造 owner 无效 |
+| 幂等与恢复 | 双击、响应丢失、上传中断、同 key 不同内容、重启恢复、换账号迟到响应分别验证，不生成重复发行版本 |
+| 审核与并发 | 待审不公开；拒绝有理由；旧版在更新失败/待审期间在线；审核与下架并发 CAS 拒绝过期写入 |
+| 真正可玩 | 桌面及手机真实浏览器覆盖模块加载、素材、音频、触屏、横竖屏、开始/重试/退出和可用全屏；不以 iframe load 代替 |
+| 隔离与撤销 | 真实不同站点和每游戏 origin 下，主站 Cookie/storage/DOM 不可访问，外部网络阻断，旧 URL 在缓存窗口后不能取得新资源 |
+| 页面与视觉 | 当前 warm token 下的目录、详情、发布、加载/空/失败/待审态，桌面和移动视口无操作遮挡，键盘可达 |
+| 工程门禁 | 定向前后端测试、两端类型检查、真实 SpacetimeDB/API smoke、schema/绑定检查、编码、文档索引及 diff 检查 |
+
+所有运行时证据须注明实际环境和结论；缺少发行域名、登录、存储、审核或真实游戏时写明未验证，不使用演示 fixture 填充为业务成功。
+
+### 待评审决策
+
+1. 是否采纳人工审核及资料随发行版本审核、更新期间旧版保持公开的首版策略；审核负责人、处理时限与申诉/解除封禁口径需确定。
+2. 是否采用 `/games` 为网页根入口，以及“游戏 / 创作 / 项目 / 我的”和移动“游戏 / 我的”的导航提案。
+3. 是否接受首版离线静态包、无 Wasm/外网/持久存档的范围，以及建议包额度、7 天失败包保留和 60 秒缓存撤销窗口；公开/撤销版本及审核记录保留周期待定。
+4. 不同可注册站点发行域名、DNS/TLS/CDN、存储区域及运营责任尚待选定。不同站点和每游戏 origin 是上线门禁，不能退化成主站同源目录。
+5. 本节已提供页面行为、发行状态、真实上传、幂等/CAS 和 API 草案，足以评审完整业务；尚不足以直接实现持久化和部署，必须在对应里程碑评审前冻结表/索引/服务身份、额度/清理、最终响应 DTO 与发行基础设施配置。未经评审不建立 `ready` 实施计划，不把 proposed 标记为 accepted。