Работа с агентами
Новое в 0.4.0
Всё на этой странице появилось в v0.4.0. Если ducklocal check --help не показывает --restricted, ваша копия старше; обновитесь, чтобы использовать его.
Агент уже может запрашивать файлы, собирать дашборд и читать ваши комментарии с помощью CLI. Эти дополнения охватывают то, что происходит вокруг такой работы: ограничение SQL, который написали не вы, понимание того, что окно сделало с запросом, возможность одобрить изменение и запись того, как был получен ответ.
Ограничивайте SQL, который написали не вы
--restricted предназначен для SQL, скопированного из данных, и для дашборда, который написал кто-то другой. Одного режима только для чтения здесь недостаточно: он защищает файл базы данных, тогда как COPY всё ещё может писать куда угодно, куда можете вы, а FROM 'https://...' всё ещё может отправлять запрос.
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 сообщал только о доставке, и больше ничего. Теперь два флага сообщают, чем закончился запрос, и защищают от действий над окном, которое изменилось.
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 и kindstale. Прочитайте состояние заново, прежде чем повторять попытку. Если человек печатает в другой вкладке, это тоже делает ревизию устаревшей — намеренно.
--state теперь также сообщает:
| Поле | Значение |
|---|---|
schema_version, revision | Версия контракта и токен того, что показывает окно |
actions | Что стало с недавними запросами: stale, queued, running, opened, succeeded или failed |
limits | Границы предварительного просмотра. Чтение никогда не возвращает результат целиком |
connections | Endpoint и регион S3, а также имя, тип, расположение и адрес каждой присоединённой базы данных. Никогда ключ |
result.reach | local, remote или unknown — определяется только по SQL — и указывает, использовался ли ваш ключ S3 |
sql_withheld | true, когда SQL вкладки может содержать учётные данные; тогда текст заменяется |
scope, у каждого графика | Какую часть своего запроса рисует график |
reach видит только то, что названо в SQL, поэтому локальное представление над удалёнными данными читается как local. Чтение всего этого не делает сетевых запросов, поэтому location: "remote" говорит, где находится база данных, а не что она всё ещё отвечает.
Агент может увидеть, что S3 настроен, не видя ключа, но SQL, который он выполняет через open --run, всё равно может использовать этот ключ.
Контракт передачи перечисляет все поля и виды ошибок, а JSON-схема описывает состояние.
Предлагайте изменение дашборда
Когда вы хотите одобрить изменение, агент может предложить его вместо того, чтобы редактировать файл:
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 будут записывать, что каждый из них сделал:
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, поэтому столбец с одним из таких имён тоже скрывает свой запрос.
Сохраняйте анализ переносимым
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 указывает, какие это шаги.
