@spacex110/core 0.1.16 → 0.1.17

package/src/types.ts

@@ -78,6 +78,13 @@ export interface Model {
     name: string;
     /** 模型能力列表（如 text, vision, audio） */
     capabilities?: ModelCapability[];
+    /**
+     * 模型输出能力（如 image, audio）。
+     * 与 capabilities 区分：capabilities 指模型能理解/处理哪些输入；
+     * outputCapabilities 指模型能生成哪些类型的输出。
+     * 当前仅在多模态输出场景（如 OpenRouter 文生图、Gemini 生图）使用。
+     */
+    outputCapabilities?: Array<'image' | 'audio'>;
     /** 上下文窗口大小 */
     contextLength?: number;
 }
@@ -161,3 +168,173 @@ export interface AIConfigFormProps {
     /** 是否禁用整个表单 */
     disabled?: boolean;
 }
+
+// ============ Multimodal Chat Types ============
+
+/**
+ * 多模态内容块（输入侧调用方传入格式）。
+ * 不同协议的 ContentPart 形态不同，这里提供统一的 OpenAI 风格接口作为上层标准。
+ */
+export type ContentPart =
+    | { type: 'text'; text: string }
+    | { type: 'image_url'; image_url: { url: string; detail?: 'low' | 'high' | 'auto' } }
+    // Anthropic 风格图片块
+    | {
+          type: 'image';
+          source:
+              | { type: 'base64'; media_type: string; data: string }
+              | { type: 'url'; url: string };
+      }
+    // Gemini 风格 inline 数据块（图片/音频通用）
+    | { type: 'inline_data'; inline_data: { mime_type: string; data: string } }
+    // OpenAI 风格输入音频
+    | { type: 'audio'; input_audio: { data: string; format: 'wav' | 'mp3' } };
+
+/**
+ * 多模态聊天消息。
+ * content 可以是纯文本字符串（兼容 sendDirectChat）或多模态内容块数组。
+ */
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /**
+     * 消息内容：字符串走纯文本路径，多模态块数组走多模态路径。
+     */
+    content: string | ContentPart[];
+    /** 可选的消息名（部分协议支持） */
+    name?: string;
+}
+
+/**
+ * 内部统一的多模态内容块。
+ * 各协议策略都接收 NormalizedMessage[] 作为输入，避免重复处理不同协议字段差异。
+ */
+export 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> };
+
+/** 内部统一的消息结构 */
+export interface NormalizedMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    parts: NormalizedPart[];
+}
+
+/**
+ * 响应侧的内容块。
+ * 文本部分用 string；多模态用数组，每个元素描述一种产出（文本/图片/音频）。
+ */
+export 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 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;
+}
+
+/**
+ * 调用 sendMultimodalChat / sendMultimodalChatStream 的输入参数。
+ * 与 sendDirectChat 不同：messages 字段是 ChatMessage[]（支持 content: string | ContentPart[]）。
+ */
+export 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 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 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 interface MultimodalChatStreamOptions extends Omit<MultimodalChatOptions, 'timeoutMs'> {
+    /**
+     * 增量回调，每次收到协议 chunk 时触发。
+     * state.text 是累计完整文本（同 sendDirectChatStream 约定）；
+     * state.images 是累计完整图片数组（图片一般整块出现，浅拷贝给上层）。
+     */
+    onDelta: (state: MultimodalStreamDelta) => void;
+    /** 可选超时（毫秒） */
+    timeoutMs?: number;
+}