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

fix(exports): emit token-safe postflight receipts

hugohe38cc25e29ce5d
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 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 consumers
This 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.md
index 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.md
index 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.md
index 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 Selection
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 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 separates
release 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 generated
pages: 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.py
index 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 re
import shutil
import sys
import zipfile
+from dataclasses import dataclass
from datetime import datetime
from pathlib import Path
from 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 1
if verbose:
- print(f" Postflight report: {report_path}")
+ _print_postflight_receipt(receipt)
return 0 if success else 1
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index 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