agentworkshop 0.6.1 → 0.7.0

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

@@ -1,200 +1,233 @@
-/**
- * DcwNode —— 数据写控制节点领域对象(与 DaqNode 对称)。
- *
- * 一个实例 = 一条工艺参数写通道:模板域(物理含义/单位/工艺安全量程)+ 驱动配置
- * (连接 + 工程量→原始值线性换算,系统封装)+ 绑定关系 + 写状态(value/lastAckAt/
- * writeState)。用户只操作工程量;PLC 原始值的换算/回读校验由运行时完成。
- * 序列化经 toRow/fromRow 对接持久化仓库(dcws.json)。
- */
-
-import { dcwKeyFromRef, type DcwDriverKind, type DcwNodeState, type DcwNodeView, type DataTransform } from '../../../../shared/dcw-protocol'
-import { findDcwTemplate } from './dcw-templates'
-
-interface DcwNodeOptions {
-  id: string
-  templateRef: string
-  name?: string
-  driver?: DcwDriverKind
-  enabled?: boolean
-  /** 保写周期 ms(心跳重下发;null = 仅手动下发) */
-  holdIntervalMs?: number | null
-  unit?: string
-  decimals?: number
-  min?: number
-  max?: number
-  deviceBindingId?: string | null
-  driverConfig?: Record<string, string | number | boolean>
-  /** 数据语义标定钩子(encode:物理值 → PLC 设定值;回读经 decoder 校验) */
-  transform?: DataTransform
-  posX?: number
-  posZ?: number
-  /** 所属产线('' = 未分配) */
-  lineId?: string
-  /** 节点级工艺语义备注(覆盖模板 semantics;注入 Agent 上下文) */
-  semantics?: string
-  createdAt?: string
-}
-
-export class DcwNode {
-  readonly id: string
-  templateRef: string
-  name: string
-  driver: DcwDriverKind
-  enabled: boolean
-  holdIntervalMs: number | null
-  unit: string
-  decimals: number
-  min: number
-  max: number
-  deviceBindingId: string | null
-  driverConfig: Record<string, string | number | boolean>
-  transform?: DataTransform
-  posX?: number
-  posZ?: number
-  /** 当前设定值(工程量;null = 从未下发) */
-  value: number | null = null
-  lastAckAt: string | null = null
-  lastWriteAt: string | null = null
-  state: DcwNodeState = 'idle'
-  /** 所属产线('' = 未分配;采集门控/写联锁/场景光晕按产线隔离) */
-  lineId = ''
-  /** 节点级工艺语义备注(覆盖模板 semantics) */
-  semantics?: string
-  lastError: string | null = null
-  readonly createdAt: string
-
-  constructor(o: DcwNodeOptions) {
-    const tpl = findDcwTemplate(dcwKeyFromRef(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.holdIntervalMs = o.holdIntervalMs ?? 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
-    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.createdAt = o.createdAt ?? new Date().toISOString()
-  }
-
-  get templateKey(): string {
-    return dcwKeyFromRef(this.templateRef)
-  }
-
-  /** 写入值工艺安全校验(越界即拒绝;返回错误消息或 null) */
-  validateEng(v: number): string | null {
-    if (!Number.isFinite(v)) return '设定值需为数字'
-    if (v < this.min || v > this.max) {
-      return `设定值 ${v}${this.unit} 越出工艺安全量程 [${this.min}, ${this.max}] ${this.unit}`
-    }
-    return null
-  }
-
-  /** 记录一次写 ACK(成功)/失败 */
-  applyWriteResult(eng: number, ok: boolean, message: string, at: string): void {
-    this.value = Number(eng.toFixed(this.decimals))
-    this.lastWriteAt = at
-    if (ok) {
-      this.lastAckAt = at
-      this.state = 'ok'
-      this.lastError = null
-    }
-    else {
-      this.state = 'error'
-      this.lastError = message
-    }
-  }
-
-  toRow(): Record<string, unknown> {
-    return {
-      id: this.id,
-      templateRef: this.templateRef,
-      name: this.name,
-      driver: this.driver,
-      enabled: this.enabled,
-      holdIntervalMs: this.holdIntervalMs,
-      unit: this.unit,
-      decimals: this.decimals,
-      min: this.min,
-      max: this.max,
-      deviceBindingId: this.deviceBindingId,
-      driverConfig: this.driverConfig,
-      transform: this.transform,
-      posX: this.posX,
-      posZ: this.posZ,
-      lineId: this.lineId,
-      semantics: this.semantics,
-      value: this.value,
-      lastAckAt: this.lastAckAt,
-      lastWriteAt: this.lastWriteAt,
-      state: this.state,
-      lastError: this.lastError,
-      createdAt: this.createdAt,
-    }
-  }
-
-  static fromRow(row: Record<string, unknown>): DcwNode {
-    const node = new DcwNode({
-      id: String(row.id),
-      templateRef: String(row.templateRef ?? ''),
-      name: row.name != null ? String(row.name) : undefined,
-      driver: (row.driver as DcwDriverKind) ?? undefined,
-      enabled: row.enabled === undefined ? undefined : Boolean(row.enabled),
-      holdIntervalMs: row.holdIntervalMs == null ? null : Number(row.holdIntervalMs),
-      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,
-      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),
-      lineId: row.lineId == null ? '' : String(row.lineId),
-      semantics: row.semantics == null ? undefined : String(row.semantics),
-      posZ: row.posZ == null ? undefined : Number(row.posZ),
-      createdAt: row.createdAt != null ? String(row.createdAt) : undefined,
-    })
-    if (row.value != null && !Number.isNaN(Number(row.value))) node.value = Number(row.value)
-    if (row.lastAckAt != null) node.lastAckAt = String(row.lastAckAt)
-    if (row.lastWriteAt != null) node.lastWriteAt = String(row.lastWriteAt)
-    if (row.state != null) node.state = String(row.state) as DcwNodeState
-    if (row.lastError != null) node.lastError = String(row.lastError)
-    return node
-  }
-
-  toView(): DcwNodeView {
-    return {
-      id: this.id,
-      templateRef: this.templateRef,
-      name: this.name,
-      driver: this.driver,
-      enabled: this.enabled,
-      holdIntervalMs: this.holdIntervalMs,
-      unit: this.unit,
-      decimals: this.decimals,
-      min: this.min,
-      max: this.max,
-      deviceBindingId: this.deviceBindingId,
-      driverConfig: this.driverConfig,
-      transform: this.transform,
-      posX: this.posX,
-      posZ: this.posZ,
-      lineId: this.lineId,
-      semantics: this.semantics,
-      value: this.value,
-      lastAckAt: this.lastAckAt,
-      lastWriteAt: this.lastWriteAt,
-      state: this.state,
-      lastError: this.lastError,
-      createdAt: this.createdAt,
-    }
-  }
-}
+/**
+ * DcwNode —— 数据写控制节点领域对象(与 DaqNode 对称)。
+ *
+ * 一个实例 = 一条工艺参数写通道:模板域(物理含义/单位/工艺安全量程)+ 驱动配置
+ * (连接 + 工程量→原始值线性换算,系统封装)+ 绑定关系 + 写状态(value/lastAckAt/
+ * writeState)。用户只操作工程量;PLC 原始值的换算/回读校验由运行时完成。
+ * 序列化经 toRow/fromRow 对接持久化仓库(dcws.json)。
+ */
+
+import { dcwKeyFromRef, type DcwDriverKind, type DcwNodeState, type DcwNodeView, type DataTransform } from '../../../../shared/dcw-protocol'
+import { findDcwTemplate } from './dcw-templates'
+
+interface DcwNodeOptions {
+  id: string
+  templateRef: string
+  name?: string
+  driver?: DcwDriverKind
+  enabled?: boolean
+  /** 保写周期 ms(心跳重下发;null = 仅手动下发) */
+  holdIntervalMs?: number | null
+  unit?: string
+  decimals?: number
+  min?: number
+  max?: number
+  deviceBindingId?: string | null
+  driverConfig?: Record<string, string | number | boolean>
+  /** 数据语义标定钩子(encode:物理值 → PLC 设定值;回读经 decoder 校验) */
+  transform?: DataTransform
+  posX?: number
+  posZ?: number
+  /** 所属产线('' = 未分配) */
+  lineId?: string
+  /** 节点级工艺语义备注(覆盖模板 semantics;注入 Agent 上下文) */
+  semantics?: string
+  /** 周期读间隔 ms(null = 走网关默认;0 = 关闭周期读,仅手动读取) */
+  readIntervalMs?: number | null
+  createdAt?: string
+}
+
+export class DcwNode {
+  readonly id: string
+  templateRef: string
+  name: string
+  driver: DcwDriverKind
+  enabled: boolean
+  holdIntervalMs: number | null
+  unit: string
+  decimals: number
+  min: number
+  max: number
+  deviceBindingId: string | null
+  driverConfig: Record<string, string | number | boolean>
+  transform?: DataTransform
+  posX?: number
+  posZ?: number
+  /** 当前设定值(工程量;null = 从未下发) */
+  value: number | null = null
+  /** PLC 当前读数(工程量物理值;null = 从未读到或驱动不支持读) */
+  readValue: number | null = null
+  lastReadAt: string | null = null
+  lastReadError: string | null = null
+  /** 周期读间隔 ms(null = 走网关默认;0 = 仅手动读取) */
+  readIntervalMs: number | null = null
+  lastAckAt: string | null = null
+  lastWriteAt: string | null = null
+  state: DcwNodeState = 'idle'
+  /** 所属产线('' = 未分配;采集门控/写联锁/场景光晕按产线隔离) */
+  lineId = ''
+  /** 节点级工艺语义备注(覆盖模板 semantics) */
+  semantics?: string
+  lastError: string | null = null
+  readonly createdAt: string
+
+  constructor(o: DcwNodeOptions) {
+    const tpl = findDcwTemplate(dcwKeyFromRef(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.holdIntervalMs = o.holdIntervalMs ?? 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
+    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.readIntervalMs = o.readIntervalMs ?? null
+    this.createdAt = o.createdAt ?? new Date().toISOString()
+  }
+
+  get templateKey(): string {
+    return dcwKeyFromRef(this.templateRef)
+  }
+
+  /** 写入值工艺安全校验(越界即拒绝;返回错误消息或 null) */
+  validateEng(v: number): string | null {
+    if (!Number.isFinite(v)) return '设定值需为数字'
+    if (v < this.min || v > this.max) {
+      return `设定值 ${v}${this.unit} 越出工艺安全量程 [${this.min}, ${this.max}] ${this.unit}`
+    }
+    return null
+  }
+
+  /** 记录一次写 ACK(成功)/失败 */
+  applyWriteResult(eng: number, ok: boolean, message: string, at: string): void {
+    this.value = Number(eng.toFixed(this.decimals))
+    this.lastWriteAt = at
+    if (ok) {
+      this.lastAckAt = at
+      this.state = 'ok'
+      this.lastError = null
+    }
+    else {
+      this.state = 'error'
+      this.lastError = message
+    }
+  }
+
+  /** 记录一次读数(成功回填物理值;失败仅记原因,旧读数保留供展示) */
+  applyReadResult(eng: number | null, raw: number | null, ok: boolean, message: string, at: string): void {
+    this.lastReadAt = at
+    if (ok && eng != null) {
+      this.readValue = Number(eng.toFixed(this.decimals))
+      this.lastReadError = null
+    }
+    else {
+      this.lastReadError = message
+    }
+  }
+
+  toRow(): Record<string, unknown> {
+    return {
+      id: this.id,
+      templateRef: this.templateRef,
+      name: this.name,
+      driver: this.driver,
+      enabled: this.enabled,
+      holdIntervalMs: this.holdIntervalMs,
+      readIntervalMs: this.readIntervalMs,
+      unit: this.unit,
+      decimals: this.decimals,
+      min: this.min,
+      max: this.max,
+      deviceBindingId: this.deviceBindingId,
+      driverConfig: this.driverConfig,
+      transform: this.transform,
+      posX: this.posX,
+      posZ: this.posZ,
+      lineId: this.lineId,
+      semantics: this.semantics,
+      value: this.value,
+      readValue: this.readValue,
+      lastReadAt: this.lastReadAt,
+      lastReadError: this.lastReadError,
+      lastAckAt: this.lastAckAt,
+      lastWriteAt: this.lastWriteAt,
+      state: this.state,
+      lastError: this.lastError,
+      createdAt: this.createdAt,
+    }
+  }
+
+  static fromRow(row: Record<string, unknown>): DcwNode {
+    const node = new DcwNode({
+      id: String(row.id),
+      templateRef: String(row.templateRef ?? ''),
+      name: row.name != null ? String(row.name) : undefined,
+      driver: (row.driver as DcwDriverKind) ?? undefined,
+      enabled: row.enabled === undefined ? undefined : Boolean(row.enabled),
+      holdIntervalMs: row.holdIntervalMs == null ? null : Number(row.holdIntervalMs),
+      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,
+      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),
+      lineId: row.lineId == null ? '' : String(row.lineId),
+      semantics: row.semantics == null ? undefined : String(row.semantics),
+      readIntervalMs: row.readIntervalMs == null ? null : Number(row.readIntervalMs),
+      posZ: row.posZ == null ? undefined : Number(row.posZ),
+      createdAt: row.createdAt != null ? String(row.createdAt) : undefined,
+    })
+    if (row.value != null && !Number.isNaN(Number(row.value))) node.value = Number(row.value)
+    if (row.readValue != null && !Number.isNaN(Number(row.readValue))) node.readValue = Number(row.readValue)
+    if (row.lastReadAt != null) node.lastReadAt = String(row.lastReadAt)
+    if (row.lastReadError != null) node.lastReadError = String(row.lastReadError)
+    if (row.lastAckAt != null) node.lastAckAt = String(row.lastAckAt)
+    if (row.lastWriteAt != null) node.lastWriteAt = String(row.lastWriteAt)
+    if (row.state != null) node.state = String(row.state) as DcwNodeState
+    if (row.lastError != null) node.lastError = String(row.lastError)
+    return node
+  }
+
+  toView(): DcwNodeView {
+    return {
+      id: this.id,
+      templateRef: this.templateRef,
+      name: this.name,
+      driver: this.driver,
+      enabled: this.enabled,
+      holdIntervalMs: this.holdIntervalMs,
+      unit: this.unit,
+      decimals: this.decimals,
+      min: this.min,
+      max: this.max,
+      deviceBindingId: this.deviceBindingId,
+      driverConfig: this.driverConfig,
+      transform: this.transform,
+      posX: this.posX,
+      posZ: this.posZ,
+      lineId: this.lineId,
+      semantics: this.semantics,
+      value: this.value,
+      readValue: this.readValue,
+      lastReadAt: this.lastReadAt,
+      lastReadError: this.lastReadError,
+      readIntervalMs: this.readIntervalMs,
+      lastAckAt: this.lastAckAt,
+      lastWriteAt: this.lastWriteAt,
+      state: this.state,
+      lastError: this.lastError,
+      createdAt: this.createdAt,
+    }
+  }
+}

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

@@ -27,23 +27,37 @@ export interface DcwWriteOutcome {
 
 export interface DcwRuntimeHost {
   running(): boolean
-  defaults(): { holdIntervalMs: number }
+  defaults(): { holdIntervalMs: number, readIntervalMs: number }
   /** 网关执行写命令(驱动写 + ACK 记账 + 写历史 + WS 广播) */
   executeWrite(node: DcwNode, eng: number, tolerance: number, recipeRunId: string | null): Promise<DcwWriteOutcome>
+  /** 网关执行读数(驱动读 + 读状态记账 + WS 广播;返回物理值) */
+  executeRead(node: DcwNode): Promise<{ ok: boolean, value: number | null, raw: number | null, message: string, at: string }>
+}
+
+export interface DcwReadOutcome {
+  ok: boolean
+  value: number | null
+  raw: number | null
+  message: string
+  at: string
 }
 
 export class DcwNodeRuntime {
   private writing = false
   private lastHoldAt = 0
+  /** 周期读节拍 + 在飞互斥(读事务不与写事务互斥,但同节点读不重入) */
+  private lastReadTick = 0
+  private reading = false
 
   constructor(
     public readonly node: DcwNode,
     private readonly host: DcwRuntimeHost,
   ) {}
 
-  /** 元数据变更后重置保写节拍 */
+  /** 元数据变更后重置保写/周期读节拍 */
   rearm(): void {
     this.lastHoldAt = 0
+    this.lastReadTick = 0
   }
 
   /**
@@ -69,14 +83,37 @@ export class DcwNodeRuntime {
   }
 
   /** 网关 tick:保写心跳(元数据 holdIntervalMs;null = 仅手动下发)。
-   *  对当前设定值周期性重下发(PLC 掉电重启后的设定恢复语义)。 */
+   *  对当前设定值周期性重下发(PLC 掉电重启后的设定恢复语义)。
+   *  周期读(元数据 readIntervalMs):读是被动观测,不受产线运行/写在飞限制
+   *  (仅与在飞读互斥),failures 只记 lastReadError 不改写状态机。 */
   tick(now: number): void {
     const node = this.node
-    if (this.writing || !node.enabled || node.value == null || node.state === 'writing') return
-    const hold = node.holdIntervalMs ?? this.host.defaults().holdIntervalMs
-    if (!hold || hold <= 0) return
-    if (now - this.lastHoldAt < hold) return
-    this.lastHoldAt = now
-    void this.host.executeWrite(node, node.value, writeTolerance(node), null).catch(() => {})
+    // 保写心跳:仅对已设定过的节点生效(尚无设定值无可保持)
+    if (!this.writing && node.enabled && node.value != null && node.state !== 'writing') {
+      const hold = node.holdIntervalMs ?? this.host.defaults().holdIntervalMs
+      if (hold && hold > 0 && now - this.lastHoldAt >= hold) {
+        this.lastHoldAt = now
+        void this.host.executeWrite(node, node.value, writeTolerance(node), null).catch(() => {})
+      }
+    }
+    // 周期读:被动观测,不依赖写过、不与写在飞互斥(仅同节点读串行)
+    if (this.reading || !node.enabled) return
+    const readInt = node.readIntervalMs ?? this.host.defaults().readIntervalMs
+    if (!readInt || readInt <= 0) return
+    if (now - this.lastReadTick < readInt) return
+    this.lastReadTick = now
+    void this.host.executeRead(node).catch(() => {})
+  }
+
+  /** 手动读取(on-demand;REST/Agent 工具共用;与周期读同一在飞互斥) */
+  async readNow(): Promise<DcwReadOutcome> {
+    if (this.reading) throw new AppError(409, ErrorCodes.CONFLICT, `通道「${this.node.name}」读取进行中,请稍后重试`)
+    this.reading = true
+    try {
+      return await this.host.executeRead(this.node)
+    }
+    finally {
+      this.reading = false
+    }
   }
 }

package/server/services/workshop/dcw/drivers.ts

@@ -38,6 +38,28 @@ export interface DcwWriteDriver {
   available(): Promise<boolean>
   write(input: DcwWriteInput): Promise<DcwWriteResult>
   test(driverConfig: Record<string, unknown>): Promise<{ ok: boolean, message: string }>
+  /** 读当前 PLC 值(可选原语;不支持读的驱动为 undefined,网关按 supportsRead 收敛) */
+  read?(input: DcwReadInput): Promise<DcwReadResult>
+}
+
+export interface DcwReadInput {
+  /** 节点工艺量程(原始值↔工程量映射缺省域) */
+  domain: { min: number, max: number }
+  driverConfig: Record<string, unknown>
+}
+
+export interface DcwReadResult {
+  ok: boolean
+  message: string
+  /** 工程量(PLC 语义;寄存器驱动 = 原始值解码后映射,直写型驱动 = 节点值本身) */
+  eng: number | null
+  /** 原始值(寄存器解码;非寄存器驱动与 eng 同源) */
+  raw: number | null
+}
+
+/** 读能力判定(网关调度周期读前先收敛,不支持读的驱动不空转) */
+export function supportsDcwRead(kind: DcwDriverKind): boolean {
+  return resolveDcwDriver(kind).read != null
 }
 
 const num = (v: unknown): number | undefined => {
@@ -111,11 +133,53 @@ export const mockDcwDriver: DcwWriteDriver = {
       readback: input.eng,
     }
   },
+  async read(input) {
+    const key = `${input.driverConfig.key ?? 'default'}`
+    const has = mockState.__dcwMockPlc!.has(key)
+    const eng = mockState.__dcwMockPlc!.get(key) ?? null
+    return has
+      ? { ok: true, message: `Mock PLC 读回:${eng}`, eng, raw: eng }
+      : { ok: false, message: `Mock PLC 无设定记录(${key};从未写入)`, eng: null, raw: null }
+  },
   async test() {
     return { ok: true, message: 'Mock 驱动无需连接,写入即模拟 ACK' }
   },
 }
 
+// ============================================================
+// Modbus 读原语(TCP/RTU 共用;读保持寄存器 → 解码 → 工程量映射)
+// ============================================================
+
+function wordsOf(dataType: string): number {
+  return dataType === 'int16' || dataType === 'uint16' ? 1 : 2
+}
+
+async function modbusRead(input: DcwReadInput, transport: 'tcp' | 'rtu-tcp'): Promise<DcwReadResult> {
+  const cfg = input.driverConfig
+  if (!cfg.host) throw new AppError(400, 'BAD_REQUEST', '缺少设备地址 host')
+  if (cfg.register == null) throw new AppError(400, 'BAD_REQUEST', '缺少寄存器地址 register')
+  const dataType = String(cfg.dataType ?? 'float32')
+  const byteOrder = String(cfg.byteOrder ?? 'big')
+  const offset = registerOffset(Number(cfg.register ?? 0), 'holding')
+  const conn = await getModbusConn(cfg, transport)
+  conn.lastUsed = Date.now()
+  return withModbusConn(conn, async (): Promise<DcwReadResult> => {
+    try {
+      const rb = await conn.client.readHoldingRegisters(offset, wordsOf(dataType))
+      const raw = decodeRegisters(rb.data as number[], dataType, byteOrder)
+      // 原始值 → 工程量(与写链路同一映射;engToRaw/rawToEng 对称)
+      const eng = rawToEng(raw, { eng: 0, tolerance: 0, domain: input.domain, driverConfig: cfg })
+      conn.errors = 0
+      return { ok: true, message: `读回 raw ${Number(raw.toFixed(4))} → eng ${Number(eng.toFixed(4))}`, eng, raw }
+    }
+    catch (err) {
+      conn.errors++
+      if (conn.errors >= 3) evictModbusConn(cfg, transport)
+      throw err
+    }
+  })
+}
+
 // ============================================================
 // Modbus TCP 写驱动(写保持寄存器 + 同址回读校验;连接池复用数采)
 // ============================================================
@@ -183,6 +247,14 @@ export const modbusTcpDcwDriver: DcwWriteDriver = {
       return { ok: false, message: `Modbus 写入失败: ${err instanceof Error ? err.message : String(err)}`, raw: null, readback: null }
     }
   },
+  async read(input) {
+    try {
+      return await modbusRead(input, 'tcp')
+    }
+    catch (err) {
+      return { ok: false, message: `Modbus 读取失败: ${err instanceof Error ? err.message : String(err)}`, eng: null, raw: null }
+    }
+  },
   async test(driverConfig) {
     const t0 = Date.now()
     try {
@@ -258,6 +330,24 @@ export const opcUaDcwDriver: DcwWriteDriver = {
       return { ok: false, message: `OPC UA 写入失败: ${err instanceof Error ? err.message : String(err)}`, raw: null, readback: null }
     }
   },
+  async read(input) {
+    try {
+      const cfg = input.driverConfig
+      if (!cfg.endpoint) throw new AppError(400, 'BAD_REQUEST', '缺少端点 endpoint(opc.tcp://…)')
+      if (!cfg.nodeId) throw new AppError(400, 'BAD_REQUEST', '缺少节点 ID nodeId(ns=…;s=…)')
+      const conn = await getOpcUaConn(cfg)
+      const opcua = reqNative('node-opcua') as typeof import('node-opcua')
+      const dv = await conn.session.read({ nodeId: opcua.coerceNodeId(String(cfg.nodeId)), attributeId: opcua.AttributeIds.Value }) as unknown as { value?: { value?: unknown }, status?: { value?: number }, statusCode?: { value?: number } }
+      const code = dv.status?.value ?? dv.statusCode?.value ?? 0
+      if (code !== 0) return { ok: false, message: `节点读取状态异常: 0x${code.toString(16)}`, eng: null, raw: null }
+      const v = Number(dv.value?.value)
+      if (!Number.isFinite(v)) return { ok: false, message: '节点值为非数值', eng: null, raw: null }
+      return { ok: true, message: `读回 ${Number(v.toFixed(4))}`, eng: v, raw: v }
+    }
+    catch (err) {
+      return { ok: false, message: `OPC UA 读取失败: ${err instanceof Error ? err.message : String(err)}`, eng: null, raw: null }
+    }
+  },
   async test(driverConfig) {
     try {
       if (!driverConfig.endpoint) return { ok: false, message: '缺少端点 endpoint(opc.tcp://…)' }
@@ -336,6 +426,14 @@ export const modbusRtuDcwDriver: DcwWriteDriver = {
       return { ok: false, message: `Modbus RTU 写入失败: ${err instanceof Error ? err.message : String(err)}`, raw: null, readback: null }
     }
   },
+  async read(input) {
+    try {
+      return await modbusRead(input, 'rtu-tcp')
+    }
+    catch (err) {
+      return { ok: false, message: `Modbus RTU 读取失败: ${err instanceof Error ? err.message : String(err)}`, eng: null, raw: null }
+    }
+  },
   async test(driverConfig) {
     const t0 = Date.now()
     try {