YuanMenghe/trip-cheat-sheet

TripCheat · Experto en planificación de viajes con IA (trip-cheat-sheet)

Convierte los materiales dispersos del usuario (vuelos, hoteles, agendas de conferencias, entradas, capturas de pantalla de guías y conversaciones) en una página web portátil: Línea de tiempo del itinerario (¿a dónde ir hoy a qué hora?), listas de verificación (¿qué no olvidar?), manual (cómo moverse/cómo pagar/a quién llamar si hay problemas). Se abre directamente en el móvil, con doble huso horario, tema oscuro, ajuste de tamaño de letra, enlaces profundos a mapas, códigos QR para entradas y se puede desplegar en cualquier hosting estático.

La página se construye a partir de un único archivo trip.json mediante el generador incluido en esta skill. El contrato de datos está en references/trip-schema.md, las normas de redacción en references/content-guide.md, y el despliegue en references/deploy.md.

Cuándo usarla

Escenarios de activación

• «Ayúdame a hacer un itinerario», «Organiza los billetes de avión, el hotel y la agenda de la conferencia en una página», «Preparativos para un viaje de negocios/asistencia a una conferencia»
• «Guía de viaje», «Página portátil», «Manual de viaje», «Lista de viaje», «Qué hacer cada día»
• El usuario proporciona capturas de pantalla / PDFs / correos / enlaces / conversaciones que necesitan ser estructurados + investigados complementariamente + convertidos en una página consultable desde el móvil
• Ya existe un trip.json: se quiere regenerar la página, cambiar el tema, añadir una puerta de contraseña, desplegarla o compartir páginas de entradas

No aplica

• Solo se necesita consultar información sobre una atracción, el tiempo o reservar algo: se busca/responde directamente, no hace falta crear una página
• Se necesita inventario en tiempo real, realizar un pedido, pagar o facturar online: esta skill no se conecta a APIs de reservas, solo organiza información y enlaces
• Navegación pura de rutas: usar herramientas de mapas, no se necesita una página de itinerario

Resultados

Modo	Comando	Resultado
Archivo único (por defecto)	node scripts/build.mjs trip.json --out dist	dist/index.html (CSS/JS/datos/manifest PWA todo incrustado) + imágenes de entradas copiadas si es necesario
Sitio multi-página	node scripts/build.mjs trip.json --multi --out dist	dist/index.html, dist/ticket-<id>.html, dist/assets/style.css, dist/assets/app.js, dist/manifest.json, recursos de entradas copiados

Capacidades de la página: tres vistas (línea de tiempo del itinerario / listas de verificación / manual); resaltado de «evento actual/siguiente»; reloj de doble huso horario y conversión de hora; temas (paper/slate/night) y cambio de tamaño de letra; enlaces profundos a Google/Gaode/Apple Maps (los enlaces de ruta de Google incluyen parámetro de modo de transporte); marcado de elementos en listas de verificación (localStorage); páginas de códigos QR para entradas; puerta de contraseña opcional (verificación SHA-256 en frontend); se puede añadir a la pantalla de inicio (PWA, desactivar con --no-pwa).

Flujo de trabajo (6 pasos)

Paso 1: Recopilación de datos (cuestionario + archivos/capturas/enlaces)

Primero pregunta, máximo 6 preguntas, evitar preguntas en cadena; si el usuario no responde, usar suposiciones por defecto y marcarlas explícitamente como «suposición».

• Quién va, cuántas personas, relación (si los acompañantes necesitan atención a mayores/niños/accesibilidad)
• Lugar de origen, fechas (incluyendo días consecutivos/vuelos nocturnos), destino(s) (si son varias ciudades/escala)
• Qué está reservado, qué queda por reservar (vuelos, hotel, registro de conferencia, entradas, restaurante)
• Horas clave de la conferencia/evento (registro, inauguración, propia ponencia/póster, cena)
• Preferencias y límites (presupuesto, restricciones dietéticas/alergias, ritmo de viaje, qué se quiere omitir)
• Requisitos de privacidad (si se va a compartir públicamente, si se necesita puerta de contraseña, qué información no puede subirse a internet)

