734 lines
20 KiB
Markdown
734 lines
20 KiB
Markdown
## Context
|
||
|
||
当前生图反馈主要依赖 `WorkZone`：
|
||
|
||
- 提交时在画布中插入固定尺寸的卡片
|
||
- 卡片内部展示标题、状态、步骤列表与删除/隐藏按钮
|
||
- 自动插入完成后再删除卡片
|
||
|
||
这种设计适合表达工作流存在，但不适合表达“图片对象即将落入画布”的过程。问题主要有：
|
||
|
||
- 过程对象抢占画布注意力，打断创作空间
|
||
- 固定卡片高度在单图场景下留白过多
|
||
- 生图反馈的核心不是步骤明细，而是“会落在哪、会长成什么比例、现在到了哪个阶段”
|
||
- 当前状态同步分散在 `AIInputBar`、`useWorkflowSubmission`、`useTaskWorkflowSync`、`useAutoInsertToCanvas` 中，后续继续在 `WorkZone` 上叠交互会进一步放大复杂度
|
||
|
||
## Goals
|
||
|
||
- 让生图过程在画布中表现为“对象正在诞生”，而非“任务卡片正在执行”
|
||
- 优先利用提交时即可获得的几何信息，建立可信的一致性反馈
|
||
- 在结果未返回前，通过锚点表达位置、比例与状态，而不伪装已知内容
|
||
- 保留失败重试、详情追踪和恢复能力
|
||
- 首版只覆盖 `image` 类型任务，不改造其他任务类型
|
||
|
||
## Non-Goals
|
||
|
||
- 不在首版统一视频、音频、文本、流程图等其他任务反馈
|
||
- 不在首版默认引入强品牌化的传送门或粒子特效
|
||
- 不依赖结果侧稳定返回 `width/height` 元数据来决定首版锚点几何
|
||
|
||
## Decision
|
||
|
||
### 1. 生图改为 `Generation Anchor`
|
||
|
||
生图提交后，系统在预期插入位置创建轻量锚点，而不是默认创建大面积 `WorkZone` 卡片。
|
||
|
||
锚点的职责只有四类：
|
||
|
||
- 表达“已受理”
|
||
- 表达“预期落点”
|
||
- 表达“预期几何外壳”
|
||
- 表达“当前阶段 + 主动作”
|
||
|
||
步骤详情、历史记录、错误细节默认不在画布中展开。
|
||
|
||
### 2. 三档几何策略
|
||
|
||
#### `Frame-first`
|
||
|
||
若提交时已存在：
|
||
|
||
- `targetFrameId`
|
||
- `targetFrameDimensions`
|
||
|
||
则锚点直接继承 Frame 外壳，在该容器内部完成生成、显影与结果接管。
|
||
|
||
#### `Size-first`
|
||
|
||
若不存在 Frame，但已存在明确的 `size`，则使用 `size` 作为锚点外壳的比例来源。该策略与当前插入逻辑一致，因为首版插入已经依赖 `parseSizeToPixels(size)` 进行几何推导。
|
||
|
||
#### `Ghost-anchor`
|
||
|
||
若既无 Frame 又无稳定比例信息，则仅创建轻量出生点锚点，不伪装为完整图片框。待结果返回后，再从出生点平滑 morph 为真实图片。
|
||
|
||
### 3. 用户态状态机
|
||
|
||
生图锚点统一使用以下用户态：
|
||
|
||
- `submitted`
|
||
- `queued`
|
||
- `generating`
|
||
- `developing`
|
||
- `inserting`
|
||
- `completed`
|
||
- `failed`
|
||
|
||
状态解释：
|
||
|
||
- `submitted`: 用户点击后，任务已创建，输入条需要立即确认
|
||
- `queued`: 请求已受理但尚未进入明显执行
|
||
- `generating`: 模型正在生成结果
|
||
- `developing`: 结果已返回，正在准备插入或执行轻显影
|
||
- `inserting`: 正在把真实图片插入画布并与锚点连续过渡
|
||
- `completed`: 图片已稳定落位，锚点将短暂停留后淡出
|
||
- `failed`: 保留失败节点，允许重试或查看详情
|
||
|
||
#### 用户态文案规范
|
||
|
||
首版默认文案应保持“对象正在诞生”的语义，而不是暴露底层工作流术语：
|
||
|
||
- `submitted`: 已提交，等待执行
|
||
- `queued`: 请求已受理，等待执行
|
||
- `generating`: 图片正在生成，请稍候
|
||
- `developing`: 结果已返回，正在准备显影
|
||
- `inserting`: 正在放入画布
|
||
- `completed`: 图片已稳定落位
|
||
- `failed`: 生成失败，请重试
|
||
|
||
允许在特定交互瞬间使用更细的提示文案，例如：
|
||
|
||
- 主线程回退时：请求已受理，正在转入本地执行
|
||
- 用户点击重试时：正在重新触发，请稍候
|
||
|
||
但这些文案必须仍然映射回上述统一用户态，不允许新增平行状态名。
|
||
|
||
### 4. 详情层收敛
|
||
|
||
锚点默认只展示：
|
||
|
||
- 当前阶段文案
|
||
- 轻进度
|
||
- 一个主动作
|
||
|
||
详细步骤、错误明细、历史版本应进入任务详情层，而不是在画布中展开完整 `WorkZone`。
|
||
|
||
#### 职责边界
|
||
|
||
`Generation Anchor` 负责：
|
||
|
||
- 受理确认
|
||
- 预期落点
|
||
- 预期几何外壳
|
||
- 当前阶段
|
||
- 轻进度
|
||
- 当前上下文中的恢复动作
|
||
|
||
任务详情层负责：
|
||
|
||
- 完整步骤列表
|
||
- 错误详情与调试信息
|
||
- 历史记录与重试历史
|
||
- 批量结果管理
|
||
- 非画布主路径的任务追踪
|
||
|
||
画布中的锚点不应默认展开完整步骤列表，也不应承载需要持续滚动阅读的信息。
|
||
|
||
### 5. 渐进迁移
|
||
|
||
首版仅对 `image` 类型启用 `Generation Anchor`。
|
||
|
||
- `image`：默认启用 Anchor
|
||
- 其他类型：继续使用现有 `WorkZone` 或现有任务反馈
|
||
|
||
这样能避免一次性改造所有任务语义，也能降低对现有任务同步链路的影响。
|
||
|
||
## State Mapping
|
||
|
||
首版建议由一个统一的 view model 负责把现有信号映射成锚点状态：
|
||
|
||
- 提交态信号：
|
||
- `expectedInsertPosition`
|
||
- `targetFrameId`
|
||
- `targetFrameDimensions`
|
||
- `size`
|
||
- 任务执行信号：
|
||
- `Task.status`
|
||
- `Task.progress`
|
||
- `Task.executionPhase`
|
||
- 后处理信号：
|
||
- `workflowCompletionService`
|
||
- 自动插入开始/完成事件
|
||
|
||
映射规则示例：
|
||
|
||
- 任务创建后但未进入稳定进度更新：`submitted`
|
||
- `TaskExecutionPhase.SUBMITTING`: `queued`
|
||
- `Task.progress` 持续推进：`generating`
|
||
- 任务已成功但后处理未完成：`developing`
|
||
- 图片正在落入画布：`inserting`
|
||
- 后处理完成并已插入：`completed`
|
||
- 任意执行或插入失败：`failed`
|
||
|
||
## UI Model
|
||
|
||
建议新增面向 UI 的锚点模型：
|
||
|
||
- `anchorType`: `frame | ratio | ghost | stack`
|
||
- `phase`
|
||
- `position`
|
||
- `dimensions`
|
||
- `progress`
|
||
- `title`
|
||
- `subtitle`
|
||
- `primaryAction`
|
||
- `secondaryAction`
|
||
- `transitionMode`
|
||
|
||
该模型只表达画布中锚点需要展示什么，不直接持有完整工作流对象。
|
||
|
||
## Integration Notes
|
||
|
||
- 输入条负责第一层反馈：点击后立即显示“已提交”
|
||
- 画布锚点负责第二层反馈：表达位置、比例、阶段
|
||
- 任务详情层负责第三层反馈：步骤明细、失败原因、历史记录
|
||
- 现有 `WorkZone` 首版可作为非生图路径保留，不与生图锚点混用
|
||
|
||
## Architecture Alignment
|
||
|
||
### Runtime Topology
|
||
|
||
首版推荐的运行时拓扑如下：
|
||
|
||
1. `AIInputBar`
|
||
- 负责生图提交入口
|
||
- 产出提交期几何上下文
|
||
- 调用 `ImageGenerationAnchorTransforms.insertAnchor`
|
||
- 触发输入条“已提交”反馈
|
||
|
||
2. `with-image-generation-anchor`
|
||
- 负责 `generation-anchor` 元素的画布承载与渲染
|
||
- 管理 anchor 元素的插入、更新、删除与命中
|
||
|
||
3. `useImageGenerationAnchorController`
|
||
- 负责把原始信号映射为 UI model
|
||
- 不直接写画布，只输出“应该显示什么”
|
||
|
||
4. `useImageGenerationAnchorSync`
|
||
- 负责监听任务与后处理事件
|
||
- 负责按 `taskId / workflowId` 找到 anchor
|
||
- 负责把 controller 产出的状态回写到画布元素
|
||
|
||
5. `useAutoInsertToCanvas`
|
||
- 负责真实图片落图
|
||
- 负责驱动 `developing -> inserting -> completed`
|
||
- 负责在插入完成后让 anchor 收口
|
||
|
||
6. `WorkZone`
|
||
- 生图首版不再作为默认反馈
|
||
- 仅保留给非生图任务与旧路径兼容
|
||
|
||
### Ownership Matrix
|
||
|
||
#### `AIInputBar`
|
||
|
||
拥有：
|
||
|
||
- `generationType === 'image'` 分流决策
|
||
- `expectedInsertPosition`
|
||
- `targetFrameId`
|
||
- `targetFrameDimensions`
|
||
- `requestedSize`
|
||
- `currentImageAnchorIdRef`
|
||
- 输入条首段反馈
|
||
|
||
不拥有：
|
||
|
||
- anchor 运行中阶段推进
|
||
- 刷新恢复
|
||
- 自动插入后的收口
|
||
- 全局任务同步
|
||
|
||
#### `Drawnix`
|
||
|
||
拥有：
|
||
|
||
- 注册 `with-image-generation-anchor`
|
||
- 挂载 `useImageGenerationAnchorSync`
|
||
- 在 board ready / task storage ready 后进行恢复协调
|
||
|
||
不拥有：
|
||
|
||
- 提交期几何推导
|
||
- 真实插入行为本身
|
||
|
||
#### `useImageGenerationAnchorSync`
|
||
|
||
拥有：
|
||
|
||
- 从 `taskQueueService`、`workflowCompletionService`、插入事件读取状态
|
||
- 根据 `taskId / workflowId` 查找 anchor
|
||
- 调用 transforms 更新 anchor 元素
|
||
|
||
不拥有：
|
||
|
||
- 具体 JSX 渲染
|
||
- 业务提交入口
|
||
|
||
#### `useAutoInsertToCanvas`
|
||
|
||
拥有：
|
||
|
||
- 结果 URL 到画布对象的真实插入
|
||
- 插入前后的 anchor 状态推进
|
||
- 插入失败到失败态的回写
|
||
|
||
不拥有：
|
||
|
||
- anchor 初次创建
|
||
- 输入条即时反馈
|
||
|
||
### Data Contracts
|
||
|
||
#### Submission Context
|
||
|
||
建议定义一个单独的提交期上下文对象，避免多个模块重复各自取值：
|
||
|
||
- `workflowId`
|
||
- `taskIds`
|
||
- `expectedInsertPosition`
|
||
- `targetFrameId`
|
||
- `targetFrameDimensions`
|
||
- `requestedSize`
|
||
- `prompt`
|
||
- `count`
|
||
- `createdAt`
|
||
|
||
来源：
|
||
|
||
- `AIInputBar`
|
||
|
||
用途：
|
||
|
||
- 创建 anchor
|
||
- 恢复定位
|
||
- 插入时兜底寻找几何上下文
|
||
|
||
#### Anchor View Model
|
||
|
||
建议定义一个稳定的 UI model，避免 JSX 直接依赖任务/工作流对象：
|
||
|
||
- `anchorType`
|
||
- `phase`
|
||
- `progressMode: 'indeterminate' | 'percent' | 'steps'`
|
||
- `progressValue`
|
||
- `title`
|
||
- `subtitle`
|
||
- `showFrameShell`
|
||
- `showRatioShell`
|
||
- `showGhostPulse`
|
||
- `canRetry`
|
||
- `canOpenDetails`
|
||
- `transitionMode: 'fade' | 'morph' | 'frame-fill' | 'stack-expand'`
|
||
|
||
### Runtime Sequence
|
||
|
||
#### 提交阶段
|
||
|
||
1. `AIInputBar` 解析生图请求
|
||
2. 推导 `expectedInsertPosition / Frame / size`
|
||
3. 构造 submission context
|
||
4. 创建 `generation-anchor`
|
||
5. 提交任务到工作流 / 任务队列
|
||
|
||
#### 执行阶段
|
||
|
||
1. `taskQueueService` 发出 `taskCreated / taskUpdated`
|
||
2. `useImageGenerationAnchorSync` 读取任务状态
|
||
3. `useImageGenerationAnchorController` 把 `Task.status / progress / executionPhase` 映射为 `submitted / queued / generating`
|
||
4. transforms 更新 anchor 元素
|
||
|
||
#### 后处理阶段
|
||
|
||
1. 任务成功返回结果 URL
|
||
2. `workflowCompletionService` 发出后处理开始
|
||
3. anchor 切到 `developing`
|
||
4. `useAutoInsertToCanvas` 开始插入
|
||
5. anchor 切到 `inserting`
|
||
6. 图片落图成功后，anchor 切到 `completed` 并收口
|
||
|
||
#### 失败阶段
|
||
|
||
1. 任务失败或插入失败
|
||
2. `useImageGenerationAnchorSync` / `useAutoInsertToCanvas` 写回失败态
|
||
3. anchor 保留失败节点
|
||
4. 用户可原位重试或打开详情
|
||
|
||
## Implementation Breakdown
|
||
|
||
### 1. 元素层拆分
|
||
|
||
首版不建议在现有 `workzone` 元素上继续追加“生图锚点”模式，而是新增独立的画布元素类型：
|
||
|
||
- `generation-anchor`
|
||
|
||
原因：
|
||
|
||
- `workzone` 语义是“工作流过程面板”
|
||
- `generation-anchor` 语义是“结果出生点”
|
||
- 两者在几何、交互密度、恢复逻辑和删除时机上都不同
|
||
- 生图首版需要与非生图路径并行存在，独立元素类型更利于渐进迁移
|
||
|
||
插件实现建议优先参考现有的轻元素模式，而不是继续沿用 `with-workzone` 的重型编排模式：
|
||
|
||
- 参考 `withCard` / `CardGenerator` 的 `foreignObject + React root + generator` 范式
|
||
- 参考 `withAudioNode` / `AudioNodeGenerator` 的“轻元素 + 实时状态渲染”模式
|
||
- 若后续需要手动缩放，再单独增加 resize companion plugin，参考 `with-card-resize` / `with-audio-node-resize`
|
||
|
||
不建议参考 `withTool` 的消息桥式重型模式，因为 anchor 不是一个 iframe 工具，也不应承担任务编排职责。
|
||
|
||
### 2. 建议新增文件
|
||
|
||
#### 类型层
|
||
|
||
- `packages/drawnix/src/types/image-generation-anchor.types.ts`
|
||
|
||
职责：
|
||
|
||
- 定义 `PlaitImageGenerationAnchor`
|
||
- 定义 `anchorType`
|
||
- 定义用户态 `phase`
|
||
- 定义提交期几何上下文与主动作字段
|
||
|
||
建议字段：
|
||
|
||
- `workflowId`
|
||
- `taskIds`
|
||
- `anchorType: 'frame' | 'ratio' | 'ghost' | 'stack'`
|
||
- `phase`
|
||
- `progress`
|
||
- `requestedSize`
|
||
- `expectedInsertPosition`
|
||
- `targetFrameId`
|
||
- `targetFrameDimensions`
|
||
- `resultUrl`
|
||
- `error`
|
||
- `zoom`
|
||
|
||
#### 渲染层
|
||
|
||
- `packages/drawnix/src/components/image-generation-anchor/ImageGenerationAnchorContent.tsx`
|
||
- `packages/drawnix/src/components/image-generation-anchor/image-generation-anchor.scss`
|
||
- `packages/drawnix/src/components/image-generation-anchor/index.ts`
|
||
|
||
职责：
|
||
|
||
- 渲染 `Frame Anchor`
|
||
- 渲染 `Ratio Anchor`
|
||
- 渲染 `Ghost-anchor`
|
||
- 渲染失败态与主动作
|
||
|
||
约束：
|
||
|
||
- 只做展示，不直接 claim / resume / 查询任务状态
|
||
- 不持有工作流恢复逻辑
|
||
|
||
#### 插件层
|
||
|
||
- `packages/drawnix/src/plugins/with-image-generation-anchor.ts`
|
||
|
||
职责：
|
||
|
||
- 注册 `generation-anchor` 元素
|
||
- 创建 `foreignObject`
|
||
- 管理激活态边框与点击命中
|
||
- 提供 transforms：
|
||
- `insertAnchor`
|
||
- `updateAnchorState`
|
||
- `updateGeometry`
|
||
- `removeAnchor`
|
||
- `getById`
|
||
- `getAnchorByTaskId`
|
||
- `getAnchorByWorkflowId`
|
||
- `getAllAnchors`
|
||
|
||
边界约束：
|
||
|
||
- 插件层只提供元素能力
|
||
- 不直接订阅 `taskQueueService`
|
||
- 不直接处理 workflow 恢复
|
||
- 不直接决定 anchor 何时完成或消失
|
||
|
||
#### 状态映射层
|
||
|
||
- `packages/drawnix/src/hooks/useImageGenerationAnchorController.ts`
|
||
- `packages/drawnix/src/utils/image-generation-anchor-view-model.ts`
|
||
|
||
职责：
|
||
|
||
- 将提交期几何信号 + 任务状态 + 后处理状态映射为 anchor UI model
|
||
- 统一决定：
|
||
- `anchorType`
|
||
- `phase`
|
||
- `progress`
|
||
- `title/subtitle`
|
||
- `primaryAction`
|
||
- `transitionMode`
|
||
|
||
关键原则：
|
||
|
||
- UI 不直接认 `taskQueueService`、`workflowSubmissionService` 或 `workflowCompletionService` 的原始对象
|
||
- UI 只认 `ImageGenerationAnchorController` 产出的 anchor view model
|
||
- controller 是 image anchor 的单一状态源
|
||
|
||
建议保持该层为纯映射或轻控制器，不直接操作 DOM。
|
||
|
||
#### 同步层
|
||
|
||
- `packages/drawnix/src/hooks/useImageGenerationAnchorSync.ts`
|
||
|
||
职责：
|
||
|
||
- 在 board 级别监听 `taskQueueService`
|
||
- 在 board 级别监听后处理 / 自动插入事件
|
||
- 在刷新恢复后重新同步 anchor 状态
|
||
- 将更新写回 `ImageGenerationAnchorTransforms`
|
||
|
||
边界约束：
|
||
|
||
- `sync` 只负责订阅和归一化原始事件
|
||
- `sync` 不直接做业务判断
|
||
- `sync` 允许重复事件、乱序事件和恢复事件
|
||
- `controller` 负责幂等推进和去重
|
||
|
||
该 hook 应由 `Drawnix` 持有，而不是由 `AIInputBar` 或单个 anchor 组件持有。
|
||
|
||
### 3. 现有文件改动范围
|
||
|
||
#### `AIInputBar.tsx`
|
||
|
||
保留职责：
|
||
|
||
- 判断当前是否是 `image` 类型提交
|
||
- 计算 `expectedInsertPosition`
|
||
- 解析 `targetFrameId / targetFrameDimensions`
|
||
- 计算 `requestedSize`
|
||
- 在提交时创建首个 anchor
|
||
- 提供输入条“已提交”即时反馈
|
||
|
||
移出职责：
|
||
|
||
- 不再负责生图默认大 `WorkZone` 创建
|
||
- 不再通过 `currentWorkZoneIdRef` 驱动生图的完整生命周期
|
||
- 不再直接订阅 `taskQueueService.observeTaskUpdates()`
|
||
- 不再直接订阅 `workflowCompletionService.observeCompletionEvents()`
|
||
- 不再直接基于 image 路径写 `WorkZoneTransforms.update/remove`
|
||
|
||
建议新增：
|
||
|
||
- `currentImageAnchorIdRef`
|
||
|
||
并保留现有：
|
||
|
||
- `currentWorkZoneIdRef`
|
||
|
||
作为非生图路径兼容。
|
||
|
||
#### `useAutoInsertToCanvas.ts`
|
||
|
||
新增职责：
|
||
|
||
- 根据 `taskId` 查找 image anchor
|
||
- 在“结果已返回但未插入”时切换到 `developing`
|
||
- 在“开始插入”时切换到 `inserting`
|
||
- 在“插入完成”时执行 anchor → image 的收口
|
||
- 在失败时更新为失败节点
|
||
|
||
需要替换的当前耦合：
|
||
|
||
- 现有 `findWorkZoneForTask`
|
||
- 现有基于 WorkZone 的 `expectedInsertPosition / targetFrameDimensions` 读取
|
||
- 现有生图完成后直接删除 WorkZone 的逻辑
|
||
- 现有依赖 `ai-generation-complete` 解锁输入条的生图路径
|
||
|
||
#### `drawnix.tsx`
|
||
|
||
新增职责：
|
||
|
||
- 注册 `with-image-generation-anchor`
|
||
- 挂载 `useImageGenerationAnchorSync`
|
||
|
||
保留职责：
|
||
|
||
- 现有 `WorkZone` 恢复与同步先只服务非生图路径
|
||
|
||
建议调整：
|
||
|
||
- 让 `Drawnix` 成为 image anchor 的全局恢复入口
|
||
- 不再让 `AIInputBar` 持有刷新恢复或跨任务同步逻辑
|
||
- 现有 `restoreWorkZones`、workflow sync、task queue sync 中的 image 逻辑应迁移到 anchor sync，而不是继续直接写 WorkZone
|
||
|
||
#### `useWorkflowSubmission.ts`
|
||
|
||
建议调整：
|
||
|
||
- 将 image 类型从“默认 WorkZone 同步路径”中分流出来
|
||
- 保持文本、Agent、非生图任务继续复用现有逻辑
|
||
|
||
说明：
|
||
|
||
生图首版的主要状态源更应该是：
|
||
|
||
- 提交期几何上下文
|
||
- `taskQueueService`
|
||
- 后处理 / 插入事件
|
||
|
||
而不是完整 `workflow` 步骤列表。
|
||
|
||
需要重点清理的耦合：
|
||
|
||
- 当前把 workflow 事件直接同步到 WorkZone 的分支
|
||
- 当前把 image 路径当成默认 workflow 面板处理的分支
|
||
|
||
#### `with-workzone.ts` / `WorkZoneContent.tsx`
|
||
|
||
首版策略：
|
||
|
||
- 保留
|
||
- 不扩展生图主路径
|
||
- 仅服务非生图任务与兜底流程
|
||
|
||
后续可选策略：
|
||
|
||
- 当 image anchor 稳定后，再把生图相关分支从 WorkZone 中逐步收缩或删除
|
||
|
||
### 4. 状态层职责划分
|
||
|
||
建议把状态划成三层：
|
||
|
||
#### 提交期几何状态
|
||
|
||
来源：
|
||
|
||
- `AIInputBar`
|
||
- 选区 / Frame
|
||
- `size`
|
||
|
||
职责：
|
||
|
||
- 决定 anchor 初始位置与外壳类型
|
||
- 是 `AIInputBar` 唯一应长期保有的 image 特有语义
|
||
|
||
#### 任务执行状态
|
||
|
||
来源：
|
||
|
||
- `taskQueueService`
|
||
- `Task.progress`
|
||
- `Task.executionPhase`
|
||
|
||
职责：
|
||
|
||
- 决定 `submitted / queued / generating`
|
||
- 是任务生命周期的唯一执行真相，不直接决定最终收口
|
||
|
||
#### 后处理 / 插入状态
|
||
|
||
来源：
|
||
|
||
- `workflowCompletionService`
|
||
- `useAutoInsertToCanvas`
|
||
|
||
职责：
|
||
|
||
- 决定 `developing / inserting / completed / failed`
|
||
- 用于避免“任务已完成但图片尚未真正落图”时提前收口
|
||
|
||
### 5. 单一状态源约束
|
||
|
||
对于 image anchor，必须明确以下 ownership 约束：
|
||
|
||
- `AIInputBar` 只拥有提交瞬间快照，不拥有持续运行态
|
||
- `WorkflowContext` / `workflowSubmissionService` 只拥有 workflow 计划真相，不拥有 anchor UI 真相
|
||
- `taskQueueService` 只拥有任务执行真相
|
||
- `workflowCompletionService` 只拥有后处理真相
|
||
- `ImageGenerationAnchorController` 拥有唯一的 anchor 运行态
|
||
|
||
任何直接绕过 controller 写入 anchor UI 状态的路径，都视为架构违规。
|
||
|
||
### 6. 迁移顺序
|
||
|
||
推荐按以下顺序推进，避免双系统互相打架：
|
||
|
||
1. 新增 anchor 类型、plugin 与 view model
|
||
2. 在 `AIInputBar` 中仅对 `image` 路径创建 anchor
|
||
3. 在 `useAutoInsertToCanvas` 中接入 anchor 查找与完成态收口
|
||
4. 在 `Drawnix` 中增加 anchor 同步 / 恢复 hook
|
||
5. 将 image 路径从默认 `WorkZone` 更新链中分流
|
||
6. 手工验证稳定后，再考虑清理 WorkZone 中的 image 分支
|
||
|
||
### 7. 为什么不复用 `WorkZone`
|
||
|
||
不推荐直接把 `WorkZoneContent` 改成“生图锚点样式”的主要原因：
|
||
|
||
- 仍会保留错误的元素语义
|
||
- 仍会把大量工作流字段塞进画布元素
|
||
- 仍会让生图依赖当前分散的 WorkZone 同步链
|
||
- 会增加“单组件承担展示 + 恢复 + 兜底编排”的复杂度
|
||
|
||
独立元素类型虽然首版工作量更高，但长期边界更清晰。
|
||
|
||
## Audit And Review Plan
|
||
|
||
### 代码层重点审计
|
||
|
||
- 是否仍有 image 路径写入 `WorkZoneTransforms`
|
||
- 是否存在 anchor 与 WorkZone 对同一 image 任务双写
|
||
- 是否有组件直接读取 `taskQueueService` 并绕过 controller
|
||
- 是否把恢复逻辑重新塞回展示组件
|
||
- 是否在未知比例场景下错误创建完整比例框
|
||
- 是否仍沿用 `ai-generation-complete` 作为 image 路径的唯一解锁信号
|
||
|
||
### 迁移层重点审计
|
||
|
||
- `AIInputBar` 创建 image anchor 后，是否仍然默认创建 WorkZone
|
||
- `useAutoInsertToCanvas` 是否还依赖 `findWorkZoneForTask`
|
||
- `drawnix.tsx` 的 WorkZone 恢复逻辑是否误处理 image anchor
|
||
- `useWorkflowSubmission` 是否仍将 image 事件同步到 WorkZone
|
||
- `useTaskWorkflowSync` 是否仍把 image 任务 fallback 到 WorkZone
|
||
- 是否仍存在多个 `setTimeout(1500)` 竞争删除同一 image 反馈对象
|
||
|
||
### 手工验证重点
|
||
|
||
- 选中 Frame 的单图生图
|
||
- 指定 `size` 的单图生图
|
||
- 不指定 `size` 的单图生图
|
||
- 同 prompt 多图生成
|
||
- 失败后原位重试
|
||
- 刷新页面后的锚点恢复
|
||
- 自动插入完成后的收口行为
|
||
|
||
### Code Review 必查文件
|
||
|
||
- `packages/drawnix/src/components/ai-input-bar/AIInputBar.tsx`
|
||
- `packages/drawnix/src/hooks/useAutoInsertToCanvas.ts`
|
||
- `packages/drawnix/src/drawnix.tsx`
|
||
- `packages/drawnix/src/hooks/useWorkflowSubmission.ts`
|
||
- `packages/drawnix/src/hooks/useTaskWorkflowSync.ts`
|
||
- `packages/drawnix/src/plugins/with-workzone.ts`
|
||
- `packages/drawnix/src/plugins/with-image-generation-anchor.ts`
|
||
- `packages/drawnix/src/services/workflow-completion-service.ts`
|
||
- `packages/drawnix/src/services/task-queue-service.ts`
|
||
|
||
## Risks
|
||
|
||
- 若锚点状态映射继续分散在多个 hook 与组件中，会重新产生“多处同步”的维护问题
|
||
- 若在未知比例时仍强制生成完整图片框，会造成锚点与最终结果不一致
|
||
- 若首版同时覆盖多任务类型，会让锚点语义被稀释，增加复杂度
|
||
|
||
## Mitigations
|
||
|
||
- 首版限制在 `image` 类型
|
||
- 将状态映射收敛到单一 view model / controller
|
||
- 将几何策略明确为 `Frame-first / Size-first / Ghost-anchor`
|
||
- 保留现有 `WorkZone` 给非生图路径，降低迁移风险
|