mrsunjc/TravelPilot-agent-skills

スマート旅行計画アシスタント

調査結果を実際に実行可能なスケジュールに変換します。単に人気スポットを列挙するだけではありません。最優先事項はルートの合理性です。まず位置と交通の関係を確立し、その後に毎日の行き先と順序を決定します。

プラットフォーム互換性

• コア仕様はこのファイル、references/、schemas/、および Python 3 標準ライブラリのスクリプトのみに依存します。特定ベンダーの専用ツールを前提としないでください。
• 現在のエージェントが利用可能な検索、ブラウザ、地図、天気、ファイルツールを使用します。特定のツールが利用できない場合は、プランを継続し、明確にダウングレード項目を明記します。
• 確定 SVG インフォグラフィックは画像モデルに依存しません。AI カバー画像は、ホストが既に提供している画像生成ツールか、ユーザーが明示的に設定した画像 API のみを呼び出します。ベンダー独自のシステムスキルをコピーしないでください。
• agents/openai.yaml は OpenAI/Codex 向けのオプションのインターフェースメタデータであり、他のエージェントは無視して構いません。
• API キー、トークン、ID 番号、予約証明書をスキル、計画ファイル、コマンド、ログ、返信に書き込まないでください。地図サービスのキーは、ホストが環境変数または安全な資格情報ストアを介してのみ提供します。

最小入力ルール

ユーザーが「洛陽、3日」とだけ言った場合でも、直接生成します。追加の質問を前提条件としないでください。不足情報には以下のデフォルト値を使用し、結果の先頭にリストします。

• 一般成人観光客、標準的な強度、中程度の予算。公共交通機関が主体ですが、明らかに時間短縮になる場合はタクシーを提案します。
• 日付未指定：正確な天気予報は生成しません。ただし、営業時間、料金、予約ルールは可能な限り最新情報を取得し、確認日を明記します。
• 到着/出発時間未指定：丸 3 日間の観光日として計画します。最終日は調整可能とし、便名/便名を補足すれば再最適化できることを伝えます。
• 出発都市未指定：到着交通ハブ以降のルートのみを計画します。
• 地名にあいまいさがある場合は、最も一般的な意味を選択し、仮定を明確に書き出して、ユーザーが一言で訂正できるようにします。

誤った仮定が高いリスクを引き起こす場合、または目的地が認識できない場合にのみ、質問を必須とします。それ以外の質問は、完全な初版を提供した後に、オプションの改善点として尋ねることができます。

ワークフロー

1. 要件の解析

目的地、日数/日付、出発都市、到着/出発ハブと時間、同行者、強度、予算、宿泊の好み、必須および除外スポットを抽出します。references/planning-rules.md を読み込み、デフォルト値、強度上限、特別なグループの制約を決定します。

2. リアルタイム調査

まず候補スポットプールを確立し、次に料金、営業時間、休館日、予約、臨時閉鎖、季節制限、適した時間帯を確認します。具体的な日付が指定された場合は天気を確認し、信頼できる予報期間内に限り日ごとの天気を提供します。

references/research-policy.md を読み込み、遵守する必要があります。公式ソースを優先します。重要な動的事実にはソースと確認日を明記します。インターネットに接続できない場合は、正確な数字をでっち上げず、「未確認」または範囲推定とマークします。

ホストに同等のツールがなく、標準化された API データが必要な場合は、references/api-providers.md を読み込み、scripts/provider_client.py を使用します。現在サポートしているのは以下のとおりです。

• 高徳（AMap）：国内のジオコーディング、スポット検索、徒歩/バス/車のルート。キーは AMAP_API_KEY からのみ取得できます。
• Open-Meteo：最大 16 日間の日次天気の標準化されたデータ。
• Nominatim：ユーザー/開発者が公式利用ポリシーを明示的に受け入れ、キャッシュディレクトリを提供する場合にのみ、単一のジオコーディングを許可します。オートコンプリートやバルクスクレイピングは禁止です。

API 出力は調査の証拠にすぎず、スポットの公式チケット販売や営業案内を意味するものではありません。料金、予約、休館、緊急情報は、引き続き一次ソースを優先して確認する必要があります。

3. スポットのグレード分け

都市の代表性、独自性、ユーザーの興味、口コミの安定性、訪問コスト、ルートの負荷に基づいて、以下のように分類します。

• 必須：初めて訪れる際に目的地を最もよく代表し、ユーザーの制約と両立するもの。
• 推奨：訪れる価値はあるが、距離、天候、興味によって代替可能。
• オプション：空いた時間を埋めたり、特定の好みに適したもの。日程が詰まっている場合は優先的に削除。

ユーザーが指定した必須スポットを黙って削除してはいけません。ユーザーが明示的に行きたくないと述べたスポットをメインプランに含めてはいけません。

4. 空間と交通モデルの構築

これはスケジューリングの前提条件です。先に Day 1 を書いてから交通を補完してはいけません。

