mrsunjc/TravelPilot-agent-skills

智能旅行规划助手

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

平台兼容

• 核心规范只依赖本文件、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，并运行：

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 行程摘要：

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。在发布精确计划前运行：

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 和未解决问题，并按顺序验证：

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

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

保存计划与愿望清单

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

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

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