ai-growth 1.1.0

package/dist/device/http.js

@@ -0,0 +1,170 @@
+import { ok, err, DomainError } from '../shared/result.js';
+import { runDailyRollover } from '../core/rollover.js';
+import { todayIn, resolveTimezone } from '../core/profile.js';
+import { deckSummary, renderCardAt } from './renderCard.js';
+import { applyDeviceReport } from './report.js';
+import { checkDeviceAccess, extractToken, deviceToken, isDeviceLanEnabled } from './token.js';
+export const DEVICE_PREFIX = '/api/device';
+export const SERVICE_NAME = 'ai-growth';
+function sendJson(res, status, body) {
+    const text = JSON.stringify(body, null, 2);
+    res.writeHead(status, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'no-store',
+    });
+    res.end(text);
+}
+function sendBinary(res, body) {
+    res.writeHead(200, {
+        'Content-Type': 'application/octet-stream',
+        'Content-Length': String(body.length),
+        'Cache-Control': 'no-store',
+    });
+    res.end(body);
+}
+function readBody(req) {
+    return new Promise((resolve) => {
+        let data = '';
+        req.on('data', (c) => { data += c; });
+        req.on('end', () => {
+            try {
+                resolve(data ? JSON.parse(data) : {});
+            }
+            catch {
+                resolve({});
+            }
+        });
+    });
+}
+/**
+ * 解析设备上报的电量，并**量化到 10% 一档**。
+ *
+ * 🔴 为什么要量化：卡片是现场用无头 Chrome 渲染的（1.1~1.2 秒），而缓存键是
+ *   `sha256(卡片 HTML)` —— 电量画在卡片的页脚里，所以电量一变，整张卡就得重渲一次。
+ *   实测：同一张卡 `bat=88` 命中缓存（1ms），`bat=87` 就变成 **1091ms**（重新渲染）。
+ *   而设备每次取卡都会上报当前电量，读数本身还有 ±1~2% 的抖动 —— 于是几乎每次
+ *   按上下键都在踩"电量变了→重渲"，用户感觉就是"切换要等一两秒"。
+ *   量化到 10% 一档，抖动被吸收掉，同时页脚那个电量仍然是有意义的参考值。
+ */
+export function parseBattery(v) {
+    if (v === null || v === '')
+        return null;
+    const n = Number(v);
+    if (!Number.isFinite(n))
+        return null;
+    const clamped = Math.max(-1, Math.min(100, Math.round(n)));
+    if (clamped < 0)
+        return clamped; // -1 = 读不到电量
+    return Math.min(100, Math.round(clamped / 10) * 10);
+}
+/**
+ * 后台把牌组里其它卡也渲一遍（**不阻塞响应**）。
+ *
+ * 渲染一张卡要 1.1~1.2 秒（无头 Chrome 现场画），而牌组通常只有 2~4 张。
+ * 设备是按上下键逐张翻的 —— 提前渲完，翻页就是缓存命中（几毫秒），
+ * 而不是每按一次都等一整次渲染。
+ *
+ * ⚠ 串行执行：同时拉起多个 Chrome 会把机器压住，反而拖慢正在等的那一次。
+ * ⚠ 预热失败不影响任何功能（用户翻到那张时照样会现场渲一次），所以这里吞掉异常。
+ */
+let warmingDeck = false;
+async function warmDeckInBackground(ctx, count, skipIndex, battery, dataDir) {
+    if (warmingDeck)
+        return;
+    warmingDeck = true;
+    try {
+        for (let i = 0; i < count; i++) {
+            if (i === skipIndex)
+                continue;
+            await renderCardAt(ctx, i, dataDir, { battery });
+        }
+    }
+    catch {
+        /* 预热是优化，失败不需要让任何人知道 */
+    }
+    finally {
+        warmingDeck = false;
+    }
+}
+/**
+ * 处理 `/api/device/*`。返回 true 表示已经响应（调用方不要再走后面的路由）。
+ */
+export async function handleDeviceRequest(args) {
+    const { ctx, req, res, path, url, cfg } = args;
+    if (!path.startsWith(DEVICE_PREFIX))
+        return false;
+    const lanEnabled = isDeviceLanEnabled(cfg, ctx());
+    const c = ctx();
+    const access = checkDeviceAccess({
+        lanEnabled,
+        expected: deviceToken(c),
+        provided: extractToken(req.headers['x-device-token'], url.searchParams.get('token')),
+    });
+    if (access === 'NOT_CONFIGURED') {
+        return sendJson(res, 503, err('DEVICE_NOT_CONFIGURED', '局域网访问已开启但还没有设备令牌。在电脑上运行 `ai-growth device --rotate` 生成一个。')), true;
+    }
+    if (access === 'TOKEN_REQUIRED' || access === 'TOKEN_INVALID') {
+        return sendJson(res, 401, err(access, access === 'TOKEN_REQUIRED'
+            ? '缺少设备令牌。请求头 X-Device-Token 或查询参数 token 必填。'
+            : '设备令牌不正确。在电脑上运行 `ai-growth device` 查看当前令牌。')), true;
+    }
+    const m = path.slice(DEVICE_PREFIX.length);
+    if (m === '/ping' && req.method === 'GET') {
+        return sendJson(res, 200, ok({
+            service: SERVICE_NAME,
+            today: todayIn(c),
+            timezone: resolveTimezone(c),
+            lan: lanEnabled,
+        })), true;
+    }
+    if (m === '/deck' && req.method === 'GET') {
+        runDailyRollover(c); // 与 /api/today 同一保证：设备永远看到"今天"，不会看到昨日残留
+        return sendJson(res, 200, ok(deckSummary(c, { battery: parseBattery(url.searchParams.get('bat')) }))), true;
+    }
+    if (m === '/status' && req.method === 'GET') {
+        runDailyRollover(c);
+        const s = deckSummary(c, { battery: parseBattery(url.searchParams.get('bat')) });
+        return sendJson(res, 200, ok({
+            today: s.today,
+            dateLabel: s.dateLabel,
+            deckId: s.deckId,
+            count: s.count,
+            doneCount: s.doneCount,
+            total: s.total,
+            stage: s.stage,
+            nextActionId: s.cards.find((x) => x.actionId)?.actionId ?? null,
+        })), true;
+    }
+    if (m === '/card' && req.method === 'GET') {
+        const raw = url.searchParams.get('i');
+        if (raw === null) {
+            return sendJson(res, 400, err('VALIDATION_ERROR', '缺少参数 i（第几张卡）')), true;
+        }
+        const index = Number(raw);
+        if (!Number.isInteger(index) || index < 0) {
+            return sendJson(res, 400, err('VALIDATION_ERROR', `参数 i 非法：${raw}`)), true;
+        }
+        runDailyRollover(c);
+        const battery = parseBattery(url.searchParams.get('bat'));
+        const card = await renderCardAt(c, index, cfg.dataDir, { battery });
+        if (!card) {
+            return sendJson(res, 404, err('NOT_FOUND', `卡序号 ${index} 越界（牌组可能刚变了，重新取 0 号即可）`)), true;
+        }
+        // 预热牌组里其它卡：设备按上下键翻页时就能命中缓存（几毫秒），而不是每次等 1.2 秒渲染。
+        // 故意不 await —— 它跑在后台，本次响应立刻返回。
+        void warmDeckInBackground(c, deckSummary(c, { battery }).count, index, battery, cfg.dataDir);
+        return sendBinary(res, card.payload), true;
+    }
+    if (m === '/action' && req.method === 'POST') {
+        const input = await readBody(req);
+        const actionId = typeof input.actionId === 'string' ? input.actionId : '';
+        const op = input.op;
+        const occurred = typeof input.occurredDateKey === 'string' ? input.occurredDateKey : undefined;
+        const reason = typeof input.reason === 'string' ? input.reason : undefined;
+        const result = applyDeviceReport(c, { actionId, op, occurredDateKey: occurred, reason });
+        const status = result.outcome === 'CONFLICT' ? 409 : 200;
+        return sendJson(res, status, ok(result)), true;
+    }
+    return sendJson(res, 404, err('NOT_FOUND', `未知的设备接口：${path}`)), true;
+}
+export { DomainError };

