agentworkshop 0.7.54 → 0.7.58

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

@@ -16,7 +16,7 @@ import { getAgentNodeBindingRepo } from '../node-bindings.repo'
 import { getDaqController } from '../../daq/daq-controller'
 import { getDcwController } from '../../dcw/dcw-controller'
 import type { HostToolResult } from '../host-tool-bridge/types'
-import { toolDcwControl } from './dcw-tools'
+import { dcwControlGovernedInternal } from './dcw-tools'
 
 const sleep = (ms: number) => new Promise(r => setTimeout(r, ms))
 
@@ -48,21 +48,31 @@ export async function toolOptimizationExplore(agentId: string, args: {
     const goalText = Object.keys(goal).length > 0 ? JSON.stringify(goal) : '(Channel 未设置 goal —— 建议先在 Channel 设置中定义优化目标)'
 
     const repo = getAgentNodeBindingRepo()
-    const dcwBindings = repo.byAgent(agentId).filter(b => b.kind === 'dcw')
-    const controlNodeId = String(args.control_node_id ?? '').trim() || dcwBindings[0]?.nodeId || ''
-    if (!controlNodeId) return { text: '未指定控制节点且当前无数控绑定;请传 control_node_id 或先绑定数控节点。', isError: true }
+    const allBindings = repo.byAgent(agentId)
+    const dcwBindings = allBindings.filter(b => b.kind === 'dcw')
+    const recipeBindings = allBindings.filter(b => b.kind === 'recipe')
+    // 配方绑定覆盖的控制节点集合(权限模型 v2:recipe 授权 = 配方参数节点授权)
+    const recipeControlled = new Set<string>()
+    for (const rb of recipeBindings) {
+      const r = getDcwController().listRecipes().find(x => x.id === rb.nodeId)
+      for (const p of (r?.params ?? [])) recipeControlled.add(p.nodeId)
+    }
+    const controlNodeId = String(args.control_node_id ?? '').trim() || dcwBindings[0]?.nodeId || [...recipeControlled][0] || ''
+    if (!controlNodeId) return { text: '未指定控制节点且当前无数控授权(数控绑定或配方绑定);请传 control_node_id 或先绑定。', isError: true }
     const binding = repo.find(agentId, controlNodeId, 'dcw')
     const node = getDcwController().byId(controlNodeId)
-    if (!binding || !node) return { text: `控制节点 ${controlNodeId} 无效(未绑定或不存在)。`, isError: true }
+    if ((!binding && !recipeControlled.has(controlNodeId)) || !node) {
+      return { text: `控制节点 ${controlNodeId} 无效(无数控授权或节点不存在;权限模型 v2 下持有含该参数的配方绑定即可)。`, isError: true }
+    }
 
     // 步长来源优先级:显式 args > 绑定 tuning.step > 场景 control.maxStep > 量程 1/20
     const sceneControl = (profile.sceneContract as { controls?: Array<{ nodeId?: string, maxStep?: number }> } | undefined)?.controls?.find(c => c.nodeId === controlNodeId)
-    const tuningStep = binding.tuning?.step
+    const tuningStep = binding?.tuning?.step
     const fallbackStep = Math.abs((node.max - node.min) / 20)
     const step = Number(args.step ?? tuningStep ?? sceneControl?.maxStep ?? fallbackStep)
     if (!Number.isFinite(step) || step <= 0) return { text: `激励步长无效:${step}(可传 step 或在绑定上设置 tuning.step)。`, isError: true }
-    const tuneMin = binding.tuning?.min ?? node.min
-    const tuneMax = binding.tuning?.max ?? node.max
+    const tuneMin = binding?.tuning?.min ?? node.min
+    const tuneMax = binding?.tuning?.max ?? node.max
     const direction = args.direction === 'down' ? -1 : 1
     const proposed = Number(node.value ?? 0) + direction * step
     const target = Math.min(tuneMax, Math.max(tuneMin, proposed))
@@ -76,7 +86,7 @@ export async function toolOptimizationExplore(agentId: string, args: {
 
     // 真实写入:复用 dcw_control 全治理链(手动绑定会挂 HITL,auto+bounded 走限界直写)
     const settleSec = Math.min(300, Math.max(10, Number(args.settle_seconds ?? 45)))
-    const write = await toolDcwControl(agentId, {
+    const write = await dcwControlGovernedInternal(agentId, {
       node_id: controlNodeId,
       value: target,
       hypothesis: args.hypothesis ?? `探索激励(${direction > 0 ? 'up' : 'down'} ${Number(step).toFixed(3)};goal=${goalText.slice(0, 120)})`,

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

@@ -1,169 +1,192 @@
-/**
- * 工艺参数读写(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 { limitsBreakdownOf } from '../../dcw/param-limits'
-import { guardTwinWrite } from '../../aml/twin/write-guard'
-import { requestManualApproval } from './manual-approval'
-
-/** 读/设定偏差对照容差(与服务端回读死区同口径) */
-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 || '无'});单步上限=${bd.stepLimit == null ? '未配置' : `${bd.stepLimit}${param.unit}`}(${bd.stepLimitSource});Agent写入间隔≥60s`
-}
-
-/** 工具: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
-}, channelId?: string): Promise<{ text: string, isError?: boolean }> {
-  const twinGuard = guardTwinWrite(agentId, channelId)
-  if (!twinGuard.allowed) return { text: `${twinGuard.code}: ${twinGuard.message}`, isError: true }
-  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 同源审批面(manual-approval),备注回给 Agent
-  if (binding.mode === 'manual') {
-    const ap = await requestManualApproval({
-      agentId,
-      nodeId: param.nodeId,
-      detail: `工艺参数「${param.key}」(${param.name})设定 ${value}${param.unit},${paramLimitsText(param)}`,
-    })
-    if (!ap.ok) return { text: ap.text, isError: ap.isError }
-  }
-  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 }
-  }
-}
+/**
+ * 工艺参数读写(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 { limitsBreakdownOf } from '../../dcw/param-limits'
+import { guardTwinWrite } from '../../aml/twin/write-guard'
+import { requestManualApproval } from './manual-approval'
+
+/** 读/设定偏差对照容差(与服务端回读死区同口径) */
+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 || '无'});单步上限=${bd.stepLimit == null ? '未配置' : `${bd.stepLimit}${param.unit}`}(${bd.stepLimitSource});Agent写入间隔≥60s`
+}
+
+/** 工具: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
+}, channelId?: string): Promise<{ text: string, isError?: boolean }> {
+  void agentId
+  void args
+  void channelId
+  return {
+    text: '参数直写已禁用(权限模型 v2):Agent 不再直接改写运行中的工艺参数。请改用绑定的配方 —— recipe_update(写入新版本)/ recipe_apply(整批下发)/ recipe_trial(候选试验);治理联锁与 HITL 在配方面照常生效。',
+    isError: true,
+  }
+}
+
+/** v2 前的语义参数直写实现(已停用;保留供回溯,不再被任何入口调用) */
+async function _toolParamControlDisabled(agentId: string, args: {
+  param?: string
+  value?: number | string
+  hypothesis?: string
+  task_id?: string
+  line_id?: string
+}, channelId?: string): Promise<{ text: string, isError?: boolean }> {
+  void channelId
+  const twinGuard = guardTwinWrite(agentId, channelId)
+  if (!twinGuard.allowed) return { text: `${twinGuard.code}: ${twinGuard.message}`, isError: true }
+  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 同源审批面(manual-approval),备注回给 Agent。
+  // 调整依据(hypothesis)进审批详情 —— 人机交互透明化:人类在审批面板直接看到
+  // Agent 基于什么分析/判断要这样调;批准附言与拒绝意见均随回执回流。
+  let manualFeedback = ''
+  if (binding.mode === 'manual') {
+    const rationale = args.hypothesis ? String(args.hypothesis).trim() : ''
+    const ap = await requestManualApproval({
+      agentId,
+      nodeId: param.nodeId,
+      detail: `工艺参数「${param.key}」(${param.name})设定 ${value}${param.unit},${paramLimitsText(param)}${rationale ? `;调整依据:${rationale}` : ''}`,
+    })
+    if (!ap.ok) return { text: ap.text, isError: ap.isError }
+    manualFeedback = ap.comment ?? ''
+  }
+  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}` : ''}${manualFeedback ? `\n[人工反馈] ${manualFeedback}` : ''}`,
+      }
+    }
+    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 }
+  }
+}

