@henjicc/ai-sdk 0.2.8

package/CHANGELOG.md

@@ -0,0 +1,143 @@
+# Changelog
+
+## Unreleased
+
+## 0.2.8 - 2026-08-31
+
+- 正式分发渠道从需要读包凭据的私有 GitHub Packages 迁移到公共 npm；消费项目现在可以直接安装 `@henjicc/ai-sdk`，无需 `.npmrc` 或访问令牌。
+- 发布前门禁固定校验 npm 公共 registry、仓库 scope 映射与 `access=public`，并提供显式指定公共源的 `npm run publish:sdk`，避免用户级配置把版本误发回私有源；正式发布仍只由 npm 包维护者手动执行。
+- 本次只调整分发与安装契约，不改变 0.2.7 的运行时 API、模型目录、请求协议或宿主能力边界。
+
+## 0.2.7 - 2026-08-31
+
+- ASR 按需能力从百炼 9 个模型扩展到 15 个：新增火山引擎 SeedASR 2.0 文件 submit/query 与二进制实时 WebSocket、硅基流动 SenseVoiceSmall/TeleSpeechASR，以及 Groq Whisper Large v3/Turbo。
+- 火山实时协议严格校验 V1 大端二进制帧、sequence、payload size、gzip 与终包语义；文件标准版只接受官方要求的公网 URL，不为本地文件伪造上传能力。
+- Groq 与硅基流动使用各自官方 multipart 转写契约并统一输出 `SpeechRecognitionOutput`；Groq `verbose_json` 额外归一化时长、分句和词级时间戳，免费层默认按 25 MB 本地上限保护，消费宿主可按套餐显式调整。
+- 新增四个 ASR 独立 exports、官方来源 fixture、协议断牙测试、bundle 隔离、仓外 Vite/Node ESM 与无全局 TextEncoder/TextDecoder 的受限宿主门禁。
+
+- 默认生成目录从 99 个扩展到 105 个模型，新增六个 Fal 入口：IC-Light v2 重打光，以及 Topaz、Topaz 透明图、SeedVR2、Bria Creative、Ideogram 高清放大；按需工具仍不混入默认目录。
+- IC-Light v2 固定单图约 1MP 重打光契约，并提供五档官方初始光照方向；Fal GPT Image 2 新增 `2:1` 比例和显式约 2K 输出档。
+- Topaz 图片放大统一为 Precision / Creative / Generative 显式模式路由，按模式裁剪模型、增强和人脸参数；Topaz 计价改为按实时官方输出 MP 阶梯计算，不再将所有超过 48MP 的任务直接估为 `$1.36`。
+- Fal 可选图片工具扩展到 12 个：保留 3 个消除工具，新增 6 个重打光、暗光增强、扩图、商品摄影、照片修复、背景移除工具，以及 Qwen、Perspective、FLUX 2 三个多角度工具；提供 3 / 6 / 3 三个聚合 pack 和对应单模型入口。
+- 多角度工具分别支持九档离散方位、透视水平/垂直旋转与 FLUX 2 连续水平、垂直、缩放控制；图片实用工具保持单图输入、官方字段限制和独立固定/按 MP 估价。
+- 新增可移植的 `StructuredGenerationOutput` / `layer-stack` 响应契约；火山引擎、APIMart、KIE 的 Seedream 5.0 Pro 图层拆分统一解析输出顺序、尺寸、格式、包围盒和原始索引，同时保留供应商原始 metadata。
+- Fal 队列提交现在只把 `sync_mode: true` 当作本地直连路由标记；显式 `sync_mode: false` 会继续发送给队列，保证 Pixelcut 等端点返回可持久化 CDN URL。
+- Fal 返回或恢复的 `status_url` / `response_url` 必须属于官方 `https://queue.fal.run` 源，拒绝带用户信息或第三方源的任务 URL，且 `invalid_endpoint` 不进入轮询重试，避免 API Key 被外带。
+- `continuePolling()` 只解析模型端点，不再为了续查重建并校验完整生成请求体；持久化任务可在没有原始媒体参数时安全恢复轮询。
+- 新增 `openai-responses` 模型步骤协议，与 Chat Completions 并存；标准 Responses SSE、usage、失败与取消统一落到既有模型步骤事件和错误契约。
+- 预制供应商按“供应商端点 × 具体模型”自动选择协议：DeepSeek、火山引擎、百炼、MiniMax 与智谱国内 GLM-5.3 的已确认组合默认 Responses，聚合网关和未确认模型继续 Chat。
+- Anthropic 协议仍未实现，不再向宿主设置界面提供伪选项；自定义未知端点只需在 Chat / Responses 之间选择。
+- `LlmProviderSetup` 新增可选 `connectionOverrides`：预设默认继续按具体模型自动路由，只有用户主动修改时才覆盖 API 地址或统一请求协议；供应商身份、凭据槽与模型能力仍保留预设契约。
+- 发布门禁同步锁定 105 个默认模型、12 个 Fal 工具、三类工具聚合包以及仓库外 Node ESM、严格 TypeScript、Vite 与受限宿主包回装；fixture/scripted 验证不发起付费供应商请求。
+
+## 0.2.6 - 2026-08-28
+
+- 新增统一的 `PROVIDER_METADATA` 与 `findProviderMetadata(providerId, options)` 公共契约，覆盖全部生成供应商、LLM 预设与 BigModel 国内/国际端点的官网和 API Key 入口。
+- 派欧云、KIE、APIMart 的 `websiteUrl` 保留项目已有邀请码，其余供应商使用正常官网；未知自定义供应商返回 `null`，宿主无需复制或猜测链接。
+- LLM preset 与 endpoint profile 改为消费统一供应商目录，并更新 Kimi、MiniMax、小米 MiMo、百炼、火山引擎等已变化的控制台入口。
+
+## 0.2.5 - 2026-08-28
+
+- 新增 `LlmProviderSetup` 的 preset/custom 来源契约和 `builtin | user` 生命周期；已有配置字段与工厂参数均保持可选，0.2.4 消费代码无需迁移即可继续运行。
+- `createProviderFromPreset()` 现在显式返回稳定 `credentialId` 与 setup 来源，并允许宿主把正式内置记录标为 `builtin`；BigModel cn/global 仍保持区域化 endpoint profile 与凭据隔离。
+- 新增 API Key 管理地址规范化与解析：endpoint profile 官方地址优先，其次 preset 官方地址，custom 只接受不含内嵌凭据、长度不超过 2048 的绝对 HTTP(S) URL。
+
+## 0.2.4 - 2026-08-28
+
+- 新增 `@henjicc/ai-sdk/llm/bigmodel` 按需入口：保留 `bigmodel` 中国大陆默认实例，并在同一协议族内提供 `cn/global` 两个端点 profile、独立凭据槽和分区价格。
+- 新增 GLM-5.3-Flash 的保守能力目录与 Chat Completions 文件引用、普通 SSE 工具分片支持；结构化输出、`tool_stream` 与 SDK 未实现的 `file_id` 上传保持关闭。
+- LLM 原生流式与模型步按 `providerFamilyId` 应用协议规则、按 `credentialId` 取密钥，并拒绝 BigModel 跨区端点或凭据错配。
+
+本项目遵循语义化版本。`0.x` 阶段仍可能包含破坏性调整，升级时请先阅读对应版本说明。
+
+## 0.2.3 - 2026-08-28
+
+- 修复 Fun-ASR Realtime 把官方 `sentence_begin=true`、`sentence_end=false`、`text=""` 句首生命周期事件误报为 `invalid_response`；空句首现在继续等待真实文本。
+- 保持严格终态：空 final 仍报协议错误，任务全程没有有效 final 时在 `task-finished` 报无有效转写；空 `task-finished.payload` 不覆盖已累计结果。
+- 重复 final 只累计并通知一次；补齐官方事件 fixture、用户错误回归、空终态、终态顺序、错误与资源释放断牙测试。
+
+## 0.2.2 - 2026-08-28
+
+- 新增按需入口 `@henjicc/ai-sdk/llm/modules`：外部包、插件与内置 LLM 共用 source-aware 注册、流式/非流式执行、模型发现、取消、drain、namespace 注销和 dispose 生命周期。
+- LLM module 复用现有 Chat DTO、Token/ReasoningToken、usage、Abort/timeout、RuntimeContext、日志、trace 与统一 discovery；client 统一发射 Usage/Finish/Done/Error，插件不需要导入 SDK，也没有第二套插件专用执行器。
+- module ID 与 provider/model 坐标冲突均拒绝覆盖并列出双方 source；新增 `createGroqLlmModule()`，正式验证外部插件不能遮蔽内置 Groq。
+- 新增精确资源/断牙测试、无网络 bundle 隔离门禁，以及远端 Node ESM、strict TypeScript、Vite 和无全局 `TextEncoder` / `TextDecoder` 消费验证。
+
+## 0.2.1 - 2026-08-28
+
+- 修复构建期 ESM specifier 重写漏掉精确 `.` / `..` 目录导入，确保 Node ESM 消费方可直接加载 ASR、实时 ASR、翻译和 Groq 按需入口。
+- 发布门禁新增仓库外 Node ESM 实际执行，连同严格 TypeScript、Vite、无全局 `TextEncoder` / `TextDecoder` 与 bundle 隔离一起验证；发布说明将 `0.2.0` 标记为不建议使用。
+
+## 0.2.0 - 2026-08-28
+
+- 新增供应商无关的 ASR、翻译与实时会话能力协议；宿主按需注入 HTTP、实时连接、媒体读取、凭据、日志、Abort 与超时，不依赖 Node/Electron 或浏览器全局 WebSocket。
+- 新增 5 个百炼短音频/文件 ASR、4 个百炼实时 ASR、Qwen-MT Flash/Plus/Lite，以及 Groq GPT-OSS 20B 流式聊天、静态默认模型与模型发现入口；具体能力均需从独立子路径显式导入。
+- capability descriptor 新增必填 `source.kind/source.namespace`，支持内置/外部/插件所有权、冲突诊断、来源批量卸载和资源释放；module ID、provider/kind/model 坐标与统一 discovery ID 冲突不再静默覆盖。
+- **破坏性变更**：百炼 ASR module ID 从 `bailian.<modelId>` 统一为 `bailian.speech-recognition.<modelId>`，SDK 不保留旧 ID 或 `funasr` provider alias；已有宿主持久化数据需一次性迁移。
+- 新增 ASR、翻译、Groq 与开放 OCR/custom operation 的穷举/断牙测试及独立 bundle 门禁；所有供应商 fixture 均不含真实密钥，本版本发布验证不发起付费模型请求。
+
+## 0.1.8 - 2026-08-28
+
+- 修复 Photoshop UXP 9.2 缺少全局 `TextDecoder` 时 LLM SSE 无法启动：窄流式入口改用 SDK 内部增量 UTF-8 解码器，不要求宿主注入 DOM 或 Node polyfill。
+- UTF-8 解码覆盖中文与 emoji 跨 chunk、畸形/过长/代理项/越界序列的替换字符语义，以及流结束截断尾段 flush；LLM reasoning/text/usage/stop/`[DONE]` 和 Abort 契约不变。
+- UXP 门禁不再向 VM 注入 `TextEncoder` / `TextDecoder`，并禁止重新引入直接 `TextDecoder` 构造。
+
+## 0.1.7 - 2026-08-28
+
+- 新增 `@henjicc/ai-sdk/llm/streaming` 受限宿主入口，仅包含原生 OpenAI-compatible SSE、取消、必要类型与错误协议，不静态带入 modelStep、Zod 或 Vercel AI SDK。
+- 原生 SSE 补齐 usage 与 finish reason 结果，保持 reasoning/text 事件与旧入口兼容；覆盖 UTF-8 跨 chunk、`[DONE]`、供应商错误与 Abort。
+- 新增关闭 tree-shaking 的 UXP LLM IIFE/ESM 发布门禁，禁止动态代码生成、Node 全局与非必需 Streams polyfill。
+
+## 0.1.6 - 2026-08-28
+
+- APIMart Nano Banana 2、Lite、Pro 新增常规/官方双渠道，保持常规渠道为默认，并按渠道切换精确模型 ID 与估价。
+- APIMart Seedream 5 Pro 补齐官方合法的 `2:1` / `1:2`；Pro/Lite 对列表外比例显式报错，不再静默降级 1:1。
+- Fal Seedream 5 Pro/Lite、Qwen Image 3、GPT Image 2、Z-Image 补齐通用比例与显式约 1MP 请求档；GPT Image 2 补齐 `quality=auto`，所有 0.1.5 默认保持不变。
+- 补齐 Photoshop adapter 迁移交接；APIMart Midjourney、Z-Image、GPT Image 2 与 Fal Nano 隐藏默认经官方契约核证后维持现实现。
+
+## 0.1.5 - 2026-08-28
+
+- 新增零内置依赖的 `generation/core`、99 个完整单模型 pack、8 个 provider adapter/pack；默认
+  `generation` 仍保持 99 模型兼容行为。
+- 新增 provider-scoped 媒体预处理/上传策略，完整 pack 可独立完成媒体读取、上传与生成生命周期。
+- 新增开放 capability module 协议，支持 ASR/OCR 等非媒体生成能力按模块注册、发现、类型化执行与取消。
+- 新增 3 个不进入默认目录的 Fal 图像消除单模型 pack 与聚合 `tool-packs/fal-image-edit-tools`，复用同一
+  Fal 上传、队列、轮询、错误与取消内核。
+- 新增跨 generation、LLM 与开放扩展的统一能力画像和组合筛选；筛选只作用于宿主已导入候选，
+  静态最小化仍由单模型、供应商或模型集合 pack 的 import 边界决定。
+
+## 0.1.4 - 2026-08-27
+
+- 新增 `@henjicc/ai-sdk/generation` 与 `createGenerationClient`，复用根客户端唯一生成内核，不静态带入 LLM/Vercel AI SDK。
+- 新增 generation IIFE/VM 发布门禁：99 模型目录与零网络生命周期通过，禁止 Node、动态代码生成、global fetch、Streams、File、`btoa`/`atob` 等受限宿主风险。
+- Fal CDN 上传改为全程使用 `RuntimeContext.transport` 的 REST initiate + signed PUT，不再依赖 `@fal-ai/client` 或构造 `File`；补齐成功、失败、取消 fixture。
+- 保留 `uploadToFal(apiKey, prepared)` 两参数兼容调用；新宿主应显式传 Transport 或使用生成客户端。
+
+## 0.1.3 - 2026-08-27
+
+- 修复 Fal 队列任务在提交 alias 与状态查询 canonical route 不一致时轮询失败：优先保存供应商返回的完整 `status_url`，仅缺失时才按 `request_id` 重建。
+- 完整 `status_url` 轮询完成后仍还原纯 request id，避免状态 URL 被媒体结果收集器误判为生成结果。
+- KIE/Fal Seedream 4.0、4.5 四个历史 override 已完成真实供应商单张最小规格验证；KIE/APIMart/PPIO 只读连通性与 KIE/APIMart 设置页余额展示已完成正式 Electron 验证。
+
+## 0.1.2 - 2026-08-27
+
+- 修复发布包在标准 Vite 开发模式下无法解析：五个 `exports` 入口不再优先指向未随包发布的 `src/`，统一解析到已发布的 `dist/` ESM 与类型声明。
+- 发布前门禁新增仓库外临时消费方的标准 Vite dev server 解析回归，覆盖包根及四个子路径入口，防止再次发布只在 monorepo 内可用的条件导出。
+
+## 0.1.1 - 2026-08-27
+
+- 新增 Electron、Tauri、UXP 接入指南，以及供应商域名与错误处理参考。
+- 新增 `minimal-node`、`form-renderer`、`llm-chat` 三个可构建示例。
+- 重写快速开始，补齐 GitHub Packages 私有安装、四项宿主接口注入和生成/轮询示例。
+
+- 不改变 `0.1.0` 的运行时 API；此补丁版用于交付完整指南、示例与已知限制。
+
+## 0.1.0 - 2026-08-27
+
+- 首次私有发布到 GitHub Packages：`@henjicc/ai-sdk`。
+- 提供 8 个生成供应商、99 个模型目录、媒体上传预处理与统一 `createAIClient` 入口。
+- 提供 OpenAI-compatible LLM 流式执行与模型步能力。
+- 提供 5 个 ESM 导出入口、完整 TypeScript 类型声明及模型/LLM 适配文档。
+- 产物保留源码模块结构，不预打成单文件，供 UXP、Tauri 与现代 Node 打包器静态分析和 tree-shaking。
+
+迁移说明：这是首次发布，无历史 npm 版本需要迁移；仓库内原占位导入名 `@henji/ai-sdk` 已统一改为 `@henjicc/ai-sdk`。

