cardbuddy 0.19.0 → 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 */
+        }
+      }
     }
   }