agentworkshop 0.7.34 → 0.7.38

package/scripts/_audit/design-shots.mjs

@@ -0,0 +1,145 @@
+/**
+ * 视觉走查截图(设计评审用)—— 全站关键页 × 亮/暗双主题。
+ *
+ * 为什么单独一支:设计验收必须看**生产构建下的真实渲染**(玻璃材质依赖 backdrop-filter
+ * 与真实极光层,dev 模式下 HMR 注入的样式顺序会让玻璃层级失真)。
+ *
+ * 用法:node scripts/_audit/design-shots.mjs [base] [--out=dir]
+ * 依赖:puppeteer-core + 本机 Edge/Chrome(无需下载 Chromium)。
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import puppeteer from 'puppeteer-core'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..', '..')
+const BASE = (process.argv[2] ?? process.env.AW_BASE ?? 'http://127.0.0.1:3111').replace(/\/$/, '')
+const OUT = (process.argv.find(a => a.startsWith('--out='))?.slice(6)) ?? join(REPO, '.e2e-shots', 'design')
+const VIEWPORT = { width: 1680, height: 1050 }
+
+const EDGE = 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe'
+const CHROME = 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
+const EXEC = existsSync(EDGE) ? EDGE : CHROME
+
+/** 关键页(路径 + 中文名)。控制在能覆盖全部视觉声部的范围内,不追求页数。 */
+const PAGES = [
+  ['/', '仪表盘'],
+  ['/daq', '数采中心'],
+  ['/dcw', '数控中心'],
+  ['/aml', '建模平台'],
+  ['/monitor', '监控'],
+  ['/logs', '运维日志'],
+  ['/tokens', '令牌'],
+  ['/settings', '系统设置'],
+  ['/plugins', '插件'],
+  ['/permissions', '权限'],
+]
+
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+async function main() {
+  mkdirSync(OUT, { recursive: true })
+  const browser = await puppeteer.launch({
+    executablePath: EXEC,
+    headless: 'new',
+    args: ['--no-sandbox', '--disable-dev-shm-usage', '--force-device-scale-factor=1', '--hide-scrollbars'],
+    defaultViewport: VIEWPORT,
+  })
+
+  const errors = []
+  const shots = []
+  try {
+    // 鉴权:优先用显式管理员登录(视觉走查要看**有数据的真实界面**,普通用户会被 403 挡成空壳)
+    const ADMIN_EMAIL = process.env.AW_ADMIN_EMAIL ?? 'admin@awshop.local'
+    const ADMIN_PASS = process.env.AW_ADMIN_PASS ?? 'admin123'
+    const login = await fetch(`${BASE}/api/users/login`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ email: ADMIN_EMAIL, password: ADMIN_PASS }),
+    }).then(r => r.json()).catch(() => null)
+    let token = login?.data?.token ?? ''
+    let role = login?.data?.user?.role ?? ''
+    if (!token) {
+      const reg = await fetch(`${BASE}/api/workshop/users/register`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ name: `shot-${Date.now().toString(36)}` }),
+      }).then(r => r.json()).catch(() => null)
+      token = reg?.data?.token ?? ''
+      role = 'registered'
+    }
+    console.log(`服务:${BASE}  token:${token ? 'ok' : '无'}  role:${role}`)
+
+    const page = await browser.newPage()
+    page.on('pageerror', e => errors.push(`[pageerror] ${e.message}`))
+    page.on('console', (m) => {
+      if (m.type() === 'error') errors.push(`[console] ${m.text().slice(0, 200)}`)
+    })
+
+    // 鉴权走 cookie `token`(apiClient 从这里取 Bearer),不是 localStorage;
+    // 主题走 pinia persistedstate 的 'app' 键 + aw-theme cookie 镜像。
+    const seed = async (theme) => {
+      await page.evaluate((t, tok) => {
+        document.cookie = `token=${encodeURIComponent(tok)}; path=/`
+        document.cookie = `aw-theme=${t}; path=/`
+        localStorage.setItem('app', JSON.stringify({
+          isDark: t === 'dark', sidebarCollapsed: false, accent: '', themeTouched: true,
+        }))
+      }, theme, token)
+    }
+
+    for (const theme of ['light', 'dark']) {
+      await page.goto(`${BASE}/`, { waitUntil: 'domcontentloaded', timeout: 60_000 })
+      await seed(theme)
+      for (const [path, label] of PAGES) {
+        const url = `${BASE}${path}`
+        try {
+          // 先落地再种 cookie,保证服务端 SSR 首帧就带鉴权与主题
+          await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60_000 })
+          await seed(theme)
+          await page.reload({ waitUntil: 'networkidle2', timeout: 60_000 })
+          await sleep(1100)
+          const name = `${theme}-${(path === '/' ? 'dashboard' : path.replace(/\//g, '_').replace(/^_/, ''))}.png`
+          const file = join(OUT, name)
+          await page.screenshot({ path: file, fullPage: false })
+          shots.push({ theme, path, label, file })
+          console.log(`  ✔ ${theme}  ${label.padEnd(6)} ${path}`)
+        }
+        catch (err) {
+          console.log(`  ✘ ${theme}  ${label} ${path} — ${err.message.slice(0, 90)}`)
+          errors.push(`[nav ${path}] ${err.message.slice(0, 160)}`)
+        }
+      }
+    }
+  }
+  finally {
+    await browser.close()
+  }
+
+  const manifest = join(OUT, 'MANIFEST.md')
+  writeFileSync(manifest, [
+    `# 视觉走查截图(${new Date().toISOString()})`,
+    '',
+    `服务:${BASE}  viewport:${VIEWPORT.width}×${VIEWPORT.height}`,
+    '',
+    '| 主题 | 页面 | 路径 | 文件 |',
+    '| --- | --- | --- | --- |',
+    ...shots.map(s => `| ${s.theme} | ${s.label} | ${s.path} | ${s.file.split(/[\\/]/).pop()} |`),
+    '',
+    `页面错误:${errors.length}`,
+    ...errors.slice(0, 40).map(e => `- ${e}`),
+    '',
+  ].join('\n'), 'utf8')
+
+  console.log(`\n输出:${OUT}`)
+  console.log(`截图 ${shots.length} 张,页面错误 ${errors.length} 条`)
+  if (errors.length) {
+    console.log(errors.slice(0, 12).join('\n'))
+  }
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/scripts/_audit/docs-font-probe.mjs

