接入画板生成视频功能

新增画板底部生成视频入口、Lovart 风格面板、视频图层渲染与元数据展示。接入 /api/editor/videos/generations 契约与后端 Ark/VectorEngine 视频任务链路。统一编辑器生成类泥点配置，并补充 UI 设计图、参考图与生成面板结构测试。更新编辑器技术方案、生成类面板方案和 Hermes 共享决策/踩坑记录。
2026-06-17 20:47:27 +08:00
parent d1cd300695
commit b2fd5574db
39 changed files with 3390 additions and 238 deletions
--- a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md
+++ b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md
@@ -12,13 +12,13 @@
 - 编辑器左侧为图片素材栏，可展开 / 收起；移动端优先保持素材栏可折叠。
 - 中央画布支持背景拖拽平移、滚轮缩放、缩放百分比菜单、显示所有元素和固定比例缩放。
 - 画布左下角提供 Lovart 式状态控件：背景色圆点、素材 / 图层入口、小地图开关；小地图显示图层缩略分布和当前视口框，点击小地图执行显示所有元素。
- 画布中的图片可展示、悬浮显示图片 Resolution 尺寸与边框，点击后在图片上方显示浮动工具栏；图片不再维护独立展示 `Size` 字段，画布显示宽高统一取 `originalWidth/originalHeight`（图片信息中的 `Resolution`）。
+- 画布中的图片可展示、悬浮显示图片 Resolution 尺寸与边框，点击后在图片上方显示浮动工具栏；图片右上角素材类型标签、查看信息按钮和悬浮尺寸标签在画布缩小时必须按 viewport 反向缩放，保持屏幕可读尺寸；查看信息按钮使用圆形 `i` 图标，不使用中括号或花括号样式。图片不再维护独立展示 `Size` 字段，画布显示宽高统一取 `originalWidth/originalHeight`（图片信息中的 `Resolution`）。
 - 默认工具为选择模式；底部工具栏采用 AI 画布工作流工具组：选择、抓手、上传、生成、局部修改 / 蒙版、文字、形状 / 标注、导出。
 - 鼠标中键拖拽始终平移画布；长按 Space 临时进入抓手模式，松开后恢复原工具。
 - 图片拖拽时显示水平 / 垂直吸附参考线，吸附到其它图层或画板的边缘与中心线。
 - 生成资源右上角显示元数据按钮，点击打开独立元数据窗口。图片信息页不展示后端组装后的生图 Prompt，也不提供复制 Prompt；只展示该图片生成时用户在面板里提交的输入快照，包括普通生成提示词、规范表单字段、角色设定、图标素材描述、修改要求，以及角色形象规范 / 常规参考图 / 图标素材规范 / 修改参考图等参考图卡片。旧数据或上传图片没有输入快照时显示 `-`，禁止回退展示内部 Prompt。
 - 对生成资源执行修改时，在右侧创建新的生成结果图层，并自动调整视图显示原图和新图。