package/dist/device/png.js

@@ -0,0 +1,111 @@
+/**
+ * 极简 PNG 解码器 —— 只为解 Chrome headless 的 `--screenshot` 输出。
+ *
+ * 为什么自己写：设备卡是**服务端渲染**的（固件不碰中文字体），渲染管线是
+ * Chrome 截图 → PNG → RGB565。为这一个用途引入 native 依赖不值得，
+ * 而 PNG 解码所需的 inflate 是 Node 内置 zlib 就有的。
+ *
+ * 支持范围（正好覆盖 Chrome 的截图输出，实测为色彩类型 2/6、位深 8、非隔行）：
+ *   - 色彩类型 2（RGB）、6（RGBA）
+ *   - 位深 8
+ *   - 非隔行（interlace = 0）
+ *   - 全部 5 种扫描线滤波器
+ * 超出范围一律抛错，不做"尽力而为"的静默降级。
+ */
+import { inflateSync } from 'node:zlib';
+const SIG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+function paeth(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a);
+    const pb = Math.abs(p - b);
+    const pc = Math.abs(p - c);
+    if (pa <= pb && pa <= pc)
+        return a;
+    return pb <= pc ? b : c;
+}
+export function decodePng(buf) {
+    const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+    if (b.length < 8 + 25)
+        throw new Error('PNG_DECODE: buffer too small');
+    for (let i = 0; i < 8; i++)
+        if (b[i] !== SIG[i])
+            throw new Error('PNG_DECODE: bad signature');
+    let width = 0;
+    let height = 0;
+    let bitDepth = 0;
+    let colorType = 0;
+    let interlace = 0;
+    const idat = [];
+    let off = 8;
+    let sawIhdr = false;
+    while (off + 8 <= b.length) {
+        const len = b.readUInt32BE(off);
+        const type = b.toString('ascii', off + 4, off + 8);
+        const body = off + 8;
+        if (body + len + 4 > b.length)
+            throw new Error('PNG_DECODE: truncated chunk');
+        if (type === 'IHDR') {
+            if (len !== 13)
+                throw new Error('PNG_DECODE: bad IHDR length');
+            width = b.readUInt32BE(body);
+            height = b.readUInt32BE(body + 4);
+            bitDepth = b[body + 8];
+            colorType = b[body + 9];
+            interlace = b[body + 12];
+            sawIhdr = true;
+        }
+        else if (type === 'IDAT') {
+            idat.push(b.subarray(body, body + len));
+        }
+        else if (type === 'IEND') {
+            break;
+        }
+        off = body + len + 4;
+    }
+    if (!sawIhdr)
+        throw new Error('PNG_DECODE: no IHDR');
+    if (!idat.length)
+        throw new Error('PNG_DECODE: no IDAT');
+    if (interlace !== 0)
+        throw new Error('PNG_DECODE: interlaced PNG unsupported');
+    if (bitDepth !== 8)
+        throw new Error(`PNG_DECODE: bit depth ${bitDepth} unsupported (need 8)`);
+    if (colorType !== 2 && colorType !== 6) {
+        throw new Error(`PNG_DECODE: color type ${colorType} unsupported (need 2 or 6)`);
+    }
+    if (width <= 0 || height <= 0)
+        throw new Error('PNG_DECODE: zero-sized image');
+    const channels = colorType === 6 ? 4 : 3;
+    const stride = width * channels;
+    const raw = inflateSync(Buffer.concat(idat));
+    const expected = height * (stride + 1);
+    if (raw.length < expected) {
+        throw new Error(`PNG_DECODE: inflated ${raw.length} bytes, expected ${expected}`);
+    }
+    const out = new Uint8Array(stride * height);
+    let prev = new Uint8Array(stride);
+    for (let y = 0; y < height; y++) {
+        const ft = raw[y * (stride + 1)];
+        const line = raw.subarray(y * (stride + 1) + 1, y * (stride + 1) + 1 + stride);
+        const cur = out.subarray(y * stride, (y + 1) * stride);
+        for (let x = 0; x < stride; x++) {
+            const a = x >= channels ? cur[x - channels] : 0;
+            const bb = prev[x];
+            const c = x >= channels ? prev[x - channels] : 0;
+            let v = line[x];
+            if (ft === 1)
+                v += a;
+            else if (ft === 2)
+                v += bb;
+            else if (ft === 3)
+                v += (a + bb) >> 1;
+            else if (ft === 4)
+                v += paeth(a, bb, c);
+            else if (ft !== 0)
+                throw new Error(`PNG_DECODE: unknown filter type ${ft} on row ${y}`);
+            cur[x] = v & 0xff;
+        }
+        prev = cur;
+    }
+    return { width, height, channels, data: out };
+}

