agentworkshop 0.7.49 → 0.7.51

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

@@ -1,139 +1,131 @@
-/**
- * Modbus 读原语(TCP/RTU 共用)与 Modbus TCP 写驱动
- * (由 server/services/workshop/dcw/drivers.ts 按职责拆出;内容逐行原文搬运)
- */
-import type { DcwReadInput, DcwReadResult, DcwWriteDriver, DcwWriteInput, DcwWriteResult } from './shared'
-import { AppError } from '../../../../utils/errors'
-import { classifyCommError, closeModbusSafely, decodeRegisters, evictModbusConn, getModbusConn, modbusKey, registerOffset, withModbusConn } from '../../daq/drivers'
-import { encodeWords, engToRaw, rawToEng, reqNative } from './shared'
-
-// ============================================================
-// Modbus 读原语(TCP/RTU 共用;读保持寄存器 → 解码 → 工程量映射)
-// ============================================================
-
-export function wordsOf(dataType: string): number {
-  return dataType === 'int16' || dataType === 'uint16' ? 1 : 2
-}
-
-export 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 写驱动(写保持寄存器 + 同址回读校验;连接池复用数采)
-// ============================================================
-
-export async function modbusWrite(input: DcwWriteInput): Promise<DcwWriteResult> {
-  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 raw = engToRaw(input.eng, input)
-  const rounded = dataType === 'float32' ? raw : Math.round(raw)
-  const words = encodeWords(rounded, dataType, byteOrder)
-  const area = 'holding' // 写只支持保持寄存器(4x)
-  const offset = registerOffset(Number(cfg.register ?? 0), area)
-  const conn = await getModbusConn(cfg)
-  conn.lastUsed = Date.now()
-  // 连接级排队:等当前数采读/其它事务完成后执行(采/控共用链路,写不再因忙被 409 拒绝)
-  return withModbusConn(conn, async (): Promise<DcwWriteResult> => {
-    try {
-      await conn.client.writeRegisters(offset, words)
-      // 回读校验:同址读回 → 解码 → 换算回工程量 → 容差比较
-      const rb = area === 'holding'
-        ? await conn.client.readHoldingRegisters(offset, words.length)
-        : await conn.client.readInputRegisters(offset, words.length)
-      const rawBack = decodeRegisters(rb.data as number[], dataType, byteOrder)
-      const engBack = rawToEng(rawBack, input)
-      const ok = Math.abs(engBack - input.eng) <= input.tolerance
-      conn.errors = 0
-      return {
-        ok,
-        message: ok
-          ? `写入并回读一致:${input.eng} → raw ${rounded},回读 ${Number(engBack.toFixed(4))}`
-          : `回读偏差超容差:写 ${input.eng},回读 ${Number(engBack.toFixed(4))}(容差 ${input.tolerance})`,
-        raw: rounded,
-        readback: engBack,
-      }
-    }
-    catch (err) {
-      // 与数采对称的自愈:连续故障主动断开,下次操作重建连接
-      conn.errors++
-      if (conn.errors >= 3) evictModbusConn(cfg)
-      throw err
-    }
-  })
-}
-
-export const modbusTcpDcwDriver: DcwWriteDriver = {
-  kind: 'modbus-tcp',
-  async available() {
-    try {
-      reqNative('modbus-serial')
-      return true
-    }
-    catch {
-      return false
-    }
-  },
-  async write(input) {
-    try {
-      return await modbusWrite(input)
-    }
-    catch (err) {
-      if (err instanceof AppError) throw err
-      return { ok: false, message: `Modbus 写入失败: ${classifyCommError(err)}`, raw: null, readback: null }
-    }
-  },
-  async read(input) {
-    try {
-      return await modbusRead(input, 'tcp')
-    }
-    catch (err) {
-      return { ok: false, message: `Modbus 读取失败: ${classifyCommError(err)}`, eng: null, raw: null }
-    }
-  },
-  async test(driverConfig) {
-    const t0 = Date.now()
-    try {
-      if (!driverConfig.host) return { ok: false, message: '缺少设备地址 host' }
-      if (driverConfig.register == null) return { ok: false, message: '缺少写寄存器地址 register' }
-      const conn = await getModbusConn(driverConfig)
-      await withModbusConn(conn, () => conn.client.readHoldingRegisters(registerOffset(Number(driverConfig.register ?? 0), 'holding'), 1))
-      return { ok: true, message: `连接成功,写寄存器可访问(offset=${registerOffset(Number(driverConfig.register ?? 0), 'holding')}), ${Date.now() - t0}ms` }
-    }
-    catch (err) {
-      try {
-        const key = modbusKey(driverConfig)
-        const conn = await getModbusConn(driverConfig).catch(() => null)
-        if (conn) await closeModbusSafely(conn.client)
-        void key
-      }
-      catch { /* ignore */ }
-      return { ok: false, message: classifyCommError(err) }
-    }
-  },
-}
+/**
+ * Modbus 读原语(TCP/RTU 共用)与 Modbus TCP 写驱动
+ * (由 server/services/workshop/dcw/drivers.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type { DcwReadInput, DcwReadResult, DcwWriteDriver, DcwWriteInput, DcwWriteResult } from './shared'
+import { AppError } from '../../../../utils/errors'
+import { classifyCommError, closeModbusSafely, decodeRegisters, evictModbusConn, getModbusConn, modbusKey, registerOffset, withModbusConn } from '../../daq/drivers/modbus-tcp'
+import { encodeWords, engToRaw, rawToEng, readbackAck, reqNative } from './shared'
+
+// ============================================================
+// Modbus 读原语(TCP/RTU 共用;读保持寄存器 → 解码 → 工程量映射)
+// ============================================================
+
+export function wordsOf(dataType: string): number {
+  return dataType === 'int16' || dataType === 'uint16' ? 1 : 2
+}
+
+export 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 写驱动(写保持寄存器 + 同址回读校验;连接池复用数采)
+// ============================================================
+
+export async function modbusWrite(input: DcwWriteInput): Promise<DcwWriteResult> {
+  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 raw = engToRaw(input.eng, input)
+  const rounded = dataType === 'float32' ? raw : Math.round(raw)
+  const words = encodeWords(rounded, dataType, byteOrder)
+  const area = 'holding' // 写只支持保持寄存器(4x)
+  const offset = registerOffset(Number(cfg.register ?? 0), area)
+  const conn = await getModbusConn(cfg)
+  conn.lastUsed = Date.now()
+  // 连接级排队:等当前数采读/其它事务完成后执行(采/控共用链路,写不再因忙被 409 拒绝)
+  return withModbusConn(conn, async (): Promise<DcwWriteResult> => {
+    try {
+      await conn.client.writeRegisters(offset, words)
+      // 回读校验:同址读回 → 解码 → 换算回工程量 → 容差比较
+      const rb = area === 'holding'
+        ? await conn.client.readHoldingRegisters(offset, words.length)
+        : await conn.client.readInputRegisters(offset, words.length)
+      const rawBack = decodeRegisters(rb.data as number[], dataType, byteOrder)
+      const engBack = rawToEng(rawBack, input)
+      conn.errors = 0
+      return readbackAck(input, engBack, { raw: rounded, rawNote: String(rounded) })
+    }
+    catch (err) {
+      // 与数采对称的自愈:连续故障主动断开,下次操作重建连接
+      conn.errors++
+      if (conn.errors >= 3) evictModbusConn(cfg)
+      throw err
+    }
+  })
+}
+
+export const modbusTcpDcwDriver: DcwWriteDriver = {
+  kind: 'modbus-tcp',
+  async available() {
+    try {
+      reqNative('modbus-serial')
+      return true
+    }
+    catch {
+      return false
+    }
+  },
+  async write(input) {
+    try {
+      return await modbusWrite(input)
+    }
+    catch (err) {
+      if (err instanceof AppError) throw err
+      return { ok: false, message: `Modbus 写入失败: ${classifyCommError(err)}`, raw: null, readback: null }
+    }
+  },
+  async read(input) {
+    try {
+      return await modbusRead(input, 'tcp')
+    }
+    catch (err) {
+      return { ok: false, message: `Modbus 读取失败: ${classifyCommError(err)}`, eng: null, raw: null }
+    }
+  },
+  async test(driverConfig) {
+    const t0 = Date.now()
+    try {
+      if (!driverConfig.host) return { ok: false, message: '缺少设备地址 host' }
+      if (driverConfig.register == null) return { ok: false, message: '缺少写寄存器地址 register' }
+      const conn = await getModbusConn(driverConfig)
+      await withModbusConn(conn, () => conn.client.readHoldingRegisters(registerOffset(Number(driverConfig.register ?? 0), 'holding'), 1))
+      return { ok: true, message: `连接成功,写寄存器可访问(offset=${registerOffset(Number(driverConfig.register ?? 0), 'holding')}), ${Date.now() - t0}ms` }
+    }
+    catch (err) {
+      try {
+        const key = modbusKey(driverConfig)
+        const conn = await getModbusConn(driverConfig).catch(() => null)
+        if (conn) await closeModbusSafely(conn.client)
+        void key
+      }
+      catch { /* ignore */ }
+      return { ok: false, message: classifyCommError(err) }
+    }
+  },
+}

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

