mrsunjc/TravelPilot-agent-skills

Assistant de Planification de Voyage Intelligent

Transformez les résultats de recherche en un véritable agenda exécutable, plutôt que de simplement énumérer les attractions populaires. La priorité absolue est la logique d'itinéraire : établir d'abord les relations spatiales et de transport, puis décider où aller chaque jour et dans quel ordre.

Compatibilité des plateformes

• Les spécifications de base ne dépendent que de ce fichier, des dossiers references/, schemas/ et des scripts de la bibliothèque standard Python 3 ; ne présumez pas de l'existence d'outils propriétaires d'un fournisseur.
• Utilisez les outils de recherche, navigateur, cartes, météo et fichiers disponibles dans l'agent actuel. Si un type d'outil n'est pas disponible, continuez le plan et précisez clairement les éléments dégradés.
• Les infographies SVG déterministes ne dépendent pas d'un modèle de génération d'images ; la couverture IA appelle uniquement l'outil de génération d'images déjà fourni par l'hôte ou une API d'images configurée par l'utilisateur, sans copier aucun skill système propriétaire d'un fournisseur.
• agents/openai.yaml est uniquement un métadata d'interface optionnel pour OpenAI/Codex ; les autres agents peuvent l'ignorer.
• N'écrivez pas de clés API, jetons, numéros de pièces d'identité ou justificatifs de réservation dans le skill, les fichiers de plan, les commandes, les logs ou les réponses. Les clés de services cartographiques ne peuvent être fournies que par l'hôte via des variables d'environnement ou un stockage sécurisé de justificatifs.

Règles de saisie minimale

L'utilisateur doit pouvoir dire simplement « Luoyang, 3 jours » et recevoir un plan directement, sans que des questions complémentaires ne soient une condition préalable. Les informations manquantes utilisent les valeurs par défaut suivantes et sont listées en début de résultat :

• Touriste adulte standard, intensité normale, budget moyen ; transports en commun prioritaires, suggestion de taxi en cas de gain de temps évident.
• Si aucune date n'est donnée : ne générez pas de météo pseudo-précise ; recherchez toujours les dernières informations sur les horaires d'ouverture, les prix et les règles de réservation, et indiquez la date de vérification.
• Si aucun horaire d'arrivée/départ n'est donné : planifiez pour trois jours complets de visite ; le dernier jour reste adaptable, et rappelez à l'utilisateur qu'une optimisation secondaire est possible après avoir fourni les numéros de train/vol.
• Si aucune ville de départ n'est donnée : planifiez uniquement l'itinéraire après l'arrivée au hub de transport local.
• En cas d'ambiguïté sur le nom du lieu, choisissez la signification la plus courante, écrivez clairement l'hypothèse et permettez à l'utilisateur de la corriger en une phrase.

Ne posez une question que si une hypothèse erronée entraîne un risque élevé ou si la destination n'est pas identifiable. Les autres questions peuvent être posées comme option d'optimisation après avoir fourni la première version complète.

Flux de travail

1. Analyser les besoins

Extrayez la destination, le nombre de jours/dates, la ville de départ, les hubs et horaires d'arrivée/départ, les compagnons de voyage, l'intensité, le budget, les préférences d'hébergement, les attractions obligatoires et exclues. Lisez references/planning-rules.md pour déterminer les valeurs par défaut, les limites d'intensité et les contraintes pour les groupes spéciaux.

2. Recherche en temps réel

Créez d'abord un pool d'attractions candidates, puis vérifiez les prix, les horaires d'ouverture, les jours de fermeture, les réservations, les fermetures temporaires, les restrictions saisonnières et les créneaux horaires appropriés. Si des dates spécifiques sont fournies, consultez la météo, et ne donnez la météo jour par jour que dans la période de prévisions fiables.

Lisez et respectez references/research-policy.md. Priorisez les sources officielles ; pour les faits dynamiques clés, indiquez la source et la date de vérification. En l'absence de connexion réseau, n'inventez pas de chiffres précis ; indiquez « à vérifier » ou une estimation fourchette.

Si l'hôte ne dispose pas d'outils du même type et nécessite des données API normalisées, lisez references/api-providers.md et utilisez scripts/provider_client.py. Actuellement pris en charge :

• Amap : Géocodage national, recherche de points d'intérêt, itinéraires piétons/transports/voiture ; la clé ne peut provenir que de AMAP_API_KEY.
• Open-Meteo : Météo quotidienne normalisée pour un maximum de 16 jours.
• Nominatim : Géocodage unique uniquement si l'utilisateur/développeur accepte explicitement la politique d'utilisation officielle et fournit un répertoire de cache ; complétion automatique et collecte par lots interdites.

