@henjicc/ai-sdk 0.2.8

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//351/255/224/346/220/255.md

@@ -0,0 +1,207 @@
+# 魔搭 ModelScope · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-30 |
+| 供应商类型 | 开源模型托管平台（API-Inference 服务） |
+| 覆盖模态 | **仅图片**（无视频、无音频） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+| 结算方式 | **魔粒积分，不是货币** |
+
+## 1. 接入协议
+
+- **Base URL**：`https://api-inference.modelscope.cn`
+- **鉴权**：`Authorization: Bearer <MODELSCOPE_TOKEN>`
+- **提交**：`POST /v1/images/generations`，请求头 `X-ModelScope-Async-Mode: true` → 返回 `{ "task_id": "..." }`
+- **查询**：`GET /v1/tasks/<task_id>`，请求头 `X-ModelScope-Task-Type: image_generation`
+- **状态字段**：`task_status`，枚举 `SUCCEED` / `FAILED`（官方示例每 5 秒轮询一次）
+- **结果字段**：`output_images`（字符串数组）
+
+### 提交路由的历史问题（已修正）
+
+代码曾把提交路由写成 `/api/v1/jobs/createTask`——那是 **KIE 的路由格式**，在一次批量改动里被复制串了供应商。已改为官方的 `/v1/images/generations`。
+
+该常量现在只有 `packages/ai-sdk/src/catalog/modelscope/utils.ts` 一份实现；所有魔搭模型的真实 builder 直接复用它。`packages/ai-sdk/tests/catalog/modelscope.test.ts` 同时验证共享函数和 catalog builder，避免路由或图片来源静默分叉。
+
+> ⚠️ 修正**尚未用真实 token 实测确认**——本机网络无法连通 `api-inference.modelscope.cn`，且未配置魔搭 Token。依据是官方文档与每个模型页示例代码的一致写法（无一例外）。首次真实调用时优先验证这一项。
+
+## 2. 硬前提（不满足则完全不可用）
+
+1. 魔搭账号**必须绑定阿里云账号**
+2. 该阿里云账号**必须已完成实名认证**
+
+## 3. 文件上传
+
+魔搭没有独立的文件上传端点。官方做法是把本地图片转成 `data:<mime>;base64,...` 直接放进 `image_url` 字段，文档提供了 `image_to_data_url()` 工具函数。
+
+本项目的处理（`upload.ts` → `uploadForHostedUrl`）：**优先借用 KIE 的上传服务**换公网 URL，KIE Key 未配置或上传失败时**静默退回 data URI**。因为有兜底，魔搭模型不会像 PPIO 那样因为缺 KIE Key 直接失败。
+
+请求体里图片来源有三个键，builder 必须都认：生成页提交是 `uploadedFilePaths`，画布节点是 `images`，旧工程可能直接存 `image_url`。历史动态运行时副本曾漏掉 `uploadedFilePaths`；SDK 直连后已删除该副本，并由真实 catalog builder 测试锁定行为。
+
+## 4. 请求参数（全模型通用）
+
+魔搭 API-Inference 是统一接口，所有图像模型共用同一套参数，差异只在 `model` 值和尺寸上限。
+
+| 字段 | 类型 | 必填 | 默认 | 约束 |
+|---|---|---|---|---|
+| `model` | string | ✅ | — | 魔搭 AIGC 模型 ID，如 `Qwen/Qwen-Image` |
+| `prompt` | string | ✅ | — | < 2000 字符；多数模型英文效果更好 |
+| `negative_prompt` | string | | — | < 2000 字符 |
+| `size` | string | | — | `WxH` 格式，**上限按模型分档，见下表** |
+| `seed` | int | | — | [0, 2³¹−1] |
+| `steps` | int | | 30 | [1, 100] |
+| `guidance` | float | | 3.5 | [1.5, 20] |
+| `image_url` | string \| **string[]** | | — | 仅图片编辑模型；公网 URL 或 base64 data URL |
+| `loras` | string \| dict | | — | 单个 `"<repo-id>"`；多个 `{"<id1>":0.6,"<id2>":0.4}`；**最多 6 个，权重和必须 = 1.0**，须与基模型兼容 |
+
+**没有 `n` 或图片数量参数——一次只出一张。**
+
+### `image_url` 支持数组（已确认）
+
+`Qwen/Qwen-Image-Edit-2509` 的官方示例代码里 `image_url` 就是数组，并明确给出了双图编辑的注释示例。官方参数表把类型写成 `string` 是**表述滞后**，以模型页示例为准。本项目发送数组的做法是正确的。
+
+### 尺寸上限分档
+
+| 模型family | `size` 范围 |
+|---|---|
+| SD 系列 | [64×64, 2048×2048] |
+| FLUX | **[64×64, 1024×1024]** |
+| Qwen-Image | [64×64, 1664×1664] |
+| Z-Image-Turbo | **[512×512, 2048×2048]** |
+
+> 已按模型分档：`buildModelscopeRequest` 接受 `sizeBounds`，各模型在 builder 里下发自己的上下界。此前统一用 `[64, 2048]`，FLUX 超过 1024 会被拒、Z-Image-Turbo 低于 512 不合法。
+
+## 5. 计费：魔粒，不是钱
+
+魔搭**不按人民币计价、没有充值入口**。消耗的是「魔粒」积分，主要靠每日登录和社区行为免费获取。
+
+### 扣减档位
+
+| 档位（`CostTier`） | 魔粒/次 | 项目已适配模型 |
+|---|---|---|
+| 轻量模型 | 0.5 | — |
+| 主流模型 `standard` | 1 | Z-Image-Turbo、FLUX.1-Krea-dev、majicMIX_realistic、14_ckpt_SD_XL |
+| 旗舰模型 `ultra` | 2 | Qwen-Image、Qwen-Image-Edit-2509 |
+
+### 魔粒获取
+
+| 行为 | 额度 | 有效期 | 频次 |
+|---|---|---|---|
+| 注册并登录 | **200/日** | 24 小时 | 每日 1 次 |
+| 绑定阿里云账号 | **+50/日** | 24 小时 | 每日 1 次 |
+| 验证邮箱 / 编辑个人介绍 / 配置个人主页 | 各 50 | 90 天 | 各首次 |
+| 发表评论 | 5/次 | 短期 | ≤2 次/日 |
+| 收藏 / 喜欢 | 2/次 | 短期 | ≤20 次/日 |
+| 邀请好友 / 受邀注册 | 20/人、50 | 长期 | 50 人/月、首次 |
+
+**日常稳态免费额度 = 250 魔粒/天**（登录 200 + 绑定阿里云 50，均为短期魔粒，24 小时过期不累积）。换算到本项目：
+
+- 旗舰档（Qwen-Image / Qwen-Image-Edit-2509）：**约 125 次/天**
+- 主流档（Z-Image-Turbo / FLUX / majicMIX / SDXL）：**约 250 次/天**
+
+### 其他计费规则
+
+- **没有固定的每日调用次数上限**，上限由魔粒余额决定
+- 短期/长期魔粒消耗时等价，系统自动优先扣最临近过期的
+- **失败返还**：系统原因导致的推理失败全额返还；用户主动取消的推理任务也全额返还
+- **并发是动态限流的**，官方只承诺「保障开发者单并发正常使用」，并明确说明「请勿用于需要高并发以及 SLA 保障的线上任务」
+
+> 已修正：`Currency` 类型增加非货币单位 `魔粒`，`priceDisplay` 对其不做汇率换算、按「数量 + 单位」渲染。固定 catalog 模型按官方档位标注（Qwen 系 2 魔粒，其余 1 魔粒）。自定义入口不再假定主流档 1 魔粒：保存前校验成功时持久化接口返回的 `CostTier` 与 `EstimatedMagicGrainCost` 并交给 SDK 计价；旧记录或校验为 `unknown` 时不显示确定金额，避免误导。
+
+### 高并发替代路径：API-Provider
+
+在个人中心托管外部供应商（DashScope、DeepSeek 等）的 API Key，然后用 `model='<模型ID>:<Provider名>'` 调用，走同一套接口和魔搭 Token 鉴权，**不受免费流控限制，平台不收费**，费用由外部供应商结算。目前官方文档只演示了 LLM，未见图像模型的 Provider 支持。
+
+## 6. 可用性判定方法
+
+「模型在魔搭有页面」和「模型支持 API-Inference 调用」是两回事，必须确认后者。权威判定接口（无需登录）：
+
+```
+GET https://www.modelscope.cn/api/v1/inference/list_model_providers?ModelId=<id>
+```
+
+三种响应（2026-08-26 实测）：
+
+| 情况 | 响应 |
+|---|---|
+| 支持 API-Inference | `200` + `Data.Providers` 数组，含 `CostTier` 与 `EstimatedMagicGrainCost` |
+| 模型存在但未开放 API-Inference | `200` + `Data.Providers: null, TotalCount: 0` |
+| **模型 ID 查不到** | **`HTTP 500`**（不是 404，也不是 200+空结果；用多个不存在的 ID 复现一致） |
+
+500 同时也是通用服务端错误码，无法从状态码本身区分「拼错了」和「魔搭挂了」，提示文案需要同时覆盖两种可能。
+
+另有 `GET /api/v1/inference/<ns>/<name>/api_inference_example` 返回官方示例代码与 `InferenceType`。
+
+**自定义模型入口已接入该校验**（`src/services/modelscopeCustomModels/availability.ts`，走 `nativeFetch` PAL 通道，未新增 IPC）：保存前查询，`unavailable` 与 `not-found` 直接拦下并给出对应提示；`available` 将 `CostTier` 与 `EstimatedMagicGrainCost` 随模型配置持久化并注册到 SDK；`unknown`（断网/超时/其他非 2xx）放行但警告，并把价格保持为未知——校验跑不通是我们这边的问题，不该因此挡住用户，也不能伪装成 1 魔粒。
+
+> API-Inference 只覆盖魔搭挑选的一个子集（依据点赞/下载热度），官方明确说明「随着新模型的推出，比较早的模型可能逐渐从 API-Inference 下架」。已实测不支持的热门模型包括 `black-forest-labs/FLUX.1-dev`、`FLUX.1-Kontext-dev`、`Tencent-Hunyuan/HunyuanImage-3.0`、`stabilityai/stable-diffusion-3.5-large`、`HiDream-ai/HiDream-O1-Image`。
+>
+> 注意 `black-forest-labs/FLUX.1-dev` 曾被用作添加表单的占位示例，而它恰恰**不支持** API-Inference，已改为 `Tongyi-MAI/Z-Image-Turbo`。
+
+## 7. 在售模型（已适配）
+
+| Model ID | 类型 | 档位 | 魔粒/次 |
+|---|---|---|---|
+| `Qwen/Qwen-Image` | 文生图 | ultra | 2 |
+| `Qwen/Qwen-Image-Edit-2509` | 图生图 | ultra | 2 |
+| `Tongyi-MAI/Z-Image-Turbo` | 文生图 | standard | 1 |
+| `black-forest-labs/FLUX.1-Krea-dev` | 文生图 | standard | 1 |
+| `MusePublic/majicMIX_realistic` | 文生图 | standard | 1 |
+| `MusePublic/14_ckpt_SD_XL` | 文生图 | standard | 1 |
+
+全部经 `list_model_providers` 确认当前可用。
+
+### 当前可用、项目尚未接入
+
+| Model ID | 类型 | 魔粒/次 | 说明 |
+|---|---|---|---|
+| `Qwen/Qwen-Image-2512` | 文生图 | 2 | Qwen-Image 的 12 月更新版，可直接替代 `Qwen/Qwen-Image` |
+| `Qwen/Qwen-Image-Edit-2511` | 图生图 | 2 | 2509 的直接后继，同样支持数组多图编辑 |
+| `krea/Krea-2-Turbo` | 文生图 | 1 | |
+| `black-forest-labs/FLUX.2-klein-base-9B` | 文生图 | 2 | |
+| `FireRedTeam/FireRed-Image-Edit-1.1` | 图生图 | 2 | |
+| `Tongyi-MAI/Z-Image` | 文生图 | 1 | 非 Turbo 版 |
+| `MAILAND/majicflus_v1` | 文生图 | 1 | |
+
+## 8. 主清单模型的覆盖情况
+
+项目「常用优秀模型清单」共 18 个，**魔搭只提供其中 1 个**：
+
+| 清单模型 | 魔搭 |
+|---|---|
+| Z-Image Turbo | ✅ 提供，见 [Z-Image-Turbo_魔搭.md](../Z-Image-Turbo/Z-Image-Turbo_魔搭.md) |
+| 其余 17 个 | ❌ 全部没有 |
+
+原因是结构性的：魔搭 API-Inference 只服务**魔搭上托管的开源权重模型**，而清单里基本全是闭源商业 API 模型。站内搜到的 Seedream / Nano Banana / Midjourney / Grok 条目**全是社区用户上传的风格 LoRA**，不是模型本体，也不支持 API-Inference。
+
+**视频类 9 个全部不可能**：魔搭 API-Inference 根本不提供视频生成——文档只定义了 `image_generation` 一种任务类型，覆盖范围明确写的是「开源大语言模型（LLM），多模态模型（MLLM），以及 AIGC 专区**文生图**模型」。MiniMax H3 是唯一一个权重真实存在于魔搭的清单视频模型，但不在 API-Inference 范围内。
+
+### 关于 Qwen Image 3.0
+
+**魔搭上没有 Qwen Image 3.0**，`Qwen/Qwen-Image-3.0` 这个 ID 不存在。
+
+Qwen 官方在魔搭的图像模型只有 4 个：`Qwen/Qwen-Image`、`Qwen/Qwen-Image-Edit-2509`、`Qwen/Qwen-Image-Edit-2511`、`Qwen/Qwen-Image-2512`。其中 `Qwen-Image-2512` 的模型卡自述是「Qwen-Image 文生图基础模型的 12 月更新版」，**不是** 3.0。清单里的 Qwen Image 3.0 是通义的闭源商业版本，两条线不同。
+
+> 若要在魔搭侧跟进 Qwen 图像新版本，正确的 ID 是 `Qwen/Qwen-Image-2512`（文生图）和 `Qwen/Qwen-Image-Edit-2511`（图片编辑）。
+
+## 9. 适配要点
+
+- 全部模型共用同一个端点与同一套参数，**只有 `model` 值和尺寸上限不同**；不要为每个模型复制一份 builder。
+- 尺寸边界必须按模型分档，不能统一用 [64, 2048]。
+- 计价不能用货币表达，应按魔粒档位展示。
+- 自定义模型入口在保存前调 `list_model_providers` 校验可用性；成功时复用并持久化返回的 `CostTier` / `EstimatedMagicGrainCost`，校验失败（`unknown`）时放行并警告、价格保持未知，不要当成不支持或默认成 1 魔粒。
+- 项目默认隐藏的参数（`seed`、负面提示词）：魔搭两个字段都有，按项目约定**不显示、不请求**。
+
+## 10. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| API-Inference 介绍与完整参数表 | https://www.modelscope.cn/docs/model-service/API-Inference/intro | 否 |
+| API-Inference 限制与覆盖范围 | https://www.modelscope.cn/docs/model-service/API-Inference/limits | 否 |
+| 魔粒说明（获取与消耗规则） | https://www.modelscope.cn/docs/magicube/intro | 否 |
+| API-Provider（高并发替代路径） | https://www.modelscope.cn/docs/model-service/API-Inference/api-provider | 否 |
+| 模型可用性判定接口 | https://www.modelscope.cn/api/v1/inference/list_model_providers?ModelId=&lt;id&gt; | 否 |
+| 官方示例代码接口 | https://www.modelscope.cn/api/v1/inference/&lt;ns&gt;/&lt;name&gt;/api_inference_example | 否 |
+| Qwen-Image-2512 模型卡 | https://www.modelscope.cn/models/Qwen/Qwen-Image-2512 | 否 |
+| Token 管理 | https://www.modelscope.cn/my/myaccesstoken | **是** |

