合并 master 最新生成契约

保留游戏场景生成链路

接入生成幂等与参考图上限

保留权威画布持久化与完美像素能力

解决图片画布生成相关冲突

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

@@ -2991,7 +2991,7 @@
               "none",
               "pixelArt"
             ],
-            "description": "可选生成后处理风格，当前识别 none 与 pixelArt。省略、null、空字符串或 none 按无风格处理；pixelArt 仅支持普通图片（kind 省略）和 character。未知字符串或不支持该风格的 kind 按 none 继续生成并返回 unsupported-image-style 告警；非字符串值返回 400。"
+            "description": "可选生成风格，当前识别 none 与 pixelArt。省略、null、空字符串或 none 按无风格处理，提交给 provider 的提示词与未带该字段时逐字一致；pixelArt 仅支持普通图片（kind 省略）和 character，会在提示词末尾追加一行像素风约束（普通图片为「画面为像素风格」，character 为「角色主体为像素风格」）并在回图后执行像素规整。未知字符串或不支持该风格的 kind 按 none 继续生成并返回 unsupported-image-style 告警；非字符串值返回 400。"
           },
           "size": {
             "type": "string",
@@ -3047,7 +3047,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS 再提交。禁止 Data URL / Blob URL。普通生成最多使用前 5 张，数组上限为 9。"
+              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS 再提交。禁止 Data URL / Blob URL。普通生成最多 5 张；kind=quick-edit 时 gpt-image-2 最多 5 张、nanobanana2 最多 9 张。超限返回 400，不会静默截断。"
             },
             "maxItems": 9
           },
@@ -3241,7 +3241,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。"
+              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。sourceImageSrc 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
             },
             "maxItems": 8
           },
@@ -3372,7 +3372,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "description": "额外图标素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。最多 8 张。"
+              "description": "额外图标素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。referenceImageSrc 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
             },
             "maxItems": 8
           },
@@ -3405,7 +3405,7 @@
               "none",
               "pixelArt"
             ],
-            "description": "可选生成后处理风格，当前识别 none 与 pixelArt。省略、null、空字符串或 none 按无风格处理；pixelArt 启用图标图集像素规整。未知字符串按 none 继续生成并返回 unsupported-image-style 告警；非字符串值返回 400。"
+            "description": "可选生成风格，当前识别 none 与 pixelArt。省略、null、空字符串或 none 按无风格处理，提交给 provider 的提示词与未带该字段时逐字一致；pixelArt 会在提示词末尾追加一行「每个图标素材均为像素风格」并启用图标图集像素规整。未知字符串按 none 继续生成并返回 unsupported-image-style 告警；非字符串值返回 400。"
           },
           "model": {
             "type": "string",
@@ -3496,7 +3496,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "description": "额外 UI 素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。最多 5 张。"
+              "description": "额外 UI 素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。sourceImageSrc 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 5 张；超限返回 400，不会静默截断。"
             },
             "maxItems": 5
           },

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

