C.E.L_Slide_test2/docs/PHASE2-PLAN.md

Phase 2 계획 — 파이프라인 고도화 + 검색 + 시각화 자동화

Phase 1 완료 현황 (2026-03-25)

항목	상태	수량
블록 라이브러리	✅	46개 (6 카테고리)
catalog.yaml	✅	46개 등록, when/not_for/slots/height_cost
BLOCK_SLOTS	✅	46개 동기화
_apply_defaults	✅	46개 동기화
SVG premium	✅	venn-diagram 검증 (3개 고정)
Figma 에셋	✅	스크린샷 16장, 에셋 15개+
5단계 파이프라인	✅	코드 동작 (BF-4~10 수정 완료/진행중)
Kei API 연동	✅	1단계(실장) + 3단계(편집자)
catalog→renderer 매핑	✅	mtime 캐시 (BF-10)
grid 역할 분리	✅	BF-9 (코드가 grid, Sonnet은 blocks만)

---

Phase 2 목표

파이프라인을 실제 사용 가능한 수준으로 고도화한다.

Phase 1은 "기반 구축 + 블록 라이브러리"였고, Phase 2는 "AI가 블록을 정확히 선택 + 고품질 결과물 생성"이다.

---

Phase 2-A: FAISS 블록 검색 인덱스

목적

디자인 팀장(Step B)이 콘텐츠를 보고 46개 블록 중 적합한 것을 검색으로 찾는다. 현재는 catalog.yaml 전문이 프롬프트에 들어가는데, 46개가 넘으면 토큰 낭비 + 선택 정확도 저하.

구현

1. 각 블록의 (id + visual + when + not_for)를 임베딩
2. FAISS 인덱스 구축 (46개 벡터)
3. 콘텐츠 꼭지 분석 결과를 쿼리 → 상위 5~8개 후보 반환
4. 팀장 프롬프트에 후보 블록만 포함 (전체 46개 대신)

효과

• 프롬프트 토큰 절약 (46개 전문 → 5~8개만)
• 선택 정확도 향상 (관련 블록만 보여주니까)
• 블록 100개+까지 확장 가능

파일

• src/block_search.py (신규)
• data/block_index.faiss (생성)
• src/design_director.py (catalog 전문 → 검색 결과로 교체)

의존성

• sentence-transformers 또는 Anthropic embeddings
• FAISS (faiss-cpu)

---

Phase 2-B: SVG N개 자동 배치

목적

현재 venn-diagram은 3개 원 고정. 콘텐츠에 따라 2~7개 원이 필요할 수 있음. 수학적 계산(cos/sin)으로 N개를 자동 배치한다.

구현

1. renderer.py에 SVG 좌표 계산 함수 추가
   - calc_circle_positions(n, center, radius) → [(cx, cy), ...]
   - 360/N 간격, 12시 방향부터 시계방향

2. venn-diagram.html 템플릿을 동적으로 변경
   - items[]에 사전 계산된 cx, cy가 포함
   - 원 크기도 N에 따라 자동 조정 (N=3: r=120, N=5: r=80, N=7: r=60)

3. Gemini 참고 디자인 흐름 (선택적)
   - SVG 초안 → Gemini에게 "이 구조로 고급 디자인" 요청
   - 생성 이미지의 색감/그라데이션을 참고하여 SVG tokens 업데이트
   - 최종은 항상 SVG (AI 이미지는 참고만)

파일

• src/svg_calculator.py (신규)
• templates/blocks/visuals/venn-diagram.html (동적 좌표 지원)
• src/renderer.py (SVG 계산 호출 추가)

검증 완료 사항

• 3/4/5개 수학적 계산: ✅ (Phase 1에서 테스트)
• SVG premium 디자인 (radialGradient+filter): ✅
• AI 이미지 방식 폐기: ✅ (텍스트 위치 불일치로 사용 불가)

---

Phase 2-C: 2단계 Step A 고도화 (Opus + FAISS)

목적

현재 Step A는 규칙 4줄(프리셋 4개 중 선택)인데, 원래 의도는 Opus가 FAISS로 적합한 구조/블록을 검색해서 배치와 크기까지 정하는 것.

구현

현재 (Phase 1):
  Step A: 규칙 기반 프리셋 선택 (코드)
  Step B: Sonnet이 블록 매핑

Phase 2:
  Step A: Opus + FAISS로 구조/블록 검색 + 배치/크기 결정
  Step B: Sonnet이 Step A 결과를 grid에 매칭 + 글자수 가이드

세부

1. Opus가 콘텐츠를 보고 "이 콘텐츠에는 비교형+정의형+관계도가 적합" 판단
2. FAISS에서 각 유형에 맞는 블록 후보 검색
3. 후보 중 배치/크기를 결정 (좌 65% 비교표, 우 35% 정의 카드, 하단 관계도)
4. Step B(Sonnet)에게 이 배치 구조 + 후보 블록을 전달

의존성

• Phase 2-A (FAISS 인덱스) 완료 필요
• Kei API (Opus) 안정 동작

파일

• src/design_director.py (Step A 전면 재작성)
• src/block_search.py (Phase 2-A에서 생성)

---

Phase 2-D: 5단계 재검토 강화

현재 문제

IMPROVEMENT 분석에서 발견된 문제:
  - HTML을 프롬프트에 실제 전달하지 않음 (블록 데이터 양만 전달)
  - shrink action이 no-op
  - rewrite action이 no-op
  - 조정 후 재편집이 정확하지 않음

구현

1. HTML 코드 요약을 프롬프트에 전달
   - 전체 HTML은 너무 크니까, 블록별 텍스트 길이 + 구조 요약

2. shrink action 구현
   - char_guide를 줄여서 재편집 유도

3. rewrite action 구현
   - 특정 블록의 텍스트를 완전히 재작성

4. 조정 횟수 제한
   - 무한 루프 방지: 최대 2회 재조정

파일

• src/pipeline.py (_review_balance, _apply_adjustments 개선)

---

Phase 2-E: 누락 기능 구현

E-1: Pillow 이미지 크기 읽기

콘텐츠에 이미지가 포함될 때:
  - Pillow로 원본 크기 확인
  - 가로/세로 비율에 따라 블록 선택 (image-full vs image-side-text)
  - 팀장에게 이미지 크기 정보 전달

• 파일: src/design_director.py (Step B에 이미지 정보 추가)

E-2: <details>/<summary> 완성

현재 details-block.html은 있지만 파이프라인에서 활용 안 됨:
  - 실장이 detail_target으로 판단한 꼭지를 details-block으로 연결
  - 편집자가 summary + detail 두 버전 작성
  - 인쇄 시 자동 펼침 JavaScript

• 파일: src/pipeline.py, templates/blocks/emphasis/details-block.html

E-3: 디자인 실무자 AI 조정

현재 4단계는 순수 코드(Jinja2)만.
CLAUDE.md에는 "텍스트에 맞게 폰트/여백/박스 조정"이라고 되어있음.
  - Sonnet이 렌더링된 HTML을 보고 CSS 미세 조정 제안
  - 또는 CSS 변수를 동적으로 조정하는 코드

• 파일: src/renderer.py 또는 src/pipeline.py
• 우선순위: 낮음 (다른 것이 더 급함)

---

Phase 2-F: 출력 확장 (design_agent 범위 밖)

글벗에서 처리:

• design_agent는 HTML 생성까지만 담당
• .astro 변환 → 글벗이 design_agent API 호출 후 HTML → .astro 래핑
• 글벗 연동 → 글벗 쪽에서 design_agent의 /api/generate 호출

---

작업 순서 (의존 관계)

Phase 2-A (FAISS) ─────────────────────┐
                                        ├→ Phase 2-C (Step A: Opus+FAISS)
Phase 2-B (SVG N개) ── 독립, 병렬 가능   │
                                        │
Phase 2-D (5단계 강화) ── 독립, 병렬 가능 │
                                        │
Phase 2-E (누락 기능) ── 독립, 병렬 가능  │
                                        │
Phase 2-F (출력 확장) ─── 글벗에서 처리 (design_agent 범위 밖)

추천 실행 순서

1순위: Phase 2-A (FAISS) — 블록 선택 정확도의 핵심
2순위: Phase 2-B (SVG N개) — 시각화 자동화
3순위: Phase 2-D (5단계 강화) — 결과물 품질
4순위: Phase 2-E (누락 기능) — 완성도
5순위: Phase 2-C (Step A: Opus) — Phase 2-A 완료 필요
※ Phase 2-F (출력 확장) — 글벗에서 처리, design_agent 범위 밖

---

기술 스택 추가

역할	도구	Phase
블록 검색	FAISS + sentence-transformers	2-A
SVG 계산	Python math (cos/sin)	2-B
Step A	Opus via Kei API + FAISS	2-C
이미지 크기	Pillow	2-E
.astro 출력	Jinja2 + StarlightPage 템플릿	2-F

---

성공 기준

Phase 2 완료 시:
  ✅ 텍스트 원고 입력 → 85점 슬라이드 HTML 자동 생성
  ✅ 블록 선택이 콘텐츠에 정확히 매칭 (FAISS 검색)
  ✅ 관계도/다이어그램 N개 자동 배치 (SVG)
  ✅ 재검토 루프가 실질적으로 동작
  ✅ Starlight에서 바로 볼 수 있는 .astro 출력