@@ -1,110 +1,103 @@
-/**
- * OPC UA 写驱动(会话池复用 + 重试)
- * (由 server/services/workshop/dcw/drivers.ts 按职责拆出;内容逐行原文搬运)
- */
-import type { DcwWriteDriver, DcwWriteInput, DcwWriteResult } from './shared'
-import { AppError } from '../../../../utils/errors'
-import { classifyCommError, evictOpcUaConn, getOpcUaConn } from '../../daq/drivers'
-import { reqNative } from './shared'
-
-// ============================================================
-// OPC UA 写驱动(写节点值 + 回读校验;会话池复用数采)
-// ============================================================
-
-export async function opcuaWrite(input: DcwWriteInput): Promise<DcwWriteResult> {
-  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)
-  // 会话死亡自愈:连续 3 次故障驱逐重建(与数采采样路径同策略)。此前纯写控节点
-  // 会拿同一个死 session 反复失败,直到 10 分钟空闲 sweep 才可能重建。
-  try {
-    return await opcuaWriteOnce(conn, input)
-  }
-  catch (err) {
-    conn.errors++
-    if (conn.errors >= 3) void evictOpcUaConn(cfg)
-    throw err
-  }
-}
-
-export async function opcuaWriteOnce(conn: { session: import('node-opcua').ClientSession, errors: number }, input: DcwWriteInput): Promise<DcwWriteResult> {
-  const cfg = input.driverConfig
-  const opcua = reqNative('node-opcua') as typeof import('node-opcua')
-  const node = opcua.coerceNodeId(String(cfg.nodeId))
-  const writeResult = await conn.session.write({
-    nodeId: node,
-    attributeId: opcua.AttributeIds.Value,
-    value: { value: { dataType: opcua.DataType.Double, value: input.eng } },
-  }) as unknown as { statusCode?: { value: number } }
-  const writeCode = writeResult.statusCode?.value ?? 0
-  if (writeCode !== 0) {
-    throw new Error(`写入状态异常: 0x${writeCode.toString(16)}`)
-  }
-  const dv = await conn.session.read({ nodeId: node, attributeId: opcua.AttributeIds.Value }) as unknown as { value?: { value?: number } }
-  const back = typeof dv.value?.value === 'number' ? dv.value.value : Number(dv.value?.value)
-  const ok = Number.isFinite(back) && Math.abs(back - input.eng) <= input.tolerance
-  return {
-    ok,
-    message: ok
-      ? `写入并回读一致:${input.eng},回读 ${Number(back.toFixed(4))}`
-      : `回读偏差超容差:写 ${input.eng},回读 ${Number.isFinite(back) ? back.toFixed(4) : '非数值'}`,
-    raw: input.eng,
-    readback: Number.isFinite(back) ? back : null,
-  }
-}
-
-export const opcUaDcwDriver: DcwWriteDriver = {
-  kind: 'opcua',
-  async available() {
-    try {
-      reqNative('node-opcua')
-      return true
-    }
-    catch {
-      return false
-    }
-  },
-  async write(input) {
-    try {
-      return await opcuaWrite(input)
-    }
-    catch (err) {
-      if (err instanceof AppError) throw err
-      return { ok: false, message: `OPC UA 写入失败: ${classifyCommError(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 读取失败: ${classifyCommError(err)}`, eng: null, raw: null }
-    }
-  },
-  async test(driverConfig) {
-    try {
-      if (!driverConfig.endpoint) return { ok: false, message: '缺少端点 endpoint(opc.tcp://…)' }
-      if (!driverConfig.nodeId) return { ok: false, message: '缺少节点 ID nodeId(ns=…;s=…)' }
-      const conn = await getOpcUaConn(driverConfig)
-      const opcua = reqNative('node-opcua') as typeof import('node-opcua')
-      const dv = await conn.session.read({ nodeId: opcua.coerceNodeId(String(driverConfig.nodeId)), attributeId: opcua.AttributeIds.Value }) as unknown as { 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)}` }
-      return { ok: true, message: `会话建立成功,写节点可访问(${String(driverConfig.nodeId)})` }
-    }
-    catch (err) {
-      return { ok: false, message: classifyCommError(err) }
-    }
-  },
-}
+/**
+ * OPC UA 写驱动(会话池复用 + 重试)
+ * (由 server/services/workshop/dcw/drivers.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type { DcwWriteDriver, DcwWriteInput, DcwWriteResult } from './shared'
+import { AppError } from '../../../../utils/errors'
+import { classifyCommError } from '../../daq/drivers/modbus-tcp'
+import { evictOpcUaConn, getOpcUaConn } from '../../daq/drivers/opcua'
+import { readbackAck, reqNative } from './shared'
+
+// ============================================================
+// OPC UA 写驱动(写节点值 + 回读校验;会话池复用数采)
+// ============================================================
+
+export async function opcuaWrite(input: DcwWriteInput): Promise<DcwWriteResult> {
+  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)
+  // 会话死亡自愈:连续 3 次故障驱逐重建(与数采采样路径同策略)。此前纯写控节点
+  // 会拿同一个死 session 反复失败,直到 10 分钟空闲 sweep 才可能重建。
+  try {
+    return await opcuaWriteOnce(conn, input)
+  }
+  catch (err) {
+    conn.errors++
+    if (conn.errors >= 3) void evictOpcUaConn(cfg)
+    throw err
+  }
+}
+
+export async function opcuaWriteOnce(conn: { session: import('node-opcua').ClientSession, errors: number }, input: DcwWriteInput): Promise<DcwWriteResult> {
+  const cfg = input.driverConfig
+  const opcua = reqNative('node-opcua') as typeof import('node-opcua')
+  const node = opcua.coerceNodeId(String(cfg.nodeId))
+  const writeResult = await conn.session.write({
+    nodeId: node,
+    attributeId: opcua.AttributeIds.Value,
+    value: { value: { dataType: opcua.DataType.Double, value: input.eng } },
+  }) as unknown as { statusCode?: { value: number } }
+  const writeCode = writeResult.statusCode?.value ?? 0
+  if (writeCode !== 0) {
+    throw new Error(`写入状态异常: 0x${writeCode.toString(16)}`)
+  }
+  const dv = await conn.session.read({ nodeId: node, attributeId: opcua.AttributeIds.Value }) as unknown as { value?: { value?: number } }
+  const back = typeof dv.value?.value === 'number' ? dv.value.value : Number(dv.value?.value)
+  return readbackAck(input, back, { raw: input.eng })
+}
+
+export const opcUaDcwDriver: DcwWriteDriver = {
+  kind: 'opcua',
+  async available() {
+    try {
+      reqNative('node-opcua')
+      return true
+    }
+    catch {
+      return false
+    }
+  },
+  async write(input) {
+    try {
+      return await opcuaWrite(input)
+    }
+    catch (err) {
+      if (err instanceof AppError) throw err
+      return { ok: false, message: `OPC UA 写入失败: ${classifyCommError(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 读取失败: ${classifyCommError(err)}`, eng: null, raw: null }
+    }
+  },
+  async test(driverConfig) {
+    try {
+      if (!driverConfig.endpoint) return { ok: false, message: '缺少端点 endpoint(opc.tcp://…)' }
+      if (!driverConfig.nodeId) return { ok: false, message: '缺少节点 ID nodeId(ns=…;s=…)' }
+      const conn = await getOpcUaConn(driverConfig)
+      const opcua = reqNative('node-opcua') as typeof import('node-opcua')
+      const dv = await conn.session.read({ nodeId: opcua.coerceNodeId(String(driverConfig.nodeId)), attributeId: opcua.AttributeIds.Value }) as unknown as { 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)}` }
+      return { ok: true, message: `会话建立成功,写节点可访问(${String(driverConfig.nodeId)})` }
+    }
+    catch (err) {
+      return { ok: false, message: classifyCommError(err) }
+    }
+  },
+}

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

