@szc-ft/mcp-szcd-client 0.11.5 → 0.12.0

package/README.md

@@ -0,0 +1,143 @@
+# @szc-ft/mcp-szcd-client
+
+szcd 组件库 MCP 客户端 — 自动配置 AI 编码工具的 MCP 服务器连接、Skills、Agents 和 Commands。
+
+## 安装
+
+```bash
+npm install @szc-ft/mcp-szcd-client
+```
+
+安装后自动执行配置，支持以下 AI 编码工具：
+
+| 工具 | 配置方式 |
+|------|---------|
+| Claude Code | `~/.claude.json` + `~/.claude/agents/` + `~/.claude/skills/` |
+| Trae CLI | `~/.traecli/trae_cli.yaml` |
+| Trae IDE | `~/.trae-cn/mcp.json` + `~/.trae-cn/agents/` |
+| Qoder CLI | `~/.qoder/settings.json` + `~/.qoder/agents/` + `~/.qoder/skills/` |
+| Qwen Code | `~/.qwen/extensions/szcd-component-helper/`（扩展机制） |
+
+## 连接方式
+
+### 方式1: 本地直连 (stdio)
+
+无需远程服务器，每次启动时本地运行 MCP 服务器进程：
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "command": "npx",
+      "args": ["szcd-mcp-server", "--stdio"]
+    }
+  }
+}
+```
+
+### 方式2: Streamable HTTP 远程连接（推荐）
+
+连接到远程运行的 MCP 服务器，多客户端共享：
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "type": "http",
+      "url": "http://localhost:3456/mcp"
+    }
+  }
+}
+```
+
+### 方式3: SSE 远程连接（旧客户端向后兼容）
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "type": "sse",
+      "url": "http://localhost:3456/sse"
+    }
+  }
+}
+```
+
+## CLI 命令
+
+| 命令 | 功能 |
+|------|------|
+| `szcd-mcp-setup` | 运行安装配置（同 `npm run setup`） |
+| `szcd-mcp-update-url [url]` | 更新 MCP 服务器地址并同步所有 IDE 配置 |
+| `szcd-mcp-coding-config` | 配置 CODING 平台连接信息 |
+
+## 智能体（Agent）
+
+提供 `szcd-component-expert` 智能体，帮助开发者查询组件信息、匹配需求到组件、生成基于 szcd 组件库的 React 代码。
+
+各工具自动获取对应详细度的版本：
+
+| 工具 | Agent 版本 | 特点 |
+|------|-----------|------|
+| Claude Code / Qwen | base | 基础工作流，无工具名前缀 |
+| Trae | enhanced | 增强工作流，`mcp__szcd-component-helper__` 工具名前缀 |
+| Qoder | full | 完整工作流 + MCP 工具表 + AskUserQuestion 交互 |
+
+### Agent 构建
+
+Agent 配置采用单一源模板 + 条件标记 + 构建脚本的方案：
+
+```bash
+npm run build:agents
+```
+
+修改 `agents/src/` 下的模板后运行构建，自动生成各平台适配文件。
+
+## Skill
+
+提供 `szcd-component-helper` Skill，包含 22 个 MCP 工具的使用说明。
+
+## 项目结构
+
+```
+├── agents/
+│   ├── src/                        # 源模板（唯一编辑入口）
+│   │   ├── szcd-component-expert.md
+│   │   └── tools.json
+│   ├── platforms.json              # 平台适配配置
+│   ├── build.js                    # 构建脚本
+│   ├── szcd-component-expert.md    # [生成] Claude / Qwen
+│   ├── szcd-component-expert.trae.md # [生成] Trae
+│   └── szcd-component-expert.qoder.md # [生成] Qoder
+├── commands/                       # 自定义命令
+├── skill/                          # Skill 定义
+├── qwen-extension/                 # Qwen Code 扩展包
+├── scripts/
+│   ├── postinstall.js              # 安装入口
+│   ├── update-mcp-url.js           # URL 同步工具
+│   ├── update-coding-config.js     # CODING 配置工具
+│   └── lib/                        # 各平台适配模块
+│       ├── claude-code.js
+│       ├── trae-cli.js
+│       ├── trae-ide.js
+│       ├── qoder.js
+│       ├── qwen-code.js
+│       └── opencode.js
+└── AGENTS.md                       # 项目级指令
+```
+
+## 配置文件
+
+MCP 服务器地址保存在 `~/.szcd-mcp-config.json`：
+
+```json
+{
+  "MCP_SERVER_URL": "http://localhost:3456",
+  "MCP_SERVER_NAME": "szcd-component-helper",
+  "MCP_TIMEOUT": 30000
+}
+```
+
+## License
+
+MIT

package/agents/build.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+
+/**
+ * agents/build.js — 从源模板生成多平台智能体配置文件
+ *
+ * 用法: node agents/build.js
+ *
+ * 逻辑：
+ * 1. 读取 src/ 下的主模板和 tools.json
+ * 2. 读取 platforms.json 平台配置
+ * 3. 将模板整体（含 frontmatter）按 INCLUDE/EXCLUDE 过滤
+ * 4. 替换 {{TOOL:name}} 和 {{MCP_TOOL_TABLE}} 占位符
+ * 5. 写入目标文件
+ * 6. 同步到 mcp-server/agents/ 目录
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const AGENTS_DIR = __dirname;
+const SRC_DIR = path.join(AGENTS_DIR, "src");
+
+// ==================== 工具函数 ====================
+
+/**
+ * 内容级别层级：base < enhanced < full
+ */
+const LEVEL_HIERARCHY = ["base", "enhanced", "full"];
+
+function getLevelIndex(level) {
+    const idx = LEVEL_HIERARCHY.indexOf(level);
+    if (idx === -1) throw new Error(`Unknown content level: ${level}`);
+    return idx;
+}
+
+/**
+ * 按内容级别过滤 INCLUDE/EXCLUDE 段
+ *
+ * 规则：
+ * - 无标记段：所有级别都包含
+ * - <!-- INCLUDE:X --> ... <!-- /INCLUDE:X -->: 仅 levelIndex >= X 的级别包含
+ * - <!-- EXCLUDE:X --> ... <!-- /EXCLUDE:X -->: 仅 levelIndex < X 的级别包含
+ *
+ * 同时处理 frontmatter 中的条件标记（如 <!-- EXCLUDE:enhanced -->tools: ["*"]<!-- /EXCLUDE:enhanced -->）
+ */
+function filterByContentLevel(content, contentLevel) {
+    const levelIndex = getLevelIndex(contentLevel);
+    const lines = content.split("\n");
+    const result = [];
+    let skipStack = []; // { type: 'INCLUDE'|'EXCLUDE', levelIndex }
+
+    for (const line of lines) {
+        // 检查行内标记（前后在同一行）
+        const inlineInclude = line.match(/^(.*)<!--\s*INCLUDE:(\w+)\s*-->(.*?)<!--\s*\/INCLUDE:\2\s*-->(.*)$/);
+        const inlineExclude = line.match(/^(.*)<!--\s*EXCLUDE:(\w+)\s*-->(.*?)<!--\s*\/EXCLUDE:\2\s*-->(.*)$/);
+
+        if (inlineInclude) {
+            const [, before, lvl, inner, after] = inlineInclude;
+            const lvlIdx = getLevelIndex(lvl);
+            if (levelIndex >= lvlIdx) {
+                result.push(before + inner + after);
+            } else {
+                result.push(before + after);
+            }
+            continue;
+        }
+
+        if (inlineExclude) {
+            const [, before, lvl, inner, after] = inlineExclude;
+            const lvlIdx = getLevelIndex(lvl);
+            if (levelIndex < lvlIdx) {
+                result.push(before + inner + after);
+            } else {
+                result.push(before + after);
+            }
+            continue;
+        }
+
+        // 检查块级开始标记
+        const includeStart = line.match(/<!--\s*INCLUDE:(\w+)\s*-->/);
+        const excludeStart = line.match(/<!--\s*EXCLUDE:(\w+)\s*-->/);
+        const includeEnd = line.match(/<!--\s*\/INCLUDE:(\w+)\s*-->/);
+        const excludeEnd = line.match(/<!--\s*\/EXCLUDE:(\w+)\s*-->/);
+
+        if (includeStart) {
+            const lvlIdx = getLevelIndex(includeStart[1]);
+            skipStack.push({ type: "INCLUDE", levelIndex: lvlIdx });
+            continue;
+        }
+
+        if (excludeStart) {
+            const lvlIdx = getLevelIndex(excludeStart[1]);
+            skipStack.push({ type: "EXCLUDE", levelIndex: lvlIdx });
+            continue;
+        }
+
+        if (includeEnd || excludeEnd) {
+            skipStack.pop();
+            continue;
+        }
+
+        // 判断当前行是否应该跳过
+        let shouldSkip = false;
+        for (const rule of skipStack) {
+            if (rule.type === "INCLUDE" && levelIndex < rule.levelIndex) {
+                shouldSkip = true;
+                break;
+            }
+            if (rule.type === "EXCLUDE" && levelIndex >= rule.levelIndex) {
+                shouldSkip = true;
+                break;
+            }
+        }
+
+        if (!shouldSkip) {
+            result.push(line);
+        }
+    }
+
+    return result.join("\n");
+}
+
+/**
+ * 替换 {{TOOL:name}} 占位符
+ */
+function replaceToolPlaceholders(content, toolPrefix) {
+    return content.replace(/\{\{TOOL:(\w+)\}\}/g, (_match, toolName) => {
+        return toolPrefix ? `${toolPrefix}${toolName}` : toolName;
+    });
+}
+
+/**
+ * 从 tools.json 生成 MCP 工具表格
+ * 按功能分组，同一 whenToUse 的工具合并在一行
+ */
+function generateMcpToolTable(tools, toolPrefix) {
+    const rows = [];
+    const grouped = new Map();
+
+    for (const tool of tools) {
+        const key = tool.whenToUse;
+        if (!grouped.has(key)) {
+            grouped.set(key, []);
+        }
+        grouped.get(key).push(tool);
+    }
+
+    for (const [, group] of grouped) {
+        const names = group.map((t) => {
+            const fullName = toolPrefix ? `${toolPrefix}${t.name}` : t.name;
+            return `\`${fullName}\``;
+        });
+        rows.push(`| ${names.join(" / ")} | ${group[0].description} | ${group[0].whenToUse} |`);
+    }
+
+    const header = "| 工具名 | 功能 | 何时使用 |\n|--------|------|---------|";
+    return header + "\n" + rows.join("\n");
+}
+
+/**
+ * 从 frontmatter 中移除指定字段
+ */
+function stripFrontmatterFields(content, fields) {
+    const fmMatch = content.match(/^(---\n)([\s\S]*?)(\n---)/);
+    if (!fmMatch) return content;
+
+    const prefix = fmMatch[1];
+    let fmBody = fmMatch[2];
+    const suffix = fmMatch[3];
+
+    for (const field of fields) {
+        // 匹配字段行（支持简单值、多行值、YAML列表等）
+        // 简单行：tools: ["*"]
+        // YAML列表：tools:\n  - "*"
+        const simpleLineRegex = new RegExp(`^${field}:.*$\\n?`, "m");
+        fmBody = fmBody.replace(simpleLineRegex, "");
+
+        const yamlListRegex = new RegExp(`^${field}:\\s*\\n(?:^\\s+.*$\\n?)*`, "m");
+        fmBody = fmBody.replace(yamlListRegex, "");
+    }
+
+    // 清理空行
+    fmBody = fmBody.replace(/\n{2,}/g, "\n");
+
+    return prefix + fmBody + suffix + content.slice(fmMatch[0].length);
+}
+
+/**
+ * 清理输出内容中的多余空行和残留空行
+ */
+function cleanupContent(content) {
+    // 移除连续3个以上空行 → 2个空行
+    let result = content.replace(/\n{4,}/g, "\n\n\n");
+    // 移除 frontmatter 后多余空行（--- 后最多1个空行）
+    result = result.replace(/(---\n)\n{2,}/g, "$1\n");
+    return result;
+}
+
+// ==================== 主构建逻辑 ====================
+
+function build() {
+    console.log("🔧 Building agent configurations...\n");
+
+    // 1. 读取源文件
+    const templatePath = path.join(SRC_DIR, "szcd-component-expert.md");
+    const toolsPath = path.join(SRC_DIR, "tools.json");
+    const platformsPath = path.join(AGENTS_DIR, "platforms.json");
+
+    const templateContent = fs.readFileSync(templatePath, "utf8");
+    const tools = JSON.parse(fs.readFileSync(toolsPath, "utf8"));
+    const platformsConfig = JSON.parse(fs.readFileSync(platformsPath, "utf8"));
+
+    // 2. 按平台生成
+    for (const [platformName, platformConfig] of Object.entries(platformsConfig.platforms)) {
+        console.log(`  Generating for ${platformName} (level: ${platformConfig.contentLevel})...`);
+
+        // 对整个模板内容（含 frontmatter）进行条件过滤
+        let filtered = filterByContentLevel(templateContent, platformConfig.contentLevel);
+
+        // 剥离 frontmatter 中指定字段（如 Qwen 不需要 tools/model/type）
+        if (platformConfig.stripFrontmatterFields && platformConfig.stripFrontmatterFields.length > 0) {
+            filtered = stripFrontmatterFields(filtered, platformConfig.stripFrontmatterFields);
+        }
+
+        // 替换 {{TOOL:}} 占位符
+        filtered = replaceToolPlaceholders(filtered, platformConfig.toolPrefix);
+
+        // 替换 {{MCP_TOOL_TABLE}}
+        if (filtered.includes("{{MCP_TOOL_TABLE}}")) {
+            const table = generateMcpToolTable(tools, platformConfig.toolPrefix);
+            filtered = filtered.replace("{{MCP_TOOL_TABLE}}", table);
+        }
+
+        // 清理
+        const output = cleanupContent(filtered);
+
+        // 确定输出路径
+        const outputDir = platformConfig.outputDir
+            ? path.join(AGENTS_DIR, platformConfig.outputDir)
+            : AGENTS_DIR;
+        const outputPath = path.join(outputDir, platformConfig.outputFile);
+
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+
+        fs.writeFileSync(outputPath, output);
+        console.log(`    ✓ Written: ${path.relative(AGENTS_DIR, outputPath)}`);
+    }
+
+    // 3. 同步到 mcp-server/agents/（同级 mcp/szcd-mcp-server 目录）
+    const mcpServerAgentsDir = path.join(AGENTS_DIR, "..", "..", "szcd-mcp-server", "agents");
+    if (fs.existsSync(path.dirname(mcpServerAgentsDir))) {
+        if (!fs.existsSync(mcpServerAgentsDir)) {
+            fs.mkdirSync(mcpServerAgentsDir, { recursive: true });
+        }
+
+        const outputFiles = [
+            "szcd-component-expert.md",
+            "szcd-component-expert.trae.md",
+            "szcd-component-expert.qoder.md",
+        ];
+        for (const file of outputFiles) {
+            const src = path.join(AGENTS_DIR, file);
+            const dest = path.join(mcpServerAgentsDir, file);
+            if (fs.existsSync(src)) {
+                fs.copyFileSync(src, dest);
+                console.log(`    ✓ Synced to mcp-server: ${file}`);
+            }
+        }
+    }
+
+    // 4. 同步到 qwen-extension/agents/（供 Qwen Code 扩展安装使用）
+    const qwenExtDir = path.join(AGENTS_DIR, "..", "qwen-extension");
+    const qwenGeneratedAgent = path.join(AGENTS_DIR, "qwen-extension", "agents", "szcd-component-expert.md");
+    if (fs.existsSync(qwenGeneratedAgent)) {
+        const qwenExtAgentsDir = path.join(qwenExtDir, "agents");
+        if (!fs.existsSync(qwenExtAgentsDir)) {
+            fs.mkdirSync(qwenExtAgentsDir, { recursive: true });
+        }
+        fs.copyFileSync(qwenGeneratedAgent, path.join(qwenExtAgentsDir, "szcd-component-expert.md"));
+        console.log(`    ✓ Synced to qwen-extension/agents/`);
+    }
+
+    // 5. 同步 SKILL.md 和 commands 到 qwen-extension/
+    const packageRoot = path.join(AGENTS_DIR, "..");
+
+    // 同步 SKILL.md
+    const skillSource = path.join(packageRoot, "skill", "SKILL.md");
+    const skillDest = path.join(qwenExtDir, "skills", "szcd-component-helper", "SKILL.md");
+    if (fs.existsSync(skillSource)) {
+        if (!fs.existsSync(path.dirname(skillDest))) {
+            fs.mkdirSync(path.dirname(skillDest), { recursive: true });
+        }
+        fs.copyFileSync(skillSource, skillDest);
+        console.log(`    ✓ Synced to qwen-extension/skills/`);
+    }
+
+    // 同步 commands
+    const commandsSourceDir = path.join(packageRoot, "commands");
+    const commandsDestDir = path.join(qwenExtDir, "commands");
+    if (fs.existsSync(commandsSourceDir)) {
+        if (!fs.existsSync(commandsDestDir)) {
+            fs.mkdirSync(commandsDestDir, { recursive: true });
+        }
+        const cmdFiles = fs.readdirSync(commandsSourceDir).filter((f) => f.endsWith(".md"));
+        for (const cmdFile of cmdFiles) {
+            fs.copyFileSync(
+                path.join(commandsSourceDir, cmdFile),
+                path.join(commandsDestDir, cmdFile),
+            );
+        }
+        if (cmdFiles.length > 0) {
+            console.log(`    ✓ Synced ${cmdFiles.length} command(s) to qwen-extension/commands/`);
+        }
+    }
+
+    console.log("\n✅ Agent build complete!");
+}
+
+try {
+    build();
+} catch (error) {
+    console.error("❌ Build failed:", error.message);
+    console.error(error.stack);
+    process.exit(1);
+}

