cardbuddy 0.6.0

package/dist/server-core/cardFiles.js

@@ -0,0 +1,188 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { markDirty, recordEdit, readImportMeta } from './cardImportMeta.js'
+import { log } from './logger.js'
+import { buildDataFromSchema } from './buildDataFromSchema.js'
+
+/**
+ * 单张卡片 / 卡片列表的按需读取 / 写回服务端处理（dev 下实时读磁盘，无缓存）。
+ * - GET  /__cards ：实时扫描 src/cards/* 目录，返回卡片列表 [{id,name,pageId}]。
+ * - GET  /__card/<id> ：实时读 src/cards/<id>/schema.json，data 由 schema 派生返回。
+ * - POST /__card/<id> ：把预览内编辑后的最新 schema 写回 src/cards/<id>/，data 单向重算。
+ *
+ * 以下纯函数被 mcp/ 客户端复用（降级模式直接读盘/写盘），保持单一实现、避免逻辑漂移。
+ */
+
+/** 扫描 src/cards/* 返回 [{id,name,pageId,mtime}]（导出供 MCP 复用）；
+ *  mtime 为 schema.json / data.json 中较新的修改时间（毫秒），供前端按修改时间排序 */
+export function listCards(root) {
+  const cardsDir = path.join(root, 'src', 'cards')
+  const list = []
+  if (fs.existsSync(cardsDir)) {
+    for (const id of fs.readdirSync(cardsDir)) {
+      const dir = path.join(cardsDir, id)
+      if (!fs.statSync(dir).isDirectory()) continue
+      let name = id
+      let pageId = null
+      let mtime = 0
+      try {
+        const schema = JSON.parse(fs.readFileSync(path.join(dir, 'schema.json'), 'utf8'))
+        if (schema && schema.name) name = schema.name
+        if (schema && schema.pageId != null) pageId = schema.pageId
+      } catch {
+        /* 读取失败则退用目录名 / pageId=null，不阻断列表 */
+      }
+      // 卡片修改时间：取 schema.json 的单文件 mtime（毫秒）。data.json 是 schema 的
+      // 单向派生产物，不应参与排序，否则它每次被重算都会让卡片「看起来更新」。
+      try {
+        mtime = fs.statSync(path.join(dir, 'schema.json')).mtimeMs
+      } catch {
+        /* 取不到修改时间则记为 0，不参与新→旧排序时排在最前 */
+      }
+      // 优先采用侧车 .import-meta.json 记录的本地编辑时间（editedAt 更准确反映「编辑」而非文件拷贝），
+      // 无侧车 / 无 editedAt 时退用上面的文件 mtime。
+      try {
+        const meta = readImportMeta(dir)
+        if (meta && meta.editedAt) {
+          const t = Date.parse(meta.editedAt)
+          if (!Number.isNaN(t)) mtime = t
+        }
+      } catch {
+        /* 解析失败则保持文件 mtime */
+      }
+      list.push({ id, name, pageId, mtime })
+    }
+  }
+  list.sort((a, b) => a.id.localeCompare(b.id))
+  return list
+}
+
+/** 读单卡 {schema,data}；不存在返回 null（导出供 MCP 复用） */
+export function readCardFiles(root, id) {
+  const dir = path.join(root, 'src', 'cards', id)
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return null
+  const read = (f) => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'))
+    } catch {
+      return null
+    }
+  }
+  const schema = read('schema.json')
+  // schema 读取失败（外部改坏 / 文件缺失）→ 卡片不可用，返回 null 让上层给 404，
+  // 而非带着 null schema 进 buildDataFromSchema 再抛 500。
+  if (!schema) return null
+  // data 由 schema 单向派生，绝不读回 data.json 文件 —— 即便 data.json 缺失/过期，
+  // GET /__card 仍返回正确的派生 data（向前兼容旧客户端 / mcp 降级读取）。
+  return { schema, data: buildDataFromSchema(schema) }
+}
+
+/**
+ * 把预览内编辑后的最新 schema 原子写回 src/cards/<id>/（导出供 MCP 复用）。
+ *
+ * 关键点（「schema 唯一真值」）：
+ * - 只接受 schema 写盘；写 schema.json 后**始终用 buildDataFromSchema(schema) 重算
+ *   data.json**，payload 里的 data 字段被忽略 —— data.json 永不成为写入来源。
+ * - 对象/数组走 JSON（剥除 _schemaNode 等运行时自引用），其余原样字符串化；
+ * - 先写临时文件再 rename，避免写到一半进程退出损坏原文件。
+ */
+function writeJsonFile(dir, filename, value) {
+  const text =
+    value !== null && typeof value === 'object'
+      ? JSON.stringify(value, (k, v) => (k === '_schemaNode' ? undefined : v), 2)
+      : String(value)
+  const target = path.join(dir, filename)
+  const tmp = target + '.tmp'
+  fs.writeFileSync(tmp, text, 'utf8')
+  fs.renameSync(tmp, target)
+}
+
+export function writeCardFiles(dir, payload) {
+  const written = []
+  if ('schema' in payload && payload.schema !== undefined) {
+    writeJsonFile(dir, 'schema.json', payload.schema)
+    written.push('schema.json')
+    // data.json 是 schema 的单向派生产物：写 schema 后强制重算，忽略 payload.data。
+    writeJsonFile(dir, 'data.json', buildDataFromSchema(payload.schema))
+    written.push('data.json')
+  } else if ('data' in payload && payload.data !== undefined) {
+    // 防御性分支：理论上不会再发生（预览只发 schema）；保留以兼容极旧调用方直接写 data。
+    writeJsonFile(dir, 'data.json', payload.data)
+    written.push('data.json')
+  }
+  return written
+}
+
+/**
+ * @param {{ root: string }} opts
+ * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, next: Function) => void}
+ */
+export function createCardFilesMiddleware({ root }) {
+  return function cardFilesMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const method = (req.method || 'GET').toUpperCase()
+
+    // 实时卡片列表：扫描 src/cards/* 目录，逐张读取 schema.name / pageId。
+    // dev 下不再依赖任何启动快照，磁盘改了列表立即变（新增 / 改名 / 删除的卡都即时反映）。
+    if (pathname === '/__cards' && method === 'GET') {
+      const cards = listCards(root)
+      log.info('读取卡片列表', '数量: ' + cards.length)
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      return res.end(JSON.stringify({ cards }))
+    }
+
+    const m = pathname.match(/^\/__card\/([^/]+)$/)
+    if (!m) return next()
+    const id = decodeURIComponent(m[1])
+    const dir = path.join(root, 'src', 'cards', id)
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+      log.warn('卡片未找到', { id })
+      res.statusCode = 404
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(JSON.stringify({ error: 'card not found', id }))
+    }
+    if (method === 'GET') {
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      return res.end(JSON.stringify(readCardFiles(root, id)))
+    }
+    if (method === 'POST') {
+      let body = ''
+      req.on('data', (c) => {
+        body += c
+        if (body.length > 16 * 1024 * 1024) req.destroy()
+      })
+      req.on('end', () => {
+        let payload
+        try {
+          payload = JSON.parse(body)
+        } catch (e) {
+          res.statusCode = 400
+          res.setHeader('Content-Type', 'application/json')
+          return res.end(JSON.stringify({ error: 'invalid json', message: String(e.message) }))
+        }
+        try {
+          const written = writeCardFiles(dir, payload)
+          // 本地编辑后偏离导入镜像（Phase E「导入来源可追溯」）：标脏，UI「来源」tab 据此提示。
+          try { markDirty(dir, true) } catch { /* 无侧车时忽略 */ }
+          // 记录本次编辑时间到侧车，供「按修改时间排序」优先采用（无侧车时忽略，退用文件 mtime）。
+          try { recordEdit(dir) } catch { /* 无侧车时忽略 */ }
+          log.ok('写回卡片', id)
+          res.statusCode = 200
+          res.setHeader('Content-Type', 'application/json')
+          return res.end(JSON.stringify({ ok: true, written }))
+        } catch (e) {
+          log.error('写回卡片失败', e)
+          res.statusCode = 500
+          res.setHeader('Content-Type', 'application/json')
+          return res.end(JSON.stringify({ error: 'write failed', message: String(e.message) }))
+        }
+      })
+      return
+    }
+    return next()
+  }
+}

