# agent

**Repository Path**: leemuyang/agent

## Basic Information

- **Project Name**: agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Chat - WebSocket 聊天服务器

基于 FastAPI 和 WebSocket 的智能对话系统，支持会话管理、历史记录和多客户端复用。

## 快速开始

### 1. 配置

编辑 `config/config.yaml` 文件，配置你的 LLM API：

```yaml
llm:
  base_url: "https://api.openai.com/v1"
  api_key: "your-api-key-here"  # 替换为你的 API Key
  model: "gpt-4"

server:
  host: "0.0.0.0"
  port: 8000

session:
  max_history_turns: 10
  session_timeout: 3600  # 1小时
  client_timeout: 7200   # 2小时
```

### 2. 安装依赖

```bash
pip install fastapi uvicorn openai pyyaml pydantic websockets
```

### 3. 启动服务器

```bash
python main.py
```

服务器启动后会显示：
```
Starting Agent Chat Server...
WebSocket endpoint: ws://localhost:8000/ws
Health check: http://localhost:8000/
Stats: http://localhost:8000/stats
```

### 4. 访问测试页面

打开浏览器访问：http://localhost:8000

你将看到一个漂亮的聊天界面，可以：
- 连接 WebSocket
- 发送消息
- 查看流式响应
- 获取/清空历史记录
- 复用 Session 和 Client

## 功能特性

### ✨ 核心功能

- **WebSocket 实时通信** - 支持双向实时通信
- **流式响应** - 支持 LLM 流式输出，实时显示响应
- **会话管理** - 每个 WebSocket 连接对应一个 Session
- **客户端复用** - 通过 Client ID 复用已有的对话历史
- **历史记录** - 自动保存对话历史
- **自动清理** - 定期清理过期的 Session 和 Client

### 🔧 API 端点

#### WebSocket 端点

- `ws://localhost:8000/ws` - 创建新的 Session
- `ws://localhost:8000/ws/{session_id}` - 复用已有的 Session

#### HTTP 端点

- `GET /` - 测试页面
- `GET /stats` - 查看统计信息

### 📝 消息格式

#### 客户端 → 服务器

**聊天消息（流式）**
```json
{
  "type": "chat",
  "message": "你好！",
  "stream": true,
  "client_id": "optional-client-id"
}
```

**聊天消息（非流式）**
```json
{
  "type": "chat",
  "message": "你好！",
  "stream": false
}
```

**获取历史记录**
```json
{
  "type": "get_history"
}
```

**清空历史记录**
```json
{
  "type": "clear_history"
}
```

**心跳**
```json
{
  "type": "ping"
}
```

#### 服务器 → 客户端

**连接成功**
```json
{
  "type": "connected",
  "session_id": "xxx-xxx-xxx",
  "message": "Successfully connected to WebSocket"
}
```

**消息确认**
```json
{
  "type": "ack",
  "session_id": "xxx-xxx-xxx",
  "client_id": "yyy-yyy-yyy"
}
```

**流式响应**
```json
{
  "type": "stream",
  "content": "部分内容",
  "done": false
}
```

**流式完成**
```json
{
  "type": "stream",
  "content": "",
  "done": true,
  "full_response": "完整响应"
}
```

**非流式响应**
```json
{
  "type": "response",
  "content": "响应内容",
  "raw_response": { ... }
}
```

**错误**
```json
{
  "type": "error",
  "message": "错误信息"
}
```

## 使用场景

### 场景 1：新用户对话
1. 访问 http://localhost:8000
2. 点击"连接"按钮
3. 系统自动分配 Session ID 和 Client ID
4. 开始对话

### 场景 2：继续之前的对话（同一浏览器）
1. 刷新页面后，Session ID 会自动保留
2. 点击"连接"
3. 继续之前的对话

### 场景 3：跨设备复用对话
1. 记录之前的 Client ID
2. 在新设备访问 http://localhost:8000
3. 在"Client ID"输入框填入之前的 Client ID
4. 点击"连接"
5. 可以继续之前的对话，历史记录保留

## 开发

### 项目结构

```
src/internal/
├── config/              # 配置管理
│   ├── __init__.py
│   └── config.py
├── context/             # 应用上下文
│   └── __init__.py
└── logic/              # 业务逻辑
    ├── llm/            # LLM 客户端
    │   ├── history.py
    │   ├── client.py
    │   └── async_client.py
    ├── session/        # Session 管理
    │   ├── session.py
    │   └── manager.py
    └── conn/           # WebSocket 连接
        └── websocket.py

config/
└── config.yaml         # 配置文件

static/
└── index.html          # 测试页面

main.py                 # 应用入口
```

### 扩展建议

1. **持久化存储** - 将 Session 和 Client 保存到 Redis 或数据库
2. **用户认证** - 添加登录功能，关联用户和 Session
3. **多模型支持** - 支持切换不同的 LLM 模型
4. **对话导出** - 支持导出对话历史
5. **监控统计** - 添加更详细的统计和监控
6. **限流** - 添加请求频率限制

## 故障排查

### 连接失败
- 检查服务器是否启动
- 检查 WebSocket URL 是否正确
- 检查防火墙设置

### API 错误
- 检查 config.yaml 中的 API Key 是否正确
- 检查 API 配额是否充足
- 查看服务器日志获取详细错误信息

### 历史记录丢失
- 默认历史记录保存在内存中，重启服务器会丢失
- 可以实现持久化存储来保留历史记录

## License

MIT