# 基于 Multi-Agent 的智能规划助手：项目说明文档

## 1. 项目简介

本项目是一个面向真实出行场景的智能路线规划系统。用户通过自然语言输入城市、预算、同行人、偏好、节奏和餐饮要求，系统会先进行多轮需求理解与澄清，再生成可执行的行程大纲与详细路线，并结合真实地图 POI、交通耗时、预算和备选方案输出结果。

项目的核心目标不是“给一个推荐列表”，而是输出一条**可执行、可解释、可局部微调**的完整行程：
- 可执行：每段有真实 POI、时长、预算、交通方式和地图坐标
- 可解释：每个点位都能说明为什么选它、为什么没选别的
- 可微调：用户可以对某一段、某一阶段或某一天做局部修改，而不是整条路线推倒重来

---

## 2. 项目核心功能

### 2.1 对话式需求理解
- 用户直接使用自然语言描述需求，无需复杂表单
- 系统支持多轮追问，补齐住宿区域、交通偏好、忌口、节奏偏好等关键信息
- 当信息不足时，返回澄清问题；当信息充分时，进入规划阶段

### 2.2 行程大纲确认
- 在真正生成细节前，系统会先给出一版大纲（按天的主题与重点）
- 用户可以：
  - 直接确认并展开详细行程
  - 先微调大纲方向，再继续生成
- 这样可以减少路线走偏后整体返工

### 2.3 多 Agent 路线规划
- 多个 Agent 分工协作完成需求理解、候选召回、时间分配、路线生成、问题检查、修复与润色
- 规划过程不是单次“黑盒生成”，而是分阶段、多轮约束下的协同产物

### 2.4 地图化结果展示
- 前端会在地图上展示真实 POI 标点
- 支持点击节点查看详情卡片
- 支持调用高德路线能力显示节点间真实道路路径，而不是简单直线
- 不同出行方式（步行 / 地铁 / 打车等）可透出到结果中

### 2.5 结果解释与备选方案
- 每个站点包含：
  - 为什么选它
  - 决策依据 / decision trace
  - 候选备选项
  - 为什么没选备选
  - 如何换成备选
- 让路线规划过程更透明，而非只给出结论

### 2.6 局部修改与重规划
- 支持针对某个站点、某个阶段、某一天发起 revise
- 支持在执行过程中基于已完成站点进行 replan
- 支持“只改当前目标，保留其他部分不变”的局部调整方式

### 2.7 Demo / 预设演示能力
- 提供独立地图预览页，用于验证真实 POI 和路线
- 提供 scripted demo 页面，用于演示完整对话、规划、解释与微调流程

---

## 3. 整体架构

项目采用**前后端分离 + Multi-Agent 协同规划**的方式实现。

### 3.1 前端
技术栈：Next.js 14、React 18、TypeScript、Tailwind CSS、Zod

职责：
- 接收用户自然语言输入
- 展示多轮对话、澄清问题、大纲、进度条、地图和行程卡片
- 通过 `/api/*` 代理与后端交互
- 调用高德地图前端 JS SDK 与路线代理接口渲染地图

### 3.2 后端
技术栈：FastAPI、Pydantic v2、LangGraph、Anthropic Claude API、Httpx

职责：
- 统一承担规划逻辑
- 管理多 Agent 工作流
- 负责需求理解、候选 POI 召回、路线生成、批判修复、行程组织和结果结构化
- 对外提供 `/route`、`/replan`、`/revise`、`/conversation`、`/plan`、`/itinerary` 等接口

### 3.3 数据与外部能力
- 高德地图 / AMap：POI 搜索、地理编码、路线能力
- 本地 `map-cli`：部分地图数据与路线辅助能力
- Mock UGC / 用户画像：用于补充候选点评分和长期偏好示意

---

## 4. 后端 Agent 体系

后端不是单个“大模型函数”，而是一组职责清晰的 Agent 协同工作。

### 4.1 IntentAgent（意图理解 Agent）
文件：`backend/agents/intent.py`

职责：
- 解析用户的 `RouteRequest`
- 提取结构化 intent
- 构建搜索计划 `search_plan`
- 注入模拟的长期用户画像
- 识别显式餐饮意图、偏好与避雷项

输入：
- `RouteRequest`

