合并最新master分支

合入 origin/master 最新画布、外部接口与后端模块化改动。

按新队列语义解决画布测试和原生壳检查冲突。

把编辑器 Agent 迁移到模块化实现并适配 LlmRunRequest。

删除已废弃的旧编辑器 Agent 单文件与个人 Claude 本地配置。

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

@@ -103,6 +103,144 @@
 - 影响范围：`apps/ai-game-creator-shell/src-tauri/src/repository_context.rs`、Agent planning prompt、pending repository-context drift 门禁、真实 Runtime E2E harness 和 AI 游戏创作 Runtime 文档。
 - 验证方式：确定性测试覆盖发现根、优先级、YAML/路径/符号链接/预算、metadata 清洗、正文按需可见和 fingerprint 漂移；正式 `openai_chat / gpt-5.5` 的 `project-skill` suite 必须证明 hash-only fixture 先失败、匹配 Skill 在首个变更前读取、无关 Skill 不读取、唯一目标文件修改、Agent 与宿主验证通过，以及 Provider lifecycle、唯一回复、配置隔离和零泄漏全部闭合。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+## 2026-07-18 图片生成 K 档由 provider 直接生成
+
+- 背景：旧 gpt-image-2 尺寸表会把 2K 竖版回落到 `1024x1536`，图标入口又使用固定 `360x360 / 512x512` 占位；角色去背景结果变小时还会直接放大整张透明成品，导致 UI 显示的 2K 与模型实际生成清晰度不一致。
+- 决策：用户选择的模型、比例和 K 档先映射为 provider 可直接接受的真实像素，前端占位、api-server 请求和 VectorEngine request body 保持一致。带显式尺寸选项的用户生成不再用回图后缩放恢复 K 档；宣发素材固定交付尺寸与旧无尺寸请求保留原有兼容恢复。角色、图标和 UI 去背景降采样时只重采样 alpha 蒙版并应用回 provider 原始 RGB，不放大低分辨率后处理 RGB。
+- 影响范围：普通图片、角色形象、图标图集、UI 设计图的占位与生成请求，gpt-image-2 尺寸矩阵，以及角色透明后处理。
+- 验证方式：前端尺寸矩阵和入口占位测试、api-server 生成参数与 alpha 合成测试、platform-image 最终 request body 测试、类型检查、Rust check、编码和 diff 门禁。
+- 关联文档：`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-07-18 阿里云 URL 抠图链路按外部调用阶段审计
+
+- 背景：阿里云 URL 抠图先从源 OSS GET，再解码、校验尺寸、归一化并上传临时 OSS；此前解码和尺寸失败仍使用普通 `InvalidRequest`，被错误标记为 `externalCallAttempted=false`，无法满足阿里云失败统一审计约定。
+- 决策：真正开始外部调用前的本地预检不写 `external_api_call_failure`；源 OSS GET 成功后发生的解码、尺寸、归一化、临时上传、阿里云请求和结果处理失败均进入审计。`platform-matting` 使用结构化 `LocalProcessing` 分类和 `failureStage`，由 api-server 映射为 `source_decode`、`source_validate`、`source_normalize`、`temp_upload`、`result_decode` 等阶段，不再把这些错误统称为“发请求前本地预检”。
+- 影响范围：`server-rs/crates/platform-matting/src/lib.rs`、`server-rs/crates/api-server/src/aliyun_matting.rs`、`server-rs/crates/api-server/src/external_api_audit.rs`、`server-rs/crates/api-server/src/editor_project.rs`、后端架构文档。
+- 验证方式：运行 `cargo test -p platform-matting --manifest-path server-rs/Cargo.toml`、阿里云抠图与外部审计定向测试、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+
+## 2026-07-18 手动去背景稳定媒体引用校验收口
+
+- 背景：当前分支与 `master` 分别增加手动去背景专用 Data URL 校验和编辑器通用稳定媒体引用校验，直接叠加会让 API 与 worker 重复执行语义相同的 helper，并造成 `data:` / `blob:` 覆盖范围和错误文案漂移。
+- 决策：删除手动去背景专用校验。HTTP API 在入队前统一调用 `ensure_editor_reference_image_source_is_stable`，立即拒绝 `data:` / `blob:`；worker 不重复调用该入口校验，只通过 `resolve_editor_reference_object_key_for_owner` 完成稳定引用解析和 owner 归属校验。底层 `resolve_editor_reference_object_key` 在尝试 object key、项目资源 ID 或素材 ID 解析前统一拒绝内联媒体，作为历史任务和内部直接调用的最终边界。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、图片画布手动去背景测试和图片画布技术方案；不改变队列 DTO、BgFilter `image_url` 协议或 SpacetimeDB 的编辑器任务 payload 门禁。
+- 验证方式：覆盖 API 入队前拒绝 `data:` / `blob:`、解析器拒绝内联媒体、worker 只调用稳定引用解析与归属校验；运行 api-server 编辑器定向测试、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-07-17 画布 Agent 普通消息不提供客户端停止
+
+- 背景：普通消息进入 LLM 前，后端已经把用户消息写入 OSS；前端中断 fetch 只能停止本地等待，不能保证后端停止规划，且会保留无法与后端消息对齐的 optimistic message。
+- 决策：移除画布 Agent 普通消息的“停止”按钮和 `stopCurrentTurn`，发送期间保持按钮禁用并等待后端响应。待确认工具调用的“取消”仍保留，不受本决策影响。
+- 影响范围：画布 Agent 对话 hook、发送区交互、前端测试和专题文档。
+- 验证方式：运行画布 Agent hook / 面板定向测试、`npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【编辑器】画布Agent对话面板-2026-07-03.md`。
+
+## 2026-07-10 画布 Agent 工具确认分离执行参数与展示投影
+
+- 背景：画布 Agent 已在实际生成前进入 `pending_confirmation`，但 `EditorAgentToolCall.args` 只保存工具私有 JSON，其中图片参数是保护真实 data key 的 SHA-256 opaque ID。前端直接解析 raw args 只能显示内部哈希或图片数量，无法向用户准确展示即将使用的目标图、参考图和完整参数；若直接把图片 URL 或对象塞回 raw args，又会破坏确认执行反序列化和 LLM 不可见真实 data key 的安全边界。
+- 决策：`EditorAgentToolCall.args` 继续作为确认执行唯一真相，不允许前端改写或回传替代参数；新增必填 `displayArgs` 只读展示投影，内含 `stringArgs`、`imageArgs` 和 `extras.priceMudPoints`。`stringArgs` 承载提示词与规格等用户可见字段，`imageArgs.refs` 承载 `imageId` 及后端解析出的 `objectKey`、`imageSrc`、可选缩略图、标签和尺寸；`extras.priceMudPoints` 由 api-server 在创建待确认消息时使用后端运行时模型定价快照计算，前端只显示“预计消耗 N泥点”，不自行计算或回传价格。api-server 必须按已注册 tool 白名单，从已校验 args 与 OSS 会话文档的附件 / 历史生成结果构建该投影；前端只渲染投影，以 `ResolvedAssetImage` 换签显示图片，不解析 tool 私有 schema、不展示 SHA-256 ID。展示价格不参与确认执行或实际扣费，确认后仍由既有生成 BFF 按后端运行时定价预扣费。删除只重复 `args` 且没有稳定语义的 `EditorAgentToolCall.summary`。模块尚未上线，不保留缺少 `displayArgs` 时读取 raw `args` 的旧消息降级路径。
+- 影响范围：`shared-contracts` / `packages/shared` 的 `editorAgent` DTO、`api-server/src/editor_agent/api.rs` 的待确认消息构建、画布 Agent 待确认卡、OSS 会话消息文档与相关测试。
+- 验证方式：`cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml editor_agent`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_agent`、`npm run test -- src/components/image-editor/EditorAgentConversation/EditorAgentConversationPanelView.test.tsx src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.test.tsx src/services/image-editor/editorAgentClient.test.ts`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md`。
+
+## 2026-07-18 图片多产物任务的原图进入正常完成画布
+
+- 背景：角色形象、图标 spritesheet 和 UI 素材提取会同时持久化带纯色背景的 provider 原图与透明后处理结果；这些原图都需要在画布中可直接查看和复用。任务与扣费实际仍只有一次。
+- 决策：provider 原图继续写入 OSS、`asset_object`、项目资源和账号素材库。三类任务透明处理正常成功时，透明结果作为主图并保持生成器 `generatedLayerId` 锚点，provider 原图作为第二个图层放在透明主结果右侧；图标和 UI 的业务拆分素材从原图右侧继续排列。只有透明背景处理最终失败时，才把 provider 原图作为唯一主图完成占位并返回 warning。
+- 影响范围：角色形象、图标 spritesheet、UI 素材提取的画布完成快照，以及多产物持久化与画布展示边界。
+- 验证方式：后端定向测试断言三类任务正常成功都落透明主图与右侧 provider 原图、`generatedLayerId` 仍指向透明主图，图标 / UI 拆分素材继续排列在原图右侧，同时保留 source-only 失败降级测试；并运行 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-07-17 生成后抠图原图以 OSS 作为内存生命周期边界
+
+- 背景：角色形象、图标图集、UI 素材图集和角色动作抽取帧的带背景原图虽然已先落私有 OSS，但 api-server 仍可能把原图字节保留到 BgFilter / 阿里云 / 本地 fallback 结束，造成并发任务下的内存峰值叠加。
+- 决策：目标链路的带背景原图上传 OSS 时消费 `DownloadedImage` 或动作帧字节所有权，不为上传克隆整张字节缓冲；上传完成后不再跨 BgFilter 调用常驻。手动去背景直接复用已有 OSS object key，不下载原图。BgFilter 只读取 600 秒签名 URL；进入阿里云 fallback 时由 `platform-matting` 新 URL 接口下载原图、上传 `AuthorizeFileUpload` 临时对象，并在开始阿里云推理前结束下载缓冲作用域；阿里云继续失败时，api-server 再从私有 OSS 独立下载原图供本地键色，产出后释放本次原图下载缓冲。
+- 边界：不改变接口 DTO、资源记录、画布原图展示、图集切分行为和降级顺序；“释放”指 Rust 所有权和 `Vec<u8>` 析构，RSS 不保证同步下降。
+- 验证方式：`platform-matting` 测试覆盖 URL 下载缓冲在临时上传后结束、降尺寸 Alpha 回贴；`api-server` 结构测试覆盖带背景原图 owned 上传、URL 阿里云 fallback、本地重新下载与原图释放；随后运行两个 crate 的测试与编译检查。
+
+## 2026-07-17 图片改造保持源图与所选清晰度
+
+- 背景：图片画布从已生成的 2K 角色图重新打开生成器时，面板恢复逻辑会优先采用新建面板的 1K 默认值；即使用户重新选择 2K，角色透明化链路也可能接受 BgFilter / 阿里云返回的 1K 后处理图，并因 `nanobanana2` 使用标量清晰度档位而跳过几何尺寸恢复，最终把 2K provider 原图降为 1K 透明图。
+- 决策：从既有图片重新打开普通图片、角色、UI 或宣发生成器时，在没有仍存活的生成对话框快照时按当前图层真实 `originalWidth / originalHeight` 恢复比例与清晰度，并按目标模型支持范围归一；恢复或切换比例 / 清晰度后，普通图片、角色、图标图集和 UI 设计图的待生成及生成中占位框必须同步使用目标像素尺寸，不能保留新建 draft 的默认 1K 框。UI 素材提取的占位按框选数量对应的 1K / 2K 计划生成，旧图片修改入口按源图真实尺寸占位。角色形象去背景完成后必须保持去背景前 provider 原图的像素尺寸；若去背景供应商返回较小结果，只把 alpha 蒙版重采样回原图并保留原始 RGB，不放大低分辨率透明成品。
+- 影响范围：图片画布生成对话框恢复、生成中占位尺寸、UI 素材提取与旧图片修改的 `canvasCompletion`、角色形象 BgFilter / 阿里云 / 本地去背后处理、项目资源与账号素材尺寸元数据。
+- 验证方式：覆盖“持久化 2K 角色图重开仍为 2K”“普通图片 / 角色 / 图标 / UI 改造的 2K 占位与目标一致”“普通生图、规范图和角色图生成中占位不回退 1K”“UI 提取和旧修改入口的完成占位使用业务目标尺寸”以及“较小去背结果只提供 alpha、最终 RGB 仍来自 2K provider 原图”的前后端定向测试，并运行前端类型检查、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
+
+## 2026-07-15 BgFilter 输入改用私有 OSS 短期签名 URL
+
+- 背景：角色形象、图标图集、UI 素材图集、角色动作抽取帧和手动去背景在调用 BgFilter 前都已有私有 OSS object key；继续由 api-server 下载或保留图片并作为 multipart `file` 再上传，会重复传输图片字节并占用 API 进程网络与内存。
+- 决策：上述抠图链路统一复用 object key，签发 600 秒 OSS GET URL，并通过 BgFilter multipart 的 `image_url` 字段提交；请求中不再携带 `file`。签名 URL 只交给 BgFilter，不写日志或持久化。2026-07-17 起，生成原图和动作帧上传后不再保留图片字节；进入“阿里云通用抠图 → 本地键色”兜底链时按阶段从私有 OSS 重新下载。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、相关测试与文档；不改变 BgFilter endpoint、鉴权、`screen_color`、`seg_model`、输出校验、熔断规则、阿里云上传协议或降级顺序。
+- 验证方式：定向测试必须断言 BgFilter 请求函数包含 `image_url` 与 600 秒 OSS 换签，不包含 multipart `file` 或源图字节读取；随后运行 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`。
+
+## 2026-07-15 阿里云通用抠图上传切换到 AuthorizeFileUpload 正式链路
+
+- 背景：`platform-matting` 原先通过 `viapiutils/GetOssStsToken` 获取临时 AK/SK，再向固定 `viapi-customer-temp` 共享桶执行 OSS V1 PUT。阿里云官方文档将该显式生成 URL 的共享临时桶通道标记为不保证 SLA、仅便于调试且不推荐生产使用；动作视频逐帧抠图会把这条风险放大到每任务 32 至 48 次。
+- 决策：非上海地域图片字节统一按新版官方 SDK `AdvanceRequest` 的实际协议处理：调用 `openplatform.aliyuncs.com` 的 `AuthorizeFileUpload` 获取单对象 `Bucket`、`Endpoint`、`AccessKeyId`、`EncodedPolicy`、`Signature` 与 `ObjectKey`；再以 multipart Policy POST 上传到动态返回的上海临时 OSS，表单字段为 `OSSAccessKeyId`（= AccessKeyId）、`policy`（= EncodedPolicy）、`Signature`、`key`（= ObjectKey）、`success_action_status=201` 与 `file`，最后把临时对象 URL 交给 `SegmentCommonImage`。移除 `GetOssStsToken`、固定 `viapi-customer-temp`、AccessKeySecret/SecurityToken 临时凭证组合和 OSS V1 SHA-1 签名；Policy POST 仍需要授权响应中的 `AccessKeyId`，不再下发可独立签名的完整临时密钥。图片归一化、结果下载、原尺寸 Alpha 回贴和上层降级顺序保持不变。该链路仍会让图片字节经过执行任务的 api-server / worker 并上传临时 OSS，不把它描述成阿里云服务端直接抓取任意公网 URL。
+- 影响范围：`server-rs/crates/platform-matting`、阿里云抠图冒烟示例、后端架构与开发运维文档；不改变 api-server DTO、动作拆帧、BgFilter 或业务降级契约。
+- 验证方式：`cargo test -p platform-matting --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`，并用真实图片运行 `segment_smoke`，确认授权上传 host 来自动态上海 OSS 且 `SegmentCommonImage` 成功返回。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、阿里云“通用图像分割”与“文件 URL 处理”官方文档。
+
+## 2026-07-15 角色动作 BgFilter 请求超时按帧数扩展
+
+- 背景：角色动作全部序列帧会并发进入 BgFilter，而服务端可能在自身进程内排队；固定 `180000ms` 会把排队时间和单帧推理共用同一预算，靠后的请求可能在服务仍正常处理时被 api-server 提前取消。
+- 决策：保留 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 作为统一基准值。只有角色动作逐帧 BgFilter 在共享 Client 的 RequestBuilder 上把每一次 HTTP attempt 覆盖为“基准值 + `2000ms × 本次实际帧数`”，默认 `32 / 40 / 48` 帧为 `244000 / 260000 / 276000ms`；角色形象单图、图标、UI 和手动去背景不增加帧预算。该 timeout 覆盖请求发起到响应体读取完成；首次失败后的重试重新获得同样的 request deadline，整批并发策略、失败排空语义和 worker long-job 总预算不变。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、后端架构、开发运维和图片画布专题文档。
+- 验证方式：运行角色动作超时公式、BgFilter request override 与逐帧流水线定向测试，执行 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-07-15 手动复杂去背景复用 BgFilter 单次重试
+
+- 背景：图片画布手动去背景已经改用 BgFilter `background_mode=complex`，但 worker 仍只发送一次上游请求，短暂网络抖动会直接让任务失败。
+- 决策：手动去背景的 complex 请求复用现有 `EDITOR_BGFILTER_RETRY_COUNT=1`，首次请求失败后立即重试一次，两次都失败仍返回最终错误；本次不把手动 complex 接入标准纯色背景链路的阿里云 / 本地兜底，也不改变 flat 路径的熔断状态。
+- 影响范围：图片画布手动去背景 worker、BgFilter complex 请求日志和 api-server 定向测试。
+- 验证方式：运行 `cargo test -p api-server editor_manual_background_removal_retries_once --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/project-memory/shared-memory/decision-log.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-07-14 手动去背景迁移到 BgFilter complex 模式
+
+> 后续更正：本条关于 multipart 图片文件输入的描述已由 2026-07-15「BgFilter 输入改用私有 OSS 短期签名 URL」和 2026-07-17「生成后抠图原图以 OSS 作为内存生命周期边界」取代；当前手动路径不下载原图，只提交 `image_url`。下文保留作历史记录。
+
+- 背景：图片画布手动“去除背景”此前单独代理 BiRefNet 服务；BgFilter 已增加 `background_mode=complex`，可直接处理非纯色背景，继续保留独立服务会形成重复的上游、配置和错误处理链路。
+- 决策：`POST /api/editor/images/background-removals` 保持前端与 BFF 契约不变，worker 改用现有 BgFilter 地址、token、超时和共享 HTTP client。multipart 提交图片文件、`background_mode=complex`、`seg_model=birefnet` 与 `cross_check=off`，不提交 `screen_color`。标准纯色背景的角色形象、图标 spritesheet、UI 素材提取和角色动作逐帧抠图继续使用 `background_mode=flat`。删除独立 BiRefNet base URL / timeout 配置；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 仅作为 `GENARRATIVE_EDITOR_BGFILTER_TOKEN` 的兼容回退别名。
+- 影响范围：图片画布手动去背景 worker、BgFilter HTTP 协议、api-server 配置、资源元数据、前端 provider 展示和相关文档。
+- 验证方式：运行 api-server BGFilter / 手动去背景定向测试、前端 editorProjectClient / 画布 workflow 定向测试、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## 2026-07-13 外部生成任务持久化真实执行阶段
+
+- 背景：图片画布任务列表此前把所有 `running` 任务固定映射为“正在生成”，角色生图、图标/UI spritesheet、角色动作和手动去背景进入抠图后仍无法展示“正在处理”；前端按耗时推断阶段会产生新的非正式业务真相。
+- 决策：不新增 DB 表，在既有 `external_generation_job` 与 `external_generation_job_summary` 末尾追加带默认值的可选 `phase`。worker claim 时写 `generating`；角色生图、图标 spritesheet、UI 素材提取在调用 BgFilter 前，角色动作在视频生成返回并开始抽帧/逐帧抠图前，手动去背景在执行开始时，通过 `job_id + worker_id + lease_token` 保护的 procedure 写 `processing`。phase procedure 用结构化结果区分 `LeaseFencingRejected` 与 `OtherRejected`；api-server 对 `LeaseFencingRejected` 立即终止，对 `OtherRejected` 以及 SDK 的 `Procedure` / `Runtime` 错误不重试，仅对 `Build` / `ConnectDropped` / `Timeout` 在同一 job attempt 内重试 `1` 次。编辑器 job 固定 `max_attempts=1`，第二次传输失败后进入 `failed`，不回 `pending`、不重新调用 provider，也不按错误文案猜测拒绝类型。BFF 将 `running + processing` 映射为“正在处理”，其它 `running`（含旧数据 `phase=None`）映射为“正在生成”；前端只展示后端投影。
+- 影响范围：`external_generation_job`、`external_generation_job_summary`、SpacetimeDB procedure / typed client / bindings、图片画布生成 worker、任务列表 BFF 与相关文档。
+- 验证方式：运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、外部生成 module/client/api-server 定向测试、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-07-13 角色动作逐帧开启 BgFilter cross-check
+
+- 背景：角色动作逐帧抠图此前为减少额外推理开销固定传 `cross_check=off`，但动作帧同样需要保留发丝、镂空和运动边缘质量。
+- 决策：角色动作逐帧 BgFilter 请求固定显式传 `cross_check=on`，与角色形象保持一致；图标 spritesheet 和 UI 设计图素材提取继续固定传 `off`。该策略仍属于后端内部供应商参数，不进入前端或外部 OpenAPI。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、后端架构文档和图片画布技术文档。
+- 验证方式：运行 `cargo test -p api-server editor_bgfilter_cross_check --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_character_animation_frames_use_three_stage_matting_fallback --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-07-13 角色动作 BgFilter 全帧流水线与单次重试
+
+- 背景：角色动作抽帧后原先固定 `buffered(3)`，并在整批绿幕源帧串行落 OSS 后才开始抠图；每帧还单独创建 HTTP Client。公网 BgFilter 的网络等待会让服务端推理队列出现空档，且首个最终错误会通过 `try_collect` 提前取消 api-server 中其余已发 Future。
+- 决策：BgFilter HTTP Client 在 `AppState` 中统一创建并复用 keep-alive 连接池；每次 BgFilter 调用失败后立即重试 `1` 次，两次都失败才进入既有“阿里云通用抠图 → 本地键色”降级链，每次已发失败调用都保留审计。角色动作全部 `32 / 40 / 48` 帧按“单帧绿幕源图落 OSS → BgFilter/降级 → 透明帧落 OSS”独立流水化，使用覆盖本次全部帧的 `buffer_unordered` 连续发射并携带原始帧序，完成后排序；不在 api-server 新增供应商进程锁或全局 Semaphore。任一帧最终失败时先排空全部已启动 Future，再让整个动作任务失败退款，不发布缺帧动画。
+- 影响范围：`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、后端架构文档和图片画布技术文档。
+- 验证方式：运行 `cargo test -p api-server editor_bgfilter_retries_once_before_fallback --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_character_animation_frames_use_three_stage_matting_fallback --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_canvas_screen_background_generation_uses_bgfilter_postprocess --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+## 2026-07-16 SpacetimeDB 备份采用逐文件基线、CAS 增量与安全历史清理
+
+- 背景：SpacetimeDB standalone 2.6.0 不自动删除已被 snapshot 覆盖的历史 commitlog 与旧 snapshot；反复压缩整个 `/stdb` 会重复占用磁盘、停机和 OSS 带宽。上游 issue #5542 的 contributor 明确说明，不触碰最新 snapshot 与重启所需 commitlog suffix 时，可在运行中移动或删除这些历史文件。
+- 决策：统一脚本新增 `--storage-format files`，完整基线递归保留目录、文件和 data-dir 内部相对符号链接，普通文件按 SHA-256 上传为不可变 CAS 对象，catalog 记录目录、路径、长度、SHA、对象 key 与相对链接目标；绝对或越界链接拒绝备份。相同内容不重复 PUT，后续 full 扫描只上传新增或变化内容，不再生成 tar.gz。旧 `archive` 路径保留兼容。full 必须从停库目录或已验证的冻结副本生成，不能把在线跨文件扫描称为一致时点备份。
+- history 继续按 replica 计算安全边界：只接受完整、未锁定且含同 offset `.snapshot_bsatn` 的 snapshot，保留跨越最新 snapshot 的边界 segment 及全部后缀。旧 segment 对和旧 snapshot 被递归映射为单文件 CAS 对象；对象、history catalog、full baseline catalog、候选 fingerprint 与当前边界全部验真后才删除源文件。同库执行用 work-dir PID lock 互斥。
+- OSS 固定恢复入口为 `<prefix>/<database>/latest.json`。CAS 文件和 full/history catalog 保持不可变；latest pointer 只保存最新 full catalog 与已发布 history catalog 的 object key、长度和 SHA，不包含主机绝对路径或文件内容。每次 state 变化先验真全部引用 catalog，再覆盖上传并 HEAD 验真 latest pointer，成功后才落本地 state；history 还必须在 pointer 成功后才允许删除源文件。全新机器可仅凭 bucket、database、prefix 与 OSS 凭据自动下载 pointer 和 full catalog。
+- dev 带宽不足时，允许把已冻结的 dev 基线经 `10.2.0.10 -> 10.2.4.16` 内网 rsync 到 release 独立 staging，再用 release 出口上传 dev bucket；staging 不得指向 release `/stdb`，不得停止或修改 release 服务，传输凭据必须临时创建并在演练后移除。catalog 不记录 staging 绝对路径，files state 可回传 dev 继续 history。
+- 恢复边界：恢复时默认从 OSS `latest.json` 自动定位 full catalog，创建目录并按相对路径下载每个对象、逐文件校验长度与 SHA；本地 state 只用于备份续跑，不再是异机恢复前置条件。远程 dev 已完成真实 OSS、清理、重启和异机隔离恢复演练；release timer 与 publish 前备份继续保持原行为。
+- systemd 接线：主 service 保持 `archive-full`。Server-Provision 新增默认值为 `archive-full` 的 `DATABASE_BACKUP_PROFILE`；dev 或 release 显式选择 `files-history` 时，必须为各自主机指定独立 work-dir，并先用 current release 脚本执行 history dry-run，确认已有 full state 后才安装仓库托管 drop-in，并删除现场手写旧 drop-in。切回默认 profile 必须删除所有 history 覆盖。
+- 影响范围：`scripts/database-backup-to-oss.mjs`、备份门禁、生产 env 示例、systemd 模板、Server-Provision、SpacetimeDB 运维与恢复流程；release timer 可在独立 baseline 验证后显式选择 profile，publish 前备份是否切换仍需单独决策。
+- 验证方式：`npm run check:database-backup`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`；dev 现场必须完成逐文件 full catalog、重复 full 零 PUT、history dry-run、上传后清理、STDB 重启和按 catalog 隔离恢复 roundtrip。
+- 关联：<https://github.com/clockworklabs/SpacetimeDB/issues/5542#issuecomment-4981566448>。
 
 ## 2026-07-14 后台账号采用 owner 引导账号与一级 Tab 实时授权
 
@@ -123,8 +261,9 @@
 ## 2026-07-13 图片画布多产物生成任务必须保存全部可恢复产物
 
 - 背景：角色形象、图标 spritesheet 和 UI 素材提取会先得到带纯色背景的原图，再执行抠图或拆分；图片修改会先得到模型对齐尺寸的原始输出，角色动作会先得到绿幕预览视频，再抽帧和抠图。此前部分原始产物只登记到 OSS，或者要等后处理成功后才进入项目资源，用户无法在失败后找回已经生成成功的内容。
-- 决策：凡一次资产生成任务产生多个具有独立复用价值的产物，后端必须把上游已返回的中间产物写入 OSS、`asset_object`、项目资源和账号素材库，再执行抠图、抽帧或拆分；未指定素材文件夹时进入默认“项目”文件夹。角色形象、图标 spritesheet 和 UI 素材提取同时保留纯色背景原图与透明后处理结果。普通图片和图片修改的纯尺寸变换不属于独立产物：provider 回图保留在内存，变换成功只上传变换结果，变换失败只上传 provider 原图，整个流程只写一次 OSS 并只创建一个素材，不能制造重复“原始输出”。`nanobanana2` 使用标量清晰度档位和独立比例，保留 provider 输出尺寸，不按 `WIDTHxHEIGHT` 解析。角色动作把绿幕预览视频作为一个可复用素材保存，逐帧源图继续留在同一任务 OSS 路径，不把 32 至 48 帧逐张灌入素材库。去背景、音频等没有独立上游中间产物的任务不制造重复副本。
-- 画布、成本与降级：有项目上下文的图片多产物继续由同一次 `canvasCompletion` 写入权威画布快照，生成器 `generatedLayerId` 锚定主后处理结果。图标和 UI 图集自动拆分是 best-effort；识别或切片持久化失败仍完成整张透明图集，并在 inline、队列轮询和刷新后任务列表中提示非阻断 warning，不得借用失败错误字段。provider 原图或角色动作预览视频承载该任务的模型生成成本，抠图、逐帧处理、透明图集和切片等后处理派生产物的 `generation_cost_mud_points = 0`，避免把生图成本误显示成抠图成本；所有中间产物沿用所属任务的真实 `asset_kind`，角色原图仍为 `character`、图标和 UI 图集原图仍为 `icon-spritesheet`、角色动作预览仍为 `character-animation`，不得再写新的“原图类型”。后台素材查询按任务分页，最终产物作为父行并显示任务总成本，每个中间产物作为可展开的独立子行显示阶段生成器和阶段成本。扣费确认边界保持为 provider 成功，OSS、尺寸恢复和画布回填不延长退款保护。
+- 决策：凡一次资产生成任务产生多个具有独立复用价值的产物，后端必须把上游已返回的中间产物写入 OSS、`asset_object`、项目资源和账号素材库，再执行抠图、抽帧或拆分；未指定素材文件夹时进入默认“项目”文件夹。角色形象、图标 spritesheet 和 UI 素材提取在透明背景处理正常成功时同时保留纯色背景原图与透明后处理结果；透明背景处理最终失败时只保留已经持久化的 provider 原图，并按下一条降级规则收口。普通图片和图片修改的纯尺寸变换不属于独立产物：provider 回图保留在内存，变换成功只上传变换结果，变换失败只上传 provider 原图，整个流程只写一次 OSS 并只创建一个素材，不能制造重复“原始输出”。`nanobanana2` 使用标量清晰度档位和独立比例，保留 provider 输出尺寸，不按 `WIDTHxHEIGHT` 解析。角色动作把绿幕预览视频作为一个可复用素材保存，逐帧源图继续留在同一任务 OSS 路径，不把 32 至 48 帧逐张灌入素材库。去背景、音频等没有独立上游中间产物的任务不制造重复副本。
+- 画布、成本与降级：有项目上下文的图片多产物继续由同一次 `canvasCompletion` 写入权威画布快照，正常成功时生成器 `generatedLayerId` 锚定主后处理结果，角色形象、图标 spritesheet 和 UI 素材提取都把 provider 原图作为第二个图层放在透明主结果右侧；图标和 UI 的业务拆分素材从原图右侧继续排列。三类任务已经保存 provider 原图、但透明背景处理最终失败时，任务以 `completed + warning` 收口，原图作为唯一主图完成画布占位；不写入不存在的透明处理图，图标和 UI 也不继续拆分。透明处理成功后的图标和 UI 图集自动拆分仍是 best-effort；识别或切片持久化失败继续完成整张透明图集，并在 inline、队列轮询和刷新后任务列表中提示非阻断 warning，不得借用失败错误字段。provider 原图或角色动作预览视频承载该任务的模型生成成本，抠图、逐帧处理、透明图集和切片等后处理派生产物的 `generation_cost_mud_points = 0`，避免把生图成本误显示成抠图成本；所有中间产物沿用所属任务的真实 `asset_kind`，角色原图仍为 `character`、图标和 UI 图集原图仍为 `icon-spritesheet`、角色动作预览仍为 `character-animation`，不得再写新的“原图类型”。后台素材查询按任务分页，最终产物作为父行并显示任务总成本，每个中间产物作为可展开的独立子行显示阶段生成器和阶段成本。扣费确认边界保持为 provider 成功，OSS、尺寸恢复和画布回填不延长退款保护。
+- 2026-07-16 告警契约补充：inline / external v1 继续返回结构化原始诊断；queue 有意把通用 `warning` 或 `sliceWarning` 归一为展示就绪字符串，通用 `warning.reason` 原样保留，`sliceWarning.reason` 由 worker 添加“图集已生成，但自动拆分未完成：”前缀，摘要与 BFF 原样投影，Web 直接展示。历史值保留写入时快照，不按新格式回填或推断；该内部字符串契约通过 API/worker 与 Web 同一维护窗口、同版本发布收口，不增加混部兼容层。
 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`character_animation_assets.rs`、外部生成任务摘要、图片画布完成快照、账号素材库和前端生成提示。
 - 验证方式：覆盖中间产物登记先于后处理、默认素材文件夹、图集拆分降级、inline / queue warning 和主结果锚定的定向测试，并运行 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、前端定向测试、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
@@ -132,7 +271,7 @@
 ## 2026-07-12 泥点充值收敛为四档并统一资产入口
 
 - 背景：主站与图片画板的泥点余额入口、余额明细和充值弹窗存在不同实现，旧充值口径仍展示六档泥点、首充双倍和会员购买 / 升级入口，容易让展示、商品资格与后端余额真相发生漂移。
-- 决策：主站与图片画板统一复用公共泥点资产入口，收起态展示总额与充值，展开态只展示不限时泥点、每日免费泥点和使用详情；充值中心 BFF 继续统一下发总额、三桶余额、限时到期时间、每日免费基础重置额及下次重置时间，前端不得自行相减推算，但会员周期限时泥点仅用于存量兼容和后端结算，当前版本不在前台展示。默认泥点商品收敛为 `60 / ¥6`、`180 + 90 / ¥18`、`300 + 150 / ¥30`、`680 + 340 / ¥68` 四档，`60` 档无赠送，后三档按现有 `user_id + product_id` 独立资格规则首次购买加赠 `50%`。当前版本关闭会员购买页签、会员商品和购买 / 升级入口。
+- 决策：主站与图片画板统一复用公共泥点资产入口，收起态展示总额与充值，展开态只展示不限时泥点、每日免费泥点和使用详情；充值中心 BFF 继续统一下发总额、三桶余额、限时到期时间、每日免费基础重置额及下次重置时间，前端不得自行相减推算，但会员周期限时泥点仅用于存量兼容和后端结算，当前版本不在前台展示。钱包明细每次展开都重新读取充值中心 BFF，打开期间实时总额变化时继续补读；图片画板的生成扣费或退款完成后同时刷新总额与充值中心拆分。充值中心读请求必须使用 revision 门禁，支付创建、到账确认等权威响应写入时使旧读失效，避免旧响应覆盖新的每日免费 / 不限时明细。默认泥点商品收敛为 `60 / ¥6`、`180 + 90 / ¥18`、`300 + 150 / ¥30`、`680 + 340 / ¥68` 四档，`60` 档无赠送，后三档按现有 `user_id + product_id` 独立资格规则首次购买加赠 `50%`。当前版本关闭会员购买页签、会员商品和购买 / 升级入口。
 - 影响范围：`profile_recharge_product_config` 默认商品、充值中心 read model、共享前后端契约、主站与图片画板泥点资产入口、充值弹窗、后台充值商品默认值。
 - 验证方式：充值与统一入口定向前端测试、`npm run typecheck`、充值商品定向 Rust 测试、`cargo check -p spacetime-module -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
