@yh-ui/ai-sdk 0.1.21

package/dist/vue/index.d.ts

@@ -0,0 +1,627 @@
+/**
+ * Vue-specific AI composables
+ *
+ * 提供与 YH-UI 组件深度集成的 Vue 3 Composition API
+ * 增强版本：多会话支持、XRequest 中间件、缓存重试
+ */
+import { type Ref } from 'vue';
+export interface StreamableValue<T = unknown> {
+    value: Ref<T>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+}
+export interface ConversationMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    name?: string;
+    toolCallId?: string;
+    toolCalls?: ToolCall[];
+    createdAt?: Date;
+    metadata?: Record<string, unknown>;
+}
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface ConversationConfig {
+    /** 消息历史保留条数 */
+    maxHistory?: number;
+    /** 是否自动保存到 localStorage */
+    persist?: boolean;
+    /** localStorage key */
+    storageKey?: string;
+}
+export interface ToolCallHandler {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    execute: (args: Record<string, unknown>) => Promise<unknown>;
+}
+export interface ProviderAdapter {
+    name: string;
+    baseUrl?: string;
+    apiKey?: string;
+    defaultModel?: string;
+}
+export interface ModelConfig {
+    model: string;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    stop?: string[];
+}
+export interface XRequestConfig {
+    /** 请求 URL */
+    url: string;
+    /** 请求方法 */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** 请求头 */
+    headers?: Record<string, string>;
+    /** 请求体 */
+    body?: Record<string, unknown>;
+    /** 查询参数 */
+    params?: Record<string, string>;
+    /** 超时时间 (ms) */
+    timeout?: number;
+    /** 是否启用流式 */
+    stream?: boolean;
+    /** 请求标识 */
+    requestId?: string;
+    /** 额外数据 */
+    extra?: Record<string, unknown>;
+}
+export interface XRequestCallbacks {
+    /** 请求开始 */
+    onStart?: (config: XRequestConfig) => void;
+    /** 收到响应头 */
+    onResponse?: (response: Response) => void;
+    /** 流式 chunk */
+    onChunk?: (chunk: string, data?: unknown) => void;
+    /** 流式完成 */
+    onFinish?: (fullContent: string, data?: unknown) => void;
+    /** 请求错误 */
+    onError?: (error: Error) => void;
+    /** 请求完成 (无论成功失败) */
+    onFinally?: () => void;
+}
+export interface AIMiddleware {
+    /** 中间件名称 */
+    name: string;
+    /** 请求前拦截 */
+    onRequest?: (config: XRequestConfig) => XRequestConfig | Promise<XRequestConfig>;
+    /** 响应后拦截 */
+    onResponse?: (response: unknown, config: XRequestConfig) => unknown;
+    /** 流式 chunk 拦截 */
+    onChunk?: (chunk: string, config: XRequestConfig) => string;
+    /** 错误拦截 */
+    onError?: (error: Error, config: XRequestConfig) => Error;
+}
+export interface CacheConfig {
+    /** 启用缓存 */
+    enabled?: boolean;
+    /** 缓存 key */
+    key?: string;
+    /** 缓存时间 (ms) */
+    ttl?: number;
+    /** 缓存策略 */
+    strategy?: 'memory' | 'localStorage' | 'sessionStorage';
+}
+export interface RetryConfig {
+    /** 启用重试 */
+    enabled?: boolean;
+    /** 最大重试次数 */
+    maxRetries?: number;
+    /** 重试延迟 (ms) */
+    retryDelay?: number;
+    /** 重试条件 */
+    retryCondition?: (error: Error) => boolean;
+}
+export interface Conversation {
+    id: string;
+    title: string;
+    messages: ConversationMessage[];
+    createdAt: Date;
+    updatedAt: Date;
+    metadata?: Record<string, unknown>;
+}
+export interface UseConversationsOptions {
+    /** 最大会话数 */
+    maxConversations?: number;
+    /** 是否持久化 */
+    persist?: boolean;
+    /** 存储 key */
+    storageKey?: string;
+    /** 自动生成标题 */
+    autoTitle?: boolean;
+}
+/**
+ * 创建可流式更新的值
+ *
+ * @example
+ * ```ts
+ * const { value, loading, error } = createStreamableValue<string>('')
+ *
+ * // 在流式更新时
+ * value.value = 'Hello '
+ * value.value = 'Hello World'
+ * loading.value = false
+ * ```
+ */
+export declare function createStreamableValue<T = unknown>(initialValue?: T): StreamableValue<T>;
+/**
+ * 组合使用 streamable value
+ *
+ * @example
+ * ```ts
+ * const streamable = createStreamableValue('')
+ * const displayValue = useStreamableValue(streamable)
+ * ```
+ */
+export declare function useStreamableValue<T>(streamable: StreamableValue<T>): {
+    value: import("vue").ComputedRef<T>;
+    loading: import("vue").ComputedRef<boolean>;
+    error: import("vue").ComputedRef<Error | null>;
+};
+/**
+ * 注册全局中间件
+ */
+export declare function registerMiddleware(middleware: AIMiddleware): () => void;
+/**
+ * 清理过期缓存
+ */
+export declare function clearCache(): void;
+/**
+ * XRequest - 增强版请求函数
+ *
+ * @example
+ * ```ts
+ * // 基础使用
+ * const result = await XRequest({
+ *   url: '/api/chat',
+ *   body: { messages: [{ role: 'user', content: '你好' }] }
+ * })
+ *
+ * // 流式使用
+ * XRequest({
+ *   url: '/api/chat/stream',
+ *   body: { messages: [{ role: 'user', content: '你好' }] },
+ *   stream: true,
+ *   callbacks: {
+ *     onChunk: (chunk) => console.log('收到:', chunk),
+ *     onFinish: (content) => console.log('完成:', content)
+ *   }
+ * })
+ * ```
+ */
+export declare function XRequest(config: XRequestConfig, callbacks?: XRequestCallbacks, options?: {
+    middlewares?: AIMiddleware[];
+    cache?: CacheConfig;
+    retry?: RetryConfig;
+}): Promise<unknown>;
+/**
+ * 创建 XRequest 实例 (可复用的配置)
+ */
+export declare function createXRequest(defaultConfig?: Partial<XRequestConfig>, defaultOptions?: {
+    middlewares?: AIMiddleware[];
+    cache?: CacheConfig;
+    retry?: RetryConfig;
+}): (config: XRequestConfig, callbacks?: XRequestCallbacks) => Promise<unknown>;
+/**
+ * 对话历史管理
+ *
+ * @example
+ * ```ts
+ * const { messages, addMessage, clearHistory, loadHistory } = useConversation()
+ *
+ * // 添加消息
+ * addMessage({ role: 'user', content: 'Hello' })
+ *
+ * // 获取历史
+ * console.log(messages.value)
+ * ```
+ */
+export declare function useConversation(config?: ConversationConfig): {
+    messages: Ref<{
+        id: string;
+        role: "user" | "assistant" | "system" | "tool";
+        content: string;
+        name?: string | undefined;
+        toolCallId?: string | undefined;
+        toolCalls?: {
+            id: string;
+            type: "function";
+            name: string;
+            arguments: Record<string, unknown>;
+        }[] | undefined;
+        createdAt?: Date | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[], ConversationMessage[] | {
+        id: string;
+        role: "user" | "assistant" | "system" | "tool";
+        content: string;
+        name?: string | undefined;
+        toolCallId?: string | undefined;
+        toolCalls?: {
+            id: string;
+            type: "function";
+            name: string;
+            arguments: Record<string, unknown>;
+        }[] | undefined;
+        createdAt?: Date | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[]>;
+    addMessage: (message: Omit<ConversationMessage, "id" | "createdAt">) => ConversationMessage;
+    clearHistory: () => void;
+    loadHistory: () => void;
+    saveHistory: () => void;
+};
+/**
+ * 多会话管理 Hook
+ *
+ * @example
+ * ```ts
+ * const {
+ *   conversations,    // 会话列表
+ *   currentId,        // 当前会话 ID
+ *   currentMessages,  // 当前会话消息
+ *   create,           // 创建会话
+ *   remove,           // 删除会话
+ *   select,           // 切换会话
+ *   updateTitle       // 更新标题
+ * } = useConversations({
+ *   maxConversations: 50,
+ *   persist: true,
+ *   autoTitle: true
+ * })
+ * ```
+ */
+export declare function useConversations(options?: UseConversationsOptions): {
+    conversations: Ref<{
+        id: string;
+        title: string;
+        messages: {
+            id: string;
+            role: "user" | "assistant" | "system" | "tool";
+            content: string;
+            name?: string | undefined;
+            toolCallId?: string | undefined;
+            toolCalls?: {
+                id: string;
+                type: "function";
+                name: string;
+                arguments: Record<string, unknown>;
+            }[] | undefined;
+            createdAt?: Date | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }[];
+        createdAt: Date;
+        updatedAt: Date;
+        metadata?: Record<string, unknown> | undefined;
+    }[], Conversation[] | {
+        id: string;
+        title: string;
+        messages: {
+            id: string;
+            role: "user" | "assistant" | "system" | "tool";
+            content: string;
+            name?: string | undefined;
+            toolCallId?: string | undefined;
+            toolCalls?: {
+                id: string;
+                type: "function";
+                name: string;
+                arguments: Record<string, unknown>;
+            }[] | undefined;
+            createdAt?: Date | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }[];
+        createdAt: Date;
+        updatedAt: Date;
+        metadata?: Record<string, unknown> | undefined;
+    }[]>;
+    currentId: Ref<string | null, string | null>;
+    currentConversation: import("vue").ComputedRef<{
+        id: string;
+        title: string;
+        messages: {
+            id: string;
+            role: "user" | "assistant" | "system" | "tool";
+            content: string;
+            name?: string | undefined;
+            toolCallId?: string | undefined;
+            toolCalls?: {
+                id: string;
+                type: "function";
+                name: string;
+                arguments: Record<string, unknown>;
+            }[] | undefined;
+            createdAt?: Date | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }[];
+        createdAt: Date;
+        updatedAt: Date;
+        metadata?: Record<string, unknown> | undefined;
+    } | null>;
+    currentMessages: import("vue").ComputedRef<{
+        id: string;
+        role: "user" | "assistant" | "system" | "tool";
+        content: string;
+        name?: string | undefined;
+        toolCallId?: string | undefined;
+        toolCalls?: {
+            id: string;
+            type: "function";
+            name: string;
+            arguments: Record<string, unknown>;
+        }[] | undefined;
+        createdAt?: Date | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[]>;
+    create: (initialMessages?: ConversationMessage[]) => string;
+    remove: (id: string) => void;
+    select: (id: string) => void;
+    updateTitle: (id: string, title: string) => void;
+    addMessage: (message: Omit<ConversationMessage, "id" | "createdAt">) => ConversationMessage | null;
+    clearCurrent: () => void;
+};
+export interface UseAIChatOptions {
+    /** API 端点 */
+    api: string;
+    /** 初始消息 */
+    initialMessages?: ConversationMessage[];
+    /** 请求头 */
+    headers?: Record<string, string>;
+    /** Body 额外参数 */
+    body?: Record<string, unknown>;
+    /** 是否流式 */
+    stream?: boolean;
+    /** 流式间隔 (ms) */
+    streamInterval?: number;
+    /** 工具定义 */
+    tools?: ToolCallHandler[];
+    /** 回调：发送前 */
+    onRequest?: (message: string) => void;
+    /** 回调：收到响应头 */
+    onResponse?: (response: Response) => void;
+    /** 回调：收到每个 chunk (流式) */
+    onChunk?: (chunk: string, message?: ConversationMessage) => void;
+    /** 回调：工具调用 */
+    onToolCall?: (toolCall: {
+        name: string;
+        args: Record<string, unknown>;
+    }) => void;
+    /** 回调：工具调用结果 */
+    onToolResult?: (toolName: string, result: unknown) => void;
+    /** 回调：完成 */
+    onFinish?: (message: ConversationMessage) => void;
+    /** 回调：出错 */
+    onError?: (error: Error) => void;
+}
+export interface UseAIChatReturn {
+    /** 消息列表 */
+    messages: Ref<ConversationMessage[]>;
+    /** 输入内容 */
+    input: Ref<string>;
+    /** 是否正在加载 */
+    isLoading: Ref<boolean>;
+    /** 是否正在流式 */
+    isStreaming: Ref<boolean>;
+    /** 错误 */
+    error: Ref<Error | null>;
+    /** 当前消息 (流式时) */
+    currentMessage: Ref<ConversationMessage | null>;
+    /** 发送消息 */
+    sendMessage: (content: string) => Promise<void>;
+    /** 流式发送 (带增量更新) */
+    sendMessageStream: (content: string) => Promise<void>;
+    /** 停止流式 */
+    stop: () => void;
+    /** 追加内容（用于流式） */
+    append: (content: string, role?: 'user' | 'assistant') => ConversationMessage;
+    /** 更新最后一条消息 */
+    updateLastMessage: (updates: Partial<ConversationMessage>) => void;
+    /** 重置 */
+    reload: () => void;
+}
+/**
+ * AI 对话 hook (增强版)
+ *
+ * @example
+ * ```ts
+ * // 基础对话
+ * const { messages, input, isLoading, sendMessage } = useAIChat({
+ *   api: '/api/chat',
+ *   onFinish: (msg) => console.log('完成:', msg.content)
+ * })
+ *
+ * // 流式对话
+ * const { messages, isStreaming, currentMessage, sendMessageStream, stop } = useAIChat({
+ *   api: '/api/chat/stream',
+ *   stream: true,
+ *   onChunk: (chunk, msg) => console.log('收到:', chunk),
+ *   onFinish: (msg) => console.log('完成:', msg.content)
+ * })
+ *
+ * // 工具调用
+ * const { messages, sendMessage } = useAIChat({
+ *   api: '/api/chat',
+ *   tools: [
+ *     {
+ *       name: 'get_weather',
+ *       description: '获取天气',
+ *       parameters: { city: { type: 'string' } },
+ *       execute: async ({ city }) => ({ temp: 25, weather: 'sunny' })
+ *     }
+ *   ],
+ *   onToolCall: (tc) => console.log('调用工具:', tc.name),
+ *   onToolResult: (name, result) => console.log('工具结果:', result)
+ * })
+ * ```
+ */
+export declare function useAIChat(options: UseAIChatOptions): UseAIChatReturn;
+export interface UseAIStreamOptions {
+    /** 流式 API 端点 */
+    api: string;
+    /** 初始内容 */
+    initialContent?: string;
+    /** 回调：每个 chunk */
+    onChunk?: (chunk: string) => void;
+    /** 回调：完成 */
+    onFinish?: (fullContent: string) => void;
+    /** 回调：出错 */
+    onError?: (error: Error) => void;
+}
+export interface UseAIStreamReturn {
+    /** 当前内容 */
+    content: Ref<string>;
+    /** 是否正在流式 */
+    isStreaming: Ref<boolean>;
+    /** 错误 */
+    error: Ref<Error | null>;
+    /** 开始流式请求 */
+    start: (prompt: string) => Promise<void>;
+    /** 停止 */
+    stop: () => void;
+}
+/**
+ * 流式文本生成 hook
+ *
+ * @example
+ * ```ts
+ * const { content, isStreaming, start, stop } = useAIStream({
+ *   api: '/api/chat/stream',
+ *   onChunk: (chunk) => console.log('收到:', chunk),
+ *   onFinish: (text) => console.log('完成:', text)
+ * })
+ *
+ * await start('请介绍一下 Vue 3')
+ * ```
+ */
+export declare function useAIStream(options: UseAIStreamOptions): UseAIStreamReturn;
+/**
+ * 创建 AI 函数工具
+ *
+ * @example
+ * ```ts
+ * const weatherTool = createYHFunctionTool({
+ *   name: 'get_weather',
+ *   description: '获取指定城市的天气',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: {
+ *       city: { type: 'string', description: '城市名称' }
+ *     },
+ *     required: ['city']
+ *   },
+ *   execute: async ({ city }) => {
+ *     return `当前${city}天气晴朗，25°C`
+ *   }
+ * })
+ * ```
+ */
+export declare function createYHFunctionTool<_T extends Record<string, unknown> = Record<string, unknown>>(tool: ToolCallHandler): {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (args: Record<string, unknown>) => Promise<unknown>;
+};
+/**
+ * Provider 预设配置
+ */
+export interface ProviderPreset {
+    name: string;
+    baseUrl: string;
+    defaultModel: string;
+    supportsStreaming?: boolean;
+    supportsFunctionCalling?: boolean;
+    needsProjectId?: boolean;
+}
+/**
+ * 内置 Provider 预设
+ */
+export declare const PROVIDER_PRESETS: Record<string, ProviderPreset>;
+/**
+ * 获取 Provider 预设
+ */
+export declare function getProviderPreset(name: string): ProviderPreset | undefined;
+/**
+ * 创建 AI Provider 适配器
+ *
+ * @example
+ * ```ts
+ * // 使用预设
+ * const openai = createProviderAdapter({
+ *   provider: 'openai',
+ *   apiKey: process.env.OPENAI_API_KEY
+ * })
+ *
+ * // 自定义配置
+ * const openai = createProviderAdapter({
+ *   name: 'openai',
+ *   baseUrl: 'https://api.openai.com/v1',
+ *   apiKey: process.env.OPENAI_API_KEY,
+ *   defaultModel: 'gpt-4'
+ * })
+ * ```
+ */
+export declare function createProviderAdapter(config: ProviderAdapter | {
+    provider: string;
+    apiKey?: string;
+}): ProviderAdapter & {
+    createChat: (model?: string | ModelConfig) => unknown;
+    preset?: ProviderPreset;
+};
+/**
+ * 创建带 Vercel AI SDK 的 Provider 适配器
+ *
+ * @example
+ * ```ts
+ * import { createVercelAIProvider } from '@yh-ui/ai-sdk'
+ * import { openai } from '@ai-sdk/openai'
+ *
+ * const provider = createVercelAIProvider(openai, {
+ *   baseURL: 'https://api.openai.com/v1'
+ * })
+ * ```
+ */
+export declare function createVercelAIProvider(provider: unknown, config?: {
+    baseURL?: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+}): {
+    languageModel: (modelId: string) => {
+        provider: unknown;
+        modelId: string;
+        config: {
+            baseURL?: string;
+            apiKey?: string;
+            headers?: Record<string, string>;
+        } | undefined;
+    };
+};
+export interface AIContextValue {
+    /** 当前会话 ID */
+    sessionId: Ref<string | null>;
+    /** 提供者配置 */
+    provider: Ref<ProviderAdapter | null>;
+    /** 模型配置 */
+    modelConfig: Ref<ModelConfig>;
+    /** 设置会话 */
+    setSession: (id: string) => void;
+    /** 设置提供者 */
+    setProvider: (provider: ProviderAdapter) => void;
+    /** 设置模型 */
+    setModel: (config: ModelConfig) => void;
+}
+declare const AIContextKey: unique symbol;
+/**
+ * 创建 AI 上下文（供 provide/inject 使用）
+ */
+export declare function createAIContext(initialProvider?: ProviderAdapter, initialModel?: string): AIContextValue;
+export { AIContextKey };