Recopilar materiales: capturas de pantalla, PDFs, correos, conversaciones, enlaces, todo vale. Primero organizar en una lista de hechos antes de escribir el JSON, no adivinar mientras se recopila.

Paso 2: Investigación profunda (con conexión, diferenciar «confirmado» de «por verificar»)

Investigar por prioridad y anotar los enlaces de las fuentes y la fecha de verificación:

Prioridad	Contenido de la investigación
P0	Visado/vigencia del pasaporte, vuelos/trenes, alojamiento, registro de conferencia/entradas, seguro
P1	Transporte aeropuerto ↔ centro urbano (último autobús/tren, terminal), billetes de transporte urbano, reserva horaria de entradas, reserva de restaurante
P2	Atracciones, compras, planes alternativos, tiempo meteorológico

• Priorizar fuentes oficiales: aerolíneas/aeropuertos/ferrocarriles, hoteles, web de la conferencia, web de museos/atracciones, embajadas/consulados, operadores de transporte.
• Clasificar cada información clave en cuatro categorías: Confirmado / Por verificar / Sin confirmar / Ejemplo (reglas en references/content-guide.md §6).
• No inventar precios, horarios, horarios de apertura, estado de reservas; si no se encuentra, escribir «por verificar» y dar una nota aclaratoria de «consultar la fuente oficial».
• Errores comunes (transporte aeropuerto, reserva de entradas, WiFi, pagos, teléfonos de emergencia, huso horario/horario de verano) revisar uno por uno e incluirlos en el manual o en la descripción del evento.

Paso 3: Escribir trip.json

Seguir estrictamente references/trip-schema.md; se puede consultar directamente el ejemplo examples/tokyo-conference/trip.json.

• meta: título, subtítulo, lugar de residencia habitual (home), fechas de inicio y fin, tema, proveedor de mapas, pie de página (escribir la fecha de corte de los datos).
• destinations: cada destino con un id + huso horario IANA (ej. Asia/Tokyo).
• days[].events: cada evento debe tener al menos time / title / short / detail / kind; si tiene ubicación, escribir location + map; si tiene enlaces oficiales, escribir links; si se puede asociar a una lista de verificación, escribir checkId.
• checklists: agrupar por fases (antes de salir / después de llegar / durante el viaje / antes de regresar), id único global.
• handbook: secciones sobre transporte, red, pagos, seguridad y emergencias, asistencia a la conferencia, alimentación, equipaje, etc. (se pueden combinar/añadir, pero no omitir temas).
• tickets: uno por persona, qr apunta a una imagen placeholder o a una imagen proporcionada por el usuario (no introducir códigos reales de entradas).

Reglas de doble huso horario (lo que más se confunde)

1. time / endTime son siempre la hora local del evento; si no se especifica tz, se hereda el huso horario del destino de ese día.
2. Para vuelos que cruzan husos horarios, tz indica el huso horario del lugar de salida, y endTime también se interpreta según ese tz. Si se combina en un solo evento de vuelo, endTime debe ser el valor de la hora de aterrizaje convertido al huso horario del lugar de salida, y en detail se debe escribir claramente «hora local de aterrizaje: HH:MM»; una forma más sencilla es dividir la salida y la llegada en dos eventos, cada uno con su propio huso horario local.
3. Las llegadas al día siguiente se colocan en days[] del día siguiente, y en detail se escribe «+1 día» / «día siguiente»; si endTime de un evento que cruza la medianoche es menor que time, se tratará como día siguiente, pero se recomienda añadir una explicación textual.
4. Para eventos de día completo sin hora concreta, usar skipTimezone: true; los husos horarios deben escribirse siempre con nombre IANA, no UTC+9, JST.
5. La página convertirá automáticamente las horas al huso horario del lugar de residencia habitual, no reescribir manualmente la conversión en el texto, a menos que se trate de algo como «apertura de facturación online» o «reunión remota» que deba hacerse antes de salir según la hora del lugar de residencia habitual.

