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
feat(routes): merge Fill and Enhance Native PPTX into Edit Native PPTX
hugohe33a0861bfe8ea
diff --git a/AGENTS.md b/AGENTS.mdindex 9b8b02aa..888818b2 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -19,17 +19,17 @@ command provides a compact view.PPT Master turns source material into natively editable DrawingML PPTX. Generate has two mutually exclusive runtimes: Default Strategist → Image_Generator → Executor, and self-contained Quick without separate strategy/confirmation. Beautify selects from explicit Quick intent; Image to PPTX always uses Quick.-**Route selection authority**: [`skills/ppt-master/workflows/routing.md`](skills/ppt-master/workflows/routing.md) owns the four top-level artifact routes: Generate PPTX, Create Template, Fill Native PPTX, and Enhance Native PPTX. Child workflows, profiles, stages, and governance documents refine one selected route; they are not competing top-level routes.+**Route selection authority**: [`skills/ppt-master/workflows/routing.md`](skills/ppt-master/workflows/routing.md) owns the three top-level artifact routes: Generate PPTX, Create Template, and Edit Native PPTX. Child workflows, profiles, stages, and governance documents refine one selected route; they are not competing top-level routes.- Topic-only or fact-insufficient inputs run [`topic-research`](skills/ppt-master/workflows/stages/topic-research.md) inside the selected Generate profile's source intake; its facts URLs are not auto-expanded. After normal image search fails, one relevant webpage may be fetched as a source package and only reviewed selections enter the runtime image pool.- Default Generate prepares template candidates internally in Step 3, then confirms the communication contract and free-design/template choice together in Stage 1. Template content stays unread until that confirmation; selected roots are installed before template-aware Stage 2. Quick skips this interaction.-- Raw PPTX template plus new material/topic routes to [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md), not the SVG pipeline.+- Raw PPTX template plus new material/topic routes to [`edit-native-pptx`](skills/ppt-master/workflows/edit-native-pptx.md): a `pptx_to_svg.py --roundtrip` workspace where unchanged pages are referenced byte-for-byte and only planned pages are edited; it never enters Generate.- Raw PPTX cannot be consumed as a Generate template workspace; run [`create-template`](skills/ppt-master/workflows/create-template.md) first and return with the generated workspace root as a Stage-1 candidate. Never add Master/Layout structure directly to an existing PPTX/SVG; generate new structured SVG pages from the workspace.- Explicit quick/fast or skip-strategy generation uses [`quick-generate`](skills/ppt-master/workflows/profiles/quick-generate.md): prepare sources/resources as needed, decide without interaction, omit Strategist/confirmation/spec/lock, hand-author `svg_output/`, pass its lockless final checker, and export.- Recorded, self-running, or video-directed Generate work conditionally loads [`video-design`](skills/ppt-master/references/video-design.md) inside the selected Default or explicit Quick runtime before page planning. It changes scene, script, and motion design—not the runtime/profile or artifact route.- PPTX beautify is a strict 1:1 Generate [`profile`](skills/ppt-master/workflows/profiles/beautify-pptx.md), not a separate route. Explicit Quick intent uses the Quick runtime; otherwise it uses Default. Any split/merge/drop/reorder disables Beautify and returns to ordinary Generate in the selected runtime.- Page-image reconstruction uses the Codex-supported, Quick-only [`image-to-pptx`](skills/ppt-master/workflows/profiles/image-to-pptx.md) profile. Normalize input page frames; one frame becomes one slide. Restore text natively, reconstruct low-resolution graphics without changing identity, and derive registered clean-base/scene layers. Padded-bbox-disjoint objects may share a generated plate and become independent crops. Never use a full-slide screenshot skin. Other hosts are unsupported.-- Finished PPTX native enhancement uses [`native-enhance-pptx`](skills/ppt-master/workflows/native-enhance-pptx.md) and must not enter SVG regeneration.+- Finished PPTX notes / narration / timings / transitions with visible slides untouched also use [`edit-native-pptx`](skills/ppt-master/workflows/edit-native-pptx.md); export must report `rebuilt=0`.- [`visual-review`](skills/ppt-master/workflows/stages/visual-review.md), [`customize-animations`](skills/ppt-master/workflows/stages/customize-animations.md), and [`generate-audio`](skills/ppt-master/workflows/stages/generate-audio.md) are supporting stages; their trigger rules remain explicit/conditional.## Execution Requirements@@ -101,13 +101,13 @@ python3 skills/ppt-master/scripts/template_preview_pptx.py <template_workspace>python3 skills/ppt-master/scripts/animation_config.py scaffold <project_path> # optional, only for custom object-level animationpython3 skills/ppt-master/scripts/animation_config.py validate <project_path> # optional, before re-export-# Existing PPTX native enhancement workflow — direct OOXML patch, no SVG conversion-python3 skills/ppt-master/scripts/native_enhance_pptx.py init <PPTX_file> --name <project_slug>-python3 skills/ppt-master/scripts/native_enhance_pptx.py validate <project_path>-python3 skills/ppt-master/scripts/native_enhance_pptx.py apply <project_path>+# Edit Native PPTX — source-preserving round-trip workspace (fill / edit / enhance an existing deck)+python3 skills/ppt-master/scripts/pptx_to_svg.py <source.pptx> -o projects/<slug>_<YYYYMMDD> --inheritance-mode both --roundtrip+python3 skills/ppt-master/scripts/svg_authoring_view.py projects/<slug>_<YYYYMMDD>/authoring-svg-flat --refresh-summary+python3 skills/ppt-master/scripts/svg_to_pptx.py projects/<slug>_<YYYYMMDD> --roundtrip # optional page_plan.json at the workspace root```-For serial post-processing and export, follow [`generate-pptx.md`](skills/ppt-master/workflows/generate-pptx.md) Step 7 exactly. See [`svg-pipeline.md`](skills/ppt-master/scripts/docs/svg-pipeline.md) for tool flags and behavior.+For Generate PPTX serial post-processing and export, follow [`generate-pptx.md`](skills/ppt-master/workflows/generate-pptx.md) Step 7 exactly; Edit Native PPTX exports through its own §7. See [`svg-pipeline.md`](skills/ppt-master/scripts/docs/svg-pipeline.md) for tool flags and behavior.## Core Directoriesdiff --git a/README.md b/README.mdindex f319b948..bb9dc089 100644--- a/README.md+++ b/README.md@@ -334,7 +334,7 @@ Whatever you state explicitly is followed; whatever you leave unspecified the ag> **Output:** The SVG pipeline has one PPTX converter: it reads `svg_output/` and writes a directly editable native DrawingML deck to `exports/<name>_<timestamp>.pptx`. The default Generate flow runs `finalize_svg.py` and produces self-contained previews in `svg_final/`; PowerPoint's manual **Convert to Shape** command is outside the supported contract. Explicit [quick generation](./skills/ppt-master/workflows/profiles/quick-generate.md) skips Strategist, confirmation, `design_spec.md`, `spec_lock.md`, and `finalize_svg.py`: whatever you state explicitly is followed, and whatever you leave unspecified the agent decides directly in one active context. It still converts sources, researches factual gaps, applies shared mode/style/aesthetic guidance, prepares required images/icons, authors formulas as native inline or block markers, considers native shapes and data visualizations, hand-authors SVG, passes the lockless Quick final quality check, and exports the final PPTX. It writes no substitute plan and cannot resume after context loss. Formula markers compile their LaTeX payload to editable OMML for PowerPoint 2010+; block groups and inline `<tspan>` runs keep ordinary SVG previews that are replaced during export. Formula rendering and editability in Keynote, WPS, LibreOffice, and other non-PowerPoint clients are not part of this contract. Ordinary export capabilities remain available as needed, including native chart/table replacement, notes, motion, narration, and diagnostics; notes, custom object animation, and narration start off, and the agent may enable them when the request or deck needs them. A default-path Quick export writes the normal postflight report and snapshots `svg_output/` to `backup/<timestamp>/svg_output/`; an explicit output path keeps the ordinary no-backup behavior. By default charts and tables export as individually editable SVG-derived DrawingML shapes, which prioritize cross-app visual consistency. Pass `--native-charts-and-tables` to replace eligible groups with PowerPoint-native Chart/Table objects backed by data, which provide **Edit Data** and object-specific controls but may render differently across apps; this variant is saved as `exports/<name>_<timestamp>_native_charts_tables.pptx`. Both chart/table export variants are editable—the distinction is the PowerPoint object model, not editability itself.-> **Already have a `.pptx` you want to reuse?** Hand the AI that deck plus your material and ask it to "fill this deck with the new content" — it fills text, table, and chart data into your existing design and exports only the pages you pick, staying natively editable. See the [FAQ](./docs/faq.md) and [template-fill workflow](./skills/ppt-master/workflows/template-fill-pptx.md).+> **Already have a `.pptx` you want to reuse?** Give the AI the deck and material and ask it to "fill this deck with the new content" — Edit Native PPTX keeps the design and unchanged pages byte-for-byte, edits chosen pages, supports selection/reordering, and can add notes or narration. See the [FAQ](./docs/faq.md) and [workflow](./skills/ppt-master/workflows/edit-native-pptx.md).> **Something went wrong?** If the AI loses context, ask it to read `skills/ppt-master/SKILL.md`; for everything else, check the **[FAQ](./docs/faq.md)** — it covers model selection, layout issues, export problems, and more. Continuously updated from real user reports.diff --git a/README_CN.md b/README_CN.mdindex 226138ea..d5dee1f9 100644--- a/README_CN.md+++ b/README_CN.md@@ -339,7 +339,7 @@ AI 全程处理——内容分析、视觉设计、SVG 生成、PPTX 导出。> **输出说明:** SVG 管线统一由项目转换器读取 `svg_output/`,生成可直接编辑的原生 DrawingML `.pptx`,保存至 `exports/<name>_<timestamp>.pptx`。默认 Generate 流程会运行 `finalize_svg.py` 并生成自包含预览 `svg_final/`;PowerPoint 手工“转换为形状”不在支持范围。用户可显式启用[快速生成](./skills/ppt-master/workflows/profiles/quick-generate.md):它跳过 Strategist、确认、`design_spec.md`、`spec_lock.md` 与 `finalize_svg.py`——你明确提出的要求照做,你没提的由 Agent 在一次有效上下文中直接决定;仍按需转换来源、研究事实缺口、应用共享 mode / visual style / 美学规范、准备图片 / 图标,并把公式直接创作为原生行内或块级 marker,同时考虑原生形状与数据可视化,随后按规范手写 SVG,通过无锁的 Quick 最终质量检查,再导出最终 PPTX。它不写替代计划,上下文丢失后不能续接。公式 marker 会把 LaTeX payload 编译为 PowerPoint 2010+ 可编辑 OMML;块级 group 与行内 `<tspan>` run 都保留普通 SVG 预览,导出时将其替换。Keynote、WPS、LibreOffice 等非 PowerPoint 客户端的公式显示与编辑能力不在支持合同内。原生图表 / 表格替换、讲稿、动效、旁白和诊断等普通导出能力仍可按需使用;讲稿、自定义对象动画和旁白默认关闭,Agent 可在用户要求或 deck 确有需要时启用。Quick 使用默认输出路径时仍会生成普通 postflight 报告,并把 `svg_output/` 镜像到 `backup/<timestamp>/svg_output/`;显式指定输出路径时沿用普通流程不创建备份的行为。图表和表格默认导出为 SVG 派生、可逐形状编辑的 DrawingML 对象,优先保证 PowerPoint / Keynote / WPS 间的视觉一致性;可加 `--native-charts-and-tables`,把符合合同的组替换为带数据源和对象专属编辑能力的 PowerPoint 原生 Chart/Table 对象,跨软件渲染可能略有差异,保存为 `exports/<name>_<timestamp>_native_charts_tables.pptx`。这两种图表/表格导出变体都可编辑,区别在于 PowerPoint 对象模型,而不是“能否编辑”。-> **已有一份想复用的 `.pptx`?** 把那份 deck 连同素材给 AI,说「套模板」即可——它会把新内容(文字、表格、图表数据)填进你现有的设计,只导出你挑选的页面,且保持原生可编辑。详见 [常见问题](./docs/zh/faq.md) 与 [套模板工作流](./skills/ppt-master/workflows/template-fill-pptx.md)。+> **已有一份想复用的 `.pptx`?** 把 deck 连同素材给 AI,说「套模板」即可——Edit Native PPTX 会保留原设计,逐字节保留未改页面,只编辑选中页面,支持选页/重排,并可添加讲稿或旁白。详见 [常见问题](./docs/zh/faq.md) 与 [工作流](./skills/ppt-master/workflows/edit-native-pptx.md)。> **遇到问题?** AI 迷失上下文时,让它先读 `skills/ppt-master/SKILL.md`;其他问题查看 **[常见问题](./docs/zh/faq.md)** — 涵盖模型选择、排版问题、导出异常等,基于真实用户反馈持续更新。diff --git a/docs/animations.md b/docs/animations.mdindex b475aa99..c70b8c6c 100644--- a/docs/animations.md+++ b/docs/animations.md@@ -272,7 +272,7 @@ PPT Master validates animation settings strictly: unknown effects or Start modes| Static structure | Backgrounds, Master/Layout content, placeholders, and page chrome remain static || Unsupported object builds | No paragraph/text-range builds, custom freeform motion-path authoring, native Chart/SmartArt build sequencing, or media playback commands are inferred from grouped SVG content || Output route | Animation exists in the native PPTX generated from `svg_output/`; `svg_final/` is a static preview |-| Existing PPTX routes | Template Fill and Native Enhance preserve source object animation rather than translating it into this generated-deck model |+| Edit Native PPTX | Preserves source object animation through the round-trip workspace rather than translating it into this generated-deck model || PPTX-to-SVG import | Reconstructs only current-registry rows with exact native duration and unique top-level group targets; advanced/build/media timing remains diagnosed || Playback compatibility | Microsoft PowerPoint desktop is the primary validation target; Keynote, WPS, LibreOffice, and older Office versions may remap or omit individual effects |diff --git a/docs/audio-narration.md b/docs/audio-narration.mdindex 3dfcaea6..a5c145c1 100644--- a/docs/audio-narration.md+++ b/docs/audio-narration.md@@ -22,7 +22,7 @@ PPT Master can turn the speaker notes into per-slide narration via [`edge-tts`](1. **Speaker notes are written as pure spoken narration.** PPT Master's notes spec deliberately produces TTS-friendly prose — no bracketed stage markers, no `Key points:` / `Duration:` meta-lines — so what is read aloud is exactly what's on the page.2. **AI picks the voice for you.** When you ask for narration, the AI checks the deck's primary language (`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …), pulls the selected provider's voice catalog, and recommends 3–6 candidates with a one-line tone description for each (e.g. "steady male voice for financial reporting"). It also recommends a speaking rate or provider defaults based on notes density.-3. **Settings resolve once.** Default Generate and Enhance Native ask once for provider, voice, rate, embedding, and optional video export. Quick uses explicit values and automatically resolves unspecified provider, voice, rate, and embedding choices; video remains off unless direct video delivery was requested.+3. **Settings resolve once.** Default Generate and Edit Native PPTX ask once for provider, voice, rate, embedding, and optional video export. Quick uses explicit values and automatically resolves unspecified provider, voice, rate, and embedding choices; video remains off unless direct video delivery was requested.4. **Generation runs.** Edge, ElevenLabs, MiniMax, and timestamp-capable CosyVoice voices write each page's audio and SRT from provider timing returned by the same synthesis; Qwen and explicit CosyVoice audio-only mode write audio only. A complete run atomically writes `audio/manifest.json` for provenance. For Generate PPTX with narration-cue synchronization, page-local SRT and canonical custom animation let the AI map current SVG content groups to numbered SRT cues and derive click-free `narration_animations.json`; narration-independent custom motion keeps canonical timing, while no animation sidecar inherits the base export's resolved motion. It then re-exports the deck with audio attached and, when page-local SRT exists, merges it using timing values read from that final PPTX. Automatic video delivery continues through PowerPoint's native encoder and, when cues exist, the verified sound mix. An explicitly selected slideshow capture instead records PowerPoint's real-time full-screen picture and system audio, skips that mixer, and aligns any delivery SRT against the accepted capture. Long-audio import and automatic long-audio splitting are not supported.Subtitles remain external artifacts: PPT Master does not embed them into the PPTX or burn them into the MP4. Automatic video export delegates to installed Windows PowerPoint; it is not a separate renderer.@@ -168,9 +168,9 @@ python3 skills/ppt-master/scripts/video_subtitles.py <project_path> \```Before sending any TTS request, `notes_to_audio.py` verifies that every-Generate SVG page or Native Enhance slide has a readable, non-empty per-slide-note. Missing or empty notes return exit code `2`; generate those notes first,-then rerun audio generation.+Generate SVG page or Edit Native PPTX output page has a readable, non-empty+per-slide note. Missing or empty notes return exit code `2`; generate those+notes first, then rerun audio generation.For edge, `--voice` is required. Use `--list-voices --locale <locale>` to see what's available.Edge generates up to three slide-level audio/SRT pairs concurrently by default.diff --git a/docs/faq.md b/docs/faq.mdindex 1e9500aa..67544953 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -387,12 +387,12 @@ For post-generation fixes, simply tell the AI: "Page 3 has a layout issue — th## Q: I have an existing PPT and want to build on it — which route should I use?-Think of "using an existing PPT" as two questions: **keep its content or not**, and **keep its design (layout + visuals) or not**. The four combinations map to three generation paths plus the option to keep the original unchanged:+Think of "using an existing PPT" as two questions: **keep its content or not**, and **keep its design (layout + visuals) or not**. The four combinations map to three processing paths plus the option to keep the original unchanged:| Intent | Route | What stays fixed ||---|---|---|| Keep content + redo layout | **Generate PPTX + beautify profile** | Page count, page order, per-slide wording, chart/table data |-| Replace content + keep design | **Fill Native PPTX** | Native source slide design; selected pages may be reused/reordered |+| Replace content + keep design | **Edit Native PPTX** | Native source design; unchanged pages stay byte-for-byte, while selected pages may be edited, reordered, repeated, or omitted || Keep only content, redo design and pagination | **Generate PPTX** | Source facts; story structure and page count may change || Keep content + keep design | No generation needed | Use the original file |@@ -400,7 +400,7 @@ Use the **beautify profile** when the source deck's page split is part of the reUse the **main pipeline** when the source PPT is just material: extract it to Markdown with `ppt_to_md`, read PPTX intake facts from `analysis/`, then let Strategist re-architect the outline freely (merge / split / reorder pages). Say "build a better deck from this one's content" or "turn this into a 10-page executive briefing".-The one-line test between beautify and the main pipeline: **is the source's page split information to preserve, or just the previous author's structure to improve?** Preserve → beautify; improve → main pipeline. The concrete discriminator is **page count / order**: if it changes at all — split, merge, drop, reorder, or even keeping every word but splitting one crowded page so it reads better — that is re-pagination, which is the main pipeline. Beautify is strictly 1:1.+The one-line test between beautify and ordinary Generate applies when the visible design will be regenerated: **is the source's page split information to preserve, or just the previous author's structure to improve?** Preserve → beautify; improve → ordinary Generate. Beautify is strictly 1:1. If the native design must survive instead, use Edit Native PPTX; its `page_plan.json` may select, reorder, repeat, or omit existing pages without redesigning them.If your request is ambiguous, for example "make this PPT more professional" or "optimize this deck", the AI should ask one clarification before routing: **keep the original page count/order and each slide's wording, or treat the PPT as source material and restructure it into a new story?**@@ -410,23 +410,24 @@ There is also one orthogonal route: if you don't want to produce a deck right no## Q: I already have a finished `.pptx` — can I reuse its design and just fill in new content?-Yes — this is the **template fill** route, separate from the SVG generation pipeline. Give the AI your existing `.pptx` plus your material (or a topic) and ask it to "fill this deck with the new content" or "fill this back into the template". It treats your deck as a native slide library, lets you pick only the pages that fit the new story (reorder freely, and reuse one page for several output slides), and writes the new text — plus native table cells and chart data — straight into the original OOXML.+Yes — this is the **Edit Native PPTX** route, separate from Generate. Give the AI your existing `.pptx` plus your material (or a topic) and ask it to "fill this deck with the new content" or "fill this back into the template". It imports the deck into a source-preserving round-trip workspace under `projects/`, treats the source pages as a native slide library, and lets you choose, reorder, repeat, or omit pages before editing selected content.-The output stays 100% native-editable PowerPoint: the original design, layouts, images, and animations are preserved, and only the planned pages are exported. It deliberately does **not** author a new layout topology or swap source images. The ordered `slides` roster in `fill_plan.json` may omit, reorder, or repeat source slide shells, so the output page count can differ from the source. A deck's page structure encodes its logic (lead-then-detail, comparison, progression), so pick pages whose structure already fits your content rather than forcing it in. When the source library lacks a required new structure, use ordinary Generate, or run Create Template first and then Generate from the resulting workspace. Full steps: [template-fill workflow](../skills/ppt-master/workflows/template-fill-pptx.md).+Unchanged output pages are referenced and restored byte-for-byte. On an edited page, unchanged objects restore in their native form and only changed objects are rebuilt. The ordered `pages` roster in `page_plan.json` uses `source_slide` plus an optional copied `svg` filename to select, reorder, repeat, or omit source pages. Notes, narration, timings, and transitions are overlays on the preserved slide. A deck's page structure encodes its logic (lead-then-detail, comparison, progression), so pick pages whose structure already fits your content rather than forcing it in. When the source library lacks a required new structure, use ordinary Generate, or run Create Template first and then Generate from the resulting workspace. Full steps: [Edit Native PPTX workflow](../skills/ppt-master/workflows/edit-native-pptx.md).---## Q: Content landed in unexpected places — how do I see what PPT Master detected in my `.pptx`?-Both PPTX-consuming routes write a read-only analysis report before anything is generated. Read that report to see exactly which shapes were recognized.+Edit Native PPTX and Create Template each write a readable inventory before authoring begins. Read it to see which pages and objects were recognized.-For **Fill Native PPTX**:+For **Edit Native PPTX**:```bash-python3 skills/ppt-master/scripts/pptx_intake.py <deck.pptx> -o <analysis_dir>+python3 skills/ppt-master/scripts/pptx_to_svg.py <deck.pptx> \+ -o projects/<slug> --inheritance-mode both --roundtrip```-`<stem>.slide_library.json` lists every fillable slot per slide with geometry, paragraph counts, and text metrics, plus separate `tables` and `charts` sections. A styled plain text box counts as a slot — a shape does not have to be a real placeholder to be filled.+`authoring-svg-flat/authoring_summary.json` lists the source page roster and per-page text, image, vector, placeholder, and source-reference counts. Open only the selected compact SVG pages you need to inspect or edit.For **Create Template**:diff --git a/docs/getting-started.md b/docs/getting-started.mdindex 63e1b108..b9c28464 100644--- a/docs/getting-started.md+++ b/docs/getting-started.md@@ -51,12 +51,12 @@ The `npx skills add hugohe3/ppt-master` installation path also requires a workin| You want… | Route | What happens ||---|---|---|-| **Use this deck's native slide shells with new content** | Fill Native PPTX | Clones the selected source slides and patches text / table / chart data directly in OOXML. The source design remains native; output is a new filled deck bound to the available slide shells. |+| **Use this deck's native slide shells with new content** | Edit Native PPTX | Imports a round-trip workspace; unchanged pages restore byte-for-byte, `page_plan.json` may select/reorder/repeat/omit pages, and only planned pages are edited. || **Build a reusable design system, then generate a new deck** | Create Template → Generate PPTX | Creates a validated Brand, Style, Layout, or Deck workspace from the reference, then authors a fresh deck. The new story, structure, and page count can differ from the source. |-For the first, give the AI your `.pptx` plus your material (or a topic) and ask it to "fill this deck with the new content" — see the [template-fill workflow](../skills/ppt-master/workflows/template-fill-pptx.md). The rest of this section covers create-template.+For the first, give the AI your `.pptx` plus your material (or a topic) and ask it to "fill this deck with the new content" — see the [Edit Native PPTX workflow](../skills/ppt-master/workflows/edit-native-pptx.md). The rest of this section covers create-template.-**To build a reusable workspace from an existing PowerPoint, explicitly request the Create Template route.** A raw `.pptx` plus new material otherwise belongs to Fill Native PPTX; it is not a Generate template workspace. Create the workspace first:+**To build a reusable workspace from an existing PowerPoint, explicitly request the Create Template route.** A raw `.pptx` plus new material otherwise belongs to Edit Native PPTX; it is not a Generate template workspace. Create the workspace first:```You: Create a reusable Deck template from projects/brand/our_deck.pptx via /create-templatediff --git a/docs/powerpoint-svg-mapping.md b/docs/powerpoint-svg-mapping.mdindex 8d05481c..cd387dae 100644--- a/docs/powerpoint-svg-mapping.md+++ b/docs/powerpoint-svg-mapping.md@@ -52,7 +52,7 @@ See [`canvas-formats.md`](../skills/ppt-master/references/canvas-formats.md) for## 2. Master, Layout, background, and placeholder features-**Route boundary**: Free-design and brand-only projects in the main SVG pipeline remain on `pptx_structure.mode: flat` from planning through export; `flat` is not a provisional state awaiting an exporter upgrade. Repeated logos, footers, or layouts never cause export to switch to `structured`, promote content into a Master/Layout, infer placeholders, or deduplicate objects. Output that requires reusable native Master, Layout, or placeholder behavior must enter Step 3 with a validated deck/layout template workspace; when none exists, run [`create-template`](../skills/ppt-master/workflows/create-template.md) first and return to the main pipeline with that workspace. The minimal Master and Blank Layout emitted by flat export are PPTX package scaffolding, not a design master derived from the slides. Filling new content into a raw PPTX template remains the [`template-fill-pptx`](../skills/ppt-master/workflows/template-fill-pptx.md) route.+**Route boundary**: Free-design and brand-only projects in the main SVG pipeline remain on `pptx_structure.mode: flat` from planning through export; `flat` is not a provisional state awaiting an exporter upgrade. Repeated logos, footers, or layouts never cause export to switch to `structured`, promote content into a Master/Layout, infer placeholders, or deduplicate objects. Output that requires reusable native Master, Layout, or placeholder behavior must enter Step 3 with a validated deck/layout template workspace; when none exists, run [`create-template`](../skills/ppt-master/workflows/create-template.md) first and return to the main pipeline with that workspace. The minimal Master and Blank Layout emitted by flat export are PPTX package scaffolding, not a design master derived from the slides. Filling new content into a raw PPTX while preserving its design belongs to [`edit-native-pptx`](../skills/ppt-master/workflows/edit-native-pptx.md).| PowerPoint feature | Project representation | PPTX result | Import and fidelity | Validation boundary ||---|---|---|---|---|@@ -125,13 +125,13 @@ preset selection and authoring behavior are documented in| Font size | Finite unitless SVG pixels, for example `font-size="24"` | DrawingML hundredths of a point; `1 px = 0.75 pt` | `Native-stable` after unit conversion | Generated authoring uses only unitless px; registered legacy units are compatible input and warn, while unknown units error; DrawingML minimum is 1 pt || Font weight | Registered `font-weight` on `<text>`/`<tspan>` | DrawingML regular/bold run switch | `Native-normalized`; numeric weights collapse to the DrawingML boolean boundary | The exact value grammar and aliases belong to [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || Italic, underline, and strike | Registered `font-style` / `text-decoration` on `<text>`/`<tspan>` | DrawingML italic, underline, and strike run properties | `Native-stable` for registered tokens | Unknown tokens are rejected; the exact grammar belongs to [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) |-| Superscript and subscript in ordinary text | Exact direct `baseline-shift="super|sub"` on `<tspan>`; an explicit run `font-size` remains independent | Editable ordinary-text `a:rPr@baseline` at `30000` / `-25000`; no automatic font-size reduction | Forward export is native. PPTX-to-SVG does not reconstruct baseline shift in visible SVG; unchanged imported `txBody` metadata and source-preserving native workflows can still retain the source run | Inline style, other elements, numeric offsets, and combination with an inline formula marker are rejected; structured mathematics uses editable OMML, while a Unicode glyph remains literal text |+| Superscript and subscript in ordinary text | Exact direct `baseline-shift="super|sub"` on `<tspan>`; an explicit run `font-size` remains independent | Editable ordinary-text `a:rPr@baseline` at `30000` / `-25000`; no automatic font-size reduction | Forward export is native. PPTX-to-SVG does not reconstruct baseline shift in visible SVG; unchanged imported `txBody` metadata and Edit Native PPTX can still retain the source run | Inline style, other elements, numeric offsets, and combination with an inline formula marker are rejected; structured mathematics uses editable OMML, while a Unicode glyph remains literal text || Solid/gradient text fill and transparency | Canonical solid/gradient fill plus run alpha | DrawingML run fill and alpha | `Native-normalized` | Use the semantic alpha channel, not an unregistered CSS effect || Picture or texture text fill | `<text>` / non-positional `<tspan>` fill referencing one annotated single-image pattern | Editable DrawingML run `a:blipFill` with native stretch or tile | Forward export is native; stretch is `Native-normalized`, tile scale/phase may normalize; reverse import does not reconstruct the fill yet | Requires `data-pptx-text-image-fill="stretch|tile"`, one direct valid image, and no image clip/filter/mask/transform; see [`svg-effects.md` §6.3](../skills/ppt-master/references/svg-effects.md#63-gradients-and-paint-effects) || Text outline | Registered stroke on text | DrawingML run outline | `Native-normalized` | Review when outline carries fine visual meaning || Text alignment | Registered `text-anchor` and paragraph semantics | Paragraph alignment plus normalized text-frame position | `Native-normalized` | Run-level anchoring and browser baseline heuristics are unsupported; exact placement belongs to [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || Vertical text-frame alignment | No canonical generated-SVG control; generated text boxes use top anchoring | Top-anchored DrawingML text body | Imported text-frame anchoring may be normalized, but the main route does not expose a general authoring control | Do not infer vertical alignment from SVG baseline or browser layout behavior |-| East Asian vertical typesetting | No registered generated-SVG control; `writing-mode` is invalid | The main generation route does not author `a:bodyPr@vert` | PPTX-to-SVG import normalizes `eaVert`, `vert`, `wordArtVert`, and `wordArtVertRtl` into upright stacked SVG glyphs; `Direct preservation` applies where a source-preserving native workflow leaves the owning OOXML unchanged | Manual glyph stacking can approximate one visual column but does not create native punctuation-orientation, automatic-reflow, or multi-column behavior; the closed grammar belongs to [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) |+| East Asian vertical typesetting | No registered generated-SVG control; `writing-mode` is invalid | The main generation route does not author `a:bodyPr@vert` | PPTX-to-SVG import normalizes `eaVert`, `vert`, `wordArtVert`, and `wordArtVertRtl` into upright stacked SVG glyphs; `Direct preservation` applies where Edit Native PPTX leaves the owning OOXML unchanged | Manual glyph stacking can approximate one visual column but does not create native punctuation-orientation, automatic-reflow, or multi-column behavior; the closed grammar belongs to [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || Character spacing | Registered `letter-spacing` | DrawingML character spacing | `Native-normalized` | Unsupported CSS typography, out-of-range DrawingML spacing, and negative tracking that collapses a generated run advance or text-frame extent to a non-positive value are rejected under [`svg-effects.md` §6.7](../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || Bulleted paragraph | Recognized leading bullet form | Native DrawingML bullet | `Native-normalized` | Only the registered bullet grammar is promoted || Rotated text | Supported transform on the text object | Rotated text shape | `Native-normalized` | Skewed text and browser-only transforms are unsupported |@@ -273,7 +273,7 @@ See [Animations & Transitions](./animations.md) (technical source: [`references/| Video | Unsupported as an SVG-authored media object | Direct preservation or an explicit poster carrying an ordinary supported hyperlink | A `media` placeholder does not create video || 3D model | Unsupported | Direct preservation or baked preview | No browser-SVG approximation is treated as native 3D || Macro / VBA | Unsupported | Preserve only through a macro-aware direct workflow | The normal generated `.pptx` route does not synthesize VBA |-| Arbitrary Office extension XML | Unsupported | Direct preservation by an owning native workflow | The SVG compiler has no generic OOXML passthrough |+| Arbitrary Office extension XML | Unsupported | Direct preservation by Edit Native PPTX when the owning source object stays unchanged | The SVG compiler has no generic OOXML passthrough |## 12. Reverse mapping: PPTX to project SVGdiff --git a/docs/roadmap.md b/docs/roadmap.mdindex f042321c..7302435e 100644--- a/docs/roadmap.md+++ b/docs/roadmap.md@@ -12,7 +12,7 @@The defining axis is **native depth**: author or preserve more of PowerPoint's own object model, behavior, and reusable structure, release after release — converging with PowerPoint itself. The [positioning charter](./project-positioning.md) states the full thesis; the [PowerPoint ↔ SVG Mapping Guide](./powerpoint-svg-mapping.md) records the current boundary honestly, feature by feature.-Today that axis is expressed through four explicit artifact routes: **Generate PPTX** authors newly designed slides through constrained SVG → DrawingML; **Create Template** produces reusable Brand / Style / Layout / Deck workspaces; **Fill Native PPTX** and **Enhance Native PPTX** preserve existing packages through scoped OOXML operations.+Today that axis is expressed through three explicit artifact routes: **Generate PPTX** authors newly designed slides through constrained SVG → DrawingML; **Create Template** produces reusable Brand / Style / Layout / Deck workspaces; **Edit Native PPTX** imports an existing deck into a source-preserving round-trip workspace and edits only planned pages or overlays.---@@ -86,7 +86,7 @@ A presentation is four layers: what is on the slide, how it is arranged, how it| Slide size | Systematized | The canvas contract selects the presentation format; the SVG `viewBox` is the single geometry truth with fail-closed validation, and every page in a deck must agree on one format || Theme | Systematized | Lock-backed Default export derives each deck's `clrScheme`, major/minor fonts, and Master title/body size defaults from its palette and typography contract. Flat Quick keeps converter-default Theme scaffolding. Structured Quick retains installed per-Master source Themes when available and infers Master title/body size defaults from semantic slot carriers; SVG-derived page colors and fonts remain direct values || Font embedding | Bounded by design | Fonts are never embedded in the package; a brand or web face leads only after confirmed availability on the target system, otherwise export uses a safe family and keeps the intended face recorded in the Design Spec |-| Slide sections | Asymmetric by design | Source-preserving native workflows retain existing section metadata as untouched package structure. Routes that generate or rebuild a slide roster do not author PowerPoint Sections because page roles and optional Design Spec Parts do not form one required, route-wide section contract. Sections change only how the thumbnail rail organizes a deck and never change page appearance; grouping a long deck by hand in PowerPoint takes about a minute and is done once |+| Slide sections | Asymmetric by design | Edit Native PPTX retains existing section metadata when the identity roster leaves presentation structure untouched; a `page_plan.json` roster drops sections. Routes that generate or rebuild a slide roster do not author PowerPoint Sections because page roles and optional Design Spec Parts do not form one required, route-wide section contract. Sections change only how the thumbnail rail organizes a deck and never change page appearance; grouping a long deck by hand in PowerPoint takes about a minute and is done once || Master / Layout | Systematized | Real `p:sldMaster` / `p:sldLayout` parts on structured routes || Placeholders | Systematized | Template workspace contracts, with strict/adaptive exporter behavior derived per deck || Date, footer & slide-number fields | Bounded by design | Structured template routes author real date / footer / slide-number placeholders under the placeholder contract. Free-design decks deliberately keep drawn page numbers and footers as ordinary text: a page numeral is often a design element rather than a standard field, telling the two apart is an intent judgment, and inserting a standard field by hand in PowerPoint takes seconds and is done once |@@ -145,7 +145,7 @@ The Generate PPTX route is built around full control of newly authored shapes, t**The basic need is actually simple**: if you just need "replace Excel data into fixed positions in a PPT template", have the AI write a few lines of `python-pptx`. You don't need this pipeline.-> **Supported boundaries**: Fill Native PPTX (`template-fill-pptx`) directly refills selected source slides. Create Template (`create-template`) derives an internal authored or mirror implementation from the natural-language request and source evidence. Strategist later derives strict/adaptive exporter behavior from the actual template and current content. What remains out of scope is unreviewed, schema-free substitution against arbitrary third-party placeholder systems.+> **Supported boundaries**: Edit Native PPTX (`edit-native-pptx`) imports an existing deck into a round-trip workspace, references unchanged pages byte-for-byte, and edits only planned pages or overlays. Create Template (`create-template`) derives an internal authored or mirror implementation from the natural-language request and source evidence. Strategist later derives strict/adaptive exporter behavior from the actual template and current content. What remains out of scope is unreviewed, schema-free substitution against arbitrary third-party placeholder systems.### Make native PowerPoint charts the defaultdiff --git a/docs/technical-design.md b/docs/technical-design.mdindex 8625044a..7175d661 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -65,9 +65,9 @@ whole-slide screenshot skin remains forbidden. Quick bypasses separateplanning/confirmation, the first-page gate, and preview finalization; sourceunderstanding and resource preparation still run as needed, and one locklessfinal quality gate remains. Exactly one runtime procedure is loaded.-Create Template has its own workspace lifecycle, while Fill Native PPTX and-Enhance Native PPTX operate directly on OOXML; the route table later in this-document covers all four.+Create Template has its own workspace lifecycle, while Edit Native PPTX imports+an existing deck into a source-preserving round-trip workspace; the route table+later in this document covers all three top-level routes.```User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)@@ -86,7 +86,6 @@ User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)[Template Candidate Preparation (Step 3)] — internal only; no UI, wait, selection, template read, or installationPrepare indexed Brand/Style/Layout/Deck candidates and supplied exact rootsStage 1 confirms communication plus free design/template use together; selected workspaces are then validated and installed before Stage 2- Raw PPTX template requests route to template-fill; reusable SVG templates are created by create-template first↓[Strategist] - Stage 1 communication confirmation + final Stage 2 solution/production confirmation → design_spec.md + spec_lock.md↓@@ -164,18 +163,17 @@ Minimal semantic markers do not weaken that closure. Free-design, brand/style-on| Project-canonical SVG syntax, compatible forms, and mapping boundary | The split authority set selected through [`references/shared-standards.md`](../skills/ppt-master/references/shared-standards.md) || Master/Layout/Slide packaging and native-object mapping | SVG-to-PPTX translation; it may reorganize represented content but does not invent visible content || Animations, transitions, speaker notes, and narration | Dedicated sidecars/assets and PPTX package post-processing |-| Direct native-PPTX editing | The selected native workflow's PPTX/OOXML contract |+| Native-PPTX preservation editing | The Edit Native PPTX round-trip workspace and source-preserving exporter |This is a page-design closure rule, not a claim that SVG describes the entire PPTX package. Rebuilding the visible slide from its completed SVG is the relevant invariant; reconstructing notes, audio, timing, relationships, or direct native edits from SVG alone is not.`svg_final/` does not change that boundary. In the default pipeline, Step 7 derives visual previews from `svg_output/`: supported bitmap/SVG resources are inlined when processing succeeds, while EMF/WMF stay external for native passthrough; unresolved ordinary images retain their original references, and the current finalizer counts those processing errors without failing the whole run. These files support IDE/browser inspection and manual insertion as SVG pictures. They are not a second PPTX export route and carry no PowerPoint Convert-to-Shape compatibility contract. Editable shapes come only from the project converter translating `svg_output/` into native DrawingML PPTX.-Existing-PPTX requests split by mutation model: the two native workflows bypass SVG, while `beautify-pptx` remains a Generate PPTX profile that regenerates the visible design:+Existing-PPTX requests split by mutation model: Edit Native PPTX uses source-preserving round-trip authoring, while `beautify-pptx` remains a Generate PPTX profile that regenerates every visible page:| 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 |+| `edit-native-pptx` | an existing PPTX whose native design must survive; new material and delivery overlays are optional | import with `pptx_to_svg.py --roundtrip`, reference unchanged pages, edit selected compact SVGs, then export with `svg_to_pptx.py --roundtrip` | unchanged pages restore byte-for-byte, unchanged objects on edited pages restore natively, and notes/motion remain overlays || `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 |---@@ -193,15 +191,15 @@ Use this table before reasoning about implementation details. Most failed runs s| One or more images contain page frames that must become layered editable slides | Generate PPTX + Image to PPTX (`image-to-pptx`) profile | Codex is currently required and the profile always activates Quick; normalize all represented frames first and map each frame to one slide; restore ordinary text natively; reference-reconstruct low-resolution logos/icons/decorative graphics only with identity, silhouette, proportions, colors, and wordmarks locked where applicable; charts/tables/data graphics require native objects with verifiable values, exact source assets, or `manual_required`; build scenes as at least a clean base plus subject/foreground layers; non-overlapping padded-bbox objects may share one generation plate before grid slicing or SVG bounding-box cropping; no similar substitute or whole-slide screenshot skin || Explicit quick generation | Generate PPTX + `quick-generate` profile | convert/read sources, research factual gaps, and prepare required resources as needed; explicit user requirements are followed and the current agent decides every remaining content, page, visual, and resource question in active context, skips Strategist/confirmation/spec/lock/finalize, hand-authors SVG, passes one lockless final gate, and exports the final PPTX || PPTX as source material, user allows a new story/page structure | Generate PPTX via `ppt_to_md` + `pptx_intake` | PPTX identity/geometry are facts and candidates, not replica constraints |-| Raw PPTX template plus new material/topic | Fill Native PPTX (`template-fill-pptx`) | clone/fill native slides; no SVG generation |+| Raw PPTX template plus new material/topic | Edit Native PPTX (`edit-native-pptx`) | import a round-trip workspace; select, reorder, repeat, or omit pages with `page_plan.json`; edit only planned pages || Existing PPTX, preserve page count/order/wording 1:1, improve layout | Generate PPTX + `beautify-pptx` profile | content and pagination stay locked; explicit Quick intent uses Quick, otherwise Default |-| Finished PPTX, keep content/layout stable, add notes/audio/timings/transitions | Enhance Native PPTX (`native-enhance-pptx`) | direct OOXML patch; no design regeneration |+| Finished PPTX, keep content/layout stable, add notes/audio/timings/transitions | Edit Native PPTX (`edit-native-pptx`) | overlay enhancements on source-preserved slides; visible authoring is not rebuilt || User wants a reusable template workspace from one or more PPTX/SVG files, images/PDFs, documents/websites, brand assets, direct text, or a mixed reference bundle | Create Template (`create-template`) | the fixed entry reads every applicable evidence channel, dispatches one Create Brand, Create Style, Create Layout, or Create Deck child workflow, then returns a workspace root as a Generate Stage-1 candidate; structured children may export a review PPTX || Default Generate reaches planning; an exact current-contract workspace root or current Create Template handoff may already be present | Generate PPTX Stage 1 | Step 3 prepares candidates without interaction; Stage 1 confirms communication plus free design/template use together; ordinary requests default to free design, explicit template intent or any root defaults to template mode, and only one root is preselected; selected workspaces are validated and installed before Stage 2 || User asks to tune object-level animation order/effect/timing | Generate PPTX + `customize-animations` stage | optional export policy via `animations.json` || User asks to preview, select, annotate, or re-export browser edits | Generate PPTX + `live-preview` stage | annotations apply only at defined handoff points |-Ambiguous "optimize this PPT" requests reduce to one discriminator: preserve the original page count/order/wording, or treat the deck as source material and rebuild the story. Both use Generate PPTX; preservation selects the `beautify-pptx` profile, while restructuring uses the normal profile. In either case, explicit Quick intent selects Quick; otherwise Default applies.+Ambiguous "optimize this PPT" requests reduce first to one discriminator: redesign the visible pages through Generate, or preserve the native deck and edit it through Edit Native PPTX. Within Generate, preserving page count/order/wording selects the `beautify-pptx` profile, while rebuilding the story uses the normal profile. Explicit Quick intent selects Quick inside Generate; otherwise Default applies.---@@ -269,11 +267,10 @@ source material or topic+ validation/<output_stem>.report.json+ backup/<ts>/svg_output/ [default output path]-Direct OOXML routes:-analysis/<stem>.slide_library.json + source PPTX + fill_plan.json- └─> template_fill_pptx.py -> exports/*.pptx-source PPTX project copy + enhancement plan + notes/audio/timing assets- └─> native_enhance_pptx.py -> exports/*.pptx+Edit Native PPTX:+source PPTX+ └─> pptx_to_svg.py --roundtrip -> authoring-svg-flat/ [+ page_plan.json]+ └─> svg_to_pptx.py --roundtrip -> exports/*.pptx```The critical split is that `svg_output/` is authored state, while `svg_final/`, `exports/`, and `backup/` are derived delivery or archival state. Deleting that distinction makes validation, re-export, and manual repair much harder to reason about.@@ -324,7 +321,7 @@ Source documents (PDF / DOCX / EPUB / XLSX / PPTX / web pages) are normalized be| Content contract | `sources/` content-type files (primarily `<stem>.md`) | `source_to_md/*` converters + `import-sources` | text, tables, chart values, SmartArt node wording, citations, and source narrative || Structured analysis | `analysis/*.json` / `analysis/*.csv` | intake and analysis tools | PPTX identity, slide geometry, native tables/charts, SmartArt relationships, and measurable image facts such as dimensions, aspect ratio, reference count, media type, and renderability |-For a PPTX source, `project_manager.py import-sources` first moves or copies the original into the project's `sources/` under the ownership boundary, then runs `pptx_intake.py` against that archived path. Only when no explicit or existing canonical same-stem Markdown is present does it finally invoke `ppt_to_md.py`. A normal first import therefore produces both fact channels, while deduplication may skip redundant Markdown conversion and an intake failure is recorded as an import note rather than fabricated analysis. Markdown remains the main generation pipeline's content source. A successful 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.+For a PPTX source, `project_manager.py import-sources` first moves or copies the original into the project's `sources/` under the ownership boundary, then runs `pptx_intake.py` against that archived path. Only when no explicit or existing canonical same-stem Markdown is present does it finally invoke `ppt_to_md.py`. A normal first import therefore produces both fact channels, while deduplication may skip redundant Markdown conversion and an intake failure is recorded as an import note rather than fabricated analysis. Markdown remains the main generation pipeline's content source. A successful 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 `beautify` promotes 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.@@ -392,7 +389,7 @@ These invariants are stronger than ordinary implementation preferences. If a cha| `svg_final/` is mandatory but derived in default delivery | it is regenerated from `svg_output/` for visual preview or manual insertion as an SVG picture; supported resources are inlined when possible while EMF/WMF retain an external-reference exception, and it never becomes the native export source of truth; quick-generate skips this artifact || Native PPTX export reads `svg_output/` by default | converter preserves icons, `preserveAspectRatio`, rounded rects, and native image crop metadata before finalization rewrites them || PowerPoint Convert to Shape is outside the compatibility contract | `svg_final/` may be inserted as an SVG picture, but the converted structure and visual result are not guaranteed and do not constrain the supported SVG feature set |-| Direct OOXML routes do not enter the SVG pipeline | preservation workflows patch native PPTX parts directly |+| Edit Native PPTX does not enter the Generate SVG pipeline | its round-trip workspace uses source-backed `authoring-svg-flat/` pages and a source-preserving exporter rather than generating a new deck || Image facts come from regenerated metadata | `analysis/image_analysis.csv` is re-derived from the live `images/` folder; in the default pipeline Strategist uses source context first and inspects only a specifically ambiguous asset when semantics or safe placement cannot otherwise be resolved, while in `quick-generate` the current agent applies the same bounded analysis while preparing resources; SVG authoring does not rescan source pixels || Raw PPTX templates are not Step 3 candidates | Step 3 accepts only exact reusable-template workspace roots as candidate input |@@ -483,7 +480,7 @@ place both rule sets into the same native Master/Layout graph.When several roots are selected, each distinct root is installed once and every contribution remains its own spec file. The complete set contains at most one contribution per kind; all four kinds may coexist, and a multi-kind project root is atomic. Ownership is resolved segment-level while reading, not field-level: Brand owns identity, Style owns direction/method defaults, Layout owns structure when present, and Deck otherwise owns structure while always retaining descriptive reusable-application context and any identity not overridden by Brand. Only the effective Layout-or-Deck structural roster is installed. Library/explicit provenance never changes that order. The current project's application contract comes only from confirmed Stage 1; Deck context is comparison input for Stage 2, not an override. User confirmation remains highest. Style palette/type defaults never override Brand/Deck identity, and its method/composition expectations must be compatible with the selected structure. A project-local Brand + Layout composition gets its application context from Stage 1 and is not automatically promoted into a reusable library Deck. Duplicate kinds are rejected before installation. This keeps template composition debuggable: the installed set is self-describing, since each file names its kind and id and retains its source body apart from provenance.-**Raw PPTX files cannot be Step 3 workspaces.** Normal Generate may use a PPTX as source material, and `beautify-pptx` may redesign it while preserving page count, order, and per-page wording 1:1; neither treats the source PPTX as a Step 3 template. When a raw PPTX is used as a template or native slide shell and filled with new material, the default route is Fill Native PPTX. If the request permits splitting, merging, dropping, reordering, or narrative restructuring, it remains Generate. Only a request to create a reusable template workspace and reuse that design system in SVG-route Step 3 first runs Create Template and then supplies the generated workspace root.+**Raw PPTX files cannot be Step 3 workspaces.** Normal Generate may use a PPTX as source material, and `beautify-pptx` may redesign it while preserving page count, order, and per-page wording 1:1; neither treats the source PPTX as a Step 3 template. When a raw PPTX is used as a template or native slide shell, or its existing pages are selected, reordered, repeated, or omitted without redesign, the default route is Edit Native PPTX. Requests that split, merge, re-outline, or redesign the deck remain Generate. Only a request to create a reusable template workspace and reuse that design system in SVG-route Step 3 first runs Create Template and then supplies the generated workspace root.**Template contracts are opt-in; catalog references and icons are not.** The asymmetry is intentional: Layout locks reusable structure, Style locks direction/method defaults, Brand locks identity, and Deck combines a recurring application with identity and structure. Page-local Chart/Table references plus icons are reusable primitives that do not by themselves impose a deck-wide contract. Qualitative Structure is instead generated from the current page's relationships by Executor and has no catalog SVG or key. Chart/Table catalogs share the `templates/` tree with reusable workspaces, but their ownership remains page-local.@@ -544,9 +541,9 @@ Standard `<a href>` wraps either a complete visible object/group or one or moreinline `<tspan>` runs. Absolute external URIs become external hyperlinkrelationships; exact 1-based `#slide-N` targets become internal Sliderelationships with `ppaction://hlinksldjump`. The PPTX importer reconstructs-the same anchors for supported shape and run clicks. Fill Native remaps an-internal jump only when its output target is unambiguous, while Enhance Native-leaves existing hyperlink XML and relationships untouched. Mouse-over, custom+the same anchors for supported shape and run clicks. Edit Native PPTX keeps+hyperlink XML and relationships untouched on unchanged pages and, with a page+plan, remaps an internal jump only when its output target is unambiguous. Mouse-over, customshow, navigation-command, program/macro/OLE/file, and arbitrary action settingsremain outside the contract. One source-only transport exception preserves aPowerPoint shape that has both a whole-shape click and inner run links:@@ -564,7 +561,7 @@ Generate routing selects one runtime authority before loading its procedure: [`wGlobal stop/continue policy is authoritative in [`failure-recovery.md`](../skills/ppt-master/workflows/governance/failure-recovery.md); its concrete recovery matrix and resume pointers currently cover Generate PPTX. This section does not duplicate those rules.-Three boundaries are especially important to the architecture. First, 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, default-pipeline cadence is `P01 → first-page gate → remaining pages (one page gate per first-exercised not-exercised item) → final gate`. P01 is a method sample: execution emits a `gate-signal`, then carries resolved method rules into later pages; no page batch interrupts P02 through the final page, and the only mid-run checker call is the first-exercise page gate. `quick-generate` retains serial hand-authoring and uses P01 as its visual-system calibration baseline, skips the first-page gate, and runs one lockless final gate after the complete roster exists. Third, routing is deterministic: raw PPTX template requests, beautify-profile requests, native enhancement, custom-animation stages, live-preview stages, and other registered triggers are not turned into open-ended user route questions when the repository already defines the boundary.+Three boundaries are especially important to the architecture. First, 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, default-pipeline cadence is `P01 → first-page gate → remaining pages (one page gate per first-exercised not-exercised item) → final gate`. P01 is a method sample: execution emits a `gate-signal`, then carries resolved method rules into later pages; no page batch interrupts P02 through the final page, and the only mid-run checker call is the first-exercise page gate. `quick-generate` retains serial hand-authoring and uses P01 as its visual-system calibration baseline, skips the first-page gate, and runs one lockless final gate after the complete roster exists. Third, routing is deterministic: raw PPTX template requests, beautify-profile requests, Edit Native PPTX requests, custom-animation stages, live-preview stages, and other registered triggers are not turned into open-ended user route questions when the repository already defines the boundary.In the default pipeline, 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.@@ -788,15 +785,9 @@ This is easy to miss when reading the code. Shared cleanup modules, the local-re----## Direct OOXML Routes+## Native PPTX Editing-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 `native_enhance_pptx_core.py` and patches the PPTX package from a project copy: notes, global or per-slide page transitions, recorded narration media, slide timings, and related metadata. Intake records a source hash and ordered slide-part roster; validate/apply reject source drift or incomplete requested material. A read-only delivery check inventories package integrity, fonts, media, hidden slides, size, and existing motion at intake/preflight, then audits the candidate before atomic publication. The retired `native_narration_pptx.py` name remains only as a thin CLI compatibility shim. The contract is preservation: existing content, layout, and formatting are not regenerated.--These direct routes share some analysis primitives with the main pipeline, but at different depths. Template Fill consumes the standard PPTX intake slide library. Native Enhance uses `ppt_to_md.py` for content understanding, generates its own lightweight `slide_index.json` from the archived package, and keeps machine delivery reports under `validation/`. Neither shares 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.+Not every PPTX-related request should regenerate every slide. Edit Native PPTX is the current preservation route: it imports the source deck with `pptx_to_svg.py --roundtrip`, references unchanged pages byte-for-byte, edits only planned compact SVG pages, and exports through `svg_to_pptx.py --roundtrip`. `page_plan.json` may select, reorder, repeat, or omit pages; notes, narration, timings, and transitions remain overlays on preserved slides.---@@ -862,7 +853,7 @@ it as a picture or SVG-derived shapes would violate round-trip intent.For supported parsed column/bar/line/area, pie/doughnut, scatter, and bubble charts, a missing baked preview is replaced by a deterministic readable SVG fallback marked `data-pptx-fallback-kind="normalized"`. The importer also covers the verified column/line/area combo subset, canonical four-series OHLC stock, area charts with numeric date axes, verified scatter/bubble charts with the closed `axes.x` / `axes.y` contract, radar, safe `of_pie` `serLines`, axis/title/legend normalization, and bounded bar/column gap/overlap cases. `gapWidth` is accepted only as one integer in `0..500`, and `overlap` only as one integer in `-100..100`; these presentation values intentionally normalize in native output, while malformed, duplicate, or out-of-range input fails closed. Combo plots may retain independent primary/secondary category caches and workbook ranges. XY import derives `scatter_style` from uniform effective series line/marker/smooth state. The closed category/value and XY axis contracts retain kind, position, visibility, label position, number format, min/max/major unit, reversal, and major gridlines for native read-back; the normalized XY fallback consumes only the two `major_gridlines` flags.-ChartEx import is deliberately closed to seven validated data models: `treemap`, `sunburst`, `histogram`, `pareto`, `box_whisker`, `waterfall`, and `funnel`. Their supported hierarchy/category/value/series/subtotal data topology round-trips through native output and reimport. Numeric caches must be non-empty and finite, with canonical non-negative counts/indexes and exact contiguous point topology. Source ChartEx style, axes, labels, and binning may normalize; this is not arbitrary ChartEx import or presentation fidelity. C4/C5 do not expand the normalized renderer, so valid active types outside it still use `data-pptx-fallback-kind="placeholder"` without a source preview. Full `AxisSpec`, arbitrary ChartEx families, arbitrary rich OOXML, rotated/flipped/3D charts, unverified combo/stock/date-axis variants, and other unmodeled semantics remain outside the active import subset. Native replacement may normalize payload-external presentation details and retains the data-model-first warning. Default export keeps preview children as editable DrawingML shapes; only explicit `--native-charts-and-tables` activates PowerPoint-native Chart/Table objects. JSON-first ignores preview freshness; SVG-first requires a present, valid, fresh `data-pptx-fallback-sha256` or native replacement fails closed. Marker presence, semantic tables, and imported chart packages never activate replacement implicitly. This importer/exporter pairing is a reconstruction aid, not a preservation-route substitute for `template-fill-pptx` or `native-enhance-pptx`.+ChartEx import is deliberately closed to seven validated data models: `treemap`, `sunburst`, `histogram`, `pareto`, `box_whisker`, `waterfall`, and `funnel`. Their supported hierarchy/category/value/series/subtotal data topology round-trips through native output and reimport. Numeric caches must be non-empty and finite, with canonical non-negative counts/indexes and exact contiguous point topology. Source ChartEx style, axes, labels, and binning may normalize; this is not arbitrary ChartEx import or presentation fidelity. C4/C5 do not expand the normalized renderer, so valid active types outside it still use `data-pptx-fallback-kind="placeholder"` without a source preview. Full `AxisSpec`, arbitrary ChartEx families, arbitrary rich OOXML, rotated/flipped/3D charts, unverified combo/stock/date-axis variants, and other unmodeled semantics remain outside the active import subset. Native replacement may normalize payload-external presentation details and retains the data-model-first warning. Default export keeps preview children as editable DrawingML shapes; only explicit `--native-charts-and-tables` activates PowerPoint-native Chart/Table objects. JSON-first ignores preview freshness; SVG-first requires a present, valid, fresh `data-pptx-fallback-sha256` or native replacement fails closed. Marker presence, semantic tables, and imported chart packages never activate replacement implicitly. This importer/exporter pairing is a reconstruction aid, not a substitute for the source-preserving Edit Native PPTX round-trip route.---@@ -943,7 +934,7 @@ The tempting simplifications below have explicit costs. Treat them as negative c|---|---|| Do not fuzzy-match template names or style phrases to library paths | Template selection must be deterministic; applying the wrong workspace is harder to recover from than free design || Do not treat a raw PPTX template as a Step 3 template | when used as a template/page shell, it belongs to native cloning/filling; source use, 1:1 beautify, and restructuring instead follow their Generate boundaries rather than passing a PPTX directly to Step 3 |-| Do not merge `template-fill-pptx`, `beautify-pptx`, and `native-enhance-pptx` into one "PPTX optimization" route | their preservation contracts differ: native fill, 1:1 redesign, and direct enhancement are separate operations |+| Merge native filling and enhancement into Edit Native PPTX; keep `beautify-pptx` separate | filling and enhancement share one source-preserving round-trip workspace and `svg_to_pptx.py --roundtrip` exporter; beautify redesigns every page through Generate instead of preserving source slides || Do not script-generate batches of Executor SVG pages | cross-page design judgment depends on sequential main-agent authoring || Do not make `image_analysis.csv` a durable cache | `images/` is a live folder; facts must be regenerated on use || Do not make `svg_final/` the default native PPTX input | `svg_final/` rewrites resources for visual preview, while native conversion needs high-fidelity `svg_output/` semantics |@@ -951,13 +942,13 @@ The tempting simplifications below have explicit costs. Treat them as negative c| Do not auto-enable object-level animations | page transitions are default; object motion is an explicit export policy || Do not default visual review, narration, chart verification, or animation customization into every run | these workflows have narrow triggers and extra dependencies || Do not replace `finalize_svg.py` with a file copy | finalization embeds icons/images, flattens special text, and prepares preview artifacts |-| Do not use `analysis/<stem>.slide_library.json` as a second source of chart values in the main pipeline | Markdown owns content values; intake chart/table entries are structural digests unless a direct-PPTX workflow owns them |+| Do not use `analysis/<stem>.slide_library.json` as a second source of chart values in the main pipeline | Markdown owns content values; intake chart/table entries are structural digests unless the beautify profile owns the full native-object facts |---## Routes and Supporting Runbooks-[`workflows/index.md`](../skills/ppt-master/workflows/index.md) is a maintainer-only inventory and does not enter the task-loading chain. Runtime route selection is authoritative in [`workflows/routing.md`](../skills/ppt-master/workflows/routing.md). PPT Master has exactly four top-level artifact routes: Generate PPTX, Create Template, Fill Native PPTX, and Enhance Native PPTX. A user request enters one of those routes; no supporting runbook competes with them.+[`workflows/index.md`](../skills/ppt-master/workflows/index.md) is a maintainer-only inventory and does not enter the task-loading chain. Runtime route selection is authoritative in [`workflows/routing.md`](../skills/ppt-master/workflows/routing.md). PPT Master has exactly three top-level artifact routes: Generate PPTX, Create Template, and Edit Native PPTX. A user request enters one of those routes; no supporting runbook competes with them.Supporting files stay separate only to keep route contracts focused and load optional context on demand:@@ -967,7 +958,7 @@ Supporting files stay separate only to keep route contracts focused and load opt| Template child workflows | `create-brand`, `create-style`, `create-layout`, `create-deck` | Create Template dispatches exactly one for identity-only, roster-free direction/method, brand-neutral/application-neutral structure, or a recurring application with integrated identity/structure || Template-input stage | `apply-template-workspace` | Runs after Default Stage 1 confirms at least one workspace and before Stage 2; free design skips installation, while Quick may provide direct exact-root input || Generation stages | `topic-research`, `resume-execute`, `refine-spec`, `verify-charts`, `visual-review`, `live-preview`, `customize-animations` | Generate PPTX at their defined intake, planning, editing, quality, or post-processing points |-| Shared stage | `generate-audio` | Generate PPTX post-processing or Enhance Native PPTX narration integration |-| Governance | `failure-recovery` | Global stop/continue policy for all four routes; concrete recovery matrix and resume pointers for Generate PPTX |+| Shared stage | `generate-audio` | Generate PPTX post-processing or Edit Native PPTX narration integration |+| Governance | `failure-recovery` | Global stop/continue policy for all three routes; concrete recovery matrix and resume pointers for Generate PPTX |This classification is a responsibility boundary, not a filename preference. A new top-level route is justified only by a distinct artifact lifecycle and mutation model; kind-specific execution inside Create Template remains a child workflow, optional route behavior remains a profile or stage, and cross-route policy remains governance.diff --git a/docs/templates-guide.md b/docs/templates-guide.mdindex 29da8ba4..3cf72429 100644--- a/docs/templates-guide.md+++ b/docs/templates-guide.md@@ -18,7 +18,7 @@ Choose the route by the artifact you already have and the result you want:| Starting point and goal | Route | Copy-ready request ||---|---|---|-| A raw `.pptx`; keep its existing slide shells and replace content | **Fill Native PPTX** | `Fill projects/source/template.pptx with projects/source/content.md.` |+| A raw `.pptx`; keep its existing slide shells and replace content | **Edit Native PPTX** | `Fill projects/source/template.pptx with projects/source/content.md; keep its design and use only the pages that fit.` || A reusable Brand/Style/Layout/Deck workspace; generate a fresh deck | **Generate PPTX → Stage-1 template controls** | `Make a deck from sources/report.pdf with template skills/ppt-master/templates/layouts/presentation_core/.` || A PPTX, SVG set, brand guide, website, images, or mixed references; first build a reusable system | **Create Template → Generate PPTX** | `Use /create-template to create a reusable Deck workspace from projects/brand/our_deck.pptx.` |diff --git a/docs/zh/animations.md b/docs/zh/animations.mdindex 3626747d..3a354caa 100644--- a/docs/zh/animations.md+++ b/docs/zh/animations.md@@ -248,7 +248,7 @@ PPT Master 会严格校验动画设置:未知效果或 Start 模式、非法| 静态结构 | 背景、Master/Layout 内容、placeholder 与页面框架保持静态 || 不支持的对象 build | 不会从分组 SVG 推导段落/文字范围 build、自定义自由动作路径、原生 Chart/SmartArt 分步 build 或媒体播放命令 || 输出路线 | 动画存在于从 `svg_output/` 生成的原生 PPTX;`svg_final/` 只是静态预览 |-| 现有 PPTX 路线 | Template Fill 与 Native Enhance 保留源对象动画,不把它翻译成生成路线的动画模型 |+| Edit Native PPTX | 通过 round-trip 工作区保留来源对象动画,不把它翻译成生成路线的动画模型 || PPTX-to-SVG 回导 | 只重建当前注册表内具有精确原生时长且可唯一映射到顶层 group 的记录;高级/build/media timing 保留诊断 || 播放兼容性 | Microsoft PowerPoint 桌面版是主要验证目标;Keynote、WPS、LibreOffice 与较旧 Office 可能重新映射或忽略个别效果 |diff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.mdindex 435204da..a1cf3af3 100644--- a/docs/zh/audio-narration.md+++ b/docs/zh/audio-narration.md@@ -22,7 +22,7 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg1. **备注本身就是为 TTS 写的口播稿**。PPT Master 的 notes 规范刻意产出适合朗读的散文——没有 `[过渡]` / `[停顿]` 这种舞台标记,也没有 `要点:` / `时长:` 这种 meta 行——念出来的内容就是页面上的内容。2. **AI 替你选音色**。当你提出生成旁白时,AI 根据 deck 的主语言(`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …)和所选 provider 拉取或解释可用音色,挑出 3–6 个候选,并用当前聊天语言为每个写一句调性说明(如“稳重男声·适合财报”)。语速/风格也会基于 notes 信息密度给出推荐值。-3. **配置一次确定**。Default Generate 和 Enhance Native 会一次确认 provider、音色、语速、是否嵌入 PPTX,以及是否继续导出视频。Quick 直接采用明确值,并自动补齐未指定的 provider、音色、语速和嵌入方式;只有明确要求直接交付视频时才开启视频导出。+3. **配置一次确定**。Default Generate 和 Edit Native PPTX 会一次确认 provider、音色、语速、是否嵌入 PPTX,以及是否继续导出视频。Quick 直接采用明确值,并自动补齐未指定的 provider、音色、语速和嵌入方式;只有明确要求直接交付视频时才开启视频导出。4. **执行**。Edge、ElevenLabs、MiniMax,以及支持时间戳的 CosyVoice 音色,会依据同一次合成返回的 provider 计时,把每页音频和 SRT 一起写入 `audio/`;Qwen 和显式 CosyVoice 纯音频模式只写音频。完整生成成功后会原子写入 `audio/manifest.json` 记录来源。对于选择旁白 cue 同步的 Generate PPTX,逐页 SRT 与规范自定义动画会让 AI 将当前 SVG 内容组映射到编号后的 SRT cue,并派生无点击的 `narration_animations.json`;与旁白无关的自定义动画保留规范计时,没有动画 sidecar 时则继承基础导出的已解析 motion。随后再导出带音频的 PPTX;存在逐页 SRT 时,才从该 PPTX 读回实际计时并合并。自动视频交付继续调用 PowerPoint 原生编码器,存在 cue 时再完成验收后的混音;显式选择实时放映录制时,则捕获 PowerPoint 实际全屏画面与系统音频、跳过混音,并将交付字幕对齐到验收后的录屏。不支持长音频导入或自动拆分。字幕保持为外部 SRT 文件:PPT Master 不把字幕嵌入 PPTX,也不烧录进 MP4。自动视频导出委托给本机 Windows PowerPoint,并不是另一套渲染器。@@ -162,8 +162,8 @@ python3 skills/ppt-master/scripts/video_subtitles.py <project_path> \```发送任何 TTS 请求前,`notes_to_audio.py` 会确认每个 Generate SVG 页面或-Native Enhance 页面都有可读且非空的逐页备注。缺失或空备注会返回退出码-`2`;必须先生成这些备注,再重新运行音频生成。+Edit Native PPTX 输出页面都有可读且非空的逐页备注。缺失或空备注会返回+退出码 `2`;必须先生成这些备注,再重新运行音频生成。edge 模式下 `--voice` 是必填项,可用 `--list-voices --locale <locale>` 查看音色。Edge 默认同时生成最多 3 页音频/SRT。可用 `--concurrency <N>` 调整;diff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex f64dfb10..5975067f 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -334,12 +334,12 @@ Quick 省略独立规划阶段,但仓库没有文档化的测量或保证表## Q: 我手上有一份现成的 PPT,想基于它做东西,该走哪条路?-把「用一份已有 PPT」拆成两个问题:**留不留它的内容**、**留不留它的设计(版式 + 视觉)**。四种组合对应三种生成路径,以及直接保留原文件这一种无需生成的结果:+把「用一份已有 PPT」拆成两个问题:**留不留它的内容**、**留不留它的设计(版式 + 视觉)**。四种组合对应三种处理路径,以及直接保留原文件这一种无需生成的结果:| 意图 | 路线 | 固定不变的东西 ||---|---|---|| 留内容 + 重做版式 | **Generate PPTX + beautify profile** | 页数、页序、每页文字、图表/表格数据 |-| 换内容 + 留设计 | **Fill Native PPTX** | 原生页面设计;可选择、乱序、复用源页 |+| 换内容 + 留设计 | **Edit Native PPTX** | 保留原生设计;未改页面逐字节保留,选中页面可编辑、重排、重复或省略 || 只留内容,设计与分页都重来 | **Generate PPTX** | 源事实;故事结构和页数都可重构 || 留内容 + 留设计 | 不必生成 | 直接用原文件 |@@ -347,7 +347,7 @@ Quick 省略独立规划阶段,但仓库没有文档化的测量或保证表用 **主管线** 的前提是:原 PPT 只是内容材料。流程会用 `ppt_to_md` 抽成 Markdown,并读取 `analysis/` 里的 PPTX intake 事实,再由 Strategist 自由重构大纲(合页 / 拆页 / 换序)。典型说法是「用这份 PPT 的内容重做一份更好的」或「提炼成 10 页高管汇报」。-beautify 和主管线的一句话判别:**原来的分页是要保留的信息,还是只是前一作者的结构、可以推翻?** 保留 → beautify;推翻 → 主管线。落到硬判据就是**页数 / 页序**:只要它有任何变化——拆页、合页、删页、换序,乃至「一字不改、只把某张太挤的页拆开排得更好看」——都属于重分页,走主管线。beautify 严格 1:1。+只有在可见设计会被重新生成时,才用这句话区分 beautify 与普通 Generate:**原来的分页是要保留的信息,还是只是前一作者的结构、可以推翻?** 保留 → beautify;推翻 → 普通 Generate。beautify 严格 1:1。若原生设计必须保留,则改走 Edit Native PPTX;它的 `page_plan.json` 可以选择、重排、重复或省略既有页面,而不重设计这些页面。如果用户说法含糊,比如「把这份 PPT 做得更专业一点」「优化一下这个 deck」,AI 应先问一句:**要保留原页数、页序和每页文字,只做美化;还是把 PPT 当素材,重新梳理成一份新故事?**@@ -357,23 +357,24 @@ beautify 和主管线的一句话判别:**原来的分页是要保留的信息## Q: 我已经有一份做好的 `.pptx`,能不能复用它的设计、只填新内容?-可以——这就是 **套模板(template fill)** 路径,独立于 SVG 生成管线。把你现成的 `.pptx` 连同素材(或一个主题)给 AI,说「套模板 / 把这些填回去」。它会把你的 deck 当作原生页面库,只挑适合新内容的页面(可乱序、可重复),把新文字——以及原生表格单元格、图表数据——直接写回原始 OOXML。+可以——这就是 **Edit Native PPTX** 路线,独立于 Generate。把现成的 `.pptx` 连同素材(或一个主题)给 AI,说「套模板 / 把这些填回去」。它会把 deck 导入 `projects/` 下保留来源的 round-trip 工作区,把来源页面当作原生页面库,并在编辑选中内容前选择、重排、重复或省略页面。-输出仍是 100% 原生可编辑的 PowerPoint:原设计、母版、图片、动画都保留,且只导出计划中的页面。它刻意**不**创作新的版式拓扑,也不替换源图。`fill_plan.json` 中有序的 `slides` 清单可以省略、乱序或重复源页面壳,因此输出页数可以不同于源文件。一份 deck 的页面结构本身承载着逻辑(总分、对比、递进),所以应挑选结构本就契合内容的页面,而不是硬塞进去。若源页面库缺少所需的新结构,请走普通 Generate,或先 Create Template、再从产出的工作区 Generate。完整步骤:[套模板工作流](../../skills/ppt-master/workflows/template-fill-pptx.md)。+未改的输出页面会被引用并逐字节恢复;在编辑过的页面上,未改对象恢复为原生形态,只有改过的对象会重建。`page_plan.json` 中有序的 `pages` 清单使用 `source_slide` 和可选的 SVG 副本文件名选择、重排、重复或省略来源页面。讲稿、旁白、计时和转场都作为保留页面上的叠加内容。一份 deck 的页面结构本身承载着逻辑(总分、对比、递进),所以应挑选结构本就契合内容的页面,而不是硬塞进去。若源页面库缺少所需的新结构,请走普通 Generate,或先 Create Template、再从产出的工作区 Generate。完整步骤:[Edit Native PPTX 工作流](../../skills/ppt-master/workflows/edit-native-pptx.md)。---## Q: 内容填到了意料之外的位置——怎么查看 PPT Master 到底识别到了什么?-两条消费 PPTX 的路径都会在生成之前先写出一份只读分析报告,读它就能确认哪些图形被识别到了。+Edit Native PPTX 与 Create Template 都会在开始创作前写出可读清单,用它确认识别到的页面和对象。-**套模板(Fill Native PPTX)**:+**Edit Native PPTX**:```bash-python3 skills/ppt-master/scripts/pptx_intake.py <deck.pptx> -o <analysis_dir>+python3 skills/ppt-master/scripts/pptx_to_svg.py <deck.pptx> \+ -o projects/<slug> --inheritance-mode both --roundtrip```-`<stem>.slide_library.json` 会逐页列出每个可填充槽位的几何、段落数与文字度量,并单独给出 `tables` 与 `charts`。带样式的普通文本框同样算槽位——图形不必是真正的占位符才能被填充。+`authoring-svg-flat/authoring_summary.json` 会列出来源页面清单,以及逐页文字、图片、矢量、placeholder 和 source-reference 数量;只打开确实要判断或编辑的紧凑 SVG 页面。**Create Template**:diff --git a/docs/zh/getting-started.md b/docs/zh/getting-started.mdindex 6ced019d..c346d3b7 100644--- a/docs/zh/getting-started.md+++ b/docs/zh/getting-started.md@@ -51,12 +51,12 @@ python3 -m pip install -r "<installed-skill-dir>/requirements.txt"| 你想要… | 路径 | 会发生什么 ||---|---|---|-| **用这份 deck 的原生页面壳承载新内容** | Fill Native PPTX | 克隆选中的源页面,并在 OOXML 中直接改写文字 / 表格 / 图表数据。来源设计保持原生;输出是受现有页面壳约束的新回填 deck。 |+| **用这份 deck 的原生页面壳承载新内容** | Edit Native PPTX | 导入 round-trip 工作区;未改页面逐字节恢复,`page_plan.json` 可选页、重排、重复或省略,且只编辑计划中的页面。 || **先建立可复用设计系统,再生成新 deck** | Create Template → Generate PPTX | 从参考材料创建经过验证的 Brand、Style、Layout 或 Deck 工作区,再创作一份新 deck。新故事、结构与页数都可以不同于来源。 |-前者:把 `.pptx` 连同素材(或一个主题)给 AI,说「套模板」——见 [套模板工作流](../../skills/ppt-master/workflows/template-fill-pptx.md)。本节其余部分讲 create-template。+前者:把 `.pptx` 连同素材(或一个主题)给 AI,说「套模板」——见 [Edit Native PPTX 工作流](../../skills/ppt-master/workflows/edit-native-pptx.md)。本节其余部分讲 create-template。-**想把某份现成 PowerPoint 做成可复用工作区,必须显式请求 Create Template 路线。** 原生 `.pptx` 加新材料默认属于 Fill Native PPTX,并不是 Generate 可以直接消费的模板工作区。先创建工作区:+**想把某份现成 PowerPoint 做成可复用工作区,必须显式请求 Create Template 路线。** 原生 `.pptx` 加新材料默认属于 Edit Native PPTX,并不是 Generate 可以直接消费的模板工作区。先创建工作区:```你:用 /create-template 从 projects/brand/our_deck.pptx 创建一个可复用 Deck 模板diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.mdindex e99793d2..12f407fb 100644--- a/docs/zh/powerpoint-svg-mapping.md+++ b/docs/zh/powerpoint-svg-mapping.md@@ -52,7 +52,7 @@ PowerPoint 意图## 2. Master、Layout、背景与占位符功能-**路线边界**:主 SVG 流程中的自由生成与 brand-only 项目从规划到导出始终使用 `pptx_structure.mode: flat`;`flat` 不是等待导出器自动升级的临时状态。即使多个页面出现相同 Logo、页脚或排版,导出器也不得据此切换到 `structured`,不得自动提升到 Master/Layout,也不得推断占位符或去重。若输出需要可复用的原生 Master、Layout 或占位符,Step 3 必须消费一个已校验的 deck/layout 模板工作区;没有该工作区时,先走 [`create-template`](../../skills/ppt-master/workflows/create-template.md),再返回主流程。flat 导出创建的最小 Master 和 Blank Layout 只是 PPTX 格式必需的包结构,不是从页面总结出的设计母版。直接使用原始 PPTX 模板填充新内容仍走 [`template-fill-pptx`](../../skills/ppt-master/workflows/template-fill-pptx.md)。+**路线边界**:主 SVG 流程中的自由生成与 brand-only 项目从规划到导出始终使用 `pptx_structure.mode: flat`;`flat` 不是等待导出器自动升级的临时状态。即使多个页面出现相同 Logo、页脚或排版,导出器也不得据此切换到 `structured`,不得自动提升到 Master/Layout,也不得推断占位符或去重。若输出需要可复用的原生 Master、Layout 或占位符,Step 3 必须消费一个已校验的 deck/layout 模板工作区;没有该工作区时,先走 [`create-template`](../../skills/ppt-master/workflows/create-template.md),再返回主流程。flat 导出创建的最小 Master 和 Blank Layout 只是 PPTX 格式必需的包结构,不是从页面总结出的设计母版。保留原设计并向原始 PPTX 填充新内容时,走 [`edit-native-pptx`](../../skills/ppt-master/workflows/edit-native-pptx.md)。| PowerPoint 功能 | 项目表达 | PPTX 结果 | 回导与保真度 | 校验边界 ||---|---|---|---|---|@@ -120,18 +120,18 @@ PowerPoint 意图| 字号 | 有限、无单位的 SVG px,例如 `font-size="24"` | DrawingML 百分之一磅;`1 px = 0.75 pt` | 单位转换后为 `Native-stable` | 生成创作只使用无单位 px;已登记历史单位是会产生 warning 的兼容输入,未知单位为 error;DrawingML 下限为 1 pt || 字重 | `<text>`/`<tspan>` 上已登记的 `font-weight` | DrawingML 常规/粗体 run 开关 | `Native-normalized`;数值字重会折叠到 DrawingML 布尔边界 | 精确取值语法与别名属于 [`svg-effects.md` §6.7](../../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || 斜体、下划线与删除线 | `<text>`/`<tspan>` 上已登记的 `font-style` / `text-decoration` | DrawingML 斜体、下划线与删除线 run 属性 | 已登记 token 为 `Native-stable` | 拒绝未知 token;精确语法属于 [`svg-effects.md` §6.7](../../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) |-| 普通文本上标与下标 | `<tspan>` 上精确的直接属性 `baseline-shift="super|sub"`;显式 run `font-size` 与之独立 | 可编辑普通文本 `a:rPr@baseline`,取值为 `30000` / `-25000`;不会自动缩小字号 | 前向导出为原生能力。PPTX-to-SVG 不在可见 SVG 中重建 baseline shift;未修改的导入 `txBody` metadata 与源保留型原生工作流仍可保留来源 run | 拒绝 inline style、其他元素、数值偏移及与行内公式 marker 组合;结构化数学使用可编辑 OMML,Unicode 字形仍是字面文字 |+| 普通文本上标与下标 | `<tspan>` 上精确的直接属性 `baseline-shift="super|sub"`;显式 run `font-size` 与之独立 | 可编辑普通文本 `a:rPr@baseline`,取值为 `30000` / `-25000`;不会自动缩小字号 | 前向导出为原生能力。PPTX-to-SVG 不在可见 SVG 中重建 baseline shift;未修改的导入 `txBody` metadata 与 Edit Native PPTX 仍可保留来源 run | 拒绝 inline style、其他元素、数值偏移及与行内公式 marker 组合;结构化数学使用可编辑 OMML,Unicode 字形仍是字面文字 || 纯色/渐变文本填充与透明度 | 规范纯色/渐变 fill 加 run alpha | DrawingML run fill 与 alpha | `Native-normalized` | 使用语义 alpha 通道,不使用未登记 CSS 效果 || 图片或纹理文本填充 | `<text>` / 不带定位的 `<tspan>` 的 fill 引用一个带注解的单图 `pattern` | 可编辑 DrawingML run `a:blipFill`,使用原生 `stretch` 或 `tile` | 正向导出为原生能力;`stretch` 为 `Native-normalized`,`tile` 的缩放/相位可能归一化;回导暂不重建该填充 | 要求 `data-pptx-text-image-fill="stretch|tile"`、一个直接有效的 `<image>`,且 `<image>` 不带 `clip-path` / `filter` / `mask` / `transform`;见 [`svg-effects.md` §6.3](../../skills/ppt-master/references/svg-effects.md#63-gradients-and-paint-effects) || 文本轮廓 | 文本上已登记 stroke | DrawingML run outline | `Native-normalized` | 轮廓承载精细视觉意义时需复核 || 文本对齐 | 已登记的 `text-anchor` 与段落语义 | 段落对齐加归一化文本框位置 | `Native-normalized` | 不支持 run 级锚定与浏览器 baseline 启发式;精确放置属于 [`svg-effects.md` §6.7](../../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || 文本框垂直对齐 | 无规范生成 SVG 控制;生成文本框使用顶部对齐 | 顶部对齐的 DrawingML text body | 导入的文本框垂直锚定可能被归一化,但主路线不公开通用创作控制 | 不得从 SVG baseline 或浏览器排版行为推断垂直对齐 |-| 东亚竖排文字 | 没有已登记的生成 SVG 控制;`writing-mode` 为非法属性 | 主生成路线不创作 `a:bodyPr@vert` | PPTX-to-SVG 回导把 `eaVert`、`vert`、`wordArtVert` 与 `wordArtVertRtl` 归一化为正立字形逐字堆叠的 SVG 文本;源保留型原生工作流在不改所属 OOXML 时为 `Direct preservation` | 手工堆叠字形可以近似单列外观,但不会产生原生标点朝向、自动续排或多栏行为;封闭文法见 [`svg-effects.md` §6.7](../../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) |+| 东亚竖排文字 | 没有已登记的生成 SVG 控制;`writing-mode` 为非法属性 | 主生成路线不创作 `a:bodyPr@vert` | PPTX-to-SVG 回导把 `eaVert`、`vert`、`wordArtVert` 与 `wordArtVertRtl` 归一化为正立字形逐字堆叠的 SVG 文本;Edit Native PPTX 在不改所属 OOXML 时为 `Direct preservation` | 手工堆叠字形可以近似单列外观,但不会产生原生标点朝向、自动续排或多栏行为;封闭文法见 [`svg-effects.md` §6.7](../../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || 字符间距 | 已登记 `letter-spacing` | DrawingML 字符间距 | `Native-normalized` | 按 [`svg-effects.md` §6.7](../../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) 拒绝不受支持的 CSS 排版、超出 DrawingML 范围的间距,以及导致生成 run advance 或文本框 extent 非正的负字距 || 项目符号段落 | 已识别的前导项目符号形式 | 原生 DrawingML bullet | `Native-normalized` | 仅提升已登记 bullet 语法 || 旋转文本 | 文本对象上受支持的 transform | 旋转文本 shape | `Native-normalized` | 倾斜文本与浏览器专属 transform 不受支持 || 文本阴影或发光 | 受支持 filter/effect 合同 | 一个原生外阴影或发光 | `Approximate` | 仅支持一个已登记效果图;实质效果需复核 |-| WordArt、文本变形或沿路径文本 | 装饰文字使用已准备的图片资产,或用普通 `<text>` 作为可编辑兜底 | 图片或普通文字;不新建原生 WordArt | 源保留型原生路线为 `Direct preservation`;其他路线需要 `Bake-required` 或使用受支持载体重建 | 不登记任何生成 SVG 的 WordArt / 变形 / 路径文字属性;浏览器可渲染不代表 PowerPoint 受支持 |+| WordArt、文本变形或沿路径文本 | 装饰文字使用已准备的图片资产,或用普通 `<text>` 作为可编辑兜底 | 图片或普通文字;不新建原生 WordArt | Edit Native PPTX 为 `Direct preservation`;其他路线需要 `Bake-required` 或使用受支持载体重建 | 不登记任何生成 SVG 的 WordArt / 变形 / 路径文字属性;浏览器可渲染不代表 PowerPoint 受支持 |## 5. PowerPoint 图片功能@@ -261,7 +261,7 @@ sidecar 工作流见[转场与动画](./animations.md)(技术规范源为 [`re| 视频 | 不支持作为 SVG 创作媒体对象 | 直接保留,或使用带普通受支持超链接的显式封面 | `media` 占位符不创建视频 || 3D 模型 | 不支持 | 直接保留或烘焙 preview | 不将浏览器 SVG 近似当作原生 3D || 宏 / VBA | 不支持 | 仅通过感知宏的直接工作流保留 | 普通生成 `.pptx` 路线不生成 VBA |-| 任意 Office 扩展 XML | 不支持 | 由拥有该语义的原生工作流直接保留 | SVG 编译器不提供通用 OOXML 透传 |+| 任意 Office 扩展 XML | 不支持 | Edit Native PPTX 在所属来源对象不变时直接保留 | SVG 编译器不提供通用 OOXML 透传 |## 12. 反向映射:PPTX 到项目 SVGdiff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.mdindex 214268ae..d7ac8b08 100644--- a/docs/zh/roadmap.md+++ b/docs/zh/roadmap.md@@ -12,7 +12,7 @@项目的主轴是**原生深度**:逐版本创作或保留更多 PowerPoint 自身的对象模型、行为与可复用结构——持续向 PowerPoint 本身靠拢。完整论述见[项目定位章程](./project-positioning.md);[PowerPoint ↔ SVG 映射指南](./powerpoint-svg-mapping.md)逐特性诚实记录当前边界。-这条主轴今天体现为四条显式产物路线:**Generate PPTX** 通过受约束的 SVG → DrawingML 创作全新设计的页面;**Create Template** 产出可复用的 Brand / Style / Layout / Deck 模板工作区;**Fill Native PPTX** 与 **Enhance Native PPTX** 通过限定范围的 OOXML 操作保留既有文件包。+这条主轴今天体现为三条显式产物路线:**Generate PPTX** 通过受约束的 SVG → DrawingML 创作全新设计的页面;**Create Template** 产出可复用的 Brand / Style / Layout / Deck 模板工作区;**Edit Native PPTX** 把既有 deck 导入保留来源的 round-trip 工作区,只编辑计划中的页面或叠加内容。---@@ -86,7 +86,7 @@| 画布尺寸 | 系统化 | 画布契约选定演示文稿格式;SVG `viewBox` 是页面几何的唯一真值,配 fail-closed 校验,且同一 deck 的所有页面必须使用同一格式 || Theme | 系统化 | 有锁的 Default 导出根据配色与字体合同逐 deck 派生 `clrScheme`、major/minor 字体与 Master 标题/正文默认字号。Flat Quick 保留转换器默认 Theme 脚手架;structured Quick 在工作区提供时保留逐 Master 源 Theme,并从语义 slot carrier 推导 Master 标题/正文字号默认值;SVG 派生的页面颜色与字体仍按直接值写入 || 字体嵌入 | 有意边界 | 从不在包内嵌入字体;品牌 / 网络字体只有确认目标系统可用后才领衔,否则导出安全字体族,并把原意向字体记录在 Design Spec 中 |-| 幻灯片节 | 有意的不对称 | 源保留型原生路线把既有节元数据作为未改动的包结构保留;生成或重建页面列表的路线不创作 PowerPoint 原生节,因为页面角色与可选的 Design Spec Part 并不构成所有路线都具备的必需章节合同。节只改变缩略图栏的组织方式,从不改变任何页面外观;长 deck 需要分组时,在 PowerPoint 里手动分节约一分钟,且只做一次 |+| 幻灯片节 | 有意的不对称 | Edit Native PPTX 在 identity roster 不改 presentation 结构时保留既有节元数据;使用 `page_plan.json` 重建页面清单时会丢弃节。生成或重建页面列表的路线不创作 PowerPoint 原生节,因为页面角色与可选的 Design Spec Part 并不构成所有路线都具备的必需章节合同。节只改变缩略图栏的组织方式,从不改变任何页面外观;长 deck 需要分组时,在 PowerPoint 里手动分节约一分钟,且只做一次 || Master / Layout | 系统化 | 结构化路线输出真实的 `p:sldMaster` / `p:sldLayout` part || Placeholder | 系统化 | 模板工作区契约,strict/adaptive 导出行为逐 deck 推导 || 日期、页脚与页码字段 | 有意边界 | 结构化模板路线按 placeholder 契约创作真实的日期 / 页脚 / 页码 placeholder。自由设计路线有意让画出的页码与页脚保持普通文本:页码数字经常本身就是设计元素而非标准字段,区分两者是意图判断;真需要标准页码域时在 PowerPoint 里手动插入只要几秒,且只做一次 |@@ -145,7 +145,7 @@ Generate PPTX 路线围绕完全可控的新形状、文字与版式创作。结**基础诉求其实很简单**:如果只是「固定位置替换 Excel 数据到 PPT 模板」,直接让 AI 写一段 `python-pptx` 脚本即可,几行代码搞定,不需要本项目这套管线。-> **已支持边界**:Fill Native PPTX(`template-fill-pptx`)直接回填选中的源页面;Create Template(`create-template`)根据自然语言请求和来源证据,在内部推导重新创作或 mirror 物化实现;Strategist 再根据真实模板和当前内容推导 strict/adaptive 导出行为。仍不做未经审查、没有契约的任意第三方 placeholder 全自动替换。+> **已支持边界**:Edit Native PPTX(`edit-native-pptx`)把既有 deck 导入 round-trip 工作区,逐字节引用未改页面,只编辑计划中的页面或叠加内容;Create Template(`create-template`)根据自然语言请求和来源证据,在内部推导重新创作或 mirror 物化实现;Strategist 再根据真实模板和当前内容推导 strict/adaptive 导出行为。仍不做未经审查、没有契约的任意第三方 placeholder 全自动替换。### 把原生 PowerPoint 图表设为默认路线diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex f7002fb5..1e1bf58e 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -40,7 +40,7 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使## Generate PPTX 路线架构-下图描述 Generate PPTX 的默认生命周期。`beautify-pptx` fidelity profile 默认使用该生命周期;同一请求明确要求快速模式时,则改用 `quick-generate`。图片还原为 PPTX 是 Generate 内另一个 fidelity profile:它当前要求 Codex 并始终直接启用 `quick-generate`,因此不进入 Default 运行时,也不需要用户另行说明“快速模式”。其他 Agent host 尚未适配该 profile,不对其行为作支持或承诺。图片还原为 PPTX 把每个规范化页面画面映射为一张幻灯片,以可见像素为表面真值,并原生还原普通文字。低清 Logo、图标、徽标或其他身份图形可由 Codex 根据参考图重建,但必须锁定身份、轮廓、比例、颜色和字标,禁止换成仅仅相似的替代物。照片和插画场景至少拆成干净背景层与人物 / 前景层。多个带 padding 包围盒且互不重叠的对象可共用一次生成 plate,再通过 grid slice 或 SVG bbox crop 拆成独立对象。整页截图 skin 始终禁止。Quick 会绕过独立规划 / 确认、首屏 gate 与预览终稿化;来源理解和资源准备仍按需运行,一次无锁最终质量门始终保留。每次只加载一份运行时流程。Create Template 有独立的工作区生命周期;Fill Native PPTX 与 Enhance Native PPTX 直接操作 OOXML。本文后续路线表会覆盖全部四条顶层路线。+下图描述 Generate PPTX 的默认生命周期。`beautify-pptx` fidelity profile 默认使用该生命周期;同一请求明确要求快速模式时,则改用 `quick-generate`。图片还原为 PPTX 是 Generate 内另一个 fidelity profile:它当前要求 Codex 并始终直接启用 `quick-generate`,因此不进入 Default 运行时,也不需要用户另行说明“快速模式”。其他 Agent host 尚未适配该 profile,不对其行为作支持或承诺。图片还原为 PPTX 把每个规范化页面画面映射为一张幻灯片,以可见像素为表面真值,并原生还原普通文字。低清 Logo、图标、徽标或其他身份图形可由 Codex 根据参考图重建,但必须锁定身份、轮廓、比例、颜色和字标,禁止换成仅仅相似的替代物。照片和插画场景至少拆成干净背景层与人物 / 前景层。多个带 padding 包围盒且互不重叠的对象可共用一次生成 plate,再通过 grid slice 或 SVG bbox crop 拆成独立对象。整页截图 skin 始终禁止。Quick 会绕过独立规划 / 确认、首屏 gate 与预览终稿化;来源理解和资源准备仍按需运行,一次无锁最终质量门始终保留。每次只加载一份运行时流程。Create Template 有独立的工作区生命周期;Edit Native PPTX 则把既有 deck 导入保留来源的 round-trip 工作区。本文后续路线表会覆盖全部三条顶层路线。```用户输入 (PDF/DOCX/XLSX/PPTX/URL/Markdown/主题文本)@@ -59,7 +59,6 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使[模板候选准备(Step 3)] — 仅内部执行;不打开 UI、不等待、不选择、不读取或安装模板准备四类索引候选与本次提供的精确 rootStage 1 同时确认沟通契约与自由设计/模板使用;随后才安装所选工作区供 Stage 2 读取- 原生 PPTX 模板请求进入 template-fill;可复用 SVG 模板需先通过 create-template 创建↓[Strategist] 策略师 - Stage 1 沟通确认 + 最终 Stage 2 完整方案与生产机制确认 → design_spec.md + spec_lock.md↓@@ -134,18 +133,17 @@ narration 标记。| 项目规范化 SVG 的语法、兼容形式与映射边界 | 由 [`references/shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 选择的拆分权威集 || Master/Layout/Slide 打包与原生对象映射 | SVG 到 PPTX 的翻译;可以重组 SVG 已表达的内容,但不能创造新的可见内容 || 动画、转场、讲稿和旁白 | 各自的 sidecar / 资源与 PPTX package 后处理 |-| 直接原生 PPTX 编辑 | 所选原生工作流自己的 PPTX / OOXML 契约 |+| 原生 PPTX 保留式编辑 | Edit Native PPTX round-trip 工作区与保留来源的导出合同 |这是一条“页面设计闭包”规则,不代表 SVG 要描述完整 PPTX package。相关验收是:完成的页面 SVG 能重建对应幻灯片的可见设计;不要求仅凭 SVG 重建讲稿、音频、计时、relationships 或直接原生编辑结果。`svg_final/` 不改变这条边界。默认流程的 Step 7 必须从 `svg_output/` 派生视觉预览:受支持的位图 / SVG 资源会内联,EMF/WMF 为 native passthrough 保留外部引用;无法解析的普通图片会保留原引用,当前 finalizer 只统计这类处理错误,并不据此让整次处理失败。这组文件供 IDE、浏览器查看,也可由用户手动作为 SVG 图片插入 PowerPoint;它不是第二条 PPTX 导出路线,也不承担 PowerPoint 手工“转换为形状”的兼容性。需要可编辑形状时,唯一受支持的路径是项目转换器把 `svg_output/` 翻译为原生 DrawingML PPTX。-已有 PPTX 请求按修改模型分流:两条原生工作流绕过 SVG,`beautify-pptx` 则仍是 Generate PPTX 内部通过 SVG 重做可见设计的 profile:+已有 PPTX 请求按修改模型分流:Edit Native PPTX 使用保留来源的 round-trip 作者流程,`beautify-pptx` 则仍是 Generate PPTX 内部重做每个可见页面的 profile:| 工作流 | 输入角色 | 输出机制 | 为什么独立 ||---|---|---|---|-| `template-fill-pptx` | 原生 PPTX 模板 deck + 新材料 | 克隆选中的幻灯片,并在 OOXML 层改写文本 / 表格 / 图表 | 保留用户的 PowerPoint 原生页面壳,而不是转成 SVG |-| `native-enhance-pptx` | 内容与版式都应保持稳定的已完成 PPTX | 在 OOXML 层直接补讲稿、旁白、计时和转场 | 只追加原生增强,不重新设计 |+| `edit-native-pptx` | 原生设计必须保留的既有 PPTX;新材料与交付叠加内容均为可选 | 用 `pptx_to_svg.py --roundtrip` 导入,引用未改页面,编辑选中的紧凑 SVG,再用 `svg_to_pptx.py --roundtrip` 导出 | 未改页面逐字节恢复;编辑页上的未改对象恢复为原生形态;讲稿与动效仍是叠加层 || `beautify-pptx` | 页数、页序、每页措辞都必须 1:1 保留的已有 PPTX | 抽取源事实后走 SVG 流水线重新生成 native deck | 只改布局和层级,不做原地编辑 |---@@ -163,15 +161,15 @@ narration 标记。| 一张或多张图片中包含的页面画面需要变成分层可编辑幻灯片 | Generate PPTX + 图片还原为 PPTX(`image-to-pptx`)profile | 当前要求 Codex 且始终直接启用 Quick;先规范化全部页面画面,每个画面映射一张幻灯片;普通文字原生还原;低清 Logo / 图标 / 装饰只能在锁定身份、轮廓、比例、颜色和字标的前提下参考重建;chart / table / data graphic 禁止生成式重建,必须使用可核对数值的原生对象、精确源资产,或标记 `manual_required`;场景至少拆成干净背景层与人物 / 前景层;多个带 padding 包围盒且互不重叠的对象可共用一次生成 plate,再用 grid slice 或 SVG bbox crop 拆分;禁止相似替代和整页截图 skin || 显式要求快速生成 | Generate PPTX + `quick-generate` profile | 按需转换 / 阅读来源、研究事实缺口并准备所需资源;用户明确提出的要求照做,其余内容、页结构、视觉与资源由当前 Agent 在上下文中决定,跳过 Strategist / 确认 / spec / lock / finalize,手写 SVG、通过一次无锁 final gate 后导出最终 PPTX || PPTX 作为源材料,用户允许重构故事和页结构 | Generate PPTX,经 `ppt_to_md` + `pptx_intake` | PPTX 身份和几何是事实与候选,不是复刻约束 |-| 原生 PPTX 模板 + 新材料 / 新主题 | Fill Native PPTX(`template-fill-pptx`) | 克隆并填充原生页面;不生成 SVG |+| 原生 PPTX 模板 + 新材料 / 新主题 | Edit Native PPTX(`edit-native-pptx`) | 导入 round-trip 工作区;用 `page_plan.json` 选页、重排、重复或省略,只编辑计划中的页面 || 现有 PPTX,页数 / 页序 / 措辞 1:1 保留,只改善排版 | Generate PPTX + `beautify-pptx` profile | 内容和分页锁定;明确要求快速时走 Quick,否则走 Default |-| 已完成 PPTX,保持内容 / 布局稳定,只加讲稿、音频、计时、转场 | Enhance Native PPTX(`native-enhance-pptx`) | 直接 OOXML patch;不重新设计 |+| 已完成 PPTX,保持内容 / 布局稳定,只加讲稿、音频、计时、转场 | Edit Native PPTX(`edit-native-pptx`) | 在保留来源的页面上叠加增强,不重建可见作者内容 || 用户想从一个或多个 PPTX/SVG、图片/PDF、文档/网站、品牌资产、直接文字或混合参考材料包构建可复用模板工作区 | Create Template(`create-template`) | 固定入口读取每个适用证据通道,只分派一个 Create Brand、Create Style、Create Layout 或 Create Deck 子工作流,再返回作为 Generate Stage 1 候选的工作区根目录;结构型子工作流可导出审阅 PPTX || Default Generate 进入规划;本次运行可能已带精确工作区 root 或 Create Template handoff | Generate PPTX Stage 1 | Step 3 只准备候选;Stage 1 同时确认沟通与自由设计/模板使用;普通请求默认自由设计,明确模板意图或任意 root 默认模板模式,且只有单 root 会预选;随后才安装供 Stage 2 读取 || 用户要求调整对象级动画顺序 / 效果 / 计时 | Generate PPTX + `customize-animations` 阶段 | 通过 `animations.json` 控制可选导出策略 || 用户要求预览、选择、注解或重导出浏览器编辑 | Generate PPTX + `live-preview` 阶段 | 注解只在规定交接点应用 |-“优化这份 PPT”这类含糊请求归约为一个判定点:是否保留原始页数、页序和逐页措辞。两者都属于 Generate PPTX;保留时选择 `beautify-pptx` profile,允许重构时使用普通 profile。两种情况下都只在明确要求快速时选择 Quick,否则使用 Default。+“优化这份 PPT”这类含糊请求先归约为一个判定点:通过 Generate 重做可见页面,还是通过 Edit Native PPTX 保留并编辑原生 deck。进入 Generate 后,保留页数、页序和逐页措辞时选择 `beautify-pptx` profile,重建故事时使用普通 profile;只有明确要求快速时才选择 Quick,否则使用 Default。---@@ -228,11 +226,10 @@ Quick Generate:+ validation/<output_stem>.report.json+ backup/<ts>/svg_output/ [默认输出路径]-直接 OOXML 路由:-analysis/<stem>.slide_library.json + 源 PPTX + fill_plan.json- └─> template_fill_pptx.py -> exports/*.pptx-源 PPTX 项目归档副本 + 增强计划 + 讲稿/音频/计时资产- └─> native_enhance_pptx.py -> exports/*.pptx+Edit Native PPTX:+源 PPTX+ └─> pptx_to_svg.py --roundtrip -> authoring-svg-flat/ [+ page_plan.json]+ └─> svg_to_pptx.py --roundtrip -> exports/*.pptx```关键切分是:`svg_output/` 是作者状态,`svg_final/` 是派生视觉预览,`exports/` 和 `backup/` 是派生的交付或归档状态。模糊这条线,会让校验、重导出和人工修复都更难推理。@@ -283,7 +280,7 @@ SVG 也是唯一同时满足流程中所有角色需要的格式:**AI 能可| 内容契约 | `sources/` 内容型文件(以 `<stem>.md` 为主) | `source_to_md/*` 转换器 + `import-sources` | 文本、表格、图表数值、SmartArt 节点文字、引用和源材料叙事 || 结构化分析 | `analysis/*.json` / `analysis/*.csv` | intake 与分析工具 | PPTX 身份信息、页面几何、原生表格/图表、SmartArt 关系,以及图片尺寸、比例、引用次数、媒体类型与渲染能力等可测量事实 |-对 PPTX 源文件,`project_manager.py import-sources` 先按所有权边界把原件 move/copy 到项目 `sources/`,再以归档后的路径运行 `pptx_intake.py`;只有没有同 stem 的显式或既有规范 Markdown 时,才在最后调用 `ppt_to_md.py`。因此正常首次导入会得到两条事实通道,但去重路径可跳过重复 Markdown 转换,intake 失败也会记录为导入 note,而不是伪造分析产物。Markdown 仍然是主生成流水线的内容源;成功的 intake bundle 会写出 `<stem>.identity.json`、`<stem>.slide_library.json`,并把紧凑的多 deck 索引合并到 `analysis/source_profile.json`。Strategist 默认读取这个紧凑索引来获取源事实;只有特定工作流需要原始细节时,才打开单个 deck 的原始 artifact。这个边界很重要:主流水线可以重构页数和叙事,而 `template-fill` 与 `beautify` 会把同一批 intake 事实中的一部分提升为更强约束。+对 PPTX 源文件,`project_manager.py import-sources` 先按所有权边界把原件 move/copy 到项目 `sources/`,再以归档后的路径运行 `pptx_intake.py`;只有没有同 stem 的显式或既有规范 Markdown 时,才在最后调用 `ppt_to_md.py`。因此正常首次导入会得到两条事实通道,但去重路径可跳过重复 Markdown 转换,intake 失败也会记录为导入 note,而不是伪造分析产物。Markdown 仍然是主生成流水线的内容源;成功的 intake bundle 会写出 `<stem>.identity.json`、`<stem>.slide_library.json`,并把紧凑的多 deck 索引合并到 `analysis/source_profile.json`。Strategist 默认读取这个紧凑索引来获取源事实;只有特定工作流需要原始细节时,才打开单个 deck 的原始 artifact。这个边界很重要:主流水线可以重构页数和叙事,而 `beautify` 会把同一批 intake 事实中的一部分提升为更强约束。转换器生成的图片资产也会被归一化。伴随的 `<stem>_files/` 目录会导入项目级 `images/` 池,`image_manifest.json` 按文件名合并;当导入后目录名发生变化时,Markdown 中的资源引用会被重写。Office 矢量图(`.emf` / `.wmf`)是一等运行时资产:intake 阶段不栅格化它们,`finalize_svg.py` 为 native 路径保留外部引用,`svg_to_pptx.py` 以 Office 矢量媒体嵌入,避免 CJK 字体替换和矢量细节损失。@@ -346,7 +343,7 @@ CLI 支持 `--move`、`--copy` 和自动默认,但共享同一条固定的所| `svg_final/` 是默认流程派生产物 | 它必须能从 `svg_output/` 重建,只负责视觉预览;受支持资源尽量内联,EMF/WMF 保留外链例外,不应成为 native 导出的事实源;`quick-generate` 跳过它 || native PPTX 标准导出读取 `svg_output/` | 唯一受支持的可编辑形状路线由项目转换器执行;它要在 finalize 重写前保留图标、`preserveAspectRatio`、圆角矩形和原生图片裁剪语义 || PowerPoint 手工“转换为形状”不属于兼容性契约 | `svg_final/` 可以作为 SVG 图片插入,但转换后的结构与视觉结果不做保证,也不反向约束 SVG 允许能力 |-| 直接 OOXML 路由不进入 SVG 流水线 | 保留型工作流直接 patch 原生 PPTX parts |+| Edit Native PPTX 不进入 Generate SVG 流水线 | round-trip 工作区使用来源支持的 `authoring-svg-flat/` 页面与保留来源的导出器,而不是生成一份新 deck || 图片事实来自重算元数据 | `analysis/image_analysis.csv` 从实时 `images/` 目录重算;默认流程由 Strategist 先用源文上下文,只在图片语义或安全放置仍无法确定时查看那一张具体图片;`quick-generate` 由当前 Agent 在备料时采用同样的有界分析,SVG 创作阶段不重新扫描源图像素 || 原生 PPTX 模板不是 Step 3 候选 | Step 3 只接受精确的可复用模板工作区 root 作为候选输入 |@@ -408,7 +405,7 @@ Theme、Slide Master、Slide Layout 与 Placeholder 是编译生成的 PowerPoin当用户选择多个 root 时,每个不同 root 只安装一次,且每份贡献保持独立 spec。完整集合中每个 kind 最多一份,四种 kind 均可共存,多 kind project root 必须原子选择。随后按**片段级**而不是字段级解析所有权:Brand 拥有身份,Style 拥有方向/方法默认值;有 Layout 时由 Layout 拥有结构,否则由 Deck 拥有结构;Deck 始终保留描述性的可复用应用语境,以及未被 Brand 覆盖的身份。项目中只安装当前有效的 Layout 或 Deck 结构 roster。library/explicit 来源不改变这个顺序。当前项目应用契约只来自已确认的 Stage 1,Deck 语境只是 Stage 2 对照输入,不会覆盖它。用户最终确认最高。Style 的色彩/字体 fallback 不覆盖 Brand/Deck 身份,其方法与构图预期必须兼容所选结构。项目内 Brand + Layout 组合的应用语境来自 Stage 1,不会自动升级成可注册的 Deck。同 kind 重复会在安装前被拒绝。这样已装集合能明确说明每个片段来自哪里,便于审计和复现。-**原生 PPTX 不能直接作为 Step 3 工作区。** 普通 Generate 可以把 PPTX 作为源材料使用,`beautify-pptx` 也可以在页数、页序和逐页措辞 1:1 的边界下重新设计;这两种情况都不会把原始 PPTX 当作 Step 3 模板。把原生 PPTX 作为模板或页面壳、再用新材料填充时,默认进入 Fill Native PPTX;若请求允许拆分、合并、删页、重排或叙事重构,则仍属于 Generate。只有当目标是创建可复用模板工作区、并在 SVG 路线的 Step 3 中重复使用其设计系统时,才先运行 Create Template,再传入生成的工作区根目录。+**原生 PPTX 不能直接作为 Step 3 工作区。** 普通 Generate 可以把 PPTX 作为源材料使用,`beautify-pptx` 也可以在页数、页序和逐页措辞 1:1 的边界下重新设计;这两种情况都不会把原始 PPTX 当作 Step 3 模板。把原生 PPTX 作为模板或页面壳,或在不重设计的前提下选择、重排、重复或省略既有页面时,默认进入 Edit Native PPTX;需要拆页、合页、重写大纲或重设计时,仍属于 Generate。只有当目标是创建可复用模板工作区、并在 SVG 路线的 Step 3 中重复使用其设计系统时,才先运行 Create Template,再传入生成的工作区根目录。**模板合同是 opt-in,catalog 参考和图标不是。** 这种不对称是有意的:Layout 锁定可复用结构,Style 锁定方向/方法默认值,Brand 锁定身份,Deck 则把重复应用与身份、结构组合起来;页面级 Chart/Table 参考和图标只是不会单独施加 deck 级合同的复用原语。定性 Structure 则由 Executor 根据当前页关系现场生成,没有 catalog SVG 或 key。Chart/Table catalog 与可复用工作区同在 `templates/` 树下,但 ownership 仍是 page-local。@@ -457,8 +454,8 @@ OMML 词汇执行更窄的反向过程,生成带可见 SVG 预览的规范块绝对外部 URI 会成为 external hyperlink relationship;精确的 1-based`#slide-N` 会成为内部 Slide relationship,并写入`ppaction://hlinksldjump`。PPTX 回导器会把受支持的形状点击与文字 run 点击重建-为同一种 anchor。Fill Native 只在输出目标唯一时重映射内部跳转;Enhance-Native 则不改既有 hyperlink XML 与 relationship。鼠标悬停、custom show、+为同一种 anchor。Edit Native PPTX 对未改页面不动既有 hyperlink XML 与+relationship;带页计划时只在输出目标唯一时重映射内部跳转。鼠标悬停、custom show、导航命令、程序 / macro / OLE / file 以及任意 action setting 仍在合同外。唯一的 source-only transport 例外用于同一 PowerPoint shape 同时具有整体 click与内部 run link 的情况:PPTX→SVG 在逻辑 group 上写@@ -475,7 +472,7 @@ Generate 路由会在加载流程前选定一份运行时权威:[`workflows/ge全路由通用的停止 / 继续规则以 [`failure-recovery.md`](../../skills/ppt-master/workflows/governance/failure-recovery.md) 为准;其中具体故障矩阵与续跑入口目前覆盖 Generate PPTX。本节不复制这些规则。-其中三条边界尤其关键。第一,页面 SVG 必须由当前主代理逐页手写;禁止写 Python / Node / shell 生成器批量吐 SVG,因为这种输出会丢失跨页判断和视觉连续性。第二,默认流程节奏是 `P01 → first-page gate → 不间断生成其余页面 → final gate`。P01 是方法样本:执行者先输出 `gate-signal`,再把已解决的方法规则带入后续页面;P02 到末页之间不分批,也不插入 checker。`quick-generate` 仍串行手写并以 P01 为视觉锚点,跳过首屏 gate,并在完整 roster 生成后运行一次无锁 final gate。第三,路由是确定性的:原生 PPTX 模板、beautify、native enhancement、自定义动画、live preview 等触发条件已经在仓库里定义清楚时,不再额外抛给用户一个开放式路线选择题。+其中三条边界尤其关键。第一,页面 SVG 必须由当前主代理逐页手写;禁止写 Python / Node / shell 生成器批量吐 SVG,因为这种输出会丢失跨页判断和视觉连续性。第二,默认流程节奏是 `P01 → first-page gate → 不间断生成其余页面 → final gate`。P01 是方法样本:执行者先输出 `gate-signal`,再把已解决的方法规则带入后续页面;P02 到末页之间不分批,也不插入 checker。`quick-generate` 仍串行手写并以 P01 为视觉锚点,跳过首屏 gate,并在完整 roster 生成后运行一次无锁 final gate。第三,路由是确定性的:原生 PPTX 模板、beautify、Edit Native PPTX、自定义动画、live preview 等触发条件已经在仓库里定义清楚时,不再额外抛给用户一个开放式路线选择题。默认流程的角色切换协议(切换模式前必须 `read_file references/<role>.md`)有两个互相支撑的作用:把新鲜的角色指令载入上下文,覆盖前一模式的漂移;对话 transcript 中的可见标记构成审计轨迹,让用户能看到 agent 何时切换了模式——回看一个具体决策为什么这样做时,这条线索很关键。@@ -671,15 +668,9 @@ SVG 与 DrawingML 的表达模型并不等价,因此主编译路径不把“----## 直接 OOXML 路由+## 原生 PPTX 编辑-不是所有 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_enhance_pptx_core.py`,在项目归档副本上直接 patch PPTX package:讲稿、全局或按页转场、录制旁白媒体、页面计时和相关元数据。intake 会记录来源 hash 与有序 slide-part roster;validate/apply 会拒绝来源漂移或缺少已请求素材。只读 delivery check 会在 intake/preflight 盘点包完整性、字体、媒体、隐藏页、体积与已有 motion,并在原子发布前审计候选文件。旧名称 `native_narration_pptx.py` 仅保留为精简的 CLI 兼容包装器。它的契约是保留:已有内容、布局和格式不重新生成。--这些直接路线会和主流水线共享部分分析原语,但复用深度不同:Template Fill 消费标准 PPTX intake 的 slide library;Native Enhance 用 `ppt_to_md.py` 理解内容,从归档 package 生成自己的轻量 `slide_index.json`,并把机器 delivery report 放在 `validation/`。两者都不共享 SVG 作者阶段和后处理阶段。这个分离是有意的:SVG 生成是设计合成路径;直接 OOXML 编辑是保留路径。+不是所有 PPTX 相关请求都应该重做每个页面。Edit Native PPTX 是当前保留路线:它用 `pptx_to_svg.py --roundtrip` 导入来源 deck,逐字节引用未改页面,只编辑计划中的紧凑 SVG,再通过 `svg_to_pptx.py --roundtrip` 导出。`page_plan.json` 可选择、重排、重复或省略页面;讲稿、旁白、计时和转场都作为保留页面上的叠加层。---@@ -780,7 +771,7 @@ ChartEx 导入被有意限制为 7 个已验证数据模型:`treemap`、`sunbu|---|---|| 不要把模板名或风格短语模糊匹配到库路径 | 模板选择必须是确定性的;套错工作区比自由设计更难恢复 || 不要把原生 PPTX 模板当作 Step 3 模板 | 作为模板 / 页面壳时应走原生克隆与填充;作为来源、1:1 beautify 或可重构材料时分别走对应 Generate 边界,而不是把 PPTX 直接交给 Step 3 |-| 不要把 `template-fill-pptx`、`beautify-pptx`、`native-enhance-pptx` 合成一个“PPTX 优化”路线 | 三者的保留契约不同:原生填充、1:1 重排、直接增强是三种操作 |+| 将原生填充与增强合并为 Edit Native PPTX;保留独立的 `beautify-pptx` | 填充与增强共享同一个保留来源的 round-trip 工作区和 `svg_to_pptx.py --roundtrip` 导出器;beautify 通过 Generate 重做每一页,而不是保留来源页面 || 不要用脚本批量生成 Executor SVG 页面 | 跨页设计判断依赖主代理逐页连续创作 || 不要把 `image_analysis.csv` 当持久缓存 | `images/` 是实时工作目录;事实必须按需重算 || 不要让 `svg_final/` 成为 native PPTX 默认输入 | `svg_final/` 为视觉预览而重写资源,native 转换需要 `svg_output/` 的高保真语义 |@@ -794,7 +785,7 @@ ChartEx 导入被有意限制为 7 个已验证数据模型:`treemap`、`sunbu## 顶层路线与支撑文档-[`workflows/index.md`](../../skills/ppt-master/workflows/index.md) 是仅供维护者使用的目录,不进入任务加载链。运行时路线选择以 [`workflows/routing.md`](../../skills/ppt-master/workflows/routing.md) 为权威。PPT Master 只有四条顶层产物路线:Generate PPTX、Create Template、Fill Native PPTX、Enhance Native PPTX。用户请求只能进入其中一条;任何支撑文档都不与它们竞争。+[`workflows/index.md`](../../skills/ppt-master/workflows/index.md) 是仅供维护者使用的目录,不进入任务加载链。运行时路线选择以 [`workflows/routing.md`](../../skills/ppt-master/workflows/routing.md) 为权威。PPT Master 只有三条顶层产物路线:Generate PPTX、Create Template、Edit Native PPTX。用户请求只能进入其中一条;任何支撑文档都不与它们竞争。支撑文件保持拆分,只是为了收紧路线合同,并在需要时加载可选上下文:@@ -804,7 +795,7 @@ ChartEx 导入被有意限制为 7 个已验证数据模型:`treemap`、`sunbu| 模板子工作流 | `create-brand`、`create-style`、`create-layout`、`create-deck` | Create Template 在“仅身份 / 无 roster 的方向与方法 / 品牌中立且应用中立的结构 / 应用语境与身份结构一体化”中只分派一个 || 模板输入阶段 | `apply-template-workspace` | Default Stage 1 确认至少一个工作区后、Stage 2 前运行;自由设计跳过安装,Quick 可直接提供精确 root || 生成阶段 | `topic-research`、`resume-execute`、`refine-spec`、`verify-charts`、`visual-review`、`live-preview`、`customize-animations` | Generate PPTX 中各自定义的 intake、planning、editing、quality 或 post-processing 节点 |-| 共享阶段 | `generate-audio` | Generate PPTX 后处理,或 Enhance Native PPTX 的旁白集成 |-| 治理文档 | `failure-recovery` | 四条顶层路线的全局停止 / 继续规则;Generate PPTX 的具体故障矩阵与续跑入口 |+| 共享阶段 | `generate-audio` | Generate PPTX 后处理,或 Edit Native PPTX 的旁白集成 |+| 治理文档 | `failure-recovery` | 三条顶层路线的全局停止 / 继续规则;Generate PPTX 的具体故障矩阵与续跑入口 |这种分类是职责边界,不是文件命名偏好。只有出现不同的产物生命周期和修改模型时,才新增顶层路线;Create Template 内按模板类型区分的执行归入子工作流,路线内的可选行为归入 profile 或 stage,跨路线政策归入 governance。diff --git a/docs/zh/templates-guide.md b/docs/zh/templates-guide.mdindex 491e7a8b..48089bb6 100644--- a/docs/zh/templates-guide.md+++ b/docs/zh/templates-guide.md@@ -18,7 +18,7 @@ PPT Master 模板是一种可复用工作区,明确分为四类:**Brand**| 起点与目标 | 路线 | 可直接复制的请求 ||---|---|---|-| 手里是原始 `.pptx`,想保留现有页面壳并替换内容 | **Fill Native PPTX** | `用 projects/source/template.pptx 套入 projects/source/content.md 的内容。` |+| 手里是原始 `.pptx`,想保留现有页面壳并替换内容 | **Edit Native PPTX** | `把 projects/source/content.md 的内容套进 projects/source/template.pptx;保留原设计,只选适合的页面。` || 已有可复用 Brand/Style/Layout/Deck 工作区,想生成一份全新 deck | **Generate PPTX → Stage 1 模板选择控件** | `用 sources/report.pdf 做 deck,模板用 skills/ppt-master/templates/layouts/presentation_core/。` || 手里是 PPTX、SVG、品牌手册、网站、图片或混合参考,想先建立可复用系统 | **Create Template → Generate PPTX** | `用 /create-template 从 projects/brand/our_deck.pptx 创建一个可复用 Deck 工作区。` |diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex 6e23379d..a3950f68 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -47,8 +47,7 @@ use CWD, or assume a repo checkout. If unavailable, ask; never search or guess.| Generate PPTX — ordinary Default | [`workflows/generate-pptx.md`](workflows/generate-pptx.md) || Generate PPTX — ordinary explicit Quick | [`workflows/profiles/quick-generate.md`](workflows/profiles/quick-generate.md) || Create Template | [`workflows/create-template.md`](workflows/create-template.md) |-| Fill Native PPTX | [`workflows/template-fill-pptx.md`](workflows/template-fill-pptx.md) |-| Enhance Native PPTX | [`workflows/native-enhance-pptx.md`](workflows/native-enhance-pptx.md) |+| Edit Native PPTX | [`workflows/edit-native-pptx.md`](workflows/edit-native-pptx.md) |**Hard rule — selected authority only**: Do not load another top-level route'sprocedure after routing. Image to PPTX and Beautify are mutually exclusive;diff --git a/skills/ppt-master/references/native-hyperlinks.md b/skills/ppt-master/references/native-hyperlinks.mdindex a43a935e..dc638f90 100644--- a/skills/ppt-master/references/native-hyperlinks.md+++ b/skills/ppt-master/references/native-hyperlinks.md@@ -75,14 +75,12 @@ levels. Every ordinary whole-object link uses the standard outer `<a href>`.| Inline or whole-object slide jump | The same click carrier plus an internal slide relationship and `ppaction://hlinksldjump` || Supported PPTX import | Reconstruct the same canonical SVG `<a href>` form |-**Hard rule — Fill Native preservation**: Preserve external links. Retarget a-same-deck jump only when its source target maps unambiguously to one output-slide; omitted or duplicated targets fail closed instead of linking to an-orphan or wrong slide.--**Hard rule — Enhance Native preservation**: Preserve existing hyperlink XML-and relationships unchanged. This route does not use the SVG authoring contract-to add new links.+**Hard rule — Edit Native PPTX preservation**: Unchanged round-trip pages keep+their hyperlink XML and relationships byte-for-byte. External links are+preserved. With a `page_plan.json`, a same-deck jump is retargeted only when+its source target maps unambiguously to one output page; omitted or repeated+targets make `svg_to_pptx.py --roundtrip` fail instead of linking to an orphan+or wrong slide. New links on an edited page use this SVG authoring contract.---diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex c60789cc..06efe211 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -119,7 +119,7 @@ When authoring §IX, translate every purpose named in `communication_intent` int| Mobilize | Urgency + agency + concrete action + immediate next step || Record and hand off | Context + decisions + status + owners + unresolved items + durable provenance |-**Material-divergence consumption — outline-authoring only.** Apply the user's stated divergence intent when authoring the `§IX` outline. Record the prose (or "balanced default") in `design_spec.md §I` (Content Strategy). Do **NOT** write it to `spec_lock.md`—it is baked into `§IX` at authoring time and the Executor never reads it. It carries no page-count coupling. Beautify seeds verbatim preservation and surfaces the field as locked/read-only; the server restores the locked value on every staged submit. Fill Native PPTX does not surface the field because that route is outside this confirmation flow.+**Material-divergence consumption — outline-authoring only.** Apply the user's stated divergence intent when authoring the `§IX` outline. Record the prose (or "balanced default") in `design_spec.md §I` (Content Strategy). Do **NOT** write it to `spec_lock.md`—it is baked into `§IX` at authoring time and the Executor never reads it. It carries no page-count coupling. Beautify seeds verbatim preservation and surfaces the field as locked/read-only; the server restores the locked value on every staged submit. Edit Native PPTX does not surface the field; it is outside this confirmation flow.### d. Style Objective Confirmation@@ -601,7 +601,7 @@ includes transitions.- **page_rhythm is mandatory**: Based on the page list in §IX Content Outline, assign each page one of `anchor` / `dense` / `breathing`. This is what breaks the uniform "every page is a card grid" feel. New locks may not omit the section; consumer omission behavior is owned by [`executor-base.md`](executor-base.md) §2.1.- **Fact IDs and scenario labels are mandatory when applicable**: Read any `sources/*.facts.json`. For each §IX page, list the stable IDs actually used; never cite an ID whose claim is absent from the page. Mark invented KPIs/targets/internal ratios as `Data class: scenario` and state which values are scenario data. Executor carries external sources into notes/footnotes and renders a visible scenario label for scenario figures.- **Mandatory — whole-roster rhythm check**: During the same §IX composition, compare neighbors and section arcs to judge whether chapter entries visibly reset, extended same-density runs are intentional, extended same-carrier or same-topology runs form an intentional semantic sub-arc, repeated dominant geometry carries a continuity job, any qualifying §6.1 visible-state sequence preserves a recognizable mental map while making its next semantic change legible, each section follows a mode-fitting progression—including framework → explanation/evidence → judgment/action when it serves the objective—and the final arc resolves the communication objective before a genuine ending lowers information load. Same section, equal weight or density, one style, and prior-page precedent do not establish a semantic sub-arc. Repair the existing roster, `Layout` recommendations, and `page_rhythm` choices in place. This is judgment, not quota; preserve intentional continuity, legitimately all-`dense` material, and 1:1/literal order. Do not invent filler pages to manufacture rhythm; a `breathing` page marks a meaningful pause—chapter transition, standalone emphasis, or SCQA bridge—and must stand alone. Create no field, lock row, artifact, or second review/execution pass.- - **Cover impact is mandatory**: In `design_spec.md §IX`, give `P01` one concrete hook from the source's strongest claim, metaphor, number, moment, or conflict plus a recommended composition. The hook binds; Executor may adopt, adapt, or decline the composition while preserving the hook and explicit constraints. With no suitable image, recommend a native-SVG hook instead of a generic title treatment. Beautify / template-fill preservation paths are exempt.+ - **Cover impact is mandatory**: In `design_spec.md §IX`, give `P01` one concrete hook from the source's strongest claim, metaphor, number, moment, or conflict plus a recommended composition. The hook binds; Executor may adopt, adapt, or decline the composition while preserving the hook and explicit constraints. With no suitable image, recommend a native-SVG hook instead of a generic title treatment. Beautify preservation paths are exempt.- **Cover rhythm lock**: `P01` remains `anchor`. Default away from generic content-page templates; a card grid, agenda, or equal-weight columns remains valid when content, user direction, or the template makes it the clearest cover.- **Closing impact (only when the deck closes)**: For a genuine conclusion / CTA / final takeaway, name the binding takeaway plus a recommended composition; Executor may adopt, adapt, or decline the latter while preserving the takeaway and explicit constraints. Do not default to an information-empty "Thank you", contact-only slide, or cover reprise; an explicit contact/event CTA may serve the purpose. **Do NOT invent a closing page to satisfy this**. Preservation paths are exempt.- **pptx_structure is mandatory**: Free-design, brand-only, and `template_reuse_scope: style` routes write `mode: flat`; a style-reference route may also record `template_reuse_scope: style` but omits every structure mapping and `template_adherence`. `template_reuse_scope: mirror|layout` writes `mode: structured` plus `template_adherence: strict|adaptive`. Do not write legacy `baseline`, `template`, `preserve`, `layout_strategy`, or Layout-kind rows into a new project.diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.mdindex 4167cb08..1aa2491c 100644--- a/skills/ppt-master/workflows/create-template.md+++ b/skills/ppt-master/workflows/create-template.md@@ -16,7 +16,7 @@ Create one reusable template workspace under either the **global template librar**Hard rule — one workspace routing contract**: Output scope changes the workspace parent, Design Spec filename placement, and index registration—not the spec schema or asset routes. Both scopes use required `templates/`, optional `images/` / `icons/`, and optional on-demand `exports/`, with the same relative asset references and validation command. Create Template must not create an optional directory or placeholder file solely to retain an empty path. An initialized project may already contain empty `images/`, `icons/`, or `exports/` scaffolding; leave it untouched, do not count it as template output, and omit the path from completion unless this workflow wrote or adopted a real file there. Do not maintain a library-only self-contained-flat package branch or a project-only thin-bundle branch.-> **Boundary against template-fill and in-place structure edits**: Create Template does not fill content into a PPTX, add Master/Layout structure to an existing PPTX/SVG, or directly output the user's final generated deck. It authors a separate reusable workspace; an optional PPTX is review evidence only. To generate a deck, return the workspace root as an exact candidate to [`generate-pptx`](./generate-pptx.md) Step 3, confirm it with Stage 1, then author new SVG pages from the installed state. A project-scoped workspace selected for its own project is consumed in place after that confirmation.+> **Boundary against existing-deck and in-place structure edits**: Create Template does not fill content into a PPTX, add Master/Layout structure to an existing PPTX/SVG, or directly output the user's final generated deck. It authors a separate reusable workspace; an optional PPTX is review evidence only. To generate a deck, return the workspace root as an exact candidate to [`generate-pptx`](./generate-pptx.md) Step 3, confirm it with Stage 1, then author new SVG pages from the installed state. A project-scoped workspace selected for its own project is consumed in place after that confirmation.> **Boundary against page-image reconstruction**: screenshots and page visuals> in this route are evidence for reusable rules and prototypes. When the userdiff --git a/skills/ppt-master/workflows/edit-native-pptx.md b/skills/ppt-master/workflows/edit-native-pptx.mdnew file mode 100644index 00000000..abf174ab--- /dev/null+++ b/skills/ppt-master/workflows/edit-native-pptx.md@@ -0,0 +1,279 @@+---+description: Edit Native PPTX route — import a finished PowerPoint deck into a source-preserving SVG workspace, reference unchanged pages, edit or recompose selected pages, add notes/narration/motion, and export a new PPTX+---++# Edit Native PPTX Route++> Run when the user brings an existing `.pptx` whose design must survive — as a template to fill with new content, as a deck to partially rewrite or restructure, or as a finished deck that only needs notes, narration, timings, or transitions. This route never regenerates the deck from scratch and never runs the Generate SVG pipeline.++The source deck becomes a `pptx_to_svg.py --roundtrip` workspace. Every source slide is available as a compact editable SVG plus immutable native backing. Pages the plan leaves untouched are **referenced**: export restores their original slide XML byte-for-byte. Pages the plan edits are rebuilt only where they changed; every unchanged object on them restores its native form. Notes, narration audio, and motion are overlays on the preserved slide and never rewrite visible content.++**Boundary against other routes**:++| User wants | Route |+|---|---|+| Fill a raw PPTX template with new content, keep its design | This route |+| Keep a finished PPTX, add speaker notes / narration / auto-advance / transitions | This route |+| Rewrite some pages of a finished PPTX, keep the rest exactly | This route |+| Drop, reorder, or repeat pages of an existing PPTX without redesign | This route |+| Regenerate every page with a new visual design (beautify, 1:1) | Generate PPTX, [`beautify-pptx`](./profiles/beautify-pptx.md) |+| Split / merge / re-outline an existing PPTX into a new deck | Generate PPTX, PPTX as source material |+| Create a reusable brand / style / layout / deck asset from the PPTX | [`create-template`](./create-template.md) |++**Hard rule — no Generate pipeline**: Do not run `pptx_template_import.py`, `project_manager.py init`, `finalize_svg.py`, or create `svg_output/` for this route. The round-trip workspace is the project; `svg_to_pptx.py --roundtrip` is the only exporter that restores source slides.++---++## 1. When to Run++| Pattern | Example |+|---|---|+| Raw PPTX called a template + new material or topic | "Use this PowerPoint template to make a deck about X" |+| Existing deck + selective reuse | "Only keep the pages that fit, in this order" |+| Existing deck + copy replacement | "Keep the design, swap in this text" |+| Existing deck + page-level rewrite | "Redo page 5 and 7, leave everything else" |+| Existing deck + page combination | "Merge the two market pages into one, drop the old chart, add the new KPI" |+| Existing deck as skeleton + a few new pages | "Keep the deck, add a summary page and a Q3 page in the same style" |+| Finished deck + delivery add-ons, visible slides stable | "Add narration and auto-play", "add fade transitions", "write speaker notes" |++**Deterministic routing**: Do not ask a route-choice question for these shapes. Ask one discriminator only when the request is ambiguous between preserving pages (this route) and redesigning them (Generate).++---++## 2. Inputs++🚧 **GATE**: The user has provided:++| Input | Required | Notes |+|---|---:|---|+| Source PPTX | Yes | Finished deck or template; the native design authority |+| New material | Only when content changes | Text, Markdown, documents, or URLs converted with `source_to_md.py`. A bare topic without facts is not enough: ask for material, or gather it from user-approved URLs before planning |+| Delivery intent | Optional | Audience, page count, must-keep / must-drop pages, notes, narration, transitions, auto-advance |++**Hard rule — facts**: Every substantive claim written into a page or a note comes from the user material; the §4.3 content mapping names the source for each page, and a page without one is dropped. Placeholder wording in the template is never carried into the output as content.++---++## 3. Import the Round-trip Workspace++Create the workspace directly under `projects/`; it is the project.++```bash+python3 skills/ppt-master/scripts/pptx_to_svg.py "<source.pptx>" \+ -o "projects/<slug>_<YYYYMMDD>" --inheritance-mode both --roundtrip+```++| Path | Content | Reading rule |+|---|---|---|+| `authoring-svg-flat/slide_NN.svg` | One compact editable SVG per source slide, in source order | Open only the pages you will edit or need to judge for reuse |+| `authoring-svg-flat/authoring_summary.json` | Roster plus per-page canvas, text, image, vector, placeholder, source-ref, and source-proxy counts | Read first; plan from it before opening any SVG |+| `images/`, `icons/imported/`, `audio/`, `video/`, `sounds/` | Source media and imported decorative vectors | Reference from pages; keep names — export resolves hrefs relative to the page and fails on a missing resource |+| `notes/slide_NN.md` | Source speaker notes when present | Edit, delete, or add per output page (§6) |+| `native-payloads/`, `analysis/` | Immutable native backing and tool-owned contracts | Tool-owned; opening them costs context and changes nothing — do not read, edit, or quote |+| `sources/source.pptx` | Exact source package | Read only through `ppt_to_md.py "<workspace>/sources/source.pptx" -o "<workspace>/validation/source_readback.md"` when you need page text without opening every SVG (notes on unchanged pages, content mapping) |+| `validation/`, `exports/` | Diagnostics and published decks | Tool-written |++**Hard rule — source proxies are atomic**: An `<image data-pptx-source-proxy="native-restore">` element stands for an unsupported native object (SmartArt, complex effects, media frames). Leave it unchanged to restore the original object; a Slide-local proxy may be deleted; an inherited Master/Layout proxy stays. Editing a proxy or its preview asset fails export.++---++## 4. Plan the Output Deck++**Default — layout-first selection (may override when the user fixes the page mapping)**: Treat the roster as a slide library, not an outline. A source page's layout already encodes a rhetorical shape — hero statement, lead-then-detail, comparison, stepwise progression, metric row, dense explanation. Match each target message to a page whose structure expresses that same logic; drop the content or the page rather than force a fit. Use fewer pages than the source when that reads better; repeat one good layout for several messages when they share its pattern.++**Default — source order is not the outline (may override when the user asks to preserve it)**: The target story controls output order. Source slides may move, be omitted, or be reused several times.++**Default — skeleton first (may override when the user asks for new pages)**: The source deck is the reference material and the skeleton of the output. Most output pages keep a source page's structure; sub-content may be recombined freely across pages, and new pages are added where the story needs them rather than as a rule.++### 4.1 Page plan++Write `page_plan.json` at the workspace root only when the output differs from the source roster (subset, reorder, repeat, or a copied page). Without the file, export is the identity round trip and every page is referenced or edited in place.++```json+{+ "schema": "ppt-master.roundtrip-page-plan.v1",+ "pages": [+ {"source_slide": 1},+ {"source_slide": 4, "svg": "chapter_market.svg"},+ {"source_slide": 7},+ {"source_slide": 7, "svg": "kpi_second_half.svg"},+ {"source_slide": 12}+ ]+}+```++| Field | Rule |+|---|---|+| `pages` | Complete output order; non-empty |+| `source_slide` | One-based source index of the page whose native slide backs this output page |+| `svg` | Authoring filename inside `authoring-svg-flat/`; omit to use that source page's `slide_NN.svg`. To reuse one source page twice, copy its SVG to a new name (`cp slide_07.svg kpi_second_half.svg`) and list the copy — every output page needs a distinct file, and every extra file must appear in the plan |++Only `schema` and `pages` at the root and `source_slide` / `svg` per page are accepted; the exporter rejects any other field.++**Forbidden — plans the exporter refuses** (fail-closed, fix the plan instead of forcing):+- Omitting a source slide that owns audio, video, or another opaque native payload+- A same-deck slide jump whose destination is omitted or repeated (include the target exactly once, or remove the link from the page)+- Unknown, duplicated, or cross-owned `svg` filenames; `source_slide` out of range++**Combining pages**: One output page always has exactly one skeleton — its `source_slide`. To merge several source pages, pick the page whose layout carries the result as the skeleton, then copy the needed elements from the other pages' SVGs into it and delete what the merged page no longer needs. Bring an object across pages only through the adopt command below — never by pasting raw SVG, because source refs are page-local and a pasted object would be mistaken for one of the skeleton's own. The adopted object keeps its visual form but loses its native identity and is rebuilt from SVG, so the combined page counts as `rebuilt`. A source proxy (§3) cannot leave its own page; a merge that needs one keeps that page as the skeleton instead.++```bash+python3 skills/ppt-master/scripts/svg_authoring_view.py \+ "projects/<slug>_<YYYYMMDD>/authoring-svg-flat" \+ --adopt-object slide_05.svg:<element-id> --into chapter_market.svg+```++The object lands at the end of the target page; then edit its position and content like any authored element.++**New pages**: A brand-new page also needs a skeleton so it inherits the deck's Master/Layout (background, logo, page number). Copy the closest source page under a new name, list it in the plan with that page's `source_slide`, delete its Slide-local content, and author the new content on the empty canvas; inherited proxies stay. The page counts as `rebuilt`.++> Note: with a plan present, presentation-level sections and custom shows are dropped and slide ids are renumbered; visible slides are unaffected.++### 4.2 Enhancement modules++| Module | Default | Carrier |+|---|---|---|+| Speaker notes | Source notes travel with every page; add or rewrite only where the plan says | `notes/<svg-stem>.md` |+| Narration audio | Off unless requested; implies notes on every output page | [`generate-audio`](./stages/generate-audio.md) → `audio/<stem>.*` |+| Auto-advance from narration | On when narration is requested | `svg_to_pptx.py --use-narration-timings` |+| Page transitions | Preserve source; replace only on request | `svg_to_pptx.py -t <effect>` or per-slide rows in `animations.json` |+| Object animations | Preserve source; author only on explicit request | `animations.json`, see [`animations.md`](../references/animations.md) |+| Native chart / table data | Source data unless the plan edits it | Inline JSON authority on the page; export needs `--native-charts-and-tables` (§7) |++### 4.3 Confirmation++⛔ **BLOCKING**: Present one plan and wait for explicit confirmation before editing any SVG, writing notes, generating audio, or exporting:++| Item | Show |+|---|---|+| Output roster | Ordered list: output page → source slide → referenced unchanged / edited / new copy, with a one-line reason for each edited or dropped page |+| Content mapping | Which material goes to which page; anything dropped for lack of a fitting layout |+| Enhancement modules | Each module on/off with its effect and duration where relevant |+| Known refusals | Any §4.1 fail-closed case the plan must avoid |++Chat confirmation is sufficient; write `page_plan.json` after confirmation.++---++## 5. Edit Pages++Load [`shared-standards-core.md`](../references/shared-standards-core.md) before the first edit. Load [`svg-effects.md`](../references/svg-effects.md) only when authoring new visual elements, and [`native-data-interface.md`](../references/native-data-interface.md) only when changing native chart or table data.++**Hard rule — edit only planned pages**: A page marked referenced is not opened for writing. Export proves it: a referenced page appears under `passthrough` / `cloned_passthrough` (no overlay) or `patched` (notes or motion overlay only) in the receipt (§7) — never under `rebuilt`.++**Hard rule — edit in place, keep identity**: Change text, paint, position, or content inside the existing page tree. Keep every `data-pptx-*` attribute on objects you did not intend to change; an object whose source attributes survive is restored natively, an object you rewrote is converted from your SVG. Do not paste a page from `svg_output/` conventions or another deck over a round-trip page.++| Edit | Rule |+|---|---|+| Text replacement | Fit the slot's visual capacity from its geometry and font size, not the old placeholder length. Resolve overflow in this order: rewrite shorter → split across another selected page → choose a larger source layout; shrinking type is last and never deck-wide. §5's capacity gate rejects text that leaves its frame |+| Cover / chapter pages | Replace title, subtitle, author, section label only |+| Dense content pages | Compress material to the slot count the page already has; move overflow to another selected page |+| Native tables | Imported tables carry `data-pptx-native-authority="json"`; edit cell text in that inline `ppt-master.semantic-table.v2` JSON and keep row/column structure unless the design calls for a different table. Export with `--native-charts-and-tables` (§7) — without it the stale preview ships |+| Native charts | Imported charts carry the same JSON authority; edit categories and series values there and leave chart type and formatting to the source. Same export flag |+| Images | Replace by pointing the existing `<image>` at a new file under `images/`; keep the frame |+| New elements | Author canonical compact SVG per shared standards; icons come from `icon_sync.py "<workspace>" <lib/name>`; AI images from `image_gen.py --manifest` when the user wants generated visuals |+| Objects from another page | Use `--adopt-object` (§4.1); it strips source identity, inlines cross-page vector assets, and keeps chart/table JSON authority. Never paste raw SVG across pages; proxies cannot move |+| Source proxies | Leave or delete; never edit (§3) |++**Mandatory after editing** — refresh the summary (page-plan copies are accepted), then run the capacity gate:++```bash+python3 skills/ppt-master/scripts/svg_authoring_view.py \+ "projects/<slug>_<YYYYMMDD>/authoring-svg-flat" --refresh-summary+python3 skills/ppt-master/scripts/svg_quality_checker.py "projects/<slug>_<YYYYMMDD>" --roundtrip+```++🚧 **GATE**: The checker's `--roundtrip` mode estimates edited text against its frame and canvas. Errors block export until the text is rewritten, split, or moved to a larger layout; warnings are reviewed and either fixed or accepted with a stated reason. The exporter remains the final gate and fails closed on a page it cannot restore or convert.++---++## 6. Notes, Narration, and Motion++Skip this section when no module in §4.2 is enabled beyond preserving source notes.++**Notes** — keyed by output SVG stem:++| Case | Behavior |+|---|---|+| `notes/<stem>.md` exists for a canonical page | Replaces source notes; delete the file to remove source notes |+| `notes/<stem>.md` exists for a copied page | Notes for that output page only |+| No file for a copied page | Inherits the source page's notes |++**Hard rule — spoken prose only**: `svg_to_pptx.py` embeds each note verbatim and `notes_to_audio.py` reads it aloud verbatim, so a heading, bullet, `[tag]`, or duration line is spoken and shown. Write 2–5 natural sentences per content page, one or two for cover / chapter / ending, transitions as prose, one language per deck. Source the content from the page's SVG text or the §3 read-back plus the user material; a note never adds a claim the page or material does not carry.++**Narration audio**: Run [`generate-audio`](./stages/generate-audio.md) Steps 1–4 with the workspace path after notes are complete. `notes_to_audio.py` resolves the roster from `page_plan.json` (copies inherit source notes) and refuses an incomplete roster, listing the missing stems. Audio lands at `audio/<stem>.*` per output page. Stop after audio generation; §7 integrates it.++**Motion**: Load [`animations.md`](../references/animations.md) when transitions or object animations are requested. `animations.json` rows are keyed by output SVG stem; a copied page inherits its source row unless it has its own.++---++## 7. Export and Validate++```bash+python3 skills/ppt-master/scripts/svg_to_pptx.py "projects/<slug>_<YYYYMMDD>" --roundtrip+```++| Request | Add |+|---|---|+| Replace transitions deck-wide | `-t <effect> [--transition-duration <s>]` |+| Narration with auto-advance | `--recorded-narration audio --use-narration-timings` |+| Per-slide motion | `--animation-config animations.json` |+| Object animation policy | `-a <preset>` (default `none`) |+| Strip all notes | `--no-notes` |+| Native chart / table data edited | `--native-charts-and-tables` |++Export writes into `exports/` and prints the exact output path (a `_narrated` or `_native_charts_tables` suffix may apply — use the printed path in every later command) plus one receipt:++```text+Round-trip export summary: output_pages=N passthrough=P cloned_passthrough=C patched=M rebuilt=R+```++| Bucket | Meaning | Assert |+|---|---|---|+| `passthrough` | Identity page, original XML and relationships | Referenced pages without a plan and without any notes/motion overlay |+| `cloned_passthrough` | Planned page, original XML on a cloned part | Referenced pages with a plan and without any overlay |+| `patched` | Visible XML kept; only notes or motion overlaid | Referenced pages once notes, transitions, animation, or narration flags apply |+| `rebuilt` | Visible authoring changed | Exactly the pages marked edited in §4.3 — a delivery-only job must show `rebuilt=0` |++**Validation**:++```bash+python3 skills/ppt-master/scripts/pptx_delivery_check.py "<printed_output.pptx>" \+ > "projects/<slug>_<YYYYMMDD>/validation/<output_stem>.delivery.json"+python3 skills/ppt-master/scripts/source_to_md/ppt_to_md.py \+ "<printed_output.pptx>" -o "projects/<slug>_<YYYYMMDD>/validation/readback.md"+```++| Check | Expected |+|---|---|+| Delivery check | No structural errors; review advisories |+| Slide count | Equals plan length, or source count without a plan |+| Key titles and replaced text | Present in the read-back |+| Notes count | Matches planned notes |+| Receipt buckets | Match the confirmed roster |++```markdown+## ✅ Edit Native PPTX Complete++- [x] Round-trip workspace imported at `projects/<slug>_<YYYYMMDD>/`+- [x] Plan confirmed by the user; `page_plan.json` written when the roster differs from the source+- [x] Only planned pages edited; `authoring_summary.json` refreshed; `svg_quality_checker.py --roundtrip` reports no errors+- [x] Notes / audio / motion prepared as confirmed+- [x] `svg_to_pptx.py --roundtrip` receipt matches the confirmed roster+- [x] Delivery JSON and read-back written under `validation/`+- [x] Final deck at the exporter's printed `exports/` path+```++---++## 8. Current Boundary++| Capability | Status |+|---|---|+| Reference unchanged pages byte-for-byte; select / reorder / repeat / omit pages | Supported |+| Edit text, paint, images, native table cells, native chart data on selected pages | Supported; unchanged objects restore natively; chart/table data edits export only with `--native-charts-and-tables` |+| Author new elements on an edited page | Supported through canonical compact SVG |+| Preserve SmartArt, complex effects, embedded media | Supported as atomic source proxies; not editable |+| Notes, narration audio, auto-advance, transitions, object animations | Supported as overlays keyed by output page |+| Delete inherited source notes on a copied page | Not supported; give the copy its own `notes/<stem>.md` |+| Edit a source proxy, change slide size, add Master/Layout structure | Not supported; use Create Template → Generate for a new structure |diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex a30516c8..f3172078 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -34,7 +34,7 @@ request does not explicitly select Quick.| Semantic SVG markers | Minimal rendering-neutral compiler hints used only after existing Layout/Layer/Placeholder/Native metadata has been considered. Chart/table markers preserve their visible SVG fallback; block and inline formula markers carry exact LaTeX and replace only their registered ordinary SVG preview with editable Office Math during PPTX export. || `svg_final/` | Optional derived, self-contained SVG visual preview in the default pipeline; release export never reads it. It may be opened directly or inserted into PowerPoint as an SVG picture, but it is not a supported PPTX source and carries no manual Convert-to-Shape compatibility contract. Quick-generate skips it. || SVG-to-PPTX export | The only supported generated-PPTX route reads `svg_output/` and maps its content through the project converter to DrawingML/native objects. It compiles only the selected route's explicit structure contract: `flat` keeps represented content Slide-local, while `structured` may place explicitly scoped content in Master/Layout/Slide parts. It MUST NOT infer structure, upgrade `flat`, or invent new visible page content. |-| Native PPTX routes and presentation-behavior stages | Remain outside SVG page-design closure. `template-fill-pptx`, `native-enhance-pptx`, animations, transitions, speaker notes, narration, and package relationships are not required to round-trip through SVG. |+| Edit Native PPTX and presentation-behavior stages | Remain outside SVG page-design closure. `edit-native-pptx` restores unchanged source slides natively; animations, transitions, speaker notes, narration, and package relationships are not required to round-trip through SVG. |**MUST — page-design closure**: For an SVG-authoring route, inspect the final page SVG to determine what the exported slide looks like. Do not reinterpret “SVG is the page-design language” as “SVG is the complete PPTX package description language.”@@ -176,9 +176,9 @@ For PPTX sources, `import-sources` automatically runs the standard intake enrichpython3 ${SKILL_DIR}/scripts/pptx_intake.py <project_path>/sources/<source.pptx> -o <project_path>/analysis```-For each PPTX it writes `<stem>.identity.json` (canvas, theme palette/fonts, observed usage) and `<stem>.slide_library.json` (text slots, geometry, native tables, native chart caches, SmartArt nodes/connections), and merges that deck's Strategist-facing digest into the single multi-deck index `analysis/source_profile.json` (`decks[]`, one self-contained entry per source deck, with prefixed artifact pointers). In the main generation path these are source facts and recommendation candidates, not replica constraints; the beautify profile and Fill Native PPTX route decide separately which fields become locked constraints.+For each PPTX it writes `<stem>.identity.json` (canvas, theme palette/fonts, observed usage) and `<stem>.slide_library.json` (text slots, geometry, native tables, native chart caches, SmartArt nodes/connections), and merges that deck's Strategist-facing digest into the single multi-deck index `analysis/source_profile.json` (`decks[]`, one self-contained entry per source deck, with prefixed artifact pointers). In the main generation path these are source facts and recommendation candidates, not replica constraints; the beautify profile decides separately which fields become locked constraints.-Multi-deck: several PPTX files may be imported into one main-pipeline project — each gets its own `<stem>.*` artifacts and a deck entry in `source_profile.json`. `source_profile.json` stays the single must-read index (one entry for a one-deck project, several for a combined-source project). Stems must be distinct; re-importing the same stem replaces that deck's entry. The beautify profile and Fill Native PPTX route remain single-deck (1:1 to one chosen source deck) and read that deck's `<stem>.*` artifacts.+Multi-deck: several PPTX files may be imported into one main-pipeline project — each gets its own `<stem>.*` artifacts and a deck entry in `source_profile.json`. `source_profile.json` stays the single must-read index (one entry for a one-deck project, several for a combined-source project). Stems must be distinct; re-importing the same stem replaces that deck's entry. The beautify profile remains single-deck (1:1 to one chosen source deck) and reads that deck's `<stem>.*` artifacts.**Source ownership boundary**: Use the automatic import mode shown above. Only inputs already under the repository's `projects/` tree move into the target project's `sources/`; every other local path is copied and remains untouched, even if `--move` is supplied. Use `--copy` when a projects-local input must also remain in place. If Step 1 wrote Markdown beside the original sources, pass that source path/directory once. If Step 1 used `-o` to write Markdown elsewhere, pass both the original source path(s)/directory and the Markdown output path(s)/directory. Intermediate artifacts (e.g., `_files/`) are handled automatically.@@ -229,7 +229,7 @@ multiple supplied roots remain unselected candidates. `free_design` selects none**Raw PPTX boundary**: A raw PPTX remains valid source material, but it is not atemplate workspace candidate. Raw PPTX plus new content uses-[`template-fill-pptx`](./template-fill-pptx.md). To create a reusable workspace,+[`edit-native-pptx`](./edit-native-pptx.md). To create a reusable workspace,run [`create-template`](./create-template.md), then return with the generatedroot. Never add Master/Layout/placeholder structure directly to an existingPPTX or SVG project.@@ -310,7 +310,7 @@ is confirmed; a bare template/style name does not.**`<project_path>/analysis/` is the project's intermediate-analysis folder: the canonical home for machine-extracted source/asset facts — the PPTX intake bundle (`source_profile.json` index + per-deck `<stem>.identity.json` / `<stem>.slide_library.json`) and `image_analysis.csv`. It holds facts, not design contracts — `design_spec.md` / `spec_lock.md` stay at the project root.** The MUST-read contract covers only the **compact structured data files (`.json` / `.csv`)**; other artifacts that may live under `analysis/` (e.g. a beautify `source_svg_import/` vector reference package) are NOT bulk-read — they are read selectively only when a specific workflow step calls for them. Before the Strategist confirmation stage, Strategist MUST read the auto-extracted fact files already in `analysis/` — currently `source_profile.json` (PPTX intake), when present. This file is the multi-deck index: read it once for the `decks[]` digests (canvas / chart / table / SmartArt entries per source deck), then open a specific deck's `<stem>.identity.json` / `<stem>.slide_library.json` only if you need its full raw facts. Use these entries as **factual source context** (format default + content facts); when several decks are present, synthesize across all of them. The source's **palette / typography / visual identity are a reference, not a constraint**: the main pipeline may inherit them where they fit the content and the confirmed style, or design fresh where they don't — the Strategist's judgment, never an obligation to either keep or discard. (Template-fill preserves the native source design by editing cloned slides directly; beautify defaults to the source identity but still follows the confirmed values; the main pipeline treats source identity as reference only and defaults to fresh design.) (`image_analysis.csv` lands later, at the image-analysis step below, and is the authoritative regenerated image-fact view there — re-derived from the live `images/` folder, not a durable store.)-**Channel ownership — read each fact once from its owning channel.** In the main pipeline the **content contract is the content-type files in `sources/`** — primarily `<stem>.md`, but also any user-supplied content the import archived there: `.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml` (a `metrics.json` or `data.csv` may carry core content — judge by what the file holds). Text, tables, chart data values, and SmartArt node wording come from these (`ppt_to_md` transcribes native charts as Markdown tables and SmartArt nodes as hierarchical bullets). **Do NOT read pipeline sidecars in `sources/` as content**: `*.conversion_profile.json` (conversion audit) and `*_files/image_manifest.json` (asset index) are process metadata — open them only to audit a conversion or resolve assets, never as slide content. Converted-source originals archived in `sources/` (`.pdf` / `.pptx` / `.docx` / `.xlsx` / `.html` / `.epub` / `.tex` / `.rst` / `.ipynb` / `.typ`, etc.) are read via their converted `<stem>.md`, not scanned directly in the main pipeline. The `analysis/` chart / table / diagram entries are a **structural digest** for outline decisions (which slides carried charts, tables, or SmartArt; chart types / series names; SmartArt layout and hierarchy) — not a second copy of the content values; do NOT also pull chart values or SmartArt wording from `<stem>.slide_library.json` in the main pipeline. The `<stem>.slide_library.json` full structured data is owned by the direct-PPTX workflows: template-fill uses it as the native fill contract while preserving SmartArt unchanged; beautify uses it for native chart / table data and SmartArt relationships while keeping all wording from the Markdown.+**Channel ownership — read each fact once from its owning channel.** In the main pipeline the **content contract is the content-type files in `sources/`** — primarily `<stem>.md`, but also any user-supplied content the import archived there: `.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml` (a `metrics.json` or `data.csv` may carry core content — judge by what the file holds). Text, tables, chart data values, and SmartArt node wording come from these (`ppt_to_md` transcribes native charts as Markdown tables and SmartArt nodes as hierarchical bullets). **Do NOT read pipeline sidecars in `sources/` as content**: `*.conversion_profile.json` (conversion audit) and `*_files/image_manifest.json` (asset index) are process metadata — open them only to audit a conversion or resolve assets, never as slide content. Converted-source originals archived in `sources/` (`.pdf` / `.pptx` / `.docx` / `.xlsx` / `.html` / `.epub` / `.tex` / `.rst` / `.ipynb` / `.typ`, etc.) are read via their converted `<stem>.md`, not scanned directly in the main pipeline. The `analysis/` chart / table / diagram entries are a **structural digest** for outline decisions (which slides carried charts, tables, or SmartArt; chart types / series names; SmartArt layout and hierarchy) — not a second copy of the content values; do NOT also pull chart values or SmartArt wording from `<stem>.slide_library.json` in the main pipeline. The `<stem>.slide_library.json` full structured data is owned by beautify for native chart / table data and SmartArt relationships while keeping all wording from the Markdown.**Confirmation orchestration**: field meaning and recommendation logic belong to the active Strategist modules; [`confirm_ui.md`](../scripts/docs/confirm_ui.md) owns the JSON schema, server lifecycle, staged-result contract, port behavior, and equivalent chat fallback.diff --git a/skills/ppt-master/workflows/governance/failure-recovery.md b/skills/ppt-master/workflows/governance/failure-recovery.mdindex 33173032..af7e9639 100644--- a/skills/ppt-master/workflows/governance/failure-recovery.md+++ b/skills/ppt-master/workflows/governance/failure-recovery.md@@ -4,7 +4,7 @@ description: Cross-route stop/continue governance with a concrete recovery matri# Failure Recovery Governance-Global stop/continue rules for all four top-level routes, plus concrete failure handling for Generate PPTX. Section 2 applies across routes; Sections 1 and 3 apply only to Generate PPTX. Owning route and stage documents may add narrower handling, but must not weaken the global rules or duplicate this matrix.+Global stop/continue rules for all three top-level routes, plus concrete failure handling for Generate PPTX. Section 2 applies across routes; Sections 1 and 3 apply only to Generate PPTX. Owning route and stage documents may add narrower handling, but must not weaken the global rules or duplicate this matrix.**Hard rule**: A failed required artifact blocks the next gate. A failed convenience surface falls back to the canonical channel and does not block the active route.diff --git a/skills/ppt-master/workflows/index.md b/skills/ppt-master/workflows/index.mdindex 60072e2c..b76935e9 100644--- a/skills/ppt-master/workflows/index.md+++ b/skills/ppt-master/workflows/index.md@@ -12,8 +12,7 @@ Maintainer-only inventory for adding, moving, or removing workflow documents. Ru|---|---|---|| `generate-pptx` | Top-level route | [`generate-pptx.md`](./generate-pptx.md) || `create-template` | Top-level route | [`create-template.md`](./create-template.md) |-| `template-fill-pptx` | Top-level route | [`template-fill-pptx.md`](./template-fill-pptx.md) |-| `native-enhance-pptx` | Top-level route | [`native-enhance-pptx.md`](./native-enhance-pptx.md) |+| `edit-native-pptx` | Top-level route | [`edit-native-pptx.md`](./edit-native-pptx.md) |## 2. Supporting Documents@@ -35,7 +34,7 @@ Maintainer-only inventory for adding, moving, or removing workflow documents. Ru| `visual-review` | Quality gate | [`stages/visual-review.md`](./stages/visual-review.md) | Before Generate Step 7 || `live-preview` | Editor stage | [`stages/live-preview.md`](./stages/live-preview.md) | Generate preview / post-export || `customize-animations` | Post-processing stage | [`stages/customize-animations.md`](./stages/customize-animations.md) | Generate conditional export |-| `generate-audio` | Shared audio stage | [`stages/generate-audio.md`](./stages/generate-audio.md) | Generate / Enhance Native |+| `generate-audio` | Shared audio stage | [`stages/generate-audio.md`](./stages/generate-audio.md) | Generate / Edit Native || `failure-recovery` | Governance | [`governance/failure-recovery.md`](./governance/failure-recovery.md) | All routes |## 3. Maintenance Rulesdiff --git a/skills/ppt-master/workflows/profiles/beautify-pptx.md b/skills/ppt-master/workflows/profiles/beautify-pptx.mdindex 1f2d0a6c..f1c60304 100644--- a/skills/ppt-master/workflows/profiles/beautify-pptx.md+++ b/skills/ppt-master/workflows/profiles/beautify-pptx.md@@ -4,7 +4,7 @@ description: Generate profile for 1:1, content-faithful re-layout of an existing# Beautify PPTX (Re-layout) Profile-> Generate profile, not a top-level route. [`template-fill-pptx.md`](../template-fill-pptx.md) reuses a deck's design and swaps in new content; this profile keeps a deck's content and redoes its layout.+> Generate profile, not a top-level route. [`edit-native-pptx.md`](../edit-native-pptx.md) keeps a deck's native design and edits selected pages; this profile keeps a deck's content and redoes its layout.Re-lays-out an existing `.pptx`: text is preserved **verbatim** and sourcepalette / fonts are the preselected recommendation. Only explicit user@@ -32,7 +32,7 @@ Beautify constraints in this file apply in either runtime.**Hard rule — content is frozen**: every text string from the source is preserved exactly (no add / remove / reword / reorder). Beautification freedom lives only in layout, hierarchy, spacing, and visual rhythm.-**Hard rule — not a patch, not a fill**: this regenerates a native deck through the selected Default or Quick SVG → PPTX runtime. It does **not** edit the source file in place, and it is **not** [`template-fill-pptx`](../template-fill-pptx.md) (which clones source slides and replaces text). It also does not parse an arbitrary third-party template for text-only substitution (the rejected #53 direction) — it builds every page from scratch.+**Hard rule — not a patch, not a fill**: this regenerates a native deck through the selected Default or Quick SVG → PPTX runtime. It does **not** edit the source file in place, and it is **not** [`edit-native-pptx`](../edit-native-pptx.md) (which restores unchanged source slides and edits only planned pages). It also does not parse an arbitrary third-party template for text-only substitution (the rejected #53 direction) — it builds every page from scratch.**Distinct from mirror templates**: `replication_mode: mirror` ([`executor-structured.md`](../../references/executor-structured.md) §1.1) keeps layout + visuals verbatim and edits text. Beautify is the inverse — content verbatim, layout redone, source identity recommended unless the user overrides it.diff --git a/skills/ppt-master/workflows/routing.md b/skills/ppt-master/workflows/routing.mdindex c534ee73..0dac0909 100644--- a/skills/ppt-master/workflows/routing.md+++ b/skills/ppt-master/workflows/routing.md@@ -1,5 +1,5 @@----description: Deterministic selection among PPT Master's four top-level artifact routes.+description: Deterministic selection among PPT Master's three top-level artifact routes.---# Routing Rules@@ -16,10 +16,10 @@ route selection. After selection, the active runtime authority owns execution.| Rule | Behavior ||---|---|-| One artifact lifecycle | Every request enters Generate PPTX, Create Template, Fill Native PPTX, or Enhance Native PPTX |+| One artifact lifecycle | Every request enters Generate PPTX, Create Template, or Edit Native PPTX || Supporting documents are not top-level routes | Create Template child workflows, generation profiles, stages, and governance documents refine the selected route; never offer them as competing top-level routes || Missing prerequisite | State the missing prerequisite and stop that route; do not invent an alternative |-| Ambiguous existing-deck request | Ask one discriminator question only when needed: regenerate visible slides, fill native slide shells with new content, or preserve slides and add native behavior? |+| Ambiguous existing-deck request | Ask one discriminator question only when needed: regenerate the visible design (Generate), or preserve the native deck and edit it (Edit Native PPTX)? || Explicit user override | Honor explicit route instructions only when the route preconditions are satisfied |**Forbidden — route-choice menus**: Do not present multiple implementation paths when the request already matches one row in §2. Ordinary design choices remain at the selected route's existing confirmation gate.@@ -32,8 +32,7 @@ route selection. After selection, the active runtime authority owns execution.|---|---|---|---|---|---|| Generate PPTX | Create, reconstruct, or visually regenerate a presentation/video from sources or a topic; templates remain optional | Image to PPTX: [`image-to-pptx`](./profiles/image-to-pptx.md), always Quick; Beautify: [`beautify-pptx`](./profiles/beautify-pptx.md), Default or Quick; ordinary [`generate-pptx`](./generate-pptx.md) / [`quick-generate`](./profiles/quick-generate.md) | Facts exist or research can gather them; Image to PPTX also requires Codex and an ordered page-frame roster | Author SVG pages and export a new PPTX | Default: spec/lock/SVG/PPTX; Quick: optional source/resource artifacts, no spec/lock, SVG/PPTX; either may derive narrated PPTX/MP4 || Create Template | Create a reusable brand/style/layout/deck template from one or more PPTX/SVG files, images/PDFs, direct or file-based text, documents/websites, brand assets, or a mixed reference bundle | [`create-template`](./create-template.md) | A reusable-template request exists; reference material is optional, and project scope additionally requires an initialized target project | Author a new portable workspace; never modify any reference file in place | Workspace with required `templates/`, optional `images/` / `icons/`, and optional review `exports/` |-| Fill Native PPTX | Use a raw PPTX's native slide shells and replace/fill content | [`template-fill-pptx`](./template-fill-pptx.md) | Source PPTX plus new material/topic | Clone and patch PPTX through OOXML; no SVG pipeline | New filled PPTX in project `exports/` |-| Enhance Native PPTX | Keep a finished PPTX's visible slides stable while adding notes, audio, timings, or transitions | [`native-enhance-pptx`](./native-enhance-pptx.md) | Finished source PPTX exists | Append/update scoped OOXML parts; no slide regeneration | New enhanced PPTX in project `exports/` |+| Edit Native PPTX | Keep an existing PPTX's native design: fill it with new content, edit or restructure selected pages, or add notes, narration, timings, or transitions with visible slides untouched | [`edit-native-pptx`](./edit-native-pptx.md) | Source PPTX exists; new material only when content changes | `pptx_to_svg.py --roundtrip` workspace: unchanged pages restore byte-for-byte, edited pages rebuild only edited objects, notes/motion overlay | New PPTX in workspace `exports/` |---@@ -46,7 +45,8 @@ route selection. After selection, the active runtime authority owns execution.| The effective delivery purpose is recorded, self-running, or video-directed | Inside the already selected Default or explicit Quick runtime, load [`video-design`](../references/video-design.md) before whole-solution/page planning. This is a conditional design reference, not a profile or fifth route; notes, animation, audio, and optional native MP4 remain owned by their existing stages || Explicit quick/fast, skip-strategy, or direct SVG-to-PPTX intent without an active fidelity profile | Load [`quick-generate`](./profiles/quick-generate.md) directly without loading `generate-pptx.md`: prepare sources/resources as needed, let the current agent decide without interaction, directly apply at most one exact workspace root per kind supplied for this run, otherwise use free design, omit Strategist/Confirm UI/spec/lock, hand-author SVG, run the lockless final checker, and export the final PPTX || Topic only, or supplied sources leave planning-critical factual gaps | Run [`topic-research`](./stages/topic-research.md) inside the selected Generate profile's source preparation: immediately for topic-only input, or after conversion and reading for source-backed input; research only the identified gaps |-| Existing PPTX may be split, merged, dropped, reordered, or re-outlined | Treat the PPTX as source content through the selected Generate authority's source intake; continue Default unless explicit Quick intent selected that runtime |+| Existing PPTX must be split, merged, or re-outlined into newly designed pages | Treat the PPTX as source content through the selected Generate authority's source intake; continue Default unless explicit Quick intent selected that runtime |+| Existing PPTX pages are dropped, reordered, or repeated without redesign | Not Generate: route to Edit Native PPTX, whose `page_plan.json` owns selection, order, and repetition || Default Generate reaches planning | Step 3 prepares template candidates without interaction. Stage 1 then confirms the communication contract and free-design/template choice together; only a confirmed non-free choice runs [`apply-template-workspace`](./stages/apply-template-workspace.md) before Stage 2 || Explicit current brand/style/layout/deck workspace root outside Image to PPTX | Default Generate preserves the exact path as a Stage-1 template candidate; Quick Generate validates and installs it directly without Steps 3–4 or Confirm UI. Classify it as `library` only when its normalized root exactly matches a registered index entry; otherwise retain `explicit`. Consume the workspace root, never only its inner `templates/` directory || Split-mode project resumes in a fresh chat | Run [`resume-execute`](./stages/resume-execute.md) inside the active Generate route |@@ -57,7 +57,7 @@ route selection. After selection, the active runtime authority owns execution.| User requests preview, selection, or annotation application outside Image to PPTX | Use the default Generate pipeline and run [`live-preview`](./stages/live-preview.md) at the stage defined there; explicit Quick + preview intent falls back to default rather than dropping preview. Image to PPTX remains Quick-only and uses its mandatory canonical-frame recomposition comparison instead of this interactive stage || User requests page transitions, auto-advance, or deck-wide animation settings without page-specific motion planning or an existing `animations.json` | Load [`animations`](../references/animations.md) and apply its export-level contract || `<project_path>/animations.json` already exists, the user explicitly requests per-slide/object-level animation control, or the effective Custom Animations outcome in `design_spec.md §I` is enabled | Run [`customize-animations`](./stages/customize-animations.md) after the final SVG quality gate and any enabled speaker-note pass, before Generate Step 7. A §IX `Motion suggestion` informs an active pass but never triggers it alone |-| Generate PPTX receives an explicit narration request or has effective Narration Audio enabled in `design_spec.md §I`; Enhance Native PPTX has a confirmed `audio.enabled: true` module | Run [`generate-audio`](./stages/generate-audio.md) after the owning route's notes/export readiness; Generate audio implies effective Speaker Notes enabled |+| Generate PPTX receives an explicit narration request or has effective Narration Audio enabled in `design_spec.md §I`; Edit Native PPTX has narration confirmed in its plan | Run [`generate-audio`](./stages/generate-audio.md) after the owning route's notes readiness; audio implies notes on every output page |**Hard rule — fidelity profiles, not fifth routes**: Image to PPTX and Beautifychange different source/page invariants and are mutually exclusive. Image to@@ -99,7 +99,7 @@ When a PPTX already contains native Master/Layout parts, `create-template` mirro| Input | Route behavior ||---|---|| One or more images containing page frames + explicit final-deck reconstruction intent | Generate PPTX with the Codex-supported, Quick-only [`image-to-pptx`](./profiles/image-to-pptx.md); normalize page frames first and do not infer reusable native structure from pixels |-| Raw PPTX called a template + new content | Fill Native PPTX unless the user explicitly asks for a reusable template workspace |+| Raw PPTX called a template + new content | Edit Native PPTX unless the user explicitly asks for a reusable template workspace || Any supported reference bundle or direct-text brief + reusable template request | Create Template || Current template workspace root + content | Default: [`generate-pptx`](./generate-pptx.md) Stage-1 template choice; explicit Quick: direct validated workspace application || Semantic-legacy or incomplete structured package | Create a new workspace through Create Template; do not migrate in place |@@ -133,9 +133,9 @@ or reusable scenario/content semantics.| Artifact state | Narration route ||---|---|| Main-generated project with notes and exported deck | Shared [`generate-audio`](./stages/generate-audio.md) stage |-| Arbitrary finished PPTX that must preserve visible slides | Enhance Native PPTX; its narration module invokes the same shared audio-stage rules |+| Arbitrary finished PPTX that must preserve visible slides | Edit Native PPTX; its narration module invokes the same shared audio-stage rules against the round-trip workspace |-Object animation for generated SVG projects uses the animation stage. Native PPTX routes preserve existing object-animation fingerprints and do not silently claim an animation-editing capability.+Object animation for generated SVG projects uses the animation stage. Edit Native PPTX preserves source motion by default and writes requested motion as an overlay per [`animations.md`](../references/animations.md).---diff --git a/skills/ppt-master/workflows/stages/apply-template-workspace.md b/skills/ppt-master/workflows/stages/apply-template-workspace.mdindex 66228598..c2276ce7 100644--- a/skills/ppt-master/workflows/stages/apply-template-workspace.md+++ b/skills/ppt-master/workflows/stages/apply-template-workspace.md@@ -42,7 +42,7 @@ may combine only with non-overlapping kinds. Default permits one explicit rootbeside registered choices; Quick applies the same kind constraint. Rejectduplicate kinds before validation.-**Hard rule — raw source boundary**: A raw PPTX is not a template workspace. Raw PPTX plus new content uses [`template-fill-pptx`](../template-fill-pptx.md). When the user wants reusable SVG/template generation, run [`create-template`](../create-template.md) first; its validated workspace-root handoff becomes a Stage-1 candidate and is preselected only when it is the sole supplied root. Never add Master/Layout/placeholder structure directly to an existing PPTX or SVG project.+**Hard rule — raw source boundary**: A raw PPTX is not a template workspace. Raw PPTX plus new content uses [`edit-native-pptx`](../edit-native-pptx.md). When the user wants reusable SVG/template generation, run [`create-template`](../create-template.md) first; its validated workspace-root handoff becomes a Stage-1 candidate and is preselected only when it is the sole supplied root. Never add Master/Layout/placeholder structure directly to an existing PPTX or SVG project.**Current-contract gate**: Reject flat-root, semantic-legacy, or incomplete structured packages, including old baseline/distillation metadata, incomplete Master identity, or legacy direct atomic placeholders. Create a new current workspace through Create Template; use the original PPTX when native topology must be preserved.diff --git a/skills/ppt-master/workflows/stages/generate-audio.md b/skills/ppt-master/workflows/stages/generate-audio.mdindex a749e7cb..20ab51eb 100644--- a/skills/ppt-master/workflows/stages/generate-audio.md+++ b/skills/ppt-master/workflows/stages/generate-audio.md@@ -11,20 +11,20 @@ This stage is **context-independent**: it reads `notes/*.md` and queries the sel**Trigger**: In Generate PPTX, run when the effective `Narration Audio` outcomein `design_spec.md` §I is `enabled`; a later explicit request first updates thatoutcome and its provenance. Quick Generate instead runs when the request or-current agent's active-context decision selects narration. In Enhance Native-PPTX, run when its confirmed enhancement plan has `audio.enabled: true`.+current agent's active-context decision selects narration. In Edit Native+PPTX, run when the confirmed plan enables narration.**Hard dependency — speaker notes**: Audio requires complete per-slide speakernotes. Generate PPTX additionally requires its effective `Speaker Notes`-outcome to be enabled; Enhance Native PPTX follows its confirmed notes/audio-plan, where enabling audio also enables notes. Quick records the same dependency+outcome to be enabled; Edit Native PPTX follows its confirmed plan, where+narration requires a note for every output page. Quick records the same dependencyin active context. Do not enter audio generation while the owning route's notesare missing or incomplete; generate and validate those notes first, then resumethis stage.## When to Run-- Per-page narration files exist at `notes/*.md`. In Generate PPTX, split `notes/total.md` during Step 7.1. In Enhance Native PPTX, the notes module writes numeric files such as `001.md`.+- Per-page narration files exist at `notes/*.md`. In Generate PPTX, split `notes/total.md` during Step 7.1. In Edit Native PPTX, notes are `notes/<svg-stem>.md` keyed by output page; the round-trip roster comes from `page_plan.json` and copies inherit source notes.- Default mode: `edge-tts` is installed (`python3 -m pip install edge-tts`).- The stage is page-level only: one note becomes `audio/<stem>.<audio-ext>` plus `audio/<stem>.srt` on provider-timed paths, or one audio file with Qwen / explicit CosyVoice audio-only mode. Never substitute one long track or automatic splitting.- Final/literal script notes are synthesized verbatim. Source SRT timecodes are pacing evidence only; new provider timing owns the generated audio/SRT set.@@ -54,9 +54,9 @@ this stage.If per-slide notes are missing, recover through the owning route. GeneratePPTX returns to its enabled notes branch and then runs-`total_md_split.py <project_path>`; Enhance Native PPTX returns to-`native-enhance-pptx` Step 6 and writes numeric notes directly. Never run the-Generate splitter against a Native Enhance project.+`total_md_split.py <project_path>`; Edit Native PPTX returns to+[`edit-native-pptx`](../edit-native-pptx.md) §6 and writes `notes/<svg-stem>.md`+per output page. Never run the Generate splitter against a round-trip workspace.---@@ -127,15 +127,15 @@ when narration-cue sync or subtitle delivery needs page-local SRT; on thenative-export branch, audio-only narration can still calibrate the sound mixfrom its complete per-page tracks.-**Default / Enhance Native — one-shot interaction (mandatory)**:+**Default / Edit Native — one-shot interaction (mandatory)**:-For Default or Enhance Native, send one message that resolves all five configuration decisions and recommends each value. Before offering automatic video export, run `python3 skills/ppt-master/scripts/powerpoint_video.py --check`; do not present an unavailable local capability as executable. Do NOT split into multiple rounds.+For Default or Edit Native, send one message that resolves all five configuration decisions and recommends each value. Before offering automatic video export, run `python3 skills/ppt-master/scripts/powerpoint_video.py --check`; do not present an unavailable local capability as executable. Do NOT split into multiple rounds.An explicit slideshow-capture choice does not run this availability check; ituses the manual Windows playback handoff below.-**Cloned-voice fast path**: if the user mentioned a cloned voice / 克隆音色 / 复刻音色 / "my own voice" along with a `voice_id`, skip the voice-recommendation list — set the named provider (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`) and pin that `voice_id`. Quick applies its exception above; Default and Enhance Native confirm only rate + embed + video.+**Cloned-voice fast path**: if the user mentioned a cloned voice / 克隆音色 / 复刻音色 / "my own voice" along with a `voice_id`, skip the voice-recommendation list — set the named provider (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`) and pin that `voice_id`. Quick applies its exception above; Default and Edit Native confirm only rate + embed + video.-**Message template** (Chinese; translate to user's chat language if different). “Embed” means caller-specific integration: SVG re-export for Generate PPTX, or native OOXML application for Enhance Native PPTX.+**Message template** (Chinese; translate to user's chat language if different). “Embed” means caller-specific integration: SVG re-export for Generate PPTX, or `svg_to_pptx.py --roundtrip --recorded-narration audio` for Edit Native PPTX.> 检测到 notes 主语言为 **<语言>**(locale: `<locale>`)。基于 deck 调性(<风格>),我推荐以下配置:>@@ -169,8 +169,9 @@ uses the manual Windows playback handoff below.## Step 4: Execute (no further interaction)**Blocking notes preflight**: `notes_to_audio.py` resolves the complete notes-roster from `svg_output/*.svg` on Generate projects or-`analysis/slide_index.json` on Native Enhance projects. Before any TTS request,+roster from `svg_output/*.svg` on Generate projects or from `page_plan.json` /+the identity roster on Edit Native PPTX round-trip workspaces (copies inherit+source notes). Before any TTS request,every expected note must exist, be readable, and contain spoken text. Exit code`2` returns the caller to its notes-generation step; never continue with partialaudio generation.@@ -408,7 +409,7 @@ that handoff remains incomplete until a real capture is accepted.| Caller | After audio generation ||---|---|| Generate PPTX | Derive narration-cued motion when selected; otherwise pass canonical motion, inherit base motion, or use explicit all-motion-off. Export with `--recorded-narration audio`; Quick also passes `--quick-generate --with-notes`. Native video uses conversion trace plus raw export and cue mix as required. Explicit capture returns the narrated PPTX for the handoff above, skips trace-only sound work and mixing, then aligns subtitles against the accepted capture. |-| Enhance Native PPTX | Return to [`native-enhance-pptx`](../native-enhance-pptx.md) Step 9. Native video passes its final PPTX to `powerpoint_video.py`; explicit capture uses the same handoff above and skips mixing. |+| Edit Native PPTX | Return to [`edit-native-pptx`](../edit-native-pptx.md) §7 and export with `--roundtrip --recorded-narration audio --use-narration-timings`. Native video passes its final PPTX to `powerpoint_video.py`; explicit capture uses the same handoff above and skips mixing. |For Qwen or explicit CosyVoice audio-only mode, embed/export the audio normallybut skip `narration_timing.json`, `narration_sync.py animations`, SRT merge, and