package/dist/server-core/cardHistory.js

@@ -0,0 +1,156 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { buildDataFromSchema } from './buildDataFromSchema.js'
+
+/**
+ * 编辑历史（撤销/重做）快照的落盘与读取。
+ *
+ * 每当预览内对 schema 做了一次结构性修改，前端会把「修改前的上一版本 schema」
+ * POST 到这里，服务端以 `src/cards/<id>/.history/schema-<ts>.json` 存盘（与卡片同目录、
+ * 独立的缓存文件夹，不进版本库）。最多保留 MAX_SNAPSHOTS 个，超出裁剪最旧。
+ *
+ * GET 返回按时间升序（旧→新）的 snapshots，供前端在页面重载后重建撤销栈，使
+ * 撤销能力跨刷新可用。
+ */
+
+const HISTORY_DIR = '.history'
+const MAX_SNAPSHOTS = 30
+
+/** 列出 .history 下全部快照元数据（按 ts 升序） */
+export function listSnapshots(histDir) {
+  if (!fs.existsSync(histDir) || !fs.statSync(histDir).isDirectory()) return []
+  return fs
+    .readdirSync(histDir)
+    .filter((f) => /^schema-(\d+)\.json$/.test(f))
+    .map((f) => {
+      const m = f.match(/^schema-(\d+)\.json$/)
+      return { ts: m ? Number(m[1]) : 0, file: f }
+    })
+    .sort((a, b) => a.ts - b.ts)
+}
+
+/** 超出上限时删除最旧文件（就地裁剪传入的数组） */
+function trimSnapshots(histDir, snapshots) {
+  while (snapshots.length > MAX_SNAPSHOTS) {
+    const oldest = snapshots.shift()
+    try {
+      fs.unlinkSync(path.join(histDir, oldest.file))
+    } catch {
+      /* 删除失败不阻断 */
+    }
+  }
+}
+
+/**
+ * 把一份 schema 落盘为新快照（原子写 + 唯一递增 ts + 超上限裁剪）。
+ * 供中间件 POST 与 MCP card_rollback 离线路径共用同一份实现，避免漂移。
+ * @param {string} cardDir src/cards/<id> 目录
+ * @param {object} schema 待快照的 schema
+ * @returns {{ ts: number, count: number }}
+ */
+export function saveSnapshot(cardDir, schema) {
+  const histDir = path.join(cardDir, HISTORY_DIR)
+  if (!fs.existsSync(histDir)) fs.mkdirSync(histDir, { recursive: true })
+  // 生成唯一且单调递增的 ts 文件名：同一毫秒内冲突则自增，保证排序稳定。
+  let ts = Date.now()
+  let file = `schema-${ts}.json`
+  while (fs.existsSync(path.join(histDir, file))) {
+    ts += 1
+    file = `schema-${ts}.json`
+  }
+  const content = JSON.stringify(
+    { ts, schema },
+    (k, v) => (k === '_schemaNode' ? undefined : v),
+    2,
+  )
+  const tmp = path.join(histDir, file + '.tmp')
+  fs.writeFileSync(tmp, content, 'utf8')
+  fs.renameSync(tmp, path.join(histDir, file))
+  const snaps = listSnapshots(histDir)
+  trimSnapshots(histDir, snaps)
+  return { ts, count: Math.min(snaps.length, MAX_SNAPSHOTS) }
+}
+
+export { HISTORY_DIR }
+
+/**
+ * @param {{ root: string }} opts
+ * @returns {(req, res, next) => void}
+ */
+export function createHistoryMiddleware({ root }) {
+  return function historyMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const method = (req.method || 'GET').toUpperCase()
+    const m = pathname.match(/^\/__history\/([^/]+)$/)
+    if (!m) return next()
+    const id = decodeURIComponent(m[1])
+    const dir = path.join(root, 'src', 'cards', id)
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+      res.statusCode = 404
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(JSON.stringify({ error: 'card not found', id }))
+    }
+    const histDir = path.join(dir, HISTORY_DIR)
+
+    // GET：读取全部历史快照（旧→新），返回 schema 内容
+    if (method === 'GET') {
+      const snaps = listSnapshots(histDir)
+      const out = []
+      for (const s of snaps) {
+        try {
+          const data = JSON.parse(fs.readFileSync(path.join(histDir, s.file), 'utf8'))
+          const schema = data.schema != null ? data.schema : data
+          // 旧快照可能带 data 字段（历史兼容）；新快照只存 schema，data 由 schema
+          // 单向派生，保证撤销/重做还原时数据绑定与 schema.defaultValue 完全一致。
+          const derived = data.data != null ? data.data : buildDataFromSchema(schema)
+          out.push({ ts: s.ts, schema, data: derived })
+        } catch {
+          /* 单文件损坏不阻断整体读取 */
+        }
+      }
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      return res.end(JSON.stringify({ snapshots: out }))
+    }
+
+    // POST：把「上一版本 schema」落盘为一张新快照
+    if (method === 'POST') {
+      let body = ''
+      req.on('data', (c) => {
+        body += c
+        if (body.length > 32 * 1024 * 1024) req.destroy()
+      })
+      req.on('end', () => {
+        let payload
+        try {
+          payload = JSON.parse(body)
+        } catch (e) {
+          res.statusCode = 400
+          res.setHeader('Content-Type', 'application/json')
+          return res.end(JSON.stringify({ error: 'invalid json', message: String(e.message) }))
+        }
+        const schema = payload && payload.schema
+        if (!schema || typeof schema !== 'object') {
+          res.statusCode = 400
+          res.setHeader('Content-Type', 'application/json')
+          return res.end(JSON.stringify({ error: 'missing schema in body' }))
+        }
+        try {
+          const { ts, count } = saveSnapshot(dir, schema)
+          res.statusCode = 200
+          res.setHeader('Content-Type', 'application/json')
+          return res.end(JSON.stringify({ ok: true, ts, count }))
+        } catch (e) {
+          console.error('[__history] 写快照失败', e)
+          res.statusCode = 500
+          res.setHeader('Content-Type', 'application/json')
+          return res.end(JSON.stringify({ error: 'write failed', message: String(e.message) }))
+        }
+      })
+      return
+    }
+
+    return next()
+  }
+}

package/dist/server-core/cardImage.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { takeScreenshot } from './screenshot.js'
+
+/**
+ * 卡片预览图本地静态服务：把卡片目录下的「同名预览图」映射为
+ * GET /__card-image/<id>[?width=375] ，流式返回 src/cards/<id>/<id>.<ext>。
+ *
+ * 用途：编辑器「卡片网格预览」弹窗用此端点取每格缩略图，复用既有的本地静态服务
+ * （与 /slices、/__card 同源，挂在 cardbuddy 上），不依赖 Vite 同源
+ * （编辑器经 apiBase 连 8787，<img> 跨域加载由 CORS 中间件放行）。
+ *
+ * 文件名取「与卡片 id 同名」的位图（png/jpg/jpeg/webp/gif，大小写不敏感）；
+ * 若卡片目录没有同名预览图，则回退到实时无头截图（takeScreenshot，复用 /__screenshot
+ * 同一套渲染内核），保证任何卡片都能出预览。截图失败（如缺 Chrome）则 404，
+ * 由调用方回退占位。仅服务 src/cards 下的卡片预览图，禁止目录穿越。
+ */
+
+const MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+}
+
+// 卡片 id 仅含字母/数字/下划线/连字符（与 src/cards 目录名一致），先收紧再拼路径。
+const ID_RE = /^[A-Za-z0-9_-]+$/
+
+/**
+ * @param {{ root: string }} opts  root = 仓库根（含 src/cards）
+ * @returns {(req, res, next) => void}
+ */
+export function createCardImageMiddleware({ root }) {
+  const cardsRoot = path.join(root, 'src', 'cards')
+  return async (req, res, next) => {
+    const url = (req.url || '').split('?')[0]
+    const m = url.match(/^\/__card-image\/([^/?]+)$/)
+    if (!m) return next()
+    const id = decodeURIComponent(m[1])
+    // 非法 id（含路径分隔/穿越字符）→ 不服务，交下一个中间件
+    if (!ID_RE.test(id)) return next()
+
+    const dir = path.join(cardsRoot, id)
+    // 防目录穿越：解析后必须仍在 src/cards/<id> 内
+    if (!dir.startsWith(cardsRoot + path.sep) && dir !== cardsRoot) return next()
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return next()
+
+    // 取与 id 同名的位图（大小写不敏感，扩展名见 MIME）
+    let file = null
+    for (const entry of fs.readdirSync(dir)) {
+      const dot = entry.lastIndexOf('.')
+      if (dot < 0) continue
+      const base = entry.slice(0, dot)
+      const ext = entry.slice(dot).toLowerCase()
+      if (base.toLowerCase() === id.toLowerCase() && MIME[ext]) {
+        file = path.join(dir, entry)
+        break
+      }
+    }
+
+    // 命中同名预览图：直接静态返回
+    if (file) {
+      const ext = path.extname(file).toLowerCase()
+      res.setHeader('Content-Type', MIME[ext] || 'application/octet-stream')
+      res.setHeader('Cache-Control', 'public, max-age=0')
+      fs.createReadStream(file).pipe(res)
+      return
+    }
+
+    // 无同名预览图：回退实时无头截图（复用 /__screenshot 渲染内核）。
+    // width 由查询参数决定（默认 390），与 /__screenshot 一致。
+    const q = new URL(req.url, 'http://localhost')
+    const width = parseInt(q.searchParams.get('width') || '390', 10) || 390
+    const shot = await takeScreenshot(id, width, 'png')
+    if (!shot || !shot.buffer) {
+      // 截图失败（缺 Chrome / 卡片渲染异常）：交下一个中间件（最终 404），由前端回退占位
+      return next()
+    }
+    res.statusCode = 200
+    res.setHeader('Content-Type', 'image/png')
+    res.setHeader('Cache-Control', 'no-store')
+    res.end(shot.buffer)
+  }
+}

