agentworkshop 0.7.15 → 0.7.17

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

@@ -11,6 +11,7 @@ import type { AgentNodeBinding } from './node-bindings.repo'
 import { getAgentNodeBindingRepo } from './node-bindings.repo'
 import { getToolApprovals } from './tool-approvals'
 import { nodeSemanticCards } from './industrial-context'
+import { agentBadgeLabel } from './agent-badge'
 import { getDcwController } from '../dcw/dcw-controller'
 import { getActiveLineRun } from '../dcw/line-run'
 import { findDcwTemplate } from '../dcw/dcw-templates'
@@ -18,6 +19,10 @@ 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 { getOps } from '../ops/ops'
+import { getDcwLineRepo } from '../dcw/dcw-line.repo'
+import { getDcwProductRepo } from '../dcw/dcw-product.repo'
+import { getDcwRecipeRepo } from '../dcw/dcw-recipe.repo'
 
 export async function toolMyIndustrialNodes(agentId: string): Promise<{ text: string }> {
   const repo = getAgentNodeBindingRepo()
@@ -65,7 +70,14 @@ export async function toolMyIndustrialNodes(agentId: string): Promise<{ text: st
 4. 改动设定后等待工艺响应(热惯性/传动惯量)再评估,避免连续大幅调整。
 5. 调控闭环:每次下发自动开一条优化记录(open);观察数采后用 dcw_judge 落判定(keep/rollback/uncertain);
    判 rollback 后用 dcw_rollback 执行回退;dcw_journal 可查节点参数变更史。未判定前再下发,旧记录会被标记 superseded。
-   若节点被他人的 open 记录阻塞(对方已消失),超时(30 分钟)后你可接管:dcw_judge 会带接管标记入册。`,
+   若节点被他人的 open 记录阻塞(对方已消失),超时(30 分钟)后你可接管:dcw_judge 会带接管标记入册。
+6. 自查面:line_context 看你控制的产线/产品/配方全景(动手前必读,确认归属);
+   ops_log 查你负责产线的运维日志(谁/何时做了什么,来源区分 Agent/用户/系统;
+   参数 line_id/node_id/kind/actor_kind/minutes/limit/mine);recipe_log 查配方下发与回退事件;
+   recipe_versions 查配方参数版本史(谁改的/为什么/参数 diff)。
+7. 配方操控闭环(在线优化框架):验证过参数更优 → recipe_update 保存进配方(记录你的名字与原因,
+   生成新版本);发现优化有问题 → recipe_rollback 回退到稳定版本(version)或已知良好批次
+   (to_last_good=true);运行中 PLC 当前值用 dcw_control 下发,配方定义供后续批次生效。`,
   }
 }
 
