agentworkshop 0.7.53 → 0.7.58

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

@@ -10,8 +10,12 @@ 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 { assertRecipeOpInterval } from '../../dcw/recipe-op-anchor'
+import { getDcwParamRepo } from '../../dcw/param-map.repo'
 import { getOps } from '../../ops/ops'
+import { settingOf } from '../../settings'
 import { fanoutQuery, windowOf } from './audit-query'
+import { assertRecipeOperation, recipeApprovalPayload } from './recipe-gate'
 
 // ================================================================
 // 运维日志 / Recipe 变更史查询(Agent 自查面:负责产线 scoped)
@@ -30,16 +34,30 @@ function channelBoundLineId(agentId: string): string | null {
   }
 }
 
-/** Agent 负责范围 = 绑定节点的全集(节点 id 集 + 这些节点所属产线集;写权限依据)
- *  ∪ 频道绑定产线(boundLineIds;v18 只读扩权:日志/配方史/上下文可读,写仍走节点授权)。 */
+/** Agent 负责范围 = 绑定节点的全集(节点 id 集 + 这些节点所属产线集)
+ *  ∪ 绑定配方所在产线(kind='recipe';v2 权限模型:配方绑定授予该线的读面+配方操作面)
+ *  ∪ 频道绑定产线(boundLineIds;v18 只读扩权:日志/配方史/上下文可读)。 */
 export function agentOpsScope(agentId: string): { lineIds: string[], nodeIds: Set<string>, boundLineIds: string[] } | null {
   const bindings = getAgentNodeBindingRepo().byAgent(agentId)
   const boundLine = channelBoundLineId(agentId)
-  const boundLineIds = boundLine ? [boundLine] : []
-  if (bindings.length === 0 && boundLineIds.length === 0) return null
+  const boundLineIds = new Set<string>(boundLine ? [boundLine] : [])
+  if (bindings.length === 0 && boundLineIds.size === 0) return null
   const lineIds = new Set<string>()
   const nodeIds = new Set<string>()
   for (const b of bindings) {
+    if (b.kind === 'recipe') {
+      // 配方绑定:配方所在产线进读面(boundLineIds);配方参数节点进可见节点集(mes_fetch/line_context)
+      try {
+        const recipe = getDcwController().listRecipes().find(r => r.id === b.nodeId)
+        if (recipe?.lineId) {
+          boundLineIds.add(recipe.lineId)
+          lineIds.add(recipe.lineId)
+          for (const p of recipe.params) nodeIds.add(p.nodeId)
+        }
+      }
+      catch { /* 配方刚被删等情况忽略 */ }
+      continue
+    }
     nodeIds.add(b.nodeId)
     try {
       const n = b.kind === 'dcw' ? getDcwController().byId(b.nodeId) : getDaqNodeRepo().byId(b.nodeId)
@@ -47,7 +65,7 @@ export function agentOpsScope(agentId: string): { lineIds: string[], nodeIds: Se
     }
     catch { /* 节点刚被删等情况忽略 */ }
   }
-  return { lineIds: [...lineIds], nodeIds, boundLineIds }
+  return { lineIds: [...lineIds], nodeIds, boundLineIds: [...boundLineIds] }
 }
 
 /** 读工具的可见产线全集 = 节点授权线 ∪ 频道绑定线(去重) */
@@ -188,6 +206,8 @@ export async function toolLineContext(agentId: string, args: { line_id?: string
     const recipe = run?.recipeId ? getDcwController().listRecipes().find(r => r.id === run.recipeId) : undefined
     const parts: string[] = []
     parts.push(`■ 产线 ${line?.name ?? lid}(${lid})${lineTag(lid, scope)} · 状态:${run ? '运行中' : '待机/停线'}`)
+    // 场景描述(产线/产品的本体说明;不透出则 Agent 不知道这条线是干什么的)
+    if (line?.description?.trim()) parts.push(`  场景说明: ${line.description.trim().slice(0, 220)}`)
     if (run) {
       parts.push(`  活动批次 ${run.runId.slice(0, 8)} · 产品「${run.productName}」(${run.productId}) · 开跑 ${run.startedAt.slice(11, 19)} · 已打标 ${run.taggedSamples} 样本`)
     }
@@ -199,9 +219,18 @@ export async function toolLineContext(agentId: string, args: { line_id?: string
       .filter(b => b.kind === 'daq')
       .map(b => getDaqNodeRepo().byId(b.nodeId))
       .filter(n => n?.lineId === lid)
+    const myRecipeIds = getAgentNodeBindingRepo().byAgent(agentId)
+      .filter(b => b.kind === 'recipe')
+      .map(b => b.nodeId)
+    const myRecipes = myRecipeIds
+      .map(id => getDcwController().listRecipes().find(r => r.id === id))
+      .filter((r): r is NonNullable<typeof r> => !!r && r.lineId === lid)
     parts.push(`  我绑定的节点:数控 [${myDcw.map(n => n!.name).join(', ') || '无'}];数采 [${myDaq.map(n => n!.name).join(', ') || '无'}]`)
+    if (myRecipes.length > 0) parts.push(`  我绑定的配方: [${myRecipes.map(r => `${r.name}(v${r.version ?? 1}${getDcwController().listRuns().some(x => x.recipeId === r.id && !x.endedAt) ? ',执行中' : ',未运行'})`).join('; ')}]`)
     if (recipe) {
       parts.push(`  配方「${recipe.name}」(${recipe.id}) v${recipe.version ?? 1}${recipe.description ? ` — ${recipe.description}` : ''}`)
+      const product = recipe.productId ? getDcwProductRepo().byId(recipe.productId) : undefined
+      if (product?.description?.trim()) parts.push(`  产品说明(${product.name}): ${product.description.trim().slice(0, 160)}`)
       for (const p of recipe.params) {
         const node = getDcwController().byId(p.nodeId)
         const mine = myDcw.some(n => n!.id === p.nodeId)
@@ -209,7 +238,8 @@ export async function toolLineContext(agentId: string, args: { line_id?: string
         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 pv = getDcwParamRepo().listViews().find(v => v.nodeId === p.nodeId)
+        parts.push(`    · ${node?.name ?? p.nodeId} = ${p.value}${node?.unit ?? ''}${win} | PLC 当前 ${cur}${node?.unit ?? ''}${mine ? ' [我负责]' : ''}${staleTag}${pv ? ` | 参数键 ${pv.key}` : ''}${pv?.desc ? ` | ${pv.desc.slice(0, 90)}` : ''}`)
       }
       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}`)
@@ -284,7 +314,9 @@ export async function toolRecipeVersions(agentId: string, args: { recipe_id?: st
 }
 
 /** 工具:recipe_update —— 把验证过的最佳参数保存进配方(生成新版本,带归因与原因)。
- *  只改配方定义(下一批次生效);不改运行中 PLC 当前值(那用 dcw_control 逐节点下发)。 */
+ *  权限模型 v2:需绑定该 recipe(kind='recipe')且通过二级认证与运行门(配方须在执行);
+ *  绑定 manual 时本次保存挂 HITL 等人工批准(理由随审批卡展示)。
+ *  只改配方定义;要把参数推到运行中的产线用 recipe_apply(整批下发)。 */
 export async function toolRecipeUpdate(agentId: string, args: {
   recipe_id?: string
   params?: Array<{ node_id?: string, value?: number | string, min?: number | string, max?: number | string }>
@@ -294,22 +326,52 @@ export async function toolRecipeUpdate(agentId: string, args: {
   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 }
+  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()
+  // 权限模型 v2:绑定 → 二级认证 → 运行门(未在执行的配方不可操作)
+  const gate = assertRecipeOperation(agentId, recipe, 'update')
+  if (!gate.ok) return { text: gate.text, isError: true }
   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 }
+  }
+  // HITL:manual 绑定(或全局下发审批开关)→ 保存前挂人工审批,理由随审批卡展示
+  let hitlNote = ''
+  if (gate.hitlRequired) {
+    const gateDecision = await hitlDispatchGate(
+      agentId,
+      recipe.id,
+      `配方参数写入:「${recipe.name}」v${recipe.version ?? 1} 拟保存 ${list.map((p) => {
+        const node = getDcwController().byId(String(p.node_id).trim())
+        const old = recipe.params.find(x => x.nodeId === String(p.node_id).trim())?.value
+        return `${node?.name ?? p.node_id} ${old ?? '?'}→${Number(p.value)}${node?.unit ?? ''}`
+      }).join(';')} | 理由:${reason} | 批准=写入新版本(不下发产线);拒绝可附指导`,
+      '配方参数写入审批',
+      { payload: recipeApprovalPayload('update', recipe.id, recipe.name, {
+        reason,
+        params: list.map((p) => {
+          const node = getDcwController().byId(String(p.node_id).trim())
+          const old = recipe.params.find(x => x.nodeId === String(p.node_id).trim())?.value
+          return { nodeId: String(p.node_id).trim(), name: node?.name ?? String(p.node_id), from: old ?? null, to: Number(p.value), unit: node?.unit }
+        }),
+        runId: gate.activeRunId,
+      }) },
+    )
+    if (!gateDecision.approved) {
+      return {
+        text: `人工未批准本次参数写入。人工指导:${gateDecision.comment || '(无附言)'}。请按人工指导修订参数与理由后重新提交 recipe_update。`,
+      }
     }
+    if (gateDecision.comment) hitlNote = `\n人工附言:${gateDecision.comment}`
   }
+  // 旧值快照(repo.update 原地改写 recipe.params,事后再取会把 before 读成新值)
+  const beforeOf = new Map(recipe.params.map(p => [p.nodeId, p.value]))
   // 部分合并:只更新提供的节点,其余参数保持不变;
   // 基线中的失效参数(节点已删除/已解绑/已改挂)自动剪除并如实告知 —— 否则整次保存会被归一化拒绝
   const dropped: string[] = []
@@ -324,12 +386,18 @@ export async function toolRecipeUpdate(agentId: string, args: {
     })
     .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) }
+      // stepLimit 必须随行携带:丢了会被 normParams 视为"参数有变化"(同值也空转增版),
+      // 且配方层单步限幅被静默抹掉(退化为参数/节点层默认)——治理数据完整性
+      const out: { nodeId: string, templateRef?: string, value: number, min?: number, max?: number, stepLimit?: number } = {
+        nodeId: p.nodeId,
+        templateRef: p.templateRef,
+        value: patch ? Number(patch.value) : p.value,
+      }
       if (p.min != null) out.min = p.min
-      if (patch.min != null && Number.isFinite(Number(patch.min))) out.min = Number(patch.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)
+      if (patch?.max != null && Number.isFinite(Number(patch.max))) out.max = Number(patch.max)
+      if (p.stepLimit != null) out.stepLimit = p.stepLimit
       return out
     })
   const extra = list.filter(p => !recipe.params.some(x => x.nodeId === String(p.node_id).trim()))
@@ -343,12 +411,12 @@ export async function toolRecipeUpdate(agentId: string, args: {
     })
     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
+      const before = beforeOf.get(String(p.node_id).trim())
       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。`,
+      text: `已保存为 v${updated.version ?? 1}:「${updated.name}」参数 ${changedNodes};原因:${reason}。${droppedNote}${hitlNote}\n注意:配方定义已更新,运行中批次仍按开跑时冻结的参数生产;要把新参数推到运行中的产线(经治理联锁整批下发),用 recipe_apply。回退用 recipe_rollback。`,
     }
   }
   catch (err) {
@@ -365,37 +433,87 @@ export async function toolRecipeRollback(agentId: string, args: {
   to_last_good?: boolean | string
   dispatch?: boolean | string
   reason?: string
-}): Promise<{ text: string, isError?: boolean }> {
+  emergency?: boolean | string
+}): Promise<{ text: string, isError: true } | { 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 dispatch = args.dispatch === true || args.dispatch === 'true'
+  const emergency = args.emergency === true || args.emergency === '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 }
-  }
+  // 权限模型 v2:绑定 → 二级认证 → 运行门(未在执行的配方不可回退)
+  const gate = assertRecipeOperation(agentId, recipe, 'rollback')
+  if (!gate.ok) return { text: gate.text, isError: true }
   if (!toLastGood && Number.isFinite(version) && version >= (recipe.version ?? 1)) {
     return { text: `不能回退到 v${version}(当前已是 v${recipe.version ?? 1};回退目标是更早的版本)。`, isError: true }
   }
+  // Recipe 级下发间隔卡控:仅统一回退(dispatch=true,含 PLC 整批重下发)受控;仅定义回退不触产线不卡
+  if (dispatch) {
+    const cadence = recipeOpIntervalGate(recipe, emergency)
+    if (cadence) return cadence
+  }
+  // HITL:manual 绑定(或全局开关)→ 回退前挂人工审批(定义回退与统一回退都改状态,同受门控)
+  let hitlNote = ''
+  let gateApprovalId = ''
+  if (gate.hitlRequired) {
+    const gateDecision = await hitlDispatchGate(
+      agentId,
+      recipe.id,
+      `${emergency ? '【应急豁免频控】' : ''}配方回退:「${recipe.name}」→ ${toLastGood ? '已知良好批次冻结' : `v${version}`}${dispatch ? '(统一回退:定义回退+整批重下发)' : '(仅定义回退)'} | 理由:${reason} | 批准=执行回退;拒绝可附指导`,
+      `${emergency ? '【应急】' : ''}配方回退审批`,
+      { payload: { ...recipeApprovalPayload('rollback', recipe.id, recipe.name, { reason, runId: gate.activeRunId }), ...(emergency ? { emergency: true } : {}) } },
+    )
+    gateApprovalId = gateDecision.id
+    if (!gateDecision.approved) {
+      return {
+        text: `人工未批准本次回退。人工指导:${gateDecision.comment || '(无附言)'}。请按人工指导补充证据或调整回退目标后重新提交。`,
+      }
+    }
+    if (gateDecision.comment) hitlNote = `\n人工附言:${gateDecision.comment}`
+  }
   try {
     if (dispatch) {
-      const { recipe: updated, run } = await getDcwController().rollbackRecipeAndDispatch(recipeId, {
+      const { recipe: updated, run, definitionNoop } = await getDcwController().rollbackRecipeAndDispatch(recipeId, {
         version: toLastGood ? undefined : version,
         toLastGood,
         by: 'agent',
         actorName: agentBadgeLabel(agentId),
         actor: agentId,
         description: reason,
+        agentDispatch: true,
+        agentApprovalId: gateApprovalId,
+        emergency,
       })
       const okN = run.results.filter(r => r.ok).length
+      const acks = run.ackSummary ?? { verified: okN, unverified: 0, failed: run.results.length - okN, total: run.results.length }
+      const defNote = definitionNoop
+        ? `定义已在目标版本 v${updated.version ?? 1}(未生成新版本)`
+        : `已生成 v${updated.version ?? 1}`
+      // 整批重下发全部失败(典型:节点写入保持窗/节流未放行)→ 响亮失败:定义已回退但产线仍运行
+      // 旧参数,Agent 必须知道并稍后重发(再调本工具会再生成一个回退版本,或用 dcw_control 直发)。
+      if (run.results.length > 0 && okN === 0) {
+        return {
+          text: `回退部分失败:配方「${updated.name}」${defNote},但整批重下发 0/${run.results.length} 参数成功(节点写入保持窗/节流未放行)。产线仍在运行旧参数 —— 等待约 60s 后重新调用 recipe_rollback(dispatch=true,回退目标 v${updated.version ?? 1}),或用 dcw_control 逐节点直发;原因:${reason}。`,
+          isError: true,
+        }
+      }
+      // ACK 鉴定铁律:回退是安全动作,未证实/失败必须响亮(否则人以为已恢复实际没有)
+      if (acks.failed > 0 || acks.unverified > 0) {
+        return {
+          text: [
+            `统一回退执行,但 ACK 鉴定未全绿:配方「${updated.name}」${defNote},设备证实 ${acks.verified}/${acks.total},未证实 ${acks.unverified},失败 ${acks.failed}(回退目标:${toLastGood ? '已知良好批次冻结' : `v${version}`});原因:${reason}。${hitlNote}`,
+            '「未证实」参数可能未真正恢复到目标值 —— 请立即用 daq_query/dcw_read 核实产线侧现值,必要时 dcw_control 逐节点直发目标值,并把清单写入汇报提醒人类。',
+          ].join('\n'),
+          isError: true,
+        }
+      }
       return {
-        text: `统一回退完成:配方「${updated.name}」已生成 v${updated.version ?? 1},参数恢复为目标版本(${toLastGood ? '已知良好批次冻结' : `v${version}`}),并已整批重下发到 PLC(${okN}/${run.results.length} 参数成功);原因:${reason}。\n用 daq_query 复测确认恢复效果;版本史用 recipe_versions 复核。`,
+        text: `统一回退完成:配方「${updated.name}」${defNote},参数恢复为目标版本(${toLastGood ? '已知良好批次冻结' : `v${version}`}),并已整批重下发到 PLC 且全部设备证实(${acks.verified}/${acks.total});原因:${reason}。${hitlNote}\n用 daq_query 复测确认恢复效果;版本史用 recipe_versions 复核。`,
       }
     }
     const updated = getDcwController().revertRecipe(recipeId, {
@@ -408,7 +526,7 @@ export async function toolRecipeRollback(agentId: string, args: {
       description: reason,
     })
     return {
-      text: `回退完成:配方「${updated.name}」已生成 v${updated.version ?? 1},参数恢复为目标版本(${toLastGood ? '已知良好批次冻结' : `v${version}`});原因:${reason}。\n注意:仅回退了配方定义,运行中 PLC 未变动;要把恢复参数写入产线(统一回退),用 recipe_rollback 并带 dispatch=true。版本史用 recipe_versions 复核。`,
+      text: `回退完成:配方「${updated.name}」已生成 v${updated.version ?? 1},参数恢复为目标版本(${toLastGood ? '已知良好批次冻结' : `v${version}`});原因:${reason}。${hitlNote}\n注意:仅回退了配方定义,运行中 PLC 未变动;要把恢复参数写入产线(统一回退),用 recipe_rollback 并带 dispatch=true。版本史用 recipe_versions 复核。`,
     }
   }
   catch (err) {
@@ -416,54 +534,146 @@ export async function toolRecipeRollback(agentId: string, args: {
   }
 }
 
+/**
+ * v19.5 HITL 下发裁决门:绑定 manual(或全局开关)时,配方动作不直接执行 ——
+ * 挂起等待人工裁决(复用 ToolApprovalService,人类批/拒理由原样回流;结构化 payload
+ * 随单落库,审批卡可渲染 Agent 的理由与参数明细):
+ *   批准       → 按原逻辑执行下发,回执附人工附言;
+ *   拒绝(可附指导)→ 工具回包携带人工指导文本,Agent 按指导修订候选后重新提交 ——
+ *   即"改好配方交给人类判断是否下发;不下发则人告诉 Agent 怎么修"的真实作业语义。
+ * 超时(默认 security.recipe_dispatch_timeout_ms,30min)自动按拒绝收敛。
+ */
+async function hitlDispatchGate(agentId: string, recipeId: string, detail: string, title: string, opts?: { payload?: unknown }): Promise<{ approved: boolean, comment: string, id: string }> {
+  const { getToolApprovals } = await import('../tool-approvals')
+  const timeoutMs = Number(settingOf('security.recipe_dispatch_timeout_ms')) || undefined
+  // nodeId = `recipe:<id>`:审批卡分流键(与 recipe-propose:<id> 平行;kind 保持 'dcw' 兼容既有裁决端点)
+  const decision = await getToolApprovals().request(agentId, `recipe:${recipeId}`, 'dcw', detail, {
+    title,
+    ...(opts?.payload !== undefined ? { payload: opts.payload } : {}),
+    ...(timeoutMs ? { timeoutMs } : {}),
+  })
+  return { approved: decision.approved, comment: decision.comment, id: decision.id }
+}
+
+/**
+ * Recipe 级下发间隔卡控(提案早拒):距上次已批准/已执行下发不足 opIntervalMs 时,
+ * 在挂审批卡**之前**拒绝(不建卡、不产线变动),报错含剩余秒数与应急豁免指引。
+ */
+function recipeOpIntervalGate(recipe: { id: string, name: string, opIntervalMs?: number }, emergency: boolean): { text: string, isError: true } | null {
+  try {
+    assertRecipeOpInterval(recipe, { emergency })
+    return null
+  }
+  catch (err) {
+    return { text: err instanceof Error ? err.message : String(err), isError: true }
+  }
+}
+
 /** 工具:recipe_trial —— 多参数候选整批试验下发(v19 配方链路核心)。
- *  候选值只覆盖列出节点(**必须是自己绑定的数控节点**);整批一次落产线,**不写配方版本** ——
- *  复测判读:有进步/达标 → recipe_update 固化(同 id 版本+1);劣化 → recipe_rollback(dispatch=true) 统一回退。
+ *  权限模型 v2:需绑定该 recipe 且过二级认证+运行门;候选值只覆盖列出节点(须为配方内节点)。
+ *  绑定 manual 时整批试验挂 HITL(理由随审批卡);整批一次落产线,不写配方版本 ——
+ *  复测判读:有进步/达标 → recipe_update 固化;劣化 → recipe_rollback(dispatch=true) 统一回退。
  *  受同线试验节拍卡控(默认 ≥5 分钟,防连发震荡);四层限界(量程∩参数∩产品)照常拦截。 */
 export async function toolRecipeTrial(agentId: string, args: {
   recipe_id?: string
   params?: Array<{ node_id?: string, value?: number | string }>
   hypothesis?: string
+  emergency?: boolean | string
 }): Promise<{ text: string, isError?: boolean }> {
   const recipeId = String(args.recipe_id ?? '').trim()
   const hypothesis = String(args.hypothesis ?? '').trim()
+  const emergency = args.emergency === true || args.emergency === 'true'
   if (!recipeId) return { text: 'recipe_id 必填(line_context 可看到当前配方 id)。', isError: true }
-  if (!hypothesis) return { text: 'hypothesis 必填:试验必须声明依据(知识库条目/数据分析结论),便于审计追溯。', isError: true }
+  if (!hypothesis) return { text: 'hypothesis 必填:试验必须声明依据(知识库条目/数据分析结论),便于审计追溯与人工审批判断。', isError: true }
   const list = (args.params ?? []).filter(p => p && String(p.node_id ?? '').trim() && Number.isFinite(Number(p.value)))
     .map(p => ({ nodeId: String(p.node_id).trim(), value: 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()
+  // 权限模型 v2:绑定 → 二级认证 → 运行门(未在执行的配方不可试验)
+  const gate = assertRecipeOperation(agentId, recipe, 'trial')
+  if (!gate.ok) return { text: gate.text, isError: true }
   for (const p of list) {
     const node = getDcwController().byId(p.nodeId)
     if (!node) return { text: `节点 ${p.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, p.nodeId, 'dcw')) {
-      return { text: `无权试验节点「${node.name}」(仅可改自己绑定的数控节点;缺授权找 lead 用 team_grant_nodes 授予)。`, isError: true }
+    if (!recipe.params.some(x => x.nodeId === p.nodeId)) {
+      return { text: `节点「${node.name}」不是配方「${recipe.name}」的参数节点;试验候选只能覆盖配方内参数。`, isError: true }
     }
   }
+  // Recipe 级下发间隔卡控(提案早拒):距上次已批准下发不足 opIntervalMs 即拒,不建卡
+  const cadence = recipeOpIntervalGate(recipe, emergency)
+  if (cadence) return cadence
   try {
-    const run = await getDcwController().applyRecipe(recipeId, { overrides: list, trial: true })
-    const okN = run.results.filter(r => r.ok).length
+    // HITL 门:manual 绑定(或全局开关)时,整批试验前先挂起等人工裁决(拒绝附指导 → 回给 Agent 修订)
+    let hitlNote = ''
+    let gateApprovalId = ''
+    if (gate.hitlRequired) {
+      const gateDecision = await hitlDispatchGate(
+        agentId,
+        recipe.id,
+        `${emergency ? '【应急豁免频控】' : ''}配方试验候选(整批 ${list.length} 参数):${list.map((p) => {
+          const node = getDcwController().byId(p.nodeId)
+          const old = recipe.params.find(x => x.nodeId === p.nodeId)?.value
+          return `${node?.name ?? p.nodeId} ${old ?? '?'}→${p.value}${node?.unit ?? ''}`
+        }).join(';')} | 假设:${hypothesis} | 批准=整批下发试验(不写版本);拒绝可附指导`,
+        `${emergency ? '【应急】' : ''}配方试验(整批候选)下发审批`,
+        { payload: { ...recipeApprovalPayload('trial', recipe.id, recipe.name, {
+          reason: hypothesis,
+          params: list.map((p) => {
+            const node = getDcwController().byId(p.nodeId)
+            const old = recipe.params.find(x => x.nodeId === p.nodeId)?.value
+            return { nodeId: p.nodeId, name: node?.name ?? p.nodeId, from: old ?? null, to: p.value, unit: node?.unit }
+          }),
+          runId: gate.activeRunId,
+        }), ...(emergency ? { emergency: true } : {}) } },
+      )
+      gateApprovalId = gateDecision.id
+      if (!gateDecision.approved) {
+        return {
+          text: `人工未批准本次试验下发。人工指导:${gateDecision.comment || '(无附言,仅不同意候选)'}。请按人工指导修订候选参数(必要时先 recipe_update 调整基线),然后重新提交 recipe_trial。`,
+        }
+      }
+      // 人工附言随批准回执回流(Agent 与审计都能看到放行时人的原话)
+      if (gateDecision.comment) hitlNote = `\n人工附言:${gateDecision.comment}`
+    }
+    const run = await getDcwController().applyRecipe(recipeId, { overrides: list, trial: true, agentDispatch: true, agentApprovalId: gateApprovalId, emergency })
+    // ACK 鉴定三段口径(2026-10-08):ok 只是命令受理,未证实/失败必须如实回给 Agent
+    const acks = run.ackSummary ?? { verified: run.results.filter(r => r.ok).length, unverified: 0, failed: run.results.filter(r => !r.ok).length, total: run.results.length }
     // 批次级留痕:试验动作入审计(逐参数写已有 write-audit;这里是"一次试验"粒度)
     try {
       const { recordOps } = await import('../../ops/ops')
       recordOps({
         actor: agentId, actorName: agentBadgeLabel(agentId), actorKind: 'agent',
         action: 'recipe.trial', kind: 'recipe', targetKind: 'recipe', targetId: recipeId, recipeId, lineId: recipe.lineId,
-        summary: `配方试验整批下发(${okN}/${run.results.length} 成功,批次 ${run.id.slice(0, 8)}):${list.map(p => `${p.nodeId.slice(0, 8)}→${p.value}`).join(';')} | 假设:${hypothesis}`,
+        level: acks.failed > 0 ? 'error' : acks.unverified > 0 ? 'warn' : 'info',
+        summary: `${emergency ? '【应急】' : ''}配方试验整批下发(证实 ${acks.verified}/${acks.total},未证实 ${acks.unverified},失败 ${acks.failed},批次 ${run.id.slice(0, 8)}):${list.map(p => `${p.nodeId.slice(0, 8)}→${p.value}`).join(';')} | 假设:${hypothesis}`,
+        detail: { runId: run.id, ackSummary: acks, ...(emergency ? { emergency: true } : {}) },
       })
     }
     catch { /* 审计失败不影响试验结果 */ }
+    const ackTagOf = (r: typeof run.results[number]): string => {
+      if (!r.ok) return ''
+      return r.verify?.verdict === 'verified' || r.ack === 'readback-verified' ? ' [证实✓]' : ' [未证实⚠]'
+    }
     const changed = run.results.map((r) => {
       const node = r.nodeId ? getDcwController().byId(r.nodeId) : undefined
       const reason = r.ok ? '' : `(${String(r.message).slice(0, 60)})`
-      return `${node?.name ?? r.templateRef}→${r.value}${node?.unit ?? ''}${r.ok ? '' : ` 被拒${reason}`}`
+      return `${node?.name ?? r.templateRef}→${r.value}${node?.unit ?? ''}${ackTagOf(r)}${r.ok ? '' : ` 被拒${reason}`}`
     }).join(';')
+    // 未证实/失败一律 isError(ACK 鉴定铁律:不许把"仅链路受理"报成试验成功)
+    if (acks.failed > 0 || acks.unverified > 0) {
+      return {
+        text: [
+          `试验下发 ACK 鉴定未全绿(证实 ${acks.verified}/${acks.total},未证实 ${acks.unverified},失败 ${acks.failed},批次 ${run.id.slice(0, 8)}):${changed}。假设:${hypothesis}。${hitlNote}`,
+          '「未证实」=命令已发到链路但设备侧未确认生效;请用 daq_query 复测这些参数的真实状态后再判读试验效果,必要时对未证实参数单独重发或 recipe_rollback 统一回退,并写入汇报提醒人类。',
+        ].join('\n'),
+        isError: true,
+      }
+    }
     return {
-      text: `试验已整批下发(${okN}/${run.results.length} 成功,批次 ${run.id.slice(0, 8)}):${changed}。假设:${hypothesis}。注意:本次试验**未写入配方版本** —— 等待工艺惯性后 daq_query 复测判读:有进步/达标 → recipe_update 把候选值固化进配方(同 id 版本+1);无进步/劣化 → recipe_rollback(recipe_id, dispatch=true, reason=…) 统一回退(定义回退+PLC 整批恢复)。`,
+      text: `试验已整批下发并全部设备证实(${acks.verified}/${acks.total},批次 ${run.id.slice(0, 8)}):${changed}。假设:${hypothesis}。${hitlNote}注意:本次试验**未写入配方版本** —— 等待工艺惯性后 daq_query 复测判读:有进步/达标 → recipe_update 把候选值固化进配方(同 id 版本+1);无进步/劣化 → recipe_rollback(recipe_id, dispatch=true, reason=…) 统一回退(定义回退+PLC 整批恢复)。`,
     }
   }
   catch (err) {
@@ -472,38 +682,98 @@ export async function toolRecipeTrial(agentId: string, args: {
 }
 
 /** 工具:recipe_apply —— 把配方当前已固化参数整批下发到产线(改配方(recipe_update)之后用)。
- *  与 recipe_trial 的区别:apply 下发的是**已固化版本**(无候选覆盖),用于"改配方 → 配方下发"链路的正式下发。 */
+ *  权限模型 v2:需绑定该 recipe 且过二级认证+运行门;绑定 manual 时挂 HITL(理由随审批卡)。 */
 export async function toolRecipeApply(agentId: string, args: {
   recipe_id?: string
   reason?: string
+  emergency?: boolean | string
 }): Promise<{ text: string, isError?: boolean }> {
   const recipeId = String(args.recipe_id ?? '').trim()
+  const emergency = args.emergency === true || args.emergency === 'true'
   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 boundInRecipe = getAgentNodeBindingRepo().byAgent(agentId)
-    .some(b => b.kind === 'dcw' && recipe.params.some(p => p.nodeId === b.nodeId))
-  if (!boundInRecipe) {
-    return { text: `无权下发配方 ${recipeId}(需持有该配方至少一个数控节点的授权;找 lead 用 team_grant_nodes 授予)。`, isError: true }
-  }
+  // 理由强制:下发必须让人(产线专家)看懂为什么这样调 —— 无描述的下发不得进入审批/执行
+  const reason = String(args.reason ?? '').trim()
+  if (!reason) return { text: 'reason 必填:整批下发必须说明依据(如数采证据/试验结论/GOAL 差距分析),产线专家要在审批卡上看懂你为什么这样调。', isError: true }
+  // 权限模型 v2:绑定 → 二级认证 → 运行门
+  const gate = assertRecipeOperation(agentId, recipe, 'dispatch')
+  if (!gate.ok) return { text: gate.text, isError: true }
+  // Recipe 级下发间隔卡控(提案早拒):距上次已批准下发不足 opIntervalMs 即拒,不建卡
+  const cadence = recipeOpIntervalGate(recipe, emergency)
+  if (cadence) return cadence
   try {
-    const run = await getDcwController().applyRecipe(recipeId)
-    const okN = run.results.filter(r => r.ok).length
+    // HITL 门:manual 绑定(或全局开关)时,正式下发前先挂起等人工裁决(拒绝附指导 → 回给 Agent 修订)
+    let hitlNote = ''
+    let gateApprovalId = ''
+    if (gate.hitlRequired) {
+      const gateDecision = await hitlDispatchGate(
+        agentId,
+        recipe.id,
+        `${emergency ? '【应急豁免频控】' : ''}配方正式下发:「${recipe.name}」v${recipe.version ?? 1} 全参数整批(${recipe.params.length} 项):${recipe.params.map((p) => {
+          const node = getDcwController().byId(p.nodeId)
+          return `${node?.name ?? p.nodeId}=${p.value}${node?.unit ?? ''}`
+        }).join(';')} | 理由:${reason} | 批准=整批下发;拒绝可附指导`,
+        `${emergency ? '【应急】' : ''}配方下发审批`,
+        { payload: { ...recipeApprovalPayload('dispatch', recipe.id, recipe.name, {
+          reason,
+          params: recipe.params.map((p) => {
+            const node = getDcwController().byId(p.nodeId)
+            return { nodeId: p.nodeId, name: node?.name ?? p.nodeId, from: null, to: p.value, unit: node?.unit }
+          }),
+          runId: gate.activeRunId,
+        }), ...(emergency ? { emergency: true } : {}) } },
+      )
+      gateApprovalId = gateDecision.id
+      if (!gateDecision.approved) {
+        return {
+          text: `人工未批准本次配方下发。人工指导:${gateDecision.comment || '(无附言)'}。请按人工指导修订配方(recipe_update)后重新提交 recipe_apply。`,
+        }
+      }
+      // 人工附言随批准回执回流(与 recipe_trial 同口径)
+      if (gateDecision.comment) hitlNote = `\n人工附言:${gateDecision.comment}`
+    }
+    const run = await getDcwController().applyRecipe(recipeId, { agentDispatch: true, agentApprovalId: gateApprovalId, emergency })
+    // ACK 鉴定三段口径(2026-10-08):ok 只是命令受理,未证实/失败必须如实回给 Agent
+    const acks = run.ackSummary ?? { verified: run.results.filter(r => r.ok).length, unverified: 0, failed: run.results.filter(r => !r.ok).length, total: run.results.length }
+    // 逐参数标注:被跳过/失败的参数(节点停用/已删除/限界拒绝)必须透出给 Agent,
+    // 否则回包只见 N/N 成功数,无法定位哪些参数未生效(与 recipe_trial 的逐参数渲染同口径)。
+    const skipped = run.results.filter(r => !r.ok)
+      .map((r) => {
+        const node = r.nodeId ? getDcwController().byId(r.nodeId) : undefined
+        return `${node?.name ?? r.templateRef ?? r.nodeId ?? '?'}: ${String(r.message).slice(0, 80)}`
+      })
+    // 未证实参数(ok 但仅链路受理)单独点名 —— 这正是"参数真实正确下发"要堵的盲区
+    const unverified = run.results.filter(r => r.ok && r.verify?.verdict !== 'verified' && r.ack !== 'readback-verified')
+      .map((r) => {
+        const node = r.nodeId ? getDcwController().byId(r.nodeId) : undefined
+        return `${node?.name ?? r.templateRef ?? r.nodeId ?? '?'}: ${String(r.message).slice(0, 100)}`
+      })
+    const skippedNote = skipped.length > 0 ? `\n未生效参数(${skipped.length}):\n  - ${skipped.join('\n  - ')}` : ''
+    const unverifiedNote = unverified.length > 0 ? `\n未证实参数(${unverified.length};命令已受理但设备侧未确认):\n  - ${unverified.join('\n  - ')}` : ''
     try {
       const { recordOps } = await import('../../ops/ops')
       recordOps({
         actor: agentId, actorName: agentBadgeLabel(agentId), actorKind: 'agent',
         action: 'recipe.apply', kind: 'recipe', targetKind: 'recipe', targetId: recipeId, recipeId, lineId: recipe.lineId,
-        summary: `Agent 整批下发配方 v${recipe.version ?? 1}(${okN}/${run.results.length} 参数成功,批次 ${run.id.slice(0, 8)})${args.reason ? ` | 原因:${String(args.reason).trim()}` : ''}`,
+        level: acks.failed > 0 ? 'error' : acks.unverified > 0 ? 'warn' : 'info',
+        summary: `${emergency ? '【应急】' : ''}Agent 整批下发配方 v${recipe.version ?? 1}(证实 ${acks.verified}/${acks.total},未证实 ${acks.unverified},失败 ${acks.failed},批次 ${run.id.slice(0, 8)}) | 原因:${reason}`,
+        detail: { runId: run.id, ackSummary: acks, ...(emergency ? { emergency: true } : {}) },
       })
     }
     catch { /* 审计失败不影响下发结果 */ }
+    if (acks.failed > 0 || acks.unverified > 0) {
+      return {
+        text: [
+          `配方「${recipe.name}」v${recipe.version ?? 1} 整批下发 ACK 鉴定未全绿(证实 ${acks.verified}/${acks.total},未证实 ${acks.unverified},失败 ${acks.failed},批次 ${run.id.slice(0, 8)})。${hitlNote}`,
+          `${skippedNote}${unverifiedNote}`,
+          '请用 daq_query 复测未证实参数的真实状态;必要时 dcw_control 单独重发或 recipe_rollback(dispatch=true) 统一回退,并把清单写入汇报提醒人类。',
+        ].filter(Boolean).join('\n'),
+        isError: true,
+      }
+    }
     return {
-      text: `配方「${recipe.name}」v${recipe.version ?? 1} 已整批下发(${okN}/${run.results.length} 参数成功,批次 ${run.id.slice(0, 8)})。用 daq_query 复测确认工艺响应。`,
+      text: `配方「${recipe.name}」v${recipe.version ?? 1} 已整批下发并全部设备证实(${acks.verified}/${acks.total},批次 ${run.id.slice(0, 8)})。${skippedNote}${hitlNote}用 daq_query 复测确认工艺响应。`,
     }
   }
   catch (err) {