@henjicc/ai-sdk 0.2.8

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

@@ -0,0 +1,81 @@
+# Tauri 2 接入
+
+## 已验证边界
+
+任务 1.1 在 `@tauri-apps/plugin-http@2.5.9` 上完成了真实 `cargo check`，并直接核对了已安装包源码：
+
+- `fetch()` 会尊重 `AbortSignal`，取消会调 Rust 侧 `fetch_cancel` / `fetch_cancel_body`。
+- `Response.body` 是按 chunk 读取的标准 `ReadableStream`，因此与 SDK SSE 读取器的类型契约相容。
+- capability URL glob 通过编译期校验。
+
+未做的是 Tauri WebView 里的真实 SSE 服务器端到端联调；不要把“源码级支持”写成“所有平台都已实测稳定”。
+
+## RuntimeContext
+
+```ts
+import { fetch as tauriFetch } from '@tauri-apps/plugin-http'
+import { readFile } from '@tauri-apps/plugin-fs'
+import type { CredentialScope, Logger, RuntimeContext } from '@henjicc/ai-sdk'
+
+type ReadSecret = (key: string) => Promise<string | undefined>
+
+export function createTauriRuntime(readSecret: ReadSecret, logger?: Logger): RuntimeContext {
+  return {
+    transport: { fetch: (url, init) => tauriFetch(url, init) },
+    credentials: {
+      get: (scope: CredentialScope, providerId: string) =>
+        readSecret(`${scope}:${providerId}`),
+    },
+    media: {
+      async read(ref) {
+        const bytes = await readFile(ref)
+        return {
+          bytes,
+          mimeType: inferMime(ref),
+          filename: ref.split(/[\\/]/).at(-1) || 'upload.bin',
+        }
+      },
+    },
+    logger,
+  }
+}
+
+function inferMime(ref: string): string {
+  const path = ref.toLowerCase()
+  if (path.endsWith('.png')) return 'image/png'
+  if (path.endsWith('.webp')) return 'image/webp'
+  if (path.endsWith('.mp4')) return 'video/mp4'
+  if (path.endsWith('.mp3')) return 'audio/mpeg'
+  return 'image/jpeg'
+}
+```
+
+`@tauri-apps/plugin-fs` 还需要单独配置可读路径 scope；不要给全文件系统无限制权限。
+
+## HTTP capability
+
+`src-tauri/capabilities/default.json` 的形状如下；实际 URL 完整清单见
+[供应商域名.md](供应商域名.md)：
+
+```json
+{
+  "permissions": [
+    "http:default",
+    {
+      "identifier": "http:allow-fetch",
+      "allow": [
+        { "url": "https://api.kie.ai/*" },
+        { "url": "https://*.apimart.ai/*" }
+      ]
+    }
+  ]
+}
+```
+
+1.1 已对 `{"url":"https://*.apimart.ai/*"}` 做过 `cargo check`。新增供应商域名后要更新 capability 并重新发版。
+
+## 凭据
+
+`tauri-plugin-store` 是明文 JSON，不应直接存 API key。使用 Stronghold 或系统 keyring 实现上面的
+`ReadSecret`，并在你的应用中完成写入/删除/重填流程。任务 1.1 只做了这两类方案的文档确认，
+没有对某个 Stronghold/keyring 包的读写 API 做真机验证，所以本指南不伪造具体插件调用。

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

@@ -0,0 +1,169 @@
+# Photoshop UXP 接入
+
+## 证据边界
+
+SDK 上游已完成 generation-only 与窄 LLM streaming IIFE/VM 门禁；Photoshop UXP 真机网络与图层编码
+仍由插件集成验证。
+
+- UXP 有 `fetch` / `AbortController` / Streams，但未找到官方证据证明长时间 `text/event-stream`
+  在 Photoshop UXP 中稳定；SDK 已完成 scripted SSE 与取消门禁，真实长流稳定性仍是插件真机项。
+- `requiredPermissions.network.domains` 支持 `https://*.example.com` 子域通配和 `"all"`。
+  `requiredPermissions.webview.domains` 是另一套权限，不支持同样的通配，不要混用。
+- `allowCodeGenerationFromStrings` 默认 `false`；UXP 又没有 Node/`node:vm`。SDK 因此只直接调用
+  ESM 函数，不用 `eval`/`new Function`。不需要为 SDK 开启这项高风险权限。
+- UXP 没有运行时 Node 模块解析；`@henjicc/ai-sdk` 必须在构建期 bundle。只做少量生成模型时使用
+  `@henjicc/ai-sdk/generation/core` + 完整模型 pack；需要全部 99 模型时才使用兼容的
+  `@henjicc/ai-sdk/generation`。不要导入带 LLM 的包根。
+- UXP 只做原生流式聊天时导入 `@henjicc/ai-sdk/llm/streaming`，不要导入 `llm` 总入口；后者为了
+  向后兼容还包含 modelStep、Zod 与 Vercel AI SDK。
+
+generation-only 入口公开 `createGenerationClient`，提供 `generate`、`continuePolling`、`cancel`、
+`catalog`、`providers` 与 `dispose`。发布门禁确认其 IIFE 不含 LLM/Vercel AI SDK、Node、动态代码生成、
+global fetch、Streams、File、`btoa`/`atob`，import/create/catalog/dispose 网络调用为 0，目录为 99 个模型；
+宿主不需要 alias 或 shim。
+
+窄 LLM streaming 入口只导出原生 OpenAI-compatible SSE 执行、取消、DTO、运行时类型与稳定错误协议。
+关闭 tree-shaking 的 IIFE/ESM 静态图门禁确认 Zod、modelStep、Vercel `ai`、`@ai-sdk/*`、Node builtin、
+`Buffer`、`process`、global fetch、`eval`/`new Function`、`TransformStream`、`WritableStream` 均为 0。
+`ReadableStream` 仍由宿主响应提供；Photoshop 27.5 / UXP 9.2 真机确认没有全局 `TextEncoder` 与
+`TextDecoder`，`0.1.8` 起 SSE 使用 SDK 内部增量 UTF-8 解码器，不要求插件注入 DOM 或 Node polyfill。
+
+## manifest v5 网络权限
+
+```json
+{
+  "manifestVersion": 5,
+  "requiredPermissions": {
+    "network": {
+      "domains": [
+        "https://api.kie.ai",
+        "https://kieai.redpandaai.co",
+        "https://fal.run",
+        "https://*.fal.run",
+        "https://rest.fal.ai"
+      ]
+    }
+  }
+}
+```
+
+这里只是短示例；复制 [供应商域名.md](供应商域名.md) 中你实际启用的全部请求域名。
+模型结果可能来自供应商 CDN 或用户自定义 LLM Base URL，它们不可能被静态 SDK 目录穷举；
+宿主需要在保持最小权限的前提下单独加入。
+
+## RuntimeContext
+
+```ts
+import { createModularGenerationClient } from '@henjicc/ai-sdk/generation/core'
+import { pack as kieZImage } from '@henjicc/ai-sdk/models/kie/z-image'
+import type { Logger, RuntimeContext } from '@henjicc/ai-sdk/runtime'
+
+const { secureStorage } = require('uxp').storage
+
+type ExportEncodedLayer = (ref: string) => Promise<{
+  bytes: Uint8Array
+  mimeType: 'image/png' | 'image/jpeg'
+  filename: string
+}>
+
+export function createUxpRuntime(
+  exportEncodedLayer: ExportEncodedLayer,
+  logger?: Logger,
+): RuntimeContext {
+  return {
+    transport: { fetch: (url, init) => fetch(url, init) },
+    credentials: {
+      async get(scope, providerId) {
+        const stored = await secureStorage.getItem(`${scope}:${providerId}`)
+        return stored ? decodeAsciiCredential(stored) : undefined
+      },
+    },
+    media: { read: exportEncodedLayer },
+    logger,
+  }
+}
+
+// API key 按 ASCII 保存；避免 UXP 不存在 TextDecoder 时凭据读取失败。
+function decodeAsciiCredential(bytes: Uint8Array): string {
+  let value = ''
+  for (const byte of bytes) value += String.fromCharCode(byte)
+  return value
+}
+
+export function createUxpGenerationClient(exportEncodedLayer: ExportEncodedLayer) {
+  return createModularGenerationClient({
+    runtime: createUxpRuntime(exportEncodedLayer),
+    packs: [kieZImage],
+  })
+}
+```
+
+LLM 使用同一个 `RuntimeContext`，密钥 scope 为 `llm`：
+
+```ts
+import {
+  cancelLlmChatTask,
+  runLlmChatStream,
+  type LlmChatRequestDto,
+} from '@henjicc/ai-sdk/llm/streaming'
+
+const request: LlmChatRequestDto = {
+  requestId: 'uxp-chat-1',
+  providerId: 'openai',
+  modelId: 'gpt-5-mini',
+  messages: [{ role: 'user', content: '描述当前图片' }],
+}
+
+const outcome = await runLlmChatStream(request, request.requestId!, (event) => {
+  if (event.type === 'Token') appendText(event.data)
+  if (event.type === 'ReasoningToken') appendReasoning(event.data)
+}, runtime)
+console.log(outcome.usage, outcome.finishReason)
+
+// 用户点击取消时使用同一个 taskId：
+cancelLlmChatTask(request.requestId!)
+```
+
+输入图片/视频/音频时仍通过 `LlmContentPart` 结构与 `RuntimeContext.media` 处理宿主管理引用；不要在插件
+里复制 SSE parser、错误分类或取消登记表。`Transport.fetch` 必须保留 `Response.body` 的原生字节流并尊重
+`init.signal`，不能先把整段响应转为字符串，否则会失去 token 流与及时取消。
+
+`kieZImage` 是完整执行 pack，不只是目录定义；它已包含 KIE adapter 与 KIE 范围内的媒体上传策略。
+选择别的模型时替换或追加对应 `models/<provider>/<model>` pack。不要只拿同路径的低层 `model`
+导出再由插件手拼上传逻辑。需要某供应商全部模型时改用 `provider-packs/<provider>`。
+
+Photoshop 的消除面板应只导入可选模型分发集合，不把工具塞进普通生成目录：
+
+```ts
+import { createModularGenerationClient } from '@henjicc/ai-sdk/generation/core'
+import { pack as falImageEditTools } from '@henjicc/ai-sdk/tool-packs/fal-image-edit-tools'
+
+const erase = createModularGenerationClient({ runtime, packs: [falImageEditTools] })
+const created = await erase.generate({
+  modelId: 'fal-finegrain-eraser',
+  params: {
+    image: ['uxp://active-layer'],
+    mask: ['uxp://erase-mask'],
+    mode: 'standard',
+  },
+})
+```
+
+该入口只携带 3 个 Fal 消除模型、Fal adapter 和 Fal CDN 上传；默认 105 目录、其他供应商与 LLM
+不会进入静态依赖图。单模型可改用 `tool-models/fal/<model>` 导出的 `pack`。运行时能力筛选只过滤
+已导入候选；要缩小 UXP bundle，必须从 import 边界选择 pack，不能先导入集合再靠筛选期待 tree-shake。
+
+`ref` 应是你插件自己管理的 `uxp://...` / `managed://...` 文档或图层引用，不是让用户手填 URL。
+这些引用会原样交给 `MediaReader.read()`。`photoshop.imaging.getPixels()`
+可得到 `PhotoshopImageData`，再从 `imageData.getData()` 取像素字节；这是**原始像素**，
+必须经插件的图像编码/临时文件导出流程得到真正 PNG/JPEG 字节，再从 `MediaReader.read()`
+返回；不得把 RGBA 像素误报成 `image/png`。记录中 Grayscale/LAB 的通道处理与 CMYK
+`getData()` 有历史问题，正式开放前要在真实 Photoshop 复测或明确禁用这些色彩模式。
+
+## SecureStorage 与媒体编码
+
+- SecureStorage 的 value 加密，key 名不加密；Adobe 将它定位为“更像缓存”，数据可丢失。
+  凭据丢失时 `get()` 返回 `undefined`，UI 必须让用户重新填写；不得把它当作唯一且永久的账户真相源。
+- SDK 的媒体 base64 编解码只依赖 `Uint8Array`，不要求 UXP 提供 `btoa` / `atob` polyfill。
+- Fal 本地媒体上传使用 `RuntimeContext.transport` 执行 REST initiate + signed PUT，不构造 `File`；
+  取消信号与 120 秒上传 deadline 会传到两段请求。真实 UXP 网络权限、取消和图片放置仍需真机验证。

package/docs//346/216/245/345/205/245/346/214/207/345/215/227//344/276/233/345/272/224/345/225/206/345/237/237/345/220/215.md

@@ -0,0 +1,83 @@
+# 供应商域名白名单
+
+本清单不是凭记忆维护。在仓库根运行：
+
+```bash
+node packages/ai-sdk/scripts/audit-integration-docs.cjs --check
+```
+
+脚本从 SDK provider、Transport 上传与 LLM Base URL 常量提取域名，
+再断言本文档逐项覆盖。`apiKeyUrl`/控制台/文档链接不属于 SDK 运行时请求，不放进白名单。
+
+## 供应商官网与 API Key 入口
+
+这些地址由 `PROVIDER_METADATA` / `findProviderMetadata(providerId, options)` 统一导出，宿主不再复制。
+`websiteUrl` 是实际对用户展示的跳转入口：一般供应商使用正常官网；派欧云、KIE、APIMart
+保留项目已有的邀请码。`apiKeyUrl` 只用于用户主动打开控制台，不参与 SDK 运行时请求。
+
+| providerId | 官网入口 `websiteUrl` | API Key 入口 `apiKeyUrl` |
+|---|---|---|
+| `apimart` | `https://apimart.ai/register?aff=cGPOZd`（邀请码） | `https://apimart.ai/keys` |
+| `bailian` | `https://www.aliyun.com/product/bailian` | `https://bailian.console.aliyun.com/?apiKey=1#/api-key` |
+| `bigmodel` | `https://open.bigmodel.cn/` | `https://bigmodel.cn/usercenter/proj-mgmt/apikeys` |
+| `bigmodel-global` | `https://z.ai/` | `https://z.ai/manage-apikey/apikey-list` |
+| `deepseek` | `https://www.deepseek.com/` | `https://platform.deepseek.com/api_keys` |
+| `fal` | `https://fal.ai/` | `https://fal.ai/dashboard/keys` |
+| `groq` | `https://groq.com/` | `https://console.groq.com/keys` |
+| `grsai` | `https://grsai.ai/` | `https://grsai.ai/zh/dashboard/api-keys` |
+| `kie` | `https://kie.ai?ref=eef20ef0b0595cad227d45b29c635f6c`（邀请码） | `https://kie.ai/api-key` |
+| `kimi` | `https://platform.kimi.com/` | `https://platform.kimi.com/console/api-keys` |
+| `minimax` | `https://platform.minimaxi.com/` | `https://platform.minimaxi.com/console/access?tab=api-keys` |
+| `mimo` | `https://mimo.mi.com/` | `https://platform.xiaomimimo.com/console/api-keys` |
+| `modelscope` | `https://www.modelscope.cn/` | `https://modelscope.cn/my/myaccesstoken` |
+| `ppio` | `https://ppio.com/user/register?invited_by=WGY0DZ`（邀请码） | `https://ppio.com/settings/key-management` |
+| `siliconflow` | `https://siliconflow.cn/` | `https://cloud.siliconflow.cn/account/ak` |
+| `volcengine` | `https://www.volcengine.com/product/ark` | `https://console.volcengine.com/ark/region:cn-beijing/apiKey` |
+
+BigModel 国内/国际共用 provider family；调用
+`findProviderMetadata('bigmodel', { endpointProfile: 'global' })` 会返回 `bigmodel-global` 的 Z.AI 地址。
+纯自定义供应商没有官方目录依据时返回 `null`，消费软件不应要求用户填写或自行猜测管理地址。
+
+## 生成、上传与连通性
+
+| 供应商/用途 | 必需域名 |
+|---|---|
+| APIMart 生成、图片上传、故障切换 | `api.apimart.ai`、`api.apib.ai`、`api.aiuxu.com`、`api.aishuch.com` |
+| Grsai 生成、查询、故障切换 | `grsaiapi.com`、`grsai.dakka.com.cn` |
+| KIE 生成/轮询/余额 | `api.kie.ai` |
+| KIE 公网文件上传 | `kieai.redpandaai.co` |
+| Fal 同步/队列 | `fal.run`、`queue.fal.run`、`*.fal.run` |
+| Fal CDN REST 存储上传 | `rest.fal.ai` |
+| 派欧云生成与 LLM | `api.ppio.com` |
+| 魔搭 | `api-inference.modelscope.cn` |
+| 百炼图像/ASR/翻译 | `dashscope.aliyuncs.com`、`*.cn-beijing.maas.aliyuncs.com` |
+| 火山引擎图像/LLM | `ark.cn-beijing.volces.com` |
+| 火山引擎 SeedASR 2.0 | `openspeech.bytedance.com` |
+| 硅基流动 ASR | `api.siliconflow.cn` |
+| Groq LLM/ASR | `api.groq.com` |
+
+## LLM 内置/默认地址
+
+| 供应商 | 必需域名 |
+|---|---|
+| DeepSeek | `api.deepseek.com` |
+| Kimi | `api.moonshot.cn` |
+| 智谱 GLM | `open.bigmodel.cn` |
+| 小米 MiMo | `api.xiaomimimo.com` |
+| MiniMax | `api.minimaxi.com` |
+| 百炼 Qwen 工作空间地址 | `*.cn-beijing.maas.aliyuncs.com` |
+| OpenAI-compatible 默认回落 | `api.openai.com` |
+
+## 权限格式
+
+UXP manifest 使用 scheme + host，例如 `https://api.kie.ai` 和 `https://*.fal.run`。
+Tauri `http:allow-fetch` 在后面加路径 glob，例如 `https://api.kie.ai/*` 和
+`https://*.fal.run/*`。
+
+本表只穷举 **SDK 主动请求**。下列域名必须由宿主按实际输入/结果动态管理，不能假装可以在此静态穷举：
+
+- 用户自建 LLM provider 的 `baseUrl`。
+- 供应商返回的 CDN/结果 URL。
+- 用户传入的既有远程媒体 URL。
+
+新增供应商或域名时，同时更新源码常量、本文档、UXP manifest/Tauri capability，并发布宿主新版本。

