# Travel Planner

> 生成可执行、少折返且有证据支撑的城市或多地旅行计划，并可输出易读的 SVG 行程信息图与宿主可选的 AI 旅行封面。适用于用户只提供目的地和天数，或进一步提供日期、出发地、返程时间、必去/不去景点、同行人、预算和游玩强度时；负责实时调研景点、开放与预约、按地理区域和交通时间编排每日路线、推荐住宿与餐饮、估算预算、准备天气/闭馆备选、检查返程风险，并通过结构化数据、证据绑定、确定性质量门和跨 Agent 交接检查阻止不可靠方案。Use for evidence-backed itinerary planning, route optimization, trip budgets, lodging areas, transport, live attraction checks, travel validation, visual itinerary summaries, and replanning.

- Skill: `mrsunjc/travel-planner` (Agent Skill, multi-file: 33 files)
- Install (CLI): `npx skillmds@latest add mrsunjc/travel-planner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mrsunjc/travel-planner/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: mrsunjc (https://skillmd.com/u/mrsunjc)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/mrsunjc/travel-planner

---


# 智能旅行规划助手

把调研结果转成真正能执行的日程，而不是简单罗列热门景点。第一优先级是路线合理：先建立位置与交通关系，再决定每天去哪以及先后顺序。

## 平台兼容

- 核心规范只依赖本文件、`references/`、`schemas/` 和 Python 3 标准库脚本；不要假定存在某个厂商专属工具。
- 使用当前 Agent 可用的搜索、浏览器、地图、天气和文件工具。某类工具不可用时，继续完成方案并明确降级项。
- 确定性 SVG 信息图不依赖图片模型；AI 封面只调用宿主已经提供的生图工具或用户明确配置的图片 API，不复制任何厂商私有系统 Skill。
- `agents/openai.yaml` 只是 OpenAI/Codex 的可选界面元数据，其他 Agent 可以忽略。
- 不把 API key、令牌、证件号或预订凭据写入 Skill、计划文件、命令、日志或回复。地图服务密钥只能由宿主通过环境变量或安全凭据存储提供。

## 最小输入规则

用户只说“洛阳，3天”也要直接生成，不得把补充问题设为前置条件。缺失信息采用以下默认值并在结果开头列出：

- 普通成年游客、正常强度、中等预算；公共交通为主，明显节时处建议打车。
- 未给日期：不生成伪精确天气；开放时间、票价和预约规则仍尽量查询最新信息，并注明核验日期。
- 未给抵离时间：按三个完整游玩日规划；最后一天保持可裁剪，并提醒补充车次/航班后可二次优化。
- 未给出发城市：只规划抵达当地交通枢纽后的路线。
- 地名有歧义时，选择最常见含义，清楚写出假设并允许用户一句话纠正。

只有在错误假设会造成高风险或目的地无法识别时才必须追问。其余问题可以在交付完整初版后作为可选优化项询问。

## 工作流

### 1. 解析需求

提取目的地、天数/日期、出发城市、抵离枢纽与时间、同行人、强度、预算、住宿偏好、必去和排除景点。读取 `references/planning-rules.md` 确定默认值、强度上限和特殊人群约束。

### 2. 实时调研

先建立候选景点池，再核验票价、开放时间、闭馆日、预约、临时关闭、季节限制和适合时段。提供具体日期时查天气，并只在可靠预报期内给出逐日天气。

必须读取并遵守 `references/research-policy.md`。优先官方来源；关键动态事实注明来源与核验日期。无法联网时不得编造精确数字，要标为“待核验”或范围估计。

宿主没有同类工具而需要标准化 API 数据时，读取 `references/api-providers.md` 并使用 `scripts/provider_client.py`。当前支持：

- 高德：国内地理编码、景点搜索、步行/公交/驾车路线；密钥只能来自 `AMAP_API_KEY`。
- Open-Meteo：最多 16 天的逐日天气规范化。
- Nominatim：仅在用户/开发者明确接受官方使用政策、提供缓存目录时进行单次地理编码；禁止自动补全和批量抓取。

API 输出只是研究证据，不等于景点官方票务或开放公告。票价、预约、闭馆和紧急信息仍需优先核验一手来源。

### 3. 景点分级

按城市代表性、独特性、用户兴趣、口碑稳定性、游览成本和路线代价分成：

- 必去：第一次到访时最能代表目的地，且与用户约束相容。
- 推荐：值得去，但可因距离、天气或兴趣替换。
- 可选：填充空档或适合特定偏好，行程紧时优先删除。

用户指定的必去项不能静默删除；用户明确不想去的项不能出现在主方案中。

### 4. 建立空间与交通模型

这是排程前置条件，不得先写 Day 1 再补交通：

1. 为景点、候选住宿区、车站/机场建立坐标或地图位置。
2. 获取相关时段的点到点距离、预计时间、换乘次数与大致费用；地图路径优先于直线距离。
3. 按自然片区聚类，如城北、老城、城南或相邻街区；不要只根据行政区名。
4. 比较步行、公共交通、打车/网约车；结合人数与节省时间选择，而非固定偏爱某一种方式。
5. 每天以一个主片区为核心，通常只允许一次有方向的跨区移动；避免上午城北、下午城南、晚上又回城北。

数据较多时，把研究结果整理成 JSON，并运行：

```bash
python scripts/validate_schema.py trip_input.json --schema schemas/route-input.schema.json
python scripts/route_optimizer.py trip_input.json --output optimized_route.json
```

脚本使用已提供的真实交通矩阵；没有矩阵时退化为坐标/片区估算并在输出中标记，不能把估算冒充地图实测。

### 5. 编排每日行程

- 将同片区或相邻片区安排在同一天；远郊核心景点通常单独占半天或一天。
- 先安排受预约、闭馆日、时段或天气制约的项目，再安排弹性项目。
- 上午放排队敏感、户外或需要体力的项目；下午衔接同片区；夜景、古城和夜市放在晚上。
- 给出每站建议到达时间、游玩时长、下一段距离/时间/方式，以及顺路吃饭区域。
- 留出用餐、排队、休息和不可预测缓冲；不要把所有空白都填满。
- 最后一天减少高风险远距离移动，路线向返程枢纽靠拢，并给出最迟离开时间和缓冲。

### 6. 补全住宿、餐饮、预算与保障

推荐 1–3 个住宿区域而非随意点名酒店，说明到主要片区和交通枢纽的便利性。列出当地代表性美食和每天顺路的用餐区域，避免要求游客为一顿饭跨城。

预算按住宿、餐饮、市内交通、门票、往返大交通和机动金分类，区分“已核验价格”“估算”和“不含项”。提供天气对应的衣物/防晒/雨具清单、避坑提醒、行李寄存策略、医院与紧急服务信息，以及下雨或闭馆备用方案。

### 7. 最终审计

交付前逐项检查：

- 是否有跨城折返、重复经过同一区域或交通成本异常的路线。
- 每日景点数、游览时间、交通时间和步行量是否符合强度。
- 景点在计划日期和到达时段是否开放，预约是否来得及。
- 夜间项目是否确实适合晚上；餐饮是否顺路。
- 天气与户外项目是否冲突；主方案不可行时是否有明确替代。
- 最后一天是否满足退房、寄存、取行李和返程缓冲。
- 所有精确动态事实是否有来源/核验日期，所有估算是否已标注。

有结构化路线时运行 `route_optimizer.py` 后检查其 `audit`；`errors` 必须解决，`warnings` 必须修正或向用户解释。随后按 `schemas/final-plan.schema.json` 生成最终结构化计划，不能只靠自然语言自检。

### 8. 输出、可视化与迭代

读取 `references/output-contract.md`，按其结构输出。先给总览和每天具体路线，再给证据、预算与注意事项，不要让用户在长篇调研中寻找结论。

读取 `references/visual-output.md`。最终结构化计划完成质量检查后，在宿主能够保存或展示本地文件且用户未要求纯文字时，生成确定性 SVG 行程摘要：

```bash
python scripts/travel_visualizer.py final-plan.json --output trip-overview.svg
```

- SVG 中的时间、地点、交通和预算必须来自最终计划，不能交给图片模型重新编写。
- 质量门存在 `error` 时不得生成看似已核验的最终信息图；只有 `warning` 时在图中保留待核验提示。
- 宿主有图片生成工具且用户希望获得更强视觉效果时，可额外生成无文字的城市封面，再通过 `--cover-image` 嵌入 SVG。
- 宿主没有生图工具时只生成 SVG，不把 AI 生图设为运行前提。
- 用户明确要求纯文字、无文件输出时跳过可视化。

用户增加必去/排除景点、改变同行人或说“不想去某个景点”时，重新执行空间分组、排程和审计，而不是只在原文中局部替换名称。

## 机器质量门

读取 `references/data-contracts.md` 和 `references/quality-gates.md`。在发布精确计划前运行：

```bash
python scripts/validate_plan.py final_plan.json --output quality-report.json
```

质量门检查 Schema、敏感字段、声明—证据绑定、证据时效与权威性、必去/排除项、开放与预约、时间重叠、交通间隔、片区折返、强度、恶劣天气备用、预算合计、住宿、紧急来源和返程缓冲。

- `passed=false` 或存在 `error`：不得把计划描述为已经核验；修正后重跑。
- 只有 `warning`：可以交付，但要在最终审计摘要中逐条解释降级和用户需要复核的内容。
- `verified` 声明必须通过证据中的 `value_digest` 绑定；修改声明值后必须重新核验来源并更新绑定，不能只重算摘要冒充复核。
- 没有实时数据时把状态写为 `estimated` 或 `unverified`，给出方法/待核验项；不要伪造证据以通过质量门。

## 多 Agent / 跨模型交接

只有宿主确实启用多个角色或模型时才拆分研究、路线、排程、预算和审计。每次交接使用 `schemas/handoff.schema.json`，保留假设、证据 ID 和未解决问题，并按顺序验证：

```bash
python scripts/validate_handoff.py research.json route.json schedule.json
```

交接摘要通过 `content_digest` 防止静默修改；父级未解决问题必须由子级继续携带或明确标记已解决。单 Agent 场景不需要制造虚假的多 Agent 文件。

## 保存计划与愿望清单

只有用户要求保存或已明确启用持久化时才写文件。先读取 `references/persistence.md`。数据必须保存在 Skill 目录之外，并通过 `--root` 或 `TRAVEL_PLANNER_DATA_DIR` 明确指定：

```bash
python scripts/plan_store.py --root <data-directory> save --plan optimized_route.json
python scripts/plan_store.py --root <data-directory> list-plans
python scripts/plan_store.py --root <data-directory> wishlist-add --destination "洛阳"
python scripts/plan_store.py --root <data-directory> wishlist-list
```

保存前移除无关个人信息；脚本会拒绝常见敏感字段。