# my-chat-app

**Repository Path**: lsq2025/my-chat-app

## Basic Information

- **Project Name**: my-chat-app
- **Description**: 项目的后端在cloud2机器上的/data/lanshanquan/cloud/agents/pegasus-chat-agent-v1/ 
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Pegasus AI Agent

一个多功能 AI 助手应用，基于 Flutter 构建，支持流式对话、工具调用、多轮上下文记忆、会话管理、图片上传等功能。通过 SSE 实时展示 Agent 的思考过程和执行状态，提供透明、高效的 AI 交互体验。

## 核心特性

### 🤖 智能对话
- **流式输出**：基于 SSE 实时展示 AI 回复，打字机效果呈现
- **状态可视化**：清晰展示 `thinking`（思考）、`executing`（工具执行）、`answering`（回复）、`complete`（完成）四个阶段
- **工具调用透明**：实时显示调用的工具名称和执行结果
- **数据来源追溯**：最终回答展示所有数据来源，增强可信度
- **字体差异化**：用户消息使用系统默认字体，Agent 回复使用微软雅黑（15px）

### 📷 图片上传
- **多种来源**：支持从相册选择或相机拍照上传图片
- **图片压缩**：自动压缩图片（最大 1024x1024，JPEG 格式，质量 85%）
- **MinIO 存储**：上传到 MinIO 后获取 URL，支持多模态对话
- **状态展示**：显示压缩、上传、完成三个阶段状态

### 📝 会话管理
- **多会话支持**：创建、切换、管理多个独立会话
- **历史消息加载**：切换会话时自动加载历史对话
- **上下文连续性**：会话内保持稳定的 `session_id`，支持多轮对话
- **消息历史透传**：每次请求携带完整对话历史

### 🔐 认证系统
- **安全登录**：用户登录/注册，JWT Token 认证
- **Token 管理**：自动刷新过期 Token，本地安全存储
- **登录态恢复**：应用启动时自动恢复登录状态

### 💾 记忆库
- **用户画像**：存储用户偏好、习惯等个性化信息
- **记忆管理**：新增、删除、查看记忆内容
- **上下文增强**：AI 可参考记忆提供个性化回复

### 🎤 语音输入
- **语音录制**：支持语音消息录制
- **ASR 识别**：语音转文字，方便快捷输入

### 🎨 界面体验
- **深色主题**：专为夜间使用设计的配色方案（深蓝紫渐变）
- **品牌标识**：浏览器标题显示 "Pegasus AI Agent"
- **响应式设计**：适配 Web、移动端多平台

## 技术架构

### 前端技术栈
| 类别 | 技术 |
|------|------|
| UI 框架 | Flutter |
| 状态管理 | Provider |
| HTTP 客户端 | Dio（认证/业务）、HTTP（SSE 流式）|
| 图片选择 | file_picker + image_picker |
| 图片压缩 | image（纯 Dart 实现）|
| Token 存储 | flutter_secure_storage |
| 本地存储 | shared_preferences |
| 语音录制 | record |
| 权限管理 | permission_handler |

### 项目结构

```
lib/
├── main.dart                     # 应用入口，Provider 配置
├── config/
│   └── app_config.dart           # 应用配置（API 地址等）
├── core/                         # 核心基础设施
│   ├── constants/                # API 常量、应用常量
│   ├── network/                  # 网络层（SSE Client、API Client、Multipart）
│   ├── storage/                  # 本地存储
│   └── utils/                    # 工具类（时间格式化、Result）
├── data/
│   └── preset_topics.dart        # 预设话题
├── models/                       # 数据模型
│   ├── agent/                    # Agent 状态、工具规格
│   ├── chat/                     # 聊天消息、会话信息
│   ├── common/                   # 通用模型
│   ├── user/                     # 用户模型
│   ├── chat_message.dart         # 消息模型
│   ├── memory.dart               # 记忆模型
│   └── user_profile.dart         # 用户画像
├── providers/                    # 状态管理（Provider）
│   ├── auth_provider.dart        # 认证状态
│   ├── chat_provider.dart        # 聊天状态
│   ├── session_provider.dart     # 会话状态
│   ├── pegasus_provider.dart     # Agent 状态
│   ├── theme_provider.dart       # 主题状态
│   └── asr_provider.dart         # 语音状态
├── services/                     # 服务层
│   ├── api_service.dart          # REST API 调用
│   ├── agent_api_service.dart    # Agent API 调用
│   ├── auth_service.dart         # 认证服务
│   ├── chat_provider.dart        # 聊天逻辑 + 图片上传
│   ├── session_service.dart      # 会话管理
│   ├── token_storage.dart        # Token 存储
│   ├── asr_service.dart          # 语音识别
│   └── http_client.dart          # Dio HTTP 客户端
├── screens/                      # 页面
│   ├── chat_screen.dart          # 主聊天页（70KB，核心页面）
│   ├── login_screen.dart         # 登录页
│   ├── memory_screen.dart        # 记忆库页
│   ├── session_list_screen.dart  # 会话列表
│   ├── sessions/                 # 会话相关
│   └── settings/                 # 设置相关
├── widgets/                      # UI 组件
│   └── voice_input_button.dart   # 语音录制按钮
└── utils/                        # 工具函数
```

## 后端接口

### API 地址（通过 nginx 代理）

前端使用相对路径，由 nginx 代理到后端服务：

| 接口类型 | 前端路径 | nginx 代理目标 |
|----------|----------|----------------|
| 认证 API | `/api/*` | `http://172.17.0.1:30022` |
| Agent 聊天 | `/internal/v1/assistant/*` | `http://172.17.0.1:30085` |
| 会话管理 | `/internal/v1/session/*` | `http://172.17.0.1:30085` |
| 图片上传 | `/internal/v1/upload/image` | `http://172.17.0.1:30005`（本机 nginx）|

### 认证接口

```
POST /api/auth/login       # 登录
POST /api/auth/register    # 注册
POST /api/auth/refresh     # 刷新 Token
POST /api/auth/logout      # 登出
GET  /api/user/profile     # 获取用户信息
```

### Agent 聊天接口

```
POST /internal/v1/assistant/chat  # 流式聊天
```

**请求示例：**

```json
{
  "message": "帮我分析一下最近的市场趋势",
  "user_id": "123",
  "session_id": "pegasus-session-1713337200000",
  "image_url": "https://minio.example.com/image.jpg"
}
```

**SSE 响应格式：**

```
event: thinking
data: {"phase":"thinking","type":"status","content":"正在分析..."}

event: executing
data: {"phase":"executing","type":"status","content":"正在查询数据...","metadata":{"tools":["get_weather"]}}

event: answering
data: {"phase":"answering","type":"delta","content":"根据"}

event: complete
data: {"phase":"complete","type":"final","content":"...","metadata":{"sources":[{"tool":"get_weather","summary":"北京晴天，22°C"}]}}
```

### 图片上传接口

```
POST /internal/v1/upload/image  # 上传图片到 MinIO
```

**响应示例：**

```json
{
  "url": "https://minio.example.com/bucket/image.jpg"
}
```

## 本地开发

### 安装依赖

```bash
flutter pub get
```

### 运行应用

```bash
# macOS
flutter run -d macos

# Chrome
flutter run -d chrome

# Web 构建
flutter build web --release
```

## Docker 部署

### 构建与部署

```bash
cd /data/lanshanquan/cloud/apps/my-chat-app

# 构建 Web 产物
export PATH="/opt/flutter/bin:$PATH"
flutter pub get
flutter build web --release

# Docker 部署
docker compose down
docker compose build --no-cache
docker compose up -d
```

### 访问地址

```
http://120.77.206.206:30005
```

### 容器信息

| 配置项 | 值 |
|--------|-----|
| 容器名 | my-chat-app |
| 端口 | 30005:80 |
| 镜像 | nginx:alpine |
| 网络 | moya-network |

### nginx 配置要点

```nginx
# SSE 流式聊天代理（禁用缓冲）
location /internal/v1/assistant/ {
    proxy_pass http://172.17.0.1:30085;
    proxy_buffering off;
    proxy_read_timeout 300s;
}

# 认证 API 代理
location /api/ {
    proxy_pass http://172.17.0.1:30022;
}

# 图片上传（本机 nginx 直接处理）
location /internal/v1/upload/ {
    # 由后端服务处理
}
```

## 实现说明

| 功能 | 实现状态 |
|------|----------|
| 流式聊天 + 状态展示 | ✅ 完成 |
| 多会话管理 | ✅ 完成 |
| 历史消息加载 | ✅ 完成 |
| Token 认证 + 自动刷新 | ✅ 完成 |
| 记忆库管理 | ✅ 完成 |
| 语音输入 | ✅ 完成 |
| 工具调用可视化 | ✅ 完成 |
| 数据来源展示 | ✅ 完成 |
| 图片上传（相册）| ✅ 完成 |
| 图片上传（相机）| ✅ 完成 |
| 图片压缩 | ✅ 完成 |
| MinIO 存储 | ✅ 完成 |
| 字体差异化 | ✅ 完成（微软雅黑）|
| 品牌标识 | ✅ 完成（Pegasus AI Agent）|

## 注意事项

1. **SSE 流式聊天**：依赖后端支持 Server-Sent Events
2. **nginx 配置**：必须禁用 `proxy_buffering` 以支持 SSE
3. **Token 存储**：Web 端使用 `flutter_secure_storage`，登出时只清理认证相关键
4. **会话持久化**：Agent 后端使用 Redis 存储会话历史
5. **图片压缩**：纯 Dart 实现（image 包），Web/APK 通用，无需原生依赖
6. **相机拍照**：Web 端需浏览器摄像头权限，移动端需配置权限声明
7. **字体显示**：微软雅黑在 Windows/iOS 显示良好，其他平台使用 fallback

## 后续优化

- [ ] 多语言支持
- [ ] 消息编辑与重新生成
- [ ] 图片预览与删除
- [ ] 错误处理增强
- [ ] 离线消息缓存
- [ ] 多图片上传

## License

MIT

LANSHANQUAN @2026

---

## 版本历史

> 项目于每月月末发布正式版本，版本号格式：`YYYY.MM`（如 `2026.04`）

| 版本 | 发布日期 | 主要更新 |
|------|----------|----------|
| **2026.05** | 2026-05-31（待发布）| 📷 图片上传（相机拍照）、字体差异化（微软雅黑）、品牌标识更新、死代码清理 |
| **2026.04** | 2026-04-30 | 🤖 流式对话 + 状态可视化、📝 多会话管理、🔐 认证系统、💾 记忆库、🎤 语音输入、📷 图片上传（相册）|
| **2026.03** | 2026-03-31 | 🎨 深色主题、基础 UI 框架、项目初始化 |

### 当前版本

```
版本：1.0.0+1
代码：2026.05-dev（开发中）
发布：2026-05-31
```

### 版本命名规则

- **版本号**：`pubspec.yaml` 中的 `version` 字段（如 `1.0.0+1`）
- **发布代号**：`YYYY.MM`（年月格式）
- **开发版本**：`YYYY.MM-dev`（开发中）
- **正式版本**：`YYYY.MM`（月末发布后）

### 更新日志

详见项目 Git 提交记录：

```bash
git log --oneline --since="2026-04-01"
```