TripStar-Java

TripStar 是一个前后端分离的 AI 旅行规划项目。系统使用多 Agent 协作理解用户需求，读取小红书旅行内容，查询高德 POI、天气、酒店与餐饮，并生成包含每日路线、地图、景点图片、预算和知识图谱的完整攻略。

• 后端 GitHub：LeeFly-cn/TripStar-Java
• 后端 Gitee：haigoya_admin/trip-star-java
• 前端 GitHub：LeeFly-cn/TripStar-Frontend
• 社区：LinuxDo

项目预览

双模式规划入口

核心能力

1. 自主规划

输入目的地、日期、交通方式、住宿偏好和自然语言要求，系统按以下顺序执行：

1. 小红书搜索 Agent 查找真实旅行笔记。
2. 小红书详情 Agent 读取正文并提炼景点、避坑和预约信息。
3. 高德 POI Agent 校准名称、地址和经纬度。
4. 天气 Agent 查询旅行天气。
5. 酒店餐饮 Agent 查询住宿与三餐候选。
6. Planner Agent 生成每日行程和预算。
7. Review Agent 检查结构与明显数据矛盾。

2. 指定笔记规划

用户可以输入一个或多个小红书长链接、短链、App 分享内容，或者直接粘贴攻略正文。系统会：

1. 解析公开笔记正文和全部图片。
2. 使用多模态模型识别图片中的 Day01、Day02、路线、酒店、餐厅和交通信息。
3. 按笔记原始顺序保留全部景点，不套用自主规划的每日数量限制。
4. 使用高德 Service 逐项补全 POI、地址、坐标、评分与图片。
5. 仅在笔记缺少酒店或餐饮时调用补充 Agent。
6. 使用独立 Planner 与 Review Prompt 生成并检查最终攻略。
7. Java 严格校验笔记景点是否全部进入最终行程，缺失时直接列出名称并终止任务。

3. 可观测的 Agent 工作流

• Spring AI Alibaba StateGraph 控制自主规划研究阶段的执行顺序和条件边。
• ReactAgent 负责阶段内的工具调用与参数决策。
• 每个 Agent 使用职责明确的小型 DTO，不共享包含大量无关字段的通用输出对象。
• Spring AI BeanOutputConverter 将模型 JSON 转换为 Java Record。
• 系统提示词、用户提示词、工具列表和模型原始输出写入 AI Trace 文件。
• WebSocket 实时推送当前阶段、进度和错误信息。

4. 真实数据链路

• 小红书支持 service、tool、both 三种运行模式。
• 高德提供地理编码、POI、天气、酒店、餐饮和图片数据。
• 餐饮与酒店查询使用高德类型过滤，避免景区或商场进入错误数据类别。
• 未配置密钥、Cookie 或工具调用失败时明确报错，不返回模拟数据。

系统架构

flowchart LR
    WEB[TripStar Frontend] --> API[Spring Boot API]
    API --> TASK[TripTaskService]

    TASK --> AUTO[自主规划 Workflow]
    TASK --> NOTE[指定笔记 Workflow]

    AUTO --> XHS[XHS Search / Detail Agents]
    XHS --> GRAPH[Spring AI Alibaba StateGraph]
    GRAPH --> AMAP[AMap POI / Weather / Hotel Agents]

    NOTE --> READER[Note Reader + Image Downloader]
    READER --> VISION[Multimodal Understanding Agent]
    VISION --> POI[POI Enrichment Service]
    POI --> SUPPLEMENT[Weather + Conditional Hotel/Food Agents]

    AMAP --> PLANNER[Planner Agent]
    SUPPLEMENT --> PLANNER
    PLANNER --> REVIEW[Review Agent]
    REVIEW --> RESULT[Trip Plan + Knowledge Graph]
    RESULT --> WEB

自主规划 StateGraph

flowchart TD
    START([START]) --> MODE{xhs_mode}
    MODE -- service --> SERVICE[XHS Service]
    MODE -- tool --> SEARCH[XHS Search Agent]
    MODE -- both --> SERVICE
    SERVICE -- service --> READY[XHS Ready Check]
    SERVICE -- continue tool --> SEARCH
    SEARCH --> DETAIL[XHS Detail Agent]
    DETAIL --> READY
    READY --> POI[AMap POI Agent]
    POI --> WEATHER[Weather Agent]
    WEATHER --> HOTEL[Hotel / Restaurant Agent]
    HOTEL --> MERGE[Merge Research Context]
    MERGE --> END([END])

Agent 与输出契约

TravelResearchResult 只在 Graph 最终合并时创建，不作为单个阶段 Agent 的大而全输出 DTO。

技术栈

• Java 21
• Spring Boot 4.0.7
• Spring AI 2.0.0-M1
• Spring AI Alibaba 2.0.0-M1.1
• Spring AI Alibaba StateGraph / ReactAgent
• Spring AI Tool Calling / Structured Output / Multimodal Message
• Maven 多模块
• MyBatis-Plus、Sa-Token、Redis、MySQL
• 高德 Web Service API
• Node.js 小红书签名运行时

模块结构

TripStar-Java/
├── app/                         # HTTP API、WebSocket、运行配置
├── common/
│   ├── core/                   # 异常、常量、运行时设置
│   ├── json/                   # JSON 配置
│   ├── redis/                  # Redis
│   ├── satoken/                # Sa-Token
│   └── web/                    # Web 通用配置
├── modules/
│   ├── ai/                     # Agent、Structured Output、Prompt、Trace
│   ├── content/                # 小红书搜索、详情、公开笔记与图片读取
│   ├── map/                    # 高德 API、Tool、POI 图片代理
│   └── trip/                   # Workflow、规划、质检、DTO、知识图谱
├── docs/                       # 源码学习与实现文档
├── .env.example
└── pom.xml

环境要求

• JDK 21
• Maven 3.9+
• Node.js 18+
• MySQL 8+
• Redis 6+
• DashScope API Key
• 高德 Web Service Key
• 自主规划使用小红书搜索时需要有效 Cookie

指定笔记模式读取公开笔记页面时不要求用户填写 Cookie；页面触发登录或风控验证时会明确失败。

配置

参考 .env.example 配置 IDE、Shell 或部署平台环境变量：

AI_DASHSCOPE_ENABLED=true
AI_DASHSCOPE_API_KEY=your_dashscope_key_here
AI_DASHSCOPE_CHAT_MODEL=qwen-plus
AI_TRACE_ENABLED=true
AI_TRACE_DIR=./logs/ai-trace

AMAP_ENABLED=true
AMAP_KEY=your_amap_web_service_key_here

XHS_ENABLED=true
XHS_MODE=tool
XHS_COOKIE=your_xhs_cookie_here
XHS_SIGN_DIR=classpath:xhs_sign

DB_URL=jdbc:mysql://localhost:3306/tripstar?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
DB_USERNAME=root
DB_PASSWORD=

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DATABASE=0
REDIS_PASSWORD=

XHS_MODE 可选值：

小红书签名资源已内置：

modules/content/src/main/resources/xhs_sign/

启动

git clone https://github.com/LeeFly-cn/TripStar-Java.git
cd TripStar-Java
mvn -DskipTests package
java -jar app/target/app-0.0.1-SNAPSHOT.jar

Windows PowerShell：

$env:JAVA_HOME="C:\path\to\jdk-21"
$env:Path="$env:JAVA_HOME\bin;$env:Path"
mvn -DskipTests package
java -jar app\target\app-0.0.1-SNAPSHOT.jar

默认地址：http://localhost:8080

启动前端

git clone https://github.com/LeeFly-cn/TripStar-Frontend.git
cd TripStar-Frontend
cp .env.example .env
npm install
npm run dev

前端默认地址：http://localhost:5173

API

自主规划请求

{
  "city": "昆明",
  "cities": [{ "city": "昆明", "days": 3 }],
  "start_date": "2026-08-01",
  "end_date": "2026-08-03",
  "travel_days": 3,
  "transportation": "公共交通",
  "accommodation": "交通方便的舒适型酒店",
  "preferences": ["自然风光", "本地美食"],
  "free_text_input": "带老人，不想太累，不去滇池",
  "language": "zh"
}

指定笔记请求

{
  "share_text": "小红书分享内容、长链接或短链，可填写多个",
  "note_content": "也可以直接粘贴攻略正文",
  "requirement": "不去滇池，保留笔记中的全部景点",
  "start_date": "2026-08-01"
}

两个接口都会立即返回 task_id，后续通过状态接口或 WebSocket 获取进度和最终结果。

AI Trace

logs/ai-trace/yyyy-MM-dd/*.md

每个 Trace 文件包含：

• Agent 名称与 threadId
• 系统提示词
• 用户提示词
• 可用工具
• 模型原始输出
• 调用耗时与状态

排查 Agent 未调用工具、Structured Output 失败、Prompt 约束冲突或数据分类错误时，优先查看对应 taskId 的 Trace。

前端能力

独立前端仓库提供：

• 自主规划与指定笔记规划双入口
• WebSocket 真实阶段进度
• 每日行程、酒店、三餐、天气和预算
• 高德与 Google 地图切换
• 真实道路路线规划
• 景点图片卡片与 1-1 / 1-2 路线序号
• 知识图谱
• 攻略图片与 PDF 导出
• 中文、英文、日文界面
• 运行时模型、地图和小红书配置

学习文档

• 代码运行导读
• Agent 学习指南
• 指定笔记规划实现指南

推荐阅读顺序：

1. TripController
2. TripTaskService
3. TripResearchService
4. XhsNoteResearchService
5. XhsNoteMapResearchService
6. TripAiPlannerService
7. AiAgentService
8. AiStructuredOutputService
9. AiPromptTraceService

注意事项

• 小红书网页接口和签名规则可能变化，请遵守平台协议、法律法规和合理请求频率。
• 不要提交真实 Cookie、API Key、.env、runtime_settings.json、Trace 日志或临时图片。
• LLM 规划结果仅作为旅行建议，营业时间、票价、天气和交通信息请在出发前再次确认。

License

本项目使用 GPL-2.0 协议开源。