cardbuddy 0.21.0 → 0.22.0

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-CpDojF__.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-C8VLzU18.css">
+    <script type="module" crossorigin src="/assets/index-CPpLZZyi.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CU8zVA2P.css">
   </head>
   <body>
     <div id="app"></div>

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

@@ -15,17 +15,20 @@ import { resolveCardDir } from './cardOpenFolder.js'
  *   <targetDir>/<yyMMddHHmmss+4位序号>/        ← 临时文件夹（完成后删除）
  *     cards.json                               ← 卡片清单（cardPO 数组，殿后写入）
  *     <数字id>/<数字id>.json                   ← { cardPO, cardJobPO, variablePOS, imageLists, platformStatus }
- *     <数字id>/<封面文件>                      ← 封面，文件名恒等于 cards.json 里该卡 picUrl 的末段
- *     <数字id>/image/<imageName>               ← schema.view 树引用的 @filestore 图片下载落盘
+ *     <数字id>/<cardCode><ext>                 ← 封面，文件名 === cards.json 里 picUrl 末段（见「封面命名铁律」）
+ *     <数字id>/image/<imageName>               ← schema.view 树引用的 @filestore 图片下载落盘（沿用原始名）
  *   <targetDir>/<同名>.zip                     ← 纯 Node 写出的 zip（条目平铺、无顶层文件夹）
  *
- * 封面铁律（2026-10-22 事故后定，依据 57 张官方导出样本 + ImportCardAction.java:61-64）：
- * - picUrl 恒非空，且末段 === `<数字id>/` 下封面文件名。导入侧按 picUrl 末段推文件名后直接读该文件，
- *   对所有空值/缺失零防御（空串时路径退化成卡目录，读目录抛异常）。
- * - 无本地封面的卡**不允许导出**（计入 failed 并给出补齐指引），不产「有卡无封面」的残包。
- * - 有 `.import-meta.json` 的 remote 快照时沿用远端真值（picUrl/cardClassId/applyScene）；
- *   本地新建卡按同一形态合成 picUrl，cardClassId 留空、applyScene 回落 '1'。
- * - 写 zip 前跑 verifyCardsJsonInvariants 自检，违例即整单失败。
+ * 封面命名铁律（2026-10-26 四期事故后定，四次事故复盘见 docs §9.1~§9.4）：
+ *   封面文件名 = `<cardCode><封面扩展名>`，cardPO.picUrl = `@filestore/dzqd-download/<同上文件名>`
+ * —— cardCode 是本地卡片目录名（= cardPO.code，也是同步/真机链路的一等身份标识），天然只含
+ * `[A-Za-z0-9_-]`，对**任何** percent-encode 口径（Java URLEncoder / JS encodeURIComponent /
+ * 后端「不编码直接字面比较」）都还原自身 ⇒ picUrl 末段、磁盘封面名、zip 封面条目名三处**字面相等**，
+ * 不再依赖双方编码器互相猜。
+ * 前四期事故（① picUrl 置空 ② 中文名编码不一致 ③ `@`/括号 JS 与 Java 口径不同 ④ 空格名）全部同源：
+ * 「JSON 里保留用户原始封面名、由包内外各自编码推导磁盘名」。规范化命名一次性根除该类型。
+ * 作用域只到封面：`image/` 与 imageLists 仍沿用 view 树引用的原始名 + 既有 percent-encode 条目口径。
+ * 写 zip 前跑 verifyCardsJsonInvariants / verifyZipEntryNames 两道自检，违例即整单失败。
  * 任务制端点（与 /__sync 同构：单飞制 + 看门狗 + 轮询 + 取消）：
  * - POST /__export-cards          body { cardIds[], targetDir } → { ok, jobId, total }
  * - GET  /__export/progress?jobId → { ok, done, total, currentId, currentTitle, finished, result }
