agentworkshop 0.8.6 → 0.8.8

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

@@ -1,212 +1,225 @@
-/**
- * DcwControllerWrite —— 数控写入(联锁/量程/租约)与驱动探测
- * (拆分层,承 DcwControllerBindings;方法体与原文件逐行一致)
- */
-import { DcwControllerBindings } from './bindings'
-import type { DcwDriverKind, DcwWriteMeta } from '../../../../../shared/dcw-protocol'
-import type { DcwNode } from '../dcw-node'
-import { AppError, ErrorCodes } from '../../../../utils/errors'
-import { assertWithinLimits, assertStepLimit } from '../param-limits'
-import { getRecipeRollBackManager } from '../recipe-rollback-manager'
-import { requireDcwDriverKind, resolveDcwDriver } from '../drivers'
-import { recordDcwWriteOps } from './write-audit'
-import { setWriteLockUntil } from './gate-persist'
-import { recordOps } from '../../ops/ops'
-import { getActiveLineRun } from '../line-run'
-
-// ================================================================
-// 只读预检谓词(产线 Co-Pilot P2:recipe_propose 整包方案的预审批校验)
-// ================================================================
-
-/** 预检结果:ok=false 时 violations[0] 即 write() 咽喉点会抛出的同文错误(单点收敛,消息零漂移) */
-export interface RecipeParamPreflight {
-  ok: boolean
-  violations: string[]
-  /** 原始错误(assertWithinLimits 抛出的 AppError;预检方需要复刻拒绝语义时原样复抛) */
-  error?: AppError
-}
-
-/**
- * 限界预检(只读,不写不下发不锁窗):对「节点+目标工程量」复跑 write() 咽喉点的
- * assertWithinLimits 断言,把 throw 式拒绝归一为 { ok, violations } 结果。
- * 选项镜像 write() 的真实语义:skipRecipe=true 即配方下发路径(量程∩参数基准∩产品三层,
- * **不含**步长/60s 间隔/保持窗 —— recipe 执行路径本就不走这些,预检不得擅自收紧);
- * 缺省 skipRecipe=false 即在线写路径(含活动配方工艺窗口)。
- * 消费方:① write() 咽喉点(行为零变化: violations[0]/error 复刻原 throw);
- *        ② recipe_propose 预检(越界参数在审批单生成前剔除,「批准必被拒包」不可达)。
- */
-export function evaluateRecipeParamLimits(node: DcwNode, eng: number, opts?: { includeSoft?: boolean, skipRecipe?: boolean }): RecipeParamPreflight {
-  try {
-    assertWithinLimits(node, eng, { includeSoft: opts?.includeSoft !== false, skipRecipe: opts?.skipRecipe === true })
-    return { ok: true, violations: [] }
-  }
-  catch (err) {
-    const msg = err instanceof Error ? err.message : String(err)
-    return {
-      ok: false,
-      violations: [msg],
-      // 复刻 write() 原分类:AppError 原样透传;非 AppError 按 400 归一(与原 catch 同口径)
-      error: err instanceof AppError ? err : new AppError(400, ErrorCodes.VALIDATION_ERROR, msg),
-    }
-  }
-}
-
-export abstract class DcwControllerWrite extends DcwControllerBindings {
-  /** 手动设定:用户提交工程量,网关校验/换算/下发/回读校验。
-   *  配方联锁:产线运行中,写入值还须落在活动配方对该参数的工艺窗口内
-   *  (节点全局量程之外的第二道约束 —— 换配方即换工艺窗口)。
-   *  meta(F7):账本与优化记录的身份信息 —— 手动/配方/Agent/回退四路共用本入口,
-   *  缺省按 manual/user 记账;调控闭环护栏(Agent 互斥/回退冷却)在 beforeWrite。 */
-  async write(id: string, eng: number, recipeRunId: string | null = null, meta?: DcwWriteMeta) {
-    this.ensureLoop()
-    const rt = this.runtimes.get(id)
-    if (!rt) throw new AppError(404, ErrorCodes.NOT_FOUND, `控制节点不存在: ${id}`)
-    const node = rt.node
-    // 控制暂停双重门控:网关全局暂停(暂停全部控制)或节点级暂停 → 一律拒绝下发。
-    // 手动 REST / 配方下发 / 产线开跑 / Agent 工具共用本入口,拒绝语义单点收敛。
-    if (!this.running) {
-      throw new AppError(409, ErrorCodes.CONFLICT, '控制网关已暂停(暂停全部控制):设定下发被拒绝,请先「恢复全部控制」')
-    }
-    if (!node.enabled) {
-      throw new AppError(409, ErrorCodes.CONFLICT, `当前节点暂停:「${node.name}」控制已暂停,仅开启控制的节点可被设定`)
-    }
-    // 调控闭环护栏(F1/F8):Agent 互斥(open 记录他人持有)+ 回退冷却方向性
-    // v18 拒绝留痕:治理咽喉点的每一次拒绝(量程/配方窗/步限/间隔/保持窗)入审计 ——
-    // 安全审计需要"谁在何时试图把参数写到哪、被哪条防线拦下";给调用方的反馈由错误消息承担。
-    const reject = (err: AppError): never => {
-      try {
-        const runNow = getActiveLineRun(node.lineId)
-        recordOps({
-          actor: meta?.actor ?? 'system', actorName: meta?.actorName ?? '', actorKind: meta?.source === 'agent' ? 'agent' : (meta?.source === 'manual' ? 'user' : 'system'),
-          action: 'dcw.write.rejected', kind: 'write', targetKind: 'dcw', targetId: id, lineId: node.lineId,
-          productId: runNow?.productId ?? '',
-          recipeId: runNow?.recipeId ?? recipeRunId ?? '',
-          summary: `设定 ${eng}${node.unit || ''} 被拒:${err.message}`,
-        })
-      }
-      catch { /* 审计失败不改变拒绝语义 */ }
-      throw err
-    }
-    try {
-      getRecipeRollBackManager().beforeWrite(node, eng, meta)
-    }
-    catch (err) {
-      reject(err instanceof AppError ? err : new AppError(409, ErrorCodes.CONFLICT, String(err instanceof Error ? err.message : err)))
-    }
-    // 写入限界分层联锁(param-limits):节点安全量程(结构层,驱动内 validateEng 结构性兜底)
-    // ∩ 工艺参数基准限界 ∩ 活动产品限界 ∩ 活动配方工艺窗口 —— 逐层收窄取交集,
-    // 手动 REST / Agent 工具 / 配方下发 / 回退四路共用本咽喉点,越界一律拒绝。
-    // D8 基准消融:仅 AW_BENCH_MODE=1 且 meta.benchArm='no-interlock'/'ungated' 时
-    // 旁路软联锁层(参数/产品/配方);结构层与硬量程校验结构性不可旁路;
-    // 生产模式(env 缺省)恒为 full 臂。
-    const benchNoInterlock = process.env.AW_BENCH_MODE === '1' && (meta?.benchArm === 'no-interlock' || meta?.benchArm === 'ungated')
-    // 配方下发路径(recipeRunId != null)跳过配方窗口层:下发值已在配方保存时对自身窗口校验,
-    // 且中途应用新配方不应被旧批次配方窗口误伤;产品/参数基准层对配方下发照常约束。
-    // 预检谓词(evaluateRecipeParamLimits)与本咽喉点共用同一断言:结果 ok=false 时
-    // 复抛其捕获的原始错误 —— 拒绝语义/错误码/消息与原 inline throw 逐字节一致。
-    const limits = evaluateRecipeParamLimits(node, eng, { includeSoft: !benchNoInterlock, skipRecipe: recipeRunId != null })
-    if (!limits.ok) {
-      reject(limits.error ?? new AppError(400, ErrorCodes.VALIDATION_ERROR, limits.violations[0] ?? '写入限界校验失败'))
-    }
-    const srcForLock = meta?.source ?? (recipeRunId ? 'recipe' : 'manual')
-    const benchBypass = process.env.AW_BENCH_MODE === '1'
-    // 在线 Agent/人工控制都走安全小步与 60s 最小间隔:这是探索阶段的硬卡控，
-    // 不依赖提示词也不依赖前端，驱动调用前完成拒绝。recipe/rollback 仍由其
-    // 专用路径管理，避免启动批次时把整套配方误判为在线探索步。
-    if ((srcForLock === 'agent' || srcForLock === 'manual') && !benchBypass) {
-      const previous = typeof node.value === 'number'
-        ? node.value
-        : (typeof node.readValue === 'number' ? node.readValue : null)
-      try {
-        assertStepLimit(node, eng, { includeSoft: !benchNoInterlock, skipRecipe: false }, previous)
-      }
-      catch (err) {
-        reject(err instanceof AppError ? err : new AppError(409, ErrorCodes.STEP_LIMIT_EXCEEDED, String(err instanceof Error ? err.message : err)))
-      }
-      const previousAt = node.lastWriteAt ? Date.parse(node.lastWriteAt) : NaN
-      if (Number.isFinite(previousAt)) {
-        const elapsed = Date.now() - previousAt
-        if (elapsed < 60_000) {
-          reject(new AppError(429, ErrorCodes.WRITE_INTERVAL_NOT_ELAPSED, `DCW 节点「${node.name}」两次在线写入间隔必须至少 60s，当前还需 ${Math.ceil((60_000 - elapsed) / 1000)}s`))
-        }
-      }
-    }
-    // 写入保持窗(防参数震荡):agent/manual 写成功一次即锁定节点 writeLockSeconds;
-    // 锁定期间的新写一律 429 快速拒绝(不排队 —— 排队写会在窗满后立刻落库,等同
-    // 为持续篡改保留通道)。rollback(安全恢复)/recipe(批量下发)不受保持窗约束;
-    // AW_BENCH_MODE=1 基准旁路(基准多轮连续写同节点,锁会破坏既有证据可复现性)。
-    // 顺序在限界联锁之后:越量程/越窗是确定性非法(400),不得被暂时性限频(429)
-    // 抢答,否则客户端会对非法值做 30s 的无谓重试。
-    const configuredLockMs = Math.max(0, Math.round((node.writeLockSeconds ?? 30) * 1000))
-    const lockMs = (srcForLock === 'agent' || srcForLock === 'manual') && !benchBypass ? Math.max(60_000, configuredLockMs) : configuredLockMs
-    const lockable = (srcForLock === 'agent' || srcForLock === 'manual') && lockMs > 0 && !benchBypass
-    if (lockable) {
-      const now = Date.now()
-      const until = this.writeLocks.get(id) ?? 0
-      // 过期条目顺手清掉,防注册表随节点删除/长时运行无限增长
-      if (this.writeLocks.size > 500) {
-        for (const [k, t] of this.writeLocks) {
-          if (t <= now) this.writeLocks.delete(k)
-        }
-      }
-      if (now < until) {
-        reject(new AppError(
-          429,
-          ErrorCodes.WRITE_FREQUENT,
-          `当前写入频繁:「${node.name}」处于写入保持窗口(剩余 ${Math.ceil((until - now) / 1000)}s),请稍后再试`,
-        ))
-      }
-    }
-    // D8: no-readback / ungated 臂 → 容差置 MAX,回读差异不致败(假成功语义,供 I2 消融)
-    const benchNoReadback = process.env.AW_BENCH_MODE === '1' && (meta?.benchArm === 'no-readback' || meta?.benchArm === 'ungated')
-    const benchToleranceOverride = benchNoReadback ? Number.MAX_VALUE : undefined
-    const prevValue = typeof node.value === 'number' ? node.value : null
-    const outcome = await rt.write(eng, recipeRunId, benchToleranceOverride)
-    // 调控闭环入册:仅成功写记锚/开记录(失败写不动账本 —— PLC 值未变更);
-    // 窗口聚合异步回填(F2)
-    if (outcome.ok !== false) {
-      // 写成功 → 锁定写入保持窗(agent/manual 路径;recipe/rollback 豁免)
-      if (lockable) {
-        this.writeLocks.set(id, Date.now() + lockMs)
-        setWriteLockUntil(id, Date.now() + lockMs) // P1-5 落盘:重启窗口延续
-      }
-      try {
-        const rbInfo = getRecipeRollBackManager().afterWrite(
-          node,
-          eng,
-          prevValue,
-          meta ?? { source: recipeRunId ? 'recipe' : 'manual', actor: 'user' },
-          recipeRunId,
-        )
-        if (rbInfo) {
-          outcome.recordId = rbInfo.recordId
-          outcome.anchorId = rbInfo.anchorId
-        }
-      }
-      catch (err) {
-        console.error('[dcw] 调控闭环入册失败(不影响写结果):', err)
-      }
-      // 运维日志 + 插件钩子:所有下发路径(manual/recipe/agent/rollback)单点入册(write-audit)
-      try {
-        recordDcwWriteOps({ id, node, eng, prevValue, outcome, src: srcForLock as DcwWriteMeta['source'], meta, recipeRunId })
-      }
-      catch {
-        // 日志失败不影响写结果
-      }
-    }
-    return outcome
-  }
-
-  /** 连接测试(显式声明的驱动 kind 必须可解析;未知协议显式报错,不静默 mock —— P0-5) */
-  async testDriver(kind: DcwDriverKind, driverConfig: Record<string, unknown>) {
-    return resolveDcwDriver(requireDcwDriverKind(kind)).test(driverConfig)
-  }
-
-  async testNode(id: string) {
-    const node = this.repo.byId(id)
-    if (!node) throw new AppError(404, ErrorCodes.NOT_FOUND, `控制节点不存在: ${id}`)
-    return this.testDriver(node.driver, node.driverConfig)
-  }
-
-  // ---------- 工艺参数映射面(用户/Agent 的唯一语义读写面)----------
-}
+/**
+ * DcwControllerWrite —— 数控写入(联锁/量程/租约)与驱动探测
+ * (拆分层,承 DcwControllerBindings;方法体与原文件逐行一致)
+ */
+import { DcwControllerBindings } from './bindings'
+import type { DcwDriverKind, DcwWriteMeta } from '../../../../../shared/dcw-protocol'
+import type { DcwNode } from '../dcw-node'
+import { AppError, ErrorCodes } from '../../../../utils/errors'
+import { assertWithinLimits, assertStepLimit } from '../param-limits'
+import { getRecipeRollBackManager } from '../recipe-rollback-manager'
+import { requireDcwDriverKind, resolveDcwDriver } from '../drivers'
+import { recordDcwWriteOps } from './write-audit'
+import { setWriteLockUntil } from './gate-persist'
+import { recordOps } from '../../ops/ops'
+import { getActiveLineRun } from '../line-run'
+import { benchModeEnabled } from '../../bench-mode'
+
+// ================================================================
+// 只读预检谓词(产线 Co-Pilot P2:recipe_propose 整包方案的预审批校验)
+// ================================================================
+
+/** 预检结果:ok=false 时 violations[0] 即 write() 咽喉点会抛出的同文错误(单点收敛,消息零漂移) */
+export interface RecipeParamPreflight {
+  ok: boolean
+  violations: string[]
+  /** 原始错误(assertWithinLimits 抛出的 AppError;预检方需要复刻拒绝语义时原样复抛) */
+  error?: AppError
+}
+
+/**
+ * 限界预检(只读,不写不下发不锁窗):对「节点+目标工程量」复跑 write() 咽喉点的
+ * assertWithinLimits 断言,把 throw 式拒绝归一为 { ok, violations } 结果。
+ * 选项镜像 write() 的真实语义:skipRecipe=true 即配方下发路径(量程∩参数基准∩产品三层,
+ * **不含**步长/60s 间隔/保持窗 —— recipe 执行路径本就不走这些,预检不得擅自收紧);
+ * 缺省 skipRecipe=false 即在线写路径(含活动配方工艺窗口)。
+ * 消费方:① write() 咽喉点(行为零变化: violations[0]/error 复刻原 throw);
+ *        ② recipe_propose 预检(越界参数在审批单生成前剔除,「批准必被拒包」不可达)。
+ */
+export function evaluateRecipeParamLimits(node: DcwNode, eng: number, opts?: { includeSoft?: boolean, skipRecipe?: boolean }): RecipeParamPreflight {
+  try {
+    assertWithinLimits(node, eng, { includeSoft: opts?.includeSoft !== false, skipRecipe: opts?.skipRecipe === true })
+    return { ok: true, violations: [] }
+  }
+  catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return {
+      ok: false,
+      violations: [msg],
+      // 复刻 write() 原分类:AppError 原样透传;非 AppError 按 400 归一(与原 catch 同口径)
+      error: err instanceof AppError ? err : new AppError(400, ErrorCodes.VALIDATION_ERROR, msg),
+    }
+  }
+}
+
+export abstract class DcwControllerWrite extends DcwControllerBindings {
+  /** 手动设定:用户提交工程量,网关校验/换算/下发/回读校验。
+   *  配方联锁:产线运行中,写入值还须落在活动配方对该参数的工艺窗口内
+   *  (节点全局量程之外的第二道约束 —— 换配方即换工艺窗口)。
+   *  meta(F7):账本与优化记录的身份信息 —— 手动/配方/Agent/回退四路共用本入口,
+   *  缺省按 manual/user 记账;调控闭环护栏(Agent 互斥/回退冷却)在 beforeWrite。 */
+  async write(id: string, eng: number, recipeRunId: string | null = null, meta?: DcwWriteMeta) {
+    this.ensureLoop()
+    const rt = this.runtimes.get(id)
+    if (!rt) throw new AppError(404, ErrorCodes.NOT_FOUND, `控制节点不存在: ${id}`)
+    const node = rt.node
+    // 控制暂停双重门控:网关全局暂停(暂停全部控制)或节点级暂停 → 一律拒绝下发。
+    // 手动 REST / 配方下发 / 产线开跑 / Agent 工具共用本入口,拒绝语义单点收敛。
+    if (!this.running) {
+      throw new AppError(409, ErrorCodes.CONFLICT, '控制网关已暂停(暂停全部控制):设定下发被拒绝,请先「恢复全部控制」')
+    }
+    if (!node.enabled) {
+      throw new AppError(409, ErrorCodes.CONFLICT, `当前节点暂停:「${node.name}」控制已暂停,仅开启控制的节点可被设定`)
+    }
+    // 调控闭环护栏(F1/F8):Agent 互斥(open 记录他人持有)+ 回退冷却方向性
+    // v18 拒绝留痕:治理咽喉点的每一次拒绝(量程/配方窗/步限/间隔/保持窗)入审计 ——
+    // 安全审计需要"谁在何时试图把参数写到哪、被哪条防线拦下";给调用方的反馈由错误消息承担。
+    const reject = (err: AppError): never => {
+      try {
+        const runNow = getActiveLineRun(node.lineId)
+        recordOps({
+          actor: meta?.actor ?? 'system', actorName: meta?.actorName ?? '', actorKind: meta?.source === 'agent' ? 'agent' : (meta?.source === 'manual' ? 'user' : 'system'),
+          action: 'dcw.write.rejected', kind: 'write', targetKind: 'dcw', targetId: id, lineId: node.lineId,
+          productId: runNow?.productId ?? '',
+          recipeId: runNow?.recipeId ?? recipeRunId ?? '',
+          summary: `设定 ${eng}${node.unit || ''} 被拒:${err.message}`,
+        })
+      }
+      catch { /* 审计失败不改变拒绝语义 */ }
+      throw err
+    }
+    try {
+      getRecipeRollBackManager().beforeWrite(node, eng, meta)
+    }
+    catch (err) {
+      reject(err instanceof AppError ? err : new AppError(409, ErrorCodes.CONFLICT, String(err instanceof Error ? err.message : err)))
+    }
+    // 写入限界分层联锁(param-limits):节点安全量程(结构层,驱动内 validateEng 结构性兜底)
+    // ∩ 工艺参数基准限界 ∩ 活动产品限界 ∩ 活动配方工艺窗口 —— 逐层收窄取交集,
+    // 手动 REST / Agent 工具 / 配方下发 / 回退四路共用本咽喉点,越界一律拒绝。
+    // D8 基准消融:仅 AW_BENCH_MODE=1 且 meta.benchArm='no-interlock'/'ungated' 时
+    // 旁路软联锁层(参数/产品/配方);结构层与硬量程校验结构性不可旁路;
+    // 生产模式(env 缺省)恒为 full 臂。
+    const benchNoInterlock = benchModeEnabled() && (meta?.benchArm === 'no-interlock' || meta?.benchArm === 'ungated')
+    // 配方下发路径(recipeRunId != null)跳过配方窗口层:下发值已在配方保存时对自身窗口校验,
+    // 且中途应用新配方不应被旧批次配方窗口误伤;产品/参数基准层对配方下发照常约束。
+    // 预检谓词(evaluateRecipeParamLimits)与本咽喉点共用同一断言:结果 ok=false 时
+    // 复抛其捕获的原始错误 —— 拒绝语义/错误码/消息与原 inline throw 逐字节一致。
+    const limits = evaluateRecipeParamLimits(node, eng, { includeSoft: !benchNoInterlock, skipRecipe: recipeRunId != null })
+    if (!limits.ok) {
+      reject(limits.error ?? new AppError(400, ErrorCodes.VALIDATION_ERROR, limits.violations[0] ?? '写入限界校验失败'))
+    }
+    const srcForLock = meta?.source ?? (recipeRunId ? 'recipe' : 'manual')
+    const benchBypass = benchModeEnabled()
+    // 在线 Agent/人工控制都走安全小步与 60s 最小间隔:这是探索阶段的硬卡控，
+    // 不依赖提示词也不依赖前端，驱动调用前完成拒绝。recipe/rollback 仍由其
+    // 专用路径管理，避免启动批次时把整套配方误判为在线探索步。
+    if ((srcForLock === 'agent' || srcForLock === 'manual') && !benchBypass) {
+      const previous = typeof node.value === 'number'
+        ? node.value
+        : (typeof node.readValue === 'number' ? node.readValue : null)
+      try {
+        assertStepLimit(node, eng, { includeSoft: !benchNoInterlock, skipRecipe: false }, previous)
+      }
+      catch (err) {
+        reject(err instanceof AppError ? err : new AppError(409, ErrorCodes.STEP_LIMIT_EXCEEDED, String(err instanceof Error ? err.message : err)))
+      }
+      // 失败冷却(5s):失败写不占 60s 成功间隔(断链恢复可立即重试),
+      // 但也不允许失败后无间隔轰炸设备 —— 只认最近一次**尝试**且节点仍处 error。
+      if (node.state === 'error' && node.lastAttemptAt) {
+        const failedAt = Date.parse(node.lastAttemptAt)
+        if (Number.isFinite(failedAt)) {
+          const sinceFail = Date.now() - failedAt
+          if (sinceFail < 5_000) {
+            reject(new AppError(429, ErrorCodes.WRITE_INTERVAL_NOT_ELAPSED, `DCW 节点「${node.name}」上次写入失败,${Math.ceil((5_000 - sinceFail) / 1000)}s 后可重试`))
+          }
+        }
+      }
+      // 60s 成功间隔:只认最近一次**成功**下发(失败尝试不占用窗口)
+      const previousAt = node.lastWriteAt ? Date.parse(node.lastWriteAt) : NaN
+      if (Number.isFinite(previousAt)) {
+        const elapsed = Date.now() - previousAt
+        if (elapsed < 60_000) {
+          reject(new AppError(429, ErrorCodes.WRITE_INTERVAL_NOT_ELAPSED, `DCW 节点「${node.name}」两次在线写入间隔必须至少 60s，当前还需 ${Math.ceil((60_000 - elapsed) / 1000)}s`))
+        }
+      }
+    }
+    // 写入保持窗(防参数震荡):agent/manual 写成功一次即锁定节点 writeLockSeconds;
+    // 锁定期间的新写一律 429 快速拒绝(不排队 —— 排队写会在窗满后立刻落库,等同
+    // 为持续篡改保留通道)。rollback(安全恢复)/recipe(批量下发)不受保持窗约束;
+    // AW_BENCH_MODE=1 基准旁路(基准多轮连续写同节点,锁会破坏既有证据可复现性)。
+    // 顺序在限界联锁之后:越量程/越窗是确定性非法(400),不得被暂时性限频(429)
+    // 抢答,否则客户端会对非法值做 30s 的无谓重试。
+    const configuredLockMs = Math.max(0, Math.round((node.writeLockSeconds ?? 30) * 1000))
+    const lockMs = (srcForLock === 'agent' || srcForLock === 'manual') && !benchBypass ? Math.max(60_000, configuredLockMs) : configuredLockMs
+    const lockable = (srcForLock === 'agent' || srcForLock === 'manual') && lockMs > 0 && !benchBypass
+    if (lockable) {
+      const now = Date.now()
+      const until = this.writeLocks.get(id) ?? 0
+      // 过期条目顺手清掉,防注册表随节点删除/长时运行无限增长
+      if (this.writeLocks.size > 500) {
+        for (const [k, t] of this.writeLocks) {
+          if (t <= now) this.writeLocks.delete(k)
+        }
+      }
+      if (now < until) {
+        reject(new AppError(
+          429,
+          ErrorCodes.WRITE_FREQUENT,
+          `当前写入频繁:「${node.name}」处于写入保持窗口(剩余 ${Math.ceil((until - now) / 1000)}s),请稍后再试`,
+        ))
+      }
+    }
+    // D8: no-readback / ungated 臂 → 容差置 MAX,回读差异不致败(假成功语义,供 I2 消融)
+    const benchNoReadback = benchModeEnabled() && (meta?.benchArm === 'no-readback' || meta?.benchArm === 'ungated')
+    const benchToleranceOverride = benchNoReadback ? Number.MAX_VALUE : undefined
+    const prevValue = typeof node.value === 'number' ? node.value : null
+    const outcome = await rt.write(eng, recipeRunId, benchToleranceOverride)
+    // 调控闭环入册:仅成功写记锚/开记录(失败写不动账本 —— PLC 值未变更);
+    // 窗口聚合异步回填(F2)
+    if (outcome.ok !== false) {
+      // 写成功 → 锁定写入保持窗(agent/manual 路径;recipe/rollback 豁免)
+      if (lockable) {
+        this.writeLocks.set(id, Date.now() + lockMs)
+        setWriteLockUntil(id, Date.now() + lockMs) // P1-5 落盘:重启窗口延续
+      }
+      try {
+        const rbInfo = getRecipeRollBackManager().afterWrite(
+          node,
+          eng,
+          prevValue,
+          meta ?? { source: recipeRunId ? 'recipe' : 'manual', actor: 'user' },
+          recipeRunId,
+        )
+        if (rbInfo) {
+          outcome.recordId = rbInfo.recordId
+          outcome.anchorId = rbInfo.anchorId
+        }
+      }
+      catch (err) {
+        console.error('[dcw] 调控闭环入册失败(不影响写结果):', err)
+      }
+      // 运维日志 + 插件钩子:所有下发路径(manual/recipe/agent/rollback)单点入册(write-audit)
+      try {
+        recordDcwWriteOps({ id, node, eng, prevValue, outcome, src: srcForLock as DcwWriteMeta['source'], meta, recipeRunId })
+      }
+      catch {
+        // 日志失败不影响写结果
+      }
+    }
+    return outcome
+  }
+
+  /** 连接测试(显式声明的驱动 kind 必须可解析;未知协议显式报错,不静默 mock —— P0-5) */
+  async testDriver(kind: DcwDriverKind, driverConfig: Record<string, unknown>) {
+    return resolveDcwDriver(requireDcwDriverKind(kind)).test(driverConfig)
+  }
+
+  async testNode(id: string) {
+    const node = this.repo.byId(id)
+    if (!node) throw new AppError(404, ErrorCodes.NOT_FOUND, `控制节点不存在: ${id}`)
+    return this.testDriver(node.driver, node.driverConfig)
+  }
+
+  // ---------- 工艺参数映射面(用户/Agent 的唯一语义读写面)----------
+}

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