package/server/services/workshop/agents/industrial/recipe-gate.ts

@@ -0,0 +1,96 @@
+/**
+ * Recipe 操作统一鉴权门(权限模型 v2)。
+ *
+ * Agent 不再直碰数控节点 —— 对产线的全部写动作收敛到「绑定的 recipe」上:
+ *   ① 绑定门:必须持有该 recipe 的绑定(kind='recipe';可绑定多个配方);
+ *   ② 认证门:recipe.access.requireAuth=true 时,只有 authorizedAgentIds 清单内的
+ *      Agent 可操作(fail-closed:开认证但清单为空 = 无人可操作);
+ *   ③ 运行门:配方必须**正在执行**(该产线存在本配方的活动批次)—— 未运行的配方
+ *      一律不可操作(参数写入/下发/试验/回退同样受限);
+ *   ④ HITL 判定:绑定 mode='manual' → 每次动作挂起等人工批准(必带 Agent 理由);
+ *      mode='auto'(显式确认切换)→ 免批直执行。全局开关 security.recipeDispatchApproval
+ *      保持兼容:开启时即便 auto 绑定也挂审批。
+ *      线级总闸(2026-10-08):line.controlMode='manual'(缺省,fail-safe)时 auto 绑定
+ *      也强制人工审批 —— 手动模式下人类必须过目每一次写动作。
+ */
+import { getAgentNodeBindingRepo, type AgentNodeBinding } from '../node-bindings.repo'
+import { getDcwController } from '../../dcw/dcw-controller'
+import { getDcwLineRepo } from '../../dcw/dcw-line.repo'
+import { getActiveLineRun } from '../../dcw/line-run'
+
+export type RecipeOp = 'update' | 'dispatch' | 'trial' | 'rollback'
+
+export type RecipeGateResult
+  = | { ok: true, binding: AgentNodeBinding, hitlRequired: boolean, activeRunId: string }
+    | { ok: false, text: string }
+
+/** 运行门:该配方当前是否有活动批次(未结束的 run) */
+export function activeRunOfRecipe(recipeId: string): { id: string } | null {
+  const run = getDcwController().listRuns().find(r => r.recipeId === recipeId && !r.endedAt)
+  if (!run) return null
+  // 反僵尸交叉校验(鲁棒性):DB 行未结束 ≠ 产线在运行 —— 多次 apply/崩溃/重启会泄漏
+  // endedAt=null 的历史行,若只查 DB,运行门会被僵尸批次永久放行(停止后仍可下发)。
+  // 权威运行态是 line-run 注册表(内存+line-runs.json 落盘,崩溃可恢复):
+  // run 所属产线必须在注册表中运行,且注册表的活跃批次就是本批次。
+  const active = getActiveLineRun(run.lineId)
+  if (!active || active.runId !== run.id) return null
+  return { id: run.id }
+}
+
+/** 统一鉴权门:绑定 → 二级认证 → 运行门;返回绑定与 HITL 判定(不做挂起,挂起由调用方执行) */
+export function assertRecipeOperation(
+  agentId: string,
+  recipe: { id: string, name: string, lineId?: string, access?: { requireAuth?: boolean, authorizedAgentIds?: string[] } },
+  op: RecipeOp,
+): RecipeGateResult {
+  const opLabel = op === 'update' ? '参数写入' : op === 'dispatch' ? '下发' : op === 'trial' ? '试验下发' : '回退'
+  // ① 绑定门(kind='recipe';nodeId 字段 = recipeId)
+  const binding = getAgentNodeBindingRepo().find(agentId, recipe.id, 'recipe')
+  if (!binding) {
+    return {
+      ok: false,
+      text: `无权${opLabel}配方「${recipe.name}」(${recipe.id}):你未绑定该配方。权限模型 v2 下 Agent 不直接操作数控节点 —— 通过绑定 recipe 获得参数写入与下发能力(可绑定多个配方);请让用户或 lead 为你绑定(recipe 绑定首绑默认 manual,每次动作需人工批准)。`,
+    }
+  }
+  // ② 二级认证(用户在配方编辑里开启并勾选授权 Agent)
+  if (recipe.access?.requireAuth && !(recipe.access.authorizedAgentIds ?? []).includes(agentId)) {
+    return {
+      ok: false,
+      text: `配方「${recipe.name}」已开启二级认证,你不在其授权 Agent 清单内,${opLabel}被拒。请让用户在配方编辑中把你的 Agent 加入授权清单(或关闭认证)。`,
+    }
+  }
+  // ③ 运行门:未运行的配方不可操作(参数写入也一样 —— 运行外改动没有可下发载体,且防误改基线)
+  const run = activeRunOfRecipe(recipe.id)
+  if (!run) {
+    return {
+      ok: false,
+      text: `配方「${recipe.name}」当前未在执行(产线上没有本配方的活动批次),按运行门约束${opLabel}被拒。请先由用户在产线开跑本配方,再进行参数写入/下发。`,
+    }
+  }
+  // ④ HITL 判定:manual 绑定 → 逐动作人工批准;auto → 免批。
+  //    线级总闸(2026-10-08 生产化):line.controlMode='manual'(缺省)时,即便绑定为
+  //    auto 也强制人工审批 —— 手动模式下人类必须过目每一次写动作(fail-safe)。
+  const lineManual = recipe.lineId ? getDcwLineRepo().controlModeOf(recipe.lineId) === 'manual' : false
+  // ⑤ 全局开关兼容位:security.recipeDispatchApproval 开启时即便 auto 也挂审批(保留语义)
+  const globalGate = false // 由调用方按 settingOf('security.recipeDispatchApproval') 叠加(本模块不依赖设置服务)
+  void globalGate
+  return { ok: true, binding, hitlRequired: binding.mode === 'manual' || lineManual, activeRunId: run.id }
+}
+
+/** 审批单载荷(结构化;前端审批卡渲染理由/参数/批次) */
+export function recipeApprovalPayload(op: RecipeOp, recipeId: string, recipeName: string, extra: {
+  reason: string
+  params?: Array<{ nodeId: string, name: string, from: number | null, to: number, unit?: string }>
+  runId?: string
+}): Record<string, unknown> {
+  return {
+    schemaVersion: 1,
+    kind: 'recipe-gate',
+    op,
+    recipeId,
+    recipeName,
+    reason: extra.reason,
+    ...(extra.params ? { params: extra.params } : {}),
+    ...(extra.runId ? { runId: extra.runId } : {}),
+  }
+}