文生图参考图弹窗重构设计

背景

当前文生图中的“参考图”弹窗已经接入三段式内部链路：

1. ReferenceSpec 提取
2. PromptDraft 生成或迁移
3. VariableizedPrompt 抽取

但当前交互仍存在几个明显问题：

• 弹窗承担了过多“临时补救”职责，例如应用后撤销，导致状态复杂度偏高。
• “检测到当前提示词”被放在“怎么使用这张参考图”内部，信息层级不清晰。
• 模式命名偏实现视角，用户第一眼难以理解差异。
• 参考图预览区域占用空间过大，挤压了真正重要的结果编辑区。
• 变量区缺少明确产品边界，当前结果更像调试信息而不是可确认的产物。
• 当前变量提取策略过于宽松，不适合参考图迁移场景，容易抽出过多变量。

本次重构目标不是新增更强的自动能力，而是把参考图弹窗整理成一个更清晰、更可理解、更可确认的前置改造流程。

目标

产品目标

• 让用户能快速理解“这张参考图会怎么影响当前提示词”。
• 保持现有 文生图 / 图生图 一级入口和模板下拉不变。
• 让“参考图”成为清晰的前置改造工具，而不是半自动编辑器。
• 保留 prompt 与变量的人工微调能力，但删除不必要的状态补丁和联动复杂度。

交互目标

• 让弹窗第一眼就能看懂当前上下文、可选模式和最终结果。
• 把视觉重心从“参考图展示”转移到“生成后的提示词”和“变量预览”。
• 让模式命名直接对应用户心智，而不是内部实现术语。

技术目标

• 删除撤销链路及其相关状态。
• 保持三段式架构不变，只收敛 UI 结构、文案与变量策略。
• 把变量数量稳定控制在 5 个以内，并保证优先级一致。

非目标

• 不修改图生图工作区。
• 不新增收藏、URL、Garden 导入等参考来源。
• 不引入 prompt 与变量的实时双向同步。
• 不把参考图弹窗演化为 JSON 树编辑器或多步向导。
• 不改变现有优化按钮、模板选择、主工作区链路。

设计原则

1. 参考图是来源，不是主角

参考图用于确认风格来源是否正确，不应该占据大块主编辑空间。默认展示应为缩略图，而不是大图卡片。

2. 先交代上下文，再让用户做选择

“检测到当前提示词”属于系统当前上下文，应先独立告知用户，再让用户选择如何使用参考图。

3. 模式命名必须是用户语言

模式名称应直接表达结果差异，而不是实现逻辑。用户要看懂“风格迁移”和“复刻图片”，而不是推断“保留当前内容”和“按参考图生成”的含义。

4. 结果区是弹窗的视觉中心

弹窗应把主要空间分配给最终会被应用的两类结果：

• 生成后的提示词
• 提取到的变量

5. 简化优先于强一致

本期保留“初次生成时自动抽变量，之后允许手动改 prompt 和变量值”的弱一致策略，不引入自动重算或手动同步动作。

方案比较

方案 A：纯纵向堆叠

按顺序纵向排列所有内容块：

• 参考图
• 检测到当前提示词
• 使用方式
• 生成后的提示词
• 变量预览

优点：

• 实现简单
• 信息顺序线性

缺点：

• 弹窗过长
• 重点区域不够突出
• prompt 与变量缺少工作台感

方案 B：完全左右双栏

整个弹窗采用左右布局，把上下文和结果一起放入双栏。

优点：

• 可在桌面端压缩高度
• 对比感更强

缺点：

• 信息关系变复杂
• 辅助信息和核心结果抢空间
• 响应式和主题适配更容易出问题

方案 C：上轻下重的混合布局

顶部为轻量上下文区，中部为模式选择，底部为结果工作区双栏。

结构为：

• 顶部：参考图 缩略图卡 + 检测到当前提示词 摘要卡
• 中部：风格迁移 / 复刻图片 两张模式卡
• 底部：左侧 生成后的提示词，右侧 提取到的变量

优点：

• 信息优先级清晰
• 结果区获得足够空间
• 比纯双栏更稳，比纯纵向更紧凑

缺点：

• 需要对弹窗结构和样式做一次性整理

推荐方案

采用方案 C。它最符合当前产品定位，也最容易沿用 Naive UI 和现有弹窗结构做稳定落地。

