@henjicc/ai-sdk 0.2.8 → 0.4.0

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

@@ -1,169 +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 网络权限、取消和图片放置仍需真机验证。
+# 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

@@ -1,83 +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，并发布宿主新版本。
+# 供应商域名白名单
+
+本清单不是凭记忆维护。在仓库根运行：
+
+```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，并发布宿主新版本。