agentworkshop 0.7.44 → 0.7.46

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

@@ -0,0 +1,164 @@
+/**
+ * DaqControllerSweepAlarms —— 巡检 / 运行时同步 / 告警处理与确认
+ * (拆分层,承 DaqControllerIngest;方法体与原文件逐行一致)
+ */
+import { DaqControllerIngest } from './ingest'
+import type { DaqRuntimeHost } from '../daq-runtime'
+import { AppError } from '../../../../utils/errors'
+import type { DaqNode } from '../daq-node'
+import { DaqNodeRuntime } from '../daq-runtime'
+import { SWEEP_MAX_CONCURRENCY, log } from './helpers'
+import { getDaqHostPorts } from '../host-ports'
+import { getOps, recordOps } from '../../ops/ops'
+import { newAlarmId, notifyAlarm } from '../alarm-notify'
+
+export abstract class DaqControllerSweepAlarms extends DaqControllerIngest {
+  /** 网关统一调度:250ms 扫描,到期判定与互斥由各运行时私有节拍自治(单节点慢/停不波及邻居)。
+   *  产线门控:未选定配方(无活动 LineRun)不执行采集 —— 采样与实时下发均由配方驱动。 */
+  protected sweep(): void {
+    if (!this.pipelineReady || !this.running) return
+    const host = getDaqHostPorts()
+    if (!host || !host.lineRun.hasAnyActiveRun()) return
+    // 在飞闸门:上一拍未消化的并发额度不叠加(避免积压 tick 雪崩)
+    const budget = SWEEP_MAX_CONCURRENCY - this.samplingInFlight
+    if (budget <= 0) return
+    const now = Date.now()
+    const defs = this.runtimeDefaults()
+    const rts = [...this.runtimes.values()]
+    const total = rts.length
+    if (!total) return
+    let started = 0
+    let examined = 0
+    // 轮转游标 + 到期预判:派发额度有限时,固定从表头遍历会让表尾节点永久饿死
+    // (新入表节点排在最后 → 永远轮不到)。游标保证有限拍内覆盖全表,isDue 保证
+    // 未到期节点不占用额度(否则表头节点每拍吃满额度,即便它们无样本可采)。
+    for (let i = 0; i < total && started < budget; i++) {
+      const rt = rts[(this.sweepCursor + i) % total]!
+      examined = i + 1
+      // 逐产线门控:节点只在其所属产线的活动批次窗口内采集(lineId 空 = 未分配,不采集)
+      if (!host.lineRun.activeRun(rt.node.lineId)) continue
+      if (!rt.isDue(now, defs)) continue
+      this.samplingInFlight += 1
+      started += 1
+      void rt.tick(now).catch(() => { /* 单节点采样异常已在 runtime 内隔离 */ })
+        .finally(() => { this.samplingInFlight -= 1 })
+    }
+    this.sweepCursor = (this.sweepCursor + examined) % total
+  }
+
+  /** 产线停止:该产线全部节点置 offline(开跑后由采样自然恢复) */
+  markLineOffline(lineId: string): void {
+    for (const n of this.repo.all()) {
+      if (n.enabled && n.lineId === lineId) n.state = 'offline'
+    }
+    this.emitController()
+  }
+
+  /** 运行时注册表对账(仓库为权威:增删节点/启动即对齐;返回新建的运行时) */
+  protected syncRuntimes(): void {
+    const live = new Set<string>()
+    for (const node of this.repo.all()) {
+      live.add(node.id)
+      if (!this.runtimes.has(node.id)) {
+        this.runtimes.set(node.id, new DaqNodeRuntime(node, this.host))
+      }
+    }
+    for (const id of [...this.runtimes.keys()]) {
+      if (!live.has(id)) this.runtimes.delete(id)
+    }
+  }
+
+  /** runtime host:网关注入的服务面(采样/入队/管线/告警/全局缺省) */
+  protected host: DaqRuntimeHost = {
+    defaults: () => this.runtimeDefaults(),
+    sample: (node, now) => this.sampleNode(node, now),
+    publishSample: env => this.publishSample(env),
+    ingest: (node, env, allowPublish) => this.ingestNode(node, env, allowPublish),
+    broadcastError: (node, message) => this.broadcastDriverError(node, message),
+    onAlarm: (node, value, rule, threshold) => this.handleAlarm(node, value, rule, threshold),
+    onAlarmRecover: (node, value) => this.handleAlarmRecover(node, value),
+    recipeWindowFor: node => this.recipeDaqWindowFor(node),
+  }
+
+  // ---------- S5:报警持久化/外送/确认 ----------
+
+  /** 累计报警次数(R4 指标暴露) */
+  alarmsRaised = 0
+
+  /** alarm 进入沿:落库(同节点同量未确认幂等)→ WS 广播 → webhook 外送;失败绝不影响采集。
+   *  metricKey:帧派生指标告警的键(模板 metrics 规则;缺省 = 模板 key,标量越限) */
+  protected handleAlarm(node: DaqNode, value: number, rule: 'lt-min' | 'gt-max', threshold: number, metricKey?: string): void {
+    this.alarmsRaised++
+    const repo = getOps()?.alarmEvents
+    let id = newAlarmId()
+    const createdAt = new Date().toISOString()
+    const metric = metricKey ?? node.templateKey
+    if (repo) {
+      try {
+        const raised = repo.raise({
+          id, nodeId: node.id, nodeName: node.name, metric,
+          value, rule, threshold, createdAt,
+        })
+        if (!raised) id = '' // 已有同源未确认报警:不重复广播/外送
+      }
+      catch (err) {
+        log.error('[daq-alarm] 报警落库失败(不影响采集):', err instanceof Error ? err.message : err)
+      }
+    }
+    if (!id) return
+    const payload = {
+      id, nodeId: node.id, nodeName: node.name, metric,
+      value, rule, threshold, escalation: 0, createdAt,
+    }
+    this.broadcast?.('daq.alarm', payload)
+    notifyAlarm(payload)
+    // 运维日志:越限告警入实时事件轨(恢复/详情在告警面板与日志管理)
+    const zh = rule === 'gt-max' ? '高于上限' : '低于下限'
+    recordOps({
+      actor: 'system',
+      actorName: 'system',
+      actorKind: 'system',
+      action: 'daq.alarm.raise',
+      kind: 'alarm',
+      targetKind: 'daq-node',
+      targetId: node.id,
+      summary: `告警:「${node.name}」${metric} ${zh}阈值 ${threshold}(当前 ${value})`,
+      lineId: node.lineId ?? '',
+      detail: { alarmId: id, metric, value, rule, threshold },
+    })
+  }
+
+  /** alarm 恢复沿:广播恢复(报警保持 open 待人工 ack) */
+  protected handleAlarmRecover(node: DaqNode, value: number): void {
+    this.broadcast?.('daq.alarm.changed', { nodeId: node.id, nodeName: node.name, recovered: true, value, at: new Date().toISOString() })
+  }
+
+  /** 报警确认(HITL 闭环的人为一步;幂等:已确认返回 false) */
+  ackAlarm(id: string, byUserId: string, byName: string): boolean {
+    const repo = getOps()?.alarmEvents
+    if (!repo) throw new AppError(503, 'UNAVAILABLE', '报警持久化未就绪')
+    const ok = repo.ack(id, byUserId, byName, new Date().toISOString())
+    if (ok) {
+      this.broadcast?.('daq.alarm.changed', { id, ackedBy: byName, ackedAt: new Date().toISOString() })
+      recordOps({
+        actor: byUserId,
+        actorName: byName,
+        actorKind: 'user',
+        action: 'daq.alarm.ack',
+        kind: 'alarm',
+        targetKind: 'alarm',
+        targetId: id,
+        summary: `确认报警 ${id}(处理完毕,移出实时告警)`,
+      })
+    }
+    return ok
+  }
+
+  listAlarms(scope: 'open' | 'all', limit = 100) {
+    const repo = getOps()?.alarmEvents
+    if (!repo) return []
+    return scope === 'open' ? repo.listOpen(limit) : repo.list(limit)
+  }
+
+  // ---------- 消费者:队列帧 → 存储/广播/回写 ----------
+}

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

