@henjicc/ai-sdk 0.2.8

package/dist/upload/base64.js

@@ -0,0 +1,49 @@
+import { AiRuntimeError } from '../runtime/AiRuntimeError.js';
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** 把字节数组编码成 base64 字符串，不依赖 Node Buffer 或浏览器 btoa。 */
+export function toBase64(bytes) {
+    let encoded = '';
+    for (let offset = 0; offset < bytes.length; offset += 3) {
+        const first = bytes[offset];
+        const second = bytes[offset + 1];
+        const third = bytes[offset + 2];
+        encoded += BASE64_ALPHABET[first >> 2];
+        encoded += BASE64_ALPHABET[((first & 0x03) << 4) | ((second ?? 0) >> 4)];
+        encoded += second === undefined
+            ? '='
+            : BASE64_ALPHABET[((second & 0x0f) << 2) | ((third ?? 0) >> 6)];
+        encoded += third === undefined ? '=' : BASE64_ALPHABET[third & 0x3f];
+    }
+    return encoded;
+}
+/** `toBase64` 的逆运算，同样不依赖 Buffer 或浏览器 atob。 */
+export function fromBase64(base64) {
+    const normalized = base64.replace(/\s+/g, '');
+    if (normalized.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(normalized)) {
+        throw new AiRuntimeError('invalid_base64', 'Invalid base64 payload');
+    }
+    const padding = normalized.endsWith('==') ? 2 : normalized.endsWith('=') ? 1 : 0;
+    const bytes = new Uint8Array((normalized.length / 4) * 3 - padding);
+    let output = 0;
+    for (let offset = 0; offset < normalized.length; offset += 4) {
+        const a = decodeBase64Char(normalized[offset]);
+        const b = decodeBase64Char(normalized[offset + 1]);
+        const c = normalized[offset + 2] === '=' ? 0 : decodeBase64Char(normalized[offset + 2]);
+        const d = normalized[offset + 3] === '=' ? 0 : decodeBase64Char(normalized[offset + 3]);
+        bytes[output++] = (a << 2) | (b >> 4);
+        if (output < bytes.length)
+            bytes[output++] = ((b & 0x0f) << 4) | (c >> 2);
+        if (output < bytes.length)
+            bytes[output++] = ((c & 0x03) << 6) | d;
+    }
+    return bytes;
+}
+function decodeBase64Char(value) {
+    const index = BASE64_ALPHABET.indexOf(value);
+    if (index < 0)
+        throw new AiRuntimeError('invalid_base64', 'Invalid base64 payload');
+    return index;
+}
+export function toDataUri(bytes, mimeType) {
+    return `data:${mimeType};base64,${toBase64(bytes)}`;
+}

package/dist/upload/fal-legacy.d.ts

@@ -0,0 +1,7 @@
+import type { Transport } from '../runtime/Transport.js';
+import type { PreparedMediaBinary } from './prepared-media.js';
+/**
+ * @deprecated 新代码请传入宿主 Transport；生成客户端内部始终使用
+ * `uploadToFalWithTransport`。省略 transport 只为兼容 0.1.3 的两参数调用。
+ */
+export declare function uploadToFal(apiKey: string, prepared: PreparedMediaBinary, transport?: Transport): Promise<string>;

package/dist/upload/fal-legacy.js

@@ -0,0 +1,19 @@
+import { uploadToFalWithTransport } from './fal-transport.js';
+/**
+ * @deprecated 新代码请传入宿主 Transport；生成客户端内部始终使用
+ * `uploadToFalWithTransport`。省略 transport 只为兼容 0.1.3 的两参数调用。
+ */
+export async function uploadToFal(apiKey, prepared, transport) {
+    return await uploadToFalWithTransport(apiKey, prepared, transport ?? createLegacyHostTransport());
+}
+function createLegacyHostTransport() {
+    return {
+        async fetch(url, init) {
+            const hostFetch = globalThis.fetch;
+            if (typeof hostFetch !== 'function') {
+                throw new Error('Fal legacy upload requires a host fetch implementation; pass Transport explicitly.');
+            }
+            return await hostFetch(url, init);
+        },
+    };
+}

package/dist/upload/fal-transport.d.ts

