# travelagent67 — 旅行规划智能体 v2

## 架构概述

```
用户请求
  │
  ▼
┌──────────────────────────────────────────────────┐
│  多 MCP 数据源 (SSE 建链)                          │
│  ┌──────────┐  ┌──────────────┐  ┌────────────┐  │
│  │ 高德地图   │  │ Google Maps  │  │ 大众点评    │  │
│  │ (国内首选) │  │ (海外备用)    │  │ (餐饮补充)  │  │
│  │ priority:1│  │ priority:2   │  │ priority:3 │  │
│  └─────┬────┘  └──────┬───────┘  └─────┬──────┘  │
│        └───────────────┼───────────────┘          │
│                        │ tools/list                │
└────────────────────────┼─────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────┐
│  用户偏好记忆层 (memory)                            │
│  预算 | 饮食禁忌 | 出行方式 | 住宿 | 游览节奏       │
└────────────────────────┼─────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────┐
│  ReAct Agent Loop (最多 30 轮, 并行工具调用)         │
│                                                  │
│  阶段0:偏好 → 阶段1:侦察 → 阶段2:POI采集           │
│  → 阶段3:编排 → 阶段4:校验 → 阶段5:JSON            │
│                                                  │
│  ┌───────────┐    ┌──────────────┐               │
│  │ LLM 推理   │───▶│ tool_calls?  │               │
│  │ (Thought)  │    │  Y: 并行调工具│  ──▶ SSE 推送  │
│  └───────────┘    │  N: 输出JSON  │     进度到前端  │
│       ▲           └──────┬───────┘               │
│       │                  │                       │
│       └──── 结果回灌 ◀───┘                       │
└────────────────────────┼─────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────┐
│  后处理校验层 (postProcess)                         │
│  ✓ 营业时间校验    ✓ 天气适配校验                    │
│  ✓ 时间冲突检测    ✓ 预算校验                       │
│  ✓ 通勤时间校验    ✓ 重复地点检测                    │
│  ──────────────────────────────                  │
│  error → 拒绝并重试  |  warning → 追加提醒           │
└────────────────────────┼─────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────┐
│  输出解析                                         │
│  1. 代码块清洗 (去除 ```json```)                   │
│  2. 提取 JSON 块 ({...})                         │
│  3. 尝试根对象 → ItineraryPlan                    │
│  4. 回退 data.itinerary / itinerary              │
└────────────────────────┼─────────────────────────┘
                         │
                         ▼
                  ItineraryPlan JSON
```

---

## v1 → v2 改进对照

| 改进方向 | v1 状态 | v2 实现 | 配置位置 |
|---|---|---|---|
| **多数据源** | 仅高德，海外不可用 | 高德 + Google Maps + 大众点评，优先级链式 fallback | `mcp.remoteServers[*].priority` |
| **流式体验** | 同步阻塞，无进度反馈 | SSE 推送六阶段进度 + 工具调用事件 | `streaming.events` |
| **用户偏好** | 无记忆，每次从零开始 | memory 持久化偏好（预算/饮食/出行/住宿/兴趣），30天有效 | `memory` + `memory.schema` |
| **增量编辑** | 全量重跑，无法局部修改 | 识别修改指令，仅验证受影响 POI，保持其余不变 | `systemPrompt` 增量编辑模式 |
| **行程校验** | 仅通勤时间约束 | 6 项后处理校验器（营业时间/天气/冲突/预算/通勤/重复） | `postProcess.validators` |
| **并行工具** | 串行，每轮1个工具 | `maxConcurrent: 5`，无依赖工具同轮并行 | `mcp.policy.maxConcurrent` |
| **成本控制** | 固定 $0.50 总预算 | CEK 引擎 + 7 个阶段预算 + 超额自动降级模型 | `runtime.stageBudgets` |

---

## App 亮点 — 实现机制解读

> 以下从产品视角说明"AI 行程规划"功能的核心卖点及其背后的技术实现。

### 亮点一：每个推荐地点都是真实的，不是 AI 编的

**用户感知**：生成的行程中每个景点、餐厅、酒店都能在地图上找到，点击即可导航。

**实现机制**：Agent 通过 MCP 协议实时连接三大地图数据源（高德/Google/大众点评），所有地点均来自真实查询结果。系统提示词设置"反幻觉"硬约束 + 后处理重复检测校验器双重保障。

### 亮点二：行程动线合理，不走冤枉路

**用户感知**：同一天的景点彼此不远，不会出现上午故宫、下午八达岭的离谱安排。

**实现机制**：逐日编排阶段要求同日行程地理聚集，`maps_driving`/`maps_transit` 验证通勤 ≤ 1h。后处理层的 `transit_duration_check` 校验器做二次确认。

### 亮点三：AI 会看天气再安排行程

**用户感知**：下雨天自动安排室内景点，晴天安排户外活动。

**实现机制**：宏观侦察阶段调用 `maps_weather` 查天气，编排阶段据此动态调整。后处理层的 `weather_adaptation_check` 校验器确保雨天不超过 1 个户外景点。

### 亮点四：一次生成完整行程，精确到经纬度

