agentworkshop 0.7.39 → 0.7.41

package/docs/plugins.md

@@ -6,7 +6,7 @@
 > 本文是唯一权威参考;`docs/site/plugins/` 的分页文档与本文同源。
 >
 > 适用版本:插件系统 v2 自 **v0.7.29** 起可用(前端组件注入 / 插件设置 / 插件 i18n /
-> 运行时服务面);本文档对应当前版本 **v0.7.38**。`ctx.sdkVersion` 当前为 `0.3.0`。
+> 运行时服务面);本文档对应当前版本 **v0.7.41**。`ctx.sdkVersion` 当前为 `0.3.0`。
 
 ## 一、目录结构与快速开始
 
@@ -207,10 +207,37 @@ async setup(ctx) {
 | 事件 | `ctx.events.on(type, fn)` / `ctx.events.off(type, fn)` | scene 实时事件糖:内部订阅 `event:<type>`(见 §7) |
 | 路径 | `ctx.paths.home / configRoot / dataDir`;`ctx.dataDir` | `ctx.dataDir` 即本插件 KV 目录 `<配置根>/data/plugins/<插件名>` |
 | 数采 | `ctx.daq.registerDriver / registerProcessor / registerTemplate / onFrame / onSample / query / nodes` | 驱动、下沉处理器、节点模板注册 + 时序查询 + 节点元数据快照 |
+| 写控 | `ctx.dcw.registerWriteDriver(driver)` | 写驱动注入(与数采读驱动对称):契约 `{ kind, available(), write(input), test(cfg), read?(input), meta? }`;热重载停用即失效 |
 | 工具 | `ctx.omp.registerTool({ name, label?, description, parameters, roles?, handler })` | Agent 工具注入;`roles` 仅 `'lead'` 与 `'worker'`(见 §10) |
 | 服务 | `ctx.services.names()` / `.get(name)` / `.provide(name, getter)` | 运行时对象面:`get('daq' \| 'lines' \| 'channels' \| 'plugins')`;`provide` 自动加 `<插件名>.` 前缀 |
 | 权限 | `ctx.permissions.lineMode / visibleLineIds / listGrants / setGrants` | 产线授权查询与管理 |
 
+### 通信协议插件(自定义接口连接方式)
+
+`ctx.daq.registerDriver` / `ctx.dcw.registerWriteDriver` 是**协议接入点**:串口、其他 PLC 协议、
+私有总线的连接实现都从这里注入,主链路(采样循环 / 写控网关 / 前端表单)零改动。
+
+```js
+ctx.daq.registerDriver({
+  kind: 'serial',                    // 自定义协议 kind(与内置冲突时插件覆盖并告警)
+  async available() { return true }, // 协议栈包探测(缺失时 UI 显示「未安装」)
+  async sample({ driverConfig }) { return 25.3 },   // 读数(标量或 v2 帧信封)
+  async test(driverConfig) { return { ok: true, message: '连接成功', sampleValue: 25.3 } },
+  meta: {                            // 自描述(前端「添加节点」下拉 + 动态参数表单)
+    label: '串口 Serial(RS-232/485)',
+    status: 'real',
+    configFields: [{ key: 'path', label: '串口路径', type: 'string', required: true, placeholder: 'COM3' }],
+  },
+})
+```
+
+要点:
+- 驱动目录经 `GET /api/workshop/daq`(读)与 `GET /api/workshop/dcw`(写)的 `drivers` 字段下发,
+  前端数采/写控页据此渲染插件协议与参数表单(带 ⌁ 徽标);不带 `meta` 的驱动只出现在可用性里;
+- 热重载先清空全部插件驱动再重装载:**停用/卸载的协议驱动立即失效**,不会残留到重启;
+- 内置示例:`server/plugins-builtin/serial-bridge`(串口 Modbus RTU + ASCII 行协议,含读/写驱动、
+  `health`/`ports`/`probe` API、前端面板与 `serial_ports` Agent 工具)——新协议插件建议以它为模板。
+
 ### KV 落在哪里
 
 `<configRoot>/data/plugins/<插件名>/kv.json` —— **不在插件目录里**。写入以内存为准,200ms 防抖后 `tmp + rename` 原子落盘;关机与热重载时取消挂起的防抖并同步落盘。`ctx.kv` 只有 `get / set / all / bump` 四个方法。
@@ -521,6 +548,7 @@ export default {
 - **浏览器新启用插件注入延迟 ≤15s**(WS 可用时即时)。
 - **`server:close` / `onDispose` 依赖优雅关闭信号**,Windows 强杀进程不触发。
 - **`aw plugin list` 只做目录扫描**,不反映装载失败与运行态健康。
+- **协议插件的原生栈与宿主同进程**:serial-bridge 的 RTU 帧机为自研实现(单 serialport 原生栈;弃用 modbus-serial —— 其包装层在 dev 模式实测触发 V8 原生崩溃)。已知边界:**`aw dev` 进程内,串口事务「写→超时→关闭」序列可能触发 bindings-cpp 的 V8 原生崩溃**(HandleScope fatal,JS 层不可捕获,与具体串口无关);**生产模式(`aw start`)不受影响 —— 已实测同一序列在生产下诚实返回超时且服务存活**,纯打开(ASCII 探针)在 dev 下同样正常。开发期连接真实硬件请知悉此风险;对稳定性要求极高的部署可把串口网关放进独立进程(参考 plc-node-simulator 的子进程模式)。
 
 ## 十三、发布前验证清单
 

package/docs/sdk.en.md

@@ -7,7 +7,7 @@
 
 **SDK version constants**: server-side `SDK_VERSION = '0.3.0'`, browser-side `CLIENT_SDK_VERSION = '0.3.0'`.
 These two constants are the **interface version of the SDK itself** and evolve **independently**
-from the npm package version (the `version` field in `package.json`, currently 0.7.38) —
+from the npm package version (the `version` field in `package.json`, currently 0.7.41) —
 them being out of sync is expected. Never use `SDK_VERSION` to infer the package version, or the reverse.
 **Module format**: ESM only (only `import` / `export`; there is no CJS entry).
 **Types**: `sdk/index.d.mts` and `sdk/client.d.mts` ship with the package, so TypeScript projects

package/docs/sdk.md

@@ -5,7 +5,7 @@
 > 零第三方运行时依赖,Node ≥ 23.4 与现代浏览器双端可用。
 
 **SDK 版本常量**:服务端 `SDK_VERSION = '0.3.0'`,浏览器端 `CLIENT_SDK_VERSION = '0.3.0'`。
-这两个常量是 **SDK 自身接口的版本号**,与 npm 包版本(`package.json` 的 `version`,当前 0.7.38)
+这两个常量是 **SDK 自身接口的版本号**,与 npm 包版本(`package.json` 的 `version`,当前 0.7.41)
 **各自独立演进** —— 常数不同步是预期行为,不要拿 `SDK_VERSION` 去推断包版本,反之亦然。
 **模块形态**:ESM only(只有 `import` / `export`,没有 CJS 入口)。
 **类型**:`sdk/index.d.mts`、`sdk/client.d.mts` 随包发布,TS 项目零配置获得提示(覆盖范围见 §7)。

package/i18n/locales/en.ts

@@ -36,6 +36,8 @@ export default {
   header: {
     collapse: 'Collapse menu',
     expand: 'Expand menu',
+    openNav: 'Open navigation',
+    closeNav: 'Close navigation',
     language: 'Language',
     theme: 'Theme',
     fullscreen: 'Fullscreen',

package/i18n/locales/zh-CN.ts

@@ -36,6 +36,8 @@ export default {
   header: {
     collapse: '折叠菜单',
     expand: '展开菜单',
+    openNav: '打开导航',
+    closeNav: '关闭导航',
     language: '语言',
     theme: '主题',
     fullscreen: '全屏',

package/nuxt.config.ts

@@ -221,6 +221,37 @@ export default defineNuxtConfig({
     },
   },
 
+  vite: {
+    build: {
+      /**
+       * rolldown 的构建期检查开关。
+       *
+       * pluginTimings 会在"插件钩子占了构建时间大头"时打一条 WARN。本项目装了
+       * unocss / antd / i18n / unplugin-icons 等一堆构建期插件,这条 WARN 每次必现 ——
+       * 它是**构建自身的耗时画像**,不是代码质量问题,也无法通过改我们的代码消除
+       * (unocss 的 renderChunk 调用 93 次、占 ~19%,这是它的工作方式)。
+       *
+       * 只关这一项。其余 checks(命名空间当函数调用、配置冲突、无用的内置特性替代等)
+       * 都是**真的可能在抓 bug** 的检查,保持开启。
+       */
+      rolldownOptions: {
+        checks: { pluginTimings: false },
+      },
+      /**
+       * 客户端单块体积阈值。
+       *
+       * 默认的 500kB 对本项目不适用:three.js(数字孪生,~1.35MB)与
+       * echarts(~650kB)是重型第三方库的固有体积,而且都已经是**路由级动态导入**
+       * ——/town 才加载 three,只有真正进入孪生页的用户才付这份下载。
+       * 继续拆分的收益很小(它们本身就是单个不可再分的库)。
+       *
+       * 阈值提到 1500kB 的用意不是"把告警关掉",而是让这条告警重新变得**有意义**:
+       * 一旦某天我们自己的代码或某个新依赖把这个数字推过 1.5MB,它照样会报。
+       */
+      chunkSizeWarningLimit: 1500,
+    },
+  },
+
   typescript: {
     strict: true,
     typeCheck: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentworkshop",
-  "version": "0.7.39",
+  "version": "0.7.41",
   "type": "module",
   "description": "AgentWorkShop 软件开发系统 - 基于 Nuxt 4 的配置驱动运行范式",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -80,6 +80,13 @@
     "prepare": "husky",
     "game:test": "tsx scripts/test-agent-brain.ts && tsx scripts/test-game-session.ts",
     "test:api-live": "node scripts/api-live-e2e.mjs",
+    "ui:seed": "node scripts/ui/seed-demo.mjs",
+    "ui:shots": "node scripts/ui/shots.mjs",
+    "ui:audit": "node scripts/ui/audit-layout.mjs",
+    "ui:verify": "node scripts/ui/verify-responsive.mjs",
+    "ui:verify-nav": "node scripts/ui/verify-nav.mjs",
+    "readme:lint": "node scripts/ui/md-lint.mjs README.md README-zh.md",
+    "readme:assets": "node scripts/ui/readme-assets.mjs",
     "game:verify": "node scripts/verify-game.mjs",
     "game:build-assets": "node scripts/build-player-sheet.mjs",
     "game:build-wuwa": "node scripts/build-wuwa-assets.mjs",
@@ -138,7 +145,8 @@
     "zod": "^3.24.1"
   },
   "optionalDependencies": {
-    "onnxruntime-node": "^1.20.1"
+    "onnxruntime-node": "^1.20.1",
+    "serialport": "^13.0.0"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.6.1",
@@ -146,6 +154,7 @@
     "@nuxt/eslint": "^1.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^26.2.0",
+    "@types/pg": "^8.23.1",
     "@types/three": "^0.185.4",
     "eslint": "^9.17.0",
     "husky": "^9.1.7",

package/scripts/_dbg-param-map-e2e.ts

@@ -0,0 +1,242 @@
+/**
+ * 工艺参数映射层 E2E(真实 PLC 模拟器连通):
+ * ①节点创建自动生成工艺参数映射 + 参数面不透出 PLC 寻址细节
+ * ②真实 Modbus TCP 从站(dev-plc-simulator,一阶惯性温度回路)参数写→回读 roundtrip
+ * ③参数基准限界联锁(常驻层) ④产品限界 + 配方窗口分层联锁(产线运行期)
+ * ⑤配方下发同样受限(run.results 记失败) ⑥Agent param_control/param_read(绑定/越权/消歧)
+ * ⑦节点删除级联清理映射 ⑧运行中 plc-node-simulator(16040)导出配置连通性交叉验证
+ * 数据目录 AW_HOME 隔离,不触碰检出内 .AgentWorkShop。
+ * 运行: npx tsx --tsconfig .nuxt/tsconfig.server.json scripts/_dbg-param-map-e2e.ts
+ */
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+// @ts-expect-error 既有验证脚本助手(无类型声明)
+import { startPlcSim } from './_lib-plc-sim-child.mjs'
+
+// 进程级隔离:配置根落在一次性目录(须在业务模块 import 前设置)
+const awHome = mkdtempSync(join(tmpdir(), 'aw-param-map-e2e-'))
+process.env.AW_MODE = 'home'
+process.env.AW_HOME = awHome
+process.env.NO_PROXY = '127.0.0.1,localhost'
+
+let failures = 0
+const check = (name: string, ok: boolean, detail = ''): void => {
+  console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok) failures += 1
+}
+
+// ===== 真实 Modbus 从站(scripts/dev-plc-simulator.mjs:40021 温度SP / 40001 温度PV,float32 大端) =====
+const SIM_PORT = 15040
+const sim = startPlcSim(SIM_PORT)
+const simReady: Promise<boolean> = sim.ready
+
+// ===== 服务层导入(隔离根内) =====
+const { getDcwController } = await import('../server/services/workshop/dcw/dcw-controller')
+const { getDcwParamRepo } = await import('../server/services/workshop/dcw/param-map.repo')
+const { getDcwLineRepo } = await import('../server/services/workshop/dcw/dcw-line.repo')
+const { getDcwProductRepo } = await import('../server/services/workshop/dcw/dcw-product.repo')
+const { getDcwRecipeRepo } = await import('../server/services/workshop/dcw/dcw-recipe.repo')
+const { getAgentNodeBindingRepo } = await import('../server/services/workshop/agents/node-bindings.repo')
+const { toolParamControl, toolParamRead } = await import('../server/services/workshop/agents/industrial-tools')
+
+const ctrl = getDcwController()
+const paramRepo = getDcwParamRepo()
+
+/** 捕获 AppError 的消息与状态码 */
+async function errOf(fn: () => Promise<unknown> | unknown): Promise<{ status: number, message: string }> {
+  try {
+    await fn()
+    return { status: 0, message: '(未抛错)' }
+  }
+  catch (err) {
+    const e = err as { status?: number, statusCode?: number, message?: string }
+    return { status: e.status ?? e.statusCode ?? 500, message: e.message ?? String(err) }
+  }
+}
+
+try {
+  console.log('\n--- ① 节点创建 → 自动工艺参数映射(参数面语义) ---')
+  if (!await simReady) throw new Error(`Modbus 模拟器未就绪(${SIM_PORT},可能端口被占)`)
+  console.log(`  模拟器就绪 @ 127.0.0.1:${SIM_PORT}`)
+  const line = getDcwLineRepo().create({ name: '参数映射验证线' })
+  const node = ctrl.create({
+    templateRef: 'dcw-temp-sp',
+    name: 'PP验证·烘箱温度',
+    driver: 'modbus-tcp',
+    driverConfig: { host: '127.0.0.1', port: SIM_PORT, unitId: 1, register: 40021, dataType: 'float32', byteOrder: 'big' },
+    min: 0,
+    max: 300,
+    readIntervalMs: 0,
+    lineId: line.id,
+  })
+  const prow = paramRepo.byNode(node.id)
+  check('节点创建自动生成工艺参数映射', !!prow && prow.key === 'temp-sp')
+  const pview0 = paramRepo.listViews().find(p => p.nodeId === node.id)
+  check('参数视图为语义面(无 driverConfig/寄存器/数据类型/字节序)', !!pview0
+    && !('driverConfig' in (pview0 ?? {}))
+    && !JSON.stringify(pview0).includes('register')
+    && !JSON.stringify(pview0).includes('float32')
+    && !JSON.stringify(pview0).includes('byteOrder'),
+  JSON.stringify(pview0).slice(0, 120))
+  check('参数视图携带驱动类别(仅类别)与产线归属', pview0?.driver === 'modbus-tcp' && pview0?.lineId === line.id)
+  const pid = pview0!.id
+
+  console.log('\n--- ② 真实 Modbus 参数写→回读 roundtrip(工程量纲直写) ---')
+  const w1 = await ctrl.writeParam(pid, 180, { source: 'manual', actor: 'e2e', actorName: 'E2E' })
+  check('参数写入成功(180℃)', w1.ok, w1.message)
+  check('PLC 同址回读一致(标定后物理值)', w1.readback != null && Math.abs((w1.readback ?? 0) - 180) < 0.5, `readback=${w1.readback}`)
+  check('执行节点设定值回填', ctrl.byId(node.id)?.value != null && Math.abs((ctrl.byId(node.id)!.value ?? 0) - 180) < 0.5)
+  await ctrl.readParam(pid).then((r) => {
+    check('参数读取成功(PLC 当前值)', r.ok && Math.abs((r.value ?? 0) - 180) < 0.5, `value=${r.value}`)
+  })
+
+  console.log('\n--- ③ 工艺参数基准限界(常驻层) ---')
+  paramRepo.update(pid, { min: 100, max: 250 })
+  const eHi = await errOf(() => ctrl.writeParam(pid, 260))
+  check('超出基准限界 260 → 拒绝且点名参数层', eHi.status === 400 && eHi.message.includes('基准限界'), eHi.message.slice(0, 90))
+  const eLo = await errOf(() => ctrl.writeParam(pid, 90))
+  check('低于基准限界 90 → 拒绝', eLo.status === 400 && eLo.message.includes('基准限界'))
+  const w2 = await ctrl.writeParam(pid, 200)
+  check('限界内 200 → 通过', w2.ok)
+  const eNode = await errOf(() => ctrl.write(node.id, 260))
+  check('节点面直写越参数限界 → 同样拒绝(同一咽喉点)', eNode.status === 400 && eNode.message.includes('基准限界'))
+
+  console.log('\n--- ④ 产品限界 + 配方窗口(产线运行期分层联锁) ---')
+  const eBadKey = await errOf(() => ctrl.createProduct({ name: 'PP验证产品·坏键', lineId: line.id, paramLimits: { 'no-such-param': { min: 1, max: 2 } } }))
+  check('产品限界引用不存在的参数键 → 400(防静默失效)', eBadKey.status === 400 && eBadKey.message.includes('no-such-param'))
+  const eBadRange = await errOf(() => ctrl.createProduct({ name: 'PP验证产品·坏区间', lineId: line.id, paramLimits: { 'temp-sp': { min: 200, max: 150 } } }))
+  check('产品限界 min>max → 400', eBadRange.status === 400)
+  const product = ctrl.createProduct({
+    name: 'PP验证产品',
+    lineId: line.id,
+    paramLimits: { 'temp-sp': { min: 150, max: 210 } },
+  })
+  check('产品限界设定成功(150~210)', (product.paramLimits?.['temp-sp']?.max ?? 0) === 210)
+  const recipe = ctrl.createRecipe({
+    productId: product.id,
+    name: 'PP验证配方',
+    params: [{ nodeId: node.id, value: 180, min: 160, max: 220 }],
+  })
+  const run = await ctrl.lineStart(line.id, recipe.id)
+  check('产线开跑(批次激活)', !!run.id)
+  const eProduct = await errOf(() => ctrl.writeParam(pid, 215))
+  check('215 在参数限界内但超产品上限 210 → 拒绝且点名产品层', eProduct.status === 400 && eProduct.message.includes('产品'), eProduct.message.slice(0, 90))
+  const eRecipe = await errOf(() => ctrl.writeParam(pid, 155))
+  check('155 在产品限界内但低于配方下限 160 → 拒绝且点名配方层', eRecipe.status === 400 && eRecipe.message.includes('配方'), eRecipe.message.slice(0, 90))
+  const w3 = await ctrl.writeParam(pid, 170)
+  check('170 四层交集内 → 通过', w3.ok)
+  const eNodeGate = await errOf(() => ctrl.write(node.id, 215))
+  check('节点面直写 215 → 产品层同样拦截', eNodeGate.status === 400 && eNodeGate.message.includes('产品'))
+
+  console.log('\n--- ⑤ 配方下发同样受限(run.results 记失败;产线保持运行) ---')
+  ctrl.updateRecipe(recipe.id, { params: [{ nodeId: node.id, value: 215, min: 160, max: 220 }] }, { by: 'user', actor: 'e2e', actorName: 'E2E', description: '压到产品上限外验证下发拦截' })
+  const run2 = await ctrl.applyRecipe(recipe.id)
+  const r2 = run2.results[0] as { ok: boolean, message: string }
+  check('配方参数 215 超产品上限 210 → 下发失败入档(不阻塞批次)', r2.ok === false && r2.message.includes('产品'), r2.message.slice(0, 90))
+  ctrl.updateRecipe(recipe.id, { params: [{ nodeId: node.id, value: 180, min: 160, max: 220 }] }, { by: 'user', actor: 'e2e', actorName: 'E2E', description: '回退验证值' })
+  const run3 = await ctrl.applyRecipe(recipe.id)
+  check('配方参数 180 限界内 → 下发成功', (run3.results[0] as { ok: boolean }).ok === true)
+  // 跨配方下发不误伤:配方乙自身窗口 [150,210] 值 155,低于活动批次配方甲窗口下限 160
+  // —— 配方下发路径跳过配方层(自身窗口保存时已校验),产品/参数层照常 → 应放行
+  const recipeB = ctrl.createRecipe({ productId: product.id, name: 'PP验证配方·乙', params: [{ nodeId: node.id, value: 155, min: 150, max: 210 }] })
+  const runB = await ctrl.applyRecipe(recipeB.id)
+  const rB = runB.results[0] as { ok: boolean, message: string }
+  check('运行中应用配方乙(155 在甲窗口外、乙窗口内)→ 不被旧批次窗口误伤', rB.ok === true, rB.message.slice(0, 90))
+
+  console.log('\n--- ⑥ Agent 参数面(param_control/param_read;批次运行中) ---')
+  const AGENT = 'agent-pp-verify'
+  getAgentNodeBindingRepo().bind(AGENT, node.id, 'dcw', 'auto')
+  const t1 = await toolParamControl(AGENT, { param: 'temp-sp', value: 175 })
+  check('param_control 按 key 下发成功(语义回包含参数名/有效区间)', !t1.isError && t1.text.includes('工艺参数') && t1.text.includes('有效写入区间'), t1.text.slice(0, 100))
+  const t2 = await toolParamControl(AGENT, { param: 'temp-sp', value: 215 })
+  check('param_control 超产品限界 → 拒绝(文案含产品层)', t2.isError === true && t2.text.includes('产品'), t2.text.slice(0, 100))
+  const t3 = await toolParamControl(AGENT, { param: pid, value: 168 })
+  check('param_control 按 pp-id 下发成功', !t3.isError)
+  const t4 = await toolParamRead(AGENT, { param: 'temp-sp' })
+  check('param_read 返回读数 + 限界区间', !t4.isError && t4.text.includes('PLC 读数'), t4.text.slice(0, 80))
+  const t5 = await toolParamControl('agent-nobody', { param: 'temp-sp', value: 170 })
+  check('未绑定 Agent → 拒绝', t5.isError === true)
+  // 跨产线:第二条线同模板节点,key 产线内唯一
+  const line2 = getDcwLineRepo().create({ name: '参数映射验证线·乙' })
+  const node2 = ctrl.create({ templateRef: 'dcw-speed-sp', name: 'PP验证乙·速度', driver: 'mock', driverConfig: { key: `pp-e2e-2-${Date.now()}` }, readIntervalMs: 0, lineId: line2.id })
+  check('第二产线节点自动映射(speed-sp)', paramRepo.byNode(node2.id)?.key === 'speed-sp')
+  const t6 = await toolParamControl(AGENT, { param: 'speed-sp', value: 300 })
+  check('未绑定节点的参数 → 拒绝(权限沿用节点绑定)', t6.isError === true, t6.text.slice(0, 80))
+
+  console.log('\n--- ⑦ 级联:节点删除 → 参数映射自动清理 ---')
+  ctrl.remove(node2.id)
+  check('执行节点删除后映射移除', paramRepo.byNode(node2.id) == null)
+
+  console.log('\n--- ⑧ 运行中 plc-node-simulator(16040)连通性交叉验证 ---')
+  try {
+    const res = await fetch('http://127.0.0.1:4010/api/nodes', { signal: AbortSignal.timeout(3000) }).then(r => r.json()) as { data?: Array<{ id: string, protocol: string }> }
+    const mbNode = (res.data ?? []).find(n => n.protocol === 'modbus-tcp')
+    if (mbNode) {
+      const exp = await fetch(`http://127.0.0.1:4010/api/nodes/${mbNode.id}/export`, { signal: AbortSignal.timeout(3000) }).then(r => r.json()) as { data?: { items?: Array<{ driver: string, driverConfig: Record<string, unknown> }> } }
+      const cfg = exp.data?.items?.[0]?.driverConfig
+      const test = await ctrl.testDriver('modbus-tcp', cfg as Record<string, unknown>)
+      check('五协议模拟器导出配置 → 网关连通测试通过', test.ok === true, JSON.stringify(cfg))
+    }
+    else {
+      check('五协议模拟器连通性交叉验证', false, '无 modbus-tcp 设备(模拟器未启动或无预设)')
+    }
+  }
+  catch (err) {
+    check('五协议模拟器连通性交叉验证', false, `模拟器不可达:${err instanceof Error ? err.message : String(err)}`)
+  }
+
+  console.log('\n--- ⑨ 标准转换模式:线级双向换算验证(原始寄存器字核对) ---')
+  const ModbusRTU = (await import('modbus-serial')).default
+  const raw = new ModbusRTU()
+  await raw.connectTCP('127.0.0.1', { port: SIM_PORT })
+  raw.setID(1)
+  // float32 直写模式:速度SP 40023(2 寄存器,大端)
+  const f32 = ctrl.createParamMapping({
+    key: 'oven_f32', templateRef: 'dcw-speed-sp', name: '转换验证·float32', lineId: line.id,
+    access: { host: '127.0.0.1', port: SIM_PORT, unitId: 1, register: 40023, conversion: { mode: 'float32' } },
+  })
+  check('access 一键建映射:自动建节点+参数面+float32 模式留存', !!f32.nodeId && f32.conversion?.mode === 'float32', `${f32.id} → ${f32.nodeId}`)
+  check('映射视图仍不透出 driverConfig', !JSON.stringify(f32).includes('driverConfig'))
+  await ctrl.writeParam(f32.id, 320)
+  const w32 = await raw.readHoldingRegisters(40023 - 40001, 2)
+  const buf32 = Buffer.alloc(4)
+  buf32.writeUInt16BE(w32.data[0]!, 0)
+  buf32.writeUInt16BE(w32.data[1]!, 2)
+  check('float32 直写:PLC 寄存器字 = float32BE(320)', Math.abs(buf32.readFloatBE(0) - 320) < 0.01, `words=[${w32.data}]`)
+  // int16 线性标定模式:eng 0~50 ↔ raw 0~500,寄存器 40025(1 寄存器)
+  const i16 = ctrl.createParamMapping({
+    key: 'oven_i16', templateRef: 'dcw-tension-sp', name: '转换验证·int16标定', lineId: line.id,
+    access: { host: '127.0.0.1', port: SIM_PORT, unitId: 1, register: 40025, conversion: { mode: 'int16-scaled', engMin: 0, engMax: 50, rawMin: 0, rawMax: 500 } },
+  })
+  await ctrl.writeParam(i16.id, 22)
+  const w16 = await raw.readHoldingRegisters(40025 - 40001, 1)
+  check('int16 线性标定写:eng 22 → 原始字 220(0.1 分辨率)', w16.data[0] === 220, `word=${w16.data[0]}`)
+  // 读方向:原始字 300 → 工程值 30.0(接收同样自动换算)
+  await raw.writeRegister(40025 - 40001, 300)
+  const rd16 = await ctrl.readParam(i16.id)
+  check('int16 线性标定读:原始字 300 → 工程值 30', rd16.ok && Math.abs((rd16.value ?? 0) - 30) < 0.01, `value=${rd16.value}`)
+  // 非法转换模式在配置期即拒
+  const eBadConv = await errOf(() => ctrl.createParamMapping({
+    key: 'bad-conv', templateRef: 'dcw-temp-sp', lineId: line.id,
+    access: { host: '127.0.0.1', register: 40021, conversion: { mode: 'int16-scaled' } as never },
+  }))
+  check('int16 标定缺量程 → 配置期 400 拒绝', eBadConv.status === 400, eBadConv.message.slice(0, 80))
+  raw.close()
+
+  console.log('\n--- 清理 ---')
+  // removeLine 自带活动批次窗口停止;lineStop 为同步抛错方法,勿在此直调
+  await ctrl.removeLine(line.id, { purge: true })
+  await ctrl.removeLine(line2.id, { purge: true })
+  check('产线 purge 后参数映射全部清理', paramRepo.listViews().filter(p => [line.id, line2.id].includes(p.lineId)).length === 0)
+}
+catch (err) {
+  failures += 1
+  console.error('\nE2E 异常中断:', err)
+}
+finally {
+  sim.kill()
+}
+
+console.log(`\n${failures === 0 ? '✅ 全部通过' : `❌ ${failures} 项失败`}  (AW_HOME=${awHome})`)
+process.exit(failures === 0 ? 0 : 1)

package/scripts/_dbg-param-map-rest-smoke.mjs

@@ -0,0 +1,73 @@
+/**
+ * 工艺参数映射 REST 冒烟(真实 dev server):
+ * ①params 列表(登录态 + 产线可见性过滤) ②建节点自动生成参数面(REST 视图无寄存器细节)
+ * ③param 写/读路由 ④param 基准限界 → 越界 400 ⑤产品限界落库 → 运行期产品层拦截
+ * ⑥清理(产线 purge)。mock 驱动,不依赖外部模拟器。
+ * 运行: node scripts/_dbg-param-map-rest-smoke.mjs(ROOT/E2E_USER/E2E_PASS 可覆盖)
+ */
+const ROOT = process.env.E2E_ROOT ?? 'http://127.0.0.1:3001'
+let failed = 0
+const check = (name, ok, detail = '') => { console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`); if (!ok) failed++ }
+
+/** 认证:AW_E2E_TOKEN 直用(隔离实例首注册 token);否则 E2E_USER/E2E_PASS 登录(docs/full-test-plan.md 测试账号) */
+let __token = process.env.AW_E2E_TOKEN
+if (!__token) {
+  const login = await fetch(`${ROOT}/api/users/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ email: process.env.E2E_USER ?? 'admin@awshop.local', password: process.env.E2E_PASS ?? 'admin123' }) }).then(r => r.json())
+  __token = login.data?.token
+  check('登录', !!__token, login.message ?? '')
+}
+else {
+  check('使用 AW_E2E_TOKEN', true)
+}
+const H = { authorization: `Bearer ${__token}`, 'content-type': 'application/json' }
+const j = (u, m = 'GET', b) => fetch(ROOT + u, { method: m, headers: H, body: b ? JSON.stringify(b) : undefined }).then(r => r.json())
+
+try {
+  // ① 列表路由
+  const list = await j('/api/workshop/dcw/params?limits=1')
+  check('GET /dcw/params 路由可用(含 limits 剖面)', Array.isArray(list.data?.params) && list.data.limits != null, `params=${list.data?.params?.length}`)
+
+  // ② 建线 + 建节点(mock)→ 自动参数面
+  const line = (await j('/api/workshop/dcw/lines', 'POST', { name: `PP冒烟线-${Date.now().toString(36)}` })).data?.line
+  check('创建产线', !!line?.id)
+  const node = (await j('/api/workshop/dcw', 'POST', { templateRef: 'dcw-pressure-sp', name: 'PP冒烟·熔体压力', driver: 'mock', driverConfig: { key: `pp-rest-${Date.now()}` }, readIntervalMs: 0, lineId: line.id })).data?.node
+  check('创建执行节点(mock)', !!node?.id)
+  const after = await j('/api/workshop/dcw/params')
+  const pv = after.data.params.find(p => p.nodeId === node.id)
+  check('节点创建自动生成参数面(pressure-sp)', pv?.key === 'pressure-sp', pv?.id)
+  check('REST 参数视图不含寄存器/数据类型细节', !JSON.stringify(pv).includes('register') && !JSON.stringify(pv).includes('dataType'))
+
+  // ③④ 参数写/读 + 基准限界
+  const w1 = (await j(`/api/workshop/dcw/params/${pv.id}/write`, 'POST', { value: 0.9 })).data?.outcome
+  check('param write 0.9MPa 成功(mock 回读一致)', w1?.ok === true, w1?.message)
+  const rd = (await j(`/api/workshop/dcw/params/${pv.id}/read`, 'POST', {})).data?.read
+  check('param read 返回物理值', rd?.ok === true && Math.abs((rd.value ?? 0) - 0.9) < 0.01, `value=${rd?.value}`)
+  await j(`/api/workshop/dcw/params/${pv.id}`, 'PATCH', { min: 0.7, max: 1.1 })
+  const w2 = await j(`/api/workshop/dcw/params/${pv.id}/write`, 'POST', { value: 1.15 })
+  check('越基准限界 1.15 → 400 点名参数层', w2.code === 'VALIDATION_ERROR' && w2.message?.includes('基准限界'), w2.message?.slice(0, 80))
+
+  // ⑤ 产品限界 → 运行期产品层拦截
+  const product = (await j('/api/workshop/dcw/products', 'POST', { name: 'PP冒烟产品', lineId: line.id, paramLimits: { 'pressure-sp': { min: 0.8, max: 1.0 } } })).data?.product
+  check('产品限界落库(0.8~1.0)', product?.paramLimits?.['pressure-sp']?.max === 1.0)
+  const recipe = (await j('/api/workshop/dcw/recipes', 'POST', { productId: product.id, name: 'PP冒烟配方', params: [{ nodeId: node.id, value: 0.9, min: 0.75, max: 1.05 }] })).data?.recipe
+  const start = await j(`/api/workshop/dcw/lines/${line.id}/start`, 'POST', { recipeId: recipe.id })
+  check('产线开跑', !!start.data?.run?.id, start.message)
+  const w3 = await j(`/api/workshop/dcw/params/${pv.id}/write`, 'POST', { value: 1.05 })
+  check('1.05 超产品上限 1.0 → 400 点名产品层', w3.code === 'VALIDATION_ERROR' && w3.message?.includes('产品'), w3.message?.slice(0, 80))
+  const w4 = (await j(`/api/workshop/dcw/params/${pv.id}/write`, 'POST', { value: 0.95 })).data?.outcome
+  check('0.95 交集内 → 通过', w4?.ok === true)
+  await j(`/api/workshop/dcw/lines/${line.id}/stop`, 'POST', {})
+
+  // ⑥ 清理
+  const del = await j(`/api/workshop/dcw/lines/${line.id}?purge=1`, 'DELETE')
+  check('产线 purge 清理', del.code === 0 || del.removed != null || del.data != null, JSON.stringify(del).slice(0, 80))
+  const afterDel = await j('/api/workshop/dcw/params')
+  check('purge 后参数面同步清理', !afterDel.data.params.some(p => p.id === pv.id))
+}
+catch (err) {
+  failed += 1
+  console.error('冒烟异常中断:', err)
+}
+
+console.log(`\n${failed === 0 ? '✅ REST 冒烟全部通过' : `❌ ${failed} 项失败`}`)
+process.exit(failed === 0 ? 0 : 1)