@@ -0,0 +1,138 @@
+/**
+ * DaqControllerTsdbTwin —— TSDB 落库 / 孪生遥测回写
+ * (拆分层,承 DaqControllerSweepAlarms;方法体与原文件逐行一致)
+ */
+import { DaqControllerSweepAlarms } from './sweep-alarms'
+import type { DaqSampleEnvelope } from '../bus/queue-port'
+import type { LruLike } from './types'
+import type { DaqNode } from '../daq-node'
+import { LruMap } from '@/shared/lru.mjs'
+import { TSDB_WRITE_RETRIES, log } from './helpers'
+import { findDaqTemplate } from '../daq-templates'
+import { getDaqHostPorts } from '../host-ports'
+import { getTsdb } from '../storage'
+
+export abstract class DaqControllerTsdbTwin extends DaqControllerSweepAlarms {
+  /** 网关消费泵:队列帧按节点分发回其运行时(乱序防御/状态派生/下发门控在 runtime) */
+  protected onSampleFromQueue(env: DaqSampleEnvelope): void {
+    this.consumedCount++
+    const rt = this.runtimes.get(env.nodeId)
+    if (!rt) return
+    if (rt.onSample(env) === 'late') this.lateDropped++
+  }
+
+  /** 单 in-flight 写 + 有限重试:写库中攒批继续,失败保留批退避重试,耗尽丢弃并计数 */
+  protected async flushTsdb(): Promise<void> {
+    if (this.tsdbWriting) return
+    this.tsdbWriting = true
+    try {
+      while (this.tsdbBuffer.length > 0) {
+        const batch = this.tsdbBuffer.splice(0, this.tsdbBuffer.length)
+        let ok = false
+        for (let attempt = 0; attempt < TSDB_WRITE_RETRIES && !ok; attempt++) {
+          try {
+            await getTsdb().writeSamples(batch)
+            this.storedCount += batch.length
+            ok = true
+          }
+          catch (err) {
+            if (attempt === TSDB_WRITE_RETRIES - 1) {
+              this.tsdbDropped += batch.length
+              log.error('[daq] 时序库写入失败(已重试,丢弃计数):', err instanceof Error ? err.message : err)
+            }
+            else {
+              await new Promise(r => setTimeout(r, 500 * (attempt + 1)))
+            }
+          }
+        }
+      }
+      // 帧批(v2:daq_frames;与样本同窗同重试语义)
+      // drainFrames 一次性取走并清空索引 —— 索引与缓冲必须同生命周期,否则查询会命中已刷盘的行
+      let pendingFrames = this.drainFrames()
+      while (pendingFrames.length > 0) {
+        const batch = pendingFrames
+        let ok = false
+        for (let attempt = 0; attempt < TSDB_WRITE_RETRIES && !ok; attempt++) {
+          try {
+            await getTsdb().writeFrames(batch)
+            this.framesStored += batch.length
+            ok = true
+          }
+          catch (err) {
+            if (attempt === TSDB_WRITE_RETRIES - 1) {
+              this.tsdbDropped += batch.length
+              log.error('[daq] 帧写入失败(已重试,丢弃计数):', err instanceof Error ? err.message : err)
+            }
+            else {
+              await new Promise(r => setTimeout(r, 500 * (attempt + 1)))
+            }
+          }
+        }
+        pendingFrames = this.drainFrames()
+      }
+    }
+    finally {
+      this.tsdbWriting = false
+      // 尾批自愈:flush 期间新样本/帧到达时 schedule 被跳过(tsdbWriting 守卫),
+      // 若此处不留 timer,停线后的残余批次将无定时器可触发,驻留内存直至进程重启
+      if (this.tsdbBuffer.length > 0 || this.frameBuffer.length > 0) this.scheduleTsdbFlush()
+    }
+  }
+
+  /** 绑定设备端到端回写:通道值进入 DeviceTwin.telemetry(键名 = 模板 telemetryKey 数据,缺省 templateKey);
+   *  状态随行:节点 alarm 派生自用户设置的量程/预警带(数据驱动),透传给孪生而非让孪生按硬编码阈值猜 */
+  protected pendingBackfill = new Map<string, Record<string, number | string | boolean>>()
+
+  /** 同绑定 siblings 缓存(1s TTL):回写热路径不再逐样本全量 scan,O(N²)→O(N)/周期。
+   *  用有界 LRU 而非「超 500 整体 clear()」——后者会造成周期性全量缓存穿透。 */
+  protected siblingsCache: LruLike<string, { at: number, list: DaqNode[] }> = new LruMap(500)
+
+  protected siblingsOf(bindingId: string): DaqNode[] {
+    const hit = this.siblingsCache.get(bindingId)
+    if (hit && Date.now() - hit.at < 1000) return hit.list
+    const list = this.repo.all().filter(n => n.deviceIds.includes(bindingId))
+    this.siblingsCache.set(bindingId, { at: Date.now(), list })
+    return list
+  }
+
+  protected writeBackTelemetry(node: DaqNode): void {
+    if (node.deviceIds.length === 0 || node.value == null) return
+    const host = getDaqHostPorts()
+    if (!host) return // 端口未装配(边缘独立/装配前):不攒积压,直接跳过回写
+    const key = findDaqTemplate(node.templateKey)?.telemetryKey ?? node.templateKey
+    // 多对多绑定:向每台绑定设备回写通道值;同设备多节点取最严重节点态
+    // (alarm > warn > ok/offline),避免"最近写者定态"抖动
+    for (const deviceId of node.deviceIds) {
+      const siblings = this.siblingsOf(deviceId)
+      const worst = siblings.some(n => n.state === 'alarm')
+        ? 'alarm'
+        : siblings.some(n => n.state === 'warn') ? 'warn' : 'ok'
+      const acc = this.pendingBackfill.get(deviceId) ?? {}
+      acc[key] = node.value
+      this.pendingBackfill.set(deviceId, acc)
+      const res = host.telemetry.applyTelemetry(deviceId, acc, worst)
+      if (!res.ok) {
+        // 目标设备已被删除:从本节点解绑该设备(其余绑定保留),链路自愈
+        this.pendingBackfill.delete(deviceId)
+        node.deviceIds = node.deviceIds.filter(d => d !== deviceId)
+        node.deviceBindingId = node.deviceIds[0] ?? null
+        this.repo.flushNow()
+        this.emitNodeChanged('updated', node)
+        continue
+      }
+      this.pendingBackfill.delete(deviceId)
+      if (res.twinId) this.pushTwinTelemetry(res.twinId)
+    }
+  }
+
+  /** 遥测 WS 推送(1s/设备节流):孪生状态/遥测事件化直推,前端全量轮询降级为断线兜底 */
+  protected twinPushAt = new Map<string, number>()
+
+  protected pushTwinTelemetry(twinId: string): void {
+    const now = Date.now()
+    if (now - (this.twinPushAt.get(twinId) ?? 0) < 1000) return
+    this.twinPushAt.set(twinId, now)
+    const payload = getDaqHostPorts()?.telemetry.scenePayload(twinId)
+    if (payload) this.broadcast?.('device.updated', payload)
+  }
+}

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

