agentworkshop 0.5.9 → 0.6.1

package/server/services/workshop/daq/daq-node.ts

@@ -1,247 +1,257 @@
-/**
- * DaqNode —— 数据采集节点领域对象(class 封装)。
- *
- * 一个实例 = 一条物理采集通道:模板域(量程/单位/精度)+ 运行配置(驱动/周期/启停)
- * + 绑定关系(deviceBindingId → DeviceTwin)+ 实时状态(value/state/lastAt)。
- * 序列化经 toRow/fromRow 与持久化仓库对接(daqs.json,对象快照落盘);
- * 采样历史仅驻内存(环形缓冲),不进磁盘快照 —— 磁盘只存"配置 + 最近一次读数"。
- */
-
-import { daqKeyFromRef, type DaqDriverKind, type DaqNodeState, type DaqNodeView, type DataTransform } from '../../../../shared/daq-protocol'
-import { findDaqTemplate } from './daq-templates'
-
-/** 采样历史环形缓冲长度(前端趋势图/火花线消费;1s 周期 ≈ 5 分钟窗口) */
-export const DAQ_HIST_CAP = 60
-
-interface DaqNodeOptions {
-  id: string
-  templateRef: string
-  name?: string
-  driver?: DaqDriverKind
-  enabled?: boolean
-  intervalMs?: number | null
-  /** WS 实时下发间隔(null=跟随全局;0=每帧) */
-  publishIntervalMs?: number | null
-  unit?: string
-  decimals?: number
-  min?: number
-  max?: number
-  warnLow?: number | null
-  warnHigh?: number | null
-  deviceBindingId?: string | null
-  /** 数据语义标定钩子(decoder:采集值 → 物理值) */
-  transform?: DataTransform
-  posX?: number
-  posZ?: number
-  /** 所属产线('' = 未分配;采集门控/场景光晕按产线隔离) */
-  lineId?: string
-  /** 节点级采集语义备注(覆盖模板 semantics;注入 Agent 上下文) */
-  semantics?: string
-  /** 驱动连接参数(modbus-tcp/opcua 协议参数;mock 空) */
-  driverConfig?: Record<string, string | number | boolean>
-  createdAt?: string
-}
-
-export class DaqNode {
-  readonly id: string
-  /** 模板引用(daq-<key> 形态;域缺省来源) */
-  templateRef: string
-  name: string
-  driver: DaqDriverKind
-  enabled: boolean
-  /** null = 跟随 controller 全局周期 */
-  intervalMs: number | null
-  /** WS 实时下发(消费)间隔;null = 跟随全局,0 = 每帧(随采样节拍) */
-  publishIntervalMs: number | null
-  unit: string
-  decimals: number
-  min: number
-  max: number
-  warnLow: number | null
-  warnHigh: number | null
-  deviceBindingId: string | null
-  driverConfig: Record<string, string | number | boolean>
-  transform?: DataTransform
-  posX?: number
-  posZ?: number
-  /** 所属产线('' = 未分配;采集门控/场景光晕按产线隔离) */
-  lineId = ''
-  /** 节点级采集语义备注(覆盖模板 semantics) */
-  semantics?: string
-  value: number | null
-  state: DaqNodeState = 'offline'
-  lastAt: string | null = null
-  /** 去抖候选态(连续 3 帧一致才切换;alarm/offline 立即生效,安全优先) */
-  private stateCand: DaqNodeState | null = null
-  private stateCandN = 0
-  readonly createdAt: string
-
-  constructor(o: DaqNodeOptions) {
-    const tpl = findDaqTemplate(daqKeyFromRef(o.templateRef))
-    this.id = o.id
-    this.templateRef = o.templateRef
-    this.name = o.name ?? (tpl ? `${tpl.name}` : '数采节点')
-    this.driver = o.driver ?? 'mock'
-    this.enabled = o.enabled ?? true
-    this.intervalMs = o.intervalMs ?? null
-    this.publishIntervalMs = o.publishIntervalMs ?? null
-    this.unit = o.unit ?? tpl?.unit ?? ''
-    this.decimals = o.decimals ?? tpl?.decimals ?? 2
-    this.min = o.min ?? tpl?.min ?? 0
-    this.max = o.max ?? tpl?.max ?? 100
-    // 预警带缺省 = 量程两端各收 8%(越带即 warn,越硬限即 alarm)
-    this.warnLow = o.warnLow !== undefined ? o.warnLow : this.min !== undefined && tpl ? +(this.min + (this.max - this.min) * 0.08).toFixed(this.decimals) : null
-    this.warnHigh = o.warnHigh !== undefined ? o.warnHigh : tpl ? +(this.max - (this.max - this.min) * 0.08).toFixed(this.decimals) : null
-    this.deviceBindingId = o.deviceBindingId ?? null
-    this.driverConfig = o.driverConfig ?? {}
-    if (o.transform) this.transform = o.transform
-    if (o.posX !== undefined) this.posX = o.posX
-    if (o.posZ !== undefined) this.posZ = o.posZ
-    this.lineId = o.lineId ?? ''
-    this.semantics = o.semantics
-    this.value = null
-    this.createdAt = o.createdAt ?? new Date().toISOString()
-  }
-
-  /** 模板 key(`daq-<key>` 中提取;未知模板返回原 ref) */
-  get templateKey(): string {
-    return daqKeyFromRef(this.templateRef)
-  }
-
-  /** 有效采样周期(ms):节点覆盖 > 全局缺省 */
-  effectiveInterval(defaultIntervalMs: number): number {
-    return Math.max(120, this.intervalMs ?? defaultIntervalMs)
-  }
-
-  /** 越限派生:硬限外 = alarm;预警带 2% 滞回(退出需越过内缩边界,防临界抖动)。
-   *  注意:滞回依赖当前 state,故仅在 applyReading 的稳态链路中语义正确。 */
-  deriveState(v: number): DaqNodeState {
-    if (!this.enabled) return 'offline'
-    if (v < this.min || v > this.max) return 'alarm'
-    const margin = (this.max - this.min) * 0.02
-    if (this.state === 'warn') {
-      // 已在预警:回到"内缩边界内"才算恢复
-      if (this.warnLow != null && v < this.warnLow + margin) return 'warn'
-      if (this.warnHigh != null && v > this.warnHigh - margin) return 'warn'
-      return 'ok'
-    }
-    if ((this.warnLow != null && v < this.warnLow) || (this.warnHigh != null && v > this.warnHigh)) return 'warn'
-    return 'ok'
-  }
-
-  /** 记录一次采样(controller 采样循环调用):去抖 + 滞回后落状态 */
-  applyReading(v: number, at: string): void {
-    this.value = v
-    const raw = this.deriveState(v)
-    // alarm/offline 立即切换(安全事件不等去抖);ok↔warn 需连续 3 帧一致
-    if (raw === 'alarm' || raw === 'offline' || raw === this.state) {
-      this.state = raw
-      this.stateCand = null
-      this.stateCandN = 0
-    }
-    else if (raw === this.stateCand) {
-      if (++this.stateCandN >= 3) {
-        this.state = raw
-        this.stateCand = null
-        this.stateCandN = 0
-      }
-    }
-    else {
-      this.stateCand = raw
-      this.stateCandN = 1
-    }
-    this.lastAt = at
-  }
-
-  /** 对象快照(磁盘形态:配置 + 最近读数;无运行时缓冲) */
-  toRow(): Record<string, unknown> {
-    return {
-      id: this.id,
-      templateRef: this.templateRef,
-      name: this.name,
-      driver: this.driver,
-      enabled: this.enabled,
-      intervalMs: this.intervalMs,
-      publishIntervalMs: this.publishIntervalMs,
-      unit: this.unit,
-      decimals: this.decimals,
-      min: this.min,
-      max: this.max,
-      warnLow: this.warnLow,
-      warnHigh: this.warnHigh,
-      deviceBindingId: this.deviceBindingId,
-      driverConfig: this.driverConfig,
-      transform: this.transform,
-      posX: this.posX,
-      posZ: this.posZ,
-      lineId: this.lineId,
-      semantics: this.semantics,
-      value: this.value,
-      state: this.state,
-      lastAt: this.lastAt,
-      createdAt: this.createdAt,
-    }
-  }
-
-  static fromRow(row: Record<string, unknown>): DaqNode {
-    const node = new DaqNode({
-      id: String(row.id),
-      templateRef: String(row.templateRef ?? ''),
-      name: row.name != null ? String(row.name) : undefined,
-      driver: (row.driver as DaqDriverKind) ?? undefined,
-      enabled: row.enabled === undefined ? undefined : Boolean(row.enabled),
-      intervalMs: row.intervalMs == null ? null : Number(row.intervalMs),
-      publishIntervalMs: row.publishIntervalMs == null ? null : Number(row.publishIntervalMs),
-      unit: row.unit != null ? String(row.unit) : undefined,
-      decimals: row.decimals != null ? Number(row.decimals) : undefined,
-      min: row.min != null ? Number(row.min) : undefined,
-      max: row.max != null ? Number(row.max) : undefined,
-      warnLow: row.warnLow === undefined ? undefined : (row.warnLow == null ? null : Number(row.warnLow)),
-      warnHigh: row.warnHigh === undefined ? undefined : (row.warnHigh == null ? null : Number(row.warnHigh)),
-      deviceBindingId: row.deviceBindingId === undefined ? undefined : (row.deviceBindingId == null ? null : String(row.deviceBindingId)),
-      driverConfig: (row.driverConfig as Record<string, string | number | boolean>) ?? {},
-      transform: (row.transform as DataTransform | undefined) ?? undefined,
-      posX: row.posX == null ? undefined : Number(row.posX),
-      posZ: row.posZ == null ? undefined : Number(row.posZ),
-      lineId: row.lineId == null ? '' : String(row.lineId),
-      semantics: row.semantics == null ? undefined : String(row.semantics),
-      createdAt: row.createdAt != null ? String(row.createdAt) : undefined,
-    })
-    if (row.value != null && !Number.isNaN(Number(row.value))) {
-      node.value = Number(row.value)
-      node.state = node.deriveState(node.value)
-    }
-    if (row.lastAt != null) node.lastAt = String(row.lastAt)
-    return node
-  }
-
-  /** AEP/REST 投影(view 同构载荷) */
-  toView(): DaqNodeView {
-    return {
-      id: this.id,
-      templateRef: this.templateRef,
-      name: this.name,
-      driver: this.driver,
-      enabled: this.enabled,
-      intervalMs: this.intervalMs,
-      publishIntervalMs: this.publishIntervalMs,
-      unit: this.unit,
-      decimals: this.decimals,
-      min: this.min,
-      max: this.max,
-      warnLow: this.warnLow,
-      warnHigh: this.warnHigh,
-      deviceBindingId: this.deviceBindingId,
-      driverConfig: this.driverConfig,
-      transform: this.transform,
-      posX: this.posX,
-      posZ: this.posZ,
-      lineId: this.lineId,
-      semantics: this.semantics,
-      value: this.value,
-      state: this.state,
-      lastAt: this.lastAt,
-      createdAt: this.createdAt,
-    }
-  }
-}
+/**
+ * DaqNode —— 数据采集节点领域对象(class 封装)。
+ *
+ * 一个实例 = 一条物理采集通道:模板域(量程/单位/精度)+ 运行配置(驱动/周期/启停)
+ * + 绑定关系(deviceBindingId → DeviceTwin)+ 实时状态(value/state/lastAt)。
+ * 序列化经 toRow/fromRow 与持久化仓库对接(daqs.json,对象快照落盘);
+ * 采样历史仅驻内存(环形缓冲),不进磁盘快照 —— 磁盘只存"配置 + 最近一次读数"。
+ */
+
+import { daqKeyFromRef, type DaqDriverKind, type DaqNodeState, type DaqNodeView, type DataTransform } from '../../../../shared/daq-protocol'
+import { findDaqTemplate } from './daq-templates'
+
+/** 采样历史环形缓冲长度(前端趋势图/火花线消费;1s 周期 ≈ 5 分钟窗口) */
+export const DAQ_HIST_CAP = 60
+
+interface DaqNodeOptions {
+  id: string
+  templateRef: string
+  name?: string
+  driver?: DaqDriverKind
+  enabled?: boolean
+  intervalMs?: number | null
+  /** WS 实时下发间隔(null=跟随全局;0=每帧) */
+  publishIntervalMs?: number | null
+  unit?: string
+  decimals?: number
+  min?: number
+  max?: number
+  warnLow?: number | null
+  warnHigh?: number | null
+  deviceBindingId?: string | null
+  /** 数据语义标定钩子(decoder:采集值 → 物理值) */
+  transform?: DataTransform
+  posX?: number
+  posZ?: number
+  /** 所属产线('' = 未分配;采集门控/场景光晕按产线隔离) */
+  lineId?: string
+  /** 节点级采集语义备注(覆盖模板 semantics;注入 Agent 上下文) */
+  semantics?: string
+  /** 驱动连接参数(modbus-tcp/opcua 协议参数;mock 空) */
+  driverConfig?: Record<string, string | number | boolean>
+  createdAt?: string
+}
+
+export class DaqNode {
+  readonly id: string
+  /** 模板引用(daq-<key> 形态;域缺省来源) */
+  templateRef: string
+  name: string
+  driver: DaqDriverKind
+  enabled: boolean
+  /** null = 跟随 controller 全局周期 */
+  intervalMs: number | null
+  /** WS 实时下发(消费)间隔;null = 跟随全局,0 = 每帧(随采样节拍) */
+  publishIntervalMs: number | null
+  unit: string
+  decimals: number
+  min: number
+  max: number
+  warnLow: number | null
+  warnHigh: number | null
+  deviceBindingId: string | null
+  driverConfig: Record<string, string | number | boolean>
+  transform?: DataTransform
+  posX?: number
+  posZ?: number
+  /** 所属产线('' = 未分配;采集门控/场景光晕按产线隔离) */
+  lineId = ''
+  /** 节点级采集语义备注(覆盖模板 semantics) */
+  semantics?: string
+  value: number | null
+  state: DaqNodeState = 'offline'
+  lastAt: string | null = null
+  /** 去抖候选态(连续 3 帧一致才切换;alarm/offline 立即生效,安全优先) */
+  private stateCand: DaqNodeState | null = null
+  private stateCandN = 0
+  readonly createdAt: string
+
+  constructor(o: DaqNodeOptions) {
+    const tpl = findDaqTemplate(daqKeyFromRef(o.templateRef))
+    this.id = o.id
+    this.templateRef = o.templateRef
+    this.name = o.name ?? (tpl ? `${tpl.name}` : '数采节点')
+    this.driver = o.driver ?? 'mock'
+    this.enabled = o.enabled ?? true
+    this.intervalMs = o.intervalMs ?? null
+    this.publishIntervalMs = o.publishIntervalMs ?? null
+    this.unit = o.unit ?? tpl?.unit ?? ''
+    this.decimals = o.decimals ?? tpl?.decimals ?? 2
+    this.min = o.min ?? tpl?.min ?? 0
+    this.max = o.max ?? tpl?.max ?? 100
+    // 预警带缺省 = 量程两端各收 8%(越带即 warn,越硬限即 alarm)
+    this.warnLow = o.warnLow !== undefined ? o.warnLow : this.min !== undefined && tpl ? +(this.min + (this.max - this.min) * 0.08).toFixed(this.decimals) : null
+    this.warnHigh = o.warnHigh !== undefined ? o.warnHigh : tpl ? +(this.max - (this.max - this.min) * 0.08).toFixed(this.decimals) : null
+    this.deviceBindingId = o.deviceBindingId ?? null
+    this.driverConfig = o.driverConfig ?? {}
+    if (o.transform) this.transform = o.transform
+    if (o.posX !== undefined) this.posX = o.posX
+    if (o.posZ !== undefined) this.posZ = o.posZ
+    this.lineId = o.lineId ?? ''
+    this.semantics = o.semantics
+    this.value = null
+    this.createdAt = o.createdAt ?? new Date().toISOString()
+  }
+
+  /** 模板 key(`daq-<key>` 中提取;未知模板返回原 ref) */
+  get templateKey(): string {
+    return daqKeyFromRef(this.templateRef)
+  }
+
+  /** 有效采样周期(ms):节点覆盖 > 全局缺省 */
+  effectiveInterval(defaultIntervalMs: number): number {
+    return Math.max(120, this.intervalMs ?? defaultIntervalMs)
+  }
+
+  /** 越限派生:硬限外 = alarm;预警带 2% 滞回(退出需越过内缩边界,防临界抖动)。
+   *  注意:滞回依赖当前 state,故仅在 applyReading 的稳态链路中语义正确。 */
+  deriveState(v: number): DaqNodeState {
+    if (!this.enabled) return 'offline'
+    if (v < this.min || v > this.max) return 'alarm'
+    const margin = (this.max - this.min) * 0.02
+    if (this.state === 'warn') {
+      // 已在预警:回到"内缩边界内"才算恢复
+      if (this.warnLow != null && v < this.warnLow + margin) return 'warn'
+      if (this.warnHigh != null && v > this.warnHigh - margin) return 'warn'
+      return 'ok'
+    }
+    if ((this.warnLow != null && v < this.warnLow) || (this.warnHigh != null && v > this.warnHigh)) return 'warn'
+    return 'ok'
+  }
+
+  /** 记录一次采样(controller 采样循环调用):去抖 + 滞回后落状态 */
+  applyReading(v: number, at: string): void {
+    this.value = v
+    const raw = this.deriveState(v)
+    // alarm/offline 立即切换(安全事件不等去抖);ok↔warn 需连续 3 帧一致
+    if (raw === 'alarm' || raw === 'offline' || raw === this.state) {
+      this.state = raw
+      this.stateCand = null
+      this.stateCandN = 0
+    }
+    else if (raw === this.stateCand) {
+      if (++this.stateCandN >= 3) {
+        this.state = raw
+        this.stateCand = null
+        this.stateCandN = 0
+      }
+    }
+    else {
+      this.stateCand = raw
+      this.stateCandN = 1
+    }
+    this.lastAt = at
+  }
+
+  /**
+   * 帧触活(v2 多形态信号):只更新展示值(avg 派生指标)与活跃时点,
+   * 不做标量量程状态派生(向量/图像无单点越限语义;帧告警由模板
+   * metrics 规则在网关侧边沿判定)。告警态由网关显式置位/恢复。
+   */
+  touchReading(displayValue: number, at: string): void {
+    this.value = Number.isFinite(displayValue) ? displayValue : null
+    this.lastAt = at
+  }
+
+  /** 对象快照(磁盘形态:配置 + 最近读数;无运行时缓冲) */
+  toRow(): Record<string, unknown> {
+    return {
+      id: this.id,
+      templateRef: this.templateRef,
+      name: this.name,
+      driver: this.driver,
+      enabled: this.enabled,
+      intervalMs: this.intervalMs,
+      publishIntervalMs: this.publishIntervalMs,
+      unit: this.unit,
+      decimals: this.decimals,
+      min: this.min,
+      max: this.max,
+      warnLow: this.warnLow,
+      warnHigh: this.warnHigh,
+      deviceBindingId: this.deviceBindingId,
+      driverConfig: this.driverConfig,
+      transform: this.transform,
+      posX: this.posX,
+      posZ: this.posZ,
+      lineId: this.lineId,
+      semantics: this.semantics,
+      value: this.value,
+      state: this.state,
+      lastAt: this.lastAt,
+      createdAt: this.createdAt,
+    }
+  }
+
+  static fromRow(row: Record<string, unknown>): DaqNode {
+    const node = new DaqNode({
+      id: String(row.id),
+      templateRef: String(row.templateRef ?? ''),
+      name: row.name != null ? String(row.name) : undefined,
+      driver: (row.driver as DaqDriverKind) ?? undefined,
+      enabled: row.enabled === undefined ? undefined : Boolean(row.enabled),
+      intervalMs: row.intervalMs == null ? null : Number(row.intervalMs),
+      publishIntervalMs: row.publishIntervalMs == null ? null : Number(row.publishIntervalMs),
+      unit: row.unit != null ? String(row.unit) : undefined,
+      decimals: row.decimals != null ? Number(row.decimals) : undefined,
+      min: row.min != null ? Number(row.min) : undefined,
+      max: row.max != null ? Number(row.max) : undefined,
+      warnLow: row.warnLow === undefined ? undefined : (row.warnLow == null ? null : Number(row.warnLow)),
+      warnHigh: row.warnHigh === undefined ? undefined : (row.warnHigh == null ? null : Number(row.warnHigh)),
+      deviceBindingId: row.deviceBindingId === undefined ? undefined : (row.deviceBindingId == null ? null : String(row.deviceBindingId)),
+      driverConfig: (row.driverConfig as Record<string, string | number | boolean>) ?? {},
+      transform: (row.transform as DataTransform | undefined) ?? undefined,
+      posX: row.posX == null ? undefined : Number(row.posX),
+      posZ: row.posZ == null ? undefined : Number(row.posZ),
+      lineId: row.lineId == null ? '' : String(row.lineId),
+      semantics: row.semantics == null ? undefined : String(row.semantics),
+      createdAt: row.createdAt != null ? String(row.createdAt) : undefined,
+    })
+    if (row.value != null && !Number.isNaN(Number(row.value))) {
+      node.value = Number(row.value)
+      node.state = node.deriveState(node.value)
+    }
+    if (row.lastAt != null) node.lastAt = String(row.lastAt)
+    return node
+  }
+
+  /** AEP/REST 投影(view 同构载荷) */
+  toView(): DaqNodeView {
+    return {
+      id: this.id,
+      templateRef: this.templateRef,
+      name: this.name,
+      driver: this.driver,
+      enabled: this.enabled,
+      intervalMs: this.intervalMs,
+      publishIntervalMs: this.publishIntervalMs,
+      unit: this.unit,
+      decimals: this.decimals,
+      min: this.min,
+      max: this.max,
+      warnLow: this.warnLow,
+      warnHigh: this.warnHigh,
+      deviceBindingId: this.deviceBindingId,
+      driverConfig: this.driverConfig,
+      transform: this.transform,
+      posX: this.posX,
+      posZ: this.posZ,
+      lineId: this.lineId,
+      semantics: this.semantics,
+      value: this.value,
+      state: this.state,
+      lastAt: this.lastAt,
+      createdAt: this.createdAt,
+    }
+  }
+}

