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(svg-export): require passing quality reports for release

hugohe341f3d8877002
diff --git a/docs/technical-design.md b/docs/technical-design.md
index f3b5ffe7..e5147b07 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -30,7 +30,7 @@ The three layers have separate responsibilities and cannot substitute for one an
|---|---|---|
| Prompts, templates, and examples | State the project-canonical spelling precisely and reduce drift and warnings at the source | They are not a correctness or safety boundary |
| `svg_quality_checker.py` | Enforce the project contract on authoring state; errors block and non-blocking warnings pass | It does not silently rewrite pages or guess design intent |
-| `svg_to_pptx.py` | Defensively validate compiler mappings and the package, normalize supported compatible forms, and link the upstream SVG quality report into postflight | It does not rerun the complete `svg_quality_checker.py` or treat file creation as proof that the upstream quality gate passed |
+| `svg_to_pptx.py` | Defensively validate compiler mappings and the package, normalize supported compatible forms, require a current matching final quality report for formal release, and link it into postflight | It does not rerun the complete `svg_quality_checker.py` or treat file creation as proof that the upstream quality gate passed |
---
@@ -598,12 +598,12 @@ The architectural reasons worth knowing here:
| Severity | Classification | Pipeline behavior |
|---|---|---|
-| `error` | A structural contract is broken; the input has no mapping or is ambiguous; required metadata is missing; a value is invalid; conversion may violate DrawingML/PPTX constraints; or PowerPoint may need to repair the file | The Executor must re-author and revalidate; Generate must not enter export while the final report still has blocking errors. If export reads such a final report, postflight marks `quality_gate=failed`, and the artifact must not be declared a successful delivery |
+| `error` | A structural contract is broken; the input has no mapping or is ambiguous; required metadata is missing; a value is invalid; conversion may violate DrawingML/PPTX constraints; or PowerPoint may need to repair the file | The Executor must re-author and revalidate; Generate must not enter export while the final report still has blocking errors. Formal release export independently rejects such a report before PPTX creation |
| `warning` | A unique, safe, legal conversion exists, but the input is not project-canonical or carries a documented normalization, fidelity reduction, or visual-quality risk | Record the diagnostic and allow publication; no acknowledgement or mandatory rewrite is required |
The gate follows the three-layer responsibility defined in the design philosophy. It intentionally has no auto-fix: a mechanical patch can silently overwrite valid design intent and ship a worse page.
-**Current implementation boundary.** `svg_to_pptx.py` creates the PPTX before writing postflight. A `quality_gate=failed` result produces a failed report, but that state alone currently does not force a nonzero CLI exit or delete the generated file. Missing, non-final, stale, or unverifiable quality reports appear under their specific `quality_gate` values and put the report into `passed-with-warnings`; current Step 7 allows those artifacts to complete after the receipt is read and material warnings are disclosed. File existence or exit code `0` therefore does not prove success: a failed report must never be delivered, while `passed-with-warnings` requires judgment and disclosure based on its exact gate and warnings. The exporter has not yet closed `quality_gate=failed` into an independent nonzero exit or rollback; that is a defensive implementation gap, not relaxed error semantics.
+**Current implementation boundary.** Formal default release export and `--quick-generate` each compute the exact SVG-source fingerprint and refuse a missing, unreadable, unsupported, non-final, blocking, stale, or unverifiable final report before PPTX creation. An existing project without `validation/svg_quality_report.json` exits nonzero with the `not-provided` gate status; run the final checker against its current `svg_output/` before release export. A matching report may still contain non-blocking warnings; publication continues and postflight records `passed-with-warnings` when applicable. An explicit non-`output` `--source` remains a diagnostic override and bypasses this release gate, so a diagnostic file's existence alone is not delivery proof; postflight still records any verifiable report linkage.
If the same warning repeatedly appears in newly generated pages, fix the prompt, template example, or specification so default output returns to the project-canonical spelling. That is a generation-quality issue, not a reason to turn otherwise safe compatible input into an error. Conversely, if practice shows that a warning can produce an invalid file or ambiguous meaning, update the contract and checker together to classify it as an error.
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 205fedbc..cf0eff68 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -30,7 +30,7 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使
|---|---|---|
| 提示词、模板与示例 | 精确表达项目规范写法,从源头减少偏差和 warning | 不作为正确性或安全边界 |
| `svg_quality_checker.py` | 在作者状态上执行项目合同;error 阻塞,非阻塞 warning 放行 | 不静默改写页面,也不猜测设计意图 |
-| `svg_to_pptx.py` | 对编译映射与 package 执行防御校验;归一化已支持的兼容形式;把前置 SVG 质量报告关联进 postflight | 不重跑完整 `svg_quality_checker.py`,也不以“文件已生成”替代前置质量门 |
+| `svg_to_pptx.py` | 对编译映射与 package 执行防御校验;归一化已支持的兼容形式;正式发布前要求当前匹配的 final 质量报告,并把它关联进 postflight | 不重跑完整 `svg_quality_checker.py`,也不以“文件已生成”替代前置质量门 |
---
@@ -541,12 +541,12 @@ SVG 与 DrawingML 的表达模型并不等价,因此主编译路径不把“
| 严重性 | 判定条件 | 流水线行为 |
|---|---|---|
-| `error` | 结构合同被破坏;输入无映射或有歧义;必要 metadata 缺失;数值非法;转换后可能违反 DrawingML / PPTX 约束;或可能导致 PowerPoint 修复文件 | Executor 必须重写并重新校验;Generate 路线不得在 final 报告仍有阻塞错误时进入导出。若导出器读到带阻塞错误的 final 报告,postflight 标记 `quality_gate=failed`,该产物不得被声明为成功交付 |
+| `error` | 结构合同被破坏;输入无映射或有歧义;必要 metadata 缺失;数值非法;转换后可能违反 DrawingML / PPTX 约束;或可能导致 PowerPoint 修复文件 | Executor 必须重写并重新校验;Generate 路线不得在 final 报告仍有阻塞错误时进入导出。正式发布导出还会在创建 PPTX 前独立拒绝这类报告 |
| `warning` | 已有唯一、安全、合法的转换结果,但输入不是项目规范写法,或存在已知的确定性归一化、保真度下降、视觉质量风险 | 记录诊断后允许发布;不要求逐条确认或强制回改 |
质量门沿用设计哲学中定义的三层职责。这里有意不提供 auto-fix:机械修补可能静默覆盖有效的设计意图,也可能交付一个更差的页面。
-**当前实现边界。** `svg_to_pptx.py` 会先生成 PPTX,再写 postflight;`quality_gate=failed` 会得到失败报告,但这一状态目前不会单独让 CLI 返回非零,也不会删除已经生成的文件。缺失、非 final、过期或无法验证的质量报告会以对应 `quality_gate` 出现在回执中,并使报告进入 `passed-with-warnings`;当前 Step 7 允许这类产物在读取回执并披露实质 warning 后完成。因而 PPTX 文件存在或命令退出 `0` 都不等于成功:`failed` 报告绝不能交付,`passed-with-warnings` 则必须结合具体 `quality_gate` 和 warning 判断、披露。导出器尚未把 `quality_gate=failed` 独立收口为非零退出或回滚,这是当前防御缺口,而不是放宽 error 语义。
+**当前实现边界。** 默认正式发布与 `--quick-generate` 会计算精确的 SVG 来源指纹,并在创建 PPTX 前拒绝缺失、不可读、schema 不支持、非 final、含阻塞项、过期或无法验证的 final 报告。既有工程缺少 `validation/svg_quality_report.json` 时会得到 `not-provided` 门状态并非零退出;正式发布前必须先对当前 `svg_output/` 运行 final 检查。匹配报告仍可包含非阻塞 warning;发布继续,postflight 在适用时记录 `passed-with-warnings`。显式指定非 `output` 的 `--source` 仍属于诊断覆盖,会绕过这道发布门,因此诊断产物“文件存在”本身不构成交付证明;postflight 仍记录可验证的报告关联。
如果同一种 warning 持续出现在新生成页面中,应优先修正提示词、模板示例或规范说明,使默认输出回到项目规范写法;这属于生成质量问题,不需要把本来安全的兼容输入升级成阻塞错误。反过来,如果实践证明某个 warning 可能产生非法文件或不确定语义,就必须把合同和 Checker 同步升级为 error。
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.md
index 363a5f2b..c7f82d40 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -41,7 +41,7 @@ tell; each capability above earns its place per page, not per deck.
| Page transition | CLI: `fade`, 0.4s | Calm baseline that suits most decks; the public Python builder retains its legacy 0.5s default |
| Per-element animation | **`none` (off)** | A page appears as a whole. Auto-firing element builds are an unsolicited "AI deck" tell, so object animation is opt-in. Turn on the content-aware canonical entrance policy with `-a auto`, or select one PowerPoint-native `entrance_*`, `emphasis_*`, `path_*`, or `exit_*` key explicitly |
-To regenerate a deck with different settings, rerun `svg_to_pptx.py` against the same `svg_output/` — no need to rerun the LLM. `-s final` is reserved for diagnostic comparison and is not a supported release source. To turn per-element animation on for the whole deck, pass `-a auto`.
+To regenerate a deck with different settings, rerun the final checker when its current matching report is absent or stale, then rerun `svg_to_pptx.py` against the same `svg_output/`; the content-generation LLM need not rerun unless authored SVG requires repair. `-s final` is reserved for diagnostic comparison and is not a supported release source. To turn per-element animation on for the whole deck, pass `-a auto`.
---
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 8360a686..bd4a5c34 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -634,6 +634,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.
- `--conversion-trace` without a path writes `validation/<output_stem>.trace.json`. `--conversion-trace <path>` respects the explicit destination; relative paths are resolved from the project root, so `exports/<name>.trace.json` remains available when intentionally requested.
+- Formal default and `--quick-generate` release export compute the exact SVG source fingerprint and refuse a missing, unreadable, unsupported, non-final, blocking, stale, or unverifiable final quality report before PPTX creation. A project without `validation/svg_quality_report.json` exits nonzero with the `not-provided` gate status; run the final checker against its current `svg_output/` first. An explicit non-`output` `--source` remains a diagnostic override and bypasses this release gate; postflight still records any verifiable report linkage.
- 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. A matching final quality report with introduced warnings yields `passed-with-warnings` and a `quality_introduced_warnings=<N>` receipt instead of a clean `passed` claim.
- 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.
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 b17ec473..bdfcb109 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
@@ -1284,8 +1284,8 @@ Recorded narration:
)
return 1
- # Native DrawingML is the only PPTX product. ``-s`` remains an explicit
- # diagnostic source override; standard export always reads svg_output/.
+ # Native DrawingML is the only PPTX product. A non-output ``-s`` remains a
+ # diagnostic source override; default and explicit output use release rules.
native_source = args.source or 'output'
native_files, native_source_dir = find_svg_files(
project_path,
@@ -1311,19 +1311,27 @@ Recorded narration:
print("Error: No SVG files found", file=sys.stderr)
return 1
- if args.quick_generate:
+ release_quality_gate = args.quick_generate or args.source in {None, 'output'}
+ if release_quality_gate:
source_fingerprint = _svg_source_fingerprint(native_files)
quality = _quality_report_context(project_path, source_fingerprint)
quality_gate, _ = _quality_gate_status(quality)
if quality_gate != 'passed':
+ export_mode = (
+ '--quick-generate'
+ if args.quick_generate
+ else 'default release export'
+ )
print(
- "Error: --quick-generate requires a passing final SVG quality "
- f"report for the current svg_output/; found {quality_gate}.",
+ f"Error: {export_mode} requires a passing final SVG quality "
+ f"report for the current {native_source_dir}/; found "
+ f"{quality_gate}.",
file=sys.stderr,
)
+ quick_flag = ' --quick-generate' if args.quick_generate else ''
print(
"Run: python3 skills/ppt-master/scripts/svg_quality_checker.py "
- f'"{project_path}" --quick-generate --stage final --json',
+ f'"{project_path}"{quick_flag} --stage final --json',
file=sys.stderr,
)
return 1
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index ad203af6..26d13021 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -667,7 +667,7 @@ sidecar, preserve `fade` / `none`.
- `validation/<project_name>_<timestamp>.report.json` with `passed` or `passed-with-warnings` package/resource postflight status
- `validation/<project_name>_<timestamp>.trace.json` when bare `--conversion-trace` is enabled; an explicit `--conversion-trace <path>` uses that destination instead
-The compact `[POSTFLIGHT]` receipt prints `status`, `quality_gate`, Slide count, warning-category counts, and PPTX/report paths. Disclose material warnings. 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. Retain its report path for later Generate narration (`deck_motion` handoff).
+Before creating the PPTX, the exporter independently requires the current matching `final` quality report; a missing, unreadable, unsupported, non-final, blocking, stale, or unverifiable report exits nonzero. The compact `[POSTFLIGHT]` receipt prints `status`, `quality_gate`, Slide count, warning-category counts, and PPTX/report paths. Disclose material warnings. 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. Retain its report path for later Generate narration (`deck_motion` handoff).
## ✅ Generate PPTX Complete