合并 master 更新到 AI 游戏创作分支

合入 master 的画布 Agent、精选素材审核、外部编辑器 API 与认证投影更新
保留当前分支的 AI 游戏创作壳、配置项和 LLM 运行接口改造
解决图片编辑器、LLM、去背景完成、外部生成排序和文档冲突
沿用 master 的 SpacetimeDB auth_store_projection 迁移与生成绑定

docs/README.md

@@ -9,6 +9,7 @@
 - [审计与复盘](./audits/README.md)：工程审查、文本/乱码审计、专项落地审计。
 - [系统设计](./design/README.md)：玩法、关系、物品与对话设计。
 - [技术方案](./technical/README.md)：动画、服务端、外部产品形态拆解。
+- [架构决策](./adr/)：记录已经接受的跨模块、长期有效架构取舍；对应长期摘要仍应同步到 `docs/project-memory/shared-memory/decision-log.md`。
 - [规划与优先级](./planning/README.md)：当前阶段的迭代排序与落地优先级；创作流程统一总计划见 [【玩法创作】创作流程统一总计划-2026-05-30.md](./planning/%E3%80%90%E7%8E%A9%E6%B3%95%E5%88%9B%E4%BD%9C%E3%80%91%E5%88%9B%E4%BD%9C%E6%B5%81%E7%A8%8B%E7%BB%9F%E4%B8%80%E6%80%BB%E8%AE%A1%E5%88%92-2026-05-30.md)。
 - [参考目录](./reference/README.md)：脚本/Function 速查入口。
   重点补充：RPG 创作与运行时脚本职责地图见 [RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md](./reference/RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md)。
@@ -32,6 +33,8 @@ Expo React Native 移动壳和 Tauri 桌面壳的工程结构、同源 WebView
 
 `/editor/canvas` 图片画布编辑器的画布素材 ZIP 导出能力，入口放在右上角标题栏下载图标内，采用前端 JSZip 打包画布中有效图层引用的上传图、生成图、修改结果和角色动作序列帧；动作图层右键“导出为”提供序列帧 ZIP（含前端生成的 `preview.gif`）与 Spine JSON ZIP 两个二级选项，方案见 [【前端架构】图片画布素材导出方案-2026-06-15.md](./technical/【前端架构】图片画布素材导出方案-2026-06-15.md)。
 
+`/editor/canvas` 右侧画布 Agent 对话面板、会话持久化、SSE 事件、附件与生成落画板例外见 [【编辑器】画布Agent对话面板-2026-07-03.md](./【编辑器】画布Agent对话面板-2026-07-03.md)；消息正文存 OSS、元数据进 SpacetimeDB 的取舍见 [【ADR】画布Agent会话消息存OSS-2026-07-03.md](./adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md)。
+
 图片画布生成类面板的模型泥点默认 JSON、运行时 override、后台“模型定价”页面和主站动态下发口径见 [【编辑器】模型定价配置管理方案-2026-06-22.md](./%E3%80%90%E7%BC%96%E8%BE%91%E5%99%A8%E3%80%91%E6%A8%A1%E5%9E%8B%E5%AE%9A%E4%BB%B7%E9%85%8D%E7%BD%AE%E7%AE%A1%E7%90%86%E6%96%B9%E6%A1%88-2026-06-22.md)。
 
 React 组件测试的用户行为、稳定契约、hook / model 分层断言口径，以及避免内部 DOM 探针、图标 class 和完整对象快照式断言的规则见 [【前端测试】React组件测试准则-2026-06-26.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%B5%8B%E8%AF%95%E3%80%91React%E7%BB%84%E4%BB%B6%E6%B5%8B%E8%AF%95%E5%87%86%E5%88%99-2026-06-26.md)。

docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md

@@ -0,0 +1,35 @@
+# 【ADR】画布Agent会话消息存OSS-2026-07-03
+
+状态：已接受
+
+## 背景
+
+画布Agent对话需要保存历史记录并支持新开会话。消息正文是流式追加、体量随对话增长的 JSON 数据；SpacetimeDB 是后端唯一结构化真相存储，但表行不适合承载不断增长的长文本；画布工程快照已有独立保存链路，且对话流式更新频率远高于布局保存。
+
+## 决策
+
+- SpacetimeDB 表 `editor_agent_conversation` 只存会话元数据：会话 ID、projectId、ownerUserId、标题、软删标记、聊天记录 OSS 对象引用、时间戳。
+- 完整消息内容以会话粒度 JSON 对象存 OSS（`editor-agent/{conversationId}.json`），追加消息即整体重写对象。
+- `editor-agent/` 是服务端内部消息文档前缀，只保存 `editor-agent/{conversationId}.json` 形态的会话级 JSON 文档；它不是浏览器直传前缀，也不是公开 generated 资源前缀。
+- 浏览器禁止直接上传、覆盖或签名写入 `editor-agent/` 对象；前端只通过 `api-server` 的会话接口创建会话、发送消息、读取历史，OSS 读写由服务端完成。
+- 消息文档序列化后的读写上限为 2 MiB；超过上限时后端拒绝继续读写该会话消息文档，并返回 payload too large 语义错误。
+- 同一会话内的消息追加采用 `conversationId` 级串行锁，避免同一会话的“读-改-写”整对象过程互相覆盖。
+- Agent 工具调用失败时，仍保留 assistant 消息和 `failed` generation record，包括 tool call、模型、错误信息等排障字段；失败记录是会话历史的一部分，不因 SSE 已返回错误而丢弃。
+- 不把消息明细写入 SpacetimeDB 表，不把对话混入画布工程快照，不在 api-server 内存中保存会话真相。
+
+## 备选方案与取舍
+
+1. **独立 message 表（逐条入 SpacetimeDB）**：查询灵活，但消息文本长、附件结构嵌套，行数与行体积随聊天无界增长，挤占 SpacetimeDB 订阅与快照成本；对话消息没有跨会话结构化查询需求，放表里收益低。
+2. **消息塞进画布工程快照 payload**：省一张表，但每条消息都会触发整个工程快照保存，与画布布局保存互相竞争，流式期间冲突概率高。
+3. **每条消息一个 OSS 对象**：追加成本最低，但加载历史需要 N 次取对象或额外清单维护；对话消息量级小，整体读写实现最简单。
+
+选择"表存引用 + OSS 存整段 JSON"：与仓库既有「画布资源」「敲击音效」等 OSS 对象引用模式一致，加载历史一次取对象即可。
+
+## 影响
+
+- 消息写入是"读-改-写"整对象；当前由 `api-server` 按 `conversationId` 做会话内串行化，保证同一进程内同一会话不会并发覆写。若未来横向多实例部署，需要补充分布式锁、对象版本条件写或等价的跨实例并发控制。
+- 会话表仍只保存元数据和 `messagesObjectKey`；API 可以在读取时把 OSS 消息文档拼装为会话详情返回，但完整消息正文的持久化真相仍是 OSS JSON 文档。
+- 消息文档最大 2 MiB；该限制用于阻止单个会话无限增长。后续如果需要更长历史，应引入归档、分页对象或摘要压缩，不应把正文回填进 SpacetimeDB 表。
+- 会话软删只打表标记，OSS 对象保留，便于恢复与审计。
+- 工具生成失败也会写入消息文档：assistant 消息可标记为失败 / 错误类型，`generations` 中保留 `failed` record、模型和错误信息，便于用户回看失败原因和后续排障。
+- 若未来出现跨会话消息检索需求，需另建投影或索引，不回退为消息入表。

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

@@ -44,6 +44,53 @@
 - 影响范围：AI 游戏创作 App 的 Tauri Rust 配置加载、主窗口配置面板、CLI wrapper、agent-run smoke、`check-config` 门禁、`.gitignore` 和实施计划文档。
 - 验证方式：运行 `npm run ai-game-creator-shell:typecheck`、`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+## 2026-07-03 作品公开默认关闭
+
+- 背景：作品发布完成不应默认进入公开广场 / 公开详情 / 公开互动消费路径，需要先由后台可见性开关明确开启。
+- 决策：各玩法源表的 `visible` 新作品默认值改为 `false`；从草稿首次发布时仍保持 `false`，只有已发布作品再次发布 / 更新时才保留既有 `visible`。公开列表、详情、点赞、Remix 和正式公开 runtime 继续按 `Published + visible=true` 判断。旧迁移数据缺少 `visible` 时仍补 `true`，避免历史已公开作品被批量隐藏。
+- 影响范围：`spacetime-module` 各玩法作品表、发布 / 编译 / Remix 写入路径、统一公开作品 read model、后台作品可见性管理。
+- 验证方式：运行 `cargo fmt --manifest-path server-rs/Cargo.toml --all`、`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md`。
+
+## 2026-07-04 陶泥儿精选改为素材提交审核后公开
+
+- 背景：`/creation` 的 `陶泥儿精选` 过去依赖 `editor_project_resource.public_showcase_enabled`，生成画布资源默认可公开，和“作品公开默认关闭、由用户主动投稿精选”的运营要求冲突，也无法在后台审核、返还泥点和配置固定活动卡。
+- 决策：`陶泥儿精选` 的公开事实改为独立 `editor_showcase_asset` 审核表。生成素材默认不公开；用户在账号级素材库对 `sourceType="generated"` 且有媒体内容的素材提交审核，后端快照素材信息并写入 `pending`。后台审核通过后写入 `approved`，但默认 `display_enabled=false` 且 `showcase_category=null`，运营需按前台 Tab 手动设置分类并开启展示；审核通过时按 `generation_cost_mud_points` 返还 50% 泥点；拒绝后写入 `rejected`。公开接口 `GET /api/editor/showcase/resources` 只返回已通过、展示开启且分类合法的快照，按通过时间和 `showcaseId` 倒序分页，并可携带后台配置的固定活动卡。旧 `editor_project_resource.public_showcase_enabled` 和旧 PATCH 接口只保留兼容，不再驱动精选公开。
+- 影响范围：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`spacetime-client` 绑定与 mapper、`api-server` 编辑器和后台路由、admin-web 精选审核页、素材库右键菜单、`/creation` 精选瀑布流、图片画布文档和后端表目录。
+- 验证方式：运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo check --manifest-path server-rs/Cargo.toml -p spacetime-module -p spacetime-client -p api-server`、前端 / 后台 typecheck 与精选相关组件测试，确认默认不公开、提交后 pending、审核通过后展示和返还、展示开关与点赞生效。
+- 关联文档：`docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-07-03 外部编辑器 API 生成默认写入画布与素材库
+
+- 背景：外部 API 面向美术 Agent 使用时，需要从自然语言自动选路，并保证生成结果不会只停留在接口回包里；同时后续素材生成需要复用已抽象出的美术规范，避免每次重新追问风格要求。
+- 决策：外部编辑器 API skill 在新对话首个生成前先确认画布名称，并创建 / 复用同名画布项目和素材库文件夹。所有外部生成请求默认携带 `projectId`、`assetFolderId`、素材展示名和 `canvasCompletion`，使结果进入画布和素材库；角色动画端点当前不直接返回 `asset`，由 helper 在动画成功后用首帧补建素材库记录。skill 先把用户需求抽象为可复用美术规范，缺少目标素材必需信息时再追问；已有规范且用户未提出新规范时自动复用。
+- 影响范围：`.codex/skills/genarrative-external-editor-api`、外部 OpenAPI 使用说明、外部画布生成集成方。
+- 验证方式：运行 skill 校验、helper 自测、Python 编译检查、编码检查和 `git diff --check`；真实线上生成 smoke 需要本机 `~/.config/genarrative/external-editor-api.json` 中有有效 API Key。
+- 关联文档：`docs/openapi/genarrative-external-v1.openapi.json`、`.codex/skills/genarrative-external-editor-api/SKILL.md`。
+
+## 2026-07-03 新建项目与 AI 任务 ID 使用短前缀
+
+- 背景：新建外部画布项目和 AI 任务 ID 需要统一以 `proj`、`task` 开头，同时保留旧 ID 兼容读取和路由。
+- 决策：新建 editor project ID 前缀改为 `proj-`，新建 AI task / 生成任务 / 草稿任务 ID 前缀改为 `task-`。路由和读写仍按字符串处理，不新增拒绝 `editor-project-*`、`aitask_*` 或 `extgen-*` 的校验，历史数据继续兼容。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/module-ai/src/domain/ids.rs`、`server-rs/crates/api-server/src/editor_generation_queue.rs`、玩法外部生成入队路径、外部编辑器 API 新建项目返回值、AI 任务创建链路。
+- 验证方式：运行 `cargo test -p module-ai --manifest-path server-rs/Cargo.toml`、定向 api-server editor project 测试、编码检查和 `git diff --check`。
+- 关联文档：`docs/openapi/genarrative-external-v1.openapi.json`。
+
+## 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 面板、`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`。
+- 关联文档：`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 同步正式表
+
+- 背景：同手机号重复账号、兑换码白名单错配和微信资料不回写暴露出 `module-auth` 内存工作集、`auth_store_snapshot` 和正式认证表之间仍有历史互刷路径；旧 JSON 快照会把过期手机号索引或用户资料重新带回运行态。
+- 决策：删除 `auth_store_snapshot` 表和旧 `import_auth_store_snapshot_json` / `export_auth_store_snapshot_from_tables` procedure；`module-auth` 只保留内存工作集和 typed `AuthStoreProjectionView` 导入 / 导出。运行中认证写操作通过 `sync_auth_store_projection` 同步 `user_account` / `auth_identity` / `refresh_session`，启动恢复通过 `export_auth_store_projection_from_tables` 从正式表恢复内存。账号资料真相只在 `user_account`，`auth_identity` 只保存登录入口身份键。
+- 影响范围：`module-auth` projection API、`spacetime-module` auth schema/procedure、`spacetime-client` bindings/facade、`api-server` 启动恢复和认证同步、后端架构文档与认证排障记忆。
+- 验证方式：`npm run spacetime:generate`、`SPACETIME_SCHEMA_GUARD_ALLOW_BREAKING=1 npm run check:spacetime-schema`、`cargo test -p module-auth --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo check -p spacetime-client --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`。
 
 ## 2026-06-29 图片画布手动抠图走远端 BiRefNet BFF
 
@@ -132,7 +179,7 @@
 ## 2026-06-22 创作主页精选展示全站公开画布生成资源
 
 - 背景：`/creation` 的 `陶泥儿精选` 曾从账号级素材库读取，并在素材为空时用公开作品图片补充，导致新创作页出现不属于任何当前图片画布项目的素材。
-- 决策：`陶泥儿精选` 从全站 `editor_project_resource` 构建素材包和素材，读取路径固定为 `GET /api/editor/showcase/resources`；只保留 `sourceType="generated"`、图片源非空且 `public_showcase_enabled = true` 的画布生成资源，按创建时间倒序展示。账号级 `editor_asset`、上传素材、公开作品图片和 `mock_generated` 都不作为精选来源。任意画布左侧素材列表中，单素材右键菜单承接文字 `删除` 和 `公开展示该素材` 勾选项；勾选项默认打开，修改时写回对应 `editor_project_resource.public_showcase_enabled`。
+- 决策：该历史决策已被 2026-07-04 的“素材提交审核后公开”取代。历史背景仍有效：公开作品图片和假数据不应回填精选；但精选事实源不再是 `editor_project_resource.public_showcase_enabled`，而是 `editor_showcase_asset` 审核快照。
 - 影响范围：`/creation` 创作主页、`creationShowcaseModel`、公开精选 BFF、图片画布素材列表右键菜单、账号素材库快照、创作主页改版计划和精选素材相关测试。
 - 验证方式：运行 `src/components/creation-home/creationShowcaseModel.test.ts`、`CreationLandingView.test.tsx`、`ImageCanvasAssetRowView.test.tsx`、`useImageCanvasAssetLibrary.test.tsx` 与 `src/services/image-editor/editorProjectClient.test.ts`，确认公开生成资源展示、上传素材过滤、公开开关隐藏资源、删除入口在右键菜单中、公开作品不再 fallback。
 - 关联文档：`docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
@@ -1963,6 +2010,13 @@
 - 影响范围：`spacetime-module` auth procedures、`spacetime-client` auth facade、`api-server` 启动恢复、后端架构文档、开发运维文档、认证排障记忆。
 - 验证方式：`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server spacetime_unavailable_router_returns_service_unavailable_for_requests --manifest-path server-rs/Cargo.toml -- --nocapture`、`npm run check:encoding`。
 
+## 2026-06-30 auth_store_snapshot 只做一次性迁移并切断运行中回灌
+
+- 背景：同手机号重复账号暴露出认证工作集、正式认证表和旧 `auth_store_snapshot` 之间仍有互刷路径；运行中 Bearer / refresh session 未命中后再导出整包状态刷新内存，会把旧手机号索引或旧会话重新带回进程。
+- 决策：`auth_store_snapshot` 不再保留行级备查；正式认证表为空时才从最新旧快照转移一次到 `user_account` / `auth_identity` / `refresh_session`，随后清空旧表。`api-server` 运行中不再因 Bearer 用户、token version、session 或 refresh token 未命中而从 SpacetimeDB 导出整包状态刷新 `InMemoryAuthStore`；启动恢复暂保留从正式表构建工作集，直到认证仓储改为直接读写正式表。
+- 影响范围：`server-rs/crates/spacetime-module/src/auth/procedures.rs`、`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/api-server/src/auth.rs`、`server-rs/crates/api-server/src/refresh_session.rs`、认证排障记忆与后端架构文档。
+- 验证方式：`cargo test -p spacetime-module auth_export -- --nocapture`、`cargo test -p module-auth phone_only_exists -- --nocapture`、`cargo test -p module-auth bind_wechat_phone_merges -- --nocapture`、`npm run check:encoding`、`git diff --check`。
+
 ## 2026-05-13 微信小程序支付以后端通知为唯一入账事实
 
 - 背景：“我的”账户充值需要接入微信小程序支付，同时保留本地 / H5 mock 支付联调能力。
@@ -2143,7 +2197,7 @@
 ## 2026-05-09 GPT-image-2 图片生成统一迁移到 VectorEngine
 
 - 背景：仓库内 RPG、拼图、方洞和本地模板脚本的 GPT-image-2 生图此前依赖 APIMart 图片网关；团队要求参考 VectorEngine Apifox `api-448710071`，后续不再使用 APIMart 执行 GPT-image-2 图片生成。
