cardbuddy 0.12.1 → 0.13.0

package/README.md

@@ -59,6 +59,12 @@ npm run preview                 # 本地服务(8787) + 内置编辑器前端 +
 > 本命令取代了 dsl-card 仓库里旧的 `npm run gen:demo`：脚手架随 npm 包发布，无需检出仓库，
 > 且版本天然与所装 `cardbuddy` 一致（旧方案生成的 `demo/` 会随主干漂移）。
 
+> ⚠️ **`npx cardbuddy init` 卡住不退、目录里只多了个 `.cache/`？** 本机装着 0.12.0 之前的
+> 全局旧版：`npx` 优先命中全局 bin，而旧版没有 `init` 子命令，会把 `init` 当无关参数忽略、
+> 转而启动常驻开发服务（于是既不退、也不脚手架）。用 `npm ls -g cardbuddy` 核对版本，
+> 再 `npm i -g cardbuddy@latest` 升级，或 `npm uninstall -g cardbuddy` 让 npx 每次自行拉取。
+> 0.12.0 起 CLI 对未知子命令会直接报错退出，不再静默起服务。
+
 ---
 
 ## Preview 模式（本地独立调试）
@@ -89,6 +95,58 @@ cardbuddy --preview          # 等价短参 -p
 
 ---
 
+## MCP：把 `card_*` 工具挂给外部 AI agent
+
+```bash
+cardbuddy --mcp        # stdio JSON-RPC 2.0；不启 HTTP 服务、不占端口
+```
+
+编辑器内置的网页 AI 助手走 `POST /__ai/chat`；`--mcp` 把**同一套** 16 个 `card_*` 工具
+（实现同为 `mcp/tools.mjs` + `mcp/client.mjs`，不存在第二份契约逻辑）以 stdio 暴露给
+Codex / Claude 这类外部 agent。工具清单与用法见 `skills/dsl-card-ai/SKILL.md`。
+
+agent 侧配置（`cwd` 必须是卡片工程根，读写才落在 `src/cards/`）：
+
+```jsonc
+{
+  "mcpServers": {
+    "dsl-card": {
+      "command": "<工程绝对路径>/node_modules/.bin/cardbuddy",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+> **stdout 是协议信道。** 经 `npm run` 调用必须加 `--silent`：`npm run mcp` 会把
+> `> 包名 脚本名` 横幅打到 stdout，多一行客户端就解析失败；直接调
+> `node_modules/.bin/cardbuddy --mcp` 无此问题。诊断一律走 stderr 且默认静默，
+> `CARDBUDDY_MCP_VERBOSE=1` 打开（会打出注入后的 `root=` / `apiBase=`）。
+
+`cardbuddy init` 生成的工程已带 `npm run mcp` 脚本。回归见 `tools/tests/cardbuddy-mcp.test.mjs`。
+
+### 工具对本地服务的依赖分档
+
+`--mcp` 自己不启服务。启动时自动注入 `CARD_ROOT=<工程根>` 与
+`CARD_API_BASE=http(s)://127.0.0.1:<端口>`（端口取 `FINMALL_CARD_PORT` / `DSL_DEV_PORT`，默认
+8787；已有同名环境变量时不覆盖），工具据此决定走 HTTP 还是本地降级：
+
+| 档 | 工具 |
+| --- | --- |
+| 纯本地，从不需要服务 | `card_route_input` `card_scaffold` `card_add_component` |
+| 优先服务，连不上自动降级为直接读写盘（`validate` 跑 Python 校验器） | `card_list` `card_read` `card_write` `card_validate` `card_history` `card_rollback` |
+| 优先服务，降级到包内独立离线渲染器 | `card_screenshot` |
+| **必须**另起一个 `cardbuddy` | `card_render_status` `card_node_models` `card_import_meta` |
+| **必须**另起服务 **且**已登录 FinMall | `card_sync` `card_save` `card_slice_upload` |
+
+> **别直接跑包内 `dist/vendored/mcp/server.mjs`。** `mcp/client.mjs` 在**模块顶层**就 resolve
+> `CARD_ROOT` / `CARD_API_BASE`（不是每次调用时读），绕过 CLI 包装层时前者会落到包内快照目录
+> （`card_list` 返回 0 张卡）、后者回退 `devApiBase()` 的 5180（消费者工程没有 Vite 把 `/__*`
+> 代理到 8787，`card_render_status` 直接 `dev-server-required`）。仓库内跑源码时入口回退
+> `<repo>/mcp/server.mjs`，无需先 build。
+
+---
+
 ## 配置（环境变量 / `.env`）
 
 在仓库根目录的 `.env` 中配置，或直接用环境变量：
