agentworkshop 0.5.9 → 0.6.1

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

@@ -1,157 +1,213 @@
-/**
- * DaqTemplate 注册表 —— 内置模板(shared 单一事实源)+ 用户自定义模板的统一查询口。
- *
- * 自定义模板落盘 server/data/daq-templates.json(仅存自定义;内置始终在代码里),
- * 与 DaqNodeRepo 同风格:进程内缓存 + 同步落盘(量小无抖动)。节点创建校验、
- * 缺省域、mock 采样一律经 findDaqTemplate 查找 —— 自定义模板与内置同权。
- */
-
-import { createLogger } from '../logger'
-import fs from 'node:fs'
-import { join } from 'node:path'
-import { randomUUID } from 'node:crypto'
-import { DAQ_TEMPLATES, DAQ_TEMPLATE_ICONS, daqTemplateByKey, type DaqTemplateDef, type DaqTemplateIcon, type DaqTemplateInput } from '../../../../shared/daq-protocol'
-import { AppError, ErrorCodes } from '../../../utils/errors'
-import { ensureDataDir } from '@/shared/config/home.mjs'
-
-const log = createLogger('daq.templates')
-
-/** 业务错误捷径(经 defineApiHandler 映射为对应 HTTP 状态与消息) */
-const bad = (msg: string): AppError => new AppError(400, ErrorCodes.VALIDATION_ERROR, msg)
-
-// 配置根 .AgentWorkShop/data（ensureDataDir 统一解析 + 旧位置迁移）
-const DB_PATH = join(ensureDataDir(), 'daq-templates.json')
-
-function load(): DaqTemplateDef[] {
-  try {
-    const raw = fs.readFileSync(DB_PATH, 'utf-8')
-    const parsed = JSON.parse(raw)
-    return Array.isArray(parsed) ? parsed as DaqTemplateDef[] : []
-  }
-  catch {
-    return []
-  }
-}
-
-/** 输入校验 + 归一(base/amp/decimals 等缺省由量程推导;非法值直接抛业务错误) */
-function normalize(input: Partial<DaqTemplateInput>, prev?: DaqTemplateDef): DaqTemplateDef {
-  const name = String(input.name ?? prev?.name ?? '').trim()
-  if (!name) throw bad('模板名称必填')
-  const unit = String(input.unit ?? prev?.unit ?? '').trim()
-  if (!unit) throw bad('单位必填(如 ℃ / MPa)')
-
-  const min = Number(input.min ?? prev?.min)
-  const max = Number(input.max ?? prev?.max)
-  if (!Number.isFinite(min) || !Number.isFinite(max) || min >= max) {
-    throw bad('量程非法:需满足 min < max 的数字')
-  }
-
-  const base = input.base ?? prev?.base ?? (min + max) / 2
-  if (!Number.isFinite(Number(base))) throw bad('模拟基值需为数字')
-
-  const amp = Number(input.amp ?? prev?.amp ?? Math.max((max - min) * 0.04, 0.001))
-  if (!Number.isFinite(amp) || amp <= 0) throw bad('模拟波幅需为正数')
-
-  const decimals = Math.round(Number(input.decimals ?? prev?.decimals ?? 2))
-  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 4) {
-    throw bad('小数位需为 0~4 的整数')
-  }
-
-  const iconRaw = String(input.icon ?? prev?.icon ?? 'thermo')
-  const icon = (DAQ_TEMPLATE_ICONS as readonly string[]).includes(iconRaw)
-    ? iconRaw as DaqTemplateIcon
-    : 'thermo'
-
-  return {
-    key: prev?.key ?? `ct-${randomUUID().slice(0, 8)}`,
-    name,
-    code: String(input.code ?? prev?.code ?? name).trim().toUpperCase() || name.toUpperCase(),
-    ch: String(input.ch ?? prev?.ch ?? name).trim() || name,
-    unit,
-    base: Number(base),
-    amp,
-    min,
-    max,
-    decimals,
-    icon,
-    semantics: String(input.semantics ?? prev?.semantics ?? '').trim() || undefined,
-    telemetryKey: String(input.telemetryKey ?? prev?.telemetryKey ?? '').trim() || undefined,
-    builtin: false,
-  }
-}
-
-class DaqTemplateRegistry {
-  private customs: DaqTemplateDef[]
-
-  constructor() {
-    this.customs = load()
-  }
-
-  /** 全目录:内置在前(统一打 builtin 标记,前端据此分区),自定义在后 */
-  all(): DaqTemplateDef[] {
-    return [...DAQ_TEMPLATES.map(t => ({ ...t, builtin: true })), ...this.customs]
-  }
-
-  byKey(key: string): DaqTemplateDef | undefined {
-    return daqTemplateByKey(key) ?? this.customs.find(t => t.key === key)
-  }
-
-  create(input: DaqTemplateInput): DaqTemplateDef {
-    const tpl = normalize(input)
-    if (this.customs.some(t => t.name === tpl.name)) {
-      throw new AppError(409, ErrorCodes.CONFLICT, `同名自定义模板已存在: ${tpl.name}`)
-    }
-    this.customs.push(tpl)
-    this.flush()
-    return tpl
-  }
-
-  update(key: string, patch: Partial<DaqTemplateInput>): DaqTemplateDef {
-    const prev = this.customs.find(t => t.key === key)
-    if (!prev) {
-      throw new AppError(400, ErrorCodes.BAD_REQUEST, daqTemplateByKey(key) ? '内置模板不可修改(可复制为自定义)' : `自定义模板不存在: ${key}`)
-    }
-    const tpl = normalize(patch, prev)
-    this.customs = this.customs.map(t => (t.key === key ? tpl : t))
-    this.flush()
-    return tpl
-  }
-
-  remove(key: string): DaqTemplateDef {
-    const prev = this.customs.find(t => t.key === key)
-    if (!prev) {
-      throw new AppError(400, ErrorCodes.BAD_REQUEST, daqTemplateByKey(key) ? '内置模板不可删除' : `自定义模板不存在: ${key}`)
-    }
-    this.customs = this.customs.filter(t => t.key !== key)
-    this.flush()
-    return prev
-  }
-
-  private flush(): void {
-    try {
-      fs.mkdirSync(join(DB_PATH, '..'), { recursive: true })
-      fs.writeFileSync(DB_PATH, JSON.stringify(this.customs, null, 2), 'utf-8')
-    }
-    catch (err) {
-      log.error('[daq] 模板落盘失败:', err)
-    }
-  }
-}
-
-// 单例(HMR 存活,与 DaqNodeRepo 同风格)
-const g = globalThis as typeof globalThis & { __daqTemplateRegistry?: DaqTemplateRegistry }
-
-export function getDaqTemplateRegistry(): DaqTemplateRegistry {
-  g.__daqTemplateRegistry ??= new DaqTemplateRegistry()
-  return g.__daqTemplateRegistry
-}
-
-/** 目录快照(server 返回给前端时附带 builtin 标记) */
-export function listDaqTemplates(): DaqTemplateDef[] {
-  return getDaqTemplateRegistry().all()
-}
-
-/** 节点缺省域/mock 采样的统一查找口(内置 + 自定义) */
-export function findDaqTemplate(key: string): DaqTemplateDef | undefined {
-  return getDaqTemplateRegistry().byKey(key)
-}
+/**
+ * DaqTemplate 注册表 —— 内置模板(shared 单一事实源)+ 用户自定义模板的统一查询口。
+ *
+ * 自定义模板落盘 server/data/daq-templates.json(仅存自定义;内置始终在代码里),
+ * 与 DaqNodeRepo 同风格:进程内缓存 + 同步落盘(量小无抖动)。节点创建校验、
+ * 缺省域、mock 采样一律经 findDaqTemplate 查找 —— 自定义模板与内置同权。
+ */
+
+import { createLogger } from '../logger'
+import fs from 'node:fs'
+import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { DAQ_TEMPLATES, DAQ_TEMPLATE_ICONS, daqTemplateByKey, normalizeSignalKind, type DaqMetricRule, type DaqSinkStep, type DaqTemplateDef, type DaqTemplateIcon, type DaqTemplateInput } from '../../../../shared/daq-protocol'
+import { AppError, ErrorCodes } from '../../../utils/errors'
+import { ensureDataDir } from '@/shared/config/home.mjs'
+
+const log = createLogger('daq.templates')
+
+/** 业务错误捷径(经 defineApiHandler 映射为对应 HTTP 状态与消息) */
+const bad = (msg: string): AppError => new AppError(400, ErrorCodes.VALIDATION_ERROR, msg)
+
+// 配置根 .AgentWorkShop/data（ensureDataDir 统一解析 + 旧位置迁移）
+const DB_PATH = join(ensureDataDir(), 'daq-templates.json')
+
+function load(): DaqTemplateDef[] {
+  try {
+    const raw = fs.readFileSync(DB_PATH, 'utf-8')
+    const parsed = JSON.parse(raw)
+    return Array.isArray(parsed) ? parsed as DaqTemplateDef[] : []
+  }
+  catch {
+    return []
+  }
+}
+
+/** 输入校验 + 归一(base/amp/decimals 等缺省由量程推导;非法值直接抛业务错误) */
+function normalize(input: Partial<DaqTemplateInput>, prev?: DaqTemplateDef): DaqTemplateDef {
+  const name = String(input.name ?? prev?.name ?? '').trim()
+  if (!name) throw bad('模板名称必填')
+  const unit = String(input.unit ?? prev?.unit ?? '').trim()
+  if (!unit) throw bad('单位必填(如 ℃ / MPa)')
+
+  const min = Number(input.min ?? prev?.min)
+  const max = Number(input.max ?? prev?.max)
+  if (!Number.isFinite(min) || !Number.isFinite(max) || min >= max) {
+    throw bad('量程非法:需满足 min < max 的数字')
+  }
+
+  const base = input.base ?? prev?.base ?? (min + max) / 2
+  if (!Number.isFinite(Number(base))) throw bad('模拟基值需为数字')
+
+  const amp = Number(input.amp ?? prev?.amp ?? Math.max((max - min) * 0.04, 0.001))
+  if (!Number.isFinite(amp) || amp <= 0) throw bad('模拟波幅需为正数')
+
+  const decimals = Math.round(Number(input.decimals ?? prev?.decimals ?? 2))
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 4) {
+    throw bad('小数位需为 0~4 的整数')
+  }
+
+  const iconRaw = String(input.icon ?? prev?.icon ?? 'thermo')
+  const icon = (DAQ_TEMPLATE_ICONS as readonly string[]).includes(iconRaw)
+    ? iconRaw as DaqTemplateIcon
+    : 'thermo'
+
+  // 多形态信号(v2 帧管线):signalKind/vector/sink/metrics 归一(缺省 scalar 零行为变化)
+  const signalKind = normalizeSignalKind(input.signalKind ?? prev?.signalKind)
+  let vector: DaqTemplateDef['vector']
+  if (signalKind === 'vector') {
+    const points = Math.round(Number(input.vector?.points ?? prev?.vector?.points ?? 64))
+    if (!Number.isInteger(points) || points < 2 || points > 4096) {
+      throw bad('vector.points 需为 2~4096 的整数')
+    }
+    const vmin = Number(input.vector?.min ?? prev?.vector?.min ?? min)
+    const vmax = Number(input.vector?.max ?? prev?.vector?.max ?? max)
+    if (!Number.isFinite(vmin) || !Number.isFinite(vmax) || vmin >= vmax) throw bad('vector 量程非法')
+    vector = { points, min: vmin, max: vmax }
+  }
+  const sink = input.sink ?? prev?.sink
+  if (sink && (!Array.isArray(sink.processors) || sink.processors.some(p => !p || typeof p.name !== 'string'))) {
+    throw bad('sink.processors 非法:需为 { name, args? } 数组')
+  }
+  const metrics = (input.metrics ?? prev?.metrics)?.filter(r => r && typeof r.key === 'string' && r.key.trim()) as DaqMetricRule[] | undefined
+
+  return {
+    key: prev?.key ?? `ct-${randomUUID().slice(0, 8)}`,
+    name,
+    code: String(input.code ?? prev?.code ?? name).trim().toUpperCase() || name.toUpperCase(),
+    ch: String(input.ch ?? prev?.ch ?? name).trim() || name,
+    unit,
+    base: Number(base),
+    amp,
+    min,
+    max,
+    decimals,
+    icon,
+    semantics: String(input.semantics ?? prev?.semantics ?? '').trim() || undefined,
+    telemetryKey: String(input.telemetryKey ?? prev?.telemetryKey ?? '').trim() || undefined,
+    builtin: false,
+    signalKind,
+    vector,
+    sink: sink && sink.processors.length > 0 ? { processors: sink.processors as DaqSinkStep[] } : undefined,
+    metrics: metrics && metrics.length > 0 ? metrics : undefined,
+  }
+}
+
+class DaqTemplateRegistry {
+  private customs: DaqTemplateDef[]
+  /** 插件注册模板(内存态,键 = 模板 key;插件热重载同名覆盖;不经 REST 增删) */
+  private pluginTpls = new Map<string, DaqTemplateDef>()
+
+  constructor() {
+    this.customs = load()
+  }
+
+  /** 全目录:内置在前(统一打 builtin 标记),插件模板居中(打 plugin 标记),自定义在后 */
+  all(): DaqTemplateDef[] {
+    return [
+      ...DAQ_TEMPLATES.map(t => ({ ...t, builtin: true })),
+      ...[...this.pluginTpls.values()].map(t => ({ ...t, plugin: t.plugin ?? 'plugin' })),
+      ...this.customs,
+    ]
+  }
+
+  byKey(key: string): DaqTemplateDef | undefined {
+    return daqTemplateByKey(key) ?? this.pluginTpls.get(key) ?? this.customs.find(t => t.key === key)
+  }
+
+  /**
+   * 插件模板注册(同名 key 覆盖 → 插件热重载幂等;REST 不可增删改)。
+   * def.key 必填(建议 `plug-<plugin>-<sig>` 命名);signalKind/sink/metrics 全量可用。
+   */
+  registerPlugin(def: DaqTemplateDef): DaqTemplateDef {
+    if (!def?.key || !/^[\w-]+$/.test(def.key)) {
+      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `插件模板 key 非法: ${def?.key}(需 [\\w-]+)`)
+    }
+    if (daqTemplateByKey(def.key)) {
+      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `插件模板 key 与内置模板冲突: ${def.key}`)
+    }
+    const merged: DaqTemplateDef = { ...def, plugin: def.plugin ?? 'plugin' }
+    this.pluginTpls.set(def.key, merged)
+    log.info(`[daq] 插件模板注册:「${merged.name}」(${def.key},插件=${merged.plugin})`)
+    return merged
+  }
+
+  isPlugin(key: string): boolean {
+    return this.pluginTpls.has(key)
+  }
+
+  create(input: DaqTemplateInput): DaqTemplateDef {
+    const tpl = normalize(input)
+    if (this.customs.some(t => t.name === tpl.name)) {
+      throw new AppError(409, ErrorCodes.CONFLICT, `同名自定义模板已存在: ${tpl.name}`)
+    }
+    this.customs.push(tpl)
+    this.flush()
+    return tpl
+  }
+
+  update(key: string, patch: Partial<DaqTemplateInput>): DaqTemplateDef {
+    if (this.pluginTpls.has(key)) {
+      throw new AppError(400, ErrorCodes.BAD_REQUEST, '插件模板不可经 REST 修改(由插件自身管理)')
+    }
+    const prev = this.customs.find(t => t.key === key)
+    if (!prev) {
+      throw new AppError(400, ErrorCodes.BAD_REQUEST, daqTemplateByKey(key) ? '内置模板不可修改(可复制为自定义)' : `自定义模板不存在: ${key}`)
+    }
+    const tpl = normalize(patch, prev)
+    this.customs = this.customs.map(t => (t.key === key ? tpl : t))
+    this.flush()
+    return tpl
+  }
+
+  remove(key: string): DaqTemplateDef {
+    if (this.pluginTpls.has(key)) {
+      throw new AppError(400, ErrorCodes.BAD_REQUEST, '插件模板不可经 REST 删除(由插件自身管理)')
+    }
+    const prev = this.customs.find(t => t.key === key)
+    if (!prev) {
+      throw new AppError(400, ErrorCodes.BAD_REQUEST, daqTemplateByKey(key) ? '内置模板不可删除' : `自定义模板不存在: ${key}`)
+    }
+    this.customs = this.customs.filter(t => t.key !== key)
+    this.flush()
+    return prev
+  }
+
+  private flush(): void {
+    try {
+      fs.mkdirSync(join(DB_PATH, '..'), { recursive: true })
+      fs.writeFileSync(DB_PATH, JSON.stringify(this.customs, null, 2), 'utf-8')
+    }
+    catch (err) {
+      log.error('[daq] 模板落盘失败:', err)
+    }
+  }
+}
+
+// 单例(HMR 存活,与 DaqNodeRepo 同风格)
+const g = globalThis as typeof globalThis & { __daqTemplateRegistry?: DaqTemplateRegistry }
+
+export function getDaqTemplateRegistry(): DaqTemplateRegistry {
+  g.__daqTemplateRegistry ??= new DaqTemplateRegistry()
+  return g.__daqTemplateRegistry
+}
+
+/** 目录快照(server 返回给前端时附带 builtin 标记) */
+export function listDaqTemplates(): DaqTemplateDef[] {
+  return getDaqTemplateRegistry().all()
+}
+
+/** 节点缺省域/mock 采样的统一查找口(内置 + 自定义) */
+export function findDaqTemplate(key: string): DaqTemplateDef | undefined {
+  return getDaqTemplateRegistry().byKey(key)
+}

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

