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

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.
@@ -0,0 +1,474 @@
1
+ # npm 接入现代化:实现与验证记录
2
+
3
+ 状态:源码实现与本地包验证已完成。真实 Gate 多窗口验收、registry 候选发布和业务试接入尚未执行;仓库修改不代表 npm 上的版本已经更新。2026-10-13 查询 registry 时,`latest` 仍为 `1.0.0-cg.6`,该版本没有包根 ESM 或 `/vite-plugin` 导出;发布新版后应更新此记录。
4
+
5
+ 本文基于 2026-10-13 的仓库状态编写。范围是 SDK 发布格式、Worker 资源接入和兼容验证。协议与业务 API 继续遵循 [接入指南](USAGE.md) 和 [协议迁移说明](PROTOCOL_MIGRATION.md)。
6
+
7
+ ## 1. 要解决的问题与完成标准
8
+
9
+ 改造前的入口基线如下:
10
+
11
+ | 当前入口 | 仓库实现 | 接入成本 |
12
+ | --- | --- | --- |
13
+ | 包根入口 | `main`、`browser`、`exports["."]` 指向 `dist/rtm.min.js`,即 UMD | npm 的 ESM 接入依赖 UMD/CommonJS 互操作;共享连接需要处理 Worker 资源地址 |
14
+ | `/vite` | `dist/rtm.vite.mjs` 包装 UMD,并以 `?url` 导入 Worker | 业务选择专用入口;现有 Demo 还配置 `optimizeDeps.include/exclude` |
15
+ | 普通 HTML | 加载 `rtm.min.js`,从 `window.rtm` 使用 | 主脚本与 Worker 同源、同目录时,SDK 自动定位 Worker |
16
+ | CommonJS | `require()` 加载 UMD | Node 可加载 SDK;TLV 独立连接仍需注入 WebSocket 实现 |
17
+
18
+ 改造后,`npm run build` 还会生成包根 ESM、入口类型和构建插件。现代 ESM 项目从包根导入;Vite 在配置中增加一次 SDK 插件;Webpack 4 使用 `/webpack4` 插件。普通脚本和 CommonJS 仍走原 UMD 文件,旧 `/vite` 路径保留。
19
+
20
+ 目标是让 Vue 2、Vue 3、React、普通 JS 和 TypeScript 使用同一套 SDK API。构建工具的差异由发布格式和配套插件处理。
21
+
22
+ 完成标准:
23
+
24
+ 1. 现代 npm 项目可从包根进行默认导入和具名导入;业务代码不填写默认 `workerUrl`,不复制 Worker 文件。
25
+ 2. 支持范围内的 Vite、Webpack 5 在开发服务器和生产构建中均能使用共享连接。优先实现零额外配置;若某版本需要插件,支持矩阵明确标注,插件负责完整配置。
26
+ 3. Webpack 4 项目最多添加一次 SDK 构建插件,不要求业务维护资源路径。
27
+ 4. 普通 HTML 的 `window.rtm`、现有 CommonJS、旧 `/vite` 和公开 API 继续可用。
28
+ 5. 同 UID 多页面仍复用同一个 Worker 和一条 Gate WebSocket;`destroy()` 只释放当前页面。
29
+ 6. 使用实际 npm tarball 和候选发布版本完成验证,保留可追溯证据后再更新线上发布标签。
30
+
31
+ “任意构建工具都零配置”不作为承诺。Vue/React 版本不能代替构建工具版本作为支持依据。
32
+
33
+ ## 2. 目标使用方式与兼容边界
34
+
35
+ ### 2.1 现代 npm 项目
36
+
37
+ 现代 npm 项目从包根进行默认导入和具名导入,业务代码不填写默认 `workerUrl`,不复制 Worker 文件:
38
+
39
+ ```js
40
+ import rtm, { createClient, RTMConfig } from '@cg-devcenter/rtc-fpnn-webjs-sdk';
41
+
42
+ // pid、endpoint、uid、credential 由业务提供。
43
+ const client = createClient({
44
+ protocol: 'tlv-v1',
45
+ pid,
46
+ tlvEndpoint: endpoint,
47
+ uid,
48
+ autoReconnect: true,
49
+ });
50
+
51
+ client.processor.on(RTMConfig.TLV_SERVER_PUSH.recvMessage, renderMessage);
52
+ await client.promises.login(uid, credential);
53
+ await client.promises.sendChat(peerUid, 'hello', '{}');
54
+
55
+ // 页面/组件释放时调用;共享连接的其他页面继续使用。
56
+ client.destroy();
57
+ ```
58
+
59
+ Vite 项目只在构建配置中增加一次 SDK 插件;应用模块仍然从包根导入:
60
+
61
+ ```js
62
+ // vite.config.js
63
+ import { rtmSdkVitePlugin } from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite-plugin';
64
+
65
+ export default {
66
+ plugins: [rtmSdkVitePlugin()],
67
+ };
68
+ ```
69
+
70
+ 默认导入 `rtm.createClient()` 与具名导入 `createClient()` 必须执行同一套资源解析逻辑。底层 `RTMSharedWorkerClient` 构造器也必须获得相同的默认 Worker 地址,不能只修工厂入口。
71
+
72
+ ### 2.2 普通 HTML 与 CommonJS
73
+
74
+ 普通 HTML 继续部署 `rtm.min.js` 和 `rtm.shared-worker.js` 到同源、同目录:
75
+
76
+ ```html
77
+ <script src="/sdk/rtm.min.js"></script>
78
+ <script>
79
+ const client = window.rtm.createClient({
80
+ protocol: 'tlv-v1',
81
+ pid: 12345,
82
+ tlvEndpoint: 'wss://<gate-host>/service/websocket',
83
+ });
84
+ // 后续仍使用现有 login、processor、promises API。
85
+ </script>
86
+ ```
87
+
88
+ CommonJS 继续支持:
89
+
90
+ ```js
91
+ const rtm = require('@cg-devcenter/rtc-fpnn-webjs-sdk');
92
+ ```
93
+
94
+ Node 导入阶段不能访问不存在的浏览器全局或启动 Worker。Node 的 TLV 独立连接继续由调用方传入 `webSocketFactory`;FPNN 和共享连接的浏览器边界保持明确。
95
+
96
+ Vue 2 在 `mounted` 创建实例、在 `beforeDestroy` 释放;React 在 `useEffect` 创建实例并返回清理函数。包不需要 Vue/React 专属适配器。
97
+
98
+ ```js
99
+ // Vue 2 生命周期示意
100
+ import { createClient } from '@cg-devcenter/rtc-fpnn-webjs-sdk';
101
+
102
+ export default {
103
+ mounted() {
104
+ this.rtmClient = createClient({ protocol: 'tlv-v1', pid, tlvEndpoint: endpoint, uid });
105
+ },
106
+ beforeDestroy() {
107
+ if (this.rtmClient) this.rtmClient.destroy();
108
+ },
109
+ };
110
+ ```
111
+
112
+ ```jsx
113
+ // React 生命周期示意
114
+ import { useEffect } from 'react';
115
+ import { createClient } from '@cg-devcenter/rtc-fpnn-webjs-sdk';
116
+
117
+ function useRtmClient({ pid, endpoint, uid }) {
118
+ useEffect(() => {
119
+ const client = createClient({ protocol: 'tlv-v1', pid, tlvEndpoint: endpoint, uid });
120
+ return () => client.destroy();
121
+ }, [pid, endpoint, uid]);
122
+ }
123
+ ```
124
+
125
+ ### 2.3 必须保留的行为
126
+
127
+ | 行为 | 改造约束 |
128
+ | --- | --- |
129
+ | `new RTMClient()` | 保留原有协议默认值、callback、Promise、事件与关闭语义 |
130
+ | `createClient()` | 默认 FPNN 以兼容旧 `RTMClient` 协议;SharedWorker API 可用时共享,浏览器不提供该 API 时自动使用独立连接;TLV 由调用方显式选择;Worker 资源或初始化失败时不静默降级 |
131
+ | `sharing: false` | 独立连接,不创建 Worker、不发起 Worker 网络请求 |
132
+ | `workerUrl` | 保留为显式覆盖项;优先于构建工具生成的默认地址 |
133
+ | UID 与环境隔离 | 沿用 PID、协议、UID、Gate endpoint 和现有名称规则 |
134
+ | `destroy()` | 共享模式只 detach 当前页;最后一页按既有闲置时间回收 |
135
+ | `bye()` / `close()` | 继续结束整个共享会话 |
136
+ | `/vite`、`/shared-worker`、`/dist/*` | 保留已公开路径;迁移期间不突然移除 |
137
+ | credential | 由后端签发;不新增持久化或跨构建入口的隐式保存 |
138
+
139
+ 不同页面只有在浏览器配置文件、origin、实际 Worker URL 和共享身份配置一致时才共享连接。独立构建的两个站点即使包版本一致,也可能产生不同的资源 URL,不能直接承诺共享。
140
+
141
+ ## 3. 实现方案
142
+
143
+ ### 3.1 发布 ESM 与兼容入口
144
+
145
+ `scripts/build-modern.mjs` 从 SDK 实现构建 ESM,并从 `types/` 复制维护中的类型声明和插件入口。CommonJS 继续使用已有 UMD 文件,避免新增另一份运行时实现;普通浏览器也继续使用该 UMD。
146
+
147
+ 产物职责如下:
148
+
149
+ | 产物 | 职责 |
150
+ | --- | --- |
151
+ | `dist/rtm.mjs` | 现代浏览器/构建工具的 ESM,支持默认与具名导出 |
152
+ | `dist/rtm.min.js` | UMD / CommonJS,继续提供 `window.rtm` 和 `require()` |
153
+ | `dist/rtm.shared-worker.js` | 完整、可独立执行的 classic SharedWorker;不依赖页面环境 |
154
+ | `dist/rtm.d.mts`、`dist/rtm.d.cts` | 分别描述 ESM 与 CommonJS 入口 |
155
+ | `dist/rtm.d.ts` | 由 `types/rtm.d.ts` 生成,保留普通 JS/旧解析方式需要的声明入口 |
156
+ | `dist/rtm.vite-plugin.mjs` | Vite 依赖预构建适配器 |
157
+ | `dist/rtm.webpack4-plugin.cjs`、`dist/rtm.webpack4-adapter.cjs` | Webpack 4 插件与 UMD 资源适配入口 |
158
+ | 兼容入口 | 保留 `/vite`、`/shared-worker` 和现有 `/dist/*` |
159
+
160
+ ESM 必须由源码构建,不能继续简单套用已压缩的 UMD。现有实现与依赖中有 CommonJS 和初始化副作用,首版不承诺完整 tree shaking,也不直接给包设置 `sideEffects: false`。
161
+
162
+ 根 `exports` 的实际条件结构如下;其余公开子路径也保留在 `package.json`:
163
+
164
+ ```json
165
+ {
166
+ "exports": {
167
+ ".": {
168
+ "import": {
169
+ "types": "./dist/rtm.d.mts",
170
+ "default": "./dist/rtm.mjs"
171
+ },
172
+ "require": {
173
+ "types": "./dist/rtm.d.cts",
174
+ "default": "./dist/rtm.min.js"
175
+ }
176
+ }
177
+ }
178
+ }
179
+ ```
180
+
181
+ `module` 指向 ESM,`main` 和 `browser` 保持指向 UMD,顶层 `types` 保留旧解析方式。Webpack 4 不通过 `module` 直接解析 ESM;使用 `/webpack4` 插件时,插件把包根 alias 到兼容适配器。
182
+
183
+ 类型声明基于同一份公开 API 定义维护,检查默认导入、具名导入、`import = require()`、JS 全局命名空间及 `workerUrl` 覆盖。不要用 `skipLibCheck` 掩盖入口类型不匹配。
184
+
185
+ ESM 与 CommonJS 混用时可能出现两个模块实例;不能承诺跨格式 `instanceof` 恒成立。资源解析采用实例配置,避免新增必须共享的全局可变配置;已有 API 的模块状态要纳入回归。
186
+
187
+ ### 3.2 Worker 地址由 SDK 与构建工具处理
188
+
189
+ 优先复用完整的 `rtm.shared-worker.js`,把它作为构建资源交给消费工程;保留 Worker 内的协议、登录复用和 Push 分发实现。
190
+
191
+ 实际 ESM 入口在包内使用相对模块 URL 解析完整 Worker 文件:
192
+
193
+ ```js
194
+ function resolveDefaultWorkerUrl() {
195
+ return new URL('../dist/rtm.shared-worker.js', import.meta.url).href;
196
+ }
197
+ ```
198
+
199
+ 由入口在创建共享客户端时注入上述地址,优先采用业务显式传入的 `workerUrl`。独立连接和纯模块导入不执行 Worker 创建。解析逻辑集中维护,默认导出、具名导出与共享构造器都复用它。
200
+
201
+ 选择独立 Worker 资源有两个好处:资源内容可以继续使用当前 standalone 构建;Worker 名称仍由 SDK 在运行时根据 UID 计算。
202
+
203
+ Vite 生产构建和 Webpack 5 会把相对模块 URL 输出为构建资源。Vite 6 开发模式若预构建 SDK,会把 `import.meta.url` 移入 `.vite/deps`,导致 Worker 解析错误;`/vite-plugin` 将包根与旧 `/vite` 子路径排除在依赖预构建之外,保留 Vite 对模块 URL 的处理。
204
+
205
+ 现代入口失败时使用 SDK 配套构建插件完成资源输出与解析;不能退回让业务手写默认路径并仍宣称“零配置”。
206
+
207
+ ### 3.3 Vite 兼容与预构建
208
+
209
+ 已在仓库 Demo 的 Vite 6.4.4 环境验证包根入口的开发模块解析与生产构建;本地使用 yalc 迭代,独立 tarball 另做安装及入口/类型检查。
210
+
211
+ Demo 已迁移到包根入口,并删除过去为 UMD 和 `?url` 设置的 `optimizeDeps.include/exclude`。插件会排除包根与旧 `/vite` 子路径;保留旧 `/vite` 作为迁移兼容入口。
212
+
213
+ 新接入使用 `/vite-plugin` 配置一次,应用代码仍从包根导入。旧项目可继续使用 `/vite`;该入口仍使用原来的 `?url` 资源引用方式。
214
+
215
+ #### Vite 迁移步骤与放行条件
216
+
217
+ Vite 也使用通用包根入口,这是本次改造的明确目标。新项目不再把 `/vite` 作为推荐业务入口;旧 `/vite` 保留原有资源引用方式和默认、具名导出。
218
+
219
+ 应用代码迁移示例:
220
+
221
+ ```js
222
+ // 当前入口。
223
+ import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite';
224
+
225
+ // 改造后默认导入;与现有 rtm.createClient() 调用兼容。
226
+ import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk';
227
+
228
+ // 或改用通用具名导入。
229
+ import { createClient } from '@cg-devcenter/rtc-fpnn-webjs-sdk';
230
+ ```
231
+
232
+ 以上三个导入展示迁移选择,不应放在同一个文件同时声明同名变量。
233
+
234
+ 迁移按以下顺序验证:
235
+
236
+ 1. 在独立 tarball 消费工程使用包根入口,移除 SDK 专属的 `optimizeDeps.include/exclude`、手动 Worker 路径和源码 alias;保留项目其他依赖需要的配置。
237
+ 2. 测试无缓存冷启动和已预构建后的重启、源码 HMR、SDK 版本更新后的重新预构建,确认 Worker 请求地址、内容和版本对应。
238
+ 3. 执行 production build 与 preview,在 `/`、`/app/` 和深层路由中验证自动资源加载;再验证同 UID 两页面一条 WebSocket、页面释放和显式 `workerUrl` 覆盖。
239
+ 4. Vite 6.4.4 dev 下根入口与旧 `/vite` 都解析到同一 Worker 文件;生产混用构建只输出一个 Worker 资源。还需在正式浏览器里验证混用入口后确实复用同一连接。
240
+ 5. 仓库 Vite Demo 的两处 SDK 导入(`src/state/demo.js`、`src/lib/rtc.js`)已迁移,SDK 专属的 `optimizeDeps.include/exclude` 已删除,Demo README 和接入指南已更新。yalc 仅用于仓库本地迭代,不是 npm 消费要求。
241
+
242
+ 完成后按锁定的 Vite 版本记录结果:
243
+
244
+ | 实测结果 | 最终接入要求 | 对外描述 |
245
+ | --- | --- | --- |
246
+ | 上述流程无需额外 SDK 配置即可通过 | 包根导入即可 | 该版本支持零额外配置 |
247
+ | 需要预构建或资源适配,配套插件可使全部流程通过 | 包根导入 + 一次插件配置;SDK 特殊处理由插件维护 | 该版本需要配套插件 |
248
+ | 仅 build 通过、开发失败,或 Worker/共享行为仍有问题 | 继续修复;已验证的旧入口仍按原用法使用 | 通用入口尚未验收,不宣布迁移完成 |
249
+
250
+ Vite 6.4.4 的开发预构建需要插件,所以本实现不宣称 Vite 零额外配置。已验证根入口 + 插件的 dev 模块解析和 production build;preview、冷缓存重启、HMR、深层路由和浏览器中的实际 Worker 启动仍需在消费工程完成。
251
+
252
+ ### 3.4 Webpack 5 与 Webpack 4
253
+
254
+ Webpack 5 使用标准 ESM 相对资源 URL。已用独立安装的 tarball 在 Webpack 5.111.1 production 工程验证编译,并看到完整 SharedWorker 文件输出为独立资源;仍需补 dev server、子目录部署和浏览器运行验证。
255
+
256
+ Webpack 4 不按现代 `import.meta.url` 能力设计。`/webpack4` 插件负责:
257
+
258
+ 1. 从已安装 SDK 包读取与主入口匹配的 Worker 文件,开发时可访问,生产时输出到 assets。
259
+ 2. 用兼容 Webpack 4 的适配入口注入构建生成的文件名和应用资源前缀,不使用 ESM 专用语法。
260
+ 3. 只重定向需要适配的 SDK 包根入口;防止适配入口再引用自己造成循环解析。
261
+ 4. 默认导入、具名导入和共享构造器都走一致的资源解析。
262
+ 5. watch/HMR 重建时更新资源;主包与 Worker 版本一起变化。
263
+
264
+ 插件通过 `resolve.alias` 重定向包根,因此不需要独立 `webpack.js` 运行入口。插件只用 Node 内置模块,导入配置时不要求 SDK 运行依赖,也不把 Webpack 构建依赖带进浏览器运行包。已用 Webpack 4.47.0 编译最小消费入口,检查 Worker 输出和 `/static/` publicPath。
265
+
266
+ Webpack 4 的配置写法:
267
+
268
+ ```js
269
+ const RTMSDKWebpack4Plugin = require('@cg-devcenter/rtc-fpnn-webjs-sdk/webpack4');
270
+
271
+ module.exports = {
272
+ plugins: [new RTMSDKWebpack4Plugin()],
273
+ };
274
+ ```
275
+
276
+ 不通过 npm 安装脚本向业务的 `public/` 写文件。Worker 应作为构建产物由插件管理,SDK 更新后随业务重建与部署更新。
277
+
278
+ ### 3.5 部署与错误处理
279
+
280
+ Worker 必须最终在页面同源地址提供,并被站点 CSP 允许。资源前缀为跨域 CDN 时不能假定 SharedWorker 可以直接加载;需要应用同源资源路由或显式覆盖部署路径,并给出明确诊断。
281
+
282
+ 主脚本和 Worker 原子部署,版本变化产生对应资源更新。普通 HTML 保留原文件名;npm 构建可以使用内容 hash。新旧页面同时存活的情况下,明确共享边界,不强行合并不同版本的会话。
283
+
284
+ 同一应用的包根入口与兼容 `/vite` 入口应解析到相同 Worker URL;避免导入路径不同造成两条连接。普通 HTML 与打包页面混用时,也必须以实际 URL 一致为前提。
285
+
286
+ 不使用每个页面独立创建的 Blob URL 作为默认共享资源地址。各页面资源 URL 不一致会破坏当前按 URL 复用的会话前提。
287
+
288
+ SharedWorker API 不可用时,`createClient()` 自动使用独立连接;Worker 404、错误 MIME、初始化超时等资源或初始化错误继续通过 SDK 错误通道报告。错误信息包含可定位的阶段与资源地址,不包含 credential。
289
+
290
+ ## 4. 实施顺序与涉及文件
291
+
292
+ | 阶段 | 工作 | 涉及位置 | 通过条件 |
293
+ | --- | --- | --- | --- |
294
+ | P0:可行性验证 | 验证 ESM Worker URL 在 Vite / Webpack 构建中的行为 | 本地 Vite Demo、安装的候选 tarball、Webpack 消费工程 | 已通过 Vite 6.4.4 dev/build、Webpack 5.111.1 production、Webpack 4.47.0 + Vue 2.7 production build;普通 HTML 在浏览器内创建客户端并观察到同目录 Worker 请求 |
295
+ | P1:发布格式 | 生成 ESM、保留 UMD/CJS、类型声明和条件导出 | `src/rtm.esm.mjs`、`scripts/build-modern.mjs`、`package.json`、`dist/` | 已通过构建、包根 ESM/CJS、自包含 tarball 安装和 NodeNext 类型检查 |
296
+ | P2:Worker 适配 | 提供实例级默认 Worker 地址、Vite 插件、Webpack 4 插件与旧入口兼容 | `src/plugins/`、`src/rtm.esm.mjs`、类型与构建文件 | 已覆盖默认 Worker URL、显式 `workerUrl`、`sharing: false` 和 Webpack 4 Worker 资源输出;不同入口之间的真实连接共享仍待浏览器验证 |
297
+ | P3:消费验证 | 验证安装包和 Vite/Webpack 消费构建 | `test/package-*`、Vue 3 Vite Demo、Vue 2 Webpack 4 与 React Vite 消费工程 | 本地 tarball、Vue 3/React Vite 与 Vue 2/Webpack 4 构建、Worker URL 资源请求已覆盖;框架生命周期、base 深层路由、preview 和真实 Gate 待验证 |
298
+ | P4:文档和发布 | 更新用法、Demo、验收记录;发布候选包并从 registry 复测 | README、`docs/USAGE.md`、Demo、发布记录 | 文档和 Demo 已更新;registry 发布、业务试接入与回退记录未执行 |
299
+
300
+ 不宣称 Vite 或 Webpack 5 零配置:Vite 需 `/vite-plugin`,Webpack 4 需 `/webpack4`,Webpack 5 最小 production build 无 SDK 插件。未完成的浏览器、真实 Gate 和 registry 关卡仍按下方清单继续。
301
+
302
+ 生成文件由构建脚本生成,不直接修改 `dist/` 来实现方案。公开类型声明以 `types/` 为维护源,构建会复制到 `dist/`;包构建仍由现有 Webpack 4 产出 UMD 与 Worker,并由 esbuild 构建 ESM;消费工程工具版本彼此独立。
303
+
304
+ ## 5. 怎么验证
305
+
306
+ ### 5.1 验证实际分发包
307
+
308
+ 最终证据来自安装包。工作区相对导入、alias 到源码或 yalc 只能用于迭代,不能替代分发验证。
309
+
310
+ 现有命令可先用于源码与包行为回归:
311
+
312
+ ```bash
313
+ npm ci
314
+ npm run test:unit
315
+ npm run test:package
316
+ ```
317
+
318
+ 制作候选 tarball 时:
319
+
320
+ ```bash
321
+ npm pack --json
322
+ ```
323
+
324
+ 当前 `prepack` 会执行构建。记录 JSON 返回的 tarball 文件名、包版本与 integrity,在仓库外的干净消费工程安装该绝对路径:
325
+
326
+ ```bash
327
+ npm install /absolute/path/to/candidate-sdk.tgz
328
+ ```
329
+
330
+ 消费工程必须从包根/公开子路径导入,关闭源码 alias,不依赖 SDK 仓库的 `node_modules`。锁文件与环境版本保存到验证记录。
331
+
332
+ `npm run test:package` 会构建、执行 `npm pack --dry-run` 文件审计、创建并安装本地 tarball,再从安装目录执行 ESM/CJS/插件导入和 ESM/CJS NodeNext 类型检查。它还运行 UMD 行为回归、根入口 ESM、Webpack 4 插件 smoke test。
333
+
334
+ ### 5.2 首批支持矩阵与当前结果
335
+
336
+ 以下记录的是本次本地实现验证。通过最小构建不等于已经支持该框架的所有生命周期、部署目录或浏览器组合。
337
+
338
+ | 编号 | 消费环境 | 当前状态与证据 | 尚未覆盖 |
339
+ | --- | --- | --- | --- |
340
+ | H1 | 普通 HTML + 浏览器 | `PARTIAL`:加载 UMD 并创建共享客户端后,浏览器实际请求同目录 `/sdk/rtm.shared-worker.js`;自动 URL 解析已观察 | 真实 Gate 登录/多窗口复用及完整 HTML Demo 业务链路 |
341
+ | N1 | Node CommonJS | `PASS`:无 `window` 时从包根 `require()`,现有包 smoke 测试通过 | 对真实 Gate 的 Node WebSocket 链路 |
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 插件 | 组件卸载、开发模式与实际登录/连接复用 |
346
+ | W5 | Webpack 5.111.1 最小工程 | `PARTIAL`:独立安装的 npm tarball production 编译成功,输出完整 Worker 资源并设置 `/static/` publicPath | dev server、浏览器请求、子目录部署和 React 生命周期 |
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
+ | R5 | React + CRA 5 / Webpack 5 | `NOT_RUN` | CRA 未 eject 的 dev/build 和 effect 清理 |
349
+ | T1 | TypeScript 消费工程 | `PASS`:工作区与安装 tarball 都通过 NodeNext ESM/CJS 声明检查 | `moduleResolution: bundler` 和旧式 TS 解析 |
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。
352
+
353
+ 每个浏览器消费工程至少测试 `/` 和 `/app/` 子目录部署,以及深层业务路由进入/刷新。ESM npm 接入不应增加 `window.rtm` 依赖。
354
+
355
+ ### 5.3 Browser / Worker 行为验收
356
+
357
+ 资源加载用例先使用可控测试端验证 Worker 握手和消息路由;再使用专用真实 Gate 环境跑端到端链路。断言浏览器中的实际资源与连接行为:
358
+
359
+ | 用例 | 操作 | 通过标准 |
360
+ | --- | --- | --- |
361
+ | B1 自动资源 | 根入口创建共享客户端 | Worker 请求 200、JS MIME 正确、无业务 `workerUrl`、无手动复制文件 |
362
+ | B2 共享登录 | 同源两个页面使用相同配置与 UID;A 首次登录,B 不传 credential | 同一个 Worker、一条 Gate WebSocket;B 复用登录,收到订阅 Push |
363
+ | B3 并发登录 | 两个页面同时登录同一 UID | Worker 内只发起一次同 UID 鉴权,两个调用正确结束 |
364
+ | B4 身份隔离 | 分别更换 UID、PID、协议或 endpoint | 按既有规则隔离;同身份的其他参数冲突明确失败 |
365
+ | B5 生命周期 | 销毁 A,B 发消息;最后销毁 B | B 继续可用;最后一页默认 5 秒后回收;宽限期内接入可取消回收 |
366
+ | B6 协议关闭 | 一个页面执行 `bye()` / `close()` | 所有共享页面观察到会话关闭;未完成请求正确结束 |
367
+ | B7 独立连接 | `sharing: false` / 普通 `RTMClient` | 不创建、不加载 Worker;独立登录与消息正常 |
368
+ | B8 入口一致 | 同一构建同时使用默认/具名导入、共享构造器、兼容 `/vite` | 解析一致的 Worker 地址;按相同身份共享连接 |
369
+ | B9 显式覆盖 | 给上述入口传入有效、同源的自定义 `workerUrl` | 都采用覆盖地址;默认资源不会另开会话 |
370
+ | B10 SharedWorker 不可用 | 移除 SharedWorker API 后用 `createClient()` 创建连接 | 自动使用独立 RTMClient;协议、登录、Push 和业务 API 可用,不声称多页共享 |
371
+ | B11 资源错误诊断 | Worker 404、错误 MIME、初始化超时 | 能定位原因;资源/初始化错误不静默降级;无挂起 Promise |
372
+ | B12 升级资源 | 构建不同版本并刷新页面 | Worker 与主包版本对应,无旧资源误配;记录旧页面仍存活的边界 |
373
+ | B13 框架卸载 | credential 获取中卸载、登录中卸载、切 UID、React 重复挂载 | 已销毁实例不再被使用,无泄漏监听器或未处理 rejection |
374
+
375
+ 跨域 CDN 和 CSP 属于部署专项验证:不允许的部署应产生清楚的诊断;允许的同源资源路由应能恢复正常。不同 Worker URL 的页面不能被误计为共享成功。
376
+
377
+ 当前 ESM smoke test 使用 mock `SharedWorker` 验证默认 URL、显式覆盖、独立连接不启动 Worker 和底层共享构造器注入;它不证明真实浏览器的请求和连接复用。连接复用证据仍需来自浏览器 Worker/Network 或测试 Gate 的连接与鉴权计数。UI 显示“已登录”或 Demo 的 BroadcastChannel 本地模拟不能证明 WebSocket 复用。
378
+
379
+ ### 5.4 真实 Gate 验收
380
+
381
+ 参考 [在线验证说明](TLV_LIVE_E2E_TEST.md) 准备 PID、endpoint、两个专用 UID 和后端签发的 credential。
382
+
383
+ 按以下顺序执行:首次登录 → 同 UID 第二页无 credential 复用 → 发送私聊 → 接收 Push → 销毁第一页 → 第二页继续收发 → 所有页面退出并确认回收。TLV 为新入口主验收协议,FPNN 用现有共享流程补回归。
384
+
385
+ 真实链路中记录发送回执、接收 message_ref、连接数量、关闭结果和可复现步骤。凭证获取失败、网络不可达等情况标为阻塞;不得当作通过。协议能力项的可选跳过规则沿用现有在线测试文档。
386
+
387
+ ## 6. 从实现到发布如何闭环
388
+
389
+ ```mermaid
390
+ flowchart TD
391
+ A[确认支持矩阵和旧入口基线] --> B[候选入口与 Worker 可行性验证]
392
+ B --> C[实施构建与资源适配]
393
+ C --> D[源码回归和 npm tarball 安装]
394
+ D --> E[开发和生产消费矩阵]
395
+ E --> F[真实 Gate 多窗口验收]
396
+ F --> G[候选标签发布]
397
+ G --> H[从 registry 干净安装并复测]
398
+ H --> I[提升 latest 并由业务试接入]
399
+ I --> J[记录结果及回退信息]
400
+ E -->|失败| C
401
+ F -->|SDK 问题| C
402
+ H -->|失败| C
403
+ ```
404
+
405
+ | 关卡 | 交付物 | 谁负责 | 放行条件 |
406
+ | --- | --- | --- | --- |
407
+ | G0 范围确认 | 消费工程版本、旧入口 API 清单、资源方案选型记录 | SDK 维护者;业务接入者提供实际构建版本 | `PASS`:Vite 需要插件、Webpack 4 需要插件、Webpack 5 最小 production build 不需要 SDK 插件 |
408
+ | G1 本地候选包 | 构建、tarball 文件审计和安装 smoke test | 实施者 | `PASS`:`npm test` 中的本地源代码与 tarball 检查通过 |
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
+ | G3 真实业务链路 | Gate 环境标识、UID、连接/鉴权计数、消息与关闭记录 | 测试/联调人员 | `NOT_RUN`:本次没有使用真实 Gate 凭证 |
411
+ | G4 候选发布 | registry、候选 tag 和 integrity | 有发布权限的维护者 | `NOT_RUN`:没有向 registry 发布或改 tag |
412
+ | G5 业务验收 | 现代项目与目标旧项目结果、回退版本 | 业务接入者 + SDK 维护者 | `NOT_RUN` |
413
+
414
+ ### 6.1 候选发布与线上安装复测
415
+
416
+ 先确定实际 registry、原 `latest` 指向和版本号策略;这里不假定包在公共 npm,也不假定仓库版本已经发布。
417
+
418
+ 发布使用新的候选版本和 `next` 等非 `latest` 标签,不覆盖已经发布的版本。发布操作由有权限的维护者执行,实施计划本身不代表已经发布。
419
+
420
+ 从 registry 验证时,在干净消费工程安装候选的精确版本,并确认没有 yalc、源码 alias 或本地 tarball 残留。比对 registry 的 integrity 与准备发布的候选包;若发布流程重新构建使内容变化,对实际发布包重新执行关卡 G1—G3,不能复用旧包的通过记录。
421
+
422
+ 候选包复测通过后再提升 `latest`,随后用 `@latest` 在干净工程安装,核对确实解析到目标版本。业务工程保留精确版本和锁文件,避免自动升级干扰验收。
423
+
424
+ ### 6.2 回退
425
+
426
+ 更新标签前记录上一稳定版本、registry integrity 和已部署业务版本。出现旧入口回归、Worker 无法加载、共享连接被拆成多条或主包/Worker 版本错配时停止推广。
427
+
428
+ 回退操作包括:将 `latest` 恢复到上一稳定版本;受影响业务恢复 SDK 精确版本与锁文件并重新构建;主脚本和 Worker 一起回退部署。单独回退 npm 标签不会自动改变已经安装或已经部署的应用。
429
+
430
+ 旧页面可能仍持有新版本 Worker,需要刷新或按既有 detach/回收流程释放。不得通过删除发布包或强行跨版本合并会话来代替回退。
431
+
432
+ ### 6.3 验收记录模板
433
+
434
+ 在后续消费或发布验收时填写以下字段,状态使用 `PASS`、`PARTIAL`、`FAIL`、`BLOCKED`、`NOT_RUN`:
435
+
436
+ ```text
437
+ 源码 commit:
438
+ SDK 精确版本 / registry / tag:
439
+ tarball 文件 / integrity:
440
+ Node / npm / 浏览器版本:
441
+ 消费工程 / 构建工具与完整版本 / 锁文件:
442
+ 入口(根 ESM、CJS、UMD、旧 /vite):
443
+ 构建配置(零额外配置或具体插件):
444
+ 部署 origin / base / publicPath / 实际 Worker URL:
445
+ 源码与分发检查状态:
446
+ 开发 / 生产 / 类型检查矩阵状态:
447
+ 真实 Gate 链路与多窗口连接计数:
448
+ 失败复现 / 修复 commit / 对应重测证据:
449
+ 上一稳定版本 / 回退操作记录:
450
+ 业务试接入结论 / 验收人 / 日期:
451
+ ```
452
+
453
+ 任何必选项仍为 `FAIL`、`BLOCKED` 或 `NOT_RUN`,都不能写“整体完成”。验证失败后要覆盖同源的所有入口与变体,例如默认导入、具名导入、共享构造器和旧 `/vite`,并为实际缺陷补能复现问题的回归用例。
454
+
455
+ ## 7. 参考依据与当前进度
456
+
457
+ 以下官方文档说明构建能力和解析规则;它们不替代本 SDK 安装包在锁定版本下的实测:
458
+
459
+ - [Vite:Worker 构造器与静态选项要求](https://vite.dev/guide/features.html#web-workers)。
460
+ - [Vite:相对模块 URL 与资源处理](https://vite.dev/guide/assets.html#new-url-url-import-meta-url)。
461
+ - [Webpack 5:URL 资源自动输出](https://webpack.js.org/guides/asset-modules/#url-assets)。
462
+ - [Webpack:Worker 语法和静态分析限制](https://webpack.js.org/guides/web-workers/)。
463
+ - [Node:条件导出与双格式包](https://nodejs.org/api/packages.html#conditional-exports)。
464
+
465
+ 本地实现与回归结果(2026-10-13):
466
+
467
+ - `npm test` 通过,包含协议、文档、Demo、UMD/CJS、ESM、tarball 导入、Webpack 4 插件与 NodeNext 类型检查。
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 候选发布仍未验收。
471
+
472
+ 本地验证环境为 Node 20.20.1、npm 10.8.2、TypeScript 5.8.3。
473
+
474
+ 本次没有发布 npm,也没有修改 registry tag。开发接入示例与限制见 [USAGE.md](USAGE.md);四个 Demo 的源码仓库专用说明位于 `examples/README.md`。
@@ -11,16 +11,17 @@
11
11
 
12
12
  ## 选择协议
13
13
 
14
- 现有 FPNN 客户端通常使用 `endpoint`(FPNN Gate 地址)创建;保留这套配置时显式指定 `protocol: 'fpnn'`,或依赖兼容默认值:
14
+ 现有 FPNN 客户端通常使用 `endpoint`(FPNN Gate 地址)创建。继续使用旧 `RTMClient` 构造器时,省略协议仍默认 FPNN。迁移到新工厂 `createClient()` 时,省略协议同样默认 FPNN;浏览器支持 SharedWorker 时工厂自动共享,不支持时自动使用独立连接:
15
15
 
16
16
  ```js
17
- const client = new rtm.RTMClient({
18
- protocol: 'fpnn',
17
+ const client = rtm.createClient({
19
18
  pid,
20
19
  endpoint: fpnnEndpoint,
21
20
  });
22
21
  ```
23
22
 
23
+ 若业务必须保持每个页面独立连接,可改用 `rtm.createClient({ sharing: false, pid, endpoint: fpnnEndpoint })`;浏览器缺少 SharedWorker 时,`createClient()` 也会自动使用独立连接。若希望新项目显式使用 TLV v1,则设置 `protocol: 'tlv-v1'` 并提供完整 `tlvEndpoint`。
24
+
24
25
  迁移到 TLV v1 时,将连接地址换成部署方提供的完整 WebSocket URL,并在创建时选择 TLV:
25
26
 
26
27
  ```js
@@ -35,7 +36,7 @@ await client.promises.login(uid, credential);
35
36
  await client.promises.sendChat(peerUid, 'hello', '{}');
36
37
  ```
37
38
 
38
- `credential` 仍须由业务服务端或受控签发工具为当前 UID 签发。不要把项目 `SecretKey` 放入浏览器。其余连接、登录、发送、监听 Push 的业务调用可以继续使用同一套 `RTMClient` API;若使用 `RTMSharedWorkerClient`,默认仍为 TLV v1,也可显式选择 FPNN。SharedWorker 配置和能力边界见 [FPNN 多窗口接入](USAGE.md#fpnn-多窗口接入)。
39
+ `credential` 仍须由业务服务端或受控签发工具为当前 UID 签发。不要把项目 `SecretKey` 放入浏览器。其余连接、登录、发送、监听 Push 的业务调用可以继续使用同一套 `RTMClient` API;`RTMSharedWorkerClient` 和 `createClient()` 省略协议时均默认 FPNN,显式设置 `protocol: 'tlv-v1'` 才使用 TLV。SharedWorker 配置和能力边界见 [FPNN 多窗口接入](USAGE.md#fpnn-多窗口接入)。
39
40
 
40
41
  ## API 与 wire 名称对照
41
42
 
@@ -130,7 +131,7 @@ Push 事件也有协议差异:名称见上表,事件字段与 FPNN wire payl
130
131
 
131
132
  ### API 支持范围
132
133
 
133
- `protocol: 'tlv-v1'` 只覆盖 [TLV v1 支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵)中标为支持的 API。常见未开放项包括文件(`filetoken`、`sendfile` 等)、好友(`addfriends`、`getfriends`)、设备 Push 设置、多媒体审核,以及传统 RTM 房间控制类接口。调用未开放 wire 不会切换到 FPNN:保留但未开放的 wire 会返回 `200020`,未知 wire 会返回 `20004`;SharedWorker 文件发送在本地拒绝。错误细节见 [能力总览](CAPABILITIES.md#协议与能力入口) 和支持矩阵。
134
+ `protocol: 'tlv-v1'` 只覆盖 [TLV v1 支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵)中标为支持的 API。常见未开放项包括文件(`filetoken`、`sendfile` 等)、好友(`addfriends`、`getfriends`)、设备 Push 设置、多媒体审核,以及传统 RTM 房间控制类接口。调用未开放 wire 不会切换到 FPNN:保留但未开放的 wire 会返回 `200020`,未知 wire 会返回 `20004`。共享层转发相同的 SDK 调用:FPNN 文件发送可用,TLV 由底层 SDK 拒绝。错误细节见 [能力总览](CAPABILITIES.md#协议与能力入口) 和支持矩阵。
134
135
 
135
136
  ### 登录与错误处理
136
137