Интеграция с ИИ
Blockstudio поставляется с двумя файлами контекста для помощников по программированию. Первый — краткий индекс документации. Второй содержит полный текст всех документов и схем для инструментов, которым нужен весь корпус за один запрос.
Агент читает индекс, находит нужный документ и открывает его. Альтернатива — передать агенту полмегабайта неструктурированного текста, в котором ничего нельзя адресовать и загружается всё, независимо от того, имеет ли это отношение к задаче.
Индекс
blockstudio-llm.txt однократно перечисляет каждый опубликованный документ, группируя их по разделам и подразделам и сохраняя порядок навигации. Каждая запись содержит:
route: URL документации.file: путь к исходному файлу Markdown в репозитории Blockstudio.purpose: описание назначения документа в одной строке.settings: путиblockstudio.json, за которые отвечает документ.hooks: названия фильтров и действий PHP и JavaScript, за которые отвечает документ.php: функции, классы и методы, за которые отвечает документ.cli: команды, за которые отвечает документ.
## 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. Скрипт выполняет следующие действия:
- Читает frontmatter каждого опубликованного документа из коллекций
docs,guidesиregistry, чтобы получить название, маршрут и назначение. - Извлекает идентификаторы, за которые отвечает каждый документ, из его содержимого: названия хуков из вызовов фильтров и действий, пути настроек, проверенные по схеме настроек, функции и классы PHP, а также команды CLI.
- Записывает индекс в
includes/llm/blockstudio-llm.txt. - Обходит дерево документации в порядке навигации, удаляет элементы навигации Markdown, сохраняя заголовки и примеры кода, добавляет схемы JSON и записывает полный текст в
includes/llm/blockstudio-llm-full.txt.
npm run docs:check завершится с ошибкой, если опубликованного документа нет в индексе или если индекс указывает на несуществующий файл.
Как ими пользоваться
- Включите настройку
ai/enableContextGenerationвblockstudio.json:
{
"ai": {
"enableContextGeneration": true
}
}
-
Теперь файлы доступны по адресам
your-site.com/blockstudio-llm.txtиyour-site.com/blockstudio-llm-full.txt. -
Укажите индекс в настройках инструмента ИИ:
- Cursor: добавьте URL как документацию в настройках проекта.
- Claude Code: укажите URL или скачайте файл и добавьте его в контекст проекта.
- GitHub Copilot: включите файл в репозиторий или укажите его в инструкциях.
Подойдет любой инструмент, принимающий URL или текстовый файл в качестве контекста. Оба файла статичны и не содержат специфичных для сайта данных, таких как зарегистрированные блоки или текущие настройки.
Контракт вашего проекта
Индекс описывает Blockstudio. Он не описывает ваш проект — вторую часть информации, которая нужна агенту: где находятся блоки и страницы, какие функции включены и что отклонит анализ. vendor/bin/blockstudio-agents создает описание на основе blockstudio.json и ваших файлов. См. контракт проекта.