发行包上限提升到 200 MiB 并支持 AGC 分片续传上传

- 发行包上限 100→200 MiB、展开总量 250→500 MiB，整包路由请求体上限继续从包上限派生；发行静态资源进程内缓存预算提到 256 MiB - 反代放行量同步放宽到 210 MiB：Nginx 三份模板的 client_max_body_size、Pingora 网关默认值与 env 样例、路由对照矩阵 - platform-oss 新增内部对象追加写 append_internal_object(_with_retry)，以 OSS 返回的 next-append-position 作为权威已收字节 - api-server 新增 upload-state / chunk / complete / reset 四条分片路由，抽出共享收口 confirm_validated_package；偏移不符返回 409 与权威偏移，校验失败删除半包并落 upload_failed - AGC 新增原生上传器 game_package_upload.rs（内容寻址暂存、分片续传、受控重试、进度事件）与 prepare / upload 两条命令，退役整包回传命令 - 渲染进程改为 prepare → 创建游戏 → 创建版本 → 原生分片上传 → 送审，LocalProjectExportPackagePayload 整包类型退役 - 同时修正 live 用例无法指向本地栈的两处基础设施问题：平台基址按传入 URL 选择，桥接层把 jsdom realm 的 Headers / Blob / FormData 降级成 Node 原生值 - 测试：platform-oss 74、api-server game_distribution 23、AGC 原生 4、发布相关前端 20；live 用例补真实栈「中断 → 续传 → 确认」断言（分片偏移序列 [0, 8388608]） - 文档：玩法创作主规范的上传合同、运维与 Pingora 文档、决策记录、发行里程碑口径，以及新增的续传里程碑与实施计划
2026-09-23 19:04:45 +08:00
parent c38d07044a
commit c2c5e1ced5
26 changed files with 1779 additions and 169 deletions
@@ -0,0 +1,49 @@
+# AGC 发行包分片续传上传实施计划
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | runtime-smoke-passed（存储原语、服务端入口、原生上传器、渲染进程接线与真实栈分片续传 smoke 均已落地） |
+| Date | 2026-09-23 |
+| Parent Milestone | `docs/project-memory/plans/【里程碑】AGC发行包分片续传上传-2026-09-23.md` |
+
+## 修改边界与顺序
+
+1. **存储原语（已完成）**：`server-rs/crates/platform-oss/src/lib.rs` 新增 `append_internal_object` / `append_internal_object_with_retry` 与 `OssAppendInternalObjectRequest` / `OssAppendInternalObjectResponse`；复用现役 V4 签名助手 `signed_request_builder`（查询串已参与签名）与 `run_internal_put_with_retry` 的可重试分类。`position = 0` 追加到末尾，`position > 0` 必须等于对象当前长度；返回 `next_position` 作为权威已收字节。
+2. **服务端入口（已完成）**：`server-rs/crates/api-server/src/modules/game_distribution.rs`
+   - 新增 `GET .../package/upload-state`、`PUT .../package/chunk`、`POST .../package/complete`、`POST .../package/reset` 四个路由，沿用作者鉴权、`game-distribution:publish` 灰度开关与 `Idempotency-Key` 约定；
+   - 分片大小 `PACKAGE_UPLOAD_CHUNK_BYTES = 8 MiB`，分片请求体放行量为分片大小 + 1 KiB；
+   - 从整包 `PUT` 抽出共享收口 `confirm_validated_package`（声明比对 → 确认 → 结构化事件），两种入口共用；
+   - 新增 `game_distribution_oss_client` / `game_distribution_package_object_key` / `staged_package_bytes` / `require_octet_stream_content_type` / `package_upload_offset` 辅助函数；偏移不一致返回 `409 PACKAGE_UPLOAD_OFFSET_MISMATCH` 与权威偏移；未收齐返回 `409 PACKAGE_UPLOAD_INCOMPLETE`；校验失败删除半包并落 `upload_failed`。
+3. **AGC 原生上传器（已完成）**：新增 `apps/ai-game-creator-shell/src-tauri/src/game_package_upload.rs`：内容寻址暂存（`<appData>/game-package-staging/<sha256>.zip`，重启后同包复用同一文件）、`upload-state → chunk → complete` 循环、409 权威偏移续传（响应丢失后按服务端已收字节对齐，不重放不跳段）、仅对传输/超时/408/429/5xx 退避重试（默认 4 次尝试）、`game-package-upload-progress` 进度事件；暂存路径必须落在暂存目录内。命令 `prepare_local_project_game_package` / `upload_local_project_game_package` 已注册，整包回传命令 `read_local_project_export_package` 退役（`read_local_project_export_package_at` 仍供暂存使用）。
+4. **渲染进程接线（已完成）**：`apps/ai-game-creator-shell/src/services/gameDistributionPublish.ts` 改为 `prepare`（拿摘要与暂存路径）→ 创建游戏 → 创建版本 → 原生分片上传 → 送审；`LocalProjectExportPackagePayload` 整包类型退役，改为 `StagedGamePackage` / `GamePackageUploadOutcome`；不再有任何整包字节进 IPC。
+5. **真实栈 smoke（已完成）**：本地 api-server + 真实 OSS bucket 上跑通「中断 → 续传 → 确认」。做法与证据：
+   - 先用 `npm run dev:spacetime` 把当前模块发布到本地库（`genarrative-game-creator-dev`，自动迁移完成），再用 `npm run dev:api-server` 起 `127.0.0.1:8082`；
+   - 本地库的 `feature_gate_config` 原本为空（发布开关默认关闭），用 `spacetime call … upsert_feature_gate_config` 写入 `game-distribution:publish enabled=true rollout=100`；
+   - `GENARRATIVE_AGC_PUBLISH_E2E_BASE_URL=http://127.0.0.1:8082 npx vitest run apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts` → **1 passed / 3.9s**（发行包 9.0 MiB，跨 8 MiB 分片边界）；
+   - 用例断言实际发送过的分片偏移序列等于 `[0, 8388608]`：第一片只发一次，中断后的续传从权威偏移开始，不重放也不跳段；
+   - api-server 侧同一轮日志：`package_chunk_stored offset=0 chunk_bytes=8388608 received_bytes=8388608 elapsed_ms=201`、`package_chunk_stored offset=8388608 chunk_bytes=1049210 received_bytes=9437818 elapsed_ms=82`、`package_confirmed package_bytes=9437818 file_count=3 oss_put_skipped=true elapsed_ms=884`。
+   - 为了能指向本地栈，用例还补了两处基础设施修正：把客户端平台基址切到传入的 base URL（`setClientServerSelection({preset:'custom'})`），以及桥接层把 jsdom realm 的 `Headers` / `Blob` / `FormData` 降级成 Node 侧原生值（`FormData` 手工序列化为 multipart 字节，否则 OSS 直传回 405）。
+
+## 不改的部分
+
+- 网页端发布路径与整包 `PUT` 语义不变；`MAX_PACKAGE_BYTES`、展开量、单文件与文件数上限不变。
+- 未新增 SpacetimeDB 表或字段：已收字节的事实来源是 OSS 对象长度，版本状态机沿用既有 `awaiting_upload → uploaded → …`。
+- 未引入半包定时清理任务。
+
+## 验证命令
+
+- `cargo test -p platform-oss`（74 passed）
+- `cargo test -p api-server game_distribution`（23 passed，含新增 `package_chunk_size_stays_inside_declared_limits`、`package_upload_offset_requires_non_negative_integer`、`package_chunk_content_type_must_be_octet_stream`）
+- `cargo fmt --all -- --check`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`
+- `cargo test game_package_upload`（AGC 原生侧 4 passed：分片规划无缝无重叠、409 权威偏移解析、URL 拼接、内容寻址暂存与路径校验）
+- `npx tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit`、`npm run --workspace apps/ai-game-creator-shell typecheck`（含 `check-config.mjs` 的命令登记门禁）
+- `npx vitest run`（发布函数 6 passed、发布面板 9 passed、发布反馈 5 passed；真实链路用例在无 `GENARRATIVE_AGC_PUBLISH_E2E_BASE_URL` 时按设计跳过）
+- 待做：真实栈 smoke（本地 api-server + 真实 OSS bucket 上跑「中断 → 续传 → 完成」，含 `x-oss-next-append-position` 语义确认）
+
+## 风险与回滚点
+
+- **对象可追加性**：`platform-oss` 之前没有追加写，首次真实调用需要在真实 bucket 上确认 `x-oss-next-append-position` 语义；失败时回滚点是 `platform-oss` 新增函数与四条路由（整包 `PUT` 不受影响，可独立回退）。
+- **半包对象**：分片写入直接落在版本键上，未完成时是半包。它不进公开目录、不服务发行网关；失败或作者重置时删除。若删除失败会记录 `package_staging_delete_failed` 告警，需要人工确认对象键状态。
+- **重置语义**：只有 `awaiting_upload` / `upload_failed` 允许重置，避免破坏已确认事实。
+- **内存**：完成动作按 200 MiB 上限回读整包再校验，峰值与整包 `PUT` 同量级；分片路径不再让整包驻留客户端。
@@ -0,0 +1,58 @@
+# AGC 发行包分片续传上传
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | runtime-smoke-passed（真实栈「中断 → 续传 → 确认」已通过；AGC 真机一键发布与 200 MiB 档容量数据未验证） |
+| Date | 2026-09-23 |
+| Parent Spec | `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`（真实发行包与资料合同第 10 条、幂等并发与恢复） |
+
+## 背景与触发
+
+AGC 一键发布今天把整包字节从 WebView 侧送出：`read_local_project_export_package` 先把 `packageBytes` 整包过一遍 IPC 回到渲染进程，渲染进程再用 `@tauri-apps/plugin-http` 发整包 `PUT`，而该插件会把 body 序列化成 `Array.from(new Uint8Array(buffer))` 再走一次 IPC。两次整包 IPC 决定了 AGC 实际可发布的包远小于服务端 200 MiB 上限，失败时表现为客户端侧传输错误（例如「无法连接登录服务」），服务端访问日志里没有这次请求；断流后也只能整包白传。本里程碑把上传下沉到原生侧并支持分片续传。
+
+## 目标
+
+1. AGC 一键发布由原生进程直接读取本地试玩包、按服务端下发的固定分片大小上传，整包字节不再经过 WebView IPC。
+2. 传输中断、网络失败、客户端进程退出或应用重启后，同一 `versionId` 只补传缺失字节，不白传整包。
+3. 分片入口与现役整包 `PUT` 共用同一版本状态机、摘要口径、幂等键与包校验；网页端发布路径不变。
+
+## 不在本里程碑内
+
+- 不改网页端发布路径（继续整包 `PUT`），不为浏览器实现续传。
+- 不做并行分片上传、不做客户端直传 OSS（分片仍经 `api-server` 转发，与今天整包路径同一出口）。
+- 不做「后台自动续传」：续传只在下一次发布动作或应用重启后的重试里发生，不引入常驻重传任务。
+- 不做未完成分片会话的定时清理任务；半包对象的回收单独开里程碑。
+- 不改发行包上限、展开量、单文件与文件数上限。
+
+## 合同要点
+
+- **入口与状态**：分片续传对既有 `versionId` 生效，版本状态沿用 `awaiting_upload → uploaded → …`；分片入口与整包入口互斥，同一版本同时只能有一个写入者，第二个写入返回 `409 UPLOAD_IN_PROGRESS`。
+- **权威偏移**：服务端记录的已收字节是唯一权威。客户端分片偏移与之不符时返回 `409` 与权威偏移，客户端按权威偏移续传；重复分片不得造成重复写入。
+- **完成动作**：全部字节到齐后才执行校验与确认；校验失败删除半包对象并把版本落到 `upload_failed`（`recoveryAction=reupload`）。重新上传同一版本前必须显式重置分片会话，重置后偏移归零，不允许在半包之上续写不同字节。
+- **可见性**：半包对象不进入公开目录、不服务发行网关、不改变当前公开版本；与既有「未通过审核不改变 `activeVersionId`」口径一致。
+- **原生侧边界**：原生上传只读本地试玩包并逐片发送，进度以事件回传渲染进程；渲染进程不再持有整包字节。
+
+## 依赖
+
+- `platform-oss`：需要一组可续写的对象写入原语（追加语义或等价的分片会话），以及读取已收字节的探测能力；现役只有整对象 `PUT`。
+- `api-server`：`modules/game_distribution.rs` 新增分片入口与完成动作，复用既有 `validate_release_zip`、OSS 上传重试分类、`package_confirmed` / `package_rejected` 可观测事件。
+- AGC：`src-tauri` 新增原生上传命令与进度事件，`src/services/gameDistributionPublish.ts` 改为调用原生命令；`read_local_project_export_package` 不再为发布回传整包字节。
+- 反代/网关：分片请求体远小于现役 210 MiB 放行量，沿用现有配置，不改限额。
+
+## 验收标准
+
+1. **不再整包过 IPC**：发布 200 MiB 档包时，渲染进程侧不出现整包字节（对照 `read_local_project_export_package` 的返回体与 IPC 报文大小），上传由原生进程完成。
+2. **续传生效**：上传中途断开传输后重发同一版本，只补传缺失分片；分片请求数、已传字节与最终包摘要三项均可复核。
+3. **跨重启续传**：上传中断时退出应用并重启，重新发布时服务端返回权威已收字节，客户端从该偏移继续，最终确认成功。
+4. **偏移与重复**：分片偏移不符返回 `409` 与权威偏移；重复提交同一分片不产生重复写入；同版本第二个写入者返回 `409 UPLOAD_IN_PROGRESS`。
+5. **失败关闭**：完成动作里校验失败（非法 ZIP、超限、压缩比越界等）删除半包对象、版本落 `upload_failed`，半包不出现在公开目录，也不影响当前公开版本。
+6. **兼容与回归**：整包 `PUT` 路径与既有测试保持绿；`npm run check:doc-index`、`npm run check:encoding`、`git diff --check` 通过；`check:spacetime-schema` 按是否新增持久字段决定是否纳入。
+7. **运行时证据（已获得）**：本地 api-server（`127.0.0.1:8082`，库 `genarrative-game-creator-dev`）+ 真实 OSS bucket 上跑通 `gameDistributionPublishLive.test.ts`：9.0 MiB 发行包跨 8 MiB 分片边界，第一片只发送一次，中断后续传从权威偏移 `8388608` 继续、第二片 `received_bytes=9437818`，最后 `package_confirmed`（`oss_put_skipped=true`）；整轮 3.9s。**未获得**：AGC 真机（Tauri 运行时）一键发布的端到端运行，以及 200 MiB 档的耗时 / 内存容量数据。
+
+## 待评审的决策点
+
+1. **续写原语**：OSS 追加写（顺序、单对象、续传只需回读当前长度）对比 OSS Multipart（可并行、更通用但需要多组新操作）。建议追加写，顺序续传已满足本里程碑目标。
+2. **分片大小**：建议 8 MiB（200 MiB 上限 → 最多 25 片，单片请求体远低于现役放行量）。
+3. **重置语义**：建议只有显式重置（作者点「重新上传」或 `reupload` 恢复动作）才删除半包并归零；其余情况一律按权威偏移续传。
+4. **半包回收**：本里程碑只标记未完成会话，不做定时清理；回收另立里程碑（涉及「不得删除仍被公开版本引用的对象」口径）。
@@ -120,7 +120,7 @@
 ### 行为与验收

 - [ ] 真实环境中完整跑通“首次上传 → 校验 → 审核 → 公开 → 游客游玩 → 更新待审旧版在线 → 新版切换 → 下架撤销”。
- [ ] 100 MiB 包与获批文件数/展开量边界有可复核耗时、内存和失败证据；校验不会执行上传代码，服务资源有界。
+- [ ] 200 MiB 包（现行上限，见 2026-09-23 决策记录）与获批文件数/展开量边界有可复核耗时、内存和失败证据；校验不会执行上传代码，服务资源有界。已有证据覆盖 100 MiB 档，上限提升后的档位待复跑。
 - [ ] 校验执行器重启可恢复，审核积压与失败可观测，清理不删除仍被公开版本引用的文件。
 - [ ] CDN purge 失败时仍在获批缓存 TTL 内拒绝新资源；明确已下载脚本无法远程抹除的边界。
 - [ ] 发布/回滚步骤保留当前公开版本，能关闭新提交和新版本激活；部署路由、缓存、响应头、日志脱敏和告警完成检查。
@@ -1,5 +1,20 @@
 # 决策记录

+## 2026-09-23 自绘标题栏是窗口边框：弹层从它下方开始，焦点陷阱放行它
+
+- 背景：AGC 打开任意一个 `ThemedModal` 弹窗（发布面板、发布进度、资源预览、账本、错误报告等）后，右上角「最小化 / 最大化 / 关闭」点击没有任何反应，标题栏拖拽也不能移动窗口；关掉弹窗立刻恢复。原因是标题栏在模态之外，而 `focus-trap-react` 在 document 捕获阶段监听 `mousedown`/`touchstart`/`click`，模态外的点击被 `preventDefault()` 且 `click` 直接 `stopImmediatePropagation()` —— React 的监听在更内层，事件到不了它，所以表现是「点了没反应」而不是报错。另有 `.app-update-overlay` 用 `inset: 0` 真的把标题栏盖住了。
+- 决策：把自绘标题栏定为**窗口边框**，不属于弹层内容：① portal 到 body 的全屏弹层一律 `top: var(--window-chrome-height)`，禁止用 `inset: 0` 盖住标题栏；② `ThemedModal` 的焦点陷阱用 `allowOutsideClick` 只放行落在 `[data-window-chrome-bar]` 内的目标，工作区内容的点击继续被拦住；③ `WindowChrome` 的标题栏加 `data-window-chrome-bar` 标记，作为这条约定的唯一契约点。
+- 影响范围：`apps/ai-game-creator-shell/src/components/modal/ThemedModal.tsx`、`apps/ai-game-creator-shell/src/components/WindowChrome.tsx`、`apps/ai-game-creator-shell/src/styles.css`（`:root` 注释、`.app-update-overlay`、`.game-publish-progress-overlay`）。
+- 验证方式：`tests/themedModal.test.tsx`（标题栏点击放行、工作区点击仍被拦）、`tests/WindowChrome.test.tsx`（弹窗打开时三个窗口按钮仍调用原生窗口 API）、`tests/windowChromeOverlayContract.test.ts`（7 个全屏弹层都从标题栏下方开始）、`tests/gamePublishFeedback.test.tsx` 与 appSurface（208 passed）；两处新增用例都做过「去掉修复即失败」的反向确认。`npm run --workspace apps/ai-game-creator-shell typecheck`、eslint、`npm run check:encoding`、`git diff --check` 通过。
+
+## 2026-09-23 游戏发行包上限提升到 200 MiB（反代放行量与发行缓存同步）
+
+- 背景：游戏广场发行包上限原为 100 MiB（`module-game-distribution` 的 `MAX_PACKAGE_BYTES` 与网页端 `GAME_PACKAGE_MAX_BYTES`），而 Nginx 三份模板与 Pingora 网关的通用 `/api` 放行量是 64 MiB。上限只改一层没有意义：包体超过 100 MiB 时先在反代层被 413，`api-server` 的 ZIP 校验根本不会执行。
+- 决策：发行包上限 100 MiB → 200 MiB；展开总量 250 MiB → 500 MiB（保持 2.5 倍余量）；单文件 64 MiB、最多 10,000 个文件、展开/压缩比 100 三条内容规则不变；发行包路由请求体上限继续从包上限派生（200 MiB + 1 KiB）。反代放行量统一放宽到 210 MiB：`deploy/nginx/genarrative.conf`、`deploy/nginx/genarrative-dev-http.conf`、`deploy/container/nginx.conf` 使用 `client_max_body_size 210m`，Pingora `DEFAULT_MAX_API_BODY_BYTES` 改为 `220200960` 并同步 `deploy/pingora/pingora-gateway.env.example`。发行静态资源进程内缓存字节预算 200 MiB → 256 MiB，让 200 MiB 档发行包仍能进缓存、且不独占整份预算。
+- 边界：包内单个文件仍不得超过 64 MiB；线上 Pingora 环境文件若仍写 `67108864`，必须在重启网关前同步改值，否则发行包 PUT 会在网关层被 413。AGC 一键发布经 `@tauri-apps/plugin-http` 传整包字节，实际可发布体积还受该传输方式限制，200 MiB 档的客户端容量需要单独验证。
+- 影响范围：`server-rs/crates/module-game-distribution/src/package.rs`、`server-rs/crates/api-server/src/modules/game_distribution.rs`、`server-rs/crates/pingora-gateway/src/main.rs`、`src/components/game-distribution/gameZipPackage.ts`、`deploy/{nginx,container,pingora}`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
+- 验证方式：`cargo test -p module-game-distribution`（13 passed，其中 `accepts_package_above_the_previous_hundred_mib_limit` 用两个 50 MiB 存储型条目构造 100 MiB 出头的包；把上限临时改回 100 MiB 时该用例确实失败，证明它能守住新上限）、`cargo test -p api-server game_distribution`（20 passed，含新增的请求体上限覆盖包上限断言）、`cargo test -p pingora-gateway`（38 passed，含 `matches_nginx_route_parity_matrix`）、`npx vitest run src/components/game-distribution`（46 passed）、`cargo fmt --all -- --check`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。`npm run check:pingora-route-parity` 仍在 dev-http / 容器模板缺少 `/games` 等 SPA 路由处失败，改动前同样失败，与本次口径无关。200 MiB 档真实栈容量证据（上传耗时、api-server 峰值内存、超限 413 口径）尚未复跑，发布前需按阶段 D 脚本重跑一轮。
+
 ## 2026-09-23 引用名不允许空白：素材 / Skill / 附件共用 `normalizeMentionName`

 - 背景：自动评审发现 `buildContentFromTextTokens` 在前缀重叠时会多插一枚芯片——素材显示名 `hero` 与 `hero v2` 并存时，粘贴 `看 @hero v2 这一版` 得到 `[chip hero]` + `[chip hero-v2]`（短名先按 index 平局抢位，长名成了补到末尾的孤儿）。根因不是匹配算法，而是**引用名自己带空白**：token 的边界规则是「前后为空白或行首行尾」，`@hero␠` 在 `@hero v2` 内部也算一次合法命中。
@@ -488,7 +488,7 @@ dev 根盘空间在安装后曾接近满盘；2026-06-17 进入 canary 前已清
 | `GENARRATIVE_PINGORA_GATEWAY_ACME_ROOT`                             | `/var/www/html`                            | ACME challenge 静态目录。                                                                                                              |
 | `GENARRATIVE_PINGORA_GATEWAY_MAINTENANCE_FILE`                      | `/var/lib/genarrative/maintenance/enabled` | 存在即进入维护模式。                                                                                                                   |
 | `GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO`                       | `http`                                     | 写入 `X-Forwarded-Proto` 的值。                                                                                                        |
-| `GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES`                    | `67108864`                                 | `/api` 通用路由的 `Content-Length` 上限。                                                                                              |
+| `GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES`                    | `220200960`                                | `/api` 通用路由的 `Content-Length` 上限（210 MiB，覆盖游戏发行包 PUT 的 200 MiB + 1 KiB 路由上限）。                                   |
 | `GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS`                | `gzip`                                     | 当前唯一允许的压缩算法白名单；Pingora 正式化口径固定为 gzip-only，Brotli 继续由 Nginx / 前置代理承担。                                 |
 | `GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED`                          | `true`                                     | 是否启用 gzip 响应压缩。                                                                                                               |
 | `GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL`                            | `5`                                        | gzip 压缩等级，必须在 `0..=9`。                                                                                                        |
@@ -893,7 +893,7 @@ worker 被硬杀或断电后，lease 过期任务只有尚未耗尽 `max_attempt
 - Server provision 不再通过 Windows helper 下载，也不再通过 Linux build 节点中转 SpacetimeDB / otelcol 工具包；Linux build 节点只负责从内网 Git 源准备 provision 脚本和配置并上传给目标 agent。`Prepare Provision Tools` 在目标 dev / release agent 工作区内先检查 `/usr/local/bin/otelcol-contrib` 与 `${SPACETIME_ROOT}/bin/current`：SpacetimeDB 必须同时匹配运行版本 `2.8.3` 和 commit `8e410d28...` 才能复用；只有缺失或版本 / commit 不匹配时才使用 `PROVISION_DOWNLOADS_DIR` 里的本地包或从配置的下载源准备官方 `v2.8.3` 资产。`SPACETIME_EXPECTED_COMMIT` 与下载根必须成对调整，安装结果也执行同一 commit 门禁。otelcol-contrib 当前锁定 `0.151.0`；如果目标服务器下载需要代理，在 `PROVISION_DOWNLOAD_PROXY` 配置目标机可访问的 HTTP 代理。
 - 除 `Genarrative-Server-Provision` 外，`Genarrative-Stdb-Module-Build`、`Genarrative-Web-Build`、`Genarrative-Api-Build`、`Genarrative-*Deploy`、`Genarrative-Database-Import/Export`、`Genarrative-Full-Build-And-Deploy` 和 `Genarrative-Notify-Email` 的生产流水线现都以 Linux agent 为主，仍按各自 Jenkinsfile 的 checkout 口径执行。Server provision 不使用公网备用 Git 源，目标部署 agent 也不再需要访问源码 Git remote。
 - `otelcol-contrib.service` 作为可选系统服务加入 provision，默认监听 `127.0.0.1:4317/4318` 并使用 `deploy/otelcol/genarrative-debug.yaml`。api-server 是否发送 OTLP 仍由 `GENARRATIVE_OTEL_ENABLED` 控制，服务 unit 见 `deploy/systemd/otelcol-contrib.service`。该服务必须存在系统用户 / 组 `otelcol`，并且 `/etc/otelcol/genarrative-debug.yaml` 已安装到目标机；若看到 `status=217/USER` 或 `Failed to determine user credentials`，优先检查 `getent passwd otelcol`，再补齐 `/etc/otelcol` 配置目录并重启服务。
