@szc-ft/mcp-szcd-client 0.11.0

package/standard-skill/SKILL.md

@@ -0,0 +1,1509 @@
+---
+name: szcd-component-helper
+description: 帮助用户查询和了解 szcd 项目中的组件信息，包括 Cover 层组件、Wrapper 层组件、Ant Design 组件、ProComponents、ProPackages 以及复合组件。支持组件搜索、详情查询、使用示例搜索和文件读取。当用户需要了解 szcd 项目的组件结构、查看组件实现、寻找组件使用示例时，应使用此技能。它是一个前端组件库，全名"@szc-ft/szcd"。这是一个客户端 skill，通过 MCP 协议（SSE 或 HTTP）连接到远程 MCP 服务器。
+compatibility:
+  tools:
+    - web_search
+    - web_fetch
+    - run_command
+    - read
+    - write
+
+---
+
+# szcd 组件助手技能（客户端）
+
+## 概述
+
+此技能提供对 szcd 项目组件的查询和分析能力，帮助用户快速了解项目中的组件结构、实现细节和使用示例。
+
+**重要说明**：这是一个客户端 skill，通过 MCP 协议（SSE 或 HTTP）连接到远程 MCP 服务器。服务器由管理员维护，包含源码和数据。
+
+**版本**：v0.8.0 - 统一版本发布，包含 0.6.x 和 0.7.x 全部功能；新增设计稿图片分析工具（视觉代理/兜底方案），支持 OCR 降级和优先级控制；新增 .traecli agents 目录兼容
+
+## 架构说明
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    连接方式（三选一）                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  方式1: 本地直连 (stdio) — 推荐                              │
+│  ┌─────────────┐     stdio      ┌─────────────────────────┐│
+│  │   IDE/AI    │ ◄─────────────►│  szcd-mcp-server        ││
+│  │   Client    │                │  (本地运行)              ││
+│  └─────────────┘                └─────────────────────────┘│
+│                                                             │
+│  方式2: SSE 远程连接 — 推荐                                   │
+│  ┌─────────────┐     SSE       ┌─────────────────────────┐│
+│  │   IDE/AI    │ ◄────────────►│  MCP Server (SSE 模式)  ││
+│  │   Client    │  GET /sse     │  管理员机器              ││
+│  │             │  POST /message│  (源码 + 数据)           ││
+│  └─────────────┘               └─────────────────────────┘│
+│                                                             │
+│  方式2b: Streamable HTTP 远程连接（Trae CLI 兼容）           │
+│  ┌─────────────┐    HTTP      ┌─────────────────────────┐ │
+│  │   IDE/AI    │ ◄───────────►│  MCP Server (HTTP 模式) │ │
+│  │   Client    │  POST /mcp   │  管理员机器              │ │
+│  │             │              │  (源码 + 数据)           │ │
+│  └─────────────┘              └─────────────────────────┘ │
+│                                                             │
+│  方式3: 代理桥接 (向后兼容)                                   │
+│  ┌─────────────┐  stdio  ┌───────────┐  SSE/HTTP  ┌─────┐│
+│  │   IDE/AI    │◄───────►│mcp-proxy  │◄──────────►│Server││
+│  │   Client    │         │(桥接代理)  │            │     ││
+│  └─────────────┘         └───────────┘            └─────┘│
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 可用工具
+
+### 复合组件工具 (Other Components)
+
+#### 1. list_other_components
+**功能**：列出 `src/other/components/index.js` 中导出的复合组件与工具
+**参数**：无
+**返回**：复合组件列表
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "list_other_components",
+    "arguments": {}
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请列出项目中的复合组件。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__list_other_components()
+```
+
+**返回值示例**：
+```json
+{
+  "exports": [
+    "LeftTree", "Query", "TitleAndBack", "TableOrList",
+    "FormItemOrDetailItem", "IconfontWapper", "TemplateMode",
+    "ModelOrDrawer", "ModeAvatar", "listToTree", "generateUniqueId",
+    "getBelongCate", "getparentDataById", "getAllIds",
+    "HTML5Backend", "DndProvider", "DragPreviewImage",
+    "useDrag", "useDrop", "useDragDropManager", "useDragLayer"
+  ],
+  "exportIndex": "src/other/components/index.js"
+}
+```
+
+##### Claude Code 调用示例
+```
+请列出项目中的复合组件。
+```
+
+##### Qwen Code 调用示例
+```
+请列出项目中的复合组件。
+```
+
+#### 2. get_other_component
+**功能**：根据组件名获取实现路径、types、docs、透传目标与 props 列表
+**参数**：
+- `name` (string, required): 组件名称
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "get_other_component",
+    "arguments": {
+      "name": "Query"
+    }
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请获取Query组件的详细信息。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__get_other_component({ "name": "Query" })
+```
+
+**返回值示例**：
+```json
+{
+  "name": "Query",
+  "found": true,
+  "exportIndex": "src/other/components/index.js",
+  "folder": "src/other/components/Query",
+  "implementation": "src/other/components/Query/index.tsx",
+  "types": null,
+  "docs": [],
+  "props": null,
+  "passthroughTargets": [
+    { "component": "Select", "spread": "..restProps}" },
+    { "component": "DatePicker", "spread": "..restProps}" },
+    { "component": "Input", "spread": "..restProps} /" },
+    { "component": "ProFormText", "spread": "..others} labelAlign='left' style={{ width: \"100%\" }} /" }
+  ],
+  "examples": [
+    { "file": "mode-packages/query/demo/base.jsx", "type": "demo" }
+  ]
+}
+```
+
+##### Claude Code 调用示例
+```
+请获取Query组件的详细信息。
+```
+
+##### Qwen Code 调用示例
+```
+请获取Query组件的详细信息。
+```
+
+#### 3. search_component_examples
+**功能**：在仓库内搜索组件名的用法片段（md/js/ts/tsx）
+**参数**：
+- `name` (string, required): 组件名称
+- `maxResults` (number, optional, default: 20): 最大结果数，范围1-50
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "search_component_examples",
+    "arguments": {
+      "name": "TableOrList",
+      "maxResults": 10
+    }
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请搜索TableOrList组件的使用示例，最多返回5个。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__search_component_examples({ "name": "TableOrList", "maxResults": 5 })
+```
+
+**返回值示例**：
+```json
+{
+  "name": "TableOrList",
+  "hits": [
+    {
+      "file": "mode-packages/table-or-list/demo/base.jsx",
+      "type": "demo",
+      "content": "import React, { useState, useRef } from 'react';\nimport { TableOrList } from '@szc-ft/szcd'..."
+    },
+    {
+      "file": "mode-packages/table-or-list/demo/base1.jsx",
+      "type": "demo",
+      "content": "import React, { useState, useRef } from 'react';\nimport { TableOrList } from '@szc-ft/szcd'..."
+    }
+  ]
+}
+```
+
+##### Claude Code 调用示例
+```
+请搜索TableOrList组件的使用示例，最多返回10个。
+```
+
+##### Qwen Code 调用示例
+```
+请搜索TableOrList组件的使用示例，最多返回10个。
+```
+
+### Cover层组件工具
+
+#### 4. list_cover_components
+**功能**：列出 src/components/cover/ 目录下的 Cover 层封装组件
+**参数**：无
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 4,
+  "method": "tools/call",
+  "params": {
+    "name": "list_cover_components",
+    "arguments": {}
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请列出Cover层的封装组件。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__list_cover_components()
+```
+
+##### Claude Code 调用示例
+```
+请列出Cover层的封装组件。
+```
+
+##### Qwen Code 调用示例
+```
+请列出Cover层的封装组件。
+```
+
+#### 5. get_cover_component
+**功能**：获取 Cover 层组件的详细信息，包括实现路径、Props 定义、透传目标等
+**参数**：
+- `name` (string, required): 组件名称
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 5,
+  "method": "tools/call",
+  "params": {
+    "name": "get_cover_component",
+    "arguments": {
+      "name": "Button"
+    }
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请获取Cover层Button组件的详细信息。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__get_cover_component({ "name": "Button" })
+```
+
+##### Claude Code 调用示例
+```
+请获取Cover层Button组件的详细信息。
+```
+
+##### Qwen Code 调用示例
+```
+请获取Cover层Button组件的详细信息。
+```
+
+### Wrapper层组件工具
+
+#### 6. list_wrapper_components
+**功能**：列出 src/components/wrappers/ 目录下的 Wrapper 层业务组件
+**参数**：无
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 6,
+  "method": "tools/call",
+  "params": {
+    "name": "list_wrapper_components",
+    "arguments": {}
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请列出Wrapper层的业务组件。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__list_wrapper_components()
+```
+
+##### Claude Code 调用示例
+```
+请列出Wrapper层的业务组件。
+```
+
+##### Qwen Code 调用示例
+```
+请列出Wrapper层的业务组件。
+```
+
+### ProPackages组件工具
+
+#### 7. list_pro_package_components
+**功能**：列出 pro-packages/ 目录下的 ProPackages 组件封装
+**参数**：无
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 7,
+  "method": "tools/call",
+  "params": {
+    "name": "list_pro_package_components",
+    "arguments": {}
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请列出ProPackages的组件封装。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__list_pro_package_components()
+```
+
+##### Claude Code 调用示例
+```
+请列出ProPackages的组件封装。
+```
+
+##### Qwen Code 调用示例
+```
+请列出ProPackages的组件封装。
+```
+
+### Ant Design组件工具
+
+#### 8. list_antd_components
+**功能**：列出 Ant Design 组件的分类概览和各分类下的组件数量
+**参数**：无
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 8,
+  "method": "tools/call",
+  "params": {
+    "name": "list_antd_components",
+    "arguments": {}
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请列出Ant Design组件的分类概览。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__list_antd_components()
+```
+
+##### Claude Code 调用示例
+```
+请列出Ant Design组件的分类概览。
+```
+
+##### Qwen Code 调用示例
+```
+请列出Ant Design组件的分类概览。
+```
+
+#### 9. list_antd_components_by_category
+**功能**：按分类列出 Ant Design 组件
+**参数**：
+- `category` (enum, optional, default: "通用"): 组件分类，可选值：通用、布局、导航、数据录入、数据展示、反馈、其他
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 9,
+  "method": "tools/call",
+  "params": {
+    "name": "list_antd_components_by_category",
+    "arguments": {
+      "category": "数据录入"
+    }
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请按分类列出Ant Design的数据录入组件。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__list_antd_components_by_category({ "category": "数据录入" })
+```
+
+##### Claude Code 调用示例
+```
+请按分类列出Ant Design的数据录入组件。
+```
+
+##### Qwen Code 调用示例
+```
+请按分类列出Ant Design的数据录入组件。
+```
+
+#### 10. get_antd_component
+**功能**：获取 Ant Design 组件的详细信息
+**参数**：
+- `name` (string, required): 组件名称
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 10,
+  "method": "tools/call",
+  "params": {
+    "name": "get_antd_component",
+    "arguments": {
+      "name": "Input"
+    }
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请获取Ant Design Input组件的详细信息。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__get_antd_component({ "name": "Input" })
+```
+
+##### Claude Code 调用示例
+```
+请获取Ant Design Input组件的详细信息。
+```
+
+##### Qwen Code 调用示例
+```
+请获取Ant Design Input组件的详细信息。
+```
+
+### ProComponents组件工具
+
+#### 11. list_pro_components
+**功能**：列出 ProComponents 组件的分类概览
+**参数**：无
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 11,
+  "method": "tools/call",
+  "params": {
+    "name": "list_pro_components",
+    "arguments": {}
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请列出ProComponents的分类概览。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__list_pro_components()
+```
+
+##### Claude Code 调用示例
+```
+请列出ProComponents的分类概览。
+```
+
+##### Qwen Code 调用示例
+```
+请列出ProComponents的分类概览。
+```
+
+#### 12. list_pro_components_by_category
+**功能**：按分类列出 ProComponents 组件
+**参数**：
+- `category` (enum, optional, default: "数据录入"): 组件分类，可选值：数据录入、数据展示、布局、反馈
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 12,
+  "method": "tools/call",
+  "params": {
+    "name": "list_pro_components_by_category",
+    "arguments": {
+      "category": "数据展示"
+    }
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请按分类列出ProComponents的数据展示组件。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__list_pro_components_by_category({ "category": "数据展示" })
+```
+
+##### Claude Code 调用示例
+```
+请按分类列出ProComponents的数据展示组件。
+```
+
+##### Qwen Code 调用示例
+```
+请按分类列出ProComponents的数据展示组件。
+```
+
+#### 13. get_pro_component
+**功能**：获取 ProComponents 组件的详细信息
+**参数**：
+- `name` (string, required): 组件名称
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 13,
+  "method": "tools/call",
+  "params": {
+    "name": "get_pro_component",
+    "arguments": {
+      "name": "ProTable"
+    }
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请获取ProTable组件的详细信息。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__get_pro_component({ "name": "ProTable" })
+```
+
+##### Claude Code 调用示例
+```
+请获取ProTable组件的详细信息。
+```
+
+##### Qwen Code 调用示例
+```
+请获取ProTable组件的详细信息。
+```
+
+### 全局功能工具
+
+#### 14. search_all_components
+**功能**：全局搜索所有层级的组件
+**参数**：
+- `keyword` (string, required): 搜索关键词
+- `type` (enum, optional): 按类型筛选，可选值：cover、wrapper、pro-package、antd、pro-components、other
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 14,
+  "method": "tools/call",
+  "params": {
+    "name": "search_all_components",
+    "arguments": {
+      "keyword": "form",
+      "type": "pro-components"
+    }
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请搜索包含"form"的ProComponents组件。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__search_all_components({ "keyword": "form", "type": "pro-components" })
+```
+
+##### Claude Code 调用示例
+```
+请搜索包含"form"的ProComponents组件。
+```
+
+##### Qwen Code 调用示例
+```
+请搜索包含"form"的ProComponents组件。
+```
+
+#### 15. get_component_library_overview
+**功能**：获取组件库的完整概览
+**参数**：无
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 15,
+  "method": "tools/call",
+  "params": {
+    "name": "get_component_library_overview",
+    "arguments": {}
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请提供组件库的完整概览。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__get_component_library_overview()
+```
+
+**返回值示例**：
+```json
+{
+  "summary": {
+    "antDesign": { "count": 0, "description": "Ant Design 官方组件" },
+    "proComponents": { "count": 0, "description": "ProComponents 高级组件" },
+    "coverLayer": { "count": 36, "description": "Cover 层封装组件", "path": "src/components/cover" },
+    "wrapperLayer": { "count": 7, "description": "Wrapper 层业务组件", "path": "src/components/wrappers" },
+    "proPackages": { "count": 8, "description": "ProPackages 封装", "path": "pro-packages" },
+    "compositeComponents": { "count": 21, "description": "复合业务组件", "path": "src/other/components" }
+  },
+  "totalCustomComponents": 72
+}
+```
+
+##### Claude Code 调用示例
+```
+请提供组件库的完整概览。
+```
+
+##### Qwen Code 调用示例
+```
+请提供组件库的完整概览。
+```
+
+### 文件操作工具
+
+#### 16. read_file
+**功能**：读取仓库内文件（相对路径）
+**参数**：
+- `path` (string, required): 文件相对路径
+- `maxChars` (number, optional, default: 20000): 最大字符数，范围200-200000
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 16,
+  "method": "tools/call",
+  "params": {
+    "name": "read_file",
+    "arguments": {
+      "path": "src/other/components/Query/index.tsx",
+      "maxChars": 5000
+    }
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请读取src/other/components/Query/index.tsx文件内容，最多5000个字符。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__read_file({ "path": "src/other/components/Query/index.tsx", "maxChars": 5000 })
+```
+
+##### Claude Code 调用示例
+```
+请读取src/other/components/Query/index.tsx文件内容，最多5000个字符。
+```
+
+##### Qwen Code 调用示例
+```
+请读取src/other/components/Query/index.tsx文件内容，最多5000个字符。
+```
+
+#### 17. get_accurate_component_doc
+**功能**：获取复合组件的准确Props文档，包含透传机制的详细说明
+**参数**：
+- `name` (string, required): 组件名称
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 17,
+  "method": "tools/call",
+  "params": {
+    "name": "get_accurate_component_doc",
+    "arguments": {
+      "name": "Query"
+    }
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请获取Query组件的准确文档，包含透传机制说明。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__get_accurate_component_doc({ "name": "Query" })
+```
+
+##### Claude Code 调用示例
+```
+请获取Query组件的准确文档，包含透传机制说明。
+```
+
+##### Qwen Code 调用示例
+```
+请获取Query组件的准确文档，包含透传机制说明。
+```
+
+### 缓存管理工具
+
+#### 18. refresh_component_docs
+**功能**：刷新 Ant Design / ProComponents 组件文档缓存
+**参数**：
+- `source` (enum, optional, default: "all"): 刷新来源，可选值：antd、pro-components、all
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 18,
+  "method": "tools/call",
+  "params": {
+    "name": "refresh_component_docs",
+    "arguments": {
+      "source": "all"
+    }
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请刷新所有组件文档缓存。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__refresh_component_docs({ "source": "all" })
+```
+
+##### Claude Code 调用示例
+```
+请刷新所有组件文档缓存。
+```
+
+##### Qwen Code 调用示例
+```
+请刷新所有组件文档缓存。
+```
+
+### 设计稿图片分析工具（兜底/代理）
+
+> **核心定位**：此工具是**兜底机制**，专门解决"用户使用的 LLM 不支持图片理解"的问题。
+>
+> 当用户的 IDE/AI 是纯文本模型（无法直接看设计稿截图）时，由 MCP 服务器调用多模态模型代为"看图"，将图片内容转化为结构化文本返回给用户 LLM，让用户 LLM 基于文字描述生成代码。如果用户的 LLM 本身支持图片输入（如 Claude 4、GPT-4o），则**不需要**使用此工具。
+
+#### 19. analyze_design_image
+**功能**：分析UI设计稿图片，将视觉设计转化为结构化文本描述。支持三通道提取，追求设计稿样式的高度还原：
+
+- **通道1: ConfigProvider Token** — 对齐 tokenConfig.json 结构，精确提取全局 Token 和组件级 Token，自动对比 szcd 默认值生成 themeDiff，输出可直接使用的 `<ConfigProvider theme={...}>` 配置代码
+- **通道2: CSS 覆盖层** — 提取 ConfigProvider Token 无法覆盖的样式属性（布局、伪元素、间距、边框、动画、字体族等），生成组件级 CSS 覆盖代码
+- **通道3: 视觉细节** — 提取渐变色、滚动条、遮罩层、状态变体(hover/focus/active/disabled)等更细粒度的视觉信息，生成全局 CSS 覆盖代码
+
+**参数**：
+- `imageSource` (string, required): 图片数据：base64编码字符串、HTTP/HTTPS URL、或相对于项目根目录的文件路径
+- `sourceType` (enum, optional, default: "file_path"): 图片来源类型：base64、url、file_path
+- `analysisType` (enum, optional, default: "full"): 分析类型：layout(布局)、components(组件)、tokens(通道1)、full(通道1+2)、pixel_perfect(全部三通道+8K输出)
+- `pageContext` (string, optional): 页面业务上下文描述
+- `targetLibrary` (enum, optional, default: "auto"): 期望匹配的组件库：szcd、antd、pro-components、auto
+- `outputFormat` (enum, optional, default: "markdown"): 输出格式：markdown、json、structured_text、restoration_code(一键输出完整还原代码)
+
+**返回值**（full/pixel_perfect 模式）：
+- designTokens: 全局 Token（对齐 tokenConfig.json）
+- componentStyleTokens: 组件级 Token
+- themeDiff: 与默认值差异 + ConfigProvider 代码
+- cssOverrides: 组件级 CSS 覆盖代码
+- visualDetails: 视觉细节（仅 pixel_perfect）
+- fidelityScore: 还原度评分（0-100）
+
+### 样式注入指南工具
+
+#### 20. get_style_injection_guide
+**功能**：查询 szcd 复合组件的样式注入方法。返回指定组件的可用样式 props、注入方式（ModeStyle/TreeBoxStyle/btnStyle/inline style等）、代码示例，以及组件嵌套时的 CSS 穿透路径和智能分配策略。
+
+**适用场景**：
+- 已有设计稿分析结果但需要知道如何将 CSS 注入到组件中
+- 使用 Sketch/Figma MCP 获取了设计规范后需了解 szcd 组件的样式定制方式
+- 开发时需要快速查询某个组件支持哪些样式 props
+
+**参数**：
+- `componentNames` (string[], optional): 要查询的组件名列表，如 ['Query', 'TableOrList', 'LeftTree']。不传则返回所有复合组件的完整指南
+- `includeNesting` (boolean, optional, default: true): 是否包含嵌套注入指南（TemplateMode/ModelOrDrawer 容器场景的 CSS 穿透路径和分配策略）
+- `includeSmartDistribute` (boolean, optional, default: false): 是否包含智能 CSS 分配建议（需要传入 cssOverrides 参数）
+- `cssOverrides` (array, optional): CSS 覆盖列表（用于智能分配），格式与 analyze_design_image 返回的 cssOverrides.perComponent 一致
+- `outputFormat` (enum, optional, default: "markdown"): 输出格式：markdown、json、text
+
+**4种注入方式**：
+- `modeStyle`: ModeStyle prop → styled-components 注入（Query, TableOrList, LeftTree, TitleAndBack, TemplateMode, ModeAvatar）
+- `modeStyleTag`: ModeStyle prop → 动态 `<style>` 标签注入（ModelOrDrawer 专属）
+- `inlineOnly`: 仅 inline style / 全局 CSS（FormItemOrDetailItem, CustomOption, TreeNode）
+- `passthrough`: className/style prop 透传（IconfontWapper）
+
+**嵌套场景**：
+- TemplateMode 的 ModeStyle 可穿透到子组件（通过 `.leftContentBox` / `.rightContentBox_top` / `.rightContentBox_bottom` 定位）
+- ModelOrDrawer DOM 挂载在 document.body，父级穿不透
+
+##### MCP协议调用示例（底层）
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 20,
+  "method": "tools/call",
+  "params": {
+    "name": "get_style_injection_guide",
+    "arguments": {
+      "componentNames": ["Query"],
+      "includeNesting": true
+    }
+  }
+}
+```
+
+##### Trae CLI 调用示例
+
+**自然语言触发**：
+```
+请查询 Query 组件的样式注入方法。
+```
+
+**实际 MCP 工具调用**（Trae CLI 自动生成）：
+```json
+mcp__szcd-component-helper__get_style_injection_guide({ "componentNames": ["Query"], "includeNesting": true })
+```
+
+**返回值示例**：
+```json
+{
+  "component": "Query",
+  "injectionType": "modeStyle",
+  "description": "ModeStyle prop → styled-components 注入",
+  "styleProps": ["ModeStyle"],
+  "codeExample": "<Query ModeStyle={{ padding: '16px', background: '#fff' }} />",
+  "nestingGuide": null
+}
+```
+
+##### Claude Code 调用示例
+```
+请查询 Query 组件的样式注入方法。
+```
+
+##### Qwen Code 调用示例
+```
+请查询 TemplateMode 和 Query 组件的样式注入指南，包括嵌套场景。
+```
+
+## 安装方式
+
+### 通过 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：配置服务器地址
+
+#### 方式1：使用配置文件（推荐）
+
+编辑配置文件 `~/.szcd-mcp-config.json`：
+
+```json
+{
+  "MCP_SERVER_URL": "http://localhost:3456",
+  "MCP_TIMEOUT": 30000,
+  "MCP_API_KEY": ""
+}
+```
+
+#### 方式2：使用环境变量
+
+```bash
+# Linux/macOS
+export MCP_SERVER_URL="http://localhost:3456"
+export MCP_TIMEOUT="30000"
+export MCP_API_KEY="your-api-key"
+
+# Windows (PowerShell)
+$env:MCP_SERVER_URL="http://localhost:3456"
+$env:MCP_TIMEOUT="30000"
+$env:MCP_API_KEY="your-api-key"
+
+# Windows (CMD)
+set MCP_SERVER_URL=http://localhost:3456
+set MCP_TIMEOUT=30000
+set MCP_API_KEY=your-api-key
+```
+
+#### 方式3：在 IDE 配置中设置
+
+**方式3a：使用代理桥接（向后兼容）**
+
+编辑您的 IDE 配置文件（如 `.trae/config.json` 或 Claude Code 配置）：
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "command": "npx",
+      "args": ["szcd-mcp-proxy"],
+      "env": {
+        "MCP_SERVER_URL": "http://localhost:3456",
+        "MCP_TIMEOUT": "30000",
+        "MCP_API_KEY": ""
+      }
+    }
+  }
+}
+```
+
+**方式3b：Trae CLI Streamable HTTP 直连（推荐）**
+
+在 `~/.trae/trae_cli.yaml` 中配置：
+
+```yaml
+mcp_servers:
+    - name: szcd-component-helper
+      url: http://localhost:3456/mcp
+      type: http
+```
+
+**方式3c：本地直连 stdio（推荐，无需远程服务器）**
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "command": "npx",
+      "args": ["szcd-mcp-server", "--stdio"]
+    }
+  }
+}
+```
+
+**方式3d：Qwen Code Streamable HTTP 直连（推荐）**
+
+在 `~/.qwen/settings.json` 中配置：
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "httpUrl": "http://localhost:3456/mcp",
+      "timeout": 30000
+    }
+  }
+}
+```
+
+**方式3e：Qwen Code 本地直连 stdio（推荐，无需远程服务器）**
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "command": "npx",
+      "args": ["szcd-mcp-server", "--stdio"]
+    }
+  }
+}
+```
+
+### 步骤3：验证配置
+
+运行以下命令验证配置是否正确：
+
+```bash
+# 测试服务器连接
+curl http://localhost:3456/health
+
+# 或使用代理脚本测试
+npx szcd-mcp-proxy --test
+```
+
+## 配置优先级
+
+地址获取的优先级顺序：
+
+1. **环境变量**（最高优先级）
+   - `MCP_SERVER_URL`
+   - `MCP_TIMEOUT`
+   - `MCP_API_KEY`
+
+2. **配置文件**（中等优先级）
+   - `~/.szcd-mcp-config.json`
+
+3. **默认值**（最低优先级）
+   - `MCP_SERVER_URL`: `http://localhost:3456`
+   - `MCP_TIMEOUT`: `30000`
+   - `MCP_API_KEY`: ``
+
+## 环境变量说明
+
+### MCP 连接配置
+
+| 变量 | 说明 | 默认值 | 示例 |
+|------|------|--------|------|
+| `MCP_SERVER_URL` | MCP 服务器地址 | `http://localhost:3456` | `http://192.168.1.100:3456` |
+| `MCP_TIMEOUT` | 请求超时时间(毫秒) | `30000` | `60000` |
+| `MCP_API_KEY` | MCP API 密钥（可选） | `` | `your-secret-key` |
+
+### 视觉模型配置（设计稿分析功能必需）
+
+| 变量 | 说明 | 默认值 | 示例 |
+|------|------|--------|------|
+| `VISION_API_KEY` | 视觉模型 API 密钥 | 读取 `ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY` | `sk-ant-...` |
+| `ANTHROPIC_API_KEY` | Claude API 密钥（当使用 Anthropic 时） | `` | `sk-ant-...` |
+| `OPENAI_API_KEY` | OpenAI API 密钥（当使用 OpenAI 时） | `` | `sk-...` |
+| `VISION_PROVIDER` | 视觉模型提供商 | `anthropic` | `anthropic` / `openai` |
+| `VISION_MODEL` | 视觉模型名称 | `claude-sonnet-4-6` | `gpt-4o` |
+| `VISION_API_URL` | 自定义视觉模型 API 地址 | 官方地址 | `https://api.anthropic.com/v1/messages` |
+| `DESIGN_ANALYSIS_ORDER` | 分析优先级：`vision_first` / `ocr_first` / `vision_only` / `ocr_only` | `vision_first` | `ocr_first` |
+| `OCR_SCRIPT_PATH` | 本地 OCR 脚本路径（降级用） | `/usr/local/bin/ocr-image` | `/usr/local/bin/ocr-image` |
+
+### 分析优先级说明
+
+| 值 | 行为 |
+|------|------|
+| `vision_first`（默认） | 先调用多模态模型，失败后降级到本地 OCR |
+| `ocr_first` | 先调用本地 OCR，识别不到文字再尝试多模态模型 |
+| `vision_only` | 只用多模态模型，失败直接报错 |
+| `ocr_only` | 只用本地 OCR，不调用多模态模型，返回原始文字 |
+
+## 使用流程
+
+1. **确定用户需求**：了解用户想要查询的组件信息或文件
+2. **Claude Code自动选择合适的MCP工具**：Claude Code会根据需求自动识别并调用对应的MCP工具
+3. **Claude Code自动连接MCP服务器**：Claude Code通过MCP协议连接到运行在MCP_SERVER_URL的服务器
+4. **MCP服务器执行查询**：服务器接收工具调用请求，执行相应的业务逻辑
+5. **返回结构化结果**：服务器返回JSON格式的结果，AI助手处理并呈现给用户
+
+## 注意事项
+
+- 所有路径都是相对于项目根目录的相对路径
+- 搜索示例时，结果可能会有重复或不相关的内容，需要用户自行筛选
+- 读取文件时，大文件可能会被截断，用户可以通过设置 maxChars 参数来调整
+- **需要确保 MCP 服务器正在运行，否则无法查询数据**
+- **服务器地址从环境变量或配置文件动态获取，无需硬编码**
+- **Claude Code会自动处理MCP协议通信，用户无需手动调用API**
+- **Qwen Code会自动处理MCP协议通信，用户无需手动调用API**
+- **设计稿分析功能需要配置视觉模型 API Key**，未配置时 analyze_design_image 工具会返回错误
+- **设计稿分析会调用外部多模态模型 API**，会产生额外费用（单张约 $0.03~0.05）
+- **设计稿分析结果会自动缓存 24 小时**，同一图片重复查询不会重复计费
+
+## 故障排除
+
+### 连接失败
+
+1. 检查服务器是否运行：`curl ${MCP_SERVER_URL}/health`
+2. 检查防火墙设置
+3. 检查网络连接
+4. 确认 `MCP_SERVER_URL` 配置正确
+5. 检查环境变量是否正确设置
+6. 检查配置文件 `~/.szcd-mcp-config.json` 是否存在
+
+### 配置文件问题
+
+1. 检查配置文件路径：`~/.szcd-mcp-config.json`
+2. 检查 JSON 格式是否正确
+3. 检查文件权限
+
+## 示例对话
+
+### 示例 1：获取组件库概览
+
+**用户**：szcd 组件库有哪些组件？
+**助手**：让我为您查询 szcd 组件库的完整概览。
+
+[助手自动触发MCP工具调用：get_component_library_overview()]
+
+**助手**：以下是 szcd 组件库的概览：
+- Cover 层封装组件：36 个 (路径: src/components/cover)
+- Wrapper 层业务组件：7 个 (路径: src/components/wrappers)
+- ProPackages 封装：8 个 (路径: pro-packages)
+- 复合业务组件：21 个 (路径: src/other/components)
+- Ant Design 官方组件：0 个 (需刷新缓存获取)
+- ProComponents 高级组件：0 个 (需刷新缓存获取)
+
+### 示例 2：搜索组件
+
+**用户**：搜索包含 "table" 的组件
+**助手**：让我在整个组件库中搜索包含 "table" 的组件。
+
+[助手自动触发MCP工具调用：search_all_components({"keyword": "table"})]
+
+**助手**：搜索到以下包含 "table" 的组件：
+- TableOrList（复合组件）
+- ProTable（ProComponents）
+- Table（Ant Design）
+
+### 示例 3：列出 Cover 层组件
+
+**用户**：Cover 层有哪些组件？
+**助手**：让我查询 Cover 层的组件列表。
+
+[助手自动触发MCP工具调用：list_cover_components()]
+
+**助手**：Cover 层有以下组件：
+- Button
+- Input
+- Select
+- DatePicker
+...
+
+### 示例 4：获取 Ant Design 组件信息
+
+**用户**：Ant Design 的 Table 组件有哪些 Props？
+**助手**：让我查询 Ant Design Table 组件的详细信息。
+
+[助手自动触发MCP工具调用：get_antd_component({"name": "Table"})]
+
+**助手**：Ant Design Table 组件的详细信息如下：
+- 中文名：表格
+- 描述：展示行列数据
+- 主要 Props：dataSource、columns、pagination、loading...
+
+### 示例 5：列出复合组件
+
+**用户**：列出项目中的复合组件
+**助手**：让我使用 list_other_components 工具来查询项目中的复合组件。
+
+[助手自动触发MCP工具调用：list_other_components()]
+
+**助手**：以下是 szcd 项目中的复合组件列表：
+- Query
+- TableOrList
+- TitleAndBack
+- LeftTree
+
+这些组件都在 src/other/components/index.js 中导出。
+
+### 示例 6：获取组件详情
+
+**用户**：获取 Query 组件的详情
+**助手**：让我使用 get_other_component 工具来获取 Query 组件的详细信息。
+
+[助手自动触发MCP工具调用：get_other_component({"name": "Query"})]
+
+**助手**：Query 组件的详细信息如下：
+- 实现文件：src/other/components/Query/index.tsx
+- 文档文件：src/other/components/Query/Query.md
+- 导出位置：src/other/components/index.js
+
+### 示例 7：搜索组件示例
+
+**用户**：搜索 TableOrList 组件的使用示例
+**助手**：让我使用 search_component_examples 工具来搜索 TableOrList 组件的使用示例。
+
+[助手自动触发MCP工具调用：search_component_examples({"name": "TableOrList", "maxResults": 10})]
+
+**助手**：以下是 TableOrList 组件的使用示例：
+1. 文件：src/anyMd/TableOrList.json - 包含组件配置信息
+2. 文件：src/anyMd/TableOrList.txt - 包含组件描述信息
+
+### 示例 8：读取文件内容
+
+**用户**：查看 Query 组件的实现代码
+**助手**：让我使用 read_file 工具来读取 Query 组件的实现文件。
+
+[助手自动触发MCP工具调用：read_file({"path": "src/other/components/Query/index.tsx"})]
+
+**助手**：Query 组件的实现代码如下：
+```tsx
+// 这里显示 src/other/components/Query/index.tsx 的内容
+```
+
+### 示例 9：分析设计稿图片
+
+**用户**：我有一张设计稿截图，路径是 `docs/designs/user-list.png`，请帮我分析页面结构并生成 szcd 代码。
+
+**助手**：让我使用 analyze_design_image 工具来分析这张设计稿。
+
+[助手自动触发MCP工具调用：analyze_design_image({
+  "imageSource": "docs/designs/user-list.png",
+  "sourceType": "file_path",
+  "analysisType": "full",
+  "pageContext": "用户管理列表页",
+  "targetLibrary": "szcd",
+  "outputFormat": "markdown"
+})]
+
+**助手**：设计稿分析结果如下：
+
+**页面类型**：列表页（带左侧树形导航）
+
+**布局结构**：
+- 顶部查询区（Query 组件）：用户名 Input、状态 Select、创建时间 RangePicker、查询/重置按钮
+- 左侧树区（LeftTree 组件）：组织机构树
+- 右侧表格区（TableOrList 组件）：用户编号、用户名、角色、状态列，含编辑/删除/查看操作
+
+**推荐代码结构**：
+```tsx
+import { Query, LeftTree, TableOrList } from '@szc-ft/szcd';
+
+// 使用 mode-packages/table-or-list 模板
+```
+
+## AI助手与MCP服务交互详解
+
+### 调用机制
+
+AI助手 通过 MCP 协议（Streamable HTTP 或 stdio）连接到 MCP 服务器。AI助手 会根据用户自然语言请求自动识别并调用适当的MCP工具。
+
+### HTTP头部信息（AI助手连接时必需）
+
+当AI助手连接到MCP服务器时，会使用以下HTTP头部：
+
+| 头部字段 | 值 | 说明 |
+|----------|----|-----|
+| `Content-Type` | `application/json` | 指定请求体为JSON格式 |
+| `Accept` | `application/json` | 指定期望响应为JSON格式 |
+| `Connection` | `keep-alive` | 保持长连接以提高性能 |
+
+### 调用流程
+
+当用户提出需求时，AI助手会：
+
+1. **理解用户意图**：分析用户想要获取的信息类型
+2. **选择适当工具**：从 MCP 服务器提供的工具中选择最合适的
+3. **构建参数**：根据用户输入构建工具调用所需的参数
+4. **发起 MCP 调用**：通过 MCP 协议发送工具调用请求到服务器
+5. **处理响应**：接收服务器返回的 JSON 格式结果
+6. **格式化输出**：将结果以易读的方式呈现给用户
+
+### 对比：MCP 协议底层 vs AI助手 实际调用
+
+| 维度 | MCP 协议底层调用 | AI助手 实际调用 |
+|------|-----------------|-------------------|
+| **调用格式** | `{"jsonrpc":"2.0","method":"tools/call","params":{...}}` | 自然语言触发，AI助手自动转换 |
+| **传输协议** | JSON-RPC over HTTP/SSE/stdio | 由 AI助手 框架自动处理 |
+| **参数传递** | 嵌套在 `params.arguments` 中 | 从自然语言解析后构建参数 |
+| **响应格式** | `{"jsonrpc":"2.0","result":{...}}` | 直接处理并格式化为自然语言响应 |
+| **触发方式** | 手动构造 HTTP 请求 | 自然语言对话自动触发 |
+
+### 实际调用示例
+
+**用户输入**：
+```
+szcd 组件库有哪些组件？
+```
+
+**AI助手 自动执行**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "get_component_library_overview",
+    "arguments": {}
+  }
+}
+```
+
+**返回结果**（AI助手 接收到的原始 JSON）：
+```json
+{
+  "summary": {
+    "coverLayer": { "count": 36, "path": "src/components/cover" },
+    "wrapperLayer": { "count": 7, "path": "src/components/wrappers" },
+    "proPackages": { "count": 8, "path": "pro-packages" },
+    "compositeComponents": { "count": 21, "path": "src/other/components" }
+  },
+  "totalCustomComponents": 72
+}
+```
+
+**AI助手 呈现给用户**：
+```
+szcd 组件库共有 72 个自定义组件：
+- Cover 层封装组件：36 个
+- Wrapper 层业务组件：7 个
+- ProPackages 封装：8 个
+- 复合业务组件：21 个
+```
+
+## Trae CLI 与 MCP 服务交互详解
+
+### 调用机制
+
+Trae CLI 通过 MCP 协议（Streamable HTTP 或 stdio）连接到 MCP 服务器，工具调用格式为：
+
+```
+mcp__szcd-component-helper__<tool_name>(<params>)
+```
+
+其中：
+- `szcd-component-helper` 是 MCP 服务器名称（在 `~/.trae/trae_cli.yaml` 中配置）
+- `<tool_name>` 是工具名称（如 `list_other_components`、`get_other_component` 等）
+- `<params>` 是 JSON 格式的参数对象
+
+### 调用流程
+
+当用户提出需求时，Trae CLI 会：
+
+1. **理解用户意图**：分析用户想要获取的信息类型
+2. **选择适当工具**：从 MCP 服务器提供的工具中选择最合适的
+3. **构建参数**：根据用户输入构建工具调用所需的参数
+4. **发起 MCP 调用**：通过 MCP 协议发送工具调用请求到服务器
+5. **处理响应**：接收服务器返回的 JSON 格式结果
+6. **格式化输出**：将结果以易读的方式呈现给用户
+
+### 对比：MCP 协议底层 vs Trae CLI 实际调用
+
+| 维度 | MCP 协议底层调用 | Trae CLI 实际调用 |
+|------|-----------------|-------------------|
+| **调用格式** | `{"jsonrpc":"2.0","method":"tools/call","params":{...}}` | `mcp__szcd-component-helper__<tool>(params)` |
+| **传输协议** | JSON-RPC over HTTP/SSE/stdio | 由 Trae CLI 框架自动处理 |
+| **参数传递** | 嵌套在 `params.arguments` 中 | 直接作为函数参数传入 |
+| **响应格式** | `{"jsonrpc":"2.0","result":{...}}` | 直接返回 result 内容 |
+| **触发方式** | 手动构造 HTTP 请求 | 自然语言对话自动触发 |
+
+### 实际调用示例
+
+**用户输入**：
+```
+szcd 组件库有哪些组件？
+```
+
+**Trae CLI 自动执行**：
+```
+mcp__szcd-component-helper__get_component_library_overview()
+```
+
+**返回结果**（Trae CLI 接收到的原始 JSON）：
+```json
+{
+  "summary": {
+    "coverLayer": { "count": 36, "path": "src/components/cover" },
+    "wrapperLayer": { "count": 7, "path": "src/components/wrappers" },
+    "proPackages": { "count": 8, "path": "pro-packages" },
+    "compositeComponents": { "count": 21, "path": "src/other/components" }
+  },
+  "totalCustomComponents": 72
+}
+```
+
+**Trae CLI 呈现给用户**：
+```
+szcd 组件库共有 72 个自定义组件：
+- Cover 层封装组件：36 个
+- Wrapper 层业务组件：7 个
+- ProPackages 封装：8 个
+- 复合业务组件：21 个
+```