Paso 4: Construcción

Ejecutar en el directorio raíz de la skill (el que contiene scripts/, templates/); el script resuelve las rutas relativas al directorio de trabajo actual, también se puede ejecutar desde cualquier directorio usando rutas completas.

node scripts/build.mjs <trip.json> --out dist

Parámetros comunes:

# Sitio multi-página (genera ticket-<id>.html que se puede compartir individualmente)
node scripts/build.mjs trip.json --multi --out dist

# Sobrescribir tema / añadir puerta de contraseña / desactivar PWA / sobrescribir directorio de salida no vacío / modo silencioso
node scripts/build.mjs trip.json --theme night --gate-password "tu-contraseña" --out dist
node scripts/build.mjs trip.json --no-pwa --out dist
node scripts/build.mjs trip.json --force --quiet --out dist

• Por defecto genera dist/index.html; --out por defecto es dist.
• Internamente, build ejecuta primero la misma validación de datos, si hay errores sale con código 1 y no genera resultados incompletos; los avisos se muestran pero no bloquean.
• Si el directorio de salida ya existe y no está vacío, se debe usar --force (que lo vaciará primero).
• --help para ver todos los parámetros.

Paso 5: Verificación

node scripts/verify.mjs <trip.json>          # Por defecto: errores fallan (código de salida 1), avisos solo informan
node scripts/verify.mjs <trip.json> --strict # Los avisos también se consideran fallos (recomendado antes de publicar)
node scripts/verify.mjs <trip.json> --quiet  # Solo muestra el resumen de errores

Cobertura de la verificación: campos obligatorios de meta y husos horarios/fechas válidos, referencias de destinations, formato de hora de days/events y validez de tz, protocolo de enlaces, lista blanca de HTML en handbook, existencia de archivo tickets.qr, y escaneo de privacidad (posibles números de teléfono/números largos generan advertencias). Las advertencias deben corregirse o poder explicarse claramente.

Paso 6: Vista previa y despliegue

• Vista previa local: abrir directamente dist/index.html con el navegador (archivo único se puede abrir con doble clic); para multi-página se recomienda usar un servidor local:

  npx serve dist
  # o python -m http.server --directory dist
  

• Despliegue: consultar references/deploy.md (GitHub Pages / Cloudflare Pages / cualquier hosting estático).
• Compartir páginas de entradas: en modo multi-página, ticket-<id>.html se puede enviar individualmente a la persona correspondiente; en modo archivo único se usa el anclaje #ticket-<id>, pero la misma página contiene el contenido de todos.
• Aviso de privacidad: un sitio público = visible para cualquiera. No incluir códigos QR reales, códigos de entrada, números de identificación, números de teléfono en la página pública; la puerta de contraseña es solo validación en frontend (ver deploy.md para más detalles).

Ejemplos de uso

Ejemplo 1: Conferencia académica en Tokio (mismo estilo que los datos de ejemplo)

Usuario: Voy a una conferencia académica en Tokio del 20 al 24 de noviembre, somos dos personas (A/B). Aquí están las capturas de los vuelos y el hotel, y el enlace de la agenda;
       Ayúdame a incluir el registro, la inauguración, el póster y la cena, y haz una página que pueda consultar fácilmente desde el móvil.

