cardbuddy 0.19.0 → 0.19.2

package/dist/skills-upgrade.js

@@ -0,0 +1,220 @@
+/**
+ * `cardbuddy skills upgrade` —— 把已装 cardbuddy 包内最新的技能库同步进当前工程的 skills/。
+ *
+ * 背景：init 时把 dist/vendored/skills 复制进 <root>/skills/（增量幂等，见 init.js）。
+ * 运行时 skillPaths 解析「项目 skills/ 优先于包内快照」（server/core/skillPaths.js），
+ * 故只 `npm i cardbuddy@latest` 不会更新工程里的 skills 副本——必须显式拉一次。本命令
+ * 就是为这个场景而生，且**只动 skills/**，绝不碰 .env.cb / package.json / README.md
+ * （那是 `init --force` 的危险面，可能冲掉端口 / FinMall 配置 / AI 网关占位）。
+ *
+ * 四类 diff（内容比对，非 mtime）：
+ *   ADDED    源有、目标无        → 复制（安全）
+ *   SAME     两边内容一致        → 跳过
+ *   MODIFIED 两边都有、内容不同  → 默认跳过 + 黄色警告（覆盖风险：消费者可能改过该 shipped skill）
+ *   ORPHAN   目标有、源无        → 默认保留不删（可能是消费者私有 skill，或上游已下架该 skill）
+ *
+ * 标志：--force 覆盖 MODIFIED；--prune 额外删除 ORPHAN（危险，需显式）；--dry-run 只报告；
+ *       --strict 存在 MODIFIED 且未 --force 时返回非 0（便于 CI 感知未决覆盖）。
+ * 同步后写 skills/.synced-from = 当前装包版本，供下次 drift 检测与启动提示。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import chalk from 'chalk'
+import { loadConfig } from './config.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const SKIP_DIRS = new Set(['node_modules', '__pycache__', '.git', '.local', '.cache', '.history'])
+const SKIP_FILES = new Set(['.DS_Store', 'Thumbs.db'])
+const MARKER = '.synced-from'
+
+function isSkipped(name, isDir) {
+  if (isDir) return SKIP_DIRS.has(name)
+  return SKIP_FILES.has(name) || name.endsWith('.pyc')
+}
+
+function fmtBytes(n) {
+  if (n < 1024) return `${n} B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`
+  return `${(n / 1024 / 1024).toFixed(2)} MB`
+}
+
+/** 当前装包版本：发布态/源码态都读 <pkg>/package.json（dist 与 src 同深度）。 */
+function ownVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8')).version || '*'
+  } catch {
+    return '*'
+  }
+}
+
+function contentEquals(a, b) {
+  try {
+    const sa = fs.statSync(a)
+    const sb = fs.statSync(b)
+    if (sa.size !== sb.size) return false
+    return fs.readFileSync(a).equals(fs.readFileSync(b))
+  } catch {
+    return false
+  }
+}
+
+/** 递归列出 dir 下所有文件（跳过私有/缓存），返回相对 base 的正斜杠路径。 */
+function walkFiles(dir, base = dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fp = path.join(dir, entry.name)
+    if (isSkipped(entry.name, entry.isDirectory())) continue
+    if (entry.isDirectory()) walkFiles(fp, base, out)
+    else if (entry.isFile()) out.push(path.relative(base, fp).split(path.sep).join('/'))
+  }
+  return out
+}
+
+/**
+ * 比对源/目标技能树（内容比对）。
+ * @returns {{ added:string[], same:string[], modified:string[], orphan:string[] }}
+ */
+export function diffSkills(src, dest) {
+  const res = { added: [], same: [], modified: [], orphan: [] }
+  if (fs.existsSync(src)) {
+    for (const rel of walkFiles(src)) {
+      const sp = path.join(src, rel)
+      const dp = path.join(dest, rel)
+      if (!fs.existsSync(dp)) res.added.push(rel)
+      else if (contentEquals(sp, dp)) res.same.push(rel)
+      else res.modified.push(rel)
+    }
+  }
+  if (fs.existsSync(dest)) {
+    for (const rel of walkFiles(dest)) {
+      if (rel === MARKER) continue
+      if (!fs.existsSync(path.join(src, rel))) res.orphan.push(rel)
+    }
+  }
+  return res
+}
+
+/**
+ * 执行 skills 升级。
+ * @param {object} opts
+ * @param {string} [opts.targetDir='.'] 目标工程根（skills 落在 <targetDir>/skills）
+ * @param {boolean} [opts.force] 覆盖本地已修改的 shipped skill
+ * @param {boolean} [opts.dryRun] 只报告不落盘
+ * @param {boolean} [opts.prune] 额外删除包内已不存在的技能文件（默认保留）
+ * @param {boolean} [opts.strict] 存在未覆盖 MODIFIED 时返回非 0
+ * @param {ReturnType<import('./config.js').loadConfig>} [opts.config]
+ * @param {(msg: string) => void} [opts.log]
+ * @returns {Promise<number>} 进程退出码
+ */
+export async function runSkillsUpgrade({
+  targetDir = '.',
+  force = false,
+  dryRun = false,
+  prune = false,
+  strict = false,
+  config,
+  log = (m) => console.log(m),
+} = {}) {
+  const cfg = config || loadConfig()
+  const src = cfg.vendoredSkillsDir
+  const target = path.resolve(targetDir)
+  const destSkills = path.join(target, 'skills')
+
+  const tag = chalk.magenta('▌ ') + chalk.magenta.bold('cardbuddy skills upgrade') + ' '
+  const say = (m) => log(tag + m)
+  const ok = (m) => say(chalk.green(`• ${m}`))
+  const warn = (m) => say(chalk.yellow(`• ${m}`))
+  const dim = (m) => say(chalk.dim(`• ${m}`))
+
+  if (dryRun) say(chalk.yellow('（dry-run：只报告将要做的事，不落盘）'))
+
+  if (!src || !fs.existsSync(src)) {
+    log(chalk.red(`✖ 找不到包内技能库快照：vendoredSkillsDir 缺失（cardbuddy 安装不完整？）`))
+    return 1
+  }
+  if (path.resolve(src) === path.resolve(destSkills)) {
+    dim(`技能库源与目标同路径（${src}），无需升级`)
+    return 0
+  }
+
+  const version = ownVersion()
+  const diff = diffSkills(src, destSkills)
+
+  let copied = 0
+  let bytes = 0
+  let overwritten = 0
+  let deleted = 0
+
+  // ADDED 总是复制；MODIFIED 仅 --force 时复制
+  const toCopy = [...diff.added, ...(force ? diff.modified : [])]
+  for (const rel of toCopy) {
+    const sp = path.join(src, rel)
+    const dp = path.join(destSkills, rel)
+    const isModified = diff.modified.includes(rel)
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(dp), { recursive: true })
+      fs.copyFileSync(sp, dp)
+    }
+    bytes += fs.statSync(sp).size
+    copied++
+    if (isModified) overwritten++
+  }
+
+  // MODIFIED 未 --force：警告（不复制，防丢改动）
+  if (!force && diff.modified.length) {
+    warn(`⚠ 检测到 ${diff.modified.length} 个已修改的技能文件（本地副本与包内不一致），默认不覆盖，避免丢失你的改动：`)
+    for (const rel of diff.modified) say(chalk.yellow(`    ${rel}`))
+    dim('  如需用包内版本覆盖，加 --force；想先看差异，加 --dry-run 后人工对比。')
+  } else if (force && diff.modified.length) {
+    warn(`--force：已用包内版本覆盖 ${diff.modified.length} 个本地修改的技能文件（你的改动将被丢弃）`)
+  }
+
+  // ORPHAN：默认保留；--prune 才删除
+  if (diff.orphan.length) {
+    if (prune) {
+      warn(`⚠ --prune：将删除 ${diff.orphan.length} 个包内已不存在的技能文件（本地私有或上游已下架）：`)
+      for (const rel of diff.orphan) {
+        const dp = path.join(destSkills, rel)
+        say(chalk.yellow(`    ${rel}`))
+        if (!dryRun) {
+          fs.rmSync(dp, { force: true })
+          deleted++
+        }
+      }
+    } else {
+      dim(`${diff.orphan.length} 个本地独有技能文件（包内无对应，可能是你私有的或上游已下架）—— 已保留不删`)
+      if (diff.orphan.length <= 20) for (const rel of diff.orphan) dim(`    ${rel}`)
+      else dim(`    （仅显示前 20，共 ${diff.orphan.length} 个；加 --prune 会删除它们，谨慎）`)
+    }
+  }
+
+  // 写同步标记（best-effort）
+  if (!dryRun) {
+    try {
+      fs.mkdirSync(destSkills, { recursive: true })
+      fs.writeFileSync(path.join(destSkills, MARKER), version + '\n', 'utf8')
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  // 汇总
+  log('')
+  say(chalk.green(dryRun ? 'dry-run 完成（未落盘）' : 'skills 升级完成'))
+  say(chalk.dim(`  源：包内 cardbuddy@${version}`))
+  const targetNote = fs.existsSync(destSkills) ? destSkills : `${destSkills}（将新建）`
+  say(chalk.dim(`  目标：${targetNote}`))
+  say(
+    chalk.dim(
+      `  新增 ${diff.added.length} · 相同 ${diff.same.length} · 覆盖 ${overwritten} · 保留私有 ${diff.orphan.length}` +
+        `${prune ? ` · 删除孤儿 ${deleted}` : ''} · 体积 ${fmtBytes(bytes)}`
+    )
+  )
+
+  if (strict && diff.modified.length && !force) {
+    say(chalk.red('（--strict：存在未覆盖的 MODIFIED 文件，返回非 0）'))
+    return 2
+  }
+  return 0
+}

package/dist/vendored/card-editor/runtime/card-runtime.js

@@ -88,6 +88,9 @@ export function createCardRuntime(rootScopeRaw, adapter) {
   // pushApiCall 只在事件处理器中调用（postMessage / callJSAPI），不在
   // 渲染函数内，直接自增安全，无需 nextTick 延迟。
   const apiRev = reactive({ value: 0 })
+  // apiSeq：接口调用自增序号（模块级单调计数器）。作为每条调用的稳定 id，
+  // 既用于列表 key / 序号展示，也供单条删除按引用精确定位（避免下标在 FIFO 截断后错位）。
+  let apiSeq = 0
   // logRev：事件代码主动日志（console.*）流水版本号。与 apiRev 同理，仅在事件
   // 处理器（用户交互/生命周期动作）中被 pushLog 自增，不在渲染函数内，直接自增安全。
   const logRev = reactive({ value: 0 })
@@ -245,10 +248,19 @@ export function createCardRuntime(rootScopeRaw, adapter) {
       this.scheduleErrorBump()
     },
     pushApiCall(api, payload) {
-      this.apiCalls.push({ api, payload, t: Date.now() })
+      this.apiCalls.push({ api, payload, t: Date.now(), id: ++apiSeq })
       if (this.apiCalls.length > 500) this.apiCalls.shift()
       apiRev.value++
     },
+    /** 单条删除某次接口调用：按 id 精确定位后 splice，并自增 apiRev 触发重渲染。
+     *  不依赖数组下标（FIFO 截断后下标会错位），可直接删除任一历史条目。 */
+    removeApiCall(call) {
+      if (!call || call.id == null) return
+      const i = this.apiCalls.findIndex((x) => x.id === call.id)
+      if (i < 0) return
+      this.apiCalls.splice(i, 1)
+      apiRev.value++
+    },
     addEventListener(name, fn) {
       if (!this.listeners[name]) this.listeners[name] = []
       this.listeners[name].push(fn)

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

@@ -2,9 +2,10 @@ import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { createHash } from 'node:crypto'
 import { writeFile, mkdir } from 'node:fs/promises'
-import { checkPushAllowed } from './cardListCache.js'
+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'
 
 /** finmall-card-sync 的批量同步脚本（同步 / 远端预览共用），相对 skills/ */
@@ -44,6 +45,13 @@ export function createSyncMiddleware({ root }) {
         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 = []

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

@@ -53,7 +53,13 @@ for (const key of ["NO_PROXY", "no_proxy"]) {
 // 仅在 5180 经中间件触发同步时本进程即 server 进程，缓存写入/读取天然一致；
 // 独立 CLI 运行时不写 server 缓存（无推送发生在该进程），故惰性加载、失败静默降级。
 let _cardListCache = null;
+// 由 server/core 上下文注入（跨「仓库内 / 包内 vendored / 消费者工程 skills」三态都能正确定位
+// cardListCache.js，刷新 dev server 进程内单例，供推送前「存在性闸门」使用）。缺省时退回按本文件
+// 位置推导的路径动态 import——该 fallback 仅在脚本物理位于 <repo>/skills/ 时正确，消费者工程下
+// workspace 会指向错误根，故优先用注入。
+let _injectedCardListCache = null;
 async function getCardListCache() {
+  if (_injectedCardListCache) return _injectedCardListCache;
   if (_cardListCache) return _cardListCache;
   try {
     const cachePath = path.resolve(workspace, 'server', 'core', 'cardListCache.js');
@@ -129,7 +135,15 @@ async function finmallPostWithHeal(page, urlPath, requestBody, transCode = urlPa
  * @returns {Promise<{success:boolean, synced:Array, failed:Array, duplicates:Array}>}
  */
 export async function syncCards(opts = {}) {
-  const outRoot = path.resolve(opts.outRoot || path.join(workspace, 'src', 'cards'));
+  // 非注入形态（纯 CLI）用 cwd 作为项目根，跨「仓库内 / 消费者工程」一致；server 中间件始终注入绝对 outRoot。
+  const outRoot = path.resolve(opts.outRoot || path.join(process.cwd(), 'src', 'cards'));
+  // 调用方可注入 cardImportMeta 实现（server/core 上下文，跨「仓库内 / 包内 vendored /
+  // 消费者工程 skills」三态都能正确定位 cardImportMeta.js）。缺省时退回按本文件位置推导的路径动态 import，
+  // 该 fallback 仅在脚本物理位于 <repo>/skills/ 时正确——消费者工程下 workspace 会指向错误根，故优先用注入。
+  const importMeta = opts.importMeta || null;
+  // 调用方可注入 cardListCache 实现（server/core 上下文，跨三态正确定位并刷新进程内单例）。
+  const cardListCacheMod = opts.cardListCache || null;
+  if (cardListCacheMod) _injectedCardListCache = cardListCacheMod;
   const startPage = Number(opts.startPage || 1);
   const startIndex = Number(opts.startIndex || 0);
   const pageSize = Number(opts.pageSize || 24);
@@ -771,6 +785,7 @@ async function syncCard(page, card, { outRoot, appId, workspaceId, summary, sche
     appId,
     workspaceId,
     card,
+    importMeta,
     files: { schema: schemaInfo.size, data: data.size, cover: cover.size },
   });
   return { cover: cover.size, schema: schemaInfo.size, data: data.size };
@@ -826,6 +841,7 @@ async function syncBlankCard(page, card, { cardDir, appId, workspaceId }) {
     appId,
     workspaceId,
     card,
+    importMeta,
     files: { schema: schemaInfo.size, data: dataInfo.size, cover: coverInfo ? coverInfo.size : 0 },
   });
 
@@ -936,11 +952,10 @@ async function findExistingCover(cardDir, id) {
  * 侧车独立于 schema.json/data.json，绝不污染 DSL 产品数据；找不到 server 模块时静默跳过。
  * 空白卡同样写侧车——pageId 已对齐远端 cardId，属于合法的远端来源卡，允许后续推送。
  */
-async function writeImportSidecar(cardDir, { appId, workspaceId, card, files }) {
+async function writeImportSidecar(cardDir, { appId, workspaceId, card, files, importMeta }) {
   try {
-    const metaPath = path.resolve(workspace, 'server', 'core', 'cardImportMeta.js');
-    const { writeImportMeta, buildImportMeta } = await import(pathToFileURL(metaPath).href);
-    const meta = buildImportMeta({
+    const mod = importMeta || (await import(pathToFileURL(path.resolve(workspace, 'server', 'core', 'cardImportMeta.js')).href));
+    const meta = mod.buildImportMeta({
       baseUrl: finmallConfig.baseUrl,
       appId,
       workspaceId,
@@ -949,7 +964,7 @@ async function writeImportSidecar(cardDir, { appId, workspaceId, card, files })
       cardName: card.title,
       files,
     });
-    writeImportMeta(cardDir, meta);
+    mod.writeImportMeta(cardDir, meta);
   } catch (e) {
     log.warn('写导入元数据侧车失败（不影响卡片落盘）', { error: e && e.message });
   }

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

@@ -35,8 +35,9 @@ 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, '..', '..');
+// 项目根：非注入形态（纯 CLI）用 cwd，跨「仓库内 / 消费者工程」一致；server 中间件始终注入绝对 root。
+// 以往按 skills 位置向上跳两级的写法在「npx cardbuddy init」消费者工程下会指向错误根。
+const workspace = process.cwd();
 
 // 统一日志美化（容错：缺 server/core/logger 时回退极简实现，保证脚本可独立运行）。
 let log;
@@ -433,8 +434,9 @@ function rewriteCardRefs(cardFiles, root, mapping) {
  * @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'));
+  // 非注入形态（纯 CLI）用 cwd 作为项目根，跨「仓库内 / 消费者工程」一致；server 中间件始终注入绝对 slicesRoot/cardsRoot。
+  const slicesRoot = path.resolve(opts.slicesRoot || path.join(process.cwd(), 'src', 'slices'));
+  const cardsRoot = path.resolve(opts.cardsRoot || path.join(process.cwd(), 'src', 'cards'));
   const manifestPath = path.join(slicesRoot, MANIFEST_FILE);
   const appId = String(opts.appId || finmallConfig.appId);
   const workspaceId = String(opts.workspaceId || finmallConfig.workspaceId);
@@ -677,8 +679,8 @@ if (isMain) {
     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,
+    slicesRoot: args.slicesRoot ? path.resolve(String(args.slicesRoot)) : undefined,
+    cardsRoot: args.cardsRoot ? path.resolve(String(args.cardsRoot)) : undefined,
   });
   const lines = [
     `目标：sassAppId=${summary.appId} sassWorkspaceId=${summary.workspaceId}${summary.dryRun ? '（dry-run，未上传）' : ''}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cardbuddy",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "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": {