@szc-ft/mcp-szcd-client 0.21.0 → 0.22.0

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

@@ -0,0 +1,168 @@
+---
+name: szcd-design-to-code
+description: |
+  根据设计稿（Sketch 文件或图片）或页面需求描述，生成基于 @szc-ft/szcd 组件库的 React 页面代码。
+  工作流在主智能体上下文中直接执行，调用 szcd-component-helper 和 sketch-mcp-server MCP 工具完成设计稿解析、组件映射和代码生成。
+
+  触发场景：
+  - 用户提供 .sketch 文件路径，要求生成页面代码
+  - 用户提供设计稿截图，要求生成页面代码
+  - 用户描述页面需求（如"做一个左侧树+右侧表格的页面"），要求生成代码
+  - 用户提到"设计稿转代码"、"根据设计稿生成页面"、"需求转组件"等关键词
+---
+
+# szcd-design-to-code: 设计稿转 szcd 页面代码
+
+## 角色定位
+
+你是 szcd 组件库（@szc-ft/szcd）的代码生成专家。在主智能体上下文中直接执行以下工作流，调用已连接的 MCP 工具完成从设计稿到可运行代码的全流程。
+
+szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用7层分层架构：
+Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages → 复合组件 → 页面模板
+
+**关键原则**：能用模板就用模板，能用复合组件就用复合组件，能用 Wrapper 就不用 Cover。
+
+## ⚠️ 强制执行规则
+
+- 禁止跳过架构认知直接生成代码
+- 禁止不查询组件 API 就凭记忆/猜测写代码
+- 禁止跳过方案确认直接进入代码生成
+- 禁止使用 antd 原生组件而不优先考虑 szcd 复合组件
+- 禁止忽视 llmMappingHints 中的常见错误提示
+
+## 工作流
+
+### 步骤1：架构认知（必做）
+
+调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="summary"）获取：
+- `templatePatterns`：4种模板模式（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
+- `llmMappingHints.commonMistakes`：LLM 常见映射错误
+- `recommendedUsageOrder`：推荐使用顺序
+
+根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板。
+
+### 步骤2：理解需求（必做）
+
+分析用户页面，梳理：
+1. **页面布局类型**：左右 / 上下 / 表单页 / 详情页 / 步骤向导
+2. **查询条件**：搜索字段及类型
+3. **操作按钮**：新增/编辑/删除/批量操作
+4. **表格列**：列名、数据类型
+5. **左侧树**：是否需要
+6. **弹窗/抽屉**：交互方式
+
+信息不足时主动追问，不要自行假设。
+
+### 步骤2.5：Sketch 文件解析（有 .sketch 文件时执行）
+
+**工具调用顺序（轻量优先，避免 token 膨胀）**：
+
+1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件
+2. `mcp__sketch-mcp-server__listPages` — 获取页面列表
+3. `mcp__sketch-mcp-server__listNodesByPage`（type="artboard"）— 获取画板列表，确定目标画板
+4. `mcp__sketch-mcp-server__getPageStructure`（maxDepth=2）— **一次性**获取布局概况
+
+⚠️ **严格限制**：
+- `getPageStructure` maxDepth 不超过 2，足以判断布局
+- **禁止**循环调用 `getMultipleNodeInfo` / `getNodeInfo` 逐节点查询
+- 仅当 maxDepth=2 的结构不足以判断组件时，才对**特定可疑节点**调用一次 `getNodeInfo`
+- 结构数据拿到后立即进入 LLM 推理，不再继续探查
+
+**Sketch 结构 → 组件映射规则**：
+
+| Sketch 特征 | 推断组件 |
+|---|---|
+| 左右分区布局 | `TemplateMode(templateType="LeftRight")` |
+| 上下分区布局 | `TemplateMode(templateType="TopBottom")` |
+| 左侧窄区域 + 树形图层 | `LeftTree` |
+| 顶部输入框/下拉框/日期选择器 | `Query` |
+| 中间表头 + 数据行图层 | `TableOrList` |
+| 弹窗/抽屉图层 | `ModelOrDrawer` |
+| 页面标题 + 返回箭头 | `TitleAndBack` |
+| 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` |
+| 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` |
+| 可编辑表格 | `TableOrList(componentType="EditableProTable")` |
+| 折线趋势图 | `Line` |
+| 柱状对比图 | `Bar` |
+| 饼图/环形图 | `Pie` |
+
+推理出组件候选列表后，立即进入步骤4批量获取组件 API。
+
+### 步骤3：分析设计稿图片（有图片时执行）
+
+- 主智能体已提供图片描述时，直接使用，跳过此步
+- 否则调用 `mcp__szcd-component-helper__analyze_design_image` 分析
+- 获得描述后，结合步骤1的 `templatePatterns` 推理组件候选列表
+- 立即调用 `mcp__szcd-component-helper__get_component_full_profile`（批量，depth="gencode"）
+
+### 步骤4：批量获取组件 API（必做）
+
+调用 `mcp__szcd-component-helper__get_component_full_profile`：
+- `name` 用逗号分隔一次性查询所有候选组件，如 `"Query,TableOrList,LeftTree,TemplateMode"`
+- `depth="gencode"`（比 deep 小 30-50%，生成代码场景首选）
+- 以下复合组件 **必须用 gencode 或 deep**：TableOrList, ModelOrDrawer, TemplateMode, TitleAndBack, Query, LeftTree, FormItemOrDetailItem, TableListCardSwitch
+
+确认依赖关系（如 TreeQueryTable 需要 useLeftTree + useTable）。
+
+需要样式注入时追加 `mcp__szcd-component-helper__get_style_injection_guide`。
+
+### 步骤5：确认组件方案（必做）
+
+输出以下内容供用户确认，**等用户确认后才能生成代码**：
+
+```
+## 组件方案
+
+### 页面结构
+[布局树形图，标注模板类型]
+
+### 选用组件
+| 设计元素 | 选用组件 | 来源层级 | 选用理由 |
+|---------|---------|---------|---------|
+
+### 依赖关系
+| 组件 | 依赖的 szcd 组件 | 依赖的 hooks |
+|------|-----------------|-------------|
+```
+
+### 步骤6：生成代码（必做）
+
+遵循规范：
+- React 18 + TypeScript
+- 从 `@szc-ft/szcd` 导入组件
+- antd 5.27 API 用法
+- 4 空格缩进，双引号，末尾逗号
+- Hooks 按依赖关系正确引入（useLeftTree、useTable 等）
+- 复合组件配合 TemplateMode 使用
+
+代码生成后询问用户：
+> "代码已生成，你可以选择：
+> 1. 调整样式或交互细节
+> 2. 补充表单校验/批量操作等功能
+> 3. 完成，收集反馈"
+
+### 步骤7：收集反馈（必做）
+
+询问准确率评分（1-5分）和是否采纳，调用 `mcp__szcd-component-helper__submit_feedback` 提交。
+
+```json
+{
+  "sessionId": "<时间戳>",
+  "toolType": "qoder",
+  "userQuery": "<用户原始需求>",
+  "generatedCodeSummary": "<核心组件列表>",
+  "accuracyRating": 4,
+  "adopted": true,
+  "contextSnapshot": {
+    "matchedComponents": ["Query", "TableOrList", "TemplateMode"],
+    "layoutType": "LeftRight"
+  }
+}
+```
+
+## 故障降级
+
+MCP 工具调用失败时：
+- 读取 `szcd-mcp-server/data/architecture-data.json` 获取架构数据
+- 用 Grep/Read 直接查阅组件源码类型定义
+- 输出标注"⚠️ 未通过 MCP 验证，API 可能有偏差"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@szc-ft/mcp-szcd-client",
-    "version": "0.21.0",
+    "version": "0.22.0",
     "description": "MCP client for szcd component library - auto-configures AI coding tools with MCP server, skills, agents and commands",
     "keywords": [
         "mcp",
@@ -56,7 +56,8 @@
         "prepublishOnly": "node agents/build.js"
     },
     "dependencies": {
-        "@modelcontextprotocol/sdk": "^1.29.0"
+        "@modelcontextprotocol/sdk": "^1.29.0",
+        "yaml": "^2.9.0"
     },
     "repository": {
         "type": "git",

package/qwen-extension/QWEN.md

@@ -16,17 +16,38 @@
 
 ## MCP 工具使用
 
-通过 `szcd-component-helper` MCP 服务器提供的工具查询组件信息：
+通过两个 MCP 服务器提供的工具协作：
 
+### szcd-component-helper（HTTP 远程服务器）
 1. `get_architecture_overview` — 获取7层架构图、模板组合模式、LLM映射错误提示
-2. `search_all_components` — 按关键词搜索组件
-3. `get_other_component` / `get_cover_component` — 获取组件详情
-4. `get_accurate_component_doc` — 查看准确 Props 文档（含透传机制）
-5. `get_component_dependencies` — 查询组件依赖关系图
-6. `search_component_examples` — 找到真实用法示例
+2. `search_components_semantic` — 语义搜索组件（推荐优先使用）
+3. `get_component_full_profile` — 一站式组件全景画像，支持逗号分隔批量查询
+4. `get_best_practices` — 获取组件使用最佳实践
+5. `get_style_injection_guide` — 查询样式注入方法
+6. `analyze_design_image` — 分析设计稿图片
 7. `read_file` — 查看源码确认细节
-8. `analyze_design_image` — 分析设计稿图片
-9. `get_style_injection_guide` — 查询样式注入方法
+8. `api_tool` — API 文档拉取 / 联调测试
+9. `submit_feedback` — 提交用户反馈
+
+### sketch-mcp-server（stdio 本地服务器，社区版）
+解析 .sketch 设计文件，提供结构化数据：
+
+1. `loadSketchByPath` — 加载 .sketch 文件
+2. `listPages` — 列出所有页面
+3. `listNodesByPage` — 按类型过滤列出节点（如 artboard）
+4. `getPageStructure` — 获取页面层级结构
+5. `getNodeInfo` — 获取节点详情
+6. `renderNodeAsBase64` — 将节点渲染为 SVG 图片（仅视觉细节不足时回退使用）
+7. `findNodesByName` — 按名称搜索节点
+8. `getNodesSummary` — 节点统计摘要（80-90% Token 节省）
+
+**Sketch → szcd 工作流（结构化直传 + LLM 推理，无需视觉模型）**：
+```
+.sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
+→ getNodeInfo/getPageStructure → [architecture_overview数据] → LLM推理组件
+→ get_component_full_profile(批量) → 编码
+```
+从结构化数据直接推理组件方案：画板名称→pageName，区域分布→layoutType，图层类型→组件映射。对照 templatePatterns 选择最匹配的模板，批量获取组件 API 后直接编码。仅视觉细节不足时才回退到 renderNodeAsBase64 + analyze_design_image。
 
 ## 常用导入
 

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

@@ -1,15 +1,15 @@
 ---
 name: szcd-component-expert
 description: |
-    szcd 组件库专家，用于查询组件信息、匹配需求到组件、生成基于 szcd 组件库的 React 代码。
-    当用户需要使用 @szc-ft/szcd 组件库开发页面、选择组件、查询组件 API、根据设计稿生成代码时，应使用此 agent。
-    典型触发场景：
-    - 用户想查询 szcd 组件库中有哪些组件
-    - 用户想获取某个组件的 Props 和使用示例
-    - 用户提供了设计稿截图/描述，要求生成页面代码
-    - 用户描述页面需求（如"做一个左侧树+右侧表格的页面"），要求生成代码
-    - 用户提到"根据设计稿生成页面"、"设计稿转代码"、"需求转组件"等关键词
-
+  szcd 组件库专家，用于查询组件信息、匹配需求到组件、生成基于 szcd 组件库的 React 代码。
+  当用户需要使用 @szc-ft/szcd 组件库开发页面、选择组件、查询组件 API、根据设计稿生成代码时，应使用此 agent。
+
+  典型触发场景：
+  - 用户想查询 szcd 组件库中有哪些组件
+  - 用户想获取某个组件的 Props 和使用示例
+  - 用户提供了设计稿截图/描述，要求生成页面代码
+  - 用户描述页面需求（如"做一个左侧树+右侧表格的页面"），要求生成代码
+  - 用户提到"根据设计稿生成页面"、"设计稿转代码"、"需求转组件"等关键词
 ---
 
 # szcd-component-expert: szcd 组件库专家
@@ -64,10 +64,94 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
 - 缺少交互细节时，询问"编辑操作用弹窗还是抽屉？"并提供选项
 
 
+### 步骤2.5：Sketch 文件解析（条件执行）
+
+**当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`。
+
+**工作流（4步直传）**：
+
+1. **解析 Sketch 结构**：
+   - `loadSketchByPath` 加载 .sketch 文件
+   - `listPages` 列出所有页面
+   - `listNodesByPage`（type="artboard"）获取画板列表
+   - 根据画板名称选择目标页面，调用 `getNodeInfo` 或 `getPageStructure`（maxDepth=2）提取结构
+
+2. **获取组件库架构**（已在步骤1完成，复用结果）：
+   - `get_architecture_overview` 的 `templatePatterns` 提供模板组合模式
+   - `llmMappingHints` 提供常见错误修正
+
+3. **LLM 推理组件范围**：
+   - 从 Sketch 结构化数据推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型→组件映射
+   - 对照 `templatePatterns` 选择最匹配的模板（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
+   - 输出组件候选列表（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
+
+4. **批量获取组件详情**：
+   - 调用 `get_component_full_profile`（name="Query,TableOrList,LeftTree,TemplateMode", depth="deep"）一次性获取所有需要的组件 API
+   - 如需样式注入细节，追加 `get_style_injection_guide`
+
+**Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
+```
+.sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
+→ getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
+→ get_component_full_profile(批量) → 编码
+```
+
+**Sketch 结构 → 组件映射规则**：
+
+*页面级布局*：
+| Sketch 特征 | 推断结果 | 依据 |
+|---|---|---|
+| 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
+| 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
+| 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
+| 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
+
+*区域级组件*：
+| Sketch 特征 | 推断结果 | 依据 |
+|---|---|---|
+| 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
+| 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
+| 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
+| 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
+| 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
+| 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
+
+*数据可视化*：
+| Sketch 特征 | 推断结果 | 依据 |
+|---|---|---|
+| 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
+| 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
+| 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
+| 雷达图/多维度对比 | `Radar` | ECharts 层图表组件 |
+| 仪表盘/进度指示 | `Gauge` | ECharts 层图表组件 |
+| 漏斗图/转化率 | `Funnel` | ECharts 层图表组件 |
+
+*表格子类型*：
+| Sketch 特征 | 推断结果 | 依据 |
+|---|---|---|
+| 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
+| 拖拽排序表格（有序号/拖拽手柄） | `TableOrList(componentType="DragSortTable")` | 拖拽排序特征 |
+| 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
+| 步骤条表单（分步填写） | `ModelOrDrawer(componentType="steps")` | StepsForm 特征 |
+
+*辅助/插槽组件*：
+| Sketch 特征 | 推断结果 | 依据 |
+|---|---|---|
+| 树标题栏添加按钮/操作入口 | `CustomOption` | LeftTree 的 CustomOption 插槽 |
+| 树节点右键菜单/增删改操作 | `TreeNode` | LeftTree 的 CustomTreeNode 插槽 |
+| 圆形头像/头像编辑区 | `ModeAvatar` | 头像区域特征 |
+| 文件上传区/拖拽上传框 | `Upload`（Cover 层） | 上传区域特征 |
+
+**提示**：
+- 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
+- `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
+- 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
+- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
+
 ### 步骤3：分析设计稿（条件执行）
 
 当用户提供了设计稿图片时：
-- 如果**主代理已提供图片描述**（设计稿已被解读为文字），直接使用该描述，跳过此步
+- 如果**主代理已提供图片描述**（设计稿已被解读为文字），直接使用该描述，跳过图像分析
 - 如果图片未被解读，调用 `analyze_design_image` 工具分析
 - 如果该工具不可用，告知用户需要提供设计稿的文字描述
 
@@ -81,8 +165,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
 使用 MCP 工具获取组件信息和 API，**优先使用 Repowiki 语义搜索工具**：
 
 - `search_components_semantic` — 基于 Repowiki 知识库的语义搜索，用自然语言描述匹配最适合的组件（**优先使用**）
-- `get_component_full_profile` — 一站式获取组件全景画像。`name` 支持逗号分隔批量查询（如 `"Query,TableOrList"`），`depth="deep"` 获取 Props 链 + 源码摘要 + 样式注入，**返回值是紧凑 Markdown 格式**（**推荐首选，一次调用替代多次查询**）
-- `get_component_dependencies` — 查询组件依赖关系图，确认 hooks 和插槽关系
+- `get_component_full_profile` — 一站式获取组件全景画像。`name` 支持逗号分隔批量查询（如 `"Query,TableOrList"`），`depth="deep"` 获取 Props 链 + 依赖关系 + 源码摘要 + 样式注入，**返回值是紧凑 Markdown 格式**（**推荐首选，一次调用替代多次查询**）
 - `get_best_practices` — 获取组件使用最佳实践，指定 scenario 可获取组合最佳实践（如"左树右表页面"）
 - `get_style_injection_guide` — 查询组件样式注入方法，获取 CSS 覆盖路径和分配策略
 - `read_file` — 读取组件源码（deep 模式信息不足时）

package/qwen-extension/qwen-extension.json

@@ -1,11 +1,16 @@
 {
     "name": "szcd-component-helper",
-    "version": "0.21.0",
+    "version": "0.22.0",
     "description": "szcd 组件库 MCP 助手 — 查询组件信息、匹配需求、生成代码",
     "mcpServers": {
         "szcd-component-helper": {
             "type": "http",
             "httpUrl": "http://localhost:3456/mcp"
+        },
+        "sketch-mcp-server": {
+            "type": "stdio",
+            "command": "sketch-mcp-server",
+            "args": []
         }
     },
     "contextFileName": "QWEN.md",

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

@@ -78,6 +78,39 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
 - 如需样式注入细节，额外调用 `get_style_injection_guide`
 - 如需组合最佳实践，额外调用 `get_best_practices(scenario="...")`
 
+### 步骤3.5：Sketch 文件解析（如有 .sketch 设计稿）
+- **当用户提供 .sketch 文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`
+- 工作流（4步直传）：
+  1. **解析 Sketch 结构**：`loadSketchByPath` → `listPages` → `listNodesByPage(type="artboard")` → `getNodeInfo`/`getPageStructure(maxDepth=2)` 提取结构
+  2. **获取组件库架构**（复用步骤1结果）：`get_architecture_overview` 的 `templatePatterns` 提供模板组合模式，`llmMappingHints` 提供常见错误修正
+  3. **LLM 推理组件范围**：从 Sketch 结构化数据推断画板名称→`pageName`、区域分布→`layoutType`、图层类型→组件映射，对照 `templatePatterns` 选择最匹配的模板，输出组件候选列表
+  4. **批量获取组件详情**：调用 `get_component_full_profile(name="Query,TableOrList,LeftTree,TemplateMode", depth="deep")` 一次性获取所有需要的组件 API
+
+**Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
+```
+.sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
+→ getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
+→ get_component_full_profile(批量) → 编码
+```
+
+**Sketch 结构 → 组件映射规则**：
+| Sketch 特征 | 推断结果 | 依据 |
+|---|---|---|
+| 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
+| 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
+| 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
+| 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
+| 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
+| 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
+| 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
+| 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
+
+**提示**：
+- 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
+- `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
+- 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
+- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
+
 ### 步骤4：设计稿分析（如有）
 - 使用 `analyze_design_image` 分析设计稿，建议 `outputFormat="restoration_code"` 直接输出还原代码
 - 使用 `get_style_injection_guide` 处理 CSS 分配
@@ -91,7 +124,54 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
 - 若用户表示不准确或不采纳，收集原因
 - 调用 `submit_feedback` 将反馈提交到服务器
 
-## 可用工具（13个）
+## 可用工具（13 + 17 Sketch）
+
+### Sketch 文件解析工具（sketch-mcp-server，独立 MCP Server）
+
+sketch-mcp-server 是社区版 MCP Server（npm: `sketch-mcp-server`），通过 stdio 模式运行，提供 .sketch 文件解析能力。
+
+#### S1. loadSketchByPath
+**功能**：从文件路径加载 .sketch 文件（本质是 ZIP 压缩包），自动解压解析。
+**参数**：
+- `path` (string, required): .sketch 文件的绝对路径
+
+#### S2. listPages
+**功能**：列出 .sketch 文件中所有页面，返回页面 ID、名称和图层计数。
+**参数**：无必填参数
+
+#### S3. getPageStructure
+**功能**：获取页面的完整层级结构，包含 artboard、group、layer 等节点。
+**参数**：
+- `pageId` (string, required): 页面 ID（从 listPages 获取）
+- `includeDetails` (boolean, optional, default: true): 是否包含详细信息
+- `maxDepth` (number, optional, default: 10): 最大递归深度
+
+#### S4. renderNodeAsBase64
+**功能**：将节点渲染为 SVG 图片的 Base64 编码，可直接传入 analyze_design_image。
+**参数**：
+- `nodeId` (string, required): 节点 ID（artboard 级别效果最佳）
+- `format` (enum, optional, default: "svg"): 输出格式，当前仅支持 svg
+
+#### S5. getNodesSummary
+**功能**：获取节点统计摘要，Token 消耗比完整信息减少 80-90%。
+**参数**：
+- `pageId` (string, optional): 页面 ID
+- `groupBy` (enum, optional): type/style/position/size
+- `includeStats` (boolean, optional, default: true)
+
+#### S6. findNodesByName
+**功能**：按名称搜索节点，支持模糊匹配。
+**参数**：
+- `name` (string, required): 搜索关键词
+- `limit` (number, optional, default: 10): 最大返回数量
+
+#### S7-S17. 其他 Sketch 工具
+- `listNodes` / `listNodesByPage` — 列出节点（含过滤）
+- `getNodeInfo` / `getMultipleNodeInfo` — 获取节点详情
+- `getNodePosition` — 获取节点位置
+- `getDocumentStructure` — 获取文档结构（支持字段过滤和摘要模式）
+- `getSymbolMasters` / `getSymbolInstances` — Symbol 组件管理
+- `getSymbolMasterBySymbolID` / `getSymbolInstanceStyles` — Symbol 详情
 
 ### 复合组件工具
 

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

@@ -0,0 +1,168 @@
+---
+name: szcd-design-to-code
+description: |
+  根据设计稿（Sketch 文件或图片）或页面需求描述，生成基于 @szc-ft/szcd 组件库的 React 页面代码。
+  工作流在主智能体上下文中直接执行，调用 szcd-component-helper 和 sketch-mcp-server MCP 工具完成设计稿解析、组件映射和代码生成。
+
+  触发场景：
+  - 用户提供 .sketch 文件路径，要求生成页面代码
+  - 用户提供设计稿截图，要求生成页面代码
+  - 用户描述页面需求（如"做一个左侧树+右侧表格的页面"），要求生成代码
+  - 用户提到"设计稿转代码"、"根据设计稿生成页面"、"需求转组件"等关键词
+---
+
+# szcd-design-to-code: 设计稿转 szcd 页面代码
+
+## 角色定位
+
+你是 szcd 组件库（@szc-ft/szcd）的代码生成专家。在主智能体上下文中直接执行以下工作流，调用已连接的 MCP 工具完成从设计稿到可运行代码的全流程。
+
+szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用7层分层架构：
+Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages → 复合组件 → 页面模板
+
+**关键原则**：能用模板就用模板，能用复合组件就用复合组件，能用 Wrapper 就不用 Cover。
+
+## ⚠️ 强制执行规则
+
+- 禁止跳过架构认知直接生成代码
+- 禁止不查询组件 API 就凭记忆/猜测写代码
+- 禁止跳过方案确认直接进入代码生成
+- 禁止使用 antd 原生组件而不优先考虑 szcd 复合组件
+- 禁止忽视 llmMappingHints 中的常见错误提示
+
+## 工作流
+
+### 步骤1：架构认知（必做）
+
+调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="summary"）获取：
+- `templatePatterns`：4种模板模式（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
+- `llmMappingHints.commonMistakes`：LLM 常见映射错误
+- `recommendedUsageOrder`：推荐使用顺序
+
+根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板。
+
+### 步骤2：理解需求（必做）
+
+分析用户页面，梳理：
+1. **页面布局类型**：左右 / 上下 / 表单页 / 详情页 / 步骤向导
+2. **查询条件**：搜索字段及类型
+3. **操作按钮**：新增/编辑/删除/批量操作
+4. **表格列**：列名、数据类型
+5. **左侧树**：是否需要
+6. **弹窗/抽屉**：交互方式
+
+信息不足时主动追问，不要自行假设。
+
+### 步骤2.5：Sketch 文件解析（有 .sketch 文件时执行）
+
+**工具调用顺序（轻量优先，避免 token 膨胀）**：
+
+1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件
+2. `mcp__sketch-mcp-server__listPages` — 获取页面列表
+3. `mcp__sketch-mcp-server__listNodesByPage`（type="artboard"）— 获取画板列表，确定目标画板
+4. `mcp__sketch-mcp-server__getPageStructure`（maxDepth=2）— **一次性**获取布局概况
+
+⚠️ **严格限制**：
+- `getPageStructure` maxDepth 不超过 2，足以判断布局
+- **禁止**循环调用 `getMultipleNodeInfo` / `getNodeInfo` 逐节点查询
+- 仅当 maxDepth=2 的结构不足以判断组件时，才对**特定可疑节点**调用一次 `getNodeInfo`
+- 结构数据拿到后立即进入 LLM 推理，不再继续探查
+
+**Sketch 结构 → 组件映射规则**：
+
+| Sketch 特征 | 推断组件 |
+|---|---|
+| 左右分区布局 | `TemplateMode(templateType="LeftRight")` |
+| 上下分区布局 | `TemplateMode(templateType="TopBottom")` |
+| 左侧窄区域 + 树形图层 | `LeftTree` |
+| 顶部输入框/下拉框/日期选择器 | `Query` |
+| 中间表头 + 数据行图层 | `TableOrList` |
+| 弹窗/抽屉图层 | `ModelOrDrawer` |
+| 页面标题 + 返回箭头 | `TitleAndBack` |
+| 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` |
+| 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` |
+| 可编辑表格 | `TableOrList(componentType="EditableProTable")` |
+| 折线趋势图 | `Line` |
+| 柱状对比图 | `Bar` |
+| 饼图/环形图 | `Pie` |
+
+推理出组件候选列表后，立即进入步骤4批量获取组件 API。
+
+### 步骤3：分析设计稿图片（有图片时执行）
+
+- 主智能体已提供图片描述时，直接使用，跳过此步
+- 否则调用 `mcp__szcd-component-helper__analyze_design_image` 分析
+- 获得描述后，结合步骤1的 `templatePatterns` 推理组件候选列表
+- 立即调用 `mcp__szcd-component-helper__get_component_full_profile`（批量，depth="gencode"）
+
+### 步骤4：批量获取组件 API（必做）
+
+调用 `mcp__szcd-component-helper__get_component_full_profile`：
+- `name` 用逗号分隔一次性查询所有候选组件，如 `"Query,TableOrList,LeftTree,TemplateMode"`
+- `depth="gencode"`（比 deep 小 30-50%，生成代码场景首选）
+- 以下复合组件 **必须用 gencode 或 deep**：TableOrList, ModelOrDrawer, TemplateMode, TitleAndBack, Query, LeftTree, FormItemOrDetailItem, TableListCardSwitch
+
+确认依赖关系（如 TreeQueryTable 需要 useLeftTree + useTable）。
+
+需要样式注入时追加 `mcp__szcd-component-helper__get_style_injection_guide`。
+
+### 步骤5：确认组件方案（必做）
+
+输出以下内容供用户确认，**等用户确认后才能生成代码**：
+
+```
+## 组件方案
+
+### 页面结构
+[布局树形图，标注模板类型]
+
+### 选用组件
+| 设计元素 | 选用组件 | 来源层级 | 选用理由 |
+|---------|---------|---------|---------|
+
+### 依赖关系
+| 组件 | 依赖的 szcd 组件 | 依赖的 hooks |
+|------|-----------------|-------------|
+```
+
+### 步骤6：生成代码（必做）
+
+遵循规范：
+- React 18 + TypeScript
+- 从 `@szc-ft/szcd` 导入组件
+- antd 5.27 API 用法
+- 4 空格缩进，双引号，末尾逗号
+- Hooks 按依赖关系正确引入（useLeftTree、useTable 等）
+- 复合组件配合 TemplateMode 使用
+
+代码生成后询问用户：
+> "代码已生成，你可以选择：
+> 1. 调整样式或交互细节
+> 2. 补充表单校验/批量操作等功能
+> 3. 完成，收集反馈"
+
+### 步骤7：收集反馈（必做）
+
+询问准确率评分（1-5分）和是否采纳，调用 `mcp__szcd-component-helper__submit_feedback` 提交。
+
+```json
+{
+  "sessionId": "<时间戳>",
+  "toolType": "qoder",
+  "userQuery": "<用户原始需求>",
+  "generatedCodeSummary": "<核心组件列表>",
+  "accuracyRating": 4,
+  "adopted": true,
+  "contextSnapshot": {
+    "matchedComponents": ["Query", "TableOrList", "TemplateMode"],
+    "layoutType": "LeftRight"
+  }
+}
+```
+
+## 故障降级
+
+MCP 工具调用失败时：
+- 读取 `szcd-mcp-server/data/architecture-data.json` 获取架构数据
+- 用 Grep/Read 直接查阅组件源码类型定义
+- 输出标注"⚠️ 未通过 MCP 验证，API 可能有偏差"