Agente:
1. Recopilar datos → preguntar 3 cosas: si la reserva del hotel incluye desayuno, el tipo de credencial de cada uno (A/B), hora de facturación del vuelo de regreso
2. Investigar → medios de transporte del aeropuerto de Haneda al centro y último autobús/tren, relación de ubicación entre el recinto y el hotel, tiempo estimado para pasar inmigración
3. Escribir trip.json → consultar examples/tokyo-conference/trip.json (el ejemplo combina el vuelo en un solo evento, endTime convertido al huso horario de salida)
4. Construir → node scripts/build.mjs trips/tokyo-2026/trip.json --multi --out dist
5. Verificar → node scripts/verify.mjs trips/tokyo-2026/trip.json --strict
6. Vista previa → abrir dist/index.html; proponer desplegar en GitHub Pages / enviar ticket-badge-a.html a A

Ejemplo 2: Viaje familiar al extranjero (múltiples destinos + doble huso horario + información del seguro)

Usuario: En verano voy con mis padres a España 10 días, entrando por Madrid y saliendo por Barcelona. Ayúdame a hacer un itinerario que incluya cómo consultar el metro y los teléfonos de emergencia.

Agente:
- Escribir dos destinos (Madrid / Barcelona, huso horario Europe/Madrid y comparar con el lugar de origen)
- En el manual, enfatizar: aeropuerto↔centro urbano, billetes de metro, pagos y propinas, teléfonos de emergencia y embajada, alimentación (restricciones de los padres)
- En los eventos, explicar claramente el «por qué» y los «elementos que se omiten» (ej. «Hoy no vamos al Retiro, guardamos energía para el Palacio Real»)
- Después de build, ejecutar verify, desplegar dist en GitHub Pages y enviar el enlace a la familia

Ejemplo 3: Actualización de datos existentes + compartir solo la página de entradas de una persona

Usuario: El itinerario ha cambiado: la cena se ha movido del día 23 al 24 a las 19:30. Además, envíame por separado la página de la credencial de mi mujer.

Agente:
1. Modificar el time/detail del evento correspondiente en trip.json (mantener la redacción de «confirmado» y las fuentes)
2. node scripts/build.mjs trip.json --multi --out dist --force
3. node scripts/verify.mjs trip.json
4. Compartir dist/ticket-badge-b.html por separado; recordar: un enlace público expondrá el código QR, se recomienda enviarlo solo a la persona interesada o añadir control de acceso

Líneas rojas de calidad

1. No inventar: precios, horarios, horarios de apertura, estado de reservas, teléfonos deben tener fuente; si no, escribir «por verificar» + «consultar la fuente oficial».
2. Confirmado vs por verificar: confirmación del usuario/página oficial = confirmado; plataformas de terceros/capturas antiguas/guías = por verificar; redacción fija en content-guide.md §6, no usar «se dice» o «debería».
3. Doble huso horario: time es la hora local del evento; al combinar vuelos, endTime se convierte según el tz del evento (huso horario de salida), detail escribe la hora local de aterrizaje; los cruces de día se separan al día siguiente; los husos horarios solo usan nombres IANA.
4. Privacidad y códigos de entrada: no incluir códigos QR reales, códigos de entrada, PNR, números de identificación, números de teléfono, direcciones en la página que se vaya a hacer pública; usar placeholders en copy; los datos de ejemplo deben ser ficticios y anonimizados; el repositorio solo debe contener códigos QR placeholder.
5. No prometer capacidades: no prometer inventario en tiempo real/reservas/facturación online; acciones irreversibles como pedidos, pagos, cambios o cancelaciones deben dejarse al usuario, no ejecutarlas por él.
6. Ejecutar verificación antes de entregar: verify.mjs --strict sin errores antes de entregar; antes de desplegar, confirmar de nuevo que no hay información sensible.
7. Explicar los límites: la puerta de contraseña es una protección de nivel «compartir con conocidos», no es cifrado; para seguridad real, usar hosting privado/control de acceso.

Cómo elegir entre archivo único y multi-página