@@ -5,6 +5,7 @@
 import type { DcwDriverKind } from '../../../../../shared/dcw-protocol'
 import type { DcwWriteDriver } from './shared'
 import { DCW_DRIVERS } from '../../../../../shared/dcw-protocol'
+import { createPluginDriverRegistry, type PluginDriverMetaLike } from '../../plugin-driver-registry'
 import { httpDcwDriver } from './http'
 import { mockDcwDriver } from './mock'
 import { modbusRtuDcwDriver } from './modbus-rtu'
@@ -27,58 +28,43 @@ export const REGISTRY: Record<DcwDriverKind, DcwWriteDriver> = {
 
 /**
  * 插件写驱动注册表(经 ctx.dcw.registerWriteDriver;与数采侧 registerPluginDriver 对称)。
- * globalThis 防 HMR 双实例;resolveDcwDriver 插件优先,热重载同名幂等覆盖。
- * 驱动可携带可选 meta(label/configFields)进写控驱动目录(dcwDriverCatalog)。
+ * resolveDcwDriver 插件优先,热重载同名幂等覆盖;驱动可携带可选 meta(label/configFields)
+ * 进写控驱动目录(dcwDriverCatalog)。装配语义(注册/覆盖告警/meta 维护/清空/目录合并)
+ * 由共享工厂提供。
  */
-export interface PluginWriteDriverMeta {
-  kind: string
-  label: string
-  status: 'builtin' | 'real' | 'planned'
-  configFields?: import('../../../../../shared/daq-protocol').DriverConfigField[]
-  plugin: true
-}
+export type PluginWriteDriverMeta = PluginDriverMetaLike
+
+const plugins = createPluginDriverRegistry<DcwWriteDriver>({
+  builtinKinds: REGISTRY,
+  driversKey: '__dcwPluginDrivers',
+  metasKey: '__dcwPluginDriverMetas',
+  onOverrideBuiltin: kind => console.warn(`[dcw-drivers] 插件写驱动覆盖内置:「${kind}」`),
+})
 
-export const g_plugins = globalThis as typeof globalThis & { __dcwPluginDrivers?: Map<string, DcwWriteDriver> }
 export function pluginRegistry(): Map<string, DcwWriteDriver> {
-  return g_plugins.__dcwPluginDrivers ??= new Map()
+  return plugins.pluginRegistry()
 }
 
-export const g_metas = globalThis as typeof globalThis & { __dcwPluginDriverMetas?: Map<string, PluginWriteDriverMeta> }
 export function pluginMetaRegistry(): Map<string, PluginWriteDriverMeta> {
-  return g_metas.__dcwPluginDriverMetas ??= new Map()
+  return plugins.pluginMetaRegistry()
 }
 
 export function registerPluginWriteDriver(driver: DcwWriteDriver): void {
-  if (driver.kind in REGISTRY) console.warn(`[dcw-drivers] 插件写驱动覆盖内置:「${driver.kind}」`)
-  pluginRegistry().set(driver.kind, driver)
-  const meta = (driver as DcwWriteDriver & { meta?: Omit<PluginWriteDriverMeta, 'kind' | 'plugin'> }).meta
-  if (meta && typeof meta.label === 'string') {
-    pluginMetaRegistry().set(driver.kind, {
-      kind: driver.kind,
-      label: meta.label,
-      status: meta.status === 'builtin' || meta.status === 'planned' ? meta.status : 'real',
-      configFields: Array.isArray(meta.configFields) ? meta.configFields : [],
-      plugin: true,
-    })
-  }
-  else {
-    pluginMetaRegistry().delete(driver.kind)
-  }
+  plugins.register(driver)
 }
 
 export function listPluginWriteDrivers(): string[] {
-  return [...pluginRegistry().keys()]
+  return plugins.listKeys()
 }
 
 /** 插件写驱动自描述目录(写控驱动目录合并端点用) */
 export function listPluginWriteDriverMetas(): PluginWriteDriverMeta[] {
-  return [...pluginMetaRegistry().values()]
+  return plugins.listMetas()
 }
 
 /** 清空插件写驱动与其自描述目录(插件宿主热重载前调用;与数采侧 clearPluginDrivers 对称) */
 export function clearPluginWriteDrivers(): void {
-  pluginRegistry().clear()
-  pluginMetaRegistry().clear()
+  plugins.clear()
 }
 
 /**
@@ -92,19 +78,7 @@ export async function dcwDriverCatalog(): Promise<Array<{
   configFields: import('../../../../../shared/daq-protocol').DriverConfigField[]
   plugin?: boolean
 }>> {
-  const out: Array<{ kind: string, label: string, status: 'builtin' | 'real' | 'planned', configFields: import('../../../../../shared/daq-protocol').DriverConfigField[], plugin?: boolean }> = DCW_DRIVERS.map(d => ({
-    kind: d.kind,
-    label: d.label,
-    status: d.status,
-    configFields: d.configFields,
-  }))
-  for (const m of listPluginWriteDriverMetas()) {
-    const i = out.findIndex(d => d.kind === m.kind)
-    const entry = { kind: m.kind, label: m.label, status: m.status, configFields: m.configFields ?? [], plugin: true }
-    if (i >= 0) out[i] = entry
-    else out.push(entry)
-  }
-  return out
+  return plugins.mergedCatalog(DCW_DRIVERS)
 }
 
 export function normalizeDcwDriverKind(kind: string): DcwDriverKind {
@@ -116,3 +90,9 @@ export function normalizeDcwDriverKind(kind: string): DcwDriverKind {
 export function resolveDcwDriver(kind: DcwDriverKind): DcwWriteDriver {
   return pluginRegistry().get(kind) ?? REGISTRY[kind] ?? mockDcwDriver
 }
+
+/** 读能力判定(网关调度周期读前先收敛,不支持读的驱动不空转)。
+ *  放在本模块而非 shared.ts:shared 是被驱动反向消费的纯函数层,依赖 registry 会成环。 */
+export function supportsDcwRead(kind: DcwDriverKind): boolean {
+  return resolveDcwDriver(kind).read != null
+}