@@ -0,0 +1,68 @@
+/**
+ * DaqController 的依赖类型与对外 DTO(原 server/services/workshop/daq/daq-controller.ts 顶部模块级类型声明)。纯类型。
+ */
+import type { DaqDriverKind, DataTransform } from '../../../../../shared/daq-protocol'
+
+export interface DaqCreateInput {
+  templateRef?: string
+  name?: string
+  driver?: DaqDriverKind
+  driverConfig?: Record<string, string | number | boolean>
+  /** 数据语义标定钩子(decoder) */
+  transform?: DataTransform
+  unit?: string
+  decimals?: number
+  min?: number
+  max?: number
+  warnLow?: number | null
+  warnHigh?: number | null
+  intervalMs?: number | null
+  /** WS 实时下发间隔(null=跟随全局;0=每帧) */
+  publishIntervalMs?: number | null
+  enabled?: boolean
+  posX?: number
+  posZ?: number
+  /** 所属产线('' = 未分配) */
+  lineId?: string
+  /** 节点级采集语义备注(覆盖模板) */
+  semantics?: string
+  deviceBindingId?: string | null
+}
+
+export interface DaqPatchInput {
+  name?: string
+  driver?: DaqDriverKind
+  driverConfig?: Record<string, string | number | boolean>
+  /** 数据语义标定钩子(decoder) */
+  transform?: DataTransform
+  unit?: string
+  decimals?: number
+  min?: number
+  max?: number
+  warnLow?: number | null
+  warnHigh?: number | null
+  intervalMs?: number | null
+  /** WS 实时下发间隔(null=跟随全局;0=每帧) */
+  publishIntervalMs?: number | null
+  enabled?: boolean
+  posX?: number
+  posZ?: number
+  /** 所属产线('' = 未分配;采集门控按产线) */
+  lineId?: string
+  /** 节点级采集语义备注(覆盖模板) */
+  semantics?: string
+}
+
+export type BroadcastFn = (type: string, payload: unknown) => void
+
+/** 有界 LRU 的最小泛型面:shared/lru.mjs 是 allowJs 推断出的**非泛型**类(JS 里没有 @template),
+ *  直接 `new LruMap<K, V>()` 无处安放类型参数。这里按实际使用面(get/set/delete/size)声明键值类型,
+ *  调用点即可拿到准确的读写类型;运行时仍是同一个 LruMap(纯类型声明,零运行时差异)。 */
+export interface LruLike<K, V> {
+  readonly size: number
+  get(key: K): V | undefined
+  set(key: K, value: V): unknown
+  delete(key: K): unknown
+}
+
+/** TSDB 批量写窗口(ms):消费端攒批再落盘 */

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

