alanchoi00/citando-fontes-com-excertos

Citando Fontes com Excertos

Visão Geral

Cada afirmação citada carrega sua prova em linha: a passagem literal, um link que salta e destaca essa passagem e, opcionalmente, uma captura de tela. Os leitores verificam sem clicar; clicar cai exatamente no texto. Funciona para arquivos markdown e para respostas em chat.

Cada citação deve vir da saída de snap.mjs, nunca da memória, de um resumo de resultado de busca ou de uma ferramenta de busca que resume. Resumos de busca e ferramentas do tipo WebFetch parafraseiam páginas; apenas o script verifica o texto renderizado literalmente.

Verifique afirmações, não apenas citações. Uma citação correspondente prova que a página diz aquilo. Não prova nada sobre o que a página não diz. Dois tipos de afirmação sempre passam pelo script como suas próprias entradas em lote, inclusive quando você está apenas "verificando um rascunho":

• Ausência: antes de escrever que uma página não diz, menciona ou exige algo, adicione a frase que estaria lá se dissesse (por exemplo, Respostas com o código de status 429 NÃO DEVEM ser armazenadas por um cache.). Apenas match: none suporta a ausência, e então escreva "não encontrado em <página>", nunca "a especificação não diz nada sobre X".
• Discordância: quando a memória, um resumo de busca, um rascunho que você já escreveu ou exemplos desta habilidade discordam sobre o que uma página diz, adicione a frase disputada. O resultado do script a resolve, independentemente de qual lado favorece. (Cada citação nos exemplos desta habilidade foi verificada com o script.)

Configuração (uma vez por máquina)

npm install --prefix <diretório-habilidade>/scripts && npx --prefix <diretório-habilidade>/scripts playwright install chromium

<diretório-habilidade> é o diretório que contém este SKILL.md.

O script

Crie o documento ou resposta primeiro, colete cada citação, depois verifique-as todas em uma única chamada em lote:

node <diretório-habilidade>/scripts/snap.mjs --batch - <<'EOF'
[
  {"url": "https://www.rfc-editor.org/rfc/rfc6585.html", "quote": "Respostas com o código de status 429 NÃO DEVEM ser armazenadas por um cache."},
  {"url": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After", "quote": "Um inteiro decimal não negativo", "out": "/caminho/absoluto/docs/refs/delay.png"}
]
EOF

Um navegador para o lote; citações na mesma URL compartilham um carregamento de página. Use caminhos absolutos para out. A entrada também pode ser {"defaults": {...}, "cites": [...]} para aplicar opções de captura de tela a cada entrada. A saída do lote é um array JSON na ordem de entrada (modo único, snap.mjs "<url>" --quote "...", imprime um objeto). Cada entrada:

Campo	Uso
ok / match	exact/loose = literal. fuzzy = sua citação estava errada; use quote_on_page em vez disso e verifique novamente se a afirmação ainda é válida. none = não está na página.
quote_on_page	O texto a colocar no blockquote. Nunca seu --quote original.
fragment_url	O link a usar (tem #:~:text=, destaca no Chrome/Safari/Firefox).
excerpt	Parágrafo circundante, para verificar contexto (negações, ressalvas, "exceto quando…"). Quer citar mais dele? Reexecute com essa passagem mais longa como --quote para que o link e a captura de tela correspondam.
title, section, retrieved	A linha de atribuição: [<title> — <section>](fragment_url) · recuperado em <date>, ou [<title>](fragment_url) quando section estiver ausente. Use estes campos; não adicione números de seção de memória.
occurrences / occurrence	Presente quando a citação aparece mais de uma vez. Verifique se excerpt é o que você queria; se não, reexecute com prefix/suffix (as palavras imediatamente antes/depois dela na página).
hidden	A citação está em conteúdo que a página oculta (por exemplo, uma aba inativa): verificada, mas sem captura de tela.
note	Qualquer outra coisa que valha a pena saber (correspondência aproximada, seção expandida colapsada, fallback de frame). Leia.
internal	A página está em uma rede interna. Seu conteúdo pode ser confidencial; não cite mais do que a afirmação precisa.

Saída 0 = todas encontradas, 1 = algumas não encontradas, 2 = algumas com erro (PDF, 4xx, muro de login, verificação de bot, timeout). Espere um lote de acompanhamento: coloque cada entrada que precisa de outra passagem (falhou, aproximada, ocorrência errada ou uma passagem mais longa desejada) nele junto.

Opções de captura de tela

Campos opcionais em qualquer entrada (ou em defaults). Mapeie a redação do usuário; sem redação, deixe-os de fora.

Usuário diz	Campo
"capturas apertadas", "apenas a citação"	"frame": "quote" (padrão paragraph)
"mostrar a seção inteira"	"frame": "section" (o limite de altura sobe para 1200 automaticamente)
"tela cheia", "mostrar a página ao redor"	"frame": "viewport"
"algumas linhas ao redor"	"context": 2 (linhas de texto inteiras acima e abaixo)
"tamanho mobile"	"width": 390 (padrão 1100)
"mantenha-as curtas"	"max_height": 150 (padrão 500; o corte centraliza na citação)
"destacar em amarelo", "sem destaque"	"highlight": "#fff3a0" / "none"
"modo escuro"	"theme": "dark" (apenas sites com tema escuro; note diz o contrário)
"imagens menores"	"scale": 1 (padrão 2)

Estes apenas moldam as capturas de tela. Contexto desejado no próprio texto (ou sem capturas de tela) → cite uma passagem mais longa retirada de excerpt, reexecute no lote de acompanhamento. Citações em células de tabela emolduram automaticamente a linha mais a linha do cabeçalho. Cada opção, com sua captura de tela, está em examples/README.md do repositório.

Formato de saída

Escolha o formato de acordo com onde o texto vai.

Arquivo Markdown: afirmação na prosa, nota de rodapé com a prova:

Os clientes não devem armazenar em cache respostas de limitação de taxa.[^429-cache]

[^429-cache]: > Respostas com o código de status 429 NÃO DEVEM ser armazenadas por um cache.
    >
    > — [Códigos de Status HTTP Adicionais — 4. 429 Muitas Requisições](https://www.rfc-editor.org/rfc/rfc6585.html#:~:text=Respostas%20com%20o%20código%20de%20status%20429%20NÃO%20DEVEM%20ser%20armazenadas%20por%20um%20cache.) · recuperado em 2026-11-08
    >
    > ![RFC 6585: 429 não deve ser armazenado em cache](refs/429-cache.png)

• IDs de notas de rodapé são slugs descritivos curtos, não números. Reutilize o mesmo [^id] quando a mesma passagem apoia duas afirmações.
• Salve capturas de tela em refs/ ao lado do arquivo markdown; nome do arquivo = slug da nota de rodapé. Exclua PNGs para citações descartadas.

Resposta em chat: sem notas de rodapé (terminais as mostram como texto bruto). Coloque a prova diretamente sob a afirmação que ela apoia:

Os clientes não devem armazenar em cache respostas de limitação de taxa:

> Respostas com o código de status 429 NÃO DEVEM ser armazenadas por um cache.
> — [Códigos de Status HTTP Adicionais — 4. 429 Muitas Requisições](https://www.rfc-editor.org/rfc/rfc6585.html#:~:text=Respostas%20com%20o%20código%20de%20status%20429%20NÃO%20DEVEM%20ser%20armazenadas%20por%20um%20cache.)

• Sem data retrieved (a resposta é a recuperação).
• Salve capturas de tela de chat sob o diretório temporário do sistema (por exemplo, $TMPDIR/receipts/<slug>.png), nunca dentro do projeto do usuário. Se seu host tiver uma ferramenta para mostrar ao usuário um arquivo ou imagem, mostre cada captura de tela com ela; caso contrário, dê o caminho absoluto completo de cada uma em sua própria linha após a citação.
• Nenhuma captura de tela solicitada → termine a resposta com uma oferta de uma linha, por exemplo, "Quer capturas de tela destas passagens?"

Ambos:

• Seu próprio raciocínio ou recomendação não recebe citação; diga que é seu (ou da equipe) raciocínio, não da fonte. Uma afirmação factual sobre o mundo exterior (como bibliotecas, navegadores ou padrões se comportam) precisa de uma citação ou deve ser formulada como uma expectativa.
• Capturas de tela são opt-in: são baratas (cerca de meio segundo por página), mas adicionam arquivos de imagem que o usuário precisa manter ou excluir. Adicione "out" apenas quando o usuário solicitar capturas de tela ou, em um arquivo markdown, a evidência é visual (uma tabela, figura, layout de código) onde o texto sozinho perde significado. Inclua uma imagem ou caminho apenas para entradas com screenshot no resultado.
• Cite a passagem mais curta que apoie totalmente a afirmação (uma frase é típica).

Quando o script falha

Resultado	Faça
match: fuzzy	Use quote_on_page (a captura de tela já destaca). Se não apoiar mais sua afirmação, mude a afirmação.
match: none	Pesquise a página de outra forma (passagem diferente, URL de seção diferente). Ainda nada → descarte a afirmação ou marque-a como **NÃO VERIFICADO:** com um link simples. Nunca apresente uma citação não verificada como um blockquote.
ok: false + erro (PDF, muro de login, verificação de bot, 403)	Link simples + **NÃO VERIFICADO (não foi possível carregar: <erro>)**. Não fabrique a citação de memória ou WebFetch.
occurrences > 1 e excerpt é o errado	Reexecute com "prefix" ou "suffix" definido para as palavras vizinhas da que você queria.

Erros Comuns

• Citar o que a página "basicamente diz" → blockquotes são apenas literais; a paráfrase vai na prosa.
• Usar uma âncora de seção (#section-4) em vez de fragment_url → o leitor ainda tem que caçar.
• Citar uma passagem cujo excerpt contradiz a afirmação (por exemplo, a próxima frase diz "isso não se aplica a…").
• Executar WebFetch para "verificar" → ele resume; não pode confirmar texto literal. Use o script.
• Confiar no resumo de resposta de uma ferramenta de busca sobre o que uma página diz ou omite → ele parafraseia como WebFetch, e frequentemente coloca mal qual seção diz o quê. Coloque a frase disputada através do script.
• "Verificar" um rascunho verificando apenas as citações já nele → suas afirmações de ausência e afirmações disputadas ficam não testadas, então uma resposta falsa parece totalmente verificada.