nexu-io/open-design / plugins/community/humanize-ppt
humanize-ppt
VerifiedA presentation system for agent-made PPTs — born for the talk, not just the template. It turns raw material into an AST (audience-state-transfer) outline with per-page visual-enhancement decisions (image / SVG diagram / video), hands a production brief to a downstream renderer (HTML-PPT skills or native PPTX), then runs a capped 3-round presentation checkup (演讲体检) on the rendered deck. It never renders slides itself. Use before generating PPT/HTML slides from raw material, and after rendering when the user says things like "给这份 deck 做演讲体检" or "PPT 渲染质检". If all you want is one beautiful template page with no outline and no checkup, a rendering skill alone is enough.
scripts/pptx_qa.py
View on GitHub#!/usr/bin/env python3
"""Static OOXML checks for PPT Master output.
The checker intentionally uses only the Python standard library. It validates
the package and the Humanize-owned semantic contract without rewriting the
downstream PPTX. Visual collision/overflow remains PPT Master's browser review
gate because those failures require a rendered slide, not XML inspection.
"""
from __future__ import annotations
import posixpath
import re
import zipfile
from pathlib import Path
from typing import Any
from xml.etree import ElementTree as ET
PML = "http://schemas.openxmlformats.org/presentationml/2006/main"
DRAWING = "http://schemas.openxmlformats.org/drawingml/2006/main"
REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
PACKAGE_REL = "http://schemas.openxmlformats.org/package/2006/relationships"
CONTENT_TYPES = "http://schemas.openxmlformats.org/package/2006/content-types"
NS = {"p": PML, "a": DRAWING, "r": REL, "pr": PACKAGE_REL}
PLACEHOLDER_RE = re.compile(
r"(?:\[必填[^\]]*\]|\b(?:lorem\s+ipsum|todo|tbd)\b|SLIDES_HERE)",
re.IGNORECASE,
)
def _finding(
check_id: str,
severity: str,
evidence: str,
pages: list[str] | None = None,
) -> dict[str, Any]:
return {
"id": check_id,
"severity": severity,
"evidence": evidence,
"pages": pages or [],
}
def _read_xml(zf: zipfile.ZipFile, name: str) -> ET.Element:
return ET.fromstring(zf.read(name))
def _relationship_path(part_name: str) -> str:
directory, filename = posixpath.split(part_name)
return posixpath.join(directory, "_rels", f"{filename}.rels")
def _relationships(zf: zipfile.ZipFile, part_name: str) -> dict[str, dict[str, str]]:
rels_name = _relationship_path(part_name)
if rels_name not in zf.namelist():
return {}
root = _read_xml(zf, rels_name)
relationships: dict[str, dict[str, str]] = {}
for rel in root.findall("pr:Relationship", NS):
rel_id = rel.attrib.get("Id")
if rel_id:
relationships[rel_id] = dict(rel.attrib)
return relationships
def _resolve_target(source_part: str, target: str) -> str:
if target.startswith("/"):
return target.lstrip("/")
return posixpath.normpath(posixpath.join(posixpath.dirname(source_part), target))
def _ordered_slide_parts(zf: zipfile.ZipFile) -> list[str]:
presentation = "ppt/presentation.xml"
root = _read_xml(zf, presentation)
rels = _relationships(zf, presentation)
parts: list[str] = []
for slide_id in root.findall(".//p:sldIdLst/p:sldId", NS):
rel_id = slide_id.attrib.get(f"{{{REL}}}id")
rel = rels.get(rel_id or "", {})
target = rel.get("Target")
if not target:
raise ValueError(f"slide relationship is missing for {rel_id or 'unknown id'}")
resolved = _resolve_target(presentation, target)
if resolved not in zf.namelist():
raise ValueError(f"slide part is missing: {resolved}")
parts.append(resolved)
return parts
def _text(root: ET.Element) -> str:
return " ".join(
(node.text or "").strip()
for node in root.findall(".//a:t", NS)
if (node.text or "").strip()
)
def _tokens(value: str) -> set[str]:
return {
token.lower()
for token in re.findall(r"[A-Za-z0-9]+|[\u3400-\u9fff]", value)
if token.strip()
}
def _semantic_match(actual: str, expected_values: list[str]) -> bool:
actual_compact = re.sub(r"\W+", "", actual, flags=re.UNICODE).lower()
actual_tokens = _tokens(actual)
for expected in expected_values:
expected_compact = re.sub(r"\W+", "", str(expected), flags=re.UNICODE).lower()
if not expected_compact:
continue
if expected_compact in actual_compact or actual_compact in expected_compact:
return True
expected_tokens = _tokens(expected)
if expected_tokens:
overlap = len(actual_tokens & expected_tokens) / max(
1, min(len(actual_tokens), len(expected_tokens))
)
if overlap >= 0.5:
return True
return False
def _meaningful_note(text: str) -> bool:
compact = re.sub(r"[\W\d_]+", "", text, flags=re.UNICODE)
return len(compact) >= 4
def inspect_pptx(
pptx_path: str | Path,
plan: list[dict[str, Any]] | None = None,
*,
require_notes: bool = True,
require_transition: bool = True,
require_native_objects: bool = False,
allowed_ids: set[str] | None = None,
) -> dict[str, Any]:
"""Inspect a PPTX and return Humanize-compatible findings plus stats."""
path = Path(pptx_path)
plan = plan or []
findings: list[dict[str, Any]] = []
def add(
check_id: str,
severity: str,
evidence: str,
pages: list[str] | None = None,
) -> None:
if allowed_ids is None or check_id in allowed_ids:
findings.append(_finding(check_id, severity, evidence, pages))
try:
with zipfile.ZipFile(path) as zf:
corrupt_member = zf.testzip()
if corrupt_member:
add("pptx-package-invalid", "fail", f"CRC check failed for {corrupt_member}.")
return {"findings": findings, "stats": {"slide_count": 0}}
names = set(zf.namelist())
required_parts = {"[Content_Types].xml", "ppt/presentation.xml"}
missing_parts = sorted(required_parts - names)
if missing_parts:
add("pptx-package-invalid", "fail", f"Required OOXML parts missing: {', '.join(missing_parts)}.")
return {"findings": findings, "stats": {"slide_count": 0}}
content_types_bytes = zf.read("[Content_Types].xml")
try:
content_types_root = ET.fromstring(content_types_bytes)
except ET.ParseError as exc:
add("pptx-package-invalid", "fail", f"[Content_Types].xml cannot be parsed: {exc}.")
return {"findings": findings, "stats": {"slide_count": 0}}
if content_types_root.tag != f"{{{CONTENT_TYPES}}}Types":
add(
"pptx-package-invalid",
"fail",
"[Content_Types].xml has an unexpected root namespace.",
)
return {"findings": findings, "stats": {"slide_count": 0}}
if re.search(rb"<[A-Za-z_][\w.-]*:Types\b", content_types_bytes):
add(
"pptx-package-invalid",
"fail",
"[Content_Types].xml uses a prefixed root namespace; this package shape is rejected by LibreOffice. Emit the content-types namespace as the default namespace.",
)
try:
slide_parts = _ordered_slide_parts(zf)
except (ET.ParseError, KeyError, ValueError) as exc:
add("pptx-package-invalid", "fail", f"Presentation relationships cannot be parsed: {exc}.")
return {"findings": findings, "stats": {"slide_count": 0}}
if len(slide_parts) != len(plan) and plan:
add(
"pptx-slide-count-mismatch",
"fail",
f"PPTX has {len(slide_parts)} slides; slide_plan.json requires {len(plan)}.",
)
placeholder_pages: list[str] = []
empty_pages: list[str] = []
flattened_pages: list[str] = []
missing_note_pages: list[str] = []
note_drift_pages: list[str] = []
content_drift_pages: list[str] = []
broken_relationship_pages: list[str] = []
missing_transition_pages: list[str] = []
missing_native_pages: list[str] = []
notes_count = 0
editable_shape_count = 0
native_object_count = 0
for index, slide_part in enumerate(slide_parts):
page = str(
(plan[index] if index < len(plan) else {}).get("slide_id")
or f"S{index + 1:02d}"
)
if slide_part not in names:
broken_relationship_pages.append(page)
continue
try:
slide_root = _read_xml(zf, slide_part)
except ET.ParseError:
broken_relationship_pages.append(page)
continue
slide_text = _text(slide_root)
if PLACEHOLDER_RE.search(slide_text):
placeholder_pages.append(page)
if not slide_text.strip():
empty_pages.append(page)
editable = (
len(slide_root.findall(".//p:sp", NS))
+ len(slide_root.findall(".//p:grpSp", NS))
+ len(slide_root.findall(".//p:graphicFrame", NS))
)
editable_shape_count += editable
if editable == 0:
flattened_pages.append(page)
if require_transition and slide_root.find(".//p:transition", NS) is None:
missing_transition_pages.append(page)
graphic_data = slide_root.findall(".//a:graphicData", NS)
native_on_page = sum(
1
for node in graphic_data
if node.attrib.get("uri", "").endswith(("/chart", "/table"))
)
native_object_count += native_on_page
plan_entry = plan[index] if index < len(plan) else {}
diagram = ((plan_entry.get("media") or {}).get("diagram") or {})
expects_native = diagram.get("needed") and diagram.get("kind") == "html-table"
if require_native_objects and expects_native and native_on_page == 0:
missing_native_pages.append(page)
expected_values = [
str(plan_entry.get("title") or ""),
str(plan_entry.get("message") or ""),
*[str(item) for item in (plan_entry.get("visible_content") or [])],
]
has_expected_content = any(value.strip() for value in expected_values)
if has_expected_content and slide_text and not _semantic_match(slide_text, expected_values):
content_drift_pages.append(page)
try:
rels = _relationships(zf, slide_part)
except ET.ParseError:
broken_relationship_pages.append(page)
rels = {}
notes_parts: list[str] = []
for rel in rels.values():
if rel.get("TargetMode") == "External":
continue
target = rel.get("Target")
if not target:
continue
resolved = _resolve_target(slide_part, target)
if resolved not in names:
broken_relationship_pages.append(page)
if rel.get("Type", "").endswith("/notesSlide"):
notes_parts.append(resolved)
note_text = ""
for notes_part in notes_parts:
if notes_part not in names:
continue
try:
note_text = f"{note_text} {_text(_read_xml(zf, notes_part))}".strip()
except ET.ParseError:
broken_relationship_pages.append(page)
if _meaningful_note(note_text):
notes_count += 1
elif require_notes:
missing_note_pages.append(page)
speaker_intent = str(plan_entry.get("speaker_intent") or "")
if (
speaker_intent
and note_text
and not _semantic_match(note_text, [speaker_intent])
):
note_drift_pages.append(page)
if placeholder_pages:
add(
"pptx-placeholder-residue",
"fail",
"Template or draft placeholders remain in slide text.",
sorted(set(placeholder_pages)),
)
if empty_pages:
add(
"pptx-slide-empty",
"fail",
"Slides contain no editable visible text.",
sorted(set(empty_pages)),
)
if flattened_pages:
add(
"pptx-flattened-slide",
"fail",
"Slides contain no editable shape, group, table, or chart object.",
sorted(set(flattened_pages)),
)
if missing_note_pages:
add(
"pptx-missing-speaker-notes",
"fail",
"Speaker notes are missing or empty for planned slides.",
sorted(set(missing_note_pages)),
)
if note_drift_pages:
add(
"pptx-speaker-intent-drift",
"warn",
"Speaker notes do not visibly preserve the Humanize speaker intent.",
sorted(set(note_drift_pages)),
)
if content_drift_pages:
add(
"pptx-ast-content-drift",
"warn",
"Slide text has weak lexical overlap with the corresponding Humanize AST page.",
sorted(set(content_drift_pages)),
)
if broken_relationship_pages:
add(
"pptx-broken-relationship",
"fail",
"One or more slide relationships point to missing or invalid OOXML parts.",
sorted(set(broken_relationship_pages)),
)
if missing_transition_pages:
add(
"pptx-transition-missing",
"fail",
"Expected native slide transitions are missing.",
sorted(set(missing_transition_pages)),
)
if missing_native_pages:
add(
"pptx-native-object-missing",
"fail",
"A planned table page was not exported as a native table/chart object.",
sorted(set(missing_native_pages)),
)
return {
"findings": findings,
"stats": {
"slide_count": len(slide_parts),
"notes_count": notes_count,
"editable_shape_count": editable_shape_count,
"native_object_count": native_object_count,
},
}
except (zipfile.BadZipFile, OSError) as exc:
add("pptx-package-invalid", "fail", f"Cannot open PPTX package: {exc}.")
return {"findings": findings, "stats": {"slide_count": 0}}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |