ailine/FEATURES.md

🎯 AI Agent 新功能说明

新增功能概览

本次更新实现了三大核心功能：用户登录隔离、对话历史管理、流式实时响应。

---

一、用户登录系统

功能特性

• ✅ 可选登录：用户可以选择输入用户名或直接使用默认用户
• ✅ 对话隔离：不同用户的对话历史完全隔离，避免污染
• ✅ 默认用户：未登录时使用 default_user，所有未登录用户共享对话

使用方式

1. 启动前端后，左侧栏显示登录界面
2. 输入用户名（可选），点击"进入"
3. 如需切换用户，点击"切换用户"按钮

技术实现

• 前端：st.session_state.user_id 和 st.session_state.logged_in 管理登录状态
• 后端：所有 API 请求携带 user_id 参数，用于数据隔离
• 数据库：LangGraph checkpoint 的 metadata 字段存储 user_id

---

二、对话历史管理

功能特性

• ✅ 历史列表：左侧栏显示用户的所有对话历史
• ✅ 摘要展示：每个历史对话显示摘要（第一条消息或生成的 summary）
• ✅ 一键加载：点击历史对话，自动加载完整消息历史
• ✅ 新对话：点击"新对话"按钮创建全新对话线程
• ✅ 实时更新：每次对话结束后自动刷新历史列表

使用方式

1. 点击"刷新列表"按钮加载历史对话
2. 点击任意历史对话，自动加载完整消息历史
3. 点击"新对话"开始全新话题

技术实现

后端新增接口

接口	方法	说明
/threads	GET	获取用户的对话历史列表
/thread/{thread_id}/messages	GET	获取指定线程的完整消息历史
/thread/{thread_id}/summary	GET	获取指定线程的摘要信息

新增模块

• app/history.py: ThreadHistoryService 类，封装历史查询逻辑
• 直接查询 LangGraph 的 checkpoints 表，通过 metadata->>'user_id' 过滤

前端实现

• 左侧栏显示历史列表，每个对话显示摘要、时间和消息数量
• 当前选中的对话高亮显示（primary 按钮样式）
• 点击历史对话调用 /thread/{thread_id}/messages 加载完整历史

---

三、流式实时响应

功能特性

• ✅ 逐字输出：AI 回复实时逐字显示，提升用户体验
• ✅ 工具调用状态：显示工具调用的开始和完成状态
• ✅ Token 统计：对话结束后显示消耗的 token 数量和耗时
• ✅ 错误处理：流式响应异常时友好提示用户

使用方式

• 在输入框输入问题后，AI 回复会逐字显示，无需等待完整响应
• 如果 AI 调用工具，会显示"🔧 调用工具: xxx..."的提示
• 工具调用完成后显示"✅ 工具 xxx 完成"
• 回复完成后显示 token 消耗和耗时统计

技术实现

后端流式接口

接口	方法	说明
/chat/stream	POST	流式对话接口（SSE）

SSE 事件类型

{
  "type": "token",           // AI 逐字输出
  "content": "你好"
}

{
  "type": "tool_start",      // 工具调用开始
  "tool": "search_calendar"
}

{
  "type": "tool_end",        // 工具调用完成
  "tool": "search_calendar"
}

{
  "type": "done",            // 对话完成
  "reply": "完整回复内容",
  "token_usage": {"total_tokens": 123},
  "elapsed_time": 2.5
}

{
  "type": "error",           // 错误信息
  "message": "错误详情"
}

Agent 流式处理

• AIAgentService.process_message_stream() 方法
• 使用 LangGraph 的 astream_events() API 获取流式事件
• 支持所有模型（zhipu, deepseek, local）

前端流式消费

• 使用 requests.post(..., stream=True) 消费 SSE 流
• 逐行解析 data: {...} 格式的事件
• 实时更新 UI 显示 token 和工具状态

---

四、三栏布局设计

布局结构

┌──────────────┬──────────────────────────┬──────────────┐
│  左侧栏 (1)  │      中间栏 (3)          │  右侧栏 (1)  │
│              │                          │              │
│  👤 用户     │  🤖 AI 个人助手          │  📊 会话信息 │
│  [登录]      │                          │              │
│              │  [模型选择器]            │  当前对话    │
│  📚 历史     │  ┌────────────────────┐  │  xxx...      │
│  [刷新]      │  │                    │  │              │
│  [新对话]    │  │   聊天消息区域     │  │  消息统计    │
│              │  │                    │  │  用户: 5     │
│  💬 对话1    │  └────────────────────┘  │  AI: 4       │
│  💬 对话2    │                          │              │
│  💬 对话3    │  [输入框]                │  💡 使用提示 │
│              │                          │              │
└──────────────┴──────────────────────────┴──────────────┘

