# 让用户极方便地接入"任意中转站的任意模型"（图片/视频/音频）

> ⛔ **已撤销（2026-06-07）**：本文的「描述符 + 通用解释器接长尾」方向本轮撤销——「对未知模型的通用接入」工程上不可行、无法 100% 验证（违反 P3）。
> 取代方案：**策展两家（kie + apimart）**，见 `docs/plan/2026-06-07-apimart-curated-onboarding.md`。本文保留为研究材料，请勿据此开工。

> 日期：2026-06-06（2026-06-07 补"自定义模型"已确认方向）｜ 状态：**方向已拍（见下"已确认产品方向"），待与"图像档案/onboarding"线（另一 AI 在改）对齐分工后执行**
> 方法：真机走查接入流程（以用户视角逐屏体验）+ 读 runtime/archetype/onboarding 代码。
> 北极星：**用户能接入任何中转站的任何模型，并且极其方便**（接近"贴个 key 就全有"）。
> 基线决定（用户已拍）：**kie 作基础**——用户连上 kie 就能用内置那几个；其余按本文档推进。

## 已确认产品方向（用户拍板，2026-06-07）

> **必须支持用户自定义接入自己的图片 / 视频（及后续音频）模型**——这是「通用第一」的核心，不做 = 把
> Nomi 做成只绑 kie 的封闭花园，与本地优先定位冲突。来源：有用户明确提出"能不能自定义图片/视频模型"。
>
> 关键认知（已真机+读码确认，别再当"要从零做"）：
> - **现在已部分支持**：「添加模型」对话框已有"图片/视频模型"tab；底层有通用 OpenAI 兼容 transport
>   （`/v1/images|videos/generations`，无 mapping 时自动走）→ OpenAI 兼容的自定义图片模型基本接上即用。
> - **缺的是"方便 + 覆盖"**，不是"能不能"：现流程是"贴文档 URL + AI 读文档"重路径，没有文本那套
>   预设/拉取/识别。本文档 §3/§4 就是把它做"方便"的路线。
> - **两个铁律**：① 图片优先、视频随后（图片有通用 transport 最快见效；视频 API 碎片化靠适配器/包逐步啃，
>   别承诺一把梭）；② **自定义模型别做成二等公民**——要能按 modelKey 吃到档案 UI，认不出才退到裸参数。

---

## 0. 一句话结论

> "选预设 + 贴 key + 拉取模型 + 自动识别"这套**极方便的流程，目前只给了文本模型；图片/视频走的是"贴文档 URL + AI 读文档"的重流程；音频根本没有。** 而底层其实**已有通用 OpenAI 兼容 transport**（图片可复用）。所以核心工作 = **把文本那套便利流程，铺到图片/视频/音频**，让 AI 读文档退居"非标兜底"。

---

## 1. 用户旅途走查（真机，2026-06-06）

任务：`我有一个中转站的 key，我想把它的图片/视频/音频模型接进来用`。

### J-文本（现状：✅ 极顺）
工作台顶栏「模型接入」→「添加模型」→ **文本模型** tab：
- 一排**供应商预设**：OpenAI / Claude / Gemini / OpenRouter / SiliconFlow / Kimi / 智谱 GLM / DeepSeek / 火山·Doubao / 阿里百炼 / Groq / **自定义·中转站**。
- 选一个 → **BaseURL 自动填**；选"自定义/中转站"→ 清空让你贴自己的地址。
- 贴 **API Key** → 点 **拉取可用模型**（`/v1/models`）→ 下拉选模型 → 测试连接 → 保存。
- **体感：~30 秒，中转站友好，零知识门槛。**

### J-图片/视频（现状：❌ 重且脆）
同对话框切 **图片/视频模型** tab：
- **没有任何供应商预设。**
- 字段变成：**文档地址**（"粘贴这个模型的官方 API 文档页"）+ **API Key**。
- 提示"AI 读取文档，自动给出参数和配置"。
- **体感卡点**：① 用户得自己去**找到并粘贴**某个模型的 API 文档 URL（多数用户根本不知道在哪/是哪页）；② 全押在 agent 把文档解析对——解析歪了就卡死、无明确补救；③ **没有"我用的是 OpenRouter/某中转"这种一键捷径**，哪怕那家就是标准 OpenAI 兼容。

### J-音频（现状：❌ 不存在）
对话框只有 文本 / 图片·视频 两个 tab，**没有音频**。代码侧仅有 `taskKind: "text_to_audio"` 的计费占位，档案的 `ArchetypeTransportTaskKind` 与通用 transport 都不含音频。

### J-kie 基线（现状：⚠️ 半截）
右侧"模型设置"里 kie 的 8 个模型**已是种子、列在那里**；但要用得有 kie key，而 key 的录入并没有一个干净的"连接 kie · 贴 key"入口（图片/视频 tab 是文档 URL 流，对不上"我就想连 kie"）。

---

## 2. 为什么会这样（根因，已读代码确认）

**根本症结：媒体生成没有像聊天那样的唯一通用线缆标准。** 文本人人都是 `/v1/chat/completions` → 一套流程通吃。图片/视频/音频各家请求/响应/异步轮询都不同。

但底层其实已经做了**两层 + 通用兜底**，只是 onboarding UI 没把它用起来：

- **第二层 模型档案（identity，供应商无关）** `src/config/modelArchetypes/`：按 `modelKey` 识别 → 套模式/参考槽/参数 UI。✅
- **第一层 transport**：
  - **有 mapping**（`(vendor, taskKind[, modelKey])`）→ 用该供应商的自定义调用（kie 的异步 createTask 走这条）。
  - **无 mapping → 通用 OpenAI 兼容兜底**（`runtime.ts:2058+`）：文本 `/v1/chat/completions`、图片 `/v1/images/generations`、视频 `/v1/videos/generations`。
- **结论**：**标准 OpenAI 兼容的中转，图片其实已经不需要建 mapping**（走通用兜底即可）！kie 要 per-model mapping 只因它非标。**onboarding 的图片/视频 tab 却没给"标准中转一键接"的路，反而默认上了最重的 agent 读文档**——这是错配。

---

## 3. 目标体验（统一成文本那样）

> 接任意媒体模型 = **选供应商（预设/自定义中转）→ 贴 key → 拉取模型 → 自动识别档案** → 用。
> "AI 读文档自动配" 退化为**非标供应商的兜底**，不是默认。

---

## 4. 方案（分阶段，按 ROI；每阶段落地前与另一 AI 的接入线对齐）

### P0 — kie 基线一键化（用户已拍的基础）
- 把"连接 kie"做成**一等入口**：一个 kie 预设/按钮 → 贴 kie key → 内置 8 个种子模型立即可用（点亮）。
- 价值：开箱默认路径顺滑；其余供应商在此之上扩展。

### P1 — 把"预设 + 拉取 + 识别"铺到图片/视频 tab（最高 ROI）
- 图片/视频 tab **复用文本 tab 的流程**：供应商预设（含中转）+ BaseURL + key + **拉取可用模型** + 测试连接。
- 拉取回来的模型 id **按 modelKey 自动比对档案** → 认得的点亮模板 UI；认不得的走**通用回退**（通用 `/v1/images|videos/generations`，能用）。
- **图片今天就能基本一把梭**（通用 transport 已在）；视频部分可走通用、部分仍需 P3 适配器。
- agent 读文档：从"默认"降级为 tab 内一个"**这家是非标？让 AI 读文档**"的兜底入口。

### P2 — 可导入的"接入包"（"把市面中转都放进来"的落地）
- 复用**已存在**的 `exportModelCatalogPackage` / `importModelCatalogPackage`。
- 出**官方包**（apimart / aihubmix / fal / replicate / openrouter 媒体…）：`{供应商 + 它的图/视/音模型 + transport}` 一个 `.json`，**一键导入**。
- 社区可维护补长尾。这是"一次性整好"最省力的杠杆。

### P3 — transport 适配器库（消灭"逐个建 mapping"）
- 把现在写死的 kie 异步 pattern **泛化成几个有名字、可填参的适配器**：`openai-images`(同步) / `openai-tts`(同步) / `async-task`(create+轮询+取结果，端点/字段名可填，覆盖 kie/fal/replicate/runway 风格)。
- 接非标模型 = **选一个适配器 + 填几个字段**（或 agent 自动推断成这份配置），而不是手写 mapping。这就是"第一层可继承"。

### P4 — 音频（绿地，需先打地基）
- 加 **音频档案 kind** + `text_to_audio` 进 `ArchetypeTransportTaskKind` + 通用 **`/v1/audio/speech`**(TTS 标准) transport；对话框加**音频 tab**。
- 然后音频自动吃到 P1/P2/P3 的便利（预设/拉取/包/适配器）。

---

## 5. 不动什么 / 风险

- **不擅自改另一 AI 正在写的接入代码**（archetype / onboarding / runtime transport 是它的活）——本文档是对齐用。
- 视频/音频的"通用 transport"覆盖面有限（端点不统一）——P1 对视频是"能走则走"，真正长尾靠 P2 包 + P3 适配器，别承诺"视频也一把梭"。
- 通用图片 transport 的**响应解析要加固**（各家图 url 位置不一），否则"调通但取不到结果"。

## 6. 待用户/对齐拍板

1. 方向认可"统一成文本那套（预设+拉取+识别），agent 读文档降级为兜底"吗？
2. 阶段顺序：P0→P1→P2→P3→P4 是否同意？还是先 P0+P1（图片便利化）见效，再排其余？
3. 这条线和另一 AI 的"图像档案/接入"工作怎么分工（谁主导 transport 层重构）？
