exploria-ui-mcp-server 2.2.5 → 2.2.7

package/README.md

@@ -24,31 +24,7 @@ Exploria UI 是一套现代化、高性能的 UI 组件库，专注于提供优
 - **可定制性**：支持主题定制和样式覆盖
 - **高性能**：优化渲染性能，确保流畅的交互体验
 
-### 2.2 核心组件类别
-
-Exploria UI 组件库包含丰富的组件，按功能分为以下几类：
-
-| 类别         | 描述                     | 示例组件                 |
-| ------------ | ------------------------ | ------------------------ |
-| 基础组件     | 构建 UI 的基础元素       | Button, Input, Icon      |
-| 布局组件     | 用于页面布局的组件       | Layout, Grid, Space      |
-| 表单组件     | 用于数据收集和验证的组件 | Form, Select, DatePicker |
-| 数据展示组件 | 用于展示数据的组件       | Table, List, Card        |
-| 反馈组件     | 用于用户反馈的组件       | Modal, Message, Loading  |
-| 导航组件     | 用于页面导航的组件       | Menu, Tabs, Breadcrumb   |
-| 高级组件     | 复杂功能的组合组件       | Pagination, Upload, Tree |
-| AI 相关组件  | 集成 AI 功能的组件       | AI Assistant, Chatbot    |
-
-### 2.3 文档体系
-
-Exploria UI 拥有完整的文档体系，包括：
-
-- **组件文档**：详细的组件使用说明、属性列表、事件和插槽
-- **API 文档**：完整的 API 参考
-- **使用示例**：丰富的代码示例和最佳实践
-- **设计指南**：设计原则和样式规范
-
-## 3. MCP Server 核心架构
+## 核心架构
 
 ### 3.1 架构定位
 
@@ -76,12 +52,10 @@ MCP Server 启动时会注册三类核心模块：
     - 提供 AI IDE 可调用的各种工具函数
     - 包括文档搜索、组件列表获取、组件详情查询等功能
     - 注册入口：`./tools/index.js`
-
 2. **资源模块 (Resources)**
     - 提供项目相关的资源支持
     - 包括服务器状态、API 文档、组件清单等
     - 注册入口：`./resources/index.js`
-
 3. **提示模块 (Prompts)**
     - 提供指导 AI 模型生成更准确响应的提示模板
     - 包括组件文档模板生成、使用示例生成等
@@ -148,7 +122,273 @@ MCP Server 启动时会注册三类核心模块：
 4. 同时将项目根目录的 README.md 复制到 `mcp-server/dist/public/README.md`
 5. 最终构建产物包含完整的 MCP Server 实现和所需的知识文件
 
