/nature-image2ppt

name: nature-image2ppt
description: "Reconstruct slide images, screenshots, scanned PDFs, or image-only PPTX files as object-level editable PowerPoint. Use for 图片转可编辑PPT、截图还原PPT and diagram reconstruction; not authoring a new deck from research notes."

Nature Image2PPT

Use this directory as the complete runtime. Run deterministic actions only through:

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

Use Python 3.10 or later with `requirements.txt` installed. When a dedicated environment exists, substitute `<image2ppt-root>/.venv/bin/python` on macOS/Linux or `<image2ppt-root>/.venv/Scripts/python.exe` on Windows for every `python` command below. Do not continue after a failed `doctor`; install only the reported missing dependency, then rerun it.

Do not discover or invoke another Skill, CLI, Prompt, Schema, module, or state machine.

Read the local contracts progressively

Always read `references/workflow.md`. Read `references/runtime-dependencies.md` only for setup or `doctor` failures, and read `references/ocr-text-hints-contract.md` only when choosing or troubleshooting OCR.

Before writing a page manifest, read `references/page-decision-tree.md` and `references/manifest-schema.md`. Add only the references needed by that page:

• structured or compound page: `references/region-decomposition.md` and

`references/object-routing.md`;

• arrows: `references/manifest-arrow-extension.md`;
• raster assets or image-backend work: `references/assets-provenance-contract.md`.

Before accepting or delivering output, read `references/qa-contract.md`.

Preserve the single source of truth

• Treat `page_jobs.json` as the only page-state source.
• Treat each `pages/page_NNN/manifest.json` as the only page-content source.
• Treat `deck_manifest.json` as the final-assembly source.
• Use only `prepare`, `run next/dispatch/record/reset/hints/finalize`, and the

page commands in the local CLI for stateful lifecycle operations.

• Keep semantic-region evidence in `manifest.json.image2ppt_region_decomposition`.
• Never create a second job file, reconstruction plan, OCR normalizer, page

controller, packager, or finalize path.

• Let supplemental QA report failures; never let it mutate lifecycle state.

Keep every write inside its owner directory

• Page build, validation, hints, and QA may read and write only inside that page

directory. Manifest paths, recorded assets, formulas, reports, previews, and `--out` overrides must not use `..`, symlinks, or absolute paths to escape it. The sole external-input exception is an explicit image-tool result supplied to `image import` or as `process-sheet --asset-sheet-source`; it is copied into the page before becoming a build dependency.

• Run-level manifests and final outputs must remain inside the prepared run

directory. Finalization rebuilds into a same-directory temporary file and publishes it atomically only after a successful build.

• Treat any boundary rejection as a hard failure; do not copy the rejected file

back into scope and present it as runtime output.

Preserve pre-migration behavior

• Treat self-containment as a path/import/entrypoint migration, not a redesign of

reconstruction behavior.

• Generate each worker Prompt from the complete local base layer plus the preserved

Image2PPT profile layer. Do not condense, reinterpret, or replace either layer.

• Prefer the previously validated visual strategy when several routes satisfy the

contracts. Keep simple measured objects native and retain bounded complex assets wherever a native redraw would reduce fidelity.

• Never re-author an accepted baseline page merely to prove runtime independence.

Run the workflow

Image backend selection

Use `builtin-imagegen` when the agent runtime exposes `image_gen.imagegen`; it is the preferred backend because the worker can inspect edit inputs and import the explicit local result. Use the CLI image contract only when the built-in tool is unavailable, errors, cannot read an input, or returns no valid local output. A missing optional argument such as model, mask, size, quality, or output path never authorizes fallback. Record the actual producer and permitted fallback reason in `imagegen-jobs.json`.

The CLI image contract is provider-neutral at the transport boundary. Select `codex-oauth` only for GPT Image model ids. Select `openai-compatible-api` for any provider-specific model whose endpoint implements the OpenAI Images-compatible `/images/generations` and/or `/images/edits` schema. Do not infer the image backend from the task's language model. Use an explicit backend when provenance matters; `auto` uses Codex OAuth only for compatible GPT Image ids and otherwise selects the configured API without sending Codex OAuth credentials to third parties.

1. Preflight and OCR choice

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

Use Baidu AI Studio `PADDLE_OCR_TOKEN` when configured. If it is absent, tell the user once that the local `builtin-ink` fallback measures text geometry but does not recognize characters; offer the configuration path in `references/ocr-text-hints-contract.md`. Respect an offline-only choice.

2. Prepare one run

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

To pin a configured third-party provider/model for auditable provenance, prepare with `--image-backend openai-compatible-api`. The run contract records the exact `IMAGE2PPT_IMAGE_MODEL` from the active project config or environment; it does not substitute a GPT Image default merely because no `--model` flag was passed.

Use `--no-text-hints` only when OCR processing is intentionally disabled. Regenerate hints without creating a new run when needed:

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

3. Advance and claim pages

python <image2ppt-root>/cli/imag