agentworkshop 0.7.54 → 0.7.58

package/scripts/testing/sdk-live.mjs

@@ -0,0 +1,55 @@
+/* eslint-disable @stylistic/max-statements-per-line */
+// SDK 行为级实调 v2(sdk/index 聚合面):HookBus 语义 + createPlatformClient 真实调用链
+import { HookBus, createClientContext, createPlatformClient, CLIENT_SDK_VERSION } from '../../sdk/index.mjs'
+
+let pass = 0, fail = 0
+const ok = (n, c, d = '') => { console.log(`${c ? '✅' : '❌'} ${n}${d ? ' — ' + d : ''}`); c ? pass++ : fail++ }
+
+ok('SDK 版本导出', CLIENT_SDK_VERSION.length > 0, CLIENT_SDK_VERSION)
+
+// ① HookBus:异步串行/错误隔离/通配/once
+const bus = new HookBus({ name: 'test' })
+const order = []
+bus.on('task', async (p) => { order.push('a' + p); return p * 2 })
+bus.on('task', async (p) => { order.push('b' + p) })
+await bus.emit('task', 5)
+ok('HookBus:异步串行', order.join(',') === 'a5,b5', order.join(','))
+bus.on('boom', () => { throw new Error('fail') })
+let survived = false
+bus.on('boom', () => { survived = true })
+await bus.emit('boom')
+ok('HookBus:错误隔离', survived)
+let wc = 0
+bus.on('*', () => wc++)
+await bus.emit('any', 1)
+ok('HookBus:* 通配', wc >= 1)
+let oc = 0
+const un = bus.once('once-e', () => oc++)
+await bus.emit('once-e')
+un()
+await bus.emit('once-e')
+ok('HookBus:once+退订', oc === 1)
+
+// ② createPlatformClient:登录 → 真实读取链
+const pc = createPlatformClient({ baseUrl: 'http://localhost:3001' })
+ok('platformClient:方法面完整', ['get', 'post', 'setToken', 'lines', 'daqNodes', 'channels'].every(k => k in pc), Object.keys(pc).length + ' 成员')
+const login = await pc.post('/api/users/login', { email: 'visual@awshop.local', password: 'Visual2026' }).catch(e => ({ err: String(e) }))
+const token = login?.data?.token ?? login?.token
+pc.setToken?.(token)
+ok('platformClient:登录+setToken', !!token)
+const health = await pc.get('/api/health').catch(e => ({ err: String(e) }))
+ok('platformClient:health', JSON.stringify(health).includes('"ok"'))
+const lines = await pc.get('/api/workshop/dcw/lines').catch(e => ({ err: String(e) }))
+const lineArr = lines?.data?.lines ?? lines?.lines ?? (Array.isArray(lines) ? lines : [])
+ok('platformClient:lines()', Array.isArray(lineArr) && lineArr.length >= 5, `count=${Array.isArray(lineArr) ? lineArr.length : 'shape?'}`)
+const daqNodes = await pc.get('/api/workshop/daq').catch(e => ({ err: String(e) }))
+ok('platformClient:daqNodes()', JSON.stringify(daqNodes).includes('controller') || JSON.stringify(daqNodes).includes('nodes'))
+const recipes = await pc.get('/api/workshop/dcw').catch(e => ({ err: String(e) }))
+ok('platformClient:recipes()', JSON.stringify(recipes).includes('rc-'))
+
+// ③ createClientContext 形状
+const ctx = createClientContext({ name: 'loop-test', baseUrl: 'http://localhost:3001' })
+ok('createClientContext:ctx 构建', !!ctx, Object.keys(ctx ?? {}).slice(0, 6).join(','))
+
+console.log(`\n=== SDK 行为级实调: ${pass} pass / ${fail} fail ===`)
+process.exit(fail ? 1 : 0)

package/scripts/ui/e2e-interactive.mjs

