CommunityImagemgithub.com

relationship-schematic

Gere ou edite esquemas de relacionamento científico (diagramas de mecanismo, cadeias de via, fluxos de trabalho experimental, contenção estrutural) como SVG editável e rastreável com semântica de relação verificada.

O que é relationship-schematic?

Este skill é um pipeline rigoroso para criar diagramas de relacionamento científico (como mecanismos de via, fluxos de trabalho, diagramas de contenção) onde a correção científica é primordial. Ele opera em 7 etapas: 1) cria um scaffold de contrato vazio, 2) extrai uma tabela entidade-relação com citações literais do material de origem, 3) valida o modelo, 4) renderiza um SVG editável em camadas com grupos `node-*`, `edge-*` e `group-*`, 5) verifica a geometria do desenho contra o modelo (setas, direções, contenção), 6) exporta para PNG 300dpi e PDF vetorial, 7) finaliza um result.json com todos os artefatos e status de verificação. A principal força está no verificador: ele impede falhas comuns como inibição desenhada como ativação, direções upstream/downstream invertidas, entidades inventadas ou alegações não rastreáveis. Inclui scripts Python para cada etapa, um dicionário de símbolos (`symbols/symbols.json`) e lida com incertezas usando direcionamento `unknown` (tracejado + `?`) e ambiguidades de entidades registradas no campo `uncertainty`. É ideal para qualquer tarefa que exija 'desenhar um esquema/mecanismo/fluxo de trabalho a partir deste artigo', onde a fidelidade semântica é mais importante que a estética.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/qingyulzx/pku-efficiency3-skills/tree/HEAD/relationship-schematic

Installed? Explore more Imagem skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Perguntar na sua IA favorita

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

Documentação

Esquemas de relacionamento: extrair → modelar → renderizar → verificar → exportar

Você está desenhando figuras cuja correção científica é julgada por um revisor LLM contra o material de origem. Os modos de falha dominantes da geração de imagem genérica são exatamente as coisas que este skill se recusa a fazer: inibição desenhada como ativação, montante/jusante invertido, contenção desenhada como caixas lado a lado, nomes de genes ou números inventados, alegações não rastreáveis. Cada mecanismo aqui existe para tornar essas falhas impossíveis de serem enviadas silenciosamente.

Inegociáveis

  1. Nada é desenhado que não esteja na tabela de relações. O modelo da figura (model.json) é a única fonte da verdade; o SVG é gerado a partir dele e lido de volta contra ele.
  2. Cada entidade e relação carrega uma citação literal + localizador do material de origem. Uma relação sem citação é recusada pela ferramenta (relation_no_evidence). Se não puder citar, não pode desenhar.
  3. from/to codificam a afirmação, não o layout. "A inibe B" ⇒ from: A, to: B, type: inhibits. O renderizador decide a geometria; o verificador verifica se a ponta da seta realmente chega a B.
  4. Desconhecido é desenhado como desconhecido. Se o material não afirma uma direção, use direction: "unknown" — ele renderiza tracejado com um ? e é sinalizado em result.json. Nunca adivinhe para deixar a figura mais limpa.
  5. Entregue o result.json mínimo garantido primeiro, melhore depois. O passo 1 escreve um scaffold em formato de contrato com nulls explícitos antes de qualquer extração, para que uma falha ainda deixe um entregável parcial válido.

Os scripts estão em scripts/ (Python 3 puro stdlib + cairosvg/PIL opcionais; auto-detecta headless de navegador para exportação). A semântica dos símbolos está em symbols/symbols.json e é documentada em references/symbol-conventions.md; o formato do modelo em references/model-schema.md. Leia ambas as referências antes da sua primeira execução.

Fluxo de trabalho (7 etapas)

Trabalhe em /app/work; os artefatos finais vão para /app/output.

Etapa 1 — Scaffold do entregável mínimo

python scripts/init_result.py --case /input/case.json --work /app/work --output /app/output

Lê o caso, cria diretórios, escreve /app/output/result.json com todos os campos output_contract presentes e null, status: "partial", e uma entrada partial_reasons. Se o arquivo de caso estiver ausente/ilegível, ainda escreve o scaffold e registra o problema. Também leia task.md e quaisquer arquivos de material você mesmo — nunca presuma conteúdo a partir de rótulos ou nomes de arquivos.

Etapa 2 — Extrair a tabela entidade–relação (seu julgamento, não de um script)

Leia o material real (texto PDF via ferramentas da plataforma, tabelas, texto do caso) e construa /app/work/model.json conforme references/model-schema.md:

  • uma entidade por ator científico; label = nome canônico conforme impresso na fonte; type = papel funcional mostrado como um pequeno subtítulo;
  • uma relação por interação declarada, com type da biblioteca de símbolos (activates inhibits binds modifies transports indirect precedes contains parallels) e direction (A_to_B / B_to_A / bidirectional / unknown);
  • contenção ("O complexo X consiste em A, B, C") torna-se um grupo com membros, mais relações contains — nunca uma aresta, nunca justaposição;
  • ordem temporal/de processo ("primeiro … depois …") torna-se precedes com rótulos de etapa;
  • evidence = substring literal do material + localizador (seção, parágrafo, linha de tabela, página) + id da fonte (DOI/nome do arquivo).

