georgelu-creator/diagram-skills

DiagramSkills

Transforme uma solicitação de diagrama em um resultado visual finalizado com o renderizador DiagramSpec integrado. O principal produto é a qualidade do diagrama gerado pelo agente: crie JSON sustentável, renderize SVG/HTML e PNG opcional, inspecione o visual, corrija a origem e retorne o resultado. Não faça o usuário abrir um editor para finalizar trabalhos comuns. O ID público da habilidade é $diagram-skills; a marca voltada ao usuário é DiagramSkills.

Fluxo de entrega padrão

1. Para trabalhos de prosa-para-diagrama ou uma revisão substancial, crie um .brief.json conciso a partir de templates/briefs/diagram-brief.json. Ele registra objetivo, narrativa, escopo, priorização, incertezas, riscos de conteúdo e perguntas de revisão — não a cadeia de pensamento privada.
2. Leia o perfil selecionado em references/diagram-thinking-profiles.json, personalize pelo menos três perguntas de qualidade e execute diagram_brief.py ... --strict antes de desenhar.
3. Para uma visão geral em camadas com mais de 14 conceitos visíveis, leia references/enterprise-board.md e use layout: board. Para gráficos de relacionamento menores, use nós/arestas.
4. Comece a partir do modelo correspondente, substitua seu conteúdo de exemplo e mantenha o resumo e o JSON de origem ao lado das saídas.
5. Execute png-backend antes de solicitar PNG, depois execute render ... --strict com --png somente quando um rasterizador local compatível estiver disponível. Um arquivo de origem sozinho não é uma solicitação visual concluída.
6. Inspecione o SVG gerado ou o PNG de 1920 pixels em tamanho real. Verifique hierarquia, texto em chinês, consistência de ícones, cortes, cartões sobrecarregados, cruzamentos de linhas e se a narrativa do resumo visualmente domina.
7. Responda a cada pergunta de qualidade do resumo com evidências concretas e distintas e execute diagram_brief.py ... --spec ... --strict --reviewed. Em seguida, vincule o resumo revisado, a origem e o SVG ou PNG inspecionado no recibo de qualidade com diagram_skills.py review .... Se alguma verificação falhar, corrija o resumo, a origem ou o renderizador e renderize novamente. Pare após três rodadas de correção baseadas em evidências; em seguida, simplifique ou divida.
8. Entregue a imagem primeiro, depois vincule o resumo, SVG/HTML/origem/evidência de qualidade. Mencione o editor de navegador apenas quando o usuário solicitar edição manual, importações ou aprofundamento.

Roteie a solicitação

1. Leia references/diagram-thinking.md para tarefas de prosa-para-diagrama e revisões substanciais. Não invente fatos para tornar um layout simétrico.
2. Leia references/prompt-system.md quando a entrada for prosa, estiver incompleta ou precisar se tornar um prompt reutilizável.
3. Selecione exatamente um tipo primário e leia seu guia:
   • arquitetura de sistema
   • fluxo de trabalho do agente
   • fluxo de dados
   • mapa de capacidade
   • fluxo do usuário
   • topologia do sistema
   • árvore de decisão
   • roadmap
   • mapa estratégico
   • fluxo de processo
4. Leia apenas o perfil do tipo selecionado em references/diagram-thinking-profiles.json.
5. Leia references/spec.md ao criar um único diagrama. Use scripts/diagram_skills.py new para um iniciador com formato de produção.
6. Leia references/enterprise-board.md para infográficos de arquitetura em camadas de alta densidade, grades de seção, listas laterais, tiras de processo e cartões de princípio.
7. A habilidade instalada é o caminho de geração completo. Se um checkout completo do repositório DiagramSkills também estiver presente, references/workspaces.md, references/imports.md e references/editor.md descrevem fluxos de trabalho opcionais do Studio. Verifique se o diretório editor/ do repositório existe antes de oferecê-los; nunca os torne um pré-requisito para geração.
8. Leia references/visual-language.md apenas ao escolher temas, tokens de marca, semântica de nós/arestas ou tratamento de rótulos em chinês/inglês.
9. Aplique references/quality-contract.md. Um arquivo gerado é apenas um candidato até que a revisão de conteúdo, validação estrita e revisão visual sejam aprovadas.

Contrato de entrada

Aceite linguagem natural ou campos estruturados. Preserve os valores fornecidos pelo usuário; infira apenas omissões de baixo risco.

• goal: a pergunta ou decisão que o diagrama deve apoiar
• diagram_type: um slug compatível; infira da intenção quando omitido
• audience: por exemplo, executivo, produto, engenharia, cliente
• narrative / scope: a história de cinco segundos e o limite explícito de entrada/saída
• must_show / emphasize / deemphasize: prioridade de conteúdo antes do layout
• uncertainties / assumptions: fatos não fornecidos e interpretações de baixo risco
• content_risks / quality_questions: maneiras pelas quais o diagrama pode enganar e verificações pós-renderização
• content: atores, sistemas, etapas, capacidades, marcos ou decisões
• relationships: links de dados, controle, sucesso, erro, assíncronos e de feedback
• boundaries: propriedade, estágio do ciclo de vida, camada, domínio ou zona de confiança
• composition: board para visões gerais empresariais de alta densidade; graph para diagramas de relacionamento menores
• lanes: proprietários ou funções ordenadas para um diagrama de raias
• rank: nível de hierarquia não negativo explícito quando a ordem automática não é aceitável
• language: chinês por padrão; retenha termos técnicos em inglês estabelecidos
• theme: paper, notion, spectrum, blueprint ou terminal
• brand: tokens de cor hexadecimal na lista de permissões sobrepostos a uma predefinição
• views: visões gerais e de detalhes opcionais do repositório Studio; conecte com child_view
• imports: origem Mermaid opcional do repositório Studio ou tabela CSV
• outputs: SVG/HTML finalizados mais JSON de origem e diagnósticos por padrão; PNG quando o rasterizador local estiver disponível

