@opentiny/tiny-robot-kit 0.4.0-alpha.1 → 0.4.0-alpha.11

package/dist/index.d.mts

@@ -1,27 +1,57 @@
 import { Ref, ComputedRef } from 'vue';
 
-type MaybePromise<T> = T | Promise<T>;
-
 /**
- * 工具函数模块
- * 提供一些实用的辅助函数
+ * 模型Provider基类
  */
+declare abstract class BaseModelProvider {
+    protected config: AIModelConfig;
+    /**
+     * @param config AI模型配置
+     */
+    constructor(config: AIModelConfig);
+    /**
+     * 发送聊天请求并获取响应
+     * @param request 聊天请求参数
+     * @returns 聊天响应
+     */
+    abstract chat(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
+    /**
+     * 发送流式聊天请求并通过处理器处理响应
+     * @param request 聊天请求参数
+     * @param handler 流式响应处理器
+     */
+    abstract chatStream(request: ChatCompletionRequest, handler: StreamHandler): Promise<void>;
+    /**
+     * 更新配置
+     * @param config 新的AI模型配置
+     */
+    updateConfig(config: AIModelConfig): void;
+    /**
+     * 获取当前配置
+     * @returns AI模型配置
+     */
+    getConfig(): AIModelConfig;
+    /**
+     * 验证请求参数
+     * @param request 聊天请求参数
+     */
+    protected validateRequest(request: ChatCompletionRequest): void;
+}
 
-declare function createSSEStreamGenerator<T = any>(response: Response, options?: {
-    signal?: AbortSignal;
-}): AsyncGenerator<T, void, unknown>;
-
-interface Tool {
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * 消息角色类型
+ */
+type MessageRole = 'system' | 'user' | 'assistant';
+interface ToolCall {
+    index: number;
+    id: string;
     type: 'function';
     function: {
         name: string;
-        description: string;
-        /**
-         * function 的输入参数，以 JSON Schema 对象描述
-         */
-        parameters: any;
+        arguments: string;
+        result?: string;
     };
-    [key: string]: any;
 }
 interface MessageMetadata {
     createdAt?: number;
@@ -30,31 +60,254 @@ interface MessageMetadata {
     model?: string;
     [key: string]: any;
 }
+/**
+ * 聊天消息接口
+ */
 interface ChatMessage {
     role: string;
     content: string;
+    reasoning_content?: string;
     metadata?: MessageMetadata;
     tool_calls?: ToolCall[];
     tool_call_id?: string;
     [key: string]: any;
     [key: symbol]: any;
 }
-interface MessageRequestBody {
-    messages: Partial<ChatMessage>[];
-    [key: string]: any;
+/**
+ * 聊天历史记录
+ */
+type ChatHistory = ChatMessage[];
+/**
+ * 聊天完成请求选项
+ */
+interface ChatCompletionOptions {
+    model?: string;
+    temperature?: number;
+    top_p?: number;
+    n?: number;
+    stream?: boolean;
+    max_tokens?: number;
+    signal?: AbortSignal;
 }
-type RequestState = 'idle' | 'processing' | 'completed' | 'aborted' | 'error';
-type RequestProcessingState = 'requesting' | 'completing' | string;
-interface ToolCall {
+/**
+ * 聊天完成请求参数
+ */
+interface ChatCompletionRequest {
+    messages: ChatMessage[];
+    options?: ChatCompletionOptions;
+}
+/**
+ * 聊天完成响应消息
+ */
+interface ChatCompletionResponseMessage {
+    role: MessageRole;
+    content: string;
+    [x: string]: unknown;
+}
+/**
+ * 聊天完成响应选择
+ */
+interface ChatCompletionResponseChoice {
+    index: number;
+    message: ChatCompletionResponseMessage;
+    finish_reason: string;
+}
+/**
+ * 聊天完成响应使用情况
+ */
+interface ChatCompletionResponseUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+/**
+ * 聊天完成响应
+ */
+interface ChatCompletionResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: ChatCompletionResponseChoice[];
+    usage: ChatCompletionResponseUsage;
+}
+/**
+ * 流式聊天完成响应增量
+ */
+interface ChatCompletionStreamResponseDelta {
+    content?: string;
+    role?: MessageRole;
+    [x: string]: unknown;
+}
+/**
+ * 流式聊天完成响应选择
+ */
+interface ChatCompletionStreamResponseChoice {
     index: number;
+    delta: ChatCompletionStreamResponseDelta;
+    finish_reason: string | null;
+}
+/**
+ * 流式聊天完成响应
+ */
+interface ChatCompletionStreamResponse {
     id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: ChatCompletionStreamResponseChoice[];
+}
+/**
+ * AI模型提供商类型
+ */
+type AIProvider = 'openai' | 'deepseek' | 'custom';
+/**
+ * AI模型配置接口
+ */
+interface AIModelConfig {
+    provider: AIProvider;
+    providerImplementation?: BaseModelProvider;
+    apiKey?: string;
+    apiUrl?: string;
+    apiVersion?: string;
+    defaultModel?: string;
+    defaultOptions?: ChatCompletionOptions;
+}
+/**
+ * 错误类型
+ */
+declare enum ErrorType {
+    NETWORK_ERROR = "network_error",
+    AUTHENTICATION_ERROR = "authentication_error",
+    RATE_LIMIT_ERROR = "rate_limit_error",
+    SERVER_ERROR = "server_error",
+    MODEL_ERROR = "model_error",
+    TIMEOUT_ERROR = "timeout_error",
+    UNKNOWN_ERROR = "unknown_error"
+}
+/**
+ * AI适配器错误
+ */
+interface AIAdapterError {
+    type: ErrorType;
+    message: string;
+    statusCode?: number;
+    originalError?: object;
+}
+/**
+ * 流式响应事件类型
+ */
+declare enum StreamEventType {
+    DATA = "data",
+    ERROR = "error",
+    DONE = "done"
+}
+/**
+ * 流式响应处理器
+ */
+interface StreamHandler {
+    onData: (data: ChatCompletionStreamResponse) => void;
+    onError: (error: AIAdapterError) => void;
+    onDone: (finishReason?: string) => void;
+}
+
+/**
+ * AI客户端类
+ * 负责根据配置选择合适的提供商并处理请求
+ */
+
+/**
+ * @deprecated
+ * AI客户端类
+ */
+declare class AIClient {
+    private provider;
+    private config;
+    /**
+     * 构造函数
+     * @param config AI模型配置
+     */
+    constructor(config: AIModelConfig);
+    /**
+     * 创建提供商实例
+     * @param config AI模型配置
+     * @returns 提供商实例
+     */
+    private createProvider;
+    /**
+     * 发送聊天请求并获取响应
+     * @param request 聊天请求参数
+     * @returns 聊天响应
+     */
+    chat(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
+    /**
+     * 发送流式聊天请求并通过处理器处理响应
+     * @param request 聊天请求参数
+     * @param handler 流式响应处理器
+     */
+    chatStream(request: ChatCompletionRequest, handler: StreamHandler): Promise<void>;
+    /**
+     * 获取当前配置
+     * @returns AI模型配置
+     */
+    getConfig(): AIModelConfig;
+    /**
+     * 更新配置
+     * @param config 新的AI模型配置
+     */
+    updateConfig(config: Partial<AIModelConfig>): void;
+}
+
+/**
+ * OpenAI提供商
+ * 用于与OpenAI API进行交互
+ */
+
+declare class OpenAIProvider extends BaseModelProvider {
+    private baseURL;
+    private apiKey;
+    private defaultModel;
+    /**
+     * @param config AI模型配置
+     */
+    constructor(config: AIModelConfig);
+    /**
+     * 发送聊天请求并获取响应
+     * @param request 聊天请求参数
+     * @returns 聊天响应
+     */
+    chat(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
+    /**
+     * 发送流式聊天请求并通过处理器处理响应
+     * @param request 聊天请求参数
+     * @param handler 流式响应处理器
+     */
+    chatStream(request: ChatCompletionRequest, handler: StreamHandler): Promise<void>;
+    /**
+     * 更新配置
+     * @param config 新的AI模型配置
+     */
+    updateConfig(config: AIModelConfig): void;
+}
+
+interface Tool {
     type: 'function';
     function: {
         name: string;
-        arguments: string;
-        result?: string;
+        description: string;
+        /**
+         * function 的输入参数，以 JSON Schema 对象描述
+         */
+        parameters: any;
     };
+    [key: string]: any;
+}
+interface MessageRequestBody {
+    messages: Partial<ChatMessage>[];
+    [key: string]: any;
 }
+type RequestState = 'idle' | 'processing' | 'completed' | 'aborted' | 'error';
+type RequestProcessingState = 'requesting' | 'completing' | string;
 interface Usage {
     prompt_tokens: number;
     completion_tokens: number;
@@ -101,7 +354,16 @@ interface ChatCompletion {
 }
 interface UseMessageOptions {
     initialMessages?: ChatMessage[];
-    requestMessageFields?: (keyof ChatMessage)[];
+    /**
+     * 请求消息时，要包含的字段（白名单）。默认包含所有字段。
+     * 如果 `requestMessageFieldsExclude` 存在，会先取 `requestMessageFields` 中的字段，再排除 `requestMessageFieldsExclude` 中的字段
+     */
+    requestMessageFields?: string[];
+    /**
+     * 请求消息时，要排除的字段（黑名单）。默认会排除 `state`、`metadata`、`loading` 字段（这几个字段是给UI展示用的）。
+     * 如果 `requestMessageFields` 存在，会先取 `requestMessageFields` 中的字段，再排除 `requestMessageFieldsExclude` 中的字段
+     */
+    requestMessageFieldsExclude?: string[];
     plugins?: UseMessagePlugin[];
     responseProvider: <T = ChatCompletion>(requestBody: MessageRequestBody, abortSignal: AbortSignal) => Promise<T> | AsyncGenerator<T> | Promise<AsyncGenerator<T>>;
     /**
@@ -111,6 +373,7 @@ interface UseMessageOptions {
      */
     onCompletionChunk?: (context: BasePluginContext & {
         currentMessage: ChatMessage;
+        choice: CompletionChoice;
         chunk: ChatCompletion;
     }, runDefault: () => void) => void;
 }
@@ -129,7 +392,6 @@ interface BasePluginContext {
     currentTurn: ChatMessage[];
     requestState: RequestState;
     processingState?: RequestProcessingState;
-    requestMessageFields: (keyof ChatMessage)[];
     plugins: UseMessagePlugin[];
     setRequestState: (state: RequestState, processingState?: RequestProcessingState) => void;
     abortSignal: AbortSignal;
@@ -150,7 +412,7 @@ interface UseMessagePlugin {
     /**
      * 是否禁用插件。useMessage 可能会内置一些默认插件，如果需要禁用，可以设置为 true。
      */
-    disabled?: boolean;
+    disabled?: boolean | ((context: BasePluginContext) => boolean);
     /**
      * 一次对话回合（turn）开始钩子：用户消息入队后、正式发起请求之前触发。
      * 按插件注册顺序串行执行，便于做有序初始化/校验；出错则中断流程。
@@ -195,6 +457,7 @@ interface UseMessagePlugin {
     onError?: (context: BasePluginContext & {
         error: unknown;
     }) => void;
+    onFinally?: (context: BasePluginContext) => void;
 }
 
 interface ConversationInfo {
@@ -215,28 +478,6 @@ interface Conversation extends ConversationInfo {
      */
     engine: UseMessageReturn;
 }
-interface ConversationStorageStrategy {
-    /**
-     * Load all conversations (id and title only).
-     */
-    loadConversations?: () => MaybePromise<ConversationInfo[]>;
-    /**
-     * Load all messages for a given conversation.
-     */
-    loadMessages?: (conversationId: string) => MaybePromise<ChatMessage[]>;
-    /**
-     * Persist conversation metadata (create or update).
-     */
-    saveConversation?: (conversation: ConversationInfo) => MaybePromise<void>;
-    /**
-     * Persist messages for a given conversation.
-     */
-    saveMessages?: (conversationId: string, messages: ChatMessage[]) => MaybePromise<void>;
-    /**
-     * Optional method to delete a conversation and its messages.
-     */
-    deleteConversation?: (conversationId: string) => MaybePromise<void>;
-}
 interface UseConversationOptions {
     /**
      * Base useMessage options for all conversations.
@@ -260,6 +501,11 @@ interface UseConversationOptions {
      * When provided, conversation list and messages can be loaded and persisted.
      */
     storage?: ConversationStorageStrategy;
+    /**
+     * Called when the initial conversation list has been loaded from storage.
+     * Only fired when storage.loadConversations is available and has completed.
+     */
+    onLoad?: (conversations: ConversationInfo[]) => void;
 }
 interface UseConversationReturn {
     conversations: Ref<ConversationInfo[]>;
@@ -277,12 +523,144 @@ interface UseConversationReturn {
     }) => Conversation;
     switchConversation: (id: string) => Promise<Conversation | null>;
     deleteConversation: (id: string) => Promise<void>;
+    clear: () => void;
     updateConversationTitle: (id: string, title?: string) => void;
     saveMessages: (id?: string) => void;
     sendMessage: (content: string) => void;
     abortActiveRequest: () => Promise<void>;
 }
 
+/**
+ * 存储策略接口
+ */
+interface ConversationStorageStrategy {
+    /**
+     * Load all conversations (id and title only).
+     */
+    loadConversations: () => MaybePromise<ConversationInfo[]>;
+    /**
+     * Load all messages for a given conversation.
+     */
+    loadMessages: (conversationId: string) => MaybePromise<ChatMessage[]>;
+    /**
+     * Persist conversation metadata (create or update).
+     */
+    saveConversation: (conversation: ConversationInfo) => MaybePromise<void>;
+    /**
+     * Persist messages for a given conversation.
+     */
+    saveMessages: (conversationId: string, messages: ChatMessage[]) => MaybePromise<void>;
+    /**
+     * Optional method to delete a conversation and its messages.
+     */
+    deleteConversation?: (conversationId: string) => MaybePromise<void>;
+}
+
+/**
+ * 本地存储策略
+ */
+declare class LocalStorageStrategy implements ConversationStorageStrategy {
+    private storageKey;
+    constructor(storageKey?: string);
+    saveConversation(conversation: ConversationInfo): void;
+    loadConversations(): ConversationInfo[];
+    saveMessages(conversationId: string, messages: ChatMessage[]): void;
+    loadMessages(conversationId: string): ChatMessage[];
+    deleteConversation(conversationId: string): void;
+}
+
+/**
+ * IndexedDB 存储策略
+ */
+declare class IndexedDBStrategy implements ConversationStorageStrategy {
+    private dbName;
+    private dbVersion;
+    private db;
+    constructor(dbName?: string, dbVersion?: number);
+    /**
+     * 获取或初始化数据库连接
+     */
+    private getDB;
+    /**
+     * 加载所有会话（只包含元数据）
+     */
+    loadConversations(): Promise<ConversationInfo[]>;
+    /**
+     * 加载指定会话的所有消息
+     */
+    loadMessages(conversationId: string): Promise<ChatMessage[]>;
+    /**
+     * 保存或更新会话元数据
+     */
+    saveConversation(conversation: ConversationInfo): Promise<void>;
+    /**
+     * 保存指定会话的消息
+     */
+    saveMessages(conversationId: string, messages: ChatMessage[]): Promise<void>;
+    /**
+     * 删除会话及其所有消息
+     */
+    deleteConversation(conversationId: string): Promise<void>;
+}
+
+interface LocalStorageConfig {
+    /** 存储键名 (default: 'tiny-robot-ai-conversations') */
+    key?: string;
+}
+interface IndexedDBConfig {
+    /** 数据库名称 (default: 'tiny-robot-ai-db') */
+    dbName?: string;
+    /** 数据库版本 (default: 1) */
+    dbVersion?: number;
+}
+/**
+ * LocalStorage 策略工厂函数
+ */
+declare function localStorageStrategyFactory(config?: LocalStorageConfig): ConversationStorageStrategy;
+/**
+ * IndexedDB 策略工厂函数
+ */
+declare function indexedDBStorageStrategyFactory(config?: IndexedDBConfig): ConversationStorageStrategy;
+
+/**
+ * 工具函数模块
+ * 提供一些实用的辅助函数
+ */
+
+/**
+ * 处理SSE流式响应
+ * @param response fetch响应对象
+ * @param handler 流处理器
+ */
+declare function handleSSEStream(response: Response, handler: StreamHandler, signal?: AbortSignal): Promise<void>;
+/**
+ * 格式化消息
+ * 将各种格式的消息转换为标准的ChatMessage格式
+ * @param messages 消息数组
+ * @returns 标准格式的消息数组
+ */
+declare function formatMessages(messages: Array<ChatMessage | string>): ChatMessage[];
+/**
+ * 从响应中提取文本内容
+ * @param response 聊天完成响应
+ * @returns 文本内容
+ */
+declare function extractTextFromResponse(response: ChatCompletionResponse): string;
+/**
+ * 将 SSE 流转换为异步生成器。
+ * 将服务器发送事件（SSE）流式响应转换为异步生成器，逐个产出解析后的数据
+ *
+ * 当取消信号被触发时，会抛出 name 为 'AbortError' 的错误
+ * @param response fetch 响应对象
+ * @param options 配置选项
+ * @param options.signal 可选的取消信号，用于中断流处理
+ * @returns 异步生成器，产出类型为 T 的数据
+ * @template T 生成器产出的数据类型，默认为 any
+ */
+declare function sseStreamToGenerator<T = any>(response: Response, options?: {
+    signal?: AbortSignal;
+}): AsyncGenerator<T, void, unknown>;
+
 declare const useConversation: (options: UseConversationOptions) => UseConversationReturn;
 
 declare const fallbackRolePlugin: (options?: UseMessagePlugin & {
@@ -366,4 +744,4 @@ declare const toolPlugin: (options: UseMessagePlugin & {
 
 declare const useMessage: (options: UseMessageOptions) => UseMessageReturn;
 
-export { type BasePluginContext, type ChatCompletion, type ChatMessage, type Choice, type CompletionChoice, type Conversation, type ConversationInfo, type ConversationStorageStrategy, type DeltaChoice, EXCLUDE_MODE_REMOVE, type MessageMetadata, type MessageRequestBody, type RequestProcessingState, type RequestState, type Tool, type ToolCall, type Usage, type UseConversationOptions, type UseConversationReturn, type UseMessageOptions, type UseMessagePlugin, type UseMessageReturn, createSSEStreamGenerator, fallbackRolePlugin, lengthPlugin, thinkingPlugin, toolPlugin, useConversation, useMessage };
+export { type AIAdapterError, AIClient, type AIModelConfig, type AIProvider, BaseModelProvider, type BasePluginContext, type ChatCompletion, type ChatCompletionOptions, type ChatCompletionRequest, type ChatCompletionResponse, type ChatCompletionResponseChoice, type ChatCompletionResponseMessage, type ChatCompletionResponseUsage, type ChatCompletionStreamResponse, type ChatCompletionStreamResponseChoice, type ChatCompletionStreamResponseDelta, type ChatHistory, type ChatMessage, type Choice, type CompletionChoice, type Conversation, type ConversationInfo, type ConversationStorageStrategy, type DeltaChoice, EXCLUDE_MODE_REMOVE, ErrorType, type IndexedDBConfig, IndexedDBStrategy, type LocalStorageConfig, LocalStorageStrategy, type MaybePromise, type MessageMetadata, type MessageRequestBody, type MessageRole, OpenAIProvider, type RequestProcessingState, type RequestState, StreamEventType, type StreamHandler, type Tool, type ToolCall, type Usage, type UseConversationOptions, type UseConversationReturn, type UseMessageOptions, type UseMessagePlugin, type UseMessageReturn, extractTextFromResponse, fallbackRolePlugin, formatMessages, handleSSEStream, indexedDBStorageStrategyFactory, lengthPlugin, localStorageStrategyFactory, sseStreamToGenerator, thinkingPlugin, toolPlugin, useConversation, useMessage };