cardbuddy 0.6.0

package/README.md

@@ -0,0 +1,211 @@
+# cardbuddy
+
+本地开发服务（Local Dev Service）—— 把「卡片编辑器平台」的前后端彻底解耦。
+
+编辑器前端是纯静态产物（可部署到任意公网静态托管），而卡片的本地增删查改（同步 / 保存 / 校验 / 渲染自检 / 截图 / 远端取卡）由本服务在**开发者本机**承接。
+
+> 目标：编辑器平台统一维护、统一部署；每位开发者只在本地启动一个 `cardbuddy`，在编辑器「设置 → 本地开发服务」里填好地址，即可立即开发自己的卡片代码。
+
+**公共 npm 包**：[`cardbuddy`](https://www.npmjs.com/package/cardbuddy) —— `npm i -g cardbuddy`（或 `npx cardbuddy`）即可安装使用。
+
+> **改名说明**：本包 `0.6.0` 起由 `cardbuddy-dev` 改名为 **`cardbuddy`**（可执行命令同名）。旧包 `cardbuddy-dev` 已 deprecated —— 仍可安装但不再更新，请改用 `npm i -g cardbuddy`。
+
+---
+
+## 快速开始
+
+```bash
+# 任选其一安装（全局或 npx 均可）
+npm i -g cardbuddy
+# 或
+npx cardbuddy
+
+# 在「卡片代码仓库根目录」下启动：
+cd /path/to/your/card-repo
+cardbuddy
+# → 监听 http://127.0.0.1:8787
+```
+
+启动后，在公网编辑器里打开「设置 → 本地开发服务」，填入 `http://127.0.0.1:8787`，即可跨源调用本机的卡片 CRUD。
+
+---
+
+## Preview 模式（本地独立调试）
+
+```bash
+cardbuddy --preview          # 等价短参 -p
+```
+
+启动后，本地服务在同一个 `8787` 端口同时托管：
+
+- 卡片 CRUD / 校验 / 截图等 `/__xxx` API
+- 打包后的编辑器前端（替代 `https://poc-agent.finmall.com/cardBuddy/index.html`）
+- 自动注入本地 API 地址并打开默认浏览器
+
+> 命名说明：`--preview` 指「本地托管编辑器前端做预览」，与端点 `GET /__preview`（远端取卡）无关。
+
+**前端产物来源优先级：**
+
+1. `DSL_PREVIEW_ROOT` 显式指定目录
+2. npm 包自带的 `dist/preview-editor/`（发布包内置；旧包布局 `dist/offline-editor/` 自动回退）
+3. 当前目录下的 `dist/`（仓库内直接运行源码时）
+
+包内已内置打包好的编辑器前端（`dist/preview-editor/`），因此无需自己构建前端即可使用 `--preview`。
+
+**已废弃别名（仍生效）**：`--offline` / `-o`、`DSL_DEV_OFFLINE=1`、`DSL_OFFLINE_ROOT`、注入全局
+`window.__CARD_DEV_OFFLINE_BASE__`。请把手上的脚本 / CI / demo 换成 preview 名，旧名将在后续版本移除；
+服务端目前会同时注入新旧两个全局名，因此**已构建好的旧 `dist/` 前端仍能被新服务托管**。
+
+---
+
+## 配置（环境变量 / `.env`）
+
+在仓库根目录的 `.env` 中配置，或直接用环境变量：
+
+| 变量 | 默认 | 说明 |
+| --- | --- | --- |
+| `DSL_CARD_ROOT` | 当前目录 (`cwd`) | 卡片代码仓库根（含 `src/cards`）。可用环境变量二次覆盖。 |
+| `DSL_DEV_PORT` | `8787` | 本地服务监听端口。 |
+| `EDITOR_URL` | `http://127.0.0.1:5180` | 截图自访问的编辑器实例地址（默认指向本地编辑器）。写入 `.env` 即可持久化。 |
+| `DSL_DEV_TOKEN` | _(空)_ | 可选鉴权令牌；开启后请求须带 `x-dev-token` 头。默认仅靠 `127.0.0.1` 绑定（不暴露局域网）。 |
+| `DSL_DEV_HTTPS` | `0` | 设为 `1` 启用自签 HTTPS（兜底旧 Safari / 企业策略的混合内容拦截）。 |
+| `DSL_EDITOR_SRC` | _(空)_ | 内核开发用：指向本地编辑器 `preview/` 源码，绕过 vendored 快照调试。 |
+| `DSL_DEV_PREVIEW` | `0` | 设为 `1` 等价于 `--preview`：同端口托管打包后的编辑器前端并自动打开浏览器。 |
+| `DSL_PREVIEW_ROOT` | _(空)_ | 自定义 preview 前端构建产物目录（默认包内 `dist/preview-editor/`，回退 `cwd/dist`）。 |
+
+---
+
+## HTTPS 模式（混合内容兜底）
+
+默认本服务跑在 `http://127.0.0.1:8787`。当公网编辑器是 **HTTPS** 时，浏览器可能因「混合内容（Mixed Content）」或「私有网络访问（PNA）」策略拦截对 `http://127.0.0.1` 的跨源请求。现代 **Chrome / Firefox** 对回环地址（127.0.0.1 / localhost）豁免混合内容，默认即可用；但 **Safari** 等更严格的环境会拦截，此时启用 HTTPS 模式：
+
+```bash
+DSL_DEV_HTTPS=1 cardbuddy
+# → 监听 https://127.0.0.1:8787，证书首次自动生成并缓存到 <root>/.local/dsl-dev-tls/
+```
+
+证书为自签（SAN 覆盖 `localhost` / `127.0.0.1` / `::1`），**不在系统信任链**，首次使用需：
+
+1. 在浏览器手动打开 `https://127.0.0.1:8787/__cards`；
+2. 接受「您的连接不是私密连接」警告（一次性，之后该主机被信任）；
+3. 回到编辑器「设置 → 本地开发服务」，把 Base URL 改为 `https://127.0.0.1:8787` 即可。
+
+> 即便走 HTTP 模式，CORS 层也已回写 `Access-Control-Allow-Private-Network: true`，向前兼容 Chrome 的 PNA 预检。
+
+---
+
+## 端点（与编辑器约定的 `/__xxx`）
+
+| 端点 | 来源 | 说明 |
+| --- | --- | --- |
+| `GET /__cards` | 自包含 | 卡片列表 |
+| `GET /__card/:id` | 自包含 | 单卡 schema/data 读取 |
+| `POST /__sync` | 本地服务代理 | 同步远端 FinMall（依赖 `finmall-card-sync` skill） |
+| `POST /__save` | 本地服务代理 | 保存到远端 FinMall（依赖 `finmall-card-sync` skill） |
+| `GET /__preview` | 本地服务代理 | 远端取卡（IDC10015，依赖 `finmall-card-sync` skill） |
+| `POST /__validate` | 本地服务代理 | 契约校验（依赖 `dsl-card-generator` skill） |
+| `GET /__render-status/:id` | 自包含 + 内嵌 Vite SSR | 渲染自检 |
+| `GET /__node-models/:id` | 自包含 + 内嵌 Vite SSR | 节点 Property 树模型 |
+| `GET /__import-meta/:id` | 自包含 | 导入侧车元数据 |
+| `GET /__history` | 自包含 | 编辑历史 |
+| `GET /__screenshot/:id` | 自包含（需 Playwright + 系统 Chrome）| 无头截图 |
+| `GET /__events` (SSE) | 自包含 | `cards-changed` 实时推送 |
+
+> **FinMall 凭据只在本机**：`/__sync` `/__save` `/__preview` 由本地服务代理 FinMall，凭据存于本机 `skills/finmall-card-sync` 与 `.env.finmall`，公网前端永不接触。
+
+---
+
+## 依赖：FinMall skill
+
+远端读写相关端点（`/__sync` `/__save` `/__preview` `/__validate`）通过动态 `import` 调用你项目里的 skill 脚本：
+
+- `finmall-card-sync`（sync / save / preview）
+- `dsl-card-generator`（validate）
+
+请确保项目根下存在 `skills/finmall-card-sync/scripts/api_batch_sync.mjs` 等，且 `.env.finmall` 已配置 `FINMALL_BASE_URL` 等。
+
+---
+
+## 安全
+
+- 仅绑定 `127.0.0.1`，不暴露局域网。
+- CORS 反射请求 `Origin`（任意公网域名均可跨源调用，无需配置白名单）。
+- 可选 `x-dev-token` 鉴权。
+- HTTPS 自签模式（`DSL_DEV_HTTPS=1`）兜底混合内容拦截（Safari / 严格策略）；Chrome / Firefox 默认 HTTP 即可用。
+
+---
+
+## 本地开发（编辑器 + 本地服务）
+
+本仓库既是「卡片编辑器平台」的源码，也是 `cardbuddy` 的源码。下面说明怎么在本地开发**编辑器本身**（即 `preview/` 前端与 `server/core/` 后端）。
+
+### 关键区别：同域（dev）vs 跨域（生产）
+
+`npm run dev` 能"免费"工作，是因为 `preview/api.js` 的 `resolveApiBase()` 在 `import.meta.env.DEV` 为真时**走同源**（第 3 条回退），而**这条同源路径在生产里不存在**——`build` 产物的 `DEV=false`，生产永远依赖「编辑器配好 8787 地址 + 跨源调用本地服务」。
+
+所以本地开发分两条互补的路径：
+
+| 命令 | 编辑器来源 | 后端来源 | 用途 |
+| --- | --- | --- | --- |
+| `npm run dev` | `preview/` 源码（Vite dev + HMR） | Vite 插件同源挂载（5180） | 日常改编辑器 / 卡片（同域，**不**走生产跨域链路） |
+| `npm run dev:prod` | `dist/` **构建产物**（`vite preview`） | `cardbuddy` 服务（8787） | 部署前权威跨域 smoke test（最贴近生产） |
+| 部署公网 | `dist/` 静态托管（CDN） | 用户本机起 8787 | 生产环境 |
+
+> 已废弃 `dev:full`：它用 dev 源码 + 注入 `VITE_API_BASE` 仿真跨域，但既不贴近生产（非 build 产物），又不如「dev + 设置里启用本地服务」更真实。直接用 `dev:prod`（build 产物 + 8787）做验证即可。
+
+### 模式一：纯同域开发（默认，最常用）
+
+```bash
+npm run dev
+# → Vite dev server 端口 5180（由 .env.finmall 的 FINMALL_DEV_PORT 控制）
+# 浏览器打开 http://localhost:5180
+```
+
+`/__cards` `/__card/:id` `/__render-status` `/__node-models` 等后端端点由 Vite 插件 `server/cardServer.js` **同源挂载**，编辑器前端直接同源调用，无需单独起服务。
+
+### 模式二：开发期顺手看跨域（可选）
+
+不想切到 build 产物、又想在开发时验证跨源？**不用专门脚本**，直接：
+
+```bash
+npm run dev                            # 编辑器 5180（同域，HMR）
+node packages/cardbuddy/src/cli.js # 另起 8787 服务（另开一个终端）
+```
+
+然后在编辑器「设置 → 本地开发服务」里**启用**并填 `http://127.0.0.1:8787`。`resolveApiBase()` 第 2 条（设置启用）优先于 DEV 回退，编辑器立即改走 8787 跨源——这与生产用户操作完全一致，比旧 `dev:full` 注入还真实。
+
+### 模式三：部署前生产级验证（`npm run dev:prod`）
+
+```bash
+npm run dev:prod
+# = npm run build && npm run preview（静态托管 dist/，默认 4173）+ 并行起 8787
+```
+
+打开 `http://localhost:4173`，在「设置 → 本地开发服务」启用并填 `http://127.0.0.1:8787`，即可对 **build 产物** 跑完整的跨源 smoke test（卡片列表 / 画布渲染 / 保存同步 / SSE 实时刷新）。这是部署前最贴近生产的验证；退出 `Ctrl+C` 同时关闭 preview 与 8787。
+
+> `dev:prod` **不注入** `VITE_API_BASE`，因此产出的 `dist/` 是干净的、可直接用于生产部署——跨源地址完全交由设置（与生产一致）。
+
+### 改动即时性（哪些要重启）
+
+| 你改的文件 | `npm run dev` | `npm run dev:prod` |
+| --- | --- | --- |
+| `preview/**`（Vue 组件 / runtime / 样式） | ✅ Vite HMR 即时 | ⚠️ 需重跑 `npm run dev:prod`（build 产物，无 HMR） |
+| `src/cards/*.json`（卡片内容） | ✅ `cards-changed` watcher 自动重载 | ✅ 8787 SSE 推送自动重载 |
+| `server/core/**`（后端中间件） | ⚠️ 需**重启** Vite | ⚠️ 需**重启** 8787 服务 |
+| `vite.config.mjs` / 插件配置 | ⚠️ 需重启 Vite | ⚠️ 需重跑 `npm run dev:prod`（重新 build） |
+
+> 铁律：**改 `server/core/**` 必须重启对应进程**（Node 不会热重载服务端模块），别白等热更新。
+
+### 前置条件
+
+- `.env.finmall` 已存在（含 `FINMALL_BASE_URL` 远端基址、`FINMALL_DEV_PORT`）。缺它编辑器仍能起，只是远端资源代理会告警。
+- 首次跑前先 `npm install`（仓库根）。
+
+### 服务侧单独起（调试 8787 本身）
+
+```bash
+# 仓库内直接跑源码（无需先 build）
+node packages/cardbuddy/src/cli.js
+# 或带 HTTPS 兜底
+DSL_DEV_HTTPS=1 node packages/cardbuddy/src/cli.js
+```

package/dist/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * cardbuddy CLI 入口（npm 包名与可执行命令同为 cardbuddy；0.6.0 前叫 cardbuddy-dev）。
+ *
+ * 读取 cwd 下 .env / .env.finmall / .env.finmall.local（dotenv），启动本地开发服务（127.0.0.1）。
+ * 配置项见 src/config.js（DSL_CARD_ROOT / FINMALL_CARD_PORT / DSL_DEV_PORT /
+ * DSL_DEV_TOKEN / DSL_DEV_HTTPS / EDITOR_URL / DSL_EDITOR_SRC）。
+ *
+ * 端口约定：.env.finmall 的 FINMALL_CARD_PORT 为「卡片开发服务端口」单一真值，
+ * 主仓库由 tools/dev.mjs 把它注入为 DSL_DEV_PORT；此处直接用 FINMALL_CARD_PORT，
+ * 使 demo（直接 npx cardbuddy 或 npm run dev，无启动器注入）也能经 .env.finmall 生效。
+ */
+import dotenv from 'dotenv'
+import chalk from 'chalk'
+import { startServer } from './standalone.js'
+
+// 被 dev.mjs 拉起时让出来源前缀（由启动器带背景色 chip 标注），避免双重来源标签。
+const srcTag =
+  process.env.DSL_LAUNCHER === 'dev'
+    ? ''
+    : chalk.magenta('▌ ') + chalk.magenta.bold('cardbuddy') + ' '
+
+// 加载环境（与 skills 同套约定：.env.finmall 为共享配置，.env.finmall.local 为个人覆盖层）。
+// dotenv 默认不覆盖已存在变量，故主仓库由启动器注入的 DSL_DEV_PORT / FINMALL_BASE_URL 仍优先。
+for (const p of ['.env', '.env.finmall', '.env.finmall.local']) {
+  dotenv.config({ path: p })
+}
+
+const args = process.argv.slice(2)
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`cardbuddy — CardBuddy 本地开发服务
+
+用法:
+  cardbuddy [--preview] [--help]
+
+选项:
+  --preview, -p  同时托管打包后的编辑器前端（本地预览），替代线上地址，并自动打开浏览器
+                 旧名 --offline / -o 仍可用，已废弃
+  --help, -h     显示帮助
+
+环境变量:
+  DSL_CARD_ROOT   卡片仓库根目录（默认 cwd）
+  DSL_DEV_PORT    本地服务端口（默认 8787，兼容 FINMALL_CARD_PORT）
+  DSL_DEV_HTTPS=1 启用自签 HTTPS
+  DSL_DEV_TOKEN   可选鉴权 token
+  DSL_DEV_PREVIEW=1 等价于 --preview
+  DSL_PREVIEW_ROOT  自定义 preview 前端构建产物目录（默认包内 dist/preview-editor，回退 cwd/dist）
+
+已废弃别名（仍生效）：--offline / -o、DSL_DEV_OFFLINE、DSL_OFFLINE_ROOT
+`)
+  process.exit(0)
+}
+
+const previewFlag = args.includes('--preview') || args.includes('-p')
+const legacyOfflineFlag = args.includes('--offline') || args.includes('-o')
+if (legacyOfflineFlag) {
+  console.warn(
+    srcTag + chalk.yellow('⚠ --offline 已废弃，请改用 --preview（本次仍按 preview 模式启动）')
+  )
+}
+// 只在显式给了 flag 时才覆盖配置：无条件传 { preview: false } 会把 DSL_DEV_PREVIEW=1 顶成
+// false —— 旧实现正因如此，环境变量开关一直是失效的。
+startServer(previewFlag || legacyOfflineFlag ? { preview: true } : {})
+  .then(({ shutdown }) => {
+    const stop = async () => {
+      console.log('\n' + srcTag + chalk.cyan('正在关闭…'))
+      await shutdown().catch(() => {})
+      process.exit(0)
+    }
+    process.on('SIGINT', stop)
+    process.on('SIGTERM', stop)
+  })
+  .catch((e) => {
+    console.error(srcTag + chalk.red('启动失败：') + e)
+    process.exit(1)
+  })

