cardbuddy 0.19.3 → 0.20.0

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

@@ -92,9 +92,10 @@ function withTimeout(promise, ms, label) {
 }
 
 // 服务端判定会话/权限失效并应「重新进入」的特征集合。命中后由 finmallPostWithHeal
-// 自动清 session 重登再试一次——覆盖会话超时（BLEC0006）、token 失效，以及
-// 本次遇到的「您当前角色菜单权限发生变化，请重新进入」这类权限态异常。
-const SESSION_INVALID_RE = /BLEC0006|会话超时|会话过期|登录超时|未登录|登录失效|登录已失效|请重新登录|invalid token|token|角色菜单权限发生变化|权限发生变化|重新进入|请重新进入/i;
+// 自动清 session 重登再试一次——覆盖会话超时（BLEC0006）、token 失效、
+// 「您当前角色菜单权限发生变化，请重新进入」这类权限态异常，以及前端页面会话键丢失
+// （localStorage._sessionId 为空，如后台 Chrome 被清理/重启后）：本地凭证仍在即可自愈。
+const SESSION_INVALID_RE = /BLEC0006|会话超时|会话过期|登录超时|未登录|登录失效|登录已失效|请重新登录|invalid token|token|角色菜单权限发生变化|权限发生变化|重新进入|请重新进入|缺少会话凭据/i;
 
 /**
  * 带自愈的 FinMall 接口调用：正常请求，若命中会话/权限失效特征则清 session 重登后重试一次。
@@ -124,6 +125,7 @@ async function finmallPostWithHeal(page, urlPath, requestBody, transCode = urlPa
  *
  * @param {object} opts
  * @param {string} [opts.cardCode]     仅同步该英文卡 id（用列表接口 searchValue 定位）
+ * @param {string[]} [opts.cardCodes]  仅同步这些英文卡 id（集合筛选；与 cardCode 互斥，cardCode 优先）
  * @param {number} [opts.startPage=1]
  * @param {number} [opts.startIndex=0]
  * @param {number} [opts.pageSize=24]
@@ -132,7 +134,11 @@ async function finmallPostWithHeal(page, urlPath, requestBody, transCode = urlPa
  * @param {string} [opts.workspaceId]
  * @param {string} [opts.cdpUrl]       已废弃：会话现在由 ensureFinMallSession 在专用后台端口自动管理
  * @param {string} [opts.outRoot]      输出根目录（默认 workspace/src/cards）
- * @returns {Promise<{success:boolean, synced:Array, failed:Array, duplicates:Array}>}
+ * @param {(p: {done:number,total:number|null,currentId:string,currentTitle:string}) => void} [opts.onProgress]
+ *                                     每张卡处理完毕后的进度回调（失败也回调），供前端进度条消费
+ * @param {() => boolean} [opts.shouldCancel] 取消探针：返回 true 时在下一条卡片前中止，
+ *                                     已落盘的卡片保留，summary 标记 cancelled
+ * @returns {Promise<{success:boolean, synced:Array, failed:Array, duplicates:Array, cancelled?:boolean}>}
  */
 export async function syncCards(opts = {}) {
   // 非注入形态（纯 CLI）用 cwd 作为项目根，跨「仓库内 / 消费者工程」一致；server 中间件始终注入绝对 outRoot。
@@ -152,6 +158,19 @@ export async function syncCards(opts = {}) {
   const workspaceId = opts.workspaceId || finmallConfig.workspaceId;
   // 单卡筛选：传 cardCode 时仅同步该卡
   const cardCodeFilter = opts.cardCode || '';
+  // 集合筛选：cardCodes 非空时仅同步集合内卡片（与单卡筛选互斥，单卡优先）。
+  // 入口处已做格式校验，这里再按 normalizeCard 同源正则兜底，非法项静默剔除。
+  const cardCodeSet =
+    !cardCodeFilter && Array.isArray(opts.cardCodes) && opts.cardCodes.length
+      ? new Set(
+          opts.cardCodes.filter((c) => typeof c === 'string' && /^[A-Za-z0-9_-]+$/.test(c))
+        )
+      : null;
+  // 进度回调与取消探针（前端「查看全部 → 下载选中/全部下载」的进度弹窗消费）
+  const onProgress = typeof opts.onProgress === 'function' ? opts.onProgress : null;
+  const shouldCancel = typeof opts.shouldCancel === 'function' ? opts.shouldCancel : () => false;
+  // 预期总张数：单卡=1；集合=集合大小；全量=0（未知，边拉边算）
+  const expectedTotal = cardCodeFilter ? 1 : cardCodeSet ? cardCodeSet.size : 0;
 
   // 自动确保后台 FinMall 会话：未启动/缺失则拉起无界面 Chrome 并登录，无需手动触发。
   const session = await ensureFinMallSession();
@@ -170,14 +189,17 @@ export async function syncCards(opts = {}) {
     const totalPages = Number(firstList.totalPages || Math.ceil(Number(firstList.totalNums || 0) / pageSize) || startPage);
 
   let done = false;
+  let cancelled = false;
   const allCards = [];
-  for (let pageNo = startPage; pageNo <= totalPages && !done; pageNo++) {
+  for (let pageNo = startPage; pageNo <= totalPages && !done && !cancelled; pageNo++) {
     const list = pageNo === startPage ? firstList : await fetchCardList(page, { pageNo, pageSize, appId, workspaceId, searchValue: cardCodeFilter });
     const cards = list.cardList || [];
     for (const c of cards) allCards.push(c);
     const begin = pageNo === startPage ? startIndex : 0;
-      for (let index = begin; index < cards.length && !done; index++) {
+      for (let index = begin; index < cards.length && !done && !cancelled; index++) {
         if (summary.synced.length + summary.failed.length >= maxCards) break;
+        // 取消探针：用户点「取消」后在下一条卡片前退出（已落盘的卡片保留）
+        if (shouldCancel()) { cancelled = true; break; }
         // normalizeCard 会对非法 code 抛错；单条异常不应中断整批同步。
         let card;
         try {
@@ -189,6 +211,8 @@ export async function syncCards(opts = {}) {
           continue;
         }
         if (cardCodeFilter && card.id !== cardCodeFilter) continue;
+        // 集合筛选：不在勾选集合内的卡片跳过（仍进 allCards 供缓存整体刷新）
+        if (cardCodeSet && !cardCodeSet.has(card.id)) continue;
         log.info('同步中', { page: `${pageNo}/${totalPages}`, index, id: card.id, title: card.title });
         try {
           const files = await syncCard(page, card, { outRoot, appId, workspaceId, summary, schemaHashes, importMeta });
@@ -203,12 +227,30 @@ export async function syncCards(opts = {}) {
           summary.failed.push({ page: pageNo, index, id: card.id, title: card.title, error: error.message });
           log.error('同步失败', { id: card.id, title: card.title, error: error.message });
         }
+        // 进度回调：失败也回调（done 计数含失败），前端据此更新「已完成 X / 全部 Y」
+        if (onProgress) {
+          try {
+            onProgress({
+              done: summary.synced.length + summary.failed.length,
+              total: expectedTotal || null,
+              currentId: card.id,
+              currentTitle: card.title || '',
+            });
+          } catch { /* 前端回调异常不阻断同步 */ }
+        }
         if (cardCodeFilter) done = true;
       }
       if (summary.synced.length + summary.failed.length >= maxCards) break;
     }
+    // 取消：已落盘的卡片保留，summary 显式标记，由调用方（dev server 任务）转成用户提示
+    if (cancelled) {
+      summary.cancelled = true;
+      summary.success = false;
+      log.warn('同步已被用户取消', { done: summary.synced.length + summary.failed.length });
+    }
     // 全量同步（无 cardCode 过滤）时整体刷新卡片列表缓存，供推送前「存在性闸门」使用；
-    // 单卡同步只增量合并，不整体替换，避免清空其余卡片。缓存未就绪则跳过（不影响同步）。
+    // 单卡同步只增量合并，不整体替换，避免清空其余卡片。集合筛选（cardCodes）会翻遍
+    // 全部分页，allCards 即完整列表，整体刷新同样准确。缓存未就绪则跳过（不影响同步）。
     try {
       const cache = await getCardListCache();
       if (cache) cache.refreshCardList(allCards, { full: !cardCodeFilter });
@@ -222,6 +264,66 @@ export async function syncCards(opts = {}) {
   return summary;
 }
 
+/**
+ * 拉取远端完整卡片列表（IDC10001 分页全量），供编辑器「查看全部」网格浏览。
+ * 只读、不落盘；与 syncCards 共用同一后台 FinMall 会话（ensureFinMallSession 自动保活）。
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.pageSize=50]    列表分页大小
+ * @param {number} [opts.maxPages=400]   分页上限保护（50×400=2 万张，防服务端异常死循环）
+ * @param {string} [opts.appId]
+ * @param {string} [opts.workspaceId]
+ * @returns {Promise<Array<{id:string,title:string,cardId:string|number,coverUrl:string}>>}
+ *   id=英文卡 code（本地目录名同源）；coverUrl 为 FinMall 图片库绝对地址（可能为空串）
+ */
+export async function listRemoteCards(opts = {}) {
+  const appId = opts.appId || finmallConfig.appId;
+  const workspaceId = opts.workspaceId || finmallConfig.workspaceId;
+  const pageSize = Number(opts.pageSize || 50);
+  const maxPages = Number(opts.maxPages || 400);
+
+  // 自动确保后台 FinMall 会话：未启动/缺失则拉起无界面 Chrome 并登录，无需手动触发。
+  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 out = [];
+    const seen = new Set();
+    let pageNo = 1;
+    let totalPages = 1;
+    do {
+      const list = await fetchCardList(page, { pageNo, pageSize, appId, workspaceId });
+      totalPages = Number(list.totalPages || Math.ceil(Number(list.totalNums || 0) / pageSize) || 1);
+      for (const raw of list.cardList || []) {
+        // 非法 code（normalizeCard 抛错）的单条跳过，不阻断整表拉取
+        let card;
+        try {
+          card = normalizeCard(raw);
+        } catch {
+          continue;
+        }
+        if (seen.has(card.id)) continue;
+        seen.add(card.id);
+        out.push({
+          id: card.id,
+          title: card.title || '',
+          cardId: card.cardId,
+          coverUrl: card.coverUrl || '',
+        });
+      }
+      pageNo += 1;
+    } while (pageNo <= totalPages && pageNo <= maxPages);
+    return out;
+  } finally {
+    // 仅断开连接，不关闭后台 Chrome（与 syncCards 一致，供后续同步/推送复用会话）
+    try { await browser.disconnect() } catch { /* ignore */ }
+  }
+}
+
 /**
  * 把一张卡片的最新 schema 写回 FinMall（线上编辑器「保存」接口 IDC10010.do）。
  * 与 syncCards 共用同一套已登录浏览器会话与带自愈的 finmallPost，
@@ -518,6 +620,251 @@ export async function fetchCardLatestVersion(cardId) {
   }
 }
 
+/**
+ * 取远端「卡片历史版本时间线」：IDC10013 按 cardId 分页返回 schemaValueList（新→旧）。
+ * 供编辑器「卡片历史记录」tab 渲染 git 式时间线。只读；与 fetchCardLatestVersion 共用
+ * 同一后台 FinMall 会话（ensureFinMallSession + finmallPostWithHeal）。
+ *
+ * schema 全量（每条数 KB~上百 KB）不跨端透传：服务端就地解析为轻量摘要 + 相邻版本 diff
+ * 标签，响应体积与 schema 大小解耦，UI 拿到的就是可直接渲染的字段。
+ *
+ * @param {string|number} cardId
+ * @param {{ pageNo?: number, pageSize?: number }} [opts]
+ * @returns {Promise<{ list: Array<object>, totalNums: number, totalPages: number }>}
+ */
+// —— 版本 schema 进程内缓存（(cardId, versionId) → schema）——
+// IDC10013 单页 100 条实测 ~6.5MB / 4.2s，而「加载此版本」只需要其中一条。
+// fetchCardHistory（时间线列表）本来就会解析页内全部 schema 算 diff，顺手按
+// (cardId, versionId) 缓存；fetchCardVersionSchema 命中缓存时零网络请求，
+// 把点击到加载的等待从 ~7s 降到毫秒级。未命中仍走原分页翻找兜底。
+const SCHEMA_CACHE_TTL_MS = Number(process.env.FINMALL_SCHEMA_CACHE_TTL_MS || 300000)
+const SCHEMA_CACHE_MAX = 500
+const _versionSchemaCache = new Map() // `${cardId}::${versionId}` → { schema, createTime, at }
+
+function cacheVersionSchema(cardId, versionId, schema, createTime) {
+  const key = `${cardId}::${versionId}`
+  _versionSchemaCache.set(key, { schema, createTime: createTime || '', at: Date.now() })
+  if (_versionSchemaCache.size > SCHEMA_CACHE_MAX) {
+    // 惰性容量控制：淘汰最早写入的一批（Map 保序）
+    let excess = _versionSchemaCache.size - SCHEMA_CACHE_MAX
+    for (const k of _versionSchemaCache.keys()) {
+      _versionSchemaCache.delete(k)
+      if (--excess <= 0) break
+    }
+  }
+}
+
+function getCachedVersionSchema(cardId, versionId) {
+  const key = `${cardId}::${versionId}`
+  const hit = _versionSchemaCache.get(key)
+  if (!hit) return null
+  if (Date.now() - hit.at > SCHEMA_CACHE_TTL_MS) {
+    _versionSchemaCache.delete(key)
+    return null
+  }
+  return hit
+}
+
+export async function fetchCardHistory(cardId, { pageNo = 1, pageSize = 30 } = {}) {
+  if (cardId == null) {
+    throw new Error('缺少 cardId，无法查询远端历史（IDC10013.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/IDC10013.do?sassAppId=${appId}&sassWorkspaceId=${workspaceId}`,
+      { cardId: id, pageNo, pageSize, sassAppId: appId, sassWorkspaceId: workspaceId },
+      'IDC10013.do',
+    )
+    const rawList = Array.isArray(resp && resp.schemaValueList) ? resp.schemaValueList : []
+    // 顺带填充版本 schema 缓存：供「加载此版本」零网络命中（同进程内，list 已解析过一份）
+    for (const raw of rawList) {
+      try {
+        const parsed = typeof raw.schema === 'string' ? JSON.parse(raw.schema) : raw.schema
+        if (parsed && typeof parsed === 'object') {
+          cacheVersionSchema(id, String(raw.id != null ? raw.id : ''), parsed, raw.createTime)
+        }
+      } catch {
+        /* 单条 schema 损坏不阻断时间线，缓存自然跳过 */
+      }
+    }
+    // 接口顺序即新→旧，时间线按此顺序直接渲染（最新在上，同 git log）
+    const list = rawList.map((raw) => summarizeHistoryItem(raw))
+    // 相邻 diff：第 i 条相对第 i+1 条（更旧的一个版本）算变更标签
+    for (let i = 0; i < list.length; i += 1) {
+      const older = list[i + 1]
+      list[i].tags = diffHistoryTags(list[i].summary, older ? older.summary : null)
+    }
+    log.info('查询远端卡片历史', { cardId: id, pageNo, count: list.length, totalNums: resp && resp.totalNums })
+    return {
+      list,
+      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 */ }
+  }
+}
+
+/**
+ * 按版本记录 id 取该历史版本的完整 schema（「加载此版本到编辑器」的数据源）。
+ * IDC10013 没有「按 id 单查」能力，只能分页翻找：pageSize 100 逐页扫到 totalPages，命中即返回。
+ * schema 为原始 JSON（顶层 version/pageId/name/desc + view.components 组件树），与 syncCard 落盘同构。
+ *
+ * @param {string|number} cardId
+ * @param {string|number} versionId 历史记录 id（IDC10013 schemaValueList[].id）
+ * @returns {Promise<{ schema: object, record: { id: string, createTime: string } }>}
+ */
+export async function fetchCardVersionSchema(cardId, versionId) {
+  if (cardId == null) {
+    throw new Error('缺少 cardId，无法查询远端历史版本（IDC10013.do 需要 cardId）。')
+  }
+  const want = String(versionId == null ? '' : versionId)
+  if (!want) {
+    throw new Error('缺少版本记录 id，无法定位远端历史版本。')
+  }
+  const id = String(cardId)
+  // 缓存优先：时间线列表（fetchCardHistory）已按 (cardId, versionId) 填充过页内 schema，
+  // 命中即零网络请求返回（毫秒级）；未命中才走下面的分页翻找。
+  const cached = getCachedVersionSchema(id, want)
+  if (cached) {
+    log.info('命中版本 schema 缓存（零网络）', { cardId: id, versionId: want })
+    return { schema: cached.schema, record: { id: want, createTime: cached.createTime || '' } }
+  }
+  const appId = finmallConfig.appId
+  const workspaceId = finmallConfig.workspaceId
+  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 url = `/ubomp-web/IDC10013.do?sassAppId=${appId}&sassWorkspaceId=${workspaceId}`
+    let pageNo = 1
+    let totalPages = 1
+    do {
+      const resp = await finmallPostWithHeal(
+        page,
+        url,
+        { cardId: id, pageNo, pageSize: 100, sassAppId: appId, sassWorkspaceId: workspaceId },
+        'IDC10013.do',
+      )
+      const rawList = Array.isArray(resp && resp.schemaValueList) ? resp.schemaValueList : []
+      const hit = rawList.find((raw) => String(raw && raw.id != null ? raw.id : '') === want)
+      if (hit) {
+        const schema = typeof hit.schema === 'string' ? JSON.parse(hit.schema) : hit.schema
+        if (!schema || typeof schema !== 'object') {
+          throw new Error(`远端版本记录 #${want} 的 schema 为空或损坏，无法加载。`)
+        }
+        log.info('定位远端历史版本', { cardId: id, versionId: want, pageNo })
+        return {
+          schema,
+          record: {
+            id: String(hit.id != null ? hit.id : ''),
+            createTime: hit.createTime || '',
+          },
+        }
+      }
+      totalPages = Number(resp && resp.totalPages != null ? resp.totalPages : 1) || 1
+      pageNo += 1
+    } while (pageNo <= totalPages)
+    throw new Error(`远端历史中找不到版本记录 #${want}（cardId=${id}，共 ${totalPages} 页）。`)
+  } finally {
+    try { await browser.disconnect() } catch { /* ignore */ }
+  }
+}
+function summarizeHistoryItem(raw) {
+  let name = ''
+  let desc = ''
+  let version = ''
+  let platform = ''
+  let width = ''
+  let components = []
+  try {
+    const schema = typeof raw.schema === 'string' ? JSON.parse(raw.schema) : raw.schema || {}
+    name = schema.name || ''
+    desc = schema.desc || ''
+    version = schema.version || ''
+    platform = schema.platform || ''
+    width = (schema.view && schema.view.width) || ''
+    // 组件树挂在 view.components 下（schema 顶层只有 version/pageId/name/desc/platform/dictionary/view）
+    components = (schema.view && Array.isArray(schema.view.components)) ? schema.view.components : []
+  } catch {
+    /* 单条 schema 损坏不阻断时间线渲染，摘要退化为空 */
+  }
+  return {
+    id: String(raw.id != null ? raw.id : ''),
+    createTime: raw.createTime || '',
+    updateTime: raw.updateTime || '',
+    bizChannel: raw.bizChannel || '',
+    // @filestore/x → /minio/x（同源相对路径，经 8787 assetProxy 回源；与 adapter.js 约定一致）
+    screenshotPath: filestorePathToLocal(raw.screenshotUrl),
+    // compKeys / eventCount 仅服务端相邻 diff 消费，体积恒定（数十字节/条）
+    summary: {
+      name,
+      desc,
+      version,
+      platform,
+      width,
+      componentCount: components.length,
+      compKeys: components.map(compKey),
+      eventCount: countEvents(components),
+    },
+  }
+}
+
+/** 组件 diff 标识：componentId::className（同卡内 componentId 稳定，跨版本可比） */
+function compKey(c) {
+  return `${c && c.componentId != null ? c.componentId : ''}::${c && c.className != null ? c.className : ''}`
+}
+
+/** 交互事件总数：各组 eventactions 条目数之和（事件代码增删的粗粒度信号） */
+function countEvents(comps) {
+  return comps.reduce((n, c) => n + (Array.isArray(c && c.eventactions) ? c.eventactions.length : 0), 0)
+}
+
+/** @filestore/ 前缀切为同源 /minio/ 相对路径；已是绝对地址则原样返回 */
+function filestorePathToLocal(value) {
+  if (!value || typeof value !== 'string') return ''
+  if (value.startsWith('http://') || value.startsWith('https://')) return value
+  if (value.startsWith('@filestore/')) return '/minio/' + value.slice('@filestore/'.length)
+  if (value.startsWith('/')) return value
+  return filestoreToUrl(value)
+}
+
+/**
+ * 相邻版本 diff 摘要：相对更旧版本算变更标签（组件增减 / 交互事件变化 / 重命名 /
+ * 描述变更 / 画布宽度变化 / 结构未变）。tags 为字符串数组，前端直接渲染徽标。
+ */
+function diffHistoryTags(cur, older) {
+  if (!older) return ['初始版本']
+  const curIds = new Set(cur.compKeys)
+  const oldIds = new Set(older.compKeys)
+  let added = 0
+  let removed = 0
+  for (const k of curIds) if (!oldIds.has(k)) added += 1
+  for (const k of oldIds) if (!curIds.has(k)) removed += 1
+  const tags = []
+  if (added > 0) tags.push(`新增 ${added} 个组件`)
+  if (removed > 0) tags.push(`移除 ${removed} 个组件`)
+  if (cur.eventCount !== older.eventCount) tags.push(`交互事件 ${older.eventCount} → ${cur.eventCount}`)
+  if (cur.name !== older.name) tags.push('重命名')
+  if (cur.desc !== older.desc) tags.push('描述变更')
+  if (cur.width !== older.width) tags.push(`画布宽度 ${older.width} → ${cur.width}`)
+  if (tags.length === 0) tags.push('结构未变')
+  return tags
+}
+
 // —— 保存落库校验辅助 ——
 
 /** 稳定序列化：对象键排序、带 id/key/className/name 的数组元素按该键排序，避免服务端字段重排导致指纹误判。 */

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

@@ -625,7 +625,8 @@ export async function performLogin(page, credentials) {
  *
  * @param {object} [options]
  * @param {string} [options.credentialsPath]  凭据文件路径
- * @param {number} [options.maxAttempts=3]    最大重试次数
+ * @param {number} [options.maxAttempts=3]    单份凭据的最大登录重试次数
+ * @param {number} [options.maxCredentialPrompts=3] 账号/密码错误时允许重新输入凭据的次数上限（仅交互终端生效）
  * @param {number} [options.retryDelayMs=1000] 重试间隔
  * @param {number} [options.debugPort=9222]   Chrome 调试端口
  * @param {boolean} [options.closeBrowser=false] 完成后是否关闭浏览器
@@ -635,6 +636,7 @@ export async function runFinmallLogin(options = {}) {
   const {
     credentialsPath = DEFAULT_CREDENTIALS_PATH,
     maxAttempts = 3,
+    maxCredentialPrompts = 3,
     retryDelayMs = 1000,
     debugPort = DEBUG_PORT,
     closeBrowser = false,
@@ -729,9 +731,12 @@ export async function runFinmallLogin(options = {}) {
       };
     }
 
-    // 登录流程（带重试）
+    // 登录流程（带重试；账号/密码错误时，交互终端下请用户重新输入）
     const failures = [];
-    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    let credentialPrompts = 0;
+    let attempt = 0;
+    while (attempt < maxAttempts) {
+      attempt += 1;
       try {
         const dismissed = await clearTimeoutPrompts(page);
         state = await waitForPageDecision(page);
@@ -779,6 +784,29 @@ export async function runFinmallLogin(options = {}) {
               };
             }
             failures.push({ attempt, reason: "登录后未看到卡片数据列表" });
+          } else if (
+            loginResult.businessFailure &&
+            process.stdout.isTTY &&
+            credentialPrompts < maxCredentialPrompts
+          ) {
+            // 账号/密码错误：交互终端下请用户重新输入，覆盖本地凭据后重来，
+            // 不消耗固定的重试次数（避免一次性输错就把次数吃光）。
+            credentialPrompts += 1;
+            console.error(
+              `✖ 登录失败：账号或密码错误。请重新输入 FinMall 凭据（${credentialPrompts}/${maxCredentialPrompts}）`,
+            );
+            try {
+              credentials = await promptAndSaveCredentials(credentialsPath);
+              attempt -= 1; // 回退本次计数，下一轮用新凭据重试
+              continue;
+            } catch (promptError) {
+              failures.push({
+                attempt,
+                reason:
+                  "重新输入凭据失败：" +
+                  String(promptError?.message || promptError).slice(0, 200),
+              });
+            }
           } else {
             failures.push({
               attempt,
@@ -807,11 +835,15 @@ export async function runFinmallLogin(options = {}) {
       }
     }
 
+    const exhaustedReason =
+      credentialPrompts >= maxCredentialPrompts && credentialPrompts > 0
+        ? `已连续 ${credentialPrompts} 次重新输入凭据仍登录失败，请核对账号密码或稍后重试`
+        : "登录重试多次仍失败，服务端可能异常";
     return {
       success: false,
-      attempts: maxAttempts,
+      attempts: attempt,
       terminal: true,
-      reason: "登录重试 3 次仍失败，服务端可能异常",
+      reason: exhaustedReason,
       failures,
     };
   } finally {

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

@@ -28,6 +28,13 @@ for (const key of ["NO_PROXY", "no_proxy"]) {
   process.env[key] = cur && cur.length ? `${cur},${extra}` : extra;
 }
 
+// 进程内会话缓存：runFinmallLogin 热路径固定消耗导航 + networkidle + sleep(2000)（实测 ~2.6s），
+// 而同步/保存/历史查询等高频只读操作都会经过 ensureFinMallSession。TTL 内且 CDP 仍连通时
+// 直接复用，跳过重复登录校验；服务端会话真过期时由 finmallPostWithHeal 的 SESSION_INVALID
+// 自愈（清 session 重登重试）兜底，故此处缓存不削弱正确性。
+const SESSION_CACHE_TTL_MS = Number(process.env.FINMALL_SESSION_CACHE_TTL_MS || 60000);
+let _sessionCache = null; // { browser, login, at }
+
 /**
  * 确保存在一个已登录的 FinMall 后台浏览器会话（无界面 headless，端口 SYNC_PORT）。
  *
@@ -36,6 +43,9 @@ for (const key of ["NO_PROXY", "no_proxy"]) {
  *   以 headless 模式启动一个独立（detached）Chrome，并用保存的凭据自动登录。
  * - 若 SYNC_PORT 已启动（含跨 dev server 重启复用的上一实例）：直接连上并复用，
  *   仅在 _sessionId 缺失时由 runFinmallLogin 自动登录。
+ * - 进程内热路径：距上次成功 ensure 不足 TTL 且 CDP 仍连通（isConnected）时直接返回缓存，
+ *   省去重复导航与固定等待；调用方 finally 的 browser.disconnect() 会令 isConnected()
+ *   为 false，缓存随之作废走完整流程，与原先行为一致。
  *
  * 注意：runFinmallLogin 只校验 _sessionId 是否存在，无法发现「服务端会话已过期」
  * （IDC10001 列表接口不鉴权，会骗过它）。最终的服务端过期由 syncCards 以需鉴权的
@@ -51,6 +61,19 @@ for (const key of ["NO_PROXY", "no_proxy"]) {
  * @returns {Promise<{ browser: import('playwright').Browser, login: object }>}
  */
 export async function ensureFinMallSession({ debugPort = SYNC_PORT, headless = true } = {}) {
+  // 热路径：进程内缓存未过期且 CDP 仍连通 → 直接复用（跳过 runFinmallLogin 的
+  // 导航 + networkidle + sleep(2000)，实测可从 ~2.6s 降到毫秒级）。
+  if (_sessionCache && Date.now() - _sessionCache.at < SESSION_CACHE_TTL_MS) {
+    try {
+      if (_sessionCache.browser.isConnected()) {
+        return _sessionCache;
+      }
+    } catch {
+      /* isConnected 抛错视作失效，走完整流程 */
+    }
+    _sessionCache = null;
+  }
+
   let browser = await tryConnectBrowser(debugPort);
 
   if (!browser) {
@@ -90,7 +113,8 @@ export async function ensureFinMallSession({ debugPort = SYNC_PORT, headless = t
     throw new Error(`后台自动登录 FinMall 失败：${reason}${captchaNote}`);
   }
 
-  return { browser, login };
+  _sessionCache = { browser, login, at: Date.now() };
+  return _sessionCache;
 }
 
 export { SYNC_PORT, SYNC_BROWSER_DATA_DIR };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cardbuddy",
-  "version": "0.19.3",
+  "version": "0.20.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": {