uulab-official/drawio-skills

Engenheiro de Diagramas Draw.io

Construa diagramas através de uma pequena representação intermediária (IR) determinística. Trate a IR como a fonte da verdade e o .drawio como o artefato compilado.

Fluxo de Trabalho

1. No primeiro uso ou após uma falha de ambiente, execute doctor. Leia user-workflows.md para estados de capacidade, seleção de ponto de partida, conteúdo do pacote e comportamento de substituição segura. Leia cli.md ao compor comandos menos comuns ou interpretar códigos de saída. Para Diagram IR legado ou versionado, leia compatibility.md e execute migrate --check antes de editar.

2. Inspecione a solicitação e o material de origem relevante. Infira um tipo de diagrama, escopo, direção e tema sensatos quando o usuário não os especificar. Para um pacote coordenado de diagramas de arquitetura, leia blueprint.md, modele com base em blueprint.schema.json e use blueprint. Para um ERD, leia erd.md, modele com base em erd.schema.json e use erd. Aceite SQL DDL diretamente quando for a fonte da verdade. Para alta disponibilidade, leia ha.md, modele com base em ha.schema.json e use ha.

3. Escreva ou adapte a menor fonte estruturada. Use init architecture, init blueprint, init erd ou init ha quando não existir fonte. Leia ir-format.md para Diagram IR e authoring.md para escolhas específicas de diagrama. Ao iniciar a partir de uma árvore Python/TypeScript, OpenAPI, SQL, Compose, Terraform, Kubernetes, GitHub Actions ou GitLab CI, leia importers.md e gere a IR com import. Quando conectores automáticos permanecerem visualmente ambíguos ou uma interface fixa for importante, leia routing.md antes de atribuir portas explícitas. Quando estilo organizacional ou revisão visual mais profunda for necessária, leia style-system.md e use um pacote de tema validado. Ao importar conteúdo não confiável ou preparar um pacote de lançamento, leia security.md. Nunca coloque credenciais em rótulos, descrições, links, metadados ou valores padrão de entidades.

4. Prefira o fluxo de trabalho de pacote com um comando:

   python3 <skill-dir>/scripts/drawio_tool.py build source.json \
     -o build/diagram --name diagram --strict
   

   Isso cria IR normalizada, .drawio editável, todas as visualizações SVG, audit.json, security.json e bundle.json. Use os comandos de nível inferior compile, validate, preview, security e audit apenas quando o usuário precisar de artefatos individuais ou de um fluxo de trabalho incremental.

5. Se o draw.io Desktop estiver disponível e uma exportação Desktop for solicitada, leia desktop-export.md, renderize a partir do .drawio do pacote e mantenha seu relatório de verificação:

   python3 <skill-dir>/scripts/drawio_tool.py render build/diagram/diagram.drawio \
     -o diagram.png --report diagram.export.json
   

6. Inspecione visualmente cada visualização empacotada. Corrija hierarquia, texto cortado, colisões, arestas pouco claras, contraste fraco e detalhes excessivos. Reconstrua no máximo duas vezes antes de apresentar o melhor resultado.

7. Entregue o .drawio editável do pacote, a fonte IR, o relatório de auditoria, as visualizações e as exportações solicitadas. Informe claramente quando a exportação Desktop foi ignorada.

Ao comparar uma arquitetura aprovada com um modelo recém-gerado, leia drift.md, execute diff e entregue tanto o relatório legível por máquina quanto a visualização de desvio editável.

Editando diagramas existentes

Preserve o artefato do usuário. Comece inspecionando e validando:

python3 <skill-dir>/scripts/drawio_tool.py inspect existing.drawio
python3 <skill-dir>/scripts/drawio_tool.py validate existing.drawio

Recupere o Diagram IR revisável antes de edições semânticas:

python3 <skill-dir>/scripts/drawio_tool.py extract existing.drawio \
  -o existing.diagram.json --report existing.extraction.json --strict

Leia round-trip.md antes de confiar em um modelo recuperado. lossless: true significa que todas as células semânticas usaram metadados de compilador suportados. Um modelo válido de melhor esforço ainda pode ser escrito quando --strict sai com código 3; revise cada célula inferida antes de substituir a original.

Para um diagrama com suporte IR, escreva operações semânticas e aplique-as atomicamente:

python3 <skill-dir>/scripts/drawio_tool.py patch diagram.json changes.json -o diagram.updated.json

Leia patching.md antes de edições destrutivas ou com várias páginas. Se a extração relatar conteúdo não suportado apenas em XML, modifique apenas valores, estilos ou geometria de mxCell correspondentes e preserve o original até que a revisão visual seja aprovada. Nunca renumere IDs estáveis apenas por organização.

Contrato de Qualidade

Exija tudo o seguinte antes da entrega:

