AI Score
Jamdesk valuta la leggibilità della documentazione per gli agenti AI secondo AFDocs a ogni build. Scopri il punteggio, correggi i problemi e monitoralo nel tempo.
Gli assistenti AI rispondono sempre più spesso alle domande sul tuo prodotto direttamente dalla documentazione, ma solo quando riescono effettivamente a leggerla. AI Score misura proprio questo. Dopo ogni build, Jamdesk analizza il tuo sito pubblicato secondo lo standard open AFDocs per la predisposizione agli agenti e assegna un punteggio da 0 a 100, un voto in lettere e una suddivisione dei problemi su cui puoi intervenire.
Gli screenshot mostrano l'interfaccia in inglese.
Provalo prima su qualsiasi sito. Lo strumento AI Score gratuito valuta qualsiasi URL di documentazione secondo lo stesso standard, mentre l'estensione AI Score per Chrome valuta i siti mentre navighi. In Jamdesk, il punteggio viene calcolato automaticamente sulla tua documentazione.
Come funziona il punteggio
AI Score viene eseguito automaticamente, senza configurazione. Dopo ogni build completata correttamente, Jamdesk attende che la nuova versione sia online, quindi analizza la documentazione pubblicata e registra il risultato.
- Viene eseguito a ogni build. Ogni deploy calcola nuovamente il punteggio del sito, quindi una regressione viene rilevata nel momento stesso in cui viene pubblicata.
- Punteggio da 0 a 100 e voto in lettere (da A+ a F), misurati secondo lo standard open AFDocs. È lo stesso motore alla base dello strumento pubblico gratuito.
- Eseguilo di nuovo in qualsiasi momento. Apri la pagina AI Score del progetto e fai clic su Run score now per valutare di nuovo il sito online senza attendere una build.
Lo trovi nel dashboard, sotto il progetto → AI Score.
Leggere il punteggio
La pagina AI Score è composta da tre parti:
- Indicatore circolare del punteggio. Il punteggio e il voto attuali, oltre alla variazione rispetto all'ultima build.
- Linea di tendenza. Il punteggio delle build recenti, così puoi vedere subito un'eventuale diminuzione.
- Schede delle categorie. I controlli sono raggruppati in sette aree, ciascuna con il proprio voto. Espandine una per vedere i singoli controlli e sapere se sono stati superati, hanno generato un avviso o non sono stati superati.
Nel piè di pagina sono indicati gli elementi analizzati, il numero di pagine campionate e la versione della specifica AFDocs.
Cosa misura il punteggio
Ogni categoria raggruppa controlli correlati sulla predisposizione agli agenti:
| Categoria | Cosa include |
|---|---|
| Individuabilità dei contenuti | llms.txt e i segnali che indirizzano gli agenti verso i tuoi contenuti |
| Disponibilità Markdown | Una versione Markdown pulita di ogni pagina che gli agenti possono leggere |
| Dimensioni della pagina e rischio di troncamento | Pagine abbastanza piccole da rientrare nella finestra di contesto di un agente |
| Struttura dei contenuti | Intestazioni, ordine e contenuti che iniziano nelle prime sezioni della pagina |
| Stabilità degli URL e redirect | URL stabili e redirect corretti verso lo stesso host |
| Osservabilità e salute dei contenuti | Codici di stato, caching e corrispondenza tra ciò che vedono lettori e agenti |
| Autenticazione e accesso | Se le pagine sono effettivamente raggiungibili dagli agenti |
Risolvere i problemi
Ogni controllo che genera un avviso o non viene superato include una spiegazione in linguaggio semplice e una soluzione descritta in termini di MDX e docs.json. Vengono mostrati due tipi di risultati:
- Problemi da risolvere nei contenuti. Ad esempio, una pagina il cui contenuto effettivo inizia troppo in basso, una pagina troppo grande che dovrebbe essere suddivisa oppure contenuti generati da un componente interattivo che non compaiono nel Markdown della pagina. Il testo della soluzione indica il passaggio successivo e le pagine a cui si applica.
- Problemi gestiti da Jamdesk.
llms.txt, l'esportazione Markdown, i codici di stato e il caching vengono generati automaticamente. Se uno di questi controlli non viene superato, di solito si tratta di un problema temporaneo di build: esegui di nuovo il punteggio dopo la build successiva e contatta l'assistenza se il problema persiste.
Copiare il prompt per la correzione
Ogni controllo risolvibile include un pulsante Copy prompt to fix. Il pulsante copia un prompt pronto da incollare che specifica il controllo, il problema rilevato e come risolverlo in MDX o docs.json. Incollalo in un agente di programmazione AI (Claude Code, il plugin Claude di Jamdesk, Cursor o Codex) e lascia che apporti la modifica, quindi esegui il push per ricostruire e calcolare nuovamente il punteggio.
Ricevere un'email quando cambia il punteggio
Il tuo team non deve controllare il dashboard. Jamdesk invia ai membri del progetto un'email con il nuovo punteggio e il problema più importante da risolvere quando una build produce il primo punteggio, modifica il punteggio di almeno 3 punti oppure lo riporta al valore perfetto di 100.
- Attivalo per ogni progetto. L'interruttore Email team when score changes si trova nella parte superiore della pagina AI Score. È attivo per impostazione predefinita.
- Le piccole variazioni non generano notifiche. Una variazione di uno o due punti non invia un'email autonomamente, ma non viene ignorata: Jamdesk confronta ogni nuovo punteggio con l'ultimo per cui ti ha inviato un'email, quindi le variazioni graduali si sommano e ricevi una notifica quando la variazione totale raggiunge 3 punti.
Sia le nuove esecuzioni manuali sia i punteggi attivati dalle build possono inviare un'email; le scansioni arretrate e quelle dello strumento pubblico non lo fanno mai.
Risoluzione dei problemi
Una scansione può risultare vuota se il sito era momentaneamente irraggiungibile, ha restituito un errore o ha bloccato lo scanner. Jamdesk non salva questi risultati, quindi un problema temporaneo non fisserà un punteggio errato né rovinerà la linea di tendenza. Rimane visualizzato l'ultimo punteggio valido; fai clic su Run score now per riprovare.
Gli agenti AI non possono leggere le pagine protette da password, quindi il punteggio ne tiene conto. Se limitare l'accesso è intenzionale, ad esempio per documentazione interna o pre-release, un punteggio basso è previsto e non è un problema.
Un progetto noindex non ha una sitemap che Jamdesk possa analizzare, quindi AI Score viene saltato invece di essere eseguito: non c'è nulla da misurare in modo affidabile. Questo non influisce sugli agenti AI: possono comunque leggere la documentazione tramite llms.txt, che rimane pubblicato indipendentemente da noindex. Per ottenere di nuovo un punteggio, rimuovi noindex da seo.metatags.robots in docs.json.
Alcuni controlli riguardano il comportamento della piattaforma gestito da Jamdesk (llms.txt, esportazione Markdown, codici di stato e caching). Questi controlli sono superati per progettazione, quindi un errore indica quasi sempre un problema temporaneo di build. Esegui di nuovo il punteggio dopo la build successiva e contatta l'assistenza se il problema persiste.