agentworkshop 0.7.38 → 0.7.40

package/scripts/ui/audit-layout.mjs

@@ -0,0 +1,301 @@
+/**
+ * 自适应布局审计 —— 用真实浏览器几何量测量,而不是目测。
+ *
+ * 检查项(每项都能给出"哪个元素、差多少像素"的硬证据):
+ *  1. 横向溢出:文档级 + 元素级(右边缘越界 / 12px 内可滚动容器豁免)
+ *  2. 内容裁切:overflow:hidden 且 scrollWidth/scrollHeight 超出(文字被切)
+ *  3. 元素重叠:同一层可见块级元素的矩形相交(排除父子/包含关系)
+ *  4. 触摸目标:移动端可点击元素 < 32×32(或 < 40×40 的纯图标按钮)
+ *  5. 字号下限:正文 < 13px、标签 < 11px
+ *  6. 对比度:遍历文本节点,用实际渲染色(含半透明叠加)算 WCAG 比值
+ *  7. 视口外固定元素:fixed/sticky 元素超出可视区
+ *
+ * 用法:node scripts/ui/audit-layout.mjs --vp 390x844,768x1024 --routes all --theme both
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { ensureVisualUser, launch, openPage, gotoReady, ROUTES, VIEWPORTS } 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 VP_ARG = arg('vp', '')
+const ROUTE_ARG = arg('routes', 'all')
+const THEME = arg('theme', 'both')
+const OUT = arg('out', '.e2e-shots/new/audit')
+const WAIT = Number(arg('wait', 6500))
+
+const vps = VP_ARG
+  ? VP_ARG.split(',').map((s) => {
+      const [w, h] = s.split('x').map(Number)
+      const hit = VIEWPORTS.find(v => v.width === w && v.height === h)
+      return hit ?? { name: `${w}x${h}`, width: w, height: h, label: `${w}×${h}` }
+    })
+  : VIEWPORTS
+const routes = ROUTE_ARG === 'all' ? ROUTES : ROUTES.filter(r => ROUTE_ARG.split(',').includes(r.name))
+const themes = THEME === 'both' ? [true, false] : [THEME === 'dark']
+
+/** 注入到页面里的审计函数(必须是自包含的:序列化后无法访问外部作用域) */
+const AUDIT_FN = function () {
+  const VW = window.innerWidth
+  const VH = window.innerHeight
+  const issues = []
+
+  const describe = (el) => {
+    if (!el) return '?'
+    const id = el.id ? '#' + el.id : ''
+    const cls = (el.className && typeof el.className === 'string')
+      ? '.' + el.className.trim().split(/\s+/).slice(0, 3).join('.')
+      : ''
+    const attr = el.getAttribute?.('data-testid') ? `[data-testid=${el.getAttribute('data-testid')}]` : ''
+    return `${el.tagName.toLowerCase()}${id}${cls}${attr}`
+  }
+  const text = el => (el.innerText || el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 60)
+  const rect = el => el.getBoundingClientRect()
+  const visible = (el) => {
+    const r = rect(el)
+    if (r.width < 1 || r.height < 1) return false
+    const cs = getComputedStyle(el)
+    if (cs.visibility === 'hidden' || cs.display === 'none' || Number(cs.opacity) < 0.05) return false
+    if (el.closest('[aria-hidden="true"]')) return false
+    return true
+  }
+  /** 元素是否位于某个可横向滚动的祖先里(那种"越界"是设计,不是缺陷) */
+  const inScroller = (el) => {
+    let p = el.parentElement
+    while (p && p !== document.body) {
+      const cs = getComputedStyle(p)
+      if (cs.overflowX === 'auto' || cs.overflowX === 'scroll' || cs.overflowX === 'hidden') return p
+      p = p.parentElement
+    }
+    return null
+  }
+
+  // 1. 文档级横向溢出
+  const de = document.documentElement
+  if (de.scrollWidth - de.clientWidth > 1) {
+    issues.push({ kind: 'doc-overflow-x', px: de.scrollWidth - de.clientWidth, detail: 'document' })
+  }
+
+  const all = Array.from(document.querySelectorAll('body *'))
+  for (const el of all) {
+    if (!visible(el)) continue
+    const cs = getComputedStyle(el)
+    const r = rect(el)
+
+    // 2. 元素级右越界(排除在滚动容器内 / 明确的装饰层)
+    const oe = inScroller(el)
+    if (!oe && r.right > VW + 2 && cs.position !== 'fixed') {
+      issues.push({
+        kind: 'el-overflow-right', el: describe(el), text: text(el),
+        right: Math.round(r.right), vw: VW, over: Math.round(r.right - VW),
+      })
+    }
+    if (!oe && r.left < -2 && cs.position !== 'fixed') {
+      issues.push({ kind: 'el-overflow-left', el: describe(el), text: text(el), left: Math.round(r.left) })
+    }
+
+    // 3. 内容裁切(只报"有文字却被切")
+    const clipsX = cs.overflowX === 'hidden' && el.scrollWidth > el.clientWidth + 2
+    const clipsY = cs.overflowY === 'hidden' && el.scrollHeight > el.clientHeight + 2
+    if ((clipsX || clipsY) && (el.textContent || '').trim().length > 4 && el.children.length === 0) {
+      issues.push({
+        kind: 'text-clipped', el: describe(el), text: text(el),
+        axis: clipsX ? 'x' : 'y',
+        need: clipsX ? el.scrollWidth : el.scrollHeight,
+        have: clipsX ? el.clientWidth : el.clientHeight,
+      })
+    }
+
+    // 5. 字号
+    if ((el.textContent || '').trim().length > 1 && el.children.length === 0) {
+      const fs = parseFloat(cs.fontSize)
+      if (fs && fs < 11) {
+        issues.push({ kind: 'font-too-small', el: describe(el), text: text(el), px: fs })
+      }
+    }
+
+    // 4. 触摸目标(仅移动端视口)
+    if (VW <= 900) {
+      const clickable = el.matches('button, a[href], [role="button"], input[type="checkbox"], .ant-switch, .ant-segmented-item')
+      if (clickable && el.children.length === 0 && (r.width < 30 || r.height < 30)) {
+        issues.push({
+          kind: 'touch-target-small', el: describe(el), text: text(el),
+          w: Math.round(r.width), h: Math.round(r.height),
+        })
+      }
+    }
+  }
+
+  // 6. 对比度(文本叶子节点)
+  const parseColor = (s) => {
+    const m = s.match(/rgba?\(([^)]+)\)/)
+    if (!m) return null
+    const p = m[1].split(',').map(Number)
+    return { r: p[0], g: p[1], b: p[2], a: p[3] === undefined ? 1 : p[3] }
+  }
+  const over = (fg, bg) => ({
+    r: fg.r * fg.a + bg.r * (1 - fg.a),
+    g: fg.g * fg.a + bg.g * (1 - fg.a),
+    b: fg.b * fg.a + bg.b * (1 - fg.a),
+    a: 1,
+  })
+  const effBg = (el) => {
+    let p = el
+    let acc = null
+    while (p && p !== document.documentElement.parentElement) {
+      const c = parseColor(getComputedStyle(p).backgroundColor)
+      if (c && c.a > 0.01) acc = acc ? over(acc, c) : c
+      if (acc && acc.a >= 0.999) break
+      if (c && c.a >= 0.999) break
+      p = p.parentElement
+    }
+    if (!acc) acc = { r: 255, g: 255, b: 255, a: 1 }
+    return acc
+  }
+  const lum = (c) => {
+    const f = (v) => {
+      const x = v / 255
+      return x <= 0.03928 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4
+    }
+    return 0.2126 * f(c.r) + 0.7152 * f(c.g) + 0.0722 * f(c.b)
+  }
+  const ratio = (a, b) => {
+    const l1 = lum(a), l2 = lum(b)
+    return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)
+  }
+  const seen = new Set()
+  let contrastChecked = 0
+  let contrastWorst = { ratio: 99, el: '', text: '', px: 0 }
+  for (const el of all) {
+    if (el.children.length > 0) continue
+    const t = (el.textContent || '').trim()
+    if (t.length < 2 || !visible(el)) continue
+    const cs = getComputedStyle(el)
+    const fg = parseColor(cs.color)
+    if (!fg) continue
+    const bg = effBg(el)
+    const cr = ratio(over(fg, bg), bg)
+    const fs = parseFloat(cs.fontSize) || 14
+    const bold = Number(cs.fontWeight) >= 700
+    const large = fs >= 24 || (fs >= 18.66 && bold)
+    const need = large ? 3 : 4.5
+    contrastChecked++
+    if (cr < contrastWorst.ratio) {
+      contrastWorst = { ratio: +cr.toFixed(2), el: describe(el), text: t.slice(0, 40), px: fs }
+    }
+    if (cr < need) {
+      const key = describe(el) + t.slice(0, 12)
+      if (seen.has(key)) continue
+      seen.add(key)
+      issues.push({
+        kind: 'contrast', el: describe(el), text: t.slice(0, 40),
+        ratio: +cr.toFixed(2), need, px: fs,
+      })
+    }
+  }
+
+  // 7. 重叠:同层可见块级元素矩形相交
+  const blocks = all.filter((el) => {
+    if (!visible(el)) return false
+    const cs = getComputedStyle(el)
+    if (cs.position === 'fixed' || cs.position === 'absolute') return false
+    const d = cs.display
+    if (d !== 'block' && d !== 'flex' && d !== 'grid' && d !== 'list-item') return false
+    const r = rect(el)
+    return r.width > 24 && r.height > 18
+  })
+  let overlaps = 0
+  const overlapSamples = []
+  for (let i = 0; i < blocks.length; i++) {
+    for (let j = i + 1; j < blocks.length; j++) {
+      const a = blocks[i], b = blocks[j]
+      if (a.contains(b) || b.contains(a)) continue
+      const ra = rect(a), rb = rect(b)
+      const ox = Math.min(ra.right, rb.right) - Math.max(ra.left, rb.left)
+      const oy = Math.min(ra.bottom, rb.bottom) - Math.max(ra.top, rb.top)
+      if (ox > 6 && oy > 6) {
+        const areaA = ra.width * ra.height, areaB = rb.width * rb.height
+        const ov = ox * oy
+        // 只报"显著遮盖":重叠面积超过较小元素的 25%
+        if (ov > Math.min(areaA, areaB) * 0.25) {
+          overlaps++
+          if (overlapSamples.length < 8) {
+            overlapSamples.push({
+              a: describe(a), b: describe(b), ox: Math.round(ox), oy: Math.round(oy),
+            })
+          }
+        }
+      }
+    }
+  }
+  if (overlaps) issues.push({ kind: 'overlap', count: overlaps, samples: overlapSamples })
+
+  // 8. fixed/sticky 越界
+  for (const el of all) {
+    const cs = getComputedStyle(el)
+    if (cs.position !== 'fixed' && cs.position !== 'sticky') continue
+    if (!visible(el)) continue
+    const r = rect(el)
+    if (r.right > VW + 2 || r.left < -2) {
+      issues.push({
+        kind: 'fixed-out-of-view', el: describe(el), text: text(el),
+        left: Math.round(r.left), right: Math.round(r.right), vw: VW,
+      })
+    }
+  }
+
+  const byKind = {}
+  for (const i of issues) byKind[i.kind] = (byKind[i.kind] || 0) + 1
+
+  return {
+    vw: VW, vh: VH,
+    scrollW: de.scrollWidth, scrollH: de.scrollHeight,
+    counts: byKind,
+    total: issues.length,
+    contrastChecked,
+    contrastWorst,
+    issues: issues.slice(0, 120),
+    bom: {
+      sidebarW: Math.round(document.querySelector('.app-sidebar, aside')?.getBoundingClientRect().width ?? 0),
+      headerH: Math.round(document.querySelector('.app-header, header')?.getBoundingClientRect().height ?? 0),
+      contentLeft: Math.round(document.querySelector('.app-content')?.getBoundingClientRect().left ?? 0),
+    },
+  }
+}
+
+fs.mkdirSync(OUT, { recursive: true })
+const token = await ensureVisualUser()
+const browser = await launch()
+const rows = []
+for (const vp of vps) {
+  for (const dark of themes) {
+    for (const r of routes) {
+      const page = await openPage(browser, { token, dark, width: vp.width, height: vp.height, deviceScaleFactor: 1 })
+      const errs = []
+      page.on('pageerror', e => errs.push(String(e.message).slice(0, 160)))
+      try {
+        await gotoReady(page, r.path, { wait: WAIT })
+        const res = await page.evaluate(AUDIT_FN)
+        res.route = r.name
+        res.path = r.path
+        res.vp = vp.name
+        res.theme = dark ? 'dark' : 'light'
+        res.pageErrors = errs
+        rows.push(res)
+        const c = res.counts
+        console.log(`${vp.name.padEnd(16)} ${(dark ? 'dark' : 'light').padEnd(5)} ${r.name.padEnd(12)} total=${String(res.total).padStart(3)} ${JSON.stringify(c)}`)
+      }
+      catch (e) {
+        rows.push({ route: r.name, vp: vp.name, theme: dark ? 'dark' : 'light', error: String(e.message).slice(0, 160) })
+        console.log(`${vp.name} ${r.name} FAIL ${String(e.message).slice(0, 100)}`)
+      }
+      await page.close()
+    }
+  }
+}
+await browser.close()
+fs.writeFileSync(path.join(OUT, 'audit.json'), JSON.stringify(rows, null, 2))
+console.log('\n->', path.join(OUT, 'audit.json'))

