AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
docs(canvas): stop encoding a canvas guess in project names
hugohe38dbf9ea2a1b0
diff --git a/AGENTS.md b/AGENTS.mdindex b55c03d3..44cca50c 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -60,7 +60,8 @@ Convenience summary only — route selection starts in [`SKILL.md`](skills/ppt-mpython3 skills/ppt-master/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or_URL_or_dir> ...]# Project management-python3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169+# Add --format <registered_format> only for an exact registered canvas.+python3 skills/ppt-master/scripts/project_manager.py init <project_name>python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs_or_URLs...>python3 skills/ppt-master/scripts/project_manager.py scaffold-spec <project_path> # optional manual helperpython3 skills/ppt-master/scripts/project_manager.py scaffold-lock <project_path> # optional manual helperdiff --git a/docs/faq.md b/docs/faq.mdindex 0456123c..96d1e985 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -42,7 +42,11 @@ Yes. Besides the standard **16:9** and **4:3** presentation formats, PPT Master| WeChat Article Header | WeChat article cover images || A4 Print | Print posters, flyers |-Just specify the format when starting a project (e.g., `--format xhs`). The output is still a `.pptx` file containing native shapes.+When the canvas exactly matches a registered format, pass that key during+initialization (for example, `--format xhs`). For any other canvas, omit+`--format`; Default Generate records the confirmed viewBox in `spec_lock.md`,+and Quick Generate uses the first SVG as the canvas authority. The output is+still a `.pptx` file containing native shapes.## Q: What AI tools work with PPT Master?diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 6254e05c..b956e2cb 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -75,7 +75,7 @@ User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)[Source Processing & Factual Sufficiency] → source_to_md.py dispatches by type; topic-only or planning-critical factual gaps enter topic-research└── Raw or converted content is ready; research writes supplemental Markdown and fact provenance for project import↓-[Create Project] → project_manager.py init <project_name> --format <format>+[Create Project] → project_manager.py init <project_name> [--format <registered_format>]↓[Archive Sources & Project Analysis (when source files exist; conversation text skips)] → project_manager.py import-sources <project_path> <sources...>├── First move/copy supplied files into sources/ under the ownership boundary@@ -339,6 +339,10 @@ Two converter design choices still shape the system:## Project Structure & Lifecycle`project_manager.py init` creates the standard project working directories;+`--format` is optional and is passed only when the actual canvas exactly+matches a registered format. Without it, the directory is named+`<name>_<YYYYMMDD>`; Default Generate records the confirmed viewBox in+`spec_lock.md`, while Quick Generate takes it from the first SVG.`--quick-generate` creates `svg_output/` plus the cold`validation/workflow.log` audit log, omits the project README, and leavesother directories on demand. The explicitdiff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex 40b2bbea..40b2a0e2 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -42,7 +42,10 @@ DOCX 转换会把内嵌图片素材抽取到配套素材目录,并写入图片| 微信文章头图 | 公众号文章封面 || A4 印刷 | 印刷海报、传单 |-创建项目时指定格式即可(如 `--format xhs`)。输出仍然是包含原生形状的 `.pptx` 文件。+实际画布与已注册格式完全一致时,初始化可传对应键(如 `--format xhs`)。+其他画布应省略 `--format`;Default Generate 会把确认后的 viewBox 记录到+`spec_lock.md`,Quick Generate 则以第一张 SVG 为画布真值。输出仍然是包含原生形状的+`.pptx` 文件。## Q: PPT Master 支持哪些 AI 工具?diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex c4b4bb88..7c75f230 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -48,7 +48,7 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使[源内容处理与事实充分性检查] → source_to_md.py 按类型分派转换器;topic-only 或关键事实缺口进入 topic-research└── 原始或转换后内容就绪;研究分支形成补充 Markdown 与 facts provenance,随后作为来源导入项目↓-[创建项目] → project_manager.py init <项目名> --format <格式>+[创建项目] → project_manager.py init <项目名> [--format <已注册格式>]↓[归档来源与项目级分析(有来源文件时;纯对话文本跳过)] → project_manager.py import-sources <项目路径> <来源...>├── 先按所有权边界把传入文件 move/copy 到 sources/@@ -297,7 +297,10 @@ SVG 也是唯一同时满足流程中所有角色需要的格式:**AI 能可## 项目结构与生命周期-`project_manager.py init` 默认创建标准项目工作目录;使用+`project_manager.py init` 默认创建标准项目工作目录。`--format` 为可选参数,+只有实际画布与已注册格式完全一致时才传入;省略时目录名为+`<名称>_<YYYYMMDD>`,Default Generate 将确认后的 viewBox 记录到+`spec_lock.md`,Quick Generate 则以第一张 SVG 为准。使用`--quick-generate` 时创建 `svg_output/` 与冷审计日志`validation/workflow.log`,省略项目 README,其他目录按需产生。显式diff --git a/projects/README.md b/projects/README.mdindex 056a676f..caf70926 100644--- a/projects/README.md+++ b/projects/README.md@@ -5,15 +5,22 @@ This directory is used for storing in-progress projects.## Create a New Project```bash-python3 skills/ppt-master/scripts/project_manager.py init my_project --format ppt169+# Defer the canvas to authoring:+python3 skills/ppt-master/scripts/project_manager.py init my_project+# Or record an exact registered canvas:+python3 skills/ppt-master/scripts/project_manager.py init my_widescreen --format ppt169```+Pass `--format` only when the canvas exactly matches a registered format. If it+is omitted, the canvas is determined during authoring and recorded in+`spec_lock.md` for Default Generate or by the first SVG for Quick Generate.+## Directory StructureA typical project usually contains the following:```-project_name_format_YYYYMMDD/+project_name[_registered_format]_YYYYMMDD/├── README.md├── design_spec.md├── sources/@@ -36,6 +43,8 @@ project_name_format_YYYYMMDD/└── *.pptx # Native DrawingML deliverables```+The optional format token appears only when `init` receives `--format`.+Projects can remain at different stages and do not necessarily have all artifacts at once. For example:- Only `sources/` archiving and the Design Specification & Content Outline (design_spec) are completediff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex baea843d..f2e00bae 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -27,7 +27,7 @@ python3 scripts/source_to_md/pdf_to_md.py <file.pdf># orpython3 scripts/source_to_md/ppt_to_md.py <deck.pptx>python3 scripts/source_to_md/excel_to_md.py <workbook.xlsx>-python3 scripts/project_manager.py init <project_name> --format ppt169+python3 scripts/project_manager.py init <project_name>python3 scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...>python3 scripts/total_md_split.py <project_path>python3 scripts/finalize_svg.py <project_path>@@ -79,7 +79,7 @@ python3 scripts/pptx_to_svg.py <deck.pptx> -o <output_dir> # reconstruction/refProject setup:```bash-python3 scripts/project_manager.py init <project_name> --format ppt169+python3 scripts/project_manager.py init <project_name> [--format <registered_format>]python3 scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...>python3 scripts/project_manager.py scaffold-spec <project_path> # optional manual helperpython3 scripts/project_manager.py scaffold-lock <project_path> # optional manual helper@@ -88,6 +88,11 @@ python3 scripts/project_manager.py page-context <project_path> P07 --record-usagpython3 scripts/project_manager.py page-context-report <project_path>```+`--format` is optional and accepts registered canvas keys only. Pass it when+the actual canvas exactly matches one of those keys; otherwise omit it. Without+the flag, `init` creates `<name>_<YYYYMMDD>`, and authoring records the canvas+in `spec_lock.md` for Default Generate or the first SVG for Quick Generate.+`page-context` is an on-demand read-only current-page projection for diagnostics,routing checks, or context measurement; normal generation retains the completeDesign Spec and lock once per valid execution context. Each invocation includes@@ -172,7 +177,7 @@ The destination must be empty, and the command does not writeTemplate fill (direct PPTX, no SVG conversion):```bash-python3 scripts/project_manager.py init <project_name> --format ppt169+python3 scripts/project_manager.py init <project_name>python3 scripts/project_manager.py import-sources <project_path> <source.pptx> <material...># Manual fallback when import-sources did not produce analysis/<stem>.slide_library.json:python3 scripts/template_fill_pptx.py analyze <project_path>/sources/<source.pptx> -o <project_path>/analysis/<stem>.slide_library.jsondiff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.mdindex ddd91105..e61c7532 100644--- a/skills/ppt-master/scripts/docs/project.md+++ b/skills/ppt-master/scripts/docs/project.md@@ -11,7 +11,7 @@ Project tools create, validate, and inspect the standard PPT Master workspace.Main entry point for project setup and validation.```bash-python3 scripts/project_manager.py init <project_name> --format ppt169+python3 scripts/project_manager.py init <project_name> [--format <registered_format>]python3 scripts/project_manager.py import-sources <project_path> <source1_or_dir> [<source2_or_dir> ...]python3 scripts/project_manager.py scaffold-spec <project_path> # optional manual helperpython3 scripts/project_manager.py scaffold-lock <project_path> # optional manual helper@@ -22,6 +22,13 @@ python3 scripts/project_manager.py page-context-report <project_path>```Notes:+- `--format` is optional and accepts registered canvas keys only. Pass it only+ when the actual canvas exactly matches a registered format.+- Without `--format`, `init` creates `<name>_<YYYYMMDD>`; authoring records the+ canvas in `spec_lock.md` for Default Generate or the first SVG for Quick+ Generate.+- With `--format`, `init` preserves the registered form+ `<name>_<format>_<YYYYMMDD>` and normalizes aliases such as `xhs`.- `init --quick-generate`: `svg_output/` plus`validation/workflow.log`; no README- Files outside `projects/` are always copied into `sources/`@@ -45,7 +52,8 @@ Notes:- Optional `scaffold-spec` creates `design_spec.md` from`templates/scaffolds/design_spec.md`; `scaffold-lock` creates `spec_lock.md`from `templates/scaffolds/spec_lock.md`. Both substitute project/canvas- metadata deterministically and refuse to overwrite an existing artifact.+ metadata deterministically, require a registered format in the project+ directory name, and refuse to overwrite an existing artifact.- `validate` parses the existing Markdown artifacts against`templates/schemas/design_spec.schema.json` and`templates/schemas/spec_lock.schema.json`. It reports missing sections and@@ -138,13 +146,14 @@ Common formats:Examples:```bash-python3 scripts/project_manager.py init my_presentation --format ppt169-python3 scripts/project_manager.py scaffold-spec projects/my_presentation_ppt169_20251116 # optional-python3 scripts/project_manager.py scaffold-lock projects/my_presentation_ppt169_20251116 # optional-python3 scripts/project_manager.py validate projects/my_presentation_ppt169_20251116-python3 scripts/project_manager.py info projects/my_presentation_ppt169_20251116-python3 scripts/project_manager.py page-context projects/my_presentation_ppt169_20251116 P07 --record-usage-python3 scripts/project_manager.py page-context-report projects/my_presentation_ppt169_20251116+python3 scripts/project_manager.py init my_presentation+python3 scripts/project_manager.py validate projects/my_presentation_20251116+python3 scripts/project_manager.py info projects/my_presentation_20251116+python3 scripts/project_manager.py init my_widescreen --format ppt169+python3 scripts/project_manager.py scaffold-spec projects/my_widescreen_ppt169_20251116 # optional+python3 scripts/project_manager.py scaffold-lock projects/my_widescreen_ppt169_20251116 # optional+python3 scripts/project_manager.py page-context projects/my_widescreen_ppt169_20251116 P07 --record-usage+python3 scripts/project_manager.py page-context-report projects/my_widescreen_ppt169_20251116```## `workflow_transcript.py` and `workflow_log.py`diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex e4810600..701b5bc0 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -119,9 +119,14 @@ final confirmation.🚧 **GATE**: Step 1 complete; source content is ready (Markdown file, user-provided text, or requirements described in conversation are all valid).```bash-python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> --format <format>+python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name>```+**Hard rule — truthful canvas token**: append+`--format <registered_format>` only when an explicit user/source fact already+establishes an exact registered canvas before initialization. Otherwise omit+the flag; Stage 1 confirms the canvas and `spec_lock.md` records its viewBox.+Project initialization creates `<project_path>/validation/workflow.log` andrecords the initialization milestone. After the project exists, run eachproject-scoped Python tool normally. The shared CLI bootstrap automaticallydiff --git a/skills/ppt-master/workflows/profiles/beautify-pptx.md b/skills/ppt-master/workflows/profiles/beautify-pptx.mdindex 6d272eec..81cb6029 100644--- a/skills/ppt-master/workflows/profiles/beautify-pptx.md+++ b/skills/ppt-master/workflows/profiles/beautify-pptx.md@@ -60,20 +60,20 @@ two fidelity profiles never compose.## 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 standard intake bundle 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 select the source-faithful canvas, passing `--format` only for an exact registered match:-| Source aspect | Format |+| Source aspect | Canvas ||---|---|| ≈1.778 (16:9) | `ppt169` || ≈1.333 (4:3) | `ppt43` |-| other | nearest format in [`canvas-formats.md`](../../references/canvas-formats.md); record the source pixel size in the spec |+| other | the exact source `width_px`x`height_px`; omit `--format` |```bash# Default runtime:-python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> --format <format>+python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> [--format <format>]# Quick runtime instead:-python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> --format <format> --quick-generate+python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> [--format <format>] --quick-generate# Both runtimes then import once:python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source.pptx>diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.mdindex 8a1548ca..59af26b0 100644--- a/skills/ppt-master/workflows/profiles/quick-generate.md+++ b/skills/ppt-master/workflows/profiles/quick-generate.md@@ -152,20 +152,26 @@ ordinary Quick and other compatible profiles.its kind/canvas, and run that stage's read-only schema/structured preflight.Do not scan the library, fuzzy-match a name, or open a selector. Explicit usercanvas wins; otherwise use the selected structure owner (Layout before Deck)- canvas when present, then fall back to `ppt169`.+ canvas when present. Pass that choice to `init --format` only when it exactly+ matches a registered canvas; otherwise retain its viewBox for authoring.- **Free design**: no exact root was supplied. Continue immediately with the- requested canvas or `ppt169`. A bare template name, brand mention, style- phrase, or vague request to choose a template is ordinary brief input, not a- workspace reference.+ requested canvas when one exists. If no canvas is specified, decide the+ viewBox during SVG authoring instead of assigning an initialization default.+ A bare template name, brand mention, style phrase, or vague request to choose+ a template is ordinary brief input, not a workspace reference.Neither branch creates anything under `confirm_ui/` or executes`confirm_ui/server.py`. Initialize the minimal workspace with:```bash-python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> \- --format <format> --quick-generate+python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> --quick-generate```+**Hard rule — truthful canvas token**: append+`--format <registered_format>` only when the branch above resolved an exact+registered canvas. Otherwise omit it; the first SVG root viewBox becomes the+canvas authority. Never encode custom dimensions as a format token.+It creates `svg_output/` plus the cold`validation/workflow.log` command/outcome audit log, and no root README. Afterthis command, run project-scoped Python tools directly; their shared CLIdiff --git a/skills/ppt-master/workflows/template-fill-pptx.md b/skills/ppt-master/workflows/template-fill-pptx.mdindex 7488e72e..b3202ad1 100644--- a/skills/ppt-master/workflows/template-fill-pptx.md+++ b/skills/ppt-master/workflows/template-fill-pptx.md@@ -56,10 +56,14 @@ If the content material is only a topic with no supporting facts, gather or askCreate a dedicated project directory under `projects/`. Do not write outputs directly into `projects/` root. Reuse the standard project manager so source import rules stay consistent with the rest of the repository:```bash-python3 skills/ppt-master/scripts/project_manager.py init "<project_name>" --format ppt169+python3 skills/ppt-master/scripts/project_manager.py init "<project_name>"python3 skills/ppt-master/scripts/project_manager.py import-sources "<project_dir>" "<source.pptx>" "<material...>"```+The source PPTX slide size remains the native canvas authority. Do not add an+initialization `--format` unless that source canvas has already been verified+as an exact registered format.+**Source import rule**: `project_manager.py import-sources` moves only sources under repository `projects/` and copies all others. `--copy` preserves a projects-local input; `--move` never widens that scope. Reuse this path.Use this fixed layout: