Aller au contenu

Intégration de l’IA

Blockstudio fournit deux fichiers de contexte aux assistants de programmation. Le premier est un index concis de la documentation. Le second contient le texte intégral de chaque document et schéma, pour les outils qui souhaitent accéder à l’ensemble du corpus en une seule requête.

Un agent consulte l’index, repère le document dont il a besoin et l’ouvre. L’autre option consiste à lui fournir un demi-mégaoctet de texte sans structure, où rien ne peut être ciblé et où tout est chargé, que ce soit pertinent ou non.

L’index

blockstudio-llm.txt répertorie une fois chaque document publié, regroupé par section et sous-section, dans l’ordre de navigation. Chaque entrée contient :

  • route : l’URL de la documentation.
  • file : le chemin source Markdown dans le dépôt Blockstudio.
  • purpose : une ligne décrivant la fonction du document.
  • settings : les chemins blockstudio.json détenus par ce document.
  • hooks : les noms de filtres et d’actions PHP et JavaScript qu’il gère.
  • php : les fonctions, classes et méthodes qu’il gère.
  • cli : les commandes qu’il gère.
Text
## 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()

Une ligne d’identifiant n’apparaît que lorsque le document gère effectivement des éléments de ce type. L’entrée ci-dessus ne comporte donc pas de ligne cli, contrairement à la page sur le prérendu statique, qui gère toute la famille de commandes de prérendu.

Les lignes d’identifiants rendent l’index consultable. Un agent qui cherche le hook déclenché avant le rendu d’un bloc parcourt les lignes de hooks et arrive sur PHP Hooks, qui regroupe tout le vocabulaire des filtres et des actions. Un agent qui cherche le prérendu statique recherche le même terme et arrive sur Static Prerendering et Settings, qui regroupent respectivement les compteurs et la configuration. Les cinq schémas publics JSON sont répertoriés de la même manière, avec leur route et leur fichier.

Les identifiants sont lus dans le texte, le code en ligne et les exemples de code. Les blocs marqués text contiennent des sorties littérales et des listes de répertoires ; ils sont ignorés : un document qui affiche la sortie d’une commande ne devient pas pour autant propriétaire de cette commande.

Le texte intégral

blockstudio-llm-full.txt rassemble dans un seul fichier l’intégralité de la documentation et tous les schémas. Il reste généré, publié et consultable, mais il n’est plus transmis en premier à un agent, comme l’indique son propre en-tête.

Génération des fichiers

Les deux fichiers sont assemblés lors de la compilation par npm run build:llm, qui exécute scripts/build-llm.ts. Le script :

  1. Lit les métadonnées préliminaires de chaque document publié dans les collections docs, guides et registry pour en extraire le titre, la route et la fonction.
  2. Extrait du corps de chaque document les identifiants qu’il gère : noms de hooks issus des appels aux filtres et aux actions, chemins de réglages validés par rapport au schéma des réglages, fonctions et classes PHP, et commandes CLI.
  3. Écrit l’index dans includes/llm/blockstudio-llm.txt.
  4. Parcourt l’arborescence de la documentation dans l’ordre de navigation, supprime les éléments de navigation uniquement Markdown tout en conservant les titres et les exemples de code, ajoute les schémas JSON et écrit le texte intégral dans includes/llm/blockstudio-llm-full.txt.

npm run docs:check échoue lorsqu’un document publié manque dans l’index ou lorsque l’index pointe vers un fichier qui n’existe plus.

Utilisation

  1. Activez le réglage ai/enableContextGeneration dans votre blockstudio.json :
JSON
{
  "ai": {
    "enableContextGeneration": true
  }
}
  1. Les fichiers sont maintenant disponibles à your-site.com/blockstudio-llm.txt et à your-site.com/blockstudio-llm-full.txt.

  2. Indiquez l’index à votre outil d’IA :

    • Cursor : ajoutez URL comme documentation dans les réglages de votre projet.
    • Claude Code : référencez URL ou téléchargez le fichier et ajoutez-le au contexte de votre projet.
    • GitHub Copilot : incluez le fichier dans votre dépôt ou référencez-le dans vos instructions.

Tout outil acceptant URL ou un fichier texte comme contexte convient. Les deux fichiers sont statiques et ne contiennent pas de données propres au site, comme les blocs enregistrés ou les réglages actuels.

Le contrat propre à votre projet

L’index décrit Blockstudio. Il ne décrit pas votre projet, l’autre élément dont un agent a besoin : l’emplacement des blocs et des pages, les fonctionnalités activées et les éléments qui feront échouer l’analyse. vendor/bin/blockstudio-agents génère ces informations à partir de votre blockstudio.json et de vos propres fichiers. Consultez le contrat du projet.