@jnrs/lingshu-smart 2.2.46 → 3.0.0

package/AGENTS.md

@@ -38,7 +38,7 @@ const saveCases = (data?: ICase[]) => {
   /* 持久化到后端 */
 }
 const handlePreview = (currentCase?: ICase) => {
-  window.open(`/preview/${currentCase?.uuid}`)
+  window.open(`/preview/${currentCase?.id}`)
 }
 const handleExit = () => {
   /* 退出逻辑 */
@@ -56,25 +56,23 @@ const handleExit = () => {
 | --------------- | ----------------------------------- | --------------------------- | --------------------------------------------------- |
 | `loadCases`     | `(id?: string) => Promise<ICase[]>` | 编辑器初始化 / 方案管理弹窗 | **必填**。返回方案列表，组件内部写入 `useDataStore` |
 | `saveCases`     | `(cases?: ICase[]) => void`         | 点击保存按钮                | 将当前全部方案提交后端                              |
-| `handlePreview` | `(currentCase?: ICase) => void`     | 点击预览按钮                | 通常跳转至预览页并携带 `uuid`                       |
+| `handlePreview` | `(currentCase?: ICase) => void`     | 点击预览按钮                | 通常跳转至预览页并携带 `id`                         |
 | `handleExit`    | `() => void`                        | 点击退出按钮                | 返回上一页或关闭窗口                                |
 
-**注意：** 编辑模式不涉及 `onMessage` / `operating`。设备运转动画仅在预览看板中通过 WebSocket 驱动。
+**注意：** 编辑模式不涉及消息协议。设备运转动画仅在预览看板中通过 `feedSocketMessage` 经 `SocketDispatcher` 驱动。
 
 ---
 
 ### ViewPageDemo.vue — 预览/运行模式
 
-**职责：** 加载并展示指定方案、响应用户交互、接收 WebSocket 消息并驱动设备动画。
+**职责：** 加载并展示指定方案、响应用户交互、接收符合《socket-operating-api.md》的标准 Socket 协议消息（`envelope + payload`）并驱动设备动画。
 
 **核心结构：**
 
 ```vue
 <script setup lang="ts">
 import { ref, computed, onMounted } from 'vue'
-import type { ICase, ILayer, ILayerOperating, InteractiveUi } from '@/types'
-import { EnumModel } from '@/types'
-import { transRuntimeToPixel, transPercentToPixel } from '@/utils'
+import type { ICase, ILayer, InteractiveUi } from '@/types'
 import LingshuSmartPreview from '@/components/preview/index.vue'
 
 const lingshuSmartPreviewRef = ref()
@@ -97,29 +95,33 @@ const onDragEnd = (layer: ILayer, data: InteractiveUi) => {
   /* 拖拽结束 */
 }
 
-// 驱动设备运转 — 转发至预览组件 expose 的方法
-const operating = (data: ILayerOperating) => {
-  lingshuSmartPreviewRef.value?.operating(data)
+// WebSocket 消息入口 — 将原始消息直接喂给协议分发器（见下文「Socket 协议接入指南」）
+const onSocketMessage = (rawMessage: any) => {
+  lingshuSmartPreviewRef.value?.feedSocketMessage(rawMessage)
 }
 
-// WebSocket 消息入口 — 见下文「onMessage 编写指南」
-const onMessage = (rawMessage: any) => {
-  /* ... */
+// 订阅协议分发器回调（回执 command_ack / 透传 alarm_push 等，可选）
+const setHandlers = () => {
+  lingshuSmartPreviewRef.value?.setSocketHandlers({
+    onAck: (ack) => console.log('[command_ack]', ack?.payload),
+    onRaw: (raw) => console.log('[透传]', raw?.envelope?.type)
+  })
 }
 
 onMounted(() => {
-  // 从 URL 解析方案 UUID，例如 /preview/abc-123
+  // 从 URL 解析方案 ID，例如 /preview/abc-123
   const VIEW_PATH = '/preview/'
   if (location.pathname.includes(VIEW_PATH)) {
     currentCaseId.value = location.pathname.split(VIEW_PATH)[1]
   }
+  setHandlers()
 })
 </script>
 
 <template>
   <LingshuSmartPreview
     ref="lingshuSmartPreviewRef"
-    :case-uuid="currentCaseId"
+    :case-id="currentCaseId"
     :actions="{ loadCases, onTap, onMenuTap, onDragEnd }"
   />
 </template>
@@ -136,330 +138,248 @@ onMounted(() => {
 
 **Preview 组件 expose：**
 
-| 属性/方法     | 类型                              | 说明                 |
-| ------------- | --------------------------------- | -------------------- |
-| `currentCase` | `ICase \| null`                   | 当前加载的方案       |
-| `operating`   | `(data: ILayerOperating) => void` | 驱动指定设备运转动画 |
+| 属性/方法           | 类型                                                                   | 说明                                                                                               |
+| ------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `currentCase`       | `ICase \| null`                                                        | 当前加载的方案                                                                                     |
+| `feedSocketMessage` | `(msg: unknown) => void`                                               | **推荐**。下发一条标准信封协议消息（`envelope + payload`），经 `SocketDispatcher` 自动分发驱动画布 |
+| `setSocketHandlers` | `(handlers: { onAck?: (ack) => void; onRaw?: (raw) => void }) => void` | 订阅回执 `command_ack` 与透传（`alarm_push` / `runtime_status_push`）回调                          |
+| `operating`         | `(data: ILayerOperating) => void`                                      | 旧链路内部 `operating` 引擎，仅 WsProxy 等内部组件可选使用                                         |
+| `resetModels`       | `() => void`                                                           | 一键复位画布（所有模型按初始配置重建，含资源清空）                                                 |
 
 **Props：**
 
-| 属性            | 类型             | 默认值    | 说明                        |
-| --------------- | ---------------- | --------- | --------------------------- |
-| `caseUuid`      | `string`         | —         | **必填**。要展示的方案 UUID |
-| `actions`       | `PreviewActions` | `{}`      | 事件与数据加载回调          |
-| `appHittable`   | `boolean`        | `true`    | 画布是否可交互              |
-| `appFill`       | `string`         | `#424242` | 容器背景色                  |
-| `hideSceneFill` | `boolean`        | `false`   | 是否隐藏场景背景            |
+| 属性            | 类型             | 默认值    | 说明                      |
+| --------------- | ---------------- | --------- | ------------------------- |
+| `caseId`        | `string`         | —         | **必填**。要展示的方案 ID |
+| `actions`       | `PreviewActions` | `{}`      | 事件与数据加载回调        |
+| `appHittable`   | `boolean`        | `true`    | 画布是否可交互            |
+| `appFill`       | `string`         | `#424242` | 容器背景色                |
+| `hideSceneFill` | `boolean`        | `false`   | 是否隐藏场景背景          |
 
 ---
 
-## 📡 onMessage 编写指南
+## 📡 Socket 协议接入指南
+
+预览看板通过 WebSocket（或 SSE、轮询等）接收后端推送，将原始消息**直接交给** **`feedSocketMessage()`**。画布内置的 `SocketDispatcher` 负责解析、去重、校验并驱动设备动画，业务侧无需自行分支映射。
 
-预览看板通过 WebSocket（或 SSE、轮询等）接收后端推送，在 `onMessage` 中将原始消息**转换为 `ILayerOperating`**，再调用 `operating()` 驱动画布。
+> 协议规范以《socket-operating-api.md》为准（v3.5），本文仅摘录接入要点。
 
 ### 数据流
 
 ```
-WebSocket 原始消息
-  → onMessage 校验 & 解析
-  → 按 payload.type 分支映射
-  → operating(ILayerOperating)
-  → AppController.businessMap 三级匹配 `${className}_${id}` → 工位号
-  → 对应 ModelAbs.handleOperation → 子组件动画
+WebSocket 原始消息（envelope + payload）
+  → feedSocketMessage(rawMessage)      // 无需手动解析
+  → SocketDispatcher.dispatch
+      ├─ 识别传输层心跳 { type: 'ping' | 'pong' }，不进业务流程
+      ├─ 校验信封（envelope.id / type / payload 缺失则丢弃）
+      ├─ 按 envelope.id 去重（重复丢弃 + warn 日志）
+      └─ 按 envelope.type 分发
+          ├─ device_init     → 全量初始化设备状态 + 初始资源实体
+          ├─ device_command  → 增量驱动单设备状态（灯/进度/出入口/position 等）
+          ├─ resource_command→ 资源池生命周期：add / batch_add / transfer / remove / batch_remove
+          ├─ alarm_push      → 设备告警高亮（resolved 解除）
+          ├─ runtime_status_push → 无模型，透传 onRaw 供全局 UI 处理
+          └─ scene_reset     → 画布全部模型重建 + 资源清空 + 告警解除
+  → AppController / ResourcePool → ModelAbs.handleOperation → 子组件动画
+  → 处理完毕产出回执 command_ack（0 / 400 / 404 / 409 / 500），经 onAck 回调交给宿主业务；是否经 WebSocket 回推后端由业务按需决定（可选）
 ```
 
-### 消息格式约定
-
-参考 `src/playground/mockWebSocketData.ts`，推荐外层结构：
+### 消息格式约定（envelope + payload）
 
 ```typescript
-interface WebSocketMessage {
-  traceId: string // 链路追踪 ID
-  type: 'update' // 消息类型，目前仅处理 'update'
-  payload: Payload // 业务载荷，内含 payload.type 标识设备/资源
+interface MessageEnvelope {
+  id: string // 唯一 ID（雪花算法 Long 型字符串），画布据此去重
+  type: EnvelopeType // device_init | device_command | resource_command
+  // | alarm_push | runtime_status_push | scene_reset | command_ack
+  timestamp: string // ISO 8601
+  case_id?: string
 }
-```
-
-**入口校验模板：**
 
-```typescript
-const onMessage = (rawMessage: any) => {
-  if (!rawMessage?.type || !rawMessage?.payload) {
-    console.warn('无效的 WebSocket 消息格式', rawMessage)
-    return
-  }
-
-  const { type, payload } = rawMessage
-
-  if (type === 'update') {
-    switch (payload.type) {
-      case 'Resource':
-        /* 资源增删 */ break
-      case 'MachineTool':
-        /* 机床状态 */ break
-      case 'ResourceStore':
-        /* 资源库/随行托 */ break
-      case 'SingleJointRobot':
-        /* 单关节机器人 */ break
-      case 'DoubleJointRobot':
-        /* 双关节机器人 */ break
-      case 'Rgv':
-        /* RGV */ break
-      case 'LoadingStation':
-        /* 装载站 */ break
-      case 'MarkingMachine':
-        /* 打标机 */ break
-      case 'CleaningMachine':
-        /* 清洗机 */ break
-      case 'Rail':
-        /* 轨道拖链 */ break
-    }
-  }
+interface SocketMessage<T> {
+  envelope: MessageEnvelope
+  payload: T
 }
 ```
 
-### 匹配规则（重要）
-
-`operating()` 通过三级匹配定位画布上的设备：`className → id → 工位号`：
-
-- `id` 作为前后端对于设备的唯一识别字段
-- `rawData` 为后端接口返回的原始数据 payload，其中包含 id 属性，如果设备注册了交互事件，则该对象会存在于回调函数的返回值中，供"点击设备后弹窗展示设备详情"等业务需求使用
-- `className` 使用 `EnumModel` 枚举值，例如 `EnumModel.MACHINE_TOOL`
-- 资源增删时，`addType` / `removeType` 为目标设备的 `className`，`addId` / `removeId` 为目标设备 `id`
-- **工位号匹配（三级）**：当同一 `id` 的设备（如 `ResourceStore`）在画布上被拆分为多个 UI（不同工位号范围）时，`businessMap` 以数组存储同 `className + id` 的多个模型，再通过 `resource.index`（工位号）匹配到具体 UI。模型通过 `containsStationIndex` 方法判断是否包含该工位号。仅有一个模型时直接使用，无需工位号匹配
-
-匹配失败时控制台输出：`模型操作失败: 模型未匹配到`。
-
-### 各业务场景映射示例
-
-#### 1. 资源增删（`payload.type === 'Resource'`）
-
-Resource 不在编辑器中进行维护，是根据业务数据动态添加或删除的一类 UI 图形，如“托盘”、“刀具”。
-同一消息可同时包含新增与移除操作。
+**入口模板（顺带订阅回执，可选）：**
 
 ```typescript
-// 新增资源到设备工位
-if (payload.addType && payload.addId) {
-  operating({
-    className: payload.addType, // 如 EnumModel.MACHINE_TOOL
-    id: payload.addId,
-    rawData: payload,
-    resource: {
-      handleType: 'add',
-      resourceType: payload.resourceType, // EnumResourceType.PALLET | TOOL
-      name: payload.name,
-      color: payload.status === 3 ? 'green' : '#424242',
-      index: payload.addSiteNumber, // 工位槽索引
-      rawData: payload
-    }
-  })
-}
-
-// 从设备工位移除资源
-if (payload.removeType && payload.removeId) {
-  operating({
-    className: payload.removeType,
-    id: payload.removeId,
-    rawData: payload,
-    resource: {
-      handleType: 'remove',
-      resourceType: payload.resourceType,
-      index: payload.removeSiteNumber,
-      rawData: payload
-    }
-  })
+// WebSocket onmessage → 直接透传，无需解析
+const onSocketMessage = (rawMessage: any) => {
+  lingshuSmartPreviewRef.value?.feedSocketMessage(rawMessage)
 }
-```
 
-#### 2. 机床（`payload.type === 'MachineTool'`）
-
-```typescript
-operating({
-  className: EnumModel.MACHINE_TOOL,
-  id: payload.id,
-  rawData: payload,
-  light: {
-    color: payload.status === 2 ? 'green' : '#424242',
-    blinking: payload.status !== 2,
-    rotating: payload.status === 2
-  },
-  progress: {
-    percent: payload.percent, // 0 ~ 1
-    textContent: payload.status === 2 ? '运行中' : '待机中'
-  },
-  entrance: {
-    isIn: payload.isIn,
-    isOut: payload.isOut
-  },
-  stationRotatable: payload.stationRotatable // false 横向 / true 纵向
+// 订阅回执 command_ack 与透传消息（可选，用于联调与全局 UI）
+lingshuSmartPreviewRef.value?.setSocketHandlers({
+  onAck: (ack) => console.log('[command_ack]', ack?.payload),
+  onRaw: (raw) => console.log('[透传]', raw?.envelope?.type)
 })
 ```
 
-#### 3. 资源库 / 随行托（`payload.type === 'ResourceStore'`）
+### 核心语义
 
-```typescript
-operating({
-  className: EnumModel.RESOURCE_STORE,
-  id: payload.id,
-  rawData: payload,
-  light: {
-    color: payload.status === 2 ? 'green' : '#424242',
-    blinking: payload.status === 2
-  },
-  x: transPercentToPixel(payload.x, 2, 'width') // 沿轨道移动时需转换
-})
-```
+- **字段缺失即跳过（防抖动）**：`device_command` / `resource_command` 中未携带的字段保持当前状态；携带的字段（哪怕为 0 / false / 空串）必须按值设置。因此高频位置消息可只传变化字段，如仅 `position.x`
 
-#### 4. 单关节机器人（`payload.type === 'SingleJointRobot'`）
+- **`device_init`** **为全量覆盖**：先复位该设备（缺失字段重置默认值、工位资源清空），再应用显式字段
 
-```typescript
-operating({
-  className: EnumModel.SINGLE_JOINT_ROBOT,
-  id: payload.id,
-  rawData: payload,
-  light: {
-    color: payload.status === 2 ? 'green' : '#424242',
-    blinking: payload.status === 2
-  },
-  x: transPercentToPixel(payload.x, 2, 'width'),
-  j1: payload.j1, // 一级关节角度（度）
-  currentFixture: payload.currentFixture // EnumResourceType.PALLET | TOOL
-})
-```
+- **资源为独立实体**：由画布对象资源池管理，按 `resource_id` 全局索引，工位退化为纯位置槽（三级坐标：设备 → 层 → 工位）
 
-#### 5. 双关节机器人（`payload.type === 'DoubleJointRobot'`）
+- **已满校验（静态强校验）**：资源类型与目标工位声明类型不匹配回执 `409`；设备/工位未找到回执 `404`；参数错误回执 `400`；成功回执 `0`；异常回执 `500`
 
-```typescript
-operating({
-  className: EnumModel.DOUBLE_JOINT_ROBOT,
-  id: payload.id,
-  rawData: payload,
-  light: {
-    color: payload.status === 0 ? '#f30' : '#424242'
-  },
-  currentFixture: payload.currentFixture,
-  x: transPercentToPixel(payload.x, 2, 'width'),
-  j1: payload.j1,
-  j2: payload.j2
-})
-```
+- **字段全层级 snake_case**：`device_type` / `device_id` / `device_station` / `current_fixture` 等
 
-#### 6. 装载站（`payload.type === 'LoadingStation'`）
+### 设备类型枚举（device_type）
 
-```typescript
-operating({
-  className: EnumModel.LOADING_STATION,
-  id: payload.id,
-  rawData: payload,
-  light: { color: payload.status === 2 ? 'green' : '#424242', blinking: payload.status === 2 },
-  progress: { percent: payload.percent, textContent: payload.textContent },
-  entrance: { isIn: payload.isIn, isOut: payload.isOut },
-  stationRotatable: payload.stationRotatable
-})
-```
+| 枚举值                      | 说明         |
+| --------------------------- | ------------ |
+| `machine_tool`              | 机床         |
+| `loading_station`           | 装载站       |
+| `shuttle_station`           | 接驳站       |
+| `material_track`            | 料道         |
+| `marking_machine`           | 打标机       |
+| `cleaning_machine`          | 清洗机       |
+| `single_joint_robot`        | 单关节机器人 |
+| `double_joint_robot`        | 双关节机器人 |
+| `rgv`                       | RGV          |
+| `resource_store`            | 资源库       |
+| `pallet`                    | 托盘         |
+| `resource_operation_window` | 资源操作窗口 |
 
-#### 7. 打标机（`payload.type === 'MarkingMachine'`）
+### 资源类型枚举（resource_type）
 
-```typescript
-operating({
-  className: EnumModel.MARKING_MACHINE,
-  id: payload.id,
-  rawData: payload,
-  light: { color: payload.lightColor, blinking: payload.blinking },
-  progress: { percent: payload.percent, textContent: payload.textContent },
-  entrance: { isIn: payload.isIn, isOut: payload.isOut },
-  laserSiteNumberArray: payload.laserSiteNumberArray // { site, active }[]
-})
-```
+| 值          | 资源 |
+| ----------- | ---- |
+| `workpiece` | 工件 |
+| `tool`      | 刀具 |
+| `auxiliary` | 辅料 |
 
-#### 8. 清洗机（`payload.type === 'CleaningMachine'`）
+### 各消息示例
 
-```typescript
-operating({
-  className: EnumModel.CLEANING_MACHINE,
-  id: payload.id,
-  rawData: payload,
-  light: { color: payload.lightColor, blinking: payload.blinking },
-  progress: { percent: payload.percent, textContent: payload.textContent },
-  entrance: { isIn: payload.isIn, isOut: payload.isOut }
-})
-```
+#### 1. `device_command` — 驱动单设备状态（增量）
 
-#### 9. RGV（`payload.type === 'Rgv'`）
+```json
+{
+  "envelope": { "id": "msg_xxx", "type": "device_command", "timestamp": "2026-08-31T10:30:00.000Z" },
+  "payload": {
+    "device_type": "single_joint_robot",
+    "device_id": "RBT-001",
+    "light": { "color": "#66DC7A", "blinking": true },
+    "position": { "x": 0.6, "j1": 45 },
+    "current_fixture": "tool"
+  }
+}
+```
 
-```typescript
-operating({
-  className: EnumModel.RGV,
-  id: payload.id,
-  rawData: payload,
-  light: { color: payload.lightColor, blinking: payload.blinking },
-  x: transPercentToPixel(payload.x, 2, 'width'),
-  j1: payload.j1, // 旋转角度
-  forkXY: payload.forkXY, // 货叉进出移动比例 [−1,1]
-  forkZ: payload.forkZ // 货叉升降比例 [0,1]
-})
+#### 2. `device_init` — 设备初始化（全量）
+
+```json
+{
+  "envelope": { "id": "msg_xxx", "type": "device_init", "timestamp": "2026-08-31T10:30:00.000Z" },
+  "payload": {
+    "devices": [
+      {
+        "device_type": "machine_tool",
+        "device_id": "CNC-001",
+        "light": { "color": "green", "blinking": false },
+        "resources": [{ "resource_type": "workpiece", "resource_id": "PRD-001", "name": "毛坯1", "device_station": 1 }]
+      }
+    ]
+  }
+}
 ```
 
-#### 10. 轨道拖链（`payload.type === 'Rail'`）
+#### 3. `resource_command` — 资源生命周期
+
+```json
+// add（进场）
+{ "envelope": { "id": "m1", "type": "resource_command", "timestamp": "..." },
+  "payload": { "operation": "add", "resource_id": "PRD-003", "resource_type": "workpiece",
+    "name": "毛坯3", "color": "#F2C34F",
+    "to": { "device_type": "machine_tool", "device_id": "CNC-001", "device_station": 1 } } }
+
+// transfer（流转）
+{ "envelope": { "id": "m2", "type": "resource_command", "timestamp": "..." },
+  "payload": { "operation": "transfer", "resource_id": "PRD-001", "resource_type": "workpiece",
+    "from": { "device_type": "machine_tool", "device_id": "CNC-001", "device_station": 1 },
+    "to": { "device_type": "resource_store", "device_id": "RS-001", "device_station": 3 } } }
+
+// remove（离场）
+{ "envelope": { "id": "m3", "type": "resource_command", "timestamp": "..." },
+  "payload": { "operation": "remove", "resource_id": "PRD-001" } }
+
+// batch_add（批量进场） / batch_remove（批量离场）
+{ "envelope": { "id": "m4", "type": "resource_command", "timestamp": "..." },
+  "payload": { "operation": "batch_add", "resources": [ { "resource_id": "PRD-4", "resource_type": "workpiece",
+    "to": { "device_type": "machine_tool", "device_id": "CNC-001", "device_station": 2 } } ] } }
+```
 
-```typescript
-operating({
-  className: EnumModel.RAIL,
-  id: payload.id, // 轨道图层 id
-  rawData: payload,
-  x: payload.x, // 拖链位置（像素，无需 runtime 转换）
-  botId: payload.botId // 关联的移动设备 rawData.id
-})
+#### 4. `alarm_push` — 全局告警推送（设备高亮）
+
+```json
+{
+  "envelope": { "id": "m5", "type": "alarm_push", "timestamp": "..." },
+  "payload": {
+    "alarm_id": "ALM-001",
+    "device_type": "machine_tool",
+    "device_id": "CNC-001",
+    "device_name": "CNC-001",
+    "alarm_level": "critical",
+    "alarm_type": "threshold_exceeded",
+    "alarm_message": "主轴温度过高",
+    "current_value": 72.5,
+    "threshold_value": 70,
+    "status": "pending",
+    "create_time": 1776230000
+  }
+}
 ```
 
-### 运行时坐标转换
+- `status: 'pending'` 点亮设备告警高亮；同一 `alarm_id` 以 `status: 'resolved'` 重推 → 解除高亮
 
-后端推送的 `x` / `y` 通常为**物理/runtime 坐标**（如毫米），画布使用**像素坐标**。转换公式：
+- 该消息同样透传给 `onRaw`，供业务弹窗等场景使用
 
-```typescript
-import { transRuntimeToPixel } from '@jnrs/lingshu-smart'
+#### 5. `scene_reset` — 场景复位
 
-// 宽方向：pixel = runtimeVal * (scene.width / scene.runtime_width)
-const pixelX = transRuntimeToPixel(payload.x, 1, 'width')
-const pixelY = transRuntimeToPixel(payload.y, 1, 'height')
+```json
+{ "envelope": { "id": "m6", "type": "scene_reset", "timestamp": "..." }, "payload": {} }
 ```
 
-### 百分比转换为像素数值
+### 坐标与数值约定
 
-后端推送的 `x` / `y` 通常为**百分比数值**（范围通常为[-1,1]），画布使用**像素坐标**。转换公式：
+| 约定项   | 说明                                                                          |
+| -------- | ----------------------------------------------------------------------------- |
+| 序号体系 | 工位 `device_station` 与层 `device_layer` 均 **1-based**                      |
+| 比例值   | 进度、货叉位移、设备位移 `position.x/y/z` 使用比例值 \[0,1]，画布自动换算像素 |
+| 角度值   | 关节/旋转角度 `position.j1/j2` 单位为 **度**                                  |
+| 时间格式 | `envelope.timestamp` 用 ISO 8601；payload 内业务时间戳用 Unix **秒**          |
 
-```typescript
-import { transPercentToPixel } from '@jnrs/lingshu-smart'
+### 心跳与重连
 
-// 宽方向：pixel = percentVal * scene.width
-const pixelX = transPercentToPixel(payload.x, 2, 'width')
-const pixelY = transPercentToPixel(payload.y, 1, 'height')
-```
+- 前端定时发送 `{ "type": "ping" }`，后端回复 `{ "type": "pong" }`；心跳为传输层消息，**不包信封**，画布识别后直接忽略不进业务流程
 
-**前提：** 方案 `IScene` 中需配置 `runtime_width` / `runtime_height`。该函数读取 `useEditorStore().scene`，预览页需确保场景数据已加载。
+- 断线后指数退避重连：初始 1s，每次翻倍，上限 30s
 
 ### WebSocket 接入示例
 
 ```typescript
 onMounted(() => {
-  const ws = new WebSocket('wss://your-server/ws')
+  const ws = new WebSocket(`wss://your-server/ws?token=${token}`)
   ws.onmessage = (event) => {
-    try {
-      onMessage(JSON.parse(event.data))
-    } catch (e) {
-      console.error('WebSocket 消息解析失败', e)
-    }
+    onSocketMessage(JSON.parse(event.data))
+  }
+  ws.onclose = () => {
+    /* 断线重连（建议指数退避） */
   }
 })
 ```
 
-本地调试可复用 `mockWebSocketData.ts` 中的 `firstBatchMessages` / `secondBatchMessages`。
-
 ---
 
 ## 📊 ILayerOperating 类型参考
 
-`ILayerOperating` 是设备层运转状态的**联合类型**，用于 `operating()` 入参。所有子类型均继承基类 `IModelOperating`，并通过 `className` 字段区分具体设备。
+`ILayerOperating` 是设备层运转状态的**联合类型**，为画布 `operating()` 内部引擎的入参。所有子类型均继承基类 `IModelOperating`，并通过 `className` 字段区分具体设备。
+
+> **业务接入说明：** 业务侧**不应直接构造** **`ILayerOperating`**。`SocketDispatcher` 已把标准协议消息（`envelope + payload`）转换为该内部类型并交由 `operating()` 驱动画布。下表仅用于理解内部驱动原理，或为 WsProxy 等内部组件的桥接逻辑提供类型参考。
 
 ### 基类 IModelOperating
 
@@ -491,42 +411,41 @@ type ILayerOperating =
 
 ### 子类型一览
 
-| 类型                         | className            | 特有属性                                                             | 子组件能力                                          | 典型 payload.type  |
-| ---------------------------- | -------------------- | -------------------------------------------------------------------- | --------------------------------------------------- | ------------------ |
-| `IMachineToolOperating`      | `MACHINE_TOOL`       | `light?`, `progress?`, `entrance?`, `stationRotatable?`, `isWorking?` | 状态灯（含旋转）、进度条、出入口、工位槽、工作状态（玻璃呼吸） | `MachineTool`      |
-| `ILoadingStationOperating`   | `LOADING_STATION`    | `light?`, `progress?`, `entrance?`, `stationRotatable?`              | 状态灯（无旋转）、进度条、出入口、工位槽            | `LoadingStation`   |
-| `IShuttleStationOperating`   | `SHUTTLE_STATION`    | `light?`, `layerLightColor?`, `layerLightBlinking?`, `layerVisible?` | 状态灯、多工位层状态灯/显隐                         | `ShuttleStation`   |
-| `IMarkingMachineOperating`   | `MARKING_MACHINE`    | `light?`, `progress?`, `entrance?`, `laserSiteNumberArray?`          | 状态灯、进度条、出入口、工位槽、激光工位（电报节奏闪动） | `MarkingMachine`   |
-| `ICleaningMachineOperating`  | `CLEANING_MACHINE`   | `light?`, `progress?`, `entrance?`, `isWorking?`                     | 状态灯、进度条、出入口、工位槽、工作状态（波浪流动）| `CleaningMachine`  |
-| `ISingleJointRobotOperating` | `SINGLE_JOINT_ROBOT` | `light?`, `x?`, `y?`, `j1?`, `currentFixture?`, `resource?`          | 双状态灯、轨道位移、关节旋转、夹具切换、双工位槽    | `SingleJointRobot` |
-| `IDoubleJointRobotOperating` | `DOUBLE_JOINT_ROBOT` | `light?`, `x?`, `y?`, `j1?`, `j2?`, `currentFixture?`, `resource?`   | 双状态灯、轨道位移、双关节旋转、夹具切换、双工位槽  | `DoubleJointRobot` |
-| `IRGVOperating`              | `RGV`                | `light?`, `x?`, `j1?`, `forkXY?`, `forkZ?`, `resource?`              | 双状态灯、轨道位移、旋转、货叉 XY/Z、双工位槽       | `Rgv`              |
-| `IRailOperating`             | `RAIL`               | `x?`, `botId?`                                                       | 拖链动画（关联 botId 的设备移动时拖链跟随）         | `Rail`             |
-| `IResourceStoreOperating`    | `RESOURCE_STORE`     | `light?`, `x?`, `resource?`, `stationColor?`                         | 状态灯、轨道位移、托盘/刀具工位槽、按工位序改背景色 | `ResourceStore`    |
-| `IPalletOperating`           | `PALLET`             | `light?`, `x?`, `y?`, `resource?`, `stationColor?`                   | 状态灯、X/Y 位移、托盘/刀具工位槽、按工位序改背景色 | `Pallet`           |
+| 类型                         | className            | 特有属性                                                              | 子组件能力                                                     | 典型 payload.type  |
+| ---------------------------- | -------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------ |
+| `IMachineToolOperating`      | `MACHINE_TOOL`       | `light?`, `progress?`, `entrance?`, `station_rotation?`, `isWorking?` | 状态灯（含旋转）、进度条、出入口、工位槽、工作状态（玻璃呼吸） | `MachineTool`      |
+| `ILoadingStationOperating`   | `LOADING_STATION`    | `light?`, `progress?`, `entrance?`                                    | 状态灯（无旋转）、进度条、出入口、工位槽                       | `LoadingStation`   |
+| `IShuttleStationOperating`   | `SHUTTLE_STATION`    | `light?`, `layerLightColor?`, `layerLightBlinking?`, `layerVisible?`  | 状态灯、多工位层状态灯/显隐                                    | `ShuttleStation`   |
+| `IMarkingMachineOperating`   | `MARKING_MACHINE`    | `light?`, `progress?`, `entrance?`, `laserSiteNumberArray?`           | 状态灯、进度条、出入口、工位槽、激光工位（电报节奏闪动）       | `MarkingMachine`   |
+| `ICleaningMachineOperating`  | `CLEANING_MACHINE`   | `light?`, `progress?`, `entrance?`, `isWorking?`                      | 状态灯、进度条、出入口、工位槽、工作状态（波浪流动）           | `CleaningMachine`  |
+| `ISingleJointRobotOperating` | `SINGLE_JOINT_ROBOT` | `light?`, `x?`, `y?`, `j1?`, `currentFixture?`, `resource?`           | 双状态灯、轨道位移、关节旋转、夹具切换、双工位槽               | `SingleJointRobot` |
+| `IDoubleJointRobotOperating` | `DOUBLE_JOINT_ROBOT` | `light?`, `x?`, `y?`, `j1?`, `j2?`, `currentFixture?`, `resource?`    | 双状态灯、轨道位移、双关节旋转、夹具切换、双工位槽             | `DoubleJointRobot` |
+| `IRGVOperating`              | `RGV`                | `light?`, `x?`, `j1?`, `forkXY?`, `forkZ?`, `resource?`               | 双状态灯、轨道位移、旋转、货叉 XY/Z、双工位槽                  | `Rgv`              |
+| `IRailOperating`             | `RAIL`               | `x?`, `botId?`                                                        | 拖链动画（关联 botId 的设备移动时拖链跟随）                    | `Rail`             |
+| `IResourceStoreOperating`    | `RESOURCE_STORE`     | `light?`, `x?`, `resource?`, `stationColor?`                          | 状态灯、轨道位移、托盘/刀具工位槽、按工位序改背景色            | `ResourceStore`    |
+| `IPalletOperating`           | `PALLET`             | `light?`, `x?`, `y?`, `resource?`, `stationColor?`                    | 状态灯、X/Y 位移、托盘/刀具工位槽、按工位序改背景色            | `Pallet`           |
 
 ### 子类型字段详情
 
 #### IMachineToolOperating
 
-| 属性               | 类型                 | 说明                                    |
-| ------------------ | -------------------- | --------------------------------------- |
-| `light`            | `ILightOperating`    | 支持 `rotating`（运行中旋转灯效）       |
-| `progress`         | `IProgressOperating` | 加工进度 0~1                            |
-| `entrance`         | `IEntranceOperating` | 物料入口/出口动画                       |
-| `stationRotatable` | `boolean`            | 工位容器方向：`false` 横向，`true` 纵向 |
+| 属性               | 类型                 | 说明                                                        |
+| ------------------ | -------------------- | ----------------------------------------------------------- |
+| `light`            | `ILightOperating`    | 支持 `rotating`（运行中旋转灯效）                           |
+| `progress`         | `IProgressOperating` | 加工进度 0\~1                                               |
+| `entrance`         | `IEntranceOperating` | 物料入口/出口动画                                           |
+| `station_rotation` | `number`             | 工位旋转增量（度）：叠加在机床配置的工位容器方向角之上      |
 | `isWorking`        | `boolean`            | 工作状态：`true` 时工位容器玻璃背景呼吸闪动（默认 `false`） |
-| `resource`         | `IResourceOperating` | 托盘等资源增删                          |
+| `resource`         | `IResourceOperating` | 托盘等资源增删                                              |
 
 #### ILoadingStationOperating
 
-| 属性               | 类型                                | 说明           |
-| ------------------ | ----------------------------------- | -------------- |
-| `light`            | `Omit<ILightOperating, 'rotating'>` | 不支持旋转灯效 |
-| `progress`         | `IProgressOperating`                | 装载进度       |
-| `entrance`         | `IEntranceOperating`                | 出入口状态     |
-| `stationRotatable` | `boolean`                           | 工位容器方向   |
-| `resource`         | `IResourceOperating`                | 工位槽资源     |
+| 属性       | 类型                                | 说明           |
+| ---------- | ----------------------------------- | -------------- |
+| `light`    | `Omit<ILightOperating, 'rotating'>` | 不支持旋转灯效 |
+| `progress` | `IProgressOperating`                | 装载进度       |
+| `entrance` | `IEntranceOperating`                | 出入口状态     |
+| `resource` | `IResourceOperating`                | 工位槽资源     |
 
 #### IShuttleStationOperating
 
@@ -541,13 +460,13 @@ type ILayerOperating =
 
 #### IMarkingMachineOperating
 
-| 属性                   | 类型                                | 说明               |
-| ---------------------- | ----------------------------------- | ------------------ |
-| `light`                | `Omit<ILightOperating, 'rotating'>` | 状态灯             |
-| `progress`             | `IProgressOperating`                | 打标进度           |
-| `entrance`             | `IEntranceOperating`                | 出入口             |
+| 属性                   | 类型                                | 说明                                                      |
+| ---------------------- | ----------------------------------- | --------------------------------------------------------- |
+| `light`                | `Omit<ILightOperating, 'rotating'>` | 状态灯                                                    |
+| `progress`             | `IProgressOperating`                | 打标进度                                                  |
+| `entrance`             | `IEntranceOperating`                | 出入口                                                    |
 | `laserSiteNumberArray` | `ILaserSiteState[]`                 | 各激光工位打标状态（`active` 时点亮并按无序电报节奏闪动） |
-| `resource`             | `IResourceOperating`                | 工位槽资源         |
+| `resource`             | `IResourceOperating`                | 工位槽资源                                                |
 
 **ILaserSiteState：**
 
@@ -558,13 +477,13 @@ type ILayerOperating =
 
 #### ICleaningMachineOperating
 
-| 属性       | 类型                                | 说明       |
-| ---------- | ----------------------------------- | ---------- |
-| `light`    | `Omit<ILightOperating, 'rotating'>` | 状态灯     |
-| `progress` | `IProgressOperating`                | 清洗进度   |
-| `entrance` | `IEntranceOperating`                | 出入口     |
+| 属性        | 类型                                | 说明                                                          |
+| ----------- | ----------------------------------- | ------------------------------------------------------------- |
+| `light`     | `Omit<ILightOperating, 'rotating'>` | 状态灯                                                        |
+| `progress`  | `IProgressOperating`                | 清洗进度                                                      |
+| `entrance`  | `IEntranceOperating`                | 出入口                                                        |
 | `isWorking` | `boolean`                           | 工作状态：`true` 时工位容器内显示波浪流动效果（默认 `false`） |
-| `resource` | `IResourceOperating`                | 工位槽资源 |
+| `resource`  | `IResourceOperating`                | 工位槽资源                                                    |
 
 #### ISingleJointRobotOperating
 
@@ -591,14 +510,14 @@ type ILayerOperating =
 
 #### IRGVOperating
 
-| 属性       | 类型                 | 说明                      |
-| ---------- | -------------------- | ------------------------- |
-| `light`    | `ILightOperating`    | 双灯同步更新              |
-| `x`        | `number`             | 沿轨道位移（像素）[0,1]   |
-| `j1`       | `number`             | 车体旋转角度（度）[0,360] |
-| `forkXY`   | `number`             | 货叉进出移动比例 [−1,1]   |
-| `forkZ`    | `number`             | 货叉升降比例 [0,1]        |
-| `resource` | `IResourceOperating` | 托盘/刀具工位槽           |
+| 属性       | 类型                 | 说明                       |
+| ---------- | -------------------- | -------------------------- |
+| `light`    | `ILightOperating`    | 双灯同步更新               |
+| `x`        | `number`             | 沿轨道位移（像素）\[0,1]   |
+| `j1`       | `number`             | 车体旋转角度（度）\[0,360] |
+| `forkXY`   | `number`             | 货叉进出移动比例 \[−1,1]   |
+| `forkZ`    | `number`             | 货叉升降比例 \[0,1]        |
+| `resource` | `IResourceOperating` | 托盘/刀具工位槽            |
 
 #### IRailOperating
 
@@ -630,12 +549,12 @@ type ILayerOperating =
 
 被 `ILayerOperating` 各字段引用的子组件操作类型，定义于 `src/types/components/operating.types.ts`：
 
-| 类型                 | 用途       | 字段                                                                                     |
-| -------------------- | ---------- | ---------------------------------------------------------------------------------------- |
-| `ILightOperating`    | 状态灯     | `color`（必填）, `blinking?`, `rotating?`                                                |
-| `IProgressOperating` | 进度条     | `percent`（0~1）, `textContent`                                                          |
-| `IEntranceOperating` | 出入口     | `isIn`, `isOut`                                                                          |
-| `IResourceOperating` | 工位槽资源 | `resourceType`, `index`, `handleType`（`'add'\|'remove'`）, `rawData`, `name?`, `color?` |
+| 类型                 | 用途       | 字段                                                                                                                                                                                |
+| -------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ILightOperating`    | 状态灯     | `color`（必填）, `blinking?`, `rotating?`                                                                                                                                           |
+| `IProgressOperating` | 进度条     | `percent`（0\~1）, `textContent`                                                                                                                                                    |
+| `IEntranceOperating` | 出入口     | `isIn`, `isOut`                                                                                                                                                                     |
+| `IResourceOperating` | 工位槽资源 | `resource_type`, `resource_id?`, `name?`, `resource_color?`（显式颜色优先，未下发时按 `resource_state` 字典映射）, `device_station`, `handle_type`（`'add'\|'remove'`）, `raw_data` |
 
 ---
 
@@ -672,10 +591,11 @@ type ILayerOperating =
 
 **EnumResourceType — 资源类型**
 
-| 枚举值   | 说明 |
-| -------- | ---- |
-| `PALLET` | 托盘 |
-| `TOOL`   | 刀具 |
+| 枚举值      | 说明 |
+| ----------- | ---- |
+| `WORKPIECE` | 工件 |
+| `TOOL`      | 刀具 |
+| `AUXILIARY` | 辅料 |
 
 #### 核心类型
 
@@ -695,7 +615,7 @@ type ILayerOperating =
 
 | 属性       | 类型       | 必填 | 说明     |
 | ---------- | ---------- | ---- | -------- |
-| `uuid`     | `string`   | ✓    | 唯一标识 |
+| `id`       | `string`   | ✓    | 唯一标识 |
 | `isActive` | `boolean`  | ✓    | 是否激活 |
 | `title`    | `string`   | ✓    | 标题     |
 | `scene`    | `IScene`   | ✓    | 场景     |
@@ -716,13 +636,14 @@ type ILayerOperating =
 
 ## 📝 注意事项
 
-1. **编辑器 vs 预览：** 编辑模式配置 `EditorActions`；预览模式配置 `PreviewActions` + `onMessage` → `operating`
-2. **ID 匹配：** `operating` 的 `id` 必须与方案图层 `rawData.id` 一致，否则静默失败（在前端层面该值即为编辑器组件中业务数据配置中必填项 id 的值，需根据后端预先提供的设备 id 在编辑器中进行配置）
-3. **坐标系：** 轨道类设备的 `x` 通常需 `transPercentToPixel` 转换；`IRailOperating.x` 直接使用像素
-4. **资源消息：** `Resource` 类型不对应独立图层，通过目标设备的 `resource` 字段操作工位槽
-5. **引擎生命周期：** 组件卸载时自动 `destroyContainer`；手动集成需自行销毁
-6. **类型安全：** 所有 API 均导出 TypeScript 类型，推荐 `import type { ILayerOperating, EnumModel } from '@jnrs/lingshu-smart'`
-7. **调试模式：** 500ms 内点击主容器（`#lingshu-smart`）10 次可打开调试配置面板，支持运行时配置日志等级、阴影/动画开关、FPS 限制、交互禁用、性能统计。配置通过 `localStorage` 持久化，详见 README「调试功能」章节。
+1. **编辑器 vs 预览：** 编辑模式配置 `EditorActions`；预览模式配置 `PreviewActions`，并通过 `feedSocketMessage` 下发标准信封协议消息（`envelope + payload`）驱动画布。画布内置 `SocketDispatcher` 自动分发，业务侧无需自行解析 `payload.type`。
+2. **设备 ID 匹配：** 协议消息中 `device_id` 必须与方案图层 `rawData.id` 一致，否则回执 `404` 且不驱动（在前端层面该值即为编辑器组件中业务数据配置中必填项 id 的值，需根据后端预先提供的设备 id 在编辑器中进行配置）
+3. **坐标系：** 协议 `position.x/y/z` 为比例值 \[0,1]，画布按场景自动换算为像素；`j1 / j2 / fork_xy / fork_z` 为角度/比例原值直接透传
+4. **资源消息：** `resource_command` 不再映射到独立图层，资源为独立实体，由画布对象资源池按 `resource_id` 管理，操作工位的纯位置槽
+5. **扩展工位（合并编号）：** 托盘图层配置 `extendHostId`（宿主设备业务 ID）后，托盘工位并入宿主设备的合并编号空间——资源寻址宿主越界时按「宿主工位总数 + 前序扩展托盘工位总数」顺延落到扩展托盘（404/409 以实际承接工位判定）；点击扩展托盘工位时 `onTap` 的 `layer` 为宿主设备、`data.index` 为合并编号（附 `extensionOf` / `localIndex` 溯源字段）。详见 socket-operating-api.md 3.6
+6. **引擎生命周期：** 组件卸载时自动 `destroyContainer`；手动集成需自行销毁
+7. **类型安全：** 所有 API 均导出 TypeScript 类型，推荐 `import type { EnvelopeType, SocketMessage, DeviceCommandPayload, ResourceCommandPayload, EnumDeviceType, EnumResourceType } from '@jnrs/lingshu-smart'`
+8. **调试模式：** 500ms 内点击主容器（`#lingshu-smart`）10 次可打开调试配置面板，支持运行时配置日志等级、阴影/动画开关、FPS 限制、交互禁用、性能统计。配置通过 `localStorage` 持久化，详见 README「调试功能」章节。
 
 ---
 
@@ -730,18 +651,19 @@ type ILayerOperating =
 
 ### 架构
 
-| 模块                                       | 职责                                                                                                                                                                                                                                                                |
-| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `utils/logger.ts`                          | 统一日志工具，支持 tag 着色、LogLevel 过滤、`operating` 追踪级别                                                                                                                                                                                                    |
-| `utils/debug-flags.ts`                     | 模块级动画标志位，供 UI 组件直接导入控制循环动画                                                                                                                                                                                                                    |
-| `utils/performance-stats.ts`               | 性能统计工具，记录运行时长和 WebSocket 数据接收量                                                                                                                                                                                                                   |
-| `stores/useDebugStore.ts`                  | 全局设置 Pinia store（facade）：响应式读写 `useDataStore.globalSetting` / `scriptRunner`，持久化统一在 `@jnrs/lingshu-smart`                                                                                                                                        |
-| `composables/useDebugEasterEgg.ts`         | 调试触发检测：500ms 内 10 次点击打开面板                                                                                                                                                                                                                            |
-| `components/debug/GlobalSetting.vue`       | 全局设置对话框 UI（原 DebugPanel，含语言/日志等级/FPS/阴影/动画等开关）                                                                                                                                                                                             |
-| `components/debug/ScriptRunner/`           | Socket 脚本模拟器：脚本步骤编排、断点调试、消息结构配置（code/msg、payload 字段名、type）、日志查看；设备下拉支持自定义/全部复位（resetAll）/资源操作                                                                                                                                                                 |
-| `components/debug/WsProxy/`                | WebSocket 代理器：声明式字段映射将后端 socket 结构桥接为 operating，支持连接/断开/重连、日志、配置导出/导入、场景像素换算（percentToPixel 百分比/ runtimeToPixel 运行时坐标）、standalone 独立标签页模式 / remote 远程接收模式（BroadcastChannel 跨标签页流转数据）；操作规则含 single/resource/global/resetAll（ResetAll 接收源类型值 `resetAll` 后生成全部复位 operating） |
-| `components/debug/WsProxy/WsProxyPage.vue` | `WsProxy` 独立路由页面组件：以独立 URL/标签页运行代理器配置，将 operating/raw/状态广播给预览页驱动图形运转                                                                                                                                                          |
-| `controller/AppController.ts`              | 提供 `toggleShadows` / `toggleAnimations` / `setFps` 方法                                                                                                                                                                                                           |
+| 模块                                       | 职责                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --- |
+| `utils/logger.ts`                          | 统一日志工具，支持 tag 着色、LogLevel 过滤、`operating` 追踪级别                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `utils/debug-flags.ts`                     | 模块级动画标志位，供 UI 组件直接导入控制循环动画                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `utils/performance-stats.ts`               | 性能统计工具，记录运行时长和 WebSocket 数据接收量                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `stores/useDebugStore.ts`                  | 全局设置 Pinia store（facade）：响应式读写 `useDataStore.globalSetting` / `scriptsConfig`（脚本按方案分组；其 `scriptSteps` / `scriptLooping` 基于「激活方案」，组件持有明确方案上下文时建议直接用 `useDataStore` 按 caseId 读写），持久化统一在 `@jnrs/lingshu-smart`                                                                                                                                                                                                                                                                                                                                                                                                         |     |
+| `composables/useDebugEasterEgg.ts`         | 调试触发检测：500ms 内 10 次点击打开面板                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `components/debug/GlobalSetting.vue`       | 全局设置对话框 UI（原 DebugPanel，含语言/日志等级/FPS/阴影/动画等开关）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `components/debug/ScriptRunner/`           | Socket 脚本模拟器：脚本步骤编排、断点调试，生成标准信封协议消息（`envelope + payload`，含 device_init / device_command / resource_command / alarm_push / scene_reset 等模板）；设备下拉支持自定义/全部复位（resetAll）/资源操作，产物经 `feedSocketMessage` 直接驱动画布；脚本**按方案分组**存储（`ScriptCaseData[]`：caseId / caseName / steps / looping，与 `wsProxyConfig` 对称，经 `currentCase` prop 确定归属）；支持**一键烧录**（二次确认后写入 `public/lingshu-smart/mockSocket.json`，开发服务器接口 `POST /lingshu-smart/__burn-mock-socket`，宿主无需改动）与**导入/导出** JSON 文件；弹窗打开时按「文件优先 + 未烧录改动确认」懒加载当前方案（见 `scriptFile.ts`） |
+| `components/debug/WsProxy/`                | WebSocket 代理器：声明式字段映射将后端 socket 结构桥接为标准信封协议消息（`envelope + payload`，snake_case）并经 `feedSocketMessage` 驱动画布，标准信封消息直接透传；支持连接/断开/重连（指数退避）、心跳 ping/pong、日志、配置导出/导入、场景像素换算（percentToPixel 百分比/ runtimeToPixel 运行时坐标）、standalone 独立标签页模式 / remote 远程接收模式（BroadcastChannel 跨标签页流转数据）；操作规则含 single/resource/global/resetAll（ResetAll 接收源类型值 `resetAll` 后生成全部复位）                                                                                                                                                                                |
+| `components/debug/WsProxy/WsProxyPage.vue` | `WsProxy` 独立路由页面组件：以独立 URL/标签页运行代理器配置，将标准协议消息/状态广播给预览页驱动图形运转                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `controller/SocketDispatcher.ts`           | Socket 协议分发器：解析 `envelope + payload`，识别心跳、按 `envelope.id` 去重、按类型分发（device_init / device_command / resource_command / alarm_push / runtime_status_push / scene_reset），对象资源池管理资源生命周期，处理完毕回执 `command_ack`（0/400/404/409/500）                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `controller/AppController.ts`              | 画布控制器：提供 `toggleShadows` / `toggleAnimations` / `setFps` / `resetAllModels` / `setAlarmHighlight` 等方法                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 ### 日志系统
 
@@ -755,9 +677,13 @@ logger.warn('警告') // [WARN:MyModule] 警告（浏览器默认样式）
 ```
 
 - `log`/`info`/`operating` 级别：使用彩色单徽章（`LEVEL:Tag` 合并显示）
+
 - `warn`/`error` 级别：纯文本前缀 `[LEVEL:Tag]`
+
 - `operating` 级别：用于追踪 UI 模型操作指令，在 `ModelAbs.handleOperation` 和 `ComponentAbs.handleOperation` 中自动埋点
+
 - 日志等级优先级：`none` < `error` < `warn` < `info` < `log` < `operating`
+
 - 默认：开发环境 `log`（全开），生产环境 `warn`
 
 ### 调试配置项
@@ -772,18 +698,25 @@ logger.warn('警告') // [WARN:MyModule] 警告（浏览器默认样式）
 | 性能统计     | —                      | `trackWebSocketMessage()` |
 
 - **动画开关**：通过标志位控制循环动画（灯闪烁、入口通道动画等），关闭后保留静态状态（如灯颜色保持不变），不影响一次性动画（如机器人摆臂、进度条动画）
+
 - **阴影开关**：递归遍历所有元素切换 `shadow`/`innerShadow` 的 `visible` 属性，同时处理 `ShadowCanvas` 元素（`createShadow` 工厂创建的 Canvas 阴影）的 `visible` 属性
 
 ### localStorage 存储
 
 统一 key 为 `lingshu-smart`，debug 配置存储在 `debug` 子对象中，与 `useDataStore` 的持久化数据共享同一 key。
 
+脚本数据存于该 key 的 `scriptsConfig` 字段（**按方案分组**的 `ScriptCaseData[]`，与 `wsProxyConfig` 平级）；旧版全局字段 `scriptRunner` / `scriptLooping` 在读取时自动归入当前激活方案（无 `isActive` 标记时兜底取第一个方案），随后删除。
+
+另有独立小 key `@jnrs/lingshu-smart/mock-socket-baseline`：记录**各方案**脚本与 `mockSocket.json` 的「已同步基线」hash，值为 `{ [caseId]: hash }`（`scriptFile.ts` 的 `readBaselineHash` / `writeBaselineHash`），用于检出该方案未烧录的脚本改动——仅在文件加载 / 烧录 / 导入成功后更新，用户手动编辑不更新。
+
 ---
 
 ## 🛠 技术栈
 
 - Vue 3 + TypeScript + Pinia
+
 - LeaferJS 2D 图形引擎
+
 - Element Plus UI
 
 ---