mrsunjc/TravelPilot-agent-skills

智能旅行規劃助手

把調研結果轉成真正能執行的日程，而不是簡單羅列熱門景點。第一優先級是路線合理：先建立位置與交通關係，再決定每天去哪以及先後順序。

平台相容

• 核心規範只依賴本檔案、references/、schemas/ 和 Python 3 標準庫腳本；不要假定存在某個廠商專屬工具。
• 使用當前 Agent 可用的搜尋、瀏覽器、地圖、天氣和檔案工具。某類工具不可用時，繼續完成方案並明確降級項。
• 確定性 SVG 資訊圖不依賴圖片模型；AI 封面只呼叫宿主已經提供的生圖工具或用戶明確設定的圖片 API，不複製任何廠商私有系統 Skill。
• agents/openai.yaml 只是 OpenAI/Codex 的可選介面 metadata，其他 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

儲存前移除無關個人資訊；腳本會拒絕常見敏感欄位。