cardbuddy 0.13.1 → 0.13.2

package/dist/vendored/skills/dsl-card-ai/SKILL.md

@@ -26,6 +26,57 @@ dsl-card 项目的 AI 技能层。它是**编排层**：把卡片编辑任务拆
 7. **dev server 前置**：`card_render_status` / `card_node_models` / `card_import_meta` 必须 dev server 已启动，未起时返回 `dev-server-required`；`card_sync` / `card_save` / `card_slice_upload` 除 dev server 外还需已登录 FinMall。（本仓库 `npm run dev` 默认 5180，由 Vite 把 `/__*` 代理到 8787；`cardbuddy init` 出来的工程 `npm run dev` 直接是 8787。）`card_list` / `card_read` / `card_write` / `card_validate` / `card_history` / `card_rollback` 会自动降级为直接读盘/写盘/跑 Python（render_status 标 skipped）；`card_screenshot` 降级到包内独立离线渲染器（`source:'standalone'`）。
 8. **建卡先判输入形态**（Workflow D）：收到设计稿输入先调 `card_route_input({path})`，按返回的 `kind` 分流，**不要凭感觉决定要不要跑上游**。判为 `meaxure-export`（Sketch MeaXure 标注导出）时必须先经 `sketch-spec-to-card` 前处理产出 `UI/<稿名>/` 要素包，**禁止直接读 `preview/` 整图建卡**；`preprocess.needed=false` 表示已前处理过，直接复用存量产物。`card_route_input` 纯离线，不需要 dev server。
 
+## 前置：`card_*` 工具从哪来（agent 里看不到工具先看这里）
+
+本技能只**编排** MCP 工具，不自带工具实现。工具由 `dsl-card` MCP server（stdio，JSON-RPC 2.0）提供，
+命名空间 `mcp__dsl-card__card_*` —— 前缀里的 `dsl-card` 就是注册时的 server 名，改名则前缀对不上。
+server 入口是 `mcp/server.mjs`（零第三方依赖），工具清单在 `mcp/tools.mjs`，实现在 `mcp/client.mjs`。
+
+**agent 里看不到 `card_*` 工具 = 没注册或注册错了**，按所处工程二选一：
+
+在 dsl-card 主干仓库（内核开发）：
+
+```toml
+# ~/.codex/config.toml
+[mcp_servers.dsl-card]
+command = "npm"
+args = ["run", "--silent", "mcp"]
+cwd = "/绝对路径/dsl-card"        # 必须是仓库根，否则 CARD_ROOT 指错、找不到 src/cards
+```
+
+在 `cardbuddy init` 出来的消费者工程（cardbuddy ≥ 0.13.0 随包提供 `--mcp` 入口）：
+
+```toml
+[mcp_servers.dsl-card]
+command = "/绝对路径/工程/node_modules/.bin/cardbuddy"
+args = ["--mcp"]
+```
+
+Claude / Cursor 等用 JSON 形式的等价配置：`{"mcpServers":{"dsl-card":{"command":"…","args":["…"]}}}`
+（command / args 同上；`cardbuddy init` 生成的 README 里有带注释的完整样例）。
+
+三条会静默踩到的坑：
+
+1. **经 `npm run` 启动必须加 `--silent`**：`npm run` 会把 `> 包名 脚本名` 横幅打到 **stdout**，而 stdout
+   是 JSON-RPC 协议信道，多一行客户端就解析失败。症状是 agent 报「server 启动失败 / 没有工具」，
+   而你手跑同一条命令却一切正常。直接调 `.bin/cardbuddy --mcp` 或 `node mcp/server.mjs` 无此问题。
+2. **别裸跑消费者工程里的 `node_modules/cardbuddy/dist/vendored/mcp/server.mjs`**：`client.mjs` 在模块
+   顶层就 resolve `CARD_ROOT` / `CARD_API_BASE`（不是每次调用时读），绕过 `cardbuddy --mcp` 包装层时
+   前者会落到包内快照目录（`card_list` 恒返回 0 张卡）、后者回退 5180（消费者工程没有 Vite 把 `/__*`
+   代理到 8787，于是 `card_render_status` 直接 `dev-server-required`）。
+3. **`cwd` 必须是工程根**：卡片读写落在 `<工程根>/src/cards/`。
+
+不依赖 agent 的一行自检（看回包即可判断 server 本身是否健康）：
+
+```bash
+printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
+  | npm run --silent mcp        # 消费者工程换成 ./node_modules/.bin/cardbuddy --mcp
+# 健康：回一行 JSON，result.tools 共 16 个
+```
+
+排查时加 `CARDBUDDY_MCP_VERBOSE=1`：注入后的 `root=` / `apiBase=` 会打到 **stderr**（不污染协议流）。
+各工具是否还需另起本地服务，见 §0.7 与 §1 表格的「离线降级」列。
+
 ## 1. 可用 MCP 工具（dsl-card 服务器，命名空间 `mcp__dsl-card__card_*`）
 
 | 工具 | 返回 | 离线降级 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cardbuddy",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "description": "Local dev service for the CardBuddy card editor — decouples card CRUD (sync/save/validate/render-status/screenshot) from the static public editor, so the editor can be deployed to any static host while each developer runs a local service against their own card source.",
   "type": "module",
   "bin": {