@@ -51,18 +51,18 @@ const bodyHas = (page, text) => page.evaluate(t => document.body.innerText.inclu
   console.log('\n── ① 认证体验(访客态 → 管理员) ──')
   const page = await browser.newPage()
   watch(page, '/guest')
-  await page.goto(BASE + '/', { waitUntil: 'networkidle2', timeout: 60000 }).catch(() => {})
+  await page.goto(BASE + '/', { waitUntil: 'domcontentloaded', timeout: 120000 }).catch(() => {})
   await sleep(2500)
   const guestShell = await page.evaluate(() => !!document.querySelector('.app-header, .user-chip') && document.body.innerText.trim().length > 200)
   const guestBadge = await page.evaluate(() => /访客|guest|anonymous/i.test(document.body.innerText))
   check('访客态渲染应用壳(游客可浏览,身份=访客)', guestShell && guestBadge, `badge=${guestBadge}`)
-  // cookie 登录(token 写入)→ 身份变为管理员
+  // cookie 登录(token 写入)→ 身份变为管理员(凭据 AW_EMAIL/AW_PASS 可覆盖)
   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' }),
+    body: JSON.stringify({ email: process.env.AW_EMAIL ?? 'admin@awshop.local', password: process.env.AW_PASS ?? 'admin123' }),
   })).json()
   await page.setCookie({ name: 'token', value: login.data.token, path: '/' })
-  await page.reload({ waitUntil: 'networkidle2' })
+  await page.reload({ waitUntil: 'domcontentloaded', timeout: 60_000 }).catch(() => {})
   await sleep(2500)
   const adminShown = await page.evaluate(() => /admin/i.test(document.querySelector('.user-chip')?.textContent ?? ''))
   check('cookie 登录后身份显示 admin', adminShown, await page.evaluate(() => (document.querySelector('.user-chip')?.textContent ?? '').trim().slice(0, 24)))
@@ -73,7 +73,7 @@ const bodyHas = (page, text) => page.evaluate(t => document.body.innerText.inclu
 // ════ 已登录会话 ════
 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' }),
+  body: JSON.stringify({ email: process.env.AW_EMAIL ?? 'admin@awshop.local', password: process.env.AW_PASS ?? 'admin123' }),
 })).json()
 const token = login.data.token
 const apiGet = async u => (await fetch(BASE + u, { headers: { authorization: `Bearer ${token}` } })).json()
