@yh-ui/hooks 0.1.10 → 0.1.15

package/dist/index.d.cts

@@ -73,17 +73,14 @@ type UseZIndexReturn = ReturnType<typeof useZIndex>;
 declare const getDayjsLocale: (localeCode: string) => string;
 /**
  * 动态加载并设置 dayjs locale
- * 使用动态导入来按需加载，避免打包所有语言
  */
 declare const setDayjsLocale: (localeCode: string) => Promise<void>;
 /**
- * 同步设置 dayjs locale（不推荐，会阻塞）
- * 用于需要立即同步的场景
+ * 同步设置 dayjs locale（立即生效，异步加载后会更新）
  */
 declare const setDayjsLocaleSync: (localeCode: string) => void;
 /**
  * 使用自定义月份名称更新 dayjs locale
- * 这样可以确保 dayjs 使用我们语言包中定义的月份名称
  */
 declare const updateDayjsMonths: (localeCode: string, months: {
     jan: string;
@@ -149,7 +146,7 @@ interface FormContext {
     layout?: string;
     addField: (field: FormItemContext) => void;
     removeField: (field: FormItemContext) => void;
-    themeOverrides?: Record<string, unknown>;
+    themeOverrides?: Record<string, string | undefined>;
 }
 interface FormItemContext {
     prop: string;
@@ -255,5 +252,448 @@ declare const useConfig: () => {
     globalLocale: ComputedRef<Language | undefined>;
 };
 
-export { FormContextKey, FormItemContextKey, configProviderContextKey, createZIndexCounter, defaultNamespace, getDayjsLocale, getNextZIndex, idInjectionKey, namespaceContextKey, resetZIndex, setDayjsLocale, setDayjsLocaleSync, updateDayjsMonths, useCache, useClickOutside, useConfig, useEventListener, useFormItem, useGlobalNamespace, useId, useIdInjection, useLocale, useNamespace, useScrollLock, useVirtualScroll, useZIndex, zIndexContextKey, zIndexCounterKey };
-export type { ConfigProviderContext, FormContext, FormItemContext, UseCacheReturn, UseFormItemReturn, UseIdReturn, UseLocaleReturn, UseNamespaceReturn, UseZIndexReturn, VirtualScrollOptions, VirtualScrollReturn };
+type StreamChunkParser = (raw: string) => string | null;
+/**
+ * OpenAI / DeepSeek 格式解析器
+ * data: {"choices":[{"delta":{"content":"hello"}}]}
+ */
+declare const openaiParser: StreamChunkParser;
+/**
+ * 文心一言 / ERNIE 格式解析器
+ * data: {"result":"hello","is_end":false}
+ */
+declare const ernieParser: StreamChunkParser;
+/**
+ * 通义千问 / Qwen 格式解析器
+ * data: {"output":{"text":"hello"},"finish_reason":null}
+ */
+declare const qwenParser: StreamChunkParser;
+/**
+ * Anthropic / Claude 格式解析器
+ * data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"hello"}}
+ */
+declare const claudeParser: StreamChunkParser;
+/**
+ * Google / Gemini 格式解析器
+ * data: {"candidates":[{"content":{"parts":[{"text":"hello"}]}}]}
+ */
+declare const geminiParser: StreamChunkParser;
+/**
+ * 纯文本流解析器（AsyncGenerator 输出的原始字符串）
+ */
+declare const plainTextParser: StreamChunkParser;
+interface AiStreamOptions {
+    /**
+     * 请求适配器，返回 AsyncGenerator 或 fetch Response
+     */
+    request: (query: string, ...args: unknown[]) => Promise<Response | AsyncGenerator<string, void, unknown>> | AsyncGenerator<string, void, unknown>;
+    /**
+     * 流式块解析器，用于适配不同厂商的格式
+     * @default plainTextParser（直接输出原始字符串）
+     */
+    parser?: StreamChunkParser;
+    /**
+     * 是否启用打字机平滑节流效果
+     * @default true
+     */
+    typewriter?: boolean;
+    /**
+     * 每帧渲染的字符数（打字机速度控制）
+     * @default 3
+     */
+    charsPerFrame?: number;
+    onUpdate?: (chunk: string, fullContent: string) => void;
+    onFinish?: (content: string) => void;
+    onError?: (err: Error) => void;
+}
+/**
+ * useAiStream - 多厂商兼容流式请求引擎
+ *
+ * 特性：
+ * - 支持 OpenAI / DeepSeek / 文心一言 / 通义千问 等主流格式（Adapter 模式）
+ * - 内置 rAF 打字机节流，保证平滑输出体验
+ * - 完整的 AbortController 取消支持
+ */
+declare function useAiStream(options: AiStreamOptions): {
+    isStreaming: vue.Ref<boolean, boolean>;
+    currentContent: vue.Ref<string, string>;
+    fetchStream: (query: string, ...args: unknown[]) => Promise<void>;
+    stop: () => void;
+    parsers: {
+        openaiParser: StreamChunkParser;
+        ernieParser: StreamChunkParser;
+        qwenParser: StreamChunkParser;
+        claudeParser: StreamChunkParser;
+        geminiParser: StreamChunkParser;
+        plainTextParser: StreamChunkParser;
+    };
+};
+
+interface AiChatMessage {
+    /** 唯一标识，避免使用 index 做 key */
+    id: string;
+    /** 消息发送方 */
+    role: 'user' | 'assistant' | 'system';
+    /** 消息内容 */
+    content: string;
+    /**
+     * 消息状态
+     * - loading: 初始加载中（占位）
+     * - generating: 流式生成中
+     * - success: 已成功完成
+     * - error: 发生错误
+     * - stopped: 被用户中途打断
+     */
+    status?: 'loading' | 'generating' | 'success' | 'error' | 'stopped';
+    /** 消息时间戳（ms） */
+    createAt: number;
+    /** 用于展示的时间字符串（可选，不传则自动格式化） */
+    time?: string;
+    /** 扩展字段 */
+    [key: string]: unknown;
+}
+interface UseAiChatOptions {
+    /** 初始化的消息列表 */
+    initialMessages?: AiChatMessage[];
+    /** 自定义生成 ID 的函数 */
+    idGenerator?: () => string;
+    /**
+     * 请求适配器
+     * 支持：
+     * - AsyncGenerator<string>：最原始的字符流，每次 yield 一段字符
+     * - Promise<string>：直接返回完整回复
+     * - Promise<Response>：SSE 流式响应
+     */
+    request?: (message: string, history: AiChatMessage[], abortSignal: AbortSignal) => AsyncGenerator<string, void, unknown> | Promise<string | Response>;
+    /**
+     * SSE / 流式块的解析器（适配不同厂商格式）
+     * 传入各厂商对应的 parser（来自 useAiStream 模块）
+     * @default plainTextParser
+     */
+    parser?: StreamChunkParser;
+    /**
+     * 是否启用打字机平滑输出效果
+     * @default true
+     */
+    typewriter?: boolean;
+    /**
+     * 打字机每帧输出字符数（越大越快）
+     * @default 3
+     */
+    charsPerFrame?: number;
+    /**
+     * 系统 Prompt（会自动插入到历史的首位）
+     */
+    systemPrompt?: string;
+    /** 出现错误时的回调 */
+    onError?: (err: Error) => void;
+    /** 消息发送完成回调 */
+    onFinish?: (message: AiChatMessage) => void;
+}
+/**
+ * useAiChat - 核心 AI 会话管理 Hook
+ *
+ * 特性：
+ * - 消息列表 CRUD + 状态机管理
+ * - 支持流式 / 非流式响应
+ * - 内置多厂商适配器接口（通过 parser 选项传入）
+ * - rAF 打字机平滑效果（可关闭）
+ * - 完整的 AbortController 取消支持
+ * - 系统 Prompt 自动注入
+ */
+declare function useAiChat(options?: UseAiChatOptions): {
+    /** 会话历史 */
+    messages: vue.Ref<{
+        [x: string]: unknown;
+        id: string;
+        role: "user" | "assistant" | "system";
+        content: string;
+        status?: "loading" | "generating" | "success" | "error" | "stopped"
+        /** 消息时间戳（ms） */
+         | undefined;
+        createAt: number;
+        time?: string
+        /** 扩展字段 */
+         | undefined;
+    }[], AiChatMessage[] | {
+        [x: string]: unknown;
+        id: string;
+        role: "user" | "assistant" | "system";
+        content: string;
+        status?: "loading" | "generating" | "success" | "error" | "stopped"
+        /** 消息时间戳（ms） */
+         | undefined;
+        createAt: number;
+        time?: string
+        /** 扩展字段 */
+         | undefined;
+    }[]>;
+    /** 是否正在生成（等同 isSending，别名友好） */
+    isGenerating: vue.Ref<boolean, boolean>;
+    /** 同 isGenerating，语义别名 */
+    isSending: vue.ComputedRef<boolean>;
+    /** 触发发送（自动处理流、打字机） */
+    sendMessage: (content: string) => Promise<void>;
+    /** 停止/中断当前生成 */
+    stop: () => void;
+    /** 移除单条消息 */
+    removeMessage: (id: string) => void;
+    /** 修改单条消息内容 */
+    updateMessage: (id: string, patch: Partial<AiChatMessage>) => void;
+    /** 重置清空所有会话 */
+    clear: () => void;
+};
+
+interface AiConversation {
+    id: string;
+    title: string;
+    /**
+     * 最近更新时间（时间戳 ms）
+     */
+    updatedAt: number;
+    /**
+     * 对话预览/最后一条消息内容
+     */
+    excerpt?: string;
+    /**
+     * 是否置顶
+     */
+    pinned?: boolean;
+    /**
+     * 自定义数据（例如知识库 ID 等业务数据）
+     */
+    meta?: Record<string, unknown>;
+}
+interface StorageAdapter {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/**
+ * localStorage 适配器（默认）
+ */
+declare const localStorageAdapter: StorageAdapter;
+/**
+ * IndexedDB 适配器（适合大量数据持久化）
+ */
+declare class IndexedDBAdapter implements StorageAdapter {
+    private db;
+    private dbName;
+    private storeName;
+    private ready;
+    constructor(dbName?: string);
+    private init;
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+type ConversationGroup = {
+    label: string;
+    items: AiConversation[];
+};
+interface UseAiConversationsOptions {
+    /** 初始化数据（或从后端的直出） */
+    initialConversations?: AiConversation[];
+    /** 自定义生成 ID 的函数 */
+    idGenerator?: () => string;
+    /**
+     * 持久化存储适配器
+     * - false: 不持久化（仅内存）
+     * - 'localStorage': 使用 localStorage（默认）
+     * - 'indexedDB': 使用 IndexedDB
+     * - StorageAdapter: 自定义适配器
+     */
+    storage?: false | 'localStorage' | 'indexedDB' | StorageAdapter;
+    /** 持久化 key 前缀 */
+    storageKey?: string;
+    /**
+     * 每次加载的数量（用于分页 / 懒加载）
+     * @default 20
+     */
+    pageSize?: number;
+}
+/**
+ * useAiConversations - 会话历史管理 Hook
+ *
+ * 特性：
+ * - 完整的 CRUD + 置顶操作
+ * - 可插拔持久化（localStorage / IndexedDB / 自定义）
+ * - 按时间自动分组（今天 / 最近 7 天 / 最近 30 天 / 更早）
+ * - 分页懒加载
+ */
+declare function useAiConversations(options?: UseAiConversationsOptions): {
+    /** 完整会话列表 */
+    conversations: vue.Ref<{
+        id: string;
+        title: string;
+        updatedAt: number;
+        excerpt?: string
+        /**
+         * 是否置顶
+         */
+         | undefined;
+        pinned?: boolean
+        /**
+         * 自定义数据（例如知识库 ID 等业务数据）
+         */
+         | undefined;
+        meta?: Record<string, unknown> | undefined;
+    }[], AiConversation[] | {
+        id: string;
+        title: string;
+        updatedAt: number;
+        excerpt?: string
+        /**
+         * 是否置顶
+         */
+         | undefined;
+        pinned?: boolean
+        /**
+         * 自定义数据（例如知识库 ID 等业务数据）
+         */
+         | undefined;
+        meta?: Record<string, unknown> | undefined;
+    }[]>;
+    /** 按时间分组后的列表（置顶 / 今天 / 最近 7 天 / 更早） */
+    groupedConversations: vue.ComputedRef<ConversationGroup[]>;
+    /** 分页后的列表 */
+    pagedConversations: vue.ComputedRef<{
+        id: string;
+        title: string;
+        updatedAt: number;
+        excerpt?: string
+        /**
+         * 是否置顶
+         */
+         | undefined;
+        pinned?: boolean
+        /**
+         * 自定义数据（例如知识库 ID 等业务数据）
+         */
+         | undefined;
+        meta?: Record<string, unknown> | undefined;
+    }[]>;
+    /** 是否还有更多数据 */
+    hasMore: vue.ComputedRef<boolean>;
+    /** 加载更多 */
+    loadMore: () => Promise<void>;
+    /** 加载更多状态 */
+    isLoadingMore: vue.Ref<boolean, boolean>;
+    /** 等待初始化完成（SSR 场景使用） */
+    ready: Promise<void>;
+    /** 新建会话 */
+    createConversation: (title: string, meta?: Record<string, unknown>) => Promise<AiConversation>;
+    /** 删除会话 */
+    removeConversation: (id: string) => Promise<void>;
+    /** 更新会话属性 */
+    updateConversation: (id: string, updates: Partial<Omit<AiConversation, "id">>) => Promise<void>;
+    /** 置顶/取消置顶 */
+    pinConversation: (id: string, pinned?: boolean) => Promise<void>;
+    /** 清空全部 */
+    clear: () => Promise<void>;
+};
+
+interface AiRequestOptions {
+    /**
+     * 请求函数
+     */
+    request: (query: string, ...args: unknown[]) => Promise<string> | string;
+    onSuccess?: (content: string) => void;
+    onError?: (err: Error) => void;
+}
+/**
+ * useAiRequest - 简单的 AI 非流式请求 Hook
+ */
+declare function useAiRequest(options: AiRequestOptions): {
+    loading: vue.Ref<boolean, boolean>;
+    data: vue.Ref<string, string>;
+    error: vue.Ref<Error | null, Error | null>;
+    send: (query: string, ...args: unknown[]) => Promise<string>;
+};
+
+interface UseAiVoiceOptions {
+    /**
+     * 语言代码 (用于 SpeechRecognition)
+     * @default 'zh-CN'
+     */
+    language?: string;
+    /**
+     * 是否需要临时结果（在说话过程中实时返回）
+     * @default true
+     */
+    interimResults?: boolean;
+    /**
+     * 是否连续识别
+     * @default false
+     */
+    continuous?: boolean;
+    /**
+     * 智能静音检测（VAD）
+     * 开启后，当检测到长时间无声会自动停止录音
+     * @default true
+     */
+    vad?: boolean;
+    /**
+     * 静音检测阈值 (ms)
+     * @default 2000
+     */
+    vadThreshold?: number;
+    /**
+     * 音量变化敏感度 (0-1)
+     * @default 0.05
+     */
+    volumeThreshold?: number;
+    /**
+     * 返回波形柱的数量（对应 AiVoiceTrigger 的 amplitudes）
+     * @default 20
+     */
+    waveCount?: number;
+    /**
+     * 是否在开始时自动执行浏览器语音识别 (SpeechRecognition)
+     * 如果关闭，则只进行物理音频录制
+     * @default true
+     */
+    useSTT?: boolean;
+    /** 回调事件 */
+    onStart?: () => void;
+    /** 停止回调，包含最终转写文本和录音文件 Blob */
+    onStop?: (transcript: string, blob: Blob | null) => void;
+    onResult?: (transcript: string) => void;
+    onPartialResult?: (transcript: string) => void;
+    onError?: (error: unknown) => void;
+}
+interface UseAiVoiceReturn {
+    /** 是否正在录音 */
+    isRecording: vue.Ref<boolean>;
+    /** 最终转写文本 */
+    transcript: vue.Ref<string>;
+    /** 过程中的临时文本 */
+    interimTranscript: vue.Ref<string>;
+    /** 实时波形数据 */
+    amplitudes: vue.Ref<number[]>;
+    /** 实时音量 (0-100) */
+    volume: vue.Ref<number>;
+    /** 录音文件的 Blob */
+    audioBlob: vue.Ref<Blob | null>;
+    /** 开始录音 */
+    start: () => Promise<void>;
+    /** 停止录音 */
+    stop: () => void;
+    /** 取消并放弃当前结果 */
+    cancel: () => void;
+    /** 浏览器是否支持 SpeechRecognition (用于显示警告) */
+    sttSupported: boolean;
+}
+/**
+ * useAiVoice - 专业级 AI 语音交互 Hook
+ *
+ * 核心能力：
+ * 1. 【音频录制】：通过 MediaRecorder 真实录制音频并导出 Blob 文件。
+ * 2. 【视觉分析】：通过 Web Audio API 实时输出驱动 AiVoiceTrigger 的波形数组。
+ * 3. 【智能 VAD】：多维检测静音状态，支持自动停顿结束。
+ * 4. 【语音转写】：内置 Web Speech API 实时转写及临时结果反馈。
+ */
+declare function useAiVoice(options?: UseAiVoiceOptions): UseAiVoiceReturn;
+
+export { FormContextKey, FormItemContextKey, IndexedDBAdapter, claudeParser, configProviderContextKey, createZIndexCounter, defaultNamespace, ernieParser, geminiParser, getDayjsLocale, getNextZIndex, idInjectionKey, localStorageAdapter, namespaceContextKey, openaiParser, plainTextParser, qwenParser, resetZIndex, setDayjsLocale, setDayjsLocaleSync, updateDayjsMonths, useAiChat, useAiConversations, useAiRequest, useAiStream, useAiVoice, useCache, useClickOutside, useConfig, useEventListener, useFormItem, useGlobalNamespace, useId, useIdInjection, useLocale, useNamespace, useScrollLock, useVirtualScroll, useZIndex, zIndexContextKey, zIndexCounterKey };
+export type { AiChatMessage, AiConversation, AiRequestOptions, AiStreamOptions, ConfigProviderContext, ConversationGroup, FormContext, FormItemContext, StorageAdapter, StreamChunkParser, UseAiChatOptions, UseAiConversationsOptions, UseAiVoiceOptions, UseAiVoiceReturn, UseCacheReturn, UseFormItemReturn, UseIdReturn, UseLocaleReturn, UseNamespaceReturn, UseZIndexReturn, VirtualScrollOptions, VirtualScrollReturn };