@szc-ft/mcp-szcd-client 0.12.1 → 0.12.4

package/qwen-extension/skills/szcd-component-helper/SKILL.md

@@ -0,0 +1,827 @@
+---
+name: szcd-component-helper
+description: 帮助用户查询和了解 szcd 项目中的组件信息，包括 Cover 层组件、Wrapper 层组件、Ant Design 组件、ProComponents 以及复合组件。支持组件搜索、详情查询、使用示例搜索、文件读取、设计稿图片分析、样式注入指南、架构概览、组件依赖分析、Props链解析、Swagger联调、CODING Issue 获取等。当用户需要了解 szcd 项目的组件结构、查看组件实现、寻找组件使用示例、分析设计稿、联调API、获取需求详情时，应使用此技能。它是一个前端组件库，全名"@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.11.6 - 新增架构概览和组件依赖分析工具；新增深度 Props 链解析和批量文档生成工具；新增 Swagger 联调工具（拉取API + 联调测试）；新增 CODING Issue 获取和配置管理工具；包含设计稿图片分析（视觉代理/兜底方案）、样式注入指南等全部功能
+
+## 架构说明
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    连接方式（三选一）                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  方式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    │         │(桥接代理)  │            │     ││
+│  └─────────────┘         └───────────┘            └─────┘│
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 可用工具（23个）
+
+### 复合组件工具 (Other Components)
+
+#### 1. get_other_component
+**功能**：根据组件名获取实现路径、types、docs、透传目标与 props 列表（若可解析），同时返回组件使用示例
+**参数**：
+- `name` (string, required): 组件名称
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请获取 Query 组件的详细信息。
+```
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool get_other_component with name "Query"' --tool-allowance '*:*'
+```
+
+#### 2. search_component_examples
+**功能**：在仓库内搜索组件名的用法片段（md/js/ts/tsx）
+**参数**：
+- `name` (string, required): 组件名称
+- `maxResults` (number, optional, default: 20): 最大结果数，范围1-50
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请搜索 TableOrList 组件的使用示例，最多返回10个。
+```
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool search_component_examples with name "TableOrList" maxResults 10' --tool-allowance '*:*'
+```
+
+### Cover层组件工具
+
+#### 3. get_cover_component
+**功能**：获取 Cover 层组件的详细信息，包括实现路径、Props 定义、透传目标、准确Props文档、使用示例
+**参数**：
+- `name` (string, required): 组件名称
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请获取 Cover 层 Button 组件的详细信息。
+```
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool get_cover_component with name "Button"' --tool-allowance '*:*'
+```
+
+### Ant Design组件工具
+
+#### 4. list_antd_components
+**功能**：列出 Ant Design 组件的分类概览和各分类下的组件数量
+**参数**：无
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请列出 Ant Design 组件的分类概览。
+```
+
+#### 5. list_antd_components_by_category
+**功能**：按分类列出 Ant Design 组件（通用、布局、导航、数据录入、数据展示、反馈等）
+**参数**：
+- `category` (enum, optional, default: "通用"): 组件分类，可选值：通用、布局、导航、数据录入、数据展示、反馈、其他
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请按分类列出 Ant Design 的数据录入组件。
+```
+
+#### 6. get_antd_component
+**功能**：获取 Ant Design 组件的详细信息，包括中文名、描述、API 文档链接和 Props 列表
+**参数**：
+- `name` (string, required): 组件名称
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请获取 Ant Design Input 组件的详细信息。
+```
+
+### ProComponents组件工具
+
+#### 7. list_pro_components
+**功能**：列出 ProComponents 组件的分类概览，包括 ProTable、ProForm、ProLayout 等高级组件
+**参数**：无
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请列出 ProComponents 的分类概览。
+```
+
+#### 8. list_pro_components_by_category
+**功能**：按分类列出 ProComponents 组件（数据录入、数据展示、布局等）
+**参数**：
+- `category` (enum, optional, default: "数据录入"): 组件分类，可选值：数据录入、数据展示、布局、反馈
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请按分类列出 ProComponents 的数据展示组件。
+```
+
+#### 9. get_pro_component
+**功能**：获取 ProComponents 组件的详细信息，包括特性说明、API 文档和 Props 列表
+**参数**：
+- `name` (string, required): 组件名称
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请获取 ProTable 组件的详细信息。
+```
+
+### 全局搜索工具
+
+#### 10. search_all_components
+**功能**：全局搜索所有层级的组件（Cover、Wrapper、AntD、ProComponents等），支持按类型筛选
+**参数**：
+- `keyword` (string, required): 搜索关键词
+- `type` (enum, optional): 按类型筛选，可选值：cover、wrapper、pro-package、antd、pro-components、other
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请搜索包含"form"的 ProComponents 组件。
+```
+
+### 架构与依赖工具
+
+#### 11. get_architecture_overview
+**功能**：获取 szcd 组件库的分层架构图、层级关系、推荐使用顺序和模板组合模式。帮助理解项目从 Ant Design → Cover → Wrapper → ProPackage → 复合组件 → 模板 的7层封装架构，以及 TreeQueryTable/QueryTabsTables 等页面模板的组合方式。含 LLM 常见映射错误的修正提示
+**参数**：
+- `detail` (enum, optional, default: "summary"): 返回粒度
+  - `summary` — 层级概览+模板模式+LLM提示
+  - `full` — 含所有层组件列表详情
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请提供 szcd 组件库的架构概览。
+```
+
+```
+请获取完整的组件库架构详情，包含所有层级的组件列表。
+```
+
+#### 12. get_component_dependencies
+**功能**：查询某个 szcd 组件的依赖关系图：它依赖哪些 szcd 组件（及外部库），哪些 szcd 组件/模板依赖它。包含组件间的组合关系（import/slot/hook/composition）、模板中的使用角色、以及 LLM 常见映射错误的修正提示
+**参数**：
+- `name` (string, required): 组件名称（如 TemplateMode, LeftTree, TableOrList, Query 等）
+- `layer` (enum, optional): 组件所在层级，可选值：cover、wrapper、pro-package、other。不传时自动推测
+- `direction` (enum, optional, default: "both"): 查询方向
+  - `depends-on` — 它依赖谁
+  - `depended-by` — 谁依赖它
+  - `both` — 双向
+- `includeExternal` (boolean, optional, default: false): 是否包含外部依赖（antd/ProComponents/第三方库），默认仅返回 szcd 组件间关系
+- `includeHooks` (boolean, optional, default: true): 是否包含 hooks 依赖关系（useLeftTree, useTable 等）
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请查询 TemplateMode 组件的依赖关系。
+```
+
+```
+请查询谁依赖了 LeftTree 组件。
+```
+
+### 文件操作工具
+
+#### 13. read_file
+**功能**：读取仓库内文件（相对路径）
+**参数**：
+- `path` (string, required): 文件相对路径
+- `maxChars` (number, optional, default: 20000): 最大字符数，范围200-200000
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请读取 src/other/components/Query/index.tsx 文件内容，最多5000个字符。
+```
+
+### 准确文档工具
+
+#### 14. get_accurate_component_doc
+**功能**：获取复合组件的准确Props文档，包含透传机制的详细说明（特别是Query组件的type/valueType双重透传机制）。同时返回 mode-packages 下的使用文档
+**参数**：
+- `name` (string, required): 组件名称
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请获取 Query 组件的准确文档，包含透传机制说明。
+```
+
+#### 15. resolve_props_chain
+**功能**：递归解析指定组件的完整 Props 链：从顶层到所有透传组件，逐层提取自有 Props、透传目标和继承关系，用于补全组件文档
+**参数**：
+- `name` (string, required): 组件名称（如 FormItemOrDetailItem、Query、TableOrList）
+- `layer` (enum, optional, default: "other"): 组件所在层级，可选值：other、cover、wrapper、pro-package
+- `maxDepth` (number, optional, default: 3): 最大递归深度，范围1-5
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请深度解析 Query 组件的 Props 链。
+```
+
+```
+请递归解析 FormItemOrDetailItem 的完整 Props 链，最大深度5。
+```
+
+#### 16. regenerate_accurate_docs
+**功能**：使用深度Props链解析，批量生成或更新组件的准确Props文档（含类型、必填、继承链、透传详情）。已有文档会智能合并保留手写独有内容。
+**参数**：
+- `componentName` (string, optional): 指定组件名，只生成该组件的文档
+- `layer` (enum, optional): 指定层级，生成该层级所有组件的文档，可选值：other、cover、wrapper、pro-package
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请重新生成 Query 组件的准确 Props 文档。
+```
+
+```
+请批量生成 other 层级所有组件的准确 Props 文档。
+```
+
+### 缓存管理工具
+
+#### 17. refresh_component_docs
+**功能**：刷新 Ant Design / ProComponents 组件文档缓存，从本地类型定义和官方文档站重新获取
+**参数**：
+- `source` (enum, optional, default: "all"): 刷新来源，可选值：antd、pro-components、all
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请刷新所有组件文档缓存。
+```
+
+### 设计稿图片分析工具（兜底/代理）
+
+> **核心定位**：此工具是**兜底机制**，专门解决"用户使用的 LLM 不支持图片理解"的问题。
+>
+> 当用户的 IDE/AI 是纯文本模型（无法直接看设计稿截图）时，由 MCP 服务器调用多模态模型代为"看图"，将图片内容转化为结构化文本返回给用户 LLM，让用户 LLM 基于文字描述生成代码。如果用户的 LLM 本身支持图片输入（如 Claude 4、GPT-4o），则**不需要**使用此工具。
+
+#### 18. 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 覆盖代码
+
+**降级机制**：
+- 服务器上的多模态模型（Claude/OpenAI）不可用时，自动降级为本地 PaddleOCR 文字识别
+- OCR 降级模式下**不做任何组件推断**，仅返回识别到的原始文字，由用户 LLM 结合组件库 MCP 工具自行映射
+- 可通过环境变量 `DESIGN_ANALYSIS_ORDER` 控制执行顺序（见下方环境变量说明）
+
+**参数**：
+- `imageSource` (string, required): 图片数据：base64编码字符串、HTTP/HTTPS URL、或相对于项目根目录的文件路径
+- `sourceType` (enum, optional, default: "file_path"): 图片来源类型：base64、url、file_path
+
+> **远程连接场景下的图片传递方式说明**：
+> - 当通过 **SSE/HTTP 远程连接** MCP 服务器时，`file_path` 方式**不可用**，因为远端服务器无法访问客户端本地文件系统
+> - **推荐方式**：`base64` — 将图片转为 base64 字符串直接传入，不受网络隔离影响，任何连接方式都可用
+> - **可选方式**：`url` — 要求图片可通过公网 URL 访问
+> - **本地直连**：`file_path` — 仅在本地 stdio 直连模式下可用
+
+- `analysisType` (enum, optional, default: "full"): 分析类型：
+  - `layout` — 仅布局结构
+  - `components` — 布局+组件识别
+  - `tokens` — 布局+组件+样式Token（通道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` — 一键输出完整还原代码（ConfigProvider + 组件级CSS + 全局CSS + 还原度评分）
+
+**输出内容**（以 `full` 或 `pixel_perfect` 模式为例）：
+- 页面类型和布局结构
+- 组件识别和 szcd 组件匹配
+- **designTokens** — 对齐 tokenConfig.json 的全局 Token（色阶、字号阶梯、间距阶梯、圆角、阴影等）
+- **componentStyleTokens** — 每个组件的 componentToken（如 Table.rowHoverBg、Button.colorPrimary 等）
+- **themeDiff** — 与 szcd 默认值的差异对比 + 可直接粘贴的 ConfigProvider 代码
+- **cssOverrides** — 组件级 CSS 覆盖（布局、伪元素、间距、边框、动画、字体等 token 无法覆盖的属性）
+- **visualDetails** — 渐变、滚动条、遮罩、状态变体等视觉细节（仅 pixel_perfect 模式）
+- **fidelityScore** — 还原度评分（0-100），含 Token 覆盖率、CSS 覆盖补充率、未覆盖场景清单
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请分析 docs/designs/user-list.png 这张设计稿，使用 pixel_perfect 模式，输出还原代码。
+```
+
+##### Trae CLI 调用示例
+```bash
+# 完整分析（通道1+2）
+trae -m 'Call MCP tool analyze_design_image with imageSource "docs/designs/user-list.png" sourceType "file_path" analysisType "full" pageContext "用户管理列表页" targetLibrary "szcd"' --tool-allowance '*:*'
+
+# 最高还原度（全部三通道）+ 一键输出还原代码
+trae -m 'Call MCP tool analyze_design_image with imageSource "docs/designs/user-list.png" sourceType "file_path" analysisType "pixel_perfect" outputFormat "restoration_code" pageContext "用户管理列表页" targetLibrary "szcd"' --tool-allowance '*:*'
+```
+
+### 样式注入指南工具
+
+#### 19. 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，父级穿不透
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请查询 Query 组件的样式注入方法。
+```
+
+```
+请查询 TemplateMode 和 Query 组件的样式注入指南，包括嵌套场景。
+```
+
+### Swagger 联调工具
+
+#### 20. swagger_fetch_apis
+**功能**：访问 Swagger 地址获取所有 API 内容。返回 API 分组（tags）、每个接口的路径/方法/参数/描述等信息，用于后续联调。支持 Basic Auth 鉴权。
+**参数**：
+- `swaggerUrl` (string, required): Swagger UI 地址，如 http://172.31.7.103:31689/dp-label/swagger-ui.html
+- `username` (string, optional, default: "admin"): 鉴权用户名
+- `password` (string, optional, default: ""): 鉴权密码
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请拉取 http://172.31.7.103:31689/dp-label/swagger-ui.html 的所有 API。
+```
+
+#### 21. swagger_test_api
+**功能**：对 Swagger 中获取的 API 进行联调测试。向目标接口发送请求并返回响应结果，用于验证接口可用性和调试。
+**参数**：
+- `url` (string, required): 完整请求地址，如 http://172.31.7.103:31689/dp-label/api/user/list
+- `method` (enum, optional, default: "GET"): HTTP 请求方法，可选值：GET、POST、PUT、DELETE、PATCH
+- `data` (object, optional, default: {}): 请求参数：GET/DELETE 为 query 参数，POST/PUT/PATCH 为请求体 JSON
+- `headers` (object, optional, default: {}): 自定义请求头，如 { "Authorization": "Bearer xxx" }
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请测试 POST http://172.31.7.103:31689/dp-label/api/user/list 接口，参数为 { "page": 1, "size": 10 }。
+```
+
+### CODING Issue 工具
+
+#### 22. coding_fetch_issue
+**功能**：获取 CODING Issue（缺陷/需求）详情。支持两种认证方式：1) Cookie 模式（推荐，从浏览器开发者工具复制 Cookie 字符串）；2) 账号密码模式（自动模拟登录流程）。如果已在 ~/.szcd-mcp-config.json 中配置了 CODING_BASE_URL 和 CODING_DEFAULT_PROJECT_ID，则 baseUrl 和 projectId 参数可省略。
+**参数**：
+- `issueCode` (string, required): Issue 编号，如 6249
+- `baseUrl` (string, optional): CODING 基础地址。若 ~/.szcd-mcp-config.json 中配置了 CODING_BASE_URL，可省略
+- `projectId` (string, optional): 项目 ID（数字）。若 ~/.szcd-mcp-config.json 中配置了 CODING_DEFAULT_PROJECT_ID，可省略
+- `cookies` (string, optional): 浏览器 Cookie 字符串（从开发者工具 Network 面板复制）。若提供则优先使用 Cookie 模式
+- `account` (string, optional): CODING 账号（邮箱）。与 password 同时提供时尝试自动登录
+- `password` (string, optional): CODING 密码。与 account 同时提供时尝试自动登录
+- `withDescriptionMarkup` (boolean, optional, default: true): 是否返回描述的富文本格式（HTML）
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请获取 CODING Issue 6249 的详情。
+```
+
+```
+请使用 Cookie 模式获取 CODING Issue 6249，Cookie 为 "session=xxx"。
+```
+
+#### 23. coding_config
+**功能**：查看或设置 CODING 默认配置（保存在 ~/.szcd-mcp-config.json 中）。设置后，coding_fetch_issue 工具可省略对应的参数。注意：cookies 和 password 为敏感信息，查看时会被脱敏显示。
+**参数**：
+- `action` (enum, optional, default: "get"): 操作类型
+  - `get` — 查看当前配置
+  - `set` — 设置配置
+  - `clear` — 清除配置
+- `baseUrl` (string, optional): CODING 基础地址，如 http://e-kjr1wok.coding.smartcitysz.work（set 时生效）
+- `projectId` (string, optional): 默认项目 ID（set 时生效）
+- `account` (string, optional): 默认账号（邮箱）（set 时生效）
+- `cookies` (string, optional): 浏览器 Cookie 字符串（set 时生效，敏感信息）
+- `password` (string, optional): CODING 密码（set 时生效，敏感信息）
+
+##### Claude Code / Qoder CLI 调用示例
+```
+请查看 CODING 配置。
+```
+
+```
+请设置 CODING 基础地址为 http://e-kjr1wok.coding.smartcitysz.work，项目 ID 为 123。
+```
+
+## 安装方式
+
+### 通过 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：Qoder CLI / Qwen Code Streamable HTTP 直连（推荐）**
+
+在 `~/.qoder/settings.json` 中配置：
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "httpUrl": "http://localhost:3456/mcp",
+      "timeout": 30000
+    }
+  }
+}
+```
+
+**方式3e：Qoder CLI / 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` |
+
+### CODING 配置
+
+| 变量 | 说明 | 默认值 | 示例 |
+|------|------|--------|------|
+| `CODING_BASE_URL` | CODING 基础地址 | `` | `http://e-kjr1wok.coding.smartcitysz.work` |
+| `CODING_DEFAULT_PROJECT_ID` | 默认项目 ID | `` | `123` |
+| `CODING_ACCOUNT` | 默认账号（邮箱） | `` | `user@example.com` |
+| `CODING_COOKIES` | 浏览器 Cookie（敏感） | `` | `session=xxx` |
+| `CODING_PASSWORD` | CODING 密码（敏感） | `` | `your-password` |
+
+### 视觉模型配置（设计稿分析功能必需）
+
+| 变量 | 说明 | 默认值 | 示例 |
+|------|------|--------|------|
+| `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. **AI助手自动选择合适的MCP工具**：AI助手会根据需求自动识别并调用对应的MCP工具
+3. **AI助手自动连接MCP服务器**：AI助手通过MCP协议连接到运行在MCP_SERVER_URL的服务器
+4. **MCP服务器执行查询**：服务器接收工具调用请求，执行相应的业务逻辑
+5. **返回结构化结果**：服务器返回JSON格式的结果，AI助手处理并呈现给用户
+
+## 注意事项
+
+- 所有路径都是相对于项目根目录的相对路径
+- 搜索示例时，结果可能会有重复或不相关的内容，需要用户自行筛选
+- 读取文件时，大文件可能会被截断，用户可以通过设置 maxChars 参数来调整
+- **需要确保 MCP 服务器正在运行，否则无法查询数据**
+- **服务器地址从环境变量或配置文件动态获取，无需硬编码**
+- **AI助手会自动处理MCP协议通信，用户无需手动调用API**
+- **设计稿分析功能需要配置视觉模型 API Key**，未配置时 analyze_design_image 工具会返回错误
+- **设计稿分析会调用外部多模态模型 API**，会产生额外费用（单张约 $0.03~0.05）
+- **设计稿分析结果会自动缓存 24 小时**，同一图片重复查询不会重复计费
+- **CODING Issue 工具需要配置 Cookie 或账号密码**，推荐使用 Cookie 模式
+- **CODING 敏感信息（cookies、password）查看时会被脱敏显示**
+
+## 故障排除
+
+### 连接失败
+
+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. 检查文件权限
+
+### CODING Issue 获取失败
+
+1. 检查 baseUrl 和 projectId 是否正确
+2. Cookie 可能已过期，需重新从浏览器复制
+3. 使用 coding_config 工具设置默认值，避免每次手动传参
+
+## 示例对话
+
+### 示例 1：获取架构概览
+
+**用户**：szcd 组件库的架构是什么样的？
+**助手**：让我为您查询 szcd 组件库的架构概览。
+
+[助手自动触发MCP工具调用：get_architecture_overview()]
+
+**助手**：szcd 组件库采用7层封装架构：
+1. Ant Design（基础层）
+2. Cover 层（封装层）
+3. Wrapper 层（业务包装层）
+4. ProPackages（高级封装层）
+5. 复合组件层
+6. 模板层（TreeQueryTable/QueryTabsTables等）
+7. AI 辅助层
+
+### 示例 2：搜索组件
+
+**用户**：搜索包含 "table" 的组件
+**助手**：让我在整个组件库中搜索包含 "table" 的组件。
+
+[助手自动触发MCP工具调用：search_all_components({"keyword": "table"})]
+
+**助手**：搜索到以下包含 "table" 的组件：
+- TableOrList（复合组件）
+- ProTable（ProComponents）
+- Table（Ant Design）
+
+### 示例 3：获取组件详情
+
+**用户**：获取 Query 组件的详情
+**助手**：让我使用 get_other_component 工具来获取 Query 组件的详细信息。
+
+[助手自动触发MCP工具调用：get_other_component({"name": "Query"})]
+
+**助手**：Query 组件的详细信息如下：
+- 实现文件：src/other/components/Query/index.tsx
+- 导出位置：src/other/components/index.js
+- 透传目标：Select、DatePicker、Input、ProFormText
+
+### 示例 4：查询组件依赖
+
+**用户**：TemplateMode 组件依赖了哪些 szcd 组件？
+**助手**：让我查询 TemplateMode 的依赖关系。
+
+[助手自动触发MCP工具调用：get_component_dependencies({"name": "TemplateMode", "direction": "depends-on"})]
+
+**助手**：TemplateMode 依赖以下 szcd 组件：
+- LeftTree（左侧树）
+- TableOrList（表格/列表）
+- Query（查询组件）
+- ProCard（布局卡片）
+
+### 示例 5：获取 CODING Issue
+
+**用户**：请获取 CODING Issue 6249 的详情
+**助手**：让我获取 CODING Issue 6249 的详细信息。
+
+[助手自动触发MCP工具调用：coding_fetch_issue({"issueCode": "6249"})]
+
+**助手**：Issue 6249 详情：
+- 标题：xxx
+- 类型：缺陷/需求
+- 优先级：高
+- 描述：...
+
+### 示例 6：Swagger 联调
+
+**用户**：请拉取 Swagger API 列表，地址是 http://172.31.7.103:31689/dp-label/swagger-ui.html
+**助手**：让我获取该 Swagger 地址的所有 API。
+
+[助手自动触发MCP工具调用：swagger_fetch_apis({"swaggerUrl": "http://172.31.7.103:31689/dp-label/swagger-ui.html"})]
+
+**助手**：共获取到 xx 个 API 分组，yy 个接口...
+
+### 示例 7：读取文件内容
+
+**用户**：查看 Query 组件的实现代码
+**助手**：让我使用 read_file 工具来读取 Query 组件的实现文件。
+
+[助手自动触发MCP工具调用：read_file({"path": "src/other/components/Query/index.tsx"})]
+
+**助手**：Query 组件的实现代码如下：
+```tsx
+// 这里显示 src/other/components/Query/index.tsx 的内容
+```
+
+### 示例 8：分析设计稿
+
+**用户**：请分析 docs/designs/user-list.png 这张设计稿
+**助手**：让我使用 analyze_design_image 工具来分析这张设计稿。
+
+[助手自动触发MCP工具调用：analyze_design_image({"imageSource": "docs/designs/user-list.png", "analysisType": "full", "targetLibrary": "szcd"})]
+
+**助手**：设计稿分析结果如下：
+- 页面类型：列表页（带左侧树形导航）
+- 推荐组件：Query + LeftTree + TableOrList
+- 样式Token差异：...
+- CSS覆盖建议：...
+
+## AI助手与MCP服务交互详解
+
+### 调用机制
+
+AI助手通过 MCP 协议（Streamable HTTP 或 stdio）连接到 MCP 服务器。AI助手会根据用户自然语言请求自动识别并调用适当的MCP工具。
+
+### 调用流程
+
+当用户提出需求时，AI助手会：
+
+1. **理解用户意图**：分析用户想要获取的信息类型
+2. **选择适当工具**：从 MCP 服务器提供的工具中选择最合适的
+3. **构建参数**：根据用户输入构建工具调用所需的参数
+4. **发起 MCP 调用**：通过 MCP 协议发送工具调用请求到服务器
+5. **处理响应**：接收服务器返回的 JSON 格式结果
+6. **格式化输出**：将结果以易读的方式呈现给用户