← Tous les articles

API et helpers

Outils d'inspection de page d'AI Helper — query_page et list_structure

17 mai 2026 · par JustZix Team

Un assistant IA ne vaut que par ce qu'il peut voir. AI Helper ne travaille pas à partir d'une description vague de la page — il dispose d'outils pour examiner le vrai DOM et votre bibliothèque JustZix existante. Cet article couvre les deux outils d'inspection : query_page et list_structure.

Le contexte de départ

Chaque message que vous envoyez porte déjà l'URL de la page, le titre et un fragment HTML. C'est suffisant pour les demandes simples. Mais un fragment reste un fragment — pour un sélecteur précis, le modèle a souvent besoin de regarder de plus près une partie spécifique de la page. C'est à cela que servent les outils d'inspection.

query_page — examiner le DOM en direct

Le modèle passe un sélecteur CSS ; l'outil l'exécute sur la page courante et renvoie le nombre de correspondances ainsi que le HTML des correspondances.

@@JZ_TOOL@@ {"tool": "query_page", "args": {"selector": "header .nav"}} @@END@@

résultat :
  correspondances : 1
  html : "<nav class=\"nav\"> ... </nav>"

Cela transforme la devinette en vérification. Au lieu d'écrire du CSS pour une structure qu'il imagine, le modèle peut confirmer ce qui est réellement là : .nav existe-t-il, y en a-t-il un ou cinq, quelles classes portent les enfants, le bouton est-il à l'intérieur d'un conteneur. Avec cela, le sélecteur qu'il écrit cible la vraie page.

Comment le modèle l'utilise

• Confirmer qu'un élément existe — interroger le sélecteur, vérifier que le compte n'est pas zéro.
• Affiner un sélecteur — commencer large, lire le HTML renvoyé, puis interroger quelque chose de plus spécifique.
• Vérifier l'unicité — un compte de 1 signifie que le sélecteur est spécifique ; un compte de 30 signifie qu'il est trop large pour une correction ciblée.
• Lire la structure — voir les relations parent/enfant avant d'écrire un sélecteur :has() ou de descendance.

Au cours d'un tour agentique, le modèle peut appeler query_page plusieurs fois, en affinant à mesure qu'il apprend — le tout dans le budget de 8 étapes.

list_structure — lire vos règles existantes

Le second outil ne regarde pas la page mais votre bibliothèque JustZix. list_structure renvoie vos dossiers, groupes et règles ainsi que leurs identifiants.

@@JZ_TOOL@@ {"tool": "list_structure", "args": {}} @@END@@

résultat :
  dossiers :
    - id: f_12  "Sites d'actualités"
      groupes :
        - id: g_3  "Corrections de mise en page"
          règles :
            - id: r_88  "Masquer les pubs de la barre latérale"
            - id: r_90  "Colonne d'article plus large"

Pourquoi le modèle en a besoin :

• Éviter les doublons — si une règle similaire existe déjà, le modèle peut vous y orienter au lieu d'en créer une autre.
• Placer les nouveaux éléments judicieusement — une nouvelle règle pour un site d'actualités peut aller dans votre dossier « Sites d'actualités » existant plutôt que de disperser des règles éparses.
• Utiliser de vrais identifiants — create_group et create_rule ont besoin d'un identifiant parent ; list_structure est l'endroit d'où viennent ces identifiants.

C'est en lecture seule. Voir votre structure n'est pas la même chose que la modifier — créer un dossier, un groupe ou une règle nécessite toujours les outils de création et votre confirmation explicite.

Pourquoi l'inspection à la demande vaut mieux que tout transmettre

Une alternative évidente serait d'envoyer au modèle tout le HTML de la page d'emblée. AI Helper ne le fait délibérément pas. L'inspection à la demande l'emporte pour de vraies raisons :

Une application web moderne peut représenter des centaines de kilo-octets de HTML. Tout entasser dans le contexte est lent, coûteux et souvent contre-productif — le signal se noie dans le bruit. Un query_page ciblé sur .cookie-banner donne au modèle exactement les quelques lignes dont il a besoin.

La fraîcheur compte aussi

Les pages ne sont pas statiques. Les menus s'ouvrent, les modales apparaissent, le contenu se charge tardivement. Comme query_page s'exécute au moment où il est appelé, le modèle lit le DOM tel qu'il est en ce moment — y compris des éléments qui n'existaient pas quand vous avez ouvert le chat. Une transmission unique de la page ne peut pas faire cela.

L'inspection alimente le workflow

Ces outils sont la première étape du workflow agentique plus large : inspecter avec query_page et list_structure, tester dans un panneau TEMP, vous demander de vérifier, puis persister. Une bonne inspection est ce qui rend les étapes ultérieures précises — le sélecteur est correct parce que le modèle a réellement regardé.

Voir aussi

• Le workflow agentique complet d'appel d'outils
• Découvrez AI Helper — la présentation
• Construire une règle avec AI Helper, étape par étape

L'inspection à la demande est ce qui garde AI Helper précis et peu coûteux. Téléchargez JustZix, ajoutez une clé et demandez-lui d'examiner un élément délicat.