open-design/plugins/community/humanize-ppt/SPEC.md

# Humanize PPT — Technical Specification

> Authoritative technical reference for the engine. `SKILL.md` is the
> agent-facing trigger doc; `README.md` / `README.en.md` are the public intro.
> This file specifies *what the engine does and guarantees*. Code-side source
> of truth is `scripts/humanize_ppt_v2.py` (stable entrypoint:
> `scripts/humanize_ppt.py`).
>
> Version: 1.1 · License: MIT · Author: LearnPrompt

## 1. Purpose & boundary

Humanize PPT is a **presentation system** for agent-made HTML presentations and native editable PPTX — built **for the talk**, not just the template. It is broadly compatible with downstream renderers that consume plain markdown + JSON; verified outputs now include both HTML decks and PPT Master's native DrawingML PowerPoint.

Three core capabilities frame everything:

1. **Outline director** — turns raw material (markdown / text / research doc) into an AST outline (audience-state-transfer; every page turn moves the audience forward) and a per-page production brief. Old `.ppt`/`.pptx` files are not read directly — extract their text first (`scripts/pptx_qa.py`), then pass the text as `--source`; a rendered `.pptx` is consumed via `--qa-from`, not `--source`.
2. **Visual-enhancement director** — decides, per page, whether the page needs an image (preferred: `baoyu-image-gen` via the local Codex CLI, no API key; alt: imagegen / imagen / nanobanana-ppt), a deterministic inline SVG diagram, or a video (Remotion), and emits machine-actionable asset slots (`asset_path` + `prompt_hint`).
3. **Presentation checkup + presenter hand-off** — auto-catches "look-only" pages after render (§7) and feeds presenter-mode speaker notes (§1 boundary below).

The downstream template skill renders the beautiful deck; Humanize orchestrates the talk. The hard boundary (the division of labor), unchanged since v0.6.4:

- Humanize never opens a downstream renderer's template.
- Humanize never injects sections into rendered HTML/PPTX.
- Humanize never post-processes rendered HTML/PPTX.
- When a downstream skill updates, Humanize needs zero changes.

Humanize decides **what** and **where**; the downstream skill produces the file. Humanize's own HTML remains zero-dependency working drafts, not decks. PPT Master style selection is delegated to its mandatory native Confirm UI rather than duplicated in Humanize.

## 2. AST — Audience-State-Transfer

- **Audience**: who listens, what they know, what they resist.
- **State**: audience state before/after the deck, plus the blocking tension.
- **Transfer**: the slide-by-slide path from initial to desired state.

Core sentence: *PPT is not an information container; it is an audience state-transfer artifact.* The role arc is `hook → context → tension → method → proof → takeaway` (`ROLE_ARC`).

## 3. CLI surface

```
python3 scripts/humanize_ppt.py --out <dir> [mode flags] [inputs] [renderer/style]
```

### Inputs (one required for brief/outline/gallery modes)
- `--source <path>` — markdown / text raw material. Old `.ppt`/`.pptx` are rejected (fail closed): extract text first via `scripts/pptx_qa.py`, then pass that text. A rendered `.pptx` goes through `--qa-from`, not `--source`.
- `--research-md <path>` — pre-existing research doc (e.g. hv-analysis output). Takes priority over `--source`; the brief writer does not re-parse raw material.
- `--title <str>` — deck title (required for non-QA modes).

### Modes (checked in this order in `main()`)
1. `--qa-from <rendered.html|native.pptx>` → **presentation checkup** (§7). Mutually exclusive with `--source`.
2. `--style-gallery` (v0.9) → **cover-style gate** (§6). Wins over `--preview-outline`.
3. `--preview-outline` → write `outline-preview.md` and stop (review checkpoint).
4. `--confirm-outline` → validate freshness, write `preview-confirmed.json`. Refuses if the outline is missing or the source mtime is newer. Mutually exclusive with `--preview-outline`.
5. (no mode flag) → **brief mode**: write the full output contract (§5) and the renderer's production prompt. Wipes and recreates `--out` first, but only when it is missing, empty, or already a Humanize PPT run (`run_manifest.json` / `style_gallery_plan.json` / `outline-preview.md` / `preview-confirmed.json` at its root) — otherwise refuses unless `--force` is passed.