• Nenhum ponto final de aresta solto, IDs duplicados, referências pai inválidas ou sobreposição de nós.
• Rótulos cabem em seus nós e permanecem legíveis no zoom normal.
• Direção e agrupamento comunicam a hierarquia pretendida.
• Rótulos de aresta descrevem relacionamentos, não detalhes de implementação.
• A cor carrega um significado consistente e não se torna o único diferenciador.
• Detalhes decorativos não sobrecarregam o caminho de leitura principal.

Use --strict como uma barreira de liberação. Leia quality-gates.md quando uma verificação falhar ou um diagrama precisar de revisão visual manual.

Regras de Criação

• Use IDs semânticos e estáveis como api-gateway, não IDs ordinais como node-7.
• Mantenha os rótulos curtos. Coloque o contexto mais longo em description.
• Use valores group explícitos para camadas, zonas de confiança, contextos delimitados ou propriedade.
• Prefira da esquerda para a direita para pipelines de requisição/dados e de cima para baixo para processos ou hierarquias.
• Mantenha uma ideia principal por diagrama. Divida sistemas grandes em várias páginas ou níveis em vez de encolher tudo.
• Use position apenas quando o usuário precisar de posicionamento intencional; caso contrário, deixe o compilador dispor os nós deterministicamente.
• Não adivinhe nomes de estêncil específicos de fornecedores do draw.io. Use um tipo semântico neutro até que um mapeamento de forma verificado exista.

Comportamento da Ferramenta

scripts/drawio_tool.py depende apenas da biblioteca padrão para entrada JSON. A entrada YAML é suportada quando PyYAML está instalado. Ele fornece:

• doctor: verificar arquivos principais e suporte a Python/XML, depois relatar capacidades YAML e Desktop opcionais.
• init: copiar um ponto de partida seguro para arquitetura, Blueprint, ERD, HA, roteamento, infraestrutura ou CI.
• build: detectar automaticamente um modelo ou fonte e criar um pacote drawio-diagram-bundle/v1 completo e auditado.
• migrate: atualizar deterministicamente Diagram IR legado/sem versão e emitir um relatório de alteração legível por máquina.
• compile: validar IR, calcular layout determinístico e emitir XML draw.io editável não compactado.
• extract: recuperar Diagram IR de draw.io compactado ou não, preservando semânticas suportadas pelo compilador e relatando cada célula legada inferida.
• blueprint: projetar um modelo de arquitetura em páginas de contexto, lógica, dados, implantação, segurança e decisão.
• erd: validar entidades, campos, chaves, tipos e cardinalidades, depois gerar um ERD editável no estilo Crow's Foot a partir de um modelo ou SQL DDL.
• ha: validar domínios de falha, réplicas, replicação, verificações de integridade e failovers, depois gerar páginas de topologia e failover.
• import: converter árvores de módulos Python/TypeScript, OpenAPI, SQL DDL, Docker Compose, Terraform, Kubernetes, GitHub Actions ou GitLab CI em Diagram IR.
• diff: comparar Diagram IR semanticamente, emitir um relatório de desvio estruturado e, opcionalmente, gerar uma visualização de desvio editável codificada por cores e formas.
• patch: aplicar atomicamente alterações semânticas de nó, aresta, grupo, posição e diagrama.
• preview: criar um SVG revisável sem draw.io Desktop.
• audit: inspecionar fonte estruturada e geometria gerada, depois agrupar descobertas com sugestões de reparo e caminhos de visualização.
• security: escanear um modelo, .drawio ou pacote completo em busca de credenciais, links inseguros, construções XML proibidas e riscos de descompressão.
• validate: lint IR ou .drawio, imprimir uma pontuação de qualidade de 0 a 100 e falhar sob --strict.
• inspect: resumir páginas, nós, arestas, grupos e limites da tela.
• render: descobrir a CLI do draw.io Desktop no macOS, Windows e Linux, respeitar DRAWIO_DESKTOP_BINARY ou --binary e exportar PNG, SVG, PDF ou JPG.
• verify-export: validar a assinatura de formato, terminador estrutural, dimensões e conteúdo SVG seguro de uma exportação nativa sem iniciar o Desktop.

Antes do primeiro uso, verifique python3 -c "import xml.etree.ElementTree". Se um Python do Homebrew no macOS relatar um erro de símbolo pyexpat/libexpat, use /usr/bin/python3 ou repare essa instalação do Python; não atribua a falha de ABI à entrada do diagrama.

Use example.architecture.json, example.blueprint.json, example.erd.json, example.ha.json, example.routing.json, example.terraform.tf ou example.kubernetes.json como um ponto de partida compacto, não como um modelo fixo. Aplique corporate.json quando um exemplo de tema personalizado reutilizável for útil.