bowen31337/image-to-editable-ppt

Imagen a PPT Editable (Port para Claude Code)

Utiliza el runtime editppt incluido para descomponer, reconstruir, validar y ensamblar diapositivas visuales como .pptx editable. Las entradas pueden ser una o más imágenes, un PDF o un PPT/PPTX basado en imágenes. La salida es siempre un único .pptx, una diapositiva por página de entrada, en el orden de entrada.

<skill-root> a continuación se refiere al directorio que contiene este SKILL.md.

Cómo está organizada esta habilidad

Este archivo es leído por ti, el orquestador. El trabajo a nivel de página lo realizan los reconstructores de página (subagentes en segundo plano, o tú mismo para una sola página) guiados por una indicación generada. Cada regla tiene un único hogar autorizado — sigue el puntero en lugar de adivinar:

• prompts/page-worker.md — plantilla del reconstructor de página: límite de propiedad, ruta de lectura, orden de ejecución, salidas requeridas, formato de retorno. Rellenado por scripts/build-page-worker-prompt.py.
• references/cli-helper.md — verificación de instalación de editppt, árbol de comandos, sintaxis. Léelo al elegir un comando.
• references/manifest-schema.md — contratos JSON para cada artefacto de ejecución/página. Léelo al escribir o validar archivos de ejecución/página.
• references/page-decision-tree.md — qué se convierte en fondo vs. activo de imagen vs. texto/forma/tabla nativos, uso de sugerencias de texto, auto-verificación final, corrección vs. advertencia. Los reconstructores de página lo leen; rara vez lo necesitas.

Mapeo del runtime de Claude Code

La habilidad original está diseñada para Codex. Estas son las sustituciones que la hacen funcionar aquí; se aplican en todas partes donde las referencias mencionen los equivalentes de Codex.

Concepto de CodeX (original)	En Claude Code
image_gen.imagegen integrado + hojas de activos de modelo de imagen	Reemplazado por el backend claude-native. Claude puede ver pero no generar mapas de bits, por lo que traza iconos/ilustraciones como SVG, mantiene las fotos como regiones de origen rectangulares y rellena fondos limpios localmente (references/page-decision-tree.md sección 2.4). Siempre prepare con --image-backend claude-native; nunca builtin-imagegen.
API de imagen CLI (editppt image generate/edit)	Mejora opcional solamente, utilizada cuando editppt doctor --check-api informa un backend listo y un objeto no encaja en ninguna fuente nativa. Nunca es obligatorio.
view_image	Read la ruta del archivo de imagen (source.png, text_hints.png, imágenes de zoom y .compare.png, preview.png, split_assets_contact.png).
Generar un trabajador de página / subagente	Herramienta Agent, subagent_type: "general-purpose", run_in_background: true, name: "ppt-<page_id>" (ej. ppt-page_003).
Worker id para --agent-id	El mismo nombre que le diste al agente (ppt-page_003); main para modo local de una sola página.
Esperar a los trabajadores	Los agentes en segundo plano te notifican cuando terminan. No hagas polling en un bucle.
Enviar una reparación al trabajador	SendMessage al nombre del trabajador, para que mantenga su contexto.
Aprobación de red / sandbox	Indicaciones de permiso de Claude Code. Una ejecución nativa de Claude con sugerencias locales de RapidOCR no realiza ninguna llamada externa. PaddleOCR se llama solo cuando se configura un token (editppt prepare / editppt run hints); editppt image generate/edit también realiza llamadas si se utiliza la mejora opcional.

Contrato de entrada

Estas reglas a nivel de orquestador se indican una vez aquí.

