agentworkshop 0.7.40 → 0.7.41

package/server/plugins-builtin/serial-bridge/index.mjs

@@ -0,0 +1,247 @@
+/**
+ * serial-bridge —— 串口通信协议插件(内置;随服务启动期装载)。
+ *
+ * 能力:
+ *  1. 数采读驱动(kind='serial'):Modbus RTU(RS-485/232,FC03/FC04)与 ASCII 行协议
+ *     (每行一个数值或 JSON)两种模式,经 ctx.daq.registerDriver 注入 —— 前端数采中心
+ *     「添加节点」即出现「串口 Serial」协议与动态参数表单;
+ *  2. 写控驱动(kind='serial'):Modbus RTU 写保持寄存器(FC06/FC16)+ 同址回读校验,
+ *     ASCII 行模板下行(无回读),经 ctx.dcw.registerWriteDriver 注入;
+ *  3. 后端 API(/api/plugins/serial-bridge/*):health(链路健康)/ ports(系统串口枚举)/
+ *     probe(无落库连接探针,支持 ASCII 发行探测);
+ *  4. Agent 工具 serial_ports:让 Agent 能枚举本机串口并诊断链路;
+ *  5. 前端面板(plugins.page 插槽):串口包可用性、系统端口表、探针表单、链路状态。
+ *
+ * 运行时依赖:serialport(optionalDependencies;缺失时 available=false 如实降级,
+ * 主服务与其余插件不受影响)。RTU 帧机为插件自研(rtu.mjs,单 serialport 原生栈)——
+ * 不用 modbus-serial:其包装层与 nitro dev worker isolate 组合会触发 V8 HandleScope
+ * 原生崩溃(实测稳定复现),纯 serialport 打开同口正常。
+ * 插件契约见 docs/plugins.md;驱动工厂见 drivers.mjs(可注入 opener,单测免硬件)。
+ */
+import { createRequire } from 'node:module'
+import { createSerialDrivers, SERIAL_READ_FIELDS } from './drivers.mjs'
+import { classifySerialError, normalizeSerialConfig } from './lib.mjs'
+import { createRtuClient } from './rtu.mjs'
+
+const require = createRequire(import.meta.url)
+
+/** serialport 可用性探测(包缺失/原生二进制不匹配 → null,驱动如实「未安装」) */
+function loadSerialPort() {
+  try {
+    const mod = require('serialport')
+    const SerialPort = mod.SerialPort ?? mod.default?.SerialPort
+    return SerialPort ? { SerialPort } : null
+  }
+  catch {
+    return null
+  }
+}
+
+/** 带硬超时的等待(建连/开串口防悬挂) */
+function withTimeout(p, ms, message) {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error(message)), ms)
+    Promise.resolve(p).then(
+      (v) => {
+        clearTimeout(t)
+        resolve(v)
+      },
+      (e) => {
+        clearTimeout(t)
+        reject(e)
+      },
+    )
+  })
+}
+
+export default {
+  name: 'serial-bridge',
+  version: '1.0.0',
+  description: '串口通信协议桥:Modbus RTU(RS-485/232)与 ASCII 行协议读驱动、带回读校验的写驱动、串口枚举/探针 API 与前端面板。',
+  auth: 'user',
+  client: './client.mjs',
+  setup(ctx) {
+    // ---- 运行时依赖探测(缺失不阻断装载,驱动 available=false 如实降级) ----
+    const sp = loadSerialPort()
+    if (!sp) ctx.logger.warn('serialport 包不可用(可选依赖未安装或原生二进制不匹配):串口驱动将显示「未安装」。npm i serialport 后重启即恢复。')
+
+    // ---- 协议栈实现(注入驱动工厂) ----
+
+    /** Modbus RTU over 串口:自研事务客户端(单 serialport 原生栈;见 rtu.mjs 头注) */
+    async function openRtu(cfg) {
+      if (!sp) throw new Error('serialport 包不可用(npm i serialport 后重启)')
+      const client = createRtuClient(sp.SerialPort, cfg)
+      await client.open()
+      return client
+    }
+
+    /** ASCII 行协议:serialport + 行分割;缓存最新行(保鲜窗在驱动层判定) */
+    async function openLine(cfg) {
+      if (!sp) throw new Error('serialport 包不可用(npm i serialport 后重启)')
+      const port = new sp.SerialPort({
+        path: cfg.path,
+        baudRate: cfg.baudRate,
+        dataBits: cfg.dataBits,
+        stopBits: cfg.stopBits,
+        parity: cfg.parity,
+        autoOpen: true,
+      })
+      await withTimeout(
+        new Promise((resolve, reject) => {
+          port.once('open', resolve)
+          port.once('error', reject)
+        }),
+        cfg.timeoutMs,
+        `串口打开超时(${cfg.timeoutMs}ms): ${cfg.path}@${cfg.baudRate}`,
+      )
+      const state = { latest: { text: '', at: 0 }, alive: true }
+      // 行分割:优先 readline 解析器;不可用时按 buffer 手工切行(等价语义)
+      let buffer = ''
+      const feed = (chunk) => {
+        buffer += chunk.toString('utf8')
+        let i
+        while ((i = buffer.indexOf('\n')) >= 0) {
+          const line = buffer.slice(0, i).replace(/\r$/, '')
+          buffer = buffer.slice(i + 1)
+          if (line.trim()) state.latest = { text: line, at: Date.now() }
+        }
+      }
+      port.on('data', feed)
+      const markDead = () => void (state.alive = false)
+      port.on('error', markDead)
+      port.on('close', markDead)
+      return {
+        alive: () => state.alive,
+        latest: () => state.latest,
+        writeLine: line => new Promise((resolve, reject) => {
+          port.write(`${line.endsWith('\n') ? line : `${line}\n`}`, (err) => {
+            if (err) reject(err)
+            else resolve()
+          })
+        }),
+        close: () => new Promise((resolve) => {
+          if (!port.isOpen) return resolve()
+          port.close(() => resolve())
+        }),
+      }
+    }
+
+    const factory = createSerialDrivers({
+      openRtu,
+      openLine,
+      isAvailable: () => Boolean(sp),
+      log: ctx.logger,
+    })
+
+    // ---- 驱动注入(数采读 + 写控;插件系统核心链路) ----
+    ctx.daq.registerDriver(factory.readDriver)
+    ctx.dcw.registerWriteDriver(factory.writeDriver)
+    ctx.onDispose(() => factory.closeAll())
+
+    // ---- 后端 API(/api/plugins/serial-bridge/*) ----
+
+    // 系统串口枚举(路径/厂商/序列号/友好名;供前端探针表单与运维排障)
+    ctx.route('GET', '/ports', async () => {
+      if (!sp) return { success: false, error: 'serialport 包不可用(npm i serialport 后重启)', ports: [] }
+      try {
+        const list = await sp.SerialPort.list()
+        return {
+          success: true,
+          ports: list.map(p => ({
+            path: p.path,
+            manufacturer: p.manufacturer ?? null,
+            serialNumber: p.serialNumber ?? null,
+            vendorId: p.vendorId ?? null,
+            productId: p.productId ?? null,
+            friendlyName: p.friendlyName ?? p.pnpId ?? null,
+          })),
+        }
+      }
+      catch (err) {
+        return { success: false, error: classifySerialError(err), ports: [] }
+      }
+    })
+
+    // 链路健康(协议栈可用性 + 打开的串口连接池快照;路由与 Agent 工具共用)
+    async function healthPayload() {
+      const nodes = await ctx.daq.nodes().catch(() => [])
+      const serialNodes = (Array.isArray(nodes) ? nodes : []).filter(n => n?.driver === 'serial')
+      return {
+        plugin: ctx.name,
+        available: Boolean(sp),
+        packages: { serialport: Boolean(sp) },
+        links: factory.poolSnapshot(),
+        /** 使用串口驱动的数采节点(读侧;写控节点见 dcw) */
+        readNodes: serialNodes.map(n => ({ id: n.id, name: n.name, lineId: n.lineId ?? null, path: n.driverConfig?.path ?? null, enabled: n.enabled !== false })),
+      }
+    }
+
+    ctx.route('GET', '/health', () => healthPayload())
+
+    // 连接探针(不落库):按给定参数开串口读一次;ascii 模式可选先行下发探测行。
+    // 复用驱动工厂的连接池与超时语义 —— probe 通过 = 该参数创建节点后必可采。
+    ctx.route('POST', '/probe', async (event) => {
+      const b = event?.awBody ?? {}
+      const driverConfig = {
+        mode: b.mode,
+        path: b.path,
+        baudRate: b.baudRate,
+        parity: b.parity,
+        dataBits: b.dataBits,
+        stopBits: b.stopBits,
+        unitId: b.unitId,
+        register: b.register,
+        registerType: b.registerType,
+        dataType: b.dataType,
+        byteOrder: b.byteOrder,
+        jsonPath: b.jsonPath,
+        timeoutMs: b.timeoutMs,
+      }
+      const { cfg, errors } = normalizeSerialConfig(driverConfig)
+      if (errors.length) return { success: false, error: errors.join(';') }
+      const t0 = Date.now()
+      try {
+        // ascii 探测行:先发一条(如「?」问询帧),给主动上报型设备一个触发
+        if (cfg.mode === 'ascii-line' && b.sendLine) {
+          const conn = await factory.getConn(cfg)
+          await conn.line.writeLine(String(b.sendLine))
+        }
+        const r = await factory.readDriver.test(driverConfig)
+        return { success: true, ...r, latencyMs: r.latencyMs ?? Date.now() - t0 }
+      }
+      catch (err) {
+        return { success: false, ok: false, message: classifySerialError(err), latencyMs: Date.now() - t0 }
+      }
+    })
+
+    // ---- Agent 工具:串口枚举 + 链路诊断 ----
+    ctx.omp.registerTool({
+      name: 'serial_ports',
+      label: '串口诊断',
+      description: '枚举本机串口端口(路径/厂商)与 serial-bridge 插件的串口链路健康(打开的连接/错误计数/串口数采节点)。串口设备接入与排障时使用。',
+      parameters: { type: 'object', properties: {} },
+      roles: ['lead', 'worker'],
+      handler: async () => {
+        try {
+          const d = await healthPayload()
+          const lines = [
+            `可用性: ${d.available === true ? 'serialport 就绪(RTU 帧机内建)' : `不可用(${JSON.stringify(d.packages ?? {})})`}`,
+            `串口数采节点: ${(d.readNodes ?? []).length} 个${(d.readNodes ?? []).length ? `(${d.readNodes.map(n => `${n.name || n.id}@${n.path || '?'}${n.enabled ? '' : '[停用]'}`).join(', ')})` : ''}`,
+            `打开的链路: ${(d.links ?? []).length} 条`,
+          ]
+          for (const l of d.links ?? []) lines.push(`  - ${l.key}(pending=${l.pending}, errors=${l.errors}, 最近使用 ${l.lastUsedAt ? new Date(l.lastUsedAt).toISOString() : '-'})`)
+          if (sp) {
+            const ports = await sp.SerialPort.list()
+            lines.push(`系统串口: ${ports.length ? ports.map(p => p.path).join(', ') : '(无)'}`)
+          }
+          return { text: lines.join('\n') }
+        }
+        catch (err) {
+          return { text: `serial_ports 异常: ${err?.message ?? err}`, isError: true }
+        }
+      },
+    })
+
+    ctx.logger.info(`serial-bridge 就绪:驱动 serial(读 ${SERIAL_READ_FIELDS.length} 参数)+ 写控 serial + 路由 health/ports/probe + 工具 serial_ports;serialport ${sp ? '可用' : '未安装(驱动显示未安装)'}`)
+  },
+}

