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

> Что DuckLocal 0.4.0 добавил для ИИ-агентов: ограниченный SQL, проверенную передачу в окно, предложения по дашбордам, записи анализа и переносимые проекты.

Source: https://ducklocal.app/docs/ru/agent-workflows

::: info Новое в 0.4.0
Всё на этой странице появилось в [v0.4.0](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.0). Если `ducklocal check --help` не показывает `--restricted`, ваша копия старше; [обновитесь](getting-started.md), чтобы использовать его.
:::

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

## Ограничивайте SQL, который написали не вы {#restricted}

`--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, который выполняет агент](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-security.md), содержит полную модель угроз и то, что было проверено на каждой платформе.

## Держите шаг с окном {#handoff}

Раньше `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` | Границы предварительного просмотра. Чтение никогда не возвращает результат целиком |
| `connections` | Endpoint и регион S3, а также имя, тип, расположение и адрес каждой присоединённой базы данных. **Никогда ключ** |
| `result.reach` | `local`, `remote` или `unknown` — определяется только по SQL — и указывает, использовался ли ваш ключ S3 |
| `sql_withheld` | `true`, когда SQL вкладки может содержать учётные данные; тогда текст заменяется |
| `scope`, у каждого графика | Какую часть своего запроса рисует график |

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

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

[Контракт передачи](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-handoff.md) перечисляет все поля и виды ошибок, а [JSON-схема](https://github.com/JetSquirrel/DuckLocal/blob/main/docs/agent-state-v1.schema.json) описывает состояние.

## Предлагайте изменение дашборда {#propose}

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

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

## Записывайте, как был получен анализ {#session}

Задайте `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`, поэтому столбец с одним из таких имён тоже скрывает свой запрос.

## Сохраняйте анализ переносимым {#project}

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

## Разобранный пример {#worked-example}

[Утёкший ключ, расследованный агентом и человеком](https://github.com/JetSquirrel/DuckLocal/tree/main/examples/cloudtrail_investigation) проходит по вымышленной неделе CloudTrail от первого запроса до проверенного дашборда. Тест выполняет половину агента при каждом изменении. Пока никто не прошёл вручную половину этого примера, относящуюся к окну, и его README указывает, какие это шаги.