@@ -0,0 +1,68 @@
+/**
+ * docs-font-probe.mjs —— 判定"中文渲染重叠"是站点缺陷还是无头环境缺字体的伪影。
+ * 方法:在目标浏览器里对同一串中文逐族测量 advance 宽度 + document.fonts.check(),
+ * 再渲染一张纯 HTML 对照图(不加载站点 CSS)。若对照图同样重叠 → 环境缺 CJK 字体。
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import puppeteer from 'puppeteer-core'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..', '..')
+const OUT = join(REPO, '.e2e-shots', 'docs-font')
+const EDGE = 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe'
+const CHROME = 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
+const EXEC = existsSync(EDGE) ? EDGE : CHROME
+
+const FAMILIES = [
+  'Punctuation SC', 'Inter', 'sans-serif', 'system-ui', 'ui-sans-serif',
+  'Microsoft YaHei', 'Microsoft YaHei UI', 'SimSun', 'SimHei', 'NSimSun',
+  'PingFang SC', 'Hiragino Sans GB', 'Noto Sans SC', 'Noto Sans CJK SC', 'Source Han Sans SC',
+  'DengXian', 'KaiTi', 'FangSong', 'Arial', 'Segoe UI', 'monospace', 'Consolas', 'Cascadia Mono',
+]
+
+mkdirSync(OUT, { recursive: true })
+const browser = await puppeteer.launch({
+  executablePath: EXEC,
+  headless: 'new',
+  args: ['--no-sandbox', '--disable-dev-shm-usage', '--force-device-scale-factor=1'],
+  defaultViewport: { width: 1200, height: 400 },
+})
+const page = await browser.newPage()
+
+const report = await page.evaluate((fams) => {
+  const SAMPLE = '首次启动时一切初始化进配置根'
+  const cv = document.createElement('canvas').getContext('2d')
+  const rows = []
+  for (const f of fams) {
+    cv.font = `16px "${f}"`
+    const w = cv.measureText(SAMPLE).width
+    const base = (() => { cv.font = '16px monospace'; return cv.measureText(SAMPLE).width })()
+    rows.push({ family: f, width: Number(w.toFixed(2)), sameAsMonospace: Math.abs(w - base) < 0.5, check: document.fonts.check(`16px "${f}"`) })
+  }
+  cv.font = '16px monospace'
+  const monoBase = Number(cv.measureText(SAMPLE).width.toFixed(2))
+  return { sample: SAMPLE, chars: SAMPLE.length, monoBase, rows }
+}, FAMILIES)
+
+console.log(`样本 ${report.chars} 字 · monospace 基准宽 ${report.monoBase}px(每字 ${(report.monoBase / report.chars).toFixed(2)}px)\n`)
+console.log('family'.padEnd(26), 'width'.padStart(9), '  sameAsMono  fonts.check')
+for (const r of report.rows) {
+  console.log(r.family.padEnd(26), String(r.width).padStart(9), '  ' + String(r.sameAsMonospace).padEnd(12) + String(r.check))
+}
+
+// 对照图:完全不使用站点 CSS 的最小 HTML,同一段中文
+const plain = `<!doctype html><meta charset="utf-8"><body style="background:#070b13;color:#e8eef8;margin:0;padding:24px">
+<p style="font:16px/1.8 sans-serif;max-width:640px">${report.sample} —— sans-serif 回退</p>
+<p style="font:16px/1.8 'Microsoft YaHei',sans-serif;max-width:640px">${report.sample} —— Microsoft YaHei 优先</p>
+<p style="font:16px/1.8 monospace;max-width:640px">${report.sample} —— monospace</p>
+</body>`
+const plainFile = join(OUT, 'plain.html')
+writeFileSync(plainFile, plain, 'utf8')
+await page.goto(`file:///${plainFile.replace(/\\/g, '/')}`, { waitUntil: 'load' })
+await new Promise(r => setTimeout(r, 300))
+await page.screenshot({ path: join(OUT, 'plain-contrast.png') })
+console.log(`\n对照图 → ${join(OUT, 'plain-contrast.png')}`)
+
+await browser.close()

package/scripts/_audit/docs-probe.mjs

@@ -0,0 +1,107 @@
+/**
+ * docs-probe.mjs —— 文档站渲染诊断:正文段落计算样式 + 字体加载 + 首屏动画
+ * 用于判定"文字发暗/重叠"是真实缺陷还是无头截图伪影。
+ * 用法:node scripts/_audit/docs-probe.mjs [route]
+ */
+import { createServer } from 'node:http'
+import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, extname, join, normalize, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import puppeteer from 'puppeteer-core'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..', '..')
+const DIST = join(REPO, 'docs', 'site', '.vitepress', 'dist')
+const BASE_PATH = '/AgentWorkShop'
+const PORT = 3223
+const ROUTE = process.argv[2] ?? '/guide/getting-started'
+const EDGE = 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe'
+const CHROME = 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
+const EXEC = existsSync(EDGE) ? EDGE : CHROME
+
+const MIME = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.woff2': 'font/woff2', '.gif': 'image/gif', '.map': 'application/json' }
+
+function serve() {
+  return new Promise((ok) => {
+    const s = createServer((req, res) => {
+      let p = decodeURIComponent(new URL(req.url, 'http://x').pathname)
+      if (!p.startsWith(BASE_PATH)) { res.writeHead(404); res.end(); return }
+      p = p.slice(BASE_PATH.length) || '/'
+      let f = join(DIST, normalize(p).replace(/^(\.\.[/\\])+/, ''))
+      if (existsSync(f) && statSync(f).isDirectory()) f = join(f, 'index.html')
+      if (!existsSync(f) && !extname(f)) f = `${f}.html`
+      if (!existsSync(f)) { res.writeHead(404); res.end('nf'); return }
+      res.writeHead(200, { 'content-type': MIME[extname(f)] ?? 'application/octet-stream' })
+      res.end(readFileSync(f))
+    })
+    s.listen(PORT, '127.0.0.1', () => ok(s))
+  })
+}
+
+const server = await serve()
+const browser = await puppeteer.launch({
+  executablePath: EXEC,
+  headless: 'new',
+  args: ['--no-sandbox', '--disable-dev-shm-usage', '--force-device-scale-factor=1', '--hide-scrollbars'],
+  defaultViewport: { width: 1680, height: 1000 },
+})
+const page = await browser.newPage()
+const failed = []
+page.on('requestfailed', r => failed.push(`${r.url()} :: ${r.failure()?.errorText}`))
+page.on('response', (r) => { if (r.status() >= 400) failed.push(`HTTP ${r.status()} ${r.url()}`) })
+await page.goto(`http://127.0.0.1:${PORT}${BASE_PATH}${ROUTE}`, { waitUntil: 'networkidle2' })
+await page.evaluate(() => document.fonts?.ready).catch(() => {})
+await new Promise(r => setTimeout(r, 1500))
+
+const out = await page.evaluate(() => {
+  const pick = (el, props) => {
+    if (!el) return null
+    const cs = getComputedStyle(el)
+    const o = {}
+    for (const p of props) o[p] = cs.getPropertyValue(p)
+    const r = el.getBoundingClientRect()
+    o._rect = `${Math.round(r.width)}x${Math.round(r.height)} @${Math.round(r.x)},${Math.round(r.y)}`
+    o._text = (el.textContent ?? '').slice(0, 30)
+    return o
+  }
+  const props = ['color', 'font-family', 'font-size', 'font-weight', 'line-height', 'letter-spacing', 'opacity', 'transform', 'filter', 'animation-name', 'text-rendering', 'font-variant-ligatures', 'visibility', 'mix-blend-mode', 'background-color', 'writing-mode']
+  const ps = [...document.querySelectorAll('.vp-doc p')]
+  return {
+    bodyBg: getComputedStyle(document.body).backgroundColor,
+    pCount: ps.length,
+    samples: ps.slice(0, 3).map(p => pick(p, props)),
+    h2: pick(document.querySelector('.vp-doc h2'), props),
+    code: pick(document.querySelector('.vp-doc div[class*="language-"] code'), props),
+    customBlock: pick(document.querySelector('.vp-doc .custom-block p'), props),
+    fonts: [...document.fonts].map(f => `${f.family} ${f.weight} ${f.status}`),
+    animations: document.getAnimations().map(a => `${a.animationName ?? a.constructor.name} @${a.playState}`),
+  }
+})
+
+console.log(JSON.stringify(out, null, 2))
+console.log('\n=== 失败请求 ===')
+console.log(failed.length ? failed.join('\n') : '(无)')
+
+// 1:1 元素截图:整体截图会被预览缩放,16px 中文在缩放后会被误判为"重叠不可读"。
+// 这里对正文段落按 deviceScaleFactor=2 单独出图,作为可读性的判据。
+await page.setViewport({ width: 1680, height: 1000, deviceScaleFactor: 2 })
+await page.reload({ waitUntil: 'networkidle2' })
+await page.evaluate(() => document.fonts?.ready).catch(() => {})
+await new Promise(r => setTimeout(r, 800))
+const cropDir = resolve(HERE, '..', '..', '.e2e-shots', 'docs-font')
+mkdirSync(cropDir, { recursive: true })
+const p = await page.$('.vp-doc p')
+if (p) {
+  const file = join(cropDir, `crop${ROUTE.replace(/\W+/g, '_')}.png`)
+  await p.screenshot({ path: file })
+  console.log(`\n正文段落 1:1 ×2 → ${file}`)
+}
+const h2 = await page.$('.vp-doc h2')
+if (h2) {
+  const file = join(cropDir, `crop-h2${ROUTE.replace(/\W+/g, '_')}.png`)
+  await h2.screenshot({ path: file })
+  console.log(`二级标题 1:1 ×2 → ${file}`)
+}
+
+await browser.close()
+server.close()