-### 6.2 NPM 包结构
+### 6.2 向量数据库构建过程
+
+#### 6.2.1 构建模式
+
+系统采用单一构建模式：**预构建模式（Prebuild）**，在项目打包时统一构建向量数据库，确保服务启动时直接加载预计算的索引，实现最快的启动速度和查询性能。
+
+#### 6.2.2 构建流程详解
+
+**阶段一：文档收集与解析**
+
+```
+文档源目录 (docsRoot)
+       │
+       ▼
+┌─────────────────────┐
+│  collectDocumentRoots│  ← 递归扫描目录，识别文档根目录（含 Document.vue/intro.md）
+└─────────────────────┘
+       │
+       ▼
+┌─────────────────────┐
+│  collectSourceFiles │  ← 收集所有文本文件（.md, .vue, .ts, .js）
+└─────────────────────┘
+       │
+       ▼
+┌─────────────────────┐
+│  sortSourceFiles    │  ← 按优先级排序（document > example > source）
+└─────────────────────┘
+```
+
+**阶段二：文档结构化**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    buildKnowledgeDocuments                   │
+├─────────────────────────────────────────────────────────────┤
+│  1. 提取文档内容        → documentContent                   │
+│  2. 解析组件属性        → props (name, type, default, desc) │
+│  3. 解析事件定义        → events (name, description)        │
+│  4. 解析插槽定义        → slots (name, description, default)│
+│  5. 提取代码示例        → examples (title, code)            │
+│  6. 构建别名索引        → aliases                          │
+│  7. 生成关键词          → keywords                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**阶段三：文本切块与向量化**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    buildKnowledgeArtifact                    │
+├─────────────────────────────────────────────────────────────┤
+│  1. splitIntoChunks    → 将文档切分为 512 字符的块           │
+│  2. tokenize           → 分词处理                           │
+│  3. 计算 IDF 权重      → 基于文档频率的逆文档频率            │
+│  4. 计算 TF-IDF        → 词频-逆文档频率权重                 │
+│  5. buildVector        → 生成 256 维向量                     │
+│     └─ 使用 FNV-1a 哈希将 token 映射到向量维度               │
+│     └─ 主哈希 + 次哈希双位置映射                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**阶段四：索引构建**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      生成 VectorDbArtifact                   │
+├─────────────────────────────────────────────────────────────┤
+│  ┌───────────┐    ┌───────────┐    ┌───────────┐           │
+│  │ documents │    │   chunks  │    │  idfMap   │           │
+│  │ (文档元数据)│    │ (向量块)  │    │ (IDF映射) │           │
+│  └───────────┘    └───────────┘    └───────────┘           │
+│         │                │                │                  │
+│         ▼                ▼                ▼                  │
+│  ┌───────────────────────────────────────────┐              │
+│  │          持久化到 vector-db.json          │              │
+│  └───────────────────────────────────────────┘              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### 6.2.3 向量生成算法
+
+本项目采用 **TF-IDF + 哈希向量化** 的轻量级方案：
+
+```
+TF-IDF 权重计算:
+weight(token) = (1 + log(frequency)) * log((totalChunks + 1) / (documentFrequency + 1))
+
+向量生成:
+vector[primaryIndex] += weight
+vector[secondaryIndex] -= weight * 0.5
+
+其中:
+- primaryIndex = FNV-1a(token) % 256
+- secondaryIndex = FNV-1a(token:secondary) % 256
+```
+
+**设计优势**：
+
+- 无需外部向量模型依赖，零运行时开销
+- 256 维向量，内存占用小
+- 支持快速构建和查询
+- 可重现性强，相同输入产生相同向量
+
+### 6.3 MCP Server 实现架构
+
+#### 6.3.1 整体架构
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│                        AI IDE (Cursor/Trae)                   │
+│                          ▲                                   │
+│                          │ StdioServerTransport              │
+│                          │ (标准输入输出管道)                 │
+│                          ▼                                   │
+│  ┌─────────────────────────────────────────────────────┐      │
+│  │              ExploriaUIMCPServer                    │      │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │      │
+│  │  │   Tools     │  │  Resources  │  │   Prompts   │ │      │
+│  │  │ (工具注册)   │  │  (资源注册) │  │  (提示注册) │ │      │
+│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘ │      │
+│  │         │                │                │         │      │
+│  │         └────────────────┼────────────────┘         │      │
+│  │                          ▼                         │      │
+│  │              ┌─────────────────────┐               │      │
+│  │              │   KnowledgeService  │               │      │
+│  │              │   (向量数据库服务)   │               │      │
+│  │              └───────────┬─────────┘               │      │
+│  │                          │                         │      │
+│  │                          ▼                         │      │
+│  │              ┌─────────────────────┐               │      │
+│  │              │   VectorDbArtifact  │               │      │
+│  │              │   (向量索引数据)     │               │      │
+│  │              └─────────────────────┘               │      │
+│  └─────────────────────────────────────────────────────┘      │
+└───────────────────────────────────────────────────────────────┘
+```
+
+#### 6.3.2 核心组件职责
+
+| 组件                     | 职责                     | 关键方法/属性                                 |
+| ------------------------ | ------------------------ | --------------------------------------------- |
+| **ExploriaUIMCPServer**  | 主服务器类，管理生命周期 | `start()`, `shutdown()`, `initializeServer()` |
+| **McpServer**            | MCP SDK 核心实例         | 处理协议通信、注册工具/资源/提示              |
+| **StdioServerTransport** | 标准输入输出传输层       | 建立与 IDE 的管道连接                         |
+| **KnowledgeService**     | 向量数据库服务           | `searchKnowledge()`, `getComponentDetails()`  |
+| **DocumentParser**       | 文档解析器               | `initialize()`, `getStatus()`                 |
+
+#### 6.3.3 服务启动流程
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     启动流程                                 │
+├─────────────────────────────────────────────────────────────┤
+│  1. loadPackageJson()     → 加载 package.json 配置         │
+│           │                                                │
+│           ▼                                                │
+│  2. setupEventHandlers()  → 设置信号处理 (SIGINT/SIGTERM)  │
+│           │                                                │
+│           ▼                                                │
+│  3. initializeServer()    → 初始化知识索引                  │
+│           │                                                │
+│           ├─→ docParser.initialize()                       │
+│           │      └─ 加载预构建向量索引                      │
+│           │                                                │
+│           ├─→ new McpServer({name, version, description}) │
+│           │                                                │
+│           ├─→ registerTools()                              │
+│           ├─→ registerResources()                         │
+│           └─→ registerPrompts()                            │
+│           │                                                │
+│           ▼                                                │
+│  4. server.connect(transport) → 建立连接                   │
+│           │                                                │
+│           ▼                                                │
+│  5. 等待 AI IDE 连接请求...                                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### 6.3.4 搜索流程（混合检索）
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    搜索流程 (Hybrid Search)                 │
+├─────────────────────────────────────────────────────────────┤
+│  输入: query = "button"                                    │
+│           │                                                │
+│           ▼                                                │
+│  1. normalizePlainText()   → 文本规范化                    │
+│  2. expandQueryTerms()     → 扩展查询词                    │
+│  3. buildQueryVector()     → 生成查询向量                  │
+│           │                                                │
+│           ▼                                                │
+│  ┌─────────────────┬─────────────────┐                    │
+│  │   Fulltext      │    Semantic     │                    │
+│  │   (全文检索)    │    (语义检索)   │                    │
+│  └────────┬────────┴────────┬────────┘                    │
+│           │                 │                             │
+│           ▼                 ▼                             │
+│  alias匹配(+8)        cosineSimilarity()                 │
+│  partial匹配(+4)      计算向量相似度                      │
+│  keyword匹配(+1.5)                                        │
+│  content匹配(+1)                                          │
+│           │                 │                             │
+│           └────────┬────────┘                             │
+│                    ▼                                      │
+│  4. 混合评分: fulltext * 0.55 + semantic * 0.45          │
+│           │                                                │
+│           ▼                                                │
+│  5. 排序 → 过滤(score > 0) → 截取前N条 → 返回结果         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### 6.3.5 索引结构
+
+**VectorDbArtifact 数据结构**：
+
+```typescript
+interface VectorDbArtifact {
+    version: number; // 版本号
+    generatedAt: string; // 生成时间
+    docsRoot: string; // 文档根目录
+    buildMode: string; // 构建模式
+    idfMap: Record<string, number>; // IDF 映射表
+    documents: KnowledgeDocument[]; // 文档列表
+    chunks: KnowledgeChunk[]; // 向量块列表
+    metrics: {
+        buildTimeMs: number; // 构建耗时
+        documentCount: number; // 文档数
+        chunkCount: number; // 切块数
+        averageChunkLength: number; // 平均切块长度
+        vectorDimension: number; // 向量维度
+    };
+}
+```
+
+**KnowledgeChunk 结构**：
+
+```typescript
+interface KnowledgeChunk {
+    id: string; // 唯一标识 (documentId#order)
+    documentId: string; // 所属文档ID
+    order: number; // 块顺序
+    text: string; // 文本内容
+    vector: number[]; // 256维向量
+}
+```
+
+#### 6.3.6 缓存机制
+
+KnowledgeService 实现了两级缓存：
+
+| 缓存类型       | 存储内容            | TTL          | 最大容量 |
+| -------------- | ------------------- | ------------ | -------- |
+| **搜索缓存**   | 查询结果            | 60s          | 200 条   |
+| **文档块映射** | documentId → chunks | 服务生命周期 | 无限制   |
+| **别名索引**   | alias → document    | 服务生命周期 | 无限制   |
+
+#### 6.3.7 性能特性
+
+| 指标     | 典型值   | 说明             |
+| -------- | -------- | ---------------- |
+| 向量维度 | 256      | 平衡精度与性能   |
+| 切块大小 | 512 字符 | 兼顾上下文完整性 |
+| 搜索延迟 | < 100ms  | 本地向量计算     |
+| 内存占用 | < 50MB   | 典型组件库规模   |
+
+### 6.4 NPM 包结构
 
 当项目打包完成并上传至 NPM 仓库后，生成的 NPM 包包含以下目录和文件结构：
 
@@ -163,7 +403,7 @@ mcp-server/
 └── README.md
 ```
 
-### 6.3 项目结构
+### 6.5 项目结构
 
 ```
 src/
@@ -187,7 +427,7 @@ src/
     └── documentParser.ts # 文档解析器
 ```
 
-### 6.4 技术栈
+### 6.6 技术栈
 
 | 技术                        | 用途                     |
 | --------------------------- | ------------------------ |
@@ -208,12 +448,10 @@ MCP Server 与 AI IDE 之间支持三种传输协议：
     - 通过管道传输数据，安全可靠
     - 由 AI 客户端自动启动、管理和停止
     - 本项目采用此协议作为主要通信方式
-
 2. **Server-Sent Events (SSE)**
     - 基于 HTTP 的单向实时通信协议
     - 适合服务器向客户端推送数据的场景
     - 支持事件驱动的通信模式
-
 3. **流式 HTTP (Streaming HTTP)**
     - 基于 HTTP 长连接的双向通信
     - 支持服务器和客户端之间的连续数据传输
@@ -247,11 +485,9 @@ npx -y @modelcontextprotocol/inspector node dist/index.js
     - 确保已正确构建项目：`pnpm run build`
     - 检查当前工作目录，确保在正确的位置运行命令
     - 查看控制台输出的错误信息，针对性解决
-
 2. **JSON 解析错误**：
     - 确保所有日志输出已重定向到 stderr（本项目已自动处理）
     - 检查是否有其他进程占用了 stdio
-
 3. **文档未找到**：
     - 确保文档已正确复制到 `public` 目录
     - 检查 `docsRoot` 配置是否正确