@@ -0,0 +1,84 @@
+/**
+ * DaqControllerViews —— 视图投影 / 状态与广播装配 / 队列重挂
+ * (拆分层,承 DaqControllerTsdbTwin;方法体与原文件逐行一致)
+ */
+import { DaqControllerTsdbTwin } from './tsdb-twin'
+import type { AepDaqControllerState, AepDaqNodeChange, DaqNodeView } from '../../../../../shared/daq-protocol'
+import type { BroadcastFn } from './types'
+import type { DaqNode } from '../daq-node'
+import { g_queueLost } from './helpers'
+import { getDaqQueue } from '../bus'
+import { getTsdb, tsdbReady } from '../storage'
+
+export abstract class DaqControllerViews extends DaqControllerTsdbTwin {
+  protected emitNodeChanged(op: AepDaqNodeChange['op'], node: DaqNode | null): void {
+    const payload: AepDaqNodeChange = { op, node: node ? node.toView() : null }
+    this.broadcast?.('daq.node.changed', payload)
+  }
+
+  protected emitController(): void {
+    this.broadcast?.('daq.controller', this.controllerState())
+  }
+
+  /** ws.ts 的 broadcastSceneEvent 在此装配(daq 路由模块加载时调用一次) */
+  setBroadcast(fn: BroadcastFn | null): void {
+    this.broadcast = fn
+  }
+
+  /** minIntervalMs / alarmsRaised / framesStored 都是本方法**实际返回**的字段,但 AepDaqControllerState
+   *  未收录(协议类型与实现漂移):minIntervalMs 被前端 useDaqStream 消费,alarmsRaised 被
+   *  server/api/metrics.ts 消费(framesStored 供管线指标展示)。这里按实现补齐返回面 —— 见报告。 */
+  controllerState(): AepDaqControllerState & { minIntervalMs: number, alarmsRaised: number, framesStored: number, produced?: number, consumed?: number, dropped?: number, samplesStored?: number, tsdbDropped?: number } {
+    // 丢弃 = 队列层真实丢弃(inproc 拥塞/mqtt 断连)+ 消费侧乱序迟到帧(诚实可见)
+    const queueLost = g_queueLost()
+    // 单次遍历(hardening PERF-1):status 高频路径不再对全表多次 all()
+    const nodes = this.repo.all()
+    return {
+      running: this.running,
+      defaultIntervalMs: this.defaultIntervalMs,
+      minIntervalMs: this.minIntervalMs,
+      defaultPublishIntervalMs: this.defaultPublishIntervalMs,
+      minPublishIntervalMs: this.minPublishIntervalMs,
+      queryDisplayIntervalMs: this.queryDisplayIntervalMs,
+      minQueryDisplayIntervalMs: this.minQueryDisplayIntervalMs,
+      nodesTotal: nodes.length,
+      nodesOnline: this.running ? nodes.filter(n => n.enabled).length : 0,
+      produced: this.producedCount,
+      consumed: this.consumedCount,
+      dropped: Math.max(0, this.producedCount - this.consumedCount) + queueLost + this.lateDropped,
+      samplesStored: this.storedCount,
+      tsdbDropped: this.tsdbDropped,
+      alarmsRaised: this.alarmsRaised,
+      framesStored: this.framesStored,
+    }
+  }
+
+  /** infra 重连后重挂消费者到新队列实例(MQTT↔进程内切换) */
+  async reattachQueue(): Promise<void> {
+    this.pipelineReady = false
+    const queue = await getDaqQueue()
+    this.queueUnsub?.()
+    this.queueUnsub = queue.consume(env => this.onSampleFromQueue(env))
+    this.pipelineReady = true
+  }
+
+  // ---------- 查询 ----------
+
+  listViews(): DaqNodeView[] {
+    this.ensureLoop()
+    return this.repo.all().map(n => n.toView())
+  }
+
+  byId(id: string): DaqNode | undefined {
+    return this.repo.byId(id)
+  }
+
+  /** 节点历史(时序库查询透传;raw 或 bucket 聚合形态) */
+  async samples(id: string, opts: { fromMs?: number, toMs?: number, bucketMs?: number, limit?: number }) {
+    this.ensureLoop()
+    await tsdbReady
+    const node = this.repo.byId(id)
+    if (!node) throw Object.assign(new Error(`数采节点不存在: ${id}`), { status: 404 })
+    return getTsdb().query(id, opts)
+  }
+}

