html-to-pptx
Wann auslösen
Benutzer sagt eine der folgenden Absichten:
- "Konvertiere dieses HTML / Web-Deck in PPT / pptx"
- "Hab eine HTML-Folienpräsentation erstellt, möchte eine PPT für Kollegen"
- "Im Meeting ist es unpraktisch, den Browser zu öffnen – ich möchte eine PPT-Datei"
- Es gibt bereits einen HTML-Dateipfad + Erwähnung von ppt / pptx / Präsentation / Folien
Aufruf
<skill_dir> ist der Installationspfad dieses Skills (normalerweise ~/.claude/skills/html-to-pptx/, unter Windows %USERPROFILE%\.claude\skills\html-to-pptx\). Ersetzen Sie <skill_dir> in den folgenden Befehlen durch den tatsächlichen Pfad, oder wechseln Sie zuerst per cd <skill_dir> und führen Sie dann direkt python convert.py … aus.
python <skill_dir>/convert.py <input.html>
- Standardmäßig wird die Ausgabe als
<input>.pptxim selben Verzeichnis wie die Eingabe erstellt - Schriftarten werden nach Bedarf geladen: Die im HTML verwendeten Schriftarten werden während der Konvertierung von Google Fonts abgerufen, subsetiert und eingebettet; zwischengespeichert in
%LOCALAPPDATA%\html-to-pptx\fonts\oder~/.cache/html-to-pptx/fonts/; bei erneuter Verwendung derselben Schriftart sofort aus dem Cache - Enthält das HTML CJK-Zeichen, werden automatisch Noto Sans SC + Noto Serif SC gesät (erster Download ca. 40 MB / ~30s für die statischen Varianten Regular/Bold, danach aus dem Cache)
- Schriftfamilien, die nicht bei GF verfügbar sind, fallen auf die Systemschriftarten des Viewers zurück, mit einer Warnung
| Option | Bedeutung |
|---|---|
--out <pfad> | Benutzerdefinierter Ausgabepfad für .pptx |
--keep-screenshots | Gleichzeitig HTML-Referenz-Screenshots + preflight.json pro Seite behalten |
--no-embed-fonts | Schriftarteinbettung überspringen. Datei wird kleiner, fällt aber auf anderen Geräten auf Systemschriften zurück |
--no-preflight | Stufe 1 (Risikovorprüfung) deaktivieren |
--no-verify | Stufe 5a (Strukturierte Selbstprüfung) deaktivieren |
--no-visual-audit | Stufe 5b (Visuelles Audit-Material) deaktivieren. Im Alltag nicht deaktivieren |
--install-user-fonts | Installiert automatisch erkannte Nicht-CJK-Schriftarten im Benutzerschriftartenverzeichnis (damit WPS sie korrekt rendern kann). Windows/macOS/Linux werden unterstützt. Muss zuerst den Benutzer fragen, siehe Abschnitt "Konfigurationsbestätigung" unten |
--only-slides N,N,N | Inkrementelle Wiederholung. Kommagetrennte Seitennummern (1-basiert). Measure läuft nur für die angegebenen Seiten + kombiniert mit zwischengespeicherten Measurements der vorherigen Runde; Assemble/Embed sind weiterhin vollständig; Stufe 5a rendert nur die angegebenen Seiten; Stufe 5b erstellt nur für die angegebenen Seiten neue Compare-Bilder – alle anderen Seiten verwenden zwischengespeicherte Daten aus der vorherigen Runde. Nur für iterative Audit-Runden, siehe Abschnitt "Inkrementelle Wiederholung" unten |
--cleanup | Keine Konvertierung. Löscht Audit / Measurement / Preflight-Artefakte neben <input>.pptx, behält nur .pptx und audited.html. Vor der endgültigen Auslieferung verwenden, siehe letzter Schritt des "Workflows" unten |
Arbeitskopie (Original-HTML bleibt unberührt)
Nach dem ersten Durchlauf von python convert.py <input>.html erstellt convert.py automatisch eine Kopie <input>.audited.html im selben Verzeichnis wie das Quell-HTML. Mechanismus:
- Alle Audit-Korrekturen werden an
audited.htmlvorgenommen, nicht am Quell-HTML - Bei späteren Durchläufen (einschließlich
--only-slides) wird<input>.audited.htmlals Eingabe verwendet, die Ausgabe bleibt<input>.pptx(das Suffix.auditedwird automatisch entfernt) - Wenn
audited.htmlbereits existiert → wird wiederverwendet, nicht überschrieben (Korrekturen aus der vorherigen Runde bleiben erhalten) - Wenn der Agent versehentlich das Quell-HTML als Eingabe übergibt → convert.py erkennt dies intern und wechselt auf audited.html zurück
- Cleanup löscht audited.html nicht (wird als lieferbares Nebenprodukt betrachtet, das mit
.pptxzusammen ausgeliefert wird) - Um von vorne zu beginnen → audited.html manuell löschen und neu ausführen
Konfiguration (.config.local.toml)
Optionale lokale Präferenzdatei im Stammverzeichnis des Skills, gitignoriert, eine pro Benutzer. Derzeit gibt es drei Präferenzkategorien:
[fonts]
auto_install = "ask" # "yes" automatisch installieren, "no" nie installieren, "ask" vom Agenten nachfragen
[cleanup]
default = "clean" # "clean" → automatische Bereinigung am Ende des Workflows, "keep" → Audit-Artefakte behalten
[audit]
mode = "ask" # "triage" / "page" / "manual" / "ask" → vom Agenten nachfragen
- Fehlende Datei / fehlender Schlüssel → Standardwert (wie oben)
- Vorlage:
<skill_dir>/.config.local.toml.example fonts.auto_installwird von convert.py erzwungen gelesen und angewendet (=yes →--install-user-fontsautomatisch anhängen, =no → automatisch ignorieren)cleanup.defaultwird vom Agenten am Ende des Workflows gelesen, um das Verhalten zu bestimmenaudit.modewird vom Agenten vor dem ersten convert bestätigt; nach Stufe 5b wird die Überprüfung gemäß diesem Wert durchgeführt:"triage"→ Der Haupt-Agent liest selbst dieaudit_contact_*.png-Übersicht, leitet Seiten weiter und delegiert die Detailansicht der Kandidatenseiten an Sub-Agenten – spart Token"page"→ Für jede Zielseite wird ein Sub-Agent beauftragt, das Einzelseitenbildslide_NN_compare.pngzu prüfen – deckt am gründlichsten ab"manual"→ Nur Audit-Material erstellen, dem Benutzer zur manuellen Prüfung übergeben; der Benutzer meldet Probleme, die dann behoben werden"ask"oder fehlend → Der Agent sammelt die Präferenz über AskUserQuestion und schreibt diesen Wert danach um (Standard)
- Erstnutzung: Der Agent sammelt
fonts.auto_installundaudit.modeüber AskUserQuestion und schreibt diese Datei selbst – der Benutzer muss sie nicht manuell erstellen
Konfigurationsbestätigung (vor dem ersten convert abschließen)
Zwei Präferenzen müssen vor dem ersten convert bestätigt werden: fonts.auto_install und audit.mode. Der Ablauf ist identisch, unterscheidet sich nur in den Auslösebedingungen und der Fragestellung.
Allgemeiner Ablauf
Jede Präferenz wird unabhängig in der folgenden Reihenfolge ermittelt:
- Lese
<skill_dir>/.config.local.toml, prüfe das entsprechende Feld:- Gültiger, nicht
askWert → gemäß diesem Wert verhalten, innerhalb der Sitzung nicht erneut fragen askoder Datei / Feld fehlt → "Auslösebestimmung + ask" durchführen
- Gültiger, nicht
- Wenn CLAUDE.md / globale Anweisung einen äquivalenten Wert explizit angibt → gemäß diesem Wert verhalten und die Konfiguration ergänzen (Single Source of Truth beibehalten)
Nach der Auslösung einmalig per AskUserQuestion fragen, beide Präferenzen müssen durchgeführt werden:
- Schreibe das entsprechende Feld in
<skill_dir>/.config.local.tomlmit der Benutzerantwort (nichtask, sonst wird es in der nächsten Sitzung erneut gefragt) - Die aktuelle Sitzung verhält sich gemäß der Antwort
Beim Schreiben der Konfiguration: Wenn die Datei nicht existiert → ganze Datei mit Write erstellen (Vorlage mit [fonts] [cleanup] [audit] Abschnitten); Wenn die Datei bereits existiert → mit Edit eine einzelne Zeile ersetzen (nur dieses eine Feld ändern), nicht die ganze Datei mit Write überschreiben, sonst gehen andere benutzerdefinierte Schlüssel verloren.
Wenn beide Präferenzen in derselben Sitzung ausgelöst werden → kombinieren und in einer einzigen AskUserQuestion nachfragen.
fonts.auto_install – Schriftarteninstallation
PowerPoint COM slide.Export() und WPS Office lesen keine rohen TTF-Schriftarten, die in pptx eingebettet sind – Audit-Rendering und WPS fallen auf Systemschriften zurück. Durch die Installation im Benutzerschriftartenverzeichnis werden beide als Systemschriften verwendet. Verzeichnisse (alle benutzerebene, manuell löschbar):
- Windows:
%LOCALAPPDATA%\Microsoft\Windows\Fonts\+ HKCU-Registrierung - macOS:
~/Library/Fonts/ - Linux:
~/.local/share/fonts/+fc-cache -f
Auslösebestimmung: Siehe auf das <head> des HTML auf <link href="...fonts.googleapis.com/..."> / @import url(https://fonts.googleapis.com/...) / Schriftfamiliennamen in <style> font-family::
- Auslösen: Jede GF / selbst gehostete Schriftart (Bricolage Grotesque, DM Sans, Inter, Space Grotesk, Caveat usw.)
- Nicht auslösen: Nur Systemschriftarten-Whitelist (Arial, Times New Roman, Helvetica, Helvetica Neue, Courier, system-ui, -apple-system, BlinkMacSystemFont, SF Pro, Microsoft YaHei, SimSun, PingFang, Hiragino)
Gemäß Antwort: Zustimmung → --install-user-fonts anhängen; Ablehnung → nicht anhängen.
audit.mode – Visueller Prüfmodus
Drei Modi triage / page / manual (Bedeutung siehe Abschnitt "Konfiguration" oben). Vor dem ersten convert jeder Sitzung auswerten (unabhängig vom HTML-Inhalt). AskUserQuestion als Single-Choice-Frage, Optionen sind die drei Modi.
Workflow (erzwungen)
convert.py ausführen bedeutet nicht, dass die Auslieferung abgeschlossen ist. Vollständiger Ablauf:
convert.py (erster Durchlauf erstellt automatisch <input>.audited.html, alle Korrekturen an dieser Kopie)
→ Stufe 5a Strukturierte Selbstprüfung (OOXML-Scan, mit Hinweisen)
→ Stufe 5b Visuelles Audit-Material – erfordert PowerPoint COM oder LibreOffice-Renderer
→ Lese `audit.mode` zur Bestimmung der Prüfmethode: triage / page / manual
→ [Agent-Audit]
triage-Modus: Haupt-Agent liest Kontaktbogen → Sub-Agent prüft Kandidatenseiten → Zusammenführen in audit_findings.md
page-Modus: Vollständige Sub-Agent-Dispatch für alle Seiten → Zusammenführen in audit_findings.md
manual-Modus: Audit-Material dem Benutzer übergeben, auf manuelles Feedback warten
→ Finding-für-Finding minimale lokale Änderungen vornehmen, Ziel ist audited.html (siehe "Reparaturdisziplin" unten)
→ Nach einer Charge von Findings: `convert.py <input>.audited.html --only-slides <geänderte Seiten>` + nur frische Seiten erneut prüfen (siehe "Inkrementelle Wiederholung" unten)
→ Alle Seiten OK oder nur noch LOW
→ [Bei HTML-Antimuster / neuen OOXML-Grenzen] In lessons-learned ablegen, siehe "Aufbereitung von HTML-Problemen und OOXML-Grenzen" unten
→ Lese `cleanup.default` aus `<skill_dir>/.config.local.toml`:
"clean" (Standard) → Direkt `python convert.py <out>.pptx --cleanup`, ohne den Benutzer zu fragen
Nach der Bereinigung bleiben: <input>.html (Quelle, unverändert) + <input>.audited.html (reparierte Version) + <out>.pptx
"keep" → Cleanup überspringen, alle Audit-Artefakte behalten
→ Liefere den .pptx-Pfad an den Benutzer aus (audited.html als reparierte HTML-Version mitliefern)
Vektoren-vor-Prinzip (erzwungen)
Inhalte, die mit nativen PPT-Text / Formen / Linien ausgedrückt werden können, sollten vorzugsweise editierbar bleiben: Normale Hintergrundfarben, normale vierkantige Rahmen, einseitige Linien, einfache Rechtecke/Ellipsen, einfache ::before / ::after-Linienrahmen sollten alle über PPT-Shapes gehen.
deco_snapshot dient nur als Fallback für OOXML-schwer ausdrückbare Dekorationen (Trefferbedingungen + vollständige Stufendefinition + Screenshot/Vektorebenen-Kooperationsmechanismus siehe references/supported-css.md). Erstellen Sie keine Screenshots für normale Linien, Diagrammachsen oder einfache Rahmen, um Zeit zu sparen – dies gefährdet die PPT-Editierbarkeit und erschwert spätere lokale Korrekturen.
Renderer-Anforderung (Vorbedingung für Stufe 5b)
Stufe 5b (Visuelles Audit) erfordert das Rendern von .pptx in PNG, abhängig von:
- PowerPoint COM (Windows + Office +
pywin32), oder - LibreOffice (plattformunabhängig, mit
pip install pdf2image)
Wenn einer davon verfügbar ist, kann das Audit ausgeführt werden. Wenn in der convert-Ausgabe [self-check] Übersprungen: Kein verfügbarer pptx-Renderer gefunden erscheint, ist keines von beiden installiert – in diesem Fall werden keine Compare-Bilder erzeugt, Stufe 5b wird direkt übersprungen.
In diesem Fall muss der Agent den Benutzer fragen (keine stillschweigende Auslieferung eines nicht auditierten pptx):
"Auf Ihrem Rechner ist weder PowerPoint noch LibreOffice installiert. Das visuelle Audit kann nicht durchgeführt werden, und die PPT könnte visuelle Fehler enthalten, die nicht erkennbar sind. Drei Optionen:
- LibreOffice installieren (empfohlen, plattformunabhängig, 2-3 Minuten):
winget install LibreOffice.LibreOffice(Windows) /brew install --cask libreoffice(macOS) /apt install libreoffice(Linux), dannpip install pdf2image, danach convert erneut ausführen- Audit überspringen und direkt ausliefern (akzeptieren, dass die PPT möglicherweise visuelle Fehler enthält)
- Auf einem anderen Rechner mit installiertem Office erneut ausführen"
Wenn der Benutzer Option 1 wählt → warten, bis die Installation abgeschlossen ist, dann convert erneut ausführen; Option 2 → --no-visual-audit anhängen, ausführen, nachdem das Risiko kommuniziert wurde; Option 3 → das aktuelle Verzeichnis + das HTML an ihn senden.
Visueller Audit-Modus (Konfiguration, Voraussetzung: 5b läuft)
Vor der Durchführung der visuellen Prüfung den Wert von [audit].mode in <skill_dir>/.config.local.toml lesen. Normalerweise sollte dies vor dem ersten convert durch den obigen Abschnitt "Konfigurationsbestätigung" abgefragt worden sein; wenn der Modus hier immer noch "ask" ist (der Agent hat die Frage vergessen), sofort den Benutzer gemäß Abschnitt "Konfigurationsbestätigung" fragen und dann fortfahren.
Die genaue Bedeutung jedes Modus siehe Abschnitt "Konfiguration" oben; hier sind nur die Anwendungsszenarien aufgelistet:
| mode | Anwendung |
|---|---|
triage | Standard, spart Token |
page | Vor endgültiger Auslieferung, bei kritischen Kunden, wenn der Benutzer maximale Gründlichkeit wünscht |
manual | Benutzer möchte selbst prüfen |
Die Aufgabenverteilung im triage-Modus ist klar: Runde 1 (Kontaktbogen-Durchgang) = Haupt-Agent liest die Thumbnail-Übersicht (günstig, Kontext enthält bereits Quell-HTML / Stufe 5a / Preflight); Runde 2 (Detail-Durchgang) = Kandidatenseiten werden an Sub-Agenten zur Einzelbildprüfung übergeben. Findings dürfen nicht allein anhand der Thumbnails als HIGH/MID eingestuft werden; ein Finding erfordert die Bestätigung durch Runde 2 mit Einzelbildprüfung durch einen Sub-Agenten.
Audit-Verteilung und Regeln zum Lesen von Compare-Bildern
Im page-Modus werden alle Seiten parallel über Claude Agent(...) Sub-Agenten dispatched. Im triage-Modus werden nur die in Runde 2 ausgewählten Kandidatenseiten an Sub-Agenten übergeben; Runde 1 (Kontaktbogen) wird vom Haupt-Agenten selbst gelesen, ohne Sub-Agenten.
Der Haupt-Agent liest Compare-Bilder nur in den folgenden fünf Szenarien:
triageRunde 1: Liestaudit_contact_*.pngzur Übersicht und Verteilung- Bestätigungsrunde für gezielte Korrekturen: Wenn in dieser Runde ≤ 2 frische Seiten vorhanden sind und die Änderungen kein globales CSS betreffen → Haupt-Agent liest direkt die Einzelbilder der frischen Seiten, um bekannte Findings zu überprüfen + auf neue Regressionen auf diesen Seiten zu scannen, kein Sub-Agent (ein Sub-Agent kostet 2-3 Minuten pro Runde, direktes Lesen dauert nur Sekunden). Bei mehr frischen Seiten oder globalen Änderungen wird weiterhin ein Sub-Agent verwendet
- Wenn Finding-Beschreibungen vage sind oder mit dem Quellcode kollidieren und nicht lokalisiert werden können → das entsprechende einzelne
slide_NN_compare.pnglesen - Vor der Bestätigung eines Sticky-Findings ein Einzelbild lesen
- Wenn der Benutzer eine bestimmte Seite bemängelt, das Einzelbild lesen
Darüber hinaus werden Compare-Bilder nicht seitenweise gelesen.
Die Batch-Aufteilung optimiert die Wall-Clock-Zeit, indem sie in kleine parallele Batches aufgeteilt wird (die serielle Verarbeitung großer Bilder durch Sub-Agenten ist der Hauptengpass; mehrere kleine Batches, die parallel gesendet werden, sind mehr als doppelt so schnell wie ein großer Batch):
| Anzahl Folien | Strategie |
|---|---|
| ≤ 2 | 1 Batch |
| 3-20 | Pro Batch 2 Seiten, alle parallel senden |
| > 20 | Pro Batch 3 Seiten (Anzahl der Agenten kontrollieren) |
Vollständige Sub-Agent-Aufrufvorlage + Checkliste + Findings-Format siehe <out>_audit/audit_prompt.md. Mehrere Agent(..., run_in_background: true, subagent_type: "general-purpose")-Aufrufe, die in derselben Nachricht des Haupt-Agenten platziert werden, werden parallel ausgeführt.
Sub-Agenten geben nur Findings-Text zurück (im page-Modus mit einem ## page NN-Block für jede Zielseite; in triage-Detail-Batches mit einem Block für jede Seite, die vergrößert geprüft wird). Der Haupt-Agent fasst alle zusammen und schreibt audit_findings.md – gleichzeitiges Schreiben würde sich gegenseitig überschreiben.
Jedes Finding muss einen stabilen Element-Kurznamen nennen und beschreiben: "Zustand im HTML-Vergleichsbild; Unterschied im PPT-Vergleichsbild". Es werden nur visuelle Probleme gemeldet, die das PPT im Vergleich zum HTML neu hinzugefügt oder verstärkt hat; bereits im HTML-Vergleichsbild vorhandene Probleme zählen nicht als Konvertierungs-Finding.
Haupt-Agent-Vorbereitung parallel zu Sub-Agenten (erzwungen)
Beim Starten von page-Modus oder triage Runde 2 Detail-Sub-Agenten: Agent-Aufrufe mit run_in_background: true und in derselben Nachricht gleichzeitig senden:
Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit Folien 1-4", prompt: ...)
Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit Folien 5-9", prompt: ...)
Read(file_path: "<deck>/template.html")
Read(file_path: "<skill_dir>/references/lessons-learned.md")
Grep(pattern: "class=\"slide |data-slide=", path: "<deck>/template.html",
output_mode: "content", -n: true)
Im Prompt jedes Sub-Agenten müssen direkt der absolute Pfad zu slide_NN_compare.png in diesem Batch, der Pfad zum Deck-HTML und der Pfad zu lessons-learned.md eingefügt werden (Anwendungsbereich siehe Abschnitt "Visueller Audit-Modus" oben); nicht davon ausgehen, dass die Read / Grep-Ausgabe des Haupt-Agenten automatisch an den Sub-Agenten weitergegeben wird.
Nur Vorbereitungen senden, die "unabhängig von den Findings immer nützlich sind" – nicht erraten und vorzeitig HTML ändern.
Reparaturdisziplin (auf Findings reagieren, nicht auf Ursachen)
Nach Erhalt von audit_findings.md: Alle Findings dieser Runde in einem Durchgang ändern und dann convert + Audit einmalig erneut ausführen – nicht eins nach dem anderen ausführen. Eine Runde = ein Batch HTML-Bearbeitungen + ein convert + ein Audit.
Nach Erhalt der Findings:
- Nicht routinemäßig Compare-Bilder selbst lesen (Findings beschreiben die Symptome bereits); drei Ausnahmen zum Lesen einzelner Bilder siehe Abschnitt "Audit-Verteilung und Regeln zum Lesen von Compare-Bildern" oben
- Nicht
measure.py/assemble.py/ irgendwelchen Skill-internen Code lesen, um die Ursache zu finden - Direkt
audited.htmlöffnen und Finding für Finding bearbeiten
Jedes Finding erhält eine minimale lokale HTML-Änderung:
-
Für jedes Finding nur die Stelle ändern, die es "verschwinden lässt", dann mit dem nächsten Finding fortfahren (weiter HTML bearbeiten, nicht convert erneut ausführen)
-
Nicht die tiefere Ursache verfolgen ("Warum ist die Schriftart zurückgefallen / warum ist das Layout verschoben")
-
Nicht "ich habe mal schnell .footer auch auf absolute Positionierung umgestellt" – Optimierungen außerhalb der Finding-Liste durchführen
-
Nicht unternehmensweite Refactorings über Findings hinweg durchführen ("Alle Folien einheitlich mit expliziter font-family-Deklaration" ≠ minimale Korrektur eines einzelnen Findings)
-
Wenn dasselbe Finding in zwei aufeinanderfolgenden Runden (vorherige Runde + aktuelle Runde) auftritt → Sticky-Regel greift, den Benutzer informieren, keine weiteren Änderungen vornehmen. Bestimmungsschlüssel =
(Seitenzahl, visueller Element-Kurzname):- Formulierung / Schweregrad / HIGH↔MID-Wechsel setzen die Zählung nicht zurück. Beispiel:
(Seite 5, take Schriftgröße)wird in Runde 6 als "zu klein" und in Runde 7 als "stark unzureichend" beschrieben → gleicher Sticky-Schlüssel, Runde 7 trifft zu - Nur wenn "Seitenzahl + Element" nicht übereinstimmen, handelt es sich um einen neuen Sticky-Schlüssel
- Zwischenrunde-Erholung: Wenn das Finding in Runde 6 auftritt, in Runde 7 verschwindet und in Runde 8 erneut auftritt → gilt nicht als Sticky (Fehlen in Runde 7 gilt als behoben, Runde 8 ist eine neue Regression)
- Sticky-Treffer = Dieses Finding in dieser Runde nicht reparieren, als Skill-Grenzkandidat dem Benutzer melden, andere Findings dieser Runde wie gewohnt reparieren
Umsetzung: Nachdem
audit_findings.mdjeder Runde zusammengeführt wurde und bevor Edit ausgeführt wird, muss zuerst dasaudit_findings.mdder vorherigen Runde (bei der ersten Runde nicht vorhanden) gelesen werden, um einen paarweisen Vergleich durchzuführen – Schlüssel, die sowohl in dieser als auch in der vorherigen Runde vorhanden sind, sind Treffer. Treffer-Findings werden separat aufgelistet und dem Benutzer zur Entscheidung vorgelegt, sie werden nicht in die aktuelle Bearbeitungswarteschlange aufgenommen. - Formulierung / Schweregrad / HIGH↔MID-Wechsel setzen die Zählung nicht zurück. Beispiel:
Nachdem alle Findings dieses Batches bearbeitet wurden, einmalig python convert.py <input>.audited.html --only-slides <geänderte Seiten> ausführen.
Bewertungskriterium: Ihre Diff-Zeilenanzahl ≤ Findings-Anzahl × 3 Zeilen. Eine Überschreitung dieser Größenordnung deutet auf "Überschießen" hin.
Inkrementelle Wiederholung (--only-slides)
Ab der zweiten Audit-Runde verwenden, erste Runde immer vollständig.
python convert.py <input>.audited.html --only-slides 2,7,12
Die inkrementelle Wiederholung deckt Measure / Stufe 5a Rendering / Stufe 5b Compare-Bilder ab, nur für die aufgelisteten Seiten + Seiten mit fehlendem Cache; Assemble / Embed Fonts bleiben vollständig. audit_index.json enthält incremental_mode: true, fresh_indices, cached_indices, pro Seite fresh: true/false.
Die Audit-Zielseiten einer inkrementellen Runde sind nur die fresh_indices. Im page-Modus werden diese Seiten direkt verteilt; im triage-Modus werden zuerst Kandidaten innerhalb dieser Seiten ausgewählt und dann zur Detailprüfung an Sub-Agenten übergeben.
Voraussetzung: Das <out>_audit/-Verzeichnis der vorherigen Runde existiert noch. Bei fehlendem Cache automatischer Fallback auf vollständige Ausführung; bei Änderung der Seitenanzahl automatische Erkennung und Fallback auf vollständige Messung.
Fälle, in denen --only-slides nicht verwendet werden darf (visuelles Überschreiten der aufgelisteten Seiten, falsch-negative Cache):
- Änderungen an globalem CSS (
<style>, Root-Selektoren,.slide-Allgemeinstile) - Hinzufügen / Entfernen von Schriftarten (@import, font-family-Deklaration geändert)
- Änderungen an Deck-Level-Tokens (Hintergrund, Themafarben, Abstände)
- Alle globalen Variablenänderungen, die das Layout anderer Seiten beeinflussen
Bei diesen Kategorien ohne Flag vollständig neu ausführen. Bei Unsicherheit → vollständige Neuausführung ist immer sicher.
Aufbereitung von HTML-Problemen und OOXML-Grenzen (erzwungen)
Ihre Rolle ist Aufruf + Verwendungsaufbereitung, nicht die Reparatur des Skills. Wenn Sie einen internen Bug im Skill entdecken, ändern Sie nicht measure.py / assemble.py vor Ort.
Nur zwei Kategorien werden aufbereitet:
1. HTML-Schreibprobleme (das HTML des Benutzers führt zu Verzerrungen bei der Konvertierung)
| Kategorie | Bestimmung | Aktion |
|---|---|---|
| Einzelfall (nur in diesem Deck vorhanden, eine oder zwei HTML-Zeilen reichen) | Seitenausnahme | Direkt im HTML-Quelltext ändern; nicht aufbereiten, nicht melden |
| Allgemeines HTML-Antimuster (jeder, der ähnliches HTML schreibt, wird darauf stoßen) | Deck-übergreifend | HTML ändern + im references/lessons-learned.md im Bereich "HTML-Schreibvermeidung" ablegen |
2. OOXML-Ausdrucksgrenzen (von PowerPoint / OOXML nativ nicht unterstützt)
Die überwältigende Mehrheit der dekorativen CSS (backdrop-filter / filter / mix-blend-mode / skew / box-shadow / gradient / ::before ::after Dekorationsverwendung – leeres content + bg-image / box-shadow usw.) wird bereits von hasComplexDecoration in der "Abdeckungsstrategie" automatisch erfasst und als deco_snapshot verarbeitet – HTML muss nicht geändert werden. ::before ::after String-Content (content: "↑" usw.) läuft über den Textkanal, siehe references/supported-css.md Stufe 1.
Echte Grenzen, die noch einen HTML-Workaround erfordern (OOXML-Textschicht kann nativ nicht ausgedrückt werden):
| Grenze | Alternativer Kanal |
|---|---|
| Farbige Emojis (COLR/CPAL-Schriftarten) | Twemoji SVG <img> über img-Kanal einbetten |
background-clip: text Textverlauf | Inline <svg><text fill="url(#grad)"> über SVG-Kanal einbetten |
Bei diesen beiden Kategorien: HTML ändern, um den alternativen Kanal zu verwenden + im references/lessons-learned.md im Bereich "OOXML-Grenzen" ablegen.
Wenn eine neue CSS-Unterstützung fehlt, die nicht in der obigen Tabelle steht → zuerst prüfen, ob hasComplexDecoration fälschlicherweise nicht ausgelöst wird (eine Zeile Auslösebedingung hinzufügen reicht), nicht HTML ändern. Siehe references/supported-css.md, Abschnitt "Standardvorgehen für neue Unterstützung".
Behandlung von vermeintlichen Skill-internen Bugs (nicht reparieren oder aufbereiten)
Wenn Sie feststellen, dass ein Symptom mit demselben CSS-Muster in einem anderen Deck erneut auftritt und es nicht innerhalb der bekannten OOXML-Grenzen liegt → dies ist eine unzureichende Abstraktion des Skills. Ändern Sie den Skill-Code nicht vor Ort. Tun Sie diese beiden Dinge:
- Workaround auf HTML-Seite für das aktuelle Deck, um das Finding zu beheben, damit der Benutzer eine lieferbare PPT erhält
- Teilen Sie dem Benutzer explizit mit: "Ein allgemeiner Bug im Skill wurde entdeckt: [Symptom + auslösendes CSS-Muster + aktueller Workaround]. Es wird empfohlen, dass der Autor dies als Issue aufnimmt, damit der Skill dieses Muster in measure/assemble allgemeiner behandeln kann."
Wo die Aufbereitung geschrieben wird: Lokale Kopie + Upstream-Vorlage
references/lessons-learned.md ist eine benutzerunabhängige lokale Arbeitskopie (gitignoriert). Beim ersten Ausführen von convert.py erstellt local_config.seed_lessons_learned() automatisch eine Kopie aus der Vorlage lessons-learned.md.example (committed). Der Mechanismus ist derselbe wie bei .config.local.toml.
- Der Agent liest/schreibt immer die lokale
lessons-learned.md– frei hinzufügen / ändern / organisieren, kein Git-Rauschen - Die lokale Kopie wird niemals von Upstream überschrieben –
git pullzieht nur die.example-Vorlage, nicht Ihre Arbeitskopie - Wenn Sie einen Eintrag upstreamen möchten: Der Autor kopiert den Eintrag manuell zurück in
lessons-learned.md.exampleund commitet; selektive Kuratierung, kein vollständiges Hochschieben - Lokale Geschäfts- / kundenspezifische Schreibweisen → direkt in die lokale Kopie schreiben, kein Upstream
- Lessons-Einträge enthalten nur wiederverwendbare Symptome, Auslösemuster und Vermeidungsregeln; keine spezifischen lokalen Dateinamen, Vorlagennamen, Seitenzahlen, Kundennamen oder Quellcodedateinamen. Konkrete Implementierungspositionen, Befehle und Codedetails bleiben in Commits / Issues / der Haupt-Skill-Dokumentation
Auslösung: Allgemeines HTML-Antimuster / OOXML-Grenze treffen → in die entsprechende Tabelle der lokalen lessons-learned.md aufnehmen. Jeder convert liest sie neu, sofort wirksam.
Abdeckungsstrategie (ein Satz)
Im Skill werden alle CSS in vier Ausgabestufen übersetzt: Vektortext → Vektorformen → Rasterdeko (deco_snapshot) → Medien-Direktübertragung. Einfache bg-color / border / border-radius gehen durch die ersten beiden Stufen (editierbar und durchsuchbar), box-shadow / gradient / filter / backdrop-filter / mix-blend-mode / asymmetrische abgerundete Ecken / beschnittene Container + rotierte Kinder usw. lösen hasComplexDecoration aus und gehen durch die dritte Stufe (Raster erfasst nur Dekorationspixel, Text bleibt als Vektor über dem Screenshot).
Vollständige Stufendefinition / Auslösebedingungen / Anleitung für neue Unterstützung (Vektoren zuerst → Screenshot-Fallback) → references/supported-css.md.
Pipeline
[1 Eingabeerkennung/Vorprüfung] → [2 Messung] → [3 Zusammenbau] → [4 Schrifteinbettung] → [5a Strukturierte Selbstprüfung] → [5b Visuelles Audit]
preflight.py measure.py assemble.py embed_fonts.py self_check.py visual_audit.py
Phasenaktionen / Anti-Annahme-Regeln / Exit-Assertions / Checkliste für neue Vorlagen → references/methodology.md.
Stufe 5b erzeugt <out>_audit/ (Compare-Bilder + Kontaktbogen + audit_index.json + audit_prompt.md). Kein Pixel-Diff – Zahlen sind für lokale Bugs unempfindlich und geben falsches Vertrauen; visuelle Beurteilung erfolgt gemäß audit.mode (triage / page / manual). Ohne Renderer wird 5b übersprungen, und der Benutzer wird gemäß Unterabschnitt "Renderer-Anforderung" oben gefragt.
Vor dem Aufruf
…
[abgeschnitten für Übersetzung]