diff --git a/README.md b/README.md index d36e6c4..3188f3f 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,22 @@ # C.E.L._slide_test -이 저장소는 `mdx` 문서를 읽고 슬라이드 HTML 결과물로 변환하는 전체 실행 프로세스를 관리하기 위한 작업 저장소다. +이 저장소는 `mdx` 문서를 읽고 슬라이드 HTML 결과물로 변환하는 **일반 파이프라인**을 관리하기 위한 작업 저장소다. -핵심 목표는 다음과 같다. -- 누구라도 같은 저장소 구조와 위키 기준만으로 `mdx -> 슬라이드` 변환을 수행할 수 있어야 한다. -- 실행 과정은 `위키 -> 이슈 -> docs/run-xxx -> 결과물` 순서로 추적 가능해야 한다. -- 결과는 한 번 만들고 끝나는 것이 아니라, `검증 -> revise -> rollback -> 재실행` 루프로 개선 가능해야 한다. -- Codex와 Gitea를 함께 사용해 작업 기준, 실행 기록, 산출물, 검증 결과를 모두 남긴다. +핵심 목표는 특정 샘플 3개를 예쁘게 만드는 것이 아니라, **어떤 MDX가 와도 내용 기반으로 적절한 슬라이드 구조를 고르고 결과를 검증하는 파이프라인**을 만드는 것이다. + +## 핵심 원칙 +- 원문 텍스트는 가능한 한 많이 유지한다. 큰 표, 큰 이미지, 긴 사례를 제외하면 텍스트의 약 85% 이상 보존을 목표로 한다. +- Step 1 ~ Step 3에서 임의 요약, 임의 제목 변경, 임의 순서 변경을 최소화한다. +- 넘치는 내용은 삭제보다 `popup`으로 이동한다. +- 모든 문서를 같은 골격에 넣지 않고, 콘텐츠 성격에 따라 `content family`를 먼저 분류한다. +- `content family`에 따라 zone, container, layout family, popup 전략을 다르게 잡는다. +- 목표는 특정 3개 run의 예외처리가 아니라, 임의의 MDX를 처리할 수 있는 일반 파이프라인이다. ## 저장소 역할 - -이 저장소는 단순 코드 저장소가 아니다. 아래 네 가지 역할을 함께 가진다. +이 저장소는 네 가지 역할을 함께 가진다. 1. 입력과 산출물 저장소 -- `mdx` 원문 입력 +- 원본 MDX 입력 - 중간 구조화 결과 - stage snapshot - 최종 HTML 결과물 @@ -37,40 +40,29 @@ - 이슈에는 단계별 실행 지시와 코멘트를 둔다. - `docs/run-xxx`에는 실제 작업 기록과 결과를 둔다. -## 전체 구조 - +## 구조 - `docs/` - run별 입력, 중간 산출물, stage snapshot, 최종 결과물, 검증 결과 - `scripts/` - 실제 실행, 자동 루프, Gitea 이슈 코멘트 등록 스크립트 - `issues/` - Gitea 이슈 탭에 등록할 Step 1 ~ Step 6 본문 초안 - -주요 경로: -- `docs/run-001/01-input/` -- `docs/run-001/02-kei-interpretation/` -- `docs/run-001/03-structure/` -- `docs/run-001/04-plan/` -- `docs/run-001/05-execution/` -- `docs/run-001/06-validation/` +- `results/` + - run별 결과물을 빠르게 비교하기 위한 복사본 +- `templates/` + - 로컬에서 직접 참조하는 템플릿 자산과 catalog ## 위키, 이슈, docs의 역할 분리 - ### 위키 위키는 기준서다. - -위키에서 관리하는 내용: -- 사고방식과 운영 원칙 -- 상위 작업 절차 +- 판단 기준 +- 작업 절차 - 상세 파이프라인 - 실행 프롬프트 - -즉, 위키는 `어떻게 할 것인가`를 정의한다. +- content family와 layout family 원칙 ### 이슈 이슈는 실행 단위다. - -이슈에서 관리하는 내용: - Step 1 입력 확인 - Step 2 기준 해석 - Step 3 콘텐츠 구조화 @@ -78,13 +70,9 @@ - Step 5 실제 수행 - Step 6 검증 및 기록 -즉, 이슈는 `이번 step에서 무엇을 할 것인가`와 `실행 후 무엇이 나왔는가`를 관리한다. - ### docs/run-xxx `docs/run-xxx`는 실제 작업 기록과 산출물 저장소다. - -여기에는 다음이 들어간다. -- 원본 입력 `mdx` +- 원본 입력 MDX - 중간 해석 파일 - 계획 파일 - stage context snapshot @@ -93,66 +81,74 @@ - validation 결과 - 이슈 코멘트 원문 -즉, `docs/run-xxx`는 `실제로 무엇이 만들어졌는가`와 `어느 stage에서 무엇이 바뀌었는가`를 저장한다. - -## 실행 대상 입력 - -각 run은 반드시 원본 입력 파일을 `01-input`에 함께 둔다. +## content family와 layout family +현재 파이프라인은 먼저 콘텐츠를 family로 분류한 뒤, family에 맞는 layout family를 고르는 방향으로 정리한다. 예시: -- `docs/run-001/01-input/01. 건설산업 DX의 올바른 이해(0127).mdx` +- `Type A`: 비교/정의/관계형 + - `run-001` 계열 + - 비교, 정의, 관계 설명이 동시에 필요한 경우 +- `Type B`: 본문 중심형 + - 목표/효과형 + - 요건/프로세스/결과형 + - 오른쪽 독립 sidebar보다 body 중심 재배치를 우선하는 경우 -이 원칙이 중요한 이유: -- run만 보면 입력부터 결과까지 모두 추적 가능해야 한다. -- 외부 경로를 다시 찾지 않아도 재실행이 가능해야 한다. +중요한 점은, layout은 내용을 다시 쓰는 수단이 아니라 **원문 block을 더 잘 보이게 재배치하는 수단**이어야 한다는 점이다. + +## popup 전략 +popup은 본문 부족을 가리는 수단이 아니라, **상세를 숨기면서 본문 가시성을 유지하는 수단**이다. + +원칙: +- 큰 표 전체 +- 긴 사례 설명 +- 긴 참고 근거 +- 이미지 원문 설명 전체 +같은 것은 popup으로 이동 가능하다. + +대신 본문에는 반드시 남아야 한다. +- 섹션 제목 +- 핵심 bullet 또는 핵심 문장 +- popup을 여는 요약 진입점 ## 기본 실행 흐름 - -전체 흐름은 다음과 같다. - 1. 위키의 `Prompt`를 읽는다. 2. Step 이슈를 읽는다. -3. `docs/run-xxx/01-input`의 원본 `mdx`를 입력으로 사용한다. -4. Step 1 ~ Step 4 결과를 기준으로 실행 준비를 마친다. -5. `scripts/run_from_artifacts.py`로 실제 stage 실행을 수행한다. -6. `scripts/auto_loop_runner.py`로 검증, retry-plan 생성, rollback, 반복 실행을 수행한다. -7. 결과를 `docs/run-xxx/05-execution`, `06-validation`에 저장한다. -8. Step 5, Step 6 결과를 Gitea 이슈 코멘트로 남긴다. +3. `docs/run-xxx/01-input`의 원본 MDX를 입력으로 사용한다. +4. Step 1 ~ Step 3에서 원문 block을 추출하고, content family와 popup 후보를 정리한다. +5. Step 4에서 family에 맞는 zone/container/layout을 고른다. +6. `scripts/run_from_artifacts.py`로 실제 stage 실행을 수행한다. +7. `scripts/auto_loop_runner.py`로 검증, retry-plan 생성, rollback, 반복 실행을 수행한다. +8. 결과를 `docs/run-xxx/05-execution`, `06-validation`에 저장한다. +9. Step 5, Step 6 결과를 Gitea 이슈 코멘트로 남긴다. ## Step 정의 - ### Step 1. 입력 확인 -- 입력 문서를 식별한다. -- 문서 제목, 목적, 범위, 제약을 정리한다. -- 결과는 `01-input/input-review.md`에 남긴다. +- 원문 block, 제목, 순서, 표/이미지/사례 위치를 식별한다. +- 이 단계의 최우선은 요약이 아니라 원문 구조 보존이다. ### Step 2. 기준 해석 -- 입력을 슬라이드 목적에 맞게 해석한다. -- 핵심 메시지, 보존 기준, 실패 패턴을 정리한다. -- 결과는 `02-kei-interpretation/`에 남긴다. +- 핵심 목적, 의미 보존 기준, 실패 패턴, popup 후보를 정리한다. +- 이 단계의 목적은 재서술이 아니라 보존 기준과 grouping 기준을 세우는 것이다. ### Step 3. 콘텐츠 구조화 -- 중심 메시지와 보조 정보를 구분한다. -- 본문, 사이드, 결론의 배치 가정을 세운다. -- 결과는 `03-structure/`에 남긴다. +- 원문 block을 `가시 본문 / popup / 결론`으로 나눈다. +- content family를 확정한다. +- 원문 순서를 함부로 바꾸지 않는다. ### Step 4. 실행 계획 -- 실제 stage 실행 계획을 세운다. -- Stage 1A/1B 산출물, 실행 입력, 검증 포인트를 정리한다. -- 결과는 `04-plan/`에 남긴다. +- family에 맞는 zone/container/layout family를 결정한다. +- stage별 입력, 출력, 검증 지점을 남긴다. ### Step 5. 실제 수행 -- 실제 HTML 생성과 렌더링, 측정을 수행한다. -- stage snapshot과 산출물은 `05-execution/`에 남긴다. +- 실제 HTML 생성, 렌더링, 측정을 수행한다. +- stage snapshot과 산출물을 저장한다. ### Step 6. 검증 및 기록 -- 핵심 메시지 가시성, 비교 정보, 이미지 참조, overflow 여부를 검증한다. +- overflow, 핵심 메시지 가시성, 원문 보존율, popup 이동 적절성, 빈 block 여부를 검증한다. - 실패 시 retry-plan과 rollback 기준을 만든다. -- 결과는 `06-validation/`에 남긴다. ## stage snapshot - -`run_from_artifacts.py`는 실행 중간 상태를 stage별로 저장한다. +`run_from_artifacts.py`는 stage별 중간 상태를 저장한다. 예시: - `stage_0_context.json` @@ -167,165 +163,40 @@ - `stage_4_context.json` - `final_context.json` -이 구조가 중요한 이유: -- 최종 `final.html`만 보고 수정하지 않는다. -- 실패가 나면 어느 stage로 돌아가야 하는지 추적할 수 있다. -- 무한 루프에 가까운 반복 개선의 근거가 된다. +이 구조가 중요한 이유는, 실패가 나면 최종 HTML만 다시 고치는 것이 아니라 어느 stage로 돌아가야 하는지 추적할 수 있기 때문이다. ## 자동 루프 +핵심 루프는 `실행 -> 검증 -> retry-plan -> rollback -> 재실행 -> 재검증`이다. -이 저장소의 핵심은 한 번 생성하고 끝나는 것이 아니라, 실패 시 자동으로 보정하고 다시 실행하는 루프다. - -현재 자동 루프 스크립트: +주요 스크립트: +- `scripts/raw_bootstrap.py` + - raw MDX 기준 Step 1 ~ Step 3와 stage 1a/1b 초기 산출물 정리 +- `scripts/run_from_artifacts.py` + - stage 실행, 템플릿 참조, 결과물 생성 - `scripts/auto_loop_runner.py` - -이 스크립트가 하는 일: -- `run_from_artifacts.py` 실행 -- 결과 HTML, measurement, stage snapshot 로드 -- strict 검증 수행 -- 실패 시 `retry-plan.json` 생성 -- 실패 분류에 따라 rollback stage 결정 -- `stage-1b-refined-concepts.json` 보정 및 이력 백업 생성 -- 다시 실행 후 재검증 -- validation 결과 기록 -- Step 5 / Step 6 코멘트 파일 작성 -- Gitea 이슈 코멘트 자동 등록 - -즉, 이 스크립트는 `실행 -> 검증 -> retry-plan -> rollback -> 재실행 -> 재검증`의 핵심 루프를 담당한다. - -## retry-plan과 rollback - -검증 실패 시 `04-plan/retry-plan.json`이 생성된다. - -이 파일에는 다음이 들어간다. -- 실패 분류 -- rollback stage -- 실패 이유 -- 어떤 topic 또는 budget을 어떻게 보정할지에 대한 mutation 목록 - -또한 `04-plan/history/` 아래에 stage 입력의 이전 버전이 백업된다. - -예시: -- `stage-1b-refined-concepts.iteration-1.json` -- `stage-1b-refined-concepts.iteration-2.json` - -즉, 루프는 단순히 마지막 HTML을 덮어쓰는 것이 아니라, stage 입력을 보정하고 다시 생성하는 구조다. + - 검증, retry-plan 생성, rollback, 재실행 +- `scripts/gitea_issue_sync.py` + - Gitea 이슈/코멘트 API 연동 ## strict 검증 기준 - -현재 합격 기준은 단순히 `HTML이 만들어졌는가`가 아니다. - -아래가 모두 충족되어야 `pass`다. -- `slide overflow = false` -- `body overflow = false` -- `sidebar overflow = false` -- `footer overflow = false` +합격 기준은 단순히 HTML 생성 여부가 아니다. +- slide/body/sidebar/footer overflow 없음 - 핵심 메시지 가시 텍스트 존재 -- 이미지/도해 참조 문구 존재 -- 비교 핵심 4축(범위, 프로세스, 성과품, 확장성) 존재 -- 관계도 블록 존재 - -즉, `측정 통과 + 가시 정보 보존 + 슬라이드 구조 유지`가 모두 만족되어야 한다. - -## 주요 스크립트 - -### `scripts/run_from_artifacts.py` -역할: -- Step 4에서 만들어진 입력 산출물을 사용해 실제 stage 실행 수행 -- stage snapshot 저장 -- `generated_html.json`, `final.html`, `measurement.json`, `context.json`, `final_context.json` 저장 -- `retry-plan.json`이 있으면 `stage_2`에서 재생성 전략 적용 - -### `scripts/auto_loop_runner.py` -역할: -- 실행 결과를 다시 읽음 -- strict 검증 수행 -- 실패 시 retry-plan 생성 -- rollback 기준에 따라 stage 입력 보정 -- validation 기록 저장 -- Step 5 / Step 6 코멘트 자동 생성 -- Gitea 이슈 코멘트 자동 등록 - -### `scripts/gitea_issue_sync.py` -역할: -- Gitea REST API를 통해 이슈 생성, 본문 수정, 코멘트 등록 수행 - -## Gitea 이슈 운영 방식 - -이슈는 Step 단위로 관리한다. - -예시: -- `Step-1-Input-Review` -- `Step-2-Interpretation` -- `Step-3-Content-Structuring` -- `Step-4-Execution-Planning` -- `Step-5-Execution` -- `Step-6-Validation-and-Recording` - -실행 결과는 각 step 이슈의 코멘트로 누적된다. - -즉: -- 이슈 본문 = step 정의와 KPI -- 이슈 코멘트 = 실제 실행 결과 - -## Gitea 자동 코멘트 등록 - -필요 환경변수: -- `GITEA_URL` -- `GITEA_TOKEN` - -예시: -```powershell -$env:GITEA_URL="https://gitea.hmac.kr" -$env:GITEA_TOKEN="발급받은_개인_액세스_토큰" -``` - -주의: -- 토큰은 채팅이나 문서에 그대로 남기지 않는다. -- 노출된 토큰은 즉시 폐기하고 새로 발급한다. +- family에 필요한 핵심 block 존재 +- popup 이동 후에도 본문 summary가 남아 있음 +- 빈 block, placeholder, 잘린 row 없음 +- 원문 보존율과 시선 흐름이 기준을 넘음 ## 새 run을 시작하는 방법 - 1. `docs/run-template/`를 복사해 새 run 폴더를 만든다. -2. 원본 `mdx`를 `01-input/`에 넣는다. -3. 필요한 Step 1 ~ Step 4 산출물을 채운다. -4. 위키의 `Prompt`를 기준으로 실행한다. -5. `scripts/auto_loop_runner.py`를 실행한다. -6. 결과와 retry-plan, history를 확인한다. +2. 원본 MDX를 `01-input/`에 넣는다. +3. 위키의 `Prompt`를 기준으로 실행한다. +4. `scripts/raw_bootstrap.py`와 `scripts/auto_loop_runner.py`를 실행한다. +5. 결과와 retry-plan, history를 확인한다. +6. Gitea 이슈 코멘트와 results 폴더를 확인한다. -## 사람이 실제로 하는 최소 판단 +## 현재 저장소의 의미 +현재 저장소는 run-001, run-002, run-003을 통해 family 분기와 raw 보존, popup 전략, stage 기반 retry를 테스트하고 있다. -이 시스템이 자동화된 뒤에도 사람은 최소한 아래를 확인하는 것이 좋다. -- 최종 `final.html`이 실제 사용 목적에 맞는가 -- 너무 과하게 압축되지는 않았는가 -- 표현 톤이나 정보 강조가 의도와 맞는가 -- stage rollback 방향이 설득력 있는가 - -즉, 시스템의 `pass`는 운영 기준 합격이고, 최종 실사용 품질은 사람 검토로 한 번 더 확인하면 가장 좋다. - -## 결과물 확인 위치 - -주요 결과물: -- 최종 HTML: `docs/run-001/05-execution/final.html` -- 생성 HTML JSON: `docs/run-001/05-execution/generated_html.json` -- 측정 결과: `docs/run-001/05-execution/measurement.json` -- 검증 결과: `docs/run-001/06-validation/validation-result.md` -- 재시도 계획: `docs/run-001/04-plan/retry-plan.json` -- 재시도 이력: `docs/run-001/04-plan/history/` - -## 현재 상태 - -현재 `run-001`은 strict 기준으로 `pass`를 달성했다. - -즉, 이 저장소는 이제 다음을 실제로 수행할 수 있다. -- `mdx` 입력을 저장소 안에 둔다. -- Codex가 위키와 이슈를 읽는다. -- 단계별 실행을 수행한다. -- stage snapshot을 저장한다. -- strict 검증을 수행한다. -- 실패 시 retry-plan과 rollback으로 재실행한다. -- Gitea 이슈 코멘트로 결과를 남긴다. - -## 한 줄 요약 - -이 저장소는 `Codex + Gitea + docs/run-xxx 구조`를 이용해 누구라도 `mdx -> 슬라이드` 변환을 반복 실행하고 검증하고 개선할 수 있도록 만든 운영 저장소다. +하지만 이 샘플들은 목표가 아니라 검증용 데이터다. +목표는 **임의의 MDX를 넣었을 때도 같은 절차로 content family를 고르고, 원문 85% 보존과 popup 전략을 통해 슬라이드로 만드는 일반 파이프라인**이다.