@threejs-shared/protobuf 0.1.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@threejs-shared/protobuf",
+  "version": "0.1.0",
+  "description": "Protobuf manager for loading and parsing proto files",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "protobufjs": "^7.0.0",
+    "@threejs-shared/xodr": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc --noEmit"
+  }
+}

package/src/ProtoBufManager.ts

@@ -0,0 +1,311 @@
+// import protobuf from 'protobufjs'
+
+// /**
+//  * Protobuf 管理器，用于加载和缓存 proto 文件
+//  */
+// export class ProtoBufManager {
+//   private protoCache: Map<string, protobuf.Type> = new Map()
+
+//   /**
+//    * 加载 proto 文件并获取指定的消息类型
+//    * @param protoFilePath proto 文件的路径（URL）
+//    * @param messageType 消息类型名称（例如：'protobuf.WsFrameData'）
+//    * @returns Promise<protobuf.Type> 解析后的消息类型
+//    */
+//   async loadProto(protoFilePath: string, messageType: string): Promise<protobuf.Type> {
+//     const cacheKey = `${protoFilePath}-${messageType}`
+//     if (this.protoCache.has(cacheKey)) {
+//       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+//       return this.protoCache.get(cacheKey)!
+//     }
+//     try {
+//       const response = await fetch(protoFilePath)
+//       if (!response.ok) {
+//         throw new Error(`Failed to fetch proto file: ${response.statusText}`)
+//       }
+//       const content = await response.text()
+//       const root = protobuf.parse(content).root
+//       const messageTypeDefinition = root.lookupType(messageType)
+//       if (!messageTypeDefinition) {
+//         throw new Error(`Message type '${messageType}' not found in proto file`)
+//       }
+//       this.protoCache.set(cacheKey, messageTypeDefinition)
+//       return messageTypeDefinition
+//     } catch (error) {
+//       console.error('Error loading proto file:', error)
+//       throw error
+//     }
+//   }
+
+//   /**
+//    * 清除缓存
+//    * @param protoFilePath 可选的 proto 文件路径，如果提供则只清除该文件的缓存，否则清除所有缓存
+//    */
+//   clearCache(protoFilePath?: string): void {
+//     if (protoFilePath) {
+//       const keysToDelete: string[] = []
+//       this.protoCache.forEach((_, key) => {
+//         if (key.startsWith(protoFilePath)) {
+//           keysToDelete.push(key)
+//         }
+//       })
+//       keysToDelete.forEach(key => this.protoCache.delete(key))
+//     } else {
+//       this.protoCache.clear()
+//     }
+//   }
+
+//   /**
+//    * 获取缓存的大小
+//    */
+//   getCacheSize(): number {
+//     return this.protoCache.size
+//   }
+// }
+
+import protobuf from 'protobufjs'
+
+/**
+ * ProtoBufManager 配置选项
+ */
+export interface ProtoBufManagerOptions {
+  /** 是否启用日志 */
+  enableLog?: boolean
+}
+
+/**
+ * Protobuf 管理器，用于加载和缓存 proto 文件
+ * 
+ * 特性：
+ * - 自动缓存已加载的 proto 类型，避免重复加载
+ * - 并发请求控制，同一 proto 文件的多次请求会共享同一个 Promise
+ * - 完善的错误处理和参数验证
+ * - 可配置的日志输出
+ */
+export class ProtoBufManager {
+  /** 已加载的 proto 类型缓存 */
+  private protoCache: Map<string, protobuf.Type> = new Map()
+  /** 正在加载的 Promise 缓存，用于并发控制 */
+  private loadingPromises: Map<string, Promise<protobuf.Type>> = new Map()
+  /** 配置选项 */
+  private options: Required<ProtoBufManagerOptions>
+
+  constructor(options?: ProtoBufManagerOptions) {
+    this.options = {
+      enableLog: options?.enableLog ?? true,
+    }
+  }
+
+  /**
+   * 加载 proto 文件并获取指定的消息类型
+   * 
+   * @param protoFilePath proto 文件的路径（URL）
+   * @param messageType 消息类型名称（例如：'protobuf.WsFrameData' 或 'SimulationMonitor.SimulationMonitorMsg'）
+   * @returns Promise<protobuf.Type> 解析后的消息类型
+   * @throws {Error} 如果参数无效、文件加载失败、解析失败或消息类型不存在
+   * 
+   * @example
+   * ```typescript
+   * const manager = new ProtoBufManager()
+   * const messageType = await manager.loadProto('/proto/SimulationMonitor.proto', 'SimulationMonitor.SimulationMonitorMsg')
+   * ```
+   */
+  async loadProto(protoFilePath: string, messageType: string): Promise<protobuf.Type> {
+    // 参数验证
+    if (!protoFilePath || typeof protoFilePath !== 'string') {
+      throw new Error('protoFilePath must be a non-empty string')
+    }
+    if (!messageType || typeof messageType !== 'string') {
+      throw new Error('messageType must be a non-empty string')
+    }
+
+    const cacheKey = `${protoFilePath}-${messageType}`
+
+    // 如果已缓存，直接返回
+    if (this.protoCache.has(cacheKey)) {
+      this.log(`Using cached proto type: ${messageType}`)
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      return this.protoCache.get(cacheKey)!
+    }
+
+    // 如果正在加载，返回同一个 Promise（并发控制）
+    if (this.loadingPromises.has(cacheKey)) {
+      this.log(`Proto file is already loading: ${protoFilePath}, waiting...`)
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      return this.loadingPromises.get(cacheKey)!
+    }
+
+    // 创建加载 Promise
+    const loadPromise = this.loadProtoInternal(protoFilePath, messageType, cacheKey)
+    this.loadingPromises.set(cacheKey, loadPromise)
+
+    try {
+      const result = await loadPromise
+      return result
+    } finally {
+      // 加载完成后移除 Promise 缓存
+      this.loadingPromises.delete(cacheKey)
+    }
+  }
+
+  /**
+   * 内部加载方法
+   */
+  private async loadProtoInternal(
+    protoFilePath: string,
+    messageType: string,
+    cacheKey: string
+  ): Promise<protobuf.Type> {
+    try {
+      this.log(`Loading proto file: ${protoFilePath}`)
+
+      // 1. 获取 proto 文件内容
+      let response: Response
+      try {
+        response = await fetch(protoFilePath)
+      } catch (error) {
+        throw new Error(
+          `Failed to fetch proto file from "${protoFilePath}": ${error instanceof Error ? error.message : String(error)}`
+        )
+      }
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch proto file: HTTP ${response.status} ${response.statusText}`
+        )
+      }
+
+      // 2. 读取文件内容
+      let content: string
+      try {
+        content = await response.text()
+      } catch (error) {
+        throw new Error(
+          `Failed to read proto file content: ${error instanceof Error ? error.message : String(error)}`
+        )
+      }
+
+      if (!content || content.trim().length === 0) {
+        throw new Error('Proto file is empty')
+      }
+
+      // 3. 解析 proto 文件
+      let root: protobuf.Root
+      try {
+        root = protobuf.parse(content).root
+      } catch (error) {
+        throw new Error(
+          `Failed to parse proto file: ${error instanceof Error ? error.message : String(error)}`
+        )
+      }
+
+      // 4. 查找消息类型
+      const messageTypeDefinition = root.lookupType(messageType)
+      if (!messageTypeDefinition) {
+        // 尝试列出可用的类型，帮助调试
+        const availableTypes: string[] = []
+        root.nestedArray.forEach((nested) => {
+          if (nested instanceof protobuf.Type) {
+            availableTypes.push(nested.fullName)
+          } else if (nested instanceof protobuf.Namespace) {
+            nested.nestedArray.forEach((nestedType) => {
+              if (nestedType instanceof protobuf.Type) {
+                availableTypes.push(nestedType.fullName)
+              }
+            })
+          }
+        })
+
+        const availableTypesHint = availableTypes.length > 0
+          ? ` Available types: ${availableTypes.slice(0, 10).join(', ')}${availableTypes.length > 10 ? '...' : ''}`
+          : ''
+
+        throw new Error(
+          `Message type "${messageType}" not found in proto file.${availableTypesHint}`
+        )
+      }
+
+      // 5. 缓存结果
+      this.protoCache.set(cacheKey, messageTypeDefinition)
+      this.log(`Successfully loaded proto type: ${messageType}`)
+
+      return messageTypeDefinition
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      this.log(`Error loading proto file: ${errorMessage}`, 'error')
+      
+      // 重新抛出错误，但使用更友好的错误信息
+      throw error instanceof Error ? error : new Error(errorMessage)
+    }
+  }
+
+  /**
+   * 清除缓存
+   * @param protoFilePath 可选的 proto 文件路径，如果提供则只清除该文件的缓存，否则清除所有缓存
+   */
+  clearCache(protoFilePath?: string): void {
+    if (protoFilePath) {
+      const keysToDelete: string[] = []
+      this.protoCache.forEach((_, key) => {
+        if (key.startsWith(protoFilePath)) {
+          keysToDelete.push(key)
+        }
+      })
+      keysToDelete.forEach((key) => {
+        this.protoCache.delete(key)
+        this.log(`Cleared cache for: ${key}`)
+      })
+      this.log(`Cleared ${keysToDelete.length} cache entries for proto file: ${protoFilePath}`)
+    } else {
+      const size = this.protoCache.size
+      this.protoCache.clear()
+      this.log(`Cleared all ${size} cache entries`)
+    }
+  }
+
+  /**
+   * 获取缓存的大小
+   */
+  getCacheSize(): number {
+    return this.protoCache.size
+  }
+
+  /**
+   * 检查指定 proto 类型是否已缓存
+   * @param protoFilePath proto 文件路径
+   * @param messageType 消息类型名称
+   * @returns 是否已缓存
+   */
+  isCached(protoFilePath: string, messageType: string): boolean {
+    const cacheKey = `${protoFilePath}-${messageType}`
+    return this.protoCache.has(cacheKey)
+  }
+
+  /**
+   * 获取所有已缓存的 proto 文件路径
+   * @returns 已缓存的 proto 文件路径数组
+   */
+  getCachedProtoFiles(): string[] {
+    const protoFiles = new Set<string>()
+    this.protoCache.forEach((_, key) => {
+      const protoFilePath = key.split('-').slice(0, -1).join('-')
+      protoFiles.add(protoFilePath)
+    })
+    return Array.from(protoFiles)
+  }
+
+  /**
+   * 日志输出
+   */
+  private log(message: string, level: 'log' | 'error' = 'log'): void {
+    if (!this.options.enableLog) return
+
+    const prefix = '[ProtoBufManager]'
+    if (level === 'error') {
+      console.error(prefix, message)
+    } else {
+      console.log(prefix, message)
+    }
+  }
+}
+

package/src/ProtobufPlaybackClient.ts

@@ -0,0 +1,238 @@
+import { ProtoBufManager } from './ProtoBufManager'
+import { TimerManager } from './TimerManager'
+import type { ProtoBufManagerOptions } from './ProtoBufManager'
+import type { LoadXodrOptions } from '@threejs-shared/xodr'
+import { loadXodr } from '@threejs-shared/xodr'
+
+/**
+ * Protobuf 回放客户端回调函数
+ */
+export interface ProtobufPlaybackCallbacks {
+  /** 每帧数据回调 */
+  onFrame?: (frameData: any) => void
+  /** 播放进度回调（当前秒数） */
+  onProcess?: (currentSecond: number) => void
+  /** 播放完成回调 */
+  onComplete?: () => void
+  /** 错误回调 */
+  onError?: (error: Error | any) => void
+}
+
+/**
+ * Protobuf 回放客户端配置
+ */
+export interface ProtobufPlaybackClientConfig {
+  /** Proto 文件路径 */
+  protoPath: string
+  /** 消息类型名称（例如：'SimulationMonitor.SimulationMonitorBag'） */
+  messageType: string
+  /** 文件下载配置（URL、请求头等） */
+  fileOptions: LoadXodrOptions
+  /** 播放频率（帧/秒，FPS），默认 50。例如：50 表示每秒播放 50 帧，即每 20ms 触发一次帧回调 */
+  frequency?: number
+  /** 每帧返回的数据量，默认 1。例如：1 表示每次 onFrame 回调接收 1 个帧数据对象；2 表示每次接收 2 个帧数据对象 */
+  frameSize?: number
+  /** ProtoBuf 管理器选项 */
+  protoBufOptions?: ProtoBufManagerOptions
+}
+
+/**
+ * Protobuf 回放客户端
+ * 
+ * 这是一个高级封装类，将 Protobuf 文件下载、解码和 TimerManager 的使用流程封装起来，
+ * 简化业务代码中的使用。业务代码只需要配置参数和定义回调函数即可。
+ * 
+ * @example
+ * ```typescript
+ * const client = new ProtobufPlaybackClient({
+ *   protoPath: '/proto/SimulationMonitor.proto',
+ *   messageType: 'SimulationMonitor.SimulationMonitorBag',
+ *   fileOptions: {
+ *     url: '/api/simpro/simtask/pb/download/?task_id=14532&scene_id=1276197',
+ *     responseType: 'arrayBuffer',
+ *     useStreaming: false,
+ *     header: {
+ *       Authorization: `JWT ${token}`,
+ *       'X-Project-Id': projectId,
+ *     }
+ *   },
+ *   frequency: 50,
+ * })
+ * 
+ * await client.loadAndPlay({
+ *   onFrame: (frameData) => {
+ *     console.log('Frame data:', frameData)
+ *   },
+ *   onProcess: (currentSecond) => {
+ *     console.log('Current second:', currentSecond)
+ *   },
+ *   onComplete: () => {
+ *     console.log('Playback completed')
+ *   },
+ *   onError: (error) => {
+ *     console.error('Error:', error)
+ *   }
+ * })
+ * ```
+ */
+export class ProtobufPlaybackClient {
+  private protoBufManager: ProtoBufManager
+  private timerManager: TimerManager | null = null
+  private config: ProtobufPlaybackClientConfig
+
+  constructor(config: ProtobufPlaybackClientConfig) {
+    this.config = config
+    this.protoBufManager = new ProtoBufManager(config.protoBufOptions)
+  }
+
+  /**
+   * 加载 Protobuf 文件并开始播放
+   * @param callbacks 事件回调函数
+   * @returns Promise<void>
+   */
+  async loadAndPlay(callbacks?: ProtobufPlaybackCallbacks): Promise<void> {
+    try {
+      // 1. 下载文件
+      const fileContent = await loadXodr(this.config.fileOptions) as ArrayBuffer | Uint8Array
+
+      // 2. 加载 Proto 文件
+      const protobufType = await this.protoBufManager.loadProto(
+        this.config.protoPath,
+        this.config.messageType
+      )
+
+      // 3. 解码文件内容
+      let decodedData: any
+      try {
+        decodedData = protobufType.decode(fileContent as Uint8Array)
+      } catch (decodeError) {
+        // 如果解码失败，尝试解析为 JSON 错误消息
+        try {
+          const decoder = new TextDecoder('utf-8')
+          const rawText = decoder.decode(fileContent as ArrayBuffer)
+          const errorData = JSON.parse(rawText)
+          const error = new Error(errorData?.err || 'Failed to decode protobuf file')
+          callbacks?.onError?.(error)
+          throw error
+        } catch (jsonError) {
+          const error = decodeError instanceof Error 
+            ? decodeError 
+            : new Error('Failed to decode protobuf file')
+          callbacks?.onError?.(error)
+          throw error
+        }
+      }
+
+      // 4. 创建 TimerManager 并开始播放
+      // frequency: 播放频率（帧/秒，FPS），默认 50，表示每秒播放 50 帧数据
+      // 例如：frequency = 50 表示每 20ms（1000ms / 50）触发一次帧回调
+      const frequency = this.config.frequency || 50
+      // frameSize: 每帧返回的数据量，默认 1，表示每次回调返回 1 个帧数据对象
+      // 例如：frameSize = 1 表示每次 onFrame 回调接收 1 个帧数据；frameSize = 2 表示每次接收 2 个帧数据
+      const frameSize = this.config.frameSize || 1
+      
+      if (!decodedData.frames || !Array.isArray(decodedData.frames)) {
+        throw new Error('Decoded data does not contain a valid "frames" array')
+      }
+
+      this.timerManager = new TimerManager(decodedData.frames, frequency, frameSize)
+      
+      this.timerManager.connect(
+        (frameData: any) => {
+          callbacks?.onFrame?.(frameData)
+        },
+        (currentSecond: number) => {
+          callbacks?.onProcess?.(currentSecond)
+        },
+        () => {
+          callbacks?.onComplete?.()
+        }
+      )
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error))
+      callbacks?.onError?.(err)
+      throw err
+    }
+  }
+
+  /**
+   * 开始播放（如果已加载）
+   */
+  start(): void {
+    if (!this.timerManager) {
+      throw new Error('TimerManager is not initialized. Please call loadAndPlay() first.')
+    }
+    this.timerManager.start()
+  }
+
+  /**
+   * 从指定秒数开始播放
+   * @param startSecond 起始秒数
+   */
+  startFrom(startSecond: number): void {
+    if (!this.timerManager) {
+      throw new Error('TimerManager is not initialized. Please call loadAndPlay() first.')
+    }
+    this.timerManager.startFrom(startSecond)
+  }
+
+  /**
+   * 暂停播放
+   */
+  pause(): void {
+    if (!this.timerManager) {
+      console.warn('TimerManager is not initialized. Cannot pause.')
+      return
+    }
+    this.timerManager.pause()
+  }
+
+  /**
+   * 继续播放
+   */
+  resume(): void {
+    if (!this.timerManager) {
+      console.warn('TimerManager is not initialized. Cannot resume.')
+      return
+    }
+    this.timerManager.resume()
+  }
+
+  /**
+   * 停止播放
+   */
+  stop(): void {
+    if (this.timerManager) {
+      this.timerManager.stop()
+    }
+  }
+
+  /**
+   * 重置播放器（可重新开始）
+   */
+  reset(): void {
+    if (!this.timerManager) {
+      console.warn('TimerManager is not initialized. Cannot reset.')
+      return
+    }
+    this.timerManager.reset()
+  }
+
+  /**
+   * 销毁客户端，清理所有资源
+   */
+  destroy(): void {
+    if (this.timerManager) {
+      this.timerManager.stop()
+      this.timerManager = null
+    }
+  }
+
+  /**
+   * 获取 TimerManager 实例（用于高级操作）
+   */
+  getTimerManager(): TimerManager | null {
+    return this.timerManager
+  }
+}
+

package/src/ProtobufWebSocketClient.ts

@@ -0,0 +1,125 @@
+import { ProtoBufManager } from './ProtoBufManager'
+import { WebSocketManager, WebSocketStatus, MessageFormat } from './WebSocketManager'
+import type { ProtobufType, WebSocketManagerOptions, WebSocketCallbacks, ProtoBufManagerOptions } from './index'
+
+/**
+ * Protobuf WebSocket 客户端配置
+ */
+export interface ProtobufWebSocketClientConfig {
+  /** Proto 文件路径 */
+  protoPath: string
+  /** 消息类型名称（例如：'SimulationMonitor.SimulationMonitorMsg'） */
+  messageType: string
+  /** WebSocket URL */
+  wsUrl: string
+  /** WebSocket 管理器选项 */
+  wsOptions?: WebSocketManagerOptions
+  /** ProtoBuf 管理器选项 */
+  protoBufOptions?: ProtoBufManagerOptions
+}
+
+/**
+ * Protobuf WebSocket 客户端
+ * 
+ * 这是一个高级封装类，将 ProtoBufManager 和 WebSocketManager 的使用流程封装起来，
+ * 简化业务代码中的使用。业务代码只需要配置参数和定义回调函数即可。
+ * 
+ * @example
+ * ```typescript
+ * const client = new ProtobufWebSocketClient({
+ *   protoPath: '/proto/SimulationMonitor.proto',
+ *   messageType: 'SimulationMonitor.SimulationMonitorMsg',
+ *   wsUrl: 'ws://localhost:8080',
+ *   wsOptions: {
+ *     autoReconnect: true,
+ *     reconnectDelay: 3000,
+ *   },
+ *   protoBufOptions: {
+ *     enableLog: true, // 控制 ProtoBufManager 的日志
+ *   }
+ * })
+ * 
+ * await client.connect({
+ *   onOpen: () => {
+ *     // 连接成功后可以在这里发送初始消息
+ *     client.send({ frameRate: { frameRate: 20 } })
+ *   },
+ *   onMessage: (data) => {
+ *     console.log('Received:', data)
+ *   }
+ * })
+ * ```
+ */
+export class ProtobufWebSocketClient {
+  private protoBufManager: ProtoBufManager
+  public webSocketManager: WebSocketManager | null = null
+  private config: ProtobufWebSocketClientConfig
+  private protobufType: ProtobufType | null = null
+
+  constructor(config: ProtobufWebSocketClientConfig) {
+    this.config = config
+    this.protoBufManager = new ProtoBufManager(config.protoBufOptions)
+  }
+
+  /**
+   * 连接 WebSocket（会自动加载 Proto 文件）
+   * @param callbacks 事件回调函数
+   * @returns Promise<void>
+   */
+  async connect(callbacks?: WebSocketCallbacks): Promise<void> {
+    try {
+      // 加载 Proto 文件
+      this.protobufType = await this.protoBufManager.loadProto(
+        this.config.protoPath,
+        this.config.messageType
+      )
+      
+      // 创建 WebSocket 管理器
+      this.webSocketManager = new WebSocketManager(
+        this.config.wsUrl,
+        this.protobufType,
+        this.config.wsOptions
+      )
+
+      // 连接 WebSocket
+      this.webSocketManager.connect(callbacks)
+    } catch (error) {
+      console.error('Protobuf WebSocket 连接失败:', error)
+      throw error
+    }
+  }
+  /**
+   * 发送消息
+   * @param message 要发送的消息对象或 JSON 字符串
+   * @param format 消息格式，默认为 Protobuf 格式
+   * @throws 如果连接未建立或消息验证失败
+   */
+  send(message: object | string, format: MessageFormat = MessageFormat.PROTOBUF): void {
+    if (!this.webSocketManager) {
+      throw new Error('WebSocket is not connected. Please call connect() first.')
+    }
+    this.webSocketManager.send(message, format)
+  }
+
+  /**
+   * 断开连接
+   * @param code 关闭代码
+   * @param reason 关闭原因
+   */
+  disconnect(code?: number, reason?: string): void {
+      if (this.webSocketManager) {
+      this.webSocketManager.disconnect(code, reason)
+      }
+  }
+  /**
+   * 销毁客户端，清理所有资源
+   */
+  destroy(): void {
+    if (this.webSocketManager) {
+      this.webSocketManager.destroy()
+      this.webSocketManager = null
+    }
+    this.protobufType = null
+  }
+}
+

package/src/TimerManager.ts

@@ -0,0 +1,103 @@
+type FrameDataCallback = (frameData: Array<{ id: number; value: number }>) => void
+type Callback = (args?: any) => void
+
+export class TimerManager {
+  private dataArray: Array<{ id: number; value: number }> // 数据数组
+  private frameSize: number // 每帧返回的数据量
+  private interval: number // 每帧的时间间隔（毫秒）
+  private currentIndex: number // 当前帧的起始索引
+  private timer: ReturnType<typeof setInterval> | null // 定时器句柄
+  isPaused: Boolean // 是否暂停
+  private onFrame: (params: any) => void // 是否暂停
+  private onComplete: Callback // 播放完成时回调函数，是否暂停
+  private onProcess: Callback // 播放过程中回调函数
+
+  constructor(dataArray = [], interval = 50, frameSize = 1) {
+    this.dataArray = dataArray
+    this.frameSize = frameSize
+    this.interval = interval
+    this.currentIndex = 0
+    this.timer = null
+    this.isPaused = false
+    this.onFrame = () => {
+      console.log('Frame updated')
+    }
+    this.onComplete = () => {
+      console.log('Timer complete')
+    }
+    this.onProcess = (args?: any) => {
+      console.log('Timer process', args)
+    }
+  }
+  // 开始模拟 WebSocket 数据发送
+  public connect(onFrame: FrameDataCallback, onProcess?: Callback, onComplete?: Callback): void {
+    this.onFrame = onFrame || this.onFrame
+    this.onProcess = onProcess || this.onProcess
+    this.onComplete = onComplete || this.onComplete
+    if (this.timer) {
+      console.warn('Simulation is already running.')
+      return
+    }
+    this.start()
+  }
+  public start(): void {
+    const processFrame = () => {
+      if (this.isPaused) return // 如果暂停，跳过处理
+      if (this.currentIndex >= this.dataArray.length) {
+        this.stop() // 停止定时器
+        if (this.onComplete) this.onComplete() // 调用完成回调
+        return
+      }
+      const frameData: any = this.dataArray.slice(this.currentIndex, this.currentIndex + this.frameSize) // 获取当前帧数据
+      this.currentIndex += this.frameSize // 更新索引
+      this.onFrame(frameData[0]) // 调用帧数据处理回调
+
+      const currentSecond = Math.floor(this.currentIndex / this.interval)
+      this.onProcess?.(currentSecond)
+    }
+
+    this.timer && clearInterval(this.timer)
+    this.timer = setInterval(processFrame, 1000 / this.interval)
+  }
+  public startFrom(startSecond: number = 0) {
+    this.currentIndex = startSecond * this.interval
+    // this.isPaused = false
+    this.start()
+  }
+  // 停止模拟
+  public stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer)
+      this.timer = null
+      this.isPaused = true
+      console.log('Simulation stopped.')
+    }
+  }
+  // 重置模拟器（可重新开始）
+  public reset(): void {
+    this.stop()
+    this.currentIndex = 0
+    this.isPaused = false
+    this.start()
+    console.log('Simulation reset.')
+  }
+  // 暂停模拟
+  public pause(): void {
+    if (this.timer) {
+      this.isPaused = true // 设置暂停状态
+      // console.log('Simulation paused.')
+    } else {
+      console.warn('Simulation is not running. Cannot pause.')
+    }
+  }
+
+  // 继续模拟
+  public resume(): void {
+    if (this.timer && this.isPaused) {
+      this.isPaused = false // 恢复非暂停状态
+      // console.log('Simulation resumed.')
+    } else {
+      console.warn('Simulation is not running or already resumed.')
+    }
+  }
+}

package/src/WebSocketManager.ts

@@ -0,0 +1,352 @@
+import type { Type as ProtobufType } from 'protobufjs'
+
+/**
+ * WebSocket 连接状态
+ */
+export enum WebSocketStatus {
+  CONNECTING = 'CONNECTING',
+  CONNECTED = 'CONNECTED',
+  DISCONNECTING = 'DISCONNECTING',
+  DISCONNECTED = 'DISCONNECTED',
+  ERROR = 'ERROR'
+}
+
+/**
+ * 消息发送格式
+ */
+export enum MessageFormat {
+  /** JSON 格式 */
+  JSON = 'JSON',
+  /** Protobuf 二进制格式 */
+  PROTOBUF = 'PROTOBUF',
+  /** 原始字符串格式 */
+  STRING = 'STRING'
+}
+
+/**
+ * WebSocket 管理器配置选项
+ */
+export interface WebSocketManagerOptions {
+  /** 是否启用自动重连 */
+  autoReconnect?: boolean
+  /** 重连延迟时间（毫秒） */
+  reconnectDelay?: number
+  /** 最大重连次数 */
+  maxReconnectAttempts?: number
+  /** 是否启用日志 */
+  enableLog?: boolean
+}
+
+/**
+ * WebSocket 事件回调
+ */
+export interface WebSocketCallbacks {
+  /** 连接打开时的回调 */
+  onOpen?: () => void
+  /** 接收到消息时的回调 */
+  onMessage?: (data: any) => void
+  /** 连接错误时的回调 */
+  onError?: (error: Event) => void
+  /** 连接关闭时的回调 */
+  onClose?: (event: CloseEvent) => void
+  /** 重连时的回调 */
+  onReconnect?: (attempt: number) => void
+}
+
+/**
+ * WebSocket 管理器，用于管理基于 Protobuf 的 WebSocket 连接
+ */
+export class WebSocketManager {
+  private socket: WebSocket | null = null
+  private MessagePb: ProtobufType | null = null
+  private wsUrl: string
+  private status: WebSocketStatus = WebSocketStatus.DISCONNECTED
+  private reconnectAttempts = 0
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private options: Required<WebSocketManagerOptions>
+  private callbacks: WebSocketCallbacks = {}
+
+  constructor(wsUrl: string, protobufType: ProtobufType, options?: WebSocketManagerOptions) {
+    this.wsUrl = wsUrl
+    this.MessagePb = protobufType
+    this.options = {
+      autoReconnect: options?.autoReconnect ?? false,
+      reconnectDelay: options?.reconnectDelay ?? 3000,
+      maxReconnectAttempts: options?.maxReconnectAttempts ?? 5,
+      enableLog: options?.enableLog ?? true
+    }
+  }
+
+  /**
+   * 连接 WebSocket
+   * @param callbacks 事件回调
+   */
+  connect(callbacks?: WebSocketCallbacks): void {
+    if (this.socket && this.status === WebSocketStatus.CONNECTED) {
+      this.log('WebSocket is already connected')
+      return
+    }
+
+    // 保存回调
+    if (callbacks) {
+      this.callbacks = { ...this.callbacks, ...callbacks }
+    }
+
+    // 清理之前的连接
+    this.cleanup()
+    try {
+      this.status = WebSocketStatus.CONNECTING
+      this.socket = new WebSocket(this.wsUrl)
+      this.setupEventListeners()
+    } catch (error) {
+      this.status = WebSocketStatus.ERROR
+      this.log('Failed to create WebSocket:', error)
+      this.callbacks.onError?.(error as Event)
+      throw error
+    }
+  }
+
+  /**
+   * 设置事件监听器
+   */
+  private setupEventListeners(): void {
+    if (!this.socket) return
+
+    this.socket.addEventListener('open', () => {
+      this.status = WebSocketStatus.CONNECTED
+      this.reconnectAttempts = 0
+      this.log('WebSocket connected')
+      this.callbacks.onOpen?.()
+    })
+
+    this.socket.addEventListener('message', async (event: MessageEvent) => {
+      if (!this.MessagePb) {
+        this.log('Protobuf type is not set')
+        return
+      }
+
+      try {
+        const blob = event.data
+        const buffer = await blob.arrayBuffer()
+        const data = new Uint8Array(buffer)
+        const receivedMessage = this.MessagePb.decode(data)
+        this.callbacks.onMessage?.(receivedMessage)
+      } catch (error) {
+        this.log('Failed to decode message:', error)
+        this.callbacks.onError?.(error as Event)
+      }
+    })
+
+    this.socket.addEventListener('error', (error: Event) => {
+      this.status = WebSocketStatus.ERROR
+      this.log('WebSocket error:', error)
+      this.callbacks.onError?.(error)
+      
+      // 如果启用了自动重连，尝试重连
+      if (this.options.autoReconnect && this.reconnectAttempts < this.options.maxReconnectAttempts) {
+        this.scheduleReconnect()
+      }
+    })
+
+    this.socket.addEventListener('close', (event: CloseEvent) => {
+      this.status = WebSocketStatus.DISCONNECTED
+      this.log('WebSocket closed', { code: event.code, reason: event.reason })
+      this.callbacks.onClose?.(event)
+      
+      // 如果启用了自动重连且不是主动关闭，尝试重连
+      if (
+        this.options.autoReconnect &&
+        this.reconnectAttempts < this.options.maxReconnectAttempts &&
+        event.code !== 1000 // 1000 表示正常关闭
+      ) {
+        this.scheduleReconnect()
+      }
+    })
+  }
+
+  /**
+   * 发送消息
+   * @param message 要发送的消息对象或字符串
+   * @param format 消息格式，默认为 Protobuf 格式
+   * @throws 如果连接未建立或消息验证失败
+   */
+  send(message: object | string, format: MessageFormat = MessageFormat.PROTOBUF): void {
+    if (!this.socket || this.status !== WebSocketStatus.CONNECTED) {
+      throw new Error('WebSocket is not connected')
+    }
+
+    try {
+      if (format === MessageFormat.STRING) {
+        // 原始字符串格式发送，直接发送字符串
+        if (typeof message !== 'string') {
+          throw new Error('STRING format requires a string message')
+        }
+        this.socket.send(message)
+        this.log('Message sent (STRING):', message)
+      } else if (format === MessageFormat.JSON) {
+        // JSON 格式发送
+        if (typeof message === 'string') {
+          // 如果是字符串，直接发送（假设已经是 JSON 字符串）
+          this.socket.send(message)
+          this.log('Message sent (JSON):', message)
+        } else {
+          // 如果是对象，序列化为 JSON 字符串
+          const jsonString = JSON.stringify(message)
+          this.socket.send(jsonString)
+          this.log('Message sent (JSON):', message)
+        }
+      } else {
+        // Protobuf 格式发送
+        if (!this.MessagePb) {
+          throw new Error('Protobuf type is not set')
+        }
+
+        // 如果传入的是字符串，解析为对象
+        let messageObj: object
+        if (typeof message === 'string') {
+          try {
+            messageObj = JSON.parse(message)
+          } catch (error) {
+            throw new Error(`Invalid JSON string for Protobuf: ${error}`)
+          }
+        } else {
+          messageObj = message
+        }
+
+        // 验证数据是否符合 Protobuf 定义
+        const errMsg = this.MessagePb.verify(messageObj)
+        if (errMsg) {
+          throw new Error(`Message verification failed: ${errMsg}`)
+        }
+
+        // 创建 Protobuf 消息
+        const msg = this.MessagePb.create(messageObj)
+        
+        // 序列化消息为二进制格式
+        const buffer = this.MessagePb.encode(msg).finish()
+        
+        // 通过 WebSocket 发送二进制数据
+        this.socket.send(buffer)
+        this.log('Message sent (Protobuf):', messageObj)
+      }
+    } catch (error) {
+      this.log('Failed to send message:', error)
+      throw error
+    }
+  }
+
+  /**
+   * 断开连接
+   * @param code 关闭代码
+   * @param reason 关闭原因
+   */
+  disconnect(code?: number, reason?: string): void {
+    if (this.socket) {
+      this.status = WebSocketStatus.DISCONNECTING
+      this.socket.close(code ?? 1000, reason)
+      this.cleanup()
+      this.status = WebSocketStatus.DISCONNECTED
+    }
+  }
+
+  /**
+   * 获取当前连接状态
+   */
+  getStatus(): WebSocketStatus {
+    return this.status
+  }
+
+  /**
+   * 检查是否已连接
+   */
+  isConnected(): boolean {
+    return this.status === WebSocketStatus.CONNECTED && 
+           this.socket?.readyState === WebSocket.OPEN
+  }
+
+  /**
+   * 设置 Protobuf 类型
+   */
+  setProtobufType(protobufType: ProtobufType): void {
+    this.MessagePb = protobufType
+  }
+
+  /**
+   * 更新回调函数
+   */
+  updateCallbacks(callbacks: WebSocketCallbacks): void {
+    this.callbacks = { ...this.callbacks, ...callbacks }
+  }
+
+  /**
+   * 计划重连
+   */
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer)
+    }
+
+    this.reconnectAttempts++
+    this.log(`Scheduling reconnect attempt ${this.reconnectAttempts}/${this.options.maxReconnectAttempts}`)
+    
+    this.callbacks.onReconnect?.(this.reconnectAttempts)
+
+    this.reconnectTimer = setTimeout(() => {
+      this.log(`Reconnecting... (attempt ${this.reconnectAttempts})`)
+      try {
+        this.socket = new WebSocket(this.wsUrl)
+        this.setupEventListeners()
+      } catch (error) {
+        this.log('Reconnect failed:', error)
+        if (this.reconnectAttempts < this.options.maxReconnectAttempts) {
+          this.scheduleReconnect()
+        }
+      }
+    }, this.options.reconnectDelay)
+  }
+
+  /**
+   * 清理资源
+   */
+  private cleanup(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = null
+    }
+
+    if (this.socket) {
+      // 移除所有事件监听器
+      this.socket.onopen = null
+      this.socket.onmessage = null
+      this.socket.onerror = null
+      this.socket.onclose = null
+      
+      // 如果连接还在，关闭它
+      if (this.socket.readyState === WebSocket.OPEN || 
+          this.socket.readyState === WebSocket.CONNECTING) {
+        this.socket.close()
+      }
+      
+      this.socket = null
+    }
+  }
+
+  /**
+   * 日志输出
+   */
+  private log(...args: any[]): void {
+    if (this.options.enableLog) {
+      console.log('[WebSocketManager]', ...args)
+    }
+  }
+
+  /**
+   * 销毁实例，清理所有资源
+   */
+  destroy(): void {
+    this.disconnect()
+    this.callbacks = {}
+    this.MessagePb = null
+    this.reconnectAttempts = 0
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+import { ProtoBufManager } from './ProtoBufManager'
+import { WebSocketManager, WebSocketStatus, MessageFormat } from './WebSocketManager'
+import { ProtobufWebSocketClient } from './ProtobufWebSocketClient'
+import { ProtobufPlaybackClient } from './ProtobufPlaybackClient'
+import type { WebSocketManagerOptions, WebSocketCallbacks } from './WebSocketManager'
+import type { ProtobufWebSocketClientConfig } from './ProtobufWebSocketClient'
+import type { ProtobufPlaybackClientConfig, ProtobufPlaybackCallbacks } from './ProtobufPlaybackClient'
+import type { ProtoBufManagerOptions } from './ProtoBufManager'
+import { TimerManager } from './TimerManager'
+export { ProtoBufManager, WebSocketManager, WebSocketStatus, MessageFormat, ProtobufWebSocketClient, ProtobufPlaybackClient, TimerManager }
+export type { Type as ProtobufType } from 'protobufjs'
+export type { WebSocketManagerOptions, WebSocketCallbacks, ProtobufWebSocketClientConfig, ProtobufPlaybackClientConfig, ProtobufPlaybackCallbacks, ProtoBufManagerOptions }
+