cardbuddy 0.19.3 → 0.20.0

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

@@ -1,113 +1,309 @@
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { createHash } from 'node:crypto'
-import { writeFile, mkdir } from 'node:fs/promises'
 import { checkPushAllowed, refreshCardList, hasCardId } from './cardListCache.js'
 import { assertRemoteSource } from './cardSidecar.js'
 import { log, fmtBytes } from './logger.js'
 import { buildImportMeta, writeImportMeta } from './cardImportMeta.js'
-import { resolveSkillPathOrProject } from './skillPaths.js'
+import { resolveSkillPathOrProject, projectSkillsDir } from './skillPaths.js'
 
 /** finmall-card-sync 的批量同步脚本（同步 / 远端预览共用），相对 skills/ */
 const SYNC_SCRIPT_REL = 'finmall-card-sync/scripts/api_batch_sync.mjs'
 
+/** 卡片 id 合法形态（与 normalizeCard / 新建卡同源正则） */
+const CARD_CODE_RE = /^[A-Za-z0-9_-]+$/
+
+/**
+ * 同步任务表（进程内单例）。
+ * 任务制模型：POST /__sync 立即返回 jobId，syncCards 在后台跑；
+ * 前端经 GET /__sync/progress 轮询进度、POST /__sync/cancel 取消。
+ * 保留最近若干个终态任务，供「轮询晚于完成」的前端仍能取到最终结果。
+ */
+const syncJobs = new Map() // jobId -> job
+const SYNC_JOB_KEEP = 8
+let syncJobSeq = 0
+
+/** 取当前活跃（未完成）同步任务；无则 null */
+function activeSyncJob() {
+  for (const job of syncJobs.values()) {
+    if (!job.finished) return job
+  }
+  return null
+}
+
+/** 终态任务入表并淘汰最旧的（保持 Map 插入序 = 创建序） */
+function rememberSyncJob(job) {
+  syncJobs.set(job.id, job)
+  while (syncJobs.size > SYNC_JOB_KEEP) {
+    const oldest = syncJobs.keys().next().value
+    syncJobs.delete(oldest)
+  }
+}
+
+/** 判断是否为「凭据缺失」类错误（与旧 /__sync 行为一致：转 needCredentials 让前端弹登录表单） */
+function isNoCredentialsError(e) {
+  return (
+    !!e &&
+    (e.code === 'NO_CREDENTIALS' ||
+      /credentials\.json|credentials 不存在|NO_CREDENTIALS/.test(String(e && e.message)))
+  )
+}
+
+/** 同步完成后的终端汇总打印（与旧实现同款美化框，便于 dev server 日志排查） */
+function logSyncSummary(summary, requestLabel) {
+  const lines = []
+  lines.push(`请求卡片：${requestLabel}`)
+  if (summary.synced && summary.synced.length) {
+    lines.push(`已同步 ${summary.synced.length} 张：`)
+    for (const s of summary.synced) {
+      const f = s.files || {}
+      // 空白卡（远端无 schemaValue）：标注落盘策略，避免误读成「抓到了完整 schema」。
+      const tag = s.blank
+        ? s.keptLocal
+          ? ' [空白卡·保留本地]'
+          : ' [空白卡·新建空白 schema]'
+        : ''
+      lines.push(
+        `• ${s.id}${s.title ? `（${s.title}）` : ''}${tag}  schema=${fmtBytes(f.schema)} data=${fmtBytes(f.data)} cover=${fmtBytes(f.cover)}`
+      )
+    }
+  } else {
+    lines.push('已同步 0 张')
+  }
+  if (summary.failed && summary.failed.length) {
+    lines.push(`失败 ${summary.failed.length} 张：`)
+    for (const f of summary.failed) {
+      lines.push(`✗ ${f.id || ''}  ${f.error || ''}`)
+    }
+  }
+  if (summary.duplicates && summary.duplicates.length) {
+    lines.push(`重复 schema ${summary.duplicates.length} 项：${summary.duplicates.map((d) => d.id).join('、')}`)
+  }
+  log.box({ title: '远端同步完成', level: summary.success ? 'ok' : 'warn', lines })
+}
+
 /**
  * 预览「同步远程数据」按钮的服务端处理：经已认证的 FinMall 浏览器会话拉取最新卡片写回 src/cards。
  * 复用 finmall-card-sync 的 syncCards（connectOverCDP 连用户已开的 Chrome，disconnect 不杀进程）。
  *
+ * 任务制端点（编辑器「远端 → 查看全部 → 下载选中 / 全部下载」的进度弹窗依赖）：
+ * - POST /__sync                body { cardCode? , cardCodes? } → 立即返回 { ok, jobId, total }
+ * - GET  /__sync/progress?jobId → { ok, done, total, currentId, currentTitle, finished, result }
+ * - POST /__sync/cancel         body { jobId } → 设取消探针，下一张卡片前中止
+ * - GET  /__remote-cards        → { ok, cards:[{id,title,cardId,coverUrl}] }（只读全量列表）
+ *
  * @param {{ root: string }} opts
  * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, next: Function) => void}
  */
 export function createSyncMiddleware({ root }) {
-  return function syncMiddleware(req, res, next) {
-    const pathname = decodeURIComponent((req.url || '').split('?')[0])
-    if (pathname !== '/__sync') return next()
-    if ((req.method || 'GET').toUpperCase() !== 'POST') return next()
-
+  /** 读 JSON body（上限 1MB，与旧实现一致） */
+  const readJsonBody = (req, res, cb) => {
     let body = ''
     req.setEncoding('utf8')
     req.on('data', (c) => {
       body += c
-      if (body.length > 1 * 1024 * 1024) req.destroy()
+      if (body.length > 1024 * 1024) req.destroy()
     })
-    req.on('end', async () => {
-      let payload
+    req.on('end', () => {
       try {
-        payload = JSON.parse(body || '{}')
+        cb(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) }))
+        res.end(JSON.stringify({ error: 'invalid json', message: String(e.message) }))
       }
-      try {
-        const skillPath = resolveSkillPathOrProject(root, SYNC_SCRIPT_REL)
-        const { syncCards } = await import(pathToFileURL(skillPath).href)
-        const summary = await syncCards({
-          cardCode: payload.cardCode || undefined,
-          outRoot: path.join(root, 'src', 'cards'),
-          // 从 server/core 上下文注入 cardImportMeta 实现：消费者工程下 api_batch_sync.mjs 按自身
-          // skills 位置推导的 workspace 会指向错误根，动态 import 找不到 cardImportMeta.js。
-          importMeta: { buildImportMeta, writeImportMeta },
-          // 从 server/core 上下文注入 cardListCache 实现：同 cardImportMeta，消费者工程下按自身 skills
-          // 位置推导的 workspace 会指向错误根，动态 import 找不到 cardListCache.js，导致全量同步时无法
-          // 刷新进程内单例，推送前「存在性闸门」形同虚设。注入后三态都能正确刷新。
-          cardListCache: { refreshCardList, checkPushAllowed, hasCardId },
-        })
-        // 同步成功后在 dev server 终端打印同步结果（统一美化框）。
-        const lines = []
-        lines.push(`请求卡片：${payload.cardCode || '(全部)'}`)
-        if (summary.synced && summary.synced.length) {
-          lines.push(`已同步 ${summary.synced.length} 张：`)
-          for (const s of summary.synced) {
-            const f = s.files || {}
-            // 空白卡（远端无 schemaValue）：标注落盘策略，避免误读成「抓到了完整 schema」。
-            const tag = s.blank
-              ? s.keptLocal
-                ? ' [空白卡·保留本地]'
-                : ' [空白卡·新建空白 schema]'
-              : ''
-            lines.push(
-              `• ${s.id}${s.title ? `（${s.title}）` : ''}${tag}  schema=${fmtBytes(f.schema)} data=${fmtBytes(f.data)} cover=${fmtBytes(f.cover)}`
+    })
+  }
+
+  return function syncMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const method = (req.method || 'GET').toUpperCase()
+
+    // ---- 远端完整卡片列表（只读）：编辑器「查看全部」网格数据源 ----
+    if (pathname === '/__remote-cards') {
+      if (method !== 'GET') return next()
+      // 与同步共用后台 Chrome 会话，并发会互相干扰：同步进行中直接拒绝，让前端稍后重试
+      if (activeSyncJob()) {
+        res.statusCode = 409
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(
+          JSON.stringify({ ok: false, error: 'sync_in_progress', message: '正在拉取卡片，请稍候再查看远端列表' })
+        )
+      }
+      ;(async () => {
+        try {
+          const skillPath = resolveSkillPathOrProject(root, SYNC_SCRIPT_REL)
+          const { listRemoteCards } = await import(pathToFileURL(skillPath).href)
+          const cards = await listRemoteCards({})
+          res.statusCode = 200
+          res.setHeader('Content-Type', 'application/json')
+          return res.end(JSON.stringify({ ok: true, cards }))
+        } catch (e) {
+          if (isNoCredentialsError(e)) {
+            res.statusCode = 200
+            res.setHeader('Content-Type', 'application/json')
+            return res.end(
+              JSON.stringify({
+                ok: false,
+                error: 'need_credentials',
+                needCredentials: true,
+                message: String(e && e.message),
+              })
             )
           }
-        } else {
-          lines.push('已同步 0 张')
-        }
-        if (summary.failed && summary.failed.length) {
-          lines.push(`失败 ${summary.failed.length} 张：`)
-          for (const f of summary.failed) {
-            lines.push(`✗ ${f.id || ''}  ${f.error || ''}`)
-          }
+          log.error('拉取远端卡片列表失败', e)
+          res.statusCode = 500
+          res.setHeader('Content-Type', 'application/json')
+          return res.end(JSON.stringify({ ok: false, error: 'list failed', message: String(e && e.message) }))
         }
-        if (summary.duplicates && summary.duplicates.length) {
-          lines.push(`重复 schema ${summary.duplicates.length} 项：${summary.duplicates.map((d) => d.id).join('、')}`)
+      })()
+      return
+    }
+
+    // ---- 同步进度查询（轮询） ----
+    if (pathname === '/__sync/progress') {
+      if (method !== 'GET') return next()
+      const jobId = new URL(req.url, 'http://127.0.0.1').searchParams.get('jobId') || ''
+      const job = syncJobs.get(jobId)
+      if (!job) {
+        res.statusCode = 404
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(JSON.stringify({ ok: false, error: 'unknown job', message: '同步任务不存在或已过期' }))
+      }
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(
+        JSON.stringify({
+          ok: true,
+          jobId: job.id,
+          done: job.progress.done,
+          total: job.progress.total,
+          currentId: job.progress.currentId,
+          currentTitle: job.progress.currentTitle,
+          finished: job.finished,
+          result: job.result,
+        })
+      )
+    }
+
+    // ---- 取消同步（下一张卡片前生效；已落盘卡片保留） ----
+    if (pathname === '/__sync/cancel') {
+      if (method !== 'POST') return next()
+      return readJsonBody(req, res, (payload) => {
+        const jobId = String(payload.jobId || '')
+        const job = syncJobs.get(jobId)
+        if (!job || job.finished) {
+          res.statusCode = 404
+          res.setHeader('Content-Type', 'application/json')
+          return res.end(JSON.stringify({ ok: false, error: 'unknown job', message: '同步任务不存在或已结束' }))
         }
-        log.box({ title: '远端同步完成', level: summary.success ? 'ok' : 'warn', lines })
+        job.cancelRequested = true
         res.statusCode = 200
         res.setHeader('Content-Type', 'application/json')
-        return res.end(JSON.stringify(summary))
-      } catch (e) {
-        // 区分「凭据缺失」与「真正的同步错误」：前者让前端弹登录表单，而非裸抛 ENOENT。
-        const isNoCred =
-          e &&
-          (e.code === 'NO_CREDENTIALS' ||
-            /credentials\.json|credentials 不存在|NO_CREDENTIALS/.test(
-              String(e && e.message),
-            ))
-        res.statusCode = isNoCred ? 200 : 500
+        return res.end(JSON.stringify({ ok: true }))
+      })
+    }
+
+    if (pathname !== '/__sync') return next()
+    if (method !== 'POST') return next()
+
+    return readJsonBody(req, res, (payload) => {
+      // 入参：单卡 cardCode / 集合 cardCodes（二选一，单卡优先）
+      const cardCode =
+        typeof payload.cardCode === 'string' && CARD_CODE_RE.test(payload.cardCode)
+          ? payload.cardCode
+          : undefined
+      let cardCodes
+      if (Array.isArray(payload.cardCodes)) {
+        const set = new Set(
+          payload.cardCodes.filter((c) => typeof c === 'string' && CARD_CODE_RE.test(c))
+        )
+        if (set.size > 500) {
+          res.statusCode = 400
+          res.setHeader('Content-Type', 'application/json')
+          return res.end(
+            JSON.stringify({ ok: false, error: 'too_many', message: '单次下载勾选不能超过 500 张' })
+          )
+        }
+        if (set.size) cardCodes = [...set]
+      }
+      if (!cardCode && !cardCodes && payload.cardCode != null) {
+        // 传了 cardCode 但不合法：明确拒绝，避免静默变成全量
+        res.statusCode = 400
         res.setHeader('Content-Type', 'application/json')
         return res.end(
-          JSON.stringify(
-            isNoCred
-              ? {
-                  error: 'need_credentials',
-                  needCredentials: true,
-                  message: String(e && e.message),
-                }
-              : { error: 'sync failed', message: String(e && e.message) },
-          ),
+          JSON.stringify({ ok: false, error: 'invalid cardCode', message: 'cardCode 含有非法字符' })
         )
       }
+      // 同一时刻只允许一个同步任务（全量同步动辄数分钟，并发会互相打断）
+      if (activeSyncJob()) {
+        res.statusCode = 409
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(
+          JSON.stringify({ ok: false, error: 'sync_in_progress', message: '已有同步任务正在进行，请等待完成或取消' })
+        )
+      }
+
+      syncJobSeq += 1
+      const job = {
+        id: `sj-${Date.now().toString(36)}-${syncJobSeq}`,
+        createdAt: Date.now(),
+        cancelRequested: false,
+        finished: false,
+        progress: { done: 0, total: cardCode ? 1 : cardCodes ? cardCodes.length : 0, currentId: '', currentTitle: '' },
+        result: null,
+      }
+      rememberSyncJob(job)
+
+      // 后台跑同步：请求立即返回，前端轮询 progress
+      ;(async () => {
+        try {
+          const skillPath = resolveSkillPathOrProject(root, SYNC_SCRIPT_REL)
+          const { syncCards } = await import(pathToFileURL(skillPath).href)
+          const summary = await syncCards({
+            cardCode,
+            cardCodes,
+            outRoot: path.join(root, 'src', 'cards'),
+            // 从 server/core 上下文注入 cardImportMeta 实现：消费者工程下 api_batch_sync.mjs 按自身
+            // skills 位置推导的 workspace 会指向错误根，动态 import 找不到 cardImportMeta.js。
+            importMeta: { buildImportMeta, writeImportMeta },
+            // 从 server/core 上下文注入 cardListCache 实现：同 cardImportMeta，消费者工程下按自身 skills
+            // 位置推导的 workspace 会指向错误根，动态 import 找不到 cardListCache.js，导致全量同步时无法
+            // 刷新进程内单例，推送前「存在性闸门」形同虚设。注入后三态都能正确刷新。
+            cardListCache: { refreshCardList, checkPushAllowed, hasCardId },
+            onProgress: (p) => {
+              job.progress = {
+                done: Number(p.done) || 0,
+                total: p.total == null ? job.progress.total : Number(p.total) || 0,
+                currentId: p.currentId || '',
+                currentTitle: p.currentTitle || '',
+              }
+            },
+            shouldCancel: () => job.cancelRequested,
+          })
+          job.result = {
+            success: !!summary.success,
+            cancelled: !!summary.cancelled,
+            synced: summary.synced || [],
+            failed: summary.failed || [],
+            duplicates: summary.duplicates || [],
+          }
+          logSyncSummary(summary, cardCode ? cardCode : cardCodes ? `勾选 ${cardCodes.length} 张` : '(全部)')
+        } catch (e) {
+          if (isNoCredentialsError(e)) {
+            job.result = { needCredentials: true, message: String(e && e.message) }
+          } else {
+            job.result = { success: false, error: String(e && e.message) }
+            log.error('远端同步失败', e)
+          }
+        } finally {
+          job.finished = true
+        }
+      })()
+
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(JSON.stringify({ ok: true, jobId: job.id, total: job.progress.total }))
     })
   }
 }
@@ -190,10 +386,110 @@ export function createPreviewMiddleware({ root }) {
   }
 }
 
+/** finmall-session-navigator 登录脚本（凭据读写 + 页面内登录验证），相对 skills/ */
+const SESSION_LOGIN_REL = 'finmall-session-navigator/scripts/finmall_login.mjs'
+/** finmall-session-navigator 后台会话管理（同步 / 登录验证共用同一 headless Chrome） */
+const SESSION_MANAGER_REL = 'finmall-session-navigator/scripts/session-manager.mjs'
+
+/** 凭据落盘路径：与 finmall_login.mjs 默认路径同址，但经 projectSkillsDir 永远写项目根 skills/，不进 node_modules */
+function credentialsFilePath(root) {
+  return path.join(
+    projectSkillsDir(root),
+    'finmall-session-navigator',
+    '.local',
+    'credentials.json',
+  )
+}
+
+/** 动态加载 finmall-session-navigator 登录脚本（仓库内 / 消费者工程 / 包内快照三态通用） */
+async function loadLoginModule(root) {
+  const p = resolveSkillPathOrProject(root, SESSION_LOGIN_REL)
+  return import(pathToFileURL(p).href)
+}
+
+/** 读取已落盘凭据的登录名；缺失 / 损坏 / 格式不合法一律返回 null（不返回密码哈希） */
+async function readSavedLoginName(root) {
+  try {
+    const { loadCredentials } = await loadLoginModule(root)
+    const creds = await loadCredentials(credentialsFilePath(root))
+    return creds.loginName || null
+  } catch {
+    return null
+  }
+}
+
 /**
- * 预览界面「远程同步」缺凭据时，由前端弹登录表单提交账号+明文密码，
- * 服务端做 MD5 后写入 skills/finmall-session-navigator/.local/credentials.json。
- * 路径与 finmall_login.mjs 的 DEFAULT_CREDENTIALS_PATH 保持一致。
+ * 用给定账号密码做一次真实登录验证（不落盘）。
+ * 与「同步」共用同一后台 headless Chrome 会话池：连上 / 拉起后在 FinMall 同源页面内
+ * 直调登录接口（performLogin），以是否建立会话（sessionCreated）判定凭据是否正确——
+ * 已登录会话不会蒙混过关，因为performLogin 每次都真实提交一遍账号密码。
+ * 只 disconnect 不关闭浏览器：后台 Chrome 以 detached 常驻，供后续同步复用。
+ *
+ * @returns {Promise<{ sessionCreated: boolean, businessFailure: boolean, status?: number }>}
+ */
+async function verifyFinmallLogin(root, loginName, rawPassword) {
+  const {
+    performLogin,
+    tryConnectBrowser,
+    launchChromeDetached,
+    findChromePath,
+    waitForDebugPort,
+    TARGET_URL,
+  } = await loadLoginModule(root)
+  const managerPath = resolveSkillPathOrProject(root, SESSION_MANAGER_REL)
+  const { SYNC_PORT, SYNC_BROWSER_DATA_DIR } = await import(
+    pathToFileURL(managerPath).href,
+  )
+  const md5Hex = createHash('md5')
+    .update(String(rawPassword), 'utf8')
+    .digest('hex')
+
+  let browser = await tryConnectBrowser(SYNC_PORT)
+  if (!browser) {
+    // 端口未启动：拉起后台 headless Chrome（与 ensureFinMallSession 同端口同数据目录）
+    launchChromeDetached(findChromePath(), SYNC_BROWSER_DATA_DIR, SYNC_PORT, TARGET_URL, {
+      headless: true,
+    })
+    const ready = await waitForDebugPort(SYNC_PORT, 20000)
+    if (!ready) {
+      throw new Error(
+        `后台 Chrome 调试端口 ${SYNC_PORT} 未就绪，无法完成登录验证（检查 Chrome 是否安装、端口是否被占用）`,
+      )
+    }
+    for (let i = 0; i < 5 && !browser; i += 1) {
+      browser = await tryConnectBrowser(SYNC_PORT)
+      if (!browser) await new Promise((r) => setTimeout(r, 400))
+    }
+    if (!browser) {
+      throw new Error(`无法连接后台 Chrome 调试端口 ${SYNC_PORT}，无法完成登录验证`)
+    }
+  }
+  try {
+    const context = browser.contexts()[0]
+    let page = context?.pages().find((p) => p.url().includes('finmall.com'))
+    if (!page) {
+      page = context ? await context.newPage() : await browser.newPage()
+      await page
+        .goto(TARGET_URL, { waitUntil: 'domcontentloaded', timeout: 20000 })
+        .catch(() => {})
+    }
+    return await performLogin(page, { loginName, loginPassword: md5Hex })
+  } finally {
+    try {
+      await browser.disconnect()
+    } catch {
+      /* 后台 Chrome 常驻，仅断开连接 */
+    }
+  }
+}
+
+/**
+ * 登录凭据端点（顶栏「远端」的前置门禁）：
+ * - GET  /__login-credentials  查询凭据是否已落盘 → { ok, hasCredentials, loginName }
+ * - POST /__login-credentials  提交账号 + 明文密码：先做一次真实登录验证，通过才落盘
+ *   （MD5，不落明文）；账号 / 密码错误返回 ok:false 且不落盘，由前端保留弹窗让用户重填。
+ *
+ * 旧行为（不验证直接写盘）会把错误密码持久化，且重跑也不再重问——故改为「验证通过才落盘」。
  *
  * @param {{ root: string }} opts
  * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, next: Function) => void}
@@ -202,7 +498,30 @@ export function createLoginCredentialsMiddleware({ root }) {
   return function loginCredentialsMiddleware(req, res, next) {
     const pathname = decodeURIComponent((req.url || '').split('?')[0])
     if (pathname !== '/__login-credentials') return next()
-    if ((req.method || 'GET').toUpperCase() !== 'POST') return next()
+    const method = (req.method || 'GET').toUpperCase()
+    if (method !== 'GET' && method !== 'POST') return next()
+    res.setHeader('Content-Type', 'application/json')
+
+    if (method === 'GET') {
+      readSavedLoginName(root)
+        .then((loginName) => {
+          res.statusCode = 200
+          res.end(
+            JSON.stringify({
+              ok: true,
+              hasCredentials: !!loginName,
+              loginName: loginName || '',
+            }),
+          )
+        })
+        .catch((e) => {
+          res.statusCode = 500
+          res.end(
+            JSON.stringify({ error: 'status failed', message: String(e && e.message) }),
+          )
+        })
+      return
+    }
 
     let body = ''
     req.setEncoding('utf8')
@@ -216,7 +535,6 @@ export function createLoginCredentialsMiddleware({ root }) {
         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 loginName =
@@ -225,7 +543,6 @@ export function createLoginCredentialsMiddleware({ root }) {
         typeof payload.loginPassword === 'string' ? payload.loginPassword : ''
       if (!loginName || !rawPassword) {
         res.statusCode = 400
-        res.setHeader('Content-Type', 'application/json')
         return res.end(
           JSON.stringify({
             error: 'missing_fields',
@@ -234,28 +551,41 @@ export function createLoginCredentialsMiddleware({ root }) {
         )
       }
       try {
-        const credentialsPath = path.join(
-          root,
-          'skills',
-          'finmall-session-navigator',
-          '.local',
-          'credentials.json',
-        )
-        const credentials = {
-          loginName,
-          loginPassword: createHash('md5').update(rawPassword, 'utf8').digest('hex'),
+        // 1) 先做一次真实登录验证，通过才落盘
+        const result = await verifyFinmallLogin(root, loginName, rawPassword)
+        if (result.sessionCreated) {
+          const { saveCredentials } = await loadLoginModule(root)
+          await saveCredentials(loginName, rawPassword, credentialsFilePath(root))
+          log.ok('登录验证通过，已保存登录凭据', { loginName })
+          res.statusCode = 200
+          return res.end(JSON.stringify({ ok: true, verified: true, loginName }))
+        }
+        if (result.businessFailure) {
+          // 账号 / 密码错误：不落盘，前端保留弹窗让用户重新输入
+          log.warn('登录验证未通过：账号或密码错误', { loginName })
+          res.statusCode = 200
+          return res.end(
+            JSON.stringify({
+              ok: false,
+              error: 'invalid_credentials',
+              message: '账号或密码错误，登录验证未通过（凭据未保存）',
+            }),
+          )
         }
-        await mkdir(path.dirname(credentialsPath), { recursive: true })
-        await writeFile(credentialsPath, JSON.stringify(credentials, null, 2), 'utf8')
-        log.ok('已保存登录凭据', { loginName })
         res.statusCode = 200
-        res.setHeader('Content-Type', 'application/json')
-        return res.end(JSON.stringify({ ok: true }))
+        return res.end(
+          JSON.stringify({
+            ok: false,
+            error: 'verify_failed',
+            message: `登录验证未通过（HTTP ${result.status || '未知'}），凭据未保存`,
+          }),
+        )
       } catch (e) {
-        log.error('保存登录凭据失败', e)
+        log.error('登录验证失败', e)
         res.statusCode = 500
-        res.setHeader('Content-Type', 'application/json')
-        return res.end(JSON.stringify({ error: 'save failed', message: String(e && e.message) }))
+        return res.end(
+          JSON.stringify({ error: 'verify_failed', message: String(e && e.message) }),
+        )
       }
     })
   }

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

@@ -15,7 +15,9 @@ import { log } from './logger.js'
  *      有实质变化经 SSE 推 code-bridge-changed { id }（内容走 GET 拉取，避免大 payload）；
  *   3) 前端 GET /__code-bridge/<id> 取回代码写回 CodeJar（updateCode 不触发 onUpdate，断回声环）；
  *   4) 会话结束 = 前端 DELETE（面板关闭 / 手动断开 / 组件卸载）或心跳 TTL 兜底
- *      （前端 5s 心跳，20s 无心跳即删文件，覆盖关浏览器 / 崩溃）；启动时清扫 >24h 残留。
+ *      （前端 5s 心跳，60s 无心跳即删文件，覆盖关浏览器 / 崩溃 / 标签页冻结）；启动时清扫 >24h 残留。
+ *      心跳由独立 Web Worker 发送，不受编辑器标签切后台后的 page-freeze / 定时器节流影响，
+ *      故"在 VSCode 里编辑、没碰编辑器"不会再把桥接掐断（旧 20s TTL 在后台冻结下几乎必断）。
  *
  * 「关闭」语义说明：VSCode CLI 把文件交给已运行实例后立即返回，标签页关闭事件不装扩展
  * 拿不到，故清除时机取「会话结束 + TTL」，而非 VSCode 关标签瞬间。
@@ -27,7 +29,7 @@ import { log } from './logger.js'
 
 export const BRIDGE_DIR_NAME = 'cardbuddy-code-bridge'
 export const SESSION_ID_RE = /^[a-f0-9]{8}$/
-export const HEARTBEAT_TTL_MS = 20000
+export const HEARTBEAT_TTL_MS = 60000
 const REAP_INTERVAL_MS = 5000
 const WATCH_DEBOUNCE_MS = 150
 const STALE_FILE_MS = 24 * 60 * 60 * 1000

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

@@ -13,6 +13,7 @@
 import { createSyncMiddleware, createPreviewMiddleware, createLoginCredentialsMiddleware } from './cardSync.js'
 import { createPublishMiddleware } from './cardPublish.js'
 import { createCardVersionMiddleware } from './cardVersion.js'
+import { createCardHistoryMiddleware } from './cardHistoryRemote.js'
 import { createSliceUploadMiddleware } from './sliceUpload.js'
 import { createCardFilesMiddleware, refreshCardList } from './cardFiles.js'
 import { createSaveMiddleware } from './cardSave.js'
@@ -46,6 +47,7 @@ export {
   createLoginCredentialsMiddleware,
   createPublishMiddleware,
   createCardVersionMiddleware,
+  createCardHistoryMiddleware,
   createSliceUploadMiddleware,
   createCardFilesMiddleware,
   createSaveMiddleware,
@@ -98,6 +100,9 @@ export function mountCoreMiddlewares(app, { root, viteServer = null, upstream =
   // 卡片来源 tab 的「远端最新版本」查询（只读）：GET /__card-version/:id 取 IDC10004 的 maxVersion，
   // 复用 finmall-card-sync 的 fetchCardLatestVersion，与发布/同步/保存共用同一后台 FinMall 会话。
   app.use(createCardVersionMiddleware({ root }))
+  // 「卡片历史记录」tab 的远端版本时间线（只读）：GET /__card-history/:cardCode 取 IDC10013 的
+  // schemaValueList（新→旧，含预览图 / 变更标签），复用 finmall-card-sync 的 fetchCardHistory。
+  app.use(createCardHistoryMiddleware({ root }))
   // 切图上传（顶栏「远端 → 切图上传」）：把当前卡引用的 src/slices 切图传到 FinMall 图片库，
   // 写 src/slices/manifest.json 映射并把卡片里的 /slices/ 引用改写为 @filestore/ 线上地址。
   // 仅在用户点击时触发，没有任何自动上传路径。