信息架构

1. 参考图

作为第一块区域展示，采用缩略图样式：

• 左侧固定尺寸缩略图，建议 96x96 或 112x112
• 右侧展示文件名、说明文字和“上传/更换图片”按钮
• 默认不展示大图，不占用额外垂直空间
• 点击缩略图时可沿用现有图片预览能力，但不作为默认状态

说明文案继续保留：

• 仅支持本地 PNG/JPEG，最大 10MB

2. 检测到当前提示词

仅在当前原始提示词非空时显示，作为独立信息卡片放在参考图区域之后。

展示规则：

• 标题：检测到当前提示词
• 只展示前 2 到 3 行摘要
• 超出内容省略，不展示完整正文
• 目的仅为帮助用户判断是否保留当前内容，避免把遗留文本误当成当前意图

该区域不承担编辑功能。

3. 怎么使用这张参考图

作为单独区域展示，不再混入当前提示词信息。

模式命名改为：

• 风格迁移
• 复刻图片

模式说明改为：

• 风格迁移：在原提示词的基础上学习图片风格进行改造
• 复刻图片：丢弃原始提示词内容，反推图片对应提示词

展示方式：

• 使用可点击卡片承载单选逻辑，而不是仅显示普通文字型 radio
• 卡片需有明显选中态，便于第一眼区分

规则：

• 当前提示词为空时，不显示模式切换，默认只走 复刻图片
• 当前提示词非空时，默认推荐 风格迁移

弹窗布局

桌面端

采用混合布局：

• 顶部上下文区：纵向排列两个轻量卡片
  • 参考图
  • 检测到当前提示词
• 中部模式区：两张模式卡横向排布
• 底部结果区：左右布局
  • 左：生成后的提示词，宽度约 2fr
  • 右：提取到的变量，宽度约 1fr

窄屏

底部结果区自动回退为纵向堆叠：

• 先显示 生成后的提示词
• 再显示 提取到的变量

弹窗尺寸

• 继续基于 Naive UI NModal + NCard
• 控制整体宽度，不允许回退为异常全屏
• 建议桌面宽度保持在 min(880px, calc(100vw - 32px)) 左右的级别
• 保持主题跟随，避免硬编码浅色背景或阴影逻辑

结果编辑区设计

生成后的提示词

这是弹窗的主内容区，应具备稳定高度。

规则：

• 使用单个可编辑 textarea
• 不再展示“请先上传参考图生成预览”之类的说明文案
• 未生成前允许为空，但界面仍保留固定编辑区域
• 建议最小高度约 260px ~ 320px
• 加载中只显示轻量状态提示，不挤压编辑区高度

提取到的变量

作为结果工作区的一部分展示，而不是附属信息。

规则：

• 变量名只读
• 变量值可编辑
• 区域需具备明确最小高度和滚动能力
• 变量行之间保持稳定间距，避免像表单碎片一样堆在底部

变量策略

产品规则

• 变量只在首次生成预览时自动提取一次
• 用户编辑 prompt 后，不自动重算变量
• 不再提供“同步变量”或“重新提取变量”按钮
• 点击应用时：
  • 直接采用当前 prompt 文本
  • 直接采用当前变量区值
  • 不再做额外重算

这意味着 prompt 与变量允许短暂不完全一致，这是有意的简化，不视为缺陷。

数量上限

变量总数必须控制在 5 个以内。

采用三层约束：

1. 参考图生成与迁移模板中，要求输出更适合少量高价值变量抽取的结构
2. 变量提取模板中明确要求最多返回 5 个变量，并按重要性排序
3. UI 服务层增加硬上限兜底，只保留前 5 个变量

优先级

优先保留以下变量类型：

• 主体
• 数量
• 颜色
• 关键动作
• 关键场景或核心风格锚点

低优先级项应避免被抽成变量：

• 细碎修饰词
• 重复限定词
• 对最终复用价值不高的局部装饰

状态与数据流

打开弹窗

1. 读取当前原始提示词
2. 若非空，生成摘要用于“检测到当前提示词”
3. 初始化模式：
   • 有当前提示词时默认 风格迁移
   • 无当前提示词时默认 复刻图片
4. 清空本次参考图预览结果

上传参考图后生成预览

