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(quick-generate): initialize minimal project workspaces

hugohe3a87c41c4d6de
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 75f1ccf5..53c33607 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -300,7 +300,15 @@ Two converter design choices still shape the system:
## Project Structure & Lifecycle
-`project_manager.py init` creates the fixed project working directories; a later default-path export creates a timestamped backup directory and then attempts to copy a `backup/` snapshot. The explicit [`quick-generate`](../skills/ppt-master/workflows/profiles/quick-generate.md) profile omits planning artifacts and `svg_final/`, but its project may still contain converted sources, analysis, images, icons, rendered formulas, and required resource manifests. It hand-authors `svg_output/`, writes a lockless final quality report, and retains the ordinary postflight and default-path backup around the final PPTX. The default delivery lifecycle is:
+`project_manager.py init` creates the standard project working directories;
+`--quick-generate` creates only `svg_output/`, omits the project README, and
+leaves other directories on demand. The explicit
+[`quick-generate`](../skills/ppt-master/workflows/profiles/quick-generate.md)
+profile omits planning artifacts and `svg_final/`, but its project may still
+contain converted sources, analysis, images, icons, rendered formulas, and
+required resource manifests. It hand-authors `svg_output/`, writes a lockless
+final quality report, and retains the ordinary postflight and default-path
+backup around the final PPTX. The default delivery lifecycle is:
| Directory | Role |
|---|---|
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 571d4d66..ffbe977f 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -286,7 +286,13 @@ SVG 也是唯一同时满足流程中所有角色需要的格式:**AI 能可
## 项目结构与生命周期
-`project_manager.py init` 创建固定的项目工作目录;使用默认输出路径的导出会创建带时间戳的备份目录,再尝试复制 `backup/` 快照。显式 [`quick-generate`](../../skills/ppt-master/workflows/profiles/quick-generate.md) profile 省略规划产物与 `svg_final/`,但项目中仍可按需存在已转换来源、分析结果、图片、图标、渲染公式及必要资源 manifest;它会手写 `svg_output/`,生成无锁最终质量报告,并围绕最终 PPTX 保留普通 postflight 与默认路径备份。默认交付生命周期如下:
+`project_manager.py init` 默认创建标准项目工作目录;使用
+`--quick-generate` 时只创建 `svg_output/`,省略项目 README,其他目录按需产生。
+显式
+[`quick-generate`](../../skills/ppt-master/workflows/profiles/quick-generate.md)
+profile 省略规划产物与 `svg_final/`,但项目中仍可按需存在已转换来源、分析结果、
+图片、图标、渲染公式及必要资源 manifest;它会手写 `svg_output/`,生成无锁最终
+质量报告,并围绕最终 PPTX 保留普通 postflight 与默认路径备份。默认交付生命周期如下:
| 目录 | 职责 |
|---|---|
diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.md
index a3c3ab63..4bad07fd 100644
--- a/skills/ppt-master/scripts/docs/project.md
+++ b/skills/ppt-master/scripts/docs/project.md
@@ -22,6 +22,7 @@ python3 scripts/project_manager.py page-context-report <project_path>
```
Notes:
+- `init --quick-generate`: only `svg_output/`; no README
- Files outside `projects/` are always copied into `sources/`
- `--move` applies only to sources under the repository's `projects/` tree
- A directly supplied supported bitmap is also copied into `images/` with a
diff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.py
index f7b56b02..3e8b3dab 100644
--- a/skills/ppt-master/scripts/project_manager.py
+++ b/skills/ppt-master/scripts/project_manager.py
@@ -2,7 +2,7 @@
"""PPT Master project management helpers.
Usage:
- python3 scripts/project_manager.py init <project_name> [--format ppt169] [--dir <path>]
+ python3 scripts/project_manager.py init <project_name> [--format ppt169] [--dir <path>] [--quick-generate]
python3 scripts/project_manager.py import-sources <project_path> <source1> [<source2> ...] [--move | --copy]
python3 scripts/project_manager.py scaffold-spec <project_path>
python3 scripts/project_manager.py scaffold-lock <project_path>
@@ -223,6 +223,8 @@ class ProjectManager:
project_name: str,
canvas_format: str = "ppt169",
base_dir: str | None = None,
+ *,
+ quick_generate: bool = False,
) -> str:
base_path = Path(base_dir) if base_dir else self.base_dir
@@ -262,44 +264,50 @@ class ProjectManager:
if project_path.exists():
raise FileExistsError(f"Project directory already exists: {project_path}")
- for rel_path in (
- "svg_output",
- "svg_final",
- "images",
- "icons",
- "notes",
- "templates",
- "live_preview",
- SOURCE_DIRNAME,
- "analysis",
- "validation",
- "exports",
- ):
+ project_dirs = (
+ ("svg_output",)
+ if quick_generate
+ else (
+ "svg_output",
+ "svg_final",
+ "images",
+ "icons",
+ "notes",
+ "templates",
+ "live_preview",
+ SOURCE_DIRNAME,
+ "analysis",
+ "validation",
+ "exports",
+ )
+ )
+ for rel_path in project_dirs:
(project_path / rel_path).mkdir(parents=True, exist_ok=True)
canvas_info = self.CANVAS_FORMATS[normalized_format]
- readme_path = project_path / "README.md"
- readme_path.write_text(
- (
- f"# {project_name}\n\n"
- f"- Canvas format: {normalized_format}\n"
- f"- Created: {date_str}\n\n"
- "## Directories\n\n"
- "- `svg_output/`: raw SVG output\n"
- "- `svg_final/`: self-contained SVG visual preview; may be inserted manually as an SVG image, but PowerPoint Convert to Shape is unsupported\n"
- "- `images/`: runtime image pool; converter assets keep their original short filenames when possible\n"
- "- `icons/`: project icon set — selected library icons copied in (via icon_sync.py) plus any custom icons you add; embedded from here at export\n"
- "- `notes/`: speaker notes\n"
- "- `templates/`: project templates\n"
- "- `live_preview/`: browser preview runtime files and history (lock.json, server.log, edits.jsonl, annotations.jsonl)\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"
- "- `validation/`: SVG quality reports and PPTX postflight audit reports\n"
- "- `exports/`: final native DrawingML pptx deliverables only (timestamped); `_native_charts_tables.pptx` name with `--native-charts-and-tables`, `_narrated.pptx` name when narration audio is embedded\n"
- "- `backup/<timestamp>/`: svg_output/ archive (always written in default-flow mode; safe to delete old timestamps)\n"
- ),
- encoding="utf-8",
- )
+ if not quick_generate:
+ readme_path = project_path / "README.md"
+ readme_path.write_text(
+ (
+ f"# {project_name}\n\n"
+ f"- Canvas format: {normalized_format}\n"
+ f"- Created: {date_str}\n\n"
+ "## Directories\n\n"
+ "- `svg_output/`: raw SVG output\n"
+ "- `svg_final/`: self-contained SVG visual preview; may be inserted manually as an SVG image, but PowerPoint Convert to Shape is unsupported\n"
+ "- `images/`: runtime image pool; converter assets keep their original short filenames when possible\n"
+ "- `icons/`: project icon set — selected library icons copied in (via icon_sync.py) plus any custom icons you add; embedded from here at export\n"
+ "- `notes/`: speaker notes\n"
+ "- `templates/`: project templates\n"
+ "- `live_preview/`: browser preview runtime files and history (lock.json, server.log, edits.jsonl, annotations.jsonl)\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"
+ "- `validation/`: SVG quality reports and PPTX postflight audit reports\n"
+ "- `exports/`: final native DrawingML pptx deliverables only (timestamped); `_native_charts_tables.pptx` name with `--native-charts-and-tables`, `_narrated.pptx` name when narration audio is embedded\n"
+ "- `backup/<timestamp>/`: svg_output/ archive (always written in default-flow mode; safe to delete old timestamps)\n"
+ ),
+ encoding="utf-8",
+ )
print(f"Project created: {project_path}")
print(f"Canvas: {canvas_info['name']} ({canvas_info['dimensions']})")
@@ -1057,6 +1065,11 @@ def build_parser() -> argparse.ArgumentParser:
init.add_argument("project_name", help="Project name")
init.add_argument("--format", default="ppt169", help="Canvas format (default: ppt169)")
init.add_argument("--dir", default=None, help="Base directory for the project")
+ init.add_argument(
+ "--quick-generate",
+ action="store_true",
+ help="Create only the svg_output directory and omit README.md",
+ )
import_sources = subparsers.add_parser(
"import-sources",
@@ -1132,12 +1145,17 @@ def main(argv: list[str] | None = None) -> int:
args.project_name,
args.format,
base_dir=args.dir,
+ quick_generate=args.quick_generate,
)
print(f"[OK] Project initialized: {project_path}")
print("Next:")
- print("1. Put source files into sources/ (or use import-sources)")
- print("2. Save your design spec to the project root")
- print("3. Generate SVG files into svg_output/")
+ if args.quick_generate:
+ print("1. Generate SVG files into svg_output/")
+ print("2. Run the Quick Generate final checker and exporter")
+ else:
+ print("1. Put source files into sources/ (or use import-sources)")
+ print("2. Save your design spec to the project root")
+ print("3. Generate SVG files into svg_output/")
return 0
if args.command == "import-sources":
diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.md
index e2d3efd4..131905c7 100644
--- a/skills/ppt-master/workflows/profiles/quick-generate.md
+++ b/skills/ppt-master/workflows/profiles/quick-generate.md
@@ -24,13 +24,10 @@ Page count alone never activates or blocks this profile.
| Planning artifacts | Do not create `design_spec.md`, `spec_lock.md`, confirmation payloads, or a second persisted strategy |
| Delivery | Hand-author the resolved SVG roster, run one lockless final checker, skip `finalize_svg.py`, and export the final native PPTX through `--quick-generate` |
-**Hard rule — speed removes interaction, not material**: source conversion,
-topic research, supplied/extracted assets, AI or web images, illustration
-slices, project icons, formula rendering, and regenerated image facts remain
-available whenever the deck needs them. The workspace may therefore contain
-`sources/`, `analysis/`, `images/`, `icons/`, and their operational manifests.
-The missing planning contract relaxes design constraints; it does not remove
-resource preparation or exporter capabilities.
+**Hard rule — speed removes interaction, not material**: all ordinary source,
+research, resource-preparation, analysis, and export capabilities remain
+available when needed; the missing planning contract relaxes design constraints
+only.
Explicit user facts, wording, choices, exclusions, and permission boundaries
still win. For every unspecified routine choice, decide directly and continue;
@@ -49,11 +46,20 @@ never creates or reads a Design Spec or lock to enable it.
## 2. Source and Resource Preparation
-Run [`generate-pptx.md`](../generate-pptx.md) Step 1 source conversion and
-bounded research when applicable. Initialize/import the project through Step 2
-when those tools or project-local resources are needed, but never scaffold a
-Design Spec or lock. Use a new project path, or first verify that its
-`svg_output/` is empty; Quick does not read any existing `design_spec.md` or
+Run [`generate-pptx.md`](../generate-pptx.md) Step 1 when applicable. Initialize
+the minimal workspace with:
+
+```bash
+python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> \
+ --format <format> --quick-generate
+```
+
+It creates only `svg_output/` and no root README. Add capability inputs only
+when triggered; checker/exporter create `validation/`, `exports/`, and the
+default-path `backup/`. With source files, continue with Step 2
+`import-sources`; it creates the triggered input directories. Never scaffold a
+Design Spec or lock. Use a new path, or verify that an existing path's
+`svg_output/` is empty; Quick ignores any existing `design_spec.md` or
`spec_lock.md`.
Before writing P01, resolve in active context: