# 模型接入（图片/视频/音频）最终方案 — 审计 + 设计 + 项目计划（R7 定稿）

> 日期：2026-06-07 ｜ 状态：**6 角色评审(R7)已过、已据评审修订；待用户拍决策表**
> 配套：`docs/design/2026-06-07-media-transport-descriptor.md`（~20 家 API + 开源对标 + spike 实测）。
> 北极星：**用户能极方便地用上他想要的模型**（注意：不是"接入任意中转站"——见 R7 修正）。

---

## 0. R7 评审推翻的三个原判断（最重要，先看）

6 角色评审高度收敛，推翻了初稿三处：

1. **"图片先、视频后"是错的判断（PM + 真实用户强烈反对）。** Nomi 是**视频创作**工具，用户来不是生图的。视频排到 P4 = 把用户最想买单的能力垫底。**改：视频与图片同级，P0 就给（kie 已有 Kling/Seedance/Veo）。**
2. **"通用描述符"是内部架构，不是产品门面（PM + 真实用户）。** 用户不在乎描述符，永远别在 UI 出现。**改：描述符/kie 重构定位为"用户零感知的内部重构"，不作独立里程碑；每周必有用户可见产出。**
3. **"贴 curl"会把普通创作者挡在悬崖外（设计师 + 真实用户 + CTO）。** 创作者不知道 curl 是什么，看到就关。**改：把长尾接入从"用户问题"变成"运营问题"——预设覆盖 + 一键求助→团队加预设；UI 删掉 curl 字眼。**

> 一句话：**把 kie 这条聚合器主路做到极致（含视频）+ 热门中转站预设 = 服务 80-90% 用户；通用描述符在背后默默支撑；长尾靠运营兜底，不逼用户懂技术。**

## 1. 审计：现状（真实代码）

| 模块 | 现状 | 评价 |
|---|---|---|
| kie 传输 | 6 个"每模型"文件（kie*.ts，~600 行）——**后端评审：其实已经是 async-task 描述符的硬编码形式**（kieSeedance.ts 就是声明数据，只是壳是 TS） | 加 `transport`+`statusInBody` 标签即可，**每文件补 30-50 行、非重写** |
| 通用 transport | `runtime.ts:2068/2077` 无 mapping 回退（chat/images/videos generations） | ✅ 标准 OpenAI 兼容家可零 mapping |
| 现有 mapping 系统 | `Mapping`+`HttpOperation`+`requestPipeline`+`taskCache`+`buildProfileTaskResult` | **后端：这就是描述符解释器 v0.5，别重造，扩它** |
| onboarding agent | `electron/ai/onboarding/` ~3200 行（贴文档 URL，AI 读） | 已重投入；"默默全自动"易错 |
| 档案 archetype | `src/config/modelArchetypes/` 6 个，声明式 | ✅ identity 层方向对 |
| ⚠️ 重复定义债 | `src/ui/onboarding/{seedance,kling,…}.ts` 与 `src/config/modelArchetypes/` **同名同模型** + `FieldDefinition` vs `ModelParameterControl` 两套 | 规则 1 翻车现场，迁移前先理依赖 |
| AI SDK | **`ai@^4.3.19`（v4，非 v6）** | "用 v6 媒体接口"= 要先大升级，破坏性，单独立项评估 EOL |

## 2. 已验证 vs 未验证（诚实，CTO 纠偏）

- ✅ **请求侧**：一个读表器 + 描述符对 3 形状 + 3 认证，**6 家假 key 全部 401 到达**（请求构造正确）。
- ✅ **响应侧**：**只有 SiliconFlow 1 家**用真 key 端到端验过（拉模型→生成→取回 1.5MB PNG）。**其余 5 家响应解析未验证**——别当"6/6 全验证"。
- ✅ per-model 自动化：Replicate/fal 暴露每模型 schema，运行时拉取自动 derive（开源成熟做法）。
- ❌ 证伪：没有"一把 key 接全部"；"社区包"现在是空的；图/视 `/v1/models` 不通用。

## 3. 设计方案 + CTO 红线

### 3.1 两层（不变）
- **identity 层 = 档案**：按 modelKey 认，声明参数槽/模式/参考槽，供应商无关。
- **transport 层 = 描述符**：扩现有 `Mapping`（加 `transport`/`statusInBody`/`resultEncoding`/`download` 字段），**不重造**。一个读表器吃所有。