@@ -145,6 +284,14 @@
 - 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、钱包定向 Rust 测试、个人中心定向前端测试、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
 
+## 2026-07-11 BgFilter 交叉模型否决用于角色形象与角色动作
+
+- 背景：新版 BgFilter 的 `cross_check` 默认开启，会额外运行 HR-matting 第二意见模型；角色形象与角色动作序列帧需要保留发丝、镂空和运动边缘质量；图标 spritesheet 和 UI 素材提取不需要承担这部分额外推理开销。
+- 决策：api-server 调用 BgFilter 时必须显式发送 multipart 字段 `cross_check`，不依赖服务端默认值。角色形象生成和角色动作逐帧去背固定传 `on`；图标 spritesheet 生成和 UI 设计图素材提取固定传 `off`。角色动作逐帧去背与三条静态生图路线复用同一条 `BgFilter → 阿里云通用抠图 → 本地键色` 降级链和同一 BgFilter 熔断器。该字段是后端内部供应商策略，不进入前端请求或外部 OpenAPI。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、图片画布 BgFilter 调用文档。
+- 验证方式：运行 `cargo test -p api-server editor_bgfilter_cross_check --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_canvas_screen_background_generation_uses_bgfilter_postprocess --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_character_animation_frames_use_three_stage_matting_fallback --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
 ## 2026-07-11 SpacetimeDB 工具链统一升级到 2.6.0
 
 - 背景：生产数据副本验证已使用 2.6.0 standalone，而仓库 Rust crate、本地 CLI、生成 bindings、容器与 server provision 仍锁定 2.5.0 或更早版本，继续混用会增加 BSATN / procedure 返回值与发布产物错配风险。
@@ -153,6 +300,14 @@
 - 验证方式：核对 `spacetime --version`，运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo check` / 定向测试、`npm run test -- scripts/dev.test.ts`、server provision 工具测试、production ops / encoding / diff 门禁。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## 2026-07-17 SpacetimeDB 工具链统一升级到 2.6.1
