@unif/react-native-chat-sdk 0.1.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@unif/react-native-chat-sdk",
+  "version": "0.1.0",
+  "description": "UNIF React Native Chat SDK — 流式通信、Provider、状态管理",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "!**/__tests__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "build": "bob build",
+    "clean": "del-cli lib",
+    "typecheck": "tsc"
+  },
+  "keywords": ["react-native", "chat", "sdk", "sse", "streaming"],
+  "author": "qq382724935 <liulijun@pec.com.cn>",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "zustand": "^4.5.0"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-sse": ">=1.0.0"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      ["module", { "esm": true }],
+      ["typescript", { "project": "tsconfig.build.json" }]
+    ]
+  }
+}

package/src/hooks/ChatProvider.tsx

@@ -0,0 +1,131 @@
+/**
+ * ChatProvider — 全局数据提供 Context
+ *
+ * 可选的全局 Provider 模式（也可直接使用 hooks）
+ */
+
+import React, {createContext, useContext, useMemo} from 'react';
+import {useXChat} from './useXChat';
+import {useXConversations} from './useXConversations';
+import {useXModel} from './useXModel';
+import type {UseXChatConfig, MessageInfo} from './useXChat';
+import type {UseXConversationsOptions, SessionSummary} from './useXConversations';
+import type {ModelInfo} from './useXModel';
+import type {ChatMessage} from '../types/message';
+import type {RequestParams, SSEOutput} from '../types/provider';
+import type {SuggestionItem} from '../types/sse';
+import type {ChatStorage} from '../stores/storage';
+import type {AbstractChatProvider} from '../providers/AbstractChatProvider';
+
+export interface ChatProviderProps<
+  Message = ChatMessage,
+  Input = RequestParams<Message>,
+  Output = SSEOutput,
+> {
+  provider: AbstractChatProvider<Message, Input, Output>;
+  storage?: ChatStorage;
+  models?: ModelInfo[];
+  defaultModel?: string;
+  generateId?: () => string;
+  requestPlaceholder?: (input: Input) => Message;
+  requestFallback?: (input: Input, info: { error: Error }) => Message;
+  children: React.ReactNode;
+}
+
+interface ChatContextValue<Message = ChatMessage> {
+  // useXChat
+  messages: MessageInfo<Message>[];
+  requesting: boolean;
+  suggestions: SuggestionItem[];
+  onRequest: (input: unknown) => void;
+  abort: () => void;
+  // useXConversations
+  sessions: SessionSummary[];
+  activeId: string;
+  switchSession: (id: string) => Promise<Message[]>;
+  newSession: () => void;
+  deleteSession: (id: string) => Promise<void>;
+  archiveSession: (id: string, title: string, messages: Message[]) => Promise<void>;
+  // useXModel
+  selectedModel: string;
+  models: ModelInfo[];
+  setSelectedModel: (id: string) => void;
+}
+
+const ChatContext = createContext<ChatContextValue | null>(null);
+
+// 内存存储 fallback（无 storage 时使用）
+const memoryStorage: ChatStorage = {
+  _data: new Map<string, string>(),
+  async getItem(key: string) {
+    return (this._data as Map<string, string>).get(key) ?? null;
+  },
+  async setItem(key: string, value: string) {
+    (this._data as Map<string, string>).set(key, value);
+  },
+  async removeItem(key: string) {
+    (this._data as Map<string, string>).delete(key);
+  },
+} as ChatStorage & { _data: Map<string, string> };
+
+export function ChatProvider<
+  Message = ChatMessage,
+  Input = RequestParams<Message>,
+  Output = SSEOutput,
+>(props: ChatProviderProps<Message, Input, Output>) {
+  const {
+    provider,
+    storage,
+    models = [],
+    defaultModel,
+    generateId,
+    requestPlaceholder,
+    requestFallback,
+    children,
+  } = props;
+
+  const chatConfig: UseXChatConfig<Message, Input, Output> = useMemo(
+    () => ({
+      provider,
+      generateId,
+      requestPlaceholder,
+      requestFallback,
+    }),
+    [provider, generateId, requestPlaceholder, requestFallback]
+  );
+
+  const chat = useXChat(chatConfig);
+
+  const convOptions: UseXConversationsOptions = useMemo(
+    () => ({ storage: storage ?? memoryStorage }),
+    [storage]
+  );
+  const conversations = useXConversations(convOptions);
+
+  const model = useXModel({ models, defaultModel });
+
+  const value: ChatContextValue<Message> = useMemo(
+    () => ({
+      ...chat,
+      ...conversations,
+      ...model,
+    }),
+    [chat, conversations, model]
+  );
+
+  return (
+    <ChatContext.Provider value={value as unknown as ChatContextValue}>
+      {children}
+    </ChatContext.Provider>
+  );
+}
+
+export function useChatContext<
+  Message = ChatMessage,
+>(): ChatContextValue<Message> {
+  const ctx = useContext(ChatContext);
+  if (!ctx) {
+    throw new Error('useChatContext must be used within a ChatProvider');
+  }
+  return ctx as unknown as ChatContextValue<Message>;
+}

