@szc-ft/mcp-szcd-client 0.35.0 → 0.38.0

package/opencode-extension/skills/local-browser-test/tests/integration/pr-08.test.js

@@ -0,0 +1,293 @@
+/**
+ * PR #8 集成测试（增强 apiCall step — v3 走法 P）
+ * 跑法：node --test tests/integration/pr-08.test.js
+ *
+ * 测试范围（不依赖真实浏览器）：
+ *   - buildCookieHeader: 共享 cookie
+ *   - assertApiResponse: L1 status / L2 header / L3 body / L4 responseTime
+ *   - matchValue 操作符: $gt / $lt / $contains / $regex / $in
+ *   - executeApiCallStep: 集成调用（用 mock server 或直接调 axios）
+ *   - 端到端字段: assert / captureTrace / noRetry / strategy / headers / tags
+ *   - build 副本同步
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SKILL_DIR = path.resolve(__dirname, '../../');
+
+const { buildCookieHeader, assertApiResponse, createTimingsInterceptor, executeApiCallStep } = await import(
+  '../../lib/api-call-executor.js'
+);
+
+describe('PR #8: buildCookieHeader（3 个核心场景）', () => {
+  it('空 cookies → 空字符串', () => {
+    assert.equal(buildCookieHeader([]), '');
+    assert.equal(buildCookieHeader(null), '');
+    assert.equal(buildCookieHeader(undefined), '');
+  });
+
+  it('多 cookies → "name1=v1; name2=v2" 格式', () => {
+    const cookies = [
+      { name: 'session', value: 'abc123' },
+      { name: 'csrf', value: 'xyz789' }
+    ];
+    const header = buildCookieHeader(cookies);
+    assert.ok(header.includes('session=abc123'));
+    assert.ok(header.includes('csrf=xyz789'));
+    assert.ok(header.includes('; '));
+  });
+
+  it('带 domain 过滤（targetOrigin）', () => {
+    const cookies = [
+      { name: 'a', value: '1', domain: 'example.com' },
+      { name: 'b', value: '2', domain: 'other.com' }
+    ];
+    const header = buildCookieHeader(cookies, 'https://example.com');
+    assert.ok(header.includes('a=1'));
+    assert.ok(!header.includes('b=2'), 'b 不应包含');
+  });
+});
+
+describe('PR #8: assertApiResponse L1 status（3 个场景）', () => {
+  it('L1: status 完全匹配 → passed', () => {
+    const result = assertApiResponse({ status: 200, data: {}, headers: {} }, { status: 200 });
+    assert.equal(result.passed, true);
+    assert.equal(result.checks[0].level, 1);
+  });
+
+  it('L1: status 不匹配 → failed', () => {
+    const result = assertApiResponse({ status: 401, data: {}, headers: {} }, { status: 200 });
+    assert.equal(result.passed, false);
+  });
+
+  it('L1: 不传 status → 不检查', () => {
+    const result = assertApiResponse({ status: 200, data: {}, headers: {} }, {});
+    assert.equal(result.passed, true);
+    assert.equal(result.checks.length, 0);
+  });
+});
+
+describe('PR #8: assertApiResponse L2 header（1 个场景）', () => {
+  it('L2: header 匹配', () => {
+    const result = assertApiResponse(
+      { status: 200, data: {}, headers: { 'content-type': 'application/json' } },
+      { headers: { 'content-type': 'application/json' } }
+    );
+    assert.equal(result.passed, true);
+    assert.equal(result.checks[0].level, 2);
+  });
+});
+
+describe('PR #8: assertApiResponse L3 body path（3 个场景）', () => {
+  it('L3: body path 完全匹配', () => {
+    const result = assertApiResponse(
+      { status: 200, data: { code: 0, data: { total: 5 } }, headers: {} },
+      { body: { 'code': 0, 'data.total': 5 } }
+    );
+    assert.equal(result.passed, true);
+  });
+
+  it('L3: body path 操作符 $gt', () => {
+    const result = assertApiResponse(
+      { status: 200, data: { data: { total: 10 } }, headers: {} },
+      { body: { 'data.total': { $gt: 5 } } }
+    );
+    assert.equal(result.passed, true);
+  });
+
+  it('L3: body path 不匹配 → failed', () => {
+    const result = assertApiResponse(
+      { status: 200, data: { code: 1 }, headers: {} },
+      { body: { code: 0 } }
+    );
+    assert.equal(result.passed, false);
+  });
+});
+
+describe('PR #8: assertApiResponse L4 responseTime（2 个场景）', () => {
+  it('L4: response time < 5000ms → passed', () => {
+    const result = assertApiResponse(
+      { status: 200, data: {}, headers: {}, config: { metadata: { total: 100 } } },
+      { responseTime: 5000 }
+    );
+    assert.equal(result.passed, true);
+    assert.equal(result.checks[0].level, 4);
+  });
+
+  it('L4: response time >= 5000ms → failed', () => {
+    const result = assertApiResponse(
+      { status: 200, data: {}, headers: {}, config: { metadata: { total: 6000 } } },
+      { responseTime: 5000 }
+    );
+    assert.equal(result.passed, false);
+  });
+});
+
+describe('PR #8: assertApiResponse 组合（2 个场景）', () => {
+  it('L1+L2+L3+L4 全过 → passed', () => {
+    const result = assertApiResponse(
+      {
+        status: 200,
+        data: { code: 0, items: [1, 2, 3] },
+        headers: { 'content-type': 'application/json' },
+        config: { metadata: { total: 100 } }
+      },
+      {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+        body: { code: 0, 'items': { $contains: 2 } },
+        responseTime: 5000
+      }
+    );
+    assert.equal(result.passed, true);
+    assert.equal(result.checks.length, 5, 'L1+L2+L3(2 keys: code+items)+L4 = 5 checks');
+  });
+
+  it('L1 过 L2 失败 → 全 failed', () => {
+    const result = assertApiResponse(
+      {
+        status: 200,
+        data: {},
+        headers: { 'content-type': 'text/html' },
+        config: { metadata: { total: 100 } }
+      },
+      {
+        status: 200,
+        headers: { 'content-type': 'application/json' }
+      }
+    );
+    assert.equal(result.passed, false);
+  });
+});
+
+describe('PR #8: createTimingsInterceptor（2 个场景）', () => {
+  it('request interceptor 设置 startTime', () => {
+    const collector = { timings: [] };
+    const interceptor = createTimingsInterceptor(collector);
+    const config = { url: 'http://x.com' };
+    const result = interceptor.request(config);
+    assert.ok(result.metadata.startTime, '应设置 startTime');
+  });
+
+  it('response interceptor 记录 timings', () => {
+    const collector = { timings: [] };
+    const interceptor = createTimingsInterceptor(collector);
+    const config = { metadata: { startTime: process.hrtime.bigint() - 1000000n }, url: 'http://x.com', method: 'GET' };
+    const response = { config, status: 200, statusText: 'OK' };
+    interceptor.response(response);
+    assert.equal(collector.timings.length, 1);
+    assert.ok(collector.timings[0].total > 0);
+  });
+});
+
+describe('PR #8: executeApiCallStep 集成（2 个场景）', () => {
+  it('返回结构含 6 个新字段位置（不实际发请求）', () => {
+    // 验证返回 schema 包含 6 个新字段的占位（通过 mock 不发请求）
+    // 这里仅验证 schema 完整性
+    const step = {
+      type: 'apiCall',
+      method: 'GET',
+      url: '/api/x',
+      assert: { status: 200 },
+      captureTrace: true,
+      noRetry: true,
+      strategy: 'newman',
+      headers: { 'X-Custom': 'test' },
+      tags: ['@api']
+    };
+    // schema 验证：所有字段存在
+    assert.equal(step.type, 'apiCall');
+    assert.equal(step.method, 'GET');
+    assert.deepEqual(step.assert, { status: 200 });
+    assert.equal(step.captureTrace, true);
+    assert.equal(step.noRetry, true);
+    assert.equal(step.strategy, 'newman');
+    assert.deepEqual(step.headers, { 'X-Custom': 'test' });
+    assert.deepEqual(step.tags, ['@api']);
+  });
+
+  it('真实请求（用 httpbin.org mock）— 2xx + assert 通过', async function() {
+    // 注：依赖外网，仅开发环境跑；CI 会因网络失败
+    // 本地跳过：if (process.env.SKIP_E2E) return;
+    if (process.env.SKIP_E2E || !process.env.RUN_E2E_NETWORK) {
+      return;  // soft skip
+    }
+    const result = await executeApiCallStep(
+      { type: 'apiCall', method: 'GET', url: 'https://httpbin.org/status/200' },
+      { baseURL: '', cookies: [] }
+    );
+    assert.equal(result.response.status, 200);
+  });
+});
+
+describe('PR #8: 端到端 testCase 样例 schema 验证（1 个场景）', () => {
+  it('31 接口 + 7 UI 流程同 plan 端到端 schema', () => {
+    const endToEndPlan = {
+      title: "数据目录端到端 P0",
+      tags: ["@p0", "@e2e"],
+      setup: { findFrame: { contentContains: "数据集目录" } },
+      steps: [
+        // UI 步骤
+        { "type": "act", "click": "text=登 录" },
+        { "type": "expect", "assertion": "url.toContain", "value": "/dashboard" },
+        // API 步骤（增强版）
+        {
+          "type": "apiCall",
+          "method": "GET",
+          "url": "/api/dataset/list",
+          "assert": { "status": 200, "body": { "code": 0 } },
+          "captureTrace": true
+        },
+        {
+          "type": "apiCall",
+          "method": "POST",
+          "url": "/api/dataset/create",
+          "body": { "name": "测试集A", "type": "image" },
+          "assert": { "status": 200, "body": { "code": 0 } },
+          "noRetry": true,
+          "captureTrace": true
+        },
+        // UI 步骤
+        { "type": "act", "click": "text=刷新" },
+        { "type": "expect", "assertion": "text.toContain", "value": "测试集A" }
+      ]
+    };
+    // 验证 schema 完整性
+    assert.equal(endToEndPlan.steps.length, 6, '2 UI + 2 API + 2 UI = 6 steps');
+    const apiSteps = endToEndPlan.steps.filter(s => s.type === 'apiCall');
+    assert.equal(apiSteps.length, 2, '应有 2 个 apiCall 步骤');
+    const writeStep = apiSteps.find(s => s.method === 'POST');
+    assert.equal(writeStep.noRetry, true, 'POST 应 noRetry: true');
+    const readStep = apiSteps.find(s => s.method === 'GET');
+    assert.equal(readStep.assert.status, 200);
+  });
+});
+
+describe('PR #8: build 副本同步', () => {
+  it('build 后 qwen-extension 含 api-call-executor.js', async () => {
+    const { spawnSync } = await import('node:child_process');
+    let result;
+    for (let attempt = 0; attempt < 5; attempt++) {
+      result = spawnSync('node', ['szcd-mcp-client/agents/build.js'], {
+        cwd: '/scity/zengzhijie/mcp',
+        stdio: 'pipe'
+      });
+      if (result.status === 0) break;
+      if (result.stderr?.toString().includes('ENOTEMPTY')) {
+        await new Promise((r) => setTimeout(r, 500));
+        continue;
+      }
+      break;
+    }
+    assert.equal(result.status, 0, `build 失败: ${result.stderr?.toString()}`);
+
+    const target = '/scity/zengzhijie/mcp/szcd-mcp-client/qwen-extension/skills/local-browser-test/lib/api-call-executor.js';
+    assert.ok(fs.existsSync(target), 'api-call-executor.js 应同步到 qwen 副本');
+  });
+});

package/opencode-extension/skills/shadcn-design-to-code/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: shadcn-design-to-code
+description: |
+  根据设计稿（.sketch 或图片）生成基于 shadcn/ui + Tailwind CSS 的 React 页面代码。
+  工作流在主智能体上下文中执行，调用 shadcn 官方 MCP + sketch-mcp-server + szcd-component-helper 共同完成。
+
+  触发场景：
+  - 用户提供 .sketch 文件，要求用 shadcn/ui 生成页面
+  - 用户提供设计稿截图，要求基于 shadcn/ui 生成代码
+  - 用户描述"自定义 Dashboard / 数据大屏 / 品牌官网 / 移动端响应式"等非标准 CRUD 页面
+  - 用户提到"shadcn"、"Tailwind"、"Radix"等关键词
+  - 设计稿风格与 szcd 默认风差异 > 30%
+
+  与 szcd-design-to-code 的关系：本 skill 是补充，不是替代。
+  业务 CRUD / 左树右表 / ProTable / 步骤向导等场景仍走 szcd-design-to-code。
+---
+
+# shadcn-design-to-code: 设计稿转 shadcn 页面代码
+
+## 角色定位
+
+你是 shadcn/ui + Tailwind CSS 的代码生成专家。在主智能体上下文中执行以下工作流，调用已连接的 MCP 工具完成从设计稿到可运行代码的全流程。
+
+shadcn/ui 的核心特征：
+- **不是组件库** —— 是把 Radix UI primitives 复制到用户仓库 `components/ui/` 的源码
+- **样式范式**：Tailwind utility + CSS variables（HSL 通道分离）
+- **变体机制**：class-variance-authority (cva)
+- **布局范式**：无模板约束，开发者用 Tailwind grid/flex 自由组合
+- **可定制性**：源码在手，任意改任意覆盖
+
+## ⚠️ 与 szcd 方案的边界（必读，决定走哪条工作流）
+
+进入工作流前先判断，**选错工作流会浪费一轮**：
+
+| 场景 | 推荐工作流 | 原因 |
+|---|---|---|
+| 左树右表 / 查询表格 / 弹窗表单 | **szcd** | TemplateMode + useTable/useLeftTree 开箱即用 |
+| 多步骤向导 / 拖拽排序 | **szcd** | ModelOrDrawer(steps) / DragSortTable 现成 |
+| ProTable / ProList / ProDescriptions | **szcd** | Pro 高级组件无 shadcn 对应 |
+| ECharts 高级图表（K线/桑基/词云） | **szcd** | shadcn Chart 仅基于 Recharts |
+| **自定义 Dashboard / 品牌官网** | **shadcn**（本 skill） | 设计驱动场景还原度优势 |
+| **数据大屏（非标准布局）** | **shadcn** | 自由 grid/flex 组合 |
+| **移动端响应式** | **shadcn** | Tailwind 移动优先 |
+| **暗色模式 / 主题切换密集** | **shadcn** | CSS variables 天然优势 |
+| **设计 token 驱动 / 高度品牌化** | **shadcn** | HSL 通道分离 CSS 变量直接吃 Sketch token |
+| 设计稿风格与 szcd 默认风差异 > 30% | **shadcn** | 强行套 szcd 还原度掉到 50-60% |
+| 复杂企业表单（含 ProForm 校验） | **szcd** | ProForm 内置 30+ 校验规则 |
+
+## ⚠️ 强制执行规则
+
+- 禁止跳过架构认知直接生成代码
+- 禁止不查询组件能力就凭记忆/猜测写代码（shadcn 组件能力通过 `mcp__shadcn__view_items_in_registries` 查元信息，通过 `get_add_command_for_items` + 本地 `npx add` 拿源码）
+- 禁止跳过方案确认直接进入代码生成
+- 禁止不读 .sketch 节点样式直接写 CSS（必须经过步骤 2.5 + 2.6 拿到 style.fills/borders 后再落样式）
+- 禁止凭 x 或 y 单轴判定元素归属（参考 szcd 的 x+y+parent 联合判定，详见步骤 2.6）
+- **shadcn 组件是"按需 npx add"模式，不要全量列组件清单** —— 走 `view_items` 拿元信息 → `add_command` 安装 → 读本地源码
+
+## 工作流
+
+### 步骤1：架构认知（必做）
+
+shadcn 不是一个传统组件库，没有"7 层架构"概念。认知重点是：
+
+**1.1 加载 shadcn 元信息目录**
+
+调用 `mcp__shadcn__list_items_in_registries(registries=["@shadcn"], limit=363)` 拿到全量 363 个 item 清单（含 ui/example/block/style/hook/theme 等 10 种类型）。
+
+调用 `mcp__shadcn__search_items_in_registries(registries=["@shadcn"], query="<关键词>")` 按设计稿关键词搜索候选。
+
+**1.2 加载辅助架构信息**
+
+调用 `mcp__szcd-component-helper__get_architecture_overview(detail="full")` 拿到：
+- `templatePatterns`（参考用，shadcn 无模板约束，但可以理解"设计稿想表达什么布局意图"）
+- `styleMapping.nodeStyleRules`（节点样式 → UI 组件样式的全局规则，shadcn 借用）
+- `assetExtraction.bitmapRules / iconWorkflow`（资源提取规则，与目标库无关，**完全复用**）
+
+**1.3 加载 shadcn 布局模式库**
+
+读取 `references/layouts.md` —— 15 种 Tailwind 布局模式（sidebar-main / dashboard-grid / topbar-content / responsive-stack 等），按设计稿区块分布反查。
+
+**1.4 加载样式落地规则**
+
+读取 `references/tokens.md` —— 设计 token → tailwind.config.ts 的映射规则。
+
+**1.5 加载节点 → shadcn 组件反查表**
+
+读取 `references/sketch-mapping.md` —— 常见 Sketch 视觉特征 → shadcn 组件映射（如"大块卡片含图表"→ Card + Chart，"3 列响应式卡片"→ `grid-cols-1 md:grid-cols-2 lg:grid-cols-3`）。
+
+**步骤 1 产出**：
+- 设计稿候选 shadcn 组件清单（来自 list_items + search_items + sketch-mapping）
+- 布局模式候选（来自 layouts.md + sketch 区块分布）
+- 样式 token 候选（来自 tokens.md + sketch style.fills/borders）
+
+### 步骤2：理解需求（必做）
+
+分析用户页面，梳理：
+1. **页面布局类型**：单列 / 左右 / 三列 / Dashboard 网格 / 表单页
+2. **核心组件**：图表、表格、表单、卡片、列表、Tab
+3. **交互需求**：筛选、搜索、分页、暗色模式
+4. **响应式断点**：移动 / 平板 / 桌面
+
+信息不足时主动追问。
+
+### 步骤2.5：Sketch 文件解析（有 .sketch 文件时执行）
+
+**完全复用 szcd 工作流**。shadcn 没有任何 sketch 解析能力，所有节点数据都来自 `sketch-mcp-server`：
+
+```
+.sketch → loadSketchByPath → listPages → queryNodes(pageId, type="artboard")
+       → getPageStructure(pageId, mode="tree", maxDepth=3)
+       → queryNodes(pageId, type=["text","rectangle","group"])
+       → getMultipleNodeInfo([全部 ID])
+```
+
+**关键字段契约**（同 szcd）：
+- `parent.{id,name,type}` —— 元素归属
+- `style.fills[0].color.hex` / `gradient` —— 背景色/渐变
+- `style.borders[0]` —— 边框
+- `style.fonts.fontFamily` 末尾编码字重（`PingFangSC-Semibold` → 600）
+- `isVisualContainer: bool` —— group 是否带视觉样式
+- bitmap ID 列表 → 步骤 2.5.1
+- shapePath 节点名 → 步骤 2.5.1
+
+**资源优先级铁律**（同 szcd，P0-P4 顺序）：
+
+| 优先级 | 来源 | 判定 | 渲染 |
+|---|---|---|---|
+| P0 | sketch bitmap | type=bitmap | `extractBitmaps` → base64 → `<img src="data:...">` |
+| P1 | shapePath SVG | 独立 shapePath | `getShapePathData` → 内联 SVG |
+| P2 | shapePath → iconfont | 节点名能匹配 | `mcp__shadcn__search_items` 找 lucide 图标 |
+| P3 | lucide-react 图标 | 上面都失败 | `<Xxx />` from `lucide-react` |
+| P4 | 纯 CSS/div | 几何/色块 | `<div style={...}>` |
+
+**步骤 2.5 产出**：text/rectangle/group 全量节点数据 + bitmap base64 + iconfont/svg 列表。
+
+### 步骤2.6：布局推理（必做）
+
+**完全复用 szcd 的 5 张表 + A/B/C/D 矩阵**（参考 szcd SKILL.md 步骤 2.6）：
+
+- **表 1：分区识别**（x+y+parent 联合）—— 决定用 layouts.md 的哪个布局模式
+- **表 2：纵向顺序**（同分区内 y 排序）
+- **表 3：横向排列**（同行 y 差<8px 按 x 排序）
+- **表 4：容器归属**（x+y 双轴边界检测）
+- **表 5：样式映射**（rectangle/group fill → Tailwind className）
+
+**x+y+parent 联合判定铁律**（来自 szcd 经验沉淀，**shadcn 工作流同样适用**）：
+
+| 情形 | 坐标判定 | parent 判定 | 处理 |
+|---|---|---|---|
+| A | 在容器 X 内 | parent 也是 X | ✅ 直接采用 |
+| B | 在容器 X 内 | parent 是兄弟 Y | ⚠️ 视觉容器优先（按坐标） |
+| C | 不在容器 X 内 | parent 是 X | ⚠️ parent 优先（用 absolute） |
+| D | 双向都不落 | parent 顶层 | 独立元素，按坐标 |
+
+**样式映射表的关键差异**（shadcn vs szcd）：
+
+| 维度 | szcd 落地方式 | shadcn 落地方式 |
+|---|---|---|
+| 颜色块 | 内联 `style={{background:'#f2f8fd'}}` | Tailwind `bg-[#f2f8fd]` 或 `bg-segment-blue`（token） |
+| 边框 | 内联 `style={{border:'1px solid #d9eafb'}}` | `border border-[#d9eafb]` |
+| 渐变 | 内联 `style={{background:'linear-gradient(...)'}}` | `bg-gradient-to-b from-[#f3faff] to-[#f8fdff]` |
+| 圆角 | 内联 `style={{borderRadius:8}}` | `rounded-lg`（或 `rounded-[8px]`） |
+| 间距 | 内联 `style={{padding:16}}` | `p-4`（或 `p-[16px]`） |
+| 字号 | 内联 `style={{fontSize:14}}` | `text-sm`（或 `text-[14px]`） |
+| 字重 | 内联 `style={{fontWeight:600}}` | `font-semibold` |
+
+**出现 ≥ 3 次的颜色/字号/间距必须抽到 tailwind.config.ts**（详见 tokens.md）。
+
+### 步骤3：分析设计稿图片（有图片时执行）
+
+复用 szcd 的 `analyze_design_image` 工具，但 `targetLibrary="auto"` 或 `targetLibrary` 不传（不指定为 szcd）。
+
+**注意**：analyze_design_image 的 token 提取逻辑与目标库无关，但其样式注入建议是 szcd 化的（如 `.ant-btn-primary`）。**对 shadcn 工作流，只用 token 部分，忽略组件映射建议**。
+
+### 步骤3.5：组件候选列表推理
+
+**与 szcd 的关键差异**：
+
+- ❌ **不要走 templatePatterns** —— shadcn 无模板约束
+- ✅ 走 `references/sketch-mapping.md` + `mcp__shadcn__search_items` 反查
+- ✅ 走 `references/layouts.md` 反查布局模式
+- ✅ 复杂业务组件（DataTable / Form）走 shadcn 官方 block（dashboard-01 / sidebar-07 等）
+
+**推理顺序**：
+
+1. **画板名称** → `pageName`（H1 + URL）
+2. **大区切分** → 读 `references/layouts.md` 反查布局模式（如"左侧 240px 导航 + 右侧主内容" → `sidebar-main`）
+3. **区域容器** → 读 `references/sketch-mapping.md` 反查组件（如"大块圆角卡片含标题+图表" → `Card` + `Chart`）
+4. **图标** → `mcp__shadcn__search_items(query="<icon-name>")` 找 lucide 图标
+5. **缺失能力** → 自写（不强行套 shadcn 组件）
+
+### 步骤4：批量安装 shadcn 组件
+
+**这是 shadcn 工作流的核心步骤**。用 shadcn MCP 拿安装命令 + 本地 npx 执行 + 读源码：
+
+```
+对每个候选组件：
+  1. mcp__shadcn__view_items_in_registries(items=["@shadcn/<name>"])
+     → 拿元信息（Type / Files / Dependencies）
+  2. mcp__shadcn__get_item_examples_from_registries(query="<name>-demo")
+     → 拿 demo 用法（参考用，不直接复制）
+  3. mcp__shadcn__get_add_command_for_items(items=["@shadcn/<name>", ...])
+     → 拿 `npx shadcn@latest add ...` 命令
+  4. 本地执行 npx shadcn@latest add @shadcn/<name> ...
+     → 源码下载到 components/ui/<name>.tsx
+  5. read_file 读 components/ui/<name>.tsx
+     → 拿到真实 Props / variants / API
+```
+
+**⚠️ 实测坑 1**（重要，违反 = 报错）：
+
+`mcp__shadcn__list_items_in_registries` 和 `mcp__shadcn__search_items_in_registries` **必须显式传 `registries: ["@shadcn"]`**，否则报 "No registries are configured"。
+
+`mcp__shadcn__get_project_registries` 能从 components.json 隐式识别，但 list/search 不行。
+
+```
+❌ mcp__shadcn__list_items_in_registries(limit=10)
+   → "No registries are configured. Add registries to components.json..."
+
+✅ mcp__shadcn__list_items_in_registries(registries=["@shadcn"], limit=10)
+   → 363 items
+```
+
+**⚠️ 实测坑 2**（重要，违反 = 拿到的是元信息不是源码）：
+
+`mcp__shadcn__view_items_in_registries` **只返回元信息**（Type / Files / Dependencies 三行），**不返回组件源码**。
+
+要拿源码必须先 `npx shadcn@latest add` 装到本地，再 `read_file` 读。
+
+```
+❌ view_items 拿源码 → 只有元信息
+✅ view_items 看类型 → get_add_command → npx add → read_file 读源码
+```
+
+**步骤 4 产出**：
+- 真实下载到本地的组件源码（`components/ui/xxx.tsx`）
+- 真实 Props / variants（从读到的源码解析）
+
+### 步骤5：确认方案（必做）
+
+```
+## 组件方案
+
+### 页面结构（布局模式 + 区块）
+[布局树形图，标注 layouts.md 的模式名，如 sidebar-main + dashboard-grid]
+
+### 选用组件
+| 设计元素 | shadcn 组件 | 变体/参数 | 选用理由 |
+|---------|------------|----------|---------|
+| 左侧导航 | Sidebar | sidebar-07 block | layouts.md 反查 |
+| 主内容卡片 | Card | default | sketch-mapping.md 反查 |
+| 折线图 | Chart | Line | Recharts 集成 |
+
+### Token 落地
+| Token | 类型 | 落地方式 | tailwind.config.ts 位置 |
+|-------|------|----------|------------------------|
+| #0ea5e9 | 品牌主色 | theme.extend.colors.brand.500 | colors |
+| #f8fafc | 背景色 | CSS variable --background | colors |
+
+### 依赖项
+- 业务组件：@tanstack/react-table, react-hook-form, zod, recharts
+- 图标：lucide-react
+- shadcn 基础：clsx, tailwind-merge, class-variance-authority
+```
+
+等用户确认。
+
+### 步骤6：生成代码（必做）
+
+**代码规范**：
+- React 18 + TypeScript
+- `components/ui/` 来源：shadcn 装的源码（不要再写）
+- 业务组件放 `components/`
+- 页面放 `app/<page>/page.tsx`（Next.js）或 `src/pages/<page>.tsx`（Vite）
+- Tailwind 优先，inline style 仅作 fallback
+
+**生成顺序**：
+1. 写 `tailwind.config.ts` 增量（design tokens）
+2. 写 `app/globals.css` 的 CSS variables（HSL 通道格式）
+3. 写业务组件（用 shadcn 装的 ui 组件组合）
+4. 写页面级 layout（Tailwind grid/flex）
+5. 写 mock data（如有需要）
+
+**样式落地校验**（必做，参考 szcd 经验 8）：
+
+代码生成后逐行核对步骤 2.6 表 5 的每一项是否真落到代码里：
+
+```
+| Sketch 节点          | 样式 Token          | 代码中位置                          | 校验 |
+|---------------------|--------------------|------------------------------------|------|
+| 渐变容器 group       | linear #f3faff→#f8fdff | page.tsx:L42 bg-gradient-to-b     | ✅  |
+| 段码块-蓝 rectangle  | bg #f2f8fd         | page.tsx:L55 bg-[#f2f8fd]         | ✅  |
+| Tab 激活态 rectangle | bg #fff border #0079f7 | components/Tabs.tsx:L18         | ✅  |
+```
+
+❌ 如果某行找不到对应代码位置 → 直接补到代码里再继续，**禁止说"代码已生成"前留缺口**。
+
+### 步骤7：浏览器验证（强烈推荐）
+
+shadcn 没有 szcd 那种"5 层架构兜底"——一旦样式不对立刻肉眼可见。**强烈建议走 local-browser-test skill 验证**：
+
+1. 启动 dev server
+2. 浏览器打开页面，截图
+3. 用 `mcp__szcd-component-helper__assert_page_screenshot` 跑语义断言（如"左侧 240px 导航栏 + 4 卡片栅格"）
+4. 迭代修复直到 80% 以上还原度
+
+### 步骤8：收集反馈（必做）
+
+调用 `mcp__szcd-component-helper__submit_feedback` 提交反馈，**toolType 必须是当前 IDE**：
+
+```json
+{
+  "sessionId": "<时间戳>",
+  "toolsUsed": [
+    "mcp__shadcn__list_items_in_registries",
+    "mcp__shadcn__search_items_in_registries",
+    "mcp__shadcn__view_items_in_registries",
+    "mcp__shadcn__get_add_command_for_items",
+    "mcp__sketch-mcp-server__loadSketchByPath",
+    "mcp__sketch-mcp-server__getMultipleNodeInfo"
+  ],
+  "userQuery": "<用户原始需求>",
+  "generatedCodeSummary": "<shadcn 组件列表 + 布局模式>",
+  "accuracyRating": 4,
+  "adopted": true,
+  "contextSnapshot": {
+    "matchedComponents": ["Sidebar", "Card", "Chart"],
+    "layoutMode": "sidebar-main + dashboard-grid",
+    "registry": "@shadcn"
+  }
+}
+```
+
+## 故障降级
+
+shadcn MCP 失败时：
+- 直接 `npx shadcn@latest search <query>` / `npx shadcn@latest add <name>` 走 CLI
+- 走 https://ui.shadcn.com 查官方文档
+- 标注"⚠️ 未通过 shadcn MCP 验证"
+
+sketch-mcp-server 失败时：
+- 降级到 szcd-component-helper 的 `analyze_design_image` 走图片分析
+- 标注"⚠️ 结构化数据缺失，依赖视觉模型"
+
+## 资源清单
+
+| 资源 | 用途 | 优先级 |
+|------|------|--------|
+| `references/layouts.md` | 15 种 Tailwind 布局模式反查 | P0 |
+| `references/tokens.md` | 设计 token → tailwind.config.ts 映射 | P0 |
+| `references/sketch-mapping.md` | 节点 → shadcn 组件反查表 | P0 |
+| `references/install-pitfalls.md` | 实测发现的 2 个坑 + audit 清单 | P0 |