package/scripts/_audit/docs-shots.mjs

@@ -0,0 +1,171 @@
+/**
+ * docs-shots.mjs —— VitePress 文档站视觉走查截图(独立审计用)
+ * ------------------------------------------------------------
+ * 站点 base = '/AgentWorkShop/'(见 docs/site/.vitepress/config.mts),
+ * 故这里起一个最小静态服务器把 dist 挂到该前缀下,再用本机 Edge/Chrome 截图。
+ * 依赖:puppeteer-core + 本机浏览器(与 scripts/_audit/design-shots.mjs 同方案)。
+ *
+ * 用法:
+ *   node scripts/_audit/docs-shots.mjs                       # 构建产物 → 默认 .e2e-shots/docs
+ *   node scripts/_audit/docs-shots.mjs --out=D:\x\y           # 指定输出目录
+ *   node scripts/_audit/docs-shots.mjs --port=3222            # 指定端口
+ *   node scripts/_audit/docs-shots.mjs --width=1440           # 桌面宽度(默认 1680)
+ */
+import { createServer } from 'node:http'
+import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, extname, join, normalize, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import puppeteer from 'puppeteer-core'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..', '..')
+const DIST = join(REPO, 'docs', 'site', '.vitepress', 'dist')
+const BASE_PATH = '/AgentWorkShop'
+const OUT = (process.argv.find(a => a.startsWith('--out='))?.slice(6)) ?? join(REPO, '.e2e-shots', 'docs')
+const PORT = Number(process.argv.find(a => a.startsWith('--port='))?.slice(7) ?? 3222)
+const WIDTH = Number(process.argv.find(a => a.startsWith('--width='))?.slice(8) ?? 1680)
+
+const EDGE = 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe'
+const CHROME = 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
+const EXEC = existsSync(EDGE) ? EDGE : CHROME
+
+/** 走查页:首页(整页) + 各内容形态的代表页(折叠以下也要看,故 fullPage) */
+const PAGES = [
+  ['/', 'home', true],
+  ['/guide/getting-started', 'guide-getting-started', false],
+  ['/guide/daq-protocols', 'guide-daq-protocols', false],
+  ['/sdk/', 'sdk-index', false],
+  ['/sdk/context', 'sdk-context', false],
+  ['/plugins/', 'plugins-index', false],
+  ['/plugins/guide', 'plugins-guide', false],
+  ['/cli/', 'cli', false],
+  ['/guide/aml', 'guide-aml', false],
+  ['/en/', 'en-home', true],
+  ['/en/plugins/guide', 'en-plugins-guide', false],
+]
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.woff2': 'font/woff2',
+  '.ico': 'image/x-icon',
+  '.map': 'application/json; charset=utf-8',
+}
+
+/** 把 dist 挂到 base 前缀下;未知路径回落到目录 index.html / 然后 404 */
+function serve() {
+  return new Promise((ok) => {
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, `http://127.0.0.1:${PORT}`)
+      let p = decodeURIComponent(url.pathname)
+      if (!p.startsWith(BASE_PATH)) {
+        res.writeHead(404, { 'content-type': 'text/plain' })
+        res.end('outside base')
+        return
+      }
+      p = p.slice(BASE_PATH.length) || '/'
+      let file = join(DIST, normalize(p).replace(/^(\.\.[/\\])+/, ''))
+      try {
+        if (existsSync(file) && statSync(file).isDirectory()) file = join(file, 'index.html')
+        if (!existsSync(file) && !extname(file)) file = `${file}.html`
+        if (!existsSync(file)) {
+          res.writeHead(404, { 'content-type': 'text/plain' })
+          res.end('not found')
+          return
+        }
+        res.writeHead(200, { 'content-type': MIME[extname(file)] ?? 'application/octet-stream' })
+        res.end(readFileSync(file))
+      }
+      catch (err) {
+        res.writeHead(500, { 'content-type': 'text/plain' })
+        res.end(String(err?.message ?? err))
+      }
+    })
+    server.listen(PORT, '127.0.0.1', () => ok(server))
+  })
+}
+
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+async function main() {
+  if (!existsSync(DIST)) {
+    console.error(`✖ 未找到构建产物:${DIST}\n  先执行:cd docs/site && npx vitepress build`)
+    process.exit(2)
+  }
+  if (!EXEC || !existsSync(EXEC)) {
+    console.error('✖ 未找到本机 Edge/Chrome')
+    process.exit(2)
+  }
+  mkdirSync(OUT, { recursive: true })
+  const server = await serve()
+  const base = `http://127.0.0.1:${PORT}${BASE_PATH}`
+  const browser = await puppeteer.launch({
+    executablePath: EXEC,
+    headless: 'new',
+    args: ['--no-sandbox', '--disable-dev-shm-usage', '--force-device-scale-factor=1', '--hide-scrollbars'],
+    defaultViewport: { width: WIDTH, height: 1000 },
+  })
+
+  const problems = []
+  let n = 0
+  try {
+    for (const [route, name, fullPage] of PAGES) {
+      const page = await browser.newPage()
+      const pageErrors = []
+      page.on('pageerror', e => pageErrors.push(String(e?.message ?? e)))
+      // 站点只声明 favicon.svg,浏览器仍会自动请求 /favicon.ico;这不是站点缺陷。
+      // 用带 URL 的 HTTP 失败事件判定,而不是靠 console 文案(它不含 URL)。
+      page.on('response', (r) => {
+        if (r.status() >= 400 && !r.url().endsWith('/favicon.ico')) pageErrors.push(`HTTP ${r.status()} ${r.url()}`)
+      })
+      page.on('requestfailed', (r) => {
+        if (!r.url().endsWith('/favicon.ico')) pageErrors.push(`REQUEST FAILED ${r.url()}`)
+      })
+      const resp = await page.goto(`${base}${route}`, { waitUntil: 'networkidle2', timeout: 45_000 })
+      if (!resp || resp.status() >= 400) problems.push(`${route} → HTTP ${resp?.status()}`)
+      // 等字体与首屏动画落定(站点有入场动画;截到中途会误判为"元素缺失")
+      await page.evaluate(() => document.fonts?.ready).catch(() => {})
+      await sleep(700)
+      const file = join(OUT, `${String(++n).padStart(2, '0')}-${name}.png`)
+      await page.screenshot({ path: file, fullPage })
+      const title = await page.title()
+      const h1 = await page.$eval('h1', el => el.textContent?.trim() ?? '').catch(() => '(no h1)')
+      // 首页是自定义布局(无 <main>),故取 <main> 缺省回落到 body
+      const bodyLen = await page.evaluate(() => {
+        const root = document.querySelector('main') ?? document.querySelector('.hw-wrap') ?? document.body
+        return (root?.innerText ?? '').replace(/\s+/g, ' ').trim().length
+      })
+      console.log(`✔ ${route.padEnd(26)} h1=${JSON.stringify(h1).slice(0, 40).padEnd(42)} text=${bodyLen}`)
+      if (bodyLen < 200) problems.push(`${route} → 正文过短(${bodyLen} 字),疑似渲染失败`)
+      if (!title) problems.push(`${route} → 无 <title>`)
+      if (pageErrors.length) problems.push(`${route} → ${pageErrors.length} 个前端/请求错误: ${pageErrors.slice(0, 2).join(' | ')}`)
+      await page.close()
+    }
+  }
+  finally {
+    await browser.close()
+    server.close()
+  }
+
+  console.log(`\n截图 ${n} 张 → ${OUT}`)
+  if (problems.length) {
+    console.log(`\n✖ 发现 ${problems.length} 个问题:`)
+    for (const p of problems) console.log(`  · ${p}`)
+    process.exit(1)
+  }
+  console.log('✔ 全部页面渲染正常(有 h1 / 正文非空 / 无前端错误)')
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})