cardbuddy 0.19.3 → 0.21.0

package/dist/vendored/server/core/cardHistoryRemote.js

@@ -0,0 +1,203 @@
+import { pathToFileURL } from 'node:url'
+import { findCardDir } from './cardSidecar.js'
+import { readImportMeta, markDirty } from './cardImportMeta.js'
+import { writeCardFiles } from './cardFiles.js'
+import { log } from './logger.js'
+import { resolveSkillPathOrProject } from './skillPaths.js'
+
+const SYNC_SCRIPT_REL = 'finmall-card-sync/scripts/api_batch_sync.mjs'
+
+/** 读取 JSON 请求体（1MB 上限防失控） */
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = ''
+    req.on('data', (chunk) => {
+      raw += chunk
+      if (raw.length > 1024 * 1024) {
+        reject(new Error('请求体过大'))
+        req.destroy()
+      }
+    })
+    req.on('end', () => {
+      try {
+        resolve(raw ? JSON.parse(raw) : {})
+      } catch {
+        reject(new Error('请求体不是合法 JSON'))
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+/**
+ * 调试面板「卡片历史记录」tab 的远端版本时间线（只读）：GET /__card-history/:cardCode
+ *
+ * 语义：经 .import-meta.json 侧车里的 cardId 调 IDC10013，取该卡历史版本列表（新→旧），
+ * 每条含时间 / 预览图（/minio 同源路径）/ 版本记录 id / 相对上一版本的变更标签。
+ * 触发时机由前端控制（切到 tab / 点刷新 / 加载更多），不自动轮询——与「卡片来源」tab
+ * 的懒加载策略一致，避免每次加载卡片都拉起后台 Chrome。
+ *
+ * 恢复端点：POST /__card-history/:cardCode/restore（body { versionId }）——把指定历史
+ * 版本的完整 schema 写入本地 src/cards/<code>/schema.json（原子写 + 派生 data.json），
+ * 并标记 dirty（本地偏离导入镜像；推送成功后自会清除）。watcher 推 SSE、编辑器重载后
+ * 即可继续编辑，经既有「推送」链路（IDC10010）保存为远端最新版本。
+ *
+ * 安全闸（与 /__card-version / /__save 同源）：仅「已同步导入卡」（有 .import-meta.json
+ * 侧车且含 cardId）可操作；本地自建卡 / 未同步卡返回 409 local_card_no_source。
+ * 恢复另有防串卡校验：历史 schema.pageId 必须等于侧车 cardId，否则 409 pageId_mismatch。
+ *
+ * @param {{ root: string }} opts
+ * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, next: Function) => void}
+ */
+export function createCardHistoryMiddleware({ root }) {
+  return function cardHistoryMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const mRestore = pathname.match(/^\/__card-history\/([^/]+)\/restore$/)
+    const mList = pathname.match(/^\/__card-history\/([^/]+)$/)
+    if (!mRestore && !mList) return next()
+    const method = (req.method || 'GET').toUpperCase()
+    if (mRestore ? method !== 'POST' : method !== 'GET') return next()
+
+    const id = decodeURIComponent((mRestore || mList)[1])
+    const dir = findCardDir(root, { code: id })
+    const meta = dir ? readImportMeta(dir) : null
+    if (!meta || !meta.cardId) {
+      res.statusCode = 409
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(
+        JSON.stringify({
+          ok: false,
+          error: 'local_card_no_source',
+          message: '该卡片为本地自建、无远端同步来源（缺少 .import-meta.json 侧车），无法查看远端历史。',
+        }),
+      )
+    }
+
+    if (mRestore) return handleRestore(req, res, { root, id, dir, meta })
+    return handleList(req, res, { root, id, meta })
+  }
+}
+
+/** GET 列表：分页参数（query）pageNo / pageSize，缺省 1 / 30，上限 100 防失控 */
+function handleList(req, res, { root, id, meta }) {
+  const qs = new URL(req.url || '/', 'http://localhost').searchParams
+  const pageNo = Math.max(1, parseInt(qs.get('pageNo') || '1', 10) || 1)
+  const pageSize = Math.min(100, Math.max(1, parseInt(qs.get('pageSize') || '30', 10) || 30))
+
+  ;(async () => {
+    try {
+      const skillPath = resolveSkillPathOrProject(root, SYNC_SCRIPT_REL)
+      const { fetchCardHistory } = await import(pathToFileURL(skillPath).href)
+      const r = await fetchCardHistory(meta.cardId, { pageNo, pageSize })
+      log.ok('查询远端卡片历史', { cardCode: id, cardId: String(meta.cardId), count: r.list.length })
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      res.end(
+        JSON.stringify({
+          ok: true,
+          cardId: String(meta.cardId),
+          cardCode: id,
+          list: r.list,
+          totalNums: r.totalNums,
+          totalPages: r.totalPages,
+        }),
+      )
+    } catch (e) {
+      // 区分「凭据缺失」与「真正的查询错误」：前者让前端提示登录，而非裸抛 ENOENT。
+      const isNoCred =
+        e && /credentials\.json|credentials 不存在|NO_CREDENTIALS/.test(String(e && e.message))
+      res.statusCode = isNoCred ? 200 : 500
+      res.setHeader('Content-Type', 'application/json')
+      res.end(
+        JSON.stringify(
+          isNoCred
+            ? { error: 'need_credentials', needCredentials: true, message: String(e && e.message) }
+            : { error: 'history failed', message: String(e && e.message) },
+        ),
+      )
+    }
+  })()
+}
+
+/** POST restore：按 versionId 取历史 schema → 防串卡校验 → 原子写 schema.json + 派生 data.json → 标记 dirty */
+function handleRestore(req, res, { root, id, dir, meta }) {
+  ;(async () => {
+    try {
+      const body = await readJsonBody(req)
+      const versionId = String((body && body.versionId) || '')
+      if (!versionId) {
+        res.statusCode = 400
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(JSON.stringify({ ok: false, error: 'missing_version_id', message: '缺少 versionId（远端版本记录 id）。' }))
+      }
+      const skillPath = resolveSkillPathOrProject(root, SYNC_SCRIPT_REL)
+      const { fetchCardVersionSchema } = await import(pathToFileURL(skillPath).href)
+      let schema
+      let record
+      try {
+        ;({ schema, record } = await fetchCardVersionSchema(meta.cardId, versionId))
+      } catch (e) {
+        // 缓存未命中（时间线未加载过 / TTL 过期 / 目标在更旧页）：先拉一页 100 条预热
+        // (cardId, versionId) 缓存再重试——一页 4.2s，通常快于翻页到命中位置，且覆盖最新
+        // 100 个版本（用户点击的多为时间线可见项）。
+        if (!/找不到版本记录/.test(String(e && e.message))) throw e
+        const { fetchCardHistory } = await import(pathToFileURL(skillPath).href)
+        await fetchCardHistory(meta.cardId, { pageNo: 1, pageSize: 100 })
+        ;({ schema, record } = await fetchCardVersionSchema(meta.cardId, versionId))
+      }
+      // 防串卡：历史 schema 的 pageId 必须等于侧车登记的 cardId（与 /__save 的 pageId 闸门同语义）
+      if (String(schema.pageId) !== String(meta.cardId)) {
+        res.statusCode = 409
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(
+          JSON.stringify({
+            ok: false,
+            error: 'pageId_mismatch',
+            message: `版本记录 #${versionId} 的 schema.pageId（${schema.pageId}）与本地卡片来源（${meta.cardId}）不一致，已拒绝加载。`,
+          }),
+        )
+      }
+      // 原子写 schema.json + 单向派生 data.json（与编辑器本地保存同一写入口）
+      const written = writeCardFiles(dir, { schema })
+      // 本地内容已偏离导入镜像：标记 dirty，来源 tab 可见；推送成功后由 recordExport/markDirty 清除
+      markDirty(dir, true)
+      log.ok('恢复远端历史版本到本地', {
+        cardCode: id,
+        cardId: String(meta.cardId),
+        versionId,
+        createTime: record.createTime,
+        written,
+      })
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      res.end(
+        JSON.stringify({
+          ok: true,
+          cardCode: id,
+          cardId: String(meta.cardId),
+          versionId,
+          createTime: record.createTime,
+          written,
+        }),
+      )
+    } catch (e) {
+      const msg = String(e && e.message)
+      const isNoCred = /credentials\.json|credentials 不存在|NO_CREDENTIALS/.test(msg)
+      const isNotFound = /找不到版本记录|schema 为空或损坏/.test(msg)
+      const status = isNoCred ? 200 : isNotFound ? 404 : 500
+      res.statusCode = status
+      res.setHeader('Content-Type', 'application/json')
+      res.end(
+        JSON.stringify(
+          isNoCred
+            ? { ok: false, error: 'need_credentials', needCredentials: true, message: msg }
+            : isNotFound
+              ? { ok: false, error: 'version_not_found', message: msg }
+              : { ok: false, error: 'restore failed', message: msg },
+        ),
+      )
+    }
+  })()
+}

package/dist/vendored/server/core/cardImportMeta.js

@@ -26,8 +26,9 @@ export const META_SCHEMA_VERSION = 1
  * @param {string} o.cardCode   英文卡 id（目录名）
  * @param {string} [o.cardName] 卡片标题
  * @param {object} [o.files]    { schema, data, cover } 字节数
+ * @param {object} [o.remote]   远端列表元数据快照（picUrl / cardClassId / applyScene）
  */
-export function buildImportMeta({ baseUrl, appId, workspaceId, cardId, cardCode, cardName, files }) {
+export function buildImportMeta({ baseUrl, appId, workspaceId, cardId, cardCode, cardName, files, remote }) {
   return {
     schemaVersion: META_SCHEMA_VERSION,
     source: 'IDC10012',
@@ -39,6 +40,10 @@ export function buildImportMeta({ baseUrl, appId, workspaceId, cardId, cardCode,
     cardCode: cardCode || '',
     cardName: cardName || '',
     files: files || null,
+    // 远端卡片列表（IDC10001）才有、本地 DSL 产品数据不持久化的元数据：picUrl / cardClassId / applyScene。
+    // 导出包必须带上**真值**：导入侧（ImportCardAction.java:61-64）无条件按 cardPO.picUrl 末段
+    // 推文件名去读卡目录根的封面，picUrl 为空会退化成目录路径、直接抛异常。真值只在同步时可获得。
+    remote: remote || null,
     syncedAt: new Date().toISOString(),
     tool: 'finmall-card-sync',
     dirty: false, // 本地编辑后偏离导入镜像为 true（重置为导入镜像后回 false）

package/dist/vendored/server/core/cardPublishVersions.js

@@ -0,0 +1,91 @@
+import { pathToFileURL } from 'node:url'
+import { findCardDir } from './cardSidecar.js'
+import { readImportMeta } from './cardImportMeta.js'
+import { log } from './logger.js'
+import { resolveSkillPathOrProject } from './skillPaths.js'
+
+const SYNC_SCRIPT_REL = 'finmall-card-sync/scripts/api_batch_sync.mjs'
+
+/**
+ * 调试面板「导入信息」tab「发布版本记录」弹框的远端数据源（只读）：
+ * GET /__card-publish-versions/:cardCode?pageNo=&pageSize=
+ *
+ * 语义：经 .import-meta.json 侧车里的 cardId 调 IDC10004，取该卡发布版本记录分页（新→旧），
+ * 每条含版本号 / 平台（iOS·Android·HarmonyOS 子集）/ 发布状态 / 发布时间。
+ * 触发时机由前端控制（打开弹框 / 滚动到底懒加载下一页），不自动轮询——与「编辑记录」tab
+ * 的懒加载策略一致，避免每次加载卡片都拉起后台 Chrome。
+ *
+ * 安全闸（与 /__card-history / /__card-version 同源）：仅「已同步导入卡」（有
+ * .import-meta.json 侧车且含 cardId）可查；本地自建卡 / 未同步卡返回 409 local_card_no_source。
+ *
+ * @param {{ root: string }} opts
+ * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, next: Function) => void}
+ */
+export function createCardPublishVersionsMiddleware({ root }) {
+  return function cardPublishVersionsMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const m = pathname.match(/^\/__card-publish-versions\/([^/]+)$/)
+    if (!m) return next()
+    if ((req.method || 'GET').toUpperCase() !== 'GET') return next()
+
+    const id = decodeURIComponent(m[1])
+    const dir = findCardDir(root, { code: id })
+    const meta = dir ? readImportMeta(dir) : null
+    if (!meta || !meta.cardId) {
+      res.statusCode = 409
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(
+        JSON.stringify({
+          ok: false,
+          error: 'local_card_no_source',
+          message: '该卡片为本地自建、无远端同步来源（缺少 .import-meta.json 侧车），无法查看发布版本记录。',
+        }),
+      )
+    }
+
+    const qs = new URL(req.url || '/', 'http://localhost').searchParams
+    const pageNo = Math.max(1, parseInt(qs.get('pageNo') || '1', 10) || 1)
+    const pageSize = Math.min(100, Math.max(1, parseInt(qs.get('pageSize') || '10', 10) || 10))
+
+    ;(async () => {
+      try {
+        const skillPath = resolveSkillPathOrProject(root, SYNC_SCRIPT_REL)
+        const { fetchCardPublishVersions } = await import(pathToFileURL(skillPath).href)
+        const r = await fetchCardPublishVersions(meta.cardId, { pageNo, pageSize })
+        log.ok('查询远端发布版本记录', {
+          cardCode: id,
+          cardId: String(meta.cardId),
+          pageNo,
+          count: r.list.length,
+        })
+        res.statusCode = 200
+        res.setHeader('Content-Type', 'application/json')
+        res.setHeader('Cache-Control', 'no-store')
+        res.end(
+          JSON.stringify({
+            ok: true,
+            cardId: String(meta.cardId),
+            cardCode: id,
+            list: r.list,
+            maxVersion: r.maxVersion,
+            totalNums: r.totalNums,
+            totalPages: r.totalPages,
+          }),
+        )
+      } catch (e) {
+        // 区分「凭据缺失」与「真正的查询错误」：前者让前端提示登录，而非裸抛 ENOENT。
+        const isNoCred =
+          e && /credentials\.json|credentials 不存在|NO_CREDENTIALS/.test(String(e && e.message))
+        res.statusCode = isNoCred ? 200 : 500
+        res.setHeader('Content-Type', 'application/json')
+        res.end(
+          JSON.stringify(
+            isNoCred
+              ? { error: 'need_credentials', needCredentials: true, message: String(e && e.message) }
+              : { error: 'publish versions failed', message: String(e && e.message) },
+          ),
+        )
+      }
+    })()
+  }
+}

package/dist/vendored/server/core/cardSave.js

@@ -9,17 +9,115 @@ import { checkPushAllowed } from './cardListCache.js'
 import { assertRemoteSource, findCardDir } from './cardSidecar.js'
 import { log } from './logger.js'
 import { resolveSkillPathOrProject } from './skillPaths.js'
+import { generateCardCover } from './screenshot.js'
+import { serialize } from './browser.js'
 
 /** 远端保存脚本相对 skills/ 的路径（与「同步」共用 finmall-card-sync） */
 const SYNC_SCRIPT_REL = 'finmall-card-sync/scripts/api_batch_sync.mjs'
 
+/**
+ * 推送成功后「截图 + 上传为远端预览图」的整段预算。
+ *
+ * 为什么要预算：这一步串了无头渲染（首次拉起 Chrome 可达数秒）与一次跨网 HTTPS 上传，
+ * 两步各有 30s 级超时。不设总闸的话，最坏情况会把 /__save 的响应拖到 1 分钟以上——
+ * 用户看到的是「点了推送一直在转圈」，而卡片内容其实早就写成功了。到点即放弃并
+ * 在响应里带 preview.error 说明，不影响推送本身的成功结论。
+ */
+const PUSH_PREVIEW_TIMEOUT_MS = Number(process.env.CARDBUDDY_PUSH_PREVIEW_TIMEOUT_MS || 45000)
+
+/**
+ * 推送成功后自动更新远端预览图的总开关（默认开）。
+ * 需要临时关闭时设 `CARDBUDDY_PUSH_PREVIEW=0`（例如远端图片库维护中，避免每条推送都多等一次失败）。
+ */
+const PUSH_PREVIEW_ENABLED = process.env.CARDBUDDY_PUSH_PREVIEW !== '0'
+
+/** 带总时限的 Promise 竞速（超时不取消底层任务，只放弃等待） */
+function withDeadline(promise, ms, label) {
+  let timer
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label}超时（>${ms}ms），已放弃`)), ms)
+    }),
+  ]).finally(() => clearTimeout(timer))
+}
+
+/**
+ * 推送成功后把「当前卡片」截图上传为远端预览图（IDC10014.do）。
+ *
+ * 为什么放在服务端而不是前端：①截图走本地无头渲染（screenshot.js 单例 Chrome），
+ * 与「预览图」按钮同一条链路，产出透明底、与卡片实际渲染尺寸 1:1 的 PNG；
+ * ②上传必须带 FinMall token，只有已登录的后台会话拿得到，前端不接触凭据。
+ *
+ * 三条纪律：
+ *   - **best-effort**：任何失败都返回结构化结果，绝不向上抛——预览图是推送的附加产物，
+ *     不能让它把「卡片已保存到远端」这个既成事实变成一次报错；
+ *   - **不写本地预览图**：只上传，不覆盖 src/cards/<id>/<id>.png。写盘会触发 watcher 的
+ *     cards-changed，而截图 + 上传耗时可能超出前端 2.5s 的自保存抑制窗口，会误弹
+ *     「卡片已在编辑器外被修改」——本地封面仍由「预览图」按钮显式生成（单一触发点）；
+ *   - **渲染基于磁盘态**：调用方（前端「推送」）需先确保未保存编辑已落盘，否则截到的是
+ *     上一版布局（见 App.vue saveToRemote 的前置 saveCard）。
+ *
+ * @param {object} opts
+ * @param {string} opts.cardCode        卡片目录名（= 英文卡 id，截图入口用它定位卡片）
+ * @param {string|number} opts.cardId   数字型远端 cardId（= schema.pageId，IDC10014.do 主键）
+ * @param {number} [opts.width]         卡片设计宽度（缺省 375，取自 schema.view.width）
+ * @param {unknown[]} [opts.components] 卡片组件数组（用于识别空白卡：空数组时不截图）
+ * @param {(p: {cardId: string, pngBase64: string}) => Promise<object>} opts.upload
+ *                                      上传实现（注入 skill 的 uploadCardPreview）
+ * @param {(id: string, o?: object) => Promise<object>} [opts.shoot]
+ *                                      截图实现（默认 generateCardCover；单测可注入）
+ * @returns {Promise<{ ok: boolean, width?: number|null, height?: number|null, bytes?: number, url?: string, error?: string, message?: string }>}
+ */
+export async function uploadPreviewAfterPush({
+  cardCode,
+  cardId,
+  width,
+  components,
+  upload,
+  shoot = generateCardCover,
+} = {}) {
+  if (!cardCode) return { ok: false, error: 'no_card_code', message: '未定位到卡片目录，跳过预览图上传' }
+  if (!cardId) return { ok: false, error: 'no_card_id', message: '缺少数字型 cardId，跳过预览图上传' }
+  if (typeof upload !== 'function') {
+    return { ok: false, error: 'upload_unavailable', message: '当前 skill 未提供 uploadCardPreview，跳过预览图上传' }
+  }
+  // 空白卡（组件数组为空）：无头渲染只会得到一张纯透明图，传上去等于把列表缩略图刷没。
+  // 与 /__card-image 的 422 判定同源（那里同样按「数组存在且为空」认定空白卡）。
+  if (Array.isArray(components) && !components.length) {
+    return { ok: false, error: 'empty-card', message: '空白卡（无组件）没有可预览内容，跳过预览图上传' }
+  }
+
+  // 与 /__card-image、/__screenshot 共用同一浏览器单例 + 串行队列，避免同时渲多张打爆内存
+  const shot = await serialize(() => shoot(cardCode, { width: Number(width) > 0 ? Number(width) : 375 }))
+  if (!shot || shot.tooBusy) {
+    return { ok: false, error: 'too-busy', message: '截图队列已满，跳过预览图上传' }
+  }
+  if (!shot.buffer) {
+    return { ok: false, error: shot.error || 'screenshot-failed', message: shot.message || '截图失败' }
+  }
+
+  const uploaded = await upload({ cardId: String(cardId), pngBase64: shot.buffer.toString('base64') })
+  return {
+    ok: true,
+    width: shot.width,
+    height: shot.height,
+    bytes: shot.buffer.length,
+    url: (uploaded && uploaded.url) || '',
+  }
+}
+
 /**
  * 远端保存（写回 FinMall）服务端处理。
  * 前端「保存」按钮把当前预览的 schema（含实时数据绑定）POST 过来，
  * 本中间件校验 pageId 后，经已登录浏览器中转调用 IDC10010.do 写回远端，
  * 与「同步」共用 finmall-card-sync 的 saveCardToRemote（带会话自愈）。
+ *
+ * @param {{ root: string, previewAfterPush?: typeof uploadPreviewAfterPush }} opts
+ *   - previewAfterPush：推送成功后的「截图 + 上传预览图」实现，默认即上面的
+ *     uploadPreviewAfterPush；单测注入替身以便在无 Chrome / 无 FinMall 会话的环境断言接线。
  */
-export function createSaveMiddleware({ root }) {
+export function createSaveMiddleware({ root, previewAfterPush = uploadPreviewAfterPush }) {
   return async function saveMiddleware(req, res, next) {
     const pathname = decodeURIComponent((req.url || '').split('?')[0])
     const method = (req.method || 'GET').toUpperCase()
@@ -102,17 +200,18 @@ export function createSaveMiddleware({ root }) {
           pathToFileURL(resolveSkillPathOrProject(root || process.cwd(), SYNC_SCRIPT_REL)).href
         )
         const { response, verified } = await mod.saveCardToRemote(schema, { skeletonScreen })
+        // 卡片目录反查只做一次：既供导出元数据落盘，也供随后的预览图截图定位（目录名 = 英文卡 id）。
+        const cardDir = root ? findCardDir(root, { code, pageId: schema.pageId }) : null
         // 导出可追溯（Phase E）：把远端保存的读回校验结果写进导入元数据侧车。
         // 注意：目录按 cardCode 命名，必须按 pageId 反查到正确的 src/cards/<cardCode>/。
         if (root) {
           try {
-            const dir = findCardDir(root, { pageId: schema.pageId })
-            if (dir) {
-              await recordExport(dir, verified)
+            if (cardDir) {
+              await recordExport(cardDir, verified)
               // 推送成功即与远端对齐：清除「偏离导入镜像」标记（来源 tab 据此提示）。
               // 注：本地磁盘（含编辑）仍可能 ≠ 当初导入镜像，此处语义转为「已与远端同步」，
               // 符合用户预期——推送到远端后不应再被标为「偏离」。
-              await markDirty(dir, false)
+              await markDirty(cardDir, false)
             } else console.warn(`[__save] 未找到 pageId=${schema.pageId} 对应的本地卡片目录，跳过导出元数据`)
           } catch (e) {
             log.warn('写导出元数据失败（不影响保存结果）', { error: e && e.message })
@@ -126,9 +225,47 @@ export function createSaveMiddleware({ root }) {
         if (!verified.fingerprintMatched && verified.diff && verified.diff.length) {
           log.warn('指纹不匹配（落库内容与本地不一致）', { diff: verified.diff.slice(0, 3) })
         }
+
+        // 推送成功后自动更新远端预览图：本地无头渲染当前卡片 → IDC10014.do 上传。
+        // 全程 best-effort：失败只记日志 + 在响应里带 preview.error，推送本身的成功结论不受影响。
+        let preview = null
+        if (PUSH_PREVIEW_ENABLED) {
+          try {
+            preview = await withDeadline(
+              previewAfterPush({
+                cardCode: cardDir ? path.basename(cardDir) : '',
+                cardId: String(schema.pageId),
+                width: Number((schema.view && schema.view.width) || 0),
+                components: schema.view && schema.view.components,
+                upload: typeof mod.uploadCardPreview === 'function' ? mod.uploadCardPreview : null,
+              }),
+              PUSH_PREVIEW_TIMEOUT_MS,
+              '推送后预览图上传',
+            )
+          } catch (e) {
+            preview = { ok: false, error: 'preview_failed', message: String(e && e.message) }
+          }
+          if (preview && preview.ok) {
+            log.ok('推送后预览图已更新', {
+              cardId: String(schema.pageId),
+              width: preview.width,
+              height: preview.height,
+              bytes: preview.bytes,
+            })
+          } else {
+            log.warn('推送成功但预览图未更新（不影响卡片内容）', {
+              cardId: String(schema.pageId),
+              error: (preview && preview.error) || 'unknown',
+              message: (preview && preview.message) || '',
+            })
+          }
+        }
+
         res.statusCode = 200
         res.setHeader('Content-Type', 'application/json')
-        return res.end(JSON.stringify({ ok: true, code, cardId: String(schema.pageId), response, verified }))
+        return res.end(
+          JSON.stringify({ ok: true, code, cardId: String(schema.pageId), response, verified, preview }),
+        )
       } catch (e) {
         log.error('远端保存失败', e)
         res.statusCode = 502