package/server/services/workshop/daq/daq-runtime.ts

@@ -11,7 +11,7 @@
 
 import { applyTransform } from '../../../../shared/daq-protocol'
 import type { DaqNode } from './daq-node'
-import type { DaqSampleEnvelope } from './bus/queue-port'
+import type { DaqFrameSample, DaqSampleEnvelope } from './bus/queue-port'
 
 /** 驱动故障广播节流(ms;每运行时独立计时) */
 const ERR_THROTTLE_MS = 30_000
@@ -23,8 +23,9 @@ export const PUBLISH_INTERVAL_MAX = 60_000
 export interface DaqRuntimeHost {
   /** 网关全局缺省(节点元数据为 null 时回退) */
   defaults(): { intervalMs: number, publishIntervalMs: number }
-  /** 生产面:驱动采样一次(网关实现协议解析与模板域) */
-  sample(node: DaqNode, now: number): Promise<number | null>
+  /** 生产面:驱动采样一次(网关实现协议解析与模板域;多形态模板返回帧信封 ——
+   *  驱动原生形态或 controller 生产侧处理形态[图像已落对象存储]) */
+  sample(node: DaqNode, now: number): Promise<number | DaqFrameSample | { frame: NonNullable<DaqSampleEnvelope['frame']> } | null> | number | DaqFrameSample | { frame: NonNullable<DaqSampleEnvelope['frame']> } | null
   /** 生产面:样本帧入队 */
   publishSample(env: DaqSampleEnvelope): void
   /**
@@ -85,7 +86,7 @@ export class DaqNodeRuntime {
     if (now < this.lastSampleAt + node.effectiveInterval(this.host.defaults().intervalMs)) return
     this.sampling = true
     try {
-      let v: number | null = null
+      let v: number | DaqFrameSample | null = null
       try {
         v = await this.host.sample(node, now)
       }
@@ -93,6 +94,23 @@ export class DaqNodeRuntime {
         // 采样完成时刻入账:采样耗时计入周期,慢驱动自然降频
         this.lastSampleAt = Date.now()
       }
+      // 多形态帧(v2):驱动已产出帧信封(vector 点列 / image 已落对象存储的引用);
+      // 值语义 = avg 派生指标(无则 0),状态由网关按指标阈值告警链路派生
+      if (v != null && typeof v === 'object' && 'frame' in v) {
+        const f = v.frame
+        const metrics = f.metrics ?? {}
+        this.host.publishSample({
+          nodeId: node.id,
+          templateRef: node.templateRef,
+          value: Number((metrics.avg ?? 0).toFixed(node.decimals)),
+          state: 'ok',
+          at: new Date(now).toISOString(),
+          frame: f.kind === 'vector'
+            ? { kind: 'vector', points: (f.points ?? []).slice(0, 4096), metrics }
+            : { kind: 'image', objectKey: f.objectKey, thumbKey: f.thumbKey, mime: f.mime, width: f.width, height: f.height, metrics },
+        })
+        return
+      }
       if (v == null || Number.isNaN(v)) return
       // 数据语义标定钩子(decoder):PLC 采集值 → 真实物理参数。
       // 状态派生/入库/WS 下发全部使用物理值(节点元数据 transform 驱动)。
@@ -129,6 +147,20 @@ export class DaqNodeRuntime {
     if (tsMs && tsMs <= this.lastIngestAt) return 'late'
     this.lastIngestAt = tsMs
 
+    // 多形态帧(v2):不走标量量程状态派生(向量/图像无单点值语义);
+    // 指标阈值告警在网关 ingestFrame 按模板 metrics 规则边沿判定,这里只做
+    // 节点活跃度/展示值更新 + WS 下发节拍门控。
+    if (env.frame) {
+      node.state = 'ok'
+      node.touchReading(env.value, env.at)
+      const pubMs = Math.max(0, Math.min(PUBLISH_INTERVAL_MAX, node.publishIntervalMs ?? this.host.defaults().publishIntervalMs))
+      const now = Date.now()
+      const allowPublish = pubMs <= 0 || now - this.lastPublishAt >= pubMs
+      if (allowPublish) this.lastPublishAt = now
+      this.host.ingest(node, env, allowPublish)
+      return 'ok'
+    }
+
     // S5:alarm 进入/恢复沿(边沿触发,非每帧;恢复不自动 ack,仍待人工确认)
     // 配方监控窗口(活动批次)在派生后叠加:越窗视同 alarm,沿语义与量程告警一致
     const prevState = node.state