+
+- 背景：SpacetimeDB 2.6.1 修复 procedure context 中调用者 `Identity` / `ConnectionId` 丢失问题，并修正 TypeScript 生成代码中 `Option<T>` 字段的可选键语义；继续运行 2.6.0 会保留已知 procedure 身份回归。
+- 决策：`server-rs/Cargo.toml` 的 `spacetimedb`、`spacetimedb-sdk`、`spacetimedb-lib` 精确锁定 2.6.1；本地 CLI / standalone、Rust bindings、worker smoke、容器压测镜像和生产 provision 下载根同步对齐 2.6.1。
+- 影响范围：Rust workspace lockfile、SpacetimeDB bindings、本地 dev 版本门禁、容器 smoke / loadtest、server provision Jenkins 与项目 SpacetimeDB skills / 文档。
+- 验证方式：核对 `spacetime --version`，运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo check` / 定向测试、server provision 工具测试、encoding / diff 门禁。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 2026-07-10 外部生成任务只持久化轻量媒体引用并独立维护摘要投影
 
 - 背景：编辑器 worker 化后直接把同步接口 payload 序列化进 `external_generation_job.request_payload_json`；前端又把已有 OSS `objectKey` 下载成 Data URL 再提交，导致单个任务 JSON 膨胀到数 MB，正式任务列表读取 20 条任务时同时搬运约 65 MB payload，并放大为 SpacetimeDB 与 api-server 的瞬时内存峰值。此前“禁止 Data URL 持久化”只覆盖工程、素材、图层和元数据，遗漏了正式生成任务表。
@@ -197,7 +352,7 @@
 ## 2026-07-09 角色动作视频生成背景色统一为多色自动决策 + 阿里云抠帧
 
 - 背景：角色动作视频抽帧过去固定 legacy `#00FF00` 绿幕 + 本地 `editor_green_screen`，与生图链路的多色自动决策不一致；实测出现背景色与前景 / 皮肤撞色（蓝撞蓝、桃 / 黄撞肤色）以及图生视频背景变白的问题。