package/agents/platforms.json

@@ -0,0 +1,47 @@
+{
+    "mcpServerName": "szcd-component-helper",
+    "platforms": {
+        "claude": {
+            "outputFile": "szcd-component-expert.md",
+            "contentLevel": "base",
+            "frontmatter": {
+                "name": "{{name}}",
+                "description": "{{description}}",
+                "tools": "[\"*\"]",
+                "model": "sonnet",
+                "type": "agent"
+            },
+            "toolPrefix": ""
+        },
+        "trae": {
+            "outputFile": "szcd-component-expert.trae.md",
+            "contentLevel": "enhanced",
+            "frontmatter": {
+                "name": "{{name}}",
+                "tools": "- \"*\"",
+                "description": "{{description}}"
+            },
+            "toolPrefix": "mcp__szcd-component-helper__"
+        },
+        "qoder": {
+            "outputFile": "szcd-component-expert.qoder.md",
+            "contentLevel": "full",
+            "frontmatter": {
+                "name": "{{name}}",
+                "description": "{{description}}"
+            },
+            "toolPrefix": ""
+        },
+        "qwen": {
+            "outputFile": "szcd-component-expert.md",
+            "outputDir": "qwen-extension/agents",
+            "contentLevel": "base",
+            "frontmatter": {
+                "name": "{{name}}",
+                "description": "{{description}}"
+            },
+            "stripFrontmatterFields": ["tools", "model", "type"],
+            "toolPrefix": ""
+        }
+    }
+}

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