@@ -16,6 +16,7 @@
  */
 import { createLogger } from '../logger'
 import { createRequire } from 'node:module'
+import { encodePng } from './png-enc'
 import type { DaqDriverKind, DriverTestResult } from '../../../../shared/daq-protocol'
 
 const log = createLogger('daq.drivers')
@@ -36,13 +37,38 @@ export interface DaqDriverInput {
   config: { base: number, amp: number, min: number, max: number }
   /** 节点保存的协议连接参数(host/register/endpoint/nodeId...) */
   driverConfig: Record<string, unknown>
+  /** 模板信号形态(v2 帧管线;缺省 scalar —— 既有驱动零感知) */
+  signalKind?: 'scalar' | 'vector' | 'image'
+  /** vector 声明(模板;mock 生成点列/校验依据) */
+  vector?: { points: number, min: number, max: number }
+}
+
+/**
+ * 帧采样值(v2 多形态信号):驱动 sample() 可返回标量(既有契约)或帧信封。
+ *  - vector:多点工程量轮廓(≤4096 点,经队列 JSON 传输)
+ *  - image :像素 blob(仅生产侧管线内存续;controller 落对象存储后剥离为 objectKey)
+ */
+export type DaqFrameSample = {
+  frame:
+    | { kind: 'vector', points: number[], metrics?: Record<string, number> }
+    | {
+      kind: 'image'
+      blob: Buffer
+      mime: string
+      width: number
+      height: number
+      metrics?: Record<string, number>
+      /** 驱动侧通常未设;controller 落对象存储后回填引用(队列信封只传引用) */
+      objectKey?: string
+      thumbKey?: string
+    }
 }
 
 export interface DaqDriver {
   readonly kind: DaqDriverKind
   /** 协议栈是否可用(包缺失时 false,节点测试连接给出可行动提示) */
   available(): Promise<boolean>
-  sample(input: DaqDriverInput): Promise<number | null> | number | null
+  sample(input: DaqDriverInput): Promise<number | DaqFrameSample | null> | number | DaqFrameSample | null
   test(driverConfig: Record<string, unknown>): Promise<DriverTestResult>
 }
 
