@nnepoch/dtc-sdk 3.0.0

package/README.md

@@ -0,0 +1,298 @@
+# enginesdk3
+
+基于 `@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 通过
+
+---
+
+## 安装
+
+```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
+```
+
+浏览器产物由 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
+```
+
+- 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` 用于检查发布产物，不参与默认构建。
+
+## 运行时配置
+
+```ts
+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'
+});
+```
+
+- 连接流程：`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();
+```
+
+### 初始对接推荐写法
+
+直接提供信令服务 HTTP 基地址：
+
+```ts
+const engine = new DTCEngine({
+  signalingServer: 'https://signaling.example.com',
+  sceneName: 'demo-scene',
+  token: 'token-from-auth-system',
+  dom: document.getElementById('app') as HTMLDivElement
+});
+```
+
+中心鉴权模式：
+
+```ts
+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`：浏览器流模式，启用完整浏览器输入链路（键鼠触摸等）与标准事件转发。
+- `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
+
+- 自动判定输入：`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`
+
+## RequestBridge 多响应能力（开发说明）
+
+- `RequestBridge.sendRequest(...)` 继续保持单响应语义：命中首条 `requestId` 响应即完成并释放 pending。
+- `RequestBridge.sendStreamRequest(...)` 用于多响应场景：返回可取消 Promise，同一 `requestId` 的状态统一通过单个 `callback` 分发。
+- 多响应请求释放条件：
+  - 收到结束信号（默认支持 `code=DONE/STREAM_DONE` 或 `done/isEnd=true`）
+  - 调用返回 Promise 的 `cancel()`
+  - 会话断开（`webRtcDisconnected` / `webRtcFailed`）
+- 流式相关类型可从 SDK 类型导出中获取：
+  - `StreamRequestCallback`
+  - `StreamRequestEvent`
+  - `StreamRequestPromise`
+
+## EngineStatus 事件
+
+```ts
+engine.on(engine.Events.EngineStatus, (status) => {
+  console.log(status);
+});
+```
+
+- `EngineStatus` 与 sdk2 事件名保持一致。
+- 事件会在会话连接后持续更新派发；会话断开或失败时停止派发，重连成功后恢复。
+- 状态来源仅为 WebRTC 统计（`statsReceived`）。
+
+`EngineStatusInfo` 主要字段：
+- `CameraHeight`
+- `FPS`
+- `Width`
+- `Height`
+- `runTime`
+- `bytePerSecond`
+- `lostPacketsRate`
+- `delayTime`
+- `Codec`
+
+## UE 主动推送事件
+
+以下事件由 UE 侧通过 Pixel Streaming Response 通道主动推送触发，SDK 内部使用单一 response listener 按 `fn/uuid` 路由后派发：
+
+- `MapLoaded`（底层事件名：`OnApiDataChannelStarted`）
+- `ModelClick`
+- `CameraHeight`
+- `LeftClick`（`MouseLeftButtonClick`）
+- `LeftDoubleClick`（`MouseLeftButtonDoubleClick`）
+- `LeftLongPressed`（`MouseLeftButtonLongPressed`）
+- `RightClick`（`MouseRightButtonClick`）
+- `RightDoubleClick`（`MouseRightButtonDoubleClick`）
+- `RightLongPressed`（`MouseRightButtonLongPressed`）
+- `SceneConfig`
+- `ModelTrigger`
+
+示例：
+
+```ts
+engine.on(engine.Events.ModelClick, (payload) => {
+  console.log('模型点击', payload);
+});
+```
+
+- 事件 payload 默认透传 UE 上行消息内容。
+- 若上行消息中的 `fn/uuid` 未命中上述事件集合，SDK 不会触发这些事件。
+
+## 从 sdk2 迁移（模式相关）
+
+- 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`。
+
+## 参数校验失败示例
+
+```ts
+try {
+  await engine.Camera.lookAt({ id: '' });
+} catch (error) {
+  console.error(error);
+  // SDKValidationError:
+  // {
+  //   code: 'VALIDATION_ERROR',
+  //   module: 'Camera',
+  //   method: 'lookAt',
+  //   issues: [...]
+  // }
+}
+```
+
+## 产物
+
+- `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）