Integração com IA
Blockstudio fornece dois arquivos de contexto para assistentes de programação. O primeiro é um índice compacto da documentação. O segundo contém o texto integral de cada documento e esquema, para ferramentas que precisam de todo o conteúdo em uma única solicitação.
Um agente lê o índice, encontra o documento de que precisa e o abre. A alternativa é entregar a um agente meio megabyte de texto sem distinção, em que nada pode ser endereçado e tudo é carregado, seja relevante ou não.
O índice
blockstudio-llm.txt lista cada documento publicado uma vez, agrupado pela seção e subseção a que pertence, na ordem de navegação. Cada entrada contém:
route: o URL da documentação.file: o caminho de origem Markdown no repositório Blockstudio.purpose: uma linha que descreve a finalidade do documento.settings: os caminhosblockstudio.jsonpertencentes ao documento.hooks: os nomes de filtros e ações PHP e JavaScript pertencentes ao documento.php: as funções, classes e métodos pertencentes ao documento.cli: os comandos pertencentes ao documento.
## 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()
Uma linha de identificador só é escrita quando o documento realmente contém algo desse tipo; por isso, a entrada acima não tem uma linha cli, enquanto a página de pré-renderização estática contém toda a família de comandos de pré-renderização.
As linhas de identificadores permitem consultar o índice. Um agente que procura o hook acionado antes da renderização de um bloco percorre as linhas de hooks e chega a PHP Hooks, que contém todo o vocabulário de filtros e ações. Um agente que procura a pré-renderização estática busca o mesmo termo e chega a Pré-renderização estática e Configurações, que contêm, respectivamente, os contadores e a configuração. Os cinco esquemas públicos JSON são listados da mesma forma, com suas rotas e arquivos.
Os identificadores são lidos do texto, do código em linha e dos exemplos de código. Blocos marcados com text contêm saída literal e listagens de diretórios, portanto são ignorados: um documento que exibe a saída de um comando não passa, por isso, a ser responsável por esse comando.
O texto integral
blockstudio-llm-full.txt é a documentação completa e contém todos os esquemas em um único arquivo. Ele continua sendo gerado, publicado e endereçável, mas deixa de ser o primeiro conteúdo entregue a um agente, como informa o próprio cabeçalho.
Como são criados
Os dois arquivos são montados durante a compilação por npm run build:llm, que executa scripts/build-llm.ts. O script:
- Lê os metadados de cabeçalho de cada documento publicado nas coleções
docs,guideseregistrypara obter seu título, rota e finalidade. - Extrai do próprio corpo de cada documento os identificadores que lhe pertencem: nomes de hooks de chamadas de filtros e ações, caminhos de configurações validados pelo esquema de configurações, funções e classes PHP e comandos CLI.
- Grava o índice em
includes/llm/blockstudio-llm.txt. - Percorre a árvore da documentação na ordem de navegação, remove os Markdown exclusivos da navegação, preservando títulos e exemplos de código, acrescenta os esquemas JSON e grava o texto integral em
includes/llm/blockstudio-llm-full.txt.
npm run docs:check falha quando um documento publicado não está no índice ou quando o índice aponta para um arquivo que não existe mais.
Como usá-los
- Ative a configuração
ai/enableContextGenerationno seublockstudio.json:
{
"ai": {
"enableContextGeneration": true
}
}
-
Os arquivos ficam disponíveis em
your-site.com/blockstudio-llm.txteyour-site.com/blockstudio-llm-full.txt. -
Aponte sua ferramenta de IA para o índice:
- Cursor: adicione o URL como um documento nas configurações do projeto.
- Claude Code: referencie o URL ou baixe o arquivo e adicione-o ao contexto do projeto.
- GitHub Copilot: inclua o arquivo no repositório ou referencie-o nas instruções.
Qualquer ferramenta que aceite um arquivo URL ou de texto como contexto funcionará. Os dois arquivos são estáticos e não incluem dados específicos do site, como blocos registrados ou configurações atuais.
O contrato do seu projeto
O índice descreve Blockstudio. Ele não descreve o seu projeto, que é a outra metade do que um agente precisa saber: onde ficam os blocos e as páginas, quais recursos estão ativados e o que a análise rejeitará. vendor/bin/blockstudio-agents gera essas informações a partir de blockstudio.json e dos seus próprios arquivos. Consulte o contrato do projeto.