# AI 블록 조립

코드를 파일로 나누는 `/modularize`와 달리, `/blocks`는 기능을 가진 블록을 선택하고 데이터 연결을 만든 뒤 실행합니다.

```text
/blocks catalog
/blocks plan examples/semiconductor/inspection.csv를 읽어 LOT별 수율을 계산하고 lot-yield-report.md로 저장해줘
/blocks show
/blocks run
```

자연어 계획은 설정한 모델을 사용합니다. AI가 `block_catalog`로 입력·출력·권한을 읽고 `block_compose`로 연결을 저장합니다. PLAN 상태에서는 블록을 실행하거나 파일을 만들지 않습니다. `/blocks run`에서 연결을 확인·승인하면 BUILD로 실행합니다. 프로젝트/데모의 PLAN 잠금은 해제할 수 없습니다. 파일 생성에는 기존 쓰기 승인과 체크포인트 정책이 별도로 적용됩니다.

실행은 모델에 한 단계씩 묻지 않고 등록된 로컬 코드로 진행합니다. 따라서 **블록 실행 자체는 LLM 호출 0회**입니다. 계획에는 모델 사용량이 발생합니다. 중간 데이터 전체는 모델 대화에 넣지 않고 메모리에서 다음 블록에 전달합니다.

## 현재 블록 13종

| 블록 | 입력 → 출력 |
| --- | --- |
| erp.parse | KRW 전표 JSON → 검증된 전표 |
| erp.balance | 전표 → 전표별 차대변 검사 결과 |
| erp.report | 검사 결과 → Markdown |
| file.read | 프로젝트 경로 → 텍스트 |
| semiconductor.parse | 텍스트 + csv/json → 검증된 검사 행 |
| semiconductor.yield | 검사 행 → LOT별 수율 |
| report.markdown | 수율 + 제목 → Markdown |
| frontend.inspect | 프로젝트 경로 → 스택 조사 텍스트 |
| design.recipe | 프레임워크 + 카탈로그 컴포넌트 ID → 코드·CSS 레시피 |
| recipe.code | 레시피 → 컴포넌트 코드 |
| recipe.css | 레시피 → CSS |
| text.join | 텍스트 2개 → 합친 텍스트 |
| file.write | 경로 + 텍스트 → 새 파일 |

반도체 보고서 예:

```text
file.read → semiconductor.parse → semiconductor.yield
                                      ↓
                                report.markdown → file.write
```

디자인 예는 `design.recipe → recipe.code/recipe.css → file.write`처럼 분기할 수 있습니다. 컴포넌트 ID는 기존 `/design list`에서 확인합니다. 레시피의 CSS import 파일명과 실제 저장 경로를 맞춰야 하며, 레시피 생성만으로 프로젝트 설치·라우팅·페이지 조립·화면 검증을 완료했다고 판단하지 않습니다.

## 키 없이 연결 실행

저장소 루트에서 OSCODE를 실행한 뒤 제공된 계획을 불러올 수 있습니다.

```text
/blocks load examples/blocks/semiconductor-report.json
/blocks show
/blocks run
```

샘플 입력은 `examples/semiconductor/inspection.csv`, 출력은 루트의 `lot-yield-report.md`입니다. 출력이 이미 존재하면 덮어쓰지 않고 실패합니다. 다시 실행하려면 새 출력 경로로 계획을 불러오세요.

## 연결 계약

```json
{
  "version": 1,
  "title": "파일 읽고 복사하기",
  "nodes": [
    {"id":"read","block":"file.read","inputs":{"path":{"value":"README.md"}}},
    {"id":"copy","block":"file.write","inputs":{"path":{"value":"README-copy.md"},"text":{"from":"read","port":"text"}}}
  ]
}
```

입력은 리터럴 `value` 또는 이전 노드의 출력 `from`/`port`입니다. 노드 순서는 의존 관계에 따라 정렬합니다. 모르는 블록, 없는 포트, 중복 ID, 형식 불일치, 순환 연결은 거절합니다. 최대 12노드·계획 24,000자·블록 출력 2 MiB입니다. 파일 읽기는 기존 도구의 512 KiB 제한을 사용합니다.

연결 계획 해시를 승인 전후 검사합니다. 파일 내용은 실행 시점에 읽으므로 계획 당시와 달라질 수 있습니다. 실행 전 입력 파일을 확인하세요. 단계 실패·취소 시 이후 노드를 실행하지 않으며, 이미 생성한 파일은 자동 삭제하지 않습니다. `/blocks show`로 상태와 실패 위치를 확인하고 `/checkpoints`, `/undo`로 필요한 변경을 검토합니다. 자동 재시도나 전체 트랜잭션 복구는 없습니다.

## 확장과 한계

새 블록은 `src/blocks.js`의 카탈로그와 실행 함수에 입력·출력·권한을 명시하고 테스트를 추가합니다. 사용자의 임의 JavaScript, 셸, 원격 플러그인을 실행하는 등록 기능은 제공하지 않습니다. 현재 UI는 콘솔 연결 목록이며 드래그 앤 드롭 캔버스는 없습니다.

형식 검사는 데이터 연결의 유효성을 확인합니다. AI가 업무에 가장 적합한 조합을 골랐다는 보장은 아닙니다. 없는 기능은 AI가 블록 이름을 지어내도 실행되지 않습니다. 반도체 시각화 전체 앱 자동 조립이나 임의 기능의 자동 블록 생성은 현재 범위 밖입니다.