agentworkshop 0.7.39 → 0.7.41

package/scripts/ui/record.mjs

@@ -0,0 +1,225 @@
+/**
+ * 真实流程录屏 → GIF(README / 文档站用)。
+ *
+ * 为什么不用现成录屏工具:这些 GIF 要展示的是**系统的真实行为**
+ * (Agent 真的在跑、DAQ 数值真的在变),所以必须是一段"操作剧本"驱动真实页面,
+ * 再逐帧采集。所有帧都来自 127.0.0.1:3021 上跑着的真服务,没有任何摆拍。
+ *
+ * 管线: puppeteer 定频截图 → ffmpeg palettegen/paletteuse → 有界 GIF
+ *
+ * 用法: node scripts/ui/record.mjs <story> [--out docs/readme-assets] [--w 1440] [--h 900]
+ *       node scripts/ui/record.mjs --list
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { ensureVisualUser, api, launch, openPage, gotoReady, sleep } from './lib.mjs'
+
+const argv = process.argv.slice(2)
+const arg = (k, d) => {
+  const i = argv.indexOf(`--${k}`)
+  return i >= 0 ? argv[i + 1] : d
+}
+const OUT = arg('out', 'docs/readme-assets')
+const W = Number(arg('w', 1440))
+const H = Number(arg('h', 900))
+const FPS = Number(arg('fps', 12))
+const GIF_W = Number(arg('gifw', 960))
+
+const token = await ensureVisualUser()
+
+/** 找到示范产线的频道(seed-demo.mjs 建的) */
+async function demoChannels() {
+  const r = await api('GET', '/api/workshop/channels', { token })
+  const list = r.data?.channels ?? r.data ?? []
+  return Array.isArray(list) ? list : []
+}
+
+/* ─────────────────────────── 剧本 ─────────────────────────── */
+
+const STORIES = {
+  /** 01 · Agent 团队真实跑一次任务:派发 → 拆解 → 并行执行 → 三个视图收敛 */
+  agents: {
+    title: 'Agent 团队执行任务',
+    async run(page, play) {
+      const chs = await demoChannels()
+      const ch = chs.find(c => c.name === '熔温优化') ?? chs[0]
+      if (!ch) throw new Error('没有可用频道,先跑 scripts/ui/seed-demo.mjs')
+      const cid = ch.channelId ?? ch.id
+      // ⚠️ 路由参数是 **workspaceId**,不是 channelId(/workshop/w/:wsId 里
+      //    channelId 由活动工作区推导)。传 channelId 会落到空壳上。
+      const wsRes = await api('GET', '/api/workshop/workspaces', { token })
+      const wsList = wsRes.data?.workspaces ?? wsRes.data ?? []
+      const wid = (Array.isArray(wsList) ? wsList[0] : null)?.id
+      if (!wid) throw new Error('没有工作区,先跑 scripts/ui/seed-demo.mjs')
+
+      await gotoReady(page, `/workshop/w/${wid}`, { wait: 4500 })
+      await play(1500)
+
+      const goal = '分析 1 号挤出线的熔体温度趋势,给出把温控设定值下调 5°C 的依据与风险。'
+      // 用**和界面同一个 REST 入口**派发任务,而不是往 composer 里模拟打字:
+      // 富文本 composer 的首个 textarea 未必是它本体(踩过:录了 30 秒空时间线),
+      // 而"事件真的在流"才是这段 GIF 要证明的东西。
+      const sent = await api('POST', `/api/workshop/channels/${cid}/tasks`, {
+        token,
+        body: { title: goal, mode: 'goal', fromLabel: 'visual' },
+      })
+      if (sent.code !== 0) console.log('  ⚠ 派发失败:', JSON.stringify(sent).slice(0, 160))
+      await play(9000)
+
+      // 依次切到 Agent lanes / 任务板,展示"同一批事件的不同切面"
+      for (const tab of ['Agent lanes', '任务板', '时间线']) {
+        await page.evaluate((label) => {
+          const el = Array.from(document.querySelectorAll('button, .aw-seg button, [role="tab"]'))
+            .find(b => (b.textContent || '').trim() === label)
+          el?.click()
+        }, tab)
+        await play(tab === '任务板' ? 7000 : 6000)
+      }
+      await play(4000)
+    },
+  },
+
+  /** 02 · 数采实时链路:节点在线、读数跳动、趋势成形 */
+  daq: {
+    title: 'DAQ 实时采集',
+    async run(page, play) {
+      await gotoReady(page, '/daq', { wait: 4500 })
+      await play(6000)
+      // 展开「实时事件」流,展示消息在滚动
+      await page.evaluate(() => {
+        const els = Array.from(document.querySelectorAll('*'))
+        const t = els.find(e => e.children.length === 0 && (e.textContent || '').includes('实时事件'))
+        t?.scrollIntoView({ block: 'center' })
+      })
+      await play(7000)
+      await page.evaluate(() => window.scrollTo({ top: 0, behavior: 'smooth' }))
+      await play(3500)
+    },
+  },
+
+  /** 03 · 产线作业:节点卡片 + 展开一条产线看工艺链 */
+  dcw: {
+    title: '产线作业与写控制',
+    async run(page, play) {
+      await gotoReady(page, '/dcw', { wait: 4500 })
+      await play(4000)
+      await page.evaluate(() => window.scrollBy({ top: 260, behavior: 'smooth' }))
+      await play(4500)
+      await page.evaluate(() => window.scrollBy({ top: -260, behavior: 'smooth' }))
+      await play(3000)
+    },
+  },
+
+  /** 04 · 数字孪生:真实遥测驱动的 3D 产线 */
+  town: {
+    title: '三维数字孪生',
+    async run(page, play) {
+      await gotoReady(page, '/town', { wait: 9000 })
+      await play(9000)
+      // 缓慢平移视角(鼠标拖拽画布中心)
+      const box = await page.evaluate(() => {
+        const c = document.querySelector('canvas')
+        if (!c) return null
+        const r = c.getBoundingClientRect()
+        return { x: r.x + r.width / 2, y: r.y + r.height / 2 }
+      })
+      if (box) {
+        await page.mouse.move(box.x, box.y)
+        await page.mouse.down()
+        for (let i = 0; i < 24; i++) {
+          await page.mouse.move(box.x - i * 6, box.y - i * 1.2)
+          await play(60)
+        }
+        await page.mouse.up()
+      }
+      await play(8000)
+    },
+  },
+
+  /** 05 · 仪表盘:全局 KPI 与趋势 */
+  dashboard: {
+    title: '运行总览仪表盘',
+    async run(page, play) {
+      await gotoReady(page, '/', { wait: 5000 })
+      await play(8000)
+      await page.evaluate(() => window.scrollBy({ top: 420, behavior: 'smooth' }))
+      await play(7000)
+    },
+  },
+
+  /** 06 · 响应式:同一套界面在桌面 / 平板 / 手机上的形态 */
+  responsive: {
+    title: '自适应:桌面 / 平板 / 手机',
+    async run(page, play) {
+      await gotoReady(page, '/daq', { wait: 5000 })
+      await play(2500)
+      const steps = [
+        { w: 1024, h: 768, wait: 2000 },
+        { w: 768, h: 1024, wait: 2000 },
+        { w: 390, h: 844, wait: 2400 },
+      ]
+      for (const s of steps) {
+        await page.setViewport({ width: s.w, height: s.h, deviceScaleFactor: 1 })
+        await play(s.wait)
+      }
+      // 手机上拉开抽屉导航
+      await page.evaluate(() => {
+        document.querySelector('.collapse-btn')?.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+      })
+      await play(3000)
+    },
+  },
+}
+
+// 剧本名 = 第一个**是已知剧本**的位置参数。
+// (不能只判"前一个参数不是 --flag":首位参数的前一个参数是 undefined,
+//  会被误判成"某个 flag 的值",于是永远解析不出剧本名 —— 实测踩过。)
+const storyName = argv.find(a => !a.startsWith('--') && Object.hasOwn(STORIES, a))
+
+if (argv.includes('--list') || !storyName || !STORIES[storyName]) {
+  console.log('可用剧本:')
+  for (const [k, v] of Object.entries(STORIES)) console.log(`  ${k.padEnd(12)} ${v.title}`)
+  process.exit(0)
+}
+
+/* ─────────────────────── 采集 + 合成 ─────────────────────── */
+
+const tmp = path.join('.e2e-shots', 'gif-frames', storyName)
+fs.rmSync(tmp, { recursive: true, force: true })
+fs.mkdirSync(tmp, { recursive: true })
+// 输出目录必须显式建:ffmpeg 不会替你 mkdir,它会以 "Could not open file" 失败,
+// 而 -loglevel error 下错误只出现在 stderr 末尾,很容易被误读成编码参数错误(实测踩过)。
+fs.mkdirSync(OUT, { recursive: true })
+
+const browser = await launch()
+const page = await openPage(browser, { token, dark: true, width: W, height: H, deviceScaleFactor: 1 })
+const errs = []
+page.on('pageerror', e => errs.push(String(e.message).slice(0, 200)))
+
+let n = 0
+let stopped = false
+/** 播放一段"时间":按 FPS 定频采样,长度 = ms */
+async function play(ms) {
+  const frames = Math.max(1, Math.round((ms / 1000) * FPS))
+  for (let i = 0; i < frames && !stopped; i++) {
+    try {
+      await page.screenshot({ path: path.join(tmp, `f${String(n++).padStart(5, '0')}.png`) })
+    }
+    catch { /* 过渡帧丢失可接受 */ }
+    await sleep(Math.round(1000 / FPS))
+  }
+}
+
+console.log(`▶ 录制「${STORIES[storyName].title}」…`)
+await STORIES[storyName].run(page, play)
+stopped = true
+await browser.close()
+console.log(`  帧数 ${n}`)
+
+const gif = path.join(OUT, `${storyName}.gif`)
+const vf = `fps=${FPS},scale=${GIF_W}:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=192:stats_mode=diff[p];[s1][p]paletteuse=dither=bayer:bayer_scale=3:diff_mode=rectangle`
+execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', path.join(tmp, 'f%05d.png'), '-vf', vf, '-loop', '0', gif], { stdio: 'inherit' })
+const size = fs.statSync(gif).size
+console.log(`✔ ${gif} (${(size / 1024 / 1024).toFixed(2)} MB, ${n} 帧)`)
+if (errs.length) console.log('  ⚠ page errors:', errs.slice(0, 4))

