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(quality-checker): restore structured preflight with layered template checks
hugohe3f9dbdca26d6d
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.pyindex 09447ac9..d0908f8f 100644--- a/skills/ppt-master/scripts/svg_quality_checker.py+++ b/skills/ppt-master/scripts/svg_quality_checker.py@@ -217,9 +217,31 @@ HEX_VALUE_RE = re.compile(r"#(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})")-# Master/Layout validation is temporarily dormant until its ownership contract-# is resolved. The exporter remains the authority for structured PPTX assembly.-_CHECK_PPTX_MASTER_LAYOUT = False+# Master/Layout preflight validation. Structured deck/layout-template projects+# are checked at authoring time; the exporter remains the final OOXML/package+# authority. Flat projects only receive the negative guard that rejects authored+# structure metadata. Template roster/placeholder checks always run; the legacy+# template structure override stays dormant until the bundled library migrates+# off native_structure_mode: template. Current structured templates opt in via+# their design_spec.md declaration without waiting for that migration.+_CHECK_PPTX_STRUCTURED_PROJECT = True+_CHECK_PPTX_TEMPLATE_MODE = False+# Explicit migration debt: remove each entry after that bundled workspace adopts+# native_structure_mode: structured. New/custom workspaces are never exempt.+_BUNDLED_LEGACY_TEMPLATE_DIRS = frozenset({+ 'decks/中国电信/templates',+ 'decks/中国电建/templates',+ 'decks/中汽研/templates',+ 'decks/招商银行/templates',+ 'decks/重庆大学/templates',+ 'layouts/academic_defense/templates',+ 'layouts/ai_ops/templates',+ 'layouts/government_blue/templates',+ 'layouts/government_red/templates',+ 'layouts/medical_university/templates',+ 'layouts/pixel_retro/templates',+ 'layouts/psychology_attachment/templates',+})_BARE_HEX_VALUE_RE = re.compile(r"(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})"@@ -574,6 +596,56 @@ def _design_spec_is_brand(spec_path: Path) -> bool:return False+def _declared_template_structure_mode(target_path: Path) -> str | None:+ """Return a template directory's explicit native structure mode."""+ directory = target_path.parent if target_path.is_file() else target_path+ spec_path = directory / 'design_spec.md'+ try:+ text = spec_path.read_text(encoding='utf-8')+ except OSError:+ return None+ if not text.startswith('---\n'):+ return None+ end = text.find('\n---\n', 4)+ if end == -1:+ return None+ match = re.search(+ r'^native_structure_mode:\s*([A-Za-z0-9_-]+)\s*$',+ text[4:end],+ re.MULTILINE,+ )+ return match.group(1).lower() if match else None+++def _is_bundled_legacy_template(target_path: Path) -> bool:+ """Return whether a template is in the explicit bundled migration set."""+ directory = target_path.parent if target_path.is_file() else target_path+ library_root = Path(__file__).resolve().parents[1] / 'templates'+ try:+ relative_path = directory.resolve().relative_to(library_root.resolve())+ except ValueError:+ return False+ return relative_path.as_posix() in _BUNDLED_LEGACY_TEMPLATE_DIRS+++def _legacy_template_structure_deferred(target_path: Path) -> bool:+ """Return whether a known bundled legacy template may defer structure."""+ return bool(+ not _CHECK_PPTX_TEMPLATE_MODE+ and _declared_template_structure_mode(target_path) == 'template'+ and _is_bundled_legacy_template(target_path)+ )+++def _template_structure_checks_enabled(target_path: Path) -> bool:+ """Return whether positive structure checks apply to this template."""+ declared_mode = _declared_template_structure_mode(target_path)+ return bool(+ declared_mode == 'structured'+ or (_CHECK_PPTX_TEMPLATE_MODE and declared_mode == 'template')+ )++def _local_name(elem: ET.Element) -> str:"""Return an XML element's namespace-free local tag name."""tag = elem.tag@@ -819,7 +891,11 @@ class SVGQualityChecker:self._check_native_object_markers(root, result)# 8d. Validate explicit master/layout/placeholder metadata.- if _CHECK_PPTX_MASTER_LAYOUT:+ if (+ _template_structure_checks_enabled(svg_path)+ if self.template_mode+ else _CHECK_PPTX_STRUCTURED_PROJECT+ ):self._check_pptx_structure_metadata(root, svg_path, result)# 8e. Validate rendering-neutral page/structure compiler hints.@@ -1955,14 +2031,28 @@ class SVGQualityChecker:result: Dict,) -> None:"""Validate the intrinsic structured Master/Layout SVG contract."""- if (- not self.template_mode- and svg_path.parent.name == 'svg_output'- and _declared_pptx_structure_mode(+ if not self.template_mode and svg_path.parent.name == 'svg_output':+ declared_mode = _declared_pptx_structure_mode(self._resolve_project_path(svg_path)- ) == 'flat'- ):- return+ )+ if declared_mode == 'flat':+ forbidden_attrs = sorted({+ attr+ for elem in root.iter()+ for attr in _PPTX_STRUCTURE_ATTRS+ if elem.get(attr) is not None+ })+ if forbidden_attrs:+ result['errors'].append(+ f"{svg_path.name}: pptx_structure.mode: flat forbids "+ "Master/Layout/layer/placeholder metadata; remove "+ + ', '.join(forbidden_attrs)+ )+ return+ if declared_mode != 'structured':+ # The project-level gate emits one actionable migration error.+ # Avoid burying it under repeated per-page structure failures.+ returnhas_structure_metadata = any(elem.get(attr) is not Nonefor elem in root.iter()@@ -2432,6 +2522,8 @@ class SVGQualityChecker:if not dir_path.exists():print(f"[ERROR] Directory does not exist: {directory}")+ self.summary['errors'] += 1+ self.issue_types['Input issues'] += 1return []# Brand-only template workspaces have no SVG roster. Resolve the current@@ -2465,7 +2557,9 @@ class SVGQualityChecker:svg_files = sorted(svg_output.glob('*.svg'))if not svg_files:- print(f"[WARN] No SVG files found")+ print(f"[ERROR] No SVG files found in: {directory}")+ self.summary['errors'] += 1+ self.issue_types['Input issues'] += 1return []print(f"\n[SCAN] Checking {len(svg_files)} SVG file(s)...\n")@@ -2474,10 +2568,24 @@ class SVGQualityChecker:result = self.check_file(str(svg_file), expected_format)self._print_result(result)- if _CHECK_PPTX_MASTER_LAYOUT:+ if self.template_mode:+ check_structure = _template_structure_checks_enabled(dir_path)+ if _legacy_template_structure_deferred(dir_path):+ print(+ "[INFO] Legacy native_structure_mode: template detected; "+ "roster and placeholder checks remain active while positive "+ "structure checks await library migration."+ )+ if check_structure:+ self._check_pptx_structure_contract(dir_path, svg_files)+ if dir_path.is_dir():+ self._check_template_contract(+ dir_path,+ svg_files,+ check_structure=check_structure,+ )+ elif _CHECK_PPTX_STRUCTURED_PROJECT:self._check_pptx_structure_contract(dir_path, svg_files)- if self.template_mode and dir_path.is_dir():- self._check_template_contract(dir_path, svg_files)if not self.template_mode and dir_path.is_dir():self._check_animation_config_contract(dir_path)self._check_illustration_resource_contract(dir_path)@@ -2495,10 +2603,33 @@ class SVGQualityChecker:not self.template_modeand (project_path / 'svg_output').is_dir())- if (- standard_project- and _declared_pptx_structure_mode(project_path) == 'flat'- ):+ declared_mode = (+ _declared_pptx_structure_mode(project_path)+ if standard_project+ else None+ )+ if standard_project and declared_mode == 'flat':+ if (+ _load_pptx_structure_lock is None+ or _TemplateStructureError is None+ ):+ self._pptx_structure_issues.append((+ 'error',+ 'Flat PPTX project validation is unavailable because the '+ 'template_structure module could not be imported.',+ ))+ return+ try:+ structure_lock = _load_pptx_structure_lock(project_path)+ except _TemplateStructureError as exc:+ self._pptx_structure_issues.append(('error', str(exc)))+ return+ if structure_lock is None or structure_lock.mode != 'flat':+ self._pptx_structure_issues.append((+ 'error',+ 'spec_lock.md must contain one complete '+ 'pptx_structure.mode: flat contract.',+ ))returnhas_metadata = Falsefor svg_path in svg_files:@@ -2547,16 +2678,18 @@ class SVGQualityChecker:)return- declared_mode = _declared_pptx_structure_mode(project_path)if standard_project and declared_mode != 'structured':label = repr(declared_mode) if declared_mode else ('missing (legacy implicit baseline)')self._pptx_structure_issues.append(('error',- 'release SVG projects require spec_lock.md '- f'pptx_structure.mode: structured; found {label}. Follow '- 'skills/ppt-master/workflows/restore-pptx-structure.md before export.',+ 'release SVG projects require an explicit spec_lock.md '+ 'pptx_structure.mode: flat (free design / brand-only) or '+ f'structured (deck/layout template); found {label}. New '+ 'free-design projects use mode: flat; restore legacy '+ 'template/structured metadata by following skills/ppt-master/'+ 'workflows/restore-pptx-structure.md before export.',))return@@ -3242,14 +3375,21 @@ class SVGQualityChecker:)self._animation_issues.append((severity, message))- def _check_template_contract(self, dir_path: Path,- svg_files: List[Path]) -> None:+ def _check_template_contract(+ self,+ dir_path: Path,+ svg_files: List[Path],+ *,+ check_structure: bool,+ ) -> None:"""Check reusable-template structure, roster, and placeholder hints.- **Roster mismatch (orphan / missing)** is reported as an *error*: astale roster will produce a wrong ``layouts_index.json`` entry.- - **Explicit structure gaps** are errors: every reusable SVG declares- its Master and Layout identity. Zero-placeholder Layouts are valid.+ - **Explicit structure gaps** are errors when positive structure checks+ are enabled: every current reusable SVG declares its Master and Layout+ identity. Zero-placeholder Layouts are valid. Legacy library templates+ still receive roster and placeholder checks while awaiting migration.- **Placeholder gaps** are reported as *warnings*. Templates maylegitimately omit conventional placeholders or swap them out (e.g.``{{CLOSING_MESSAGE}}`` instead of ``{{THANK_YOU}}``), and a content@@ -3260,107 +3400,125 @@ class SVGQualityChecker:Issues are aggregated and printed in :py:meth:`print_summary` so theper-file report stays focused on intrinsic SVG validity."""- native_contract_path = dir_path / 'native_structure.json'- source_template_path = dir_path / 'source_template.pptx'- legacy_structure_detected = False- for svg_file in svg_files:- try:- root = ET.parse(svg_file).getroot()- except (OSError, ET.ParseError):- continue- if not root.get('data-pptx-master'):- legacy_structure_detected = True- self._template_issues.append((- 'error',- 'explicit_master_missing',- f"{svg_file.name}: reusable templates require root "- "data-pptx-master metadata",- ))- if not root.get('data-pptx-master-name'):- legacy_structure_detected = True- self._template_issues.append((- 'error',- 'explicit_master_name_missing',- f"{svg_file.name}: reusable templates require root "- "data-pptx-master-name metadata",- ))- if not root.get('data-pptx-layout'):- self._template_issues.append((- 'error',- 'explicit_structure_missing',- f"{svg_file.name}: reusable templates require root "- "data-pptx-layout metadata",- ))- if not root.get('data-pptx-layout-name'):- self._template_issues.append((- 'error',- 'explicit_structure_name_missing',- f"{svg_file.name}: reusable templates require root "- "data-pptx-layout-name metadata",- ))- if root.get('data-pptx-layout-kind') is not None:+ spec_path = dir_path / 'design_spec.md'+ spec_text = spec_path.read_text(encoding='utf-8') if spec_path.exists() else ""+ declared_structure_mode = _declared_template_structure_mode(dir_path)+ legacy_structure_deferred = _legacy_template_structure_deferred(dir_path)+ mode_error_recorded = False+ if declared_structure_mode != 'structured' and not legacy_structure_deferred:+ mode_error_recorded = True+ if declared_structure_mode == 'template':+ mode_error = (+ "legacy native_structure_mode: template is accepted only for "+ "the explicit bundled-library migration set; restore this "+ "workspace to native_structure_mode: structured"+ )+ else:+ mode_error = (+ "design_spec.md frontmatter must declare "+ "native_structure_mode: structured; only the explicit bundled "+ "legacy migration set may temporarily declare template"+ )+ self._template_issues.append((+ 'error',+ 'explicit_structure_mode',+ mode_error,+ ))+ if check_structure:+ native_contract_path = dir_path / 'native_structure.json'+ source_template_path = dir_path / 'source_template.pptx'+ legacy_structure_detected = False+ for svg_file in svg_files:+ try:+ root = ET.parse(svg_file).getroot()+ except (OSError, ET.ParseError):+ continue+ if not root.get('data-pptx-master'):+ legacy_structure_detected = True+ self._template_issues.append((+ 'error',+ 'explicit_master_missing',+ f"{svg_file.name}: reusable templates require root "+ "data-pptx-master metadata",+ ))+ if not root.get('data-pptx-master-name'):+ legacy_structure_detected = True+ self._template_issues.append((+ 'error',+ 'explicit_master_name_missing',+ f"{svg_file.name}: reusable templates require root "+ "data-pptx-master-name metadata",+ ))+ if not root.get('data-pptx-layout'):+ self._template_issues.append((+ 'error',+ 'explicit_structure_missing',+ f"{svg_file.name}: reusable templates require root "+ "data-pptx-layout metadata",+ ))+ if not root.get('data-pptx-layout-name'):+ self._template_issues.append((+ 'error',+ 'explicit_structure_name_missing',+ f"{svg_file.name}: reusable templates require root "+ "data-pptx-layout-name metadata",+ ))+ if root.get('data-pptx-layout-kind') is not None:+ legacy_structure_detected = True+ self._template_issues.append((+ 'error',+ 'deck_instance_layout_kind',+ f"{svg_file.name}: reusable template prototypes must omit "+ "legacy data-pptx-layout-kind metadata",+ ))+ if any(+ child.get('data-pptx-placeholder') is not None+ and child.tag.rsplit('}', 1)[-1] != 'g'+ for child in list(root)+ ):+ legacy_structure_detected = True+ missing_bounds = [+ child.get('id') or child.tag.rsplit('}', 1)[-1]+ for child in list(root)+ if child.get('data-pptx-placeholder') is not None+ and child.get('data-pptx-placeholder-bounds') is None+ ]+ if missing_bounds:+ legacy_structure_detected = True+ self._template_issues.append((+ 'error',+ 'placeholder_bounds_missing',+ f"{svg_file.name}: reusable templates require "+ "explicit design-zone data-pptx-placeholder-bounds; missing: "+ + ', '.join(missing_bounds),+ ))+ if native_contract_path.exists() or source_template_path.exists():legacy_structure_detected = Trueself._template_issues.append(('error',- 'deck_instance_layout_kind',- f"{svg_file.name}: reusable template prototypes must omit "- "legacy data-pptx-layout-kind metadata",+ 'legacy_native_structure_pair',+ "legacy native_structure.json/source_template.pptx template "+ "contracts must be restored through "+ "skills/ppt-master/workflows/restore-pptx-structure.md",))- if any(- child.get('data-pptx-placeholder') is not None- and child.tag.rsplit('}', 1)[-1] != 'g'- for child in list(root)- ):- legacy_structure_detected = True- missing_bounds = [- child.get('id') or child.tag.rsplit('}', 1)[-1]- for child in list(root)- if child.get('data-pptx-placeholder') is not None- and child.get('data-pptx-placeholder-bounds') is None- ]- if missing_bounds:++ if declared_structure_mode != 'structured':legacy_structure_detected = True+ if not mode_error_recorded:+ self._template_issues.append((+ 'error',+ 'explicit_structure_mode',+ "design_spec.md frontmatter must declare "+ "native_structure_mode: structured",+ ))+ if legacy_structure_detected:self._template_issues.append(('error',- 'placeholder_bounds_missing',- f"{svg_file.name}: reusable templates require "- "explicit design-zone data-pptx-placeholder-bounds; missing: "- + ', '.join(missing_bounds),+ 'legacy_structure_contract',+ "legacy template structure detected; run "+ "skills/ppt-master/workflows/restore-pptx-structure.md before "+ "Step 3 consumption",))- if native_contract_path.exists() or source_template_path.exists():- legacy_structure_detected = True- self._template_issues.append((- 'error',- 'legacy_native_structure_pair',- "legacy native_structure.json/source_template.pptx template "- "contracts must be restored through "- "skills/ppt-master/workflows/restore-pptx-structure.md",- ))-- spec_path = dir_path / 'design_spec.md'- spec_text = spec_path.read_text(encoding='utf-8') if spec_path.exists() else ""- mode_match = re.search(- r'^native_structure_mode:\s*([A-Za-z0-9_-]+)\s*$',- spec_text,- re.MULTILINE,- )- declared_structure_mode = mode_match.group(1).lower() if mode_match else None- if declared_structure_mode != 'structured':- legacy_structure_detected = True- self._template_issues.append((- 'error',- 'explicit_structure_mode',- "design_spec.md frontmatter must declare "- "native_structure_mode: structured",- ))- if legacy_structure_detected:- self._template_issues.append((- 'error',- 'legacy_structure_contract',- "legacy template structure detected; run "- "skills/ppt-master/workflows/restore-pptx-structure.md before "- "Step 3 consumption",- ))spec_pages = self._extract_spec_roster(spec_text) if spec_text else []custom_contract = self._extract_frontmatter_placeholders(spec_text) if spec_text else {}@@ -3384,9 +3542,15 @@ class SVGQualityChecker:))elif spec_path.exists():# design_spec.md is present but the roster parser found nothing —- # surface as a warning. Legacy specs may lack an explicit roster.+ # current structured templates fail closed; allowlisted legacy+ # library specs retain the historical warning until migration.+ severity = (+ 'error'+ if declared_structure_mode == 'structured'+ else 'warning'+ )self._template_issues.append((- 'warning',+ severity,'roster_unknown',f"could not extract page roster from {spec_path.name}; ""skipping orphan/missing checks",@@ -3855,20 +4019,23 @@ def print_usage() -> None:print("Usage:")print(" python3 scripts/svg_quality_checker.py <svg_file>")print(" python3 scripts/svg_quality_checker.py <directory>")- print(" python3 scripts/svg_quality_checker.py <template_dir> --template-mode")+ print(" python3 scripts/svg_quality_checker.py <workspace>/templates --template-mode")print(" python3 scripts/svg_quality_checker.py --all examples")print("\nExamples:")print(" python3 scripts/svg_quality_checker.py examples/project/svg_output/slide_01.svg")print(" python3 scripts/svg_quality_checker.py examples/project/svg_output")print(" python3 scripts/svg_quality_checker.py examples/project")- print(" python3 scripts/svg_quality_checker.py templates/layouts/academic_defense --template-mode")- print(" python3 scripts/svg_quality_checker.py templates/decks/招商银行 --template-mode")+ print(" python3 scripts/svg_quality_checker.py templates/layouts/academic_defense/templates --template-mode")+ print(" python3 scripts/svg_quality_checker.py templates/decks/招商银行/templates --template-mode")print("\nOptions:")print(" --format <ppt169|ppt43|...> Expected canvas format")- print(" --template-mode Validate a templates/{layouts,decks}/<id> directory:")- print(" glob *.svg directly, skip spec_lock checks,")- print(" enforce roster ↔ design_spec.md Page Roster consistency,")- print(" and emit advisory placeholder-convention warnings.")+ print(" --template-mode Validate a template workspace's templates/ directory:")+ print(" glob *.svg directly and skip spec_lock checks;")+ print(" always enforce roster consistency and emit placeholder hints.")+ print(" native_structure_mode: structured also enables complete")+ print(" per-file and cross-page structure validation. Legacy")+ print(" native_structure_mode: template defers only those structure")+ print(" checks until the bundled template library is migrated.")def main() -> None: