@henjicc/ai-sdk 0.2.8

package/docs/model-adaptation/ControlLight/ControlLight_Fal.md

@@ -0,0 +1,85 @@
+# ControlLight（Fal）适配资料
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-29 |
+| 平台 | Fal |
+| 展示名 | ControlLight |
+| API endpoint ID | `fal-ai/control-light` |
+| 模态 | 单图输入 → 暗光增强图片 |
+| SDK 入口 | `@henjicc/ai-sdk/tool-models/fal/control-light` |
+| 工具包 | `@henjicc/ai-sdk/tool-packs/fal-image-utility-tools` |
+| 价格 | `$0.03 / megapixel` |
+| 登录状态 | 模型页、`llms.txt` 与 OpenAPI 公开；真实调用需要 Fal Key |
+
+## 1. 能力与产品边界
+
+ControlLight 是基于 FLUX.2 [klein] 9B 的 LoRA，用于抬升暗光曝光并恢复可见细节。它与“重新设计光照方向/风格”不同：核心可见控件应是 `lighting_level` 强度，产品名建议使用“暗光增强”或“低光修复”，不宣称为物理补光。
+
+## 2. 接口与队列契约
+
+- 鉴权：`Authorization: Key <FAL_KEY>`
+- 直连：`POST https://fal.run/fal-ai/control-light`
+- 队列提交：`POST https://queue.fal.run/fal-ai/control-light`
+- 状态：`GET https://queue.fal.run/fal-ai/control-light/requests/{request_id}/status`
+- 结果：`GET https://queue.fal.run/fal-ai/control-light/requests/{request_id}`
+- 取消：`PUT https://queue.fal.run/fal-ai/control-light/requests/{request_id}/cancel`
+- 结果路径：`images[].url`；`images` 必填，`seed` 在 OpenAPI 中也标为必填
+
+队列状态仅有 `IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`，`status` 和 `request_id` 必填，日志、指标、队列位置和各 URL 可选。`COMPLETED` 后必须另取结果并校验媒体 URL；模型 OpenAPI 未定义新错误码、断线恢复或乱序规则，其余沿用 [Fal 供应商队列契约](../供应商/Fal.md#2-队列契约)。
+
+## 3. 请求字段
+
+| 字段 | 类型 | 必填 | 默认 / 范围 | 产品策略 |
+|---|---|---|---|---|
+| `image_url` | string | 是 | 官方未公布文件限制 | 恰好 1 张已有素材，由 Fal CDN 上传 |
+| `lighting_level` | number | 否 | `0.75`；`0..1` | 显示并发送；0 近似不处理，1 为训练范围内最强抬升 |
+| `prompt` | string | 否 | 官方内置一段保留身份、几何和自然颜色的恢复提示词 | 首版不展示、不发送，使用服务端当前默认 |
+| `num_inference_steps` | integer | 否 | `4`；`4..8` | 不展示、不发送 |
+| `guidance_scale` | number | 否 | `1`；`0..20` | 不展示、不发送 |
+| `enable_safety_checker` | boolean | 否 | `true` | 不展示、不发送，保持官方默认 |
+| `seed` | integer/null | 否 | 随机 | 不展示、不发送 |
+| `sync_mode` | boolean | 否 | `false` | 不展示、不发送，使用持久队列 |
+| `output_format` | enum | 否 | `png`；`jpeg` / `png` / `webp` | 按项目约定不展示、不发送 |
+
+## 4. 示例与响应契约冲突
+
+```json
+{
+  "image_url": "https://v3.fal.media/files/.../low-light.png",
+  "lighting_level": 0.75
+}
+```
+
+```json
+{
+  "images": [
+    {
+      "url": "https://v3b.fal.media/files/.../enhanced.png",
+      "width": 768,
+      "height": 1360,
+      "content_type": "image/png"
+    }
+  ],
+  "has_nsfw_concepts": [false]
+}
+```
+
+OpenAPI 把 `seed` 标为必填，但同一份官方 `llms.txt` 的字面响应示例缺少 `seed`。因此解析器只应将非空 `images[].url` 作为成功必要条件，`seed` 按可选元数据读取，不得因为缺少 seed 丢弃有效图片。
+
+## 5. 计价与未知项
+
+- 实时 `llms.txt` 标价 `$0.03 / megapixel`，但未字面说明是输入、输出还是处理像素。
+- 静态目录可保留 `$0.03/MP` 单位价；在未通过 billing event 校验前，不应把估算值表述成最终账单。
+- 官方未给输入图像尺寸/格式上限、输出尺寸算法、延迟 SLA 和结果保留期。
+- 真实验收需记录 0 / 0.75 / 1 三档对主体、噪点、高光溢出和计费的影响。
+
+## 6. 原始链接索引
+
+| 内容 | 链接 | 是否需登录 | 核查日期 |
+|---|---|---|---|
+| 模型页与当前价格 | https://fal.ai/models/fal-ai/control-light | 否 | 2026-08-29 |
+| 实时字段、范围、示例与价格 | https://fal.ai/models/fal-ai/control-light/llms.txt | 否 | 2026-08-29 |
+| OpenAPI（必填、响应与枚举） | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/control-light | 否 | 2026-08-29 |
+| Fal 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 | 2026-08-29 |
+| Fal 价格 API | https://fal.ai/docs/platform-apis/v1/models/pricing | 否（调用需 Key） | 2026-08-29 |

package/docs/model-adaptation/FLUX-2-/345/244/232/350/247/222/345/272/246/FLUX-2-/345/244/232/350/247/222/345/272/246_Fal.md

@@ -0,0 +1,107 @@
+# FLUX 2 多角度（Fal）适配资料
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-29 |
+| 平台 | Fal |
+| 展示名 | Flux 2 Lora Gallery / Multiple Angles |
+| API endpoint ID | `fal-ai/flux-2-lora-gallery/multiple-angles` |
+| 模态 | 图片数组输入 → 指定镜头角度的图片 |
+| SDK 入口 | `@henjicc/ai-sdk/tool-models/fal/flux-2-multiple-angles` |
+| 工具包 | `@henjicc/ai-sdk/tool-packs/fal-multi-angle-tools` |
+| 价格 | `$0.021 / processed megapixel` |
+| 登录状态 | 模型页、`llms.txt` 与 OpenAPI 公开；真实调用需要 Fal Key |
+
+> 模型用度数表达水平和垂直控制，但没有输出相机内参、外参或误差。产品可称“镜头角度”或“模型控制角”，不能称测量级姿态。
+
+## 1. 角度语义
+
+| 字段 | 官方语义 |
+|---|---|
+| `horizontal_angle` | `0°` 正面，`90°` 右侧，`180°` 背面，`270°` 左侧，`360°` 回到正面 |
+| `vertical_angle` | `0°` 平视，`30°` 高机位，`60°` 高角度俯拍 |
+| `zoom` | `0` 远景，`5` 中景，`10` 近景 |
+
+该端点没有请求 `prompt`：官方说明提示词由滑块数值自动组装。正式 UI 不应展示一个不会进入请求的提示词框。
+
+## 2. 接口与队列契约
+
+- 鉴权：`Authorization: Key <FAL_KEY>`
+- 直连：`POST https://fal.run/fal-ai/flux-2-lora-gallery/multiple-angles`
+- 队列提交：`POST https://queue.fal.run/fal-ai/flux-2-lora-gallery/multiple-angles`
+- 状态：`GET https://queue.fal.run/fal-ai/flux-2-lora-gallery/multiple-angles/requests/{request_id}/status`
+- 结果：`GET https://queue.fal.run/fal-ai/flux-2-lora-gallery/multiple-angles/requests/{request_id}`
+- 取消：`PUT https://queue.fal.run/fal-ai/flux-2-lora-gallery/multiple-angles/requests/{request_id}/cancel`
+- 结果路径：`images[].url`；OpenAPI 还把 `seed` 和服务端组装的 `prompt` 标为必填
+
+通用状态为 `IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`，`status` / `request_id` 必填。`COMPLETED` 后再获取结果并严格校验 `images[].url`；模型没有新增状态或错误码，其余复用 [Fal 供应商队列契约](../供应商/Fal.md#2-队列契约)。
+
+## 3. 请求字段
+
+| 字段 | 类型 | 必填 | 默认 / 范围 | 产品策略 |
+|---|---|---|---|---|
+| `image_urls` | `string[]` | 是 | **官方未给 `minItems` / `maxItems`** | 首版保守限制恰好 1 张；这是产品约束，不冒充官方限制；由 Fal CDN 上传 |
+| `horizontal_angle` | number | 否 | `0`；`0..360` | 显示并发送 |
+| `vertical_angle` | number | 否 | `0`；`0..60` | 显示并发送 |
+| `zoom` | number | 否 | `5`；`0..10` | 显示并发送 |
+| `image_size` | 对象 / enum / null | 否 | 枚举见下 | 首版按输入比例选约 1MP 标准档，显式发送，限制波动与费用 |
+| `guidance_scale` | number | 否 | `2.5`；`0..20` | 不展示、不发送 |
+| `num_inference_steps` | integer | 否 | `40`；`4..50` | 不展示、不发送 |
+| `acceleration` | enum | 否 | `regular`；`none` / `regular` | 不展示、不发送 |
+| `enable_safety_checker` | boolean | 否 | `true` | 不展示、不发送 |
+| `num_images` | integer | 否 | `1`；`1..4` | 首版一个目标角度对应一张，固定 1，不展示、不发送 |
+| `lora_scale` | number | 否 | `1`；`0..2` | 不展示、不发送 |
+| `seed` | integer/null | 否 | 随机 | 不展示、不发送 |
+| `sync_mode` | boolean | 否 | `false` | 不展示、不发送 |
+| `output_format` | enum | 否 | `png`；`png` / `jpeg` / `webp` | 按项目约定不展示、不发送 |
+
+`image_size` 可以是 `{width, height}`（宽高为正整数，单边最大 `14142`，子字段默认 `512`），或以下枚举：
+
+`square_hd` / `square` / `portrait_4_3` / `portrait_16_9` / `landscape_4_3` / `landscape_16_9`。
+
+## 4. 请求与响应示例
+
+```json
+{
+  "image_urls": ["https://v3.fal.media/files/.../object.png"],
+  "horizontal_angle": 90,
+  "vertical_angle": 30,
+  "zoom": 5,
+  "image_size": "square_hd"
+}
+```
+
+```json
+{
+  "images": [
+    { "url": "https://v3b.fal.media/files/.../angle.png" }
+  ],
+  "prompt": "<server-generated prompt>"
+}
+```
+
+OpenAPI 把 `seed` 标为必填，但同一份官方 `llms.txt` 的字面响应示例缺少 `seed`。解析器只应把非空 `images[].url` 当作成功必要条件，`seed` / `prompt` 按可选元数据处理。
+
+## 5. 多角度组与计价
+
+- 每个目标角度使用一次独立 Fal 请求，选择顺序在请求前固定，不从结果文件名推断。
+- 实时 `llms.txt` 标价 `$0.021 / processed megapixel`。首版固定约 1MP 时，单角度静态预算约 `$0.021`；4 角度约 `$0.084`。
+- “processed megapixel”的精确取整和输入/输出基准未在 `llms.txt` 展开，最终以 pricing API / billing event 为准。
+- 多次独立生成不保证身份、文字、不可见结构或背景一致；批次失败和按失败项重试策略应与现有多角度工具保持一致。
+
+## 6. 待真实验证
+
+- 人物、商品、建筑在 `0/90/180/270/360°` 的方位遵从和回环误差。
+- `vertical_angle` 只有正值，是否无法表达仰拍。
+- `zoom` 是改变景别还是同时改变主体几何。
+- 官方未给输入数量、文件限制、延迟 SLA 和一致性承诺。
+
+## 7. 原始链接索引
+
+| 内容 | 链接 | 是否需登录 | 核查日期 |
+|---|---|---|---|
+| 模型页与当前价格 | https://fal.ai/models/fal-ai/flux-2-lora-gallery/multiple-angles | 否 | 2026-08-29 |
+| 实时字段、范围、示例与价格 | https://fal.ai/models/fal-ai/flux-2-lora-gallery/multiple-angles/llms.txt | 否 | 2026-08-29 |
+| OpenAPI（完整尺寸枚举、范围、必填与响应） | https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/flux-2-lora-gallery/multiple-angles | 否 | 2026-08-29 |
+| Fal 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 | 2026-08-29 |
+| Fal 价格 API | https://fal.ai/docs/platform-apis/v1/models/pricing | 否（调用需 Key） | 2026-08-29 |

package/docs/model-adaptation/Finegrain-Eraser/Finegrain-Eraser_Fal.md

@@ -0,0 +1,31 @@
+# Finegrain Eraser (Mask) · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| SDK 模型 ID | `fal-finegrain-eraser`（可选工具模型，不进入默认 105 目录） |
+| Fal endpoint ID | `fal-ai/finegrain-eraser/mask` |
+| API 文档 | https://fal.ai/models/fal-ai/finegrain-eraser/mask/api |
+| 价格 | Express $0.04 / Standard $0.13 / Premium $0.22 |
+| 登录 | 文档与模型页无需登录；调用需要 Fal Key |
+
+## 协议与字段
+
+使用 Fal 队列公共协议，认证、提交、状态与结果读取同 [Fal 供应商文档](../供应商/Fal.md)。
+输出位于 `image.url`。
+
+| 字段 | 约束 | SDK 策略 |
+|---|---|---|
+| `image_url` | 必填，待处理原图 | `image-upload`，Fal CDN 自动上传 |
+| `mask_url` | 必填；白色区域擦除 | `image-upload`，Fal CDN 自动上传 |
+| `mode` | `express` / `standard` / `premium`，默认 `standard` | 保留为唯一可选参数 |
+| `seed` | 可选 | 项目约定隐藏且不请求 |
+
+Fal 另有 prompt/box 端点；本次严格适配 Photoshop 已启用的 mask 工具，不顺手扩张范围。
+统一画像从本模型 schema 派生为 `operation=image-edit`、`feature=erase`，执行仍走统一 Fal 生成内核。
+
+## 原始链接索引
+
+- https://fal.ai/models/fal-ai/finegrain-eraser/mask/api — mask endpoint、字段、结果与队列示例。
+- https://fal.ai/models/fal-ai/finegrain-eraser/mask — 当前三档价格。
+- https://fal.ai/docs/documentation/model-apis/inference/queue — Fal 队列公共协议。

package/docs/model-adaptation/Flux-Pro-Erase/Flux-Pro-Erase_Fal.md

@@ -0,0 +1,34 @@
+# Flux Pro Erase · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| SDK 模型 ID | `fal-flux-pro-erase`（可选工具模型，不进入默认 105 目录） |
+| Fal endpoint ID | `fal-ai/flux-pro/v1/erase` |
+| API 文档 | https://fal.ai/models/fal-ai/flux-pro/v1/erase/api |
+| 价格 | 首个生成 MP $0.03，后续 $0.004/MP；参考图 $0.004/MP，至少按 3 MP |
+| 登录 | 文档与模型页无需登录；调用需要 Fal Key |
+
+## 协议与字段
+
+使用 Fal 队列公共协议：`POST https://queue.fal.run/<endpoint-id>`，随后查询服务端返回的
+`status_url`，状态为 `COMPLETED` 后读取 `response_url`。认证为
+`Authorization: Key <FAL_KEY>`。结果位于 `images[].url`。
+
+| 字段 | 约束 | SDK 策略 |
+|---|---|---|
+| `image_url` | 必填，待处理原图 | `image-upload`，本地媒体由 Fal CDN uploader 自动上传 |
+| `mask_url` | 必填，与原图同尺寸；白色擦除、黑色保留 | `image-upload`，自动上传 |
+| `dilate_pixels` | 整数，默认 10 | 固定发送 10，不增加宿主控件 |
+| `output_format` | `jpeg` / `png`，默认 `jpeg` | 按项目约定不显示、不发送 |
+| `sync_mode` | 同步返回 data URI | 不发送，统一使用可恢复队列 |
+
+静态价格展示采用最低约 `$0.042`（1 MP 生成 + 参考图最低 3 MP）；真实费用随输出像素增加。
+该模型按需发布为完整 generation pack，统一画像派生为 `operation=image-edit`、`feature=erase`；
+执行直接使用模块化生成客户端，不增加专用擦除执行内核。
+
+## 原始链接索引
+
+- https://fal.ai/models/fal-ai/flux-pro/v1/erase/api — endpoint、输入/输出 schema、队列调用。
+- https://fal.ai/models/fal-ai/flux-pro/v1/erase — 当前模型页价格与示例结果。
+- https://fal.ai/docs/documentation/model-apis/inference/queue — Fal 队列公共协议。

package/docs/model-adaptation/Fun-ASR/Fun-ASR_/347/231/276/347/202/274.md

@@ -0,0 +1,43 @@
+# Fun-ASR · 百炼
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| 能力 | 长音频/录音文件异步识别 |
+| 平台模型 ID | `fun-asr`（稳定别名，官方当前等同 `fun-asr-2025-11-07`） |
+| 输入上限 | 12 小时 / 2 GB；单次 1 个 URL |
+| 文档/价格 | 公开，无需登录 |
+
+## 1. 提交、轮询与结果
+
+```text
+POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
+Authorization: Bearer <API Key>
+X-DashScope-Async: enable
+GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
+```
+
+提交体使用 `model="fun-asr"` 和 `input.file_urls=["<public-url>"]`。返回 `output.task_id/task_status`；状态为 `PENDING/RUNNING/SUCCEEDED/FAILED/UNKNOWN`。多子任务时顶层成功不代表每个子任务成功，必须查 `results[].subtask_status`。
+
+成功后 `output.results[].transcription_url` 指向 JSON，需二次下载。结果含 `transcript/sentences/words/begin_time/end_time/speaker_id`，顶层 `usage.duration` 是计量秒数。
+
+## 2. 能力、上传与价格
+
+- 多语种/方言、热词、说话人分离；不支持情感识别。说话人分离建议音频 ≤ 2 小时。
+- 格式 `aac/amr/avi/flac/flv/m4a/mkv/mov/mp3/mp4/mpeg/ogg/opus/wav/webm/wma/wmv`，采样率任意。
+- 公网 HTTP(S) URL；REST 也可用 48 小时百炼 `oss://` 临时 URL，需 `X-DashScope-OssResourceResolve: enable`。上传凭证与模型/主账号绑定，不可复用到别的模型。
+- 北京原价 0.00022 元/有效语音秒，非语音不计费；官方列 36,000 秒/10 小时限时免费额度。
+
+## 3. 适配要点
+
+宿主桥负责上传、轮询、取消和将转写 JSON 落地；SDK 负责协议与结果解析。不得把 `transcription_url` 或用户原始音频 URL 写入普通日志。最近 24 小时任务可查询，不代表结果 URL 可长期存储。
+
+## 4. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| HTTP API/结果 | https://help.aliyun.com/zh/model-studio/fun-asr-recorded-speech-recognition-http-api | 否 |
+| 模型/音频规格 | https://help.aliyun.com/zh/model-studio/asr-model/ | 否 |
+| 临时上传 | https://help.aliyun.com/zh/model-studio/get-temporary-file-url | 否 |
+| 价格 | https://help.aliyun.com/zh/model-studio/model-pricing | 否 |
+| API Key | https://bailian.console.aliyun.com/?apiKey=1#/api-key | **是** |

package/docs/model-adaptation/Fun-ASR-Flash-2026-06-15/Fun-ASR-Flash-2026-06-15_/347/231/276/347/202/274.md

@@ -0,0 +1,41 @@
+# Fun-ASR-Flash-2026-06-15 · 百炼
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| 能力 | 短音频同步识别（HTTP） |
+| 平台模型 ID | `fun-asr-flash-2026-06-15` |
+| 输入上限 | 5 分钟 / 2 GB，单次 1 个音频 |
+| 文档/价格 | 公开，无需登录 |
+
+## 1. 端点与请求
+
+```text
+POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
+Authorization: Bearer <API Key>
+Content-Type: application/json
+```
+
+`model` 取上述 ID；`input.messages[].content[]` 最后一条为 `{type:"input_audio", input_audio:{data}}`，`data` 支持公网 URL 或 `data:<mime>;base64,...`。`parameters.format` 必填，`sample_rate/language_hints/vocabulary_id` 等可选。
+
+`X-DashScope-SSE: enable` 开启 SSE，但音频至少 1 分钟才会分段返回中间结果；否则只有最终结果。官方明确该协议不支持 DashScope SDK，TypeScript SDK 需直连 HTTP/SSE。
+
+## 2. 结果、能力与价格
+
+- `output.text` 为累积文本，`output.sentence` 含句子、时间戳、`sentence_end`，`usage.duration` 为用量。
+- 支持多语种/方言与 Prompt 上下文；不支持情感识别和说话人分离。
+- 北京原价 0.00022 元/秒，输出不计费；官方列 36,000 秒/10 小时限时免费额度。
+
+## 3. 上传与适配要点
+
+小文件优先 Base64；大文件用公网 URL 或百炼临时 OSS。临时上传凭证为 `GET https://dashscope.aliyuncs.com/api/v1/uploads?action=getPolicy&model=fun-asr-flash-2026-06-15`，上传后得 `oss://` URL，调用时需 `X-DashScope-OssResourceResolve: enable`；URL 48 小时过期，不用于生产托管。
+
+## 4. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| API | https://help.aliyun.com/zh/model-studio/non-real-time-speech-recognition-for-fun-asr-flash | 否 |
+| 模型/音频规格 | https://help.aliyun.com/zh/model-studio/asr-model/ | 否 |
+| 临时上传 | https://help.aliyun.com/zh/model-studio/get-temporary-file-url | 否 |
+| 价格 | https://help.aliyun.com/zh/model-studio/model-pricing | 否 |
+| API Key | https://bailian.console.aliyun.com/?apiKey=1#/api-key | **是** |

package/docs/model-adaptation/Fun-ASR-Realtime/Fun-ASR-Realtime_/347/231/276/347/202/274.md

@@ -0,0 +1,37 @@
+# Fun-ASR-Realtime · 百炼
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| 能力 | 实时语音识别（WebSocket） |
+| 平台模型 ID | `fun-asr-realtime`（稳定别名，官方当前等同 `fun-asr-realtime-2025-11-07`） |
+| 地域 | 华北2（北京）、新加坡 |
+| 文档/价格 | 公开，无需登录 |
+
+## 1. 协议与结果
+
+`wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference`，握手 `Authorization: Bearer <API Key>`。流程为 `run-task/task-started` → 发二进制音频并接收 `result-generated` → `finish-task/task-finished`。`task_id` 由客户端产生 UUID。
+
+`task-failed` 后 socket 废弃；等 `task-finished` 后可用不同 `task_id` 复用连接，空闲 60 秒自动断开。`result-generated.payload.output.sentence` 提供文本、句末标志和时间戳，句末 `usage.duration` 为计费时长。
+
+官方服务端事件示例明确包含一种合法的空文本中间事件：新句开始时会返回 `sentence_begin=true`、`sentence_end=false`、`text=""`、`words=[]`。客户端应把它当作句子生命周期通知并继续等待，不能报响应无效。相反，`sentence_end=true` 的最终结果仍必须有有效文本；`task-finished` 自身的 `payload` 通常为空，只负责结束任务，也不能覆盖已经累计的最终文本。如果整个任务直到 `task-finished` 都没有任何有效最终文本，SDK 应报 `invalid_response`。
+
+## 2. 能力、限制与价格
+
+- 格式 `pcm/wav/mp3/opus/speex/aac/amr`，采样率任意，单声道，时长无限制。
+- 支持多语种及中文方言/口音、热词；不支持说话人分离和情感识别。
+- 北京原价 0.00033 元/秒；官方列 36,000 秒/10 小时限时免费额度。
+
+## 3. 适配要点
+
+Say-It 保留该稳定别名与 2026-02-28 快照供用户选择；SDK 不应自行把稳定别名锁定为某快照。空 `sentence_begin` 事件只推进状态，不产生 partial/final；重复 final 只累计一次。取消时主动关闭 socket，密钥和原始音频不记日志。
+
+## 4. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| 模型/音频规格 | https://help.aliyun.com/zh/model-studio/asr-model/ | 否 |
+| WebSocket 交互 | https://help.aliyun.com/zh/model-studio/fun-asr-realtime-websocket-api | 否 |
+| 事件 | https://help.aliyun.com/zh/model-studio/fun-asr-client-events ; https://help.aliyun.com/zh/model-studio/fun-asr-server-events | 否 |
+| 价格 | https://help.aliyun.com/zh/model-studio/model-pricing | 否 |
+| API Key | https://bailian.console.aliyun.com/?apiKey=1#/api-key | **是** |

package/docs/model-adaptation/Fun-ASR-Realtime-2026-02-28/Fun-ASR-Realtime-2026-02-28_/347/231/276/347/202/274.md

@@ -0,0 +1,39 @@
+# Fun-ASR-Realtime-2026-02-28 · 百炼
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| 能力 | 实时语音识别（WebSocket） |
+| 平台模型 ID | `fun-asr-realtime-2026-02-28`（官方标注的最新快照版） |
+| 地域 | 华北2（北京）、新加坡 |
+| 文档/价格 | 公开，无需登录 |
+
+## 1. 协议
+
+`wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference`，握手头 `Authorization: Bearer <API Key>`。事件顺序：`run-task` → `task-started` → 单声道二进制音频 / `result-generated` → `finish-task` → `task-finished`。客户端生成 UUID `task_id`，每任务唯一。
+
+`task-failed` 后连接不可复用；必须等 `task-finished` 才可开下一任务，完成后空闲 60 秒自动断开。
+
+## 2. 音频、结果与价格
+
+- 格式：`pcm/wav/mp3/opus/speex/aac/amr`；采样率任意；单声道；时长无限制。
+- 语言：中文（多方言/口音）、英语、日语。
+- 热词：支持。不支持说话人分离和情感识别。
+- `result-generated.payload.output.sentence` 含中间/最终文本与时间戳；句末时 `usage.duration` 为计费时长。
+- 新句开始的首个中间事件可为 `sentence_begin=true`、`sentence_end=false`、`text=""`、`words=[]`；这是官方定义的合法生命周期事件，应继续等待文本。`sentence_end=true` 的 final 仍必须非空。
+- `task-finished.payload` 通常为空，只表示任务正常结束；不能把它当作识别结果，也不能覆盖已累计 final。若此前始终没有有效 final，任务结束时应报无有效转写。
+- 北京原价：0.00033 元/秒，输出不计费；官方页列 36,000 秒/10 小时限时免费额度（以账号实际为准）。
+
+## 3. 适配要点
+
+与稳定别名 `fun-asr-realtime` 并列保留，不自动改写 ID。两者共用传输实现，但能力元数据和显示名分开注册。空 `sentence_begin` 不产生 partial/final，重复 final 只累计一次。取消必须停止送音频、关闭当前 socket，不得把该连接放回池。
+
+## 4. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| 模型/音频规格 | https://help.aliyun.com/zh/model-studio/asr-model/ | 否 |
+| WebSocket 交互 | https://help.aliyun.com/zh/model-studio/fun-asr-realtime-websocket-api | 否 |
+| 客户端/服务端事件 | https://help.aliyun.com/zh/model-studio/fun-asr-client-events ; https://help.aliyun.com/zh/model-studio/fun-asr-server-events | 否 |
+| 价格 | https://help.aliyun.com/zh/model-studio/model-pricing | 否 |
+| API Key | https://bailian.console.aliyun.com/?apiKey=1#/api-key | **是** |

package/docs/model-adaptation/GLM-5.3-Flash/GLM-5.3-Flash_/346/231/272/350/260/261.md

@@ -0,0 +1,207 @@
+# GLM-5.3-Flash · 智谱
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-28 |
+| 模态 | 原生多模态 LLM/VLM：文本、图片、视频、文件输入 → 文本输出 |
+| 供应商 / 项目 provider family | 智谱国内 BigModel + 国际 Z.AI / `bigmodel` |
+| 平台模型 ID | `glm-5.3-flash` |
+| API 协议 | OpenAI 兼容 Chat Completions；同步 JSON / SSE |
+| API / 价格资料 | 公开无需登录；API Key 与真实调用需登录/付费 |
+| 适配状态 | 仅完成官方资料；SDK 尚未登记；完整能力受第 10 节冲突项阻断 |
+
+## 1. 身份与边界
+
+GLM-5.3-Flash 是 2026-08-26 上线的 GLM-5 系列首个原生多模态模型，是既有
+`bigmodel` 供应商族下的**新增独立模型**。它不是文本模型 `glm-5.3` 的别名，也不触发供应商
+重命名。国内 BigModel 与国际 Z.AI 都正式提供该模型，展示名均为 `GLM-5.3-Flash`，API
+Model Code 均为小写 `glm-5.3-flash`；公开资料没有第二个模型 alias。
+
+当前仓库的 `bigmodel` preset 使用 `open.bigmodel.cn` 和国内 API Key 页面，因此它是国内配置，
+不是国际站配置。`Z.AI` 是国际 endpoint profile，不应被当成现有 providerId 的别名直接换域名。
+
+## 2. 端点与鉴权
+
+| endpoint profile | Chat Completions 端点 | API Key 管理 | 账号 / 凭据边界 |
+|---|---|---|---|
+| `cn` | `https://open.bigmodel.cn/api/paas/v4/chat/completions` | `https://bigmodel.cn/usercenter/proj-mgmt/apikeys` | 国内 BigModel；现有 preset 与存量 `bigmodel` 凭据归此 profile |
+| `global` | `https://api.z.ai/api/paas/v4/chat/completions` | `https://z.ai/manage-apikey/apikey-list` | 国际 Z.AI；需要独立配置槽，不复用国内 key |
+
+两者均使用 `Authorization: Bearer <API Key>` 与 JSON。两个官方 Quick Start 分别要求到各自平台注册/
+登录并创建 Key；官方没有说明账号、余额或 API Key 可以跨区互通。本项目不读取/试投用户真实 key，
+因此互通性保持“未知”，实现必须按不互通处理。
+
+两区模型页都只链接 Chat Completions。国内相同供应商的 `glm-5.3` 另有 Responses 与 Anthropic 协议，
+不能据此外推 Flash。订阅过 GLM Coding Plan（含过期）的账号还可能被限制为只能使用 Chat Completions。
+
+## 3. 能力与限制
+
+| 能力 | 官方值 / 结论 |
+|---|---|
+| 输入 | text / image / video / file |
+| 输出 | text；未确认 audio 输入或输出 |
+| 上下文 | 1,000,000 tokens |
+| 最大输出 | 131,072 tokens |
+| 思考 | 强制开启；`reasoning_effort=low/high/max`，默认 max |
+| 流式 | SSE，文本/思考增量、最终 usage、`[DONE]` |
+| 工具 | Function Calling；最多 128 个工具；仅确认 `tool_choice=auto` |
+| 缓存 | 支持；标准 API 保留跨轮思考需显式 `clear_thinking=false` |
+| 结构化输出 | 官方页面相互冲突，暂不得登记，见第 10 节 |
+
+推荐请求参数：`temperature=1`、`top_p=0.95`、`reasoning_effort=max`、
+`thinking={"type":"enabled"}`。官方建议不要同时调整 temperature 与 top_p；`max_tokens`
+最大 131072，建议不低于 1024；`stop` 最多 4 个字符串。
+
+## 4. 多模态请求
+
+### 图片
+
+```json
+{"type":"image_url","image_url":{"url":"<host supplied URL or data URL>"}}
+```
+
+- 支持公网 URL 或 Base64 Data URL。
+- 单张 <5 MB、最大 6000×6000，JPG/PNG/JPEG，最多 50 张。
+- 消费界面不得提供媒体 URL 文本框；URL/Base64 必须来自宿主媒体选择、上传或转换链路。
+
+### 视频
+
+```json
+{"type":"video_url","video_url":{"url":"<host supplied URL>"}}
+```
+
+- 官方 Chat 示例确认 URL；单文件 ≤200 MB，MP4/MKV/MOV。
+- 官方没有给出 Flash 的视频时长上限或视频 Base64 写法，保持未知。
+
+### 文件
+
+- 推荐内容块类型 `file`；旧 `file_url` 类型仍可用但不推荐。
+- `file_id` / `file_url` / `file_data` 三选一；单文件 ≤50 MB，最多 50 个文件。
+- `file_data` 是带 MIME 的 Base64 Data URL；`file_url` 文档列举 PDF/TXT/Word/JSONL/XLSX/PPTX 等。
+- Chat 文档说 `file_id` 来自文件上传接口，但 Files API 的 `purpose` 只列 `batch`、
+  `code-interpreter`、`agent`、`voice-clone-input`，没有 Chat 用途，不能猜测。
+
+官方没有说明图片、视频、文件能否跨模态混合，也没有给出混合总数量/体积上限。既不能套用
+`glm-5v-turbo` 的互斥限制，也不能反向假设 Flash 可任意混合。
+
+## 5. 思考与工具调用
+
+- `thinking.type` 只能为 `enabled`，不能关闭。
+- `reasoning_effort`：low / high / max，默认 max。
+- 标准 API 默认清除历史思考；若保留跨轮思考，显式传 `thinking.clear_thinking=false`。
+- 交错思考的工具续轮必须回传上一轮完整、原序的 `reasoning_content`、assistant tool calls，
+  再附带包含 `tool_call_id` 的 role=tool 消息。
+- 工具由宿主执行，不是模型或 SDK transport 代执行。
+- 模型页建议 `stream=true` + `tool_stream=true`，但 Vision OpenAPI 未暴露 `tool_stream`，
+  通用支持模型清单也没有 Flash。普通 Function Calling 已确认，专有工具流优化仍阻断。
+
+## 6. Chat Completions 事件契约矩阵
+
+| 事件 / 响应 | 前置状态 | required / optional / nullable | 空值 / 缺字段语义 | 状态迁移、输出、副作用 | 终态 / 连接 |
+|---|---|---|---|---|---|
+| 非流式成功 | 请求已发送 | `choices`；message.content 在工具调用时可 null；reasoning/tool_calls/usage 按场景可选 | 有工具调用但无文本合法 | 发出非空文本/思考；收集工具与 usage | HTTP 终态，消费后释放 |
+| SSE 普通增量 | 流已建立 | choices 可缺失/为空；delta.content/reasoning_content/tool_calls 均可选，content 可 null/空串 | 空块与无 choices 块合法，忽略 | 非空文本/思考按序追加 | 非终态，保持连接 |
+| SSE 工具增量 | 工具参数未完成 | tool_calls 分片含 index；id/函数名/arguments 可跨块 | 单片不完整合法 | 按 index 拼接；此时不执行工具 | 非终态，保持连接 |
+| SSE 完成块 | 已有零到多个增量 | finish_reason 只在最终块；content 可空；usage 通常只在最终块 | 空文本+finish+usage 合法；纯工具调用也合法 | 保存开放 finish 字符串与 usage，不发空 token | 语义终态，继续消费 `[DONE]` |
+| `[DONE]` | 最终块之后或服务端结束 | 非 JSON 哨兵 | 不解析为对象 | 停止读取并释放 reader/连接 | 流终态 |
+| HTTP 错误 | 端点拒绝请求 | error.code 与 error.message | 不当作增量 | 转脱敏 SDK 错误，保留状态和诊断码 | 终态，释放响应 |
+| 断线 / Abort / timeout | 流已建立 | 无官方专用恢复事件 | 不得当成 `[DONE]` / 成功 | 传播错误、停止工具副作用 | 终态；复用语义未知，宿主释放 |
+| 工具结果续轮 | finish_reason=tool_calls | 保留完整 reasoning/tool_calls；工具消息含 tool_call_id | 丢字段会破坏续轮 | 宿主执行工具并发起新请求 | 新 HTTP/SSE 会话 |
+
+官方流式示例证明最终增量可只有空 `content`、`finish_reason` 与 usage，之后再发 `[DONE]`；
+官方 SDK 示例也先判断 `choices` 是否为空。因此合法空块、无 choices 块必须作为 parser 正例。
+
+`finish_reason` schema 枚举包含 stop/length/tool_calls/sensitive/network_error，但同页说明另提
+`model_context_window_exceeded`。解析器必须接受和保留开放字符串，不能用封闭枚举拒绝返回。
+
+## 7. 官方示例与 fixture 清单
+
+13.2 必须逐项保存下列字面示例并带来源 URL、抓取日期、原样/脱敏说明：
+
+| fixture | 官方来源 | 真实性与用途 |
+|---|---|---|
+| Flash 图片请求 | 对话补全 API | 官方字面示例；替换 API Key/公网媒体即可，model ID 必须保留 |
+| Flash 视频请求 | 对话补全 API | 官方字面示例；覆盖 `video_url` |
+| Flash 文件请求 | 对话补全 API | 官方字面示例；分别识别 file_id/file_url/file_data，不猜上传 purpose |
+| 普通 SSE 文本/思考/最终 usage/`[DONE]` | 流式输出 | 官方字面示例实际 model 为 `glm-5.2`，只能标“同端点相关模型”，不能冒充 Flash |
+| 工具调用参数分块 | 流式工具调用 | 官方字面示例实际 model 为 `glm-5.3`，只能标“同端点相关模型” |
+| 合法无 choices / 空终态 | 上述流式说明与 SDK 判断逻辑 | 可按官方字段表构造，元数据必须标明构造，不冒充原始响应 |
+| 缺字段、乱序、重复、断线等负例 | 事件矩阵推导 | 合成负例，单独目录/元数据 |
+
+当前没有 Flash 模型专属 SSE/工具流响应样本；要取得只能等待官方补充或在用户授权后做真实请求。
+
+## 8. 区域价格
+
+| profile | 币种 | 输入 / M | 输出 / M | 缓存命中 / M | 2026-08-28 促销 |
+|---|---|---:|---:|---:|---|
+| `cn` | CNY | 0.8 | 2.8 | 0.23 | 0.4 / 1.4 / 0.115；页面仅写“5 折限时两周”，无绝对截止日 |
+| `global` | USD | 0.15 | 0.50 | 0.03 | 0.075 / 0.25 / 0.015；截至 2026-09-09 24:00（UTC+8，新加坡时间） |
+
+两区缓存存储均显示限时免费。国内模型页称标准 API 价为 GLM-5.3 的 1/10、限时为 1/20；
+Coding Plan 3 倍额度扣减是订阅用量规则，不是 token 单价。SDK/产品必须让价格随 endpoint profile
+选择，不做静态汇率换算，也不把任何促销固化为长期标准价；实现或发布前分别重新核价。
+
+## 9. 错误与资源边界
+
+- 401：鉴权/令牌问题；429：余额或并发/频率限制；400/403：参数、模型权限或字段冲突；
+  500：服务/网络异常；1261：prompt 过长；1301：敏感内容。
+- 错误响应按 `{error:{code,message}}` 解析并脱敏，不能记录 Authorization、媒体 Base64 或完整用户内容。
+- 官方没有定义中途断线恢复与连接复用。SDK/宿主仍需用 Abort/timeout 终止读取并释放 reader、
+  transport、工具资源；不得把 EOF 当成功 `[DONE]`。
+
+## 10. 未决项与编码阻断
+
+完整能力适配目前被以下官方冲突/缺口阻断：
+
+| 未决项 | 官方冲突 / 缺口 | 保守实现边界 |
+|---|---|---|
+| 结构化输出 | 模型页称支持；Vision OpenAPI 无 response_format，通用说明称仅文本模型支持 | `structuredOutputMode: none`，不发送 response_format |
+| `tool_stream` | 模型页建议开启；Vision schema 无字段，通用支持列表缺 Flash | 只做普通工具调用，不发送 tool_stream |
+| `file_id` 上传 | Chat 接受 file_id；Files API purpose 无 Chat 枚举 | 不实现 file_id 上传；不猜 purpose |
+| 跨模态混合 | 是否可混合和总量限制未说明 | 不承诺/不自动开放任意组合 |
+| Flash 专属事件样本 | 官方流式样本使用其他 GLM 模型 | 通用 parser 可用相关样本测试，但不宣称 Flash 真网事件已验证 |
+| 国内 / 国际 Key 互通 | 两站分别要求到各自平台创建 Key，未声明账号、余额或 Key 可互通 | 分离 credential slot；禁止跨 endpoint 自动试投 |
+
+结论：**完整能力暂不可编码；若 13.2 明确接受上述保守降级，只实现已确认子集，则可编码。**
+
+## 11. 13.2 精确实现输入
+
+- `packages/ai-sdk/src/llm/modelCatalogEntries.ts`：新增独立条目，image/video=true、audio=false、
+  1M/128K；结构化输出保持保守值。
+- `packages/ai-sdk/src/llm/providerPresets.ts`：保留现有国内 `bigmodel` 默认值，加入 Flash；以同一
+  provider family 声明 `cn` / `global` endpoint profiles，不新增第二套 provider 内核。
+- `packages/ai-sdk/src/llm/types.ts`：增加供应商族/endpoint profile/credential identity 的可移植数据契约；
+  国内存量 `providerId=bigmodel` 默认迁为 `cn`，国际配置必须有不同实例 id 和凭据槽。
+- SDK credential 获取与 Electron keystore：凭据不能只按供应商族共享；按配置实例或显式
+  credential identity 区分国内/国际，且迁移不得移动、删除或拿国内 key 试国际端点。
+- `packages/ai-sdk/src/llm/providerReasoningRequest.ts`：现有规则仅供应商感知；若下发
+  clear_thinking=false，先加入模型感知，避免误伤 GLM-5V-Turbo。
+- `packages/ai-sdk/src/llm/streaming.ts` / `chatTypes.ts`：工具增量、合法空块、无 choices、
+  开放 finish reason 与 reasoning 续轮。
+- `packages/ai-sdk/src/llm/sdk/provider.ts`：确认 image/video 在两条消费路径的真实能力；当前 Agent
+  模型步骤不能表达视频，不得静默宣传全路径支持。
+- 文件输入若进入范围，扩统一输入类型与宿主 media/upload 契约，不加手动 URL 或模型旁路。
+- 精确测试：目录/预设/reasoning、多模态序列化、空块/空终态/无 final、工具分块、重复/乱序、
+  错误、Abort/timeout/断线/资源归零；断牙时临时把合法空最终块判错，确认测试失败后恢复。
+
+## 12. 官方来源索引
+
+以下页面均于 2026-08-28 核对：
+
+- [GLM-5.3-Flash 模型说明](https://docs.bigmodel.cn/cn/guide/models/vlm/glm-5.3-flash)：用户指定页面；模型身份、模态、上下文、参数、能力与相对价格。
+- [新模型发布记录](https://docs.bigmodel.cn/cn/update/new-releases)：2026-08-26 上线日期。
+- [模型总览](https://docs.bigmodel.cn/cn/guide/start/model-overview)：定位、上下文、最大输出与价格入口。
+- [对话补全 API](https://docs.bigmodel.cn/api-reference/模型-api/对话补全)：端点、Flash 多模态字面请求、请求/响应 schema 与限制。
+- [流式输出](https://docs.bigmodel.cn/cn/guide/capabilities/streaming)：SSE、空最终块、usage 与 `[DONE]`。
+- [流式工具调用](https://docs.bigmodel.cn/cn/guide/capabilities/stream-tool)：工具参数分块、tool_stream 与续轮。
+- [Function Calling](https://docs.bigmodel.cn/cn/guide/capabilities/function-calling)：工具声明、执行与 tool_call_id。
+- [思考模式](https://docs.bigmodel.cn/cn/guide/capabilities/thinking-mode)：强制思考、交错思考与 clear_thinking。
+- [文件上传 API](https://docs.bigmodel.cn/api-reference/文件-api/上传文件)：上传端点与 purpose 缺口。
+- [错误码](https://docs.bigmodel.cn/cn/faq/api-code)：认证、参数、限流、内容安全与服务错误。
+- [价格页](https://open.bigmodel.cn/pricing)：标准价与核对日促销价。
+- [官方文档全量索引](https://docs.bigmodel.cn/llms.txt)：相关能力页发现与覆盖复核。
+- [国内 Quick Start](https://docs.bigmodel.cn/cn/guide/start/quick-start)：国内 Base URL、API Key 页面与 Flash 模型入口。
+- [国际 GLM-5.3-Flash](https://docs.z.ai/guides/vlm/glm-5.3-flash)：国际站模型 ID、模态、上下文、参数与能力。
+- [国际 Quick Start](https://docs.z.ai/guides/overview/quick-start)：国际 Base URL、API Key 页面与 Flash 模型入口。
+- [国际 HTTP API](https://docs.z.ai/guides/develop/http/introduction)：国际通用端点与 Bearer 鉴权。
+- [国际价格](https://docs.z.ai/guides/overview/pricing)：USD 标准价、促销价和绝对截止时间。