TripCheat · Cola de Viagem com IA (`trip-cheat-sheet`)

TripCheat · Especialista em Planejamento de Viagens com IA (trip-cheat-sheet)

Transforme os materiais de viagem dispersos do usuário (voos, hotéis, agenda de conferências, ingressos, capturas de tela de guias e conversas) em uma página web portátil: Linha do tempo do itinerário (aonde ir e a que horas hoje), listas de verificação (o que não esquecer) e manual (como se locomover, como pagar, a quem recorrer em caso de problemas). Pronto para uso no celular, com suporte a fusos duplos, tema escuro, ajuste de tamanho de fonte, links profundos para mapas, QR codes para ingressos e implantável em qualquer hospedagem estática.

A página é construída a partir de um único arquivo trip.json usando o gerador incluído neste skill: consulte o contrato de dados em references/trip-schema.md, as regras de redação em references/content-guide.md e a implantação em references/deploy.md.

Quando usar

Cenários de ativação

• "Me ajude a fazer um roteiro", "Organize as passagens, hotel e agenda da conferência em uma página", "Preparação para viagem de negócios/evento"
• "Guia de viagem", "Página portátil", "Manual de viagem", "Lista de viagem", "O que fazer a cada dia e a que horas"
• O usuário forneceu várias capturas de tela / PDFs / e-mails / links / conversas e precisa de estruturação + pesquisa complementar + uma página que possa ser consultada em qualquer lugar
• Já existe um trip.json: precisa regenerar a página, mudar o tema, adicionar um portão de senha, implantar ou compartilhar páginas de ingressos

Não aplicável

• Apenas precisa consultar a descrição de um ponto turístico, clima ou reservar ingresso: faça uma pesquisa/resposta direta, não precisa criar uma página
• Precisa de estoque em tempo real, finalização de compra, pagamento ou check-in: este skill não se conecta a APIs de reserva, apenas organiza informações e links
• Roteiro puro de navegação: use ferramentas de mapa, não precisa de página de itinerário

Saídas

Modo	Comando	Saída
Arquivo único (padrão)	node scripts/build.mjs trip.json --out dist	dist/index.html (CSS/JS/dados/manifest PWA totalmente embutidos) + imagens de ingressos copiadas conforme necessário
Site 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 ingressos copiados

Recursos da página: três visões (linha do tempo do itinerário / listas de verificação / manual); destaque do "evento atual/próximo"; relógios de fuso duplo e conversão de horário; temas (paper/slate/night) e alternância de tamanho de fonte; links profundos para Google/Amap/Apple Maps (links de rota do Google com parâmetro de modo de transporte); marcação de conclusão em listas de verificação (localStorage do navegador); página de QR code para ingressos; portão de senha opcional (verificação SHA-256 no front-end); pode ser adicionado à tela inicial (PWA, desativado com --no-pwa).

Fluxo de trabalho (6 etapas)

Etapa 1: Coleta de materiais (questionário + arquivos/capturas de tela/links)

Primeiro, faça uma rodada de perguntas, no máximo 6, evitando perguntas em sequência; para o que o usuário não responder, use suposições padrão e indique explicitamente "Suposição".

• Quem vai, quantas pessoas, qual a relação (os acompanhantes precisam de cuidados especiais para idosos/crianças/acessibilidade?)
• Origem, datas (incluindo dias consecutivos/voos noturnos), destino (múltiplas cidades/escala?)
• O que já está reservado, o que ainda precisa ser reservado (voos, hotel, inscrição em conferência, ingressos, restaurante)
• Horários chave da conferência/evento (inscrição, abertura, sua própria apresentação/pôster, jantar)
• Preferências e limites (orçamento, restrições alimentares/alergias, ritmo de viagem, o que gostaria de abrir mão)
• Requisitos de privacidade (compartilhar publicamente? precisa de portão de senha? quais informações não podem ir para a internet?)

Colete materiais: capturas de tela, PDFs, e-mails, conversas, links. Primeiro organize em uma lista de fatos antes de escrever o JSON, não adivinhe enquanto coleta.

Etapa 2: Pesquisa aprofundada (com conexão, distinguindo "confirmado" de "a verificar")

Pesquise por prioridade e registre os links das fontes e a data da verificação:

Prioridade	Conteúdo da pesquisa
P0	Visto/validade do passaporte, voos/tr Emilia, hospedagem, inscrição em conferência/ingressos, seguro
P1	Transporte aeroporto ↔ centro (último ônibus, terminal), transporte urbano, reserva com hora marcada para ingressos, reserva de restaurante
P2	Pontos turísticos, compras, planos alternativos, clima

• Priorize fontes oficiais: companhias aéreas/aeroportos/ferrovias, hotéis, sites de conferências, museus/parques, consulados, operadoras de transporte.
• Cada informação chave deve ser classificada em quatro categorias: Confirmado / A verificar / Não definido / Exemplo (regras em references/content-guide.md §6).
• Não invente preços, horários, horários de funcionamento ou status de reserva; se não encontrar, escreva "A verificar" e dê uma ressalva "Consulte a fonte oficial".
• Verifique armadilhas comuns (transporte do aeroporto, reserva de ingresso, Wi-Fi, pagamento, números de emergência, fuso horário/horário de verão) item por item e inclua no manual ou na descrição do evento.

Etapa 3: Escrever trip.json

Siga estritamente references/trip-schema.md; consulte o exemplo examples/tokyo-conference/trip.json.

• meta: título, subtítulo, cidade de origem (home), datas de início e fim, tema, provedor de mapa, rodapé (incluir data de corte dos dados).
• destinations: cada destino com um id + fuso horário IANA (ex.: Asia/Tokyo).
• days[].events: cada evento deve ter no mínimo time / title / short / detail / kind; se tiver local, incluir location + map; se tiver link oficial, incluir links; se puder ser associado a uma lista de verificação, incluir checkId.
• checklists: agrupar por fase (antes da partida / após o desembarque / durante / antes do retorno), id único global.
• handbook: seções sobre transporte, rede, pagamento, segurança e emergências, participação em eventos, alimentação, arrumação (pode combinar/adicionar, mas não pule nenhum tópico).
• tickets: um por pessoa, qr apontando para uma imagem placeholder ou imagem fornecida pelo usuário (não envie códigos de ingresso reais).

Regras de fuso duplo (as que mais causam erro)

1. time / endTime são horários locais do evento; quando tz não é informado, herda o fuso do destino do dia.
2. Para voos que cruzam fusos, tz representa o fuso do local de partida, e endTime também é interpretado nesse tz. Ao consolidar em um único evento de voo, endTime deve ser o valor do horário de chegada convertido para o fuso do local de partida, e no detail escreva claramente "Horário local de chegada: HH:MM"; uma abordagem mais simples é dividir a partida e a chegada em dois eventos separados, cada um com seu próprio fuso local.
3. Chegadas no dia seguinte devem ser colocadas no próximo days[] e no detail escreva "+1 dia"/"próximo dia"; eventos que cruzam a meia-noite com endTime menor que time serão tratados como próximo dia, mas ainda assim é recomendado esclarecer no texto.
4. Para compromissos de dia inteiro sem horário específico, use skipTimezone: true; fusos devem ser sempre escritos com nomes IANA, não use UTC+9, JST.
5. A página converterá automaticamente os horários para o fuso da cidade de origem, não escreva a conversão manualmente no texto, a menos que seja algo como "abertura de check-in" ou "reunião remota" que precisa ser feito no horário da cidade de origem antes da partida.

Etapa 4: Construção

Execute no diretório raiz do skill (que contém scripts/, templates/); o script resolve caminhos relativos ao diretório de trabalho atual, ou pode ser executado de qualquer diretório usando caminhos completos.

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

Parâmetros comuns:

# Site multi-página (gera ticket-<id>.html para compartilhamento individual)
node scripts/build.mjs trip.json --multi --out dist

# Sobrescrever tema / adicionar portão de senha / desativar PWA / sobrescrever diretório de saída não vazio / modo silencioso
node scripts/build.mjs trip.json --theme night --gate-password "sua-senha" --out dist
node scripts/build.mjs trip.json --no-pwa --out dist
node scripts/build.mjs trip.json --force --quiet --out dist

• A saída padrão é dist/index.html; --out padrão é dist.
• O build executa a mesma validação de dados internamente primeiro; se houver erros, sairá com código 1 e não gerará uma saída incompleta; avisos serão exibidos, mas não bloquearão.
• Se o diretório de saída já existir e não estiver vazio, é obrigatório usar --force (que primeiro limpará o diretório).
• Use --help para ver todos os parâmetros.

Etapa 5: Verificação

node scripts/verify.mjs <trip.json>          # Padrão: erros falham (código de saída 1), avisos apenas informam
node scripts/verify.mjs <trip.json> --strict # Avisos também contam como falha (recomendado antes da entrega)
node scripts/verify.mjs <trip.json> --quiet  # Apenas resume os erros

A verificação cobre: campos obrigatórios de meta e validade de fuso/data, referências de destinations, formato de horário e validade de tz em days/events, protocolos de links, lista branca de HTML em handbook, existência do arquivo tickets.qr, e varredura de privacidade (números de telefone suspeitos/números longos geram aviso). Corrija os avisos ou seja capaz de explicá-los.

Etapa 6: Visualização e implantação

• Visualização local: abra dist/index.html diretamente no navegador (arquivo único pode ser aberto com duplo clique); para multi-página, é recomendado iniciar um servidor local:

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

• Implantação: consulte references/deploy.md (GitHub Pages / Cloudflare Pages / qualquer hospedagem estática).
• Compartilhar página de ingresso: no modo multi-página, ticket-<id>.html pode ser enviado individualmente para a pessoa correspondente; no modo arquivo único, use a âncora #ticket-<id>, mas a mesma página conterá o conteúdo de todos.
• Aviso de privacidade: site público = visível para todos. Não coloque códigos QR reais, códigos de ingresso, números de documento, números de telefone em páginas públicas; o portão de senha é apenas uma verificação no front-end (veja deploy.md para detalhes).

Exemplos de chamada

Exemplo 1: Conferência acadêmica em Tóquio (mesmo estilo dos dados de exemplo)

Usuário: Vou a Tóquio de 20 a 24 de novembro para uma conferência acadêmica, duas pessoas (A/B), aqui estão as capturas de tela do voo e do hotel, e o link da agenda;
       Ajude a incluir inscrição, abertura, pôster e jantar no roteiro, e faça uma página que eu possa consultar a qualquer momento no celular.

Agente:
1. Coletar materiais → perguntar 3 coisas: a reserva do hotel inclui café da manhã, os tipos de crachá de A e B, horário do check-in do voo de volta
2. Pesquisar → meios de transporte de Haneda para o centro e último ônibus, relação de localização entre o local do evento e o hotel, tempo de desembarque/imigração
3. Escrever trip.json → consultar examples/tokyo-conference/trip.json (exemplo consolida o voo em um único evento, endTime convertido para o fuso da origem)
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. Visualizar → abrir dist/index.html; propor implantação no GitHub Pages / enviar ticket-badge-a.html para A

Exemplo 2: Viagem familiar ao exterior (múltiplos destinos + fuso duplo + informações de seguro)

Usuário: Vou levar meus pais para a Espanha por 10 dias nas férias de verão, entrando em Madri e saindo de Barcelona. Ajude a fazer um roteiro, que possa consultar metrô e números de emergência.

Agente:
- destinations escrever dois (Madrid / Barcelona, fuso horário Europe/Madrid comparado com a origem)
- handbook focar em: aeroporto↔centro, bilhete de metrô, gorjetas e pagamento, números de emergência e consulado, alimentação (restrições dos pais)
- Nos eventos, escrever claramente o "porquê" e os "itens dispensados" (ex.: "Hoje não vamos ao Parque do Retiro, poupar energia para o Palácio Real")
- Após construir, executar verify, implantar dist no GitHub Pages e enviar o link para a família

Exemplo 3: Atualização de dados existentes + compartilhar apenas a página de ingresso de uma pessoa

Usuário: O roteiro mudou: o jantar passou do dia 23 para o dia 24 às 19:30. Além disso, me envie separadamente a página do crachá da minha esposa.

Agente:
1. Alterar time/detail do evento correspondente no trip.json (manter a redação "Confirmado" e a fonte)
2. node scripts/build.mjs trip.json --multi --out dist --force
3. node scripts/verify.mjs trip.json
4. Compartilhar dist/ticket-badge-b.html separadamente; lembrar: links públicos expõem o QR code, recomenda-se enviar apenas para a pessoa ou adicionar controle de acesso

Limites de qualidade

1. Não inventar: preços, horários, horários de funcionamento, status de reserva, telefones devem ter fonte; se não houver, escreva "A verificar" + "Consulte a fonte oficial".
2. Confirmado vs A verificar: confirmação do usuário/página oficial = confirmado; plataforma de terceiros/captura de tela antiga/guia = a verificar; redação fixa conforme content-guide.md §6, não use "dizem que" ou "deveria".
3. Fuso duplo: time escreva o horário local do evento; ao consolidar voo, endTime deve ser convertido para o fuso do evento (tz da origem), no detail escreva o horário local de chegada; dias seguintes separados no próximo dia; use apenas nomes IANA.
4. Privacidade e códigos de ingresso: não escreva códigos QR reais, códigos de ingresso, PNR, números de documento, números de telefone, endereços em páginas que serão públicas; copy use placeholder; dados de exemplo devem ser fictícios e anonimizados; o repositório deve conter apenas QR codes placeholder.
5. Não prometer capacidades: não prometa estoque em tempo real/reserva/check-in; ações irreversíveis como finalizar compra, pagamento, reembolso ou alteração devem ser deixadas para o usuário, não execute em nome do usuário.
6. Executar verificação antes da entrega: verify.mjs --strict com zero erros antes de entregar; antes de implantar, verifique novamente se não há informações sensíveis.
7. Explicar limites: o portão de senha é uma proteção de nível "compartilhamento entre conhecidos", não é criptografia; para segurança real, use hospedagem privada/controle de acesso.

Como escolher entre arquivo único e multi-página

Necessidade	Escolher arquivo único (padrão)	Escolher multi-página (--multi)
Enviar para família/colegas, WeChat/e-mail, abrir offline com duplo clique	✅ Um HTML é o mais prático	Não recomendado (precisa do diretório inteiro)
Implantar como site, uso de longo prazo, atualizações frequentes	Pode ser (cada vez reenviar um arquivo)	✅ Amigável para cache, estrutura clara
Compartilhar página de ingresso individualmente por pessoa	❌ Usar âncora expõe os ingressos de todos na mesma página	✅ ticket-<id>.html páginas independentes
Quer um único arquivo (incluindo QR codes)	Substitua tickets[].qr por URI data: ou URL externa	—
Precisa de portão de senha	✅ Suporta (tela principal e visualização de ingressos na página exibem)	✅ Tela principal e ticket-<id>.html exibem caixa de senha (mesma senha, mesmo navegador desbloqueia uma vez)

Nota: No modo arquivo único, as imagens locais apontadas por qr são automaticamente embutidas como URI data:, o resultado é realmente um único arquivo HTML; QR codes que já são data:/http(s) são mantidos como estão.

Mapa de arquivos

skills/trip-cheat-sheet/
├── SKILL.md                     # Este arquivo: quando usar, como usar, limites
├── references/
│   ├── trip-schema.md           # Único contrato de dados (campos/fuso/comandos de build)
│   ├── content-guide.md         # Regras de redação de conteúdo (seis elementos/fuso duplo/seções do manual/regras de marcação)
│   └── deploy.md                # Implantação e compartilhamento (Pages/Cloudflare/único+multi/portão de senha)
├── scripts/
│   ├── build.mjs                # trip.json → página web
│   └── verify.mjs               # Validador de trip.json (reutilizado internamente pelo build)
├── templates/                   # style.css / app.js / index.html / ticket.html
└── examples/tokyo-conference/   # Exemplo executável (contém QR codes placeholder)
    ├── trip.json
    └── assets/qr-a.svg, qr-b.svg

Perguntas frequentes

Fenômeno	Tratamento
❌ Diretório de saída não vazio	Adicione --force, ou mude o diretório --out
Página em branco/estilos ausentes	No modo multi-página, é necessário enviar todo o diretório dist/ (incluindo assets/); confirme se index.html e assets/ estão no mesmo nível
Horário exibido incorretamente	Verifique a ortografia de tz (nome IANA); ao consolidar voo, verifique se endTime foi convertido para o fuso da origem
verify exibe avisos	Corrija-os, ou confirme que são aceitáveis e entregue; --strict falhará
Esqueceu a senha do portão de senha	Reconstrua: node scripts/build.mjs trip.json --gate-password "nova senha"
404 após implantação	Verifique as configurações de branch/diretório do Pages, se a Action foi concluída, maiúsculas/minúsculas do nome do arquivo
Erro de versão do Node	Use Node.js ≥ 18 (precisa de dados completos de fuso Intl e ESM)

English quick reference

• What: generate a mobile-first travel cheat-sheet web page from one trip.json — itinerary timeline, checklists, destination handbook, dual-timezone display, map deep links, QR ticket pages, optional password gate, PWA.
• Build: node scripts/build.mjs <trip.json> --out dist (single file, default) or --multi (static site with ticket-<id>.html). Flags: --theme paper|slate|night, --gate-password, --no-pwa, --force, --quiet.
• Verify: node scripts/verify.mjs <trip.json> [--strict] [--quiet].
• Contract: references/trip-schema.md; writing rules: references/content-guide.md; deployment: references/deploy.md.
• Never: fabricate prices/schedules, mix up timezones, or commit real ticket codes, QR images, IDs or phone numbers. Mark verified vs unverified content explicitly.