@unif/react-native-chat-sdk 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,252 @@
+# @unif/react-native-chat-sdk
+
+AI 聊天 SDK — 流式通信、Provider 模式、状态管理，参考 [Ant Design X SDK](https://ant-design-x.antgroup.com/x-sdks/introduce) 架构设计。
+
+## 安装
+
+```bash
+yarn add @unif/react-native-chat-sdk
+```
+
+### peerDependencies
+
+```bash
+yarn add react react-native react-native-sse
+```
+
+## 架构
+
+```
+┌──────────────────────────────────────────┐
+│            useXChat (Hook)               │
+│  组合 Provider + store，输出 messages    │
+├──────────────────────────────────────────┤
+│           ChatProvider 层                │
+│  AbstractChatProvider → OpenAI/DeepSeek  │
+├──────────────────────────────────────────┤
+│              工具层                      │
+│  XRequest + XStream + SSEParser          │
+└──────────────────────────────────────────┘
+```
+
+## 快速开始
+
+### 方式一：ChatProvider 全局模式
+
+```tsx
+import {
+  ChatProvider,
+  useChatContext,
+  OpenAIChatProvider,
+  XRequest,
+} from '@unif/react-native-chat-sdk';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const request = new XRequest({
+  baseURL: 'https://api.openai.com',
+  getToken: async () => 'sk-...',
+});
+const provider = new OpenAIChatProvider({request, model: 'gpt-4o'});
+
+function App() {
+  return (
+    <ChatProvider provider={provider} storage={AsyncStorage}>
+      <ChatScreen />
+    </ChatProvider>
+  );
+}
+
+function ChatScreen() {
+  const {messages, onRequest, requesting, abort} = useChatContext();
+  // 使用 messages 渲染列表，onRequest 发送消息...
+}
+```
+
+### 方式二：直接使用 Hooks
+
+```tsx
+import {useXChat, useXConversations, useXModel} from '@unif/react-native-chat-sdk';
+
+function ChatScreen() {
+  const {messages, onRequest, abort, requesting} = useXChat({provider});
+  const {sessions, switchSession, newSession} = useXConversations({storage: AsyncStorage});
+  const {selectedModel, setSelectedModel} = useXModel({models: MODELS});
+}
+```
+
+## API
+
+### Hooks
+
+#### useXChat
+
+聊天操作核心 hook，消费 Provider 输出可渲染 messages。
+
+```typescript
+const {
+  messages,      // MessageInfo[] — 可渲染消息列表
+  requesting,    // boolean — 是否请求中
+  suggestions,   // SuggestionItem[] — 建议提示
+  error,         // string | null — 错误信息
+  onRequest,     // (input) => void — 发起请求
+  abort,         // () => void — 中止请求
+  resetChat,     // () => void — 重置聊天
+  loadSession,   // (messages) => void — 加载历史会话
+  clearError,    // () => void — 清除错误
+} = useXChat({provider});
+```
+
+#### useXConversations
+
+会话管理 hook，组合 session + history。
+
+```typescript
+const {
+  sessions,        // SessionSummary[]
+  activeId,        // string
+  switchSession,   // (id) => Promise<ChatMessage[]>
+  newSession,      // () => void
+  deleteSession,   // (id) => Promise<void>
+  archiveSession,  // (id, title, messages) => Promise<void>
+} = useXConversations({storage: AsyncStorage});
+```
+
+#### useXModel
+
+模型选择 hook。
+
+```typescript
+const {
+  selectedModel,     // string
+  models,            // ModelInfo[]
+  setSelectedModel,  // (id) => void
+} = useXModel({models: AVAILABLE_MODELS, defaultModel: 'gpt-4o'});
+```
+
+### Providers
+
+#### AbstractChatProvider
+
+抽象基类，自定义 Provider 需继承并实现 3 个方法：
+
+```typescript
+class MyProvider extends AbstractChatProvider {
+  // 将 useXChat.onRequest() 参数转为 HTTP 请求体
+  transformParams(input: RequestParams): Record<string, unknown>;
+
+  // 创建用户本地消息（立即显示在列表中）
+  transformLocalMessage(input: RequestParams): ChatMessage;
+
+  // 将 SSE 流数据转为 assistant 消息（流式累积）
+  transformMessage(output: SSEOutput, current?: ChatMessage): ChatMessage;
+}
+```
+
+#### OpenAIChatProvider
+
+OpenAI 兼容 Provider，支持所有 OpenAI 标准 API。
+
+```typescript
+const provider = new OpenAIChatProvider({
+  baseURL: 'https://api.openai.com',
+  model: 'gpt-4o',
+  getToken: async () => apiKey,
+});
+```
+
+#### DeepSeekChatProvider
+
+DeepSeek Provider，继承 OpenAI，额外处理 `reasoning_content`。
+
+```typescript
+const provider = new DeepSeekChatProvider({
+  model: 'deepseek-chat',
+  getToken: async () => apiKey,
+});
+```
+
+### Tools
+
+#### XStream
+
+SSE 流适配器，基于 `react-native-sse` 的 RN 原生实现。
+
+```typescript
+const stream = new XStream({
+  url: 'https://api.example.com/stream',
+  method: 'POST',
+  body: {message: 'hello'},
+  timeout: 120000,
+});
+
+stream.connect({
+  onMessage: (output) => console.log(output.data),
+  onError: (err) => console.error(err),
+  onComplete: () => console.log('done'),
+});
+```
+
+#### XRequest
+
+面向 LLM 的 HTTP 请求工具，组合 XStream + SSEParser。
+
+```typescript
+const request = new XRequest({
+  baseURL: 'https://api.example.com',
+  endpoint: '/v1/chat/completions',
+  getToken: async () => token,
+});
+
+await request.create(params, {
+  onStream: (chunk) => handleChunk(chunk),
+  onSuccess: () => handleDone(),
+  onError: (err) => handleError(err),
+});
+```
+
+#### SSEParser
+
+SSE 解析器，event_id 幂等去重 + seq 严格排序。
+
+```typescript
+const parser = new SSEParser();
+parser.reset(); // 每轮对话重置
+
+const envelopes = parser.process(rawData); // 返回排序后的事件数组
+```
+
+### Types
+
+```typescript
+// 消息类型
+interface ChatMessage {
+  id: string;
+  text: string;
+  role: 'user' | 'assistant' | 'system';
+  status: 'local' | 'loading' | 'updating' | 'success' | 'error' | 'abort';
+  messageType: 'text' | 'card' | 'system';
+  createdAt: Date;
+  turnId: string;
+  cardType?: string;
+  cardData?: { data: Record<string, unknown>; actions: string[] };
+  extra?: Record<string, unknown>;
+}
+
+// 存储抽象
+interface ChatStorage {
+  getItem: (key: string) => Promise<string | null>;
+  setItem: (key: string, value: string) => Promise<void>;
+  removeItem: (key: string) => Promise<void>;
+}
+```
+
+## 兼容性
+
+| @unif/react-native-chat-sdk | React Native | React | 状态 |
+|-----------------------------|-------------|-------|------|
+| 0.1.x | >= 0.71 | >= 18 | ✅ |
+| 0.1.x | 0.74.x | 18.x | ✅ 已验证（PECPortal） |
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unif/react-native-chat-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "UNIF React Native Chat SDK — 流式通信、Provider、状态管理",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/hooks/ChatProvider.tsx

@@ -37,8 +37,12 @@ interface ChatContextValue<Message = ChatMessage> {
   messages: MessageInfo<Message>[];
   requesting: boolean;
   suggestions: SuggestionItem[];
+  error: string | null;
   onRequest: (input: unknown) => void;
   abort: () => void;
+  resetChat: () => void;
+  loadSession: (messages: ChatMessage[]) => void;
+  clearError: () => void;
   // useXConversations
   sessions: SessionSummary[];
   activeId: string;
@@ -54,7 +58,6 @@ interface ChatContextValue<Message = ChatMessage> {
 
 const ChatContext = createContext<ChatContextValue | null>(null);
 
-// 内存存储 fallback（无 storage 时使用）
 const memoryStorage: ChatStorage = {
   _data: new Map<string, string>(),
   async getItem(key: string) {

package/src/hooks/useXChat.ts

@@ -4,7 +4,7 @@
  * 消费 ChatProvider，输出可渲染的 messages 列表
  */
 
-import {useCallback, useEffect, useRef} from 'react';
+import {useCallback, useEffect, useRef, useSyncExternalStore} from 'react';
 import {createChatStore} from '../stores/chatStore';
 import type {AbstractChatProvider} from '../providers/AbstractChatProvider';
 import type {ChatMessage, MessageStatus} from '../types/message';
@@ -36,8 +36,12 @@ export interface UseXChatReturn<
   messages: MessageInfo<Message>[];
   requesting: boolean;
   suggestions: SuggestionItem[];
+  error: string | null;
   onRequest: (input: Input) => void;
   abort: () => void;
+  resetChat: () => void;
+  loadSession: (messages: ChatMessage[]) => void;
+  clearError: () => void;
 }
 
 let _idCounter = 0;
@@ -55,27 +59,25 @@ export function useXChat<
   const storeRef = useRef(createChatStore());
   const store = storeRef.current;
 
-  // 订阅 store 变化
-  const state = store.getState();
-
-  // 同步最新值（组件级别使用 zustand subscribe 或 useSyncExternalStore）
-  // 简化实现：直接用 store.getState()
-  const getState = useCallback(() => store.getState(), [store]);
+  // 使用 useSyncExternalStore 订阅 zustand store 变化
+  const state = useSyncExternalStore(
+    store.subscribe,
+    store.getState,
+    store.getState,
+  );
 
   const onRequest = useCallback(
     (input: Input) => {
-      const s = getState();
-      if (s.isRequesting) return; // 请求去重
+      const s = store.getState();
+      if (s.isRequesting) return;
 
       store.getState().setRequesting(true);
       store.getState().setError(null);
       store.getState().setSuggestions([]);
 
-      // 添加用户本地消息
       const localMessage = provider.transformLocalMessage(input);
       store.getState().addMessage(localMessage as unknown as ChatMessage);
 
-      // 发起请求
       provider.sendMessage(input, {
         onUpdate: (message) => {
           store
@@ -101,9 +103,12 @@ export function useXChat<
               .addMessage(fallbackMsg as unknown as ChatMessage);
           }
         },
+        onSuggestion: (items) => {
+          store.getState().setSuggestions(items);
+        },
       });
     },
-    [provider, getState, store, config]
+    [provider, store, config]
   );
 
   const abort = useCallback(() => {
@@ -111,14 +116,27 @@ export function useXChat<
     store.getState().setRequesting(false);
   }, [provider, store]);
 
-  // 清理
+  const resetChat = useCallback(() => {
+    store.getState().resetChat();
+  }, [store]);
+
+  const loadSession = useCallback(
+    (messages: ChatMessage[]) => {
+      store.getState().loadSession(messages);
+    },
+    [store]
+  );
+
+  const clearError = useCallback(() => {
+    store.getState().setError(null);
+  }, [store]);
+
   useEffect(() => {
     return () => {
       provider.abort();
     };
   }, [provider]);
 
-  // 转换为 MessageInfo 格式
   const messages: MessageInfo<Message>[] = state.messages.map((m) => ({
     id: m.id,
     message: m as unknown as Message,
@@ -130,7 +148,11 @@ export function useXChat<
     messages,
     requesting: state.isRequesting,
     suggestions: state.suggestions,
+    error: state.error,
     onRequest,
     abort,
+    resetChat,
+    loadSession,
+    clearError,
   };
 }

package/src/index.ts

@@ -20,6 +20,7 @@ export type {
   SSEErrorEvent,
   SSEDoneEvent,
   SSEEnvelope,
+  SuggestionItem,
 } from './types/sse';
 
 export type {
@@ -49,7 +50,7 @@ export type {ChatStorage} from './stores/storage';
 
 // Hooks
 export {useXChat} from './hooks/useXChat';
-export type {UseXChatConfig, MessageInfo} from './hooks/useXChat';
+export type {UseXChatConfig, UseXChatReturn, MessageInfo} from './hooks/useXChat';
 
 export {useXConversations} from './hooks/useXConversations';
 export type {UseXConversationsOptions, SessionSummary} from './hooks/useXConversations';

package/src/tools/XRequest.ts

@@ -7,6 +7,7 @@
 import {XStream} from './XStream';
 import {SSEParser} from './SSEParser';
 import type {SSEOutput} from '../types/provider';
+import type {SSEEnvelope} from '../types/sse';
 
 export interface XRequestConfig {
   baseURL: string;
@@ -49,11 +50,12 @@ export class XRequest {
     } = this.config;
 
     // 注入 auth token
+    const reqHeaders = {...headers};
     if (getToken) {
       try {
         const token = await getToken();
         if (token) {
-          headers['Authorization'] = `Bearer ${token}`;
+          reqHeaders['Authorization'] = `Bearer ${token}`;
         }
       } catch {
         // token 获取失败，继续无认证请求
@@ -65,14 +67,21 @@ export class XRequest {
     this.stream = new XStream({
       url,
       method: 'POST',
-      headers,
+      headers: reqHeaders,
       body: params,
       timeout,
     });
 
     this.stream.connect({
       onMessage: (output: SSEOutput) => {
-        callbacks.onStream?.(output);
+        // 通过 SSEParser 进行幂等去重和排序
+        const envelopes: SSEEnvelope[] = this.parser.process(output.data);
+        for (const envelope of envelopes) {
+          callbacks.onStream?.({
+            data: JSON.stringify(envelope),
+            event: envelope.type,
+          });
+        }
       },
       onError: (error: Error) => {
         callbacks.onError?.({

package/src/types/provider.ts

@@ -4,6 +4,7 @@
  */
 
 import type {ChatMessage} from './message';
+import type {SuggestionItem} from './sse';
 
 export interface RequestParams<T = ChatMessage> {
   message: T;
@@ -21,4 +22,5 @@ export interface ProviderCallbacks<Message = ChatMessage> {
   onUpdate: (message: Message) => void;
   onSuccess: (message: Message) => void;
   onError: (error: Error) => void;
+  onSuggestion?: (items: SuggestionItem[]) => void;
 }