npm - cardbuddy - Versions diffs - 0.6.0 - Mend

cardbuddy 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (167) hide show

package/README.md +211 -0
package/dist/cli.js +76 -0
package/dist/config.js +63 -0
package/dist/core.js +2 -0
package/dist/preview-editor/assets/apple-touch-icon-BQcES9QK.png +0 -0
package/dist/preview-editor/assets/default-image-wzZYQ86K.png +0 -0
package/dist/preview-editor/assets/favicon-16-Cg6Nrosk.png +0 -0
package/dist/preview-editor/assets/favicon-32-B_1744sp.png +0 -0
package/dist/preview-editor/assets/index-BYB0hngG.js +72 -0
package/dist/preview-editor/assets/index-CpBZEQDy.css +1 -0
package/dist/preview-editor/assets/site-icon-CFMif8z4.png +0 -0
package/dist/preview-editor/assets/svg-symbols-B2exBrAr.svg +118 -0
package/dist/preview-editor/index.html +17 -0
package/dist/server-core/_vendor/finmall-env.mjs +96 -0
package/dist/server-core/assetProxy.js +154 -0
package/dist/server-core/bbox.js +153 -0
package/dist/server-core/browser.js +108 -0
package/dist/server-core/buildDataFromSchema.js +50 -0
package/dist/server-core/cardFiles.js +188 -0
package/dist/server-core/cardHistory.js +156 -0
package/dist/server-core/cardImage.js +85 -0
package/dist/server-core/cardImportMeta.js +139 -0
package/dist/server-core/cardListCache.js +68 -0
package/dist/server-core/cardOpenFolder.js +135 -0
package/dist/server-core/cardSave.js +127 -0
package/dist/server-core/cardSidecar.js +72 -0
package/dist/server-core/cardSync.js +259 -0
package/dist/server-core/cardValidate.js +134 -0
package/dist/server-core/index.js +82 -0
package/dist/server-core/logger.js +241 -0
package/dist/server-core/nodeModels.js +52 -0
package/dist/server-core/renderStatus.js +207 -0
package/dist/server-core/screenshot.js +123 -0
package/dist/server-core/sliceStatic.js +44 -0
package/dist/standalone.js +447 -0
package/dist/vendored/App.vue +2330 -0
package/dist/vendored/api.js +142 -0
package/dist/vendored/assets/apple-touch-icon.png +0 -0
package/dist/vendored/assets/default-image.png +0 -0
package/dist/vendored/assets/favicon-16.png +0 -0
package/dist/vendored/assets/favicon-32.png +0 -0
package/dist/vendored/assets/logo.png +0 -0
package/dist/vendored/assets/site-icon.png +0 -0
package/dist/vendored/assets/svg-symbols.svg +118 -0
package/dist/vendored/assets/svgIcons/icons.svg +54 -0
package/dist/vendored/assets/svgIcons/index.js +39 -0
package/dist/vendored/components/AbsoluteLayout.vue +42 -0
package/dist/vendored/components/AlertCardInstance.vue +58 -0
package/dist/vendored/components/AlertCardLayer.vue +59 -0
package/dist/vendored/components/ApiPayloadTree.vue +168 -0
package/dist/vendored/components/AppToast.vue +37 -0
package/dist/vendored/components/Button.vue +37 -0
package/dist/vendored/components/Canvas.vue +65 -0
package/dist/vendored/components/CardGallery.vue +243 -0
package/dist/vendored/components/CardPreview.vue +72 -0
package/dist/vendored/components/CardSelect.vue +200 -0
package/dist/vendored/components/CheckGroup.vue +131 -0
package/dist/vendored/components/Column.vue +25 -0
package/dist/vendored/components/ComponentPalette.vue +294 -0
package/dist/vendored/components/ConfirmDialog.vue +39 -0
package/dist/vendored/components/CustomPlaceholder.vue +33 -0
package/dist/vendored/components/DatePickerOverlay.vue +345 -0
package/dist/vendored/components/DebugPanel.vue +806 -0
package/dist/vendored/components/DeviceOverlay.vue +70 -0
package/dist/vendored/components/Divider.vue +22 -0
package/dist/vendored/components/Dropdown.vue +191 -0
package/dist/vendored/components/EventEditor.vue +247 -0
package/dist/vendored/components/GridLayout.vue +67 -0
package/dist/vendored/components/HoverGuides.vue +122 -0
package/dist/vendored/components/Icon.vue +34 -0
package/dist/vendored/components/Image.vue +34 -0
package/dist/vendored/components/Input.vue +90 -0
package/dist/vendored/components/JsonTree.vue +516 -0
package/dist/vendored/components/ListLayout.vue +68 -0
package/dist/vendored/components/LogValue.vue +51 -0
package/dist/vendored/components/Map.vue +110 -0
package/dist/vendored/components/MultiColumn.vue +49 -0
package/dist/vendored/components/MultiText.vue +58 -0
package/dist/vendored/components/NodeInspector.vue +295 -0
package/dist/vendored/components/PickerOverlay.vue +131 -0
package/dist/vendored/components/ProgressSlider.vue +167 -0
package/dist/vendored/components/PropControl.vue +241 -0
package/dist/vendored/components/PropTree.vue +128 -0
package/dist/vendored/components/RadioButton.vue +74 -0
package/dist/vendored/components/RemotePreview.vue +171 -0
package/dist/vendored/components/RenderTree.vue +437 -0
package/dist/vendored/components/Root.vue +30 -0
package/dist/vendored/components/Row.vue +25 -0
package/dist/vendored/components/SelectionOverlay.vue +105 -0
package/dist/vendored/components/StructureTree.vue +949 -0
package/dist/vendored/components/SvgCode.vue +19 -0
package/dist/vendored/components/SvgSymbols.vue +30 -0
package/dist/vendored/components/Switch.vue +38 -0
package/dist/vendored/components/Text.vue +32 -0
package/dist/vendored/components/Video.vue +70 -0
package/dist/vendored/components/ViewContainer.vue +52 -0
package/dist/vendored/components/base.js +12 -0
package/dist/vendored/components/icons.js +47 -0
package/dist/vendored/components/index.js +58 -0
package/dist/vendored/components/setters/SetBgPosition.vue +64 -0
package/dist/vendored/components/setters/SetBgSize.vue +90 -0
package/dist/vendored/components/setters/SetCode.vue +90 -0
package/dist/vendored/components/setters/SetColor.vue +244 -0
package/dist/vendored/components/setters/SetCustomSelect.vue +58 -0
package/dist/vendored/components/setters/SetExpr.vue +107 -0
package/dist/vendored/components/setters/SetGradient.vue +125 -0
package/dist/vendored/components/setters/SetGrid9.vue +68 -0
package/dist/vendored/components/setters/SetIconSelect.vue +67 -0
package/dist/vendored/components/setters/SetIfForm.vue +61 -0
package/dist/vendored/components/setters/SetImage.vue +43 -0
package/dist/vendored/components/setters/SetList.vue +139 -0
package/dist/vendored/components/setters/SetNumber.vue +118 -0
package/dist/vendored/components/setters/SetNumberStyle.vue +113 -0
package/dist/vendored/components/setters/SetPadding.vue +77 -0
package/dist/vendored/components/setters/SetSegment.vue +160 -0
package/dist/vendored/components/setters/SetSelect.vue +51 -0
package/dist/vendored/components/setters/SetSwitch.vue +49 -0
package/dist/vendored/components/setters/SetText.vue +52 -0
package/dist/vendored/components/setters/props.js +23 -0
package/dist/vendored/fidelity/baseline-messageOverview.json +87 -0
package/dist/vendored/fidelity/calibration.json +29 -0
package/dist/vendored/fidelity/fidelity-messageOverview-after.html +114 -0
package/dist/vendored/fidelity/fidelity-messageOverview-after.json +272 -0
package/dist/vendored/fidelity/fidelity-messageOverview.html +185 -0
package/dist/vendored/fidelity/fidelity-messageOverview.json +336 -0
package/dist/vendored/fidelity/fidelity-messageOverview_v2.html +262 -0
package/dist/vendored/fidelity/fidelity-messageOverview_v2.json +502 -0
package/dist/vendored/fidelity/fidelity-messageOverview_v3.html +201 -0
package/dist/vendored/fidelity/fidelity-messageOverview_v3.json +417 -0
package/dist/vendored/fidelity/fidelity-messageOverview_visual.html +125 -0
package/dist/vendored/fidelity/fidelity-messageOverview_visual.json +338 -0
package/dist/vendored/index.html +16 -0
package/dist/vendored/main.js +36 -0
package/dist/vendored/meta/action-meta.json +141 -0
package/dist/vendored/meta/component-meta.json +2714 -0
package/dist/vendored/meta/directive-meta.json +40 -0
package/dist/vendored/meta/style-meta.json +1086 -0
package/dist/vendored/runtime/StyleParser.js +179 -0
package/dist/vendored/runtime/adapter.js +166 -0
package/dist/vendored/runtime/alert-card.js +125 -0
package/dist/vendored/runtime/app-toast.js +33 -0
package/dist/vendored/runtime/assets.js +16 -0
package/dist/vendored/runtime/canvas-context.js +141 -0
package/dist/vendored/runtime/card-runtime.js +289 -0
package/dist/vendored/runtime/clipboard-node.js +83 -0
package/dist/vendored/runtime/clipboard.js +29 -0
package/dist/vendored/runtime/evaluate.js +152 -0
package/dist/vendored/runtime/event-model.js +300 -0
package/dist/vendored/runtime/hoverGuide.js +31 -0
package/dist/vendored/runtime/jsapi-mock.js +256 -0
package/dist/vendored/runtime/node-model.js +217 -0
package/dist/vendored/runtime/property.js +364 -0
package/dist/vendored/runtime/selectionOverlay.js +53 -0
package/dist/vendored/runtime/toPreview.js +648 -0
package/dist/vendored/standalone-main.js +36 -0
package/dist/vendored/standalone.html +12 -0
package/dist/vendored/styles/app.css +2565 -0
package/dist/vendored/styles/card-gallery.css +234 -0
package/dist/vendored/styles/card-select.css +281 -0
package/dist/vendored/styles/components.css +383 -0
package/dist/vendored/styles/dropdown.css +337 -0
package/dist/vendored/styles/json-tree.css +308 -0
package/dist/vendored/styles/node-inspector.css +1003 -0
package/dist/vendored/styles/setters.css +962 -0
package/dist/vendored/styles/standalone.css +27 -0
package/dist/vendored/styles/structure-tree.css +320 -0
package/package.json +42 -0

