git:20260818.ffd2674 to git:20260818.8349383

58 added, 21 removed. Audit A to A.

---

name: nature-image2ppt

description: Convert slide images, screenshots, scanned PDFs, and image-only PPT/PPTX files into high-fidelity object-level editable PowerPoint, including semantic-region mixed reconstruction, measured flowcharts and knowledge graphs, native circle nodes and connectors, single-object thin and filled arrows, speaker-note preservation, and rendered QA. Use for 图片转可编辑PPT、截图还原PPT、扫描PDF恢复、图片型PPTX转换、流程图/知识图谱/复合图形/箭头重建; not for authoring a new deck from notes.

---

# Nature Image2PPT

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

```bash

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

```

- For this project-local Windows deployment, substitute

- `<image2ppt-root>/.venv/Scripts/python.exe` for every `python` command below when

- that interpreter exists. It contains the pinned runtime dependencies and avoids

- depending on the user's global Python environment.

+ 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

- Before a run, read:

+ ## Read the local contracts progressively

- - `references/workflow.md`

- - `references/runtime-dependencies.md`

- - `references/ocr-text-hints-contract.md`

+ 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 reconstructing a page, also read:

+ Before writing a page manifest, read `references/page-decision-tree.md` and

+ `references/manifest-schema.md`. Add only the references needed by that page:

- - `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`

+ - 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`.

### 1. Preflight and OCR choice

```bash

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

```bash

python <image2ppt-root>/cli/image2ppt/cli.py prepare <input...> \

--out-root output/image2ppt --image-backend builtin-imagegen

```

Use `--no-text-hints` only when OCR processing is intentionally disabled. Regenerate

hints without creating a new run when needed:

```bash

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

```

### 3. Advance and claim pages

```bash

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>

```

For exactly one page, claim it with `--local` and reconstruct it in the current

agent. For multiple pages, dispatch independent page workers up to the capacity in

`page_jobs.json`. Do not reset a live worker merely because it is slow.

### 4. Reconstruct and gate each page

Plan a structured page as 3–5 semantic regions and route each region independently.

Use measured compound diagrams: measure every node, relation, and protected anchor. Keep measurable

circles, cards, straight/dashed relations, and simple connectors native. Use bounded

transparent assets only for complex local subparts.

Represent a thin arrow as one connector with its arrowhead on the same object.

Represent a filled arrow as one Arrow AutoShape, with centered label text inside the

same object. Never construct an ordinary arrow from a line plus triangle and never

flatten a whole knowledge graph into one image.

+ Write new page manifests with `schema_version: 2`. Use structured

+ `visual_inventory` items with explicit `kind` and `representation` values, and

+ write a concrete `quality_evidence` observation for every required quality check.

+ Formula rendering is a hard gate: a missing engine, converter, or failed compile

+ must keep the page failed unless the user explicitly approves that exact formula

+ exception and the manifest records both `user_approved_exception: true` and a

+ concrete `approval_note`.

The worker Prompt performs the deterministic sequence. Its final gates are:

```bash

python <image2ppt-root>/cli/image2ppt/cli.py page build <page-dir>

python <image2ppt-root>/scripts/run_image2ppt_qa.py <page-dir>

- # inspect source.png against render/rendered.png, repair, then:

+ # The first run writes visual-review-evidence.template.json and remains pending.

+ # Inspect source.png against render/rendered.png, copy and complete the template

+ # as visual-review-evidence.json, repair if needed, then:

python <image2ppt-root>/scripts/run_image2ppt_qa.py <page-dir> \

--visual-review-status reviewed \

- --visual-review-notes "<specific observations checked>"

+ --visual-review-evidence <page-dir>/visual-review-evidence.json

python <image2ppt-root>/cli/image2ppt/cli.py page contact-sheet <page-dir>

```

+ The evidence file must cover the current source/render hashes and every required

+ check with a specific observation. `--visual-review-notes` is optional context and

+ cannot substitute for the evidence file.

Record only after standard validation and the Image2PPT region, arrow, and rendered

gates pass:

```bash

python <image2ppt-root>/cli/image2ppt/cli.py run record \

<run-dir> --page <page-id> --agent-id <id>

```

Use the same `run reset` → dispatch → record lifecycle to repair rejected pages.

### 5. Finalize and revalidate the rebuilt deck

When `run next` reports `finalize`, run:

```bash

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

python <image2ppt-root>/scripts/run_final_image2ppt_qa.py <run-dir>

- # inspect every rendered slide against its source, repair manifests if needed, then:

+ # The first run writes final/visual-review-evidence.template.json and remains pending.

+ # Inspect every rendered slide, complete final/visual-review-evidence.json, then:

python <image2ppt-root>/scripts/run_final_image2ppt_qa.py <run-dir> \

--visual-review-status reviewed \

- --visual-review-notes "<specific checks covering every slide>"

+ --visual-review-evidence <run-dir>/final/visual-review-evidence.json

```

Finalize rebuilds from page manifests, preserves source speaker notes, validates the

package, and writes the output recorded by `deck_manifest.json`. Final QA reapplies

manifest arrows, verifies arrow atomicity and compound structure, renders every

slide, checks speaker-note integrity, and writes `final/image2ppt_qa.json`.

## Deliver

Return the final PPTX path, standard final validation, and

`final/image2ppt_qa.json`. Report which complex visuals remain replaceable bitmap

assets. Do not call the deck complete while any page/final gate is pending or failed.