Guida a fasi per gli agenti

01Panoramica

La guida divide il lavoro su un sito in cinque fasi, numerate da 0 a 4. La fase 0 spiega il modello di Nucleo. Le fasi da 1 a 4 portano il sito da token e sezioni fino alle parti dinamiche.

A ogni chiamata la guida legge lo stato del sito e i documenti salvati. Da questi calcola la fase corrente e l'elenco delle cose da fare.

La guida è in sola lettura: non salva nessuno stato e non ricorda le chiamate precedenti.

Si consulta con l'ability nucleo/guide, con wp nucleo guide (o wp nucleo ability run guide) e con il comando nucleo guide della CLI locale.

Le istruzioni del server MCP chiedono all'agente di chiamare nucleo-guide prima di scrivere.

Ogni regola ha un codice (R1.2). Alcuni errori e alcune segnalazioni di qualità riportano lo stesso codice nel campo guide.

02Consultazione

nucleo/guide

Cosa fa: restituisce la fase richiesta, oppure la fase corrente calcolata. La risposta contiene lo stato del sito, le regole della fase, le cose da fare, le condizioni di uscita e il comando successivo.

Come si usa: via MCP con il tool nucleo-guide. Via REST con GET /wp-json/wp-abilities/v1/abilities/nucleo/guide/run. Esempio di input: {"phase": 2, "design": "home.html"}.

Parametri:

Campi della risposta:

Permessi: current_user_can('edit_posts'). Scope OAuth nucleo:read.

Edizione: Free

Limiti noti:

• L'ability è annotata readonly, idempotent e non destructive. Il limite di frequenza delle scritture non si applica.
• I testi di regole, cose da fare e uscita sono in inglese nel codice, traducibili con il dominio nucleo.
• Se la cache di Nucleo è vuota ma i dati esistono, la prima voce di todo chiede di eseguire cache-rebuild.
• Se la lettura dei documenti si ferma al limite, l'ultima voce di todo dice quanti documenti ha letto su quanti.

wp nucleo ability run guide

Cosa fa: esegue nucleo/guide da WP-CLI e stampa la risposta JSON.

Come si usa: wp nucleo ability run guide --input='{"phase":1}' --user=<id|login>. Il prefisso nucleo/ del nome è facoltativo.

Parametri: --input, oggetto JSON con gli stessi campi dell'ability. Default {}.

Permessi: come nucleo/guide. Edizione: Free

Limiti noti: un --input che non è un oggetto JSON restituisce invalid_json. Il comando wp nucleo guide è generato per l'ability: vedi la sezione seguente.

wp nucleo guide

Cosa fa: esegue nucleo/guide con il comando generato per ogni ability (nucleo/guide diventa wp nucleo guide) e stampa la risposta JSON.

Come si usa: wp nucleo guide --input='{"phase":1}' --user=<id|login>.

Parametri: --input, oggetto JSON con gli stessi campi dell'ability.

Permessi: come nucleo/guide. Edizione: Free

