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 事件类型
```json
{
  "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）
```bash
# API 地址（注意：不需要 /chat 后缀）
API_URL=http://localhost:8083

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

#### Docker 部署（.env.docker）
```bash
# 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()` 流式处理方法<br>• `process_message()` 写入 `metadata` 支持历史查询 |
| `app/backend.py` | • 添加 `/threads`、`/thread/{id}/messages`、`/thread/{id}/summary` 接口<br>• 添加 `/chat/stream` 流式接口<br>• 注入 `history_service` |
| `frontend/frontend.py` | • 完全重写为三栏布局<br>• 实现用户登录和历史管理<br>• 支持流式响应消费 |
| `.env`, `.env.docker`, `.env.example` | • 移除 `API_URL` 中的 `/chat` 后缀 |

---

## 七、使用示例

### 1. 本地开发启动
```bash
# 启动后端和前端
./scripts/start.sh both

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

### 2. Docker 部署
```bash
# 配置环境变量
cp .env.docker .env
# 编辑 .env 填入 API Key

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

### 3. API 测试
```bash
# 获取历史列表
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 索引：
  ```sql
  CREATE INDEX idx_checkpoints_metadata_user_id 
  ON checkpoints USING GIN ((metadata->>'user_id'));
  ```

### 2. 流式响应缓冲
- 如果使用 Nginx 反向代理，需要关闭缓冲：
  ```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. **收藏功能**：支持收藏重要对话，方便快速访问

---

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