package/server/plugins-builtin/serial-bridge/lib.mjs

@@ -0,0 +1,208 @@
+/**
+ * serial-bridge —— 纯协议层(零 I/O,可独立单测)。
+ *
+ * 串口链路上的两种报文语义:
+ *  - modbus-rtu:Modbus RTU over RS-485/232(CRC16 帧;寄存器读 FC03/FC04,写 FC06/FC16);
+ *    帧的收发与超时由 modbus-serial 承担,本层提供 CRC/编解码与寄存器↔工程量换算,
+ *    与内置 modbus-tcp / dcw 写驱动逐字节兼容(big/little/wordSwap 同一字节序约定)。
+ *  - ascii-line:设备每行输出一个数值(裸数字或 JSON,如 `{"temp":25.3}`);按 jsonPath 取值。
+ *
+ * 本文件不 import 任何宿主模块 —— 测试脚本直接以 ESM 引入即可。
+ */
+
+// ============================================================
+// 配置规范化(driverConfig → 强类型连接参数)
+// ============================================================
+
+const MODES = new Set(['modbus-rtu', 'ascii-line'])
+const PARITIES = new Set(['none', 'even', 'odd'])
+const DATA_TYPES = new Set(['int16', 'uint16', 'int32', 'uint32', 'float32'])
+const BYTE_ORDERS = new Set(['big', 'little', 'wordSwap'])
+export const WORDS_OF = { int16: 1, uint16: 1, int32: 2, uint32: 2, float32: 2 }
+
+/**
+ * 规范化并校验串口驱动配置;返回 { cfg, errors }。
+ * errors 非空时 cfg 仍给出(缺省补齐),调用方决定是否以 errors 拒绝。
+ */
+export function normalizeSerialConfig(raw = {}) {
+  const errors = []
+  const s = v => String(v ?? '').trim()
+  const cfg = {
+    mode: MODES.has(s(raw.mode)) ? s(raw.mode) : 'modbus-rtu',
+    path: s(raw.path),
+    baudRate: Number(raw.baudRate) > 0 ? Number(raw.baudRate) : 9600,
+    dataBits: [7, 8].includes(Number(raw.dataBits)) ? Number(raw.dataBits) : 8,
+    stopBits: [1, 2].includes(Number(raw.stopBits)) ? Number(raw.stopBits) : 1,
+    parity: PARITIES.has(s(raw.parity)) ? s(raw.parity) : 'none',
+    unitId: Number(raw.unitId) > 0 ? Math.min(247, Math.floor(Number(raw.unitId))) : 1,
+    register: Number.isFinite(Number(raw.register)) ? Number(raw.register) : 0,
+    registerType: s(raw.registerType) === 'input' ? 'input' : 'holding',
+    dataType: DATA_TYPES.has(s(raw.dataType)) ? s(raw.dataType) : 'float32',
+    byteOrder: BYTE_ORDERS.has(s(raw.byteOrder)) ? s(raw.byteOrder) : 'big',
+    scale: Number.isFinite(Number(raw.scale)) && Number(raw.scale) !== 0 ? Number(raw.scale) : 1,
+    jsonPath: s(raw.jsonPath),
+    /** ascii-line 写模板({v} 替换为数值;行尾 \n 自动补) */
+    writeTemplate: s(raw.writeTemplate),
+    /** ascii-line 数据保鲜窗(超过视为停发,采样返回 null 跳帧,不重复消费陈旧值) */
+    staleMs: Number(raw.staleMs) > 0 ? Number(raw.staleMs) : 30_000,
+    /** 单次串口事务超时(建连/响应共用;半开链路防悬挂) */
+    timeoutMs: Number(raw.timeoutMs) > 0 ? Math.min(10_000, Number(raw.timeoutMs)) : 3000,
+  }
+  if (!cfg.path) errors.push('缺少串口路径 path(Windows 如 COM3,Linux 如 /dev/ttyUSB0)')
+  if (!MODES.has(s(raw.mode)) && s(raw.mode)) errors.push(`mode 非法: ${s(raw.mode)}(仅 modbus-rtu / ascii-line)`)
+  if (cfg.mode === 'modbus-rtu' && raw.register == null) errors.push('modbus-rtu 模式缺少寄存器地址 register(如 40001)')
+  return { cfg, errors }
+}
+
+/** 4xxxx 保持寄存器 → 协议偏移(40001 → 0);3xxxx 输入寄存器同理(与内置 modbus 驱动同规约) */
+export function registerOffset(addr, area) {
+  if (area === 'input') return addr >= 30001 ? addr - 30001 : addr
+  return addr >= 40001 ? addr - 40001 : addr
+}
+
+// ============================================================
+// Modbus RTU 帧(CRC16;诊断/探针与单测用 —— 常规收发走 modbus-serial)
+// ============================================================
+
+/** Modbus CRC16(多项式 0xA001 反射;返回 16 位无符号) */
+export function crc16Modbus(buf) {
+  let crc = 0xFFFF
+  for (const byte of buf) {
+    crc ^= byte & 0xFF
+    for (let i = 0; i < 8; i++) {
+      if (crc & 1) crc = (crc >> 1) ^ 0xA001
+      else crc >>= 1
+    }
+  }
+  return crc & 0xFFFF
+}
+
+/** 构造 RTU 请求帧:addr + func + payload + CRC(lo hi) */
+export function buildRtuFrame(addr, func, payload = []) {
+  const body = Buffer.from([addr & 0xFF, func & 0xFF, ...payload])
+  const crc = crc16Modbus(body)
+  return Buffer.concat([body, Buffer.from([crc & 0xFF, (crc >> 8) & 0xFF])])
+}
+
+/**
+ * 解析 RTU 响应帧(不含地址校验——单从站总线由调用方关注):
+ * 返回 { addr, func, data:Buffer } | { error:'crc'|'short' }
+ */
+export function parseRtuFrame(buf) {
+  if (!buf || buf.length < 4) return { error: 'short' }
+  const crc = buf.readUInt16LE(buf.length - 2)
+  if (crc !== crc16Modbus(buf.subarray(0, buf.length - 2))) return { error: 'crc' }
+  return { addr: buf[0], func: buf[1] & 0x7F, data: buf.subarray(2, buf.length - 2) }
+}
+
+// ============================================================
+// 寄存器字 ↔ 数值(与内置数采 decodeRegisters / 写控 encodeWords 逐字节一致)
+// ============================================================
+
+const hi = x => (x >> 8) & 0xFF
+const lo = x => x & 0xFF
+
+/** 寄存器字序 → 数值(1~2 word;big=ABCD / little=DCBA / wordSwap=CDAB) */
+export function decodeRegisters(data, dataType, byteOrder) {
+  if (dataType === 'int16' || dataType === 'uint16') {
+    const raw = data[0] ?? 0
+    return dataType === 'int16' ? (raw << 16) >> 16 : raw
+  }
+  let b
+  if (byteOrder === 'little') b = [hi(data[1]), lo(data[1]), hi(data[0]), lo(data[0])].reverse()
+  else if (byteOrder === 'wordSwap') b = [hi(data[1]), lo(data[1]), hi(data[0]), lo(data[0])]
+  else b = [hi(data[0]), lo(data[0]), hi(data[1]), lo(data[1])]
+  const buf = Buffer.from(b)
+  if (dataType === 'float32') return buf.readFloatBE(0)
+  if (dataType === 'uint32') return buf.readUInt32BE(0)
+  return buf.readInt32BE(0)
+}
+
+/** 数值 → 寄存器字序(decodeRegisters 的逆;写驱动 FC06/FC16 用) */
+export function encodeWords(raw, dataType, byteOrder) {
+  if (dataType === 'int16' || dataType === 'uint16') return [raw & 0xFFFF]
+  const buf = Buffer.alloc(4)
+  if (dataType === 'float32') buf.writeFloatBE(raw, 0)
+  else if (dataType === 'uint32') buf.writeUInt32BE(raw, 0)
+  else buf.writeInt32BE(raw, 0)
+  const B = [buf[0], buf[1], buf[2], buf[3]]
+  const word = (a, b) => ((a & 0xFF) << 8) | (b & 0xFF)
+  if (byteOrder === 'little') return [word(B[1], B[0]), word(B[3], B[2])]
+  if (byteOrder === 'wordSwap') return [word(B[2], B[3]), word(B[0], B[1])]
+  return [word(B[0], B[1]), word(B[2], B[3])]
+}
+
+// ============================================================
+// 工程量 ↔ 原始值(写控线性映射;与 dcw/drivers.ts 同语义)
+// ============================================================
+
+const num = (v) => {
+  const n = Number(v)
+  return v !== '' && v != null && Number.isFinite(n) ? n : undefined
+}
+
+/** 工程量 → 原始值(未提供 rawMin/rawMax 时直传) */
+export function engToRaw(eng, cfg, domain = { min: 0, max: 100 }) {
+  const rawMin = num(cfg.rawMin)
+  const rawMax = num(cfg.rawMax)
+  if (rawMin === undefined || rawMax === undefined || rawMax === rawMin) return eng
+  const engMin = num(cfg.engMin) ?? domain.min
+  const engMax = num(cfg.engMax) ?? domain.max
+  if (engMax === engMin) return rawMin
+  return rawMin + ((eng - engMin) / (engMax - engMin)) * (rawMax - rawMin)
+}
+
+/** 原始值 → 工程量(engToRaw 的逆;回读换算用) */
+export function rawToEng(raw, cfg, domain = { min: 0, max: 100 }) {
+  const rawMin = num(cfg.rawMin)
+  const rawMax = num(cfg.rawMax)
+  if (rawMin === undefined || rawMax === undefined || rawMax === rawMin) return raw
+  const engMin = num(cfg.engMin) ?? domain.min
+  const engMax = num(cfg.engMax) ?? domain.max
+  if (rawMax === rawMin) return engMin
+  return engMin + ((raw - rawMin) / (rawMax - rawMin)) * (engMax - engMin)
+}
+
+// ============================================================
+// ASCII 行取值(裸数字直取;JSON 按 jsonPath 点分路径,含数组下标)
+// ============================================================
+
+/** 从一行报文提取数值;无法提取返回 null(不抛,采样循环靠 null 跳帧) */
+export function extractLineValue(text, jsonPath) {
+  const trimmed = String(text ?? '').trim()
+  if (!trimmed) return null
+  const direct = Number(trimmed)
+  if (Number.isFinite(direct)) return direct
+  let parsed
+  try {
+    parsed = JSON.parse(trimmed)
+  }
+  catch {
+    return null
+  }
+  const target = jsonPath
+    ? String(jsonPath).split('.').reduce((acc, k) => (acc == null ? undefined : acc[k]), parsed)
+    : parsed
+  const n = typeof target === 'number' ? target : Number(target)
+  return Number.isFinite(n) ? n : null
+}
+
+// ============================================================
+// 通信故障分类(与内置 classifyCommError 同风格;串口特化)
+// ============================================================
+
+export function classifySerialError(err) {
+  const raw = err instanceof Error ? err.message : String(err)
+  const m = raw.toLowerCase()
+  if (/no such file|device not found|file not found|access denied|拒绝访问|找不到/.test(m))
+    return `串口不存在或被占用——检查设备插入/驱动与路径拼写,关闭占用该口的程序(${raw})`
+  if (/timeout|timed out/.test(m))
+    return `串口响应超时——检查波特率/校验位/从站地址与接线(${raw})`
+  if (/crc/.test(m))
+    return `CRC 校验失败——线路干扰或波特率/校验位不匹配(${raw})`
+  if (/illegal|exception|function code/.test(m))
+    return `设备拒绝该操作——功能码或寄存器地址不被支持(${raw})`
+  if (/port is not open|closing|closed/.test(m))
+    return `串口已断开——将自动重建,若持续失败请检查线缆(${raw})`
+  return raw
+}