@@ -82,7 +82,10 @@ export class DcwNode {
   /** 单次控制步长上限(工程量);探索阶段必须有有限值 */
   stepLimit: number | null
   lastAckAt: string | null = null
+  /** 最近一次**成功**下发(设备已证实/受理)的时刻;失败写不更新 */
   lastWriteAt: string | null = null
+  /** 最近一次写**尝试**的时刻(含失败);仅用于诊断/失败冷却,不参与 60s 成功间隔 */
+  lastAttemptAt: string | null = null
   state: DcwNodeState = 'idle'
   /** 所属产线('' = 未分配;采集门控/写联锁/场景光晕按产线隔离) */
   lineId = ''
@@ -137,8 +140,12 @@ export class DcwNode {
    *  此前失败写把从未被 PLC 接受的指令值占进 value —— 保写心跳按 value 周期重下发,
    *  会把幻影指令值反复写向设备(10-07 事故放大器);同时污染步长基准与回退账本 prevValue。 */
   applyWriteResult(eng: number, ok: boolean, message: string, at: string): void {
-    this.lastWriteAt = at
+    // 尝试时间恒更新;成功时间只在设备证实/受理时更新 ——
+    // 失败写不再占用 60s 成功间隔(现场瞬断恢复后可立即重试),失败冷却另由
+    // write.ts 用 lastAttemptAt 做 5s 防轰炸。
+    this.lastAttemptAt = at
     if (ok) {
+      this.lastWriteAt = at
       this.value = Number(eng.toFixed(this.decimals))
       this.lastAckAt = at
       this.state = 'ok'
@@ -191,6 +198,7 @@ export class DcwNode {
       lastReadError: this.lastReadError,
       lastAckAt: this.lastAckAt,
       lastWriteAt: this.lastWriteAt,
+      lastAttemptAt: this.lastAttemptAt,
       state: this.state,
       lastError: this.lastError,
       createdAt: this.createdAt,
@@ -228,6 +236,9 @@ export class DcwNode {
     if (row.lastReadError != null) node.lastReadError = String(row.lastReadError)
     if (row.lastAckAt != null) node.lastAckAt = String(row.lastAckAt)
     if (row.lastWriteAt != null) node.lastWriteAt = String(row.lastWriteAt)
+    if (row.lastAttemptAt != null) node.lastAttemptAt = String(row.lastAttemptAt)
+    // 旧快照兼容:历史 lastWriteAt 是「尝试时间」语义,补一份到 lastAttemptAt
+    else if (row.lastWriteAt != null) node.lastAttemptAt = String(row.lastWriteAt)
     if (row.state != null) {
       const restored = String(row.state)
       // 持久化恢复消毒:'writing' 是进程内瞬态(写事务在飞)。若被快照带出后进程
@@ -275,6 +286,7 @@ export class DcwNode {
       stepLimit: this.stepLimit,
       lastAckAt: this.lastAckAt,
       lastWriteAt: this.lastWriteAt,
+      lastAttemptAt: this.lastAttemptAt,
       state: this.state,
       lastError: this.lastError,
       createdAt: this.createdAt,

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

@@ -80,7 +80,8 @@ export class DcwNodeRuntime {
     }
     this.writing = true
     node.state = 'writing'
-    node.lastWriteAt = new Date().toISOString()
+    // 只记「尝试」;成功时间由 applyWriteResult 在设备证实后写入
+    node.lastAttemptAt = new Date().toISOString()
     try {
       // D8 基准消融:no-readback/ungated 臂由 write() 传入 MAX 容差 → 回读差异不再致败(假成功语义)
       return await this.host.executeWrite(node, eng, toleranceOverride ?? writeTolerance(node), recipeRunId)

package/server/services/workshop/dcw/drivers/mqtt.ts

@@ -6,6 +6,7 @@ import type { DcwWriteDriver } from './shared'
 import { AppError } from '../../../../utils/errors'
 import { reqNative } from './shared'
 import { mqttConnectOpts, readMqttValue, invalidateMqttTopic } from '../../daq/drivers/mqtt'
+import { renderMqttWritePayload } from '../mqtt-payload'
 
 // ============================================================
 // MQTT 写驱动(publish 设定值到 Broker;fire-and-forget,无回读)
@@ -33,9 +34,9 @@ export const mqttDcwDriver: DcwWriteDriver = {
       const mqtt = reqNative('mqtt') as typeof import('mqtt')
       const secure = Boolean(cfg.secure ?? cfg.tls)
       const url = `mqtt${secure ? 's' : ''}://${String(cfg.host)}:${Number(cfg.port ?? 1883)}`
-      const payload = cfg.jsonKey
-        ? JSON.stringify({ [String(cfg.jsonKey)]: input.eng })
-        : String(input.eng)
+      // 载荷三档:jsonTemplate(嵌套/多字段,{{value}} 插值)> jsonKey(单键)> 裸数值。
+      // 模板先渲染再 JSON.parse 规范化:坏模板在发布前就 400,绝不把畸形报文发给设备。
+      const payload = renderMqttWritePayload(cfg, input.eng)
       // 控制发布用一次性连接(低频关键动作,不复用采样的长连接;发布即断,资源可控)。
       // TLS 语义经采侧 mqttConnectOpts 同源;一次性连接绝不能让 mqtt.js 默认重连后台空转。
       const client = await new Promise<import('mqtt').MqttClient>((resolve, reject) => {

package/server/services/workshop/dcw/mqtt-payload.ts

@@ -0,0 +1,64 @@
+/**
+ * MQTT 写载荷渲染(纯函数,零 IO)—— jsonTemplate / jsonKey / 裸数值 三档。
+ *
+ * jsonTemplate:支持 `{{value}}` 插值(可多处、可嵌套、可带静态字段),例如
+ *   {"cmd":"set","params":{"temp":{{value}},"hold":8}}
+ * 渲染后必须是**合法 JSON**(解析一次再序列化,等价于规范化),避免把坏报文发给设备。
+ *
+ * 安全边界:
+ *  - 不做任何表达式/函数求值,只有字面替换;
+ *  - 下发值必须是有限数字(NaN/Infinity 拒绝);
+ *  - 模板长度 ≤ 4096 字符,渲染结果 ≤ 64KB;
+ *  - jsonTemplate 与 jsonKey 互斥(避免"看起来都配了、实际只生效一个")。
+ */
+import { AppError, ErrorCodes } from '../../../utils/errors'
+
+export const MQTT_TEMPLATE_MAX_CHARS = 4096
+export const MQTT_PAYLOAD_MAX_CHARS = 64 * 1024
+
+function bad(message: string): AppError {
+  return new AppError(400, ErrorCodes.VALIDATION_ERROR, message)
+}
+
+/**
+ * 渲染一条 MQTT 写载荷。
+ * @param cfg 节点 driverConfig(读取 jsonTemplate / jsonKey)
+ * @param value 工程量纲设定值(有限数字)
+ * @returns 待 publish 的字符串(JSON 模板会被规范化;裸数值为 String(value))
+ */
+export function renderMqttWritePayload(cfg: Record<string, unknown>, value: number): string {
+  const tplRaw = cfg.jsonTemplate
+  const keyRaw = cfg.jsonKey
+  const tpl = tplRaw == null ? '' : String(tplRaw).trim()
+  const key = keyRaw == null ? '' : String(keyRaw).trim()
+
+  if (tpl) {
+    if (key) throw bad('jsonTemplate 与 jsonKey 互斥:嵌套/多字段报文用 jsonTemplate,单键报文用 jsonKey')
+    if (!Number.isFinite(value)) throw bad('下发值必须是有限数字(NaN/Infinity 已拒绝)')
+    if (tpl.length > MQTT_TEMPLATE_MAX_CHARS) {
+      throw bad(`jsonTemplate 过长(${tpl.length} 字符,上限 ${MQTT_TEMPLATE_MAX_CHARS})`)
+    }
+    if (!tpl.includes('{{value}}')) throw bad('jsonTemplate 缺少 {{value}} 占位符(模板必须把下发值插入报文)')
+    const rendered = tpl.replaceAll('{{value}}', String(value))
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(rendered)
+    }
+    catch (err) {
+      throw bad(`jsonTemplate 渲染后不是合法 JSON:${err instanceof Error ? err.message : String(err)}(渲染结果:${rendered.slice(0, 200)})`)
+    }
+    const out = JSON.stringify(parsed)
+    if (out.length > MQTT_PAYLOAD_MAX_CHARS) {
+      throw bad(`jsonTemplate 渲染结果过大(${out.length} 字节,上限 ${MQTT_PAYLOAD_MAX_CHARS})`)
+    }
+    return out
+  }
+
+  if (key) return JSON.stringify({ [key]: value })
+  return String(value)
+}
+
+/** 配置期校验(创建/PATCH 时调用):模板可渲染、JSON 合法、占位符存在、与 jsonKey 不冲突。 */
+export function validateMqttWriteConfig(driverConfig: Record<string, unknown>): void {
+  renderMqttWritePayload(driverConfig, 0)
+}

package/server/services/workshop/dcw/recipe-rollback-manager/lock.ts

@@ -73,6 +73,7 @@ export abstract class RecipeRollBackManagerLock extends RecipeRollBackManagerSta
         newValue: eng,
         source: meta.source,
         actor: meta.actor,
+        approvalId: meta.approvalId,
         recipeRunId,
         taskId: meta.taskId,
       })