cardbuddy 0.11.0 → 0.12.1

package/dist/preview-editor/index.html

@@ -8,8 +8,8 @@
     <link rel="icon" type="image/png" sizes="16x16" href="/assets/favicon-16-Cg6Nrosk.png" />
     <link rel="icon" type="image/png" sizes="32x32" href="/assets/favicon-32-B_1744sp.png" />
     <link rel="apple-touch-icon" sizes="180x180" href="/assets/apple-touch-icon-BQcES9QK.png" />
-    <script type="module" crossorigin src="/assets/index-jl4YJzKv.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-B4VZgNSK.css">
+    <script type="module" crossorigin src="/assets/index-CHuGGIR3.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CQScMhyg.css">
   </head>
   <body>
     <div id="app"></div>

package/dist/standalone.js

@@ -430,12 +430,20 @@ export async function startServer(userConfig = {}) {
   subscribeLog((lines) => events.notify({ lines }, 'service-log'))
 
   const vite = await createEmbeddedVite(config)
+  // AI 工具调度复用仓库的 mcp/tools.mjs（发布态为包内快照），其 mcp/client.mjs 在 import 时
+  // 读取 CARD_ROOT（卡片工程根）与 CARD_API_BASE（dev server 基址）。loadTools() 是懒加载
+  // （首次 AI 请求才 import），故这里在启动期注入即可；已有的显式环境变量优先，不覆盖。
+  if (!process.env.CARD_ROOT) process.env.CARD_ROOT = config.root
+  if (!process.env.CARD_API_BASE) process.env.CARD_API_BASE = apiBase
   // upstream（FINMALL_BASE_URL）透传给资源代理中间件，使其能回源 FinMall 取站内资源
   mountCoreMiddlewares(app, {
     root: config.root,
     viteServer: vite,
     upstream: config.upstream,
     notify: events.notify,
+    // card_patch 走 card_write 管线（历史快照 + validate/render_status）：本服务的 root 就是
+    // 卡片工程根，且 CARD_ROOT 已指向同一处，dispatch 落点一致，故显式开启。
+    allowDispatch: true,
     // 代码桥单文件监听注入 chokidar 版：原子保存（改名覆盖）由 add 兜住，awaitWriteFinish 防半截读
     watchFile: (file, onChange) => {
       const watcher = chokidar.watch(file, {

package/dist/vendored/mcp/client.mjs

@@ -0,0 +1,537 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { listCards, readCardFiles, writeCardFiles } from '../server/core/cardFiles.js'
+import { validateCard, resolvePython, scriptPath } from '../server/core/cardValidate.js'
+import { listSnapshots, saveSnapshot, HISTORY_DIR } from '../server/core/cardHistory.js'
+import { devApiBase } from '../tools/finmall-env.mjs'
+
+/**
+ * MCP 薄 HTTP 客户端：只封装对 dev server（端口见 .env.cb 的 FINMALL_DEV_PORT）的请求，不复制任何业务逻辑。
+ *
+ * 降级策略（与 tools/card-check.mjs 一致）：
+ * - list / read / write / validate：dev server 未启动（fetch 抛连接错误）时，
+ *   降级为直接读盘 / 写盘 / 跑 Python —— 复用 server/* 导出的同一份实现，避免漂移。
+ * - render_status / sync / save：依赖 dev server 与 FinMall 登录态，不支持离线降级；
+ *   screenshot 在 dev server 未启动时降级到独立离线渲染器。
+ */
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const ROOT = process.env.CARD_ROOT ? resolve(process.env.CARD_ROOT) : resolve(__dirname, '..')
+// dev server 端口由 .env.cb 的 FINMALL_DEV_PORT 控制（默认 5180）；
+// 仍可用 CARD_API_BASE 覆盖（如 dev server 跑在非默认端口）。
+const BASE = (process.env.CARD_API_BASE || devApiBase()).replace(/\/$/, '')
+
+/** 发起 GET，返回 { status, buf, text, json, contentType }；任何网络错误向上抛，由调用方决定降级 */
+async function httpGet(p) {
+  const res = await fetch(BASE + p, { headers: { Accept: 'application/json, image/png' } })
+  const buf = Buffer.from(await res.arrayBuffer())
+  let text = null
+  let json = null
+  try {
+    text = buf.toString('utf8')
+    json = text ? JSON.parse(text) : null
+  } catch {
+    /* 非 JSON 响应（如截图 png） */
+  }
+  return { status: res.status, buf, text, json, contentType: res.headers.get('content-type') || '' }
+}
+
+/** 发起 POST（JSON body） */
+async function httpPost(p, body) {
+  const res = await fetch(BASE + p, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body || {}),
+  })
+  const buf = Buffer.from(await res.arrayBuffer())
+  let text = null
+  let json = null
+  try {
+    text = buf.toString('utf8')
+    json = text ? JSON.parse(text) : null
+  } catch {
+    /* 非 JSON 响应 */
+  }
+  return { status: res.status, buf, text, json, contentType: res.headers.get('content-type') || '' }
+}
+
+// 需要 FinMall 登录态的远端工具：提示语要额外说明「且已登录 FinMall」。
+const REMOTE_TOOLS = new Set(['card_sync', 'card_save', 'card_slice_upload'])
+
+const DEV_REQUIRED = (tool) => ({
+  source: null,
+  error: 'dev-server-required',
+  message: `${tool} 需要 dev server 已启动（npm run dev）${REMOTE_TOOLS.has(tool) ? ' 且已登录 FinMall' : ''}。本工具不支持离线降级。`,
+})
+
+// ---- card_list ----
+export async function cardList() {
+  try {
+    const { status, json } = await httpGet('/__cards')
+    if (status === 200 && json && Array.isArray(json.cards)) return { source: 'http', cards: json.cards }
+  } catch {
+    /* 降级 */
+  }
+  return { source: 'local', cards: listCards(ROOT) }
+}
+
+// ---- card_read ----
+export async function cardRead(id) {
+  try {
+    const { status, json } = await httpGet(`/__card/${encodeURIComponent(id)}`)
+    if (status === 200 && json) return { source: 'http', ...json }
+  } catch {
+    /* 降级 */
+  }
+  const r = readCardFiles(ROOT, id)
+  if (!r) return { source: 'local', error: 'card not found', id }
+  return { source: 'local', ...r }
+}
+
+// ---- card_write（闭环收口：写前自动留历史快照，写完自动校验）----
+export async function cardWrite(id, payload, { verify = true, snapshot = true } = {}) {
+  const dir = path.join(ROOT, 'src', 'cards', id)
+  let writeResult = null
+  let source = 'local'
+
+  // 安全网：写卡前把「当前版本 schema」落一张历史快照（与编辑器改卡先 POST /__history 同语义），
+  // 使 AI 编辑同样可被 card_rollback 撤销。card_rollback 内部写回传 snapshot:false 避免重复留快照。
+  let safetyTs = null
+  if (snapshot && payload && payload.schema) {
+    try {
+      const { status, json } = await httpGet(`/__card/${encodeURIComponent(id)}`)
+      if (status === 200 && json && json.schema) {
+        const h = await httpPost(`/__history/${encodeURIComponent(id)}`, { schema: json.schema })
+        if (h.status === 200 && h.json && h.json.ok) safetyTs = h.json.ts
+      }
+    } catch {
+      /* dev server 不在线，走本地降级 */
+    }
+    if (safetyTs == null) {
+      try {
+        const sp = path.join(dir, 'schema.json')
+        if (fs.existsSync(sp)) {
+          const prev = JSON.parse(fs.readFileSync(sp, 'utf8'))
+          safetyTs = saveSnapshot(dir, prev).ts
+        }
+      } catch {
+        /* 首次写卡（无旧 schema）或快照失败不阻断写卡 */
+      }
+    }
+  }
+
+  try {
+    const { status, json } = await httpPost(`/__card/${encodeURIComponent(id)}`, payload)
+    if (status === 200 && json) {
+      writeResult = json
+      source = 'http'
+    } else if (status === 404) {
+      return { source: 'http', error: 'card not found', id }
+    } else if (status === 400) {
+      return { source: 'http', error: json?.error || 'invalid request', detail: json }
+    }
+  } catch {
+    /* 降级 */
+  }
+
+  if (!writeResult) {
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+      return { source: 'local', error: 'card not found', id }
+    }
+    try {
+      writeResult = { ok: true, written: writeCardFiles(dir, payload) }
+      try { await import('../server/core/cardImportMeta.js').then((m) => m.markDirty(dir, true)) } catch { /* 无侧车时忽略 */ }
+    } catch (e) {
+      return { source: 'local', error: 'write failed', message: String(e && e.message) }
+    }
+  }
+
+  const verifyResult = { validate: null, renderStatus: null }
+  if (verify) {
+    if (source === 'http') {
+      try {
+        const v = await httpGet(`/__validate/${encodeURIComponent(id)}`)
+        if (v.status === 200 && v.json) verifyResult.validate = v.json
+      } catch {
+        /* 忽略 */
+      }
+      try {
+        const r = await httpGet(`/__render-status/${encodeURIComponent(id)}`)
+        if (r.status === 200 && r.json) verifyResult.renderStatus = r.json
+      } catch {
+        /* 忽略 */
+      }
+    } else {
+      // 本地降级：只能跑 Python 硬校验；render_status 需 dev server（SSR），标注 skipped
+      const python = resolvePython()
+      const sp = path.join(dir, 'schema.json')
+      if (python && fs.existsSync(sp)) {
+        verifyResult.validate = await validateCard(python, scriptPath(ROOT), sp, { checkData: true })
+      } else if (!python) {
+        verifyResult.validate = { ok: false, errors: ['python-not-found'], warnings: [], toolError: 'python-not-found' }
+      }
+      verifyResult.renderStatus = { skipped: true, reason: 'dev server 未启动，无法 SSR 自检；请先 npm run dev' }
+    }
+  }
+
+  return {
+    source,
+    written: writeResult.written,
+    ...(safetyTs != null ? { safetySnapshotTs: safetyTs } : {}),
+    ...(verify ? { verify: verifyResult } : {}),
+  }
+}
+
+// ---- card_validate ----
+export async function cardValidate(id, { noData = false } = {}) {
+  try {
+    const { status, json } = await httpGet(`/__validate/${encodeURIComponent(id)}${noData ? '?no-data' : ''}`)
+    if (status === 200 && json) return { source: 'http', ...json }
+    if (status === 404) return { source: 'http', error: 'card not found', id }
+  } catch {
+    /* 降级 */
+  }
+  const dir = path.join(ROOT, 'src', 'cards', id)
+  const sp = path.join(dir, 'schema.json')
+  if (!fs.existsSync(sp)) return { source: 'local', error: 'card not found', id }
+  const python = resolvePython()
+  if (!python) {
+    return {
+      source: 'local',
+      error: 'python-not-found',
+      message: '未找到 python3/python，请安装 Python 或设置 DSL_PYTHON 环境变量',
+    }
+  }
+  const r = await validateCard(python, scriptPath(ROOT), sp, { checkData: !noData })
+  return { source: 'local', id, ...r }
+}
+
+// ---- card_render_status（需 dev server）----
+export async function cardRenderStatus(id) {
+  try {
+    const { status, json } = await httpGet(`/__render-status/${encodeURIComponent(id)}`)
+    if (status === 200 && json) return { source: 'http', ...json }
+    if (status === 404) return { source: 'http', error: 'card not found', id }
+  } catch {
+    /* 降级不可用 */
+  }
+  return DEV_REQUIRED('card_render_status')
+}
+
+// ---- card_node_models（需 dev server，Task #5 暴露的字段结构树）----
+export async function cardNodeModels(id) {
+  try {
+    const { status, json } = await httpGet(`/__node-models/${encodeURIComponent(id)}`)
+    if (status === 200 && json) return { source: 'http', ...json }
+    if (status === 404) return { source: 'http', error: 'card not found', id }
+  } catch {
+    /* 降级不可用 */
+  }
+  return DEV_REQUIRED('card_node_models')
+}
+
+// ---- card_import_meta（需 dev server）----
+export async function cardImportMeta(id) {
+  try {
+    const { status, json } = await httpGet(`/__import-meta/${encodeURIComponent(id)}`)
+    if (status === 200 && json) return { source: 'http', ...json }
+    if (status === 404) return { source: 'http', error: 'import-meta not found', id, hint: json?.hint }
+  } catch {
+    /* 降级不可用 */
+  }
+  return DEV_REQUIRED('card_import_meta')
+}
+
+// ---- card_route_input（离线：直接复用 skill 的输入路由判定器，无需 dev server）----
+/** 展开 `~` 与工作区相对路径：MCP 调用方常给 `~/Downloads/...` 或相对工程根的路径 */
+function expandInputPath(p) {
+  const raw = String(p == null ? '' : p).trim()
+  if (!raw) return raw
+  if (raw === '~') return process.env.HOME || raw
+  if (raw.startsWith('~/') || raw.startsWith('~\\')) return path.join(process.env.HOME || '', raw.slice(2))
+  return path.isAbsolute(raw) ? raw : resolve(ROOT, raw)
+}
+
+export async function cardRouteInput({ path: inputPath } = {}) {
+  if (!inputPath) {
+    return {
+      source: 'local',
+      error: 'missing-args',
+      message: 'path 必填：MeaXure 标注导出目录 / UI 要素包 / 卡片目录 / 设计稿 PNG',
+    }
+  }
+  const mod = await import('../skills/dsl-card-generator/scripts/route_input.mjs')
+  const r = mod.routeInput(expandInputPath(inputPath))
+  if (r.error) return { source: 'local', ...r }
+  const hint =
+    r.kind === 'meaxure-export' && r.preprocess && r.preprocess.needed
+      ? '先执行 next 里的两条命令跑 sketch-spec-to-card 前处理，产出 UI/<稿名>/ 要素包后再逐卡生成；禁止直接读 preview/ 整图建卡'
+      : r.kind === 'meaxure-export'
+        ? '该导出已前处理过，直接消费 next 给出的存量产物，不重复跑管线'
+        : r.kind === 'unknown'
+          ? '判不出输入形态：向用户确认，不要猜（CLI 等价退出码 3）'
+          : '按 next 的命令继续（Workflow A 建卡 / Workflow B 改卡）'
+  return { source: 'local', ok: r.kind !== 'unknown', ...r, hint }
+}
+
+// ---- card_scaffold（离线：直接调 scaffold lib，无需 dev server）----
+export async function cardScaffold({ intent, id, name, outBase, platform, force, from } = {}) {
+  const lib = await import('../skills/dsl-card-generator/scripts/lib/scaffold.mjs')
+  if (!from && (!intent || !lib.SCAFFOLD_INTENTS.includes(intent))) {
+    return { error: 'invalid-intent', message: `intent 必须是 ${lib.SCAFFOLD_INTENTS.join('|')}`, intent }
+  }
+  if (!id) return { error: 'missing-id', message: '缺少 id' }
+  const base = outBase ? resolve(outBase) : path.join(ROOT, 'src', 'cards')
+  if (force) {
+    const dir = path.join(base, id)
+    if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true })
+  }
+  try {
+    if (from) {
+      const dir = lib.cloneCardFrom(from, id, { name, outBase: base })
+      return { source: 'local', ok: true, from, id, name: name || undefined, dir, note: '整卡模板克隆：pageId/name 已重写，封面未复制（定稿后重新渲染生成）' }
+    }
+    const dir = lib.writeSkeleton(id, intent, { name, platform, outBase: base })
+    return { source: 'local', ok: true, intent, id, name: name || '新建卡片', dir }
+  } catch (e) {
+    return { source: 'local', error: 'scaffold-failed', message: String((e && e.message) || e) }
+  }
+}
+
+// ---- card_add_component（离线：直接调 scaffold lib + 离线硬校验）----
+/** 归一化 --set-prop 风格的属性覆盖：支持 "key=value" 字符串数组或 {key,value} 对象数组 */
+function normalizeSetProps(setProps) {
+  const list = Array.isArray(setProps) ? setProps : setProps ? [setProps] : []
+  return list.map((p) => {
+    if (typeof p === 'string') {
+      const i = p.indexOf('=')
+      if (i < 0) throw new Error(`setProps 需 "key=value" 形式：${p}`)
+      const key = p.slice(0, i).trim()
+      const value = p.slice(i + 1)
+      if (!key) throw new Error(`setProps 缺 key：${p}`)
+      return { key, value, isVar: value.startsWith('$') }
+    }
+    const key = String((p && p.key) || '').trim()
+    const value = p ? String(p.value ?? '') : ''
+    if (!key) throw new Error('setProps 元素缺 key')
+    return { key, value, isVar: value.startsWith('$') }
+  })
+}
+
+export async function cardAddComponent({ id, parent, className, text, click, setProps } = {}) {
+  if (!id || !parent || !className) {
+    return { error: 'missing-args', message: 'id / parent / className 必填' }
+  }
+  const lib = await import('../skills/dsl-card-generator/scripts/lib/scaffold.mjs')
+  let r
+  let propOverrides = []
+  try {
+    // insertComponent 签名是 (id, opts)，与 CLI add_component.mjs 保持一致
+    propOverrides = normalizeSetProps(setProps)
+    r = lib.insertComponent(id, { parentId: parent, className, text, click, propOverrides })
+  } catch (e) {
+    return {
+      source: 'local',
+      error: 'insert-failed',
+      message: String((e && e.message) || e),
+      hint: '确认 parent 是容器节点（有 slots，或 ListLayout/GridLayout）；用 card_read 查 componentId',
+    }
+  }
+  // 插入成功后离线硬校验，把结果一并带回（python 缺失时 validate 会标注 python-not-found）
+  const validate = await cardValidate(id, { noData: false })
+  return {
+    source: 'local',
+    ok: true,
+    inserted: { componentId: r.id, className: r.className, parentId: r.parentId, parentClassName: r.parentClassName },
+    setProps: r.setProps,
+    dir: r.dir,
+    validate,
+  }
+}
+
+// ---- card_screenshot（优先 dev server；未启动时降级到独立渲染器）----
+export async function cardScreenshot(id, { format = 'json', width = 390 } = {}) {
+  try {
+    const { status, buf, json, contentType } = await httpGet(
+      `/__screenshot/${encodeURIComponent(id)}?width=${width}&format=${format}`,
+    )
+    if (status === 200) {
+      if (format === 'json') return { source: 'http', ...(json || {}) }
+      return { source: 'http', mime: contentType || 'image/png', base64: buf.toString('base64') }
+    }
+    if (status === 404) return { source: 'http', error: 'card not found', id }
+    return { source: 'http', error: json?.error || 'screenshot-failed', message: json?.message, fix: json?.fix }
+  } catch {
+    /* dev server 不可用：走独立离线渲染器 */
+  }
+  try {
+    const { renderCardScreenshot } = await import('../skills/dsl-card-generator/scripts/render_card.mjs')
+    const r = await renderCardScreenshot({ id, width, format })
+    if (r.error) return { source: 'standalone', error: r.error, message: r.message }
+    return { source: 'standalone', ...(format === 'json' ? r : { mime: r.mime, base64: r.base64 }) }
+  } catch (e) {
+    return DEV_REQUIRED('card_screenshot')
+  }
+}
+
+// ---- card_sync（需 dev server + FinMall 登录态）----
+export async function cardSync({ cardCode } = {}) {
+  try {
+    const { status, json } = await httpPost('/__sync', { cardCode })
+    if (status === 200) return { source: 'http', ...(json || {}) }
+    return { source: 'http', error: json?.error || 'sync-failed', message: json?.message }
+  } catch {
+    /* 降级不可用 */
+  }
+  return DEV_REQUIRED('card_sync')
+}
+
+// ---- card_save（需 dev server + FinMall 登录态）----
+export async function cardSave({ schema, code, skeletonScreen } = {}) {
+  try {
+    const { status, json } = await httpPost('/__save', { schema, code, skeletonScreen })
+    if (status === 200) return { source: 'http', ...(json || {}) }
+    return { source: 'http', error: json?.error || 'save-failed', message: json?.message }
+  } catch {
+    /* 降级不可用 */
+  }
+  return DEV_REQUIRED('card_save')
+}
+
+// ---- card_slice_upload（需 dev server + FinMall 登录态）----
+// 切图上传只按单卡范围执行：端点内部复用 finmall-card-sync 的 uploadSlices({ cardId })，
+// 上传 src/slices 里该卡引用的图并把 schema/data 的 /slices/ 引用改写为 @filestore/ 线上地址。
+export async function sliceUpload({ cardId, force } = {}) {
+  try {
+    const { status, json } = await httpPost('/__slice-upload', { cardId, force })
+    if (status === 200) return { source: 'http', ...(json || {}) }
+    return { source: 'http', error: json?.error || 'slice-upload-failed', message: json?.message }
+  } catch {
+    /* 降级不可用 */
+  }
+  return DEV_REQUIRED('card_slice_upload')
+}
+
+// ---- 历史快照：内部共用读取 ----
+// 与编辑器撤销/重做同源（.history/ 由 cardWrite/编辑器写卡时自动累积）。
+// card_history 只返回元数据（ts/时间/字节数/节点数），不把整份 schema 倒进上下文。
+
+/** 递归统计节点数（view 即根节点；子节点双通道：.components 直连 + .slots[].components 插槽） */
+function countNodes(node) {
+  if (!node || typeof node !== 'object') return 0
+  let n = 1
+  for (const c of Array.isArray(node.components) ? node.components : []) n += countNodes(c)
+  for (const s of Array.isArray(node.slots) ? node.slots : []) {
+    for (const c of Array.isArray(s && s.components) ? s.components : []) n += countNodes(c)
+  }
+  return n
+}
+
+function snapshotMeta(s) {
+  const schema = s.schema != null ? s.schema : s
+  return {
+    ts: s.ts,
+    time: new Date(s.ts).toISOString(),
+    bytes: Buffer.byteLength(JSON.stringify(schema), 'utf8'),
+    components: countNodes(schema.view),
+  }
+}
+
+/** 读取全部快照 [{ts, schema}]（旧→新）。优先 dev server，离线降级直接读 .history/ */
+async function readSnapshots(id) {
+  try {
+    const { status, json } = await httpGet(`/__history/${encodeURIComponent(id)}`)
+    if (status === 200 && json && Array.isArray(json.snapshots)) {
+      return { source: 'http', snapshots: json.snapshots.map((s) => ({ ts: s.ts, schema: s.schema })) }
+    }
+    if (status === 404) return { source: 'http', error: 'card not found', id }
+  } catch {
+    /* 降级 */
+  }
+  const dir = path.join(ROOT, 'src', 'cards', id)
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    return { source: 'local', error: 'card not found', id }
+  }
+  const histDir = path.join(dir, HISTORY_DIR)
+  const out = []
+  for (const s of listSnapshots(histDir)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(path.join(histDir, s.file), 'utf8'))
+      out.push({ ts: s.ts, schema: data.schema != null ? data.schema : data })
+    } catch {
+      /* 单文件损坏跳过 */
+    }
+  }
+  return { source: 'local', snapshots: out }
+}
+
+// ---- card_history（列出编辑历史快照元数据）----
+export async function cardHistory(id) {
+  const r = await readSnapshots(id)
+  if (r.error) return r
+  const snapshots = r.snapshots.map(snapshotMeta)
+  return {
+    source: r.source,
+    id,
+    count: snapshots.length,
+    latestTs: snapshots.length ? snapshots[snapshots.length - 1].ts : null,
+    snapshots,
+    hint: snapshots.length
+      ? '用 card_rollback 回滚到指定 ts（默认 latestTs）；回滚前会自动把当前版本另存为新快照，回滚本身可撤销。'
+      : '暂无历史快照——快照在编辑器或 card_write 每次写卡时自动累积。',
+  }
+}
+
+// ---- card_rollback（回滚到指定快照，默认最新）----
+export async function cardRollback(id, { ts, verify = true } = {}) {
+  const r = await readSnapshots(id)
+  if (r.error) return r
+  if (!r.snapshots.length) {
+    return { source: r.source, id, error: 'no-history', message: '该卡片暂无历史快照，无法回滚。' }
+  }
+  const target = ts != null ? r.snapshots.find((s) => s.ts === Number(ts)) : r.snapshots[r.snapshots.length - 1]
+  if (!target) {
+    return {
+      source: r.source,
+      id,
+      error: 'snapshot-not-found',
+      message: `快照 ts=${ts} 不存在。`,
+      available: r.snapshots.map((s) => s.ts),
+    }
+  }
+
+  // 安全网：先把「回滚前的当前版本」另存为新快照，保证回滚本身可撤销。
+  let safetyTs = null
+  const current = await cardRead(id)
+  if (current && current.schema && typeof current.schema === 'object') {
+    if (r.source === 'http') {
+      try {
+        const { status, json } = await httpPost(`/__history/${encodeURIComponent(id)}`, { schema: current.schema })
+        if (status === 200 && json && json.ok) safetyTs = json.ts
+      } catch {
+        /* 安全快照失败不阻断回滚，但会在结果中标注 */
+      }
+    } else {
+      try {
+        safetyTs = saveSnapshot(path.join(ROOT, 'src', 'cards', id), current.schema).ts
+      } catch {
+        /* 同上 */
+      }
+    }
+  }
+
+  const written = await cardWrite(id, { schema: target.schema }, { verify, snapshot: false })
+  if (written.error) return { source: written.source, id, error: written.error, message: written.message }
+  return {
+    source: written.source,
+    id,
+    rolledBackTo: target.ts,
+    rolledBackToTime: new Date(target.ts).toISOString(),
+    safetySnapshotTs: safetyTs,
+    ...(safetyTs == null ? { warning: '回滚前版本未能另存为安全快照，本次回滚不可通过快照撤销。' } : {}),
+    written: written.written,
+    ...(verify ? { verify: written.verify } : {}),
+  }
+}