Kyeongmin/C.E.L._slide_test
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

Add Stage 1 docs, run-001 artifacts, and no-Kei bridge

Browse Source
This commit is contained in:
이경민
2026-04-01 16:16:49 +09:00
commit 1481a36fda
16 changed files with 1347 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
README.md Normal file
View File

@@ -0,0 +1,13 @@
# C.E.L._slide_test
이 저장소는 `design_agent`의 문서화, `Kei API` 비의존 실행 경로 실험, run 단위 산출물 정리를 위한 작업 공간이다.
## 구성
- `docs/`: 방향성 문서, Stage 1 문서, run-001 기록
- `scripts/`: `Kei API` 없이 후반부 실행을 시도하는 브리지 스크립트
- `issues/`: Gitea 이슈에 올릴 초안 문서
## 현재 포함된 항목
- Stage 1 이해 및 문서화 자료
- run-001 해석/구조화/계획/검증 기록
- `run_from_artifacts.py` 브리지 스크립트

17
docs/Folder-Layout.md Normal file
View File

@@ -0,0 +1,17 @@
# Folder Layout
이 폴더는 `design_agent`를 위키, 이슈, 실행 산출물로 분리해 정리하는 작업 공간이다.
## 구조
- `wiki/`: 기준 문서와 절차 문서
- `issues/`: 작업 이슈 초안, 템플릿, 기록 초안
- `runs/`: 실제 수행 결과와 중간 산출물
## 기본 원칙
- 위키는 고정 기준서다.
- 이슈는 작업별 기록이다.
- runs는 실제 산출물 저장소다.
## run 폴더 규칙
각 작업은 `run-001`, `run-002`처럼 별도 폴더를 만든다.
각 run 안에는 step별 하위 폴더를 둔다.

261
docs/codex.md Normal file
View File

@@ -0,0 +1,261 @@
# codex.md
## 목적
이 문서는 `design_agent`를 현재 구현 상태에서 바로 뜯어고치는 대신, 먼저 작업 절차와 판단 기준을 `design_agnet_codex`의 위키/이슈 체계로 외부화한 뒤, 이를 기반으로 `Kei API` 의존을 제거하는 방향과 실행 계획을 정리한 기준 문서다.
핵심 목표는 다음과 같다.
- `design_agent`의 현재 프로세스를 위키와 이슈 체계로 정리한다.
- `Kei API`가 담당하던 사고 단계를 문서 기반/에이전트 기반 단계로 치환한다.
- 후반부의 계산, 생성, 검증, 렌더링은 기존 코드 자산을 최대한 활용한다.
- 최종적으로 `Kei API` 없이도 `design_agent`가 운영 가능하도록 구조를 옮긴다.
## 현재 인식
현재 `design_agent`는 다음과 같은 구조를 가진다.
- 일부 초기 판단 단계에서 `Kei API`를 호출한다.
- 이후 단계에서는 공간 계산, HTML 생성, 검증, 렌더링, 측정, 품질 게이트를 코드로 수행한다.
- 즉, 전체 시스템이 전부 `Kei API`에 의존하는 것은 아니고, 초반의 해석/구조화 단계가 특히 의존적이다.
문제가 되는 핵심 의존 구간은 다음과 같다.
- topic extraction
- concept refinement
- relation_type 정리
- expression_hint 정리
- source_data 보강
이 부분은 현재 `Kei API`가 맡고 있지만, 앞으로는 위키와 이슈를 기반으로 Codex 또는 Claude Code가 수행하도록 전환해야 한다.
## 기본 방향
앞으로의 구조는 아래처럼 바뀌어야 한다.
기존 구조:
- `design_agent code -> kei_client.py -> Kei API -> 결과 수신 -> 후속 코드 실행`
목표 구조:
- `위키 1/2/3 -> 이슈에서 현재 작업 정리 -> Codex/Claude가 초기 해석 수행 -> 구조화 산출물 생성 -> design_agent 코드가 후반부 실행`
즉, `Kei API`가 하던 사고 단계는 위키+이슈+에이전트가 맡고, 계산과 생성과 검증은 코드가 맡는 구조로 바꾼다.
## 역할 분리
### 위키
위키는 다음을 정의한다.
- 무엇을 해야 하는가
- 어떤 순서로 해야 하는가
- 어떤 기준으로 판단하는가
- 각 단계의 입력, 출력, 검증 조건은 무엇인가
즉, 위키는 실행 기준서다.
### 이슈
이슈는 다음을 기록한다.
- 이번 작업의 실제 입력
- Kei 기준 해석 결과
- 구조화 결과
- 단계별 진행 기록
- 검증 결과
- 남은 문제와 다음 액션
즉, 이슈는 실행 기록이자 작업 메모리다.
### 코드
코드는 다음을 수행한다.
- 공간 계산
- 디자인 budget 계산
- HTML 생성
- 콘텐츠 검증
- 렌더링
- 높이 측정
- 품질 게이트
즉, 코드는 실행기다.
## 위키 체계
현재 `design_agnet_codex`에는 다음 구조를 두는 방향으로 정리한다.
### 위키 1 계열
Kei의 판단 기준
- Kei 사고방식과 프로세스
- Kei 역할과 운영 원칙
### 위키 2 계열
design_agent 상위 작업 절차
- 입력 확인
- Kei 기준 해석
- 콘텐츠 구조화
- 실행 계획 수립
- 실제 수행
- 검증 및 기록
### 위키 3 계열
design_agent 상세 파이프라인
- Stage 0 입력 로드 및 MDX 정규화
- Stage 1A topic extraction
- Stage 1B concept refinement
- Stage 1.5a 폰트 위계와 비율 계획
- Stage 1.7 참조 블록 선정
- Stage 1.5b 디자인 버짓 재계산
- Stage 2 HTML 생성
- Stage 2 검증 및 재시도
- Stage 3 렌더와 측정
- Stage 4 품질 게이트와 최종화
## 가장 중요한 전환 원칙
위키를 만든다고 자동으로 `Kei API`가 사라지는 것은 아니다.
진짜 전환은 아래 조건이 충족될 때 일어난다.
- Stage 1A와 Stage 1B를 `Kei API 호출 단계`가 아니라 `위키/이슈 기반 해석 단계`로 재정의한다.
- Codex 또는 Claude Code가 위키를 읽고 topic/concept/expression_hint/source_data를 직접 정리한다.
- 이 결과를 코드가 읽을 수 있는 중간 산출물로 남긴다.
- 이후 후반부 파이프라인은 기존 코드가 그대로 또는 최소 수정으로 수행한다.
즉, 핵심은 `Kei API 제거`가 아니라 `Kei 사고 단계를 외부화`하는 것이다.
## 단계별 실행 계획
### 1단계. 현재 design_agent 문서화
목적:
현재 `design_agent`가 어떤 순서로 동작하는지, 어떤 단계가 코드에 있고 어떤 단계가 `Kei API`에 의존하는지 문서로 고정한다.
할 일:
- 위키 2와 위키 3을 현재 구조 기준으로 정리한다.
- 각 stage의 입력/출력/검증 기준을 문서화한다.
- `Phase T` 기준 변경점도 함께 반영한다.
### 2단계. 위키/이슈 기반 작업 체계 완성
목적:
Codex/Claude가 `Kei persona 프롬프트` 대신 위키와 이슈를 읽고 움직이도록 만든다.
할 일:
- 위키 1 계열 완성
- 위키 2 계열 완성
- 위키 3 계열 완성
- 이슈 템플릿 작성
이 단계가 끝나면 작업 방식은 다음과 같아야 한다.
- 위키 2를 기준으로 현재 작업 step을 정한다.
- 판단은 위키 1을 기준으로 한다.
- 상세 실행은 위키 3을 따른다.
- 중간 결과와 최종 결과는 이슈에 남긴다.
### 3단계. Kei API 역할 외부화
목적:
초기 판단 단계가 더 이상 API 호출을 기본 전제로 하지 않게 만든다.
할 일:
- Stage 1A를 `위키 기반 topic extraction`으로 재정의한다.
- Stage 1B를 `위키 기반 concept refinement`로 재정의한다.
- relation_type, expression_hint, source_data를 사람이 읽고 검토 가능한 형태로 정리한다.
- 이를 이슈 또는 별도 산출물 파일에 저장한다.
### 4단계. 중간 산출물 포맷 정의
목적:
에이전트가 정리한 초기 해석 결과를 코드가 받아 쓸 수 있게 만든다.
예상 산출물 예시:
- `topics.json`
- `refined_concepts.json`
- `design_context.json`
- 또는 단계별 markdown 기록
이 단계에서 중요한 것은 파일 형식보다도 아래 항목이 안정적으로 남는 것이다.
- 핵심 topic
- refined concept
- relation 정보
- expression hint
- source data
- 검증 기준
### 5단계. 코드 경로 전환
목적:
`design_agent`가 기본적으로 `Kei API`를 호출하지 않도록 흐름을 바꾼다.
할 일:
- `kei_client` 호출을 기본 경로에서 제거하거나 optional fallback으로 내린다.
- Stage 1A/1B 입력을 API 응답이 아니라 중간 산출물로 바꾼다.
- 후반부 파이프라인은 최대한 기존 코드 자산을 유지한다.
원칙:
- 계산, 생성, 검증 로직은 함부로 다시 쓰지 않는다.
- 먼저 입력 경로만 바꾼다.
- 코드 변경은 작고 명확하게 진행한다.
### 6단계. 운영 방식 정착
목적:
실제 작업이 `위키 -> 이슈 -> 코드 실행` 흐름으로 안정적으로 반복되게 만든다.
운영 흐름:
1. 작업 이슈 생성
2. 위키 2의 현재 step 확인
3. 위키 1 기준으로 해석
4. 위키 3 기준으로 상세 실행 계획 수립
5. 초기 해석 결과 작성
6. 코드 실행
7. 검증 결과 기록
8. 필요한 단계만 재시도
## Phase T 반영 원칙
현재는 `Phase T` 진행 중이므로, 위키 2와 위키 3은 단순히 기존 구현 복제가 아니라 `Phase T 목표 구조`를 반영해야 한다.
특히 반드시 반영해야 할 항목은 다음과 같다.
- Stage 0 MDX normalization
- Stage 1A / 1B 분리
- Stage 1.5a / 1.7 / 1.5b 분리
- font hierarchy first
- PipelineContext 기반 사고
- 단계별 validation
- partial retry
- quality gate
즉, 위키는 현재 코드 설명서이면서 동시에 `Phase T 전환 가이드`여야 한다.
## 코드와 문서의 관계
문서는 코드를 대체하지 않는다.
문서는 코드가 어떤 역할을 해야 하는지 지시한다.
예시:
- 위키: `MDX 정규화의 목적, 입력, 출력, 검증 기준 정의`
- 코드: 실제 정규화 수행
- 위키: `topic extraction에서 무엇을 뽑아야 하는지 정의`
- 에이전트 또는 코드: 실제 추출 수행
- 위키: `HTML 생성의 원칙과 실패 기준 정의`
- 코드: 실제 HTML 생성 수행
즉:
- 위키는 기준
- 이슈는 기록
- 코드는 실행
## 당장 해야 할 일
우선순위는 다음과 같다.
1. `design_agnet_codex`의 위키 문서명을 Gitea 형식에 맞게 정리한다.
2. 위키 3의 Stage 1A/1B 내용을 `Kei API 호출형`이 아니라 `위키/이슈 기반 해석형`으로 수정한다.
3. `이슈 템플릿` 문서를 만든다.
4. `Kei API`가 하던 초기 판단 산출물 포맷을 정의한다.
5. 그 다음에야 실제 코드 경로를 전환한다.
## 기준 문장
앞으로 Codex 또는 Claude Code에게는 아래와 같은 운영 문장을 사용한다.
`현재 작업은 위키 2의 상위 작업 절차를 기준으로 진행한다. 판단 기준이 필요하면 위키 1 계열을 참조한다. 상세 실행과 검증은 위키 3 계열을 따른다. 초기 해석 결과와 중간 결과와 최종 결과는 이슈에 기록한다. 가능하면 Kei API를 호출하지 않고 위키와 이슈를 기반으로 Stage 1A와 Stage 1B를 수행한다.`
## 결론
이번 작업의 핵심은 단순히 `Kei API를 끄는 것`이 아니다.
진짜 목표는 `Kei의 사고 단계를 API 안에 가두지 않고, 위키와 이슈와 에이전트 실행 흐름으로 꺼내는 것`이다.
이 전환이 완료되면 `design_agent`는 다음과 같은 구조를 갖게 된다.
- 사고 기준은 위키에 있고
- 작업 기억은 이슈에 있고
- 계산과 생성은 코드가 수행하며
- `Kei API`는 필수가 아니라 선택적 fallback이 된다.

