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

package/standard-skill/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/standard-skill/szcd-design-to-code/SKILL.md

@@ -0,0 +1,177 @@
+---
+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 文件时执行）
+
+**核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。一次 `getMultipleNodeInfo(50-100 个节点)` 比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
+
+**工具调用顺序（深度探查，像素级还原）**：
+
+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`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID（含初始样式）
+5. `mcp__sketch-mcp-server__getNodesSummary`（pageId, groupBy="type"）— 按类型分组统计，识别组件模式
+   - `group(rectangle + text)` = 标签组件
+   - `group(text + text + rectangle...)` = 表单项
+   - 统计各类型数量，决定下一批查询范围
+6. `mcp__sketch-mcp-server__getMultipleNodeInfo`（[id1, id2, ...]）— **批量查询所有 type=text 和 type=rectangle 节点**，每次 ≤ 100 个
+   - 关键字段：`style.fills[0].color.hex`（背景色）、`text.color`（文字色）、`style.fontSize`、`style.fontWeight`
+   - 不要逐个 `getNodeInfo`，太慢且容易漏
+
+**⚠️ 与旧策略的差异**：
+- 旧策略：maxDepth=2 拿布局，样式靠组件默认
+- 新策略：includeDetails=true + 批量 `getMultipleNodeInfo` 拿所有 text/rectangle 完整样式 Token
+- 适用场景：需要像素级还原设计稿（颜色、字号、标签背景色等）
+- 代价：token 消耗约 10 倍（旧策略的几 KB → 新策略的几十到几百 KB，取决于节点数）
+
+**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 可能有偏差"