@cg-devcenter/rtc-fpnn-webjs-sdk 1.0.0-cg.7 → 1.0.0-cg.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -20,6 +20,8 @@ export type RTMSharedWorkerOptions = rtm.RTMSharedWorkerOptions;
20
20
  export type RTMSharedCreateClientOptions = rtm.RTMSharedCreateClientOptions;
21
21
  export type RTMIndependentCreateClientOptions = rtm.RTMIndependentCreateClientOptions;
22
22
  export type RTMCreateClientOptions = rtm.RTMCreateClientOptions;
23
+ export type RTMConnectionInfo = rtm.RTMConnectionInfo;
24
+ export type RTMConnectionInfoProvider = rtm.RTMConnectionInfoProvider;
23
25
  export type RTMDefaultClient = rtm.RTMDefaultClient;
24
26
  export type RTMSharedSessionSnapshot = rtm.RTMSharedSessionSnapshot;
25
27
  export type RTMSharedLoginResult = rtm.RTMSharedLoginResult;
@@ -8,7 +8,7 @@
8
8
 
9
9
  ## 能力地图
10
10
 
11
- 推荐通过 `createClient()` 接入:扁平配置,UID 从登录参数取得;浏览器支持 SharedWorker 时,SDK 按 PID、协议、UID 和 Gate endpoint 自动隔离并复用连接,不支持时自动使用当前页面的独立连接。工厂和 `RTMSharedWorkerClient` 省略协议时均默认使用 FPNN,TLV 需显式选择。`sharing: false` 可显式选择独立连接;旧构造器保留业务 API。混用共享入口时,连接参数仍须保持一致。若 npm `latest` 尚未包含此入口,请使用本地构建;配置、错误和生命周期见 [默认共享接入](USAGE.md#默认共享接入当前源码)。
11
+ 推荐通过 `createClient()` 接入:扁平配置,UID 从登录参数取得;浏览器支持 SharedWorker 且配置可安全传递时,SDK 按 PID、协议、UID 和 Gate endpoint 自动隔离并复用连接。工作区 `1.0.0-cg.8` 在不支持 Worker 或配置包含函数、自定义对象等运行时值时,自动使用当前页面连接;`getConnectionInfo()` 报告实际模式和回退原因。工厂和 `RTMSharedWorkerClient` 省略协议时均默认使用 FPNN,TLV 需显式选择。`sharing: false` 可显式选择页面内连接;旧构造器保留业务 API。混用共享入口时,连接参数仍须保持一致。npm `latest` `1.0.0-cg.7` 已包含包根 ESM 和构建插件入口,但尚不包含本段所述配置值回退和诊断 API;这些能力尚未发布到 npm。配置、错误和生命周期见 [默认共享接入](USAGE.md#默认共享接入)。
12
12
 
13
13
  | 业务目标 | SDK 能力 | 常用 API |
14
14
  | --- | --- | --- |
@@ -1,6 +1,6 @@
1
1
  # npm 接入现代化:实现与验证记录
2
2
 
3
- 状态:源码实现与本地包验证已完成。真实 Gate 多窗口验收、registry 候选发布和业务试接入尚未执行;仓库修改不代表 npm 上的版本已经更新。2026-10-13 查询 registry 时,`latest` 仍为 `1.0.0-cg.6`,该版本没有包根 ESM 或 `/vite-plugin` 导出;发布新版后应更新此记录。
3
+ 状态更新(2026-10-13):工作区包版本已升至 `1.0.0-cg.8`,重建并审计本地 npm tarball;该版本尚未发布。registry `latest` 仍为 `1.0.0-cg.7`,此前已直接从 registry 安装到三个 Vite Demo,并在 Vite 6.4.4 下完成生产构建;包根 ESM、`/vite-plugin`、`/webpack4` 和 SharedWorker 入口均在该发布包中。`cg.8` 工作区构建新增的不可传输配置直连回退和 `getConnectionInfo()` 尚未发布;框架 Demo lockfile 仍固定 `cg.7`,因此使用 SharedWorker 可用性兼容推断。真实 Gate 多窗口验收和业务试接入仍未完成。
4
4
 
5
5
  本文基于 2026-10-13 的仓库状态编写。范围是 SDK 发布格式、Worker 资源接入和兼容验证。协议与业务 API 继续遵循 [接入指南](USAGE.md) 和 [协议迁移说明](PROTOCOL_MIGRATION.md)。
6
6
 
@@ -26,7 +26,7 @@
26
26
  3. Webpack 4 项目最多添加一次 SDK 构建插件,不要求业务维护资源路径。
27
27
  4. 普通 HTML 的 `window.rtm`、现有 CommonJS、旧 `/vite` 和公开 API 继续可用。
28
28
  5. 同 UID 多页面仍复用同一个 Worker 和一条 Gate WebSocket;`destroy()` 只释放当前页面。
29
- 6. 使用实际 npm tarball 和候选发布版本完成验证,保留可追溯证据后再更新线上发布标签。
29
+ 6. 使用实际 npm tarball 和 registry `latest` 完成验证,保留可追溯证据。
30
30
 
31
31
  “任意构建工具都零配置”不作为承诺。Vue/React 版本不能代替构建工具版本作为支持依据。
32
32
 
@@ -206,7 +206,7 @@ Vite 生产构建和 Webpack 5 会把相对模块 URL 输出为构建资源。Vi
206
206
 
207
207
  ### 3.3 Vite 兼容与预构建
208
208
 
209
- 已在仓库 Demo 的 Vite 6.4.4 环境验证包根入口的开发模块解析与生产构建;本地使用 yalc 迭代,独立 tarball 另做安装及入口/类型检查。
209
+ 直接从 npm registry 安装 `@cg-devcenter/rtc-fpnn-webjs-sdk@latest`(`1.0.0-cg.7`)后,在 Vite 6.4.4 的隔离消费工程对比验证了开发模式:不加 SDK 插件时,Vite 会把包根 ESM 预构建到 `node_modules/.vite/deps`,模块中的 `new URL('../dist/rtm.shared-worker.js', import.meta.url)` 因而解析到错误目录;加 `/vite-plugin` 后 SDK 保留在 Vite 转换链中,Worker URL 指向包内 `dist/rtm.shared-worker.js` 且请求返回 200。该 SDK 插件只调整 Vite 开发依赖预构建;生产构建中 Vite 根据 ESM 的静态 Worker URL 输出独立资源。Vue 3、Vue 2.7、React 三个 Demo 也都从 registry 安装该版本并通过生产构建,输出独立 Worker 资源。
210
210
 
211
211
  Demo 已迁移到包根入口,并删除过去为 UMD 和 `?url` 设置的 `optimizeDeps.include/exclude`。插件会排除包根与旧 `/vite` 子路径;保留旧 `/vite` 作为迁移兼容入口。
212
212
 
@@ -340,15 +340,15 @@ npm install /absolute/path/to/candidate-sdk.tgz
340
340
  | H1 | 普通 HTML + 浏览器 | `PARTIAL`:加载 UMD 并创建共享客户端后,浏览器实际请求同目录 `/sdk/rtm.shared-worker.js`;自动 URL 解析已观察 | 真实 Gate 登录/多窗口复用及完整 HTML Demo 业务链路 |
341
341
  | N1 | Node CommonJS | `PASS`:无 `window` 时从包根 `require()`,现有包 smoke 测试通过 | 对真实 Gate 的 Node WebSocket 链路 |
342
342
  | N2 | Node ESM / SSR 导入 | `PASS`:包根默认/具名导入,在无 `window` 和 `SharedWorker` 下导入成功 | SSR 框架服务端请求周期和 socket 注入场景 |
343
- | V1 | Vue 3 + Vite 6.4.4 | `PARTIAL`:yalc 本地包 dev 模块和 Worker 请求通过;production build 输出带 hash 的 Worker;生产 preview 可加载发送台并成功调用本机 credential 状态 API;包根与旧 `/vite` 混用时 URL 一致且只输出一个 Worker | tarball 冷启动、HMR、深层路由和实际登录/连接复用 |
344
- | V2 | React 18 + Vite 6.4.4 | `PARTIAL`:dev 页面和 Worker 资源请求通过;production build 与 preview 页面、本机 credential 状态 API 均通过 | effect 清理、开发模式重复挂载和实际登录/连接复用 |
345
- | V3 | Vue 2.7.16 + Vite 6.4.4 | `PARTIAL`:yalc 链接本地构建后,production build 与 preview 页面、本机 credential 状态 API 通过;使用官方 Vue 2 Vite 插件 | 组件卸载、开发模式与实际登录/连接复用 |
343
+ | V1 | Vue 3 + Vite 6.4.4 | `PARTIAL`:registry `1.0.0-cg.7` 安装后 production build 输出带 hash 的 Worker;独立 Vite dev 对照确认 SDK 插件修正 Worker URL;此前 yalc 本地开发包的 preview 和本机 credential 状态 API 验收为历史记录 | registry 包的 HMR、深层路由和实际登录/连接复用 |
344
+ | V2 | React 18 + Vite 6.4.4 | `PARTIAL`:registry `1.0.0-cg.7` 安装后 production build 输出带 hash 的 Worker;此前 yalc 本地开发包的 dev、preview 页面和本机 credential 状态 API 验收为历史记录 | registry 包的 effect 清理、开发模式重复挂载和实际登录/连接复用 |
345
+ | V3 | Vue 2.7.16 + Vite 6.4.4 | `PARTIAL`:registry `1.0.0-cg.7` 安装后 production build 输出带 hash 的 Worker;使用官方 Vue 2 Vite 插件;此前 yalc 本地开发包的 preview 和本机 credential 状态 API 验收为历史记录 | registry 包的组件卸载、开发模式与实际登录/连接复用 |
346
346
  | W5 | Webpack 5.111.1 最小工程 | `PARTIAL`:独立安装的 npm tarball production 编译成功,输出完整 Worker 资源并设置 `/static/` publicPath | dev server、浏览器请求、子目录部署和 React 生命周期 |
347
347
  | W4 | Vue 2.7.16 + Webpack 4.47.0 | `PARTIAL`:yalc 包配合 `vue-loader` 15 production build 成功;`/webpack4` 插件输出 Worker,bundle 解析为 `/static/rtm.shared-worker.js` | Vue CLI 4 dev/watch、浏览器实际启动/连接与组件卸载生命周期 |
348
348
  | R5 | React + CRA 5 / Webpack 5 | `NOT_RUN` | CRA 未 eject 的 dev/build 和 effect 清理 |
349
349
  | T1 | TypeScript 消费工程 | `PASS`:工作区与安装 tarball 都通过 NodeNext ESM/CJS 声明检查 | `moduleResolution: bundler` 和旧式 TS 解析 |
350
350
 
351
- 若项目实际使用其他版本,新增锁定版本的矩阵行后才声明支持。不能从 Webpack 5 最小工程通过推导所有 CRA 版本通过,也不能从 Vue 3 推导所有 Vue 2 工程通过。Vue 3、Vue 2.7、React + Vite 和 Vue 2 + Webpack 4 验证通过 yalc 指向本地构建,Webpack 5 验证通过安装的 `.tgz`;以上消费工程都没有访问真实 Gate。
351
+ 若项目实际使用其他版本,新增锁定版本的矩阵行后才声明支持。不能从 Webpack 5 最小工程通过推导所有 CRA 版本通过,也不能从 Vue 3 推导所有 Vue 2 工程通过。上文标注 yalc 的浏览器和 preview 结果是此前对工作区改动的历史验收;本轮三个 Vite Demo 使用 registry 发布包 `1.0.0-cg.7` 做了生产构建,隔离消费工程用 registry 包做了 Vite dev 插件对照。以上消费工程都没有访问真实 Gate。
352
352
 
353
353
  每个浏览器消费工程至少测试 `/` 和 `/app/` 子目录部署,以及深层业务路由进入/刷新。ESM npm 接入不应增加 `window.rtm` 依赖。
354
354
 
@@ -393,9 +393,9 @@ flowchart TD
393
393
  C --> D[源码回归和 npm tarball 安装]
394
394
  D --> E[开发和生产消费矩阵]
395
395
  E --> F[真实 Gate 多窗口验收]
396
- F --> G[候选标签发布]
396
+ F --> G[发布 latest]
397
397
  G --> H[从 registry 干净安装并复测]
398
- H --> I[提升 latest 并由业务试接入]
398
+ H --> I[业务试接入]
399
399
  I --> J[记录结果及回退信息]
400
400
  E -->|失败| C
401
401
  F -->|SDK 问题| C
@@ -408,18 +408,18 @@ flowchart TD
408
408
  | G1 本地候选包 | 构建、tarball 文件审计和安装 smoke test | 实施者 | `PASS`:`npm test` 中的本地源代码与 tarball 检查通过 |
409
409
  | G2 消费工程 | dev/build/运行日志、浏览器记录、类型检查结果 | 实施者/测试 | `PARTIAL`:Vue 3、Vue 2.7、React + Vite,Vue 2 + Webpack 4 的本地消费构建通过;普通 HTML 浏览器已观察到自动 Worker 请求。此次新增框架 Demo 共用同一状态模型和 RTC 运行时适配层;三种框架的 production preview 页面和 credential 状态 API 均通过,三个框架的四窗口本地模拟也完成。框架运行生命周期、子目录/深层路由及真实 Gate 仍待测 |
410
410
  | G3 真实业务链路 | Gate 环境标识、UID、连接/鉴权计数、消息与关闭记录 | 测试/联调人员 | `NOT_RUN`:本次没有使用真实 Gate 凭证 |
411
- | G4 候选发布 | registry、候选 tag 和 integrity | 有发布权限的维护者 | `NOT_RUN`:没有向 registry 发布或改 tag |
411
+ | G4 npm 发布 | registry、`latest` tag 和 integrity | 有发布权限的维护者 | `PASS`:registry `latest` 为 `1.0.0-cg.7`;三个 Vite Demo 均从 registry 安装并构建成功,lockfile 指向 npm tarball。registry integrity 与 npm `pack --dry-run` 已核对 |
412
412
  | G5 业务验收 | 现代项目与目标旧项目结果、回退版本 | 业务接入者 + SDK 维护者 | `NOT_RUN` |
413
413
 
414
- ### 6.1 候选发布与线上安装复测
414
+ ### 6.1 发布 latest 与线上安装复测
415
415
 
416
- 先确定实际 registry、原 `latest` 指向和版本号策略;这里不假定包在公共 npm,也不假定仓库版本已经发布。
416
+ 先确认实际 registry、当前 `latest` 指向和版本号策略;仓库构建本身不代表 npm 已发布。
417
417
 
418
- 发布使用新的候选版本和 `next` 等非 `latest` 标签,不覆盖已经发布的版本。发布操作由有权限的维护者执行,实施计划本身不代表已经发布。
418
+ 发布一个新的包版本,并直接使用 `latest` 标签。项目不使用 `next` 等预发布 dist-tag;发布操作由有权限的维护者执行。
419
419
 
420
- 从 registry 验证时,在干净消费工程安装候选的精确版本,并确认没有 yalc、源码 alias 或本地 tarball 残留。比对 registry 的 integrity 与准备发布的候选包;若发布流程重新构建使内容变化,对实际发布包重新执行关卡 G1—G3,不能复用旧包的通过记录。
420
+ 发布后在干净消费工程安装 `@cg-devcenter/rtc-fpnn-webjs-sdk@latest`,确认没有 yalc、源码 alias 或本地 tarball 残留。对比 registry integrity 与准备发布的包;若发布流程重新构建导致内容变化,应对实际发布包重新执行关卡 G1—G3,不能复用旧包的通过记录。
421
421
 
422
- 候选包复测通过后再提升 `latest`,随后用 `@latest` 在干净工程安装,核对确实解析到目标版本。业务工程保留精确版本和锁文件,避免自动升级干扰验收。
422
+ 只有 registry 安装和入口 smoke check 通过后,才把该版本作为可接入版本对外说明。生产业务工程可通过锁文件固定已验收的依赖,避免自动升级干扰发布。
423
423
 
424
424
  ### 6.2 回退
425
425
 
@@ -466,9 +466,10 @@ Node / npm / 浏览器版本:
466
466
 
467
467
  - `npm test` 通过,包含协议、文档、Demo、UMD/CJS、ESM、tarball 导入、Webpack 4 插件与 NodeNext 类型检查。
468
468
  - npm tarball 文件审计通过;安装到临时消费工程后,包根 ESM/CJS、Vite 插件、Webpack 4 插件及 ESM/CJS 类型导入通过。
469
- - Vite 6.4.4 的 Vue 3、Vue 2.7.16、React 18 Demo 均通过 yalc 本地链接和 production build;React 与 Vue 2.7 Demo 新增后复用框架无关的 `framework-demo.mjs` 状态模型、RTC 运行时适配及样式。三种框架的发送台和收件箱均在本地浏览器打开;Vue 3、Vue 2、React 的四窗口 BroadcastChannel 模拟均完成;生产 preview 页面及本机 credential 状态 API 均通过。Vue 2.7 + Webpack 4.47.0 yalc 消费工程 production build 通过并输出 Worker;Webpack 5.111.1 使用安装的 tarball 完成 production build。
470
- - 普通 HTML 在浏览器中创建共享客户端后观察到同目录 Worker 请求。框架组件卸载、多窗口 RTC 连接复用、子目录/深层路由、真实 Gate 和 registry 候选发布仍未验收。
469
+ - `1.0.0-cg.8` 本地 tarball 文件清单与内容已审计;未发现凭证、私钥、环境文件或开发机绝对路径。该检查不代表 npm 发布。
470
+ - 此前 Vue 3、Vue 2.7.16、React 18 Demo 的浏览器、preview 和四窗口 BroadcastChannel 模拟均通过,但当时使用 yalc 工作区包,属于本地改动验收。当前 npm `latest`(`1.0.0-cg.7`)已安装到三个 Vite Demo,Vue 3、Vue 2、React production build 均通过并输出独立 Worker;Vite 6.4.4 隔离 dev 对照实证不加 SDK 插件会把 Worker URL 指向错误目录,加 `/vite-plugin` 后 Worker 请求返回 200。Vue 2.7 + Webpack 4.47.0 yalc 消费工程 production build 通过并输出 Worker;Webpack 5.111.1 使用安装的 tarball 完成 production build。
471
+ - 普通 HTML 在浏览器中创建共享客户端后观察到同目录 Worker 请求。框架组件卸载、多窗口 RTC 连接复用、子目录/深层路由和真实 Gate 仍未验收。
471
472
 
472
473
  本地验证环境为 Node 20.20.1、npm 10.8.2、TypeScript 5.8.3。
473
474
 
474
- 本次没有发布 npm,也没有修改 registry tag。开发接入示例与限制见 [USAGE.md](USAGE.md);四个 Demo 的源码仓库专用说明位于 `examples/README.md`。
475
+ 当前 registry `latest`(`1.0.0-cg.7`)已发布现代包入口;此前用该 registry 包完成三个框架 Demo 的生产构建,`npm pack --dry-run` 仅核对当时的文件清单。本轮工作区 `1.0.0-cg.8` 则对实际 `.tgz` 文件清单与内容做了审计。以上都不代表已完成真实 Gate 或多窗口 RTC 验收,也不代表 `cg.8` 已发布。开发接入示例与限制见 [USAGE.md](USAGE.md);四个 Demo 的源码仓库专用说明位于 `examples/README.md`。
@@ -97,10 +97,12 @@ const independentClient = rtm.createClient({
97
97
  });
98
98
  ```
99
99
 
100
- 浏览器应用无需自行维护 Worker 名称或 URL。共享连接要求页面同源,并使用一致的连接配置;完整身份规则、生命周期和构建工具配置见[默认共享接入](USAGE.md#默认共享接入当前源码)。
100
+ 浏览器应用无需自行维护 Worker 名称或 URL。共享连接要求页面同源,并使用一致的连接配置;完整身份规则、生命周期和构建工具配置见[默认共享接入](USAGE.md#默认共享接入)。
101
101
 
102
102
  ### 启用 SharedWorker 后真正需要调整的地方
103
103
 
104
+ 工作区构建版本 `1.0.0-cg.8` 的 `createClient()` 会在配置不能安全传递给 Worker 时使用页面内 `RTMClient`,并通过 `getConnectionInfo()` 报告原因。npm `latest` `1.0.0-cg.7` 尚未包含这项配置回退和诊断;该版仅在浏览器缺少 SharedWorker 时使用页面内连接。`cg.8` 尚未发布到 npm。
105
+
104
106
  | 接入部分 | 迁移要求 |
105
107
  | --- | --- |
106
108
  | 创建客户端 | 将 `new RTMClient(options)` 改成 `createClient(options)`;默认 FPNN,SharedWorker 可用时共享、不可用时自动独立连接。UID 可继续从 `login()` 参数取得。 |
@@ -108,7 +110,7 @@ const independentClient = rtm.createClient({
108
110
  | 业务 API、结果和事件 | FPNN 方法名、callback / Promise 结果和 Push 名称沿用底层 SDK;包括 `fileToken` 和三种文件发送。Worker 不维护业务禁用名单。 |
109
111
  | 组件卸载 / 页面关闭 | 使用 `destroy()` 解绑当前页面;`bye()` / `close()` 会结束所有页面共享的 RTC 会话。不要继续用 `close()` 做单页清理。 |
110
112
  | 多页配置 | 同 UID 页面需使用相同 PID、协议、Gate 和连接配置;页面需同源并支持 SharedWorker。 |
111
- | 函数或平台对象配置 | 普通 `File` 可跨线程克隆;`md5` 函数、`platformImpl` 类实例、`webSocketFactory`、函数型 metadata 等不能直接跨线程保留执行行为。依赖这些自定义运行时的项目可继续独立模式。 |
113
+ | 函数或平台对象配置 | `createClient()` 检测到 `md5`、`platformImpl`、`webSocketFactory`、函数型 metadata 等无法保留到 Worker 的运行时值时,会自动使用当前页面内的 `RTMClient`,完整保留配置行为;用 `getConnectionInfo()` 查看 `mode` 和 `fallbackReason`。直接构造 `RTMSharedWorkerClient` 仍要求配置可传递,并会对不支持的值报出路径和原因。 |
112
114
  | 构建和部署 | 普通 HTML 将 Worker 与 SDK 部署在同源同目录;Vite 注册 `/vite-plugin`;Webpack 4 注册 `/webpack4` 插件;Webpack 5 使用包根 ESM 资源解析。 |
113
115
  | 会话筛选 | 默认全部 SDK 事件广播到所有页面端口。已有 `conversation` / `setConversation()` 用法继续可用,筛选只在页面适配器中执行。 |
114
116
 
package/docs/USAGE.md CHANGED
@@ -22,7 +22,7 @@
22
22
 
23
23
  请随文提供以下环境信息,避免接入者猜测项目配置或尝试从浏览器获取项目密钥:
24
24
 
25
- - SDK:测试项目可安装 npm `latest` 标签对应的版本:`npm install @cg-devcenter/rtc-fpnn-webjs-sdk@latest`。若验证的功能尚未进入 npm `latest`,请同时提供 yalc 链接、本地 tarball 或源码工作区。
25
+ - SDK:测试项目可安装 npm `latest` 标签对应的版本:`npm install @cg-devcenter/rtc-fpnn-webjs-sdk@latest`。包根 ESM 与 Vite、Webpack 4 构建插件均已随 npm `latest` 发布。当前工作区包版本 `1.0.0-cg.8` 尚未发布,registry `latest` 仍为 `1.0.0-cg.7`;下文标为工作区新版的 API 需使用本地源码或 `cg.8` 构建产物验证,不属于当前 npm `latest` 的能力。
26
26
  - RTC 环境:`pid`、协议(通常为 `tlv-v1`)、完整 WebSocket endpoint,以及应用页面的 origin。
27
27
  - 测试身份:发送 UID、接收 UID、账号权限和预期验证场景;不要在文档或任务描述中粘贴长期凭证。
28
28
  - credential 获取方式:由哪个业务服务端接口签发、请求需要的登录态/参数、响应 JSON 字段名和 credential 有效期。项目 `SecretKey` 只保留在受控服务端或本机签发工具中。
@@ -40,11 +40,19 @@
40
40
 
41
41
  ## 2. 快速开始:登录、收 Push、发消息、关闭
42
42
 
43
- ### 默认共享接入(当前源码)
43
+ ### 默认共享接入
44
44
 
45
- 新入口 `createClient(options)` 在浏览器支持 SharedWorker 时默认共享连接;浏览器没有 SharedWorker API 时自动创建独立的 `RTMClient`,业务 API、事件和 Promise 接口保持可用,但页面之间不共享连接或登录态。Worker 脚本加载失败、初始化失败或超时时会报告错误,不会被当作“不支持 SharedWorker”而静默降级。显式设置 `sharing: false` 可始终使用独立连接。省略 `protocol` 时默认使用 FPNN,以便从旧 `RTMClient` 构造方式迁移时保持协议一致;直接构造 `RTMSharedWorkerClient` 表示明确要求 Worker,浏览器不支持时会报错。只有显式设置 `protocol: 'tlv-v1'` 才选择 TLV v1。请使用 npm `latest` 标签对应的版本;若该标签尚未包含此入口或 FPNN 共享扩展,请使用本地构建/yalc。旧 `RTMClient` 的业务 API 保留;共享连接按 PID、协议、UID 和 Gate endpoint 区分环境;两个共享入口在协议及其他连接参数一致时可复用同一会话。
45
+ 工作区 `1.0.0-cg.8` 的 `createClient(options)` 优先使用 SharedWorker;浏览器不支持 SharedWorker,或配置中含有无法保留到 Worker 的运行时值(例如函数型 `webSocketFactory`、`md5`、`platformImpl` 或 metadata)时,会自动使用当前页面内的 `RTMClient`。两种模式使用同一个 `createClient()` facade、业务 API、事件和 Promise 接口;页面内模式不共享连接或登录态。该版本可通过 `client.getConnectionInfo()` 读取 `{ mode: 'shared' | 'direct', fallbackReason: string | null }`。`sharing: false` 会主动选择页面内模式,`fallbackReason` 为 `null`。Worker 脚本加载失败、初始化失败或超时仍会报告错误,不会静默改成页面内连接。省略 `protocol` 时默认使用 FPNN;直接构造 `RTMSharedWorkerClient` 表示明确要求 Worker,不能传输的配置会抛出具体原因。只有显式设置 `protocol: 'tlv-v1'` 才选择 TLV v1。npm `latest` `1.0.0-cg.7` 包含 `createClient()` 入口和 FPNN SharedWorker 扩展,但尚不支持配置值导致的自动直连回退,也没有 `getConnectionInfo()`;这些能力尚未发布到 npm。当前 npm 版本仍会在浏览器缺少 SharedWorker 时使用页面内连接。共享连接按 PID、协议、UID 和 Gate endpoint 区分环境;两个共享入口在连接参数一致时可复用同一会话。
46
46
 
47
- 现代 ESM 项目从包根导入。Worker URL 按构建工具解析:Vite 在 `vite.config.js` 注册一次 SDK 插件;Webpack 4 注册 SDK 的 `/webpack4` 插件;Webpack 5 使用包根 ESM 入口和标准资源解析。普通 HTML 将 SDK 脚本和 Worker 文件放在同源同目录。上述常规方式都不需要业务传 `workerUrl`;只有自定义 Worker 部署位置时才需要覆盖它。旧 `/vite` 入口继续兼容。包根入口和插件是当前仓库实现,尚未发布到 npm;正式安装前请确认使用的版本已包含它们。下面可作为 Vite 页面脚本使用,替换项目配置和 credential 接口:
47
+ ```js
48
+ const client = rtm.createClient({ pid, endpoint, webSocketFactory });
49
+ if (typeof client.getConnectionInfo === 'function') {
50
+ console.log(client.getConnectionInfo());
51
+ // { mode: 'direct', fallbackReason: 'options.webSocketFactory is a function; SharedWorker cannot preserve page-side function behavior' }
52
+ }
53
+ ```
54
+
55
+ 现代 ESM 项目从包根导入。Worker URL 按构建工具解析:Vite 开发模式在 `vite.config.js` 注册一次 SDK 插件,避免依赖预构建将 SDK 的 `import.meta.url` 移入 `.vite/deps`;生产 Worker 资源由 Vite 构建输出。Webpack 4 注册 SDK 的 `/webpack4` 插件;Webpack 5 使用包根 ESM 入口和标准资源解析。普通 HTML 将 SDK 脚本和 Worker 文件放在同源同目录。上述常规方式都不需要业务传 `workerUrl`;只有自定义 Worker 部署位置时才需要覆盖它。旧 `/vite` 入口继续兼容。包根 ESM 与构建插件已包含在 npm `latest` 中。下面可作为 Vite 页面脚本使用,替换项目配置和 credential 接口:
48
56
 
49
57
  ```js
50
58
  import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk';
@@ -91,15 +99,15 @@ UID 使用正整数或十进制字符串;超过 JavaScript 安全整数范围
91
99
 
92
100
  | 配置 / API | 默认与边界 |
93
101
  | --- | --- |
94
- | `createClient(options)` | 使用扁平客户端配置,默认 `sharing: true`、`protocol: 'fpnn'`;浏览器没有 SharedWorker API 时自动回退为当前页面的独立连接。 |
95
- | `sharing: false` | 返回独立的 `RTMClient`,省略协议时仍默认 FPNN。Node.js 需显式设置 `protocol: 'tlv-v1'` 并提供 `webSocketFactory`;FPNN 仍仅支持浏览器。 |
102
+ | `createClient(options)` | 使用扁平客户端配置,默认优先共享、协议默认 `fpnn`;无法使用 SharedWorker 或配置含不可传输的运行时值时,自动回退为当前页面连接,并可用 `getConnectionInfo()` 查询模式和原因。 |
103
+ | `sharing: false` | 显式选择页面内连接,但仍返回相同的 `createClient()` facade。Node.js 使用 TLV 时传 `protocol: 'tlv-v1'` 和 `webSocketFactory`;FPNN 仍仅支持浏览器。 |
96
104
  | `uid` | 可选;提供时立即挂接共享 Worker,适合收件箱自动观察其他页面登录。省略时在 `login()` / `loginIfNeeded()` / `whenReady(uid)` 时挂接。一个实例固定一个 UID;切换账号需 detach 后创建新实例。 |
97
105
  | `workerName` / `workerUrl` | 可选高级覆盖项;常规接入不需要配置 `workerUrl`。默认共享身份由 PID、协议、UID 和 Gate endpoint 生成,endpoint 不需要单独配置。普通 HTML 使用脚本同目录规则;Vite 使用 `/vite-plugin`;Webpack 4 使用 `/webpack4`;Webpack 5 使用标准 ESM 资源解析。只有自定义 Worker 部署位置时才传同源 `workerUrl`。`workerNamespace` 仍可隔离应用。 |
98
106
  | `whenReady(uid?)` | 等待首次挂接并返回当时的快照;后续状态用 `getSharedSession()` 或 `SharedSessionState` 读取。尚未绑定 UID 且未传 UID 时立即 reject `RTM_SHARED_UID_REQUIRED`,不会无限等待。 |
99
107
  | `promises.login(uid, credential?, timeout?)` | 成功 resolve `{accepted: true, errorCode}`,RTC 拒绝或本地/Worker 错误 reject;并发同 UID 登录只发一次鉴权。`loginIfNeeded()` 保留 `{accepted, errorCode, reused, uid}` 的结果约定。 |
100
108
  | `login(uid, credential?, callback?, timeout?)` | RTC 拒绝回调 `callback(false, numericCode)`;共享模式的本地/Worker 失败会通过 `SharedWorkerError` 提供详情。仅 `accepted === true` 表示登录成功;`promises.login()` 会 reject 详细错误。 |
101
109
  | `destroy()` | 共享模式只 detach 当前页面;最后一页离开后按 `idleShutdownTimeout` 回收共享连接。独立模式关闭本页的 RTMClient。`bye()` / `close()` 结束当前连接。 |
102
- | 会话路由与业务 API | 沿用 `setConversation()`、`processor`、重连和原协议的业务返回;业务能力由底层 `RTMClient` 决定,FPNN 文件发送可用;函数型配置不能跨线程克隆。绑定 UID 前的业务请求明确报 `RTM_SHARED_UID_REQUIRED`。 |
110
+ | 会话路由与业务 API | 沿用 `setConversation()`、`processor`、重连和原协议的业务返回;业务能力由底层 `RTMClient` 决定,FPNN 文件发送可用。`createClient()` 会为函数或自定义实例配置自动选择页面内模式;直接 `RTMSharedWorkerClient` 则要求配置可传给 Worker。绑定 UID 前的业务请求明确报 `RTM_SHARED_UID_REQUIRED`。 |
103
111
 
104
112
  共享还要求同一浏览器配置文件、origin 和 Worker URL。同一浏览器配置文件、origin、Worker URL、PID、协议、UID 和 Gate endpoint 的页面会复用一条连接;Gate 地址不同会自动隔离。**同一共享身份下的 `clientOptions` 必须一致**;认证、重连或其他参数不同会初始化失败,不会覆盖已有连接。`createClient()` 和 `RTMSharedWorkerClient` 自动使用相同规则,同一应用混用入口也能加入同一会话。显式传入 `workerName` 或 `workerNamespace` 时,共享页面仍须保持一致。
105
113
 
@@ -214,7 +222,7 @@ module.exports = {
214
222
 
215
223
  Webpack 5 项目从包根 ESM 入口导入即可使用标准资源解析,不需要 SDK 插件。无论使用 Vue、React 还是普通 JS,页面里的客户端创建方式相同。
216
224
 
217
- 浏览器可加载 `dist/rtm.min.js` 并从 `window.rtm` 取 SDK。Node.js 仅支持 TLV v1;需要在 `RTMClient` 选项中传入 `webSocketFactory(url)`,返回对象须支持 `send(data)`、`close(code?, reason?)` 及 `onopen`、`onmessage`、`onerror`、`onclose`。SDK 不附带 Node WebSocket 实现。`fpnn` 和 SharedWorker 仅面向浏览器。
225
+ 浏览器可加载 `dist/rtm.min.js` 并从 `window.rtm` 取 SDK。Node.js 仅支持 TLV v1;通过 `RTMClient` 或 `createClient()` 传入 `webSocketFactory(url)`,返回对象须支持 `send(data)`、`close(code?, reason?)` 及 `onopen`、`onmessage`、`onerror`、`onclose`。`createClient()` 在 Node.js 会报告 direct 模式。SDK 不附带 Node WebSocket 实现。`fpnn` 和 SharedWorker 仅面向浏览器。
218
226
 
219
227
  若用 unpkg 或 jsDelivr 加载 `rtm.min.js`,不要让 SDK 自动推导共享 Worker 地址:推导出的 Worker 会落在 CDN 域名,与业务页面不同源。可把同版本的 `rtm.shared-worker.js` 部署到应用自己的同源静态目录,并显式传入 `workerUrl`;如果不需要多页面共享,可设置 `sharing: false`。例如:
220
228
 
@@ -260,9 +268,9 @@ SharedWorker 仍要求 Worker 与页面同源;仅配置跨域 CORS 不会满
260
268
  | `autoReconnect` | `boolean` | `true` | 自动重连开关。终止性鉴权错误不会无限重试。 |
261
269
  | `connectionTimeout` | `number` | `30000` | 建立 WebSocket 连接的超时。 |
262
270
  | `requestTimeout` | `number` | `20000` | 请求默认超时;方法级 `timeout > 0` 时覆盖此值。 |
263
- | `requestMetadata` | `object \| (() => object)` | 可选 | TLV v1 只发送 `trace`、`sent_ms`。禁止放 credential、SecretKey 等敏感字段。SharedWorker 仅接受静态对象。 |
264
- | `requestMetadataProvider` | `() => object` | 可选 | `requestMetadata` 函数形式的兼容选项;SharedWorker 不支持函数。 |
265
- | `webSocketFactory` | `(url) => RTMWebSocket` | Node 必填 | 自定义 WebSocket 工厂。浏览器通常使用全局 `WebSocket`。 |
271
+ | `requestMetadata` | `object \| (() => object)` | 可选 | TLV v1 只发送 `trace`、`sent_ms`。禁止放 credential、SecretKey 等敏感字段。SharedWorker 仅接受静态可传输对象;函数形式会使 `createClient()` 回退到页面内连接。 |
272
+ | `requestMetadataProvider` | `() => object` | 可选 | `requestMetadata` 函数形式的兼容选项;通过 `createClient()` 使用时会自动选择页面内连接。 |
273
+ | `webSocketFactory` | `(url) => RTMWebSocket` | Node 必填 | 自定义 WebSocket 工厂。浏览器通常使用全局 `WebSocket`;`createClient()` 会在配置该函数时选择页面内连接。 |
266
274
  | `authSec` / `authVer` | `number` / `2` | 可选 | 自签鉴权字段;须同时提供,且 `authVer` 必须为 `2`。 |
267
275
  | `locale` / `clientVersion` | `string` | 可选 | 登录语言和客户端版本。未提供版本时 SDK 使用内置版本字符串。 |
268
276
  | `attrs` | `Record<string, string>` | 可选 | 登录连接属性。 |
@@ -389,11 +397,11 @@ connectInbox().catch(console.error);
389
397
  - 最后一个页面 detach 后,SDK 默认等待 5 秒再销毁 RTMClient 和连接;宽限期内新页面接入会取消回收。浏览器也可能在页面挂起或资源回收时结束 Worker,但 SDK 当前没有就绪后的心跳检测,浏览器静默回收不保证触发事件。
390
398
  - 收到 `SharedWorkerError` 时,表示 SDK 检测到当前页面到 Worker 的错误(例如初始化失败、Worker `error` 或消息端口错误),可丢弃旧 client 并用相同连接配置创建新 client。此事件不是 Worker 被浏览器回收的通用通知;如果浏览器静默结束 Worker,页面可能无法及时获知。新 client 的登录快照若为 `idle`,重新登录时必须取得服务端为该 UID 签发的 credential。SDK 不在页面、Worker 或存储中持久化 credential,也不会在 Worker 进程丢失后自动重登。
391
399
  - SharedWorker 仅共享实时连接和 Push,不同步页面草稿、未读 UI 或消息列表,也不持久化登录态。它不跨 origin、浏览器配置文件或 InPrivate 窗口共享;浏览器没有 SharedWorker API 时,`createClient()` 会改用每页一条独立连接,因此这些页面不能共享登录态。Worker 脚本加载或初始化失败仍会报告错误。
392
- - `clientOptions` 必须可结构化克隆;不能包含 `requestMetadataProvider`、元数据函数或 `webSocketFactory`。SharedWorker 只接受静态 `requestMetadata` 对象。
400
+ - 直接构造 `RTMSharedWorkerClient` 时,`clientOptions` 必须可安全传递给 Worker;函数、循环引用、访问器和自定义原型实例会抛出带配置路径的错误。通过 `createClient()` 时,这些配置会改用页面内 `RTMClient`,原因可通过 `getConnectionInfo()` 查询。
393
401
 
394
402
  ### FPNN 多窗口接入
395
403
 
396
- FPNN SharedWorker 的可用性以 npm `latest` 标签对应的 SDK 版本为准;若该标签版本尚未包含此扩展,请使用本地构建或 yalc。Node.js 仍只支持 TLV。
404
+ FPNN SharedWorker 已包含在 npm `latest` 中。Node.js 仍只支持 TLV。
397
405
 
398
406
  首次登录、后续窗口 `loginIfNeeded()`、`SharedSessionState`、路由和 detach 的使用方式与上面的 TLV 示例相同。FPNN 只改变连接配置和 Push 订阅;以下片段假定已加载 `rtm` 并取得 `pid`、`uid`、`peerUid`、FPNN Gate 地址及首次登录所需的 credential:
399
407
 
@@ -601,7 +609,7 @@ TLV 不支持的调用按实现分为三类:
601
609
  - 未登记且非保留的 wire 返回 `20004`(`RTM_EC_UNKNOWN_METHOD`)。
602
610
  - 共享客户端原样转发 SDK 请求及结果。TLV 文件发送由底层 `filetoken` 的契约校验拒绝;callback 收到 `{mid, error}`,其中 `error.code` 为 `200020`,Promise 版本 reject 同一对象。
603
611
 
604
- 这些错误都不会自动切换到 FPNN。SharedWorker 的 TLV 模式复用 TLV 支持范围;FPNN 模式可转发其兼容业务 API,包括文件发送。两种模式都不接受函数型配置;`clientOptions` 必须可结构化克隆。FPNN 兼容能力列表见[能力总览](CAPABILITIES.md),服务端支持仍需单独确认。
612
+ 这些错误都不会自动切换到 FPNN。SharedWorker 的 TLV 模式复用 TLV 支持范围;FPNN 模式可转发其兼容业务 API,包括文件发送。通过 `createClient()` 使用函数型配置会自动选择页面内 `RTMClient`;直接构造 `RTMSharedWorkerClient` 时,`clientOptions` 必须可安全传递给 Worker。FPNN 兼容能力列表见[能力总览](CAPABILITIES.md),服务端支持仍需单独确认。
605
613
 
606
614
  ## 7. 调试与参考
607
615
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cg-devcenter/rtc-fpnn-webjs-sdk",
3
- "version": "1.0.0-cg.7",
3
+ "version": "1.0.0-cg.8",
4
4
  "description": "Browser RTM SDK with FPNN and TLV v1 MessagePack WebSocket transports",
5
5
  "main": "./dist/rtm.min.js",
6
6
  "browser": "./dist/rtm.min.js",