
# 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](https://blockstudio.dev/ko/docs/blocks/hooks/php/)로 이동합니다. 정적 사전 렌더링을 찾는 에이전트는 같은 단어를 검색해 카운터를 소유한 [Static Prerendering](https://blockstudio.dev/ko/docs/production/static-prerendering/)과 구성을 소유한 [Settings](https://blockstudio.dev/ko/docs/general/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 title="blockstudio.json"
{
  "ai": {
    "enableContextGeneration": true
  }
}
```

2. 이제 `your-site.com/blockstudio-llm.txt` 및 `your-site.com/blockstudio-llm-full.txt`에서 파일을 사용할 수 있습니다.

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

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

## 자체 프로젝트 계약

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