@nnepoch/dtc-sdk 3.0.0 → 3.0.2

package/README.md

@@ -1,97 +1,44 @@
-# enginesdk3
+# @nnepoch/dtc-sdk
 
-基于 `@epicgames-ps/lib-pixelstreamingfrontend-ue5.6` 的 UE 前端 SDK。
-
-## 📋 代码审查报告
-
-> **最新审查**: 2026-08-15 | **健康度**: C+ (65/100) | **问题数**: 184
-
-查看完整报告：[docs/code-review/](./docs/code-review/)
-
-**关键发现**:
-- 🔴 6 个 Critical 问题需要立即处理
-- 🟠 49 个 High 优先级问题
-- ⚡ 5 个快速胜利（1.4 天可完成）
-
-**代码审查与重构记录**：
-- [总览、处理计划与完成情况](./docs/code-review/README.md)
-- [详细问题清单](./docs/code-review/CODE_REVIEW_ISSUES.md)
-
-**当前重构状态**：
-- ✅ EventBus 提取完成
-- ✅ ConnectionManager 提取完成
-- ✅ EngineBuilder 装配完成
-- ✅ DTCEngine 第一轮简化及生命周期回归修复完成
-- ✅ 聚焦测试、类型检查和生产源码 lint 通过
-
----
+面向 Unreal Engine 云渲染场景的前端 SDK，基于 Pixel Streaming 提供鉴权、WebRTC 连接和引擎 API 调用能力。
 
 ## 安装
 
 ```bash
-pnpm install
-```
-
-## 构建命令
-
-```bash
-pnpm run clean          # 清理 dist 和 API 文档
-pnpm run build          # 构建 npm CJS/ESM、browser 压缩包和混淆包
-pnpm run build:lib      # 仅构建 npm CJS/ESM bundle 与声明文件
-pnpm run build:browser  # 仅构建 browser IIFE 压缩包和混淆包
-pnpm run verify:build   # 验证入口加载、导出、声明文件和 sourcemap
-pnpm run typecheck      # 仅执行 TypeScript 类型检查
-pnpm run rebuild        # clean + build
-pnpm run build:release  # rebuild + API 文档
-pnpm run watch          # library 构建监听
-pnpm run dev:browser    # browser 构建监听
-```
-
-npm library 产物由 tsdown 统一生成：
-
-```text
-dist/cjs/index.cjs
-dist/cjs/index.d.cts
-dist/esm/index.js
-dist/esm/index.d.ts
+npm install @nnepoch/dtc-sdk
 ```
 