1. スポット、候補宿泊エリア、駅/空港の座標または地図上の位置を取得します。
2. 関連する時間帯におけるポイント間の距離、所要時間、乗り換え回数、おおよその料金を取得します。地図上のルートを直線距離よりも優先します。
3. 自然なエリア（城北、旧市街、城南、隣接する街区など）でクラスタリングします。行政区名だけで判断しないでください。
4. 徒歩、公共交通機関、タクシー/ライドシェアを比較します。人数と時間節約を考慮して選択し、特定の手段に固定的に偏らないようにします。
5. 毎日、1 つの主要エリアを中心に据え、通常は方向性のあるエリア間移動を 1 回のみ許可します。午前中に城北、午後に城南、夜にまた城北に戻るようなことは避けます。

データが多い場合は、調査結果を 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. 日次の旅程の編成

• 同じエリアまたは隣接エリアのスポットを同じ日に配置します。遠方の主要スポットは、通常、半日または 1 日を別途割り当てます。
• 予約、休館日、時間帯、天候に制約される項目を最初に配置し、その後に柔軟な項目を配置します。
• 午前中には、待ち時間が発生しやすい、屋外、または体力を要するアクティビティを配置します。午後は同じエリア内でつなげます。夜景、旧市街、夜市は夜に配置します。
• 各スポットへの推奨到着時間、滞在時間、次のスポットまでの距離/時間/手段、および途中の食事エリアを提供します。
• 食事、待ち時間、休憩、予測不能なバッファの時間を確保します。すべての空き時間を埋め尽くさないでください。
• 最終日は、リスクの高い長距離移動を減らし、ルートを帰路のハブに近づけ、最終出発時間とバッファを提供します。

6. 宿泊、食事、予算、およびサポートの補完

ホテル名を適当に挙げるのではなく、1～3 つの宿泊エリアを推薦し、主要エリアや交通ハブへのアクセスの良さを説明します。地元の代表的な料理と、毎日のルート沿いの食事エリアをリストアップします。旅行者が一食のために都市をまたぐ必要があるような提案は避けます。

予算は、宿泊、食事、市内交通、入場料、往復の長距離交通、予備費に分類し、「確認済み価格」「推定」「含まれない項目」を区別します。天候に応じた服装/日焼け止め/傘のリスト、注意点、荷物預け戦略、病院と緊急サービス情報、雨天または閉館時の代替案を提供します。

7. 最終監査

納品前に以下を項目ごとにチェックします。

• 都市間の往復、同じエリアの重複通過、または異常に高い交通コストのルートがないか。
• 1 日あたりのスポット数、観光時間、移動時間、徒歩量が強度に見合っているか。
• スポットが計画日と到着時間帯に開いており、予約が間に合うか。
• 夜間のアクティビティが実際に夜に適しているか。食事がルート沿いか。
• 天候と屋外アクティビティが矛盾していないか。メインプランが実行不可能な場合に明確な代替案があるか。
• 最終日がチェックアウト、荷物預け、荷物受け取り、帰路のバッファに対応しているか。
• すべての正確な動的事実にソース/確認日があるか。すべての推定値にマークが付いているか。

構造化ルートがある場合は、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

品質ゲートは、スキーマ、機密フィールド、宣言-証拠バインディング、証拠の鮮度と信頼性、必須/除外項目、営業時間と予約、時間的重複、交通間隔、エリアの往復、強度、悪天候時の代替案、予算合計、宿泊、緊急ソース、帰路バッファをチェックします。

• passed=false または error がある場合：計画を確認済みと説明してはいけません。修正して再実行します。
• warning のみの場合：納品は可能ですが、最終監査サマリーで各ダウングレード項目とユーザーが確認すべき内容を説明する必要があります。
• verified 宣言は、証拠内の value_digest を介してバインドされている必要があります。宣言値を変更した後は、ソースを再確認してバインディングを更新する必要があります。サマリーを再計算して再確認を偽装してはいけません。
• リアルタイムデータがない場合は、状態を estimated または unverified とし、方法/未確認項目を提供します。品質ゲートを通過するために証拠を偽造してはいけません。

マルチエージェント / クロスモデルハンドオフ

ホストが実際に複数のロールまたはモデルを有効にしている場合にのみ、調査、ルート、スケジューリング、予算、監査を分割します。各ハンドオフには schemas/handoff.schema.json を使用し、仮定、証拠 ID、未解決問題を保持し、順番に検証します。

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

ハンドオフサマリーは content_digest を介して、静かな変更を防ぎます。親の未解決問題は、子が引き続き保持するか、解決済みとして明確にマークする必要があります。シングルエージェントシナリオで、偽のマルチエージェントファイルを作成する必要はありません。

計画とウィッシュリストの保存

ユーザーが保存を要求した場合、または永続化が明示的に有効になっている場合にのみ、ファイルに書き込みます。最初に references/persistence.md を読み込みます。データはスキルディレクトリの外部に保存し、--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

保存前に関係のない個人情報を削除します。スクリプトは一般的な機密フィールドを拒否します。