package/scripts/ui/bump-microfont.mjs

@@ -0,0 +1,39 @@
+/**
+ * 把工作坊组件里 8–9px 的微字统一抬到 10px(桌面档的"铭牌地板")。
+ *
+ * 为什么要机械扫而不是逐个改:这些值散落在 13 个组件里、且只有**渲染到**才会被
+ * 审计抓到(所以"没被报出来"不等于"不存在" —— 频道会话台根本不在审计矩阵里)。
+ * 8–9px 在任何视距下都读不了,统一到 10px 既过门槛,又不改变布局
+ * (它们全是行内标签,容器本来就允许换行)。
+ *
+ * 用法: node scripts/ui/bump-microfont.mjs [--dry]
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+const dry = process.argv.includes('--dry')
+const root = 'app/components/workshop'
+const files = []
+const walk = (dir) => {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name)
+    if (e.isDirectory()) walk(p)
+    else if (/\.(vue|ts)$/.test(e.name)) files.push(p)
+  }
+}
+walk(root)
+
+let total = 0
+for (const f of files) {
+  const before = fs.readFileSync(f, 'utf8')
+  const after = before
+    .replace(/font-size: 8px/g, 'font-size: 10px')
+    .replace(/font-size: 9px/g, 'font-size: 10px')
+  if (after !== before) {
+    const n = (before.match(/font-size: (8|9)px/g) || []).length
+    total += n
+    if (!dry) fs.writeFileSync(f, after)
+    console.log((dry ? '[dry] ' : '') + f.replace(/\\/g, '/') + ' -> ' + n)
+  }
+}
+console.log((dry ? '[dry] would bump ' : 'bumped ') + total + ' rules')

package/scripts/ui/lib.mjs

@@ -0,0 +1,198 @@
+/**
+ * UI 视觉走查公共库 —— 真实浏览器(puppeteer-core + 本机 Chrome)驱动的
+ * 截图 / 自适应审计 / 录屏(GIF)统一入口。
+ *
+ * 为什么集中在一处:此前 20+ 个 _dbg-*.mjs 各写一遍 launch/login/screenshot,
+ * 浏览器路径、登录方式、等待策略各不一致,改一处要改二十处。这里收敛为
+ * 一个可复用对象(huashu-design「可复用优先」+ 项目 hygiene 要求)。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import puppeteer from 'puppeteer-core'
+
+export const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3021'
+export const CHROME = process.env.AW_CHROME
+  ?? 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
+
+export const VISUAL_USER = {
+  name: 'visual',
+  email: 'visual@awshop.local',
+  password: 'Visual2026',
+}
+
+export const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+/** 站点全部页面(与 app/pages 一一对应) —— 自适应审计矩阵的行 */
+export const ROUTES = [
+  { path: '/', name: 'dashboard', title: '仪表盘' },
+  { path: '/workshop', name: 'workshop', title: 'Agent 工作台' },
+  { path: '/workshop/agents', name: 'agents', title: 'Agent 管理' },
+  { path: '/workshop/teams', name: 'teams', title: '团队/频道' },
+  { path: '/workshop/channel-templates', name: 'templates', title: '频道模板' },
+  { path: '/monitor', name: 'monitor', title: '实时监控 & HITL' },
+  { path: '/daq', name: 'daq', title: '数采中心' },
+  { path: '/dcw', name: 'dcw', title: '产线作业' },
+  { path: '/aml', name: 'aml', title: '自动建模实验室' },
+  { path: '/town', name: 'town', title: '数字孪生' },
+  { path: '/logs', name: 'logs', title: '审计日志' },
+  { path: '/permissions', name: 'permissions', title: '产线权限' },
+  { path: '/plugins', name: 'plugins', title: '插件' },
+  { path: '/settings', name: 'settings', title: '设置' },
+  { path: '/tokens', name: 'tokens', title: 'API Token' },
+  { path: '/users', name: 'users', title: '用户' },
+]
+
+/** 自适应验收视口矩阵:从 iPhone SE 到超宽屏,含横屏与平板 */
+export const VIEWPORTS = [
+  { name: 'xs-320', width: 320, height: 720, label: 'iPhone SE(竖)' },
+  { name: 'sm-390', width: 390, height: 844, label: 'iPhone 14(竖)' },
+  { name: 'mobile-land-844', width: 844, height: 390, label: '手机横屏' },
+  { name: 'tablet-768', width: 768, height: 1024, label: 'iPad(竖)' },
+  { name: 'laptop-1280', width: 1280, height: 800, label: '笔记本' },
+  { name: 'desktop-1440', width: 1440, height: 900, label: '桌面' },
+  { name: 'wide-1920', width: 1920, height: 1080, label: '宽屏' },
+]
+
+/** REST 调用(JSON envelope 解包) */
+export async function api(method, endpoint, { body, token } = {}) {
+  const headers = { 'content-type': 'application/json' }
+  if (token) headers.authorization = `Bearer ${token}`
+  const res = await fetch(`${BASE}${endpoint}`, {
+    method,
+    headers,
+    body: body === undefined ? undefined : JSON.stringify(body),
+  })
+  const text = await res.text()
+  try {
+    return JSON.parse(text)
+  }
+  catch {
+    return { code: -1, message: `HTTP ${res.status}: ${text.slice(0, 200)}`, data: null }
+  }
+}
+
+/** 确保存在一个可登录的视觉走查账号(admin 角色,便于看到全部页面真实数据) */
+export async function ensureVisualUser() {
+  let login = await api('POST', '/api/users/login', {
+    body: { email: VISUAL_USER.email, password: VISUAL_USER.password },
+  })
+  if (login.code === 0 && login.data?.token) return login.data.token
+
+  const reg = await api('POST', '/api/users/register', {
+    body: { name: VISUAL_USER.name, email: VISUAL_USER.email, password: VISUAL_USER.password },
+  })
+  if (reg.code === 0 && reg.data?.token) return reg.data.token
+
+  // 已存在但密码不同 → 直接改库(仅测试种子用途)
+  const { DatabaseSync } = await import('node:sqlite')
+  const db = new DatabaseSync('.AgentWorkShop/data/users.sqlite')
+  db.prepare('update users set role=\'admin\', status=\'active\' where email=?').run(VISUAL_USER.email)
+  db.close()
+  login = await api('POST', '/api/users/login', {
+    body: { email: VISUAL_USER.email, password: VISUAL_USER.password },
+  })
+  if (login.code === 0 && login.data?.token) return login.data.token
+  throw new Error(`无法取得视觉走查账号 token: ${login.message}`)
+}
+
+/** 把账号提升为 admin(测试种子;生产数据不受影响,只改这一行) */
+export async function promoteToAdmin() {
+  const { DatabaseSync } = await import('node:sqlite')
+  const db = new DatabaseSync('.AgentWorkShop/data/users.sqlite')
+  db.prepare('update users set role=\'admin\' where email=?').run(VISUAL_USER.email)
+  db.close()
+}
+
+export async function launch({ width = 1440, height = 900 } = {}) {
+  return puppeteer.launch({
+    executablePath: CHROME,
+    headless: true,
+    args: [
+      '--no-sandbox',
+      '--disable-dev-shm-usage',
+      '--hide-scrollbars',
+      '--force-color-profile=srgb',
+      '--font-render-hinting=none',
+    ],
+    defaultViewport: { width, height, deviceScaleFactor: 2 },
+  })
+}
+
+/**
+ * 打开一个已登录页面。
+ * 主题必须同时写 cookie(SSR 首帧)与 localStorage(pinia 持久化),
+ * 只写其一会导致首帧闪色 + antd cssinjs 不重注入(历史踩坑)。
+ */
+export async function openPage(browser, {
+  token, dark = true, width = 1440, height = 900, deviceScaleFactor = 2, touch,
+} = {}) {
+  const page = await browser.newPage()
+  // 窄视口默认按**触摸设备**仿真:不这么做,Chromium 报告 pointer:fine →
+  // 全局层 @media (pointer: coarse) 的 40px 触摸目标规则根本不生效,
+  // 审计会把"桌面鼠标语境下的紧凑按钮"误判成"手机上点不中"(实测踩过)。
+  const isTouch = touch ?? width <= 900
+  await page.setViewport({
+    width, height, deviceScaleFactor, isMobile: isTouch, hasTouch: isTouch,
+  })
+  if (token) {
+    await page.setCookie({ name: 'token', value: token, domain: '127.0.0.1', path: '/' })
+  }
+  await page.setCookie({
+    name: 'aw-theme', value: dark ? 'dark' : 'light', domain: '127.0.0.1', path: '/',
+  })
+  await page.evaluateOnNewDocument((isDark) => {
+    try {
+      localStorage.setItem('app', JSON.stringify({
+        isDark, sidebarCollapsed: false, accent: null, themeTouched: true,
+      }))
+    }
+    catch { /* 页面跳转瞬间可能失败,跳过该帧 */ }
+  }, dark)
+  return page
+}
+
+/**
+ * 导航到某页并**等到客户端真正水合完成**。
+ *
+ * 为什么不能只等 domcontentloaded + sleep:dev 模式下首个请求要现场编译客户端
+ * 包(实测冷启动 >9s),此时页面只是 SSR 快照 —— 主题、断点、图表全都没接管。
+ * 拿这种快照做视觉验收,会把"还没水合"误判成"设计有问题"(踩过一次)。
+ *
+ * 水合判据用 <html data-vp-tier>:它由 useResponsive 在客户端 watchEffect 里写入,
+ * 出现即证明客户端 setup 已跑、响应式判据已生效。
+ */
+export async function gotoReady(page, path, { wait = 2500, timeout = 90000 } = {}) {
+  await page.goto(BASE + path, { waitUntil: 'domcontentloaded', timeout: 60000 })
+  await page.waitForFunction(
+    () => document.documentElement.dataset.vpTier !== undefined,
+    { timeout, polling: 200 },
+  )
+  await sleep(wait)
+  return page
+}
+
+/** 逐帧录屏器:采集 PNG 序列后交给 ffmpeg 合成 GIF(palette 优化) */
+export function createRecorder(page, { dir, fps = 12, maxFrames = 400 }) {
+  fs.mkdirSync(dir, { recursive: true })
+  for (const f of fs.readdirSync(dir)) fs.rmSync(path.join(dir, f), { force: true })
+  let n = 0
+  let stopped = false
+  const tick = async () => {
+    if (stopped || n >= maxFrames) return
+    const i = n++
+    try {
+      await page.screenshot({ path: path.join(dir, `f${String(i).padStart(5, '0')}.png`), type: 'png' })
+    }
+    catch { /* 页面跳转瞬间可能失败,跳过该帧 */ }
+  }
+  const timer = setInterval(tick, Math.round(1000 / fps))
+  return {
+    dir,
+    frames: () => n,
+    async stop() {
+      stopped = true
+      clearInterval(timer)
+    },
+    tick,
+  }
+}

