@henjicc/ai-sdk 0.2.8 → 0.3.0

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

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

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

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

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

@@ -1,81 +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 做真机验证，所以本指南不伪造具体插件调用。
+# 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 做真机验证，所以本指南不伪造具体插件调用。