alanchoi00/citation-sources-avec-extraits

Citer des sources avec des extraits

Présentation

Chaque affirmation citée porte sa preuve en ligne : le passage textuel, un lien qui pointe directement vers ce passage et le surligne, et éventuellement une capture d'écran. Les lecteurs vérifient sans avoir à cliquer ; un clic les amène exactement sur le texte. Fonctionne pour les fichiers Markdown et pour les réponses dans le chat.

Chaque citation doit provenir de la sortie de snap.mjs, jamais de la mémoire, d'un résumé de résultat de recherche ou d'un outil de récupération qui résume. Les résumés de recherche et les outils de type WebFetch paraphrasent les pages ; seul le script vérifie le texte rendu textuellement.

Vérifiez les affirmations, pas seulement les citations. Une citation correspondante prouve que la page dit cela. Elle ne prouve rien sur ce que la page ne dit pas. Deux types d'affirmations passent toujours par le script comme leurs propres entrées de lot, y compris lorsque vous ne faites que « vérifier un brouillon » :

• Absence : avant d'écrire qu'une page ne dit pas, ne mentionne pas ou n'exige pas quelque chose, ajoutez la phrase qui serait là si c'était le cas (par exemple, Les réponses avec le code d'état 429 NE DOIVENT PAS être stockées par un cache.). Seul correspondance: aucune étaye l'absence, puis écrivez « introuvable sur », jamais « la spécification ne dit rien sur X ».
• Désaccord : lorsque la mémoire, un résumé de recherche, un brouillon que vous avez déjà écrit ou les exemples de cette compétence sont en désaccord sur ce que dit une page, ajoutez la phrase contestée. Le résultat du script la tranche, quel que soit le côté qu'il favorise. (Chaque citation dans les exemples de cette compétence a été vérifiée avec le script.)

Configuration (une fois par machine)

npm install --prefix <dossier-comp>/scripts && npx --prefix <dossier-comp>/scripts playwright install chromium

<dossier-comp> est le répertoire contenant ce SKILL.md.

Le script

Rédigez d'abord le document ou la réponse, rassemblez chaque citation, puis vérifiez-les toutes en un seul appel par lot :

node <dossier-comp>/scripts/snap.mjs --batch - <<'EOF'
[
  {"url": "https://www.rfc-editor.org/rfc/rfc6585.html", "quote": "Responses with the 429 status code MUST NOT be stored by a cache."},
  {"url": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After", "quote": "A non-negative decimal integer", "out": "/chemin/absolu/docs/refs/delay.png"}
]
EOF

Un navigateur pour le lot ; les citations sur la même URL partagent un chargement de page. Utilisez des chemins absolus pour out. L'entrée peut également être {"defaults": {...}, "cites": [...]} pour appliquer des options de capture d'écran à chaque entrée. La sortie du lot est un tableau JSON dans l'ordre d'entrée (le mode simple, snap.mjs "<url>" --quote "...", imprime un objet). Chaque entrée :

Champ	Utilisation
ok / match	exact/loose = textuel. fuzzy = votre citation était erronée ; utilisez quote_on_page à la place et revérifiez que l'affirmation tient toujours. none = pas sur la page.
quote_on_page	Le texte à mettre dans le bloc de citation. Jamais votre --quote d'origine.
fragment_url	Le lien à utiliser (a #:~:text=, surligne dans Chrome/Safari/Firefox).
excerpt	Paragraphe environnant, pour vérifier le contexte (négations, mises en garde, « sauf quand… »). Vous voulez en citer plus ? Relancez avec ce passage plus long comme --quote pour que le lien et la capture d'écran correspondent.
title, section, retrieved	La ligne d'attribution : [<titre> — <section>](fragment_url) · récupéré le <date>, ou [<titre>](fragment_url) quand section est absent. Utilisez ces champs ; n'ajoutez pas de numéros de section de mémoire.
occurrences / occurrence	Présent lorsque la citation apparaît plus d'une fois. Vérifiez que excerpt est celui que vous vouliez ; sinon, relancez avec prefix/suffix (les mots juste avant/après sur la page).
hidden	La citation se trouve dans un contenu que la page cache (par exemple, un onglet inactif) : vérifiée, mais pas de capture d'écran.
note	Tout autre chose utile à savoir (correspondance floue, section réduite développée, repli de cadre). Lisez-la.
internal	La page est sur un réseau interne. Son contenu peut être confidentiel ; ne citez pas plus que ce dont l'affirmation a besoin.

Code de sortie 0 = tout trouvé, 1 = certains non trouvés, 2 = certains en erreur (PDF, 4xx, mur de connexion, vérification de bot, délai d'attente). Attendez-vous à un lot de suivi : mettez chaque entrée qui nécessite un autre passage (échec, flou, mauvaise occurrence ou un passage plus long souhaité) ensemble.

Options de capture d'écran

Champs facultatifs sur n'importe quelle entrée (ou dans defaults). Adaptez le libellé de l'utilisateur ; sans libellé, omettez-les.

L'utilisateur dit	Champ
« captures d'écran serrées », « juste la citation »	"frame": "quote" (par défaut paragraph)
« montrer toute la section »	"frame": "section" (la limite de hauteur passe automatiquement à 1200)
« plein écran », « montrer la page autour »	"frame": "viewport"
« quelques lignes autour »	"context": 2 (lignes de texte entières au-dessus et en dessous)
« taille mobile »	"width": 390 (par défaut 1100)
« gardez-les courtes »	"max_height": 150 (par défaut 500 ; le recadrage se centre sur la citation)
« surligner en jaune », « pas de surlignage »	"highlight": "#fff3a0" / "none"
« mode sombre »	"theme": "dark" (uniquement les sites avec un thème sombre ; note le dit sinon)
« images plus petites »	"scale": 1 (par défaut 2)

Celles-ci ne façonnent que les captures d'écran. Contexte souhaité dans le texte lui-même (ou sans captures d'écran) → citez un passage plus long tiré de excerpt, relancez dans le lot de suivi. Les citations dans les cellules de tableau encadrent automatiquement la ligne plus la ligne d'en-tête. Chaque option, avec sa capture d'écran, se trouve dans examples/README.md du dépôt.

Format de sortie

Choisissez le format selon l'endroit où va le texte.

Fichier Markdown : affirmation dans le texte, note de bas de page avec la preuve :

Les clients ne devraient pas mettre en cache les réponses de limitation de débit.[^429-cache]

[^429-cache]: > Responses with the 429 status code MUST NOT be stored by a cache.
    >
    > — [Additional HTTP Status Codes — 4. 429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585.html#:~:text=Responses%20with%20the%20429%20status%20code%20MUST%20NOT%20be%20stored%20by%20a%20cache.) · retrieved 2026-11-08
    >
    > ![RFC 6585 : 429 ne doit pas être mis en cache](refs/429-cache.png)

• Les identifiants de notes de bas de page sont de courts slugs descriptifs, pas des numéros. Utilisez le même [^id] lorsque le même passage étaye deux affirmations.
• Enregistrez les captures d'écran dans refs/ à côté du fichier Markdown ; nom de fichier = slug de la note de bas de page. Supprimez les PNG pour les citations que vous avez abandonnées.

Réponse dans le chat : pas de notes de bas de page (les terminaux les affichent comme du texte brut). Mettez la preuve directement sous l'affirmation qu'elle étaye :

Les clients ne devraient pas mettre en cache les réponses de limitation de débit :

> Responses with the 429 status code MUST NOT be stored by a cache.
> — [Additional HTTP Status Codes — 4. 429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585.html#:~:text=Responses%20with%20the%20429%20status%20code%20MUST%20NOT%20be%20stored%20by%20a%20cache.)

• Pas de date récupéré le (la réponse est la récupération).
• Enregistrez les captures d'écran du chat dans le répertoire temporaire du système (par exemple, $TMPDIR/receipts/<slug>.png), jamais dans le projet de l'utilisateur. Si votre hôte dispose d'un outil pour montrer un fichier ou une image à l'utilisateur, montrez chaque capture d'écran avec cet outil ; sinon, donnez le chemin absolu complet de chacune sur sa propre ligne après la citation.
• Pas de captures d'écran demandées → terminez la réponse par une offre d'une ligne, par exemple « Vous voulez des captures d'écran de ces passages ? »

Les deux :

• Votre propre raisonnement ou recommandation n'obtient pas de citation ; dites qu'il s'agit de votre raisonnement (ou de celui de l'équipe), pas de la source. Une affirmation factuelle sur le monde extérieur (comment se comportent les bibliothèques, les navigateurs ou les normes) a besoin d'une citation ou doit être formulée comme une attente.
• Les captures d'écran sont facultatives : elles sont peu coûteuses (environ une demi-seconde par page) mais ajoutent des fichiers image que l'utilisateur doit conserver ou supprimer. Ajoutez "out" uniquement lorsque l'utilisateur demande des captures d'écran ou, dans un fichier Markdown, que la preuve est visuelle (un tableau, une figure, une disposition de code) où le texte seul perd son sens. Incluez une image ou un chemin uniquement pour les entrées avec screenshot dans le résultat.
• Citez le passage le plus court qui étaye entièrement l'affirmation (une phrase est typique).

En cas d'échec du script

Résultat	Faites
match: fuzzy	Utilisez quote_on_page (la capture d'écran le surligne déjà). Si elle n'étaye plus votre affirmation, modifiez l'affirmation.
match: none	Recherchez la page d'une autre manière (passage différent, URL de section différente). Toujours rien → abandonnez l'affirmation ou marquez-la **NON VÉRIFIÉ:** avec un lien simple. Ne présentez jamais une citation non vérifiée comme un bloc de citation.
ok: false + erreur (PDF, mur de connexion, vérification de bot, 403)	Lien simple + **NON VÉRIFIÉ (impossible de charger : <erreur>)**. N'inventez pas la citation de mémoire ou via WebFetch.
occurrences > 1 et excerpt est le mauvais	Relancez avec "prefix" ou "suffix" défini sur les mots voisins de celui que vous vouliez.

Erreurs courantes

• Citer ce que la page « dit en gros » → les blocs de citation sont textuels uniquement ; la paraphrase va dans le texte courant.
• Utiliser une ancre de section (#section-4) au lieu de fragment_url → le lecteur doit encore chercher.
• Citer un passage dont excerpt contredit l'affirmation (par exemple, la phrase suivante dit « cela ne s'applique pas à… »).
• Exécuter WebFetch pour « vérifier » → il résume ; il ne peut pas confirmer le texte textuel. Utilisez le script.
• Faire confiance au résumé de réponse d'un outil de recherche sur ce qu'une page dit ou omet → il paraphrase comme WebFetch, et souvent se trompe sur quelle section dit quoi. Passez la phrase contestée dans le script.
• « Vérifier » un brouillon en ne contrôlant que les citations déjà présentes → ses affirmations d'absence et ses affirmations contestées restent non testées, donc une réponse fausse semble entièrement vérifiée.