Перейти к содержимому

Работа с агентами ​

Новое в 0.4.0

Всё на этой странице появилось в v0.4.0. Если ducklocal check --help не показывает --restricted, ваша копия старше; обновитесь, чтобы использовать его.

Агент уже может запрашивать файлы, собирать дашборд и читать ваши комментарии с помощью CLI. Эти дополнения охватывают то, что происходит вокруг такой работы: ограничение SQL, который написали не вы, понимание того, что окно сделало с запросом, возможность одобрить изменение и запись того, как был получен ответ.

Ограничивайте SQL, который написали не вы ​

--restricted предназначен для SQL, скопированного из данных, и для дашборда, который написал кто-то другой. Одного режима только для чтения здесь недостаточно: он защищает файл базы данных, тогда как COPY всё ещё может писать куда угодно, куда можете вы, а FROM 'https://...' всё ещё может отправлять запрос.

bash
ducklocal query --restricted --allow-read ./data --sql "SELECT * FROM 'data/sales.csv'"
ducklocal check report.dash --restricted --allow-read ./data
SQL пытаетсяРезультат
Прочитать файл в пределах --allow-readРазрешено
Прочитать любой другой файл — по пути, glob или через ..Запрещено
Записать файл, даже в пределах --allow-readЗапрещено
Выполнить ATTACH базы данных или создать еёЗапрещено
Обратиться к http, https, s3 или любому другому URLЗапрещено
Выполнить INSTALL или LOAD расширенияЗапрещено
Изменить настройку, включая эти ограниченияЗапрещено
Работать дольше --timeout (по умолчанию 60 секунд)Прервано, kind timeout
Использовать больше --memory-limit (по умолчанию 2GB)Ошибка, kind resource_limit

Без --allow-read не читается ни один файл, включая собственную папку дашборда. Запрещённая инструкция завершается с кодом 1 и kind policy_denied и никогда не переходит к выполнению без ограничений. EXPLAIN, PRAGMA и PIVOT верхнего уровня тоже отклоняются, потому что инструкция должна быть одним SELECT.

Это не песочница. Ограничения — собственные ограничения DuckDB, и DuckLocal не применяет изоляцию операционной системы ни на одной платформе. Они связывают SQL, а не того, кто выбирает флаги: агент с доступом к оболочке может убрать --restricted. Чтобы изолировать агента, которому вы не доверяете, запускайте самого агента в контейнере или виртуальной машине. schema, profile, project check и open --run не выполняются с ограничениями, как и окно, когда открывает дашборд.

Что ограничивает SQL, который выполняет агент, содержит полную модель угроз и то, что было проверено на каждой платформе.

Держите шаг с окном ​

Раньше ducklocal open сообщал только о доставке, и больше ничего. Теперь два флага сообщают, чем закончился запрос, и защищают от действий над окном, которое изменилось.

bash
ducklocal open --state --active                  # note `revision`
ducklocal open --if-revision REV --run --wait \
  --title "Revenue by channel" --sql "SELECT ..."
  • --wait ждёт до 5 минут и добавляет в вывод status, tab_id, result_status, error и revision.
  • --if-revision REV ничего не открывает, если окно больше не показывает эту ревизию, и завершается с кодом 1 и kind stale. Прочитайте состояние заново, прежде чем повторять попытку. Если человек печатает в другой вкладке, это тоже делает ревизию устаревшей — намеренно.

--state теперь также сообщает:

ПолеЗначение
schema_version, revisionВерсия контракта и токен того, что показывает окно
actionsЧто стало с недавними запросами: stale, queued, running, opened, succeeded или failed
limitsГраницы предварительного просмотра. Чтение никогда не возвращает результат целиком
connectionsEndpoint и регион S3, а также имя, тип, расположение и адрес каждой присоединённой базы данных. Никогда ключ
result.reachlocal, remote или unknown — определяется только по SQL — и указывает, использовался ли ваш ключ S3
sql_withheldtrue, когда SQL вкладки может содержать учётные данные; тогда текст заменяется
scope, у каждого графикаКакую часть своего запроса рисует график

reach видит только то, что названо в SQL, поэтому локальное представление над удалёнными данными читается как local. Чтение всего этого не делает сетевых запросов, поэтому location: "remote" говорит, где находится база данных, а не что она всё ещё отвечает.

Агент может увидеть, что S3 настроен, не видя ключа, но SQL, который он выполняет через open --run, всё равно может использовать этот ключ.

Контракт передачи перечисляет все поля и виды ошибок, а JSON-схема описывает состояние.

Предлагайте изменение дашборда ​

Когда вы хотите одобрить изменение, агент может предложить его вместо того, чтобы редактировать файл:

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

Спецификация остаётся как есть, а вкладка дашборда показывает, что изменение ожидает рассмотрения. Нажмите Проверить, чтобы выполнить предложенный SQL и увидеть diff и проверки, затем нажмите Применить или Отклонить.

  • Применить предложение можете только вы, в окне. Команды для этого нет.
  • При применении старая версия сохраняется как sales.dash.bak, а если спецификация изменилась после предложения, применение отклоняется.
  • Отклонение оставляет спецификацию нетронутой.
  • Нажатие Проверить выполняет предложенный SQL, поэтому предложение, которому вы не доверяете, может добраться до всего, до чего может добраться SQL дашборда. Сначала выполните над ним check --restricted.

Записывайте, как был получен анализ ​

Задайте DUCKLOCAL_SESSION, и query, check, propose и open будут записывать, что каждый из них сделал:

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

Без этой переменной ничего не записывается. Файл содержит текст SQL и спецификаций, размер и время изменения каждого источника, а также форму каждого результата — но никогда его строки. Ошибки хранятся до 500 символов и могут цитировать значения, поэтому держите файл вне общих папок, если не собираетесь ими делиться.

У каждого шага и каждого вывода есть doubts, вычисляемые при чтении файла: что не удалось, было обрезано или изменилось с тех пор. Пустой список означает, что против него ничего не известно, а не что он верен.

SQL, который может содержать учётные данные, исключается. Эта проверка ориентируется на слова вроде secret, token и access_key, поэтому столбец с одним из таких имён тоже скрывает свой запрос.

Сохраняйте анализ переносимым ​

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

Файл ducklocal-project.json необязателен. Он перечисляет дашборды папки и то, что им нужно; данные указываются по ссылке и никогда не копируются. Открытие его в окне открывает эти дашборды.

project check сообщает ok, portable, problems (у каждого есть hint) и limitations и завершается с кодом 0 независимо от того, что найдёт, поэтому читайте вывод. Он никогда не обращается к сети и ничего не устанавливает. Успешная проверка не доказывает, что данные те же. project relink изменяет ваши дашборды и сохраняет каждый старый как NAME.dash.bak.

Разобранный пример ​

Утёкший ключ, расследованный агентом и человеком проходит по вымышленной неделе CloudTrail от первого запроса до проверенного дашборда. Тест выполняет половину агента при каждом изменении. Пока никто не прошёл вручную половину этого примера, относящуюся к окну, и его README указывает, какие это шаги.

Опубликовано под лицензией Apache-2.0.