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

2026-04-01 16:16:49 +09:00
commit 1481a36fda
16 changed files with 1347 additions and 0 deletions
--- a/docs/run-001/04-plan/artifact-bridge-notes.md
+++ b/docs/run-001/04-plan/artifact-bridge-notes.md
@@ -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 경로다.
--- a/docs/run-001/04-plan/execution-plan.md
+++ b/docs/run-001/04-plan/execution-plan.md
@@ -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`
--- a/docs/run-001/04-plan/stage-1a-topics.json
+++ b/docs/run-001/04-plan/stage-1a-topics.json
@@ -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)을 수행하는 과정에서 가장 기초가 되는 일부분이다"
+    }
+  ]
+}
--- a/docs/run-001/04-plan/stage-1b-refined-concepts.json
+++ b/docs/run-001/04-plan/stage-1b-refined-concepts.json
@@ -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 수행 과정의 가장 기초가 되는 일부분"
+    }
+  ]
+}