---
description:
globs:
alwaysApply: false
---
# 聚义厅MCP系统架构指南
## 整体架构设计
### 三层架构模式
```
┌─────────────────────────────────────────┐
│ MCP客户端环境 │
│ ┌─────────────────────────────────────┐ │
│ │ Cursor/Claude Desktop │ │
│ └─────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────┐ │
│ │ MCP协议层 │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 聚义厅MCP服务器 │
│ ┌─────────────┬─────────────┬─────────┐ │
│ │工具接口层 │人格管理器 │协作引擎 │ │
│ └─────────────┴─────────────┴─────────┘ │
│ ┌─────────────┬─────────────┬─────────┐ │
│ │配置同步器 │本地人格仓库 │遥测模块 │ │
│ └─────────────┴─────────────┴─────────┘ │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 数据层 │
│ ┌─────────────┬─────────────┬─────────┐ │
│ │本地配置文件 │远程人格源 │API接口 │ │
│ └─────────────┴─────────────┴─────────┘ │
└─────────────────────────────────────────┘
```
## 核心组件设计
### 1. PersonaSummonerServer (主服务器)
**职责**: MCP服务器主入口，协调各组件工作
**关键方法**:
- `setupHandlers()`: 注册MCP工具处理器
- `handleListTools()`: 列出可用工具
- `handleCallTool()`: 处理工具调用
### 2. RemotePersonaRepository (人格仓库)
**职责**: 管理人格数据的获取、缓存和合并
**核心特性**:
- 多源数据获取策略
- 智能缓存机制（5分钟TTL）
- 本地人格优先级覆盖
- 优雅降级到默认人格
### 3. CollaborationEngine (协作引擎)
**职责**: 执行多人格协作分析
**协作模式**:
- `PARALLEL`: 并行分析模式
- `SEQUENTIAL`: 顺序分析模式
- `INTELLIGENT`: 智能协作模式
### 4. ConfigSynchronizer (配置同步器)
**职责**: 处理远程配置同步和本地存储
**功能**:
- 远程配置下载
- 本地配置管理
- 自动同步检查
- 配置完整性验证
## MCP工具接口设计
### 工具注册模式
```typescript
private setupHandlers() {
this.server.setRequestHandler(ListToolsRequestSchema, async () => {
return { tools: [...] };
});
this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
switch (name) {
case 'summon_persona': return await this.handleSummonPersona(args);
case 'list_persona_configs': return await this.handleListPersonaConfigs(args);
case 'download_persona_config': return await this.handleDownloadPersonaConfig(args);
case 'start_collaboration': return await this.handleStartCollaboration(args);
}
});
}
```
### 标准响应格式
所有工具返回统一格式：
```typescript
{
content: [{
type: 'text',
text: string
}]
}
```
## 数据流设计
### 人格数据流
1. **多源获取**: GitHub → Gitee → CDN镜像
2. **缓存策略**: 内存缓存 + TTL机制
3. **合并逻辑**: 本地 > 远程 > 默认
4. **验证检查**: 必填字段验证
### 配置同步流
1. **权限验证**: userKey验证
2. **配置下载**: 完整配置获取
3. **完整性检查**: 字段和格式验证
4. **本地存储**: ~/.juyiting/config.json
### 协作执行流
1. **人格选择**: 智能算法或指定列表
2. **并行分析**: Promise.all执行
3. **交叉验证**: 结果互相验证
4. **结果综合**: 生成最终分析
## 性能优化策略
### 缓存机制
- **人格缓存**: 5分钟内存缓存
- **配置缓存**: 本地文件持久化
- **LRU策略**: 最大1000条缓存
### 请求优化
- **请求去重**: 相同请求合并
- **批量处理**: 并发控制
- **超时控制**: 15秒网络超时
### 错误处理
- **优雅降级**: 远程失败使用默认
- **重试机制**: 网络请求重试
- **错误上报**: 遥测数据收集
## 扩展性设计
### 插件化人格管理
- 支持自定义人格源
- 动态人格加载
- 人格版本管理
### 模块化协作引擎
- 可扩展协作模式
- 自定义分析流程
- 结果格式化插件
### 开放配置格式
- JSON Schema验证
- 向后兼容性
- 配置迁移支持