@@ -14,6 +14,21 @@
 - 关联：相关文件、文档、提交或 Issue
 ```
 
+## `timeout_at` 不能替代显式的预算耗尽预检
+
+- 现象：给完美像素加端点级并发闸后，预算已经耗尽的请求仍然能拿到许可，白占一个名额继续去打几轮全账号 SpacetimeDB 扫描，直到下载那步才失败。
+- 原因：`tokio::time::timeout_at` 会先 poll 一次内层 future 再判超时。信号量有空闲许可时 `acquire_owned()` 首次 poll 就绪，于是即使 deadline 早已过去，返回的仍是 `Ok(Ok(permit))` 而不是超时。既有 `acquire_editor_pixel_art_cpu_permit` 里那句 `if Instant::now() >= processing_deadline` 正是为此存在，新写的许可函数漏掉后被单测抓出。
+- 处理：所有「先判预算、再等资源」的获取函数都必须在 `timeout_at` 之前显式判一次 `Instant::now() >= deadline` 并直接返回超时错误；这句不是冗余防御。同理，进入排队计数之前也要先做这个预检，避免为注定失败的请求占用队列名额。
+- 验证：在有空闲许可时用已过期的 deadline 调用获取函数，只断言返回 `504` 而不是许可；`504` 已足以证明显式预检没有被 `timeout_at` 的首次 poll 绕过。禁止在该用例里读取进程级队列 Atomic 的 before/after；相对断言同样会被并行测试插入。仅靠「信号量占满时超时」的用例发现不了这个问题。
+- 关联：`server-rs/crates/api-server/src/editor_project.rs`（`acquire_editor_pixel_art_snap_permit`、`acquire_editor_pixel_art_cpu_permit`）。
+
+## 有界等待队列的计数递减必须写在 Drop 里
+
+- 现象：给同步端点加「最多 N 个等待者」的保险丝时，若把计数递减写在正常返回路径上，客户端断连或超时触发会让等待中的 future 被丢弃而跳过递减；计数只增不减，最终队列永久判定为满，接口对所有人返回 `503` 且不会自愈。
+- 原因：Rust 的 async future 可以在任意 await 点被取消，取消时只保证 `Drop` 会跑，不保证后续代码会执行。有界队列的入场与离场天然不对称。
+- 处理：把递增封进一个 guard 结构体，递减放在它的 `Drop` 实现里；递增本身用 `fetch_update` 的 CAS，不能用「先读后加」——两个线程同时读到 `max - 1` 各自加一就会越界。拿到资源后立即 `drop(guard)` 让出队列名额，不要让它跟着许可一起活到请求结束。
+- 验证：单测覆盖 CAS 边界（满了返回失败且计数不越界、上限为 0 时任何进入都失败），并由独立用例覆盖 guard 离开作用域后的计数归还。预算耗尽路径只断言 `504`，不得通过另一个测试也会修改的进程级 static before/after 来推断“未入队”，也不得用串行锁或 `--test-threads=1` 掩盖隔离问题。
+- 关联：`server-rs/crates/api-server/src/editor_project.rs`（`try_enter_bounded_queue`、`EditorPixelArtSnapQueueGuard`）。
 ## Linux 生产脚本门禁不能假设本地也是 GNU userland
 
 - 现象：macOS 本地运行维护页、生产 API 部署和 Rust 产物门禁时，依次出现 `mv: illegal option -- T`、`mapfile: command not found`、`/usr/bin/cp` / `/usr/bin/chmod` 不存在，以及 `.rlib` 明明含有 `.o` 却报告“没有可扫描成员”；安全修复计划还会把 `/var/folders` 到 `/private/var/folders` 的系统别名误判为用户符号链接。
@@ -3236,9 +3251,9 @@
 
 - 现象：release 上 api-server 周期性出现全量 `spacetime_stage="pool_acquire" elapsed_ms=45000` 业务超时，`/readyz` 503（`reason=spacetime_unhealthy, stage=pool_acquire`），`/healthz` 仍 200，只有重启能恢复，过若干小时复发。
 - 原因：旧 `PooledConnectionLease` 只能显式 `release_connection` 归还；HTTP 请求方在等待 StDB 回包期间断开时 handler future 被取消，permit 自动归还但槽位 `in_use` 永不复位。后续 acquire 在拿到 permit 后进入无界 `loop + yield_now` 扫描空闲槽位，泄漏积累到 pool_size 后整池挂死。
-- 处理：租约持有 `Arc<SpacetimeConnectionPool>` 并实现 `Drop` 统一复位槽位/归还连接；槽位改 `AtomicBool` CAS 抢占，删除自旋循环（持有 permit 必然命中空闲槽位）。任何新的"显式归还"资源在 async 取消语义下都要先想 Drop 兜底。
+- 处理：租约持有 `Arc<SpacetimeConnectionPool>` 并实现 `Drop` 统一复位槽位/归还连接；槽位改 `AtomicBool` CAS 抢占，删除自旋循环（持有 permit 必然命中空闲槽位）。任何新的"显式归还"资源在 async 取消语义下都要先想 Drop 兜底。该保证只覆盖本地 lease / slot / permit 回收；RPC 已发出后，handler timeout/drop 不会取消或回滚远端 procedure，结果仍须按 unknown 读取权威事实。
 - 验证：`cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml --lib`（`dropped_lease_releases_slot_and_permit`、`acquire_times_out_at_pool_acquire_when_pool_is_busy`）。
-- 关联：`server-rs/crates/spacetime-client/src/lib.rs`、`docs/【后端架构】SpacetimeDB连接池租约Drop兜底与取消安全-2026-06-11.md`。
+- 关联：`server-rs/crates/spacetime-client/src/active.rs`、`docs/【后端架构】SpacetimeDB连接池租约Drop兜底与取消安全-2026-06-11.md`。
 
 ## 后台灰度配置不能从 SpacetimeDB 本地表缓存读取
 
@@ -4180,3 +4195,10 @@
 - 原因：两个跨模块测试读写同一进程全局状态，却没有共用隔离边界；只给 accept 后取得的 stream 设置 read timeout 无法约束 accept 本身，payload 读取也缺少总 deadline。
 - 处理：全部全局 sink 测试共用一把 test-only 串行锁，并由 RAII guard 在 `Drop` 中无条件清空；测试统一使用 `manifest_invalidation_sink_isolation_` 前缀。relay fixture 对 accept 和 payload 分别使用非阻塞轮询与总 deadline，不使用固定 sleep；生产 loopback、token、连接 / 写入超时和 payload 大小校验保持不变。
 - 验证：用 `--test-threads=2` 重复运行统一 filter，覆盖正常 relay、无事件 accept 超时、不完整 payload 超时、panic 展开清理，以及 GUI owner attach 配置与 guard 清理。
+
+## 编辑器生成不能把传输重试、参考图截断和客户端 provenance 当成独立小问题（2026-08-05）
+
+- 现象：生成 POST 首次已经入队但响应丢失时，客户端自动重试产生第二个任务；第 6 张或更多参考图仍显示在 UI / 元数据里，却没有送给 provider；直接构造请求还能把任意资源 ID 写成最终素材引用。
+- 原因：客户端虽在重试中复用 `x-request-id`，队列入口却用随机 job id 生成 dedupe key；前端允许无限追加，api-server 和 provider 用 `.take(...)` 静默截断；`generationInputs.references` 被当成可信持久 provenance。
+- 处理：主站生成 POST 禁止自动重试，把显式复用的稳定 request id 接到队列唯一键并校验 replay payload；所有边界显式拒绝超限，前端还要预留主图槽位、统计在途上传，并在上传完成前拒绝模型切换、画布选图、提交生成、关联源图删除 / 剪切 / 素材删除和面板切换 / 关闭；reservation 必须绑定原面板上下文，批量部分失败时不能丢弃已经持久化的成功项。入队、完美像素及直接创建资源 / 素材时删除客户端 references，执行时按真实参考源和 owner 资源记录重建权威引用。历史任务比较必须兼容仅差已删除 references 的旧 payload，不能只保留旧 hash 却让 payload 比较误报冲突。
+- 验证：覆盖同键同 payload / 不同 payload、普通图片第 6 张、带主图的 GPT-image-2 第 5 张额外引用、provider 6 / 15 张边界、伪造引用删除和 owned 资源 / 素材重建。

docs/【后端架构】SpacetimeDB连接池租约Drop兜底与取消安全-2026-06-11.md

@@ -2,7 +2,7 @@
 
 - 日期：2026-06-11
 - 关联故障：release 环境 api-server 周期性全量 `spacetime_stage="pool_acquire" elapsed_ms=45000` 超时，`/readyz` 503（`reason=spacetime_unhealthy, stage=pool_acquire`），重启后临时恢复。
-- 涉及代码：`server-rs/crates/spacetime-client/src/lib.rs`
+- 涉及代码：`server-rs/crates/spacetime-client/src/active.rs`
 
 ## 故障根因
 
@@ -28,6 +28,8 @@
 3. acquire 改为 CAS 抢占槽位：持有 permit 即保证并发持有者不超过 `pool_size`，扫描一轮必然命中空闲槽位，彻底删除自旋循环；建连失败直接返回错误，槽位由租约 Drop 复位。
 4. `release_connection` 退化为 `drop(lease)`，显式与隐式归还共用同一条兜底路径。
 
+这里的“取消安全”只指本地连接租约、槽位与 permit 可回收。RPC 已发出后，handler timeout/drop 不会取消或回滚远端 procedure，结果必须按 unknown 读取权威事实对账；`dropped_lease_releases_slot_and_permit` 只覆盖本地 Drop，不构成远端取消测试。
+
 ## 验收
 
 - `cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml --lib`（44 通过，含上述连接池与缓存连接测试）

docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md

@@ -123,7 +123,7 @@ POST   /api/profile/api-keys
 DELETE /api/profile/api-keys/{keyId}
 ```
 