package/dist/device/provision.js

@@ -0,0 +1,185 @@
+/**
+ * 一条命令把 AI Passport 配好，并**自己确认成功**。
+ *
+ * 为什么需要它（产品层面的理由）：这仓库要作为「应用」发布到 FoloToy 玩法社区。
+ * 如果用户刷完之后还得跑几个脚本、或者让 Agent 一步步读日志排查，那就不是能发布的东西。
+ * 所以这里把整条链路收成一个命令，而且**验证也自己做掉** ——
+ * 前提是设备固件开机就直接进卡页并自动取卡（见固件 main.c 的 APP_DEMO_INDEX），
+ * 于是"配置→重启→取卡"的结论会直接出现在串口日志里，不需要用户按任何键。
+ *
+ * ⚠ 一个必须知道的前提：**串口控制台是 ASCII 通道**。
+ *   ESP-IDF 的 esp_console 在把输入交给命令前会过一条 sanitize()，
+ *   它只保留 isprint() 为真的字节，中文（UTF-8 的 0x80~0xFF）会被整段丢掉。
+ *   所以凭据含非 ASCII（或空格）时必须走 growth_set_hex，用 hex 把字节送过去。
+ *   这里自动判断该走哪条，调用方不用关心。
+ */
+import { request } from 'node:http';
+import { DomainError } from '../shared/result.js';
+import { findSerialPorts, SerialSession } from './serial.js';
+/**
+ * 本机 apiPort 上有没有服务在跑。
+ *
+ * 为什么要单独探一下：如果服务没起来，设备**一定**取不到卡，但那种失败要等到
+ * 串口日志里出现"取卡失败"才看得出来（几十秒后），而且报出来的原因是 Wi-Fi 层的，
+ * 会把人往错方向带。所以在动手之前先问一句，失败就直接说清是服务没跑。
+ * 401 也算"活着"——那说明服务在，只是我们没带令牌。
+ */
+export function probeService(port, timeoutMs = 1500) {
+    return new Promise((resolve) => {
+        const req = request({ host: '127.0.0.1', port, path: '/api/device/ping', method: 'GET', timeout: timeoutMs }, (res) => { res.resume(); resolve(true); });
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+        req.on('error', () => resolve(false));
+        req.end();
+    });
+}
+/**
+ * 固件侧 esp_console 的命令行上限（对应 growth_config.c 的 max_cmdline_length）。
+ *
+ * ⚠ 为什么要在宿主侧也拦一次：命令行编辑器**超长是静默丢字符**的 ——
+ * 命令照样能被解析，只是末尾少几个字符。最典型的表现是令牌被截断（中文 Wi-Fi 名
+ * 走 hex 后一行会明显变长，我们实测刚好 129 字符 > 当时的 128 上限），
+ * 于是设备一直回 401，而设备日志里只有"HTTP 401 令牌不对"，完全看不出是被截了。
+ * 与其让用户去猜，不如在发出去之前就拦住并说清楚。
+ */
+export const MAX_DEVICE_CMDLINE = 512;
+/** 留出余量：编辑器在临界点上的行为不值得去试 */
+export function commandFits(line) {
+    return line.length <= MAX_DEVICE_CMDLINE - 8;
+}
+/** 串口命令的单个参数：纯 ASCII 且不含空格才能直接传，否则必须走 hex */
+function isConsoleSafe(s) {
+    return /^[\x20-\x7e]*$/.test(s) && !s.includes(' ');
+}
+function toHex(s) {
+    return Buffer.from(s, 'utf8').toString('hex');
+}
+function pickPort(requested) {
+    const candidates = findSerialPorts();
+    if (requested)
+        return { path: requested, candidates };
+    if (candidates.length === 0) {
+        throw new DomainError('DEVICE_NOT_FOUND', '没有找到串口设备。请确认：①设备已开机 ②用的是能传数据的 USB 线（不是仅充电线）③直接插电脑而不是走 hub。');
+    }
+    if (candidates.length > 1) {
+        throw new DomainError('MULTIPLE_DEVICES', `找到多个串口：${candidates.map((c) => c.path).join('、')}。用 --port 明确指定要配哪一个，避免配错设备。`);
+    }
+    return { path: candidates[0].path, candidates };
+}
+/** 从 growth_status 的输出里抽出已经配置好的 ssid（没有则 null） */
+function parseSsid(statusText) {
+    const m = statusText.match(/wifi ssid\s*:\s*(.*)/);
+    if (!m)
+        return null;
+    const v = m[1].trim();
+    return v && v !== '(none)' ? v : null;
+}
+export async function provisionDevice(input) {
+    const steps = [];
+    const evidence = [];
+    const { path, candidates } = pickPort(input.serialPath);
+    const session = SerialSession.open(path);
+    try {
+        // ① 开端口会让设备复位（USB-Serial-JTAG），先把可能涌出的启动日志吃掉。
+        const boot = await session.drain(1500);
+        if (boot)
+            evidence.push(...boot.split('\n').filter((l) => l.trim()).slice(0, 3));
+        steps.push({ name: '找到串口并打开', ok: true, detail: `${path}（候选 ${candidates.length} 个）` });
+        // ② 读当前配置：判断"是不是已经配过了"，也确认控制台活着
+        const status = await session.sendAndWait('growth_status', ['configured :'], 6000);
+        if (!status.matched) {
+            throw new DomainError('DEVICE_NO_CONSOLE', '设备没有回应串口命令。可能是固件不是这一版（缺 AI Growth 页），或者串口被别的程序占着（网页刷机工具/monitor 都会占）。');
+        }
+        const previousSsid = parseSsid(status.text);
+        steps.push({
+            name: '读取设备当前配置',
+            ok: true,
+            detail: previousSsid ? `已配置过：${previousSsid}` : '尚未配置',
+        });
+        if (/wifi ssid/.test(status.text))
+            evidence.push(...status.text.split('\n').filter((l) => l.startsWith('wifi ssid')));
+        // ③ 写配置。凭据含非 ASCII/空格 → 必须 hex，否则控制台会把字节丢掉
+        const needsHex = !isConsoleSafe(input.ssid) || !isConsoleSafe(input.password);
+        const usedCommand = needsHex ? 'growth_set_hex' : 'growth_set';
+        const ssidArg = needsHex ? toHex(input.ssid) : input.ssid;
+        const passArg = needsHex ? toHex(input.password) : (input.password === '' ? '""' : input.password);
+        const line = [
+            usedCommand, ssidArg, passArg, input.host, String(input.apiPort), input.token,
+        ].join(' ');
+        if (!commandFits(line)) {
+            throw new DomainError('COMMAND_TOO_LONG', `这条配置命令有 ${line.length} 字符，超过设备的串口命令行上限（${MAX_DEVICE_CMDLINE}）。`
+                + '超长会被设备**静默截断**（末尾少几个字符，典型后果是令牌不完整 → 设备一直 401）。'
+                + '请缩短 Wi-Fi 名，或先 `ai-growth device --rotate` 换一个更短的令牌后重试。');
+        }
+        const saved = await session.sendAndWait(line, ['saved.', 'error:'], 8000);
+        if (saved.matched !== 'saved.') {
+            const errLine = (saved.text.match(/error:[^\n]*/) ?? ['设备没有回应写入命令'])[0];
+            steps.push({ name: '写入配置', ok: false, detail: errLine });
+            throw new DomainError('DEVICE_WRITE_FAILED', `设备拒绝了配置：${errLine}`);
+        }
+        steps.push({
+            name: '写入配置',
+            ok: true,
+            detail: `${usedCommand}${needsHex ? '（含非 ASCII/空格，已用 hex 编码绕过控制台的 ASCII 限制）' : ''}`,
+        });
+        if (input.skipVerify) {
+            return { serialPath: path, usedCommand, previousSsid, verdict: 'UNKNOWN', ok: true, steps, evidence };
+        }
+        // ④ 设备会立刻重启、开机直接进卡页并自动取卡 —— 结论就在日志里，不需要用户按键。
+        //    这几个 pattern 就是固件自己的结论行。
+        const verdictWait = input.verifyTimeoutMs ?? 30000;
+        const log = await session.drain(verdictWait);
+        const lines = log.split('\n').map((l) => l.trim()).filter(Boolean);
+        let verdict = 'UNKNOWN';
+        if (/显示第\s*\d+\s*\/\s*\d+\s*张/.test(log))
+            verdict = 'FETCHED';
+        else if (/连不上 Wi-Fi/.test(log))
+            verdict = 'WIFI_FAIL';
+        else if (/取卡失败/.test(log))
+            verdict = 'FETCH_FAIL';
+        else if (/还没配置/.test(log))
+            verdict = 'NOT_CONFIGURED';
+        for (const re of [/显示第.*/, /连不上 Wi-Fi.*/, /取卡失败.*/, /还没配置.*/, /wifi:mode.*/]) {
+            const hit = lines.find((l) => re.test(l));
+            if (hit)
+                evidence.push(hit);
+        }
+        const result = {
+            serialPath: path,
+            usedCommand,
+            previousSsid,
+            verdict,
+            ok: verdict === 'FETCHED',
+            steps,
+            evidence,
+        };
+        if (verdict === 'FETCHED') {
+            steps.push({ name: '设备端确认取卡成功', ok: true, detail: '日志里出现「显示第 N/M 张」' });
+        }
+        else {
+            steps.push({ name: '设备端确认取卡', ok: false, detail: `结论：${verdict}` });
+            result.nextAction = nextActionFor(verdict, input);
+        }
+        return result;
+    }
+    finally {
+        session.close();
+    }
+}
+/** 把设备端的失败结论翻译成"下一步该干什么"，让 Agent 不用自己猜 */
+function nextActionFor(verdict, input) {
+    switch (verdict) {
+        case 'WIFI_FAIL':
+            return `设备连不上 Wi-Fi「${input.ssid}」。两种最常见原因：`
+                + '① 这个网络只有 5GHz —— ESP32-C3 只支持 2.4GHz（很多路由器会用同一个名字同时广播 2.4G/5G，那就没问题，'
+                + '先确认名字在 2.4G 上也有）；② 密码不对。改完重跑本命令即可。';
+        case 'FETCH_FAIL':
+            return `Wi-Fi 通了，但设备够不到电脑（${input.host}:${input.apiPort}）。检查：`
+                + '① 服务是否以局域网模式在跑（AI_GROWTH_DEVICE_LAN=1 ai-growth serve；ai-growth device 会显示状态）；'
+                + '② 电脑与设备是否在同一个 Wi-Fi/局域网；③ 令牌是否与设备里的一致。';
+        case 'NOT_CONFIGURED':
+            return '设备仍认为未配置，说明配置没写进去。重跑本命令；仍失败就把串口日志发出来。';
+        default:
+            return '在等待窗口内没有看到设备的取卡结论。设备可能还在开机或卡在某一步 —— '
+                + '再跑一次本命令，或查看串口实时日志定位。';
+    }
+}

