diff --git a/CLAUDE.md b/CLAUDE.md
index 1ec436c..6d06c3d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,84 +2,89 @@
 
 ## 项目定位
 
-XuqmGroup React Native SDK monorepo。为集成宿主 App（如 YiwangxinApp4）提供核心能力：初始化、HTTP、设备信息、XWebView、OTA 更新、推送、IM、证书、**日志追踪**。
+XuqmGroup React Native SDK monorepo。为集成宿主 App（如 YiwangxinApp4）提供核心能力：初始化、HTTP、设备信息、XWebView、OTA 更新、推送、IM、证书、日志追踪。
 
-- Git 远端：`ssh://git@xuqinmin.com:2222/`（以 `git remote -v` 实际结果为准）
+- Git 远端：`https://xuqinmin.com/xuqmGroup/XuqmGroup-RNSDK.git`
 - Nexus npm 发布：`https://nexus.xuqinmin.com/repository/npm-hosted/`
+- 规范文档：`XuqmGroup-Docs/design/06-sdk-cross-platform-spec.md`
 
 ## 包结构
 
-| 包名 | 目录 | 当前版本 | 状态 |
-|------|------|----------|------|
-| `@xuqm/rn-common` | packages/common | 0.4.0 | 活跃开发 |
-| `@xuqm/rn-update` | packages/update | — | 活跃开发 |
-| `@xuqm/rn-xwebview` | packages/xwebview | — | 活跃开发 |
-| `@xuqm/rn-log` | packages/log | 0.1.0（新） | 新建中 |
-| `@xuqm/rn-push` | packages/push | — | 代码冻结（仅文档） |
-| `@xuqm/rn-im` | packages/im | — | 代码冻结（仅文档） |
-| `@xuqm/rn-license` | packages/license | — | 代码冻结（仅文档） |
+| 包名 | 目录 | 版本 | 说明 |
+|------|------|------|------|
+| `@xuqm/rn-common` | packages/common | 0.4.0 | 核心层：初始化、HTTP、设备、XWebView Bridge、API hooks |
+| `@xuqm/rn-update` | packages/update | 0.4.0 | OTA 热更新、APK 更新 |
+| `@xuqm/rn-push` | packages/push | 0.2.2 | 厂商推送（代码冻结，仅文档） |
+| `@xuqm/rn-im` | packages/im | 0.2.2 | IM 会话、消息（代码冻结，仅文档） |
+| `@xuqm/rn-xwebview` | packages/xwebview | 0.2.2 | WebView 容器 + JSBridge UI 组件 |
+| `@xuqm/rn-license` | packages/license | 0.3.0 | 证书授权（代码冻结，仅文档） |
+| `@xuqm/rn-log` | packages/log | 0.1.0 | 日志、错误追踪、漏斗分析（新） |
 
 **代码冻结模块（push/im/license）：不修改代码，仅补充文档。**
 
-## 技术约束
+## 技术栈
 
-- **React Native ≥ 0.76**（Bridgeless Mode，New Architecture）
-- **TypeScript 5.x strict** — `noImplicitAny: true`，禁止 `any`
-- **向下兼容**：公开接口不删除不修改，新字段一律可选
-- **无静默降级**：autoInit 失败时 `__DEV__` 模式 throw，生产模式 console.error
+- React Native >= 0.76（Bridgeless Mode，New Architecture）
+- TypeScript 5.x strict — `noImplicitAny: true`，禁止 `any`
+- yarn workspaces monorepo
+- 发布到 Nexus npm 私有仓库
 
-## 核心 API（@xuqm/rn-common）
-
-### 初始化（两种方式，均不得修改签名）
+## 初始化（两种方式）
 
 **方式 A — 配置文件自动初始化（推荐）**  
-宿主配置 Babel alias `@xuqm/autoinit-config` → 加密配置文件。SDK 自动读取并初始化，App 代码无需调用任何 init。
+宿主配置 Babel alias `@xuqm/autoinit-config` → 加密配置文件（XUQM-CONFIG-V1 格式）。SDK 自动读取并初始化，App 无需调用任何 init。
 
 **方式 B — 手动初始化**
 ```ts
-// 仅传 appKey → 使用内置公有平台
+import { XuqmSDK } from '@xuqm/rn-common'
+
+// 公有平台
 await XuqmSDK.initialize({ appKey: 'xxx' })
 
-// 传 appKey + platformUrl → 使用指定私有化平台
+// 私有化平台
 await XuqmSDK.initialize({ appKey: 'xxx', platformUrl: 'https://xxx' })
 
 // 等待异步平台配置拉取
 await XuqmSDK.awaitInitialization()
 ```
 
-**两种平台互相独立，不允许自动降级到默认公有平台。**
+**两种平台互相独立，不允许自动降级。**
+
+## 用户信息
 
-### 用户信息
 ```ts
 XuqmSDK.setUserInfo({ userId: 'u001', userSig: 'sig', name: '张三' })
-XuqmSDK.setUserInfo(null)  // 登出
+XuqmSDK.setUserInfo(null)  // 登出，触发所有子 SDK 登出
 ```
 
