@bdky/chat-pilot-kit-react-native

chat-pilot-kit 的 React Native 适配层：native-only，Expo 优先。基于 @bdky/chat-pilot-kit-react-core 的无 DOM 共享层（Provider、Context、Hooks、NodeView 契约），补齐 RN 环境下的传输、原生 NodeView 与存储适配。

当前阶段（M2）

M2 聚焦可插拔双传输：基于 @bdky/websocket-client 的 WSTransport，与注入式流式 fetch + eventsource-parser 的 SSETransport。编解码走用户钩子，不绑定具体业务帧协议。 原生 NodeView 与 Expo 存储适配留待后续阶段。

依赖前置说明

• RN 全局 fetch 不支持流式响应体（streaming body）。SSETransport 需要 expo/fetch（Expo SDK ≥ 52）或由消费方注入等价的 fetchImpl。
• expo 为 optional peerDependency：未安装 expo 的纯 RN CLI 工程需自行提供 fetchImpl 才能使用 SSETransport。

入口 polyfill 要求

消费方应用的入口文件需在首行引入：

import 'reflect-metadata';
import 'react-native-get-random-values';

reflect-metadata 是 @bdky/chat-pilot-kit 依赖注入（inversify）所需； react-native-get-random-values 补齐 RN 环境缺失的 crypto.getRandomValues （uuid 等依赖运行时需要）。

错误处理注意

transport 的 error 事件触发后，会话不会自动结束（不会 markCompleted）， 仍停留在 streaming 态；下一轮 query() 可能粘进已出错的气泡。当前版本建议在应用的 错误处理回调中调用 kit.interrupt() 结束该轮，避免残留态影响后续对话（core 后续 版本将提供 fatal 语义以区分终态/瞬态错误，届时可移除该临时处理）。

持久化加密

MMKVAdapter / ExpoSQLiteAdapter 默认明文落盘：聊天记录含用户 PII，设备失窃或 系统备份被提取时可被直接读取。是否加密在外部构造存储实例时决定 —— adapter 依赖注入， 只接收已构造好的 MMKV / db 实例，加密与否对 adapter 代码透明，无需改动 adapter。

• 密钥请存 iOS Keychain / Android Keystore（如 expo-secure-store、 react-native-keychain），切勿硬编码到源码或打包产物。
• 加密有轻微性能开销，敏感对话场景建议开启。

MMKV 加密（react-native-mmkv encryptionKey）

用 new MMKV({encryptionKey}) 构造加密实例，再交给 MMKVAdapter：

import {MMKV} from 'react-native-mmkv';
import {MMKVAdapter} from '@bdky/chat-pilot-kit-react-native';

const storage = new MMKV({id: 'chat', encryptionKey: '<from-keychain>'});
const adapter = new MMKVAdapter(storage);

expo-sqlite 加密（SQLCipher）

构建期启用 SQLCipher（expo-sqlite config plugin 的 useSQLCipher: true），运行期在 任何读写之前执行 PRAGMA key，再交给 ExpoSQLiteAdapter.create(db)：

import * as SQLite from 'expo-sqlite';
import {ExpoSQLiteAdapter} from '@bdky/chat-pilot-kit-react-native';

const db = SQLite.openDatabaseSync('chat.db');
await db.execAsync("PRAGMA key = '<from-keychain>'");
const adapter = await ExpoSQLiteAdapter.create(db);

PRAGMA key 必须在建表等任何操作之前执行（ExpoSQLiteAdapter.create(db) 内部会建表）， 否则 SQLCipher 会报错或以未加密方式打开。