Humanize PPT은(는) 무엇을 하나요?
사용자가 원자재, 메모, 음성 기록, 문서, 링크를 프레젠테이션 준비가 된 아웃라인과 페이지별 미디어 결정으로 변환한 후, 다운스트림 스킬에 렌더링을 위임하려 할 때 이 스킬을 사용합니다. 기존 PPT/PPTX 파일은 직접 읽지 않습니다. 먼저 텍스트를 추출한 다음(scripts/pptx_qa.py의 dump/inspect 출력 참조), 해당 텍스트를 --source로 입력합니다. Humanize PPT가 이미 렌더링한 덱은 대신 --qa-from <rendered.pptx>를 사용합니다. 이는 브리프 모드가 아닌 프레젠테이션 체크업 모드입니다.
포지셔닝
Humanize PPT는 발표를 위해 태어난 프레젠테이션 시스템입니다. 아웃라인 디렉터(AST 청중 상태 전이 – 페이지가 넘어갈 때마다 청중이 앞으로 나아감), 페이지별 시각적 개선 디렉터(실제 이미지 / SVG 다이어그램 / Remotion 비디오), 제작 브리프 오케스트레이터, 프레젠테이션 체크업 러너(演讲体检; 이전의 QA 루프, CLI 플래그는 여전히 --qa-from), 그리고 발표자 모드 핸드오프를 담당합니다. 동기는 다음과 같습니다. HTML-PPT 템플릿 스킬은 개념 표시에는 훌륭하지만 간단한 아이디어를 수십 개의 예쁜 페이지로 불려버리는 반면, 실제 90분 발표는 약 30페이지입니다. 예쁜 껍데기가 내용 밀도를 따라가지 못합니다. Humanize는 그 격차를 해소합니다. 아름다움(다운스트림 템플릿 스킬이 네이티브로 렌더링)을 유지하고 발표 가능하게 만듭니다. 즉, 일어나서 전달할 수 있는 라인을 제공합니다. 다운스트림 템플릿 스킬은 "아름답게 렌더링"을 담당하고, Humanize는 "이것은 발표이며, 누군가가 검토했다"를 담당합니다.
프레젠테이션 체크업을 한 문장으로 요약하면 다음과 같습니다. 아름다움을 평가하지 않고, 아웃라인을 평가합니다. 렌더링된 모든 페이지를 아웃라인 페이지와 비교하고, 볼 수만 있고 말할 수 없는 페이지를 찾아내며, 모든 페이지가 발표자가 일어나서 발표할 수 있을 때까지 계속합니다. 실패한 페이지란, 간단히 말해 몇 단어만 담고 요점을 끝내지 못하는 페이지, 또는 약속한 청중 상태 전이를 실패하는 페이지(청중이 그 페이지에 들어갔을 때와 같은 상태로 나옴)입니다. 그러한 페이지는 존재해서는 안 됩니다. 체크업이 이를 찾아내고 수정 지침을 생성합니다.
Humanize는 일반적으로 마크다운과 JSON을 소비할 수 있는 다운스트림 렌더러와 호환됩니다. 검증된 경로는 다음과 같습니다. 중국어 HTML → guizang-ppt-skill, 영어 HTML → frontend-slides / beautiful-html-templates, 네이티브 편집 가능 PowerPoint → ppt-master. 다른 다운스트림은 여전히 핫 플러그 가능하며, 지원 수준은 registry/renderer_registry.json에 있으며 실제 출력에 대해서만 업데이트됩니다.
이 스킬은 다운스트림 PPT / HTML 슬라이드 스킬 전과 포스트 렌더 프레젠테이션 체크업 주변에서 실행됩니다. AST 계약, 페이지별 미디어 결정(이 페이지에 사진, 시스템 다이어그램, 10초 프로세스 클립, 아무것도 필요하지 않은가?), 다음 에이전트가 소비할 제작 브리프, 그리고 렌더링된 HTML/PPTX에 대한 체크업 패스를 담당합니다. 렌더링된 덱 자체는 소유하지 않습니다.
렌더링 전에 두 가지 인간 검토 게이트가 있습니다. 아웃라인 미리보기와 렌더러의 스타일 게이트입니다. HTML 경로는 Humanize의 ≥4 실제 커버 --style-gallery를 사용합니다. PPT Master는 이미 기본 시각적 미리보기가 포함된 필수 3단계 Confirm UI를 소유하고 있으므로, --renderer ppt-master --style-gallery는 해당 게이트에 위임하고 style_gallery_plan.json + commands/style-gallery/ppt-master-confirm-ui.md를 작성하여 카탈로그를 중복하지 않습니다.
사용자는 Humanize PPT를 브리프를 위해 한 번 호출하고, 브리프를 다운스트림 스킬에 전달하여 네이티브 렌더링을 수행한 다음, --qa-from <rendered.html|native.pptx>와 함께 다시 Humanize를 호출하여 3회 반복 프레젠테이션 체크업을 실행합니다. 각 반복은 qa_report.md, fix_prompt.md, qa_iteration.json을 작성합니다. 3회 후에도 실패가 남아 있으면 상태가 needs-human으로 전환됩니다.
Humanize PPT는 다운스트림 스킬의 템플릿을 복사하지 않고, 사용자 정의 섹션을 삽입하지 않으며, 렌더링된 HTML 또는 PPTX를 후처리하지 않습니다. 수정 사항은 다운스트림 작성자 소스로 반환됩니다. references/guizang-production-brief-orchestrator.md 및 adapters/ppt-master-bridge-notes.md를 참조하세요.
공개 포지셔닝을 위해, Humanize PPT를 네이티브 다운스트림 렌더러와 쌍을 이루는 브리프 오케스트레이터로 설명하세요. 이를 렌더러 자체로 프레이밍하지 말고, 사용자에게 가장 좋은 시각적 스타일을 선택하는 "라우터"로 제시하지 마세요. 해당 결정은 브리프, 다운스트림 스킬의 자체 템플릿 및 인간의 검토에 있습니다. 사용자가 예쁜 템플릿 페이지만 원한다면, 그것은 Humanize의 작업이 아니라 렌더링 스킬의 작업입니다. 선택을 명시하되 금지는 아닙니다.
AST 이론
AST는 Audience-State-Transfer(청중 상태 전이)를 의미합니다.
- 청중(Audience): 누가 듣고 있는지, 그들이 무엇을 알고 있는지, 무엇에 저항하는지, 왜 계속 들을 것인지.
- 상태(State): 덱 전후의 청중 상태, 그리고 전환을 막는 핵심 긴장.
- 전이(Transfer): 청중을 초기 상태에서 원하는 상태로 이동시키는 슬라이드별 경로.
핵심 문장:
PPT는 정보 컨테이너가 아닙니다. PPT는 청중 상태 전이 인공물입니다.
필수 출력 계약
모든 Humanize PPT 실행 시 다음을 생성합니다.
deck_brief.md— 청중, 목표, 긴장, 성공 기준.ast_outline.md— AST 맵 및 내러티브 아크.slide_plan.json— 슬라이드별 계획, 페이지별media: {image, diagram, video}결정 및layout_hint포함.speaker_intent.md— 각 슬라이드에서 발표자가 해야 할 일. 다운스트림 스킬이 네이티브 발표자 노트 및 발표자 셸의 소스로 소비합니다.asset_manifest.md— Humanize의 페이지별 자료 결정: 각 페이지에 어떤 종류의 자산(이미지 / 다이어그램 / 비디오)이 필요한지, 그리고 그 목적.video_slots.json— 선택적 Remotion / HyperFrames / 네이티브 비디오 삽입 계획.style_brief.md— 다운스트림 생산을 위한 시각적 원칙.renderer_registry.json— 이번 실행을 위한 렌더러 기능 스냅샷.router_plan.json— 선택된 기본 렌더러 및 단계별 경로 계획.commands/*.md— 각 다운스트림 전문 에이전트에 대한 제한된 지침.run_manifest.json— 최종 파일 인벤토리, 경로 상태 및 QA 상태.<renderer>-production-prompt.md— 다운스트림 진입점. HTML 경로 외에도ppt-master는ppt-master-production-prompt.md+ 자체 포함ppt-master-source.md및 일회용outputs/ppt-master-handoff/복사본을 생성합니다.outputs/qa/qa_report.md— 첫 번째 패스 QA 게이트(브리프 모드) 또는 반복별 QA 결과(QA 모드).
QA 모드(포스트 렌더)는 반복별로 추가로 다음을 생성합니다.
outputs/qa/fix_prompt.md— 다운스트림 스킬이 실행 가능한 수정 지침.outputs/qa/qa_iteration.json— 라운드 번호, 상태(iterate/pass/needs-human), 해결되지 않은 결과, 이력.
스타일 갤러리 모드(--style-gallery, 아웃라인 사전 게이트)는 대신 다음을 생성하고 중지합니다.
- HTML 경로:
style_gallery.html및 ≥4 커버 항목. PPT Master: 가짜 갤러리 HTML 없음. 스타일 선택은 기본 Confirm UI에 남아 있습니다. style_gallery_plan.json— HTML용 커버 후보 또는 PPT Master용mode: downstream-confirm-ui.commands/style-gallery/<id>.md— HTML용 커버 명령, 또는 기본 게이트용ppt-master-confirm-ui.md.
권장 OPC 워크플로우 (v0.6.4)
O — 아웃라인 + 페이지별 미디어 방향
Humanize PPT: 원자재 → AST 아웃라인 + 페이지별 미디어 결정
(deck_brief.md, ast_outline.md, slide_plan.json, speaker_intent.md,
asset_manifest.md, video_slots.json, style_brief.md)
P — 네이티브 렌더러 호출 (100% 다운스트림)
zh → guizang-ppt-skill (Style A 또는 B, 네이티브; 권장)
en → frontend-slides / beautiful-html-templates (네이티브; 권장)
pptx → ppt-master (네이티브 DrawingML; 명시적 --renderer ppt-master)
기타 HTML-PPT 스킬 → 핫 플러그 가능, 동일한 브리프 계약
Humanize가 제작 프롬프트를 생성하고 중지합니다. 다운스트림
스킬이 덱을 렌더링합니다. Humanize는 템플릿을 복사하지 않고,
SLIDES_HERE / [必填] 대체를 삽입하지 않으며, 렌더링된 HTML에
postMessage 브리지를 추가하지 않습니다.
Q — 렌더링된 인공물에 대한 프레젠테이션 체크업 (演讲体检)
Humanize --qa-from <rendered.html|native.pptx>가 P의 출력을 읽고,
페이지를 아웃라인과 비교하며, 실패 모드
(references/qa-failure-modes.md)를 스캔하고, qa_report.md 및
fix_prompt.md를 작성하며, qa_iteration.json에서 반복을 추적합니다.
제한: 3라운드. 제한 후에도 결과가 남아 있으면 상태가
needs-human으로 전환됩니다.
C — 완료 / 제어
다운스트림 스킬 네이티브 발표자 노트 + 발표자 셸 + 배포
(Humanize는 v0.6.4에서 이를 소유하지 않습니다. 브리프는
다음 에이전트에게 다운스트림 스킬의 자체 형식으로 이를
생성하도록 지시합니다.)
규칙
v0.6.4 불변 규칙 (이것들은 엄격한 규칙입니다. 하나라도 위반하면 v0.6.4 경계를 벗어난 것입니다.)
- Humanize는 브리프 전용입니다. 렌더러 생산 계약을 작성하고 중지합니다. 다운스트림 템플릿이나 최종 HTML/PPTX를 열거나, 복사하거나, 후처리하지 않습니다.
- 다운스트림 렌더러는 100% 네이티브입니다. 다음 에이전트는 다운스트림 스킬의 자체
SKILL.md를 따릅니다. 브리지는 다음 에이전트에게 로드할 스킬, 사용할 스타일(A/B), 선택할 레이아웃, 통과해야 하는 QA 게이트를 알려줍니다. 그러나 템플릿 내부를 전달하지는 않습니다. - 프레젠테이션 체크업은 3회 반복으로 제한됩니다. 라운드 4에 여전히 실패 결과가 있으면
needs-human입니다. 루프는 영원히 회전하지 않으며, 결정을 인간에게 반환합니다. - 발표자 노트 및 발표자 셸 — Humanize는 기본
presenter-shell.html을 생성합니다. 다운스트림이 전체 스테이지를 소유합니다. Humanize는 의미론적 소스(speaker_intent.md)를 소유하며, 이제slide_plan.json+speaker_intent.md에서 직접outputs/presenter/presenter-shell.html을 작성합니다(다운스트림 덱이 존재하지 않더라도 단독으로 사용 가능). 다운스트림 스킬은 네이티브 발표자 노트와 더 완전한 발표자 콘솔을 생성합니다. Humanize는 렌더링된 HTML에postMessage브리지나?slide=URL 매개변수를 삽입하지 않습니다. - 제작 프롬프트는 다운스트림 진입점입니다. 렌더러가 읽어야 하는 모든 지원 인공물의 이름을 지정합니다. PPT Master는 추가로
ppt-master-source.md를 읽습니다. 이 파일은 PPT Master의 시각적 계약을 중복하지 않고 Humanize 페이지 스토리와 노트 의도를 고정합니다.
작업 규칙
- Humanize PPT가 먼저 AST 계약을 생성할 수 있을 때 슬라이드 렌더러가 원자재를 직접 소비하도록 하지 마십시오.
- 다운스트림 스킬을 전체 스테이지 뷰의 소유자로 유지하십시오. Humanize의
presenter-shell.html은 기능적 기준선일 뿐, 네이티브 콘솔을 대체하지 않습니다. - 휴머나이저 도구의 AI 글쓰기 정리 원칙을 흡수하되, Humanize PPT를 텍스트 다듬기로 축소하지 마십시오.
- 검증되지 않은 광범위한 약속보다는 검증된 작은 워크플로우를 선호하십시오.
- 공개 Skill 출시의 경우, 리포지토리를 생성/푸시하고, GitHub에서 로컬로 설치하고, 하나의 안전한 전체 샘플을 실행하고, 브리프 및 프레젠테이션 체크업을 검증된 알려진-양호 체크포인트(
examples/03-codex-guizang-native-ink-classic/)에서 확인한 다음 README 세부 사항을 다듬으십시오. - Agent Teams 개발의 경우, 실제 다운스트림 Skills를 연결하기 전에
router_plan.json,run_manifest.json, 제한된commands/*.md및 렌더러별 제작 프롬프트를 생성하십시오. - WorkBuddy/CodeBuddy 팀 업로드 패키지의 경우, 데모 또는 렌더링된 HTML 출력을 팀 zip으로 패키징하지 마십시오. 업로드 zip은
trading-team과 같은 팀-플러그인 구조를 미러링해야 합니다. 루트 레벨에.codebuddy-plugin/plugin.json,agents/,skills/,rules/,setting.json(선택적avatars/,.workbuddy-plugin/,README.md,settings.json포함).rules/디렉토리에는 프론트매터(description,alwaysApply,enabled,updatedAt,provider)와 사용 가능한 에이전트, 스킬, SOP, 사용 요구 사항을 설명하는<system_reminder>블록이 있는rules/<plugin-name>_rules.md와 같은 시나리오 규칙 파일이 포함되어야 합니다.unzip -l로 루트가index.html/assets/screenshots/source가 아니고 대상 업로더가 명시적으로 래퍼 디렉토리를 요구하지 않는 한 폴더로 래핑되지 않았는지 확인하십시오. - HyperFrames/Remotion 비디오를 PPT 콘텐츠를 대체하는 단일 임베디드 플레이어로 취급하지 마십시오. Humanize PPT 산출물의 경우, 비디오 도구는 자료 생산자입니다. 전환, 설명 클립, 이전/이후 비교, 발표 자료 삽입, 소셜 미리보기 및 특정 슬라이드 요구 사항을 채우는 대체 스틸 이미지입니다. 페이지당
media.video결정(slide_plan.json스키마 참조)은 다운스트림 스킬에 어떤 페이지가 Remotion 클립을 원하는지, 어떤 목적으로, 어떤 지속 시간으로 알려줍니다.
운영 참조
references/guizang-production-brief-orchestrator.md— 표준 브리프 사양:<renderer>-production-prompt.md가 반드시 포함하고 포함하지 말아야 할 사항.references/qa-failure-modes.md(+ 영어 미러references/qa-failure-modes.en.md) — 프레젠테이션 체크업을 위한 실패 모드 카탈로그; 코드 측 진실의 원천은scripts/humanize_ppt_v2.py의FAILURE_MODES.references/style-gallery-spec.md—--style-gallery커버 스타일 게이트.references/renderer-guidance.md— 렌더러별 권장 경로 및 알려진-양호 체크포인트 규칙.references/renderer-verification.md— 프론트매터 한 줄 설명 뒤의 렌더러별 검증 증거.adapters/ppt-master-bridge-notes.md— 네이티브 PPTX 경로 경계 및 OOXML 체크업 계약.SPEC.md— 엔진 기술 사양: CLI 표면, 데이터 흐름, 출력 계약, 스타일 갤러리, 체크업, 미디어 모델, 렌더러 레지스트리.- 모든 참조, 어댑터, 버전 노트 및 도우미 스크립트의 전체 주석 인덱스:
docs/index.md.
로컬 데모
권장되는 안정적인 진입점은 scripts/humanize_ppt.py입니다(버전 관리된 스크립트는 호환성 심으로 남아 있음). 전체 CLI 예제(브리프 모드, 프레젠테이션 체크업, 네이티브 PPTX, 아웃라인 미리보기, 레거시 진입점)는 docs/local-demo.md에 있습니다.
--out 경고: --out을 전용 실행 디렉토리로 지정하십시오. 브리프 모드는 매번 처음부터 다시 빌드하지만, 디렉토리가 없거나 비어 있거나 이전 Humanize PPT 실행(run_manifest.json / style_gallery_plan.json / outline-preview.md / preview-confirmed.json이 루트에 있음)인 경우에만 자동으로 지웁니다. 그렇지 않으면 거부하고 --force를 요청합니다.