@@ -101,7 +159,7 @@ cardbuddy --preview          # 等价短参 -p
 | `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_EDITOR_SRC` | _(空)_ | 内核开发用：指向本地编辑器 `card-editor/` 源码，绕过 vendored 快照调试。 |
 | `DSL_DEV_PREVIEW` | `0` | 设为 `1` 等价于 `--preview`：同端口托管打包后的编辑器前端并自动打开浏览器。 |
 | `DSL_PREVIEW_ROOT` | _(空)_ | 自定义 preview 前端构建产物目录（默认包内 `dist/preview-editor/`，回退 `cwd/dist`）。 |
 | `DSL_EDITOR_CMD` | _(空)_ | 代码桥外部编辑器命令（如 `code` / `cursor` / 带参数整串），按 shell 语义执行并追加临时文件路径；缺省按平台拉起 VSCode（mac `open -a`、win `cmd /s /c "code"`、linux `code`），CLI 缺失再回退 `vscode://` 协议。 |
@@ -214,17 +272,17 @@ DSL_DEV_HTTPS=1 cardbuddy
 
 ## 本地开发（编辑器 + 本地服务）
 
-本仓库既是「卡片编辑器平台」的源码，也是 `cardbuddy` 的源码。下面说明怎么在本地开发**编辑器本身**（即 `preview/` 前端与 `server/core/` 后端）。
+本仓库既是「卡片编辑器平台」的源码，也是 `cardbuddy` 的源码。下面说明怎么在本地开发**编辑器本身**（即 `card-editor/` 前端与 `server/core/` 后端）。
 
 ### 关键区别：同域（dev）vs 跨域（生产）
 
-`npm run dev` 能"免费"工作，是因为 `preview/api.js` 的 `resolveApiBase()` 在 `import.meta.env.DEV` 为真时**走同源**（第 3 条回退），而**这条同源路径在生产里不存在**——`build` 产物的 `DEV=false`，生产永远依赖「编辑器配好 8787 地址 + 跨源调用本地服务」。
+`npm run dev` 能"免费"工作，是因为 `card-editor/api.js` 的 `resolveApiBase()` 在 `import.meta.env.DEV` 为真时**走同源**（第 3 条回退），而**这条同源路径在生产里不存在**——`build` 产物的 `DEV=false`，生产永远依赖「编辑器配好 8787 地址 + 跨源调用本地服务」。
 
 所以本地开发分两条互补的路径：
 
 | 命令 | 编辑器来源 | 后端来源 | 用途 |
 | --- | --- | --- | --- |
-| `npm run dev` | `preview/` 源码（Vite dev + HMR，5180） | `cardbuddy` 服务（8787，由 `tools/dev.mjs` 同起） | 日常改编辑器 / 卡片 |
+| `npm run dev` | `card-editor/` 源码（Vite dev + HMR，5180） | `cardbuddy` 服务（8787，由 `tools/dev.mjs` 同起） | 日常改编辑器 / 卡片 |
 | `npm run dev:prod` | `dist/` **构建产物**（`vite preview`） | `cardbuddy` 服务（8787） | 部署前权威跨域 smoke test（最贴近生产） |
 | 部署公网 | `dist/` 静态托管（CDN） | 用户本机起 8787 | 生产环境 |
 
@@ -266,7 +324,7 @@ npm run dev:prod
 
 | 你改的文件 | `npm run dev` | `npm run dev:prod` |
 | --- | --- | --- |
-| `preview/**`（Vue 组件 / runtime / 样式） | ✅ Vite HMR 即时 | ⚠️ 需重跑 `npm run dev:prod`（build 产物，无 HMR） |
+| `card-editor/**`（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） |

package/dist/cli.js

@@ -17,9 +17,14 @@ import { installLogMirror } from './core.js'
 import { loadConfig } from './config.js'
 import { runInit } from './init.js'
 
+const args = process.argv.slice(2)
+const mcpMode = args.includes('--mcp')
+
 // 尽早镜像 stdout/stderr：让启动期日志（配置解析、端口占用提示等）也进入
 // 编辑器底部「服务日志」面板的环形缓冲。幂等，CARDBUDDY_STREAM_LOGS=0 时自动跳过。