- 图片生成 / 修改统一经 api-server BFF 接入 VectorEngine `gpt-image-2`：纯文本生成走 `/api/editor/images/generations`，基于当前生成图的修改走 `/api/editor/images/edits`。纯文本生成入口采用 Lovart 式画布内占位图 + 锚定生成输入框：点击生成工具后先在画布中心创建选中的灰色占位框，输入框跟随占位框显示；待生成、生成中和失败后保留的占位图都必须继续支持拖动，生成完成时真实生成图落在最新占位框位置，输入框继续跟随新生成图；点击所有图片生成入口并确认请求开始后，必须隐藏对应设置面板，只保留画布内占位图或原图预览，并在预览上显示 Lovart 式生成中遮罩，避免“面板仍占屏”或“预览一起消失”。快速编辑和修改图片在调用后端前必须把当前图层图片源读取为图片 Data URL，来源可以是本地上传 Data URL、站内 public 图片、历史 `/generated-*` 路径或可读取的 OSS generated URL；后端仍只接收图片 Data URL，不把普通 URL 直接透传到 VectorEngine edits。前端不持有 provider 密钥；上游失败或配置缺失时恢复当前生成设置面板展示失败，不创建 mock 成功图。
+- 图片生成 / 修改统一经 api-server BFF 接入 VectorEngine。普通生成、生成规范和快速编辑保留既有 `gpt-image-2` 路径；`生成角色形象` 与 `生成图标素材` 支持 `nanobanana2`（`gemini-3.1-flash-image-preview`）和 `gpt-image-2`，默认 `nanobanana2`，并在两类面板之间沿用用户上次选择的模型。`nanobanana2` 走 `/v1beta/models/{model}:generateContent`，请求体写入 `generationConfig.imageConfig.aspectRatio/imageSize`；`gpt-image-2` 走 `/v1/images/generations` 或 `/v1/images/edits`，请求体按 VectorEngine 文档映射 `size`。纯文本生成走 `/api/editor/images/generations`，基于当前生成图的修改走 `/api/editor/images/edits`。`生成视频` 走 `/api/editor/videos/generations`，支持 Seedance 2.0 / Seedance 2.0 Fast / Kling 3.0 / Kling 3.0 Omni / Veo 3.1 / Veo 3.1 Fast，首期固定文字转视频、`16:9`、标准模式、静音，生成结果以视频图层加入画布。纯文本生成入口采用 Lovart 式画布内占位图 + 锚定生成输入框：点击生成工具后先在画布中心创建选中的灰色占位框，输入框跟随占位框显示；待生成、生成中和失败后保留的占位图都必须继续支持拖动，生成完成时真实生成图或视频落在最新占位框位置，输入框继续跟随新生成图层；占位图失焦时隐藏高亮边框、左上角生成器名称和右上角原始尺寸，重新聚焦时再显示，且名称 / 尺寸在画布缩小时按 viewport 反向缩放保持屏幕尺寸稳定；点击所有图片 / 视频生成入口并确认请求开始后，必须隐藏对应设置面板，只保留画布内占位图或原图预览，并在预览上显示 Lovart 式生成中遮罩，避免“面板仍占屏”或“预览一起消失”。快速编辑和修改图片在调用后端前必须把当前图层图片源读取为图片 Data URL，来源可以是本地上传 Data URL、站内 public 图片、历史 `/generated-*` 路径或可读取的 OSS generated URL；后端仍只接收图片 Data URL，不把普通 URL 直接透传到 VectorEngine edits。前端不持有 provider 密钥；上游失败或配置缺失时恢复当前生成设置面板展示失败，不创建 mock 成功图。
 - 底部生成类按钮每次点击都必须创建独立的画布生成对象；新建规范、角色形象或图标素材时，只切换当前编辑面板，不得销毁此前尚未生成或已生成后的其它生成对象状态。归档为非当前编辑对象的生成占位仍可拖动、删除和等待异步完成，完成 / 失败回写必须按生成对象 ID 读取最新占位状态，不能使用提交瞬间的旧快照。

 ## 交互规则
@@ -62,8 +62,10 @@
 - `POST /api/editor/assets`：批量或单个创建账号级素材，支持按钮上传和拖拽上传后的 data URL / 后续 OSS 元数据。
 - `PATCH /api/editor/assets/{assetId}`：重命名素材或移动素材到文件夹。
 - `DELETE /api/editor/assets/{assetId}`：删除素材。已放入画布的 project resource 不被级联删除，避免旧画布丢图。
- `POST /api/editor/images/generations`：按提示词调用 VectorEngine `gpt-image-2` 生成图片；携带参考图的快速编辑也走该接口，前端必须把参考图源预读成图片 Data URL 后放入 `referenceImageSrcs`；接口返回 data URL、尺寸、prompt、model、provider 和 taskId。
+- `POST /api/editor/images/generations`：按提示词调用 VectorEngine 生成图片；角色生成可携带 `model`、`aspectRatio`、`imageSize` 和 `referenceImageSrcs`。`nanobanana2` 参考图作为 `inline_data` 进入 `generateContent`，`gpt-image-2` 参考图进入 edits。携带参考图的快速编辑也走该接口，前端必须把参考图源预读成图片 Data URL 后放入 `referenceImageSrcs`；接口返回 data URL、尺寸、prompt、model、provider 和 taskId。
+- `POST /api/editor/icon-spritesheets/generations`：按图标素材规范图和素材描述数组生成 spritesheet，再由后端切分为独立透明图标。请求支持 `model`、`aspectRatio`、`imageSize`；`nanobanana2` 走原生 `generateContent` 并写入 `generationConfig.imageConfig.aspectRatio/imageSize`，`0.5K` 传 `"512"`；`gpt-image-2` 走 `/v1/images/edits`，后端把 UI 尺寸归一为文档支持的 `1024x1024`、`1024x1536`、`1536x1024`、`2048x2048`、`2048x1152` 等 `size` 字符串。
 - `POST /api/editor/images/edits`：按提示词和当前图片 Data URL 调用 VectorEngine edits，返回新的生成图片元数据。
+- `POST /api/editor/videos/generations`：按视频描述、模型、比例、时长、分辨率、模式、声音和泥点价格生成视频。请求模型支持 `seedance2.0`、`seedance2.0-fast`、`kling3.0`、`kling3.0-omni`、`veo3.1`、`veo3.1-fast`；后端复用 Ark / VectorEngine content generation task 轮询链路，下载最终视频并持久化到 OSS，返回 `videoSrc`、尺寸、prompt、model、provider、taskId、durationSeconds、resolution 和 `priceMudPoints`。

 所有写接口都必须校验 Bearer 登录态和 owner；接口只返回当前用户有权读取的工程与资源。

--- a/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md
+++ b/docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md
@@ -0,0 +1,101 @@
+# 生成类面板 Lovart 统一改造方案
+
+日期：`2026-06-17`
+
+## 范围
+
+图片画布编辑器内以下生成类面板统一对齐 Lovart 式极简创作工具风格：
+
+- `生成图片`
+- `生成规范`
+- `生成角色形象`
+- `生成图标素材`
+- `生成UI设计图`
+- `生成视频`
+- `角色动画生成面板`
+
+## 统一布局
+
+1. 参考图区域永远位于面板第一行。
+2. 参考图使用统一参考图卡片：
+   - 普通参考图：灰蓝色图片图标。
+   - 规范参考图：紫色剪贴板图标。
+   - 图标素材规范：绿色图标图标。
+   - UI 图标规范：琥珀色图标图标。
+   - 视频参考图 / 角色视频源图：深色视频或角色图标。
+3. 参考图卡片尽量少文字；必要文字写在图标块内或短标签内，不写规则说明。
+4. 普通参考图支持连续追加：已有图缩略图后始终保留一个 `+` 入口。点击入口只弹出“从画布中选择 / 上传图片”来源选项，不再直接打开系统文件选择器；生成图片、生成视频、角色常规参考图等同类参考图入口都遵循同一交互。
+5. 单文本输入面板不显示文本框标题，用问题式 placeholder：
+   - 生成图片：`今天想生成什么画面？`
+   - 生成角色：`你希望角色如何设计？`
+   - 生成 UI：`你希望这个 UI 长什么样？`
+   - 生成视频：`你希望生成什么视频？`
+   - 角色动画：`你希望角色做什么动作？`
+6. 多输入框面板必须保留每个字段标题和输入框边界，例如生成规范、图标素材多描述。
+7. 生成规范下的角色形象规范、UI素材规范、图标素材规范和自定义规范都使用同一生成类 shell：首行参考图区域、中央字段区、底部生成按钮区，不再出现缺首行参考区或单独 footer 样式。
+
+## 参数交互
+
+画面比例、大小尺寸、模型、分辨率、时长等生成参数统一为 Lovart 式底部胶囊按钮：
+
+```text
+左下：[比例 · 尺寸 ˄]          右下：[模型 ˄] [生成 · 图标 12]
+```
+
+- 面板内不显示 `画面比例`、`大小尺寸`、`模型` 等字段标题，只显示当前选择值。
+- 图片类面板把画面比例和大小尺寸合并成一个左下角选项框；视频 / 角色动画把比例、时长、清晰度合并成一个左下角选项框。
+- 模型选项框和生成按钮位于右下角。
+- 点击后在父级生成面板内向上弹出子面板；父级面板隐藏或销毁时，子面板同步销毁。
+- 子面板展示时，点击父级面板中除当前子面板和选项触发器以外的任意区域即可收起，不额外显示右上角关闭按钮。
+- 弹出面板内可分组展示字段，点击某个选项只更新当前字段和选中样式，不关闭弹出面板，方便连续修改。
+- 模型子面板每行固定一个模型，不用方框包裹模型名；模型名不换行，前置对应模型类型图标，选中项在模型名后用对号标记。
+- 比例选项卡片内展示对应比例的线框。
+- 父级面板、底部选项框、弹出子面板字号保持一致。
+- 底部组合值使用 `·` 分隔，例如 `16:9 · 4秒 · 480p`。
+- 底部参数热区与生成按钮等高，默认不显示阴影；悬停显示轻量阴影；箭头默认向下，展开后旋转向上。
+- 生成图片和生成视频文本输入框紧贴参考图下方，取消旧网格预留导致的空白高度。
+- 不再在底部常驻展开全部可选项。
+
+## 泥点显示
+
+- 本次消耗泥点必须显示在生成按钮内部。
+- `泥点` 文本不在 UI 中显示，改用图标 + 数值，例如 `生成  ✦ 12`。
+- 泥点配置统一收口到 `api-server` 的编辑器生成配置模块；前端只保留与后端配置同名的展示兜底，后续可接接口动态下发。
+
+## 第一版计费配置
+
+```text
+生成图片：12 泥点
+生成规范：5 泥点
+生成角色形象：12 泥点
+生成图标素材：12 泥点
+生成UI设计图：12 泥点
+生成视频：480p 每秒 10 泥点，720p 每秒 20 泥点
+角色动画：480p 每秒 10 泥点，720p 每秒 20 泥点
+```
+
+## 生成视频模型与接口
+
+- 底部 `生成视频` 面板提交到 `POST /api/editor/videos/generations`。
+- 首期只开放文字生成视频，固定 `16:9`、静音、标准模式；结果作为 `mediaType="video"`、`assetKind="video"` 的视频图层加入画布。
+- 支持模型：
+  - `seedance2.0`
+  - `seedance2.0-fast`
+  - `kling3.0`
+  - `kling3.0-omni`
+- 不展示 Veo 模型入口。
+  - `veo3.1`
+  - `veo3.1-fast`
+- 后端复用现有 Ark / VectorEngine content generation task 轮询链路，并把生成视频持久化到 OSS；缺少 `ARK_CHARACTER_VIDEO_BASE_URL` 或 `ARK_CHARACTER_VIDEO_API_KEY` 时 fail-closed 返回配置错误。
+
+## 验收
+
+- 所有生成类面板首行都是参考图区域。
+- 比例 / 尺寸 / 模型不再平铺全部选项；比例与尺寸合并为左下角当前值按钮，模型与生成按钮位于右下角。
+- 单文本输入面板不显示字段标题，placeholder 是问题式文案。
+- 多文本输入面板字段标题和边界仍清晰。
+- 生成按钮内能看到图标化泥点消耗数值。
+- 弹出选项面板点击选项后保持打开，可连续修改多个字段。
+- 规范面板比图片生成面板更紧凑，字段间距和输入高度更小，但外层 shell、首行参考图和底部按钮区必须继续对齐生成图片 / 生成角色 / 生成视频。
+- 后端存在独立编辑器生成计费配置文件，角色动画价格校验使用该配置。
+- 生成视频结果以视频图层加入画布，画布媒体元素标记为 `画布视频：生成视频 N`。
--- a/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md
+++ b/docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md
@@ -0,0 +1,53 @@
+# 【编辑器】画板UI设计图生成入口设计
+
+日期：2026-06-17
+
+## 入口与画布状态
+
+- 底部 AI 画布工具栏新增 `生成UI设计图`。
+- 点击后立即在画布中新建 `UI设计图生成占位图`，不复用普通新建图片的空白样式。
+- 占位图默认 16:9 展示，生成成功后替换为 `assetKind: "ui-design"` 的画布图层。
+
+## 生成面板
+
+- 占位图下方打开独立生成面板，标题为 `生成UI设计图`。
+- 面板复用普通 `生成图片` / `生成角色形象` / `生成视频` 的生成类 shell：首行参考图区域、中央单文本输入、底部参数与生成按钮区。
+- 面板第一个模块为 `图标素材规范`，并放在首行参考图区域。
+- 点击图标素材规范卡片后，在卡片旁弹出来源菜单：
+  - `从画布中选择`
+  - `新建图标素材规范`
+  - `上传图片`
+- `从画布中选择` 只接受 `assetKind: "icon-spec"` 的图层；普通图片、其他类别图层和不携带标签的图片不绑定。
+- `新建图标素材规范` 复用现有图标素材规范生成表单。
+- `上传图片` 仅绑定到当前 UI 设计面板的图标素材规范参考，不自动添加为画布图层。
+
+## 生成参数
+
+- 支持自定义画面比例和大小尺寸。
+- 模型固定为 `gpt-image-2`，面板不提供切换到其他模型的能力。
+- 默认画面比例为 `16:9`，默认大小为 `1K`。
+
+## 提示词契约
+
+后端收到 `kind: "ui-design"` 时固定拼接：
+
+```text
+生成玩法UI原型图
+【用户输入】<用户输入>
+```
+
+如果用户设置了图标素材规范参考图，则追加：
+
+```text
+参考图1为图标素材规范，请在UI图标、按钮符号、描边、材质、圆角、阴影和状态层级上严格遵循参考图1的素材规范。
+```
+
+生成请求固定使用 `gpt-image-2`。有参考图时走图片编辑请求；无参考图时走图片生成请求。
+
+## 验收点
+
+- 点击 `生成UI设计图` 后出现 UI 设计占位图和独立生成面板。
+- 面板第一模块为图标素材规范，来源菜单包含三个动作。
+- 从画布选择时只能绑定图标素材规范图片。
+- 请求参数包含 `kind: "ui-design"`、`model: "gpt-image-2"`、比例、大小与可选参考图。
+- 生成图层信息面板展示 `用户输入` 与 `图标素材规范`。
--- a/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md
+++ b/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md
@@ -39,11 +39,13 @@
 - 请求字段：
  - `referenceImageSrc`：图标素材规范 Data URL。
  - `iconDescriptions`：过滤空文本后的图标描述数组，`1..100`。
