Communitygithub.com

Criação, edição e análise de DOCX

Uma coleção de habilidades personalizadas para agentes de IA no ecossistema Google Antigravity e de habilidades abertas para agentes.

O que é Criação, edição e análise de DOCX?

Esta habilidade capacita agentes de IA a criar, editar e analisar documentos .docx programaticamente. A habilidade explica que arquivos .docx são arquivos ZIP contendo XML, e fornece métodos para leitura (via ferramentas como `markitdown` ou descompactação para XML bruto), criação (usando a biblioteca JavaScript `docx-js`) e edição (descompactar, editar XML e recompactar). Ela inclui regras críticas para `docx-js`, como configurar explicitamente o tamanho da página (o padrão é A4, não US Letter), usar `WidthType.DXA` para larguras de tabela em vez de porcentagens (que quebram no Google Docs), e usar `LevelFormat.BULLET` com configuração de numeração para listas em vez de caracteres Unicode. A habilidade também cobre validação de documentos, formatação profissional (tipografia com aspas curvas, estilos de parágrafo, cabeçalhos/rodapés, quebras de página, hiperlinks, notas de rodapé, paradas de tabulação, layouts de múltiplas colunas e sumários) e a aceitação de alterações controladas. É compatível com ambientes bash e JavaScript e se destina a plataformas como Claude Code, Cursor e Codex. O resumo enfatiza práticas recomendadas para evitar erros comuns, como itálico em parágrafos quebrados ou renderização incorreta de tabelas.

Funciona com✓Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add hankunpeng/skills

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Criação, edição e análise de DOCX faz?

Visão geral

Um arquivo .docx é um arquivo ZIP contendo arquivos XML.

Referência rápida

TarefaAbordagem
Ler/analisar conteúdomarkitdown ou descompactar para XML bruto
Criar novo documentoUse docx-js - veja Criando Novos Documentos abaixo
Editar documento existenteDescompactar → editar XML → recompactar - veja Editando Documentos Existentes abaixo

Leitura de conteúdo

# Extração de texto
markitdown documento.docx > output.md

# Acesso XML bruto
python scripts/office/unpack.py documento.docx descompactado/

Aceitando alterações controladas

Para produzir um documento limpo com todas as alterações controladas aceitas:

python scripts/accept_changes.py entrada.docx saida.docx

Criando Novos Documentos

Gere arquivos .docx com JavaScript, depois valide. Instale: npm install -g docx

Configuração

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
        Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
        InternalHyperlink, Bookmark, FootnoteReferenceRun, PositionalTab,
        PositionalTabAlignment, PositionalTabRelativeTo, PositionalTabLeader,
        TabStopType, TabStopPosition, Column, SectionType,
        TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,
        VerticalAlign, PageNumber, PageBreak } = require('docx');

const doc = new Document({ sections: [{ children: [/* conteúdo */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));

Validação

Após criar o arquivo, valide-o. Se a validação falhar, descompacte, corrija o XML e recompacte.

python scripts/office/validate.py doc.docx

Tamanho da página

// CRÍTICO: docx-js usa A4 como padrão, não US Letter
// Sempre defina o tamanho da página explicitamente para resultados consistentes
sections: [{
  properties: {
    page: {
      size: {
        width: 12240,   // 8,5 polegadas em DXA
        height: 15840   // 11 polegadas em DXA
      },
      margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // margens de 1 polegada
    }
  },
  children: [/* conteúdo */]
}]

Tamanhos de página comuns (unidades DXA, 1440 DXA = 1 polegada):

PapelLarguraAlturaLargura do conteúdo (margens de 1")
US Letter12.24015.8409.360
A4 (padrão)11.90616.8389.026

Orientação paisagem: docx-js troca largura/altura internamente, então passe as dimensões de retrato e deixe-o lidar com a troca:

size: {
  width: 12240,   // Passe o lado CURTO como largura
  height: 15840,  // Passe o lado LONGO como altura
  orientation: PageOrientation.LANDSCAPE  // docx-js os troca no XML
},
// Largura do conteúdo = 15840 - margem esquerda - margem direita (usa o lado longo)

Estilos (Substituir cabeçalhos internos)

Use Arial como fonte padrão (suportada universalmente). Mantenha títulos em preto para legibilidade.

const doc = new Document({
  styles: {
    default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt padrão
    paragraphStyles: [
      // IMPORTANTE: Use IDs exatos para substituir estilos internos
      { id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal", quickFormat: true,
        run: { size: 32, bold: true, font: "Arial" },
        paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // outlineLevel obrigatório para TOC
      { id: "Heading2", name: "Heading 2", basedOn: "Normal", next: "Normal", quickFormat: true,
        run: { size: 28, bold: true, font: "Arial" },
        paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 } },
    ]
  },
  sections: [{
    children: [
      new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Título")] }),
    ]
  }]
});

Listas (NUNCA use marcadores Unicode)

// ❌ ERRADO - nunca insira manualmente caracteres de marcador
new Paragraph({ children: [new TextRun("• Item")] })  // RUIM
new Paragraph({ children: [new TextRun("\u2022 Item")] })  // RUIM

// ✅ CORRETO - use configuração de numeração com LevelFormat.BULLET
const doc = new Document({
  numbering: {
    config: [
      { reference: "bullets",
        levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
      { reference: "numbers",
        levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
    ]
  },
  sections: [{
    children: [
      new Paragraph({ numbering: { reference: "bullets", level: 0 },
        children: [new TextRun("Item com marcador")] }),
      new Paragraph({ numbering: { reference: "numbers", level: 0 },
        children: [new TextRun("Item numerado")] }),
    ]
  }]
});

// ⚠️ Cada referência cria numeração INDEPENDENTE
// Mesma referência = continua (1,2,3 então 4,5,6)
// Referência diferente = reinicia (1,2,3 então 1,2,3)

Tabelas

CRÍTICO: Tabelas precisam de larguras duplas - defina tanto columnWidths na tabela quanto width em cada célula. Sem ambos, as tabelas renderizam incorretamente em algumas plataformas.

// CRÍTICO: Sempre defina a largura da tabela para renderização consistente
// CRÍTICO: Use ShadingType.CLEAR (não SOLID) para evitar fundos pretos
const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
const borders = { top: border, bottom: border, left: border, right: border };

new Table({
  width: { size: 9360, type: WidthType.DXA }, // Sempre use DXA (porcentagens quebram no Google Docs)
  columnWidths: [4680, 4680], // Devem somar à largura da tabela (DXA: 1440 = 1 polegada)
  rows: [
    new TableRow({
      children: [
        new TableCell({
          borders,
          width: { size: 4680, type: WidthType.DXA }, // Também defina em cada célula
          shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR não SOLID
          margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Preenchimento da célula (interno, não adiciona à largura)
          children: [new Paragraph({ children: [new TextRun("Célula")] })]
        })
      ]
    })
  ]
})

Cálculo da largura da tabela:

Sempre use WidthType.DXA — WidthType.PERCENTAGE quebra no Google Docs.

// Largura da tabela = soma de columnWidths = largura do conteúdo
// US Letter com margens de 1": 12240 - 2880 = 9360 DXA
width: { size: 9360, type: WidthType.DXA },
columnWidths: [7000, 2360]  // Devem somar à largura da tabela

Regras de largura:

  • Sempre use WidthType.DXA — nunca WidthType.PERCENTAGE (incompatível com Google Docs)
  • A largura da tabela deve ser igual à soma de columnWidths
  • A width da célula deve corresponder à columnWidth respectiva
  • As margins da célula são preenchimento interno; elas reduzem a área de conteúdo e não se somam à largura da célula
  • Para tabelas de largura total: use a largura do conteúdo (largura da página menos as margens esquerda e direita)

Imagens

// CRÍTICO: o parâmetro type é OBRIGATÓRIO
new Paragraph({
  children: [new ImageRun({
    type: "png", // Obrigatório: png, jpg, jpeg, gif, bmp, svg
    data: fs.readFileSync("imagem.png"),
    transformation: { width: 200, height: 150 },
    altText: { title: "Título", description: "Desc", name: "Nome" } // Todos os três obrigatórios
  })]
})

Quebras de página

// CRÍTICO: PageBreak deve estar dentro de um Paragraph
new Paragraph({ children: [new PageBreak()] })

// Ou use pageBreakBefore
new Paragraph({ pageBreakBefore: true, children: [new TextRun("Nova página")] })

Hiperlinks

// Link externo
new Paragraph({
  children: [new ExternalHyperlink({
    children: [new TextRun({ text: "Clique aqui", style: "Hyperlink" })],
    link: "https://exemplo.com",
  })]
})

// Link interno (marcador + referência)
// 1. Crie marcador no destino
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [
  new Bookmark({ id: "capitulo1", children: [new TextRun("Capítulo 1")] }),
]})
// 2. Link para ele
new Paragraph({ children: [new InternalHyperlink({
  children: [new TextRun({ text: "Veja Capítulo 1", style: "Hyperlink" })],
  anchor: "capitulo1",
})]})

Notas de rodapé

const doc = new Document({
  footnotes: {
    1: { children: [new Paragraph("Fonte: Relatório Anual 2024")] },
    2: { children: [new Paragraph("Consulte o apêndice para metodologia")] },
  },
  sections: [{
    children: [new Paragraph({
      children: [
        new TextRun("A receita cresceu 15%"),
        new FootnoteReferenceRun(1),
        new TextRun(" usando métricas ajustadas"),
        new FootnoteReferenceRun(2),
      ],
    })]
  }]
});

Paradas de tabulação

// Alinhar texto à direita na mesma linha (ex.: data oposta a um título)
new Paragraph({
  children: [
    new TextRun("Nome da Empresa"),
    new TextRun("\tJaneiro 2025"),
  ],
  tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
})

// Líder de ponto (estilo TOC)
new Paragraph({
  children: [
    new TextRun("Introdução"),
    new TextRun({ children: [
      new PositionalTab({
        alignment: PositionalTabAlignment.RIGHT,
        relativeTo: PositionalTabRelativeTo.MARGIN,
        leader: PositionalTabLeader.DOT,
      }),
      "3",
    ]}),
  ],
})

Layouts de múltiplas colunas

// Colunas de largura igual
sections: [{
  properties: {
    column: {
      count: 2,          // número de colunas
      space: 720,        // espaço entre colunas em DXA (720 = 0,5 polegada)
      equalWidth: true,
      separate: true,    // linha vertical entre colunas
    },
  },
  children: [/* conteúdo flui naturalmente entre colunas */]
}]

// Colunas de largura personalizada (equalWidth deve ser false)
sections: [{
  properties: {
    column: {
      equalWidth: false,
      children: [
        new Column({ width: 5400, space: 720 }),
        new Column({ width: 3240 }),
      ],
    },
  },
  children: [/* conteúdo */]
}]

Force uma quebra de coluna com uma nova seção usando type: SectionType.NEXT_COLUMN.

Sumário

// CRÍTICO: Cabeçalhos devem usar HeadingLevel APENAS - sem estilos personalizados
new TableOfContents("Sumário", { hyperlink: true, headingStyleRange: "1-3" })

Cabeçalhos/Rodapés

sections: [{
  properties: {
    page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 polegada
  },
  headers: {
    default: new Header({ children: [new Paragraph({ children: [new TextRun("Cabeçalho")] })] })
  },
  footers: {
    default: new Footer({ children: [new Paragraph({
      children: [new TextRun("Página "), new TextRun({ children: [PageNumber.CURRENT] })]
    })] })
  },
  children: [/* conteúdo */]
}]

Regras críticas para docx-js

  • Defina o tamanho da página explicitamente - docx-js usa A4 como padrão; use US Letter (12240 x 15840 DXA) para documentos dos EUA
  • Paisagem: passe dimensões de retrato - docx-js troca largura/altura internamente; passe o lado curto como width, o lado longo como height, e defina orientation: PageOrientation.LANDSCAPE
  • Nunca use \n - use elementos Paragraph separados
  • Nunca use marcadores Unicode - use LevelFormat.BULLET com configuração de numeração
  • PageBreak deve estar em Paragraph - autônomo cria XML inválido
  • ImageRun requer type - sempre especifique png/jpg/etc
  • Sempre defina width da tabela com DXA - nunca use WidthType.PERCENTAGE (quebra no Google Docs)
  • Tabelas precisam de larguras duplas - array columnWidths E width da célula, ambos devem corresponder
  • Largura da tabela = soma de columnWidths - para DXA, garanta que somem exatamente
  • Sempre adicione margens de célula - use margins: { top: 80, bottom: 80, left: 120, right: 120 } para preenchimento legível
  • Use ShadingType.CLEAR - nunca SOLID para sombreamento de tabela
  • Nunca use tabelas como divisores/linhas - células têm altura mínima e renderizam como caixas vazias (incluindo em cabeçalhos/rodapés); use border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E75B6", space: 1 } } em um Paragraph. Para rodapés de duas colunas, use paradas de tabulação (veja seção Paradas de Tabulação), não tabelas
  • TOC requer HeadingLevel apenas - sem estilos personalizados em parágrafos de cabeçalho
  • Substitua estilos internos - use IDs exatos: "Heading1", "Heading2", etc.
  • Inclua outlineLevel - obrigatório para TOC (0 para H1, 1 para H2, etc.)

Editando Documentos Existentes

Siga todas as 3 etapas em ordem.

Etapa 1: Descompactar

python scripts/office/unpack.py documento.docx descompactado/

Extrai XML, formata-o, mescla execuções adjacentes e converte aspas curvas em entidades XML (“ etc.) para que sobrevivam à edição. Use --merge-runs false para pular a mesclagem de execuções.

Etapa 2: Editar XML

Edite arquivos em descompactado/word/. Veja a Referência XML abaixo para padrões.

Use "Claude" como autor para alterações controladas e comentários, a menos que o usuário solicite explicitamente o uso de um nome diferente.

Use a ferramenta Editar diretamente para substituição de strings. Não escreva scripts Python. Scripts introduzem complexidade desnecessária. A ferramenta Editar mostra exatamente o que está sendo substituído.

CRÍTICO: Use aspas curvas para novo conteúdo. Ao adicionar texto com apóstrofos ou aspas, use entidades XML para produzir aspas curvas:

<!-- Use estas entidades para tipografia profissional -->
<w:t>Aqui&#x2019;s a quote: &#x201C;Olá&#x201D;</w:t>
EntidadeCaractere
&#x2018;' (aspa simples esquerda)
&#x2019;' (aspa simples direita / apóstrofo)
&#x201C;" (aspa dupla esquerda)
&#x201D;" (aspa dupla direita)

Adicionando comentários: Use comment.py para lidar com código padrão em múltiplos arquivos XML (o texto deve ser pré-escapado em XML):

python scripts/comment.py descompactado/ 0 "Texto do comentário com &amp; e &#x2019;"
python scripts/comment.py descompactado/ 1 "Texto de resposta" --parent 0  # responder ao comentário 0
python scripts/comment.py descompactado/ 0 "Texto" --author "Autor Personalizado"  # nome de autor personalizado

Em seguida, adicione marcadores ao document.xml (veja Comentários na Referência XML).

Etapa 3: Compactar

python scripts/office/pack.py descompactado/ saida.docx --original documento.docx

Valida com auto-reparo, condensa XML e cria o arquivo .docx.

Habilidades Relacionadas