Dokumentation · QGIS-Plugin

Verbindung, Operationen und Freigaben im Plugin.

Das Plugin ist die QGIS-Seite des Systems; Projekte, Einrichtung und Betreuung übernimmt die Geoinformatikbüro Dassau GmbH (GBD). Es nimmt die Aufrufe der Bridge entgegen, prüft jeden Dateipfad, legt eingriffsreiche Anfragen vor und gibt Zustand, Bilder und Dateien zurück.

Zu den neun Gruppen System und Skills

Voraussetzungen

Was vorhanden sein muss.

Das Plugin läuft in QGIS Desktop ab Version 3.28. Die Nutzung unter Windows ist experimentell.

QGIS: Version 3.28 oder neuer, mit geöffnetem Projekt; das Plugin wird als ZIP installiert und im Plugin-Verwalter aktiviert. Die Druckvorlagen des Skills qgis-print-layouts setzen QGIS 3.34 oder neuer voraus.
CLI: Codex CLI, Claude Code oder OpenCode, installiert und angemeldet, bevor das Plugin sie startet.
Arbeitsverzeichnis: Ein Pfad, auf den QGIS und die CLI zugreifen. Er wird in den Plugin-Einstellungen eingetragen.
Netz: Keine Freigabe nach außen nötig. Die Verbindung endet auf demselben Rechner.

Verbindung

WebSocket auf 127.0.0.1, Port 64876.

Die Bridge läuft als eigener Prozess. Die CLI spricht sie über die Standardeingabe an, sie selbst hält die Verbindung zum Plugin. Die Gegenstelle ist die Rückschleife des eigenen Rechners.

Host   127.0.0.1
Port   64876
Token  in den Plugin-Einstellungen anzeigen, kopieren, neu erzeugen

Das Token wird im Plugin erzeugt und von dort in die Konfiguration der CLI übernommen. Eine Bindung an eine andere Adresse als die Rückschleife verlangt Tokenprüfung und TLS zugleich; ohne beides verweigert das Plugin den Start, weil ein Token auf einer offenen Leitung mitgelesen werden kann.

Operationen

Neun Gruppen, 67 Werkzeuge.

Jedes Werkzeug der Bridge entspricht einem Handler im Plugin. Die Handler liegen in neun Modulen; die Zahlen unten sind am 18. September 2026 gezählt.

Gruppe	Anzahl	Drei Beispiele
Projekt	3	`save_project`, `load_project`, `set_project_crs`
Zustand	7	`get_qgis_state`, `get_layer_details`, `get_raster_statistics`
Layer	23	`load_layers`, `set_graduated_style`, `set_layer_labels`
Objekte	9	`select_features`, `get_attribute_values`, `edit_features`
Karte	9	`map_navigation`, `get_map_screenshot`, `measure_distance`
Layouts	4	`load_layout_template`, `export_layout`, `list_layouts`
Aufträge	3	`start_job`, `get_job_status`, `cancel_job`
Plugins	6	`list_plugins`, `install_plugin`, `set_plugin_enabled`
Dateien	3	`upload_to_qgis`, `download_from_qgis`, `list_files`
Summe	67	Vollständige Signaturen stehen im Skill `spatial-agent-bridge`.

Zwei weitere Handler lesen abgeschnittene Antworten nach; sie sind Teil des Plugins, aber kein eigenes Werkzeug der Bridge.

Pfadregeln

Jeder Pfad wird vor QGIS geprüft.

Alle Werkzeuge mit einem Dateipfad — Bildausgabe, Layoutexport, Stil speichern, Projekt speichern, Layer exportieren, Dateitransfer, Verzeichnisliste — fragen dieselbe Prüfstelle, bevor QGIS den Pfad zu sehen bekommt.

Erlaubte Wurzeln: Der Pfad wird aufgelöst und muss unterhalb einer eingestellten Wurzel liegen. Sonst endet der Aufruf mit ACCESS_DENIED.
Überschreiben: Eine vorhandene Datei bleibt stehen: Der Aufruf endet mit FILE_EXISTS, bis er das Überschreiben ausdrücklich verlangt.
Lesen aus Skills: Zusätzlich lesbar sind die Vorlagen und Stile der mitgelieferten Skills. Geschrieben wird dorthin nie.
Fernquellen: Adressen mit http, https, WMS oder WFS sind keine Dateipfade und gehen an den Netzweg von QGIS.

Kartenbilder

Bild und Prüfsumme.

Ein Kartenbild kommt als Base64-PNG zurück oder wird im Arbeitsverzeichnis abgelegt. Zu jedem Bild gehört die SHA-256-Prüfsumme seines Inhalts.

Die Prüfsumme beantwortet eine Frage, die sich beim Prüfen eines Ergebnisses stellt: Hat sich das Bild nach der letzten Änderung tatsächlich geändert? Zwei gleiche Summen heißen gleiches Bild, unabhängig von Dateinamen und Zeitstempel. Dieselbe Summe steht auch an den Bildern, die aus einem Layout exportiert werden.

Asynchrone Aufträge

Lange Vorgänge laufen als Auftrag.

Ein synchroner Aufruf wartet höchstens 60 Sekunden. Export, Bildausgabe großer Layouts, Projektspeicherung und Massenänderungen an Objekten überschreiten das; sie werden deshalb als Auftrag gestartet und abgefragt.

pending → running → completed
                 → failed
                 → cancelling → cancelled

Ein Abbruch setzt ein Signal, das die laufende Arbeit an ihren Stufengrenzen prüft; erzwungen wird nichts. Was bis dahin entstanden ist, bleibt als Teilergebnis erhalten. Ein Auftrag, der vor dem Signal fertig wird, gilt als abgeschlossen, denn die Arbeit ist geschehen.

Dateien

Übertragung und Verzeichnisliste.

Im lokalen Betrieb teilen sich beide Seiten das Arbeitsverzeichnis, und eine Übertragung erübrigt sich. Im Containerbetrieb und bei Dateien außerhalb des geteilten Pfades bewegen zwei Werkzeuge sie in beide Richtungen.

Hinauf: upload_to_qgis schreibt eine Datei auf den Rechner, auf dem QGIS läuft. Grenze: 100 MB.
Herunter: download_from_qgis holt eine Datei zurück. Grenze: 32 MB, weil der Inhalt dabei vollständig in den Speicher geht.
Größeres: Was darüber liegt, wird über das gemeinsame Arbeitsverzeichnis ausgetauscht.
Liste: list_files zeigt den Inhalt erlaubter Verzeichnisse, seitenweise und mit Filter auf Namensmuster.

Grundsatz

In QGIS wird kein beliebiger Code ausgeführt.

Was in QGIS geschieht, geschieht über die neun Gruppen oben. Für die Ausführung eingereichten Python-Codes gibt es im Plugin keinen Handler, und die Bridge kündigt kein solches Werkzeug an.

Rechnen findet außerhalb statt, im gemeinsamen Arbeitsverzeichnis, und kommt als Datei zurück. Das kostet einen Zwischenschritt und bringt zwei Dinge ein: Ein Fehler in einer Berechnung kann die laufende QGIS-Sitzung nicht mitreißen, und jedes Zwischenergebnis liegt als prüfbare Datei vor.

System und Skills Geospatial API