cardbuddy 0.11.0 → 0.12.1

package/dist/vendored/mcp/tools.mjs

@@ -0,0 +1,268 @@
+import * as client from './client.mjs'
+
+/**
+ * MCP 工具清单（16 个）+ 分发。
+ * 工具描述里写死了两处语义边界（与 renderStatus/screenshot 端点、方案文档三处一致）：
+ *   - card_render_status 只保证「结构合法 + 绑定可解析 + 渲染不抛错」，**不保证画得对**；
+ *   - card_screenshot 才代表「浏览器里实际画出来长什么样」。
+ * Agent 误把 render_status.ok 当成「画对了」是整个闭环的头号坑，故反复强调。
+ * card_scaffold / card_add_component 为离线脚手架工具（P5），直接复用 scaffold lib，
+ * 不依赖 dev server，把「生成骨架 / 插入组件」从手写样板降级为一次工具调用。
+ * card_route_input 为离线建卡输入路由（Workflow 0），直接复用 skill 的 route_input.mjs 判定器：
+ * 识别到 Sketch MeaXure 标注导出时强制先转 sketch-spec-to-card 前处理，防止直接读整图建卡。
+ */
+
+export const TOOLS = [
+  {
+    name: 'card_list',
+    description:
+      '列出工作区所有卡片（id / 名称 / pageId）。优先走 dev server 的 GET /__cards；dev server 未启动时自动降级为直接扫描 src/cards/。',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'card_read',
+    description:
+      '读取单张卡片的 schema.json（组件树/属性/样式/事件）与 data.json（输入参数默认值）。优先走 GET /__card/:id；未启动 dev server 时降级为直接读盘。',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string', description: '卡片 id，对应 src/cards/<id>' } },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'card_write',
+    description:
+      '把编辑后的 schema / data 写回 src/cards/<id>/（仅允许写 schema.json / data.json，白名单由服务端校验）。【闭环收口】写前自动把当前版本存为历史快照（可被 card_rollback 撤销；snapshot:false 可关闭），写完默认自动跑 validate + render_status（dev server 在线时）把校验结果一起返回；设 verify:false 可关闭。dev server 未启动时降级为直接写盘 + 本地 Python 硬校验（render_status 需 dev server，会标注 skipped）。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: '卡片 id' },
+        schema: { type: 'object', description: '新 schema.json 内容（可只传要改的字段，整体替换）' },
+        data: { type: 'object', description: '新 data.json 内容' },
+        verify: { type: 'boolean', description: '写后是否自动校验，默认 true' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'card_validate',
+    description:
+      '对单卡跑契约校验（Python 校验器）：组件/属性/样式/表达式/data.json 一致性。返回 {ok, errors, warnings, durationMs}。优先走 GET /__validate/:id；未启动 dev server 时降级为直接子进程跑 Python。这是「硬」契约（CI 真卡口）。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        noData: { type: 'boolean', description: 'true=跳过 data.json 一致性检查' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'card_render_status',
+    description:
+      'SSR 渲染自检：返回结构统计 + 绑定/运行时/渲染错误 + JSAPI 清单。⚠️ 语义边界：只保证「结构合法 + 绑定可解析 + 渲染不抛错」，**不保证画得对**——视觉正确性以 card_screenshot 为准。必须 dev server 已启动（npm run dev），不支持离线降级。',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'card_node_models',
+    description:
+      '读取单卡的「可编辑字段结构树」（Task #5 暴露的 Property-tree 模型，对应 dev server 的 GET /__node-models/:id）。返回每个节点的 {componentId, className, properties, style, directives, eventactions, components}，其中每个字段含 itemKey/itemName/itemType/itemValue/itemValueFrom/itemTypeRange/options(iParamList|iTypeList)/children——AI 无需解析 raw DSL + component-meta 即可知道「某节点有哪些可改字段、各自类型与枚举」。⚠️ 该模型是只读视图，改卡仍走 card_write（整体替换）；必须 dev server 已启动（npm run dev），不支持离线降级。',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string', description: '卡片 id，对应 src/cards/<id>' } },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'card_screenshot',
+    description:
+      '无头浏览器截图（走系统 Chrome）。format=json 返回 {mime,width,height,base64}；format=png 直接返回一张图片供多模态阅读（白底纯净卡片，等价于 ?chrome=off）。⚠️ 这是「画面对不对」的唯一真相来源。优先走 dev server；未启动时自动降级到独立渲染器（临时 Vite + 临时 Chrome，不占 5180/8787）。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        format: { type: 'string', enum: ['json', 'png'], default: 'json' },
+        width: { type: 'number', default: 390 },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'card_sync',
+    description:
+      '经已登录的 FinMall 浏览器会话从远端拉取最新卡片写回 src/cards（复用 finmall-card-sync）。必须 dev server 已启动且已登录 FinMall，不支持离线降级。',
+    inputSchema: {
+      type: 'object',
+      properties: { cardCode: { type: 'string', description: '指定卡片 code；留空=同步全部' } },
+      required: [],
+    },
+  },
+  {
+    name: 'card_save',
+    description:
+      '把当前卡片 schema 经已登录浏览器写回 FinMall（IDC10010.do）。必须 dev server 已启动且已登录 FinMall，不支持离线降级。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        schema: { type: 'object', description: '当前卡片 schema（必须含 pageId）' },
+        code: { type: 'string' },
+        skeletonScreen: { type: 'string' },
+      },
+      required: ['schema'],
+    },
+  },
+  {
+    name: 'card_slice_upload',
+    description:
+      '把指定卡片引用的本地切图（src/slices）经已登录浏览器上传到 FinMall 图片库（CC0000.do），写「本地文件 ↔ 线上地址」映射 src/slices/manifest.json，并把该卡 schema.json / data.json 里的 "/slices/<name>" 引用改写为返回的 @filestore/… 线上地址。按 sha256 判重：内容未变的切图直接复用已有地址不重复上传；本地切图真源保留不动。**仅按需调用，不存在自动上传**——推送版本 / 出真机预览前，若卡片仍引用 /slices/ 就先跑本工具，否则线上卡片取不到图。必须 dev server 已启动且已登录 FinMall，不支持离线降级。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cardId: { type: 'string', description: '卡片 id，对应 src/cards/<id>（上传与改写都只作用于这张卡）' },
+        force: { type: 'boolean', description: 'true=忽略 sha256 判重，强制重新上传（会得到新的线上地址）' },
+      },
+      required: ['cardId'],
+    },
+  },
+  {
+    name: 'card_import_meta',
+    description:
+      '读取单卡的「导入来源元数据」（Phase E 可追溯性侧车，对应 dev server 的 GET /__import-meta/:id）。返回 {source, interface, baseUrl, appId, workspaceId, cardId, cardCode, cardName, syncedAt, tool, dirty, lastExport}——AI/skill 可据此判断「这张卡是不是从远端同步来的、何时导入、上一次导出读回校验是否通过」。无侧车（本地新建、未同步）时返回 {error:"import-meta not found"}。只读，不污染 DSL。必须 dev server 已启动，不支持离线降级。',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string', description: '卡片 id，对应 src/cards/<id>' } },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'card_route_input',
+    description:
+      '建卡输入路由（dsl-card-generator SKILL.md §8 Workflow 0 的机械判定器，离线）：判定用户给的输入形态，返回 kind + 判定证据 + 下一步可直接执行的命令。kind=meaxure-export（Sketch MeaXure 标注导出目录：index.html 内嵌 artboards + preview/ 画板整图 + assets/ 切图）时**必须先经 sketch-spec-to-card 前处理**——next 直接给出 parse_meaxure.py（--src/--out/--draft/--build）与 cluster_states.py（--out UI/<稿名>）两条命令，禁止直接读 preview/ 整图建卡；若 UI/*/manifest.json 的 export 字段已匹配该导出，则 preprocess.needed=false 并给出存量产物路径，不重复跑管线。其余 kind：ui-bundle（要素包 → Workflow A 逐卡，overlay_dialog 不产卡）/ image（单张设计稿 → Workflow A 纯视觉推断）/ card-dir（已存在 schema.json → Workflow B 改卡）/ unknown（判不出，需向用户确认，ok=false）。无需 dev server。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description:
+            '输入路径：MeaXure 标注导出目录，或 UI 要素包目录（也可传其中的 manifest.json / spec.json / prompt.md / card-N.png），或卡片目录 src/cards/<id>，或设计稿图片。相对路径按工程根解析，支持 ~ 展开。',
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'card_scaffold',
+    description:
+      '新建卡片双模：① intent 模式——秒出「合法最小」骨架（blank|list|detail|form|dialog|tab|canvas-head），data.json 由 inputParams 反推自洽；② from 模式——整卡模板克隆（references/card_templates.json 提供簇→代表卡路由，如 dialog→creditCardBill、list→revenueAnalysis、tab→DepositHolding、amount→myLoan），只重写 pageId/name，版式纪律与绑定范式原样继承，封面不复制（定稿后重新渲染）。从零建卡用 intent，有近似存量卡用 from。无需 dev server。默认写到 src/cards；传 outBase 可改输出根；force=true 覆盖已存在目录。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        intent: { type: 'string', enum: ['blank', 'list', 'detail', 'form', 'dialog', 'tab', 'canvas-head'], description: '卡片意图（决定骨架结构）；from 存在时忽略' },
+        from: { type: 'string', description: '整卡模板克隆：源模板卡 id（references/card_templates.json 的 template.sourceCard）' },
+        id: { type: 'string', description: '新卡片 id，对应 src/cards/<id>' },
+        name: { type: 'string', description: '卡片名称（写入 schema.name），可不传' },
+        outBase: { type: 'string', description: '输出根目录，默认 src/cards' },
+        platform: { type: 'string', description: '平台码，默认 002' },
+        force: { type: 'boolean', description: 'true=覆盖已存在的目录' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'card_add_component',
+    description:
+      '向已有卡片的某个「容器节点」插入一个「合法最小组件」（P5 脚手架）。定位 parent（必须是容器，有 slots 或 ListLayout/GridLayout）→ 在默认插槽追加一个由 scaffold lib 生成的合法节点 → 写回 → 离线跑 Python 硬校验并把结果带回。纪律：只增不改、不重排 componentId、不碰孤儿字段。text 以 $ 开头视为变量绑定（itemValueFrom=1），否则常量；click=true 给节点挂一个 customAction 点击动作骨架；setProps 可单点覆盖属性（等价 CLI 的 --set-prop key=value）。无需 dev server。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: '卡片 id，对应 src/cards/<id>' },
+        parent: { type: 'string', description: '目标容器节点的 componentId' },
+        className: { type: 'string', description: '要插入的组件类型，如 Text/Row/Button/Image/Column' },
+        text: { type: 'string', description: '可选文案/绑定表达式；$ 开头视为变量绑定' },
+        click: { type: 'boolean', description: 'true=附带 customAction 点击动作骨架' },
+        setProps: {
+          type: 'array',
+          description:
+            '可选属性覆盖，等价 CLI 的 --set-prop key=value。数组元素可为 "key=value" 字符串或 {key,value} 对象；value 以 $ 开头视为变量绑定（itemValueFrom=1）。存在时优先于 text（text 仅在未覆盖 value 时兜底）。',
+          items: {},
+        },
+      },
+      required: ['id', 'parent', 'className'],
+    },
+  },
+  {
+    name: 'card_history',
+    description:
+      '列出单卡的编辑历史快照元数据（ts / 时间 / 字节数 / 节点数），快照由编辑器编辑或 card_write 写卡时自动累积（.history/，上限 30）。只返回元数据不返回整份 schema，用于选择回滚目标。优先走 dev server GET /__history/:id；未启动时降级为直接读盘。',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string', description: '卡片 id，对应 src/cards/<id>' } },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'card_rollback',
+    description:
+      '把卡片回滚到指定历史快照的 schema（默认最新快照 ts，即「撤销上一次写卡」）。安全语义：回滚前会自动把当前版本另存为新快照，回滚本身可再次回滚撤销；写回走 card_write 同一收口（默认自动 validate + render_status 校验并返回结果）。离线可降级（直接写盘 + Python 硬校验）。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: '卡片 id，对应 src/cards/<id>' },
+        ts: { type: 'number', description: '目标快照 ts（来自 card_history）；缺省 = 最新快照' },
+        verify: { type: 'boolean', description: '回滚写回后是否自动校验，默认 true' },
+      },
+      required: ['id'],
+    },
+  },
+]
+
+/** 把工具名 + 参数分发到 client 函数；未知工具返回标准错误对象 */
+export async function dispatch(name, args = {}) {
+  switch (name) {
+    case 'card_list':
+      return client.cardList()
+    case 'card_read':
+      return client.cardRead(args.id)
+    case 'card_write':
+      return client.cardWrite(args.id, { schema: args.schema, data: args.data }, { verify: args.verify !== false })
+    case 'card_validate':
+      return client.cardValidate(args.id, { noData: !!args.noData })
+    case 'card_render_status':
+      return client.cardRenderStatus(args.id)
+    case 'card_node_models':
+      return client.cardNodeModels(args.id)
+    case 'card_screenshot':
+      return client.cardScreenshot(args.id, { format: args.format || 'json', width: args.width || 390 })
+    case 'card_sync':
+      return client.cardSync({ cardCode: args.cardCode })
+    case 'card_save':
+      return client.cardSave({ schema: args.schema, code: args.code, skeletonScreen: args.skeletonScreen })
+    case 'card_slice_upload':
+      return client.sliceUpload({ cardId: args.cardId, force: args.force })
+    case 'card_import_meta':
+      return client.cardImportMeta(args.id)
+    case 'card_route_input':
+      return client.cardRouteInput({ path: args.path })
+    case 'card_scaffold':
+      return client.cardScaffold({ intent: args.intent, id: args.id, name: args.name, outBase: args.outBase, platform: args.platform, force: args.force, from: args.from })
+    case 'card_add_component':
+      return client.cardAddComponent({
+        id: args.id,
+        parent: args.parent,
+        className: args.className,
+        text: args.text,
+        click: args.click,
+        setProps: args.setProps,
+      })
+    case 'card_history':
+      return client.cardHistory(args.id)
+    case 'card_rollback':
+      return client.cardRollback(args.id, { ts: args.ts, verify: args.verify !== false })
+    default:
+      return { error: 'unknown-tool', message: `未知道具: ${name}` }
+  }
+}

