nature-image2ppt

Nature Image2PPT

이 디렉토리를 완전한 런타임으로 사용하세요. 결정적 동작은 다음을 통해서만 실행하세요:

python <image2ppt-root>/cli/image2ppt/cli.py <command> ...

Python 3.10 이상과 requirements.txt 설치가 필요합니다. 전용 환경이 있는 경우, 아래 모든 python 명령에서 macOS/Linux의 경우 <image2ppt-root>/.venv/bin/python을, Windows의 경우 <image2ppt-root>/.venv/Scripts/python.exe로 대체하세요. doctor가 실패한 후에는 계속하지 말고; 보고된 누락된 종속성만 설치한 후 다시 실행하세요.

다른 스킬, CLI, 프롬프트, 스키마, 모듈 또는 상태 머신을 발견하거나 호출하지 마세요.

지역 계약을 점진적으로 읽으세요

항상 references/workflow.md를 읽으세요. 설정 또는 doctor 실패 시에만 references/runtime-dependencies.md를 읽고, OCR을 선택하거나 문제 해결 시에만 references/ocr-text-hints-contract.md를 읽으세요.

페이지 매니페스트를 작성하기 전에 references/page-decision-tree.md와 references/manifest-schema.md를 읽으세요. 해당 페이지에 필요한 참조만 추가하세요:

• 구조화된 또는 복합 페이지: references/region-decomposition.md 및 references/object-routing.md;
• 화살표: references/manifest-arrow-extension.md;
• 래스터 자산 또는 이미지 백엔드 작업: references/assets-provenance-contract.md.

출력을 수락하거나 전달하기 전에 references/qa-contract.md를 읽으세요.

단일 진실 공급원을 유지하세요

• page_jobs.json을 유일한 페이지 상태 소스로 취급하세요.
• 각 pages/page_NNN/manifest.json을 유일한 페이지 콘텐츠 소스로 취급하세요.
• deck_manifest.json을 최종 어셈블리 소스로 취급하세요.
• 상태 저장 라이프사이클 작업에는 prepare, run next/dispatch/record/reset/hints/finalize 및 로컬 CLI의 페이지 명령만 사용하세요.
• 의미론적 영역 증거를 manifest.json.image2ppt_region_decomposition에 보관하세요.
• 두 번째 작업 파일, 재구성 계획, OCR 정규화기, 페이지 컨트롤러, 패키저 또는 최종화 경로를 생성하지 마세요.
• 보조 QA가 실패를 보고하도록 하세요. 절대 라이프사이클 상태를 변경하게 하지 마세요.

모든 쓰기 작업을 해당 소유 디렉토리 내에 유지하세요

• 페이지 빌드, 유효성 검사, 힌트 및 QA는 해당 페이지 디렉토리 내에서만 읽고 쓸 수 있습니다. 매니페스트 경로, 기록된 자산, 수식, 보고서, 미리보기 및 --out 재정의는 .., 심볼릭 링크 또는 절대 경로를 사용하여 이를 벗어날 수 없습니다. 유일한 외부 입력 예외는 image import 또는 process-sheet --asset-sheet-source에 제공된 명시적 이미지 도구 결과이며, 이는 빌드 종속성이 되기 전에 페이지에 복사됩니다.
• 실행 수준 매니페스트 및 최종 출력은 준비된 실행 디렉토리 내에 유지되어야 합니다. 최종화는 동일한 디렉토리의 임시 파일로 재빌드되고 성공적인 빌드 후에만 원자적으로 게시됩니다.
• 경계 거부를 하드 실패로 처리하십시오. 거부된 파일을 범위 내로 다시 복사하여 런타임 출력으로 제시하지 마십시오.

사전 마이그레이션 동작을 유지하세요

• 자체 포함을 경로/가져오기/진입점 마이그레이션으로 취급하고 재구성 동작의 재설계로 취급하지 마십시오.
• 각 작업자 프롬프트를 완전한 로컬 기본 계층과 보존된 Image2PPT 프로필 계층에서 생성하십시오. 어느 계층도 압축, 재해석 또는 대체하지 마십시오.
• 여러 경로가 계약을 충족할 때 이전에 검증된 시각적 전략을 선호하십시오. 간단한 측정 객체는 네이티브로 유지하고, 네이티브 재그리기가 충실도를 떨어뜨리는 경우 경계가 있는 복잡한 자산은 보유하십시오.
• 런타임 독립성을 증명하기 위해 수락된 기준선 페이지를 다시 작성하지 마십시오.

워크플로 실행

이미지 백엔드 선택

에이전트 런타임이 image_gen.imagegen을 노출하는 경우 builtin-imagegen을 사용하십시오. 작업자가 편집 입력을 검사하고 명시적 로컬 결과를 가져올 수 있으므로 선호되는 백엔드입니다. 기본 제공 도구를 사용할 수 없거나, 오류가 발생하거나, 입력을 읽을 수 없거나, 유효한 로컬 출력을 반환하지 않는 경우에만 CLI 이미지 계약을 사용하십시오. 모델, 마스크, 크기, 품질 또는 출력 경로와 같은 선택적 인수가 누락되어도 폴백이 허용되지 않습니다. 실제 생성자와 허용된 폴백 이유를 imagegen-jobs.json에 기록하십시오.

CLI 이미지 계약은 전송 경계에서 공급자 중립적입니다. GPT Image 모델 ID에 대해서만 codex-oauth를 선택하십시오. 엔드포인트가 OpenAI Images 호환 /images/generations 및/또는 /images/edits 스키마를 구현하는 공급자별 모델에 대해 openai-compatible-api를 선택하십시오. 작업의 언어 모델에서 이미지 백엔드를 유추하지 마십시오. 출처가 중요한 경우 명시적 백엔드를 사용하십시오. auto는 호환되는 GPT Image ID에 대해서만 Codex OAuth를 사용하고, 그렇지 않으면 Codex OAuth 자격 증명을 제3자에게 보내지 않고 구성된 API를 선택합니다.

1. 사전 점검 및 OCR 선택

python <image2ppt-root>/cli/image2ppt/cli.py doctor --json

구성된 경우 Baidu AI Studio PADDLE_OCR_TOKEN을 사용하십시오. 없으면 로컬 builtin-ink 폴백이 텍스트 형상은 측정하지만 문자를 인식하지는 못한다는 사실을 사용자에게 한 번 알리고 references/ocr-text-hints-contract.md의 구성 경로를 제공하십시오. 오프라인 전용 선택을 존중하십시오.

2. 하나의 실행 준비

python <image2ppt-root>/cli/image2ppt/cli.py prepare <input...> \
  --out-root output/image2ppt --image-backend builtin-imagegen

감사 가능한 출처를 위해 구성된 제3자 공급자/모델을 고정하려면 --image-backend openai-compatible-api로 준비하십시오. 실행 계약은 활성 프로젝트 구성 또는 환경의 정확한 IMAGE2PPT_IMAGE_MODEL을 기록합니다. --model 플래그가 전달되지 않았다고 해서 GPT Image 기본값을 대체하지 않습니다.

OCR 처리가 의도적으로 비활성화된 경우에만 --no-text-hints를 사용하십시오. 필요할 때 새 실행을 만들지 않고 힌트를 다시 생성하려면:

python <image2ppt-root>/cli/image2ppt/cli.py run hints <run-dir>

3. 페이지 진행 및 할당

python <image2ppt-root>/cli/image2ppt/cli.py run next <run-dir> --json
python <image2ppt-root>/scripts/build_page_worker_prompt.py \
  <run-dir> --page <page-id> --out <absolute-page-dir>/worker-prompt.md
python <image2ppt-root>/cli/image2ppt/cli.py run dispatch \
  <run-dir> --page <page-id> --agent-id <id> --prompt-file <absolute-prompt>

정확히 한 페이지의 경우 --local로 할당하고 현재 에이전트에서 재구성하십시오. 여러 페이지의 경우 page_jobs.json의 용량까지 독립적인 페이지 작업자들을 디스패치하십시오. 느리다고 해서 살아있는 작업자를 재설정하지 마십시오.

4. 각 페이지 재구성 및 게이트 통과

구조화된 페이지를 3~5개의 의미론적 영역으로 계획하고 각 영역을 독립적으로 라우팅하십시오. 측정된 복합 다이어그램을 사용하십시오: 모든 노드, 관계 및 보호된 앵커를 측정하십시오. 측정 가능한 원, 카드, 직선/점선 관계 및 간단한 커넥터는 네이티브로 유지하십시오. 복잡한 로컬 하위 부분에 대해서만 경계가 있는 투명 자산을 사용하십시오.

