agent-draw

Eine agentenorientierte technische Leinwand. Menschen ordnen und inspizieren eine tldraw-Leinwand; Agenten lesen und patchen ein renderer-unabhängiges, versioniertes Graphdokument.

Alpha: Die Dokumentgrenze ist bewusst gesetzt; das Plugin-SDK und die Kompatibilitätsgarantien entwickeln sich noch weiter.

Der erste vertikale Schnitt umfasst:

• eine tldraw-basierte technische Leinwand mit API-, Service-, Datenbank-, Tabellen-, Datei- und Externsystem-Blöcken;

• inspizierbare Tabellenspalten und semantische Kanten für Datenbankbesitz, Service-Lesezugriffe und Fremdschlüsselreferenzen;

• benutzerdefinierte React-Knotenformen mit benannten Ein-/Ausgabe-Handles und typisierten, verbindenden Kanten;

• kanonisches agent-draw/0.1-JSON mit stabilen IDs, semantischen Kanten, benannten Ansichten, Fähigkeiten und vorwärtskompatiblen Erweiterungen;

• agent-draw-patch/0.1-Operationen mit optimistischen Revisionsprüfungen;

• Build-Zeit-Plugin-Registrierung mit namespaced Knotentypen und deklarierten Fähigkeiten;

• einen API-Inspektor, der HTTP-Anfragen über eine geschützte lokale Fähigkeitslaufzeit bearbeitet und ausführt;

• JSON-Import/-Export und browserlokale Persistenz;

• eine TypeScript-CLI und einen stdio-MCP-Server für agentenverfasste Lesevorgänge, Importe, Verbindungsvorschläge und optimistische Patches.

Ausführen

Voraussetzungen: Node 20+ und pnpm.

pnpm install
pnpm dev

Öffnen Sie http://127.0.0.1:4173. Die Leinwandlaufzeit lauscht nur auf 127.0.0.1:4174 und Vite proxyt /api dorthin.

Verwenden Sie den Beispiel-Picker in der Kopfzeile oder öffnen Sie ein Beispiel direkt:

• /?sample=system-map

• /?sample=agent-loop

• /?sample=plugin-system

• /?sample=openapi-projects

pnpm test
pnpm typecheck
pnpm build

Related MCP server: tldraw MCP Server

Agenten-Workflow

1. Exportieren Sie ein .agent-draw.json-Dokument aus der UI oder lesen Sie eines aus dem Projekt.

2. Bewahren Sie IDs und unbekannte extensions-Felder.

3. Bevorzugen Sie einen kleinen agent-draw-patch/0.1-Vorschlag gegenüber dem Neuschreiben des gesamten Dokuments.

4. Setzen Sie baseRevision auf die Revision des Quelldokuments.

5. Ändern Sie semantische Felder getrennt vom Layout (setLayout).

6. Validieren Sie vor dem Anwenden. Ein veralteter Patch muss gegen die neueste Revision neu generiert werden.

Siehe das Beispiel-Patch und Formatreferenz.

Die CLI stellt dieselben Modelloperationen bereit, die auch die Leinwand verwendet:

pnpm agent-draw validate path/to/map.agent-draw.json
pnpm agent-draw import-openapi openapi.yaml -o map.agent-draw.json
pnpm agent-draw connect map.agent-draw.json \
  --source service-api/calls \
  --target database-projects/query \
  -o connection.agent-draw-patch.json
pnpm agent-draw apply map.agent-draw.json connection.agent-draw-patch.json --write

MCP-Server

pnpm mcp führt den TypeScript-stdio-Server aus. Richten Sie einen MCP-Client auf das Projekt und beschränken Sie dessen Dateizugriff mit AGENT_DRAW_ROOT:

{
  "mcpServers": {
    "agent-draw": {
      "command": "pnpm",
      "args": ["--dir", "/absolute/path/to/agent-draw", "mcp"],
      "env": { "AGENT_DRAW_ROOT": "/absolute/path/to/your/project" }
    }
  }
}

Der erste Tool-Satz ist bewusst auf Graphebene angesiedelt: read_document, list_plugins, propose_connection, apply_patch und import_openapi. Siehe Agent-Tools.

Sicherheitsmodell

Diagrammdateien enthalten Fähigkeitsreferenzen, niemals Anmeldedaten. Der Host besitzt die Fähigkeitsgewährungen. Die MVP-HTTP-Laufzeit:

• unterstützt nur explizite HTTP-Methoden;

• blockiert localhost, private, link-lokale, .local-Adressen, eingebettete Anmeldedaten, Weiterleitungen und Nicht-HTTP-Schemata;

• begrenzt Eingabe-/Body-Größen, Antwortgröße und Dauer;

• führt nur aus, nachdem der Mensch Anfrage ausführen gedrückt hat.

Dies ist eine nützliche Basislinie, keine produktionsreife Netzwerk-Sandbox. Eine bereitgestellte Version sollte auch die Ausführung isolieren, DNS zur Verbindungszeit erneut auflösen, pro-Bereich-Allowlists hinzufügen und überprüfbare Gewährungen speichern.

Architektur

src/model ist die Quelle der Wahrheit. src/canvasAdapter.ts ist der tldraw-Adapter. src/plugins enthält Manifeste und semantische Helfer. src/runtime ist der Browser-Client; server ist die vertrauenswürdige lokale Fähigkeitslaufzeit.

Die Leinwand übernimmt die nützlichen Interaktionssemantiken von React Flow – sichtbare Handles, kompatible Endpunkte und typisierte Verbindungen – ohne einen zweiten Szenengraphen zu übernehmen. tldraw besitzt Auswahl, Kamera, räumliche Transformationen und Rendering. Das kanonische Agent-Draw-Dokument besitzt Knoten-IDs, Ports, Kanten und Revisionen. Eine UI-Geste wird in denselben agent-draw-patch/0.1-Vorschlag übersetzt, der auch von CLI und MCP-Server verwendet wird.

Die Plugin-Grenze übernimmt die nützliche Trennung von BB zwischen einem deklarativen Manifest, Frontend-Oberflächen und begrenzten Host-Fähigkeiten. Sie setzt den tldraw-Store bewusst nicht als Plugin-Vertrag ein.

Konfigurierbarkeitsrichtung

Die aktuellen Blöcke sind In-Process-TypeScript-Plugins. Der beabsichtigte nächste Schritt ist, die meisten Blöcke deklarativ zu machen, ohne das kanonische Modell zu schwächen:

1. Block-Schema: Manifeste deklarieren Felder, Ports, Standardwerte, Darstellung und kompatible Beziehungen.

2. Generierter Inspektor: Der Host rendert gewöhnliche Feld-Editoren aus diesem Schema; Plugins stellen benutzerdefinierte React-Panels nur für wirklich spezialisierte Interaktionen bereit.

3. Importeure und Adapter: SQL/ORM/OpenAPI/Repository-Scanner übersetzen externe Systeme in stabile Knoten und Patches mit Herkunftsnachweis.

4. Host-Fähigkeiten: Blöcke referenzieren Connector- oder Secret-IDs, während der vertrauenswürdige Host Anmeldedaten besitzt und Laufzeitaktionen genehmigt.

5. Agent-Tools: MCP stellt denselben Schema-Katalog und dieselben Patch-Operationen wie die UI bereit, sodass agentenverfasste Diagramme inspizierbar und überprüfbar bleiben.

Dies bietet gewöhnlichen Blöcken einen Low-Code-Pfad, während typisierte Ausstiegsmöglichkeiten für API-Ausführung, Live-Datenbankinspektion und andere umfangreichere Dienstprogramme erhalten bleiben.