Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs(technical-design): sync architecture doc with landed capabilities

hugohe31a9b232f4045
diff --git a/docs/technical-design.md b/docs/technical-design.md
index f846d373..cb6ed652 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -15,22 +15,25 @@ The generated PPTX is a **design draft**, not a finished product. Think of it li
## System Architecture
```
-User Input (PDF/DOCX/XLSX/URL/Markdown)
+User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)
↓
[Source Content Conversion] → source_to_md/pdf_to_md.py / doc_to_md.py / excel_to_md.py / ppt_to_md.py / web_to_md.py
+ ├── Markdown is the content contract
+ └── PPTX intake writes analysis/<stem>.identity.json, <stem>.slide_library.json, source_profile.json
↓
[Create Project] → project_manager.py init <project_name> --format <format>
↓
-[Template (optional)] — default: skip, proceed with free design
- User names a template: copy template files into the project
- Need a new global template: use /create-template workflow separately
+[Template / Brand / Layout (optional)] — default: skip, proceed with free design
+ Trigger only on an explicit template directory path containing design_spec.md kind: brand/layout/deck
+ Raw PPTX template requests route to template-fill; reusable SVG templates are created by create-template first
↓
-[Strategist] - Eight Confirmations & Design Specifications → design_spec.md + spec_lock.md
+[Strategist] - two-tier Eight Confirmations & Design Specifications → design_spec.md + spec_lock.md
↓
-[Image Acquisition] (when any row in the resource list needs AI generation or web search)
+[Image Acquisition] (when any resource row needs AI generation, web search, or slicing)
↓
[Executor]
- ├── Visual construction: generate all SVG pages → svg_output/
+ ├── Live preview starts and stays available during generation
+ ├── Visual construction: generate SVG pages sequentially → svg_output/
├── [Quality Check] svg_quality_checker.py (mandatory — must pass with 0 errors)
└── Notes generation: complete speaker notes → notes/total.md
↓
@@ -50,6 +53,14 @@ Output:
└── svg_output/ ← Archived Executor SVG source (rerun finalize_svg → svg_to_pptx to rebuild)
```
+Direct PPTX workflows intentionally bypass this SVG route:
+
+| Workflow | Input role | Output mechanics | Why it is separate |
+|---|---|---|---|
+| `template-fill-pptx` | a native PPTX template deck plus new material | clone selected slides and patch text / tables / charts in OOXML | preserves the user's PowerPoint slide shells instead of converting them into SVG |
+| `native-enhance-pptx` | a finished PPTX whose layout/content should remain stable | patch notes, narration, timings, and transitions directly in OOXML | appends native enhancements without regenerating design |
+| `beautify-pptx` | an existing PPTX whose page count/order/wording must stay 1:1 | extract source facts, regenerate a native deck through the SVG pipeline | changes layout and hierarchy only; it is not direct in-place editing |
+
---
## Technical Pipeline
@@ -59,7 +70,7 @@ Output:
The full flow breaks into three stages:
**Stage 1 — Content Understanding & Design Planning**
-Source documents (PDF/DOCX/URL/Markdown) are converted to structured text. The Strategist role analyzes the content, plans the slide structure, and confirms the visual style, producing a complete design specification.
+Source documents (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text) are converted into the content and analysis facts the Strategist needs. The Strategist role analyzes the material, reads relevant `analysis/` artifacts, plans the slide structure, and confirms the visual style, producing a complete design specification.
**Stage 2 — AI Visual Generation**
The Executor role generates each slide as an SVG file. The output of this stage is a **design draft**, not a finished product.
@@ -100,17 +111,44 @@ SVG is also the only format that simultaneously satisfies every role in the pipe
## Source Content Conversion
-Source documents (PDF / DOCX / EPUB / XLSX / PPTX / web pages) are normalized into Markdown before the pipeline starts — this is the source of truth Strategist reads from. Two design choices shape the converters:
+Source documents (PDF / DOCX / EPUB / XLSX / PPTX / web pages) are normalized before Strategist work starts, but there is no single "everything becomes Markdown and nothing else matters" channel anymore. The current design has two fact channels with explicit ownership:
+
+| Channel | Artifact | Owner | Used for |
+|---|---|---|---|
+| Content contract | `sources/<stem>.md` | `source_to_md/*` converters | text, tables, chart values, citations, and source narrative |
+| Structured analysis | `analysis/*.json` / `analysis/*.csv` | intake and analysis tools | PPTX identity, slide geometry, native tables/charts, image dimensions/colors/subjects |
+
+For PPTX sources, `project_manager.py import-sources` runs both `ppt_to_md.py` and `pptx_intake.py`. The Markdown remains the content source for the main generation pipeline. The intake bundle writes `<stem>.identity.json`, `<stem>.slide_library.json`, and merges a compact multi-deck index into `analysis/source_profile.json`. Strategist reads the compact index for source facts and opens raw per-deck artifacts only when a workflow needs them. That distinction matters: the main pipeline may rethink page count and story, while `template-fill` and `beautify` promote parts of the same intake facts into stronger constraints.
+
+Converter-generated image assets are also normalized. Companion `<stem>_files/` directories are imported into the project `images/` pool, `image_manifest.json` is merged by filename, and Markdown asset references are rewritten when imported names change. Office vector images (`.emf` / `.wmf`) are first-class runtime assets: they are not rasterized during intake, `finalize_svg.py` leaves them external for the native path, and `svg_to_pptx.py` embeds them as Office vector media so CJK fonts and vector detail are not lost.
+
+Two converter design choices still shape the system:
-**Native-Python first, external binaries as fallback.** Common formats are handled by pure-Python wheels; pandoc is only invoked for the long tail of niche formats. Forcing every user to install system binaries they may not have permission for is a usability tax that doesn't pay off when 95% of inputs are docx / pdf / html.
+**Native-Python first, external binaries as fallback.** Common formats are handled by pure-Python wheels; pandoc is only invoked for the long tail of niche formats. Forcing every user to install system binaries they may not have permission for is a usability tax that does not pay off when most inputs are docx / pdf / html / pptx.
-**TLS fingerprint impersonation for high-security sites.** Web fetching impersonates a Chrome TLS fingerprint by default. WeChat Official Accounts and several CDNs block Python's default `requests` handshake outright, and a single dependency that handles them is preferable to maintaining a parallel Node.js fetcher as the primary path.
+**TLS fingerprint impersonation for high-security sites.** Web fetching uses the Python `web_to_md.py` path by default and relies on `curl_cffi` when available for Chrome-like TLS impersonation. WeChat Official Accounts and several CDNs block Python's default handshake outright; keeping this in the Python converter path avoids making a Node fetcher the primary architecture.
---
## Project Structure & Lifecycle
-The non-obvious bit of the project layout is `import-sources`'s **asymmetric default**: files outside the repo are *copied* in (preserving the user's original), files inside the repo are *moved* in (so intermediate artifacts don't get committed by accident). The asymmetry tracks the natural risk profile — outside-repo files are typically user assets we shouldn't disturb, inside-repo files are typically transient artifacts that should be cleaned up. A single uniform default would get one or the other case wrong every time.
+`project_manager.py init` creates a project as a self-contained workspace, not just an output folder:
+
+| Directory | Role |
+|---|---|
+| `sources/` | archived originals, normalized Markdown, and converter companion files |
+| `analysis/` | machine-extracted facts: PPTX intake bundles and regenerated image analysis |
+| `images/` | single runtime image pool for user, extracted, formula, web, AI, sliced, EMF/WMF assets |
+| `icons/` | project-local icon set copied by `icon_sync.py`, with global library fallback at export |
+| `templates/` | copied template specs / SVG references / non-image template assets |
+| `svg_output/` | the only hand-authored SVG source directory |
+| `svg_final/` | derived, self-contained SVGs for IDE/browser/preview-snapshot workflows |
+| `live_preview/` | preview server state, edit history, and annotation logs |
+| `notes/` | `total.md` and split per-slide speaker notes |
+| `exports/` | timestamped native PPTX deliverables |
+| `backup/<timestamp>/` | frozen `svg_output/` snapshots written by default export |
+
+The CLI still supports three source-import modes: `--move`, `--copy`, and an automatic default that moves repo-local files but copies external files. The production workflow in `SKILL.md` deliberately tightens that: agents must call `import-sources ... --move` so every source artifact and generated intermediate enters `sources/` and the working root stays clean. The script-level default exists for ad hoc CLI safety; the workflow-level contract is stricter so AI runs are reproducible and auditable.
---
@@ -124,27 +162,39 @@ The architectural choice worth flagging: **viewBox is in pixels, not absolute un
## Template System & Optional Path
-Templates are **opt-in, not default**. The default Strategist flow is free design — AI invents the visual system from the source content alone. The template path activates only on explicit user trigger.
+Templates are **opt-in, not default**. The default Strategist flow is free design — AI invents the visual system from the source content alone. The template path activates only on an explicit directory path supplied by the user.
**Why default to free design.** Templates are floors that easily become ceilings: they lock the deck into the template's visual idioms regardless of how the content actually wants to be presented. Free-design layouts derive structure from the source content rather than imposing it from a fixed grammar, so the visual rhythm tracks the content rather than fighting it. Constrained mode is genuinely better in narrow cases (brand-locked decks, strongly-typed scenarios like academic defense or government report), so it stays available — but the AI doesn't proactively reach for it; the user does.
-**No proactive matching.** The AI does not suggest, hint at, or auto-map content to a template. Even when a deck looks like an obvious fit for an existing template, the AI stays silent and proceeds with free design unless the user has named the template. The reason is reliability over discoverability: matching content to templates is a judgment call that drifts as the library evolves, and a wrong "you might want X" pushes the user toward a commitment the AI cannot reliably make. Discoverability is handed to docs (the three `templates/{brands,layouts,decks}/README.md` per-kind indexes) and to the explicit query path ("what templates are available?"), not the runtime prompt.
+**Mechanical trigger, not semantic matching.** A bare name like `academic_defense`, a brand mention, or a style phrase such as "McKinsey style" does not trigger Step 3 even if a matching library directory exists. Step 3 only consumes a path that resolves to a directory whose `design_spec.md` declares `kind: brand`, `kind: layout`, or `kind: deck`. Discoverability is handled by template indexes and explicit Q&A ("what templates are available?"), not by runtime fuzzy matching.
+
+The three template kinds own different segments of the design contract:
+
+| Kind | Owns | Typical contents | Effect on Strategist |
+|---|---|---|---|
+| `brand` | identity | colors, typography, logo, voice, icon style | locks identity; structure remains free |
+| `layout` | structure | canvas, page structure, page types, SVG roster | locks structure; identity is confirmed in the Eight Confirmations |
+| `deck` | identity + structure + template overview | full replica-style package | locks the full template grammar, with only content-specific choices left |
+
+When several paths are supplied, fusion is segment-level, not field-level. A brand overrides the identity segment, a layout overrides the structure segment, and a deck supplies the middle/template-overview segment. Same-kind conflicts are surfaced as conflicts rather than resolved by implicit ordering. This keeps template composition debuggable: a fused spec can say exactly which bundle owns each segment.
+
+**Raw PPTX templates are outside Step 3.** A `.pptx` may be source material, and PPTX intake can extract its identity and geometry. But a raw PPTX template plus a request to generate a new PPTX routes to `template-fill`, because the user's expectation is native slide cloning and text/table/chart replacement. The SVG route can consume only a reusable template package; to use a PPTX's design language in the SVG route, the PPTX must first pass through `create-template`, then the resulting template directory path can be supplied to Step 3.
**Layouts are opt-in; charts and icons are not.** The asymmetry isn't an inconsistency — *layout* is what locks visual idiom (the floor/ceiling problem above), while charts and icons are reusable primitives that don't impose deck-wide style. Same `templates/` directory, different role in the visual contract.
---
-## Role System: Three Specialized Agents in a Single Pipeline
+## Role System: Specialized Modes in a Single Pipeline
-PPT Master uses **role switching within one main agent** rather than parallel sub-agents. The choice has three connected reasons:
+PPT Master uses **role switching within one main agent** rather than parallel sub-agents. Strategist, Image_Generator, Executor, and workflow-specific modes are instruction scopes loaded on demand; they are not independent agents with their own stale copies of the deck state. The choice has three connected reasons:
**Why one agent, not parallel sub-agents.** Page design depends on the full upstream context — Strategist's color choices, the image resources that actually got acquired (vs failed and substituted), prior pages' visual rhythm. Sub-agents would start with a stale partial snapshot of that context and produce visually drifting decks. The same logic forbids batched page generation (e.g., five pages per turn): batching accelerates context compression and the deck's visual consistency degrades faster than the speed gain is worth.
**Why role-specialized references, not one mega prompt.** Strategist runs in "negotiate with user" mode (open-ended, conversational, willing to back up); Executor runs in "produce strict XML" mode (no improvisation, no missing attributes). Mixing both into one prompt forces the model to hold incompatible discipline in the same turn — every prompt-engineering pathology of mode-mixing shows up. Splitting into per-role files lets each role load only what it needs and discard the rest.
-**Eight Confirmations as the only blocking gate.** Strategist ends with eight bundled user confirmations (canvas / page count / audience / style / color / icon / typography / image) presented as one blocking decision point. After confirmation, the pipeline runs to completion without further interrupts. The reason it's bundled and singular: design choices are correlated (color affects icon library affects typography), so resolving them together produces coherent decisions, while spreading confirmations across phases would invite contradictory user inputs and force backtracking.
+**Eight Confirmations as the only blocking gate.** Strategist ends with eight bundled user confirmations (canvas / page count / audience / style / color / icon / typography / image). In the current workflow this is normally delivered through the Confirm UI in two tiers: Tier 1 confirms anchors (canvas, audience, divergence, delivery purpose, mode, visual style); Tier 2 is re-derived from the confirmed anchors and confirms realization choices (page count, palette, typography, icons, formula policy, image usage, AI image path, generation mode, refine-spec). The final `confirm_ui/result.json` is authoritative — if the user changes a field, the generated `design_spec.md` and `spec_lock.md` must use that value, not the AI's original recommendation.
-**User-provided image analysis goes through metadata, not pixels.** When the user supplies images, Strategist runs an extractor that summarizes dimensions, EXIF orientation, dominant color, and subject — and reasons over that text. Opening image bytes directly is forbidden because the LLM doesn't need pixels to make layout decisions; it needs facts that fit on a page (aspect ratio for placement, color tone for palette compatibility, subject for slide assignment). Pixel reading would burn context for no decision-quality gain.
+**Image analysis goes through regenerated metadata, not pixels.** When images exist, Strategist and Executor use `analyze_images.py` output (`analysis/image_analysis.csv`) rather than directly opening image files. The CSV is a regenerated view over the live `images/` folder, not a durable cache. Re-running it before image-sensitive decisions is the staleness strategy: user images, extracted images, web images, AI outputs, formulas, and sliced elements all converge into the same measured fact table.
**Per-page spec_lock re-read** is the long-deck anti-drift mechanism — full rationale in § Spec Propagation below.
@@ -152,7 +202,9 @@ PPT Master uses **role switching within one main agent** rather than parallel su
## Execution Discipline
-The pipeline is enforced by an 8-rule set in [`SKILL.md` § Global Execution Discipline](../skills/ppt-master/SKILL.md) — that file is authoritative; the rules live there. They look bureaucratic but exist because LLMs default to "let me solve the whole problem in this turn", which is exactly the wrong shape for a serial pipeline where each step's output is bounded, checkpointed, and consumed by the next. The rules collectively close failure modes that surfaced repeatedly in practice: out-of-order execution, AI proxying user design decisions, cross-phase bundling, missing prerequisites, speculative pre-work, sub-agent context loss, page-batching drift, and long-deck color/font drift.
+The pipeline is enforced by a 10-rule set in [`SKILL.md` § Global Execution Discipline](../skills/ppt-master/SKILL.md) — that file is authoritative; the rules live there. They look bureaucratic but exist because LLMs default to "let me solve the whole problem in this turn", which is exactly the wrong shape for a serial pipeline where each step's output is bounded, checkpointed, and consumed by the next. The rules collectively close failure modes that surfaced repeatedly in practice: out-of-order execution, AI proxying user design decisions, cross-phase bundling, missing prerequisites, speculative pre-work, sub-agent context loss, page-batching drift, long-deck color/font drift, batch/script-generated SVG drift, and routing ambiguity.
+
+Two newer rules are especially important to the architecture. First, Executor page SVGs must be hand-authored by the current main agent, one page at a time; writing a Python/Node/shell generator to emit pages is prohibited because the resulting deck loses cross-page judgment and visual continuity. Second, routing is deterministic: raw PPTX template requests, beautify requests, native enhancement, custom animation, live preview, and other workflow triggers are not turned into open-ended user route questions when the repository already defines the boundary.
The Role Switching Protocol (mandated read of `references/<role>.md` before mode change) serves two reinforcing purposes: forcing fresh role instructions into context overrides drift from the previous mode, and the visible marker in the conversation transcript creates an audit trail so the user can see when the agent moved between modes — critical when reviewing why a particular decision was made.
@@ -167,6 +219,8 @@ The Strategist phase produces two artifacts that look redundant but serve differ
Why both? Without `spec_lock.md`, the Executor would re-read `design_spec.md` per page during long decks and the LLM's context-compression drift would gradually mutate colors and fonts mid-deck. `spec_lock.md` is the **anti-drift mechanism** — the SKILL.md mandates `read_file <project>/spec_lock.md` before every page, so values stay verbatim across 20+ slides.
+The lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_layouts` (which layout template SVG, if any, a page should inherit), `page_charts` (which chart template should be adapted), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` references that decide which execution rule files are loaded. Empty entries are meaningful signals: no template, no chart, or no image is often a design decision rather than missing data.
+
`update_spec.py` propagates a post-generation change in two coordinated steps: write the new value to `spec_lock.md`, then literal-replace it across every `svg_output/*.svg`. The tool's scope is deliberately narrow — only `colors.*` (HEX values, case-insensitive replacement) and `typography.font_family` (attribute-scoped). Other fields (font sizes, icons, images, canvas) are intentionally **not supported** because their replacements would need attribute-scoped or semantic awareness whose risk/benefit doesn't justify bulk propagation. For those, edit `spec_lock.md` and re-author the affected pages.
The tool refuses to back up: it relies on git for revert. Adding a backup mechanism would just duplicate git's job and create stale snapshots.
@@ -175,12 +229,18 @@ The tool refuses to back up: it relies on git for revert. Adding a backup mechan
## Image Acquisition & Embedding
-Two architectural decisions shape this phase:
+Several architectural decisions shape this phase:
**Provider-specific config keys, not a generic `IMAGE_API_KEY`.** Every backend takes its own `OPENAI_API_KEY` / `MINIMAX_API_KEY` / etc. and the active one is selected by an explicit `IMAGE_BACKEND=<name>`. A unified `IMAGE_API_KEY` field looks tidier on first glance but causes silent confusion when a user has multiple providers configured at once and isn't sure which one is active — the kind of fault that surfaces only as "image generation gives weird results" with no clear failure point. Forcing per-provider keys makes "which backend am I using" a config-readable fact, not an inference.
**Permissive-by-default license filter, with strict mode for credit-incompatible layouts.** Web image search defaults to allowing CC BY / CC BY-SA images with inline attribution — most slides have visual room for a credit element. `--strict-no-attribution` is the escape hatch for full-bleed hero images and tight composition where there's no place to put a credit without breaking the design. Non-commercial (CC BY-NC*) and no-derivatives (CC BY-ND*) licenses are auto-rejected because the typical PPT Master output is shared in commercial or modified contexts; a permissive default with that floor is the failure mode users actually want.
+**Manifest-first acquisition.** In-pipeline AI generation always writes `images/image_prompts.json` and renders the sidecar `image_prompts.md`, even for one image. The positional `image_gen.py "prompt"` form is intentionally limited to one-off debugging because it leaves no manifest/sidecar audit trail. Web acquisition mirrors this with `images/image_queries.json` for multi-row batches and `image_sources.json` for attribution/source tracking.
+
+**One coherent sheet for related spot illustrations.** When a deck needs three or more same-family small illustrations, the plan uses one AI illustration sheet row plus `slice` rows rather than separate generations. `slice_images.py` cuts the sheet into named transparent elements, those derived files join `images/`, and `analyze_images.py` is rerun so Executor sees their real dimensions. This is a style-cohesion rule as much as a cost rule: one sheet forces the small elements to share a visual hand.
+
+**Terminal status before Executor.** Rows that require acquisition must end in `Generated`, `Sourced`, or `Needs-Manual`; `Pending` and `Failed` are not allowed to leak into Executor. A `Needs-Manual` row can continue through SVG generation only as a known placeholder/dependency, and Step 7 re-checks required files before final export.
+
**External refs during development, two divergent embedding strategies for delivery.** While editing in `svg_output/`, images are external file references — fast iteration, single-source-of-truth replacement. The two delivery artifacts then diverge: `svg_final/` Base64-inlines (a folder of self-contained SVGs that IDE preview, browser, and the preview pptx can all open without missing the bitmap dependencies); native pptx instead copies bitmaps into the PPTX media folder and uses `<a:srcRect>` to express the cropping. The split exists because Base64 inside DrawingML works but bloats file size 3-4×, while file-referenced bitmaps are PowerPoint's native idiom for which `<a:srcRect>` is the canonical crop expression — wrong tool in either direction would cost editability or file size.
**Three-dimensional AI image lock at Strategist time.** When the deck includes AI-generated images, Strategist decides three orthogonal dimensions up front — `rendering` (visual style family: vector-illustration / editorial / 3d-isometric / sketch-notes / …), `palette` (how the deck's HEX values are *used*: proportion + role + temperament), `type` (per-image internal composition: background / hero / framework / comparison / …). The first two are deck-wide and written into `spec_lock.md`; Image_Generator then assembles every per-image prompt from the single locked rendering + palette plus a per-image type, instead of re-deciding style per image. Without this, every image gets its own style drift and the deck reads as a stack of unrelated illustrations. This is the visual-cohesion dual of `spec_lock`'s typography/color anti-drift mechanism, just one level upstream of pixels. Strategist surfaces ≥3 candidate `rendering × palette` combinations to the user during the Eight Confirmations — never auto-locking a single combination silently, because the choice has far-reaching deck-wide consequences and the user's taste is the only oracle for it.
@@ -233,9 +293,9 @@ The architectural reasons worth knowing here:
> Why each artifact and module exists in the engineering conversion stage, and which workflows would break if you delete it. Read this before considering any simplification of `svg_final/` / `finalize_svg.py` / `svg_to_pptx.py`.
-### Four artifacts, four workflows
+### Five artifacts, five workflows
-The post-processing stage produces four artifacts. Each one serves a workflow that nothing else in the pipeline can replace.
+The post-processing stage works with five artifacts. Each one serves a workflow that nothing else in the pipeline can replace.
| Artifact | Workflow it serves | Why nothing else replaces it |
| --- | --- | --- |
@@ -270,6 +330,18 @@ This is the key insight that's easy to miss when reading the code. The same modu
---
+## Direct OOXML Routes
+
+Not every PPTX-related request should regenerate slides. PPT Master now has direct OOXML routes for cases where the native deck itself is the object being edited.
+
+`template_fill_pptx.py` is a thin CLI wrapper over `scripts/template_fill_pptx/`. Its analyzer extracts a slide library with text slots, tables, charts, and geometry; the fill plan selects source slides, confirms replacements, then the applier clones slides and patches XML parts directly. This route deliberately avoids SVG: a user who supplies a PowerPoint template usually wants those native slide masters, placeholders, tables, and charts to remain PowerPoint-native.
+
+`native_enhance_pptx.py` is the stable entry point for finished-deck enhancement. It delegates to the native narration/timing implementation and patches the PPTX package in place from a project copy: notes, page transitions, recorded narration media, slide timings, and related metadata. The contract is preservation: existing content, layout, and formatting are not regenerated.
+
+These direct routes share some analysis primitives with the main pipeline, especially PPTX intake, but they do not share the SVG authoring or post-processing stages. That separation is intentional: SVG generation is a design synthesis path; direct OOXML editing is a preservation path.
+
+---
+
## Native PPTX Conversion Internals
**Why per-element dispatch, not whole-file translation.** SVG's hierarchical model maps cleanly onto DrawingML's group / shape / picture types — there's no need for a holistic optimizer that re-plans the slide. Each shape kind gets its own narrow translator, which keeps each translator simple enough to debug and unit-test in isolation. The output quality of a slide is the sum of independent local conversions; that property is fragile under whole-file translation but robust under element dispatch.
@@ -296,4 +368,22 @@ The interesting design choice is the animation **anchor**, not the effect list.
## Standalone Workflows
-Six capabilities (`create-template`, `verify-charts`, `customize-animations`, `live-preview`, `generate-audio`, `visual-review`) live as standalone workflows rather than pipeline steps. Each is sparsely triggered — per-template, per-chart-deck, per-animation-tuning request, per-complaint, per-video-export, per explicit visual-review request — not per-deck. Folding any into the default pipeline would either run unnecessary steps for the majority of users (added latency and failure surface) or force a one-size-fits-all narrowing of the main flow. Keeping them opt-in lets the deck-generation pipeline stay tight and predictable while making the capability available when its trigger condition fires; each `workflows/<name>.md` is self-contained and loaded on demand, so paying the prompt-context cost is also opt-in.
+Standalone workflows are route definitions, not optional decorations. They exist when a capability has a different contract from the main pipeline or is too sparse to justify loading by default.
+
+| Workflow | Trigger | Contract |
+|---|---|---|
+| `topic-research` | user provides only a topic and no source material | gather web materials before Step 1 |
+| `template-fill-pptx` | raw PPTX template + new material/topic | direct native slide clone/fill; no SVG pipeline |
+| `beautify-pptx` | existing PPTX, preserve page count/order/wording 1:1, improve layout | regenerate through SVG pipeline with source identity/content locked |
+| `create-template` | build a reusable layout/deck template package | output a directory Step 3 can consume later |
+| `create-brand` | extract or define a reusable brand identity | output `templates/brands/<id>/` |
+| `resume-execute` | fresh chat after Phase A; user says to continue a project | enter Phase B without rerunning Strategist |
+| `refine-spec` | user explicitly wants to review/refine the spec before generation | stop after full spec/lock for revision, then resume |
+| `verify-charts` | generated deck contains data charts | calibrate chart geometry before export |
+| `customize-animations` | user asks for object-level animation order/effect/timing | create/validate `animations.json` and re-export policy |
+| `live-preview` | user asks to preview, click/select, apply annotations, or re-export browser edits | start/re-enter browser preview and apply submitted edits only at the defined point |
+| `visual-review` | user explicitly requests per-page visual self-check | rubric pass between Executor and post-processing |
+| `generate-audio` | user asks for narration/video export | produce narration audio and recorded timing export path |
+| `native-enhance-pptx` | finished PPTX should keep existing content/layout while adding native enhancements | direct OOXML patch route |
+
+Keeping these files separate is a dependency-control decision. The main path loads only the roles and references it actually needs; a narration backend, animation sidecar, chart calibration rubric, or template-import contract is pulled into context only when the trigger fires. That keeps the default deck-generation path tight while making the rarer capabilities deterministic rather than improvised.
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 370eb3d0..f720d2d5 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -15,22 +15,25 @@
## 系统架构
```
-用户输入 (PDF/DOCX/XLSX/URL/Markdown)
+用户输入 (PDF/DOCX/XLSX/PPTX/URL/Markdown/主题文本)
↓
[源内容转换] → source_to_md/pdf_to_md.py / doc_to_md.py / excel_to_md.py / ppt_to_md.py / web_to_md.py
+ ├── Markdown 是内容契约
+ └── PPTX intake 写入 analysis/<stem>.identity.json、<stem>.slide_library.json、source_profile.json
↓
[创建项目] → project_manager.py init <项目名> --format <格式>
↓
-[模板处理(可选)] — 默认跳过,直接自由设计
- 用户主动点名模板时:复制模板文件到项目目录
- 需要新建全局模板:使用 /create-template 工作流单独完成
+[模板 / 品牌 / 布局(可选)] — 默认跳过,直接自由设计
+ 仅在用户提供明确模板目录路径且其中 design_spec.md 声明 kind: brand/layout/deck 时触发
+ 原生 PPTX 模板请求进入 template-fill;可复用 SVG 模板需先通过 create-template 创建
↓
-[Strategist] 策略师 - 八项确认与设计规范 → design_spec.md + spec_lock.md
+[Strategist] 策略师 - 两层八项确认与设计规范 → design_spec.md + spec_lock.md
↓
-[Image Acquisition] 图片获取(当资源列表中有需要 AI 生成或网络搜索的图片时)
+[Image Acquisition] 图片获取(当资源列表中有需要 AI 生成、网络搜索或切片的图片时)
↓
[Executor] 执行师
- ├── 视觉构建:连续生成所有 SVG 页面 → svg_output/
+ ├── 生成开始前启动 live preview,并在生成期间保持可用
+ ├── 视觉构建:按页顺序连续生成 SVG 页面 → svg_output/
├── [Quality Check] svg_quality_checker.py(强制通过,0 错误)
└── 讲稿生成:完整讲稿 → notes/total.md
↓
@@ -50,6 +53,14 @@
└── svg_output/ ← Executor 原始 SVG 备份(重跑 finalize_svg → svg_to_pptx 即可重建 pptx)
```
+以下直接 PPTX 工作流会有意绕过这条 SVG 路线:
+
+| 工作流 | 输入角色 | 输出机制 | 为什么独立 |
+|---|---|---|---|
+| `template-fill-pptx` | 原生 PPTX 模板 deck + 新材料 | 克隆选中的幻灯片,并在 OOXML 层改写文本 / 表格 / 图表 | 保留用户的 PowerPoint 原生页面壳,而不是转成 SVG |
+| `native-enhance-pptx` | 内容与版式都应保持稳定的已完成 PPTX | 在 OOXML 层直接补讲稿、旁白、计时和转场 | 只追加原生增强,不重新设计 |
+| `beautify-pptx` | 页数、页序、每页措辞都必须 1:1 保留的已有 PPTX | 抽取源事实后走 SVG 流水线重新生成 native deck | 只改布局和层级,不做原地编辑 |
+
---
## 技术流程
@@ -59,7 +70,7 @@
整个流程分为三个阶段:
**第一阶段:内容理解与设计规划**
-源文档(PDF/DOCX/URL/Markdown)经过转换变为结构化文本,由 Strategist 角色完成内容分析、页面规划和设计风格确认,输出完整的设计规格。
+源文档(PDF/DOCX/XLSX/PPTX/URL/Markdown/主题文本)会被转换成 Strategist 所需的内容事实与分析事实。Strategist 角色分析材料、读取相关 `analysis/` artifact、规划页面结构,并确认视觉风格,最终输出完整设计规格。
**第二阶段:AI 视觉生成**
Executor 角色逐页生成演示文稿的视觉内容,输出为 SVG 文件。这个阶段的产物是**设计稿**,而非成品。
@@ -100,17 +111,44 @@ SVG 也是唯一同时满足流程中所有角色需要的格式:**AI 能可
## 源内容转换
-源文档(PDF / DOCX / EPUB / XLSX / PPTX / 网页)在流水线启动前先被归一化为 Markdown——这是 Strategist 阅读的事实源。两个设计选择塑造了转换器:
+源文档(PDF / DOCX / EPUB / XLSX / PPTX / 网页)会在 Strategist 开始前完成归一化,但当前架构已经不是“全部转成 Markdown 后其他信息都不重要”的单通道模型。现在有两条事实通道,各自拥有明确职责:
+
+| 通道 | 产物 | 所有者 | 用途 |
+|---|---|---|---|
+| 内容契约 | `sources/<stem>.md` | `source_to_md/*` 转换器 | 文本、表格、图表数值、引用和源材料叙事 |
+| 结构化分析 | `analysis/*.json` / `analysis/*.csv` | intake 与分析工具 | PPTX 身份信息、页面几何、原生表格/图表、图片尺寸/色彩/主体 |
+
+对 PPTX 源文件,`project_manager.py import-sources` 会同时运行 `ppt_to_md.py` 和 `pptx_intake.py`。Markdown 仍然是主生成流水线的内容源;intake bundle 会写出 `<stem>.identity.json`、`<stem>.slide_library.json`,并把紧凑的多 deck 索引合并到 `analysis/source_profile.json`。Strategist 默认读取这个紧凑索引来获取源事实;只有特定工作流需要原始细节时,才打开单个 deck 的原始 artifact。这个边界很重要:主流水线可以重构页数和叙事,而 `template-fill` 与 `beautify` 会把同一批 intake 事实中的一部分提升为更强约束。
+
+转换器生成的图片资产也会被归一化。伴随的 `<stem>_files/` 目录会导入项目级 `images/` 池,`image_manifest.json` 按文件名合并;当导入后目录名发生变化时,Markdown 中的资源引用会被重写。Office 矢量图(`.emf` / `.wmf`)是一等运行时资产:intake 阶段不栅格化它们,`finalize_svg.py` 为 native 路径保留外部引用,`svg_to_pptx.py` 以 Office 矢量媒体嵌入,避免 CJK 字体替换和矢量细节损失。
+
+两个转换器设计选择仍然成立:
-**Native-Python 优先,外部二进制兜底。** 常见格式由纯 Python wheel 处理,pandoc 仅在长尾的小众格式时才被调用。让每个用户都去装一份可能没有权限装的系统级二进制是一种可用性税,而 95% 的输入是 docx / pdf / html,付这种税不划算。
+**Native-Python 优先,外部二进制兜底。** 常见格式由纯 Python wheel 处理,pandoc 仅在长尾小众格式时才被调用。让每个用户都去装一份可能没有权限装的系统级二进制是一种可用性税,而大多数输入是 docx / pdf / html / pptx,这种税不值得。
-**TLS 指纹模拟应对高安全站点。** 网页抓取默认模拟 Chrome TLS 指纹。微信公众号和不少 CDN 直接屏蔽 Python 默认 `requests` 握手;用一个依赖把这事一并解决,比维持一份 Node.js 抓取器作为主路径更划算。
+**TLS 指纹模拟应对高安全站点。** 网页抓取默认走 Python 版 `web_to_md.py`,并在可用时依赖 `curl_cffi` 做类 Chrome TLS 指纹模拟。微信公众号和不少 CDN 会直接屏蔽 Python 默认握手;把这件事留在 Python 转换路径里,避免让 Node 抓取器成为主架构。
---
## 项目结构与生命周期
-项目布局里非显然的一点是 `import-sources` 的**非对称默认**:仓库**外**的文件默认 *copy*(保留用户原件),仓库**内**的文件默认 *move*(避免中间产物被误提交)。这种不对称恰好对应自然的风险画像——仓库外的文件一般是用户资产、不该动;仓库内的文件一般是临时产物、应该清理。一个统一默认无论选 copy 还是 move,每次都会在另一种场景出错。
+`project_manager.py init` 创建的是一个自包含工作区,而不只是输出目录:
+
+| 目录 | 职责 |
+|---|---|
+| `sources/` | 原件归档、归一化 Markdown、转换器伴随文件 |
+| `analysis/` | 机器抽取事实:PPTX intake bundle 与按需重算的图片分析 |
+| `images/` | 单一运行时图片池:用户图、抽取图、公式图、网络图、AI 图、切片图、EMF/WMF |
+| `icons/` | 由 `icon_sync.py` 复制的项目级图标集;导出时可回退到全局库 |
+| `templates/` | 复制进项目的模板 spec / SVG reference / 非图片模板资产 |
+| `svg_output/` | 唯一手写 SVG 源目录 |
+| `svg_final/` | 派生出的自包含 SVG,服务 IDE / 浏览器 / 预览快照 |
+| `live_preview/` | 预览服务状态、直接编辑历史和注解日志 |
+| `notes/` | `total.md` 与拆分后的逐页讲稿 |
+| `exports/` | 带时间戳的 native PPTX 交付物 |
+| `backup/<timestamp>/` | 默认导出时写入的冻结 `svg_output/` 快照 |
+
+CLI 仍支持三种导入模式:`--move`、`--copy`,以及“仓库内文件 move、仓库外文件 copy”的自动默认。`SKILL.md` 中的生产工作流会刻意收紧这一点:agent 必须调用 `import-sources ... --move`,让所有源文件和中间产物进入 `sources/`,保持工作根目录干净。脚本级默认服务临时 CLI 使用的安全性;工作流级契约更严格,是为了让 AI 执行具备可复现和可审计性。
---
@@ -124,27 +162,39 @@ PPT Master 不只服务 PPT——同一套 SVG → DrawingML 流水线还能产
## 模板系统与可选路径
-模板是**可选项,不是默认**。Strategist 默认走自由设计——AI 完全凭源内容创造视觉系统。模板路径只在用户显式触发时启用。
+模板是**可选项,不是默认**。Strategist 默认走自由设计——AI 完全凭源内容创造视觉系统。模板路径只在用户明确提供目录路径时启用。
**为什么默认自由设计。** 模板是地板,但很容易变成天花板:它会把整个 deck 锁进模板自有的视觉惯用语,无视内容本身想要怎样被呈现。自由设计的布局从源内容的结构推导而来,而不是从一套固定语法套上去——视觉节奏跟着内容走,而不是跟内容打架。约束模式在窄场景里确实更好(品牌锁定的 deck、强类型场景如学术答辩或政府报告),所以它一直在;但 AI 不主动去抓,是用户去抓。
-**不主动匹配。** AI 不会基于内容向用户推荐、暗示或自动映射模板。即便某份 deck 看起来"明显适合"库里某个模板,没有用户点名,AI 也保持沉默,按自由设计走。理由是可靠性优先于发现性:把内容与模板做匹配是会随库演进而漂移的判断,一句错误的"或许你想用 X"会把用户推向 AI 本就无法可靠承诺的选择。发现性交给文档(三类各自的 `templates/{brands,layouts,decks}/README.md`)和显式查询路径("有哪些模板可以用?")承担,不放进运行时 prompt。
+**机械触发,不做语义匹配。** 像 `academic_defense` 这样的裸名字、品牌提及,或“麦肯锡风格”这类风格短语,即使库里存在相似目录,也不会触发 Step 3。Step 3 只消费一个能解析为目录的路径,并且该目录的 `design_spec.md` 必须声明 `kind: brand`、`kind: layout` 或 `kind: deck`。发现性交给模板索引和显式问答(“有哪些模板可以用?”),不交给运行时 fuzzy matching。
+
+三类模板拥有不同的设计契约片段:
+
+| Kind | 拥有的片段 | 典型内容 | 对 Strategist 的影响 |
+|---|---|---|---|
+| `brand` | 身份片段 | 配色、字体、logo、语气、图标风格 | 锁定身份;结构保持自由 |
+| `layout` | 结构片段 | 画布、页面结构、页面类型、SVG roster | 锁定结构;身份仍在八项确认里确定 |
+| `deck` | 身份 + 结构 + 模板总览 | 完整复刻型包 | 锁定完整模板语法,只剩内容相关选择 |
+
+当用户提供多个路径时,融合是**片段级**而不是字段级:brand 覆盖身份片段,layout 覆盖结构片段,deck 提供中间的 template overview 片段。同类冲突会被显式列为冲突,而不是按输入顺序默默决定。这样融合后的 spec 能明确说明每个片段来自哪里,便于审计和复现。
+
+**原生 PPTX 模板不属于 Step 3。** `.pptx` 可以作为源材料进入流水线,PPTX intake 也能抽取其身份和几何信息。但“给一个原生 PPTX 模板并生成新 PPTX”的请求会进入 `template-fill`,因为用户期望的是克隆 PowerPoint 页面壳并替换文本 / 表格 / 图表。SVG 路线只能消费可复用模板包;如果要把某个 PPTX 的设计语言用于 SVG 路线,必须先通过 `create-template` 生成模板目录,再把该目录路径提供给 Step 3。
**布局是 opt-in,图表和图标不是。** 这种不对称不是矛盾——*布局*正是锁定视觉惯用语的那一层(地板/天花板问题),而图表和图标是不会施加 deck 级风格约束的复用原语。同一个 `templates/` 目录,但在视觉契约里扮演的角色不同。
---
-## 角色系统:单一流水线中的三个专业代理
+## 角色系统:单一流水线中的专业模式
-PPT Master 用的是**单主代理内的角色切换**,不是并行子代理。这个选择有三条互相支撑的理由:
+PPT Master 用的是**单主代理内的角色切换**,不是并行子代理。Strategist、Image_Generator、Executor 以及各独立工作流模式,本质上都是按需加载的指令作用域;它们不是带着各自过期 deck 状态的独立 agent。这个选择有三条互相支撑的理由:
**为什么是单代理而非并行子代理。** 页面设计依赖完整的上游上下文——Strategist 的色彩选择、图片资源是否成功获取(还是失败被替代)、之前几页的视觉节奏。子代理拿到的只能是这个上下文的过期局部快照,产出的 deck 视觉会逐页漂。同一逻辑也禁止分批生成(比如一次 5 页):分批加速上下文压缩,deck 的视觉一致性下降速度比节省的速度更快——不划算。
**为什么是角色专属 reference 而不是一个超大 prompt。** Strategist 跑的是「跟用户协商」模式(开放式、对话式、可以回退),Executor 跑的是「产出严格 XML」模式(不准即兴、不准漏属性)。把两者塞进同一个 prompt,强迫模型在同一个 turn 里持守相互矛盾的纪律——所有混合模式的 prompt 工程病灶都会出现。按角色拆开,每个角色只加载它需要的、扔掉其他。
-**Eight Confirmations 是唯一的阻塞 gate。** Strategist 阶段以八项打包确认(画布 / 页数 / 受众 / 风格 / 配色 / 图标 / 排版 / 图像)作为单一阻塞决策点呈现给用户。确认后,流水线一路跑到结束,不再有用户中断点。打包且单一的理由:设计选项之间是相关的(配色影响图标库、影响排版),一起决能产出一致的决策;分散到各阶段确认会引入互相矛盾的用户输入,最后被迫回退重做。
+**Eight Confirmations 是唯一的阻塞 gate。** Strategist 阶段以八项打包确认(画布 / 页数 / 受众 / 风格 / 配色 / 图标 / 排版 / 图像)作为核心阻塞决策点。当前流程默认通过 Confirm UI 分两层呈现:Tier 1 确认锚点(画布、受众、改写幅度、交付目的、mode、visual style);Tier 2 基于用户已确认的锚点重新推导,再确认实现层选择(页数、调色板、字体、图标、公式策略、图片来源、AI 图片路径、生成模式、refine-spec)。最终的 `confirm_ui/result.json` 是权威输入——用户改过的字段必须进入 `design_spec.md` 和 `spec_lock.md`,不能回退到 AI 的原始推荐。
-**用户已有图片走元数据,不读像素。** 用户自带图片时,Strategist 跑的是一个抽取器,把尺寸、EXIF 方向、主色调、主体内容总结成文本,然后基于这份文本推理。直接读图片字节是被禁的,因为 LLM 做布局决策不需要像素,需要的是能塞进一页的事实(用宽高比定位置、用色调判定调色板兼容、用主体决定哪页放)。读像素只会消耗上下文而不带来决策质量收益。
+**图片分析走重算元数据,不读像素。** 当项目里存在图片时,Strategist 和 Executor 使用 `analyze_images.py` 的输出(`analysis/image_analysis.csv`),而不是直接打开图片文件。这个 CSV 是基于当前 `images/` 目录重算出来的视图,不是持久缓存。每次做图片敏感决策前重跑分析,就是它的防陈旧策略:用户图、抽取图、网络图、AI 图、公式图和切片图最终都会汇入同一张可度量事实表。
**逐页 spec_lock 重读** 是长 deck 的抗漂移机制——完整理由见下面的 § 设计规范的传播。
@@ -152,7 +202,9 @@ PPT Master 用的是**单主代理内的角色切换**,不是并行子代理
## 执行纪律
-流水线由 [`SKILL.md` § 全局执行纪律](../../skills/ppt-master/SKILL.md) 中的 8 条规则强制——那份文件是权威,规则住在那里。它们看起来很官僚,但存在的理由是:LLM 默认行为是「让我在这一 turn 里把整个问题搞定」,而这恰好是串行流水线最不该有的形状——串行流水线要求每一步的输出都是有界、过 checkpoint、被下一步消费的。这套规则共同关闭了实际反复出现的失败模式:乱序执行、AI 代为做用户设计决策、跨阶段打包、前置条件未满足、投机预先准备、子代理上下文丢失、分批漂移、长 deck 色彩字体漂移。
+流水线由 [`SKILL.md` § 全局执行纪律](../../skills/ppt-master/SKILL.md) 中的 10 条规则强制——那份文件是权威,规则住在那里。它们看起来很官僚,但存在的理由是:LLM 默认行为是“让我在这一 turn 里把整个问题搞定”,而这恰好是串行流水线最不该有的形状——串行流水线要求每一步的输出都是有界、过 checkpoint、被下一步消费的。这套规则共同关闭了实际反复出现的失败模式:乱序执行、AI 代为做用户设计决策、跨阶段打包、前置条件未满足、投机预先准备、子代理上下文丢失、分批漂移、长 deck 色彩字体漂移、脚本批量生成 SVG 漂移,以及路由歧义。
+
+其中两条新边界尤其关键。第一,Executor 页面 SVG 必须由当前主代理逐页手写;禁止写 Python / Node / shell 生成器批量吐 SVG,因为这种输出会丢失跨页判断和视觉连续性。第二,路由是确定性的:原生 PPTX 模板、beautify、native enhancement、自定义动画、live preview 等触发条件已经在仓库里定义清楚时,不再额外抛给用户一个开放式路线选择题。
角色切换协议(切换模式前必须 `read_file references/<role>.md`)有两个互相支撑的作用:把新鲜的角色指令载入上下文,覆盖前一模式的漂移;对话 transcript 中的可见标记构成审计轨迹,让用户能看到 agent 何时切换了模式——回看一个具体决策为什么这样做时,这条线索很关键。
@@ -167,6 +219,8 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
为什么两份都要?没有 `spec_lock.md` 的话,Executor 在长 deck 里会逐页重读 `design_spec.md`,LLM 上下文压缩漂移会逐渐扭曲色值和字体。`spec_lock.md` 是**抗漂移机制**——SKILL.md 强制要求生成每一页前 `read_file <project>/spec_lock.md`,让数值在 20+ 页里保持字面一致。
+这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_layouts`(某页是否继承某个 layout 模板 SVG)、`page_charts`(某页应适配哪个图表模板)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。空值本身也是信号:没有模板、没有图表、没有图片,很多时候是设计选择,而不是漏填。
+
`update_spec.py` 把生成后的修改用两个协调步骤传播:把新值写入 `spec_lock.md`,然后字面替换到每一份 `svg_output/*.svg`。工具的范围**故意收得很窄**——只支持 `colors.*`(HEX 值,大小写不敏感替换)和 `typography.font_family`(属性级)。其他字段(字号、图标、图片、画布)**有意不支持**——它们的替换需要属性级或语义级理解,风险/收益不值得做批量传播。这些情况手动改 `spec_lock.md` 然后重做受影响的页面。
工具拒绝做备份:依赖 git 回滚。加备份机制只是重复 git 的工作,还会留下过时快照。
@@ -175,12 +229,18 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
## 图片获取与嵌入
-这一阶段有三个架构层面的决策:
+这一阶段有多项架构层面的决策:
**provider 专属 config key,不用通用 `IMAGE_API_KEY`。** 每个 backend 用自己的 `OPENAI_API_KEY` / `MINIMAX_API_KEY` 等等,当前 backend 由显式的 `IMAGE_BACKEND=<name>` 选定。统一的 `IMAGE_API_KEY` 字段第一眼看着干净,但当用户同时配了多个 provider 又不确定哪个在生效时会造成静默混乱——这种 fault 通常只表现为「图像生成结果怪怪的」,找不到清晰失败点。强制 per-provider key 让「我现在用的是哪个 backend」从推理变成可读配置。
**默认宽松 license 过滤,配以严格模式应对没法放致谢的版面。** 网络图片搜索默认允许 CC BY / CC BY-SA 加内联致谢——大部分幻灯片都有视觉空间放一个致谢元素。`--strict-no-attribution` 是给全屏 hero image 和紧凑构图的逃生口,那些场景没法放致谢又不打破设计。NC(CC BY-NC*)和 ND(CC BY-ND*)自动拒绝,因为 PPT Master 的典型产物会用于商用或修改场景;宽松默认 + 这个底线正好对应用户实际想要的 fail-mode。
+**Manifest-first 获取。** 流水线内的 AI 图片生成永远先写 `images/image_prompts.json`,并渲染旁路 `image_prompts.md`,哪怕只有一张图。`image_gen.py "prompt"` 这种位置参数形式只保留给一次性调试,因为它没有 manifest / sidecar 审计轨迹。网络图片获取也类似:多行 web 资源写入 `images/image_queries.json` 批量执行,并用 `image_sources.json` 追踪来源和致谢信息。
+
+**相关小插画用一张统一 sheet。** 当 deck 需要三个或更多同风格小插画时,资源计划使用一个 AI illustration sheet 行,再用若干 `slice` 行派生元素,而不是分别生成多张小图。`slice_images.py` 把 sheet 切成具名透明元素,这些派生文件进入 `images/`,随后重跑 `analyze_images.py`,让 Executor 看到真实尺寸。这既是成本规则,也是风格一致性规则:一张 sheet 会强迫这些小元素来自同一种视觉手法。
+
+**Executor 前必须进入终态。** 需要获取的资源行必须落到 `Generated`、`Sourced` 或 `Needs-Manual`;`Pending` 和 `Failed` 不能漏进 Executor。`Needs-Manual` 可以作为已知占位 / 依赖继续进入 SVG 生成,但 Step 7 会在最终导出前重新检查必需文件是否已经存在。
+
**开发期外部引用,交付期分叉成两套嵌入策略。** 在 `svg_output/` 里编辑时,图片是外部文件引用——快速迭代、单点替换。两份交付产物随后分叉:`svg_final/` 走 Base64 内联(产出一组自包含 SVG,IDE 预览、浏览器、preview pptx 都能开而不丢位图依赖);native pptx 反过来把位图复制进 PPTX 的 media 文件夹,用 `<a:srcRect>` 表达裁剪。分叉的理由:在 DrawingML 里塞 Base64 能跑但文件膨胀 3-4 倍;文件引用的位图是 PowerPoint 原生表达方式,配 `<a:srcRect>` 的裁剪也是 DrawingML 的规范写法——任一方向用错工具都要付出可编辑性或文件大小的代价。
**AI 图片三维系统:Strategist 阶段就锁定。** 当 deck 包含 AI 生成图片时,Strategist 在前置阶段一次性确定三个正交维度——`rendering`(视觉风格家族:vector-illustration / editorial / 3d-isometric / sketch-notes / ……)、`palette`(deck 的 HEX 在图里**怎么用**:比例 + 角色 + 气质)、`type`(每张图的内部构图:background / hero / framework / comparison / ……)。前两个是 deck 级、写进 `spec_lock.md`;Image_Generator 此后每张图的 prompt 都从同一份锁定的 rendering + palette 加上该图的 type 组装出来,而不是逐图重决风格。没有这层锁定,每张图都会自己风格漂移,整套 deck 读起来就是一摞互不相关的插画。这是 `spec_lock` 字体/色彩抗漂移机制在像素上游的对偶——同一思路,往前推一层。Strategist 在八项确认阶段会向用户呈现 **≥3 个 `rendering × palette` 候选**,绝不静默地自动锁定单一组合,因为这是一个会牵动全 deck 视觉的选择,唯一权威只有用户的品味。
@@ -233,9 +293,9 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份
> 工程化转换阶段中每一份产物和每一个模块为何存在,删除它会破坏哪些工作流。在考虑简化 `svg_final/` / `finalize_svg.py` / `svg_to_pptx.py` 之前,先读这一节。
-### 四份产物,四种工作流
+### 五份产物,五种工作流
-后处理阶段产生四份产物。每一份都服务于一种流水线中无法替代的工作流。
+后处理阶段涉及五份产物。每一份都服务于一种流水线中无法替代的工作流。
| 产物 | 服务的工作流 | 为何无可替代 |
| --- | --- | --- |
@@ -270,6 +330,18 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份
---
+## 直接 OOXML 路由
+
+不是所有 PPTX 相关请求都应该重新生成页面。PPT Master 现在为“原生 deck 本身就是编辑对象”的场景提供直接 OOXML 路由。
+
+`template_fill_pptx.py` 是 `scripts/template_fill_pptx/` 包的薄 CLI 入口。analyzer 抽取带文本槽位、表格、图表和几何信息的 slide library;fill plan 选择源页面并确认替换内容;applier 克隆幻灯片并直接 patch XML parts。这条路线故意绕开 SVG:用户提供 PowerPoint 模板时,通常期望原生母版、占位符、表格和图表继续保持 PowerPoint-native。
+
+`native_enhance_pptx.py` 是已完成 deck 原生增强的稳定入口。它委托 native narration / timing 实现,在项目归档副本上直接 patch PPTX package:讲稿、页面转场、录制旁白媒体、页面计时和相关元数据。它的契约是保留:已有内容、布局和格式不重新生成。
+
+这些直接路线会和主流水线共享部分分析原语,尤其是 PPTX intake,但不共享 SVG 作者阶段和后处理阶段。这个分离是有意的:SVG 生成是设计合成路径;直接 OOXML 编辑是保留路径。
+
+---
+
## Native PPTX 转换器内部
**为什么是逐元素派发而不是整体翻译。** SVG 的层级模型干净地映射到 DrawingML 的 group / shape / picture 类型——不需要一个全局优化器去重新规划幻灯片。每种形状都有自己窄的翻译器,简单到能单独调试和单元测试。一张幻灯片的最终质量等于这些独立局部转换之和;这个性质在整体翻译下脆弱,在元素派发下稳健。
@@ -296,4 +368,22 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份
## Standalone Workflows(独立工作流)
-六个能力(`create-template`、`verify-charts`、`customize-animations`、`live-preview`、`generate-audio`、`visual-review`)作为独立工作流存在,而不是流水线步骤。每个都是稀疏触发的——按模板、按含图表的 deck、按一次动画微调、按一次具体抱怨、按一次视频导出、按用户明确请求的一次视觉自检,而不是按每个 deck。把任何一个塞进默认流水线,要么对大多数用户运行无意义的步骤(增加延迟和失败面),要么强制一刀切收窄主流程。保持 opt-in 让 deck 生成主流水线保持紧凑、可预期,同时在触发条件命中时仍提供这些能力;每个 `workflows/<name>.md` 是自包含的、按需加载——所以 prompt context 的开销也是 opt-in。
+独立工作流是路线定义,不是可有可无的装饰。只有当某个能力与主流水线契约不同,或触发频率太低、不值得默认加载时,才会独立成 `workflows/<name>.md`。
+
+| 工作流 | 触发条件 | 契约 |
+|---|---|---|
+| `topic-research` | 用户只有主题、没有源材料 | 在 Step 1 前收集网络材料 |
+| `template-fill-pptx` | 原生 PPTX 模板 + 新材料 / 新主题 | 直接克隆并填充原生页面;不进入 SVG 流水线 |
+| `beautify-pptx` | 现有 PPTX,页数/页序/措辞必须 1:1 保留,只改善排版 | 锁定源身份与内容后,通过 SVG 流水线重新生成 |
+| `create-template` | 构建可复用 layout/deck 模板包 | 输出后续 Step 3 可消费的目录 |
+| `create-brand` | 提取或定义可复用品牌身份 | 输出 `templates/brands/<id>/` |
+| `resume-execute` | Phase A 后新开聊天,用户要求继续某项目 | 不重跑 Strategist,直接进入 Phase B |
+| `refine-spec` | 用户明确要求生成前先审阅 / 修改 spec | 写出完整 spec/lock 后停下,用户修改后再恢复 |
+| `verify-charts` | 生成 deck 含数据图表 | 导出前校准图表几何 |
+| `customize-animations` | 用户要求调对象级动画顺序 / 效果 / 计时 | 创建 / 校验 `animations.json` 并控制再导出策略 |
+| `live-preview` | 用户要求预览、点击选择、应用注解或重导出浏览器编辑 | 启动 / 重入浏览器预览,并只在规定时机应用提交内容 |
+| `visual-review` | 用户明确要求逐页视觉自检 | 在 Executor 与后处理之间做 rubric pass |
+| `generate-audio` | 用户要求旁白 / 视频导出 | 生成旁白音频并走录制计时导出路径 |
+| `native-enhance-pptx` | 已完成 PPTX 要保留内容/布局,同时追加原生增强 | 直接 OOXML patch 路线 |
+
+保持这些文件独立,是依赖控制决策。主路径只加载当前需要的角色和 reference;旁白 backend、动画 sidecar、图表校准 rubric、模板导入契约等,只有触发命中时才进入上下文。这样默认 deck 生成路径保持紧凑,同时让低频能力也有确定实现,而不是临场发挥。