合并图标规范与图集生成优化

合入 PR 137 的图标规范生成、稳定引用与图集提示词链路
保留主分支现行音效提交、Prompt 模块与结果压缩逻辑
解决 External Worker、生成提交和客户端测试冲突

docs/openapi/genarrative-external-v1.openapi.json

@@ -3650,29 +3650,32 @@
       "EditorIconSpritesheetGenerationRequest": {
         "type": "object",
         "required": [
-          "referenceImageSrc",
+          "referenceId",
           "iconDescriptions"
         ],
         "properties": {
-          "referenceImageSrc": {
+          "referenceId": {
             "type": "string",
-            "description": "图标规范的稳定引用：当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。"
+            "description": "当前账号中已登记为 icon-spec 的项目资源 ID 或素材 ID。只接受 ID，不接受 objectKey、图片 URL、Data URL 或 Blob URL。"
           },
           "referenceImageSrcs": {
             "type": "array",
             "items": {
               "type": "string",
-              "description": "额外图标素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。referenceImageSrc 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
+              "description": "额外图标素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。referenceId 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
             },
             "maxItems": 8
           },
           "iconDescriptions": {
             "type": "array",
-            "description": "图标生成需求文本数组，供 prompt 组装使用；数组长度不控制自动切片数量。画布前端把完整用户提示词作为唯一数组元素提交；其它调用方可继续提交 1 到 100 条非空文本。",
+            "description": "图标生成需求文本数组，供 prompt 组装使用；数组长度不控制自动切片数量。画布前端把完整用户提示词作为唯一数组元素提交；其它调用方可继续提交 1 到 100 条非空文本。服务端去空并以换行拼接后，单条最多 200 个 Unicode 字符，合计最多 2000 个 Unicode 字符且不超过 6144 个 UTF-8 字节；超限同步返回 400，不会入队或计费。",
             "minItems": 1,
             "maxItems": 100,
+            "x-genarrative-maxTotalCharacters": 2000,
+            "x-genarrative-maxTotalUtf8Bytes": 6144,
             "items": {
-              "type": "string"
+              "type": "string",
+              "maxLength": 200
             }
           },
           "screenColor": {

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

@@ -5837,7 +5837,7 @@
 ## 2026-07-28 AI 游戏创作正式视觉规范与透明 spritesheet DAG
 
 - 16-task 边界：继续复用现有 seed manifest 的 `art-director / design-foundation / art-asset-plan` 三个任务，不新增平行任务、会话或素材系统。`art-director` 是正式视觉规范前置：先通过 `/api/external/v1/editor/images/generations` 的 `kind=spec` 生成 `assets/art-spec.png`，并登记为 `assetKind=icon-spec`。`generationInputs.artSpec` 只是辅助结构化上下文，不能替代这张真实规范图。
-- 路由与依赖：`design-foundation` 以已登记 `assets/art-spec.png` 的 External Editor 稳定资源 ID 作为 `referenceImageSrcs` 中的视觉规范参考，通过 `/api/external/v1/editor/images/generations` 的 `kind=ui-design` 生成完整 `assets/ui-prototype.png`；`art-asset-plan` 以同一 art-spec 资源 ID 作为必填 `referenceImageSrc`，调用 `/api/external/v1/editor/icon-spritesheets/generations`，提交具体 `iconDescriptions` 与 `screenColor=auto` 生成透明 `assets/art-spritesheet.png`。严禁把 `assets/ui-prototype.png` 当作规范图引用；`art-spec.png` 缺失、不是当前画布的 `icon-spec` 或缺少稳定 `resourceId` 时，两个下游任务都必须等待 `art-director`，不得把本地路径、Data URL / Blob URL 当成稳定引用，也不得退回普通生图。单波最多 `3` 个静态职责的资源上限保持不变，调度只调整现有任务的依赖边和就绪顺序。
+- 路由与依赖：`design-foundation` 以已登记 `assets/art-spec.png` 的 External Editor 稳定资源 ID 作为 `referenceImageSrcs` 中的视觉规范参考，通过 `/api/external/v1/editor/images/generations` 的 `kind=ui-design` 生成完整 `assets/ui-prototype.png`；`art-asset-plan` 以同一 art-spec 资源 ID 作为必填 `referenceId`，调用 `/api/external/v1/editor/icon-spritesheets/generations`，提交具体 `iconDescriptions` 与 `screenColor=auto` 生成透明 `assets/art-spritesheet.png`。严禁把 `assets/ui-prototype.png` 当作规范图引用；`art-spec.png` 缺失、不是当前画布的 `icon-spec` 或缺少稳定 `resourceId` 时，两个下游任务都必须等待 `art-director`，不得把本地路径、Data URL / Blob URL 当成稳定引用，也不得退回普通生图。单波最多 `3` 个静态职责的资源上限保持不变，调度只调整现有任务的依赖边和就绪顺序。
 - UI extraction 边界：`/api/external/v1/editor/ui-designs/assets/extractions` 只适用于已有且带红框标注的 UI 设计图，不是 UI 设计图生成接口，也不进入本次 canonical DAG。后续若要生成独立 UI spritesheet，必须先补红框源图生成与正式产物合同，不得直接对无标注 `ui-prototype.png` 调用 extraction。
 - 完成门禁：External Editor 2xx 只表示生成请求完成。通用 `warning` 优先于 `sliceWarning`；`postprocess-failed-source-preserved` 表示 provider 源图是唯一权威结果，但不满足透明图集合同，客户端保留服务端事实并失败关闭，不登记本地正式 spritesheet、不伪造切片、不自动重跑。仅 `sliceWarning` 时完整透明图集有效，Runtime 把原始 reason 写入私有审计与 Agent observation，但不得声称独立切片存在。下载结果还必须解码并至少包含一个真实透明像素，纯 RGB 或全不透明 RGBA 一律拒绝落盘和 manifest 登记。
 - OpenAPI 同步事实：2026-07-28 从 `https://www.genarrative.world/api/external/v1/openapi.json` 获取的线上合同与 `docs/openapi/genarrative-external-v1.openapi.json` 原始 SHA-256 均为 `00fa39ea8781605b895b331a579fbf097eea7892962350cb2a82bed7e1024135`，逐字节一致，因此不制造无意义 JSON diff；实现按现有公开 `screenColor`、`assetLabel`、`warning` 与 `sliceWarning` 契约更新。
@@ -6763,6 +6763,21 @@
 - 升级前 External 幂等任务可能仍在 payload 中保留客户端 references；重放比较只对白名单内已迁移的图片生成、图片修改、去背景、图标图集和 UI 提取任务，在旧侧有 references、当前侧已删除时移除旧字段，其他字段变化仍返回 `409`。音频 / 视频 / 角色动作等未迁移 job kind 始终完整比较，不能扩大兼容面。
 - 本次复用既有 `external_generation_job.dedupe_key` 唯一索引和 `spacetime-client` 查询，不改 SpacetimeDB schema、迁移或 bindings。
 
+## 2026-08-05 图标规范生成拆分请求预检与最终执行，图集规范引用改为窄事务查询
+
+- 图标规范 HTTP handler 在调用文本 LLM 前，先通过可复用图片请求预检完成参考图稳定性、owner 授权、Provider 配置与运行时定价校验；随后补齐 `ExtraParam` 与最终 prompt，并继续走既有 `editor_image_generation` inline / queue 分流，不新增图标规范专用 worker job。最终执行仍重新校验请求，以处理排队期间发生的权限或资源变化。
+- 图标图集主规范引用由通用 SpacetimeDB procedure `resolve_editor_reference_and_return` 在同一事务快照内解析和校验 owner。ID 使用资源 / 素材主键；objectKey 按规范化 `image_src="/<objectKey>"` 索引读取唯一行，并使用 `asset_object(bucket, object_key)` 复合索引校验对象 owner。procedure 不接收业务 / 存储类型 allowlist，复用既有 `EditorProjectResourceSnapshot` / `EditorAssetSnapshot` 返回完整单行，不新增图标专属 DTO，也不再拉取完整项目和素材库；`icon-spec` 业务类型与游戏类型由 API 业务代码校验和提取。缺失引用、跨 owner、asset object 不匹配、业务类型错误、元数据解析与数据库错误全部失败关闭；仅“合法记录没有 genre”允许返回 `None`。
+- 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-08-06 图标规范与图标图集使用独立任务及 ID-only 主规范引用
+
+- 本条取代上一条“不新增图标规范专用 worker job”和“图标图集主规范允许 objectKey”的结论。图标规范生成使用独立 `editor_icon_spec_generation` job kind；队列保存原始强类型业务参数，worker 在统一计费操作预扣成功后执行 ExtraParam LLM、构建最终 prompt，再进入共享图片生成和既有后处理 / 持久化链。SpacetimeDB 编辑器生成结果 operation kind 白名单必须显式包含该独立 job kind，确保 Provider 成功后可以进入统一 durable receipt 原子提交；新增正式生成 job kind 时必须同步扩展白名单和模块回归。余额不足不调用文本 LLM，执行失败沿用统一退款；普通 `editor_image_generation` 的 DTO、payload 与执行行为保持不变。
+- `editor_project_icon.rs` 独立承接图标规范、图标 spritesheet、自动切片和手工拆分。普通图片模块只暴露可复用的 prompt builder 执行入口与强类型 provider 请求分流；nanobanana、无参考图 generation、有参考图 edit 的选择集中在同一个 helper，图标图集复用该 helper，不复制 provider 分支。
+- 图标规范生成的可选参考图与图标图集的必选主规范统一使用 `referenceId`，只接受当前 owner 的项目资源 ID 或账号素材 ID，不接受 objectKey、URL 或临时 key。SpacetimeDB `resolve_editor_reference_and_return` 因而只接收 `reference_id` 并按两张表主键查询，删除 `image_src` 二级索引。图标图集的普通附加参考图 `referenceImageSrcs` 仍允许 owned objectKey、项目资源 ID 或素材 ID，并继续走既有 owner 校验与真实图片下载链。
+- External v1 图标图集请求与 OpenAPI 同步改为必填 `referenceId`。前端和 Editor Agent 优先传正式 resource ID，其次传 asset ID；本地临时 ID、objectKey 和图片地址不得回退成主规范引用，未登记时明确失败并要求先上传或登记。
+- `resolve_editor_reference_and_return` 的歧义只在当前 owner 范围内判断：两张表先按 `owner_user_id` 过滤，同名但属于其它账号的行不阻断合法引用。记录存在 `asset_object_id` 时按该 ID 定位并同时核对 bucket、object key 与 owner，只有缺少 ID 的兼容旧行才按位置查询。图标规范入队 / inline 预检只验证这组行与对象元数据，最终共享图片执行器再下载一次参考图正文，避免同一引用在入队、worker 预检和生成阶段重复下载。
+- 关联：`server-rs/crates/api-server/src/editor_project_icon.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`docs/openapi/genarrative-external-v1.openapi.json`。
+
 ## 2026-08-06 音效与背景音乐恢复共享音频 Composer
 
 - 决策：图片画布的 `audio-sound-effect` 与 `audio-background-music` 只保留一个 `ImageCanvasAudioGenerationComposerView`，组件内以 `isSoundEffect = dialog.mode === 'audio-sound-effect'` 分流。撤销的是完整 `ImageCanvasBackgroundMusicGenerationComposerView` 这一层视图拆分，不撤销 BGM Prompt 纯模型、助手 controller、预设模型或预设跑马灯的独立职责。

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

@@ -397,7 +397,7 @@
 
 - 现象：画板生成、快速编辑、图标素材或 UI 素材提取如果允许直接提交 generated objectKey，用户只要知道其他账号的私有 objectKey，就可能让 api-server 签名读取并送给外部生成供应商。
 - 原因：Data URL/Blob URL 只允许停留在浏览器临时态，正式编辑器引用必须先上传并经统一 resolver 校验归属。
-- 处理：所有私有对象引用在读取字节或签发 URL 前统一走 `resolve_editor_reference_object_key_for_owner(state, owner_user_id, source)`，先在当前账号的项目资源、素材库资产或 `asset_object` 中匹配 owner / bucket / key。只有确实需要图片字节的入口（生成 / 重绘 / 图标 / UI 提取等交给 provider 的路径）再走 `parse_editor_reference_image`（内部仍先 resolve，再下载 OSS 字节）；手动去背景等只签发短期 URL 的入口不要 `parse` 整图。手动去背景还要恢复源模型时，object key 解析、所有权校验和源模型回溯必须复用同一轮账号项目 / 素材快照，项目与素材快照各最多读取一次；不得先走通用 resolver 全量读取，再为模型回溯重复拉取完整画布和素材库。图标素材等额外参考图必须真实传到 provider，不只写 metadata；图片快速编辑当前不开放额外参考图，若后续重开入口也必须沿用同一归属校验。
+- 处理：普通图片、重绘、图标图集附加参考图和 UI 提取等允许 objectKey 的私有对象引用，在读取字节或签发 URL 前统一走 `resolve_editor_reference_object_key_for_owner(state, owner_user_id, source)`，先在当前账号的项目资源、素材库资产或 `asset_object` 中匹配 owner / bucket / key。只有确实需要图片字节的入口再走 `parse_editor_reference_image`（内部仍先 resolve，再下载 OSS 字节）；手动去背景等只签发短期 URL 的入口不要 `parse` 整图。图标规范生成的可选参考图与图标图集的主规范引用是更窄的业务契约：只接受正式 `referenceId`（项目资源 ID / 素材 ID），不得回退 objectKey、URL 或临时 key；图标图集的额外 `referenceImageSrcs` 才继续沿用通用 owned objectKey 规则。手动去背景还要恢复源模型时，object key 解析、所有权校验和源模型回溯必须复用同一轮账号项目 / 素材快照，项目与素材快照各最多读取一次；不得先走通用 resolver 全量读取，再为模型回溯重复拉取完整画布和素材库。图标素材等额外参考图必须真实传到 provider，不只写 metadata；图片快速编辑当前不开放额外参考图，若后续重开入口也必须沿用同一归属校验。
 - 验证：`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_reference`，并用前端 workflow 测试覆盖 `referenceImageSrcs` 进入图标生成请求；若快速编辑重开额外参考图，再补对应请求覆盖。
 - 关联：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/spacetime-client/src/assets.rs`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`。
 
@@ -4012,7 +4012,7 @@
 ## 画布 Agent 的规划请求不能关闭瞬时失败重试
 
 - 现象：美术 Agent 对话返回红色错误气泡 `completion error: LLM 请求超时，累计尝试 1 次`；HTTP 本身仍返回 200，前端 20 分钟 transport timeout 没有触发。
-- 原因：规划请求虽然有 Agent 专用单次 timeout，但 `editor_agent_llm_client` 把 `max_retries` 硬编码为 0；VectorEngine `gpt-5.4-mini` 的偶发长尾、连接超时或可重试上游状态会在第一次失败后直接持久化成 system error。framework 的英文 `completion error` 前缀也被原样暴露给用户。
+- 原因：规划请求虽然有 Agent 专用单次 timeout，但 `vector_engine_llm_client` 把 `max_retries` 硬编码为 0；VectorEngine `gpt-5.4-mini` 的偶发长尾、连接超时或可重试上游状态会在第一次失败后直接持久化成 system error。framework 的英文 `completion error` 前缀也被原样暴露给用户。
 - 处理：120 秒改为前端软提示阈值：POST 仍 pending 时显示不入库的“仍在处理中，请耐心等待”；provider 明确断开/失败才写正式错误。专用 provider 单 attempt 使用 8 分钟 hard timeout，请求发起阶段读取 `GENARRATIVE_LLM_MAX_RETRIES`，但画布 Agent 最多重试 1 次且重试退避最多 60 秒。不要只计算单次 complete 的最坏时间：runner 还可因非法 JSON/工具校验失败进入后续轮次，必须从 handler 入口开始计算 18 分钟总 deadline，进入 `agent.prompt(...)` 时扣除会话锁/上下文准备已用时间，为持久化和前端 20 分钟 timeout 留出余量。响应头后的体读取/解析错误按明确失败收口，必须使用真实 attempt 计数；规划、配置和定价错误对用户统一为中文，原始诊断只记后端日志。重试发生在任何生成工具执行前，不会重复提交生成任务或扣费，不要通过提高前端 timeout 或 runner `max_turns` 掩盖 provider 重试缺失。
 - 验证：`platform-editor-agent` 测试锁定 8 分钟 hard timeout 与中文错误；前端 fake timer 用例锁定 120 秒前只显示思考动画、到点后显示耐心等待、成功/失败后移除；`platform-llm` 回归用例锁定第二次 attempt 成功响应头后的 body timeout 仍报累计 2 次；`api-server` 测试锁定专用 client retry、18 分钟整体 deadline 与中文直达错误。运行态排障按同一 request id 对齐 `platform_llm` failure stage 与 `/messages` 总耗时，并确认仍 pending 的请求不再在 120 秒形成错误气泡。
 - 关联：`server-rs/crates/platform-editor-agent/src/agent/agent.rs`、`server-rs/crates/platform-agent-harness/src/error.rs`、`server-rs/crates/api-server/src/state.rs`、`src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.ts`、`src/components/image-editor/EditorAgentConversation/MessageBubble.tsx`、`src/services/image-editor/editorAgentClient.ts`。

docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md

@@ -857,7 +857,7 @@ game-project/
 - 自动验收现在严格要求 manifest 恰好包含固定 16 个不重复 task ID 且全部为 `completed`，并逐任务核对当前父 Run 下唯一 logical run、一次 started、一次 completed、零 failed / cancelled 和一次 manifest projection；七份基础正式产物存在并满足文件 / JSON / 非占位入口检查，配置画布 API Key 时再增加 `art-spec / ui-prototype / art-spritesheet` 三张图片。PNG 验收不止检查 magic / IHDR / 比例，还会校验 chunk CRC、zlib 解压、scanline 长度、索引色 PLTE 和未知 critical chunk。Runtime 根 Supervisor 的完成合同已升级为 `game-creator-autonomous-completion-contract.v2`，`baselineArtifacts` 必填并纳入指纹，旧 v1 或缺基线合同失败关闭；最终门禁要求最后一次验证工具是 `game.static_smoke`、状态通过且 `verifiedRevision == currentRevision`。`preview.validate` 回执必须绑定同一 Agent、run、current revision、当前 `game/index.html` 摘要、固定试玩场景、持久浏览器报告以及 desktop / mobile 两张截图的路径、摘要和 PNG 身份，任一证据缺失、变化、过期或来自其它 run / revision 都阻止最终回复。旧两图合同的确定性证据不替代新三图 DAG 验收；新合同实现后必须新起独立单轮。
 - `design-foundation` 已增加专属职责边界：项目文件只允许写 `memory/project.md` 与 `game/game_design.md`；配置 External Editor API Key 且合同要求界面原型时，只额外允许固定 `assets/ui-prototype.png`。它不得创建、修改、删除或补丁 `game/index.html`，不得改动其它程序实现、发布、音频或美术素材，也不得调用 `preview.start`、`preview.validate`、`game.static_smoke`，或借 `command.exec / command.start / command.run_limited` 启动预览服务、浏览器、Playwright 和桌面 / 移动试玩。程序和质量 Agent 的共享 Runtime 工具合同不因此缩减；有 / 无画布配置和其它 Agent 不受影响的聚焦回归为 `3/3` 通过。
 - `canvas.asset_generate.replaceExisting` 默认并必须保持 `false`；只有静态专业 Agent 的 `delegated-*` 唯一 repair run 才能申请 `true`。Runtime 要求当前 delivery 带 `repairOfDelegationId`，原 delivery 已被同一父 Agent / 父 run 认领，原始与返工合同的目标 Agent 和精确 `expectedArtifacts` 路径一致；普通 run、未声明路径、错误 Agent、未认领原交付或缺失原图都失败关闭。图片生成仍服从 `art-director` / `design-foundation` / `art-asset-plan` 的固定输出路径、比例、尺寸、kind 和 label，禁止先删除正式图片；请求前记录旧文件 SHA-256，外部生成返回后在项目写锁内复核，旧图在网络请求期间变化即拒绝覆盖。授权替换先写私有临时文件，再以备份 / rename 切换；落盘或 manifest 登记失败时恢复旧图，不把新旧文件并存状态当作成功。
-- 2026-07-28 起，在既有 16-task manifest 内固定正式视觉 DAG，不新增平行任务系统：`art-director` 先通过 `/api/external/v1/editor/images/generations` 的 `kind=spec` 生成 `assets/art-spec.png`，并登记为 `assetKind=icon-spec`；`design-foundation` 使用该规范图的 External Editor 稳定资源 ID 作为 `referenceImageSrcs` 中的视觉规范参考，再通过同一 images 接口的 `kind=ui-design` 生成完整 `assets/ui-prototype.png`；`art-asset-plan` 以同一 `assets/art-spec.png` 资源 ID 作为必填 `referenceImageSrc` 调用 `/api/external/v1/editor/icon-spritesheets/generations`，传入具体 `iconDescriptions`、`screenColor=auto`、同名画布 / 素材库与 `canvasCompletion`，生成透明 `assets/art-spritesheet.png`。`generationInputs.artSpec` 只是辅助结构化上下文，不能代替真实 `art-spec.png`；严禁把 `assets/ui-prototype.png` 当作图集规范图。规范图缺失、未登记为当前画布的 `icon-spec` 或缺少稳定资源 ID 时，两个下游任务均等待 `art-director`，不得退回普通生图。UI extraction 只适用于已有且带红框标注的 UI 设计图，不用于生成完整 UI，也不进入本次 canonical DAG。单波最多 `3` 个静态职责的资源上限保持不变，只调整现有任务的依赖边与就绪顺序。图集返回 `warning` 时以 `postprocess-failed-source-preserved` 源图保留语义失败关闭，不把不透明源图登记为正式 spritesheet，也不自动重试；仅有 `sliceWarning` 时完整透明图集仍可登记，但必须原样保留切片失败原因。客户端下载后还要解码 PNG 并确认至少存在一个 alpha 小于 255 的像素，未形成真实透明像素时拒绝落盘和 manifest 登记。
+- 2026-07-28 起，在既有 16-task manifest 内固定正式视觉 DAG，不新增平行任务系统：`art-director` 先通过 `/api/external/v1/editor/images/generations` 的 `kind=spec` 生成 `assets/art-spec.png`，并登记为 `assetKind=icon-spec`；`design-foundation` 使用该规范图的 External Editor 稳定资源 ID 作为 `referenceImageSrcs` 中的视觉规范参考，再通过同一 images 接口的 `kind=ui-design` 生成完整 `assets/ui-prototype.png`；`art-asset-plan` 以同一 `assets/art-spec.png` 资源 ID 作为必填 `referenceId` 调用 `/api/external/v1/editor/icon-spritesheets/generations`，传入具体 `iconDescriptions`、`screenColor=auto`、同名画布 / 素材库与 `canvasCompletion`，生成透明 `assets/art-spritesheet.png`。`generationInputs.artSpec` 只是辅助结构化上下文，不能代替真实 `art-spec.png`；严禁把 `assets/ui-prototype.png` 当作图集规范图。规范图缺失、未登记为当前画布的 `icon-spec` 或缺少稳定资源 ID 时，两个下游任务均等待 `art-director`，不得退回普通生图。UI extraction 只适用于已有且带红框标注的 UI 设计图，不用于生成完整 UI，也不进入本次 canonical DAG。单波最多 `3` 个静态职责的资源上限保持不变，只调整现有任务的依赖边与就绪顺序。图集返回 `warning` 时以 `postprocess-failed-source-preserved` 源图保留语义失败关闭，不把不透明源图登记为正式 spritesheet，也不自动重试；仅有 `sliceWarning` 时完整透明图集仍可登记，但必须原样保留切片失败原因。客户端下载后还要解码 PNG 并确认至少存在一个 alpha 小于 255 的像素，未形成真实透明像素时拒绝落盘和 manifest 登记。
 - 旧项目已有同路径派生图但缺少上述 provenance 时，一律标记为 legacy，不得只因文件、kind 或通用视觉检查存在就完成。原位替换仍走显式 repair：`design-foundation` 与 `art-asset-plan` 先在同一 Supervisor 批次分别建立 owner 精确原合同并交付 `needs-repair`，父 run 认领后再在同一批次分别发起各自唯一 repair；两个 repair 合称一个显式视觉返工阶段。`art-director` 不得跨 owner 声明或替换 UI / spritesheet，Runtime 在委派落盘前就拒绝这类合同，不再等到生图阶段才失败。
 - 2026-07-27 新起的“16 任务正式产物 + 两张真实画布图片 + current revision 静态 / 双视口浏览器 / PNG 证据 + 受限 repair 替换”独立外部 Provider 验收，使用 `npm run agc:test:chat -- --timeout-minutes 75`，约 `59m50s` 后以退出码 `0` 完整 **PASS**。同一轮真实生成并登记 `assets/ui-prototype.png`（`2829418` bytes）与 `assets/art-spritesheet.png`（`1361906` bytes），固定 `16` 个 manifest task 均为当前父 Run 下唯一 logical run、一次 started、一次 completed、零 failed / cancelled 和一次 manifest projection；七份基础正式产物、两张 PNG、当前 revision 的 `game.static_smoke`、desktop / mobile `lane-defense-v1` playtest、浏览器报告与截图全部通过。`turn.report=settled` 且唯一 assistant，busy / pending / running / confirmation / user-input / reconciliation 均为 `0`；隔离 Runner、一次性项目和隔离 AppData 已自动清理。此前失败轮继续独立保留，不与本轮拼接；未来合同变化仍须新起完整轮次复验。
 - 2026-07-27 补充 tool-plan 成功响应交接的内容边界：Provider 的自然语言计划叙述，以及结构化 arguments 中 `body / code / content / css / html / newText / oldText / patch / script / text` 等源码内容字段，只检查真实密钥 token 形状、凭据头标记和不安全控制字符；仅仅提及 `.env` 或 `game-creator.config` 不能阻断已经计费的安全响应。结构化输入中的敏感 JSON key、非内容字段中的配置痕迹或绝对路径、真实 token、容量、thinking、身份、顺序和账本完整性门禁仍失败关闭。成功 handoff 失败进入 reconciliation 时，Runtime 额外只持久化受控 `failureKind`、脱敏错误 SHA-256 和字符数，不保存 Provider 正文、function arguments、密钥或绝对路径。定向回归覆盖叙述/源码字段放行、`.env.local` 路径和真实 token 拒绝、全部 tool-plan handoff 回归及诊断零正文。

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

@@ -83,6 +83,7 @@ npm run check:server-rs-ddd
 - 完整消息文档存 OSS `editor-agent/{conversationId}.json`，由 `api-server` 负责 2 MiB 上限、会话内串行锁、读改写、消息与工具结果持久化和 `touch` 元数据更新时间；该 JSON 不进入 `editor_canvas.layers_json`，也不作为画布布局真相。LLM 未配置、连接已经断开、请求明确失败、达到最终安全上限或规划不可解析时，必须写入 `role=system`、正文以 `ERROR ` 开头的消息，并通过 `deltaMessages` 返回，`errorMessage` 保持为空；前端隐藏前缀并显示红色错误气泡，面向用户的错误正文使用中文语义，不暴露 `completion error` 等 framework 内部前缀或原始配置/定价错误；原始诊断只写后端结构化日志。后端仍把该 system 消息注入后续 LLM memory，使 Agent 能读取失败上下文。普通 JSON POST 尚未结束不形成持久化消息；工具失败同样必须形成可回读记录，不能只返回瞬时错误。
 - 画布 Agent 的 `gpt-5.4-mini` Chat Completions 规划使用 1024 生成 token 预算；VectorEngine 专用 client 显式发送当前字段 `max_completion_tokens`，其预算包含可见输出和隐藏 reasoning token。通用 OpenAI-compatible client 默认保留旧 `max_tokens`，只有确认 endpoint 能力后才 opt-in，禁止按模型名猜测或在 `400` 后自动重放。前端在 POST pending 120 秒后显示不入库的耐心等待提示；provider request future 明确返回 connect/timeout/HTTP/transport 错误时立即进入正式失败，尚未返回则继续等待。专用 provider 单 attempt hard timeout 为 8 分钟；请求发起阶段的 timeout、连接失败、`408`、`429` 与 `5xx` 读取 `GENARRATIVE_LLM_MAX_RETRIES`，但画布 Agent 最多重试 1 次，显式配置 0 仍可关闭，专用重试退避最多 60 秒。消息规划生命周期从 handler 入口开始计入 18 分钟总 deadline，进入 `agent.prompt(...)` 时只使用剩余预算；该 deadline 覆盖会话锁/上下文准备与最多 3 轮规划，并为错误持久化/HTTP 返回预留约 2 分钟，不允许多轮规划绕过前端 20 分钟 timeout。已收到成功响应头后的响应体读取或解析失败直接按明确失败收口，并使用该成功响应所属的真实 attempt 记录错误。重试只包围 LLM 规划请求并发生在任何待确认工具执行之前，因此不会重复提交生成任务或扣费。
 - 对话附件只允许引用当前工程 `editor_project_resource` 或当前账号 `editor_asset` 的图片；前端可提交展示用 `imageSrc` / `thumbnailSrc`，后端必须按 `resourceId` / `assetId` 重新归一、校验 owner / project 和 `objectKey`，再给 LLM 或生成工具使用。
+- 工具上下文不得把 OSS 消息附件当作 `assetKind` 真相；每次规划和每次确认都按附件 `source + referenceId` 经 `spacetime-client` 重新读取当前工程资源或账号素材库，只把权威 `asset_kind` 放入服务端内存 `ImageMetadata`。图标 spritesheet 的主参考必须精确为 `icon-spec`，普通图片或风格参考图只能作为额外参考；主参考类型缺失、已删除或不是 `icon-spec` 时必须在生成任务入队和用户确认生效前失败关闭，并提示重新选择图标规范。
 - `edit-image` 只接受当前图片上下文中的 `object_image_id`；`source_image_id` 不是现役 schema 字段，prompt、tool args、确认执行和测试中都不得生成或兼容该字段。
 - 画布 Agent 工具复用既有编辑器图片生成 / 修改 / 图标 spritesheet BFF，并继续使用后端模型定价和 `execute_billable_asset_operation_with_cost`；前端不提交 `priceMudPoints`。
 - api-server 对 `PromptRunError` 的持久化顺序固定为：先按 `partial_outputs` 原顺序映射已成功工具，将其保存为 `status=not_completed` 且无 `externalJobId` 的待确认消息；再在同一会话增量末尾追加 `ERROR ` terminal system 消息并整体写入 OSS。后续规划失败不得吞掉失败前已执行的成功工具结果；结构化 `ToolFailed` 可用于调用方诊断与流程决策，但画布确认面不得把它伪装成成功待确认卡。
@@ -243,7 +244,7 @@ npm run check:server-rs-ddd
 6. 编辑器图片生成 / 图片修改 / 图标 spritesheet / UI 设计图提取素材 / 视频 / 角色动作 / 音效 / 背景音乐必须在后端计算模型价格后使用 `execute_billable_asset_operation_with_cost` 预扣泥点；预扣失败必须 fail-closed，不得继续提交 VectorEngine、Ark、Suno 或 Vidu 上游任务。进入预扣或外部生成队列前，还必须调用只读 `preflight_editor_generation_target_and_return`，按认证 owner 校验可选 `projectId`，并校验归一化后的可选 `assetFolderId`。请求 JSON、纯本地格式、引用数量及 `data:` / `blob:` 稳定媒体门禁必须先于该数据库预检返回 4xx；目标预检随后执行，并且仍必须早于定价读取、引用 owner 解析、generation input rebuild、入队、扣费、provider 请求或 OSS 写入，不得为调整错误优先级把任何远端读取或副作用搬到预检前。`project`、任意旧 `folder-*` 与 owner 默认目录 ID 都统一指向当前 owner 的默认素材目录；角色图片、角色动作、图标 spritesheet 与 UI 提取在请求省略目录时也必须按最终真实写入的默认目录预检。尚未创建的默认目录允许通过，自定义目录必须已存在且归属当前 owner。预检 helper 必须返回同一份 canonical `projectId + assetFolderId`，调用方在入队、worker/provider 执行和原子结果准备中都复用这份值；禁止校验 trim/默认映射后的值却继续序列化或持久化原始请求。worker / inline 执行在首个 provider 或 OSS 写副作用前再次执行同一预检，不能只信任入队时结果；任一读取不可达、超时、项目或目录不匹配都失败关闭。该预检不创建锁或 reservation，最终资源 / 素材 procedure 仍必须重新校验归属，以处理预检后并发删除或转移。
 7. 队列任务按 `job_id + claim_attempt` 使用独立 consume/refund ledger。新 attempt 结算旧 attempt 时必须先写 `asset_operation_wallet_settlement`：旧 consume 已存在则原子退款，尚不存在则写取消 intent；迟到 consume 在同一 SpacetimeDB 事务内看到 intent 后必须失败关闭。重复 consume/refund 只有用户、金额、来源和配对 ledger 全部一致时才可视为幂等成功。lease 过期时只有 `attempt < max_attempts` 才能递增并重领；最终 attempt 已耗尽时，claim transaction 必须直接把 job 收口为 `failed`、清理 lease、写失败事件并结算当前 attempt，不能再把任务返回 worker 或调用 provider。
 8. 音频生成的编辑器链路虽然任务提交和结果发布分离，仍必须把提交时后端计算出的模型价格写入 `AudioAssetBindingTarget.billing_points_cost`，最终发布落资产时按该价格扣费；创作音频目标未提供该字段时才使用旧的创作音频固定成本。
-9. 编辑器进入外部生成持久队列的图片生成、图片修改、去背景、图标 spritesheet、UI 设计图提取、角色动作和视频参考图，调用方必须提交 `objectKey` / `resourceId` / `assetId` 候选引用；BFF 对生成目标执行上一条只读 owner / project / asset folder 预检，但参考媒体的登记状态和归属仍由 worker 统一解析。任务 `request_payload_json` / `result_payload_json` 任意层级都禁止 `data:` / `blob:`，并受统一字节上限保护。无效普通参考字符串可以入队，但必须在签名和 provider 调用前失败；若以后要求无效参考引用同步返回 400，应作为独立改造。objectKey 最终必须归属于当前账号的 `editor_project_resource`、`editor_asset` 或 `asset_object`，由 worker 在解析后、签名读取 OSS 前完成归属校验。本地红框序号标注图必须先上传并确认对象，再把 objectKey 入队；不得把既有 objectKey 下载成 Data URL 后写入任务。图标素材、图片快速编辑和 UI 素材提取的额外参考图必须真正传入 provider，不得只写入 `generationInputs` 展示快照。普通图片生成最多 5 张参考图；图片修改、图标素材和 UI 提取的额外参考图上限还必须与所选 provider 的总容量共同取最小值：GPT-image-2 总计 5 张，nanobanana2 总计 14 张。前端添加和提交、api-server 入队 / 扣费前以及 `platform-image` provider 边界都必须明确拒绝超限，禁止用 `.take(...)` 静默截断。同步且不持久化的历史兼容入口即使仍能解析 Data URL，也不能把该值转存到工程、素材、元数据、审计或任务表。
+9. 编辑器进入外部生成持久队列的图片生成、图片修改、去背景、图标 spritesheet、UI 设计图提取、角色动作和视频参考图，调用方必须提交 `objectKey` / `resourceId` / `assetId` 候选引用；BFF 对生成目标执行上一条只读 owner / project / asset folder 预检，但参考媒体的登记状态和归属仍由 worker 统一解析。任务 `request_payload_json` / `result_payload_json` 任意层级都禁止 `data:` / `blob:`，并受统一字节上限保护。无效普通参考字符串可以入队，但必须在签名和 provider 调用前失败；若以后要求无效参考引用同步返回 400，应作为独立改造。objectKey 最终必须归属于当前账号的 `editor_project_resource`、`editor_asset` 或 `asset_object`，由 worker 在解析后、签名读取 OSS 前完成归属校验。本地红框序号标注图必须先上传并确认对象，再把 objectKey 入队；不得把既有 objectKey 下载成 Data URL 后写入任务。图标规范结构化分析里位于 `<playSetting>` / `<artStyle>` XML 元素内的数据必须转义 `& < > " '`；玩法润色、美术风格润色、规范图生图和图标 spritesheet 等自然语言 prompt 则必须保留已经过边界校验的原文，不得把 `R&B`、引号或尖括号改写成 XML entity。图标 spritesheet 的 `iconDescriptions` 还必须在请求边界执行独立合同：原始数组先满足 OpenAPI `1..100`，再去空且至少保留 1 条；单条最多 `200` 个 Unicode 字符、换行拼接后合计最多 `2000` 个 Unicode 字符且不超过 `6144` 个 UTF-8 字节；只有 `ValidatedEditorIconSpritesheetPrompt` 能进入 prompt builder，External v1 超限同步返回 `400`。图标素材、图片快速编辑和 UI 素材提取的额外参考图必须真正传入 provider，不得只写入 `generationInputs` 展示快照。普通图片生成最多 5 张参考图；图片修改、图标素材和 UI 提取的额外参考图上限还必须与所选 provider 的总容量共同取最小值：GPT-image-2 总计 5 张，nanobanana2 总计 14 张。前端添加和提交、api-server 入队 / 扣费前以及 `platform-image` provider 边界都必须明确拒绝超限，禁止用 `.take(...)` 静默截断。同步且不持久化的历史兼容入口即使仍能解析 Data URL，也不能把该值转存到工程、素材、元数据、审计或任务表。
 10. 已有静态图片的 `POST /api/editor/images/pixel-art-snaps` 是免费 inline 派生操作，不调用外部 provider、不创建 `external_generation_job`、不读写泥点 ledger，也不进入任务侧栏。免费不放宽 owner、稳定引用、输入上限、持久化或处理阶段零持久化门禁。
 11. 主站编辑器生成队列使用同一次前端请求稳定复用的 `x-request-id`，按 namespace + owner + job kind + request id 生成唯一 `dedupe_key`；首次请求已入队但响应丢失时，重试必须返回原任务。同一幂等键携带不同 payload 返回 `409`，不得创建第二个任务或串到旧结果。外部 v1 的 `Idempotency-Key` 使用独立 namespace，不能与主站请求标识碰撞。幂等 payload 比较只对本次已迁移 sanitizer 的图片生成、图片修改、去背景、图标图集和 UI 提取任务，兼容“升级前旧任务仍含客户端 `generationInputs.references`、当前请求已删除该字段”的单向形状；当前请求仍含 references，或 job kind 属于音频 / 视频 / 角色动作等未迁移任务时必须完整比较，其余请求字段始终完全一致。
 12. `generationInputs.references` 是最终资产的服务端权威行引用，不接受客户端自报 provenance。图片生成类请求入队、完美像素及直接创建资源 / 素材时删除客户端 references；worker 和 inline 路径按本次真实参考图、当前 owner 的项目资源 / 素材记录重建 `refType/refId` 后再持久化。仅能证明 owned objectKey、但找不到对应资源或素材行时可以参与生成，不得制造虚假行引用；`title/label` 只作为展示快照，不提升为资源身份。完美像素为兼容升级前的未知结果重放，可继续用旧版 canonical 客户端输入计算 operation fingerprint；新操作持久化元数据只能使用服务端重建值，检测到 owner 项目中已存在同一稳定 task/resource 的历史结果时则复用该服务端既存 metadata 完成精确 compare-and-return。
@@ -739,7 +740,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 
 - Rust 结构体：`EditorGenerationOperation`
 - 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
-- 说明：编辑器生成结果的私有 durable commit receipt，queue 与受控 inline 路径共用。主键 `operation_key` 由 owner 与 operation ID 稳定派生，同 owner 不得跨 kind 复用 operation ID；`operation_fingerprint` 绑定规范用户请求，`commit_sha256` 绑定全部 slot 候选、object/resource/asset/binding、可选 canvas 候选与 job completion。表内另固化 owner/kind/ID、可选 `project_id`、queue 的 `job_id / job_worker_id / job_lease_token / job_result_payload_sha256` 和首次提交时间；重放从已完成 job 回读权威 compact result 并核对摘要，不在 receipt 复制正文。它只证明一笔业务结果已原子提交，不是第二套 job 状态或 resource/asset/canvas read model，不保存大快照。
+- 说明：编辑器生成结果的私有 durable commit receipt，queue 与受控 inline 路径共用。主键 `operation_key` 由 owner 与 operation ID 稳定派生，同 owner 不得跨 kind 复用 operation ID；`operation_fingerprint` 绑定规范用户请求，`commit_sha256` 绑定全部 slot 候选、object/resource/asset/binding、可选 canvas 候选与 job completion。表内另固化 owner/kind/ID、可选 `project_id`、queue 的 `job_id / job_worker_id / job_lease_token / job_result_payload_sha256` 和首次提交时间；重放从已完成 job 回读权威 compact result 并核对摘要，不在 receipt 复制正文。它只证明一笔业务结果已原子提交，不是第二套 job 状态或 resource/asset/canvas read model，不保存大快照。结果提交的 operation kind 白名单必须覆盖所有进入统一持久化的正式 job kind，其中包括独立图标规范任务 `editor_icon_spec_generation`；新增 job kind 时必须在同一变更中同步白名单和模块回归。
 - 重放：receipt 存在时必须核对全部绑定和权威记录，完全一致才返回 `AlreadyApplied`；同 operation 的请求或提交摘要漂移、project/job 绑定漂移、receipt 缺失但稳定 resource/asset/binding 等业务记录已存在均失败关闭。事务前单独确认的 asset object 只在全部字段与稳定候选完全一致时允许复用，不能据此补造 receipt。重放不更新 receipt 时间，不重复 job/binding 事件，不推进 canvas revision。
 - 时间：`completed_at_micros` 必须为正数并固化为 receipt 完成时间；object/resource/asset/binding/canvas 候选的原时间字段与它一起进入 commit SHA-256，重放必须复用原 prepared commit 而不得重新取时。queue job 完成时间与完成事件仍使用 SpacetimeDB `ctx.timestamp`，不信任调用方时钟。
 - 索引：主键 `operation_key`；`by_editor_generation_operation_owner(owner_user_id, operation_id)` 仅用于受控定位和诊断，不允许同 owner 跨 operation kind 复用同一 operation ID。

docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md

@@ -38,10 +38,12 @@
    - 生成角色：`你希望角色如何设计？`
    - 生成 UI：`你希望这个 UI 长什么样？`
    - 生成视频：`你希望生成什么视频？`
-8. 多输入框面板必须保留每个字段标题和输入框边界，例如生成规范。图标素材生成不再使用多描述列表，改为复用角色形象生成面板同款单文本输入框。
+8. 多输入框面板必须保留每个字段标题和输入框边界，例如生成规范。图标素材生成不再使用多描述列表，改为复用角色形象生成面板同款单文本输入框；该完整文本按 Unicode 字符限制为 `200`，输入时按 code point 截断，不能用 UTF-16 `maxLength` 误截 emoji。
 9. 生成规范下的角色规范、图标规范和自定义规范都使用同一生成类 shell：首行参考图区域、中央字段区、底部生成按钮区，不再出现缺首行参考区或单独 footer 样式。
-10. 图片快速编辑不展示额外参考图入口；原图或绘制了红框和序号的标注图始终作为 `/api/editor/images/edits` 的 `sourceImageSrc` 直接提交，不作为 `referenceImageSrcs`。
-11. 快速编辑打开后，画布视口应调整到原图完整展示，且面板位于原图下方并不遮挡原图；原图右侧显示竖向框选工具，支持矩形、椭圆和画笔自由框选。快速编辑进入时不默认启用框选工具，点击工具后出现选中态并保持高亮，再点同一工具取消启用；红色圈选框使用细描边。每完成一次框选，红色圈选框按完成顺序标注 `1 / 2 / 3...`，并在快速编辑提示词中追加一行 `对N号红色圈选框里的内容做以下修改：`。
+10. 图标规范只使用 `specType="icon"`，历史 `specType="ui"` 快照在恢复边界迁移为 `icon`。表单字段使用 `playSetting / artStyle`，界面标题继续使用「玩法设定 / 美术风格」。两项初始为空且必填，客户端提交前统一 trim 并拒绝空白值；每项独立支持一键优化、处理中锁定自身、成功后单次撤销，操作行最右侧按 Unicode 字符实时显示 `当前数/200`。撤销必须恢复优化前的原始输入（包括首尾空白）；手工编辑后立即清除该字段已经失效的撤销快照，失败只保留当前文本与仍然有效的旧撤销快照。LLM 返回空文本、超长文本、Markdown / 结构化内容，或 finish reason 明确表示截断、过滤、失败时，后续有界重试必须携带上次无效输出和对应修正要求，不能把未完成前缀当作成功结果。优化请求必须绑定发起时的生成对象 ID 和请求代次；活动对象身份只在 React effect 提交后更新，并在 cleanup 中失效，丢弃的并发 render 不得改变请求归属；对象切换或新请求取代旧请求后，旧成功或失败结果都不得更新当前面板。任一项处理中或任一项为空时禁用生成。字段标题使用真实 label 关联 textarea，不得把优化 / 撤销按钮包进 label。控件继续使用平台默认样式，不新增图标规范专属 CSS。
+11. 图标规范最终生成改走 `POST /api/editor/icon-specs/generations`。前端只提交业务字段和统一参考图 / 项目完成包络，不拼最终 prompt，不提交 `kind / assetKind / ExtraParam`；可选参考图字段为 `referenceId`，只允许当前 owner 的项目资源 ID 或素材 ID。后端固定以 `kind=spec / assetKind=icon-spec / gpt-image-2 / 16:9·2K` 执行图片生成。inline 路径校验业务字段和 `referenceId` 后，补全 `ExtraParam` 与最终 prompt 并交给共享图片生成执行器；queue 路径在预校验后按 `gpt-image-2 / 2K` 运行时定价冻结价格，再以独立 `editor_icon_spec_generation` job kind 入队原始业务载荷。worker 使用入队价格和当前 claim attempt 的计费上下文，重新解析载荷、校验当前 owner 与引用事实，再补全 `ExtraParam` 并调用同一共享图片生成执行器，避免排队期间状态变化产生 TOCTOU。
+12. 图片快速编辑不展示额外参考图入口；原图或绘制了红框和序号的标注图始终作为 `/api/editor/images/edits` 的 `sourceImageSrc` 直接提交，不作为 `referenceImageSrcs`。
+13. 快速编辑打开后，画布视口应调整到原图完整展示，且面板位于原图下方并不遮挡原图；原图右侧显示竖向框选工具，支持矩形、椭圆和画笔自由框选。快速编辑进入时不默认启用框选工具，点击工具后出现选中态并保持高亮，再点同一工具取消启用；红色圈选框使用细描边。每完成一次框选，红色圈选框按完成顺序标注 `1 / 2 / 3...`，并在快速编辑提示词中追加一行 `对N号红色圈选框里的内容做以下修改：`。
 
 ## 参数交互
 
@@ -77,7 +79,7 @@
 - 本次消耗泥点必须显示在生成按钮内部。
 - 生成按钮内明确显示 `N泥点`，例如 `生成12泥点`、`生成40泥点`；不使用泥点图标替代文字。
 - 画板内所有会提交外部生成任务的按钮，展示价格都必须从模型定价配置函数推导，不允许在按钮文案中散落固定泥点数字；生成请求不提交 `priceMudPoints`，修改后端模型定价配置后，后端实际扣费和前端下一次拉取到的按钮展示应同步变化。
-- 后端所有编辑器外部生成入口必须按运行时模型定价配置计算价格后进入 `execute_billable_asset_operation_with_cost`：`/api/editor/images/generations`、`/api/editor/images/edits`、`/api/editor/icon-spritesheets/generations`、`/api/editor/ui-designs/assets/extractions`、`/api/editor/videos/generations`、`/api/editor/character-animations/generations`、`/api/editor/audios/sound-effects/generations`、`/api/editor/audios/background-music/generations` 都不能只展示价格而不真实预扣钱包。
+- 后端所有编辑器外部生成入口必须按运行时模型定价配置计算价格后进入 `execute_billable_asset_operation_with_cost`：`/api/editor/icon-specs/generations`、`/api/editor/images/generations`、`/api/editor/images/edits`、`/api/editor/icon-spritesheets/generations`、`/api/editor/ui-designs/assets/extractions`、`/api/editor/videos/generations`、`/api/editor/character-animations/generations`、`/api/editor/audios/sound-effects/generations`、`/api/editor/audios/background-music/generations` 都不能只展示价格而不真实预扣钱包。
 - 当前前端展示价统一收口在 `ImageCanvasGenerationModel.ts`：生成图片、生成角色、快速编辑、重绘、宣发素材走 `calculateEditorImageModelPrice` / `calculateEditorImageGenerationPrice`；生成图标素材走 `calculateEditorIconSpritesheetPrice`；生成 UI 设计图走 `calculateEditorUiDesignPrice`；生成规范走 `calculateEditorSpecGenerationPrice`；生成视频走 `calculateEditorVideoPrice`；角色动作走 `calculateCharacterAnimationPrice`；音效 / 背景音乐分别走 `calculateEditorSoundEffectPrice` / `calculateEditorBackgroundMusicPrice`。这些函数启动时会被后端下发配置覆盖，接口失败时才使用内置兜底。定价配置只按模型区分，不按图片 / 规范、视频 / 动作用途拆分；图片类价格必须同时传入模型和 `imageSize`，规范固定读取 `gpt-image-2` 的 `2K` 定价。
 - 泥点配置默认值独立收口到 `server-rs/crates/api-server/config/editor-generation-pricing.default.json`，JSON 结构为 `models[model] = { unit, price | prices }`；后台“模型定价”页面通过 `POST /admin/api/editor-generation-pricing` 保存完整配置到 SpacetimeDB `editor_generation_pricing_config` 全局表，主站通过 `GET /api/editor/generation-pricing` 动态读取当前配置。后台必须展示定价单位：`perGeneration` 显示“按次”，`perSecond` 显示“按秒”。
 - 生成图标素材、生成视频、角色动画、音效和背景音乐请求只提交生成参数，不提交价格字段；后端按归一后的模型、清晰度、时长或音频模型重新计算并扣费。

docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md

@@ -2,7 +2,7 @@
 
 日期：`2026-06-15`
 
-更新时间：`2026-07-29`
+更新时间：`2026-08-07`
 
 ## 背景
 
@@ -16,7 +16,7 @@
 - 图标素材面板锚定在占位图下方，和现有生成输入框同一层级展示。
 - 透明背景处理正常成功后删除占位态：透明 spritesheet 作为主图（`assetKind: "icon-spritesheet"`，`generatedLayerId` 锚点）放入画布，provider 带背景原图作为第二个同类型图层放在透明主图右侧，按 alpha 连通域成功拆出的 `assetKind: "icon"` 素材从原图右侧继续铺放；透明背景处理最终失败时，后端完成快照只用 provider 原图替换占位态。
 - 选中 `assetKind: "icon-spritesheet"` 图层时，图片浮动工具栏显示 `拆分图集`；手动拆分只追加独立素材，不复制原图集。
-- 用户把现有图层手动标记为“图集”时，必须先持久化一条 `assetKind: "icon-spritesheet"` 的项目资源并把返回的 `resourceId` 写回图层；项目资源只能在媒体来源和 `assetKind` 都相同时复用，不得因同源图片而返回旧类型资源。持久化完成前必须禁用“拆分图集”，持久化失败时回滚到上一个已确认的素材标签和资源引用，并失效该轮未确认的标签撤销记录。
+- 用户把现有图层手动标记为“图集”时，必须先持久化一条 `assetKind: "icon-spritesheet"` 的项目资源并把返回的 `resourceId` 写回图层；项目资源只能在媒体来源和 `assetKind` 都相同时复用，不得因同源图片而返回旧类型资源。持久化完成前必须禁用“拆分图集”，持久化失败时回滚到上一个已确认的素材标签和资源引用，并失效该轮未确认的标签撤销记录。后端拆分授权只信任该项目资源的 `assetKind`，图层 `assetKindOverride` 仅用于展示，不能把其它资源提升为可拆分图集。
 - 图标规范图写入 `assetKind: "icon-spec"`，用于刷新后保留标签和限制点选来源。
 
 ## 面板结构
@@ -25,7 +25,7 @@
    - 点击后弹出菜单：`从画布中选择`、`新建图标规范`、`上传图片`。
    - `从画布中选择` 进入画布点选状态，只允许选择 `assetKind: "icon-spec"` 的图标规范图片；其它图片点击无效。
    - `新建图标规范` 复用生成规范表单，规格类型为 `图标规范`，生成成功后图层标记为 `icon-spec`。
-   - `上传图片` 使用现有本地图片上传入口，上传图只绑定到本次面板，不自动放入画布。
+   - `上传图片` 使用现有本地图片上传入口，上传图只绑定到本次面板，不自动放入画布；存在当前项目时创建 `assetKind: "icon-spec"` 的项目资源，不存在当前项目时创建同类型账号素材，提交图集生成时只使用持久化返回的 `resourceId` 或 `assetId`，不得按通用 `image` 类型登记。
 2. 第二模块为素材描述文本框。
    - UI 复用角色形象生成面板同款单个文本输入框，让用户直接叙述多个素材。
    - 默认按换行填入：`返回按钮`、`设置按钮`、`下一关按钮`、`提示按钮`、`原图按钮`、`冻结按钮`。
@@ -40,14 +40,21 @@
 ## 生成契约
 
 - 前端提交到 `POST /api/editor/icon-spritesheets/generations`。
+- 图标规范生成在 inline 模式下也必须先建立带稳定请求指纹的 generation operation，并由编辑器生成 durable billing 边界包住共享执行器；不得在 `operation=None` 时调用 provider 后再进入原子结果持久化。
+- 图标 spritesheet 的入队与实际执行路径都必须在引用解析、generation input 重建、定价和 provider / OSS 副作用之前预检 owner、项目和最终素材目录，并将返回的 canonical `projectId + assetFolderId` 回写到后续流程；请求省略目录时按实际写入的 owner 默认目录预检，worker 不得只信任入队时的旧校验结果。
+- queued 图标规范生成由共享原子结果持久化使用 worker caller 中的 lease 一并完成任务并清理 lease；共享执行器返回成功后 worker 只能返回 `Ok(())`，不得再次调用 job completion。
+- queued 图标规范生成在本地文本门禁后、参考资源 owner 解析和定价之前执行目标预检，并把 canonical `projectId + assetFolderId` 写入任务 payload；不存在、越权或目录不匹配必须由提交请求同步失败，不得入队后再变成 worker 失败。
+- spritesheet 队列提交对主图标规范只运行 metadata-only resolver，校验 owner、`assetKind="icon-spec"`、对象元数据和保存的游戏类型，不读取 OSS object body；worker 执行时复用同一 metadata resolver 重新确认当前事实，并在通过后只下载一次图片正文。
+- inline 与持久队列入口共用同一份 `iconDescriptions` prompt 合同：请求数组原始长度先满足 OpenAPI `1..100`，不得通过丢弃空白项绕过 `maxItems`；随后去除空白项仍须至少保留 1 条，单条最多 `200` 个 Unicode 字符，以换行拼接后合计最多 `2000` 个 Unicode 字符且不超过 `6144` 个 UTF-8 字节。请求边界校验成功后生成 `ValidatedEditorIconSpritesheetPrompt`，后续 prompt builder 不接受裸字符串。队列入口必须在引用解析、定价和任务持久化前同步拒绝可预测错误，不能把无效任务留给 worker 延迟失败。
+- worker 解析主 `referenceId` 时必须通过 `spacetime-client` 的通用窄查询 `resolve_editor_reference` 在同一事务快照内完成引用解析和 owner 校验：该字段只接受当前 owner 的项目资源 ID 或素材 ID，并只按两张表的主键查询；不接受 `objectKey`、`image_src`、URL 或临时 key 作为主规范引用。两张表先按 `owner_user_id` 筛选候选，再判断同一 ID 是否在当前 owner 范围内同时命中；其它账号的同名 ID 不得制造歧义或阻断当前账号的合法引用。记录带 `asset_object_id` 时必须按该 ID 读取对象并同时核对 bucket、object key 与 owner，只有明确缺少 `asset_object_id` 的兼容旧行才允许按对象位置查询。procedure 复用既有 `EditorProjectResourceSnapshot` 或 `EditorAssetSnapshot` 返回唯一已验证行，不接收图标业务类型参数、不新建图标专属快照，也不得拉取当前用户的完整工程列表或素材库。`assetKind="icon-spec"` 与 `genre` 都由图标图集业务代码从返回行校验和提取。入队与 inline 预检只核对引用行和 asset object 元数据，不下载图片正文；最终执行重新解析当前事实并只下载一次实际参考图。解析成功后的 `objectKey` 是服务端内部存储事实，不是该请求的输入协议。引用不存在、owner 不匹配、asset object 不存在或数据库调用失败时 procedure 直接失败；业务类型不符或保存的游戏类型无效时 API 失败；合法规范没有已保存游戏类型时允许 `genre=None`。
 - 请求字段：
-  - `referenceImageSrc`：图标规范的稳定引用（当前账号的 `objectKey`、项目资源 ID 或素材 ID）；本地临时图必须先上传 OSS，禁止 Data URL / Blob URL。
-  - `iconDescriptions`：兼容现有接口的图标需求数组，`1..100`；当前画布前端固定把完整文本作为唯一数组元素提交。数组长度只表达请求文本，不作为自动拆分数量。
+  - `referenceId`：图标主规范的正式引用，必填且只允许当前 owner 的项目资源 ID 或素材 ID。本地临时图必须先按 `assetKind="icon-spec"` 上传并登记为项目资源或账号素材，再提交返回的 `resourceId` 或 `assetId`；禁止提交 `objectKey`、URL、Data URL、Blob URL 或临时 key。
+  - `iconDescriptions`：兼容现有接口的图标需求数组，`1..100`；当前画布前端固定把完整文本作为唯一数组元素提交。数组长度只表达请求文本，不作为自动拆分数量；单项、聚合字符和 UTF-8 字节上限按上一条 prompt 合同执行。
   - `model`：支持 `gemini-3.1-flash-image-preview`（UI 显示 `nanobanana2`）和 `gpt-image-2`，默认 `nanobanana2`。
   - `aspectRatio`：按 `x:y` 展示，选项跟随模型。
   - `imageSize`：按 `0.5K / 1K / 2K` 展示，选项跟随模型。
   - `style`：可选生成风格，同时影响提交给 provider 的提示词和回图后的像素规整；未勾选像素艺术时传 `"none"`，勾选时传 `"pixelArt"`。
-  - `priceMudPoints`：按当前模型和尺寸从编辑器生成计费配置计算；`nanobanana2 1K` 为 `12`，`gpt-image-2 1K` 为 `3`、`gpt-image-2 2K` 为 `5`。前端只提交配置函数计算值，后端用 `editor_generation_config` 校验，不允许素材生成面板自行写死价格。
+  - 计费不属于客户端请求字段：前端不提交 `priceMudPoints`，后端按归一化后的模型和尺寸从运行时编辑器生成定价配置计算价格。队列模式在入队时冻结该价格，worker 的预扣、退款、响应 `priceMudPoints` 和资产 `generationCostMudPoints` 都使用同一入队价格；定价配置变更只影响之后入队的任务。
 - 模型与尺寸选项：
   - `nanobanana2`：比例 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9`；大小 `0.5K / 1K / 2K`。后端走 `/v1beta/models/{model}:generateContent`，把图标规范图作为 `inline_data`，并把 `aspectRatio` / `imageSize` 写入 `generationConfig.imageConfig`；`0.5K` 按 VectorEngine 文档传 `"512"`。
   - `gpt-image-2`：比例 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9`；大小 `1K / 2K`。后端走 `/v1/images/edits`，把图标规范图作为 multipart `image`。K 档按最长边计算，并转换为 provider 可直接生成的合法像素：`1K` 的 `1:1 / 4:3 / 3:2 / 2:3 / 9:16 / 16:9` 分别为 `1024x1024 / 1024x768 / 1024x688 / 688x1024 / 608x1088 / 1088x608`；`2K` 分别为 `2048x2048 / 2048x1536 / 2048x1376 / 1376x2048 / 1152x2048 / 2048x1152`。其中 9:16 的 1K 尺寸按 provider 最小总像素和 16 对齐约束修正。禁止把 2K 竖图回落为 1K 请求，也禁止在回图后放大伪造所选 K 档。
@@ -61,6 +68,8 @@
 <完整用户需求>
 ```
 
+上述最终 spritesheet prompt、玩法润色 prompt、美术风格润色 prompt 和规范图生图 prompt 都是自然语言文本，必须保留已经过长度与空白校验的用户原文；不得把 `R&B`、引号或尖括号改写成 XML entity。只有 `build_extra_param_prompt` 中真正位于 `<playSetting>` / `<artStyle>` XML 元素内的数据执行 XML 转义。
+
 ## 像素风格后处理
 
 - 图标素材面板增加紧凑的 `像素艺术` 勾选项。选择保存于现有生成器快照，并可随现有请求和队列 payload 传递；不写入用户可见 `generationInputs`、素材元数据或新建的持久化记录。
@@ -95,8 +104,8 @@
 - 默认打开图标素材面板时选中 `nanobanana2 / 1:1 / 1K`；模型切换后，角色和图标素材面板之间沿用上次选择的模型。
 - 图标素材生成请求必须带 `model`、`aspectRatio` 和 `imageSize`；`nanobanana2` 请求体必须包含 `generationConfig.imageConfig.aspectRatio/imageSize`，`gpt-image-2` 请求必须包含文档映射后的 `size`。
 - 图标素材面板可选择 `style: "none" | "pixelArt"`；`none` 完整保持原处理路径，且提交给 provider 的提示词与未带该字段时逐字一致，`pixelArt` 在提示词末尾追加「每个图标素材均为像素风格」并在 Alpha 回贴后、自动拆分前执行内存像素规整，最终 OSS PUT、项目资源、图集画布项和切片画布项数量不得因此增加。
-- 图标素材生成可以上传普通参考图；提交时图标规范图仍走 `referenceImageSrc`，普通参考图走 `referenceImageSrcs`，二者都必须是稳定引用（`objectKey` / 项目资源 ID / 素材 ID），禁止 Data URL / Blob URL，并写入 `generationInputs.references`。
+- 图标素材生成可以上传普通附加参考图；提交时图标主规范图走 `referenceId`，且只提交当前 owner 的项目资源 ID 或素材 ID。普通附加参考图单独走 `referenceImageSrcs`，继续允许稳定 `objectKey` / 项目资源 ID / 素材 ID，但禁止 Data URL / Blob URL。两类引用都写入 `generationInputs.references`，不得用普通附加参考图协议放宽主规范边界。
 - 透明背景处理和自动拆分都成功后，画布同时出现透明 spritesheet 主图、其右侧的 provider 原图，以及从原图右侧铺开的全部有效连通域图标图层，图标依次命名为 `素材 N`；透明图集成功但拆分失败时仍出现透明主图与右侧原图，透明背景处理最终失败时只出现 provider 原图。
 - 选中透明图集图层时显示 `拆分图集`；点击后源图集显示扫描蒙层与 `拆图中` 状态，工具栏按钮同步切换为旋转图标和 `拆图中` 并禁用重复提交。完成后恢复工具栏，不新增第二张图集，只在 provider 原图右侧追加自动识别的独立素材，并同步写入素材库。
 - 把同源派生图层从其它标签改为“图集”时，在项目资源返回新 `resourceId` 前“拆分图集”保持禁用；持久化成功后拆分请求必须指向 `assetKind: "icon-spritesheet"` 的新资源，失败时标签回滚且不发起拆分请求。
-- 生成图标素材提交体包含按模型和尺寸计算的 `priceMudPoints`；`nanobanana2 1K` 应为 `12`，`gpt-image-2 1K` 应为 `3`，`gpt-image-2 2K` 应为 `5`。若前端传入与后端计费配置不一致的值，后端返回 `priceMudPoints` 校验错误，不继续调用上游生成。
+- 生成图标素材的提交体不包含 `priceMudPoints`；后端必须按归一化后的模型和尺寸计算价格，不信任客户端声明。queue 任务的计费、退款和结果投影使用入队时冻结的同一价格。