33
docs/run-001/01-input/input-review.md Normal file
View File

@@ -0,0 +1,33 @@
# Input Review Result
## Source
- input file: `01. 건설산업 DX의 올바른 이해(0127).mdx`
- source path: `D:\ad-hoc\kei\design_agnet_codex\runs\run-001\01-input\01. 건설산업 DX의 올바른 이해(0127).mdx`
## Request Understanding
- 주제: 건설산업에서 DX와 BIM의 개념적 혼용 문제를 바로잡고, DX의 올바른 의미와 BIM의 위치를 설명하는 콘텐츠
- 예상 산출 방향: 1장 슬라이드 또는 구조화된 설명 자료의 입력 원문
- 문서 성격: 개념 정리 + 용어 정의 + 관계 설명 + 핵심 요약
## Scope
- 건설산업, BIM, DX의 정의를 분리해 설명한다.
- DX와 BIM의 상호관계를 정리한다.
- `BIM은 DX의 일부`라는 결론을 명확히 전달한다.
## Constraints
- 원문 의미를 축약하더라도 왜곡하면 안 된다.
- DX를 단순 기술 도입으로 축소하면 안 된다.
- BIM을 DX와 동격 개념으로 다루면 안 된다.
- 문서 안의 비교 구조와 핵심 요약은 보존 가치가 높다.
## Must-Preserve Elements
- 용어 혼용 문제 제기
- 건설산업 정의
- BIM 정의: 핵심 기술, 정보 관리 도구
- DX 정의: 산업 패러다임 변화, 상위 개념
- DX는 BIM 등 디지털 기술 기반의 상위 개념이라는 관계
- 핵심 요약: `BIM은 건설산업의 디지털전환(DX)을 수행하는 과정에서 가장 기초가 되는 일부분`
## Confirm Needed
- 이미지(`DX1.png`)를 실제 결과물에 반영할지 여부는 후속 단계에서 결정 필요
- 세부 비교표는 본문 핵심으로 둘지, 보조 정보로 내릴지 후속 구조화 필요

60
docs/run-001/02-kei-interpretation/kei-interpretation.md Normal file
View File

@@ -0,0 +1,60 @@
# Kei Interpretation Result
## Core Purpose
이 작업의 핵심 목적은 건설산업에서 DX와 BIM이 혼용되는 문제를 바로잡고, DX가 산업 전반의 전환을 뜻하는 상위 개념이며 BIM은 그 전환을 구성하는 핵심 기술 중 하나라는 점을 명확히 이해시키는 것이다.
## Meaning Preservation Criteria
- DX는 단순 소프트웨어 도입이나 3D 모델링 도입으로 축소되면 안 된다.
- BIM은 중요한 기술이지만 DX 전체와 동일시되면 안 된다.
- 문서의 메시지는 `정의 -> 관계 -> 결론` 흐름으로 보존되어야 한다.
- 비교표와 사례는 핵심 메시지를 보조하는 근거로 다뤄야 한다.
## Core Topics
- 건설산업 DX와 BIM의 용어 혼용 문제
- 건설산업의 정의와 목표
- BIM의 정의와 역할
- DX의 정의와 역할
- DX와 BIM, GIS, 디지털 트윈의 상호관계
- BIM은 DX의 일부라는 핵심 결론
## Topic Relations
- `용어 혼용 문제` -> `정의 정립 필요성`을 유발함
- `건설산업 정의`는 DX 적용 대상과 목적을 설명하는 배경임
- `BIM 정의`와 `DX 정의`는 비교 대상이 아니라 계층 관계를 밝히는 재료임
- `DX와 핵심기술의 상호관계`는 DX가 상위 개념임을 시각적으로 뒷받침함
- `핵심 요약`은 전체 메시지의 결론임
## Core vs Support
### Core
- DX는 산업 패러다임 변화이며 상위 개념이다.
- BIM은 건설산업 DX를 위한 핵심 기술이지만 DX 자체는 아니다.
- 건설산업 DX를 올바르게 이해하려면 용어 정의와 상호관계 정립이 필요하다.
### Support
- 정책 문서에서의 혼용 사례
- 건설산업의 일반 정의와 목표
- GIS와 디지털 트윈의 보조적 역할
- DX와 BIM 비교표의 세부 행들
## Expression Hints
- 표현은 `오해 바로잡기`와 `개념 계층 설명` 중심이 적절하다.
- DX를 크게, BIM을 그 하위 핵심 기술로 보이게 해야 한다.
- 비교표 전체를 다 펼치기보다 핵심 차이 몇 개만 요약하는 편이 전달력이 좋다.
- `BIM ≠ DX`, `BIM ⊂ DX` 관계가 시각적으로 드러나야 한다.
## Source Data Candidates
- 스마트 건설 활성화 방안(2022.07)
- 제7차 건설기술진흥 기본계획(2023.12)
- 건설산업 BIM 기본지침, 국토교통부, 2020
- IBM Institute for Business Value, 2011
- Agile Elephant, 2015
## Risks
- DX를 기술 리스트처럼 보이게 만들 위험
- BIM의 중요성을 약화시키거나 반대로 과대평가할 위험
- 비교표 세부가 너무 많아 핵심 메시지가 묻힐 위험
## Stage 1A/1B Memo
- topic extraction에서는 `혼용 문제`, `정의`, `상호관계`, `핵심 결론` 4축이 유지되어야 한다.
- concept refinement에서는 `정의 비교`보다 `계층 관계 설명`이 전면에 와야 한다.
- 핵심 산출물은 `DX는 상위, BIM은 핵심 기술`이라는 한 문장으로 수렴되어야 한다.

44
docs/run-001/03-structure/content-structure.md Normal file
View File

@@ -0,0 +1,44 @@
# Content Structure Result
## Primary Message
건설산업에서 DX와 BIM은 동일 개념이 아니며, DX는 산업 전반의 전환을 뜻하는 상위 개념이고 BIM은 그 전환을 가능하게 하는 핵심 기술 중 하나다.
## Supporting Messages
- 정책 및 현장 문서에서 DX와 BIM이 혼용되어 왔다.
- 건설산업 DX를 올바르게 이해하려면 용어 정의와 관계 정리가 필요하다.
- BIM은 정보 관리와 디지털 협업을 위한 핵심 인프라 기술이다.
- DX는 BIM, GIS, 디지털 트윈 등 기술 융합을 통해 실현된다.
## Proposed Section Structure
1. 문제 제기: DX와 BIM의 혼용
2. 핵심 정의: 건설산업 / BIM / DX
3. 관계 설명: DX는 상위, BIM은 핵심 기술
4. 결론: BIM은 DX의 기초적 일부
## Priority
### Highest Priority
- DX와 BIM의 관계를 오해 없이 한눈에 설명하는 것
- `BIM은 DX의 일부`라는 결론을 선명하게 전달하는 것
### Medium Priority
- 정책 문서 혼용 사례 제시
- DX 구현에 필요한 기술 융합 설명
### Lower Priority
- DX와 BIM 비교표의 세부 항목 전부
- 건설산업 일반 정의의 상세 수식어
## Area Assumptions
- body: DX와 BIM의 관계 및 핵심 정의
- sidebar: 혼용 사례, 핵심 비교 포인트, 보조 출처
- footer: 최종 한 줄 요약 또는 출처 요약
## Compression Guidance
- 비교표는 전체를 그대로 쓰기보다 `범위`, `프로세스`, `성과품`, `확장성` 정도만 핵심 차이로 요약하는 편이 좋다.
- 건설산업 정의는 길게 풀기보다 `종합산업`, `품질/기간/비용/안전` 키워드 중심 압축이 적절하다.
- 핵심 이미지가 들어간다면 `DX 상위 - BIM/GIS/디지털트윈 하위` 구조를 강화하는 방향이 맞다.
## Next Stage Handoff
- Stage 1.5a에서는 `DX`를 가장 큰 타이포그래피 초점으로 둘 수 있다.
- Stage 1.7에서는 계층 관계를 잘 보여주는 reference block이 적합하다.
- Stage 2 생성에서는 결론이 본문 하단에 묻히지 않도록 구조적 강조가 필요하다.

24
docs/run-001/04-plan/artifact-bridge-notes.md Normal file
View File

@@ -0,0 +1,24 @@
# Artifact Bridge Notes
## 목적
이 파일들은 `Kei API` 없이도 기존 `design_agent`의 후반부 코드를 사용할 수 있도록 만든 입력 산출물이다.
## 파일
- `stage-1a-topics.json`: Stage 1A 수동 대체 결과
- `stage-1b-refined-concepts.json`: Stage 1B 수동 대체 결과
- `D:\ad-hoc\kei\design_agent\scripts\run_from_artifacts.py`: run 산출물을 읽어 Stage 1.5a 이후를 실행하는 브리지 스크립트
## 실행 예시
```powershell
cd D:\ad-hoc\kei\design_agent
python scripts\run_from_artifacts.py `
--input "D:\ad-hoc\kei\design_agnet_codex\runs\run-001\01-input\01. 건설산업 DX의 올바른 이해(0127).mdx" `
--stage1a "D:\ad-hoc\kei\design_agnet_codex\runs\run-001\04-plan\stage-1a-topics.json" `
--stage1b "D:\ad-hoc\kei\design_agnet_codex\runs\run-001\04-plan\stage-1b-refined-concepts.json" `
--output-dir "D:\ad-hoc\kei\design_agnet_codex\runs\run-001\05-execution"
```
## 주의
- 이 경로는 `Kei API`를 사용하지 않는다.
- 다만 Stage 2의 Claude/Anthropic 호출과 로컬 렌더링 환경은 필요하다.
- 품질 게이트는 Kei vision 대신 `measurement + screenshot`만 수행하는 lite 경로다.

100
docs/run-001/04-plan/execution-plan.md Normal file
View File

