cardbuddy 0.9.1 → 0.11.0

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

@@ -0,0 +1,699 @@
+#!/usr/bin/env node
+/**
+ * slice_upload —— 切图上传（slices_convention.md 的「③ 远程同步」阶段实现）。
+ *
+ * 把 `src/slices/` 下被卡片引用的切图上传到 FinMall 图片库（`CC0000.do`，multipart：
+ * `fileName` + `file`），拿到线上地址（形如 `@filestore/dzqd-download/<ts>_<name>.png`），
+ * 然后做两件事：
+ *   1. 写「本地文件 ↔ 线上地址」映射：`src/slices/manifest.json`；
+ *   2. 把卡片 `schema.json` / `data.json` 里的 `"/slices/<name>"` 引用改写为该线上地址
+ *      （运行时 `adapter.doReplaceUrl` 再把 `@filestore/x` 解析成 `/minio/x`，预览链路无需改动）。
+ *
+ * 鉴权与会话复用与 api_batch_sync.mjs 完全一致：ensureFinMallSession 拉起/复用后台无界面
+ * Chrome，token（localStorage `_sessionId`）只在页面上下文内读取并直接用于请求——
+ * **绝不回传 Node 侧、不打印、不落盘**（见 shared/auth-model.md §1.5）。
+ * 命中会话/权限失效（BLEC0006 等）时自动清 session 重登并重试一次。
+ *
+ * 幂等：按内容 sha256 判重，已上传且内容未变的切图直接跳过；卡片引用改写可反复执行。
+ * **同内容只上传一次**：判重不认文件名——src/slices 里内容完全相同但命名不同的副本、或多张卡共用
+ * 的同一张切图，都按 sha256 命中已上传条目直接复用同一线上地址（manifest 记 `reusedFrom`），
+ * 绝不为同一张图产生第二个 @filestore 地址（`--force` 才强制重传）。
+ * 切图内容变了会重新上传得到新地址，旧地址记入 manifest 的 `superseded` 并一并被改写，
+ * 避免卡片继续指向过期的线上图。
+ *
+ * 用法：
+ *   node skills/finmall-card-sync/scripts/slice_upload.mjs
+ *   node skills/finmall-card-sync/scripts/slice_upload.mjs --only=arrowRightGray.png,icon.png
+ *   node skills/finmall-card-sync/scripts/slice_upload.mjs --all --dry-run
+ *   node skills/finmall-card-sync/scripts/slice_upload.mjs --force --no-rewrite
+ */
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { finmallConfig } from '../../shared/finmall-config.mjs';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const skillDir = path.resolve(scriptDir, '..');
+// 与 api_batch_sync.mjs 一致：skill 位于 <repo-root>/skills/<name>，仓库根为上两级。
+const workspace = path.resolve(skillDir, '..', '..');
+
+// 统一日志美化（容错：缺 server/core/logger 时回退极简实现，保证脚本可独立运行）。
+let log;
+try {
+  ({ log } = await import('../../../server/core/logger.js'));
+} catch {
+  const w = (m, ...a) => console.log(`[slice] ${m}`, ...a);
+  log = {
+    info: w,
+    ok: w,
+    warn: (m, ...a) => console.warn(`[slice] ${m}`, ...a),
+    error: (m, ...a) => console.error(`[slice] ${m}`, ...a),
+    box: () => {},
+    rule: () => {},
+  };
+}
+
+import { ensureFinMallSession } from '../../finmall-session-navigator/scripts/session-manager.mjs';
+import {
+  performLogin,
+  clearTimeoutPrompts,
+  waitForAuthenticatedPage,
+  loadCredentials,
+} from '../../finmall-session-navigator/scripts/finmall_login.mjs';
+
+// 本机设了 HTTP_PROXY 时，Node→Chrome 的 CDP 连接（127.0.0.1）必须排除在代理外。
+for (const key of ['NO_PROXY', 'no_proxy']) {
+  const cur = process.env[key];
+  const extra = '127.0.0.1,localhost';
+  process.env[key] = cur && cur.length ? `${cur},${extra}` : extra;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** 映射清单文件名（与切图真源同目录，随 src/ 一起入库） */
+export const MANIFEST_FILE = 'manifest.json';
+
+const IMAGE_MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+};
+
+// 单文件上传超时。切图都很小（当前全量 <1MB），但 Filestore 对异常对象有「挂起不响应」的
+// 先例（见 api_batch_sync 的封面下载闸门），故内层 AbortController + 外层 race 双重设防。
+const UPLOAD_TIMEOUT_MS = Number(process.env.CARDBUDDY_UPLOAD_TIMEOUT_MS || 60000);
+
+// 服务端判定会话/权限失效并应「重新进入」的特征集合（与 api_batch_sync 同义）。
+const SESSION_INVALID_RE = /BLEC0006|会话超时|会话过期|登录超时|未登录|登录失效|登录已失效|请重新登录|invalid token|token|角色菜单权限发生变化|权限发生变化|重新进入|请重新进入/i;
+
+/** 卡片目录里参与引用改写的文件名（.history/ 快照与封面图不碰） */
+const CARD_JSON_FILES = ['schema.json', 'data.json'];
+
+function withTimeout(promise, ms, label) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label}超时（>${ms}ms），已放弃`)), ms);
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+/** 清空过期会话并以保存的凭据重新登录（与 api_batch_sync.relogin 同实现）。 */
+async function relogin(page) {
+  await clearTimeoutPrompts(page);
+  await page
+    .evaluate(() => {
+      try {
+        localStorage.clear();
+      } catch {
+        /* ignore */
+      }
+    })
+    .catch(() => {});
+  await page.reload({ waitUntil: 'domcontentloaded', timeout: 15000 }).catch(() => {});
+  await sleep(1500);
+  const credentials = await loadCredentials();
+  const result = await performLogin(page, credentials);
+  if (!result.sessionCreated) {
+    throw new Error(
+      '自动重新登录失败：' +
+        (result.businessFailure ? '登录接口返回业务失败' : `HTTP ${result?.status || '失败'}`),
+    );
+  }
+  await page.reload({ waitUntil: 'domcontentloaded', timeout: 15000 }).catch(() => {});
+  await sleep(1500);
+  await clearTimeoutPrompts(page);
+  await waitForAuthenticatedPage(page, 20000);
+}
+
+/**
+ * 在已认证页面上下文内以 multipart/form-data 上传单个文件。
+ * 请求形态取自线上编辑器抓包：表单字段 `fileName`（纯文本原名）+ `file`（二进制，带
+ * filename 与 Content-Type），查询串带 `sassAppId` / `sassWorkspaceId`。
+ *
+ * @returns {Promise<string>} 原始响应文本（交由 parseUploadResponse 解析）
+ */
+async function postUpload(page, { fileName, mime, base64, appId, workspaceId, endpoint }) {
+  return withTimeout(
+    page.evaluate(
+      async ({ fileName, mime, base64, appId, workspaceId, endpoint, timeoutMs }) => {
+        const controller = new AbortController();
+        setTimeout(() => controller.abort(), timeoutMs);
+        // token 仅在页面上下文内读取并直接用于请求，不回传 Node 侧、不打印、不落盘。
+        const readSessionToken = () => {
+          try {
+            const raw = localStorage.getItem('_sessionId');
+            if (!raw) return '';
+            let value = JSON.parse(raw);
+            if (value && typeof value === 'object' && 'value' in value) value = value.value;
+            if (typeof value === 'string' && value.startsWith('"')) {
+              try {
+                value = JSON.parse(value);
+              } catch {
+                /* 保留原字符串 */
+              }
+            }
+            return typeof value === 'string' ? value : '';
+          } catch {
+            return '';
+          }
+        };
+        const sessionToken = readSessionToken();
+        if (!sessionToken) {
+          throw new Error('页面缺少会话凭据（localStorage._sessionId 为空），请先运行 finmall-session-navigator 登录。');
+        }
+        const binary = atob(base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+        const form = new FormData();
+        form.append('fileName', fileName);
+        form.append('file', new Blob([bytes], { type: mime }), fileName);
+        const url = new URL(endpoint, location.origin);
+        url.searchParams.set('sassAppId', String(appId));
+        url.searchParams.set('sassWorkspaceId', String(workspaceId));
+        const response = await fetch(url.href, {
+          method: 'POST',
+          headers: { token: sessionToken, iCIFID: sessionToken, eCIFID: sessionToken, Accept: '*/*' },
+          credentials: 'include',
+          body: form,
+          signal: controller.signal,
+        });
+        const text = await response.text();
+        if (!response.ok) throw new Error(`HTTP ${response.status}: ${text.slice(0, 200)}`);
+        return text;
+      },
+      { fileName, mime, base64, appId, workspaceId, endpoint, timeoutMs: UPLOAD_TIMEOUT_MS },
+    ),
+    UPLOAD_TIMEOUT_MS + 2000,
+    `上传 ${fileName}`,
+  );
+}
+
+/**
+ * 解析 CC0000.do 响应，取出线上地址。已验证响应形态：
+ * `{ header:{errorCode:"0"}, body:{ errorCode:"0", uploadFileList:[
+ *    { fileName:"x.png", filePath:"@filestore/dzqd-download/<ts>_x.png", size:"443", dimensions:"60x60" } ] } }`
+ * 会话失效时 header/body 双双返回 errorCode=BLEC0006，由 uploadWithHeal 捕获后重登重试。
+ */
+function parseUploadResponse(text, fileName) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`上传响应不是 JSON：${text.slice(0, 300)}`);
+  }
+  const header = (parsed && parsed.header) || {};
+  const body = (parsed && parsed.body) || {};
+  const errorCode = header.errorCode || body.errorCode;
+  if (errorCode && errorCode !== '0') {
+    throw new Error(`FinMall 上传失败 [errorCode=${errorCode}] ${header.errorMsg || body.errorMsg || ''}`);
+  }
+  const list = Array.isArray(body.uploadFileList)
+    ? body.uploadFileList
+    : Array.isArray(parsed.uploadFileList)
+      ? parsed.uploadFileList
+      : null;
+  if (!list || !list.length) {
+    throw new Error(`上传响应缺少 uploadFileList：${text.slice(0, 300)}`);
+  }
+  // uploadFileList 是数组（接口支持一次多文件），按 fileName 精确回显匹配，避免批量时错位。
+  const hit = list.find((item) => item && item.fileName === fileName) || list[0];
+  const url = hit && (hit.filePath || hit.fileUrl || hit.url);
+  if (!url || typeof url !== 'string') {
+    throw new Error(`uploadFileList 未给出可用地址：${JSON.stringify(hit).slice(0, 300)}`);
+  }
+  return { url, dimensions: String(hit.dimensions || ''), remoteSize: String(hit.size || '') };
+}
+
+/** 带自愈的上传：命中会话/权限失效特征则清 session 重登后重试一次。 */
+async function uploadWithHeal(page, payload) {
+  try {
+    return parseUploadResponse(await postUpload(page, payload), payload.fileName);
+  } catch (error) {
+    if (SESSION_INVALID_RE.test(error.message)) {
+      log.warn('会话/权限失效，自动重新登录后重试上传', { file: payload.fileName, reason: error.message.slice(0, 40) });
+      await relogin(page);
+      return parseUploadResponse(await postUpload(page, payload), payload.fileName);
+    }
+    throw error;
+  }
+}
+
+/** 扫描 src/slices 下的图片真源（扁平落点，manifest.json 等非图片文件自动忽略） */
+function listSlices(slicesRoot) {
+  if (!existsSync(slicesRoot)) return [];
+  const out = [];
+  for (const name of readdirSync(slicesRoot).sort()) {
+    const file = path.join(slicesRoot, name);
+    if (!statSync(file).isFile()) continue; // 约定为扁平落点，子目录一律忽略
+    const mime = IMAGE_MIME[path.extname(name).toLowerCase()];
+    if (!mime) continue;
+    const buf = readFileSync(file);
+    out.push({
+      name,
+      file,
+      mime,
+      size: buf.length,
+      sha256: createHash('sha256').update(buf).digest('hex'),
+      base64: buf.toString('base64'),
+    });
+  }
+  return out;
+}
+
+/**
+ * 扫描卡片目录，收集 `/slices/<name>` 引用。
+ * 只认「整串等于 /slices/<name>」的字符串值（当前全量 71 处引用均为此形态）；同时认
+ * 「整串等于映射清单里已记录的线上地址（含 superseded 历史地址）」——已改写过的卡片不再
+ * 出现 `/slices/`，若不反查就会把这张卡当成「没引用切图」，导致 manifest 的 cards 关联被
+ * 抹掉、二次点击误报「无需上传」。
+ *
+ * @param {string} cardsRoot
+ * @param {Set<string>} sliceNames src/slices 下实际存在的文件名，用于识别悬空引用
+ * @param {Map<string, string>} urlToName 线上地址（含历史地址）→ 本地切图文件名
+ * @returns {{ refs: Map<string, Set<string>>, cardFiles: string[], dangling: string[] }}
+ */
+function collectCardRefs(cardsRoot, sliceNames, urlToName) {
+  const refs = new Map();
+  const cardFiles = [];
+  if (!existsSync(cardsRoot)) return { refs, cardFiles, dangling: [] };
+  const walk = (value, cardId) => {
+    if (typeof value === 'string') {
+      const matched = /^\/slices\/([^/]+)$/.exec(value);
+      const name = matched ? matched[1] : urlToName.get(value);
+      if (name) {
+        if (!refs.has(name)) refs.set(name, new Set());
+        refs.get(name).add(cardId);
+      }
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item, cardId);
+      return;
+    }
+    if (value && typeof value === 'object') {
+      for (const item of Object.values(value)) walk(item, cardId);
+    }
+  };
+  for (const cardId of readdirSync(cardsRoot).sort()) {
+    const dir = path.join(cardsRoot, cardId);
+    if (!statSync(dir).isDirectory()) continue;
+    for (const name of CARD_JSON_FILES) {
+      const file = path.join(dir, name);
+      if (!existsSync(file)) continue;
+      cardFiles.push(file);
+      try {
+        walk(JSON.parse(readFileSync(file, 'utf8')), cardId);
+      } catch {
+        /* 单卡 JSON 损坏不阻断整批上传，改写阶段会再次跳过 */
+      }
+    }
+  }
+  const dangling = [...refs.keys()].filter((name) => !sliceNames.has(name)).sort();
+  return { refs, cardFiles, dangling };
+}
+
+/**
+ * 把「全量引用表」收窄到单张卡片（顶栏「切图上传」按钮走的就是单卡模式）。
+ * @param {Map<string, Set<string>>} refs 文件名 → 引用它的卡片 id 集合
+ * @param {string} cardId
+ * @returns {Map<string, Set<string>>}
+ */
+function scopeRefsToCard(refs, cardId) {
+  const scoped = new Map();
+  for (const [name, cards] of refs) {
+    if (cards.has(cardId)) scoped.set(name, new Set([cardId]));
+  }
+  return scoped;
+}
+
+/**
+ * 由映射清单构造反查表：线上地址（当前地址 + superseded 历史地址）→ 本地切图文件名。
+ * @param {Record<string, {url?: string, superseded?: string[]}>} files
+ * @returns {Map<string, string>}
+ */
+function buildUrlToName(files) {
+  const urlToName = new Map();
+  for (const [name, entry] of Object.entries(files || {})) {
+    if (!entry) continue;
+    if (entry.url) urlToName.set(entry.url, name);
+    for (const old of entry.superseded || []) {
+      if (old) urlToName.set(old, name);
+    }
+  }
+  return urlToName;
+}
+
+function readManifest(manifestPath) {
+  if (!existsSync(manifestPath)) return { version: 1, files: {} };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`映射清单损坏（${manifestPath}）：${error.message}`);
+  }
+  return {
+    version: parsed.version || 1,
+    updatedAt: parsed.updatedAt,
+    files: parsed.files && typeof parsed.files === 'object' ? parsed.files : {},
+  };
+}
+
+/** 原子写（临时文件 + rename），与 server/core/cardFiles.js 的落盘纪律一致 */
+function writeJsonAtomic(file, value) {
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2), 'utf8');
+  renameSync(tmp, file);
+}
+
+/**
+ * 把卡片里的本地切图引用改写为线上地址。
+ *
+ * 采用「JSON 解析定位 + 原文精确替换」：只把 `JSON.stringify(旧值)` 的字面量替换为
+ * `JSON.stringify(新值)`，从而**完全不改动文件的缩进 / 键序 / 末尾换行**（仓库约定
+ * schema.json 无末尾换行，整体重新序列化会造成全文件 diff）。
+ * 除 `/slices/<name>` 外，同时替换 manifest 记录的 `superseded` 旧线上地址，
+ * 保证切图内容更新后卡片不会继续指向过期图。
+ *
+ * @param {string[]} cardFiles
+ * @param {string} root 仓库根（仅用于把结果里的路径写成相对路径）
+ * @param {Map<string, {url:string, superseded:string[]}>} mapping
+ * @returns {Array<{file:string, cardId:string, count:number}>}
+ */
+function rewriteCardRefs(cardFiles, root, mapping) {
+  const rewritten = [];
+  for (const file of cardFiles) {
+    const raw = readFileSync(file, 'utf8');
+    if (!raw.includes('/slices/') && !raw.includes('@filestore/')) continue;
+    let out = raw;
+    let count = 0;
+    for (const [name, entry] of mapping) {
+      if (!entry || !entry.url) continue;
+      const pairs = [[`/slices/${name}`, entry.url]];
+      for (const old of entry.superseded || []) {
+        if (old && old !== entry.url) pairs.push([old, entry.url]);
+      }
+      for (const [from, to] of pairs) {
+        if (from === to) continue;
+        const needle = JSON.stringify(from);
+        if (!out.includes(needle)) continue;
+        count += out.split(needle).length - 1;
+        out = out.split(needle).join(JSON.stringify(to));
+      }
+    }
+    if (!count) continue;
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, out, 'utf8');
+    renameSync(tmp, file);
+    rewritten.push({ file: path.relative(root, file), cardId: path.basename(path.dirname(file)), count });
+  }
+  return rewritten;
+}
+
+/**
+ * 上传 src/slices 切图并改写卡片引用。
+ *
+ * @param {object} [opts]
+ * @param {string}   [opts.cardId]       单卡模式：只上传该卡引用的切图、只改写该卡的 schema/data
+ *                                        （顶栏「切图上传」按钮走此模式）；缺省 = 全量卡片
+ * @param {string[]} [opts.only]        仅处理这些文件名（默认：全部被卡片引用的切图）
+ * @param {boolean}  [opts.all]          true=连未被任何卡片引用的切图一起上传
+ * @param {boolean}  [opts.force]        true=忽略 sha256 判重，强制重新上传
+ * @param {boolean}  [opts.dryRun]       true=只报告计划，不上传、不写盘
+ * @param {boolean}  [opts.noRewrite]    true=只上传 + 写映射，不改写卡片引用
+ * @param {string}   [opts.appId]        覆盖 sassAppId（默认取 .env.cb 的 FINMALL_APP_ID）
+ * @param {string}   [opts.workspaceId]  覆盖 sassWorkspaceId
+ * @param {string}   [opts.slicesRoot]   切图目录（默认 <repo>/src/slices）
+ * @param {string}   [opts.cardsRoot]    卡片目录（默认 <repo>/src/cards）
+ * @returns {Promise<object>} 汇总结果
+ */
+export async function uploadSlices(opts = {}) {
+  const slicesRoot = path.resolve(opts.slicesRoot || path.join(workspace, 'src', 'slices'));
+  const cardsRoot = path.resolve(opts.cardsRoot || path.join(workspace, 'src', 'cards'));
+  const manifestPath = path.join(slicesRoot, MANIFEST_FILE);
+  const appId = String(opts.appId || finmallConfig.appId);
+  const workspaceId = String(opts.workspaceId || finmallConfig.workspaceId);
+  const dryRun = !!opts.dryRun;
+  const force = !!opts.force;
+  const cardId = opts.cardId ? String(opts.cardId) : '';
+  // 卡片 id 即目录名，只允许 api_batch_sync.normalizeCard 同款安全字符集；
+  // 首字符排除 `.`，避免 `..` 这类纯点号 id 拼出越权路径。
+  if (cardId && !/^[\w][\w.-]*$/.test(cardId)) throw new Error(`非法卡片 id：${cardId}`);
+  if (cardId && !existsSync(path.join(cardsRoot, cardId))) {
+    throw new Error(`卡片不存在：${cardId}（${path.relative(workspace, cardsRoot)}）`);
+  }
+
+  const slices = listSlices(slicesRoot);
+  const sliceNames = new Set(slices.map((s) => s.name));
+  // 映射清单先读：已改写过的卡片引用的是线上地址而非 /slices/，要靠反查表才能把它们
+  // 认回本地切图（否则二次运行会误判「该卡没引用切图」并抹掉 manifest 的 cards 关联）。
+  const manifest = readManifest(manifestPath);
+  let manifestDirty = false;
+  // 跨文件名同内容去重：sha256 → 已上传条目。共用切图（多卡引用同一张图，或同图在 src/slices
+  // 里有命名不同的副本）只上传一次，其余按内容命中直接复用同一线上地址。
+  const shaToUploaded = new Map();
+  for (const [name, entry] of Object.entries(manifest.files)) {
+    if (entry && entry.url && entry.sha256 && !shaToUploaded.has(entry.sha256)) {
+      shaToUploaded.set(entry.sha256, { name, entry });
+    }
+  }
+  // 引用表始终按「全量卡片」统计：manifest 的 cards 字段要如实反映一张切图被哪些卡引用，
+  // 不能因为本次只处理单卡就把其他卡的引用关系抹掉。
+  const scanned = collectCardRefs(cardsRoot, sliceNames, buildUrlToName(manifest.files));
+  // 单卡模式把「上传范围 + 改写范围」都收窄到当前卡；共享切图若已被别的卡上传过，
+  // 这里按 sha256 命中映射直接复用线上地址，不会重复上传。
+  const refs = cardId ? scopeRefsToCard(scanned.refs, cardId) : scanned.refs;
+  const cardFiles = cardId
+    ? scanned.cardFiles.filter((file) => path.basename(path.dirname(file)) === cardId)
+    : scanned.cardFiles;
+  const dangling = cardId
+    ? scanned.dangling.filter((name) => scanned.refs.get(name)?.has(cardId))
+    : scanned.dangling;
+  const only = Array.isArray(opts.only) && opts.only.length ? new Set(opts.only) : null;
+  if (only) {
+    const unknown = [...only].filter((name) => !sliceNames.has(name));
+    if (unknown.length) throw new Error(`--only 指定的切图不存在：${unknown.join('、')}`);
+  }
+
+  const summary = {
+    success: true,
+    dryRun,
+    cardId: cardId || null,
+    appId,
+    workspaceId,
+    slicesRoot: path.relative(workspace, slicesRoot),
+    manifestPath: path.relative(workspace, manifestPath),
+    total: slices.length,
+    referenced: refs.size,
+    dangling,
+    pending: [],
+    skipped: [],
+    uploaded: [],
+    failed: [],
+    rewritten: [],
+    manifestWritten: false,
+  };
+
+  // 待上传集合：默认只上传「被卡片引用」的切图（切图约定的目标就是让卡片引用可远端解析）；
+  // --all 时连未引用的一起上传，便于预先铺素材。sha256 未变的直接跳过（--force 可强制重传）。
+  // 同内容只传一次（slices_convention.md §4.1）：命中「已上传条目」立即复用线上地址；命中「本批次
+  // 计划上传的同内容文件」则延后复用（等它传完拿到地址再写映射），两种情况都不进 pending。
+  const pending = [];
+  const deferredReuse = [];
+  const batchSha = new Map();
+  const writeReusedEntry = (slice, fromName, fromEntry) => {
+    const reused = {
+      url: fromEntry.url,
+      httpUrl: fromEntry.httpUrl || finmallConfig.filestoreUrl(fromEntry.url),
+      sha256: slice.sha256,
+      size: slice.size,
+      reusedFrom: fromName,
+      uploadedAt: new Date().toISOString(),
+      cards: scanned.refs.has(slice.name) ? [...scanned.refs.get(slice.name)].sort() : [],
+    };
+    if (fromEntry.dimensions) reused.dimensions = fromEntry.dimensions;
+    manifest.files[slice.name] = reused;
+    manifestDirty = true;
+  };
+  for (const slice of slices) {
+    const inScope = only ? only.has(slice.name) : !!opts.all || refs.has(slice.name);
+    if (!inScope) continue;
+    const prev = manifest.files[slice.name];
+    if (prev && prev.url && prev.sha256 === slice.sha256 && !force) {
+      summary.skipped.push({ name: slice.name, url: prev.url });
+      continue;
+    }
+    if (!force) {
+      const uploadedTwin = shaToUploaded.get(slice.sha256);
+      if (uploadedTwin && uploadedTwin.name !== slice.name) {
+        summary.skipped.push({ name: slice.name, url: uploadedTwin.entry.url, reusedFrom: uploadedTwin.name });
+        if (!dryRun) writeReusedEntry(slice, uploadedTwin.name, uploadedTwin.entry);
+        continue;
+      }
+      const batchTwin = batchSha.get(slice.sha256);
+      if (batchTwin && batchTwin !== slice.name) {
+        summary.skipped.push({ name: slice.name, url: null, reusedFrom: batchTwin, deferred: true });
+        deferredReuse.push({ slice, fromName: batchTwin });
+        continue;
+      }
+    }
+    if (!batchSha.has(slice.sha256)) batchSha.set(slice.sha256, slice.name);
+    pending.push(slice);
+  }
+  summary.pending = pending.map((s) => ({ name: s.name, size: s.size }));
+
+  // 引用关系（cards）随每次运行刷新，让映射清单能回答「这张图被哪些卡用」。
+  for (const slice of slices) {
+    const prev = manifest.files[slice.name];
+    if (!prev) continue;
+    const cards = scanned.refs.has(slice.name) ? [...scanned.refs.get(slice.name)].sort() : [];
+    if (JSON.stringify(prev.cards || []) !== JSON.stringify(cards)) {
+      prev.cards = cards;
+      manifestDirty = true;
+    }
+  }
+
+  if (dryRun) return summary;
+
+  if (pending.length) {
+    log.info('待上传切图', { count: pending.length, appId, 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 页面，请检查凭据或重新触发上传。');
+      await page.bringToFront();
+
+      for (const slice of pending) {
+        try {
+          const result = await uploadWithHeal(page, {
+            fileName: slice.name,
+            mime: slice.mime,
+            base64: slice.base64,
+            appId,
+            workspaceId,
+            endpoint: finmallConfig.uploadImgEndpoint,
+          });
+          const prev = manifest.files[slice.name];
+          // 内容变了会拿到新地址：旧地址进 superseded（上限 5），改写阶段一并替换，
+          // 否则卡片会继续指向已过期的线上图。
+          const superseded =
+            prev && prev.url && prev.url !== result.url
+              ? [prev.url, ...(prev.superseded || [])].slice(0, 5)
+              : (prev && prev.superseded) || [];
+          const entry = {
+            url: result.url,
+            httpUrl: finmallConfig.filestoreUrl(result.url),
+            sha256: slice.sha256,
+            size: slice.size,
+            uploadedAt: new Date().toISOString(),
+            cards: scanned.refs.has(slice.name) ? [...scanned.refs.get(slice.name)].sort() : [],
+          };
+          if (result.dimensions) entry.dimensions = result.dimensions;
+          if (superseded.length) entry.superseded = superseded;
+          manifest.files[slice.name] = entry;
+          if (!shaToUploaded.has(slice.sha256)) shaToUploaded.set(slice.sha256, { name: slice.name, entry });
+          manifestDirty = true;
+          summary.uploaded.push({ name: slice.name, url: result.url, size: slice.size, dimensions: result.dimensions });
+          log.ok('已上传', { file: slice.name, url: result.url });
+        } catch (error) {
+          summary.success = false;
+          summary.failed.push({ name: slice.name, error: error.message });
+          log.error('上传失败', { file: slice.name, error: error.message });
+        }
+      }
+    } finally {
+      // 仅断开连接，后台 Chrome 常驻以便复用（与 syncCards 一致）。
+      try {
+        await browser.disconnect();
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  // 延后复用：同批次里内容相同的副本，等「源文件」上传拿到地址后再写复用映射
+  for (const { slice, fromName } of deferredReuse) {
+    const fromEntry = manifest.files[fromName];
+    const item = summary.skipped.find((x) => x.name === slice.name && x.deferred);
+    if (fromEntry && fromEntry.url) {
+      if (item) { item.url = fromEntry.url; delete item.deferred; }
+      writeReusedEntry(slice, fromName, fromEntry);
+      if (!shaToUploaded.has(slice.sha256)) shaToUploaded.set(slice.sha256, { name: slice.name, entry: fromEntry });
+    } else if (item) {
+      item.deferred = false;
+      item.note = `同内容源 ${fromName} 未上传成功，本次未复用`;
+      log.warn('同内容复用失败', { file: slice.name, from: fromName });
+    }
+  }
+
+  if (manifestDirty) {
+    manifest.updatedAt = new Date().toISOString();
+    mkdirSync(slicesRoot, { recursive: true });
+    writeJsonAtomic(manifestPath, manifest);
+    summary.manifestWritten = true;
+  }
+
+  if (!opts.noRewrite) {
+    const mapping = new Map(
+      Object.entries(manifest.files)
+        .filter(([, entry]) => entry && entry.url)
+        .map(([name, entry]) => [name, { url: entry.url, superseded: entry.superseded || [] }]),
+    );
+    summary.rewritten = rewriteCardRefs(cardFiles, workspace, mapping);
+  }
+
+  return summary;
+}
+
+function parseArgs(argv) {
+  const parsed = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) continue;
+    const eq = arg.indexOf('=');
+    if (eq >= 0) parsed[arg.slice(2, eq)] = arg.slice(eq + 1);
+    else parsed[arg.slice(2)] = argv[i + 1]?.startsWith('--') ? true : (argv[++i] ?? true);
+  }
+  return parsed;
+}
+
+// 仅当作为脚本直接运行时执行 CLI 逻辑（被 dev server 中间件 import 时不触发）
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const args = parseArgs(process.argv.slice(2));
+  const summary = await uploadSlices({
+    cardId: args.cardId ? String(args.cardId) : undefined,
+    only: args.only ? String(args.only).split(',').map((s) => s.trim()).filter(Boolean) : undefined,
+    all: !!args.all,
+    force: !!args.force,
+    dryRun: !!args['dry-run'],
+    noRewrite: !!args['no-rewrite'],
+    appId: args.appId ? String(args.appId) : undefined,
+    workspaceId: args.workspaceId ? String(args.workspaceId) : undefined,
+    slicesRoot: args.slicesRoot ? path.resolve(workspace, String(args.slicesRoot)) : undefined,
+    cardsRoot: args.cardsRoot ? path.resolve(workspace, String(args.cardsRoot)) : undefined,
+  });
+  const lines = [
+    `目标：sassAppId=${summary.appId} sassWorkspaceId=${summary.workspaceId}${summary.dryRun ? '（dry-run，未上传）' : ''}`,
+    `范围：${summary.cardId ? `单卡 ${summary.cardId}` : '全部卡片'}`,
+    `切图：${summary.total} 个（本次范围内被引用 ${summary.referenced} 个），待上传 ${summary.pending.length} 个`,
+    `本次上传：${summary.uploaded.length} 个${summary.uploaded.length ? ` → ${summary.uploaded.map((u) => u.name).join('、')}` : ''}`,
+    `跳过：${summary.skipped.length} 个（内容未变 ${summary.skipped.filter((x) => !x.reusedFrom).length}；同内容复用已上传地址 ${summary.skipped.filter((x) => x.reusedFrom).length}${summary.skipped.some((x) => x.reusedFrom) ? ` → ${summary.skipped.filter((x) => x.reusedFrom).map((x) => `${x.name}≡${x.reusedFrom}`).join('、')}` : ''}）`,
+    `改写引用：${summary.rewritten.length} 个文件 / ${summary.rewritten.reduce((a, r) => a + r.count, 0)} 处`,
+    `映射清单：${summary.manifestPath}${summary.manifestWritten ? '（已更新）' : '（无变化）'}`,
+    ...(summary.failed.length ? [`失败：${summary.failed.map((f) => `${f.name}（${f.error}）`).join('、')}`] : []),
+    ...(summary.dangling.length ? [`悬空引用（schema 引用但 src/slices 无此文件）：${summary.dangling.join('、')}`] : []),
+  ];
+  log.box({ title: '切图上传结果', level: summary.success ? 'ok' : 'warn', lines });
+  // 显式退出：ensureFinMallSession 内部的登录流程会另开一条 CDP 连接且按约定不关闭
+  // （后台 Chrome 要常驻复用），残留的 WebSocket 会让事件循环一直不空、进程挂住不退出。
+  // 与 finmall_login.mjs CLI 同款处理——detached 的 Chrome 进程不受影响，继续运行。
+  process.exit(summary.success ? 0 : 1);
+}