package/dist/{server-core → vendored/server/core}/ai-chat.js

@@ -50,11 +50,14 @@ import path from 'node:path'
 import fs from 'node:fs'
 import os from 'node:os'
 import { execFile, spawn, spawnSync } from 'node:child_process'
-import { fileURLToPath } from 'node:url'
+import { SNAPSHOT_ROOT, skillsDirFor, resolveSkillPath, normalizeSkillRel } from './skillPaths.js'
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-const REPO_ROOT = path.resolve(__dirname, '..', '..')
-const SKILLS_DIR = path.join(REPO_ROOT, 'skills')
+/**
+ * 快照根：仓库内运行 = 真仓库根；cardbuddy 发布态 = 包内 dist/vendored（构建期内联的迷你仓库快照，
+ * 其下同样有 skills/ 与 mcp/，故本文件里 `../../mcp/tools.mjs` 这类相对引用两种形态都成立）。
+ * 它只作「随代码走的那份资源」（mcp 工具 / 技能文档）的兜底根；卡片工程根一律用中间件的 root。
+ */
+const REPO_ROOT = SNAPSHOT_ROOT
 
 /** 单卡片最多保留的消息条数，超出从头部裁剪（避免历史无限增长撑爆上下文与磁盘） */
 const MAX_HISTORY_MESSAGES = 200
