Pular para o conteúdo

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 caminhos blockstudio.json pertencentes 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.
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()

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:

  1. Lê os metadados de cabeçalho de cada documento publicado nas coleções docs, guides e registry para obter seu título, rota e finalidade.
  2. 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.
  3. Grava o índice em includes/llm/blockstudio-llm.txt.
  4. 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

  1. Ative a configuração ai/enableContextGeneration no seu blockstudio.json:
JSON
{
  "ai": {
    "enableContextGeneration": true
  }
}
  1. Os arquivos ficam disponíveis em your-site.com/blockstudio-llm.txt e your-site.com/blockstudio-llm-full.txt.

  2. 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.