cardbuddy 0.20.0 → 0.21.0

package/dist/vendored/skills/finmall-card-sync/scripts/api_batch_sync.mjs

@@ -80,6 +80,9 @@ const COVER_FETCH_TIMEOUT_MS = Number(process.env.CARDBUDDY_COVER_TIMEOUT_MS ||
 // FinMall 交易请求超时。IDC10001/IDC10012 偶发挂起（后端不响应），同样没有任何默认超时，
 // 一张卡挂住就会拖垮整批同步——所以和预览图一样，内层 abort + 外层 race 双重设防。
 const FINMALL_POST_TIMEOUT_MS = Number(process.env.CARDBUDDY_POST_TIMEOUT_MS || 30000);
+// 卡片预览图上传（IDC10014.do）超时。与切图上传同款设防：内层 AbortController +
+// 外层 Promise.race 兜住 page.evaluate 自身不返回（evaluate 无默认超时）。
+const PREVIEW_UPLOAD_TIMEOUT_MS = Number(process.env.CARDBUDDY_PREVIEW_UPLOAD_TIMEOUT_MS || 30000);
 
 function withTimeout(promise, ms, label) {
   let timer;
@@ -417,6 +420,175 @@ export async function saveCardToRemote(schema, { skeletonScreen = '', verify = t
   }
 }
 
+/**
+ * 在已认证页面上下文内以 multipart/form-data 上传卡片预览图（IDC10014.do）。
+ *
+ * 请求形态取自线上编辑器抓包（`/ubomp-web/IDC10014.do`），与切图上传（CC0000.do）的差异：
+ *   - 表单字段是 `cardId`（纯文本数字 cardId）+ `file`（二进制，filename 固定 `<cardId>.png`，
+ *     抓包里 Content-Type 为 application/octet-stream —— Blob 不带 type 时浏览器就是这个值，
+ *     这里照抄抓包，不做「更正确」的覆盖）；
+ *   - `sassAppId` / `sassWorkspaceId` 走**表单字段**（CC0000.do 是查询串）；
+ *   - 没有 `fileName` 纯文本字段；
+ *   - 鉴权头只有 `token`。
+ *
+ * token 仅在页面上下文内读取并直接用于请求，不回传 Node 侧、不打印、不落盘（与 finmallPost 同纪律）。
+ *
+ * @returns {Promise<string>} 原始响应文本（交由 parsePreviewUploadResponse 解析）
+ */
+async function postPreviewUpload(page, { cardId, fileName, base64, appId, workspaceId }) {
+  return withTimeout(
+    page.evaluate(
+      async ({ cardId, fileName, base64, appId, workspaceId, timeoutMs }) => {
+        const controller = new AbortController();
+        setTimeout(() => controller.abort(), timeoutMs);
+        const readSessionToken = () => {
+          try {
+            const raw = localStorage.getItem('_sessionId');
+            if (!raw) return '';
+            let value = JSON.parse(raw);
+            if (value && typeof value === 'object' && 'value' in value) value = value.value;
+            if (typeof value === 'string' && value.startsWith('"')) {
+              try {
+                value = JSON.parse(value);
+              } catch {
+                /* 保留原字符串 */
+              }
+            }
+            return typeof value === 'string' ? value : '';
+          } catch {
+            return '';
+          }
+        };
+        const sessionToken = readSessionToken();
+        if (!sessionToken) {
+          throw new Error('页面缺少会话凭据（localStorage._sessionId 为空），请先运行 finmall-session-navigator 登录。');
+        }
+        const binary = atob(base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+        const form = new FormData();
+        form.append('cardId', cardId);
+        // 抓包里该 part 的 Content-Type 是 application/octet-stream，filename 为 <cardId>.png
+        form.append('file', new Blob([bytes]), fileName);
+        form.append('sassAppId', String(appId));
+        form.append('sassWorkspaceId', String(workspaceId));
+        const response = await fetch(new URL('/ubomp-web/IDC10014.do', location.origin).href, {
+          method: 'POST',
+          headers: { token: sessionToken, Accept: '*/*' },
+          credentials: 'include',
+          body: form,
+          signal: controller.signal,
+        });
+        const text = await response.text();
+        if (!response.ok) throw new Error(`HTTP ${response.status}: ${text.slice(0, 200)}`);
+        return text;
+      },
+      { cardId, fileName, base64, appId, workspaceId, timeoutMs: PREVIEW_UPLOAD_TIMEOUT_MS },
+    ),
+    PREVIEW_UPLOAD_TIMEOUT_MS + 2000,
+    `上传卡片预览图 ${fileName}`,
+  );
+}
+
+/**
+ * 解析 IDC10014.do 响应（导出仅为单测可直接断言；正常路径走 uploadCardPreview）。
+ *
+ * 该接口的响应体形态没有可比对的既有文档，故按 FinMall 交易接口的通用信封
+ * （`{header:{errorCode,errorMsg}, body:{...}}`）做**宽松**判定：
+ *   - 空响应体 → 视为成功（HTTP 2xx 已由调用方保证，接口可能不返回业务体）；
+ *   - 非 JSON 非空 → 直接报错（多半是网关 HTML 错误页，不能当成功）；
+ *   - errorCode 存在且非 '0' → 抛错（BLEC0006 等会话失效特征会被 uploadCardPreview 捕获并重登重试）；
+ *   - 成功时尽力从 body 里捞预览图地址（字段名依 ubomp 同类接口习惯多键兜底），
+ *     捞不到不影响「上传成功」的结论。
+ *
+ * @param {string} text 原始响应文本
+ * @param {string} cardId 请求用的数字型 cardId（用于回显校验 / 日志）
+ * @returns {{ ok: boolean, url: string, cardId: string }}
+ */
+export function parsePreviewUploadResponse(text, cardId) {
+  const raw = String(text == null ? '' : text).trim();
+  if (!raw) return { ok: true, url: '', cardId: String(cardId == null ? '' : cardId) };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`预览图上传响应不是 JSON：${raw.slice(0, 300)}`);
+  }
+  const header = (parsed && parsed.header) || {};
+  const body = (parsed && parsed.body) || {};
+  // header 与 body 各自可能带 errorCode：**逐个**看，不能用 `a || b` 短路——
+  // header.errorCode='0' 是真值，会把 body 里的业务错误（如 PEO000003）整段盖掉。
+  const codes = [header.errorCode, body.errorCode].filter((c) => c != null && String(c).trim() !== '');
+  const bad = codes.find((c) => String(c) !== '0');
+  if (bad != null) {
+    throw new Error(
+      `FinMall 预览图上传失败 [errorCode=${bad}] ${header.errorMsg || body.errorMsg || ''} | ${raw.slice(0, 300)}`,
+    );
+  }
+  // 地址字段多键兜底：接口未回地址属正常（上传即生效），所以这里只做尽力提取。
+  const url =
+    body.picUrl || body.previewUrl || body.imageUrl || body.filePath || body.url ||
+    parsed.picUrl || '';
+  return {
+    ok: true,
+    url: typeof url === 'string' ? url : '',
+    cardId: String(body.cardId || cardId || ''),
+  };
+}
+
+/**
+ * 上传卡片预览图到远端（IDC10014.do）。供「推送」成功后由 server/core/cardSave.js 调用：
+ * 本地无头渲染出透明底 PNG → 交给已登录的 FinMall 后台会话上传，卡片列表缩略图随之更新。
+ *
+ * 与 saveCardToRemote 的会话纪律一致：saveCardToRemote 末尾会 disconnect，故本函数自行
+ * ensureFinMallSession 重新取一次连接（Chrome 已常驻时这一步是廉价的 attach）。
+ * 会话/权限失效命中 SESSION_INVALID_RE 时自动清 session 重登并重试一次。
+ *
+ * @param {{ cardId: string|number, pngBase64: string, appId?: string, workspaceId?: string }} opts
+ * @returns {Promise<{ ok: true, url: string, cardId: string, bytes: number }>}
+ */
+export async function uploadCardPreview({ cardId, pngBase64, appId, workspaceId } = {}) {
+  const id = String(cardId == null ? '' : cardId).trim();
+  if (!/^\d+$/.test(id)) {
+    throw new Error(`上传卡片预览图需要数字型 cardId（IDC10014.do 主键），收到：${JSON.stringify(cardId)}`);
+  }
+  const base64 = String(pngBase64 == null ? '' : pngBase64);
+  if (!base64) throw new Error('上传卡片预览图缺少 PNG 内容（pngBase64 为空）。');
+  const appIdv = appId || finmallConfig.appId;
+  const workspaceIdv = workspaceId || finmallConfig.workspaceId;
+  const fileName = `${id}.png`;
+
+  const session = await ensureFinMallSession();
+  const browser = session.browser;
+  try {
+    const context = browser.contexts()[0];
+    const page = context?.pages().find((p) => p.url().includes('finmall.com')) || context?.pages()[0];
+    if (!page) throw new Error('未能在后台 Chrome 中找到 FinMall 页面，请检查凭据或重新触发同步。');
+    await page.bringToFront();
+
+    const payload = { cardId: id, fileName, base64, appId: appIdv, workspaceId: workspaceIdv };
+    let parsed;
+    try {
+      parsed = parsePreviewUploadResponse(await postPreviewUpload(page, payload), id);
+    } catch (error) {
+      if (SESSION_INVALID_RE.test(String(error && error.message))) {
+        log.warn('会话/权限失效，自动重新登录后重试预览图上传', {
+          cardId: id,
+          reason: String(error && error.message).slice(0, 40),
+        });
+        await relogin(page);
+        parsed = parsePreviewUploadResponse(await postPreviewUpload(page, payload), id);
+      } else {
+        throw error;
+      }
+    }
+    log.ok('卡片预览图已上传', { cardId: id, fileName, url: parsed.url || '(接口未回地址)' });
+    return { ...parsed, bytes: Math.round((base64.length * 3) / 4) };
+  } finally {
+    try { await browser.disconnect() } catch { /* 后台 Chrome 常驻，仅断开连接 */ }
+  }
+}
+
 /**
  * 远端预览：复刻 ubomp-h5-sub PreviewPopover.vue 的 onPopoverShow 全链路。
  *  1) prepreview：先把当前编辑的卡片保存到远端（IDC10010.do，对齐 ubomp 的 prepreview 钩子）
@@ -520,11 +692,40 @@ export async function previewCardRemote(schema, { skeletonScreen = '', publish =
 }
 
 /**
- * 远端发布：取当前卡片远端最大版本号 +1，发布上线为新版本。
+ * FinMall 版本号格式：8 位「年份 + 4 位序号」，如 20260025。
+ * 该格式的最小值约 20200001，故任何 < 10000000 的纯数字都不符合格式
+ * （含旧实现首发时误写出的 1 / 2 / 3…）。
+ */
+const MIN_YEAR_SEQ_VERSION = 10000000;
+
+/**
+ * 由远端最大版本号推导「下一个待发布版本号」。
+ *   - 远端从未发布（maxVersion 为 null / 空 / '0'）→ `${当前年份}0001`，而不是裸 '1'；
+ *   - 已是「年份+4 位序号」→ 数值 +1。注意这里**不按年份重置**：跨年后沿用上一年的序号递增
+ *     （如 20250028 → 20250029），保证版本号单调递增，避免回退到比线上更小的值；
+ *   - 历史遗留的旧格式小版本（旧 bug 写出的 '1' 等）→ 视同首发，规范化为 `${当前年份}0001`，
+ *     数值上 20260001 > 2，不会造成版本回退，可自愈已受该 bug 影响的卡片。
+ * @param {string|number|null|undefined} maxVersion IDC10004 返回的 maxVersion
+ * @returns {string} 8 位版本号
+ * @example nextPublishVersion(null) // '20260001'
+ * @example nextPublishVersion('20260025') // '20260026'
+ * @example nextPublishVersion('1') // '20260001'
+ */
+export function nextPublishVersion(maxVersion) {
+  const raw = String(maxVersion == null ? '' : maxVersion).trim();
+  const num = Number(raw);
+  const valid = /^\d+$/.test(raw) && Number.isFinite(num) && num >= MIN_YEAR_SEQ_VERSION;
+  if (!valid) return `${new Date().getFullYear()}0001`;
+  return String(num + 1);
+}
+
+/**
+ * 远端发布：取当前卡片远端最大版本号，推导下一个版本号并发布上线。
  * 链路（对齐 ubomp 发布流程，仅两步）：
  *   1) IDC10004.do 取当前卡片最大版本号 maxVersion；
- *   2) IDC10016.do 以 maxVersion+1 作为新版本号发布（发布的是远端「当前已保存」的卡片内容——
+ *   2) IDC10016.do 以 nextPublishVersion(maxVersion) 作为新版本号发布（发布的是远端「当前已保存」的卡片内容——
  *      故发布前应先用「推送当前卡」把本地内容保存到远端，否则会发布陈旧内容）。
+ *      版本号格式为 8 位「年份 + 4 位序号」：远端从未发布时取 `${当前年份}0001`（不是裸 1）。
  * 会话由 ensureFinMallSession 自动保证；与 saveCardToRemote / syncCards / previewCardRemote
  * 共用同一套已登录后台 Chrome，命中会话/权限失效（BLEC0006 等）时自动清 session 重登重试一次。
  *
@@ -554,8 +755,7 @@ export async function publishCard(schema) {
       'IDC10004.do',
     )
     const maxVersion = String(maxResp && maxResp.maxVersion != null ? maxResp.maxVersion : '0')
-    const maxNum = Number(maxVersion)
-    const nextVersion = String(Number.isFinite(maxNum) ? maxNum + 1 : 1)
+    const nextVersion = nextPublishVersion(maxVersion)
     log.info('发布前取最大版本', { cardId, maxVersion, nextVersion })
 
     // 2) 以 maxVersion+1 发布（发布类型/平台等参数对齐 ubomp 发布弹窗的默认值）
@@ -620,6 +820,90 @@ export async function fetchCardLatestVersion(cardId) {
   }
 }
 
+/**
+ * 取远端「发布版本记录」分页列表：IDC10004.do 的 versionList（新→旧，最多一页 pageSize 条）。
+ * 供调试面板「导入信息」tab 的「发布版本记录」弹框渲染（版本号 / 平台 / 状态 / 发布时间）。
+ * 只读；与 fetchCardLatestVersion / fetchCardHistory 共用同一后台 FinMall 会话
+ * （ensureFinMallSession + finmallPostWithHeal，命中会话失效自动清 session 重登重试一次）。
+ *
+ * 响应体（逆向 innermanage 前端 inner_flamePublish 页面）：
+ *   body.versionList[] = { versionId, version, platformStatus（JSON 字符串，如 '["iOS","Android"]'）,
+ *                           publishStatus, createTime }
+ *   body.maxVersion / pageNo / pageSize / totalNums / totalPages
+ *
+ * publishStatus 枚举（逆向页面 statusEnum，见 34.*.js：{ UNPUB:'0', PUB:'1', FINISH:'2', STOP:'3' }；
+ * 页面渲染仅对 0/1 出标签「未发布 / 发布中」，2/3 依枚举名与「停止发布」动作（publishStatus:'3'）释义）：
+ *   0=未发布  1=发布中  2=已完成  3=已停止
+ *
+ * @param {string|number} cardId
+ * @param {{ pageNo?: number, pageSize?: number }} [opts]
+ * @returns {Promise<{ list: Array<object>, maxVersion: string, totalNums: number, totalPages: number }>}
+ */
+export async function fetchCardPublishVersions(cardId, { pageNo = 1, pageSize = 10 } = {}) {
+  if (cardId == null) {
+    throw new Error('缺少 cardId，无法查询发布版本记录（IDC10004.do 需要 cardId）。');
+  }
+  const appId = finmallConfig.appId;
+  const workspaceId = finmallConfig.workspaceId;
+  const id = String(cardId);
+  const session = await ensureFinMallSession();
+  const browser = session.browser;
+  try {
+    const context = browser.contexts()[0];
+    const page = context?.pages().find((p) => p.url().includes('finmall.com')) || context?.pages()[0];
+    if (!page) throw new Error('未能在后台 Chrome 中找到 FinMall 页面，请先运行 finmall-session-navigator 登录。');
+    await page.bringToFront();
+    const resp = await finmallPostWithHeal(
+      page,
+      `/ubomp-web/IDC10004.do?sassAppId=${appId}&sassWorkspaceId=${workspaceId}`,
+      {
+        channel: '',
+        pageNo,
+        pageSize,
+        publishStatus: '',
+        version: '',
+        cardId: id,
+        sassAppId: appId,
+        sassWorkspaceId: workspaceId,
+      },
+      'IDC10004.do',
+    );
+    const rawList = Array.isArray(resp && resp.versionList) ? resp.versionList : [];
+    const list = rawList.map((raw) => {
+      let platforms = [];
+      try {
+        const parsed = JSON.parse(raw.platformStatus || '[]');
+        if (Array.isArray(parsed)) platforms = parsed.map((p) => String(p));
+      } catch {
+        /* platformStatus 损坏时按空平台处理，不阻断列表 */
+      }
+      const status = String(raw.publishStatus == null ? '' : raw.publishStatus);
+      return {
+        versionId: String(raw.versionId == null ? '' : raw.versionId),
+        version: String(raw.version == null ? '' : raw.version),
+        platforms,
+        platformStr: platforms.join('、'),
+        publishStatus: status,
+        publishTime: String(raw.createTime == null ? '' : raw.createTime),
+      };
+    });
+    log.info('查询远端发布版本记录', {
+      cardId: id,
+      pageNo,
+      count: list.length,
+      totalNums: resp && resp.totalNums,
+    });
+    return {
+      list,
+      maxVersion: String(resp && resp.maxVersion != null ? resp.maxVersion : ''),
+      totalNums: Number(resp && resp.totalNums != null ? resp.totalNums : list.length) || list.length,
+      totalPages: Number(resp && resp.totalPages != null ? resp.totalPages : 1) || 1,
+    };
+  } finally {
+    try { await browser.disconnect(); } catch { /* ignore */ }
+  }
+}
+
 /**
  * 取远端「卡片历史版本时间线」：IDC10013 按 cardId 分页返回 schemaValueList（新→旧）。
  * 供编辑器「卡片历史记录」tab 渲染 git 式时间线。只读；与 fetchCardLatestVersion 共用
@@ -979,15 +1263,17 @@ async function fetchCardSchema(page, card, { appId, workspaceId }) {
 /** 清空过期会话并以保存的凭据重新登录（复用导航器的登录逻辑，全程在页面上下文内完成）。 */
 async function relogin(page) {
   await clearTimeoutPrompts(page);
-  await page
-    .evaluate(() => {
+  await withTimeout(
+    page.evaluate(() => {
       try {
         localStorage.clear();
       } catch {
         /* ignore */
       }
-    })
-    .catch(() => {});
+    }),
+    FINMALL_POST_TIMEOUT_MS,
+    'page.evaluate(localStorage.clear)',
+  ).catch(() => {});
   await page.reload({ waitUntil: "domcontentloaded", timeout: 15000 }).catch(() => {});
   await sleep(1500);
   const credentials = await loadCredentials();
@@ -1302,6 +1588,7 @@ async function findExistingCover(cardDir, id) {
 async function writeImportSidecar(cardDir, { appId, workspaceId, card, files, importMeta }) {
   try {
     const mod = importMeta || (await import(pathToFileURL(path.resolve(workspace, 'server', 'core', 'cardImportMeta.js')).href));
+    const raw = card.raw || {};
     const meta = mod.buildImportMeta({
       baseUrl: finmallConfig.baseUrl,
       appId,
@@ -1310,6 +1597,14 @@ async function writeImportSidecar(cardDir, { appId, workspaceId, card, files, im
       cardCode: card.id,
       cardName: card.title,
       files,
+      // 远端列表元数据原样快照：导入包（cards.json）的 picUrl / cardClassId / applyScene
+      // 只能从这里取真值，本地无处可推。缺了它导出侧只能伪造或留空，而留空会让
+      // 导入侧按空串推封面文件名、退化成卡目录路径并抛异常（2026-10-22 事故）。
+      remote: {
+        picUrl: typeof raw.picUrl === 'string' ? raw.picUrl : '',
+        cardClassId: raw.cardClassId == null ? '' : String(raw.cardClassId),
+        applyScene: raw.applyScene == null ? '' : String(raw.applyScene),
+      },
     });
     mod.writeImportMeta(cardDir, meta);
   } catch (e) {

package/dist/vendored/skills/finmall-session-navigator/scripts/finmall_login.mjs

@@ -54,6 +54,24 @@ const CHROME_CANDIDATES = [
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
+// page.evaluate 没有默认超时：FinMall 页面主线程被占 / 页面内 fetch 挂起（实测该环境确有
+// responseStatus=0 的常驻请求）时，裸 evaluate 永远不返回，连带 ensureFinMallSession 与
+// 整个同步任务永久挂起——同步中间件是单飞制，一个挂死的任务会让之后每次「远端同步」都拿到
+// 409「已有同步任务正在进行」，用户侧就是「点了同步、服务端再也不响应」。
+// 这里给每次 evaluate 套硬超时：Node 侧停止等待并抛明确错误（页面里仍在跑的那个 evaluate
+// 无法真正取消，但至少不会把同步任务与单飞锁一起拖死）。
+const EVALUATE_TIMEOUT_MS = Number(process.env.CARDBUDDY_EVALUATE_TIMEOUT_MS || 30000);
+
+function withTimeout(promise, ms, label) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label}超时（>${ms}ms），已放弃`)), ms);
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
 // ---------------------------------------------------------------------------
 // 凭据与请求体
 // ---------------------------------------------------------------------------
@@ -329,12 +347,17 @@ async function evaluateWithRetry(page, fn, arg, maxRetries = 5) {
   let lastError;
   for (let i = 0; i < maxRetries; i++) {
     try {
-      return await page.evaluate(fn, arg);
+      // 硬超时包裹：页面主线程被占 / 页面内 fetch 挂起时不让同步任务永久挂起
+      return await withTimeout(
+        page.evaluate(fn, arg),
+        EVALUATE_TIMEOUT_MS,
+        'page.evaluate',
+      );
     } catch (error) {
       lastError = error;
       const msg = String(error?.message || error);
       if (
-        /Execution context was destroyed|Target page.*has been closed|Frame was detached|Cannot find context/i.test(
+        /Execution context was destroyed|Target page.*has been closed|Frame was detached|Cannot find context|page\.evaluate\s*超时/i.test(
           msg,
         )
       ) {
@@ -444,9 +467,16 @@ export async function performLogin(page, credentials) {
   return evaluateWithRetry(
     page,
     async (input) => {
+      // 页面内 fetch 也必须自带超时：IM01001 / IM01002 挂起时（该环境实测有常驻不返回的请求），
+      // 没有 AbortController 就会把 performLogin → runFinmallLogin → ensureFinMallSession
+      // 整条链永久挂住。这里内层 abort + 外层 evaluateWithRetry 的硬超时双重设防。
+      const ctl = new AbortController();
+      const timer = setTimeout(() => ctl.abort(), input.timeoutMs);
+      try {
       const response = await fetch(input.endpoint, {
         method: "POST",
         credentials: "include",
+        signal: ctl.signal,
         headers: {
           Accept: "application/json, text/plain, */*",
           "Content-Type": "application/json;charset=UTF-8",
@@ -533,6 +563,7 @@ export async function performLogin(page, credentials) {
           {
             method: "POST",
             credentials: "include",
+            signal: ctl.signal,
             headers: {
               Accept: "application/json, text/plain, */*",
               "Content-Type": "application/json;charset=UTF-8",
@@ -603,8 +634,16 @@ export async function performLogin(page, credentials) {
         businessFailure: businessFailure || !loginSucceeded,
         sessionCreated: loginSucceeded,
       };
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+    {
+      endpoint: LOGIN_ENDPOINT,
+      menuEndpoint: MENU_ENDPOINT,
+      payload,
+      timeoutMs: EVALUATE_TIMEOUT_MS,
     },
-    { endpoint: LOGIN_ENDPOINT, menuEndpoint: MENU_ENDPOINT, payload },
   );
 }
 

package/dist/vendored/skills/mbank-design-gen/tools/screenshot.mjs

@@ -22,7 +22,16 @@ if (!input) {
 }
 const output = positional[1] || input.replace(/\.html$/i, '') + '.png';
 
-const browser = await chromium.launch();
+// 优先用 Playwright 自带浏览器；未下载（ms-playwright 缓存为空）时回退系统 Chrome，
+// 与仓库「Playwright + 系统 Chrome 验证」约定一致，避免强依赖 npx playwright install。
+let browser;
+try {
+  browser = await chromium.launch();
+} catch (err) {
+  if (!/Executable doesn't exist/.test(String(err?.message ?? err))) throw err;
+  console.error('[screenshot] 未找到 Playwright 内置浏览器，回退系统 Chrome');
+  browser = await chromium.launch({ channel: 'chrome' });
+}
 const page = await browser.newPage({
   viewport: { width: 375, height: 812 },
   deviceScaleFactor: 2, // @2x → 750 宽输出，与设计稿一致

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cardbuddy",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Local dev service for the CardBuddy card editor — decouples card CRUD (sync/save/validate/render-status/screenshot) from the static public editor, so the editor can be deployed to any static host while each developer runs a local service against their own card source.",
   "type": "module",
   "bin": {