-- 决策：所有 GPT-image-2 无参考图生图请求统一走 VectorEngine `POST /v1/images/generations`，有参考图请求走 `POST /v1/images/edits` multipart，基础配置读取 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` / `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`，上游模型使用 `gpt-image-2`，请求体不再携带 `official_fallback`。APIMart 只保留给创意 Agent 的 `gpt-5` Responses 文本/多模态链路。
+- 决策：所有 GPT-image-2 无参考图生图请求统一走 VectorEngine `POST /v1/images/generations`，有参考图请求走 `POST /v1/images/edits` multipart，基础配置读取 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` / `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`，上游模型使用 `gpt-image-2`，请求体不再携带 `official_fallback`。当时 APIMart 仍保留给创意 Agent 的 `gpt-5` Responses 文本/多模态链路；该文本链路已被 2026-07-05 VectorEngine Chat Completions `gpt-5.4-mini` 决策覆盖。
 - 影响范围：`api-server` 共享图片 helper、拼图图片生成、角色主图、RPG 场景图、开局 CG 故事板、方洞视觉资产、生产环境示例、gpt-image-2 本地 skill 和相关技术文档。
 - 验证方式：执行 `npm run check:encoding`、`cargo test -p api-server openai_image --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server puzzle --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server custom_world_ai --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server character_visual --manifest-path server-rs/Cargo.toml`，并用 `npm run dev:api-server` + `/healthz` 做后端 smoke。
 - 关联文档：`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`、`docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md`。
@@ -2166,7 +2220,7 @@
 
 ## 2026-05-08 APIMart 接口统一携带 `official_fallback`
 
-> 2026-05-09 追认：本决策中的图片生成部分已被“GPT-image-2 图片生成统一迁移到 VectorEngine”覆盖；当前只保留 APIMart `gpt-5` Responses 文本/多模态链路继续显式携带 `official_fallback`。
+> 2026-05-09 追认：本决策中的图片生成部分已被“GPT-image-2 图片生成统一迁移到 VectorEngine”覆盖；2026-07-05 后 APIMart `gpt-5` Responses 文本/多模态链路也被 VectorEngine Chat Completions `gpt-5.4-mini` 覆盖，不再携带 `official_fallback`。
 
 - 背景：APIMart 的图片生成和 Responses 接口在仓库内分散于 `api-server`、`platform-llm` 和本地 skill 脚本，若只修单点，容易出现不同入口的上游请求体不一致。
 - 决策：凡是仓库内调用 APIMart 的 OpenAI 兼容接口，请求体统一携带 `official_fallback: true`；其中图片生成请求直接固定写入，`platform-llm` 的 APIMart GPT-5 client 通过显式开关开启，不默认扩散到 Ark 等其它 provider。
@@ -2321,7 +2375,7 @@
 ## 2026-05-05 creative-agent Task E API / SSE facade 已落地
 
 - 背景：Phase 1 需要先把创意 Agent 的 HTTP/SSE 门面接入 Rust `api-server`，用于前端工作区调用和拼图模板确认闭环。
-- 决策：`api-server` 挂载 `/api/runtime/creative-agent/*` 六个鉴权路由；creative session 在 Task D 表未收口前暂存在 `api-server` 运行态并按 authenticated user 校验 owner；未确认模板前不创建拼图 session，`confirm-template` 后才通过既有 `spacetime-client` 创建/编译 `puzzle_agent_session`；`gpt-5` 请求只从 `APIMART_BASE_URL` / `APIMART_API_KEY` 构造专用 Responses client，不复用通用 `GENARRATIVE_LLM_API_KEY`。
+- 决策：`api-server` 挂载 `/api/runtime/creative-agent/*` 六个鉴权路由；creative session 在 Task D 表未收口前暂存在 `api-server` 运行态并按 authenticated user 校验 owner；未确认模板前不创建拼图 session，`confirm-template` 后才通过既有 `spacetime-client` 创建/编译 `puzzle_agent_session`；当时 `gpt-5` 请求只从 `APIMART_BASE_URL` / `APIMART_API_KEY` 构造专用 Responses client，不复用通用 `GENARRATIVE_LLM_API_KEY`。该 LLM 来源已被 2026-07-05 VectorEngine Chat Completions `gpt-5.4-mini` 决策覆盖。
 - 影响范围：`server-rs/crates/api-server/src/creative_agent.rs`、`creative_agent_sse.rs`、`app.rs`、`state.rs`、`module-puzzle` creative template/tool、Phase 1 PRD。
 - 验证方式：`cargo check -p api-server`、`cargo test -p module-puzzle creative`、`cargo test -p api-server creative_agent`、`npm run dev:api-server` 后检查 `/healthz`、`POST /api/runtime/creative-agent/sessions`、`POST /api/runtime/creative-agent/sessions/{sessionId}/messages/stream`。
 - 关联文档：`docs/prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md`。
@@ -3016,6 +3070,7 @@
 - 背景：图片画布的图片、改图、图标素材、UI 素材提取、角色动作、视频和音频生成都可能长时间等待外部 provider；如果继续由 HTTP handler 同步执行，生产只能扩 API 进程，不能独立扩生成吞吐。
 - 决策：`GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 下，画板所有外部 provider 生成入口统一入 `external_generation_job`，job kind 使用 `editor_image_generation`、`editor_image_edit`、`editor_background_removal`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation` 和 `editor_background_music_generation`。worker 成功后由后端写 `editor_project_resource` / `editor_asset` / `editor_canvas.layers_json`；前端只轮询 BFF job 状态并重新读取项目快照，不从队列 payload 或本地临时状态重建完成图层。
 - 2026-06-29 补充：手动点击图层“去除背景”也属于图片画布外部 provider 任务，`/api/editor/images/background-removals` 在 queue 模式只入队 `editor_background_removal`，worker 完成后用新 resource 原地替换目标 layer。任务列表只展示服务器 `external_generation_job` 返回的任务，禁止再用前端 local task 伪造抠图进度。
+- 2026-06-30 补充：手动“去除背景”在有项目上下文时也创建画布生成占位并随请求提交 `canvasCompletion`，worker / BFF 完成后通过现有生成完成链路把结果写入该占位；无 `canvasCompletion` 的旧路径才原地替换目标 layer。画布任务列表展示服务器阶段文案，生成中才显示耗时，排队不计时也不展示百分比。
 - 补充：带 `dialogId` 的 `canvasCompletion` 必须读取后端当前 layout 中的最新 generation dialog placeholder；等待期间用户移动占位时，结果层要跟随最新占位。无 dialog 的重绘 / UI 素材提取等入口使用明确的右侧完成占位；生成器已删除时不把结果重新塞回画布。
 - 影响范围：`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`。
@@ -3965,3 +4020,18 @@
 - 2026-06-24 调整：普通用户通过聊天输入 `/canvas 画板项目ID` 触发待确认 `canvas.project_open`，只打开本机 Genarrative 编辑器 `/editor/canvas?projectid=...`；不得把它扩展成远程站点或任意 URL 打开能力。
 - 2026-06-24 调整：普通用户通过聊天输入 `/import-canvas-asset 本地路径 画板项目ID 资源ID|object:资产对象ID [kind] [mediaType]` 触发待确认 `canvas.asset_import`，只登记项目目录内已有文件为 `canvas` 来源资产；只有 `assetObjectId` 时使用 `object:` 前缀，不伪造 resourceId；画板导出包回流使用 `/import-canvas-export /绝对/画板素材.zip 画板项目ID`。
 - 验证方式：`npm run ai-game-creator-shell:typecheck`、`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`、`npm run test -- packages/shared/src/contracts/gameCreationApp.test.ts`、`cargo test -p shared-contracts game_creation_app --manifest-path server-rs/Cargo.toml`、`cargo test -p platform-agent --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
+## 2026-06-30 唯一码和私有码按用户限兑一次
+
+- 背景：运营私有码按内部 user_id 指定用户后，指定用户仍可能无法兑换；排查 release `SEEDUSERLUO0630` 时确认兑换校验把私有码当成全局次数上限，而不是每个允许用户各自限兑一次。
+- 决策：兑换码使用校验中，公共码继续按 `max_uses` 控制单用户可兑次数；唯一码和私有码改为同一 `code + user_id` 只能成功兑换一次。私有码仍先校验 `allowed_user_ids`，命中允许名单后再按该用户历史使用次数拒绝重复兑换；`global_used_count` 只保留为统计字段，不再作为唯一码 / 私有码的兑换阻断条件。
+- 影响范围：`module-runtime::validate_runtime_profile_redeem_code_usage`、`profile_redeem_code_usage` 计次语义。
+- 验证方式：`cargo test -p module-runtime --manifest-path server-rs/Cargo.toml runtime_profile_redeem_code_usage_validation_matches_modes`、`npm run check:encoding`、`git diff --check`。
+
+## 2026-07-05 VectorEngine LLM 默认使用 `gpt-5.4-mini`
+
+- 背景：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 侧边栏的“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”是 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`。

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

@@ -1,6 +1,6 @@
 # 文档地图与阅读索引
 
-更新时间：`2026-06-22`
+更新时间：`2026-07-03`
 
 ## 当前文档入口
 
@@ -18,6 +18,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` |
 
 ## 阅读顺序
 

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

@@ -30,6 +30,14 @@
 - 验证：`ImageCanvasEditorModel.test.ts` 覆盖素材库 source resource 保留，`useImageCanvasAssetCanvasBridge.test.tsx` 覆盖资源 ID 级联清理，`ImageCanvasEditorAssetsIntegration.test.tsx` 覆盖删除后保存的新 layout 不再包含被删图层。
 - 关联：`src/components/image-editor/ImageCanvasEditorModel.ts`、`src/components/image-editor/useImageCanvasAssetCanvasBridge.ts`、`src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx`。
 
+## 后台素材查询不要用 SQL 直查 editor_asset
+
+- 现象：后台“素材查询”报 `HTTP 400：no such table: editor_asset. If the table exists, it may be marked private.`。
+- 原因：`editor_asset` 是私有 SpacetimeDB 表，后台 SQL / schema HTTP 查询面看不到私有表；即使 api-server 有后台身份，也不能把私有表当 Dashboard SQL 表直接查。
+- 处理：后台素材查询走 `spacetime-module` 内的 `admin_list_editor_assets_and_return` procedure，由 `spacetime-client` typed facade 调用后再在 `api-server` 映射作者展示名和陶泥号。新增类似后台只读能力时，优先补窄 procedure / read model，不要复用 `fetch_admin_dashboard_rows` 直查私有源表。
+- 验证：`cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`。
+- 关联：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`server-rs/crates/spacetime-client/src/editor_project.rs`、`server-rs/crates/api-server/src/admin.rs`。
+
 ## 陶泥儿精选重复先查同源同媒体画布副本
 
 - 现象：每次从项目素材中把同一个生成素材拖到画布上，`陶泥儿精选` 都多出一张看起来相同的素材。
@@ -66,8 +74,8 @@
 
 - 现象：画板生成、快速编辑、图标素材或 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。
-- 验证：`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_reference`，并用前端 workflow 测试覆盖 `referenceImageSrcs` 进入快速编辑 / 图标生成请求。
+- 处理：所有编辑器参考图入口统一走 `parse_editor_reference_image(state, owner_user_id, source)`；objectKey 分支必须先在当前账号的项目资源、素材库资产或 `asset_object` 中匹配 owner / bucket / key，再读取 OSS。图标素材等额外参考图必须真实传到 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`。
 
 ## 编辑器生成按钮显示泥点后仍要查真实钱包预扣
@@ -86,6 +94,15 @@
 - 验证：`http://127.0.0.1:3101/v1/ping` 可访问、`http://127.0.0.1:8082/healthz` 返回 200、`http://127.0.0.1:3000/` 和 `http://127.0.0.1:3102/admin/` 可打开。
 - 关联：`scripts/dev.mjs`、`.app/dev-stack.json`、`docs/project-memory/shared-memory/development-workflow.md`。
 
+## 私有兑换码不适用先查同手机号重复账号
+
+- 现象：后台把私有兑换码配给某个陶泥号或手机号后，用户用同一手机号登录兑换仍提示 `该兑换码不适用于当前账号`。
+- 原因：认证表里可能存在同一手机号的多条 `user_account`。如果认证工作集重建 `phone_to_user_id` 时让 `user_account.phone_number_e164` 后写覆盖前写，当前登录态会漂到没有 `auth_identity` 的重复账号，而兑换码白名单仍指向另一个内部 `user_id`。
+- 处理：重建认证工作集时以 typed `AuthStoreProjectionView` 从 `user_account` / `auth_identity` / `refresh_session` 恢复；手机号索引以 `auth_identity(provider="phone")` 指向的账号为权威，`user_account.phone_number_e164` 只补没有 identity 的手机号；`auth_store_snapshot` 表和旧 JSON procedure 已删除，Bearer / refresh session 本进程未命中时不要再从 SpacetimeDB 导出整包状态刷新内存。线上止血先核对失败请求附近的 current session `user_id` 与兑换码 `allowed_user_ids`，不要只看手机号展示值。
+- 约束：`auth_identity` 只保存登录入口身份键；手机号、昵称和头像的正式资料真相在 `user_account.phone_number_e164` / `display_name` / `avatar_url`。旧 `auth_identity.phone_e164` / `display_name` / `avatar_url` 只能作为历史回填来源，不能继续让新写入依赖这些列。
+- 验证：`cargo test -p spacetime-module auth_export -- --nocapture` 应覆盖同手机号重复账号时手机号索引优先指向有 phone identity 的账号；`api-server` 中不应再存在运行期 `refresh_auth_store_from_spacetime` 调用。
+- 关联：`server-rs/crates/spacetime-module/src/auth/procedures.rs`、`server-rs/crates/spacetime-module/src/auth/tables.rs`、`server-rs/crates/module-auth/src/lib.rs`。
+
 ## API Build / Deploy 归档清单不能漏掉随包 Pingora 脚本
 
 - 现象：`Genarrative-Api-Deploy` 在发布阶段报 `发布产物缺少 Pingora TLS 证书同步脚本: build/<version>/scripts/deploy/pingora-tls-cert-sync.mjs`。
@@ -302,14 +319,30 @@
 - 验证：`npm run test -- src/components/image-editor/ImageCanvasOverlayModel.test.ts src/components/image-editor/useImageCanvasGenerationSurface.test.tsx`。
 - 关联：`src/components/image-editor/ImageCanvasOverlayModel.ts`、`src/components/image-editor/useImageCanvasGenerationSurface.tsx`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。
 
-## 图片画布图片改造也必须创建独立生成器占位
+## 图片画布重绘创建独立占位，快速编辑不要新建生成器
 
-- 现象：点击图片图层的“改造”后，输入框直接挂在原图上，提交时既不像其它生成入口一样有独立占位，也容易让用户误以为会覆盖源图。
-- 原因：图片改造复用了旧 `QuickEditPanelState` / redraw 面板路径，只把源图选中并在原图附近打开快速编辑框，没有进入统一的 `CanvasGenerationDialogState` 占位链路。
-- 处理：图片和用户快照图层的“改造”统一创建 `mode="quick-edit"` 的 generation dialog，占位仍走 `ImageCanvasGenerationPlacementModel`；源图作为隐式最后一张参考图提交，并把“当前图”提示词归一到对应参考图编号。音频改造继续走音频生成器路径，非图片 fallback 才保留旧面板。参考图 Data URL 提交前可压缩，但浏览器图片解码卡住时必须超时透传原图，不能阻塞生成请求。
-- 验证：`npm run test -- src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/services/image-editor/editorImageReference.test.ts -- --runInBand`，以及 `npm run test -- src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx -t "hides quick edit and redraw panels|opens generated image info|shows the quick edit generator" -- --runInBand`。
+- 现象：用户点击图片素材的“快速编辑”后，画布上额外出现 `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`。
 
+## 图片画布快速编辑完成必须按目标图层回写
+
+- 现象：图片快速编辑任务成功后，刷新页面素材库能看到新图，但画布上的源图没有替换。
+- 原因：`/api/editor/images/edits` 只保存生成图、项目资源和素材；没有 `canvasCompletion` 时不会写 `editor_canvas.layers_json`。`sourceResourceId` 只能表示溯源，同一资源可出现在多个图层，不能用它来决定替换哪一层。
+- 处理：图片快速编辑请求必须传 `targetLayerId`；后端在没有 `canvasCompletion` 的快速编辑完成分支里，用目标 layer id 和生成资源写回项目 layout。
+- 验证：`npm run test -- src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx -- --runInBand`；后端验证至少覆盖 `editor_image_edit_request_omits_price_mud_points` 和 `editor_image_edit_can_complete_by_replacing_target_layer`。
+- 关联：`src/services/image-editor/editorProjectClient.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`server-rs/crates/api-server/src/editor_project.rs`。
+
+## 图片画布快速编辑元数据必须记录原图引用
+
+- 现象：快速编辑生成的新图可以替换画布，但打开图片信息时“生成输入”里看不到被修改的原图。
+- 原因：信息面板直接渲染 `generationInputs.references`；快速编辑虽然把原图作为 `sourceImageSrc` 传给 provider，但如果 `buildQuickEditGenerationInputs(...)` 不把源图写成引用，后端资源和画布层都没有可展示的原图引用。
+- 处理：快速编辑的 `generationInputs.references` 必须始终包含 `原图`，再追加用户额外参考图；关闭额外参考图入口时也不能删除这条源图引用。
+- 验证：`npm run test -- src/components/image-editor/ImageCanvasGenerationModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx -- --runInBand`。
+- 关联：`src/components/image-editor/ImageCanvasGenerationModel.ts`、`src/components/image-editor/ImageCanvasMetadataModalView.tsx`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`。
+
 ## 图片画布生成完成应用项目快照后也要刷新素材库
 
 - 现象：部分素材生成成功后画布上已经出现结果，但左侧素材库没有立刻出现新素材，刷新页面后才显示。
@@ -387,16 +420,16 @@
 
 - 现象：拼图首关生成接口返回 `queued`，但生成页长时间不完成，重启 `genarrative-api.service` 也没有推进任务。
 - 原因：HTTP 角色只入队，不再直接调用外部 provider；如果没有运行 `GENARRATIVE_PROCESS_ROLE=external-generation-worker` 或 `all` 的进程，`external_generation_job` 会停留在 `pending/running`，直到有 worker claim。
