agentworkshop 0.7.39 → 0.7.40

package/server/services/workshop/agents/industrial-tools.ts

@@ -19,6 +19,9 @@ import { daqRuntimeSettings } from '../settings'
 import { getDaqNodeRepo } from '../daq/daq-node.repo'
 import { findDaqTemplate } from '../daq/daq-templates'
 import { getRecipeRollBackManager } from '../dcw/recipe-rollback-manager'
+import { getDcwParamRepo } from '../dcw/param-map.repo'
+import { limitsBreakdownOf } from '../dcw/param-limits'
+import type { DcwParamView } from '../../../../shared/dcw-protocol'
 import { getOps, recordOps } from '../ops/ops'
 import { getDcwLineRepo } from '../dcw/dcw-line.repo'
 import { getDcwProductRepo } from '../dcw/dcw-product.repo'
@@ -75,7 +78,10 @@ export async function toolMyIndustrialNodes(agentId: string): Promise<{ text: st
 ---
 通用规则:
 1. 一个 Agent 可绑定多个节点;先读本清单理解每个节点的物理意义与操作守则,再动手。
-2. 数控下发 dcw_control(node_id, value):目标值必须落在「安全量程 ∩ 活动配方工艺窗口」;单次调幅建议按语义卡的步进指引。下发前/后用 dcw_read(node_id) 读 PLC 当前值取证复核(被动观测免审批)。
+2. 数控下发优先用 param_control(param, value) 以**工艺参数**寻址(key 语义稳定,跨批次/换配方不变);
+   dcw_control(node_id, value) 为节点直接寻址的兼容面。设定值受四层限界联锁
+   (节点安全量程 ∩ 工艺参数基准限界 ∩ 活动产品限界 ∩ 活动配方工艺窗口)逐层收窄,
+   越界一律拒绝 —— 用户与 Agent 一体约束,无旁路。下发前/后用 param_read(param) 读 PLC 当前值取证复核(被动观测免审批)。
 3. 数据获取 daq_query(不传 node_id = 全部数采节点),支持按产线/产品/配方/时间检索;解读数据时结合语义卡的判读方法。
 4. 改动设定后等待工艺响应(热惯性/传动惯量)再评估,避免连续大幅调整。
 5. 调控闭环:每次下发自动开一条优化记录(open);观察数采后用 dcw_judge 落判定(keep/rollback/uncertain);
@@ -130,11 +136,8 @@ export async function toolDcwControl(agentId: string, args: { node_id?: string,
     if (approvals.hasPendingFor(agentId, nodeId)) {
       return { text: `你对该节点已有一条待审批的下发指令,请等待用户处理后再发新指令(避免审批堆积)。`, isError: true }
     }
-    const run = node.lineId ? getActiveLineRun(node.lineId) : null
-    const recipe = run ? getDcwController().listRecipes().find(r => r.id === run.recipeId) : undefined
-    const param = recipe?.params.find(p => p.nodeId === nodeId)
-    const detail = `${node.name}(${tpl?.ch ?? node.templateKey})设定 ${value}${node.unit}`
-      + (param && (param.min != null || param.max != null) ? `,配方窗口 ${param.min ?? '-∞'}~${param.max ?? '+∞'}${node.unit}` : `,安全量程 ${node.min}~${node.max}${node.unit}`)
+    const bd = limitsBreakdownOf(node)
+    const detail = `${node.name}(${tpl?.ch ?? node.templateKey})设定 ${value}${node.unit},有效写入区间 ${bd.effective.min}~${bd.effective.max}${node.unit}(${bd.layers.map(l => l.label).join(' ∩ ')})`
     const ap = await approvals.request(agentId, nodeId, 'dcw', detail)
     if (!ap.approved) {
       return { text: `指令未执行:用户${ap.comment.includes('超时') ? '未在时限内批准(超时)' : `拒绝了本次下发`}。用户备注:${ap.comment || '(无)'}` }
@@ -236,6 +239,161 @@ function writeToleranceOf(node: { decimals: number, min: number, max: number }):
   return Math.max(0.5 * 10 ** -node.decimals, (node.max - node.min) * 0.005)
 }
 
+/** 工艺参数解析(param_control/param_read 共用):pp-id 优先,其次按 key;跨产线同名需 line_id 消歧 */
+function resolveParamRef(ref: string, lineId?: string): { ok: true, param: DcwParamView } | { ok: false, text: string, isError: true } {
+  const repo = getDcwParamRepo()
+  const trimmed = String(ref ?? '').trim()
+  if (!trimmed) {
+    return { ok: false, text: 'param 必填:工艺参数 id(pp-*)或参数 key(见 my_industrial_nodes)。', isError: true }
+  }
+  const row = trimmed.startsWith('pp-') ? repo.byId(trimmed) : undefined
+  if (row) {
+    const view = repo.viewOf(row)
+    if (!view) return { ok: false, text: `工艺参数 ${trimmed} 的执行节点已不存在(映射悬空)。`, isError: true }
+    if (lineId && view.lineId !== lineId) {
+      return { ok: false, text: `工艺参数 ${view.key} 不属于产线 ${lineId}(实际归属:${view.lineId || '未分配'})。`, isError: true }
+    }
+    return { ok: true, param: view }
+  }
+  const hits = repo.byKey(trimmed)
+    .map(r => repo.viewOf(r))
+    .filter((v): v is DcwParamView => v != null)
+  const scoped = lineId ? hits.filter(v => v.lineId === lineId) : hits
+  if (scoped.length === 1) return { ok: true, param: scoped[0]! }
+  if (scoped.length === 0) {
+    const catalog = repo.listViews().slice(0, 12).map(v => `${v.key}(${v.name})`).join('、')
+    return { ok: false, text: `未找到工艺参数「${trimmed}」${lineId ? `(产线 ${lineId})` : ''}。可用参数:${catalog || '无 —— 请先让用户创建写控节点生成参数面'}。`, isError: true }
+  }
+  return { ok: false, text: `工艺参数「${trimmed}」命中 ${scoped.length} 条同名映射,请附加 line_id 消歧或改用参数 id(${scoped.map(v => v.id).join(' / ')})。`, isError: true }
+}
+
+/** 参数面权限摘要(工具回包统一口径;不透出寄存器等 PLC 寻址细节) */
+function paramLimitsText(param: DcwParamView): string {
+  const node = getDcwController().byId(param.nodeId)
+  if (!node) return '执行节点已删除'
+  const bd = limitsBreakdownOf(node)
+  const layers = bd.layers.filter(l => l.min != null || l.max != null).map(l => l.label).join(' ∩ ')
+  return `有效写入区间 ${bd.effective.min}~${bd.effective.max}${param.unit}(约束层:${layers || '无'})`
+}
+
+/** 工具:param_control —— 按工艺参数下发设定值(推荐的参数语义寻址面)。
+ *  权限沿用节点绑定(参数 → 执行节点);限界联锁(参数基准 ∩ 产品 ∩ 配方 ∩ 节点安全量程)
+ *  在网关咽喉点统一生效。args.hypothesis 声明本次假设(入册),args.task_id 关联任务。 */
+export async function toolParamControl(agentId: string, args: {
+  param?: string
+  value?: number | string
+  hypothesis?: string
+  task_id?: string
+  line_id?: string
+}): Promise<{ text: string, isError?: boolean }> {
+  const resolved = resolveParamRef(String(args.param ?? ''), args.line_id ? String(args.line_id) : undefined)
+  if (!resolved.ok) return resolved
+  const param = resolved.param
+  const value = Number(args.value)
+  if (!Number.isFinite(value)) {
+    return { text: '设定值 value 必须为数字。', isError: true }
+  }
+  const repo = getAgentNodeBindingRepo()
+  const binding = repo.find(agentId, param.nodeId, 'dcw')
+  if (!binding) {
+    const mine = repo.byAgent(agentId).filter(b => b.kind === 'dcw')
+    return {
+      text: mine.length
+        ? `无权操作工艺参数「${param.key}」(执行节点 ${param.nodeId} 未绑定给你)。你有权控制的数控节点:${mine.map(b => b.nodeId).join(', ')}。`
+        : '你尚未绑定任何数控节点,无权下发控制指令。请在数字孪生界面绑定数控节点。',
+      isError: true,
+    }
+  }
+  const node = getDcwController().byId(param.nodeId)
+  if (!node) {
+    repo.removeAgentNode(agentId, param.nodeId, 'dcw')
+    return { text: `工艺参数「${param.key}」的执行节点已不存在(可能被删除),原绑定已自动清理。`, isError: true }
+  }
+  if (!node.enabled) {
+    return { text: `工艺参数「${param.key}」的执行节点「${node.name}」已停用(控制已暂停),无法下发。`, isError: true }
+  }
+  // 手动确认模式:与 dcw_control 同源审批面,备注回给 Agent
+  if (binding.mode === 'manual') {
+    const approvals = getToolApprovals()
+    if (approvals.hasPendingFor(agentId, param.nodeId)) {
+      return { text: '你对该执行节点已有一条待审批的下发指令,请等待用户处理后再发新指令(避免审批堆积)。', isError: true }
+    }
+    const detail = `工艺参数「${param.key}」(${param.name})设定 ${value}${param.unit},${paramLimitsText(param)}`
+    const ap = await approvals.request(agentId, param.nodeId, 'dcw', detail)
+    if (!ap.approved) {
+      return { text: `指令未执行:用户${ap.comment.includes('超时') ? '未在时限内批准(超时)' : `拒绝了本次下发`}。用户备注:${ap.comment || '(无)'}` }
+    }
+    if (!repo.find(agentId, param.nodeId, 'dcw')) {
+      return { text: '指令未执行:审批通过时你的该节点绑定已被解除(权限在批准时失效)。', isError: true }
+    }
+  }
+  try {
+    const meta = {
+      source: 'agent' as const,
+      actor: agentId,
+      actorName: agentBadgeLabel(agentId),
+      taskId: args.task_id ? String(args.task_id) : undefined,
+      hypothesis: args.hypothesis ? String(args.hypothesis) : '',
+    }
+    const outcome = await getDcwController().writeParam(param.id, value, meta)
+    if (outcome.ok) {
+      const stable = getRecipeRollBackManager().journal({ nodeId: param.nodeId, limit: 10 }).find(a => a.prevValue != null && a.prevValue !== a.newValue)
+      const loopTxt = [
+        outcome.recordId ? `优化记录 ${outcome.recordId} 已开窗(观察数采后 dcw_judge 落判定)` : null,
+        stable ? `上一稳定锚:${stable.prevValue}${param.unit}(可 dcw_rollback 回退)` : null,
+      ].filter(Boolean).join(';')
+      return {
+        text: `下发成功:工艺参数「${param.key}」(${param.name})设定 ${value}${param.unit} → 执行节点「${node.name}」;回读 ${outcome.readback != null ? `${outcome.readback}${param.unit}` : '不支持'}一致。${paramLimitsText(param)}。${outcome.message}${loopTxt ? `\n[调控闭环] ${loopTxt}` : ''}`,
+      }
+    }
+    return { text: `下发失败:${outcome.message}(工艺参数 ${param.key},执行节点「${node.name}」;${paramLimitsText(param)};当前设定值保持 ${node.value ?? '原值'}${param.unit} 未被改动)`, isError: true }
+  }
+  catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return { text: `下发被拒绝:${msg}(工艺参数 ${param.key};${paramLimitsText(param)})`, isError: true }
+  }
+}
+
+/** 工具:param_read —— 按工艺参数读取 PLC 当前值(被动观测免审批) */
+export async function toolParamRead(agentId: string, args: {
+  param?: string
+  line_id?: string
+}): Promise<{ text: string, isError?: boolean }> {
+  const resolved = resolveParamRef(String(args.param ?? ''), args.line_id ? String(args.line_id) : undefined)
+  if (!resolved.ok) return resolved
+  const param = resolved.param
+  const repo = getAgentNodeBindingRepo()
+  if (!repo.find(agentId, param.nodeId, 'dcw')) {
+    const mine = repo.byAgent(agentId).filter(b => b.kind === 'dcw')
+    return {
+      text: mine.length
+        ? `无权读取工艺参数「${param.key}」(执行节点 ${param.nodeId} 未绑定给你)。你有权读取的数控节点:${mine.map(b => b.nodeId).join(', ')}。`
+        : '你尚未绑定任何数控节点,无权读取控制通道数据。请在数字孪生界面绑定数控节点。',
+      isError: true,
+    }
+  }
+  const node = getDcwController().byId(param.nodeId)
+  if (!node) {
+    repo.removeAgentNode(agentId, param.nodeId, 'dcw')
+    return { text: `工艺参数「${param.key}」的执行节点已不存在(可能被删除),原绑定已自动清理。`, isError: true }
+  }
+  try {
+    const read = await getDcwController().readParam(param.id)
+    if (!read.ok && read.value == null && !node.readValue) {
+      return { text: `读取失败:${read.message}(执行节点「${node.name}」驱动 ${node.driver} 可能不支持读取;可改用 daq_query 查关联数采通道)`, isError: true }
+    }
+    const readTxt = read.value != null
+      ? `${Number(read.value.toFixed(param.decimals))}${param.unit} @ ${read.at.slice(11, 19)}`
+      : (node.readValue != null ? `${node.readValue}${param.unit}(最近一次)` : '无读数')
+    return {
+      text: `读取成功:工艺参数「${param.key}」(${param.name})\n  PLC 读数(ACT): ${readTxt}\n  当前设定(SET): ${node.value != null ? `${node.value}${param.unit}` : '从未下发'}\n  ${paramLimitsText(param)}`,
+    }
+  }
+  catch (err) {
+    return { text: `读取被拒绝:${err instanceof Error ? err.message : String(err)}(工艺参数 ${param.key})`, isError: true }
+  }
+}
+
 /**
  * 数采目标集解析(工具共用鉴权面):Agent 绑定(kind=daq)为权限边界 ——
  * node_id/line_id 只能缩小范围,不能放大(越权节点一律拒绝)。

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

@@ -18,7 +18,7 @@
  * 与 codex/dsh/opencode impl 全引擎一致。协议权威:omp://rpc.md。
  */
 import { createLogger } from '../logger'
-import { BaseAgentImpl } from './base-agent'
+import { BaseAgentImpl, type BaseAgentConfigView } from './base-agent'
 import { randomUUID } from 'node:crypto'
 import type {
   AgentEvent,
@@ -133,8 +133,8 @@ export class OmpRpcAgentImpl extends BaseAgentImpl implements AgentInterface {
     return 'omp'
   }
 
-  protected configRecord(): Record<string, unknown> {
-    return this.config as unknown as Record<string, unknown>
+  protected configRecord(): BaseAgentConfigView {
+    return this.config
   }
 
   /**
@@ -205,7 +205,9 @@ export class OmpRpcAgentImpl extends BaseAgentImpl implements AgentInterface {
   /** 当前回合产生的 assistant 文本(供诊断) */
   private turnText = ''
   /** agent 身份信息(factory 注入;无需等待 init()) */
-  private agentRole: 'lead' | 'worker' = 'worker'
+  // agentRole 由 BaseAgentImpl 持有(protected);同名私有声明会遮蔽基类 identity 角色。
+  // 仅收窄可见性声明,运行时代码不变(构造函数与 ensureClient 仍显式同步)。
+  protected override agentRole: 'lead' | 'worker' = 'worker'
 
   // ===== 上下文治理(70% 无中断压缩环)=====
   /** 压缩进行中(平台 gate 与 omp 原生压缩共用互斥位) */
@@ -421,7 +423,7 @@ export class OmpRpcAgentImpl extends BaseAgentImpl implements AgentInterface {
 
   // ===== 生命周期 =====
 
-  async init(input: { agent: AgentInfo, channelId: string }): Promise<void> {
+  override async init(input: { agent: AgentInfo, channelId: string }): Promise<void> {
     this.agentInfo = input.agent
     this.channelId = input.channelId
     this.agentName = input.agent.name
@@ -550,10 +552,13 @@ export class OmpRpcAgentImpl extends BaseAgentImpl implements AgentInterface {
 
   // ===== supervise() =====
 
-  /** supervise 单飞守卫:同一 client 不并发 LLM 回合(残留回合与下一 prompt 混流的根因) */
-  private supervising = false
+  /**
+   * supervise 单飞守卫:同一 client 不并发 LLM 回合(残留回合与下一 prompt 混流的根因)。
+   * 守卫位由 BaseAgentImpl 的 protected supervising 承载 —— 本类原先的私有重复声明与基类构成
+   * "两个私有声明"(TS2415),而 JS 只有一个实例字段,故删除后语义与运行时完全一致。
+   */
 
-  async supervise(snapshot: SupervisionSnapshot, ctx: AgentRunContext, opts?: { signal?: AbortSignal }): Promise<SupervisionDecision[]> {
+  override async supervise(snapshot: SupervisionSnapshot, ctx: AgentRunContext, opts?: { signal?: AbortSignal }): Promise<SupervisionDecision[]> {
     await this.ensureClient(ctx)
     if (!this.client) return []
     if (this.supervising) return [] // 上一轮 supervise 未收口:跳过本拍(节流即正确)
@@ -1109,7 +1114,8 @@ export class OmpRpcAgentImpl extends BaseAgentImpl implements AgentInterface {
       const client = new OmpRpcClient({
         command,
         mode: this.rpcMode,
-        args: [...(this.config.thinkingLevel ? ['--thinking', this.config.thinkingLevel] : [])],
+        // 重复键 args 的生效者是下一行(JS 对象字面量后写覆盖先写):保留生效语义,删除被覆盖项。
+        // (原 ['--thinking', level] 从未真正传给 omp —— 见报告"未修的缺陷"一节。)
         args: this.config.args,
         cwd: this.config.cwd ?? process.cwd(),
         // 进程退出 → 注册表标记(供运行时资源监控);pid=-1 表示无法取得,忽略

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

@@ -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()

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)
       }