@@ -0,0 +1,7 @@
+import type { Transport } from '../runtime/Transport.js';
+import type { PreparedMediaBinary } from './prepared-media.js';
+/**
+ * Fal CDN 单文件 REST 上传。协议与官方客户端的 initiate + signed PUT 路径一致，但全部网络
+ * 都经宿主 Transport，且直接传递编码后的字节，不依赖 File/Blob 或全局 fetch。
+ */
+export declare function uploadToFalWithTransport(apiKey: string, prepared: PreparedMediaBinary, transport: Transport, signal?: AbortSignal): Promise<string>;

package/dist/upload/fal-transport.js

@@ -0,0 +1,104 @@
+import { AiRuntimeError } from '../runtime/AiRuntimeError.js';
+const FAL_UPLOAD_INITIATE_URL = 'https://rest.fal.ai/storage/upload/initiate?storage_type=fal-cdn-v3';
+const FAL_UPLOAD_TIMEOUT_MS = 120_000;
+/**
+ * Fal CDN 单文件 REST 上传。协议与官方客户端的 initiate + signed PUT 路径一致，但全部网络
+ * 都经宿主 Transport，且直接传递编码后的字节，不依赖 File/Blob 或全局 fetch。
+ */
+export async function uploadToFalWithTransport(apiKey, prepared, transport, signal) {
+    const deadline = createDeadlineSignal(signal, FAL_UPLOAD_TIMEOUT_MS);
+    try {
+        const initiateResponse = await transport.fetch(FAL_UPLOAD_INITIATE_URL, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json',
+                Authorization: `Key ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                content_type: prepared.mimeType,
+                file_name: prepared.filename,
+            }),
+            signal: deadline.signal,
+        });
+        const initiation = await readInitiation(initiateResponse);
+        assertHttpsUrl(initiation.uploadUrl, 'upload_url');
+        assertHttpsUrl(initiation.fileUrl, 'file_url');
+        const uploadResponse = await transport.fetch(initiation.uploadUrl, {
+            method: 'PUT',
+            headers: { 'Content-Type': prepared.mimeType },
+            body: prepared.bytes.slice().buffer,
+            signal: deadline.signal,
+        });
+        if (!uploadResponse.ok) {
+            throw new AiRuntimeError('upload_failed', `Fal signed upload HTTP ${uploadResponse.status}`);
+        }
+        return initiation.fileUrl;
+    }
+    catch (error) {
+        if (signal?.aborted) {
+            throw new AiRuntimeError('cancelled', 'Fal upload cancelled');
+        }
+        if (deadline.didTimeout()) {
+            throw new AiRuntimeError('upload_timeout', `Fal upload exceeded ${FAL_UPLOAD_TIMEOUT_MS}ms`);
+        }
+        throw error;
+    }
+    finally {
+        deadline.dispose();
+    }
+}
+async function readInitiation(response) {
+    const payload = await response.json().catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new AiRuntimeError('upload_failed', `Fal upload initiation returned invalid JSON: ${message}`);
+    });
+    if (!response.ok) {
+        throw new AiRuntimeError('upload_failed', `Fal upload initiation HTTP ${response.status}: ${JSON.stringify(payload)}`);
+    }
+    if (!isJsonObject(payload)) {
+        throw new AiRuntimeError('upload_failed', 'Fal upload initiation returned a non-object response');
+    }
+    const uploadUrl = typeof payload.upload_url === 'string' ? payload.upload_url : '';
+    const fileUrl = typeof payload.file_url === 'string' ? payload.file_url : '';
+    if (!uploadUrl || !fileUrl) {
+        throw new AiRuntimeError('upload_failed', 'Fal upload initiation response is missing upload_url or file_url');
+    }
+    return { uploadUrl, fileUrl };
+}
+function assertHttpsUrl(value, field) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new AiRuntimeError('upload_failed', `Fal upload initiation returned an invalid ${field}`);
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new AiRuntimeError('upload_failed', `Fal upload initiation returned a non-HTTPS ${field}`);
+    }
+}
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function createDeadlineSignal(parent, timeoutMs) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const abort = () => controller.abort();
+    if (parent?.aborted)
+        abort();
+    else
+        parent?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    return {
+        signal: controller.signal,
+        didTimeout: () => timedOut,
+        dispose: () => {
+            clearTimeout(timer);
+            parent?.removeEventListener('abort', abort);
+        },
+    };
+}

package/dist/upload/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 媒体文件上传相关工具（供应商官方上传服务封装）：字段识别、上传策略、上传实现、
+ * `data:` URI 解析、MIME 推断（任务 2.4 迁入）。
+ */
+export { buildMediaSourceIndex, classifyMediaKey, inheritMediaKind, isLocalMediaSource, isRemoteHttpUrl, normalizeLocalSource, resolveMediaKind, type MediaKind, type MediaSourceIndex, type ResolvedMediaKind, } from './media-fields.js';
+export { defaultFilename, inferMimeFromPath, parseDataUri, type ParsedDataUri } from './media-binary.js';
+export { preprocessRequestBody } from './preprocess.js';
+export { fromBase64, toBase64, toDataUri, uploadToApiMart, uploadToKie, type PreparedMediaBinary, } from './providers.js';
+export { uploadToFal } from './fal-legacy.js';
+export { uploadToFalWithTransport } from './fal-transport.js';

package/dist/upload/index.js

@@ -0,0 +1,15 @@
+/**
+ * 媒体文件上传相关工具（供应商官方上传服务封装）：字段识别、上传策略、上传实现、
+ * `data:` URI 解析、MIME 推断（任务 2.4 迁入）。
+ */
+export { buildMediaSourceIndex, classifyMediaKey, inheritMediaKind, isLocalMediaSource, isRemoteHttpUrl, normalizeLocalSource, resolveMediaKind, } from './media-fields.js';
+// 任务 2.4 迁入：`data:` URI 解析 / MIME 推断 / 缺省文件名，宿主的 `MediaReader`
+// 实现（如 Electron 侧 sdk-runtime.ts）复用这里的实现，不再各自维护一份重复拷贝。
+export { defaultFilename, inferMimeFromPath, parseDataUri } from './media-binary.js';
+// 任务 2.4 迁入：媒体上传主入口（识别请求体里的媒体字段、按供应商上传策略上传、回填 URL）。
+export { preprocessRequestBody } from './preprocess.js';
+// 任务 2.4 迁入：供应商官方上传服务封装（Fal/APIMart/KIE），以及不依赖 `Buffer` 的
+// base64 编解码（UXP/浏览器没有 Node 的 `Buffer`）。
+export { fromBase64, toBase64, toDataUri, uploadToApiMart, uploadToKie, } from './providers.js';
+export { uploadToFal } from './fal-legacy.js';
+export { uploadToFalWithTransport } from './fal-transport.js';

package/dist/upload/kie-upload.d.ts

@@ -0,0 +1,3 @@
+import type { Transport } from '../runtime/Transport.js';
+import type { PreparedMediaBinary } from './prepared-media.js';
+export declare function uploadToKie(apiKey: string, prepared: PreparedMediaBinary, transport: Transport): Promise<string>;

package/dist/upload/kie-upload.js

@@ -0,0 +1,41 @@
+import { fetchProvider } from '../providers/provider-fetch.js';
+import { readUploadJson, readUploadString } from './upload-response.js';
+import { AiRuntimeError } from '../runtime/AiRuntimeError.js';
+const KIE_UPLOAD_URL = 'https://kieai.redpandaai.co/api/file-stream-upload';
+export async function uploadToKie(apiKey, prepared, transport) {
+    const form = new FormData();
+    form.append('uploadPath', 'henji-uploads');
+    form.append('file', new Blob([prepared.bytes], {
+        type: inferUploadMime(prepared.filename),
+    }), prepared.filename);
+    const response = await fetchProvider('KIE upload', KIE_UPLOAD_URL, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${apiKey}` },
+        body: form,
+    }, { transport, retryPreconnectOnce: true });
+    const payload = await readUploadJson(response, 'KIE upload');
+    const fileUrl = readUploadString(payload, '/data/fileUrl')
+        ?? readUploadString(payload, '/data/downloadUrl');
+    if (!fileUrl) {
+        throw new AiRuntimeError('upload_failed', `KIE upload missing file URL: ${JSON.stringify(payload)}`);
+    }
+    return fileUrl;
+}
+function inferUploadMime(filename) {
+    const lower = filename.toLowerCase();
+    if (lower.endsWith('.png'))
+        return 'image/png';
+    if (lower.endsWith('.jpg') || lower.endsWith('.jpeg'))
+        return 'image/jpeg';
+    if (lower.endsWith('.webp'))
+        return 'image/webp';
+    if (lower.endsWith('.gif'))
+        return 'image/gif';
+    if (lower.endsWith('.mp4'))
+        return 'video/mp4';
+    if (lower.endsWith('.webm'))
+        return 'video/webm';
+    if (lower.endsWith('.mov'))
+        return 'video/quicktime';
+    return 'application/octet-stream';
+}