@@ -75,39 +101,101 @@ export const mockDaqDriver: DaqDriver = {
   async available() {
     return true
   },
-  sample({ ctx, config }) {
-    const states = mockStates()
-    let st = states.get(ctx.nodeId)
-    if (!st) {
-      st = { phase: hashPhase(ctx.nodeId), value: null, excursionLeft: 0, excursionDir: 0, excursionDepth: 0, lastAt: ctx.now }
-      states.set(ctx.nodeId, st)
-    }
-    const dt = Math.max(0, Math.min(ctx.now - st.lastAt, 60_000))
-    st.lastAt = ctx.now
-    if (st.excursionLeft <= 0 && Math.random() < 0.008 * Math.max(1, dt / 1000)) {
-      st.excursionLeft = 6 + Math.floor(Math.random() * 9)
-      st.excursionDir = Math.random() < 0.5 ? -1 : 1
-      st.excursionDepth = (config.max - config.min) * (0.08 + Math.random() * 0.1)
-    }
-    const t = (ctx.ageMs + st.phase * 100) / 1000
-    const sine = Math.sin(t * 0.35) * config.amp * 0.55 + Math.sin(t * 0.11 + 1.3) * config.amp * 0.3
-    let v = config.base + sine
-    if (st.value != null) v += (config.base - st.value) * 0.06 + (Math.random() - 0.5) * config.amp * 0.5
-    if (st.excursionLeft > 0) {
-      st.excursionLeft -= 1
-      const ramp = Math.min(1, (10 - st.excursionLeft) / 4)
-      v += st.excursionDir * st.excursionDepth * (0.4 + 0.6 * ramp)
-      if (st.excursionLeft === 0) st.excursionDir = 0
-    }
-    v = Math.min(config.max + config.amp * 2.2, Math.max(config.min - config.amp * 2.2, v))
-    st.value = v
-    return v
+  sample({ ctx, config, signalKind, vector }) {
+    // 多形态分支(v2 帧管线):vector=多点波形轮廓;image=程序化灰度 PNG;scalar=既有单点波形
+    if (signalKind === 'vector') return mockVectorSample(ctx, config, vector)
+    if (signalKind === 'image') return mockImageSample(ctx, config)
+    return mockScalarSample(ctx, config)
   },
   async test() {
     return { ok: true, message: 'Mock 驱动无需连接,采样即模拟波形' }
   },
 }
 
+/** 既有单点波形(原 sample() 主体,零行为变化) */
+function mockScalarSample(ctx: DaqSampleCtx, config: { base: number, amp: number, min: number, max: number }): number {
+  const states = mockStates()
+  let st = states.get(ctx.nodeId)
+  if (!st) {
+    st = { phase: hashPhase(ctx.nodeId), value: null, excursionLeft: 0, excursionDir: 0, excursionDepth: 0, lastAt: ctx.now }
+    states.set(ctx.nodeId, st)
+  }
+  const dt = Math.max(0, Math.min(ctx.now - st.lastAt, 60_000))
+  st.lastAt = ctx.now
+  if (st.excursionLeft <= 0 && Math.random() < 0.008 * Math.max(1, dt / 1000)) {
+    st.excursionLeft = 6 + Math.floor(Math.random() * 9)
+    st.excursionDir = Math.random() < 0.5 ? -1 : 1
+    st.excursionDepth = (config.max - config.min) * (0.08 + Math.random() * 0.1)
+  }
+  const t = (ctx.ageMs + st.phase * 100) / 1000
+  const sine = Math.sin(t * 0.35) * config.amp * 0.55 + Math.sin(t * 0.11 + 1.3) * config.amp * 0.3
+  let v = config.base + sine
+  if (st.value != null) v += (config.base - st.value) * 0.06 + (Math.random() - 0.5) * config.amp * 0.5
+  if (st.excursionLeft > 0) {
+    st.excursionLeft -= 1
+    const ramp = Math.min(1, (10 - st.excursionLeft) / 4)
+    v += st.excursionDir * st.excursionDepth * (0.4 + 0.6 * ramp)
+    if (st.excursionLeft === 0) st.excursionDir = 0
+  }
+  v = Math.min(config.max + config.amp * 2.2, Math.max(config.min - config.amp * 2.2, v))
+  st.value = v
+  return v
+}
+
+/** 多点波形轮廓(测厚仪/扫描仪语义:横向 n 点,带漂移与偶发局部尖峰) */
+function mockVectorSample(
+  ctx: DaqSampleCtx,
+  config: { base: number, amp: number, min: number, max: number },
+  vector?: { points: number, min: number, max: number },
+): { frame: { kind: 'vector', points: number[], metrics: Record<string, number> } } {
+  const n = Math.max(2, Math.min(4096, vector?.points ?? 64))
+  const vMin = vector?.min ?? config.min
+  const vMax = vector?.max ?? config.max
+  const span = vMax - vMin
+  const t = (ctx.ageMs + hashPhase(ctx.nodeId) * 100) / 1000
+  const points: number[] = []
+  // 横向轮廓:慢波(工艺整体偏移)+ 位置抛物面(边缘偏厚)+ 噪声 + 偶发局部尖峰(缺陷)
+  const drift = Math.sin(t * 0.21) * config.amp
+  const spikePos = Math.floor((Math.sin(t * 0.07) * 0.5 + 0.5) * n)
+  for (let i = 0; i < n; i++) {
+    const rel = i / (n - 1)
+    const crown = -4 * (rel - 0.5) ** 2 * span * 0.03 // 边缘略薄(负抛物面)
+    let v = config.base + drift + crown + (Math.random() - 0.5) * config.amp * 0.4
+    if (Math.abs(i - spikePos) <= 1) v += span * 0.06 // 偶发局部尖峰
+    points.push(Math.round(Math.min(vMax, Math.max(vMin, v)) * 1e6) / 1e6)
+  }
+  return { frame: { kind: 'vector', points, metrics: {} } }
+}
+
+/** 程序化灰度图像(CCD 语义:纹理背景 + 移动暗斑;零外部依赖 zlib PNG) */
+function mockImageSample(
+  ctx: DaqSampleCtx,
+  config: { base: number, amp: number, min: number, max: number },
+): { frame: { kind: 'image', blob: Buffer, mime: string, width: number, height: number, metrics: Record<string, number> } } {
+  // 偶发"曝光异常"帧(低亮度)驱动 quality-gate 告警链路可观测
+  const dark = Math.random() < 0.03
+  const baseGray = dark ? 22 : Math.round(Math.min(230, Math.max(60, config.base)))
+  const w = 320
+  const h = 240
+  const px = new Uint8Array(w * h)
+  const t = (ctx.ageMs + hashPhase(ctx.nodeId) * 100) / 1000
+  const spotX = Math.floor(((Math.sin(t * 0.4) + 1) / 2) * (w - 60)) + 30
+  const spotY = Math.floor(((Math.cos(t * 0.3) + 1) / 2) * (h - 60)) + 30
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      // 编织纹理 + 随机噪声 + 移动暗斑(表面缺陷模拟)
+      let v = baseGray + Math.sin(x * 0.35) * 8 + Math.sin(y * 0.22 + 1.7) * 6 + (Math.random() - 0.5) * 10
+      const dx = x - spotX
+      const dy = y - spotY
+      const d2 = dx * dx + dy * dy
+      if (d2 < 400) v -= (1 - d2 / 400) * 90
+      px[y * w + x] = Math.max(0, Math.min(255, Math.round(v)))
+    }
+  }
+  const blob = encodePng(w, h, px)
+  return { frame: { kind: 'image', blob, mime: 'image/png', width: w, height: h, metrics: {} } }
+}
+
 // ============================================================
 // Modbus TCP 真实驱动(modbus-serial;连接池按 host:port:unitId 复用)
 // ============================================================