输出：
- `intent`
- `search_plan`
- `user_profile`

它是整个规划流程的第一步，相当于“把自然语言需求翻译成规划系统内部可执行的结构化目标”。

### 4.2 RetrievalAgent（候选召回 Agent）
文件：`backend/agents/retrieval.py`

职责：
- 根据 `search_plan` 召回候选 POI
- 地理编码出发点
- 优先处理显式指定地点
- 整合高德 / map-cli 搜索结果
- 使用 UGC 与用户画像做轻量打分补充
- 生成 `candidate_pois`

输入：
- `search_plan`
- `start_location`
- `user_profile`

输出：
- `candidate_pois`
- `start_location_location`

这是“找素材”的环节，为后续排路线提供可选点位池。

### 4.3 SchedulerAgent（时段调度 Agent）
文件：`backend/agents/scheduler.py`

职责：
- 将一天切分成多个规划时段（早餐、上午、午餐、下午、晚餐等）
- 做区域聚类（area clusters）
- 为每一天选择主要活动区域
- 为每个时段分配候选集合 `slot_candidates`

输入：
- `candidate_pois`
- 用户时长 / 节奏约束

输出：
- `day_slots`
- `slot_plan`
- `area_clusters`
- `day_area_plans`
- `slot_candidates`

它负责把“点位池”组织成“按天、按时段可调度”的结构。

### 4.4 RouteAgent（路线生成 Agent）
文件：`backend/agents/route.py`

职责：
- 在候选集中挑选具体 POI 填入每个时段
- 同时尝试**确定性规则方案**与**LLM 方案**
- 比较后选择更优路线
- 生成：
  - `day_route_plan`
  - `draft_stops`
  - `phase_results`

输入：
- `slot_candidates`
- `day_area_plans`
- 约束条件

输出：
- `draft_stops`
- `route_plan`
- `phase_results`

这是路线真正“成形”的地方，是从候选到具体停留站点的核心步骤。

### 4.5 CriticAgent（批判检查 Agent）
文件：`backend/agents/critic.py`

职责：
- 检查当前路线是否存在问题，例如：
  - 时长超出
  - 预算超出
  - 重复点位
  - 已完成点位被重复选回
  - 区域切换过多
  - 路线回头太多
  - 用餐点偏离主路线太远
  - 节奏或主题单一

输入：
- `draft_stops`
- `route_plan`

输出：
- `issues`

它像一个“质量审查员”，不生成新路线，但会指出当前路线的缺陷。

### 4.6 RepairAgent（修复 Agent）
文件：`backend/agents/repair.py`

职责：
- 根据 CriticAgent 提出的 `issues` 生成最小修复动作
- 替换不合适的点位或顺序
- 尽量在不破坏整体路线的前提下完成修复
- 回写 `draft_stops`

输入：
- `issues`
- `draft_stops`

输出：
- 修复后的 `draft_stops`
- `repair_plan`

RepairAgent 与 CriticAgent 形成“问题发现 -> 局部修复”的循环。

### 4.7 NarrationAgent（结果润色 Agent）
文件：`backend/agents/narration.py`

职责：
- 将内部规划结果转成用户可读的 `RouteResponse`
- 为每个 stop 补充：
  - `reason`
  - `tips`
- 生成整体 `summary`

输入：
- `draft_stops`
- 规划上下文

输出：
- `RouteResponse`

它负责把“工程结构化路线”转成真正适合用户阅读的结果。

### 4.8 ConversationAgent（对话规划 Agent）
文件：`backend/agents/conversation.py`

职责：
- 管理多轮对话与槽位补齐
- 判断当前是：
  - 普通聊天 `chat_reply`
  - 还需澄清 `need_clarification`
  - 给出大纲 `outline_pending`
  - 已可正式规划 `ready`
- 构建 `TripBrief` / `resolved_brief`
- 输出大纲 `outline`

输入：
- `messages`
- `user_id`

输出：
- `PlannerResponse` 相关中间结果

它是 `/plan` 统一入口的上层“大脑”，决定什么时候该继续问、什么时候该先出大纲、什么时候可以真正规划。

### 4.9 ItineraryAgent（多日行程组织 Agent）
文件：`backend/agents/itinerary.py`