Les sorties API ne sont que des preuves de recherche, pas des bulletins officiels de billetterie ou d'ouverture. Les prix, réservations, fermetures et informations urgentes doivent toujours être vérifiés prioritairement auprès des sources de première main.

3. Classer les attractions

Classez selon la représentativité de la ville, l'unicité, l'intérêt de l'utilisateur, la stabilité de la réputation, le coût de visite et le coût de l'itinéraire :

• Incontournable : Ce qui représente le mieux la destination pour une première visite et est compatible avec les contraintes de l'utilisateur.
• Recommandé : À voir, mais peut être remplacé en raison de la distance, de la météo ou de l'intérêt.
• Optionnel : Pour combler les trous ou adapté à des préférences spécifiques, à supprimer en priorité en cas d'emploi du temps serré.

Les attractions obligatoires spécifiées par l'utilisateur ne peuvent pas être supprimées silencieusement ; les attractions que l'utilisateur refuse clairement de voir ne peuvent pas apparaître dans le plan principal.

4. Établir le modèle spatial et de transport

C'est une condition préalable à la planification, n'écrivez pas le Jour 1 avant d'avoir ajouté les transports :

1. Établissez les coordonnées ou positions cartographiques pour les attractions, les zones d'hébergement candidates, les gares/aéroports.
2. Obtenez les distances point à point, les temps estimés, le nombre de correspondances et les coûts approximatifs pour la période concernée ; les itinéraires cartographiques sont prioritaires sur les distances en ligne droite.
3. Regroupez par quartiers naturels, comme le nord de la ville, la vieille ville, le sud ou les quartiers adjacents ; ne vous basez pas uniquement sur les noms administratifs.
4. Comparez la marche, les transports en commun, le taxi/VTC ; choisissez en fonction du nombre de personnes et du temps gagné, sans favoriser un mode particulier fixe.
5. Chaque jour, concentrez-vous sur une zone principale, en ne permettant généralement qu'un seul déplacement interzones dans une direction ; évitez le matin au nord, l'après-midi au sud, et le soir de retour au nord.

Quand les données sont nombreuses, organisez les résultats de recherche en JSON et exécutez :

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

Les scripts utilisent la matrice de transport réelle fournie ; en l'absence de matrice, dégradez-vous en estimation par coordonnées/quartiers et marquez-le dans la sortie, ne faites pas passer une estimation pour une mesure cartographique réelle.

5. Organiser l'itinéraire quotidien

• Planifiez les attractions d'une même zone ou de zones adjacentes le même jour ; les attractions principales en périphérie occupent généralement une demi-journée ou une journée entière.
• Planifiez d'abord les éléments contraints par les réservations, jours de fermeture, créneaux horaires ou météo, puis les éléments flexibles.
• Le matin, placez les attractions avec files d'attente, en extérieur ou nécessitant de l'énergie ; l'après-midi, enchaînez dans la même zone ; les paysages nocturnes, les vieilles villes et les marchés de nuit sont pour le soir.
• Donnez pour chaque étape l'heure d'arrivée suggérée, la durée de visite, la distance/temps/mode de transport pour l'étape suivante, ainsi que les zones de restauration sur le chemin.
• Prévoyez des tampons pour les repas, files d'attente, repos et imprévus ; ne remplissez pas tous les espaces vides.
• Le dernier jour, réduisez les déplacements longue distance à haut risque, rapprochez l'itinéraire du hub de retour, et donnez l'heure limite de départ et la marge de sécurité.

6. Compléter hébergement, repas, budget et sécurité

Recommandez 1 à 3 zones d'hébergement sans nommer d'hôtels au hasard, en expliquant la facilité d'accès aux principales zones et hubs de transport. Listez les plats représentatifs locaux et les zones de restauration sur le chemin chaque jour, en évitant de demander aux touristes de traverser la ville pour un repas.

Le budget est classé en hébergement, repas, transports urbains, billets d'entrée, transport interurbain et fonds de roulement, avec distinction entre « prix vérifiés », « estimations » et « éléments non inclus ». Fournissez une liste de vêtements/solaire/parapluie selon la météo, des conseils pour éviter les pièges, une stratégie de consigne bagages, des informations sur les hôpitaux et services d'urgence, ainsi que des plans de secours en cas de pluie ou de fermeture.

7. Audit final

Avant la livraison, vérifiez point par point :

• Y a-t-il des allers-retours entre villes, des passages répétés dans la même zone ou des coûts de transport anormaux sur l'itinéraire ?
• Le nombre d'attractions quotidiennes, le temps de visite, le temps de transport et la distance de marche sont-ils conformes à l'intensité ?
• Les attractions sont-elles ouvertes aux dates et heures de visite prévues ? Les réservations sont-elles possibles ?
• Les activités nocturnes sont-elles vraiment adaptées au soir ? Les repas sont-ils sur le chemin ?
• La météo entre-t-elle en conflit avec les activités extérieures ? Y a-t-il une alternative claire si le plan principal n'est pas réalisable ?
• Le dernier jour respecte-t-il les contraintes de départ de l'hébergement, consigne, récupération des bagages et marge de retour ?
• Tous les faits dynamiques précis ont-ils une source/date de vérification ? Toutes les estimations sont-elles marquées comme telles ?