package/dist/upload/media-binary.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 媒体二进制的解析/推断工具：`data:` URI 解码、按扩展名推断 MIME、缺省文件名。
+ *
+ * 三者都是纯函数、不触碰文件系统，因此既被 SDK 内部的 `preprocess.ts`（处理请求体里的
+ * `data:` URI 分支）使用，也导出给宿主的 `MediaReader` 实现复用——Electron 侧
+ * `electron/main/services/ai-runtime/sdk-runtime.ts` 此前维护了一份几乎一样的临时拷贝
+ * （2.1 产出时的注释就说明了这一点），本任务（2.4）统一到这一份，删除宿主侧的重复实现。
+ */
+import type { MediaKind } from './media-fields.js';
+export interface ParsedDataUri {
+    bytes: Uint8Array;
+    mimeType: string;
+}
+/** 解析 `data:` URI；不是 `data:` URI 时返回 `undefined`，格式非法时 throw。 */
+export declare function parseDataUri(input: string): ParsedDataUri | undefined;
+/**
+ * 按扩展名推断 MIME 类型，纯字符串处理、不依赖 Node path 模块（UXP 没有 Node 模块解析器）。
+ * 先去掉查询串/片段（形如 `...jpg?x-oss-token=...`），再取最后一个路径分隔符之后、
+ * 最后一个 `.` 之后的部分；取不到扩展名（或形如 `.gitignore` 的纯隐藏文件名）时按
+ * `mediaKind` 退化成一个合理的默认值。
+ */
+export declare function inferMimeFromPath(filePath: string, mediaKind?: MediaKind): string;
+export declare function defaultFilename(mimeType: string, mediaKind?: MediaKind): string;

