Feature: 参考图输入

一句话目标

用户在节点中可直接上传参考图，并与上游连线传入的图片统一管理，作为 AI 生成的输入条件。

行为约束

约束 1：参考图来源与顺序

前置条件： 节点处于编辑模式（selected），模型具备 reference_image 能力 行为： 参考图来自两个来源：①上游连线传入的图片输出；②用户在节点内直接上传 后置条件： 两种来源的图片在同一区域统一展示，上游图按 edges 数组顺序在前、上传图按 append 顺序在后，无来源视觉区分

约束 2：参考图区域 UI 布局

前置条件： 模型具备 reference_image 能力 行为： prompt 输入框上方显示参考图区域 后置条件：

• 已有图片以缩略图列表展示，每张图右上角有删除按钮（×）
• 分割线
• 上传按钮（方框中心加号图标），点击触发文件选择

约束 3：上传参考图

前置条件： 用户点击上传按钮 行为： 选择图片文件，经过验证（JPG/PNG/WebP，≤30MB）后上传至 COS 后置条件： 上传成功后图片追加到参考图列表末尾，URL 存储在节点数据的 referenceImages 字段中

约束 4：参考图数量限制

前置条件： 模型 reference_image 能力指定了最大数量 行为： 系统计算当前参考图总数（上游 + 上传） 后置条件：

• 总数达到上限 → 上传按钮不可用
• 上游连线图片超出上限 → 按 edges 数组顺序取前 N 张，超出部分不展示

约束 5：删除参考图

前置条件： 用户点击某张参考图的删除按钮 行为：

• 若该图来自上游连线 → 移除对应的 edge
• 若该图为直接上传 → 从节点数据中移除

后置条件：

• 图片从列表中消失
• 若删除后总数低于上限且有被截断的上游图片 → 被截断的下一张按顺序补位

约束 6：生成时数据传递

前置条件： 用户点击生成 行为： 收集所有参考图（上游 + 上传），按当前展示顺序合并到 images[] 参数 后置条件： 请求体中 images[] 的顺序与 UI 展示一致

约束 7：模型无 reference_image 能力时

前置条件： 当前模型不具备 reference_image 能力 行为： 不显示参考图区域和上传按钮 后置条件： 上游图片仍通过 data-flow 注入 images[]，但无管理 UI

约束 8：适用范围

前置条件： 任意节点类型，当前选中模型具备 reference_image 能力 行为： 显示参考图管理 UI 后置条件： 共享相同的 UI 组件和业务逻辑，不限定节点类型

约束 9：切换模型时保留数据

前置条件： 用户切换模型 行为： 节点数据中的上传参考图保留不清除 后置条件： 新模型支持 reference_image → 继续展示；不支持 → UI 隐藏但数据保留，生成时不发送

Acceptance Criteria

来源与展示（约束 1、2）

• [~] AC-01：模型具备 reference_image 能力时，prompt 输入框上方显示参考图区域
• [x] AC-02：参考图区域同时展示上游连线传入的图片和用户直接上传的图片
• [x] AC-03：上游图按 edges 数组顺序在前、上传图按 append 顺序在后，无来源视觉区分
• [~] AC-04：每张缩略图右上角显示删除按钮（×）
• [~] AC-05：已有图片列表与上传按钮之间有分割线
• [~] AC-06：上传按钮为方框中心加号图标，点击触发文件选择

上传（约束 3）

• [~] AC-07：点击上传按钮可选择图片文件，验证通过（JPG/PNG/WebP，≤30MB）后上传至 COS
• [x] AC-08：上传成功后图片追加到参考图列表末尾

数量限制（约束 4）

• [x] AC-09：参考图总数（上游 + 上传）达到模型 reference_image 上限时，上传按钮不可用
• [x] AC-10：上游连线图片超出上限时，按 edges 数组顺序取前 N 张，超出部分不展示

删除与补位（约束 5）

• [x] AC-11：删除来自上游连线的参考图时，移除对应的 edge
• [x] AC-12：删除直接上传的参考图时，从节点数据中移除
• [x] AC-13：删除后总数低于上限且有被截断的上游图片时，下一张按顺序补位

生成（约束 6）

• [x] AC-14：生成时所有参考图按 UI 展示顺序合并到 images[] 参数

能力控制（约束 7、8、9）

• [~] AC-15：模型无 reference_image 能力时，不显示参考图区域，上游图片仍通过 data-flow 注入
• [~] AC-16：任意节点类型，只要模型支持 reference_image，均显示参考图管理 UI
• [~] AC-17：切换模型时上传的参考图数据保留，新模型不支持时 UI 隐藏但数据不清除

BDD Scenarios

