agentworkshop 0.7.44 → 0.7.47

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

@@ -0,0 +1,382 @@
+/**
+ * 运维日志与配方变更史(ops_log / recipe_* / line_context)
+ * (由 server/services/workshop/agents/industrial-tools.ts 按职责拆出;内容逐行原文搬运)
+ */
+import { agentBadgeLabel } from '../agent-badge'
+import { getActiveLineRun } from '../../dcw/line-run'
+import { getAgentNodeBindingRepo } from '../node-bindings.repo'
+import { getDaqNodeRepo } from '../../daq/daq-node.repo'
+import { getDcwController } from '../../dcw/dcw-controller'
+import { getDcwLineRepo } from '../../dcw/dcw-line.repo'
+import { getDcwProductRepo } from '../../dcw/dcw-product.repo'
+import { getDcwRecipeRepo } from '../../dcw/dcw-recipe.repo'
+import { getOps } from '../../ops/ops'
+
+// ================================================================
+// 运维日志 / Recipe 变更史查询(Agent 自查面:负责产线 scoped)
+// ================================================================
+
+/** Agent 负责范围 = 绑定节点的全集(节点 id 集 + 这些节点所属产线集);无绑定 = 无范围 */
+export 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 }
+}
+
+/** 配方参数的节点失效态(数据一致性展示/Agent 提示共用):null=正常 */
+export function nodeRefStatus(nodeId: string, lineId: string): { code: 'deleted' | 'disabled' | 'unbound', label: string } | null {
+  const node = getDcwController().byId(nodeId)
+  if (!node) return { code: 'deleted', label: '已删除' }
+  if (!node.enabled) return { code: 'disabled', label: '已停用' }
+  if (node.lineId !== lineId) return { code: 'unbound', label: '已取消绑定' }
+  return null
+}
+
+export const OPS_ACTOR_LABEL: Record<string, string> = { agent: 'Agent', user: '用户', system: '系统' }
+
+export 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 stale = nodeRefStatus(p.nodeId, recipe.lineId)
+        const staleTag = stale ? ` [${stale.label},参数不下发]` : ''
+        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 ? ' [我负责]' : ''}${staleTag}`)
+      }
+      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 : '?'
+            const stale = nodeRefStatus(p.nodeId, r.lineId)
+            const tag = stale ? `[${stale.label},参数不下发]` : ''
+            return `${node?.name ?? p.nodeId}=${p.value}${node?.unit ?? ''}(PLC 当前 ${cur})${tag}`
+          }).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 nodeName = (id: string): string => {
+        const n = getDcwController().byId(id)
+        return n ? n.name : `${id}(已删除)`
+      }
+      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 }) => `${nodeName(p.nodeId)} ${old?.value ?? '新增'}→${p.value}`)
+      const removed = prev.params.filter(o => !v.params.some(x => x.nodeId === o.nodeId)).map(o => `${nodeName(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 (!node.enabled) return { text: `节点「${node.name}」已停用,参数保存被拒。请先让用户恢复节点控制,或保存到其他节点。`, isError: true }
+    if (!repo.find(agentId, nodeId, 'dcw')) {
+      return { text: `无权修改节点「${node.name}」的配方参数(仅可改自己绑定 dcw 的节点)。`, isError: true }
+    }
+  }
+  // 部分合并:只更新提供的节点,其余参数保持不变;
+  // 基线中的失效参数(节点已删除/已解绑/已改挂)自动剪除并如实告知 —— 否则整次保存会被归一化拒绝
+  const dropped: string[] = []
+  const merged = recipe.params
+    .filter((p) => {
+      const node = getDcwController().byId(p.nodeId)
+      if (!node || node.lineId !== recipe.lineId) {
+        dropped.push(node?.name ?? p.nodeId)
+        return false
+      }
+      return true
+    })
+    .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(';')
+    const droppedNote = dropped.length > 0 ? `\n注意:已自动剔除失效参数(${dropped.join('、')}:节点已删除或改挂其他产线),这些参数不再属于本配方。` : ''
+    return {
+      text: `已保存为 v${updated.version ?? 1}:「${updated.name}」参数 ${changedNodes};原因:${reason}。${droppedNote}\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/agents/industrial/param-tools.ts

@@ -0,0 +1,172 @@
+/**
+ * 工艺参数读写(param_control / param_read)与量程/容差辅助
+ * (由 server/services/workshop/agents/industrial-tools.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type { DcwParamView } from '../../../../../shared/dcw-protocol'
+import { agentBadgeLabel } from '../agent-badge'
+import { getAgentNodeBindingRepo } from '../node-bindings.repo'
+import { getDcwController } from '../../dcw/dcw-controller'
+import { getDcwParamRepo } from '../../dcw/param-map.repo'
+import { getRecipeRollBackManager } from '../../dcw/recipe-rollback-manager'
+import { getToolApprovals } from '../tool-approvals'
+import { limitsBreakdownOf } from '../../dcw/param-limits'
+
+/** 读/设定偏差对照容差(与服务端回读死区同口径) */
+export function writeToleranceOf(node: { decimals: number, min: number, max: number }): number {
+  return Math.max(0.5 * 10 ** -node.decimals, (node.max - node.min) * 0.005)
+}
+
+/** 工艺参数解析(param_control/param_read 共用):pp-id 优先,其次按 key;跨产线同名需 line_id 消歧 */
+export 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 寻址细节) */
+export 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 }
+  }
+}