**用户感知**：生成结果直接可用于地图渲染，前端无需二次查询。

**实现机制**：v2 的 JSON Schema 更丰富 —— 除经纬度外，还包含 `timeSlot`（时间段）、`transitToNext`（到下一站的交通方式和时间）、`estimatedCost`（单项费用），前端可渲染带时间轴的地图路线。

### 亮点五：实时看到 AI 在干什么

**用户感知**：等待时不再焦虑 —— 能看到"正在查询天气..."、"正在搜索景点..."、"正在验证路线..."的实时进度。

**实现机制**：SSE streaming 配置监听 Agent 输出中的 `[STAGE:X/5]` 标记和 tool_call/tool_result 事件，实时推送给前端，展示六阶段进度条和当前操作。

### 亮点六：记住你的偏好，越用越懂你

**用户感知**：第二次使用时不需要重复说"我吃素"、"预算有限"，AI 已经记住了。

**实现机制**：memory 模块按用户隔离，持久化 6 个偏好维度（预算/饮食/出行/住宿/兴趣/节奏），30 天有效。阶段〇自动检查历史偏好，仅对缺失项向用户确认。

### 亮点七：想改哪天改哪天，不用重新生成

**用户感知**：说一句"第二天午餐换成火锅"，只改那一项，其余行程不变。

**实现机制**：增量编辑模式解析修改指令（第几天/第几项/操作类型），仅对修改涉及的 POI 做工具查询验证，保持未修改部分不变。避免全量重跑的资源浪费和行程漂移。

### 亮点八：网络抖动不怕，多源兜底

**用户感知**：不管网络多不稳定，行程都能正常生成。

**实现机制**：3 层容错 —— 单工具 3 次重试 + 指数退避；高德失败自动切 Google Maps；三源均失败则从已采集候选列表替代。绝不因单次网络问题中断整个规划。

---

## 优点

### 1. 多数据源冗余架构
三个 MCP 远程服务按优先级链式 fallback：高德（国内全覆盖） → Google Maps（海外覆盖） → 大众点评（餐饮深度信息）。单一数据源故障不影响整体可用性，且国内外目的地均可支持。

### 2. 六阶段结构化规划
从 v1 的四阶段升级为六阶段（新增偏好采集 + 行程校验），每个阶段有明确目标、工具策略和进度标记。规划过程完全可观测、可调试。

### 3. 并行工具调用
`maxConcurrent: 5` 允许单轮内并行发起多个无依赖的工具调用（如同时搜索景点/美食/酒店），将 POI 采集阶段的耗时从串行的 N 轮压缩到 ceil(N/5) 轮。

### 4. 用户偏好记忆
跨会话持久化 6 个偏好维度，30 天有效。第二次使用时自动加载已有偏好，仅确认缺失项。越用越精准，减少沟通成本。

### 5. 后处理校验层
6 个独立校验器（营业时间/天气适配/时间冲突/预算/通勤/重复）在 JSON 生成后做结构化验证。error 级别问题自动拒绝并要求模型重新生成，warning 级别追加到行程 tips 中提醒用户。

### 6. 增量编辑能力
支持"修改第 N 天第 M 项"的局部更新，仅对修改涉及的 POI 做工具查询和路线验证。避免全量重跑带来的资源浪费、延迟和行程漂移。

### 7. 分阶段成本控制
CEK 引擎支持 7 个阶段预算（偏好 $0.03 / 侦察 $0.05 / 采集 $0.25 / 编排 $0.20 / 校验 $0.15 / 输出 $0.05 / 预留 $0.07），超出阶段预算时自动从 qwen-max 降级到 qwen-plus 继续执行，兼顾质量与成本。

### 8. 流式进度推送
SSE streaming 实时推送六阶段进度和工具调用事件到前端，用户在等待时能看到 AI 当前在做什么，大幅降低等待焦虑感。

---

## 仍存在的局限

### 1. 延迟仍然较高
虽然并行工具调用减少了轮次，但六阶段流水线 + 后处理校验 + 可能的重试，整体延迟仍在 2-4 分钟级别。对于"随便帮我规划一下"的轻量需求，等待时间偏长。

### 2. Prompt 工程脆弱性
六阶段策略、增量编辑模式、并行工具引导、多数据源切换均依赖 system prompt 的约束力。换模型（如从 qwen-max 到 GPT-4o）可能需要重新调优 prompt。

### 3. 后处理校验为声明式伪代码
`postProcess.validators` 中的 rule 是语义描述而非可执行代码，需要运行时框架实现对应的校验逻辑。当前 lambdagent 框架尚未原生支持 postProcess，需要在应用层（如 Java 后端）额外实现。

### 4. Google Maps / 大众点评 MCP 依赖外部部署
高德有官方 MCP 服务 (`mcp.amap.com`)，但 Google Maps 和大众点评的 MCP 服务需要自行搭建或使用第三方封装，增加了部署复杂度。

### 5. 偏好采集可能增加交互轮次
阶段〇的偏好确认需要用户回答问题，对于希望"一句话直接出结果"的用户可能感到繁琐。需要平衡个性化精度和交互简洁性。
