Stesso prompt, stesso diagramma

Prateek Rai ha rilasciato tldraw-canvas-kit, una collezione di 19 "Agent Skills" che permettono ad assistenti AI locali come Claude Code o Cursor di pilotare l'app desktop offline di tldraw e produrre diagrammi ingegneristici identici ogni volta. Il kit funziona senza alcuna connessione cloud o telemetria, il che significa che i team possono mantenere i propri asset visivi interamente on-premises.

Perché uno strumento di diagrammazione locale e deterministico è importante

I team di ingegneria passano ore a spostare diagrammi di flusso, diagrammi delle classi e mappe di architettura tra presentazioni, siti di documentazione e strumenti di progettazione. Ogni passaggio di copia-incolla introduce sottili cambiamenti: lo stile delle linee cambia, gli ID vengono rigenerati, i layout si spostano. Quando un diagramma viene rigenerato da un LLM, il risultato è spesso una disposizione diversa, anche se il prompt testuale rimane invariato. Per le organizzazioni che necessitano di documentazione pronta per l'audit o di artefatti di progettazione riproducibili, tale variabilità rappresenta un rischio.

Prateek ha creato tldraw-canvas-kit per affrontare due criticità: (1) uno strumento che gira interamente sulla macchina dell'utente, e (2) la garanzia che lo stesso prompt produca lo stesso diagramma. Esponendo un'API HTTP locale che l'agente AI può chiamare, il kit elimina la latenza di rete, il rischio di esfiltrazione dei dati e la necessità di un abbonamento SaaS.

Come funziona il kit

  • Core offline – L'app desktop di tldraw esegue un server locale che accetta comandi codificati in JSON. Non vengono effettuate chiamate esterne e nessun dato di utilizzo lascia la macchina.
  • Agent Skills – Ogni skill codifica una specifica struttura fissa: calcoli di layout, scelte di stencil e ID stabili. Quando un agente invoca una skill, riceve un set deterministico di istruzioni di disegno.
  • Aggiornamenti idempotenti – Se una skill viene eseguita su un diagramma esistente, aggiorna le forme sul posto, rimuove gli elementi obsoleti e ri-ancora i bordi. Il risultato è una canvas che può essere aggiornata senza accumulare oggetti duplicati.
  • Formato file – I diagrammi sono salvati come semplici file .tldraw. Poiché la logica di layout risiede all'interno del file, la condivisione di un set include automaticamente le regole di navigazione necessarie per riprodurre la visualizzazione.

Il kit supporta tredici categorie di diagrammi, che vanno da sequenza e diagrammi di flusso a diagrammi ER, macchine a stati, swimlane, casi d'uso, componenti, pacchetti, deployment, architettura, mappe mentali e mappe della base di codice. Gli utenti devono solo descrivere il diagramma desiderato; la skill gestisce la struttura sottostante.

Lezioni apprese durante lo sviluppo

  1. Lo stile delle frecce è impostato di default su un aspetto disegnato a mano – Anche quando viene richiesta una linea pulita, l'API inizialmente crea una freccia in stile schizzo. La skill deve emettere un comando successivo per cambiare lo stile.
  2. Le frecce possono intersecare le forme silenziosamente – L'API non segnala errori se un connettore passa attraverso un nodo. È necessaria un'ispezione visiva degli screenshot generati per rilevare tali collisioni.
  3. L'andata a capo delle etichette dei bordi si rompe sulle frecce corte – Le etichette potrebbero andare a capo male se il connettore è troppo corto, quindi la skill deve imporre una lunghezza minima o regolare il posizionamento dell'etichetta.

Queste particolarità illustrano perché le skill sono state costruite sul comportamento reale dell'API piuttosto che su supposizioni al riguardo.

Installazione e utilizzo del kit

npx skills add prateek11rai/tldraw-canvas-kit

Il comando funziona su macOS e Linux. Dopo l'installazione, un agente AI sulla stessa workstation può interrogare i documenti locali, generare codice e inviare comandi di disegno al server tldraw in esecuzione. Il risultato è un diagramma riproducibile che può essere ulteriormente modificato o esportato in presentazioni senza mai lasciare l'host.

Chi ne beneficia e quali sono i compromessi

  • Team focalizzati sulla sicurezza – Le aziende con rigide politiche di gestione dei dati possono mantenere tutti gli artefatti di progettazione dietro i propri firewall.
  • Ingegneri della documentazione – Coloro che hanno bisogno di incorporare diagrammi in repository controllati da versioni ottengono una fonte di verità deterministica.
  • Contributori individuali – Gli sviluppatori stanchi di regolare manualmente i layout dopo ogni esecuzione di un LLM possono automatizzare il processo.

Il limite principale è la dipendenza da un'istanza tldraw in esecuzione localmente. Le organizzazioni che già si affidano a servizi di diagrammazione basati su cloud dovranno adottare l'app desktop e adattare i flussi di lavoro. Inoltre, l'attuale set di skill non copre librerie di stencil personalizzate; gli utenti devono lavorare all'interno delle forme predefinite.

Prossimi passi

Prateek ha in programma di espandere la libreria di skill sulla base dei feedback della community e di aggiungere il supporto per Windows, ampliando così la base di utenti potenziali. Spera inoltre che agenti di terze parti integrino il kit, creando un marketplace di generatori di diagrammi specializzati che condividano tutti lo stesso core deterministico.

In sintesi

tldraw-canvas-kit dimostra che la creazione di diagrammi guidata dall'IA non deve necessariamente essere un processo probabilistico basato esclusivamente sul cloud. Ancorando la logica di disegno a un'API locale e imponendo identificatori stabili, permette agli ingegneri di generare visualizzazioni ripetibili e pronte per l'audit, senza sacrificare la privacy o il controllo.