mrsunjc/TravelPilot-agent-skills

Asistente Inteligente de Planificación de Viajes

Convierte los resultados de la investigación en un itinerario verdaderamente ejecutable, no en una simple lista de lugares populares. La máxima prioridad es la lógica de la ruta: primero establece las relaciones de ubicación y transporte, luego decide a dónde ir cada día y en qué orden.

Compatibilidad de Plataformas

• El núcleo de la especificación solo depende de este archivo, references/, schemas/ y scripts de la biblioteca estándar de Python 3; no asumas la existencia de herramientas exclusivas de un proveedor.
• Utiliza las herramientas de búsqueda, navegador, mapas, clima y archivos disponibles en el agente actual. Si algún tipo de herramienta no está disponible, completa el plan e indica claramente las degradaciones.
• Los infográficos SVG deterministas no dependen de modelos de imagen; la portada de IA solo llama a las herramientas de generación de imágenes ya proporcionadas por el anfitrión o a la API de imágenes configurada explícitamente por el usuario, sin copiar ningún Skill de sistema privado del proveedor.
• agents/openai.yaml es solo metadatos de interfaz opcionales para OpenAI/Codex; otros agentes pueden ignorarlo.
• No escribas claves API, tokens, números de identificación, credenciales de reserva en el Skill, archivos de plan, comandos, registros o respuestas. Las claves del servicio de mapas solo pueden ser proporcionadas por el anfitrión a través de variables de entorno o almacenamiento seguro de credenciales.

Regla Mínima de Entrada

Incluso si el usuario solo dice "Luoyang, 3 días", debes generar directamente el plan sin establecer preguntas adicionales como condición previa. Para la información faltante, utiliza los siguientes valores predeterminados y enuméralos al comienzo del resultado:

• Turista adulto normal, intensidad normal, presupuesto medio; transporte público principalmente, sugerir taxi cuando ahorre tiempo significativamente.
• Sin fecha proporcionada: no generar un clima pseudo-preciso; aún así, intenta consultar la información más reciente sobre horarios de apertura, precios de entradas y reglas de reserva, e indica la fecha de verificación.
• Sin hora de llegada/salida: planificar como tres días completos de visita; el último día debe ser recortable y recordar al usuario que puede optimizar nuevamente después de proporcionar los detalles del tren/vuelo.
• Sin ciudad de origen: solo planificar la ruta después de llegar al centro de transporte local.
• Si el nombre del lugar es ambiguo, elige la interpretación más común, escribe claramente la suposición y permite al usuario corregirla con una sola oración.

Solo debes preguntar cuando una suposición incorrecta cause un alto riesgo o cuando el destino no sea reconocible. El resto de las preguntas se pueden hacer como opciones de optimización después de entregar la primera versión completa.

Flujo de Trabajo

1. Analizar Requisitos

Extraer destino, número de días/fechas, ciudad de origen, centro de transporte de llegada/salida y hora, acompañantes, intensidad, presupuesto, preferencias de alojamiento, atracciones obligatorias y excluidas. Leer references/planning-rules.md para determinar valores predeterminados, límites de intensidad y restricciones para grupos especiales.

2. Investigación en Tiempo Real

Primero establecer un conjunto de atracciones candidatas, luego verificar precios de entradas, horarios de apertura, días de cierre, reservas, cierres temporales, restricciones estacionales y horas adecuadas. Consultar el clima cuando se proporcionen fechas específicas, y solo dar el clima diario dentro del período de pronóstico confiable.

Debes leer y cumplir con references/research-policy.md. Priorizar fuentes oficiales; para hechos dinámicos críticos, indicar la fuente y la fecha de verificación. Si no hay conexión a internet, no inventar números precisos, sino marcarlos como "por verificar" o estimaciones de rango.

Si el anfitrión no tiene herramientas similares y necesita datos de API estandarizados, leer references/api-providers.md y usar scripts/provider_client.py. Actualmente compatible con:

• Gaode: geocodificación nacional, búsqueda de atracciones, rutas a pie/transporte público/automóvil; la clave solo puede provenir de AMAP_API_KEY.
• Open-Meteo: clima diario normalizado para un máximo de 16 días.
• Nominatim: solo para una geocodificación única cuando el usuario/desarrollador acepte explícitamente la política de uso oficial y proporcione un directorio de caché; prohibido el autocompletado y el scraping por lotes.

La salida de la API es solo evidencia de investigación, no equivale a la información oficial de boletos u horarios de apertura de las atracciones. Los precios de las entradas, reservas, cierres e información de emergencia aún deben verificarse prioritariamente en fuentes de primera mano.

3. Clasificar Atracciones

Según la representatividad de la ciudad, singularidad, interés del usuario, estabilidad de la reputación, costo de visita y costo de ruta, dividir en:

• Obligatorio: lo que mejor representa el destino para una primera visita y es compatible con las restricciones del usuario.
• Recomendado: vale la pena visitar, pero puede ser reemplazado debido a distancia, clima o intereses.
• Opcional: para llenar espacios vacíos o adecuado para preferencias específicas; eliminar primero si el itinerario está apretado.

Las atracciones obligatorias especificadas por el usuario no se pueden eliminar silenciosamente; las atracciones que el usuario ha indicado explícitamente que no quiere visitar no deben aparecer en el plan principal.

4. Establecer Modelo Espacial y de Transporte

Esta es una condición previa para la programación; no se debe escribir "Día 1" primero y luego agregar el transporte:

1. Establecer coordenadas o ubicaciones en el mapa para las atracciones, áreas de alojamiento candidatas y estaciones/aeropuertos.
2. Obtener distancias punto a punto, tiempos estimados, número de transbordos y costos aproximados para el período relevante; priorizar las rutas de mapa sobre las distancias en línea recta.
3. Agrupar por áreas naturales, como ciudad norte, ciudad vieja, ciudad sur o barrios adyacentes; no basarse solo en nombres de distritos administrativos.
4. Comparar caminar, transporte público, taxi/transporte privado; elegir según el número de personas y el tiempo ahorrado, no por una preferencia fija por un modo.
5. Cada día, centrarse en un área principal; normalmente solo se permite un movimiento entre áreas con dirección; evitar: mañana en el norte, tarde en el sur y noche de nuevo al norte.

Cuando haya muchos datos, organizar los resultados de la investigación en JSON y ejecutar:

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

Los scripts utilizan la matriz de transporte real ya proporcionada; si no hay matriz, degenerar a estimaciones de coordenadas/áreas y marcarlo en la salida; no se puede hacer pasar estimaciones como mediciones reales del mapa.

5. Organizar Itinerario Diario

• Colocar atracciones en la misma área o áreas adyacentes el mismo día; las atracciones principales en las afueras generalmente ocupan medio día o un día completo.
• Primero programar elementos sujetos a reservas, días de cierre, horarios o clima, luego los elementos flexibles.
• Por la mañana, colocar actividades sensibles a las colas, al aire libre o que requieran esfuerzo físico; por la tarde, conectar con la misma área; actividades nocturnas, ciudades antiguas y mercados nocturnos por la noche.
• Proporcionar hora de llegada sugerida, duración de la visita, distancia/tiempo/modo al siguiente lugar y áreas para comer de paso.
• Dejar espacio para comidas, colas, descanso y amortiguadores impredecibles; no llenar todos los espacios en blanco.
• El último día, reducir los movimientos de larga distancia de alto riesgo; la ruta debe acercarse al centro de transporte de salida y proporcionar la hora límite de salida y un amortiguador.

6. Completar Alojamiento, Comida, Presupuesto y Garantías

Recomendar 1–3 áreas de alojamiento en lugar de nombrar hoteles al azar, explicando la conveniencia para las áreas principales y los centros de transporte. Listar la gastronomía local representativa y las áreas para comer de paso cada día, evitando pedir a los turistas que crucen la ciudad para una comida.

El presupuesto debe clasificarse en alojamiento, comidas, transporte dentro de la ciudad, entradas, transporte interurbano de ida y vuelta, y fondos de contingencia, distinguiendo entre "precio verificado", "estimado" y "no incluido". Proporcionar una lista de ropa, protector solar y paraguas según el clima, consejos para evitar trampas, estrategias de almacenamiento de equipaje, información del hospital y servicios de emergencia, y planes de respaldo para lluvia o cierres.

7. Auditoría Final

Antes de entregar, verificar punto por punto:

• ¿Hay rutas que crucen la ciudad y vuelvan, pasen repetidamente por la misma área o tengan costos de transporte anormales?
• ¿El número de atracciones por día, el tiempo de visita, el tiempo de transporte y la distancia a pie son adecuados para la intensidad?
• ¿Las atracciones están abiertas en la fecha y hora de visita planificadas? ¿La reserva es posible a tiempo?
• ¿Las actividades nocturnas son realmente adecuadas para la noche? ¿La comida está de paso?
• ¿Hay conflicto entre el clima y las actividades al aire libre? ¿Hay alternativas claras si el plan principal no es factible?
• ¿El último día cumple con el check-out, almacenamiento de equipaje, recogida de maletas y amortiguador de regreso?
• ¿Todos los hechos dinámicos precisos tienen fuente/fecha de verificación? ¿Todas las estimaciones están marcadas?

Si hay una ruta estructurada, ejecutar route_optimizer.py y verificar su audit; los errores deben resolverse, las advertencias deben corregirse o explicarse al usuario. Luego generar el plan estructurado final según schemas/final-plan.schema.json; no confiar solo en la autoinspección en lenguaje natural.

8. Salida, Visualización e Iteración

Leer references/output-contract.md y generar la salida según su estructura. Primero dar una visión general y la ruta específica de cada día, luego la evidencia, el presupuesto y las notas; no hacer que el usuario busque conclusiones en una investigación larga.

Leer references/visual-output.md. Una vez que el plan estructurado final haya pasado la verificación de calidad, si el anfitrión puede guardar o mostrar archivos locales y el usuario no ha solicitado solo texto, generar un resumen SVG determinista del itinerario:

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

• El tiempo, lugar, transporte y presupuesto en el SVG deben provenir del plan final, no pueden ser reescritos por el modelo de imagen.
• Si la compuerta de calidad tiene error, no generar infografía final que parezca verificada; si solo hay advertencia, mantener la nota de "por verificar" en el gráfico.
• Si el anfitrión tiene una herramienta de generación de imágenes y el usuario desea efectos visuales más fuertes, se puede generar adicionalmente una portada de ciudad sin texto, y luego incrustarla en SVG mediante --cover-image.
• Si el anfitrión no tiene herramienta de generación de imágenes, solo generar SVG; no hacer de la generación de imágenes por IA una condición previa para la ejecución.
• Si el usuario solicita explícitamente solo texto o sin salida de archivos, omitir la visualización.

Cuando el usuario agregue atracciones obligatorias/excluidas, cambie de acompañantes o diga "no quiero ir a esta atracción", re-ejecutar la agrupación espacial, programación y auditoría, no solo reemplazar nombres localmente en el texto.

Compuertas de Calidad Automatizadas

Leer references/data-contracts.md y references/quality-gates.md. Antes de publicar un plan preciso, ejecutar:

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

Las compuertas de calidad verifican Schema, campos sensibles, vinculación de declaración-evidencia, actualidad y autoridad de la evidencia, elementos obligatorios/excluidos, apertura y reservas, superposición de tiempo, intervalos de transporte, retrocesos de área, intensidad, plan de respaldo para mal tiempo, total del presupuesto, alojamiento, fuente de emergencia y amortiguador de regreso.

• passed=false o existencia de error: no describir el plan como verificado; corregir y volver a ejecutar.
• Solo advertencia: se puede entregar, pero en el resumen de la auditoría final, explicar punto por punto las degradaciones y lo que el usuario necesita revisar.
• La declaración verified debe estar vinculada a través de value_digest en la evidencia; después de modificar el valor de la declaración, se debe volver a verificar la fuente y actualizar el vínculo; no solo recalcular el resumen para pretender una revisión.
• Si no hay datos en tiempo real, escribir el estado como estimated o unverified, proporcionar métodos/elementos por verificar; no fabricar evidencia para pasar las compuertas de calidad.

Intercambio Multi-Agente/Entre Modelos

Solo dividir la investigación, ruta, programación, presupuesto y auditoría cuando el anfitrión realmente active múltiples roles o modelos. Cada intercambio debe usar schemas/handoff.schema.json, conservando suposiciones, ID de evidencia y problemas no resueltos, y verificar en orden:

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

El resumen del intercambio previene modificaciones silenciosas a través de content_digest; los problemas no resueltos del nivel padre deben ser llevados por el nivel hijo o marcados explícitamente como resueltos. En un escenario de un solo agente, no es necesario crear archivos falsos de múltiples agentes.

Guardar Plan y Lista de Deseos

Solo escribir archivos cuando el usuario solicite guardar o haya activado explícitamente la persistencia. Primero, leer references/persistence.md. Los datos deben guardarse fuera del directorio del Skill y especificarse explícitamente mediante --root o 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

Antes de guardar, eliminar información personal irrelevante; el script rechazará campos sensibles comunes.