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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.pyindex 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 1diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex 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