package/dist/config.js

@@ -0,0 +1,63 @@
+/**
+ * cardbuddy 配置解析（Phase 0 占位，Phase 1 扩展）。
+ *
+ * 约定：
+ *   - 项目根默认 process.cwd()，可用 DSL_CARD_ROOT 覆盖。
+ *   - 监听端口默认 8787，由 FINMALL_CARD_PORT 控制（.env.finmall 单一真值）；
+ *     兼容旧 DSL_DEV_PORT（主仓库 tools/dev.mjs / prod-preview.mjs 注入）。
+ *     前端 resolveApiBase 的 DEV 默认端口同样读 FINMALL_CARD_PORT，保持三者一致。
+ *   - 编辑器 URL 默认 http://127.0.0.1:5180（EDITOR_URL），供截图使用。
+ *   - 仅绑定 127.0.0.1；token / https 为可选增强。
+ */
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+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)
+  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 || ''
+  const editorSrc = env.DSL_EDITOR_SRC || ''
+  // preview 模式：cardbuddy 同时托管打包后的编辑器前端（替代公网地址）。
+  //   DSL_DEV_PREVIEW=1 / --preview 启动；DSL_PREVIEW_ROOT 可指定任意已构建产物目录。
+  //   旧名 DSL_DEV_OFFLINE / DSL_OFFLINE_ROOT 仍作兼容回退（已废弃，见 README「Preview 模式」）。
+  const truthy = (value) => value === '1' || value === 'true'
+  const preview = truthy(env.DSL_DEV_PREVIEW) || truthy(env.DSL_DEV_OFFLINE)
+  const previewRoot = env.DSL_PREVIEW_ROOT || env.DSL_OFFLINE_ROOT || ''
+  // FinMall 远端站点基址：资源代理（createAssetProxyMiddleware）回源用。
+  // 由 .env.finmall 的 FINMALL_BASE_URL 经启动器（tools/dev.mjs / prod-preview.mjs）
+  // 注入到本进程 env；缺省空串表示不回源（/minio 等只走占位图兜底）。
+  const upstream = env.FINMALL_BASE_URL || ''
+
+  return {
+    root,
+    port,
+    editorUrl,
+    https,
+    token,
+    editorSrc,
+    preview,
+    previewRoot,
+    upstream,
+    // 包内 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'),
+    // 仓库内开发回退：从仓库根运行时（cwd=仓库根）能直接命中 preview/，无需先 build。
+    repoPreviewDir: path.resolve(process.cwd(), 'preview'),
+    // 发布态包内自带的预览编辑器构建产物（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'),
+  }
+}

package/dist/core.js

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