-  - `model`：固定 `gemini-3.1-flash-image-preview`。
- 后端根据图标数量选择尺寸：
-  - `<=25` 个：`512x512`，即 0.5K 1:1。
-  - `>25` 个：`1024x1024`，即 1K 1:1。
- 后端使用 VectorEngine 图片编辑接口，把 `referenceImageSrc` 作为参考图 1，模型固定传 `gemini-3.1-flash-image-preview`。
+  - `model`：支持 `gemini-3.1-flash-image-preview`（UI 显示 `nanobanana2`）和 `gpt-image-2`，默认 `nanobanana2`。
+  - `aspectRatio`：按 `x:y` 展示，选项跟随模型。
+  - `imageSize`：按 `0.5K / 1K / 2K` 展示，选项跟随模型。
+- 模型与尺寸选项：
+  - `nanobanana2`：比例 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`；大小 `0.5K / 1K / 2K`。后端走 `/v1beta/models/{model}:generateContent`，把图标素材规范图作为 `inline_data`，并把 `aspectRatio` / `imageSize` 写入 `generationConfig.imageConfig`；`0.5K` 按 VectorEngine 文档传 `"512"`。
+  - `gpt-image-2`：比例 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`；大小 `1K / 2K`。后端走 `/v1/images/edits`，把图标素材规范图作为 multipart `image`，按 `size` 映射：`1K 1:1 -> 1024x1024`、`1K 2:3/9:16 -> 1024x1536`、`1K 3:2/16:9 -> 1536x1024`、`2K 1:1 -> 2048x2048`、`2K 3:2/16:9 -> 2048x1152`；文档未列出 `2K` 竖版，`2K 2:3/9:16` 后端回落到 `1024x1536`。
+- 用户在角色或图标素材面板中切换过模型后，下一次打开这两类面板继续使用上次模型。
 - Prompt 固定为：

 ```text
@@ -72,6 +74,6 @@
 - 点击 `生成图标素材` 后出现一叠空白图标占位和图标素材面板。
 - `图标素材规范 -> 从画布中选择` 只能选择图标素材规范图，点击普通图片或角色规范图不会绑定。
 - 默认 6 个素材描述会进入 prompt；新增描述最多到 100 个。
- `<=25` 个描述提交时后端请求尺寸为 `512x512`；`>25` 个描述提交时后端请求尺寸为 `1024x1024`。
- VectorEngine 请求体的 `model` 为 `gemini-3.1-flash-image-preview`。
+- 默认打开图标素材面板时选中 `nanobanana2 / 1:1 / 1K`；模型切换后，角色和图标素材面板之间沿用上次选择的模型。
+- 图标素材生成请求必须带 `model`、`aspectRatio` 和 `imageSize`；`nanobanana2` 请求体必须包含 `generationConfig.imageConfig.aspectRatio/imageSize`，`gpt-image-2` 请求必须包含文档映射后的 `size`。
 - 生成成功后画布出现按描述命名的多个透明图标素材图层，图层之间不重叠。
--- a/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md
+++ b/docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md
@@ -32,6 +32,16 @@
 4. 左下角展示画面比例和大小选择按钮。
 5. 右下角展示模型选择和生成按钮。

+## 普通生成面板视觉口径
+
+普通 `生成图片`、`生成角色形象`、`生成UI设计图` 等锚定在图片下方的生成面板统一采用 Lovart 式极简创作工具风格：
+
+- PC 端优先保持面板锚定在占位图或目标图片下方，宽度允许比旧版略宽，避免比例、尺寸、模型和生成按钮挤成一行难以阅读。
+- 面板只展示创作必需输入：参考图、提示词、比例、大小、模型和生成按钮；不在 UI 内铺说明性规则文案。
+- 视觉以白色半透明面板、轻边框、低阴影、低饱和选项按钮和清晰黑色主按钮为主，减少游戏式厚重装饰，贴近 Lovart 的极简画布工具感。
+- 普通 `生成图片` 面板的比例、大小和模型必须使用真实选项按钮，不再使用占位式参数按钮或弹出“建设中”提示。
+- 移动端仍可固定在底部工具栏上方并允许内部滚动，保证不遮挡底部 AI 工具栏和画布操作。
+
 ## 生成与参考图契约

 - 前端提交角色生成时，使用 `POST /api/editor/images/generations`。
@@ -39,8 +49,14 @@
 - 角色形象规范与常规参考图作为 `referenceImageSrcs` 传入，顺序固定为：
  1. 角色形象规范图。
  2. 常规参考图列表。
- 当前请求尺寸沿用编辑器普通生成默认值；比例和大小按钮先复用现有占位交互。
- 后端如果收到参考图，则走带多参考图的图片编辑/参考图生成链路；没有参考图时走纯文本生成链路。
+- 请求同时提交 `model`、`aspectRatio` 和 `imageSize`：
+  - `model` 支持 `gemini-3.1-flash-image-preview`（UI 显示 `nanobanana2`）和 `gpt-image-2`，默认 `nanobanana2`。
+  - 用户在角色或图标素材面板中切换过模型后，下一次打开这两类面板继续使用上次模型。
+  - 比例按 `x:y` 展示；大小按 `0.5K / 1K / 2K` 展示。
+- 尺寸选项来源以 VectorEngine 接入文档为准：
+  - `nanobanana2`：比例 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`；大小 `0.5K / 1K / 2K`。后端走 `/v1beta/models/{model}:generateContent`，把比例写入 `generationConfig.imageConfig.aspectRatio`，把大小写入 `generationConfig.imageConfig.imageSize`；其中 `0.5K` 按文档传 `"512"`。
+  - `gpt-image-2`：比例 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`；大小 `1K / 2K`。后端走 `/v1/images/generations` 或 `/v1/images/edits`，按文档尺寸映射：`1K 1:1 -> 1024x1024`、`1K 2:3/9:16 -> 1024x1536`、`1K 3:2/16:9 -> 1536x1024`、`2K 1:1 -> 2048x2048`、`2K 3:2/16:9 -> 2048x1152`；文档未列出 `2K` 竖版，`2K 2:3/9:16` 后端回落到 `1024x1536`。
+- 后端如果收到参考图，`nanobanana2` 把参考图作为 `inline_data` 传入原生 `generateContent`；`gpt-image-2` 走带多参考图的图片编辑链路。没有参考图时按所选模型走纯文本生成链路。
 - `kind = "character"` 时，后端不直接把前端文本当完整生图提示词，而是把文本作为 `角色设定` 填入固定提示词骨架：

 ```text
