Integrazione AI
Blockstudio include due file di contesto per gli assistenti di programmazione. Il primo è un indice compatto della documentazione. Il secondo contiene il testo completo di ogni documento e schema, per gli strumenti che vogliono l’intero corpus in un’unica richiesta.
Un agente legge l’indice, trova il documento che gli serve e lo apre. L’alternativa è passargli mezzo megabyte di testo indifferenziato, in cui nulla è consultabile e viene caricato tutto, indipendentemente dalla sua pertinenza.
L’indice
blockstudio-llm.txt elenca una volta ciascun documento pubblicato, raggruppato per sezione e sottosezione di appartenenza, nell’ordine di navigazione. Ogni voce contiene:
route: l’URL della documentazione.file: il percorso sorgente Markdown nel repository Blockstudio.purpose: una riga che descrive lo scopo del documento.settings: i percorsiblockstudio.jsondi cui il documento è responsabile.hooks: i nomi di filtri e azioni PHP e JavaScript di cui è responsabile.php: le funzioni, le classi e i metodi di cui è responsabile.cli: i comandi di cui è responsabile.
## Docs / Dev / Inspection Tools
### Canvas
route: /docs/dev/canvas
file: docs/docs/dev/canvas.md
purpose: A visual workspace and public inventory API for Blockstudio content.
settings: dev/canvas/enabled, ui
hooks: blockstudio/settings/dev/canvas/admin_bar, blockstudio/settings/dev/canvas/enabled
php: Blockstudio\Canvas, Canvas::documents(), Canvas::inventory()
Una riga identificativa viene scritta solo quando il documento è effettivamente responsabile di qualcosa di quel tipo; perciò la voce sopra non ha una riga cli, mentre la pagina di prerendering statico è responsabile dell’intera famiglia di comandi di prerendering.
Le righe identificative permettono di consultare l’indice. Un agente che cerca l’hook attivato prima del rendering di un blocco esamina le righe degli hook e arriva a PHP Hook, che contiene l’intero vocabolario di filtri e azioni. Un agente che cerca il prerendering statico cerca la stessa parola e arriva a Prerendering statico e Impostazioni, che contengono rispettivamente i contatori e la configurazione. I cinque schemi JSON pubblici sono elencati allo stesso modo, con il relativo percorso e file.
Gli identificatori vengono letti dalla prosa, dal codice in linea e dagli esempi di codice. I blocchi contrassegnati con text contengono output letterale ed elenchi di directory, quindi vengono ignorati: un documento che stampa l’output di un comando non diventa per questo responsabile di quel comando.
Il testo completo
blockstudio-llm-full.txt contiene in un unico file la documentazione completa e tutti gli schemi. Viene comunque generato, pubblicato e reso consultabile, ma non è più il primo contenuto fornito a un agente, e lo dichiara nell’intestazione.
Come vengono creati
Entrambi i file vengono assemblati in fase di build da npm run build:llm, che esegue scripts/build-llm.ts. Lo script:
- Legge il frontmatter di ogni documento pubblicato nelle raccolte
docs,guideseregistryper ricavarne titolo, percorso e scopo. - Estrae dal corpo di ogni documento gli identificatori di cui è responsabile: i nomi degli hook dalle chiamate a filtri e azioni, i percorsi delle impostazioni convalidati rispetto allo schema delle impostazioni, le funzioni e classi PHP e i comandi CLI.
- Scrive l’indice in
includes/llm/blockstudio-llm.txt. - Esamina l’albero della documentazione nell’ordine di navigazione, rimuove i Markdown riservati alla navigazione mantenendo intestazioni ed esempi di codice, aggiunge gli schemi JSON e scrive il testo completo in
includes/llm/blockstudio-llm-full.txt.
npm run docs:check genera un errore se un documento pubblicato manca dall’indice o se l’indice rimanda a un file che non esiste più.
Come usarli
- Abilitate l’impostazione
ai/enableContextGenerationnel vostroblockstudio.json:
{
"ai": {
"enableContextGeneration": true
}
}
-
Ora i file sono disponibili in
your-site.com/blockstudio-llm.txteyour-site.com/blockstudio-llm-full.txt. -
Indicate l’indice al vostro strumento AI:
- Cursor: aggiungete URL come documentazione nelle impostazioni del progetto.
- Claude Code: fate riferimento a URL oppure scaricate il file e aggiungetelo al contesto del progetto.
- GitHub Copilot: includete il file nel repository oppure fatevi riferimento nelle istruzioni.
Funziona qualsiasi strumento che accetti un file URL o di testo come contesto. Entrambi i file sono statici e non includono dati specifici del sito, come i blocchi registrati o le impostazioni correnti.
Il contratto del vostro progetto
L’indice descrive Blockstudio. Non descrive il vostro progetto, l’altra metà di ciò che serve a un agente: dove si trovano blocchi e pagine, quali funzionalità sono abilitate e quali elementi verranno rifiutati dall’analisi. vendor/bin/blockstudio-agents genera queste informazioni dal vostro blockstudio.json e dai vostri file. Consultate il contratto del progetto.