Regras de extração para casos difíceis:

  • Ambiguidade de entidade (sinônimos/abreviações, "β-catenina" vs "CTNNB1"): uma entidade, rótulo como a fonte imprime, anote a equivalência em result.json uncertainty. Dois nomes que a fonte distingue permanecem duas entidades.
  • Direção não declarada: direction: "unknown" (tracejado + ?). Declare a ambiguidade em uncertainty; não a resolva por plausibilidade.
  • Evidência indireta ("X leva a Y via Z" para a alegação X→Y): use tipo indirect (tracejado) ou modele a cadeia mecanicista X→Z→Y se cada salto for citado. Prefira a cadeia — revisores podem segui-la.
  • Números/unidades/concentrações no material (por exemplo, "3,3–10,4%"): mantenha-os nos rótulos de aresta/nó exatamente como impressos, nunca arredondados ou inventados.
  • Se o caso solicitar um gráfico de valores de dados reais, isso está fora do núcleo deste skill (gráficos estatísticos) — ainda entregue o que se aplica (tabela de entidades, disciplina de mapeamento dados-para-legenda) e marque o resto como parcial com a razão.

Etapa 3 — Validar antes de desenhar

python scripts/model_check.py /app/work/model.json

Exit 0 = limpo (avisos permitidos). Corrija todos os erros — o renderizador recusa com erros de qualquer maneira. Avisos (entity_no_evidence, direction_uncertain, cycle_in_rank_graph, …) são estados científicos legítimos: mantenha-os e carregue-os para result.json em vez de "corrigi-los" por invenção.

Etapa 4 — Renderizar o SVG editável

python scripts/make_schematic.py /app/work/model.json -o /app/work/figure.svg --report /app/work/layout.json

Produz um SVG em camadas: grupos node-* / edge-* / group-* / legend, cada um carregando data-evidence-quote/-locator/-source. O layout é automático (empilhamento por caminho mais longo, então as arestas A_to_B apontam para baixo); se o conteúdo exceder canvas_width, a tela alarga e um aviso canvas_expanded é registrado — nada é jamais cortado.

Etapa 5 — Ler o desenho de volta e verificar

python scripts/verify_svg.py /app/work/model.json /app/work/figure.svg --out /app/work/verify.json

Esta é a porta de segurança central contra falhas. Verifica cobertura de entidade/relação, semântica de marcadores conforme a biblioteca de símbolos, direção geométrica da seta (a ponta deve estar mais perto do alvo semântico do que da fonte), caixas de contenção realmente envolvendo membros (e não prendendo não-membros), sobreposição de nós, ajuste de rótulo e cobertura da legenda. Exit 0 = aprovado.

Se falhar: corrija o modelo ou a edição, re-renderize, re-verifique. Nunca corrija o SVG manualmente para silenciar uma verificação. Duas iterações é normal; se uma verificação não puder passar porque o material é contraditório, mantenha a figura que as citações suportam e registre o conflito em result.json uncertainty.

Etapa 6 — Exportar e verificar conformidade

python scripts/export_svg.py /app/work/figure.svg -o /app/output --pdf

Escreve <nome>_300dpi.png e <nome>.pdf em /app/output, tentando backends em ordem (cairosvg → Edge headless → Chrome headless → rasterizador PIL embutido para PNG) e registrando cada falha de backend. O relatório inclui verificações por artefato (resolução, fundo branco, cabeçalho/aspecto da página PDF, fluxos de conteúdo vetorial). Copie figure.svg e model.json para /app/output como as fontes editáveis, e o PNG funciona como a pré-visualização renderizada.

Etapa 7 — Finalizar result.json (cobertura do contrato, honestamente)

Preencha todos os campos output_contract — um campo que você não puder preencher permanece null com uma razão em partial_reasons. Mapeamento típico (adapte os nomes ao contrato do caso):

  • editable_source → {svg, model, note: "SVG em camadas; cada elemento carrega data-evidence-*"}
  • exported_artifacts → os artefatos do relatório de exportação (caminho, formato, dpi, backend, verificações)
  • rendered_preview → o caminho do PNG
  • entity_relation_table → entidades + relações incl. citações/localizadores (ou um caminho para model.json mais contagens)
  • verification_report → resumo de verify.json (contagens de aprovação/falha, avisos)
  • sources → documentos fontes/DOIs usados, com a proveniência das citações
  • status → complete apenas se verify passou e todas as exportações estão ok; caso contrário partial com razões. uncertainty lista ambiguidades (identificação de entidades, direções desconhecidas, conflitos não resolvidos).

Editando um SVG existente (preservando a fonte)