-- 处理：生产用 `systemctl enable --now genarrative-external-generation-worker@1.service genarrative-external-generation-controller.service` 启动保底 worker 和 controller；首次 API deploy 会在默认 worker pattern 下自动启用并启动 `@1`、等待 worker active，并重启验活 controller。扩容默认交给 controller 按队列统计启动 `@2.service` 等实例，手动扩缩容只作为兜底；worker 收到停机信号后会停止 claim 新任务并等待当前任务完成。本地 smoke 可临时用 `GENARRATIVE_PROCESS_ROLE=all npm run dev`；本地若只想同步排查可通过 `.env.local` 或本机环境设置 `GENARRATIVE_EXTERNAL_GENERATION_MODE=inline`，但这不会创建 job，也不能验证 worker 扩缩容。
+- 处理：生产用 `systemctl enable --now genarrative-external-generation-worker@1.service genarrative-external-generation-controller.service` 启动保底 worker 和 controller；`genarrative-api.service` 对 controller 使用 systemd `Wants` 弱依赖，启动 API 时会尝试一并拉起 controller，但不会让 HTTP 进程自己执行 `systemctl`。首次 API deploy 会在默认 worker pattern 下自动启用并启动 `@1`、等待 worker active，并重启验活 controller。扩容默认交给 controller 按队列统计启动 `@2.service` 等实例，手动扩缩容只作为兜底；worker 收到停机信号后会停止 claim 新任务并等待当前任务完成。本地 smoke 可临时用 `GENARRATIVE_PROCESS_ROLE=all npm run dev`；本地若只想同步排查可通过 `.env.local` 或本机环境设置 `GENARRATIVE_EXTERNAL_GENERATION_MODE=inline`，但这不会创建 job，也不能验证 worker 扩缩容。
 - 验证：`systemctl status genarrative-external-generation-controller.service 'genarrative-external-generation-worker@*.service'` 能看到 controller 和 worker 实例；queue 模式下任务被 claim 后 `worker_id` 与 `lease_expires_at` 会更新，完成后 session 进入 ready 或 failed；inline 模式下不应产生新的 `external_generation_job`。
 - 关联：`deploy/systemd/genarrative-external-generation-worker@.service`、`deploy/systemd/genarrative-external-generation-controller.service`、`deploy/env/external-generation-controller.env.example`、`server-rs/crates/spacetime-module/src/external_generation.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
-## 外部生成 worker 不应等待 HTTP 认证快照恢复
+## 外部生成 worker 不应等待 HTTP 认证投影恢复
 
-- 现象：`genarrative-external-generation-worker@1.service` 在 systemd 中显示 active，但 `external_generation_job` 长时间保持 `pending`；worker 日志每 5 秒出现 `export_auth_store_snapshot_from_tables` 订阅失败，例如缺少 `public_work_gallery_entry` 公开 read model 表。
-- 原因：独立 worker / controller 是非 HTTP 角色，不承接用户登录态恢复；如果启动路径复用 HTTP `api-server` 的认证快照恢复，SpacetimeDB 认证投影或公开 read model 漂移会把 worker claim 循环挡在启动前。
-- 处理：`GENARRATIVE_PROCESS_ROLE=external-generation-worker` 和 `external-generation-controller` 启动时只构建空 auth store 的 `AppState`，不调用 SpacetimeDB 认证快照导出；只有 `api` / `all` 这类 HTTP 角色需要在启动时恢复认证快照并在依赖不可用时重试或进入 503 降级。
-- 验证：重启 worker 后日志应先出现“非 HTTP 进程跳过 SpacetimeDB 认证快照恢复”，随后出现 `external generation worker 已启动`；同一时间窗口不应再因为 `export_auth_store_snapshot_from_tables` 缺表而阻止 job claim。HTTP `api-server` 的认证恢复日志和 503 降级语义保持不变。
+- 现象：`genarrative-external-generation-worker@1.service` 在 systemd 中显示 active，但 `external_generation_job` 长时间保持 `pending`；worker 日志每 5 秒出现认证投影或公开 read model 订阅失败。
+- 原因：独立 worker / controller 是非 HTTP 角色，不承接用户登录态恢复；如果启动路径复用 HTTP `api-server` 的认证投影恢复，SpacetimeDB 认证投影或公开 read model 漂移会把 worker claim 循环挡在启动前。
+- 处理：`GENARRATIVE_PROCESS_ROLE=external-generation-worker` 和 `external-generation-controller` 启动时只构建空 auth store 的 `AppState`，不调用 SpacetimeDB 认证投影导出；只有 `api` / `all` 这类 HTTP 角色需要在启动时恢复认证投影并在依赖不可用时重试或进入 503 降级。
+- 验证：重启 worker 后日志应先出现“非 HTTP 进程跳过 SpacetimeDB 认证投影恢复”，随后出现 `external generation worker 已启动`；同一时间窗口不应再因为认证投影恢复失败而阻止 job claim。HTTP `api-server` 的认证恢复日志和 503 降级语义保持不变。
 - 关联：`server-rs/crates/api-server/src/main.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`、`server-rs/crates/api-server/src/external_generation_worker_controller.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
 ## 本地旧 external-generation-worker 会抢队列并暴露成 procedure 超时
@@ -427,7 +460,7 @@
 
 - 现象：release 机器 `03:20` 冷备份后，`spacetimedb.service` 已恢复，但作品列表、创作入口配置或公开 gallery 继续超时 / 502 / 504，`genarrative-api.service` 保持 stopped；或图片画布生成请求返回队列态后长期显示排队，`external_generation_job` 有 claimable pending，但 `genarrative-external-generation-worker@1.service` / controller 是 inactive。
 - 原因：`genarrative-api.service`、`genarrative-external-generation-worker@*.service` 和 `genarrative-external-generation-controller.service` 都配置了 `Requires=spacetimedb.service`，冷备份停止 `spacetimedb.service` 时这些服务会被 systemd 依赖关系一并停止；如果 `genarrative-database-backup.service` 只恢复数据库或只重启 API，外部生成队列就不会被消费。
-- 处理：生产冷备份 unit 和发布脚本必须带 `--restart-service-after genarrative-api.service`、`--restart-service-after genarrative-external-generation-worker@1.service` 和 `--restart-service-after genarrative-external-generation-controller.service`；仓库用 `npm run check:production-ops` 检查 systemd 模板、API build/deploy 归档和健康巡检链路。现场修复后执行 `systemctl daemon-reload`，但不要为了验证而手动触发冷备份。
+- 处理：生产冷备份 unit 和发布脚本必须带 `--restart-service-after genarrative-api.service`、`--restart-service-after genarrative-external-generation-worker@1.service` 和 `--restart-service-after genarrative-external-generation-controller.service`；`genarrative-api.service` 也保留对 controller 的 `Wants` 弱依赖，覆盖“只恢复 API”的现场兜底。仓库用 `npm run check:production-ops` 检查 systemd 模板、API build/deploy 归档和健康巡检链路。现场修复后执行 `systemctl daemon-reload`，但不要为了验证而手动触发冷备份。
 - 验证：`systemctl cat genarrative-database-backup.service` 应包含这些参数；`systemctl is-active spacetimedb.service genarrative-api.service genarrative-external-generation-worker@1.service genarrative-external-generation-controller.service nginx.service` 全为 `active`；`curl -fsS http://127.0.0.1:3101/v1/ping`、`/healthz`、`/readyz` 和代表性 `/api/runtime/puzzle/gallery` 均成功；`get_external_generation_queue_stats_and_return` 不应长期出现 claimable pending。
 - 关联：`deploy/systemd/genarrative-database-backup.service`、`scripts/database-backup-to-oss.mjs`、`scripts/ops/production-health-patrol.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
@@ -1188,27 +1221,27 @@
 - 验证：生成文件落在 `public/branding/taonier-logo-*/`，用 Pillow 检查图片尺寸和非空；执行 `node --check scripts/generate-taonier-logo-concepts.mjs`、`npm run check:encoding`、`git diff --check`。
 - 关联：`scripts/generate-taonier-logo-concepts.mjs`、`docs/design/TAONIER_BRAND_LOGO_CONCEPTS_2026-05-13.md`。
 
-## 忘记密码后仍提示手机号或密码错误先查认证快照同步
+## 忘记密码后仍提示手机号或密码错误先查认证投影同步
 
 - 现象：用户通过“忘记密码”重设密码后，接口返回成功或页面进入登录态，但再次使用新密码登录仍提示“手机号或密码错误”；重启后还可能出现 `Bearer JWT 版本已失效`，日志里的 token version 与本地快照不一致。
-- 原因：重置/修改密码会更新 `password_hash`、`password_login_enabled` 和 `token_version`，如果 API 层只更新本地 `InMemoryAuthStore`，没有调用 `sync_auth_store_snapshot_to_spacetime()`，`api-server` 重启时可能从旧的 SpacetimeDB 表或旧快照恢复账号状态。
-- 处理：`POST /api/auth/password/change` 与 `POST /api/auth/password/reset` 成功后必须同步认证快照。2026-05-27 起，启动恢复只允许从 SpacetimeDB 正式认证表恢复；`auth_store_snapshot` 只保留行级记录，不再写 `default` 聚合单行，也不再把本地文件 `auth-store.json` / `GENARRATIVE_AUTH_STORE_PATH` 当作恢复源。认证创建、登录会话、刷新、退出、改密、重置密码、绑定和资料变更等写操作必须在返回客户端前成功同步 SpacetimeDB；同步失败时接口返回错误，不允许把只存在于当前进程内存的账号或会话当成成功结果。新用户注册奖励、邀请码绑定和登录埋点必须排在认证同步成功之后，避免认证没落库时先写出钱包或邀请关系。若启动时连不上 SpacetimeDB，`api-server` 等待启动恢复超时后进入依赖不可用模式，所有请求返回 `503 SERVICE_UNAVAILABLE`，`details.reason = "spacetime_startup_unavailable"`。
+- 原因：重置/修改密码会更新 `password_hash`、`password_login_enabled` 和 `token_version`，如果 API 层只更新本地 `InMemoryAuthStore`，没有调用 `sync_auth_store_tables_to_spacetime()`，`api-server` 重启时可能从旧的 SpacetimeDB 正式认证表恢复账号状态。
+- 处理：`POST /api/auth/password/change` 与 `POST /api/auth/password/reset` 成功后必须同步正式认证表。2026-07-01 起，`auth_store_snapshot` 表和旧 JSON procedure 已删除；认证工作集只通过 typed projection 同步 `user_account` / `auth_identity` / `refresh_session`。认证创建、登录会话、刷新、退出、改密、重置密码、绑定和资料变更等写操作必须在返回客户端前成功同步 SpacetimeDB；同步失败时接口返回错误，不允许把只存在于当前进程内存的账号或会话当成成功结果。新用户注册奖励、邀请码绑定和登录埋点必须排在认证同步成功之后，避免认证没落库时先写出钱包或邀请关系。
 - 验证：执行 `cargo test -p module-auth password --manifest-path server-rs/Cargo.toml` 与 `cargo test -p api-server password --manifest-path server-rs/Cargo.toml`；手测时重设密码后旧密码应失败，新密码应成功，重启后仍应保持。
 - 关联：`server-rs/crates/api-server/src/password_management.rs`、`server-rs/crates/api-server/src/state.rs`、`docs/technical/PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md`。
 
 ## 密码登录失败且短信登录提示手机号已存在先查孤儿手机号索引
 
 - 现象：老账号用密码登录提示“手机号或密码错误”，改用短信验证码登录又提示“手机号已存在 / 已注册”，用户卡在既不能登录也不能重新创建的状态。
-- 原因：历史版本或停服务时认证同步不完整，可能在 SpacetimeDB `auth_identity(provider=phone)` 或 `module-auth` 快照里留下 `phone_to_user_id` 映射，但对应 `user_account` / `users_by_username` 用户行已经不存在。密码登录按手机号索引找不到真实用户，短信登录尝试创建新用户时又被孤儿手机号索引挡住。
-- 处理：`export_auth_store_snapshot_from_tables` 导出时必须过滤没有 `user_account` 的 phone / wechat identity、union 索引和 refresh session；`module-auth` 从 JSON 快照恢复时也必须二次丢弃指向不存在用户的索引。运行时创建手机号用户前若发现手机号映射指向不存在的用户，应删除孤儿映射后继续创建，避免死锁态继续扩散。
-- 验证：`cargo test -p module-auth snapshot_json_drops_orphan_phone_index_before_phone_login --manifest-path server-rs/Cargo.toml`、`cargo test -p module-auth phone --manifest-path server-rs/Cargo.toml`、`cargo test -p spacetime-module auth --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server phone_login_reuses_existing_user_for_same_phone_number --manifest-path server-rs/Cargo.toml`。
+- 原因：历史版本或停服务时认证同步不完整，可能在 SpacetimeDB `auth_identity(provider=phone)` 或旧 `module-auth` 快照里留下 `phone_to_user_id` 映射，但对应 `user_account` / `users_by_username` 用户行已经不存在。密码登录按手机号索引找不到真实用户，短信登录尝试创建新用户时又被孤儿手机号索引挡住。
+- 处理：`export_auth_store_projection_from_tables` 只导出正式认证表 projection；`module-auth` 从 projection 恢复时必须丢弃指向不存在 `user_account` 的 identity、union 索引和 refresh session。运行时创建手机号用户前若发现手机号映射指向不存在的用户，应删除孤儿映射后继续创建，避免死锁态继续扩散。
+- 验证：`cargo test -p module-auth projection --manifest-path server-rs/Cargo.toml`、`cargo test -p module-auth phone --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server phone_login_reuses_existing_user_for_same_phone_number --manifest-path server-rs/Cargo.toml`。
 - 关联：`server-rs/crates/module-auth/src/lib.rs`、`server-rs/crates/spacetime-module/src/auth/procedures.rs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
 
-## 认证本地文件快照已废弃，旧 procedure 也已删
+## 认证快照表和旧 procedure 已删除
 
-- 现象：有些旧代码和生成 bindings 里还会残留 `get_auth_store_snapshot`、`upsert_auth_store_snapshot`、`import_auth_store_snapshot`，或者把 `auth-store.json` 误当成认证恢复源。
-- 原因：认证恢复已经彻底收口到 SpacetimeDB 正式表和 `module-auth` 的 JSON 导入 / 导出路径；本地文件持久化会和正式表投影打架，SpacetimeDB 不可用时还可能把旧快照回灌到用户表。
-- 处理：先用 `npm run spacetime:generate -- --rust-only` 刷新 bindings，确认 `server-rs/crates/spacetime-client/src/module_bindings.rs` 里已没有旧 procedure 导出；`module-auth` 只保留内存态，不再写本地快照文件。
+- 现象：有些旧代码和生成 bindings 里还会残留 `get_auth_store_snapshot`、`upsert_auth_store_snapshot`、`import_auth_store_snapshot`、`import_auth_store_snapshot_json`、`export_auth_store_snapshot_from_tables`，或者把 `auth-store.json` 误当成认证恢复源。
+- 原因：认证恢复已经彻底收口到 SpacetimeDB 正式表和 `module-auth` typed projection；本地文件持久化或 JSON 快照会和正式表投影打架，SpacetimeDB 不可用时还可能把旧快照回灌到用户表。
+- 处理：先用 `npm run spacetime:generate` 刷新 bindings，确认 `server-rs/crates/spacetime-client/src/module_bindings.rs` 里已没有旧 snapshot table / procedure 导出；`module-auth` 只保留内存态和 projection view，不再写本地快照文件。
 - 验证：`cargo check -p module-auth --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、`npm run check:encoding`。
 
 ## 抓大鹅生成页只显示服务暂不可用先查 reason 和外部服务配置
@@ -1337,7 +1370,7 @@
 ## GPT-image-2 不再读 APIMart 图片配置
 
 - 现象：配置了 `APIMART_BASE_URL` / `APIMART_API_KEY` 后，RPG、拼图或方洞的 GPT-image-2 生图仍返回缺配置，或请求体里还出现 `official_fallback` / `image_urls`。
-- 原因：2026-05-21 后 GPT-image-2 图片生成按 VectorEngine 创建/编辑接口分流，APIMart 只保留给创意 Agent 的 `gpt-5` Responses 文本/多模态链路。
+- 原因：2026-05-21 后 GPT-image-2 图片生成按 VectorEngine 创建/编辑接口分流；2026-07-05 后创意 Agent 文本链路也改为 VectorEngine Chat Completions `gpt-5.4-mini`，APIMart 不再作为当前创意 Agent 来源。
 - 处理：为图片生成配置 `VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai`、`VECTOR_ENGINE_API_KEY`、`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；排查请求体时确认无参考图路径为 `/v1/images/generations`、有参考图路径为 `/v1/images/edits`，模型为 `gpt-image-2`。
 - 验证：运行 `cargo test -p api-server openai_image --manifest-path server-rs/Cargo.toml` 和相关玩法图片生成测试；真实联调只在本地私密环境放置 VectorEngine key。
 - 关联：`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`、`server-rs/crates/api-server/src/openai_image_generation.rs`。
@@ -2378,7 +2411,7 @@
 
 ## 本地 api-server 启动订阅 401 先查 Web identity token 注入
 
-- 现象：`npm run dev` 启动到 api-server 恢复认证快照时，日志出现 `Failed to initiate WebSocket connection ... /v1/database/<db>/subscribe?compression=Brotli: HTTP error: 401 Unauthorized`。
+- 现象：`npm run dev` 启动到 api-server 恢复认证投影时，日志出现 `Failed to initiate WebSocket connection ... /v1/database/<db>/subscribe?compression=Brotli: HTTP error: 401 Unauthorized`。
 - 原因：SpacetimeDB SDK 订阅需要 Web API identity token；本地 `.env.local` 常把 `GENARRATIVE_SPACETIME_TOKEN` 留空，只靠 CLI 登录态 publish 成功并不能让 api-server 的 WebSocket subscribe 获得权限。
 - 处理：`scripts/dev.mjs` 在 SpacetimeDB 就绪后调用 `/v1/identity` 创建当前进程专用 Web API identity token，并只注入本次 `api-server` 环境；不要把临时 token 写进 `.env.local` 或日志。若仍报 401，先确认是否使用了项目脚本启动、日志是否出现 `已创建本地 Web identity`，以及 `GENARRATIVE_SPACETIME_SERVER_URL` / 数据库名是否指向本次启动的实例。
 - 验证：`npm run test -- scripts/dev.test.ts`；重新运行 `npm run dev` 后 api-server 启动日志不再出现上述 subscribe 401，`/healthz` 返回 200。

docs/technical/【前端架构】SSE客户端传输层收口约定-2026-06-03.md

@@ -13,6 +13,7 @@
 - `readSseStream` 负责读取 `Response.body`、识别 `\n\n` 与 `\r\n\r\n` 事件边界、合并多行 `data:`、flush `TextDecoder` 尾部缓冲，并支持事件处理函数返回 `false` 后取消 reader。
 - `readSseJsonStream` 只在传输事件基础上解析 JSON object，空 data 与异常 JSON 继续按旧口径静默跳过。
 - 各业务 client 只保留领域事件归一化、最终结果聚合和中文错误文案，不再重复实现 SSE 边界扫描、reader 循环或 UTF-8 flush。
+- `src/services/image-editor/editorAgentSse.ts` 消费画布 Agent 的 JSON SSE，只校验并归一 `stage`、`message_delta`、`tool_started`、`tool_completed`、`generation_result`、`error`、`done` 事件，不持有 reader 循环或事件边界解析。
 - OpenAI 兼容流、`[DONE]` 哨兵或其它非 JSON SSE 可直接使用 `readSseStream`；业务 JSON 事件优先使用 `readSseJsonStream`。
 
 ## 落地范围
@@ -25,12 +26,27 @@
 - `src/services/visual-novel-runtime/visualNovelRuntimeSse.ts`
 - `src/services/rpg-entry/rpgProfileClient.ts`
 - `src/services/llmClient.ts`
+- `src/services/image-editor/editorAgentSse.ts`
 
 后续新增 SSE client 时不得复制 `findSseEventBoundary`、`parseSseEventBlock` 或手写 reader 循环；若确实需要特殊 framing，应先扩展 `sseStream.ts` 的传输能力，再在业务 client 中处理领域语义。
 
