← Tutti gli articoli

API e helper

Strumenti di ispezione della pagina di AI Helper — query_page e list_structure

17 maggio 2026 · di JustZix Team

Un assistente IA vale solo quanto ciò che può vedere. AI Helper non lavora a partire da una descrizione vaga della pagina — ha strumenti per guardare il DOM reale e la tua libreria JustZix esistente. Questo post copre i due strumenti di ispezione: query_page e list_structure.

Il contesto iniziale

Ogni messaggio che invii porta già l'URL della pagina, il titolo e un frammento HTML. È sufficiente per richieste semplici. Ma un frammento è un frammento — per un selettore preciso il modello spesso ha bisogno di guardare più da vicino una parte specifica della pagina. È a questo che servono gli strumenti di ispezione.

query_page — guarda il DOM dal vivo

Il modello passa un selettore CSS; lo strumento lo esegue sulla pagina corrente e restituisce il numero di corrispondenze più l'HTML delle corrispondenze.

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

risultato:
  matches: 1
  html: "<nav class=\"nav\"> ... </nav>"

Questo trasforma l'indovinare in verificare. Invece di scrivere CSS per una struttura che immagina, il modello può confermare cosa c'è realmente: .nav esiste, ce n'è uno o cinque, quali classi portano i figli, il pulsante è dentro un wrapper. Con ciò, il selettore che scrive prende di mira la pagina reale.

Come lo usa il modello

• Conferma che un elemento esiste — interroga il selettore, verifica che il conteggio non sia zero.
• Restringi un selettore — inizia ampio, leggi l'HTML restituito, poi interroga qualcosa di più specifico.
• Verifica l'unicità — un conteggio di 1 significa che il selettore è specifico; un conteggio di 30 significa che è troppo ampio per una correzione mirata.
• Leggi la struttura — osserva le relazioni genitore/figlio prima di scrivere un selettore :has() o discendente.

Nel corso di un turno agentico il modello può chiamare query_page diverse volte, affinando man mano che apprende — tutto dentro il budget di 8 passi.

list_structure — leggi le tue regole esistenti

Il secondo strumento guarda non la pagina ma la tua libreria JustZix. list_structure restituisce le tue cartelle, gruppi e regole insieme ai loro id.

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

risultato:
  folders:
    - id: f_12  "Siti di notizie"
      groups:
        - id: g_3  "Correzioni di layout"
          rules:
            - id: r_88  "Nascondi annunci nella barra laterale"
            - id: r_90  "Colonna dell'articolo più larga"

Perché il modello ne ha bisogno:

• Evita i duplicati — se una regola simile esiste già, il modello può indicartela invece di crearne un'altra.
• Colloca le nuove cose con buon senso — una nuova regola per un sito di notizie può andare nella tua cartella "Siti di notizie" esistente invece di disperdere regole sciolte.
• Usa id reali — create_group e create_rule hanno bisogno di un id genitore; list_structure è da dove provengono quegli id.

È in sola lettura. Vedere la tua struttura non è la stessa cosa che cambiarla — creare una cartella, un gruppo o una regola richiede comunque gli strumenti di creazione e la tua conferma esplicita.

Perché l'ispezione su richiesta batte lo scaricare l'intera pagina

Un'alternativa ovvia sarebbe inviare al modello l'intero HTML della pagina in anticipo. AI Helper deliberatamente non lo fa. L'ispezione su richiesta vince per motivi reali:

Una moderna web app può essere centinaia di kilobyte di HTML. Stipare tutto questo nel contesto è lento, costoso e spesso controproducente — il segnale viene sepolto nel rumore. Un query_page mirato per .cookie-banner dà al modello esattamente le poche righe che gli servono.

Anche l'aggiornamento conta

Le pagine non sono statiche. I menu si aprono, le modali appaiono, il contenuto si carica in ritardo. Poiché query_page viene eseguito nel momento in cui è chiamato, il modello legge il DOM com'è in questo momento — inclusi gli elementi che non esistevano quando hai aperto la chat per la prima volta. Uno scaricamento una tantum della pagina non può farlo.

L'ispezione alimenta il flusso di lavoro

Questi strumenti sono il primo passo del più ampio flusso di lavoro agentico: ispeziona con query_page e list_structure, testa in un pannello TEMP, chiedi a te di verificare, poi persisti. Una buona ispezione è ciò che rende accurati i passi successivi — il selettore è giusto perché il modello ha effettivamente guardato.

Vedi anche

• L'intero flusso di lavoro agentico con tool-calling
• Ti presentiamo AI Helper — la panoramica
• Costruisci una regola con AI Helper, passo dopo passo

L'ispezione su richiesta è ciò che mantiene AI Helper preciso ed economico. Scarica JustZix, aggiungi una chiave e chiedigli di guardare un elemento complicato.