@@ -52,11 +68,18 @@

 ## 生成规范参考图

- `生成规范 -> 角色形象规范`、`UI素材规范`、`自定义规范` 的设定面板支持上传 1 张参考图；`图标素材规范` 继续使用后续图标素材生成面板里的专用规范图链路，不在这里重复新增入口。
+- `生成规范 -> 角色形象规范`、`UI素材规范`、`图标素材规范`、`自定义规范` 的设定面板都支持上传 1 张参考图，并统一放在面板首行参考图区域。
 - 参考图入口只展示字段标题、缩略图或上传图标、文件名，不把参考规则说明铺在 UI 上。
 - 提交生成规范时，若存在参考图，前端必须把参考图作为 `referenceImageSrcs[0]` 提交到 `/api/editor/images/generations`，并在生图提示词开头自动追加“参考图生成规范”语义：要求模型参考图 1 的构图、风格、材质、色彩、形状语言和视觉层级生成规范图，但不要复制参考图中的文字、水印或无关背景。
 - 生成结果的信息快照必须记录该参考图，标题为 `参考图`，便于后续在图片信息面板回看生成输入。

+## 新建生成图落点避让
+
+- 普通生成、生成规范、生成角色形象和生成图标素材在创建画布占位图前，必须先检测占位图矩形是否与画布中已有可见图片图层或已有生成占位图重叠。
+- 若当前屏幕中心对应的画板位置可用，则占位图仍创建在该中心；若重叠，则以当前屏幕中心对应画板位置为原点，按距离由近到远查找不重叠候选位置。
+- 候选占位图与相邻图片或占位图之间保留 `32px` 画板间距；隐藏图层不阻挡新建落点。
+- 选中落点后保持当前缩放比例不变，将视口中心移动到新占位图中心，确保用户创建后立即看到新图和生成面板。
+
 ## 图片信息展示

 - 图片信息弹窗标题固定为 `图片信息`，不拼接图片 / 图层名称。