@@ -123,6 +135,8 @@ export async function toolDcwControl(agentId: string, args: { node_id?: string,
     const meta = {
       source: 'agent' as const,
       actor: agentId,
+      // 人话操作者:「Channel名/成员名」——/logs 来源=Agent 与用户/系统操作可区分追溯
+      actorName: agentBadgeLabel(agentId),
       taskId: args.task_id ? String(args.task_id) : undefined,
       hypothesis: args.hypothesis ? String(args.hypothesis) : '',
     }
@@ -355,7 +369,7 @@ export async function toolDcwJudge(agentId: string, args: { record_id?: string,
     return { text: `记录 ${recordId} 不是你发起的优化(发起者:${record.agentId ?? '用户'}),Agent 仅可判定自己的记录;他人记录请请用户在界面判定。`, isError: true }
   try {
     const finalReason = takeover ? `[接管孤儿记录,原属主 ${record.agentId ?? '?'} 超时未判定] ${reason}` : reason
-    const updated = rb.judge(recordId, verdict, finalReason, 'agent', agentId, { takeover })
+    const updated = rb.judge(recordId, verdict, finalReason, 'agent', agentId, { takeover, actorName: agentBadgeLabel(agentId) })
     const next = verdict === 'rollback'
       ? '判定已入册;请立即用 dcw_rollback(record_id) 执行回退(判定不自动改 PLC)。'
       : verdict === 'keep'
@@ -385,10 +399,10 @@ export async function toolDcwRollback(agentId: string, args: { record_id?: strin
       const takeover = record.agentId !== agentId && rb.isStale(record)
       if (record.agentId !== agentId && !takeover)
         return { text: `记录 ${recordId} 不是你发起的优化(发起者:${record.agentId ?? '用户'}),回退他人记录请请用户在数采中心/产线详情执行;若原属主已消失(超时未判定),可先 dcw_judge 接管后再回退。`, isError: true }
-      const fresh = await rb.rollbackRecord(recordId, agentId, 'agent')
+      const fresh = await rb.rollbackRecord(recordId, agentId, 'agent', undefined, { actorName: agentBadgeLabel(agentId) })
       return { text: `回退已执行:记录 ${recordId} 标记 rolled-back;下发恢复值 ${fresh?.params[0]?.to}${'(以回读为准)'};新回退记录 ${fresh?.id} 已入册。请 daq_query 复测确认恢复。` }
     }
-    const fresh = await rb.rollbackNode(nodeId, agentId, 'agent', to)
+    const fresh = await rb.rollbackNode(nodeId, agentId, 'agent', to, { actorName: agentBadgeLabel(agentId) })
     return { text: `节点单步回退已执行:恢复到最近稳定锚值;新回退记录 ${fresh?.id} 已入册。请 daq_query 复测确认恢复。` }
   }
   catch (err) {
@@ -481,3 +495,342 @@ export async function toolDaqFrames(agentId: string, args: {
   }
   return { text: `数采帧查询结果(${targets.length} 个节点):\n\n${sections.join('\n\n')}\n\n向量=多点工程量轮廓(完整点列前端可查);图像=像素在对象存储,指标供判读(brightness 过低=曝光不足/遮挡)。` }
 }
+
+// ================================================================
+// 运维日志 / Recipe 变更史查询(Agent 自查面:负责产线 scoped)
+// ================================================================
+
+/** Agent 负责范围 = 绑定节点的全集(节点 id 集 + 这些节点所属产线集);无绑定 = 无范围 */
+function agentOpsScope(agentId: string): { lineIds: string[], nodeIds: Set<string> } | null {
+  const bindings = getAgentNodeBindingRepo().byAgent(agentId)
+  if (bindings.length === 0) return null
+  const lineIds = new Set<string>()
+  const nodeIds = new Set<string>()
+  for (const b of bindings) {
+    nodeIds.add(b.nodeId)
+    try {
+      const n = b.kind === 'dcw' ? getDcwController().byId(b.nodeId) : getDaqNodeRepo().byId(b.nodeId)
+      if (n?.lineId) lineIds.add(n.lineId)
+    }
+    catch { /* 节点刚被删等情况忽略 */ }
+  }
+  return { lineIds: [...lineIds], nodeIds }
+}
+
+const OPS_ACTOR_LABEL: Record<string, string> = { agent: 'Agent', user: '用户', system: '系统' }
+
+function fmtAuditAt(iso: string): string {
+  return iso.length >= 19 ? iso.slice(5, 19).replace('T', ' ') : iso
+}
+
+/** 工具:ops_log —— 负责产线的运维/审计日志查询(全部下发/判定/回退/配方/产线事件)。
+ *  权限:仅自己绑定节点所覆盖的产线;node_id 须为绑定节点。来源(actor_kind)区分 Agent/用户/系统。 */
+export async function toolOpsLog(agentId: string, args: {
+  line_id?: string
+  node_id?: string
+  kind?: string
+  actor_kind?: string
+  minutes?: number | string
+  limit?: number | string
+  mine?: boolean | string
+}): Promise<{ text: string, isError?: boolean }> {
+  const audit = getOps()?.audit
+  if (!audit) return { text: '审计仓储未装配(服务未就绪),请稍后重试。', isError: true }
+  const scope = agentOpsScope(agentId)
+  if (!scope) return { text: '你尚未绑定任何工业节点,无日志可查(日志权限跟随节点绑定)。', isError: true }
+  const nodeId = String(args.node_id ?? '').trim()
+  const lineId = String(args.line_id ?? '').trim()
+  if (nodeId && !scope.nodeIds.has(nodeId))
+    return { text: `无权查询节点 ${nodeId} 的日志(仅可查自己绑定的节点;用 my_industrial_nodes 查看绑定)。`, isError: true }
+  if (lineId && !scope.lineIds.includes(lineId))
+    return { text: `无权查询产线 ${lineId} 的日志(你的负责产线:${scope.lineIds.join(', ') || '(绑定节点均未分配产线)'})。`, isError: true }
+  const kind = String(args.kind ?? '').trim() || undefined
+  const actorKind = String(args.actor_kind ?? '').trim() || undefined
+  const mine = args.mine === true || args.mine === 'true'
+  const minutes = Number(args.minutes) || 1440
+  const limit = Math.min(Number(args.limit) || 20, 100)
+  const from = new Date(Date.now() - minutes * 60_000).toISOString()
+
+  const lines = lineId ? [lineId] : scope.lineIds
+  const byId = new Map<string, Record<string, unknown>>()
+  for (const lid of lines) {
+    for (const r of audit.query({ lineId: lid, kind, actorKind, actor: mine ? agentId : undefined, from, limit }))
+      byId.set(String(r.id), r)
+  }
+  let rows = [...byId.values()]
+  if (nodeId) rows = rows.filter(r => r.targetId === nodeId)
+  rows.sort((a, b) => String(b.at).localeCompare(String(a.at)))
+  rows = rows.slice(0, limit)
+  if (rows.length === 0) return { text: `窗口(近 ${minutes} 分钟)内无匹配日志。可调大 minutes,或放宽 kind/actor_kind/node_id 过滤。` }
+
+  const body = rows.map((r) => {
+    const src = OPS_ACTOR_LABEL[String(r.actorKind)] ?? String(r.actorKind)
+    return `- [${fmtAuditAt(String(r.at))}] 来源=${src} 操作者=${String(r.actorName) || String(r.actor)} | ${String(r.action)} | ${String(r.summary)}`
+  })
+  const scopeNote = lineId ? `产线 ${lineId}` : `负责产线 ${scope.lineIds.length} 条`
+  return {
+    text: `运维日志(${scopeNote},近 ${minutes} 分钟,${rows.length} 条,新→旧):\n${body.join('\n')}\n\n说明:来源=Agent 的操作者格式为「Channel名/成员名」;需要节点级参数值变更史用 dcw_journal,配方下发/回退专门视图用 recipe_log。`,
+  }
+}
+
+/** 工具:recipe_log —— 负责产线的配方下发与回退历史(recipe.apply + 优化开窗/判定/回退)。
+ *  Agent 据此知道 Recipe 层面发生过哪些下发变更、谁做的、是否已回退。 */
+export async function toolRecipeLog(agentId: string, args: {
+  line_id?: string
+  recipe_id?: string
+  minutes?: number | string
+  limit?: number | string
+}): Promise<{ text: string, isError?: boolean }> {
+  const audit = getOps()?.audit
+  if (!audit) return { text: '审计仓储未装配(服务未就绪),请稍后重试。', isError: true }
+  const scope = agentOpsScope(agentId)
+  if (!scope) return { text: '你尚未绑定任何工业节点,无 Recipe 历史可查(权限跟随节点绑定)。', isError: true }
+  const lineId = String(args.line_id ?? '').trim()
+  if (lineId && !scope.lineIds.includes(lineId))
+    return { text: `无权查询产线 ${lineId} 的 Recipe 历史(你的负责产线:${scope.lineIds.join(', ') || '(无)'})。`, isError: true }
+  const recipeId = String(args.recipe_id ?? '').trim() || undefined
+  const minutes = Number(args.minutes) || 1440
+  const limit = Math.min(Number(args.limit) || 20, 100)
+  const from = new Date(Date.now() - minutes * 60_000).toISOString()
+
+  const lines = lineId ? [lineId] : scope.lineIds
+  const byId = new Map<string, Record<string, unknown>>()
+  for (const lid of lines) {
+    for (const kind of ['recipe', 'rollback']) {
+      for (const r of audit.query({ lineId: lid, kind, recipeId, from, limit }))
+        byId.set(String(r.id), r)
+    }
+  }
+  const rows = [...byId.values()].sort((a, b) => String(b.at).localeCompare(String(a.at))).slice(0, limit)
+  if (rows.length === 0) return { text: `窗口(近 ${minutes} 分钟)内无配方下发/回退记录。可调大 minutes 或换 line_id。` }
+
+  const body = rows.map((r) => {
+    const src = OPS_ACTOR_LABEL[String(r.actorKind)] ?? String(r.actorKind)
+    const action = String(r.action)
+    const tag = action === 'recipe.apply'
+      ? '配方下发'
+      : action === 'optimization.open'
+        ? '优化开窗'
+        : action === 'optimization.judge'
+          ? '优化判定'
+          : action === 'optimization.rollback'
+            ? '回退执行'
+            : action
+    return `- [${fmtAuditAt(String(r.at))}] ${tag} 来源=${src} 操作者=${String(r.actorName) || String(r.actor)} | ${String(r.summary)}${r.recipeId ? `(配方 ${String(r.recipeId).slice(0, 8)})` : ''}`
+  })
+  return {
+    text: `Recipe 变更史(${lineId ? `产线 ${lineId}` : `负责产线 ${scope.lineIds.length} 条`},近 ${minutes} 分钟,${rows.length} 条,新→旧):\n${body.join('\n')}\n\n说明:配方下发=整批参数写命令;优化开窗=单次设定变更(含 Agent 假设);回退执行=已恢复基线值。节点级参数值逐笔历史用 dcw_journal(node_id)。`,
+  }
+}
+
+// ================================================================
+// 产线上下文 + Recipe 版本管理(Agent 操控闭环:知道改什么 → 保存 → 可回退)
+// ================================================================
+
+/** 工具:line_context —— 我控制的产线/产品/Recipe 全景(归属认知 + 完整参数面)。
+ *  逐产线输出:产线名/运行态、活动批次(产品/配方/版本/参数)、我的节点绑定、
+ *  配方目标 vs PLC 当前值对照、lastGood 批次。 */
+export async function toolLineContext(agentId: string, args: { line_id?: string } = {}): Promise<{ text: string, isError?: boolean }> {
+  const scope = agentOpsScope(agentId)
+  if (!scope) return { text: '你尚未绑定任何工业节点,暂无产线上下文(请先在数字孪生界面绑定节点)。' }
+  const wanted = String(args.line_id ?? '').trim()
+  const lineIds = wanted ? [wanted] : scope.lineIds
+  if (wanted && !scope.lineIds.includes(wanted)) {
+    return { text: `产线 ${wanted} 不在你的负责范围(你绑定节点覆盖的产线:${scope.lineIds.join(', ') || '无'})。`, isError: true }
+  }
+  if (lineIds.length === 0) return { text: '你绑定的节点均未分配产线(未挂线的节点没有产线/产品/配方上下文)。' }
+
+  const sections: string[] = []
+  for (const lid of lineIds) {
+    const line = getDcwLineRepo().byId(lid)
+    const run = getActiveLineRun(lid)
+    const recipe = run?.recipeId ? getDcwController().listRecipes().find(r => r.id === run.recipeId) : undefined
+    const parts: string[] = []
+    parts.push(`■ 产线 ${line?.name ?? lid}(${lid})· 状态:${run ? '运行中' : '待机/停线'}`)
+    if (run) {
+      parts.push(`  活动批次 ${run.runId.slice(0, 8)} · 产品「${run.productName}」(${run.productId}) · 开跑 ${run.startedAt.slice(11, 19)} · 已打标 ${run.taggedSamples} 样本`)
+    }
+    const myDcw = getAgentNodeBindingRepo().byAgent(agentId)
+      .filter(b => b.kind === 'dcw')
+      .map(b => getDcwController().byId(b.nodeId))
+      .filter(n => n?.lineId === lid)
+    const myDaq = getAgentNodeBindingRepo().byAgent(agentId)
+      .filter(b => b.kind === 'daq')
+      .map(b => getDaqNodeRepo().byId(b.nodeId))
+      .filter(n => n?.lineId === lid)
+    parts.push(`  我绑定的节点:数控 [${myDcw.map(n => n!.name).join(', ') || '无'}];数采 [${myDaq.map(n => n!.name).join(', ') || '无'}]`)
+    if (recipe) {
+      parts.push(`  配方「${recipe.name}」(${recipe.id}) v${recipe.version ?? 1}${recipe.description ? ` — ${recipe.description}` : ''}`)
+      for (const p of recipe.params) {
+        const node = getDcwController().byId(p.nodeId)
+        const mine = myDcw.some(n => n!.id === p.nodeId)
+        const cur = node?.value != null ? node.value : '?'
+        const win = p.min != null || p.max != null ? `(窗口 ${p.min ?? '-∞'}~${p.max ?? '+∞'})` : ''
+        parts.push(`    · ${node?.name ?? p.nodeId} = ${p.value}${node?.unit ?? ''}${win} | PLC 当前 ${cur}${node?.unit ?? ''}${mine ? ' [我负责]' : ''}`)
+      }
+      const good = recipe.lastGoodRunId ? getDcwRecipeRepo().runById(recipe.lastGoodRunId) : undefined
+      parts.push(`  已知良好批次:${good ? `${good.id.slice(0, 8)}(${good.startedAt.slice(0, 19).replace('T', ' ')})` : '未标记'};当前参数版本 v${recipe.version ?? 1}`)
+    }
+    else {
+      // 无活动批次:列出该产线的配方定义(产线未开跑也有配方上下文)
+      const lineRecipes = getDcwController().listRecipes().filter(r => r.lineId === lid).slice(0, 3)
+      if (lineRecipes.length === 0) {
+        parts.push('  当前无活动配方(产线未开跑;该产线也暂无配方定义)')
+      }
+      else {
+        parts.push(`  当前无活动批次;产线已有 ${lineRecipes.length} 个配方定义(开跑时绑定):`)
+        for (const r of lineRecipes) {
+          const product = r.productId ? getDcwProductRepo().byId(r.productId) : undefined
+          const pp = r.params.map((p) => {
+            const node = getDcwController().byId(p.nodeId)
+            const cur = node?.value != null ? node.value : '?'
+            return `${node?.name ?? p.nodeId}=${p.value}${node?.unit ?? ''}(PLC 当前 ${cur})`
+          }).join(', ')
+          parts.push(`    · 配方「${r.name}」(${r.id}) v${r.version ?? 1} · 产品「${product?.name ?? r.productId}」: ${pp}${r.lastGoodRunId ? ` [良好批次 ${r.lastGoodRunId.slice(0, 8)}]` : ''}`)
+        }
+      }
+    }
+    sections.push(parts.join('\n'))
+  }
+  return {
+    text: `你控制的产线全景(${sections.length} 条):\n\n${sections.join('\n\n')}\n\n说明:配方目标=开跑批次冻结的工艺窗口;PLC 当前值=实时读数。把验证过的最佳参数固化到配方用 recipe_update;回退配方到稳定版本用 recipe_rollback;逐节点参数变更史用 dcw_journal;配方版本史用 recipe_versions。`,
+  }
+}
+
+/** 工具:recipe_versions —— 配方参数版本史(谁/何时/为什么改了什么;旧→新)。
+ *  每条含 by(user/agent/system)、操作者人话名、变更描述、参数 diff。 */
+export async function toolRecipeVersions(agentId: string, args: { recipe_id?: string, limit?: number | string }): Promise<{ text: string, isError?: boolean }> {
+  const recipeId = String(args.recipe_id ?? '').trim()
+  if (!recipeId) return { text: 'recipe_id 必填(line_context 可看到当前配方的 id)。', isError: true }
+  const recipe = getDcwController().listRecipes().find(r => r.id === recipeId)
+  if (!recipe) return { text: `配方 ${recipeId} 不存在。`, isError: true }
+  const scope = agentOpsScope(agentId)
+  if (!scope || !recipe.lineId || !scope.lineIds.includes(recipe.lineId)) {
+    return { text: `无权查看配方 ${recipeId} 的版本史(该配方不在你负责的产线上)。`, isError: true }
+  }
+  const rows = getDcwController().recipeVersions(recipeId)
+  const limit = Math.min(Number(args.limit) || 20, 50)
+  const shown = rows.slice(-limit)
+  const srcLabel: Record<string, string> = { user: '用户', agent: 'Agent', system: '系统' }
+  const lines = shown.map((v, i) => {
+    const prev = shown[i - 1]
+    let diff = '初始版本'
+    if (prev) {
+      const changed = v.params
+        .map(p => ({ p, old: prev.params.find(x => x.nodeId === p.nodeId) }))
+        .filter(({ p, old }) => !old || old.value !== p.value)
+        .map(({ p, old }) => `${getDcwController().byId(p.nodeId)?.name ?? p.nodeId} ${old?.value ?? '新增'}→${p.value}`)
+      const removed = prev.params.filter(o => !v.params.some(x => x.nodeId === o.nodeId)).map(o => `${o.nodeId} 移除`)
+      const all = [...changed, ...removed]
+      diff = all.length > 0 ? `变更:${all.join(';')}` : '参数未变'
+    }
+    const src = v.by ? (srcLabel[v.by] ?? v.by) : '—'
+    return `- v${v.version} [${v.at.slice(0, 19).replace('T', ' ')}] 来源=${src} 操作者=${v.actorName ?? '—'}${v.description ? ` | ${v.description}` : ''}\n    ${diff}`
+  })
+  return {
+    text: `配方「${recipe.name}」版本史(当前 v${recipe.version ?? 1},共 ${rows.length} 条,旧→新):\n${lines.join('\n')}\n\n回退用 recipe_rollback(recipe_id + version 或 to_last_good=true);保存新参数用 recipe_update。`,
+  }
+}
+
+/** 工具:recipe_update —— 把验证过的最佳参数保存进配方(生成新版本,带归因与原因)。
+ *  只改配方定义(下一批次生效);不改运行中 PLC 当前值(那用 dcw_control 逐节点下发)。 */
+export async function toolRecipeUpdate(agentId: string, args: {
+  recipe_id?: string
+  params?: Array<{ node_id?: string, value?: number | string, min?: number | string, max?: number | string }>
+  reason?: string
+  task_id?: string
+}): Promise<{ text: string, isError?: boolean }> {
+  const recipeId = String(args.recipe_id ?? '').trim()
+  const reason = String(args.reason ?? '').trim()
+  if (!recipeId) return { text: 'recipe_id 必填(line_context 可看到当前配方的 id)。', isError: true }
+  if (!reason) return { text: 'reason 必填:保存参数必须说明依据(如数采证据/判定结论),便于版本史追溯。', isError: true }
+  const list = (args.params ?? []).filter(p => p && String(p.node_id ?? '').trim() && Number.isFinite(Number(p.value)))
+  if (list.length === 0) return { text: 'params 至少提供一条 {node_id, value}(value 必须为数字)。', isError: true }
+  const recipe = getDcwController().listRecipes().find(r => r.id === recipeId)
+  if (!recipe) return { text: `配方 ${recipeId} 不存在。`, isError: true }
+  const repo = getAgentNodeBindingRepo()
+  for (const p of list) {
+    const nodeId = String(p.node_id).trim()
+    const node = getDcwController().byId(nodeId)
+    if (!node) return { text: `节点 ${nodeId} 不存在。`, isError: true }
+    if (node.lineId !== recipe.lineId) return { text: `节点「${node.name}」不属于配方「${recipe.name}」所在产线,不可混入。`, isError: true }
+    if (!repo.find(agentId, nodeId, 'dcw')) {
+      return { text: `无权修改节点「${node.name}」的配方参数(仅可改自己绑定 dcw 的节点)。`, isError: true }
+    }
+  }
+  // 部分合并:只更新提供的节点,其余参数保持不变
+  const merged = recipe.params.map((p) => {
+    const patch = list.find(x => String(x.node_id).trim() === p.nodeId)
+    if (!patch) return { nodeId: p.nodeId, templateRef: p.templateRef, value: p.value, min: p.min, max: p.max }
+    const out: { nodeId: string, templateRef?: string, value: number, min?: number, max?: number } = { nodeId: p.nodeId, templateRef: p.templateRef, value: Number(patch.value) }
+    if (p.min != null) out.min = p.min
+    if (patch.min != null && Number.isFinite(Number(patch.min))) out.min = Number(patch.min)
+    if (p.max != null) out.max = p.max
+    if (patch.max != null && Number.isFinite(Number(patch.max))) out.max = Number(patch.max)
+    return out
+  })
+  const extra = list.filter(p => !recipe.params.some(x => x.nodeId === String(p.node_id).trim()))
+  for (const p of extra) merged.push({ nodeId: String(p.node_id).trim(), value: Number(p.value) })
+  try {
+    const updated = getDcwController().updateRecipe(recipeId, { params: merged }, {
+      by: 'agent',
+      actorName: agentBadgeLabel(agentId),
+      actor: agentId,
+      description: reason,
+    })
+    const changedNodes = list.map((p) => {
+      const node = getDcwController().byId(String(p.node_id).trim())
+      const before = recipe.params.find(x => x.nodeId === String(p.node_id).trim())?.value
+      return `${node?.name ?? p.node_id} ${before ?? '?'}→${Number(p.value)}`
+    }).join(';')
+    return {
+      text: `已保存为 v${updated.version ?? 1}:「${updated.name}」参数 ${changedNodes};原因:${reason}。\n注意:配方定义已更新,运行中批次仍按开跑时冻结的参数生产,新参数从下次开跑/一键下发生效;要把新值写入运行中的 PLC,用 dcw_control 逐节点下发(走安全联锁)。回退用 recipe_rollback。`,
+    }
+  }
+  catch (err) {
+    return { text: `保存失败:${err instanceof Error ? err.message : String(err)}`, isError: true }
+  }
+}
+
+/** 工具:recipe_rollback —— 回退配方参数到稳定版本(指定历史版本或已知良好批次快照)。
+ *  生成新版本(非破坏,历史保留);不改运行中 PLC 当前值。 */
+export async function toolRecipeRollback(agentId: string, args: {
+  recipe_id?: string
+  version?: number | string
+  to_last_good?: boolean | string
+  reason?: string
+}): Promise<{ text: string, isError?: boolean }> {
+  const recipeId = String(args.recipe_id ?? '').trim()
+  const reason = String(args.reason ?? '').trim()
+  const toLastGood = args.to_last_good === true || args.to_last_good === 'true'
+  const version = Number(args.version)
+  if (!recipeId) return { text: 'recipe_id 必填。', isError: true }
+  if (!reason) return { text: 'reason 必填:回退必须说明原因(如优化翻车/越限),便于版本史追溯。', isError: true }
+  if (!toLastGood && !Number.isFinite(version)) return { text: '需提供 version(历史版本号)或 to_last_good=true。', isError: true }
+  const recipe = getDcwController().listRecipes().find(r => r.id === recipeId)
+  if (!recipe) return { text: `配方 ${recipeId} 不存在。`, isError: true }
+  const scope = agentOpsScope(agentId)
+  if (!scope || !recipe.lineId || !scope.lineIds.includes(recipe.lineId)) {
+    return { text: `无权回退配方 ${recipeId}(该配方不在你负责的产线上)。`, isError: true }
+  }
+  if (!toLastGood && Number.isFinite(version) && version >= (recipe.version ?? 1)) {
+    return { text: `不能回退到 v${version}(当前已是 v${recipe.version ?? 1};回退目标是更早的版本)。`, isError: true }
+  }
+  try {
+    const updated = getDcwController().revertRecipe(recipeId, {
+      version: toLastGood ? undefined : version,
+      toLastGood,
+    }, {
+      by: 'agent',
+      actorName: agentBadgeLabel(agentId),
+      actor: agentId,
+      description: reason,
+    })
+    return {
+      text: `回退完成:配方「${updated.name}」已生成 v${updated.version ?? 1},参数恢复为目标版本(${toLastGood ? '已知良好批次冻结' : `v${version}`});原因:${reason}。\n运行中批次不受影响(仍按开跑冻结参数);新参数下次开跑生效。版本史用 recipe_versions 复核。`,
+    }
+  }
+  catch (err) {
+    return { text: `回退失败:${err instanceof Error ? err.message : String(err)}`, isError: true }
+  }
+}

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

@@ -228,18 +228,51 @@ export function evictModbusConn(cfg: Record<string, unknown>, transport: ModbusT
   modbusPool.delete(key)
 }
 
+/**
+ * 安全关闭:半开 socket(对端断电)时 modbus-serial close() 等待 FIN 永不返回,
+ * 一律 500ms 超时保护(fire-and-forget 底层 close,调用方不阻塞)。
+ */
+export async function closeModbusSafely(client: import('modbus-serial').ModbusRTU): Promise<void> {
+  await Promise.race([
+    Promise.resolve()
+      .then(() => client.close())
+      .catch(() => { /* 已断 */ }),
+    new Promise((r) => setTimeout(r, 500)),
+  ])
+}
+
 /**
  * 连接级排队执行:操作串行入队,完成后链路归还。
  * 数控写入等当前采样读完成再执行(不再 409 快速失败);数采采样忙时仍跳帧让路防堆积。
+ * per-request 3s 硬超时:半开连接(对端断电/SYN 黑洞)时底层请求永不 settle,
+ * 超时后作废连接并重置 tail 链,防止单条死连接堵死该 host:port 的全部后续请求。
  */
 export function withModbusConn<R>(conn: ModbusConn, fn: () => Promise<R>): Promise<R> {
   conn.pending++
   const run = conn.tail.then(() => fn(), () => fn())
-  conn.tail = run.then(
-    () => { conn.pending-- },
-    () => { conn.pending-- },
-  )
-  return run
+  let timer: NodeJS.Timeout | undefined
+  let dead = false
+  const guarded = Promise.race([
+    run,
+    new Promise<never>((_, rej) => {
+      timer = setTimeout(() => {
+        dead = true
+        try {
+          void conn.client.close()
+        }
+        catch { /* 已断 */ }
+        rej(new Error('Modbus 响应超时(3s)——连接可能半开,已作废重连'))
+      }, 3000)
+    }),
+  ] as Promise<R>)
+  void guarded.catch(() => { /* 超时分支先 reject,防 unhandled */ })
+  conn.tail = guarded.then(
+    () => { clearTimeout(timer); conn.pending-- },
+    () => { clearTimeout(timer); conn.pending-- },
+  ).then(() => {
+    if (dead) conn.tail = Promise.resolve()
+  })
+  return guarded
 }
 
 export function modbusKey(cfg: Record<string, unknown>, transport: ModbusTransport = 'tcp'): string {
@@ -252,7 +285,7 @@ export async function getModbusConn(cfg: Record<string, unknown>, transport: Mod
   if (existing && existing.client.isOpen) return existing
   if (existing) {
     try {
-      await existing.client.close()
+      await closeModbusSafely(existing.client)
     }
     catch { /* 已断 */ }
     modbusPool.delete(key)
@@ -405,7 +438,7 @@ export const modbusTcpDriver: DaqDriver = {
         const key = modbusKey(driverConfig)
         const conn = modbusPool.get(key)
         if (conn) {
-          await conn.client.close()
+          await closeModbusSafely(conn.client)
           modbusPool.delete(key)
         }
       }
@@ -643,7 +676,7 @@ export const modbusRtuDriver: DaqDriver = {
       try {
         const conn = modbusPool.get(modbusKey(driverConfig, 'rtu-tcp'))
         if (conn) {
-          await conn.client.close()
+          await closeModbusSafely(conn.client)
           modbusPool.delete(modbusKey(driverConfig, 'rtu-tcp'))
         }
       }

package/server/services/workshop/dcw/dcw-controller.ts

@@ -556,8 +556,56 @@ class DcwController {
     return getDcwRecipeRepo().create(input)
   }
 
-  updateRecipe(id: string, patch: Partial<RecipeInput>) {
-    return getDcwRecipeRepo().update(id, patch)
+  updateRecipe(id: string, patch: Partial<RecipeInput>, meta?: { by: 'user' | 'agent' | 'system', actorName: string, actor: string, description: string }) {
+    const recipe = getDcwRecipeRepo().update(id, patch, meta)
+    // 配方参数版本变更 → 运维日志(版本号 + 归因;与版本历史同点入册)
+    if (patch.params !== undefined) {
+      try {
+        recordOps({
+          actor: meta?.actor ?? 'user',
+          actorName: meta?.actorName ?? meta?.actor ?? 'user',
+          actorKind: meta?.by ?? 'user',
+          action: meta?.by === 'agent' ? 'recipe.update.agent' : 'recipe.update',
+          kind: 'recipe',
+          targetKind: 'recipe',
+          targetId: id,
+          summary: `更新配方「${recipe.name}」→ v${recipe.version ?? 1}${meta?.description ? `:${meta.description.slice(0, 80)}` : ''}`,
+          lineId: recipe.lineId ?? '',
+          productId: recipe.productId ?? '',
+          recipeId: id,
+          detail: { version: recipe.version ?? 1, description: meta?.description ?? '' },
+        })
+      }
+      catch { /* 日志失败不影响更新 */ }
+    }
+    return recipe
+  }
+
+  /** 回退配方参数到历史版本/lastGood(生成新版本;非破坏) */
+  revertRecipe(id: string, target: { version?: number, toLastGood?: boolean }, meta: { by: 'user' | 'agent' | 'system', actorName: string, actor: string, description: string }) {
+    const recipe = getDcwRecipeRepo().revertToVersion(id, target, meta)
+    try {
+      recordOps({
+        actor: meta.actor,
+        actorName: meta.actorName,
+        actorKind: meta.by,
+        action: 'recipe.revert',
+        kind: 'recipe',
+        targetKind: 'recipe',
+        targetId: id,
+        summary: `回退配方「${recipe.name}」→ v${recipe.version ?? 1}${meta.description ? `:${meta.description.slice(0, 80)}` : ''}`,
+        lineId: recipe.lineId ?? '',
+        productId: recipe.productId ?? '',
+        recipeId: id,
+        detail: { version: recipe.version ?? 1, description: meta.description },
+      })
+    }
+    catch { /* 日志失败不影响回退 */ }
+    return recipe
+  }
+
+  recipeVersions(id: string) {
+    return getDcwRecipeRepo().versions(id)
   }
 
   removeRecipe(id: string): void {

package/server/services/workshop/dcw/dcw-recipe.repo.ts

@@ -29,6 +29,14 @@ function loadJson<T>(file: string, fallback: T): T {
   return loadJsonFile(file, fallback) as T
 }
 
+/** 配方变更归因(版本历史/运维日志共用):by=来源,actorName=人话操作者 */
+export interface RecipeUpdateMeta {
+  by: 'user' | 'agent' | 'system'
+  actorName: string
+  actor: string
+  description: string
+}
+
 function saveJson(file: string, data: unknown): void {
   saveJsonFileAtomic(file, data)
 }
@@ -175,7 +183,7 @@ class DcwRecipeRepo {
     return recipe
   }
 
-  update(id: string, patch: Partial<RecipeInput>): RecipeView {
+  update(id: string, patch: Partial<RecipeInput>, meta?: RecipeUpdateMeta): RecipeView {
     const r = this.byId(id)
     if (!r) throw new AppError(404, ErrorCodes.NOT_FOUND, `Recipe 不存在: ${id}`)
     if (patch.productId !== undefined && patch.productId !== r.productId) {
@@ -191,11 +199,20 @@ class DcwRecipeRepo {
     if (patch.description !== undefined) r.description = String(patch.description).trim()
     if (patch.params !== undefined) {
       const fresh = normParams(patch.params, r.lineId)
-      // 参数版本化(调控闭环):活动批次外的参数修改 → 版本自增 + 旧版入史(cap 20)
+      // 参数版本化(调控闭环):活动批次外的参数修改 → 版本自增 + 旧版入史(cap 20);
+      // 归因元数据(by/actorName/actor/description)随版本入史,前端/Agent 可查谁改的为什么改
       const changed = JSON.stringify(fresh) !== JSON.stringify(r.params)
       if (changed) {
         r.paramsHistory ??= []
-        r.paramsHistory.push({ version: r.version ?? 1, params: r.params, at: new Date().toISOString() })
+        r.paramsHistory.push({
+          version: r.version ?? 1,
+          params: r.params,
+          at: new Date().toISOString(),
+          by: meta?.by ?? 'user',
+          actorName: meta?.actorName ?? meta?.actor ?? 'user',
+          actor: meta?.actor ?? '',
+          description: meta?.description ?? '',
+        })
         if (r.paramsHistory.length > 20)
           r.paramsHistory.splice(0, r.paramsHistory.length - 20)
         r.version = (r.version ?? 1) + 1
@@ -208,6 +225,67 @@ class DcwRecipeRepo {
     return r
   }
 
+  /**
+   * 回退配方参数到指定历史版本(或已知良好批次快照),生成新版本(非破坏,历史完整保留)。
+   * target: { version: N } = 回到 vN 的参数;{ toLastGood: true } = 回到 lastGood 批次的参数冻结。
+   */
+  revertToVersion(id: string, target: { version?: number, toLastGood?: boolean }, meta: RecipeUpdateMeta): RecipeView {
+    const r = this.byId(id)
+    if (!r) throw new AppError(404, ErrorCodes.NOT_FOUND, `Recipe 不存在: ${id}`)
+    let snapshot: RecipeParam[] | undefined
+    let desc: string
+    if (target.toLastGood) {
+      const run = r.lastGoodRunId ? this.runById(r.lastGoodRunId) : undefined
+      if (!run?.paramsSnapshot?.length) {
+        throw new AppError(409, ErrorCodes.CONFLICT, `配方「${r.name}」无可回退的良好批次(先标记 lastGood 或指定 version)`)
+      }
+      snapshot = normParams(run.paramsSnapshot, r.lineId)
+      desc = `回退到已知良好批次 ${run.id.slice(0, 8)} 的参数冻结`
+    }
+    else {
+      const v = Number(target.version)
+      if (!Number.isFinite(v)) throw new AppError(400, ErrorCodes.VALIDATION_ERROR, 'version 必须为数字版本号')
+      const hit = (r.paramsHistory ?? []).find(h => h.version === v)
+      if (!hit) {
+        const avail = (r.paramsHistory ?? []).map(h => h.version).sort((a, b) => b - a)
+        throw new AppError(404, ErrorCodes.NOT_FOUND, `版本 v${v} 不存在(可用历史版本:${avail.length ? avail.map(n => `v${n}`).join(', ') : '无'};当前 v${r.version ?? 1})`)
+      }
+      snapshot = hit.params
+      desc = `回退到 v${v}(该版变更于 ${hit.at.slice(0, 19).replace('T', ' ')}${hit.actorName ? `,原操作者 ${hit.actorName}` : ''})`
+    }
+    if (JSON.stringify(snapshot) === JSON.stringify(r.params)) {
+      throw new AppError(409, ErrorCodes.CONFLICT, `目标版本参数与当前 v${r.version ?? 1} 完全一致,无需回退`)
+    }
+    const out = this.update(id, {
+      params: snapshot.map(p => ({ nodeId: p.nodeId, templateRef: p.templateRef, value: p.value, min: p.min, max: p.max })),
+    }, { ...meta, description: `${meta.description ? `${meta.description};` : ''}${desc}` })
+    return out
+  }
+
+  /** 参数版本历史(旧→新;含当前版尾部) */
+  versions(id: string): Array<{ version: number, at: string, by?: string, actorName?: string, description?: string, params: RecipeParam[], current?: boolean }> {
+    const r = this.byId(id)
+    if (!r) throw new AppError(404, ErrorCodes.NOT_FOUND, `Recipe 不存在: ${id}`)
+    const rows: Array<{ version: number, at: string, by?: string, actorName?: string, description?: string, params: RecipeParam[], current?: boolean }> = (r.paramsHistory ?? []).map(h => ({
+      version: h.version,
+      at: h.at,
+      by: h.by,
+      actorName: h.actorName,
+      description: h.description,
+      params: h.params,
+    }))
+    rows.push({
+      version: r.version ?? 1,
+      at: r.updatedAt,
+      by: undefined,
+      actorName: undefined,
+      description: '当前版本',
+      params: r.params,
+      current: true,
+    })
+    return rows
+  }
+
   /** 标记已知良好批次(基准恢复的目标;Trial keep / 手动均可调) */
   markGood(recipeId: string, runId: string): RecipeView {
     const r = this.byId(recipeId)