Necesidad	Elegir archivo único (por defecto)	Elegir multi-página (--multi)
Enviar a familia/colegas, WeChat/correo, abrir sin conexión	✅ Un solo HTML es lo más sencillo	No recomendado (requiere todo el directorio)
Desplegar como sitio, uso a largo plazo, actualizaciones frecuentes	Se puede (cada vez se sube un archivo)	✅ Amigable con caché, estructura clara
Compartir páginas de entradas individualmente por persona	❌ Usar anclajes expone las entradas de otros en la misma página	✅ ticket-<id>.html página independiente
Querer un solo archivo (incluyendo códigos QR)	Reemplazar tickets[].qr con URI data: o URL externa	—
Necesitar puerta de contraseña	✅ Compatible (aparece tanto en la página principal como en las vistas de entradas dentro de la página)	✅ Tanto la página principal como ticket-<id>.html muestran el cuadro de contraseña (misma contraseña, se desbloquea una vez en el mismo navegador)

Nota: En modo de archivo único, las imágenes locales apuntadas por qr se incrustan automáticamente como URI data:, el resultado es realmente un solo archivo HTML; los QR que ya sean data:/http(s) se mantienen tal cual.

Mapa de archivos

skills/trip-cheat-sheet/
├── SKILL.md                     # Este archivo: cuándo usarlo, cómo usarlo, líneas rojas
├── references/
│   ├── trip-schema.md           # Contrato de datos único (campos/huso horario/comandos de construcción)
│   ├── content-guide.md         # Normas de redacción de contenido (seis elementos/doble huso horario/secciones del manual/reglas de marcado)
│   └── deploy.md                # Despliegue y uso compartido (Pages/Cloudflare/archivo único o múltiple/puerta de contraseña)
├── scripts/
│   ├── build.mjs                # trip.json → página web
│   └── verify.mjs               # Validador de trip.json (reutilizado internamente por build)
├── templates/                   # style.css / app.js / index.html / ticket.html
└── examples/tokyo-conference/   # Ejemplo ejecutable (incluye códigos QR placeholder)
    ├── trip.json
    └── assets/qr-a.svg, qr-b.svg

Preguntas frecuentes

Síntoma	Solución
❌ El directorio de salida no está vacío	Añadir --force, o cambiar el directorio --out
Página en blanco/falta de estilo	En modo multi-página, subir todo dist/ (incluyendo assets/) junto; asegurar que index.html y assets/ están al mismo nivel
La hora mostrada es incorrecta	Revisar la ortografía de tz (nombre IANA); en vuelos combinados, verificar si endTime se ha convertido según el huso horario de salida
verify muestra advertencias	Corregirlas, o confirmar que son aceptables antes de entregar; --strict fallará
Olvidar la contraseña de la puerta	Reconstruir: node scripts/build.mjs trip.json --gate-password "nueva-contraseña"
Error 404 después del despliegue	Revisar la configuración de la rama/directorio de Pages, si las Actions se han completado, mayúsculas/minúsculas en nombres de archivo
Error de versión de Node	Usar Node.js ≥ 18 (necesita datos completos de zona horaria Intl y ESM)

Referencia rápida en inglés

• Qué hace: genera una página web de viajes optimizada para móviles a partir de un trip.json — línea de tiempo del itinerario, listas de verificación, manual del destino, visualización de doble huso horario, enlaces profundos a mapas, páginas QR de entradas, puerta de contraseña opcional, PWA.
• Construcción: node scripts/build.mjs <trip.json> --out dist (archivo único, por defecto) o --multi (sitio estático con ticket-<id>.html). Banderas: --theme paper|slate|night, --gate-password, --no-pwa, --force, --quiet.
• Verificación: node scripts/verify.mjs <trip.json> [--strict] [--quiet].
• Contrato: references/trip-schema.md; reglas de redacción: references/content-guide.md; despliegue: references/deploy.md.
• Nunca: inventar precios/horarios, confundir husos horarios, o incluir códigos de entrada reales, imágenes QR, IDs o números de teléfono. Marcar explícitamente el contenido como verificado vs no verificado.