Yeshwanthyk/viz

¿Qué hace viz?

Un renderizador fijo, assets/viz.js, dibuja cada visual. El agente solo escribe datos en la gramática, por lo que un visual cuesta aproximadamente tantos tokens como el árbol ASCII que reemplaza. A cambio, obtiene reproducción paso a paso, un inspector de nodos, trazado de aristas, filtrado y copia de rutas.

Elige la vista

Escribe datos, no HTML: una sección == graph (nodos, rutas y un view:) o una sección de gráfico. Elige según la pregunta que se hace el lector, luego lee solo la gramática que necesita: gramática para grafos, árboles y diffs, gráficos para == timing, gantt, hist, retries, causes, board, stock y waits.

¿Cómo fluye?

• Datos que se mueven entre componentes (ramas, fallos, saltos asíncronos, salidas por error) → view: flow, la opción por defecto. "Guíame" añade una cola de narración (abajo). Etiqueta cada arista con lo que se mueve y declara las aristas en el orden en que ocurren; los números siguen.
• Quién actúa, qué envía, qué lo filtra, qué resultado da → ranks: columnas, una ruta por disparador, terminando en => result cuando llega y =| result cuando es filtrado. Equipos o servicios como bandas → añade lane:.
• Solicitudes entre servicios a lo largo del tiempo → view: seq, con horas at: cuando la espera importa. Elige seq sobre flow cuando el orden de las llamadas y las esperas entre ellas son el punto, y flow cuando lo son las ramas. En qué estado está cada servicio después de cada mensaje → sets: id=*charging bajo una arista y state: bajo un nodo.
• La vida de un campo o trabajo → view: states, una ruta por historia (!giveup: running > blocked => dead). Un flujo orientado al usuario añade un punto de inicio ([*] -> form), tonos y cuadros group (vistas).
• Quién llama a quién → == tree. Una pila de llamadas en un momento dado, con los valores que fallaron → view: stack y locals:.

¿Cuándo y durante cuánto tiempo?

• Qué se ejecuta al mismo tiempo: una carrera, trabajo superpuesto → == timing, un carril por trabajador y un !window sobre la superposición.
• Por qué se acumularon los reintentos: backoff, jitter, el punto de abandono, muchos clientes a la vez → == retries, con policy:.
• Dónde va la latencia de una solicitud y qué cadena la limita (ruta crítica, margen) → == gantt, encadenando barras con after; budget: dibuja el límite, y was 140ms en una fila cambiada dibuja la ejecución anterior debajo.

¿Cuánto?

• Cómo se divide el volumen: una división de tráfico, un embudo, dónde se pierden las solicitudes → view: sankey, con weight: bajo cada ruta y las rutas que se pierden terminando en =| <nodo de salida>. Usa sankey sobre ranks: cuando el volumen importa.
• Si es la cola o todo (p50 vs p99, una regresión de latencia) → == hist, con was: para la distribución anterior.
• Una cantidad a lo largo del tiempo contra umbrales (profundidad de cola, retraso, grupo en uso), como stock-y-flujo → == stock, con bandas meter:. Para un patrón que se repite, traza una ventana típica y di cuál.

¿Por qué se rompió y dónde está atascado?

• Quién tiene cada bloqueo y quién espera por él, un bloqueo → == waits; encuentra los ciclos.
• Las causas sospechosas de un incidente, confirmadas o descartadas → == causes, una espina de pescado.
• Elementos de trabajo a través de etapas (fragmentos en un relleno, trabajos en un pipeline), con límites de WIP y lo que está bloqueado → == board, un kanban.
• Qué entradas lee una comprobación y qué desencadenantes mantienen cada una actualizada → == cover después del grafo; una matriz escritor × campo → columns: <rank>.

¿Qué cambió?

• Un cambio en un diseño → + y - en nodos y rutas; el lector obtiene un alternador anterior | ambos | posterior.
• Lo que un cambio hizo a un árbol de llamadas → == diff, desde el convertidor en lugar de a mano. <viz> es el directorio de este skill; los dos primeros argumentos son la referencia base y la cabeza (la rama base de un PR, luego HEAD); <paths> limita el escaneo:

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

Añade a cualquier vista según sea necesario:

• El porqué de cada paso → una cola | payload | narración en las rutas; cada una se convierte en un paso de reproducción.
• Un documento de diseño que recorre escenarios → theme drawing, shows: id = text bajo los pasos, y un meter: cuando un número decide el resultado (dibujo).
• Una página que se guardará, imprimirá o compartirá → theme paper. Pinta su propia hoja, por lo que los renderizados en línea de T3 mantienen el tema por defecto.

Fundamenta todo en evidencia. Cada nodo recibe un @ruta:línea y líneas de detalle para lecturas, escrituras y comportamiento de fallo. Cada número (una duración, un peso, un nivel) proviene de un trace, un log, una consulta o el código. Marca cualquier cosa que no hayas leído o medido con ?: un prefijo ? en un nodo, ruta, barra o segmento, y una nota # estimación en un punto de stock.

Muéstralo

T3 Code (la lista de herramientas tiene html_render): escribe la página directamente en html_preview, lee su consola en busca de errores de análisis viz:, luego pasa la misma página a html_render. No pegues 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>

Si la consola de vista previa muestra que el script no se cargó, recurre a la página a continuación (En cualquier otro lugar) y dale al usuario su ruta. Nunca incrustes viz.js en un renderizado T3: son unos 55k tokens por llamada.

En cualquier otro lugar: guarda los datos en /tmp/viz/<nombre>.viz, luego ejecuta python3 <viz>/scripts/viz.py html /tmp/viz/<nombre>.viz --open. Reporta errores de análisis, escribe /tmp/viz/<nombre>.html con el renderizador incrustado y lo abre en el navegador. En pi con glimpse instalado, abre ese archivo allí en su lugar (pi). Reporta la ruta.

Dentro de una página guardada que debe permanecer autocontenida (una página que el usuario conserva o comparte): escribe bloques text/viz donde pertenezcan las vistas, termina el body con <script data-viz></script>, y ejecuta viz.py inline page.html. Vuelve a ejecutarlo después de actualizar viz.js. Dale a un título de historia, fila de tabla o término de glosario data-viz-id="<id de nodo o nombre de ruta>" y al pasar el ratón se iluminará esa parte de cada grafo en la página, sin ningún script de página.

Responde

El visual lleva la estructura. La respuesta añade solo lo que no puede mostrar: lo que no verificaste, y lo único que debes mirar primero.

Finalización

Hecho cuando el visual se renderiza sin errores viz:, cada nodo y número está fundamentado o marcado con ?, y lo has visto donde el lector lo mirará: en línea en T3, o una captura de pantalla de la página abierta en otro lugar. Una carga sin cabeza, un curl o una consola limpia no es verlo; cuando no pudiste mirar, dilo en lugar de llamarlo renderizado.