@@ -83,7 +86,15 @@ async function loadTools() {
 
 // ---- System prompt：精简协议 + 按需参考索引 ----
 
-const SKILL_REFS_DIR = path.join(SKILLS_DIR, 'dsl-card-generator', 'references')
+/** 技能库根：项目内 skills/ 优先，缺失时回退随包发布的快照（cardbuddy 未跑 init 也能用） */
+function skillsDir(root) {
+  return skillsDirFor(root)
+}
+
+/** dsl-card-generator 的 references 目录：系统提示词「按需参考索引」的来源 */
+function skillRefsDir(root) {
+  return path.join(skillsDirFor(root), 'dsl-card-generator', 'references')
+}
 /** 参考索引的一句话说明：够模型选对文件即可，全文不进上下文 */
 const SKILL_REF_HINTS = {
   'rules.md': '卡片生成铁律（card_write 前必读：结构 / 绑定 / 样式红线）',
@@ -121,15 +132,17 @@ let _systemPromptCache = null
  * 此前整份注入两份 SKILL.md + rules.md（约 125KB / 数万 token），上下文臃肿会显著放大
  * 推理模型的空转思考（实测单轮 reasoning 4 分钟不收敛、界面一直「思考中」）。
  */
-function buildSystemPrompt({ shellAllowed = false, vision = false, autoApprove = DEFAULT_AUTO_APPROVE } = {}) {
-  const cacheKey = `${shellAllowed ? 'shell' : 'base'}${vision ? '+vision' : ''}+aa:${autoApprove}`
+function buildSystemPrompt({ shellAllowed = false, vision = false, autoApprove = DEFAULT_AUTO_APPROVE, root = '' } = {}) {
+  const refsDir = skillRefsDir(root)
+  // 缓存键带上实际命中的技能库：仓库内与消费者项目（init 释放的副本）文档集可能不同
+  const cacheKey = `${shellAllowed ? 'shell' : 'base'}${vision ? '+vision' : ''}+aa:${autoApprove}+sk:${skillsDir(root)}`
   if (_systemPromptCache && _systemPromptCache.key === cacheKey) return _systemPromptCache.text
   // 免确认策略要如实写进协议：模型若以为「每次都要用户点确认」，会主动停下来等批准 / 把命令甩给用户
   const skillAuto = autoApproves(autoApprove, 'skill_exec')
   const shellAuto = autoApproves(autoApprove, 'shell_exec')
   const lines = []
   for (const entry of SKILL_DOC_ENTRIES) {
-    const abs = path.join(SKILLS_DIR, entry.path)
+    const abs = path.join(skillsDir(root), entry.path)
     let size = 0
     try {
       size = fs.statSync(abs).size
@@ -139,10 +152,10 @@ function buildSystemPrompt({ shellAllowed = false, vision = false, autoApprove =
     lines.push(`- ${entry.path}（${Math.max(1, Math.round(size / 1024))}KB）：${entry.hint}`)
   }
   try {
-    for (const name of fs.readdirSync(SKILL_REFS_DIR)) {
+    for (const name of fs.readdirSync(refsDir)) {
       let st
       try {
-        st = fs.statSync(path.join(SKILL_REFS_DIR, name))
+        st = fs.statSync(path.join(refsDir, name))
       } catch {
         continue
       }
@@ -151,7 +164,7 @@ function buildSystemPrompt({ shellAllowed = false, vision = false, autoApprove =
     }
     // 范式片段是子目录，不列出来模型根本不知道存在（曾经为此反推 expand_ir 源码猜字段形状）
     const snippets = fs
-      .readdirSync(path.join(SKILL_REFS_DIR, 'recipe_snippets'))
+      .readdirSync(path.join(refsDir, 'recipe_snippets'))
       .filter((f) => f.endsWith('.json'))
       .sort()
     if (snippets.length) {
@@ -259,13 +272,14 @@ const CARD_PATCH_TOOL = {
   type: 'function',
   function: {
     name: 'card_patch',
-    description: '按 JSON 点路径（数组用数字段）对卡片 schema/data 做最小修改并写回；大卡必用本工具，禁止用 card_write 整包重写。路径必须先用 card_grep 拿真实路径——schema 的节点树是 view.components[].slots[].components[]（不是 view.children）。路径中段不存在会直接报错（不再静默新建分支），确要新建传 create:true。仓库根下走 card_write 管线（带历史快照与校验）。',
+    description: '按 JSON 点路径（数组用数字段）对卡片 schema/data 做最小修改并写回；大卡必用本工具，禁止用 card_write 整包重写。路径必须先用 card_grep 拿真实路径——schema 的节点树是 view.components[].slots[].components[]（不是 view.children）。路径中段不存在会直接报错（不再静默新建分支），确要新建传 create:true。patches（改/增）与 deletes（删）至少给一个，可只删不改（清理无用样式项、多余节点）。仓库根下走 card_write 管线（带历史快照与校验）。',
     parameters: {
       type: 'object',
       properties: {
         id: { type: 'string', description: '卡片 id' },
         patches: {
           type: 'array',
+          description: '要写入的 {path,value} 列表；只删除时可省略（此时必须给 deletes）',
           items: {
             type: 'object',
             properties: {
@@ -275,11 +289,11 @@ const CARD_PATCH_TOOL = {
             required: ['path', 'value'],
           },
         },
-        deletes: { type: 'array', items: { type: 'string' }, description: '要删除的 JSON 点路径' },
+        deletes: { type: 'array', items: { type: 'string' }, description: '要删除的 JSON 点路径；可单独使用（只删不改）' },
         target: { type: 'string', enum: ['schema', 'data'], description: '默认 schema' },
         create: { type: 'boolean', description: '路径中段不存在时是否新建分支（默认 false = 响亮报错）' },
       },
-      required: ['id', 'patches'],
+      required: ['id'],
     },
   },
 }
@@ -337,16 +351,44 @@ function applyByPath(doc, p, setter, { create = false } = {}) {
   setter(cur, segs[segs.length - 1])
 }
 
-async function cardPatch(root, args, dispatch) {
+async function cardPatch(root, args, dispatch, { allowDispatch = false } = {}) {
   const { id, patches = [], deletes = [], target = 'schema' } = args || {}
-  if (!Array.isArray(patches) || !patches.length) throw new Error('缺少 patches')
+  if (!Array.isArray(patches)) throw new Error('patches 必须是数组')
+  if (!Array.isArray(deletes)) throw new Error('deletes 必须是数组')
+  // 「只删不改」是合法操作（清理无用样式项 / 多余节点）；真正的错误是两个都空 —— 空补丁什么都不做，
+  // 却会照样走一遍 card_write 管线、平白多存一份历史快照，所以在这里响亮拒掉。
+  if (!patches.length && !deletes.length) throw new Error('patches 与 deletes 至少给一个（空补丁无意义）')
   const file = path.join(root, 'src', 'cards', String(id || ''), target === 'data' ? 'data.json' : 'schema.json')
   const doc = JSON.parse(fs.readFileSync(file, 'utf8'))
   const create = args.create === true
   for (const pt of patches) applyByPath(doc, pt.path, (obj, k) => (obj[k] = pt.value), { create })
-  for (const d of deletes) applyByPath(doc, d, (obj, k) => delete obj[k], { create })
-  // 仓库根：走 card_write 管线（历史快照 + validate/render_status）；其它根（测试/自定义）直接落盘
-  if (path.resolve(root) === REPO_ROOT && dispatch) {
+  // 删数组元素必须 splice：早先用 delete obj[k]，在数组上只留一个 null 空洞
+  // （properties 变成 [null, {...}]），补丁报「成功」却把 schema 写成稀疏数组，渲染与校验随后就崩。
+  // 同一父数组里删多项时按原始下标从大到小删 —— splice 会让后面的索引左移，升序删会误删邻居。
+  const orderedDeletes = [...deletes].sort((a, b) => {
+    const sa = String(a).split('.')
+    const sb = String(b).split('.')
+    const pa = sa.slice(0, -1).join('.')
+    const pb = sb.slice(0, -1).join('.')
+    if (pa !== pb) return pa < pb ? -1 : 1
+    const na = Number(sa[sa.length - 1])
+    const nb = Number(sb[sb.length - 1])
+    return Number.isFinite(na) && Number.isFinite(nb) ? nb - na : 0
+  })
+  for (const d of orderedDeletes)
+    applyByPath(
+      doc,
+      d,
+      (obj, k) => {
+        if (Array.isArray(obj)) obj.splice(Number(k), 1)
+        else delete obj[k]
+      },
+      { create },
+    )
+  // 工程根：走 card_write 管线（历史快照 + validate/render_status）；其它根（测试/自定义）直接落盘。
+  // 仓库内运行由「root === 仓库根」判定；cardbuddy 发布态快照根在包内、永不等于工程根，
+  // 故由宿主显式 allowDispatch 开启（它已把 CARD_ROOT 指到同一个工程根，dispatch 落点一致）。
+  if (dispatch && (allowDispatch || path.resolve(root) === REPO_ROOT)) {
     const res = await dispatch('card_write', { id, [target]: doc })
     return { ok: true, via: 'card_write', patches: patches.length, deletes: deletes.length, write: res }
   }
@@ -458,9 +500,12 @@ function resolveSkillScript(root, script) {
   if (!SKILL_SCRIPT_RE.test(rel)) {
     throw new Error(`只能执行 skills/<skill>/scripts/ 下的 .mjs / .js / .py 脚本（收到：${rel}）；其余命令用 shell_exec`)
   }
-  const abs = path.resolve(root, rel)
-  if (!abs.startsWith(path.join(root, 'skills') + path.sep)) throw new Error('非法路径：脚本必须在仓库 skills/ 目录内')
-  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) throw new Error(`脚本不存在：${rel}`)
+  // 项目内 skills/ 优先；cardbuddy 安装态尚未释放技能库时回退包内快照。
+  // normalizeSkillRel 拒绝绝对路径与任何 `..` 片段，resolveSkillPath 只在候选 skills 根内查找。
+  const clean = normalizeSkillRel(rel)
+  if (!clean) throw new Error('非法路径：脚本必须在仓库 skills/ 目录内')
+  const abs = resolveSkillPath(root, clean)
+  if (!abs || !fs.statSync(abs).isFile()) throw new Error(`脚本不存在：${rel}`)
   return { rel, abs, bin: path.extname(abs).toLowerCase() === '.py' ? pythonBin() : 'node' }
 }
 
@@ -1255,21 +1300,14 @@ const SKILL_DOC_EXT = new Set(['.md', '.json', '.txt', '.csv'])
 function skillRead(root, args) {
   const name = String(args?.path || '').trim().replace(/^\.?\/+/u, '')
   if (!name) throw new Error('缺少 path')
-  const refsDir = path.join(root, 'skills', 'dsl-card-generator', 'references')
-  const rel = name.includes('/') ? name.replace(/^skills\//, '') : path.join('dsl-card-generator', 'references', name)
-  const full = path.resolve(path.join(root, 'skills'), rel)
-  const skillsRoot = path.join(root, 'skills')
-  if (!full.startsWith(skillsRoot + path.sep)) throw new Error('非法路径：只能读 skills/ 目录内的文档')
+  const rel = name.includes('/') ? name.replace(/^skills\//, '') : `dsl-card-generator/references/${name}`
+  // 越界（绝对路径 / 任何 `..` 片段）先判非法，再谈存在性 —— 与 skill_exec 同一套闸。
+  if (!normalizeSkillRel(rel)) throw new Error('非法路径：只能读 skills/ 目录内的文档')
+  // 项目内 skills/ 优先，缺失时回退随包发布的技能快照（cardbuddy 安装态未跑 init 也能读文档）。
+  const full = resolveSkillPath(root, rel)
+  if (!full) throw new Error(`文档不存在：skills/${rel}`)
   if (!SKILL_DOC_EXT.has(path.extname(full).toLowerCase())) throw new Error('只能读文档（.md / .json / .txt / .csv）；跑脚本用 skill_exec')
-  if (!fs.existsSync(full) || !fs.statSync(full).isFile()) {
-    // 测试根等场景下 skills/ 可能不存在：退回模块加载时的仓库 references 目录
-    const fallback = path.resolve(fs.existsSync(refsDir) ? refsDir : SKILL_REFS_DIR, name)
-    if (!name.includes('/') && fallback.startsWith(SKILL_REFS_DIR + path.sep) && fs.existsSync(fallback)) {
-      const text = fs.readFileSync(fallback, 'utf8')
-      return text.length <= SKILL_READ_MAX ? text : `${text.slice(0, SKILL_READ_MAX)}\n…（已截断，省略 ${text.length - SKILL_READ_MAX} 字符）`
-    }
-    throw new Error(`文档不存在：skills/${rel}`)
-  }
+  if (!fs.statSync(full).isFile()) throw new Error(`文档不存在：skills/${rel}`)
   const text = fs.readFileSync(full, 'utf8')
   if (text.length <= SKILL_READ_MAX) return text
   return `${text.slice(0, SKILL_READ_MAX)}\n…（已截断，省略 ${text.length - SKILL_READ_MAX} 字符）`
@@ -1732,7 +1770,7 @@ function describePath(target) {
  * 搜索根先剪掉「被其它根包含」的子根：否则同一文件会在父 / 子根各命中一次，被误判成重名歧义而返回空。
  * 同一个根里出现多个同名同尺寸文件才算歧义，此时不猜。
  */
-async function locateDropped({ name, relPath = '', size = -1 }) {
+async function locateDropped({ name, relPath = '', size = -1, root = '' }) {
   const fileName = String(name || '').trim()
   if (!fileName) return null
   const wantSize = Number(size) >= 0 ? Number(size) : -1
@@ -1770,6 +1808,7 @@ async function locateDropped({ name, relPath = '', size = -1 }) {
   pushRoot(path.join(home, 'Desktop'))
   pushRoot(path.join(home, 'Downloads'))
   pushRoot(path.join(home, 'Documents'))
+  if (root) pushRoot(root)
   pushRoot(REPO_ROOT)
   pushRoot(path.dirname(REPO_ROOT))
   pushRoot(home)
@@ -2693,6 +2732,9 @@ function toOpenAiMessages(messages) {
  */
 export function createAiChatMiddleware(opts = {}) {
   const root = opts.root ? path.resolve(opts.root) : REPO_ROOT
+  // card_patch 是否走 card_write 管线（历史快照 + validate/render_status）：
+  // 仓库内运行由「root === 仓库根」自动成立；cardbuddy 发布态快照根在包内，由宿主显式开启。
+  const allowDispatch = opts.allowDispatch === true
   /** 对话记录落盘目录（.cache/ 已在 .gitignore）：随 root 走，测试可用临时根隔离 */
   const chatDir = path.join(root, '.cache', 'ai-chats')
 
@@ -3007,6 +3049,7 @@ export function createAiChatMiddleware(opts = {}) {
         name: body.name,
         relPath: body.relPath || '',
         size: Number.isFinite(Number(body.size)) ? Number(body.size) : -1,
+        root,
       })
       if (!found) return sendJson(req, res, 404, { error: 'not-located' })
       const info = describePath(found)
@@ -3093,6 +3136,7 @@ export function createAiChatMiddleware(opts = {}) {
         shellAllowed: Boolean(defaults.shellAllowed),
         vision: visionOn,
         autoApprove: defaults.autoApprove,
+        root,
       })
     } catch (e) {
       return sendJson(req, res, 500, { error: 'tools-load-failed', message: String((e && e.message) || e) })
@@ -3540,7 +3584,7 @@ export function createAiChatMiddleware(opts = {}) {
                 result = cardGrep(root, parsedArgs)
                 break
               case 'card_patch':
-                result = await cardPatch(root, parsedArgs, dispatch)
+                result = await cardPatch(root, parsedArgs, dispatch, { allowDispatch })
                 break
               case 'fs_read':
                 result = fsRead(root, parsedArgs, mountedRoots)

package/dist/{server-core → vendored/server/core}/browser.js

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

package/dist/{server-core → vendored/server/core}/cardSave.js

@@ -4,12 +4,14 @@ import { pathToFileURL } from 'node:url'
 import { fileURLToPath } from 'node:url'
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
-const skillDir = path.resolve(process.cwd(), 'skills', 'finmall-card-sync')
-const skillPath = path.join(skillDir, 'scripts', 'api_batch_sync.mjs')
 import { recordExport } from './cardImportMeta.js'
 import { checkPushAllowed } from './cardListCache.js'
 import { assertRemoteSource, findCardDir } from './cardSidecar.js'
 import { log } from './logger.js'
+import { resolveSkillPathOrProject } from './skillPaths.js'
+
+/** 远端保存脚本相对 skills/ 的路径（与「同步」共用 finmall-card-sync） */
+const SYNC_SCRIPT_REL = 'finmall-card-sync/scripts/api_batch_sync.mjs'
 
 /**
  * 远端保存（写回 FinMall）服务端处理。
@@ -94,7 +96,10 @@ export function createSaveMiddleware({ root }) {
       // 骨架屏：线上编辑器始终传 SVG 缩略图；本地无生成器，传空串（仅影响编辑器列表缩略图）。
       const skeletonScreen = typeof payload.skeletonScreen === 'string' ? payload.skeletonScreen : ''
       try {
-        const mod = await import(pathToFileURL(skillPath).href)
+        // 脚本按「项目根 skills/ → 随包技能快照」解析：cardbuddy 安装态无 skills/ 时也能保存。
+        const mod = await import(
+          pathToFileURL(resolveSkillPathOrProject(root || process.cwd(), SYNC_SCRIPT_REL)).href
+        )
         const { response, verified } = await mod.saveCardToRemote(schema, { skeletonScreen })
         // 导出可追溯（Phase E）：把远端保存的读回校验结果写进导入元数据侧车。
         // 注意：目录按 cardCode 命名，必须按 pageId 反查到正确的 src/cards/<cardCode>/。

package/dist/{server-core → vendored/server/core}/cardSync.js

@@ -5,6 +5,10 @@ import { writeFile, mkdir } from 'node:fs/promises'
 import { checkPushAllowed } from './cardListCache.js'
 import { assertRemoteSource } from './cardSidecar.js'
 import { log, fmtBytes } from './logger.js'
+import { resolveSkillPathOrProject } from './skillPaths.js'
+
+/** finmall-card-sync 的批量同步脚本（同步 / 远端预览共用），相对 skills/ */
+const SYNC_SCRIPT_REL = 'finmall-card-sync/scripts/api_batch_sync.mjs'
 
 /**
  * 预览「同步远程数据」按钮的服务端处理：经已认证的 FinMall 浏览器会话拉取最新卡片写回 src/cards。
@@ -34,13 +38,7 @@ export function createSyncMiddleware({ root }) {
         return res.end(JSON.stringify({ error: 'invalid json', message: String(e.message) }))
       }
       try {
-        const skillPath = path.join(
-          root,
-          'skills',
-          'finmall-card-sync',
-          'scripts',
-          'api_batch_sync.mjs'
-        )
+        const skillPath = resolveSkillPathOrProject(root, SYNC_SCRIPT_REL)
         const { syncCards } = await import(pathToFileURL(skillPath).href)
         const summary = await syncCards({
           cardCode: payload.cardCode || undefined,
@@ -160,13 +158,7 @@ export function createPreviewMiddleware({ root }) {
         }
       }
       try {
-        const skillPath = path.join(
-          root,
-          'skills',
-          'finmall-card-sync',
-          'scripts',
-          'api_batch_sync.mjs'
-        )
+        const skillPath = resolveSkillPathOrProject(root, SYNC_SCRIPT_REL)
         const { previewCardRemote } = await import(pathToFileURL(skillPath).href)
         const result = await previewCardRemote(payload.schema)
         log.ok('远端预览完成', {

package/dist/{server-core → vendored/server/core}/cardValidate.js

@@ -5,6 +5,11 @@ import { execFile, execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
+import { resolveSkillPathOrProject } from './skillPaths.js'
+
+/** 校验脚本相对 skills/ 的固定路径（导出供 MCP 复用） */
+const VALIDATE_SCRIPT_REL = 'dsl-card-generator/scripts/validate_schema.py'
+
 /**
  * 契约校验端点（L0 闭环之一）。
  *
@@ -18,15 +23,13 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url))
  * @param {{ root: string }} opts
  */
 
-/** 校验脚本在仓库根下的固定相对路径（导出供 MCP 复用） */
+/**
+ * 校验脚本绝对路径（导出供 MCP 复用）。
+ * 优先项目根下的 skills/；缺失时回退随包发布的技能快照 —— cardbuddy 安装态即便
+ * 没跑过 `cardbuddy init`（项目里还没有 skills/）也能正常校验。
+ */
 export function scriptPath(root) {
-  return path.join(
-    root,
-    'skills',
-    'dsl-card-generator',
-    'scripts',
-    'validate_schema.py',
-  )
+  return resolveSkillPathOrProject(root, VALIDATE_SCRIPT_REL)
 }
 
 /** 解析可用的 python 解释器；找不到返回 null（导出供 MCP 复用） */