Skip to content

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

docs(canvas): stop encoding a canvas guess in project names

hugohe38dbf9ea2a1b0
diff --git a/AGENTS.md b/AGENTS.md
index b55c03d3..44cca50c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -60,7 +60,8 @@ Convenience summary only — route selection starts in [`SKILL.md`](skills/ppt-m
python3 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 helper
python3 skills/ppt-master/scripts/project_manager.py scaffold-lock <project_path> # optional manual helper
diff --git a/docs/faq.md b/docs/faq.md
index 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.md
index 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 leaves
other directories on demand. The explicit
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 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.md
index 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.md
index 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 Structure
A 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 complete
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 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>
# or
python3 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/ref
Project 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 helper
python3 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-usag
python3 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 complete
Design 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 write
Template 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.json
diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.md
index 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 helper
python3 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.md
index 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` and
records the initialization milestone. After the project exists, run each
project-scoped Python tool normally. The shared CLI bootstrap automatically
diff --git a/skills/ppt-master/workflows/profiles/beautify-pptx.md b/skills/ppt-master/workflows/profiles/beautify-pptx.md
index 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.md
index 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 user
canvas 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. After
this command, run project-scoped Python tools directly; their shared CLI
diff --git a/skills/ppt-master/workflows/template-fill-pptx.md b/skills/ppt-master/workflows/template-fill-pptx.md
index 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 ask
Create 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: