# wander-ai

**Repository Path**: qq910183766/wander-ai

## Basic Information

- **Project Name**: wander-ai
- **Description**: 基于 Spring AI Alibaba 的多 Agent 智能旅行规划开源应用。用户通过自然语言对话，即可获得从目的地推荐、行程编排、预算管理到实时信息查询的全链路旅行规划服务。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-31
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WanderAI（漫游记）

基于 **Spring AI Alibaba** 的多 Agent 智能旅行规划开源应用。用户通过自然语言对话，即可获得从目的地推荐、行程编排、预算管理到实时信息查询的全链路旅行规划服务。

## ✨ 核心功能

- **多 Agent 协作**：Supervisor 意图路由 + 8 个专业子 Agent 并行执行 + 合成器统一汇总
- **Graph 工作流**：两阶段并行编排（需求分析 → 并行调研 → 行程编排 → 并行细化 → 生成计划）
- **智能行程创建**：AI 生成待确认行程计划，用户可查看、编辑每日活动并确认
- **SSE 任务通知**：实时推送后台任务阶段、结果和错误，连接断开不影响后台执行
- **异步任务可恢复**：对话和创建行程支持后台执行、任务状态查询、恢复与取消，切换页面后可继续查看结果
- **三层记忆机制**：短期对话记忆（MysqlSaver）+ 长期记忆存储 + 用户偏好注入（TopK 检索、冲突感知写入）
- **评分反馈学习**：对 AI 回复评分（0.5-5.0），自动更新用户偏好画像，越用越懂你
- **行程全生命周期**：行程确认、开始、完成、每日活动执行记录、评价评分、天气关联和只读分享
- **管理员控制台**：用户锁定/解锁、剩余次数调整、游客与注册用户分组、用户画像查看、模型与高德配置
- **统一缓存服务**：Redis 缓存天气、地理编码、用户画像、系统配置和分享行程，外部服务失败时不阻塞主流程
- **JWT 用户认证**：登录/注册、BCrypt 密码加密
- **MCP 工具集成**：高德地图、天气、翻译、汇率查询
- **会员配额体系**：FREE / MEMBER / PRO 三级，按月限制调用次数
- **多模型热切换**：DeepSeek / 豆包（火山引擎 ARK），通过 Spring Profile 切换
- **PWA 离线支持**：对话与行程数据 IndexedDB 离线缓存

## 🛠 技术栈

| 层 | 技术 |
|----|------|
| 后端 | Java 17、Spring Boot 3.5.7、Spring AI 1.1.2、Spring AI Alibaba 1.1.2.2、Spring Data JPA |
| 前端 | Vue 3、Vant 4（移动端 UI）、Pinia、Vue Router 4、Vite 5、Tailwind CSS、PWA |
| 数据库 | MySQL 8.x（数据持久化）、Redis（缓存与偏好） |
| AI 模型 | OpenAI 兼容接口（DeepSeek / 豆包），`spring-ai-starter-model-openai` |
| 认证 | JWT（jjwt 0.12.6）+ BCrypt（spring-security-crypto） |
| 构建 | Maven（后端）+ Vite（前端） |

## 📁 项目结构

```
wander-ai/
├── pom.xml                    # 父 POM（Spring Boot 3.5.7 + Spring AI Alibaba 1.1.2.2）
├── wander-ai-app/             # 后端 Spring Boot 应用
│   └── src/main/java/com/wanderai/
│       ├── agent/             # Agent 扩展（执行日志 Hook）
│       ├── config/            # Agent / Graph / 记忆 / 模型 / Redis 等配置
│       ├── constant/          # Agent 常量与中文显示名映射
│       ├── controller/        # 认证 / 对话 / 行程 / 记忆 / 模型 / 语音等接口
│       ├── graph/             # Graph 工作流节点与执行器（两阶段并行）
│       ├── memory/            # 用户偏好记忆、旅行历史记忆、偏好注入 Hook
│       ├── model/             # JPA 实体（用户 / 行程 / 对话历史等）
│       ├── repository/        # JPA Repository
│       ├── service/           # 业务服务（对话 / 记忆 / 偏好提取 / 语音等）
│       ├── tool/              # MCP 工具（高德地图 / 天气 / 翻译 / 汇率）
│       └── resources/
│           ├── application.yml              # 主配置
│           ├── application-deepseek.yml     # DeepSeek 模型 Profile
│           ├── application-doubao.yml       # 豆包模型 Profile
│           ├── db/init.sql                  # 数据库初始化脚本（10 张表）
│           ├── db/upgrade/                   # 生产环境增量升级脚本
│           └── skills/                      # Agent 技能定义
├── wander-ai-web/             # 前端 Vue 3 移动端应用
│   └── src/
│       ├── views/             # 对话 / 拍照 / 行程 / 登录注册 / 个人中心 / 偏好 / 历史
│       ├── components/        # 气泡 / 行程卡片 / 预算图表 / 天气组件等
│       ├── stores/            # Pinia 状态（认证 / 对话 / 行程 / 记忆 / 模型）
│       ├── composables/       # useChat / usePhoto 组合式函数
│       └── utils/             # 拍照 / 离线缓存 / 请求封装
└── doc/                       # 项目文档与 Spring AI Alibaba 学习笔记
```

## 🚀 快速开始

### 环境准备

- JDK 17+
- Maven 3.8+
- Node.js 18+
- MySQL 8.x（数据库 `wander_ai`）
- Redis（默认 localhost:6379）

### 1. 初始化数据库

在 MySQL 中创建数据库并执行初始化脚本：

```sql
CREATE DATABASE IF NOT EXISTS wander_ai DEFAULT CHARACTER SET utf8mb4;
```