package/server/plugins-builtin/serial-bridge/rtu.mjs

@@ -0,0 +1,168 @@
+/**
+ * serial-bridge —— Modbus RTU 事务客户端(直接架在 serialport 之上)。
+ *
+ * 为什么不用 modbus-serial 的 connectRTUBuffered:其包装层与 nitro dev 的 worker
+ * isolate 组合下触发 V8 HandleScope 原生崩溃(实测稳定复现,纯 serialport 打开同口
+ * 正常)—— 详见 docs/plugins.md「已知边界」。本类用 lib.mjs 的 CRC16/帧编解码自行
+ * 实现 FC03/FC04/FC06/FC16:连接级队列(drivers.mjs withConn)保证同链路同时只有
+ * 一个事务,故「请求 → 等响应帧」的匹配无需复杂多路复用。
+ *
+ * 帧形态(RTU):
+ *   请求  [addr, func, ...payload, crcLo, crcHi]
+ *   读响应 addr, func, byteCount, data…, crc(8+2×words 字节)
+ *   写响应 FC06 回显 8 字节;FC16 回 [addr, func, offsetHi, offsetLo, countHi, countLo, crc…]
+ *   异常  addr, func|0x80, exceptionCode, crc(5 字节)
+ */
+import { buildRtuFrame, crc16Modbus } from './lib.mjs'
+
+const hi8 = x => (x >> 8) & 0xFF
+const lo8 = x => x & 0xFF
+
+/**
+ * @param {Function} SerialPort serialport 构造器(注入,便于测试)
+ * @param {{ path, baudRate, dataBits, stopBits, parity, unitId, timeoutMs }} cfg
+ */
+export function createRtuClient(SerialPort, cfg) {
+  let port = null
+  let buffer = Buffer.alloc(0)
+  /** 当前在飞事务的收帧器(连接级队列保证至多一个) */
+  let waiter = null
+  let dead = false
+
+  /** 响应帧期望总长(-1 = 还差 byteCount 字节没法判) */
+  function frameLength(func) {
+    if ((func & 0x7F) === 3 || (func & 0x7F) === 4) return -1
+    if ((func & 0x7F) === 6 || (func & 0x7F) === 16) return 8
+    return 0
+  }
+
+  function feed(chunk) {
+    buffer = Buffer.concat([buffer, chunk])
+    if (!waiter) {
+      buffer = Buffer.alloc(0)
+      return
+    }
+    const min = 4
+    if (buffer.length < min) return
+    const func = buffer[1]
+    let need
+    if (func & 0x80) need = 5
+    else {
+      const fixed = frameLength(func)
+      need = fixed >= 0 ? fixed : (buffer.length >= 3 ? 5 + buffer[2] : -1)
+    }
+    if (need < 0 || buffer.length < need) return
+    const frame = buffer.subarray(0, need)
+    buffer = Buffer.from(buffer.subarray(need))
+    const w = waiter
+    waiter = null
+    const crc = frame.readUInt16LE(frame.length - 2)
+    if (crc !== crc16Modbus(frame.subarray(0, frame.length - 2))) {
+      w.reject(new Error('CRC 校验失败(CRC mismatch)'))
+      return
+    }
+    if (frame[0] !== cfg.unitId) {
+      w.reject(new Error(`响应从站地址不匹配(期望 ${cfg.unitId},收到 ${frame[0]})`))
+      return
+    }
+    if (frame[1] & 0x80) {
+      w.reject(new Error(`Modbus 异常响应 exception code=${frame[2]}(功能码 ${frame[1] & 0x7F})`))
+      return
+    }
+    w.resolve(frame)
+  }
+
+  /** 单事务:写请求帧 → 等匹配响应帧(硬超时;连接级队列保证同时至多一个) */
+  function transact(func, payload) {
+    if (dead || !port || !port.isOpen) return Promise.reject(new Error('Port is not open'))
+    return new Promise((resolveP, rejectP) => {
+      const frame = buildRtuFrame(cfg.unitId, func, payload)
+      const timer = setTimeout(() => {
+        waiter = null
+        rejectP(new Error(`Modbus 响应超时(${cfg.timeoutMs}ms)`))
+      }, cfg.timeoutMs)
+      waiter = {
+        resolve: (f) => {
+          clearTimeout(timer)
+          resolveP(f)
+        },
+        reject: (e) => {
+          clearTimeout(timer)
+          rejectP(e)
+        },
+      }
+      buffer = Buffer.alloc(0)
+      port.write(frame, (err) => {
+        if (err) {
+          clearTimeout(timer)
+          waiter = null
+          rejectP(err)
+        }
+      })
+    })
+  }
+
+  function wordsFrom(frame) {
+    const byteCount = frame[2]
+    const out = []
+    for (let i = 0; i < byteCount / 2; i++) out.push(frame.readUInt16BE(3 + i * 2))
+    return out
+  }
+
+  return {
+    /** 打开串口(autoOpen;open/error 事件二选一收敛,硬超时由 cfg.timeoutMs 保护) */
+    open() {
+      return new Promise((resolveP, rejectP) => {
+        port = new SerialPort({
+          path: cfg.path,
+          baudRate: cfg.baudRate,
+          dataBits: cfg.dataBits,
+          stopBits: cfg.stopBits,
+          parity: cfg.parity,
+          autoOpen: true,
+        })
+        const timer = setTimeout(() => rejectP(new Error(`串口打开超时(${cfg.timeoutMs}ms): ${cfg.path}@${cfg.baudRate}`)), cfg.timeoutMs)
+        port.once('open', () => {
+          clearTimeout(timer)
+          resolveP()
+        })
+        port.once('error', (err) => {
+          clearTimeout(timer)
+          rejectP(err)
+        })
+        port.on('data', feed)
+        const markDead = () => void (dead = true)
+        port.on('error', markDead)
+        port.on('close', markDead)
+      })
+    },
+    /** modbus-serial 兼容面(drivers.mjs 零改动):isOpen、setID、读写方法、close */
+    get isOpen() { return Boolean(port && port.isOpen && !dead) },
+    setID() { /* 单连接绑定单从站:unitId 在 cfg 固定 */ },
+    on() { /* 兼容位;端口错误已在内部标记 dead */ },
+    async readHoldingRegisters(offset, length) {
+      const f = await transact(3, [hi8(offset), lo8(offset), hi8(length), lo8(length)])
+      return { data: wordsFrom(f) }
+    },
+    async readInputRegisters(offset, length) {
+      const f = await transact(4, [hi8(offset), lo8(offset), hi8(length), lo8(length)])
+      return { data: wordsFrom(f) }
+    },
+    async writeRegister(offset, value) {
+      await transact(6, [hi8(offset), lo8(offset), hi8(value), lo8(value)])
+      return { address: offset, value }
+    },
+    async writeRegisters(offset, words) {
+      const byteCount = words.length * 2
+      const payload = [hi8(offset), lo8(offset), hi8(words.length), lo8(words.length), byteCount, ...words.flatMap(w => [hi8(w), lo8(w)])]
+      await transact(16, payload)
+      return { address: offset, length: words.length }
+    },
+    close() {
+      return new Promise((resolveP) => {
+        if (!port || !port.isOpen) return resolveP()
+        port.close(() => resolveP())
+      })
+    },
+  }
+}

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

