@spacex110/core 0.1.15 → 0.1.17

package/dist/index.d.ts

@@ -168,6 +168,55 @@ export declare class AIChannelManager {
         onDelta: (full: string) => void;
         signal?: AbortSignal;
     }): Promise<ChatResult>;
+    /**
+     * 私有：根据聊天结果更新通道状态。复用 chatWith / chatWithStream 的逻辑。
+     */
+    private updateChannelStatusAfterChat;
+    /**
+     * 使用当前激活通道发送多模态聊天。
+     * messages 支持 string（纯文本）或 ContentPart[]（多模态）。
+     */
+    chatMultimodal(message: ChatMessage | ChatMessage[], options?: {
+        messages?: ChatMessage[];
+        maxTokens?: number;
+        outputModalities?: Array<'text' | 'image'>;
+        temperature?: number;
+        timeoutMs?: number;
+    }): Promise<MultimodalChatManagerResult>;
+    /**
+     * 使用指定通道发送多模态聊天。
+     * 与 chatMultimodal 区别：可显式指定 channelId。
+     */
+    chatMultimodalWith(channelId: string, message: ChatMessage | ChatMessage[], options?: {
+        messages?: ChatMessage[];
+        maxTokens?: number;
+        outputModalities?: Array<'text' | 'image'>;
+        temperature?: number;
+        timeoutMs?: number;
+    }): Promise<MultimodalChatManagerResult>;
+    /**
+     * 使用当前激活通道发送多模态流式聊天。
+     * onDelta 每次收到「累计完整状态」（{ text, images }）。
+     */
+    chatMultimodalStream(message: ChatMessage | ChatMessage[], options: {
+        messages?: ChatMessage[];
+        maxTokens?: number;
+        outputModalities?: Array<'text' | 'image'>;
+        temperature?: number;
+        timeoutMs?: number;
+        onDelta: (state: MultimodalStreamDelta) => void;
+    }): Promise<MultimodalChatManagerResult>;
+    /**
+     * 使用指定通道发送多模态流式聊天。
+     */
+    chatMultimodalStreamWith(channelId: string, message: ChatMessage | ChatMessage[], options: {
+        messages?: ChatMessage[];
+        maxTokens?: number;
+        outputModalities?: Array<'text' | 'image'>;
+        temperature?: number;
+        timeoutMs?: number;
+        onDelta: (state: MultimodalStreamDelta) => void;
+    }): Promise<MultimodalChatManagerResult>;
     /** 测试指定通道的连接 */
     testChannel(id: string): Promise<{
         success: boolean;
@@ -305,6 +354,20 @@ export declare interface ChannelManagerOptions {
     proxyUrl?: string;
 }
 
+/**
+ * 多模态聊天消息。
+ * content 可以是纯文本字符串（兼容 sendDirectChat）或多模态内容块数组。
+ */
+export declare interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /**
+     * 消息内容：字符串走纯文本路径，多模态块数组走多模态路径。
+     */
+    content: string | ContentPart[];
+    /** 可选的消息名（部分协议支持） */
+    name?: string;
+}
+
 /** 聊天结果 */
 export declare interface ChatResult {
     success: boolean;
@@ -315,6 +378,62 @@ export declare interface ChatResult {
     model?: string;
 }
 
+/**
+ * 多模态内容块（输入侧调用方传入格式）。
+ * 不同协议的 ContentPart 形态不同，这里提供统一的 OpenAI 风格接口作为上层标准。
+ */
+export declare type ContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'low' | 'high' | 'auto';
+    };
+} | {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    } | {
+        type: 'url';
+        url: string;
+    };
+} | {
+    type: 'inline_data';
+    inline_data: {
+        mime_type: string;
+        data: string;
+    };
+} | {
+    type: 'audio';
+    input_audio: {
+        data: string;
+        format: 'wav' | 'mp3';
+    };
+};
+
+/**
+ * 响应侧的内容块。
+ * 文本部分用 string；多模态用数组，每个元素描述一种产出（文本/图片/音频）。
+ */
+export declare type ContentResponsePart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    url?: string;
+    b64_json?: string;
+    mimeType?: string;
+} | {
+    type: 'audio';
+    url?: string;
+    b64_json?: string;
+    mimeType?: string;
+};
+
 export declare function createConfigStorage(adapter?: StorageAdapter, options?: StorageOptions): {
     /**
      * Save AI config
@@ -400,6 +519,16 @@ export declare interface FetchModelsOptions {
     fallbackToStatic?: boolean;
 }
 
+/**
+ * 远程图片 → data URI。
+ * 拉取失败时返回原始 URL（标记 fallback=true），让协议策略自行决定是否接受 URL。
+ */
+export declare function fetchRemoteToDataUri(url: string): Promise<{
+    dataUri: string;
+    mimeType?: string;
+    fallback: boolean;
+}>;
+
 /**
  * Get all providers as an array
  */
@@ -427,6 +556,17 @@ export declare function getStaticModels(providerId: string): Model[];
 
 export declare function getStrategy(format: string): ProviderStrategy;
 
+/**
+ * 从 data URI 字符串中猜测 MIME 类型。
+ * 用于图片/音频响应在缺少 mimeType 字段时的回退解析。
+ *
+ * @example
+ * guessMimeFromDataUri('data:image/png;base64,xxx')  // => 'image/png'
+ * guessMimeFromDataUri('data:audio/mp3;base64,xxx')   // => 'audio/mp3'
+ * guessMimeFromDataUri('https://example.com/a.jpg')    // => null
+ */
+export declare function guessMimeFromDataUri(uri: string): string | null;
+
 export declare const I18N: {
     readonly zh: {
         readonly save: "保存配置";
@@ -502,6 +642,13 @@ export declare interface Model {
     name: string;
     /** 模型能力列表（如 text, vision, audio） */
     capabilities?: ModelCapability[];
+    /**
+     * 模型输出能力（如 image, audio）。
+     * 与 capabilities 区分：capabilities 指模型能理解/处理哪些输入；
+     * outputCapabilities 指模型能生成哪些类型的输出。
+     * 当前仅在多模态输出场景（如 OpenRouter 文生图、Gemini 生图）使用。
+     */
+    outputCapabilities?: Array<'image' | 'audio'>;
     /** 上下文窗口大小 */
     contextLength?: number;
 }
@@ -528,6 +675,153 @@ declare interface ModelCapabilityMeta {
  */
 export declare type ModelFetcher = (params: FetcherParams) => Promise<any>;
 
+/**
+ * 多模态聊天结果（通道管理器层）。
+ * 在底层 MultimodalChatResult 上附加 channelId 与 model，便于上层定位调用方。
+ */
+export declare interface MultimodalChatManagerResult extends MultimodalChatResult {
+    /** 调用方通道 ID */
+    channelId: string;
+    /** 实际请求的模型 ID */
+    model: string;
+}
+
+/**
+ * 调用 sendMultimodalChat / sendMultimodalChatStream 的输入参数。
+ * 与 sendDirectChat 不同：messages 字段是 ChatMessage[]（支持 content: string | ContentPart[]）。
+ */
+export declare interface MultimodalChatOptions {
+    /** 协议类型 */
+    apiFormat: ApiFormat;
+    /** API Key */
+    apiKey: string;
+    /** 模型 ID */
+    model: string;
+    /** 厂商 Base URL */
+    baseUrl: string;
+    /** 聊天消息列表（支持多模态） */
+    messages: ChatMessage[];
+    /** 最大输出 token */
+    maxTokens?: number;
+    /** 温度 */
+    temperature?: number;
+    /** 请求超时（毫秒） */
+    timeoutMs?: number;
+    /**
+     * 期望的输出模态。
+     * - 仅在 OpenRouter（OpenAI 协议）或 Gemini 协议下生效；其他协议传入 image 会直接报错
+     * - 示例：['text']、['text', 'image']
+     */
+    outputModalities?: Array<'text' | 'image'>;
+    /** 透传给 fetch 的额外 headers（用于透传 Authorization 代理等） */
+    extraHeaders?: Record<string, string>;
+}
+
+/** 非流式多模态聊天结果 */
+export declare interface MultimodalChatResult {
+    success: boolean;
+    /** 纯文本内容（仅当响应只有文本时填充） */
+    text?: string;
+    /** 多模态产出（文本/图片/音频混排；与 text 二选一） */
+    images?: Array<{
+        type: 'image';
+        url?: string;
+        b64_json?: string;
+        mimeType?: string;
+    }>;
+    /** token 用量 */
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    /** 耗时（毫秒） */
+    latencyMs?: number;
+    /** 错误信息（success=false 时填充） */
+    message?: string;
+    /** 结束原因 */
+    finishReason?: string;
+    /** 协议原始响应 */
+    raw?: unknown;
+}
+
+/** 流式多模态聊天入参 */
+export declare interface MultimodalChatStreamOptions extends Omit<MultimodalChatOptions, 'timeoutMs'> {
+    /**
+     * 增量回调，每次收到协议 chunk 时触发。
+     * state.text 是累计完整文本（同 sendDirectChatStream 约定）；
+     * state.images 是累计完整图片数组（图片一般整块出现，浅拷贝给上层）。
+     */
+    onDelta: (state: MultimodalStreamDelta) => void;
+    /** 可选超时（毫秒） */
+    timeoutMs?: number;
+}
+
+/** 流式多模态聊天的增量回调状态 */
+export declare interface MultimodalStreamDelta {
+    /** 累计的完整文本 */
+    text?: string;
+    /** 累计的图片数组（每次浅拷贝替换，不要 append） */
+    images?: Array<{
+        type: 'image';
+        url?: string;
+        b64_json?: string;
+        mimeType?: string;
+    }>;
+    /** 结束原因（最后一片 chunk 时填充） */
+    finishReason?: string;
+    /** token 用量（最后一片 chunk 时填充） */
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+}
+
+/** 内部统一的消息结构 */
+export declare interface NormalizedMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    parts: NormalizedPart[];
+}
+
+/**
+ * 内部统一的多模态内容块。
+ * 各协议策略都接收 NormalizedMessage[] 作为输入，避免重复处理不同协议字段差异。
+ */
+export declare type NormalizedPart = {
+    type: 'text';
+    data: string;
+    meta?: Record<string, unknown>;
+} | {
+    type: 'image';
+    data: string;
+    mimeType?: string;
+    meta?: Record<string, unknown>;
+} | {
+    type: 'audio';
+    data: string;
+    mimeType?: string;
+    meta?: Record<string, unknown>;
+};
+
+/**
+ * 把 ChatMessage[] 转为 NormalizedMessage[]。
+ *
+ * 规则：
+ * - content: string → 一个 text part
+ * - content: ContentPart[] → 逐个 normalizePart
+ * - role: 'tool' → 在统一层视为 'user'（避免各策略重复处理 tool role）
+ */
+export declare function normalizeMessages(messages: ChatMessage[]): Promise<NormalizedMessage[]>;
+
+/**
+ * 把一个 ContentPart 转成 NormalizedPart。
+ * - text：透传
+ * - image_url / image / inline_data：归一化为 image + data URI
+ * - audio：归一化为 audio + data URI
+ */
+export declare function normalizePart(p: ContentPart): Promise<NormalizedPart>;
+
 /**
  * 明文存储适配器（不推荐）
  */
@@ -597,6 +891,16 @@ export declare interface ProviderStrategy {
     /** 从一个 SSE data 块中提取增量文本（流式）。返回空字符串表示无内容。 */
     parseStreamChunk?: (data: any) => string;
     buildHeaders: (apiKey: string, baseUrl?: string) => Record<string, string>;
+    /** 是否支持图片/音频等多模态输入。不支持时调用方传入多模态消息应直接报错。 */
+    supportsMultimodalInput?: boolean;
+    /** 是否支持多模态输出（如文生图）。不支持时调用方传入 outputModalities 含 image 应直接报错。 */
+    supportsMultimodalOutput?: boolean;
+    /** 构造多模态聊天请求体 */
+    buildMultimodalChatPayload?: (model: string, messages: NormalizedMessage[], options: MultimodalChatOptions) => Record<string, unknown>;
+    /** 解析多模态聊天响应为统一的 ResponseMessage */
+    parseMultimodalChatResponse?: (data: any) => ResponseMessage;
+    /** 解析 SSE 流式 chunk 为增量状态 */
+    parseMultimodalStreamChunk?: (data: any) => MultimodalStreamDelta;
 }
 
 export declare interface ResolvedConfig {
@@ -609,6 +913,25 @@ export declare interface ResolvedConfig {
  */
 export declare function resolveProviderConfig(config?: ProviderConfig): ResolvedConfig;
 
+/** 各协议策略解析后的统一响应结构 */
+export declare interface ResponseMessage {
+    role: 'assistant';
+    /**
+     * 响应内容：纯文本时用 string，包含图片/音频时用 ContentResponsePart 数组。
+     */
+    content: string | ContentResponsePart[];
+    /** token 用量（如协议提供） */
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    /** 原始协议响应（调试/透传用） */
+    raw?: unknown;
+    /** 结束原因（如 'stop'、'length'、'tool_calls'） */
+    finishReason?: string;
+}
+
 /**
  * 纯前端直连 AI 厂商进行聊天
  * 注意: 这会将 API Key 暴露在浏览器中，仅适用于 Demo/测试场景
@@ -621,6 +944,20 @@ export declare function sendDirectChat(options: DirectChatOptions): Promise<Dire
  */
 export declare function sendDirectChatStream(options: DirectChatStreamOptions): Promise<DirectChatResult>;
 
+/**
+ * 发送多模态聊天请求（输入支持文本/图片/音频；输出可选图片）。
+ * 与 sendDirectChat 并存，是独立 API，不影响纯文本路径。
+ */
+export declare function sendMultimodalChat(options: MultimodalChatOptions): Promise<MultimodalChatResult>;
+
+/**
+ * 发送多模态聊天请求（SSE 流式）。
+ * 每次收到协议 chunk 都会触发 onDelta 回调：
+ *   - state.text 累计完整文本
+ *   - state.images 累计完整图片数组（浅拷贝）
+ */
+export declare function sendMultimodalChatStream(options: MultimodalChatStreamOptions): Promise<MultimodalChatResult>;
+
 export declare const STATIC_MODELS: Record<string, Model[]>;
 
 export declare interface StorageAdapter {