@unif/react-native-chat-sdk

AI 聊天 SDK — 流式通信、Provider 模式、状态管理。

安装

yarn add @unif/react-native-chat-sdk

peerDependencies

yarn add react react-native react-native-sse

架构

┌──────────────────────────────────────────┐
│            useXChat (Hook)               │
│  组合 Provider + store，输出 messages    │
├──────────────────────────────────────────┤
│           ChatProvider 层                │
│  AbstractChatProvider → OpenAI/DeepSeek  │
├──────────────────────────────────────────┤
│              工具层                      │
│  XRequest + XStream + SSEParser          │
└──────────────────────────────────────────┘

快速开始

方式一：ChatProvider 全局模式

import {
  ChatProvider,
  useChatContext,
  OpenAIChatProvider,
} from '@unif/react-native-chat-sdk';
import AsyncStorage from '@react-native-async-storage/async-storage';

const provider = new OpenAIChatProvider({
  baseURL: 'https://api.openai.com',
  model: 'gpt-4o',
  apiKey: 'sk-...',
});

function App() {
  return (
    <ChatProvider provider={provider} storage={AsyncStorage}>
      <ChatScreen />
    </ChatProvider>
  );
}

function ChatScreen() {
  const {messages, onRequest, isRequesting, abort} = useChatContext();
  // 使用 messages 渲染列表，onRequest 发送消息...
}

方式二：直接使用 Hooks

import {useXChat, useXConversations, useXModel} from '@unif/react-native-chat-sdk';

function ChatScreen() {
  const {messages, onRequest, abort, isRequesting} = useXChat({provider, conversationKey: 'main'});
  const {sessions, activeSession, switchSession, createSession} = useXConversations({storage: AsyncStorage});
  const {selectedModel, setSelectedModel} = useXModel({models: MODELS});
}

API

Hooks

useXChat

聊天操作核心 hook，消费 Provider 输出可渲染 messages。

const {
  messages,             // MessageInfo[] — 可渲染消息列表
  isRequesting,         // boolean — 是否请求中
  suggestions,          // SuggestionItem[] — 建议提示
  error,                // string | null — 错误信息
  onRequest,            // (input) => void — 发起请求
  regenerate,           // (assistantMessageId, extra?) => void — 重新生成
  abort,                // () => void — 中止请求
  clearError,           // () => void — 清除错误
  setMessages,          // (messages | updater) => void — 设置消息列表
  setMessage,           // (id, partial | updater) => void — 更新单条消息
  removeMessage,        // (id) => void — 删除单条消息
  getBranches,          // (messageId) => Message[] — 获取分支列表
  getActiveBranchIndex, // (messageId) => number — 获取活跃分支索引
  switchBranch,         // (messageId, index) => void — 切换分支
} = useXChat({provider, conversationKey: 'main'});

useXConversations

会话管理 hook，组合 historyStore + chatStore。

const {
  sessions,          // SessionSummary[] — 已持久化会话列表
  activeSession,     // ActiveSession | null — 当前活跃会话
  switchSession,     // (id) => Promise<void> — 切换会话
  createSession,     // () => string — 创建新会话，返回 id
  deleteSession,     // (id) => Promise<void> — 删除会话
  archiveSession,    // (id, title, messages) => Promise<void> — 归档会话
  saveActiveSession, // (title) => Promise<void> — 保存当前活跃会话
  updateSession,     // (id, data) => Promise<void> — 更新会话元数据
} = useXConversations({storage: AsyncStorage});

useXModel

模型选择 hook。

const {
  selectedModel,     // string
  models,            // ModelInfo[]
  setSelectedModel,  // (id) => void
} = useXModel({models: AVAILABLE_MODELS, defaultModel: 'gpt-4o'});

Providers

AbstractChatProvider

抽象基类，自定义 Provider 需继承并实现 3 个方法：

class MyProvider extends AbstractChatProvider<Message, ProviderInput<Message>, Output> {
  // 将 ProviderInput 转为 HTTP 请求体
  transformParams(input: ProviderInput<Message>): Record<string, unknown>;

  // 创建用户本地消息（立即显示在列表中）
  transformLocalMessage(input: UserInput<Message>): Message;

  // 将 SSE 流数据转为 assistant 消息（流式累积）
  transformMessage(info: TransformMessageInfo<Message, Output>): Message;
}

OpenAIChatProvider

OpenAI 兼容 Provider，支持所有 OpenAI 标准 API。

const provider = new OpenAIChatProvider({
  baseURL: 'https://api.openai.com',
  model: 'gpt-4o',
  getToken: async () => apiKey,
});

DeepSeekChatProvider

DeepSeek Provider，继承 OpenAI，额外处理 reasoning_content → <think> 标签。

const provider = new DeepSeekChatProvider({
  model: 'deepseek-chat',
  getToken: async () => apiKey,
});

Tools

XStream

SSE 流适配器，基于 react-native-sse 的 RN 原生实现。

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。

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 严格排序。

const parser = new SSEParser();
parser.reset(); // 每轮对话重置

const envelopes = parser.process(rawData); // 返回排序后的事件数组

Types

// 消息类型
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;
  extra?: Record<string, unknown>;
}

// 存储抽象
interface ChatStorage {
  getItem: (key: string) => Promise<string | null>;
  setItem: (key: string, value: string) => Promise<void>;
  removeItem: (key: string) => Promise<void>;
}

注意： zustand 已内置在 SDK 包中，无需单独安装。

许可证

MIT