@@ -27,7 +27,7 @@ import { daqRuntimeSettings } from '../settings'
 import { getSystemConfigService } from '../../system-config'
 import { daqKeyFromRef, normalizeDataTransform, normalizeSignalKind, DAQ_DRIVERS, type AepDaqControllerState, type AepDaqFrame, type AepDaqReading, type AepDaqNodeChange, type DaqDriverKind, type DaqNodeView, type DataTransform, type DriverTestResult } from '../../../../shared/daq-protocol'
 import { AppError, ErrorCodes } from '../../../utils/errors'
-import { normalizeDriverKind, resolveDaqDriver, probeDriverAvailability, listPluginDrivers, type DaqFrameSample } from './drivers'
+import { normalizeDriverKind, resolveDaqDriver, probeDriverAvailability, listPluginDrivers, driverCatalog, type DaqFrameSample } from './drivers'
 import { findDaqTemplate } from './daq-templates'
 import { DaqNode } from './daq-node'
 import { DaqNodeRuntime, type DaqRuntimeHost } from './daq-runtime'
@@ -1216,11 +1216,16 @@ class DaqController {
     return this.testDriver(node.driver, node.driverConfig)
   }
 
-  /** 驱动可用性(meta;包缺失 → planned 提示而非硬失败) */
+  /** 驱动可用性(meta;包缺失 → planned 提示而非硬失败;含插件驱动) */
   async driverAvailability(): Promise<Record<string, boolean>> {
     return probeDriverAvailability()
   }
 
+  /** 驱动目录(内置 + 插件自描述合并;前端「添加节点」下拉/动态参数表单数据源) */
+  async driverCatalog(): Promise<ReturnType<typeof driverCatalog>> {
+    return driverCatalog()
+  }
+
   // ---------- 存量迁移(device-twins kind=daq → DaqNode 幂等供给) ----------
 
   /**