### Renderer / style selection
- `--renderer {auto,guizang,beautiful-html-templates,html-ppt,frontend-slides,ppt-master}` (default `auto`). `ppt-master` is explicit unless `--ppt-master-template` forces it.
- `--guizang-style {A,B}` — A = flexible (5 themes), B = Swiss-locked (4 accents). A requires `--guizang-theme {ink-classic,indigo-porcelain,forest-ink,kraft-paper,dune}`; B requires `--guizang-accent {ikb,lemon-yellow,lemon-green,safety-orange}`.
- `--selected-template <slug>`, `--occasion`, `--mood`, `--preview-count` — beautiful-html-templates selection hints.
- `--gallery-count N` (v0.9) — style-gallery candidate count, minimum and default 4, capped at the candidates defined for the renderer.
- `--ppt-master-template <raw.pptx>` — forces PPT Master's native `template-fill-pptx` route.
- `--ppt-master-repo`, `--ppt-master-python` (verified Python ≥3.10), `--ppt-master-format`, `--ppt-master-project-name`, `--ppt-master-visual-style` — downstream runtime/location/project/confirmation recommendations.
- `--ppt-master-native-objects`, `--ppt-master-transition`, `--ppt-master-animation`, `--ppt-master-animation-trigger`, `--ppt-master-visual-review` — native export and explicit visual-review settings. On raw-template fill, only page transitions are written; existing native objects/animations are preserved and image replacement or new object animation is reported as a template-fill v1 boundary.

### Adapters & flags
`--presenter-adapter`, `--export-adapter`, `--presenter`, `--no-render`, `--skip-install-check`, `--max-qa-iterations N` (default 3), `--beautiful-repo`, `--no-beautiful-auto-clone`, `--force` (brief mode only — wipe a non-empty `--out` that is not already a Humanize PPT run).

## 4. Data flow

```
raw material
   │  read_source → detect_language → build_slide_plan (per-role + decide_media)
   ▼
slide_plan.json  ──(--style-gallery)──▶  ≥4 cover-only render commands + style_gallery.html picker  ──pick──┐
   │                                                                                                         │
   │  (--preview-outline) ──▶ outline-preview.md ──(--confirm-outline)──▶ preview-confirmed.json             │ reinjection_command
   ▼                                                                                                         ▼
brief mode: deck_brief / ast_outline / slide_plan / speaker_intent / asset_manifest / video_slots / style_brief
   │  + <renderer>-production-prompt.md (per-page media block + media production guidance)
   ▼
downstream skill renders natively  ──▶  rendered HTML or native PPTX
   │
   ▼
--qa-from <rendered.html|native.pptx>  ──▶  presentation checkup (≤3 rounds): qa_report.md / fix_prompt.md / qa_iteration.json
```

The brief is plain markdown + JSON. Verified recommendations: zh HTML → `guizang-ppt-skill`; en HTML → `frontend-slides` / `beautiful-html-templates`; native editable PowerPoint → `ppt-master`.

## 5. Output contract (brief mode)

Every brief run writes, into `--out`:

1. `deck_brief.md` — audience, goal, tension, success criteria.
2. `ast_outline.md` — AST map and narrative arc.
3. `slide_plan.json` — per-slide plan; schema `contracts/slide-plan.schema.json`.
4. `speaker_intent.md` — per-slide speaker action (downstream's source for native speaker notes).
5. `asset_manifest.md` — per-page material decisions.
6. `video_slots.json` — optional Remotion / HyperFrames insertion plan.
7. `style_brief.md` — visual principle for downstream production.
8. `renderer_registry.json` — renderer capability snapshot for this run.
9. `router_plan.json` — selected primary renderer + staged routes.
10. `commands/*.md` — bounded instructions per downstream specialist.
11. `<renderer>-production-prompt.md` — the brief the next agent consumes.
12. `run_manifest.json`, `outputs/qa/qa_report.md`, `outputs/qa/fix_list.md`.

PPT Master additionally writes `ppt-master-source.md` and disposable `outputs/ppt-master-handoff/` copies. The former freezes Humanize's semantic page contract; the latter lets PPT Master's main route obey its `import-sources --move` rule without moving the user's original file.

## 6. Style gallery (v0.9) — the cover-style gate

`--style-gallery` precedes the outline: it lets the human compare ≥4 covers side by side before committing to a style. Humanize emits the spec; the downstream skill renders the covers.

For the resolved renderer it takes the first `N` of `STYLE_GALLERY_CANDIDATES[renderer]` (guizang spans Style A themes + a Style B Swiss accent so the four covers are visually distinct) and writes:

- `commands/style-gallery/<id>.md` — a **cover-only** render command: render only S01 in that style → `outputs/style-gallery/<id>/cover.{html,png}`. Not a full deck.
- `style_gallery.html` — zero-dependency single-file picker stitching the covers via relative-path `<iframe>`s, each with its label, description, and re-injection command. A not-yet-rendered cover shows the frame backdrop plus an always-visible caption — no faked thumbnail.
- `style_gallery_plan.json` — per-candidate `id`, `label`, `description`, `cli`, `command_file`, `cover_html`, `cover_png`, `reinjection_command`.

After picking, the human runs the candidate's `reinjection_command`, which carries `--renderer` + style args into the normal outline → brief flow. Spec: `references/style-gallery-spec.md`.

PPT Master exception: `--renderer ppt-master --style-gallery` writes `style_gallery_plan.json` with `mode: downstream-confirm-ui` and `commands/style-gallery/ppt-master-confirm-ui.md`. It does not emit fake cover artifacts because PPT Master's mandatory Stage 1 already owns the visual-style catalog and native preview SVGs.

**WebGL static-screenshot trap**: Style A covers use a WebGL hero canvas whose PNG can capture blank (canvas paints after load). Each Style A cover command warns to treat `cover.html` as truth, delay screenshots ≥1.5s, and treat a `cover.png` under 20KB as a failed capture. See §7 and `references/qa-failure-modes.md`.

## 7. Presentation checkup (`--qa-from`)

Per-page review of rendered HTML or native PPTX against the outline — grades the outline, not beauty. Capped at `--max-qa-iterations` (default 3); unresolved findings at the cap flip `qa_status` to `needs-human`.

- `FAILURE_MODES` (in `humanize_ppt_v2.py`) is the code-side source of truth; the human-readable catalog is `references/qa-failure-modes.md` (+ English mirror `references/qa-failure-modes.en.md`), matched by id.
- Each round: `run_checks` → findings `[{id, severity, pages, evidence}]` → `qa_report.md` (human) + `fix_prompt.md` (downstream-actionable) + `qa_iteration.json` (round state).
- PPTX dispatch uses `scripts/pptx_qa.py::inspect_pptx`: OOXML package integrity, page count, placeholder residue, editable shapes, speaker notes, AST/notes drift, relationships, transitions, and requested native table/chart objects.
- Failure classes the static scan can't catch (text overflow, badge occlusion, the WebGL static-screenshot trap) are listed but not packaged as `FAILURE_MODES` rules — catalog discipline: only rules that exist in code.

## 8. Per-page media model

`build_slide_plan` calls `decide_media(role, title, message, visible_content, slide_id)`, which applies `ROLE_MEDIA_POLICY` per role and produces, for each of `image` / `diagram` / `video`:

- `needed` (bool), `kind` (e.g. `gpt-photo`, `screenshot`, `svg-html`, `remotion-clip`), and for `video` a `duration_s`.
- v0.6.7 machine-actionable fields: `asset_path` (where to write), `prompt_hint` (what to generate), plus `aspect_ratio` / `max_size_kb` for images.

A media slot **with** `asset_path` is an executable task; **without** one it is a label only. The three brief writers share `_format_per_page_media_block` (surfaces the slots) and `_media_production_guidance` (maps each `kind` to a concrete, hot-pluggable generator skill). Schema: `contracts/slide-plan.schema.json`.

## 9. Renderer registry

`registry/renderer_registry.json` snapshots renderer capability. `support_level` values, updated only on real results (宁空不摆拍):

- `guizang` → `full`
- `beautiful-html-templates` → `full` (brief exit + real Neo-Grid checkup + 5 English-specific modes)
- `frontend-slides` → `full` (brief exit + real frontend-slides checkup + the same 5 English-specific modes)
- `ppt-master` → `full` (main + raw template-fill real routes, 11 PPTX-specific modes, real 10-page main export and 5-page template-fill export/checkup on 2026-07-10)

## 10. Versioning & tests

- `VERSION` in `humanize_ppt_v2.py`. Version history under `docs/versions/`.
- Tests in `tests/` (pytest); run `python3 -m pytest -q`. v0.9 adds `tests/test_v090_style_gallery.py`.
- The Luban discipline for this project: 验料 (confirm baseline green) → 访行 (read the existing flow) → 过尺 (run pytest) → 慢刨 (implement) → 回炉 (registry / SKILL.md / version / marketplace). Release actions (push / tag / marketplace bump) are gated on human review.