X-Agents/teams/chat_history_plan.md

对话内容记录实现计划

创建时间：2026-03-13 11:30 计划周期：2026-03-13 ~ 2026-03-15

目标

在 Chat 页面创建新对话时，持久化记录对话内容，支持历史会话查看和刷新页面不丢失。

一、数据库设计

1. 会话表 (chat_sessions)

CREATE TABLE IF NOT EXISTS chat_sessions (
    id VARCHAR(191) PRIMARY KEY,
    user_id VARCHAR(191) NOT NULL,
    agent_id VARCHAR(191) NOT NULL,
    title VARCHAR(255) NOT NULL,
    model_id VARCHAR(191),
    status VARCHAR(20) DEFAULT 'active',  -- active/archived
    created_at DATETIME(3),
    updated_at DATETIME(3),
    INDEX idx_sessions_user (user_id),
    INDEX idx_sessions_agent (agent_id),
    INDEX idx_sessions_updated (updated_at DESC)
);

2. 消息表 (chat_messages)

CREATE TABLE IF NOT EXISTS chat_messages (
    id VARCHAR(191) PRIMARY KEY,
    session_id VARCHAR(191) NOT NULL,
    role VARCHAR(20) NOT NULL,  -- user/assistant/system
    content TEXT NOT NULL,
    tokens_used INT DEFAULT 0,
    duration_ms INT DEFAULT 0,
    metadata TEXT,  -- JSON格式存储额外信息
    created_at DATETIME(3),
    INDEX idx_messages_session (session_id),
    INDEX idx_messages_created (created_at)
);

二、后端接口设计

1. 会话管理

方法	路径	说明
POST	/chat/sessions	创建新会话
GET	/chat/sessions	获取用户会话列表
GET	/chat/sessions/:id	获取会话详情(含消息)
PUT	/chat/sessions/:id	更新会话(如标题)
DELETE	/chat/sessions/:id	删除会话

2. 消息管理

方法	路径	说明
GET	/chat/sessions/:id/messages	获取会话消息历史
POST	/chat/messages	记录单条消息(可选)

三、实现步骤

阶段一：后端 (小尧、小陈)

• 1. 创建 chat_sessions 和 chat_messages 表的 GORM 模型
• 2. 添加数据库表初始化代码到 main.go
• 3. 实现 SessionRepository (会话 CRUD)
• 4. 实现 MessageRepository (消息 CRUD)
• 5. 创建 ChatSessionHandler 和 ChatMessageHandler
• 6. 注册路由并测试接口

阶段二：Python 服务 (小泽、小明)

• 1. 修改 api/routes.py 接入后端会话服务
• 2. 每次对话结束后调用后端保存消息
• 3. 支持历史消息加载(从后端获取)
• 4. 异常处理和重试机制

阶段三：前端 (小荣、狗蛋)

• 1. 创建 useChatSession composable
• 2. 新建对话时调用后端创建会话
• 3. 发送消息时持久化到后端
• 4. 加载历史会话和消息
• 5. 会话列表展示和切换

四、详细时间计划

阶段一：后端开发 (2026-03-13 ~ 2026-03-13)

日期	任务	负责人
03-13 下午	创建 chat_sessions 和 chat_messages 表的 GORM 模型	小尧
03-13 下午	添加数据库表初始化代码到 main.go	小尧
03-13 下午	实现 SessionRepository (会话 CRUD)	小尧
03-13 下午	实现 MessageRepository (消息 CRUD)	小陈
03-13 下午	创建 ChatSessionHandler 和 ChatMessageHandler	小陈
03-13 下午	注册路由并测试接口	小陈

阶段二：Python 服务接入 (2026-03-14)

日期	任务	负责人
03-14 上午	修改 api/routes.py 接入后端会话服务	小泽
03-14 上午	每次对话结束后调用后端保存消息	小泽
03-14 下午	支持历史消息加载(从后端获取)	小明
03-14 下午	异常处理和重试机制	小明

阶段三：前端对接 (2026-03-14 ~ 2026-03-15)

日期	任务	负责人
03-14 下午	创建 useChatSession composable	小荣
03-14 下午	新建对话时调用后端创建会话	小荣
03-15 上午	发送消息时持久化到后端	小荣
03-15 上午	加载历史会话和消息	狗蛋
03-15 下午	会话列表展示和切换	狗蛋

五、技术细节

前端消息流程

1. 用户点击"新建对话"
   → 调用 POST /chat/sessions 创建会话
   → 保存 sessionId 到状态

2. 用户发送消息
   → 前端发送消息到 Python 服务
   → Python 服务返回响应后
   → 前端调用 POST /chat/messages 保存用户消息
   → 前端调用 POST /chat/messages 保存 AI 响应

3. 加载历史会话
   → 调用 GET /chat/sessions 获取会话列表
   → 选择会话后调用 GET /chat/sessions/:id/messages 获取消息

消息结构

interface ChatMessage {
  id: string
  session_id: string
  role: 'user' | 'assistant' | 'system'
  content: string
  tokens_used?: number
  duration_ms?: number
  metadata?: Record<string, any>
  created_at: string
}

五、分工汇总

人员	任务	阶段
小尧	后端 - 会话/消息模型和 Repository	阶段一
小陈	后端 - Handler 和路由注册	阶段一
小泽	Python - 接入后端会话服务	阶段二
小明	Python - 历史消息加载	阶段二
小荣	前端 - 会话管理和消息持久化	阶段三
狗蛋	前端 - UI 对接和测试	阶段三

六、待确认问题

1. 是否需要支持消息撤回/编辑？
2. 会话标题是否需要 AI 自动生成还是用户手动输入？
3. 是否需要消息搜索功能？