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.
ducklocal query --restricted --allow-read ./data --sql "SELECT * FROM 'data/sales.csv'"
ducklocal check report.dash --restricted --allow-read ./data| L'SQL tenta di | Risultato |
|---|---|
Leggere un file sotto --allow-read | Consentito |
Leggere qualsiasi altro file, per percorso, glob o .. | Negato |
Scrivere un file, anche sotto --allow-read | Negato |
Fare ATTACH a un database, o crearne uno | Negato |
Raggiungere http, https, s3 o qualsiasi altro URL | Negato |
INSTALL o LOAD un'estensione | Negato |
| Cambiare un'impostazione, compresi questi limiti | Negato |
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.
ducklocal open --state --active # note `revision`
ducklocal open --if-revision REV --run --wait \
--title "Revenue by channel" --sql "SELECT ..."--waitattende fino a 5 minuti e aggiungestatus,tab_id,result_status,errorerevisionall'output.--if-revision REVnon apre nulla se la finestra non mostra più quella revisione, ed esce con codice 1 e kindstale. Rileggi lo stato prima di riprovare. Anche una persona che digita in un'altra scheda lo rende obsoleto, di proposito.
--state ora riporta anche:
| Campo | Significato |
|---|---|
schema_version, revision | La versione del contratto e un token di ciò che mostra la finestra |
actions | Che fine hanno fatto le richieste recenti: stale, queued, running, opened, succeeded o failed |
limits | I limiti delle anteprime. Una lettura non restituisce mai un risultato intero |
connections | L'endpoint e la regione di S3, e nome, tipo, posizione e indirizzo di ogni database collegato. Mai una chiave |
result.reach | local, remote o unknown, dedotto solo dall'SQL, e se ha usato la tua chiave S3 |
sql_withheld | true quando l'SQL di una scheda può contenere una credenziale, e il testo viene sostituito |
scope, su ogni grafico | Quanta 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:
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 rejectedLa 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 --restrictedsu di essa.
Registra come si è arrivati a un'analisi
Imposta DUCKLOCAL_SESSION, e query, check, propose e open registrano ciascuno quello che hanno fatto:
export DUCKLOCAL_SESSION=analysis.session.jsonl
ducklocal session note --text "EU revenue fell 12%" --refs 3,4
ducklocal session show --last 20Senza 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
ducklocal project init # write ducklocal-project.json
ducklocal project check # what a move would break
ducklocal project relink --source orders --to data/2026/orders.csvUn 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.
