Image vers PPTX Éditable (port Claude Code)
Utilisez l'exécutable editppt fourni pour décomposer, reconstruire, valider et assembler des diapositives visuelles en .pptx éditables. Les entrées peuvent être une ou plusieurs images, un PDF, ou un PPT/PPTX basé sur une image. La sortie est toujours un fichier .pptx, une diapositive par page d'entrée, dans l'ordre d'entrée.
<racine-de-la-compétence> ci-dessous signifie le répertoire contenant ce SKILL.md.
Organisation de cette compétence
Ce fichier est lu par vous, l'orchestrateur. Le travail au niveau de la page est effectué par les reconstructeurs de page (sous-agents d'arrière-plan, ou vous-même pour une page unique) pilotés par un prompt généré. Chaque règle a un emplacement faisant autorité — suivez le pointeur plutôt que de deviner :
prompts/page-worker.md— modèle de reconstructeur de page : périmètre de propriété, chemin de lecture, ordre d'exécution, sorties requises, format de retour. Rempli parscripts/build-page-worker-prompt.py.references/cli-helper.md— vérification d'installation deeditppt, arbre de commandes, syntaxe. À lire lors du choix d'une commande.references/manifest-schema.md— contrats JSON pour chaque artefact d'exécution/page. À lire lors de l'écriture ou de la validation des fichiers d'exécution/page.references/page-decision-tree.md— ce qui devient arrière-plan vs. actif image vs. texte/forme/tableau natif, utilisation des indices de texte, auto-vérification finale, correction vs. avertissement. Les reconstructeurs de page lisent ceci ; vous en avez rarement besoin.
Correspondance d'exécution Claude Code
La compétence d'origine cible Codex. Les substitutions suivantes s'appliquent partout où les références mentionnent les équivalents Codex.
| Concept (Codex) | Dans Claude Code |
|---|---|
image_gen.imagegen + feuilles d'actifs du modèle d'image | Remplacé par le backend claude-native. Claude peut voir mais pas générer de bitmaps, donc il trace les icônes/illustrations en SVG, conserve les photos comme régions source rectangulaires, et peint localement les bases propres (references/page-decision-tree.md section 2.4). Utilisez toujours prepare avec --image-backend claude-native ; jamais builtin-imagegen. |
API image CLI (editppt image generate/edit) | Mise à niveau optionnelle uniquement, utilisée lorsque editppt doctor --check-api signale un backend prêt et qu'un objet ne correspond à aucune source native. Jamais requis. |
view_image | Read le chemin du fichier image (source.png, text_hints.png, zoom et images .compare.png, preview.png, split_assets_contact.png). |
| Lancer un travailleur de page / sous-agent | Outil Agent, subagent_type: "general-purpose", run_in_background: true, name: "ppt-<page_id>" (ex. ppt-page_003). |
Worker id pour --agent-id | Le même nom que vous avez donné à l'agent (ppt-page_003) ; main pour le mode local mono-page. |
| Attendre les travailleurs | Les agents d'arrière-plan vous informent lorsqu'ils ont terminé. N'interrogez pas en boucle. |
| Envoyer une réparation au travailleur | SendMessage au nom du travailleur, afin qu'il conserve son contexte. |
| Approbation sandbox / réseau | Invites d'autorisation Claude Code. Une exécution claude-native avec des indices RapidOCR locaux n'effectue aucun appel externe. PaddleOCR n'est appelé que lorsqu'un jeton est configuré (editppt prepare / editppt run hints) ; editppt image generate/edit appelle également si la mise à niveau optionnelle est utilisée. |
Contrat d'entrée
Ces règles au niveau de l'orchestrateur sont énoncées une fois ici.
- CLI d'abord.
editpptest un environnement d'exécution requis. Sieditppt --helpéchoue, installez-le à partir de<racine-de-la-compétence>/clien utilisant la vérification pré-exécution dansreferences/cli-helper.md(préférezuv tool install --force --editable <racine-de-la-compétence>/clilorsqueuvexiste, puispipx, puispip --user), puis exécutezeditppt doctor. - État uniquement via le CLI. Commencez par
editppt prepare <entrée...>. Ensuite, avancez chaque transition d'état uniquement via des commandeseditppt; n'écrivez jamais manuellement l'état JSON de l'exécution/de la page. Cela maintient l'exécution déterministe et reprise. - Qui reconstruit les pages. Une exécution avec exactement une page est reconstruite par vous en mode local après que
editppt run dispatch --locall'ait réclamée. Les exécutions multi-pages sont reconstruites par des travailleurs de page d'arrière-plan — un par page. Ne reconstruisez pas vous-même les artefacts multi-pages : chaque page consomme beaucoup de contexte (images, manifestes, boucles de réparation), et les conserver dans des travailleurs séparés est ce qui rend votre contexte d'orchestration utilisable et permet aux pages de s'exécuter en parallèle. - Propriété des artefacts. Vous n'écrivez pas
manifest.json,page.pptx,preview.png,split_assets_contact.png,validation.jsonoupage_result.jsonsauf en mode local mono-page après la réclamation--local. Le mode local suit le même prompt de page, références, sorties et validationrun recordqu'un travailleur. - Backend d'image. Voir "Backend d'image dans Claude Code" ci-dessous. Si aucune source autorisée ne peut reproduire un objet, la page échoue à la validation plutôt que de substituer des formes approximatives ou des rognages d'icônes (
references/page-decision-tree.mdsection 2). - Appels externes autorisés. Une demande de conversion de diapositives en PPT modifiable autorise les appels OCR (et, si configuré, les appels API image) nécessaires à cette conversion, sauf si l'utilisateur demande un traitement local uniquement ou marque l'entrée comme confidentielle. N'envoyez que des images de page locales à la tâche, des prompts, des masques et des images de référence — jamais de fichiers non liés ou d'identifiants. Les points de terminaison tiers sont autorisés uniquement lorsque l'utilisateur les a configurés ou nommés.
- Autonomie. Exécutez la reconstruction de routine, les replis configurés et les réparations locales de page sans portes de confirmation. Arrêtez-vous pour l'utilisateur uniquement pour quelque chose que seul lui peut fournir (une décision de jeton OCR, une entrée manquante). Signalez les blocages concrets plutôt que de demander à l'utilisateur de déboguer.
- Les décisions d'objet suivent
references/page-decision-tree.md; la validation déterministe est une porte de structure et ne supprime jamais une décision de source d'objet. manifest.jsonest la source faisant autorité pour la construction de la page ;run recordvalidepage.pptxpar rapport à celui-ci, etrun finalizereconstruit le jeu à partir des manifestes enregistrés.
Hygiène des identifiants
Les secrets (jeton PaddleOCR, clé API image optionnelle) se retrouvent dans la transcription si l'utilisateur les colle dans le chat. Suggérez à l'utilisateur d'exécuter lui-même la commande de configuration avec le préfixe ! afin que la valeur aille directement au CLI, par exemple :
! editppt config --paddle-ocr-token <jeton>
! editppt config --api-key sk-... --base-url https://api.openai.com/v1 # mise à niveau API image optionnelle
S'ils collent quand même une clé dans le chat, stockez-la avec editppt config et ne la renvoyez jamais en écho ; le CLI la masque dans la sortie. N'écrivez jamais de clés dans le projet, le répertoire d'exécution ou le répertoire de compétence.
Backend d'image dans Claude Code
Claude a la vision mais pas la génération d'images, donc chaque exécution utilise le backend claude-native : editppt prepare <entrée...> --image-backend claude-native. Les reconstructeurs de page choisissent ensuite la source de chaque objet conformément à la section 2.4 de references/page-decision-tree.md :
- Icônes, logos, badges, marques dessinées à la main, illustrations plates — Claude les trace sous forme de SVG (
editppt image zoom, puiseditppt image svg). Le PPTX intègre le SVG réel, donc dans PowerPoint, l'utilisateur peut le recolorer ou utiliser Convertir en forme pour modifier ses chemins individuels. Cela rend ces objets plus éditables que les actifs bitmap de la compétence d'origine. - Photos, captures d'écran, blocs texturés — conservés sous forme de régions source rectangulaires (
editppt image photo-region). Le traçage vectoriel les transformerait en dessins animés. - Arrière-plans complexes derrière le texte reconstruit — nettoyés par inpainting local (
editppt image inpaint).
Ne demandez pas d'API image à l'utilisateur. Si editppt doctor --check-api affiche par hasard un backend prêt (connexion Codex ou une clé configurée), les travailleurs peuvent utiliser editppt image generate/edit comme mise à niveau optionnelle pour les objets qui ne correspondent bien à aucune source native, comme un détourage photographique sur un arrière-plan chargé. Les commandes d'actifs au sein d'une page s'exécutent en série.
Flux de travail
Phase 1 : Préparation
Lisez les exemples de préparation dans references/cli-helper.md et les descriptions des fichiers d'exécution/page dans references/manifest-schema.md.
editppt prepare <entrée...> --image-backend claude-native
Conservez le --out-root par défaut : il crée le répertoire de travail d'exécution output/image-to-editable-ppt/<job-id>/ sous le répertoire courant. Ne le pointez pas vers le dossier où l'utilisateur souhaite le résultat ; ce dossier ne doit recevoir que le jeu final (Phase 4). Après cela, il doit y avoir deck_manifest.json, page_jobs.json, notes_manifest.json, et chaque page doit avoir source.png plus page_request.json.
Prepare écrit également des indices de texte par page (text_hints.json/text_hints.png). Sans jeton, ils proviennent de RapidOCR local, qui lit le texte sur l'appareil sans téléchargement, ne demandez donc rien à l'utilisateur. Uniquement si prepare signale le backend builtin-ink (géométrie seule, RapidOCR indisponible), demandez à l'utilisateur une fois avant de répartir une page : un jeton gratuit de https://aistudio.baidu.com/account/accessToken, stocké avec editppt config --paddle-ocr-token <jeton>, rend les indices conscients du contenu (il lit le texte, pas seulement mesure où il se trouve) et améliore considérablement la fidélité du texte ; editppt run hints <exécution> régénère ensuite les indices de l'exécution en cours. Le quota personnel gratuit est plus que suffisant pour cette compétence. Attendez leur choix ; s'ils refusent, continuez avec des indices hors ligne et ne demandez plus.
Si l'utilisateur demande Indra OCR (ou pour un OCR local plus rapide/alternatif), exécutez editppt config --text-hints-backend indra et réinstallez le CLI avec l'extra [indra] (references/cli-helper.md). Mentionnez une fois que les poids du modèle Indra portent une licence OpenRAIL-M modifiée restreignant certaines utilisations commerciales. Ne passez pas vous-même : RapidOCR a lu le texte des diapositives de manière plus complète lors des tests.
Si un jeton est configuré mais que l'OCR a échoué parce qu'une invite d'autorisation ou un échec réseau l'a bloqué, ce n'est pas le chemin de qualité préféré : faites autoriser l'appel et relancez editppt run hints <exécution> avant la reconstruction de la page. Continuez hors ligne uniquement après que l'utilisateur ait refusé l'OCR, après qu'une tentative d'OCR autorisée ait échoué pour une raison de service réelle, ou lorsque l'utilisateur a demandé un traitement local uniquement.
Phase 2 : Reconstruire ou répartir les pages
Appelez à plusieurs reprises et agissez en fonction du stage retourné :
editppt run next <exécution> --json
stage=rebuild_page_locally (exactement une page). Réclamez-la, puis reconstruisez-la vous-même :
python3 <racine-de-la-compétence>/scripts/build-page-worker-prompt.py <exécution> --page <page_id> --out <chemin-abs-répertoire-exécution>/pages/<page_id>/worker-prompt.mdeditppt run dispatch <exécution> --page <page_id> --agent-id main --prompt-file <chemin-abs-répertoire-exécution>/pages/<page_id>/worker-prompt.md --localReadle prompt généré et suivez-le dans ce répertoire de page, en produisant les mêmes sorties qu'un travailleur.
stage=dispatch_pages. Pour chaque page suggérée, dans cet ordre :
- Construisez le prompt avec le script, comme ci-dessus.
- Lancez le travailleur avec l'outil
Agent—subagent_type: "general-purpose",run_in_background: true,name: "ppt-<page_id>",description: "Reconstruire <page_id> en PPT modifiable", etpromptdéfini sur :Vous êtes un reconstructeur de page pour la compétence image-to-editable-ppt (port Claude Code). Lisez <chemin-abs-répertoire-exécution>/pages/<page_id>/worker-prompt.md et suivez-le exactement. Notes Claude Code : visualisez les images avec l'outil Read ; vous ne pouvez pas générer de bitmaps, donc les visuels non textuels proviennent de la section 2.4 du page-decision-tree.md (traces SVG, régions photo, inpainting local) ; exécutez des commandes shell avec Bash. Ne touchez pas aux fichiers en dehors de votre répertoire de page. - Uniquement après la réussite du lancement :
editppt run dispatch <exécution> --page <page_id> --agent-id ppt-<page_id> --prompt-file <chemin-abs-répertoire-exécution>/pages/<page_id>/worker-prompt.md
Lancez toutes les pages suggérées d'un lot dans un seul message afin qu'elles s'exécutent simultanément. --out et --prompt-file doivent être absolus pour que le répertoire de page ne soit pas préfixé deux fois. Les créneaux de concurrence proviennent de page_jobs.json.max_concurrent_pages (par défaut 6).
stage=wait. Les pages réparties sont des baux actifs, pas des créneaux inactifs. Attendez les notifications d'achèvement. N'arrêtez pas, ne réinitialisez pas et ne remplacez pas un travailleur parce qu'il est lent ou silencieux — les pages complexes prennent légitimement 10 minutes ou plus.
stage=configure_backend. Exécutez editppt run backend <exécution> --mode claude-native plutôt que le builtin-imagegen/contrat CLI suggéré.
Phase 3 : Enregistrement
Lorsque la notification d'achèvement d'un travailleur arrive (ou que vous terminez la page locale) :
editppt run record <exécution> --page <page_id> --agent-id <id>
Ceci valide page.pptx par rapport à manifest.json et rejette la page si les objets positionnés manquent de coordonnées de pixel source, le manifeste ne peut pas reconstruire la page de manière indépendante, ou validation.json manque de passed: true au niveau supérieur. Ensuite, revenez à editppt run next.
Réparations. Si l'enregistrement échoue, lisez les preuves d'échec et demandez au propriétaire de la page de ne réparer que les artefacts affectés, de revalider (editppt page validate, voir references/cli-helper.md), et d'enregistrer à nouveau. En mode multi-pages, SendMessage les preuves au travailleur existant (ppt-<page_id>) plutôt que d'en lancer un nouveau — il détient déjà le contexte de la page et ses actifs vérifiés. Ne régénérez pas les actifs conformes pour corriger une erreur de manifeste ou de tableau non liée.
Réinitialisation uniquement lorsqu'une page nécessite une nouvelle exécution : le travailleur s'est terminé dans un état d'échec terminal, l'utilisateur a annulé, ou des tentatives de joignabilité répétées ne montrent aucun progrès local de la page. Lent n'est pas perdu. Après avoir corrigé ce qui l'a bloqué :
editppt run reset <exécution> --page <page_id> --agent-id <id> --confirm-lost
La réinitialisation remet la page à en attente ; reprenez la Phase 2 avec un nouveau prompt et un nouveau travailleur. Les artefacts existants sont conservés à des fins de provenance et de réutilisation sélective.
Ne réessayez qu'après avoir modifié une entrée ou une condition — ne répétez jamais un appel défaillant identique. Si un prérequis réel est manquant, préservez la progression et signalez le blocage concret. Une fois que les sorties passent leurs vérifications, passez à autre chose ; ne répétez pas une QA visuelle inchangée.
Phase 4 : Finalisation
Lorsque run next retourne l'étape de finalisation :
editppt run finalize <exécution>
Finalize reconstruit le jeu à partir de chaque pages/page_NNN/manifest.json enregistré dans l'ordre des pages, copie les notes du présentateur .pptx inchangées, et valide le résultat : package valide, nombre de diapositives = nombre de pages d'entrée, pagination PDF/PPTX correcte.