@szc-ft/mcp-szcd-client 0.13.0 → 0.13.2

package/standard-skill/szcd-component-helper/SKILL.md

@@ -0,0 +1,439 @@
+---
+name: szcd-component-helper
+description: 帮助用户查询和了解 szcd 项目中的组件信息，包括 Cover 层组件、Wrapper 层组件、Ant Design 组件、ProComponents、ProPackages 以及复合组件。支持组件搜索、详情查询、使用示例搜索、设计稿分析、API 联调和文件读取。当用户需要了解 szcd 项目的组件结构、查看组件实现、寻找组件使用示例、根据设计稿生成代码时，应使用此技能。它是一个前端组件库，全名"@szc-ft/szcd"。这是一个客户端 skill，通过 MCP 协议（SSE 或 HTTP）连接到远程 MCP 服务器。
+compatibility:
+  tools:
+    - web_search
+    - web_fetch
+    - run_command
+    - read
+    - write
+
+---
+
+# szcd 组件助手技能（客户端）
+
+## 概述
+
+此技能提供对 szcd 项目组件的查询和分析能力，帮助用户快速了解项目中的组件结构、实现细节、使用示例、设计稿还原和后端 API 联调。
+
+**重要说明**：这是一个客户端 skill，通过 MCP 协议（SSE 或 HTTP）连接到远程 MCP 服务器。服务器由管理员维护，包含源码和数据。
+
+**版本**：v0.13.0 - MCP 服务器架构重构，工具精简至13个；新增语义搜索、一站式组件画像、最佳实践、反馈收集等工具；Swagger/YApi 统一为 api_tool；CODING Issue 支持URL自动解析
+
+## 架构说明
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    连接方式（三选一）                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  方式1: 本地直连 (stdio) — 推荐                              │
+│  ┌─────────────┐     stdio      ┌─────────────────────────┐│
+│  │   IDE/AI    │ ◄─────────────►│  szcd-mcp-server        ││
+│  │   Client    │                │  (本地运行)              ││
+│  └─────────────┘                └─────────────────────────┘│
+│                                                             │
+│  方式2: Streamable HTTP 远程连接 — 推荐                      │
+│  ┌─────────────┐    HTTP      ┌─────────────────────────┐ │
+│  │   IDE/AI    │ ◄───────────►│  MCP Server (HTTP 模式) │ │
+│  │   Client    │  POST /mcp   │  管理员机器              │ │
+│  │             │              │  (源码 + 数据)           │ │
+│  └─────────────┘              └─────────────────────────┘ │
+│                                                             │
+│  方式2b: SSE 远程连接（旧客户端向后兼容）                      │
+│  ┌─────────────┐     SSE       ┌─────────────────────────┐│
+│  │   IDE/AI    │ ◄────────────►│  MCP Server (SSE 模式)  ││
+│  │   Client    │  GET /sse     │  管理员机器              ││
+│  │             │  POST /message│  (源码 + 数据)           ││
+│  └─────────────┘               └─────────────────────────┘│
+│                                                             │
+│  方式3: 代理桥接 (向后兼容)                                   │
+│  ┌─────────────┐  stdio  ┌───────────┐  SSE/HTTP  ┌─────┐│
+│  │   IDE/AI    │◄───────►│mcp-proxy  │◄──────────►│Server││
+│  │   Client    │         │(桥接代理)  │            │     ││
+│  └─────────────┘         └───────────┘            └─────┘│
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 推荐工作流（页面生成类任务）
+
+AI 助手在处理页面生成需求时，必须按以下流程使用工具：
+
+### 步骤1：架构认知 + 需求理解
+- 调用 `get_architecture_overview(detail="summary")` 获取 7 层架构和模板组合模式
+- 分析用户需求的页面布局类型、查询字段、操作按钮、表格列等
+
+### 步骤2：组件发现（优先语义搜索）
+- 使用 `search_components_semantic(query="...", scope="all")` 进行语义搜索，比关键词匹配更精准
+- 例如："查询表单" → Query，"左树右表" → LeftTree + TableOrList + TemplateMode
+
+### 步骤3：一站式组件查询（替代多次调用）
+- 使用 `get_component_full_profile(name, depth="deep")` 一次性获取：
+  - `name` 支持逗号分隔批量查询（如 `"Query,TableOrList"`）
+  - 基本信息 + Props（优先 mode-packages 文档）+ 透传机制
+  - 源码摘要（关键函数、架构、导航图）+ Props 链深度解析
+  - 依赖关系 + 使用示例 + 最佳实践 + 样式注入信息
+  - **返回值是紧凑 Markdown 格式，直接阅读即可**
+- 如需样式注入细节，额外调用 `get_style_injection_guide`
+- 如需组合最佳实践，额外调用 `get_best_practices(scenario="...")`
+
+### 步骤4：设计稿分析（如有）
+- 使用 `analyze_design_image` 分析设计稿，建议 `outputFormat="restoration_code"` 直接输出还原代码
+- 使用 `get_style_injection_guide` 处理 CSS 分配
+
+### 步骤5：代码生成 + 样式注入
+- 生成代码时包含 ModeStyle / ConfigProvider 配置
+- 参考 `get_best_practices(scenario="...")` 获取场景组合最佳实践
+
+### 步骤6：收集用户反馈（质量闭环）
+- **必须**在代码输出后主动询问用户满意度
+- 若用户表示不准确或不采纳，收集原因
+- 调用 `submit_feedback` 将反馈提交到服务器
+
+## 可用工具（13个）
+
+### 复合组件工具
+
+#### 1. read_file
+**功能**：读取仓库内文件（相对路径），支持路径自动纠错（node_modules → src、扩展名纠正、目录补全）。
+**参数**：
+- `path` (string, required): 文件相对路径
+- `maxChars` (number, optional, default: 20000): 最大字符数 200-200000
+
+### Cover 层组件工具
+
+### Ant Design 组件工具
+
+#### 2. get_antd_component
+**功能**：获取 Ant Design 组件的详细信息，包括中文名、描述、API 文档链接和 Props 列表。
+**参数**：
+- `name` (string, required): 组件名称
+
+### ProComponents 组件工具
+
+#### 3. get_pro_component
+**功能**：获取 ProComponents 组件的详细信息，包括特性说明、API 文档和 Props 列表。
+**参数**：
+- `name` (string, required): 组件名称
+
+### 全局搜索与架构工具
+
+#### 4. get_architecture_overview
+**功能**：查看 7 层架构（AntD→Cover→Wrapper→ProPackage→复合组件→模板）、层级关系和推荐使用顺序。含 LLM 映射修正提示。
+**参数**：
+- `detail` (enum, optional, default: "summary"): summary=层级概览+模板模式+LLM提示；full=含所有层组件列表详情
+
+### Props 深度解析工具
+
+### 设计稿分析工具
+
+#### 5. analyze_design_image
+**功能**：分析 UI 设计稿图片，提取 Token 配置、CSS 覆盖样式、视觉细节。支持 base64/URL/文件路径，pixel_perfect 模式最高还原度。
+**参数**：
+- `imageSource` (string, required): 图片数据（base64/URL/文件路径）
+- `sourceType` (enum, optional, default: "file_path"): base64/url/file_path
+- `analysisType` (enum, optional, default: "full"): layout/components/tokens/full/pixel_perfect
+- `pageContext` (string, optional): 页面业务上下文
+- `targetLibrary` (enum, optional, default: "auto"): szcd/antd/pro-components/auto
+- `outputFormat` (enum, optional, default: "markdown"): markdown/json/structured_text/restoration_code
+
+**重要提示**：远程 SSE/HTTP 连接时优先使用 base64；本地 stdio 可用 file_path。
+
+### 样式注入指南工具
+
+#### 6. get_style_injection_guide
+**功能**：查询复合组件的样式注入方法：可用样式 props、注入方式、代码示例、嵌套 CSS 穿透路径和智能分配策略。
+**参数**：
+- `componentNames` (string[], optional): 组件名列表
+- `includeNesting` (boolean, optional, default: true): 是否包含嵌套注入指南
+- `includeSmartDistribute` (boolean, optional, default: false): 是否包含智能 CSS 分配
+- `cssOverrides` (array, optional): CSS 覆盖列表（用于智能分配）
+- `includeDeepStyleKnowledge` (enum, optional, default: "off"): off/summary/full/examples
+- `outputFormat` (enum, optional, default: "markdown"): markdown/json/text
+
+### Swagger 联调工具
+
+### CODING Issue 工具
+
+#### 7. coding_fetch_issue
+**功能**：获取 CODING Issue 详情。支持直接粘贴 Issue URL 自动解析，也支持 Cookie（推荐）或账号密码认证。支持从配置文件读取默认参数。
+**参数**：
+- `url` (string, optional): 完整 Issue URL，如 http://xxx/p/p-nkdq3ke/all/issues/46269。提供后自动解析 projectName 和 issueCode
+- `issueCode` (string, optional): Issue 编号，如 6249
+- `baseUrl` (string, optional): CODING 基础地址（可从配置文件读取）
+- `projectId` (string, optional): 项目 ID（可从配置文件读取）
+- `projectName` (string, optional): 项目名（如 p-nkdq3ke），提供后自动解析为 projectId
+- `cookies` (string, optional): 浏览器 Cookie 字符串
+- `account` (string, optional): CODING 账号
+- `password` (string, optional): CODING 密码
+- `withDescriptionMarkup` (boolean, optional, default: true): 是否返回富文本格式
+
+#### 8. coding_config
+**功能**：查看/设置 CODING 默认配置（baseUrl/projectId/账号/Cookie）。
+**参数**：
+- `action` (enum, optional, default: "get"): get/set/clear
+- `baseUrl`, `projectId`, `account`, `cookies`, `password` (optional, set 时生效)
+
+### API 工具
+
+#### 9. api_tool
+**功能**：统一 API 工具，自动识别 YApi/Swagger 拉取 API 文档、联调测试、配置管理。
+**参数**：
+- `action` (enum, required): fetch=拉取API文档, test=联调测试, config=配置管理
+- `url` (string, optional): API文档地址（fetch时）/ 请求地址（test时）
+- `method` (enum, optional, default: "GET"): GET/POST/PUT/DELETE/PATCH（test时）
+- `data` (object, optional, default: {}): 请求参数（test时）
+- `headers` (object, optional, default: {}): 请求头（test时）
+- `username` / `password` / `account` / `cookies` (string, optional): 鉴权信息
+- `yapiBaseUrl` / `yapiAccount` / `yapiPassword` / `yapiCookies` (string, optional): YApi 配置（config set 时生效）
+
+### Repowiki 增强工具（推荐优先使用）
+
+#### 10. get_component_full_profile
+**功能**：一站式获取组件完整画像：基本信息、Props（优先 mode-packages 文档）、源码摘要、示例、最佳实践、依赖、样式注入。支持逗号分隔批量查询，返回值是紧凑 Markdown 格式。
+**参数**：
+- `name` (string, required): 组件名称，支持逗号分隔批量查询（如 `"Query,TableOrList"`）
+- `depth` (enum, optional, default: "standard"): quick=基本信息+核心Props；standard=完整画像；deep=含Props链解析+源码摘要
+
+**推荐使用场景**：替代多次单独查询，一次获取组件的全部信息。
+
+#### 11. search_components_semantic
+**功能**：语义搜索组件，支持中文关键词和场景描述。如"查询表单"→Query，"树形导航"→LeftTree。
+**参数**：
+- `query` (string, required): 自然语言查询
+- `scope` (enum, optional, default: "all"): all/template/cover/wrapper/pro/chart
+- `maxResults` (number, optional, default: 10): 最大结果数 1-30
+
+**推荐使用场景**：组件初筛首选，语义匹配比关键词搜索更精准。
+
+#### 12. get_best_practices
+**功能**：获取组件使用最佳实践和常见错误修正。指定 scenario 可获取组合最佳实践。
+**参数**：
+- `componentName` (string, optional): 组件名称
+- `scenario` (string, optional): 场景描述，如"左树右表页面"
+
+### 反馈收集工具
+
+#### 13. submit_feedback
+**功能**：提交用户对本次 AI 生成结果的反馈。AI 助手在生成代码后应主动询问用户满意度，若用户表示不准确或不采纳，则收集原因并通过此工具提交到服务器，用于持续优化 MCP 工具质量。
+**参数**：
+- `sessionId` (string, required): 会话 ID
+- `toolsUsed` (string[], optional): 本次使用的工具列表
+- `userQuery` (string, optional): 用户原始需求
+- `generatedCodeSummary` (string, optional): 生成代码摘要
+- `accuracyRating` (number, optional): 准确性评分 1-5
+- `adopted` (boolean, required): 是否采纳
+- `rejectionReason` (string, optional): 未采纳原因
+- `contextSnapshot` (object, optional): 额外上下文
+- `toolType` (string, optional): IDE 类型 trae/claude/qwen/cursor/vscode/generic
+
+## 工具使用优先级
+
+| 优先级 | 工具 | 用途 |
+|--------|------|------|
+| P0 | `get_architecture_overview` | 首次使用时获取架构全局视图 |
+| P0 | `search_components_semantic` | 语义搜索，比关键词搜索更精准 |
+| P0 | `get_component_full_profile` | 一站式查询，支持批量，返回 Markdown |
+| P1 | `get_best_practices` | 获取场景组合最佳实践 |
+| P1 | `analyze_design_image` | 设计稿分析 |
+| P1 | `get_style_injection_guide` | 样式注入配置 |
+| P2 | `api_tool` | API 文档拉取 / 联调测试（YApi/Swagger） |
+| P2 | `read_file` | 读取源码文件确认行为 |
+| P2 | `get_antd_component` / `get_pro_component` | 底层组件详情 |
+| P3 | `coding_fetch_issue` / `coding_config` | 需求追踪 / 配置管理 |
+| - | `submit_feedback` | **代码生成后必做：收集反馈** |
+
+## 旧工具迁移映射
+
+| 已移除的旧工具 | 替代方案 |
+|---|---|
+| `list_other_components` | `search_components_semantic` 或 `get_component_full_profile` |
+| `get_other_component` | `get_component_full_profile` |
+| `search_component_examples` | `get_component_full_profile`（含示例） |
+| `list_cover_components` | `search_components_semantic(scope="cover")` |
+| `get_cover_component` | `get_component_full_profile` |
+| `list_wrapper_components` | `search_components_semantic(scope="wrapper")` |
+| `list_pro_package_components` | `search_components_semantic(scope="pro")` |
+| `list_antd_components` / `list_antd_components_by_category` | `search_components_semantic` |
+| `list_pro_components` / `list_pro_components_by_category` | `search_components_semantic` |
+| `search_all_components` | `search_components_semantic` |
+| `get_component_library_overview` | `get_architecture_overview` |
+| `get_accurate_component_doc` | `get_component_full_profile(depth="deep")` |
+| `resolve_props_chain` | `get_component_full_profile(depth="deep")` |
+| `get_component_dependencies` | `get_component_full_profile`（含依赖） |
+| `swagger_fetch_apis` / `swagger_test_api` | `api_tool(action="fetch")` / `api_tool(action="test")` |
+| `refresh_component_docs` / `regenerate_accurate_docs` | 已移除（管理操作转 REST API） |
+
+## 安装方式
+
+### 通过 npm 安装
+
+```bash
+npm install @szc-ft/mcp-szcd-component-helper
+```
+
+安装后会自动：
+- 安装 MCP 代理脚本
+- 自动配置 skill 到 `~/.trae-cn/skills/szcd-component-helper/`
+- 创建配置文件模板 `~/.szcd-mcp-config.json`
+
+## 配置步骤
+
+### 步骤1：安装客户端包
+
+```bash
+npm install @szc-ft/mcp-szcd-component-helper
+```
+
+### 步骤2：配置服务器地址
+
+编辑配置文件 `~/.szcd-mcp-config.json`：
+
+```json
+{
+  "MCP_SERVER_URL": "http://localhost:3456",
+  "MCP_TIMEOUT": 30000,
+  "MCP_API_KEY": ""
+}
+```
+
+### 步骤3：在 IDE 配置中设置
+
+**Trae CLI Streamable HTTP 直连（推荐）**
+
+在 `~/.trae/trae_cli.yaml` 中配置：
+
+```yaml
+mcp_servers:
+    - name: szcd-component-helper
+      url: http://localhost:3456/mcp
+      type: http
+```
+
+**本地直连 stdio（推荐，无需远程服务器）**
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "command": "npx",
+      "args": ["szcd-mcp-server", "--stdio"]
+    }
+  }
+}
+```
+
+**Qwen Code / Qoder CLI Streamable HTTP 直连（推荐）**
+
+在 `~/.qwen/settings.json` 中配置：
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "httpUrl": "http://localhost:3456/mcp",
+      "timeout": 30000
+    }
+  }
+}
+```
+
+**Qwen Code / Qoder CLI 本地直连 stdio（推荐，无需远程服务器）**
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "command": "npx",
+      "args": ["szcd-mcp-server", "--stdio"]
+    }
+  }
+}
+```
+
+**Claude Code 配置**
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "command": "npx",
+      "args": ["szcd-mcp-server", "--stdio"]
+    }
+  }
+}
+```
+
+### 步骤4：验证配置
+
+```bash
+curl http://localhost:3456/health
+npx szcd-mcp-proxy --test
+```
+
+## 反馈收集（质量闭环）
+
+### 触发时机
+
+当 AI 助手完成以下任一任务后，**必须**主动询问用户反馈：
+- 生成了基于 szcd 组件库的页面代码
+- 推荐了组件方案并生成代码
+- 根据设计稿分析结果生成还原代码
+
+### 反馈问题
+
+AI 助手应在代码输出后询问：
+
+1. "代码是否准确满足您的需求？（1-5分）"
+2. "您是否计划采纳这段代码？"
+3. 如果用户表示不准确或不采纳：
+   - "请问哪里不准确？是组件选择、Props 用法、还是布局结构？"
+   - "请描述您的预期，以便我改进。"
+
+### 提交反馈
+
+收集到用户反馈后，AI 助手应调用 `submit_feedback` MCP 工具将反馈提交到服务器：
+
+```json
+{
+  "sessionId": "<当前会话ID或生成UUID>",
+  "toolsUsed": ["search_components_semantic", "get_component_full_profile", "get_best_practices"],
+  "userQuery": "用户原始需求",
+  "generatedCodeSummary": "生成代码的首行/核心结构摘要",
+  "accuracyRating": 3,
+  "adopted": false,
+  "rejectionReason": "用户描述的不准确之处",
+  "contextSnapshot": {
+    "selectedComponents": ["Query", "TableOrList"],
+    "templateType": "LeftRight"
+  },
+  "toolType": "trae"
+}
+```
+
+### 提交时机
+
+- 用户明确表示不采纳 → 立即提交
+- 用户给出修改意见 → 先修改代码，若仍不采纳则提交
+- 用户未回复反馈问题 → 在对话结束时自动提交（adopted 建议设为 false，rejectionReason 为"用户未反馈"）
+
+## 注意事项
+
+- 所有路径都是相对于项目根目录的相对路径
+- **优先使用语义搜索 `search_components_semantic` 和一站式查询 `get_component_full_profile`**，减少工具调用次数
+- `get_component_library_overview`、`list_other_components`、`search_all_components` 等旧工具已移除，请使用 `get_architecture_overview` 和 `search_components_semantic` 替代
+- **需要确保 MCP 服务器正在运行，否则无法查询数据**
+- **设计稿分析功能需要配置视觉模型 API Key**，未配置时 analyze_design_image 工具会返回错误
+- **反馈收集是可选但强烈建议的功能**，有助于持续优化 MCP 工具质量
+
+## 故障排除
+
+### 连接失败
+
+1. 检查服务器是否运行：`curl ${MCP_SERVER_URL}/health`
+2. 检查防火墙设置
+3. 检查网络连接
+4. 确认 `MCP_SERVER_URL` 配置正确
+5. 检查环境变量是否正确设置
+6. 检查配置文件 `~/.szcd-mcp-config.json` 是否存在