From 9a780828df082d9fa2b9bbeb315a93eff0690fb0 Mon Sep 17 00:00:00 2001 From: kyeongmin Date: Tue, 24 Mar 2026 17:29:55 +0900 Subject: [PATCH] =?UTF-8?q?Add=20README.md=20=E2=80=94=20=ED=94=84?= =?UTF-8?q?=EB=A1=9C=EC=A0=9D=ED=8A=B8=20=EA=B0=9C=EC=9A=94,=20=EC=95=84?= =?UTF-8?q?=ED=82=A4=ED=85=8D=EC=B2=98,=20=EC=84=A4=EC=B9=98=20=EB=B0=A9?= =?UTF-8?q?=EB=B2=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2b6424c --- /dev/null +++ b/README.md @@ -0,0 +1,146 @@ +# Kei Design Agent + +콘텐츠를 시각적으로 구조화된 슬라이드 HTML로 변환하는 독립 에이전트. + +## 개요 + +텍스트 콘텐츠를 입력하면, AI가 내용을 분석하여 적합한 레이아웃을 결정하고, 핵심 내용을 추출하여 깔끔한 1페이지(또는 다중 페이지) 슬라이드를 생성합니다. + +## 아키텍처 + +``` +텍스트 입력 + ↓ +[1] Kei 실장 (Opus) — 콘텐츠 유형 분류 + 블록 배치 방향 + ↓ +[2] 디자인 팀장 (Sonnet) — 레이아웃 컨셉 (블록 배치 + 페이지 수) + ↓ +[3] 텍스트 편집자 (Sonnet) — 슬롯 텍스트 정리 (핵심 유지, 도메인 지식 보존) + ↓ +[4] CSS Grid 렌더러 — HTML 조립 + ↓ +미리보기 + HTML 다운로드 +``` + +### 역할 분리 + +| 역할 | 담당 | 하는 일 | 안 하는 일 | +|------|------|---------|-----------| +| Kei 실장 | Opus | 콘텐츠 분석, 유형 분류, 배치 방향 | 디자인, 텍스트 편집 | +| 디자인 팀장 | Sonnet | 레이아웃 컨셉, 페이지 수, 블록 선택 | 텍스트 정리 | +| 텍스트 편집자 | Sonnet | 슬롯별 텍스트 정리, 핵심 유지 | 레이아웃 결정 | +| 실무자 | CSS Grid | HTML/CSS 조립 | AI 판단 | + +## 블록 템플릿 (7종) + +| 블록 | 용도 | 시각 | +|------|------|------| +| `comparison` | 2단 병렬 비교 (A vs B) | 좌/우 분할, 색상 구분 | +| `card-grid` | 카드 2~4열 배열 | 상단 컬러 라인 + 제목 + 설명 | +| `relationship` | 벤 다이어그램 | 외부 원 + 내부 원 3개 | +| `process` | 단계 흐름 | 번호 원 + 연결선 | +| `quote-block` | 강조 인용 | 좌측 컬러 라인 + 배경 | +| `conclusion-bar` | 결론 한 줄 | 다크 배경 + 흰색 텍스트 | +| `comparison-table` | 다항목 비교 | 테이블 헤더 + 교대 행 | + +## 기술 스택 + +| 역할 | 도구 | +|------|------| +| 웹 서버 | FastAPI + uvicorn | +| AI | Anthropic Claude API (Opus + Sonnet) | +| 템플릿 | Jinja2 | +| 레이아웃 | CSS Grid (16:9 고정, 1280x720px) | +| 폰트 | Pretendard Variable (한국어 최적화) | +| SSE 스트리밍 | sse-starlette | + +## 설치 및 실행 + +### 사전 요구사항 + +- Python 3.10+ +- Anthropic API Key + +### 설치 + +```bash +cd design_agent +python -m venv .venv +.venv/Scripts/activate # Windows +pip install -e . +``` + +### 환경 변수 + +`.env` 파일 생성: + +```env +ANTHROPIC_API_KEY=sk-ant-... +KEI_API_URL=http://localhost:8000 +LOG_LEVEL=DEBUG +``` + +### 실행 + +```bash +# Design Agent 서버 +uvicorn src.main:app --reload --host 127.0.0.1 --port 8001 +``` + +접속: http://localhost:8001 + +### Kei API 연동 (선택) + +Kei persona 서버가 `localhost:8000`에 떠있으면 자동 연동됩니다. +없어도 Anthropic API 직접 호출로 동작합니다. + +## 디자인 원칙 + +- **여백 > 장식** — 그라데이션, 애니메이션, 그림자 금지 +- **색상 3개** — primary(#1e293b), accent(#2563eb), danger(#dc2626) +- **정보 계층** — 위→아래 (문제 제기 → 분석 → 결론) +- **1페이지 4~5파트** — 초과 시 자동 다중 페이지 +- **한국어 최적화** — `word-break: keep-all`, `line-height: 1.7` + +## 프로젝트 구조 + +``` +design_agent/ +├── CLAUDE.md # 프로젝트 규칙 +├── PLAN.md # 태스크 계획 +├── PROGRESS.md # 진행 상황 +├── pyproject.toml +├── src/ +│ ├── main.py # FastAPI 서버 +│ ├── config.py # 설정 +│ ├── pipeline.py # 4단계 파이프라인 +│ ├── kei_client.py # Opus 분류 (Kei API 또는 직접) +│ ├── design_director.py # 디자인 팀장 (레이아웃 컨셉) +│ ├── content_editor.py # 텍스트 편집자 (슬롯 채우기) +│ └── renderer.py # HTML 렌더러 +├── templates/ +│ ├── slide-base.html # 슬라이드 베이스 +│ └── blocks/ # 블록 템플릿 7종 +├── static/ +│ ├── index.html # 프론트엔드 +│ ├── tokens.css # 디자인 토큰 +│ └── base.css # 기본 스타일 +├── docs/ +│ └── RESEARCH.md # 기술 조사 +└── tests/ +``` + +## Kei Persona와의 관계 + +``` +Kei Persona (본체) — localhost:5173/8000 + ├ 대화/생성/피드백/실행 모드 + └ 독립적으로 동작 + +Design Agent (이 프로젝트) — localhost:8001 + ├ 슬라이드 생성 전용 + ├ Kei API 호출 가능 (선택) + └ 독립적으로 동작 +``` + +두 프로젝트는 완전히 독립. 코드 공유 없음. API 연동만.