Vai al contenuto

Flussi di lavoro per agenti ​

Novità nella 0.4.0

Tutto ciò che è descritto in questa pagina è arrivato con la v0.4.0. Se ducklocal check --help non elenca --restricted, la tua copia è più vecchia; aggiorna per usarlo.

Un agente può già interrogare file, creare una dashboard e leggere i tuoi commenti con la CLI. Queste aggiunte coprono ciò che accade intorno a quel lavoro: limitare l'SQL che non ha scritto, sapere cosa ha fatto la finestra con una richiesta, lasciarti approvare una modifica e registrare come si è arrivati a una risposta.

Limita l'SQL che non hai scritto ​

--restricted serve per l'SQL copiato dai dati e per una dashboard scritta da qualcun altro. La sola modalità di sola lettura non basta: protegge il file del database, mentre COPY può comunque scrivere ovunque tu possa e FROM 'https://...' può comunque inviare una richiesta.

bash
ducklocal query --restricted --allow-read ./data --sql "SELECT * FROM 'data/sales.csv'"
ducklocal check report.dash --restricted --allow-read ./data
L'SQL tenta diRisultato
Leggere un file sotto --allow-readConsentito
Leggere qualsiasi altro file, per percorso, glob o ..Negato
Scrivere un file, anche sotto --allow-readNegato
Fare ATTACH a un database, o crearne unoNegato
Raggiungere http, https, s3 o qualsiasi altro URLNegato
INSTALL o LOAD un'estensioneNegato
Cambiare un'impostazione, compresi questi limitiNegato
Eseguire più a lungo di --timeout (60 secondi per impostazione predefinita)Interrotto, kind timeout
Usare più di --memory-limit (2GB per impostazione predefinita)Fallisce, kind resource_limit

Senza --allow-read nessun file è leggibile, e questo include la cartella della dashboard stessa. Un'istruzione negata esce con codice 1 e kind policy_denied e non ripiega mai sull'esecuzione senza restrizioni. Anche EXPLAIN, PRAGMA e un PIVOT di primo livello vengono rifiutati, perché l'istruzione deve essere un solo SELECT.

Questa non è una sandbox. I limiti sono quelli di DuckDB e DuckLocal non applica alcun isolamento del sistema operativo su nessuna piattaforma. Vincolano l'SQL, non chi sceglie i flag: un agente con una shell può togliere --restricted. Per contenere un agente di cui non ti fidi, esegui l'agente stesso in un container o in una VM. schema, profile, project check e open --run non girano in modalità limitata, e nemmeno la finestra quando apre una dashboard.

Cosa limita l'SQL eseguito da un agente contiene il modello di minaccia completo e cosa è stato testato su ogni piattaforma.

Resta al passo con la finestra ​

ducklocal open in passato riportava soltanto la consegna. Ora due flag riportano come si è conclusa una richiesta e proteggono dall'agire su una finestra che è cambiata.

bash
ducklocal open --state --active                  # note `revision`
ducklocal open --if-revision REV --run --wait \
  --title "Revenue by channel" --sql "SELECT ..."
  • --wait attende fino a 5 minuti e aggiunge status, tab_id, result_status, error e revision all'output.
  • --if-revision REV non apre nulla se la finestra non mostra più quella revisione, ed esce con codice 1 e kind stale. Rileggi lo stato prima di riprovare. Anche una persona che digita in un'altra scheda lo rende obsoleto, di proposito.

--state ora riporta anche:

CampoSignificato
schema_version, revisionLa versione del contratto e un token di ciò che mostra la finestra
actionsChe fine hanno fatto le richieste recenti: stale, queued, running, opened, succeeded o failed
limitsI limiti delle anteprime. Una lettura non restituisce mai un risultato intero
connectionsL'endpoint e la regione di S3, e nome, tipo, posizione e indirizzo di ogni database collegato. Mai una chiave
result.reachlocal, remote o unknown, dedotto solo dall'SQL, e se ha usato la tua chiave S3
sql_withheldtrue quando l'SQL di una scheda può contenere una credenziale, e il testo viene sostituito
scope, su ogni graficoQuanta parte della sua query disegna il grafico

reach può vedere solo ciò che l'SQL nomina, quindi una vista locale su dati remoti risulta local. Leggere uno di questi dati non effettua alcuna richiesta di rete, quindi location: "remote" dice dove si trova un database, non che risponda ancora.

Un agente può vedere che S3 è configurato senza vedere la chiave, ma l'SQL che esegue con open --run può comunque usare quella chiave.

Il contratto di passaggio di consegne elenca ogni campo e tipo di errore, e lo schema JSON descrive lo stato.

Proponi una modifica a una dashboard ​

Quando vuoi approvare una modifica, un agente può proporla invece di modificare il file:

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

La specifica resta com'è, e la scheda della dashboard mostra che c'è una modifica in attesa. Fai clic su Rivedi per eseguire l'SQL proposto e vedere il diff e i controlli, poi fai clic su Applica o Rifiuta.

  • Solo tu puoi applicare una proposta, nella finestra. Non c'è un comando per farlo.
  • Applicare conserva la versione precedente come sales.dash.bak, e viene rifiutato se la specifica è cambiata dalla proposta.
  • Rifiutare lascia la specifica intatta.
  • Fare clic su Rivedi esegue l'SQL proposto, quindi una proposta di cui non ti fidi può raggiungere tutto ciò che può raggiungere l'SQL della dashboard. Esegui prima check --restricted su di essa.

Registra come si è arrivati a un'analisi ​

Imposta DUCKLOCAL_SESSION, e query, check, propose e open registrano ciascuno quello che hanno fatto:

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

Senza quella variabile non viene registrato nulla. Il file contiene testo SQL e delle specifiche, la dimensione e l'ora di modifica di ogni origine, e la forma di ogni risultato, mai le sue righe. Gli errori vengono conservati fino a 500 caratteri e possono citare valori, quindi tieni il file fuori dalle cartelle condivise a meno che tu non voglia condividerle.

Ogni passo e ogni conclusione ha doubts, calcolato quando leggi il file: cosa è fallito, è stato interrotto o è cambiato da allora. Un elenco vuoto significa che non si sa nulla contro di esso, non che sia giusto.

L'SQL che può contenere una credenziale viene omesso. Quel controllo si basa su parole come secret, token e access_key, quindi anche una colonna con uno di quei nomi nasconde la sua query.

Mantieni un'analisi spostabile ​

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

Un ducklocal-project.json è facoltativo. Elenca le dashboard di una cartella e ciò di cui hanno bisogno; i dati sono referenziati, mai copiati. Aprirlo nella finestra apre quelle dashboard.

project check riporta ok, portable, problems (ciascuno con un hint) e limitations, ed esce con 0 qualunque cosa trovi, quindi leggi l'output. Non accede mai alla rete né installa nulla. Il fatto che passi non dimostra che i dati siano gli stessi. project relink modifica le tue dashboard e conserva ogni vecchia versione come NAME.dash.bak.

Un esempio completo ​

Una chiave trapelata, indagata da un agente e da una persona percorre una settimana inventata di CloudTrail dalla prima query a una dashboard revisionata. Un test esegue la metà dell'agente a ogni modifica. Nessuno ha ancora fatto clic sulla metà della finestra di questo esempio, e il suo README indica quali passi sono.

Pubblicato con licenza Apache-2.0.