-installLogMirror()
+// --mcp 下整个跳过：该模式不启 HTTP 服务，/__logs 没有消费者，让镜像去逐帧拦截
+// JSON-RPC 报文纯属白做功；协议信道的纯净由「这条路径上不打日志」保证（见 src/mcp.js）。
+if (!mcpMode) installLogMirror()
 
 // 被 dev.mjs 拉起时让出来源前缀（由启动器带背景色 chip 标注），避免双重来源标签。
 const srcTag =
@@ -40,12 +45,11 @@ for (const p of ['.env', '.env.cb', '.env.cb.local']) {
   }
 }
 
-const args = process.argv.slice(2)
 if (args.includes('--help') || args.includes('-h')) {
   console.log(`cardbuddy — CardBuddy 本地开发服务
 
 用法:
-  cardbuddy [--preview] [--help]
+  cardbuddy [--preview] [--mcp] [--help]
   cardbuddy init [目标目录] [--force] [--dry-run] [--no-skills] [--no-sample]
 
 命令:
@@ -61,6 +65,13 @@ if (args.includes('--help') || args.includes('-h')) {
 选项:
   --preview, -p  同时托管打包后的编辑器前端（本地预览），替代线上地址，并自动打开浏览器
                  旧名 --offline / -o 仍可用，已废弃
+  --mcp          以 stdio 起 MCP server（JSON-RPC 2.0），把 16 个 card_* 工具挂给 Codex / Claude
+                 等外部 agent；不启 HTTP 服务、不占端口。stdout 只走协议（经 npm run 调用要加
+                 --silent，否则横幅污染协议流），诊断走 stderr（CARDBUDDY_MCP_VERBOSE=1 打开）。
+                 本命令自身不起服务，工具按依赖分档：route_input / scaffold / add_component 纯本地；
+                 list / read / write / validate / history / rollback 降级为直接读写盘；screenshot
+                 降级到包内离线渲染器；render_status / node_models / import_meta 必须另起一个
+                 cardbuddy；sync / save / slice_upload 还必须已登录 FinMall。
   --help, -h     显示帮助
 
 环境变量:
@@ -117,26 +128,32 @@ if (subCommand === 'init') {
   }
 }
 
-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 模式启动）')
-  )
+if (mcpMode) {
+  // stdio MCP server：不碰端口 / TLS / Vite，由 server.mjs 常驻监听 stdin 直到对端关闭。
+  const { startMcpServer } = await import('./mcp.js')
+  await startMcpServer(loadConfig())
+} else {
+  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)
+    })
 }
-// 只在显式给了 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

@@ -88,12 +88,18 @@ export function loadConfig(env = process.env) {
     portTakeover,
     // 迷你仓库快照根（发布态 = dist/vendored）
     vendorRoot,
-    // 内嵌 Vite 的 SSR 根：build 阶段按「SSR 模块闭包」从 preview/ 精选复制（components/* +
+    // 内嵌 Vite 的 SSR 根：build 阶段按「SSR 模块闭包」从 card-editor/ 精选复制（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'),
+    vendoredRuntimeDir: path.join(vendorRoot, 'card-editor'),
+    // 仓库内开发回退：从仓库根运行时（cwd=仓库根）能直接命中 card-editor/，无需先 build。
+    repoEditorDir: path.resolve(process.cwd(), 'card-editor'),
+    // MCP stdio server 入口（`cardbuddy --mcp`）：发布态命中包内快照 vendored/mcp/server.mjs；
+    // 仓库内跑源码时 src/vendored 不存在，回退到 <repo>/mcp/server.mjs —— src 与 dist 同深度，
+    // 故 __dirname 相对路径在两种情形下都对（不像 root 那样依赖 cwd）。
+    mcpServerEntry: fs.existsSync(path.join(vendorRoot, 'mcp', 'server.mjs'))
+      ? path.join(vendorRoot, 'mcp', 'server.mjs')
+      : path.resolve(__dirname, '../../../mcp/server.mjs'),
     // 包内技能快照（build 阶段从仓库 skills/ 全量内联，排除 .local / node_modules / __pycache__）：
     // 既是运行时的只读回退，也是 `cardbuddy init` 释放到项目根的源。
     vendoredSkillsDir,

package/dist/init.js

@@ -9,7 +9,7 @@
  *                             释放后既跑得快也写得了（FinMall 凭据落在项目内，不进 node_modules）
  *   tools/link-skills.mjs     把 skills/ 链到 Codex / Claude / WorkBuddy 等 AI 工具的项目级技能目录
  *   .env.cb                   共享配置模板（端口 / 远端基址 / AI 网关占位；密钥写 .env.cb.local）
- *   package.json              声明 cardbuddy 依赖与 dev / preview / link:skills 脚本
+ *   package.json              声明 cardbuddy 依赖与 dev / preview / mcp / link:skills 脚本
  *   .gitignore                私密层与产物不入库
  *   README.md                 上手说明
  *
@@ -188,6 +188,43 @@ skills/               AI 协作技能库（校验 / 同步 / 建卡管线脚本
 npm run link:skills   # 交互式选择 Codex / Claude / WorkBuddy 等，建立项目级技能软链
 \`\`\`
 
+## 把卡片工具挂给外部 AI agent（MCP，可选）
+
+编辑器内置的网页 AI 助手走 \`POST /__ai/chat\`。若要让 Codex / Claude 这类**外部** agent
+直接操作卡片，用随包提供的 MCP stdio server（16 个 \`card_*\` 工具，清单见
+\`skills/dsl-card-ai/SKILL.md\`）：
+
+\`\`\`jsonc
+// agent 的 MCP 配置；cwd 必须是本工程根，卡片读写才落在 src/cards/
+{
+  "mcpServers": {
+    "dsl-card": {
+      "command": "<本工程绝对路径>/node_modules/.bin/cardbuddy",
+      "args": ["--mcp"]
+    }
+  }
+}
+\`\`\`
+
+也可用 \`npm run --silent mcp\`。**\`--silent\` 不能省**：\`npm run\` 会把
+\`> 包名 脚本名\` 横幅打到 **stdout**，而 stdout 是 JSON-RPC 协议信道，多一行就让客户端解析失败。
+
+\`--mcp\` 自身不启服务、不占端口，工具按对本地服务的依赖分档：
+
+| 档 | 工具 |
+| --- | --- |
+| 纯本地，从不需要服务 | \`card_route_input\` \`card_scaffold\` \`card_add_component\` |
+| 优先服务，连不上自动降级为直接读写盘（\`validate\` 跑 Python 校验器） | \`card_list\` \`card_read\` \`card_write\` \`card_validate\` \`card_history\` \`card_rollback\` |
+| 优先服务，降级到包内独立离线渲染器 | \`card_screenshot\` |
+| **必须**另起一个 \`npm run dev\` | \`card_render_status\` \`card_node_models\` \`card_import_meta\` |
+| **必须**另起服务 **且**已登录 FinMall | \`card_sync\` \`card_save\` \`card_slice_upload\` |
+
+\`--mcp\` 会自动把 \`CARD_ROOT\` 指到本工程根、\`CARD_API_BASE\` 指到 \`.env.cb\` 的
+\`FINMALL_CARD_PORT\`（默认 8787）。**别直接跑包内 \`vendored/mcp/server.mjs\`**：那样
+\`CARD_ROOT\` 会落到 node_modules 里的快照目录（\`card_list\` 返回 0 张卡），端口也回退到
+5180（\`card_render_status\` 直接报 \`dev-server-required\`）。排查时可设
+\`CARDBUDDY_MCP_VERBOSE=1\` 让启动信息打到 stderr。
+
 ## FinMall 远端能力（可选）
 
 同步 / 保存 / 切图上传需要已登录的 FinMall 会话与 \`playwright\`
@@ -208,6 +245,10 @@ function projectPackageJson(projectName, version) {
           dev: 'cardbuddy',
           start: 'cardbuddy',
           preview: 'cardbuddy --preview',
+          // 给外部 agent（Codex / Claude）挂 card_* 工具的 stdio MCP server。
+          // 注意：MCP 客户端要走 `npm run --silent mcp` 或直接调 node_modules/.bin/cardbuddy --mcp，
+          // 因为 `npm run` 的横幅会打到 stdout、污染 JSON-RPC 协议流（详见生成的 README）。
+          mcp: 'cardbuddy --mcp',
           'link:skills': 'node tools/link-skills.mjs',
         },
         devDependencies: {
@@ -382,7 +423,7 @@ export async function runInit({
   const pkgState = writeFileSafe(path.join(target, 'package.json'), projectPackageJson(projectName, version), opts)
   pkgState === 'skipped'
     ? dim('package.json 已存在（跳过，--force 可覆盖）')
-    : ok(`${dryRun ? '将生成' : '已生成'} package.json（cardbuddy ^${version} + dev / preview / link:skills 脚本）`)
+    : ok(`${dryRun ? '将生成' : '已生成'} package.json（cardbuddy ^${version} + dev / preview / mcp / link:skills 脚本）`)
 
   // 6) tools/link-skills.mjs（把 skills/ 链给 AI 工具）
   const linkSrc = resolveLinkSkillsSource(config)

package/dist/mcp.js

@@ -0,0 +1,54 @@
+/**
+ * `cardbuddy --mcp` —— 以 stdio 起 MCP server（JSON-RPC 2.0，newline-delimited）。
+ *
+ * 为什么要有它：包内快照早就带了 mcp/tools.mjs + client.mjs（AI 工具调度的实现真身），
+ * 却没带 server.mjs 这个 stdio 入口 —— 于是消费者工程只能用编辑器内置的网页 AI 助手
+ * （/__ai/chat），没法把同一套 card_* 工具挂给 Codex / Claude 这类外部 agent。而随包释放的
+ * dsl-card-ai 技能整篇是以「只调 dsl-card MCP 工具、绝不重实现契约逻辑」为前提写的，
+ * 缺了入口那份技能在消费者工程里就落不了地。
+ *
+ * 两个必须守住的前提：
+ *   1. **stdout 是协议信道**，多一行非 JSON 就让客户端解析失败（`npm run` 的 `> 包名 脚本名`
+ *      横幅正是典型污染源，故推荐 `.bin/cardbuddy --mcp` 或 `npm run --silent mcp`）。这条路径
+ *      上因此一律不打日志：cli.js 跳过 installLogMirror()（该镜像服务于编辑器「服务日志」面板，
+ *      MCP 模式没有 HTTP 服务、/__logs 无消费者），启动诊断只走 stderr 且默认静默。
+ *   2. **CARD_ROOT / CARD_API_BASE 必须在 import 之前落定**。mcp/client.mjs 在模块顶层
+ *      就读这两个变量（不是每次调用时读），晚一步注入就无效：
+ *        - CARD_ROOT 不给，client 会把「mcp/ 的上一级」当工程根 —— 发布态那是包内快照目录，
+ *          根本找不到 src/cards；
+ *        - CARD_API_BASE 不给，client 回退 devApiBase() 即 5180（仓库里由 Vite 把 /__* 代理到
+ *          8787），而消费者工程通常只有 cardbuddy 的 8787、没有 Vite，于是连不上，
+ *          且 render_status / sync / save 这三个不支持离线降级的工具直接不可用。
+ *
+ * 本地服务没起也能用一部分：client.mjs 对 list / read / write / validate 有「直接读盘 + 跑
+ * Python 校验器」的离线降级；render_status / sync / save 依赖服务与 FinMall 登录态，不降级。
+ */
+import fs from 'node:fs'
+import { pathToFileURL } from 'node:url'
+
+/** 启动信息只在对 stderr 可见时才打（交互式调试）；被 MCP 客户端接管时保持静默。 */
+function diag(line) {
+  if (process.stderr.isTTY || process.env.CARDBUDDY_MCP_VERBOSE === '1') {
+    process.stderr.write(`[cardbuddy --mcp] ${line}\n`)
+  }
+}
+
+/**
+ * @param {ReturnType<import('./config.js').loadConfig>} config
+ * @returns {Promise<void>} 解析后 server.mjs 自行常驻监听 stdin，本函数不返回直到进程结束
+ */
+export async function startMcpServer(config) {
+  const entry = config.mcpServerEntry
+  if (!entry || !fs.existsSync(entry)) {
+    // 走 stderr + 非 0 退出：MCP 客户端会把它显示成 server 启动失败，而不是静默挂着
+    process.stderr.write(`[cardbuddy --mcp] 找不到 MCP server 入口：${entry || '(未解析)'}\n`)
+    process.exit(1)
+  }
+  if (!process.env.CARD_ROOT) process.env.CARD_ROOT = config.root
+  if (!process.env.CARD_API_BASE) {
+    process.env.CARD_API_BASE = `${config.https ? 'https' : 'http'}://127.0.0.1:${config.port}`
+  }
+  diag(`root=${process.env.CARD_ROOT}`)
+  diag(`apiBase=${process.env.CARD_API_BASE}（本地服务未起时 list/read/write/validate 自动降级为直接读盘）`)
+  await import(pathToFileURL(entry).href)
+}