优化 AGC 发布资料与截图交互

发布门禁阻断提示改为独立弹窗且不写入聊天记录移除发布面板发行包技术摘要新增免费发布简介与分类建议接口和前端回填接入封面泥点定价、确认与生成流程截图改为并行上传，单张失败隔离且不阻断发布截图操作改为图标，失败项内嵌错误与删除同步发布合同、实施计划和决策记录
2026-09-23 17:40:08 +08:00
parent 64018f9661
commit 297d7bf1e7
15 changed files with 1816 additions and 335 deletions
@@ -0,0 +1,47 @@
+# 实施计划：游戏分发阶段 C · AGC 发布资料 AI 生成
+
+- 状态：`in_progress`
+- 日期：`2026-09-23`
+- 上游：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 的“AGC 游戏分发与在线游玩合同”
+- 里程碑：`docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md` 阶段 C
+
+## 1. 交付结果
+
+AGC 发布面板完成三项收敛：
+
+1. 移除 ZIP 路径、文件数、体积和“只上传字节”等技术摘要。
+2. 打开面板时基于有界、脱敏的项目上下文免费生成一句话简介和七类白名单分类；失败保留本地兜底，不阻断发布，生成结果可编辑。
+3. 游戏封面支持基于项目上下文生成，复用现役图片生成与泥点扣费链路；生成结果登记为当前账号平台素材后自动作为 `coverAssetId`，不二次上传。
+
+## 2. 实现边界
+
+- 只改 AGC 发布面板、AGC 发布 service、api-server 内部发布资料建议路由、shared DTO、定向测试和文档。
+- 不改网页发布表单、游戏分发审核 API、发行包上传/审核状态机、SpacetimeDB schema 或 `/api/external/v1` OpenAPI。
+- 简介/分类生成不写用户泥点账本；封面生成继续由现役 `execute_billable_asset_operation_with_cost` 负责预扣、幂等、失败退款和结果登记。
+- 传给文本模型的上下文只包含项目名称、创作目标、任务标题/状态、素材 kind/相对路径、运行状态和最近编辑提示；不包含绝对路径、聊天记录、凭据、Token 或完整 manifest。
+
+## 3. 实现步骤
+
+1. `packages/shared` 与 `shared-contracts` 增加发布资料建议请求/响应 DTO，分类继续使用 `GAME_DISTRIBUTION_CATEGORIES`。
+2. api-server 增加 `POST /api/game-distribution/publish-metadata/suggestions`，经 Bearer 鉴权后使用内部文本模型生成严格 JSON；解析失败或模型不可用时返回本地确定性兜底，不触发钱包扣费。
+3. AGC `GameDistributionPublishPanel` 打开时调用建议接口；用户未修改字段时回填，用户已编辑或迟到响应不得覆盖，失败不影响发布。
+4. AGC 封面生成复用 `POST /api/editor/images/generations` 的 `publication-material`、`gpt-image-2`、`16:9`、`2K` 合同；按钮和确认弹窗从 `/api/editor/generation-pricing` 读取并显示具体泥点数。若响应进入队列，轮询 `/api/runtime/external-generation/jobs/{operationId}`，完成后直接使用 `assetObjectId`。
+5. 发布截图同批并行上传；成功缩略图悬浮显示“删除｜预览”，失败缩略图内部显示错误并在下方保留删除按钮。失败项不参与发布，不阻断同批其它截图。
+6. 定向测试覆盖面板删除技术摘要、免费资料回填、封面价格/确认/生成/`coverAssetId` 直用、截图并行与单张失败跳过、服务端 parser/route 与输入边界。
+
+## 4. 验收判据
+
+- 发布面板不出现 `发行包摘要`、ZIP 相对路径或文件数/体积。
+- 建议接口成功时简介和分类自动回填；分类只可能是七类之一；接口失败时保留原创作目标或通用兜底。
+- 建议请求不会调用钱包、不会写 `asset_operation_consume` 或 LLM Router 额度账本。
+- 封面按钮和确认弹窗显示后端运行时定价对应的具体泥点数；确认后调用现役图片生成接口，生成结果直接成为发布 `coverAssetId`，没有第二次上传或素材身份分叉。
+- 同批截图并行上传；成功图悬浮显示删除/预览，失败图内部显示错误并有独立删除按钮；失败项不参与发布且不影响其它截图。
+- 生成失败、余额不足和队列失败均在面板内可见且可重试，不进入聊天历史。
+- 定向 vitest、api-server Rust 测试、AGC typecheck、`check:encoding`、`git diff --check` 通过。
+
+## 5. 非目标
+
+- 不做标题 AI 改写。
+- 不做网页发布页的自动生成。
+- 不新增发布草稿持久化、生成历史、重试队列或 SpacetimeDB 表。
+- 不改变封面上传入口和手动选择封面的能力。
@@ -86,6 +86,8 @@

 ## 阶段 C：双端发布与现代游戏体验

