# 工具管理与数据管理模块实现文档

## 📅 实现日期
2025年10月14日

## 📋 实现内容

### 1️⃣ 工具管理模块 (ToolsManager.vue)

#### ✅ 已实现功能

##### 核心功能
- **工具列表展示**
  - 卡片式网格布局
  - 显示工具名称、描述、端点、参数数量
  - 实时状态显示（已启用/已禁用）

- **工具 CRUD 操作**
  - ✅ 添加工具：弹窗表单，支持配置名称、端点、参数
  - ✅ 编辑工具：修改现有工具配置
  - ✅ 删除工具：删除不需要的工具
  - ✅ 启用/禁用工具：开关控制

- **工具测试**
  - 发送 HTTP POST 请求测试工具端点
  - 支持自定义测试参数（JSON 格式）
  - 显示测试结果和响应数据

- **数据持久化**
  - LocalStorage 存储（key: `mcp-tools`）
  - 自动保存和加载

- **其他功能**
  - 复制工具配置到剪贴板
  - 参数配置 JSON 编辑器
  - 表单验证

#### 🎨 UI 特性
- 响应式网格布局（每行最多 3 个卡片）
- 空状态提示
- 加载动画
- 成功/失败状态反馈
- Naive UI 组件集成

#### 📊 数据结构

```typescript
interface Tool {
  id: string                      // 唯一标识
  name: string                    // 工具名称（如: web_search）
  displayName?: string            // 显示名称（如: 网页搜索）
  description: string             // 工具描述
  endpoint: string                // API 端点地址
  parameters: Record<string, any> // 参数配置（JSON 对象）
  enabled: boolean                // 启用状态
  createdAt?: Date               // 创建时间
  updatedAt?: Date               // 更新时间
}
```

---

### 2️⃣ 数据管理模块 (DataManager.vue)

#### ✅ 已实现功能

##### 统计仪表板
- **4 个统计卡片**
  - 对话数量
  - 消息总数
  - 存储使用量（自动计算）
  - 最后活动时间

##### 对话历史管理
- **对话列表**
  - 显示所有对话历史
  - 显示消息数量和更新时间
  - 对话预览（最后一条消息）
  - 相对时间显示（刚刚、5分钟前、今天等）

- **搜索功能**
  - 搜索对话标题
  - 搜索消息内容
  - 实时过滤

- **对话操作**
  - ✅ 查看详情：弹窗显示完整对话内容
  - ✅ 导出对话：单个对话导出为 JSON
  - ✅ 删除对话：删除不需要的对话

##### 数据导出
- **全量导出**
  - 导出所有对话历史
  - 导出工具配置
  - 导出模型服务配置
  - 导出系统设置
  - 包含导出时间戳

##### 数据清理
- **选择性清理**
  - 对话历史
  - 工具配置
  - 模型服务
  - 系统设置
  - 清理前警告提示

#### 🎨 UI 特性
- 现代化卡片布局
- 统计数据可视化
- 消息气泡样式（用户/助手区分）
- 空状态提示
- 搜索框集成
- 确认对话框

#### 📊 数据结构

```typescript
interface Message {
  role: 'user' | 'assistant' | 'system'
  content: string
  timestamp: Date
}

interface Conversation {
  id: string
  title: string
  messages: Message[]
  createdAt: Date
  updatedAt: Date
}
```

---

## 🔧 技术栈

### 前端框架
- **Vue 3**: Composition API
- **TypeScript**: 类型安全
- **Naive UI**: UI 组件库

### 状态管理
- **LocalStorage**: 本地持久化
  - `mcp-tools`: 工具配置
  - `mcp-conversations`: 对话历史
  - `model-services`: 模型服务
  - `mcp-settings`: 系统设置

### 图标库
- **@vicons/tabler**: 图标组件

---

## 📁 文件结构

```
web/src/components/
├── ToolsManager.vue      # 工具管理组件（540 行）
├── DataManager.vue       # 数据管理组件（580 行）
└── SimpleApp.vue         # 主应用（已更新引用）
```

---

## 🚀 使用方法

### 工具管理

