Інтеграція зі ШІ
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 Хуки, де перелічено всі фільтри й дії. Агент, який шукає статичний попередній рендеринг, шукає те саме слово й знаходить Статичний попередній рендеринг і Налаштування, які описують відповідно лічильники та конфігурацію. П’ять публічних схем 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 і власних файлів. Див. контракт проєкту.