Visual Explainer : de l'art terminal aux diagrammes HTML
Visual Explainer : de l'art terminal aux diagrammes HTML
Introduction
De nombreux développeurs continuent encore d'imprimer des sorties complexes du terminal en texte brut, mais l'art ASCII et les tableaux délimités par des pipes deviennent rapidement illisibles. Visual Explainer transforme tout diagramme terminal, diff de code ou revue de plan en une page HTML soignée et autonome — avec thèmes clair/ombre, graphiques Mermaid interactifs et présentations adaptées.
Le Problème
- L'art ASCII du terminal fonctionne pour un organigramme à boîte unique mais se fissure avec des diagrammes multi-boîtes.
- Les tableaux rendus avec
|et-semblent superbes sur le terminal mais s'effondrent ou se repliquent mal lorsqu'ils sont exportés ou partagés. - Préparer des présentations ou de la documentation à partir d'un diff brut est chronophage et sujet aux erreurs.
La Solution
Visual Explainer remplace la sortie encombrée du terminal par une page prête à l'emploi dans le navigateur qui préserve la structure, le style et l'interactivité. Elle est livrée avec plusieurs commandes pratiques qui détectent automatiquement l'instant où vous lancez une sortie complexe et génèrent la meilleure représentation HTML.
Fonctions Principales
| Fonctionnalité | Description |
|---|---|
/diff-review |
Crée une revue visuelle des diff avec diagrammes d'architecture avant/après, tableaux de bord KPI et revue de code structurée (Bon/Mauvais/Inesthétique). |
/plan-review |
Référence croisée d'un fichier de plan avec la base de code, signale les risques et produit des diagrammes d'architecture actuels vs prévus. |
/generate-web-diagram |
Transforme tout sujet de diagramme en une page HTML autonome, par ex. « dessinez un diagramme du flux d'authentification ». |
/generate-slides |
Convertit une invite en une présentation de qualité magazine, avec un indicateur optionnel --slides. |
/project-recap |
Capture l'activité récente d'un projet, affichant l'architecture, le journal de décisions et les points chauds de dette cognitive. |
/fact-check |
Vérifie les affirmations d'un document par rapport au code réel. |
Toutes les commandes déclenchent le même flux de travail sous-jacent : la compétence analyse votre demande, choisit le bon modèle de référence, récupère les données nécessaires depuis le dossier references/, puis écrit un fichier HTML dans ~/.agent/diagrams/. La page s'ouvre automatiquement dans votre navigateur par défaut.
Installation
Si vous êtes déjà utilisateur de pi, l'installation se fait en une seule ligne :
pi install https://github.com/nicobailon/visual-explainer
Pour les utilisateurs de Claude Code ou d'autres agents, il suffit de cloner dans le répertoire des compétences :
git clone https://github.com/nicobailon/visual-explainer.git ~/.claude/skills/visual-explainer
Aucune étape de compilation n'est requise ; l'outil ne dépend que d'un navigateur et, facultativement, du binaire surf-cli pour la génération d'images.
Utilisation de la compétence
Une démonstration rapide :
generate-web-diagram
dessine un diagramme de notre flux d'authentification
La compétence rendra un diagramme Mermaid, appliquera un thème clair/sombre, et ouvrira le fichier ~/.agent/diagrams/auth-flow.html dans votre navigateur.
Pour examiner une pull request récente :
diff-review #42
Par défaut, /diff-review compare la branche actuelle avec main. Vous pouvez également passer des références arbitraires :
diff-review abc123 # commit unique
diff-review main..HEAD # tous les commits en attente
diff-review main..dev-feature # branche entière
Pour créer une présentation à partir de votre revue de diff, ajoutez l'indicateur --slides :
diff-review --slides
Personnalisation
- Thème & mise en page – modifiez les fichiers CSS dans
references/css-patterns.mdpour choisir des palettes ou ajuster les animations. - Modèle – remplacez n'importe lequel des quatre modèles dans
templates/(par ex.architecture.html,data-table.html) ou créez le vôtre. - Répertoire de sortie & navigateur – modifiez les variables dans
SKILL.mdpour changer l'emplacement où les fichiers sont écrits ou la façon dont ils sont lancés.
Comme la compétence recharge les modèles à chaque exécution, vous pouvez itérer rapidement sans redémarrer l'agent.
Limites et compromis
- Pas de rendu inline dans le terminal – les résultats s'ouvrent dans un navigateur ; vous ne pouvez pas les voir dans le terminal lui‑même.
- Le changement de thème requiert un rechargement de page – les SVG Mermaid ne s'adaptent pas automatiquement aux changements de thème du système.
- Qualité dépendante du modèle – la sortie visuelle dépend de la capacité du LLM sous-jacent à générer du code Mermaid ou CSS.
Malgré ces limitations, Visual Explainer réduit significativement la friction de la conversion de texte brut en artefacts visuels pertinents.
Communauté & assistance
Le dépôt est activement maintenu et propose des mises à jour régulières, telles que des garde-fous anti-slop (v0.3.0). Les problèmes, demandes de fonctionnalités et demandes de fusion sont les bienvenus sur GitHub. Les 3,3 k étoiles reflètent une communauté de développeurs croissante qui utilise l'outil pour tout, des diagrammes ad-hoc aux documentations formelles.
Conclusion
Visual Explainer est une utilité développeur légère et open‑source qui transforme la sortie bruyante du terminal en pages HTML soignées ou en présentations. Grâce à quelques commandes slash, vous pouvez auto-générer des diagrammes d'architecture, des revues de diff, des audits de plan ou des decks de présentation — tout en gardant votre workflow dans l'environnement de l'agent. Essayez‑le et récupérez la clarté visuelle que votre codebase mérite.