본문으로 건너뛰기

AI 통합

Blockstudio에는 코딩 도우미를 위한 컨텍스트 파일 두 개가 포함되어 있습니다. 기본 파일은 문서의 간결한 색인입니다. 두 번째 파일은 모든 문서와 스키마의 전체 텍스트로, 전체 자료를 한 번에 요청하려는 도구에 적합합니다.

에이전트는 색인을 읽고 필요한 문서를 찾아 엽니다. 반면 주소를 지정할 수 없는 방대한 산문을 에이전트에 전달하면 관련 여부와 관계없이 모든 내용이 로드됩니다.

색인

blockstudio-llm.txt에는 게시된 모든 문서가 탐색 순서에 따라 해당 섹션 및 하위 섹션별로 한 번씩 나열됩니다. 각 항목에는 다음이 포함됩니다:

  • route: 문서 URL.
  • file: Blockstudio 저장소의 Markdown 소스 경로.
  • 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 스키마 5개도 경로와 파일이 같은 방식으로 나열됩니다.

식별자는 산문, 인라인 코드 및 코드 예제에서 읽어옵니다. text으로 표시된 블록은 출력과 디렉터리 목록을 그대로 담으므로 건너뜁니다. 명령의 출력을 보여주는 문서가 그 명령을 소유하는 것은 아닙니다.

전체 텍스트

blockstudio-llm-full.txt에는 전체 문서와 모든 스키마가 단일 파일로 들어 있습니다. 이 파일도 계속 생성되고 게시되며 주소를 지정할 수 있지만, 에이전트에 처음 제공되는 파일은 아니며 자체 헤더에서 이를 설명합니다.

생성 방식

두 파일은 빌드 시 npm run build:llm이 scripts/build-llm.ts을 실행해 조합합니다. 스크립트는 다음 작업을 수행합니다:

  1. 게시된 모든 문서의 프런트매터를 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. blockstudio.json에서 ai/enableContextGeneration 설정을 활성화합니다:
JSON
{
  "ai": {
    "enableContextGeneration": true
  }
}
  1. 이제 your-site.com/blockstudio-llm.txt 및 your-site.com/blockstudio-llm-full.txt에서 파일을 사용할 수 있습니다.

  2. AI 도구에서 색인을 지정합니다:

    • Cursor: 프로젝트 설정에서 URL을 문서로 추가합니다.
    • Claude Code: URL을 참조하거나 파일을 다운로드해 프로젝트 컨텍스트에 추가합니다.
    • GitHub Copilot: 파일을 저장소에 포함하거나 지침에서 참조합니다.

URL 또는 텍스트 파일을 컨텍스트로 받는 도구라면 무엇이든 사용할 수 있습니다. 두 파일은 정적이며 등록된 블록이나 현재 설정과 같은 사이트별 데이터는 포함하지 않습니다.

자체 프로젝트 계약

색인은 Blockstudio을 설명합니다. 하지만 에이전트에 필요한 나머지 정보, 즉 블록과 페이지의 위치, 활성화된 기능, 분석에서 거부되는 항목은 프로젝트에 관한 것입니다. vendor/bin/blockstudio-agents은 blockstudio.json과 자체 파일을 바탕으로 이를 생성합니다. 프로젝트 계약을 참조하세요.