+## 画布 Agent SSE client 口径
+
+`src/services/image-editor/editorAgentSse.ts` 是画布 Agent 的业务事件归一层，只允许做以下事情：
+
+- 调用 `readSseJsonStream(response, handler)` 读取 JSON SSE。
+- 白名单识别 `stage`、`message_delta`、`tool_started`、`tool_completed`、`generation_result`、`error`、`done`。
+- 支持两种兼容输入形态：优先使用 SSE `event:` 字段作为事件名；若 `data` 内含 `{ "event": "...", "data": {...} }`，则归一为同一 `EditorAgentSseEvent`。
+- 对未知事件名、缺失 `data` 或非对象 JSON 静默跳过，保持业务 client 的容错口径。
+
+`editorAgentSse.ts` 不得实现 `Response.body.getReader()`、`TextDecoder`、SSE 边界扫描、JSON 字符串拼接、fetch、鉴权、错误文案、会话状态聚合或画布聚焦逻辑；这些职责分别留在 `sseStream.ts`、`editorAgentClient.ts`、`useEditorAgentConversation.ts` 和画布视图层。
+
 ## 验收
 
 - `src/services/sseStream.test.ts` 覆盖 CRLF / LF 边界、UTF-8 尾部 flush、异常 JSON 跳过和提前停止取消 reader。
 - `src/services/llmClient.test.ts` 覆盖 OpenAI 兼容文本流、异常 JSON 跳过和 `[DONE]` 后提前停止。
+- `src/services/image-editor/editorAgentSse.test.ts` 覆盖画布 Agent 的 `stage`、`generation_result`、`done` 事件解析，以及 `{ event, data }` fallback 形态归一。
+- `src/services/image-editor/editorAgentClient.test.ts` 覆盖会话 CRUD 路由和 `/messages/stream` 发起后能收到类型化 SSE 事件。
+- 后续修改 `editorAgentSse.ts` 时，若出现手写 reader、`TextDecoder`、SSE 边界扫描或 fetch 逻辑，应视为违反本收口约定。
 - 已有 OpenAI 兼容文本流、NPC 聊天流、创作 Agent、创意互动 Agent、视觉小说运行态和充值订单状态测试继续通过。
 - `npm run typecheck` 不产生新的类型错误。

docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md

@@ -214,7 +214,7 @@ curl -f http://127.0.0.1:<api-port>/healthz
 
 本地 `npm run dev` 与 `npm run dev:api-server` 默认注入 `GENARRATIVE_PROCESS_ROLE=all`，同一 Rust 进程同时监听 HTTP 并消费外部生成队列；显式设置 `GENARRATIVE_PROCESS_ROLE` 时保留显式值。需要验证生产式拆分角色、lease 重领或扩缩容时，再分别启动 `api`、`external-generation-worker` 和 `external-generation-controller`，也可以使用隔离容器 smoke。
 
-生产 smoke 需要保持 `GENARRATIVE_EXTERNAL_GENERATION_MODE=queue`，并至少启动一个 `api` 角色、一个 `external-generation-worker` 角色和一个 `external-generation-controller` 角色；发布脚本会在默认 worker pattern 下自动启用并启动 `genarrative-external-generation-worker@1.service`，重启并验活 `genarrative-external-generation-controller.service`。若 worker 数量归零，生成任务会保持 `queued/running`，不会由 HTTP 进程偷偷执行。部署验证除 `/healthz` / `/readyz` 外，还要确认任务列表 BFF 可读、未确认终态任务会弹出提示、提示展示后后台 acknowledge 且刷新后不再弹出，单 job 状态能从 `queued/running` 收敛到业务 session/detail 的 ready 或 failed。
+生产 smoke 需要保持 `GENARRATIVE_EXTERNAL_GENERATION_MODE=queue`，并至少启动一个 `api` 角色、一个 `external-generation-worker` 角色和一个 `external-generation-controller` 角色；发布脚本会在默认 worker pattern 下自动启用并启动 `genarrative-external-generation-worker@1.service`，重启并验活 `genarrative-external-generation-controller.service`。`genarrative-api.service` 还通过 systemd `Wants=genarrative-external-generation-controller.service` 弱依赖覆盖只启动 API 的现场兜底；controller 仍是独立进程，不由 HTTP 进程内执行 `systemctl`。若 worker 数量归零，生成任务会保持 `queued/running`，不会由 HTTP 进程偷偷执行。部署验证除 `/healthz` / `/readyz` 外，还要确认任务列表 BFF 可读、未确认终态任务会弹出提示、提示展示后后台 acknowledge 且刷新后不再弹出，单 job 状态能从 `queued/running` 收敛到业务 session/detail 的 ready 或 failed。
 
 systemd 生产 controller 与手动兜底示例：
 

docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md

@@ -39,7 +39,7 @@
 - `sort_time_micros`
 - `detail_payload_json`
 
-作品源表新增 `visible` 可见性字段，默认 `true`。`visible` 属于源表 / source view 过滤条件，不作为统一公开契约默认返回字段；当 `visible=false` 时，对应作品不得进入 `public_work_gallery_entry` 和 `public_work_detail_entry`。
+作品源表新增 `visible` 可见性字段，新作品默认 `false`。`visible` 属于源表 / source view 过滤条件，不作为统一公开契约默认返回字段；当 `visible=false` 时，对应作品不得进入 `public_work_gallery_entry` 和 `public_work_detail_entry`。
 
 其中 `detail_payload_json` 只承载平台详情页展示扩展，不承载正式 runtime 配置、玩法规则或草稿真相。
 
@@ -76,7 +76,7 @@
 - 旧 view 保留，不删除。
 - 旧 view 退到底层 source / 兼容职责。
 - 新 `public_work_*` view 是 `api-server` 公开列表 / 详情的统一主读模型。
-- 各玩法 source view 只暴露 `visible=true` 的已发布作品；旧数据迁移默认补 `visible=true`，避免历史作品被误隐藏。
+- 各玩法 source view 只暴露 `visible=true` 的已发布作品；旧数据迁移仍补 `visible=true`，避免历史作品被误隐藏；新发布作品默认不公开，需后台开启后才进入公开消费路径。
 - RPG / 自定义世界旧数据可能缺少 `published_at`。统一公开详情可以用 `updated_at` 作为展示和排序兜底；点赞、游玩、Remix 等写入路径也必须按 `publication_status=Published + visible=true + 未删除` 判断作品存在，不能额外要求 `published_at` 非空。
 - 临时运行约束：SpacetimeDB 2.2 下抓大鹅 `match_3_d_gallery_view` 的 `publication_status` 索引过滤在源表更新触发统一 view 刷新时可能初始化 panic；为避免后台隐藏作品打爆 module instance，统一 `public_work_*` view 暂不级联抓大鹅 source view，抓大鹅公开入口先保留玩法专用路径。后续应以 source projection 表替代索引 view 后再重新并入统一 read model。
 - 旧 `/api/runtime/<play>/gallery` 响应 shape 保持兼容，由 BFF mapper 把统一 cache 再映射回当前 DTO。

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

@@ -1,6 +1,6 @@
 # server-rs 与 SpacetimeDB 数据契约
 
-更新时间：`2026-06-24`
+更新时间：`2026-07-03`
 
 ## 后端主线
 
@@ -21,7 +21,7 @@ SpacetimeDB 版本口径：当前 Rust crate `spacetimedb`、`spacetimedb-sdk`
 当前主要 crate：
 
 - HTTP 服务：`api-server`。
-- 领域模块：`module-ai`、`module-assets`、`module-auth`、`module-bark-battle`、`module-big-fish`、`module-combat`、`module-creative-agent`、`module-custom-world`、`module-inventory`、`module-match3d`、`module-npc`、`module-progression`、`module-puzzle`、`module-quest`、`module-runtime`、`module-runtime-item`、`module-runtime-story`、`module-square-hole`、`module-story`、`module-visual-novel`。
+- 领域模块：`module-ai`、`module-assets`、`module-auth`、`module-bark-battle`、`module-big-fish`、`module-combat`、`module-creative-agent`、`module-editor-agent`、`module-custom-world`、`module-inventory`、`module-match3d`、`module-npc`、`module-progression`、`module-puzzle`、`module-quest`、`module-runtime`、`module-runtime-item`、`module-runtime-story`、`module-square-hole`、`module-story`、`module-visual-novel`。
 - 平台副作用：`platform-agent`、`platform-auth`、`platform-image`、`platform-llm`、`platform-oss`、`platform-wechat`、`platform-speech`。
 - 共享层：`shared-contracts`、`shared-kernel`、`shared-logging`。
 - SpacetimeDB：`spacetime-client`、`spacetime-module`。
@@ -54,14 +54,15 @@ npm run check:server-rs-ddd
 路由树由 `server-rs/crates/api-server/src/app.rs` 统一构造。当前主要分组：
 
 - 健康检查：`GET /healthz`。
-- 后台管理：`/admin/api/*`，包括登录、Dashboard 运营看板、概览、HTTP debug、埋点、表查询、创作入口开关、作品互动配置、作品可见性、兑换码、邀请码、任务配置和充值商品配置。Dashboard 指标口径见 [`docs/technical/【后台管理】Dashboard运营看板方案-2026-06-23.md`](./technical/【后台管理】Dashboard运营看板方案-2026-06-23.md)。
+- 后台管理：`/admin/api/*`，包括登录、Dashboard 运营看板、概览、HTTP debug、埋点、表查询、精选审核、素材查询、创作入口开关、作品互动配置、作品可见性、兑换码、邀请码、任务配置和充值商品配置。Dashboard 指标口径见 [`docs/technical/【后台管理】Dashboard运营看板方案-2026-06-23.md`](./technical/【后台管理】Dashboard运营看板方案-2026-06-23.md)。
 - 认证与账号：`/api/auth/*`、`/api/profile/me`，包括短信、密码、微信、refresh session、多端会话和登出。
 - 个人中心：`/api/profile/*`，包括钱包流水、任务、领奖、充值、反馈、邀请和兑换等账号侧能力。
 - 平台基础能力：`/api/llm/*`、`/api/speech/volcengine/*`，只保留通用 LLM 和语音代理。
 - 资产基础能力：`/api/assets/direct-upload-tickets`、`/api/assets/sts-upload-credentials`、`/api/assets/objects/*`、`/api/assets/read-*`，负责直传、确认、绑定和读取。
 - 外部 OpenAPI：`/api/external/v1/openapi.json`、`/api/external/v1/assets/direct-upload-tickets`、`/api/external/v1/assets/objects/confirm`、`/api/external/v1/assets/read-url`、`/api/external/v1/editor/*`，使用 Bearer API Key 鉴权；API Key 管理仍在登录态 `/api/profile/api-keys`，不进入外部 OpenAPI JSON。
-- 创作 / 游玩支撑能力：`/api/creation-entry/config`、`/api/ai/tasks*`、`/api/runtime/chat/*`、`/api/runtime/settings`、`/api/runtime/save/snapshot`、`/api/profile/browse-history`、`/api/profile/save-archives*`、`/api/profile/play-stats`、`/api/assets/history`、`/api/assets/character-visual/*`、`/api/assets/character-animation/*`、`/api/assets/character-workflow-cache*`、`/api/assets/hyper3d/*`、`/api/runtime/custom-world/asset-studio/*`、`/api/editor/projects*`。`/api/runtime/custom-world/asset-studio/*` 解析默认角色形象 / 动作提示词时可以在 OSS 缓存不可用或未配置时按无缓存返回默认提示；保存 workflow 缓存和真实素材读写仍必须要求 OSS 正常可用。
+- 创作 / 游玩支撑能力：`/api/creation-entry/config`、`/api/ai/tasks*`、`/api/runtime/chat/*`、`/api/runtime/settings`、`/api/runtime/save/snapshot`、`/api/profile/browse-history`、`/api/profile/save-archives*`、`/api/profile/play-stats`、`/api/assets/history`、`/api/assets/character-visual/*`、`/api/assets/character-animation/*`、`/api/assets/character-workflow-cache*`、`/api/assets/hyper3d/*`、`/api/runtime/custom-world/asset-studio/*`、`/api/editor/projects*`、`/api/editor/projects/{projectId}/agent-conversations`、`/api/editor/agent-conversations/{conversationId}*`。`/api/runtime/custom-world/asset-studio/*` 解析默认角色形象 / 动作提示词时可以在 OSS 缓存不可用或未配置时按无缓存返回默认提示；保存 workflow 缓存和真实素材读写仍必须要求 OSS 正常可用。
 - 后台入口配置：`/admin/api/creation-entry/config`、`/admin/api/creation-entry/config/banners` 和 `/admin/api/creation-entry/config/interactions`。
+- 后台素材查询：`GET /admin/api/editor-assets` 通过 `admin_list_editor_assets_and_return` 后台只读 procedure 读取私有账号级 `editor_asset` 中 `source_type = 'generated'` 的素材，支持 `ownerUserId`、`keyword`、`createdAfter`、`createdBefore`、`cursor` 和 `limit`；返回缩略图 / Object Key、作者展示名、陶泥号、提示词、生成输入和生成成本，只用于查询，不提供分类筛选，也不执行精选审核、返还或展示状态修改，不通过后台 SQL 直查私有表。
 - 自定义世界 / RPG：`/api/runtime/custom-world*`、`/api/story/*`、`/api/runtime/chat/*`。
 - 拼图：`/api/runtime/puzzle/*`。
 - 抓大鹅 Match3D：`/api/creation/match3d/*`、`/api/runtime/match3d/*`。
@@ -75,6 +76,15 @@ npm run check:server-rs-ddd
 
 需要新增路由时，先确认玩法入口配置和 tracking 分类，不要绕过 `app.rs` 的统一中间件、鉴权和入口开关。涉及创作、生成、作品、公开详情、试玩、正式运行态、运行态库存、运行态设置 / 存档、游玩历史、存档归档、游玩统计、AI task、角色资产工坊或玩法生成支撑资产的路由，不再直接在 `app.rs` 逐玩法 `.merge(...)`，也不挂到 `modules/platform.rs`；必须先进入 `server-rs/crates/api-server/src/modules/play_flow.rs` 的统一玩法流程主干，再由主干注册表分发到各领域 HTTP Adapter 或支撑能力 handler。
 
+### 图片画布 Agent 对话
+
+- `/api/editor/projects/{projectId}/agent-conversations` 负责当前工程会话列表和新建；`/api/editor/agent-conversations/{conversationId}` 负责详情读取和软删；`/api/editor/agent-conversations/{conversationId}/messages/stream` 负责发送消息并返回 SSE。
+- `module-editor-agent` 只承载纯领域校验：标题派生、附件上限、消息输入规则和会话软删访问规则；不直接依赖 Axum、SpacetimeDB、OSS、LLM 或 Tokio。
+- `spacetime-module` 的 `editor_agent_conversation` 只保存元数据；创建、列表、读取、更新时间和软删通过 `create_editor_agent_conversation_and_return`、`list_editor_agent_conversations_and_return`、`get_editor_agent_conversation_and_return`、`touch_editor_agent_conversation_and_return`、`delete_editor_agent_conversation_and_return` procedure 完成，`api-server` 只能经 `spacetime-client` facade 访问。
+- 完整消息文档存 OSS `editor-agent/{conversationId}.json`，由 `api-server` 负责 2 MiB 上限、会话内串行锁、读改写、SSE 事件持久化和 `touch` 元数据更新时间；该 JSON 不进入 `editor_canvas.layers_json`，也不作为画布布局真相。
+- 对话附件只允许引用当前工程 `editor_project_resource` 或当前账号 `editor_asset` 的图片；前端可提交展示用 `imageSrc` / `thumbnailSrc`，后端必须按 `resourceId` / `assetId` 重新归一、校验 owner / project 和 `objectKey`，再给 LLM 或生成工具使用。
+- 画布 Agent 工具复用既有编辑器图片生成 / 修改 / 图标 spritesheet BFF，并继续使用后端模型定价和 `execute_billable_asset_operation_with_cost`；前端不提交 `priceMudPoints`。
+
 ### 创作 / 游玩统一流程主干
 
 `modules/play_flow.rs` 是后端创作与游玩流程的统一入口。现有外部 URL、DTO、错误 envelope、鉴权方式、入口开关语义和 SpacetimeDB schema 默认不变，但路由组织必须遵循：
@@ -202,11 +212,12 @@ npm run check:server-rs-ddd
 2. 编辑器画板所有会调用外部生成 provider 的入口都不从前端请求接收 `priceMudPoints`；实际扣费真相以后端运行时模型定价配置为准，前端按钮泥点只作为展示。
 3. 编辑器图片生成 / 图片修改 / 图标 spritesheet / UI 设计图提取素材 / 视频 / 角色动作 / 音效 / 背景音乐必须在后端计算模型价格后使用 `execute_billable_asset_operation_with_cost` 预扣泥点；预扣失败必须 fail-closed，不得继续提交 VectorEngine、Ark、Suno 或 Vidu 上游任务。
 4. 音频生成的编辑器链路虽然任务提交和结果发布分离，仍必须把提交时后端计算出的模型价格写入 `AudioAssetBindingTarget.billing_points_cost`，最终发布落资产时按该价格扣费；创作音频目标未提供该字段时才使用旧的创作音频固定成本。
-5. 编辑器图片生成、图片修改、图标 spritesheet 和 UI 设计图提取素材的参考图可以提交 Data URL 或已登记的 generated objectKey；objectKey 必须归属于当前账号的 `editor_project_resource`、`editor_asset` 或 `asset_object`，后端通过归属校验后才签名读取 OSS。快速编辑、图标素材和 UI 素材提取的额外参考图必须真正传入 provider，不得只写入 `generationInputs` 展示快照；UI 素材提取额外参考图上限为 5 张，普通图片生成上限 5 张，快速编辑 / 图标素材上限 8 张额外参考图。
+5. 编辑器图片生成、图片修改、图标 spritesheet 和 UI 设计图提取素材的参考图可以提交 Data URL 或已登记的 generated objectKey；objectKey 必须归属于当前账号的 `editor_project_resource`、`editor_asset` 或 `asset_object`，后端通过归属校验后才签名读取 OSS。图标素材和 UI 素材提取的额外参考图必须真正传入 provider，不得只写入 `generationInputs` 展示快照；图片快速编辑当前不开放额外参考图，只提交原图或红框序号标注图作为 `sourceImageSrc`。UI 素材提取额外参考图上限为 5 张，普通图片生成上限 5 张，图标素材上限 8 张额外参考图。
 
 ## 外部服务与资产
 
 - LLM：通用 LLM 门面继续使用 `GENARRATIVE_LLM_*`；`platform-llm` 文本请求默认走 Responses，旧 `/api/llm/chat/completions` 代理和少数旧运行态聊天显式保留 Chat Completions 兼容协议；创意 Agent `gpt-5` Responses / Chat Completions 文本链路已于 2026-06 从 APIMart 迁移到 VectorEngine，使用 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible client，`api-server` 会把未带 `/v1` 的 VectorEngine base URL 规范化到 `/v1` 后请求 `/responses`。`APIMART_BASE_URL` / `APIMART_API_KEY` 只作为历史残留，不再作为创意 Agent gpt-5 客户端来源；后续排障时优先确认 VectorEngine `/v1/models`、`/v1/chat/completions` 和 `/v1/responses` 可用性。