package/docs//346/216/245/345/205/245/346/214/207/345/215/227//351/224/231/350/257/257/345/244/204/347/220/206.md

@@ -0,0 +1,72 @@
+# 错误处理
+
+SDK 有两层错误契约：生成/上传的 `AiRuntimeError.code`，以及 LLM 的
+`ProviderModelStepError.details` 分类。宿主显示用户可读提示，把原始细节放进经脱敏的调试日志；
+不要把 API key、Authorization header 或完整供应商 body 原样显示。
+
+在仓库根运行下列命令，会从 `packages/ai-sdk/src` 的真实 schema/callsites 穷举并检查本页：
+
+```bash
+node packages/ai-sdk/scripts/audit-integration-docs.cjs --check
+```
+
+## AiRuntimeError
+
+| code | 宿主提示/处理 |
+|---|---|
+| `api_key_missing` | 该生成供应商未配置密钥；打开凭据设置。 |
+| `missing_api_key` | 媒体上传依赖的供应商密钥缺失；补配后重新提交。 |
+| `cancelled` | 任务已取消；不作失败 toast，停止轮询。 |
+| `client_disposed` | client 已释放；修正宿主生命周期，不要自动重试。 |
+| `empty_result` | 供应商已响应但没有可用结果 URL；保留 taskId 与脱敏响应供排查。 |
+| `invalid_audio` | 实时识别没有收到可提交的音频；检查录音与分块生命周期。 |
+| `invalid_audio_chunk` | 音频块为空或不满足 PCM 字节对齐；宿主修正分块后再发送。 |
+| `invalid_data_uri` | 媒体 data URI 格式无效；让用户重新选择/导出文件。 |
+| `invalid_base64` | 媒体 base64 数据无效；让宿主重新编码文件。 |
+| `invalid_json` | 供应商返回非 JSON；不重放付费创建请求，保留 taskId 查询。 |
+| `invalid_media` | 文件识别收到空媒体；让用户重新选择或重新读取文件。 |
+| `invalid_parameter` | ASR 通用或供应商参数类型/范围无效；修正调用参数，不自动重试。 |
+| `invalid_provider_id` | 自定义 provider ID 为空；在注册前校验。 |
+| `invalid_response` | 响应缺少必需字段；提示协议不兼容并记录脱敏响应。 |
+| `invalid_route` | catalog 给出空路由；属于开发/版本错误。 |
+| `invalid_selector_result` | endpoint selector 没有返回字符串；属于开发/版本错误。 |
+| `provider_already_registered` | provider ID 已被另一 client 占用；使用唯一 ID 或先 `dispose()`。 |
+| `provider_http_error` | 供应商 HTTP 失败；按 status 引导检查参数/鉴权/服务。 |
+| `provider_network_error` | DNS/连接等网络失败；允许用户主动重试，不自动重放可能计费的 POST。 |
+| `provider_not_found` | 模型无法映射 provider；检查模型 ID/版本。 |
+| `provider_task_failed` | 供应商明确宣告任务失败；显示经脱敏原因，不继续轮询。 |
+| `provider_task_unreachable` | 状态查询连续 20 次失败；保留 taskId，让用户稍后手动续查。 |
+| `public_media_url_required` | 目标字段必须是公网 URL，但当前供应商没有可用官方上传路径。 |
+| `unknown_provider` | 调用了未注册 provider；核对 ID 或注册流程。 |
+| `unsupported_media_source` | 后端不能解析 `blob:` 等媒体引用；宿主先导出成受管字节。 |
+| `unsupported_media_type` | 上传端点不支持当前 MIME；转成文档允许的格式。 |
+| `unsupported_audio_format` | ASR 音频编码不受当前协议支持；按模型要求转换格式。 |
+| `unsupported_parameter` | 当前 P0 协议未实现该可选参数；宿主移除参数或选择其他模型。 |
+| `unsupported_provider` | 对同步 provider 调用了续轮询等不支持的生命周期。 |
+| `upload_failed` | 供应商官方上传失败/未返回 URL；引导重新选择或检查密钥。 |
+| `upload_timeout` | Fal 两段上传超过 120 秒；确认网络后由用户重新提交。 |
+| `upload_too_large` | 文件超过上传上限；显示精确限制并让用户压缩/换文件。 |
+
+## LLM 结构化错误
+
+`ProviderModelStepError.details` 固定字段为 `code/category/status/retryable/retryAfterMs/providerId/modelId/requestId/message`。
+供应商的 code 可动态透传；SDK 自己产生的固定 code 是 `API_KEY_MISSING`、`MODEL_REQUEST_TIMEOUT`、
+`MODEL_STEP_CANCELLED`、`PROVIDER_ERROR`。字符串协议 marker 为 `api_key_missing`、`model_step_failed`、
+`provider_error`、`task_cancelled`。
+
+| category | 建议提示 | SDK 默认 retryable |
+|---|---|---|
+| `authentication` | 鉴权失败，重新配置密钥 | 否 |
+| `billing` | 计费状态异常，检查账单/充值 | 否 |
+| `quota` | 供应商额度不足 | 否 |
+| `rate_limit` | 请求频率受限，按 `retryAfterMs` 等待 | 是 |
+| `server` | 供应商服务暂时不可用 | 是 |
+| `network` | 网络请求失败 | 是 |
+| `invalid_request` | 供应商拒绝了参数，显示脱敏 detail | 否 |
+| `context_overflow` | 上下文超限，缩短历史/附件 | 否 |
+| `content_filter` | 内容策略拒绝，调整输入 | 否 |
+| `cancelled` | 用户取消，不当成系统失败 | 否 |
+| `unknown` | 供应商请求失败，保留 requestId 供排查 | 否 |
+
+`retryable: true` 不等于宿主可以无脑重放一次完整付费请求。生成创建 POST 只在能证明尚未建连时有
+“安全预连接”重试；轮询 GET 和 LLM 模型步又有各自独立生命周期。