package/dist/server-core/cardImportMeta.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * 导入来源元数据（provenance）侧车。
+ *
+ * 设计纪律（与「绝不污染 DSL 产品数据」一致）：
+ * - 侧车文件名为 `.import-meta.json`（点前缀），放在 `src/cards/<id>/` 下，**绝不**写进
+ *   schema.json / data.json。卡片契约（`validate_schema.py`）只校验 schema.json，写回白名单
+ *   （cardFiles.writeCardFiles）只接受 schema/data，故本文件永远不会进入 DSL 产品数据，也
+ *   不会被 `card_write` / 远端保存带出去。
+ * - 它只承载「这张卡从哪来 / 何时导入 / 落盘在哪 / 是否偏离导入镜像」这类可追溯信息，
+ *   供 UI（DebugPanel「来源」tab）与 AI skill（card_import_meta）读取，落实 Phase E「导入来源可追溯」。
+ */
+
+export const IMPORT_META_FILE = '.import-meta.json'
+export const META_SCHEMA_VERSION = 1
+
+/**
+ * 构造一份导入元数据（纯函数，便于单测，不触碰磁盘）。
+ * @param {object} o
+ * @param {string} o.baseUrl    远端基址（如 https://uat-pkg.finmall.com）
+ * @param {string} o.appId      应用标识
+ * @param {string} o.workspaceId 工作空间标识
+ * @param {string|number} o.cardId      数字型 cardId（IDC10012 主键）
+ * @param {string} o.cardCode   英文卡 id（目录名）
+ * @param {string} [o.cardName] 卡片标题
+ * @param {object} [o.files]    { schema, data, cover } 字节数
+ */
+export function buildImportMeta({ baseUrl, appId, workspaceId, cardId, cardCode, cardName, files }) {
+  return {
+    schemaVersion: META_SCHEMA_VERSION,
+    source: 'IDC10012',
+    interface: 'IDC10012.do',
+    baseUrl: baseUrl || '',
+    appId: appId || '',
+    workspaceId: workspaceId || '',
+    cardId: cardId == null ? null : String(cardId),
+    cardCode: cardCode || '',
+    cardName: cardName || '',
+    files: files || null,
+    syncedAt: new Date().toISOString(),
+    tool: 'finmall-card-sync',
+    dirty: false, // 本地编辑后偏离导入镜像为 true（重置为导入镜像后回 false）
+    lastExport: null, // 远端保存（/__save）后写入校验结果
+    editedAt: null, // 最近一次本地编辑时间（每次写盘都更新），供「按修改时间排序」
+  }
+}
+
+/** 原子写：先写 tmp 再 rename，避免写到一半进程退出损坏。 */
+export function writeImportMeta(dir, meta) {
+  const target = path.join(dir, IMPORT_META_FILE)
+  const tmp = target + '.tmp'
+  fs.writeFileSync(tmp, JSON.stringify(meta, null, 2), 'utf8')
+  fs.renameSync(tmp, target)
+  return target
+}
+
+/** 读取并解析；文件不存在 / 解析失败返回 null（调用方据此区分「本地新建卡」与「已同步卡」）。 */
+export function readImportMeta(dir) {
+  const file = path.join(dir, IMPORT_META_FILE)
+  if (!fs.existsSync(file)) return null
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** 标记/清除 dirty（本地编辑偏离导入镜像）。无侧车时静默跳过。 */
+export function markDirty(dir, dirty = true) {
+  const meta = readImportMeta(dir)
+  if (!meta) return null
+  const next = { ...meta, dirty: !!dirty }
+  writeImportMeta(dir, next)
+  return next
+}
+
+/**
+ * 记录一次本地编辑时间（每次写盘都更新 editedAt），用于「按修改时间排序」。
+ * 与 markDirty 正交：dirty 记录是否偏离导入镜像，editedAt 记录最近编辑时刻。
+ * 无侧车（本地新建卡）时静默跳过，由文件 mtime 兜底。
+ */
+export function recordEdit(dir) {
+  const meta = readImportMeta(dir)
+  if (!meta) return null
+  const next = { ...meta, editedAt: new Date().toISOString() }
+  writeImportMeta(dir, next)
+  return next
+}
+
+/**
+ * 记录一次远端保存（/__save）的读回校验结果。
+ * @param {string} dir
+ * @param {object} verified  saveCardToRemote 返回的 { ok, cardIdMatched, fingerprintMatched, diff, readBackError }
+ */
+export function recordExport(dir, verified) {
+  const meta = readImportMeta(dir)
+  if (!meta) return null
+  const next = {
+    ...meta,
+    lastExport: {
+      at: new Date().toISOString(),
+      ok: !!(verified && verified.ok),
+      cardIdMatched: !!(verified && verified.cardIdMatched),
+      fingerprintMatched: !!(verified && verified.fingerprintMatched),
+      readBackError: (verified && verified.readBackError) || null,
+    },
+  }
+  writeImportMeta(dir, next)
+  return next
+}
+
+/**
+ * dev server 中间件：GET /__import-meta/:id 暴露导入来源元数据（供 UI「来源」tab / AI skill 读取）。
+ * 纯只读、no-store；卡片无侧车时 404（区分「本地新建卡」与「已同步卡」）。
+ *
+ * @param {{ root: string }} opts
+ * @returns {(req, res, next) => void}
+ */
+export function createImportMetaMiddleware({ root }) {
+  return function importMetaMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const m = pathname.match(/^\/__import-meta\/([^/]+)$/)
+    if (!m) return next()
+    if ((req.method || 'GET').toUpperCase() !== 'GET') return next()
+    const id = decodeURIComponent(m[1])
+    const dir = path.join(root, 'src', 'cards', id)
+    const meta = readImportMeta(dir)
+    res.setHeader('Cache-Control', 'no-store')
+    res.setHeader('Content-Type', 'application/json')
+    if (!meta) {
+      res.statusCode = 404
+      return res.end(JSON.stringify({ error: 'import-meta not found', id, hint: '该卡尚未经同步远程导入，无导入来源元数据' }))
+    }
+    res.statusCode = 200
+    return res.end(JSON.stringify({ id, meta }))
+  }
+}