职责：
- 在 `TripBrief` 与每日候选基础上组织多日 `ItineraryResponse`
- 保证 segment 的结构完整：
  - `location`
  - `travel_mode`
  - `travel_distance_km`
  - `travel_time_min`
  - `decision_trace`
  - `alternatives`
- 做多日层面的后处理：
  - 去重
  - 补足餐食覆盖
  - 补全可渲染坐标
  - 回酒店收尾点
  - 规范交通字段

输入：
- `TripBrief`
- `candidate_pois`
- `day_contexts`

输出：
- `ItineraryResponse`

它负责把“每天一条 route”提升成“完整的多日旅行 itinerary”。

### 4.10 ScoringAgent（评分 Agent）
文件：`backend/agents/scoring.py`

职责：
- 对 itinerary 或 route 做评分
- 作为 `ItineraryPlanner` 的重试与优选依据

输入：
- itinerary / route

输出：
- 评分结果 / review 结果

它让系统不仅能“生成”，还能在多种可能方案中挑更好的那一版。

### 4.11 LLMClient（模型调用封装）
文件：`backend/agents/llm.py`

职责：
- 提供统一的大模型调用接口
- 处理超时、429、重试、JSON 代码块去壳等细节
- 被多个 Agent 复用

---

## 5. 后端 Agent 协作方式

### 5.1 `/route` 单日路线工作流
核心工作流定义在：`backend/planner/graph.py`

调用链如下：

`Intent -> Retrieval -> Scheduler -> Route -> Critic -> (Repair <-> Critic)* -> Narration`

说明：
1. IntentAgent 理解需求
2. RetrievalAgent 召回候选
3. SchedulerAgent 做时段与区域规划
4. RouteAgent 生成实际路线
5. CriticAgent 检查问题
6. 若有问题，RepairAgent 修复，再回到 Critic 复检
7. 无问题后，NarrationAgent 输出最终结果

这套链路通过 LangGraph 编排，最多允许 2 轮 repair。

### 5.2 `/plan` 对话式多日规划工作流
`/plan` 不直接进入 route graph，而是分两层：

#### 第一层：ConversationAgent
负责：
- 多轮对话理解
- 槽位补齐
- 澄清问题生成
- 行程大纲生成
- 判断是否进入正式规划

#### 第二层：ItineraryPlanner + RoutePlannerGraph
当 ConversationAgent 判断 `status = ready` 时：
- 先构建 `TripBrief`
- 再按天调用 RoutePlannerGraph 生成每日候选路线
- 最后交给 ItineraryAgent 组织成完整 itinerary

也就是说：
- `/route` 更像“直接给我一条路线”
- `/plan` 更像“先聊清楚，再先出大纲，再展开成详细多日行程”

### 5.3 `/revise` 局部修改机制
文件：`backend/planner/replan.py`

特点：
- 不重新跑整条 LangGraph
- 直接基于当前 route / itinerary 做局部替换
- 可以针对：
  - stop
  - phase
  - day
- 会优先利用 alternatives 做局部改写

适用场景：
- “这个点我不喜欢，换一个”
- “午饭想更近一点”
- “这一天节奏想更松一点”

### 5.4 `/replan` 剩余路段重规划机制
特点：
- 基于 `completed_stops` 重新规划剩余路段
- 适合执行过程中的动态变化
- 如天气变化、时间不足、预算变化等

适用场景：
- “前面已经走完了，后面重新排”
- “下雨了，剩下路线改室内”
- “预算不足，后续改便宜一些”

---

## 6. 前端结构与主要能力

### 6.1 主页面与核心组件
- 页面入口：`frontend/src/app/page.tsx`
- 主组件：`frontend/src/components/PlannerChat.tsx`

前端承担：
- 聊天输入与消息展示
- 澄清问题按钮
- 大纲确认
- 进度展示
- 结果页（地图 + 行程卡片）
- revise/replan 的交互入口与结果更新

### 6.2 地图能力
核心组件：`frontend/src/components/ItineraryMapCard.tsx`

能力：
- 加载高德地图 JS SDK
- 根据 itinerary 的 `location` 绘制 marker
- 点击 marker 查看详情卡片
- 调用 `/api/map-route` 查询真实道路路线
- 根据不同交通方式展示不同路径效果

