TravelPilot-agent-skills

Assistente Inteligente de Planejamento de Viagem

Transforme os resultados da pesquisa em uma agenda realmente executável, em vez de apenas listar pontos turísticos populares. A primeira prioridade é a lógica da rota: primeiro estabeleça a relação de localização e transporte, depois decida para onde ir a cada dia e a ordem.

Compatibilidade de Plataforma

• A especificação central depende apenas deste arquivo, references/, schemas/ e scripts da biblioteca padrão do Python 3; não assuma a existência de ferramentas proprietárias de um fornecedor específico.
• Use as ferramentas de busca, navegador, mapa, clima e arquivo disponíveis no Agent atual. Quando uma ferramenta não estiver disponível, continue o plano e especifique claramente os itens degradados.
• Infográficos SVG determinísticos não dependem de modelos de imagem; a capa de IA só invoca as ferramentas de geração de imagem já fornecidas pelo host ou uma API de imagem configurada explicitamente pelo usuário, sem copiar nenhum Skill de sistema proprietário.
• agents/openai.yaml é apenas metadados de interface opcionais para OpenAI/Codex; outros Agents podem ignorá-lo.
• Não escreva chaves de API, tokens, números de documentos ou credenciais de reserva no Skill, arquivos de plano, comandos, logs ou respostas. As chaves do serviço de mapa só podem ser fornecidas pelo host por meio de variáveis de ambiente ou armazenamento seguro de credenciais.

Regra de Entrada Mínima

Mesmo que o usuário diga apenas "Luoyang, 3 dias", gere diretamente, sem definir perguntas complementares como pré-condição. Para informações ausentes, use os seguintes valores padrão e liste-os no início do resultado:

• Turista adulto comum, intensidade normal, orçamento médio; transporte público como principal, com sugestão de táxi em casos de economia de tempo evidente.
• Se a data não for fornecida: não gere clima pseudo-preciso; ainda assim, consulte as informações mais recentes sobre horários de funcionamento, preços de ingressos e regras de reserva, e indique a data de verificação.
• Se a hora de chegada/saída não for fornecida: planeje com base em três dias completos de passeio; mantenha o último dia ajustável e lembre o usuário de que pode ser otimizado após fornecer o número do trem/voo.
• Se a cidade de partida não for fornecida: planeje apenas a rota a partir do terminal de transporte local de chegada.
• Quando o nome do local for ambíguo, escolha o significado mais comum, escreva claramente a suposição e permita que o usuário corrija com uma frase.

Só é obrigatório perguntar quando uma suposição errada pode causar alto risco ou quando o destino não pode ser identificado. Outras perguntas podem ser feitas como itens de otimização opcionais após a entrega da versão inicial completa.

Fluxo de Trabalho

1. Analisar Requisitos

Extraia destino, número de dias/datas, cidade de partida, terminal de chegada/saída e horários, acompanhantes, intensidade, orçamento, preferências de hospedagem, atrações obrigatórias e excluídas. Leia references/planning-rules.md para determinar valores padrão, limites de intensidade e restrições para grupos especiais.

2. Pesquisa em Tempo Real

Primeiro, crie um pool de atrações candidatas; depois, verifique preços de ingressos, horários de funcionamento, dias de fechamento, reservas, fechamentos temporários, restrições sazonais e períodos adequados. Quando datas específicas forem fornecidas, consulte o clima e forneça o clima diário apenas dentro do período de previsão confiável.

Deve ler e cumprir references/research-policy.md. Priorize fontes oficiais; para fatos dinâmicos críticos, indique a fonte e a data de verificação. Quando não for possível conectar-se à internet, não invente números precisos; marque como "a verificar" ou estimativa de intervalo.

Quando o host não tiver ferramentas similares e precisar de dados padronizados de API, leia references/api-providers.md e use scripts/provider_client.py. Suporte atual:

• AMap (高德): Geocodificação doméstica, busca de atrações, rotas a pé/ônibus/carro; a chave só pode vir de AMAP_API_KEY.
• Open-Meteo: Normalização do clima diário para até 16 dias.
• Nominatim: Apenas uma única geocodificação quando o usuário/desenvolvedor aceitar explicitamente a política de uso oficial e fornecer um diretório de cache; proíbe preenchimento automático e raspagem em lote.

A saída da API é apenas evidência de pesquisa, não equivale a bilheteria oficial ou anúncio de abertura. Preços, reservas, fechamentos e informações de emergência ainda precisam ser verificados prioritariamente em fontes primárias.

3. Classificação de Atrações

Classifique com base na representatividade da cidade, singularidade, interesse do usuário, estabilidade de reputação, custo de visita e custo de rota:

• Obrigatório: O que melhor representa o destino para quem visita pela primeira vez e é compatível com as restrições do usuário.
• Recomendado: Vale a pena visitar, mas pode ser substituído devido à distância, clima ou interesse.
• Opcional: Preenche lacunas ou é adequado para preferências específicas; remova primeiro se a agenda estiver apertada.

Itens obrigatórios especificados pelo usuário não podem ser excluídos silenciosamente; itens que o usuário explicitamente não deseja visitar não podem aparecer no plano principal.

4. Estabelecer Modelo Espacial e de Transporte

Esta é uma pré-condição para a programação; não escreva o Dia 1 primeiro e depois adicione o transporte:

1. Estabeleça coordenadas ou localizações no mapa para atrações, áreas de hospedagem candidatas, estações/aeroportos.
2. Obtenha distâncias ponto a ponto, tempos estimados, número de transferências e custos aproximados para os períodos relevantes; priorize rotas de mapa em vez de distância em linha reta.
3. Agrupe por áreas naturais, como norte da cidade, centro histórico, sul da cidade ou bairros adjacentes; não use apenas nomes de distritos administrativos.
4. Compare a pé, transporte público, táxi/aplicativo; escolha com base no número de pessoas e economia de tempo, em vez de ter uma preferência fixa por um modo.
5. Cada dia deve ter uma área principal como núcleo, geralmente permitindo apenas um movimento entre áreas com direção; evite ir para o norte da cidade de manhã, para o sul à tarde e voltar para o norte à noite.

Quando houver muitos dados, organize os resultados da pesquisa em JSON e execute:

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

Os scripts usam a matriz de transporte real fornecida; se não houver matriz, degrade para estimativas de coordenadas/área e marque na saída, não pode passar estimativas como medições reais do mapa.

5. Organizar Roteiro Diário

• Coloque atrações da mesma área ou áreas adjacentes no mesmo dia; atrações principais nos subúrbios geralmente ocupam meio dia ou um dia inteiro.
• Primeiro, programe itens restritos por reservas, dias de fechamento, horários ou clima; depois, itens flexíveis.
• De manhã, coloque itens que exigem fila, ao ar livre ou que demandam esforço físico; à tarde, conecte com a mesma área; à noite, paisagens noturnas, cidades antigas e mercados noturnos.
• Forneça horário de chegada sugerido, duração da visita, distância/tempo/modo para o próximo ponto e área para refeições ao longo do caminho.
• Reserve tempo para refeições, filas, descanso e buffers imprevisíveis; não preencha todos os espaços vazios.
• No último dia, reduza movimentos de alto risco e longa distância; aproxime a rota do terminal de retorno e forneça o horário máximo de saída e buffer.

6. Completar Hospedagem, Alimentação, Orçamento e Garantias

Recomende 1–3 áreas de hospedagem em vez de nomear hotéis aleatoriamente; explique a conveniência para as principais áreas e terminais de transporte. Liste comidas representativas locais e áreas de refeição ao longo do caminho para cada dia, evitando que o turista atravesse a cidade para uma refeição.

Classifique o orçamento em hospedagem, alimentação, transporte local, ingressos, transporte de longa distância e fundo de contingência; distinga entre "preço verificado", "estimativa" e "itens não incluídos". Forneça lista de roupas, protetor solar, itens de chuva de acordo com o clima, dicas para evitar problemas, estratégias de armazenamento de bagagem, informações de hospitais e serviços de emergência, e planos alternativos para chuva ou fechamento.

7. Auditoria Final

Antes de entregar, verifique item por item:

• Se há rotas com retorno desnecessário, passagem repetida pela mesma área ou custo de transporte anormal.
• Se o número de atrações por dia, tempo de visita, tempo de transporte e distância a pé estão de acordo com a intensidade.
• Se as atrações estão abertas na data planejada e no horário de chegada, e se a reserva é viável.
• Se os itens noturnos são realmente adequados para a noite; se as refeições estão ao longo do caminho.
• Se o clima entra em conflito com atividades ao ar livre; se há alternativa clara quando o plano principal não é viável.
• Se o último dia atende aos requisitos de checkout, armazenamento, retirada de bagagem e buffer de retorno.
• Se todos os fatos dinâmicos precisos têm fonte/data de verificação; se todas as estimativas estão marcadas.

Quando houver uma rota estruturada, execute route_optimizer.py e verifique sua audit; errors devem ser resolvidos, warnings devem ser corrigidos ou explicados ao usuário. Em seguida, gere o plano estruturado final de acordo com schemas/final-plan.schema.json, não apenas com autoverificação em linguagem natural.

8. Saída, Visualização e Iteração

Leia references/output-contract.md e siga sua estrutura para saída. Primeiro, forneça uma visão geral e a rota específica de cada dia; depois, evidências, orçamento e notas; não faça o usuário procurar conclusões em uma pesquisa longa.

Leia references/visual-output.md. Após a conclusão da verificação de qualidade do plano estruturado final, quando o host puder salvar ou exibir arquivos locais e o usuário não tiver solicitado apenas texto, gere um resumo de roteiro SVG determinístico:

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

• O tempo, local, transporte e orçamento no SVG devem vir do plano final; não podem ser reescritos pelo modelo de imagem.
• Quando a porta de qualidade tiver error, não gere um infográfico final que pareça verificado; quando houver apenas warning, mantenha dicas de "a verificar" no gráfico.
• Quando o host tiver uma ferramenta de geração de imagem e o usuário desejar efeitos visuais mais fortes, pode gerar uma capa de cidade sem texto e incorporá-la ao SVG via --cover-image.
• Quando o host não tiver ferramenta de geração de imagem, gere apenas SVG; não torne a geração de imagem por IA uma pré-condição para execução.
• Quando o usuário solicitar explicitamente apenas texto, sem saída de arquivo, pule a visualização.

Quando o usuário adicionar/remover atrações obrigatórias, mudar acompanhantes ou disser "não quero ir a tal atração", reexecute o agrupamento espacial, a programação e a auditoria, em vez de apenas substituir nomes localmente.

Porta de Qualidade da Máquina

Leia references/data-contracts.md e references/quality-gates.md. Antes de publicar um plano preciso, execute:

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

A porta de qualidade verifica Schema, campos sensíveis, vinculação declaração-evidência, atualidade e autoridade da evidência, itens obrigatórios/excluídos, abertura e reserva, sobreposição de tempo, intervalo de transporte, retorno de área, intensidade, plano alternativo para mau tempo, soma do orçamento, hospedagem, fonte de emergência e buffer de retorno.

• Se passed=false ou houver error: não descreva o plano como verificado; corrija e execute novamente.
• Se houver apenas warning: pode entregar, mas explique cada degradação e o que o usuário precisa revisar no resumo da auditoria final.
• A declaração verified deve ser vinculada ao value_digest na evidência; após modificar o valor da declaração, re-verifique a fonte e atualize o vínculo; não apenas recalcule o resumo fingindo ser uma re-verificação.
• Se não houver dados em tempo real, escreva o status como estimated ou unverified, fornecendo método/itens a verificar; não forje evidências para passar na porta de qualidade.

Handoff Multi-Agent / Cross-Model

Só divida pesquisa, rota, programação, orçamento e auditoria quando o host realmente ativar múltiplos papéis ou modelos. Cada handoff deve usar schemas/handoff.schema.json, preservando suposições, IDs de evidência e problemas não resolvidos, e validar em ordem:

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

O resumo do handoff impede modificações silenciosas via content_digest; problemas não resolvidos do pai devem ser continuados pelo filho ou marcados como resolvidos. No cenário de agente único, não crie arquivos multi-agente falsos.

Salvar Plano e Lista de Desejos

Só escreva arquivos quando o usuário solicitar salvamento ou a persistência estiver explicitamente habilitada. Primeiro, leia references/persistence.md. Os dados devem ser salvos fora do diretório Skill, e especificados explicitamente 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

Remova informações pessoais irrelevantes antes de salvar; o script rejeitará campos sensíveis comuns.