Skip to content

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

feat(intake): standardize PPTX intake into analysis/ as the canonical must-read folder

hugohe3cd1b261f2f2f
diff --git a/docs/faq.md b/docs/faq.md
index d1cd3b7a..d831727d 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -158,13 +158,21 @@ For post-generation fixes, simply tell the AI: "Page 3 has a layout issue — th
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 four routes:
-- **Keep content + redo layout** → **beautify (re-layout)**: text stays verbatim, page count and order are preserved 1:1, only the layout is redone while inheriting the original palette/fonts. Say "make this deck look better" / "re-layout this, keep the wording". See the [beautify workflow](../skills/ppt-master/workflows/beautify-pptx.md).
-- **Replace content + keep design** → **template-fill**: keep the original design, pour new content back into the native slides (next question).
-- **Keep only content, redo design and pagination** → **main pipeline (free re-architecture)**: treat the PPT as an ordinary source document — extract it to Markdown with `ppt_to_md`, then run the standard generation flow, where the Strategist re-architects the outline freely (merge / split / reorder pages). Say "build a better deck from this one's content".
-- **Keep content + keep design** → no generation needed; just use the original file.
+| Intent | Route | What stays fixed |
+|---|---|---|
+| Keep content + redo layout | **beautify (re-layout)** | Page count, page order, per-slide wording, chart/table data |
+| Replace content + keep design | **template-fill** | Native source slide design; selected pages may be reused/reordered |
+| Keep only content, redo design and pagination | **main pipeline** | Source facts; story structure and page count may change |
+| Keep content + keep design | No generation needed | Use the original file |
+
+Use **beautify** when the source deck's page split is part of the requested output: text stays verbatim, page count and order are preserved 1:1, only layout / hierarchy / whitespace are redone while inheriting the original palette/fonts. Say "make this deck look better" / "re-layout this, keep the wording". See the [beautify workflow](../skills/ppt-master/workflows/beautify-pptx.md).
+
+Use 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.
+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?**
+
There is also one orthogonal route: if you don't want to produce a deck right now but want to **harvest the design into a reusable template** for future use, use **create-template** (see "How do I create a custom template?" below).
---
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index e34e7443..95bf57fb 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -160,13 +160,21 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-t
把「用一份已有 PPT」拆成两个问题:**留不留它的内容**、**留不留它的设计(版式 + 视觉)**。四种组合对应四条路:
-- **留内容 + 重做版式** → **beautify(美化 / 重排)**:文字逐字不动、页数页序 1:1 保留,只重排版式并继承原配色字体。说「把这份 PPT 美化一下 / 重新排版,内容别动」。见 [beautify 工作流](../../skills/ppt-master/workflows/beautify-pptx.md)。
-- **换内容 + 留设计** → **template-fill(套模板)**:保留原设计,把新内容灌回原生页面(见下一问)。
-- **只留内容,设计与页数都重来** → **主管线(自由重构)**:把 PPT 当普通源文档,用 `ppt_to_md` 抽成 Markdown 再走标准生成流程,Strategist 会自由重排大纲(合页 / 拆页 / 换序)。说「用这份 PPT 的内容重做一份更好的」。
-- **留内容 + 留设计** → 不必生成,直接用原文件即可。
+| 意图 | 路线 | 固定不变的东西 |
+|---|---|---|
+| 留内容 + 重做版式 | **beautify(美化 / 重排)** | 页数、页序、每页文字、图表/表格数据 |
+| 换内容 + 留设计 | **template-fill(套模板)** | 原生页面设计;可选择、乱序、复用源页 |
+| 只留内容,设计与分页都重来 | **主管线** | 源事实;故事结构和页数都可重构 |
+| 留内容 + 留设计 | 不必生成 | 直接用原文件 |
+
+用 **beautify** 的前提是:原 PPT 的分页本身就是输出要求的一部分。文字逐字不动、页数页序 1:1 保留,只重排版式、层级和留白,并继承原配色字体。典型说法是「把这份 PPT 美化一下 / 重新排版,内容别动」。见 [beautify 工作流](../../skills/ppt-master/workflows/beautify-pptx.md)。
+
+用 **主管线** 的前提是:原 PPT 只是内容材料。流程会用 `ppt_to_md` 抽成 Markdown,并读取 `analysis/` 里的 PPTX intake 事实,再由 Strategist 自由重构大纲(合页 / 拆页 / 换序)。典型说法是「用这份 PPT 的内容重做一份更好的」或「提炼成 10 页高管汇报」。
beautify 和主管线的一句话判别:**原来的分页是要保留的信息,还是只是前一作者的结构、可以推翻?** 保留 → beautify;推翻 → 主管线。
+如果用户说法含糊,比如「把这份 PPT 做得更专业一点」「优化一下这个 deck」,AI 应先问一句:**要保留原页数、页序和每页文字,只做美化;还是把 PPT 当素材,重新梳理成一份新故事?**
+
还有一条正交的路:如果你不是要现在产出一份 deck,而是想把这套设计**收成可复用模板**供以后反复用,走 **create-template**(见下面「如何制作自定义模板」)。
---
diff --git a/projects/README.md b/projects/README.md
index 7aa2a45b..ea77365e 100644
--- a/projects/README.md
+++ b/projects/README.md
@@ -20,6 +20,7 @@ project_name_format_YYYYMMDD/
│ ├── Raw files / URL archives / Converted Markdown
│ └── *_files/ # Markdown companion resource directory (e.g., images)
├── images/ # Image assets used by the project
+├── analysis/ # Extracted source facts (PPTX intake bundle, image_analysis.csv)
├── notes/
│ ├── 01_xxx.md
│ ├── 02_xxx.md
@@ -31,8 +32,7 @@ project_name_format_YYYYMMDD/
│ ├── 01_xxx.svg
│ └── ...
├── templates/ # Project-level templates (if any)
-├── *.pptx
-└── image_analysis.csv # Optional, image scan analysis results
+└── *.pptx
```
Projects can remain at different stages and do not necessarily have all artifacts at once. For example:
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 1266a135..ff1d960f 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -49,6 +49,7 @@ description: >
| `${SKILL_DIR}/scripts/source_to_md/doc_to_md.py` | Documents to Markdown — native Python for DOCX/HTML/EPUB/IPYNB, pandoc fallback for legacy formats (.doc/.odt/.rtf/.tex/.rst/.org/.typ) |
| `${SKILL_DIR}/scripts/source_to_md/excel_to_md.py` | Excel workbooks to Markdown — supports .xlsx/.xlsm; legacy .xls should be resaved as .xlsx |
| `${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py` | PowerPoint to Markdown |
+| `${SKILL_DIR}/scripts/pptx_intake.py` | Standard PPTX intake enrichment — canvas / identity / slide geometry / tables / native chart data |
| `${SKILL_DIR}/scripts/source_to_md/web_to_md.py` | Web page to Markdown (supports WeChat via `curl_cffi`) |
| `${SKILL_DIR}/scripts/project_manager.py` | Project init / validate / manage |
| `${SKILL_DIR}/scripts/icon_sync.py` | Copy chosen library icons into `<project>/icons/` at selection time; missing names reported + non-zero (re-pick gate) |
@@ -89,6 +90,19 @@ For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.
| `live-preview` | `workflows/live-preview.md` | Browser-based live preview — auto-started during generation and re-enterable any time the user mentions "live preview", "preview", "看效果", or wants to click/select a slide element |
| `visual-review` | `workflows/visual-review.md` | Per-page rubric-based visual self-check — run only when the user explicitly asks for a visual re-pass on the generated SVGs (between Executor and post-processing). Opt-in only; never invoked by the main pipeline. |
+### PPTX Route Boundary
+
+When the user provides an existing `.pptx`, route by the role of the source deck:
+
+| User intent | Route | Contract |
+|---|---|---|
+| Preserve the deck's page split, page order, and per-slide wording; improve layout / hierarchy / whitespace | `beautify` | Source page count and order are 1:1; text and data values are frozen; visual identity is inherited after confirmation |
+| Treat the deck as source material; rethink the story, merge / split / drop / reorder pages, or change page count | Main pipeline | `ppt_to_md` + PPTX intake provide content facts and candidates; Strategist may re-architect freely |
+| Reuse the deck's native design with new material | `template-fill` | Clone selected source slides and replace text / table / chart data directly in OOXML; no SVG generation |
+| Harvest the deck as a reusable future template | `create-template` | Build a template package, not a one-off generated deck |
+
+Ambiguous requests such as "make this PPT more professional" or "optimize this deck" MUST be clarified with one question before routing: "Should the original page count/order and each slide's wording be preserved, or should the deck be treated as source material and restructured into a new story?" Preserve → `beautify`; restructure → main pipeline.
+
---
## Workflow
@@ -107,7 +121,7 @@ When the user provides non-Markdown content, convert immediately:
| DOCX / Word / Office document | `python3 ${SKILL_DIR}/scripts/source_to_md/doc_to_md.py <file>` |
| XLSX / XLSM / Excel workbook | `python3 ${SKILL_DIR}/scripts/source_to_md/excel_to_md.py <file>` |
| CSV / TSV | Read directly as plain-text table source |
-| PPTX / PowerPoint deck | `python3 ${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py <file>` |
+| PPTX / PowerPoint deck | `python3 ${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py <file>` for Markdown content; after Step 2 `import-sources`, standard PPTX intake is also written to `<project>/analysis/` |
| EPUB / HTML / LaTeX / RST / other | `python3 ${SKILL_DIR}/scripts/source_to_md/doc_to_md.py <file>` |
| Web link | `python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL>` |
| WeChat / high-security site | `python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL>` (requires `curl_cffi`, included in `requirements.txt`) |
@@ -148,6 +162,16 @@ Import source content (choose based on the situation):
| Has source files (PDF/MD/etc.) | `python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files...> --move` |
| User provided text directly in conversation | No import needed — content is already in conversation context; subsequent steps can reference it directly |
+For PPTX sources, `import-sources` automatically runs the standard intake enrichment:
+
+```bash
+python3 ${SKILL_DIR}/scripts/pptx_intake.py <project_path>/sources/<source.pptx> -o <project_path>/analysis
+```
+
+It writes `identity.json` (canvas, theme palette/fonts, observed usage), `slide_library.json` (text slots, geometry, native tables, native chart caches), and `source_profile.json` (Strategist-facing digest). In the main generation path these are source facts and recommendation candidates, not replica constraints; beautify and template-fill workflows decide separately which fields become locked constraints.
+
+Current boundary: PPTX intake is single-deck per project. If multiple PPTX files are imported, the first one writes `analysis/source_profile.json`; later PPTX files are still archived / converted to Markdown, but their intake analysis is skipped with a note rather than overwriting the first deck's facts.
+
> ⚠️ **MUST use `--move`** (not copy): all source files — Step 1's generated Markdown, original PDFs / MDs / images — go into `sources/` via `import-sources --move`. After execution they no longer exist at the original location. Intermediate artifacts (e.g., `_files/`) are handled automatically.
**✅ Checkpoint — Confirm project structure created successfully, `sources/` contains all source files, converted materials are ready. Proceed to Step 3.**
@@ -282,6 +306,8 @@ Read references/strategist.md
> ⚠️ **Mandatory gate**: before writing `design_spec.md`, Strategist MUST `read_file templates/design_spec_reference.md` and follow its full I–XI section structure. See `strategist.md` Section 1.
+**`<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` + `identity.json` + `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 Eight Confirmations, Strategist MUST read the auto-extracted fact files already in `analysis/` — currently `source_profile.json` (PPTX intake), when present. Use canvas / chart / table entries as factual source context, and use palette / typography observations as recommendation candidates only unless a standalone workflow (beautify / template-fill) has explicitly promoted them to constraints. (`image_analysis.csv` lands later, at the image-analysis step below, and is the authoritative image-fact source there.)
+
**Eight Confirmations** (full template: `templates/design_spec_reference.md`):
⛔ **BLOCKING**: present the Eight Confirmations as a single bundled recommendation set and **wait for explicit user confirmation or modification** before outputting Design Specification & Content Outline. This is the single core confirmation point — once confirmed, all subsequent steps proceed automatically.
@@ -358,12 +384,12 @@ After the Eight Confirmations are approved and **before outputting `design_spec.
The formula renderer uses a provider fallback chain by default: `codecogs,quicklatex,mathpad,wikimedia`. The first three are color-aware; Wikimedia is an availability fallback. Formula PNGs are transparent by default: manifest `background` is the temporary render matte and transparency-removal reference, not a retained final background unless `transparent: false` is set for that item. Do not scan `spec_lock.md` for `$...$` or `$$...$$`. Dollar-delimited math in source material is only a signal for Strategist; the renderer consumes the explicit manifest.
-If the user provided images or formula PNGs were rendered, run analysis **before outputting the design spec**:
+If the user provided images or formula PNGs were rendered, run analysis **before outputting the design spec**. It writes `analysis/image_analysis.csv` — the authoritative image-fact source in the `analysis/` folder, which MUST be read before authoring §VIII:
```bash
python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images
```
-> ⚠️ **Image handling**: NEVER directly read / open / view image files (`.jpg`, `.png`, etc.). All image info comes from `analyze_images.py` output or the Design Spec's Image Resource List.
+> ⚠️ **Image handling**: NEVER directly read / open / view image files (`.jpg`, `.png`, etc.). All image info comes from `analyze_images.py` output (`analysis/image_analysis.csv`) or the Design Spec's Image Resource List.
**Output**:
- `<project_path>/design_spec.md` — human-readable design narrative
@@ -372,6 +398,7 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images
**✅ Checkpoint — Phase deliverables complete, auto-proceed to next step**:
```markdown
## ✅ Strategist Phase Complete
+- [x] Read the auto-extracted facts already in `analysis/` (e.g. `source_profile.json`) before the Eight Confirmations
- [x] Eight Confirmations completed (user confirmed via Confirm UI `result.json` or chat fallback)
- [x] Split-mode note appended below the eight items (heavy or normal variant)
- [x] Spec-refinement opt-in line appended (default OFF; only the user's explicit request enters the refine-spec workflow)
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 04371adc..8ca4500b 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -331,7 +331,7 @@ Handle images by their status in the Design Spec's Image Resource List. Status e
**`no-crop` images**: when a `spec_lock.md images` entry ends with ` | no-crop`, size the container to the image's native ratio (from `analyze_images.py` or file dims) and use `preserveAspectRatio="xMidYMid meet"`. Untagged entries are croppable — default to `slice`.
-**Formula images**: rows with `Acquire Via: formula` or `Type: Latex Formula` MUST be treated as no-crop even if a legacy `spec_lock.md` forgot the flag. Use the dimensions from `design_spec.md §VIII`, `image_analysis.csv`, or `images/formula_manifest.json`; do not normalize all formulas to one height unless the spec explicitly states that layout choice.
+**Formula images**: rows with `Acquire Via: formula` or `Type: Latex Formula` MUST be treated as no-crop even if a legacy `spec_lock.md` forgot the flag. Use the dimensions from `design_spec.md §VIII`, `analysis/image_analysis.csv`, or `images/formula_manifest.json`; do not normalize all formulas to one height unless the spec explicitly states that layout choice.
### 6.1 Inline Attribution for Sourced Images (web path)
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index a51ccee2..915c200b 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -40,7 +40,7 @@ python3 scripts/update_repo.py
| Area | Primary scripts | Documentation |
|------|-----------------|---------------|
-| Conversion | `source_to_md/pdf_to_md.py`, `source_to_md/doc_to_md.py`, `source_to_md/excel_to_md.py`, `source_to_md/ppt_to_md.py`, `source_to_md/web_to_md.py` | [docs/conversion.md](./docs/conversion.md) |
+| Conversion | `source_to_md/pdf_to_md.py`, `source_to_md/doc_to_md.py`, `source_to_md/excel_to_md.py`, `source_to_md/ppt_to_md.py`, `source_to_md/web_to_md.py`, `pptx_intake.py` | [docs/conversion.md](./docs/conversion.md) |
| Project management | `project_manager.py`, `batch_validate.py`, `generate_examples_index.py`, `error_helper.py`, `pptx_template_import.py`, `template_fill_pptx.py` | [docs/project.md](./docs/project.md) |
| SVG pipeline | `finalize_svg.py`, `svg_to_pptx.py`, `total_md_split.py`, `svg_quality_checker.py`, `extract_svg_assets.py`, `animation_config.py`, `notes_to_audio.py` | [docs/svg-pipeline.md](./docs/svg-pipeline.md) |
| Spec maintenance | `update_spec.py` | [docs/update_spec.md](./docs/update_spec.md) |
diff --git a/skills/ppt-master/scripts/analyze_images.py b/skills/ppt-master/scripts/analyze_images.py
index 548a9c6f..4b083d35 100644
--- a/skills/ppt-master/scripts/analyze_images.py
+++ b/skills/ppt-master/scripts/analyze_images.py
@@ -18,7 +18,8 @@ Usage:
Output:
- Analysis report displayed in console
- - Generates image_analysis.csv in the parent directory of the images folder
+ - Generates image_analysis.csv under the project's analysis/ directory
+ (sibling of the images folder), alongside the PPTX intake bundle
"""
import argparse
@@ -572,9 +573,12 @@ def main() -> None:
print_results(results)
generate_markdown(results, canvas_key)
- # Save to CSV file (saved in the parent directory of the images folder)
+ # Save to CSV file (saved under the project's analysis/ directory,
+ # alongside the PPTX intake bundle)
parent_dir = os.path.dirname(images_dir)
- csv_path = os.path.join(parent_dir, "image_analysis.csv")
+ analysis_dir = os.path.join(parent_dir, "analysis")
+ os.makedirs(analysis_dir, exist_ok=True)
+ csv_path = os.path.join(analysis_dir, "image_analysis.csv")
save_csv(results, csv_path)
else:
print("No image files found in the directory.")
diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.md
index acadc31f..6d0cc7e3 100644
--- a/skills/ppt-master/scripts/docs/conversion.md
+++ b/skills/ppt-master/scripts/docs/conversion.md
@@ -133,6 +133,28 @@ pip install python-pptx
Legacy `.ppt` is not parsed directly. Resave it as `.pptx` or export it to PDF first.
+## `pptx_intake.py`
+
+Standard enrichment layer for PPTX sources. It complements `ppt_to_md.py` rather
+than replacing it: Markdown remains the normalized content source, while intake
+artifacts provide source facts for Strategist and standalone PPTX workflows.
+
+```bash
+python3 scripts/pptx_intake.py deck.pptx -o projects/demo/analysis
+```
+
+Outputs:
+- `identity.json` — canvas size/aspect, theme palette/fonts, observed colors/fonts
+- `slide_library.json` — text slots, geometry, native tables, native chart display caches
+- `source_profile.json` — compact Strategist-facing digest over identity, tables, charts, and page types
+
+`project_manager.py import-sources` runs this automatically for PPTX/PPTM/PPSX/PPSM/POTX/POTM inputs and stores the bundle directly under `analysis/`. The bundle is single-deck per project: importing a second PPTX keeps its Markdown source but skips intake rather than overwriting `analysis/source_profile.json`.
+
+Usage boundary:
+- Standard generation uses these fields as facts and recommendation candidates; it does not inherit source slide coordinates or page order by default.
+- Beautify promotes selected identity/content fields into locked constraints after confirmation.
+- Template-fill uses the slide library as the native PPTX fill contract.
+
## `source_to_md/web_to_md.py`
Convert web pages to Markdown and download images locally.
diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.md
index 6354d73c..46ad2aaa 100644
--- a/skills/ppt-master/scripts/docs/project.md
+++ b/skills/ppt-master/scripts/docs/project.md
@@ -22,6 +22,11 @@ Notes:
note), to avoid leaving unintended artifacts that could be committed by mistake.
Pass `--copy` to force a copy for in-repo sources instead.
- `--move` and `--copy` are mutually exclusive.
+- PPTX-family inputs are enriched automatically under `analysis/` with
+ `identity.json`, `slide_library.json`, and `source_profile.json`.
+ Intake is currently single-deck per project: later PPTX imports are archived
+ and converted to Markdown, but skip intake rather than overwriting the first
+ deck's analysis.
Common formats:
- `ppt169`
diff --git a/skills/ppt-master/scripts/pptx_intake.py b/skills/ppt-master/scripts/pptx_intake.py
new file mode 100644
index 00000000..33b39f4f
--- /dev/null
+++ b/skills/ppt-master/scripts/pptx_intake.py
@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""
+PPT Master - PPTX Intake Enrichment
+
+Extract reusable PPTX intake facts into a standard analysis bundle. This is a
+read-only companion to `ppt_to_md.py`: Markdown remains the content source,
+while this bundle provides canvas, visual identity, slide geometry, tables, and
+native chart data for downstream workflows.
+
+Usage:
+ python3 scripts/pptx_intake.py <source.pptx> -o <output_dir>
+
+Examples:
+ python3 scripts/pptx_intake.py deck.pptx -o projects/demo/analysis
+
+Dependencies:
+ None beyond the repository scripts used for PPTX parsing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+ sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from beautify_identity import extract_identity # noqa: E402
+from template_fill_pptx.analyzer import analyze_pptx # noqa: E402
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def _chart_summary(slide_library: dict[str, Any]) -> dict[str, Any]:
+ charts: list[dict[str, Any]] = []
+ total_series = 0
+ multi_plot_count = 0
+ for slide in slide_library.get("slides", []):
+ for chart in slide.get("charts", []):
+ series_count = int(chart.get("series_count") or 0)
+ plot_types = chart.get("plot_types") or []
+ if len(plot_types) > 1:
+ multi_plot_count += 1
+ total_series += series_count
+ charts.append(
+ {
+ "slide_index": slide.get("slide_index"),
+ "chart_id": chart.get("chart_id"),
+ "chart_type": chart.get("chart_type"),
+ "plot_types": plot_types,
+ "category_count": chart.get("category_count", 0),
+ "series_count": series_count,
+ "series_names": [
+ series.get("name")
+ for series in chart.get("series", [])
+ if series.get("name")
+ ],
+ }
+ )
+ return {
+ "chart_count": len(charts),
+ "series_count": total_series,
+ "multi_plot_chart_count": multi_plot_count,
+ "charts": charts,
+ }
+
+
+def _table_summary(slide_library: dict[str, Any]) -> dict[str, Any]:
+ tables: list[dict[str, Any]] = []
+ for slide in slide_library.get("slides", []):
+ for table in slide.get("tables", []):
+ tables.append(
+ {
+ "slide_index": slide.get("slide_index"),
+ "table_id": table.get("table_id"),
+ "row_count": table.get("row_count", 0),
+ "column_count": table.get("column_count", 0),
+ }
+ )
+ return {"table_count": len(tables), "tables": tables}
+
+
+def build_source_profile(
+ pptx_path: Path,
+ identity: dict[str, Any],
+ slide_library: dict[str, Any],
+) -> dict[str, Any]:
+ """Build the Strategist-facing digest over the raw intake artifacts."""
+ return {
+ "schema": "pptx_intake_profile.v1",
+ "source_pptx": str(pptx_path),
+ "slide_count": slide_library.get("slide_count", identity.get("slide_count", 0)),
+ "usage_contract": {
+ "standard_generation": (
+ "Use identity and slide-library fields as source facts and recommendation "
+ "candidates only; do not preserve original page count, order, or coordinates "
+ "unless the user selected a beautify/template-fill workflow."
+ ),
+ "beautify": (
+ "Promote source text, page order, page count, colors, and fonts into locked "
+ "constraints after user confirmation."
+ ),
+ "template_fill": (
+ "Use slide slots, tables, charts, and geometry as the native PPTX fill contract."
+ ),
+ },
+ "artifacts": {
+ "identity": "identity.json",
+ "slide_library": "slide_library.json",
+ },
+ "canvas": identity.get("canvas", {}),
+ "identity": {
+ "theme_palette": (identity.get("theme") or {}).get("palette", {}),
+ "theme_fonts": (identity.get("theme") or {}).get("fonts", {}),
+ "observed_colors": (identity.get("observed") or {}).get("colors", []),
+ "observed_fonts": (identity.get("observed") or {}).get("fonts", {}),
+ },
+ "structure": {
+ "canvas_px": slide_library.get("canvas_px", {}),
+ "page_types": [
+ {
+ "slide_index": slide.get("slide_index"),
+ "page_type": slide.get("page_type"),
+ "slot_count": len(slide.get("slots", [])),
+ }
+ for slide in slide_library.get("slides", [])
+ ],
+ },
+ "tables": _table_summary(slide_library),
+ "charts": _chart_summary(slide_library),
+ }
+
+
+def run_intake(pptx_path: Path, output_dir: Path) -> dict[str, Path]:
+ """Write `identity.json`, `slide_library.json`, and `source_profile.json`."""
+ output_dir.mkdir(parents=True, exist_ok=True)
+ identity = extract_identity(pptx_path)
+ slide_library = analyze_pptx(pptx_path)
+ profile = build_source_profile(pptx_path, identity, slide_library)
+
+ identity_path = output_dir / "identity.json"
+ slide_library_path = output_dir / "slide_library.json"
+ profile_path = output_dir / "source_profile.json"
+ _write_json(identity_path, identity)
+ _write_json(slide_library_path, slide_library)
+ _write_json(profile_path, profile)
+ return {
+ "identity": identity_path,
+ "slide_library": slide_library_path,
+ "source_profile": profile_path,
+ }
+
+
+def build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(
+ description="Extract standard PPTX intake analysis artifacts.",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ )
+ parser.add_argument("source", help="Source PPTX / PPTM / PPSX / PPSM / POTX / POTM file")
+ parser.add_argument("-o", "--output-dir", required=True, help="Output project analysis directory")
+ return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = build_parser()
+ args = parser.parse_args(argv)
+ source = Path(args.source).expanduser().resolve()
+ if not source.is_file():
+ print(f"Error: source not found: {source}", file=sys.stderr)
+ return 1
+ try:
+ outputs = run_intake(source, Path(args.output_dir).expanduser().resolve())
+ except (RuntimeError, KeyError, ValueError) as exc:
+ print(f"Error: PPTX intake failed: {exc}", file=sys.stderr)
+ return 1
+ print(f"PPTX intake -> {Path(args.output_dir).expanduser().resolve()}", file=sys.stderr)
+ for name, path in outputs.items():
+ print(f" {name}: {path}", file=sys.stderr)
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.py
index 4fb1abda..f1c3ac49 100644
--- a/skills/ppt-master/scripts/project_manager.py
+++ b/skills/ppt-master/scripts/project_manager.py
@@ -147,6 +147,7 @@ class ProjectManager:
"notes",
"templates",
SOURCE_DIRNAME,
+ "analysis",
"exports",
):
(project_path / rel_path).mkdir(parents=True, exist_ok=True)
@@ -166,6 +167,7 @@ class ProjectManager:
"- `notes/`: speaker notes\n"
"- `templates/`: project templates\n"
"- `sources/`: source materials and normalized markdown\n"
+ "- `analysis/`: machine-extracted intermediate analysis (PPTX intake, image_analysis.csv) — the pipeline's canonical must-read source/asset facts\n"
"- `exports/`: main native pptx (timestamped); `_svg.pptx` sibling added when exported with `--svg-snapshot`\n"
"- `backup/<timestamp>/`: svg_output/ archive (always written in default-flow mode; safe to delete old timestamps)\n"
),
@@ -181,6 +183,11 @@ class ProjectManager:
sources_dir.mkdir(parents=True, exist_ok=True)
return sources_dir
+ def _analysis_dir(self, project_path: Path) -> Path:
+ analysis_dir = project_path / "analysis"
+ analysis_dir.mkdir(parents=True, exist_ok=True)
+ return analysis_dir
+
def _ensure_unique_path(self, path: Path) -> Path:
if not path.exists():
return path
@@ -275,6 +282,22 @@ class ProjectManager:
]
)
+ def _import_pptx_intake(self, presentation_path: Path, project_dir: Path) -> Path | None:
+ analysis_dir = self._analysis_dir(project_dir)
+ profile_path = analysis_dir / "source_profile.json"
+ if profile_path.exists():
+ return None
+ self._run_tool(
+ [
+ sys.executable,
+ str(TOOLS_DIR / "pptx_intake.py"),
+ str(presentation_path),
+ "-o",
+ str(analysis_dir),
+ ]
+ )
+ return analysis_dir
+
def _import_excel(self, excel_path: Path, markdown_path: Path) -> None:
self._run_tool(
[
@@ -534,6 +557,7 @@ class ProjectManager:
"archived": [],
"markdown": [],
"assets": [],
+ "analysis": [],
"notes": [],
"skipped": [],
}
@@ -640,6 +664,17 @@ class ProjectManager:
summary["skipped"].append(f"{item}: PDF conversion failed ({exc})")
elif suffix in PRESENTATION_SUFFIXES:
canonical_markdown_path = sources_dir / f"{archived_path.stem}.md"
+ try:
+ intake_dir = self._import_pptx_intake(archived_path, project_dir)
+ if intake_dir is None:
+ summary["notes"].append(
+ f"{item}: skipped PPTX intake because analysis/source_profile.json already exists; "
+ "current intake is single-deck and keeps the first PPTX analysis"
+ )
+ else:
+ summary["analysis"].append(str(intake_dir))
+ except Exception as exc: # pragma: no cover - summary path
+ summary["notes"].append(f"{item}: PPTX intake analysis failed ({exc})")
if archived_path.stem in explicit_markdown_stems:
summary["notes"].append(
f"{item}: skipped presentation auto-conversion because a same-stem Markdown source was provided"
@@ -825,6 +860,10 @@ def main(argv: list[str] | None = None) -> int:
print("\nImported asset directories:")
for item in summary["assets"]:
print(f" - {item}")
+ if summary["analysis"]:
+ print("\nAnalysis artifacts:")
+ for item in summary["analysis"]:
+ print(f" - {item}")
if summary["notes"]:
print("\nNotes:")
for item in summary["notes"]:
diff --git a/skills/ppt-master/scripts/template_fill_pptx/chart_fill.py b/skills/ppt-master/scripts/template_fill_pptx/chart_fill.py
index 34467445..9748391d 100644
--- a/skills/ppt-master/scripts/template_fill_pptx/chart_fill.py
+++ b/skills/ppt-master/scripts/template_fill_pptx/chart_fill.py
@@ -77,9 +77,17 @@ def _chart_type_with_series(chart_root: ET.Element) -> ET.Element:
plot_area = chart_root.find(".//c:plotArea", NS)
if plot_area is None:
raise RuntimeError("Chart XML has no plotArea")
+ chart_types: list[ET.Element] = []
for child in list(plot_area):
if child.tag.endswith("Chart") and child.findall("c:ser", NS):
- return child
+ chart_types.append(child)
+ if len(chart_types) > 1:
+ raise RuntimeError(
+ "template-fill chart edits do not support multi-plot / combination charts; "
+ "use beautify/main pipeline to redraw the chart, or leave the native chart untouched"
+ )
+ if chart_types:
+ return chart_types[0]
raise RuntimeError("Chart XML has no editable series")
diff --git a/skills/ppt-master/scripts/template_fill_pptx/chart_read.py b/skills/ppt-master/scripts/template_fill_pptx/chart_read.py
index ab930f20..e3d9e65c 100644
--- a/skills/ppt-master/scripts/template_fill_pptx/chart_read.py
+++ b/skills/ppt-master/scripts/template_fill_pptx/chart_read.py
@@ -27,14 +27,15 @@ def _local_name(tag: str) -> str:
return tag.rsplit("}", 1)[-1]
-def _chart_type_with_series(chart_root: ET.Element) -> ET.Element | None:
+def _chart_types_with_series(chart_root: ET.Element) -> list[ET.Element]:
plot_area = chart_root.find(".//c:plotArea", NS)
if plot_area is None:
- return None
+ return []
+ chart_types: list[ET.Element] = []
for child in list(plot_area):
if _local_name(child.tag).endswith("Chart") and child.findall("c:ser", NS):
- return child
- return None
+ chart_types.append(child)
+ return chart_types
def _coerce_number(value: str) -> int | float | str:
@@ -75,23 +76,33 @@ def _series_name(series: ET.Element, fallback: str) -> str:
def read_chart_data(chart_root: ET.Element) -> dict[str, Any]:
"""Return a compact summary of chart type, categories, series, and values."""
- chart_type = _chart_type_with_series(chart_root)
- if chart_type is None:
+ chart_types = _chart_types_with_series(chart_root)
+ if not chart_types:
return empty_chart_data()
- series_nodes = chart_type.findall("c:ser", NS)
- categories = _cache_values(series_nodes[0].find("c:cat", NS)) if series_nodes else []
+ first_series = chart_types[0].find("c:ser", NS)
+ categories = _cache_values(first_series.find("c:cat", NS)) if first_series is not None else []
series_payload: list[dict[str, Any]] = []
- for index, series in enumerate(series_nodes, start=1):
- series_payload.append(
- {
- "name": _series_name(series, f"系列{index}"),
- "values": _cache_values(series.find("c:val", NS), numeric=True),
- }
- )
+ plot_types: list[str] = []
+ for chart_type in chart_types:
+ plot_name = _local_name(chart_type.tag)
+ plot_types.append(plot_name)
+ for series in chart_type.findall("c:ser", NS):
+ index = len(series_payload) + 1
+ series_categories = _cache_values(series.find("c:cat", NS))
+ if not categories and series_categories:
+ categories = series_categories
+ series_payload.append(
+ {
+ "name": _series_name(series, f"系列{index}"),
+ "values": _cache_values(series.find("c:val", NS), numeric=True),
+ "chart_type": plot_name,
+ }
+ )
return {
- "chart_type": _local_name(chart_type.tag),
+ "chart_type": plot_types[0] if len(set(plot_types)) == 1 else "comboChart",
+ "plot_types": plot_types,
"category_count": len(categories),
"series_count": len(series_payload),
"categories": categories,
diff --git a/skills/ppt-master/scripts/template_fill_pptx/checker.py b/skills/ppt-master/scripts/template_fill_pptx/checker.py
index 5d452fe5..10b1fedf 100644
--- a/skills/ppt-master/scripts/template_fill_pptx/checker.py
+++ b/skills/ppt-master/scripts/template_fill_pptx/checker.py
@@ -387,6 +387,22 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
)
summary["error"] += 1
continue
+ if len(chart.get("plot_types") or []) > 1:
+ results.append(
+ {
+ "status": "ERROR",
+ "plan_slide": slide_index,
+ "source_slide": source_slide,
+ "selector": selectors[0] if selectors else "",
+ "chart_id": chart.get("chart_id"),
+ "message": (
+ "template-fill chart edits do not support multi-plot / combination charts; "
+ "use beautify/main pipeline to redraw the chart, or leave the native chart untouched"
+ ),
+ }
+ )
+ summary["error"] += 1
+ continue
categories = chart_edit.get("categories", [])
series = chart_edit.get("series", [])
if not isinstance(categories, list) or not isinstance(series, list) or not series:
diff --git a/skills/ppt-master/workflows/beautify-pptx.md b/skills/ppt-master/workflows/beautify-pptx.md
index 4e4ea132..95ebcb29 100644
--- a/skills/ppt-master/workflows/beautify-pptx.md
+++ b/skills/ppt-master/workflows/beautify-pptx.md
@@ -43,7 +43,7 @@ Re-lays-out an existing `.pptx`: the text is preserved **verbatim**, the source
## 3. Create the Project Workspace
-Match the canvas to the source so 1:1 pages and paste-back align. Determine the source aspect first — before the project exists, run `beautify_identity.py <source.pptx>` to **stdout** and read `canvas.aspect` (the formal `analysis/identity.json` is written in Step 4, after `init`) — then `init` with the matching format:
+Match the canvas to the source so 1:1 pages and paste-back align. Determine the source aspect first — before the project exists, run `beautify_identity.py <source.pptx>` to **stdout** and read `canvas.aspect` (the formal standard intake bundle is written in Step 4, after `init`) — then `init` with the matching format:
| Source aspect | Format |
|---|---|
@@ -60,16 +60,16 @@ python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <s
## 4. Extract Identity and Data; Assemble Inventory
-Two reads off the source PPTX (text + images already exist from Step 3). Neither rewrites the deck.
-
-**Content + images — already produced by Step 3.** `import-sources` ran `ppt_to_md` on the deck, so the **frozen content contract** is `sources/<stem>.md` (one source slide per block, in order). If the source deck contains pictures, they are already propagated to `images/` with per-slide binding in `images/image_manifest.json` (`occurrences[].slide_index`). Do **not** re-run `ppt_to_md` — it would duplicate the conversion and write images to `analysis/<stem>_files/` instead of `images/`.
-
-**Visual identity (theme + observed sample + canvas)**:
+Use the standard PPTX intake bundle from Step 3. `project_manager.py import-sources` already writes it under `analysis/` for PPTX-family inputs. If the bundle is missing because the project predates this workflow, generate it once:
```bash
-python3 ${SKILL_DIR}/scripts/beautify_identity.py <project_path>/sources/<source.pptx> -o <project_path>/analysis/identity.json
+python3 ${SKILL_DIR}/scripts/pptx_intake.py <project_path>/sources/<source.pptx> -o <project_path>/analysis
```
+**Content + images — already produced by Step 3.** `import-sources` ran `ppt_to_md` on the deck, so the **frozen content contract** is `sources/<stem>.md` (one source slide per block, in order). If the source deck contains pictures, they are already propagated to `images/` with per-slide binding in `images/image_manifest.json` (`occurrences[].slide_index`). Do **not** re-run `ppt_to_md` — it would duplicate the conversion and write images to `analysis/<stem>_files/` instead of `images/`.
+
+**Visual identity (theme + observed sample + canvas)**: read `<project_path>/analysis/identity.json`.
+
| Field | Use |
|---|---|
| `theme.palette.background` / `text` / `primary` / `accent1..6` | the deck's *declared* colors |
@@ -79,11 +79,7 @@ python3 ${SKILL_DIR}/scripts/beautify_identity.py <project_path>/sources/<source
> Note: `theme` is what the deck declares; `observed` is a frequency sample of run-level overrides (not a complete style resolution — it misses `schemeClr` and master/layout inheritance, and counts chart/gradient fills). A hand-edited deck can diverge from `theme` — Step 5 recommends which to inherit and the user confirms.
-**Chart + table data (for regeneration)**: read the source's chart and table *data* so they can be redrawn natively in the inherited style:
-
-```bash
-python3 ${SKILL_DIR}/scripts/template_fill_pptx.py analyze <project_path>/sources/<source.pptx> -o <project_path>/analysis/slide_library.json
-```
+**Chart + table data (for regeneration)**: read `<project_path>/analysis/slide_library.json`. It contains the source chart and table *data* so they can be redrawn natively in the inherited style:
| `slide_library.json` field | Use |
|---|---|
@@ -127,6 +123,7 @@ If `images/image_manifest.json` does not exist because the source deck has no ex
- [x] `sources/<stem>.md` (from Step 3) holds every source slide's text, in order; extracted pictures, if any, are in `images/` + `images/image_manifest.json`
- [x] `analysis/identity.json` has theme + observed identity + canvas aspect
- [x] `analysis/slide_library.json` holds chart + table data for regeneration
+- [x] `analysis/source_profile.json` summarizes the source facts
- [x] `analysis/beautify_inventory.json` ledgers per-slide text / images / data + ignored + needs-confirmation
- [ ] **Next**: Step 5 — Beautify Plan (recommend & confirm)
```
diff --git a/skills/ppt-master/workflows/template-fill-pptx.md b/skills/ppt-master/workflows/template-fill-pptx.md
index f425b5d5..b6c41eab 100644
--- a/skills/ppt-master/workflows/template-fill-pptx.md
+++ b/skills/ppt-master/workflows/template-fill-pptx.md
@@ -60,12 +60,12 @@ Use this fixed layout:
---
-## Step 3: Extract the Slide Library
+## Step 3: Extract the PPTX Intake Bundle
Run:
```bash
-python3 skills/ppt-master/scripts/template_fill_pptx.py analyze "<project_dir>/sources/<source.pptx>" -o "<project_dir>/analysis/slide_library.json"
+python3 skills/ppt-master/scripts/pptx_intake.py "<project_dir>/sources/<source.pptx>" -o "<project_dir>/analysis"
```
Read `<project_dir>/analysis/slide_library.json` and identify:
@@ -169,6 +169,7 @@ The plan structure:
| Empty slots | Use `scaffold --include-empty` only when a real placeholder is empty in the source deck |
| Native tables | Keep the original table row and column count; this workflow edits existing cells, not table structure |
| Native charts | Each series `values` list must match the category count; this workflow edits chart data, not chart styling |
+| Multi-plot / combo charts | Not supported for direct `chart_edits`; `check-plan` reports an error rather than silently writing the wrong plot. Use beautify / main pipeline to redraw them, or leave the native chart untouched. |
| Facts | Every substantive claim must come from the user material |
**Fit check before apply**:
@@ -278,7 +279,7 @@ If the extracted text is correct but visual overflow is likely, reduce the text
```markdown
## ✅ Template Fill Complete
-- [x] `slide_library.json` extracted from the source PPTX
+- [x] Standard PPTX intake extracted from the source deck, including `slide_library.json`
- [x] `fill_plan.json` selects only pages that fit the target story
- [x] `check-plan` run and capacity warnings resolved or explicitly accepted
- [x] Output PPTX generated through direct OOXML text replacement