-- 决策：角色动作视频背景色与生图统一。`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、`reasoning_effort=low`，`max_tokens=1024`）读源角色图自动决策，并经硬过滤器（Lab 危险质量 + 皮肤专属三判据：ΔE 距离 / 色调投影 / RGB 分离）剔除与前景及皮肤撞色的候选，手动 hex 仍尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景确定性等于抠图键色。抽帧后逐帧优先走阿里云通用抠图，失败降级本地 `editor_green_screen` 键色兜底（按生成时选定的背景色，而非固定 `#00FF00`）。BgFilter 与阿里云抠图失败均写入 `external_api_call_failure` 失败审计。调色板新增中明度低饱和「灰竹绿 `#A0BBA0`」补齐冷区绿色段。
+- 决策：角色动作视频背景色与生图统一。`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、`reasoning_effort=low`，`max_tokens=1024`）读源角色图自动决策，并经硬过滤器（Lab 危险质量 + 皮肤专属三判据：ΔE 距离 / 色调投影 / RGB 分离）剔除与前景及皮肤撞色的候选，手动 hex 仍尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景确定性等于抠图键色。抽帧后逐帧优先走 BgFilter（固定 `seg_model=birefnet`、`cross_check=on`），失败依次降级阿里云通用抠图和本地 `editor_green_screen` 键色兜底（按生成时选定的背景色，而非固定 `#00FF00`）。BgFilter 与阿里云抠图失败均写入 `external_api_call_failure` 失败审计。调色板新增中明度低饱和「灰竹绿 `#A0BBA0`」补齐冷区绿色段。
 - 影响范围：`server-rs/crates/api-server/src/character_animation_assets.rs`、`editor_screen_background_decision.rs`、`editor_screen_background_filter.rs`（新增硬过滤模块）、`editor_green_screen.rs`（调色板）、`external_api_audit.rs`、`llm_model_routing.rs`、图片画布 MVP 与后端数据契约文档。
 - 验证方式：`cargo test -p api-server editor_screen_background character_animation --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、真机对源角色图跑视觉决策与候选危险度表、抽帧后采样序列帧背景色确认落在冷区安全集。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
@@ -312,6 +467,8 @@
 
 ## 2026-07-05 BgFilter 失败时本地纯色去背兜底
 
+> 后续更正：本条关于手动去背景仍使用独立 BiRefNet BFF 的描述已由 2026-07-14「手动去背景迁移到 BgFilter complex 模式」、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代。下文保留作历史记录。
+
 - 背景：曾用一次性 BgFilter live probe 稳定复现 BgFilter 对 2K 输入返回 `HTTP 500 {"detail":"inference failed"}`，浏览器生成链路会因此收到“BgFilter 服务返回非成功状态”。
 - 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取仍优先调用独立 BgFilter；若 BgFilter 请求失败、返回非成功状态、返回空图片或非法图片，api-server 记录 warning 后使用本地 `editor_green_screen` 按解析后的纯色背景执行确定性去背兜底，不中断生成。手动任意图片去背景仍只走独立 BiRefNet BFF，不使用该兜底。
 - 更正（截至 2026-07-10 实现）：BgFilter 失败/熔断后不再直接本地兜底，而是先走阿里云通用抠图，仅阿里云也失败才本地 `editor_green_screen` 键色兜底；口径统一见 2026-07-09「角色动作视频…阿里云抠帧」决策，并已扩展到本条的角色形象/图标/UI 三条静态生图链路。
@@ -321,6 +478,8 @@
 
 ## 2026-07-03 图片画布生成纯色背景资产接入 BgFilter
 
+> 后续更正：本条关于 multipart `file`、手动去背景独立 BiRefNet 配置以及 BgFilter 失败后直接本地兜底的描述，已分别由 2026-07-14、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代。下文保留作历史记录。
+
 - 背景：独立 BgFilter 服务已部署在 image host，并提供 `POST /bgfilter/remove-background`，支持显式 `screen_color` 和 `seg_model`。手动去背景已有独立 BiRefNet BFF，不能把两个服务的配置或语义混在一起。
 - 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取在保存带纯色背景源图后，统一调用 BgFilter 生成透明 PNG；请求 multipart 字段为 `file`、`screen_color=<screenColor>` 和内部固定的 `seg_model=birefnet`。`segModel` 虽是后端可识别的内部兼容字段（另保留 `anime-seg`），但不向用户或外部 OpenAPI 暴露：当前 BgFilter 的内存与并发容量不适合由调用方自由切换模型。BgFilter 使用独立配置 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时 `180000ms`，token 未配置时复用 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`。手动 `POST /api/editor/images/background-removals` 继续使用独立 BiRefNet 配置 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL`，不受 BgFilter 影响。BgFilter 参数里的 `seg_model=birefnet` 只表示 BgFilter 内部分割后端，不等于手动去背景的独立 BiRefNet 服务。若 BgFilter 失败，api-server 对这些标准纯色背景生成图使用本地 `editor_green_screen` 兜底；连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）后，`GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内直接本地兜底。角色动作背景色和抠帧口径已由 2026-07-09 决策取代：角色动作同样使用多色自动决策，抽帧后优先阿里云通用抠图，失败再按选定背景色本地兜底。更正（截至 2026-07-10 实现）：BgFilter 失败与熔断期本条描述的「直接本地兜底」已过时——角色形象/图标/UI 三条静态生图链路同样先走阿里云通用抠图，仅阿里云也失败才本地 `editor_green_screen` 兜底。
 - 影响范围：`server-rs/crates/api-server/src/config.rs`、`server-rs/crates/api-server/src/editor_project.rs`、图片画布 MVP 文档和角色形象生成设计文档。
@@ -362,10 +521,10 @@
 
 ## 2026-07-03 画布Agent会话元数据入 SpacetimeDB、消息正文存 OSS
 
-- 背景：图片画布工程需要对话式编辑历史，但消息正文随流式输出增长，不适合放入表行或画布布局快照；同时画布 Agent 只属于编辑器画布域，不能复用拼图 `creative-agent` 内存会话。
-- 决策：新增 `module-editor-agent` 承载纯领域规则，`editor_agent_conversation` 只保存会话元数据，完整消息以 `editor-agent/{conversationId}.json` 会话粒度存 OSS；`api-server` 负责编排 LLM、SSE、OSS 读写和既有生成工具调用。
+- 背景：图片画布工程需要对话式编辑历史，但消息正文随对话和工具结果增长，不适合放入表行或画布布局快照；同时画布 Agent 只属于编辑器画布域，不能复用拼图 `creative-agent` 内存会话。
+- 决策：`module-editor-agent` 只承载可供 SpacetimeDB WASM 使用的纯领域规则；Agent runner、工具实现和资产 DTO 迁入原生 `platform-editor-agent`，仅由 `api-server` 依赖。`editor_agent_conversation` 只保存会话元数据，完整消息以 `editor-agent/{conversationId}.json` 会话粒度存 OSS；`api-server` 负责编排 LLM、普通 JSON 消息、OSS 读写和既有生成工具调用。用户消息以独立 `clientMessageId` 在会话锁内幂等，数字 `message.id` 只作后端定位；旧 OSS 消息允许缺失幂等键，早期用户消息字符串 `id` 在读取时迁入 `clientMessageId`。画布 Agent 只与任务侧栏互斥，不与左侧素材 / 图层栏互斥。
 - 影响范围：图片画布右侧 Agent 面板、`shared-contracts` / `packages/shared` 的 `editorAgent` 契约、`spacetime-module` / `spacetime-client`、`platform-oss` 内部读签名边界、画布生成落板规则。
-- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo test -p module-editor-agent --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_agent`、前端 Agent 面板与 SSE client 定向测试、`npm run check:encoding`、`git diff --check`。
+- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo test -p module-editor-agent --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_agent`、前端 Agent 面板与 JSON client 定向测试、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
 
 ## 2026-07-01 认证工作集只经 typed projection 同步正式表
@@ -378,6 +537,8 @@
 
 ## 2026-06-29 图片画布手动抠图走远端 BiRefNet BFF
 
+> 后续更正：本条独立 BiRefNet 服务、专用 base URL 以及 api-server 下载并解析原图的实现，已由 2026-07-14「手动去背景迁移到 BgFilter complex 模式」、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代。下文保留作历史记录。
+
 - 背景：用户手动“去除背景”面对任意图片，前端 `chromaKey` 和标准绿幕后处理不适合复杂人物、自然背景或非纯色背景；远端 image host 已部署 BiRefNet 服务，需要让手动抠图走高质量模型，同时避免把服务令牌暴露到浏览器。
 - 决策：画布手动“去除背景”默认调用登录态同源 BFF `POST /api/editor/images/background-removals`。api-server 解析当前图片后代理到 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL/remove-background`，默认指向 `http://58.87.105.82/remove-background`，可选 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 只在服务端注入。api-server 对上游结果做字节和尺寸上限保护，并先落 OSS / asset object 再返回给前端。编辑器自己生成的标准绿幕资产不属于该决策，见 2026-06-30 绿幕契约收口。
 - 影响范围：api-server 编辑器图片接口、图片画布手动去背景、画布右上角任务侧栏、图片画布 MVP 技术文档。
@@ -551,13 +712,15 @@
 ## 2026-06-18 图片画布 UI 设计图提取素材保留图集
 
 - 背景：UI 设计图需要从成图中继续抽取可复用独立素材；原图标素材生成只把拆分后的图标放入画布，spritesheet 原图没有保留，后续追溯和二次切图不方便。
-- 决策：`assetKind="ui-design"` 图层浮动工具栏新增 `提取素材`，点击后先进入红框素材框选编辑态，默认矩形框选，并支持椭圆框选和画笔自由框选。至少存在一个框选区域后才能提交；前端把红色轮廓绘入原 UI 设计图并将合成图作为 `/api/editor/ui-designs/assets/extractions` 的参考图。后端固定 `gpt-image-2` 和纯色背景素材提取提示词，返回结构复用图标 spritesheet 响应。UI 提取把 spritesheet 图集作为 `assetKind="icon-spritesheet"` 图层放到画布，再放拆分后的 `assetKind="icon"` 素材。2026-07-03 起，UI 提取的纯色背景由 `screenColor` 选择并经 BgFilter 透明化。2026-07-13 起，图标素材生成先把带背景原图和透明 spritesheet 同时写入项目资源、账号素材库并回填画布，未指定文件夹时落默认“项目”文件夹，再 best-effort 按 alpha 连通域拆分独立图标；拆分失败不改变生成成功状态，响应以空 `iconImageSrcs` 和结构化 `sliceWarning` 返回原因，用户可从图集工具栏手动重试。手动拆分不计费，限制单边 `4096`、总像素 `2048×2048`、最多 `64` 个切片，所有切片用 `sourceResourceId` 指向透明图集。`icon-spritesheet` 图集继续显示并允许快速编辑，只有拆分后的 `assetKind="icon"` 单图标隐藏并拒绝快速编辑；工具栏、右键菜单、打开流程和提交兜底必须共用同一判定。本条新决策取代“图标素材生成只保留图集”的旧口径。
+- 决策：`assetKind="ui-design"` 图层浮动工具栏新增 `提取素材`，点击后先进入红框素材框选编辑态，默认矩形框选，并支持椭圆框选和画笔自由框选。至少存在一个框选区域后才能提交；前端把红色轮廓绘入原 UI 设计图并将合成图作为 `/api/editor/ui-designs/assets/extractions` 的参考图。后端固定 `gpt-image-2` 和纯色背景素材提取提示词，返回结构复用图标 spritesheet 响应。透明背景处理正常成功时，UI 提取把透明 spritesheet 图集作为 `assetKind="icon-spritesheet"` 图层放到画布，再放 provider 原图和拆分成功的 `assetKind="icon"` 素材。2026-07-03 起，UI 提取的纯色背景由 `screenColor` 选择并经 BgFilter 透明化。2026-07-13 起，图标素材生成在透明背景处理正常成功时把带背景原图和透明 spritesheet 同时写入项目资源、账号素材库和画布，未指定文件夹时落默认“项目”文件夹，再 best-effort 按 alpha 连通域拆分独立图标；拆分素材从 provider 原图右侧继续排列。拆分失败不改变生成成功状态，响应以空 `iconImageSrcs` 和结构化 `sliceWarning` 返回原因，用户可从图集工具栏手动重试。2026-07-16 起，透明背景处理最终失败时只把已经持久化的 provider 原图作为唯一主图放入画布，以 `completed + warning` 收口，不创建透明图集，也不继续拆分。手动拆分不计费，限制单边 `4096`、总像素 `2048×2048`、最多 `64` 个切片，所有切片用 `sourceResourceId` 指向透明图集。`icon-spritesheet` 图集继续显示并允许快速编辑，只有拆分后的 `assetKind="icon"` 单图标隐藏并拒绝快速编辑；工具栏、右键菜单、打开流程和提交兜底必须共用同一判定。本条新决策取代“图标素材生成只保留图集”的旧口径。
 - 影响范围：图片画布浮动工具栏、编辑器图片生成 BFF、`platform-image` 图集连通域拆分、画布图层类型和编辑器文档。
 - 验证方式：运行图片画布工具栏 / 图集落层 / 生成提交相关前端测试，`cargo test -p platform-image generated_asset_sheets --manifest-path server-rs/Cargo.toml`，以及 `cargo test -p api-server editor_ui_design_asset_extraction_prompt_is_fixed --manifest-path server-rs/Cargo.toml`。
 - 关联文档：`docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`。
 
 ## 2026-06-30 图片画布标准绿幕契约收口
 