• CLI primero. editppt es un runtime obligatorio. Si editppt --help falla, instálalo desde <skill-root>/cli usando la Verificación Previa a la Ejecución en references/cli-helper.md (prefiere uv tool install --force --editable <skill-root>/cli cuando exista uv, luego pipx, luego pip --user), luego ejecuta editppt doctor.
• Estado solo a través de la CLI. Comienza con editppt prepare <input...>. Después, avanza cada transición de estado solo a través de comandos editppt; nunca escribas manualmente el estado JSON de ejecución/página. Esto mantiene la ejecución determinista y reanudable.
• Quién reconstruye las páginas. Una ejecución con exactamente una página es reconstruida por ti en modo local después de que editppt run dispatch --local la reclame. Las ejecuciones de varias páginas son reconstruidas por trabajadores de página en segundo plano — uno por página. No reconstruyas artefactos de varias páginas tú mismo: cada página consume mucho contexto (imágenes, manifiestos, bucles de reparación), y mantenerlos en trabajadores separados es lo que mantiene tu contexto de orquestación utilizable y permite que las páginas se ejecuten en paralelo.
• Propiedad de los artefactos. No escribes manifest.json, page.pptx, preview.png, split_assets_contact.png, validation.json, o page_result.json excepto en modo local de una sola página después del reclamo --local. El modo local sigue la misma indicación de página, referencias, salidas y validación de run record que un trabajador.
• Backend de imagen. Consulta "Backend de imagen en Claude Code" a continuación. Si ninguna fuente permitida puede reproducir un objeto, la página falla la validación en lugar de sustituir formas aproximadas o recortes de iconos (references/page-decision-tree.md sección 2).
• Llamadas externas autorizadas. Una solicitud para convertir diapositivas en PPT editable autoriza las llamadas de OCR (y, si está configurada, las llamadas a la API de imagen) necesarias para esa conversión, a menos que el usuario solicite procesamiento solo local o marque la entrada como confidencial. Envía solo imágenes de página locales a la tarea, indicaciones, máscaras e imágenes de referencia — nunca archivos o credenciales no relacionados. Se permiten endpoints de terceros solo cuando el usuario los configuró o nombró.
• Autonomía. Ejecuta la reconstrucción rutinaria, las alternativas configuradas y las reparaciones locales de la página sin puertas de confirmación. Detente para el usuario solo para algo que solo él puede proporcionar (una decisión sobre un token de OCR, una entrada faltante). Informa bloqueadores concretos en lugar de pedir al usuario que depure.
• Decisiones de objetos siguen references/page-decision-tree.md; la validación determinista es una puerta de estructura y nunca renuncia a una decisión de fuente de objeto.
• manifest.json es la fuente autorizada de construcción de la página; run record valida page.pptx contra él, y run finalize reconstruye la presentación a partir de los manifiestos registrados.

Higiene de credenciales

Los secretos (token de PaddleOCR, clave de API de imagen opcional) terminan en la transcripción si el usuario los pega en el chat. Sugiere al usuario que ejecute el comando de configuración él mismo con el prefijo ! para que el valor vaya directamente a la CLI, por ejemplo:

! editppt config --paddle-ocr-token <token>
! editppt config --api-key sk-... --base-url https://api.openai.com/v1   # mejora opcional de API de imagen

Si pegan una clave en el chat de todos modos, guárdala con editppt config y nunca la repitas; la CLI la enmascara en la salida. Nunca escribas claves en el proyecto, el directorio de ejecución o el directorio de la habilidad.

Backend de imagen en Claude Code

Claude tiene visión pero no generación de imágenes, por lo que cada ejecución utiliza el backend claude-native: editppt prepare <input...> --image-backend claude-native. Los reconstructores de página luego eligen la fuente de cada objeto según references/page-decision-tree.md sección 2.4:

• Iconos, logotipos, insignias, marcas dibujadas a mano, ilustraciones planas — Claude los traza como SVG (editppt image zoom, luego editppt image svg). El PPTX incrusta el SVG real, por lo que en PowerPoint el usuario puede cambiarle el color o usar Convertir en forma para editar sus trazados individuales. Esto hace que estos objetos sean más editables que los activos de mapa de bits de la habilidad original.
• Fotos, capturas de pantalla, bloques texturizados — se mantienen como regiones de origen rectangulares (editppt image photo-region). El trazado vectorial los convertiría en dibujos animados.
• Fondos complejos detrás de texto reconstruido — se limpian mediante inpainting local (editppt image inpaint).

