ai-growth 1.1.0

package/scripts/check-device-cards.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * 设备卡的「程序化布局断言」：用真实 Chrome 量每个元素的位置，
+ * 抓肉眼容易漏的溢出/重叠（完成页统计卡压字、长 meta 顶穿页脚、阶段节点横向溢出）。
+ *
+ * 为什么必须用真 Chrome 量而不是 jsdom：jsdom 没有排版引擎，
+ * `.wrap{bottom}` / `-webkit-line-clamp` 这类都不会生效，量出来恒为 0 —— 等于没测。
+ *
+ * 用法：node scripts/check-device-cards.mjs [--json]
+ * 退出码 1 = 有布局问题。
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DIST = join(HERE, '..', 'dist');
+
+const { buildCardHtml } = await import(join(DIST, 'device/card.js'));
+const { findChrome, CARD_WIDTH, CARD_HEIGHT } = await import(join(DIST, 'device/render.js'));
+const { buildDeck, dateLabelIn } = await import(join(DIST, 'device/deck.js'));
+
+const chrome = findChrome();
+if (!chrome) {
+  console.error('找不到 Chrome/Chromium，无法做布局测量。可用 AI_GROWTH_CHROME 指定路径。');
+  process.exit(2);
+}
+
+// ---- 用例：正常 + 边界（长标题 / 长 meta / 多阶段 / 无电量 / 全完成）----
+const base = {
+  dateLabel: dateLabelIn('Asia/Shanghai'),
+  dateKey: '2026-09-20',
+  stage: { title: 'Memory', order: 2, total: 5 },
+  items: [
+    { id: 'a1', kind: 'MAIN_QUEST', title: '实现最小 Agent Memory Demo', status: 'PLANNED', done: false, minutes: 60, why: 'Memory 是当前阶段的出口标准', completionCriteria: 'demo 能写入并召回' },
+    { id: 'a2', kind: 'DAILY', title: '散步 30 分钟', status: 'PLANNED', done: false, minutes: 30, why: '保持运动习惯' },
+    { id: 'a3', kind: 'DAILY', title: '读 20 页书', status: 'PLANNED', done: false, minutes: 20 },
+  ],
+  doneCount: 0, total: 3, battery: 72,
+  facts: { evidence: 37, mainDone: 6 },
+};
+const doneItems = base.items.map((i) => ({ ...i, done: true, status: 'COMPLETED' }));
+
+const cases = [
+  ['总览', { ...base }, { kind: 'overview', title: 'x' }],
+  ['总览·部分完成', { ...base, items: base.items.map((i, n) => ({ ...i, done: n === 0 })), doneCount: 1 }, { kind: 'overview', title: 'x' }],
+  ['总览·空条目', { ...base, items: [], total: 0, doneCount: 0 }, { kind: 'overview', title: 'x' }],
+  ['总览·无阶段', { ...base, stage: null }, { kind: 'overview', title: 'x' }],
+  ['任务·主线', { ...base }, { kind: 'task', itemIndex: 0, title: 'x' }],
+  ['任务·日常', { ...base }, { kind: 'task', itemIndex: 1, title: 'x' }],
+  ['任务·无附加信息', { ...base, items: [{ id: 'x', kind: 'DAILY', title: '给妈妈打个电话', status: 'PLANNED', done: false }], total: 1, doneCount: 0 }, { kind: 'task', itemIndex: 0, title: 'x' }],
+  ['任务·已完成', { ...base, items: [{ ...base.items[0], done: true, status: 'COMPLETED' }], total: 1, doneCount: 1 }, { kind: 'task', itemIndex: 0, title: 'x' }],
+  ['完成页', { ...base, items: doneItems, doneCount: 3 }, { kind: 'alldone', title: 'x' }],
+  ['完成页·无阶段', { ...base, items: doneItems, doneCount: 3, stage: null }, { kind: 'alldone', title: 'x' }],
+  ['无计划', { ...base, items: [], total: 0, doneCount: 0, stage: null }, { kind: 'noplan', title: 'x' }],
+  ['离线', { ...base, offlineSince: '9月20日 08:12' }, { kind: 'offline', title: 'x' }],
+  ['离线·从未同步', { ...base }, { kind: 'offline', title: 'x' }],
+  ['开机', { ...base, battery: null, stage: null }, { kind: 'booting', title: 'x' }],
+  ['未配置', { ...base, battery: null, stage: null }, { kind: 'setup', title: 'x' }],
+  // ---- 压力 ----
+  ['压力·超长标题', { ...base, items: [{ id: 'x', kind: 'MAIN_QUEST', title: '把公司里那套离线优先的同步协议重新设计一遍并写清边界条件', status: 'PLANNED', done: false, minutes: 90, why: '这是当前阶段唯一的出口标准，也是整个系统最脆的部分', completionCriteria: '有一份能被人独立读懂并复现的协议文档，且包含失败路径' }], total: 1, doneCount: 0, battery: -1 }, { kind: 'task', itemIndex: 0, title: 'x' }],
+  ['压力·超长阶段名', { ...base, stage: { title: '把 Agent 的记忆系统从零搭起来并跑通端到端', order: 4, total: 5 } }, { kind: 'overview', title: 'x' }],
+  ['压力·12 阶段', { ...base, stage: { title: '打磨与交付', order: 11, total: 12 }, battery: 8 }, { kind: 'overview', title: 'x' }],
+  ['压力·20 阶段', { ...base, stage: { title: '打磨与交付', order: 3, total: 20 }, battery: 8 }, { kind: 'overview', title: 'x' }],
+  ['压力·50 阶段', { ...base, stage: { title: '长跑', order: 40, total: 50 }, battery: 8 }, { kind: 'overview', title: 'x' }],
+  ['压力·超长每日标题', { ...base, items: [{ id: 'x', kind: 'DAILY', title: '把今天要交付的那份文档从头到尾再读一遍并逐条核对是否覆盖了所有边界条件', status: 'PLANNED', done: false }], total: 1, doneCount: 0 }, { kind: 'task', itemIndex: 0, title: 'x' }],
+  ['压力·3 条长标题', { ...base, items: ['把公司里那套离线优先的同步协议重新设计一遍并写清边界条件', '把今天要交付的那份文档从头到尾再读一遍并逐条核对', '给所有早年的同事逐个写一封说明近况的邮件'].map((t, n) => ({ id: 'x' + n, kind: n === 0 ? 'MAIN_QUEST' : 'DAILY', title: t, status: 'PLANNED', done: false })), total: 3, doneCount: 0, stage: null }, { kind: 'overview', title: 'x' }],
+];
+
+const MEASURE = `
+<script>
+(() => {
+  const issues = [];
+  const card = document.querySelector('.card');
+  const cr = card.getBoundingClientRect();
+  const ft = document.querySelector('.ft');
+  const fr = ft ? ft.getBoundingClientRect() : null;
+  const CONTENT = ['.wrap', '.list', '.ttl', '.meta', '.big', '.done', '.dc', '.facts', '.track', '.stg', '.row', '.hint'];
+  for (const sel of CONTENT) {
+    for (const el of document.querySelectorAll(sel)) {
+      const r = el.getBoundingClientRect();
+      if (r.width === 0 && r.height === 0) continue;
+      if (r.right > cr.right + 0.5) issues.push(sel + ' 横向溢出 ' + (r.right - cr.right).toFixed(1) + 'px');
+      if (r.bottom > cr.bottom + 0.5) issues.push(sel + ' 纵向溢出卡片 ' + (r.bottom - cr.bottom).toFixed(1) + 'px');
+      if (fr && !el.closest('.ft') && r.bottom > fr.top + 1) {
+        issues.push(sel + ' 压住页脚 ' + (r.bottom - fr.top).toFixed(1) + 'px');
+      }
+    }
+  }
+  const nd = document.querySelectorAll('.nd').length;
+  if (nd > 12) issues.push('阶段节点 ' + nd + ' 个（>12，轨道会溢出）');
+  const pre = document.createElement('pre');
+  pre.id = '__report';
+  pre.textContent = JSON.stringify(issues);
+  document.body.appendChild(pre);
+})();
+</script>`;
+
+/** 用 Chrome --dump-dom 跑页面内的测量脚本，把结果读回来 */
+function measure(html) {
+  const dir = mkdtempSync(join(tmpdir(), 'aig-layout-'));
+  const file = join(dir, 'card.html');
+  writeFileSync(file, html.replace('</body>', MEASURE + '</body>'), 'utf8');
+  return new Promise((resolve) => {
+    const child = spawn(chrome, [
+      '--headless=new', '--disable-gpu', '--no-sandbox', '--no-first-run',
+      '--no-default-browser-check', '--disable-extensions',
+      `--user-data-dir=${join(dir, 'profile')}`,
+      '--virtual-time-budget=1200', '--dump-dom', `file://${file}`,
+    ], { stdio: ['ignore', 'pipe', 'ignore'], detached: true });
+    let out = '';
+    child.stdout.on('data', (d) => { out += String(d); });
+    const finish = () => {
+      try { process.kill(-child.pid, 'SIGKILL'); } catch { /* 已退出 */ }
+      try { child.kill('SIGKILL'); } catch { /* 已退出 */ }
+      try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+      const m = out.match(/<pre id="__report">([\s\S]*?)<\/pre>/);
+      resolve(m ? JSON.parse(m[1]) : null);
+    };
+    child.on('close', finish);
+    child.on('error', finish);
+    setTimeout(finish, 15000);
+  });
+}
+
+const asJson = process.argv.includes('--json');
+let failed = 0;
+const rows = [];
+
+for (const [name, state, spec] of cases) {
+  const res = await measure(buildCardHtml(state, spec));
+  if (!res) {
+    rows.push({ name, ok: false, issues: ['测量失败（Chrome 没回吐报告）'] });
+    failed++;
+    continue;
+  }
+  rows.push({ name, ok: res.length === 0, issues: res });
+  if (res.length) failed++;
+}
+
+// 牌组组成也要核一遍：没任务 → 只一张 noplan；全完成 → 末尾补 alldone
+const deckChecks = [];
+deckChecks.push(['空计划 → noplan', JSON.stringify(buildDeck({ ...base, items: [], total: 0, doneCount: 0 }).map((c) => c.kind)) === '["noplan"]']);
+deckChecks.push(['有任务 → overview 打头', buildDeck(base)[0].kind === 'overview']);
+deckChecks.push(['全完成 → 末位 alldone', buildDeck({ ...base, items: doneItems, doneCount: 3 }).at(-1).kind === 'alldone']);
+deckChecks.push(['未全完成 → 无 alldone', !buildDeck({ ...base, doneCount: 1 }).some((c) => c.kind === 'alldone')]);
+
+// 自检：往一张本来合格的卡里塞一个必然越界的元素，测量脚本必须报出来。
+// 没有这一步的话，一个恒为绿的检查等于没检查。
+const poison = buildCardHtml(base, { kind: 'overview', title: 'x' }).replace(
+  '</body>',
+  '<div class="wrap" style="position:absolute;top:282px;left:0;width:400px;height:80px"></div></body>'
+);
+const poisonRes = await measure(poison);
+const selfTest = Array.isArray(poisonRes) && poisonRes.length > 0;
+
+if (asJson) {
+  console.log(JSON.stringify({ failed, rows, deckChecks, selfTest }, null, 2));
+} else {
+  console.log(`设备卡布局测量（${cases.length} 张，真实 Chrome ${CARD_WIDTH}×${CARD_HEIGHT}）\n`);
+  for (const r of rows) {
+    console.log(`${r.ok ? '✓' : '✗'} ${r.name}`);
+    for (const i of r.issues) console.log(`    · ${i}`);
+  }
+  console.log('\n牌组组成：');
+  for (const [label, ok] of deckChecks) {
+    if (!ok) failed++;
+    console.log(`${ok ? '✓' : '✗'} ${label}`);
+  }
+  console.log(`\n自检（故意塞越界元素，必须被报出）：${selfTest ? '✓ 检查有效' : '✗ 检查失效 —— 上面的绿色不可信'}`);
+  if (!selfTest) failed++;
+  console.log(failed ? `\n✗ 共 ${failed} 处问题` : `\n✓ 全部通过`);
+}
+
+process.exit(failed ? 1 : 0);