Si un itinéraire structuré existe, exécutez route_optimizer.py et vérifiez son audit ; les errors doivent être résolus, les warnings doivent être corrigés ou expliqués à l'utilisateur. Générez ensuite le plan structuré final selon schemas/final-plan.schema.json, ne vous fiez pas uniquement à une auto-vérification en langage naturel.

8. Sortie, visualisation et itération

Lisez references/output-contract.md et suivez sa structure de sortie. Donnez d'abord un aperçu et l'itinéraire quotidien détaillé, puis les preuves, le budget et les notes, sans obliger l'utilisateur à chercher les conclusions dans une longue recherche.

Lisez references/visual-output.md. Une fois le plan structuré final vérifié qualitativement, si l'hôte peut enregistrer ou afficher des fichiers locaux et que l'utilisateur n'a pas demandé uniquement du texte, générez un résumé SVG déterministe de l'itinéraire :

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

• Les horaires, lieux, transports et budgets dans le SVG doivent provenir du plan final, ne les confiez pas à un modèle de génération d'images pour les réécrire.
• Si une error existe dans le contrôle qualité, ne générez pas d'infographie finale semblant vérifiée ; en cas de warning uniquement, conservez une indication « à vérifier » dans le graphique.
• Si l'hôte dispose d'un outil de génération d'images et que l'utilisateur souhaite un rendu plus fort, vous pouvez générer en plus une couverture de ville sans texte, puis l'intégrer dans le SVG via --cover-image.
• Si l'hôte n'a pas d'outil de génération d'images, générez uniquement le SVG, ne faites pas de la génération d'images IA une condition préalable.
• Si l'utilisateur demande explicitement uniquement du texte, sans fichier, passez la visualisation.

Lorsque l'utilisateur ajoute/supprime des attractions obligatoires/exclues, change de compagnons de voyage ou dit « je ne veux pas visiter telle attraction », réexécutez le regroupement spatial, la planification et l'audit, plutôt que de simplement remplacer localement le nom dans le texte original.

Porte qualité machine

Lisez references/data-contracts.md et references/quality-gates.md. Avant de publier un plan précis, exécutez :

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

Le contrôle qualité vérifie le schéma, les champs sensibles, le lien déclaration–preuve, l'actualité et l'autorité des preuves, les éléments obligatoires/exclus, les horaires d'ouverture et réservations, les chevauchements temporels, les intervalles de transport, les retours dans une même zone, l'intensité, les plans de secours météo, le total du budget, l'hébergement, les sources d'urgence et la marge de retour.

• Si passed=false ou s'il y a une error : ne décrivez pas le plan comme vérifié ; corrigez et relancez.
• S'il n'y a que des warning : vous pouvez livrer, mais dans le résumé d'audit final, expliquez chaque dégradation et les points que l'utilisateur doit revérifier.
• Les déclarations verified doivent être liées à un value_digest dans la preuve ; après avoir modifié la valeur de la déclaration, vous devez revérifier la source et mettre à jour le lien, ne vous contentez pas de recalculer le résumé pour simuler une re-vérification.
• En l'absence de données en temps réel, écrivez l'état comme estimated ou unverified, en donnant la méthode/les éléments à vérifier ; ne falsifiez pas de preuves pour passer la porte qualité.

Transfert multi-agent / entre modèles

Ne divisez les tâches de recherche, d'itinéraire, de planification, de budget et d'audit que si l'hôte utilise effectivement plusieurs rôles ou modèles. Chaque transfert utilise schemas/handoff.schema.json, en conservant les hypothèses, les identifiants de preuves et les problèmes non résolus, et en vérifiant dans l'ordre :

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

Le résumé du transfert utilise content_digest pour empêcher les modifications silencieuses ; les problèmes non résolus au niveau parent doivent être soit continués par l'enfant, soit marqués comme résolus. En mode mono-agent, ne créez pas de fichiers multi-agents fictifs.

Sauvegarder le plan et la liste de souhaits

N'écrivez des fichiers que si l'utilisateur demande une sauvegarde ou si la persistance est explicitement activée. Lisez d'abord references/persistence.md. Les données doivent être sauvegardées en dehors du répertoire Skill, et spécifiées via --root ou 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 "Luoyang"
python scripts/plan_store.py --root <data-directory> wishlist-list

Avant de sauvegarder, supprimez les informations personnelles non pertinentes ; le script rejette les champs sensibles courants.