@@ -83,7 +83,7 @@ watch(page, 'global')
 // ════ ② 仪表盘 ════
 {
   console.log('\n── ② 仪表盘 ──')
-  await page.goto(BASE + '/', { waitUntil: 'networkidle2', timeout: 60000 })
+  await page.goto(BASE + '/', { waitUntil: 'domcontentloaded', timeout: 120000 })
   await sleep(3000)
   const txt = await page.evaluate(() => document.body.innerText)
   check('仪表盘渲染非空', txt.trim().length > 200, `${txt.length} chars`)
@@ -93,7 +93,7 @@ watch(page, 'global')
 // ════ ③ 产线运营:停止 / 开跑(经 API 校验真实状态) ════
 {
   console.log('\n── ③ 产线运营(停止/开跑) ──')
-  await page.goto(BASE + '/dcw', { waitUntil: 'networkidle2', timeout: 60000 })
+  await page.goto(BASE + '/dcw', { waitUntil: 'domcontentloaded', timeout: 120000 })
   await sleep(2500)
   check('演示产线卡片渲染', await bodyHas(page, '演示线'))
   const lines = (await apiGet('/api/workshop/dcw/lines')).data?.lines ?? []
@@ -159,7 +159,7 @@ watch(page, 'global')
   const node = dcwAll.find(n => n.name.includes('Coating Oven'))
   if (!demoLine || !node) { check('定位演示产线/节点', false) }
   else {
-    await page.goto(`${BASE}/dcw/${demoLine.id}`, { waitUntil: 'networkidle2', timeout: 60000 })
+    await page.goto(`${BASE}/dcw/${demoLine.id}`, { waitUntil: 'domcontentloaded', timeout: 120000 })
     await sleep(3500)
     const before = node.value
     const target = Math.min(node.max - 1, Math.max(node.min + 1, Math.round(before ?? 130) + 5))
@@ -196,7 +196,7 @@ watch(page, 'global')
 // ════ ⑤ 数采中心:实时性 + 节点详情 ════
 {
   console.log('\n── ⑤ 数采中心 ──')
-  await page.goto(BASE + '/daq', { waitUntil: 'networkidle2', timeout: 60000 })
+  await page.goto(BASE + '/daq', { waitUntil: 'domcontentloaded', timeout: 120000 })
   await sleep(3000)
   const snap1 = await page.evaluate(() => document.body.innerText.slice(0, 4000))
   await sleep(7000)
@@ -205,7 +205,7 @@ watch(page, 'global')
   const daqList = await apiGet('/api/workshop/daq')
   const dn = (daqList.data?.nodes ?? []).find(n => n.name.includes('Coating Oven'))
   if (dn) {
-    await page.goto(`${BASE}/daq/${dn.id}`, { waitUntil: 'networkidle2', timeout: 60000 })
+    await page.goto(`${BASE}/daq/${dn.id}`, { waitUntil: 'domcontentloaded', timeout: 120000 })
     await sleep(3500)
     const chart = await page.evaluate(() => !!document.querySelector('canvas, svg'))
     check('数采节点详情(图表渲染)', chart)
@@ -216,7 +216,7 @@ watch(page, 'global')
 // ════ ⑥ 数字孪生:3D + 实时面板 + 交互 ════
 {
   console.log('\n── ⑥ 数字孪生 ──')
-  await page.goto(BASE + '/town', { waitUntil: 'networkidle2', timeout: 60000 })
+  await page.goto(BASE + '/town', { waitUntil: 'domcontentloaded', timeout: 120000 })
   await sleep(9000)
   const scene = await page.evaluate(() => {
     const canvas = [...document.querySelectorAll('canvas')].find(c => c.width > 300)
@@ -238,7 +238,7 @@ watch(page, 'global')
 // ════ ⑦ Agent 工作台:进入控制台 + 发消息 ════
 {
   console.log('\n── ⑦ Agent 工作台 ──')
-  await page.goto(BASE + '/workshop', { waitUntil: 'networkidle2', timeout: 60000 })
+  await page.goto(BASE + '/workshop', { waitUntil: 'domcontentloaded', timeout: 120000 })
   await sleep(2500)
   const cardOk = await clickText(page, '进入控制台')
   await sleep(3500)
@@ -279,7 +279,7 @@ watch(page, 'global')
 // ════ ⑧ 系统设置:主题色 + 暗色开关 ════
 {
   console.log('\n── ⑧ 系统设置 ──')
-  await page.goto(BASE + '/settings', { waitUntil: 'networkidle2', timeout: 60000 })
+  await page.goto(BASE + '/settings', { waitUntil: 'domcontentloaded', timeout: 120000 })
   await sleep(2000)
   const accentBefore = await page.evaluate(() => localStorage.getItem('app'))
   const picked = await clickText(page, '琥珀')
@@ -302,7 +302,7 @@ watch(page, 'global')
 {
   console.log('\n── ⑨ 其余页面渲染冒烟 ──')
   for (const p of ['/logs', '/monitor', '/tokens', '/users', '/permissions', '/plugins', '/aml']) {
-    await page.goto(BASE + p, { waitUntil: 'networkidle2', timeout: 45000 }).catch(() => {})
+    await page.goto(BASE + p, { waitUntil: 'domcontentloaded', timeout: 45000 }).catch(() => {})
     await sleep(1500)
     const len = await page.evaluate(() => document.body.innerText.trim().length)
     check(`渲染 ${p}`, len > 80, `${len} chars`)

package/scripts/ui/lib.mjs

@@ -1,210 +1,210 @@
-/**
- * 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'
-
-/**
- * 渲染倍率:默认 2(视觉走查/截图取清晰像素)。
- * 资源紧张的机器(或长链路交互 E2E:多页 + 整页截图)可 `AW_UI_SCALE=1` 降一档 ——
- * 否则 Chromium 会以 `net::ERR_INSUFFICIENT_RESOURCES` 拒绝加载后续资源,
- * 表现为"页面加载不出来",实际是渲染表面内存打满(与产品无关)。
- */
-export const UI_SCALE = Number(process.env.AW_UI_SCALE ?? 2) || 2
-
-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,
-    // 重页面(echarts/three/phaser + 首帧 SSR 水合)在**负载较高的机器**上单次
-    // Runtime.evaluate 可能超过 CDP 默认 180s → ProtocolError 直接把断言打断。
-    // 这里放宽到 5 分钟:慢 ≠ 失败,断言本身仍各自带超时。
-    protocolTimeout: 300_000,
-    args: [
-      '--no-sandbox',
-      '--disable-dev-shm-usage',
-      '--hide-scrollbars',
-      '--force-color-profile=srgb',
-      '--font-render-hinting=none',
-    ],
-    defaultViewport: { width, height, deviceScaleFactor: UI_SCALE },
-  })
-}
-
-/**
- * 打开一个已登录页面。
- * 主题必须同时写 cookie(SSR 首帧)与 localStorage(pinia 持久化),
- * 只写其一会导致首帧闪色 + antd cssinjs 不重注入(历史踩坑)。
- */
-export async function openPage(browser, {
-  token, dark = true, width = 1440, height = 900, deviceScaleFactor = UI_SCALE, 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,
-  }
-}
+/**
+ * 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'
+
+/**
+ * 渲染倍率:默认 2(视觉走查/截图取清晰像素)。
+ * 资源紧张的机器(或长链路交互 E2E:多页 + 整页截图)可 `AW_UI_SCALE=1` 降一档 ——
+ * 否则 Chromium 会以 `net::ERR_INSUFFICIENT_RESOURCES` 拒绝加载后续资源,
+ * 表现为"页面加载不出来",实际是渲染表面内存打满(与产品无关)。
+ */
+export const UI_SCALE = Number(process.env.AW_UI_SCALE ?? 2) || 2
+
+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,
+    // 重页面(echarts/three/phaser + 首帧 SSR 水合)在**负载较高的机器**上单次
+    // Runtime.evaluate 可能超过 CDP 默认 180s → ProtocolError 直接把断言打断。
+    // 这里放宽到 5 分钟:慢 ≠ 失败,断言本身仍各自带超时。
+    protocolTimeout: 900_000,
+    args: [
+      '--no-sandbox',
+      '--disable-dev-shm-usage',
+      '--hide-scrollbars',
+      '--force-color-profile=srgb',
+      '--font-render-hinting=none',
+    ],
+    defaultViewport: { width, height, deviceScaleFactor: UI_SCALE },
+  })
+}
+
+/**
+ * 打开一个已登录页面。
+ * 主题必须同时写 cookie(SSR 首帧)与 localStorage(pinia 持久化),
+ * 只写其一会导致首帧闪色 + antd cssinjs 不重注入(历史踩坑)。
+ */
+export async function openPage(browser, {
+  token, dark = true, width = 1440, height = 900, deviceScaleFactor = UI_SCALE, 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/server/api/health.get.ts

@@ -1,9 +1,10 @@
 /**
  * GET /api/health —— 存活探测(公开,无需认证;供运维/脚本探活)。
- * 返回版本 + 进程 uptime + workshop manager 装配概要。
+ * 返回版本 + 进程 uptime + workshop manager 装配概要 + 内存水位(P0-4)。
  * 存活语义:进程可响应即 200;manager 未就绪(启动早期)降级标记 workshop='not_ready',
  * 不抛错——就绪探针可按该字段判断,而探活端点本身不被组件状态拖垮。
  */
+import v8 from 'node:v8'
 import { useServerConfig } from '../utils/config'
 import { defineApiHandler } from '../utils/response'
 import { getWorkshopManager } from '../plugins/workshop'
@@ -19,6 +20,9 @@ export default defineApiHandler(async () => {
   catch {
     workshop = 'not_ready'
   }
+  // P0-4 内存水位(heapUsed 相对 --max-old-space-size;exit 134 = 堆耗尽,与其同源)
+  const mu = process.memoryUsage()
+  const heapLimit = v8.getHeapStatistics().heap_size_limit
   return {
     status: 'ok',
     app: cfg.app.name,
@@ -28,5 +32,12 @@ export default defineApiHandler(async () => {
     timestamp: new Date().toISOString(),
     workshop,
     ...summary,
+    memory: {
+      heapUsedMb: Math.round(mu.heapUsed / 1048576),
+      heapLimitMb: Math.round(heapLimit / 1048576),
+      rssMb: Math.round(mu.rss / 1048576),
+      externalMb: Math.round(mu.external / 1048576),
+      heapRatio: heapLimit > 0 ? Number((mu.heapUsed / heapLimit).toFixed(4)) : 0,
+    },
   }
 })