Ir para o conteúdo

Fluxos de trabalho de agentes ​

Novo na 0.4.0

Tudo nesta página chegou na v0.4.0. Se ducklocal check --help não lista --restricted, sua cópia é mais antiga; atualize para usá-lo.

Um agente já consegue consultar arquivos, montar um painel e ler seus comentários com a CLI. Estas novidades cobrem o que gira em torno desse trabalho: limitar SQL que ele não escreveu, saber o que a janela fez com uma requisição, deixar você aprovar uma mudança e registrar como uma resposta foi alcançada.

Limite SQL que você não escreveu ​

--restricted serve para SQL copiado dos dados, e para um painel que outra pessoa escreveu. O modo somente leitura sozinho não cobre isso: ele protege o arquivo do banco de dados, enquanto COPY ainda pode escrever em qualquer lugar onde você possa, e FROM 'https://...' ainda pode enviar uma requisição.

bash
ducklocal query --restricted --allow-read ./data --sql "SELECT * FROM 'data/sales.csv'"
ducklocal check report.dash --restricted --allow-read ./data
O SQL tentaResultado
Ler um arquivo sob --allow-readPermitido
Ler qualquer outro arquivo, por caminho, glob ou ..Negado
Escrever um arquivo, mesmo sob --allow-readNegado
Fazer ATTACH de um banco de dados, ou criar umNegado
Alcançar http, https, s3 ou qualquer outra URLNegado
INSTALL ou LOAD de uma extensãoNegado
Mudar uma configuração, incluindo estes limitesNegado
Rodar por mais de --timeout (60 segundos por padrão)Interrompido, kind timeout
Usar mais de --memory-limit (2GB por padrão)Falha, kind resource_limit

Sem --allow-read, nenhum arquivo é legível, e isso inclui a própria pasta do painel. Uma instrução negada sai com código 1 e kind policy_denied e nunca cai para a execução sem restrições. EXPLAIN, PRAGMA e um PIVOT de nível superior também são recusados, porque a instrução precisa ser um único SELECT.

Isto não é uma sandbox. Os limites são os do próprio DuckDB, e o DuckLocal não aplica isolamento de sistema operacional em nenhuma plataforma. Eles prendem o SQL, não quem escolhe as flags: um agente com shell pode remover --restricted. Para conter um agente em quem você não confia, execute o próprio agente em um contêiner ou VM. schema, profile, project check e open --run não rodam restritos, e a janela também não, quando abre um painel.

O que limita o SQL executado por um agente traz o modelo de ameaças completo e o que foi testado em cada plataforma.

Fique em sincronia com a janela ​

O ducklocal open antes informava a entrega e nada mais. Duas flags agora informam como uma requisição terminou e protegem contra agir sobre uma janela que mudou.

bash
ducklocal open --state --active                  # note `revision`
ducklocal open --if-revision REV --run --wait \
  --title "Revenue by channel" --sql "SELECT ..."
  • --wait espera até 5 minutos e acrescenta status, tab_id, result_status, error e revision à saída.
  • --if-revision REV não abre nada se a janela já não mostra aquela revisão, e sai com código 1 e kind stale. Releia o estado antes de tentar de novo. Uma pessoa digitando em outra aba também o deixa obsoleto, de propósito.

--state agora também informa:

CampoSignificado
schema_version, revisionA versão do contrato, e um token para o que a janela mostra
actionsO que aconteceu com as requisições recentes: stale, queued, running, opened, succeeded ou failed
limitsOs limites das prévias. Uma leitura nunca devolve um resultado inteiro
connectionsO endpoint e a região do S3, e o nome, tipo, localização e endereço de cada banco de dados anexado. Nunca uma chave
result.reachlocal, remote ou unknown, lido só do SQL, e se ele usou sua chave do S3
sql_withheldtrue quando o SQL de uma aba pode conter uma credencial, e o texto é substituído
scope, em cada gráficoQuanto da consulta o gráfico desenha

reach só consegue ver o que o SQL nomeia, então uma visão local sobre dados remotos é lida como local. Ler qualquer um destes dados não faz requisição de rede, então location: "remote" diz onde um banco de dados está, não que ele ainda responda.

Um agente consegue ver que o S3 está configurado sem ver a chave, mas o SQL que ele executa com open --run ainda pode usar essa chave.

O contrato de entrega lista todos os campos e kinds de erro, e o JSON schema descreve o estado.

Proponha uma mudança em um painel ​

Quando você quer aprovar uma mudança, um agente pode propô-la em vez de editar o arquivo:

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

A especificação continua como está, e a aba do painel mostra que há uma mudança esperando. Clique em Revisar para executar o SQL proposto e ver o diff e as verificações, e depois clique em Aplicar ou Rejeitar.

  • Só você pode aplicar uma proposta, na janela. Não há comando para isso.
  • Aplicar mantém a versão antiga como sales.dash.bak, e é recusado se a especificação mudou desde a proposta.
  • Rejeitar deixa a especificação intacta.
  • Clicar em Revisar executa o SQL proposto, então uma proposta em que você não confia pode alcançar tudo o que o SQL do painel alcança. Execute check --restricted nela primeiro.

Registre como uma análise chegou até aqui ​

Defina DUCKLOCAL_SESSION, e query, check, propose e open registram cada um o que fizeram:

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

Nada é registrado sem essa variável. O arquivo guarda texto de SQL e de especificações, o tamanho e o horário de modificação de cada fonte, e a forma de cada resultado, nunca suas linhas. Os erros são mantidos até 500 caracteres e podem citar valores, então mantenha o arquivo fora de pastas compartilhadas, a menos que você queira compartilhá-las.

Cada passo e cada conclusão tem doubts, calculado quando você lê o arquivo: o que falhou, foi cortado ou mudou desde então. Uma lista vazia significa que nada se sabe contra ele, não que esteja certo.

SQL que pode conter uma credencial fica de fora. Essa verificação se guia por palavras como secret, token e access_key, então uma coluna com um desses nomes também esconde sua consulta.

Mantenha uma análise transportável ​

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

Um ducklocal-project.json é opcional. Ele lista os painéis de uma pasta e do que eles precisam; os dados são referenciados, nunca copiados. Abri-lo na janela abre aqueles painéis.

project check informa ok, portable, problems (cada um com um hint) e limitations, e sai com 0 seja o que encontrar, então leia a saída. Ele nunca acessa a rede nem instala nada. Passar não prova que os dados são os mesmos. project relink muda seus painéis e mantém cada antigo como NAME.dash.bak.

Um exemplo completo ​

Uma chave vazada, investigada por um agente e uma pessoa percorre uma semana inventada de CloudTrail da primeira consulta até um painel revisado. Um teste executa a metade do agente a cada mudança. Ninguém ainda percorreu clicando a metade da janela deste exemplo, e o README dele diz quais passos são esses.

Publicado sob a licença Apache-2.0.