@@ -0,0 +1,100 @@
# Execution Plan
## Run
- run id: `run-001`
- input: `01. 건설산업 DX의 올바른 이해(0127).mdx`
- planning basis: `Wiki-2-4` and `Wiki-3` series
## Planning Summary
이번 작업은 `DX와 BIM의 관계를 오해 없이 설명하는 1장 슬라이드`를 목표로 한다.
실행은 `Phase T` 상세 파이프라인을 기준으로 하되, 초기 해석 단계는 이미 run 폴더에 기록된 문서 기반 결과를 우선 사용하고, 후반부의 계산/생성/검증/렌더는 기존 `design_agent` 코드 자산을 활용하는 방식으로 계획한다.
## Stage Plan
### Stage 0 입력 로드 및 MDX 정규화
- 목표: 원문 MDX를 후속 stage가 다루기 쉬운 형태로 정리한다.
- 입력: `01-input/01. 건설산업 DX의 올바른 이해(0127).mdx`
- 산출물: 정규화된 본문 또는 정규화 메모
- 검증: 핵심 섹션 `문제 제기`, `용어 정의`, `상호관계`, `핵심 요약`이 유지되어야 한다.
- 비고: 필요 시 현재 `html_generator.py`의 정규화 방향을 참고한다.
### Stage 1A Topic Extraction
- 목표: 주요 topic과 relation_type 초안을 명확히 한다.
- 입력: 원문 MDX + `02-kei-interpretation/kei-interpretation.md`
- 산출물: topic 목록, relation, expression_hint 초안, source_data 초안
- 검증: `혼용 문제`, `정의`, `상호관계`, `핵심 결론` 4축이 유지되어야 한다.
- 운영 원칙: `Kei API`는 호출하지 않고 문서 기반으로 수행한다.
### Stage 1B Concept Refinement
- 목표: topic 결과를 slide 생성에 적합한 개념 단위로 정제한다.
- 입력: Stage 1A 결과 + `03-structure/content-structure.md`
- 산출물: refined concepts, core/support 구분, expression_hint 보강
- 검증: `DX는 상위`, `BIM은 핵심 기술` 메시지가 최종 중심으로 남아야 한다.
### Stage 1.5a 폰트 위계와 비율 계획
- 목표: DX를 최상위 메시지로 두는 타이포그래피 위계와 body/sidebar 비율을 계획한다.
- 입력: refined concept, 구조화 결과
- 산출물: 타이포 위계 계획, body/sidebar 비율 가정
- 검증: 결론이 본문 하단에 묻히지 않아야 한다.
### Stage 1.7 참조 블록 선정
- 목표: 계층 관계와 오해 바로잡기 메시지를 잘 드러낼 reference block 방향을 정한다.
- 입력: expression_hint, 구조화 결과, block catalog
- 산출물: 추천 블록 또는 레이아웃 방향 메모
- 검증: `BIM ⊂ DX` 관계를 한눈에 보여줄 수 있어야 한다.
### Stage 1.5b 디자인 버짓 재계산
- 목표: 핵심 메시지 강조 구조에 맞게 영역별 budget을 계산한다.
- 입력: 위계 계획, 비율 계획, reference block 가정
- 산출물: container specs, text budget, height budget
- 검증: 본문에 핵심 관계 설명이 충분히 들어가고, sidebar는 근거/비교 보조 정보 중심이어야 한다.
### Stage 2 HTML 생성
- 목표: 1장 slide HTML을 생성한다.
- 입력: refined concepts, budget, reference block 방향
- 산출물: slide HTML, body/sidebar/footer fragment
- 검증: 핵심 관계 문장이 가장 먼저 읽혀야 하며, 비교표는 요약형이 적절하다.
### Stage 2 검증 및 재시도
- 목표: 의미 보존과 구조 적합성을 확인하고 실패 영역만 수정한다.
- 입력: 생성된 HTML, 원문, interpretation 결과
- 산출물: 검증 결과, 실패 영역 목록, 재시도 결과
- 검증: DX 축소 해석 금지, BIM 과대/과소평가 금지, 결론 누락 금지
### Stage 3 렌더와 측정
- 목표: 실제 화면에서 overflow와 균형을 측정한다.
- 입력: 검증 통과 HTML
- 산출물: 렌더 결과, 측정값, overflow 경고
- 검증: 핵심 메시지와 관계 설명이 과밀하지 않게 보여야 한다.
### Stage 4 품질 게이트와 최종화
- 목표: 1장 슬라이드가 `오해 바로잡기 + 개념 계층 설명`을 성공적으로 전달하는지 최종 판단한다.
- 입력: 렌더 결과, 측정값, 시각 검토 결과
- 산출물: 최종 결과물, 최종 판정, 남은 수정 포인트
- 검증: 첫 시선에 `DX는 상위`, `BIM은 핵심 기술` 관계가 읽혀야 한다.
## Validation Points
- 원문 메시지의 중심이 `정의 비교`가 아니라 `계층 관계 설명`으로 유지되는가
- 비교표 세부가 본문을 압도하지 않는가
- 혼용 사례는 문제 제기 역할만 하고 핵심 메시지를 가리지 않는가
- 핵심 결론 문장이 시각적으로 충분히 강조되는가
- 이미지 사용 시 `DX 상위 구조`를 강화하는가
## Retry Rules
- Stage 1A/1B 실패 시: interpretation과 structure 문서를 먼저 보강한 뒤 재수행
- Stage 1.5a/1.5b 실패 시: 정보량과 비율을 먼저 조정
- Stage 2 실패 시: 전체 재생성보다 실패 영역 부분 재생성을 우선
- Stage 3 실패 시: overflow 영역 중심으로 budget 또는 HTML 구조 수정
- Stage 4 실패 시: 시각 강조 구조와 핵심 결론 위치를 우선 수정
## Fallback Path
- 기본 경로는 `문서 기반 해석 -> run 산출물 -> 코드 기반 후반부 실행`
- `Kei API`는 기본 경로에서 제외한다.
- 후반부 코드 자산을 그대로 쓰기 어렵다면, 우선 수동/에이전트 기반 산출물로 Stage 1A/1B만 대체하고 이후 파이프라인은 최소 수정으로 연결한다.
## Ready-for-Next Step
다음 단계에서는 아래 항목을 실제 파일로 추가하면 좋다.
- `04-plan/stage-1a-topics.md`
- `04-plan/stage-1b-refined-concepts.md`
- `04-plan/design-budget-notes.md`
- `04-plan/reference-block-notes.md`

75
docs/run-001/04-plan/stage-1a-topics.json Normal file
View File