+- LLM：通用 LLM 门面继续使用 `GENARRATIVE_LLM_*`；创意 Agent `gpt-5.4-mini` Chat Completions 文本链路已于 2026-06 从 APIMart 迁移到 VectorEngine，使用 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible client，`api-server` 会把未带 `/v1` 的 VectorEngine base URL 规范化到 `/v1` 后请求 `/chat/completions`。通用 `/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` 时可复用 `VECTOR_ENGINE_API_KEY`。`APIMART_BASE_URL` / `APIMART_API_KEY` 只作为历史残留，不再作为创意 Agent gpt-5.4-mini 客户端来源；后续排障时优先确认 VectorEngine `/v1/models`、`/v1/chat/completions` 和 `/v1/responses` 可用性。
 - 图片生成：VectorEngine `gpt-image-2` 图片 provider 归属 `platform-image`，密钥只在后端环境变量中；`api-server` 内的 `openai_image_generation.rs` 只是兼容调用面和外部失败审计桥接，不再承载 provider 协议实现。实际外部生成运行记录统一落 `tracking_event`，`event_key = external_generation_run`，metadata 记录开始 / 结束时间、耗时、状态、成功标记、失败原因、provider task id 和结果摘要，不再写回过时的 `ai_task`。DashScope 只按仍在使用的历史能力单独处理，不作为 GPT-image-2 兜底。VectorEngine `/v1/images/generations` 和 `/v1/images/edits` 上游 POST 使用 `libcurl` 发送；`reqwest` 只保留给参考图 URL 下载和响应中图片 URL 下载。`/v1/images/edits` 的 multipart 参考图必须作为 libcurl 文件上传 part 发送，字段名为 `image`，实现上使用 `Form::buffer(file_name, bytes)` 并设置 `Content-Type`；不能只用 `contents(...).filename(...)`，否则上游会把请求转码为缺少图片并返回 `image is required`。`request_send` 阶段的 curl timeout / connect error 按可重试传输错误处理，最多尝试 5 次，并使用指数退避加短抖动；排障时优先看 `attempt`、`max_attempts`、`retry_delay_ms`、`reference_image_bytes_total` 和 `request_params`，不要把 `SendRequest` 当成上游业务错误。
 - Match3D 物品 sheet：关卡整图完成后走 VectorEngine `/v1/images/edits` multipart `image`，模型为 `gpt-image-2`，`2K 1:1` 输出 `10*10` spritesheet；物品 sheet prompt 固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG，并把透明整图写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。后端优先按透明 alpha 连通域从该 sheet 识别真实素材矩形并持久化 20 个物品、每个 5 个形态；识别数量不足时才回退 `10*10` 固定网格。通用系列素材图集的行列索引按每行 2 个物品计算，必须落在 `1..=10`，难度只决定运行态加载 3 / 9 / 15 / 20 种。
 - Match3D UI spritesheet 和背景派生图：关卡整图作为参考图并发生成 `1K 1:1` UI spritesheet 与 `1K 9:16` 背景图，模型均为 `gpt-image-2`。UI spritesheet prompt 固定要求单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；背景图必须合成为全画幅不透明 PNG。
@@ -214,7 +225,7 @@ npm run check:server-rs-ddd
 - 敲木鱼敲击物和背景环境图：VectorEngine `/v1/images/edits`，模型固定 `gpt-image-2`。敲击物支持 multipart 多参考图，第一张固定为后端内嵌默认木鱼图，用户上传图只作为新主题参考；prompt 必须要求 `1:1` 单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景主体图，并禁止黑底、白底、棋盘格和任何实底背景。当前敲击物和返回按钮上传 OSS 前只做服务端绿幕去背后处理，避免泛抠图误伤玉米等主体像素。背景环境图只使用第一步抠图完成后的透明敲击物图作为参考，prompt 必须要求中央主体预留区保持干净，中央 40% 区域禁止出现主题主体、主体局部特写、轮廓影子或重复元素，主题元素只能作为外围氛围，且必须显式声明不继承任何绿色底色、绿幕底色或纯绿色画布。
 - Hyper3D / Rodin：只保留后端安全代理和旧数据兼容；Rodin 提交、状态、下载和响应解析归属 `platform-hyper3d`，`api-server/src/hyper3d_generation.rs` 只做路由、配置和错误 envelope 映射；新 Match3D 草稿和批量新增不再生成 GLB。
 - 音频：视觉小说专用音频路由保留；VectorEngine Suno/Vidu provider 协议、任务提交/查询、音频 URL 提取、下载、MIME/extension 归一和 OSS put 请求准备归属 `platform-audio`。`api-server/src/vector_engine_audio_generation.rs` 只做路由、配置、计费、asset object confirm、entity binding 和错误 envelope 映射；拼图、抓大鹅和敲木鱼提示词生成音效入口暂时关闭，通用 `/api/creation/audio/*` 对这些目标返回 `410 Gone`。敲木鱼创作只接收上传 / 录音音频资产；前端选择或录音阶段只在浏览器本地处理待提交音频，统一限制裁切后最长 1 秒、裁掉前后声音过小片段，并用浏览器端近似响度算法平衡到 `-15 LKFS` 后做峰值保护。点击生成时才直传 OSS 并确认 `asset_object`，创作 JSON 只提交轻量 `WoodenFishAudioAsset`，不得继续上传 Data URL 音频；未提供时由 `api-server` 写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。
-- OSS：私有 generated legacy path 进入浏览器前必须通过 `/api/assets/read-url` 换签；不要裸请求 `/generated-*`。前端如果收到同一 OSS bucket 的完整 `https://*.oss-*.aliyuncs.com/generated-*` 地址，也必须先归一为 legacy path 后走同一换签链路，避免裸连私有 bucket 403 或绕过签名缓存。OSS 签名、读签名、HEAD 和 PUT 的结构化日志由 `platform-oss` 输出，排查资产写入 / 确认失败时优先按 `operation`、`object_key` / `key_prefix`、`status_class`、`error_kind` 和 `elapsed_ms` 下钻。新上传 generated 私有对象默认写入 `Cache-Control: public, max-age=31536000, immutable`；旧对象若缺该头，只能依赖 `ETag` / `Last-Modified` 协商缓存，应通过 OSS 元数据刷新或 CDN 配置补齐，不要恢复 api-server 静态代理。
+- OSS：私有 generated legacy path 进入浏览器前必须通过 `/api/assets/read-url` 换签；不要裸请求 `/generated-*`。前端如果收到同一 OSS bucket 的完整 `https://*.oss-*.aliyuncs.com/generated-*` 地址，也必须先归一为 legacy path 后走同一换签链路，避免裸连私有 bucket 403 或绕过签名缓存。OSS 签名、读签名、HEAD 和 PUT 的结构化日志由 `platform-oss` 输出，排查资产写入 / 确认失败时优先按 `operation`、`object_key` / `key_prefix`、`status_class`、`error_kind` 和 `elapsed_ms` 下钻。新上传 generated 私有对象默认写入 `Cache-Control: public, max-age=31536000, immutable`；旧对象若缺该头，只能依赖 `ETag` / `Last-Modified` 协商缓存，应通过 OSS 元数据刷新或 CDN 配置补齐，不要恢复 api-server 静态代理。`editor-agent/` 前缀只用于服务端内部读写画布 Agent 会话消息文档，不属于浏览器直传 legacy public prefix；`/api/assets/direct-upload-tickets` 必须拒绝 `legacyPrefix=editor-agent`，内部读取只允许 `editor-agent/{conversationId}.json` 形态。
 - 外部 API 失败审计：外部供应商调用未成功时，`api-server` 必须发送 OTLP 失败事件并写入 `tracking_event`。VectorEngine 图片 provider 在 `platform-image` 内输出结构化日志和 `PlatformImageFailureAudit`，覆盖 `request_send`、`response_body`、`upstream_status`、`response_parse`、`missing_image` 和 `image_download` 阶段；`api-server` 只把该 audit 映射成 `external_api_call_failure`，`scope_kind = module`、`scope_id = provider`、`module_key = external-api`。metadata 固定包含 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel、rawExcerpt，以及在调用方可获得上下文时补充的 `userId`（触发者）和 `profileId`（草稿 / 作品 / 场景作用域）。图片生成入口应优先把 owner user id 和 profile id 透传到失败审计，不要只保留 provider 级聚合，否则很难按“谁触发、哪个作品触发”定位问题。入库优先复用 tracking outbox，outbox 不可写或保护阈值拒绝时回退同步写 SpacetimeDB；不得新增前端兜底或在 SpacetimeDB reducer 内做外部 I/O。
 - 外部生成运行记录：所有外部生成编排的完成态统一写入 `tracking_event`，`event_key = external_generation_run`，`scope_kind = module`，`scope_id = provider`，`module_key = external-generation`。metadata 固定包含 `runId`、`provider`、`operation`、`requestLabel`、`requestPayload`、`status`、`success`、`failureReason`、`providerRequestId`、`resultPayload`、`startedAtMicros`、`completedAtMicros` 和 `durationMs`。这类记录只用于运行审计和排障，不再走 `ai_task` 旧表。
 
@@ -283,22 +294,16 @@ npm run check:server-rs-ddd
 
 - Rust 结构体：`AuthIdentity`
 - 源码：`server-rs/crates/spacetime-module/src/auth/tables.rs`
+- 职责：只表达登录入口身份键到 `user_account.user_id` 的绑定；`provider_uid` 保存手机号 E.164 或微信 openid，`provider_union_id` 保存微信 unionid。账户资料以 `user_account.phone_number_e164`、`user_account.display_name`、`user_account.avatar_url` 为准，`auth_identity.phone_e164` / `display_name` / `avatar_url` 仅保留旧行兼容，不再作为写入或恢复真相。
 
 ### `auth_store_projection_meta`
 
 - Rust 结构体：`AuthStoreProjectionMeta`
 - 源码：`server-rs/crates/spacetime-module/src/auth/tables.rs`
 
-### `auth_store_snapshot`
+认证恢复策略：`api-server` 启动时只从 SpacetimeDB 正式认证表（`user_account` / `auth_identity` / `refresh_session`）导出 typed `AuthStoreProjectionView`，再恢复 `module-auth` 的进程内认证工作集；运行中 Bearer `sid` 或 refresh cookie 在本进程工作集内未命中时直接按失效处理，不再从 SpacetimeDB 导出整包认证状态刷新内存，避免旧投影把重复手机号或旧会话重新灌回进程。`module-auth` 只保留内存工作集和 projection 导入 / 导出能力，不再保留 JSON 快照导入 / 导出能力，也不写本地持久化文件；`auth-store.json` / `GENARRATIVE_AUTH_STORE_PATH` 不再是兼容恢复源。认证创建、登录会话、刷新、退出、改密、重置密码、绑定和资料变更等写操作必须在返回客户端前通过 `sync_auth_store_projection` 成功同步 SpacetimeDB 正式认证表；同步失败时接口返回错误，不允许把只存在于当前进程内存的账号或会话当成成功结果。新用户注册奖励、邀请码绑定和登录埋点必须排在认证同步成功之后，避免认证没落库时先写出钱包或邀请关系。若启动恢复阶段 SpacetimeDB 不可连接或超时，`api-server` 会按固定间隔持续重试认证工作集恢复，恢复成功后才开始监听 HTTP，避免一次短超时让进程永久停留在依赖不可用状态。
 
-- Rust 结构体：`AuthStoreSnapshot`
-- 源码：`server-rs/crates/spacetime-module/src/auth/tables.rs`
-
-认证恢复策略：`api-server` 启动时只从 SpacetimeDB 正式认证表（`user_account` / `auth_identity` / `refresh_session`）投影恢复进程内认证工作集；运行中若 Bearer `sid` 或 refresh cookie 在本进程工作集内未命中，会先从 SpacetimeDB 正式认证表按需刷新一次认证工作集再复查，避免多实例或滚动重启时新登录设备只被签发它的进程认识。`auth_store_snapshot` 只保留行级快照备查，不再作为启动兜底来源。`module-auth` 只保留内存工作集和 JSON 导入 / 导出能力，不再写本地持久化文件；`auth-store.json` / `GENARRATIVE_AUTH_STORE_PATH` 不再是兼容恢复源，也不得在启动时回写覆盖 `auth_identity` / `user_account`。认证创建、登录会话、刷新、退出、改密、重置密码、绑定和资料变更等写操作必须在返回客户端前成功同步 SpacetimeDB 正式认证表；同步失败时接口返回错误，不允许把只存在于当前进程内存的账号或会话当成成功结果。新用户注册奖励、邀请码绑定和登录埋点必须排在认证同步成功之后，避免认证没落库时先写出钱包或邀请关系。若启动恢复阶段 SpacetimeDB 不可连接或超时，`api-server` 会按固定间隔持续重试认证工作集恢复，恢复成功后才开始监听 HTTP，避免一次短超时让进程永久停留在依赖不可用状态。
-
-`auth_store_snapshot` 禁止再写单行 `snapshot_id = "default"` 聚合 JSON。认证同步入口收到 `module-auth` 整份快照后必须拆成行级记录写入同一张表，当前行键前缀包括：`meta/next_user_id`、`user/<user_id>`、`phone/<phone+user>`、`session/<session_id>`、`session_hash/<hash+session>`、`wechat/<provider_uid+user>`、`union/<union+user>`。SpacetimeDB 模块只保留 `import_auth_store_snapshot_json` 与 `export_auth_store_snapshot_from_tables` 两个认证快照过程；旧 `get_auth_store_snapshot`、`upsert_auth_store_snapshot`、`import_auth_store_snapshot` 兼容入口已删除。导入正式表时只按主键 upsert 本次快照包含的用户、身份和会话，避免过期快照把其他用户整表删除。
-
-导出认证快照时，`auth_identity` 与 `refresh_session` 只能引用仍存在于 `user_account` 的用户；孤儿手机号 identity、微信 identity、union 索引或 refresh session 必须被过滤，不能恢复成 `module-auth` 内存态里的 `phone_to_user_id` 死索引。`module-auth` 从 JSON 快照恢复时也要二次清理这些孤儿索引，避免历史坏快照导致密码登录提示错误、短信登录又提示手机号已存在。
+`auth_store_snapshot` 表和旧 `import_auth_store_snapshot_json` / `export_auth_store_snapshot_from_tables` procedure 已删除。认证投影同步只读写 `user_account`、`auth_identity`、`refresh_session` 和 `auth_store_projection_meta`；`auth_identity` 不再写 `phone_e164`、`display_name`、`avatar_url`，这些账号资料只以 `user_account` 为准。
 
 ### `bark_battle_draft_config`
 
@@ -319,7 +324,7 @@ npm run check:server-rs-ddd
 
 - Rust 结构体：`BarkBattlePublishedConfigRow`
 - 源码：`server-rs/crates/spacetime-module/src/bark_battle/tables.rs`
-- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，新作品默认 `false`；旧迁移数据由 `migration.rs` 按历史公开默认补 `true`。
 
 ### `bark_battle_runtime_run`
 
@@ -356,7 +361,7 @@ npm run check:server-rs-ddd
 - Rust 结构体：`BigFishCreationSession`
 - 源码：`server-rs/crates/spacetime-module/src/big_fish/tables.rs`
 - 索引：`by_big_fish_session_owner_user_id`、`by_big_fish_session_stage`。公开广场 view 使用 `by_big_fish_session_stage` 读取已发布会话，避免扫整表。
-- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，新作品默认 `false`；旧迁移数据由 `migration.rs` 按历史公开默认补 `true`。
 
 ### `big_fish_event`
 
@@ -420,13 +425,13 @@ npm run check:server-rs-ddd
 - Rust 结构体：`CustomWorldGalleryEntry`
 - 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
 - 作用：自定义世界公开 source 读模型。统一公开列表 / 详情主路径通过 `public_work_gallery_entry` / `public_work_detail_entry` 消费该投影并映射成跨玩法契约；`/api/runtime/custom-world-gallery` 保留旧 HTTP shape，并从统一 public cache 映射回旧 DTO。旧 procedure 只用于兼容旧库缺少 gallery 读模型行时的一次性同步兜底。
-- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，新作品默认 `false`；旧迁移数据由 `migration.rs` 按历史公开默认补 `true`。
 
 ### `custom_world_profile`
 
 - Rust 结构体：`CustomWorldProfile`
 - 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
-- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，新作品默认 `false`；旧迁移数据由 `migration.rs` 按历史公开默认补 `true`。
 - 兼容约束：历史公开 RPG / 自定义世界 profile 可能存在 `publication_status=Published` 但 `published_at=None`。公开详情、点赞、游玩、Remix 和 `custom_world_gallery_entry` 同步都以 `Published + deleted_at=None + visible=true` 判断作品可公开互动；展示和 gallery 同步时间在 `published_at` 缺失时回退 `updated_at`，不得仅因 `published_at` 为空返回“已发布作品不存在”。
 
 ### `custom_world_session`
@@ -451,11 +456,19 @@ npm run check:server-rs-ddd
 - 说明：外部 OpenAPI 调用使用的账号级 API Key 凭据表，只保存 key prefix、SHA-256 hash、作用域、撤销状态和使用时间；明文 Key 只在 `/api/profile/api-keys` 创建接口返回一次，不进入 SpacetimeDB，且 API Key 管理接口不写入外部 OpenAPI JSON。v1 默认作用域为 `editor:project`、`editor:canvas`、`editor:image-generate`、`editor:asset`；其中 `editor:project` 覆盖项目列表、最近项目、创建、读取、重命名和删除，`editor:canvas` 覆盖默认画布布局保存，`editor:image-generate` 覆盖编辑器现有图片生成、重绘 / 调整、规范图、宣发素材、图标 spritesheet 生成 / 拆分、UI 设计图素材拆分、角色动画、视频、音效和背景音乐生成，`editor:asset` 覆盖素材直传凭证、素材对象确认、签名读取、账号级素材库和项目画布资源记录操作。
 - 索引：`by_external_api_key_owner_user_id` 用于登录态 API Key 列表；`key_hash` 唯一索引用于外部 API 鉴权。
 
+### `editor_agent_conversation`
+
+- Rust 结构体：`EditorAgentConversation`
+- 源码：`server-rs/crates/spacetime-module/src/editor_agent_storage.rs`
+- 说明：画布Agent对话会话元数据表，归属单个 `editor_project`；只保存会话 ID、project、owner、标题、消息 OSS 对象键（`editor-agent/{conversationId}.json`）、软删标记和时间戳。消息正文整体存 OSS，按会话粒度整体读写，不进 SpacetimeDB、不进画布工程快照 payload。删除为软删（`deleted = true`，OSS 对象保留）。领域校验（标题截取、附件上限、归属 / 软删规则）沉在 `module-editor-agent`。
+- 过程：只通过 `create_editor_agent_conversation_and_return`、`list_editor_agent_conversations_and_return`、`get_editor_agent_conversation_and_return`、`touch_editor_agent_conversation_and_return`、`delete_editor_agent_conversation_and_return` procedure 操作；`api-server` 不直接绕过 `spacetime-client` facade 读写表。消息文档当前由 `api-server` 做单会话串行锁和 2 MiB 上限保护，避免同一 SSE 回合并发重写同一个 OSS JSON 文档。
+- 索引：`by_editor_agent_conversation_project_id` 用于会话列表；`by_editor_agent_conversation_owner_user_id` 用于账号级归属校验。
+
 ### `editor_project`
 
 - Rust 结构体：`EditorProject`
 - 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
-- 说明：图片画布工程真相表，保存 owner、标题和工程时间戳；viewport 与图层布局已拆到 `editor_canvas`，旧 layout columns 暂作为兼容列保留，不再作为权威数据源。只通过 `/api/editor/projects*` BFF 和 `spacetime-client` facade 读写；项目页列表、重命名和删除也使用该能力，删除工程时级联清理默认画布和资源元数据。
+- 说明：图片画布工程真相表，保存 owner、标题和工程时间戳；viewport 与图层布局已拆到 `editor_canvas`，旧 layout columns 暂作为兼容列保留，不再作为权威数据源。只通过 `/api/editor/projects*`、`/api/editor/projects/{projectId}/agent-conversations`、`/api/editor/agent-conversations/{conversationId}*` BFF 和 `spacetime-client` facade 读写；项目页列表、重命名和删除也使用该能力，删除工程时级联清理默认画布和资源元数据。
 - 索引：`by_editor_project_owner_user_id` 用于读取当前用户最近编辑工程和项目页工程列表。
 
 ### `editor_canvas`
@@ -469,7 +482,7 @@ npm run check:server-rs-ddd
 
 - Rust 结构体：`EditorProjectResource`
 - 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
-- 说明：图片画布工程资源元数据表，保存已经放入某个 project 画布的上传 / 生成图片资源快照、OSS 引用、尺寸、来源类型、prompt、provider、task、源资源关系、`asset_kind`、`generation_inputs_json` 和 `public_showcase_enabled`。`asset_kind` 标记角色、图标、UI 设计图、视频、音频等素材类别；`generation_inputs_json` 保存用户可见生成输入快照，供图片信息页刷新后恢复；`public_showcase_enabled` 控制该生成资源是否进入 `/creation` 的 `陶泥儿精选`，新增和旧行默认 `true`，但通过 `source_resource_id` 指向同一 owner 源资源且媒体引用相同的画布副本默认不公开。图片 / 图标 / UI 提取等生成 BFF 在请求携带 `project_id` 时负责创建该表记录并把 resource 快照返回前端；前端只保存布局引用，不能把同一生成结果再次作为正式业务真相写入。项目封面快照也落在该表，使用 `asset_kind = project-cover-snapshot`、`source_type = uploaded` 和私有 OSS / asset object 引用，代表画布当前视口栅格化后的静态封面；项目列表和创作主页最近项目只读取最新封面快照资源，不在列表页根据 `editor_canvas.layers_json` 临时拼画布。从账号级素材库把同一生成素材拖回同一项目画布时，后端优先复用同项目内同源同媒体资源，避免每个图层实例都插入新的资源行。公开精选读取走 `GET /api/editor/showcase/resources`，只返回 `source_type = generated`、图片源非空且 `public_showcase_enabled = true` 的全站资源，并跳过同源同媒体副本，按 `created_at` 倒序取前 36 条；公开响应的作者展示字段优先提供 `authorDisplayName` / `display_name`，没有展示名时提供 `authorPublicUserCode` / 陶泥号作为展示兜底，前端公开展示绝不能兜底到内部 `ownerUserId` / `user_id`。公开开关修改走登录鉴权 `PATCH /api/editor/project-resources/{resource_id}/showcase`，只允许资源 owner 更新。账号级素材删除不级联删除该表，避免历史画布丢图。`editor_canvas.layers_json` 只保存图层几何、层级、分组、资源引用和生成器对象；新写入不再把素材生成输入快照作为图层布局真相保存，旧布局字段只作为兼容兜底读取。
+- 说明：图片画布工程资源元数据表，保存已经放入某个 project 画布的上传 / 生成图片资源快照、OSS 引用、尺寸、来源类型、prompt、provider、task、源资源关系、`asset_kind`、`generation_inputs_json` 和历史 `public_showcase_enabled`。`asset_kind` 标记角色、图标、UI 设计图、视频、音频等素材类别；`generation_inputs_json` 保存用户可见生成输入快照，供图片信息页刷新后恢复。`public_showcase_enabled` 只保留旧接口兼容，不再作为 `/creation` 的 `陶泥儿精选` 事实源；精选公开改由账号级生成素材提交 `editor_showcase_asset` 审核决定。图片 / 图标 / UI 提取等生成 BFF 在请求携带 `project_id` 时负责创建该表记录并把 resource 快照返回前端；前端只保存布局引用，不能把同一生成结果再次作为正式业务真相写入。项目封面快照也落在该表，使用 `asset_kind = project-cover-snapshot`、`source_type = uploaded` 和私有 OSS / asset object 引用，代表画布当前视口栅格化后的静态封面；项目列表和创作主页最近项目只读取最新封面快照资源，不在列表页根据 `editor_canvas.layers_json` 临时拼画布。从账号级素材库把同一生成素材拖回同一项目画布时，后端优先复用同项目内同源同媒体资源，避免每个图层实例都插入新的资源行。账号级素材删除不级联删除该表，避免历史画布丢图。`editor_canvas.layers_json` 只保存图层几何、层级、分组、资源引用和生成器对象；新写入不再把素材生成输入快照作为图层布局真相保存，旧布局字段只作为兼容兜底读取。
 - 索引：`by_editor_project_resource_project_id`、`by_editor_project_resource_owner_user_id`。
 
 ### `editor_asset_folder`
@@ -483,9 +496,30 @@ npm run check:server-rs-ddd
 
 - Rust 结构体：`EditorAsset`
 - 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
-- 说明：图片画布账号级素材表，保存用户上传 / 生成素材的名称、文件夹、图片读取地址、可选封面 `thumbnail_src`、OSS 引用、尺寸、来源类型、prompt、provider、task、`asset_kind`、`generation_inputs_json` 和可选 `source_resource_id`。素材在同一账号的所有项目中可见；图片 / 图标 / UI 提取等生成 BFF 在请求携带 `asset_folder_id` 时负责创建账号级生成素材并返回 asset 快照，若同次生成也创建了 `editor_project_resource`，则把该 `resource_id` 写入 `source_resource_id`。生成视频会抽取首帧封面写入 `thumbnail_src`，素材库和再次放入画布时用它作为 video poster。素材库快照通过 `source_resource_id` 回查对应 project resource 的 `public_showcase_enabled`，供左侧素材菜单展示和切换公开状态；公开开关本身仍只落在 `editor_project_resource`，不在账号素材表复制真相。素材放入画布时复制为 `editor_project_resource` 并由图层引用 resourceId，画布从 resource / asset 级元数据恢复素材类别和用户可见生成输入快照。
+- 说明：图片画布账号级素材表，保存用户上传 / 生成素材的名称、文件夹、图片读取地址、可选封面 `thumbnail_src`、OSS 引用、尺寸、来源类型、prompt、provider、task、`asset_kind`、`generation_inputs_json`、可选 `source_resource_id` 和 `generation_cost_mud_points`。素材在同一账号的所有项目中可见；图片 / 图标 / UI 提取等生成 BFF 在请求携带 `asset_folder_id` 时负责创建账号级生成素材并返回 asset 快照，若同次生成也创建了 `editor_project_resource`，则把该 `resource_id` 写入 `source_resource_id`。生成视频会抽取首帧封面写入 `thumbnail_src`，素材库和再次放入画布时用它作为 video poster。素材库快照通过 `asset_id` 回查对应 `editor_showcase_asset`，供左侧素材菜单展示 `pending` / `approved` / `rejected` 审核状态；公开事实不落在账号素材表，素材库只发起提交审核。素材放入画布时复制为 `editor_project_resource` 并由图层引用 resourceId，画布从 resource / asset 级元数据恢复素材类别和用户可见生成输入快照。
 - 索引：`by_editor_asset_owner_user_id`、`by_editor_asset_folder_id`。
 
+### `editor_showcase_asset`
+
+- Rust 结构体：`EditorShowcaseAsset`
+- 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
+- 说明：`陶泥儿精选` 的独立审核与公开快照表。用户从账号级生成素材提交后，后端把素材媒体、提示词、生成输入、素材类型和 `generation_cost_mud_points` 快照到该表，初始 `review_status = pending`、`display_enabled = false` 且 `showcase_category = null`。后台审核通过后写入 `approved`，但仍保持不展示；运营需在后台按前台 Tab 手动设置 `showcase_category`（`packs`、`characters`、`ui`、`music`、`marketing`）并开启展示后，素材才进入公开精选。审核通过时生成确定性返还流水 `editor-showcase-refund:{showcase_id}`，BFF 按 50% 生成成本返还泥点后回写 `refund_completed_at`；拒绝后写入 `rejected`。公开精选 `GET /api/editor/showcase/resources` 只读取 `review_status = approved`、`display_enabled = true`、`showcase_category` 合法且媒体非空的记录，按通过时间 / `showcase_id` 倒序 cursor 分页。素材删除时，待审核记录标记 `asset_deleted_while_pending`，已拒绝记录删除，已通过记录保留快照继续展示。
+- 索引：`by_editor_showcase_asset_owner_user_id`、`by_editor_showcase_asset_review_status`。
+
+### `editor_showcase_asset_like`
+
+- Rust 结构体：`EditorShowcaseAssetLike`
+- 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
+- 说明：`陶泥儿精选` 点赞去重表，主键由 `showcase_id:user_id` 组成。点赞 / 取消点赞通过登录接口更新该表，并同步回写 `editor_showcase_asset.like_count`；未通过审核或未展示的精选素材不能点赞。
+- 索引：`by_editor_showcase_asset_like_showcase_id`、`by_editor_showcase_asset_like_user_id`。
+
+### `editor_showcase_campaign_config`
+
+- Rust 结构体：`EditorShowcaseCampaignConfig`
+- 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
+- 说明：`陶泥儿精选` 首位固定活动卡配置表，当前使用固定 `config_id = default`。后台可配置启用状态、标题、图片 URL、提示词、作者和成本文案；固定活动卡不包含副标题或 Object Key，公开精选接口只在启用时返回该配置。
+- 索引：主键 `config_id`。
+
 ### `inventory_slot`
 
 - Rust 结构体：`InventorySlot`
@@ -533,7 +567,7 @@ npm run check:server-rs-ddd
 - 返回类型：`Vec<JumpHopGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/jump_hop.rs`
 - 说明：跳一跳公开详情兼容投影，包含作品、路径和素材字段；统一公开详情主路径通过 `public_work_detail_entry` 消费该 view，只保留平台详情页展示摘要。
-- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，新作品默认 `false`；旧迁移数据由 `migration.rs` 按历史公开默认补 `true`。
 
 ### `wooden_fish_agent_session`
 
@@ -569,7 +603,7 @@ npm run check:server-rs-ddd
 - 返回类型：`Vec<WoodenFishGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/wooden_fish.rs`
 - 说明：敲木鱼公开详情兼容投影，包含敲击物图案、背景环境图、主题返回按钮图、敲击音效和飘字配置；统一公开详情主路径通过 `public_work_detail_entry` 消费该 view，只保留平台详情页展示摘要。
-- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，新作品默认 `false`；旧迁移数据由 `migration.rs` 按历史公开默认补 `true`。
 
 ### `match3d_agent_message`
 
@@ -599,7 +633,7 @@ npm run check:server-rs-ddd
 - 返回类型：`Vec<Match3DGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/match3d.rs`
 - 说明：抓大鹅公开 source 投影，只暴露 `publication_status = published` 的作品卡片字段；统一公开列表 / 详情主路径通过 `public_work_gallery_entry` / `public_work_detail_entry` 消费该 view 并映射成跨玩法契约。个人作品列表、详情、发布、点赞、游玩记录和 Remix 仍按原有 procedure / reducer 路径处理。
-- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，新作品默认 `false`；旧迁移数据由 `migration.rs` 按历史公开默认补 `true`。
 
 ### `npc_state`
 
@@ -626,6 +660,12 @@ npm run check:server-rs-ddd
 - Rust 结构体：`ProfileInviteCode`
 - 源码：`server-rs/crates/spacetime-module/src/runtime/profile.rs`
 
+### `profile_code_operation`
+
+- Rust 结构体：`ProfileCodeOperation`
+- 源码：`server-rs/crates/spacetime-module/src/runtime/profile.rs`
+- 作用：后台兑换码 / 邀请码的持久操作记录，记录新增、更新、停用的码值、操作人和操作时间。
+
 ### `profile_membership`
 
 - Rust 结构体：`ProfileMembership`
@@ -740,7 +780,7 @@ npm run check:server-rs-ddd
 - Rust 结构体：`PuzzleWorkProfileRow`
 - 源码：`server-rs/crates/spacetime-module/src/puzzle.rs`
 - 说明：拼图作品 profile 表，保存草稿 / 已发布作品的标题、作者、关卡、封面、发布状态、可见性、基础游玩数、点赞数、改造数和积分激励领取状态。
-- 字段变更：`visible` 控制是否进入公开列表 / 详情、通关后的推荐下一作品候选、公开点赞 / Remix 和正式公开 runtime；默认 `true`。后台隐藏后作品可保留 `publication_status = Published`，但公开消费路径必须按 `Published + visible=true` 判断。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情、通关后的推荐下一作品候选、公开点赞 / Remix 和正式公开 runtime；新作品默认 `false`，旧迁移数据按历史公开默认补 `true`。后台隐藏后作品可保留 `publication_status = Published`，但公开消费路径必须按 `Published + visible=true` 判断。
 
 ### `puzzle_clear_agent_session`
 
@@ -753,7 +793,7 @@ npm run check:server-rs-ddd
 - Rust 结构体：`PuzzleClearWorkProfileRow`
 - 源码：`server-rs/crates/spacetime-module/src/puzzle_clear/tables.rs`
 - 说明：拼消消作品 profile 表，保存中央底图资产、4 张素材工作表切片后合成的最终 atlas、35 个复合图案组、95 个 1x1 卡牌切片、卡背占位图、发布状态、可见性和基础 play count；公开列表 / 详情只通过 read model 消费，不让前端直接订阅源表。
-- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，新作品默认 `false`；旧迁移数据由 `migration.rs` 按历史公开默认补 `true`。
 
 ### `puzzle_clear_runtime_run`
 
@@ -842,7 +882,7 @@ RPG 创作入口的配置 ID 是 `rpg`，当前 `visible=true`、`open=true`；
 结构化创作和 RPG 的 LLM JSON 链路默认不启用 Responses `web_search`；只有在明确需要联网增强时，才通过 `GENARRATIVE_RPG_LLM_WEB_SEARCH_ENABLED` 或 `GENARRATIVE_CREATION_AGENT_LLM_WEB_SEARCH_ENABLED` 显式打开。否则未开通工具的上游会先吐自然语言再返回 `ToolNotOpen`，这类失败要按上游工具不可用处理，不要误判成模型返回结果解析失败。
 
 统一公开作品 BFF 路由是 `GET /api/public-works` 与 `GET /api/public-works/{publicWorkCode}`，响应契约由 `shared-contracts::public_work` 和 `packages/shared/src/contracts/publicWork.ts` 共同维护。前端首期仍走 BFF HTTP，不直接订阅 SpacetimeDB；后续若允许浏览器直连订阅，也只能订阅 `public_work_gallery_entry` / `public_work_detail_entry` 这类稳定公开 read model，不能订阅 `puzzle_work_profile`、`custom_world_profile` 等源表后自行拼装列表。设计细节见 `docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md`。
-- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，新作品默认 `false`；旧迁移数据由 `migration.rs` 按历史公开默认补 `true`。
 
 ### `quest_log`
 
@@ -895,7 +935,7 @@ RPG 创作入口的配置 ID 是 `rpg`，当前 `visible=true`、`open=true`；
 - 返回类型：`Vec<SquareHoleGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/square_hole.rs`
 - 说明：方洞挑战公开 source 投影，只暴露 `publication_status = published` 的作品卡片字段；统一公开列表 / 详情主路径通过 `public_work_gallery_entry` / `public_work_detail_entry` 消费该 view 并映射成跨玩法契约。个人作品列表、详情、发布、点赞、游玩记录和 Remix 仍按原有 procedure / reducer 路径处理。
-- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，新作品默认 `false`；旧迁移数据由 `migration.rs` 按历史公开默认补 `true`。
 
 ### `story_event`
 
@@ -929,6 +969,7 @@ RPG 创作入口的配置 ID 是 `rpg`，当前 `visible=true`、`open=true`；
 
 - Rust 结构体：`UserAccount`
 - 源码：`server-rs/crates/spacetime-module/src/auth/tables.rs`
+- 职责：账号资料真相源，保存 `phone_number_e164`、`display_name`、`avatar_url`、`created_at`、登录状态、密码 hash、token version 和账号标签。`module-auth` 进程内工作集必须通过 typed projection 与该表同步，不得再经 auth JSON 快照回灌。
 
 ### `user_browse_history`
 
@@ -971,4 +1012,4 @@ RPG 创作入口的配置 ID 是 `rpg`，当前 `visible=true`、`open=true`；
 - 返回类型：`Vec<VisualNovelGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/visual_novel.rs`
 - 说明：视觉小说公开 source 投影，只暴露 `publication_status = published` 的作品卡片字段，不把完整 `draft` 暴露给公开列表订阅；统一公开列表 / 详情主路径通过 `public_work_gallery_entry` / `public_work_detail_entry` 消费该 view 并映射成跨玩法契约。个人历史、详情、运行态和发布仍按原有 procedure / reducer 路径处理。
-- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，新作品默认 `false`；旧迁移数据由 `migration.rs` 按历史公开默认补 `true`。

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

@@ -99,13 +99,13 @@ SpacetimeDB procedure：
 
 - 图片生成 / 重绘 / 规范图 / 宣发图 / UI 设计图复用 `/api/editor/images/generations` 与 `/api/editor/images/edits` 的校验、模型归一、计费和持久化规则。
 - 图标 spritesheet 和 UI 设计图素材提取复用站内拆分逻辑，生成图集后按连通域切片，并把图集与切片都按请求写入项目资源和素材库。
-- 角色动画、视频、音效和背景音乐复用站内编辑器生成链路；音频类外部调用使用 API Key 所属账号作为 asset owner。
+- 角色动画、视频、音效和背景音乐复用站内编辑器生成链路；请求携带 `assetFolderId` 时按站内规则写入素材库，音频类外部调用使用 API Key 所属账号作为 asset owner。
 - API Key 管理接口仍只属于登录态个人中心，不进入外部 OpenAPI JSON。
 
-图片类外部生成成功后，后端拿到素材后：
+素材外部生成成功后，后端拿到素材后：
 
