mixvideo-v2/MULTI_TURN_CONVERSATION_FEATURE.md

# 多轮对话功能实现文档

## 概述

本文档描述了基于 `promptx/tauri-desktop-app-expert` 开发规范实现的多轮对话功能。该功能扩展了现有的 Gemini API 集成，支持会话历史管理和上下文保持的多轮对话。

## 功能特性

### 🎯 核心功能
- **多轮对话支持**: 支持历史消息传递给后端，构建完整的对话上下文
- **会话管理**: 利用 session_id 进行会话生命周期管理
- **历史消息存储**: 完整的会话历史持久化存储
- **上下文保持**: 在多轮对话中保持对话上下文
- **类型安全**: 完整的 TypeScript 类型定义

### 🏗️ 架构设计
遵循 Tauri 四层架构设计模式：

1. **表现层 (Presentation Layer)**
   - `conversation_commands.rs`: Tauri 命令处理
   - 前端 React 组件和页面

2. **业务逻辑层 (Business Layer)**
   - `conversation_service.rs`: 会话管理业务逻辑
   - 多轮对话处理逻辑

3. **数据访问层 (Data Layer)**
   - `conversation_repository.rs`: 会话数据访问
   - `conversation.rs`: 数据模型定义

4. **基础设施层 (Infrastructure Layer)**
   - 扩展的 `gemini_service.rs`: 支持多轮对话的 API 调用

## 技术实现

### 后端实现 (Rust)

#### 数据模型
```rust
// 会话消息
pub struct ConversationMessage {
    pub id: String,
    pub session_id: String,
    pub role: MessageRole,
    pub content: Vec<MessageContent>,
    pub timestamp: DateTime<Utc>,
    pub metadata: Option<serde_json::Value>,
}

// 会话会话
pub struct ConversationSession {
    pub id: String,
    pub title: Option<String>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub is_active: bool,
    pub metadata: Option<serde_json::Value>,
}
```

#### API 结构修改
扩展了 Gemini API 的请求结构以支持多轮对话：

```rust
pub struct GenerateContentRequest {
    pub contents: Vec<ContentPart>,  // 支持多条历史消息
    pub generation_config: GenerationConfig,
}

pub struct ContentPart {
    pub role: String,  // "user", "assistant", "system"
    pub parts: Vec<Part>,
}
```

#### 核心服务方法
```rust
impl ConversationService {
    // 处理多轮对话
    pub async fn process_multi_turn_conversation(
        &self,
        request: MultiTurnConversationRequest,
    ) -> Result<MultiTurnConversationResponse>

    // 会话管理
    pub async fn create_session(&self, request: CreateConversationSessionRequest) -> Result<ConversationSession>
    pub async fn get_conversation_history(&self, query: ConversationHistoryQuery) -> Result<ConversationHistory>
}
```

### 前端实现 (TypeScript + React)

#### 类型定义
```typescript
// 多轮对话请求
export interface MultiTurnConversationRequest {
  session_id?: string;
  user_message: string;
  include_history?: boolean;
  max_history_messages?: number;
  system_prompt?: string;
  config?: Record<string, any>;
}

// 多轮对话响应
export interface MultiTurnConversationResponse {
  session_id: string;
  assistant_message: string;
  message_id: string;
  response_time_ms: number;
  model_used: string;
  metadata?: Record<string, any>;
}
```

#### 服务层
```typescript
export class ConversationService {
  static async processMultiTurnConversation(
    request: MultiTurnConversationRequest
  ): Promise<MultiTurnConversationResponse>

  static async createSession(request: CreateConversationSessionRequest): Promise<ConversationSession>
  static async getConversationHistory(query: ConversationHistoryQuery): Promise<ConversationHistory>
}
```

## 数据库设计

### 会话表 (conversation_sessions)
```sql
CREATE TABLE conversation_sessions (
    id TEXT PRIMARY KEY,
    title TEXT,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL,
    is_active BOOLEAN NOT NULL DEFAULT 1,
    metadata TEXT
);
```

### 消息表 (conversation_messages)
```sql
CREATE TABLE conversation_messages (
    id TEXT PRIMARY KEY,
    session_id TEXT NOT NULL,
    role TEXT NOT NULL,
    content TEXT NOT NULL,
    timestamp TEXT NOT NULL,
    metadata TEXT,
    FOREIGN KEY (session_id) REFERENCES conversation_sessions (id) ON DELETE CASCADE
);
```

## 使用示例

### 基本多轮对话
```typescript
import { ConversationService, MultiTurnConversationHelper } from '../services/conversationService';

// 创建对话请求
const request = MultiTurnConversationHelper.createTextConversationRequest(
  "你好，请介绍一下自己",
  sessionId, // 可选，如果为空会创建新会话
  {
    includeHistory: true,
    maxHistoryMessages: 20,
    systemPrompt: "你是一个友好的AI助手"
  }
);

// 处理多轮对话
const response = await ConversationService.processMultiTurnConversation(request);
console.log(response.assistant_message);
```

### 会话管理
```typescript
// 创建新会话
const session = await ConversationService.createSession({
  title: "新的对话",
  metadata: { topic: "技术讨论" }
});

// 获取会话历史
const history = await ConversationService.getConversationHistory({
  session_id: session.id,
  limit: 50,
  include_system_messages: false
});
```

## 测试组件

项目包含了完整的测试组件：

- `MultiTurnChatTest.tsx`: 多轮对话测试界面
- `MultiTurnChatTestPage.tsx`: 测试页面
- `conversation_service_test.rs`: 后端单元测试

## 配置选项

### 多轮对话配置
```typescript
interface MultiTurnConversationOptions {
  sessionId?: string;           // 会话ID
  includeHistory?: boolean;     // 是否包含历史消息
  maxHistoryMessages?: number;  // 最大历史消息数
  systemPrompt?: string;        // 系统提示词
  temperature?: number;         // 生成温度
  maxTokens?: number;          // 最大输出令牌数
  timeout?: number;            // 请求超时时间
}
```

### 会话清理配置
```rust
pub struct ConversationCleanupConfig {
    pub max_inactive_days: u32,      // 最大非活跃天数
    pub max_messages_per_session: u32, // 每个会话最大消息数
    pub auto_cleanup_enabled: bool,   // 是否启用自动清理
}
```

## 性能优化

1. **数据库索引**: 为会话ID和时间戳创建索引以提高查询性能
2. **消息限制**: 支持限制历史消息数量以控制API请求大小
3. **连接池**: 使用数据库连接池提高并发性能
4. **异步处理**: 所有数据库操作都是异步的

## 安全考虑

1. **输入验证**: 严格验证用户输入和会话ID
2. **权限控制**: 遵循最小权限原则
3. **数据加密**: 敏感数据的安全存储
4. **会话隔离**: 确保会话之间的数据隔离

## 扩展性

该实现设计为可扩展的：

1. **插件化**: 支持自定义消息处理器
2. **多模型支持**: 可以轻松扩展支持其他AI模型
3. **存储后端**: 可以替换为其他数据库后端
4. **消息类型**: 支持文本、文件、内联数据等多种消息类型

## 开发规范遵循

- ✅ 遵循 `promptx/tauri-desktop-app-expert` 开发规范
- ✅ 四层架构设计模式
- ✅ 类型安全的 TypeScript 实现
- ✅ 完整的错误处理和用户反馈
- ✅ 性能优化和安全防护
- ✅ 模块化和可维护的代码结构

## 未来改进

1. **流式响应**: 支持流式生成响应
2. **消息搜索**: 实现会话历史搜索功能
3. **导出功能**: 支持会话导出为各种格式
4. **多用户支持**: 扩展为多用户会话管理
5. **实时同步**: 支持多设备间的会话同步