-浏览器产物由 tsdown 生成 IIFE，再由 `javascript-obfuscator` 就地替换为混淆版本：
-
-```text
-dist/browser/dtc-sdk-3.0.0.js
-```
-
-
-## Playground 开发环境
-
-- `playground/` 是 SDK 维护者使用的多技术栈联调容器。
-- `playground/vue/` 当前使用 `Vue 3 + Vite`，页面入口在 `playground/vue/src/App.vue`，直接消费源码入口 `src/index.ts`。
-- 现有 [examples/index.html](examples/index.html) 继续保留为版本化 browser 产物的 smoke test。
-- 首次使用：
-
-```bash
-pnpm run playground:dev
+## 快速开始
+
+### 直接连接信令服务
+
+```html
+<div id="app"></div>
+<script type="module">
+  import { DTCEngine } from '@nnepoch/dtc-sdk';
+
+  const engine = new DTCEngine({
+    signalingServer: 'https://signaling.example.com',
+    sceneName: 'demo-scene',
+    token: 'your-token',
+    dom: document.getElementById('app'),
+    viewMode: 'bs',
+    showProgressBar: true,
+    logger: 'info'
+  });
+
+  try {
+    await engine.whenReady();
+    console.log('引擎已连接');
+  } catch (error) {
+    console.error('引擎连接失败', error);
+  }
+</script>
 ```
 
-- Vue Playground 配置固定写在 [playground/vue/src/App.vue](playground/vue/src/App.vue) 的 `PLAYGROUND_CONFIG` 常量中。
-- 更详细的字段说明和联调说明见 [playground/vue/README.md](playground/vue/README.md)。
-
-## GitLab 发版流程
-
-- 分支开发阶段仅执行 `pnpm changeset`（或 `npx @changesets/cli`）生成 `.changeset/*.md`。
-- `changeset version` 由 GitLab CI 在默认主分支 push 的 `release` job 中统一执行。
-- 发布完成后，CI 会回写版本文件并提交 `chore(release): vX.Y.Z [skip ci]`，同时推送 tag。
-- 详细说明见 [docs/GITLAB_RELEASE_FLOW.md](docs/GITLAB_RELEASE_FLOW.md)。
+### 通过中心服务鉴权
 
-## 迁移说明
-
-- 旧的 `build:cjs` / `build:esm` 已移除；CJS/ESM 由 `build:lib` 一次性生成。
-- `build:lib` 同时执行类型检查和 npm bundle，不再保留单独的 `build:types` 命令。
-- `build:obfuscate` 作为 `build:browser` 的内部后处理步骤，通常不需要单独调用。
-- `verify:build` 用于检查发布产物，不参与默认构建。
-
-## 运行时配置
+如果使用中心服务，可以传入 `centerIP`，SDK 会完成中心鉴权、服务分配和 WebRTC 连接：
 
 ```ts
 import { DTCEngine } from '@nnepoch/dtc-sdk';
@@ -99,200 +46,139 @@ import { DTCEngine } from '@nnepoch/dtc-sdk';
 const engine = new DTCEngine({
   centerIP: 'https://center.example.com',
   sceneName: 'demo-scene',
-  token: 'token-from-auth-system',
-  dom: document.getElementById('app') as HTMLDivElement,
-  viewMode: 'bs',
-  logger: 'info'
+  token: 'your-token',
+  dom: document.getElementById('app') as HTMLDivElement
 });
-```
-
-- 连接流程：`new DTCEngine(...)` 后会自动选择 bootstrap 模式并发起 WebRTC 连接。
-- `Connect.connect()` 保留为兼容层接口，不再是用户必调入口。
-- 支持 `engine.restart()`：用于按 `disconnect -> start` 顺序重启中心与 WebRTC 链路。
-- `restart()` 返回 `Promise<AuthSessionSnapshot>`，重启成功 resolve，鉴权/建连失败 reject。
-- `disconnect()` 后仍可调用 `restart()` 重新拉起链路。
-- bootstrap 模式优先级：
-  - `signalingServer`
-  - `centerIP`
-- `signalingServer` 的新语义为“信令服务 HTTP 基地址”，SDK 会自动请求 `${signalingServer}/api/v1/allocate?token={config.token}` 获取最终 WebSocket 播放地址。
-- 中心鉴权模式下，`TokenAuthorize.values.signalingServer` 返回信令服务 HTTP 基地址，SDK 会再请求 `${signalingServer}/api/v1/allocate?token={engineToken}` 获取最终 WebSocket 播放地址。
-- `setSignallingUrlBuilder` 不承载鉴权逻辑，不会在 builder 中发起异步鉴权请求。
-- 中心消息处理采用 sdk2 风格的 `OnMessage` 路由分发，鉴权状态由消息事件驱动推进。
-- 鉴权主链路不再依赖 `waitForMessage`。
-- 参数校验基于 `zod`，在 API 调用前执行 `safeParse`。
-- 初始化配置也会执行结构校验与默认值填充（如 `mapType=web`、`operationType=viewer`）。
-- 支持从 `navigator.userAgent` 读取初始化覆盖参数，格式与 sdk2 对齐：
-  - `RunMode/<value>` -> `viewMode`
-  - `CenterIP/<value>` -> `centerIP`
-  - `PrivateKey/<value>` -> `privateKey`
-  - `showProgressBar/<true|false>` -> `showProgressBar`
-- 配置优先级：`userAgent` > 调用方 `config` > SDK 默认值。
-- `viewMode` 仅支持 `bs | cs`，默认值为 `bs`；传入 `desktop` 或其他非法值会直接抛错并中断初始化。
-- 参数不合法时会快速失败，不会触发底层请求发送。
-- 若未提供 `centerIP`、`signalingServer` 中的任意一种，初始化会直接失败。
-- 日志默认复用 `@epicgames-ps/lib-pixelstreamingcommon-ue5.6` 的 logger。
-- `logger` 参数为字符串级别：`silent | error | warn | info | debug`。
-- `logger` 默认值为 `info`。
-- BREAKING: 不再支持旧对象写法 `logger: { level, includeStack, prefix }`。
-- `includeStack` 固定为 `false`，`prefix` 改为 SDK 内部固定策略。
-- V1 不提供日志自定义 sink 接口。
-- SDK 内部已接入轻量自定义日志上报通道（默认关闭），仅上报 SDK 内部 logger 打印日志。
-- 日志上报配置不对业务侧暴露，统一由 SDK 内部维护。
-- 运维接入步骤见 [docs/LOG_REPORTING_OPS.md](docs/LOG_REPORTING_OPS.md)。
-- `agentBridge` 为可选宿主扩展能力，配置入口位于 `DTCEngine` 的第二个参数 `DTCEngineOptions` 中，而不是 `EngineConfig`。
-- 当前 `agentBridge` 只完成源码骨架与生命周期挂载点预留，默认关闭，不会主动建立 MCP runtime 连接。
 
-```ts
 await engine.whenReady();
-await engine.restart();
 ```
 
-### 初始对接推荐写法
+`signalingServer` 和 `centerIP` 至少需要提供一个。两者同时提供时，SDK 优先使用 `signalingServer` 的直接连接模式。
 
-直接提供信令服务 HTTP 基地址：
+## 常用配置
 
 ```ts
 const engine = new DTCEngine({
+  // 二选一：信令服务 HTTP 基地址或中心服务地址
   signalingServer: 'https://signaling.example.com',
-  sceneName: 'demo-scene',
-  token: 'token-from-auth-system',
-  dom: document.getElementById('app') as HTMLDivElement
-});
-```
-
-中心鉴权模式：
+  // centerIP: 'https://center.example.com',
 
-```ts
-const engine = new DTCEngine({
-  centerIP: 'https://center.example.com',
   sceneName: 'demo-scene',
-  token: 'token-from-auth-system',
-  dom: document.getElementById('app') as HTMLDivElement
+  token: 'your-token',
+  dom: document.getElementById('app') as HTMLDivElement,
+
+  // bs：浏览器流模式；cs：宿主协同模式
+  viewMode: 'bs',
+  showProgressBar: true,
+  logger: 'info'
 });
 ```
 
-## viewMode 说明
-
-- `bs`：浏览器流模式，启用完整浏览器输入链路（键鼠触摸等）与标准事件转发。
-- `cs`：宿主协同模式，保留键盘输入并关闭鼠标/触摸/手柄/XR 输入转发，适用于宿主侧接管交互的场景。
-- 不支持 `desktop`：不会做软降级映射，统一按配置错误处理。
-
-## API 接入维护说明
+支持的日志级别：
 
-- `DTCEngine` 的 API 门面由注册表+工厂统一装配，不再在构造函数中逐个 `new Xxx(...)`。
-- 新增 API 时，仅需修改 [src/api/apiRegistry.ts](src/api/apiRegistry.ts) 的注册项并实现对应模块类。
-- 若新增模块需要特殊依赖注入（例如 `authWorkflow` / `session`），直接在该模块注册工厂中注入即可。
-- 完成注册后，`engine.<Module>` 属性会自动挂载，避免重复修改入口初始化代码。
-- 当前已补齐 `engine.Screen` 模块（码率/FPS/分辨率），用于业务调用与自动弱网策略复用。
-
-## 弱网自适应 V1
+```text
+silent | error | warn | info | debug
+```
 
-- 自动判定输入：`statsReceived + webRtc` 生命周期事件。
-- 状态机档位：`Normal / Mild / Moderate / Severe / Recovering`，含迟滞与冷却机制。
-- 自动动作：通过 `Screen.SetSceneRenderBitrate / SetSceneFPS / SetScreenResolution` 执行降级与恢复。
-- 诊断面板：默认快捷键 `Ctrl + Alt + D`，支持 `Auto / Manual` 接管。
-- 详细阈值和验收口径见 [docs/NETWORK_ADAPTATION_V1.md](docs/NETWORK_ADAPTATION_V1.md)。
+## 生命周期
 
-弱网相关事件：
-- `networkLevelChanged`
-- `networkActionExecuted`
-- `networkModeChanged`
-- `networkDiagnosticsVisibilityChanged`
-- `networkDiagnosticsUpdated`
+```ts
+// 等待首次鉴权和 WebRTC 连接完成
+await engine.whenReady();
 
-## RequestBridge 多响应能力（开发说明）
+// 断开当前连接
+engine.disconnect();
 
-- `RequestBridge.sendRequest(...)` 继续保持单响应语义：命中首条 `requestId` 响应即完成并释放 pending。
-- `RequestBridge.sendStreamRequest(...)` 用于多响应场景：返回可取消 Promise，同一 `requestId` 的状态统一通过单个 `callback` 分发。
-- 多响应请求释放条件：
-  - 收到结束信号（默认支持 `code=DONE/STREAM_DONE` 或 `done/isEnd=true`）
-  - 调用返回 Promise 的 `cancel()`
-  - 会话断开（`webRtcDisconnected` / `webRtcFailed`）
-- 流式相关类型可从 SDK 类型导出中获取：
-  - `StreamRequestCallback`
-  - `StreamRequestEvent`
-  - `StreamRequestPromise`
+// 重新鉴权并连接
+await engine.restart();
+```
 
-## EngineStatus 事件
+## 监听事件
 
 ```ts
-engine.on(engine.Events.EngineStatus, (status) => {
-  console.log(status);
+engine.on(engine.Events.WebRtcConnected, () => {
+  console.log('WebRTC connected');
 });
-```
 
-- `EngineStatus` 与 sdk2 事件名保持一致。
-- 事件会在会话连接后持续更新派发；会话断开或失败时停止派发，重连成功后恢复。
-- 状态来源仅为 WebRTC 统计（`statsReceived`）。
+engine.on(engine.Events.MapLoaded, () => {
+  console.log('场景加载完成');
+});
 
-`EngineStatusInfo` 主要字段：
-- `CameraHeight`
-- `FPS`
-- `Width`
-- `Height`
-- `runTime`
-- `bytePerSecond`
-- `lostPacketsRate`
-- `delayTime`
-- `Codec`
+engine.on(engine.Events.EngineStatus, (status) => {
+  console.log('引擎状态', status);
+});
 
-## UE 主动推送事件
+engine.on(engine.Events.ModelClick, (payload) => {
+  console.log('模型点击', payload);
+});
+```
 
-以下事件由 UE 侧通过 Pixel Streaming Response 通道主动推送触发，SDK 内部使用单一 response listener 按 `fn/uuid` 路由后派发：
+常用事件包括：
 
-- `MapLoaded`（底层事件名：`OnApiDataChannelStarted`）
+- `WebRtcConnected`
+- `WebRtcDisconnected`
+- `MapLoaded`
+- `EngineStatus`
 - `ModelClick`
-- `CameraHeight`
-- `LeftClick`（`MouseLeftButtonClick`）
-- `LeftDoubleClick`（`MouseLeftButtonDoubleClick`）
-- `LeftLongPressed`（`MouseLeftButtonLongPressed`）
-- `RightClick`（`MouseRightButtonClick`）
-- `RightDoubleClick`（`MouseRightButtonDoubleClick`）
-- `RightLongPressed`（`MouseRightButtonLongPressed`）
-- `SceneConfig`
 - `ModelTrigger`
+- `AuthStateChanged`
+- `NetworkLevelChanged`
 
-示例：
+## 调用引擎 API
 
 ```ts
-engine.on(engine.Events.ModelClick, (payload) => {
-  console.log('模型点击', payload);
+await engine.Camera.lookAt({
+  parentId: 'ModelLayer',
+  id: 'CameraTarget',
+  time: 2,
+  distance: 20
 });
-```
-
-- 事件 payload 默认透传 UE 上行消息内容。
-- 若上行消息中的 `fn/uuid` 未命中上述事件集合，SDK 不会触发这些事件。
 
-## 从 sdk2 迁移（模式相关）
+await engine.Screen.setSceneFPS({ fps: 30 });
 
-- sdk2 中的 `desktop` 在 sdk3 中已移除；请改为 `bs` 或 `cs`。
-- 若历史接入使用 `desktop`，需要在业务配置中显式切换为目标模式，不支持自动兜底。
-- `new DTCEngine(...)` 后依然保持自动鉴权并自动连接，`Connect.connect()` 仅作为兼容层保留。
-- sdk3 已对齐 sdk2 的容器注参逻辑：可通过 `navigator.userAgent` 注入 `RunMode/CenterIP/PrivateKey/showProgressBar` 并覆盖 `config`。
-- 本次中心消息迁移范围内，`Offer`、`Answer`、`IceCandidate` 不新增专门处理逻辑。
-- 详细迁移步骤可参考 `docs/VIEW_MODE_MIGRATION.md`。
+await engine.Model.setVisible({
+  parentId: 'ModelLayer',
+  id: 'CameraTarget',
+  visible: false
+});
+```
 
-## 参数校验失败示例
+SDK 会在 API 调用前校验参数。参数不合法时，Promise 会抛出 `SDKValidationError`：
 
 ```ts
 try {
   await engine.Camera.lookAt({ id: '' });
 } catch (error) {
   console.error(error);
-  // SDKValidationError:
-  // {
-  //   code: 'VALIDATION_ERROR',
-  //   module: 'Camera',
-  //   method: 'lookAt',
-  //   issues: [...]
-  // }
 }
 ```
 
-## 产物
+完整 API 列表请查看：[API 文档](./docs/api/)。
+
+## 浏览器脚本产物
+
+如果不使用 npm 模块系统，也可以使用版本化的浏览器脚本：
+
+```html
+<script src="./dist/browser/dtc-sdk-<version>.js"></script>
+<script>
+  const engine = new window.DTCEngine({
+    signalingServer: 'https://signaling.example.com',
+    sceneName: 'demo-scene',
+    token: 'your-token',
+    dom: document.getElementById('app')
+  });
+</script>
+```
+
+## 示例和文档
+
+- [快速开始](./docs/guide/getting-started.md)
+- [API 文档](./docs/api/)
+- [开发者文档](./docs/DEVELOPMENT.md)
+- [Playground 说明](./playground/README.md)
+- [杭州九中示例](./examples/hzjz/)
+
+## 许可证
 
-- `dist/cjs/index.cjs`（CJS）
-- `dist/esm/index.js`（ESM）
-- `dist/esm/index.d.ts`（types）
-- `dist/browser/dtc-sdk-<version>.js`（script 可直引，已混淆）
-- `docs/api`（typedoc）
+MIT