Limiti noti: il comando è generato per le ability nucleo/*: il trattino nel nome diventa uno spazio (nucleo/doc-patch diventa wp nucleo doc patch). I comandi che iniziano con status, export, import, sync, docs, mcp o ability non vengono generati, per non sovrascrivere quelli esistenti.

nucleo guide

Cosa fa: chiama nucleo/guide dal computer locale e stampa la risposta come testo.

Come si usa: nucleo guide [0-4] [--design PERCORSO]. Esempio: nucleo guide 2.

Parametri:

Righe stampate, in ordine: Phase <n>: <titolo>, State: …, Checks: … (se presente), Distinct: con una riga per nodo (se presente), Coverage: <letti> of <totali> documents read (con (truncated) se la lettura si è interrotta), Basics:, To do:, Rules: (con tools: sotto ogni regola), Exit:, Next: …. Le sezioni vuote non compaiono. Next non compare quando next è null.

Permessi: come nucleo/guide, con le credenziali della CLI.

Edizione: Free

Limiti noti: la riga State mostra solo token, sezioni, layout, menu, tipi e documenti. Le righe Checks, Distinct e Coverage sono separate; Distinct compare solo se ci sono nodi distinti. Se il sito risponde con un errore, la CLI mostra il messaggio del server come errore.

Istruzioni del server MCP

Cosa fa: il server MCP invia all'agente un testo fisso all'avvio. Il testo chiede di chiamare nucleo-guide prima di scrivere e di seguire le fasi in ordine.

Come si usa: automatico, campo INSTRUCTIONS della risposta del server.

Parametri: Nessuno

Permessi: quelli del collegamento MCP.

Edizione: Free

Limiti noti: è un'indicazione. Tutti i tool restano visibili in ogni fase.

03Calcolo della fase

Fase corrente

Cosa fa: senza phase, la guida controlla le fasi da 1 a 4 in ordine. Restituisce la prima non soddisfatta. Se tutte sono soddisfatte, restituisce 4.

Come si usa: chiama nucleo/guide senza phase.

Parametri: Nessuno

Permessi: come nucleo/guide.

Edizione: Free

Limiti noti:

• La fase 0 non viene mai scelta in automatico. Si legge solo con phase: 0.
• Le condizioni verificate sono queste. Le condizioni di exit sono solo testo.

• pathLinks, mixedSections e forms generano cose da fare ma non bloccano l'uscita dalla fase.
• Con il modello vuoto, la fase 3 controlla solo handLists.
• Un layout single con condizione entire_site vale per tutti i tipi.

Stato del sito

Cosa fa: raccoglie lo stato a ogni chiamata, con poche query aggregate. Non scrive nulla nel database.

Come si usa: campo state della risposta.

Parametri: campi di state:

Permessi: come nucleo/guide.

Edizione: Free

Limiti noti:

• La lettura si ferma a 1000 documenti. Prima legge layout e sezioni, poi i documenti modificati più di recente.
• Sono esclusi i post trash, auto-draft e inherit. Le bozze contano.
• L'applicazione di header, footer e single a tutto il sito viene dalla mappa dei layout nello store. Se la cache è vuota, la guida vede queste condizioni come non soddisfatte.
• Una bozza senza slug compare con l'ID nei riferimenti (page:14#r).

Controlli sui documenti

Cosa fa: percorre l'albero di ogni documento letto e conta i segnali delle regole. Per ogni contatore conserva fino a 3 posizioni d'esempio, nella forma <ref>#<id nodo>.

Come si usa: campo state.checks. Gli esempi compaiono nelle voci di todo.

Parametri: contatori:

Permessi: come nucleo/guide.

Edizione: Free

Limiti noti:

• Struttura di un blocco per repeated: tipo e alcune impostazioni. Contano level per nc/heading, section per nc/section-ref, postType per nc/query e nc/collection, layout e tag per gli altri blocchi. Un'impostazione assente vale il default del manifest del blocco.
• Contano anche i bind a un campo del contenuto corrente, con sorgente post, nucleo, item, acf, metabox, jetengine o woo. Testi, immagini, link e stile non contano.
• nc/section-ref ed elenchi pesano 0. Un contenitore di soli riferimenti non è una ripetizione.
• I blocchi dentro nc/query, nc/collection e le liste a mano non contano in repeated.
• Un blocco si segnala se almeno una copia non sta dentro un blocco già ripetuto. Il gruppo elenca tutte le copie.
• Il to-do spiega al massimo 3 gruppi e mostra al massimo 4 copie per gruppo.
• Per mixedSections, un nc/section-ref vale come sezione se il root della sezione è nc/section. Se la sezione non è tra i documenti letti, il riferimento non conta.

Blocco diverso di proposito

Cosa fa: un nodo con "guide": {"distinct": "<motivo>"} non conta come ripetizione. I blocchi al suo interno contano ancora. La guida elenca il nodo e il motivo in state.distinct.

Come si usa: aggiungi la chiave guide al nodo nel documento. Esempio: "guide": {"distinct": "apertura della home, diversa di proposito"}.

Parametri:

Permessi: quelli della scrittura del documento.

Edizione: Free

Limiti noti: un nodo distinct rende diversi anche i suoi contenitori. state.distinct mostra al massimo 3 nodi; state.checks.distinct li conta tutti.

04Fasi

Fase 0: struttura del template

Cosa fa: spiega il modello di Nucleo. Titolo nel codice: Template structure.

Come si usa: nucleo/guide con phase: 0. Nelle altre fasi le stesse regole compaiono in forma breve in basics.

Parametri: regole:

Permessi: come nucleo/guide.

Edizione: Free

Limiti noti: ingresso solo su richiesta esplicita. Uscita testuale: conoscere i due mondi, il modello dei documenti, la sintassi dei token e i due canali. Nessuna condizione verificata. todo è sempre vuoto.

Fase 1: token e componenti

Cosa fa: porta il design in token e sezioni riutilizzabili. Titolo nel codice: Tokens and components.

Come si usa: fase corrente quando la condizione della fase 1 non è soddisfatta, oppure phase: 1.

Parametri: regole:

Cose da fare generate:

• nessun token salvato: eseguire nucleo tokens suggest <design.html>, poi tokens-set;
• tokenLiterals > 0: sostituire i valori con i token;
• repeated > 0: creare sezioni, con la spiegazione dei gruppi e le operazioni doc-patch (remove, poi insert di un nc/section-ref con lo stesso id);
• mixedSections > 0: spostare gli altri blocchi in una sezione propria.

Permessi: come nucleo/guide.

Edizione: Free

Limiti noti: uscita testuale: ogni elemento ripetuto ha una sezione; nessun valore coincide con un token. R1.3 non ha un controllo nel codice. R1.4 cita nucleo/kit-list, che è Pro: senza licenza l'ability non è registrata.

Fase 2: parti globali

Cosa fa: sposta header, footer e navigazione nei layout. Titolo nel codice: Global parts.

Come si usa: fase corrente quando la fase 1 è soddisfatta e la 2 no, oppure phase: 2.

Parametri: regole:

Cose da fare generate: layout header o footer mancante; layout presente ma senza condizione entire_site; nessun menu; globalParts > 0; pathLinks > 0.

Permessi: come nucleo/guide.

Edizione: Free

Limiti noti: uscita testuale: header, footer e menu valgono su tutto il sito; nessuna pagina ripete le parti globali. pathLinks non blocca l'uscita. R2.5 non ha un controllo nel codice.

Fase 3: contenuti veri

Cosa fa: trasforma gli elementi ripetuti in contenuti con tipo, campi e layout single. Titolo nel codice: Real content.

Come si usa: fase corrente quando le fasi 1 e 2 sono soddisfatte e la 3 no, oppure phase: 3.

Parametri: regole:

Cose da fare generate: handLists > 0; per ogni tipo senza layout single; per ogni tipo senza elementi pubblicati.

Permessi: come nucleo/guide.

Edizione: Free

Limiti noti: uscita testuale: ogni elenco del design legge contenuti veri; ogni elemento ha la sua pagina. Il codice non verifica che esista un elenco nc/query o nc/collection per ogni tipo.

Fase 4: parti dinamiche

Cosa fa: sostituisce i controlli finti con blocchi nativi o componenti. Titolo nel codice: Dynamic parts.

Come si usa: fase corrente quando le fasi da 1 a 3 sono soddisfatte, oppure phase: 4. È anche la fase restituita quando tutte le fasi sono soddisfatte.

Parametri: regole:

Cose da fare generate: inertButtons > 0; un invio di prova per ogni modulo, con il numero di moduli.

Permessi: come nucleo/guide.

Edizione: Free

Limiti noti: uscita testuale: nessun controllo finto; ogni modulo provato con un invio di test. Il codice verifica solo inertButtons. L'invio di prova non è verificabile: la voce resta in todo finché esistono moduli. next è null.

05Codici delle regole negli errori

Collegamento a errori e segnalazioni

Cosa fa: aggiunge il codice della regola della guida nel campo guide di alcune segnalazioni di qualità e di alcuni errori. Il campo rule resta l'id della regola di qualità.

Come si usa: automatico, nelle risposte di salvataggio, validazione, qualità e import.

Parametri:

Permessi: quelli dell'operazione che produce l'errore.

Edizione: Free

Limiti noti: le altre regole non hanno un collegamento. Le regole di qualità sono descritte nel motore qualità.