html-to-pptx
Quand déclencher
L'utilisateur exprime l'une des intentions suivantes :
- "Convertir ce deck HTML / web en PPT / pptx"
- "J'ai fait des diapositives HTML, je veux un ppt pour mes collègues"
- "Pas pratique de naviguer dans le navigateur pour une présentation, je veux un fichier ppt"
- Donne le chemin d'un fichier HTML + mentionne ppt / pptx / présentation / diapositives
Appel
<skill_dir> est le chemin d'installation de ce skill (généralement ~/.claude/skills/html-to-pptx/, sous Windows %USERPROFILE%\.claude\skills\html-to-pptx\). Remplacez <skill_dir> par le chemin réel dans les commandes ci-dessous, ou faites d'abord cd <skill_dir> puis exécutez python convert.py ….
python <skill_dir>/convert.py <input.html>
- Par défaut, le fichier de sortie est
<input>.pptxdans le même répertoire que l'entrée. - Les polices sont gérées à la demande : les polices utilisées dans le HTML sont récupérées depuis Google Fonts lors de la conversion, sous-ensemble puis intégrées, mises en cache dans
%LOCALAPPDATA%\html-to-pptx\fonts\ou~/.cache/html-to-pptx/fonts/; la même police est réutilisée instantanément la fois suivante. - Si le HTML contient des caractères CJK, les polices Noto Sans SC + Noto Serif SC sont automatiquement semées (premier téléchargement ~40 Mo / ~30s pour les instances statiques Regular/Bold, ensuite en cache).
- Les familles non présentes sur Google Fonts seront remplacées par la police système du visualiseur, avec un avertissement dans la console.
| Option | Signification |
|---|---|
--out <path> | Chemin de sortie personnalisé pour le .pptx |
--keep-screenshots | Conserve également les captures d'écran de référence de chaque diapositive + preflight.json |
--no-embed-fonts | Ignore l'intégration des polices. Fichier plus petit mais risque de substitution de polices sur d'autres machines |
--no-preflight | Désactive l'analyse préalable des risques (Stage 1) |
--no-verify | Désactive l'auto-vérification structurée (Stage 5a) |
--no-visual-audit | Désactive la production des éléments d'audit visuel (Stage 5b). Ne pas désactiver en usage normal |
--install-user-fonts | Installe les polices non-CJK détectées automatiquement dans le répertoire de polices utilisateur (pour que WPS les rende correctement). Supporte Win/macOS/Linux. Demander d'abord à l'utilisateur, voir le chapitre "Configuration préalable" ci-dessous |
--only-slides N,N,N | Ré-exécution incrémentale. Numéros de pages séparés par des virgules (indexés à partir de 1). measure ne s'exécute que pour les pages spécifiées + fusionne avec les mesures de la session précédente ; assemble/embed reste complet ; Stage 5a ne rend que les pages spécifiées ; Stage 5b ne reconstruit que les images de comparaison des pages spécifiées — les autres pages sont toutes réutilisées depuis le cache de la session précédente. Réservé aux itérations d'audit, voir le chapitre "Ré-exécution incrémentale" ci-dessous |
--cleanup | Ne fait pas de conversion. Supprime les artefacts de travail audit / measurement / preflight à côté de input.pptx (ne conserve que le .pptx et audited.html). À utiliser avant la livraison finale, voir la dernière étape du "Workflow" ci-dessous |
Copie de travail (le HTML d'origine est préservé)
Après la première exécution de python convert.py <input>.html, convert.py copie automatiquement <input>.audited.html dans le même répertoire que le HTML source. Mécanisme :
- Toutes les corrections d'audit modifient
audited.html, jamais le HTML source. - Les exécutions suivantes (y compris avec
--only-slides) utilisent<input>.audited.htmlcomme entrée, et la sortie reste<input>.pptx(le suffixe.auditedest automatiquement supprimé). - Si
audited.htmlexiste déjà → il est réutilisé, non écrasé (les corrections de la session précédente sont conservées). - Si l'agent transmet par erreur le HTML source comme entrée →
convert.pydétecte cela en interne et bascule versaudited.htmlpour la sécurité. cleanupne supprime pasaudited.html(considéré comme un sous-produit livrable, faisant partie de la même livraison que.pptx).- Pour repartir de zéro → supprimez manuellement
audited.htmlpuis relancez.
Configuration (.config.local.toml)
Fichier de préférences locales optionnel situé à la racine du skill, gitignored, un par utilisateur. Actuellement trois catégories de préférences :
[fonts]
auto_install = "ask" # "yes" install automatiquement, "no" n'installe jamais, "ask" l'agent demande
[cleanup]
default = "clean" # "clean" nettoie automatiquement à la fin du workflow, "keep" conserve les artefacts d'audit
[audit]
mode = "ask" # "triage" / "page" / "manual" / "ask" l'agent demande
- Fichier / clé absent → comportement par défaut (comme ci-dessus)
- Template :
<skill_dir>/.config.local.toml.example fonts.auto_installest lu et appliqué de force parconvert.py(=yes ajoute automatiquement--install-user-fonts, =no l'ignore automatiquement)cleanup.defaultest lu par l'agent à la dernière étape du workflow pour décider du comportementaudit.modeest confirmé par l'agent avant la première conversion ; après Stage 5b, l'examen est effectué selon cette valeur :"triage"→ l'agent principal consulte la planche contact (audit_contact_*.png) pour trier, puis envoie un sous-agent pour examiner les pages retenues, économisant des jetons."page"→ chaque page cible est envoyée à un sous-agent pour voir l'imageslide_NN_compare.pngindividuelle, couverture la plus stricte."manual"→ seuls les éléments d'audit sont générés, l'utilisateur vérifie manuellement ; l'agent corrige ensuite sur la base des retours."ask"ou absent → l'agent recueille la préférence viaAskUserQuestionpuis modifie cette valeur.
- Première utilisation : l'agent recueille
fonts.auto_installetaudit.modeviaAskUserQuestionpuis écrit lui-même ce fichier — l'utilisateur n'a pas à le créer manuellement.
Configuration préalable (à faire avant la première convert)
Deux préférences doivent être confirmées avant la première conversion : fonts.auto_install et audit.mode. Le processus est le même, seules les conditions de déclenchement et la formulation diffèrent.
Processus général
Chaque préférence est évaluée indépendamment selon l'ordre suivant :
- Lire
<skill_dir>/.config.local.toml, vérifier le champ correspondant :- Valeur valide autre que
ask→ suivre cette valeur, ne plus demander pendant la session. askou fichier/champ manquant → passer à "déclenchement + demande".
- Valeur valide autre que
- Si
CLAUDE.md/ les instructions globales spécifient explicitement une valeur équivalente, suivre cette valeur et mettre à jour le config (source unique de vérité).
Si déclenché, demander une fois via AskUserQuestion pour les deux :
- Écrire dans
<skill_dir>/.config.local.tomlle champ correspondant avec la réponse de l'utilisateur (ne pas écrireask, sinon la question sera reposée à la prochaine session). - En même temps, suivre la réponse pour la session en cours.
Pour écrire le config : si le fichier n'existe pas → écrire le fichier entier (blocs [fonts] [cleanup] [audit]) ; si le fichier existe déjà → utiliser Edit pour remplacer la ligne unique (ne modifier que ce champ), ne pas réécrire tout le fichier avec Write, car cela écraserait d'autres clés personnalisées de l'utilisateur.
Si les deux préférences sont déclenchées dans la même session → les fusionner dans une seule AskUserQuestion une seule fois.
fonts.auto_install — Installation des polices
PowerPoint COM slide.Export() et WPS Office ne lisent pas les TTF bruts intégrés dans le pptx — les rendus d'audit et WPS sont donc soumis aux polices système. Installer dans le répertoire de polices utilisateur permet aux deux de les utiliser comme polices système. Répertoires (tous au niveau utilisateur, supprimables manuellement) :
- Windows :
%LOCALAPPDATA%\Microsoft\Windows\Fonts\+ enregistrement HKCU - macOS :
~/Library/Fonts/ - Linux :
~/.local/share/fonts/+fc-cache -f
Déclenchement : Analyser le <head> du HTML pour <link href="...fonts.googleapis.com/..."> / @import url(https://fonts.googleapis.com/...) / les noms de polices dans font-family: des <style> :
- Déclenché : toute police GF ou auto-hébergée (Bricolage Grotesque, DM Sans, Inter, Space Grotesk, Caveat, etc.)
- Non déclenché : uniquement polices système de la liste blanche (Arial, Times New Roman, Helvetica, Helvetica Neue, Courier, system-ui, -apple-system, BlinkMacSystemFont, SF Pro, Microsoft YaHei, SimSun, PingFang, Hiragino)
Selon la réponse : accepter → ajouter --install-user-fonts ; refuser → ne pas l'ajouter.
audit.mode — Mode d'examen visuel
Trois modes triage / page / manual (voir signification dans le chapitre "Configuration" ci-dessus). Évalué avant chaque première conversion d'une session (ne dépend pas du contenu HTML). AskUserQuestion sous forme de question à choix unique, les options étant les trois modes.
Workflow (obligatoire)
Exécuter convert.py ne signifie pas que la livraison est terminée. Processus complet :
convert.py (première exécution : copie automatique de <input>.audited.html, toutes les corrections modifient cette copie)
→ Stage 5a Auto-vérification structurée (scan OOXML, donne des indices)
→ Stage 5b Production des éléments d'audit visuel — nécessite PowerPoint COM ou LibreOffice comme moteur de rendu
→ Lire `audit.mode` pour déterminer la méthode d'examen : triage / page / manual
→ 【Audit par l'agent】
mode triage : agent principal lit la planche contact pour trier → sous-agent examine les pages retenues → fusionne et écrit audit_findings.md
mode page : tous les sous-agents examinent les pages individuelles → fusionnent et écrivent audit_findings.md
mode manual : remet les éléments d'audit à l'utilisateur, attend ses retours manuels
→ Appliquer les corrections minimales et locales pour chaque finding, en ciblant audited.html (voir "Discipline de correction" ci-dessous)
→ Après un lot de corrections : `convert.py <input>.audited.html --only-slides <numéros de pages corrigées>` + ne réexaminer que les pages fraîches (voir "Ré-exécution incrémentale" ci-dessous)
→ Toutes les pages OK ou seulement des LOW restants
→ 【Si rencontré un anti-patron HTML / une nouvelle limite OOXML】 Capitaliser dans lessons-learned, voir "Capitalisation des problèmes HTML et limites OOXML" ci-dessous
→ Lire `cleanup.default` dans `<skill_dir>/.config.local.toml` :
"clean" (par défaut) → exécuter directement `python convert.py <out>.pptx --cleanup`, sans demander à l'utilisateur
Le répertoire contient alors : <input>.html (source, non modifié) + <input>.audited.html (version corrigée) + <out>.pptx
"keep" → ignorer le cleanup, tous les artefacts d'audit sont conservés
→ Livrer le chemin du .pptx à l'utilisateur (audited.html livré en même temps comme version HTML corrigée)
Principe de priorité vectorielle (obligatoire)
Tout contenu pouvant être exprimé avec du texte / des formes / des lignes PowerPoint natives doit rester modifiable en priorité : les couleurs de fond simples, les bordures simples, les lignes unilatérales, les rectangles/ellipses simples, les cadres ::before / ::after simples doivent tous passer par les formes PowerPoint.
deco_snapshot n'est utilisé qu'en dernier recours pour les décorations difficiles à exprimer en OOXML (conditions de déclenchement + définition complète des niveaux + mécanisme de coopération capture/vecteur dans references/supported-css.md). Il ne faut pas, pour simplifier, capturer en entier des lignes ordinaires, des axes de graphiques, des bordures simples — cela sacrifierait la modificabilité du PPT et rendrait les corrections locales ultérieures plus difficiles.
Exigence de moteur de rendu (condition préalable à Stage 5b)
Stage 5b (audit visuel) nécessite de rendre le .pptx en PNG, dépend de :
- PowerPoint COM (Windows + Office +
pywin32), ou - LibreOffice (multiplateforme, avec
pip install pdf2image)
Si l'un ou l'autre est disponible, l'audit peut être effectué. Si le message [self-check] skip : aucun moteur de rendu pptx disponible apparaît en sortie de convert, cela signifie qu'aucun des deux n'est installé — dans ce cas, l'audit ne produit pas d'images de comparaison, et Stage 5b est directement sauté.
Dans ce cas, l'agent doit obligatoirement demander à l'utilisateur (ne pas livrer un pptx non audité en silence) :
"Sur votre machine, il n'y a ni PowerPoint ni LibreOffice installé, l'audit visuel ne peut pas être effectué, le PPT pourrait avoir des bugs visuels non détectés. Trois options :
- Installer LibreOffice (recommandé, multiplateforme, 2-3 minutes) :
winget install LibreOffice.LibreOffice(Windows) /brew install --cask libreoffice(mac) /apt install libreoffice(Linux), puispip install pdf2image, relancer convert- Ignorer l'audit et livrer tel quel (accepter le risque de bugs visuels dans le PPT)
- Relancer sur une autre machine avec Office déjà installé"
Si l'utilisateur choisit 1 → attendre qu'il ait installé et relancer convert ; si 2 → exécuter avec --no-visual-audit et livrer après avoir informé du risque ; si 3 → lui envoyer le répertoire actuel + HTML.
Mode d'audit visuel (config, condition : 5b a été exécuté)
Avant d'effectuer l'examen visuel, lire [audit].mode dans <skill_dir>/.config.local.toml. Normalement, cela devrait avoir été demandé avant la première conversion via le chapitre "Configuration préalable" ci-dessus ; si ici mode est encore "ask" (signifiant que l'agent a oublié de demander), redemander immédiatement à l'utilisateur selon ce chapitre avant de continuer.
Chaque mode a sa signification donnée dans le chapitre "Configuration" ci-dessus ; ici on ne liste que les scénarios d'application :
| mode | Application |
|---|---|
triage | Par défaut, économique en jetons |
page | Avant livraison finale, client clé, utilisateur exigeant le plus strict |
manual | L'utilisateur veut vérifier lui-même |
La répartition du mode triage est très claire : Phase 1 (contact pass) = l'agent principal examine lui-même les vignettes pour trier (peu coûteux, le contexte contient déjà le HTML source / Stage 5a / preflight) ; Phase 2 (detail pass) = envoie les pages retenues à un sous-agent pour examen individuel des images de comparaison. On ne peut pas déclarer un finding HIGH/MID uniquement sur la base des vignettes ; pour signaler un finding, il faut passer par la Phase 2 confirmée par le sous-agent.
Distribution d'audit et règles de lecture des images de comparaison
Le mode page envoie toutes les pages à un sous-agent Agent(...) en parallèle (dispatch). Le mode triage n'envoie que les pages retenues en Phase 2 au sous-agent ; la Phase 1 (planche contact) est lue directement par l'agent principal, sans envoyer de sous-agent.
L'agent principal ne lit les images de comparaison que dans les cinq cas suivants :
triagePhase 1 : lireaudit_contact_*.pngpour la planche de tri.- Validation ciblée après correction : si le nombre de pages fraîches ≤ 2 et que les modifications n'ont pas affecté le CSS global → l'agent principal lit directement les images des pages fraîches pour vérifier les findings connus + détecter les éventuelles régressions sur la page, sans envoyer de sous-agent (un sous-agent prend 2-3 minutes par round, la lecture directe ne prend que quelques secondes). Si plus de pages fraîches ou des changements globaux, passer par le sous-agent.
- Si la description d'un finding est vague / en conflit avec le code source et ne peut être localisée → lire l'image
slide_NN_compare.pngde la page individuelle correspondante. - Confirmation avant de déclencher un sticky : lire l'image individuelle.
- Si l'utilisateur donne un retour sur une page spécifique : lire l'image individuelle de cette page.
En dehors de ces cas, ne pas lire les images de comparaison page par page.
Les lots sont optimisés par parallélisation pour réduire le temps d'horloge murale (les sous-agents lisant séquentiellement de grandes images sont la cause principale de latence ; envoyer plusieurs petits lots en parallèle est plus de deux fois plus rapide qu'un grand lot) :
| Nombre de diapositives | Stratégie |
|---|---|
| ≤ 2 | 1 lot |
| 3-20 | 2 pages par lot, tous envoyés en parallèle |
| > 20 | 3 pages par lot (pour limiter le nombre total d'agents) |
Le modèle d'appel complet du sous-agent + liste de vérification + format des findings se trouve dans <out>_audit/audit_prompt.md. Plusieurs appels Agent(...run_in_background: true, subagent_type: "general-purpose") insérés dans le même message de l'agent principal s'exécutent en parallèle.
Le sous-agent ne renvoie que le texte des findings (le mode page inclut des blocs ## page NN pour chaque page cible ; le mode triage pour les lots d'examen détaillé inclut des blocs pour chaque page agrandie et vérifiée), et l'agent principal fusionne le tout et écrit audit_findings.md — les écritures concurrentes se chevaucheraient.
Chaque finding doit mentionner le nom court de l'élément stable, et décrire "l'état réel de la moitié HTML ; la différence de la moitié PPT". Ne rapporter que les problèmes visuels nouveaux ou amplifiés du PPT par rapport au HTML ; les problèmes déjà présents dans la moitié HTML ne sont pas des findings de conversion.
Préparation parallèle avec les sous-agents (obligatoire)
Au lancement des sous-agents de détail (mode page ou Phase 2 du mode triage), utiliser run_in_background: true dans l'appel Agent, et envoyer dans le même message :
Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit slides 1-4", prompt: ...)
Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit slides 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)
Chaque prompt de sous-agent doit inclure directement le chemin absolu des images slide_NN_compare.png de son lot, le chemin du HTML du deck, et le chemin de lessons-learned.md (le champ d'application est décrit ci-dessus dans le chapitre "Mode d'audit visuel") ; ne pas supposer que la sortie des Read / Grep de l'agent principal sera automatiquement transmise au sous-agent.
N'envoyer que les préparations "utilisables quel que soit le finding" — ne pas prédire les findings pour modifier le HTML à l'avance.
Discipline de correction (cibler le finding, pas la cause racine)
Après avoir reçu audit_findings.md, modifier tous les findings de ce tour en une fois, puis relancer convert + audit en bloc — ne pas modifier un finding puis relancer. Un tour = un lot d'éditions HTML + une convert + une audit.
Après avoir reçu les findings :
- Ne pas lire soi-même les images de comparaison (les findings décrivent déjà les symptômes) ; les trois exceptions sont listées ci-dessus dans le chapitre "Distribution d'audit et règles de lecture des images de comparaison"
- Ne pas lire
measure.py/assemble.py/ aucun code du skill pour trouver la cause racine - Ouvrir directement
audited.htmlet appliquer les corrections finding par finding
Pour chaque finding, faire la modification HTML locale minimale :
-
Pour chaque finding, ne modifier que l'endroit qui le fait disparaître, puis passer au finding suivant (continuer à modifier le HTML, ne pas relancer convert)
-
Ne pas chercher la cause profonde de "pourquoi la police a régressé / pourquoi le layout a décalé"
-
Ne pas faire d'optimisations hors liste comme "je vais aussi mettre le .footer en position absolue"
-
Ne pas faire de restructuration entre findings ("déclarer explicitement font-family pour toutes les diapositives" n'est pas une correction minimale)
-
Si un même finding apparaît deux tours consécutifs (le tour précédent + le tour actuel) → sticky déclenché : s'arrêter et en informer l'utilisateur, ne pas étendre le périmètre des modifications. La clé de jugement =
(numéro de page, nom court de l'élément visuel):- La formulation / la sévérité / le changement HIGH↔MID ne réinitialisent pas le jugement. Exemple :
(page 5, taille du take)décrit comme "trop petit" au round 6, puis "gravement insuffisant" au round 7 → même clé sticky, round 7 est déjà sticky. - Seul un
(numéro de page + élément)totalement différent compte comme une nouvelle clé sticky. - Reprise après un tour : si le round 6 apparaît, round 7 disparaît, round 8 réapparaît → pas sticky (l'absence au round 7 est considérée comme problème résolu, round 8 est une nouvelle régression).
- Stické = ne pas corriger ce finding pendant ce tour, le signaler à l'utilisateur comme candidat à la limite du skill, et corriger les autres findings de ce tour.
Mise en œuvre : après avoir fusionné
audit_findings.mdet avant d'appliquer lesEdit, il faut d'abord lireaudit_findings.mddu tour précédent (premier tour absent) et faire une comparaison deux à deux — si une clé apparaît à la fois dans ce tour et le tour précédent, c'est sticky. Les findings sticky sont listés séparément pour que l'utilisateur les juge, et ne sont pas inclus dans la file d'édition de ce tour. - La formulation / la sévérité / le changement HIGH↔MID ne réinitialisent pas le jugement. Exemple :
Après avoir corrigé tous les findings de ce lot, exécuter en une seule fois python convert.py <input>.audited.html --only-slides <numéros de pages modifiées>.
Critère : le nombre de lignes de votre diff ≤ nombre de findings × 3 lignes. Au-delà, cela signifie que vous "dérapez".
Ré-exécution incrémentale (--only-slides)
Utilisée à partir du second tour d'audit ; le premier tour est complet.
python convert.py <input>.audited.html --only-slides 2,7,12
La ré-exécution incrémentale couvre measure / le rendu Stage 5a / les images de comparaison Stage 5b, uniquement pour les pages listées + les pages manquantes dans le cache ; assemble / embed_fonts reste complet. audit_index.json indique incremental_mode: true, fresh_indices, cached_indices, et fresh: true/false pour chaque page.
Les pages cibles de l'audit incrémental sont uniquement les fresh_indices. Le mode page distribue directement ces pages ; le mode triage trie d'abord dans ces pages, puis envoie les pages retenues au sous-agent.
Condition : le répertoire <out>_audit/ du tour précédent doit encore exister. Si le cache est manquant, revenir automatiquement à l'exécution complète ; si le nombre de pages HTML a changé, le détecter automatiquement et revenir à l'exécution complète de measure.
Cas où --only-slides ne peut pas être utilisé (effet visuel débordant des pages listées, faux négatifs de cache) :
- Changement de CSS global (
<style>, sélecteur racine, styles généraux de.slide) - Ajout / suppression de polices (modification de
@import, déclarationfont-family) - Changement de tokens au niveau du deck (fond, couleur de thème, espacement)
- Toute modification de variable globale affectant la mise en page d'autres diapositives
Dans ces cas, exécuter une conversion complète sans flag. En cas de doute, une conversion complète est toujours sûre.
Capitalisation des problèmes HTML et limites OOXML (obligatoire)
Votre rôle est l'appel + la capitalisation de l'utilisation, pas la correction du skill. Si vous rencontrez un bug interne au skill, ne modifiez pas measure.py / assemble.py sur place.
Ne capitalisez que deux catégories :
1. Problèmes d'écriture HTML (le HTML de l'utilisateur fausse la conversion)
| Catégorie | Jugement | Action |
|---|---|---|
| Cas unique (n'apparaît que dans ce deck, une ou deux lignes HTML suffisent à corriger) | Cas particulier d'une page | Corriger directement le HTML source ; ne pas capitaliser, ne pas signaler |
| Anti-patron HTML général (toute personne écrivant du HTML similaire le rencontrera) | Transversal (plusieurs decks) | Corriger le HTML + capitaliser dans la section "Contournements d'écriture HTML" de references/lessons-learned.md |
2. Limites d'expressivité OOXML (PowerPoint / OOXML ne supporte pas naturellement)
La grande majorité des décorations CSS (backdrop-filter / filter / mix-blend-mode / skew / box-shadow / gradient / ::before ::after usage décoratif — content vide + bg-image / box-shadow, etc.) est déjà automatiquement capturée par hasComplexDecoration dans la "stratégie de couverture" via deco_snapshot — le HTML n'a pas besoin d'être modifié. Le ::before ::after avec contenu textuel (content: "↑" etc.) passe par le canal texte, voir references/supported-css.md niveau 1.
Les vraies limites nécessitant un workaround HTML (que le calque texte OOXML ne peut pas exprimer nativement) :
| Limite | Voie alternative |
|---|---|
| Emoji coloré (police COLR/CPAL) | <img> SVG Twemoji, via le canal img intégré |
background-clip: text dégradé de texte | <svg><text fill="url(#grad)"> en ligne, via le canal SVG |
Quand on rencontre ces cas → modifier le HTML pour utiliser la voie alternative + capitaliser dans la section "Limites OOXML" de references/lessons-learned.md.
Si on rencontre un nouveau CSS non supporté ne figurant pas dans le tableau ci-dessus → vérifier d'abord si hasComplexDecoration n'a pas été mal déclenché (ajouter une ligne de condition suffit), plutôt que de modifier le HTML. Voir references/supported-css.md "Méthode standard pour ajouter un nouveau support".
Comment traiter un bug apparent dans le skill (ne pas corriger, ne pas capitaliser)
Si un symptôme se reproduit avec le même motif CSS sur un autre deck et n'est pas dans les limites OOXML connues → c'est une abstraction insuffisante du skill. Ne modifiez pas le code du skill sur place. Faites ces deux choses :
- Pour le deck actuel, appliquer un workaround côté HTML pour corriger le finding, afin que l'utilisateur obtienne un PPT livrable
- Informer clairement l'utilisateur : "J'ai trouvé un bug qui semble générique dans le skill : [symptôme + motif CSS déclencheur + workaround actuel]. Je suggère de le signaler à l'auteur comme une issue, pour que le skill gère ce motif de manière plus générique dans measure/assemble."
Où écrire la capitalisation : copie locale + template amont
references/lessons-learned.md est un fichier de travail local indépendant par utilisateur (gitignored). Lors de la première exécution de convert.py, local_config.seed_lessons_learned() copie automatiquement le template lessons-learned.md.example (committed). Le mécanisme est le même que pour .config.local.toml.
- L'agent lit / capitalise en écrivant dans le
lessons-learned.mdlocal — libre d'ajouter / modifier / réorganiser, sans bruit git. - La copie locale n'est jamais écrasée par l'amont —
git pullrécupère le template.example, ne touche pas votre copie de travail. - Pour remonter une capitalisation vers l'amont : l'auteur copie manuellement l'entrée dans
lessons-learned.md.examplepuis commit ; curation sélective, pas tout pousser. - Écritures spécifiques au local / client particulier → les écrire directement dans la copie locale, pas d'amont.
- Les entrées de lessons n'écrivent que les symptômes réutilisables, les motifs déclencheurs et les règles de contournement ; ne pas écrire de noms de fichiers locaux, de noms de templates, de numéros de page, de noms de clients ou de noms de fichiers source spécifiques. Les détails d'implémentation, les commandes et les détails de code restent dans le commit / l'issue / la documentation principale du skill.
Déclenchement : si on rencontre un anti-patron HTML général ou une limite OOXML → l'ajouter dans le tableau correspondant du lessons-learned.md local. Chaque conversion le relit, effet immédiat.
Stratégie de couverture (en une phrase)
En interne, le skill traduit tout le CSS en quatre niveaux de sortie : texte vectoriel → formes vectorielles → décoration matricielle (deco_snapshot) → média direct. Les couleurs de fond simples / bordures / border-radius passent par les deux premiers niveaux (modifiables et recherchables), tandis que box-shadow / gradient / filter / backdrop-filter / mix-blend-mode / coins asymétriques / conteneurs rognés + éléments tournés, etc., qui déclenchent hasComplexDecoration, passent par le troisième niveau (seuls les pixels de décoration sont capturés, le texte reste toujours vectoriel et dessiné au-dessus de la capture).
Définition complète des niveaux / conditions de déclenchement / guide pour ajouter un nouveau support (priorité vectorielle → capture en dernier recours) → references/supported-css.md.
Pipeline
[1 Reconnaissance d'entrée / pré-scan] → [2 Mesure] → [3 Assemblage] → [4 Embarquement des polices] → [5a Auto-vérification structurée] → [5b Audit visuel]
preflight.py measure.py assemble.py embed_fonts.py self_check.py visual_audit.py
Actions de chaque phase / règles de contre-hypothèse / assertions de sortie / checklist pour nouveau template → references/methodology.md.
Stage 5b produit <out>_audit/ (images de comparaison + planche contact + audit_index.json + audit_prompt.md). Ne pas faire de diff pixel par pixel — les chiffres sont insensibles aux bugs locaux et donnent une fausse confiance ; le jugement visuel suit audit.mode en triage / page / manual. Sans moteur de rendu, 5b est sauté, et on demande à l'utilisateur selon la section "Exigence de moteur de rendu" ci-dessus.
Avant l'appel
…
[truncated for translation]