@@ -317,28 +320,164 @@ function refBasename(ref) {
  * picUrl 为空串时路径退化成卡目录本身，读目录抛异常，整卡导入失败。
  * 故此处绝不允许产出空 picUrl。
  *
- * @param {{ remotePicUrl?: string, coverPath: string }} o
- *   remotePicUrl：`.import-meta.json` 记录的远端真值（有则原样沿用，形态与官方产物同构）；
- *   coverPath：本地封面绝对路径（无远端真值时以其文件名为准）。
- * @returns {{ fileName: string, picUrl: string, inherited: boolean }}
+ * 文件名不再继承远端 / 用户上传的原始名（四期事故：中文 / 空格 / `@` / 括号四次都因两侧
+ * 编码口径不一致而对不上），统一取 `<资源基名><扩展名>`（资源基名 = cardCode，见 resolveAssetBase）
+ * —— 任何编码口径都还原自身。
+ *
+ * @param {{ assetBase: string, coverPath: string }} o
+ *   assetBase：资源命名基名（cardCode，异常时回落数字 id）；coverPath：本地封面绝对路径（只取扩展名）。
+ * @returns {{ fileName: string, picUrl: string }}
+ */
+export function resolveCoverForExport({ assetBase, coverPath }) {
+  const fileName = coverExportName(assetBase, path.extname(coverPath))
+  return { fileName, picUrl: `${COVER_FILESTORE_PREFIX}/${fileName}` }
+}
+
+/** percent-encode 的保留字符集：与 Java `URLEncoder` 的「无需编码」集合同口径（`*` 也保留） */
+const ENC_SAFE_CH = /[A-Za-z0-9\-_.*]/
+/**
+ * 按 **Java `URLEncoder.encode(x, "UTF-8")` 口径**做 percent-encode（空格例外，见下）。
+ *
+ * 为什么不用内置 `encodeURIComponent`：两者的保留集合不同，JS 会放过 `! ' ( ) ~`，
+ * Java 会全部编码。2026-10-26 事故的封面名 `20260615151313_WPS图片(1).png` 正好踩在
+ * `(` `)` 上：JS 口径产出 `...%E5%9B%BE%E7%89%87(1).png`，后端按自己的口径算出
+ * `...%E5%9B%BE%E7%89%87%281%29.png`，两边对不上 → 找不到封面文件 → 导入失败。
+ *
+ * 空格：Java 原生编码成 `+`，而官方 57 卡样本里 `电话备份 2@3x.png` 落地是 `%20`，
+ * 故按 `+`→`%20` 归一（`%20` 在两种解码口径下都还原成空格，`+` 只在 URL 表单口径下还原）。
+ * @param {string} str 原始文本
+ * @returns {string}
+ */
+export function javaUrlEncode(str) {
+  let out = ''
+  for (const ch of String(str)) {
+    if (ENC_SAFE_CH.test(ch)) {
+      out += ch
+    } else if (ch === ' ') {
+      out += '%20'
+    } else {
+      for (const b of Buffer.from(ch, 'utf8')) out += '%' + b.toString(16).toUpperCase().padStart(2, '0')
+    }
+  }
+  return out
+}
+
+/* ------------------------- 包内资源命名（2026-10-26 四期：一律以卡片 id 生成） ------------------------- */
+
+/** 扩展名归一：只认已知图片扩展名（小写），其余或缺失回落 `.png` */
+export function normalizeImageExt(ext, fallback = '.png') {
+  const e = String(ext || '').toLowerCase()
+  return IMAGE_EXTS.has(e) ? e : fallback
+}
+
+/**
+ * 「编码无关」文件名判定：该名字在**任何** percent-encode 口径下都还原自身。
+ * 只有纯 `[A-Za-z0-9._-]` 成立 —— 中文、空格、`@`、`(` `)`、`%`、`~`、`!` 在任一口径下都会变形。
+ * 这是四次事故的总闸：名字符合此判定 ⇒ JSON 里的值与磁盘名/zip 条目名不可能对不上。
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isInvariantName(name) {
+  const s = String(name || '')
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(s) && javaUrlEncode(s) === s
+}
+
+/** 封面文件名：`<资源基名><ext>`（卡目录根，与 `<数字id>.json` 同级，彼此不撞名） */
+export function coverExportName(base, ext) {
+  return `${base}${normalizeImageExt(ext)}`
+}
+
+/**
+ * 资源命名基名：**用 cardCode（= 本地卡片目录名 = cardPO.code）**，不用用户上传 / 远端原始文件名。
+ * cardCode 是本仓对卡片的一等身份标识（`-cardCode mostlyLike` 同步、侧车 `cardCode`、真机 `alertCard({cardCode})`
+ * 全部以此为准），且天然只含 `[A-Za-z0-9_-]`（`cardSync` 的 `CARD_CODE_RE` 同口径校验），可直接做文件名。
+ * 兜底：个别目录名万一不合「编码无关」判定，回落到数字 id 并告警 —— 宁可用数字也不用不可推导的名字。
+ * @param {{ cardCode: string, numericId: string, onFallback?: (msg: string) => void }} o
+ * @returns {string}
+ */
+export function resolveAssetBase({ cardCode, numericId, onFallback }) {
+  const code = String(cardCode || '')
+  if (isInvariantName(code)) return code
+  if (typeof onFallback === 'function') {
+    onFallback(`cardCode 不合规范化字符集（${code}），资源名回落到数字 id ${numericId}`)
+  }
+  return String(numericId)
+}
+
+/**
+ * zip 条目名转 ASCII：**JSON 保留原名，包内文件名 percent-encode**。
+ *
+ * 契约依据（官方 57 卡大样本 `2609091710000055.zip`：439 个条目里非 ASCII 为 0）：
+ * 中文名整段编码——`20260519101312_右箭头@3x.png` 落地为
+ * `20260519101312_%E5%8F%B3%E7%AE%AD%E5%A4%B4%403x.png`（`@`→`%40`、空格→`%20`），
+ * 而 `cards.json`/`<id>.json` 里的 `picUrl`、`imageName`、`localUrl` 全部保持中文原文。
+ * 该口径与 `javaUrlEncode()` 对 439 个官方条目**逐字节一致**（除去老工具写出的 `????` 乱码副本）。
+ *
+ * 为什么必须这样（2026-10-23 事故）：后端（Java）读 zip 条目名不认 UTF-8 语言编码标志位，
+ * 非 ASCII 名会被按默认字符集解成乱码 → 解压落盘的文件名与 JSON 里引用的名字对不上 →
+ * 导入报错。上一版只落中文原名（旧 §8.1「只落原名一份」）正是这次失败的直接原因。
+ *
+ * **所有段无条件编码**（不是「命中中文才编码」）：官方样本 `20260522173828_VS-44@3x.png`
+ * 整段无中文，仍落地为 `20260522173828_VS-44%403x.png`。纯 ASCII 名里的 `@`/空格/括号/`#`
+ * 同样要编（`greetingRecommend` 的 `mascotDing@2x.png`、`activityList` 的 `...图片(1).png`）。
+ *
+ * 幂等：已编码段（本地切图名可能本来就是 %XX 形式）先 decode 再 encode，避免二次编码；
+ * 含裸 `%` 无法解码时按原文编码（`%`→`%25`）。
+ * @param {string} rel 相对路径（POSIX 分隔符）
+ * @returns {string}
  */
-export function resolveCoverForExport({ remotePicUrl, coverPath }) {
-  const localName = path.basename(coverPath)
-  const remote = typeof remotePicUrl === 'string' ? remotePicUrl.trim() : ''
-  if (remote) {
-    // 远端真值可能带 query（极少见），取文件名时剥掉；picUrl 本身保持原样不重写
-    const name = path.basename(remote.split('?')[0].split('#')[0])
-    if (name) return { fileName: name, picUrl: remote, inherited: true }
+export function zipEntryName(rel) {
+  return String(rel)
+    .split('/')
+    .map((seg) => {
+      let raw = seg
+      try {
+        raw = decodeURIComponent(seg)
+      } catch {
+        /* 含裸 % / 非法转义：直接按原文编码 */
+      }
+      return javaUrlEncode(raw)
+    })
+    .join('/')
+}
+
+/**
+ * zip 层自检（与后端无关的结构断言）：
+ * 1. 条目名全 ASCII（官方 439/439 全 ASCII；非 ASCII 名会被后端按错误字符集解成乱码）；
+ *    image/ 下的图仍沿用原始名，由 `zipEntryName()` 编码成 %XX 形态落条目（见 §4.2）。
+ * 2. 无重名（同卡两个不同文件编码后撞名会让其中一份被覆盖）；
+ * 3. 每张卡的封面以「picUrl 末段」的条目名存在（封面名已是规范化名，`zipEntryName` 对其为恒等变换）。
+ * @param {{ cardsPO: Array<object>, zipNames: string[] }} o
+ * @returns {string[]}
+ */
+export function verifyZipEntryNames({ cardsPO, zipNames }) {
+  const problems = []
+  const names = zipNames || []
+  for (const n of names) {
+    if (/[^\x00-\x7F]/.test(n)) problems.push(`条目名非 ASCII：${n}`)
   }
-  return { fileName: localName, picUrl: `${COVER_FILESTORE_PREFIX}/${localName}`, inherited: false }
+  const seen = new Set()
+  for (const n of names) {
+    if (seen.has(n)) problems.push(`条目名重复：${n}`)
+    seen.add(n)
+  }
+  for (const po of cardsPO || []) {
+    if (!po || !po.picUrl) continue
+    const id = String(po.id)
+    const cover = path.basename(String(po.picUrl).split('?')[0])
+    const expect = zipEntryName(`${id}/${cover}`)
+    if (!seen.has(expect)) problems.push(`${id}: 封面条目缺失 ${expect}`)
+  }
+  return problems
 }
 
 /**
  * 产物自检：cards.json 的每条 cardPO 都能被导入侧无障碍消费。
  * 只做**与后端无关**的结构断言（不依赖远端服务，纯本地即可证伪）：
  * 1. picUrl 非空；
- * 2. picUrl 末段在 `<id>/` 卡目录根存在且是文件（不是目录）；
- * 3. 每张卡都有 `<id>/<id>.json`。
+ * 2. picUrl 末段**编码无关**（否则 backend 按自己的编码口径推文件名必然错位）；
+ * 3. picUrl 末段在 `<id>/` 卡目录根存在且是文件（不是目录）；
+ * 4. 每张卡都有 `<id>/<id>.json`。
  * 返回问题清单（空数组 = 通过）。任何一条违例都会被导入侧的同一段逻辑打出异常。
  * @param {{ cardsPO: Array<object>, outDir: string }} o
  * @returns {string[]}
@@ -353,12 +492,16 @@ export function verifyCardsJsonInvariants({ cardsPO, outDir }) {
       continue
     }
     const name = path.basename(String(picUrl).split('?')[0])
-    const coverAbs = path.join(outDir, id, name)
+    // 末段必须是「编码无关」的生成名：含中文/空格/@/括号时，两侧编码口径一旦不同就对不上（四期同源事故）
+    if (!isInvariantName(name)) {
+      problems.push(`${id}: picUrl 末段含需转义字符 ${name}（封面名须为纯 [A-Za-z0-9._-]）`)
+    }
     let stat = null
     try {
-      stat = fs.statSync(coverAbs)
+      const s = fs.statSync(path.join(outDir, id, name))
+      if (!stat) stat = s
     } catch {
-      /* 不存在即视为违例 */
+      /* 不存在即报错 */
     }
     if (!stat) problems.push(`${id}: 封面文件缺失 ${name}`)
     else if (!stat.isFile()) problems.push(`${id}: 封面路径不是文件 ${name}`)
@@ -402,11 +545,15 @@ async function exportOneCard({ root, id, outDir, upstream, buildPreview }) {
         '无封面必导入失败。请先在卡片上「生成封面预览图」补齐，再重试导出'
     )
   }
+  const warnings = []
   const remoteMeta = (meta && meta.remote) || null
-  const cover = resolveCoverForExport({
-    remotePicUrl: remoteMeta && remoteMeta.picUrl,
-    coverPath,
+  // 资源名基名 = cardCode（本地目录名 = cardPO.code）；不再 Ping-pong 用户/远端的原始文件名与编码口径
+  const assetBase = resolveAssetBase({
+    cardCode: id,
+    numericId,
+    onFallback: (msg) => warnings.push(msg),
   })
+  const cover = resolveCoverForExport({ assetBase, coverPath })
 
   const cardPO = {
     id: numericId,
@@ -416,8 +563,8 @@ async function exportOneCard({ root, id, outDir, upstream, buildPreview }) {
     updateTime: null,
     sassAppId: (meta && meta.appId) || '100001',
     sassWorkspaceId: (meta && meta.workspaceId) || 'dev',
-    // picUrl 恒非空，且末段 === 卡目录根封面文件名（见 resolveCoverForExport 的契约说明）：
-    // 有远端真值（侧车 remote.picUrl）就原样沿用，与官方产物同构；本地新建卡按同一形态合成。
+    // picUrl 恒非空，且末段 === 卡目录根封面文件名（见 resolveCoverForExport 的契约说明）。
+    // 名字由数字 id 生成、编码无关，picUrl 末段 / 磁盘名 / zip 条目名三者字面相等，无需任何转义推导。
     picUrl: cover.picUrl,
     // 远端列表才有的分类字段：有真值用真值（官方 57 张样本里恒非空），未知时留空由导入侧兜底
     cardClassId: (remoteMeta && remoteMeta.cardClassId) || '',
@@ -463,6 +610,7 @@ async function exportOneCard({ root, id, outDir, upstream, buildPreview }) {
     updateTime: null,
   }))
 
+  // imageName/localUrl 沿用 view 树引用的原始末段（本次不改图片口径，见 §9.4）
   const refs = collectViewImageRefs(schema.view)
   const imageLists = refs.map(({ ref }) => {
     const imageName = refBasename(ref)
@@ -477,9 +625,8 @@ async function exportOneCard({ root, id, outDir, upstream, buildPreview }) {
   // 落盘：<outDir>/<numericId>/
   const cardOutDir = path.join(outDir, numericId)
   fs.mkdirSync(cardOutDir, { recursive: true })
-  const warnings = []
 
-  // 图片：@filestore 走 minio 公网下载；/slices/ 从 src/slices 拷贝
+  // 图片：@filestore 走 minio 公网下载；/slices/ 从 src/slices 拷贝（落盘名沿用原 ImageName）
   for (const { ref, kind } of refs) {
     const imageName = refBasename(ref)
     if (!imageName) continue
@@ -487,7 +634,7 @@ async function exportOneCard({ root, id, outDir, upstream, buildPreview }) {
     try {
       fs.mkdirSync(path.dirname(dest), { recursive: true })
       if (kind === 'slice') {
-        const src = path.join(root, 'src', 'slices', imageName)
+        const src = path.join(root, 'src', 'slices', refBasename(ref))
         if (!fs.existsSync(src)) throw new Error('本地切图不存在')
         fs.copyFileSync(src, dest)
       } else {
@@ -512,9 +659,6 @@ async function exportOneCard({ root, id, outDir, upstream, buildPreview }) {
 
   // 封面：以 picUrl 末段的文件名落卡目录根（导入侧按此名取文件；官方产物同形）
   fs.copyFileSync(coverPath, path.join(cardOutDir, cover.fileName))
-  if (!cover.inherited) {
-    warnings.push(`本地无远端 picUrl，封面已合成 ${cover.picUrl}（文件名为本地预览图名）`)
-  }
 
   const cardJson = JSON.stringify({
     cardPO,
@@ -607,13 +751,15 @@ async function runExportJob(job, { root, cardIds, targetDir, upstream, viteServe
       )
     }
 
-    // 收集 zip 条目（按名排序保证确定性），cards.json 殿后（与样本一致）
+
+    // 收集 zip 条目（按名排序保证确定性），cards.json 殿后（与样本一致）。
+    // 条目名一律经 zipEntryName 转 ASCII：JSON 里保留原名，包内文件名 percent-encode。
     const collectEntries = (dir, prefix) => {
       for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
         const full = path.join(dir, entry.name)
         const rel = prefix ? `${prefix}/${entry.name}` : entry.name
         if (entry.isDirectory()) collectEntries(full, rel)
-        else zipEntries.push({ name: rel, data: fs.readFileSync(full) })
+        else zipEntries.push({ name: zipEntryName(rel), data: fs.readFileSync(full) })
       }
     }
     collectEntries(outDir, '')
@@ -621,6 +767,18 @@ async function runExportJob(job, { root, cardIds, targetDir, upstream, viteServe
     fs.writeFileSync(path.join(outDir, 'cards.json'), JSON.stringify(cardsPO), 'utf8')
     zipEntries.push({ name: 'cards.json', data: Buffer.from(JSON.stringify(cardsPO), 'utf8') })
 
+    // zip 层自检：条目名全 ASCII（对齐官方 439/439）、无重名、每张卡的封面条目按编码名命中
+    const zipProblems = verifyZipEntryNames({
+      cardsPO,
+      zipNames: zipEntries.map((e) => e.name),
+    })
+    if (zipProblems.length) {
+      throw new Error(
+        `导出产物 zip 自检未通过（${zipProblems.length} 项）：${zipProblems.slice(0, 5).join('；')}` +
+          (zipProblems.length > 5 ? ' 等' : '')
+      )
+    }
+
     const zipPath = path.join(targetDir, `${folderName}.zip`)
     fs.writeFileSync(zipPath, buildZip(zipEntries))
 

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

@@ -0,0 +1,190 @@
+import { execFile } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * 卡片发布后的「本地快照提交」：只提交该卡片目录下的变更，不 push、不触碰其他改动。
+ *
+ * 设计约束（与仓库 AGENTS.md 的提交规范一致）：
+ *  - 提交类型固定用 `chore(cards)`：发布快照属日常维护，按 version-bump 映射不升版本号；
+ *  - 只提交 `src/cards/<code>/` 这一个 pathspec：`git commit --only -- <path>` 会忽略索引里
+ *    其他已暂存的内容，绝不把用户正在做的别处改动一起带走；
+ *  - `.import-meta.json` 等被 .gitignore 忽略的文件由 git 自行跳过，无需特判；
+ *  - 永不 push、永不抛错：远端发布已经成功，本地提交失败只作为附加信息回传，不影响主流程；
+ *  - 失败时不 reset 索引：宁可留下已暂存状态，也不清掉用户原本的暂存意图。
+ *
+ * 「工程不是 git 工程」是正常场景（npm 包 / 独立部署副本 / 拷进别的仓库子目录都会没有
+ * 自己的 .git），因此这条链路必须全程静默降级：识别为不可提交就返回 skipped 类 reason，
+ * 既不写日志噪声，也不给用户弹错误提示。
+ */
+
+const GIT_TIMEOUT_MS = 20000
+
+/** 模块级串行队列：连续两次发布避免并发争抢 .git/index.lock */
+let chain = Promise.resolve()
+
+/**
+ * 跑一条 git 命令（不抛错，统一返回结果对象）。
+ * @param {string} cwd
+ * @param {string[]} args
+ * @returns {Promise<{ok: boolean, stdout: string, stderr: string, code: string}>}
+ */
+function runGit(cwd, args) {
+  return new Promise((resolve) => {
+    execFile(
+      'git',
+      args,
+      {
+        cwd,
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: 4 * 1024 * 1024,
+        // 禁用任何交互（凭据 / 编辑器），避免服务进程被 git 挂住
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_EDITOR: 'true', GIT_PAGER: 'cat' },
+      },
+      (err, stdout, stderr) => {
+        resolve({
+          ok: !err,
+          stdout: String(stdout || ''),
+          stderr: String(stderr || ''),
+          // ENOENT = 机器上没装 git / 不在 PATH；killed = 超时被杀
+          code: String((err && (err.code || (err.killed ? 'ETIMEDOUT' : ''))) || ''),
+        })
+      },
+    )
+  })
+}
+
+/** 相对路径统一成 posix 形式（git pathspec 在 Windows 上同样接受正斜杠） */
+function toPosixRel(root, target) {
+  const rel = path.relative(root, target)
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return ''
+  return rel.split(path.sep).join('/')
+}
+
+/**
+ * 路径归一：解析软链后比较，避免 /var 与 /private/var、符号链接目录导致的误判。
+ * 解析失败（目录已删等）退回 path.resolve。
+ */
+function canonical(p) {
+  try {
+    return fs.realpathSync(p)
+  } catch {
+    return path.resolve(p)
+  }
+}
+
+/**
+ * 判断 root 是否为「自己的」git 仓库根。
+ *
+ * 只认 root 本身就是仓库顶层（`rev-parse --show-toplevel` == root）这一种情况：
+ *  - 不是仓库 → not_a_git_repo（工程未纳入版本控制，正常场景）；
+ *  - 位于某个父仓库内部（例如把工程拷进 home 目录仓库 / 某个巨仓子目录）→ 也算
+ *    not_a_git_repo，绝不能把卡片提交到那个不相干的父仓库里去；
+ *  - git 命令不存在 / 超时 → git_unavailable。
+ *
+ * @returns {Promise<{ok: boolean, reason?: string, message?: string}>}
+ */
+async function detectOwnRepo(root) {
+  const ver = await runGit(root, ['--version'])
+  if (!ver.ok) {
+    return {
+      ok: false,
+      reason: 'git_unavailable',
+      message: ver.code === 'ENOENT' ? '未检测到 git 命令' : 'git 命令执行失败',
+    }
+  }
+  const top = await runGit(root, ['rev-parse', '--show-toplevel'])
+  if (!top.ok) {
+    return { ok: false, reason: 'not_a_git_repo', message: '工程目录不是 git 仓库' }
+  }
+  if (canonical(top.stdout.trim()) !== canonical(root)) {
+    return {
+      ok: false,
+      reason: 'not_a_git_repo',
+      message: '工程目录不是独立的 git 仓库根（位于其他仓库内部），已跳过提交',
+    }
+  }
+  return { ok: true }
+}
+
+/**
+ * 提交某卡片目录的未提交变更（不 push）。
+ *
+ * @param {{ root: string, cardDir: string|null, cardCode: string, version?: string|number }} opts
+ * @returns {Promise<{ committed: boolean, reason?: string, message?: string, hash?: string, files?: string[] }>}
+ *   reason 取值：card_dir_not_found / not_a_git_repo / git_unavailable / no_changes / failed
+ */
+export function commitCardChanges({ root, cardDir, cardCode, version }) {
+  const task = chain.then(() => doCommit({ root, cardDir, cardCode, version }))
+  // 队列自身吞掉异常，保证后续任务不被前一个失败拖垮
+  chain = task.catch(() => {})
+  return task
+}
+
+async function doCommit({ root, cardDir, cardCode, version }) {
+  try {
+    if (!cardDir) {
+      return { committed: false, reason: 'card_dir_not_found', message: '未定位到卡片本地目录' }
+    }
+    const rel = toPosixRel(root, cardDir)
+    if (!rel) {
+      return { committed: false, reason: 'card_dir_not_found', message: '卡片目录不在工程根内' }
+    }
+
+    const repo = await detectOwnRepo(root)
+    if (!repo.ok) {
+      // 工程不是 git 工程（含 git 不可用）属正常场景：静默跳过，不产生任何提示
+      return { committed: false, reason: repo.reason, message: repo.message }
+    }
+
+    // 该卡目录是否有未提交变更（含未跟踪文件；被忽略的文件不计入，符合预期）
+    const status = await runGit(root, ['status', '--porcelain', '--', rel])
+    if (!status.ok) {
+      return { committed: false, reason: 'failed', message: status.stderr.trim() || 'git status 失败' }
+    }
+    if (!status.stdout.trim()) {
+      return { committed: false, reason: 'no_changes' }
+    }
+
+    const add = await runGit(root, ['add', '-A', '--', rel])
+    if (!add.ok) {
+      return { committed: false, reason: 'failed', message: add.stderr.trim() || 'git add 失败' }
+    }
+
+    // add 之后仍可能为空（例如只改动了被 .gitignore 忽略的文件）
+    const staged = await runGit(root, ['diff', '--cached', '--name-only', '--', rel])
+    const files = staged.ok
+      ? staged.stdout
+          .split('\n')
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : []
+    if (!files.length) {
+      return { committed: false, reason: 'no_changes' }
+    }
+
+    // 提交类型固定 chore：发布快照属日常维护，不触发版本号升级（映射见 tools/version-bump.mjs）
+    const ver = version == null || String(version).trim() === '' ? '' : ` v${version}`
+    const message = `chore(cards): ${cardCode} 发布${ver ? `${ver} 后` : '后'}提交本地变更`
+    // --only + pathspec：只提交该卡目录的工作区内容，索引里其他已暂存改动原样保留
+    const commit = await runGit(root, ['commit', '--only', '-m', message, '--', rel])
+    if (!commit.ok) {
+      return {
+        committed: false,
+        reason: 'failed',
+        message: (commit.stderr || commit.stdout).trim() || 'git commit 失败',
+        files,
+      }
+    }
+
+    const head = await runGit(root, ['rev-parse', '--short', 'HEAD'])
+    return {
+      committed: true,
+      hash: head.ok ? head.stdout.trim() : '',
+      message,
+      files,
+    }
+  } catch (e) {
+    return { committed: false, reason: 'failed', message: String((e && e.message) || e) }
+  }
+}

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

@@ -1,6 +1,7 @@
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { assertRemoteSource } from './cardSidecar.js'
+import { assertRemoteSource, findCardDir } from './cardSidecar.js'
+import { commitCardChanges } from './cardGitCommit.js'
 import { checkPushAllowed } from './cardListCache.js'
 import { log } from './logger.js'
 import { resolveSkillPathOrProject } from './skillPaths.js'
@@ -20,6 +21,10 @@ const SYNC_SCRIPT_REL = 'finmall-card-sync/scripts/api_batch_sync.mjs'
  *     避免把测试数据误发布到 FinMall 服务器。
  *   - checkPushAllowed：卡片须存在于远端列表缓存（全量同步时刷新）；缓存为空（尚未同步）则放行。
  *
+ * 发布成功后的收尾：把该卡目录（src/cards/<code>/）的未提交变更提交为一条
+ * `chore(cards)` 提交（见 cardGitCommit.js），只落本地、不 push。提交结果随响应
+ * 以 commit 字段回传，前端据此提示；提交失败不回滚发布，也不影响接口成功态。
+ *
  * @param {{ root: string }} opts
  * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, next: Function) => void}
  */
@@ -72,9 +77,38 @@ export function createPublishMiddleware({ root }) {
         const { publishCard } = await import(pathToFileURL(skillPath).href)
         const result = await publishCard(payload.schema)
         log.ok('卡片发布完成', { cardId: payload.schema.pageId, nextVersion: result.nextVersion })
+
+        // 发布成功后的本地快照：该卡目录若有未提交变更，只提交这一个目录（不 push）。
+        // 提交的是磁盘现状——编辑器未保存的改动不在其中，故失败/跳过都不影响发布结果。
+        // 整段独立 try/catch：工程不是 git 工程、git 未安装、定位目录异常等一律静默降级，
+        // 绝不能让附加的本地提交把已经成功的发布改成 500。
+        let commit = { committed: false, reason: 'skipped', message: '本地提交环节已跳过' }
+        try {
+          const cardDir = findCardDir(root, { pageId: payload.schema.pageId })
+          const cardCode = cardDir ? path.basename(cardDir) : String(payload.schema.pageId)
+          commit = await commitCardChanges({ root, cardDir, cardCode, version: result.nextVersion })
+          if (commit.committed) {
+            log.ok('发布后已提交卡片本地变更', { cardCode, hash: commit.hash, files: commit.files })
+          } else if (commit.reason === 'failed') {
+            log.warn('发布后提交卡片本地变更失败', { cardCode, message: commit.message })
+          }
+          // 其余 reason（not_a_git_repo / git_unavailable / no_changes / card_dir_not_found）
+          // 都是正常的「无需提交」，不写日志、不提示用户。
+        } catch (e) {
+          commit = { committed: false, reason: 'skipped', message: String((e && e.message) || e) }
+          log.warn('本地提交环节异常（已忽略，不影响发布）', { message: String((e && e.message) || e) })
+        }
+
         res.statusCode = 200
         res.setHeader('Content-Type', 'application/json')
-        return res.end(JSON.stringify({ ok: true, maxVersion: result.maxVersion, nextVersion: result.nextVersion }))
+        return res.end(
+          JSON.stringify({
+            ok: true,
+            maxVersion: result.maxVersion,
+            nextVersion: result.nextVersion,
+            commit,
+          }),
+        )
       } catch (e) {
         log.error('卡片发布失败', e)
         // 区分「凭据缺失」与「真正的发布错误」：前者让前端弹登录表单，而非裸抛 ENOENT。