cardbuddy 0.13.3 → 0.14.1

package/dist/vendored/server/core/cardFiles.js

@@ -1,6 +1,10 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { markDirty, recordEdit, readImportMeta } from './cardImportMeta.js'
+import { markDirty, recordEdit, readImportMeta, setImportMetaCardCode } from './cardImportMeta.js'
+import { deleteChatHistory, chatHistoryDir, safeCardId } from './chatHistory.js'
+// 回合日志（.cache/ai-turns/<id>.jsonl）与对话记录同生命周期：删卡时一并清掉，
+// 否则「上一轮跑到哪了」会指向一张已经不存在的卡。
+import { deleteJournal, turnsDir } from './turnJournal.js'
 import { log } from './logger.js'
 import { buildDataFromSchema } from './buildDataFromSchema.js'
 
@@ -19,46 +23,84 @@ import { buildDataFromSchema } from './buildDataFromSchema.js'
 /** 扫描 src/cards/* 返回 [{id,name,pageId,mtime,imported}]（导出供 MCP 复用）；
  *  mtime 为 schema.json / data.json 中较新的修改时间（毫秒），供前端按修改时间排序；
  *  imported = 目录下存在 .import-meta.json 侧车（经远端同步导入而来），供 UI 打「导入卡」标记 */