-前端入口位于登录后个人中心的 `我的 → 开发者 API Key`，用于查看当前 Key、创建新 Key、复制一次性明文和撤销已创建 Key。外部 OpenAPI 只描述 `/api/external/v1` 下可由 API Key 调用的接口，不混入登录态 API Key 管理接口。
+前端入口位于登录后个人中心的 `我的 → 开发者 API Key`，用于查看当前 Key、创建新 Key、复制一次性明文和撤销已创建 Key。Key 卡片中的创建时间和最近使用时间必须格式化为 `YYYY-MM-DD`，不得直接展示后端时间戳。外部 OpenAPI 只描述 `/api/external/v1` 下可由 API Key 调用的接口，不混入登录态 API Key 管理接口。
 
 ## 版本与兼容策略
 

docs/【图片画布】撤销范围与操作提示方案-2026-07-17.md

@@ -15,7 +15,7 @@
 
 允许撤销的典型操作包括移动图片、移动生成结果、调整层级、组合与取消组合、删除或剪切图片、隐藏图片、锁定与解锁、翻转、修改素材类型和调整画布视图。删除、剪切和隐藏允许撤销，是因为目标只会让内容重新出现。
 
-添加素材、上传到画布、粘贴、创建副本、生成图片、扩图新增结果、显示隐藏图片、替换图片以及其它会让当前结果消失的撤销必须被安全检查阻止。`Ctrl+C`、选择变化、滚轮或抓手视口移动、导出下载、项目重命名、素材库后端删除和生成任务副作用不进入画布历史；素材库后端删除发生后，同时剪除撤销栈和恢复栈中所有包含关联图层的目标快照，不能让更早的画布历史复活已删除素材。
+添加素材、上传到画布、粘贴、创建副本、生成图片、扩图新增结果、完美像素新增结果、显示隐藏图片、替换图片以及其它会让当前结果消失的撤销必须被安全检查阻止。`Ctrl+C`、选择变化、滚轮或抓手视口移动、导出下载、项目重命名、素材库后端删除和生成任务副作用不进入画布历史；素材库后端删除发生后，同时剪除撤销栈和恢复栈中所有包含关联图层的目标快照，不能让更早的画布历史复活已删除素材。
 
 恢复同样执行动态安全检查。移动、层级、分组、锁定、翻转和视图等不会减少内容的操作可以恢复；重新执行删除、剪切、隐藏、删除生成结果或替换当前素材时必须被阻止。
 