各栏功能

左侧栏（宽度 1/5）

• 用户登录：输入用户名，切换用户
• 历史列表：刷新、点击加载、新对话按钮

中间栏（宽度 3/5）

• 模型选择：下拉框选择 AI 模型
• 聊天区域：显示消息历史，支持流式输出
• 输入框：输入用户问题

右侧栏（宽度 1/5）

• 会话信息：显示当前线程 ID
• 消息统计：用户消息和 AI 回复数量
• 使用提示：功能说明

---

五、配置说明

环境变量

本地开发（.env）

# API 地址（注意：不需要 /chat 后缀）
API_URL=http://localhost:8083

# 日志调试配置（本地开发推荐 DEBUG）
LOG_LEVEL=DEBUG
DEBUG=true
ENABLE_GRAPH_TRACE=true

Docker 部署（.env.docker）

# API 地址（Docker 内部网络）
API_URL=http://backend:8083

# 日志调试配置（生产环境推荐 WARNING）
LOG_LEVEL=WARNING
DEBUG=false
ENABLE_GRAPH_TRACE=false

端口分配

服务	端口	说明
llama.cpp LLM	8081	Gemma-4-E2B GGUF 模型
llama.cpp Embedding	8082	embeddinggemma-300M GGUF 模型
Backend (FastAPI)	8083	AI Agent 后端服务
Frontend (Streamlit)	8501	Web 界面

---

六、文件变更清单

新增文件

文件	说明
app/history.py	历史查询服务 ThreadHistoryService

修改文件

文件	修改内容
app/agent.py	• 添加 process_message_stream() 流式处理方法 • process_message() 写入 metadata 支持历史查询
app/backend.py	• 添加 /threads、/thread/{id}/messages、/thread/{id}/summary 接口 • 添加 /chat/stream 流式接口 • 注入 history_service
frontend/frontend.py	• 完全重写为三栏布局 • 实现用户登录和历史管理 • 支持流式响应消费
.env, .env.docker, .env.example	• 移除 API_URL 中的 /chat 后缀

---

七、使用示例

1. 本地开发启动

# 启动后端和前端
./scripts/start.sh both

# 访问前端
open http://localhost:8501

2. Docker 部署

# 配置环境变量
cp .env.docker .env
# 编辑 .env 填入 API Key

# 启动服务
cd docker
docker compose up -d

3. API 测试

# 获取历史列表
curl "http://localhost:8083/threads?user_id=test_user"

# 获取线程消息
curl "http://localhost:8083/thread/{thread_id}/messages?user_id=test_user"

# 流式对话
curl -X POST "http://localhost:8083/chat/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "你好",
    "thread_id": "test-thread",
    "model": "zhipu",
    "user_id": "test_user"
  }'

---

八、注意事项

1. 数据库查询性能

• 当前直接查询 checkpoints 表的 JSONB metadata 字段
• 如果用户对话数量很大，建议在 checkpoints 表上创建 GIN 索引：

  CREATE INDEX idx_checkpoints_metadata_user_id 
  ON checkpoints USING GIN ((metadata->>'user_id'));
  

2. 流式响应缓冲

• 如果使用 Nginx 反向代理，需要关闭缓冲：

  location /chat/stream {
      proxy_pass http://backend:8083;
      proxy_buffering off;
      proxy_cache off;
  }
  

3. 历史列表分页

• 当前默认返回 50 条历史记录
• 如需支持更多历史，可在 /threads 接口添加 offset 参数实现分页

4. 用户认证增强

• 当前用户登录仅为前端输入，无密码验证
• 如需加强安全性，可集成 OAuth2 或 JWT 认证

---

九、下一步优化建议

1. 对话摘要生成：在 summarize 节点中生成对话摘要，存入 checkpoint metadata
2. 历史记录搜索：添加关键词搜索功能，快速定位历史对话
3. 对话导出：支持导出对话历史为 Markdown 或 JSON 格式
4. 多设备同步：同一用户的不同设备共享对话历史
5. 对话标签：支持为对话添加标签和分类
6. 收藏功能：支持收藏重要对话，方便快速访问

---

🎉 新功能已全部实现并测试通过！