### 3.2 描述符红线（CTO 强制，不钉死不开工）
- 描述符 schema **字段数 ≤18**；新增字段过 review。
- **任何算法/钩子/表达式用 TypeScript 函数实现，绝不进 JSON**（JSON 只承载"槽位的值"）。
- 读表器**单文件 ≤500 行**；解释器拆成 `normalizeResult / checkStatus / secondHop`（后端建议），防巨壳（规则 12）。
- 每加一种 `encoding/transport` 枚举，须列"已有几家用+12 月预期"，单家用的回退到 per-家函数，不进枚举。

### 3.3 接入便利（R7 修订后）
- **主路：内置预设**——按**中国创作者真实使用频次**排（302.ai/openrouter/ohmygpt/apiyi/各聚合中转，不是只 OpenAI/SiliconFlow）。选一家+贴 key+测试。
- **kie 聚合器做到极致**——一把 key，图/视频模型自动出现，团队负责跟新模型。
- **测试连接=4 态人话卡片**（设计师）：✅通了 / 🔑key错 / 🌐网址错 / ⚙️格式对不上——每态一个明确下一步 CTA，不是技术日志。
- **长尾=运营兜底**（不逼用户懂技术）：预设没有你的中转站 → "告诉我们" 一键求助 → 团队加预设，下版本就有。（"贴文档链接 + AI 读"作为可选高级入口，**删 curl 字眼**。）
- **通用回退"先能用"**：花式 UI 生不出也给参数框+生成钮，但**视觉标记成临时态**（设计师：用 InlinePanel+⚠️，逼用户升级走，别污染设计系统）。

### 3.4 从开源学到（R6，写进设计）
- 描述符只声明槽、不声明转换算法；图/视一等公民（Dify 反面教材）；异步照 ComfyUI 两段式 + new-api 状态机 + 结果 URL 统一代理；身份用字符串不用枚举。

## 4. 项目方案（R7 重排：用户价值驱动，每周可见）

- **P0 — kie 主路做到极致（MVP 主体，含视频）**：一把 kie key → 图**和视频**模型自动出现、能生成、出错有人话提示。视频不再延后。**这一个就服务 80% 用户。**
- **P1 — 异步生命周期基础设施（独立期，视频前置依赖）**：持久 `taskStore`（替 `taskCache` 内存）+ 后台 `poller`（进度/中断/超时/重启恢复）+ `nomi-task://` 结果代理协议（服务端补凭证、不泄漏到渲染层）。**后端：5-8 周量级，独立成期，别和别的混。**
- **P2 — 描述符化（用户零感知内部重构）**：扩 `Mapping` 加形状标签 + 拆解释器；**kie 6 文件改写成描述符数据 + 删旧（规则 1）**，灰度（先迁 1 家→真 key 回归→再迁 5 家）。顺带开标准图片家预设池（几乎免费）。
- **P3 — 热门预设池 + 一键求助运营闭环**：按中国创作者频次扩预设；"没有你的中转站"求助入口。
- **P4 —（延后/按需）schema 自动 derive**（Replicate/fal）：等真有用户在这类平台卡住再做。PM：5% 用户，不进 MVP。
- **P5 —（延后）音频**：绿地，看到真实需求再补。
- **独立 spike（与本方案解耦）**：AI SDK v4 EOL & v4→v6 升级路径（CTO：季度级技术雷达，今年内出）。

## 5. 不做 / 非目标
- ❌ "一把 key 接全部"（物理不可能）。❌ 现在做社区包市场（无用户）。❌ JSON 里写转换算法/表达式（守 schema 边界）。❌ 自造独立网关服务塞进 Electron。❌ 把"贴 curl"当主路逼用户。❌ 把"描述符重构"当用户可见里程碑（PM）。❌ 视频排到最后（R7 推翻）。

## 6. 风险 / 回滚
- **kie 迁移**：每个文件先有**真 key 响应快照基准**，迁移 PR 双跑对账（旧 vs 新逐字段比对）；先迁 NanoBanana（纯 t2i 最低风险）→ 1 周 → 再迁 5 个；不一把梭。`seedBuiltins` 的 drift 对账自愈老装机。
- **异步基础设施**：每条描述符落地 = 真 key 端到端"接入即验证"才算成功。
- **并行 AI 撞车**（前端实测：近 20 commit 有 15 个 onboarding 相关，那个 AI 在主战场）：P0/P2 优先动**数据+主进程**、渲染层晚动；和它**明确划界**（它管"AI 读文档"语义，本方案管 transport + 预设 + 异步）。
- 每期单 commit、可 revert。
- **重复定义债先清**：迁移前 grep 依赖图，把 `FieldDefinition` 合并进 `ModelParameterControl`、`src/ui/onboarding/*` 与 `modelArchetypes/*` 同名文件理清真相源。

