agentworkshop 0.7.39 → 0.7.41

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()

package/scripts/ui/md-lint.mjs

@@ -0,0 +1,80 @@
+/**
+ * README 结构自检:标签配平、图片/链接存在、模板残留、表格列数一致。
+ * GitHub 的渲染器很宽容,写坏了不报错 —— 只会在页面上难看,所以得自己查。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+const files = process.argv.slice(2)
+const FENCE = String.fromCharCode(96).repeat(3)
+let bad = 0
+const fail = (f, m) => {
+  bad += 1
+  console.log('  x ' + f + ': ' + m)
+}
+
+for (const f of files) {
+  const t = fs.readFileSync(f, 'utf8')
+  const ls = t.split(/\r?\n/)
+  console.log('·', f)
+
+  // 转义残留:只把'转义了不该转义的字符'当问题(表格里的 \\| 是合法的)
+  const esc = ls.findIndex(l => l.includes('\\' + String.fromCharCode(96)))
+  if (esc >= 0) fail(f, 'line ' + (esc + 1) + ' 存在反引号转义残留')
+
+  // ${...} 只在不处于围栏代码块里时才算未求值模板(shell 示例里的 ${VAR} 合法)
+  {
+    let fenced = false
+    let hit = -1
+    for (let i = 0; i < ls.length; i++) {
+      if (ls[i].trim().startsWith(FENCE)) {
+        fenced = !fenced
+        continue
+      }
+      if (!fenced && /\$\{[a-zA-Z_]/.test(ls[i])) {
+        hit = i
+        break
+      }
+    }
+    if (hit >= 0) fail(f, 'line ' + (hit + 1) + ' 存在未求值的模板占位')
+  }
+
+  // 标签配平
+  for (const tag of ['div', 'table', 'tr', 'td', 'details', 'summary', 'picture', 'sub', 'code', 'a']) {
+    const open = (t.match(new RegExp('<' + tag + '(\\s|>)', 'g')) || []).length
+    const close = (t.match(new RegExp('</' + tag + '>', 'g')) || []).length
+    const self = (t.match(new RegExp('<' + tag + '[^>]*/>', 'g')) || []).length
+    if (open - self !== close) fail(f, '<' + tag + '> 不配平: open=' + open + ' self=' + self + ' close=' + close)
+  }
+
+  // 本地图片 / 链接存在
+  for (const m of t.matchAll(/<img[^>]+src="([^"]+)"/g)) {
+    const src = m[1]
+    if (/^https?:/.test(src)) continue
+    const abs = path.resolve(path.dirname(f), src.replace(/^\.\//, ''))
+    if (!fs.existsSync(abs)) fail(f, '图片不存在: ' + src)
+  }
+  for (const m of t.matchAll(/\]\((\.\/[^)#]+)\)/g)) {
+    const abs = path.resolve(path.dirname(f), m[1].replace(/^\.\//, ''))
+    if (!fs.existsSync(abs)) fail(f, '链接目标不存在: ' + m[1])
+  }
+
+  // 表格列数一致(转义管道符不算分隔)
+  const cells = row => row.replace(/\\\|/g, '\u0000').split('|').length
+  let cols = null, start = 0
+  for (let i = 0; i <= ls.length; i++) {
+    const isRow = i < ls.length && /^\s*\|.*\|\s*$/.test(ls[i])
+    if (!isRow) {
+      cols = null
+      continue
+    }
+    const n = cells(ls[i])
+    if (cols === null) {
+      cols = n
+      start = i
+    }
+    else if (n !== cols) fail(f, 'line ' + (i + 1) + ' 表格列数 ' + n + ' != 表头 ' + cols + '(表从 line ' + (start + 1) + ' 起)')
+  }
+}
+console.log(bad ? '\n' + bad + ' 个问题' : '\n全部通过')
+process.exit(bad ? 1 : 0)

package/scripts/ui/perf-audit.mjs

@@ -0,0 +1,132 @@
+/**
+ * 前端实时链路性能体检 —— 用真实浏览器量"数据刷新是否把主线程压垮"。
+ *
+ * 量的是四件事(全部来自运行时,不是估算):
+ *  1. Long Task:>50ms 的主线程阻塞任务数 与 总阻塞时长(TBT)
+ *  2. FPS:用 requestAnimationFrame 采样的真实帧率 + 掉帧比例
+ *  3. DOM 变更速率:每秒多少次节点/属性变更(重渲染churn 的直接代理指标)
+ *  4. CDP Performance 指标:ScriptDuration / LayoutDuration / RecalcStyleDuration 的增量
+ *
+ * 用法: node scripts/ui/perf-audit.mjs [--routes daq,town,dashboard] [--secs 20] [--vp 1440x900]
+ */
+import { ensureVisualUser, launch, openPage, gotoReady, sleep, 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 ONLY = arg('routes', 'daq,town,dashboard,monitor')
+const SECS = Number(arg('secs', 20))
+const [W, H] = arg('vp', '1440x900').split('x').map(Number)
+
+const picks = ROUTES.filter(r => ONLY.split(',').includes(r.name))
+// 频道会话台(/workshop/w/<id>)不在静态 ROUTES 里,但它是事件最密的页面 ——
+// 用真实 workspace id 合成一条,才能量到"Agent 事件流是否压垮主线程"。
+
+const token = await ensureVisualUser()
+// 频道会话台(/workshop/w/<id>)不在静态 ROUTES 里,但它是事件最密的页面 ——
+// 用真实 workspace id 合成一条,才能量到"Agent 事件流是否压垮主线程"。
+if (ONLY.includes('console')) {
+  const { api } = await import('./lib.mjs')
+  const ws = await api('GET', '/api/workshop/workspaces', { token })
+  const list = ws.data?.workspaces ?? ws.data ?? []
+  const wid = (Array.isArray(list) ? list[0] : null)?.id
+  if (wid) picks.push({ path: `/workshop/w/${wid}`, name: 'console', title: '频道会话台' })
+  else console.log('!! 没有可用工作区,跳过 console(先跑 scripts/ui/seed-demo.mjs)')
+}
+const browser = await launch()
+
+const INSTRUMENT = () => {
+  const w = window
+  w.__perf = { longTasks: 0, tbt: 0, frames: 0, slowFrames: 0, mutations: 0, last: performance.now(), maxGap: 0 }
+  try {
+    new PerformanceObserver((list) => {
+      for (const e of list.getEntries()) {
+        w.__perf.longTasks++
+        w.__perf.tbt += Math.max(0, e.duration - 50)
+      }
+    }).observe({ entryTypes: ['longtask'] })
+  }
+  catch { /* 不支持 longtask 就只靠 FPS */ }
+  const mo = new MutationObserver((recs) => {
+    w.__perf.mutations += recs.length
+  })
+  mo.observe(document.body, { childList: true, subtree: true, attributes: true, characterData: true })
+  const tick = (t) => {
+    const p = w.__perf
+    const gap = t - p.last
+    p.last = t
+    if (p.frames > 0) {
+      if (gap > p.maxGap) p.maxGap = gap
+      if (gap > 33) p.slowFrames++
+    }
+    p.frames++
+    requestAnimationFrame(tick)
+  }
+  requestAnimationFrame(tick)
+}
+
+const rows = []
+for (const r of picks) {
+  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, 140)))
+  try {
+    await gotoReady(page, r.path, { wait: 4000 })
+    await page.evaluate(INSTRUMENT)
+    const client = await page.createCDPSession()
+    await client.send('Performance.enable')
+    const m0 = await client.send('Performance.getMetrics')
+    const t0 = Date.now()
+
+    await sleep(SECS * 1000)
+
+    const m1 = await client.send('Performance.getMetrics')
+    const p = await page.evaluate(() => ({ ...window.__perf }))
+    const metric = (name) => {
+      const a = m0.metrics.find(x => x.name === name)?.value ?? 0
+      const b = m1.metrics.find(x => x.name === name)?.value ?? 0
+      return b - a
+    }
+    const secs = (Date.now() - t0) / 1000
+    const row = {
+      route: r.name,
+      secs: +secs.toFixed(1),
+      fps: +(p.frames / secs).toFixed(1),
+      slowFramePct: +((p.slowFrames / Math.max(1, p.frames)) * 100).toFixed(1),
+      maxGapMs: Math.round(p.maxGap),
+      longTasks: p.longTasks,
+      tbtMs: Math.round(p.tbt),
+      mutPerSec: Math.round(p.mutations / secs),
+      scriptMs: Math.round(metric('ScriptDuration') * 1000),
+      layoutMs: Math.round(metric('LayoutDuration') * 1000),
+      styleMs: Math.round(metric('RecalcStyleDuration') * 1000),
+      nodes: Math.round(metric('Nodes')),
+      listeners: Math.round(metric('JSEventListeners')),
+      pageErrors: errs.length,
+    }
+    rows.push(row)
+    console.log(JSON.stringify(row))
+  }
+  catch (e) {
+    console.log(r.name, 'FAIL', String(e.message).slice(0, 120))
+  }
+  await page.close()
+}
+await browser.close()
+console.log('\n路由          FPS   掉帧%  最大间隔  长任务  阻塞ms  DOM变更/s  脚本ms  布局ms  样式ms')
+for (const r of rows) {
+  console.log(
+    r.route.padEnd(12),
+    String(r.fps).padStart(5),
+    String(r.slowFramePct).padStart(6),
+    String(r.maxGapMs).padStart(8),
+    String(r.longTasks).padStart(7),
+    String(r.tbtMs).padStart(7),
+    String(r.mutPerSec).padStart(10),
+    String(r.scriptMs).padStart(7),
+    String(r.layoutMs).padStart(7),
+    String(r.styleMs).padStart(7),
+  )
+}

package/scripts/ui/readme-assets.mjs

@@ -0,0 +1,30 @@
+/**
+ * README / 文档站素材一键重建。
+ *
+ * 顺序不能换:截图 → GIF → hero。hero.html 里内嵌的是同目录的 town.png / daq.png,
+ * 所以 hero 必须最后渲,否则首屏会用到上一轮的界面截图(实测踩过)。
+ *
+ *   node scripts/ui/readme-assets.mjs [--skip-gif]
+ */
+import fs from 'node:fs'
+import { execFileSync } from 'node:child_process'
+
+const skipGif = process.argv.includes('--skip-gif')
+const run = (script, args = []) => {
+  console.log('\n▶ node ' + script + ' ' + args.join(' '))
+  execFileSync(process.execPath, [script, ...args], { stdio: 'inherit' })
+}
+
+run('scripts/ui/readme-shots.mjs')
+
+if (!skipGif) {
+  for (const story of ['agents', 'daq', 'dcw', 'town', 'dashboard', 'responsive']) {
+    const num = { agents: '01-closedloop', daq: '02-daq', dcw: '03-dcw', town: '04-town', dashboard: '05-dashboard', responsive: '06-responsive' }[story]
+    // record.mjs 按剧本名输出 <story>.gif,这里落成 README 里的 fig-NN-*.gif 编号名
+    run('scripts/ui/record.mjs', [story, '--out', 'docs/readme-assets', '--gifw', '1000'])
+    fs.renameSync('docs/readme-assets/' + story + '.gif', 'docs/readme-assets/fig-' + num + '.gif')
+  }
+}
+
+run('scripts/ui/shot-hero.mjs')
+console.log('\n✔ README 素材重建完成')

package/scripts/ui/readme-shots.mjs

@@ -0,0 +1,42 @@
+/**
+ * README 用真实截图(与 record.mjs 的 GIF 配套)。
+ * 全部 1600×1000 @2x 出图,固定暗色控制室主题 —— README 首屏是深色语境,
+ * 混入亮色截图会让整页忽明忽暗。
+ */
+import path from 'node:path'
+import { ensureVisualUser, launch, openPage, gotoReady } from './lib.mjs'
+
+const OUT = 'docs/readme-assets'
+const W = 1600
+const H = 1000
+
+const SHOTS = [
+  { file: 'town.png', route: '/town', wait: 11000 },
+  { file: 'daq.png', route: '/daq', wait: 8000 },
+  { file: 'shot-workshop.png', route: '/workshop', wait: 7000 },
+  { file: 'shot-monitor.png', route: '/monitor', wait: 6000 },
+  { file: 'shot-settings.png', route: '/settings', wait: 6000 },
+  { file: 'shot-plugins.png', route: '/plugins', wait: 6000 },
+  { file: 'shot-dcw.png', route: '/dcw', wait: 7000 },
+  { file: 'shot-aml.png', route: '/aml', wait: 7000 },
+  { file: 'shot-logs.png', route: '/logs', wait: 6000 },
+]
+
+const token = await ensureVisualUser()
+const browser = await launch()
+for (const s of SHOTS) {
+  const page = await openPage(browser, { token, dark: true, width: W, height: H, deviceScaleFactor: 2 })
+  const errs = []
+  page.on('pageerror', e => errs.push(String(e.message).slice(0, 120)))
+  try {
+    await gotoReady(page, s.route, { wait: s.wait })
+    await page.screenshot({ path: path.join(OUT, s.file) })
+    console.log('  ok  ' + s.file.padEnd(22) + s.route + (errs.length ? '  errs=' + errs.length : ''))
+  }
+  catch (e) {
+    console.log('  FAIL ' + s.file + ' — ' + String(e.message).slice(0, 120))
+  }
+  await page.close()
+}
+await browser.close()
+console.log('-> ' + OUT)