panfu/arch-diagram

O que arch-diagram faz?

Dois métodos, podem ser usados separadamente ou em série (linguagem natural → Mermaid → HTML).

• nl2mmd: linguagem natural → dialeto Mermaid
• mmd2html: dialeto Mermaid → HTML interativo (template: diretório assets/template.html deste skill)

Convenção comum: dialeto Mermaid

Estrutura (três níveis, correspondentes a Servidor → Serviço → Subserviço no HTML):

• subgraph do nível superior = servidor, com direction TB
• subgraph do segundo nível = serviço (só cria subgrafo se houver subserviços; serviços sem subserviços são escritos diretamente como nós)
• Nós dentro de subgrafos de serviço = subserviços
• Todos os títulos usam texto entre aspas: subgraph X["Título"], N["Título"]

Observações (meta): Use | no título para separar nome e observação; o HTML exibirá a observação em letras pequenas e claras ao lado do nome (especificações do servidor, portas, volume de tarefas, parâmetros, etc.). Sem observação, omita |:

• subgraph WEB["Web Edge | Ativo · LAN"] → nome do servidor "Web Edge", observação "Ativo · LAN"
• WEB_GW["API Gateway | QPS 3k"] → nome do serviço + observação
• Regra de parsing: pegue o último |, o lado esquerdo é o nome, o lado direito é a observação

O tipo de aresta é expresso pelo estilo da linha, fixo:

Tipo	Estilo da linha	Semântica
sync síncrono	==>	Sincronização de dados / gravação
call chamada	-->	API / RPC / WS
job agendado	-.->	cron / tarefa programada / push
data leitura	-.-	Consulta somente leitura ao banco

• Rótulo da aresta: ==>|"tipo · horário ou frequência"|, ex.: ==>|"sync · 07:10 4×/dia"|; -->|call| pode omitir a descrição
• IDs de nós em maiúsculas com snake_case: <servidor>_<serviço>_<subserviço>, ex.: NAS_SCHED_FLAT
• Arestas podem ser ancoradas em subgrafos (nível de serviço/servidor), representando arestas nessa granularidade
• Inicie com flowchart LR; arestas internas do mesmo host são escritas normalmente (o HTML as desenhará como loops saindo pela direita e retornando pela direita)

Método 1: nl2mmd (linguagem natural → Mermaid)

1. Extrair entidades: máquina/host/ambiente → servidor; software instalado/executado → serviço; componentes/funcionalidades/tarefas/bibliotecas dentro do software → subserviço.
2. Extrair relações: mapeamento de verbos para tipos: sincronização/gravação/espelhamento → sync; chamada/solicitação/envio/recebimento → call; diário/agendado/cron/hh:mm/push → job; leitura/consulta/whitebox → data. Horário e frequência vão no rótulo da aresta.
3. Se a hierarquia for duvidosa, coloque no nível de serviço, não invente subserviços.
4. Números e especificações (portas, tamanho, volume de tarefas, faixa IP etc.) vão na observação do nó: ["Nome | Observação"]; horário e frequência vão no rótulo da aresta. Não os perca.
5. Saída: um bloco de código flowchart LR completo, sem explicação.

Método 2: mmd2html (Mermaid → HTML interativo)

Passos

1. Leia o conteúdo completo de assets/template.html (~38KB, arquivo único autocontido, dados padrão são o conteúdo de examples/sample.mmd).
2. Faça o parsing do Mermaid (conforme dialeto acima), construa um mapeamento id do Mermaid → caminho hierárquico: caminho no formato servidor.serviço.subserviço (truncado pela profundidade de aninhamento). Arestas ancoradas em subgrafos param no nível correspondente.
3. Substitua o bloco inteiro entre /*==DATA==*/ e /*==DATA-END==*/ no template pelo novo bloco de dados, sem alterar o restante do código:

/*==DATA==*/
var ARCH_TITLE='Título do diagrama (barra de título do terminal e <title> standalone)';
var ARCH_LSKEY='arch-<slug>';   // chave do localStorage, única para cada diagrama
var TYPE={sync:{c:'#3ecf8e',dash:'10 4',dur:'1.5s',label:'Síncrono'},
 call:{c:'#58a6ff',dash:'6 5',dur:'1.1s',label:'Chamada'},
 job :{c:'#f0a942',dash:'2 4',dur:'0.85s',label:'Agendado'},
 data:{c:'#b18cff',dash:'14 5',dur:'1.9s',label:'Leitura'}};