Quando o caso fornece um SVG para modificar em vez de material para desenhar:

  1. Leia o SVG; localize grupos node-*/edge-* e seus atributos data-* (figuras deste skill são totalmente autodescritivas).
  2. Alterações locais (renomear, recolorir, tipo/rótulo de aresta, título, deletar um elemento não anexado) → escreva um JSON de edições e execute python scripts/edit_svg.py figure.svg edits.json -o figure_edited.svg. Cada operação precisa de um reason; o relatório prova que elementos não tocados são byte-idênticos (preserved.ok). Em seguida, re-exporte (Etapa 6).
  3. Alterações estruturais (adicionar/remover entidades ou relações, inverter uma direção) → estas são RECUSADAS pelo edit_svg por design (um atributo invertido sem re-roteamento desenha uma seta mentirosa). Reconstrua/estenda model.json a partir dos atributos de dados do SVG, edite o modelo, re-renderize, re-verifique.
  4. Se o SVG existente for de outra ferramenta (sem atributos de dados), reconstrua o modelo a partir do material de origem e re-renderize — não hackeie manualmente SVG estrangeiro; registre o que fez em result.json change_log.

Manual de falhas (caminhos reais, não prosa)

situaçãodetecçãoaçãoresult.json
caso/material ilegívelEtapa 1 ou sua própria leiturascaffold escrito, partial_reasons nomeia o arquivo/problemastatus partial, campos null
relação que não pode citarerro model_check relation_no_evidencedescarte a relação ou encontre a citação; nunca desenhe não citadoausente da figura (correto)
direção não declaradasua extraçãodirection: "unknown"tracejado + ?; entrada uncertainty
entidade sinônimo/abreviaçãosua extraçãoentidade única, equivalência anotadaentrada uncertainty
material contraditórioduas citações conflitamdesenhe o que a citação mais forte/mais específica suportaambas as citações + conflito em uncertainty
rótulo transborda sua caixaaviso verify text_fitencurte o rótulo ou adicione \n, re-renderize; crescimento da caixa é uma decisão de re-renderizaçãoaviso carregado
tela muito pequenaaviso canvas_expandedjá alargado automaticamente; ou aumente canvas_widthaviso carregado
DLL cairosvg ausente (Windows)tentativa de backend de exportação registradafallback automático para headless do navegador, depois rasterizador PILbackend + tentativas registradas
sem navegador, sem cairosvgtodos os backends falhamrasterizador PIL (caixas/linhas/texto; marcadores aproximados) + notesstatus partial para qualidade PNG, PDF null com razão
aspecto PDF erradoverificação de exportaçãocorrigido pelo dimensionamento de @page; se um backend o ignorar, registrado como checks_failstatus partial
verify não pode passarverify_svg exit 1loop de correção em nível de modelo; se impossível, entregue o subconjunto citadoverification_report mostra falhas honestamente

Auto-verificação antes de finalizar

  • verify_svg exit 0 (ou falhas honestamente relatadas);
  • /app/output contém: result.json (todas as chaves do contrato presentes, nulls explicados), figure.svg, model.json, PNG (300 dpi), PDF;
  • cada relação desenhada é citável — verifique pontualmente três valores aleatórios de data-evidence-quote contra o material;
  • nenhuma entidade/número aparece no SVG que não esteja em model.json;
  • change_log conta a história do que você fez, incluindo as etapas deste skill.

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

biopathway-mechanism-diagram

Build or edit publication-grade biological mechanism/pathway diagrams from research materials (PDF/text) as a challengeable mechanism statement - three-layer model (typed entities, typed directed edges with verbatim evidence, compartment layout), semantics-correct SVG source, PNG/PDF exports and a traceable, uncertainty-aware result.json. Use for tasks asking to draw, generate or edit signaling pathways, mechanism figures, crosstalk diagrams or pathway flowcharts; refuses to guess regulation direction and marks unstated information instead.

graphical-abstract-builder

Build a single-page graphical abstract (question, method, results, conclusion) from research material as a traceable, editable SVG with PNG/PDF exports. Use when asked to create or edit a graphical abstract, science summary figure, mechanism or flow diagram, or data chart from a paper, study notes or experimental records, especially when editable source files and element-to-source traceability are required.

paper-to-academic-ppt

Turn a research paper (PDF) into a structured, evidence-traceable, template-compliant academic slide deck. Two phases: agent-authored narrative spine and page-level claims (each with paper locators and verbatim quotes), then scripted template adaptation that writes content into real master/layout placeholders, embeds original paper figures, checks overflow/aspect/notes, and exports a PDF preview. Handles missing conclusions, figure-trimming, layout mismatch and over-limit slide counts with explicit rules.

slides-genedit

Generate and edit academic presentation decks from research material. Two routes: (1) generate a new deck from a paper/notes under fixed audience, duration and slide-count constraints, with per-slide claims, verbatim-number evidence mapping, speaker notes, and a rendered PDF preview; (2) source-preserving edits of an existing starting deck - inventory it, apply only the requested local changes, and prove untouched slides stayed byte-identical. Use when asked to turn research material into slides, or to modify/compress/re-audience an existing deck without breaking it.

Habilidades Relacionadas