-### 日志（@xuqm/rn-log）
+子 SDK 自动订阅 `setUserInfo` 事件：Push 自动注册/解绑 token，IM 自动登录/断开，Update 更新 userId。
+
+## 日志 SDK（@xuqm/rn-log）
+
 ```ts
-import { XLog } from '@xuqm/rn-log'  // 注意是 XLog 不是 Log
+import { XLog } from '@xuqm/rn-log'
 
 XLog.setLogLevel('debug')
 XLog.setEnvironment('production')
 XLog.startCapture()                   // 开启全局错误捕获
 XLog.event('page_view', { page: 'home' })
 XLog.captureError(new Error('xxx'))
+XLog.defineFunnel('checkout', ['cart_view', 'checkout_start', 'payment_done'])
 ```
 
 `logApiUrl` 由 SDK 在 init 后从 `/api/sdk/config` 自动获取，无需 App 传入。
 
+## 关键约束
+
+- `XuqmSDK.initialize()` 签名不得更改
+- `XuqmSDK.setUserInfo()` 现有字段不得删除
+- 新增字段一律为可选，有合理默认值
+- 不允许静默降级（autoInit 失败时 `__DEV__` 模式 throw）
+- rn-common 与 rn-log 解耦：rn-common 可独立使用；rn-log peerDep rn-common
+
 ## XWebView JSBridge 标准 Handler
 
-见 `docs/XWebView-JSBridge.md`（已有文档，以该文档为准）。
-
-## 任务文档
-
-开发前阅读 `/Users/xuqinmin/Projects/XuqmProjects/YiwangxinApp4/docs/agent-tasks/` 中对应的 agent 任务文件：
-
-- Agent 2 任务：`agent2-rn-common.md`
-- Agent 3 任务：`agent3-rn-update-xwebview.md`
-- Agent 4 任务：`agent4-rn-log.md`
-- Agent 8 任务：`agent8-docs.md`
+见 `docs/XWebView-JSBridge.md`。
 
 ## 常用命令
 
@@ -87,4 +92,8 @@ XLog.captureError(new Error('xxx'))
 yarn workspace @xuqm/rn-common typecheck
 yarn workspace @xuqm/rn-log typecheck
 yarn workspace @xuqm/rn-update typecheck
