cardbuddy 0.6.0 → 0.8.0

package/dist/server-core/codeBridge.js

@@ -0,0 +1,359 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { spawn } from 'node:child_process'
+import { log } from './logger.js'
+
+/**
+ * 外部编辑器代码桥（VSCode / DSL_EDITOR_CMD 指定的任意编辑器，如 cursor）。
+ *
+ * 闭环：
+ *   1) 前端 POST /__code-bridge { code, label } → 后端在 os.tmpdir()/cardbuddy-code-bridge/
+ *      下写 <session>.js 并拉起编辑器，返回 { id, file }；
+ *   2) 后端 chokidar 单文件监听：保存事件防抖 + 内容哈希去重（忽略服务端自写回声），
+ *      有实质变化经 SSE 推 code-bridge-changed { id }（内容走 GET 拉取，避免大 payload）；
+ *   3) 前端 GET /__code-bridge/<id> 取回代码写回 CodeJar（updateCode 不触发 onUpdate，断回声环）；
+ *   4) 会话结束 = 前端 DELETE（面板关闭 / 手动断开 / 组件卸载）或心跳 TTL 兜底
+ *      （前端 5s 心跳，20s 无心跳即删文件，覆盖关浏览器 / 崩溃）；启动时清扫 >24h 残留。
+ *
+ * 「关闭」语义说明：VSCode CLI 把文件交给已运行实例后立即返回，标签页关闭事件不装扩展
+ * 拿不到，故清除时机取「会话结束 + TTL」，而非 VSCode 关标签瞬间。
+ *
+ * 安全：与其余 /__ 端点同信任级（仅 127.0.0.1 + 可选 DSL_DEV_TOKEN）；临时文件名由服务端
+ * 生成（hex 白名单），用户代码内容不进入命令行；DSL_EDITOR_CMD 为开发者自配环境变量，
+ * 按 shell 语义执行（文档注明）。
+ */
+
+export const BRIDGE_DIR_NAME = 'cardbuddy-code-bridge'
+export const SESSION_ID_RE = /^[a-f0-9]{8}$/
+export const HEARTBEAT_TTL_MS = 20000
+const REAP_INTERVAL_MS = 5000
+const WATCH_DEBOUNCE_MS = 150
+const STALE_FILE_MS = 24 * 60 * 60 * 1000
+const MAX_BODY = 2 * 1024 * 1024
+
+/** 桥接临时目录：os.tmpdir() 下独立子目录，不污染仓库 */
+export function bridgeDir() {
+  return path.join(os.tmpdir(), BRIDGE_DIR_NAME)
+}
+
+/** 回写归一：Windows 编辑器可能以 CRLF 落盘，schema 代码串统一 LF，避免无谓 churn */
+export function normalizeEol(s) {
+  if (s == null) return ''
+  return String(s).replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+}
+
+export function hashContent(s) {
+  return crypto.createHash('sha1').update(String(s), 'utf8').digest('hex')
+}
+
+/**
+ * 编辑器拉起方式（纯函数，便于单测）：
+ * - DSL_EDITOR_CMD 优先：整串按 shell 语义执行 + 追加带引号文件路径（支持 cursor / 自定义命令带参数）；
+ * - 否则平台默认 VSCode：mac 走 `open -a`；linux 直接 `code`；win 走 shell 语义的 `code "<file>"`
+ *   （PATH 里的 code 是 code.cmd，裸 spawn 执行不了 .cmd；而 ComSpec + 参数数组会被 node 的
+ *   Windows 引号转义与 cmd /s /c 剥首尾引号规则叠加拆坏，实测命令变成 '\"code\"' 报 9009）；
+ * - 返回 null 表示平台不支持（由 resolveEditorChain 继续降级 vscode:// 协议）。
+ */
+export function resolveEditorSpec(file, env = process.env, platform = process.platform) {
+  const custom = String(env.DSL_EDITOR_CMD || '').trim()
+  if (custom) return { kind: 'custom', command: `${custom} "${file}"`, shell: true }
+  if (platform === 'darwin') {
+    return { kind: 'vscode', cmd: 'open', args: ['-a', 'Visual Studio Code', file], shell: false }
+  }
+  if (platform === 'win32') {
+    return { kind: 'vscode', command: `code "${file}"`, shell: true }
+  }
+  if (platform === 'linux') {
+    return { kind: 'vscode', cmd: 'code', args: [file], shell: false }
+  }
+  return null
+}
+
+/** VSCode 未安装 / CLI 缺失时的协议兜底（安装器默认注册 vscode:// 处理器） */
+export function resolveProtocolSpec(file, env = process.env, platform = process.platform) {
+  const url = 'vscode://file/' + String(file).split(path.sep).join('/')
+  if (platform === 'darwin') return { cmd: 'open', args: [url], shell: false }
+  if (platform === 'win32') {
+    return { command: `start "" "${url}"`, shell: true }
+  }
+  if (platform === 'linux') return { cmd: 'xdg-open', args: [url], shell: false }
+  return null
+}
+
+/**
+ * 拉起方式降级链（跨平台兼容的核心）：
+ * - DSL_EDITOR_CMD 自定义 → 单级；
+ * - win：`code "<file>"`（shell 语义）→ vscode:// 协议；
+ * - mac：`open -a "Visual Studio Code"` → `code` CLI（App 被改名/移动但装过 CLI 时兜一层）→ vscode:// 协议；
+ * - linux：`code` → xdg-open vscode://；
+ * 任一级 spawn ENOENT 或非 0 退出即尝试下一级。
+ */
+export function resolveEditorChain(file, env = process.env, platform = process.platform) {
+  const custom = String(env.DSL_EDITOR_CMD || '').trim()
+  if (custom) return [{ tag: 'custom', spec: { command: `${custom} "${file}"`, shell: true } }]
+  const chain = []
+  const primary = resolveEditorSpec(file, env, platform)
+  if (primary) chain.push({ tag: primary.kind, spec: primary })
+  if (platform === 'darwin') chain.push({ tag: 'vscode-cli', spec: { command: `code "${file}"`, shell: true } })
+  const proto = resolveProtocolSpec(file, env, platform)
+  if (proto) chain.push({ tag: 'protocol', spec: proto })
+  return chain
+}
+
+function launchEditor(file) {
+  const chain = resolveEditorChain(file)
+  const attempt = (i) => {
+    if (i >= chain.length) return false
+    const { tag, spec } = chain[i]
+    const next = () => {
+      if (i + 1 >= chain.length) return false
+      if (!attempt(i + 1)) return false
+      log.ok('代码桥降级下一级拉起方式', { from: tag, to: chain[i + 1].tag, file })
+      return true
+    }
+    try {
+      const child = spec.shell
+        ? spawn(spec.command, { shell: true, stdio: 'ignore' })
+        : spawn(spec.cmd, spec.args, { shell: false, stdio: 'ignore' })
+      let handed = false
+      const fail = (detail) => {
+        if (handed) return
+        handed = true
+        log.warn(`代码桥拉起编辑器失败（${tag}）`, detail)
+        next()
+      }
+      child.on('error', (e) => fail({ message: String(e.message) }))
+      // shell 语义下 spawn 本身不会 ENOENT（shell 一定在），内部命令缺失只体现在退出码上
+      child.on('exit', (code) => {
+        if (code === 0 || code === null) return
+        fail({ code })
+      })
+      return true
+    } catch (e) {
+      log.warn(`代码桥拉起编辑器异常（${tag}）`, e)
+      return next()
+    }
+  }
+  return attempt(0)
+}
+
+/** 启动清扫：删除 >24h 的残留临时文件（会话表在内存，跨重启即孤儿） */
+export function sweepStaleFiles(now = Date.now()) {
+  const dir = bridgeDir()
+  let removed = 0
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+    for (const name of fs.readdirSync(dir)) {
+      if (!SESSION_ID_RE.test(name.replace(/\.js$/, ''))) continue
+      const full = path.join(dir, name)
+      try {
+        const st = fs.statSync(full)
+        if (now - st.mtimeMs > STALE_FILE_MS) {
+          fs.rmSync(full, { force: true })
+          removed++
+        }
+      } catch (_) { /* 忽略单文件竞态 */ }
+    }
+  } catch (e) {
+    log.warn('代码桥启动清扫失败', { message: String(e.message) })
+  }
+  return removed
+}
+
+/**
+ * 默认单文件监听（fs.watch + rename 重挂兜底原子保存）。
+ * cardbuddy 会注入 chokidar 版 watchFile（更稳）；本兜底保证中间件零额外依赖，
+ * 使 server/core 可被根仓库（无 chokidar 依赖）直接 import / 单测。
+ */
+export function defaultWatchFile(file, onChange) {
+  let watcher = null
+  let rearmTimer = null
+  let closed = false
+  const arm = () => {
+    if (closed) return
+    try {
+      watcher = fs.watch(file, (event) => {
+        onChange()
+        // 原子保存（临时文件改名覆盖）会让旧 inode 失效：重挂监听
+        if (event === 'rename') rearm()
+      })
+      watcher.on('error', () => rearm())
+    } catch (_) {
+      rearm()
+    }
+  }
+  const rearm = () => {
+    if (closed) return
+    try {
+      watcher && watcher.close()
+    } catch (_) { /* ignore */ }
+    if (rearmTimer) clearTimeout(rearmTimer)
+    rearmTimer = setTimeout(arm, 120)
+  }
+  arm()
+  return {
+    close() {
+      closed = true
+      if (rearmTimer) clearTimeout(rearmTimer)
+      try {
+        watcher && watcher.close()
+      } catch (_) { /* ignore */ }
+    },
+  }
+}
+
+/**
+ * @param {{ root?: string, notify?: (data: object, event?: string) => void, watchFile?: (file: string, cb: () => void) => { close: () => void } }} opts
+ *   - watchFile：单文件监听能力注入（cardbuddy 注入 chokidar 版）；缺省用 fs.watch 兜底。
+ * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, next: Function) => void}
+ */
+export function createCodeBridgeMiddleware({ notify = null, watchFile = null } = {}) {
+  /** @type {Map<string, {id:string,file:string,label:string,lastHash:string,lastHeartbeat:number,watcher:object|null,timer:object|null}>} */
+  const sessions = new Map()
+  const swept = sweepStaleFiles()
+  if (swept) log.ok('代码桥清扫残留临时文件', { removed: swept })
+
+  const push = (data, event) => {
+    if (typeof notify === 'function') notify(data, event)
+  }
+
+  function closeSession(id, reason) {
+    const s = sessions.get(id)
+    if (!s) return false
+    sessions.delete(id)
+    if (s.timer) clearTimeout(s.timer)
+    try { s.watcher && s.watcher.close() } catch (_) { /* ignore */ }
+    try { fs.rmSync(s.file, { force: true }) } catch (e) {
+      log.warn('代码桥删除临时文件失败', { file: s.file, message: String(e.message) })
+    }
+    push({ id, reason }, 'code-bridge-closed')
+    log.ok('代码桥会话结束', { id, reason, file: s.file })
+    return true
+  }
+
+  const reaper = setInterval(() => {
+    const now = Date.now()
+    for (const [id, s] of sessions) {
+      if (now - s.lastHeartbeat > HEARTBEAT_TTL_MS) closeSession(id, 'ttl')
+    }
+  }, REAP_INTERVAL_MS)
+  reaper.unref && reaper.unref()
+
+  function onFileChange(session) {
+    if (session.timer) clearTimeout(session.timer)
+    session.timer = setTimeout(() => {
+      session.timer = null
+      let raw
+      try {
+        raw = fs.readFileSync(session.file, 'utf8')
+      } catch (_) {
+        return // 文件被外部删除：等 TTL / 前端断开收尾
+      }
+      const hash = hashContent(normalizeEol(raw))
+      if (hash === session.lastHash) return // 服务端自写回声 / 无实质变化
+      session.lastHash = hash
+      push({ id: session.id }, 'code-bridge-changed')
+    }, WATCH_DEBOUNCE_MS)
+  }
+
+  function openSession(code, label) {
+    const id = crypto.randomBytes(4).toString('hex')
+    const file = path.join(bridgeDir(), `${id}.js`)
+    const text = normalizeEol(code == null ? '' : code)
+    fs.mkdirSync(bridgeDir(), { recursive: true })
+    fs.writeFileSync(file, text, 'utf8')
+    const session = {
+      id,
+      file,
+      label: String(label || ''),
+      lastHash: hashContent(text),
+      lastHeartbeat: Date.now(),
+      watcher: null,
+      timer: null,
+    }
+    const watch = typeof watchFile === 'function' ? watchFile : defaultWatchFile
+    session.watcher = watch(file, () => onFileChange(session))
+    sessions.set(id, session)
+    const launched = launchEditor(file)
+    log.ok('代码桥会话建立', { id, file, label: session.label, launched })
+    return { id, file, launched }
+  }
+
+  const sendJson = (res, status, payload) => {
+    res.statusCode = status
+    res.setHeader('Content-Type', 'application/json')
+    res.setHeader('Cache-Control', 'no-store')
+    res.end(JSON.stringify(payload))
+  }
+
+  const readBody = (req, limit = MAX_BODY) =>
+    new Promise((resolve, reject) => {
+      let body = ''
+      req.on('data', (c) => {
+        body += c
+        if (body.length > limit) {
+          reject(new Error('body too large'))
+          req.destroy()
+        }
+      })
+      req.on('end', () => resolve(body))
+      req.on('error', reject)
+    })
+
+  return async function codeBridgeMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const method = (req.method || 'GET').toUpperCase()
+    if (!pathname.startsWith('/__code-bridge')) return next()
+
+    // POST /__code-bridge —— 建立会话
+    if (pathname === '/__code-bridge' && method === 'POST') {
+      let payload
+      try {
+        payload = JSON.parse((await readBody(req)) || '{}')
+      } catch (_) {
+        return sendJson(res, 400, { ok: false, error: 'invalid json' })
+      }
+      try {
+        const opened = openSession(payload.code, payload.label)
+        return sendJson(res, 200, { ok: true, ...opened })
+      } catch (e) {
+        log.error('代码桥建立会话失败', e)
+        return sendJson(res, 500, { ok: false, error: String(e.message) })
+      }
+    }
+
+    // 其余端点：/__code-bridge/<id>[/heartbeat]
+    const m = pathname.match(/^\/__code-bridge\/([a-f0-9]{8})(\/heartbeat)?$/)
+    if (!m) return sendJson(res, 404, { ok: false, error: 'unknown bridge route' })
+    const [, id, isHeartbeat] = m
+    const session = sessions.get(id)
+
+    if (isHeartbeat && method === 'POST') {
+      if (!session) return sendJson(res, 404, { ok: false, error: 'session not found', id })
+      session.lastHeartbeat = Date.now()
+      return sendJson(res, 200, { ok: true, id })
+    }
+
+    if (!isHeartbeat && method === 'GET') {
+      if (!session) return sendJson(res, 404, { ok: false, error: 'session not found', id })
+      let raw = ''
+      try {
+        raw = fs.readFileSync(session.file, 'utf8')
+      } catch (e) {
+        return sendJson(res, 410, { ok: false, error: 'temp file gone', id })
+      }
+      session.lastHeartbeat = Date.now()
+      const code = normalizeEol(raw)
+      return sendJson(res, 200, { ok: true, id, code, hash: hashContent(code) })
+    }
+
+    if (!isHeartbeat && method === 'DELETE') {
+      const closed = closeSession(id, 'client')
+      return sendJson(res, closed ? 200 : 404, { ok: closed, id })
+    }
+
+    return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+  }
+}