+> 后续更正：本条关于生成资产只使用本地透明化、手动路径继续使用独立 BiRefNet 的描述，已由 2026-07-14、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代；当前 flat 链路为 `BgFilter → 阿里云 → 本地键色`。下文保留作历史记录。
+
 - 背景：角色形象、图标 spritesheet、UI 提取 spritesheet 和角色动作帧都要求模型生成标准绿幕，但提示词片段和后处理入口分散在多个模块中，容易把标准绿幕资产误接到远端 BiRefNet。
 - 决策：编辑器标准绿幕提示词和本地确定性绿幕透明化统一收口到 `server-rs/crates/api-server/src/editor_green_screen.rs`。手动 `POST /api/editor/images/background-removals` 继续面向用户任意图片并走 BiRefNet；编辑器自己生成的标准绿幕资产统一复用 `platform-image::generated_asset_sheets` 的本地透明化能力，不再依赖 BiRefNet。角色图、图标 spritesheet、UI 提取 spritesheet 和角色动作抽帧源图必须在绿幕透明化前先保存一份带绿幕原图到 OSS，便于追溯和重处理。
 - 影响范围：`editor_project.rs` 的角色图 / 图标图集 / UI 提取图集、`character_animation_assets.rs` 的编辑器角色动作帧、编辑器绿幕相关文档。
@@ -1539,7 +1702,7 @@
 - 2026-06-07 追加：`GENARRATIVE_EXTERNAL_GENERATION_MODE` 使用 `queue|inline` 显式策略；生产和容器扩缩容验证保持 `queue`。本地开发若需要同步等待结果，应通过 `.env.local` 或本机环境显式配置为 `inline`，由 HTTP handler 复用同一 worker executor 直接返回 `completed`，不创建 `external_generation_job`，不支持 worker 动态扩缩容；脚本不得硬编码该策略。拼图写回 guard 字段改为可选，queue 路径仍必须完整校验 `job_id + worker_id + lease_token`；inline 路径只允许三项同时为空，半空 guard 仍拒绝。
 - 2026-06-11 追加：生产新增固定 `external-generation-controller` 进程角色和 `genarrative-external-generation-controller.service`。controller 只读取 `get_external_generation_queue_stats_and_return` 队列统计并管理 `genarrative-external-generation-worker@N.service`，不监听 HTTP、不执行外部生成任务；默认保留 `@1`，按 `claimable_pending + running_active + expired_running` 计算目标实例数，上限由 `GENARRATIVE_EXTERNAL_GENERATION_CONTROLLER_MAX_WORKERS` 控制，缩容需要连续空闲轮数且每轮只停最高编号一个实例。
 - 2026-07-08 追加：生产 worker/controller 作为轻量 SpacetimeDB 客户端运行，专属 env 示例默认 `GENARRATIVE_SPACETIME_POOL_SIZE=1`；非 HTTP 角色只保留 `external_generation_job` 队列窄订阅作为响应式唤醒信号，实际抢占和扩缩容判断仍走 SpacetimeDB procedure，且不再订阅 API 读模型连接池。worker/controller poll interval 只作为订阅失效、漏事件和 lease 过期这类时间条件的兜底，不作为正常领取任务的主路径。
