Перейти к содержимому

Интеграция с ИИ

Blockstudio поставляется с двумя файлами контекста для помощников по программированию. Первый — краткий индекс документации. Второй содержит полный текст всех документов и схем для инструментов, которым нужен весь корпус за один запрос.

Агент читает индекс, находит нужный документ и открывает его. Альтернатива — передать агенту полмегабайта неструктурированного текста, в котором ничего нельзя адресовать и загружается всё, независимо от того, имеет ли это отношение к задаче.

Индекс

blockstudio-llm.txt однократно перечисляет каждый опубликованный документ, группируя их по разделам и подразделам и сохраняя порядок навигации. Каждая запись содержит:

  • route: URL документации.
  • file: путь к исходному файлу Markdown в репозитории Blockstudio.
  • purpose: описание назначения документа в одной строке.
  • settings: пути blockstudio.json, за которые отвечает документ.
  • hooks: названия фильтров и действий PHP и JavaScript, за которые отвечает документ.
  • php: функции, классы и методы, за которые отвечает документ.
  • cli: команды, за которые отвечает документ.
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()

Строка с идентификаторами записывается, только если документ действительно содержит что-либо соответствующего типа. Поэтому в записи выше нет строки cli, тогда как страница статической предварительной генерации отвечает за все команды этого семейства.

Строки с идентификаторами позволяют искать сведения в индексе. Агент, которому нужен хук, срабатывающий перед рендерингом блока, просматривает строки с хуками и переходит к PHP Hooks, где собраны все фильтры и действия. Агент, которому нужна статическая предварительная генерация, ищет то же слово и находит разделы Static Prerendering и Settings, где описаны счетчики и конфигурация соответственно. Пять общедоступных схем JSON перечислены так же — с указанием маршрута и файла.

Идентификаторы извлекаются из текста, встроенного кода и примеров кода. Блоки, помеченные text, содержат буквальный вывод и списки каталогов, поэтому пропускаются: документ не становится владельцем команды лишь потому, что выводит результат ее выполнения.

Полный текст

blockstudio-llm-full.txt — это полный текст документации и всех схем в одном файле. Он по-прежнему создается автоматически, публикуется и доступен по адресу, но агентам его больше не передают в первую очередь, и это указано в его заголовке.

Как они создаются

Оба файла собираются во время сборки с помощью npm run build:llm, который запускает scripts/build-llm.ts. Скрипт выполняет следующие действия:

  1. Читает frontmatter каждого опубликованного документа из коллекций docs, guides и registry, чтобы получить название, маршрут и назначение.
  2. Извлекает идентификаторы, за которые отвечает каждый документ, из его содержимого: названия хуков из вызовов фильтров и действий, пути настроек, проверенные по схеме настроек, функции и классы PHP, а также команды CLI.
  3. Записывает индекс в includes/llm/blockstudio-llm.txt.
  4. Обходит дерево документации в порядке навигации, удаляет элементы навигации Markdown, сохраняя заголовки и примеры кода, добавляет схемы JSON и записывает полный текст в includes/llm/blockstudio-llm-full.txt.

npm run docs:check завершится с ошибкой, если опубликованного документа нет в индексе или если индекс указывает на несуществующий файл.

Как ими пользоваться

  1. Включите настройку ai/enableContextGeneration в blockstudio.json:
JSON
{
  "ai": {
    "enableContextGeneration": true
  }
}
  1. Теперь файлы доступны по адресам your-site.com/blockstudio-llm.txt и your-site.com/blockstudio-llm-full.txt.

  2. Укажите индекс в настройках инструмента ИИ:

    • Cursor: добавьте URL как документацию в настройках проекта.
    • Claude Code: укажите URL или скачайте файл и добавьте его в контекст проекта.
    • GitHub Copilot: включите файл в репозиторий или укажите его в инструкциях.

Подойдет любой инструмент, принимающий URL или текстовый файл в качестве контекста. Оба файла статичны и не содержат специфичных для сайта данных, таких как зарегистрированные блоки или текущие настройки.

Контракт вашего проекта

Индекс описывает Blockstudio. Он не описывает ваш проект — вторую часть информации, которая нужна агенту: где находятся блоки и страницы, какие функции включены и что отклонит анализ. vendor/bin/blockstudio-agents создает описание на основе blockstudio.json и ваших файлов. См. контракт проекта.