#### 添加工具
1. 点击「添加工具」按钮
2. 填写工具信息：
   - **工具名称**: 英文标识符（如 `web_search`）
   - **显示名称**: 中文名称（如 `网页搜索`）
   - **描述**: 工具功能说明
   - **端点地址**: API URL（如 `http://localhost:8080/api/search`）
   - **参数配置**: JSON 格式
   ```json
   {
     "query": {
       "type": "string",
       "description": "搜索关键词"
     },
     "max_results": {
       "type": "number",
       "description": "最大结果数",
       "default": 10
     }
   }
   ```
3. 点击「保存」

#### 测试工具
1. 点击工具卡片上的「测试工具」按钮
2. 输入测试参数：
   ```json
   {
     "query": "Vue 3 教程",
     "max_results": 5
   }
   ```
3. 点击「运行测试」
4. 查看响应结果

### 数据管理

#### 查看对话
1. 在对话列表中找到目标对话
2. 点击眼睛图标查看详情
3. 可以看到完整的消息历史

#### 导出数据
- **单个对话**: 点击下载图标导出 JSON
- **全部数据**: 点击顶部「导出数据」按钮

#### 清理数据
1. 点击「清理数据」按钮
2. 选择要清理的数据类型
3. 确认清理（⚠️ 不可恢复）

---

## 🎯 功能亮点

### 工具管理
- ✅ 完整的 CRUD 操作
- ✅ 实时测试功能
- ✅ JSON 参数配置
- ✅ 启用/禁用开关
- ✅ 配置导出复制

### 数据管理
- ✅ 统计仪表板
- ✅ 搜索过滤
- ✅ 对话详情查看
- ✅ 数据导出（单个/全量）
- ✅ 选择性清理
- ✅ 自动计算存储使用

---

## 📝 数据示例

### 示例工具配置

```json
{
  "id": "tool_1697123456789_abc123",
  "name": "web_search",
  "displayName": "网页搜索",
  "description": "搜索网页内容并返回结果",
  "endpoint": "http://localhost:8080/api/search",
  "parameters": {
    "query": {
      "type": "string",
      "description": "搜索关键词"
    }
  },
  "enabled": true,
  "createdAt": "2025-10-14T10:00:00.000Z",
  "updatedAt": "2025-10-14T10:00:00.000Z"
}
```

### 示例对话数据

```json
{
  "id": "conv_1697123456789_xyz789",
  "title": "Vue 3 学习讨论",
  "messages": [
    {
      "role": "user",
      "content": "Vue 3 的 Composition API 有什么优势？",
      "timestamp": "2025-10-14T10:00:00.000Z"
    },
    {
      "role": "assistant",
      "content": "Vue 3 的 Composition API 主要有以下优势...",
      "timestamp": "2025-10-14T10:00:05.000Z"
    }
  ],
  "createdAt": "2025-10-14T10:00:00.000Z",
  "updatedAt": "2025-10-14T10:00:05.000Z"
}
```

---

## 🔮 后续优化建议

### 工具管理
- [ ] 工具版本管理
- [ ] 工具依赖关系
- [ ] 工具市场/商店
- [ ] 批量导入工具
- [ ] 工具使用统计
- [ ] 工具权限管理
- [ ] WebSocket 测试支持

### 数据管理
- [ ] 向量数据库集成
- [ ] RAG 数据源配置
- [ ] 数据分析图表
- [ ] 自动备份功能
- [ ] 数据同步（云端）
- [ ] 高级搜索（正则、标签）
- [ ] 导入数据功能
- [ ] 对话标签分类

---

## 🐛 已知限制

1. **LocalStorage 容量限制**
   - 浏览器限制约 5-10MB
   - 建议定期导出备份

2. **工具测试**
   - 仅支持 POST 请求
   - 需要处理 CORS 问题
   - 10 秒超时限制

3. **数据导出**
   - 仅支持 JSON 格式
   - 未包含二进制数据

---

## 📞 技术支持

如需帮助或报告问题，请：
1. 检查浏览器控制台错误
2. 查看 LocalStorage 数据
3. 导出数据备份后重试

---

*最后更新: 2025-10-14*