Feature: 参考图输入

  # AC-01, AC-06
  Scenario: 模型支持参考图时显示参考图区域
    Given 用户选中一个图片节点
    And 当前模型具备 reference_image 能力
    When 底部浮动面板显示
    Then prompt 输入框上方显示参考图区域
    And 区域内有上传按钮（方框加号图标）

  # AC-02, AC-03
  Scenario: 上游图片在前、上传图片在后
    Given 图片节点 B 已选中，模型支持参考图
    And 上游图片节点 A、C 依次连线到 B
    And 用户上传了一张参考图
    When 查看参考图区域
    Then 图片按 A、C、上传图的顺序排列

  # AC-07, AC-08
  Scenario: 上传参考图
    Given 视频节点已选中，模型支持参考图
    When 用户点击上传按钮并选择一张 JPG 图片
    Then 图片上传至 COS
    And 图片缩略图追加到参考图列表末尾

  # AC-07 异常路径
  Scenario: 拒绝非法参考图文件
    Given 节点已选中，模型支持参考图
    When 用户点击上传按钮并选择一个 40MB 的 PNG 文件
    Then 显示文件大小超限的错误提示
    And 参考图列表不变

  # AC-09
  Scenario: 达到上限后禁用上传
    Given 模型 reference_image 上限为 2
    And 当前已有 2 张参考图（1 张上游 + 1 张上传）
    When 查看参考图区域
    Then 上传按钮不可用

  # AC-10
  Scenario: 上游图片超出上限时截断
    Given 模型 reference_image 上限为 2
    And 上游有 3 条图片连线（按 A、B、C 顺序创建）
    When 查看参考图区域
    Then 只展示 A、B 两张图片
    And C 不展示

  # AC-11
  Scenario: 删除上游参考图移除对应连线
    Given 图片节点 A 连线到视频节点 B
    And B 的参考图区域展示 A 的图片
    When 用户点击该图片的删除按钮
    Then A → B 的连线被移除
    And 该图片从参考图列表中消失

  # AC-12
  Scenario: 删除上传的参考图
    Given 用户已在节点内上传了一张参考图
    When 用户点击该图片的删除按钮
    Then 图片从参考图列表中移除
    And 节点数据中不再包含该图片 URL

  # AC-13, AC-10
  Scenario: 删除后截断图片补位
    Given 模型 reference_image 上限为 2
    And 上游有 A、B、C 三条图片连线
    And 当前展示 A、B（C 被截断）
    When 用户删除 A 的参考图
    Then A → 节点的连线被移除
    And 参考图列表变为 B、C

  # AC-14
  Scenario: 生成时按展示顺序传递参考图
    Given 节点参考图列表依次为：上游图 url-1、上传图 url-2
    And 用户输入了 prompt
    When 用户点击生成
    Then 生成请求的 images 参数为 ["url-1", "url-2"]

  # AC-15
  Scenario: 模型不支持参考图时隐藏区域
    Given 用户选中一个视频节点
    And 当前模型无 reference_image 能力
    When 底部浮动面板显示
    Then 不显示参考图区域
    And 上游图片仍通过 data-flow 注入 images 参数

  # AC-16
  Scenario: 文本节点模型支持参考图时也显示
    Given 用户选中一个文本节点
    And 当前模型具备 reference_image 能力
    When 底部浮动面板显示
    Then prompt 上方显示参考图管理区域

  # AC-17
  Scenario: 切换模型后保留上传的参考图
    Given 用户已上传 2 张参考图
    And 当前模型支持 reference_image
    When 用户切换到另一个也支持 reference_image 的模型
    Then 参考图列表仍展示这 2 张图片

  # AC-17 模型不支持
  Scenario: 切换到不支持参考图的模型后再切回
    Given 用户已上传 2 张参考图
    When 用户切换到不支持 reference_image 的模型
    Then 参考图区域隐藏
    When 用户再切换回支持 reference_image 的模型
    Then 参考图区域重新显示，仍有 2 张图片

TDD 单元测试要点

纯函数 collectUpstreamImages + mergeReferenceImages（test/unit/referenceImage.test.ts）：

• [x] 收集上游图片节点的 imageUrl 并保留 edgeId
• [x] 跳过非图片类型的上游节点
• [x] 上游图在前、上传图在后合并
• [x] 超出模型上限时截断为前 N 张
• [x] 删除一张后截断图片自动补位

composable useReferenceImages（test/nuxt/useReferenceImages.test.ts）：

• [x] 上游 + 上传总数正确计算、canUpload 判定
• [x] addImage 追加不影响已有图片
• [x] 删除上游图时移除对应 edge
• [x] 删除上传图时从节点数据中移除
• [x] imageUrls 按展示顺序返回所有参考图 URL
• [x] 新增/删除连线后列表响应式更新
• [x] 上游节点输出变化后列表响应式更新

Out of Scope

• 参考图拖拽排序（当前按固定顺序：上游在前、上传在后）
• 参考图点击放大预览（可结合 Quick Look，但不在此 spec 范围）
• 参考图裁剪/编辑
• 视频帧作为参考图（截帧功能未确定）
• 首尾帧模式（独立 spec）
• 视频节点工具栏的参考图/首尾帧模式切换（独立 spec）
• 上游视频缩略图的管理（当前 spec 仅覆盖图片类参考媒体）

跨 Spec 影响

• data-flow.md 约束 9：已更新为按时间顺序合并，并添加指向本 spec 的链接