@@ -0,0 +1,165 @@
+---
+name: szcd-component-expert
+description: |
+    szcd 组件库专家，用于查询组件信息、匹配需求到组件、生成基于 szcd 组件库的 React 代码。
+    当用户需要使用 @szc-ft/szcd 组件库开发页面、选择组件、查询组件 API、根据设计稿生成代码时，应使用此 agent。
+    典型触发场景：
+    - 用户想查询 szcd 组件库中有哪些组件
+    - 用户想获取某个组件的 Props 和使用示例
+    - 用户提供了设计稿截图/描述，要求生成页面代码
+    - 用户描述页面需求（如"做一个左侧树+右侧表格的页面"），要求生成代码
+    - 用户提到"根据设计稿生成页面"、"设计稿转代码"、"需求转组件"等关键词
+
+---
+
+# szcd-component-expert: szcd 组件库专家
+
+## 角色定位
+
+你是 szcd 组件库（@szc-ft/szcd）的专家助手。你的职责是帮助开发者快速找到合适的组件并生成可直接使用的代码。
+
+szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层架构：
+
+| 层级 | 路径 | 说明 |
+|------|------|------|
+| Cover 层 | src/components/cover/ | 对 antd 组件的样式和交互定制 |
+| Wrapper 层 | src/components/wrappers/ | 封装业务逻辑的包装组件 |
+| 复合组件 | src/other/components/ | 11 个高级业务组件（Query/LeftTree/TableOrList 等） |
+| ProPackages | pro-packages/ | ProComponents 封装 |
+| 模板组件 | mode-packages/ | 页面级模板（LeftTree+Query+Table 等） |
+
+**关键原则**: 能用复合组件就用复合组件，能用 Wrapper 就不用 Cover，能用 Cover 就不直接用 Ant Design。
+
+
+## 完整工作流程（页面生成类任务）
+
+### 步骤1：架构认知 + 工具自检（必做）
+
+**在正式开始之前，获取项目架构全局视图，同时验证 MCP 连接。**
+
+执行动作：
+1. 调用 `get_architecture_overview`（detail="summary"）获取7层架构图、模板组合模式、推荐使用顺序和 LLM 映射错误提示
+2. 如果连接失败，**立即停止并返回错误信息**，告知用户需要先配置 MCP 服务器
+3. 如果成功，根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板
+
+- 如果仍失败，说明当前环境没有配置 szcd-component-helper MCP 服务器，请直接告知用户需要先配置 MCP 服务器
+- **不要假设工具一定存在，务必先验证再使用**
+
+
+### 步骤2：理解需求（必做）
+
+分析用户要实现的页面或功能，梳理以下维度：
+
+1. **页面布局类型**: 左右布局 / 上下布局 / 表单页 / 详情页
+2. **查询条件**: 有哪些搜索字段，每个字段的类型
+3. **操作按钮**: 新增/编辑/删除/批量操作等
+4. **表格列**: 列名、数据类型、是否可排序/筛选
+5. **左侧树**: 是否需要，树的数据来源
+6. **弹窗/抽屉**: 新增/编辑用的弹窗或抽屉
+
+**交互节点**：如果用户描述的信息不够明确，**必须主动向用户追问**缺失的关键信息，不要自行假设：
+- 信息不足时，列出需要确认的问题，逐项向用户提问
+- 布局类型不明确时，询问"页面是左右布局还是上下布局？"并提供选项
+- 查询字段不完整时，询问"还需要哪些搜索条件？"
+- 缺少交互细节时，询问"编辑操作用弹窗还是抽屉？"并提供选项
+
+
+### 步骤3：分析设计稿（条件执行）
+
+当用户提供了设计稿图片时：
+- 如果**主代理已提供图片描述**（设计稿已被解读为文字），直接使用该描述，跳过此步
+- 如果图片未被解读，调用 `analyze_design_image` 工具分析
+- 如果该工具不可用，告知用户需要提供设计稿的文字描述
+
+- 注意：OCR 降级模式下仅返回原始文字，需结合组件库工具自行映射
+
+
+### 步骤4：查询组件 + 依赖验证（必做）
+
+**这一步是核心，必须实际调用 MCP 工具查询，禁止凭记忆猜测 API。**
+
+使用 MCP 工具获取组件信息和 API：
+
+- `get_component_library_overview` — 获取全部组件概览（含功能描述和适用场景）
+- `search_all_components` — 按关键词搜索组件
+- `get_other_component` / `get_cover_component` — 获取组件详情和 Props
+- `get_accurate_component_doc` — 获取复合组件的透传机制
+- `search_component_examples` — 搜索组件使用示例
+- `read_file` — 读取组件源码（必要时）
+
+**映射规则**:
+- 页面布局 → `TemplateMode`
+- 查询表单 → `Query`（通过 config 配置字段）
+- 数据表格 → `TableOrList`
+- 左侧树 → `LeftTree`
+- 弹窗/抽屉 → `ModelOrDrawer`
+- 返回标题 → `TitleAndBack`
+- 按钮 → Cover 层 `Button`
+- 输入框 → Cover 层 `Input` 或 Query 的 valueType: 'input'
+- 下拉选择 → Cover 层 `Select` 或 Query 的 valueType: 'select'
+- 日期选择 → Cover 层 `DatePicker` 或 Query 的 valueType: 'datePicker'
+- 树选择 → Query 的 valueType: 'treeSelect'
+
+
+### 步骤5：匹配组件并确认方案（必做）
+
+根据需求描述和组件的 useCases/description 匹配最合适的组件，形成组件方案。
+
+**交互节点**：向用户展示匹配结果，**必须确认方案后再生成代码**：
+- 列出选用的组件及理由、页面布局结构、备选方案
+- 询问用户是否同意此方案，或有调整需求
+
+
+### 步骤6：生成代码（必做）
+
+产出可直接运行的 React 代码，遵循项目规范：
+
+- 使用 React 18 + TypeScript
+- 从 `@szc-ft/szcd` 导入组件
+- 遵循 antd 5.27 的 API 用法
+- 4 空格缩进，双引号，末尾逗号
+- ProTable/ProForm 等使用 valueType 配置列/字段类型
+- 复合组件配合 TemplateMode 使用实现标准页面布局
+
+**交互节点**：代码生成后，主动询问用户是否需要调整：
+- "代码已生成，是否需要调整样式或交互细节？"
+- "是否需要补充表单校验规则？"
+- "是否需要添加批量操作功能？"
+
+## 典型页面模式
+
+### 模式1: 左右布局 + 查询 + 表格（最常见）
+```
+TemplateMode(templateTpye="LeftRight")
+  ├── LeftContent: LeftTree 组件
+  ├── Query: Query 组件 + 操作按钮
+  └── PageContent: TableOrList 组件
+```
+
+### 模式2: 上下布局 + 查询 + 表格
+```
+TemplateMode(templateTpye="TopBottom")
+  ├── Query: Query 组件 + 操作按钮
+  └── PageContent: TableOrList 组件
+```
+
+### 模式3: 纯表格页
+```
+TemplateMode(templateTpye="TopBottom")
+  └── PageContent: TableOrList 组件
+```
+
+### 模式4: 表单页
+```
+ProForm / ProFormWrapper
+```
+
+## 关键复合组件速查
+
+- **Query**: 查询面板，支持 antd type 和 Pro valueType 双模式
+- **TableOrList**: 内容区，7种模式（ProTable/EditableProTable/DragSortTable/ProList 等）
+- **LeftTree**: 左侧树，内置数据请求和搜索
+- **FormItemOrDetailItem**: 表单/详情项动态渲染
+- **ModelOrDrawer**: 弹窗/抽屉交互层
+- **TemplateMode**: 模板容器，预设 LeftRight/UpDown/TreeQueryTable 等布局
+