package/scripts/ui/seed-admin.mjs

@@ -0,0 +1,68 @@
+/**
+ * 给 admin 账号准备一套可看的演示数据(工作区 + 3 个频道 + 挂载)。
+ * 幂等:已存在就不重复建。admin 是文档里写的管理员账号(admin@awshop.local),
+ * 而演示工作区原本挂在另一个账号下 —— 不补的话 /town 与 /workshop 会是空态。
+ *
+ * ⚠️ 本文件的 api() 是**位置参数** (m, p, body, token);别照抄 lib.mjs 的
+ * options-object 写法 —— 混用会把 {body,token} 整体当成请求体序列化出去,
+ * 服务端 zod 校验失败但外层仍是 200,排查时极具迷惑性(已踩)。
+ */
+const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3021'
+const api = async (m, p, body, token) => {
+  const h = { 'content-type': 'application/json' }
+  if (token) h.authorization = 'Bearer ' + token
+  const r = await fetch(BASE + p, { method: m, headers: h, body: body ? JSON.stringify(body) : undefined })
+  const t = await r.text()
+  try {
+    return JSON.parse(t)
+  }
+  catch {
+    return { code: -1, message: 'HTTP ' + r.status }
+  }
+}
+const login = await api('POST', '/api/users/login', { email: 'admin@awshop.local', password: 'admin123' })
+const token = login.data.token
+console.log('admin:', login.data.user.name, login.data.user.role)
+
+const WANT = [
+  { name: '熔温优化', prompt: '分析熔体温度趋势并优化设定值:读取历史,统计与异常剔除,给出新设定值建议,走 HITL 审批后写入 PLC 并回读校验。', lead: 'melt-lead', workers: ['trend-analyst', 'setpoint-writer'] },
+  { name: '厚度扫描诊断', prompt: '厚度扫描仪多点剖面诊断:定位横向厚度偏差来源,给出模头螺栓调整建议。', lead: 'scan-lead', workers: ['profile-analyst'] },
+  { name: '配方调优', prompt: '配方参数寻优:在工艺窗口内搜索更优参数组合,记录每次试验并给出推荐版本。', lead: 'recipe-lead', workers: ['doe-runner'] },
+]
+
+let wsList = await api('GET', '/api/workshop/workspaces', null, token)
+let list = wsList.data ?? []
+let ws = list.find(w => w.name === '示范产线')
+if (!ws) {
+  const r = await api('POST', '/api/workshop/workspaces', { name: '示范产线' }, token)
+  ws = r.data
+}
+const wsId = ws?.id
+if (!wsId) throw new Error('工作区创建失败: ' + JSON.stringify(wsList).slice(0, 200))
+console.log('workspace:', wsId, ws.name)
+
+const chList = await api('GET', '/api/workshop/channels', null, token)
+const all = chList.data?.channels ?? chList.data ?? []
+for (const spec of WANT) {
+  let ch = (Array.isArray(all) ? all : []).find(c => c.name === spec.name)
+  if (!ch) {
+    const r = await api('POST', '/api/workshop/channels', {
+      name: spec.name,
+      scenarioPrompt: spec.prompt,
+      leadAgent: { name: spec.lead, harness: 'mock', config: { delayMs: 260, streamDemo: true } },
+    }, token)
+    ch = r.data
+    if (!ch) {
+      console.log('  建频道失败', spec.name, JSON.stringify(r).slice(0, 150))
+      continue
+    }
+    for (const w of spec.workers) {
+      await api('POST', `/api/workshop/channels/${ch.channelId ?? ch.id}/agents`, { name: w, harness: 'mock', role: 'worker', config: { delayMs: 300, streamDemo: true } }, token)
+    }
+  }
+  const cid = ch.channelId ?? ch.id
+  await api('POST', `/api/workshop/workspaces/${wsId}/channels/${cid}`, {}, token)
+  console.log('  挂载:', spec.name, cid)
+}
+const after = await api('GET', '/api/workshop/workspaces', null, token)
+console.log('workspaces now:', JSON.stringify(after.data).slice(0, 300))