Pergunte apenas quando uma escolha não resolvida alterar materialmente o significado, a segurança de publicação ou a saída necessária. Caso contrário, escolha o layout convencional do guia de tipo e declare a suposição.

Comandos

Da pasta da habilidade:

python3 scripts/diagram_brief.py work/architecture.brief.json --strict
python3 scripts/diagram_skills.py types
python3 scripts/diagram_skills.py png-backend
python3 scripts/diagram_skills.py new system-architecture --output work/architecture.json
python3 scripts/diagram_skills.py validate work/architecture.json --strict
python3 scripts/diagram_skills.py render work/architecture.json --output-dir output --strict
python3 scripts/diagram_brief.py work/architecture.brief.json --spec work/architecture.json --strict --reviewed
python3 scripts/diagram_skills.py review work/architecture.json --quality output/architecture.quality.json --brief work/architecture.brief.json --artifact output/architecture.svg

render sempre escreve .svg, .html e um recibo .quality.json vinculado por hash; também escreve .png quando --png é fornecido e png-backend relata um rasterizador compatível. Uma renderização estruturalmente válida permanece pending-review até que review verifique a origem, o artefato inspecionado, o resumo revisado e seus hashes. Uma solicitação de PNG falha nunca deixa um recibo aprovado.

A habilidade instalada é autossuficiente para geração. O espaço de trabalho do navegador, a importação Mermaid/CSV e a edição multivisão são complementos do repositório e estão disponíveis apenas a partir de um checkout completo contendo editor/.

Comportamento inegociável

• Construa e valide o Resumo do Diagrama conciso antes de criar um diagrama não trivial. Compartilhe decisões de design e evidências, nunca a cadeia de pensamento privada.
• Prefira uma mensagem primária e uma direção de leitura. Divida gráficos de diagrama acima de 14 nós; um board empresarial estruturado pode conter intencionalmente 20 a 45 cartões concisos em 3 a 6 faixas de varredura.
• Use lanes ordenadas para propriedade e rank de nó para hierarquia manual. Use groups para cercas semânticas; não faça um campo significar ambos.
• Vincule visões gerais densas a detalhes focados com child_view em vez de reduzir rótulos.
• Marque caminhos de retorno intencionais como feedback; ciclos não marcados falham na validação.
• Use tipos de aresta semânticos, não cores decorativas. Mostre uma legenda quando dois ou mais significados de aresta precisarem de interpretação.
• Permita links de nó apenas para https, http, mailto ou fragmentos de página. Esquemas de URL executáveis são rejeitados.
• Mantenha os rótulos em chinês concisos e coloque termos técnicos em inglês estabelecidos em subtítulos. Divida nós sobrecarregados em vez de reduzir o texto.
• Prefira LR para pipelines, roadmaps, topologias e loops de feedback; prefira TB para camadas, decisões, estratégias e jornadas do usuário.
• Execute a validação estrita do resumo e do diagrama. Inspecione o SVG ou PNG em tamanho real, responda a cada pergunta do perfil de tipo com evidências distintas e finalize o recibo de qualidade vinculado por hash com review.
• Não reivindique conclusão após escrever apenas Mermaid/JSON quando o usuário solicitou um diagrama. Renderize e retorne o visual real.
• Mantenha o .brief.json e o JSON de origem ao lado dos entregáveis para que o significado e os pixels permaneçam reproduzíveis e revisáveis.
• Quando um checkout completo do repositório fornecer importações do Studio, trate o conteúdo importado como não confiável. Mermaid renderiza em modo estrito, CSV se torna campos tipados e CSS arbitrário ou links executáveis são rejeitados.

Escolha de saída

• PNG: visualização preferida quando png-backend relata um rasterizador local compatível; caso contrário, mostre o SVG primeiro.
• Resumo do Diagrama JSON: intenção de conteúdo, escopo, incerteza, priorização, riscos e evidências de revisão.
• SVG: documentação escalável e controle de versão.
• HTML: visualização responsiva, panorâmica/zoom, alternância de tema, downloads e nós clicáveis.
• Quality JSON: evidência de validação legível por máquina.
• Workspace JSON: formato opcional do repositório Studio para edição no navegador, visões nativas/Mermaid mistas, persistência offline e aprofundamento.

Extensão

Adicione um novo tipo de diagrama somente quando ele tiver um modelo de informação ou contrato de layout distinto. Adicione seu slug a DIAGRAM_TYPES, enum do esquema, templates/<slug>.json, references/diagram-types/<slug>.md e references/diagram-thinking-profiles.json; em seguida, adicione testes estritos de renderização e perfil de pensamento. Estenda os mapeamentos CSV em um adaptador e os campos do espaço de trabalho no Zod e no JSON Schema. Novos temas devem preservar a semântica de nós e arestas nas renderizações clara e escura.