+yarn workspace @xuqm/rn-push typecheck
+yarn workspace @xuqm/rn-im typecheck
+yarn workspace @xuqm/rn-xwebview typecheck
+yarn workspace @xuqm/rn-license typecheck
 ```
diff --git a/docs/架构总览.md b/docs/架构总览.md
new file mode 100644
index 0000000..e248505
--- /dev/null
+++ b/docs/架构总览.md
@@ -0,0 +1,105 @@
+# XuqmGroup RN SDK 架构总览
+
+## 整体架构
+
+```
+宿主 App（YiwangxinApp4 等）
+  └── 初始化（方式A: 配置文件自动 / 方式B: 手动 initialize）
+        ↓
+  @xuqm/rn-common （核心层 v0.4.0）
+    ├── XuqmSDK.initialize() → 拉取 /api/sdk/config
+    ├── XuqmSDK.setUserInfo() → 通知所有子 SDK（订阅者模式）
+    ├── api/（useApi / usePageApi / apiRequest）
+    ├── device（设备信息 / 厂商检测）
+    ├── xwebview（JSBridge 桥接控制）
+    ├── ui/（toast / alert / confirm）
+    └── logApiUrl / logEnabled（从平台配置获取）
+        ↓ peerDep / 依赖
+  子 SDK（各自独立）
+    ├── @xuqm/rn-update   → OTA 热更新 / APK 更新
+    ├── @xuqm/rn-push     → 厂商推送（peerDep: rn-common）
+    ├── @xuqm/rn-im       → IM 会话 / 消息（peerDep: rn-common）
+    ├── @xuqm/rn-xwebview → WebView UI 组件（peerDep: rn-common）
+    ├── @xuqm/rn-license  → 证书授权（peerDep: rn-common）
+    └── @xuqm/rn-log      → 日志 / 追踪（peerDep: rn-common）
+```
+
+## 依赖关系
+
+```
+rn-common （核心，无 SDK 内部依赖）
+  ↑ peerDep
+  ├── rn-update   （直接依赖 rn-common）
+  ├── rn-push     （peerDep rn-common）
+  ├── rn-im       （peerDep rn-common + watermelondb）
+  ├── rn-xwebview （peerDep rn-common + webview + navigation）
+  ├── rn-license  （peerDep rn-common + quick-crypto）
+  └── rn-log      （peerDep rn-common）
+```
+
+## 用户状态分发机制
+
+```
+XuqmSDK.setUserInfo(info)
+  ├── PushSDK: 检测厂商 → 获取厂商配置 → 注册 token
+  ├── ImSDK:   若 userSig 存在且 imEnabled → 自动登录 WebSocket
+  ├── UpdateSDK: 更新 userId（用于定向更新）
+  └── LicenseSDK: 更新用户上下文
+
+XuqmSDK.setUserInfo(null)
+  ├── PushSDK: 解绑 token
+  ├── ImSDK:   断开 WebSocket
+  └── 其他子 SDK: 清理用户状态
+```
+
+各子 SDK 在模块加载时通过 `_registerUserInfoHandler()` 注册处理器，无需 App 手动协调。
+
+## 初始化流程
+
+### 方式 A（自动）
+
+```
+Metro alias → @xuqm/autoinit-config → encrypted .xuqmconfig
+  ↓ import 时触发
+autoInit.ts → require('@xuqm/autoinit-config')
+  ↓ 解密（PBKDF2 + AES-256-GCM）
+initWithConfigFile() → initialize({ appKey, platformUrl })
+  ↓ HTTP GET
+/api/sdk/config → 返回 { apiUrl, imWsUrl, fileServiceUrl, ... }
+```
+
+### 方式 B（手动）
+
+```
+App 代码调用 XuqmSDK.initialize({ appKey })
+  ↓ HTTP GET
+/api/sdk/config → 解析平台配置
+  ↓
+各子 SDK 就绪（等待 setUserInfo 触发具体功能）
+```
+
+## 数据流
+
+```
+App 代码
+  ↓ 调用 API
+子 SDK（update/push/im/license/log）
+  ↓ 使用 apiRequest()
+rn-common http.ts
+  ↓ 附加 Bearer Token + 处理响应
+平台服务（tenant-service / im-service / push-service / update-service / log-service）
+```
+
+## 包发布
+
+所有包发布到 Nexus npm 私有仓库：`https://nexus.xuqinmin.com/repository/npm-hosted/`
+
+```bash
+# 发布单个包
+cd packages/common && npm publish
+
+# 发布所有包
+for pkg in common update push im xwebview license log; do
+  cd packages/$pkg && npm publish && cd ../..
+done
+```
diff --git a/docs/模块待开发说明.md b/docs/模块待开发说明.md
new file mode 100644
index 0000000..250cd76
--- /dev/null
+++ b/docs/模块待开发说明.md
@@ -0,0 +1,85 @@
+# 模块待开发说明
+
+> 以下模块当前代码冻结，仅补充文档。后续开发需单独评估。
+
+---
+
+## rn-push（厂商推送）
+
+### 当前状态
+
+- FCM/APNS 基础注册已实现
+- HMS/VIVO/OPPO 厂商推送集成框架已建
+- 自动厂商检测（通过原生模块 `NativePush`）
+- Token 注册/解绑 API 完整
+- 离线推送开关、免打扰时间段 API 已实现
+
+### 后续待做
+
+- 厂商推送 token 注册完整流程（华为 HMS 需要 AppGallery Connect 配置）
+- 设备绑定/解绑统一 API（当前分散在各厂商 SDK）
+- 角标管理（badge count 同步）
+- 厂商推送通道选择（高优先级 vs 普通通知）
+- 推送数据分析（到达率、点击率统计）
+
+### 技术要点
+
+- 原生模块 `XuqmPushModule` 需要在宿主 App 中链接
+- 各厂商 SDK 初始化需要对应的 App ID / App Secret
+- `setUserInfo(info)` 触发自动注册，`setUserInfo(null)` 触发自动解绑
+
+---
+
+## rn-im（即时通讯）
+
+### 当前状态
+
+- 腾讯云 IM SDK 封装（WebSocket/STOMP 传输）
+- WatermelonDB 本地消息持久化
+- 基础会话/消息 API 完整（15 种消息类型）
+- 群组管理 API 完整
+- 关系链（好友/黑名单）API 完整
+- 离线消息同步、消息搜索（本地）
+
+### 后续待做
+
+- 消息已读回执（单聊已读状态同步）
+- 群组消息已读回执统计
+- 离线消息补全（当前为 best-effort 同步）
+- 消息撤回时间窗口控制（服务端策略）
+- 语音消息录制组件（当前仅发送本地音频文件）
+- 图片/视频消息缩略图生成
+- 消息转发、合并转发 UI
+- @所有人（@all）支持
+
+### 技术要点
+
+- 需要 `@nozbe/watermelondb` 依赖
+- DB 名称由 `appKey + userId` 派生，多账号隔离
+- 断线重连由 `ImClient` 内部处理（指数退避）
+- `setUserInfo` 自动触发 IM 登录（若 `imEnabled` 为 true）
+
+---
+
+## rn-license（证书授权）
+
+### 当前状态
+
+- 证书授权基础流程已实现
+- 设备 License 验证（`checkLicense`）
+- License 状态查询（`getStatus`）
+- 本地缓存（AsyncStorage）
+
+### 后续待做
+
+- 证书到期提醒（服务端推送 + 本地定时检查）
+- 证书自动刷新机制
+- 多设备 License 管理
+- 离线 License 验证（降级策略）
+- License 使用量统计
+
+### 技术要点
+
+- 需要 `react-native-quick-crypto` 依赖
+- 内部自动等待 `XuqmSDK` 初始化完成
+- License 服务地址从平台配置获取（`licenseUrl`）
diff --git a/packages/common/README.md b/packages/common/README.md
new file mode 100644
index 0000000..540d8b9
--- /dev/null
+++ b/packages/common/README.md
@@ -0,0 +1,109 @@
+# @xuqm/rn-common
+
+XuqmGroup RN SDK 核心模块。负责 SDK 初始化、HTTP 请求、Token 管理、设备信息、XWebView Bridge、API hooks。
+
+## 安装
+
+```bash
+yarn add @xuqm/rn-common @react-native-async-storage/async-storage
+```
+
+Peer dependencies：`react >= 18`，`react-native >= 0.76`，`axios >= 1.0.0`
+
+## 初始化
+
+### 方式 A — 配置文件自动初始化（推荐）
+
+在宿主项目中配置 Babel alias `@xuqm/autoinit-config` → 加密配置文件：
+
+```js
+// metro.config.js
+config.resolver.extraNodeModules = {
+  '@xuqm/autoinit-config': './path/to/your.xuqmconfig',
+};
+```
+
+SDK 在 import 时自动调用 `initWithConfigFile()`，App 无需任何 init 代码。
+
+### 方式 B — 手动初始化
+
+```ts
+import { XuqmSDK } from '@xuqm/rn-common'
+
+await XuqmSDK.initialize({ appKey: 'xxx' })               // 公有平台
+await XuqmSDK.initialize({ appKey: 'xxx', platformUrl: 'https://xxx' })  // 私有化
+await XuqmSDK.awaitInitialization()                        // 等待配置拉取
+```
+
+## API
+
+### 初始化
+
+| API | 说明 |
+|-----|------|
+| `XuqmSDK.initialize(opts)` | 初始化，拉取平台配置 |
+| `XuqmSDK.awaitInitialization()` | 等待异步初始化完成 |
+| `isInitialized()` | 检查 SDK 是否就绪 |
+| `getConfig()` | 获取已解析的平台配置 |
+
+### 用户信息
+
+| API | 说明 |
+|-----|------|
+| `XuqmSDK.setUserInfo(info)` | 设置用户信息，触发所有子 SDK 登录 |
+| `XuqmSDK.setUserInfo(null)` | 登出，触发全局登出 |
+| `getUserId()` | 获取当前 userId |
+| `getUserInfo()` | 获取当前用户信息 |
+| `setUserId(id)` | 直接设置 userId（内部用） |
+
+### HTTP
+
+| API | 说明 |
+|-----|------|
+| `apiRequest(url, options?)` | 带 Bearer token 的 HTTP 请求 |
+| `configureHttp(opts)` | 覆盖 HTTP 基础配置 |
+| `_getToken()` | 获取当前 token（内部用） |
+| `_saveToken(token)` | 保存 token（内部用） |
+| `_clearToken()` | 清除 token（内部用） |
+
+### 设备
+
+| API | 说明 |
+|-----|------|
+| `getDeviceId()` | 获取设备稳定 UUID |
+| `getDeviceInfo()` | 获取设备品牌/型号/系统信息 |
+| `detectPushVendor()` | 检测设备推送厂商 |
+
+### XWebView Bridge
+
+| API | 说明 |
+|-----|------|
+| `openXWebView(url, options?)` | 打开 WebView |
+| `setXWebViewController(controller)` | 设置全局 WebView 控制器 |
+| `getXWebViewConfig()` | 获取当前 WebView 配置 |
+| `XWebViewControl` | WebView 控制器类 |
+
+### API Hooks
+
+| API | 说明 |
+|-----|------|
+| `useApi(method, url, opts?)` | React hook：带 loading/error 的 API 调用 |
+| `usePageApi(method, url, opts?)` | React hook：分页 API |
+| `useRequest(opts?)` | React hook：通用请求 |
+| `setGlobalApiErrorHandler(handler)` | 设置全局 API 错误处理 |
+
+### UI
+
+| API | 说明 |
+|-----|------|
+| `showToast(msg)` | 显示 toast |
+| `showAlert(title, msg)` | 显示 alert |
+| `showConfirm(title, msg)` | 显示确认对话框 |
+| `ScaledImage` | 等比缩放图片组件 |
+
+### 常量
+
+| 常量 | 说明 |
+|------|------|
+| `DEFAULT_TENANT_PLATFORM_URL` | 默认公有平台地址 |
+| `DEFAULT_IM_WS_URL` | 默认 IM WebSocket 地址 |
diff --git a/packages/im/README.md b/packages/im/README.md
new file mode 100644
index 0000000..fe02815
--- /dev/null
+++ b/packages/im/README.md
@@ -0,0 +1,127 @@
+# @xuqm/rn-im
+
+XuqmGroup RN SDK IM 模块。提供 WebSocket 实时通信、会话管理、消息收发、群组管理、关系链管理。
+
+## 安装
+
+```bash
+yarn add @xuqm/rn-im @nozbe/watermelondb
+```
+
+Peer dependencies：`@nozbe/watermelondb >= 0.27.0`，`react-native >= 0.76`
+
+## 使用
+
+**无需手动初始化。** `XuqmSDK.setUserInfo({ userId, userSig })` 被调用时，SDK 自动完成 IM 登录。
+
+```ts
+import { ImSDK } from '@xuqm/rn-im'
+
+// 发送消息
+await ImSDK.sendTextMessage('user_002', 'SINGLE', 'Hello!')
+
+// 获取会话列表
+const conversations = await ImSDK.listConversations()
+
+// 监听新消息
+ImSDK.addListener({
+  onMessage: (msg) => console.log('新消息:', msg),
+  onConnected: () => console.log('IM 已连接'),
+})
+```
+
+## API
+
+### 连接管理
+
+| API | 说明 |
+|-----|------|
+| `ImSDK.login(userId, userSig)` | 手动登录（通常不需要直接调用） |
+| `ImSDK.refreshToken(userSig)` | 刷新 userSig（过期时调用） |
+| `ImSDK.disconnect()` | 断开连接 |
+| `ImSDK.reconnect()` | 重新连接 |
+| `ImSDK.isConnected()` | 检查连接状态 |
+
+### 消息 API
+
+| API | 说明 |
+|-----|------|
+| `ImSDK.sendMessage(toId, chatType, msgType, content, mentionedUserIds?)` | 发送消息 |
+| `ImSDK.sendTextMessage(toId, chatType, content, mentionedUserIds?)` | 发送文本 |
+| `ImSDK.sendImageMessage(toId, chatType, localUri, width?, height?)` | 发送图片 |
+| `ImSDK.sendVideoMessage(toId, chatType, localUri, thumbnailUri?, duration?)` | 发送视频 |
+| `ImSDK.sendAudioMessage(toId, chatType, localUri, duration)` | 发送语音 |
+| `ImSDK.sendFileMessage(toId, chatType, localUri, filename, size)` | 发送文件 |
+| `ImSDK.sendQuoteMessage(toId, chatType, quotedMsgId, quotedContent, text)` | 引用回复 |
+| `ImSDK.sendLocationMessage(toId, chatType, latitude, longitude, title?, address?)` | 发送位置 |
+| `ImSDK.revokeMessage(messageId)` | 撤回消息 |
+| `ImSDK.editMessage(messageId, content)` | 编辑消息 |
+
+### 会话 API
+
+| API | 说明 |
+|-----|------|
+| `ImSDK.listConversations()` | 获取会话列表 |
+| `ImSDK.subscribeConversations(callback)` | 订阅会话变更（返回 unsubscribe） |
+| `ImSDK.markRead(targetId, chatType?)` | 标记已读 |
+| `ImSDK.deleteConversation(targetId, chatType)` | 删除会话 |
+| `ImSDK.getTotalUnreadCount()` | 获取总未读数 |
+
+### 历史消息
+
+| API | 说明 |
+|-----|------|
+| `ImSDK.fetchHistory(toId, page?, size?)` | 获取单聊历史（优先本地缓存） |
+| `ImSDK.fetchGroupHistory(groupId, page?, size?)` | 获取群聊历史 |
+| `ImSDK.fetchHistoryWithFilters(toId, params)` | 按条件查询历史 |
+| `ImSDK.searchMessages(params)` | 搜索消息（本地 WatermelonDB） |
+| `ImSDK.locateHistoryPage(toId, messageId)` | 定位消息所在页 |
+
+### 群组 API
+
+| API | 说明 |
+|-----|------|
+| `ImSDK.createGroup(name, memberIds, groupType?)` | 创建群组 |
+| `ImSDK.listGroups()` | 获取群组列表 |
+| `ImSDK.getGroupInfo(groupId)` | 获取群组信息 |
+| `ImSDK.listGroupMembers(groupId)` | 获取群成员 |
+| `ImSDK.addGroupMember(groupId, userId)` | 添加成员 |
+| `ImSDK.removeGroupMember(groupId, userId)` | 移除成员 |
+| `ImSDK.setGroupRole(groupId, userId, role)` | 设置管理员 |
+| `ImSDK.muteGroupMember(groupId, userId, minutes)` | 禁言 |
+| `ImSDK.dismissGroup(groupId)` | 解散群组 |
+
+### 关系链 API
+
+| API | 说明 |
+|-----|------|
+| `ImSDK.listFriends()` | 好友列表 |
+| `ImSDK.addFriend(friendId)` | 添加好友 |
+| `ImSDK.removeFriend(friendId)` | 删除好友 |
+| `ImSDK.sendFriendRequest(toUserId, remark?)` | 发送好友申请 |
+| `ImSDK.acceptFriendRequest(requestId)` | 接受好友申请 |
+| `ImSDK.addToBlacklist(blockedUserId)` | 加入黑名单 |
+| `ImSDK.checkBlacklist(targetUserId)` | 检查黑名单 |
+
+### 事件监听
+
+```ts
+ImSDK.addListener({
+  onConnected: () => {},
+  onDisconnected: (code, reason) => {},
+  onMessage: (msg) => {},
+  onGroupMessage: (msg) => {},
+  onSystemMessage: (msg) => {},
+  onRead: (msg) => {},
+  onRevoke: (data) => {},
+})
+ImSDK.removeListener(listener)
+```
+
+## 消息类型
+
+`TEXT` / `IMAGE` / `VIDEO` / `AUDIO` / `FILE` / `CUSTOM` / `LOCATION` / `NOTIFY` / `RICH_TEXT` / `CALL_AUDIO` / `CALL_VIDEO` / `QUOTE` / `MERGE` / `REVOKED` / `FORWARD`
+
+## 本地存储
+
+使用 WatermelonDB 进行本地消息缓存，支持离线消息同步和本地搜索。DB 名称由 `appKey + userId` 派生。
diff --git a/packages/license/README.md b/packages/license/README.md
new file mode 100644
index 0000000..f28c231
--- /dev/null
+++ b/packages/license/README.md
@@ -0,0 +1,59 @@
+# @xuqm/rn-license
+
+XuqmGroup RN SDK 证书授权模块。提供设备 License 验证能力。
+
+## 安装
+
+```bash
+yarn add @xuqm/rn-license react-native-quick-crypto
+```
+
+Peer dependencies：`react-native >= 0.76`，`@react-native-async-storage/async-storage >= 1.21.0`，`react-native-quick-crypto >= 0.7.0`
+
+## 使用
+
+**无需独立初始化。** 内部自动调用 `awaitInitialization()` 等待 `XuqmSDK` 就绪。
+
+```ts
+import { checkLicense, getStatus, clear } from '@xuqm/rn-license'
+
+// 验证 License
+const result = await checkLicense()
+if (result.type === 'success') {
+  console.log('License 通过:', result.reason)
+} else {
+  console.error('License 失败:', result.message)
+}
+
+// 获取状态
+const status = await getStatus()  // 'ok' | 'denied' | 'unknown'
+
+// 清除本地缓存（调试用）
+await clear()
+```
+
+## API
+
+| API | 说明 |
+|-----|------|
+| `checkLicense(userInfo?)` | 验证设备 License |
+| `getStatus()` | 获取当前 License 状态 |
+| `getDeviceId()` | 获取设备 ID |
+| `clear()` | 清除本地 License 缓存 |
+
+## 类型
+
+```ts
+interface LicenseUserInfo {
+  userId?: string
+  userSig?: string
+}
+
+type LicenseStatus = 'ok' | 'denied' | 'unknown'
+
+interface LicenseResult {
+  type: 'success' | 'denied' | 'error'
+  reason?: string
+  message?: string
+}
+```
diff --git a/packages/log/README.md b/packages/log/README.md
new file mode 100644
index 0000000..be68d59
--- /dev/null
+++ b/packages/log/README.md
@@ -0,0 +1,89 @@
+# @xuqm/rn-log
+
+XuqmGroup RN SDK 日志模块。提供日志采集、错误追踪、漏斗分析能力。
+
+## 安装
+
+```bash
+yarn add @xuqm/rn-log
+```
+
+Peer dependencies：`@xuqm/rn-common >= 0.4.0`，`@react-native-async-storage/async-storage >= 1.21.0`，`react-native >= 0.76`
+
+## 快速开始
+
+```ts
+import { XLog } from '@xuqm/rn-log'
+
+// 1. 设置日志级别
+XLog.setLogLevel('debug')  // 'debug' | 'info' | 'warn' | 'error'
+
+// 2. 设置环境标签
+XLog.setEnvironment('production')  // 'development' | 'staging' | 'production'
+
+// 3. 开启全局错误捕获（App 启动时调用一次）
+XLog.startCapture()
+
+// 4. 记录自定义事件
+XLog.event('page_view', { page: 'home' })
+
+// 5. 上报错误
+try { ... } catch (e) { XLog.captureError(e) }
+```
+
+## API
+
+### XLog 对象
+
+| API | 说明 |
+|-----|------|
+| `XLog.setLogLevel(level)` | 设置最低日志级别（低于此级别的事件被丢弃） |
+| `XLog.setEnvironment(env)` | 设置环境标签（附加到每个事件） |
+| `XLog.startCapture()` | 开启全局 JS 错误和未处理 Promise rejection 捕获 |
+| `XLog.event(name, properties?)` | 记录自定义分析事件 |
+| `XLog.captureError(error, metadata?)` | 上报 JS 异常 |
+| `XLog.warn(message, metadata?)` | 记录警告（需级别允许） |
+| `XLog.info(message, metadata?)` | 记录信息事件（需级别允许） |
+| `XLog.defineFunnel(id, steps)` | 定义漏斗（按步骤顺序追踪转化） |
+| `XLog.getFunnelProgress(funnelId)` | 获取客户端漏斗进度 |
+| `XLog.flush()` | 立即刷新所有待发送事件（如 App 进后台前调用） |
+
+### 事件类型
+
+| 类型 | 说明 |
+|------|------|
+| `LogEvent` | 自定义事件（`type: 'event'`） |
+| `IssueEvent` | 错误事件（`type: 'js_error'` / `'native_crash'` / `'api_error'` / `'warning'`） |
+
+### 日志级别
+
+`'debug'` (0) < `'info'` (1) < `'warn'` (2) < `'error'` (3)
+
+### 漏斗分析示例
+
+```ts
+import { XLog } from '@xuqm/rn-log'
+
+// 定义漏斗
+XLog.defineFunnel('checkout', ['cart_view', 'checkout_start', 'payment_done'])
+
+// 在业务代码中记录步骤事件（SDK 自动推进漏斗）
+XLog.event('cart_view')
+XLog.event('checkout_start')
+XLog.event('payment_done')
+
+// 查询进度
+const progress = XLog.getFunnelProgress('checkout')
+console.log(progress?.completedSteps) // ['cart_view', 'checkout_start', 'payment_done']
+```
+
+## 工作原理
+
+1. **LogQueue**：事件先进入内存队列，按批次异步上传到 `logApiUrl`
+2. **ErrorCapture**：`startCapture()` 注册全局 `ErrorUtils` handler，自动捕获未处理异常
+3. **Fingerprint**：为每个错误生成指纹（基于 message + stack），用于服务端去重聚合
+4. **FunnelTracker**：客户端维护漏斗进度，服务端跨 session 聚合
+
+## 配置
+
+`logApiUrl` 和 `logEnabled` 由 `@xuqm/rn-common` 在 init 后从 `/api/sdk/config` 自动获取，无需 App 传入。
diff --git a/packages/push/README.md b/packages/push/README.md
new file mode 100644
index 0000000..d9106bf
--- /dev/null
+++ b/packages/push/README.md
@@ -0,0 +1,53 @@
+# @xuqm/rn-push
+
+XuqmGroup RN SDK 推送模块。自动检测设备厂商并完成推送 token 注册。
+
+## 安装
+
+```bash
+yarn add @xuqm/rn-push
+```
+
+Peer dependencies：`react-native >= 0.76`
+
+## 使用
+
+**无需手动初始化。** `XuqmSDK.setUserInfo(info)` 被调用时，SDK 自动完成：
+1. 检测设备厂商（华为/小米/OPPO/vivo/荣耀/FCM/APNs）
+2. 从平台获取该厂商推送配置
+3. 调用厂商 SDK 完成设备注册
+4. 收到 token 后自动上报绑定到平台
+
+```ts
+import { PushSDK } from '@xuqm/rn-push'
+
+// 通常不需要手动调用，setUserInfo 会自动触发
+// 设置离线推送开关
+await PushSDK.setOfflinePushEnabled(false)
+
+// 设置免打扰时间段（24 小时制）
+await PushSDK.setQuietHours('22:00', '08:00')
+
+// 清除免打扰
+await PushSDK.clearQuietHours()
+
+// 主动登出（通常不需要，setUserInfo(null) 自动触发）
+await PushSDK.logout()
+```
+
+## API
+
+| API | 说明 |
+|-----|------|
+| `PushSDK.setOfflinePushEnabled(enabled)` | 设置离线推送开关 |
+| `PushSDK.setQuietHours(start, end)` | 设置免打扰时间段 |
+| `PushSDK.clearQuietHours()` | 清除免打扰设置 |
+| `PushSDK.logout()` | 解绑推送 token |
+
+## 支持厂商
+
+HUAWEI / XIAOMI / OPPO / VIVO / HONOR / FCM / APNS
+
+## 依赖
+
+需要原生模块 `NativeModules.XuqmPushModule` 已链接到宿主 App。
diff --git a/packages/update/README.md b/packages/update/README.md
new file mode 100644
index 0000000..1b5c661
--- /dev/null
+++ b/packages/update/README.md
@@ -0,0 +1,116 @@
+# @xuqm/rn-update
+
+XuqmGroup RN SDK 更新模块。提供 App 整包更新检查和 RN 插件热更新能力。
+
+## 安装
+
+```bash
+yarn add @xuqm/rn-update @react-native-async-storage/async-storage
+```
+
+Peer dependencies：`react-native >= 0.76`，`@react-native-async-storage/async-storage >= 1.21.0`
+
+## 快速开始
+
+```ts
+import { UpdateSDK } from '@xuqm/rn-update'
+
+// 注册插件
+UpdateSDK.registerPlugins([
+  { moduleId: 'szyx' },
+  { moduleId: 'miniapp' },
+])
+
+// 注入宿主 BundleRuntime
+UpdateSDK.setBundleCallbacks({
+  writeBundle: writeBundleFile,
+  reloadBundle: loadBundle,
+})
+
+// 检查 App 更新
+const info = await UpdateSDK.checkAppUpdate()
+if (info.needsUpdate) {
+  await UpdateSDK.downloadAndInstallApk(info.downloadUrl)
+}
+
+// 检查插件更新
+const pluginInfo = await UpdateSDK.checkPluginUpdate('szyx')
+if (pluginInfo.needsUpdate) {
+  await UpdateSDK.updatePlugin('szyx', { onProgress: setProgress })
+}
+```
+
+## API
+
+### 插件注册
+
+| API | 说明 |
+|-----|------|
+| `UpdateSDK.registerPlugins(plugins)` | 批量注册插件 |
+| `UpdateSDK.registerPlugin(meta)` | 单个注册（向后兼容） |
+| `UpdateSDK.setBundleCallbacks(callbacks)` | 注入宿主写入/重载能力 |
+| `UpdateSDK.getRegisteredPlugins()` | 获取已注册插件列表 |
+
+### App 整包更新
+
+| API | 说明 |
+|-----|------|
+| `UpdateSDK.checkAppUpdate(bypassIgnore?)` | 检查 App 更新（30 分钟缓存） |
+| `UpdateSDK.downloadApk(info, options?)` | 下载 APK，返回 ArrayBuffer |
+| `UpdateSDK.downloadAndInstallApk(url, options?)` | 下载 APK 并调起系统安装器（Android） |
+| `UpdateSDK.openStore(appStoreUrl?, marketUrl?)` | 跳转应用商店 |
+| `UpdateSDK.getAppVersionCode()` | 获取当前 versionCode |
+| `UpdateSDK.getAppVersionName()` | 获取当前 versionName |
+
+### 插件热更新
+
+| API | 说明 |
+|-----|------|
+| `UpdateSDK.checkPluginUpdate(moduleId)` | 检查插件更新（30 分钟缓存） |
+| `UpdateSDK.updatePlugin(moduleId, options?)` | 一步完成：检查 → 下载 → 写文件 → 重载 |
+
+### 类型定义
+
+```ts
+interface PluginRegistration {
+  moduleId: string
+}
+
+interface AppUpdateInfo {
+  needsUpdate: boolean
+  versionName?: string
+  versionCode?: number
+  downloadUrl?: string
+  changeLog?: string
+  forceUpdate?: boolean
+  appStoreUrl?: string
+  marketUrl?: string
+  apkHash?: string | null
+}
+
+interface PluginUpdateInfo {
+  needsUpdate: boolean
+  latestVersion: string
+  currentVersion: string
+  downloadUrl: string
+  md5: string
+  minCommonVersion: string
+  note: string
+  forceUpdate?: boolean
+}
+
+interface CachedRnBundle {
+  moduleId: string
+  version: string
+  md5: string
+  downloadedAt: string
+  source: string
+}
+```
+
+## 工作原理
+
+- 版本号由 SDK 自动从本地 AsyncStorage 缓存读取，首次为 `0.0.0`
+- 更新检查结果缓存 30 分钟（TTL），避免频繁请求
+- `updatePlugin()` 内部自动完成：`checkPluginUpdate` → `fetch(downloadUrl)` → AsyncStorage 缓存 → `writeBundle` → `reloadBundle`
+- `silent: true` 时跳过 `reloadBundle`，下次启动生效
diff --git a/packages/xwebview/README.md b/packages/xwebview/README.md
new file mode 100644
index 0000000..f9e47a1
--- /dev/null
+++ b/packages/xwebview/README.md
@@ -0,0 +1,78 @@
+# @xuqm/rn-xwebview
+
+XuqmGroup RN SDK WebView 模块。提供增强型 WebView 组件和 JSBridge 通信能力。
+
+## 安装
+
+```bash
+yarn add @xuqm/rn-xwebview react-native-webview react-native-blob-util react-native-svg
+```
+
+Peer dependencies：`react >= 18`，`react-native >= 0.76`，`@react-navigation/native >= 7.0.0`
+
+## 组件
+
+### XWebViewScreen — 全屏 WebView（React Navigation screen）
+
+```tsx
+import { XWebViewScreen } from '@xuqm/rn-xwebview'
+
+// 在导航中使用
+<XWebViewScreen />
+// URL 通过 openXWebView() 预设
+```
+
+### XWebViewView — 嵌入式 WebView 组件
+
+```tsx
+import { XWebViewView } from '@xuqm/rn-xwebview'
+
+<XWebViewView
+  config={{
+    url: 'https://example.com',
+    title: '嵌入式网页',
+    jsBridgeName: 'XWebViewBridge',
+  }}
+/>
+```
+
+### XWebViewProgress — 进度条
+
+```tsx
+import { XWebViewProgress } from '@xuqm/rn-xwebview'
+
+<XWebViewProgress progress={50} />
+```
+
+## API
+
+| API | 说明 |
+|-----|------|
+| `openXWebView(url, options?)` | 打开 WebView 页面 |
+| `setXWebViewController(controller)` | 设置全局 WebView 控制器 |
+| `getXWebViewConfig()` | 获取当前 WebView 配置 |
+| `XWebViewControl` | WebView 控制器类 |
+
+## XWebViewConfig 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `url` | string | 初始加载地址 |
+| `title` | string | 页面标题 |
+| `jsBridgeName` | string | JS 桥接对象名（默认 `'XWebViewBridge'`） |
+| `hideToolbar` | boolean | 隐藏顶栏 |
+| `userAgent` | string? | 自定义 User-Agent |
+| `injectedJavaScript` | string? | 页面加载后注入的 JS |
+| `onMessage` | (event) => void | H5 发送消息回调 |
+
+## JSBridge 通信
+
+```js
+// H5 → Native
+window.XWebViewBridge.postMessage(JSON.stringify({ type: 'login', token: '...' }))
+
+// Native → H5
+controller.postMessageToWeb("window.dispatchEvent(new CustomEvent('nativeMsg', { detail: { key: 'value' } }))")
+```
+
+详细 handler 列表见 `@xuqm/rn-common` 的 `xwebview/` 目录和 `docs/XWebView-JSBridge.md`。