Zum Inhalt springen

Agent-Workflows ​

Neu in 0.4.0

Alles auf dieser Seite ist in v0.4.0 enthalten. Wenn ducklocal check --help --restricted nicht auflistet, ist Ihre Kopie älter; aktualisieren Sie sie, um das Flag zu nutzen.

Ein Agent kann bereits Dateien abfragen, ein Dashboard bauen und Ihre Kommentare mit der CLI lesen. Diese Ergänzungen decken ab, was rund um diese Arbeit passiert: SQL begrenzen, das jemand anderes geschrieben hat, wissen, was das Fenster mit einer Anfrage gemacht hat, Ihnen eine Änderung zur Freigabe vorlegen und festhalten, wie eine Antwort zustande kam.

SQL begrenzen, das Sie nicht geschrieben haben ​

--restricted ist für SQL gedacht, das aus Daten kopiert wurde, und für ein Dashboard, das jemand anderes geschrieben hat. Der Nur-Lese-Modus allein deckt das nicht ab: Er schützt die Datenbankdatei, während COPY weiterhin überall dorthin schreiben kann, wo Sie es können, und FROM 'https://...' weiterhin eine Anfrage senden kann.

bash
ducklocal query --restricted --allow-read ./data --sql "SELECT * FROM 'data/sales.csv'"
ducklocal check report.dash --restricted --allow-read ./data
Das SQL versuchtErgebnis
Eine Datei unter --allow-read zu lesenErlaubt
Eine andere Datei zu lesen, per Pfad, Glob oder ..Verweigert
Eine Datei zu schreiben, auch unter --allow-readVerweigert
Eine Datenbank per ATTACH zu öffnen oder eine anzulegenVerweigert
http, https, s3 oder eine andere URL zu erreichenVerweigert
Eine Erweiterung zu INSTALLieren oder zu LOADenVerweigert
Eine Einstellung zu ändern, auch diese GrenzenVerweigert
Länger als --timeout zu laufen (Standard 60 Sekunden)Unterbrochen, kind timeout
Mehr als --memory-limit zu nutzen (Standard 2GB)Schlägt fehl, kind resource_limit

Ohne --allow-read ist keine Datei lesbar, auch nicht der eigene Ordner eines Dashboards. Eine verweigerte Anweisung endet mit Exit-Code 1 und kind policy_denied und fällt nie darauf zurück, ohne Einschränkung zu laufen. EXPLAIN, PRAGMA und ein PIVOT auf oberster Ebene werden ebenfalls abgelehnt, weil die Anweisung ein einziges SELECT sein muss.

Das ist keine Sandbox. Die Grenzen sind DuckDBs eigene, und DuckLocal wendet auf keiner Plattform eine Isolation durch das Betriebssystem an. Sie binden das SQL, nicht den Aufrufer, der die Flags wählt: Ein Agent mit einer Shell kann --restricted weglassen. Wenn Sie einen Agenten einschränken wollen, dem Sie nicht trauen, führen Sie den Agenten selbst in einem Container oder einer VM aus. schema, profile, project check und open --run laufen nicht eingeschränkt, und das Fenster auch nicht, wenn es ein Dashboard öffnet.

Welche Grenzen für SQL gelten, das ein Agent ausführt, enthält das vollständige Bedrohungsmodell und was auf welcher Plattform getestet wurde.

Mit dem Fenster Schritt halten ​

ducklocal open meldete früher nur die Zustellung und sonst nichts. Zwei Flags melden jetzt, wie eine Anfrage geendet hat, und schützen davor, auf ein Fenster zu reagieren, das sich geändert hat.

bash
ducklocal open --state --active                  # note `revision`
ducklocal open --if-revision REV --run --wait \
  --title "Revenue by channel" --sql "SELECT ..."
  • --wait wartet bis zu 5 Minuten und ergänzt status, tab_id, result_status, error und revision in der Ausgabe.
  • --if-revision REV öffnet nichts, wenn das Fenster diese Revision nicht mehr zeigt, und endet mit Exit-Code 1 und kind stale. Lesen Sie den Zustand erneut, bevor Sie es noch einmal versuchen. Tippt eine Person in einem anderen Tab, wird die Revision absichtlich ebenfalls veraltet.

--state meldet jetzt zusätzlich:

FeldBedeutung
schema_version, revisionDie Version des Vertrags und ein Token für das, was das Fenster zeigt
actionsWas aus den letzten Anfragen wurde: stale, queued, running, opened, succeeded oder failed
limitsDie Grenzen für Vorschauen. Ein Lesevorgang liefert nie ein ganzes Ergebnis
connectionsEndpunkt und Region von S3 sowie Name, Art, Speicherort und Adresse jeder angebundenen Datenbank. Niemals ein Schlüssel
result.reachlocal, remote oder unknown, allein aus dem SQL gelesen, und ob Ihr S3-Schlüssel verwendet wurde
sql_withheldtrue, wenn das SQL eines Tabs ein Zugangsdatum enthalten könnte, und der Text ersetzt wird
scope, bei jedem PlotWie viel seiner Abfrage der Plot zeichnet

reach sieht nur, was das SQL nennt, daher liest sich eine lokale View über entfernte Daten als local. Nichts davon löst eine Netzwerkanfrage aus, location: "remote" sagt also, wo eine Datenbank liegt, nicht, dass sie noch antwortet.

Ein Agent kann sehen, dass S3 konfiguriert ist, ohne den Schlüssel zu sehen, aber SQL, das er mit open --run ausführt, kann diesen Schlüssel weiterhin verwenden.

Der Übergabe-Vertrag listet jedes Feld und jede Fehlerart, und das JSON-Schema beschreibt den Zustand.

Eine Dashboard-Änderung vorschlagen ​

Wenn Sie eine Änderung freigeben möchten, kann ein Agent sie vorschlagen, statt die Datei zu bearbeiten:

bash
ducklocal propose sales.dash --status                  # note current_hash
ducklocal propose sales.dash --from new.dash --note "Split revenue by region" --based-on HASH
ducklocal propose sales.dash --status                  # pending, applied or rejected

Die Spezifikation bleibt, wie sie ist, und der Dashboard-Tab zeigt, dass eine Änderung wartet. Klicken Sie auf Prüfen, um das vorgeschlagene SQL auszuführen und den Diff und die Prüfungen zu sehen, dann auf Übernehmen oder Verwerfen.

  • Nur Sie können einen Vorschlag anwenden, und zwar im Fenster. Es gibt keinen Befehl dafür.
  • Beim Anwenden bleibt die alte Version als sales.dash.bak erhalten; ist die Spezifikation seit dem Vorschlag geändert worden, wird abgelehnt.
  • Ein Verwerfen lässt die Spezifikation unverändert.
  • Ein Klick auf Prüfen führt das vorgeschlagene SQL aus, ein Vorschlag, dem Sie nicht trauen, kann also alles erreichen, was das SQL des Dashboards erreicht. Führen Sie vorher check --restricted darauf aus.

Festhalten, wie eine Analyse zustande kam ​

Setzen Sie DUCKLOCAL_SESSION, und query, check, propose und open zeichnen jeweils auf, was sie getan haben:

bash
export DUCKLOCAL_SESSION=analysis.session.jsonl
ducklocal session note --text "EU revenue fell 12%" --refs 3,4
ducklocal session show --last 20

Ohne diese Variable wird nichts aufgezeichnet. Die Datei enthält SQL- und Spezifikationstext, Größe und Änderungszeit jeder Quelle und die Form jedes Ergebnisses, nie dessen Zeilen. Fehler werden bis zu 500 Zeichen lang aufbewahrt und können Werte zitieren; halten Sie die Datei daher aus gemeinsamen Ordnern heraus, wenn Sie sie nicht teilen wollen.

Jeder Schritt und jede Schlussfolgerung hat doubts, ermittelt beim Lesen der Datei: was fehlschlug, abgeschnitten wurde oder sich seither geändert hat. Eine leere Liste bedeutet, dass nichts dagegen bekannt ist, nicht, dass es richtig ist.

SQL, das ein Zugangsdatum enthalten könnte, wird ausgelassen. Diese Prüfung geht nach Wörtern wie secret, token und access_key, eine Spalte mit einem dieser Namen verbirgt also ebenfalls ihre Abfrage.

Eine Analyse portabel halten ​

bash
ducklocal project init             # write ducklocal-project.json
ducklocal project check            # what a move would break
ducklocal project relink --source orders --to data/2026/orders.csv

Eine ducklocal-project.json ist optional. Sie listet die Dashboards eines Ordners und was sie brauchen; Daten werden referenziert, nie kopiert. Öffnen Sie sie im Fenster, öffnen sich diese Dashboards.

project check meldet ok, portable, problems (jeweils mit einem hint) und limitations und endet mit Exit-Code 0, egal was es findet; lesen Sie die Ausgabe also. Es erreicht nie das Netzwerk und installiert nichts. Ein bestandener Lauf beweist nicht, dass die Daten gleich sind. project relink ändert Ihre Dashboards und behält jedes alte als NAME.dash.bak.

Ein durchgearbeitetes Beispiel ​

Ein geleakter Schlüssel, untersucht von einem Agenten und einer Person führt durch eine erfundene Woche CloudTrail von der ersten Abfrage bis zu einem geprüften Dashboard. Ein Test führt bei jeder Änderung die Hälfte des Agenten aus. Die Hälfte des Fensters in diesem Beispiel hat noch niemand durchgeklickt, und die README nennt die betroffenen Schritte.

Veröffentlicht unter der Apache-2.0-Lizenz.