-1. 通过 OSS / asset object adapter 持久化图片。
-2. 写入 `editor_asset`，让生成图进入账号级素材库。
+1. 通过 OSS / asset object adapter 持久化媒体文件。
+2. 写入 `editor_asset`，让生成素材进入账号级素材库。
 3. 如果请求带 `projectId`，写入 `editor_project_resource`。
 4. 返回图片读取地址、素材 ID、资源 ID、尺寸、prompt、model、provider 和 taskId。
 
@@ -136,7 +136,7 @@ docs/openapi/genarrative-external-v1.openapi.json
 
 - API Key 创建只返回一次明文，列表不返回明文。
 - 撤销后的 API Key 调用外部接口返回 `401`。
-- 外部图片生成、重绘、图标拆分和 UI 素材拆分成功后，生成结果按请求同时出现在画布资源和账号级素材库。
+- 外部图片生成、重绘、图标拆分、UI 素材拆分、视频、音效和音乐生成成功后，生成结果按请求同时出现在画布资源和账号级素材库。
 - 外部视频、角色动画、音效和音乐接口使用站内编辑器相同的请求校验、模型限制和价格校验。
 - OpenAPI JSON 能被 `serde_json` 解析，且 security scheme 为 Bearer API Key。
 - OpenAPI JSON 不包含 `/api/profile/api-keys`、`UserAccessToken` 或 API Key 管理 schema。

docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md

@@ -27,7 +27,7 @@
 - 社群入口：原地弹出“玩家社区”二维码弹窗，复用现有社区弹层能力，不跳转或切换到“我的 / 用户中心”。
 - 营销点：`登录即送100泥点，可以免费制作50个素材`
 
-`开始创作` 与“新建项目”使用同一项目创建链路。用户已登录时调用现有 `createEditorProject`，成功后进入 `/editor/canvas?projectid=xxx`；未登录或登录过期时打开登录弹窗，并在登录后重试创建。
+`开始创作` 与“新建项目”使用同一项目创建链路。用户已登录时调用现有 `createEditorProject`，成功后进入 `/editor/canvas?projectid=xxx&guide=toolbar`，画布只消费一次 `guide=toolbar` 并清理 query，用于显示新画布工具栏引导；未登录或登录过期时打开登录弹窗，并在登录后重试创建。
 
 该区是页面第一屏的品牌与主操作区域，不使用外站品牌名。桌面端 `/creation` 继续保留现有平台左侧导航栏和上方栏，创作主页只替换中间内容区。
 
@@ -45,6 +45,16 @@
 8. 游戏功能编码：自然语言驱动游戏生成。
 9. 一键导出：支持一键导出为微抖小游戏、Godot、Unity、UE 工程。
 
+交互口径：
+
+- 游戏视觉规范：创建新画布后进入 `/editor/canvas?projectid=xxx&tool=icon-spec`，画布消费 `tool=icon-spec` 后拉起图标规范生成面板。
+- 游戏角色：创建新画布后进入 `/editor/canvas?projectid=xxx&tool=character-spec`，画布消费后拉起角色规范生成面板。
+- 游戏 UI：创建新画布后进入 `/editor/canvas?projectid=xxx&tool=ui-design`，画布消费后拉起生成 UI 设计图面板。
+- 游戏音乐：创建新画布后进入 `/editor/canvas?projectid=xxx&tool=background-music`，画布消费后拉起生成游戏背景音乐面板。
+- 游戏场景：创建新画布后进入 `/editor/canvas?projectid=xxx&tool=image`，画布消费后拉起生成图片面板。
+- 游戏美宣：创建新画布后进入 `/editor/canvas?projectid=xxx&tool=publication-cover`，画布消费后拉起游戏首图宣发素材面板。
+- 游戏特效、游戏功能编码、一键导出：不创建项目，复用移动端欢迎弹窗样式展示 `抱歉 / 功能还在调试中 / 暂未开放`，按钮为 `期待一下`。
+
 ### 最近项目
 
 仅登录后展示。模块位置在“陶泥儿精选”上方。
@@ -53,7 +63,7 @@
 - 标题右侧：`查看全部`，跳转 `/project`
 - 左侧第一项：`新建项目`
 - 右侧项目卡：按 `updatedAt` 倒序展示最近 4 个项目。
-- 项目卡点击进入 `/editor/canvas?projectid=xxx`。
+- 项目卡点击进入 `/editor/canvas?projectid=xxx`；“新建项目”进入 `/editor/canvas?projectid=xxx&guide=toolbar` 并触发一次新画布工具栏引导。
 - 项目卡点击必须直接写入最终 `/editor/canvas?projectid=xxx` 历史项，不允许先进入无参数 `/editor/canvas` 再二次跳转，否则浏览器返回需要点两次。
 - 项目缩略图复用 `/project` 项目卡的画布中心封面逻辑，避免两套封面算法。
 
@@ -63,7 +73,9 @@
 
 `陶泥儿精选` 是页面底部的全站公开画布生成素材瀑布流，不承载玩法入口列表。瀑布流卡片按真实素材宽高设置预览比例，同一行允许出现不同高度卡片，不使用固定等高网格。创作入口配置仍继续来自 `/api/creation-entry/config`，供旧创作入口和具体 `/creation/<play>` 工作台使用，但不作为本页精选区内容。
 
-精选内容只使用 `editor_project_resource` 中 `sourceType="generated"` 且 `public_showcase_enabled = true` 的项目资源，代表用户通过图片画布生成、已经落入某个项目并允许公开展示的素材。账号级 `editor_asset` 只表示跨项目素材库，不单独作为精选来源；上传素材、公开作品图片和 `mock_generated` 资源都不进入精选。从项目素材把同一个生成素材再次拖入画布时，只是新增图层实例或复用同源同媒体项目资源，不应额外生成新的精选候选；历史上已经产生的同源同媒体副本也需要在精选读取时跳过。公开 BFF 必须返回资源作者公开展示字段：优先 `authorDisplayName` / `display_name`，没有展示名时兜底 `authorPublicUserCode` / 陶泥号；前端展示绝不能兜底到内部 `ownerUserId` / `user_id`。若现有数据缺少提示词、作者公开标识或成本字段，v1 显示保守占位，不伪造内容。
+精选内容只使用用户从账号级素材库主动提交、后台审核通过、手动设置精选分类且展示状态开启的 `editor_showcase_asset` 快照。新生成素材不会默认公开，审核通过后也不会自动展示；运营需在后台按前台 Tab 设置分类（素材包、角色、UI、音乐、美宣）并开启展示。旧 `editor_project_resource.public_showcase_enabled` 只保留历史兼容，不再作为 `/creation` 精选事实源。账号级 `editor_asset` 仍是素材库私有事实；只有 `sourceType="generated"`、有媒体内容、提交审核并通过的素材才可进入精选，上传素材、公开作品图片和 `mock_generated` 资源都不进入精选。审核通过时按生成成本返还 50% 泥点，返还流水使用确定性 `editor-showcase-refund:{showcaseId}` 保证幂等。公开 BFF 必须返回作者公开展示字段：优先 `authorDisplayName` / `display_name`，没有展示名时兜底 `authorPublicUserCode` / 陶泥号；前端展示绝不能兜底到内部 `ownerUserId` / `user_id`。若现有数据缺少提示词、作者公开标识或成本字段，v1 显示保守占位，不伪造内容。
+
+瀑布流通过 `GET /api/editor/showcase/resources` 按通过审核时间 / `showcaseId` 倒序 cursor 分页读取，每页最多 36 条；响应有 `nextCursor` 时，页面滚动到底部继续请求 `?cursor=...` 并追加到现有瀑布流，而不是固定只展示首屏数量。响应可以额外携带后台配置的固定活动卡，用于在列表首位展示运营精选。
 
 Tab：
 
@@ -100,11 +112,12 @@ Tab：
 
 数据来源：
 
-- 读取公开 BFF `GET /api/editor/showcase/resources` 返回的全站公开 `editor_project_resource` 快照，快照包含 `authorDisplayName` / `display_name` 和 `authorPublicUserCode` / 陶泥号用于作者展示；前端只保留 `sourceType="generated"` 且 `publicShowcaseEnabled !== false` 的画布生成资源；若某条资源通过 `sourceResourceId` 指回同一 owner 的源资源且媒体引用相同，则视为拖拽画布副本，不进入精选。作者展示优先展示名，没有展示名时展示陶泥号，绝不能展示内部 `ownerUserId` / `user_id`。
-- 素材包、角色、UI、音乐、音效、视频和美宣都必须来自已存在项目资源；素材库里尚未放入任何项目的账号级素材不展示。
+- 读取公开 BFF `GET /api/editor/showcase/resources` 返回的全站公开 `editor_showcase_asset` 快照，快照包含 `showcaseId`、`assetId`、审核状态、展示状态、`showcaseCategory`、点赞数、生成成本、返还泥点、`authorDisplayName` / `display_name` 和 `authorPublicUserCode` / 陶泥号用于展示；前端按 `showcaseCategory` 放入素材包、角色、UI、音乐或美宣 Tab，只展示后端已经筛过的公开结果。作者展示优先展示名，没有展示名时展示陶泥号，绝不能展示内部 `ownerUserId` / `user_id`。
+- 素材包、角色、UI、音乐、音效、视频和美宣都必须来自用户素材库中已提交并通过审核的生成素材；不要求素材当前仍保留在某个项目资源中，已通过审核的快照在原素材删除后仍可保留公开展示。
 - 未登录用户也可读取公开精选；当没有公开画布生成资源时，不再用公开作品图片补充，只显示简洁空态。
 - 上传素材、公开作品图片、mock 资源和假组合都不进入精选。
-- 任意画布左侧素材列表中，单个素材右键打开素材菜单；原外置删除按钮移入该菜单，以文字 `删除` 展示。菜单内 `公开展示该素材` 默认勾选，取消勾选后调用 `PATCH /api/editor/project-resources/{resourceId}/showcase` 写回 `public_showcase_enabled = false`，该资源从 `陶泥儿精选` 移除。
+- 任意画布左侧素材列表中，单个素材右键打开素材菜单；原外置删除按钮移入该菜单，以文字 `删除` 展示。生成素材菜单内提供 `提交精选审核`，调用 `POST /api/editor/assets/{assetId}/showcase-submissions` 后进入 `pending` 状态；已提交、已通过或已拒绝的素材显示对应状态，不再显示默认打开的公开勾选项。
+- 后台新增纯素材查询页，读取账号级 `editor_asset` 中 `sourceType="generated"` 的素材，用于查看所有用户生成素材。该页只提供时间、用户 ID 和关键词查询，以及缩略图详情、提示词全文、生成成本、作者展示名和陶泥号查看；不提供分类筛选，也不承载审核、返还、展示开关或活动卡配置操作。
 - 不为了填满展示区创建假素材、假作者、假泥点成本或假组合关系。
 - 暂无真实数据的 Tab 保留 Tab 入口，但内容区显示简洁空态。
 
@@ -113,9 +126,9 @@ Tab：
 - `/creation` 是创作工具主页，不承接正式玩法业务真相。
 - 创作入口配置继续从 `/api/creation-entry/config` 读取。
 - 最近项目继续使用编辑器项目接口：`listEditorProjects`、`createEditorProject` 和 `/editor/canvas?projectid=xxx`。
-- 最近项目和项目页打开画布时，浏览器 history 只保留带 `projectid` 的最终画布路由。
+- 最近项目和项目页打开画布时，浏览器 history 只保留带 `projectid` 的最终画布路由；新建画布引导使用 `guide=toolbar` 一次性 query，主站九宫格直达生成器使用 `tool=<intent>` 一次性 query，画布消费后通过 `history.replaceState` 清理这两个参数。
 - 项目封面逻辑复用 `/project` 项目卡已有的画布中心缩略图算法。
-- `陶泥儿精选` 读取后端公开精选接口返回的全站公开画布生成资源；公开开关以后端 `editor_project_resource.public_showcase_enabled` 为准，前端只做展示过滤、同源同媒体副本兜底过滤和乐观交互回滚。
+- `陶泥儿精选` 读取后端公开精选接口返回的审核通过素材快照；公开事实以后端 `editor_showcase_asset.review_status`、`display_enabled` 和 `showcase_category` 为准，前端只做展示组合、Tab 归类、点赞交互和提交审核的乐观状态回滚。
 - `/creation/<play>` 的玩法工作台、草稿、生成页、结果页、发布、运行态和作品架链路保持原状。
 
 ## 路由与导航
@@ -147,6 +160,7 @@ Tab：
 
 - 新增 `CreationLandingView`。
 - 实现首屏主视觉、九大功能区、最近项目区和陶泥儿精选素材瀑布流。
+- 九大功能区卡片必须是可点击按钮；已开放卡片复用 `createEditorProject` 和画布现有生成器，不新增入口系统；暂未开放卡片复用移动端欢迎弹窗样式。
 - 桌面端复用现有平台壳层，保留上方栏和左侧导航栏。
 - 主页整体采用浅色布局，避免外站品牌文案。
 - 视觉排版参考陶土质感创作工具工作台：首屏标题居中、主按钮与社区按钮使用大号圆角胶囊尺寸，九大创作工具以 3 列大卡片展示，卡片左侧保留大号陶土感图标区域，右侧展示原有标题与描述；桌面平台一级页的顶部栏和左侧导航统一压平成单层工作台 chrome，避免外框套内框；桌面端页面结构必须先分为“左侧完整栏 / 右侧内容区”，左侧完整栏同时包含顶部品牌 Logo 和下方导航页签，右侧内容区再拆为顶部搜索、钱包、账号栏与下方主屏，不能用顶部栏的第一列假装左侧品牌区；左侧栏采用紧凑但保留图标和文字的导航胶囊，顶部搜索栏、泥点入口和账号入口都保持精简宽度，提升推荐、发现、我的、创作主页和项目页的工具感与精致度；只调整样式与布局，不改文案、搜索、登录、导航、项目创建、社区弹层、最近项目、精选素材 Tab 或数据读取逻辑。
@@ -173,6 +187,7 @@ Tab：
 - `appPageRoutes.test.ts`：覆盖 `/creation -> creation-home`，并确认现有 `/creation/<play>` 不回归。
 - `RpgEntryHomeView.recharge.test.tsx`：桌面显示“创作”“项目”，不显示“草稿”；移动端不显示“创作”和“项目”；我的页不再出现项目快捷入口。
 - `CreationLandingView.test.tsx`：覆盖首屏主视觉、九大功能、最近项目、新建入口、查看全部、未登录隐藏最近项目、素材 Tab。
+- `ImageCanvasEditorView.test.tsx`：覆盖新画布 `guide=toolbar` 显示工具栏引导并在打开生成器后关闭，以及 `tool=background-music` 等启动意图只消费一次。
 - `PlatformEntryFlowShellImpl` 相关测试：点击“创作”进入 `/creation`，点击“项目”进入 `/project`，新建项目进入 `/editor/canvas?projectid=xxx`。
 - `ProjectGalleryView.test.tsx`：封面抽取后项目封面、重命名、删除和选择模式保持通过。
 
@@ -194,6 +209,9 @@ git diff --check
 - 未登录时最近项目区不展示，点击“开始创作”弹登录。
 - 登录后显示最近项目、新建项目、最多 4 个项目和“查看全部”。
 - 点击新建项目进入 `/editor/canvas?projectid=xxx`。
+- 点击“开始创作”或项目页“新建项目”进入新画布后，工具栏上方显示 `工具栏在这里，快试着随便做点什么`，底部工具栏有高亮边框；点击任一生成入口并弹出生成面板后，引导和高亮关闭。
+- 点击“创作工具”中的游戏视觉规范、游戏角色、游戏 UI、游戏音乐、游戏场景、游戏美宣，分别创建新画布并直接拉起对应的图标规范、角色规范、UI 设计图、背景音乐、图片、游戏首图面板；URL 中的 `tool` 参数被消费后不保留。
+- 点击游戏特效、游戏功能编码、一键导出时弹出 `抱歉 / 功能还在调试中 / 暂未开放`，按钮为 `期待一下`，不创建项目。
 - 桌面导航显示“项目”，不显示“草稿”。
 - `/project` 头部不展示“返回主站”，右侧只保留选择和新建等项目管理动作。
 - 移动视口底部不显示“创作”和“项目”。

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

@@ -18,7 +18,7 @@
 - `快速编辑`
 
 `角色动画生成面板` 同步纳入本次生成类面板交互统一：点击角色图只聚焦图层，不自动弹出底部重绘或角色动画面板；点击 `生成动画` 后像新建图片一样创建 `角色动作` 画布占位，面板跟随占位底部，参考图首行、单文本无边界、参数按钮向上弹出、生成按钮明确展示泥点。
-`快速编辑` 由选中图片后的浮动工具栏显式打开，面板结构、参考图首行、提示词输入区和底部参数 / 生成区对齐其它生成类面板。
+`快速编辑` 由选中图片后的浮动工具栏显式打开，图片类素材统一进入框选区域 + 单提示词 + 模型选择的修改面板，不再恢复原来源生成器，也不展示参考图或尺寸控件。
 
 ## 统一布局
 
@@ -40,7 +40,7 @@
    - 生成视频：`你希望生成什么视频？`
 8. 多输入框面板必须保留每个字段标题和输入框边界，例如生成规范。图标素材生成不再使用多描述列表，改为复用角色形象生成面板同款单文本输入框。
 9. 生成规范下的角色规范、图标规范和自定义规范都使用同一生成类 shell：首行参考图区域、中央字段区、底部生成按钮区，不再出现缺首行参考区或单独 footer 样式。
-10. 快速编辑最多允许额外绑定 8 张参考图；原图始终作为 `/api/editor/images/edits` 的 `sourceImageSrc` 直接提交，不占用额外参考图额度，也不在参考图条里固定展示 `图x`。
+10. 图片快速编辑不展示额外参考图入口；原图或绘制了红框和序号的标注图始终作为 `/api/editor/images/edits` 的 `sourceImageSrc` 直接提交，不作为 `referenceImageSrcs`。
 11. 快速编辑打开后，画布视口应调整到原图完整展示，且面板位于原图下方并不遮挡原图；原图右侧显示竖向框选工具，支持矩形、椭圆和画笔自由框选。快速编辑进入时不默认启用框选工具，点击工具后出现选中态并保持高亮，再点同一工具取消启用；红色圈选框使用细描边。每完成一次框选，红色圈选框按完成顺序标注 `1 / 2 / 3...`，并在快速编辑提示词中追加一行 `对N号红色圈选框里的内容做以下修改：`。
 
 ## 参数交互
@@ -68,7 +68,7 @@
 - 生成图片和生成视频文本输入框紧贴参考图下方，取消旧网格预留导致的空白高度。
 - 生成规范类图片固定使用 `16:9·2K · gpt-image-2`。这三个参数在面板底部沿用可编辑参数按钮的胶囊样式展示，但控件保持禁用不可点击，不提供比例、尺寸或模型修改入口。
 - 宣发素材的 `游戏首图`、`详情五图`、`运营海报` 固定使用 `gpt-image-2`。面板底部只显示禁用态 `gpt-image-2` 模型胶囊和生成按钮，不出现 `nanobanana2` 选项；后端收到 `publication-material` 旧请求时也必须强制归一为 `gpt-image-2`。
