# smart-ride-mvp **Repository Path**: nbcyf/smart-ride-mvp ## Basic Information - **Project Name**: smart-ride-mvp - **Description**: 智能打车系统mvp-可行性验证 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-10 - **Last Updated**: 2026-05-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 🤖 Agent-Native 智能语音打车系统 > NLP 层 = Agent（智能体），而非意图分类器。 > > 用户输入 → Agent 自主推理 → 多步工具调用 → 比较推荐 → 确认下单 [![Java](https://img.shields.io/badge/Java-17%2B-orange)](https://adoptium.net/) [![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.3.5-brightgreen)](https://spring.io/projects/spring-boot) [![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE) --- ## 目录结构 ``` smart-ride-mvp/ ├── src/ # Spring Boot 源码（22 个 Java 文件） │ └── main/java/com/ridehailing/agent/ │ ├── agent/ # RideAgent（ReAct 循环）+ ToolRegistry │ ├── tools/ # 8 个 Tool（车型/路况/估价/司机/订单/天气） │ ├── model/ # 5 个 Record（RideOption/Driver/Order/...） │ ├── repository/ # OrderRepository（SQLite 持久化） │ ├── service/ # 业务服务层 │ ├── config/ # SqliteConfig │ └── controller/ # REST API（/chat /orders /reset /health） ├── src/main/resources/ │ ├── application.yml # 服务配置 │ └── static/index.html # 仿聊天界面交互页 ├── pom.xml # Maven 依赖 ├── start.cmd / start.ps1 # Windows 一键启动（.env Token 持久化） ├── start.sh # macOS/Linux 一键启动 ├── ops-manager/ # 运维管理工具（Flet 桌面版 + Flask Web 版） ├── one-api-config/ # One API 网关配置指南 ├── .env.example # Token 配置文件模板 └── .gitignore ``` --- ## 快速开始 ### 前置条件 | 组件 | 版本要求 | 说明 | |------|---------|------| | JDK | 17+ | 推荐 21 | | Maven | 3.8+ | 或使用 `./mvnw` wrapper | | Docker | 20+ | 运行 One API 网关 | | One API Token | — | 从 One API 获取，替代直接使用 LLM API Key | ### 1. 克隆仓库 ```bash git clone https://gitee.com/nbcyf/smart-ride-mvp.git cd smart-ride-mvp ``` ### 2. 启动 One API 网关（Docker） One API 是一个 LLM 接口管理和分发系统，统一管理多个模型厂商的 API Key： ```bash # 拉取并启动 One API docker run -d --name one-api --restart unless-stopped \ -p 3005:3000 \ -v $(pwd)/one-api-data:/data \ justsong/one-api:latest # 验证 curl http://localhost:3005/api/status ``` > 详细配置见 [one-api-config/README.md](one-api-config/README.md) ### 3. 配置 One API 浏览器打开 `http://localhost:3005`，默认账号 `root` / `123456`： 1. **渠道** → 添加新渠道 - 类型：DeepSeek（或通义千问 DashScope） - 密钥：你的 LLM API Key - 模型：`deepseek-v4-flash`（或 `qwen-turbo`） 2. **令牌** → 新建令牌 → 复制 `sk-` 开头的令牌 ### 4. 设置 Token ```bash # 复制 .env 模板 cp .env.example .env # 编辑 .env，填入上一步的 One API 令牌 # DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx ``` ### 5. 启动服务 ```bash # macOS / Linux ./start.sh # Windows start.cmd ``` 服务启动后： - **聊天界面**：`http://localhost:8080` - **健康检查**：`http://localhost:8080/api/ride/health` - **One API 管理**：`http://localhost:3005` --- ## API 端点 | 方法 | 路径 | 说明 | |------|------|------| | `GET` | `/api/ride/health` | 健康检查 | | `POST` | `/api/ride/chat` | 发送消息 → Agent 回复（支持 sessionId） | | `POST` | `/api/ride/reset` | 重置指定会话记忆 | | `GET` | `/api/ride/orders` | 查询所有历史订单（SQLite） | | `GET` | `/` | 仿聊天界面交互页 | ### 交互示例 ```bash # 简单打车 curl -X POST http://localhost:8080/api/ride/chat \ -H "Content-Type: application/json" \ -d '{"message":"从西二旗去望京"}' # 智能推荐（Agent 会查天气、比价、找司机） curl -X POST http://localhost:8080/api/ride/chat \ -H "Content-Type: application/json" \ -d '{"message":"今天下雨，帮我从西二旗找个最快最靠谱的方案去望京"}' # 查询历史订单 curl http://localhost:8080/api/ride/orders ``` --- ## 架构原理 ### Agent 架构（Agent-Native） ``` 用户(语音/文字) │ ▼ ┌──────────────────────────────────────┐ │ RideAgent (ReAct 循环) │ │ ┌────────┐ ┌────────┐ ┌───────┐ │ │ │ Think │→│ Act │→│Observe │ │ │ │ 思考 │ │ 行动 │ │ 观察 │ │ │ └────────┘ └────┬───┘ └───┬───┘ │ │ │ │ │ │ ┌────▼────┐ │ │ │ │ 8 Tools │◄─────┘ │ │ └────┬─────┘ │ └───────────────────┼──────────────────┘ │ ┌───────────▼───────────┐ │ One API (:3005) │ │ LLM 管理网关 │ └───────────┬───────────┘ │ ┌───────────▼───────────┐ │ DeepSeek / 通义千问 │ └───────────────────────┘ ``` ### ReAct 循环 ``` 用户输入 → Think(我该做什么？) ↓ Act(调用 Tool) ↓ Observe(Tool 返回结果) ↓ 够了吗？──不够→ 回到 Think ↓够了 Respond(总结+推荐) ``` ### 8 个内置工具 | 工具 | 功能 | 数据源 | |------|------|--------| | `search_ride_types` | 查询可选车型+价格+时间 | 模拟数据 | | `check_traffic` | 查询路线实时拥堵 | 随机模拟 | | `estimate_price` | 精准估价（含费用明细） | 模拟计价 | | `find_drivers` | 搜索附近司机（评分+车型过滤） | 7 人司机池 | | `create_order` | 创建订单 | → SQLite | | `cancel_order` | 取消订单 | → SQLite | | `check_order` | 查询订单状态 | ← SQLite | | `get_weather` | 查询天气（影响推荐） | 随机模拟 | --- ## 不同平台部署 ### Windows 11 ```powershell # 1. 安装 JDK 17+ winget install EclipseAdoptium.Temurin.17.JDK # 2. 安装 Docker Desktop winget install Docker.DockerDesktop # 3. 安装 Maven scoop install maven # 或: winget install Apache.Maven.3 # 4. 启动 start.cmd ``` ### macOS ```bash # 1. 安装 JDK 17+ brew install openjdk@17 # 2. 安装 Docker Desktop brew install --cask docker # 3. 安装 Maven brew install maven # 4. 启动 ./start.sh ``` ### 切换 LLM 模型 编辑 `.env` 或在启动时传参： ```bash # DeepSeek mvn spring-boot:run -Dllm.model=deepseek-v4-flash # 通义千问 mvn spring-boot:run -Dllm.model=qwen-turbo # OpenAI mvn spring-boot:run \ -Dllm.base.url=https://api.openai.com/v1 \ -Dllm.model=gpt-4o-mini ``` --- ## 运维管理工具 ```bash # Windows cd ops-manager && start-ops.cmd # macOS/Linux cd ops-manager && python app_desktop.py # Flet 桌面版 cd ops-manager && python app.py # Flask Web 版 ``` 功能：服务状态监控、启停控制、日志检索（关键词+级别过滤）、实时日志流（SSE）。 --- ## 技术决策 | 决策 | 理由 | |------|------| | **不依赖 Spring AI** | 手动 ReAct 循环更透明、可控 | | **RestClient 直连 LLM** | 简洁，兼容任何 OpenAI 兼容 API | | **ThreadLocal → ConcurrentHashMap** | 解决 Tomcat 线程池下会话记忆丢失 | | **SQLite 嵌入式数据库** | 零配置，文件即数据库，可备份迁移 | | **One API 网关** | 统一管理多个模型厂商 Key，Token 权限控制 | | **纯 ASCII 启动脚本** | 避免 CMD 编码问题和 BOM 字符干扰 | --- ## 设计文档 - [Agent-Native 架构方案](https://gitee.com/nbcyf/smart-ride-mvp)（本项目） - 前版 NLP 引擎 MVP：[2026-05-09-2243-smart-ride-mvp](wiki/queries/) - 源码分析：[2026-05-10-1811-ride-agent-source-analysis](wiki/queries/) ## License MIT