cardbuddy 0.22.0 → 0.24.0

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

@@ -4,7 +4,7 @@ import path from 'node:path'
 
 /**
  * 远端资源代理：把预览里引用的站内资源路径（@filestore / /minio / /fastdfs …）
- * 回源到 FinMall 上游站点并落盘缓存。所有跨网络回源逻辑集中在本模块维护。
+ * 回源到远端上游站点并落盘缓存。所有跨网络回源逻辑集中在本模块维护。
  */
 
 /**

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

@@ -1,4 +1,4 @@
-import { devApiBase } from '../../tools/finmall-env.mjs'
+import { devApiBase } from '../../tools/platform-env.mjs'
 
 /**
  * 共享浏览器单例 + 卡片页面加载（screenshot.js / bbox.js 共用）。

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

@@ -0,0 +1,202 @@
+/**
+ * 卡片编译端点：把本地 schema.json 编译成两套可投放产物
+ *
+ * POST /__compile-cards  body { cardIds: string[], targetDir?: string }
+ *   → { ok, outDir, cards: [{ id, name, ok, version, templates, nodes, clientBytes, h5Bytes, warnings, error }] }
+ *
+ * 产物布局（客户端 / H5 分两个目录，同属一个父目录）：
+ *   <targetDir>/                    ← 默认 <工程根>/flame-build
+ *     client/<cardCode>/<templateCode>/index.{json,css,databinding,data,js,style}
+ *     h5/<cardCode>.js
+ *     manifest.json                 ← 目录内产物清单（累计）+ 本次编译批次（lastBatch）
+ *
+ * 编译逻辑本身在 flameCompile/ 下（1:1 迁移自 flame-release-mange 的 card/exporter），
+ * 本文件只负责「读盘 → 编译 → 落盘 → 汇报」，不含任何渲染规则。
+ *
+ * 覆盖语义：产物是构建缓存，允许直接覆盖——
+ *   - 逐文件 writeFileSync 截断重写，同卡重复编译结果字节一致；
+ *   - 写之前先删该卡的整个模板目录，模板数量变少（如删掉列表）时不会残留 _sub_/_item；
+ *   - 编译失败不删旧产物（先编译成功再落盘），上一次的好产物不会被半途失败搞坏；
+ *   - manifest 同理不丢信息：按 id 并入已有记录（本次为准），只保留磁盘上仍有产物的卡。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { compileCard } from './flameCompile/index.js'
+import { log } from './logger.js'
+
+/** 单次编译上限（与导出的 500 同口径） */
+const MAX_COMPILE_CARDS = 500
+
+/** 卡片 id 白名单：只允许字母数字下划线中划线，杜绝目录穿越 */
+const CARD_ID_RE = /^[A-Za-z0-9_-]+$/
+
+/**
+ * 读已有 manifest 的 cards 段。缺失 / 损坏 / 结构不对一律当空数组 ——
+ * 一份旧清单坏掉不该让整批编译失败（它是构建产物，不是输入）。
+ */
+function readPrevManifestCards(manifestPath) {
+  try {
+    const mf = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+    return Array.isArray(mf.cards) ? mf.cards : []
+  } catch {
+    return []
+  }
+}
+
+export function createCompileMiddleware({ root }) {
+  const readJsonBody = (req, res, cb) => {
+    let body = ''
+    req.setEncoding('utf8')
+    req.on('data', (c) => {
+      body += c
+      if (body.length > 1024 * 1024) req.destroy()
+    })
+    req.on('end', () => {
+      try {
+        cb(JSON.parse(body || '{}'))
+      } catch (e) {
+        res.statusCode = 400
+        res.setHeader('Content-Type', 'application/json')
+        res.end(JSON.stringify({ ok: false, error: 'invalid json', message: String(e.message) }))
+      }
+    })
+  }
+
+  const sendJson = (res, status, obj) => {
+    res.statusCode = status
+    res.setHeader('Content-Type', 'application/json')
+    res.setHeader('Cache-Control', 'no-store')
+    res.end(JSON.stringify(obj))
+  }
+
+  return function compileMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const method = (req.method || 'GET').toUpperCase()
+    if (pathname !== '/__compile-cards' || method !== 'POST') return next()
+
+    readJsonBody(req, res, (body) => {
+      const rawIds = Array.isArray(body.cardIds)
+        ? body.cardIds.filter((x) => typeof x === 'string')
+        : []
+      // 去重：同一张卡在同一批里传两次没有意义（第二次会把第一次刚写的产物删掉再写一遍），只留首个
+      const ids = [...new Set(rawIds)]
+      if (!ids.length) return sendJson(res, 400, { ok: false, error: 'cardIds 不能为空' })
+      if (ids.length > MAX_COMPILE_CARDS) {
+        return sendJson(res, 400, { ok: false, error: `单次最多编译 ${MAX_COMPILE_CARDS} 张卡片` })
+      }
+
+      const bad = ids.filter((id) => !CARD_ID_RE.test(id))
+      if (bad.length) return sendJson(res, 400, { ok: false, error: `非法卡片 id: ${bad.join(', ')}` })
+
+      // 目标目录：默认工程根下 flame-build；自定义时限制在工程根内，避免误写到系统目录
+      const outDir = body.targetDir
+        ? path.resolve(root, String(body.targetDir))
+        : path.join(root, 'flame-build')
+      const rootResolved = path.resolve(root)
+      if (!outDir.startsWith(rootResolved + path.sep)) {
+        return sendJson(res, 400, { ok: false, error: 'targetDir 必须位于工程目录内' })
+      }
+
+      const clientDir = path.join(outDir, 'client')
+      const h5Dir = path.join(outDir, 'h5')
+      fs.mkdirSync(clientDir, { recursive: true })
+      fs.mkdirSync(h5Dir, { recursive: true })
+
+      const results = []
+      const manifestCards = []
+
+      for (const id of ids) {
+        const schemaPath = path.join(root, 'src', 'cards', id, 'schema.json')
+        if (!fs.existsSync(schemaPath)) {
+          results.push({ id, ok: false, error: 'schema.json 不存在' })
+          continue
+        }
+
+        try {
+          const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'))
+          const compiled = compileCard(schema, { cardCode: id })
+
+          // 清掉该卡的旧产物（模板数量可能变化）
+          const cardClientDir = path.join(clientDir, id)
+          if (fs.existsSync(cardClientDir)) fs.rmSync(cardClientDir, { recursive: true, force: true })
+
+          for (const template of compiled.client) {
+            const dir = path.join(cardClientDir, template.code)
+            fs.mkdirSync(dir, { recursive: true })
+            for (const [file, content] of Object.entries(template.files)) {
+              // index.style 是 SM4 密文（Buffer），必须按字节原样落盘；
+              // 其余是 utf8 文本，显式声明编码便于排查乱码。
+              if (Buffer.isBuffer(content)) fs.writeFileSync(path.join(dir, file), content)
+              else fs.writeFileSync(path.join(dir, file), content, 'utf8')
+            }
+          }
+
+          fs.writeFileSync(path.join(h5Dir, `${id}.js`), compiled.h5, 'utf8')
+
+          results.push({
+            id,
+            ok: true,
+            version: compiled.version,
+            templates: compiled.client.length,
+            nodes: compiled.stats.nodes,
+            clientBytes: compiled.stats.clientBytes,
+            h5Bytes: compiled.stats.h5Bytes,
+            warnings: compiled.warnings,
+          })
+          manifestCards.push({
+            id,
+            name: schema.name || '',
+            version: compiled.version,
+            templates: compiled.client.map((t) => t.code),
+            nodes: compiled.stats.nodes,
+            clientBytes: compiled.stats.clientBytes,
+            h5Bytes: compiled.stats.h5Bytes,
+            warnings: compiled.warnings,
+          })
+        } catch (e) {
+          log.warn(`[compile] ${id} 编译失败: ${e.message}`)
+          results.push({ id, ok: false, error: String(e.message || e) })
+        }
+      }
+
+      const okCount = results.filter((r) => r.ok).length
+      // manifest 描述的是「这个目录里有什么」，因此跨批次累计：按 id 合并，本次记录覆盖同 id 旧记录。
+      // 只按本次批次重写会得到一份自相矛盾的清单——磁盘上 10 张卡，manifest 里只有最后勾的 2 张。
+      // 旧记录还要过一道「磁盘上仍有产物」的存在性检查：换过 targetDir、手工删过文件时它会失真。
+      const manifestPath = path.join(outDir, 'manifest.json')
+      const merged = new Map()
+      for (const c of readPrevManifestCards(manifestPath)) {
+        if (!c || typeof c.id !== 'string' || !c.id) continue
+        const hasArtifacts =
+          fs.existsSync(path.join(clientDir, c.id)) || fs.existsSync(path.join(h5Dir, `${c.id}.js`))
+        if (hasArtifacts) merged.set(c.id, c)
+      }
+      for (const c of manifestCards) merged.set(c.id, c)
+      const manifest = {
+        generatedAt: new Date().toISOString(),
+        outDir,
+        // 目录内卡片总数（累计），不是本批张数
+        count: merged.size,
+        cards: [...merged.values()].sort((a, b) => String(a.id).localeCompare(String(b.id))),
+        // 本次请求的批次结果，便于回溯「这一次又编了什么」
+        lastBatch: {
+          requested: ids.length,
+          ok: okCount,
+          failed: ids.length - okCount,
+          ids,
+        },
+      }
+      fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8')
+
+      log.info(`[compile] 编译完成 ${okCount}/${ids.length} → ${outDir}`)
+      return sendJson(res, 200, {
+        ok: okCount > 0,
+        outDir,
+        clientDir,
+        h5Dir,
+        cards: results,
+      })
+    })
+  }
+}

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

