@szc-ft/mcp-szcd-client 0.26.0 → 0.27.1

package/opencode-extension/skills/local-browser-test/local-browser-executor.cjs

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+/**
+ * local-browser-executor.js - 本地浏览器自动化执行器
+ *
+ * 功能：
+ *   --action diagnose    全面诊断（JS错误、网络请求、API检查、资源加载）
+ *   --action list-pages  列出所有标签页
+ *   --action screenshot  截图
+ *   --action api-check   检查 API 请求状态
+ *   --action plan        执行测试计划 JSON
+ *
+ * 连接方式：
+ *   --cdp-url http://localhost:9222  (默认自动检测 9222)
+ *   --auto-detect                    自动检测 Chrome/Edge 进程
+ *
+ * 通用参数：
+ *   --url <url>          目标页面 URL
+ *   --url-contains <s>   按关键词查找已打开的页面
+ *   --wait <ms>          额外等待时间（默认 5000）
+ *   --output <path>      结果输出文件
+ *   --output-dir <dir>   截图/产物输出目录
+ */
+
+const puppeteer = require('puppeteer-core');
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+
+// ===== 参数解析 =====
+const args = process.argv.slice(2);
+function getArg(name, defaultVal) {
+  const idx = args.indexOf(`--${name}`);
+  if (idx === -1) return defaultVal;
+  return args[idx + 1] || defaultVal;
+}
+function hasFlag(name) {
+  return args.includes(`--${name}`);
+}
+
+const ACTION = getArg('action', 'diagnose');
+const CDP_URL = getArg('cdp-url', 'http://localhost:9222');
+const TARGET_URL = getArg('url', null);
+const URL_CONTAINS = getArg('url-contains', null);
+const WAIT_MS = parseInt(getArg('wait', '5000'), 10);
+const OUTPUT = getArg('output', null);
+const OUTPUT_DIR = getArg('output-dir', '/tmp/browser-test');
+const PLAN_FILE = getArg('plan-file', null);
+
+// ===== 工具函数 =====
+function log(msg) { console.log(msg); }
+function ensureDir(dir) { fs.mkdirSync(dir, { recursive: true }); }
+
+function checkCDP(url) {
+  return new Promise((resolve) => {
+    const req = http.get(url + '/json/version', { timeout: 2000 }, (res) => {
+      let data = '';
+      res.on('data', c => data += c);
+      res.on('end', () => {
+        try { resolve(JSON.parse(data)); } catch { resolve(null); }
+      });
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+async function findPage(browser) {
+  const pages = await browser.pages();
+  if (TARGET_URL) {
+    for (const p of pages) {
+      if (p.url().includes(TARGET_URL) || p.url() === TARGET_URL) return p;
+    }
+    // 导航到目标 URL
+    const p = pages[0] || await browser.newPage();
+    await p.goto(TARGET_URL, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    return p;
+  }
+  if (URL_CONTAINS) {
+    for (const p of pages) {
+      if (p.url().includes(URL_CONTAINS)) return p;
+    }
+    log(`[WARN] 未找到包含 "${URL_CONTAINS}" 的页面，使用第一个页面`);
+  }
+  // 找到非 about:blank 的页面
+  for (const p of pages) {
+    if (!p.url().startsWith('about:') && !p.url().startsWith('devtools:')) return p;
+  }
+  return pages[0];
+}
+
+// ===== Action: list-pages =====
+async function listPages(browser) {
+  const pages = await browser.pages();
+  const result = [];
+  for (let i = 0; i < pages.length; i++) {
+    const p = pages[i];
+    let title = '';
+    try { title = await p.title(); } catch {}
+    result.push({ index: i, url: p.url(), title });
+    log(`[${i}] ${p.url()}`);
+    if (title) log(`    title: ${title}`);
+  }
+  return { pages: result, total: result.length };
+}
+
+// ===== Action: diagnose =====
+async function diagnose(browser) {
+  ensureDir(OUTPUT_DIR);
+  const page = await findPage(browser);
+  log(`[PAGE] ${page.url()}`);
+
+  // 收集数据
+  const pageErrors = [];
+  const consoleMessages = [];
+  const failedRequests = [];
+  const apiRequests = [];
+  const resourceRequests = [];
+
+  page.on('pageerror', err => {
+    pageErrors.push({ message: err.message, stack: err.stack?.split('\n').slice(0, 5).join('\n') });
+  });
+  page.on('console', msg => {
+    const type = msg.type();
+    const text = msg.text().substring(0, 500);
+    consoleMessages.push({ type, text });
+  });
+  page.on('response', resp => {
+    const url = resp.url();
+    const status = resp.status();
+    const type = resp.request().resourceType();
+    if (type === 'xhr' || type === 'fetch') {
+      apiRequests.push({ status, url, method: resp.request().method() });
+    }
+    if (type === 'stylesheet' || type === 'script') {
+      resourceRequests.push({ status, url, type });
+    }
+    if (status >= 400) {
+      failedRequests.push({ status, url, type });
+    }
+  });
+  page.on('requestfailed', req => {
+    failedRequests.push({ status: 'ABORTED', url: req.url(), error: req.failure()?.errorText });
+  });
+
+  // 刷新页面收集
+  log('[INFO] 刷新页面收集诊断数据...');
+  try {
+    await page.reload({ waitUntil: 'load', timeout: 30000 });
+  } catch (e) {
+    log(`[WARN] 刷新超时: ${e.message.substring(0, 100)}`);
+  }
+  await new Promise(r => setTimeout(r, WAIT_MS));
+
+  // 截图
+  const screenshotPath = path.join(OUTPUT_DIR, 'diagnose-screenshot.png');
+  await page.screenshot({ path: screenshotPath, fullPage: false });
+  log(`[OK] 截图: ${screenshotPath}`);
+
+  // 检查 iframe
+  const frames = page.frames();
+  const iframeInfo = [];
+  for (const frame of frames) {
+    const url = frame.url();
+    if (url === page.url() || url === 'about:blank') continue;
+    let bodyText = '';
+    let rootContent = '';
+    try {
+      const info = await frame.evaluate(() => ({
+        bodyText: document.body?.innerText?.substring(0, 200) || '',
+        rootHTML: document.getElementById('root')?.innerHTML?.substring(0, 200) || 'no root',
+        hasReactRoot: !document.getElementById('root')?.innerHTML?.includes('loading-spinner'),
+        antdElements: document.querySelectorAll('[class*="ant-"]').length,
+      }));
+      bodyText = info.bodyText;
+      rootContent = info.rootHTML;
+      iframeInfo.push({ url, ...info });
+    } catch (e) {
+      iframeInfo.push({ url, error: e.message.substring(0, 100) });
+    }
+  }
+
+  // 输出结果
+  const errors = consoleMessages.filter(m => m.type === 'error');
+  const warnings = consoleMessages.filter(m => m.type === 'warning');
+
+  const result = {
+    url: page.url(),
+    timestamp: new Date().toISOString(),
+    screenshot: screenshotPath,
+    pageErrors,
+    consoleErrors: errors,
+    consoleWarnings: warnings,
+    consoleTotal: consoleMessages.length,
+    failedRequests,
+    apiRequests,
+    resourceStatus: resourceRequests.map(r => ({
+      status: r.status, type: r.type, name: r.url.split('/').pop()
+    })),
+    iframes: iframeInfo,
+    summary: {
+      jsErrors: pageErrors.length,
+      consoleErrors: consoleMessages.filter(m => m.type === 'error').length,
+      failedNetwork: failedRequests.length,
+      totalAPI: apiRequests.length,
+      failedAPI: apiRequests.filter(r => r.status >= 400).length,
+      totalResources: resourceRequests.length,
+      failedResources: resourceRequests.filter(r => r.status >= 400).length,
+    }
+  };
+
+  // 打印摘要
+  log('\n========== 诊断结果 ==========');
+  log(`JS 异常: ${result.summary.jsErrors}`);
+  pageErrors.forEach(e => log(`  [PAGEERROR] ${e.message}`));
+  log(`Console 错误: ${errors.length}`);
+  errors.forEach(e => log(`  [ERROR] ${e.text}`));
+  log(`Console 警告: ${warnings.length}`);
+  warnings.forEach(e => log(`  [WARN] ${e.text}`));
+  log(`Console 消息总数: ${consoleMessages.length}`);
+  log(`失败网络请求: ${result.summary.failedNetwork}`);
+  failedRequests.forEach(r => log(`  [${r.status}] ${r.url}`));
+  log(`API 请求: ${result.summary.totalAPI} (失败: ${result.summary.failedAPI})`);
+  apiRequests.forEach(r => {
+    const marker = r.status >= 400 ? '❌' : '✅';
+    log(`  ${marker} [${r.status}] ${r.method} ${r.url}`);
+  });
+  log(`CSS/JS 资源: ${result.summary.totalResources} (失败: ${result.summary.failedResources})`);
+  resourceRequests.filter(r => r.status >= 400).forEach(r => log(`  ❌ [${r.status}] ${r.url}`));
+  if (iframeInfo.length > 0) {
+    log(`\niframe 信息:`);
+    iframeInfo.forEach(f => log(`  ${f.url} → ${f.error || (f.hasReactRoot ? 'React已挂载' : '未挂载')}`));
+  }
+
+  // 保存结果
+  if (OUTPUT) {
+    fs.writeFileSync(OUTPUT, JSON.stringify(result, null, 2));
+    log(`\n[OK] 结果已保存: ${OUTPUT}`);
+  }
+
+  return result;
+}
+
+// ===== Action: screenshot =====
+async function screenshot(browser) {
+  ensureDir(OUTPUT_DIR);
+  const page = await findPage(browser);
+  const filename = getArg('filename', 'screenshot.png');
+  const fullPath = path.join(OUTPUT_DIR, filename);
+  const fullPage = hasFlag('full-page');
+  await page.screenshot({ path: fullPath, fullPage });
+  log(`[OK] 截图已保存: ${fullPath}`);
+  return { filepath: fullPath };
+}
+
+// ===== Action: api-check =====
+async function apiCheck(browser) {
+  const page = await findPage(browser);
+  log(`[PAGE] ${page.url()}`);
+
+  const requests = [];
+  const failed = [];
+
+  page.on('response', resp => {
+    const type = resp.request().resourceType();
+    if (type === 'xhr' || type === 'fetch') {
+      requests.push({
+        status: resp.status(),
+        url: resp.url(),
+        method: resp.request().method(),
+        frameUrl: resp.request().frame()?.url?.() || '',
+      });
+    }
+  });
+  page.on('requestfailed', req => {
+    failed.push({ url: req.url(), error: req.failure()?.errorText });
+  });
+
+  log('[INFO] 刷新页面收集 API 请求...');
+  try { await page.reload({ waitUntil: 'load', timeout: 30000 }); } catch {}
+  await new Promise(r => setTimeout(r, WAIT_MS));
+
+  log('\n========== API 请求 ==========');
+  requests.forEach(r => {
+    const marker = r.status >= 400 ? '❌' : '✅';
+    const isIframe = r.frameUrl && r.frameUrl !== page.url() ? ' [iframe]' : '';
+    log(`${marker} [${r.status}] ${r.method} ${r.url}${isIframe}`);
+  });
+  if (failed.length > 0) {
+    log('\n========== 失败请求 ==========');
+    failed.forEach(r => log(`[FAILED] ${r.url} → ${r.error}`));
+  }
+  log(`\n总计: ${requests.length} 请求, 失败: ${requests.filter(r => r.status >= 400).length + failed.length}`);
+
+  return { requests, failed };
+}
+
+// ===== Action: plan =====
+async function executePlan(browser) {
+  const planPath = PLAN_FILE;
+  if (!planPath) { log('[ERROR] --plan-file 未指定'); return; }
+  const plan = JSON.parse(fs.readFileSync(planPath, 'utf-8'));
+  ensureDir(plan.options?.outputDir || OUTPUT_DIR);
+
+  log(`[PLAN] ${plan.description || plan.planId}`);
+  log(`[STEPS] ${plan.steps.length} 个步骤`);
+
+  const results = [];
+  let currentPage = await findPage(browser);
+
+  for (let i = 0; i < plan.steps.length; i++) {
+    const step = plan.steps[i];
+    const start = Date.now();
+    try {
+      let result = {};
+      switch (step.type) {
+        case 'navigate':
+          await currentPage.goto(step.url, { waitUntil: step.waitUntil || 'domcontentloaded', timeout: 30000 });
+          result = { url: currentPage.url() };
+          break;
+        case 'screenshot':
+          const fp = path.join(plan.options?.outputDir || OUTPUT_DIR, step.filename || `step-${i}.png`);
+          await currentPage.screenshot({ path: fp, fullPage: step.fullPage });
+          result = { filepath: fp };
+          break;
+        case 'waitFor':
+          if (step.selector) await currentPage.waitForSelector(step.selector, { timeout: step.timeout || 10000 });
+          result = { matched: true };
+          break;
+        case 'evaluate':
+          const evalResult = await currentPage.evaluate(step.expression);
+          result = { result: evalResult };
+          break;
+        case 'click':
+          await currentPage.click(step.selector);
+          result = { clicked: true };
+          break;
+        case 'checkElement':
+          const count = await currentPage.$$eval(step.selector, els => els.length).catch(() => 0);
+          const passed = step.expect?.minCount ? count >= step.expect.minCount : count > 0;
+          result = { passed, elementCount: count };
+          break;
+        default:
+          result = { skipped: true, reason: `unknown step type: ${step.type}` };
+      }
+      const duration = Date.now() - start;
+      results.push({ index: i, step: step.type, status: 'PASS', duration, ...result });
+      log(`  [${i + 1}/${plan.steps.length}] ✅ ${step.type} (${duration}ms)`);
+    } catch (e) {
+      const duration = Date.now() - start;
+      results.push({ index: i, step: step.type, status: 'FAIL', duration, error: e.message });
+      log(`  [${i + 1}/${plan.steps.length}] ❌ ${step.type} (${duration}ms) → ${e.message.substring(0, 100)}`);
+    }
+  }
+
+  const summary = {
+    total: results.length,
+    passed: results.filter(r => r.status === 'PASS').length,
+    failed: results.filter(r => r.status === 'FAIL').length,
+  };
+  log(`\n[RESULT] ${summary.passed}/${summary.total} 通过`);
+
+  if (OUTPUT) {
+    fs.writeFileSync(OUTPUT, JSON.stringify({ steps: results, summary }, null, 2));
+  }
+  return { steps: results, summary };
+}
+
+// ===== 主入口 =====
+(async () => {
+  // 检测 CDP
+  const cdpInfo = await checkCDP(CDP_URL);
+  if (!cdpInfo) {
+    log(`[ERROR] 无法连接到 CDP: ${CDP_URL}`);
+    log('请确保浏览器已启动调试端口:');
+    log('  Windows Edge: "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe" --remote-debugging-port=9222');
+    log('  Windows Chrome: "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" --remote-debugging-port=9222');
+    process.exit(1);
+  }
+  log(`[CDP] ${cdpInfo.Browser || 'connected'} (${CDP_URL})`);
+
+  const browser = await puppeteer.connect({ browserURL: CDP_URL, defaultViewport: null });
+
+  let result;
+  switch (ACTION) {
+    case 'list-pages': result = await listPages(browser); break;
+    case 'diagnose': result = await diagnose(browser); break;
+    case 'screenshot': result = await screenshot(browser); break;
+    case 'api-check': result = await apiCheck(browser); break;
+    case 'plan': result = await executePlan(browser); break;
+    default: log(`[ERROR] 未知 action: ${ACTION}`);
+  }
+
+  browser.disconnect();
+  log('\n[DONE]');
+})();

package/opencode-extension/skills/szcd-component-helper/SKILL.md

@@ -61,7 +61,7 @@ compatibility:
 AI 助手在处理页面生成需求时，必须按以下流程使用工具：
 
 ### 步骤1：架构认知 + 需求理解
-- 调用 `get_architecture_overview(detail="summary")` 获取 7 层架构和模板组合模式
+- 调用 `get_architecture_overview(detail="full")` 获取 7 层架构、模板组合模式、全量组件设计元信息（componentSummary）+ styleMapping + assetExtraction，用于后续步骤的组件推理与样式注入
 - 分析用户需求的页面布局类型、查询字段、操作按钮、表格列等
 
 ### 步骤2：组件发现（优先语义搜索）
@@ -93,17 +93,13 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
 → get_component_full_profile(批量) → 编码
 ```
 
-**Sketch 结构 → 组件映射规则**：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
-| 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
-| 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
-| 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
-| 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
-| 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
-| 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
-| 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
+**Sketch 结构 → 组件映射依据**：直接查阅步骤 1 `get_architecture_overview(detail="full")` 返回的 `componentSummary` 全量元信息，按以下顺序反查组件：
+1. **大区切分** → `componentSummary.other` 中 `layoutRole === '页面定位'`（如 TemplateMode），结合 `variantProps.templateType` 和 `templatePatterns` 选模板
+2. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack 等），按 `useCases` 匹配 Sketch 区域语义
+3. **图表** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`
+4. **变体** → `variantProps` 配合 `useCases` 区分子类型
+
+`componentSummary` 由组件库源码动态扫描生成，是唯一可信源；不要依赖任何硬编码 Sketch→组件对照表。
 
 **提示**：
 - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
@@ -204,7 +200,10 @@ sketch-mcp-server 是社区版 MCP Server（npm: `sketch-mcp-server`），通过
 #### 4. get_architecture_overview
 **功能**：查看 7 层架构（AntD→Cover→Wrapper→ProPackage→复合组件→模板）、层级关系和推荐使用顺序。含 LLM 映射修正提示。
 **参数**：
-- `detail` (enum, optional, default: "summary"): summary=层级概览+模板模式+LLM提示；full=含所有层组件列表详情
+- `detail` (enum, optional, default: "summary"):
+  - `summary`：层级概览 + 模板模式 + LLM 提示（轻量，~2K tokens）
+  - `full`：在 summary 基础上附加 `componentSummary`（全量组件清单 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层另含 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射 + 注入机制 + 选择器表）+ `assetExtraction`（位图/图标/图表色提取规则）。设计稿 → 代码场景必选 full
+  - `decisions`：含架构决策记录
 
 ### Props 深度解析工具
 

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

@@ -34,12 +34,15 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 ### 步骤1：架构认知（必做）
 
-调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="summary"）获取：
+调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="full"）一次性获取：
 - `templatePatterns`：4种模板模式（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
 - `llmMappingHints.commonMistakes`：LLM 常见映射错误
 - `recommendedUsageOrder`：推荐使用顺序
+- **`componentSummary`**：全量组件清单（cover/wrappers/proPackages/other/echarts），每个组件附带 `layoutRole`（页面定位/区域容器/可视化等）、`variantProps`（关键 variant 参数）、`styleInjection`（样式注入入口）、`useCases`（典型场景）；other/echarts 层还附带 `compositionSlots`、`requiredHooks`、`chartType`、`sketchSignals` 等元信息——LLM 据此推理组件候选
+- **`styleMapping`**：节点样式 → 组件样式的映射规则（nodeStyleRules / injectionMechanisms / selectorMap）
+- **`assetExtraction`**：图标/位图/图表色提取规则（bitmapRules / iconWorkflow / chartColorMapping）
 
-根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板。
+根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板，并在步骤 3.5 用 `componentSummary` 推理组件候选列表。
 
 ### 步骤2：理解需求（必做）
 
@@ -115,11 +118,50 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
 
 **输入**：步骤 2.5 产出的 bitmap ID 列表 + shapePath 节点名列表
 
+#### 🔒 资源优先级铁律（必读，违反则直接重做本步骤）
+
+代码中的每一处图标、背景、装饰资源，必须按以下优先级**依次尝试**，前一级能命中就**不许跳到下一级**：
+
+| 优先级 | 来源 | 适用判定 | 渲染产物 |
+|---|---|---|---|
+| **P0** | **sketch 自带 bitmap** | 节点是 `type=bitmap` | `extractBitmaps` 返回的 `siblingsAfterMe + position + nodeSize` 三维判定渲染产物：区域背景图 / 行内图标 / 独立装饰插图（详见下方表 6） |
+| **P1** | **sketch 自带 shapePath（SVG 直出）** | 独立 shapePath（parent.type !== 'shapeGroup'），P1 未命中且 viewBox 校验通过 | `getShapePathData` → 内联 SVG |
+| **P2** | **sketch 自带 shapePath（iconfont 命中）** | shapePath/shapeGroup 节点名能在 iconfont 库匹配到 | `matchIconFromName` → `<IconfontWapper type='icon-xxx' />` |
+
+| **P3** | **antd 图标语义匹配** | 上面三级都失败：shapeGroup 无法直出、节点名无 iconfont 匹配 | `<XxxOutlined />` 按 contextTable 选语义最近的 antd 图标 |
+| **P4** | **纯 CSS / div 渲染** | 上面四级全部失败，且元素是几何/色块（非图标语义） | `<div style={{...}}>` |
+
+**禁止行为（违反 = 重做）**：
+- ❌ sketch 里有 bitmap 节点，却用 `<div style={{backgroundColor}}>` 模拟（必须 P0 提取真图）
+- ❌ shapePath 节点直接降级 antd 图标，没跑过 `matchIconFromName`（跳过 P1）
+- ❌ 凭节点名"猜"语义就选 antd 图标，没看 parent 上下文（contextTable 在 `assetExtraction.iconWorkflow.contextTable`）
+- ❌ 把 P0 提取出的 base64 写成 hardcoded url 而非 inline data URI（资源会丢）
+
+**前置自检**：步骤 1 拿到的 `assetExtraction.bitmapRules` + `assetExtraction.iconWorkflow` 是上述铁律的服务端权威定义；本步开始前必须已加载，否则回到步骤 1 调 `get_architecture_overview(detail="full")`。
+
 **工具调用**：
 
 1. `mcp__sketch-mcp-server__extractBitmaps`（bitmapIds）— 从 .sketch 解压目录提取 bitmap PNG 资源
-   - 返回 `{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName }] }`
-   - 位图资源用于 CSS `background-image` 引用
+   - 返回（v1.7.0+）：`{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName, position:{x,y}, nodeSize:{width,height}, parentId, parent:{id,name,type,size}, siblingsBeforeMe:[...], siblingsAfterMe:[...] }] }`
+   - **`siblingsAfterMe` 是 z-order 渲染在 bitmap 上方的兄弟节点**（Sketch `layers[]` 排在它之后的项），是判定"区域背景图 vs 独立装饰"的核心信号
+   - **不要再为每个 bitmap 单独跑 `getNodeInfo` 拿 position/parent**，这些字段在 extractBitmaps 返回里已有
+
+##### 表 6：bitmap 用途判定与代码落地（必做）
+
+每个 bitmap 都要按本表归类，**只看 `siblingsAfterMe` + `position` + `nodeSize/parent.size`**，不要凭名字猜。判定后必须落到代码（详见经验 9 的"资源落地校验"）。
+
+| # | 判定信号（联合判断） | 用途 | 代码落地方式 |
+|---|---|---|---|
+| 1 | `siblingsAfterMe.length > 0` **且** `nodeSize.width / parent.size.width >= 0.7` | **区域背景图**（容器底图，内容元素叠在上面） | `parent` 包一层 wrapper div，bitmap 作为 wrapper 的 `style={{backgroundImage:` `url(data:image/png;base64,${base64})` `, backgroundSize:'cover'}}`；`siblingsAfterMe` 作为 wrapper 子节点正常渲染 |
+| 2 | `nodeSize.width <= 32 && nodeSize.height <= 32` **且** 同 parent 内有 text 兄弟（`siblingsBeforeMe + siblingsAfterMe` 含 text） | **行内图标**（表格行图标、按钮前缀图标等） | `<img src={`data:image/png;base64,${base64}`} style={{width:N,height:N}} />` 替换原本的 `<IconfontWapper>` 占位 |
+| 3 | `siblingsAfterMe.length === 0 && siblingsBeforeMe.length === 0`（独占父容器） | **独立装饰插图**（占位图、空状态图等） | `<img src={`data:image/png;base64,${base64}`} style={{width:nodeSize.width,height:nodeSize.height}} />` 走文档流 |
+| 4 | `siblingsAfterMe.length > 0` **但** 占父宽 < 70% | **嵌入式插图**（区域内某子块的背景） | 同 #1，但 wrapper 是该子块而非整个 parent；定位用 `position:'absolute', top:position.y, left:position.x` |
+
+**反例（违反 = 重做）**：
+- ❌ 把 #1 区域背景图渲染为独立 `<img>`（反馈 #14 的 `未编目资源` 493×64 y=52 错例）——丢失"内容叠在底图上"的视觉关系
+- ❌ 把 #2 行内图标用 `backgroundImage` 写在 `<div>` 上——`<div>` 没设宽高就塌缩；用 `<img>` 自带尺寸更稳
+- ❌ 同一 imageRef 多个 nodeId 引用，extractBitmaps 多次调用——只调一次（按 nodeId 列表去重前判断 `fileName`），渲染时复用 base64 引用
+
 2. `mcp__sketch-mcp-server__matchIconFromName`（nodeNames, library="newFont"）— 匹配 iconfont 图标库（v1.5.0+ 评分制）
    - 输入 shapePath 节点名列表（如 `["表 icon", "新建文件夹", "编组11备份"]`）
    - **评分机制**：compoundIcons 强映射 +100、keyword 精确 +20、keyword 包含 +10、semanticTag +3
@@ -239,6 +281,8 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
 
 识别出图表后，**图例色块**应归入 ECharts `legend` 配置（不要用 div 硬编码），**柱体色**映射到 `series.itemStyle.color`。
 
+**图表组件类型选择**：参考步骤 1 返回的 `componentSummary.echarts`，每项含 `chartType`（line/bar/pie 等）和 `sketchSignals`（典型 Sketch 特征），按 sketchSignals 反查 chartType 即可锁定组件名（如 `Line` / `Bar` / `Pie`）。
+
 **经验7：矢量图形用 matchIconFromName 自动匹配，无需手动解压**
 - `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%，但 `renderNodeAsBase64` 不支持渲染
 - **新方案**：`matchIconFromName(shapePathNames)` 自动查询 iconfont 库 → 返回匹配结果
@@ -255,6 +299,23 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
 - 若必须用 CSS class，类名要能反向追到 Sketch 节点（如 `.segmentBlock-blue` 而非 `.beforebg`），且 class 内容必须**精确等于** rectangle 的 fill/border
 - 反例排查：写完代码后 grep 一下 CSS class 名，出现 `.bg1/.box2/.before*` 这类无语义类名、且颜色和设计稿对不上 → 几乎确定是凭空兜底
 
+**经验9：bitmap 资源落地校验（每张 PNG 必须对应一处代码引用）**
+
+实战教训（反馈 #14，2026-06-15）：`未编目资源` bitmap（493×64, y=52）首版被渲染为独立 `<img>` 装饰插图，实际上它是 64px 高统计区域的底图（`siblingsAfterMe` 含 7 个 text/rect 内容元素叠在上面）。9 张 PNG 资源拿到了 base64，但其中 1 张用错位置——这种"提取了但用错"的回退比"忘记提取"更隐蔽。
+
+**校验流程（写代码后必跑）**：
+
+1. 把 `extractBitmaps` 返回的每个 `bitmap` 按表 6 归类，列出"用途清单"（区域背景 N 个、行内图标 N 个、独立装饰 N 个）
+2. 在生成的代码里 grep `data:image/png;base64`，统计实际引用数 ≥ 用途清单总数（去重后）
+3. 对每个 #1 区域背景图核对：是否真的写在 wrapper div 的 `style.backgroundImage` 上？wrapper 内部是否包含 `siblingsAfterMe` 列出的子节点？
+4. 对每个 #2 行内图标核对：原本在该位置的 `<IconfontWapper>` / antd 图标是否已被 `<img>` 替换？
+5. 对每个 #3 独立装饰核对：是否在 parent 的纵向流中出现？
+
+**反例（违反 = 重做）**：
+- ❌ extractBitmaps 拿到 9 张 PNG，代码里只 grep 出 8 个 `data:image/png;base64` 引用——必有 1 张被丢
+- ❌ #1 区域背景图被错放成独立 `<img>`，导致 `siblingsAfterMe` 的内容元素失去底图衬托（这是反馈 #14 的具体回退）
+- ❌ 同 imageRef 多次出现（如 `文件备份2/3/4` 复用同一 PNG），代码生成了 N 份 base64 字符串而非引用同一个常量——文件大小翻倍
+
 ### 步骤2.6：布局推理（必做，写代码前的最后一道关）
 
 ⚠️ 这一步专治"数据全拿到却放错位置"。反馈 #11 的 5 处错位全部由跳过此步骤导致。
@@ -391,23 +452,14 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
 - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
 - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
 
-**推理时使用映射规则**（**此表为本步骤专用，核心高频场景**）：
-
-| Sketch 特征 | 推断组件 |
-|---|---|
-| 左右分区布局 | `TemplateMode(templateType="LeftRight")` |
-| 上下分区布局 | `TemplateMode(templateType="TopBottom")` |
-| 左侧窄区域 + 树形图层 | `LeftTree` |
-| 顶部输入框/下拉框/日期选择器 | `Query` |
-| 中间表头 + 数据行图层 | `TableOrList` |
-| 弹窗/抽屉图层 | `ModelOrDrawer` |
-| 页面标题 + 返回箭头 | `TitleAndBack` |
-| 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` |
-| 卡片列表 | `TableOrList(componentType="ProList")` |
-| 可编辑表格 | `TableOrList(componentType="EditableProTable")` |
-| 折线趋势图 | `Line` |
-| 柱状对比图 | `Bar` |
-| 饼图/环形图 | `Pie` |
+**推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录，每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
+
+1. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（TemplateMode）匹配 `templateType` 变体
+2. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer 等），按 `useCases` 描述匹配 Sketch 区域语义
+3. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
+4. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
+
+不要再依赖任何硬编码映射表——`componentSummary` 由组件库源码动态生成，是唯一可信源。
 
 ### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@szc-ft/mcp-szcd-client",
-    "version": "0.26.0",
+    "version": "0.27.1",
     "description": "MCP client for szcd component library - auto-configures AI coding tools with MCP server, skills, agents and commands",
     "keywords": [
         "mcp",

package/qwen-extension/agents/szcd-component-expert.md

@@ -38,7 +38,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
 **在正式开始之前，获取项目架构全局视图，同时验证 MCP 连接。**
 
 执行动作：
-1. 调用 `get_architecture_overview`（detail="summary"）获取7层架构图、模板组合模式、推荐使用顺序和 LLM 映射错误提示
+1. 调用 `get_architecture_overview`（detail="full"）一次性获取：7 层架构图、模板组合模式、推荐使用顺序、LLM 映射错误提示，**以及 `componentSummary`（全量组件 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射）+ `assetExtraction`（图标/位图/图表色提取规则）**——这些是步骤 3.5 推理组件候选和步骤 5 样式注入的核心依据
 2. 如果连接失败，**立即停止并返回错误信息**，告知用户需要先配置 MCP 服务器
 3. 如果成功，根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板
 
@@ -366,6 +366,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
 
 **输入**：
 - 步骤 1 的 `get_architecture_overview` 返回的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
+- 步骤 1 的 `componentSummary`：全量组件 + 设计元信息（layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）—— **推理组件候选的权威目录，长尾场景按 layoutRole / useCases / sketchSignals 直接反查**
 - 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
 - 步骤 2.5 的 Sketch 节点结构 + 样式 Token
 - 或步骤 3 的图片分析描述
@@ -379,38 +380,15 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
 - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
 - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
 
-**推理时使用映射规则**（**此表为本步骤专用，仅含核心高频场景**）：
+**推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录（由组件库源码动态生成），每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
 
-*页面级布局*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
-| 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
-| 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
-| 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
+1. **画板名称** → 直接作为 `pageName`
+2. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（如 TemplateMode），结合 `variantProps.templateType`（LeftRight / TopBottom）和 `templatePatterns`（TreeQueryTable / QueryTabsTables）选模板
+3. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack / FormItemOrDetailItem 等），按 `useCases` 描述匹配 Sketch 区域语义
+4. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
+5. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
 
-*区域级组件*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
-| 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
-| 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
-| 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
-| 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
-| 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
-
-*数据可视化（核心 3 类）*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
-| 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
-| 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
-
-*表格子类型（核心 2 类）*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
-| 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
+不要硬编码任何「Sketch 特征 → 组件」对照表——`componentSummary` 是唯一可信源，硬编码表会和服务端动态扫描结果漂移。
 
 #### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
 

package/qwen-extension/qwen-extension.json

@@ -1,6 +1,6 @@
 {
     "name": "szcd-component-helper",
-    "version": "0.26.0",
+    "version": "0.27.1",
     "description": "szcd 组件库 MCP 助手 — 查询组件信息、匹配需求、生成代码",
     "mcpServers": {
         "szcd-component-helper": {