package/scripts/ui/seed-demo.mjs

@@ -0,0 +1,83 @@
+/**
+ * 视觉走查用示范数据集 —— 用 visual 账号通过公开 REST 建一套「像真产线」的工作区:
+ * 工作区 + 3 个语义化频道(mock harness, 带 streamDemo 流式事件) + 一次真实派发。
+ *
+ * 为什么不复用仓库里已有的 43 个频道:它们是压测遗留的 team-ip16i7gy 之类机读名,
+ * 拿来当 README/GIF 的素材会让截图说不出故事。这里只新增,不改动既有数据。
+ */
+import { ensureVisualUser, api } from './lib.mjs'
+
+const token = await ensureVisualUser()
+
+const CHANNELS = [
+  {
+    name: '熔温优化',
+    scenarioPrompt: '分析熔体温度趋势并优化设定值:读取近 24h 历史,做统计与异常剔除,给出新设定值建议,走 HITL 审批后写入 PLC 并回读校验。',
+    lead: 'melt-lead',
+    workers: [
+      { name: 'trend-analyst', role: 'worker' },
+      { name: 'setpoint-writer', role: 'worker' },
+    ],
+    goal: '分析 1 号挤出线的熔体温度趋势,给出把温控设定值下调 5°C 的依据,并说明风险。',
+  },
+  {
+    name: '厚度扫描诊断',
+    scenarioPrompt: '厚度扫描仪的多点剖面数据诊断:定位横向厚度偏差来源,给出模头螺栓调整建议。',
+    lead: 'scan-lead',
+    workers: [{ name: 'profile-analyst', role: 'worker' }],
+    goal: '诊断 abw16t4v19 的横向厚度剖面偏差,指出偏差最大的点位。',
+  },
+  {
+    name: '配方调优',
+    scenarioPrompt: '配方参数寻优:在工艺窗口内搜索更优参数组合,记录每次试验并给出推荐版本。',
+    lead: 'recipe-lead',
+    workers: [{ name: 'doe-runner', role: 'worker' }],
+    goal: '在工艺窗口内搜索一组更优的牵引速度与冷却水温组合。',
+  },
+]
+
+const existing = await api('GET', '/api/workshop/workspaces', { token })
+const wsList = existing.data?.workspaces ?? existing.data ?? []
+let ws = Array.isArray(wsList) ? wsList.find(w => w.name === '示范产线') : null
+if (!ws) {
+  const r = await api('POST', '/api/workshop/workspaces', { body: { name: '示范产线' }, token })
+  ws = r.data
+}
+const wsId = ws?.id ?? ws?.workspaceId
+if (!wsId) throw new Error('workspace 创建失败: ' + JSON.stringify(existing).slice(0, 300))
+console.log('workspace:', wsId, ws?.name)
+
+const channels = []
+const chList = await api('GET', '/api/workshop/channels', { token })
+const all = chList.data?.channels ?? chList.data ?? []
+for (const spec of CHANNELS) {
+  let ch = (Array.isArray(all) ? all : []).find(c => c.name === spec.name)
+  if (!ch) {
+    const r = await api('POST', '/api/workshop/channels', {
+      body: {
+        name: spec.name,
+        scenarioPrompt: spec.scenarioPrompt,
+        leadAgent: { name: spec.lead, harness: 'mock', config: { delayMs: 260, streamDemo: true } },
+      },
+      token,
+    })
+    ch = r.data
+    if (!ch) {
+      console.log('channel fail', spec.name, JSON.stringify(r).slice(0, 200))
+      continue
+    }
+    const cid = ch.channelId ?? ch.id
+    for (const wk of spec.workers) {
+      await api('POST', `/api/workshop/channels/${cid}/agents`, {
+        body: { name: wk.name, harness: 'mock', role: wk.role, config: { delayMs: 300, streamDemo: true } },
+        token,
+      })
+    }
+  }
+  const cid = ch.channelId ?? ch.id
+  channels.push({ id: cid, name: spec.name, goal: spec.goal })
+  await api('POST', `/api/workshop/workspaces/${wsId}/channels/${cid}`, { token })
+  console.log('mounted channel:', spec.name, cid)
+}
+
+console.log(JSON.stringify({ wsId, channels }, null, 1))

