修正美术包 API 指南、AGC 调用与切片用途判定 (#628)

AGC 美术包此前把内容、风格和排布要求放在未被提示词消费的元数据中，并要求恰好四张切片、按返回顺序分配用途。本 PR 完成以下三项修正：

- [x] API 文档：修正整个 `generationInputs` 的定位、保存与读取方式、接口保留/重建规则及已知消费者。任意元数据不会自动进入提示词，服务端行为和校验约束保持不变。
- [x] AGC 请求：美术包将原 brief 和内容、风格、排布要求写入实际消费的 `iconDescriptions`；普通图标入口继续原文单项透传。参考图、比例和尺寸使用正式参数，同步工具说明与随包 skill。
- [x] 客户端切片处理：美术包和直接生图工具不再暴露或发送 `sliceCount`，取消固定四片和按序赋义；按实际产物保存、登记和返回。切片目录按源图集隔离，文件名使用中性序号，普通清单指向真实总图。

四类素材需求只表达内容覆盖，不能证明四个连通区域或固定语义顺序。两个工具返回总图、完整切片路径及资源身份，预览逐项标注路径，未内嵌的图片列出路径供 Agent 查看。Agent 看图识别实体、状态和用途后再接入或处理；有效总图零切片时仍交付并保留告警。

本轮切片改造仅限客户端：服务端 API、请求侧 sliceCount 契约、切分算法和计费行为不变。不新增为数量不符找回、补切或凑数的工作流。保留文件完整性、平台身份、资源预算、事务与重生成恢复；兼容历史四用途产物和旧数量参数账本，旧请求正文、幂等键及 operation 不改写，候选身份不唯一时要求对账。完成结果快照补存切分声明，避免重放丢失响应字段。

验证：

- API 文档阶段：MCP 25 项、External editor API 30 项测试及 OpenAPI 约束等价检查通过。
- 本轮：317 项定向 Rust 测试通过（生成 118、Direct 运行时 93、工具桥 44、MCP 32、账本 6、提示词 24）。覆盖新请求完全省略字段、0/2/4/6 片、目录隔离、完整资源投影、动态事务回滚、旧请求和旧输出槽恢复；已受理任务恢复不新增生成 POST。
- cargo check、rustfmt、skill-pack:check、文档索引、变更文件编码及 git diff --check 通过。
- 未调用真实付费 Provider，未做客户端视觉试玩；PR 保持草稿，等待视觉及产品验收。

Closes #525

Reviewed-on: #628
Co-authored-by: Linghong <ink29535@proton.me>
Co-committed-by: Linghong <ink29535@proton.me>

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

@@ -2,6 +2,14 @@
 
 这里只记录对当前开发仍有用的症状、根因、排查方法和风险边界。同一事实保留一个当前口径；退役对象的专属过程与单轮测试结果由 Git 历史追溯。遇到旧路径或版本时，以现行代码和专题文档为准。
 
+## 2026-10-05 generationInputs 的保存与复用不等于自动生效或完整透传
+
+- **现象 / 根因**：调用方把构图等要求只写入 `generationInputs.artSpec`，但实际生图输入没有这些要求；把 `JsonValue` 和“可复用规范”误读为服务端会自动组装提示词、完整保留全部元数据或自动用于下一次生成。
+- **现行边界**：整个 `generationInputs` 承载生成上下文、来源和应用元数据，保存规则取决于接口。场景与音效重建配方；图集原图可保存自定义字段，透明图集与切片另建处理阶段 / 来源元数据。已知字段仍有实际消费者，例如规范图的“游戏类型”、V2 面板恢复字段和客户端来源标记，不能把整个对象描述为无业务作用。
+- **排查 / 使用**：同时核对正式请求字段、当前接口的重建 / 清理逻辑，以及最终资源 / 素材记录；重要要求必须进入 `prompt`、`iconDescriptions` 或场景结构化参数。项目与素材库读取可取得服务端实际保存的上下文，但它不等于完整 HTTP 重放载荷；重试仍保存原始请求和幂等键。
+- **AGC 美术包**：核心图集新请求将原 brief 与共用的风格、内容和间距要求分别写入 `iconDescriptions`；普通图标入口仍原文单项透传。新增模板只影响新请求，旧请求继续按冻结正文和操作身份恢复，不改原 brief 的意图判据。真实 HTTP 载荷与旧请求恢复必须同时验证，不能只测试 `artSpec` 包含文案。
+- **权威说明**：[External v1 OpenAPI](../../openapi/genarrative-external-v1.openapi.json) 与 [API 指南的 Generation Inputs Metadata](../../../.codex/skills/genarrative-external-editor-api/references/requests-and-outputs.md#generation-inputs-metadata)。本条记录现有行为，不引入 API、存储或 UI 行为变更。
+
 ## 2026-10-06 陶泥儿导出与发布媒体直传：幂等摘要、幂等账本、skill-pack 红与 zip 根入口
 
 - **multipart 发布的幂等摘要必须纳入图片字节**：写路径改 `multipart/form-data` 后，`metadata` 文本 part 只描述槽位；若摘要只序列化元数据，同一 `Idempotency-Key` 换一张新图或换一个沿用 objectKey 会被判成同请求重放，服务端静默复用旧结果、新图丢失。现行口径：服务端 `publish_request_digest` = 规范化元数据 JSON + 每个 `cover`/`screenshot` part 的 SHA-256 + 槽位里的 objectKey；AGC 侧 `metadata_digest` 同样把图片原始字节喂进哈希。create / create version / update metadata 三条写路径共用；回归时「只换图不改文案」必须得到不同摘要。
@@ -173,7 +181,6 @@
 - **处理（现行口径）**：`.project-chat-composer.is-direct-codex` 是单列网格（`gap: 8px`）；**控件全部集中在唯一一行工具条**——左组 `@` / `+`，右组 模型 / 语音 / **「AI 润色 / 恢复原文」（紧贴发送左侧）** / 发送，六颗 `flex-wrap: nowrap` 平铺（润色钮由 `ResourceReferenceInput` 的 `actionsPortalTarget` portal 进右组发送钮之前的挂点，不再自成一行；它与发送钮同为圆角矩形按钮，相邻成组，DOM / Tab 顺序都是 模型 → 麦克风 → 润色 → 发送）；状态/提示层只在有内容时占行（空输入态第二行为 0 高、行间距为 0，状态自己带 6px 上间距）。窄宽度用 `min-width` 兜（控件排 252px / 外壳 278px）+ 横向溢出可见：**不换行、不堆叠、不重叠**，发送钮仍可点击（夹具 `elementFromPoint` 命中）。模型钮封顶 160px 且名字走省略号（收缩由它承担），左组是固定 28px 动作钮、`flex: 0 0 auto` 不参与收缩。**模型失败提示后来改成走浮层**（见本文件顶部 2026-10-04 / 2026-10-05 两条）：控件排里既不留常驻红字、也不留常驻状态文字——「控件排内独占一行」那次快照已退役，行高回到由模型触发钮决定。
 - **判据/取证**：`apps/ai-game-creator-shell/tests/chatDialogFrameLayout.test.ts` 用层叠求值钉住单行工具条（240 / 280 / 296 / 320 / 360 / 438 / 900 七个宽度下 `flex-wrap` 都是 `nowrap`、控件排 `min-width: 252px`、外壳 `min-width: 278px`）、输入盒最高高度算式（12 盒内上内边距 + 160 编辑器 + 0 输入区行距 + 0 状态行 + 0 输入区下内边距 + 8 输入盒与工具栏行距 + **30 工具栏行高（模型触发钮 30px 撑起来，发送/语音是 28px）** + 12 盒内下内边距 = **222**），以及组件源码里润色钮渲染在工具条挂点（`actionsPortalTarget={controlsActionsSlot}`、挂点在控件排之后）；`tests/appSurface/project-development.suite.ts` 钉住 composer 的 `gap: 8px`。真实渲染对照见 #600 PR：同一夹具在 495/438/360/296/280px 面板 × 空 / 长多行 / 队列+提示 四态下，改前 2~4 处相交（含文字被提示盖住），改后 0 处相交、0 处溢出。
 - **关联**：`apps/ai-game-creator-shell/src/styles.css`（文件末尾「输入区工具栏与状态提示」区块）、`docs/【功能说明】AGC聊天AI润色与发送前提醒-2026-09-10.md`。
-
 ## 2026-10-03 AGC 随包 plugins 的 feature 档位必须与消费方一致，且门禁会因 build.rs 未重跑而假通过
 
 - **现象**：Windows 本机 `npm run check:generated-bindings`（`npm run lint` 链内，`scripts/check-repository-ci.sh` 的 Repository checks 也走它）在 `build.rs:167:29` panic：`插件随包资源校验失败：随包插件存在未声明文件：.../src-tauri/resources/plugins/agc-godot-editor/native/gdextension/bin/win-x64/agc_godot_editor.dll（目标 x86_64-pc-windows-msvc 与当前 feature 组合不允许；请先执行随包资源准备步骤）`；树上换成 `agc-unity-editor/dotnet/publish/win-x64/Agc.Unity.Attach.exe` 时报同一类错。反向还有更隐蔽的形态：门禁 2 秒就 exit 0 说「通过」，但 tree 上其实带着编辑器产物。
@@ -540,7 +547,7 @@ Copy Artifact 插件在**非 SYSTEM 认证**下按「认证用户」判权：只
 ## 同一条链路两处上限不一致：平台合法产出被客户端整条丢弃
 
 - 现象：客户端报「生成素材失败：platform-generation-result-unknown: 异步生成完成结果无法绑定到 operationId：External Editor 旧同步结果的图集切片超过 64 个」，而平台侧这次生成**其实已经成功并切完图**（任务账本耗时正常、`assetId` 为空、没有任何素材落盘，付费产物被丢）。
-- 成因：图集切片上限在链路里存在两份字面量——平台切分、Agent 工具 schema `sliceCount` 与持久化产物批次都是 256，客户端结果绑定门写着 64（`agent/generation/{canvas_generation.rs,external_generation_state.rs}`）。自动切分（`connected-components` + `sliceCount=null`）切出 65~256 片是合法产出，客户端比平台更严就会把结果整条判失败。
+- 成因：图集切片上限在链路里存在两份字面量——平台切分与持久化产物批次都是 256，客户端结果绑定门写着 64（`agent/generation/{canvas_generation.rs,external_generation_state.rs}`）。自动切分（`connected-components` 且省略数量参数）切出 65~256 片是合法产出，客户端比平台更严就会把结果整条判失败。
 - 处理：客户端门统一到 `PLATFORM_ART_SPRITESHEET_MAX_SLICES = 256`，判据与文案各只留一份（数字由常量插值），并在注释里点名三处同值权威（平台切分常量、工具 schema、公开契约）。
 - 复用判据：凡是「平台产出 → 客户端校验后落盘」的链路，客户端门只能表达**安全 / 预算**约束，不得比平台的产品上限更严；两边上限要引同一个常量或同一份文档，改一边时必须同时改另一边，并补一条「上限之内必须能落盘」的回归用例。
 
@@ -5572,10 +5579,10 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 处理：显式重做使用 `mode=regenerate`，普通请求使用 `reuse-or-create`。模式由 Codex 根据当前用户请求通过审核工具显式选择；客户端不再使用 Unicode NFKC、关键词、否定词表或独立确认句式判断业务意图。旧文本授权规则已被 2026-09-03 MCP 决策替代，相关无调用实现于 2026-09-23 删除。工具桥绑定活动客户端回合与稳定 `clientTurnId`，冻结首次 `brief` 摘要；缺少活动回合或摘要冲突仍拒绝。项目权限、账号、计费、幂等、锁与未知结果恢复合同继续有效。
 - 幂等与恢复：同一调用完成回包丢失只从 `completed` 持久结果等值重放，不能因重试再次扣费。App 必须在 Direct 调用前落盘原始 User 消息和回合 ID，Tauri 必须在成功返回前幂等落盘同 ID assistant 终态；同进程重复水合若命中“回合仍在运行”，只能显示瞬时占用提示，不得以稳定 assistant messageId 写成终态并抢占原执行的成功回复。恢复扫描与启动前置恢复必须发现 `resetting / compensating / anchored in-progress` 并在专用锁内恢复，重开项目只续跑真正未回答的原身份。整条付费链必须持有专用跨进程执行锁；换新回合时先持久化 `resetting` 再清理旧阶段账本，不得通过删除 workflow 留出无主窗口。崩溃补偿只恢复旧文件并清 replacement CAS 锚点，已 `prepared / accepted` 阶段账本、原 `Idempotency-Key / operationId` 必须保留，同冻结意图续跑复用旧请求；未知账本在文件 mutation 前失败关闭。只有没有任何阶段账本和替换锚点的孤立 workflow 空壳可原子接管；旧 schema 和其余冲突失败关闭。遇到 prompt 或当前 art-spec 身份不一致的未决账本必须保留原 operation 并返回对账错误。
 - 执行边界（2026-09-24 校准）：DirectProject 的 cwd 与 AGC 业务身份根是用户选择的 canonical 项目根；其原生 OS 路径字节与权威 manifest `projectId` 经域标签和独立长度前缀编码后绑定连接池和 thread 身份。旧的 `game/` 唯一可写根、禁止全部网络 / 命令 / MCP 的描述已失效；也不能把后来的“完整访问”描述理解为绕过当前宿主门禁。当前 thread 使用 `sandbox=read-only`、`approvalPolicy=untrusted`，turn 使用 `sandboxPolicy.type=readOnly`；原生命令按逐次审批与宿主执行许可处理，客户端 MCP 仍校验项目绑定、业务权限和副作用许可。具体边界以[主实施计划“宿主验收与执行许可合同”](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#宿主验收与执行许可合同)及当前实现为准，Provider 凭据保持隔离。
-- 资源投影：标准图集首次创建和重生成都要求四张透明、可见、像素及平台身份唯一的 canonical 切片；工具只回传通过私有回执、公开清单、源图和顶层登记交叉验证的 `slicePaths` 与安全 `resources`。部分/opaque/重复/缺回执切片必须告警，不能把公开清单或顶层自述身份当作 Canvas 权威。
+- 资源投影：标准图集首次创建和重生成均按实际切片集合提交，保留透明、可见、像素及平台身份唯一的校验；有效总图零切片时仍返回成功与告警；工具只回传通过私有回执、公开清单、源图和顶层登记交叉验证的 `slicePaths` 与安全 `resources`。部分/opaque/重复/缺回执切片必须告警，不能把公开清单或顶层自述身份当作 Canvas 权威。
 - 同进程恢复补充：命中“同一 stable turn 仍在运行”后除禁止写 assistant 终态外，还必须删除当前 App 实例的恢复 claim。这样原调用随后成功时显式刷新能读取其终态，随后失败时也能按相同 `clientTurnId` 再次续跑；不要靠重载 WebView 清理进程内 claim，也不要用无界定时轮询制造并发调用。
-- 严格图集崩溃补充：规范图和背景图的两文件 rollback 不覆盖严格图集事务已经整体修改的 `.agent/manifest.json`、私有回执、公开清单、主图集、四切片和切片清单。必须在严格调用前持久化 pending 及九项旧合同身份；重启恢复先对账底层严格事务，完整新合同直接收口完成，完整旧合同才补偿前两阶段，混合或漂移状态失败关闭。不要在严格提交成功后局部恢复前两张图。
-- 部分旧包补充：rollback 的规范图/背景图必须保存旧字节与旧 manifest entry，不能把这两项缺失隐式当成空内容；显式 `regenerate` 因此只在这两项可信可回滚时开放。历史主图集、私有回执、公开清单或 canonical 切片可以缺失，但八个严格路径与受管顶层 asset identity 必须逐项冻结其真实 `Present/Some` 或 `Missing/None` 状态，补偿也必须恢复相同存在性。不要因为旧美术包缺切片而阻断重生成，也不要把本轮新建的严格文件误记成旧文件。
+- 严格图集崩溃补充：规范图和背景图的两文件 rollback 不覆盖严格图集事务已经整体修改的 `.agent/manifest.json`、私有回执、公开清单、主图集、实际切片和切片清单。必须在严格调用前持久化 pending 及完整旧合同身份；重启恢复先对账底层严格事务，完整新合同直接收口完成，完整旧合同才补偿前两阶段，混合或漂移状态失败关闭。不要在严格提交成功后局部恢复前两张图。
+- 部分旧包补充：rollback 的规范图/背景图必须保存旧字节与旧 manifest entry，不能把这两项缺失隐式当成空内容；显式 `regenerate` 因此只在这两项可信可回滚时开放。历史主图集、私有回执、公开清单或 canonical 切片可以缺失，但固定合同文件、实际切片与受管顶层 asset identity 必须逐项冻结其真实 `Present/Some` 或 `Missing/None` 状态，补偿也必须恢复相同存在性。不要因为旧美术包缺切片而阻断重生成，也不要把本轮新建的严格文件误记成旧文件。
 - 对话扫描与 claim 补充：历史中出现 `User A / User B / Assistant B` 时，B 已回答不代表 A 已回答，扫描必须继续寻找 A。成功 Direct 回复在 Rust 返回前已经落盘，前端冗余 append 失败不能据此重跑；普通错误回复的显式落盘失败时，恢复 claim 要保持到 React fallback writer 的同一 messageId append 明确收敛。writer 成功或明确失败后才释放；失败路径要停止该消息的自动迟到重试，再由显式重新加载对话复用原 stable turn。终态后及时删除 claim，避免 Set 无界增长。
 
 ## Native shell CI 不能在测试阶段重新解析 Cargo registry（2026-08-26）
@@ -6562,6 +6569,14 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **判据/取证**：`node --test scripts/check-nginx-spa-routes.test.mjs`（正/反用例，含「写回精确匹配即红」）、`npm run check:nginx-spa-routes`、`npm run check:pingora-route-parity`、`cargo test -p pingora-gateway -- pay_checkout_deep_link matches_nginx_route_parity_matrix`；线上复验 `curl -s -o /dev/null -w '%{http_code}' https://<平台域名>/pay/<checkoutToken>` → 200 且正文与 `/` 同一份 `index.html`。
 - **关联**：`scripts/check-nginx-spa-routes.mjs`、`deploy/pingora/nginx-route-parity.matrix.json`、`server-rs/crates/pingora-gateway/src/main.rs`、`server-rs/crates/api-server/src/payment.rs`、`deploy/nginx/genarrative.conf`。
 
+## AGC 图集数量与返回次序不表达用途（2026-10-05）
+
+- 图集请求中的 sliceCount 不影响模型提示词，只会约束服务端后处理；客户端不再暴露或发送它，服务端 API 仍保留现状。四类内容需求不等于四个连通域，也不能按返回次序或历史 player 等文件名分配用途。
+- 新切片按源资源摘要隔离、以中性序号保存；普通清单记录实际总图路径，美术包回执按实际集合验证。工具返回全部身份与路径标注预览，Agent 看图识别后使用或处理；零片仍交付有效总图与告警。
+- 动态集合必须同时进入事务 journal、重生成快照、完整性检查和工具投影。旧数量请求需先定位原动作槽并使用原请求体、幂等键和 operation，候选不唯一则对账；不能删掉指纹字段后直接发起新付费请求。完成结果要保留 sliceMode/gridX/gridY，否则重放会丢失服务端回显。
+- 美术包仅有规范图和背景图时，`reuse-or-create` 必须继续补齐图集，不能把两图包返回为 completed。补齐优先恢复现有阶段请求；无请求才只读查找并按需生成，查询失败、身份冲突或账本损坏不能当作资源不存在而重发。补齐失败保留有效基础图，三张主图齐全且可验证后才交付；零切片告警不等于缺失总图。
+- 规范图的原始生成资源 ID 与当前账号重新登记后的参考 ID 可以不同。整包完成和中断恢复只按阶段完成结果核对图集资源、对象、任务身份，不能额外要求请求参考 ID 等于规范图原始 ID；这会在素材已经保存后误报身份未绑定。规范图来源关系沿用现有绑定校验。
+
 ## 2026-10-05 在线游玩「一直黑屏」：加载面缺失 + 发行网关不压不发 ETag
 
 - **现象**：用户反馈「进入游玩…加载有点慢，一直黑屏体验不好」。真实栈（真实发行包 + Chromium + 4 Mbps/100 ms 模拟链路）实测：网页游玩页点击「开始游戏」后 99.3% 像素亮度 < 24 的近黑面板 + 一行 `游戏正在启动…`，游戏画面 **3298 ms** 才出现；后台审核页点「试玩当前待审版本」后 iframe 直接以 `opacity:1` 出现、区域**全白空白** 4587 ms，页面**全程没有任何加载文案**。