var COLS=[['srvA','srvB'],['srvC']];   // layout de colunas padrão: cada array = um grupo de IDs de servidores
var SERVERS=[
 {id:'srvA',short:'A',name:'A · Nome exibido',meta:'Observação',ac:'#b18cff',svc:[
   {id:'svc1',short:'svc1',name:'Serviço1',meta:'',subs:[
     {id:'sub1',short:'sub1',name:'Subserviço1',meta:''}]},
   {id:'svc2',short:'svc2',name:'Serviço2'}]},
];
var EDGES=[
 {from:'srvA.svc1.sub1',to:'srvC.svc2',type:'sync',sched:'07:10 4×/dia'},
];
/*==DATA-END==*/

Regras dos campos:

• id usa ASCII (caminho com pontos é montado a partir dele); name pode ser em chinês; short é o nome abreviado para linhas/logs
• meta vem da parte após o último | no título do nó/subgrafo; omitido se não houver
• ac é alternado da paleta: #b18cff #3ecf8e #39d0c4 #58a6ff #f0a942
• type ∈ sync|call|job|data (correspondente ao estilo da linha Mermaid); sched vem da parte do rótulo da aresta após o tipo; se não houver, escreva Tempo real
• COLS: ordenação aproximada pelo fluxo das arestas (origem à esquerda, destino à direita); o gerador de colunas para servidor único centraliza verticalmente automaticamente

4. Escreva o artefato no caminho de destino (versão fragmento). Quando quiser que funcione com duplo clique, encapsule:

<!doctype html><html lang="pt-BR"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{ARCH_TITLE}</title>
<style>html,body{margin:0;padding:0;background:#080b12}#svcarch{min-height:100vh}</style></head><body>
{fragment}</body></html>

QA

1. Obrigatório: extraia o <script> e execute node --check; verifique os dados — número de servidores/serviços/subserviços igual ao Mermaid, número de arestas = número de arestas no Mermaid, número de linhas na visualização padrão = número de grupos (from,to,type) após deduplicação.
2. Com navegador: ao iniciar um servidor local, deve incluir cabeçalho charset (python3 -m http.server não inclui charset, o que causará caracteres chineses ilegíveis; é necessário um handler personalizado para adicionar Content-Type: text/html; charset=utf-8 aos arquivos .html). Abra e verifique título, contagens, seletor de granularidade ▾ servers, clique para recolher.
3. Altere apenas o bloco DATA no template; não reimplemente o restante do código (arrastar/recolher/persistência).

Exemplos

• examples/sample.mmd — exemplo completo do dialeto (4 servidores, 9 arestas, cobrindo todos os 4 tipos de linha e arestas do mesmo host)
• examples/sample.html — artefato gerado a partir do template (funciona com duplo clique)

Capacidades inerentes do HTML gerado (não reimplementar fora do template)

Arrastar (alça no topo; segurar Alt exibe todas as alças), ajuste de largura pela borda direita, recolhimento, três predefinições de granularidade (servidores/serviços/folhas), log de arestas / inspetor, layout e estado de recolhimento salvos no localStorage (chave = ARCH_LSKEY). Texto da interface em inglês.

• Zoom e deslocamento da tela: Ctrl+roda do mouse para zoom centrado no cursor (0.4–2.5×), segurar Ctrl transforma o mouse em mão para arrastar a tela; chip de porcentagem no canto inferior direito; clique para resetar. Zoom/deslocamento persistem no localStorage.
• Edição interna: Segurar Alt e clicar em qualquer cabeçalho de nó (nos três níveis) para alterar nome/observação/cor da caixa do servidor, adicionar subordinado, excluir (confirmação em duas etapas, com exclusão em cascata da subárvore e arestas); Alt+clique em uma aresta permite alterar tipo/horário ou excluir aresta. Ao segurar Alt, aparece um botão ⇱ export no canto superior direito, exibindo um modal com o Mermaid do estado mais recente (com destaque de sintaxe e cópia), contendo botões ⟲ relayout e ↺ restaurar dados padrão. As edições persistem no localStorage.