# 服务层组件化重构文档

## 概述

本次重构将CLI功能组件化，创建了独立的服务层，使CLI和MCP服务共享相同的业务逻辑。

## 重构目标

1. **代码复用**: CLI和MCP共享业务逻辑，避免重复代码
2. **职责分离**: 明确分离表示层（CLI/MCP）和业务逻辑层（Service）
3. **易于维护**: 集中管理业务逻辑，便于后续维护和扩展
4. **功能完整**: MCP服务支持所有CLI功能

## 架构变更

### 重构前
```
CLI命令 → RAGSystem（直接调用）
MCP工具 → RAGSystem（直接调用）
```

### 重构后
```
CLI命令 → RAGService → RAGSystem
MCP工具 → RAGService → RAGSystem
MCP资源 → RAGService → RAGSystem
```

## 新增组件

### 1. 服务层 (src/services/)

#### RAGService (src/services/rag_service.py)

提供统一的业务逻辑封装，包含以下方法：

- `build_index(data_dir, force_rebuild)` - 构建索引
- `query(question, mode, top_k)` - 查询知识库（使用LLM）
- `retrieve(question, mode, top_k)` - 检索文档（不使用LLM）
- `get_status(verbose)` - 获取系统状态
- `delete_index(confirm)` - 删除索引
- `get_config()` - 获取系统配置

**特点**:
- 统一的错误处理和日志记录
- 统一的返回格式（JSON格式，包含success字段）
- 懒加载RAGSystem实例
- 易于测试和扩展

### 2. 更新的MCP处理器

#### MCPToolsHandler (src/mcp/handlers/tools_handler.py)

**新增工具**:
- `retrieve_documents` - 检索文档片段（对应CLI的retrieve命令）
- `get_config` - 获取系统配置（对应CLI的config命令）

**更新工具**:
- `get_index_status` - 新增verbose参数支持详细信息

**改进**:
- 使用RAGService替代直接创建RAGSystem
- 统一的错误处理
- 更清晰的代码结构

#### MCPResourcesHandler (src/mcp/handlers/resources_handler.py)

**新增资源**:
- `stats://index/verbose` - 索引详细统计信息

**改进**:
- 使用RAGService获取数据
- 更好的错误处理

### 3. 更新的CLI命令处理器

#### src/cli/commands.py

**改进**:
- 所有命令处理器使用RAGService
- 统一的错误处理
- 保持原有用户体验

## 功能对照表

| 功能 | CLI命令 | MCP工具 | MCP资源 |
|------|---------|---------|---------|
| 构建索引 | `index` | `build_index` | - |
| 查询（使用LLM） | `query` | `query_knowledge` | - |
| 检索（不使用LLM） | `retrieve` | `retrieve_documents` | - |
| 查看状态 | `status` | `get_index_status` | `stats://index`, `stats://index/verbose` |
| 查看配置 | `config` | `get_config` | `config://system` |
| 删除索引 | `delete` | `delete_index` | - |

## 使用示例

### CLI使用（保持不变）

```bash
# 构建索引
python cli.py index --dir ./knowledge_base

# 查询知识库
python cli.py query --question "什么是RAG?"

# 检索文档
python cli.py retrieve --question "RAG" --mode hybrid

# 查看状态
python cli.py status --verbose --config

# 查看配置
python cli.py config

# 删除索引
python cli.py delete --yes
```

### MCP工具使用

```json
// 构建索引
{
  "tool": "build_index",
  "arguments": {
    "data_dir": "./knowledge_base",
    "force_rebuild": false
  }
}

// 查询知识库
{
  "tool": "query_knowledge",
  "arguments": {
    "question": "什么是RAG?",
    "mode": "hybrid",
    "top_k": 3
  }
}

// 检索文档（新增）
{
  "tool": "retrieve_documents",
  "arguments": {
    "question": "RAG",
    "mode": "hybrid",
    "top_k": 5
  }
}

// 获取状态
{
  "tool": "get_index_status",
  "arguments": {
    "verbose": true
  }
}

// 获取配置（新增）
{
  "tool": "get_config",
  "arguments": {}
}

// 删除索引
{
  "tool": "delete_index",
  "arguments": {
    "confirm": true
  }
}
```

### MCP资源使用

```
// 系统配置
config://system

// 索引统计
stats://index

// 索引详细统计（新增）
stats://index/verbose
```

## 代码质量改进

### 1. 统一的返回格式

所有服务方法返回统一的JSON格式：

```json
{
  "success": true/false,
  "data": {...},  // 成功时的数据
  "error": "...",  // 失败时的错误信息
  "traceback": "..."  // 详细错误堆栈（仅开发模式）
}
```

### 2. 统一的错误处理

- 所有异常都被捕获并转换为统一格式
- 详细的日志记录
- 用户友好的错误信息

### 3. 更好的可测试性

- 服务层可独立测试
- 易于模拟（Mock）
- 清晰的依赖关系

### 4. 更好的可扩展性

- 新增功能只需在服务层添加方法
- CLI和MCP自动获得新功能
- 易于添加新的表示层（如Web API）

## 向后兼容性

- ✅ CLI命令完全兼容
- ✅ MCP现有工具完全兼容
- ✅ MCP现有资源完全兼容
- ✅ 配置文件完全兼容

## 迁移指南

### 对于CLI用户
不需要任何更改，所有命令保持原样。

### 对于MCP用户
现有工具和资源保持不变，新增了以下功能：
- `retrieve_documents` 工具
- `get_config` 工具
- `stats://index/verbose` 资源

### 对于开发者
如果要添加新功能：

1. 在 `RAGService` 中添加业务逻辑方法
2. 在 `MCPToolsHandler` 中添加工具定义和调用
3. 在 `src/cli/commands.py` 中添加CLI命令处理器（可选）
4. 在 `cli.py` 中添加命令解析器（可选）

## 测试建议

### 1. CLI测试
```bash
# 测试索引构建
python cli.py index --dir ./test_data

# 测试查询
python cli.py query --question "测试问题"

# 测试检索
python cli.py retrieve --question "测试" --mode hybrid

# 测试状态
python cli.py status --verbose --config

# 测试配置
python cli.py config
```

### 2. MCP测试
使用MCP客户端测试所有工具和资源。

### 3. 单元测试（推荐添加）
```python
# 测试服务层
from src.services import RAGService

service = RAGService()
result = service.get_config()
assert result["success"] == True
```

## 性能影响

- ✅ 无性能损失（仅增加一层薄封装）
- ✅ 懒加载减少初始化时间
- ✅ 相同的RAGSystem实例复用

## 未来改进方向

1. **配置管理**: 支持动态配置更新
2. **缓存机制**: 添加查询结果缓存
3. **异步支持**: 支持异步查询和检索
4. **批量操作**: 支持批量查询和索引构建
5. **Web API**: 基于服务层快速构建REST API
6. **监控和指标**: 添加性能监控和使用统计

## 总结

本次重构实现了：

✅ 代码复用和组件化
✅ 职责分离和清晰架构  
✅ CLI和MCP功能对等
✅ 向后兼容
✅ 易于维护和扩展
✅ 统一的错误处理和日志

这为后续功能开发和系统扩展奠定了良好的基础。
