agentworkshop 0.7.49 → 0.7.51

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

@@ -0,0 +1,148 @@
+/**
+ * 工艺优化 Channel 专属工具(2026-09-26 解耦计划)。
+ *
+ * toolOptimizationExplore —— 探索模式核心:goal 驱动的真实激励步。
+ * 一次调用 = ①读 goal 与当前工况 → ②生成激励值(按方向与步长,clamp 到调试范围)
+ * → ③经 dcw_control 全治理链真实写入(绑定鉴权/HITL/写限界/调控闭环,与本平台任何
+ * agent 下发同源,不新造权限) → ④等待工艺响应 → ⑤读回目标 DAQ 均值 →
+ * ⑥探索记录落库 optimization_explorations(写入值↔响应值配对,训练数据回流事实源)
+ * → 返回学习摘要(参数波动 ↔ 目标响应)。
+ * 多轮迭代与方向判断由 agent 编排(工况提示词提供节点物理意义与调试跨度)。
+ */
+import { createId } from '../../aml/twin/contracts'
+import { getAmlRuntime } from '../../aml/runtime'
+import { getChannelTwinProfile } from '../../aml/twin/channel-profile'
+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'
+
+const sleep = (ms: number) => new Promise(r => setTimeout(r, ms))
+
+async function readTargetMean(nodeId: string, windowMs = 45_000): Promise<number | null> {
+  const now = Date.now()
+  try {
+    const pts = await getDaqController().samples(nodeId, { fromMs: now - windowMs, toMs: now, bucketMs: 1000, limit: 60 }) as Array<{ at?: number, value?: number, avg?: number }>
+    const vals = pts.map(p => Number(p.value ?? p.avg)).filter(Number.isFinite)
+    if (vals.length === 0) return null
+    return vals.reduce((a, b) => a + b, 0) / vals.length
+  }
+  catch {
+    return null
+  }
+}
+
+export async function toolOptimizationExplore(agentId: string, args: {
+  control_node_id?: string
+  target_node_id?: string
+  direction?: 'up' | 'down'
+  step?: number | string
+  settle_seconds?: number | string
+  hypothesis?: string
+}, channelId?: string): Promise<HostToolResult> {
+  try {
+    const profile = getChannelTwinProfile(channelId ?? '')
+    if (profile.profile !== 'aml_optimization') return { text: 'optimization_explore 仅适用于工艺优化 Channel。', isError: true }
+    const goal = (args as { objective?: Record<string, unknown> }).objective ?? profile.objective ?? {}
+    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 binding = repo.find(agentId, controlNodeId, 'dcw')
+    const node = getDcwController().byId(controlNodeId)
+    if (!binding || !node) return { text: `控制节点 ${controlNodeId} 无效(未绑定或不存在)。`, 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 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 direction = args.direction === 'down' ? -1 : 1
+    const proposed = Number(node.value ?? 0) + direction * step
+    const target = Math.min(tuneMax, Math.max(tuneMin, proposed))
+    const clamped = Math.abs(target - proposed) > 1e-9
+
+    const daqBindings = repo.byAgent(agentId).filter(b => b.kind === 'daq')
+    const targetNodeId = String(args.target_node_id ?? '').trim() || daqBindings[0]?.nodeId || ''
+    if (!targetNodeId) return { text: '未指定目标观测节点且当前无数采绑定;请传 target_node_id 或先绑定数采节点。', isError: true }
+
+    const targetBefore = await readTargetMean(targetNodeId)
+
+    // 真实写入:复用 dcw_control 全治理链(手动绑定会挂 HITL,auto+bounded 走限界直写)
+    const settleSec = Math.min(300, Math.max(10, Number(args.settle_seconds ?? 45)))
+    const write = await toolDcwControl(agentId, {
+      node_id: controlNodeId,
+      value: target,
+      hypothesis: args.hypothesis ?? `探索激励(${direction > 0 ? 'up' : 'down'} ${Number(step).toFixed(3)};goal=${goalText.slice(0, 120)})`,
+    }, channelId)
+    const writeOk = !write.isError
+
+    let targetAfter: number | null = null
+    if (writeOk) {
+      await sleep(settleSec * 1000)
+      targetAfter = await readTargetMean(targetNodeId)
+    }
+
+    const record = {
+      id: createId('opt-exploration'),
+      channelId: channelId ?? '',
+      agentId,
+      goalJson: JSON.stringify(goal),
+      controlNodeId,
+      controlBefore: Number(node.value ?? 0),
+      controlAfter: writeOk ? target : Number(node.value ?? 0),
+      controlStep: step,
+      targetNodeId,
+      targetBefore,
+      targetAfter,
+      direction: direction > 0 ? 'up' : 'down',
+      hypothesis: String(args.hypothesis ?? ''),
+      writeStatus: writeOk ? 'ok' : 'rejected',
+      writeMessage: write.text.slice(0, 400),
+    }
+    try {
+      const rt = getAmlRuntime()
+      rt.db.prepare(`INSERT INTO optimization_explorations(id,channel_id,agent_id,goal_json,control_node_id,control_before,control_after,control_step,target_node_id,target_before,target_after,direction,hypothesis,write_status,write_message,created_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
+        .run(record.id, record.channelId, record.agentId, record.goalJson, record.controlNodeId, record.controlBefore, record.controlAfter, record.controlStep, record.targetNodeId, record.targetBefore, record.targetAfter, record.direction, record.hypothesis, record.writeStatus, record.writeMessage, new Date().toISOString())
+    }
+    catch (err) {
+      return { text: `探索步已执行但记录落库失败:${err instanceof Error ? err.message : String(err)}\n\n${write.text}`, isError: writeOk ? undefined : true }
+    }
+
+    if (!writeOk) {
+      return { text: `探索步被拒绝(未写入产线,已记录 rejected):\n${write.text}`, isError: true }
+    }
+    const deltaTarget = targetAfter != null && targetBefore != null ? targetAfter - targetBefore : null
+    const lines = [
+      `探索步完成(已真实写入产线并记录):`,
+      `  记录: ${record.id}`,
+      `  控制: ${node.name}(${controlNodeId}) ${record.controlBefore} → ${record.controlAfter}(步长 ${Number(step).toFixed(3)},方向 ${record.direction}${clamped ? ',触调试边界截断' : ''})`,
+      `  响应: ${targetNodeId} ${targetBefore != null ? targetBefore.toFixed(3) : 'n/a'} → ${targetAfter != null ? targetAfter.toFixed(3) : 'n/a'}(Δ=${deltaTarget != null ? deltaTarget.toFixed(3) : 'n/a'},窗口 ${settleSec}s)`,
+      `  goal: ${goalText}`,
+      deltaTarget != null
+        ? `  学习: 该方向目标响应 ${deltaTarget > 0 ? '上升' : '下降'} ${Math.abs(deltaTarget).toFixed(3)};继续探索请按此符号外推,或反向验证。`
+        : '  学习: 响应窗口内未读到稳定差分;建议增大 settle_seconds 或检查目标节点采样。',
+      `探索记录已归档,可在 AML 界面与训练数据回流中使用。`,
+    ]
+    return { text: lines.join('\n') }
+  }
+  catch (err) {
+    return { text: `探索步失败:${err instanceof Error ? err.message : String(err)}`, isError: true }
+  }
+}
+
+/** 探索记录查询(供 agent 复盘与提示词组装;按 Channel 最近优先) */
+export function optimizationExplorationsOf(channelId: string, limit = 50): Array<Record<string, unknown>> {
+  try {
+    return getAmlRuntime().db.prepare('SELECT * FROM optimization_explorations WHERE channel_id = ? ORDER BY created_at DESC LIMIT ?').all(channelId, limit) as Array<Record<string, unknown>>
+  }
+  catch {
+    return []
+  }
+}

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

@@ -1,172 +1,169 @@
-/**
- * 工艺参数读写(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 }
-  }
-}
+/**
+ * 工艺参数读写(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 }
+  }
+}