## 7. 决策表（R3，请用户拍）

| # | 决策 | 选项 | R7 后推荐 |
|---|---|---|---|
| D1 | 视频 transport | A 升 AI SDK v6 / B 自建异步读表器 | **B**（升级对用户零价值、纯成本；异步要可观测可控）|
| D2 | 接入便利主力 | A 社区包 / B 内置预设+kie极致+运营兜底 | **B**（社区包是空的）|
| **D3** | **图片 vs 视频优先** | A 图片先 / **B 视频与图片同级、P0 就给** | **B（R7 推翻初稿的"图片先"）** |
| D4 | kie 硬编码 | A 保留 / B 描述符化+删旧 | **B**（但作内部重构、灰度迁移）|
| **D5** | **长尾接入** | A 教用户贴 curl / **B 预设覆盖 + 一键求助→团队加** | **B（设计师+真实用户：别逼创作者懂技术）** |
| **D6** | **描述符复杂度** | A 任意扩 / **B 红线封顶(≤18字段/算法不进JSON/读表器≤500行)** | **B（CTO 红线，不钉死不开工）** |

## 8. R7 六角色评审结论（已回填）

- **CTO（有条件通过）**：方向 PASS、是真证据；但①描述符 schema 复杂度蠕变是最大长期风险→红线（§3.2）；②异步被低估 5-8 周→独立期（P1）；③补 AI SDK EOL spike；④kie 迁移要快照+灰度+双跑对账；⑤诚实标注"响应侧只验 1/6"。
- **设计师（条件通过）**：这是"工程师为工程师设计的方便"；curl 是流失悬崖→改"贴示例/文档链接"删 curl 字眼；"核对参数"普通用户判断不了→改"AI 一句话总结+测一下"；通用回退是审美黑洞→标记临时态；**定稿前必出 5 张样张**（预设主入口/自助入口/4态测试卡/回退节点对比/全流程层级）。
- **PM（方向对、范围错位）**：架构≠产品；视频必须提前（最大判断错误）；P3 schema-derive 砍/延；描述符当内部基础设施别当主线；每周要有用户可见产出；MVP=kie极致(含视频)+2-3视频家+轻量自助+图片预设顺带。
- **前端（可行）**：identity 层基本不用动；OnboardingWizard 已有预设+测试+人话报错可复用；难点=docs tab 从流式黑盒改"预填+核对"、schema→控件复用 `buildDynamicControls`、curl 反推的"响应路径靠点选 JSON 树"；**规则 1 风险：`FieldDefinition` vs `ModelParameterControl` 两套、`src/ui/onboarding/*` 与档案同名文件**；和并行 AI 撞车，P0 先动数据+主进程。
- **后端（可行，异步被低估）**：现有 mapping 系统=描述符 v0.5，扩不重造；解释器拆 `normalizeResult/checkStatus/secondHop` 防巨壳；异步要 `taskStore`(持久)+`poller`+`nomi-task://`代理，`taskCache` 纯内存要替；4 处新安全审计点（schema 缓存不存用户内容、task 协议防伪造、二段下载结果 URL 不回渲染层、curl 反推前脱敏 key）。
- **真实用户（3/5 分）**：预设路 4.5 分、自助路(curl)1.5 分被拉低；90% 创作者只想 kie 一把 key 丝滑；视频是现在最想要的；放弃点=预设没我的中转站就让贴 curl、报错看不懂；想要"像加微信好友"的接入；预设按中国创作者真实频次排；长尾变成"一键求助你们加"。

## 9. 成功指标（CTO 补）
- P0：kie 一把 key 从 0 到"出图**和出视频**" ≤ 5 分钟、出错有人话提示。
- P2：新接入一个 OpenAI 兼容家**代码量=0**（只加描述符数据）。
- P1：视频任务重启 app 后能继续（持久化生效）。
- P3：预设覆盖 ≥ 主流中转站 N 家（按创作者调研定 N）；"求助"到"团队加上预设"闭环时延 ≤ 1 版本。