package/src/hooks/useXChat.ts

@@ -0,0 +1,136 @@
+/**
+ * useXChat — 聊天操作 hook
+ *
+ * 消费 ChatProvider，输出可渲染的 messages 列表
+ */
+
+import {useCallback, useEffect, useRef} from 'react';
+import {createChatStore} from '../stores/chatStore';
+import type {AbstractChatProvider} from '../providers/AbstractChatProvider';
+import type {ChatMessage, MessageStatus} from '../types/message';
+import type {RequestParams, SSEOutput} from '../types/provider';
+import type {SuggestionItem} from '../types/sse';
+
+export interface MessageInfo<Message = ChatMessage> {
+  id: string;
+  message: Message;
+  status: MessageStatus;
+  extra?: Record<string, unknown>;
+}
+
+export interface UseXChatConfig<
+  Message = ChatMessage,
+  Input = RequestParams<Message>,
+  Output = SSEOutput,
+> {
+  provider: AbstractChatProvider<Message, Input, Output>;
+  requestPlaceholder?: (input: Input) => Message;
+  requestFallback?: (input: Input, info: { error: Error }) => Message;
+  generateId?: () => string;
+}
+
+export interface UseXChatReturn<
+  Message = ChatMessage,
+  Input = RequestParams<Message>,
+> {
+  messages: MessageInfo<Message>[];
+  requesting: boolean;
+  suggestions: SuggestionItem[];
+  onRequest: (input: Input) => void;
+  abort: () => void;
+}
+
+let _idCounter = 0;
+const defaultGenId = () => `xc-${Date.now()}-${++_idCounter}`;
+
+export function useXChat<
+  Message = ChatMessage,
+  Input = RequestParams<Message>,
+  Output = SSEOutput,
+>(
+  config: UseXChatConfig<Message, Input, Output>
+): UseXChatReturn<Message, Input> {
+  const { provider, generateId = defaultGenId } = config;
+
+  const storeRef = useRef(createChatStore());
+  const store = storeRef.current;
+
+  // 订阅 store 变化
+  const state = store.getState();
+
+  // 同步最新值（组件级别使用 zustand subscribe 或 useSyncExternalStore）
+  // 简化实现：直接用 store.getState()
+  const getState = useCallback(() => store.getState(), [store]);
+
+  const onRequest = useCallback(
+    (input: Input) => {
+      const s = 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
+            .getState()
+            .upsertMessage(message as unknown as ChatMessage);
+        },
+        onSuccess: (message) => {
+          const m = message as unknown as ChatMessage;
+          store.getState().upsertMessage({
+            ...m,
+            status: 'success',
+          });
+          store.getState().setRequesting(false);
+        },
+        onError: (error) => {
+          store.getState().setError(error.message);
+          store.getState().setRequesting(false);
+
+          if (config.requestFallback) {
+            const fallbackMsg = config.requestFallback(input, { error });
+            store
+              .getState()
+              .addMessage(fallbackMsg as unknown as ChatMessage);
+          }
+        },
+      });
+    },
+    [provider, getState, store, config]
+  );
+
+  const abort = useCallback(() => {
+    provider.abort();
+    store.getState().setRequesting(false);
+  }, [provider, store]);
+
+  // 清理
+  useEffect(() => {
+    return () => {
+      provider.abort();
+    };
+  }, [provider]);
+
+  // 转换为 MessageInfo 格式
+  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,
+  }));
+
+  return {
+    messages,
+    requesting: state.isRequesting,
+    suggestions: state.suggestions,
+    onRequest,
+    abort,
+  };
+}

