agentworkshop 0.6.1 → 0.7.1

package/scripts/_dbg-dcw-read-rest.mjs

@@ -0,0 +1,103 @@
+/**
+ * DCW 读写集成 E2E(真实 dev server):
+ * ①mock 驱动手动读写闭环(读随写变) ②标定 transform 物理域往返
+ * ③周期读服务端调度(不手动读,等节点自己读) ④真实 Modbus TCP(127.0.0.1:1502 从站,
+ * 40021 保持寄存器 float32 大端)写→读 roundtrip ×2  ⑤视图字段/视图列表收敛。
+ * 运行: node scripts/_dbg-dcw-read-rest.mjs(CLEANUP=1 结束后清理测试节点)
+ */
+const ROOT = process.env.E2E_ROOT ?? 'http://127.0.0.1:3000'
+const CLEANUP = process.env.CLEANUP === '1'
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+let failed = 0
+const check = (name, cond, detail = '') => { console.log(`  ${cond ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`); if (!cond) failed++ }
+
+const login = await fetch(`${ROOT}/api/users/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ email: 'zhangwei@awshop.io', password: 'Awshop@123' }) }).then(r => r.json())
+const H = { authorization: `Bearer ${login.data.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())
+const nodesOf = async () => (await j('/api/workshop/dcw')).data.nodes
+const nodeView = async (id) => (await nodesOf()).find(n => n.id === id)
+const write = (id, value) => j(`/api/workshop/dcw/${id}/write`, 'POST', { value }).then(r => r.data.outcome)
+const read = (id) => j(`/api/workshop/dcw/${id}/read`, 'POST', {}).then(r => r.data.read)
+
+const created = []
+async function mkNode(name, extra) {
+  const node = (await j('/api/workshop/dcw', 'POST', { templateRef: 'dcw-temp-sp', name, readIntervalMs: 0, ...extra })).data.node
+  created.push(node.id)
+  return node
+}
+
+// 幂等清理:上一次异常中断残留的同名节点先删
+for (const stale of (await nodesOf()).filter(n => n.name?.startsWith('读写验证·'))) {
+  await j(`/api/workshop/dcw/${stale.id}`, 'DELETE').catch(() => {})
+}
+// mock PLC 状态在服务进程内掉电保持(同真实寄存器):每次运行用独立 key 避免跨运行串扰
+const RUN = Date.now().toString(36)
+
+// ===== ① mock 手动读写闭环 =====
+console.log('\n--- ① mock 手动读写闭环 ---')
+{
+  const n = await mkNode('读写验证·mock 手动', { driver: 'mock', driverConfig: { key: `rw-e2e-1-${RUN}` } })
+  check('视图透出读字段(readValue/readIntervalMs/lastRead*)', 'readValue' in n && 'readIntervalMs' in n && 'lastReadAt' in n && 'lastReadError' in n)
+  const before = await read(n.id)
+  check('未写入时读取:如实报告失败(mock 无记录)', before.ok === false && before.value == null, before.message.slice(0, 50))
+  const w1 = await write(n.id, 165.5)
+  check('写 165.5 成功(回读一致)', w1.ok === true, w1.message.slice(0, 60))
+  const r1 = await read(n.id)
+  check('读回 = 刚写值(165.5)', r1.ok && Math.abs(r1.value - 165.5) < 0.01, `value=${r1.value}`)
+  await write(n.id, 180)
+  const r2 = await read(n.id)
+  check('再写 180 后读随写变', r2.ok && Math.abs(r2.value - 180) < 0.01, `value=${r2.value}`)
+  const v = await nodeView(n.id)
+  check('节点视图记账(readValue/lastReadAt/SET value)', Math.abs(v.readValue - 180) < 0.01 && v.lastReadAt != null && Math.abs(v.value - 180) < 0.01, `act=${v.readValue} set=${v.value}`)
+}
+
+// ===== ② 标定 transform 物理域往返 =====
+console.log('\n--- ② transform 物理域往返 ---')
+{
+  const n = await mkNode('读写验证·标定×2', { driver: 'mock', driverConfig: { key: `rw-e2e-2-${RUN}` }, transform: { kind: 'linear', scale: 2, offset: 0 }, min: 0, max: 400 })
+  await write(n.id, 100)
+  const r = await read(n.id)
+  check('物理 100(PLC 50)写→读往返一致', r.ok && Math.abs(r.value - 100) < 0.01, `value=${r.value}(raw=${r.raw})`)
+}
+
+// ===== ③ 周期读服务端调度 =====
+console.log('\n--- ③ 周期读调度(readIntervalMs=1000,不手动读) ---')
+{
+  const n = await mkNode('读写验证·周期读', { driver: 'mock', driverConfig: { key: `rw-e2e-3-${RUN}` }, readIntervalMs: 1000 })
+  await write(n.id, 155)
+  check('写入后 SET 已记账', Math.abs((await nodeView(n.id)).value - 155) < 0.01)
+  await sleep(2600)
+  const v = await nodeView(n.id)
+  check('2.6s 内周期读自动回填 ACT(服务端调度)', Math.abs(v.readValue - 155) < 0.01 && v.lastReadAt != null, `act=${v.readValue} @${v.lastReadAt?.slice(11, 19)}`)
+}
+
+// ===== ④ 真实 Modbus TCP 读写 roundtrip =====
+console.log('\n--- ④ 真实 Modbus TCP(1502 从站,float32 大端) ---')
+{
+  const cfg = { host: '127.0.0.1', port: 1502, unitId: 1, register: 40021, dataType: 'float32', byteOrder: 'big' }
+  const n = await mkNode('读写验证·Modbus真实链路', { driver: 'modbus-tcp', driverConfig: cfg, min: 0, max: 300 })
+  const t = await j(`/api/workshop/dcw/${n.id}/test`, 'POST').then(r => r.data.test)
+  check('真实从站连接测试(40021 可访问)', t.ok === true, t.message.slice(0, 60))
+  const r0 = await read(n.id)
+  check('真实读:初始寄存器值(raw=0 → 0)', r0.ok && r0.raw != null, `raw=${r0.raw}`)
+  const w1 = await write(n.id, 3.1416)
+  check('真实写:3.1416 下发+同址回读一致', w1.ok === true, w1.message.slice(0, 70))
+  const r1 = await read(n.id)
+  check('真实读:寄存器回 3.1416(独立于写回读的第二笔读)', r1.ok && Math.abs(r1.raw - 3.1416) < 0.001, `raw=${r1.raw} eng=${r1.value}`)
+  const w2 = await write(n.id, 2.71828)
+  const r2 = await read(n.id)
+  check('第二轮写读:2.71828 roundtrip', w2.ok && r2.ok && Math.abs(r2.raw - 2.71828) < 0.001, `raw=${r2.raw}`)
+  const v = await nodeView(n.id)
+  check('真实节点视图 ACT 收敛(2.72 MPa? ℃模板域 150~200 → 用原始值展示)', v.readValue != null && v.lastReadAt != null, `act=${v.readValue} raw=${r2.raw}`)
+}
+
+// ===== 收尾 =====
+if (CLEANUP) {
+  for (const id of created) await j(`/api/workshop/dcw/${id}`, 'DELETE').catch(() => {})
+  console.log(`(cleanup:${created.length} 个测试节点已删)`)
+}
+else {
+  console.log(`(节点保留:${created.join(', ')};CLEANUP=1 可清理)`)
+}
+console.log(failed === 0 ? '\nDCW-READ-E2E ALL PASS' : `\nDCW-READ-E2E FAILED(${failed})`)
+process.exit(failed === 0 ? 0 : 1)

package/scripts/_dbg-dcw-read-toolface.ts

@@ -0,0 +1,13 @@
+/**
+ * 一次性检查:dcw_read 进入 hostToolsForRole 工具面(worker/lead)。
+ * 运行: npx tsx --tsconfig .nuxt/tsconfig.server.json scripts/_dbg-dcw-read-toolface.ts
+ */
+import { hostToolsForRole } from '../server/services/workshop/agents/omp-agent'
+
+for (const role of ['worker', 'lead'] as const) {
+  const names = hostToolsForRole(role).map(t => t.name)
+  const hit = names.includes('dcw_read')
+  console.log(`${role}: dcw_read ${hit ? '在工具面' : '缺失!'}(${names.length} 个工具)`)
+  if (role === 'worker' && !hit) process.exit(1)
+}
+console.log('TOOLFACE PASS')

package/scripts/_dbg-dcw-read-ui.mjs

@@ -0,0 +1,74 @@
+/**
+ * DCW 读写集成 UI 目视验证:/dcw/[line] 节点表「PLC 读数」列(含真实 Modbus 节点)
+ * + /town 设备卡 ACT 读数行。截图落 .e2e-shots/。
+ * 运行: node scripts/_dbg-dcw-read-ui.mjs
+ */
+import puppeteer from 'puppeteer-core'
+import { mkdirSync } from 'node:fs'
+
+const ROOT = process.env.E2E_ROOT ?? 'http://127.0.0.1:3000'
+const LINE = process.env.LINE ?? 'ln-af002514'
+const DEV = '循环泵 #01'
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+let failed = 0
+const check = (name, cond, detail = '') => { console.log(`  ${cond ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`); if (!cond) failed++ }
+const shot = async (page, name) => {
+  mkdirSync('.e2e-shots', { recursive: true })
+  await page.screenshot({ path: `.e2e-shots/${name}.png` })
+}
+
+const login = await fetch(`${ROOT}/api/users/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ email: 'zhangwei@awshop.io', password: 'Awshop@123' }) }).then(r => r.json())
+
+const browser = await puppeteer.launch({ executablePath: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', headless: 'new', args: ['--no-sandbox', '--disable-gpu', '--window-size=1600,1000'] })
+const page = await browser.newPage()
+await page.setViewport({ width: 1600, height: 1000 })
+await page.setCookie({ name: 'token', value: login.data.token, domain: '127.0.0.1', path: '/' })
+try {
+  // ① /dcw/[line] 节点表:PLC 读数列 + 读取按钮 + 各节点读数值
+  await page.goto(`${ROOT}/dcw/${LINE}`, { waitUntil: 'networkidle2', timeout: 90000 })
+  await page.waitForSelector('.nodes-table tbody tr', { timeout: 30000 })
+  await sleep(3000)
+  const head = await page.evaluate(() => [...document.querySelectorAll('.nodes-table th')].map(t => t.textContent.trim()))
+  check('①表头含「PLC 读数」列', head.some(t => t.includes('PLC 读数')), head.join('|'))
+  const rows = await page.evaluate(() => [...document.querySelectorAll('.nodes-table tbody tr')].map((tr) => {
+    const cells = [...tr.querySelectorAll('td')]
+    const name = tr.querySelector('td b')?.textContent?.trim() ?? ''
+    return { name, read: cells[4]?.textContent?.replace(/\s+/g, ' ').trim() ?? '', hasReadBtn: !!cells[4]?.querySelector('.read-btn') }
+  }).filter(r => r.name.includes('读写验证')))
+  check('①四个测试节点都在行内', rows.length >= 4, rows.map(r => `${r.name}:${r.read}`).join(' | ').slice(0, 160))
+  check('①行内有「读取」按钮', rows.every(r => r.hasReadBtn) && rows.length > 0)
+  check('①Modbus 真实节点 ACT 已回填', rows.some(r => r.name.includes('Modbus') && /\d/.test(r.read)), rows.find(r => r.name.includes('Modbus'))?.read)
+  await shot(page, 'dcw-line-read-column')
+
+  // ② 点「读取」按钮 → 读数刷新(手动读 UI 路径)
+  const btnOk = await page.evaluate(() => {
+    const row = [...document.querySelectorAll('.nodes-table tbody tr')].find(tr => tr.textContent?.includes('mock 手动'))
+    const btn = row?.querySelector('.read-btn')
+    if (!btn) return false
+    btn.click()
+    return true
+  })
+  await sleep(1500)
+  check('②点击「读取」按钮执行手动读', btnOk)
+
+  // ③ /town 设备卡:SET + ACT 两行实时
+  await page.goto(`${ROOT}/town`, { waitUntil: 'domcontentloaded', timeout: 90000 })
+  await sleep(20000)
+  const act = () => page.evaluate((dev) => {
+    const card = [...document.querySelectorAll('.twin-card')].find(c => c.querySelector('.twin-name')?.textContent?.includes(dev))
+    const items = card ? [...card.querySelectorAll('.dcw-item')].map(e => ({
+      set: e.querySelector('.dcw-set')?.textContent?.replace(/\s+/g, '') ?? '',
+      act: e.querySelector('.dcw-act b')?.textContent?.replace(/\s+/g, '') ?? null,
+    })) : []
+    return items
+  }, DEV)
+  const a1 = await act()
+  check('③/town 设备卡出现智控通道(SET)', a1.length > 0, JSON.stringify(a1).slice(0, 120))
+  check('③通道带 ACT 读数行', a1.some(r => r.act != null && /\d/.test(r.act)), JSON.stringify(a1.map(r => r.act)))
+  await shot(page, 'town-dcw-act')
+}
+finally {
+  await browser.close().catch(() => {})
+}
+console.log(failed === 0 ? '\nDCW-READ-UI ALL PASS' : `\nDCW-READ-UI FAILED(${failed})`)
+process.exit(failed === 0 ? 0 : 1)

package/scripts/_dbg-plugin-ui-wizard.mjs

@@ -0,0 +1,125 @@
+/**
+ * 插件扩展验证 D(浏览器 UI 真实操作):/daq 新增节点向导选择插件模板 →
+ * 通过 UI 建节点 → 列表行实时值流入 → /town 孪生面板出现该节点。
+ * 截图落 .e2e-shots/(向导/列表/孪生);节点保留(CLEANUP=1 删除)。
+ * 运行: node scripts/_dbg-plugin-ui-wizard.mjs
+ */
+import puppeteer from 'puppeteer-core'
+import { mkdirSync, writeFileSync } from 'node:fs'
+
+const ROOT = process.env.E2E_ROOT ?? 'http://127.0.0.1:3000'
+const CLEANUP = process.env.CLEANUP === '1'
+const NODE_NAME = process.env.NODE_NAME ?? 'UI向导插件验证'
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+let failed = 0
+const check = (name, cond, detail = '') => { console.log(`  ${cond ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`); if (!cond) failed++ }
+const shot = async (page, name) => {
+  mkdirSync('.e2e-shots', { recursive: true })
+  await page.screenshot({ path: `.e2e-shots/${name}.png` })
+}
+
+const login = await fetch(`${ROOT}/api/users/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ email: 'zhangwei@awshop.io', password: 'Awshop@123' }) }).then(r => r.json())
+const H = { authorization: `Bearer ${login.data.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())
+
+const browser = await puppeteer.launch({ executablePath: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', headless: 'new', args: ['--no-sandbox', '--disable-gpu', '--window-size=1600,1000'] })
+const page = await browser.newPage()
+await page.setViewport({ width: 1600, height: 1000 })
+await page.setCookie({ name: 'token', value: login.data.token, domain: '127.0.0.1', path: '/' })
+let createdNodeId = null
+try {
+  // ① 打开 /daq → 点「添加节点」→ 向导弹出
+  await page.goto(`${ROOT}/daq`, { waitUntil: 'networkidle2', timeout: 90000 })
+  await page.waitForSelector('tbody tr', { timeout: 30000 })
+  await page.click('button.aw-pill.add-btn:not(.outline)')
+  await page.waitForSelector('.modal .f-grid select.inp', { timeout: 15000 })
+
+  // ② 模板下拉含插件模板(服务端目录直出)
+  const opts = await page.$$eval('.modal .f-grid select.inp option', os => os.map(o => ({ v: o.value, t: o.textContent.replace(/\s+/g, ' ').trim() })))
+  const plugOpt = opts.find(o => o.v === 'plug-verify-x2-profile')
+  check('①向导模板下拉含插件模板', plugOpt != null, plugOpt?.t ?? `共 ${opts.length} 项`)
+  check('①插件模板带自定义标记(非内置)', plugOpt != null && /自定义|插件/.test(plugOpt.t), plugOpt?.t)
+
+  // ③ 选中插件模板 → 命名 → 截图 → UI 保存
+  await page.select('.modal .f-grid select.inp', 'plug-verify-x2-profile')
+  await page.type('.modal input.inp', NODE_NAME)
+  await shot(page, 'wizard-plugin-template')
+  await page.click('.m-actions button.aw-pill:not(.outline)')
+  await sleep(4000)
+
+  // ③b 行内产线下拉挂到运行中的产线(采集是配方驱动的:未分配不采样)
+  const ctxFile = await import('node:fs')
+  const runLine = process.env.RUN_LINE ?? JSON.parse(ctxFile.readFileSync('.e2e-plugin-ctx.json', 'utf-8')).lineId
+  const lineName = ((await j('/api/workshop/dcw')).data.lines ?? []).find(l => l.id === runLine)?.name
+  const lineOpts = await page.evaluate((nm) => {
+    const row = [...document.querySelectorAll('tbody tr')].find(r => r.textContent?.includes(nm))
+    const sel = row?.querySelector('select.line-sel')
+    return sel ? Array.from(sel.options).map(o => ({ v: o.value, t: o.textContent.trim() })) : null
+  }, NODE_NAME)
+  const lineOpt = (lineOpts ?? []).find(o => o.t === lineName)
+  check('③b 行内产线下拉含运行中产线', lineOpt != null, `${lineName} 选项=${lineOpt?.v ?? '无'}`)
+  // puppeteer 的 page.select 需要全局选择器:行内直接派发 change 更稳
+  await page.evaluate((nm, lineId) => {
+    const row = [...document.querySelectorAll('tbody tr')].find(r => r.textContent?.includes(nm))
+    const sel = row?.querySelector('select.line-sel')
+    if (!sel) throw new Error('行内无产线下拉')
+    sel.value = lineId
+    sel.dispatchEvent(new Event('change', { bubbles: true }))
+  }, NODE_NAME, runLine)
+  await sleep(2500)
+
+  // ④ 列表行出现且实时值流入(WS 帧驱动)
+  const rowVal = () => page.evaluate((nm) => {
+    const row = [...document.querySelectorAll('tbody tr')].find(r => r.textContent?.includes(nm))
+    const m = row?.textContent?.match(/(\d+\.\d+)\s*mm/)
+    return { v: m ? m[1] : null, row: row?.textContent?.replace(/\s+/g, ' ').slice(0, 120) ?? '' }
+  }, NODE_NAME)
+  const r1 = await rowVal()
+  await sleep(5000)
+  const r2 = await rowVal()
+  check('④UI 建出的插件节点出现在列表', r1.v != null, r1.row)
+  check('④列表实时值变化(帧流入)', r1.v != null && r2.v != null && r1.v !== r2.v, `${r1.v} → ${r2.v}`)
+  await shot(page, 'daq-list-plugin-node')
+  const nodes = (await j('/api/workshop/daq')).data.nodes
+  createdNodeId = nodes.find(n => n.name === NODE_NAME)?.id ?? null
+
+  // ④b 行内设备下拉绑定设备(孪生面板按设备挂数采项)
+  const devOpt = await page.evaluate((nm) => {
+    const row = [...document.querySelectorAll('tbody tr')].find(r => r.textContent?.includes(nm))
+    const sel = row?.querySelectorAll('select.line-sel')[1]
+    const first = sel?.querySelector('option[value]:not([value=""])')
+    if (!sel || !first) return null
+    sel.value = first.value
+    sel.dispatchEvent(new Event('change', { bubbles: true }))
+    return { v: first.value, t: first.textContent.trim() }
+  }, NODE_NAME)
+  check('④b 行内绑定设备(第一可绑定项)', devOpt != null, devOpt ? `${devOpt.t}(${devOpt.v})` : '无可绑定设备')
+  await sleep(2000)
+
+  // ⑤ /town 孪生面板出现该节点且实时
+  await page.goto(`${ROOT}/town`, { waitUntil: 'domcontentloaded', timeout: 90000 })
+  await sleep(20000)
+  // 面板项显示模板通道名(d.ch),节点挂在绑定设备卡下 → 按「设备卡 + 通道名」定位
+  const panel = () => page.evaluate(() => {
+    const card = [...document.querySelectorAll('.twin-card')].find(c => c.querySelector('.twin-name')?.textContent?.includes('循环泵 #01'))
+    const item = card ? [...card.querySelectorAll('.daq-item')].find(e => e.textContent?.includes('标定轮廓')) : null
+    return { card: !!card, text: item?.textContent?.replace(/\s+/g, '') ?? '', val: item?.querySelector('b')?.textContent?.replace(/\s+/g, '') ?? null }
+  })
+  const p1 = await panel()
+  await sleep(5000)
+  const p2 = await panel()
+  check('⑤/town 设备卡(循环泵 #01)出现', p1.card)
+  check('⑤/town 孪生面板出现插件节点通道(标定轮廓)', p1.text !== '', p1.text.slice(0, 60))
+  check('⑤/town 面板实时值变化', p1.val != null && p2.val != null && p1.val !== p2.val, `${p1.val} → ${p2.val}`)
+  await shot(page, 'town-panel-plugin-node')
+}
+finally {
+  await browser.close().catch(() => {})
+  if (CLEANUP && createdNodeId) {
+    await j(`/api/workshop/daq/${createdNodeId}`, 'DELETE').catch(() => {})
+    console.log(`(cleanup:节点 ${createdNodeId} 已删)`)
+  }
+}
+writeFileSync('.e2e-plugin-ui-node.json', JSON.stringify({ nodeId: createdNodeId, name: NODE_NAME }))
+console.log(failed === 0 ? '\nSTACK-D ALL PASS' : `\nSTACK-D FAILED(${failed})`)
+process.exit(failed === 0 ? 0 : 1)

package/scripts/test-config-precedence.ts

@@ -0,0 +1,124 @@
+/**
+ * 配置驱动回归:优先级链(env > runtime-settings > config.yml > 描述符默认)+
+ * 历史别名兼容 + 项目级(.AgentWorkShop)优先/用户级(~/.AgentWorkShop)兜底的路径判定。
+ * 运行: npx tsx --tsconfig .nuxt/tsconfig.server.json scripts/test-config-precedence.ts
+ */
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+let failures = 0
+const check = (name: string, ok: boolean, detail = ''): void => {
+  console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok) failures += 1
+}
+
+const root = mkdtemp()
+function mkdtemp(): string {
+  return rm0(join(tmpdir(), 'aw-cfg-prec-'))
+  function rm0(p: string): string {
+    const dir = `${p}${Math.random().toString(36).slice(2, 8)}`
+    mkdirSync(dir, { recursive: true })
+    return dir
+  }
+}
+
+const engine = await import('../shared/config/engine.mjs')
+const { loadDescriptors, envOverridesFromEnv, loadEffective } = engine as unknown as {
+  loadDescriptors: () => Array<Record<string, unknown>>
+  envOverridesFromEnv: (env: Record<string, string | undefined>, d?: unknown) => Record<string, unknown>
+  loadEffective: (o: { configPath?: string, settingsPath?: string, env?: Record<string, string | undefined> }) => { effective: Record<string, unknown>, sources: Record<string, string> }
+}
+
+// ===== 1. 描述符完整性:每个键都有 default + labelKey;别名唯一 =====
+{
+  const descs = loadDescriptors() as Array<{ key: string, default?: unknown, labelKey?: string, aliases?: string[] }>
+  check(`描述符规模(≥62 键,当前 ${descs.length})`, descs.length >= 62)
+  check('全部键带 default 与 labelKey', descs.every(d => d.default !== undefined && !!d.labelKey))
+  const seen = new Map<string, string>()
+  let dup = ''
+  for (const d of descs) {
+    for (const a of [d.key, ...(d.aliases ?? [])].map(x => x.toUpperCase())) {
+      if (seen.has(a) && seen.get(a) !== d.key) dup = `${a}:${seen.get(a)}&${d.key}`
+      seen.set(a, d.key)
+    }
+  }
+  check('键+别名无冲突', dup === '')
+  // 新迁移组抽查
+  const keys = new Set(descs.map(d => d.key))
+  for (const k of ['memory.inject_total', 'omp.compact_enabled', 'dcw.rollback_stale_ms', 'backup.keep', 'retention.audit_days', 'log.level', 'daq.mqtt.qos', 'daq.frameRetentionH', 'security.hitl_timeout_ms', 'workshop.idle_grace_ms']) {
+    if (!keys.has(k)) {
+      check(`迁移键 ${k} 已注册`, false)
+      failures++
+    }
+  }
+  check('迁移键抽查全部注册', true)
+}
+
+// ===== 2. env 覆盖:AW_<KEY> 自动名 + 历史别名 =====
+{
+  const o = envOverridesFromEnv({
+    AW_MEMORY_INJECT_TOTAL: '800',
+    DAQ_FRAME_RETENTION_H: '999', // 历史别名(无 AW_ 前缀)
+    RETENTION_DISABLED: '1', // 历史别名(boolean "1")
+    AWSHOP_LOG_LEVEL: 'warn',
+  })
+  check('AW_<KEY> 自动名覆盖', o['memory.inject_total'] === 800)
+  check('历史别名:DAQ_FRAME_RETENTION_H', o['daq.frameRetentionH'] === 999)
+  check('历史别名 boolean "1"', o['retention.disabled'] === true)
+  check('历史别名:AWSHOP_LOG_LEVEL', o['log.level'] === 'warn')
+}
+
+// ===== 3. 完整优先级链:env > runtime-settings > config.yml > 描述符默认 =====
+{
+  const configPath = join(root, 'config.yml')
+  const settingsPath = join(root, 'runtime-settings.json')
+  writeFileSync(configPath, [
+    'memory:',
+    '  primer_tokens: 111',
+    'backup:',
+    '  keep: 5',
+    'log:',
+    '  level: warn',
+  ].join('\n'))
+  writeFileSync(settingsPath, JSON.stringify({ version: 1, overrides: { 'memory.primer_tokens': 222 } }))
+  const eff = loadEffective({ configPath, settingsPath, env: { AW_MEMORY_INJECT_TOTAL: '800', BACKUP_KEEP: '3' } })
+  check('env 胜 runtime(memory.inject_total=800)', eff.effective['memory.inject_total'] === 800 && eff.sources['memory.inject_total'] === 'env')
+  check('runtime 胜 config.yml(memory.primer_tokens=222)', eff.effective['memory.primer_tokens'] === 222 && eff.sources['memory.primer_tokens'] === 'runtime')
+  check('config.yml 胜默认(log.level=warn)', eff.effective['log.level'] === 'warn' && eff.sources['log.level'] === 'config.yml')
+  check('描述符默认兜底(dcw.rollback_cooldown_ms=300000)', eff.effective['dcw.rollback_cooldown_ms'] === 300000)
+  check('别名 env 胜 config.yml(backup.keep=3)', eff.effective['backup.keep'] === 3 && eff.sources['backup.keep'] === 'env')
+}
+
+// ===== 4. 项目级优先 / 用户级兜底(resolveRunMode 路径判定) =====
+{
+  const home = await import('../shared/config/home.mjs') as unknown as {
+    resolveRunMode: (o: { cwd: string, packageRoot?: string, env?: Record<string, string | undefined> }) => { mode: string, configRoot: string, dataDir: string, configPath: string, settingsPath: string }
+    awHome: (env?: Record<string, string | undefined>) => string
+    ensureDataDir: (cwd?: string, env?: Record<string, string | undefined>) => string
+  }
+  // ④a 项目级:cwd 下存在 .AgentWorkShop → 用它(最高优先)
+  const proj = join(root, 'proj')
+  mkdirSync(join(proj, '.AgentWorkShop'), { recursive: true })
+  const m1 = home.resolveRunMode({ cwd: proj, packageRoot: join(root, 'pkg') })
+  check('④项目级 .AgentWorkShop 优先', m1.mode === 'repo' && m1.configRoot === join(proj, '.AgentWorkShop'), m1.configRoot)
+
+  // ④b 用户级兜底:检出内无 ./.AgentWorkShop → 数据落 ~/.AgentWorkShop(AW_HOME 可重定向)
+  const fakeHome = join(root, 'fake-home')
+  const m2 = home.resolveRunMode({ cwd: join(root, 'empty-cwd'), packageRoot: join(root, 'pkg'), env: { AW_HOME: fakeHome } })
+  check('④无项目根 → 用户级兜底 ~/.AgentWorkShop(AW_HOME)', m2.configRoot === fakeHome, m2.configRoot)
+  mkdirSync(fakeHome, { recursive: true })
+  const dataDir = home.ensureDataDir(join(root, 'empty-cwd'), { AW_HOME: fakeHome })
+  check('④ensureDataDir 初始化创建 <home>/data', dataDir === join(fakeHome, 'data'), dataDir)
+
+  // ④c home 模式(AW_MODE=home,全局安装载荷):强制用户级
+  const m3 = home.resolveRunMode({ cwd: proj, packageRoot: join(root, 'pkg'), env: { AW_MODE: 'home', AW_HOME: fakeHome } })
+  check('④AW_MODE=home 强制用户级(项目 .AgentWorkShop 不采用)', m3.mode === 'home' && m3.configRoot === fakeHome)
+
+  // ④d 默认 awHome = ~/.AgentWorkShop
+  check('④awHome 默认 ~/.AgentWorkShop', /AgentWorkShop$/.test(home.awHome({})) === true, home.awHome({}))
+}
+
+rmSync(root, { recursive: true, force: true })
+console.log(failures === 0 ? '\nCONFIG-PRECEDENCE ALL PASS' : `\nCONFIG-PRECEDENCE FAILED(${failures})`)
+process.exit(failures === 0 ? 0 : 1)

package/scripts/test-dcw-read.ts

@@ -0,0 +1,153 @@
+/**
+ * DCW 读写集成单元测试:驱动 read 原语(mock/modbus 形态判定)/工程量↔原始值对称映射/
+ * 节点读状态记账/运行时周期读调度/手动读取/Agent dcw_read 工具(鉴权+执行,AW_HOME 隔离)。
+ * 运行: AW_MODE=home AW_HOME=<tmp> npx tsx --tsconfig .nuxt/tsconfig.server.json scripts/test-dcw-read.ts
+ */
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+// 工具段需要文件型仓库:整体进程重定向到一次性配置根(避免触碰检出内 .AgentWorkShop)
+const awHome = mkdtempSync(join(tmpdir(), 'aw-dcw-read-'))
+process.env.AW_MODE = 'home'
+process.env.AW_HOME = awHome
+
+let failures = 0
+function check(name: string, ok: boolean, detail = ''): void {
+  console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok) failures += 1
+}
+
+// ===== 1. 驱动 read 原语 =====
+console.log('\n--- 驱动 read 原语 ---')
+{
+  const { mockDcwDriver, supportsDcwRead } = await import('../server/services/workshop/dcw/drivers')
+  const domain = { min: 0, max: 300 }
+  const w = await mockDcwDriver.write({ eng: 165, tolerance: 0.1, domain, driverConfig: { key: 't1' } })
+  check('mock 写入成功', w.ok)
+  const r = await mockDcwDriver.read!({ domain, driverConfig: { key: 't1' } })
+  check('mock 读回写值(读写闭环)', r.ok && r.eng === 165 && r.raw === 165, `eng=${r.eng}`)
+  const miss = await mockDcwDriver.read!({ domain, driverConfig: { key: 'never-written' } })
+  check('mock 未写地址读取明确失败', !miss.ok && miss.eng == null)
+  check('读能力判定:mock/modbus-tcp/modbus-rtu/opcua 可读,mqtt/http 不可读',
+    supportsDcwRead('mock') && supportsDcwRead('modbus-tcp') && supportsDcwRead('modbus-rtu') && supportsDcwRead('opcua')
+    && !supportsDcwRead('mqtt') && !supportsDcwRead('http'))
+}
+
+// ===== 2. 工程量↔原始值映射对称 =====
+console.log('\n--- 工程量↔原始值映射 ---')
+{
+  const { engToRaw, rawToEng } = await import('../server/services/workshop/dcw/drivers')
+  const input = { eng: 50, tolerance: 0, domain: { min: 0, max: 100 }, driverConfig: { rawMin: 0, rawMax: 16383, engMin: 0, engMax: 100 } }
+  const raw = engToRaw(50, input)
+  check('线性映射:eng 50 → raw 8191.5', Math.abs(raw - 8191.5) < 1e-9, String(raw))
+  check('映射对称:rawToEng(engToRaw(x)) = x', Math.abs(rawToEng(raw, input) - 50) < 1e-9)
+  const pass = { eng: 7, tolerance: 0, domain: { min: 0, max: 100 }, driverConfig: {} }
+  check('无原始量程:直传(float32 语义)', engToRaw(7, pass) === 7 && rawToEng(7, pass) === 7)
+}
+
+// ===== 3. 节点读状态记账 =====
+console.log('\n--- 节点读状态 ---')
+{
+  const { DcwNode } = await import('../server/services/workshop/dcw/dcw-node')
+  const n = new DcwNode({ id: 'dw-t1', templateRef: 'dcw-temp-sp', readIntervalMs: 2000 })
+  const at = new Date().toISOString()
+  n.applyReadResult(168.456, 168.456, true, '读回', at)
+  check('成功读数回填(按 decimals 取整)', n.readValue === 168.5 && n.lastReadAt === at && n.lastReadError == null, `readValue=${n.readValue}`)
+  n.applyReadResult(null, null, false, '链路超时', new Date().toISOString())
+  check('失败读保留旧值并记原因', n.readValue === 168.5 && n.lastReadError === '链路超时')
+  n.applyReadResult(170, 170, true, '读回', new Date().toISOString())
+  check('恢复成功后清空错误', n.readValue === 170 && n.lastReadError == null)
+  const row = n.toRow()
+  const n2 = DcwNode.fromRow(row)
+  check('持久化 roundtrip(readIntervalMs/readValue/lastRead*)', n2.readIntervalMs === 2000 && n2.readValue === 170 && n2.lastReadError == null)
+  const v = n2.toView()
+  check('视图透出读字段', v.readValue === 170 && v.readIntervalMs === 2000 && 'lastReadError' in v)
+}
+
+// ===== 4. 运行时周期读调度 =====
+console.log('\n--- 运行时周期读调度 ---')
+{
+  const { DcwNode } = await import('../server/services/workshop/dcw/dcw-node')
+  const rtMod = await import('../server/services/workshop/dcw/dcw-runtime')
+  const { DcwNodeRuntime } = rtMod
+  type DcwRuntimeHost = import('../server/services/workshop/dcw/dcw-runtime').DcwRuntimeHost
+  type DcwNodeT = import('../server/services/workshop/dcw/dcw-node').DcwNode
+  const reads: number[] = []
+  const atNow = () => new Date().toISOString()
+  // 记账语义与控制器一致:读成功回填节点 readValue
+  const makeHost = (defaults: { holdIntervalMs: number, readIntervalMs: number }): DcwRuntimeHost => ({
+    running: () => true,
+    defaults: () => defaults,
+    executeWrite: async () => ({ ok: true, message: '', raw: null, readback: null }),
+    executeRead: async (node: DcwNodeT) => {
+      reads.push(Date.now())
+      node.applyReadResult(1, 1, true, '读回', atNow())
+      return { ok: true, value: 1, raw: 1, message: '', at: atNow() }
+    },
+  })
+  const n = new DcwNode({ id: 'dw-t2', templateRef: 'dcw-temp-sp', readIntervalMs: 1000 })
+  const rt = new DcwNodeRuntime(n, makeHost({ holdIntervalMs: 0, readIntervalMs: 5000 }))
+  const t0 = 1_000_000
+  rt.tick(t0)
+  rt.tick(t0 + 500)
+  rt.tick(t0 + 1100)
+  check('周期读按 readIntervalMs 节拍触发(两次窗内各一次)', reads.length === 2, `reads=${reads.length}`)
+  check('写心跳不触发(value=null)', reads.length === 2)
+  n.readValue = 165
+  const manual = await rt.readNow()
+  check('手动读取(readNow)执行并记账', manual.ok && n.readValue === 1 && n.lastReadError == null, `readValue=${n.readValue}`)
+  const schedAfterManual = reads.length
+  const off = new DcwNode({ id: 'dw-t3', templateRef: 'dcw-temp-sp', readIntervalMs: 0 })
+  const rtOff = new DcwNodeRuntime(off, makeHost({ holdIntervalMs: 0, readIntervalMs: 5000 }))
+  rtOff.tick(t0)
+  rtOff.tick(t0 + 2000)
+  check('readIntervalMs=0 关闭周期读', reads.length === schedAfterManual)
+  // 在飞互斥:挂起中的读阻塞 readNow → 409
+  let release: (() => void) | null = null
+  const slowHost: DcwRuntimeHost = {
+    running: () => true,
+    defaults: () => ({ holdIntervalMs: 0, readIntervalMs: 5000 }),
+    executeWrite: async () => ({ ok: true, message: '', raw: null, readback: null }),
+    executeRead: async () => {
+      await new Promise<void>((r) => {
+        release = r
+      })
+      return { ok: true, value: 1, raw: null, message: '', at: atNow() }
+    },
+  }
+  const rtSlow = new DcwNodeRuntime(new DcwNode({ id: 'dw-t4', templateRef: 'dcw-temp-sp', readIntervalMs: null }), slowHost)
+  const inFlight = rtSlow.readNow()
+  let conflicted = false
+  await rtSlow.readNow().catch((e: unknown) => {
+    conflicted = (e as { status?: number }).status === 409
+  })
+  release!()
+  const done = await inFlight
+  check('读在飞互斥(并发 readNow → 409)', conflicted && done.ok)
+}
+
+// ===== 5. Agent dcw_read 工具(鉴权 + 执行;隔离配置根) =====
+console.log('\n--- Agent dcw_read 工具 ---')
+{
+  const { toolDcwRead } = await import('../server/services/workshop/agents/industrial-tools')
+  const denied = await toolDcwRead('agent-x', { node_id: 'dw-none' })
+  check('未绑定 agent 读取被拒', denied.isError === true && /未绑定|无权/.test(denied.text))
+  const { getDcwController } = await import('../server/services/workshop/dcw/dcw-controller')
+  const { getAgentNodeBindingRepo } = await import('../server/services/workshop/agents/node-bindings.repo')
+  const node = getDcwController().create({ templateRef: 'dcw-temp-sp', driver: 'mock', driverConfig: { key: 'agent-t' }, readIntervalMs: 0, name: '读链路测试节点' })
+  const repo = getAgentNodeBindingRepo()
+  repo.bind('agent-a', node.id, 'dcw', 'auto')
+  const before = await toolDcwRead('agent-a', { node_id: node.id })
+  check('从未下发的节点:鉴权通过并如实报告读取失败(mock 无记录)', before.isError === true && /读取失败/.test(before.text) && !/无权|未绑定/.test(before.text), before.text.slice(0, 80))
+  await getDcwController().write(node.id, 172.5, null, { source: 'manual', actor: 'tester' })
+  const after = await toolDcwRead('agent-a', { node_id: node.id })
+  check('写入后读取:ACT 与 SET 一致', after.isError !== true && /172\.5/.test(after.text) && /一致/.test(after.text), after.text.replace(/\n/g, ' | ').slice(0, 140))
+  const other = await toolDcwRead('agent-b', { node_id: node.id })
+  check('其他 agent 越权读取被拒', other.isError === true)
+}
+
+// 收尾
+rmSync(awHome, { recursive: true, force: true })
+console.log(failures === 0 ? '\nDCW-READ ALL PASS' : `\nDCW-READ FAILED(${failures})`)
+process.exit(failures === 0 ? 0 : 1)

package/server/api/workshop/dcw/[id]/read.post.ts

@@ -0,0 +1,18 @@
+/**
+ * POST /api/workshop/dcw/:id/read —— 手动读取 PLC 当前值(读写集成的读半边)。
+ * 驱动读(寄存器解码/节点值)→ 标定 decode → 节点读状态记账 + WS dcw.read 直推。
+ * 读取是被动观测:不受控制暂停/产线运行门控;不支持读的驱动返回 ok:false 说明。
+ */
+import { getRouterParam } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { bindDcwBroadcast, getDcwController } from '@/server/services/workshop/dcw/dcw-controller'
+import { broadcastSceneEvent } from '@/server/services/workshop/scene-events'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  bindDcwBroadcast(broadcastSceneEvent)
+  const id = getRouterParam(event, 'id') ?? ''
+  const read = await getDcwController().readNow(id)
+  return { read }
+})

package/server/api/workshop/ws.ts

@@ -26,6 +26,7 @@ import type { AepEnvelope } from '../../../shared/workshop-protocol'
 import { parseJson } from '../../services/workshop/db/database'
 import { registerScenePeer, unregisterScenePeer } from '../../services/workshop/scene-events'
 import { createLogger } from '../../services/workshop/logger'
+import { retentionSettings } from '../../services/workshop/settings'
 
 const log = createLogger('workshop.ws')
 
@@ -35,8 +36,8 @@ const RING_CAP = 5000
 const RING_BYTES_CAP = 4 * 1024 * 1024
 /** 落库聚合缓冲上限(滞留超限即刷,防库故障时缓冲无限涨) */
 const DB_BUFFER_CAP = 2000
-/** 事件保留期(天;channel_events 周期清理,防磁盘无限涨) */
-const EVENTS_RETENTION_DAYS = Number(process.env.AW_EVENTS_RETENTION_D ?? 7)
+/** 事件保留期(天;retention.events_days,env AW_EVENTS_RETENTION_D 可覆盖) */
+const EVENTS_RETENTION_DAYS = (): number => retentionSettings().events_days
 /** 单 peer 发送预算(字节/秒):超限视为慢消费者断开(1013),客户端重连快照对齐 */
 const PEER_SEND_BUDGET_BYTES = 32 * 1024 * 1024
 
@@ -449,8 +450,9 @@ if (!(hubGlobal as Record<string, unknown>)[RETENTION_TIMER_KEY]) {
   const t = setInterval(() => {
     if (!hub.boundManager) return
     try {
-      const removed = internalsOf(hub.boundManager).deps.repos.channelEvents.sweepRetention(EVENTS_RETENTION_DAYS)
-      if (removed > 0) console.log(`[workshop-ws] 事件保留期清理 ${removed} 行(>${EVENTS_RETENTION_DAYS}d)`)
+      const days = EVENTS_RETENTION_DAYS()
+      const removed = internalsOf(hub.boundManager).deps.repos.channelEvents.sweepRetention(days)
+      if (removed > 0) console.log(`[workshop-ws] 事件保留期清理 ${removed} 行(>${days}d)`)
     }
     catch (err) {
       console.error('[workshop-ws] 事件保留期清理失败:', err)