package/scripts/doctor.sh

@@ -0,0 +1,194 @@
+#!/usr/bin/env bash
+# AI Growth — 健康检查（doctor）
+# 逐项验证：Node / 依赖 / 构建 / 数据库 / launchd / MCP / Web UI / 数据可写 / 时区
+# 退出码：0 全部通过；1 存在失败项
+
+set -uo pipefail
+
+PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DATA_DIR="${AI_GROWTH_DATA_DIR:-$HOME/.ai-growth}"
+PLIST_LABEL="com.lairey.ai-growth.daemon"
+PLIST_DEST="$HOME/Library/LaunchAgents/${PLIST_LABEL}.plist"
+NODE_BIN="$(command -v node || true)"
+
+PASS=0; FAIL=0; INFO=0
+ok()   { printf "  \033[0;32m✓\033[0m %s\n" "$1"; PASS=$((PASS+1)); }
+bad()  { printf "  \033[0;31m✗\033[0m %s\n" "$1"; FAIL=$((FAIL+1)); }
+info() { printf "  \033[0;33m-\033[0m %s\n" "$1"; INFO=$((INFO+1)); }
+head_() { printf "\n\033[1m%s\033[0m\n" "$1"; }
+
+printf "\033[1mAI Growth Doctor\033[0m\n项目：%s\n数据：%s\n" "$PROJECT_DIR" "$DATA_DIR"
+
+# 1. Node
+head_ "运行环境"
+if [ -n "$NODE_BIN" ]; then
+  V="$("$NODE_BIN" -p 'process.versions.node')"
+  MAJOR="$("$NODE_BIN" -p 'process.versions.node.split(".")[0]')"
+  if [ "$MAJOR" -ge 20 ]; then ok "node v$V"; else bad "node v$V 版本过低（需要 >= 20）"; fi
+else
+  bad "未找到 node"
+fi
+
+# 2. 依赖
+head_ "依赖"
+if [ -d "$PROJECT_DIR/node_modules/better-sqlite3" ]; then ok "better-sqlite3 已安装"; else bad "better-sqlite3 缺失（运行 npm install）"; fi
+if [ -d "$PROJECT_DIR/node_modules/@modelcontextprotocol/sdk" ]; then ok "MCP SDK 已安装"; else bad "MCP SDK 缺失（运行 npm install）"; fi
+if [ -d "$PROJECT_DIR/node_modules/zod" ]; then ok "zod 已安装"; else bad "zod 缺失（运行 npm install）"; fi
+
+# 3. 构建产物
+head_ "构建"
+for f in dist/mcp/server.js dist/daemon/main.js dist/api/server.js dist/db/cli.js dist/db/migrations/V1__init.sql dist/ui/index.html; do
+  if [ -f "$PROJECT_DIR/$f" ]; then ok "$f"; else bad "$f 缺失（运行 npm run build）"; fi
+done
+
+# 3b. 构建产物是否与源码同步（曾出现 cp -R 套娃导致 dist 静默陈旧）
+STALE=0
+for pair in "src/db/migrations/V1__init.sql:dist/db/migrations/V1__init.sql" \
+            "src/ui/index.html:dist/ui/index.html" \
+            "src/ui/app.js:dist/ui/app.js" \
+            "src/ui/style.css:dist/ui/style.css"; do
+  S="${pair%%:*}"; D="${pair##*:}"
+  if [ -f "$PROJECT_DIR/$S" ] && [ -f "$PROJECT_DIR/$D" ]; then
+    cmp -s "$PROJECT_DIR/$S" "$PROJECT_DIR/$D" || { bad "构建产物陈旧：$D ≠ ${S}（运行 npm run build）"; STALE=1; }
+  fi
+done
+[ "$STALE" -eq 0 ] && ok "dist 与 src 一致（migration / UI 均已同步）"
+
+# 3c. 套娃目录（cp -R 到已存在目录会产生 dist/ui/ui）
+NESTED="$(find "$PROJECT_DIR/dist" -maxdepth 3 -type d -name ui -o -maxdepth 3 -type d -name migrations 2>/dev/null | sed -n '2,$p' | grep -E "/(ui/ui|migrations/migrations)$" || true)"
+if [ -n "$NESTED" ]; then
+  bad "存在套娃目录：$(echo "$NESTED" | tr '\n' ' ')（npm run clean && npm run build）"
+else
+  ok "无套娃目录"
+fi
+
+# 4. 数据库
+head_ "数据库"
+if [ -f "$DATA_DIR/growth.db" ]; then
+  ok "growth.db 存在"
+  if [ -n "$NODE_BIN" ]; then
+    APPLIED="$("$NODE_BIN" -e "
+      const D=require('$PROJECT_DIR/node_modules/better-sqlite3');
+      const db=new D('$DATA_DIR/growth.db',{readonly:true});
+      try{
+        const r=db.prepare('SELECT COUNT(*) n FROM _migrations').get();
+        const t=db.prepare(\"SELECT COUNT(*) n FROM sqlite_master WHERE type='table'\").get();
+        console.log(r.n+'|'+t.n);
+      }catch(e){console.log('ERR');}
+    " 2>/dev/null)"
+    if [ "$APPLIED" = "ERR" ]; then bad "无法读取 schema（数据库可能损坏）"; else
+      M="${APPLIED%%|*}"; T="${APPLIED##*|}"
+      ok "migration 已应用：$M 个；表数量：$T"
+    fi
+  fi
+else
+  bad "growth.db 不存在（运行 node dist/db/cli.js migrate）"
+fi
+
+# 5. 数据目录可写
+head_ "数据目录"
+if [ -d "$DATA_DIR" ]; then
+  if [ -w "$DATA_DIR" ]; then ok "$DATA_DIR 可写"; else bad "$DATA_DIR 不可写"; fi
+else
+  bad "$DATA_DIR 不存在"
+fi
+
+# 6. 时区
+head_ "时区"
+if [ -n "$NODE_BIN" ]; then
+  TZ_="$(AI_GROWTH_DATA_DIR="$DATA_DIR" "$NODE_BIN" -e "
+    process.env.AI_GROWTH_TZ=process.env.AI_GROWTH_TZ||Intl.DateTimeFormat().resolvedOptions().timeZone;
+    console.log(process.env.AI_GROWTH_TZ);
+  " 2>/dev/null)"
+  if [ -n "$TZ_" ]; then ok "解析为 $TZ_"; else bad "无法解析时区"; fi
+fi
+
+# 7. launchd
+head_ "常驻服务（launchd）"
+UID_NUM="$(id -u)"
+if [ "$(uname -s)" != "Darwin" ]; then
+  info "非 macOS，跳过（Linux 需改为 systemd unit）"
+elif [ ! -f "$PLIST_DEST" ]; then
+  bad "plist 未安装（运行 ./scripts/install.sh）"
+else
+  ok "plist 已安装：$PLIST_DEST"
+  if ! launchctl list >/dev/null 2>&1; then
+    info "当前进程无权查询 launchd（正常，非故障）——plist 会在下次登录时自动加载"
+    printf "     要立刻生效，在「终端」执行：launchctl bootstrap gui/%s \"%s\"\n" "$UID_NUM" "$PLIST_DEST"
+    printf "     验证是否在跑：launchctl list | grep %s\n" "$PLIST_LABEL"
+  elif launchctl list 2>/dev/null | grep -q "$PLIST_LABEL"; then
+    LINE="$(launchctl list | grep "$PLIST_LABEL" | head -1)"
+    PID="$(echo "$LINE" | awk '{print $1}')"
+    if [ "$PID" = "-" ]; then
+      bad "daemon 未在运行（已加载但进程退出，查看 $DATA_DIR/daemon-stderr.log）"
+    else
+      ok "daemon 运行中（pid ${PID}）"
+    fi
+  else
+    info "服务尚未加载——下次登录会自动加载；想立刻生效在「终端」执行："
+    printf "     launchctl bootstrap gui/%s \"%s\"\n" "$UID_NUM" "$PLIST_DEST"
+  fi
+fi
+
+# 8. MCP server 可启动
+head_ "MCP Server"
+if [ -f "$PROJECT_DIR/dist/mcp/server.js" ] && [ -n "$NODE_BIN" ]; then
+  TMP_OUT="$(mktemp -t aigrowth-mcp)"
+  # stdio MCP server 在 stdin EOF 时会正常退出，故用 sleep 管道保持 stdin 打开。
+  # 注意：直接在主 shell 取 $!，不要用子 shell + PID 文件（存在竞态）。
+  { sleep 5; } | AI_GROWTH_DATA_DIR="$DATA_DIR" "$NODE_BIN" "$PROJECT_DIR/dist/mcp/server.js" >"$TMP_OUT" 2>&1 &
+  MCP_PID=$!
+  sleep 3
+
+  ALIVE=0
+  kill -0 "$MCP_PID" 2>/dev/null && ALIVE=1
+
+  if grep -q "MCP server ready" "$TMP_OUT" 2>/dev/null; then
+    ok "启动成功：DB 打开 + migration + tools 注册完成"
+    if [ "$ALIVE" -eq 1 ]; then ok "进程保持运行（pid ${MCP_PID}）"; fi
+  elif [ "$ALIVE" -eq 1 ]; then
+    ok "进程运行中（pid ${MCP_PID}），未捕获就绪日志"
+  else
+    bad "MCP server 启动失败：$(head -3 "$TMP_OUT" 2>/dev/null | tr '\n' ' ')"
+  fi
+
+  kill "$MCP_PID" 2>/dev/null || true
+  pkill -P "$MCP_PID" 2>/dev/null || true
+  rm -f "$TMP_OUT"
+else
+  bad "dist/mcp/server.js 缺失"
+fi
+
+# 9. 面板 API / Web UI
+head_ "面板 API"
+PORT="${AI_GROWTH_API_PORT:-4580}"
+# 用 node 直连 127.0.0.1，不要用 curl：受限环境的 HTTP 代理会把本地请求变成 502，误判为"未运行"
+PANEL_OK=0
+if [ -n "$NODE_BIN" ]; then
+  PANEL_OUT="$(AI_GROWTH_PROBE_PORT="$PORT" "$NODE_BIN" -e "
+    const http=require('http');
+    const req=http.get({host:'127.0.0.1',port:process.env.AI_GROWTH_PROBE_PORT,path:'/api/health',timeout:2500},res=>{
+      let d='';res.on('data',c=>d+=c);res.on('end',()=>{console.log(res.statusCode+'|'+d.replace(/\s+/g,''));process.exit(0)});
+    });
+    req.on('timeout',()=>{console.log('TIMEOUT');process.exit(0)});
+    req.on('error',e=>{console.log('ERR:'+e.code);process.exit(0)});
+  " 2>/dev/null)"
+  case "$PANEL_OUT" in
+    200*) PANEL_OK=1 ;;
+  esac
+fi
+if [ "$PANEL_OK" -eq 1 ]; then
+  ok "面板可访问：http://127.0.0.1:${PORT}（由 daemon 或 npm run api 提供）"
+else
+  info "面板未运行（daemon 会自带面板；或手动：npm run api）"
+fi
+
+# 汇总
+printf "\n\033[1m结果：%d 项通过，%d 项失败" "$PASS" "$FAIL"
+[ "$INFO" -gt 0 ] && printf "，%d 项提示" "$INFO"
+printf "\033[0m\n"
+if [ "$FAIL" -gt 0 ]; then
+  printf "\033[0;31m存在失败项，请按上方提示修复。\033[0m\n"
+  exit 1
+fi
+printf "\033[0;32m核心检查全部通过。\033[0m\n"