package/examples/form-renderer/README.md

@@ -0,0 +1,17 @@
+# form-renderer
+
+无框架、无 DOM 依赖的 `@henjicc/ai-sdk@0.2.8` 参数表单契约示例。它从 `client.catalog` 读取真实模型，使用
+`evaluateRuntimeCondition()` 处理显隐/禁用，使用 `getRuntimeMediaInputContract()` 生成媒体上传入口。
+示例只使用 `generation`、`catalog` 与 `runtime` 按需入口，保留完整 generation catalog，
+但不会带入 LLM/BigModel。
+
+```bash
+npm install
+npm start
+```
+
+入口会真实渲染 5 个差异模型，覆盖普通下拉与数值、条件显隐、动态 input limits、通用与特殊媒体、
+`composite` 宿主钩子。输出是最小 HTML 骨架，不包含痕迹AI 的名称、i18n、面板布局或专属组件。
+
+媒体控件只负责让宿主选择本地/受管资源，不能降级为 URL 文本框；实际上传仍由 SDK 在请求边界调用
+当前供应商的官方上传能力。`composite` 只输出 `data-control="custom"`，宿主按参数 ID 注入自己的组件。

package/examples/form-renderer/cli.ts

@@ -0,0 +1,32 @@
+import { createGenerationClient } from '@henjicc/ai-sdk/generation'
+import type { RuntimeContext } from '@henjicc/ai-sdk/runtime'
+
+import { renderMinimalModelForm } from './index.js'
+
+const runtime: RuntimeContext = {
+  transport: { fetch: async () => { throw new Error('form-renderer does not access the network') } },
+  credentials: { get: () => undefined },
+  media: { read: async () => { throw new Error('form-renderer does not read media') } },
+}
+
+const modelIds = [
+  'volcengine-seedream-5.0-lite',
+  'apimart-gemini-omni-flash',
+  'ppio-wan-2.7',
+  'apimart-midjourney',
+  'ppio-minimax-speech',
+] as const
+
+const client = createGenerationClient({ runtime })
+try {
+  const forms = modelIds.map((modelId) => renderMinimalModelForm(client, modelId))
+  console.log(JSON.stringify(forms.map((form) => ({
+    modelId: form.modelId,
+    controlCount: form.controls.length,
+    mediaKinds: [...new Set(form.controls.map((control) => control.mediaKind).filter(Boolean))],
+    customControlIds: form.customControlIds,
+    html: form.html,
+  })), null, 2))
+} finally {
+  client.dispose()
+}

package/examples/form-renderer/index.ts

@@ -0,0 +1,144 @@
+import {
+  evaluateRuntimeCondition,
+  flattenRuntimeParams,
+  getRuntimeMediaInputContract,
+} from '@henjicc/ai-sdk/catalog'
+import type { GenerationClient } from '@henjicc/ai-sdk/generation'
+
+type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject
+type JsonObject = { [key: string]: JsonValue }
+type RuntimeParamDef = ReturnType<GenerationClient['catalog']['getParams']>[number]
+
+export type MinimalControlKind =
+  | 'text'
+  | 'textarea'
+  | 'number'
+  | 'select'
+  | 'switch'
+  | 'upload'
+  | 'custom'
+
+export interface MinimalRenderedControl {
+  id: string
+  kind: MinimalControlKind
+  value: JsonValue | undefined
+  disabled: boolean
+  source: 'param' | 'input-limits'
+  mediaKind?: 'image' | 'video' | 'audio' | 'file'
+}
+
+export interface MinimalRenderedForm {
+  modelId: string
+  controls: MinimalRenderedControl[]
+  customControlIds: string[]
+  html: string
+}
+
+/**
+ * 无框架、无 DOM 依赖的最小 renderer，只用于证明 SDK 参数契约足以驱动消费方表单。
+ * composite 只输出 data-control="custom" 钩子；痕迹AI 专属 panel/config 属于 presentation，
+ * 宿主必须按 param id 注入自定义组件。
+ */
+export function renderMinimalModelForm(
+  client: GenerationClient,
+  modelId: string,
+  values: JsonObject = {}
+): MinimalRenderedForm {
+  const model = client.catalog.get(modelId)
+  if (!model) throw new Error(`Unknown model: ${modelId}`)
+  const runtimeValues: JsonObject = {
+    ...client.catalog.getDefaultValues(modelId),
+    uploadedFilePaths: [],
+    uploadedVideoFilePaths: [],
+    uploadedAudioFilePaths: [],
+    images: [],
+    videos: [],
+    audios: [],
+    uploadedImages: [],
+    uploadedVideos: [],
+    uploadedAudios: [],
+    ...values,
+  }
+  const controls: MinimalRenderedControl[] = []
+
+  for (const param of flattenRuntimeParams(client.catalog.getParams(modelId))) {
+    if (!evaluateRuntimeCondition(param.visible?.condition, runtimeValues)) continue
+    controls.push({
+      id: param.id,
+      kind: controlKindForParam(param),
+      value: runtimeValues[param.id],
+      disabled: param.disabled !== undefined &&
+        evaluateRuntimeCondition(param.disabled.condition, runtimeValues),
+      source: 'param',
+      ...mediaKindForParam(param),
+    })
+  }
+
+  const media = getRuntimeMediaInputContract(model, runtimeValues)
+  for (const input of media.genericInputs) {
+    controls.push({
+      id: input.id,
+      kind: 'upload',
+      value: runtimeValues[input.id],
+      disabled: false,
+      source: 'input-limits',
+      mediaKind: input.kind,
+    })
+  }
+
+  controls.sort((left, right) => {
+    const leftParam = model.params.find((param) => param.id === left.id)
+    const rightParam = model.params.find((param) => param.id === right.id)
+    return (leftParam?.order ?? Number.MAX_SAFE_INTEGER) -
+      (rightParam?.order ?? Number.MAX_SAFE_INTEGER)
+  })
+
+  return {
+    modelId: model.meta.id,
+    controls,
+    customControlIds: controls.filter((control) => control.kind === 'custom').map((control) => control.id),
+    html: `<form data-model-id="${escapeHtml(model.meta.id)}">${controls.map(renderControlHtml).join('')}</form>`,
+  }
+}
+
+function controlKindForParam(param: RuntimeParamDef): MinimalControlKind {
+  switch (param.type) {
+    case 'text': return 'text'
+    case 'textarea': return 'textarea'
+    case 'number': return 'number'
+    case 'dropdown':
+    case 'radio':
+    case 'resolution':
+    case 'aspect-ratio': return 'select'
+    case 'switch': return 'switch'
+    case 'image-upload':
+    case 'video-upload':
+    case 'file-upload': return 'upload'
+    case 'composite': return 'custom'
+    case 'panel': return 'custom'
+  }
+}
+
+function mediaKindForParam(
+  param: RuntimeParamDef
+): Pick<MinimalRenderedControl, 'mediaKind'> | Record<string, never> {
+  if (param.type === 'image-upload') return { mediaKind: 'image' }
+  if (param.type === 'video-upload') return { mediaKind: 'video' }
+  if (param.type === 'file-upload') return { mediaKind: 'file' }
+  return {}
+}
+
+function renderControlHtml(control: MinimalRenderedControl): string {
+  const id = escapeHtml(control.id)
+  const media = control.mediaKind ? ` data-media-kind="${control.mediaKind}"` : ''
+  const disabled = control.disabled ? ' aria-disabled="true"' : ''
+  return `<div data-param-id="${id}" data-control="${control.kind}" data-source="${control.source}"${media}${disabled}></div>`
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+}

