Aller au contenu

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.

bash
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 faireRésultat
Lire un fichier sous --allow-readAutorisé
Lire tout autre fichier, par chemin, glob ou ..Refusé
Écrire un fichier, même sous --allow-readRefusé
ATTACH une base de données, ou en créer uneRefusé
Atteindre http, https, s3 ou toute autre URLRefusé
INSTALL ou LOAD une extensionRefusé
Modifier un paramètre, y compris ces limitesRefusé
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é.

bash
ducklocal open --state --active                  # note `revision`
ducklocal open --if-revision REV --run --wait \
  --title "Revenue by channel" --sql "SELECT ..."
  • --wait attend jusqu'à 5 minutes et ajoute status, tab_id, result_status, error et revision à la sortie.
  • --if-revision REV n'ouvre rien si la fenêtre n'affiche plus cette révision, et se termine avec le code 1 et le kind stale. 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 :

ChampSignification
schema_version, revisionLa version du contrat, et un jeton pour ce que la fenêtre affiche
actionsCe qu'il est advenu des requêtes récentes : stale, queued, running, opened, succeeded ou failed
limitsLes bornes des aperçus. Une lecture ne renvoie jamais un résultat entier
connectionsLe 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.reachlocal, remote ou unknown, déduit du SQL seul, et s'il a utilisé votre clé S3
sql_withheldtrue quand le SQL d'un onglet peut contenir un identifiant, et le texte est remplacé
scope, sur chaque graphiqueLa 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 :

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 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 --restricted dessus.

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 :

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

Rien 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 ​

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 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.

Publié sous licence Apache-2.0.