@@ -0,0 +1,75 @@
{
"analysis": {
"title": "건설산업 DX의 올바른 이해",
"core_message": "건설산업에서 DX는 상위 개념이고 BIM은 그 디지털 전환을 가능하게 하는 핵심 기술 중 하나다.",
"total_pages": 1
},
"page_structure": {
"배경": {"topic_ids": [1], "weight": 0.14},
"본심": {"topic_ids": [2, 3], "weight": 0.58},
"첨부": {"topic_ids": [4, 5], "weight": 0.18},
"결론": {"topic_ids": [6], "weight": 0.10}
},
"topics": [
{
"id": 1,
"title": "DX와 BIM의 혼용 문제",
"purpose": "문제제기",
"role": "flow",
"layer": "intro",
"source_hint": "용어의 혼용",
"summary": "건설산업 디지털 전환 논의에서 DX와 BIM이 혼용되어 BIM 도입을 DX 완성으로 오인하는 문제가 발생하고 있다.",
"source_data": "건설산업의 디지털 전환 논의에서 DX(Digital Transformation)와 BIM(Building Information Modeling)이 개념적으로 명확히 정립되지 않은채 혼용되어 사용되고 있음. 이로인해 BIM기술의 도입을 DX의 완성으로 오인하거나, DX를 BIM 기술 도입 수준으로 한정하는 인식 확산. 건설산업의 DX를 올바르게 이해하기 위해 각 용어의 정의, 역할, 상호관계에 대한 체계적 정립 필요"
},
{
"id": 2,
"title": "DX의 정의와 위치",
"purpose": "핵심전달",
"role": "flow",
"layer": "core",
"source_hint": "용어 정의",
"summary": "DX는 디지털 기술 기반으로 산업 전반의 업무방식과 가치 창출 구조를 전환하는 상위 개념이다.",
"source_data": "DX(Digital Transformation): 디지털 기술을 기반으로 산업 전반의 업무방식과 가치 창출 구조를 전환하는 과정 및 결과. 단순한 기술 도입이 아닌, 고객 가치와 의사결정 방식의 근본적인 변화로 산업의 새로운 방향을 정립하는 것을 의미함"
},
{
"id": 3,
"title": "BIM과 핵심기술의 관계",
"purpose": "구조시각화",
"role": "flow",
"layer": "core",
"source_hint": "용어간 상호관계",
"summary": "BIM은 DX를 가능하게 하는 핵심 기술이며, GIS·디지털 트윈과 함께 DX 구현을 구성한다.",
"source_data": "BIM(Building Information Modeling): 시설물의 생애주기동안 발생한 모든 정보를 3차원 모델 기반으로 통합·관리하는 정보 관리 도구. 건설 정보와 절차를 표준화된 방식으로 연계하고 디지털 협업이 가능하도록 하는 핵심 인프라 기술. DX는 BIM과 같은 디지털기술을 기반으로 산업 전반의 프로세스를 혁신하는 상위개념. 건설산업의 DX는 GIS(공간정보), BIM, 디지털 트윈(가상환경)의 기술융합을 통해서만 실현 또는 구현 가능. GIS의 역할 : 지리적 데이터를 공간 분석하여 시각적으로 표현, 위치기반 정보 제공. BIM의 역할 : 형상정보와 내용정보가 포함된 3D모델로, 건설 정보 기반의 Process와 Product를 제공. [이미지: DX와 핵심기술간 상호관계, 경로: /assets/images/DX1.png]"
},
{
"id": 4,
"title": "정책 혼용 사례",
"purpose": "근거사례",
"role": "reference",
"layer": "supporting",
"source_hint": "혼용 대표 사례",
"summary": "정책 문서에서 DX와 BIM을 혼용한 대표 사례를 보조 근거로 제시한다.",
"source_data": "스마트 건설 활성화 방안(2022.07): 추진과제는 건설산업 디지털화, 실행과제는 BIM 전면 도입과 BIM 전문인력 양성. 제7차 건설기술진흥 기본계획(2023.12): 추진방향은 디지털 전환을 통한 스마트 건설 확산, 추진과제는 BIM 도입으로 건설산업 디지털화"
},
{
"id": 5,
"title": "DX와 BIM 비교 핵심 포인트",
"purpose": "용어정의",
"role": "reference",
"layer": "supporting",
"source_hint": "DX와 BIM의 구분",
"summary": "비교표 전체가 아니라 DX와 BIM의 차이를 이해시키는 핵심 비교 포인트만 보조 정보로 제시한다.",
"source_data": "핵심 비교 포인트: 범위(DX는 BIM을 포함하는 상위 개념, BIM은 3D 중심 기술), 프로세스(DX는 근본적 개선, BIM은 기존 2D 설계 방식 연장), 성과품(DX는 공학 정보 및 콘텐츠 연계, BIM은 3D 모델 중심), 확장성(DX는 전 생애주기 활용 시스템, BIM은 분야별 단절 위험)"
},
{
"id": 6,
"title": "핵심 결론",
"purpose": "결론강조",
"role": "flow",
"layer": "conclusion",
"source_hint": "핵심 요약",
"summary": "BIM은 건설산업의 디지털전환을 수행하는 과정에서 가장 기초가 되는 일부분이다.",
"source_data": "BIM은 건설산업의 디지털전환(DX)을 수행하는 과정에서 가장 기초가 되는 일부분이다"
}
]
}

40
docs/run-001/04-plan/stage-1b-refined-concepts.json Normal file
View File

@@ -0,0 +1,40 @@
{
"concepts": [
{
"topic_id": 1,
"relation_type": "cause_effect",
"expression_hint": "오해의 원인과 그 결과를 짧고 분명하게 보여주는 문제 제기 블록이 적절하다. 사례는 전부 펼치지 말고 대표 사례만 연결한다.",
"source_data": "DX/BIM 혼용, BIM 도입을 DX 완성으로 오인, DX를 BIM 수준으로 축소하는 인식"
},
{
"topic_id": 2,
"relation_type": "definition",
"expression_hint": "DX 정의는 본심의 시작점으로 크고 선명하게 제시한다. 단순 기술 도입이 아니라 산업 전환이라는 점이 강조되어야 한다.",
"source_data": "DX 정의와 상위 개념 설명"
},
{
"topic_id": 3,
"relation_type": "hierarchy",
"expression_hint": "DX가 상위, BIM/GIS/디지털 트윈이 하위 핵심기술이라는 계층 구조를 시각적으로 드러내야 한다. 이미지 참조는 유지하고, 본문과 충돌하지 않게 배치한다.",
"source_data": "BIM 정의, DX와 핵심기술 상호관계, 이미지 참조"
},
{
"topic_id": 4,
"relation_type": "definition",
"expression_hint": "정책 혼용 사례는 본문을 방해하지 않는 보조 카드 또는 사이드바 근거 리스트가 적절하다. 길게 설명하지 않는다.",
"source_data": "스마트 건설 활성화 방안, 제7차 건설기술진흥 기본계획 사례"
},
{
"topic_id": 5,
"relation_type": "comparison",
"expression_hint": "비교표 전체를 재현하지 말고 핵심 4개 비교축만 요약한다. popup 또는 reference 영역으로 처리하는 것이 적절하다.",
"source_data": "범위, 프로세스, 성과품, 확장성 비교 포인트"
},
{
"topic_id": 6,
"relation_type": "none",
"expression_hint": "한 줄 결론을 강하게 강조하는 footer 또는 key message 배너가 적절하다. 문구는 축약하지 않는다.",
"source_data": "BIM은 DX 수행 과정의 가장 기초가 되는 일부분"
}
]
}

85
docs/run-001/06-validation/validation-result.md Normal file
View File

@@ -0,0 +1,85 @@
# Validation Result
## Run
- run id: `run-001`
- input: `01. 건설산업 DX의 올바른 이해(0127).mdx`
- validation basis: `Wiki-2-6`
- execution path: `Kei API` 없이 `run_from_artifacts.py` 브리지 경로 사용
## Final Output
- generated fragments: `05-execution/generated_html.json`
- rendered html: `05-execution/final.html`
- measurement: `05-execution/measurement.json`
## Validation Summary
이번 실행은 `Kei API` 없이 후반부 파이프라인을 실제로 통과시켰다는 점에서 중요한 진전이 있다.
다만 결과를 최종 합격으로 보기에는 아직 이르다.
현재 판정은 다음과 같다.
- 실행 경로 검증: 통과
- 렌더링/측정 검증: 통과
- 내용 보존 검증: 실패
- 최종 품질 판정: 재작업 필요
## What Passed
### 1. 요청 목적 부합 여부
- 결과물은 `DX는 상위 개념`, `BIM은 핵심 기술`이라는 중심 메시지를 유지했다.
- 본문, 사이드바, 푸터 구조로 1장 슬라이드 형태가 생성되었다.
### 2. Kei API 비사용 경로 검증
- `stage-1a-topics.json`와 `stage-1b-refined-concepts.json`을 입력으로 사용했다.
- 기존 `design_agent` 후반부를 연결하는 브리지 스크립트가 실제로 동작했다.
- `Kei API` 호출 없이 실행이 끝까지 진행되었다.
### 3. 렌더링/측정 상태
- `measurement.json` 기준 slide overflow는 없었다.
- body, sidebar, footer 영역 모두 overflow 없이 측정되었다.
- 최소한의 렌더 경로와 결과 저장은 정상 동작했다.
## What Failed
### 1. 내용 보존 검증 실패
`content_verifier` 기준으로 `body_core`에서 누락 문장이 반복 검출되었다.
주요 누락 항목은 다음과 같다.
- 이미지 참조 문구: `[이미지: DX와 핵심기술간 상호관계, 경로: /assets/images/DX1.png]`
- DX/BIM 비교표의 여러 행
- 비교표와 시각 자료 일부가 본문에서 충분히 보존되지 않음
즉, 현재 결과는 핵심 메시지는 살렸지만 원문 보존 규칙을 완전히 만족하지 못했다.
### 2. 검증 기준과 생성 전략의 충돌
- 현재 생성 전략은 비교표를 요약형으로 압축하는 방향이었다.
- 현재 검증 규칙은 원문 세부를 더 강하게 보존하도록 요구한다.
- 그 결과, 실행 계획과 검증 규칙 사이에 충돌이 발생했다.
### 3. 측정 결과 해석 주의
- `measurement.json`에서 body/sidebar의 `block_count`가 0으로 잡혀 있다.
- 이는 렌더 결과 자체는 생성되었지만, 측정 로직이 현재 출력 구조를 완전히 세분해 읽지 못했을 가능성을 시사한다.
- 따라서 `overflow 없음`만으로 시각 품질 합격을 단정하면 안 된다.
## Constraint Check
### 유지된 제약
- DX를 BIM 수준으로 축소하지 않았다.
- BIM을 DX와 동격 개념으로 처리하지 않았다.
- 결론 문장은 유지되었다.
### 아직 불안한 제약
- 원문 비교표와 이미지 참조의 보존 정도
- 보조 자료와 핵심 자료의 경계가 검증 기준과 완전히 맞지 않음
- 본문 구조가 검증기 기준으로는 아직 충분하지 않음
## Final Decision
- 판정: `revise`
- 이유: 실행 성공에도 불구하고 내용 보존 검증이 실패했고, 현재 상태를 최종 결과물로 확정하기 어렵다.
## Next Action
1. `Stage 1A/1B` 산출물에서 비교표와 이미지 참조를 어떻게 다룰지 더 명확히 적는다.
2. `Stage 2` 생성 전략을 `핵심 메시지 유지 + 비교표 핵심 행만 보존` 또는 `비교표를 팝업/보조 영역으로 완전 이관` 중 하나로 명시한다.
3. 필요하면 `content_verifier` 규칙을 `Kei API 없는 run 기반 흐름`에 맞게 조정한다.
4. 재실행 시 `05-execution` 결과와 함께 `06-validation` 실패 패턴을 누적 기록한다.
## Recommended Rollback Point
- 1차 되돌림: `Stage 1B Concept Refinement`
- 2차 되돌림: `Stage 2 HTML Generation`
이유:
현재 실패는 후반 렌더보다도, `무엇을 어느 정도 보존할지`와 `어떻게 표현할지` 사이의 정합성 문제에 더 가깝다.

