@unif/react-native-chat-sdk 0.6.0 → 1.0.0

package/src/hooks/useXChat.ts

@@ -1,11 +1,18 @@
 /**
- * useXChat — 聊天操作 hook
+ * useXChat — 聊天操作 Hook
  *
- * 消费 ChatProvider，输出可渲染的 messages 列表
+ * 支持 isRequesting / parser 消息展开 / defaultMessages 初始消息
  */
 
-import { useCallback, useEffect, useMemo, useSyncExternalStore } from 'react';
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+} from 'react';
 import { getOrCreateChatStore } from '../stores/chatStore';
+import type { StoreMessage } from '../stores/chatStore';
 import type { AbstractChatProvider } from '../providers/AbstractChatProvider';
 import type { ChatMessage, MessageStatus } from '../types/message';
 import type { RequestParams, SSEOutput } from '../types/provider';
@@ -25,6 +32,10 @@ export interface UseXChatConfig<
 > {
   conversationKey: string;
   provider: AbstractChatProvider<Message, Input, Output>;
+  /** 将单条消息解析为多条展示消息 */
+  parser?: (message: Message) => Message[];
+  /** 初始消息（同步数组或异步 Promise） */
+  defaultMessages?: Message[] | (() => Promise<Message[]>);
   requestPlaceholder?: (input: Input) => Message;
   requestFallback?: (input: Input, info: { error: Error }) => Message;
   generateId?: () => string;
@@ -35,7 +46,8 @@ export interface UseXChatReturn<
   Input = RequestParams<Message>,
 > {
   messages: MessageInfo<Message>[];
-  requesting: boolean;
+  /** 是否正在请求 */
+  isRequesting: boolean;
   suggestions: SuggestionItem[];
   error: string | null;
   onRequest: (input: Input) => void;
@@ -56,21 +68,47 @@ export interface UseXChatReturn<
   removeMessage: (id: string) => void;
 }
 
+/** 从 Message 中安全读取 status 字段 */
+function getStatus<M>(m: M): MessageStatus {
+  return ((m as Record<string, unknown>).status as MessageStatus) ?? 'local';
+}
+
+/** 从 Message 中安全读取 extra 字段 */
+function getExtra<M>(m: M): Record<string, unknown> | undefined {
+  return (m as Record<string, unknown>).extra as
+    | Record<string, unknown>
+    | undefined;
+}
+
 export function useXChat<
-  Message = ChatMessage,
+  Message extends StoreMessage = ChatMessage,
   Input = RequestParams<Message>,
   Output = SSEOutput,
 >(
   config: UseXChatConfig<Message, Input, Output>
 ): UseXChatReturn<Message, Input> {
-  const { provider, conversationKey } = config;
+  const { provider, conversationKey, parser, defaultMessages } = config;
+  const defaultMessagesLoadedRef = useRef(false);
 
   const store = useMemo(
-    () => getOrCreateChatStore(conversationKey),
+    () => getOrCreateChatStore<Message>(conversationKey),
     [conversationKey]
   );
 
-  // 使用 useSyncExternalStore 订阅 zustand store 变化
+  // 首次挂载时加载 defaultMessages
+  useEffect(() => {
+    if (!defaultMessages || defaultMessagesLoadedRef.current) return;
+    defaultMessagesLoadedRef.current = true;
+
+    if (Array.isArray(defaultMessages)) {
+      store.getState().setMessages(defaultMessages);
+    } else {
+      defaultMessages().then((msgs) => {
+        store.getState().setMessages(msgs);
+      });
+    }
+  }, [defaultMessages, store]);
+
   const state = useSyncExternalStore(
     store.subscribe,
     store.getState,
@@ -87,20 +125,21 @@ export function useXChat<
       store.getState().setSuggestions([]);
 
       const localMessage = provider.transformLocalMessage(input);
-      const localChatMessage = localMessage as unknown as ChatMessage;
-      store.getState().addMessage(localChatMessage);
+      store.getState().addMessage(localMessage);
 
-      // 注入 loading 占位消息（显示"正在思考"动画）
-      const loadingMessageId = `loading-${localChatMessage.id}`;
-      const loadingMessage: ChatMessage = {
+      // loading 占位消息：合成临时对象，收到首条响应后立即移除。
+      // 这里无法直接构造 Message 泛型实例，因此使用 unknown 中转，
+      // 这是整个 SDK 中唯一一处不可避免的类型断言。
+      const loadingMessageId = `loading-${localMessage.id}`;
+      const loadingMessage = {
         id: loadingMessageId,
         text: '',
         role: 'assistant',
         createdAt: new Date(),
         messageType: 'text',
-        status: 'loading',
-        turnId: localChatMessage.turnId,
-      };
+        status: 'loading' as MessageStatus,
+        turnId: (localMessage as Record<string, unknown>).turnId ?? '',
+      } as unknown as Message;
       store.getState().addMessage(loadingMessage);
 
       let loadingRemoved = false;
@@ -114,15 +153,13 @@ export function useXChat<
       provider.sendMessage(input, {
         onUpdate: (message) => {
           removeLoading();
-          store.getState().upsertMessage(message as unknown as ChatMessage);
+          store.getState().upsertMessage(message);
         },
         onSuccess: (message) => {
           removeLoading();
-          const m = message as unknown as ChatMessage;
-          store.getState().upsertMessage({
-            ...m,
-            status: 'success',
-          });
+          store
+            .getState()
+            .upsertMessage({ ...message, status: 'success' } as Message);
           store.getState().setRequesting(false);
         },
         onError: (error) => {
@@ -132,7 +169,7 @@ export function useXChat<
 
           if (config.requestFallback) {
             const fallbackMsg = config.requestFallback(input, { error });
-            store.getState().addMessage(fallbackMsg as unknown as ChatMessage);
+            store.getState().addMessage(fallbackMsg);
           }
         },
         onSuggestion: (items) => {
@@ -145,9 +182,8 @@ export function useXChat<
 
   const abort = useCallback(() => {
     provider.abort();
-    // 清理可能存在的 loading 占位消息
     const msgs = store.getState().messages;
-    const loadingMsg = msgs.find((m) => m.status === 'loading');
+    const loadingMsg = msgs.find((m) => getStatus(m) === 'loading');
     if (loadingMsg) {
       store.getState().removeMessage(loadingMsg.id);
     }
@@ -163,7 +199,6 @@ export function useXChat<
       const s = store.getState();
       if (s.isRequesting) return;
 
-      // 将目标消息标记为 loading，移除其后的 assistant 消息
       const targetIdx = s.messages.findIndex((m) => m.id === id);
       if (targetIdx < 0) return;
 
@@ -173,14 +208,12 @@ export function useXChat<
 
       provider.sendMessage(input, {
         onUpdate: (message) => {
-          store.getState().upsertMessage(message as unknown as ChatMessage);
+          store.getState().upsertMessage(message);
         },
         onSuccess: (message) => {
-          const m = message as unknown as ChatMessage;
-          store.getState().upsertMessage({
-            ...m,
-            status: 'success',
-          });
+          store
+            .getState()
+            .upsertMessage({ ...message, status: 'success' } as Message);
           store.getState().setRequesting(false);
         },
         onError: (error) => {
@@ -189,7 +222,7 @@ export function useXChat<
 
           if (config.requestFallback) {
             const fallbackMsg = config.requestFallback(input, { error });
-            store.getState().addMessage(fallbackMsg as unknown as ChatMessage);
+            store.getState().addMessage(fallbackMsg);
           }
         },
         onSuggestion: (items) => {
@@ -208,24 +241,11 @@ export function useXChat<
     ) => {
       if (typeof messagesOrFn === 'function') {
         const current = store.getState().messages;
-        const currentInfos: MessageInfo<Message>[] = current.map((m) => ({
-          id: m.id,
-          message: m as unknown as Message,
-          status: m.status,
-          extra: m.extra as Record<string, unknown> | undefined,
-        }));
+        const currentInfos = toMessageInfoList(current);
         const next = messagesOrFn(currentInfos);
-        store
-          .getState()
-          .setMessages(
-            next.map((info) => info.message as unknown as ChatMessage)
-          );
+        store.getState().setMessages(next.map((info) => info.message));
       } else {
-        store
-          .getState()
-          .setMessages(
-            messagesOrFn.map((info) => info.message as unknown as ChatMessage)
-          );
+        store.getState().setMessages(messagesOrFn.map((info) => info.message));
       }
     },
     [store]
@@ -241,18 +261,18 @@ export function useXChat<
       store.getState().setMessage(id, (m) => {
         const info: MessageInfo<Message> = {
           id: m.id,
-          message: m as unknown as Message,
-          status: m.status,
-          extra: m.extra as Record<string, unknown> | undefined,
+          message: m,
+          status: getStatus(m),
+          extra: getExtra(m),
         };
         const partial =
           typeof partialOrFn === 'function' ? partialOrFn(info) : partialOrFn;
-        const updated: Partial<ChatMessage> = {};
+        const updated: Partial<Message> = {};
         if (partial.message !== undefined) {
           Object.assign(updated, partial.message);
         }
         if (partial.status !== undefined) {
-          updated.status = partial.status;
+          (updated as Record<string, unknown>).status = partial.status;
         }
         return updated;
       });
@@ -273,16 +293,34 @@ export function useXChat<
     };
   }, [provider]);
 
-  const messages: MessageInfo<Message>[] = state.messages.map((m) => ({
-    id: m.id,
-    message: m as unknown as Message,
-    status: m.status,
-    extra: m.extra as Record<string, unknown> | undefined,
-  }));
+  // 应用 parser（一对多展开）
+  const messages = useMemo<MessageInfo<Message>[]>(() => {
+    const rawInfos = toMessageInfoList(state.messages);
+
+    if (!parser) return rawInfos;
+
+    const expanded: MessageInfo<Message>[] = [];
+    for (const info of rawInfos) {
+      const parsed = parser(info.message);
+      if (parsed.length === 0) continue;
+      if (parsed.length === 1) {
+        expanded.push({ ...info, message: parsed[0]! });
+      } else {
+        parsed.forEach((p, i) => {
+          expanded.push({
+            ...info,
+            id: `${info.id}-${i}`,
+            message: p,
+          });
+        });
+      }
+    }
+    return expanded;
+  }, [state.messages, parser]);
 
   return {
     messages,
-    requesting: state.isRequesting,
+    isRequesting: state.isRequesting,
     suggestions: state.suggestions,
     error: state.error,
     onRequest,
@@ -294,3 +332,15 @@ export function useXChat<
     removeMessage,
   };
 }
+
+/** store messages → MessageInfo 列表 */
+function toMessageInfoList<M extends StoreMessage>(
+  messages: M[]
+): MessageInfo<M>[] {
+  return messages.map((m) => ({
+    id: m.id,
+    message: m,
+    status: getStatus(m),
+    extra: getExtra(m),
+  }));
+}

package/src/index.ts

@@ -27,6 +27,8 @@ export type {
   RequestParams,
   SSEOutput,
   ProviderCallbacks,
+  TransformMessageInfo,
+  TransformParamsOptions,
 } from './types/provider';
 
 // Tools
@@ -47,6 +49,7 @@ export type { DeepSeekChatProviderConfig } from './providers/DeepSeekChatProvide
 
 // Stores
 export type { ChatStorage } from './stores/storage';
+export type { StoreMessage, ChatStoreApi } from './stores/chatStore';
 export {
   getOrCreateChatStore,
   deleteChatStore,

package/src/providers/AbstractChatProvider.ts

@@ -1,7 +1,7 @@
 /**
  * AbstractChatProvider — Provider 抽象基类
  *
- * 3 个抽象方法：transformParams / transformLocalMessage / transformMessage
+ * 定义 transformMessage / transformParams / transformLocalMessage 抽象方法
  */
 
 import type { XRequest, XRequestCallbacks } from '../tools/XRequest';
@@ -10,6 +10,8 @@ import type {
   RequestParams,
   SSEOutput,
   ProviderCallbacks,
+  TransformMessageInfo,
+  TransformParamsOptions,
 } from '../types/provider';
 
 export abstract class AbstractChatProvider<
@@ -25,9 +27,12 @@ export abstract class AbstractChatProvider<
 
   /**
    * 转换请求参数
-   * 将 useXChat.onRequest() 传入的参数转换为 XRequest 需要的格式
+   * 新签名：接收 options 参数（含 messages 等上下文）
    */
-  abstract transformParams(input: Input): Record<string, unknown>;
+  abstract transformParams(
+    input: Input,
+    options?: TransformParamsOptions<Message>
+  ): Record<string, unknown>;
 
   /**
    * 转换本地消息
@@ -37,9 +42,11 @@ export abstract class AbstractChatProvider<
 
   /**
    * 转换响应消息
-   * 将 XRequest 返回的流数据转换为 ChatMessage（用于 assistant 消息渲染）
+   * 新签名：接收 info 对象（含 output + current）
    */
-  abstract transformMessage(output: Output, current?: Message): Message;
+  abstract transformMessage(
+    info: TransformMessageInfo<Message, Output>
+  ): Message;
 
   /**
    * 发起请求（内部调用 XRequest）
@@ -50,10 +57,11 @@ export abstract class AbstractChatProvider<
 
     const requestCallbacks: XRequestCallbacks = {
       onStream: (chunk) => {
-        currentMessage = this.transformMessage(
-          chunk as unknown as Output,
-          currentMessage
-        );
+        // XRequest 回调类型是 SSEOutput，与 Output 泛型默认一致
+        currentMessage = this.transformMessage({
+          output: chunk as Output,
+          current: currentMessage,
+        });
         callbacks.onUpdate(currentMessage);
       },
       onSuccess: () => {

package/src/providers/DeepSeekChatProvider.ts

@@ -7,7 +7,7 @@
 
 import { OpenAIChatProvider } from './OpenAIChatProvider';
 import type { ChatMessage } from '../types/message';
-import type { SSEOutput } from '../types/provider';
+import type { SSEOutput, TransformMessageInfo } from '../types/provider';
 
 export interface DeepSeekChatProviderConfig {
   apiKey?: string;
@@ -28,11 +28,12 @@ export class DeepSeekChatProvider extends OpenAIChatProvider {
 
   /**
    * 覆写 transformMessage，处理 DeepSeek reasoning_content
+   * 新签名：info.output + info.current
    */
   override transformMessage(
-    output: SSEOutput,
-    current?: ChatMessage
+    info: TransformMessageInfo<ChatMessage, SSEOutput>
   ): ChatMessage {
+    const { output, current } = info;
     const raw = output.data;
 
     if (raw.trim() === '[DONE]') {
@@ -62,7 +63,6 @@ export class DeepSeekChatProvider extends OpenAIChatProvider {
 
       // 将 reasoning_content 映射为 <think> 标签包裹
       if (reasoningContent) {
-        // 如果还没有开始 think 标签，添加开始标签
         if (!prevText.includes('<think>')) {
           newText += '<think>';
         }
@@ -70,7 +70,6 @@ export class DeepSeekChatProvider extends OpenAIChatProvider {
       }
 
       if (content) {
-        // 如果有未关闭的 think 标签，先关闭
         if (newText.includes('<think>') && !newText.includes('</think>')) {
           newText += '</think>';
         }
@@ -96,7 +95,7 @@ export class DeepSeekChatProvider extends OpenAIChatProvider {
         turnId: current?.turnId ?? `turn-${Date.now()}`,
       };
     } catch {
-      return current ?? super.transformMessage(output, current);
+      return current ?? super.transformMessage(info);
     }
   }
 }

package/src/providers/OpenAIChatProvider.ts

@@ -7,7 +7,11 @@
 import { AbstractChatProvider } from './AbstractChatProvider';
 import { XRequest } from '../tools/XRequest';
 import type { ChatMessage, MessageStatus } from '../types/message';
-import type { RequestParams, SSEOutput } from '../types/provider';
+import type {
+  RequestParams,
+  SSEOutput,
+  TransformMessageInfo,
+} from '../types/provider';
 
 export interface OpenAIChatProviderConfig {
   baseURL: string;
@@ -82,8 +86,12 @@ export class OpenAIChatProvider extends AbstractChatProvider<
 
   /**
    * 将 SSE delta 转为 ChatMessage（累积 content）
+   * 新签名：info.output + info.current
    */
-  transformMessage(output: SSEOutput, current?: ChatMessage): ChatMessage {
+  transformMessage(
+    info: TransformMessageInfo<ChatMessage, SSEOutput>
+  ): ChatMessage {
+    const { output, current } = info;
     const raw = output.data;
 
     // OpenAI 结束标记

package/src/stores/chatStore.ts

@@ -1,64 +1,44 @@
 /**
  * Chat 消息状态管理（Zustand）
- * 内部 store，通过 useXChat hook 封装后对外暴露
+ *
+ * 泛型 store，通过 useXChat hook 封装后对外暴露。
+ * M 约束：必须包含 id 字段用于查找/去重。
  */
 
 import { create } from 'zustand';
-import type { ChatMessage } from '../types/message';
 import type { SuggestionItem } from '../types/sse';
 
-interface ChatState {
-  messages: ChatMessage[];
-  streamingText: string;
+/** store 中消息的最小约束：必须有 id 用于查找/去重 */
+export interface StoreMessage {
+  id: string;
+}
+
+interface ChatState<M extends StoreMessage> {
+  messages: M[];
   suggestions: SuggestionItem[];
   isRequesting: boolean;
   error: string | null;
 
-  addMessage: (message: ChatMessage) => void;
-  updateMessage: (
-    id: string,
-    updater: (msg: ChatMessage) => ChatMessage
-  ) => void;
-  upsertMessage: (message: ChatMessage) => void;
-  setMessages: (
-    messages: ChatMessage[] | ((prev: ChatMessage[]) => ChatMessage[])
-  ) => void;
+  addMessage: (message: M) => void;
+  updateMessage: (id: string, updater: (msg: M) => M) => void;
+  upsertMessage: (message: M) => void;
+  setMessages: (messages: M[] | ((prev: M[]) => M[])) => void;
   setMessage: (
     id: string,
-    partial: Partial<ChatMessage> | ((msg: ChatMessage) => Partial<ChatMessage>)
+    partial: Partial<M> | ((msg: M) => Partial<M>)
   ) => void;
   removeMessage: (id: string) => void;
   setSuggestions: (items: SuggestionItem[]) => void;
   setRequesting: (v: boolean) => void;
   setError: (error: string | null) => void;
   resetChat: () => void;
-  loadSession: (messages: ChatMessage[]) => void;
-}
-
-// 全局 store 管理器 — 多会话内存常驻
-const chatStoreMap = new Map<string, ReturnType<typeof createChatStore>>();
-
-export function getOrCreateChatStore(key: string) {
-  let store = chatStoreMap.get(key);
-  if (!store) {
-    store = createChatStore();
-    chatStoreMap.set(key, store);
-  }
-  return store;
-}
-
-export function deleteChatStore(key: string) {
-  chatStoreMap.delete(key);
-}
-
-export function getChatStoreMessages(key: string) {
-  return chatStoreMap.get(key)?.getState()?.messages;
+  loadSession: (messages: M[]) => void;
 }
 
-export const createChatStore = () =>
-  create<ChatState>((set, get) => ({
+/** 创建一个泛型 chat store 实例 */
+export function createChatStore<M extends StoreMessage>() {
+  return create<ChatState<M>>((set, get) => ({
     messages: [],
-    streamingText: '',
     suggestions: [],
     isRequesting: false,
     error: null,
@@ -116,7 +96,6 @@ export const createChatStore = () =>
     resetChat: () =>
       set({
         messages: [],
-        streamingText: '',
         suggestions: [],
         isRequesting: false,
         error: null,
@@ -125,9 +104,42 @@ export const createChatStore = () =>
     loadSession: (messages) =>
       set({
         messages,
-        streamingText: '',
         suggestions: [],
         isRequesting: false,
         error: null,
       }),
   }));
+}
+
+/** store 实例类型 */
+export type ChatStoreApi<M extends StoreMessage> = ReturnType<
+  typeof createChatStore<M>
+>;
+
+// 全局 store 管理器 — 多会话内存常驻
+
+const chatStoreMap = new Map<string, ChatStoreApi<any>>();
+
+/** 获取或创建指定会话的 store */
+export function getOrCreateChatStore<M extends StoreMessage>(
+  key: string
+): ChatStoreApi<M> {
+  let store = chatStoreMap.get(key);
+  if (!store) {
+    store = createChatStore<M>();
+    chatStoreMap.set(key, store);
+  }
+  return store;
+}
+
+/** 删除指定会话的 store */
+export function deleteChatStore(key: string) {
+  chatStoreMap.delete(key);
+}
+
+/** 读取指定会话的消息列表 */
+export function getChatStoreMessages<M extends StoreMessage>(
+  key: string
+): M[] | undefined {
+  return chatStoreMap.get(key)?.getState()?.messages;
+}

package/src/types/provider.ts

@@ -1,6 +1,7 @@
 /**
  * Provider 协议类型
- * 定义 ChatProvider ↔ useXChat 之间的数据契约
+ *
+ * 定义 ChatProvider 与 useXChat 之间的数据契约
  */
 
 import type { ChatMessage } from './message';
@@ -24,3 +25,20 @@ export interface ProviderCallbacks<Message = ChatMessage> {
   onError: (error: Error) => void;
   onSuggestion?: (items: SuggestionItem[]) => void;
 }
+
+/** TransformMessage 接收 info 对象而非位置参数 */
+export interface TransformMessageInfo<
+  Message = ChatMessage,
+  Output = SSEOutput,
+> {
+  /** 当前 SSE 输出块 */
+  output: Output;
+  /** 已累积的消息（首块时为 undefined） */
+  current?: Message;
+}
+
+/** TransformParams 选项 */
+export interface TransformParamsOptions<Message = ChatMessage> {
+  /** 会话中的全部消息 */
+  messages?: Message[];
+}