package/docs/model-adaptation//346/226/207/346/241/243/351/207/207/351/233/206/346/211/213/345/206/214.md

@@ -0,0 +1,311 @@
+# 文档采集手册
+
+> 这份手册只记**做过一遍才知道**的东西。目标：下次做模型调研时，不再重新踩一遍坑。
+> 最后更新：2026-08-28（补充 SDK 官方资料先行、事件契约与首发验证规范）
+
+---
+
+## 一、怎么发现文档：先拿全量索引，别靠单页链接往下点
+
+**最大的坑：一个模型往往对应多份文档、多个端点，只看用户给的那一个链接必然漏。**
+上一版适配 Midjourney 只做了 2 个端点，实际有 18 个；Grok Imagine 2.0 漏掉了整块图层选区编辑。
+
+### 三个平台都有 `llms.txt` 全量索引，第一步就抓它
+
+```bash
+curl -sL https://docs.apimart.ai/llms.txt -o apimart-index.txt   # 171 行，含全部页面
+curl -sL https://docs.kie.ai/llms.txt     -o kie-index.txt       # 517 行
+curl -sL https://fal.ai/llms.txt          -o fal-index.txt       # 只是代表性列表，不全，见下
+```
+
+然后**按前缀过滤出目标模型的所有页面**，而不是凭印象猜：
+
+```bash
+grep -oE "https://docs\.apimart\.ai/en/api-reference/(images|videos)[^)]*\.md" apimart-index.txt | sort -u
+grep -oE "https://docs\.kie\.ai/cn/market/[^)]*\.md" kie-index.txt | sort -u
+```
+
+### 发现「同一个模型有多份文档」的信号
+
+| 信号 | 例子 |
+|---|---|
+| 同目录下多个页面 | `images/midjourney/{generation,imagine,blend,describe,upscale,...}` 18 个 |
+| `official` / `ext` 后缀 | `gpt-image-2/{generation,official}`、`grok-imagine-2.0-ext/{generation,layer-region-edit,official}` |
+| `-lite` / `-fast` / `-mini` 变体 | `gemini-3.1-flash/{generation,generation-lite}` |
+| 平级的辅助能力 | `minimax-h3/{generation,context-ir,regeneration}`、`seedance-2-0/private-avatar` |
+| KIE 把能力拆成独立 model | `kling-3.0-omni/{text-to-video,image-to-video,reference-to-video,transformation}` |
+
+**判断标准**：只要索引里同一个模型名下有第二个页面，就必须打开看，哪怕名字看起来像「辅助说明」。
+
+### Fal 的索引不全，要靠探测
+
+`fal.ai/llms.txt` 只列代表性端点。Fal 的端点是**可组合路径**（`<厂商>/<模型>/<档位>/<输入形态>`），用 HTTP 状态码探测存在性最快：
+
+```bash
+for p in bytedance/seedance-2.0/text-to-video bytedance/seedance-2.0/image-to-video \
+         bytedance/seedance-2.0/reference-to-video; do
+  code=$(curl -sL -o /dev/null -w "%{http_code}" "https://fal.ai/models/$p/llms.txt")
+  echo "$code  $p"
+done
+```
+
+常见组合维度：`{text-to-video, image-to-video, reference-to-video}`、`{pro, standard}`、`{turbo}`、`{edit}`。
+探测出来的 404 也是信息——比如 `google/gemini-omni-flash/text-to-video` 不存在，说明 Fal 上做不了纯文生视频。
+
+---
+
+## 二、怎么找文档：优先拿原始 Markdown，浏览器是最后手段
+
+### 1. 文档站：URL 后面加 `.md` 就是原文
+
+`docs.apimart.ai` 和 `docs.kie.ai` 都支持，且 `/cn/` 前缀是中文版：
+
+```bash
+curl -sL "https://docs.apimart.ai/cn/api-reference/images/midjourney/imagine.md"
+curl -sL "https://docs.kie.ai/cn/market/kling/kling-3-0.md"
+```
+
+**比浏览器渲染好在**：拿到的是完整原文（含被折叠的参数、被 Tab 隐藏的示例），不会因为 UI 折叠而丢内容。
+
+### 2. Fal：每个模型的 `llms.txt` 是权威实时 schema
+
+```bash
+curl -sL "https://fal.ai/models/<endpoint-id>/llms.txt"
+```
+
+它由平台元数据实时生成，**不会与线上端点漂移**，且**同时包含 schema 和价格**。
+
+枚举值被折叠成 `ImageSize | Enum` 时，去拿 OpenAPI 才能看到具体取值：
+
+```bash
+curl -sL "https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=bytedance/seedream/v5/pro/text-to-image"
+# → image_size 的真实枚举：square_hd / square / portrait_4_3 / ... / auto_1K / auto_2K
+```
+
+### 3. 官方控制台是 SPA，curl 拿不到正文——去找它的内容接口
+
+火山方舟的文档页 `curl` 只能拿到 18 个字符。用 ego-browser 打开后列出网络请求，就能找到真正的内容 API：
+
+```js
+await js(`performance.getEntriesByType('resource').map(e => e.name)
+  .filter(n => /api|doc|content/i.test(n))`)
+```
+
+火山方舟的结果（**可直接 curl，无需登录**）：
+
+```bash
+# 单篇文档全文（Result.MDContent 是完整 Markdown，Result.UpdatedTime 是官方更新时间）
+curl -sL "https://docs.volcengine.com/api/doc/getDocDetail?LibraryID=82379&DocumentID=1541523&type=online"
+# 全库目录（用来找价格页、模型列表页的 DocumentID）
+curl -sL "https://docs.volcengine.com/api/doc/getDocList?LibraryID=82379&DataSchema=all_second_nav&type=online"
+```
+
+常用 DocumentID：`1541523` 图片生成 API、`1544106` 模型价格、`1330310` 模型列表。
+
+**通用做法**：任何 SPA 文档站，都先用这招找内容 API，找到就退回 curl，别在浏览器里跟折叠 UI 搏斗。
+
+### 4. 阿里云百炼是 SSR，直接 curl 就有全文
+
+```bash
+curl -sL "https://help.aliyun.com/document_detail/3047054.html"   # 会 302 到 slug 页
+curl -sL "https://help.aliyun.com/zh/model-studio/model-pricing"  # 价格页，3.4 MB HTML
+```
+
+用户给的控制台链接里的 `url=3047054` 就是 `document_detail` 的 ID，可以直接换算。
+
+### 5. 价格页只能用浏览器（ego-browser）
+
+APIMart 和 KIE 的定价都是前端渲染的：
+
+- **APIMart**：图像/视频/LLM/音频是**标签页**，切了才渲染。用 `js()` 找文本等于「视频」的可见元素点一下，等 4 秒再取 `document.body.innerText`
+- **KIE**：441 个模型的**搜索框** + 分页。`fillInput('input[type="text"]', 'seedance')` → 等 3.5 秒 → 取全文
+  - ⚠️ 注意底部的 `1-25 of 28`：**默认每页 25 条，会漏**。换更精确的搜索词（如 `bytedance/seedance-2,` 带逗号）把结果压到 25 条以内
+
+把 ego-browser 的输出落盘要这样写（`cliLog` 走的是进程输出）：
+
+```bash
+ego-browser nodejs > out.txt 2>&1 <<'EOF'
+const task = await useOrCreateTaskSpace(<空间id>)
+cliLog(await js(`document.body.innerText`))
+EOF
+```
+
+---
+
+## 三、怎么处理文档：两个提取脚本 + 一轮交叉校验
+
+### 1. KIE 文档是 OpenAPI YAML，用脚本提 schema
+
+KIE 每页正文是一个 ```` ```yaml ```` 代码块包着的完整 OpenAPI。手读会漏字段，**必须用脚本递归展开**（含 `enum` / `default` / `minItems` / `maxItems` / 嵌套对象）：
+
+```python
+# kie_extract.py  —— 用法：python3 kie_extract.py <文件...>
+import sys, re, yaml, json
+
+def fmt(name, sch, indent=0, req=()):
+    pad = '  ' * indent
+    typ = sch.get('type', '')
+    if 'enum' in sch:    typ += ' enum=' + json.dumps(sch['enum'], ensure_ascii=False)
+    if 'default' in sch: typ += f" default={json.dumps(sch['default'], ensure_ascii=False)}"
+    for k in ('minimum','maximum','minLength','maxLength','minItems','maxItems'):
+        if k in sch: typ += f" {k}={sch[k]}"
+    desc = re.sub(r'\s*\n\s*', ' ', (sch.get('description') or '').strip())
+    print(f"{pad}- {name} [{typ}] {'必填' if name in req else '可选'}: {desc[:1400]}")
+    if sch.get('type') == 'object' and 'properties' in sch:
+        r = tuple(sch.get('required', ()))
+        for k, v in sch['properties'].items(): fmt(k, v, indent + 1, r)
+    if sch.get('type') == 'array' and isinstance(sch.get('items'), dict):
+        it = sch['items']
+        if it.get('type') == 'object' and 'properties' in it:
+            r = tuple(it.get('required', ()))
+            for k, v in it['properties'].items(): fmt(k, v, indent + 1, r)
+
+for path in sys.argv[1:]:
+    t = open(path, encoding='utf-8').read()
+    m = re.search(r'```yaml\n(.*?)\n```', t, re.S)
+    if not m: print(f'{path}: 无 OpenAPI 块'); continue
+    d = yaml.safe_load(m.group(1))
+    print('\n=====', path.split('/')[-1])
+    for p, ops in d.get('paths', {}).items():
+        for method, op in ops.items():
+            print(f"### {method.upper()} {p} | {op.get('summary')} | {op.get('operationId')}")
+            rb = op.get('requestBody', {}).get('content', {}).get('application/json', {}).get('schema')
+            if rb:
+                req = tuple(rb.get('required', ()))
+                for k, v in (rb.get('properties') or {}).items(): fmt(k, v, 1, req)
+```
+
+**`input` 是 `oneOf` 的要单独展开**（KIE 用它表达「二选一的输入形态」，如 Kling Omni 的「单张首帧」vs「仅视频输入」）——上面脚本会跳过，需要另外 dump `schema['properties']['input']`。
+
+对比多个变体的字段差异，一行就够：
+
+```bash
+for f in seedance-2 seedance-2-fast seedance-2-mini; do
+  echo -n "$f: "; python3 kie_extract.py raw/$f.md | grep -oE "^    - [a-z_]+" | tr -d ' -' | tr '\n' ' '; echo
+done
+# 一眼看出 mini 少了 return_last_frame
+```
+
+### 2. APIMart 文档是 MDX，代码示例占 80%，先剥掉
+
+每页会把同一个请求写成 15 种语言的示例，正文被淹没：
+
+```python
+# apimart_strip.py —— 保留 bash/json，其余语言的代码块换成占位符
+import sys, re
+for path in sys.argv[1:]:
+    t = open(path, encoding='utf-8').read()
+    t = re.sub(r'```([^\n]*)\n(.*?)```',
+               lambda m: m.group(0) if m.group(1).startswith(('bash','json'))
+                         else f'\n[[{m.group(1).strip()} 示例已省略]]\n', t, flags=re.S)
+    print(re.sub(r'\n{3,}', '\n\n', t))
+```
+
+之后配合 `sed -n '/^## Body/,$p'` 直接跳到参数区。
+
+### 3. 必做的三项交叉校验
+
+| 校验 | 为什么 | 这次的实例 |
+|---|---|---|
+| **API 文档正文价格 vs 定价页价格** | 文档正文更新慢，经常是过期价 | Seedream Pro 文档写 $0.045/$0.09，定价页是 $0.02928/$0.05856 |
+| **同一模型跨供应商的取值集合** | 名字一样但取值/默认值经常不同 | Lite 分辨率官方是 2K/3K/4K，旧文档抄成了 1K/2K；`adaptive`(APIMart/KIE) vs `auto`(Fal)；`duration` 整数 vs 字符串 |
+| **schema 内部自相矛盾** | 供应商文档确实会写错 | KIE Qwen3-Pro 的 `enum` 与 `default` 不一致；KIE z-image 的 `aspect_ratio` 描述提到 `auto` 但枚举里没有 |
+
+**处理原则**：两处不一致时**两个都写进文档**并说明以哪个为准；文档自相矛盾时标注「接入前实测确认」，不要替供应商猜。
+
+---
+
+## 四、SDK 官方资料先行与首发验证（唯一详细规范）
+
+Henji-AI 是 `@henjicc/ai-sdk` 的主开发仓库与首发验证宿主。新模型、新供应商或新协议必须先在这里完成官方调研、SDK 实现和完整验证，再发布版本；消费项目只接入已经验证并发布的精确版本。禁止先在消费项目按猜测实现协议，再把结果回填 SDK。
+
+### 1. 先文档，后代码
+
+编码前必须把以下信息写入本目录对应的供应商/模型文档，并能逐项追溯到官方来源：
+
+- 模型展示名、API model ID 与适用区域/版本；
+- Base URL、端点、方法、鉴权、请求字段、枚举、限制和默认值；
+- 当前价格、计费维度、价格来源与冲突取舍；
+- 同步响应，或轮询、SSE、WebSocket 等异步/流式协议的完整事件契约；
+- 错误、终态、取消、断线、超时、资源释放与连接复用规则。
+
+缺少官方来源，或模型、端点、价格、事件契约中任一项仍无法确定时，必须把未知项和已查入口写清并暂停编码；不得用相近模型、旧版本、SDK 现状或消费项目行为替官方契约作结论。官方资料本身矛盾时同时保留冲突来源，标为“实现前待官方确认/授权实测”，不能替供应商猜。
+
+### 2. 流式与异步协议必须有事件契约矩阵
+
+只要涉及 WebSocket、SSE、流式 HTTP、上传后轮询或回调，就必须在供应商/模型文档中按官方资料建立事件级矩阵。每一个官方事件/状态单独一行，不得只写一条 happy path 示例：
+
+| 事件/状态 | 前置状态 | 字段契约（required / optional / nullable） | 空值/缺字段语义 | 下一状态 | 对外输出 | 副作用 | 终态/错误 | 连接复用 |
+|---|---|---|---|---|---|---|---|---|
+| 官方事件名或状态值 | 允许从哪些状态进入 | 逐字段写清存在性、类型与可空性 | `null`、空串、空数组、字段缺失分别是否合法以及是否忽略 | 保持/迁移到哪个状态 | partial/final/usage/finish 或无输出 | ack、上传、轮询、计时器、资源释放等 | 是否终止；官方错误码/原因 | 继续收消息、等待关闭、主动关闭或可开启下一会话 |
+
+矩阵还必须说明状态机不变量：首事件、合法重复/乱序、是否允许先终态后结果、什么才算“有效 final”、空终态如何处理、断线后能否恢复、取消与正常结束各释放哪些资源。若官方没有说明某项，明确写“官方未说明”，不要把实现假设写成官方事实。
+
+### 3. 官方示例与 fixture 一一对应
+
+官方资料中出现的每一个字面请求、响应或事件示例，都要逐项进入 `packages/ai-sdk/tests/fixtures/`，或由测试逐字内联引用同一份 fixture。fixture 必须记录：
+
+- 精确来源 URL 与抓取日期；
+- 内容是官方原样、仅做脱敏/不可联网替换，还是从字段表构造；
+- 任何替换的字段及替换原因；
+- 对应事件矩阵的行或场景。
+
+原样示例只允许做安全脱敏、ID/URL 不可联网替换和必要的稳定化，不得为了让当前 parser 通过而补字段。官方只有字段表、没有字面示例时，可以据表构造 fixture，但必须标为“依据官方字段表构造”，不能标为官方原样。合成负例必须放在独立场景或独立文件并标为 `synthetic-negative`（或同等清晰标记），不得冒充官方样本。fixture 的通用格式与现有目录约定见 [../../tests/fixtures/README.md](../../tests/fixtures/README.md)。
+
+### 4. fixture、parser 与测试必须闭环
+
+协议实现的精确测试必须从事件矩阵和 fixture 推导，至少覆盖实际适用的下列场景：
+
+- 官方 happy path 的逐事件解析与完整状态迁移；
+- 合法空值（包括合法空始帧/心跳/无输出事件）；
+- required 字段缺失或类型错误的明确拒绝；
+- 空终态、结束前无有效 final、重复事件、乱序事件；
+- 供应商错误事件、网络断开、取消、超时；
+- 正常结束、失败、取消、断线后的连接、计时器、迭代器和会话资源释放。
+
+“测试通过”还不够，门禁必须做一次**断牙验证**：临时破坏被测试的不变量（例如把合法空事件误判为错误、接受缺失必填字段、漏掉终态释放），确认对应测试确实失败，再恢复实现并确认重新通过。断牙改动不能提交；交接中记录破坏点和实际失败的测试。只匹配标题、关键词或 fixture 数量的检查不算协议门禁。
+
+### 5. SDK 首发与消费顺序
+
+发布和接入严格按以下顺序进行，任一步失败都在当前阶段修复，不跨阶段绕过：
+
+1. 在 Henji-AI 跑变更协议/模型的精确契约测试与宿主集成测试；
+2. 跑 SDK 全量测试、可移植性检查、类型/构建、打包与本地安装包验证；
+3. 从将要发布的包或远端预发布/正式包回装，在受限运行环境验证公开入口、按需 bundle 与版本内容；
+4. 发布 SDK；
+5. 消费项目精确锁定已验证版本及 lockfile integrity，不使用 workspace 提升、浮动范围或源码旁路；
+6. 消费项目再运行宿主 transport、凭据、媒体、取消、日志和资源释放的集成测试。
+
+真实付费网络只在用户明确授权时执行；没有真网不妨碍协议契约测试，但必须在交接中准确写明边界，不能把 fixture/scripted 测试表述成真实供应商成功。
+
+---
+
+## 五、零散但会卡住你的坑
+
+| 坑 | 表现 | 解法 |
+|---|---|---|
+| **KIE 限流** | 连续请求后返回 HTTP **200**，但内容是 HTML 外壳 | 用 `grep -l "DOCTYPE html"` 检出，加 2 秒延迟重试。批量下载后一定要跑一次这个检查 |
+| **zsh 不做单词分割** | `for p in $PATHS` 把整个多行变量当成一个词 | 用 `while IFS= read -r p; do ... done < 路径文件` |
+| **Bash 工具禁用前台 `sleep`** | 加延迟的循环跑不了 | `perl -e 'select(undef,undef,undef,2.0)'` |
+| **ego-browser 里 `require` + 顶层 await 冲突** | `Cannot determine intended module format` | 别在 heredoc 里写文件，用 `> out.txt 2>&1` 重定向 |
+| **shell 工作目录会跨调用保留** | 上一条 `cd` 影响下一条 | 一律用绝对路径 |
+| **文件名带 `/`** | 批量落盘时路径炸掉 | `tr '/' '~'` 做扁平文件名 |
+| **Fal 价格标注 tentative** | 价格会变 | 文档里注明「接入前重新读一次 `llms.txt`」 |
+
+---
+
+## 六、推荐执行顺序
+
+1. **抓三份 `llms.txt` 索引** → 按模型名前缀过滤，列出**完整**页面清单（这一步决定会不会漏能力）
+2. **Fal 端点探测** → 补上索引里没有的组合路径
+3. **批量 curl 落盘**（`.md` / `llms.txt`），完成后检查有没有 HTML 外壳
+4. **官方站**：SPA 找内容 API，SSR 直接 curl
+5. **价格页**：ego-browser，注意标签页与分页
+6. **用两个脚本提取** schema 与正文，逐字段成表
+7. **三项交叉校验**，不一致的地方写清来源与取舍
+8. 涉及异步/流式协议时，完成第四节的事件矩阵、官方 fixture 与测试场景清单
+9. 每份文档结尾写「原始链接索引」，标注**是否需要登录**
+
+---
+
+相关：[README.md](README.md)（模型清单与结构约定）、[docs/rules/model-adaptation.md](../../../../docs/rules/model-adaptation.md)（代码侧适配规范）

package/docs/model-adaptation//351/200/217/350/247/206/345/217/230/346/215/242//351/200/217/350/247/206/345/217/230/346/215/242_Fal.md

@@ -0,0 +1,59 @@
+# 透视变换（Fal）适配资料
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-29 |
+| 平台 | Fal |
+| 展示名 | Perspective Change |
+| API endpoint ID | `fal-ai/image-apps-v2/perspective` |
+| 模态 | 单图输入 → 单个离散视角图 |
+| 商用标记 | Fal 模型页明确标为 `Commercial use` |
+| 价格 | `$0.04 / image` |
+| 登录状态 | 模型页、Agent 文本与 OpenAPI 公开；真实调用需要 Fal Key |
+| 接入定位 | 多角度能力的离散完整方位档；不与连续控制档混成同一结果组 |
+
+## 1. 接口
+
+- endpoint ID：`fal-ai/image-apps-v2/perspective`
+- 输入：`image_url` 必填；`target_perspective` 可选；`aspect_ratio` 可选。
+- 输出：`images[]`，首版要求恰好一张。
+- 异步、上传、取消、结果解析复用 [Fal 供应商资料](../供应商/Fal.md)。
+
+## 2. 离散视角枚举
+
+| API 值 | 产品标签 | 精度说明 |
+|---|---|---|
+| `front` | 正面 | 语义预设，不是 0° 相机外参 |
+| `left_side` | 左侧面 | 语义预设，不承诺精确 90° |
+| `right_side` | 右侧面 | 语义预设，不承诺精确 -90° |
+| `back` | 背面 | 由模型推断不可见区域 |
+| `top_down` | 顶视 | 语义预设 |
+| `bottom_up` | 仰视 | 语义预设 |
+| `birds_eye` | 鸟瞰 | 语义预设 |
+| `three_quarter_left` | 左三分之四 | 语义预设 |
+| `three_quarter_right` | 右三分之四 | 语义预设 |
+
+首版固定 1 张输入图、每个目标预设单独请求、同组不允许重复预设。默认完整方位组为正面、右侧面、背面、左侧面。该端点没有提示词、连续角度、距离或 FOV 字段，界面不得补造相关控件。
+
+## 3. 价格与失败策略
+
+- `$0.04 / image`；4 个方位约 `$0.16`，全部 9 个预设约 `$0.36`。
+- 单次输出数量不等于 1 时视为契约失败。
+- 批次失败时沿用多角度原子落图和按失败项重试策略。
+- 离散档和连续档来自不同模型，不能在一个结果组混用，否则组内一致性和精度语义不可比较。
+
+## 4. 待真实验证
+
+- `front/side/back` 的方位遵从和人物/商品身份一致性。
+- 不可见背面补全质量与文字、标志、结构漂移。
+- `top_down` 与 `birds_eye` 的实际差异。
+- 官方未给延迟承诺，需按 request ID 记录真实耗时。
+
+## 5. 原始链接索引
+
+| 内容 | 链接 | 是否需登录 | 核查日期 |
+|---|---|---|---|
+| 模型页、商用标记与价格 | https://fal.ai/models/fal-ai/image-apps-v2/perspective | 否 | 2026-08-29 |
+| 实时 Agent 文本 | https://fal.ai/models/fal-ai/image-apps-v2/perspective/llms.txt | 否 | 2026-08-29 |
+| OpenAPI | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/image-apps-v2/perspective | 否 | 2026-08-29 |
+| Fal 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 | 2026-08-29 |

package/docs//346/216/245/345/205/245/346/214/207/345/215/227/Electron.md

@@ -0,0 +1,77 @@
+# Electron 接入
+
+## 分层
+
+SDK 客户端应只在 Electron **主进程**构造一次。渲染层通过 preload 白名单和 IPC 发送可序列化
+DTO，不直接持有 API key，不导入 provider/runtime 实现，不直接请求供应商。
+
+```text
+renderer -> preload -> ipcMain -> createAIClient({ runtime }) -> provider
+```
+
+痕迹AI 的已验证实现在
+`electron/main/services/ai-runtime/sdk-runtime.ts`，其单例 `sdkRuntimeContext` 与
+`sdkAIClient` 同时服务生成和 LLM。
+
+## 四个宿主能力
+
+```ts
+import fs from 'node:fs'
+import path from 'node:path'
+import {
+  createAIClient,
+  defaultFilename,
+  inferMimeFromPath,
+  normalizeLocalSource,
+  parseDataUri,
+  type RuntimeContext,
+} from '@henjicc/ai-sdk'
+
+const runtime: RuntimeContext = {
+  transport: { fetch: (url, init) => fetch(url, init) },
+  credentials: {
+    get: (scope, providerId) => readFromOsProtectedStore(scope, providerId),
+  },
+  media: {
+    async read(ref) {
+      const data = parseDataUri(ref)
+      if (data) {
+        return { ...data, filename: defaultFilename(data.mimeType) }
+      }
+      const localPath = normalizeLocalSource(ref)
+      if (!localPath) throw new Error(`Unsupported media ref: ${ref}`)
+      return {
+        bytes: new Uint8Array(fs.readFileSync(localPath)),
+        mimeType: inferMimeFromPath(localPath),
+        filename: path.basename(localPath),
+      }
+    },
+  },
+  logger: createSanitizedLogger(),
+}
+
+export const client = createAIClient({ runtime })
+```
+
+`readFromOsProtectedStore` 和 `createSanitizedLogger` 是宿主的安全存储/日志实现；痕迹AI 分别使用
+Electron `safeStorage` 和统一结构化日志。日志不得放 API key、token、cookie 或完整授权头。
+
+### `safeStorage` 与开发脚本身份
+
+独立 Electron 验证脚本默认使用 `Electron` 这个 app name/profile，不能直接解密正式应用以另一
+app identity 写入的密文。若维护脚本需要复用正式凭据，必须在 `app.whenReady()` **之前**设置与
+正式应用相同的 `app.setName()`，并让 `userData` / `sessionData` 指向正式 profile；否则应要求用户
+重新注入密钥，而不是复制密文、猜解密格式或把明文写入临时文件。这个限制只影响复用既有
+`safeStorage` 密文；按本指南自行实现新宿主时，应始终让读写使用同一个应用身份。
+
+## IPC 边界
+
+- IPC 只传 `modelId` / 扁平 `params` / `requestId` / `taskId`等 DTO，不传函数或 `RuntimeContext`。
+- `generate()` 可能返回 `pending + taskId`；宿主可立即 `continuePolling()`，或持久化 taskId 稍后续查。
+- SDK 结果只有 URL/metadata，不会下载成 `filePath`。落盘、媒体协议转换、进度学习和应用 trace 留在宿主。
+- 创建阶段用 requestId 取消；续轮询阶段用供应商 taskId 取消：
+  `client.cancel({ namespace: 'generation', taskId })`。LLM 使用 `namespace: 'llm'`。
+- 应用退出或替换 client 时调用 `dispose()`；它会注销该 client 拥有的自定义 provider。
+
+Electron 主进程从包根 `@henjicc/ai-sdk` 导入是最兼容的写法；老的 TypeScript
+`moduleResolution: "node"` 不识别 `exports` 子路径。