evgyur/hermes-bird-xurl-skill

Bird

Bird é o roteador único para X/Twitter. Use o SocialData como o plano de leitura padrão e barato. Use o CLI oficial xurl apenas quando a tarefa exigir um contexto de conta autenticada, um objeto nativo do X, ou uma mutação de conta explicitamente aprovada. Não faça ambos os provedores responderem à mesma requisição de leitura rotineira.

Gatilhos e compatibilidade

Use para URLs do X/Twitter, extração de tweets/threads/artigos, busca, perfis, respostas/citações/contexto, recuperação de mídia e ações na conta do X.

Preserve estes pontos de entrada:

• /bird <requisicao> — roteador canônico.
• Legado bird.py <URL-ou-ID> — ainda lê através do SocialData.
• /xurl ... — ponto de entrada de compatibilidade para usuários que solicitam explicitamente o xurl; deve seguir as portas de roteamento e escrita do Bird.

Roteamento determinístico

Intenção	Primário	Fallback	Limite
Ler tweet por URL/ID	SocialData	web/browser apenas para evidência pública visível	Nunca escalar para xurl meramente por ele existir
Ler thread/conversa/respostas	SocialData	leitura xurl apenas quando o contexto nativo do X for exclusivamente necessário e suportado	Determinar a thread a partir dos dados obtidos, não da forma da URL
Pesquisar posts	Busca limitada do SocialData	Rota de pesquisa existente SocialData/web	O acesso atual de pesquisa recente do xurl não é presumido
Ler perfil público	SocialData	pesquisa de usuário xurl se uma visualização específica da conta/atual do X for necessária	Sem coleta em massa de grafos
Artigo do X	Payload do tweet do SocialData primeiro; analisar artigo aninhado	Endpoint de tweet bruto do xurl com campo article	Seguir página de primeira parte vinculada quando o texto do artigo estiver ausente
Baixar mídia anexada	Metadados do SocialData + download HTTPS limitado	browser apenas para mídia pública visível	Sem cookies em URLs/logs; validar host/tamanho/tipo
Quem sou eu / identidade autenticada	xurl	nenhum	Contexto de conta somente leitura
Objeto nativo do X exato necessário para engajamento posterior	xurl	SocialData para descoberta/contexto	Usar xurl apenas para o objeto/endpoint exato
Postar, responder, citar, deletar, curtir, repostar, favoritar, seguir, bloquear, silenciar, DM, enviar	xurl	nenhum	Aprovação explícita do alvo, conteúdo e efeito exatos necessária

Carregue roteamento do provedor para receitas de endpoint, erros e regras de fallback. Carregue operações xurl apenas para uma tarefa específica do xurl.

Contrato de provedor e custo

• SocialData é o padrão para toda leitura comum. Use a SOCIALDATA_API_KEY direta configurada primeiro no runtime atual. Use o proxy SocialData aprovado das Human20 Keys quando uma chave direta estiver ausente e a chave de cliente H20 tiver a capacidade socialdata. Uma chave de modelo H20 genérica pode existir, mas retornar provider not allowed: socialdata; isso não justifica a troca para xurl.
• A classe de preço padrão ativa das Human20 Keys para social-request foi verificada em 0 credits/request; trate isso como estado de runtime mutável e verifique novamente antes de alegar custo.
• Uma requisição de usuário deve normalmente consumir uma consulta/pesquisa mais apenas as leituras dependentes limitadas necessárias para uma thread ou contexto solicitado. Não faça expansão, raspagem de seguidores/seguindo, exportação, transmissão, polling ou busca em massa.
• Nunca recorra silenciosamente do SocialData para chamadas pagas da API do X. O xurl é selecionado pela necessidade de capacidade, não por falha do provedor.

Segredos e segurança de execução

• Nunca leia, imprima, analise, resuma ou exponha armazenamentos de segredos, ~/.xurl, cookies, cabeçalhos de autorização, chaves de API, tokens de portador, assinaturas de requisição ou valores de ambiente.
• Verifique as credenciais apenas através de comandos seguros de status/probe. Não use o xurl com --verbose/-v ou flags de credenciais inline.
• Chamadas do SocialData são somente leitura e limitadas. Trate 401/403 como credencial/política, 402 como créditos/faturamento, 404 como ausente/privado/deletado, 429 como limite de taxa, e 5xx como falha do provedor. Não rotule erroneamente uma classe como outra.
• Browser/relay é último recurso e nunca um mecanismo de extração de cookies.
• Escritas são efeitos protegidos. Antes de qualquer mutação xurl, releia o alvo e payload exatos, exija aprovação explícita do usuário para aquele efeito exato, execute uma vez, e verifique a partir da resposta bruta do xurl/X. Aprovação para pesquisar não é aprovação para engajar ou publicar.
• DMs, deleção, bloqueios, mudanças de conta, upload de mídia e postagem pública nunca acontecem implicitamente.

Fluxo de trabalho

1. Classifique a requisição: read, search, profile, thread, article, media, account-read ou write.
2. Normalize a URL/ID do X sem alterar o identificador. Busque antes de decidir entre tweet e thread.
3. Roteie a partir da tabela. Para leituras rotineiras, chame o SocialData exatamente uma vez primeiro.
4. Analise defensivamente. Payloads de artigo podem estar sob article.title, article.preview_text e article.content_state.blocks[]; mídia pode estar aninhada em objetos citados ou retweetados.
5. Se o usuário perguntar se o item é relevante, abra repositórios/documentos/artigos vinculados de primeira parte e inspecione a mídia anexada. Mantenha o post do X como uma alegação/fonte, não prova automática.
6. Se o provedor selecionado falhar, reporte a falha exata. Use apenas o fallback declarado quando ele ainda puder responder à mesma requisição sem expandir custo, privacidade ou efeito.
7. Retorne uma saída fiel à fonte e um recibo compacto do provedor.

Contrato de saída

Retorne:

Resultado: <conteúdo completo solicitado ou resposta concisa e fiel>
Tipo: tweet | thread | artigo | perfil | busca | acao-conta
Autor/fonte: <identidade pública segura + URL canônica>
Provedor: SocialData | xurl | fallback web/browser
Evidência: <IDs, timestamp, métricas/contexto quando disponível>
Recibo de ação: <apenas para mutações xurl aprovadas; status exato/ID do objeto>
Limitação: <ausente/privado/deletado/taxa/plano/lacuna do provedor, ou nenhuma>

Não exponha chaves internas, modos de autenticação, locais de segredos ou detalhes de runtime privados em recibos voltados ao usuário.

Lista de verificação rápida

• /bird <URL do tweet> seleciona SocialData, não xurl.
• /bird search from:handle seleciona busca limitada do SocialData.
• /bird whoami seleciona identidade xurl somente leitura.
• /bird reply <URL> <texto> para para aprovação exata antes do xurl.
• 402 do SocialData não é reportado como credenciais ausentes; falha de pesquisa recente do xurl não desabilita leituras de identidade/perfil.
• Análise de thread e artigo usa a estrutura buscada, não suposições de URL.
• Remover o contrato de SocialData como padrão ou de aprovação de escrita faz a validação falhar.

Critérios de conclusão

• O conteúdo/ação do X solicitado está completo ou um bloqueador exato é reportado.
• Leituras rotineiras usaram SocialData primeiro e evitaram gastos duplicados de provedor.
• xurl foi usado apenas por uma razão específica de capacidade.
• Qualquer escrita teve aprovação exata e leitura de retorno da API bruta.
• Nenhum segredo/cookie/credencial privada entrou na saída, artefatos ou logs.