first commit
This commit is contained in:
nasir@endelospay.com
307
docs/ARCHITECTURE_zh.md
Normal file
307
docs/ARCHITECTURE_zh.md
Normal file
@@ -0,0 +1,307 @@
|
||||
# Chrome MCP Server 架构设计 🏗️
|
||||
|
||||
本文档提供 Chrome MCP Server 架构、设计决策和实现细节的详细技术概述。
|
||||
|
||||
## 📋 目录
|
||||
|
||||
- [概述](#概述)
|
||||
- [系统架构](#系统架构)
|
||||
- [组件详情](#组件详情)
|
||||
- [数据流](#数据流)
|
||||
- [AI 集成](#ai-集成)
|
||||
- [性能优化](#性能优化)
|
||||
- [安全考虑](#安全考虑)
|
||||
|
||||
## 🎯 概述
|
||||
|
||||
Chrome MCP Server 是一个复杂的浏览器自动化平台，通过模型上下文协议 (MCP) 将 AI 助手与 Chrome 浏览器功能连接起来。架构设计目标：
|
||||
|
||||
- **高性能**：SIMD 优化的 AI 操作和高效的原生消息传递
|
||||
- **可扩展性**：模块化工具系统，便于添加新功能
|
||||
- **可靠性**：强大的错误处理和优雅降级
|
||||
- **安全性**：沙盒执行和基于权限的访问控制
|
||||
|
||||
## 🏗️ 系统架构
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "AI 助手层"
|
||||
A[Claude Desktop]
|
||||
B[自定义 MCP 客户端]
|
||||
C[其他 AI 工具]
|
||||
end
|
||||
|
||||
subgraph "MCP 协议层"
|
||||
D[HTTP/SSE 传输]
|
||||
E[MCP 服务器实例]
|
||||
F[工具注册表]
|
||||
end
|
||||
|
||||
subgraph "原生服务器层"
|
||||
G[Fastify HTTP 服务器]
|
||||
H[原生消息主机]
|
||||
I[会话管理]
|
||||
end
|
||||
|
||||
subgraph "Chrome 扩展层"
|
||||
J[后台脚本]
|
||||
K[内容脚本]
|
||||
L[弹窗界面]
|
||||
M[离屏文档]
|
||||
end
|
||||
|
||||
subgraph "浏览器 APIs 层"
|
||||
N[Chrome APIs]
|
||||
O[Web APIs]
|
||||
P[原生消息]
|
||||
end
|
||||
|
||||
subgraph "AI 处理层"
|
||||
Q[语义引擎]
|
||||
R[向量数据库]
|
||||
S[SIMD 数学引擎]
|
||||
T[Web Workers]
|
||||
end
|
||||
|
||||
A --> D
|
||||
B --> D
|
||||
C --> D
|
||||
D --> E
|
||||
E --> F
|
||||
F --> G
|
||||
G --> H
|
||||
H --> P
|
||||
P --> J
|
||||
J --> K
|
||||
J --> L
|
||||
J --> M
|
||||
J --> N
|
||||
J --> O
|
||||
J --> Q
|
||||
Q --> R
|
||||
Q --> S
|
||||
Q --> T
|
||||
```
|
||||
|
||||
## 🔧 组件详情
|
||||
|
||||
### 1. 原生服务器 (`app/native-server/`)
|
||||
|
||||
**目的**：MCP 协议实现和原生消息桥接
|
||||
|
||||
**核心组件**：
|
||||
|
||||
- **Fastify HTTP 服务器**：处理基于 HTTP/SSE 的 MCP 协议
|
||||
- **原生消息主机**：与 Chrome 扩展通信
|
||||
- **会话管理**：管理多个 MCP 客户端会话
|
||||
- **工具注册表**：将工具调用路由到 Chrome 扩展
|
||||
|
||||
**技术栈**：
|
||||
|
||||
- TypeScript + Fastify
|
||||
- MCP SDK (@modelcontextprotocol/sdk)
|
||||
- 原生消息协议
|
||||
|
||||
### 2. Chrome 扩展 (`app/chrome-extension/`)
|
||||
|
||||
**目的**：浏览器自动化和 AI 驱动的内容分析
|
||||
|
||||
**核心组件**：
|
||||
|
||||
- **后台脚本**：主要协调器和工具执行器
|
||||
- **内容脚本**：页面交互和内容提取
|
||||
- **弹窗界面**：用户配置和状态显示
|
||||
- **离屏文档**：在隔离环境中进行 AI 模型处理
|
||||
|
||||
**技术栈**：
|
||||
|
||||
- WXT 框架 + Vue 3
|
||||
- Chrome 扩展 APIs
|
||||
- WebAssembly + SIMD
|
||||
- Transformers.js
|
||||
|
||||
### 3. 共享包 (`packages/`)
|
||||
|
||||
#### 3.1 共享类型 (`packages/shared/`)
|
||||
|
||||
- 工具模式和类型定义
|
||||
- 通用接口和工具
|
||||
- MCP 协议类型
|
||||
|
||||
#### 3.2 WASM SIMD (`packages/wasm-simd/`)
|
||||
|
||||
- 基于 Rust 的 SIMD 优化数学函数
|
||||
- 使用 Emscripten 编译 WebAssembly
|
||||
- 向量运算性能提升 4-8 倍
|
||||
|
||||
## 🔄 数据流
|
||||
|
||||
### 工具执行流程
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ ┌──────────────┐
|
||||
│ AI 助手 │ │ 原生服务器 │ │ Chrome 扩展 │ │ 浏览器 APIs │
|
||||
└─────┬───────┘ └──────┬───────┘ └─────────┬───────┘ └──────┬───────┘
|
||||
│ │ │ │
|
||||
│ 1. 工具调用 │ │ │
|
||||
├──────────────────►│ │ │
|
||||
│ │ 2. 原生消息 │ │
|
||||
│ ├─────────────────────►│ │
|
||||
│ │ │ 3. 执行工具 │
|
||||
│ │ ├──────────────────►│
|
||||
│ │ │ 4. API 响应 │
|
||||
│ │ │◄──────────────────┤
|
||||
│ │ 5. 工具结果 │ │
|
||||
│ │◄─────────────────────┤ │
|
||||
│ 6. MCP 响应 │ │ │
|
||||
│◄──────────────────┤ │ │
|
||||
```
|
||||
|
||||
### AI 处理流程
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ ┌──────────────┐
|
||||
│ 内容提取 │ │ 文本分块器 │ │ 语义引擎 │ │ 向量数据库 │
|
||||
└─────┬───────┘ └──────┬───────┘ └─────────┬───────┘ └──────┬───────┘
|
||||
│ │ │ │
|
||||
│ 1. 原始内容 │ │ │
|
||||
├──────────────────►│ │ │
|
||||
│ │ 2. 文本块 │ │
|
||||
│ ├─────────────────────►│ │
|
||||
│ │ │ 3. 嵌入向量 │
|
||||
│ │ ├──────────────────►│
|
||||
│ │ │ │
|
||||
│ │ 4. 搜索查询 │ │
|
||||
│ ├─────────────────────►│ │
|
||||
│ │ │ 5. 查询向量 │
|
||||
│ │ ├──────────────────►│
|
||||
│ │ │ 6. 相似文档 │
|
||||
│ │ │◄──────────────────┤
|
||||
│ │ 7. 搜索结果 │ │
|
||||
│ │◄─────────────────────┤ │
|
||||
```
|
||||
|
||||
## 🧠 AI 集成
|
||||
|
||||
### 语义相似度引擎
|
||||
|
||||
**架构**：
|
||||
|
||||
- **模型支持**：BGE-small-en-v1.5、E5-small-v2、Universal Sentence Encoder
|
||||
- **执行环境**：Web Workers 用于非阻塞处理
|
||||
- **优化**：向量运算的 SIMD 加速
|
||||
- **缓存**：嵌入和分词的 LRU 缓存
|
||||
|
||||
**性能优化**：
|
||||
|
||||
```typescript
|
||||
// SIMD 加速的余弦相似度
|
||||
const similarity = await simdMath.cosineSimilarity(vecA, vecB);
|
||||
|
||||
// 批处理提高效率
|
||||
const similarities = await simdMath.batchSimilarity(vectors, query, dimension);
|
||||
|
||||
// 内存高效的矩阵运算
|
||||
const matrix = await simdMath.similarityMatrix(vectorsA, vectorsB, dimension);
|
||||
```
|
||||
|
||||
### 向量数据库 (hnswlib-wasm)
|
||||
|
||||
**特性**：
|
||||
|
||||
- **算法**：分层导航小世界 (HNSW)
|
||||
- **实现**：WebAssembly 实现接近原生性能
|
||||
- **持久化**：IndexedDB 存储，自动清理
|
||||
- **可扩展性**：高效处理 10,000+ 文档
|
||||
|
||||
**配置**：
|
||||
|
||||
```typescript
|
||||
const config: VectorDatabaseConfig = {
|
||||
dimension: 384, // 模型嵌入维度
|
||||
maxElements: 10000, // 最大文档数
|
||||
efConstruction: 200, // 构建时精度
|
||||
M: 16, // 连接参数
|
||||
efSearch: 100, // 搜索时精度
|
||||
enableAutoCleanup: true, // 自动清理旧数据
|
||||
maxRetentionDays: 30, // 数据保留期
|
||||
};
|
||||
```
|
||||
|
||||
## ⚡ 性能优化
|
||||
|
||||
### 1. SIMD 加速
|
||||
|
||||
**Rust 实现**：
|
||||
|
||||
```rust
|
||||
use wide::f32x4;
|
||||
|
||||
fn cosine_similarity_simd(&self, vec_a: &[f32], vec_b: &[f32]) -> f32 {
|
||||
let len = vec_a.len();
|
||||
let simd_lanes = 4;
|
||||
let simd_len = len - (len % simd_lanes);
|
||||
|
||||
let mut dot_sum_simd = f32x4::ZERO;
|
||||
let mut norm_a_sum_simd = f32x4::ZERO;
|
||||
let mut norm_b_sum_simd = f32x4::ZERO;
|
||||
|
||||
for i in (0..simd_len).step_by(simd_lanes) {
|
||||
let a_chunk = f32x4::new(vec_a[i..i+4].try_into().unwrap());
|
||||
let b_chunk = f32x4::new(vec_b[i..i+4].try_into().unwrap());
|
||||
|
||||
dot_sum_simd = a_chunk.mul_add(b_chunk, dot_sum_simd);
|
||||
norm_a_sum_simd = a_chunk.mul_add(a_chunk, norm_a_sum_simd);
|
||||
norm_b_sum_simd = b_chunk.mul_add(b_chunk, norm_b_sum_simd);
|
||||
}
|
||||
|
||||
// 计算最终相似度
|
||||
let dot_product = dot_sum_simd.reduce_add();
|
||||
let norm_a = norm_a_sum_simd.reduce_add().sqrt();
|
||||
let norm_b = norm_b_sum_simd.reduce_add().sqrt();
|
||||
|
||||
dot_product / (norm_a * norm_b)
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 内存管理
|
||||
|
||||
**策略**：
|
||||
|
||||
- **对象池**：重用 Float32Array 缓冲区
|
||||
- **延迟加载**：按需加载 AI 模型
|
||||
- **缓存管理**：嵌入的 LRU 淘汰
|
||||
- **垃圾回收**：显式清理大对象
|
||||
|
||||
### 3. 并发处理
|
||||
|
||||
**Web Workers**：
|
||||
|
||||
- **AI 处理**：模型推理的独立 worker
|
||||
- **内容索引**：后台标签页内容索引
|
||||
- **网络捕获**：并行请求处理
|
||||
|
||||
## 🔧 扩展点
|
||||
|
||||
### 添加新工具
|
||||
|
||||
1. **定义模式** 在 `packages/shared/src/tools.ts`
|
||||
2. **实现工具** 继承 `BaseBrowserToolExecutor`
|
||||
3. **注册工具** 在工具索引中
|
||||
4. **添加测试** 用于功能测试
|
||||
|
||||
### 自定义 AI 模型
|
||||
|
||||
1. **模型集成** 在 `SemanticSimilarityEngine`
|
||||
2. **Worker 支持** 用于处理
|
||||
3. **配置** 在模型预设中
|
||||
4. **性能测试** 使用基准测试
|
||||
|
||||
### 协议扩展
|
||||
|
||||
1. **MCP 扩展** 用于自定义功能
|
||||
2. **传输层** 用于不同通信方法
|
||||
3. **身份验证** 用于安全连接
|
||||
4. **监控** 用于性能指标
|
||||
|
||||
此架构使 Chrome MCP Server 能够在保持安全性和可扩展性的同时，提供高性能的浏览器自动化和先进的 AI 功能。
|
||||
Reference in New Issue
Block a user