复刻图片

1. extractReferenceSpecFromImage
2. composePromptFromReferenceSpec
3. extractPromptVariables
4. 将结果填入弹窗中的 prompt 和变量区

风格迁移

1. extractReferenceSpecFromImage
2. migratePromptWithReferenceSpec
3. extractPromptVariables
4. 将结果填入弹窗中的 prompt 和变量区

应用到当前提示词

1. 使用当前编辑框中的 prompt 作为最终文本
2. 使用当前变量区中的值覆盖当前临时变量
3. 关闭弹窗
4. 不再保留撤销快照

需要删除的复杂度

删除撤销链路

移除以下能力：

• 弹窗应用后的撤销提示条
• lastApplySnapshot
• canUndoLastApply
• undoLastApply()
• 相关 UI 按钮与成功提示

原因：

• 弹窗本身已承担最终确认职责
• 应用后撤销会引入额外状态与心智负担
• 不符合本功能“确认后替换”的简单模型

删除变量同步链路

移除或保持不存在以下能力：

• 手动同步变量
• 自动重算变量
• prompt 变更后的失焦刷新
• 变量与 prompt 的双向联动逻辑

原因：

• 这会把弹窗变成编辑器，不再是前置参考改造工具
• 当前 MVP 的价值在于快速得到一份可用起点，而不是维护强一致的数据模型

文案调整

主要文案

• 识图提取 保持为 参考图
• 检测到当前提示词：{prompt} 改为分离式标题和摘要内容，不再拼成一整句
• 保留当前内容 改为 风格迁移
• 按参考图生成 改为 复刻图片

模式说明

• 风格迁移：在原提示词的基础上学习图片风格进行改造
• 复刻图片：丢弃原始提示词内容，反推图片对应提示词

影响范围

UI

• packages/ui/src/components/image-mode/ImageText2ImageWorkspace.vue
• packages/ui/src/composables/image/useReferencePromptDialog.ts
• packages/ui/src/i18n/locales/zh-CN.ts
• packages/ui/src/i18n/locales/zh-TW.ts
• packages/ui/src/i18n/locales/en-US.ts

服务与模板

• packages/ui/src/services/ImageStyleExtractor.ts
• packages/core/src/services/template/default-templates/image-prompt-composition/
• packages/core/src/services/template/default-templates/image-prompt-migration/
• packages/core/src/services/template/default-templates/variable-extraction/

错误处理

• 上传失败时，维持当前 prompt 和变量不变
• 参考图解析失败时，仅提示本次生成失败，不关闭弹窗
• 变量提取失败时，允许 prompt 继续展示，但变量区为空
• 当前提示词为空时，不展示模式选择，也不报错

测试要点

交互测试

• 弹窗不再显示应用后撤销提示
• 当前提示词非空时，先显示摘要，再显示模式选择
• 模式名称和说明文案已切换为 风格迁移 / 复刻图片
• 参考图区域使用缩略图，不再占用大图高度
• prompt 区和变量区有稳定高度

逻辑测试

• 风格迁移 默认选中，仅在当前提示词非空时出现
• 复刻图片 在当前提示词为空时自动生效
• 应用时不再保存撤销快照
• 编辑 prompt 不触发变量自动刷新
• 变量数量始终不超过 5 个

回归测试

• 未使用参考图时，文生图现有流程不变
• 图生图工作区不受影响
• 三段式内部服务链路保持不变

验收标准

• 用户能在首次打开弹窗时看懂“当前看到了什么”和“可以怎么用这张图”
• 参考图不再抢占主编辑区空间
• 风格迁移 / 复刻图片 的语义差异无需额外解释即可理解
• 弹窗应用链路不再包含撤销和同步变量等补救型复杂度
• 变量数量被稳定控制在 5 个以内

实施建议

建议按以下顺序实施：

1. 先删状态复杂度
   • 移除撤销状态与相关文案
2. 再改 UI 信息架构
   • 缩略图参考图
   • 当前提示词摘要卡
   • 模式卡
   • 底部混合布局
3. 最后收变量策略
   • 提取模板收紧
   • 服务层硬上限兜底

这样可以先把交互心智收干净，再保证变量结果稳定。

Source: docs/superpowers/specs/2026-03-31-reference-image-dialog-redesign-design.md