Перейти до вмісту

Інтеграція зі ШІ

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