@@ -24,6 +24,7 @@
 - 撤销栈和恢复栈均保存操作类型、目标 `CanvasHistorySnapshot` 和创建时间，分别最多保留 60 条。
 - 新画布操作把操作前快照写入撤销栈并清空恢复栈；成功撤销把当前快照写入恢复栈，成功恢复把当前快照写回撤销栈。
 - 操作类型用于生成用户提示，并对添加、上传、生成和替换等明确会移除当前结果的撤销做保护；其它操作能否应用由当前快照与目标快照的差异检查决定。
+- 已有图片完美像素化成功落入画布前记录独立 `perfect-pixel` 历史类型，中文提示使用“完美像素”。该类型与 `generate-image`、`expand-image`、`remove-background` 一样属于新增结果保护操作：撤销不得删除派生 PNG，源图继续保留也不改变这一保护语义。像素处理失败、超时或不适用时不写历史。
 - 安全检查以稳定的 `layer.id` 判断当前图层是否仍存在；内容身份优先比较对象存储 key、对象标识和媒体地址，序列帧结果比较完整帧列表。`resourceId`、`sourceResourceId`、`sourceAssetId` 等内部关联 ID 的延迟回填不视为图片替换。
 - 恢复历史快照时，相同 ID 的图层以当前对象为权威，只从目标快照覆盖 `x`、`y`、`zIndex`、`groupId`、`assetKind`、`hidden`、`locked`、`flipX`、`flipY`。当前图层的资源关联、内容、媒体、生成元数据、`width` / `height` / `originalWidth` / `originalHeight` 和标题必须保留，不能被异步回填前的旧快照覆盖。
 - 当前生成对话框和非活动生成结果按稳定 ID 纳入内容存在性检查，避免恢复操作删除当前生成结果。相同 ID 的生成对话框只从目标快照恢复占位框 `x` / `y` 以及 active / inactive 槽位对应的 `composerOpen`，当前占位框的 `width` / `height` / `originalWidth` / `originalHeight`、当前比例与清晰度等参数、`generating` / `failed` / 完成态、提示词、参考图和任务结果继续以当前状态为准，不能被旧历史快照降级。
@@ -34,6 +35,7 @@
 - 修改素材类型的撤销与恢复仍以当前图层内容为权威，但每次成功恢复类型后都要创建与恢复类型一致的正式项目 resource，再回填新 `resourceId`。同一图层的 resource 创建请求使用单调版本号，迟到的旧类型响应不得覆盖更晚的 undo / redo 结果。
 - 鼠标拖动在按下时暂存操作前快照；屏幕位移达到点击阈值后才开始改变画布坐标并只提交一条历史，阈值内的指针抖动和单击都不产生位移或历史记录。
 - 本地即时结果与后端项目快照结果都必须在生成图层加入画布前写入一条生成历史；生成完成后的自动适合视图不再额外压入视口历史，保证用户第一次撤销就命中生成保护。
+- 完美像素的关闭 composer 占位沿用 generation dialog 的内容存在性保护。占位删除已先持久化时，后端 completion 不得用旧 placeholder 复活占位或派生图层；回包时本地占位已删除则前端不应用完成快照或写 `perfect-pixel` 历史，已经持久化的 project resource / 账号素材仍可由资源或素材入口读取。现有布局 CAS 没有 deletion tombstone，completion 先提交、删除保存后冲突的极端竞态仍按权威快照收口。
 - 顶部消息复用 `PlatformRuntimeStatusToast`，成功使用中性色，被阻止使用警告色；连续触发会替换消息并重新开始 3 秒计时。
 
 ## 验收重点
@@ -55,3 +57,5 @@
 15. 图层移动后从素材库删除关联素材，随后撤销或恢复都不得把已删除图层重新加入画布；普通画布删除未伴随素材库删除时仍可撤销。
 16. 打开“修改图片”并输入未提交提示词后，从按钮等非输入控件触发撤销不得关闭弹窗或回退当前草稿。
 17. 修改素材类型后立即撤销或快速撤销再恢复，最终只允许最新类型的 resource 响应回填；刷新项目后类型与最后一次成功历史操作一致。