package/scripts/ui/linkcheck2.mjs

@@ -0,0 +1,37 @@
+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 token = (await api('POST', '/api/users/login', { email: 'admin@awshop.local', password: 'admin123' })).data.token
+const nodes = (await api('GET', '/api/workshop/daq', null, token)).data.nodes
+const simPorts = [16040, 15041, 5840, 18830, 4010]
+const sim = nodes.filter(n => simPorts.some(p => JSON.stringify(n).includes(String(p))))
+const good = sim.filter(n => n.state === 'ok' || n.state === 'warn')
+console.log('在线且有值的模拟器节点:', good.length, '/', sim.length)
+const seen = new Set()
+for (const n of good) {
+  const key = n.driver
+  if (seen.has(key) && seen.size > 4) continue
+  seen.add(key)
+  const c = n.config ?? {}
+  console.log('  ' + String(n.name).padEnd(22) + String(n.driver).padEnd(12) + 'state=' + String(n.state).padEnd(6) + 'val=' + String(n.value).padStart(10) + ' ' + String(n.unit ?? '').padEnd(6) + '| ' + JSON.stringify({ host: c.host, port: c.port, unitId: c.unitId, register: c.register, dataType: c.dataType, topic: c.topic, nodeId: c.nodeId, url: c.url }).slice(0, 150))
+}
+console.log('')
+console.log('按驱动看最后更新时间(判断是否还在采):')
+const byDrv = {}
+for (const n of good) {
+  byDrv[n.driver] = byDrv[n.driver] ?? { n: 0, last: '' }
+  byDrv[n.driver].n++
+  const t = n.lastSampleAt ?? n.updatedAt ?? ''
+  if (t > byDrv[n.driver].last) byDrv[n.driver].last = t
+}
+for (const [k, v] of Object.entries(byDrv)) console.log('   ' + k.padEnd(14) + ' 在线 ' + String(v.n).padStart(4) + '  最近采样 ' + v.last)