@@ -746,14 +834,30 @@ const REGISTRY: Record<DaqDriverKind, DaqDriver> = {
   's7': new PlannedProtocolStub('s7', 'S7comm'),
 }
 
+/** 插件注册的驱动(经 ctx.daq.registerDriver;热重载重复注册幂等覆盖) */
+const g_plugins = globalThis as typeof globalThis & { __daqPluginDrivers?: Map<string, DaqDriver> }
+function pluginRegistry(): Map<string, DaqDriver> {
+  return g_plugins.__daqPluginDrivers ??= new Map()
+}
+
+/** 插件驱动注册(kind 与内置冲突时覆盖并告警;resolveDaqDriver 插件优先) */
+export function registerPluginDriver(driver: DaqDriver): void {
+  if (driver.kind in REGISTRY) log.warn(`[daq-drivers] 插件驱动覆盖内置:「${driver.kind}」`)
+  pluginRegistry().set(driver.kind, driver)
+}
+
+export function listPluginDrivers(): string[] {
+  return [...pluginRegistry().keys()]
+}
+
 export function normalizeDriverKind(kind: string): DaqDriverKind {
   if (kind === 'modbus') return 'modbus-tcp'
   if (kind === 'rtu' || kind === 'modbus-rtu-tcp') return 'modbus-rtu'
-  return (kind in REGISTRY ? kind : 'mock') as DaqDriverKind
+  return (kind in REGISTRY || pluginRegistry().has(kind) ? kind : 'mock') as DaqDriverKind
 }
 
 export function resolveDaqDriver(kind: DaqDriverKind): DaqDriver {
-  return REGISTRY[kind] ?? mockDaqDriver
+  return pluginRegistry().get(kind) ?? REGISTRY[kind] ?? mockDaqDriver
 }
 
 /** 驱动可用性探测(meta 报告:包缺失时 UI 显示"未安装"而非硬失败) */