@yh-ui/hooks 0.1.10 → 0.1.12

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,334 @@ 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;
+/**
+ * 纯文本流解析器（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;
+        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>;
+};
+
+export { FormContextKey, FormItemContextKey, IndexedDBAdapter, configProviderContextKey, createZIndexCounter, defaultNamespace, ernieParser, getDayjsLocale, getNextZIndex, idInjectionKey, localStorageAdapter, namespaceContextKey, openaiParser, plainTextParser, qwenParser, resetZIndex, setDayjsLocale, setDayjsLocaleSync, updateDayjsMonths, useAiChat, useAiConversations, useAiStream, useCache, useClickOutside, useConfig, useEventListener, useFormItem, useGlobalNamespace, useId, useIdInjection, useLocale, useNamespace, useScrollLock, useVirtualScroll, useZIndex, zIndexContextKey, zIndexCounterKey };
+export type { AiChatMessage, AiConversation, AiStreamOptions, ConfigProviderContext, ConversationGroup, FormContext, FormItemContext, StorageAdapter, StreamChunkParser, UseAiChatOptions, UseAiConversationsOptions, UseCacheReturn, UseFormItemReturn, UseIdReturn, UseLocaleReturn, UseNamespaceReturn, UseZIndexReturn, VirtualScrollOptions, VirtualScrollReturn };