Flux de travail des agents
Nouveau dans la 0.4.0
Tout ce qui figure sur cette page est arrivé avec v0.4.0. Si ducklocal check --help n'affiche pas --restricted, votre copie est plus ancienne ; mettez-la à jour pour l'utiliser.
Un agent peut déjà interroger des fichiers, construire un tableau de bord et lire vos commentaires avec la CLI. Ces ajouts couvrent ce qui entoure ce travail : limiter du SQL qu'il n'a pas écrit, savoir ce que la fenêtre a fait d'une requête, vous laisser approuver une modification et enregistrer comment une réponse a été obtenue.
Limiter le SQL que vous n'avez pas écrit
--restricted s'adresse au SQL copié depuis des données et à un tableau de bord écrit par quelqu'un d'autre. Le mode lecture seule ne suffit pas : il protège le fichier de base de données, alors que COPY peut toujours écrire partout où vous pouvez écrire et que FROM 'https://...' peut toujours envoyer une requête.
ducklocal query --restricted --allow-read ./data --sql "SELECT * FROM 'data/sales.csv'"
ducklocal check report.dash --restricted --allow-read ./data| Ce que le SQL tente de faire | Résultat |
|---|---|
Lire un fichier sous --allow-read | Autorisé |
Lire tout autre fichier, par chemin, glob ou .. | Refusé |
Écrire un fichier, même sous --allow-read | Refusé |
ATTACH une base de données, ou en créer une | Refusé |
Atteindre http, https, s3 ou toute autre URL | Refusé |
INSTALL ou LOAD une extension | Refusé |
| Modifier un paramètre, y compris ces limites | Refusé |
S'exécuter plus longtemps que --timeout (60 secondes par défaut) | Interrompu, kind timeout |
Utiliser plus que --memory-limit (2GB par défaut) | Échec, kind resource_limit |
Sans --allow-read, aucun fichier n'est lisible, y compris le dossier du tableau de bord lui-même. Une instruction refusée se termine avec le code 1 et le kind policy_denied, et ne retombe jamais sur une exécution sans restriction. EXPLAIN, PRAGMA et un PIVOT de premier niveau sont eux aussi refusés, car l'instruction doit être un seul SELECT.
Ce n'est pas un bac à sable. Les limites sont celles de DuckDB, et DuckLocal n'applique aucune isolation du système d'exploitation, sur aucune plateforme. Elles lient le SQL, pas celui qui choisit les options : un agent disposant d'un shell peut retirer --restricted. Pour contenir un agent auquel vous ne faites pas confiance, exécutez l'agent lui-même dans un conteneur ou une VM. schema, profile, project check et open --run ne s'exécutent pas en mode restreint, et la fenêtre non plus lorsqu'elle ouvre un tableau de bord.
Ce qui limite le SQL exécuté par un agent contient le modèle de menace complet et ce qui a été testé sur chaque plateforme.
Rester synchronisé avec la fenêtre
ducklocal open ne signalait auparavant que la remise, rien de plus. Deux options indiquent désormais comment une requête s'est terminée et protègent contre une action sur une fenêtre qui a changé.
ducklocal open --state --active # note `revision`
ducklocal open --if-revision REV --run --wait \
--title "Revenue by channel" --sql "SELECT ..."--waitattend jusqu'à 5 minutes et ajoutestatus,tab_id,result_status,erroretrevisionà la sortie.--if-revision REVn'ouvre rien si la fenêtre n'affiche plus cette révision, et se termine avec le code 1 et le kindstale. Relisez l'état avant de réessayer. Une personne qui tape dans un autre onglet rend aussi l'état périmé, volontairement.
--state indique désormais aussi :
| Champ | Signification |
|---|---|
schema_version, revision | La version du contrat, et un jeton pour ce que la fenêtre affiche |
actions | Ce qu'il est advenu des requêtes récentes : stale, queued, running, opened, succeeded ou failed |
limits | Les bornes des aperçus. Une lecture ne renvoie jamais un résultat entier |
connections | Le point de terminaison et la région de S3, ainsi que le nom, le type, l'emplacement et l'adresse de chaque base de données attachée. Jamais une clé |
result.reach | local, remote ou unknown, déduit du SQL seul, et s'il a utilisé votre clé S3 |
sql_withheld | true quand le SQL d'un onglet peut contenir un identifiant, et le texte est remplacé |
scope, sur chaque graphique | La part de sa requête que le graphique dessine |
reach ne voit que ce que le SQL nomme : une vue locale sur des données distantes est donc lue comme local. La lecture de toutes ces informations n'effectue aucune requête réseau ; location: "remote" indique où se trouve une base de données, pas qu'elle répond encore.
Un agent peut constater que S3 est configuré sans voir la clé, mais le SQL qu'il exécute avec open --run peut encore utiliser cette clé.
Le contrat de passation liste chaque champ et chaque kind d'erreur, et le schéma JSON décrit l'état.
Proposer une modification de tableau de bord
Quand vous voulez approuver une modification, un agent peut la proposer au lieu de modifier le fichier :
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 spécification reste telle quelle, et l'onglet du tableau de bord montre qu'une modification est en attente. Cliquez sur Review pour exécuter le SQL proposé et voir le diff et les contrôles, puis cliquez sur Apply ou Reject.
- Vous seul pouvez appliquer une proposition, dans la fenêtre. Il n'existe aucune commande pour cela.
- L'appliquer conserve l'ancienne version sous
sales.dash.bak, et est refusé si la spécification a changé depuis la proposition. - Un refus laisse la spécification intacte.
- Cliquer sur Review exécute le SQL proposé : une proposition à laquelle vous ne faites pas confiance peut donc atteindre tout ce que le SQL du tableau de bord peut atteindre. Lancez d'abord
check --restricteddessus.
Enregistrer comment une analyse a été menée
Définissez DUCKLOCAL_SESSION, et query, check, propose et open enregistrent chacun ce qu'ils ont fait :
export DUCKLOCAL_SESSION=analysis.session.jsonl
ducklocal session note --text "EU revenue fell 12%" --refs 3,4
ducklocal session show --last 20Rien n'est enregistré sans cette variable. Le fichier contient le SQL et le texte des spécifications, la taille et la date de modification de chaque source, et la forme de chaque résultat, jamais ses lignes. Les erreurs sont conservées jusqu'à 500 caractères et peuvent citer des valeurs : gardez donc le fichier hors des dossiers partagés, sauf si vous voulez les partager.
Chaque étape et chaque conclusion a ses doubts, calculés quand vous lisez le fichier : ce qui a échoué, a été tronqué ou a changé depuis. Une liste vide signifie que rien de connu ne s'y oppose, pas qu'elle est juste.
Le SQL susceptible de contenir un identifiant est omis. Ce contrôle repose sur des mots comme secret, token et access_key, si bien qu'une colonne portant l'un de ces noms masque aussi sa requête.
Garder une analyse déplaçable
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 fichier ducklocal-project.json est facultatif. Il liste les tableaux de bord d'un dossier et ce dont ils ont besoin ; les données sont référencées, jamais copiées. L'ouvrir dans la fenêtre ouvre ces tableaux de bord.
project check rapporte ok, portable, problems (chacun avec un hint) et limitations, et se termine avec le code 0 quoi qu'il trouve : lisez donc la sortie. Il ne contacte jamais le réseau et n'installe rien. Réussir ne prouve pas que les données sont identiques. project relink modifie vos tableaux de bord et conserve chaque ancien sous NAME.dash.bak.
Un exemple concret
Une clé divulguée, examinée par un agent et par une personne parcourt une semaine fictive de CloudTrail, de la première requête à un tableau de bord relu. Un test exécute la moitié de l'agent à chaque modification. Personne n'a encore parcouru dans la fenêtre la moitié de cet exemple qui la concerne, et son README indique de quelles étapes il s'agit.