package/scripts/ui/live-render-check.mjs

@@ -0,0 +1,72 @@
+/**
+ * 验证"PLC 模拟数据 → 主项目前端"是真·实时渲染(而不是打开时拍一张快照)。
+ *
+ * 做法:同一个页面停留 15 秒,取两次 DOM 文本做逐字符 diff。
+ * 只在有值变化时才算通过 —— 这是"实时"唯一诚实的判据。
+ *
+ * 用法: node scripts/ui/live-render-check.mjs [--route daq] [--secs 15]
+ */
+import { 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
+}
+// 路由要归一成以 / 开头:BASE + 'daq' 会拼出 http://127.0.0.1:3021daq(非法 URL)
+const ROUTE = '/' + arg('route', 'daq').replace(/^\/+/, '')
+const SECS = Number(arg('secs', 15))
+const FILTER = arg('filter', '-cfA')
+const BASE = process.env.AW_BASE ?? 'http://127.0.0.1:3021'
+
+const login = await (await fetch(BASE + '/api/users/login', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ email: 'admin@awshop.local', password: 'admin123' }),
+})).json()
+const token = login.data.token
+const browser = await launch()
+const page = await openPage(browser, { token, dark: true, width: 1440, height: 900, deviceScaleFactor: 1 })
+await gotoReady(page, ROUTE, { wait: 8000 })
+
+if (FILTER) {
+  await page.evaluate((f) => {
+    const input = document.querySelector('input[placeholder*="节点名称"]')
+      || Array.from(document.querySelectorAll('input')).find(i => /搜索|search/i.test(i.placeholder || ''))
+    if (!input) return
+    const set = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set
+    set.call(input, f)
+    input.dispatchEvent(new Event('input', { bubbles: true }))
+  }, FILTER)
+  await sleep(3000)
+}
+
+// 滚到节点表,保证读的是表内容
+await page.evaluate(() => document.querySelector('.nodes-table')?.scrollIntoView({ block: 'start' }))
+await sleep(1500)
+
+const grab = () => page.evaluate(() => {
+  const t = document.querySelector('.nodes-table') || document.body
+  return t.innerText.replace(/\s+/g, ' ')
+})
+const a = await grab()
+await sleep(SECS * 1000)
+const c = await grab()
+
+let diff = 0
+const spots = []
+for (let i = 0; i < Math.max(a.length, c.length); i++) {
+  if (a[i] !== c[i]) {
+    diff++
+    if (spots.length < 8) spots.push(i)
+  }
+}
+console.log('路由:', ROUTE, ' 过滤:', FILTER || '(无)', ' 观察窗口:', SECS + 's')
+console.log('文本长度:', a.length, '->', c.length, ' 变化字符数:', diff)
+console.log('判据:', diff > 0 ? '✔ 实时渲染(值在变)' : '✘ 静止(只是快照)')
+console.log('')
+for (const i of spots.slice(0, 6)) {
+  console.log('  ' + a.slice(Math.max(0, i - 24), i + 24).trim() + '   =>   ' + c.slice(Math.max(0, i - 24), i + 24).trim())
+}
+await page.screenshot({ path: `.e2e-shots/admin/live-${ROUTE.replace(/\//g, '_')}.png` })
+await browser.close()