+- AGC 发布资料生成切片实施计划：`docs/project-memory/plans/【实施计划】游戏分发阶段C-AGC发布资料AI生成-2026-09-23.md`。
+
 ### 前置条件

 - B 已验收；网页根入口、桌面/移动导航、暖色主题交互稿及首版设备范围已评审。
@@ -94,6 +96,8 @@
 ### 行为与验收

 - [ ] AGC 从已构建 dist 生成根入口为 `index.html` 的真实包，一次提交动作完成检查、资料确认、上传和送审；状态及失败原因与服务端回读一致。
+- [ ] AGC 发布面板隐藏发行包技术摘要；打开时基于有界、脱敏的项目上下文免费生成一句话简介与白名单分类，失败保留本地兜底且不阻断发布；作者始终可以直接编辑生成结果。
+- [ ] AGC 发布封面支持基于项目上下文生成，复用现役图片生成与泥点扣费链路；生成结果登记为当前账号平台素材后自动作为 `coverAssetId`，不二次上传。
 - [ ] 网页可选 ZIP、提交封面和必需资料，进入相同上传/校验/审核流程；任一客户端可以查看同账号游戏状态，更新沿用相同 `gameId`。
 - [ ] 上传中断、双击、登录失效、窗口关闭后恢复原操作；换账号不能恢复前账号私有状态；待审不能显示为已发布。
 - [ ] 目录支持真实数据、关键词/分类/设备筛选、空/错/加载态；详情提供明确主动作，搜索与返回恢复上下文。
@@ -103,7 +107,7 @@

 ### 证据要求

- 自动化：AGC 打包与操作恢复定向 Rust 测试、两端客户端/组件/路由/状态测试及类型检查。
+- 自动化：AGC 打包与操作恢复定向 Rust 测试、两端客户端/组件/路由/状态测试及类型检查；发布资料免费生成必须验证不写入钱包账本，封面生成必须验证扣费幂等、失败退款与 `assetObjectId` 直用。
 - 运行时：AGC 一次真实发布、网页一次真实 ZIP 上传，分别审核后从桌面和手机游玩；浏览器覆盖游戏模块、素材、音频、触屏及横竖屏。
 - 边界：未构建/失效 dist、资料缺失、换账号、迟到响应、审核拒绝、非移动游戏及真实空态。

@@ -26,10 +26,19 @@
 - 验证方式：`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 apps/ai-game-creator-shell/tests/appSurface.test.ts`、`cargo check --tests`（告警消息集与基线一致）、`npm run check:encoding`、`git diff --check`；保留的 e2e 套件为 `supervisor-swarm`、`-transient-retry`、`-final-reply-transient-retry`、`-tool-plan-handoff-runner-kill`、`goal-runtime`、`response-stream`、`web-search`、`context-compaction`、`scoped-agents`、`project-skill`、`parallel-read`、`steer-runner-kill`、`process-session`。
 - 关联文档：[【ADR】退役AGC项目对话斜杠命令与终端swarm chat入口-2026-09-22](../../adr/【ADR】退役AGC项目对话斜杠命令与终端swarm chat入口-2026-09-22.md)、[【里程碑】退役AGC项目对话斜杠命令与终端swarm chat入口-2026-09-22](../plans/【里程碑】退役AGC项目对话斜杠命令与终端swarm chat入口-2026-09-22.md)、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。