package/README.md

@@ -0,0 +1,472 @@
+# @henjicc/ai-sdk
+
+痕迹AI 的多供应商模型 SDK：内含 8 个生成供应商、105 个图片/视频/音频模型，以及
+7 家 LLM 供应商预设（加上派欧云聚合入口共 8 个预设项）和 15 个按需 ASR 模型。另有 12 个 FAL 图片工具使用独立按需入口，不进入默认 105 模型目录。预制 LLM 会按供应商与具体模型自动选择 Responses API 或 Chat Completions，宿主不需要暴露逐模型协议设置。SDK 负责目录、请求构建、媒体预处理、
+供应商调用、轮询、SSE 与错误归一化；宿主只需注入网络、凭据、媒体读取和日志。
+
+## 5 分钟快速开始
+
+SDK `0.2.8` 公开发布在 npm，无需配置 registry 或访问令牌：
+
+```bash
+npm install @henjicc/ai-sdk@0.2.8
+```
+
+然后提供 4 个宿主能力（`Transport` / `CredentialStore` / `MediaReader` / `Logger`），创建客户端：
+
+```ts
+import { readFile } from 'node:fs/promises'
+import { basename } from 'node:path'
+import { createAIClient, type RuntimeContext } from '@henjicc/ai-sdk'
+
+const runtime: RuntimeContext = {
+  transport: { fetch: (url, init) => fetch(url, init) },
+  credentials: {
+    get: (scope, providerId) =>
+      scope === 'generation' && providerId === 'kie' ? process.env.KIE_API_KEY : undefined,
+  },
+  media: {
+    read: async (ref) => ({
+      bytes: new Uint8Array(await readFile(ref)),
+      mimeType: 'image/png',
+      filename: basename(ref),
+    }),
+  },
+  logger: {
+    info: console.log,
+    warn: console.warn,
+    error: console.error,
+  },
+}
+
+const client = createAIClient({ runtime })
+try {
+  const params = { prompt: 'A blue paper boat', kieZImageAspectRatio: '1:1' }
+  const created = await client.generate({ modelId: 'kie-z-image', params })
+  const result = created.status === 'pending' && created.taskId
+    ? await client.continuePolling({ modelId: 'kie-z-image', taskId: created.taskId, params })
+    : created
+  console.log(result.url) // SDK 返回 URL；宿主决定是否下载落盘
+} finally {
+  client.dispose()
+}
+```
+
+可直接运行的 Node 版本在 [examples/minimal-node](examples/minimal-node/README.md)；它先提供零网络
+`dry-run`，并为付费创建请求加了单次外网闸门。
+
+## 宿主契约
+
+| 接口 | 宿主必须保证 |
+|---|---|
+| `Transport.fetch` | 返回标准 `Response`，保留 4xx/5xx 响应，网络失败抛异常，尊重 `AbortSignal` |
+| `CredentialStore.get` | 按 scope/providerId 读取明文密钥；未配置或丢失时返回 `undefined` |
+| `MediaReader.read` | 将宿主的本地/受管引用转成 `Uint8Array + mimeType + filename` |
+| `Logger` | 可选；不得记录 API key/token/cookie/授权头 |
+| `Tracer` | 可选；缺省为 no-op |
+
+生成和 LLM 取消都必须带命名空间：
+`client.cancel({ namespace: 'generation' | 'llm', taskId })`。自定义 provider 使用进程级注册表，
+同 ID 并发注册会拒绝；持有它的 client 退出时必须 `dispose()`。
+
+供应商官网与 API Key 入口由 SDK 统一提供，宿主不需要再维护一份链接表：
+
+```ts
+import { findProviderMetadata } from '@henjicc/ai-sdk'
+
+const provider = findProviderMetadata('kie')
+console.log(provider?.websiteUrl, provider?.apiKeyUrl)
+
+// 同一供应商的区域站点通过 endpointProfile 选择。
+const zAi = findProviderMetadata('bigmodel', { endpointProfile: 'global' })
+```
+
+LLM 预设默认使用 SDK 维护的官方地址，并按具体模型选择 Chat Completions 或 Responses。宿主若允许高级用户修改连接信息，应把主动修改写入
+`setup.connectionOverrides`；字段缺省时保持自动路由，不要把 SDK 的默认值复制成覆盖值。
+
+`websiteUrl` 是面向用户的实际跳转入口；派欧云、KIE、APIMart 会保留项目配置的邀请码，
+其余供应商使用正常官网。未知的自定义供应商返回 `null`，SDK 不猜测地址。
+
+## 接入文档与示例
+
+- [SDK 消费项目清单](docs/consumers.md)
+- [Electron 主进程适配](docs/接入指南/Electron.md)
+- [Tauri 2 适配](docs/接入指南/Tauri.md)
+- [Photoshop UXP 适配](docs/接入指南/UXP.md)
+- [供应商域名与白名单](docs/接入指南/供应商域名.md)
+- [错误处理](docs/接入指南/错误处理.md)
+- [Node KIE 生成](examples/minimal-node/README.md)
+- [5 模型表单契约](examples/form-renderer/README.md)
+- [LLM 流式对话](examples/llm-chat/README.md)
+
+## 发布形式与可移植性
+
+发布产物是保留模块边界的 ESM + `.d.ts`，没有 CJS `require` 入口。CommonJS 项目请用
+动态 `import()`。UXP/Tauri 必须在构建期用 Vite/Rollup/webpack/esbuild 打包实际使用的 ESM 依赖。
+SDK 源码不得依赖 `@/`、`node:`、Electron、`import.meta.glob`、`eval`/`new Function`/`node:vm`；
+`npm run check:sdk` 会守住这些边界。Photoshop/受限宿主只做生成时应从
+`@henjicc/ai-sdk/generation` 导入 `createGenerationClient`；该入口不静态带入 LLM、Vercel AI SDK、
+Node 内置模块或 Fal 官方客户端，发布门禁会把它打成 IIFE 并在无网络生命周期中核对 105 个模型。
+
+## 按需装配生成模型
+
+`@henjicc/ai-sdk/generation` 是兼容入口，默认始终装入 105 个模型。真正需要缩小 Photoshop/Tauri
+包体时，从不含任何内置 catalog/provider 的 `generation/core` 创建模块化客户端，并只导入完整 pack：
+
+```ts
+import { createModularGenerationClient } from '@henjicc/ai-sdk/generation/core'
+import { pack as kieZImage } from '@henjicc/ai-sdk/models/kie/z-image'
+
+const client = createModularGenerationClient({ runtime, packs: [kieZImage] })
+console.log(client.catalog.list().map((model) => model.meta.id)) // ['kie-z-image']
+```
+
+完整单模型 pack 同时携带该模型的唯一真实 schema、provider adapter 与 provider-scoped 媒体预处理/
+上传策略；宿主不需要知道内部上传模块。`@henjicc/ai-sdk/provider-packs/kie` 可一次装入 KIE 的全部
+27 个模型；`provider-adapters/kie` 只装入 KIE 执行与上传策略、不装任何模型。所有 105 个单模型路径和
+8 个供应商路径由 catalog 生成器自动产出并由 bundle 门禁穷举，新增模型不会靠手工维护 exports。
+
+每个 `models/<provider>/<model>` 子路径也导出名为 `model` 的低层定义，供目录分析或高级自定义组合；
+直接传裸 `model` 而不传同文件的 `pack` 不保证媒体上传或供应商执行完整，普通宿主应使用 `pack`。
+包根 `createAIClient` 仍默认 105 模型；若确实需要根 client 的 chat 与按需生成共存，可显式传：
+
+```ts
+const client = createAIClient({
+  runtime,
+  generation: { mode: 'modular', packs: [kieZImage] },
+})
+```
+
+普通 LLM 宿主可直接导入 `@henjicc/ai-sdk/llm`。Photoshop UXP 等禁止字符串代码生成的受限宿主
+必须改用 `@henjicc/ai-sdk/llm/streaming`：它只提供原生 OpenAI-compatible SSE 的
+`runLlmChatStream`、`cancelLlmChatTask` 与必要类型/错误，不会进入 modelStep、Zod、Vercel AI SDK
+或 generation 静态图。两条入口复用同一份原生流式实现，不存在功能分叉。
+
+```ts
+import {
+  cancelLlmChatTask,
+  runLlmChatStream,
+  type LlmChatRequestDto,
+  type RuntimeContext,
+} from '@henjicc/ai-sdk/llm/streaming'
+
+const request: LlmChatRequestDto = {
+  requestId: 'chat-1', providerId: 'openai', modelId: 'gpt-5-mini',
+  messages: [{ role: 'user', content: '你好' }],
+}
+const result = await runLlmChatStream(request, 'chat-1', onStreamEvent, runtime as RuntimeContext)
+console.log(result.output, result.reasoningOutput, result.usage, result.finishReason)
+cancelLlmChatTask('chat-1')
+```
+
+### 可选模型分发包与统一能力筛选
+
+当前 12 个 FAL 图片工具不会混入默认 105 模型。宿主可选择单个完整工具模型 pack，也可按用户任务装入三个聚合包：
+
+- `tool-packs/fal-image-edit-tools`：3 个消除工具。
+- `tool-packs/fal-image-utility-tools`：6 个重打光、暗光增强、扩图、商品摄影、照片修复和背景移除工具。
+- `tool-packs/fal-multi-angle-tools`：3 个连续镜头控制或离散方位工具。
+
+```ts
+import { createModularGenerationClient } from '@henjicc/ai-sdk/generation/core'
+import { createModelCapabilityDiscovery } from '@henjicc/ai-sdk/discovery'
+import { pack as falImageEditTools } from '@henjicc/ai-sdk/tool-packs/fal-image-edit-tools'
+import { pack as falImageUtilityTools } from '@henjicc/ai-sdk/tool-packs/fal-image-utility-tools'
+
+const eraseDiscovery = createModelCapabilityDiscovery({ generationPacks: [falImageEditTools] })
+const utilityDiscovery = createModelCapabilityDiscovery({ generationPacks: [falImageUtilityTools] })
+const erasers = eraseDiscovery.search({
+  providerIds: 'fal',
+  outputModalities: 'image',
+  operations: 'image-edit',
+  features: 'erase',
+})
+const utilities = utilityDiscovery.search({ providerIds: 'fal', outputModalities: 'image' })
+const client = createModularGenerationClient({
+  runtime,
+  packs: [falImageEditTools, falImageUtilityTools],
+})
+console.log(erasers.map((item) => item.id))
+console.log(utilities.map((item) => item.id))
+```
+
+单模型入口按集合分为：
+
+- 消除：`tool-models/fal/flux-pro-erase`、`tool-models/fal/bria-eraser`、`tool-models/fal/finegrain-eraser`。
+- 图片实用工具：`tool-models/fal/relighting`、`tool-models/fal/control-light`、`tool-models/fal/outpaint`、`tool-models/fal/product-photography`、`tool-models/fal/photo-restoration`、`tool-models/fal/pixelcut-background-removal`。
+- 多角度：`tool-models/fal/qwen-image-edit-2509-multiple-angles`、`tool-models/fal/perspective-change`、`tool-models/fal/flux-2-multiple-angles`。
+
+每个单模型入口只导出 `model`、`provider` 与完整 `pack`。三个聚合包只携带各自 3 / 6 / 3 个工具模型、Fal adapter 和 Fal CDN 上传，不携带其余 105 模型或 LLM。能力筛选与分发是两层：`search()` 只过滤已经导入的候选，不会让已经进入 bundle 的代码自动消失；缩小包体仍必须显式选择单模型/provider/collection pack。
+
+Henji-AI 在执行层按需装入工具 pack，但普通模型选择器、`@henjicc/ai-sdk/generation` 与默认能力发现仍只展示 105 个主目录模型。
+
+## 两类模型的公共边界
+
+生成模型与 LLM 共用以下基础设施：
+
+| 能力 | 统一实现 | 约束 |
+|---|---|---|
+| 凭据 | `RuntimeContext.credentials` / `CredentialStore` | 用 `generation`、`llm` scope 隔离宿主密钥空间 |
+| 网络 | `Transport` + `fetchProvider` | 只自动重试可证明尚未建连的错误，避免重放可能计费的请求 |
+| 错误 | `runtime/errors.ts` + `runtime/error-classify.ts` | 生成错误码字符串保持稳定；LLM 保留鉴权、余额、限流、上下文、内容过滤等细分类 |
+| 取消 | `runtime/task-registry.ts` | 单一 registry，以 `generation` / `llm` 命名空间隔离同名任务 |
+| 重试判断 | `shouldRetry(error, mode)` | `safe-preconnect`、`request`、`poll-query` 共用分类，但策略生命周期不同 |
+| 追踪 | `RuntimeContext.tracer` | SDK 只报告通用 span；助手专属 trace 由痕迹AI 宿主持有 |
+
+以下协议刻意保持分离：
+
+- 生成模型是“创建任务 → 可选轮询 → 提取媒体结果”，允许长时间轮询，并容忍状态查询的连续瞬态失败。
+- LLM 是 SSE 流式或 Vercel 模型步，持续输出 token / tool call，单次请求失败按模型步策略处理。
+
+二者的终止条件、进度含义、结果形状和可安全重试边界都不同。把它们压成一个通用 `execute()`
+只会隐藏协议差异，无法形成可靠抽象；第五阶段统一客户端只应在入口层分组编排，不应合并生命周期。
+
+## 目录与参数表单契约
+
+消费方从 client 私有目录读取模型，不需要自行复刻 canonical/alias 索引规则：
+
+```ts
+const images = client.catalog.listByType('image')
+const falModels = client.catalog.listByProvider('fal')
+const editors = client.catalog.listByTag('supports-image-editing')
+const params = client.catalog.getParams('fal-ai-gpt-image-2')
+const defaults = client.catalog.getDefaultValues('fal-ai-gpt-image-2')
+const price = client.catalog.estimatePrice('fal-ai-gpt-image-2', defaults)
+```
+
+价格依赖本地图片像素或视频时长时，模型会在 `pricing.mediaContext` 声明所需指标。消费方从
+`@henjicc/ai-sdk/pricing` 调用 `resolvePricingMediaContext()`，只需注入自身的图片/视频元数据读取器；
+SDK 统一处理媒体来源优先级、首个/求和聚合、固定倍率和参数倍率换算，再把结果交给原模型 calculator。
+指标无法读取时返回 `complete: false`，消费方应隐藏总价，而不是显示最低档兜底价。
+
+`getParams()` 返回纯运行时 `RuntimeParamDef[]`。参数名、选项 label、图标、分组布局、linkages 和
+痕迹AI 特有 composite 面板配置属于应用 presentation，不在 SDK 目录里；通用消费方可以用参数 ID
+作最小标签，也可以在宿主维护自己的本地化展示层。`composite` 只保证值类型/default/API 契约，宿主
+必须按参数 ID 注入自定义组件，不能从 SDK 还原痕迹AI 专属面板。
+
+### 参数类型 → 控件
+
+以下 13 种是 `RuntimeParamDef` 的完整公开联合；括号内是当前真实 105 catalog 的出现数量。未出现不代表
+类型无效，而是当前目录没有对应模型。
+
+| type | 105 catalog | 消费方控件 | 关键运行时字段 |
+|---|---:|---|---|
+| `dropdown` | 298 | 下拉选择 | `options[].value`、`default`、`required?` |
+| `switch` | 92 | 布尔开关 | `default` |
+| `number` | 83 | 数值输入/步进器 | `min?`、`max?`、`step?`、`default` |
+| `text` | 7 | 单行文本 | `maxLength?`、`default` |
+| `image-upload` | 5 | 图片上传 | `maxCount?`、`accept?`、`maxSize?`、`format?` |
+| `composite` | 4 | 宿主自定义组件钩子 | `valueType?`、`default`；panel/config 不在 SDK |
+| `textarea` | 3 | 多行文本 | `maxLength?`、`default` |
+| `file-upload` | 1 | 文件上传 | `maxCount?`、`accept?`、`maxSize?` |
+| `radio` | 0 | 单选组 | `options[].value`、`default` |
+| `panel` | 0 | 递归分组容器 | `children[]`；布局样式由宿主决定 |
+| `video-upload` | 0 | 视频上传 | `maxCount?`、`accept?`、`maxSize?`、时长范围 |
+| `resolution` | 0 | 分辨率选择 | `presets[].value`、`allowCustom?` |
+| `aspect-ratio` | 0 | 比例选择 | `options[].value` |
+
+所有参数共有 `id`、`type`、`order`、`default`，并可带 `required`、`valueType`、API 映射、
+`transferKey`、`visible`、`disabled`。实际 105 catalog 的字段集合与数量由
+`packages/ai-sdk/tests/catalog-consumer-contract.test.ts` 穷举锁定，不以旧 ParamDef 文件或示例推断。
+
+### 条件与媒体输入
+
+- `evaluateRuntimeCondition()` 是条件显隐/inputLimits/requirements 的公共判断入口。函数条件直接调用；
+  字符串条件使用受限 parser，支持真实 catalog 用到的标识符、`.length`、字面量、`typeof`、比较、
+  `&&`/`||`/`!`、括号和 `Array.isArray()`。它不使用 `eval`/`new Function`；未知 token、属性或调用
+  会抛出明确错误，不会静默判为 false。
+- `resolveRuntimeInputLimits()` 解析数据型/函数型输入限制并应用条件规则。
+- `getRuntimeMediaInputContract()` 把 `inputLimits` 的通用图片/视频/音频入口、显式
+  `image-upload`/`video-upload`/`file-upload` 参数，以及 `runtimeConstraints.mediaFields` 的特殊请求字段
+  分层返回。消费方必须据此渲染上传组件；不存在 URL 文本框 fallback。
+
+最小无框架验证器位于 `examples/form-renderer/`。它用 5 个真实模型覆盖普通选择、数值范围、条件显隐、
+通用与特殊媒体上传、composite 自定义钩子，可作为无 UI 框架的最小接入参考。
+
+本包不发布 JSON catalog 快照。Tauri/UXP 消费端都能在构建期使用 ESM，而真实目录包含 builder、
+计价、显隐和 inputLimits 函数，JSON 无法无损表达；并行发布不完整快照会形成第二份真相。未来只有出现
+明确的非 JavaScript/TypeScript 消费方时，才应另行设计带版本的可序列化投影契约。
+
+## 扩展模型类型与供应商
+
+`ModelType` 与 `ProviderId` 都采用“内置字面量 + 开放字符串”的形式：编辑器仍会提示
+`image` / `video` / `audio` 和 8 个内置供应商，同时消费方可以直接声明自己的类型与 provider id。
+下面的 TypeScript 示例不新增真实模型或供应商，只演示完整的注册、索引与请求构建机制：
+
+```ts
+import {
+  buildRequest,
+  createModelIndex,
+  defineModel,
+  registerProvider,
+  unregisterProvider,
+} from '@henjicc/ai-sdk'
+
+const providerId = 'acme-transcript'
+
+async function main(): Promise<void> {
+  registerProvider(providerId, {
+    execute: async (input) => ({
+      status: 'completed',
+      url: 'memory://result',
+      metadata: { requestBody: input.body },
+    }),
+    continuePolling: async () => ({
+      status: 'failed',
+      url: '',
+      metadata: { reason: 'not-supported' },
+    }),
+  })
+
+  try {
+    const model = defineModel({
+      meta: {
+        id: 'acme-transcript-v1',
+        canonicalModelId: 'acme-transcript-v1',
+        provider: providerId,
+        type: 'transcript',
+      },
+      params: [{ id: 'text', type: 'text', order: 1, default: '' }],
+      endpoints: '/v1/transcript',
+      request: { builder: (params) => ({ input: params.text }) },
+      pricing: { currency: '$', fixed: 0 },
+    })
+
+    const index = createModelIndex([model])
+    const request = await buildRequest(
+      { text: 'hello' },
+      index.get('acme-transcript-v1'),
+    )
+    console.log(request)
+  } finally {
+    unregisterProvider(providerId)
+  }
+}
+
+void main()
+```
+
+注册表语义是确定的：`registerProvider` 遇到同名 id 会抛
+`provider_already_registered`，不会覆盖既有适配器；`unregisterProvider` 删除成功返回 `true`，
+未登记返回 `false`；`listProviders` 返回快照，修改返回数组不会改动注册表。插件与测试应使用唯一 id，
+并在 `finally` / `afterEach` 中注销。SDK 在首次访问 provider 注册表时惰性初始化 APIMart、Bailian、
+Volcengine、PPIO、KIE、ModelScope、Fal、Grsai 八个内置供应商；调用方无需手工初始化。惰性初始化
+避免依赖仅靠模块加载保留的副作用，使 `sideEffects: false` 与 tree-shaking 语义一致。
+
+### 跨模型类型的统一能力画像
+
+`@henjicc/ai-sdk/discovery` 只负责发现和筛选，不改变 generation、LLM 或扩展模块各自的执行协议。
+画像从已导入候选的真实 schema 派生，统一提供 provider、输出模态、operation、输入/输出内容类型、
+features 与原始 tags。顶层查询维度默认 AND，也可设 `mode: 'any'`；单一维度可用
+`{ anyOf: [...] }` / `{ allOf: [...] }` 表达 OR/AND。
+
+标准 operation 覆盖图片生成/编辑、视频文生/图生/参考/编辑、音频生成、chat、语音识别和 OCR，
+同时保留开放字符串。筛选结果用 `sourceKind` 区分 `generation-model`、`llm-model`、`extension`，
+调用方随后交给对应执行 handle；SDK 不提供一个掩盖协议差异的通用 `generate()`。
+
+能力画像是运行时选择层，不是打包器。`createModelCapabilityDiscovery({ generationPacks: [...] })` 只会看
+传入的 pack；它既不会隐式导入默认 105，也不会从 bundle 删除已导入代码。真正的按需分发仍以 import
+单模型/provider/collection pack 为边界。
+
+### ASR/OCR 等开放能力
+
+ASR、OCR 不属于图片/视频/音频生成的 `ModelType`，SDK 不再要求把它们伪装成媒体生成模型。
+`@henjicc/ai-sdk/capabilities` 提供独立的开放模块协议：
+
+```ts
+import { createCapabilityClient, type CapabilityModule } from '@henjicc/ai-sdk/capabilities'
+
+const speechRecognition: CapabilityModule<{ audio: Uint8Array }, { text: string }> = {
+  descriptor: {
+    id: 'my.speech-recognition',
+    kind: 'speech-recognition',
+    source: { kind: 'external', namespace: '@example/my-asr' },
+    contract: {
+      input: [{ kind: 'audio', required: true }],
+      output: [{ kind: 'text', required: true }],
+    },
+  },
+  execute: async ({ audio }, { signal }) => runLocalAsr(audio, signal),
+}
+
+const capabilities = createCapabilityClient({ runtime })
+const asr = capabilities.register(speechRecognition)
+const result = await asr.execute({ audio: bytes }, { requestId: 'asr-1' })
+await capabilities.unregister(speechRecognition.descriptor.id)
+await capabilities.dispose()
+```
+
+`CapabilityKind` 与输入/输出 `CapabilityContentKind` 都是开放字符串；`source.namespace` 是包或插件的
+稳定所有者 ID，用于冲突诊断和批量卸载。模块执行上下文统一带
+`RuntimeContext`、`AbortSignal`、requestId、Logger 与 Tracer。client 提供注册、发现、类型化执行、取消、
+注销、`unregisterSource(namespace)` 和 dispose，并统一错误边界。跨类型筛选使用上面的
+`ModelCapabilityProfile`；执行仍走各自稳定的轮询、流式或扩展 handle，不复制协议。
+
+以下可选供应商入口只有显式 import 才进入消费方 bundle：
+
+- `capabilities/speech-recognition/bailian`：5 个百炼短音频/文件 ASR；
+- `capabilities/speech-recognition/bailian/realtime`：4 个百炼 Fun-ASR/Qwen 实时 ASR；
+- `capabilities/speech-recognition/volcengine`：SeedASR 2.0 文件 submit/query；官方标准版只接受公网 URL；
+- `capabilities/speech-recognition/volcengine/realtime`：SeedASR 2.0 gzip 二进制 WebSocket 实时识别；
+- `capabilities/speech-recognition/siliconflow`：SenseVoiceSmall 与 TeleSpeechASR multipart 文件转写；
+- `capabilities/speech-recognition/groq`：Whisper Large v3 Turbo/v3 文件转写与可选词/句时间戳；
+- `capabilities/translation/bailian`：Qwen-MT Flash/Plus/Lite；
+- `llm/groq`：Groq GPT-OSS 20B 默认配置、流式聊天和模型发现。
+- `llm/bigmodel`：智谱同一 provider family 下的中国大陆/Global 端点 profile、独立凭据槽与 GLM-5.3-Flash 能力。
+- `llm/modules`：外部包、插件与内置 LLM 共用的注册、执行、发现、取消和 namespace 卸载边界。
+
+ASR module ID 固定为 `<providerId>.speech-recognition.<modelId>`，翻译固定为
+`bailian.translation.<modelId>`；供应商 ID 使用 `bailian` / `volcengine` / `siliconflow` / `groq`，
+没有 `funasr` 兼容供应商别名。火山文件标准版不会读取本地 bytes/media-ref；宿主必须先通过自己受控的
+对象存储发布成供应商可访问 URL。SDK 不提供公共 URL 文本框或冒充上传成功的回退路径。
+
+外部 LLM 不属于 ASR/translation `CapabilityModule`。宿主从插件 manifest 构造 `LlmModule`，插件本身
+只实现宿主约定的轻量 ABI，无需导入或打包 SDK：
+
+```ts
+import { createLlmModuleClient, type LlmModule } from '@henjicc/ai-sdk/llm/modules'
+
+const pluginModule: LlmModule = {
+  descriptor: {
+    id: 'com.example.chat',
+    source: { kind: 'plugin', namespace: 'com.example.provider' },
+    providerId: 'example',
+    modelId: 'example-chat',
+    capabilities,
+    executionModes: ['request-response', 'event-stream'],
+  },
+  execute: async (request, context) => pluginAdapter.invoke(request, context),
+  discover: async (context) => pluginAdapter.discover(context),
+  dispose: async () => pluginAdapter.dispose(),
+}
+
+const llmModules = createLlmModuleClient({ runtime, modules: [pluginModule] })
+const result = await llmModules.execute(pluginModule.descriptor.id, { messages }, {
+  requestId: 'chat-1',
+  mode: 'event-stream',
+  onEvent,
+})
+await llmModules.unregisterSource('com.example.provider')
+```
+
+client 统一拥有 Usage/Finish/Done/Error 终态、Abort/timeout、结构化日志、trace、冲突诊断和资源 drain；
+module 只发送 Token/ReasoningToken 增量并返回最终结果。`createGroqLlmModule()` 把现有 Groq 共享内核
+包装成同一注册边界，插件占用 `groq/openai/gpt-oss-20b` 时会列出双方 source 并拒绝覆盖。
+
+## 已知限制与验证边界
+
+- SDK 从 `0.2.8` 起以公共 npm 为唯一正式分发渠道，可匿名安装；旧 GitHub Packages 版本仅保留作历史与回滚依据。
+- Electron 宿主已经完整构建、桌面冒烟与真实 KIE/LLM 请求验证；`0.1.2` 已在真实 macOS Tauri 2.11.0 WebView + Rust `tauri-plugin-http` 中以 loopback fixture 跑通 create/poll、multi-chunk SSE 与 AbortSignal。`0.2.0` 的 generation-only、单工具、Fal erase tool pack、ASR、翻译、Groq 与 UXP LLM streaming 入口已通过静态依赖、受限 VM 和零网络生命周期门禁；窄 LLM 入口在完全没有 `TextEncoder` / `TextDecoder` 的 VM 中覆盖 UTF-8 跨 chunk、reasoning、text、usage、stop、`[DONE]` 与取消。`0.2.7` 新增的火山文件/实时、硅基流动和 Groq ASR 四个按需入口也已纳入独立 bundle 与受限宿主门禁；百炼、火山、硅基流动、Groq 的 ASR/翻译验证均使用官方来源或明确分类的构造 fixture，没有发起真实或付费网络请求。Photoshop UXP 真机网络稳定性仍由插件集成任务验证，Grayscale/LAB/CMYK 图层字节读取也未真机复验。
+- Fal 官方存储上传已在 Electron/Node real profile 中用无隐私合成 PNG 跑通真实端到端：119 字节上传与 Range 回读 SHA-256 一致，未触发模型请求或费用。`0.1.4` 将同一 initiate + signed PUT 协议收口到 `RuntimeContext.transport`，不再依赖 `@fal-ai/client` 或构造 `File`，并补齐成功、失败与取消 fixture；真实证据仍来自迁移前已核对的同一官方协议。CDN URL 公开，生产代码未显式设置 lifecycle，保留期依赖 Fal 账户设置。
+- 四个历史 override 模型均已完成真实供应商 create/poll/result URL 验证。KIE Seedream 4.0/4.5 首轮各一次完成；Fal Seedream 4.0 首轮 create 后暴露 `0.1.2` status route 重建 405 并按首败停止，后在新的独立费用授权下，修复后 4.0 completed 才继续 4.5，两者均 completed 且无 create 重试。优先保存供应商完整 `status_url` 的修复已在私有 `0.1.3` 发布，并通过远程干净安装与标准 Vite 五入口回归。
+- KIE、APIMart、PPIO 的正式只读 probe 均已得到 HTTP 200 且分类为 connected/verified；KIE/APIMart 余额已在正式 Electron real-profile 设置页显示，对应截图已实际打开目视。首轮场景选择器失败仍保留在 6.6 交接，没有用后台日志冒充 UI 证据。
+- 8 家 provider fixture 中只有 Grsai 来自真实日志；其余按已核对测试断言与供应商文档构建。准确来源逐条记在 `tests/fixtures/README.md`，未冒充真实日志。
+- `llm-chat` 已离线验证显式关闭 reasoning 后的文本 token 路径；唯一一次 DeepSeek 真实请求只返回 reasoning，修正版未再发起付费复验。
+- 真实供应商的取消响应与错误 Key body 形状仅有注入 `Transport` 的契约测试，没有额外发起付费或故意失败的外网请求。
+
+## 相关文档
+
+- 任务定义：`docs/task/模型SDK抽离/任务/第一阶段-可行性验证与基础设施/1.2-建立SDK包骨架.md`
+- 重要决定记录：`docs/task/模型SDK抽离/重要记录.md`
+- 本包内的调研资料索引：[docs/README.md](docs/README.md)
+- 版本记录：[CHANGELOG.md](CHANGELOG.md)

package/dist/capabilities/builtin-descriptors.d.ts

@@ -0,0 +1,5 @@
+import type { CapabilityDescriptor } from './types.js';
+/** 仅用于统一发现；执行继续由 generation client 持有。 */
+export declare const GENERATION_CAPABILITY_DESCRIPTOR: CapabilityDescriptor;
+/** 仅用于统一发现；执行继续由 LLM/chat client 持有。 */
+export declare const CHAT_CAPABILITY_DESCRIPTOR: CapabilityDescriptor;