Yeshwanthyk/viz

O que viz faz?

Um renderizador fixo, assets/viz.js, desenha todos os visuais. O agente escreve apenas dados na gramática, de modo que um visual custa aproximadamente tantos tokens quanto a árvore ASCII que ele substitui. Em troca, obtém replay de passos, inspetor de nós, rastreamento de arestas, filtragem e cópia de caminho.

Escolha a visão

Escreva dados, não HTML: uma seção == graph (nós, caminhos e uma view:) ou uma seção de gráfico. Escolha pela pergunta que o leitor está fazendo, depois leia apenas a gramática necessária: gramática para gráficos, árvores e diffs, gráficos para == timing, gantt, hist, retries, causes, board, stock e waits.

Como flui?

• Dados se movendo entre componentes (ramos, fallbacks, saltos assíncronos, saídas de falha) → view: flow, o padrão. "Walk me through" adiciona uma cauda narrativa (abaixo). Rotule cada aresta com o que se move e declare as arestas na ordem em que acontecem; os números seguem.
• Quem age, o que envia, o que filtra, o que resulta → ranks: colunas, um caminho por gatilho, terminando em => result quando passa e =| result quando é filtrado. Times ou serviços como bandas → adicione lane:.
• Requisições entre serviços ao longo do tempo → view: seq, com at: tempos quando a espera importa. Escolha seq em vez de flow quando a ordem das chamadas e as esperas entre elas são o ponto, e flow quando os ramos são. Em que estado cada serviço está após cada mensagem → sets: id=*charging sob uma aresta e state: sob um nó.
• A vida de um campo ou job → view: states, um caminho por história (!giveup: running > blocked => dead). Um fluxo voltado ao usuário adiciona um ponto inicial ([*] -> form), tons e caixas group (visões).
• Quem chama quem → == tree. Uma pilha de chamadas em um momento, com os valores que deram errado → view: stack e locals:.

Quando, e por quanto tempo?

• O que executa ao mesmo tempo: uma corrida, trabalho sobreposto → == timing, uma pista por trabalhador e um !window sobre a sobreposição.
• Por que as retentativas se acumularam: backoff, jitter, o ponto de desistência, muitos clientes ao mesmo tempo → == retries, com policy:.
• Para onde vai a latência de uma requisição e qual cadeia a limita (caminho crítico, folga) → == gantt, encadeando barras com after; budget: desenha o limite, e was 140ms em uma linha alterada desenha a execução antiga abaixo dela.

Quanto?

• Como o volume se divide: uma divisão de tráfego, um funil, onde as requisições caem → view: sankey, com weight: sob cada caminho e caminhos que caem terminando em =| <nó de saída>. Use sankey em vez de ranks: quando o volume importar.
• Se é a cauda ou tudo (p50 vs p99, uma regressão de latência) → == hist, com was: para a distribuição antiga.
• Uma quantidade ao longo do tempo contra limites (profundidade de fila, lag, pool em uso), como estoque-e-fluxo → == stock, com faixas meter:. Para um padrão que se repete, plote uma janela típica e mencione qual.

Por que quebrou, e onde está travado?

• Quem segura qual bloqueio e quem espera por ele, um deadlock → == waits; ele encontra os ciclos.
• Causas suspeitas de um incidente, confirmadas ou descartadas → == causes, uma espinha de peixe.
• Itens de trabalho entre estágios (shards em um backfill, jobs em um pipeline), com limites de WIP e o que está bloqueado → == board, um kanban.
• Quais entradas uma verificação lê e quais gatilhos mantêm cada uma atualizada → == cover após o gráfico; uma matriz de escritor × campo → columns: <rank>.

O que mudou?

• Uma mudança em um layout → + e - em nós e caminhos; o leitor obtém um alternador antes | ambos | depois.
• O que uma mudança fez em uma árvore de chamadas → == diff, a partir do conversor em vez de manualmente. <viz> é o diretório desta skill; os dois primeiros argumentos são as refs base e head (branch base de um PR, então HEAD); <paths> limita a varredura:

python3 <viz>/scripts/viz.py calldiff main HEAD --max-depth 4 <paths>   # imprime base + == diff, subárvores inalteradas recolhidas
python3 <viz>/scripts/viz.py calltree --entry submitForm

Adicione a qualquer visão conforme necessário:

• O porquê de cada passo → uma cauda | payload | narration nos caminhos; cada um se torna um passo de replay.
• Um documento de design que percorre cenários → theme drawing, shows: id = text sob passos, e um meter: quando um número decide o resultado (desenho).
• Uma página que será salva, impressa ou compartilhada → theme paper. Ela pinta sua própria folha, então renderizações inline T3 mantêm o tema padrão.

Fundamente tudo em evidência. Cada nó recebe um @path:line e linhas de detalhe para leituras, escritas e comportamento de falha. Cada número (uma duração, um peso, um nível) vem de um trace, log, consulta ou código. Marque qualquer coisa que você não leu ou mediu com ?: um prefixo ? em um nó, caminho, barra ou segmento, e uma nota # estimate em um ponto de estoque.

Mostre-o

T3 Code (a lista de ferramentas tem html_render): escreva a página diretamente em html_preview, leia seu console para erros de parse viz:, então passe a mesma página para html_render. Não cole o viz.js.

<!doctype html><script src="https://cdn.jsdelivr.net/gh/Yeshwanthyk/agent-skills@efe8911d3765b764d7f0bf775e395d5201e29b16/skills/viz/assets/viz.js"></script>
<script type="text/viz">
…
</script>

Se o console de pré-visualização mostrar que o script falhou ao carregar, recorra à página abaixo (Em qualquer outro lugar) e informe ao usuário seu caminho. Nunca coloque viz.js inline em uma renderização T3: são cerca de 55k tokens por chamada.

Em qualquer outro lugar: salve os dados em /tmp/viz/<nome>.viz, então execute python3 <viz>/scripts/viz.py html /tmp/viz/<nome>.viz --open. Ele relata erros de parse, escreve /tmp/viz/<nome>.html com o renderizador inline e abre no navegador. No pi com glimpse instalado, abra esse arquivo lá em vez disso (pi). Informe o caminho.

Dentro de uma página salva que deve permanecer auto-contida (uma página que o usuário guarda ou compartilha): escreva blocos text/viz onde as visões pertencem, termine o body com <script data-viz></script>, e execute viz.py inline page.html. Reexecute após atualizar o viz.js. Atribua uma legenda de história, linha de tabela ou termo de glossário data-viz-id="<id do nó ou nome do caminho>" e passar o mouse sobre ele ilumina essa parte de cada gráfico na página, sem script de página.

Responda

O visual carrega a estrutura. A resposta adiciona apenas o que ele não pode mostrar: o que você não verificou, e a única coisa a olhar primeiro.

Conclusão

Concluído quando o visual renderiza sem erros viz:, cada nó e número está fundamentado ou marcado com ?, e você o viu onde o leitor irá procurar: inline no T3, ou uma captura de tela da página aberta em outro lugar. Um carregamento headless, um curl, ou um console limpo não é vê-lo; quando você não pôde olhar, diga isso em vez de chamá-lo de renderizado.