@@ -0,0 +1,324 @@
+/**
+ * 大卡 schema 的**读方向折叠**（structure digest）。
+ *
+ * 为什么需要：`schema.json` 是编辑器持久化格式，单卡紧凑 JSON 实测最大 239KB / 167 节点。
+ * 读大卡时旧行为是「JSON 字符串取前 12000 字符」，而 JSON 的键序是
+ * `version / pageId / name / desc / platform / dictionary / view` —— `dictionary` 排在 view 前面，
+ * 30 条 inputParams 就吃掉 10.5KB。实测 overseaTransfer（239KB / 167 节点）的 12k 切片里
+ * **componentId 出现 0 次**：模型花 12k 字符只拿到参数声明 + 根节点的半张样式表，
+ * 一个组件都没看到，于是转头用 card_grep 反复试路径，白走 2~5 步（每步 20~40k 输入）。
+ *
+ * 同一个 12k 预算下，全节点骨架只要 4.7k：167 行 `componentId(ClassName) 「主文本」`。
+ * 所以折叠的目标不是「少给」，而是**把预算从「前 N 个字节」换成「N 个节点的地图」**：
+ *   - 骨架：全部节点的身份 + 主文本 + 层级（模型据此能点到任何一处）
+ *   - 参数：inputParams 压缩成一行 key:type=default
+ *   - 不给样式与属性全量 —— 要就 `card_read {id, node:"<componentId>"}` 定向取子树
+ *   - 同时给出该子树的真实 JSON 路径，`card_patch` 可直接用，省掉 card_grep 摸索
+ */
+
+/** 骨架里主文本的截断长度：够认人即可，不搬正文 */
+const TEXT_MAX = 24
+/** 层级缩进最多叠到第几层（更深的保持同缩进，防止 30 层缩进把行宽吃光） */
+const DEPTH_INDENT_MAX = 8
+/** 骨架占预算的比例，其余留给参数表 / 元信息 / 下一步指引 */
+const TREE_BUDGET_RATIO = 0.66
+/** 参数表预算上限 */
+const PARAM_BUDGET = 2400
+
+/**
+ * 取节点主值（等价于渲染出来的那段字）。
+ * `itemValueFrom`: 0=常量 / 1=变量 / 2=图片（与 ir-format.md 的 p / v / pi 对应）。
+ * @returns {string} 空串表示该节点没有主值
+ */
+function mainValue(node) {
+  const props = Array.isArray(node.properties) ? node.properties : []
+  for (const p of props) {
+    if (!p || p.itemKey !== 'value') continue
+    const from = String(p.itemValueFrom ?? '0')
+    if (from === '2') return '[图片]'
+    const raw = p.itemValue
+    if (from === '1') {
+      const name = typeof raw === 'string' ? raw : raw && typeof raw === 'object' ? (raw.value ?? raw.key) : ''
+      const s = name ? String(name) : ''
+      if (!s) return '[变量]'
+      // itemValue 本身就形如 `$remark`，不要再补一个 $（曾出现 `$$remark`）
+      return s.startsWith('$') ? s : `$${s}`
+    }
+    if (raw == null || typeof raw === 'object') return ''
+    return String(raw)
+  }
+  return ''
+}
+
+/**
+ * 事件摘要：把 `eventactions[]` 压成 `eventKey:actionType(N字)`，多个逗号分隔。
+ *
+ * 为什么必须进骨架：全库 366 个节点有事件、代码合计 324KB，单卡最多 27.5KB。
+ * 事件是卡片里真正的业务逻辑，却藏在 8 层路径下
+ * （`eventactions[0].action.properties[0].itemValue.code`）。骨架不给这个标记，
+ * 模型拿到 167 行结构图也不知道哪个节点有事件，只能 `jq` 手数路径去扫 ——
+ * 历史日志里同型命令跨 3 张卡出现 12 次以上，每次一整步（20~40k 输入）。
+ *
+ * 只标「有事件 + 什么事件 + 代码多长」，不搬代码本身：读代码走
+ * `card_read {id, node:"<componentId>"}`，那一棵子树才几千字符。
+ * @returns {string} 空串表示该节点无事件
+ */
+function eventSummary(node) {
+  const ea = node && node.eventactions
+  if (!Array.isArray(ea) || !ea.length) return ''
+  const parts = []
+  for (const a of ea) {
+    if (!a || typeof a !== 'object') continue
+    const key = (a.event && a.event.eventKey) || '?'
+    const type = (a.action && a.action.actionType) || '?'
+    const props = Array.isArray(a.action && a.action.properties) ? a.action.properties : []
+    const fn = props.find((p) => p && p.itemKey === 'function')
+    const iv = fn && fn.itemValue
+    // 运行时取 `code || compiled`（见 preview 的 actionCode），长度按同口径算
+    const code = iv && typeof iv === 'object' ? String(iv.code || iv.compiled || '') : ''
+    parts.push(`${key}:${type}${code ? `(${code.length}字)` : ''}`)
+  }
+  return parts.join(',')
+}
+
+/**
+ * 全卡事件代码总字符数（运行时口径 `code || compiled`）。
+ * 只用于 meta 报规模，帮模型判断「要不要一次读完」。
+ */
+function countEventChars(view) {
+  let total = 0
+  const walk = (n) => {
+    if (!n || typeof n !== 'object') return
+    const ea = n.eventactions
+    if (Array.isArray(ea)) {
+      for (const a of ea) {
+        const props = Array.isArray(a && a.action && a.action.properties) ? a.action.properties : []
+        const fn = props.find((p) => p && p.itemKey === 'function')
+        const iv = fn && fn.itemValue
+        if (iv && typeof iv === 'object') total += String(iv.code || iv.compiled || '').length
+      }
+    }
+    for (const c of n.components || []) walk(c)
+    for (const sl of n.slots || []) for (const c of (sl && sl.components) || []) walk(c)
+  }
+  walk(view)
+  return total
+}
+
+/**
+ * 子节点列表，带**可直接用于 card_patch 的真实 JSON 点路径**。
+ * 节点树是 `view.components[]` 与 `view.slots[].components[]` 两种容器，不是 `view.children`。
+ * @returns {Array<{node: object, path: string}>}
+ */
+function childEntries(node, nodePath) {
+  const out = []
+  if (Array.isArray(node.components)) {
+    node.components.forEach((c, i) => {
+      if (c && typeof c === 'object') out.push({ node: c, path: `${nodePath}.components.${i}` })
+    })
+  }
+  if (Array.isArray(node.slots)) {
+    node.slots.forEach((sl, j) => {
+      const inner = Array.isArray(sl && sl.components) ? sl.components : []
+      inner.forEach((c, k) => {
+        if (c && typeof c === 'object') out.push({ node: c, path: `${nodePath}.slots.${j}.components.${k}` })
+      })
+    })
+  }
+  return out
+}
+
+/** 深度优先遍历，产出行列表（带真实路径） */
+function flatten(view) {
+  const rows = []
+  const walk = (node, nodePath, depth) => {
+    const v = mainValue(node)
+    rows.push({
+      depth,
+      cid: typeof node.componentId === 'string' ? node.componentId : '',
+      cls: typeof node.className === 'string' ? node.className : '',
+      text: v ? v.slice(0, TEXT_MAX) : '',
+      events: eventSummary(node),
+      path: nodePath,
+    })
+    for (const e of childEntries(node, nodePath)) walk(e.node, e.path, depth + 1)
+  }
+  walk(view, 'view', 0)
+  return rows
+}
+
+/** 骨架单行渲染（缩进=层级；componentId(className) 「主文本」 ⚡事件） */
+function renderRow(r) {
+  const indent = '  '.repeat(Math.min(r.depth, DEPTH_INDENT_MAX))
+  // 根节点通常没有 componentId，别渲染成 `(无id)(Root)` 这种噪音
+  const head = r.cid ? `${r.cid}(${r.cls})` : r.cls || '(无类名)'
+  const ev = r.events ? ` ⚡${r.events}` : ''
+  return `${indent}${head}${r.text ? ` 「${r.text}」` : ''}${ev}`
+}
+
+/**
+ * inputParams 压成一行 `key:type=default`。
+ * 富字段（rule / children / desc）不进 —— 需要结构化细节时读 node 或 fs_read data.json。
+ * 只给**标量**默认值：对象/数组默认值是 mock 数据（实测 `myCardList` 一条就 400 字符），
+ * 它要的是「存在」而不是「内容」，全搬进来等于把 dictionary 换个地方重新塞满预算。
+ */
+function renderParams(inputParams, budget = PARAM_BUDGET) {
+  const list = Array.isArray(inputParams) ? inputParams : []
+  const parts = []
+  let used = 0
+  let listed = 0
+  for (const p of list) {
+    if (!p || typeof p !== 'object') continue
+    const key = String(p.key ?? '')
+    if (!key) continue
+    const type = String(p.type ?? 'any')
+    const def = p.defaultValue
+    const isScalar = typeof def === 'string' || typeof def === 'number' || typeof def === 'boolean'
+    let suffix = ''
+    if (isScalar && def !== '') {
+      const shown = typeof def === 'string' && def.length > 24 ? `${def.slice(0, 24)}…` : def
+      suffix = `=${JSON.stringify(shown)}`
+    }
+    const seg = `${key}:${type}${suffix}`
+    if (used + seg.length + 2 > budget) break
+    parts.push(seg)
+    used += seg.length + 2
+    listed++
+  }
+  const more = list.length - listed
+  return {
+    text: parts.join(', ') + (more > 0 ? `, …（另有 ${more} 个未列出，用 fs_read data.json 看全量）` : ''),
+    listed,
+    total: list.length,
+  }
+}
+
+/**
+ * 生成大卡结构摘要。
+ * @param {object} schema 完整 schema 对象
+ * @param {object} data 派生 data（用于参数表兜底；通常与 inputParams.defaultValue 一致）
+ * @param {{id?: string, budget?: number}} opts budget ≈ 该工具结果的字符档位
+ * @returns {{meta: object, tree: string, treeTruncated: boolean, params: string, next: string[]}|null}
+ */
+export function digestCard(schema, data, { id = '', budget = 12000 } = {}) {
+  const view = schema && typeof schema.view === 'object' ? schema.view : null
+  if (!view) return null
+  const rows = flatten(view)
+  const compactBytes = JSON.stringify(schema).length
+  const treeBudget = Math.max(1200, Math.floor(budget * TREE_BUDGET_RATIO))
+
+  const lines = []
+  let used = 0
+  let listed = 0
+  for (const r of rows) {
+    const line = renderRow(r)
+    // 留 1 字节给换行；超预算即停（宁可少列，也不让骨架本身被 clipToolResult 二次腰斩）
+    if (used + line.length + 1 > treeBudget) break
+    lines.push(line)
+    used += line.length + 1
+    listed++
+  }
+  const truncated = listed < rows.length
+
+  // 截断时补一段「被截掉的区块分布」：不列全文，但让模型知道还有哪些区域、各多少节点，
+  // 从而能直接 node 定向读，而不是重新猜。
+  let restNote = ''
+  if (truncated) {
+    const rest = rows.slice(listed)
+    const byCls = new Map()
+    for (const r of rest) {
+      const k = `${r.cls}`
+      byCls.set(k, (byCls.get(k) || 0) + 1)
+    }
+    const dist = [...byCls].sort((a, b) => b[1] - a[1]).slice(0, 12).map(([k, n]) => `${k}×${n}`).join(' ')
+    // 事件节点尤其要点名：截断区里的事件是「看不见但一定要改」的那部分
+    const restEv = rest.filter((r) => r.events)
+    const evNote = restEv.length
+      ? `\n其中 ${restEv.length} 个节点带事件：${restEv.slice(0, 10).map((r) => `${r.cid || '(根)'}[${r.events}]`).join(' ')}${restEv.length > 10 ? ' …' : ''}`
+      : ''
+    restNote =
+      `\n… 还有 ${rest.length} 个节点未列出（已达骨架预算）。它们的组件分布：${dist}${evNote}` +
+      `\n用 card_read {id:"${id}", node:"<componentId>"} 定向读某棵子树；` +
+      `未列出的组件 id 可用 card_grep 按文案/类名查，或 fs_read schema.json 按 offset 续读。`
+  }
+
+  const params = renderParams(schema?.dictionary?.inputParams)
+  const evRows = rows.filter((r) => r.events)
+  const evChars = countEventChars(view)
+  const next = [
+    `**带 ⚡ 标记的节点有事件**（click / onReady / onMeasured…），圆括号里是代码字符数；读它 → card_read {id:"${id}", node:"<componentId>"}，返回该子树含完整 JS（比整卡小一到两个数量级）`,
+    `改值/改样式/改事件 → card_patch {id:"${id}", patches:[{path:"@<componentId>/eventactions.0.action.properties.0.itemValue.code", value:"…"}]}；@ 前缀自动解析成真实 JSON 路径，不用先 card_grep；写 code 时 compiled 会自动同步，不必手写第二份`,
+    `看某节点的样式/属性 → card_read {id:"${id}", node:"<componentId>"}`,
+    `要看原文 → fs_read {"path":"src/cards/${id}/schema.json","offset":<字节偏移>}`,
+  ]
+
+  return {
+    meta: {
+      id,
+      pageId: schema?.pageId ?? '',
+      platform: schema?.platform ?? '',
+      root: view.className || '',
+      nodes: rows.length,
+      nodesListed: listed,
+      compactBytes,
+      /** 有事件的节点数 / 事件代码总字符（不含在白给的 tree 里，要按 node 定向读） */
+      eventNodes: evRows.length,
+      eventChars: evChars,
+    },
+    tree: lines.join('\n') + restNote,
+    treeTruncated: truncated,
+    params: params.text,
+    next,
+    hasData: !!(data && typeof data === 'object' && Object.keys(data).length),
+  }
+}
+
+/**
+ * 按 componentId 找节点，返回它的真实 JSON 路径与祖先链。
+ * @returns {{path: string, node: object, depth: number, ancestors: Array<{cid: string, cls: string, path: string}>}|null}
+ */
+export function findNodeByComponentId(schema, componentId) {
+  const view = schema && typeof schema.view === 'object' ? schema.view : null
+  const want = String(componentId || '')
+  if (!view || !want) return null
+  let hit = null
+  const walk = (node, nodePath, depth, ancestors) => {
+    if (hit) return
+    if (node.componentId === want) {
+      hit = { path: nodePath, node, depth, ancestors: ancestors.slice() }
+      return
+    }
+    const chain = depth === 0 ? [] : ancestors
+    for (const e of childEntries(node, nodePath)) {
+      walk(e.node, e.path, depth + 1, [...chain, { cid: node.componentId || '', cls: node.className || '', path: nodePath }])
+      if (hit) return
+    }
+  }
+  walk(view, 'view', 0, [])
+  return hit
+}
+
+/**
+ * 把 `@<componentId>` 开头的路径解析成真实 JSON 点路径。
+ * 支持三种写法：
+ *   `@text_dw`                    → 节点自身路径
+ *   `@text_dw/s.properties`       → 用 `/` 分隔相对段（推荐：componentId 本身可能含 `.`？实际不会，
+ *                                    但相对段里全是数字下标与字段名，用 `/` 更不易歧义）
+ *   `@text_dw.properties.0...`    → 用 `.` 续写相对段
+ * 找不到组件时抛错（响亮失败，不静默新建分支）。
+ * @returns {string} 真实点路径
+ */
+export function resolveComponentPath(schema, atPath) {
+  const s = String(atPath || '')
+  if (!s.startsWith('@')) return s
+  const body = s.slice(1)
+  // componentId 的合法字符集是字母数字 _ -，遇到首个 `/` 或 `.` 就断开
+  const m = body.match(/^([A-Za-z0-9_-]+)(.*)$/)
+  if (!m) throw new Error(`@ 路径缺少 componentId：${s}`)
+  const cid = m[1]
+  const rest = m[2].replace(/^\//, '').replace(/^\./, '')
+  const found = findNodeByComponentId(schema, cid)
+  if (!found) throw new Error(`找不到 componentId=${cid}；先用 card_read 看结构图，或 card_grep 按文案定位`)
+  if (!rest) return found.path
+  return `${found.path}.${rest}`
+}

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

@@ -10,7 +10,7 @@ import { resolveCardDir } from './cardOpenFolder.js'
 /**
  * 卡片导出端点（编辑器「卡片网格预览 → 勾选 → 导出」的服务端实现）。
  *
- * 产物契约（对桌面两份 FinMall 导出样本的逆向结论，详见
+ * 产物契约（对桌面两份远端导出样本的逆向结论，详见
  * docs/卡片导出产物逆向分析与导出功能.md）：
  *   <targetDir>/<yyMMddHHmmss+4位序号>/        ← 临时文件夹（完成后删除）
  *     cards.json                               ← 卡片清单（cardPO 数组，殿后写入）
@@ -49,7 +49,7 @@ const EXPORT_JOB_TIMEOUT_MS = Number(process.env.CARDBUDDY_EXPORT_JOB_TIMEOUT_MS
 /** 图片下载超时（与资源代理回源超时同口径） */
 const IMAGE_FETCH_TIMEOUT_MS = 12000
 
-/** 封面候选扩展名（与 finmall-card-sync 的 findExistingCover 同集） */
+/** 封面候选扩展名（与 platform-card-sync 的 findExistingCover 同集） */
 const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg'])
 
 /**
@@ -60,7 +60,7 @@ const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.
  */
 const COVER_FILESTORE_PREFIX = '@filestore/dzqd-download'
 
-/** 平台状态常量：两份样本恒为三端全平台（与 FinMall 发布接口默认平台集一致） */
+/** 平台状态常量：两份样本恒为三端全平台（与远端发布接口默认平台集一致） */
 const PLATFORM_STATUS = ['iOS', 'Android', 'HarmonyOS']
 
 /** 最小合法骨架屏 SVG：样本为线上编辑器按布局生成，本地不做布局推测，占位保证字段非空 */
@@ -255,7 +255,7 @@ function stampFolderName(targetDir, now = new Date()) {
   return base + Math.random().toString(36).slice(2, 6).padStart(4, '0')
 }
 
-/** 找本地封面预览图（<cardId>.<ext>）；没有返回 null（与 finmall-card-sync 同规则） */
+/** 找本地封面预览图（<cardId>.<ext>）；没有返回 null（与 platform-card-sync 同规则） */
 function findExistingCover(cardDir, id) {
   let entries = []
   try {
@@ -639,7 +639,7 @@ async function exportOneCard({ root, id, outDir, upstream, buildPreview }) {
         fs.copyFileSync(src, dest)
       } else {
         const url = filestoreUrlFor(ref, upstream)
-        if (!url) throw new Error('未配置 FinMall 上游地址，无法下载 @filestore 图片')
+        if (!url) throw new Error('未配置远端上游地址，无法下载 @filestore 图片')
         const res = await fetch(url, {
           headers: { 'User-Agent': 'Mozilla/5.0', Referer: upstream ? `${upstream}/` : '' },
           signal: AbortSignal.timeout(IMAGE_FETCH_TIMEOUT_MS),

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

@@ -14,7 +14,7 @@ import { buildDataFromSchema } from './buildDataFromSchema.js'
  * 空白卡必须显式归零压掉注入，否则新卡自带隐性间距且属性面板显示「未设置」。
  * 形状取自存量卡根节点（见 style-meta.json：marginType / paddingType，'0' = 全边统一值）。
  * 同一形状还有两份内联副本（禁跨包 import）：skills/dsl-card-generator lib/scaffold.mjs、
- * skills/finmall-card-sync api_batch_sync.mjs 的 buildBlankSchema —— 改这里必须同步改那两处。
+ * skills/platform-card-sync api_batch_sync.mjs 的 buildBlankSchema —— 改这里必须同步改那两处。
  */
 function blankResetStyle() {
   return {

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

@@ -5,7 +5,7 @@ import { writeCardFiles } from './cardFiles.js'
 import { log } from './logger.js'
 import { resolveSkillPathOrProject } from './skillPaths.js'
 
-const SYNC_SCRIPT_REL = 'finmall-card-sync/scripts/api_batch_sync.mjs'
+const SYNC_SCRIPT_REL = 'platform-card-sync/scripts/api_batch_sync.mjs'
 
 /** 读取 JSON 请求体（1MB 上限防失控） */
 function readJsonBody(req) {

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

@@ -45,7 +45,7 @@ export function buildImportMeta({ baseUrl, appId, workspaceId, cardId, cardCode,
     // 推文件名去读卡目录根的封面，picUrl 为空会退化成目录路径、直接抛异常。真值只在同步时可获得。
     remote: remote || null,
     syncedAt: new Date().toISOString(),
-    tool: 'finmall-card-sync',
+    tool: 'platform-card-sync',
     dirty: false, // 本地编辑后偏离导入镜像为 true（重置为导入镜像后回 false）
     lastExport: null, // 远端保存（/__save）后写入校验结果
     editedAt: null, // 最近一次本地编辑时间（每次写盘都更新），供「按修改时间排序」