-- 快速编辑默认从原图分辨率和模型初始化比例、尺寸和模型，但底部胶囊必须可点击修改；左下角统一显示 `x:y·xK`，右下角模型胶囊紧贴生成按钮。
+- 图片快速编辑只保留一个提示词输入框和模型选择；提示词 placeholder 为 `写下每个编号要怎么改`，提交按钮显示 `修改`，不展示比例 / 尺寸或参考图控件。
 - 不再在底部常驻展开全部可选项。
 
 ## 泥点显示
@@ -98,8 +98,9 @@
 - 图片类待生成占位尺寸必须与面板当前比例和尺寸同步：普通图片、角色形象、图标素材、UI 设计图按当前 `aspectRatio + imageSize` 计算像素尺寸；生成规范固定为 `16:9·2K`，占位为 `2048 x 1152`；宣发素材按 workflow 输出尺寸创建占位。
 - 视频待生成占位必须与面板当前比例和清晰度同步：默认 `16:9 · 480p` 为 `854 x 480`，切换比例、`720p` 或 `1080p` 后按比例和清晰度重算偶数宽度；调整参数时保持占位中心点不变。
 - 面板中用户修改比例、尺寸或清晰度后，已有空白待生成占位立即同步更新 `width / height / originalWidth / originalHeight`，且保持中心点不跳动。
-- 快速编辑点击生成后不在原图上播放生成中遮罩，而是立即创建独立 `Quick Edit Generator` 画布生成占位并播放生成中动画；该占位必须复用新建图片的 placement 避让逻辑，和已有素材 / 生成占位至少保留 32px 画布间距，不允许固定放到原图右侧后压住其它素材；生成成功后结果落在该占位框位置，失败时占位标记失败并恢复快速编辑面板。
+- 快速编辑点击修改后不创建独立 `Quick Edit Generator` 画布生成占位；当前快速编辑面板显示修改中，生成成功后结果直接覆盖源图，失败时保留当前面板并显示错误。需要新建占位的是生成图片、生成视频、重绘、去背景和角色动作等会产出新图层的入口。
 - 任何会打开画布内 composer / 面板的入口，必须在面板渲染后通过统一 overlay 可见性校正检查真实 DOM 矩形；如果面板超出画布视口，或底部工具栏 / 左下 dock 会遮住面板，就只平移当前 viewport 让面板完整进入安全区域。新增生成类入口不要在按钮 handler 里手写单独的避让偏移。
+- 画布Agent对话入口例外：画布Agent对话（右侧对话面板）触发的生成不创建"即将生成"画布占位，生成中状态由对话消息流内的条目承载（阶段提示、模型标注、进行中动画）；生成完成后结果图才按统一 placement 避让模型落画板为新图层，并在对话消息内显示缩略图。工具失败时也必须在对话消息内保留失败 generation record，而不是只弹一次性错误气泡。该例外仅限画布Agent对话入口，其余生成入口仍必须先落占位。详见 docs/【编辑器】画布Agent对话面板-2026-07-03.md。
 
 ## 画布悬浮信息
 
@@ -175,12 +176,12 @@
 - `生成音乐` 选项面板出现在音乐按钮上方，不再固定在底栏中间。
 - 规范面板比图片生成面板更紧凑，字段间距和输入高度更小，但外层 shell、首行参考图和底部按钮区必须继续对齐生成图片 / 生成角色 / 生成视频。
 - 生成规范类图片底部展示禁用态参数按钮 `16:9·2K` 和 `gpt-image-2`，视觉对齐可编辑面板的比例 / 尺寸 / 模型按钮；提交参数也固定为这三项，不出现可展开选项。
-- 快速编辑底部展示当前选择的比例 / 尺寸和模型，视觉对齐可编辑面板的比例 / 尺寸 / 模型按钮，并允许展开修改；额外参考图最多 8 张，原图作为 `sourceImageSrc` 直接编辑，不在参考图条里固定显示 `图x`。
+- 图片快速编辑底部只展示模型选择和 `修改` 按钮；原图或红框序号标注图作为 `sourceImageSrc` 直接编辑，不展示参考图条或比例 / 尺寸控件。
 - 快速编辑打开后画布自动缩放平移到原图完整展示，并让面板位于原图下方且不遮挡原图；原图右侧出现竖向矩形 / 椭圆 / 画笔自由框选按钮。进入快速编辑不默认启用框选，点击工具启用并保持高亮，再点同一工具取消；完成框选后画布红色细框显示连续序号，输入框同步追加 `对N号红色圈选框里的内容做以下修改：`。
 - 快速编辑提交前保留提示词里对原图的 `原图`、`当前图片`、`当前图` 或 `图1` 引用，不再改写成 `图N`。
-- 快速编辑提交给后端时只把原图或已绘制红框和序号的标注图作为 `sourceImageSrc`；额外参考图进入输入快照，并作为图片编辑请求的 `referenceImageSrcs` 一起提交。
+- 快速编辑提交给后端时只把原图或已绘制红框和序号的标注图作为 `sourceImageSrc`，不提交隐藏的 `referenceImageSrcs`。
 - 生成中的占位图聚焦后可用 `Delete` / `Backspace` 删除；删除后异步结果不再落回画布，也不显示额外删除 UI。
-- 快速编辑生成中的占位图同样只支持键盘 `Delete` / `Backspace` 删除，不新增 UI 删除按钮；删除后异步结果不得再落回画布。
+- 快速编辑不创建生成中占位图；提交后当前面板显示修改中，异步结果只允许回填到源图。
 - 生成视频 / 角色形象 / 角色动作 / 音效 / 背景音乐新建后，画布占位空白样式和右上角标签均与对应生成类型一致，不再统一使用图片占位 icon。
 - 新建空白待生成占位的尺寸必须和面板参数一致；图片类修改比例 / 尺寸、视频修改清晰度后，画布空白占位同步变更且保持中心点。
 - 点击角色图只选中图层并显示工具栏，不自动弹出重绘、快速编辑或角色动画面板；点击工具栏或右键菜单中的 `生成动画` 才创建角色动作占位和面板。

docs/【编辑器】画布Agent对话面板-2026-07-03.md

@@ -0,0 +1,134 @@
+# 画布Agent对话面板
+
+日期：`2026-07-03`
+
+## 定位与边界
+
+- **画布Agent对话** 是图片画布工程（`/editor/canvas`）右侧的对话式编辑器工具：用户通过自然语言调度画布已有的图片类生成与编辑能力，并可附加画布资源或素材库图片作为参考。
+- 它是画布域工具，**不承接玩法创作**、不产出玩法作品或模板，与 `CONTEXT.md` 中「表单/图片输入创作工作台」的 Avoid 边界不冲突。
+- 独立于拼图专用的 `/api/runtime/creative-agent/sessions`（该会话为 api-server 内存态、拼图领域专用，不复用）。
+
+## 能力范围（第一期）
+
+对话 Agent 可通过 function-calling 触发以下五类工具，全部复用既有计费收口接口：
+
+| 工具 | 后端接口 |
+| --- | --- |
+| 生成图片 | `POST /api/editor/images/generations` |
+| 修改图片（基于附件/画布素材） | `POST /api/editor/images/edits` |
+| 生成角色形象 | 既有角色形象生成入口对应接口 |
+| 生成图标素材 | `POST /api/editor/icon-spritesheets/generations` |
+| 生成 UI 设计图 | 既有 UI 设计图生成入口对应接口 |
+
+- 意图解析与工具编排在后端 api-server，前端只渲染状态，不承接业务规则。
+- 下面的工具选择口径属于 Agent 规划 prompt / function-calling 约束，不是侧边栏 UI 说明文案；侧边栏面板不展示这些规则解释。
+- 用户要求“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”时，规划默认选择 `generate_image`，并在 prompt 中明确要求生成规范展板，包含统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等可落地的视觉规范元素。
+- 用户要求“角色规范图”且语义是角色的规范展板、风格展板或设定板时，仍走 `generate_image`，不要误分流到 `generate_character`；只有实际生成角色立绘、角色主形象或角色视觉资产时才走 `generate_character`。用户要求多个图标素材、图集或 spritesheet 时才走 `generate_icon_spritesheet`。
+- 所有生成必须走 `execute_billable_asset_operation_with_cost` 与模型定价配置，禁止绕过定价收口。
+- 视频 / 音频 / 图层操作等其余画板功能第一期不进入对话工具面，仍走现有面板。
+
+## 当前分支落地状态
+
+- 已落地：会话元数据、OSS 消息文档、会话 CRUD、SSE 消息流、后端 LLM 工具规划、右侧对话面板、会话历史、新建 / 软删会话、停止当前 SSE 回合、附件从画布资源 / 账号素材库选择，以及五类图片工具对既有生成入口的复用。
+- 已落地：`tool_started` / `tool_completed` 事件携带 `status`；工具失败时也会写入失败 generation record，并随后发送 `stage=failed` 与 `error`，前端应保留消息内失败条目。
+- 未落地：附件弹窗末尾上传格、跨刷新异步生成恢复、external generation task 轮询回填。未落地前，对话消息状态只表示本次 SSE 回合记录，不作为后台任务队列真相。
+
+## 会话与持久化
+
+- 对话归属单个图片画布工程；每个工程有自己的会话列表，可新开会话。
+- SpacetimeDB 新表 `editor_agent_conversation` 只存会话元数据：会话 ID、projectId、ownerUserId、标题、软删标记、聊天记录 OSS 对象引用、创建/更新时间。
+- 完整消息内容存 OSS：`editor-agent/{conversationId}.json`，**会话粒度整体读写**（追加消息=重写对象），不按消息拆对象。
+- 不把对话塞进画布工程快照 payload，不在 api-server 内存中保存会话真相。
+- 会话标题：新会话默认「新对话」，首条用户消息发出后自动截取前 N 字作为标题；第一期不做手动重命名。
+- 会话删除：列表项 hover 出删除按钮 + 确认；软删（表打 deleted 标记，OSS 对象保留）。
+
+## 生成结果落画板（对现有占位规则的例外）
+
+- 对话入口触发的生成**不创建"即将生成"画布占位**（区别于其余生成面板）；生成中状态由对话消息流承载。
+- 生成完成后：结果图按统一 placement 避让模型（视口中心就近、避开现有图层、32px 间距）落画板为新图层，同时登记到默认项目素材库，并在对话消息内显示纯缩略图；前端收到 `generation_result` 后立即刷新工程快照与素材库，缩略图本身不显示名称也不承担图层跳转。
+- 消息内生成结果缩略图必须携带并优先使用 `objectKey` / `assetObjectId`，前端通过 `ResolvedAssetImage` / `/api/assets/read-url` 换签后渲染，不能把裸 `/generated-*` 私有路径直接交给 `<img>`。
+- 当前第一阶段通过既有编辑器生成 BFF 的 `canvasCompletion` 写回工程快照；刷新后异步任务恢复和轮询回填属于后续能力，不在本阶段声明为已完成。
+- 该例外已同步登记在《生成类面板Lovart统一改造方案-2026-06-17》「画布占位落点」节。
+
+## 右侧布局
+
+- 对话框与既有任务侧栏（`ImageCanvasTaskSidebarView`）**互斥展开**：展开一个自动收起另一个；各自收起后保留入口按钮。
+- 对话框与左侧素材 / 图层侧栏也互斥：打开画布 Agent 时收起左侧栏；再次打开素材、图层或任务侧栏时收起 Agent 面板。
+- 桌面端对话框固定宽约 360–400px；移动端抽屉式全宽覆盖；收起态为胶囊/圆形入口按钮。
+- 会话管理入口在对话框头部：当前会话标题 + 历史会话下拉（按更新时间倒序）+ 新建对话按钮，全部包在对话框内。
+- 收起对话框只是隐藏面板，不卸载当前会话 hook；流式回复、`生成中` 阶段和停止按钮状态必须在收起 / 重新打开之间保持一致。
+
+## 附件
+
+- 输入区 `+` 按钮打开**图片选择弹窗**（仅图片，无音视频）：
+  - 「画布」页签（默认）：展示当前工程图层引用的图片资源；
+  - 「素材库」页签：账号级素材库（复用 `ImageCanvasAssetLibrary` 数据源）；
+  - 多选 + 底部「取消 / 应用」。
+- 网格末尾上传格为后续补齐项；在上传格未落地前，对话附件只从已有画布资源和账号素材库选择。后续若从对话入口上传图片，必须复用素材库 / 画布资源登记链路，不新增对话私有图片类型。
+- 应用后附件以胶囊 chip 挂在输入框上方；发出的消息内附件渲染为纯文本胶囊 chip（名称 + 小图标），**默认无缩略图，鼠标悬浮才浮出缩略图预览**。
+- 附件领域形状：统一为画布资源 / 素材库对象引用（`resourceId` / `assetId` + 可选 `objectKey`），不存在只属于对话的第三种图；单条消息上限 9 张（前后端共同校验）。前端可携带展示用 `imageSrc` / `thumbnailSrc`，后端必须按当前工程和当前账号重新归一、校验归属与 `objectKey`。
+
+## LLM 与计费
+
+- 编排复用 `creative_agent_gpt5_client` 的 LLM 接入配置（同 provider/env，独立用途标识），画布 Agent 规划请求固定使用 VectorEngine `gpt-5.4-mini` Chat Completions；function-calling 注册五类工具。
+- 每个用户回合必须由 LLM 返回结构化计划；LLM 未配置、请求失败或返回格式不可解析时，后端写入明确错误消息，不使用本地关键词或“收到：...”回显兜底。
+- 规划 prompt 必须自动带入上一条已完成生成结果的 `latestGeneratedImage` 引用，内容只包含上一轮 generation 的 `summary` / `toolName` / `resourceId` / `objectKey` / `assetObjectId` 等轻量元数据，不把私有签名 URL 或大图内容塞进 prompt。
+- 用户使用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代或编辑上一张结果图时，LLM 默认选择 `edit_image` 并引用 `latestGeneratedImage` 作为源图；除非用户明确要求全新生成，否则不能因为本轮没有重新上传附件而降级为 `generate_image`。
+- 规划 prompt 必须显式区分“规范展板”和“实际素材产出”：规范图、视觉规范图、风格规范图、素材规范展板、角色规范图等规范展板请求走 `generate_image`，并补齐统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等要求；实际角色立绘才走 `generate_character`，多个图标素材 / 图集才走 `generate_icon_spritesheet`。
+- 画布 Agent 规划请求使用 Chat Completions、1024 `max_tokens` 和 60 秒 Agent 专用请求超时；生成图片/编辑图片仍走对应生成工具和模型计费。
+- **对话回合免费**（聊天、分析回复不扣泥点），仅 Agent 实际触发生成工具时按对应模型定价扣泥点。
+- 工具调用前后端校验泥点余额；不足时该次生成失败并在对话中以明确错误气泡告知，对话本身可继续。
+
+## Lovart 参照做/不做清单（验收标准）
+
+做（第一期）：
+
+1. 助手文本 SSE 流式输出；
+2. 阶段提示行（思考中 → 思考完成 → 生成中 → 完成/失败）；
+3. 工具/模型标注行（生成时显示模型名 + 图标）；
+4. 消息内生成结果缩略图（纯预览，不显示名称，不点击聚焦图层）；
+5. 生成中的进行中动画；
+6. 错误气泡（失败/余额不足，带原因）；
+7. 发送中断：进行中时发送按钮变「停止」，可中断当前回合（已提交的生成任务不追回，照常落画板）。
+
+不做（明确排除，防止后人补齐）：
+
+- 点赞/点踩反馈按钮；
+- 消息复制、分享/导出对话；
+- Agent 模式切换下拉（固定单一 Agent）；
+- 语音输入、@引用、多 Agent 协作；
+- Lovart 的积分/加速档位显示（泥点扣费只在生成动作上体现）。
+
+## 顺手需求
+
+- 左侧侧边栏默认隐藏：`useImageCanvasEditorChrome.ts` 中 `activeSidebarPanel` 初始值 `'assets'` → `null`；
+- 小地图默认隐藏：`isMinimapOpen` 初始值 `true` → `false`；
+- 纯默认值修改，不加 localStorage 偏好记忆。
+
+## 后端分层落位
+
+- `module-editor-agent`（新 crate）：领域规则——会话/消息校验、状态机、附件上限、软删规则、工具清单领域定义；纯逻辑无 IO。
+- `spacetime-module`：新表 `editor_agent_conversation` + procedure；同步 `migration.rs`、表目录、生成绑定，运行 `npm run check:spacetime-schema`。
+- `spacetime-client`：facade 读写方法。
+- `api-server`：
+  - `GET/POST /api/editor/projects/{projectId}/agent-conversations`（列表/新建）；
+  - `GET/DELETE /api/editor/agent-conversations/{conversationId}`（详情/软删）；
+  - `POST /api/editor/agent-conversations/{conversationId}/messages/stream`（SSE）；
+  - Agent 编排（function-calling 循环、工具内部调既有生成执行链路）放 api-server 编排层，独立文件，不复用 `creative_agent.rs` 内存会话。
+- `shared-contracts` + `packages/shared`：新 `editorAgent` DTO 与 SSE 事件契约（`stage`、`message_delta`、`tool_started`、`tool_completed`、`generation_result`、`error`、`done`）。
+
+## 实施顺序
+
+1. 契约与领域规则（shared-contracts / packages/shared + module-editor-agent）；
+2. 存储层（spacetime-module 表 + procedure + migration + spacetime-client + schema check）；
+3. api-server 会话 CRUD + 消息 OSS 读写 + SSE 回显桩（不接 LLM，先保证会话链路端到端真实落库）；
+4. 前端最小纵切（对话框、会话管理、消息流、附件弹窗、侧边栏/小地图默认值）——可与 3 并行：3 只碰 `server-rs/`，4 只碰 `src/` 且先以契约 mock 客户端联调，汇合点在 4 末接真实 API；
+5. LLM 编排 + 五类工具接入 + 生成落画板 + 停止/错误态（替换回显桩这一个点）；
+6. 验证与文档：定向测试、类型检查、`npm run check:encoding`、`git diff --check`、`npm run check:spacetime-schema`、api-server smoke `/healthz`；同步 `CONTEXT.md` 与相关文档。
+
+## 第一阶段验收补充
+
+- 打开画布 Agent 后，任务侧栏和左侧素材 / 图层面板应关闭；再次打开任务侧栏或素材 / 图层面板时，Agent 面板应关闭。
+- 发送消息时先本地追加用户消息，再消费 SSE 增量；停止按钮只中断当前 SSE 回合，不追回已经提交的生成工具调用。
+- Agent 消息内生成结果缩略图只用于预览，不显示名称，也不点击跳转图层；收到 `generation_result` 时统一刷新工程快照和素材库。
+- 对话内容可被用户选中复制；用户从输入框或对话内容点击回画布图层 / 生成器时，焦点应回到画布对象，Backspace / Delete 等画布快捷键继续生效。