agentworkshop 0.7.39 → 0.7.41

package/scripts/seed-walkthrough-fixture.mjs

@@ -0,0 +1,143 @@
+/**
+ * Purpose-built ENGLISH-locale fixture for the IEEE TII Figure 2 walkthrough.
+ *
+ * The shared production instance is full of Chinese-named test data; we must NOT
+ * rename or delete anything. Instead this script creates a small additive fixture
+ * with English entity names via the platform's own REST API, so the four
+ * walkthrough screenshots contain English strings only:
+ *
+ *   - line      "Cast-film line A"
+ *   - DAQ nodes  mock + a real Modbus-TCP node on the PLC simulator, one line
+ *   - device     "Die-head heater" twin, bound by a DCW node with a 150-200 C window
+ *   - agents     English lead + workers on the `omp` harness
+ *   - team       "Cast-film control team" (lead + 2 workers)
+ *
+ * Idempotent: re-running reuses rows with the same names. Prints a JSON summary.
+ *
+ * Usage: NO_PROXY='127.0.0.1,localhost' node scripts/seed-walkthrough-fixture.mjs
+ */
+const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3005'
+
+const login = async (e, p) =>
+  (await (await fetch(`${BASE}/api/users/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ email: e, password: p }) })).json()).data.token
+
+const T = await login('admin@awshop.local', 'admin123')
+
+const api = async (method, path, body) => {
+  const r = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${T}`, ...(body ? { 'content-type': 'application/json' } : {}) },
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  const j = await r.json().catch(() => ({}))
+  if (!r.ok || j.code !== 0) throw new Error(`${method} ${path} -> ${r.status} ${JSON.stringify(j).slice(0, 200)}`)
+  return j.data
+}
+const get = p => api('GET', p)
+const post = (p, b) => api('POST', p, b)
+
+// ── 1. production line ────────────────────────────────────────────────────
+const LINE_NAME = 'Cast-film line A'
+const lines = (await get('/api/workshop/dcw/lines')).lines
+let line = lines.find(l => l.name === LINE_NAME)
+if (!line) line = (await post('/api/workshop/dcw/lines', { name: LINE_NAME, color: '#f4c542' })).line
+console.log(`line    : ${line.id}  ${line.name}`)
+
+// ── 2. DAQ nodes on that line (mock + real Modbus-TCP share one loop) ─────
+const daq = await get('/api/workshop/daq')
+const haveNode = n => daq.nodes.find(x => x.name === n)
+const mkNode = async (spec) => {
+  const existing = haveNode(spec.name)
+  if (existing) return existing
+  return (await post('/api/workshop/daq', { enabled: true, intervalMs: 1000, lineId: line.id, ...spec })).node
+}
+
+const nTemp = await mkNode({
+  name: 'Melt temperature', templateRef: 'daq-temp-tc', driver: 'mock',
+  unit: '\u00B0C', decimals: 1, min: 150, max: 200, warnLow: 155, warnHigh: 195,
+})
+const nSpeed = await mkNode({
+  name: 'Line speed', templateRef: 'daq-line-encoder', driver: 'mock',
+  unit: 'm/min', decimals: 0, min: 280, max: 360, warnLow: 290, warnHigh: 350,
+})
+const nPress = await mkNode({
+  name: 'Melt pressure', templateRef: 'daq-pressure-tx', driver: 'mock',
+  unit: 'MPa', decimals: 2, min: 0.6, max: 1.2, warnLow: 0.65, warnHigh: 1.15,
+})
+// real Modbus-TCP against the PLC simulator's "extruder" slave (melt-temp @ 40001)
+const nModbus = await mkNode({
+  name: 'Die-head temperature', templateRef: 'daq-temp-tc', driver: 'modbus-tcp',
+  unit: '\u00B0C', decimals: 2, min: 0, max: 400, warnLow: 150, warnHigh: 260,
+  driverConfig: { host: '127.0.0.1', port: 16040, unitId: 1, register: 40001, dataType: 'float32', byteOrder: 'big' },
+})
+console.log(`daq     : temp=${nTemp.id} speed=${nSpeed.id} pressure=${nPress.id} modbus=${nModbus.id}`)
+
+// ── 3. device twin + DCW control node with a recipe window ────────────────
+const twins = (await get('/api/workshop/device-twins')).twins
+let twin = twins.find(t => t.name === 'Die-head heater')
+if (!twin) twin = (await post('/api/workshop/device-twins', { name: 'Die-head heater', kind: 'device', controls: ['setpoint'] })).twin
+console.log(`twin    : ${twin.id}  ${twin.name}`)
+
+const dcw = await get('/api/workshop/dcw')
+let dcwNode = dcw.nodes.find(n => n.name === 'Die-head setpoint')
+if (!dcwNode) {
+  dcwNode = (await post('/api/workshop/dcw', {
+    name: 'Die-head setpoint', templateRef: 'dcw-temp-sp', driver: 'mock',
+    unit: '\u00B0C', decimals: 1, min: 150, max: 200,
+    holdIntervalMs: 5000, readIntervalMs: 5000, enabled: true,
+    lineId: line.id, deviceIds: [twin.id],
+  })).node
+}
+console.log(`dcw     : ${dcwNode.id}  ${dcwNode.name}  bound=${twin.id}  window=${dcwNode.min}-${dcwNode.max}`)
+
+// ── 4. English agents + team (one lead, harness-backed workers) ───────────
+const teams0 = await get('/api/workshop/teams')
+let team = teams0.find(t => t.name === 'Cast-film control team')
+if (!team) team = await post('/api/workshop/teams', { name: 'Cast-film control team', description: 'Cast-film process lead plus DAQ and modelling workers.', visibility: 'public' })
+
+const teamId = team.id
+const existingTeam = (await get('/api/workshop/teams')).find(t => t.id === teamId)
+const memberNames = new Set((existingTeam?.members ?? []).map(m => m.name))
+
+const AGENTS = [
+  { name: 'Cast-film process lead', harness: 'omp', role: 'lead' },
+  { name: 'DAQ engineer', harness: 'omp', role: 'worker' },
+  { name: 'Model trainer', harness: 'omp', role: 'worker' },
+]
+for (const a of AGENTS) {
+  if (memberNames.has(a.name)) continue
+  const agent = await post('/api/workshop/agents', { name: a.name, harness: a.harness, visibility: 'public' })
+  await post(`/api/workshop/teams/${teamId}/members`, { agentId: agent.id, role: a.role })
+}
+const finalTeam = (await get('/api/workshop/teams')).find(t => t.id === teamId)
+console.log(`team    : ${teamId}  ${finalTeam.name}  members=${(finalTeam.members ?? []).map(m => `${m.role}:${m.name}:${m.harness}`).join(', ')}`)
+
+// ── 5. start the line so DAQ acquisition is genuinely live ────────────────
+// DAQ sampling is gated on an active per-line batch (recipe run). Without a run
+// the nodes report `offline` and the panel-1 claim "share one acquisition loop"
+// would be untrue. Create a product + recipe carrying one setpoint param and
+// start the line; idempotent via the line's active-run flag.
+const lineStates = (await get('/api/workshop/dcw/lines')).states
+const alreadyRunning = lineStates.find(s => s.lineId === line.id && s.active)
+if (alreadyRunning) {
+  console.log(`run     : already active ${alreadyRunning.runId}`)
+}
+else {
+  const dcwState = await get('/api/workshop/dcw')
+  let product = (dcwState.products ?? []).find(p => p.name === 'Cast-film roll')
+  if (!product) product = (await post('/api/workshop/dcw/products', { name: 'Cast-film roll', lineId: line.id })).product
+  let recipe = (dcwState.recipes ?? []).find(r => r.name === 'Cast-film recipe' && r.lineId === line.id)
+  if (!recipe) {
+    recipe = (await post('/api/workshop/dcw/recipes', {
+      productId: product.id,
+      name: 'Cast-film recipe',
+      description: 'Cast-film line A baseline recipe.',
+      params: [{ nodeId: dcwNode.id, value: 178, min: 150, max: 200 }],
+      daqWindows: [{ nodeId: nTemp.id, min: 150, max: 200 }],
+    })).recipe
+  }
+  await post(`/api/workshop/dcw/lines/${line.id}/start`, { recipeId: recipe.id })
+  console.log(`run     : started with recipe ${recipe.id} (${recipe.name})`)
+}
+
+console.log('\nFIXTURE ' + JSON.stringify({ lineId: line.id, lineName: line.name, modbusNodeId: nModbus.id, dcwNodeId: dcwNode.id, twinId: twin.id, teamId }))

package/scripts/test-plugin-hardening.mjs

@@ -60,6 +60,14 @@ console.log('\n━━━ 3. 稳定性护栏的严重性判定(哪类异常不该
   check('undici UND_ERR_CONNECT_TIMEOUT → upstream', classifyFatalCandidate(err('UND_ERR_CONNECT_TIMEOUT')) === 'upstream')
   check('无 code 但 message 带 ECONNREFUSED → upstream',
     classifyFatalCandidate(new Error('connect ECONNREFUSED 127.0.0.1:1502')) === 'upstream')
+  // 实测事故 2:工业驱动库(Modbus/OPC UA 客户端)超时时只给可读 message、不带 errno code,
+  // 旧实现据此判 fatal → 生产实例运行中 exit 1(平台带着数采/数控一起挂掉)。
+  check('无 code,message "TCP Connection Timed Out" → upstream',
+    classifyFatalCandidate(new Error('TCP Connection Timed Out')) === 'upstream')
+  check('无 code,message "connection timed out" → upstream',
+    classifyFatalCandidate(new Error('connect error: connection timed out')) === 'upstream')
+  check('无 code,message "socket hang up" → upstream',
+    classifyFatalCandidate(new Error('socket hang up')) === 'upstream')
 
   // 其余既有分级不得回退
   check('ECONNRESET(客户端硬断)→ socket', classifyFatalCandidate(err('ECONNRESET')) === 'socket')

package/scripts/test-serial-bridge.mjs

@@ -0,0 +1,418 @@
+/**
+ * 回归测试 —— serial-bridge 串口协议插件(纯协议层 + RTU 事务客户端 + 假端口驱动契约 + 插件入口契约)。
+ * 运行: node scripts/test-serial-bridge.mjs
+ * 退出码: 0 全通过 / 1 有失败
+ *
+ * 无需真实串口硬件:RTU 客户端(rtu.mjs)以假 SerialPort(内存从站应答)驱动,
+ * 驱动工厂(drivers.mjs)以注入 opener 构建,ASCII 行用假行端口;插件入口用桩 ctx
+ * 验证注册契约与 API 路由。
+ */
+import { Buffer } from 'node:buffer'
+import {
+  crc16Modbus,
+  buildRtuFrame,
+  parseRtuFrame,
+  decodeRegisters,
+  encodeWords,
+  engToRaw,
+  rawToEng,
+  extractLineValue,
+  normalizeSerialConfig,
+  registerOffset,
+} from '../server/plugins-builtin/serial-bridge/lib.mjs'
+import { createSerialDrivers } from '../server/plugins-builtin/serial-bridge/drivers.mjs'
+import { createRtuClient } from '../server/plugins-builtin/serial-bridge/rtu.mjs'
+import serialBridge from '../server/plugins-builtin/serial-bridge/index.mjs'
+
+let pass = 0
+let fail = 0
+const check = (name, ok, detail = '') => {
+  if (ok) {
+    pass++
+    console.log(`  PASS  ${name}`)
+    return
+  }
+  fail++
+  console.log(`  FAIL  ${name}${detail ? '  — ' + detail : ''}`)
+}
+const approx = (a, b, eps = 1e-4) => Math.abs(a - b) <= eps
+
+console.log('\n━━━ 1. 纯协议层(lib.mjs) ━━━')
+{
+  // Modbus CRC16 已知向量:01 03 00 00 00 02 → C4 0B(Modbus 官方工具可复算)
+  const crc = crc16Modbus(Buffer.from([0x01, 0x03, 0x00, 0x00, 0x00, 0x02]))
+  check('CRC16 已知向量 01 03 00 00 00 02 → 0xC40B', crc === 0x0BC4, `got 0x${crc.toString(16)}`)
+
+  const frame = buildRtuFrame(1, 3, [0x00, 0x00, 0x00, 0x02])
+  check('RTU 帧构造(CRC lo/hi 序)', frame.length === 8 && frame[6] === 0xC4 && frame[7] === 0x0B, frame.toString('hex'))
+
+  const parsed = parseRtuFrame(frame)
+  check('RTU 帧解析(addr/func/data)', parsed.addr === 1 && parsed.func === 3 && parsed.data.length === 4)
+  const bad = Buffer.from(frame)
+  bad[2] ^= 0xFF
+  check('RTU 帧篡改 → crc 错误', parseRtuFrame(bad).error === 'crc')
+  check('RTU 短帧 → short', parseRtuFrame(Buffer.from([1, 2])).error === 'short')
+
+  // 寄存器编解码:float32 123.456 全字节序 roundtrip(int16 零点用带符号验证)
+  for (const byteOrder of ['big', 'little', 'wordSwap']) {
+    const words = encodeWords(123.456, 'float32', byteOrder)
+    const back = decodeRegisters(words, 'float32', byteOrder)
+    check(`float32 ${byteOrder} 编解码互逆`, approx(words.length === 2 ? back : back, 123.456), `got ${back}`)
+  }
+  const i16 = decodeRegisters([0xFFFE], 'int16', 'big')
+  check('int16 带符号解码 0xFFFE → -2', i16 === -2, `got ${i16}`)
+  const u32 = decodeRegisters(encodeWords(3000000123, 'uint32', 'big'), 'uint32', 'big')
+  check('uint32 3000000123 roundtrip', u32 === 3000000123, `got ${u32}`)
+
+  // 与内置 modbus 驱动同规约:40001 → 偏移 0,30001 → 0
+  check('registerOffset 40001→0 / 30001→0', registerOffset(40001, 'holding') === 0 && registerOffset(30001, 'input') === 0)
+
+  // 工程量↔原始值线性映射(0~27648 ↔ 0~100)
+  const cfg = { rawMin: 0, rawMax: 27648, engMin: 0, engMax: 100 }
+  const raw = engToRaw(50, cfg)
+  check('engToRaw 50 → 13824', approx(raw, 13824, 0.01), `got ${raw}`)
+  check('rawToEng 互逆', approx(rawToEng(raw, cfg), 50, 1e-6))
+  check('未配置量程直传', engToRaw(7.5, {}) === 7.5)
+
+  // ASCII 行取值
+  check('裸数字行', extractLineValue('25.3\n', '') === 25.3)
+  check('JSON 无路径 → null(需配置 jsonPath,取值路径语义显式)', extractLineValue('{"temp": 21.5}', '') === null)
+  check('JSON jsonPath', extractLineValue('{"data":{"temp":21.5}}', 'data.temp') === 21.5)
+  check('JSON 数组下标路径', extractLineValue('{"arr":[1,2,9.5]}', 'arr.2') === 9.5)
+  check('垃圾行 → null(跳帧)', extractLineValue('ERROR OVERHEAT', '') === null)
+  check('空行 → null', extractLineValue('  \n', '') === null)
+
+  // 配置规范化
+  const n1 = normalizeSerialConfig({ path: 'COM3', register: 40001 })
+  check('缺省补齐(mode/baud/type/byteOrder)', n1.errors.length === 0 && n1.cfg.mode === 'modbus-rtu' && n1.cfg.baudRate === 9600 && n1.cfg.dataType === 'float32' && n1.cfg.byteOrder === 'big')
+  const n2 = normalizeSerialConfig({ mode: 'ascii-line' })
+  check('ascii-line 不要求 register,仍要求 path', n2.errors.length === 1 && /path/.test(n2.errors[0]))
+  const n3 = normalizeSerialConfig({ path: 'COM3', register: 1, mode: 'nope' })
+  check('非法 mode 报错且回退 modbus-rtu', n3.cfg.mode === 'modbus-rtu' && n3.errors.some(e => /mode/.test(e)))
+  const n4 = normalizeSerialConfig({ path: 'COM3', register: 40001, scale: 0 })
+  check('scale=0 拒绝(除零保护)', n4.cfg.scale === 1)
+}
+
+console.log('\n━━━ 2. RTU 事务客户端(rtu.mjs,假 SerialPort 从站) ━━━')
+{
+  /** 内存 RTU 从站:以 EventEmitter 风格的假 SerialPort,写请求即回应答帧 */
+  function makeFakeSerialSlave({ unitId = 7, holding = new Map(), corrupt = false, silent = false, badAddr = false } = {}) {
+    const listeners = { data: [], error: [], close: [], open: [] }
+    const port = {
+      isOpen: false,
+      on(ev, fn) { listeners[ev]?.push(fn) },
+      once(ev, fn) { listeners[ev]?.push(fn) },
+      write(buf, cb) {
+        setImmediate(() => cb?.())
+        if (silent) return
+        const req = Buffer.from(buf)
+        const func = req[1]
+        const respAddr = badAddr ? unitId + 1 : unitId
+        let resp
+        if (func === 3 || func === 4) {
+          const offset = req.readUInt16BE(2)
+          const count = req.readUInt16BE(4)
+          const data = Buffer.alloc(count * 2)
+          for (let i = 0; i < count; i++) data.writeUInt16BE(holding.get(offset + i) ?? 0, i * 2)
+          resp = Buffer.concat([Buffer.from([respAddr, func, count * 2]), data])
+        }
+        else if (func === 6) {
+          resp = Buffer.from(req.subarray(0, 6))
+        }
+        else if (func === 16) {
+          resp = Buffer.from([respAddr, func, req[2], req[3], req[4], req[5]])
+        }
+        else {
+          resp = Buffer.from([respAddr, func | 0x80, 1])
+        }
+        if (corrupt) resp[resp.length - 1] ^= 0xFF
+        const c = Buffer.alloc(2)
+        c.writeUInt16LE(crc16Modbus(resp))
+        const frame = Buffer.concat([resp, c])
+        if (corrupt) frame[frame.length - 1] ^= 0xFF
+        setImmediate(() => listeners.data.forEach(fn => fn(frame)))
+      },
+      close(cb) {
+        port.isOpen = false
+        listeners.close.forEach(fn => fn())
+        setImmediate(() => cb?.())
+      },
+    }
+    // autoOpen 语义:构造即异步发 open 事件(与真实 serialport 一致)
+    setImmediate(() => {
+      port.isOpen = true
+      listeners.open.forEach(fn => fn())
+    })
+    return port
+  }
+
+  const regs = new Map([[0, 0x41D4], [1, 0x0000]]) // float32 big 26.5
+  /** rtu.mjs 需要的是「类」(open() 内 new SerialPort(opts));构造器返回实例对象 */
+  const mkClass = (opts = {}) => function FakeSerialPortClass() {
+    return makeFakeSerialSlave({ holding: regs, ...opts })
+  }
+  const mk = (opts = {}) => createRtuClient(mkClass(opts), { path: 'FAKE', baudRate: 9600, dataBits: 8, stopBits: 1, parity: 'none', unitId: 7, timeoutMs: 400 })
+
+  const client = mk()
+  await client.open()
+  check('RTU open 后 isOpen', client.isOpen === true)
+
+  const r1 = await client.readHoldingRegisters(0, 2)
+  check('RTU FC03 读保持寄存器(float32 字序)', r1.data.length === 2 && r1.data[0] === 0x41D4 && r1.data[1] === 0x0000, JSON.stringify(r1))
+
+  const w1 = await client.writeRegister(5, 0xABCD)
+  check('RTU FC06 写单寄存器(回显)', w1.value === 0xABCD, JSON.stringify(w1))
+
+  const w2 = await client.writeRegisters(10, [1, 2, 3])
+  check('RTU FC16 写多寄存器', w2.length === 3, JSON.stringify(w2))
+  await client.close()
+  check('RTU close 后 isOpen=false', client.isOpen === false)
+
+  // 异常帧:专用假从站对一切请求回 func|0x80 + code=2(带合法 CRC)
+  function ExceptionPortClass() {
+    const __l = { data: [], error: [], close: [], open: [] }
+    const port = {
+      isOpen: false,
+      on(ev, fn) { __l[ev].push(fn) },
+      once(ev, fn) { __l[ev].push(fn) },
+      write(buf, cb) {
+        setImmediate(() => cb?.())
+        const body = Buffer.from([7, Buffer.from(buf)[1] | 0x80, 2])
+        const c = Buffer.alloc(2)
+        c.writeUInt16LE(crc16Modbus(body))
+        setImmediate(() => __l.data.forEach(fn => fn(Buffer.concat([body, c]))))
+      },
+      close(cb) { setImmediate(() => cb?.()) },
+    }
+    setImmediate(() => {
+      port.isOpen = true
+      __l.open.forEach(fn => fn())
+    })
+    return port
+  }
+  const exReal = createRtuClient(ExceptionPortClass, { path: 'FAKE', baudRate: 9600, dataBits: 8, stopBits: 1, parity: 'none', unitId: 7, timeoutMs: 400 })
+  await exReal.open()
+  let exErr = null
+  await exReal.readHoldingRegisters(0, 1).catch(e => (exErr = e.message))
+  check('RTU 异常帧 → exception code 错误', exErr?.includes('exception code=2'), exErr)
+
+  const crcClient = mk({ corrupt: true })
+  await crcClient.open()
+  let crcErr = null
+  await crcClient.readHoldingRegisters(0, 1).catch(e => (crcErr = e.message))
+  check('RTU CRC 篡改 → CRC 错误', crcErr?.includes('CRC'), crcErr)
+
+  const addrClient = mk({ badAddr: true })
+  await addrClient.open()
+  let addrErr = null
+  await addrClient.readHoldingRegisters(0, 1).catch(e => (addrErr = e.message))
+  check('RTU 从站地址不匹配 → 报错', addrErr?.includes('从站地址不匹配'), addrErr)
+
+  const silentClient = mk({ silent: true })
+  await silentClient.open()
+  const t0 = Date.now()
+  let timeoutErr = null
+  await silentClient.readHoldingRegisters(0, 1).catch(e => (timeoutErr = e.message))
+  check('RTU 无应答 → 硬超时(250ms)', timeoutErr?.includes('超时') && Date.now() - t0 < 1500, timeoutErr)
+}
+
+console.log('\n━━━ 3. 驱动契约(假端口,免硬件) ━━━')
+{
+  // 内存 Modbus 从站:保持寄存器阵列 + 写镜像
+  function makeFakeRtu() {
+    const holding = new Map()
+    const input = new Map()
+    const client = {
+      isOpen: true,
+      closed: false,
+      setID() {},
+      on() {},
+      async readHoldingRegisters(offset, length) {
+        const out = []
+        for (let i = 0; i < length; i++) out.push(holding.get(offset + i) ?? 0)
+        return { data: out }
+      },
+      async readInputRegisters(offset, length) {
+        const out = []
+        for (let i = 0; i < length; i++) out.push(input.get(offset + i) ?? 0)
+        return { data: out }
+      },
+      async writeRegister(offset, value) { holding.set(offset, value & 0xFFFF) },
+      async writeRegisters(offset, words) { words.forEach((w, i) => holding.set(offset + i, w & 0xFFFF)) },
+      async close() {
+        client.closed = true
+        client.isOpen = false
+      },
+    }
+    client.__holding = holding
+    client.__input = input
+    return client
+  }
+
+  // float32 26.5(0x41D40000)按 big 端写入保持寄存器 0
+  const seedWords = (v) => {
+    const b = Buffer.alloc(4)
+    b.writeFloatBE(v, 0)
+    return [(b[0] << 8) | b[1], (b[2] << 8) | b[3]]
+  }
+
+  const fake = makeFakeRtu()
+  const w = seedWords(26.5)
+  fake.__holding.set(0, w[0])
+  fake.__holding.set(1, w[1])
+
+  const linePort = {
+    aliveRet: true,
+    alive() { return this.aliveRet },
+    latestRet: { text: '25.3', at: Date.now() },
+    latest() { return this.latestRet },
+    written: [],
+    async writeLine(line) { this.written.push(line) },
+    async close() {},
+  }
+
+  const factory = createSerialDrivers({
+    openRtu: async () => fake,
+    openLine: async () => linePort,
+    isAvailable: () => true,
+    log: { warn: () => {} },
+  })
+
+  const cfgRtu = { mode: 'modbus-rtu', path: 'COM9', baudRate: 19200, register: 40001, dataType: 'float32', byteOrder: 'big', scale: 1 }
+  const v1 = await factory.readDriver.sample({ driverConfig: cfgRtu })
+  check('sample: RTU float32 读数', approx(v1, 26.5), `got ${v1}`)
+
+  const cfgRtuScaled = { ...cfgRtu, scale: 0.1 }
+  const v2 = await factory.readDriver.sample({ driverConfig: cfgRtuScaled })
+  check('sample: 缩放系数生效(26.5×0.1)', approx(v2, 2.65), `got ${v2}`)
+
+  const cfgInput = { ...cfgRtu, registerType: 'input', register: 30001 }
+  fake.__input.set(0, 100)
+  const v3 = await factory.readDriver.sample({ driverConfig: { ...cfgInput, dataType: 'uint16' } })
+  check('sample: 输入寄存器(3x)FC04', v3 === 100, `got ${v3}`)
+
+  const cfgAscii = { mode: 'ascii-line', path: 'COM10', baudRate: 9600 }
+  const v4 = await factory.readDriver.sample({ driverConfig: cfgAscii })
+  check('sample: ASCII 行取值', v4 === 25.3, `got ${v4}`)
+
+  linePort.latestRet = { text: '{"data":{"t":-3.5}}', at: Date.now() }
+  const v5 = await factory.readDriver.sample({ driverConfig: { ...cfgAscii, jsonPath: 'data.t' } })
+  check('sample: ASCII JSON 路径 + 负值', v5 === -3.5, `got ${v5}`)
+
+  linePort.latestRet = { text: '99', at: Date.now() - 60_000 }
+  const v6 = await factory.readDriver.sample({ driverConfig: { ...cfgAscii, staleMs: 30000 } })
+  check('sample: 保鲜窗外 → null 跳帧', v6 === null, `got ${v6}`)
+
+  // 写 + 回读校验(0~27648 ↔ 0~100 映射)
+  const cfgWrite = { mode: 'modbus-rtu', path: 'COM9', baudRate: 19200, register: 40001, dataType: 'uint16', byteOrder: 'big', rawMin: 0, rawMax: 27648, engMin: 0, engMax: 100 }
+  const wr1 = await factory.writeDriver.write({ eng: 50, tolerance: 0.5, domain: { min: 0, max: 100 }, driverConfig: cfgWrite })
+  check('write: 写+回读一致 ACK', wr1.ok === true && approx(wr1.readback, 50, 0.5), JSON.stringify(wr1))
+
+  // 从站写入失真(写入值 ≠ 回读值,如从站寄存器故障)→ 回读不一致 → 拒绝 ACK
+  const corruptRtu = makeFakeRtu()
+  corruptRtu.writeRegister = async function (offset, value) {
+    this.__holding.set(offset, (value + 1000) & 0xFFFF)
+  }
+  corruptRtu.writeRegisters = async function (offset, words) {
+    words.forEach((w, i) => this.__holding.set(offset + i, (w + 1000) & 0xFFFF))
+  }
+  const corruptFactory = createSerialDrivers({
+    openRtu: async () => corruptRtu,
+    openLine: async () => linePort,
+    isAvailable: () => true,
+    log: { warn: () => {} },
+  })
+  const wr2 = await corruptFactory.writeDriver.write({ eng: 50, tolerance: 0.5, domain: { min: 0, max: 100 }, driverConfig: cfgWrite })
+  check('write: 回读不一致 → 拒绝', wr2.ok === false && /不一致/.test(wr2.message), JSON.stringify(wr2))
+  await corruptFactory.closeAll()
+
+  // ASCII 写模板下行
+  const wr3 = await factory.writeDriver.write({ eng: 42.5, tolerance: 0.5, domain: { min: 0, max: 100 }, driverConfig: { mode: 'ascii-line', path: 'COM10', writeTemplate: 'SET {v}' } })
+  check('write: ASCII 模板下行(无回读诚实标注)', wr3.ok === true && linePort.written[0] === 'SET 42.5' && wr3.readback === null, JSON.stringify({ wr3, written: linePort.written }))
+
+  // 连接测试
+  const t1 = await factory.readDriver.test(cfgRtu)
+  check('test: 通过并带回读数', t1.ok === true && t1.sampleValue != null, JSON.stringify(t1))
+  const t2 = await factory.readDriver.test({ mode: 'modbus-rtu', path: '' })
+  check('test: 缺 path 给可读错误', t2.ok === false && /path/.test(t2.message))
+  const t3 = await factory.writeDriver.test(cfgWrite)
+  check('test: 写驱动测试不触发真实写', t3.ok === true, JSON.stringify(t3))
+
+  // meta 自描述(前端动态表单数据源)
+  check('读驱动 meta.configFields 非空', Array.isArray(factory.readDriver.meta?.configFields) && factory.readDriver.meta.configFields.length >= 10)
+  check('写驱动 meta.configFields 含量程映射', factory.writeDriver.meta.configFields.some(f => f.key === 'rawMax'))
+
+  // 串行队列:前一事务阻塞时后续排队(契约:同一物理链路不并发)
+  let busy = 0
+  let maxBusy = 0
+  const slowFactory = createSerialDrivers({
+    openRtu: async () => ({
+      isOpen: true,
+      setID() {},
+      on() {},
+      async readHoldingRegisters() {
+        busy++
+        maxBusy = Math.max(maxBusy, busy)
+        await new Promise(r => setTimeout(r, 20))
+        busy--
+        return { data: [1, 2] }
+      },
+      async close() {},
+    }),
+    openLine: async () => linePort,
+    isAvailable: () => true,
+    log: { warn: () => {} },
+  })
+  const cfgSlow = { mode: 'modbus-rtu', path: 'COMX', register: 40001 }
+  await Promise.all([
+    slowFactory.readDriver.sample({ driverConfig: cfgSlow }),
+    slowFactory.readDriver.sample({ driverConfig: cfgSlow }),
+    slowFactory.readDriver.sample({ driverConfig: cfgSlow }),
+  ])
+  check('同链路事务串行化(无并发读)', maxBusy === 1, `maxBusy=${maxBusy}`)
+
+  await factory.closeAll()
+  check('closeAll 关闭串口连接', fake.closed === true)
+}
+
+console.log('\n━━━ 3. 插件入口契约(index.mjs + 桩 ctx) ━━━')
+{
+  const registered = { daqDrivers: [], dcwDrivers: [], routes: new Map(), tools: [], disposed: [] }
+  const ctx = {
+    name: 'serial-bridge',
+    logger: { info: () => {}, warn: m => console.warn('    [log]', m), error: () => {} },
+    daq: {
+      registerDriver: d => registered.daqDrivers.push(d),
+      nodes: async () => [{ id: 'n1', name: '炉温', driver: 'serial', enabled: true, lineId: 'L1', driverConfig: { path: 'COM3' } }],
+    },
+    dcw: { registerWriteDriver: d => registered.dcwDrivers.push(d) },
+    route: (method, path, handler) => registered.routes.set(`${method} ${path}`, handler),
+    omp: { registerTool: t => registered.tools.push(t) },
+    onDispose: fn => registered.disposed.push(fn),
+    http: {},
+  }
+  await serialBridge.setup(ctx)
+
+  check('数采读驱动已注册(kind=serial)', registered.daqDrivers.length === 1 && registered.daqDrivers[0].kind === 'serial')
+  check('写控驱动已注册(kind=serial)', registered.dcwDrivers.length === 1 && registered.dcwDrivers[0].kind === 'serial')
+  check('驱动 available 探测可用(serialport 已安装)', await registered.daqDrivers[0].available() === true)
+  check('API 路由已注册(health/ports/probe)', ['GET /health', 'GET /ports', 'POST /probe'].every(k => registered.routes.has(k)))
+  check('omp 工具已注册(serial_ports)', registered.tools.length === 1 && registered.tools[0].name === 'serial_ports')
+  check('dispose 已登记(串口回收)', registered.disposed.length >= 1)
+
+  const health = await registered.routes.get('GET /health')()
+  check('GET /health:可用性 + 串口节点识别', health.available === true && health.readNodes.length === 1 && health.readNodes[0].path === 'COM3', JSON.stringify(health))
+  const ports = await registered.routes.get('GET /ports')()
+  check('GET /ports:系统串口枚举(免硬件)', ports.success === true && Array.isArray(ports.ports), JSON.stringify(ports).slice(0, 120))
+  const probe1 = await registered.routes.get('POST /probe')({ awBody: { mode: 'modbus-rtu' } })
+  check('POST /probe:缺参数给可读错误', probe1.success === false && /path/i.test(probe1.error))
+  const probe2 = await registered.routes.get('POST /probe')({ awBody: { mode: 'ascii-line', path: 'COM_NOT_EXIST_42', timeoutMs: 800 } })
+  check('POST /probe:不存在的串口给可行动诊断', probe2.success === true && probe2.ok === false && /串口/.test(probe2.message), JSON.stringify(probe2))
+
+  const tool = registered.tools[0]
+  const r = await tool.handler({})
+  check('serial_ports 工具返回诊断文本', r.text.includes('可用性') && r.text.includes('炉温'), r.text)
+}
+
+console.log(`\n━━━ 结果: ${pass} 通过 / ${fail} 失败 ━━━`)
+process.exit(fail ? 1 : 0)

package/scripts/ui/admin-shots.mjs

@@ -0,0 +1,46 @@
+/**
+ * 以 **admin 账号** 登录并给数采 / 数控 / 数字孪生出图。
+ * 与 lib.mjs 的视觉走查账号(visual)区分:admin 是文档里写的管理员账号,
+ * 能看见全量节点与全部产线;演示工作区由 scripts/ui/seed-admin.mjs 准备。
+ */
+import { launch, openPage, gotoReady } from './lib.mjs'
+import fs from 'node:fs'
+
+const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3021'
+const OUT = process.env.AW_OUT ?? '.e2e-shots/admin'
+fs.mkdirSync(OUT, { recursive: true })
+
+const loginRes = await fetch(BASE + '/api/users/login', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ email: 'admin@awshop.local', password: 'admin123' }),
+})
+const login = await loginRes.json()
+if (login.code !== 0) throw new Error('admin 登录失败: ' + JSON.stringify(login).slice(0, 200))
+const token = login.data.token
+console.log('登录成功:', login.data.user.name, '(' + login.data.user.role + ')')
+
+const browser = await launch()
+const routes = [
+  { path: '/', name: '01-dashboard', wait: 9000 },
+  { path: '/daq', name: '02-daq', wait: 12000 },
+  { path: '/dcw', name: '03-dcw', wait: 9000 },
+  { path: '/town', name: '04-town', wait: 16000 },
+  { path: '/monitor', name: '05-monitor', wait: 7000 },
+]
+for (const r of routes) {
+  const page = await openPage(browser, { token, dark: true, width: 1440, height: 900, deviceScaleFactor: 2 })
+  const errs = []
+  page.on('pageerror', e => errs.push(String(e.message).slice(0, 120)))
+  await gotoReady(page, r.path, { wait: r.wait })
+  const file = OUT + '/' + r.name + '.png'
+  await page.screenshot({ path: file })
+  const info = await page.evaluate(() => ({
+    nodes: document.querySelectorAll('*').length,
+    text: document.body.innerText.replace(/\s+/g, ' ').slice(0, 120),
+  }))
+  console.log('  ok ' + r.name.padEnd(16) + ' dom=' + String(info.nodes).padStart(6) + ' errs=' + errs.length)
+  await page.close()
+}
+await browser.close()
+console.log('->', OUT)