package/examples/form-renderer/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@henjicc/ai-sdk-example-form-renderer",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "npm run build && node dist/cli.js"
+  },
+  "dependencies": {
+    "@henjicc/ai-sdk": "0.2.8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.2"
+  }
+}

package/examples/form-renderer/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "types": ["node"]
+  },
+  "include": ["index.ts", "cli.ts"]
+}

package/examples/llm-chat/README.md

@@ -0,0 +1,32 @@
+# llm-chat
+
+用 `@henjicc/ai-sdk@0.2.8` 的 `llm/streaming` 按需入口走 OpenAI-compatible SSE 流式对话，
+不会把 generation、BigModel preset/models/pricing、Groq 或 LLM modules 打进示例 bundle；
+通用端点身份解析所需的 BigModel profiles 仍会保留。默认目标是
+DeepSeek `deepseek-v4-flash`，提示词要求只回复 `SDK OK`，并限制最多 16 tokens。示例显式传入
+`reasoning: { enabled: false, effort: 'high' }`，避免短输出预算被供应商默认思考过程占用；若流结束后
+没有任何文本 token，示例会明确失败。
+
+```bash
+npm install
+npm run dry-run
+npm run check:bundle
+```
+
+`dry-run` 使用本地 SSE fixture，不访问网络。真实调用前先确认供应商、模型、Base URL 和价格：
+
+```bash
+LLM_API_KEY='你的密钥' \
+LLM_PROVIDER_ID='deepseek' \
+LLM_MODEL_ID='deepseek-v4-flash' \
+LLM_BASE_URL='https://api.deepseek.com' \
+npm start
+```
+
+DeepSeek Flash 当前资料价为缓存未命中输入 ¥1.5/百万 tokens（闲时）或 ¥3/百万（高峰），输出
+¥4.5/百万（闲时）或 ¥9/百万（高峰）。示例按高峰价、并把字符数保守当 token 数输出粗估；实际账单
+以供应商 usage 和账单为准。
+
+示例对 `/chat/completions` 的 POST 设置单次外网闸门，进程内第二次付费请求会在本地被拒绝。
+要取消流式请求，保存 `resolveLlmTaskId(request)` 返回的 `taskId`，再调用
+`cancelLlmChatTask(taskId)`。按需流式入口没有需要宿主释放的客户端实例。