package/dist/server-core/cardListCache.js

@@ -0,0 +1,68 @@
+/**
+ * 远端卡片列表缓存（dev server 进程内单例）。
+ *
+ * 用途：推送（保存 / 预览）前确认目标卡片确实存在于 FinMall 卡片列表中，
+ * 拦截「推到已删除 / pageId 错位的卡片」这类风险。
+ *
+ * 数据来源：IDC10001 卡片列表（与同步同一份数据）。刷新时机由同步逻辑触发——
+ * 全量同步（无 cardCode 过滤）时整体替换；单卡同步时增量合并，避免清空其他卡片。
+ * 列表条目字段：cardId（数字型，等于 schema.pageId）、code（英文卡 id）、cardName。
+ *
+ * 单例性：本模块被 server/* 与 skills/finmall-card-sync 以相同绝对路径 import，
+ * 在同一 dev server 进程内共享同一份内存，故同步写入、推送读取天然一致。
+ */
+
+const cardIndex = new Map(); // cardId(String) -> { cardId, code, cardName }
+let lastRefreshedAt = 0;
+
+/**
+ * 写入/合并卡片列表。
+ * @param {Array<{cardId:string|number, code?:string, cardName?:string}>} cards
+ * @param {{ full?: boolean }} [opts] full=true 时整体替换（先清空），否则增量合并。
+ */
+export function refreshCardList(cards, { full = false } = {}) {
+  if (full) cardIndex.clear();
+  for (const c of cards || []) {
+    if (c == null || c.cardId == null) continue;
+    const id = String(c.cardId);
+    cardIndex.set(id, { cardId: id, code: c.code, cardName: c.cardName });
+  }
+  lastRefreshedAt = Date.now();
+}
+
+/** 卡片是否存在于缓存列表（按 cardId / pageId 查）。 */
+export function hasCardId(cardId) {
+  return cardIndex.has(String(cardId));
+}
+
+/** 取缓存中的卡片元信息，不存在返回 null。 */
+export function getCard(cardId) {
+  return cardIndex.get(String(cardId)) || null;
+}
+
+/** 缓存是否已非空（至少同步过一次全量列表）。 */
+export function cacheSize() {
+  return cardIndex.size;
+}
+
+/**
+ * 推送前存在性校验：目标卡片是否确实在远端卡片列表中（按 cardId/pageId 查）。
+ * - 缓存为空（本次 dev server 尚未全量同步过）：放行，返回 allowed=true，避免误拦截首推。
+ * - 命中：allowed=true。
+ * - 未命中：allowed=false，reason 给出拦截说明（疑似已删除 / pageId 错位）。
+ * @param {string|number} pageId
+ * @returns {{ allowed: boolean, reason: string }}
+ */
+export function checkPushAllowed(pageId) {
+  if (cardIndex.size === 0) return { allowed: true, reason: '' };
+  if (hasCardId(pageId)) return { allowed: true, reason: '' };
+  return {
+    allowed: false,
+    reason: `卡片 pageId=${pageId} 不在远端卡片列表中，疑似已删除或 pageId 错位，请先「远程同步」刷新列表后再推送`,
+  };
+}
+
+/** 上次刷新时间戳（ms），未刷新为 0。 */
+export function lastRefreshed() {
+  return lastRefreshedAt;
+}