后端首次启动时可通过 `spring.sql.init` 执行 `db/init.sql`（表结构也可由 JPA `ddl-auto: update` 自动同步）。

### 2. 配置环境变量

> 仓库中的配置文件不含任何真实密钥，请通过环境变量注入：

| 变量 | 说明 | 示例 |
|------|------|------|
| `spring.profiles.active` | 模型 Profile（`deepseek` / `doubao`） | deepseek |
| `DEEPSEEK_API_KEY` | DeepSeek API Key（active=deepseek 时必填） | sk-xxx |
| `DOUBAO_API_KEY` | 豆包 ARK API Key（active=doubao 时必填） | ark-xxx |
| `MYSQL_USERNAME` | MySQL 用户名 | root |
| `MYSQL_PASSWORD` | MySQL 密码 | 必填 |
| `REDIS_HOST` | Redis 主机 | localhost |
| `REDIS_PORT` | Redis 端口 | 6379 |
| `REDIS_PASSWORD` | Redis 密码 | 必填 |
| `AMAP_API_KEY` | 高德地图 API Key | 选填 |
| `AMAP_SECURITY_KEY` | 高德 Web 服务安全密钥（签名鉴权） | 使用高德 Web 服务时必填 |
| `WEATHER_API_KEY` | 天气 API Key | 选填 |
| `WANDER_AI_CACHE_ENABLED` | 是否启用 Redis 缓存 | `true` |
| `WANDER_AI_WEATHER_CACHE_TTL` | 天气缓存时间 | `1d` |
| `WANDER_AI_GEOCODE_CACHE_TTL` | 地理编码缓存时间 | `30d` |
| `WANDER_AI_USER_PROFILE_CACHE_TTL` | 用户画像缓存时间 | `1d` |
| `WANDER_AI_SYSTEM_CONFIG_CACHE_TTL` | 系统配置缓存时间 | `30m` |
| `WANDER_AI_SHARED_TRIP_CACHE_TTL` | 分享行程缓存时间 | `1h` |

缓存默认使用 Redis；Redis 不可用时自动按缓存未命中处理，不影响主业务请求。生产环境请通过环境变量注入密钥，不要把真实值写入配置文件或文档。

### 3. 启动后端

```bash
cd wander-ai-app
mvn spring-boot:run
```

默认端口 `8080`，REST 接口前缀 `/api`（通过代理转发）。

### 4. 启动前端

```bash
cd wander-ai-web
npm install
npm run dev
```

开发地址 `http://localhost:3000`，`/api` 请求代理到 `http://localhost:8080`。

### 5. 生产构建

```bash
# 后端打包
cd wander-ai-app && mvn clean package -DskipTests

# 前端构建
cd wander-ai-web && npm run build
```

## 🏗 架构概览

### 多 Agent 协作

**Supervisor + 8 个子 Agent + 合成器**：旅行主管 Agent（LlmRoutingAgent）根据用户意图路由到对应子 Agent 并行执行，合成器 Agent 将各子 Agent 结果合并为连贯回复。

| Agent | 职责 | 绑定工具 |
|-------|------|----------|
| travel-supervisor | 意图路由、结果汇总 | - |
| destination-agent | 根据偏好推荐目的地 | MapTool |
| itinerary-agent | 编排每日行程 | - |
| budget-agent | 预算估算与分配 | CurrencyTool |
| weather-agent | 天气查询 | WeatherTool |
| transport-agent | 交通方案查询 | MapTool |
| food-agent | 美食推荐 | - |
| photo-agent | 图片识别 | - |
| local-guide-agent | 当地向导 | TranslationTool |
| synthesizer-agent | 汇总子 Agent 结果生成连贯回复 | - |

### Graph 工作流

两阶段并行模式（`StateGraph` 实现）：

1. 需求分析 → 并行（目的地推荐、天气查询、预算评估）→ 行程编排
2. 行程编排 → 并行（交通查询、美食推荐）→ 结果汇总 → 生成旅行计划（待确认）

### 记忆与偏好体系

- **短期对话记忆**：`MysqlSaver` 将对话状态持久化到 MySQL，支持会话隔离与恢复（threadId）
- **长期记忆存储**：`MemoryStore` 跨会话存储，保存用户长期偏好
- **偏好注入 Hook**：`UserPreferenceHook` 在 Agent 调用前注入用户画像（TopK 检索 + 冲突感知写入 + 置信度合并）
- **偏好 key 规范化**：自动提取由 LLM 按固定枚举输出 key，同义词自动收敛，手动/自动同语义偏好按值级合并为一条
- **矛盾处理**：同类别互斥偏好（如"喜辣"与"不吃辣"）自动禁用旧偏好，避免矛盾信息同时注入
- **加权检索**：TopK 排序采用"手动优先、新近优先"（来源加权 + 时间衰减）
- **评分反馈**：对 AI 回复评分后自动提取/修正用户画像（高分提取正面偏好，低分记录负面偏好）
- **画像隐私**：自动提取的用户画像为系统内部数据，记忆管理页仅展示用户手动添加的记忆

## 📄 文档

- [项目方案](doc/WanderAI-项目方案.md)
- [PRD 需求文档](doc/WanderAI-PRD需求文档.md)
- [开发计划](doc/WanderAI-开发计划.md)
- [对话模块优化方案](doc/WanderAI-对话模块优化方案.md)
- [服务器部署与升级指南](doc/WanderAI-部署与升级.md)
- [Spring AI Alibaba 学习笔记](doc/spring-ai-alibaba/README.md)

## 📜 License

Apache License 2.0