Réviser le Site Statique
Objectif
Valider une sortie de site web statique avant que l'utilisateur ne l'édite davantage, ne le publie ou ne le considère comme terminé.
Cette compétence est une porte de qualité pour les sites générés en HTML/CSS/JS. Elle ne choisit pas un thème, ne recrée pas une référence, ne migre pas de contenu et ne déploie pas le site. Elle vérifie que le dossier généré se comporte comme un véritable site statique.
Vérifications principales :
- Les fichiers sources sont en UTF-8 valide et lisibles par un humain.
- Les liens, scripts, feuilles de style, images et autres actifs locaux se résolvent.
- Les liens et actifs propres au site utilisent des chemins relatifs à la page par défaut, et non des chemins absolus racine comme
/actifs/style.css. - La sortie peut être ouverte directement depuis
index.htmlpour un aperçu manuel, sauf si l'utilisateur a explicitement accepté un comportement serveur uniquement. - Les pages générées couvrent les types de pages attendus.
- Le site s'affiche dans un navigateur réel via HTTP local.
- Les mises en page desktop et mobile sont utilisables.
- Les erreurs de console, les interactions cassées, les espaces réservés restants et le texte spécifique à la source copiée sont signalés ou corrigés.
Contrat
Entrées :
- Racine du site statique telle que
site/,dist/,out/,public/,docs/, ou racine du dépôt. - Portée de page attendue facultative, URL d'aperçu local,
EDITING.md, URL/capture d'écran de référence, et chaînes spécifiques à la source interdites.
Sorties :
- Résultats classés par sévérité, ou corrections lorsque la validation fait partie d'une tâche de construction/correction.
- Résultats d'audit statique, pages/vues du navigateur vérifiées, et fichiers modifiés le cas échéant.
- État de réussite/échec clair pour la publication ou l'aptitude à la remise.
Limites :
- Ne choisissez pas de thèmes, ne recréez pas de sites web, ne migrez pas de contenu, ne personnalisez pas d'identité et ne déployez pas.
- Ne reconcevez pas le site pendant la validation, sauf si un problème visuel bloque l'utilisabilité et que l'utilisateur a demandé des corrections.
- N'approuvez pas les chemins absolus racine pour le site local, sauf si
--allow-root-absoluteest utilisé intentionnellement et que la limitation est indiquée.
Condition de succès :
- Aucun bloqueur ne subsiste : navigation principale cassée, type de page requis manquant, encodage source illisible, échec d'actif local, plantage de console, inutilisabilité mobile, ou problème de chemin absolu racine accidentel.
- Les avertissements sont soit corrigés, soit documentés, soit acceptés par l'utilisateur.
Si la condition de succès échoue :
- Corrigez les problèmes locaux simples lorsque la validation fait partie de la construction.
- Acheminez les échecs plus importants vers
make-personal-site,copy-website-style,personalize-site,add-blog-posts, ouedit-site-partselon la surface défaillante. - Réexécutez l'audit déterministe et les vérifications de navigateur affectées.
Utilisation Conjointe
Utilisez cette compétence après :
make-personal-sitecrée ou reconçoit un site personnel statique original.copy-website-stylerecrée le style d'un site cible sous forme de fichiers statiques.- Un utilisateur pointe vers un dossier de sortie statique existant et demande s'il est suffisant.
- Un utilisateur demande de vérifier, valider, faire du QA, inspecter, auditer ou tester un site statique avant publication.
Si l'utilisateur fournit un projet source de framework, validez le dossier de sortie statique déjà construit lorsque c'est possible. N'introduisez pas de workflow de construction de framework ici, sauf si l'utilisateur le demande explicitement.
Entrées
Utilisez toutes les entrées disponibles :
- Dossier racine du site statique, tel que
site/,dist/,out/, oupublic/. - URL d'aperçu local, si un serveur est déjà en cours d'exécution.
- Portée de page attendue : page d'accueil uniquement, site personnel complet, blog, portfolio, notes, liens, recréation de style, etc.
EDITING.md, plan de page, ou toute note de remise produite par une autre compétence.- URL ou capture d'écran de référence, lors de la validation d'une recréation de style.
- Chaînes connues qui ne doivent pas subsister, telles que les noms d'auteur d'origine, les domaines, les e-mails, les ID d'analytique, ou les anciens textes d'espace réservé.
Si la racine du site n'est pas claire, inspectez les dossiers voisins et choisissez celui qui contient index.html et les actifs statiques.
Workflow
- Identifiez la racine du site statique et la portée de page attendue.
- Lisez
EDITING.mdou déduisez le plan de page à partir des fichiers HTML et des liens de navigation. - Exécutez le script d'audit de fichier déterministe.
- Démarrez ou réutilisez un serveur HTTP local pour la racine statique.
- Validez le site dans un navigateur réel aux largeurs desktop et mobile.
- Ouvrez au moins une page représentative pour chaque type de page générée.
- Testez les interactions principales telles que la navigation, le changement de thème, la recherche/filtre, les boutons de copie, le menu mobile, et la pagination.
- Vérifiez les erreurs de console du navigateur et les ressources réseau manquantes.
- Auditez la compatibilité des chemins relatifs, les espaces réservés, la lisibilité UTF-8, et les textes résiduels spécifiques à la source.
- Corrigez les défauts simples lorsque l'utilisateur a demandé une validation dans le cadre d'une construction ; sinon, rapportez d'abord les résultats.
Audit de Fichier Déterministe
Utilisez le script fourni avant la validation du navigateur :
python scripts/static_site_check.py <site-root>
Pour les recréations de style ou les nettoyages de site copié, transmettez les chaînes spécifiques à la source interdites :
python scripts/static_site_check.py <site-root> --forbid "auteur-original" --forbid "domaine-original.com"
Le script vérifie :
- Décodage UTF-8 pour les fichiers HTML, CSS, JS, JSON, Markdown, SVG, XML et texte.
- Mojibake suspects et caractères de remplacement.
<meta charset="utf-8">manquant dans les fichiers HTML.- Références
href,src,srcset,poster,action, etdata-srclocales cassées. - Références absolues racine au site local telles que
/actifs/...,/articles/...,/donnees/..., ou/images/...sauf autorisation explicite. - Références d'actifs CSS
url(...), y compris les URL locales manquantes ou absolues racine. - Chaînes absolues racine courantes dans le HTML, JavaScript et les données JSON.
- Liens qui s'échappent de la racine du site.
- Chaînes d'espace réservé courantes.
- Chaînes interdites fournies avec
--forbid. - Fichiers racine de déploiement sensibles à la vie privée tels que
.env, les clés privées, les fichiers d'identifiants, et les artefacts de compte de service locaux. - Assignations de type secret, motifs de jeton connus, blocs de clé privée, et chemins de système de fichiers absolus locaux dans le texte source.
- Fichiers temporaires, journaux, sauvegardes et artefacts de système d'exploitation qui ne devraient pas être publiés.
- Nombre de pages HTML et types de pages déduits.
- Si
EDITING.mdexiste.
L'audit de fichier doit toujours vérifier la lisibilité UTF-8 pour les fichiers fournisseurs, mais ne doit pas traiter les mots ressemblant à des espaces réservés dans les bundles minimisés de fournisseurs tiers comme du contenu d'espace réservé du site.
Traitez les erreurs de script comme des bloqueurs, sauf si l'utilisateur ne voulait qu'un examen exploratoire rapide. Traitez les avertissements comme des éléments à inspecter manuellement.
Si le site est intentionnellement conçu pour nécessiter des chemins relatifs à la racine sous un domaine racine personnalisé, exécutez le script avec --allow-root-absolute et indiquez que l'ouverture directe via file:// et le déploiement en sous-chemin de projet GitHub ne sont pas garantis. N'utilisez pas cette exception pour les sites statiques personnels plats générés, sauf si l'utilisateur accepte explicitement ce compromis.
Compatibilité des Chemins
Les sites statiques plats générés doivent fonctionner dans trois contextes courants :
- Ouvrir directement
index.htmldepuis le système de fichiers pour un aperçu manuel rapide. - Servir le dossier via HTTP local pour l'automatisation du navigateur et les vérifications de console/réseau.
- Déployer sur un hôte statique qui peut servir le site depuis une racine de domaine ou un sous-chemin.
Règle par défaut :
- Utilisez des chemins relatifs à la page pour les liens et actifs propres au site.
- Depuis les pages racine, utilisez
actifs/style.css,articles/exemple.html, eta-propos.html. - Depuis les pages imbriquées, utilisez
../actifs/style.css,../blog.html, et des chemins relatifs entre frères selon le cas. - N'utilisez pas
/actifs/style.css,/articles/exemple.html,/donnees/articles.json,/images/truc.png, ou/pour la navigation interne par défaut.
Vérifiez également les liens générés par JavaScript, les résultats de recherche, les filtres de balises, les boutons de copie, les cartes dynamiques, les références RSS/plan de site, les couvertures d'images, les valeurs CSS url(...), les favicons, les polices, et les actifs fournisseurs KaTeX/math. Il ne suffit pas que les attributs HTML statiques soient relatifs si JavaScript insère ensuite des chemins absolus racine.
Les chemins absolus racine ne sont acceptables que lorsque l'utilisateur souhaite explicitement un déploiement serveur-racine uniquement, par exemple une racine de domaine personnalisée, et comprend que l'ouverture directe de fichier et les sous-chemins GitHub Pages peuvent être cassés.
Validation du Navigateur
Utilisez un navigateur réel avant la livraison finale. Servez les fichiers locaux via HTTP, pas file:// :
python -m http.server 8000
Ensuite, ouvrez :
http://127.0.0.1:8000/
Utilisez un outil de navigation interactif réellement disponible comme chemin de validation de premier choix pour les cibles HTTP locales. "Disponible" signifie que l'outil est exposé dans la liste d'outils appelables du tour actuel, pas seulement mentionné dans une compétence, une liste de plugins ou une description du système. Dans Codex, il peut s'agir du plugin Navigateur/navigateur intégré à l'application lorsque l'utilisateur ou le client l'a acheminé dans le tour ; dans d'autres agents, il peut s'agir d'un navigateur visible équivalent, d'un outil d'utilisation de navigateur ou d'un navigateur avec outils de développement. Il doit ouvrir l'URL locale, inspecter les vues desktop/mobile, exercer les interactions et vérifier les problèmes visibles de console/réseau.
Si aucun outil de navigation interactif n'est exposé dans le tour actuel, ne prétendez pas que la passe navigateur a eu lieu. Si la validation en dépend, demandez à l'utilisateur d'activer ou d'invoquer l'outil de navigation en utilisant la méthode d'acheminement de son client ; pour Codex, cela peut signifier envoyer une requête qui mentionne explicitement @browser. Si l'utilisateur ne réachemine pas ou si le client n'a pas un tel outil, recourez à Playwright, aux captures d'écran, aux audits statiques ou aux vérifications shell et indiquez qu'il s'agissait d'un repli, et non d'une validation de navigateur interactive complète.
Ne recourez pas par défaut à Playwright, aux scripts de capture d'écran sans tête, aux fenêtres de navigateur ouvertes via shell, ou à la génération de captures d'écran statiques lorsqu'un outil de navigation interactif est réellement appelable. Les captures d'écran sont des preuves utiles, mais elles ne remplacent pas une passe de navigateur interactive. Utilisez Playwright uniquement comme repli lorsqu'aucun outil de navigation interactif n'est appelable, lorsque l'utilisateur demande explicitement Playwright, ou lorsqu'une régression scriptée reproductible est spécifiquement nécessaire.
Utilisez l'automatisation Chrome uniquement lorsque la tâche nécessite le profil Chrome de l'utilisateur, les onglets existants, les extensions, les pages distantes authentifiées ou un comportement spécifique à Chrome. Ne comptez pas sur l'automatisation d'extension Chrome pour les pages file:// ; utilisez HTTP local à la place.
Même si l'automatisation doit utiliser HTTP local, la source générée doit toujours être compatible avec l'ouverture directe en utilisant des chemins relatifs et en évitant les hypothèses serveur-uniquement pour le contenu principal. Si l'application/le navigateur permet une vérification rapide via file://, ouvrez directement le fichier racine index.html et vérifiez que le CSS, les images, la navigation et les sous-pages représentatives ne sont pas cassés. Si l'automatisation de fichier n'est pas disponible, fiez-vous à l'audit déterministe des chemins absolus racine et mentionnez si l'ouverture directe a été vérifiée manuellement ou automatiquement.
Vérifications du navigateur :
- Premier écran desktop : composition, espacement, typographie, navigation visible et débordement évident.
- Premier écran mobile : comportement de navigation, habillage du texte, priorité du contenu et débordement horizontal.
- Navigation interne : tous les liens de navigation principaux s'affichent.
- Couverture des types de pages : au moins une passe navigateur ou capture d'écran pour chaque type de page générée.
- Couverture des interactions : changements de thème, menus, filtres, recherche, boutons de copie, pagination, accordéons, onglets, états de survol/clic, ou autres contrôles visibles.
- État de la console : aucune erreur JavaScript évidente.
- État du réseau : aucun actif CSS, JS, image ou police local manquant.
- Bases d'accessibilité : visibilité du focus pour les contrôles interactifs, contraste lisible, titres de page significatifs et texte alt non vide pour les images lorsque c'est pratique.
Pour les petits sites, cliquez sur chaque page générée. Pour les sites plus grands, échantillonnez chaque type de page et toute route mentionnée dans EDITING.md.
Couverture des Types de Pages
Déduisez les types de pages à partir des noms de fichiers, des routes, de la navigation visible et de EDITING.md.
Types de pages typiques :
- Accueil.
- À propos ou profil.
- Blog, archives, catégorie, balise, notes, ou page de liste.
- Article ou page de détail.
- Projets, portfolio, publications, ou page de travail.
- Liens, amis, ressources, maintenant, utilisations, jardin, recherche, thème/paramètres, ou autre page spéciale.
Si un site généré prétend être un blog mais n'a pas de page d'article/détail, signalez-le. S'il a une navigation vers des sous-pages qui n'existent pas, signalez-le comme bloqueur.
Encodage et Lisibilité de la Source
Les captures d'écran du navigateur ne suffisent pas. Les fichiers sources doivent être lisibles par les futurs modèles et humains.
Exigences :
- Les fichiers HTML incluent
<meta charset="utf-8">. - Le texte non-ASCII est stocké en UTF-8.
- Les commentaires HTML, CSS, les chaînes JavaScript, les fichiers JSON/données, le texte SVG, et
EDITING.mdsont lisibles sous forme source. - Pas de mojibake, caractères de remplacement, ou récupération d'encodage accidentelle du navigateur.
Si un terminal affiche du mojibake mais que le navigateur semble correct, confirmez avec une lecture consciente de l'UTF-8 avant de le déclarer cassé. Si le contenu du fichier lui-même contient du mojibake, réécrivez les chaînes affectées à partir d'un texte propre au lieu d'ajouter une autre conversion d'encodage.
Audit des Espaces Réservés et Résidus
Vérifiez si le site généré contient encore :
TODO,FIXME,lorem ipsum,placeholder,remplacez-moi,votre nom,exemple.com, ou texte d'exemple/démo.- E-mails factices, liens sociaux faux, boutons vides, ou appels à l'action morts.
- Noms d'auteur du site original, domaines, titres d'articles, e-mails, ID d'analytique, liens sociaux, liens d'amis, ou URL privés dans les recréations de style.
Ne supprimez pas les espaces réservés aveuglément si l'utilisateur en a encore besoin comme marqueurs édirables intentionnels. Signalez-les clairement, ou remplacez-les uniquement lorsque l'utilisateur a fourni du contenu réel.
Confidentialité et Résidus Locaux
Traitez ces éléments comme des bloqueurs avant publication :
.env,.npmrc,.pypirc, fichiers de clé privée, fichiers JSON d'identifiants, fichiers de compte de service, ou fichiers d'exportation de coffre-fort de mots de passe dans la racine déployable.- Assignations de type secret, jetons d'accès, blocs de clé privée, ou clés API dans les fichiers HTML, CSS, JavaScript, JSON, Markdown, SVG, ou texte.
- Chemins de système de fichiers absolus locaux tels que les chemins de lecteur Windows,
file:///...,/Utilisateurs/...,/home/..., ou/mnt/...dans la source générée.
Traitez les journaux, les sauvegardes, les fichiers temporaires et les métadonnées du système d'exploitation comme des avertissements, sauf s'ils exposent du contenu privé. Supprimez-les de la sortie déployable avant de conditionner ou de publier.
Politique de Correction
Lorsque l'utilisateur demande de "vérifier", "réviser" ou "dire ce qui ne va pas", signalez d'abord les résultats et évitez les modifications généralisées.
Lorsque la validation fait partie d'une construction