David-Li0406/meta-skill-evloving

Creación, edición y análisis de documentos DOCX

Resumen

Un usuario puede pedirte que crees, edites o analices el contenido de un archivo .docx. Un archivo .docx es esencialmente un archivo ZIP que contiene archivos XML y otros recursos que puedes leer o editar. Dispones de diferentes herramientas y flujos de trabajo para distintas tareas.

Árbol de decisión de flujos de trabajo

Lectura/Análisis de contenido

Usa las secciones "Extracción de texto" o "Acceso XML sin procesar" a continuación

Creación de un nuevo documento

Usa el flujo de trabajo "Creación de un nuevo documento de Word"

Edición de un documento existente

• Documento propio + cambios simples Usa el flujo de trabajo "Edición OOXML básica"

• Documento de otra persona Usa el "Flujo de trabajo de redlining" (recomendado por defecto)

• Documentos legales, académicos, comerciales o gubernamentales Usa el "Flujo de trabajo de redlining" (obligatorio)

Lectura y análisis de contenido

Extracción de texto

Si solo necesitas leer el contenido textual de un documento, debes convertirlo a markdown usando pandoc. Pandoc proporciona un excelente soporte para preservar la estructura del documento y puede mostrar cambios controlados:

# Convertir documento a markdown con cambios controlados
pandoc --track-changes=all ruta-al-archivo.docx -o salida.md
# Opciones: --track-changes=accept/reject/all

Acceso XML sin procesar

Necesitas acceso XML sin procesar para: comentarios, formato complejo, estructura del documento, medios incrustados y metadatos. Para cualquiera de estas funcionalidades, deberás desempaquetar un documento y leer su contenido XML sin procesar.

Desempaquetar un archivo

python ooxml/scripts/unpack.py <archivo_oficina> <directorio_salida>

Estructuras clave de archivos

• word/document.xml - Contenido principal del documento
• word/comments.xml - Comentarios referenciados en document.xml
• word/media/ - Imágenes y archivos multimedia incrustados
• Los cambios controlados usan etiquetas <w:ins> (inserciones) y <w:del> (eliminaciones)

Creación de un nuevo documento de Word

Al crear un nuevo documento de Word desde cero, usa docx-js, que te permite crear documentos de Word usando JavaScript/TypeScript.

Flujo de trabajo

1. OBLIGATORIO - LEER ARCHIVO COMPLETO: Lee docx-js.md (~500 líneas) completamente de principio a fin. NUNCA establezcas límites de rango al leer este archivo. Lee el contenido completo del archivo para obtener la sintaxis detallada, las reglas de formato críticas y las mejores prácticas antes de proceder con la creación del documento.
2. Crea un archivo JavaScript/TypeScript usando los componentes Document, Paragraph, TextRun (Puedes asumir que todas las dependencias están instaladas, pero si no, consulta la sección de dependencias más abajo)
3. Exporta como .docx usando Packer.toBuffer()

Edición de un documento de Word existente

Al editar un documento de Word existente, usa la Biblioteca de Documentos (una biblioteca de Python para manipulación OOXML). La biblioteca maneja automáticamente la configuración de infraestructura y proporciona métodos para la manipulación de documentos. Para escenarios complejos, puedes acceder al DOM subyacente directamente a través de la biblioteca.

Flujo de trabajo

1. OBLIGATORIO - LEER ARCHIVO COMPLETO: Lee ooxml.md (~600 líneas) completamente de principio a fin. NUNCA establezcas límites de rango al leer este archivo. Lee el contenido completo del archivo para obtener la API de la Biblioteca de Documentos y los patrones XML para editar archivos de documento directamente.
2. Desempaqueta el documento: python ooxml/scripts/unpack.py <archivo_oficina> <directorio_salida>
3. Crea y ejecuta un script de Python usando la Biblioteca de Documentos (consulta la sección "Biblioteca de Documentos" en ooxml.md)
4. Empaqueta el documento final: python ooxml/scripts/pack.py <directorio_entrada> <archivo_oficina>

La Biblioteca de Documentos proporciona tanto métodos de alto nivel para operaciones comunes como acceso directo al DOM para escenarios complejos.

Flujo de trabajo de redlining para revisión de documentos

Este flujo de trabajo te permite planificar cambios controlados exhaustivos usando markdown antes de implementarlos en OOXML. CRÍTICO: Para cambios controlados completos, debes implementar TODOS los cambios de forma sistemática.

Estrategia de lotes: Agrupa los cambios relacionados en lotes de 3 a 10 cambios. Esto hace que la depuración sea manejable mientras se mantiene la eficiencia. Prueba cada lote antes de pasar al siguiente.

Principio: Ediciones mínimas y precisas Al implementar cambios controlados, solo marca el texto que realmente cambia. Repetir texto sin cambios hace que las ediciones sean más difíciles de revisar y parece poco profesional. Divide los reemplazos en: [texto sin cambios] + [eliminación] + [inserción] + [texto sin cambios]. Preserva el RSID del fragmento original para texto sin cambios extrayendo el elemento <w:r> del original y reutilizándolo.

Ejemplo: Cambiar "30 días" a "60 días" en una oración:

# MAL - Reemplaza toda la oración
'<w:del><w:r><w:delText>El plazo es de 30 días.</w:delText></w:r></w:del><w:ins><w:r><w:t>El plazo es de 60 días.</w:t></w:r></w:ins>'

# BIEN - Solo marca lo que cambió, preserva <w:r> original para texto sin cambios
'<w:r w:rsidR="00AB12CD"><w:t>El plazo es de </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> días.</w:t></w:r>'

Flujo de trabajo de cambios controlados

1. Obtén representación markdown: Convierte el documento a markdown con cambios controlados preservados:

   pandoc --track-changes=all ruta-al-archivo.docx -o actual.md
   

2. Identifica y agrupa cambios: Revisa el documento e identifica TODOS los cambios necesarios, organizándolos en lotes lógicos:

   Métodos de ubicación (para encontrar cambios en XML):

   • Números de sección/encabezado (ej., "Sección 3.2", "Artículo IV")
   • Identificadores de párrafo si están numerados
   • Patrones de grep con texto circundante único
   • Estructura del documento (ej., "primer párrafo", "bloque de firma")
   • NO uses números de línea de markdown - no se corresponden con la estructura XML

   Organización de lotes (agrupa 3-10 cambios relacionados por lote):

   • Por sección: "Lote 1: Modificaciones de la Sección 2", "Lote 2: Actualizaciones de la Sección 5"
   • Por tipo: "Lote 1: Correcciones de fechas", "Lote 2: Cambios de nombres de partes"
   • Por complejidad: Comienza con reemplazos de texto simples, luego aborda cambios estructurales complejos
   • Secuencial: "Lote 1: Páginas 1-3", "Lote 2: Páginas 4-6"

3. Lee la documentación y desempaqueta:

   • OBLIGATORIO - LEER ARCHIVO COMPLETO: Lee ooxml.md (~600 líneas) completamente de principio a fin. NUNCA establezcas límites de rango al leer este archivo. Presta especial atención a las secciones "Biblioteca de Documentos" y "Patrones de Cambios Controlados".
   • Desempaqueta el documento: python ooxml/scripts/unpack.py <archivo.docx> <directorio>
   • Toma nota del RSID sugerido: El script de desempaquetado sugerirá un RSID para usar en tus cambios controlados. Copia este RSID para usarlo en el paso 4b.

4. Implementa cambios en lotes: Agrupa los cambios de forma lógica (por sección, por tipo o por proximidad) e impleméntalos juntos en un solo script. Este enfoque:

   • Facilita la depuración (lote más pequeño = más fácil aislar errores)
   • Permite un progreso incremental
   • Mantiene la eficiencia (el tamaño de lote de 3-10 cambios funciona bien)

   Agrupaciones de lotes sugeridas:

   • Por sección del documento (ej., "Cambios en la Sección 3", "Definiciones", "Cláusula de rescisión")
   • Por tipo de cambio (ej., "Cambios de fechas", "Actualizaciones de nombres de partes", "Reemplazos de términos legales")
   • Por proximidad (ej., "Cambios en las páginas 1-3", "Cambios en la primera mitad del documento")

   Para cada lote de cambios relacionados:

   a. Mapea texto a XML: Usa grep en word/document.xml para verificar cómo se divide el texto entre los elementos <w:r>.

   b. Crea y ejecuta script: Usa get_node para encontrar nodos, implementa cambios, luego doc.save(). Consulta la sección "Biblioteca de Documentos" en ooxml.md para patrones.

   Nota: Siempre haz grep en word/document.xml inmediatamente antes de escribir un script para obtener los números de línea actuales y verificar el contenido del texto. Los números de línea cambian después de cada ejecución de script.

5. Empaqueta el documento: Después de completar todos los lotes, convierte el directorio desempaquetado de nuevo a .docx:

   python ooxml/scripts/pack.py desempaquetado documento-revisado.docx
   

6. Verificación final: Haz una comprobación exhaustiva del documento completo:

   • Convierte el documento final a markdown:

     pandoc --track-changes=all documento-revisado.docx -o verificacion.md
     

   • Verifica que TODOS los cambios se aplicaron correctamente:

     grep "frase original" verificacion.md  # NO debería encontrarla
     grep "frase de reemplazo" verificacion.md  # Debería encontrarla
     

   • Verifica que no se hayan introducido cambios no deseados

Conversión de documentos a imágenes

Para analizar visualmente documentos de Word, conviértelos a imágenes mediante un proceso de dos pasos:

1. Convierte DOCX a PDF:

   soffice --headless --convert-to pdf documento.docx
   

2. Convierte páginas PDF a imágenes JPEG:

   pdftoppm -jpeg -r 150 documento.pdf pagina
   

   Esto crea archivos como pagina-1.jpg, pagina-2.jpg, etc.

Opciones:

• -r 150: Establece la resolución a 150 DPI (ajusta para equilibrar calidad/tamaño)
• -jpeg: Formato de salida JPEG (usa -png para PNG si se prefiere)
• -f N: Primera página a convertir (ej., -f 2 comienza desde la página 2)
• -l N: Última página a convertir (ej., -l 5 se detiene en la página 5)
• pagina: Prefijo para los archivos de salida

Ejemplo para un rango específico:

pdftoppm -jpeg -r 150 -f 2 -l 5 documento.pdf pagina  # Convierte solo las páginas 2-5

Directrices de estilo de código

IMPORTANTE: Al generar código para operaciones DOCX:

• Escribe código conciso
• Evita nombres de variables verbosos y operaciones redundantes
• Evita declaraciones print innecesarias

Dependencias

Dependencias requeridas (instalar si no están disponibles):

• pandoc: sudo apt-get install pandoc (para extracción de texto)
• docx: npm install -g docx (para crear nuevos documentos)
• LibreOffice: sudo apt-get install libreoffice (para conversión a PDF)
• Poppler: sudo apt-get install poppler-utils (para pdftoppm, que convierte PDF a imágenes)
• defusedxml: pip install defusedxml (para análisis seguro de XML)