Même prompt, même diagramme

Prateek Rai a publié tldraw-canvas-kit, une collection de 19 « Agent Skills » qui permettent aux assistants IA locaux tels que Claude Code ou Cursor de piloter l'application de bureau tldraw hors ligne et de produire des diagrammes d'ingénierie identiques à chaque fois. Le kit fonctionne sans aucune connexion cloud ni télémétrie, ce qui signifie que les équipes peuvent conserver leurs actifs visuels entièrement sur site.

Pourquoi un outil de diagramme local et déterministe est important

Les équipes d'ingénierie passent des heures à déplacer des organigrammes, des diagrammes de classes et des cartes d'architecture entre des présentations, des sites de documentation et des outils de conception. Chaque étape de copier-coller introduit des changements subtils : les styles de ligne changent, les identifiants sont régénérés, les mises en page dérivent. Lorsqu'un diagramme est régénéré par un LLM, le résultat est souvent une disposition différente, même si le prompt textuel reste inchangé. Pour les organisations qui ont besoin d'une documentation prête pour l'audit ou d'artefacts de conception reproductibles, cette variabilité est un risque.

Prateek a conçu tldraw-canvas-kit pour répondre à deux problèmes majeurs : (1) un outil qui s'exécute entièrement sur la machine de l'utilisateur, et (2) la garantie que le même prompt produit le même diagramme. En exposant une API HTTP locale que l'agent IA peut appeler, le kit élimine la latence réseau, le risque d'exfiltration de données et le besoin d'un abonnement SaaS.

Comment fonctionne le kit

  • Noyau hors ligne – L'application de bureau tldraw exécute un serveur local qui accepte des commandes encodées en JSON. Aucun appel externe n'est effectué et aucune donnée d'utilisation ne quitte la machine.
  • Agent Skills – Chaque compétence encode une spécification de structure fixe : calculs de mise en page, choix de pochoirs (stencils) et identifiants stables. Lorsqu'un agent invoque une compétence, il reçoit un ensemble déterministe d'instructions de dessin.
  • Mises à jour idempotentes – Si une compétence est appliquée à un diagramme existant, elle met à jour les formes sur place, supprime les éléments obsolètes et réancre les segments. Le résultat est un canevas qui peut être rafraîchi sans accumuler d'objets en double.
  • Format de fichier – Les diagrammes sont stockés sous forme de fichiers .tldraw simples. Comme la logique de mise en page réside à l'intérieur du fichier, le partage d'une présentation inclut automatiquement les règles de navigation nécessaires pour reproduire la vue.

Le kit prend en charge treize catégories de diagrammes, allant des diagrammes de séquence et des organigrammes aux diagrammes ER, machines à états, couloirs (swimlanes), cas d'utilisation, composants, packages, déploiement, architecture, cartes mentales (mind maps) et cartes de base de code. Les utilisateurs décrivent simplement le diagramme souhaité ; la compétence gère la structure sous-jacente.

Leçons apprises lors du développement

  1. Le style des flèches est par défaut de type « dessiné à la main » – Même lorsqu'une ligne nette est demandée, l'API crée initialement une flèche de style croquis. La compétence doit émettre une commande de suivi pour changer le style.
  2. Les flèches peuvent traverser les formes sans avertissement – L'API ne génère pas d'erreur si un connecteur passe à travers un nœud. Une inspection visuelle des captures d'écran générées est nécessaire pour détecter de telles collisions.
  3. Le retour à la ligne des étiquettes de segment échoue sur les flèches courtes – Les étiquettes peuvent mal s'afficher si le connecteur est trop court, la compétence doit donc imposer une longueur minimale ou ajuster le placement de l'étiquette.

Ces particularités illustrent pourquoi les compétences ont été construites sur le comportement réel de l'API plutôt que sur des suppositions à son sujet.

Installation et utilisation du kit

npx skills add prateek11rai/tldraw-canvas-kit

La commande fonctionne sur macOS et Linux. Après l'installation, un agent IA sur la même station de travail peut interroger des documents locaux, générer du code et envoyer des commandes de dessin au serveur tldraw en cours d'exécution. Le résultat est un diagramme reproductible qui peut être édité davantage ou exporté vers des présentations sans jamais quitter l'hôte.

Qui en bénéficie et quels sont les compromis

  • Équipes axées sur la sécurité – Les entreprises ayant des politiques strictes de manipulation des données peuvent conserver tous les artefacts de conception derrière leurs pare-feu.
  • Ingénieurs de documentation – Ceux qui doivent intégrer des diagrammes dans des dépôts gérés par version obtiennent une source de vérité déterministe.
  • Contributeurs individuels – Les développeurs fatigués d'ajuster manuellement les mises en page après chaque exécution de LLM peuvent automatiser le processus.

La principale limitation est la dépendance à une instance tldraw s'exécutant localement. Les organisations qui dépendent déjà de services de diagrammes basés sur le cloud devront adopter l'application de bureau et ajuster leurs flux de travail. De plus, l'ensemble actuel de compétences ne couvre pas les bibliothèques de pochoirs personnalisées ; les utilisateurs doivent travailler avec les formes prédéfinies.

La suite

Prateek prévoit d'étendre la bibliothèque de compétences en se basant sur les retours de la communauté et d'ajouter la prise en charge de Windows, élargissant ainsi la base d'utilisateurs potentiels. Il espère également voir des agents tiers intégrer le kit, créant ainsi un marché de générateurs de diagrammes spécialisés qui partagent tous le même noyau déterministe.

À retenir

tldraw-canvas-kit prouve que la création de diagrammes pilotée par l'IA n'a pas obligatoirement besoin d'être un processus probabiliste exclusivement basé sur le cloud. En ancrant la logique de dessin dans une API locale et en imposant des identifiants stables, il permet aux ingénieurs de générer des visuels reproductibles et prêts pour l'audit, sans sacrifier la confidentialité ou le contrôle.