package/scripts/ui/seed-industrial-demo.mjs

@@ -0,0 +1,171 @@
+/**
+ * 工业演示现场布线 —— 对真实 PLC 模拟器(:4010)做一次「可登录即可见」的完整接装:
+ *   ①每台模拟器设备 → 平台节点(DCW 写控 / DAQ 数采,driverConfig 取自模拟器对接导出)
+ *   ②每台设备一个数字孪生模型(modelRef=设备模型库)并把节点双向绑定到孪生
+ *   ③产线+产品+配方(全量程窗)并开跑 → 数采在活动批次内真实采样
+ *   ④逐节点 test-driver 真连通验证 + 一次受治理参数写→回读 + 数采样本增长
+ * 幂等:按「演示」标记清理上一次的演示线,再重建。
+ * 运行: AW_BASE=http://127.0.0.1:3001 node scripts/ui/seed-industrial-demo.mjs
+ */
+const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3001'
+const SIM = process.env.E2E_SIM_API ?? 'http://127.0.0.1:4010'
+const ADMIN = { email: process.env.E2E_USER ?? 'admin@awshop.local', password: process.env.E2E_PASS ?? 'admin123' }
+
+let failed = 0
+const check = (name, ok, detail = '') => {
+  console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok) failed++
+}
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+const login = await fetch(`${BASE}/api/users/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(ADMIN) }).then(r => r.json())
+const token = login.data?.token
+check('管理员登录', !!token, `${ADMIN.email} ${login.message ?? ''}`)
+if (!token) process.exit(1)
+const H = { 'content-type': 'application/json', 'authorization': `Bearer ${token}` }
+const api = async (m, u, b) => (await fetch(BASE + u, { method: m, headers: H, body: b ? JSON.stringify(b) : undefined })).json()
+// 列表解包:data 可能是数组或 {lines/nodes/twins: [...]}(各路由形状不一)
+const arr = (d, key) => (Array.isArray(d) ? d : d?.[key] ?? d?.nodes ?? d?.lines ?? d?.twins ?? [])
+const sim = async (m, u, b) => (await fetch(SIM + u, { method: m, headers: { 'content-type': 'application/json' }, body: b ? JSON.stringify(b) : undefined })).json()
+
+// ── ① 模拟器设备清单(真实五协议) ──
+const devices = (await sim('GET', '/api/nodes')).data ?? []
+check('PLC 模拟器在线', devices.length > 0, `${devices.length} 台设备: ${devices.map(d => d.name).join(' / ')}`)
+
+// ── ② 清理上一轮演示实体(按「演示」标记) ──
+const oldLines = arr((await api('GET', '/api/workshop/dcw/lines')).data, 'lines')
+for (const l of oldLines.filter(x => x.name.startsWith('演示线'))) {
+  await api('DELETE', `/api/workshop/dcw/lines/${l.id}?purge=1`)
+}
+const oldTwins = arr((await api('GET', '/api/workshop/device-twins')).data, 'twins')
+for (const n of arr((await api('GET', '/api/workshop/daq')).data, 'nodes').filter(x => x.name.startsWith('演示·'))) {
+  await api('DELETE', `/api/workshop/daq/${n.id}`)
+}
+for (const n of arr((await api('GET', '/api/workshop/dcw')).data, 'nodes').filter(x => x.name.startsWith('演示·'))) {
+  await api('DELETE', `/api/workshop/dcw/${n.id}`)
+}
+for (const t of oldTwins.filter(x => x.name.startsWith('演示·'))) {
+  await api('DELETE', `/api/workshop/device-twins/${t.id}`)
+}
+console.log('  · 旧演示实体已清理')
+
+// ── ③ 逐设备建节点(SP→DCW 写控;标量 PV→DAQ 数采;driverConfig 取自模拟器导出) ──
+// 模型映射:按设备语义挑数字孪生模型库里的模型
+const MODEL_OF = {
+  'Coating Oven PLC': 'caster', 'Remote RTU Temp Slave': 'power-cabinet',
+  'OPC UA Temp Controller': 'extruder', 'MQTT Temp Sensor': 'device-scanner',
+  'HTTP Flow Meter': 'pump',
+}
+const isSp = s => /SP/i.test(s.signal ?? '') || /^Set/i.test(s.signal ?? '')
+const results = []
+let lineIx = 0
+const twins = []
+for (const dev of devices) {
+  const exp = (await sim('GET', `/api/nodes/${dev.id}/export`)).data
+  const items = exp?.items ?? []
+  const spItem = items.find(i => isSp(i)) ?? null
+  const pvItems = items.filter(i => i !== spItem && (i.format ?? 'scalar') === 'scalar')
+  if (!spItem && pvItems.length === 0) continue
+  const modelKey = MODEL_OF[dev.name] ?? 'device-console'
+  const twin = (await api('POST', '/api/workshop/device-twins', {
+    name: `演示·${dev.name}`,
+    modelRef: modelKey,
+    posX: -14 + lineIx * 7,
+    posZ: 6 + (lineIx % 2) * 5,
+    rotationY: 0,
+  })).data?.twin
+  if (!twin) {
+    check(`孪生创建 ${dev.name}`, false)
+    continue
+  }
+  twins.push(twin)
+
+  let hostLine = null
+  const bindNode = async (nodeId) => {
+    const r = await api('POST', `/api/workshop/dcw/${nodeId}/bind`, { deviceId: twin.id }).catch(() => null)
+    return r?.code === 0
+  }
+  const bindDaq = async (nodeId) => {
+    const r = await api('POST', `/api/workshop/daq/${nodeId}/bind`, { deviceId: twin.id }).catch(() => null)
+    return r?.code === 0
+  }
+
+  // SP → 写控节点 + 自成产线(开跑后本线批次活动,数采采样门放行)
+  if (spItem) {
+    lineIx++
+    const line = (await api('POST', '/api/workshop/dcw/lines', { name: `演示线${lineIx}·${dev.name}` })).data?.line
+    const product = (await api('POST', '/api/workshop/dcw/products', { lineId: line.id, name: `演示产品${lineIx}` })).data?.product
+    hostLine = line
+    const cfg = spItem.driverConfig
+    const dcw = (await api('POST', '/api/workshop/dcw', {
+      templateRef: 'dcw-temp-sp', name: `演示·${dev.name}·${spItem.signal}`,
+      driver: spItem.driver, driverConfig: cfg,
+      unit: spItem.unit ?? '℃', decimals: spItem.decimals ?? 1,
+      min: spItem.min ?? 0, max: spItem.max ?? 300,
+      readIntervalMs: 3000, lineId: line.id, semantics: `模拟器设备「${dev.name}」的 ${spItem.signal}(真实 ${spItem.driver} 写控链路)`,
+    })).data?.node
+    const bindOk = await bindNode(dcw.id)
+    check(`DCW 节点+孪生绑定 ${dev.name}`, !!dcw?.id && bindOk, `${dcw.id} ↔ twin ${twin.id}(${modelKey})`)
+    const recipe = (await api('POST', '/api/workshop/dcw/recipes', {
+      productId: product.id, name: `演示配方${lineIx}`,
+      params: [{ nodeId: dcw.id, value: dev.signals?.find(x => x.id === spItem.signal)?.value ?? (Number(spItem.min ?? 0) + Number(spItem.max ?? 300)) / 2, min: spItem.min ?? 0, max: spItem.max ?? 300 }],
+    })).data?.recipe
+    const st = (await api('POST', `/api/workshop/dcw/lines/${line.id}/start`, { recipeId: recipe.id }))
+    check(`产线开跑 ${line.name}`, !!st.data?.run?.id)
+    results.push({ dev, dcw, line, spItem })
+  }
+
+  // 标量 PV → 数采节点(挂到本线或第一条既有演示线)
+  for (const pv of pvItems) {
+    const cfg = pv.driverConfig
+    const daq = (await api('POST', '/api/workshop/daq', {
+      templateRef: 'daq-temp-tc', name: `演示·${dev.name}·${pv.signal}`,
+      driver: pv.driver, driverConfig: cfg,
+      unit: pv.unit ?? '', min: pv.min ?? 0, max: pv.max ?? 400,
+      lineId: hostLine?.id ?? '', intervalMs: 2000, publishIntervalMs: 0,
+      semantics: `模拟器设备「${dev.name}」的 ${pv.signal}(真实 ${pv.driver} 采样链路)`,
+    })).data?.node
+    if (!daq) {
+      check(`DAQ 节点 ${dev.name}·${pv.signal}`, false)
+      continue
+    }
+    if (hostLine?.id) await bindDaq(daq.id)
+    results.push({ dev, daq, pvItem: pv })
+  }
+}
+
+// 卫星数采补绑定(无 SP 设备的 DAQ 挂到第一条演示线,否则不采样)
+const firstLine = arr((await api('GET', '/api/workshop/dcw/lines')).data, 'lines').find(l => l.name.startsWith('演示线'))
+if (firstLine) {
+  const allDaq = arr((await api('GET', '/api/workshop/daq')).data, 'nodes')
+  for (const n of allDaq.filter(x => x.name.startsWith('演示·') && !x.lineId)) {
+    await api('PATCH', `/api/workshop/daq/${n.id}`, { lineId: firstLine.id })
+    await bindDaqSoft(n.id)
+  }
+  async function bindDaqSoft(nodeId) {
+    const twin0 = twins[0]
+    if (twin0) await api('POST', `/api/workshop/daq/${nodeId}/bind`, { deviceId: twin0.id }).catch(() => {})
+  }
+}
+// ── ④ 真连通验证:逐节点 test-driver ──
+const allDcw = arr((await api('GET', '/api/workshop/dcw')).data, 'nodes').filter(n => n.name.startsWith('演示·'))
+let connOk = 0
+for (const n of allDcw.filter(x => x.driver !== 'mock')) {
+  const t = await api('POST', `/api/workshop/dcw/${n.id}/test`)
+  connOk += t.data?.test?.ok === true ? 1 : 0
+}
+check('逐节点真连通(test-driver)', connOk === allDcw.filter(x => x.driver !== 'mock').length, `${connOk}/${allDcw.filter(x => x.driver !== 'mock').length} 台真实驱动连通`)
+
+// ── ⑤ 数采样本增长(活动批次内真实采样) ──
+await sleep(9000)
+const allDaq = arr((await api('GET', '/api/workshop/daq')).data, 'nodes').filter(n => n.name.startsWith('演示·'))
+let sampling = 0
+for (const n of allDaq) {
+  const s = await api('GET', `/api/workshop/daq/${n.id}/samples?limit=5`)
+  const pts = s.data?.points ?? []
+  sampling += pts.length > 0 ? 1 : 0
+}
+check('数采真实采样', sampling === allDaq.length, `${sampling}/${allDaq.length} 通道有样本(9s 窗)`)
+
+console.log(`\n${failed === 0 ? '✅ 演示现场就绪' : `❌ ${failed} 项失败`}`)
+process.exit(failed === 0 ? 0 : 1)

package/scripts/ui/shot-hero.mjs

@@ -0,0 +1,25 @@
+/**
+ * 把 docs/readme-assets/hero.html 渲成 2 倍图 hero.png(README 首屏).
+ * hero.html 里的截图是同目录下的真实运行截图(town.png / daq.png),
+ * 所以出图前必须先跑 scripts/ui/shots.mjs 更新它们。
+ */
+import puppeteer from 'puppeteer-core'
+import path from 'node:path'
+import { CHROME } from './lib.mjs'
+
+const dir = path.resolve('docs/readme-assets')
+const browser = await puppeteer.launch({
+  executablePath: CHROME,
+  headless: true,
+  args: ['--no-sandbox', '--force-color-profile=srgb', '--font-render-hinting=none'],
+  defaultViewport: { width: 1300, height: 520, deviceScaleFactor: 2 },
+})
+const page = await browser.newPage()
+const errs = []
+page.on('pageerror', e => errs.push(e.message))
+page.on('requestfailed', r => errs.push('failed: ' + r.url()))
+await page.goto('file:///' + path.join(dir, 'hero.html').replace(/\\/g, '/'), { waitUntil: 'networkidle0' })
+await new Promise(r => setTimeout(r, 400))
+await page.screenshot({ path: path.join(dir, 'hero.png'), type: 'png' })
+console.log('hero.png written', errs.length ? '⚠ ' + errs.join(' | ') : '')
+await browser.close()

package/scripts/ui/shots.mjs

@@ -0,0 +1,75 @@
+/**
+ * 全站视觉走查截图 —— 视口 × 主题 矩阵批量出图。
+ *   node scripts/ui/shots.mjs [--out .e2e-shots/new/base] [--theme dark|light|both]
+ *                             [--vp 1440x900] [--routes workshop,daq,...] [--wait 6000]
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { ensureVisualUser, launch, openPage, gotoReady, ROUTES } from './lib.mjs'
+
+const argv = process.argv.slice(2)
+const arg = (k, d) => {
+  const i = argv.indexOf(`--${k}`)
+  return i >= 0 ? argv[i + 1] : d
+}
+const OUT = arg('out', '.e2e-shots/new/base')
+const THEME = arg('theme', 'dark')
+const VP = arg('vp', '1440x900')
+const ONLY = arg('routes', '')
+const WAIT = Number(arg('wait', 6500))
+const [WV, HV] = VP.split('x').map(Number)
+
+const themes = THEME === 'both' ? [true, false] : [THEME === 'dark']
+// 'all' 与不传等价:两个验收脚本的参数语义必须一致,
+// 否则 `--routes all` 会被当成"找一个名叫 all 的路由"而筛出空集(实测踩过:
+// 跑完只留下一份空报告,还打印了 "saved")。
+const picks = (!ONLY || ONLY === 'all')
+  ? ROUTES
+  : ROUTES.filter(r => ONLY.split(',').includes(r.name))
+
+fs.mkdirSync(OUT, { recursive: true })
+const token = await ensureVisualUser()
+const browser = await launch({ width: WV, height: HV })
+const report = []
+
+for (const dark of themes) {
+  for (const r of picks) {
+    const page = await openPage(browser, { token, dark, width: WV, height: HV })
+    const errs = []
+    const consoleErrs = []
+    page.on('pageerror', e => errs.push(String(e.message).slice(0, 200)))
+    page.on('console', (m) => {
+      if (m.type() === 'error') consoleErrs.push(m.text().slice(0, 200))
+    })
+    try {
+      await gotoReady(page, r.path, { wait: WAIT })
+      const geo = await page.evaluate(() => {
+        const de = document.documentElement
+        return {
+          scrollW: de.scrollWidth,
+          clientW: de.clientWidth,
+          scrollH: de.scrollHeight,
+          clientH: de.clientHeight,
+          url: location.pathname,
+        }
+      })
+      const file = path.join(OUT, `${dark ? 'dark' : 'light'}__${r.name}.png`)
+      await page.screenshot({ path: file })
+      report.push({
+        route: r.name, path: r.path, theme: dark ? 'dark' : 'light',
+        landed: geo.url, overflowX: geo.scrollW - geo.clientW,
+        scrollH: geo.scrollH, pageErrors: errs, consoleErrors: consoleErrs.slice(0, 3), file,
+      })
+      console.log(`  ${dark ? 'dark ' : 'light'} ${r.name.padEnd(12)} overflowX=${geo.scrollW - geo.clientW} landed=${geo.url} errs=${errs.length}`)
+    }
+    catch (e) {
+      report.push({ route: r.name, theme: dark ? 'dark' : 'light', error: String(e.message).slice(0, 200) })
+      console.log(`  FAIL ${r.name}: ${String(e.message).slice(0, 120)}`)
+    }
+    await page.close()
+  }
+}
+
+fs.writeFileSync(path.join(OUT, '_report.json'), JSON.stringify(report, null, 2))
+await browser.close()
+console.log('\nsaved ->', OUT)

package/scripts/ui/sim-ui-shot.mjs

@@ -0,0 +1,16 @@
+import puppeteer from 'puppeteer-core'
+import { CHROME, sleep } from './lib.mjs'
+import fs from 'node:fs'
+
+fs.mkdirSync('.e2e-shots/admin', { recursive: true })
+const b = await puppeteer.launch({ executablePath: CHROME, headless: true, args: ['--no-sandbox', '--no-proxy-server'], defaultViewport: { width: 1600, height: 1000, deviceScaleFactor: 2 } })
+const p = await b.newPage()
+const errs = []
+p.on('pageerror', e => errs.push(String(e.message).slice(0, 140)))
+await p.goto('http://127.0.0.1:4010/', { waitUntil: 'networkidle0', timeout: 60000 })
+await sleep(6000)
+const info = await p.evaluate(() => ({ title: document.title, text: document.body.innerText.replace(/\s+/g, ' ').slice(0, 260), nodes: document.querySelectorAll('*').length }))
+console.log('sim UI:', JSON.stringify(info))
+console.log('errs:', errs.length, errs.slice(0, 3))
+await p.screenshot({ path: '.e2e-shots/admin/00-plc-simulator.png' })
+await b.close()