O que biopathway-mechanism-diagram faz?
Uma figura de via é uma declaração de mecanismo que os leitores contestarão uma seta de cada vez. O contrato deste skill: cada entidade e cada aresta na tela remetem a uma citação literal com uma localização; a semântica da interação (ativação / inibição / ligação / modificação / transporte) é visualmente distinta e nunca confundida; qualquer coisa que a fonte não declarar (direção, localização, números) é marcada visivelmente como não declarada, não adivinhada. As entregas são um SVG editável em camadas, com IDs endereçáveis, mais exportações PNG/PDF e um result.json completo do contrato.
Quando usar / quando não usar
Use para: figuras de mecanismos, diagramas de vias de sinalização, cascatas receptor-núcleo, cross-talk entre vias, tarefas de "desenhar Figura N deste artigo", e edições em uma figura de via existente (adicionar/remover entidade ou aresta, renomear). Não use para: gráficos estatísticos (barras/boxplot/volcano), esquemas experimentais, ou retoques estéticos apenas; esses pertencem a skills adjacentes.
Contrato de execução (runtime da plataforma)
- Entrada:
/input/case.json(+ task.md). Trabalhe em/app/work; entregas em/app/output. - Primeira ação de toda a execução (antes de ler o case em profundidade):
python scripts/scaffold_result.py --input /input/case.json --outdir /app/outputIsso escreve um result.json com todos os campos do contrato de saída presentes, os não produzidos com null + motivo. Atualize-o passo a passo; nunca remova um campo do contrato. - Todos os scripts abaixo recebem caminhos no estilo
--model/--svge são Python 3 puro (stdlib apenas), salvo indicação.references/é lido pelos scripts; leia os arquivos.mdvocê mesmo antes do Passo 1.
Passo 0 - Leia o contrato e scaffold (1 requisição)
Execute o scaffold. Folheie task.md + case.json: identifique o alvo da figura (qual mecanismo, qual figura se estiver reproduzindo uma, cenário de gerar vs editar), os formatos de exportação necessários e o escopo de evidência. Registre a lista de campos do contrato que você deve preencher. Consciência de orçamento: procure terminar em 5-8 passos do modelo; os scripts fazem o trabalho pesado, você faz a ciência.
Passo 1 - Extraia o modelo de mecanismo (o núcleo científico - faça você mesmo)
Leia o material real (analise o PDF de verdade; leia arquivos, nunca presuma conteúdo a partir de rótulos). Construa /app/work/model.json conforme references/layout-conventions.md com SEU PRÓPRIO julgamento:
- Entidades — gene / proteína / receptor / RNA / complexo / molécula / célula / família. Aplique
references/naming-rules.md: símbolos de genes em itálico e nós de genes distintos de suas proteínas (MYC vs MYC); símbolos preferidos com grafias da fonte em sinônimos; famílias vs membros; um nó por complexo declarado. Cada entidade carregasource: {loc, quote}— uma citação LITERAL e uma localização precisa o suficiente para ser reencontrada (seção/parágrafo/página/legenda da figura). - Arestas — tipo do conjunto fechado em
references/edge-types.json(ativação, inibição, ligação, fosforilação, ubiquitinação, regulação_transcricional, translocação, formação_de_complexo, ...).directeddeve ser definido explicitamente. Nunca adivinhe direção: se a citação não tem pista direcional, definadirected: falsee registre uma incerteza (references/uncertainty-policy.md). Ligação/recrutamento é não-dirigido. Regulação transcricional tem como alvo um nó de gene e precisa de um sinal. - Compartimentos — extracelular / membrana / citoplasma / núcleo (+ RE, Golgi, sub-regiões de organelas se o mecanismo precisar). Entidades cuja localização não é declarada vão para a banda
nao_especificado— nunca silenciosamente para o citoplasma. Receptores se ancoram na banda de membrana. - Ordem — defina
orderconforme a posição na via (ordem topológica, não ordem textual); loops de feedback emergem naturalmente como arestas para trás. - Números na tela (expressão, significância) apenas se existirem literalmente na fonte; caso contrário, deixe os mapeamentos de dados como nulls explícitos.
Ordem prática de extração: leia uma vez para o fluxo geral; segunda passagem frase por frase para entidades + citações; terceira passagem para arestas incluindo inibidores, feedback e cross-talk (eles se escondem em frases com "no entanto" / "enquanto").
Passo 2 - Valide o modelo (script)
python scripts/validate_model.py --model /app/work/model.json \
--report /app/work/validation-report.json
Corrija todo erro E-*. E-DIR-01 (aresta dirigida sem pista direcional) é a guarda científica central: ou cite uma frase que declare direção ou rebaixe para não-dirigida + incerteza. Avisos exigem uma decisão consciente: nós de família, posicionamento de receptor, incompatibilidades sinal-vs-citação. Re-execute até ficar válido. Se o material não pode suportar um item de contrato necessário, anote isso agora (torna-se um null + motivo no Passo 5).
Passo 3 - Renderize SVG e exporte (scripts)
python scripts/render_svg.py --model /app/work/model.json \
--out /app/output/pathway.svg --report /app/work/render-report.json
python scripts/export_assets.py --svg /app/output/pathway.svg \
--outdir /app/output --model /app/work/model.json \
--png-width 2400 --report /app/work/export-report.json
Leia os avisos do relatório de renderização (limites do canvas, compartimentos desconhecidos). Olhe o PNG você mesmo; se o layout obscurecer o mecanismo (cruzamentos de arestas escondendo uma bifurcação, feedback sobre a cascata), ajuste order/posições de pin no modelo e re-renderize. O SVG é determinístico: modelo idêntico → SVG idêntico.
Passo 4 - Cenários de edição (se o case pedir edições em uma figura existente)
Reconstrua o modelo da figura alvo primeiro (Passo 1 no texto fonte da figura original), depois use edições que preservam a fonte — o modelo/SVG original é copiado em backup, cada edição é registrada no change_log do modelo:
python scripts/apply_edit.py --model /app/work/model.json --op add-edge \
--id e-new --src A --tgt B --type inhibition --directed true \
--sign negative --loc "..." --quote "..."
Operações: adicionar/renomear/remover entidade (remove recusa quando arestas estão anexadas a menos que --cascade, e remoções em cascata são registradas como incertezas), adicionar/remover aresta, adicionar compartimento. Toda entidade/aresta adicionada REQUER --loc + --quote literais. Após edições, re-valide (automático) e re-renderize (Passo 3).
Passo 5 - Verifique e finalize result.json (script + você)
python scripts/verify_outputs.py --model /app/work/model.json \
--svg /app/output/pathway.svg --result /app/output/result.json \
--exports /app/output/pathway.png /app/output/pathway.pdf \
--report /app/output/verification-report.json
Isso relê o SVG e verifica a leitura reversa de nós/arestas, consistência legenda↔uso em ambas as direções, overflow de rótulo, limites do canvas, existência das exportações, e que cada null em result.json tem um motivo. Em seguida, finalize result.json você mesmo: preencha os campos do contrato (caminhos de fonte editável, exportações com backend/parâmetros, tabela_de_entidades/tabela_de_arestas com citações, base_da_legenda, fontes com versões, incertezas, resumo de verificação, status honesto). Mantenha _motivos_nao_respondidos para qualquer coisa null. A entrega parcial deve declarar seus limites em palavras claras.
Tratamento de exceções (caminhos reais, não decoração)
| Falha | Detecção | Ação |
|---|---|---|
| PDF ilegível / sem camada de texto | análise falha ou texto vazio | ferramenta de renderização-pdf / ferramenta-ocr para renderizar, sinalize "camada de texto ausente" em result.json |
| Nome de entidade ambíguo (duas leituras) | sua extração | escolha pelo contexto, registre alternativa + incerteza; se indecidível, null + motivo |
| Direção não declarada | E-DIR-01 | rebaixe para aresta não-dirigida (sem ponta de seta) + incerteza. NUNCA adivinhe |
| Compartimento desconhecido | E-CMP-01 / aviso de layout | banda nao_especificado + nota |
| Dados numéricos ausentes para visuais codificados por dados | modelo não tem números literais | desenhe topologia, marque mapeamento null + "dados ausentes da fonte" |
| Overflow de rótulo | verifique label_overflow | encurte rótulo / divida em rótulo+sub / reordene |
| Canvas excede limites | aviso de renderização | divida em painéis ou reduza ramos; anote |
| Backend de exportação ausente | status do relatório de exportação falhou | cadeia de fallback já tentada; entregue SVG, registre falha + orientação em result.json |
| PNG em branco/degenerado | blank_check | investigue relatório de renderização; re-renderize; registre |
| Erros de validação persistem | código de saída 2 | corrija modelo; se impossível de corrigir a partir do material, entregue o subconjunto válido + limites explícitos |
Barra de qualidade (auto-verificação antes de finalizar)
- Um revisor poderia apontar para qualquer seta e obter sua justificativa literal da tabela embutida / modelo? (rastreabilidade)
- Ativação/inibição/ligação/modificação são visualmente distintas, e a legenda corresponde ao que foi desenhado — sem entradas faltando ou fantasmas?
- Tudo que não foi declarado está visivelmente não declarado (não-dirigido, banda não especificada, null + motivo)?
- Alguém consegue abrir o SVG, alterar um rótulo e re-exportar? (em camadas, com IDs endereçáveis, pilha de fontes padrão)
- O result.json cobre todos os campos do contrato com status honesto?
Arquivos
scripts/scaffold_result.py- result.json completo do contrato com null+motivoscripts/validate_model.py- esquema + evidência de direção + verificações de nomenclaturascripts/render_svg.py- SVG determinístico em camadas a partir de model.jsonscripts/export_assets.py- PNG/PDF com cadeia de fallback + verificação de brancoscripts/apply_edit.py- edições registradas que preservam a fontescripts/verify_outputs.py- verificação de leitura reversa do pacotereferences/edge-types.json- semântica de símbolos legível por máquinareferences/symbol-semantics.md- gramática visual e sua fundamentaçãoreferences/naming-rules.md- convenções para genes/proteínas/famílias/complexosreferences/uncertainty-policy.md- regras de rebaixamento; política de nunca adivinharreferences/layout-conventions.md- esquema de model.json + algoritmo de layoutexamples/ras-mapk-case/- um exemplo trabalhado com material real (Brown & Ried 2022)README.md- documentação de uso autônomo