Yeshwanthyk/viz

Que fait viz ?

Un moteur de rendu fixe, assets/viz.js, dessine toutes les visuels. L'agent n'écrit que des données dans la grammaire, de sorte qu'un visuel coûte environ autant de jetons que l'arbre ASCII qu'il remplace. En échange, il offre le rejeu par étape, un inspecteur de nœuds, le traçage d'arêtes, le filtrage et la copie de chemin.

Choisir la vue

Écrivez des données, pas du HTML : une section == graph (nœuds, chemins et une view:) ou une section de graphique. Choisissez en fonction de la question que se pose le lecteur, puis lisez uniquement la grammaire nécessaire : grammaire pour les graphes, arbres et diffs, graphiques pour == timing, gantt, hist, retries, causes, board, stock et waits.

Comment ça circule ?

• Données se déplaçant entre composants (branches, replis, sauts asynchrones, sorties d'échec) → view: flow, la valeur par défaut. "Guide-moi" ajoute une queue de narration (ci-dessous). Étiquetez chaque arête avec ce qui se déplace et déclarez les arêtes dans l'ordre où elles se produisent ; les chiffres suivent.
• Qui agit, ce qu'il envoie, ce qui le filtre, ce qui en résulte → ranks: colonnes, un chemin par déclencheur, se terminant par => result quand ça passe et =| result quand c'est filtré. Équipes ou services en bandes → ajoutez lane:.
• Requêtes entre services au fil du temps → view: seq, avec des at: moments quand l'attente compte. Préférez seq à flow quand l'ordre des appels et les attentes entre eux sont le sujet, et flow quand les branches le sont. Quel état chaque service après chaque message → sets: id=*charging sous une arête et state: sous un nœud.
• La vie d'un champ ou d'un travail → view: states, un chemin par histoire (!giveup: running > blocked => dead). Un flux utilisateur ajoute un point de départ ([*] -> form), des teintes et des boîtes group (vues).
• Qui appelle qui → == tree. Une pile d'appels à un instant donné, avec les valeurs erronées → view: stack et locals:.

Quand et pendant combien de temps ?

• Ce qui s'exécute en même temps : une course, du travail qui se chevauche → == timing, une voie par travailleur et une !window sur le chevauchement.
• Pourquoi les tentatives s'accumulent : backoff, gigue, point d'abandon, plusieurs clients à la fois → == retries, avec policy:.
• Où va la latence d'une requête et quelle chaîne la limite (chemin critique, mou) → == gantt, enchaînant les barres avec after ; budget: dessine la limite, et was 140ms sur une ligne modifiée dessine l'ancienne exécution en dessous.

Combien ?

• Comment le volume se répartit : une répartition de trafic, un entonnoir, où les requêtes chutent → view: sankey, avec weight: sous chaque chemin et les chemins qui chutent se terminant par =| <nœud de sortie>. Utilisez sankey plutôt que ranks: quand le volume compte.
• S'agit-il de la queue ou de tout (p50 vs p99, une régression de latence) → == hist, avec was: pour l'ancienne distribution.
• Une quantité au fil du temps par rapport à des seuils (profondeur de file d'attente, retard, pool utilisé), en stock et flux → == stock, avec des bandes meter:. Pour un motif qui se répète, tracez une fenêtre typique et dites laquelle.

Pourquoi ça a cassé et où ça bloque ?

• Qui détient quel verrou et qui l'attend, un interblocage → == waits ; il trouve les cycles.
• Les causes suspectées d'un incident, confirmées ou infirmées → == causes, un diagramme d'Ishikawa.
• Des éléments de travail à travers les étapes (shards dans un rattrapage, jobs dans un pipeline), avec des limites WIP et ce qui est bloqué → == board, un kanban.
• Quelles entrées une vérification lit et quels déclencheurs la maintiennent à jour → == cover après le graphique ; une matrice écrivain × champ → columns: <rank>.

Qu'est-ce qui a changé ?

• Un changement sur une mise en page → + et - sur les nœuds et les chemins ; le lecteur obtient un basculement avant | les deux | après.
• Ce qu'un changement a fait à un arbre d'appels → == diff, depuis le convertisseur plutôt qu'à la main. <viz> est le répertoire de cette compétence ; les deux premiers arguments sont les références de base et de tête (la branche de base d'une PR, puis HEAD) ; <paths> limite l'analyse :

python3 <viz>/scripts/viz.py calldiff main HEAD --max-depth 4 <paths>   # imprime base + == diff, sous-arbres inchangés réduits
python3 <viz>/scripts/viz.py calltree --entry submitForm

Ajoutez à n'importe quelle vue selon les besoins :

• Le pourquoi de chaque étape → une queue | payload | narration sur les chemins ; chacun devient une étape de rejeu.
• Un document de conception qui parcourt des scénarios → theme drawing, shows: id = text sous les étapes, et un meter: quand un nombre décide du résultat (dessin).
• Une page qui sera sauvegardée, imprimée ou partagée → theme paper. Elle peint sa propre feuille, donc les rendus T3 en ligne conservent le thème par défaut.

Fondez tout sur des preuves. Chaque nœud reçoit un @path:line et des lignes de détail pour les lectures, écritures et comportements d'échec. Chaque nombre (une durée, un poids, un niveau) provient d'une trace, d'un journal, d'une requête ou du code. Marquez tout ce que vous n'avez pas lu ou mesuré avec ? : un préfixe ? sur un nœud, un chemin, une barre ou un segment, et une note # estimate sur un point de stock.

Afficher

Code T3 (la liste d'outils contient html_render) : écrivez la page directement dans html_preview, lisez sa console pour les erreurs d'analyse viz:, puis passez la même page à html_render. Ne collez pas 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 console d'aperçu montre que le script n'a pas pu se charger, revenez à la page ci-dessous (Ailleurs) et donnez à l'utilisateur son chemin. N'intégrez jamais viz.js en ligne dans un rendu T3 : cela représente environ 55k jetons par appel.

Ailleurs : sauvegardez les données dans /tmp/viz/<nom>.viz, puis exécutez python3 <viz>/scripts/viz.py html /tmp/viz/<nom>.viz --open. Il signale les erreurs d'analyse, écrit /tmp/viz/<nom>.html avec le moteur de rendu intégré, et l'ouvre dans le navigateur. Sur pi avec glimpse installé, ouvrez ce fichier là-bas à la place (pi). Signalez le chemin.

Dans une page sauvegardée qui doit rester autonome (une page que l'utilisateur conserve ou partage) : écrivez des blocs text/viz là où les vues appartiennent, terminez le corps par <script data-viz></script>, et exécutez viz.py inline page.html. Réexécutez-le après avoir mis à jour viz.js. Donnez à une légende d'histoire, une ligne de tableau ou un terme de glossaire data-viz-id="<id de nœud ou nom de chemin>" et survoler allume cette partie de chaque graphique sur la page, sans script de page.

Répondre

Le visuel porte la structure. La réponse n'ajoute que ce qu'il ne peut pas montrer : ce que vous n'avez pas vérifié, et la chose à regarder en premier.

Achèvement

Terminé lorsque le visuel s'affiche sans erreurs viz:, chaque nœud et nombre est fondé ou marqué ?, et vous l'avez vu là où le lecteur regardera : en ligne dans T3, ou une capture d'écran de la page ouverte ailleurs. Un chargement sans tête, un curl, ou une console propre n'est pas le voir ; quand vous n'avez pas pu regarder, dites-le plutôt que de l'appeler rendu.