cardbuddy 0.19.1 → 0.19.2

package/README.md

@@ -67,6 +67,38 @@ npm run preview                 # 本地服务(8787) + 内置编辑器前端 +
 
 ---
 
+## 升级 cardbuddy 后同步 skills（`cardbuddy skills upgrade`）
+
+`init` 会把技能库复制进工程的 `skills/`；而运行时**项目 `skills/` 优先于包内快照**
+（见 `server/core/skillPaths.js`），所以 `npm i cardbuddy@latest` 只是刷新了包内快照，
+**不会**更新工程里正在用的 `skills/` 副本——必须显式拉一次。本命令就是为这个场景而生，
+且**只动 `skills/`**，绝不碰 `.env.cb` / `package.json` / `README.md`（那得用 `init --force`，有冲配置风险）。
+
+```bash
+npm i cardbuddy@latest
+npx cardbuddy skills upgrade            # 新增的 skill 复制进来；本地改过的 shipped skill 默认跳过并黄色警告
+npx cardbuddy skills upgrade --force    # 确认要抛弃本地改动、用包内版本覆盖时
+npx cardbuddy skills upgrade --dry-run  # 先看会动哪些文件（四类统计，不落盘）
+npx cardbuddy skills upgrade --prune    # 额外删除包内已不存在的技能文件（默认保留，防误删你的私有 skill）
+```
+
+按**内容比对**（非 mtime）分四类处理：
+
+| 分类 | 判定 | 默认行为 | 风险 |
+| --- | --- | --- | --- |
+| `ADDED` | 包内有、本地无 | 复制 | 无（新 skill） |
+| `SAME` | 两边内容一致 | 跳过 | 无 |
+| `MODIFIED` | 两边都有、内容不同 | **跳过 + 黄色警告列清单** | ⚠️ 你可能改过该 shipped skill；`--force` 才覆盖 |
+| `ORPHAN` | 本地有、包内无 | **保留不删** | ⚠️ 可能是你私有的 skill，或上游已下架该 skill；`--prune` 才删 |
+
+> `init` 生成的工程已带 `npm run upgrade:skills` 脚本（等价 `cardbuddy skills upgrade`），
+> 要覆盖时用 `npm run upgrade:skills -- --force`。
+
+同步后写 `skills/.synced-from = 当前装包版本`，供下次 drift 检测（Phase 2：服务启动时可据此提示
+"skills 停留在 X，包已 Y"）。
+
+---
+
 ## Preview 模式（本地独立调试）
 
 ```bash

package/dist/cli.js

@@ -19,6 +19,7 @@ import { startServer } from './standalone.js'
 import { installLogMirror } from './core.js'
 import { loadConfig } from './config.js'
 import { runInit } from './init.js'
+import { runSkillsUpgrade } from './skills-upgrade.js'
 
 const args = process.argv.slice(2)
 const mcpMode = args.includes('--mcp')
@@ -66,6 +67,7 @@ if (args.includes('--help') || args.includes('-h')) {
 用法:
   cardbuddy [--preview] [--mcp] [--version] [--help]
   cardbuddy init [目标目录] [--force] [--dry-run] [--no-skills] [--no-sample]
+  cardbuddy skills upgrade [目标目录] [--force] [--dry-run] [--prune] [--strict]
 
 命令:
   init            生成「立刻能开发调试」的卡片工程最小实例（增量、幂等，不覆盖已存在文件）：
@@ -77,6 +79,20 @@ if (args.includes('--help') || args.includes('-h')) {
                   --no-sample   不生成示例卡
                   典型用法：npx cardbuddy init my-cards && cd my-cards && npm i && npm run preview
 
+  skills upgrade  升级 cardbuddy 包后，把包内最新技能库同步进当前工程的 skills/（增量拉取 skill 更新）：
+                    仅动 skills/，不碰 .env.cb / package.json / README.md（那要用 init --force，有冲配置风险）。
+                    运行时「项目 skills/ 优先于包内快照」，故只 npm i cardbuddy@latest 不会更新工程里的
+                    skills 副本，需显式拉一次。按内容比对分四类：
+                      ADDED    包内有、本地无      → 复制（安全）
+                      SAME     两边一致            → 跳过
+                      MODIFIED 两边都有、内容不同  → 默认跳过并黄色警告（防丢你改过的 shipped skill）
+                      ORPHAN   本地有、包内无      → 默认保留不删（可能是你私有的或上游已下架）
+                  --force      覆盖本地已修改的 shipped skill（丢弃你的改动）
+                  --dry-run    只报告四类统计，不落盘
+                  --prune      额外删除包内已不存在的技能文件（默认保留，防误删你的私有 skill）
+                  --strict     存在未覆盖的 MODIFIED 时返回非 0（便于 CI 感知）
+                  典型用法：npm i cardbuddy@latest && npx cardbuddy skills upgrade
+
 选项:
   --preview, -p  同时托管打包后的编辑器前端（本地预览），替代线上地址，并自动打开浏览器
                  旧名 --offline / -o 仍可用，已废弃
@@ -106,10 +122,12 @@ if (args.includes('--help') || args.includes('-h')) {
   process.exit(0)
 }
 
-// 未知子命令：非 flag 的位置参数只有 init 合法（避免 `cardbuddy inti` 静默起服务）
+// 未知子命令：非 flag 的位置参数只有 init / skills 合法（避免 `cardbuddy inti` 静默起服务）
 const subCommand = args.find((a) => !a.startsWith('-'))
-if (subCommand && subCommand !== 'init') {
-  console.error(srcTag + chalk.red(`未知命令：${subCommand}（可用：init；或直接启动服务，见 --help）`))
+const isSkillsUpgrade =
+  args.includes('upgrade-skills') || (subCommand === 'skills' && args.includes('upgrade'))
+if (subCommand && subCommand !== 'init' && subCommand !== 'skills' && !isSkillsUpgrade) {
+  console.error(srcTag + chalk.red(`未知命令：${subCommand}（可用：init、skills upgrade；或直接启动服务，见 --help）`))
   process.exit(1)
 }
 
@@ -144,6 +162,50 @@ if (subCommand === 'init') {
   }
 }
 
+// skills upgrade 子命令：把已装包内最新技能库同步进当前工程的 skills/（升级包后拉取 skill 更新）。
+// 只动 skills/，不碰 .env.cb / package.json / README.md。支持 `skills upgrade` 与 `upgrade-skills` 两种写法。
+if (isSkillsUpgrade) {
+  const marker = args.includes('upgrade-skills')
+    ? args.indexOf('upgrade-skills')
+    : args.indexOf('upgrade')
+  const rest = args.slice(marker + 1)
+  const flags2 = new Set(rest.filter((a) => a.startsWith('-')))
+  const positional2 = rest.filter((a) => !a.startsWith('-'))
+  const knownFlags = ['--force', '--dry-run', '--prune', '--strict']
+  const unknown = [...flags2].filter((f) => !knownFlags.includes(f))
+  if (unknown.length) {
+    console.error(srcTag + chalk.red(`skills upgrade 不支持的参数：${unknown.join(' ')}（可用：${knownFlags.join(' ')}）`))
+    process.exit(1)
+  }
+  if (positional2.length > 1) {
+    console.error(srcTag + chalk.red('skills upgrade 只接受一个目标目录参数（收到：' + positional2.join(' ') + '）'))
+    process.exit(1)
+  }
+  try {
+    process.exit(
+      await runSkillsUpgrade({
+        targetDir: positional2[0] || '.',
+        force: flags2.has('--force'),
+        dryRun: flags2.has('--dry-run'),
+        prune: flags2.has('--prune'),
+        strict: flags2.has('--strict'),
+        config: loadConfig(),
+      })
+    )
+  } catch (e) {
+    console.error(srcTag + chalk.red('skills upgrade 失败：') + (e && e.stack ? e.stack : e))
+    process.exit(1)
+  }
+}
+
+// 仅 `skills` 而无 upgrade：提示唯一合法子命令
+if (subCommand === 'skills' && !isSkillsUpgrade) {
+  console.error(
+    srcTag + chalk.red('skills 子命令仅支持 upgrade（用法：cardbuddy skills upgrade [目标目录] [--force] [--dry-run] [--prune] [--strict]）')
+  )
+  process.exit(1)
+}
+
 if (mcpMode) {
   // stdio MCP server：不碰端口 / TLS / Vite，由 server.mjs 常驻监听 stdin 直到对端关闭。
   const { startMcpServer } = await import('./mcp.js')

package/dist/init.js

@@ -197,6 +197,21 @@ skills/               AI 协作技能库（校验 / 同步 / 建卡管线脚本
 npm run link:skills   # 交互式选择 Codex / Claude / WorkBuddy 等，建立项目级技能软链
 \`\`\`
 
+## 升级 cardbuddy 后同步 skills
+
+\`cardbuddy init\` 会把技能库复制进本工程的 \`skills/\`，而运行时**项目 skills/ 优先于包内快照**
+（见 \`server/core/skillPaths.js\`），所以只 \`npm i cardbuddy@latest\` 不会更新工程里的 skills 副本。
+装完新版后拉一次：
+
+\`\`\`bash
+npm run upgrade:skills            # 新增的 skill 复制进来；本地改过的 shipped skill 默认跳过并警告
+npx cardbuddy skills upgrade --force   # 确认要抛弃本地改动、用包内版本覆盖时
+npx cardbuddy skills upgrade --dry-run # 先看会动哪些文件（四类：新增/相同/已修改/本地私有）
+\`\`\`
+
+该命令**只动 \`skills/\`**，绝不碰 \`.env.cb\` / \`package.json\` / \`README.md\`
+（那得用 \`init --force\`，有冲掉端口 / FinMall 配置 / AI 网关占位的风险）。
+
 ## 把卡片工具挂给外部 AI agent（MCP，可选）
 
 编辑器内置的网页 AI 助手走 \`POST /__ai/chat\`。若要让 Codex / Claude 这类**外部** agent
@@ -259,6 +274,10 @@ function projectPackageJson(projectName, version) {
           // 因为 `npm run` 的横幅会打到 stdout、污染 JSON-RPC 协议流（详见生成的 README）。
           mcp: 'cardbuddy --mcp',
           'link:skills': 'node tools/link-skills.mjs',
+          // 升级 cardbuddy 后，把包内最新技能库同步进本工程的 skills/（仅动 skills/，
+          // 不碰 .env.cb / package.json / README.md；本地改过的 shipped skill 默认跳过并警告，
+          // 确认要抛弃改动时加 -- --force）。
+          'upgrade:skills': 'cardbuddy skills upgrade',
         },
         devDependencies: {
           cardbuddy: `^${version}`,
@@ -397,6 +416,14 @@ export async function runInit({
           chalk.dim(`（新增 ${stat.copied} 文件 / ${fmtBytes(stat.bytes)}，保留已存在 ${stat.skipped} 个${force ? '，--force 覆盖' : ''}）`)
       )
       if (names.length) say(chalk.dim(`  ${names.join('、')}`))
+      // 写同步标记（best-effort）：记录本次 init 基于的 cardbuddy 版本，供 `skills upgrade` 做 drift 检测
+      if (!dryRun && fs.existsSync(dest)) {
+        try {
+          fs.writeFileSync(path.join(dest, '.synced-from'), ownVersion() + '\n', 'utf8')
+        } catch {
+          /* best-effort */
+        }
+      }
     }
   }
 

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/package.json

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