package/src/hooks/useXConversations.ts

@@ -0,0 +1,90 @@
+/**
+ * useXConversations — 会话管理 hook
+ *
+ * 组合 sessionStore + historyStore，管理会话生命周期
+ */
+
+import {useState, useCallback, useEffect, useRef} from 'react';
+import {createHistoryStore} from '../stores/historyStore';
+import type {ChatStorage} from '../stores/storage';
+import type {ChatMessage} from '../types/message';
+
+export {type SessionSummary} from '../stores/historyStore';
+
+export interface UseXConversationsOptions {
+  storage: ChatStorage;
+  maxSessions?: number;
+}
+
+export function useXConversations(options: UseXConversationsOptions) {
+  const {storage} = options;
+
+  const historyRef = useRef(createHistoryStore(storage));
+  const history = historyRef.current;
+
+  const [sessions, setSessions] = useState(history.sessions);
+  const [activeId, setActiveId] = useState('');
+
+  // 初始化加载
+  useEffect(() => {
+    // 触发 loadIndex
+    history.archiveSession('__init__', '', []).then(() => {
+      history.deleteSession('__init__').then(() => {
+        setSessions([...history.sessions]);
+      });
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const switchSession = useCallback(
+    async (id: string): Promise<ChatMessage[]> => {
+      setActiveId(id);
+      return await history.loadSessionMessages(id);
+    },
+    [history]
+  );
+
+  const newSession = useCallback(() => {
+    setActiveId('');
+  }, []);
+
+  const deleteSession = useCallback(
+    async (id: string) => {
+      await history.deleteSession(id);
+      setSessions([...history.sessions]);
+      if (activeId === id) {
+        setActiveId('');
+      }
+    },
+    [history, activeId]
+  );
+
+  const archiveSession = useCallback(
+    async (id: string, title: string, messages: ChatMessage[]) => {
+      await history.archiveSession(id, title, messages);
+      setSessions([...history.sessions]);
+    },
+    [history]
+  );
+
+  const updateSession = useCallback(
+    (id: string, data: Partial<{ title: string }>) => {
+      const session = history.sessions.find((s) => s.id === id);
+      if (session && data.title) {
+        session.title = data.title;
+        setSessions([...history.sessions]);
+      }
+    },
+    [history]
+  );
+
+  return {
+    sessions,
+    activeId,
+    switchSession,
+    newSession,
+    deleteSession,
+    archiveSession,
+    updateSession,
+  };
+}

package/src/hooks/useXModel.ts

@@ -0,0 +1,33 @@
+/**
+ * useXModel — 模型选择 hook
+ */
+
+import {useState, useCallback} from 'react';
+
+export interface ModelInfo {
+  id: string;
+  name: string;
+  desc: string;
+}
+
+export interface UseXModelOptions {
+  models: ModelInfo[];
+  defaultModel?: string;
+}
+
+export function useXModel(options: UseXModelOptions) {
+  const {models, defaultModel} = options;
+  const [selectedModel, setSelected] = useState(
+    defaultModel ?? models[0]?.id ?? ''
+  );
+
+  const setSelectedModel = useCallback((id: string) => {
+    setSelected(id);
+  }, []);
+
+  return {
+    selectedModel,
+    models,
+    setSelectedModel,
+  };
+}

package/src/index.md

@@ -0,0 +1,188 @@
+---
+title: SDK 概览
+nav:
+  title: SDK
+  path: /sdk
+---
+
+# @unif/react-native-chat-sdk
+
+聊天 SDK 包，提供 Provider 抽象、Hooks、状态管理和流式处理工具。
+
+## 架构
+
+```
+┌─────────────────────────────────────────┐
+│            useXChat (Hook)              │
+│   组合 Provider + store，输出 messages  │
+├─────────────────────────────────────────┤
+│           ChatProvider 层               │
+│  AbstractChatProvider → OpenAI/DeepSeek │
+├─────────────────────────────────────────┤
+│              工具层                     │
+│   XRequest → XStream → SSEParser       │
+├─────────────────────────────────────────┤
+│              数据层                     │
+│   chatStore / sessionStore / modelStore │
+└─────────────────────────────────────────┘
+```
+
+## 核心 Hooks
+
+### useXChat — 聊天操作
+
+```tsx
+import { useXChat, OpenAIChatProvider, XRequest } from '@unif/react-native-chat-sdk';
+
+const request = new XRequest({
+  baseURL: 'https://api.openai.com',
+  getToken: async () => 'sk-...',
+});
+const provider = new OpenAIChatProvider({ request, model: 'gpt-4o' });
+
+const { messages, requesting, onRequest, abort } = useXChat({ provider });
+
+// 发起请求
+onRequest({ message: { text: '你好' } });
+
+// 中止请求
+abort();
+```
+
+**返回值:**
+
+| 属性 | 说明 | 类型 |
+|------|------|------|
+| messages | 可渲染消息列表 | `MessageInfo<Message>[]` |
+| requesting | 是否请求中 | `boolean` |
+| suggestions | 建议提示 | `SuggestionItem[]` |
+| onRequest | 发起请求 | `(input: Input) => void` |
+| abort | 中止请求 | `() => void` |
+
+### useXConversations — 会话管理
+
+```tsx
+import { useXConversations } from '@unif/react-native-chat-sdk';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const {
+  sessions, activeId,
+  switchSession, newSession, deleteSession,
+} = useXConversations({ storage: AsyncStorage });
+```
+
+### useXModel — 模型选择
+
+```tsx
+import { useXModel } from '@unif/react-native-chat-sdk';
+
+const { selectedModel, setSelectedModel } = useXModel({
+  models: [
+    { id: 'gpt-4o', name: 'GPT-4o', desc: '最强模型' },
+    { id: 'gpt-4o-mini', name: 'GPT-4o Mini', desc: '快速响应' },
+  ],
+  defaultModel: 'gpt-4o',
+});
+```
+
+## Provider 体系
+
+### 内置 Provider
+
+| Provider | 说明 |
+|----------|------|
+| `OpenAIChatProvider` | 兼容 OpenAI API 格式（含 Azure、Moonshot、通义千问等） |
+| `DeepSeekChatProvider` | 继承 OpenAI，额外处理 `reasoning_content` 字段 |
+
+### 自定义 Provider
+
+继承 `AbstractChatProvider`，实现 3 个抽象方法：
+
+```tsx
+import { AbstractChatProvider } from '@unif/react-native-chat-sdk';
+
+class MyProvider extends AbstractChatProvider {
+  transformParams(input) {
+    // 转换请求参数为你的 API 格式
+    return { query: input.message.text, model: input.model };
+  }
+
+  transformLocalMessage(input) {
+    // 创建本地用户消息
+    return { id: generateId(), text: input.message.text, role: 'user', status: 'local', ... };
+  }
+
+  transformMessage(output, current) {
+    // 解析流式响应，累积到 assistant 消息
+    const data = JSON.parse(output.data);
+    return { ...current, text: (current?.text || '') + data.content, status: 'updating' };
+  }
+}
+```
+
+## 工具类
+
+### XRequest
+
+面向 LLM 的 HTTP 请求工具，内置 token 注入和 SSE 解析。
+
+```tsx
+const request = new XRequest({
+  baseURL: 'https://api.example.com',
+  endpoint: '/v1/chat/completions',
+  getToken: async () => await loadToken(),
+  timeout: 120000,
+});
+```
+
+### XStream
+
+SSE 流适配器（RN 原生实现，基于 react-native-sse）。
+
+### SSEParser
+
+SSE 解析器，提供 `event_id` 幂等去重和 `seq` 严格排序。
+
+## ChatProvider — 全局模式
+
+```tsx
+import { ChatProvider, useChatContext } from '@unif/react-native-chat-sdk';
+
+// 根组件
+<ChatProvider provider={provider} storage={AsyncStorage} models={MODELS}>
+  <App />
+</ChatProvider>
+
+// 子组件
+const { messages, onRequest, sessions, selectedModel } = useChatContext();
+```
+
+## 类型定义
+
+### ChatMessage
+
+```typescript
+interface ChatMessage {
+  id: string;
+  text: string;
+  role: 'user' | 'assistant' | 'system';
+  createdAt: Date;
+  messageType: 'text' | 'card' | 'system';
+  status: 'local' | 'loading' | 'updating' | 'success' | 'error' | 'abort';
+  cardType?: string;
+  cardData?: { data: Record<string, unknown>; actions: string[] };
+  turnId: string;
+  extra?: Record<string, unknown>;
+}
+```
+
+### MessageInfo
+
+```typescript
+interface MessageInfo<Message> {
+  id: string;
+  message: Message;
+  status: MessageStatus;
+  extra?: Record<string, unknown>;
+}
+```

package/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * @unif/react-native-chat-sdk
+ * AI 聊天 SDK — 流式通信、Provider 模式、状态管理
+ */
+
+// Types
+export type {
+  ChatMessage,
+  MessageRole,
+  MessageType,
+  MessageStatus,
+} from './types/message';
+
+export type {
+  SSEEventType,
+  SSEEnvelopeBase,
+  SSETextEvent,
+  SSECardDataEvent,
+  SSESuggestionEvent,
+  SSEErrorEvent,
+  SSEDoneEvent,
+  SSEEnvelope,
+} from './types/sse';
+
+export type {
+  RequestParams,
+  SSEOutput,
+  ProviderCallbacks,
+} from './types/provider';
+
+// Tools
+export {XStream} from './tools/XStream';
+export type {XStreamConfig, XStreamCallbacks} from './tools/XStream';
+
+export {XRequest} from './tools/XRequest';
+export type {XRequestConfig, XRequestCallbacks} from './tools/XRequest';
+
+export {SSEParser} from './tools/SSEParser';
+
+// Providers
+export {AbstractChatProvider} from './providers/AbstractChatProvider';
+export {OpenAIChatProvider} from './providers/OpenAIChatProvider';
+export type {OpenAIChatProviderConfig} from './providers/OpenAIChatProvider';
+export {DeepSeekChatProvider} from './providers/DeepSeekChatProvider';
+export type {DeepSeekChatProviderConfig} from './providers/DeepSeekChatProvider';
+
+// Stores
+export type {ChatStorage} from './stores/storage';
+
+// Hooks
+export {useXChat} from './hooks/useXChat';
+export type {UseXChatConfig, MessageInfo} from './hooks/useXChat';
+
+export {useXConversations} from './hooks/useXConversations';
+export type {UseXConversationsOptions, SessionSummary} from './hooks/useXConversations';
+
+export {useXModel} from './hooks/useXModel';
+export type {UseXModelOptions, ModelInfo} from './hooks/useXModel';
+
+export {ChatProvider, useChatContext} from './hooks/ChatProvider';
+export type {ChatProviderProps} from './hooks/ChatProvider';