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 数据：

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

3. API 变更

3.1 修改 ChatRequest

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

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

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 组件（新建）

<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