106
docs/stage-1/Current-Code-Map.md Normal file
View File

@@ -0,0 +1,106 @@
# Current Code Map
## 목적
이 문서는 현재 `design_agent`의 주요 코드 파일이 위키 2/위키 3의 어떤 단계와 연결되는지 정리한다.
## 주요 코드 파일과 역할
### src/main.py
- FastAPI 진입점
- `/api/generate` SSE 처리
- 파이프라인 호출과 응답 흐름 관리
### src/pipeline.py
- 현재 실제 실행 흐름의 중심
- 단계별 진행 관리
- 중간 산출물 저장
- 렌더, 측정, 품질 게이트까지 연결
### src/kei_client.py
- `Kei API` 호출 담당
- classify_content
- refine_concepts
### src/space_allocator.py
- page structure 기반 공간 제약 계산
- height budget, text budget 계산
### src/html_generator.py
- 영역별 HTML 생성
- body/sidebar/footer 생성
- 일부 MDX 정규화 관련 변경 진행 중
### src/content_verifier.py
- 텍스트 보존 검증
- 금지 텍스트 검증
- 구조 검증
- 실패 영역 부분 재시도
### src/renderer.py
- HTML 렌더링
### src/slide_measurer.py
- 실제 브라우저 측정
- 높이/overflow 확인
## 위키 2와 코드의 연결
### Step 1 입력 확인
- 코드 직접 책임보다는 작업 시작 전 준비 단계
- 실제 입력은 main/pipeline으로 전달됨
### Step 2 Kei 기준 해석
- 현재는 `src/kei_client.py` 의존이 큼
- 이후 문서 기반/에이전트 기반으로 대체 대상
### Step 3 콘텐츠 구조화
- 현재는 Kei 응답과 일부 generator 로직에 분산됨
- 이후 분리 필요
### Step 4 실행 계획 수립
- 현재는 명시적 문서 없이 pipeline과 내부 로직에 암묵적으로 존재
- Phase T에서는 더 명확히 분리될 필요가 있음
### Step 5 실제 수행
- `src/pipeline.py`
- `src/space_allocator.py`
- `src/html_generator.py`
- `src/content_verifier.py`
- `src/renderer.py`
- `src/slide_measurer.py`
### Step 6 검증 및 기록
- `src/content_verifier.py`
- `src/slide_measurer.py`
- pipeline의 결과 저장 및 품질 게이트
## 위키 3와 코드의 연결
### Stage 0 입력 로드 및 MDX 정규화
- 현재 일부는 `src/html_generator.py`에서 WIP 형태
- 향후 분리 필요
### Stage 1A Topic Extraction
- 현재 `src/kei_client.py`의 classify_content
### Stage 1B Concept Refinement
- 현재 `src/kei_client.py`의 refine_concepts
### Stage 1.5a / 1.7 / 1.5b
- 현재는 완전히 분리되어 있지 않음
- `src/space_allocator.py`, `src/html_generator.py`, 문서 설계에 걸쳐 있음
### Stage 2 HTML 생성
- `src/html_generator.py`
### Stage 2 검증 및 재시도
- `src/content_verifier.py`
### Stage 3 렌더와 측정
- `src/renderer.py`
- `src/slide_measurer.py`
### Stage 4 품질 게이트와 최종화
- `src/pipeline.py` 중심
## 1단계에서 얻은 중요한 관찰
- 후반부는 이미 코드 자산이 충분하다.
- 가장 큰 전환 포인트는 `src/kei_client.py` 의존 구간이다.
- `Phase T`는 초기 단계와 제약 계산 단계를 더 잘게 분해하고 명시화하려는 방향이다.

63
docs/stage-1/Kei-API-Dependency-Map.md Normal file
View File

@@ -0,0 +1,63 @@
# Kei API Dependency Map
## 목적
이 문서는 현재 `design_agent`에서 `Kei API`가 개입하는 지점과, 앞으로 위키/이슈/에이전트 기반으로 대체해야 하는 지점을 정리한다.
## 현재 Kei API 의존 단계
### 1. classify_content
현재 `Kei API`는 콘텐츠의 주요 꼭지와 관계를 추출하는 역할을 맡는다.
현재 기대되는 성격:
- topic 추출
- relation_type 정리
- expression_hint 초안
- source_data 초안
### 2. refine_concepts
현재 `Kei API`는 추출된 개념을 더 정제하는 역할을 맡는다.
현재 기대되는 성격:
- 핵심/보조 정보 정리
- concept 정제
- relation 보강
- expression_hint 보강
- source_data 보강
## 왜 이 구간이 중요한가
이 두 단계는 단순한 전처리가 아니다.
후속 단계가 어떤 내용을 어느 정도 강조하고 어떤 방식으로 표현할지에 직접 영향을 준다.
즉, 이 구간은 디자인보다 앞선 `의미 판단 단계`다.
## 앞으로의 대체 방향
이 구간은 다음 구조로 옮겨가야 한다.
- 위키 1: 판단 원칙 제공
- 위키 2: 현재 작업 절차 제공
- 위키 3: Stage 1A/1B의 입력/출력/검증 기준 제공
- 이슈: 현재 작업의 실제 입력과 해석 결과 기록
- Codex/Claude: 위 문서를 읽고 topic, concept, hint, source를 직접 정리
즉, API 호출이 아니라 `문서 기반 해석 + 작업 기록 기반 누적`으로 전환한다.
## 대체 후 남아야 하는 정보
Kei API를 없애더라도 아래 정보는 반드시 남아야 한다.
- 핵심 topic
- topic 간 relation
- refined concept
- expression hint
- source data
- 검증 기준
이 정보가 없으면 후반부 코드가 무엇을 중심으로 만들어야 하는지 흔들린다.
## 2단계로 넘길 핵심 질문
- Stage 1A 결과를 어떤 포맷으로 남길 것인가
- Stage 1B 결과를 어떤 포맷으로 남길 것인가
- 이 결과를 이슈에만 남길지, json 산출물로도 남길지
- `src/kei_client.py`를 완전히 제거할지 fallback으로 남길지
## 1단계 결론
현재 `Kei API`는 `design_agent` 전체가 아니라, 초반의 의미 해석과 개념 정제 구간에 집중적으로 묶여 있다.
따라서 2단계에서는 이 구간만 잘 외부화하면 후반부 코드 자산을 상당 부분 유지할 수 있다.

