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

package/standard-skill/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 可能有偏差"