+18. 完美像素结果加入画布后只写一条 `perfect-pixel` 历史；第一次撤销命中保护提示，源图和派生 PNG 都不消失。
+19. 完美像素处理中删除占位后，本次完成回包不得在本地重新应用结果或写 `perfect-pixel` 历史；删除已先持久化时，后端不得复活占位或结果图层；已成功持久化的资源或账号素材允许保留。

docs/【编辑器】图片画布结构化持久化与迁移回滚方案-2026-07-19.md

@@ -69,6 +69,21 @@ worker 完成生成任务时，本次先用读取时 revision 调用 CAS 保存
 
 重复 completion 必须返回同一资源、layer 和 dialog 终态，不得重复插入，也不能因 dialog 暂时缺失而返回 `changed=false` 后仍把任务标记完成。任一步失败时整笔业务写回回滚，任务保留可诊断的失败或可重试状态。
 
+### 3.6 免费同步栅格派生完成
+
+`POST /api/editor/images/pixel-art-snaps` 的完美像素化不是 external job completion：它免费、在当前 HTTP 请求内 inline 执行，不创建任务行，也没有 `job_id / worker_id / lease_token`。前端仍须先创建关闭 composer 的右侧 generation dialog，再解析或上传源图以取得稳定引用，随后 flush 包含该占位的当前布局，最后把稳定源媒体引用和带非空 `dialogId` 的 `canvasCompletion` 一次提交；结构化 / legacy canvas 的完成分流继续由后端决定，前端不能直接写表或本地补造正式 layer。
+
+端点级并发排队、像素读取、静态 PNG / JPEG / WebP 编码门禁、解码、输入限制、legacy 网格步长估算、CPU 并发排队、规整和 PNG 编码全部发生在持久化前。两层排队的位置不同：端点级闸在首次 IO 之前，因此队列满的 `503` 早于任何 SpacetimeDB 读取和 OSS 下载返回；CPU 排队仍在下载之后、规整之前，等待超预算返回 `504`。两者都在持久化前失败，零写入结论不变。strict 与生成风格使用同一 profile、峰值估算、单轴步长补全、walker、采样和编码；仅在横纵两轴都未检测到步长、legacy 即将进入统一网格兜底时拒绝，任一轴已检测到步长时行为和输出完全一致。任一步失败、超时或不适用时不执行最终 OSS PUT，不创建 asset object、`editor_project_resource`、`editor_asset` 或结果 layer；不得保存原图副本、逻辑低分辨率图、诊断图或前后对比图冒充结果。处理成功时只 PUT 一张最终 PNG，并至多各创建一个 project resource 和一个账号素材；源图已有正式 project resource 时，结果资源的 `source_resource_id` 指向该资源。
+
+该零写入保证只覆盖首个最终 PNG PUT 前的可预判与处理阶段。进入持久化后，PNG / asset object、project resource、账号素材与 canvas completion 仍跨 OSS 和多个 SpacetimeDB procedure，沿用既有非事务顺序；后段失败可以保留此前已经确认的对象或记录，不做自动删除补偿，也不由客户端重放请求。调用方应按 `task_id / object_key / resource_id` 重新读取权威项目和素材快照后显式收口。
+
+同步 completion 写画布前必须读取当前 revision 和 dialog，而不能信任请求中提交时的旧 placeholder：
+
+1. dialog 仍存在时，在同一当前布局上完成一个结果 layer，保留源图，并关联结果 resource；
+2. dialog 的删除已先持久化时，跳过 layer / dialog 写回，不重建占位、不复活派生图层；已成功持久化的 project resource / 账号素材允许保留；
+3. CAS 冲突时不得拿新 revision 原样重放旧整包；按当前项目保存冲突规则重新读取权威快照并显式收口；
+4. 客户端回包时若本地 dialog 已删除，不应用完成快照或写历史；现有布局 CAS 没有 deletion tombstone，completion 先提交、删除保存后冲突的极端竞态仍按权威快照收口。客户端不得为该 unsafe POST 配置 `EDITOR_REQUEST_RETRY_OPTIONS`。请求字节可能已发出后的 transport 异常或 `408 / 425 / 429 / 502 / 503 / 504` 不自动重放，先通过 GET 核对项目 / 素材快照，再由用户显式决定是否再次执行；Bearer 中间件在 handler 前拒绝请求后的既有认证恢复继续保留。
+
 ## 4. 存量迁移
 
 迁移按 canvas 执行 `backfill → hash 核对 → activate`，并保持幂等：
@@ -110,5 +125,6 @@ SpacetimeDB 必须先于依赖新 procedure / bindings 的 API 发布；前端
 - structured 模式下 typed 列而非扩展 JSON 决定几何、层级、分组、显示 / 锁定、资源引用、`asset_kind_override` 和 dialog 状态；标签展示和类型能力判断统一按 `override ?? resource default`。修改当前图层标签与清除覆盖都保持 `resource_id` 和资源行数量不变；复制共享同一资源并复制 override，随后各副本可独立修改 override。两个客户端基于同一 revision 写入时只允许一个成功，冲突方重载后端最新快照，不换上新 revision 原样重放旧整包。细粒度 batch mutation 是取消 2 MiB 兼容入口的后续项，不冒充为本次已完成。
 - worker completion 当前以读取时 revision 做 CAS，冲突时拒绝覆盖；V2 保存和保存后快照在同一 procedure 结果内返回，避免“已提交但后续 GET 失败”的不确定结果。lease-fenced 资源 / layer / dialog / job 单事务 completion 仍是后续收口项。
 - structured 快照刷新后，上传参考图、生成结果、占位与 dialog 状态均可恢复；资源存在但布局写入失败时不会伪装为保存成功。
+- 完美像素处理失败 / 超时时 OSS、resource、asset 和 layer 均无新增；成功时只有一个最终 PNG、至多一个 project resource 和一个账号素材。处理中占位删除已先持久化时，完成请求不复活 dialog 或结果 layer；回包时本地占位已删除则不应用完成快照，已成功创建的资源 / 素材仍可读取；传输结果未知时客户端不自动重放 unsafe POST。
 - 回滚重组结果经 schema 校验、canonical hash / 资源引用核对且不超过 2 MiB；超限或不一致时明确拒绝且 structured 快照仍可读取。
 - 完成 `npm run spacetime:generate`，确认 Rust 表字段、migration、生成 bindings、HTTP DTO 与前端 `assetKindOverride` 形状一致；再运行 `npm run check:spacetime-runtime-access`、`npm run check:spacetime-schema`、相关 Rust / API / 前端定向测试、`npm run check:encoding` 和 `git diff --check`。

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

@@ -46,7 +46,7 @@
   - `model`：支持 `gemini-3.1-flash-image-preview`（UI 显示 `nanobanana2`）和 `gpt-image-2`，默认 `nanobanana2`。
   - `aspectRatio`：按 `x:y` 展示，选项跟随模型。
   - `imageSize`：按 `0.5K / 1K / 2K` 展示，选项跟随模型。
-  - `style`：可选生成后处理风格；未勾选像素艺术时传 `"none"`，勾选时传 `"pixelArt"`。
+  - `style`：可选生成风格，同时影响提交给 provider 的提示词和回图后的像素规整；未勾选像素艺术时传 `"none"`，勾选时传 `"pixelArt"`。
   - `priceMudPoints`：按当前模型和尺寸从编辑器生成计费配置计算；`nanobanana2 1K` 为 `12`，`gpt-image-2 1K` 为 `3`、`gpt-image-2 2K` 为 `5`。前端只提交配置函数计算值，后端用 `editor_generation_config` 校验，不允许素材生成面板自行写死价格。
 - 模型与尺寸选项：
   - `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"`。
@@ -65,6 +65,7 @@
 
 - 图标素材面板增加紧凑的 `像素艺术` 勾选项。选择保存于现有生成器快照，并可随现有请求和队列 payload 传递；不写入用户可见 `generationInputs`、素材元数据或新建的持久化记录。
 - `style` 省略、为 `null`、空字符串或 `"none"` 时按内部 `None` 处理且不告警；`"pixelArt"` 启用像素规整。未知字符串按 `None` 继续生成，并通过既有通用 `warning` 返回 `unsupported-image-style`；非字符串 JSON 仍返回 `400`。
+- 2026-08-01 修订：`"pixelArt"` 不再只是后处理，同时向提交给 provider 的提示词末尾追加独立一行约束。图标链路使用「每个图标素材均为像素风格」，**不得**使用「画面为像素风格」——图集生成后要按纯色抠像，绿幕底必须保持平整，画面级像素化要求会与同一段提示词里的「纯色背景必须平整无纹理、无渐变」互相拆台；一张图内是多个彼此分离的素材，需要逐个点名，避免模型只把其中一部分做成像素块。注入发生在 `build_editor_icon_spritesheet_prompt` 返回之后，该函数签名和输出契约不变。约束句只随工程化提示词写入**原图 spritesheet** 的 `editor_project_resource` prompt 列；透明结果的 prompt 列是 `"去除纯色背景"`，自动拆分的切片是 `"自动拆分图集"`，两者都不含约束句。与普通图片和角色形象不同，本链路**响应体**的 `prompt` 字段返回的也是含约束句的工程化提示词，而不是用户输入——图标请求本身没有 `prompt` 字段（收的是 `iconDescriptions`），因此调用方（含外部 API v1）能直接看到绿幕子句、间距要求和本次新增的像素约束。以上 prompt 列写入与响应字段规则都是既有行为，与 `web/master` 一致，本次只是让被回传的模板多了一行。不新增 OSS PUT、项目资源、图集画布项或切片画布项。尚未约束各素材共用同一像素块大小（`estimate_step_size` 取全图相邻峰间距的第 30 百分位，块大小不一时步长估计会偏），等实测。
 - 图标链路以已持久化的带纯色背景 provider 原图实际尺寸为基准；BgFilter 正常成功后，把 Alpha 蒙版回贴到该同尺寸平底原图，再执行像素规整。网格分析源使用平底 provider 原图，RGBA 采样源使用 Alpha 已回贴的透明图；规整结果不再经过独立的最终尺寸处理，直接上传透明 spritesheet，成功后才进入原有连通域自动拆分。
 - 首版固定参数为分析色数 `16`、Alpha 覆盖阈值 `0.375`、像素格尺寸自动检测、固定色板关闭、K-means 最大采样 `262144`。单格颜色按 `Σ(A × RGB) / ΣA` 进行 Alpha 加权；覆盖率 `Σ(A / 255) / N >= 0.375` 且 `ΣA > 0` 时输出硬 Alpha `255`，否则输出严格 `[0,0,0,0]`。分析色数不限制最终输出色数。
 - 像素规整 CPU 工作使用进程级最大并发 `2`；取得并发许可的排队时间与实际处理时间共享最多 `30` 秒预算，同时不得晚于当前请求 deadline，最终以两者中更早者为准。输入图片任一边不得超过 `10000` 像素，总像素不得超过 `8294400`；超限、排队超时或处理超时均保留 Alpha 已回贴的透明图并走非致命降级，随后仍可进入原有自动拆分。
@@ -93,7 +94,7 @@
 - 默认提示文本会完整进入 prompt；用户输入不再被解析为素材数量。例如“各种敌人头像：骷髅 哥布林 强盗 龙 蝙蝠等”只是一段完整需求，不代表必须生成或拆出 `6` 个素材。
 - 默认打开图标素材面板时选中 `nanobanana2 / 1:1 / 1K`；模型切换后，角色和图标素材面板之间沿用上次选择的模型。
 - 图标素材生成请求必须带 `model`、`aspectRatio` 和 `imageSize`；`nanobanana2` 请求体必须包含 `generationConfig.imageConfig.aspectRatio/imageSize`，`gpt-image-2` 请求必须包含文档映射后的 `size`。
-- 图标素材面板可选择 `style: "none" | "pixelArt"`；`none` 完整保持原处理路径，`pixelArt` 在 Alpha 回贴后、自动拆分前执行内存像素规整，最终 OSS PUT、项目资源、图集画布项和切片画布项数量不得因此增加。
+- 图标素材面板可选择 `style: "none" | "pixelArt"`；`none` 完整保持原处理路径，且提交给 provider 的提示词与未带该字段时逐字一致，`pixelArt` 在提示词末尾追加「每个图标素材均为像素风格」并在 Alpha 回贴后、自动拆分前执行内存像素规整，最终 OSS PUT、项目资源、图集画布项和切片画布项数量不得因此增加。
 - 图标素材生成可以上传普通参考图；提交时图标规范图仍走 `referenceImageSrc`，普通参考图走 `referenceImageSrcs`，二者都必须是稳定引用（`objectKey` / 项目资源 ID / 素材 ID），禁止 Data URL / Blob URL，并写入 `generationInputs.references`。
 - 透明背景处理和自动拆分都成功后，画布同时出现透明 spritesheet 主图、其右侧的 provider 原图，以及从原图右侧铺开的全部有效连通域图标图层，图标依次命名为 `素材 N`；透明图集成功但拆分失败时仍出现透明主图与右侧原图，透明背景处理最终失败时只出现 provider 原图。
 - 选中透明图集图层时显示 `拆分图集`；点击后源图集显示扫描蒙层与 `拆图中` 状态，工具栏按钮同步切换为旋转图标和 `拆图中` 并禁用重复提交。完成后恢复工具栏，不新增第二张图集，只在 provider 原图右侧追加自动识别的独立素材，并同步写入素材库。

docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md

@@ -65,6 +65,7 @@
 
 - 角色面板增加紧凑的 `像素艺术` 勾选项，请求使用可选字符串字段 `style`：未勾选传 `"none"`，勾选传 `"pixelArt"`。该选择可以随现有生成器快照和队列 payload 保存，但不写入用户可见 `generationInputs`、素材元数据或新建的持久化记录。
 - `style` 省略、为 `null`、空字符串或 `"none"` 时按内部 `None` 处理且不告警；`"pixelArt"` 在 `kind="character"` 时启用像素规整。未知字符串按 `None` 继续生成，并通过既有通用 `warning` 返回 `unsupported-image-style`；非字符串 JSON 仍返回 `400`。同一图片生成请求 DTO 被其它 `kind` 复用时，只有普通图片和 `character` 支持 `"pixelArt"`，其它 `kind` 收到该值也按不支持风格降级。
+- 2026-08-01 修订：`"pixelArt"` 不再只是后处理，同时向提交给 provider 的提示词末尾追加独立一行约束。角色链路使用「角色主体为像素风格」，**不得**使用「画面为像素风格」——角色生成后要按纯色抠像，绿幕底必须保持平整，同一段提示词里已写死「纯色背景必须平整无纹理、无渐变」，画面级像素化要求会与之互相拆台；且该提示词已禁止出现角色以外的场景内容，因此只需点名角色本身。注入发生在 `build_editor_character_image_prompt` 返回之后，该函数签名和输出契约不变。约束句**不会**进入角色链路的任何 `editor_project_resource`：原图 resource 的 prompt 列存的是 `role_setting`（用户原文），透明结果的 `output_prompt` 在抠图成功后被无条件覆盖为 `"去除纯色背景"`；完整提交提示词是否留存取决于 provider：`persist_editor_provider_source_image` 写原图 asset object 元数据时用的是 `actual_prompt.unwrap_or(prompt)`，provider 未回 `actualPrompt` 时才存 `submitted_prompt`（含约束句），此时排障可按 `object_key` 查；provider 回了 `actualPrompt` 就存 provider 改写后的文本，该次生成的 `submitted_prompt` 在系统内一处都不落——外部 API 审计的 `request_payload` 只记 `promptChars` 字符数，没有提示词原文。响应体返回的是用户原文，前端显示不变。以上 prompt 列写入与 asset object 元数据规则都是既有行为，与 `web/master` 逐行一致，本次未改动。角色提示词里既有的「严格基于图1的角色美术视觉规范的美术风格」与像素约束存在潜在冲突，本次未改写，等实测。
 - 角色 provider 回图先按统一业务像素矩阵执行交付尺寸归一：允许无放大恢复时使用 Lanczos 重采样并居中裁切，无法安全恢复时保留 provider 实际尺寸并返回非阻断告警。归一后的带纯色背景图先持久化并作为 BgFilter 输入；BgFilter 正常成功后，把 Alpha 蒙版回贴到这张同尺寸平底原图，再执行像素规整并上传透明主图。网格分析源使用已收口到实际交付尺寸的平底原图，RGBA 采样源使用 Alpha 已回贴的透明图；软 Alpha 只参与单格覆盖率和 Alpha 加权 RGB 计算，输出 Alpha 硬化为 `0 / 255`。
 - 首版参数固定为分析色数 `16`、Alpha 覆盖阈值 `0.375`、像素格尺寸自动检测、固定色板关闭、K-means 最大采样 `262144`。单格覆盖率 `Σ(A / 255) / N >= 0.375` 且 `ΣA > 0` 时输出 `A=255`，颜色按 `Σ(A × RGB) / ΣA` 计算；否则输出 `[0,0,0,0]`。分析色数不限制最终输出色数。
 - 像素规整 CPU 工作使用进程级最大并发 `2`；取得并发许可的排队时间与实际处理时间共享最多 `30` 秒预算，同时不得晚于当前请求 deadline，最终以两者中更早者为准。输入图片任一边不得超过 `10000` 像素，总像素不得超过 `8294400`；超限、排队超时或处理超时均保留 Alpha 已回贴的透明图并走非致命降级。
@@ -118,7 +119,7 @@
 - `从画布中选择` 后点击已有画布图片可绑定为角色规范，`Esc` 可退出点选状态。
 - 上传常规参考图后缩略图右下角显示序号。
 - 输入角色设定并生成时，请求包含 `kind: "character"`、角色设定 prompt、参考图数组、`model`、`screenColor`、`aspectRatio` 和 `imageSize`。
-- 角色面板可选择 `style: "none" | "pixelArt"`；`none` 的处理路径和产物保持不变，`pixelArt` 在 Alpha 回贴后执行内存像素规整，最终 OSS PUT、项目资源和画布图层数量不得增加。
+- 角色面板可选择 `style: "none" | "pixelArt"`；`none` 的处理路径和产物保持不变，且提交给 provider 的提示词与未带该字段时逐字一致，`pixelArt` 在提示词末尾追加「角色主体为像素风格」并在 Alpha 回贴后执行内存像素规整，最终 OSS PUT、项目资源和画布图层数量不得增加。
 - 默认打开角色生成面板时选中 `nanobanana2 / 1:1 / 1K`；切换到 `gpt-image-2` 后再次打开角色或图标素材面板应沿用该模型。
 - 生成成功后在占位图位置创建 `assetKind: "character"` 图层，右上角显示 `角色` 标签，布局保存包含该字段。