- Nginx `/api/` 与 `/admin/api/` 通过 `genarrative_api` upstream 代理到 `127.0.0.1:8082`，upstream keepalive 为 64；通用 API 使用 `genarrative_api_rps`，后台 API 使用 `genarrative_admin_rps`。通用 `/api` location 保留 `client_max_body_size 64m` 作为编辑器图片、视频和文档请求的反代兜底，真实大小仍由路由与业务校验负责。若线上出现 `413 Request Entity Too Large` 且 access log 中 `request_time=0.000`、`upstream_status=-`，说明请求在 Nginx 层被拦截，先核对 release 模板与实际媒体大小。`limit_conn_status 429` 和 `limit_req_status 429` 必须在 HTTP 与 HTTPS server 中同时生效。
+- Nginx `/api/` 与 `/admin/api/` 通过 `genarrative_api` upstream 代理到 `127.0.0.1:8082`，upstream keepalive 为 64；通用 API 使用 `genarrative_api_rps`，后台 API 使用 `genarrative_admin_rps`。通用 `/api` location 保留 `client_max_body_size 210m` 作为编辑器图片、视频、文档请求与游戏发行包 PUT（路由上限 200 MiB + 1 KiB）的反代兜底，真实大小仍由路由与业务校验负责；使用 Pingora 网关时 `GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES` 必须同步不低于该值，否则网关侧会先返回 413。若线上出现 `413 Request Entity Too Large` 且 access log 中 `request_time=0.000`、`upstream_status=-`，说明请求在 Nginx 层被拦截，先核对 release 模板与实际媒体大小。`limit_conn_status 429` 和 `limit_req_status 429` 必须在 HTTP 与 HTTPS server 中同时生效。

 容器化隔离部署方案单独放在 `deploy/container/`，用于本机或预发模拟现有的 Linux release + Nginx + OTLP Collector 非 BgFilter 拓扑，不替换当前生产 `systemd + Nginx + Jenkins` 发布路径。当前 compose 没有 `bgfilter-worker`，不构成完整 BgFilter 预发拓扑，也不覆盖任何会触发 BgFilter 的现役任务；它只用于非 BgFilter 路径，或通过下述 unsupported job smoke 验证外部生成队列的 claim / fail 回写和 API-only 更新。当前容器模拟参数保留 `genarrative-release` 的 CPU、`nofile=4096` 与 `worker_connections=768` 采样口径，并在 compose 里落实到 `spacetimedb cpus=1.0 mem_limit=2g`、`api-server cpus=2.0 mem_limit=1g`、`external-generation-worker cpus=2.0 mem_limit=1g`、`nginx cpus=0.5 mem_limit=128m`、`otelcol cpus=0.25 mem_limit=128m`。完整模块首次实例化会超过旧 `896m` cgroup 上限，因此 SpacetimeDB 必须使用 `2g`；这不改变生产服务资源合同。容器 `api-server` 默认 `GENARRATIVE_API_WORKER_THREADS=4`，只增加 Tokio worker 调度并发，不突破 `api-server cpus=2.0` 的 CPU 配额；容器默认 `GENARRATIVE_EXTERNAL_GENERATION_MODE=queue`，可用 `npm run container:up -- --scale external-generation-worker=N external-generation-worker` 验证不经过 BgFilter 的外部生成 worker 动态扩缩容，`inline` 模式不参与该验证：