package/dist/server-core/index.js

@@ -13,6 +13,7 @@
  * 接收 viteServer 参数透传；无 SSR 需求的场景可传 null（这两个端点会返回明确错误）。
  */
 import { createSyncMiddleware, createPreviewMiddleware, createLoginCredentialsMiddleware } from './cardSync.js'
+import { createSliceUploadMiddleware } from './sliceUpload.js'
 import { createCardFilesMiddleware } from './cardFiles.js'
 import { createSaveMiddleware } from './cardSave.js'
 import { createImportMetaMiddleware } from './cardImportMeta.js'
@@ -26,12 +27,14 @@ import { createAssetProxyMiddleware } from './assetProxy.js'
 import { createSliceStaticMiddleware } from './sliceStatic.js'
 import { createCardImageMiddleware } from './cardImage.js'
 import { createOpenFolderMiddleware } from './cardOpenFolder.js'
+import { createCodeBridgeMiddleware } from './codeBridge.js'
 import { buildDataFromSchema } from './buildDataFromSchema.js'
 
 export {
   createSyncMiddleware,
   createPreviewMiddleware,
   createLoginCredentialsMiddleware,
+  createSliceUploadMiddleware,
   createCardFilesMiddleware,
   createSaveMiddleware,
   createImportMetaMiddleware,
@@ -45,19 +48,26 @@ export {
   createSliceStaticMiddleware,
   createCardImageMiddleware,
   createOpenFolderMiddleware,
+  createCodeBridgeMiddleware,
   buildDataFromSchema,
 }
 
 /**
  * 把全部卡片中间件挂到 Connect 风格容器（需实现 .use(mw)）。
  * @param {{ use: (mw: Function) => void }} app
- * @param {{ root: string, viteServer?: import('vite').ViteDevServer | null, upstream?: string }} opts
+ * @param {{ root: string, viteServer?: import('vite').ViteDevServer | null, upstream?: string, notify?: (data: object, event?: string) => void, watchFile?: (file: string, cb: () => void) => { close: () => void } }} opts
  *   - upstream：FinMall 远端站点基址（来自 FINMALL_BASE_URL），资源代理回源用；空串表示不回源。
+ *   - notify：SSE 推送入口（cardbuddy 的 /__events hub）；代码桥经它推 bridge 事件，缺省时静默降级。
+ *   - watchFile：代码桥单文件监听能力注入（chokidar 版）；缺省代码桥用 fs.watch 兜底。
  */
-export function mountCoreMiddlewares(app, { root, viteServer = null, upstream = '' }) {
+export function mountCoreMiddlewares(app, { root, viteServer = null, upstream = '', notify = null, watchFile = null }) {
   app.use(createSyncMiddleware({ root }))
   app.use(createPreviewMiddleware({ root }))
   app.use(createLoginCredentialsMiddleware({ root }))
+  // 切图上传（顶栏「远端 → 切图上传」）：把当前卡引用的 src/slices 切图传到 FinMall 图片库，
+  // 写 src/slices/manifest.json 映射并把卡片里的 /slices/ 引用改写为 @filestore/ 线上地址。
+  // 仅在用户点击时触发，没有任何自动上传路径。
+  app.use(createSliceUploadMiddleware({ root }))
   app.use(createCardFilesMiddleware({ root }))
   app.use(createSaveMiddleware({ root }))
   app.use(createHistoryMiddleware({ root }))
@@ -70,6 +80,8 @@ export function mountCoreMiddlewares(app, { root, viteServer = null, upstream =
   app.use(createBboxMiddleware({ root }))
   // 在系统文件管理器中打开当前卡片本地目录（编辑器顶栏「打开目录」按钮触发，跨平台由后端完成）
   app.use(createOpenFolderMiddleware({ root }))
+  // 外部编辑器代码桥（VSCode / DSL_EDITOR_CMD）：临时 js + 保存回写 + 会话 TTL 清理
+  app.use(createCodeBridgeMiddleware({ root, notify, watchFile }))
   // 卡片预览图静态服务：/__card-image/<id> → src/cards/<id>/<id>.<ext>（编辑器网格预览缩略图用，
   // 复用本地静态服务，避免实时无头截图）。
   app.use(createCardImageMiddleware({ root }))

package/dist/server-core/sliceUpload.js

@@ -0,0 +1,97 @@
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { log, fmtBytes } from './logger.js'
+
+/**
+ * 顶栏「远端 → 切图上传」按钮的服务端处理：把卡片引用的 src/slices 切图上传到 FinMall
+ * 图片库（CC0000.do），写「本地文件 ↔ 线上地址」映射（src/slices/manifest.json），
+ * 并把该卡 schema.json / data.json 里的 `/slices/<name>` 引用改写为返回的 `@filestore/...`。
+ *
+ * 复用 finmall-card-sync 的 uploadSlices（与「同步」「版本推送」共用同一后台 FinMall 会话）。
+ * 纯前端无法直接调 FinMall：跨域 + 需 token（只在页面上下文内读取，不回传 Node），故必须经此中转。
+ *
+ * **只由用户点击触发**——没有任何自动上传路径：保存 / 推送 / 同步都不会顺带上传切图。
+ *
+ * @param {{ root: string }} opts
+ * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, next: Function) => void}
+ */
+export function createSliceUploadMiddleware({ root }) {
+  return function sliceUploadMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    if (pathname !== '/__slice-upload') return next()
+    if ((req.method || 'GET').toUpperCase() !== 'POST') return next()
+
+    let body = ''
+    req.on('data', (c) => {
+      body += c
+      if (body.length > 64 * 1024) req.destroy()
+    })
+    req.on('end', async () => {
+      let payload
+      try {
+        payload = JSON.parse(body || '{}')
+      } catch (e) {
+        res.statusCode = 400
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(JSON.stringify({ error: 'invalid json', message: String(e.message) }))
+      }
+      if (!payload.cardId) {
+        res.statusCode = 400
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(
+          JSON.stringify({ error: 'missing cardId', message: '需传入当前卡片 id（切图上传按单卡范围执行）' }),
+        )
+      }
+      try {
+        const skillPath = path.join(root, 'skills', 'finmall-card-sync', 'scripts', 'slice_upload.mjs')
+        const { uploadSlices } = await import(pathToFileURL(skillPath).href)
+        const summary = await uploadSlices({
+          cardId: String(payload.cardId),
+          force: !!payload.force,
+          slicesRoot: path.join(root, 'src', 'slices'),
+          cardsRoot: path.join(root, 'src', 'cards'),
+        })
+        // 上传结果在 dev server 终端同样留痕（与「远端同步」一致的美化框）。
+        const replaced = summary.rewritten.reduce((n, r) => n + r.count, 0)
+        const lines = [
+          `卡片：${summary.cardId}`,
+          `目标：sassAppId=${summary.appId} sassWorkspaceId=${summary.workspaceId}`,
+          summary.uploaded.length
+            ? `已上传 ${summary.uploaded.length} 张：`
+            : '已上传 0 张',
+          ...summary.uploaded.map(
+            (u) => `• ${u.name}（${fmtBytes(u.size)}${u.dimensions ? ` ${u.dimensions}` : ''}）→ ${u.url}`,
+          ),
+          `复用已有地址（内容未变）：${summary.skipped.length} 张`,
+          `改写引用：${summary.rewritten.length} 个文件 / ${replaced} 处`,
+          ...(summary.failed.length
+            ? [`失败 ${summary.failed.length} 张：`, ...summary.failed.map((f) => `✗ ${f.name}  ${f.error}`)]
+            : []),
+          ...(summary.dangling.length
+            ? [`悬空引用（schema 引用但 src/slices 无此文件）：${summary.dangling.join('、')}`]
+            : []),
+        ]
+        log.box({ title: '切图上传完成', level: summary.success ? 'ok' : 'warn', lines })
+        res.statusCode = 200
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(JSON.stringify(summary))
+      } catch (e) {
+        // 区分「凭据缺失」与「真正的上传错误」：前者让前端弹登录表单，而非裸抛 ENOENT。
+        const isNoCred =
+          e &&
+          (e.code === 'NO_CREDENTIALS' ||
+            /credentials\.json|credentials 不存在|NO_CREDENTIALS/.test(String(e && e.message)))
+        if (!isNoCred) log.error('切图上传失败', e)
+        res.statusCode = isNoCred ? 200 : 500
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(
+          JSON.stringify(
+            isNoCred
+              ? { error: 'need_credentials', needCredentials: true, message: String(e && e.message) }
+              : { error: 'slice upload failed', message: String(e && e.message) },
+          ),
+        )
+      }
+    })
+  }
+}

package/dist/standalone.js

@@ -290,8 +290,8 @@ function createEventsEndpoint() {
       clients.delete(res)
     })
   }
-  const notify = (data) => {
-    const payload = `event: cards-changed\ndata: ${JSON.stringify(data)}\n\n`
+  const notify = (data, event = 'cards-changed') => {
+    const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
     for (const res of clients) res.write(payload)
   }
   return { handler, notify }
@@ -397,7 +397,22 @@ export async function startServer(userConfig = {}) {
 
   const vite = await createEmbeddedVite(config)
   // upstream（FINMALL_BASE_URL）透传给资源代理中间件，使其能回源 FinMall 取站内资源
-  mountCoreMiddlewares(app, { root: config.root, viteServer: vite, upstream: config.upstream })
+  mountCoreMiddlewares(app, {
+    root: config.root,
+    viteServer: vite,
+    upstream: config.upstream,
+    notify: events.notify,
+    // 代码桥单文件监听注入 chokidar 版：原子保存（改名覆盖）由 add 兜住，awaitWriteFinish 防半截读
+    watchFile: (file, onChange) => {
+      const watcher = chokidar.watch(file, {
+        ignoreInitial: true,
+        awaitWriteFinish: { stabilityThreshold: 120, pollInterval: 40 },
+      })
+      watcher.on('change', onChange)
+      watcher.on('add', onChange)
+      return watcher
+    },
+  })
 
   watchCards(config.root, events.notify)