### 6.3 行程卡片能力
核心组件：`frontend/src/components/ItineraryDayCard.tsx`

能力：
- 展示每一天主题与站点顺序
- 展示原因、交通、预算、提示、评分
- 展开查看候选备选项
- 支持“换成这个备选”发起 revise

### 6.4 局部修改面板
核心组件：`frontend/src/components/ItineraryRevisionPanel.tsx`

能力：
- 输入自由文本修改要求
- 选择保留其他部分不变
- 一键替换成候选备选项

### 6.5 预设演示页面
- `/demo`：静态完成态演示页
- `/scripted-demo`：对话式演示页，用于录制完整功能流程

---

## 7. 主要接口说明

### 后端原始接口
- `GET /health`：健康检查
- `POST /route`：单条路线生成
- `POST /replan`：剩余路段重规划
- `POST /revise`：局部修改
- `POST /conversation`：对话理解 / 槽位补齐
- `POST /plan`：统一对话式规划入口
- `POST /itinerary`：直接生成多日 itinerary

### 前端代理接口
- `POST /api/route`
- `POST /api/replan`
- `POST /api/revise`
- `POST /api/plan`
- `POST /api/map-route`

前端通过这些代理与后端联调，统一处理请求体校验和 envelope 格式。

---

## 8. 典型用户流程

### 流程 A：对话式生成多日行程
1. 用户自然语言输入需求
2. ConversationAgent 多轮澄清
3. 系统返回大纲
4. 用户确认或微调大纲
5. ItineraryPlanner 正式生成多日 itinerary
6. 前端展示地图与卡片
7. 用户查看原因、备选和真实路线

### 流程 B：结果出来后局部修改
1. 用户在某一站点展开候选
2. 点击“换成这个备选”或输入微调诉求
3. 前端调用 `/revise`
4. 后端做局部替换
5. 前端刷新 itinerary 与地图

### 流程 C：执行过程中的剩余重排
1. 用户标记已完成站点
2. 提出天气/预算/时长新变化
3. 前端调用 `/replan`
4. 后端重新规划剩余路线
5. 前端显示新的剩余路段结果

---

## 9. 项目特点与亮点

### 9.1 Multi-Agent 分工清晰
每个 Agent 都负责规划过程中的一个明确阶段，职责边界清晰，便于扩展与调试。

### 9.2 不是黑盒推荐
系统不仅给答案，还解释：
- 为什么选它
- 为什么没选别的
- 如何换成别的

### 9.3 支持“先确认方向，再出细节”
通过大纲确认机制，减少误判需求后的返工成本。

### 9.4 支持局部修改
相比整条路线重算，`/revise` 支持保留大部分成果，只修改局部，体验更接近真实产品。

### 9.5 与真实地图数据联动
POI、路线、距离、时长都尽量基于真实地图数据构建，而不是纯文本生成。

### 9.6 适合演示与扩展
项目同时具备：
- 主产品聊天流
- 独立地图预览
- scripted demo 演示页
便于开发、测试和对外汇报。

---

## 10. 当前项目目录重点

```text
/Users/bytedance/mt
├── backend/
│   ├── main.py                 # FastAPI 入口
│   ├── agents/                 # Multi-Agent 核心逻辑
│   ├── planner/                # LangGraph 工作流与 itinerary 编排
│   ├── data/                   # 地图与 POI 数据能力
│   └── schemas/                # Pydantic 数据模型
├── frontend/
│   ├── src/app/                # Next.js 页面与 API proxy
│   ├── src/components/         # 聊天、地图、卡片、revision 面板
│   ├── src/lib/                # API client、demo 数据、schemas
│   └── src/types/              # 前端共享类型
└── PROJECT_OVERVIEW.md         # 当前文档
```

---

## 11. 总结

这是一个围绕“真实可执行出行规划”构建的 Multi-Agent 智能助手项目。它将自然语言理解、地图候选召回、路线组织、质量检查、修复润色、多日 itinerary 编排和前端地图化展示整合在同一个系统中。

与只会“给建议”的普通聊天机器人相比，本项目更强调：
- 结构化规划能力
- 地图与路线真实落地
- 结果解释性
- 局部修改能力
- 多轮交互中的产品化体验