package/dist/device/render.js

@@ -0,0 +1,194 @@
+/**
+ * 设备卡渲染管线：HTML → Chrome headless 截图 → PNG → RGB565 → 磁盘缓存。
+ *
+ * 为什么走「服务端出图」而不是让设备自己画：
+ * AI Passport 默认的 Montserrat 字体没有中文字形，而目标标题是用户自由输入的
+ * 任意汉字（官方文档把这种情形定义为"动态内容需明确的字符契约"的高危场景）。
+ * 服务端把整张卡渲染成像素，固件就完全不必碰字库/字形覆盖。
+ *
+ * 安全边界说明：Chrome 只读一个临时 HTML、只写一个临时 PNG，两个路径都在
+ * 系统临时目录，不涉及用户的 Desktop/Documents/Downloads。
+ */
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { decodePng } from './png.js';
+export const CARD_WIDTH = 240;
+export const CARD_HEIGHT = 320;
+/** 单张卡的渲染上限。Chrome 冷启动 + 字体加载实测 1~2 秒，留足余量后硬超时。 */
+const RENDER_TIMEOUT_MS = Number(process.env.AI_GROWTH_RENDER_TIMEOUT_MS ?? 20000);
+const CHROME_CANDIDATES = [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+];
+export function findChrome() {
+    const override = process.env.AI_GROWTH_CHROME;
+    if (override && existsSync(override))
+        return override;
+    for (const p of CHROME_CANDIDATES)
+        if (existsSync(p))
+            return p;
+    return null;
+}
+/** RGBA/RGB 像素 → RGB565 小端字节流（面板原生格式） */
+export function toRgb565(png) {
+    const { width, height, channels, data } = png;
+    const out = Buffer.allocUnsafe(width * height * 2);
+    let o = 0;
+    for (let i = 0; i < width * height; i++) {
+        const s = i * channels;
+        const r = data[s];
+        const g = data[s + 1];
+        const b = data[s + 2];
+        const v = ((r & 0xf8) << 8) | ((g & 0xfc) << 3) | (b >> 3);
+        out[o++] = v & 0xff;
+        out[o++] = (v >> 8) & 0xff;
+    }
+    return out;
+}
+/**
+ * 用 Chrome headless 把一段 HTML 渲染成 PNG。
+ * 每张卡一次进程调用（约 1 秒）；上层按内容哈希做磁盘缓存，所以只会付一次。
+ *
+ * size 默认是设备卡的 240×320；字形覆盖检查要渲染更大的网格，所以开放出来。
+ * 调用方必须保证 HTML 的布局尺寸与这里一致（否则截出来的图会被裁掉）。
+ */
+export function screenshotPng(html, size = { width: CARD_WIDTH, height: CARD_HEIGHT }) {
+    const chrome = findChrome();
+    if (!chrome) {
+        return Promise.reject(new Error('CHROME_NOT_FOUND: 渲染设备卡需要 Chrome/Chromium。可用 AI_GROWTH_CHROME 指定可执行文件路径。'));
+    }
+    const stamp = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const htmlPath = join(tmpdir(), `aig-card-${stamp}.html`);
+    const pngPath = join(tmpdir(), `aig-card-${stamp}.png`);
+    const profileDir = join(tmpdir(), `aig-chrome-${stamp}`);
+    writeFileSync(htmlPath, html, 'utf8');
+    const args = [
+        '--headless=new',
+        '--disable-gpu',
+        '--no-sandbox',
+        '--no-first-run',
+        '--no-default-browser-check',
+        '--disable-extensions',
+        '--hide-scrollbars',
+        '--force-device-scale-factor=1',
+        `--user-data-dir=${profileDir}`,
+        `--window-size=${size.width},${size.height}`,
+        // 给字体加载与首帧留出确定的时间预算，避免截到空白帧
+        '--virtual-time-budget=1500',
+        `--screenshot=${pngPath}`,
+        `file://${htmlPath}`,
+    ];
+    return new Promise((resolve, reject) => {
+        // detached：Chrome 出图后不一定自己退出（实测会一直挂着），
+        // 所以不能等 close 事件，必须轮询截图文件并在拿到后主动杀整个进程组。
+        const child = spawn(chrome, args, { stdio: ['ignore', 'ignore', 'pipe'], detached: true });
+        let err = '';
+        child.stderr?.on('data', (d) => { err += String(d); });
+        let settled = false;
+        const cleanup = () => {
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+            catch { /* 已退出 */ }
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* 已退出 */ }
+            for (const p of [htmlPath, pngPath]) {
+                try {
+                    rmSync(p, { force: true });
+                }
+                catch { /* ignore */ }
+            }
+            try {
+                rmSync(profileDir, { recursive: true, force: true });
+            }
+            catch { /* ignore */ }
+        };
+        const fail = (e) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(e);
+        };
+        const done = (buf) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(buf);
+        };
+        child.on('error', (e) => fail(e));
+        const deadline = Date.now() + RENDER_TIMEOUT_MS;
+        let lastSize = -1;
+        let stable = 0;
+        const poll = () => {
+            if (settled)
+                return;
+            if (Date.now() > deadline) {
+                fail(new Error(`CHROME_TIMEOUT: ${RENDER_TIMEOUT_MS}ms 内没拿到截图。${err.slice(-300)}`));
+                return;
+            }
+            try {
+                if (existsSync(pngPath)) {
+                    const size = statSync(pngPath).size;
+                    // 连续两次大小一致才认为写完了（避免读到半个文件）
+                    if (size > 0 && size === lastSize)
+                        stable++;
+                    else
+                        stable = 0;
+                    lastSize = size;
+                    if (stable >= 2) {
+                        done(readFileSync(pngPath));
+                        return;
+                    }
+                }
+            }
+            catch (e) {
+                fail(e instanceof Error ? e : new Error(String(e)));
+                return;
+            }
+            setTimeout(poll, 80);
+        };
+        poll();
+    });
+}
+function cacheDir(dataDir) {
+    const d = join(dataDir, 'device-cache');
+    mkdirSync(d, { recursive: true });
+    return d;
+}
+/**
+ * 渲染一张卡并落到磁盘缓存。key 由调用方按「内容 + 状态」算好，
+ * 所以同一张卡（哪怕同一天多次看）只会真正渲染一次。
+ */
+export async function renderCardCached(html, key, dataDir) {
+    const hash = createHash('sha256').update(html).digest('hex').slice(0, 24);
+    const file = join(cacheDir(dataDir), `${hash}.rgb565`);
+    if (existsSync(file)) {
+        const pixels = readFileSync(file);
+        if (pixels.length === CARD_WIDTH * CARD_HEIGHT * 2) {
+            return { pixels, width: CARD_WIDTH, height: CARD_HEIGHT, cached: true };
+        }
+        // 尺寸不对说明缓存来自旧版本，丢掉重渲
+        try {
+            rmSync(file, { force: true });
+        }
+        catch { /* ignore */ }
+    }
+    const png = await screenshotPng(html);
+    const decoded = decodePng(png);
+    if (decoded.width !== CARD_WIDTH || decoded.height !== CARD_HEIGHT) {
+        throw new Error(`CARD_SIZE_MISMATCH: 渲染出 ${decoded.width}x${decoded.height}，期望 ${CARD_WIDTH}x${CARD_HEIGHT}`);
+    }
+    const pixels = toRgb565(decoded);
+    writeFileSync(file, pixels);
+    void key;
+    return { pixels, width: CARD_WIDTH, height: CARD_HEIGHT, cached: false };
+}