# 真实生成任务 E2E 验证回路（工作流）

日期：2026-06-06
触发场景：接入新模型 / 验证某条生成链路 / 怀疑"配好了但没真跑通" / 验证提示词出图效果。
关系：是规则 13（穿透走查）在「真实外呼生成任务」上的专用化，叠加规则 7（角色 agent）+ 规则 14（审计）+ 一条新原则「接入即验证」。

> **一句话**：一个模型 / 一条生成链路，不算「接入成功」，直到**一次真实 E2E 生成跑通**。
> 自动接入也会抽错（实例：GPT Image 2 的 mapping 是从视频模型克隆来的，留了视频参数、丢了图像输入字段、读错结果字段）——
> 唯一能在用户之前抓住它的，是接入末尾**强制真跑一次**。

## 为什么需要这条（本会话的根因复盘）

我要验证「GPT Image 2 出身份板提示词效果好不好」，结果**根本没跑出一张图**，因为撞了一串**分层**的坑：
1. **UI 层**：composer 的提示词编辑器 z-index 盖住生成按钮（黑 ↑），拦截点击，得 `force` 才点得动。
2. **交互 UX 层**：参考图入口「添加 Input image URL」→ 选择器上传 → 结果在画布多出一个独立节点，**没填进输入槽**。
3. **配置层**：`gpt-image-2-image-to-image` 的 mapping 是**视频形状**——请求体没有图像输入字段、带 `duration`，结果读 `video_url`、`image_url` 为空。
4. **传输可观测层**：kie 的真实 HTTP 在 **Electron 主进程**发，Playwright 渲染层监听**抓不到**——以为"没发请求"，其实是看不见。
5. **根因层**：GPT Image 2 **没有 archetype** → 没有能力/请求模板 → 配置只能手动克隆视频 mapping → 必然错。

单测 / mock 一个都抓不到这些——它们只在**真实任务、真机、真传输**下暴露。

## 回路（7 步，按性质分层）

1. **定义真实任务**（不是 mock）：写死 `模型 + 真实输入 + 期望产物`。
   例：「GPT Image 2：基准图 + 身份板提示词 → 一张 16:9 身份板图」。
2. **真机驱动 + 全层埋点**：Playwright `_electron` 驱动**构建产物**走真实用户旅程；
   **关键补课**：在**主进程**给 vendor HTTP 出入口加日志（请求体 + 响应），否则传输层是黑盒（坑 #4）。
3. **分层暴露、不止步于第一个坑**：UI → 交互 UX → 配置 → 传输 → 结果渲染，**逐层记录**。
   撞到阻塞先 `log` + 绕过 + 继续，把**所有**问题收集齐，别修一个停一个。
4. **逐个挖根因（到底，不停在症状）**：「没出图」→「mapping 没有图像输入字段」→「GPT Image 2 没 archetype，mapping 手动克隆自视频」。
5. **分级修复**：
   - 琐碎（z-index / 选择器）→ 就地改。
   - **系统性**（mapping 形状 / archetype 缺失 / 自动接入抽取）→ **起 agent 审项目文档 + 架构**（规则 7 的 CTO/前端/后端、规则 14 审计），
     先读 `modelArchetypes` / `onboarding` 抽取 / catalog mapping，确认根因与改法，**再动手**。
6. **补可观测性 + 锁回归**：把缺的埋点（主进程 HTTP 日志）做成**常驻**；把验证过的任务沉淀成**可复跑断言**（`tests/ux/*.e2e.mjs`）。
7. **接入即验证（门）**：模型 / 链路接入流程的**最后一步**＝自动跑本回路一次；**真生成成功才标「就绪」**。

## 与「自动接入」的耦合（Part 1）

本回路是「文档 + key 自动接入」的**验收门**：
- 自动接入 = 识别模型 → 套 archetype（能力）+ 从文档抽传输（端点/字段/结果路径）→ 生成 mapping。
- 自动接入**会抽错**（本会话实证）→ 末尾必须真跑一次本回路，错的 mapping 当场暴露。
- 缺 archetype 的模型（如 GPT Image 2 图像类）应**先补 archetype**，否则手配 mapping 必然漂。

## 能力边界（诚实记录，省得反复试）

- Playwright 渲染层**抓不到主进程的 vendor HTTP**——要诊断传输必须在主进程埋点（或读 runtime 日志）。
- image-to-image 模型纯文生图会被**客户端挡在发送前**（缺输入图），表现为「点了生成没反应」，不是 bug 是缺输入。
- 真实生成**花额度**——默认先问用户；本回路的"真跑"步骤是授权动作。

## 沉淀的待办（指向 Part 1 的设计/审计）

- [ ] GPT Image 2 缺 archetype → 补一个**图像模型 archetype 路径**（对偶于 Seedance/HappyHorse 视频档案）。
- [ ] 修 `gpt-image-2-image-to-image` mapping：补图像输入字段、改对结果字段、去视频参数。
- [ ] 修参考图入口（「添加 Input image URL」应填进槽，而非另建节点）+ composer 生成按钮 z-index。
- [ ] 主进程 vendor HTTP 埋点常驻。
- [ ] 「接入即验证」门：onboarding 自动接入末尾强制真跑一次本回路。
- [ ] **设计/审计**：文档 + key 一次粘贴 → 正确 mapping 的自动接入闭环（Part 1 主题）。