+## 2026-09-23 AGC 发布资料免费生成与封面泥点生成
+
+- 背景：AGC 发布面板仍展示 ZIP 路径、文件数和体积，同时一句话简介只取创作目标、分类固定为“其他”，封面只能手选；这与发布页应隐藏技术信息、使用创作上下文降低填写成本的目标不一致。
+- 决策：发布面板移除发行包技术摘要。简介和分类由 AGC 调用平台内部免费文本模型生成，输入仅限有界、脱敏的项目名称、创作目标、任务状态、素材类型和最近编辑摘要；生成失败保留本地兜底，不扣用户泥点且不阻断发布。分类始终收敛到七类白名单。
+- 决策：封面支持基于项目上下文生成，复用现役编辑器图片生成接口和泥点扣费 wrapper；按钮与确认弹窗显示后端运行时定价对应的具体泥点数。服务端返回的 `assetObjectId` 直接作为 `coverAssetId`，禁止生成后再直传导致素材身份分叉。生成失败原因留在发布面板内。
+- 决策：发布截图同批并行上传；成功缩略图在鼠标移入时显示“删除｜预览”，失败缩略图在图片内显示错误并保留独立删除按钮。单张失败只跳过该张，不阻断同批上传或发布。
+- 边界：网页发布表单、游戏分发审核 API、SpacetimeDB schema、外部 `/api/external/v1` OpenAPI 均不变；临时项目上下文不落库、不进聊天记录。
+- 验证：AGC 发布面板与发布 service 定向 vitest、api-server 发布资料 parser/route 测试、AGC 与 api-server 类型/编译检查、编码和 diff 检查。
+
 ## 2026-09-23 AGC 发布前先守可运行原型门禁

 - 背景：客户端已经显示“首个可运行原型尚未完成，运行视图暂不可用”，但发布入口仍会先执行用户项目的 `build`，导致未完成原型也进入构建并在后续失败。
- 决策：`project.export_package` 的发布专用导出链路先检查可玩入口；没有入口时，只有 `code-prototype` 已完成或存在运行中的预览才允许执行 `build`，否则直接返回“首个可运行原型尚未完成，暂不能发布”。发布不再进入聊天确认卡，改为独立全屏进度弹窗；运行中遮罩覆盖整个工作区并阻止交互，失败留在弹窗内，成功后切换到发布资料面板。
+- 决策：`project.export_package` 的发布专用导出链路先检查可玩入口；没有入口时，只有 `code-prototype` 已完成或存在运行中的预览才允许执行 `build`，否则直接返回“首个可运行原型尚未完成，暂不能发布”。发布阻断反馈使用独立提示弹窗，不写入 Direct 聊天记录；发布过程不再进入聊天确认卡，改为独立全屏进度弹窗；运行中遮罩覆盖整个工作区并阻止交互，失败留在弹窗内，成功后切换到发布资料面板。
 - 边界：已有可运行入口仍直接打包；原型已完成但缺构建产物时保留原有自动构建；缺失 `exports/README.md` 仍在导出前自动生成。
 - 验证：Rust `publish_export` 4/4、前端发布相关测试 16/16、AGC `tsc`、编码检查和 `git diff --check` 通过。

@@ -86,7 +86,7 @@
 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 字。分类首版为休闲、益智、动作、冒险、模拟、策略、其他；封面/截图复用平台图片上传与归属校验，不接受任意外链作为审核图片。作者不需要自己构建或打 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 的旧版本必须要求作者重新选择封面。
+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`，避免发行文件被主站同源读取；发行网关必须部署在独立来源。发行包按对象键在进程内做有界缓存，单个超预算包不进入缓存。