agentworkshop 0.7.39 → 0.7.41

package/server/services/workshop/agents/opencode-agent.ts

@@ -32,7 +32,7 @@ import { extractJsonArray, peerPrompt, supervisePrompt, systemManual, toolArgsPr
 import { getHitlRegistry } from './hitl-registry'
 import { harnessSettings } from '../settings'
 import { spawnLineProcess } from './adapters/line-spawn'
-import { BaseAgentImpl } from './base-agent'
+import { BaseAgentImpl, type BaseAgentConfigView } from './base-agent'
 import { resolveBridgePath, resolvePlatformBaseUrl } from './harness-env'
 
 const log = createLogger('workshop.opencode')
@@ -152,7 +152,7 @@ export class OpenCodeAgentImpl extends BaseAgentImpl implements AgentInterface {
     return 'opencode'
   }
 
-  protected configRecord(): Record<string, unknown> {
+  protected configRecord(): BaseAgentConfigView {
     return this.config
   }
 
@@ -222,7 +222,7 @@ export class OpenCodeAgentImpl extends BaseAgentImpl implements AgentInterface {
   }
 
   /** HITL 应答(codex/opencode/dsh 统一入口;本 impl 处理 opencode-permission) */
-  async respondHitl(kind: string, id: string, outcome: {
+  override async respondHitl(kind: string, id: string, outcome: {
     confirmed?: boolean
     cancelled?: boolean
     value?: string
@@ -247,7 +247,9 @@ export class OpenCodeAgentImpl extends BaseAgentImpl implements AgentInterface {
         await this.api('POST', `/question/${encodeURIComponent(id)}/reply`, { answer: outcome.value ?? outcome.comment ?? '' })
       }
     }
-    if (pending.timer) clearTimeout(p.timer)
+    // 原为 clearTimeout(p.timer):p 在本作用域不存在(ReferenceError,且仅当计时器非空时触发),
+    // 该待办条目在此处就是 pending(与 dsh/codex/hermes 的同名分支写法一致)。
+    if (pending.timer) clearTimeout(pending.timer)
     this.pendingHitl.delete(id)
     getHitlRegistry().resolve(kind, id, cancelled ? 'cancelled' : 'answered')
   }
@@ -273,9 +275,9 @@ export class OpenCodeAgentImpl extends BaseAgentImpl implements AgentInterface {
     }
   }
 
-  private supervising = false
+  // supervising 由 BaseAgentImpl 持有(protected):同名私有声明会与基类形成"两个私有声明"(TS2415)。
 
-  async supervise(snapshot: SupervisionSnapshot, ctx: AgentRunContext, opts?: { signal?: AbortSignal }): Promise<SupervisionDecision[]> {
+  override async supervise(snapshot: SupervisionSnapshot, ctx: AgentRunContext, opts?: { signal?: AbortSignal }): Promise<SupervisionDecision[]> {
     // 引擎/会话不可用 → 本轮监督降级为空(调度器回退规则引擎);绝不让引擎故障
     // 以 unhandledRejection 形态逃逸(dev-stability-guard 会据此杀掉整个服务端)
     try {
@@ -296,16 +298,22 @@ export class OpenCodeAgentImpl extends BaseAgentImpl implements AgentInterface {
       memory: ctx.memory,
     })
     const timeoutMs = this.config.superviseTimeoutMs ?? 150_000
-    return await this.runTurn(prompt, undefined, {
-      timeoutMs,
-      signal: opts?.signal,
-      onDone: async () => {
-        this.supervising = false
-      },
-      beforeStart: () => {
-        this.supervising = true
-      },
-    }).then((events) => {
+    // runTurn 是 async generator(返回 AsyncGenerator,不是 Promise),必须以异步迭代消费完整个回合。
+    // (原实现写 .then(...)/.catch(...):运行时是 "then is not a function" 的 TypeError,supervise 整条路径实际不可用。)
+    try {
+      const events: AgentEvent[] = []
+      for await (const e of this.runTurn(prompt, undefined, {
+        timeoutMs,
+        signal: opts?.signal,
+        onDone: async () => {
+          this.supervising = false
+        },
+        beforeStart: () => {
+          this.supervising = true
+        },
+      })) {
+        events.push(e)
+      }
       // 从事件流提取最终文本 → JSON 决策兜底(工具直执行路径返回空)
       let text = ''
       for (const e of events) {
@@ -315,10 +323,21 @@ export class OpenCodeAgentImpl extends BaseAgentImpl implements AgentInterface {
       }
       const parsed = extractJsonArray(text)
       return parsed && parsed.length > 0 ? parsed as SupervisionDecision[] : []
-    }).catch(() => {
+    }
+    catch {
       this.supervising = false
       return []
-    })
+    }
+  }
+
+  /** supervise 用:收齐整个回合的事件(基类抽象成员;本类 supervise 自行消费并需 beforeStart/onDone 钩子) */
+  protected async collectTurnEvents(prompt: string, timeoutMs: number, signal?: AbortSignal): Promise<AgentEvent[]> {
+    const events: AgentEvent[] = []
+    for await (const e of this.runTurn(prompt, undefined, { timeoutMs, signal })) {
+      events.push(e)
+      if (e.kind === 'error') break
+    }
+    return events
   }
 
   protected async* workerTurn(request: AgentRunRequest, ctx: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown> {
@@ -800,10 +819,17 @@ export class OpenCodeAgentImpl extends BaseAgentImpl implements AgentInterface {
     }
     const createWith = async (extra: Record<string, unknown> | undefined): Promise<Record<string, unknown>> =>
       this.api('POST', '/session', { ...body, ...(extra ?? {}) })
-    const created = await (this.config.permission ?? DEFAULT_PERMISSION)
+    // 历史实现写作 `await (cond) ? a : b`:await 只作用于条件,整个三元表达式的结果是**未 await** 的
+    // Promise,故 created?.id 恒为 undefined → sessionId 恒为 String(undefined ?? '') === '' →
+    // 必然落到下面的 2.5s 重试循环(真正被使用的会话来自重试那次 createWith(undefined))。
+    // 此处逐字保留该运行时语义:同样的 await 让出一次微任务、同样的请求照发、首次结果同样丢弃。
+    // 直白的修法是给整个三元表达式加括号 await(会用上带 permission 的首次会话、省掉 2.5s 重试),
+    // 但那会改变 opencode 会话的权限策略与启动时序,故本次不改 —— 见报告"未修的缺陷"一节。
+    const firstAttempt = await (this.config.permission ?? DEFAULT_PERMISSION)
+    void (firstAttempt
       ? createWith({ permission: this.config.permission ?? DEFAULT_PERMISSION }).catch(() => createWith(undefined))
-      : createWith(undefined)
-    this.sessionId = String(created?.id ?? '')
+      : createWith(undefined))
+    this.sessionId = ''
     if (!this.sessionId) {
       // 瞬态失败(实例刚起/内部分配竞态/权限规则不兼容)→ 无附加字段重试,最多 3 次
       for (let i = 0; i < 3 && !this.sessionId; i++) {

package/server/services/workshop/agents/qwen-agent.ts

@@ -27,7 +27,7 @@ import type {
 } from './agent-interface'
 import type { AgentContextStats } from '../types/task'
 import { markHarnessProcessExit, registerHarnessProcess, bindHarnessProcess, killHarnessProcess } from './harness-process'
-import { peerPrompt, systemManual, toolArgsPreview, workerPrompt } from './prompt-builder'
+import { extractJsonArray, peerPrompt, supervisePrompt, systemManual, toolArgsPreview, workerPrompt } from './prompt-builder'
 import { getHitlRegistry } from './hitl-registry'
 import { harnessSettings } from '../settings'
 import { StdioJsonRpcClient, type JsonRpcRequestIncoming } from './adapters/stdio-jsonrpc'
@@ -111,7 +111,9 @@ export interface QwenAgentConfig {
 export class QwenAgentImpl extends BaseAgentImpl {
   private readonly config: QwenAgentConfig
 
-  private agentRole: 'lead' | 'worker' = 'worker'
+  // agentRole 由 BaseAgentImpl 持有(protected);同名私有声明会遮蔽基类 identity 角色。
+  // 仅收窄可见性声明,运行时代码不变。
+  protected override agentRole: 'lead' | 'worker' = 'worker'
   private client: StdioJsonRpcClient | null = null
   private clientStarting: Promise<void> | null = null
   private turnActive = false
@@ -177,7 +179,7 @@ export class QwenAgentImpl extends BaseAgentImpl {
   }
 
   /** HITL 应答:requestToolCallConfirmation → outcome allow/reject/cancel(fail-closed) */
-  async respondHitl(kind: string, id: string, outcome: {
+  override async respondHitl(kind: string, id: string, outcome: {
     confirmed?: boolean
     cancelled?: boolean
   }): Promise<void> {
@@ -202,7 +204,7 @@ export class QwenAgentImpl extends BaseAgentImpl {
 
   // ===== run / supervise =====
 
-  async supervise(snapshot: import('./agent-interface').SupervisionSnapshot, ctx: AgentRunContext, opts?: { signal?: AbortSignal }): Promise<import('./agent-interface').SupervisionDecision[]> {
+  override async supervise(snapshot: import('./agent-interface').SupervisionSnapshot, ctx: AgentRunContext, opts?: { signal?: AbortSignal }): Promise<import('./agent-interface').SupervisionDecision[]> {
     await this.ensureClient(ctx)
     if (!this.client || !this.sessionStarted) return []
     if (this.supervising) return []
@@ -216,7 +218,10 @@ export class QwenAgentImpl extends BaseAgentImpl {
     })
     this.supervising = true
     try {
-      const events = await this.collectTurn(prompt, this.config.superviseTimeoutMs ?? 150_000, opts?.signal)
+      // 原为 this.collectTurn(...):该类唯一存在的整回合收集实现是 collectTurnEvents
+      // (与基类 supervise 调用的同名抽象成员同签名)。原调用在运行时抛 TypeError 并被
+      // 本方法的 catch 吞掉 → supervise 恒返回 [],详见报告。
+      const events = await this.collectTurnEvents(prompt, this.config.superviseTimeoutMs ?? 150_000, opts?.signal)
       let text = ''
       for (const e of events) {
         if (e.kind === 'artifact') {

package/server/services/workshop/aml/entity.ts

@@ -72,7 +72,9 @@ export function inventory(): AmlInventory {
     kind: EntityIssue['kind'],
     rows: Array<{ id: string, path?: string }>,
     baseDir: string,
-    contract: string[],
+    // 非空契约列表:三个调用点都传字面量,且下面按"多选一"语义读 contract[0] 作展示路径,
+    // 用非空元组表达"至少一项"这一既有前提(纯类型,运行时零变化)
+    contract: readonly [string, ...string[]],
   ): number => {
     const ids = new Set(rows.map(r => r.id))
     for (const r of rows) {

package/server/services/workshop/aml/python-runtime.ts

@@ -362,7 +362,8 @@ export async function installUv(rt: AmlRuntime, onLog?: ProgressFn): Promise<{ o
     const hit = findUvInDir(rt.toolsDir)
     if (hit) {
       const v = await runCapture(hit, ['--version'], 15_000)
-      const version = (v.out || v.err).trim().split('\n')[0]
+      // 运行时 `''.split('\n')[0] === ''`,首行恒存在;?? '' 只是 noUncheckedIndexedAccess 下的写法
+      const version = (v.out || v.err).trim().split('\n')[0] ?? ''
       writeUvRecord(rt, { uvPath: hit, version, installedAt: new Date().toISOString(), installDir: rt.toolsDir, method: 'official-script' })
       resetProbeCache()
       emit(`安装成功:${version} @ ${hit}`)
@@ -390,7 +391,7 @@ export async function installUv(rt: AmlRuntime, onLog?: ProgressFn): Promise<{ o
         }
         catch { /* Windows 无 x 位 */ }
         const v = await runCapture(hit, ['--version'], 15_000)
-        const version = (v.out || v.err).trim().split('\n')[0]
+        const version = (v.out || v.err).trim().split('\n')[0] ?? ''
         writeUvRecord(rt, { uvPath: hit, version, installedAt: new Date().toISOString(), installDir: rt.toolsDir, method: 'pip-target' })
         resetProbeCache()
         emit(`安装成功:${version} @ ${hit}`)

package/server/services/workshop/daq/bus/mqtt.adapter.ts

@@ -25,6 +25,10 @@ const TOPIC_WILDCARD = `${TOPIC_ROOT}/+/sample`
 /** 断连离线缓冲上限(满丢最旧;补发帧按消费侧乱序防御自然去重) */
 const OFFLINE_CAP = 2000
 
+/** MQTT QoS 协议取值(0/1/2;shared/config/schema.json 的 daq.mqtt.qos 声明 min 0 / max 2)。
+ *  settings 面(settings.ts)把该配置读成 number,这里按协议收窄 —— 运行时原值透传,不做钳制/兜底。 */
+type MqttQos = 0 | 1 | 2
+
 export class MqttQueueAdapter implements DaqQueuePort {
   readonly backend = 'mqtt' as const
   private client: MqttClient | null = null
@@ -48,7 +52,7 @@ export class MqttQueueAdapter implements DaqQueuePort {
     const mod = requireMqtt('mqtt') as unknown as { connect: (url: string, opts?: Record<string, unknown>) => MqttClient }
     // 凭据/QoS/TLS 配置驱动(daq.mqtt.*;legacy DAQ_MQTT_* env 别名兼容,DAQ_MQTT_URL 整串覆盖仍最高优先)
     const mqttCfg = daqRuntimeSettings().mqtt
-    const qos = mqttCfg.qos
+    const qos = mqttCfg.qos as MqttQos
     const opts: Record<string, unknown> = {
       clientId: `aw-daq-${process.pid}-${Math.random().toString(36).slice(2, 6)}`,
       reconnectPeriod: 2000,
@@ -99,7 +103,7 @@ export class MqttQueueAdapter implements DaqQueuePort {
       return
     }
     this.published++
-    this.client.publish(TOPIC_SAMPLE(env.nodeId), JSON.stringify(env), { qos: daqRuntimeSettings().mqtt.qos })
+    this.client.publish(TOPIC_SAMPLE(env.nodeId), JSON.stringify(env), { qos: daqRuntimeSettings().mqtt.qos as MqttQos })
   }
 
   consume(fn: DaqConsumer): () => void {
@@ -123,8 +127,8 @@ export class MqttQueueAdapter implements DaqQueuePort {
         // end() 回调在某些断连路径下不触发,旧 client 的 connect/message/error 监听器
         // 会连同 socket 一起滞留(client 对象被闭包引用,GC 不可达)。
         // rebuildDaqQueue 反复换装时会累积;显式摘除是唯一确定性的清理点。
-        try {
-          c.removeAllListeners()
+        try {
+          c.removeAllListeners()
         }
         catch { /* 已销毁等场景:尽力而为 */ }
       }

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'
@@ -106,6 +106,16 @@ export interface DaqPatchInput {
 
 type BroadcastFn = (type: string, payload: unknown) => void
 
+/** 有界 LRU 的最小泛型面:shared/lru.mjs 是 allowJs 推断出的**非泛型**类(JS 里没有 @template),
+ *  直接 `new LruMap<K, V>()` 无处安放类型参数。这里按实际使用面(get/set/delete/size)声明键值类型,
+ *  调用点即可拿到准确的读写类型;运行时仍是同一个 LruMap(纯类型声明,零运行时差异)。 */
+interface LruLike<K, V> {
+  readonly size: number
+  get(key: K): V | undefined
+  set(key: K, value: V): unknown
+  delete(key: K): unknown
+}
+
 /** TSDB 批量写窗口(ms):消费端攒批再落盘 */
 const TSDB_FLUSH_MS = 500
 /** TSDB 攒批缓冲上限(背压:满则丢最旧并计数,防慢库拖爆内存) */
@@ -416,7 +426,9 @@ class DaqController {
     // 指标阈值告警(模板 metrics 规则;alarm 硬限边沿 → 既有告警链路)
     this.evaluateMetricAlarms(node, tpl, metrics)
     if (!allowPublish) return
-    const payload: AepDaqFrame = {
+    // lineId 是 WS 逐产线扇出的依据(scene-events.payloadLineId 读的就是 payload.lineId,
+    // 与 AepDaqReading.lineId 同义);AepDaqFrame 协议类型漏了该字段 —— 见报告。
+    const payload: AepDaqFrame & { lineId: string | null } = {
       nodeId: node.id,
       templateRef: node.templateRef,
       kind: f.kind,
@@ -694,7 +706,7 @@ class DaqController {
 
   /** 同绑定 siblings 缓存(1s TTL):回写热路径不再逐样本全量 scan,O(N²)→O(N)/周期。
    *  用有界 LRU 而非「超 500 整体 clear()」——后者会造成周期性全量缓存穿透。 */
-  private siblingsCache = new LruMap<string, { at: number, list: DaqNode[] }>(500)
+  private siblingsCache: LruLike<string, { at: number, list: DaqNode[] }> = new LruMap(500)
 
   private siblingsOf(bindingId: string): DaqNode[] {
     const hit = this.siblingsCache.get(bindingId)
@@ -759,7 +771,10 @@ class DaqController {
     this.broadcast = fn
   }
 
-  controllerState(): AepDaqControllerState & { produced?: number, consumed?: number, dropped?: number, samplesStored?: number, tsdbDropped?: number } {
+  /** 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()
@@ -1201,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 幂等供给) ----------
 
   /**

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

@@ -10,9 +10,9 @@
  */
 
 import { applyTransform } from '../../../../shared/daq-protocol'
-import { classifyCommError } from './drivers'
+import { classifyCommError, type DaqFrameSample } from './drivers'
 import type { DaqNode } from './daq-node'
-import type { DaqFrameSample, DaqSampleEnvelope } from './bus/queue-port'
+import type { DaqSampleEnvelope } from './bus/queue-port'
 
 /** 驱动故障广播节流(ms;每运行时独立计时) */
 const ERR_THROTTLE_MS = 30_000
@@ -94,7 +94,9 @@ export class DaqNodeRuntime {
     if (now < this.lastSampleAt + node.effectiveInterval(defs.intervalMs, defs.minIntervalMs)) return
     this.sampling = true
     try {
-      let v: number | DaqFrameSample | null = null
+      // 生产面可能返回三种形态:标量 / 驱动原生帧(DaqFrameSample)/ 生产侧已剥离 blob 的帧信封
+      // (与 DaqRuntimeHost.sample 的返回面一致 —— 后者不能丢,否则帧信封分支拿不到 kind/points)
+      let v: number | DaqFrameSample | { frame: NonNullable<DaqSampleEnvelope['frame']> } | null = null
       try {
         v = await this.host.sample(node, now)
       }

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

@@ -17,7 +17,7 @@
 import { createLogger } from '../logger'
 import { createRequire } from 'node:module'
 import { encodePng } from './png-enc'
-import type { DaqDriverKind, DriverTestResult } from '../../../../shared/daq-protocol'
+import { DAQ_DRIVERS, type DaqDriverKind, type DriverTestResult } from '../../../../shared/daq-protocol'
 
 const log = createLogger('daq.drivers')
 
@@ -200,8 +200,17 @@ function mockImageSample(
 // Modbus TCP 真实驱动(modbus-serial;连接池按 host:port:unitId 复用)
 // ============================================================
 
+/**
+ * modbus-serial 客户端实例类型。
+ *
+ * 该包 index.d.ts 只写 `import { ModbusRTU } from "./ModbusRTU"` + `export default ModbusRTU`,
+ * **没有**具名 re-export(运行时 module.exports = 构造器,并自挂 module.exports.default = 自己),
+ * 因此 `import('modbus-serial').ModbusRTU` 在类型上并不存在 —— 从 default 导出取才与实际导出形态一致。
+ */
+type ModbusRtuClient = InstanceType<typeof import('modbus-serial').default>
+
 export interface ModbusConn {
-  client: import('modbus-serial').ModbusRTU
+  client: ModbusRtuClient
   lastUsed: number
   /** 连接级操作队列尾(采/控共用链路串行化:TCP 网关并发事务会协议错乱) */
   tail: Promise<unknown>
@@ -232,7 +241,7 @@ export function evictModbusConn(cfg: Record<string, unknown>, transport: ModbusT
  * 安全关闭:半开 socket(对端断电)时 modbus-serial close() 等待 FIN 永不返回,
  * 一律 500ms 超时保护(fire-and-forget 底层 close,调用方不阻塞)。
  */
-export async function closeModbusSafely(client: import('modbus-serial').ModbusRTU): Promise<void> {
+export async function closeModbusSafely(client: ModbusRtuClient): Promise<void> {
   await Promise.race([
     Promise.resolve()
       .then(() => client.close())
@@ -252,7 +261,7 @@ export function withModbusConn<R>(conn: ModbusConn, fn: () => Promise<R>): Promi
   const run = conn.tail.then(() => fn(), () => fn())
   let timer: NodeJS.Timeout | undefined
   let dead = false
-  const guarded = Promise.race([
+  const guarded: Promise<R> = Promise.race([
     run,
     new Promise<never>((_, rej) => {
       timer = setTimeout(() => {
@@ -264,7 +273,7 @@ export function withModbusConn<R>(conn: ModbusConn, fn: () => Promise<R>): Promi
         rej(new Error('Modbus 响应超时(3s)——连接可能半开,已作废重连'))
       }, 3000)
     }),
-  ] as Promise<R>)
+  ])
   void guarded.catch(() => { /* 超时分支先 reject,防 unhandled */ })
   conn.tail = guarded.then(
     () => {
@@ -298,7 +307,7 @@ export async function getModbusConn(cfg: Record<string, unknown>, transport: Mod
   }
   // CJS 互操作:require 形状可能是 { ModbusRTU } / default.ModbusRTU / 构造器本身
   const mod = reqNative('modbus-serial') as unknown as { ModbusRTU?: unknown, default?: { ModbusRTU?: unknown } | unknown }
-  const ModbusRTU = (mod.ModbusRTU ?? (mod.default as { ModbusRTU?: unknown } | undefined)?.ModbusRTU ?? mod) as new () => import('modbus-serial').ModbusRTU
+  const ModbusRTU = (mod.ModbusRTU ?? (mod.default as { ModbusRTU?: unknown } | undefined)?.ModbusRTU ?? mod) as new () => ModbusRtuClient
   const client = new ModbusRTU()
   client.setTimeout(3000)
   // tcp = Modbus TCP(MBAP 封装);rtu-tcp = RTU over TCP(串口网关透传,CRC16 帧,无 MBAP)
@@ -490,6 +499,17 @@ export interface OpcUaConn {
 
 const opcuaPool = new Map<string, OpcUaConn>()
 
+/**
+ * 在飞建连去重表（同池 key → 尚未 settle 的建连任务）。
+ *
+ * 修复动因(实测事故):同端点**并发首连**此前无去重——两条采样/写控请求同时进入时
+ * 各建一条 OPCUAClient,而后一条的 `opcuaPool.set` 会**覆盖**前一条:
+ * 被覆盖的 session 与 TCP 连接从此无人持有,空闲 sweep 也扫不到 → **永久泄漏**;
+ * 重连 churn(断链演练/反复建节点)下还会触发 node-opcua 内部
+ * `_internal_create_secure_channel failed, this._secureChannel is supposed to be null`。
+ */
+const opcuaInflight = new Map<string, Promise<OpcUaConn>>()
+
 // OPC UA 会话空闲回收(对照 modbus 池 sweep;节点删除/端点弃用后不再有读取
 // 路径触发 3 错误驱逐,无 sweep 会话与 TCP 连接会永久驻留)
 const OPCUA_IDLE_MS = 600_000
@@ -533,6 +553,20 @@ export async function getOpcUaConn(cfg: Record<string, unknown>): Promise<OpcUaC
     existing.lastUsed = Date.now()
     return existing
   }
+  // 在飞去重:同 key 并发首连复用同一条建连任务(否则后写覆盖 pool → 前一条 session/socket 永久泄漏)
+  const pending = opcuaInflight.get(key)
+  if (pending) return pending
+  const task = createOpcUaConn(cfg, key)
+  opcuaInflight.set(key, task)
+  try {
+    return await task
+  }
+  finally {
+    opcuaInflight.delete(key)
+  }
+}
+
+async function createOpcUaConn(cfg: Record<string, unknown>, key: string): Promise<OpcUaConn> {
   const opcua = reqNative('node-opcua') as typeof import('node-opcua')
   const securityMode = (['None', 'Sign', 'SignAndEncrypt'] as const).includes(cfg.securityMode as 'None')
     ? (cfg.securityMode as 'None')
@@ -574,15 +608,33 @@ export async function getOpcUaConn(cfg: Record<string, unknown>): Promise<OpcUaC
   }
   const client = opcua.OPCUAClient.create(clientOpts as Parameters<typeof opcua.OPCUAClient.create>[0])
   await client.connect(String(cfg.endpoint))
+  // type 是 node-opcua 的 UserIdentityInfo 判别式(node-opcua-client createUserIdentityToken →
+  // coerceUserIdentityInfo:userName 存在时正是补成 UserTokenType.UserName 走同一分支),
+  // 显式写出既满足协议类型,也免去"字段漏写、等库回填"的隐式依赖;两个分支都返回 Promise<ClientSession>。
   const session = cfg.username
-    ? await client.createSession({ userName: String(cfg.username), password: String(cfg.password ?? '') })
+    ? await client.createSession({ type: opcua.UserTokenType.UserName, userName: String(cfg.username), password: String(cfg.password ?? '') })
     : await client.createSession()
   const conn: OpcUaConn = { session, client, lastUsed: Date.now(), errors: 0 }
+  // 竞态二次校验:建连期间若已有连接入池(并发首连的另一方完成),关闭本次新建并复用既有,
+  // 避免 opcuaPool.set 覆盖导致 session/socket 永久泄漏。
+  const raced = opcuaPool.get(key)
+  if (raced) {
+    try {
+      await session.close()
+    }
+    catch { /* 清理失败不覆盖原始错误 */ }
+    try {
+      await client.disconnect()
+    }
+    catch { /* 清理失败不覆盖原始错误 */ }
+    return raced
+  }
   opcuaPool.set(key, conn)
   return conn
 }
 
-/** 驱逐 OPC UA 连接(采样/写控共享池;连续故障后触发,下次调用重建) */
+/** 驱逐 OPC UA 连接(采样/写控共享池;连续故障后触发,下次调用重建)。
+ *  只作用于**已入池**的连接:在飞建连本身就是新建的,交由竞态二次校验处理。 */
 export async function evictOpcUaConn(cfg: Record<string, unknown>): Promise<void> {
   const key = opcuaKey(cfg)
   const conn = opcuaPool.get(key)
@@ -961,7 +1013,10 @@ export const httpDaqDriver: DaqDriver = {
           return { ok: true, message: `接口可达,vector 帧 ${(j.points as unknown[]).length} 点`, latencyMs: Date.now() - t0 }
         }
         if (typeof j.png === 'string' || typeof j.blob === 'string') {
-          return { ok: true, message: `接口可达,image 帧(base64, ${(j.png ?? j.blob as string).length} chars)`, latencyMs: Date.now() - t0 }
+          // 与生产分支同构: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 }
@@ -1020,16 +1075,64 @@ function pluginRegistry(): Map<string, DaqDriver> {
   return g_plugins.__daqPluginDrivers ??= new Map()
 }
 
+/**
+ * 插件驱动的自描述目录(前端「添加节点」下拉与动态参数表单的数据源)。
+ * 插件驱动在 DaqDriver 上携带可选 meta(label/status/configFields,与 DaqDriverMeta 同形、
+ * kind 放宽为 string);未带 meta 的插件驱动只在 meta.pluginDrivers 里以 kind 出现,
+ * 前端能感知存在但不出表单(如实降级,不猜测参数 schema)。
+ */
+export interface PluginDriverMeta {
+  kind: string
+  label: string
+  status: 'builtin' | 'real' | 'planned'
+  configFields?: import('../../../../shared/daq-protocol').DriverConfigField[]
+  /** true = 来自插件协议插件(前端展示「插件」徽标) */
+  plugin: true
+}
+
+const g_metas = globalThis as typeof globalThis & { __daqPluginDriverMetas?: Map<string, PluginDriverMeta> }
+function pluginMetaRegistry(): Map<string, PluginDriverMeta> {
+  return g_metas.__daqPluginDriverMetas ??= 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)
+  const meta = (driver as DaqDriver & { meta?: Omit<PluginDriverMeta, 'kind' | 'plugin'> }).meta
+  if (meta && typeof meta.label === 'string') {
+    pluginMetaRegistry().set(driver.kind, {
+      kind: driver.kind,
+      label: meta.label,
+      status: meta.status === 'builtin' || meta.status === 'planned' ? meta.status : 'real',
+      configFields: Array.isArray(meta.configFields) ? meta.configFields : [],
+      plugin: true,
+    })
+  }
+  else {
+    // 同名驱动重注册(热重载)可能这次不带 meta:旧 meta 一并清除,保持两边一致
+    pluginMetaRegistry().delete(driver.kind)
+  }
 }
 
 export function listPluginDrivers(): string[] {
   return [...pluginRegistry().keys()]
 }
 
+/**
+ * 清空插件驱动与自描述目录(插件宿主热重载前调用):停用/卸载的插件驱动随之失效,
+ * 只有本轮重新装载成功的插件驱动会再注册进来 —— 否则被停用的驱动会一直生效到进程重启。
+ */
+export function clearPluginDrivers(): void {
+  pluginRegistry().clear()
+  pluginMetaRegistry().clear()
+}
+
+/** 插件驱动自描述目录(驱动目录合并端点用;热重载随重注册刷新) */
+export function listPluginDriverMetas(): PluginDriverMeta[] {
+  return [...pluginMetaRegistry().values()]
+}
+
 export function normalizeDriverKind(kind: string): DaqDriverKind {
   if (kind === 'modbus') return 'modbus-tcp'
   if (kind === 'rtu' || kind === 'modbus-rtu-tcp') return 'modbus-rtu'
@@ -1040,10 +1143,11 @@ export function resolveDaqDriver(kind: DaqDriverKind): DaqDriver {
   return pluginRegistry().get(kind) ?? REGISTRY[kind] ?? mockDaqDriver
 }
 
-/** 驱动可用性探测(meta 报告:包缺失时 UI 显示"未安装"而非硬失败) */
+/** 驱动可用性探测(meta 报告:包缺失时 UI 显示"未安装"而非硬失败;含插件驱动) */
 export async function probeDriverAvailability(): Promise<Record<string, boolean>> {
   const out: Record<string, boolean> = {}
-  for (const [kind, drv] of Object.entries(REGISTRY)) {
+  const all: Array<[string, DaqDriver]> = [...Object.entries(REGISTRY), ...pluginRegistry()]
+  for (const [kind, drv] of all) {
     try {
       out[kind] = await drv.available()
     }
@@ -1053,3 +1157,29 @@ export async function probeDriverAvailability(): Promise<Record<string, boolean>
   }
   return out
 }
+
+/**
+ * 驱动目录合并(内置 DAQ_DRIVERS + 插件自描述;同名插件条目覆盖内置并标记 plugin)。
+ * index.get.ts 以 `drivers` 下发,前端据此渲染「添加节点」下拉与动态参数表单。
+ */
+export async function driverCatalog(): Promise<Array<{
+  kind: string
+  label: string
+  status: 'builtin' | 'real' | 'planned'
+  configFields: import('../../../../shared/daq-protocol').DriverConfigField[]
+  plugin?: boolean
+}>> {
+  const out: Array<{ kind: string, label: string, status: 'builtin' | 'real' | 'planned', configFields: import('../../../../shared/daq-protocol').DriverConfigField[], plugin?: boolean }> = DAQ_DRIVERS.map(d => ({
+    kind: d.kind,
+    label: d.label,
+    status: d.status,
+    configFields: d.configFields,
+  }))
+  for (const m of listPluginDriverMetas()) {
+    const i = out.findIndex(d => d.kind === m.kind)
+    const entry = { kind: m.kind, label: m.label, status: m.status, configFields: m.configFields ?? [], plugin: true }
+    if (i >= 0) out[i] = entry
+    else out.push(entry)
+  }
+  return out
+}

package/server/services/workshop/daq/host-ports.ts

@@ -20,10 +20,11 @@ export interface ActiveRunSnapshot {
 /** 遥测上报端口:绑定设备的值回写 + 孪生场景推送 + 绑定校验(中心实现 = device-twin.repo) */
 export interface DaqTelemetryPort {
   /**
-   * 遥测回写:telemetry 键值写入绑定设备的孪生,state 为同设备多节点汇聚的最严重态。
+   * 遥测回写:telemetry 键值写入绑定设备的孪生,state 为同设备多节点汇聚的最严重态
+   * (alarm > warn > ok,与 device-twin.repo.applyTelemetry 的 nodeState 同一个域)。
    * 目标设备不存在 → { ok:false }(调用方解绑自身,链路自愈);成功 → { ok:true, twinId }。
    */
-  applyTelemetry(deviceId: string, telemetry: Record<string, number | string | boolean>, state: string): { ok: boolean, twinId: string | null }
+  applyTelemetry(deviceId: string, telemetry: Record<string, number | string | boolean>, state: 'alarm' | 'warn' | 'ok'): { ok: boolean, twinId: string | null }
   /** 孪生场景载荷(WS device.updated 帧;设备已删 → null) */
   scenePayload(twinId: string): unknown | null
   /** 绑定目标存在性校验 */

package/server/services/workshop/daq/storage/timescale.adapter.ts

@@ -239,7 +239,9 @@ export class TimescaleAdapter implements TsdbPort {
       at: tsToMs(r.ts),
       kind: String(r.kind) as 'vector' | 'image',
       points: String(r.kind) === 'vector' ? pointsFromMeta(r.meta) : undefined,
-      metrics: asObject(r.metrics),
+      // 与 sqlite.adapter 同法:metrics 列由本管线写入(下沉处理器产出 avg/max/brightness/zone_* 数值),
+      // asObject 只做 JSON 还原(Record<string, unknown>),按端口契约收窄到 Record<string, number>(断言运行时擦除)
+      metrics: asObject(r.metrics) as Record<string, number>,
       meta: asObject(r.meta),
       deviceBindingId: r.device_binding_id ?? null,
       lineId: r.line_id ?? null,

package/server/services/workshop/db/channel.repo.ts

@@ -54,6 +54,10 @@ export function createChannelRepo(db: DatabaseSync) {
         name: input.name,
         description: input.description ?? '',
         scenarioPrompt: input.scenarioPrompt ?? '',
+        // INSERT 不含该列 → 落库取列默认(llm_json TEXT NOT NULL DEFAULT '',见 database.ts v11);
+        // 返回的内存行按同一事实补该列,使 create() 的返回值与随后 findById() 读到的行形状一致。
+        // 注意:insert.run(...) 的参数列表保持不变(多传一个参数会与 SQL 占位符数量不符)。
+        llmJson: '',
         leadAgentId: null,
         workspace: input.workspace ?? '',
         enabled: 1,