-- 2026-07-08 追加：worker lease 默认从 `3600s` 收短到 `600s`，普通 job 执行预算默认 `900s`，视频 / 角色动作等长 job 默认 `1800s`；预算到期后当前 worker 结束本次尝试、写失败 / 重试状态并释放 worker 槽位，若 SpacetimeDB 当时不可写则最多等到较短 lease 过期后重新领取，避免无进展续租无限延长。资产计费层对已扣费但 future 被取消的外部生成操作做异步补偿退款，避免超时取消绕过退款 outbox。
+- 2026-07-08 追加：worker lease 默认从 `3600s` 收短到 `600s`，普通 job 执行预算默认 `900s`，视频 / 角色动作等长 job 默认 `1800s`；预算到期后当前 worker 停止续租并释放 worker 槽位，但不取消已启动的业务 future，也不主动写失败 / 重试状态。在途写回由 lease fencing 仲裁：有效租约内照常完成，租约过期后任务可被重新认领，attempt 耗尽时由认领事务原子标记失败并结算退款，避免客户端取消与服务端写回发生竞态。
 - 影响范围：`server-rs/crates/spacetime-module/src/external_generation.rs`、`server-rs/crates/spacetime-client/src/external_generation.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`、`server-rs/crates/api-server/src/external_generation_worker_controller.rs`、`deploy/systemd/genarrative-external-generation-worker@.service`、`deploy/systemd/genarrative-external-generation-controller.service`、`deploy/env/external-generation-controller.env.example`、`scripts/deploy/production-api-deploy.sh`、`scripts/jenkins-server-provision.sh`、拼图 `compile_puzzle_draft`、拼图 `generate_puzzle_images`、拼图 `generate_puzzle_ui_background`、生产 env 模板和运维文档。
 - 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:server-rs-ddd`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`，并在 queue 模式下用 `GENARRATIVE_PROCESS_ROLE=all npm run dev` smoke 至少一次 queued -> worker 完成链路；本地 inline 排查只确认不创建 `external_generation_job`。
 - 关联文档：`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
@@ -2518,7 +2681,7 @@
 ## 2026-05-07 server-rs Cargo 依赖集中到 workspace
 
 - 背景：`server-rs` 多 crate 已稳定成 DDD workspace，成员 `Cargo.toml` 中重复散写第三方版本和本地 path 依赖，升级 SpacetimeDB SDK、`serde`、`reqwest`、`tokio` 等依赖时容易漂移。
-- 决策：`server-rs/Cargo.toml` 的 `[workspace.dependencies]` 统一维护第三方依赖版本和 workspace 内部 crate path；成员 crate 默认使用 `{ workspace = true }`，只保留自身 feature、optional 或 target-specific 差异；OSS 与阿里云 OpenAPI 签名统一走 `sha2::Sha256` 对应的 V4/V3 口径。例外：`platform-matting` 向 VIAPI 官方临时 OSS 桶上传抠图输入时，因该临时桶接口要求 OSS V1 头签名，允许在该 crate 内部受限使用 `sha1` / `Hmac<sha1::Sha1>` 生成 V1 签名；该例外不得扩展到自有 OSS、通用阿里云 OpenAPI 或其它新链路。
+- 决策：`server-rs/Cargo.toml` 的 `[workspace.dependencies]` 统一维护第三方依赖版本和 workspace 内部 crate path；成员 crate 默认使用 `{ workspace = true }`，只保留自身 feature、optional 或 target-specific 差异；OSS 与阿里云 OpenAPI 签名统一走 `sha2::Sha256` 对应的 V4/V3 口径。2026-07-15 起，`platform-matting` 已移除 VIAPI 共享临时桶的 OSS V1 SHA-1 例外，改用 `AuthorizeFileUpload` 返回的 Policy POST 授权；后续不得恢复 crate 内 SHA-1 签名。
 - 影响范围：`server-rs/Cargo.toml`、所有 `server-rs/crates/*/Cargo.toml`、`platform-oss`、`platform-auth`、后续新增 Rust crate 或新增 Rust 依赖的开发流程。
 - 验证方式：修改 Cargo 配置后先执行 `cargo metadata --manifest-path server-rs\Cargo.toml --format-version 1 --no-deps`，再按影响范围执行 `cargo check`、DDD 边界检查和编码检查。
 - 关联文档：`docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md`。
@@ -3347,8 +3510,9 @@
 ## 2026-06-19 编辑器角色形象回填改用通用抠图
 
 - 背景：画板编辑器里的 `生成角色形象` 属于编辑器图片生成链路，用户要求把“人物抠图”改成通用抠图方法，不再与 RPG / 资产工坊角色主图专用后处理绑定。
-- 决策：仅 `/api/editor/images/generations` 中 `kind = "character"` 的编辑器角色形象回填改用 `platform-image::generated_asset_sheets` 通用绿幕 / 近白去背能力，并开启内部镂空检测；输出仍归一为透明 PNG。`character_visual_assets::try_apply_background_alpha_to_png` 继续服务 RPG 角色主图与 Big Fish 等“角色主图口径”调用者，本轮不改变这些链路。
+- 决策：仅 `/api/editor/images/generations` 中 `kind = "character"` 的编辑器角色形象回填改用 `platform-image::generated_asset_sheets` 通用绿幕 / 近白去背能力，并开启内部镂空检测；透明背景处理正常成功时输出归一为透明 PNG。`character_visual_assets::try_apply_background_alpha_to_png` 继续服务 RPG 角色主图与 Big Fish 等“角色主图口径”调用者，本轮不改变这些链路。
 - 2026-06-22 补充：所有明确设置绿幕用于后续抠图的 prompt 都必须固定写明 `#00FF00 / RGB(0,255,0)`，不能只写“纯绿色绿幕”或“接近 #00FF00”；编辑器角色图通用抠图额外开启暗绿 / 灰绿绿幕背景识别，只作为生成模型偏离标准亮绿时的兜底。该宽松识别只参与从画布边缘连通扩散出的背景清理，不参与全图断开绿色区域删除，避免误伤角色衣物或纹理。
+- 2026-07-16 补充：透明背景处理最终失败、但 provider 原图已持久化时，角色任务以 `completed + warning` 收口，provider 原图作为唯一主图放入画布，不创建透明处理图。
 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
 - 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_character_image_general_cutout`、`cargo test -p platform-image --manifest-path server-rs/Cargo.toml generated_asset_sheet_muted_green_alpha_requires_explicit_option`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
 
@@ -3362,6 +3526,13 @@
 - 影响范围：`server-rs/crates/api-server/src/editor_generation_queue.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/services/image-editor/editorProjectClient.ts`。
 - 验证方式：`cargo test -p api-server external_generation_worker --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_canvas_generation --manifest-path server-rs/Cargo.toml`、`cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml`、`npm run test -- src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/services/image-editor/editorProjectClient.test.ts`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
 
+## 2026-07-13 画布 Agent 工具执行状态复用外部生成任务
+
+- 决策：画布 Agent 的 OSS 工具消息使用 `status=not_completed|completed|failed|cancelled` 和可选 `externalJobId`；不使用 `cancelledAt`，不新增关联表。`external_generation_job` 是排队、执行、lease 与计费结算的唯一真相；OSS status 只表达该消息回填结果，不复制 queued / running。确认接口按 `conversationId + messageId + toolName` 稳定去重并复用既有编辑器 worker job kind。
+- 懒回填：`GET /conversation` 会在持有 conversation lock 后扫描 `status=not_completed` 且有 `externalJobId` 的工具消息，按 job id 定向读取主任务；完成时复用原工具 formatter 更新 system text、写入轻量媒体引用并标记 `completed`，任务本身失败时写入 `error` 并标记 `failed`。任务结果读取或 completed payload 解析 / formatter 首次失败后，在同一次 GET 内最多重试 3 次，每次等待 100ms 并重新读取主任务；读取失败或 completed 任务暂缺 `result_payload_json` 时，本次重试耗尽后保留 `not_completed + externalJobId` 供下次 GET 继续 reconcile，确定性的 payload 损坏、结构不兼容或 formatter 错误才在重试耗尽后写为 `failed`，避免致命错误永久循环。排队 / 执行保持 `not_completed`。worker 的 `result_payload_json` 只保留 formatter 与媒体引用所需的轻量生成回包，不向通用 summary 状态接口投影。
+- 影响范围：画布 Agent 共享契约、确认/取消接口、编辑器生成入队 helper、对话状态展示与恢复。
+- 验证方式：`cargo check -p api-server -p shared-contracts --manifest-path server-rs/Cargo.toml`、画布 Agent 定向前端测试、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+
 ## 2026-06-18 原生壳 WebView 刷新能力只保留受控当前页刷新
 
 - 背景：Expo 移动壳和 Tauri 桌面壳都需要一个真实的宿主级刷新入口，供 H5 在检测到资源、登录态或运行态需要重新载入时请求宿主刷新当前容器；该能力不能演变成任意 URL 导航或原生 WebView ref 透传。
@@ -4348,7 +4519,7 @@
 
 - 背景：VectorEngine Apifox `api-349239079` 暴露 OpenAI-compatible `POST /v1/chat/completions`；创意 Agent 和通用 LLM 代理需要统一到 VectorEngine 文本服务，并将默认文本模型切换为 `gpt-5.4-mini`。
 - 决策：创意 Agent 的 `CREATIVE_AGENT_GPT5_MODEL` 固定为 `gpt-5.4-mini`，协议切到 Chat Completions，不再携带旧 APIMart `official_fallback` 字段；画布 Agent 侧边栏聊天规划请求也复用该模型和 Chat Completions 协议，不再显式使用 `gpt-4o` / Responses。通用 `/api/llm/chat/completions` 代理使用 `GENARRATIVE_LLM_PROVIDER=openai-compatible`、`GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1`、`GENARRATIVE_LLM_MODEL=gpt-5.4-mini`。未单独配置 `GENARRATIVE_LLM_API_KEY` 时，api-server 可复用 `VECTOR_ENGINE_API_KEY`；前端 LLM 客户端必须兼容 OpenAI `choices`、api-server raw `{content}` 和项目 envelope `{ok,data:{content}}` 三种非流式响应，以及 OpenAI SSE delta 和 api-server `event: delta` 两种流式响应。
-- 决策补充：画布 Agent 的 planning prompt 必须自动注入上一条已完成生成结果的 `latestGeneratedImage`，来源为上一轮 generation 的 `summary` / `toolName` / `resourceId` / `objectKey` 等轻量摘要。用户用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代上一张图或继续编辑时，规划默认调用 `edit_image` 并引用该结果；不能因为本轮没有手动附件而退回 `generate_image`。
+- 决策补充：画布 Agent 的 planning prompt 必须自动注入上一条已完成生成结果的 `latestGeneratedImage`，来源为上一轮 generation 的 `toolName` / `resourceId` / `objectKey` 等轻量元数据。用户用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代上一张图或继续编辑时，规划默认调用 `edit_image` 并引用该结果；不能因为本轮没有手动附件而退回 `generate_image`。
 - 决策补充：画布 Agent 侧边栏的“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”是 Agent 规划 prompt 和 function-calling 工具选择约束，不是侧边栏 UI 说明文案。此类请求默认走 `generate_image`，prompt 必须要求规范展板包含统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等视觉规范元素；角色规范图若是规范展板也走 `generate_image`，只有实际角色立绘才走 `generate_character`，多个图标素材 / 图集才走 `generate_icon_spritesheet`。
 - 影响范围：`server-rs/crates/platform-agent`、`server-rs/crates/api-server/src/config.rs`、`src/services/llmClient.ts`、`.env.example`、`deploy/env/api-server.env.example`、`scripts/test-ve-llm.mjs`。
 - 验证方式：`npm run test -- src/services/llmClient.test.ts`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml from_env_reads_non_public_models_and_urls app_state_builds_creative_agent_gpt5_client_from_vector_engine_settings llm_chat_completions editor_agent_llm_request_uses_vector_engine_chat_model`、`cargo test -p platform-agent --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
@@ -4942,3 +5113,8 @@
 - 所有权与清理：账本保留同一 run 的已成功 planning entry，直到 run 完成、取消、失败、作废或明确 reconciliation 清理；这样单动作、多动作、confirmation、协作 batch 和直接回复都不会在下一 durable owner 建立前丢失。steer/cancel/终态/漂移清理前必须按整本账本补齐所有实际 requestId lifecycle，任一条失败时保留账本并进入 reconciliation。Runner 恢复会严格扫描 hash 路径、primary/`.previous` 和安全原子临时文件，清理合法终态遗留；Unix 全程使用固定目录句柄和根目录/Agent 目录 `flock`，安装用 `RENAME_EXCHANGE` 复核回滚，删除用 `RENAME_NOREPLACE` quarantine、inode 复核和原 fd 清空同步；Windows 使用相对父句柄及 `GetFileInformationByHandleEx` 句柄枚举，拒绝 reparse point/junction/硬链接并以禁止共享的独占句柄表示活跃 temp。两端都不依赖 PID 存活判断。未知、链接、目录身份替换或内容冲突项失败关闭。primary、`.previous` 或损坏账本阻止 `runner.shutdown_if_idle`。非协作同 UID 进程可主动忽略 Unix advisory lock，属于宿主 OS 信任边界，不纳入完整沙箱承诺。
 - 验收边界：确定性测试必须分别覆盖 base handoff 与 repair handoff 在 lifecycle completed 前停止，关闭 mock Provider 后恢复零网络、原 requestId 唯一闭合、repair/protocol audit 幂等、唯一 assistant/completed/committed stream和终局零 sidecar。独立非默认真实 suite `supervisor-swarm-tool-plan-handoff-runner-kill` 已实现并完成 Shell/Root 两级注册；它只使用 sentinel-owned sibling AppData 与 metadata-only zero-fault proxy，每轮随机 capability 严格绑定 project/Agent/run/实际 request slot。断点只能在 handoff 原子落盘并回读一致后、同一实际 requestId lifecycle `completed` 前 ACK，ACK 后才通过 pidfd `SIGKILL` 强杀 suite 自有 Runner。恢复必须在同一轮证明同一 requestId 唯一闭合、`networkReplayCount=0`、protocol/repair audit 幂等、handoff 与 durable batch plan fingerprint 对应、恢复消费前 action/pending/delivery/claim 等副作用为 `0`，并在终局得到零 sidecar、零重复、零临时资源残留和零正文/凭据/URL/绝对路径泄漏。2026-07-20 的真实单轮已经到达并通过上述 checkpoint，但随后因专业 Agent 连续连接失败而整轮 FAIL；另一独立轮因首批工具数不满足 fixture 也未通过，不能拼接为 PASS。Provider 成功到 handoff 原子落盘回读前的 unknown-result 及手动 context-compaction 仍不在本决策承诺内。
 - 当前证据：`tool_plan_`、`tool_plan_handoff_`、`provider_handoff_`、`provider_retry_`、`response_stream_`、`finalization_` 与 `finalization_resume_` 定向门禁均保持通过；本轮 `tool_plan_handoff_` 为 `44/44`，Supervisor collaboration 相关过滤为 `55/55`，权威返工合同用例为 `1/1`。Tauri/Rust 串行全量 1058 tests 为 `1054 passed / 4 ignored / 0 failed`，Linux `cargo check --tests` 与 `x86_64-pc-windows-gnu cargo check --tests` 均通过；E2E self-test、typecheck、变更脚本 ESLint、encoding 和 `git diff --check` 通过。默认并发全量只作竞态诊断，不替代 `--test-threads=1`。实现过程中发现并修复 thinking 归一化、源码路径误判、repair 漂移删账本、durable control 清理遗漏后继 repair lifecycle、复数敏感 key/Provider ID 泄漏、malformed JSON trivia 路径绕过、Agent DB 审计字段扩张、PID 复用 temp 误判、中间目录/文件名称换绑 TOCTOU、Windows 路径枚举 ABA 和审计尾部近似去重问题。真实 suite 的 checkpoint 已有单轮外部证据，但整轮仍无 PASS。
+## 2026-07-17 旧创作模板与入口停止维护
+
+- 决策：旧创作模板、旧创作入口及其专属运行服务进入下线范围，不再为跳一跳、抓大鹅 Match3D、儿童动作 Demo 等旧链路修复兼容问题、补生成脚本或维持专属门禁。
+- 边界：共享账号、钱包、资产、图片编辑器、公开作品、通用 HostBridge、API、SpacetimeDB、发布运维和安全能力不属于旧链路，仍需维持正式门禁。历史文档只作为背景材料，不再作为旧入口继续运行的依据。
+- 清理方式：允许直接删除已经失效的旧素材生成命令、入口路由、专属服务和对应测试；删除工程链路时仍需核对是否被当前共享能力引用，不能连带移除仍在使用的公共契约或持久化事实。

docs/project-memory/shared-memory/document-map.md

@@ -1,6 +1,6 @@
 # 文档地图与阅读索引
 
-更新时间：`2026-07-03`
+更新时间：`2026-07-16`
 
 ## 当前文档入口
 
@@ -19,7 +19,7 @@
 | 微信小程序虚拟支付 | `docs/【技术方案】微信虚拟支付接入-2026-05-26.md` |
 | UI 像素资产与 9-slice 规范 | `UI_CODING_STANDARD.md` |
 | 图片画布生成面板与模型定价 | `docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/【编辑器】模型定价配置管理方案-2026-06-22.md` |
-| 图片画布右侧 Agent 对话、会话消息 OSS 持久化、SSE 事件契约、与任务侧栏 / 左侧栏互斥规则 | `docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md` |
+| 图片画布右侧 Agent 对话、会话消息 OSS 持久化、普通 JSON 消息、工具任务懒回填及侧栏并存规则 | `docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md` |
 
 ## 阅读顺序
 

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

@@ -69,6 +69,29 @@
 - 处理：所有分钟级阶段等待都要在每轮先检查 owning task 的 failed/cancelled/budget-exhausted，以及 Runtime 的 needs-reconciliation；命中后立即抛出带阶段前缀的结构化错误。正常 pause 必须保留为可恢复状态，不能被 fail-fast 当失败；Runner 强杀后的 paused 稳定窗口继续按签名零推进单独验证。
 - 验证：用正式 `goal-runtime` 观察 Provider repair transport failure，确认部分报告立即保留成功/repair 协议计数、生命周期闭合和零泄漏证据；随后完整复跑仍能通过 Goal edit/pause/Runner kill/resume/finalization，证明 fail-fast 未破坏正常恢复路径。
 - 关联：`apps/ai-game-creator-shell/scripts/agent-runtime-real-e2e.mjs`、`docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`。
+## 图片生成的 K 档不能靠回图后缩放实现
+
+- 现象：用户选择 2K 时占位框看起来是 2K，最终资源元数据也显示为 2K，但模型请求实际仍是固定 1K 或竖版回落尺寸；画面只是后端放大后的低分辨率结果。
+- 原因：前端占位尺寸、api-server 的模型尺寸映射和 VectorEngine provider 合法尺寸各自维护；同时通用交付恢复与角色去背景恢复会直接缩放整张回图，掩盖了上游请求尺寸错误。
+- 处理：`model + imageSize + aspectRatio` 必须先解析为 provider 可直接生成的真实尺寸，前端占位和后端请求使用同一矩阵。带新尺寸字段的用户生成不执行回图后交付放大；角色、图标和 UI 的去背景服务若降采样，只缩放 alpha 蒙版并应用回模型原始 K 档 RGB。
+- 验证：覆盖 nanobanana2 / gpt-image-2 的比例与 K 档尺寸矩阵、VectorEngine 最终请求体、普通图片 / 角色 / 图标 / UI 占位，以及低分辨率去背景结果只贡献 alpha、不贡献被放大的 RGB。
+- 关联：`src/components/image-editor/ImageCanvasGenerationModel.ts`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/platform-image/src/vector_engine/request.rs`。
+
+## 多产物任务的中间原图不能只落资源库
+
+- 现象：角色形象、图标 spritesheet 或 UI 素材提取正常成功后，画布只有透明结果，用户无法直接对照和复用 provider 原图。
+- 原因：后端虽然为追溯和后处理失败恢复持久化了 provider 原图，但完成画布只写入透明主结果和拆分素材，把“资源已保存”错误等同为“用户已拿到原图”。
+- 处理：provider 原图始终写入 OSS、项目资源和账号素材库；三类任务正常成功时都同时落透明主结果与右侧 provider 原图，生成器 `generatedLayerId` 仍指向透明主结果，图标 / UI 拆分素材从原图右侧继续排列。仅当透明处理最终失败时，才用 provider 原图作为唯一主图完成占位。
+- 验证：覆盖三类任务正常成功都落透明结果与原图、原图位于透明图右侧、`generatedLayerId` 指向透明图、图标 / UI 拆分素材位于原图右侧，以及透明处理失败仍由原图单独完成占位。
+- 关联：`server-rs/crates/api-server/src/editor_project.rs`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`。
+
+## phase 上报的业务拒绝与传输失败不能共用字符串错误
+
+- 现象：provider 已经返回并保存原图，worker 上报 `processing` 时一次断连或超时就直接把任务判为失败；或者为了规避误杀而重试所有错误，导致 stale lease 的旧 worker 继续执行后处理。
+- 原因：phase procedure 的 lease / fencing 业务拒绝与 SDK 建连、断连、超时错误被压成同一种字符串错误，调用方无法可靠决定是否重试；按中文或 SDK 文案匹配会在错误文本变化后失效。
+- 处理：procedure 返回结构化 `LeaseFencingRejected` / `OtherRejected`，typed client 再把模块拒绝与 RPC 错误分开。`LeaseFencingRejected` 立即终止，`OtherRejected` 以及 SDK 的 `Procedure` / `Runtime` 错误不重试；只有 `Build` / `ConnectDropped` / `Timeout` 在同一 job attempt 内重试一次。编辑器 job 固定 `max_attempts=1`，第二次传输失败后进入 `failed`，不回 `pending`、不重新调用 provider。不得让 phase 上报错误落入“后处理失败保留原图”的降级分支。
+- 验证：分别覆盖 lease / fencing 拒绝、其它拒绝、建连、断连、超时和第二次失败，确认最多调用两次；同时断言角色、图标和 UI 的原图降级只包住透明背景处理，不包住 phase 上报。
+- 关联：`server-rs/crates/spacetime-module/src/external_generation.rs`、`server-rs/crates/spacetime-client/src/external_generation.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`。
 
 ## 禁止 Data URL 持久化时不要漏掉异步任务 JSON
 
@@ -151,11 +174,19 @@
 - 验证：画板生成 workflow 测试覆盖 queueState 持续 `running` 到前端等待窗口结束时，不进入 failed、不显示该排队文案、不添加本地临时结果层。
 - 关联：`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx`。
 
+## 图片画布历史不能回退当前权威状态或复活后端已删素材
+
+- 现象：生成占位框移动后开始生成，撤销移动会把仍在运行的生成对象恢复成待生成状态；切换到 2K 或改变比例后撤销位置，旧占位框还可能把当前尺寸回退。上传图层落库后，普通移动撤销可能被提示“可能会使图片消失”并永久卡在栈顶；即使安全检查已放行，直接恢复旧图层快照也会丢失刚回填的资源关联。素材库后端删除关联素材后，更早的移动快照还可能把已删图层重新加入并自动保存；修改素材类型虽然界面提示撤销成功，刷新后却可能从仍指向新类型的 resource 回弹。无稳定 ID 的“修改图片”草稿也可能被 target-null 快照直接关闭。
+- 原因：内容消失安全检查和历史快照合并是两道独立边界。图层内容签名若严格比较 `sourceAssetId`、`sourceResourceId` 等延迟回填的内部关联 ID，会把同一媒体误判为替换；放行后若仍用目标快照整体覆盖同 ID 图层或占位框，又会回退当前权威关联、内容或尺寸。相同 dialog ID 直接恢复整个旧对话框快照还会覆盖当前 `generating` / 完成态；没有 ID 的 edit 草稿则根本不会进入存在性检查。外部素材删除不写画布历史，若不主动剪除包含关联图层的旧目标快照，target-only 图层会被当作正常撤销删除完整恢复。`assetKind` 的正式事实保存在项目 resource，历史只改内存字段而保留当前 `resourceId` 时无法跨刷新成立。
+- 处理：图层内容身份按对象存储 key、对象标识和媒体地址的稳定优先级比较，内部关联 ID 的补齐不参与内容消失判断。同 ID 图层以 current 为权威，只从历史覆盖 `x`、`y`、`zIndex`、`groupId`、`assetKind`、`hidden`、`locked`、`flipX`、`flipY`；current 的资源关联、内容、媒体、生成元数据、尺寸和标题全部保留。同 ID generation dialog 从 target 恢复 placeholder 的 `x` / `y` 和 active / inactive 槽位对应的 `composerOpen`，current 的 `width` / `height` / `originalWidth` / `originalHeight`、当前参数、任务生命周期、提示词、参考图和结果保持一致；edit 草稿使用基于来源图层的稳定 ID。current 中不存在对应 ID 时属于撤销完整删除，可从 target 全量恢复对象。素材库删除必须用 `isLayerLinkedToAsset` matcher 同步过滤 undo / redo 中所有包含关联图层的 entry，即使图层只存在于历史中也要过滤；普通画布删除不调用该接口。assetKind undo / redo 每次重新创建匹配恢复类型的正式 resource，并按 layer 请求版本只接受最新响应。即时生成结果在追加图层前捕获生成历史，自动适合视图不再压入另一条历史。
+- 验证：覆盖 idle 生成框移动后进入 generating 再撤销、上传图层异步回填 `resourceId` / `sourceAssetId` / `sourceResourceId` 后撤销移动仍保留当前关联值、切换到 2K 或改变比例后撤销位置仍保留当前占位尺寸、非活动生成框被激活并拖动后撤销可恢复原 active / inactive 打开状态、撤销完整删除可以全量恢复对象、即时生成后第一次撤销直接命中生成保护、阈值内指针抖动既不移动也不产生历史、素材库删除后旧 undo / redo 无法复活关联 layer、edit 草稿不会被 target-null 快照吞掉，以及 assetKind 撤销与乱序 resource 响应后刷新仍保持最终类型。
+- 关联：`src/components/image-editor/ImageCanvasHistoryModel.ts`、`src/components/image-editor/useCanvasHistory.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/components/image-editor/useImageCanvasStageInteractions.ts`、`docs/【图片画布】撤销范围与操作提示方案-2026-07-17.md`。
+
 ## 画板参考图 objectKey 必须先做归属校验
 
 - 现象：画板生成、快速编辑、图标素材或 UI 素材提取如果允许直接提交 generated objectKey，用户只要知道其他账号的私有 objectKey，就可能让 api-server 签名读取并送给外部生成供应商。
-- 原因：Data URL 参考图可以直接解析，但 objectKey 是服务端私有对象引用；只校验 generated 前缀、mime 和大小不能证明它属于当前账号。
-- 处理：所有编辑器参考图入口统一走 `parse_editor_reference_image(state, owner_user_id, source)`；objectKey 分支必须先在当前账号的项目资源、素材库资产或 `asset_object` 中匹配 owner / bucket / key，再读取 OSS。图标素材等额外参考图必须真实传到 provider，不只写 metadata；图片快速编辑当前不开放额外参考图，若后续重开入口也必须沿用同一归属校验。
+- 原因：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` 整图。图标素材等额外参考图必须真实传到 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`。
 
@@ -288,21 +319,21 @@
 - 验证：`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx --reporter verbose`。
 - 关联：`src/components/image-editor/ImageCanvasEditorModel.ts`、`src/components/image-editor/ImageCanvasPublicationMaterialsDemoPanelView.tsx`、`src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`。
 
-## 图片画布快速编辑不要直接提交普通图片 URL
+## 图片画布生成请求不要直接提交临时媒体源
 
-- 现象：图片画布快速编辑站内示例图、历史 generated 图或 OSS generated 图时，后端返回 `修改图片参考图必须是图片 Data URL。`。
-- 原因：快速编辑直接把图层 `src` 塞进 `/api/editor/images/generations` 的 `referenceImageSrcs`；默认示例图和部分持久化图层的 `src` 是 `/creation-type-references/*.webp`、`/generated-*` 或 OSS URL，而 `api-server` 的编辑参考图解析只接收 `data:image/*;base64,...`。
-- 处理：前端统一通过 `resolveEditorImageReferenceDataUrl(...)` 在提交前读取图片字节并转成图片 Data URL；Data URL 原样透传，`/generated-*` 和 generated OSS URL 先走 `/api/assets/read-url` 换签后由浏览器直读 OSS，直读失败时才 fallback 到 `/api/assets/read-bytes`，普通 public 路径直接 fetch。
-- 验证：`npm run test -- src/services/image-editor/editorImageReference.test.ts src/components/image-editor/ImageCanvasEditorView.test.tsx -t "editorImageReference|converts non-data-url quick edit source images before submitting references"`。
-- 关联：`src/services/image-editor/editorImageReference.ts`、`src/components/image-editor/ImageCanvasEditorView.tsx`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+- 现象：图片画布快速编辑、参考生成、去背景或角色动画提交 Data URL / Blob URL 时，前端或后端返回“必须先上传 OSS”。
+- 原因：Data URL / Blob URL 体积大且不能作为持久引用；如果写入外部生成队列，请求体会膨胀，worker 也无法稳定复用浏览器临时资源。
+- 处理：提交前优先复用图层已有 `objectKey`、项目资源 ID 或素材 ID；未登记的本地图片和普通 public 图片路径先通过 `resolveEditorGenerationMediaReference(...)` 读取并上传 OSS，再把稳定引用交给生成接口。Data URL 只允许用于浏览器内压缩、标注等临时处理，不能进入 API 请求、队列载荷或项目持久化。
+- 验证：`npm run test -- src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx`；`cargo test -p api-server inline_data_url --manifest-path server-rs/Cargo.toml`。
+- 关联：`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/services/image-editor/editorProjectClient.ts`、`server-rs/crates/api-server/src/editor_generation_queue.rs`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
 
-## 图片编辑器角色动画不要默认提交大图 Data URL
+## 图片编辑器角色动画必须提交稳定图片引用
 
-- 现象：图片编辑器里对角色图点击 `生成动画` 后，后端返回 `Failed to buffer the request body: length limit exceeded`，请求还没进入角色动画 handler。
-- 原因：角色动画生成请求曾把角色图片 `src` 原样作为 `sourceImageSrc` 放进 JSON；角色图如果是较大的 Data URL，会超过 Axum 默认 `2MB` body limit，在 `Json` 提取器阶段被拦截。
-- 处理：前端在角色图已持久化时优先提交 `objectKey`，只把 Data URL 作为未持久化本地临时图兜底；后端 `/api/editor/character-animations/generations` 单独配置 `12MB` body limit 兼容旧请求，但新链路不应依赖传大图 JSON。
-- 验证：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "only exposes character animation"`；`cargo test -p api-server editor_character_animation_accepts_character_image_body_above_default_limit --manifest-path server-rs/Cargo.toml`。
-- 关联：`src/components/image-editor/ImageCanvasEditorView.tsx`、`server-rs/crates/api-server/src/modules/play_flow.rs`、`server-rs/crates/api-server/src/app.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
+- 现象：图片编辑器里对尚未上传的角色图点击 `生成动画` 后，前端或后端返回 `sourceImageSrc 必须先上传 OSS`。
+- 原因：角色动画会进入外部生成队列，浏览器 Data URL / Blob URL 既不适合持久任务，也会放大 JSON 请求体。
+- 处理：前端统一通过 `resolveEditorGenerationMediaReference(...)` 取得 `objectKey` 或画板资源引用；本地临时角色图必须先上传 OSS。后端在入队前同步拒绝内联媒体，不再通过放宽 body limit 兼容 Data URL。
+- 验证：`npm run test -- src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx`；`cargo test -p api-server editor_character_animation --manifest-path server-rs/Cargo.toml`。
+- 关联：`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`server-rs/crates/api-server/src/app.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
 
 ## 图片编辑器角色动画抽帧不要采到视频尾点
 
@@ -376,11 +407,11 @@
 - 验证：`npm run test -- src/services/assetReadUrlService.test.ts --reporter verbose` 应覆盖大量不同 objectKey 同时换签时首批限量放行、后续按间隔派发；发布现场同类页面刷新时，Nginx `GET /api/assets/read-url` 429 应从 `upstream_status=-` / `genarrative_api_rps` 收敛。
 - 关联：`src/services/assetReadUrlService.ts`、`src/hooks/useResolvedAssetReadUrl.ts`、`src/components/ResolvedAssetImage.tsx`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
 
-## 图片编辑器 Seedance 2.0 参考媒体不要提交视频 Data URL
+## 图片编辑器 Seedance 2.0 参考媒体只提交稳定引用
 
 - 现象：画板生成视频选择 Seedance 2.0 并上传参考视频后，请求体暴涨、可能返回 `413` 或上游拒绝 `video_url.url`；文档示例或测试如果写 `data:video/mp4;base64,...`，后续实现很容易照抄。
-- 原因：火山 Seedance 2.0 参考视频只支持公网 URL 或 `asset://` 素材 ID，项目内画板资源应以 `objectKey` 由后端换签；视频不支持 Base64 / `data:video`，且 50MB 视频转 Base64 后会逼近或超过 64MB 请求体上限。参考音频虽然支持 Base64，但也不能单独输入，且大文件同样不应塞进 JSON。
-- 处理：参考视频 / 音频上传先走 `/api/assets/direct-upload-tickets` 直传 OSS，再 `/api/assets/objects/confirm` 确认；前端保留 signed URL 做预览，提交生成时优先使用 `objectKey`。后端归一化必须拒绝 `data:video/*`，非 Seedance 模型携带参考字段也必须拒绝；Ark body 显式带 `generate_audio:false`。
+- 原因：画板生成会进入持久队列，Base64 / Data URL / Blob URL 会放大请求和任务 JSON；直接签名客户端给出的 objectKey 又会绕过跨账号素材归属校验。项目资源 ID、素材 ID 和 objectKey 必须先解析到当前 owner 的正式对象，公网 URL 与 `asset://` 才能按供应商契约直接透传。
+- 处理：本地参考图片 / 视频 / 音频先走 `/api/assets/direct-upload-tickets` 直传 OSS，再 `/api/assets/objects/confirm` 确认；前端保留 signed URL 做预览，提交生成时使用 `objectKey`、项目资源 ID 或素材 ID。后端归一化拒绝全部 `data:*` / `blob:*`，签名 OSS URL 前统一校验 owner；稳定引用字段总长度限制为 `256KB`，非 Seedance 模型携带参考字段也必须拒绝；Ark body 显式带 `generate_audio:false`。
 - 验证：`npx vitest run src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/services/image-editor/editorReferenceUploadClient.test.ts --reporter verbose`；`cargo test -p api-server editor_video --manifest-path server-rs/Cargo.toml`；`cargo test -p shared-contracts editor_video_request_supports_seedance_multimodal_references --manifest-path server-rs/Cargo.toml`。
 - 关联：`src/services/image-editor/editorReferenceUploadClient.ts`、`src/components/image-editor/useImageCanvasUploadWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。
 
@@ -428,9 +459,9 @@
 
 - 现象：用户点击图片素材的“快速编辑”后，画布上额外出现 `Quick Edit Generator` 占位，像是新建了一个生成器；但用户预期是在原图下方框选区域、填写一个提示词和模型，然后直接修改当前图。
 - 原因：快速编辑入口和提交链路误用了 `createQuickEditGenerationDialogDraft(...)` / `CanvasGenerationDialogState`，把“覆盖源图”的快速编辑伪装成会产出新图层的生成器占位。
-- 处理：图片快速编辑必须走 `QuickEditPanelState`，打开时归档当前 active generation dialog 但不创建新的 `mode="quick-edit"` dialog；提交时调用 `/api/editor/images/edits`，把当前图片或带编号标注的图片作为 `sourceImageSrc`，成功后覆盖源图，失败时保留快速编辑面板。图片重绘、去背景、视频快速编辑等会产出新图层或异步占位的入口仍可走 generation dialog / placement 链路。
-- 验证：`npm run test -- src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx -- --runInBand`，以及按需运行 `npm run test -- src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx -t "快速编辑|quick edit" -- --runInBand`。
-- 关联：`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/services/image-editor/editorImageReference.ts`。
+- 处理：图片快速编辑必须走 `QuickEditPanelState`，打开时归档当前 active generation dialog 但不创建新的 `mode="quick-edit"` dialog；提交时调用 `/api/editor/images/edits`，把当前图片或带编号标注的图片作为 `sourceImageSrc`，成功后覆盖源图，失败时保留快速编辑面板。快速编辑任务进入 `generating` 后必须移除框选工具和覆盖层，禁止继续新增框选；失败恢复面板后可继续调整框选再重试。图片重绘、去背景、视频快速编辑等会产出新图层或异步占位的入口仍可走 generation dialog / placement 链路。
+- 验证：`npm run test -- src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx -- --runInBand`，以及按需运行 `npm run test -- src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx -t "快速编辑|quick edit" -- --runInBand`。
+- 关联：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/services/image-editor/editorImageReference.ts`。
 
 ## 图片画布快速编辑完成必须按目标图层回写
 
@@ -448,6 +479,22 @@
 - 验证：`npm run test -- src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx` 覆盖来源参数继承、模型参数切换、目标尺寸提交和图层回填；`cargo test -p api-server editor_image_edit --manifest-path server-rs/Cargo.toml` 覆盖图标类拒绝、provider 尺寸对齐和回图恢复。
 - 关联：`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationLayerModel.ts`、`server-rs/crates/api-server/src/editor_project.rs`。
 
+## 图片画布生成中占位必须同步业务目标尺寸
+
+- 现象：用户选择 `2K` 生成或从 2K 普通图、角色图再次改造时，最终成品仍是 2K，但待生成 / 生成中的灰色框保持 1K 大小，完成后突然放大；UI 素材提取也可能始终显示 512 方框。
+- 原因：同来源改造先按默认 1K 创建 draft，再只恢复 `imageModel / aspectRatio / imageSize`，没有重新计算 placeholder；UI 提取和旧修改入口则分别写死图标展示尺寸与 `1024x1024`。
+- 处理：所有共享图片参数恢复和面板比例 / 清晰度切换都经过 `resizeGenerationPlaceholderToImageSelection(...)`，保持占位中心不变并同步 `width/height/originalWidth/originalHeight`；UI 提取按 `resolveUiAssetExtractionGenerationPlan(...)` 的 1K / 2K 计划计算占位，旧修改入口使用源图真实 Resolution。快速编辑覆盖源图，不另建生成占位，仍按目标尺寸更新原图层。
+- 验证：`npm run test -- src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/ImageCanvasGenerationImageOptionsView.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx --reporter=dot`。
+- 关联：`src/components/image-editor/ImageCanvasGenerationModel.ts`、`src/components/image-editor/ImageCanvasGenerationDialogModel.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 图片画布快速编辑模型必须在后端选择正确的 provider 协议
+
+- 现象：快速编辑继承或选择 `nanobanana2` 后，上游返回 `not supported model for image generation`；图集开放快速编辑后尤其容易触发。
+- 原因：前端把 `gemini-3.1-flash-image-preview` 正常提交到 `/api/editor/images/edits`，但后端无条件使用只支持 `gpt-image-2` 的 VectorEngine `/v1/images/edits` multipart 协议。
+- 处理：快速编辑请求同时提交 `model / aspectRatio / imageSize`。api-server 归一模型后分流：`nanobanana2` 使用 `/v1beta/models/{model}:generateContent`，把原图和参考图放入 `inline_data`，并传递 `generationConfig.imageConfig`；`gpt-image-2` 继续使用 `/v1/images/edits` multipart 和 16 像素 provider 边界对齐。nanobanana2 保留 provider 输出几何尺寸，不套用 GPT edits 的像素恢复。
+- 验证：`npm run test -- src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx` 覆盖前端参数提交；`cargo test -p api-server editor_image_edit --manifest-path server-rs/Cargo.toml` 覆盖模型分流、尺寸档位计费与 GPT 对齐恢复。
+- 关联：`src/services/image-editor/editorProjectClient.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`。
+
 ## 图片画布纯尺寸变换必须先在内存决策再单次上传
 
 - 现象：`nanobanana2` 已返回并成功解码图片，任务随后报“尺寸无效”；普通生图若把尺寸恢复作为硬失败，provider 已成功回图后仍可能没有素材进入素材库和画布。
@@ -1666,6 +1713,14 @@
 - 验证：`npm run dev -- --watch` 下修改 `apps/admin-web/src/**` 应由 Vite HMR 处理，不应出现连续 `[dev] 重启 admin-web`；`scripts/dev.test.ts` 覆盖 web/admin-web 不注册外层 watch。
 - 关联：`scripts/dev.mjs`、`docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`。
 
+## 根目录 `nohup.out` 持续写入会触发主站 Vite 刷新循环
+
+- 现象：在仓库根目录用 `nohup npm run dev ... &` 启动完整 dev 栈后，即使没有修改前端源码，主站页面也会反复整页刷新；`nohup.out` 同时持续增长。
+- 原因：未显式重定向 stdout / stderr 时，`nohup.out` 会收集 SpacetimeDB、api-server 和两套 Vite 的整套 dev 栈输出。主站 Vite 的 root 是仓库根目录，若 watcher 未忽略这个持续写入的文件，每次追加日志都会被当成文件变化；后台 Vite root 是 `apps/admin-web`，仓库根日志不在其监听根内。
+- 处理：主站 `vite.config.ts` 的 `server.watch.ignored` 保持忽略 `**/nohup.out`，Git 同时忽略 `nohup.out`。修改配置后重启主站 Vite。若显式重定向到其它仓库内日志文件，该文件不会自动受保护，应写到 Vite root 之外或补充精确忽略规则。
+- 验证：在仓库根目录追加 `nohup.out` 时主站不再刷新，真实源码修改仍正常触发 HMR；`git check-ignore nohup.out` 能命中忽略规则，`git status` 不出现该日志。
+- 关联：`vite.config.ts`、`.gitignore`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 本地 SpacetimeDB publish 401 可清本地库重发
 
 - 现象：本地 `spacetime publish` 显示 `401` 无权限，或重新发布仍像是在更新旧库。
@@ -3389,3 +3444,26 @@
 - 验证：新命令为 `npm run ai-game-creator-shell:agent-runtime:supervisor-swarm-final-reply-transient-retry-real-e2e -- --config-dir <发布AppData绝对路径>`；旧 `supervisor-swarm-transient-retry` 只保留首次 tool-plan 证明。fault proxy `14/14`、E2E self-test **PASS**、前端 `308/308` 及 shell typecheck、`platform-llm 41/41`、`platform-agent 17/17`、`shared-contracts 7/7` 等确定性门禁已完成。真实外部 Provider suite 共执行六轮，前五轮均为 **FAIL** 且不得拼接：第一、二轮沿用既有失败记录，第三轮为终态后过早观察到 `1` 个 finalization journal，第四轮为 quality-review 普通 tool-plan 连续 transport/connectivity 失败耗尽重试且未进入目标故障，第五轮为上述写锁竞争与绝对锁路径问题；修复后第六轮在同一轮内完整 **PASS**。
 - 第六轮证据：`gpt-5.5 / openai_chat`，`2` 条初始加 `1` 条 repair delivery、`3` 条专业 Agent assistant，Project Supervisor base final-reply 目标与可信宿主 verify marker 门禁均成立；受控 Provider `failed=1 / retry=1`、incidental `failure=0 / retry=0`，`30s` backoff，pidfd `claim=2 / signal=2`，Runner `resumed=true / identityStable=true`。父 tool-plan 故障前后均为 `13`，parent final-reply 与最终 assistant 唯一，response stream `sequence=2 / committed`；pending、retry、handoff、finalization、confirmation sidecar、全部重复计数及 API Key、私有正文、项目路径、正式配置路径和公共报告泄漏扫描命中均为 `0`。V1.41 handoff 原子提交前的 unknown-result 和 tool-plan handoff 未覆盖边界继续保留。
 - 关联：`apps/ai-game-creator-shell/scripts/llm-transient-fault-proxy.mjs`、`apps/ai-game-creator-shell/scripts/agent-runtime-real-e2e.mjs`、`apps/ai-game-creator-shell/tests/llmTransientFaultProxy.test.ts`、`docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`。
+## SpacetimeDB 历史归档不能按文件名小于 snapshot 就全部删除
+
+- 现象：看到最新 `N.snapshot_dir` 后，把所有起始 offset 小于 `N` 的 `.stdb.log` 删除，或者只把旧日志上传 OSS 就宣称已有完整增量灾备。
+- 原因：segment 文件名只表示该段最早事务；起始 offset 小于等于最新 snapshot 的最后一个 segment 可能跨越 snapshot 边界，重启仍需要它。历史归档也不会及时覆盖 control-db、program bytes、最新 snapshot 和 active segment。
+- 处理：latest snapshot 必须是未锁定且存在同 offset `.snapshot_bsatn` 的完整目录，空目录或同名 `.lock` 存在时忽略。每个 replica 独立保留 `max(segment_start <= latest_snapshot)` 及全部后缀，只处理更早 segment 对；旧 snapshot 只保留最新一个。`--storage-format files` 必须先发布完整 full catalog；history 对每个候选文件 CAS 对象、history catalog 和 full catalog 执行 HEAD 长度/SHA 验真，再复算边界与 stat fingerprint，最后发布并验真固定 `latest.json`；pointer 失败时不得推进 state 或删除源文件。不要把在线逐文件 full 扫描当成跨文件一致备份，基线必须来自停库目录或已验证冻结副本。SSH 或工具超时后先检查 work-dir PID lock 与原进程，不要直接并发重跑；不要在 history 模式传 `--stop-service`。定时任务通过 Server-Provision 的显式 profile 和仓库 drop-in 管理，启用前 dry-run 验证 baseline，切回 archive 时同时移除托管与现场遗留 drop-in；不要在 `/etc/systemd/system` 长期保留手写覆盖，release 必须建立和验证自己的 full baseline 与 work-dir，不能直接复用 dev 的本地 state。
+- 验证：dry-run 输出 replica 的 `latestSnapshot`、`boundarySegment` 和候选清单；从另一台机器仅凭 OSS `latest.json` 自动定位 full catalog，创建目录、下载文件并逐项校验长度/SHA，启动隔离 data-dir 验证 `/v1/ping`、snapshot restore、commitlog replay、module launch、代表性 SQL 与 reducer。
+- 关联：`scripts/database-backup-to-oss.mjs`、`scripts/check-database-backup-to-oss.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## Procedure 事务鉴权要兼容 SpacetimeDB 2.6.0 的匿名 TxContext
+
+- 现象：api-server 的 SpacetimeDB token identity 与 `editor_generation_pricing_config.writer_identity` 完全一致，服务启动门禁也通过，但手动拆分图集调用 `find_editor_asset_group_source_and_return` 仍返回“当前 identity 无权调用模型生成运行时服务”。
+- 原因：SpacetimeDB 2.6.0 的 `ProcedureContext::try_with_tx` 使用内部匿名事务上下文，闭包参数 `TxContext` 解引用得到的 `ReducerContext::sender()` 固定为 `Identity::ZERO`，不是 procedure 外层调用者。把 runtime writer 鉴权写成 `require_*(tx, tx.sender())` 会稳定误拒绝合法服务 identity。SpacetimeDB 2.6.1 已修复为向事务透传 procedure caller，但尚未升级的 dev / release 模块仍受 2.6.0 行为影响。
+- 处理：在调用 `try_with_tx` 前通过 `let caller = ctx.sender()` 捕获真实调用者，再把 `caller` 显式传入事务函数；迁移、后台账号、runtime profile、外部生成等现有 procedure 已采用这一模式。`npm run check:spacetime-runtime-access` 禁止编辑器 runtime writer 鉴权重新直接读取事务 `ctx.sender()`。运行环境升级到 2.6.1 后继续保留显式 caller，避免鉴权依赖 SDK 版本细节。
+- 验证：运行 `npm run check:spacetime-runtime-access`、`cargo test -p spacetime-module --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`；发布使用 SpacetimeDB 2.6.1 构建的新模块后，以 runtime writer identity 重试 `POST /api/editor/icon-spritesheets/slices`，确认来源查询、分片素材写入与 cohort 完成不再返回 identity 403。
+- 关联：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`scripts/check-spacetime-runtime-access.mjs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## Portal 弹窗必须在遮罩根节点携带平台主题
+
+- 现象：项目库点击“重命名”后，标题、输入框和按钮仍显示，但弹窗面板及遮罩背景变透明，看起来像“改名界面的背景没了”。
+- 原因：`UnifiedModal` 默认 portal 到 `document.body`；若业务入口只在页面内层继承 `platform-theme`，portal 根节点不会继承该容器的 CSS 变量。此时 `.platform-modal-shell` 的 `background: var(--platform-modal-fill)` 和 `.platform-overlay` 的背景声明都会失效。
+- 处理：平台白底工具弹窗优先复用 `PlatformToolModalShell`，由共享壳读取当前 `AuthUiContext.platformTheme`，并把 `platform-theme platform-theme--<light|dark>` 挂到 portal overlay；不要用硬编码白底掩盖主题变量缺失。必须直接使用 `UnifiedModal` 的特殊场景，也要在 `overlayClassName` 显式传递当前平台主题。
+- 验证：在 light / dark 主题下打开 portal 弹窗，断言 dialog 的 overlay 携带对应主题类，并在真实浏览器核对 panel 与遮罩的 computed background 均非透明。
+- 关联：`src/components/project/ProjectGalleryView.tsx`、`src/components/common/PlatformToolModalShell.tsx`、`src/components/common/UnifiedModal.tsx`。

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

@@ -1,6 +1,6 @@
 # Genarrative 项目共享概览
 
-更新时间：`2026-06-23`
+更新时间：`2026-07-17`
 
 ## 一句话定位
 
@@ -36,7 +36,7 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 A
 server-rs + Axum + SpacetimeDB
 ```
 
-当前 SpacetimeDB crate、SDK、CLI / standalone、生成 bindings 和容器压测镜像统一按 `2.6.0` 对齐；遇到版本不匹配时先升级到 `server-rs/Cargo.toml` 锁定版本，升级后重启对应 SpacetimeDB 进程再重试。
+当前 SpacetimeDB crate、SDK、CLI / standalone、生成 bindings 和容器压测镜像统一按 `2.6.1` 对齐；遇到版本不匹配时先升级到 `server-rs/Cargo.toml` 锁定版本，升级后重启对应 SpacetimeDB 进程再重试。
 
 职责边界：