JARVIS/docs/superpowers/specs/2026-03-20-chat-enhancement-design.md

# 沟通系统增强设计

## 1. 概述与目标

在沟通系统（ChatView）中增加两个功能：
1. **文件上传** - 用户可在对话中上传文件，AI 自动理解内容并回复
2. **表情包选择器** - 在发送按钮旁添加 emoji 选择面板

## 2. 技术方案

### 2.1 文件上传

**前端实现：**
- 在 `ChatView.vue` 输入区域添加附件按钮（Paperclip 图标）
- 使用 `<input type="file">` 触发文件选择
- 支持类型：图片（jpg/png/gif/webp）、文档（pdf/doc/docx/xls/xlsx/ppt/pptx/txt）
- 文件大小限制：10MB
- 上传时显示进度状态

**消息气泡展示：**
- 文件上传成功后，在对话中显示文件消息气泡
- 气泡内容：文件图标 + 文件名 + 文件大小
- 点击可下载/预览

**后端实现：**
- 复用现有 `/api/documents/upload` 接口上传文件
- 创建 KGNode（entity_type: 'document'）关联到对话
- 修改 `AgentService.chat_simple()` 支持文件上下文
- AI 自动读取上传文件内容并理解

**数据流：**
```
用户选择文件 → 前端上传到 /api/documents/upload
→ 后端存储文件，创建 KGNode
→ 前端发送消息带 file_ids
→ AgentService 读取文件内容
→ AI 基于文件内容回复
```

### 2.2 表情包选择器

**前端实现：**
- 在发送按钮旁添加 Emoji 图标按钮
- 点击展开浮层面板，显示 emoji 分类网格
- 分类：😀 笑脸 | 👍 手势 | 📦 物品 | 💬 符号
- 每个分类显示常用 emoji 网格
- 点击 emoji 插入到输入框
- 点击外部关闭面板

**Emoji 数据：**
```typescript
const emojiCategories = {
  smile: ['😀', '😃', '😄', '😁', '😅', '😂', '🤣', '😊', '😇', '🙂', '😉', '😌'],
  gesture: ['👍', '👎', '👌', '🤌', '🤏', '✌️', '🤞', '🖖', '🤙', '💪', '🙏', '👏'],
  object: ['📄', '📁', '🖼️', '📊', '📝', '💾', '📧', '🔗', '📌', '🔍', '💡', '⚡'],
  symbol: ['✅', '❌', '⚠️', '🔥', '💯', '🎯', '⭐', '✨', '💬', '🗨️', '❤️', '🧡']
}
```

## 3. API 变更

### 3.1 修改 ChatRequest

```python
class ChatRequest(BaseModel):
    message: str
    conversation_id: str | None = None
    agent_id: str | None = None
    file_ids: list[str] = []  # 新增：上传的文件ID列表
```

### 3.2 修改 Message 模型（可选扩展）

```python
class Message(BaseModel):
    # 新增字段
    attachments: list[dict] = []  # [{file_id, filename, file_type, file_size}]
```

### 3.3 新增文件读取接口

```
GET /api/documents/{document_id}/content
返回: 文件的文本内容（用于 AI 理解）
```

## 4. 组件变更

### 4.1 ChatView.vue 变更

**新增：**
- `fileInput` ref - 文件 input
- `showEmojiPicker` ref - emoji 面板显示状态
- `selectedFiles` ref - 已选择待上传文件
- `uploadFile()` - 上传文件方法
- `insertEmoji()` - 插入 emoji 到输入框

**修改：**
- 输入区域布局：附件按钮 | 输入框 | Emoji按钮 | 发送按钮
- `sendMessage()` - 发送前先上传文件，获取 file_ids

### 4.2 EmojiPicker 组件（新建）

```vue
<script setup lang="ts">
defineProps<{
  visible: boolean
}>()

const emit = defineEmits<{
  select: [emoji: string]
  close: []
}>()

const categories = {
  smile: { name: '😀', emojis: [...] },
  gesture: { name: '👍', emojis: [...] },
  object: { name: '📦', emojis: [...] },
  symbol: { name: '💬', emojis: [...] }
}
</script>
```

### 4.3 FileMessage 组件（新建）

用于展示文件消息气泡：
- 文件图标（根据类型）
- 文件名（可截断）
- 文件大小
- 下载按钮

## 5. 错误处理

| 场景 | 处理 |
|------|------|
| 文件类型不支持 | 提示"不支持该文件类型" |
| 文件超过10MB | 提示"文件超过10MB限制" |
| 上传失败 | 提示"上传失败，请重试"，显示重试按钮 |
| AI读取文件失败 | AI 回复"无法读取文件内容" |
| 网络断开 | 提示"网络连接断开" |

## 6. 状态定义

| 状态 | 显示 |
|------|------|
| 上传中 | 进度环 + 文件名 |
| 上传成功 | 文件气泡 |
| 上传失败 | 错误图标 + 重试按钮 |
| AI 读取中 | AI 思考状态..." |

## 7. 实现顺序

1. **Phase 1: 基础 UI**
   - 添加附件按钮和 Emoji 按钮到输入区域
   - Emoji 选择器组件
   - 文件消息气泡组件

2. **Phase 2: 文件上传**
   - 前端文件上传逻辑
   - 消息带 file_ids
   - 文件气泡展示

3. **Phase 3: AI 理解文件**
   - 后端文件内容读取接口
   - AgentService 支持文件上下文
   - 测试完整流程

## 8. 文件结构

```
frontend/src/
├── views/
│   └── ChatView.vue          # 修改 - 添加附件/Emoji按钮
├── components/
│   ├── chat/
│   │   ├── EmojiPicker.vue  # 新建 - Emoji 选择器
│   │   └── FileMessage.vue   # 新建 - 文件消息气泡
│   └── stats/               # 已存在
│       └── ...
└── api/
    ├── conversation.ts       # 修改 - chat 支持 file_ids
    └── document.ts          # 新增 - getDocumentContent

backend/app/
├── routers/
│   ├── conversation.py       # 修改 - ChatRequest 支持 file_ids
│   └── document.py          # 修改 - 新增 content 接口
├── services/
│   └── agent_service.py     # 修改 - chat 支持文件上下文
└── models/
    └── conversation.py      # 修改 - Message 新增 attachments
```