@@ -84,13 +84,14 @@

 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`、凭据文件与源码映射文件。超限返回明确错误，不截断后继续发布。
+3. 现行限额：压缩包 200 MiB、展开总量 500 MiB、单文件 64 MiB、最多 10,000 个文件、展开/压缩比不超过 100。压缩包上限同时决定 `api-server` 的发行包路由请求体上限（200 MiB + 1 KiB）与反代放行量：Nginx 通用 `/api` location 为 `client_max_body_size 210m`，Pingora 网关为 `GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES=220200960`；三者必须同时满足，否则合法包会在反代或路由层被 413。服务端拒绝加密 ZIP、重复或大小写冲突路径、绝对路径、`..`、符号链接/重解析点、设备文件和嵌套压缩包；拒绝 `.agent`、版本控制目录、`node_modules`、凭据文件与源码映射文件。超限返回明确错误，不截断后继续发布。超过约 100 MiB 的包在 `api-server` 会带来数百 MB 的瞬时内存占用，发布窗口与实例规格需按容量验证基线预留。
 4. 提交声明 ZIP 的 SHA-256 与字节数，服务端对收到的真实 ZIP 重新计算，再对展开文件建立相对路径、字节数和 SHA-256 清单。摘要不一致、缺文件或入口损坏时停止；只有 metadata 而没有已确认完整对象的提交必须失败。
 5. 游戏资料随发行版本冻结：标题 2–40 字、短简介不超过 120 字、详细介绍不超过 2,000 字、一个分类、最多 5 个标签（每个不超过 20 字）、必需封面、最多 6 张截图、操作方式不超过 240 字。分类首版为休闲、益智、动作、冒险、模拟、策略、其他；封面/截图复用平台图片上传与归属校验，不接受任意外链作为审核图片。作者不需要自己构建或打 ZIP：AGC 发布时对 `game/` 子工程按需执行 `npm install`（复用 `project.bootstrap`）与 `npm run build`（复用 `project.verify` 的受控 npm 运行器，脚本白名单含 `build`、禁止项目级 `.npmrc` 改写语义），再把 `game/dist` 归一化成根 `index.html` 的发行包上传；已有可玩入口（`game/index.html` 或 `dist/index.html`）时跳过构建。Phaser 4 + Vite 已按此口径端到端验证（构建产物、发行网关与网页沙箱播放）。发布入口按灰度下发：后端灰度配置键固定为 `game-distribution:publish`（后台「灰度发布配置」可改，支持 `enabled` / `rolloutPercent` / `allowUserIds` / `allowUserTags`）。灰度默认关闭：未配置该键、或 `enabled=false` 时，未登录与已登录作者都拿到不开放（发布入口不渲染、写入口 503）；运营在后台创建该键并 `enabled=true` 后，只有白名单 / 灰度比例 / 用户标签命中的作者拿到开放状态。发布入口的开放状态随 `/api/runtime/frontend-config` 的 `gameDistributionPublishEnabled` 下发，网页广场/我的游戏入口与 AGC 聊天头「发布到游戏广场」按钮据此显示或隐藏；写入口仍独立校验，收紧期间提交返回 503 与可读文案，读接口、目录、详情、发行网关与安全下架不受影响。作者续发时按版本冻结快照回填封面与截图并复用同一批素材；公开投影只暴露对象键，素材 ID 只在作者与管理员回读时返回，快照里缺素材 ID 的旧版本必须要求作者重新选择封面。AGC 发布面板不展示 ZIP 路径、文件数或体积等技术摘要；一句话简介与分类可根据有界、脱敏的创作上下文免费生成（不扣用户泥点，仍可编辑），分类必须收敛到上述白名单；游戏封面支持基于项目上下文生成，生成走现役图片生成与泥点扣费链路，产物必须登记为当前账号平台素材后才能作为 `coverAssetId` 提交。
 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}`（含尾斜杠）等价于该游戏的 `index.html`，`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。
+10. 上传有两条等价入口，共用同一版本状态机、摘要口径、幂等键与校验规则：① 整包入口——网页端与旧客户端对 `versionId` 直接 `PUT` 整包字节，原子、不可续传，仍受发行包上限与请求体限制约束；② 分片续传入口——AGC 原生一键发布对同一 `versionId` 顺序上传固定大小的分片，再以单独的完成动作收口。分片大小由服务端下发且固定（现为 8 MiB，随发行包上限 200 MiB 取整到 25 片以内），客户端不得自行改变；分片续传入口只补传缺失字节，任何分片重复或乱序都不得造成重复写入。AGC 侧必须由原生进程直接读取本地试玩包并按分片发送，整包字节不得经过 WebView IPC 往返，也不得整包驻留宿主内存。

 ### 身份、状态、审核与更新

@@ -106,7 +107,9 @@
 ### 幂等、并发与恢复

 - 所有创建、提交、审核、撤销和下架动作携带 `Idempotency-Key`。服务端以认证主体、动作和 key 保存请求摘要与结果；同 key 同请求返回原结果，同 key 不同请求返回 `409 IDEMPOTENCY_CONFLICT`。至少保留 30 天；客户端超出恢复窗口先回读记录，不能把未知结果自动当作失败重发。
- 同一个版本只能确认一份 ZIP：中断重传仍使用同 `versionId` 和摘要，已确认相同字节直接返回成功，不同摘要返回 409。上传中同版本第二个写入返回 `409 UPLOAD_IN_PROGRESS`；未确认半包不会进入校验。首版整包重传，不宣称支持分片断点续传。
+- 同一个版本只能确认一份 ZIP：中断重传仍使用同 `versionId` 和摘要，已确认相同字节直接返回成功，不同摘要返回 409。上传中同版本第二个写入返回 `409 UPLOAD_IN_PROGRESS`；未确认半包不会进入校验。
+- 分片续传以「服务端已收字节」为唯一权威偏移：客户端带上自己认为的偏移上传分片，与服务端记录不一致时服务端返回 `409` 与权威偏移，客户端按权威偏移继续，不重放也不跳段。传输失败、网络中断、客户端进程退出或应用重启后，同一 `versionId` 重新发布只补传缺失分片；已收字节数由服务端持久化事实决定，不依赖客户端本地记录。
+- 分片会话在全部字节到齐并执行完成动作之前，不进入包校验、不确认版本、不改变任何公开可见性，半包对象也不服务给发行网关。完成动作里校验失败时删除该半包对象并把版本落到 `upload_failed`（`recoveryAction=reupload`）；作者要重新上传同一版本时必须先显式重置分片会话，重置后已收字节归零，不允许在半包之上续写不同字节。
 - 重复提交同一次 AGC 操作不得创建第二个游戏或版本；原生端持久保存操作 ID、目标游戏/版本和 key，网页保存恢复标识并以服务端回读为准。相同 ZIP 用于不同资料修订时允许新版本，不能仅按包摘要吞掉新的发布意图。
 - 公开版本切换、作者下架和管理员审核必须带 `expectedPublicationRevision`，在持久化事务中比较并推进。并发变化返回 `409 PUBLICATION_CONFLICT`；旧送审版本不能在用户已发布更新或下架之后静默覆盖状态。审核员重新查看现状后才能提交新的明确动作。
 - 网络中断或响应丢失后先查询原操作/版本；服务端恢复 `validating` 的在途任务并按版本身份幂等续作，不另建版本。登录失效保留私有草稿和恢复标识，重新登录同账号后继续；换账号不能读取或接管原账号操作。