package/dist/standalone.js ADDED Viewed

@@ -0,0 +1,447 @@
+/**
+ * cardbuddy 本地开发服务（Phase 1 骨架）。
+ *
+ * 职责：把 dsl-card 后端的卡片增删查改能力从 Vite dev-server 抽离为独立进程——
+ *   监听 127.0.0.1，挂载 server/core 的全部中间件（sync / card / save / validate /
+ *   render-status / node-models / import-meta / screenshot），并提供：
+ *     - 反射 Origin 的 CORS（公网域名/IP 不确定也无妨）
+ *     - 可选 x-dev-token 鉴权（默认仅靠 127.0.0.1 绑定）
+ *     - /__events（SSE）实时推送 cards-changed（替代 Vite HMR）
+ *     - 内嵌 Vite middlewareMode 实例，仅为 render-status / node-models 提供 ssrLoadModule
+ *
+ * 仅绑定 127.0.0.1；FinMall 凭据只在本机，公网前端永不接触。
+ */
+import http from 'node:http'
+import https from 'node:https'
+import path from 'node:path'
+import fs from 'node:fs'
+import { spawn } from 'node:child_process'
+import connect from 'connect'
+import { createServer as createViteServer } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import chokidar from 'chokidar'
+import chalk from 'chalk'
+import { mountCoreMiddlewares } from './core.js'
+import { loadConfig } from './config.js'
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.eot': 'application/vnd.ms-fontobject',
+  '.map': 'application/json; charset=utf-8',
+}
+function decodePathname(url) {
+  if (!url) return '/'
+  const raw = url.split('?')[0]
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    return raw
+  }
+}
+function resolvePreviewRoot(config) {
+  if (config.previewRoot) {
+    const explicit = path.resolve(config.previewRoot)
+    if (fs.existsSync(explicit)) return explicit
+    throw new Error(`DSL_PREVIEW_ROOT 指定的前端构建产物不存在：${explicit}`)
+  }
+  // 发布态优先使用 npm 包内自带的 preview-editor（旧包布局 offline-editor 作兼容回退），
+  // 其次回退到仓库根 dist/（源码运行、未打包内置前端时）。
+  if (fs.existsSync(config.previewEditorDir)) return config.previewEditorDir
+  if (fs.existsSync(config.legacyOfflineEditorDir)) return config.legacyOfflineEditorDir
+  if (fs.existsSync(config.repoDistDir)) return config.repoDistDir
+  throw new Error(
+    '--preview 需要前端构建产物。请先在仓库根运行 `npm run build`，' +
+      '或重新执行 cardbuddy 的 `npm run build` 打包内置前端。'
+  )
+}
+function injectPreviewConfig(html, apiBase) {
+  // 同时注入新旧两个全局名：已构建好的旧 dist/ 前端只认 __CARD_DEV_OFFLINE_BASE__，
+  // 新前端优先读 __CARD_DEV_PREVIEW_BASE__（见 preview/api.js），升级期间两者都能起。
+  const script =
+    `<script>window.__CARD_DEV_PREVIEW_BASE__=${JSON.stringify(apiBase)};` +
+    `window.__CARD_DEV_OFFLINE_BASE__=${JSON.stringify(apiBase)};</script>`
+  if (html.includes('<head>')) return html.replace('<head>', `<head>${script}`)
+  return `${script}${html}`
+}
+function sendFile(res, filePath, { inject = null } = {}) {
+  res.statusCode = 200
+  const ext = path.extname(filePath).toLowerCase()
+  res.setHeader('Content-Type', MIME_TYPES[ext] || 'application/octet-stream')
+  if (path.basename(filePath) === 'index.html') {
+    res.setHeader('Cache-Control', 'no-store')
+  }
+  if (inject !== null) {
+    const html = injectPreviewConfig(fs.readFileSync(filePath, 'utf8'), inject)
+    res.setHeader('Content-Length', Buffer.byteLength(html))
+    res.end(html)
+    return
+  }
+  fs.createReadStream(filePath).pipe(res)
+}
+function createPreviewStaticMiddleware(root, apiBase) {
+  const indexFile = path.join(root, 'index.html')
+  if (!fs.existsSync(indexFile)) {
+    throw new Error(`preview 前端缺少 index.html：${indexFile}`)
+  }
+  return (req, res, next) => {
+    if (req.method !== 'GET' && req.method !== 'HEAD') return next()
+    let pathname = decodePathname(req.url)
+    // 兼容线上 /cardBuddy/index.html 习惯；本地实际按根路径托管 build 产物。
+    if (pathname === '/cardBuddy' || pathname === '/cardBuddy/') pathname = '/'
+    else if (pathname.startsWith('/cardBuddy/')) pathname = pathname.slice('/cardBuddy'.length) || '/'
+    // API/SSE 等内部端点交给后端中间件，不能走 SPA fallback。
+    if (pathname.startsWith('/__')) return next()
+    const relativePath = pathname.replace(/^\/+/, '')
+    let filePath = path.join(root, relativePath)
+    if (!filePath.startsWith(root + path.sep) && filePath !== root) {
+      res.statusCode = 403
+      return res.end('Forbidden')
+    }
+    let stat = null
+    try {
+      stat = fs.statSync(filePath)
+    } catch {
+      stat = null
+    }
+    if (stat?.isDirectory()) {
+      filePath = path.join(filePath, 'index.html')
+      try {
+        stat = fs.statSync(filePath)
+      } catch {
+        stat = null
+      }
+    }
+    if (stat?.isFile()) {
+      if (req.method === 'HEAD') {
+        res.statusCode = 200
+        res.setHeader('Content-Type', MIME_TYPES[path.extname(filePath).toLowerCase()] || 'application/octet-stream')
+        return res.end()
+      }
+      // 所有 HTML 都注入 preview apiBase，避免只在首页注入、路由刷新后丢失。
+      const inject = path.extname(filePath).toLowerCase() === '.html' ? apiBase : null
+      return sendFile(res, filePath, { inject })
+    }
+    // SPA fallback：无扩展名路径返回 index.html；真正的资源 404 交给后续处理。
+    if (!path.extname(pathname)) {
+      if (req.method === 'HEAD') return res.end()
+      return sendFile(res, indexFile, { inject: apiBase })
+    }
+    next()
+  }
+}
+function openBrowser(url) {
+  let command
+  let args
+  if (process.platform === 'darwin') {
+    command = 'open'
+    args = [url]
+  } else if (process.platform === 'win32') {
+    command = 'cmd'
+    args = ['/c', 'start', '', url]
+  } else {
+    command = 'xdg-open'
+    args = [url]
+  }
+  try {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' })
+    child.on('error', () => {})
+    child.unref()
+  } catch {
+    // 自动打开浏览器失败不影响服务启动。
+  }
+}
+/**
+ * 解析嵌入式 Vite 的「运行时根目录」与别名。
+ *
+ * 优先级（决定 SSR 端点 ssrLoadModule('/components/...') 落到哪里）：
+ *   1) DSL_EDITOR_SRC 显式设置 → 用该编辑器源码目录（内核开发 / 调试用）；
+ *   2) 包内 vendoredRuntimeDir 存在 → 用发布快照（默认、消费者场景，无需持有编辑器源码）；
+ *   3) cwd 下存在 preview/ → 仓库内开发回退（无需先 build 编辑器即可起本地服务）；
+ *   4) 兜底 → 仍用 vendored（不存在则由调用方捕获报错，给出明确提示）。
+ *
+ * 无论哪种，都把 `@` 别名指向运行时根，确保内部 `@/runtime/*`、`@/components/*` 解析一致。
+ * @returns {{ root: string, aliasAt: string }}
+ */
+function resolveRuntimeRoot(config) {
+  if (config.editorSrc) {
+    return { root: config.editorSrc, aliasAt: config.editorSrc }
+  }
+  if (fs.existsSync(config.vendoredRuntimeDir)) {
+    return { root: config.vendoredRuntimeDir, aliasAt: config.vendoredRuntimeDir }
+  }
+  if (fs.existsSync(config.repoPreviewDir)) {
+    return { root: config.repoPreviewDir, aliasAt: config.repoPreviewDir }
+  }
+  // 兜底：vendored（即便不存在，createEmbeddedVite 会抛清晰错误）
+  return { root: config.vendoredRuntimeDir, aliasAt: config.vendoredRuntimeDir }
+}
+/** 内嵌 Vite（middlewareMode）只为 SSR 端点提供 ssrLoadModule。 */
+async function createEmbeddedVite(config) {
+  const base = {
+    server: { middlewareMode: true, hmr: false, ws: false },
+    appType: 'custom',
+    logLevel: 'warn',
+  }
+  const { root, aliasAt } = resolveRuntimeRoot(config)
+  // 若运行时根下存在 vite.config（如 DSL_EDITOR_SRC 指向完整仓库 preview），优先复用其配置，
+  // 保证 vue 插件 + 全部别名与编辑器完全一致；否则用最小配置（vue 插件 + @ 别名）。
+  const repoConfig = path.join(root, 'vite.config.mjs')
+  if (fs.existsSync(repoConfig)) {
+    return createViteServer({ configFile: repoConfig, ...base })
+  }
+  return createViteServer({
+    root,
+    configFile: false,
+    plugins: [vue()],
+    resolve: {
+      alias: {
+        '@': aliasAt,
+        // 与仓库 vite.config 对齐：@cards 指向消费者项目根的 src/cards
+        '@cards': path.join(config.root, 'src', 'cards'),
+      },
+    },
+    ...base,
+  })
+}
+/** 反射 Origin 的 CORS + OPTIONS 预检处理。 */
+function corsMiddleware(req, res, next) {
+  const origin = req.headers.origin
+  if (origin) res.setHeader('Access-Control-Allow-Origin', origin)
+  res.setHeader('Access-Control-Allow-Credentials', 'false')
+  res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE,OPTIONS')
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type,x-dev-token')
+  res.setHeader('Access-Control-Expose-Headers', 'Content-Type')
+  // Private Network Access（PNA）预检应答：即便未来 Chrome 对私有/回环地址收紧，
+  // 带上该头可避免 OPTIONS 预检被拒。（回环 127.0.0.1 当前免 PNA，但带上零成本、向前兼容。）
+  res.setHeader('Access-Control-Allow-Private-Network', 'true')
+  if (req.method === 'OPTIONS') {
+    res.statusCode = 204
+    return res.end()
+  }
+  next()
+}
+/** 可选 token 鉴权。 */
+function tokenMiddleware(token) {
+  return (req, res, next) => {
+    if (req.method === 'OPTIONS') return next()
+    if (req.headers['x-dev-token'] !== token) {
+      res.statusCode = 403
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(JSON.stringify({ error: 'invalid x-dev-token' }))
+    }
+    next()
+  }
+}
+/** SSE 端点：订阅者集合 + 推送 helper。 */
+function createEventsEndpoint() {
+  const clients = new Set()
+  const handler = (req, res, next) => {
+    if (!req.url || req.url.split('?')[0] !== '/__events') return next()
+    res.statusCode = 200
+    res.setHeader('Content-Type', 'text/event-stream')
+    res.setHeader('Cache-Control', 'no-cache')
+    res.setHeader('Connection', 'keep-alive')
+    res.flushHeaders?.()
+    res.write('retry: 3000\n\n')
+    const ping = setInterval(() => res.write(': ping\n\n'), 15000)
+    clients.add(res)
+    req.on('close', () => {
+      clearInterval(ping)
+      clients.delete(res)
+    })
+  }
+  const notify = (data) => {
+    const payload = `event: cards-changed\ndata: ${JSON.stringify(data)}\n\n`
+    for (const res of clients) res.write(payload)
+  }
+  return { handler, notify }
+}
+/**
+ * 监听 src/cards 变更并（防抖）推送。
+ *
+ * 用 chokidar 替代裸 fs.watch：Windows 下 fs.watch 的 recursive 递归监听不稳定
+ * （深层子目录改动易漏报、编辑器「临时文件改名覆盖」常漏捕、事件可能丢失文件名），
+ * 而这正是「连接本地开发服务后，外部改文件偶尔不自动刷新」的根因。chokidar 跨平台
+ * 稳定，与 Vite 内置监听同源。保持既有的 120ms 防抖、.history 过滤与
+ * file=relative(root,file) 发送格式不变（前端零改动）。
+ */
+function watchCards(root, notify) {
+  const cardsDir = path.join(root, 'src', 'cards')
+  if (!fs.existsSync(cardsDir)) return
+  let timer = null
+  const onChange = (file) => {
+    if (!file || !file.startsWith(cardsDir) || !/\.json$/.test(file)) return
+    if (file.split(path.sep).includes('.history')) return // 忽略编辑历史快照
+    // 忽略 data.json：它是 schema 的单向派生产物，被写盘时总会随 schema 一起重算，
+    // 若把它当作变更源会重复触发预览重载（且外部直接改 data.json 不应影响系统）。
+    if (path.basename(file) === 'data.json') return
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(() => {
+      timer = null
+      notify({ file: path.relative(root, file) })
+    }, 120)
+  }
+  const watcher = chokidar.watch(cardsDir, {
+    ignoreInitial: true,
+    // 忽略编辑历史快照目录（src/cards/<id>/.history/）：快照落盘会写 .json，
+    // 若触发 cards-changed → 预览自动 loadCard 重载卡片，会丢弃未保存编辑并关闭属性面板。
+    ignored: /(^|[/\\])\.history([/\\]|$)/,
+    depth: Infinity,
+  })
+  watcher.on('add', (f) => onChange(f))
+  watcher.on('change', (f) => onChange(f))
+  watcher.on('unlink', (f) => onChange(f))
+}
+/**
+ * 解析 HTTPS 凭据（DSL_DEV_HTTPS=1 时启用）。
+ *
+ * - 首次生成自签证书（SAN 覆盖 localhost / 127.0.0.1 / ::1），缓存到
+ *   `<root>/.local/dsl-dev-tls/`，后续重启复用（避免每次换指纹、浏览器需反复信任）。
+ * - 自签证书不在系统信任链，浏览器首次访问会告警；用户需在浏览器打开
+ *   `https://127.0.0.1:<port>/__cards` 并接受一次警告，之后编辑器跨源 fetch 即放行。
+ * - 仅 lazy-import selfsigned，HTTP 模式（默认）完全不触碰该依赖。
+ *
+ * @param {ReturnType<typeof loadConfig>} config
+ * @returns {Promise<{ key: string, cert: string } | null>}
+ */
+async function resolveTls(config) {
+  if (!config.https) return null
+  const dir = path.join(config.root, '.local', 'dsl-dev-tls')
+  const keyPath = path.join(dir, 'key.pem')
+  const certPath = path.join(dir, 'cert.pem')
+  if (fs.existsSync(keyPath) && fs.existsSync(certPath)) {
+    return {
+      key: fs.readFileSync(keyPath, 'utf8'),
+      cert: fs.readFileSync(certPath, 'utf8'),
+    }
+  }
+  const selfsigned = (await import('selfsigned')).default
+  const attrs = [
+    { name: 'commonName', value: 'localhost' },
+    { name: 'subjectAltName', value: 'DNS:localhost,IP:127.0.0.1,IP:::1' },
+  ]
+  const pems = selfsigned.generate(attrs, { days: 365, keySize: 2048, algorithm: 'sha256' })
+  fs.mkdirSync(dir, { recursive: true })
+  fs.writeFileSync(keyPath, pems.private)
+  fs.writeFileSync(certPath, pems.cert)
+  return { key: pems.private, cert: pems.cert }
+}
+/**
+ * 启动本地开发服务。
+ * @param {Partial<ReturnType<typeof loadConfig>>} [userConfig]
+ * @returns {Promise<{ server: import('node:http').Server, vite: any, config: object }>}
+ */
+export async function startServer(userConfig = {}) {
+  const config = { ...loadConfig(), ...userConfig }
+  const app = connect()
+  app.use(corsMiddleware)
+  const tls = await resolveTls(config)
+  const scheme = tls ? 'https' : 'http'
+  const apiBase = `${scheme}://127.0.0.1:${config.port}`
+  // preview 页面需要绕过 token（浏览器直接导航无法带 x-dev-token）；API 仍在 token 之后保护。
+  if (config.preview) {
+    const previewRoot = resolvePreviewRoot(config)
+    app.use(createPreviewStaticMiddleware(previewRoot, apiBase))
+  }
+  if (config.token) app.use(tokenMiddleware(config.token))
+  const events = createEventsEndpoint()
+  app.use(events.handler)
+  const vite = await createEmbeddedVite(config)
+  // upstream（FINMALL_BASE_URL）透传给资源代理中间件，使其能回源 FinMall 取站内资源
+  mountCoreMiddlewares(app, { root: config.root, viteServer: vite, upstream: config.upstream })
+  watchCards(config.root, events.notify)
+  const server = tls
+    ? https.createServer(tls, app)
+    : http.createServer(app)
+  await new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(config.port, '127.0.0.1', () => resolve())
+  })
+  const bind = `${scheme}://127.0.0.1:${config.port}`
+  // 被 dev.mjs 拉起时（DSL_LAUNCHER='dev'），来源标签由启动器用带背景色的 chip 标注，
+  // 这里让出前缀避免双重来源标签；直接运行 / dev:prod（stdio:inherit）则自带标签。
+  const srcTag =
+    process.env.DSL_LAUNCHER === 'dev'
+      ? ''
+      : chalk.magenta('▌ ') + chalk.magenta.bold('cardbuddy') + ' '
+  console.log(
+    srcTag +
+      chalk.green(`本地开发服务已启动：${bind}`) +
+      chalk.dim(
+        ` （root=${config.root}，token=${config.token ? 'on' : 'off(仅127.0.0.1)'}）`
+      )
+  )
+  if (tls) {
+    console.log(
+      srcTag +
+        chalk.dim(
+          `自签证书已缓存于 ${path.join(config.root, '.local', 'dsl-dev-tls')}` +
+            ` ；首次使用请先在浏览器打开 ${bind}/__cards 并接受一次安全警告，之后编辑器跨源调用即放行。`
+        )
+    )
+  }
+  if (config.preview) {
+    const previewUrl = `${bind}/`
+    console.log(srcTag + chalk.cyan(`本地预览编辑器已启动：${previewUrl}`) + chalk.dim(' （正在打开浏览器）'))
+    openBrowser(previewUrl)
+  }
+  const shutdown = async () => {
+    server.close()
+    await vite.close().catch(() => {})
+  }
+  return { server, vite, config, shutdown }
+}