95
docs/stage-1/STAGE-1-Overview.md Normal file
View File

@@ -0,0 +1,95 @@
# STAGE-1-Overview
## 목적
이 문서는 1단계의 기준 문서다.
1단계의 목표는 `design_agent`의 현재 구조를 충분히 이해하고, 그 이해를 `design_agnet_codex`의 위키 및 관련 문서로 정리하는 것이다.
이 단계에서는 아직 `Kei API`를 제거하지 않는다.
먼저 현재 구조와 목표 구조를 명확히 분리해서 기록한다.
## 1단계의 핵심 질문
1. 현재 `design_agent`는 실제로 어떤 순서로 동작하는가
2. 어떤 단계가 코드로 구현되어 있는가
3. 어떤 단계가 `Kei API`에 의존하는가
4. `Phase T`는 현재 구조에서 무엇을 바꾸려 하는가
5. 위키 1/2/3 체계로 이 내용을 어떻게 옮길 것인가
## 현재 design_agent에 대한 이해
현재 `design_agent`는 완전히 새로운 Phase T 구현체라기보다, Phase S 중심의 실행 경로 위에 일부 T 방향 수정이 얹혀 있는 상태로 이해하는 것이 정확하다.
현재 흐름은 크게 다음과 같다.
1. 입력 수신
2. Kei 기반 초기 해석
3. 공간/영역 제약 계산
4. HTML 생성
5. 콘텐츠 검증 및 부분 재시도
6. 렌더링
7. 실제 측정
8. 품질 게이트
9. 결과 저장 및 응답
즉, 전체 시스템의 후반부는 코드 기반으로 꽤 많이 구현되어 있고, 초반부의 의미 해석과 개념 정리가 `Kei API`에 의존하는 구조다.
## 현재 구현과 위키 계층의 연결
### 위키 1
- Kei가 어떻게 판단하는가
- 어떤 의미를 보존해야 하는가
- 무엇을 경계해야 하는가
### 위키 2
- 작업을 어떤 상위 절차로 진행하는가
- 언제 판단 기준을 호출하는가
- 언제 상세 파이프라인으로 내려가는가
### 위키 3
- 실제 내부 파이프라인 stage 정의
- 각 stage의 입력, 출력, 검증, 실패 처리 기준
즉 1단계에서는 현재 `design_agent`를 위키 2와 위키 3의 구조로 다시 서술하는 것이 핵심이다.
## Phase T를 1단계에 반영해야 하는 이유
1단계가 단순히 현재 코드 복사만 되면 안 된다.
현재는 `Phase T` 진행 중이므로, 문서화는 다음 두 축을 함께 가져야 한다.
- 현재 실제 코드가 무엇을 하고 있는가
- 앞으로 Phase T에서 어떤 구조로 정리하려는가
특히 다음 항목은 1단계 문서화에 반드시 반영해야 한다.
- Stage 0 MDX normalization
- Stage 1A / 1B 분리
- Stage 1.5a / 1.7 / 1.5b 분리
- font hierarchy first
- stage별 validation
- partial retry
- quality gate
즉, 위키 3은 단순 구현 설명서가 아니라 `현재 구현 + Phase T 목표 구조`를 함께 보여주는 문서여야 한다.
## 1단계 산출물
1단계에서 만들어야 할 핵심 산출물은 다음과 같다.
- 위키 1 계열 정리
- 위키 2 계열 정리
- 위키 3 계열 정리
- 현재 코드와 위키 단계 매핑 문서
- Kei API 의존 지점 정리 문서
- Phase T 반영 포인트 정리 문서
## 완료 기준
1단계는 아래 조건을 만족하면 완료로 본다.
- `design_agent`의 전체 흐름을 위키 2와 위키 3으로 설명할 수 있다.
- 어떤 단계가 코드 책임인지, 어떤 단계가 Kei 책임인지 구분되어 있다.
- `Kei API` 제거 전환 시 무엇을 바꿔야 하는지 문서로 드러난다.
- `Phase T` 반영 포인트가 누락되지 않는다.
## 1단계 이후로 넘어갈 수 있는 상태
1단계가 끝나면 다음 질문에 답할 수 있어야 한다.
- `Kei API`를 제거하려면 어느 단계부터 바꿔야 하는가
- 어떤 중간 산출물이 필요할까
- 어떤 코드는 유지하고 어떤 입력 경로만 바꾸면 되는가
그 상태가 되면 2단계인 `Kei API를 안 쓰는 방식으로 개선하기`로 넘어갈 수 있다.

41
issues/run-001.md Normal file
View File

@@ -0,0 +1,41 @@
# run-001 Issue Draft
## 제목
run-001 - 건설산업 DX의 올바른 이해(0127) / Kei API 없이 후반부 실행 실험
## 입력
- 파일: `01. 건설산업 DX의 올바른 이해(0127).mdx`
- 목적: DX와 BIM의 혼용 문제를 바로잡고, DX는 상위 개념이고 BIM은 핵심 기술이라는 메시지를 1장 슬라이드로 전달
## Step 1 입력 확인 결과
- `docs/run-001/01-input/input-review.md` 참고
## Step 2 Kei 기준 해석 결과
- `docs/run-001/02-kei-interpretation/kei-interpretation.md` 참고
## Step 3 콘텐츠 구조화 결과
- `docs/run-001/03-structure/content-structure.md` 참고
## Step 4 실행 계획
- `docs/run-001/04-plan/execution-plan.md` 참고
- Stage 1A/1B 대체 입력:
- `docs/run-001/04-plan/stage-1a-topics.json`
- `docs/run-001/04-plan/stage-1b-refined-concepts.json`
## 실행 경로
- `scripts/run_from_artifacts.py` 사용
- `Kei API` 없이 run 산출물을 입력으로 사용
- 후반부는 기존 `design_agent` 코드 자산 활용
## 검증 결과
- `docs/run-001/06-validation/validation-result.md` 참고
- 요약:
- 실행 경로 검증: 통과
- 렌더링/측정: 통과
- 내용 보존 검증: 실패
- 최종 판정: revise
## 다음 액션
1. Stage 1A/1B 산출물 정교화
2. 비교표/이미지 처리 방식 명시 강화
3. 필요 시 verifier 규칙 조정

290
scripts/run_from_artifacts.py Normal file
View File

@@ -0,0 +1,290 @@
from __future__ import annotations
import argparse
import asyncio
import json
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
if str(ROOT) not in sys.path:
sys.path.insert(0, str(ROOT))
from src.block_reference import select_and_generate_references
from src.config import settings
from src.content_verifier import generate_with_retry
from src.design_director import LAYOUT_PRESETS, select_preset
from src.image_utils import embed_images, get_image_sizes
from src.mdx_normalizer import normalize_mdx_content
from src.pipeline_context import (
Analysis,
BlockReference,
ContainerInfo,
DesignBudget,
FontHierarchy,
NormalizedContent,
PageStructure,
PipelineContext,
Topic,
create_context,
)
from src.renderer import render_slide_from_html
from src.slide_measurer import capture_slide_screenshot, measure_rendered_heights
from src.space_allocator import (
ContainerSpec as LegacyContainerSpec,
calculate_container_specs,
calculate_design_budget,
calculate_dynamic_ratio,
calculate_font_hierarchy,
)
def _load_json(path: Path) -> dict:
return json.loads(path.read_text(encoding='utf-8-sig'))
def _build_context(content: str, base_path: str, stage1a: dict, stage1b: dict) -> PipelineContext:
ctx = create_context(content, base_path)
normalized = normalize_mdx_content(content)
ctx.normalized = NormalizedContent(
clean_text=normalized['clean_text'],
title=normalized['title'],
images=normalized['images'],
popups=normalized['popups'],
tables=normalized['tables'],
sections=normalized['sections'],
)
analysis_raw = stage1a['analysis']
ctx.analysis = Analysis(
core_message=analysis_raw['core_message'],
title=analysis_raw['title'],
total_pages=analysis_raw.get('total_pages', 1),
)
ctx.page_structure = PageStructure(roles=stage1a['page_structure'])
refined_map = {item['topic_id']: item for item in stage1b['concepts']}
topics = []
for raw in stage1a['topics']:
merged = dict(raw)
if raw['id'] in refined_map:
merged.update(refined_map[raw['id']])
topics.append(Topic(**merged))
ctx.topics = topics
return ctx
def _stage_1_5a(ctx: PipelineContext) -> PipelineContext:
image_sizes = get_image_sizes(ctx.raw_content, ctx.base_path)
role_text_lengths = {}
for role, info in ctx.page_structure.roles.items():
if isinstance(info, dict):
role_text_lengths[role] = len(ctx.get_role_content(role))
font_hierarchy_dict = calculate_font_hierarchy(role_text_lengths)
ctx.font_hierarchy = FontHierarchy(
key_msg=font_hierarchy_dict.get('핵심', 14.0),
core=font_hierarchy_dict.get('본심', 12.0),
bg=font_hierarchy_dict.get('배경', 11.0),
sidebar=font_hierarchy_dict.get('첨부', 10.0),
)
ctx.container_ratio = calculate_dynamic_ratio(role_text_lengths, font_hierarchy_dict)
analysis_dict = {
'topics': [t.model_dump() for t in ctx.topics],
'page_structure': ctx.page_structure.roles,
}
preset_name = select_preset(analysis_dict)
ctx.preset_name = preset_name
ctx.preset = LAYOUT_PRESETS.get(preset_name, {})
container_specs = calculate_container_specs(
page_structure=ctx.page_structure.roles,
topics=[t.model_dump() for t in ctx.topics],
preset=ctx.preset,
slide_width=settings.slide_width,
slide_height=settings.slide_height,
)
ctx.containers = {
role: ContainerInfo(
role=spec.role,
zone=spec.zone,
topic_ids=spec.topic_ids,
weight=spec.weight,
height_px=spec.height_px,
width_px=spec.width_px,
max_height_cost=spec.max_height_cost,
block_constraints=spec.block_constraints,
)
for role, spec in container_specs.items()
}
slide_images = []
for img_key, img_info in (image_sizes or {}).items():
img_path = Path(ctx.base_path) / img_key if ctx.base_path else Path(img_key)
slide_images.append({
'path': str(img_path),
'width': img_info.get('width', 0),
'height': img_info.get('height', 0),
'ratio': round(img_info.get('width', 1) / max(1, img_info.get('height', 1)), 2),
'topic_id': img_info.get('topic_id'),
'b64': '',
})
ctx.slide_images = slide_images
ctx.analysis = ctx.analysis.model_copy(update={'image_sizes': image_sizes or {}})
return ctx
def _stage_1_7(ctx: PipelineContext) -> PipelineContext:
refs_raw = select_and_generate_references(
topics=[t.model_dump() for t in ctx.topics],
containers=ctx.containers,
page_structure=ctx.page_structure.roles,
)
ctx.references = {
role: BlockReference(
block_id=ref['block_id'],
variant=ref['variant'],
visual_type=ref['visual_type'],
schema_info=ref['schema_info'],
design_reference_html=ref['design_reference_html'],
)
for role, ref in refs_raw.items()
}
return ctx
def _stage_1_5b(ctx: PipelineContext) -> PipelineContext:
updated = {}
font_map = {'본심': 'core', '배경': 'bg', '첨부': 'sidebar', '결론': 'core'}
for role, ci in ctx.containers.items():
ref = ctx.references.get(role)
schema_info = ref.schema_info if ref else {}
font_size = getattr(ctx.font_hierarchy, font_map.get(role, 'core'), 12.0)
budget = calculate_design_budget(
container_height_px=ci.height_px,
container_width_px=ci.width_px,
block_schema=schema_info,
font_size=font_size,
)
updated[role] = ci.model_copy(update={
'design_budget': DesignBudget(
available_height_px=budget['available_height_px'],
available_width_px=budget['available_width_px'],
max_circle_diameter=budget['max_circle_diameter'],
max_img_width=budget['max_img_width'],
max_img_height=budget['max_img_height'],
fits=budget['fits'],
)
})
ctx.containers = updated
return ctx
async def _stage_2(ctx: PipelineContext) -> PipelineContext:
analysis_dict = {
'topics': [t.model_dump() for t in ctx.topics],
'page_structure': ctx.page_structure.roles,
'core_message': ctx.analysis.core_message,
'title': ctx.analysis.title,
'total_pages': ctx.analysis.total_pages,
'image_sizes': ctx.analysis.image_sizes,
}
container_specs_dict = {
role: LegacyContainerSpec(
role=ci.role,
zone=ci.zone,
topic_ids=ci.topic_ids,
weight=ci.weight,
height_px=ci.height_px,
width_px=ci.width_px,
max_height_cost=ci.max_height_cost,
block_constraints=ci.block_constraints,
)
for role, ci in ctx.containers.items()
}
analysis_dict['phase_t'] = {
'font_hierarchy': ctx.font_hierarchy.model_dump(),
'container_ratio': ctx.container_ratio,
'references': {role: ref.model_dump() for role, ref in ctx.references.items()},
'design_budgets': {
role: ci.design_budget.model_dump() if ci.design_budget else {}
for role, ci in ctx.containers.items()
},
}
generated, _verification = await generate_with_retry(
content=ctx.raw_content,
analysis=analysis_dict,
container_specs=container_specs_dict,
preset=ctx.preset,
images=ctx.slide_images,
)
ctx.generated_html = generated
return ctx
def _stage_3(ctx: PipelineContext) -> PipelineContext:
analysis_dict = {
'topics': [t.model_dump() for t in ctx.topics],
'page_structure': ctx.page_structure.roles,
'core_message': ctx.analysis.core_message,
'title': ctx.analysis.title,
}
ctx.rendered_html = render_slide_from_html(ctx.generated_html, analysis_dict, ctx.preset)
if ctx.base_path:
ctx.rendered_html = embed_images(ctx.rendered_html, ctx.base_path)
return ctx
def _stage_4_lite(ctx: PipelineContext) -> PipelineContext:
ctx.measurement = measure_rendered_heights(ctx.rendered_html)
ctx.screenshot_b64 = capture_slide_screenshot(ctx.rendered_html) or ''
ctx.quality_score = 100 if not any(
zone.get('overflowed') for zone in ctx.measurement.get('zones', {}).values()
) else 60
return ctx
async def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument('--input', required=True)
parser.add_argument('--stage1a', required=True)
parser.add_argument('--stage1b', required=True)
parser.add_argument('--base-path', default='')
parser.add_argument('--output-dir', required=True)
args = parser.parse_args()
content = Path(args.input).read_text(encoding='utf-8')
stage1a = _load_json(Path(args.stage1a))
stage1b = _load_json(Path(args.stage1b))
ctx = _build_context(content, args.base_path, stage1a, stage1b)
ctx = _stage_1_5a(ctx)
ctx = _stage_1_7(ctx)
ctx = _stage_1_5b(ctx)
ctx = await _stage_2(ctx)
ctx = _stage_3(ctx)
ctx = _stage_4_lite(ctx)
out_dir = Path(args.output_dir)
out_dir.mkdir(parents=True, exist_ok=True)
(out_dir / 'generated_html.json').write_text(
json.dumps(ctx.generated_html, ensure_ascii=False, indent=2),
encoding='utf-8',
)
(out_dir / 'final.html').write_text(ctx.rendered_html, encoding='utf-8')
(out_dir / 'measurement.json').write_text(
json.dumps(ctx.measurement, ensure_ascii=False, indent=2),
encoding='utf-8',
)
(out_dir / 'context.json').write_text(
ctx.model_dump_json(indent=2, exclude={'screenshot_b64', 'rendered_html'}),
encoding='utf-8',
)
if __name__ == '__main__':
asyncio.run(main())