package/server/services/workshop/daq/drivers/http.ts

@@ -0,0 +1,95 @@
+/**
+ * HTTP/REST 轮询真实驱动
+ * (由 server/services/workshop/daq/drivers.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type { DaqDriver } from './shared'
+import { extractNumeric, parseHeaders } from './mqtt'
+
+// ============================================================
+// HTTP/REST 轮询真实驱动(无状态 GET;JSON 路径或纯文本取值)
+// ============================================================
+
+export const httpDaqDriver: DaqDriver = {
+  kind: 'http',
+  async available() {
+    return true
+  },
+  async sample({ driverConfig, signalKind }) {
+    if (!driverConfig.url) throw new Error('缺少接口地址 url')
+    const headers = parseHeaders(driverConfig.headersJSON)
+    const res = await fetch(String(driverConfig.url), { headers, signal: AbortSignal.timeout(5000) })
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    // v2 多形态分支(vector/image 由模板信号形态门控;标量端点零感知)
+    if (signalKind === 'vector') {
+      const j: unknown = JSON.parse(await res.text())
+      const path = driverConfig.jsonPath ? String(driverConfig.jsonPath) : 'points'
+      const target = path.split('.').reduce<unknown>((acc, k) => (acc == null ? undefined : (acc as Record<string, unknown>)[k]), j)
+      if (!Array.isArray(target)) throw new Error(`vector 帧报文缺少点列(jsonPath=${path})`)
+      const points = (target as unknown[]).map(Number)
+      if (points.length === 0 || points.length > 4096 || !points.every(Number.isFinite)) {
+        throw new Error(`vector 帧点列非法(1~4096 个有限数值,实际 ${points.length})`)
+      }
+      return { frame: { kind: 'vector', points } }
+    }
+    if (signalKind === 'image') {
+      const ct = res.headers.get('content-type') ?? ''
+      if (ct.includes('image/')) {
+        const blob = Buffer.from(await res.arrayBuffer())
+        if (blob.length === 0) throw new Error('image 帧响应体为空')
+        // PNG 尺寸兜底:IHDR 宽高在固定偏移(width@16, height@20;大端)——端点不必额外传
+        let width = Number(driverConfig.width ?? 0) || 0
+        let height = Number(driverConfig.height ?? 0) || 0
+        if ((!width || !height) && blob.length >= 24 && blob.readUInt32BE(12) === 0x49484452) {
+          width = width || blob.readUInt32BE(16)
+          height = height || blob.readUInt32BE(20)
+        }
+        return { frame: { kind: 'image', blob, mime: ct.split(';')[0]!, width, height } }
+      }
+      // JSON 报文:{ png: base64, width?, height? }
+      const j = JSON.parse(await res.text()) as Record<string, unknown>
+      const b64 = typeof j.png === 'string' ? j.png : typeof j.blob === 'string' ? j.blob : ''
+      const blob = Buffer.from(b64, 'base64')
+      if (blob.length === 0) throw new Error('image 帧报文缺少 png/blob(base64)字段')
+      return { frame: { kind: 'image', blob, mime: 'image/png', width: Number(j.width ?? 0) || 0, height: Number(j.height ?? 0) || 0 } }
+    }
+    const text = await res.text()
+    return extractNumeric(text, driverConfig.jsonPath ? String(driverConfig.jsonPath) : undefined)
+  },
+  async test(driverConfig) {
+    const t0 = Date.now()
+    try {
+      if (!driverConfig.url) return { ok: false, message: '缺少接口地址 url' }
+      const headers = parseHeaders(driverConfig.headersJSON)
+      const res = await fetch(String(driverConfig.url), { headers, signal: AbortSignal.timeout(5000) })
+      if (!res.ok) return { ok: false, message: `接口返回 HTTP ${res.status}` }
+      const ct = res.headers.get('content-type') ?? ''
+      // 帧形态感知测试:同一端点形态可能是 vector(JSON 点列)/ image(PNG 或 base64)/ 标量
+      if (ct.includes('image/')) {
+        const n = (await res.arrayBuffer()).byteLength
+        return { ok: true, message: `接口可达,image 帧 ${n}B(${ct.split(';')[0]})`, latencyMs: Date.now() - t0 }
+      }
+      const text = await res.text()
+      try {
+        const j = JSON.parse(text) as Record<string, unknown>
+        if (Array.isArray(j.points) && (j.points as unknown[]).length > 0) {
+          return { ok: true, message: `接口可达,vector 帧 ${(j.points as unknown[]).length} 点`, latencyMs: Date.now() - t0 }
+        }
+        if (typeof j.png === 'string' || typeof j.blob === 'string') {
+          // 与生产分支同构:png/blob 至少一个是 base64 字符串(见上一行守卫)。
+          // b64 的取值表达式与原来逐字一致(断言运行时擦除),只是把 unknown 标注成 string 以取 .length
+          const b64 = (j.png as string | undefined) ?? (j.blob as string)
+          return { ok: true, message: `接口可达,image 帧(base64, ${b64.length} chars)`, latencyMs: Date.now() - t0 }
+        }
+        const v = extractNumeric(text, driverConfig.jsonPath ? String(driverConfig.jsonPath) : undefined)
+        return { ok: true, message: `接口可达,取值 = ${v}`, sampleValue: v, latencyMs: Date.now() - t0 }
+      }
+      catch {
+        const v = extractNumeric(text, driverConfig.jsonPath ? String(driverConfig.jsonPath) : undefined)
+        return { ok: true, message: `接口可达,取值 = ${v}`, sampleValue: v, latencyMs: Date.now() - t0 }
+      }
+    }
+    catch (err) {
+      return { ok: false, message: `HTTP 请求失败: ${err instanceof Error ? err.message : String(err)}` }
+    }
+  },
+}

package/server/services/workshop/daq/drivers/index.ts

@@ -0,0 +1,29 @@
+/**
+ * DAQ 协议驱动族(mock / Modbus TCP / OPC UA / Modbus RTU / MQTT / HTTP)与注册表
+ *
+ * 由原单文件按职责拆分而来;此处保持**原文件的公开 API 与 import 路径不变**
+ * (目录 index 解析),外部调用方无需改动。
+ *
+ * 模块划分:
+ *   shared.ts              模块头 / 依赖注入类型 / 驱动接口(DaqDriver 等)
+ *   mock.ts                mock 内置模拟源
+ *   modbus-tcp.ts          Modbus TCP 真实驱动(连接池按 host:port:unitId 复用)
+ *   opcua.ts               OPC UA 真实驱动(会话池按 endpoint+账号 复用)
+ *   modbus-rtu.ts          Modbus RTU over TCP 真实驱动(串口网关透传)
+ *   mqtt.ts                MQTT 真实驱动(broker 连接池 + 订阅缓存)
+ *   http.ts                HTTP/REST 轮询真实驱动
+ *   s7-stub.ts             S7 预留(未安装栈时的显式拒绝桩)
+ *   registry.ts            驱动注册表与旧命名归一解析
+ */
+export type { DaqSampleCtx, DaqDriverInput, DaqFrameSample, DaqDriver } from './shared'
+export { mockDaqDriver } from './mock'
+export { evictModbusConn, closeModbusSafely, withModbusConn, modbusKey, getModbusConn, decodeRegisters, registerOffset, classifyCommError, WORDS_OF, modbusTcpDriver } from './modbus-tcp'
+export type { ModbusConn, ModbusTransport } from './modbus-tcp'
+export { opcuaKey, getOpcUaConn, evictOpcUaConn, opcUaDriver } from './opcua'
+export type { OpcUaConn } from './opcua'
+export { modbusRtuDriver } from './modbus-rtu'
+export { extractNumeric, parseHeaders, mqttDaqDriver } from './mqtt'
+export type { MqttConn } from './mqtt'
+export { httpDaqDriver } from './http'
+export { registerPluginDriver, listPluginDrivers, clearPluginDrivers, listPluginDriverMetas, normalizeDriverKind, resolveDaqDriver, probeDriverAvailability, driverCatalog } from './registry'
+export type { PluginDriverMeta } from './registry'