+/**
+ * 扫描单张卡片目录，抽取列表项元信息 {id,name,pageId,mtime,imported}。
+ * 抽出以便 listCards（全量）与 readCardListItem（单卡）复用同一套口径，避免漂移。
+ * 目录不存在 / 非目录返回 null（调用方据此跳过）。
+ */
+function scanCardMeta(cardsDir, id) {
+  const dir = path.join(cardsDir, id)
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return null
+  let name = id
+  let pageId = null
+  let mtime = 0
+  try {
+    const schema = JSON.parse(fs.readFileSync(path.join(dir, 'schema.json'), 'utf8'))
+    if (schema && schema.name) name = schema.name
+    if (schema && schema.pageId != null) pageId = schema.pageId
+  } catch {
+    /* 读取失败则退用目录名 / pageId=null，不阻断列表 */
+  }
+  // 卡片修改时间：取 schema.json 的单文件 mtime（毫秒）。data.json 是 schema 的
+  // 单向派生产物，不应参与排序，否则它每次被重算都会让卡片「看起来更新」。
+  try {
+    mtime = fs.statSync(path.join(dir, 'schema.json')).mtimeMs
+  } catch {
+    /* 取不到修改时间则记为 0，不参与新→旧排序时排在最前 */
+  }
+  // 优先采用侧车 .import-meta.json 记录的本地编辑时间（editedAt 更准确反映「编辑」而非文件拷贝），
+  // 无侧车 / 无 editedAt 时退用上面的文件 mtime。
+  // 导入卡标记：存在 .import-meta.json 侧车即为「经远端同步导入」的卡，
+  // UI 据此在下拉项前置绿色圆点 / 网格格子上角打「导入」标签。
+  let imported = false
+  try {
+    const meta = readImportMeta(dir)
+    imported = !!meta
+    if (meta && meta.editedAt) {
+      const t = Date.parse(meta.editedAt)
+      if (!Number.isNaN(t)) mtime = t
+    }
+  } catch {
+    /* 解析失败则保持文件 mtime / imported=false */
+  }
+  return { id, name, pageId, mtime, imported }
+}
+
+/**
+ * 进程内卡片列表快照缓存：dev 服务不再每次 GET /__cards 都全量 readdir + 逐张 JSON.parse。
+ * 快照仅在低频时机刷新：watcher 检测到 src/cards 下 .json 变更 / 本地 CRUD（新建·删除·改名）成功。
+ * 日常列表读取直接命中缓存，把 70+ 张卡片的磁盘扫描降到接近零（修复 A）。
+ * @type {Map<string, Array<{id:string,name:string,pageId:?string,mtime:number,imported:boolean}>>}
+ */
+const cardListCache = new Map()
+
+/** 强制重扫并缓存列表（供 watcher / CRUD 调用） */
+export function refreshCardList(root) {
+  const list = listCards(root)
+  cardListCache.set(root, list)
+  return list
+}
+
+/** 读取列表：命中进程内快照则直接返回，否则惰性全扫一次并缓存 */
+export function getCardList(root) {
+  const hit = cardListCache.get(root)
+  if (hit) return hit
+  return refreshCardList(root)
+}
+
+/** 读单卡列表项（供前端 onCardsChanged 增量更新，O(1) 只读该卡 schema.json，不扫全目录） */
+export function readCardListItem(root, id) {
+  return scanCardMeta(path.join(root, 'src', 'cards'), id)
+}
+
+/** 扫描 src/cards/* 返回 [{id,name,pageId,mtime,imported}]（导出供 MCP 复用） */
 export function listCards(root) {
   const cardsDir = path.join(root, 'src', 'cards')
   const list = []
   if (fs.existsSync(cardsDir)) {
     for (const id of fs.readdirSync(cardsDir)) {
-      const dir = path.join(cardsDir, id)
-      if (!fs.statSync(dir).isDirectory()) continue
-      let name = id
-      let pageId = null
-      let mtime = 0
-      try {
-        const schema = JSON.parse(fs.readFileSync(path.join(dir, 'schema.json'), 'utf8'))
-        if (schema && schema.name) name = schema.name
-        if (schema && schema.pageId != null) pageId = schema.pageId
-      } catch {
-        /* 读取失败则退用目录名 / pageId=null，不阻断列表 */
-      }
-      // 卡片修改时间：取 schema.json 的单文件 mtime（毫秒）。data.json 是 schema 的
-      // 单向派生产物，不应参与排序，否则它每次被重算都会让卡片「看起来更新」。
-      try {
-        mtime = fs.statSync(path.join(dir, 'schema.json')).mtimeMs
-      } catch {
-        /* 取不到修改时间则记为 0，不参与新→旧排序时排在最前 */
-      }
-      // 优先采用侧车 .import-meta.json 记录的本地编辑时间（editedAt 更准确反映「编辑」而非文件拷贝），
-      // 无侧车 / 无 editedAt 时退用上面的文件 mtime。
-      // 导入卡标记：存在 .import-meta.json 侧车即为「经远端同步导入」的卡，
-      // UI 据此在下拉项前置绿色圆点 / 网格格子上角打「导入」标签。
-      let imported = false
-      try {
-        const meta = readImportMeta(dir)
-        imported = !!meta
-        if (meta && meta.editedAt) {
-          const t = Date.parse(meta.editedAt)
-          if (!Number.isNaN(t)) mtime = t
-        }
-      } catch {
-        /* 解析失败则保持文件 mtime / imported=false */
-      }
-      list.push({ id, name, pageId, mtime, imported })
+      const item = scanCardMeta(cardsDir, id)
+      if (item) list.push(item)
     }
   }
   list.sort((a, b) => a.id.localeCompare(b.id))
@@ -123,11 +165,125 @@ export function writeCardFiles(dir, payload) {
   return written
 }
 
+/** 卡片封面图支持扩展名（与 card-image 服务一致） */
+const COVER_EXTS = ['.png', '.jpg', '.jpeg', '.webp', '.gif']
+
 /**
- * @param {{ root: string }} opts
+ * 把卡片目录内「与旧 id 同名」的封面图改名为「与新 id 同名」。
+ * card-image 服务按 base===id 取封面，故目录改名后封面文件名必须同步跟随，否则网格回退到实时截图。
+ */
+function renameCoverImage(dir, oldId, newId) {
+  try {
+    for (const entry of fs.readdirSync(dir)) {
+      const dot = entry.lastIndexOf('.')
+      if (dot < 0) continue
+      const base = entry.slice(0, dot)
+      const ext = entry.slice(dot).toLowerCase()
+      if (base === oldId && COVER_EXTS.includes(ext)) {
+        try {
+          fs.renameSync(path.join(dir, entry), path.join(dir, newId + ext))
+        } catch {
+          /* 单图改名失败不阻断重命名主体 */
+        }
+      }
+    }
+  } catch {
+    /* 读目录失败忽略：封面缺失不致命 */
+  }
+}
+
+/** 把该卡的对话记录 / 回合日志缓存一并改名跟随（避免重命名后丢历史 / 留孤儿缓存） */
+function moveCardCache(root, oldId, newId) {
+  const move = (dir, suffix) => {
+    if (!fs.existsSync(dir)) return
+    const from = path.join(dir, `${safeCardId(oldId)}${suffix}`)
+    const to = path.join(dir, `${safeCardId(newId)}${suffix}`)
+    if (from === to || !fs.existsSync(from)) return
+    try {
+      fs.renameSync(from, to)
+    } catch {
+      /* 目标已存在 / 并发占用则忽略，不阻断重命名 */
+    }
+  }
+  move(chatHistoryDir(root), '.json')
+  move(turnsDir(root), '.jsonl')
+  move(turnsDir(root), '.jsonl.1')
+}
+
+/**
+ * 重命名卡片：改卡片目录名（src/cards/<oldId> → <newId>）+ 写回 schema.name/desc，
+ * 并把该卡的封面图 / 对话记录 / 回合日志缓存一并改名跟随（重命名后历史不丢、不留孤儿缓存）。
+ * - id 未传 / 等于旧 id：只改描述（schema.name/desc），不移动目录。
+ * - id 不同：先做目录撞名兜底，再原子 rename 目录。
+ * 导出供 MCP 降级模式复用。
+ * @throws {{ code?: string, message: string }} NOT_FOUND / INVALID_ID / INVALID_DESC / CONFLICT
+ * @returns {{ ok: true, id: string, oldId: string, renamed: boolean }}
+ */
+export function renameCard(root, oldId, payload = {}) {
+  const newId = String(payload.id || '').trim()
+  const desc = payload.desc == null ? '' : String(payload.desc).trim()
+  const cardsRoot = path.join(root, 'src', 'cards')
+  const oldDir = path.join(cardsRoot, oldId)
+  if (!fs.existsSync(oldDir) || !fs.statSync(oldDir).isDirectory()) {
+    const e = new Error(`卡片不存在：src/cards/${oldId}`)
+    e.code = 'NOT_FOUND'
+    throw e
+  }
+  const renameFolder = !!newId && newId !== oldId
+  if (renameFolder && !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(newId)) {
+    const e = new Error('卡片 ID 只能以字母/数字开头，含字母/数字/_/-（≤64 字符）')
+    e.code = 'INVALID_ID'
+    throw e
+  }
+  if (desc.length > 200) {
+    const e = new Error('卡片描述过长（≤200 字）')
+    e.code = 'INVALID_DESC'
+    throw e
+  }
+  const finalId = renameFolder ? newId : oldId
+  const finalDir = renameFolder ? path.join(cardsRoot, newId) : oldDir
+  if (renameFolder && fs.existsSync(finalDir)) {
+    const e = new Error(`卡片 ID 已存在：src/cards/${newId} 已在本地，换一个 ID`)
+    e.code = 'CONFLICT'
+    throw e
+  }
+  if (renameFolder) {
+    fs.renameSync(oldDir, finalDir)
+    renameCoverImage(finalDir, oldId, newId)
+    moveCardCache(root, oldId, newId)
+    // 侧车 cardCode（=目录名）必须跟着改：远端身份是 schema.pageId，不随本地改名变化，
+    // 但 cardCode 停留旧值会让「来源」tab / 推送闸门 / card-save 落点判定指向不存在的目录。
+    try {
+      setImportMetaCardCode(finalDir, newId)
+    } catch {
+      /* 侧车写入失败不阻断重命名主体（本地新建卡本来就没有侧车） */
+    }
+  }
+  // 写回 schema.name/desc（与新建空白卡同构：name 回落 id）；data 由 schema 单向重算
+  const schema = JSON.parse(fs.readFileSync(path.join(finalDir, 'schema.json'), 'utf8'))
+  schema.name = desc || finalId
+  schema.desc = desc
+  writeJsonFile(finalDir, 'schema.json', schema)
+  writeJsonFile(finalDir, 'data.json', buildDataFromSchema(schema))
+  if (renameFolder) {
+    try {
+      recordEdit(finalDir)
+    } catch {
+      /* 无侧车时忽略 */
+    }
+  }
+  log.ok(renameFolder ? '重命名卡片' : '更新卡片描述', `${oldId} → ${finalId}`)
+  return { ok: true, id: finalId, oldId, renamed: renameFolder }
+}
+
+/**
+ * @param {{ root: string, notify?: ((data: object, event?: string) => void) | null }} opts
+ *   - notify：SSE 推送入口（cardbuddy 的 /__events hub）。重命名成功后据此推一条
+ *     `cards-changed { type: 'rename', oldId, id }`，让前端能把选中态 / 会话状态一并迁移到新 id
+ *     （chokidar 的 unlink(旧) + add(新) 在 120ms 防抖里会被压成一条，认不出「这是改名」）。
  * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, next: Function) => void}
  */
-export function createCardFilesMiddleware({ root }) {
+export function createCardFilesMiddleware({ root, notify = null }) {
   return function cardFilesMiddleware(req, res, next) {
     const pathname = decodeURIComponent((req.url || '').split('?')[0])
     const method = (req.method || 'GET').toUpperCase()
@@ -207,6 +363,30 @@ export function createCardFilesMiddleware({ root }) {
       return
     }
 
+    // 单卡列表项（O(1)：只读该卡 schema.json，供前端增量更新，避免为「改一张卡」全量重扫 70+ 张）
+    const metaMatch = pathname.match(/^\/__card\/([^/]+)\/meta$/)
+    if (metaMatch && method === 'GET') {
+      const id = decodeURIComponent(metaMatch[1])
+      const cardsRoot = path.join(root, 'src', 'cards')
+      const dir = path.join(cardsRoot, id)
+      const rel = path.relative(cardsRoot, dir)
+      if (rel.startsWith('..') || path.isAbsolute(rel) || !rel) {
+        res.statusCode = 404
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(JSON.stringify({ error: 'card not found', id }))
+      }
+      const item = readCardListItem(root, id)
+      if (!item) {
+        res.statusCode = 404
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(JSON.stringify({ error: 'card not found', id }))
+      }
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      return res.end(JSON.stringify(item))
+    }
+
     const m = pathname.match(/^\/__card\/([^/]+)$/)
     if (!m) return next()
     const id = decodeURIComponent(m[1])
@@ -270,6 +450,13 @@ export function createCardFilesMiddleware({ root }) {
       // 删除本地卡片文件夹（网格预览格子右下角删除钮触发，前端有警告确认兜底）
       try {
         fs.rmSync(dir, { recursive: true, force: true })
+        // 卡片没了，.cache/ai-chats/<id>.json 就是孤儿（还会让「最近对话」列出已删除的卡），
+        // 在这里联动清掉。best-effort：删卡已成功，缓存清理失败只记日志，不把响应翻成 500。
+        const gone = deleteChatHistory(root, id)
+        if (!gone.ok) log.warn('清理对话缓存失败', `${id}: ${gone.error}`)
+        const turns = deleteJournal(root, id)
+        if (!turns.ok) log.warn('清理回合日志失败', `${id}: ${turns.error}`)
+        try { refreshCardList(root) } catch { /* 快照刷新失败不阻断删除 */ }
         log.ok('删除卡片', id)
         res.statusCode = 200
         res.setHeader('Content-Type', 'application/json')
@@ -278,9 +465,54 @@ export function createCardFilesMiddleware({ root }) {
         log.error('删除卡片失败', e)
         res.statusCode = 500
         res.setHeader('Content-Type', 'application/json')
-        return res.end(JSON.stringify({ error: 'delete failed', message: String(e.message) }))
+      return res.end(JSON.stringify({ error: 'delete failed', message: String(e.message) }))
       }
     }
+    // 重命名卡片（目录改名 + 描述写回）：PATCH /__card/<oldId>，body { id?, desc? }
+    if (method === 'PATCH') {
+      let body = ''
+      req.on('data', (c) => {
+        body += c
+        if (body.length > 64 * 1024) req.destroy()
+      })
+      req.on('end', () => {
+        const send = (code, payload) => {
+          res.statusCode = code
+          res.setHeader('Content-Type', 'application/json')
+          res.end(JSON.stringify(payload))
+        }
+        let payload
+        try {
+          payload = JSON.parse(body || '{}')
+        } catch (e) {
+          return send(400, { error: 'invalid json', message: String(e.message) })
+        }
+        try {
+          const result = renameCard(root, id, payload)
+          try { refreshCardList(root) } catch { /* 快照刷新失败不阻断改名 */ }
+          // 改名广播：必须带上 oldId→id 的映射（file 字段仅供前端日志/正则解析），
+          // 前端据此把 selectedId 与对话面板的卡上下文一起迁移，否则会停在已消失的旧目录上。
+          if (result.renamed && notify) {
+            try {
+              notify({ file: `src/cards/${result.id}/schema.json`, type: 'rename', oldId: result.oldId, id: result.id }, 'cards-changed')
+            } catch { /* 推送失败不影响改名结果 */ }
+          }
+          return send(200, result)
+        } catch (e) {
+          const code =
+            e.code === 'NOT_FOUND'
+              ? 404
+              : e.code === 'CONFLICT'
+                ? 409
+                : e.code === 'INVALID_ID' || e.code === 'INVALID_DESC'
+                  ? 400
+                  : 500
+          log.error('重命名卡片失败', e)
+          return send(code, { error: e.code ? String(e.code).toLowerCase() : 'rename failed', message: String(e.message) })
+        }
+      })
+      return
+    }
     return next()
   }
 }

package/dist/vendored/server/core/cardImportMeta.js

@@ -89,6 +89,22 @@ export function recordEdit(dir) {
   return next
 }
 
+/**
+ * 卡片目录被重命名时同步侧车里的 cardCode（= 目录名）。
+ *
+ * 为什么必须跟随：cardCode 是侧车对「卡片落在哪个目录」的自我声明，
+ * 远端身份是 cardId（→ schema.pageId），**不**随本地改名变化；但 cardCode 一旦与实际
+ * 目录名不符，「来源」tab、推送闸门与 card-save 的落点判定都会指向一个不存在的目录。
+ * 只在侧车存在时改写（本地新建卡无侧车，目录名即身份，无需同步）。
+ */
+export function setImportMetaCardCode(dir, cardCode) {
+  const meta = readImportMeta(dir)
+  if (!meta) return null
+  const next = { ...meta, cardCode: cardCode || '' }
+  writeImportMeta(dir, next)
+  return next
+}
+
 /**
  * 记录一次远端保存（/__save）的读回校验结果。
  * @param {string} dir

package/dist/vendored/server/core/chatHistory.js

@@ -0,0 +1,122 @@
+/**
+ * 对话记录落盘（.cache/ai-chats/<cardId>.json）的单一实现。
+ *
+ * 从 ai-chat.js 抽成中立模块的原因：删卡（cardFiles.js 的 DELETE /__card/<id>）也要顺手
+ * 清掉对应缓存对话，否则卡片删了孤儿 json 还躺在 .cache 里越积越多，「最近对话」还会列出
+ * 已不存在的卡。目录约定与文件名消毒只能有一处，ai-chat 与 cardFiles 共用本模块，避免漂移。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+/** 单卡最多保留的消息条数：写盘时截尾，防止长对话把 .cache 撑爆 */
+const MAX_HISTORY_MESSAGES = 200
+
+/** 对话记录目录（.cache/ 不入库）：随 root 走，测试可用临时根隔离 */
+export function chatHistoryDir(root) {
+  return path.join(root, '.cache', 'ai-chats')
+}
+
+export function safeCardId(cardId) {
+  const id = String(cardId || '').trim()
+  if (!id) return ''
+  // 只允许文件名安全字符，杜绝 ../ 路径穿越
+  return id.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 120)
+}
+
+function historyFile(chatDir, cardId) {
+  const id = safeCardId(cardId)
+  return id ? path.join(chatDir, `${id}.json`) : ''
+}
+
+export function readHistory(chatDir, cardId) {
+  const file = historyFile(chatDir, cardId)
+  if (!file || !fs.existsSync(file)) return { cardId: String(cardId || ''), messages: [], updatedAt: 0 }
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return {
+      cardId: String(raw.cardId || cardId || ''),
+      messages: Array.isArray(raw.messages) ? raw.messages : [],
+      updatedAt: Number(raw.updatedAt || 0),
+    }
+  } catch {
+    return { cardId: String(cardId || ''), messages: [], updatedAt: 0 }
+  }
+}
+
+/**
+ * 服务端权威历史合并（P2-13）：回合结束时把 turnJournal.reduce() 的 assistant 消息写进记录。
+ * 同 turnId 的旧副本（客户端回合中的中途落盘）先剔掉再写服务端这份，避免「同一轮两条回答」；
+ * 其余消息原样保留并按 ts 稳定排序 —— 用户消息仍由浏览器负责，服务端只权威 assistant 一侧。
+ * @param {object} msg journal.reduce() 的产物（带 turnId / serverAuthored 标记）
+ */
+export function mergeServerTurn(chatDir, cardId, msg) {
+  if (!msg || msg.role !== 'assistant' || !msg.turnId) return { ok: false, error: 'bad-message' }
+  const cur = readHistory(chatDir, cardId)
+  const kept = (Array.isArray(cur.messages) ? cur.messages : []).filter((m) => !(m && m.turnId === msg.turnId))
+  kept.push(msg)
+  kept.sort((a, b) => (Number(a.ts) || 0) - (Number(b.ts) || 0))
+  return writeHistory(chatDir, cardId, kept)
+}
+
+export function writeHistory(chatDir, cardId, messages) {
+  const file = historyFile(chatDir, cardId)
+  if (!file) return { ok: false, error: 'missing-card-id' }
+  fs.mkdirSync(chatDir, { recursive: true })
+  const list = Array.isArray(messages) ? messages.slice(-MAX_HISTORY_MESSAGES) : []
+  const payload = { cardId: safeCardId(cardId), messages: list, updatedAt: Date.now() }
+  const tmp = `${file}.tmp`
+  fs.writeFileSync(tmp, JSON.stringify(payload), 'utf8')
+  fs.renameSync(tmp, file)
+  return { ok: true, count: list.length, updatedAt: payload.updatedAt }
+}
+
+export function deleteHistory(chatDir, cardId) {
+  const file = historyFile(chatDir, cardId)
+  if (!file) return { ok: false, error: 'missing-card-id' }
+  try {
+    if (fs.existsSync(file)) fs.unlinkSync(file)
+  } catch (e) {
+    return { ok: false, error: String((e && e.message) || e) }
+  }
+  return { ok: true }
+}
+
+/** 历史卡片清单（面板「最近对话」用，按更新时间倒序） */
+export function listHistories(chatDir, limit = 30) {
+  try {
+    if (!fs.existsSync(chatDir)) return []
+    return fs
+      .readdirSync(chatDir)
+      .filter((f) => f.endsWith('.json'))
+      .map((f) => {
+        try {
+          const raw = JSON.parse(fs.readFileSync(path.join(chatDir, f), 'utf8'))
+          const messages = Array.isArray(raw.messages) ? raw.messages : []
+          return {
+            cardId: String(raw.cardId || f.replace(/\.json$/, '')),
+            updatedAt: Number(raw.updatedAt || 0),
+            count: messages.length,
+            preview: String(messages.find((m) => m.role === 'user')?.content || '').slice(0, 60),
+          }
+        } catch {
+          return null
+        }
+      })
+      .filter(Boolean)
+      .sort((a, b) => b.updatedAt - a.updatedAt)
+      .slice(0, limit)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 删卡联动入口：清掉该卡的缓存对话文件。
+ * 调用方（cardFiles 的 DELETE /__card/<id>）按 best-effort 处理返回值：
+ * 删卡本身已成功时，缓存清理失败只记日志，不把响应翻成 500。
+ * @param {string} root 工程根
+ * @param {string} cardId
+ */
+export function deleteChatHistory(root, cardId) {
+  return deleteHistory(chatHistoryDir(root), cardId)
+}

package/dist/vendored/server/core/index.js

@@ -12,7 +12,7 @@
  */
 import { createSyncMiddleware, createPreviewMiddleware, createLoginCredentialsMiddleware } from './cardSync.js'
 import { createSliceUploadMiddleware } from './sliceUpload.js'
-import { createCardFilesMiddleware } from './cardFiles.js'
+import { createCardFilesMiddleware, refreshCardList } from './cardFiles.js'
 import { createSaveMiddleware } from './cardSave.js'
 import { createImportMetaMiddleware } from './cardImportMeta.js'
 import { createHistoryMiddleware } from './cardHistory.js'
@@ -57,6 +57,12 @@ export {
   createCardImageMiddleware,
   createOpenFolderMiddleware,
   createCodeBridgeMiddleware,
+  // refreshCardList：standalone / --preview 服务在文件变动后重建卡片列表快照要用它。
+  // 必须经本入口导出，**不要**让包外调用方直接 import './cardFiles.js' —— 发布态
+  // dist/core.js 被构造成桥到包内快照（./vendored/server/core/index.js），而写死的仓库相对路径
+  // 在安装态会解析到包外（0.14.0 的 standalone.js 就因此 ERR_MODULE_NOT_FOUND）。
+  // build.mjs 门禁 D 会静态拦住这类「dist 里解析不到的相对引用」。
+  refreshCardList,
   createLogMiddleware,
   installLogMirror,
   subscribeLog,
@@ -72,7 +78,8 @@ export {
  * @param {{ use: (mw: Function) => void }} app
  * @param {{ root: string, viteServer?: import('vite').ViteDevServer | null, upstream?: string, notify?: (data: object, event?: string) => void, watchFile?: (file: string, cb: () => void) => { close: () => void }, allowDispatch?: boolean }} opts
  *   - upstream：FinMall 远端站点基址（来自 FINMALL_BASE_URL），资源代理回源用；空串表示不回源。
- *   - notify：SSE 推送入口（cardbuddy 的 /__events hub）；代码桥经它推 bridge 事件，缺省时静默降级。
+ *   - notify：SSE 推送入口（cardbuddy 的 /__events hub）；卡片改名的 card-renamed 广播、代码桥
+ *     bridge 事件都经它推送，缺省时静默降级。
  *   - watchFile：代码桥单文件监听能力注入（chokidar 版）；缺省代码桥用 fs.watch 兜底。
  *   - allowDispatch：AI 的 card_patch 是否走 card_write 管线（历史快照 + 校验）。仓库内运行由
  *     「root === 仓库根」自动成立；cardbuddy 发布态代码快照在包内，需宿主显式开启。
@@ -85,7 +92,7 @@ export function mountCoreMiddlewares(app, { root, viteServer = null, upstream =
   // 写 src/slices/manifest.json 映射并把卡片里的 /slices/ 引用改写为 @filestore/ 线上地址。
   // 仅在用户点击时触发，没有任何自动上传路径。
   app.use(createSliceUploadMiddleware({ root }))
-  app.use(createCardFilesMiddleware({ root }))
+  app.use(createCardFilesMiddleware({ root, notify }))
   app.use(createSaveMiddleware({ root }))
   app.use(createHistoryMiddleware({ root }))
   app.use(createValidateMiddleware({ root }))