package/dist/upload/media-binary.js

@@ -0,0 +1,80 @@
+/**
+ * 媒体二进制的解析/推断工具：`data:` URI 解码、按扩展名推断 MIME、缺省文件名。
+ *
+ * 三者都是纯函数、不触碰文件系统，因此既被 SDK 内部的 `preprocess.ts`（处理请求体里的
+ * `data:` URI 分支）使用，也导出给宿主的 `MediaReader` 实现复用——Electron 侧
+ * `electron/main/services/ai-runtime/sdk-runtime.ts` 此前维护了一份几乎一样的临时拷贝
+ * （2.1 产出时的注释就说明了这一点），本任务（2.4）统一到这一份，删除宿主侧的重复实现。
+ */
+import { AiRuntimeError } from '../runtime/AiRuntimeError.js';
+import { fromBase64 } from './base64.js';
+/** 解析 `data:` URI；不是 `data:` URI 时返回 `undefined`，格式非法时 throw。 */
+export function parseDataUri(input) {
+    if (!input.startsWith('data:'))
+        return undefined;
+    const commaIndex = input.indexOf(',');
+    if (commaIndex < 0)
+        throw new AiRuntimeError('invalid_data_uri', 'Invalid data URI format');
+    const header = input.slice(0, commaIndex);
+    const payload = input.slice(commaIndex + 1);
+    const mimeType = header.slice(5).split(';')[0] || 'application/octet-stream';
+    const bytes = header.includes(';base64')
+        ? fromBase64(payload)
+        : new TextEncoder().encode(decodeURIComponent(payload));
+    return { bytes, mimeType };
+}
+/**
+ * 按扩展名推断 MIME 类型，纯字符串处理、不依赖 Node path 模块（UXP 没有 Node 模块解析器）。
+ * 先去掉查询串/片段（形如 `...jpg?x-oss-token=...`），再取最后一个路径分隔符之后、
+ * 最后一个 `.` 之后的部分；取不到扩展名（或形如 `.gitignore` 的纯隐藏文件名）时按
+ * `mediaKind` 退化成一个合理的默认值。
+ */
+export function inferMimeFromPath(filePath, mediaKind = 'unknown') {
+    const ext = extractExtension(filePath);
+    switch (ext) {
+        case 'png': return 'image/png';
+        case 'jpg':
+        case 'jpeg': return 'image/jpeg';
+        case 'webp': return 'image/webp';
+        case 'gif': return 'image/gif';
+        case 'bmp': return 'image/bmp';
+        case 'mp4': return 'video/mp4';
+        case 'webm': return 'video/webm';
+        case 'mov': return 'video/quicktime';
+        case 'mp3': return 'audio/mpeg';
+        case 'm4a': return 'audio/mp4';
+        case 'wav': return 'audio/wav';
+        case 'flac': return 'audio/flac';
+        case 'ogg': return 'audio/ogg';
+        default:
+            if (mediaKind === 'image')
+                return 'image/jpeg';
+            if (mediaKind === 'video')
+                return 'video/mp4';
+            if (mediaKind === 'audio')
+                return 'audio/mpeg';
+            return 'application/octet-stream';
+    }
+}
+function extractExtension(filePath) {
+    const withoutQuery = filePath.split(/[?#]/)[0] ?? filePath;
+    const lastSlash = Math.max(withoutQuery.lastIndexOf('/'), withoutQuery.lastIndexOf('\\'));
+    const basename = lastSlash >= 0 ? withoutQuery.slice(lastSlash + 1) : withoutQuery;
+    const dotIndex = basename.lastIndexOf('.');
+    if (dotIndex <= 0)
+        return '';
+    return basename.slice(dotIndex + 1).toLowerCase();
+}
+export function defaultFilename(mimeType, mediaKind = 'unknown') {
+    const ext = mimeType.includes('png') ? 'png'
+        : mimeType.includes('jpeg') || mimeType.includes('jpg') ? 'jpg'
+            : mimeType.includes('webp') ? 'webp'
+                : mimeType.includes('audio/mp4') ? 'm4a'
+                    : mimeType.includes('mp4') ? 'mp4'
+                        : mimeType.includes('webm') ? 'webm'
+                            : mimeType.includes('mpeg') ? 'mp3'
+                                : mimeType.includes('wav') ? 'wav'
+                                    : 'bin';
+    const prefix = mediaKind === 'unknown' ? 'file' : mediaKind;
+    return `${prefix}_${Date.now()}.${ext}`;
+}

package/dist/upload/media-fields.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 媒体字段识别：判断请求体里的某个值是不是待上传的媒体源，以及它是图/视频/音频。
+ *
+ * 识别分两层，按可靠性排序：
+ * 1. 按值识别（主）——用本次请求 params 里真实的媒体源反查。builder 把媒体
+ *    塞进什么字段名、嵌套多深都能命中，不依赖命名约定。
+ * 2. 按字段名 hint 识别（兜底）——覆盖 builder 对媒体值做过变换（裁剪、拼接）
+ *    因而对不上原值的少数情况。
+ *
+ * 纯函数模块，无 IO、无 Electron 依赖，可直接单测。
+ */
+import type { JsonObject } from '../types/runtime.js';
+export type MediaKind = 'image' | 'video' | 'audio' | 'file' | 'unknown';
+export type ResolvedMediaKind = Exclude<MediaKind, 'unknown'>;
+export type MediaSourceIndex = ReadonlyMap<string, ResolvedMediaKind>;
+/**
+ * 收集本次请求真实用到的本地媒体源，供按值识别使用。
+ *
+ * 只收本地路径 / data URI —— 远程 URL 本来就不需要重写，排除掉也顺带避免
+ * 普通字符串误入索引。
+ */
+export declare function buildMediaSourceIndex(params: JsonObject): MediaSourceIndex;
+/** 是否是需要上传的本地媒体源（本地路径 / 本地协议 / data URI）。 */
+export declare function isLocalMediaSource(value: string): boolean;
+/**
+ * 解析出实际媒体类型：优先沿用字段名 hint 推导出的类型，命中不了就按值回查。
+ */
+export declare function resolveMediaKind(mediaSources: MediaSourceIndex, declaredKind: MediaKind, value: string): MediaKind;
+/** 嵌套对象里，子字段没有自己的类型线索时沿用父级类型。 */
+export declare function inheritMediaKind(current: MediaKind, key: string): MediaKind;
+export declare function classifyMediaKey(key: string): MediaKind;
+/** 把各种本地协议还原成文件系统路径；不是本地源时返回 undefined。 */
+export declare function normalizeLocalSource(source: string): string | undefined;
+export declare function isRemoteHttpUrl(value: string): boolean;

package/dist/upload/media-fields.js

@@ -0,0 +1,135 @@
+/**
+ * 媒体字段识别：判断请求体里的某个值是不是待上传的媒体源，以及它是图/视频/音频。
+ *
+ * 识别分两层，按可靠性排序：
+ * 1. 按值识别（主）——用本次请求 params 里真实的媒体源反查。builder 把媒体
+ *    塞进什么字段名、嵌套多深都能命中，不依赖命名约定。
+ * 2. 按字段名 hint 识别（兜底）——覆盖 builder 对媒体值做过变换（裁剪、拼接）
+ *    因而对不上原值的少数情况。
+ *
+ * 纯函数模块，无 IO、无 Electron 依赖，可直接单测。
+ */
+/**
+ * 媒体输入在 params 上的标准落点。前端各入口（画布端口 / 工具面板 / 对话）
+ * 都只往这几个 key 写媒体，所以这里能穷举。
+ */
+const MEDIA_PARAM_SOURCE_KEYS = [
+    { kind: 'image', keys: ['uploadedFilePaths', 'images', 'image'] },
+    { kind: 'video', keys: ['uploadedVideoFilePaths', 'videos', 'video'] },
+    { kind: 'audio', keys: ['uploadedAudioFilePaths', 'audios', 'audio'] },
+];
+const IMAGE_FIELD_HINTS = [
+    'image', 'images', 'img_url', 'img_urls', 'image_url', 'image_urls',
+    'start_image_url', 'end_image_url', 'first_frame_image_url', 'last_frame_image_url',
+    'frame_url', 'frame_urls',
+    'reference_image_urls', 'input_urls', 'reference_images', 'input_image',
+];
+const VIDEO_FIELD_HINTS = [
+    'video', 'videos', 'video_url', 'video_urls', 'reference_video_urls',
+    'clip_url', 'clip_urls',
+    'uploaded_video_file_paths', 'uploaded_video_paths', 'input_video',
+];
+const AUDIO_FIELD_HINTS = [
+    'audio', 'audios', 'audio_url', 'audio_urls', 'prompt_audio_url',
+    'prompt_audio_urls', 'reference_audio_url', 'input_audio',
+];
+const LOCAL_SOURCE_PREFIXES = [
+    // 受限宿主可用不暴露真实路径的受管引用，由 RuntimeContext.media.read 解释。
+    'uxp://', 'managed://',
+    'henji-media://local/',
+    'http://asset.localhost/', 'https://asset.localhost/',
+    'http://tauri.localhost/', 'https://tauri.localhost/',
+    'asset://localhost/', 'tauri://localhost/',
+    'file://localhost/', 'file:///', 'file://',
+];
+/**
+ * 收集本次请求真实用到的本地媒体源，供按值识别使用。
+ *
+ * 只收本地路径 / data URI —— 远程 URL 本来就不需要重写，排除掉也顺带避免
+ * 普通字符串误入索引。
+ */
+export function buildMediaSourceIndex(params) {
+    const index = new Map();
+    for (const { kind, keys } of MEDIA_PARAM_SOURCE_KEYS) {
+        for (const key of keys) {
+            collectLocalMediaValues(params[key], (value) => {
+                if (!index.has(value))
+                    index.set(value, kind);
+            });
+        }
+    }
+    return index;
+}
+function collectLocalMediaValues(value, visit) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed && isLocalMediaSource(trimmed))
+            visit(trimmed);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectLocalMediaValues(item, visit);
+    }
+}
+/** 是否是需要上传的本地媒体源（本地路径 / 本地协议 / data URI）。 */
+export function isLocalMediaSource(value) {
+    return value.startsWith('data:') || normalizeLocalSource(value) !== undefined;
+}
+/**
+ * 解析出实际媒体类型：优先沿用字段名 hint 推导出的类型，命中不了就按值回查。
+ */
+export function resolveMediaKind(mediaSources, declaredKind, value) {
+    if (declaredKind !== 'unknown')
+        return declaredKind;
+    return mediaSources.get(value.trim()) ?? 'unknown';
+}
+/** 嵌套对象里，子字段没有自己的类型线索时沿用父级类型。 */
+export function inheritMediaKind(current, key) {
+    if (current === 'unknown' && key.toLowerCase() === 'url') {
+        return 'unknown';
+    }
+    const nested = classifyMediaKey(key);
+    return nested === 'unknown' ? current : nested;
+}
+export function classifyMediaKey(key) {
+    const normalized = key.toLowerCase();
+    if (IMAGE_FIELD_HINTS.some((hint) => normalized.includes(hint)))
+        return 'image';
+    if (VIDEO_FIELD_HINTS.some((hint) => normalized.includes(hint)))
+        return 'video';
+    if (AUDIO_FIELD_HINTS.some((hint) => normalized.includes(hint)))
+        return 'audio';
+    return 'unknown';
+}
+/** 把各种本地协议还原成文件系统路径；不是本地源时返回 undefined。 */
+export function normalizeLocalSource(source) {
+    for (const prefix of LOCAL_SOURCE_PREFIXES) {
+        if (source.startsWith(prefix)) {
+            return stripWindowsDrivePrefix(safeDecodeURIComponent(source.slice(prefix.length)));
+        }
+    }
+    return isLocalPath(source) ? source : undefined;
+}
+export function isRemoteHttpUrl(value) {
+    return /^https?:\/\//i.test(value) &&
+        !value.startsWith('http://asset.localhost/') &&
+        !value.startsWith('http://tauri.localhost/');
+}
+function isLocalPath(value) {
+    return value.startsWith('\\\\') ||
+        value.startsWith('/') ||
+        value.startsWith('~/') ||
+        /^[a-zA-Z]:[\\/]/.test(value);
+}
+function safeDecodeURIComponent(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function stripWindowsDrivePrefix(value) {
+    return /^\/[a-zA-Z]:/.test(value) ? value.slice(1) : value;
+}

package/dist/upload/prepared-media.d.ts

@@ -0,0 +1,5 @@
+export interface PreparedMediaBinary {
+    bytes: Uint8Array;
+    mimeType: string;
+    filename: string;
+}

package/dist/upload/prepared-media.js

@@ -0,0 +1 @@
+export {};

package/dist/upload/preprocess-core.d.ts

@@ -0,0 +1,40 @@
+import { type ResolvedRuntimeContext, type RuntimeContext } from '../runtime/RuntimeContext.js';
+import type { RuntimeConstraints } from '../types/model.js';
+import type { JsonObject, JsonValue } from '../types/runtime.js';
+import { type MediaKind } from './media-fields.js';
+import type { PreparedMediaBinary } from './prepared-media.js';
+export interface ProviderPreprocessInput {
+    providerId: string;
+    route: string;
+    body: JsonValue;
+    runtime: RuntimeContext;
+    params?: JsonObject;
+    constraints?: RuntimeConstraints;
+    requestId?: string;
+    signal?: AbortSignal;
+}
+export interface ProviderMediaRewriteInput {
+    providerId: string;
+    route: string;
+    mediaKind: Exclude<MediaKind, 'unknown'>;
+    fieldName?: string;
+    source: string;
+    prepared: PreparedMediaBinary;
+    params: JsonObject;
+    requestId?: string;
+    signal?: AbortSignal;
+    runtime: ResolvedRuntimeContext;
+}
+export interface ProviderObjectPreprocessInput {
+    providerId: string;
+    route: string;
+    object: JsonObject;
+    params: JsonObject;
+    rewrite(mediaKind: Exclude<MediaKind, 'unknown'>, fieldName: string, source: string): Promise<string>;
+}
+export interface ProviderPreprocessStrategy {
+    rewrite(input: ProviderMediaRewriteInput): Promise<string>;
+    preprocessObject?(input: ProviderObjectPreprocessInput): Promise<void>;
+}
+/** 供应商无关的唯一媒体遍历与本地字节读取内核。 */
+export declare function preprocessWithProviderStrategy(input: ProviderPreprocessInput, strategy: ProviderPreprocessStrategy): Promise<JsonValue>;