cardbuddy 0.11.0 → 0.12.1

package/dist/vendored/skills/dsl-card-generator/scripts/render_card.mjs

@@ -0,0 +1,801 @@
+#!/usr/bin/env node
+/**
+ * render_card.mjs —— 离线卡片渲染截图（不启动 npm run dev，也不占 5180/8787）。
+ *
+ * 自包含架构：
+ *   - 渲染页面来自 <skill>/vendor/preview 的构建产物（由工程根 npm run build:skill-preview 产出）；
+ *   - 卡片数据目录默认取 cwd 的 src/cards，也可用 DSL_CARD_CARDS_DIR 覆盖；
+ *   - 切图 /slices/* 由本脚本从 DSL_CARD_SLICES_DIR（默认 cwd/src/slices）直接提供；
+ *   - 运行时只依赖 Node 内置模块 + 系统 Chrome（CDP），不再依赖 vite/vue/playwright；
+ *   - 用纯 Node HTTP 托管构建产物，Chrome headless 打开后等 [data-card-ready]，
+ *     通过 CDP 截取 .phone__screen 元素，调用结束后立即关闭浏览器与 HTTP server。
+ *
+ * 用法：
+ *   node render_card.mjs --id <cardId> [--width 375] [--out render.png] [--format json|png]
+ *
+ * 渲染确定性（冷帧结论，2026-09 实测）：
+ *   - 会话首帧曾缺失卡片背景图/装饰图（同 schema 首帧 vs 热帧差 ~27% 像素）：根因是页面侧
+ *     「资源静默 300ms」启发式看不见「在途但尚未产生 ResourceTiming 条目」的请求，提前触发截图；
+ *   - 现改为 CDP Network 域追踪在途请求，截图前等网络静默（inflight 清空且 250ms 无新请求，
+ *     封顶 5s 防坏图挂死），首帧与热帧逐像素一致；调用方（训练评分 / lint 守护）无需暖机帧。
+ */
+import fs from 'node:fs'
+import http from 'node:http'
+import os from 'node:os'
+import readline from 'node:readline'
+import path from 'node:path'
+import { spawn, spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+import { cardsDir, slicesDir, previewDir } from './lib/paths.mjs'
+
+const DEFAULT_WIDTH = 375
+const NAV_TIMEOUT_MS = 30000
+const SETTLE_MS = 300
+// CDP 单条命令的兜底超时：浏览器崩溃/被杀时响应永远不会回来，无超时会让
+// 调用方（训练轮收尾、MCP 渲染、dev 预览）永久挂起。
+const CDP_SEND_TIMEOUT_MS = 60000
+// 预览 HTTP server 关闭兜底：Chrome 的 keep-alive 连接会让 server.close() 回调不触发。
+const SERVER_CLOSE_TIMEOUT_MS = 2000
+
+/* ------------------------------------------------------------------ */
+/* 数据读取                                                             */
+/* ------------------------------------------------------------------ */
+function deriveDataFromSchema(schema) {
+  const params = (schema && schema.dictionary && schema.dictionary.inputParams) || []
+  return Object.fromEntries(params.map((p) => [p.key, p.defaultValue]))
+}
+
+function readCardFiles(cardsRoot, id) {
+  const dir = path.join(cardsRoot, id)
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return null
+  let schema
+  try {
+    schema = JSON.parse(fs.readFileSync(path.join(dir, 'schema.json'), 'utf8'))
+  } catch {
+    return null
+  }
+  return { schema, data: deriveDataFromSchema(schema) }
+}
+
+/* ------------------------------------------------------------------ */
+/* 静态 HTTP 服务（构建产物 + 卡片数据 + 切图）                          */
+/* ------------------------------------------------------------------ */
+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',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+}
+
+function mimeFor(filePath) {
+  return MIME[path.extname(filePath).toLowerCase()] || 'application/octet-stream'
+}
+
+function sendFile(res, filePath, contentType) {
+  if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+    res.statusCode = 404
+    res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+    return res.end('Not found')
+  }
+  res.statusCode = 200
+  res.setHeader('Content-Type', contentType || mimeFor(filePath))
+  res.setHeader('Cache-Control', 'no-store')
+  fs.createReadStream(filePath).pipe(res)
+}
+
+function resolveStaticPath(pathname) {
+  const rel = pathname.replace(/^\/+/, '')
+  if (!rel || rel.includes('..')) return null
+  const filePath = path.join(previewDir, rel)
+  if (filePath !== previewDir && !filePath.startsWith(previewDir + path.sep)) return null
+  if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) return null
+  return filePath
+}
+
+function sendSlice(req, res, next) {
+  if (!req.url || !req.url.startsWith('/slices/')) return next()
+  const rel = decodeURIComponent(req.url.slice('/slices/'.length).split('?')[0])
+  if (!rel || rel.includes('..')) return next()
+  const file = path.join(slicesDir, rel)
+  if (file !== slicesDir && !file.startsWith(slicesDir + path.sep)) return next()
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return next()
+  res.statusCode = 200
+  res.setHeader('Content-Type', mimeFor(file))
+  res.setHeader('Cache-Control', 'no-store')
+  fs.createReadStream(file).pipe(res)
+}
+
+function createPreviewServer({ cardsRoot }) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const pathname = decodeURIComponent((req.url || '').split('?')[0])
+
+      if (pathname === '/' || pathname === '/standalone.html') {
+        return sendFile(res, path.join(previewDir, 'standalone.html'))
+      }
+
+      const ph = pathname.match(/^\/__ph__\/(\d+)x(\d+)$/)
+      if (ph) {
+        const pw = Math.max(1, Math.min(2000, Number(ph[1]) || 1))
+        const phh = Math.max(1, Math.min(2000, Number(ph[2]) || 1))
+        const phText = decodeURIComponent(new URL('http://x' + req.url).searchParams.get('text') || '缺素材')
+        const fontSize = Math.max(9, Math.min(14, Math.floor(Math.min(pw, phh) / 3)))
+        const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="' + pw + '" height="' + phh + '">'
+          + '<rect width="100%" height="100%" fill="#EDEFF3"/>'
+          + '<text x="50%" y="50%" font-size="' + fontSize + '" fill="#9AA0A6" text-anchor="middle"'
+          + ' dominant-baseline="middle" font-family="sans-serif">' + phText.replace(/[<>&]/g, '') + '</text></svg>'
+        res.statusCode = 200
+        res.setHeader('Content-Type', 'image/svg+xml')
+        res.setHeader('Cache-Control', 'no-store')
+        return res.end(svg)
+      }
+
+      const m = pathname.match(/^\/__standalone-card\/([^/]+)$/)
+      if (m) {
+        const files = readCardFiles(cardsRoot, decodeURIComponent(m[1]))
+        if (!files) {
+          res.statusCode = 404
+          res.setHeader('Content-Type', 'application/json; charset=utf-8')
+          return res.end(JSON.stringify({ error: 'card not found', id: decodeURIComponent(m[1]) }))
+        }
+        // iph.href.lu 占位链接 → 本地 /__ph__/ 路由（仅改渲染侧，schema 契约不变）
+        const rewritten = JSON.stringify(files).replace(
+          /https?:\/\/iph\.href\.lu\/(\d+)x(\d+)\?text=([^"\\]+)/g,
+          (all, w, h, text) => '/__ph__/' + w + 'x' + h + '?text=' + text)
+        res.statusCode = 200
+        res.setHeader('Content-Type', 'application/json; charset=utf-8')
+        res.setHeader('Cache-Control', 'no-store')
+        return res.end(rewritten)
+      }
+
+      if (pathname.startsWith('/slices/')) {
+        return sendSlice(req, res, () => {
+          res.statusCode = 404
+          res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+          res.end('Not found')
+        })
+      }
+
+      const staticPath = resolveStaticPath(pathname)
+      if (staticPath) return sendFile(res, staticPath)
+
+      res.statusCode = 404
+      res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+      res.end('Not found')
+    })
+
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      resolve({
+        port: server.address().port,
+        close: () => new Promise((resolveClose) => {
+          let settled = false
+          const finish = () => { if (!settled) { settled = true; resolveClose() } }
+          // keep-alive 连接不会自己断开 ⇒ server.close() 回调可能永不触发；
+          // 超时后强制断开全部连接兜底，保证调用方（训练轮/MCP/dev）能收尾退出。
+          const hardKill = setTimeout(() => {
+            try { server.closeAllConnections() } catch {}
+            setTimeout(finish, 300).unref?.()
+          }, SERVER_CLOSE_TIMEOUT_MS)
+          hardKill.unref?.()
+          try { server.closeIdleConnections() } catch {}
+          server.close(() => { clearTimeout(hardKill); finish() })
+        }),
+      })
+    })
+  })
+}
+
+/* ------------------------------------------------------------------ */
+/* Chrome + CDP 截屏                                                     */
+/* ------------------------------------------------------------------ */
+function findChromePath() {
+  const candidates = [
+    process.env.CHROME_PATH,
+    process.platform === 'darwin' ? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' : null,
+    process.platform === 'darwin' ? '/Applications/Chromium.app/Contents/MacOS/Chromium' : null,
+    'google-chrome',
+    'google-chrome-stable',
+    'chromium',
+    'chromium-browser',
+    'chrome',
+  ].filter(Boolean)
+
+  for (const c of candidates) {
+    if (c.includes('/')) {
+      if (fs.existsSync(c)) return c
+      continue
+    }
+    const r = spawnSync('which', [c], { encoding: 'utf8' })
+    if (r.status === 0 && r.stdout.trim()) return r.stdout.trim()
+  }
+  return null
+}
+
+function launchChrome() {
+  return new Promise((resolve, reject) => {
+    const executablePath = findChromePath()
+    if (!executablePath) return reject(new Error('未找到系统 Chrome（可设置 CHROME_PATH）'))
+
+    const userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dsl-card-chrome-'))
+    const child = spawn(
+      executablePath,
+      [
+        '--headless=new',
+        '--disable-gpu',
+        '--no-sandbox',
+        '--no-first-run',
+        '--no-default-browser-check',
+        '--hide-scrollbars',
+        '--remote-debugging-port=0',
+        `--user-data-dir=${userDataDir}`,
+        'about:blank',
+      ],
+      { stdio: ['ignore', 'pipe', 'pipe'] },
+    )
+
+    let wsUrl = ''
+    let settled = false
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      try { child.kill('SIGKILL') } catch {}
+      reject(new Error('Chrome DevTools 启动超时'))
+    }, 15000)
+
+    const onData = (chunk) => {
+      const text = String(chunk)
+      const matched = /DevTools listening on (ws:\/\/\S+)/.exec(text)
+      if (matched && !wsUrl) {
+        wsUrl = matched[1]
+        const portMatch = /ws:\/\/[^/:]+:(\d+)\//.exec(wsUrl)
+        settled = true
+        clearTimeout(timer)
+        resolve({ child, wsUrl, userDataDir, port: portMatch ? Number(portMatch[1]) : 0 })
+      }
+    }
+
+    child.stdout.on('data', onData)
+    child.stderr.on('data', onData)
+    child.on('error', (err) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      reject(err)
+    })
+    child.on('exit', (code) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      reject(new Error(`Chrome 提前退出（code ${code}）`))
+    })
+  })
+}
+
+class CDP {
+  constructor(socket) {
+    this.socket = socket
+    this.id = 0
+    this.pending = new Map()
+    this.events = []
+    this.bindingHandlers = new Map()
+    this.listeners = new Map()
+    socket.addEventListener('message', (ev) => this._onMessage(ev))
+    // 连接断开（浏览器退出/崩溃/被 SIGKILL）时立刻拒绝全部在途请求，
+    // 否则 send() 的 Promise 永不 settle，收尾 close() 卡死整轮。
+    const abortAll = () => this._abortPending(new Error('CDP WebSocket 已关闭'))
+    socket.addEventListener('close', abortAll)
+    socket.addEventListener('error', abortAll)
+  }
+
+  _abortPending(error) {
+    for (const entry of this.pending.values()) {
+      clearTimeout(entry.timer)
+      entry.reject(error)
+    }
+    this.pending.clear()
+  }
+
+  _onMessage(ev) {
+    let msg
+    try { msg = JSON.parse(ev.data) } catch { return }
+    if (!msg || !msg.id) {
+      if (msg?.method === 'Runtime.bindingCalled') {
+        const name = msg.params?.name
+        const handler = this.bindingHandlers.get(name)
+        if (handler) handler(msg.params?.payload || '')
+      }
+      if (msg?.method) {
+        this.events.push({ method: msg.method, params: msg.params })
+        if (this.events.length > 100) this.events.shift()
+        const handlers = this.listeners.get(msg.method)
+        if (handlers) for (const handler of handlers.slice()) {
+          try { handler(msg.params) } catch {}
+        }
+      }
+      return
+    }
+    if (!this.pending.has(msg.id)) return
+    const { resolve, reject, timer } = this.pending.get(msg.id)
+    this.pending.delete(msg.id)
+    clearTimeout(timer)
+    if (msg.error) reject(new Error(msg.error.message || JSON.stringify(msg.error)))
+    else resolve(msg.result)
+  }
+
+  send(method, params = {}, timeoutMs = CDP_SEND_TIMEOUT_MS) {
+    const id = ++this.id
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error(`CDP ${method} 超时 (${timeoutMs}ms)`))
+      }, timeoutMs)
+      timer.unref?.()
+      this.pending.set(id, { resolve, reject, timer })
+      try {
+        this.socket.send(JSON.stringify({ id, method, params }))
+      } catch (error) {
+        this.pending.delete(id)
+        clearTimeout(timer)
+        reject(error instanceof Error ? error : new Error(String(error)))
+      }
+    })
+  }
+
+  /** 订阅 CDP 事件，返回退订函数 */
+  on(method, handler) {
+    const list = this.listeners.get(method) || []
+    list.push(handler)
+    this.listeners.set(method, list)
+    return () => {
+      const current = this.listeners.get(method) || []
+      this.listeners.set(method, current.filter((h) => h !== handler))
+    }
+  }
+
+  /** 注册一个 CDP binding，返回一个在 binding 被调用时 resolve 的 Promise */
+  waitForBinding(name, timeoutMs = 10000) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.bindingHandlers.delete(name)
+        reject(new Error(`等待 binding "${name}" 超时 (${timeoutMs}ms)`))
+      }, timeoutMs)
+      this.bindingHandlers.set(name, (payload) => {
+        clearTimeout(timer)
+        this.bindingHandlers.delete(name)
+        resolve(payload)
+      })
+    })
+  }
+}
+
+function connectCDP(wsUrl) {
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocket(wsUrl)
+    socket.addEventListener('open', () => resolve(new CDP(socket)))
+    socket.addEventListener('error', () => reject(new Error('CDP WebSocket 连接失败')))
+  })
+}
+
+async function getPageTargetWsUrl(port) {
+  const listUrl = `http://127.0.0.1:${port}/json/list`
+  const res = await fetch(listUrl)
+  const targets = await res.json()
+  const page = targets.find((t) => t.type === 'page' && t.webSocketDebuggerUrl)
+  if (!page) throw new Error('未找到 Chrome 页面调试目标（/json/list）')
+  return page.webSocketDebuggerUrl
+}
+
+async function waitForExpression(cdp, expression, timeoutMs = NAV_TIMEOUT_MS) {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const res = await cdp.send('Runtime.evaluate', { expression, returnByValue: true })
+    if (res && res.result && res.result.value) return res
+    await new Promise((r) => setTimeout(r, 100))
+  }
+  throw new Error('等待渲染就绪超时（.phone__screen[data-card-ready]）')
+}
+
+function describeRuntimeEvents(events) {
+  return events.map(({ method, params }) => {
+    if (method === 'Runtime.consoleAPICalled') {
+      const text = (params.args || []).map((arg) => arg.value ?? arg.description ?? '').join(' ')
+      return `console.${params.type}: ${text}`
+    }
+    if (method === 'Runtime.exceptionThrown') {
+      const detail = params.exceptionDetails || {}
+      return `exception: ${detail.text} ${detail.exception?.description || ''}`
+    }
+    if (method === 'Log.entryAdded') {
+      const entry = params.entry || {}
+      return `log.${entry.level}: ${entry.text}`
+    }
+    return method
+  }).filter(Boolean).slice(-20).join(' | ')
+}
+
+/* ------------------------------------------------------------------ */
+/* 可复用渲染会话                                                       */
+/* ------------------------------------------------------------------ */
+/** 等网络静默：inflight 清空且 quietMs 内无新请求；超时返回 false（不阻塞截图） */
+async function waitNetworkIdle(inflight, { quietMs = 250, timeoutMs = 5000 } = {}) {
+  const deadline = Date.now() + timeoutMs
+  let quietStart = null
+  while (Date.now() < deadline) {
+    if (inflight.size === 0) {
+      if (quietStart === null) quietStart = Date.now()
+      else if (Date.now() - quietStart >= quietMs) return true
+    } else {
+      quietStart = null
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50))
+  }
+  return false
+}
+
+export async function createRenderSession({ cardsRoot = cardsDir } = {}) {
+  const htmlPath = path.join(previewDir, 'standalone.html')
+  if (!fs.existsSync(htmlPath)) {
+    throw new Error(`未找到自包含预览产物：${htmlPath}。请先在工程根目录运行 npm run build:skill-preview`)
+  }
+
+  const server = await createPreviewServer({ cardsRoot })
+  const chrome = await launchChrome()
+  const pageWsUrl = await getPageTargetWsUrl(chrome.port)
+  const cdp = await connectCDP(pageWsUrl)
+  await cdp.send('Page.enable')
+  await cdp.send('Runtime.enable')
+  // 网络在途追踪：截图前等网络静默，闭环「首帧缺背景图/字体」的冷帧根因
+  await cdp.send('Network.enable').catch(() => {})
+  const inflight = new Set()
+  cdp.on('Network.requestWillBeSent', (params) => { if (params.type !== 'WebSocket') inflight.add(params.requestId) })
+  cdp.on('Network.loadingFinished', (params) => inflight.delete(params.requestId))
+  cdp.on('Network.loadingFailed', (params) => inflight.delete(params.requestId))
+  cdp.on('Network.requestServedFromCache', (params) => inflight.delete(params.requestId))
+  // 注册渲染完成 binding（事件驱动，替代 SETTLE_MS 轮询）
+  try {
+    await cdp.send('Runtime.addBinding', { name: '__cardRenderComplete' })
+  } catch {}
+  let closed = false
+  let pageReady = false
+
+  async function render({
+    id,
+    width = DEFAULT_WIDTH,
+    captureHeight = null,
+    format = 'png',
+    outFile = null,
+    hotReload = false,
+    captureElements = false,
+  } = {}) {
+    if (closed) return { error: 'session-closed', message: '渲染会话已关闭' }
+    if (!id) return { error: 'missing-id', message: '缺少卡片 id' }
+
+    const card = readCardFiles(cardsRoot, id)
+    if (!card) return { error: 'card-not-found', id }
+    if (format !== 'png' && format !== 'json') {
+      return { error: 'invalid-format', message: 'format 仅支持 png 或 json' }
+    }
+
+    const startedAt = performance.now()
+    const url = `http://127.0.0.1:${server.port}/standalone.html?card=${encodeURIComponent(id)}&width=${encodeURIComponent(width)}`
+
+    try {
+      cdp.events.length = 0
+      await cdp.send('Emulation.setDeviceMetricsOverride', {
+        width: Math.ceil(Number(width)) + 40,
+        height: Math.max(2000, Math.ceil(Number(captureHeight || 2000)) + 40),
+        deviceScaleFactor: 1,
+        mobile: false,
+      })
+      // 热更新路径：同会话内已渲染过该页时，通过 fetch 刷新卡片数据 + 重新触发 boot，跳过整页导航
+      if (hotReload && pageReady) {
+        await cdp.send('Emulation.setDeviceMetricsOverride', {
+          width: Math.ceil(Number(width)) + 40,
+          height: Math.max(2000, Math.ceil(Number(captureHeight || 2000)) + 40),
+          deviceScaleFactor: 1,
+          mobile: false,
+        }).catch(() => {})
+        // 修改 URL 参数让 boot 函数用新 width，然后重新执行 boot
+        const reloadRes = await cdp.send('Runtime.evaluate', {
+          expression: `(async function(){history.replaceState(null,'','/standalone.html?card=${encodeURIComponent(id)}&width=${width}');await window.__bootCard&&window.__bootCard();return'ok'})()`,
+          returnByValue: true,
+          awaitPromise: true,
+        }).catch(() => ({ result: { value: null } }))
+        if (reloadRes?.result?.value === 'ok') {
+          // 外部图片（占位图等）加载慢于 boot：等资源静默 300ms 再截图
+          await cdp.send('Runtime.evaluate', {
+            expression: `new Promise((resolve)=>{var lastN=performance.getEntriesByType('resource').length,stable=0,tries=0;(function quiet(){var c=performance.getEntriesByType('resource').length;if(c===lastN){stable++}else{stable=0;lastN=c}tries++;if(stable>=6||tries>40){resolve('1');return}setTimeout(quiet,50)})()})`,
+            returnByValue: true,
+            awaitPromise: true,
+          }).catch(() => {})
+          await waitNetworkIdle(inflight)
+          const boxRes2 = await cdp.send('Runtime.evaluate', {
+            expression: `JSON.stringify((()=>{const el=document.querySelector('.phone__screen'); if(!el) return null; const r=el.getBoundingClientRect(); return {x:r.x,y:r.y,width:r.width,height:r.height};})())`,
+            returnByValue: true,
+          })
+          const box2 = boxRes2 && boxRes2.result && boxRes2.result.value ? JSON.parse(boxRes2.result.value) : null
+          if (box2 && box2.width && box2.height) {
+            const shot2 = await cdp.send('Page.captureScreenshot', {
+              format: 'png',
+              clip: { x: box2.x, y: box2.y, width: box2.width, height: box2.height, scale: 2 },
+              captureBeyondViewport: true,
+            })
+            const buffer2 = Buffer.from(shot2.data, 'base64')
+            return {
+              ok: true, source: 'standalone-hot', id,
+              width: Math.round(box2.width), height: Math.round(box2.height),
+              base64: buffer2.toString('base64'),
+              outFile: outFile ? path.resolve(outFile) : null,
+              ms: Math.round(performance.now() - startedAt),
+            }
+          }
+        }
+        // hot-reload 失败则 fallback 到正常导航
+      }
+
+      // 事件驱动：导航前注册 binding promise，页面渲染完成后 requestAnimationFrame 里回调
+      const renderDone = cdp.waitForBinding('__cardRenderComplete', NAV_TIMEOUT_MS).catch(() => null)
+      await cdp.send('Page.navigate', { url })
+      // 暴露 boot 函数供热更新复用（Vl 是 bundle 中的异步 boot 函数）
+      await cdp.send('Runtime.evaluate', { expression: `try{window.__bootCard=Vl}catch(e){window.__bootCard=null}` }).catch(() => {})
+      // 注入 rAF 检测器：data-card-ready 出现后等 2 帧（保证 layout）再触发 binding
+      await cdp.send('Runtime.evaluate', {
+        expression: `(function check(){var el=document.querySelector('.phone__screen');if(!(el&&el.hasAttribute('data-card-ready'))){setTimeout(check,30);return}requestAnimationFrame(()=>{requestAnimationFrame(()=>{var lastN=performance.getEntriesByType('resource').length,stable=0,tries=0;(function quiet(){var c=performance.getEntriesByType('resource').length;if(c===lastN){stable++}else{stable=0;lastN=c}tries++;if(stable>=6||tries>40){window.__cardRenderComplete&&__cardRenderComplete('1');return}setTimeout(quiet,50)})()})})})()`,
+      }).catch(() => {})
+      await renderDone
+      pageReady = true
+      // 截图前等网络静默：冷帧根因（背景图/字体在途时截图）在此闭环
+      await waitNetworkIdle(inflight)
+      const boxRes = await cdp.send('Runtime.evaluate', {
+        expression: `JSON.stringify((()=>{const el=document.querySelector('.phone__screen'); if(!el) return null; const r=el.getBoundingClientRect(); return {x:r.x,y:r.y,width:r.width,height:r.height};})())`,
+        returnByValue: true,
+      })
+      const box = boxRes && boxRes.result && boxRes.result.value ? JSON.parse(boxRes.result.value) : null
+      if (!box || !box.width || !box.height) {
+        return { error: 'capture-target-not-found', message: '.phone__screen 元素未找到' }
+      }
+
+      const shot = await cdp.send('Page.captureScreenshot', {
+        format: 'png',
+        clip: {
+          x: box.x,
+          y: box.y,
+          width: box.width,
+          height: captureHeight ? Math.min(box.height, Math.ceil(Number(captureHeight))) : box.height,
+          scale: 2,
+        },
+        captureBeyondViewport: true,
+      })
+      const buffer = Buffer.from(shot.data, 'base64')
+      let elementBoxes = null
+      if (captureElements) {
+        try {
+          const elRes = await cdp.send('Runtime.evaluate', {
+            expression: `(function(){
+              var scr = document.querySelector('.phone__screen');
+              if (!scr) return JSON.stringify([]);
+              var sr = scr.getBoundingClientRect();
+              var els = scr.querySelectorAll('[data-cid]');
+              var out = [];
+              els.forEach(function(el) {
+                var r = el.getBoundingClientRect();
+                if (r.width < 1 || r.height < 1) return;
+                var cls = el.getAttribute('data-class') || '';
+                var text = (el.textContent || '').trim();
+                // Input 类组件的占位文本在内部 <input placeholder> 属性上，textContent 为空；
+                // 评分/位置配对需要把它当作可见文本捕获（否则占位行被误判为文本缺失）。
+                if (!text) {
+                  // Input.vue 根元素即 <input>：自身优先，其次向后兼容包裹式实现
+                  var innerInput = (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') ? el : el.querySelector('input,textarea');
+                  if (innerInput) text = (innerInput.getAttribute('placeholder') || innerInput.value || '').trim();
+                }
+                var cs = window.getComputedStyle(el);
+                var fs = parseFloat(cs.fontSize) || 0;
+                var color = cs.color || '';
+                out.push({
+                  cid: el.getAttribute('data-cid') || '',
+                  cls: cls,
+                  text: text.slice(0, 60),
+                  x: Math.round((r.left - sr.left) * 100) / 100,
+                  y: Math.round((r.top - sr.top) * 100) / 100,
+                  w: Math.round(r.width * 100) / 100,
+                  h: Math.round(r.height * 100) / 100,
+                  fs: Math.round(fs * 100) / 100,
+                  color: color,
+                  scrollH: el.scrollHeight || 0,
+                  clientH: el.clientHeight || 0,
+                });
+              });
+              return JSON.stringify(out);
+            })()`,
+            returnByValue: true,
+          })
+          if (elRes?.result?.value) elementBoxes = JSON.parse(elRes.result.value)
+        } catch (e) { /* element extraction is best-effort */ }
+      }
+      const json = {
+        id,
+        mime: 'image/png',
+        width: Math.round(box.width),
+        height: Math.round(captureHeight ? Math.min(box.height, Number(captureHeight)) : box.height),
+        base64: buffer.toString('base64'),
+        elementBoxes: elementBoxes,
+      }
+
+      if (format === 'json') return { ok: true, source: 'standalone', ...json }
+
+      if (outFile) {
+        fs.mkdirSync(path.dirname(path.resolve(outFile)), { recursive: true })
+        fs.writeFileSync(outFile, buffer)
+      }
+      return {
+        ok: true,
+        source: 'standalone',
+        ...json,
+        outFile: outFile ? path.resolve(outFile) : null,
+        ms: Math.round(performance.now() - startedAt),
+      }
+    } catch (e) {
+      const runtime = describeRuntimeEvents(cdp.events)
+      return {
+        error: 'screenshot-failed',
+        message: String((e && e.message) || e) + (runtime ? ` | runtime: ${runtime}` : ''),
+      }
+    }
+  }
+
+  async function close() {
+    if (closed) return
+    closed = true
+    await cdp.send('Browser.close', {}, 5000).catch(() => {})
+    try { chrome.child.kill('SIGKILL') } catch {}
+    try { fs.rmSync(chrome.userDataDir, { recursive: true, force: true }) } catch {}
+    await server.close().catch(() => {})
+    try { cdp.socket.close() } catch {}
+  }
+
+  return { render, close }
+}
+
+/* ------------------------------------------------------------------ */
+/* 对外 API                                                             */
+/* ------------------------------------------------------------------ */
+export async function renderCardScreenshot({
+  id,
+  width = DEFAULT_WIDTH,
+  captureHeight = null,
+  format = 'png',
+  outFile = null,
+  cardsRoot = cardsDir,
+  captureElements = false,
+} = {}) {
+  if (!id) return { error: 'missing-id', message: '缺少卡片 id' }
+
+  let server = null
+  let session = null
+
+  try {
+    session = await createRenderSession({ cardsRoot })
+    return await session.render({ id, width, captureHeight, format, outFile, captureElements })
+  } catch (e) {
+    const runtime = session?.render ? describeRuntimeEvents([]) : ''
+    return {
+      error: 'screenshot-failed',
+      message: String((e && e.message) || e) + (runtime ? ` | runtime: ${runtime}` : ''),
+    }
+  } finally {
+    if (session) await session.close().catch(() => {})
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* CLI                                                                  */
+/* ------------------------------------------------------------------ */
+function parseArgs(argv) {
+  const out = { id: '', width: DEFAULT_WIDTH, format: 'png', outFile: '', keepAlive: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--id') out.id = argv[++i] || ''
+    else if (a === '--width') out.width = Number(argv[++i]) || DEFAULT_WIDTH
+    else if (a === '--format') out.format = argv[++i] === 'json' ? 'json' : 'png'
+    else if (a === '--out') out.outFile = argv[++i] || ''
+    else if (a === '--keep-alive') out.keepAlive = true
+    else if (a === '-h' || a === '--help') {
+      console.log([
+        'Usage: node render_card.mjs --id <cardId> [--width 375] [--out render.png] [--format json|png]',
+        '',
+        'Keep-alive mode (reuse Chrome + HTTP server across renders):',
+        '  node render_card.mjs --keep-alive',
+        '  Input one JSON object per line: {"id":"<cardId>","width":375,"outFile":"/tmp/render.png"}',
+        '  Output one JSON result per line. Close with Ctrl-D / stdin EOF.',
+      ].join('\n'))
+      process.exit(0)
+    }
+  }
+  if (!out.id && !out.keepAlive) {
+    console.error('[error] 缺少 --id')
+    process.exit(1)
+  }
+  return out
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+
+  if (args.keepAlive) {
+    const session = await createRenderSession()
+    const rl = readline.createInterface({ input: process.stdin, terminal: false })
+    try {
+      for await (const line of rl) {
+        const text = line.trim()
+        if (!text) continue
+        let request
+        try {
+          request = JSON.parse(text)
+        } catch (e) {
+          console.log(JSON.stringify({ ok: false, error: 'invalid-json', message: e.message }))
+          continue
+        }
+        if (!request.id || !request.outFile) {
+          console.log(JSON.stringify({ ok: false, error: 'invalid-request', message: 'keep-alive 渲染必须提供 id 和 outFile' }))
+          continue
+        }
+        const result = await session.render({
+          id: request.id,
+          width: request.width ?? DEFAULT_WIDTH,
+          captureHeight: request.captureHeight ?? null,
+          format: request.format ?? 'png',
+          outFile: request.outFile || null,
+        })
+        const { base64, ...summary } = result
+        console.log(JSON.stringify(summary))
+      }
+    } finally {
+      await session.close()
+    }
+    return
+  }
+
+  const result = await renderCardScreenshot({
+    id: args.id,
+    width: args.width,
+    format: args.format,
+    outFile: args.outFile || null,
+  })
+
+  if (result.error) {
+    console.error(`[error] ${result.message || result.error}`)
+    process.exit(1)
+  }
+
+  if (args.format === 'json') {
+    console.log(JSON.stringify(result, null, 2))
+  } else {
+    const outFile = args.outFile || path.join(process.cwd(), `${args.id}.png`)
+    if (!args.outFile) fs.writeFileSync(outFile, Buffer.from(result.base64, 'base64'))
+    console.log(outFile)
+  }
+}
+
+// 通过 realpath 归一化处理符号链接（.codex/skills → .workbuddy/skills）
+const _thisScript = fs.realpathSync(fileURLToPath(import.meta.url))
+const _invokedAs = (process.argv[1] && fs.existsSync(process.argv[1]))
+  ? fs.realpathSync(process.argv[1])
+  : process.argv[1]
+if (_invokedAs === _thisScript) {
+  main()
+}
+
+export default renderCardScreenshot