AI連携
Blockstudioはコーディングアシスタント向けに2つのコンテキストファイルを提供します。1つ目はドキュメントの簡潔なインデックスです。2つ目は、1回のリクエストで全体を取得したいツール向けに、すべてのドキュメントとスキーマの全文を収録します。
エージェントはインデックスを読み、必要なドキュメントを見つけて開きます。もう一つの方法は、参照先がなく、関連性にかかわらずすべて読み込まれる、まとまりのない膨大な文章をエージェントに渡すことです。
インデックス
blockstudio-llm.txtには、公開済みの各ドキュメントが1回ずつ、ナビゲーション順に、属するセクションとサブセクションごとにまとめて掲載されます。各項目には次の情報が含まれます。
route: ドキュメントのURL。file: Blockstudioリポジトリ内のMarkdownソースパス。purpose: ドキュメントの用途を説明する1行。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フックにたどり着きます。静的プリレンダリングを探すエージェントは同じ語句を検索し、カウンターと設定をそれぞれ管理する静的プリレンダリングと設定にたどり着きます。5つの公開JSONスキーマも、ルートとファイルを含め、同じ方法で一覧表示されます。
識別子は、本文、インラインコード、コード例から読み取られます。textとマークされたブロックには、リテラルな出力やディレクトリ一覧が含まれるため、対象外になります。コマンドの出力を掲載していても、そのドキュメントがそのコマンドを管理することにはなりません。
全文
blockstudio-llm-full.txtは、すべてのドキュメントとスキーマを1つのファイルにまとめたものです。引き続き生成、公開され、参照可能ですが、エージェントに最初に渡すファイルではなくなりました。そのことはファイル自体のヘッダーにも記載されています。
生成方法
2つのファイルは、ビルド時にnpm run build:llmによって生成されます。scripts/build-llm.tsを実行するスクリプトは、次の処理を行います。
docs、guides、registryコレクションにある公開済み各ドキュメントのフロントマターを読み取り、タイトル、ルート、用途を取得する。- 各ドキュメントの本文から、そのドキュメントが管理する識別子を抽出する。フィルターとアクションの呼び出しからフック名、設定スキーマで検証された設定パス、PHPの関数とクラス、CLIのコマンドを取得する。
- インデックスを
includes/llm/blockstudio-llm.txtに書き込む。 - ナビゲーション順にドキュメントツリーをたどり、見出しとコード例を保持したままナビゲーション専用のMarkdownを取り除き、JSONスキーマを追加して、全文を
includes/llm/blockstudio-llm-full.txtに書き込む。
公開済みのドキュメントがインデックスにない場合、またはインデックスが存在しないファイルを指している場合、npm run docs:checkは失敗します。
使用方法
blockstudio.jsonでai/enableContextGeneration設定を有効にします。
{
"ai": {
"enableContextGeneration": true
}
}
-
ファイルは
your-site.com/blockstudio-llm.txtとyour-site.com/blockstudio-llm-full.txtで利用できます。 -
AIツールにインデックスを指定します。
- Cursor: プロジェクト設定でURLをドキュメントとして追加します。
- Claude Code: URLを参照するか、ファイルをダウンロードしてプロジェクトのコンテキストに追加します。
- GitHub Copilot: ファイルをリポジトリに含めるか、指示内で参照します。
URLまたはテキストファイルをコンテキストとして受け取れるツールなら使用できます。どちらのファイルも静的で、登録済みブロックや現在の設定など、サイト固有のデータは含みません。
プロジェクト固有の契約
インデックスが説明するのはBlockstudioです。エージェントに必要なもう半分の情報、つまりブロックやページの場所、有効な機能、分析で拒否される内容は、プロジェクトについて説明しません。vendor/bin/blockstudio-agentsはblockstudio.jsonとプロジェクト内のファイルからこの情報を生成します。プロジェクト契約を参照してください。