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
fix(exports): emit token-safe postflight receipts
hugohe38cc25e29ce5d
diff --git a/docs/technical-design.md b/docs/technical-design.mdindex c237c314..57d40c3f 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -485,6 +485,8 @@ The post-processing and export stages keep authoring, validation, preview, deliv| `exports/<name>_<ts>_narrated.pptx` (via `--recorded-narration audio`) | narrated deck for auto-play and PowerPoint video export | embedded per-slide audio plus auto-advance timings; name marks it apart from silent exports || `backup/<ts>/svg_output/` (always written in default-flow mode) | re-export from frozen SVG sources without re-running the LLM, archival | the only persisted copy of the Executor's raw SVG source after the project has been edited downstream |+Validation JSON files are cold audit artifacts, not routine model inputs. The exporter reads the SVG quality report programmatically, then prints a compact `[POSTFLIGHT]` receipt with the status, quality-gate result, Slide count, warning-category counts, and artifact paths. Successful agents consume that receipt instead of loading either complete JSON; only failure investigation or an explicit audit extracts targeted report fields.+### SVG preprocessors have TWO consumersThis is the key insight that's easy to miss when reading the code. Cleanup modules under `skills/ppt-master/scripts/svg_finalize/`, together with the local-reference expander, are used in two places for two different products.diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex fc446581..96bf80d1 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -481,6 +481,8 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集,因此主编译路| `exports/<name>_<ts>_narrated.pptx`(经 `--recorded-narration audio` 生成) | 自动放映与 PowerPoint 视频导出用的旁白版 deck | 逐页嵌入音频并写入自动推进时间;命名与无声导出区分开 || `backup/<ts>/svg_output/`(默认流程下始终生成) | 不重跑 LLM 的前提下从冻结 SVG 源重建 pptx、长期存档 | 项目下游被改动后,Executor 原始 SVG 唯一的留存副本 |+校验 JSON 是冷审计产物,不是常规模型输入。导出器在程序内部读取 SVG 质量报告,再打印紧凑的 `[POSTFLIGHT]` 回执,包含状态、质量门结果、Slide 数量、warning 类别计数和产物路径。成功流程只消费该回执,不加载两份完整 JSON;只有失败排查或用户明确要求审计时才定向提取报告字段。+### SVG 预处理器有**两种**消费者这是读代码时容易忽略的关键事实。`skills/ppt-master/scripts/svg_finalize/` 下的清理模块和本地引用展开器,会在两个地方被使用,服务两份不同的产物。diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.mdindex 0d380cc4..b7a3f278 100644--- a/skills/ppt-master/references/artifact-ownership.md+++ b/skills/ppt-master/references/artifact-ownership.md@@ -39,8 +39,8 @@ Global artifact ownership rules for PPT Master projects.| `notes/total.md` | Speaker-note source | Complete notes before splitting | Step 6 writes; Step 7.1 splits || `notes/slide_*.md` | Split notes | Per-slide notes generated from `total.md` | Derived by `total_md_split.py` || `svg_final/` | Derived visual preview | Self-contained post-processed SVGs that may be opened directly or inserted as SVG pictures | Rebuild from `svg_output/` with `finalize_svg.py`; do not use as a supported PPTX source |-| `validation/svg_quality_report.json` | Quality provenance | Final SVG gate split into blocking / introduced / inherited / source-import categories, bound to the checked SVG bytes by SHA-256 | `svg_quality_checker.py --stage final --json` writes before export; postflight links it only when the export-source fingerprint matches. |-| `validation/<output_stem>.report.json` | Published-package audit | PPTX package/resource postflight status, part counts, and quality-gate linkage | Step 7.3 writes after the PPTX passes package validation. |+| `validation/svg_quality_report.json` | Quality provenance | Final SVG gate split into blocking / introduced / inherited / source-import categories, bound to the checked SVG bytes by SHA-256 | `svg_quality_checker.py --stage final --json` writes before export; the exporter reads it programmatically and links it only when the export-source fingerprint matches. Agents use successful command output and do not load the full JSON except for targeted failure/audit reads. |+| `validation/<output_stem>.report.json` | Published-package audit | PPTX package/resource postflight status, part counts, and quality-gate linkage | Step 7.3 writes after the PPTX passes package validation and emits a compact `[POSTFLIGHT]` receipt. Agents use the receipt on routine success and keep the full JSON cold unless targeted failure/audit evidence is required. || `exports/` | Delivery artifacts | Native DrawingML PPTX and explicit native-object/narration variants | Step 7.3 writes only final deliverables from `svg_output/`. || `backup/<timestamp>/svg_output/` | Frozen author-source archive | Re-export source without re-running LLM | `svg_to_pptx.py` writes a snapshot during export || `animations.json` | Optional animation config | Object-level animation sidecar | Created only by explicit animation workflow/request |diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex 5dea2eb4..1e08e32c 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -113,7 +113,7 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`- **Reference — create depth with restraint**: use rhythm, spacing, typography, accent bars, and subtle tints before shadows. Reserve lift for a few genuinely floating elements; keep peer grids, dividers, and body containers flat.- **Phased batch generation** (recommended):1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Use layout judgment for chart marks during the draft. **MUST embed plot-area markers** per [`executor-chart.md`](./executor-chart.md) §2.1 on every chart page — coordinate calibration is a post-generation step (see [`verify-charts`](../workflows/stages/verify-charts.md)) that depends on these markers — and **native object metadata** per [`executor-chart.md`](./executor-chart.md) §2.2 on every eligible data-chart page. **Reach for native presets** per §3.0 as you draw each page: a block arrow, chevron, banner/ribbon, callout, standard flowchart node, or star is authored through `preset_shape_svg.py` at draw time — decided by the object's intent as you create it, never by scanning finished paths, and never committed to a bare `<path>`/`<polygon>` when a preset expresses it (a gradient fill/stroke or a pattern fill is the one paint exception — keep those ordinary SVG). **First-page gate (Mandatory)**: after completing the first page, run `python3 scripts/svg_quality_checker.py <project_path> --stage first-page` and fix every error before drawing page 2. This stage validates only the first authored page with a partial structure roster; future declared pages are not reported missing.- 2. **Quality Check Gate**: run `python3 scripts/svg_quality_checker.py <project_path> --stage final --json` on `svg_output/`. Any `error` (banned/unsupported features, invalid values, unresolved references, viewBox mismatch, etc.) MUST be fixed on the offending page before proceeding — regenerate and re-check. Every `warning` is advisory: it never sends the page back for required modification, never authorizes automatic rewriting of compatible user syntax, and needs no acknowledgement/disposition line. Recommendation warnings describe the generated-SVG default; fidelity/quality warnings may be surfaced when material, while the existing input remains releasable. Prototype-identical diagnostics are recorded as `inherited`, source conversion losses as `source-import`, changed/new advisories as `introduced`, and release failures as `blocking` in `validation/svg_quality_report.json`. If release truly depends on a condition, it belongs in `errors`. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.+ 2. **Quality Check Gate**: run `python3 scripts/svg_quality_checker.py <project_path> --stage final --json` on `svg_output/`. Any `error` (banned/unsupported features, invalid values, unresolved references, viewBox mismatch, etc.) MUST be fixed on the offending page before proceeding — regenerate and re-check. Every `warning` is advisory: it never sends the page back for required modification, never authorizes automatic rewriting of compatible user syntax, and needs no acknowledgement/disposition line. Recommendation warnings describe the generated-SVG default; fidelity/quality warnings may be surfaced when material, while the existing input remains releasable. Prototype-identical diagnostics are recorded as `inherited`, source conversion losses as `source-import`, changed/new advisories as `introduced`, and release failures as `blocking` in `validation/svg_quality_report.json`. If release truly depends on a condition, it belongs in `errors`. On success, use the exit status and terminal summary; do not open or `cat` the complete JSON into model context. Read only targeted fields for failure investigation or an explicit audit request. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.3. **Logic Construction Phase**: after SVGs pass the quality check, batch-generate speaker notes for narrative continuity.### 3.0 Native Preset Shape Selectiondiff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.mdindex b8a99c3f..c95b9918 100644--- a/skills/ppt-master/scripts/docs/svg-pipeline.md+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md@@ -339,6 +339,7 @@ Behavior:- `[Content_Types].xml` is generated from the actual media extensions written into the PPTX. Unknown media extensions fail unless Python's `mimetypes` can identify them.- Native export writes to a temporary file first and publishes the requested PPTX only after conversion succeeds. A failed conversion does not replace the main output file.- After publication, native export writes `validation/<output_stem>.report.json`. The report distinguishes authored Slides from internal Layout definitions, reruns ZIP integrity and published Slide-count checks, records slide/layout/master/notes part counts, labels relationship/structured/transition/animation validation as enforced at build time, links the final SVG quality report only when its SHA-256 source fingerprint matches the exact export inputs, and surfaces stale/unverified gates, unresolved template tokens, generic-only font stacks, and external image references.+- By default, a successful command also prints a compact receipt instead of requiring a report read: `[POSTFLIGHT] status=<...> quality_gate=<...> slides=<N> warning_categories=<N>`, followed by one compact line per warning category and the `[PPTX]` / `[REPORT]` paths. Resource-warning lines carry counts; a non-passing quality gate carries its status. Routine agents use this receipt and do not load either complete validation JSON into model context. Full reports remain cold audit artifacts; failure investigation and explicit audits extract only the required fields. `--quiet` keeps suppressing successful-run output.- Before publishing structured template output, export reopens the temporary PPTX and validates the Slide → Layout → Master graph and registrations, Layout identity, placeholder identity, reusable bounds, and prompt/level-one sizes. A mismatch aborts publication. Flat release instead validates its single referenced Master/Layout shell and exact date/footer/slide-number hook roster before packaging.- SVG clip paths are still restricted for authored SVGs, but nested crop wrappers generated by PPTX import are mapped back to native picture crop / geometry when possible.- Speaker notes are embedded automatically unless `--no-notes` is used@@ -429,7 +430,9 @@ the release gate (or use `--json-output`). The report separatesrelease failures (`blocking`), changed/new advisories (`introduced`),prototype-identical diagnostics (`inherited`), and source-conversion losses(`source-import`). It also fingerprints every checked SVG so postflight cannot-mistake a stale report for the current export gate.+mistake a stale report for the current export gate. On a successful run, use the+checker exit status and terminal summary; do not load the complete JSON unless a+failure investigation or explicit audit requires targeted fields.Template mode accepts the same compact canonical preset groups as generatedpages: one atomic `<g data-pptx-authoring="preset">` with direct visible paths.diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.pyindex c57880a2..6508c5d7 100644--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py@@ -10,6 +10,7 @@ import reimport shutilimport sysimport zipfile+from dataclasses import dataclassfrom datetime import datetimefrom pathlib import Pathfrom xml.etree import ElementTree as ET@@ -109,6 +110,18 @@ class PptxPostflightValidationError(RuntimeError):"""Reject a generated PPTX that fails package postflight validation."""+@dataclass+class _PostflightReceipt:+ """Carry the compact export result printed after the audit is written."""++ output_path: Path+ report_path: Path+ status: str+ quality_gate: str+ slide_count: int+ warnings: tuple[str, ...]++def _font_stack_is_generic_only(stack: str) -> bool:"""Return whether a CSS font stack contains no concrete family name."""families = [@@ -274,6 +287,26 @@ def _quality_report_context(}+def _postflight_warning_summaries(+ *,+ quality_gate: str,+ unresolved_token_count: int,+ external_image_count: int,+ generic_font_stack_count: int,+) -> tuple[str, ...]:+ """Return stable warning summaries for the terminal receipt."""+ warnings: list[str] = []+ if quality_gate != 'passed':+ warnings.append(f'quality_gate={quality_gate}')+ if unresolved_token_count:+ warnings.append(f'unresolved_template_tokens={unresolved_token_count}')+ if external_image_count:+ warnings.append(f'external_images={external_image_count}')+ if generic_font_stack_count:+ warnings.append(f'generic_only_font_stacks={generic_font_stack_count}')+ return tuple(warnings)++def _write_postflight_report(*,output_path: Path,@@ -283,7 +316,7 @@ def _write_postflight_report(pptx_structure: str,backup_path: Path | None,conversion_trace_path: Path | None,-) -> Path:+) -> _PostflightReceipt:"""Write the unified package/resource audit for a successful PPTX."""try:package = _package_part_counts(output_path)@@ -389,7 +422,35 @@ def _write_postflight_report(json.dumps(report, ensure_ascii=False, indent=2) + '\n',encoding='utf-8',)- return report_path+ warnings = _postflight_warning_summaries(+ quality_gate=quality_gate,+ unresolved_token_count=len(unresolved_tokens),+ external_image_count=external_image_count,+ generic_font_stack_count=len(generic_only_font_stacks),+ )+ return _PostflightReceipt(+ output_path=output_path,+ report_path=report_path,+ status=report_status,+ quality_gate=quality_gate,+ slide_count=int(package['slides']),+ warnings=warnings,+ )+++def _print_postflight_receipt(receipt: _PostflightReceipt) -> None:+ """Print the compact completion evidence; keep the full JSON on disk."""+ print(+ ' [POSTFLIGHT] '+ f'status={receipt.status} '+ f'quality_gate={receipt.quality_gate} '+ f'slides={receipt.slide_count} '+ f'warning_categories={len(receipt.warnings)}'+ )+ for warning in receipt.warnings:+ print(f' [POSTFLIGHT][WARNING] {warning}')+ print(f' [PPTX] {receipt.output_path}')+ print(f' [REPORT] {receipt.report_path}')def _declared_pptx_structure_mode(project_path: Path) -> str | None:@@ -1311,7 +1372,7 @@ Recorded narration:if success:try:- report_path = _write_postflight_report(+ receipt = _write_postflight_report(output_path=native_path,project_path=project_path,svg_files=native_files,@@ -1340,7 +1401,7 @@ Recorded narration:print(f" PPTX output remains at: {native_path}", file=sys.stderr)return 1if verbose:- print(f" Postflight report: {report_path}")+ _print_postflight_receipt(receipt)return 0 if success else 1diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex 6aa8babd..e9aaf03c 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -394,6 +394,7 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final- The same rule applies to structured-template warnings (empty/framing-only Layout, bare Master, duplicate layout keys): they may guide an optional template cleanup, but warnings alone never fail the quality gate. Flat `style`, free-design, and brand-only routes still rely on their existing hard errors for invalid structure metadata or incomplete required locks.- Run against `svg_output/` (not after `finalize_svg.py` — finalize rewrites SVG and masks violations).- The JSON report is written to `validation/svg_quality_report.json`. `inherited` prototype diagnostics and `source-import` compatibility losses are informational provenance; only changed/new warnings remain `introduced`, and all release-blocking failures remain `blocking`.+- **Hard rule — token-safe report handling**: On a successful checker run, use the exit status and terminal summary as gate evidence. Do not open, `cat`, or otherwise load the complete JSON report into model context. Read it only for failure investigation, an explicit audit request, or a field absent from stdout; extract only the required field(s).**Logic Construction Phase**: after the SVG quality gate passes, load [`executor-notes.md`](../references/executor-notes.md) and generate speaker notes → `<project_path>/notes/total.md`@@ -450,7 +451,7 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>- `exports/<project_name>_<timestamp>.pptx`- `validation/<project_name>_<timestamp>.report.json` with `passed` or `passed-with-warnings` package/resource postflight status-Disclose material postflight warnings to the user. A failed report or missing PPTX is not success.+The command prints a compact `[POSTFLIGHT]` receipt containing `status`, `quality_gate`, Slide count, warning-category counts, and the PPTX/report paths. Use that receipt as completion evidence and disclose its material warnings to the user. Do not open or `cat` the complete report on routine success; use targeted field extraction only for failure investigation, an explicit audit request, or information absent from the receipt. A failed report or missing PPTX is not success.## ✅ Generate PPTX Complete