# 聊天界面 (Chat Interface)

> **分类**: 核心功能
> **优先级**: P0 - 决定性
> **成熟度**: L4 - 生产
> **最后更新**: 2026-03-25
> **验证状态**: ✅ 代码已验证

---

## 一、功能概述

### 1.1 基本信息

聊天界面是用户与 Agent 交互的主要入口，支持流式响应、Markdown 渲染、模型选择等核心功能。

| 属性 | 值 |
|------|-----|
| 分类 | 核心功能 |
| 优先级 | P0 |
| 成熟度 | L4 |
| 依赖 | chatStore, GatewayClient, TauriGateway |
| **LLM Provider 支持** | **8** |
| **流式响应** | ✅ 已实现 |
| **Markdown 渲染** | ✅ 已实现 |
| **多模型切换** | ✅ 已实现 |

### 1.2 支持的 LLM Provider

| Provider | 模型示例 | 状态 |
|----------|---------|------|
| **Kimi** | kimi-k2.5 | ✅ 可用 |
| **Qwen (通义千问)** | qwen3.5-plus | ✅ 可用 |
| **DeepSeek** | deepseek-chat | ✅ 可用 |
| **Zhipu (智谱)** | glm-5 | ✅ 可用 |
| **OpenAI** | gpt-4o | ✅ 可用 |
| **Anthropic** | claude-3-5-sonnet | ✅ 可用 |
| **Gemini** | gemini-2.0-flash | ✅ 可用 |
| **Local/Ollama** | llama3 | ✅ 可用 |

### 1.3 相关文件

| 文件 | 路径 | 用途 |
|------|------|------|
| 主组件 | `desktop/src/components/ChatArea.tsx` | 聊天 UI |
| 状态管理 | `desktop/src/store/chatStore.ts` | 消息和会话状态 |
| 消息渲染 | `desktop/src/components/MessageItem.tsx` | 单条消息 |
| Markdown | `desktop/src/components/MarkdownRenderer.tsx` | 轻量 Markdown 渲染 |
| Tauri 网关 | `desktop/src/lib/tauri-gateway.ts` | Tauri 原生命令 |
| 内核客户端 | `desktop/src/lib/kernel-client.ts` | Kernel 通信 |

---

## 二、设计初衷

### 2.1 问题背景

**用户痛点**:
1. 需要等待完整响应，无法实时看到进度
2. 代码块没有语法高亮
3. 长对话难以管理

**系统缺失能力**:
- 缺乏流式响应展示
- 缺乏消息的富文本渲染
- 缺乏多会话管理

**为什么需要**:
作为 AI Agent 的主要交互界面，聊天功能必须是核心体验的入口。

### 2.2 设计目标

1. **流式体验**: 实时展示 AI 响应进度
2. **富文本渲染**: Markdown + 代码高亮
3. **多会话管理**: 创建、切换、删除会话
4. **模型选择**: 用户可选择不同 LLM

### 2.3 竞品参考

| 项目 | 参考点 |
|------|--------|
| ChatGPT | 流式响应、Markdown 渲染 |
| Claude | 代码块复制、消息操作 |
| OpenClaw | 历史消息管理 |

### 2.4 设计约束

- **性能约束**: 流式更新不能阻塞 UI
- **存储约束**: 消息历史需要持久化
- **兼容性约束**: 支持多种 LLM 提供商

---

## 三、技术设计

### 3.1 核心接口

```typescript
interface Message {
  id: string;
  role: 'user' | 'assistant' | 'tool' | 'hand' | 'workflow';
  content: string;
  timestamp: number;
  agentId?: string;
  model?: string;
  metadata?: Record<string, any>;
}

interface Conversation {
  id: string;
  title: string;
  messages: Message[];
  createdAt: number;
  updatedAt: number;
  agentId?: string;
}

interface ChatState {
  messages: Message[];
  conversations: Conversation[];
  currentConversationId: string | null;
  isStreaming: boolean;
  currentModel: string;
}
```

### 3.2 数据流

```
用户输入
    │
    ▼
ChatArea (React)
    │
    ▼
chatStore.sendMessage()
    │
    ├──► 记忆增强 (getRelevantMemories)
    │
    ├──► 上下文压缩检查 (threshold: 15000)
    │
    ▼
GatewayClient.chatStream()
    │
    ├──► WebSocket 连接
    │       │
    │       └──► 流式事件 (assistant, tool, hand, workflow)
    │
    ▼
消息更新 (isStreaming: true → false)
    │
    ├──► 记忆提取 (extractMemories)
    │
    └──► 反思触发 (recordConversation)
```

### 3.3 状态管理

```typescript
// chatStore 核心状态 (desktop/src/store/chatStore.ts)
interface ChatState {
  messages: Message[];              // 当前会话消息
  conversations: Conversation[];    // 所有会话
  currentConversationId: string | null;
  isStreaming: boolean;
  currentModel: string;             // 默认 'glm-5'
  agents: Agent[];                  // 可用 Agent 列表
  currentAgent: Agent | null;       // 当前选中的 Agent
  abortController: AbortController | null; // 流式中断控制
}

// 核心方法
{
  sendMessage: (content: string, options?) => Promise<void>,
  stopStreaming: () => void,
  switchModel: (modelId: string) => void,
  switchAgent: (agentId: string) => void,
  createConversation: () => string,
  deleteConversation: (id: string) => void,
}
```

### 3.4 流式处理

```typescript
// WebSocket 事件处理
case 'assistant':
  // 追加内容到当前消息
  updateMessage(currentMessageId, { content: delta });
  break;

case 'tool':
  // 添加工具调用记录
  addMessage({ role: 'tool', content: toolResult });
  break;

case 'workflow':
  // 添加工作流状态更新
  addMessage({ role: 'workflow', content: workflowStatus });
  break;

case 'done':
  // 完成流式
  setIsStreaming(false);
  // 触发后处理
  extractMemories();
  recordConversation();
  break;
```

---

## 四、预期作用

### 4.1 用户价值

| 价值类型 | 描述 |
|---------|------|
| 效率提升 | 流式响应无需等待 |
| 体验改善 | 富文本渲染，代码高亮 |
| 能力扩展 | 多模型选择，多会话管理 |

### 4.2 系统价值

| 价值类型 | 描述 |
|---------|------|
| 架构收益 | 清晰的消息流处理 |
| 可维护性 | 组件职责分离 |
| 可扩展性 | 支持新的消息类型 |

### 4.3 成功指标

| 指标 | 基线 | 目标 | 当前 |
|------|------|------|------|
| 流式延迟 | 2s | <500ms | 300ms |
| 消息渲染 | 1s | <200ms | 150ms |
| 用户满意度 | - | 4.5/5 | 4.3/5 |

---

## 五、实际效果

### 5.1 已实现功能

- [x] 流式响应展示 (WebSocket 实时更新)
- [x] Markdown 渲染（轻量级）
- [x] 代码块渲染
- [x] 多会话管理
- [x] 多模型选择（8 个 LLM Provider）
- [x] 消息自动滚动
- [x] 输入框自动调整高度
- [x] 记忆增强注入 (getRelevantMemories)
- [x] 上下文自动压缩 (threshold: 15000 tokens)
- [x] 流式中断控制 (AbortController)
- [x] Agent 切换
- [x] 工具调用展示 (tool, hand, workflow 消息类型)

### 5.2 测试覆盖

- **单元测试**: 30+ 项
- **集成测试**: 包含在 chatStore.test.ts
- **覆盖率**: ~85%

### 5.3 已知问题

| 问题 | 严重程度 | 状态 | 计划解决 |
|------|---------|------|---------|
| 超长消息渲染卡顿 | 中 | 待处理 | Q2 |
| 代码高亮样式单一 | 低 | 待处理 | Q3 |

### 5.4 用户反馈

流式体验流畅，Markdown 渲染满足需求。希望增加更多代码高亮主题。

---

## 六、演化路线

### 6.1 短期计划（1-2 周）
- [ ] 消息搜索功能
- [ ] 消息导出功能

### 6.2 中期计划（1-2 月）
- [ ] 多代码高亮主题
- [ ] 消息引用和回复

### 6.3 长期愿景
- [ ] 语音输入/输出
- [ ] 多模态消息（图片、文件）

---

## 七、头脑风暴笔记

### 7.1 待讨论问题
1. 是否需要支持消息编辑？
2. 是否需要支持消息分支（同一提示的不同响应）？

### 7.2 创意想法
- 消息时间线：可视化对话历史
- 智能摘要：长对话自动生成摘要
- 协作模式：多人同时对话

### 7.3 风险与挑战
- **技术风险**: 大量消息的渲染性能
- **缓解措施**: 虚拟化列表，消息分页