@@ -78,13 +101,16 @@
 - `角色形象规范` 与 `上传常规参考图` 入口是带预览视觉块的参考图卡片，不是无样式文字。
 - `从画布中选择` 后点击已有画布图片可绑定为角色形象规范，`Esc` 可退出点选状态。
 - 上传常规参考图后缩略图右下角显示序号。
- 输入角色设定并生成时，请求包含 `kind: "character"`、角色设定 prompt 和参考图数组。
+- 输入角色设定并生成时，请求包含 `kind: "character"`、角色设定 prompt、参考图数组、`model`、`aspectRatio` 和 `imageSize`。
+- 默认打开角色生成面板时选中 `nanobanana2 / 1:1 / 1K`；切换到 `gpt-image-2` 后再次打开角色或图标素材面板应沿用该模型。
 - 生成成功后在占位图位置创建 `assetKind: "character"` 图层，右上角显示 `角色` 标签，布局保存包含该字段。

 ## 当前落地记录

 - 前端画板已接入 `生成角色形象` 底部入口、角色占位图、角色面板、画布点选规范图、上传规范图、上传常规参考图和序号角标。
+- 画布生成类入口已统一接入新建占位图落点避让：优先使用当前屏幕中心对应画板位置，重叠时自动选择最近的不重叠位置，并将视口中心移动到新占位图。
 - 角色生成提交统一走 `/api/editor/images/generations`，按 `角色形象规范 -> 常规参考图` 顺序传 `referenceImageSrcs`，并写入 `assetKind: "character"`。
+- 角色和图标素材生成已接入 `nanobanana2` / `gpt-image-2` 模型切换、上次模型记忆，以及按模型归一的比例 / 大小尺寸；`nanobanana2` 使用原生 `generateContent` 的 `imageConfig.aspectRatio/imageSize`，`gpt-image-2` 使用文档列出的 `size` 字符串。
 - 角色生成后端已按固定 prompt 骨架补入 `角色设定`，并在生成成功后自动执行绿幕去背、写入 `generated-character-drafts/editor/character-images/<taskId>/image.png` 路径下的 OSS 私有对象，返回的 `objectKey` / `assetObjectId` 会随画板资源记录保存。
 - `Esc` 只退出角色规范画布点选状态，不关闭角色生成面板。
 - 已补充回归测试覆盖角色形象生成、点选退出、角色动画入口隔离和快速编辑入口。