No le pidas al usuario una API de imagen. Si editppt doctor --check-api muestra un backend listo (inicio de sesión de Codex o una clave configurada), los trabajadores pueden usar editppt image generate/edit como una mejora opcional para objetos que no encajan bien en ninguna fuente nativa, como un recorte fotográfico sobre un fondo ocupado. Los comandos de activos dentro de una página se ejecutan en serie.

Flujo de trabajo

Fase 1: Preparación

Lee los ejemplos de preparación en references/cli-helper.md y las descripciones de archivos de ejecución/página en references/manifest-schema.md.

editppt prepare <input...> --image-backend claude-native

Mantén el --out-root predeterminado: crea el directorio de trabajo de ejecución output/image-to-editable-ppt/<job-id>/ en el directorio actual. No lo apuntes a la carpeta donde el usuario quiere el resultado; esa carpeta debe recibir solo la presentación final (Fase 4). Después de esto, deben existir deck_manifest.json, page_jobs.json, notes_manifest.json, y cada página debe tener source.png más page_request.json.

Prepare también escribe sugerencias de texto por página (text_hints.json/text_hints.png). Sin token, provienen de RapidOCR local, que lee el texto en el dispositivo sin carga, así que no le pidas nada al usuario. Solo si prepare informa el backend builtin-ink solo de geometría (RapidOCR no disponible) debes preguntarle al usuario una vez antes de despachar cualquier página: un token gratuito de https://aistudio.baidu.com/account/accessToken, almacenado con editppt config --paddle-ocr-token <token>, hace que las sugerencias tengan en cuenta el contenido (lee el texto, no solo mide dónde está) y mejora notablemente la fidelidad del texto; editppt run hints <run> luego regenera las sugerencias de la ejecución actual en su lugar. La cuota personal gratuita es más que suficiente para esta habilidad. Espera su decisión; si se niega, continúa con sugerencias sin conexión y no preguntes de nuevo.

Si el usuario solicita Indra OCR (o un OCR local más rápido/alternativo), ejecuta editppt config --text-hints-backend indra y reinstala la CLI con el extra [indra] (references/cli-helper.md). Menciona una vez que los pesos del modelo de Indra conllevan una licencia OpenRAIL-M modificada que restringe algunos usos comerciales. No cambies a él por tu cuenta: RapidOCR leyó el texto de las diapositivas de manera más completa en las pruebas.

Si hay un token configurado pero OCR retrocedió debido a un mensaje de permiso o una falla de red, esa no es la ruta de calidad preferida: haz que la llamada esté permitida y vuelve a ejecutar editppt run hints <run> antes de la reconstrucción de la página. Continúa sin conexión solo después de que el usuario rechace OCR, después de que un intento de OCR permitido falle por una razón real del servicio, o cuando el usuario haya solicitado un manejo solo local.

Fase 2: Reconstruir o despachar páginas

Llama repetidamente y actúa sobre el stage devuelto:

editppt run next <run> --json

stage=rebuild_page_locally (exactamente una página). Reclámala, luego reconstruyela tú mismo:

1. python3 <skill-root>/scripts/build-page-worker-prompt.py <run> --page <page_id> --out <abs-run-dir>/pages/<page_id>/worker-prompt.md
2. editppt run dispatch <run> --page <page_id> --agent-id main --prompt-file <abs-run-dir>/pages/<page_id>/worker-prompt.md --local
3. Read la indicación generada y síguela dentro de ese directorio de página, produciendo las mismas salidas que haría un trabajador.

stage=dispatch_pages. Para cada página sugerida, en este orden:

1. Construye la indicación con el script, como se indicó anteriormente.
2. Genera el trabajador con la herramienta Agent — subagent_type: "general-purpose", run_in_background: true, name: "ppt-<page_id>", description: "Reconstruir <page_id> como PPT editable", y prompt configurado en:

   Eres un reconstructor de páginas para la habilidad image-to-editable-ppt (port para Claude Code).
   Lee <abs-run-dir>/pages/<page_id>/worker-prompt.md y síguelo exactamente.
   Notas de Claude Code: ve las imágenes con la herramienta Read; no puedes generar
   mapas de bits, por lo que los elementos visuales que no son texto provienen de page-decision-tree.md sección 2.4
   (trazados SVG, regiones de foto, inpainting local); ejecuta comandos de shell con Bash.
   No toques archivos fuera del directorio de tu página.
   

3. Solo después de que la generación haya tenido éxito: editppt run dispatch <run> --page <page_id> --agent-id ppt-<page_id> --prompt-file <abs-run-dir>/pages/<page_id>/worker-prompt.md

Genera todas las páginas sugeridas de un lote en un solo mensaje para que se ejecuten simultáneamente. --out y --prompt-file deben ser absolutos para que el directorio de la página no se anteponga dos veces. Los espacios de concurrencia provienen de page_jobs.json.max_concurrent_pages (valor predeterminado 6).

stage=wait. Las páginas despachadas son concesiones activas, no espacios inactivos. Espera las notificaciones de finalización. No detengas, reinicies o reemplaces a un trabajador porque sea lento o silencioso — las páginas complejas legítimamente toman más de 10 minutos.

stage=configure_backend. Ejecuta editppt run backend <run> --mode claude-native en lugar del builtin-imagegen/contrato CLI sugerido.

Fase 3: Registro

Cuando llegue la notificación de finalización de un trabajador (o termines la página local):

editppt run record <run> --page <page_id> --agent-id <id>

Esto valida page.pptx contra manifest.json y rechaza la página si a los objetos posicionados les faltan coordenadas de píxeles de origen, el manifiesto no puede reconstruir la página de forma independiente, o validation.json carece de passed: true en el nivel superior. Luego vuelve a editppt run next.

Reparaciones. Si record falla, lee la evidencia de la falla y haz que el propietario de la página repare solo los artefactos afectados, vuelva a validar (editppt page validate, consulta references/cli-helper.md), y registre de nuevo. En modo de varias páginas, SendMessage la evidencia al trabajador existente (ppt-<page_id>) en lugar de generar uno nuevo — ya tiene el contexto de la página y sus activos verificados. No regeneres activos que cumplen para corregir un error de manifiesto o tabla no relacionado.

Reinicia solo cuando una página necesite una ejecución nueva: el trabajador terminó en un estado fallido terminal, el usuario canceló, o los intentos repetidos de alcanzabilidad no muestran progreso local de la página. Lento no es perdido. Después de solucionar lo que lo bloqueó:

editppt run reset <run> --page <page_id> --agent-id <id> --confirm-lost

Reset devuelve la página a pending; reanuda la Fase 2 con una nueva indicación y trabajador. Los artefactos existentes permanecen para procedencia y reutilización selectiva.

Reintenta solo después de cambiar una entrada o condición — nunca repitas una llamada fallida idéntica. Si falta un requisito previo real, preserva el progreso e informa el bloqueador concreto. Una vez que las salidas pasan sus verificaciones, continúa; no repitas el control de calidad visual sin cambios.

Fase 4: Finalización

Cuando run next devuelva la etapa de finalización:

editppt run finalize <run>

Finalize reconstruye la presentación a partir de cada pages/page_NNN/manifest.json registrado en orden de página, copia las notas del orador .pptx sin cambios, y valida el resultado: paquete válido, número de diapositivas = número de páginas de entrada, paginación correcta de PDF/PPTX