가는 화살표는 화살표 머리가 동일한 객체에 있는 하나의 커넥터로 표현하십시오. 채워진 화살표는 동일한 객체 내에 중앙에 레이블 텍스트가 있는 하나의 화살표 자동 도형으로 표현하십시오. 일반 화살표를 선과 삼각형으로 구성하지 말고 전체 지식 그래프를 하나의 이미지로 평탄화하지 마십시오.

schema_version: 2로 새 페이지 매니페스트를 작성하십시오. 명시적 kind 및 representation 값이 있는 구조화된 visual_inventory 항목을 사용하고 모든 필수 품질 검사에 대해 구체적인 quality_evidence 관찰을 작성하십시오. 수식 렌더링은 하드 게이트입니다: 누락된 엔진, 변환기 또는 컴파일 실패는 사용자가 명시적으로 해당 수식 예외를 승인하고 매니페스트가 user_approved_exception: true와 구체적인 approval_note를 모두 기록하지 않는 한 페이지를 실패 상태로 유지해야 합니다.

작업자 프롬프트가 결정적 시퀀스를 수행합니다. 최종 게이트는 다음과 같습니다:

python <image2ppt-root>/cli/image2ppt/cli.py page build <page-dir>
python <image2ppt-root>/scripts/run_image2ppt_qa.py <page-dir>
# 첫 번째 실행은 visual-review-evidence.template.json을 작성하고 대기 상태로 유지됩니다.
# source.png를 render/rendered.png와 비교하고 템플릿을 복사하여 visual-review-evidence.json으로 완성한 후 필요시 수리한 다음:
python <image2ppt-root>/scripts/run_image2ppt_qa.py <page-dir> \
  --visual-review-status reviewed \
  --visual-review-evidence <page-dir>/visual-review-evidence.json
python <image2ppt-root>/cli/image2ppt/cli.py page contact-sheet <page-dir>

증거 파일은 현재 소스/렌더 해시와 특정 관찰을 포함한 모든 필수 검사를 다루어야 합니다. --visual-review-notes는 선택적 컨텍스트이며 증거 파일을 대체할 수 없습니다.

표준 유효성 검사와 Image2PPT 영역, 화살표 및 렌더링 게이트를 통과한 후에만 기록하십시오:

python <image2ppt-root>/cli/image2ppt/cli.py run record \
  <run-dir> --page <page-id> --agent-id <id>

거부된 페이지를 수리하려면 동일한 run reset → dispatch → record 라이프사이클을 사용하십시오.

5. 재구성된 덱 최종화 및 재검증

run next가 finalize를 보고하면 다음을 실행하십시오:

python <image2ppt-root>/cli/image2ppt/cli.py run finalize <run-dir>
python <image2ppt-root>/scripts/run_final_image2ppt_qa.py <run-dir>
# 첫 번째 실행은 final/visual-review-evidence.template.json을 작성하고 대기 상태로 유지됩니다.
# 렌더링된 모든 슬라이드를 검사하고 final/visual-review-evidence.json을 완성한 다음:
python <image2ppt-root>/scripts/run_final_image2ppt_qa.py <run-dir> \
  --visual-review-status reviewed \
  --visual-review-evidence <run-dir>/final/visual-review-evidence.json

최종화는 페이지 매니페스트에서 재빌드하고, 소스 발표자 노트를 보존하며, 패키지의 유효성을 검사하고 deck_manifest.json에 기록된 출력을 씁니다. 최종 QA는 매니페스트 화살표를 다시 적용하고, 화살표 원자성과 복합 구조를 확인하고, 모든 슬라이드를 렌더링하고, 발표자 노트 무결성을 확인하고 final/image2ppt_qa.json을 작성합니다.

전달

최종 PPTX 경로, 표준 최종 유효성 검사 및 final/image2ppt_qa.json을 반환하십시오. 대체 가능한 비트맵 자산으로 남아 있는 복잡한 시각적 요소를 보고하십시오. 페이지/최종 게이트가 보류 중이거나 실패한 상태에서 덱이 완료되었다고 간주하지 마십시오.