cardbuddy 0.11.0 → 0.12.1

package/README.md

@@ -30,6 +30,37 @@ cardbuddy
 
 ---
 
+## 初始化一个新工程（`cardbuddy init`）
+
+没有现成的卡片工程时，一条命令生成「立刻能开发调试」的最小实例：
+
+```bash
+npx cardbuddy init my-cards     # 目录不存在会自动创建；省略目录名则在当前目录初始化
+cd my-cards
+npm install
+npm run preview                 # 本地服务(8787) + 内置编辑器前端 + 自动开浏览器
+```
+
+生成内容（**增量、幂等**：已存在的文件一律保留，加 `--force` 才覆盖）：
+
+| 产物 | 说明 |
+| --- | --- |
+| `src/cards/` | 卡片目录骨架（后端与编辑器的约定落点） |
+| `src/cards/helloCard/` | 示例卡（`schema.json` + `data.json`，构建期已过校验）——起服务即有卡可看可改 |
+| `skills/` | 随包发布的全量技能库：校验 / 同步 / 保存 / 切图上传 / 建卡管线脚本与工作流文档 |
+| `tools/link-skills.mjs` | `npm run link:skills`：把 `skills/` 链到 Codex / Claude / WorkBuddy 等 AI 工具的项目级技能目录 |
+| `.env.cb` | 共享配置模板（端口、FinMall 远端基址、AI 网关占位；密钥请写 `.env.cb.local`） |
+| `package.json` | 声明 `cardbuddy` 依赖 + `dev` / `start` / `preview` / `link:skills` 脚本 |
+| `.gitignore` | 只追加缺失条目：`node_modules/`、`.env.cb.local`、`.cache/`、`skills/*/.local/` 等 |
+| `README.md` | 上手说明 |
+
+参数：`--force` 覆盖已存在文件 · `--dry-run` 只报告不落盘 · `--no-skills` 不释放技能库（项目已自带）· `--no-sample` 不生成示例卡。
+
+> 本命令取代了 dsl-card 仓库里旧的 `npm run gen:demo`：脚手架随 npm 包发布，无需检出仓库，
+> 且版本天然与所装 `cardbuddy` 一致（旧方案生成的 `demo/` 会随主干漂移）。
+
+---
+
 ## Preview 模式（本地独立调试）
 
 ```bash
@@ -151,14 +182,24 @@ DSL_DEV_HTTPS=1 cardbuddy
 
 ---
 
-## 依赖：FinMall skill
+## 依赖：技能库（skills/）
+
+远端读写与校验类端点（`/__sync` `/__save` `/__preview` `/__validate`）以及 AI 助手的
+`skill_read` / `skill_exec`，都通过动态 `import` / 子进程调用技能脚本：
+
+- `finmall-card-sync`（sync / save / preview / 切图上传）
+- `dsl-card-generator`（validate / autofix / 建卡管线）
+- `finmall-session-navigator`（FinMall 登录会话；凭据落 `skills/finmall-session-navigator/.local/credentials.json`）
 
-远端读写相关端点（`/__sync` `/__save` `/__preview` `/__validate`）通过动态 `import` 调用你项目里的 skill 脚本：
+**解析顺序**（见 `server/core/skillPaths.js`，全后端统一）：
 
-- `finmall-card-sync`（sync / save / preview）
-- `dsl-card-generator`（validate）
+1. `DSL_SKILLS_ROOT` 显式指定；
+2. 项目根 `skills/` —— 跑过 `cardbuddy init` 即有，**推荐**：可写（凭据、审计、缓存都落在项目内）、随项目走；
+3. 包内快照 `dist/vendored/skills/` —— 随 npm 包发布的全量技能库，没跑 `init` 也能只读兜底。
 
-请确保项目根下存在 `skills/finmall-card-sync/scripts/api_batch_sync.mjs` 等，且 `.env.cb` 已配置 `FINMALL_BASE_URL` 等。
+> 远端能力（同步 / 保存 / 切图上传）还需要 `.env.cb` 里的 `FINMALL_BASE_URL` 等配置，
+> 以及 `playwright`（本包 optionalDependency，默认会装）与一次 FinMall 登录。
+> 写入类文件（凭据等）**永远落项目根**，不会写进 `node_modules`。
 
 ---
 

package/dist/cli.js

@@ -14,6 +14,8 @@ import dotenv from 'dotenv'
 import chalk from 'chalk'
 import { startServer } from './standalone.js'
 import { installLogMirror } from './core.js'
+import { loadConfig } from './config.js'
+import { runInit } from './init.js'
 
 // 尽早镜像 stdout/stderr：让启动期日志（配置解析、端口占用提示等）也进入
 // 编辑器底部「服务日志」面板的环形缓冲。幂等，CARDBUDDY_STREAM_LOGS=0 时自动跳过。
@@ -44,12 +46,22 @@ if (args.includes('--help') || args.includes('-h')) {
 
 用法:
   cardbuddy [--preview] [--help]
+  cardbuddy init [目标目录] [--force] [--dry-run] [--no-skills] [--no-sample]
+
+命令:
+  init            生成「立刻能开发调试」的卡片工程最小实例（增量、幂等，不覆盖已存在文件）：
+                    src/cards/ + 示例卡 helloCard + 全量 skills/（校验/同步/建卡管线脚本与文档）
+                    + .env.cb 模板 + package.json + tools/link-skills.mjs + .gitignore + README.md
+                  --force       覆盖已存在的文件
+                  --dry-run     只报告将要做的事，不落盘
+                  --no-skills   不释放技能库（项目已自带 skills/ 时）
+                  --no-sample   不生成示例卡
+                  典型用法：npx cardbuddy init my-cards && cd my-cards && npm i && npm run preview
 
 选项:
   --preview, -p  同时托管打包后的编辑器前端（本地预览），替代线上地址，并自动打开浏览器
                  旧名 --offline / -o 仍可用，已废弃
   --help, -h     显示帮助
-  init            初始化项目骨架：创建 src/cards/ 目录，释放内置技能脚本到 skills/，生成模板 .env.cb
 
 环境变量:
   DSL_CARD_ROOT   卡片仓库根目录（默认 cwd）
@@ -67,6 +79,44 @@ if (args.includes('--help') || args.includes('-h')) {
   process.exit(0)
 }
 
+// 未知子命令：非 flag 的位置参数只有 init 合法（避免 `cardbuddy inti` 静默起服务）
+const subCommand = args.find((a) => !a.startsWith('-'))
+if (subCommand && subCommand !== 'init') {
+  console.error(srcTag + chalk.red(`未知命令：${subCommand}（可用：init；或直接启动服务，见 --help）`))
+  process.exit(1)
+}
+
+// init 子命令：只脚手架，不起服务（端口 / TLS / Vite 全都不碰）。
+// 顶层 await + process.exit：确保脚手架跑完就退出，绝不落到下面的启动路径。
+if (subCommand === 'init') {
+  const rest = args.slice(args.indexOf('init') + 1)
+  const flags = new Set(rest.filter((a) => a.startsWith('-')))
+  const positional = rest.filter((a) => !a.startsWith('-'))
+  if (positional.length > 1) {
+    console.error(srcTag + chalk.red('init 只接受一个目标目录参数（收到：' + positional.join(' ') + '）'))
+    process.exit(1)
+  }
+  const knownFlags = ['--force', '--dry-run', '--no-skills', '--no-sample']
+  const unknown = [...flags].filter((f) => !knownFlags.includes(f))
+  if (unknown.length) {
+    console.error(srcTag + chalk.red(`init 不支持的参数：${unknown.join(' ')}（可用：${knownFlags.join(' ')}）`))
+    process.exit(1)
+  }
+  try {
+    process.exit(await runInit({
+      targetDir: positional[0] || '.',
+      force: flags.has('--force'),
+      dryRun: flags.has('--dry-run'),
+      skipSkills: flags.has('--no-skills'),
+      skipSample: flags.has('--no-sample'),
+      config: loadConfig(),
+    }))
+  } catch (e) {
+    console.error(srcTag + chalk.red('init 失败：') + (e && e.stack ? e.stack : e))
+    process.exit(1)
+  }
+}
+
 const previewFlag = args.includes('--preview') || args.includes('-p')
 const legacyOfflineFlag = args.includes('--offline') || args.includes('-o')
 if (legacyOfflineFlag) {

package/dist/config.js

@@ -15,11 +15,34 @@ import { fileURLToPath } from 'node:url'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
+/**
+ * 取「真实环境变量」的值：排除 cli.js 用 dotenv 从 .env / .env.cb / .env.cb.local 灌进来的那份。
+ * 没有这层区分，工程里 .env.cb 写了 FINMALL_CARD_PORT=8787 时，命令行的
+ * `DSL_DEV_PORT=9000 cardbuddy` 会被文件值静默顶掉（实测踩过）——显式命令行覆盖必须赢。
+ * @param {Record<string,string|undefined>} env
+ * @param {string} key
+ * @returns {string}
+ */
+function realEnvValue(env, key) {
+  const value = env[key]
+  if (value === undefined || value === '') return ''
+  const injected = globalThis.__cardbuddyDotenvInjected
+  return injected && injected[key] === value ? '' : String(value)
+}
+
 export function loadConfig(env = process.env) {
   const root = env.DSL_CARD_ROOT
     ? path.resolve(env.DSL_CARD_ROOT)
     : process.cwd()
-  const port = Number(env.FINMALL_CARD_PORT || env.DSL_DEV_PORT || 8787)
+  // 端口优先级：真实环境变量（DSL_DEV_PORT > FINMALL_CARD_PORT）> .env 文件值
+  // （FINMALL_CARD_PORT > DSL_DEV_PORT，文件层以 FINMALL_CARD_PORT 为单一真值）> 默认 8787。
+  const port = Number(
+    realEnvValue(env, 'DSL_DEV_PORT') ||
+      realEnvValue(env, 'FINMALL_CARD_PORT') ||
+      env.FINMALL_CARD_PORT ||
+      env.DSL_DEV_PORT ||
+      8787
+  )
   const editorUrl = env.EDITOR_URL || 'http://127.0.0.1:5180'
   const https = env.DSL_DEV_HTTPS === '1' || env.DSL_DEV_HTTPS === 'true'
   const token = env.DSL_DEV_TOKEN || ''
@@ -41,9 +64,16 @@ export function loadConfig(env = process.env) {
   // 注入到本进程 env；缺省空串表示不回源（/minio 等只走占位图兜底）。
   const upstream = env.FINMALL_BASE_URL || ''
 
-
-  const repoSkillsDir = path.resolve(process.cwd(), 'skills')
-  const vendoredSkillsDir = path.resolve(__dirname, 'vendored', 'skills')
+  // 包内「迷你仓库快照」根：build.mjs 把 SSR 运行时、server/core、tools、mcp、全量 skills
+  // 按仓库原布局内联到 dist/vendored/ 下，使快照内的相对 import（如 ai-chat.js 的
+  // `../../mcp/tools.mjs`、client.mjs 的 `../server/core/*`）在发布态原样成立。
+  //   - 源码运行（src/cli.js，__dirname=.../src）：指向 .../src/vendored（不存在）→ 全部走仓库回退，
+  //     仓库内开发无需先 build。
+  //   - 发布运行（dist/cli.js，__dirname=.../dist）：指向 .../dist/vendored（build 产出）→ 真正自包含。
+  const vendorRoot = path.resolve(__dirname, 'vendored')
+  const vendoredSkillsDir = path.join(vendorRoot, 'skills')
+  // 项目自身的技能库（跑过 `cardbuddy init` 后由包内快照释放而来）；仓库内开发即 <repo>/skills。
+  const projectSkillsDir = path.join(root, 'skills')
 
   return {
     root,
@@ -56,26 +86,31 @@ export function loadConfig(env = process.env) {
     previewRoot,
     upstream,
     portTakeover,
-    // 包内 vendored 运行时快照（build 阶段从 preview/ 复制到 dist/vendored）：SSR 端点
-    // 所需的编辑器运行时（components/* + runtime/*）全量快照，使发布后无需消费者持有编辑器源码。
-    //   - 源码运行（src/cli.js，__dirname=.../src）：此处指向 .../src/vendored（不存在）→
-    //     走 repoPreviewDir 回退，仓库内开发无需先 build。
-    //   - 发布运行（dist/cli.js，__dirname=.../dist）：此处指向 .../dist/vendored（build 产出）→
-    //     命中 vendored，真正自包含。
-    vendoredRuntimeDir: path.resolve(__dirname, 'vendored'),
+    // 迷你仓库快照根（发布态 = dist/vendored）
+    vendorRoot,
+    // 内嵌 Vite 的 SSR 根：build 阶段按「SSR 模块闭包」从 preview/ 精选复制（components/* +
+    // runtime/* + meta/* + 被引用的少量 assets + api.js），不含编辑器 UI（App.vue / styles /
+    // fidelity）—— 那些只存在于已构建好的 preview-editor 静态产物里。
+    vendoredRuntimeDir: path.join(vendorRoot, 'preview'),
     // 仓库内开发回退：从仓库根运行时（cwd=仓库根）能直接命中 preview/，无需先 build。
     repoPreviewDir: path.resolve(process.cwd(), 'preview'),
-    // 包内 vendored 技能脚本（build 阶段从 skills/ 复制到 dist/vendored/skills）：运行时回退
+    // 包内技能快照（build 阶段从仓库 skills/ 全量内联，排除 .local / node_modules / __pycache__）：
+    // 既是运行时的只读回退，也是 `cardbuddy init` 释放到项目根的源。
     vendoredSkillsDir,
-    // 仓库内 skills/ 目录（开发期直接命中）
-    repoSkillsDir,
+    // 项目自身的 skills/ 目录（开发期即仓库 skills/；消费者项目由 init 释放）
+    projectSkillsDir,
     // 发布态包内自带的预览编辑器构建产物（build.mjs 从 ../../dist 复制到 dist/preview-editor）。
     previewEditorDir: path.resolve(__dirname, 'preview-editor'),
     // 兼容旧包布局（<= 0.5.x 的 dist/offline-editor）：存在时作为回退，避免升级后 --preview 找不到前端。
     legacyOfflineEditorDir: path.resolve(__dirname, 'offline-editor'),
     // 仓库内开发回退：根目录 npm run build 的产物 dist/。
     repoDistDir: path.resolve(process.cwd(), 'dist'),
-    // 技能脚本根目录：优先用户项目 skills/，否则回退包内 vendored
-    skillsRoot: fs.existsSync(repoSkillsDir) ? repoSkillsDir : (fs.existsSync(vendoredSkillsDir) ? vendoredSkillsDir : null),
+    // 技能库根：项目内 skills/ 优先（可写、随项目走），否则回退包内快照（只读）。
+    // 与 server/core/skillPaths.js 的解析顺序一致，供 CLI / init 复用。
+    skillsRoot: fs.existsSync(projectSkillsDir)
+      ? projectSkillsDir
+      : fs.existsSync(vendoredSkillsDir)
+        ? vendoredSkillsDir
+        : null,
   }
 }

package/dist/core.js

@@ -1,2 +1,2 @@
-// 发布态 core 桥：指向 build 阶段内联进 dist/server-core 的中间件（自包含）。
-export * from './server-core/index.js'
+// 发布态 core 桥：指向构建期内联进 dist/vendored/server/core 的中间件（自包含）。
+export * from './vendored/server/core/index.js'