package/scripts/gen-device-assets.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * 生成 AI Passport 固件内置的「兜底卡」资源，并顺带校验中文字形覆盖。
+ *
+ * 为什么兜底卡要在【构建期】出图：
+ *   设备的开机卡、离线卡、未配置卡必须在不联网、没配置的情况下也能显示中文。
+ *   而固件里没有可用的中文字库（见 docs/development/engineering/lvgl-chinese-fonts.md）。
+ *   所以这三张图在构建期就用与运行时完全相同的 HTML/CSS 渲染成 RGB565 塞进 Flash，
+ *   设备端一个汉字都不用画 —— 中文显示问题在宿主侧一次性解决。
+ *
+ * 用法：
+ *   npm run build && node scripts/gen-device-assets.mjs \
+ *     --out <ai-passport>/main/assets/growth \
+ *     --preview <ai-passport>/assets/growth/firmware
+ *
+ * 产物（与仓库里 rock-paper-scissors 示例的布局一致：
+ * 只有二进制进 main/assets/，给人看的预览和说明进 assets/）：
+ *   <out>/booting.rgb565  offline.rgb565  setup.rgb565   240×320 RGB565 小端，各 153600 字节
+ *   <out>/manifest.json                                  尺寸/哈希/字形覆盖结论
+ *   <preview>/<name>.png                                 预览图（不参与固件）
+ *
+ * 退出码：0 = 资源生成且字形覆盖检查通过；非 0 = 生成失败或发现缺字（不会留下"看起来成功"的产物）。
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, '..');
+
+function argValue(flag, fallback) {
+  const i = process.argv.indexOf(flag);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+
+const outDir = resolve(argValue('--out', join(root, 'out', 'device-assets')));
+const previewDir = resolve(argValue('--preview', join(outDir, 'preview')));
+const distDir = join(root, 'dist', 'device');
+
+if (!existsSync(join(distDir, 'card.js'))) {
+  console.error('未找到 dist/device/card.js —— 先跑 `npm run build`。');
+  process.exit(2);
+}
+
+const { buildCardHtml } = await import(join(distDir, 'card.js'));
+const { screenshotPng, toRgb565, CARD_WIDTH, CARD_HEIGHT } = await import(join(distDir, 'render.js'));
+const { decodePng } = await import(join(distDir, 'png.js'));
+const { renderGlyphMasks, classifyCoverage } = await import(join(distDir, 'fontCoverage.js'));
+const { encodeCardPayload, buildCardMeta, CARD_W, CARD_H } = await import(join(distDir, 'deck.js'));
+
+/** 与 check-device-cards.mjs 保持同一套"最坏情况"素材，避免两边覆盖不一致 */
+const BASE_ITEMS = [
+  { id: 'a1', kind: 'MAIN_QUEST', title: '实现最小 Agent Memory Demo', status: 'PLANNED', done: false, minutes: 60, why: 'Memory 是当前阶段的出口标准', completionCriteria: 'demo 能写入并召回' },
+  { id: 'a2', kind: 'DAILY', title: '散步 30 分钟', status: 'PLANNED', done: false, minutes: 30, why: '保持运动习惯' },
+  { id: 'a3', kind: 'DAILY', title: '读 20 页书', status: 'PLANNED', done: false, minutes: 20 },
+];
+const BASE = {
+  dateLabel: '9月20日 周日',
+  dateKey: '2026-09-20',
+  stage: { title: '跑通端到端最小闭环', order: 3, total: 6 },
+  items: BASE_ITEMS,
+  doneCount: 0,
+  total: BASE_ITEMS.length,
+  battery: 76,
+  facts: { evidence: 14, mainDone: 3 },
+};
+
+/**
+ * 要写进 Flash 的兜底卡（必须成功）。
+ * ⚠ dateLabel 一律留空：这三张卡是构建期渲染的，设备上没有 RTC；
+ *   把构建日的日期烧进去 = 设备天天说"今天是 9 月 20 日"。时间只能由服务端给。
+ * 后面那几张"覆盖用"的卡只用来把字符集铺开，不产出资源。
+ */
+const FALLBACK = [
+  ['booting', { ...BASE, dateLabel: '', dateKey: '', items: [], total: 0, doneCount: 0, battery: null, stage: null }, { kind: 'booting', title: '正在连接' }],
+  ['offline', { ...BASE, dateLabel: '', dateKey: '', items: [], total: 0, doneCount: 0, battery: null, stage: null }, { kind: 'offline', title: '连不上电脑' }],
+  ['setup', { ...BASE, dateLabel: '', dateKey: '', items: [], total: 0, doneCount: 0, battery: null, stage: null }, { kind: 'setup', title: '还没配置' }],
+];
+
+const COVERAGE_ONLY = [
+  ['总览', { ...BASE }, { kind: 'overview', title: 'x' }],
+  ['总览·12 阶段', { ...BASE, stage: { title: '打磨与交付', order: 11, total: 12 } }, { kind: 'overview', title: 'x' }],
+  ['任务·主线', { ...BASE }, { kind: 'task', itemIndex: 0, title: 'x' }],
+  ['任务·无附加信息', { ...BASE, items: [{ id: 'x', kind: 'DAILY', title: '给妈妈打个电话', status: 'PLANNED', done: false }], total: 1, doneCount: 0 }, { kind: 'task', itemIndex: 0, title: 'x' }],
+  ['完成页', { ...BASE, items: BASE_ITEMS.map((i) => ({ ...i, done: true })), doneCount: 3 }, { kind: 'alldone', title: 'x' }],
+  ['无计划', { ...BASE, items: [], total: 0, doneCount: 0, stage: null }, { kind: 'noplan', title: 'x' }],
+  ['压力·超长标题', { ...BASE, items: [{ id: 'x', kind: 'MAIN_QUEST', title: '把公司里那套离线优先的同步协议重新设计一遍并写清边界条件', status: 'PLANNED', done: false, minutes: 90, why: '这是当前阶段唯一的出口标准，也是整个系统最脆的部分', completionCriteria: '有一份能被人独立读懂并复现的协议文档，且包含失败路径' }], total: 1, doneCount: 0, battery: -1 }, { kind: 'task', itemIndex: 0, title: 'x' }],
+  ['压力·下标数字', { ...BASE, stage: { title: '长跑', order: 40, total: 50 }, battery: 8 }, { kind: 'overview', title: 'x' }],
+  ['标点与符号', { ...BASE, items: [{ id: 'x', kind: 'DAILY', title: '写《周报》初稿（第 3 版）；含 13% 数据、A/B 对比', status: 'PLANNED', done: false, why: '用全角标点与括号测字形：，。；：！？（）《》、' }], total: 1, doneCount: 0 }, { kind: 'task', itemIndex: 0, title: 'x' }],
+];
+
+/** 从卡片 HTML 里抽出"真正会画出来的文字"，交给字形覆盖检查 */
+function visibleText(html) {
+  return html
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'")
+    .replace(/&nbsp;/g, ' ');
+}
+
+async function renderOne(state, spec) {
+  const html = buildCardHtml(state, spec);
+  const png = await screenshotPng(html, { width: CARD_WIDTH, height: CARD_HEIGHT });
+  const img = decodePng(png);
+  if (img.width !== CARD_WIDTH || img.height !== CARD_HEIGHT) {
+    throw new Error(`${spec.kind}: 渲染出 ${img.width}x${img.height}，期望 ${CARD_WIDTH}x${CARD_HEIGHT}`);
+  }
+  return { html, png, pixels: toRgb565(img) };
+}
+
+async function main() {
+  mkdirSync(outDir, { recursive: true });
+  mkdirSync(previewDir, { recursive: true });
+
+  const manifest = {
+    card: { width: CARD_W, height: CARD_H, pixelFormat: 'RGB565 little-endian' },
+    generatedFrom: 'scripts/gen-device-assets.mjs',
+    assets: [],
+    coverage: null,
+  };
+
+  // 1) 生成兜底卡（先删旧的，避免"生成失败但旧文件还在"的假成功）
+  for (const [name] of FALLBACK) {
+    const f = join(outDir, `${name}.rgb565`);
+    if (existsSync(f)) rmSync(f, { force: true });
+  }
+
+  const texts = [];
+  for (const [name, state, spec] of FALLBACK) {
+    const { html, png, pixels } = await renderOne(state, spec);
+    if (pixels.length !== CARD_W * CARD_H * 2) {
+      throw new Error(`${name}: RGB565 长度 ${pixels.length}，期望 ${CARD_W * CARD_H * 2}`);
+    }
+    // 自检：用与运行时相同的编码器包一层，再解回来，确保这 153600 字节能被固件原样解析
+    const meta = buildCardMeta(state, spec, 0, 1);
+    const payload = encodeCardPayload(meta, pixels);
+    if (payload.length !== 14 + Buffer.byteLength(JSON.stringify(meta), 'utf8') + pixels.length) {
+      throw new Error(`${name}: 载荷长度自检失败`);
+    }
+    writeFileSync(join(outDir, `${name}.rgb565`), pixels);
+    writeFileSync(join(previewDir, `${name}.png`), png);
+    texts.push(visibleText(html));
+    manifest.assets.push({
+      name,
+      file: `${name}.rgb565`,
+      bytes: pixels.length,
+      sha256: createHash('sha256').update(pixels).digest('hex').slice(0, 16),
+      payloadBytes: payload.length,
+    });
+    console.log(`✓ ${name}.rgb565  ${pixels.length} 字节`);
+  }
+
+  // 2) 把字符集铺开（只渲染不落盘，用于覆盖检查）
+  for (const [name, state, spec] of COVERAGE_ONLY) {
+    const html = buildCardHtml(state, spec);
+    texts.push(visibleText(html));
+    void name;
+  }
+
+  // 3) 字形覆盖：让同一套 Chrome 把每个字符画进网格，再与"缺字参考格"逐像素比对
+  const allText = texts.join('');
+  const masks = await renderGlyphMasks(allText);
+  const coverage = classifyCoverage(masks);
+  manifest.coverage = {
+    ok: coverage.ok,
+    detectorOk: coverage.detectorOk,
+    checked: coverage.checked,
+    missing: coverage.missing,
+    noInk: coverage.noInk,
+    message: coverage.message,
+  };
+  console.log(`${coverage.ok ? '✓' : '✗'} ${coverage.message}`);
+
+  writeFileSync(join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+
+  if (!coverage.ok) {
+    console.error('字形覆盖检查未通过 —— 不交付这些资源。');
+    process.exit(1);
+  }
+
+  const total = manifest.assets.reduce((n, a) => n + a.bytes, 0);
+  console.log(`\n资源目录 ${outDir}`);
+  console.log(`共 ${manifest.assets.length} 张，合计 ${total} 字节（约 ${(total / 1024).toFixed(0)} KB Flash）`);
+}
+
+await main();