# CLI для ИИ и официальный навык

> Используйте SQL CLI DuckLocal с ИИ-агентами: изучайте схемы локальных файлов, выполняйте одну инструкцию и получайте ограниченный JSON без GUI и сервера.

Source: https://ducklocal.app/docs/ru/cli

Обзор, ориентированный на задачи, см. в разделе [SQL для ИИ-агентов на локальных данных](https://ducklocal.app/ru/use-cases/ai-agent-sql/). Эта страница — полный справочник по командам и выводу.

## Запуск без окна

`ducklocal --help` перечисляет десять подкоманд:

| Команда | Что делает |
| --- | --- |
| `ducklocal query` | Выполняет одну инструкцию SQL и печатает результат как JSON |
| `ducklocal schema` | Перечисляет, что можно запрашивать, со столбцами; `--stats` — статистику столбцов одного отношения |
| `ducklocal open` | Показывает SQL, дашборд или данные в работающем окне; `--state` считывает обратно то, что оно показывает |
| `ducklocal check` | Проверяет дашборд `.dash` |
| `ducklocal metrics` | Перечисляет метрики семантической модели; `compile` или `query` компилируют и запрашивают их |
| `ducklocal comments` | Читает и отвечает на комментарии к обзору, оставленные людьми в дашборде |
| `ducklocal propose` | Предлагает изменение дашборда, чтобы человек его проверил и применил |
| `ducklocal project` | Проверяет переносимую папку анализа и её потребности; `relink` исправляет перемещённые пути |
| `ducklocal session` | Считывает, как анализ пришёл к своему результату |
| `ducklocal presence` | Показывает, кто работает над открытым дашбордом и куда попадёт правка |

`ducklocal lsp` — языковой сервер, который редакторы запускают для файлов `.dash`, — и `ducklocal profile`, устаревший псевдоним для `schema --stats`, по-прежнему работают, но не показываются в `--help`.

`propose`, `project` и `session`, а также параметры `--restricted`, `--wait` и `--if-revision` появились в 0.4.0 и описаны в разделе [Работа с агентами](agent-workflows.md). `metrics` и `--format html` новее 0.4.1: они уже в ветке `main` и войдут в следующий выпуск. `metrics` описана в разделе [Семантические метрики](metrics.md).

`ducklocal query` выполняет SQL, не инициализируя GUI, историю, зарегистрированные файлы, языковые настройки и глобальное соединение GUI. Каждый вызов создаёт отдельное соединение. Вызов DuckLocal без команд — или только с путями к файлам, каталогами и шаблонами glob — открывает обычный GUI. Чтобы открыть в GUI путь, имя которого совпадает с командой (`query`, `schema`, `open`, `check`, `metrics`, `comments`, `propose`, `project`, `session`, `presence`, `profile` или `lsp`), поставьте перед ним `./`, например `./query`.

## Получение команды {#get-the-command}

DuckLocal поддерживает macOS 12+ на Apple silicon, Windows (x86_64) и Linux (x86_64). CLI работает прямо из исполняемого файла приложения, поэтому отдельный бинарный файл DuckDB CLI устанавливать не нужно.

Быстрее всего попасть в `PATH` можно из приложения (0.1.1 и новее): откройте **Command line & AI…** — кнопку с роботом в строке заголовка или меню DuckLocal — и нажмите **Install command**. Тот же диалог устанавливает навык для ИИ-агентов; см. [Установка официального навыка](#install-the-official-skill). Если пропустить установку, вызывайте исполняемый файл там, где он лежит:

```bash
# macOS
/Applications/DuckLocal.app/Contents/MacOS/ducklocal --help
# Linux: wherever you extracted the tarball
./ducklocal-linux-x86_64/ducklocal --help
# Windows (PowerShell): wherever you extracted the zip
.\ducklocal-windows-x86_64\ducklocal.exe --help
```

Из рабочей копии исходного кода `cargo build --locked` собирает `./target/debug/ducklocal`. Примеры ниже предполагают, что `ducklocal` есть в `PATH`. В более старых выпусках может не быть `query`; сначала проверьте `--help`. Поддержка JSON и Parquet встроена, а не скачивается во время запроса.

## Параметры query {#query-options}

```bash
ducklocal --help
ducklocal --version
ducklocal query --help
ducklocal query --sql "SELECT 1 AS n"
ducklocal query --sql "SELECT 1 AS n" --format md
ducklocal query --sql-file analysis.sql --limit 100
ducklocal query --sql-file - < analysis.sql
ducklocal query --database warehouse.duckdb --sql "SHOW TABLES"
```

- Нужно ровно одно из `--sql SQL` и `--sql-file FILE`. Файлы должны быть в UTF-8; `-` читает stdin. SQL должен содержать ровно одну инструкцию. Парсер DuckDB проверяет это до открытия целевой базы данных и до любого выполнения; комментарии, точки с запятой в кавычках и завершающие точки с запятой работают. Скрипты отклоняются, а не выполняются частично.
- `--database PATH` открывает **существующий файл, по умолчанию только для чтения**. Не указывайте его, чтобы получить новую базу данных в памяти. `--read-write` требует `--database` и явно разрешает запись и создание базы данных (но не родительских каталогов). Ошибки базы данных никогда не приводят к переходу в память. Когда DuckDB отказывается открыть файл, сообщение об ошибке начинается с причины, которую DuckLocal читает из заголовка файла — файл записан более новым DuckDB, файл эпохи v0.9, файл SQLite или вообще не база данных, — и с того, что выполнить вместо этого (для более нового файла — копию `ATTACH … (STORAGE_VERSION)` / `COPY FROM DATABASE`, которую нужно сделать в том выпуске; для SQLite — `ATTACH`, который его читает), — и только потом идёт собственное сообщение DuckDB.
- `--limit N` — положительное целое, по умолчанию 1000, ограничивает число возвращаемых строк. Также действует бюджет в 2 000 000 ячеек. После достижения предела CLI продолжает считать ещё до 100 000 строк, не кодируя их значения, и сообщает `total_rows` и `total_rows_exact`. Это ограничивает вывод, а не вычисления или память: сортировка и агрегаты всё равно могут обрабатывать весь вход. Ошибка выполнения, возникшая после предела вывода, всё равно приводит к сбою команды.
- `--format json` (по умолчанию) — это контракт, описанный ниже. `--format md` отображает тот же результат как таблицу Markdown для документа или агента, который его читает. `--format html` выводит его как одну самодостаточную веб-страницу; см. [Вывод HTML](#html-output). Больше ничего не меняется: тот же SQL, те же пределы, те же ошибки.
- Повторяющиеся или неизвестные флаги, отсутствующие значения, пустой SQL и недопустимые пределы — ошибки. Параметры используют отдельные значения, а не `--flag=value`. Относительные пути разрешаются относительно рабочего каталога процесса, а не каталога SQL-файла. Заключайте пути оболочки в кавычки; внутри SQL удваивайте апострофы (`'O''Brien.csv'`). Идентификаторы SQL заключаются в двойные кавычки.

**Режим только для чтения — не песочница файловой системы или сети.** SQL вроде `COPY` может писать файлы, даже когда база данных доступна только для чтения. Авторизуйте пути вывода, перезапись, изменения базы данных, установку расширений и внешний доступ до выполнения. DuckLocal не устанавливает расширения автоматически и не повторяет операции. Явные `INSTALL`/`LOAD` в SQL остаются возможными при наличии разрешения; установленные расширения могут автозагружаться. Неудачная команда могла уже выполнить побочные эффекты (например, до сбоя вывода); проверьте место назначения, прежде чем повторять попытку.

### Вывод Markdown

`--format md` — это отображение, а не второй контракт: значения те же, что в JSON, записанные так, как их показывает таблица результатов.

| Значение | Отображается как |
| --- | --- |
| `NULL` | `NULL` |
| целое, decimal, float | ровно те цифры, которые несёт значение — `DECIMAL(38,10)` сохраняет свой масштаб, `NaN`/`inf`/`-inf` пишутся словами |
| `DATE` | `YYYY-MM-DD` |
| `TIMESTAMP` | `YYYY-MM-DD HH:MM:SS[.fffffffff]`, причём дробная часть только если она есть у значения, и с таким числом цифр, сколько у неё есть. Часовой пояс не добавляется; `--format json` сохраняет исходный счётчик |
| `TIME` | `HH:MM:SS[.ffffff]` |
| `INTERVAL` | как его записывает DuckDB: `1 month 2 days 00:00:00.000003` |
| `BLOB`, `GEOMETRY` | `0x00ff`, сокращается через `…`, когда длинно |
| `LIST`, `STRUCT`, `MAP` | `[1, 2]`, `{x: 1}`, сокращается через `…` после 120 символов |

`|` в ячейке экранируется, а перевод строки становится `<br>`, поэтому значение не может разорвать таблицу, в которой находится. После результата без строк идёт `_0 rows._`, а после результата, урезанного `--limit` или бюджетом ячеек, — `_Truncated at 2 of 5000 rows, so this is not the whole answer._` (`of at least …` после подсчёта 100 000 строк) — предварительный просмотр не должен читаться как полный ответ. Ошибки не меняются: JSON в stderr, пустой stdout.

### Вывод HTML {#html-output}

```bash
ducklocal query --sql "SELECT * FROM 'sales.csv'" --format html > sales.html
```

`--format html` записывает те же значения, что и `--format md`, в виде одной веб-страницы:

- Число строк и столбцов, затраченное время и SQL, давший результат, в свёрнутом виде.
- Имена столбцов с их типами. Числа выровнены по правому краю, `NULL` помечены.
- Щёлкните заголовок, чтобы отсортировать; `NULL` остаются в конце. Введите текст в поле фильтра, чтобы оставить только подходящие строки.
- Если результат обрезан `--limit` или бюджетом ячеек, страница сообщает об этом, как и Markdown.

Стили и скрипт встроены, и страница ничего не загружает, поэтому она открывается с диска и публикуется как есть, например на GitHub Pages. Каждая ячейка экранируется для HTML.

## Карта того, что можно запрашивать {#map-what-can-be-queried}

`ducklocal schema` отвечает на вопрос «что здесь есть и какие у этого столбцы?» одним вызовом, тогда как `DESCRIBE` отвечает на него по одному отношению за раз. Это первое, что должен запустить агент.

```bash
ducklocal schema ./data/                          # files, folders, globs
ducklocal schema --database warehouse.duckdb      # tables and views
ducklocal schema warehouse.duckdb --table orders  # one relation, whole
ducklocal schema ./logs/ --full                   # everything, however large
```

PATH раскрываются так же, как при перетаскивании в окно: файлы данных папки рекурсивно (скрытые пропускаются, не более 256), совпадения glob и файл базы данных так, как если бы он был указан через `--database`. Возвращается один объект JSON:

```json
{"detail":"full","relations":[{"name":"data/orders.csv","kind":"file","from":"'data/orders.csv'","rows":null,"column_count":2,"path":"data/orders.csv","columns":[{"name":"channel","type":"VARCHAR"},{"name":"amount","type":"BIGINT"}]}],"without_columns":0}
```

| Поле | Значение |
| --- | --- |
| `name` | Путь файла в том виде, в каком он задан (относительно рабочего каталога, если он внутри него), или имя таблицы в том виде, в каком до неё доходит SQL на этом соединении: без схемы в схеме по умолчанию, `schema.table` в остальных случаях |
| `kind` | `file`, `glob`, `table`, `view` или `workbook` |
| `from` | SQL, который её читает, готовый идти после `FROM`: путь в кавычках или идентификатор в кавычках, где это нужно |
| `rows` | Оценка каталога для таблицы, точная для Parquet (из его footer), `null` там, где для точности нужно сканирование — CSV, JSON, представления |
| `column_count`, `columns` | Столбцы в том виде, в каком их описывает DuckDB |
| `files` | Для `glob`: сколько файлов он сопоставляет |

Glob, все совпадения которого одного формата, — одно отношение, читаемое так же, как его читает `source` в `.dash` (`ducklocal schema 'logs/*.csv'`); `--stats` профилирует его как одно. Glob по смешанным форматам и папка перечисляют свои файлы по одному.

Небольшой каталог возвращается целиком (`"detail": "full"`). После 12 отношений или 400 столбцов вместо него возвращается **сводка** (`"detail": "summary"`). 5 отношений с наибольшим числом строк сохраняют свои столбцы; остальные перечисляют имя, тип, строки и число столбцов, а `without_columns` их считает. Чтобы получить больше, `hint` называет два способа: `--table NAME` для одного отношения (сопоставление по его имени, простому имени таблицы или имени файла) и `--full` для всех. Книга перечисляется со своими `sheets` и без столбцов, поскольку у неё нет табличной функции; `--stats` читает её первый лист. PATH, которого не существует, или `--table`, который ничего не называет, — код выхода 2.

Текст в gzip, такой как `.json.gz` и `.csv.gz`, здесь считается файлом данных — как и для блоков `source` и для окна. Файл, записи которого лежат в одном списке — скажем, `{"Records": [...]}` в CloudTrail, — возвращается с `hint`: SQL, который читает эти записи как строки, поскольку иначе одна строка и один столбец описывают только обёртку.

## Изучение и преобразование файлов

После того как вы убедились, что файл действительно существует:

```bash
ducklocal query --sql "DESCRIBE SELECT * FROM 'sales.csv'"
ducklocal query --sql "SELECT * FROM 'sales.csv'" --limit 20
ducklocal query --sql "SELECT sum(amount) AS total FROM 'sales.csv'"
# Only after authorizing this output path:
ducklocal query --sql "COPY (SELECT * FROM 'sales.csv') TO 'sales.parquet' (FORMAT PARQUET)"
ducklocal query --sql "SELECT count(*), sum(amount) FROM 'sales.parquet'"
ducklocal query --sql "DESCRIBE SELECT * FROM 'events.json'"
```

Не гадайте, что `amount` существует: сначала выполните `ducklocal schema` или `DESCRIBE`. Вычисляйте полные агрегаты в SQL, а не суммируйте усечённый предварительный просмотр. Вызовы CLI не разделяют зарегистрированные представления GUI или таблицы в памяти друг друга. Сохраняйте явно, когда это нужно:

```bash
# These are separate statements and separate invocations, with explicit write permission.
ducklocal query --database warehouse.duckdb --read-write --sql "CREATE TABLE sales AS SELECT * FROM 'sales.csv'"
ducklocal query --database warehouse.duckdb --sql "SELECT count(*) FROM sales"
```

Конфликт блокировки базы данных — ошибка. Закройте другого писателя (включая GUI) или используйте разрешённую копию; никогда не удаляйте файлы блокировки и не создавайте молча другую базу данных.

## JSONL и вложенный JSON {#jsonl-and-nested-json}

`read_ndjson_objects` — читатель для JSON с разделителями-переводами строк (один объект на строку, `.jsonl`/`.ndjson`); `read_json`/`read_json_auto` читают документы JSON (массив или один объект). Для файла JSONL указывайте читателя явно, а не полагайтесь на автоопределение. `json_extract_string(col, '$.a.b[0].c')` проходит по вложенному пути — ключам объектов и индексам массивов — и возвращает VARCHAR:

```bash
ducklocal query --sql "SELECT json_extract_string(event, '$.payload.items[0].sku') AS sku, count(*) AS n FROM read_ndjson_objects('events.jsonl') GROUP BY 1 ORDER BY n DESC"
```

Используйте `json_extract` вместо этого, когда лист не является строкой и вы хотите получить его как JSON.

## Статистика столбцов

`ducklocal schema --stats` отвечает на вопросы, которые определяют график, масштаб и формат чисел, до того, как на них что-либо построят. `DESCRIBE` говорит, что столбец имеет тип `DOUBLE`; его статистика говорит, что он использует два знака после запятой, что его наибольшее значение в тысячу раз больше медианы и что в его датах пропущено одиннадцать дней в середине.

```bash
ducklocal schema sales.csv --stats
ducklocal schema ./exports/ --table orders.parquet --stats
ducklocal schema --database warehouse.duckdb --table "my orders" --stats
```

`--stats` профилирует одно отношение: то единственное, которое названо в аргументах, или то, которое выбрал `--table`, — два или больше без `--table` дают код выхода 2 с подсказкой об этом. Его нельзя сочетать с `--full`. `ducklocal profile TARGET [--database PATH]` из более ранних выпусков выдаёт тот же отчёт и по-прежнему работает.

Отношение — это файл данных (`csv`, `tsv`, `txt`, `parquet`, `json`, `ndjson`, `jsonl`) либо книга (`xlsx`, `xls`, `xlsb`, `ods`; её первый лист импортируется как временная таблица TEMP и профилируется), либо, с `--database`, имя таблицы или представления. Имя с точкой читается как `schema.table`, и каждая часть заключается в кавычки, поэтому имя с пробелом или заглавной буквой работает как написано. Отношение, которое ничего не называет, — ошибка аргументов (код выхода 2), а не SQL.

Возвращается один объект JSON: `target`, `relation` (SQL, по которому выполнялась статистика), `row_count`, `elapsed_ms` и `columns` в собственном порядке отношения. По каждому столбцу:

| Поле | Значение |
| --- | --- |
| `name`, `type` | как их сообщает `DESCRIBE` |
| `nulls` | строки, где столбец равен `NULL` |
| `distinct` | точное значение, а не оценка |
| `unique` | присутствует и равно `true`, когда `distinct` равно `row_count` |
| `min`, `max` | как текст, поэтому `DECIMAL` сохраняет свои цифры |
| `decimals` | цифры после точки, которые столбец **фактически использует**, а не его объявленный масштаб |
| `median` | значение, которое есть в столбце, а не интерполяция между двумя из них |
| `max_over_median` | во сколько раз наибольшее значение больше медианы — число, которое решает, использовать линейную ось или логарифмическую |
| `covered_days`, `span_days`, `missing_days` | дни, которые называет столбец, дни между его концами и разница: `0` — непрерывный ряд, любое другое значение — дыры, по которым линия провела бы черту |

`decimals`, `median` и `max_over_median` появляются у числовых столбцов; поля дней — у дат и меток времени. Столбцы `LIST`, `STRUCT`, `MAP` и `UNION` сообщают только `nulls` — `min` и `max` для них не определены.

Текстовый столбец, в котором лежат числа и одно короткое слово, например `NA` из R, также сообщает `null_marker` и `null_marker_rows`. Тогда отчёт добавляет `hint` с вызовом `read_csv`, который читает столбец как числа.

Статистика точна и читает всё отношение, поэтому стоит полного сканирования. `--limit` не применяется: профиль выборки — не профиль.

## Показ работы в работающем окне {#show-work-in-the-running-window}

`ducklocal open` передаёт что-либо окну DuckLocal, которое уже работает, — запуская его, если ни одного нет, — и выводит его на передний план. Так агент показывает свою работу человеку, который может продолжить с этого места:

```bash
ducklocal open --title "Revenue by channel" --run --sql "SELECT channel, sum(amount) AS total FROM 'orders.csv' GROUP BY 1"
ducklocal open sales.dash                    # a dashboard tab
ducklocal open ./data/ --sql-file analysis.sql
echo "SELECT 42" | ducklocal open --sql-file - --no-launch
```

- PATH открываются так же, как при перетаскивании в окно: файл `.dash` — как вкладка, файл базы данных DuckDB — как база данных окна, файлы данных, папки и glob — как присоединённые представления. Относительные PATH разрешаются относительно каталога команды. Запрос, пришедший пока окно ещё запускается, ждёт, пока завершится его стартовое открытие.
- `--sql` или `--sql-file` (`-` читает stdin) открывает новую вкладку запроса с заголовком `--title`. `--run` выполняет его, как только присоединятся PATH.
- `--no-launch` завершается с kind `not_running` вместо запуска окна — для машины, где незапрошенное появление окна было бы нежелательным.

Успех печатает `{"delivered": true, "launched": BOOL}`: доставку, а не результат. То, что открывается, работает в собственной сессии окна — с его соединением, присоединёнными представлениями, историей, — и любая ошибка показывается там, а не в stdout. Код 2 для аргументов; 1 с kind `not_running` (окно недоступно), `refused` (окно отклонило запрос) или `launch`.

Окно слушает порт loopback. Оно записывает порт и случайный токен в файл, который может прочитать только ваша учётная запись (см. [Настройки и данные приложения](settings-and-data.md#where-things-are-stored)); другой пользователь машины или веб-страница, нацеленная на localhost, до него не дотянутся.

### Чтение того, что показывает окно

`ducklocal open --state` идёт в обратную сторону: ничего не открывает, никогда не запускает окно и печатает то, что показывает работающее окно, — чтобы агент мог продолжить с места, где остановился человек, вместо того чтобы просить его вставить свой запрос.

```bash
ducklocal open --state
ducklocal open --state sales.dash
ducklocal open --state --active
```

```json
{"database":":memory:","attached":[{"path":"/Users/me/data/orders.csv","name":"orders","rows":224}],"active_tab":1,"tabs":[{"kind":"query","title":"Query 1","active":false,"sql":"SELECT …","result":{"status":"rows","columns":[…],"row_count":5,"truncated":false,"preview":[["Web","132771.24"],…],"sql":"SELECT …","elapsed_ms":4}},{"kind":"dashboard","title":"sales","active":true,"path":"/Users/me/data/sales.dash","unsaved":false,"dashboard":{"running":false,"error":null,"stale":null,"plots":[…],"filters":[{"name":"channel","plot":"revenue_by_channel","column":"channel","picked":true,"value":"Web"}]}}]}
```

- `database` — открытый файл базы данных или `":memory:"`; `attached` перечисляет файлы, которые окно зарегистрировало как представления, с именем представления `name`. Запрос CLI не может читать эти представления — используйте `path`.
- Вкладка **query** имеет `sql` — текст редактора, выполнялся он или нет, — и `result`: `status` равен `empty`, `running`, `rows`, `affected`, `failed`, `explain` или `profile`. Для строк: `columns`, `row_count`, `truncated`, `preview` (первые 20 строк в том виде, в каком их показывает таблица, в виде строк), `elapsed_ms` и `sql`, который их произвёл; для `affected` — `count` и `elapsed_ms`; для ошибки — `error`.
- После того как человек выбрал столбцы на вкладке «График», у результата есть также `chart`: `type`, `x`, `y`, `split` и `dash` — блоки `query` и `plot`, которые рисуют тот же график в дашборде.
- `explain` — то, что показывает **Explain**: `plan`, вывод `EXPLAIN` DuckDB в виде массива текстовых строк, и `elapsed_ms`.
- `profile` — то, что показывает **Profile** (см. [Редактор SQL](sql-editor.md)): `plan`, дерево операторов, измеренное `EXPLAIN ANALYZE`, в виде массива корней, каждый `{operator, seconds, rows, estimated, children}` — `seconds` это собственное время оператора без его дочерних, `rows` — что он произвёл, `estimated` — догадка оптимизатора для `rows` (`null` там, где план её не указывает), `children` — та же структура снова. `operator_seconds` — сумма собственного времени всех операторов, которую складывают доли, а не время по часам; `elapsed_ms` — весь прогон.
- Вкладка **dashboard** имеет `path`, `unsaved` и `dashboard`: путь `comments_file`, `plots` (имя, тип, заголовок, запрос, строки, `open_comments` и `failure`, когда график не может отрисоваться) и `filters` с тем, что каждый выбрал: `picked`, `value` (первое значение), `values` (все выбранные значения по порядку) и `multiple`. `value: null` при `picked: true` означает, что выбрано значение NULL.

Используйте `--state sales.dash`, чтобы оставить только вкладки, показывающие этот дашборд, или `--state --active` — только активную вкладку. Путь, который не открыт, даёт код выхода 1, kind `not_open`, с открытыми дашбордами в подсказке. `active_tab` — индекс активной вкладки в возвращённом `tabs` или `null`, если её среди них нет; `database` и `attached` по-прежнему включаются.

`--state` принимает либо один PATH `.dash`, либо `--active`, но не оба. `--no-launch` принимается и ничего не меняет. Другие параметры, включая `--sql` и `--run`, недопустимы (код 2). Код 1 с kind `not_running`, когда окно не запущено, и `timeout`, когда оно не отвечает в течение 5 секунд.

## Проверка спецификации дашборда {#check-a-dashboard-spec}

Сам формат — блоки, атрибуты, типы графиков, правила SQL и типичные сообщения — описан в разделе [Дашборды (.dash)](dashboards.md); в этом разделе речь о команде.

Файл `.dash` объявляет дашборд так, как Terraform объявляет инфраструктуру — запросы и графики как блоки, ссылки между ними, — а не программирует его. Его легко писать и сравнивать человеку или агенту.

```hcl
query "latency" {
  sql = <<SQL
    SELECT timestamp, service, avg(latency) AS latency
    FROM logs
    GROUP BY timestamp, service
  SQL
}

plot "latency" {
  type   = "line"
  query  = query.latency
  x      = timestamp
  y      = latency
  series = service
}
```

```bash
ducklocal check dashboard.dash
ducklocal check dashboard.dash --database warehouse.duckdb
ducklocal check dashboard.dash --summary
```

Блок `source` называет файлы данных относительно файла `.dash`, которые должны читать запросы, а блок `view` хранит SQL, общий для нескольких запросов. Блок `query` содержит один атрибут `sql` — одну инструкцию только для чтения, в виде heredoc или строки. Принимаются `SELECT`, `WITH`, `FROM`-первым, `VALUES`, `SHOW`, `DESCRIBE`, `SUMMARIZE` и `PIVOT`; всё, что могло бы писать, — DDL, DML, `COPY`, `ATTACH`, `INSTALL` — становится диагностикой, и GUI отказывается это выполнять, потому что запросы дашборда выполняются при каждом открытии файла. Блок `plot` содержит `type` (один из `line`, `bar`, `stacked_bar`, `area`, `scatter`, `pie`, `heatmap`, `histogram`, `map`, `timeline`, `table`, `card`, `text`), `query` (ссылку вида `query.latency` на блок запроса в том же файле), его столбцы и необязательные `title` и `width`. Блок `filter` делает столбчатую диаграмму или таблицу кликабельной — одно значение или несколько при `multiple = true` для столбчатой диаграммы, — и запрос читает выбор как `$name`. `#` и `//` комментируют до конца строки. В разделе [Дашборды (.dash)](dashboards.md) есть каждый атрибут.

График `text` — исключение: он содержит `title`, `text` или и то и другое и не принимает `query`. Карточки могут также использовать `note` и `tone`; см. [Карточки и текстовые панели](dashboards.md#cards-and-text-panels).

Сначала идут статические проверки: SQL каждого запроса проходит через настоящий парсер DuckDB на одноразовом соединении — так же, как `query` проверяет перед выполнением, — и каждый `$name` сверяется с блоками фильтров: SQL разбирается и выполняется с каждым `$name`, равным `TRUE`, — именно так дашборд работает, пока ничего не выбрано.

Затем выполняется каждый запрос — точно так, как его выполнило бы открытие дашборда: только для чтения, со своими источниками, через тот же путь кода и с тем же бюджетом строк, — и столбцы каждого графика сверяются со столбцами, которые запрос действительно возвращает: `y`, не являющийся числовым, — ошибка для любого типа графика, как и нечисловые координаты или `size` карты, и `column` фильтра, который запрос его графика не возвращает.

- **Без `--database`** запросы выполняются в памяти, чего достаточно дашборду на собственных файлах `source`. Запрос, читающий таблицу, которую не определяет ни один источник, может быть предназначен для базы данных, которую проверке не дали: он попадает в `unresolved` (запрос, строка, причина), а не в ошибки, и столбцы его графиков не проверяются.
- **С `--database PATH`** (существующий файл, только для чтения) они выполняются на этой базе данных. Передавайте её всякий раз, когда запросы читают таблицы базы данных: всё, что попало в `unresolved`, не проверялось.

Каждый запрос, читающий фильтр, также связывается с выбранным значением, но без выполнения этого варианта. Это ловит столбец фильтра, отсутствующий в потребляющем запросе, даже когда начальная версия с `$name = TRUE` работает. Фильтр также должен ссылаться на столбец, который возвращает его собственный график.

Выполнение, а не только планирование, важно: некоторые сбои — например, приведение типа, которое сборка не может выполнить, или значение, которое не преобразуется, — появляются только после чтения строк, и проверка, которая их пропустит, передаст дашборд, который не сможет отрисоваться. Запросы выполняются полностью, поэтому проверка на большой базе данных занимает столько же времени, сколько открытие дашборда.

Успех — это один объект JSON, перечисляющий источники файла (с каждым `resolved` путём), представления, запросы (с их результирующими столбцами и `rows` — сколько вернул каждый при пустом выборе, плюс `truncated: true`, когда его урезал бюджет строк дашборда), фильтры (с `queries`, которые читают каждый), графики, `unresolved` и `empty` — запросы, которые выполнились и не вернули строк. Пустой запрос проходит все остальные проверки, но обычно это регулярное выражение, фильтр или соединение, которое ничего не нашло, поэтому посмотрите на каждый. С `--summary` успех — это одна компактная строка JSON:

```json
{"file":"sales.dash","ok":true,"sources":1,"views":0,"queries":3,"filters":1,"plots":6,"unresolved":[],"empty":[]}
```

Пять полей блоков — это счётчики; `unresolved` перечисляет запросы, которые не удалось проверить, а `empty` — те, что не вернули строк.

Ошибочный блок пропускается, а валидные блоки продолжают проходить проверку. Ошибки спецификации и сбои запросов собираются в одном прогоне, по одному `file:line: message` на каждую. Если есть хоть одна диагностика спецификации, код выхода 2 с kind `spec`; если падает только выполнение SQL или связывание, код выхода 1 с kind `sql`. Сбои базы данных и ввода-вывода также дают код 1. `--summary` не скрывает диагностику.

Тот же файл открывается как вкладка дашборда в GUI — `ducklocal dashboard.dash`, `ducklocal open dashboard.dash` или перетаскиванием в окно — с графиками на сетке из 12 столбцов, а график, который не может отрисоваться, показывает причину прямо на месте. См. [Дашборды (.dash)](dashboards.md).

## Метрики из семантической модели {#metrics}

```bash
ducklocal metrics                       # ./model.ossie.yaml
ducklocal metrics compile --metric error_count,event_count --by events.ip
ducklocal metrics query --metric event_count --by events.event_time:day \
  --views reports/investigation.dash --restricted --allow-read data
```

`ducklocal metrics` читает модель Apache Ossie, `model.ossie.yaml`, и перечисляет её метрики и поля. `compile` печатает единственный `SELECT` DuckDB, отвечающий на запрос, и не читает данные; `query` выполняет его так же, как `ducklocal query`, и добавляет объект `semantic` с SQL и `sha256` модели. Запрос, на который модель не может ответить точно, отклоняется с кодом выхода 2 и `kind`, например `metric_fanout`. Формат модели, все параметры и все отказы описаны в разделе [Семантические метрики](metrics.md).

## Проверка комментариев к дашборду {#review-comments-on-a-dashboard}

Люди проверяют дашборд, комментируя его графики в окне — наведите курсор на график, нажмите облачко с репликой (см. [Проверка с комментариями](dashboards.md#review-with-comments)). `ducklocal comments` — сторона агента: он читает ветки и отвечает на них без окна.

```bash
ducklocal comments sales.dash [--all]
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" [--resolve]
ducklocal comments sales.dash --resolve c1
ducklocal comments sales.dash --reopen c1
ducklocal comments sales.dash --add revenue_by_channel --text "Is this net of refunds?"
```

- Без действия печатает открытые ветки: `{file, comments_file, open, threads}`. `--all` включает решённые.
- Каждая ветка имеет `id`, `plot` и то, что нужно агенту, чтобы найти её в спецификации: `plot_title`, `plot_query` и `plot_lines` — первую и последнюю строку блока `plot` (`null`, когда спецификация не разбирается). `plot_missing` равно `true`, когда графика с таким именем больше нет. Затем `resolved` и `comments`, каждый с `author` (`user` или `agent`), у комментария агента — его `name` (имя, которое показывает [`presence`](#agent-presence)), `text` и `at` (RFC 3339, местное время).
- `--reply ID --text TEXT` добавляет ответ агента. Ответ в решённую ветку открывает её заново, если только не указан также `--resolve`.
- `--resolve ID` и `--reopen ID` меняют состояние ветки; `--add PLOT --text TEXT` начинает ветку, подписанную агентом.
- Номер ветки работает как её ID: `--reply 1` означает `c1`. `--add` отказывается от графика, которого нет в спецификации (код 2), а подсказка перечисляет её графики.
- Действие печатает `{thread}` в изменённом виде.

Ветки хранятся рядом со спецификацией, в `FILE.comments.json`. Работающее окно замечает изменение в течение секунды и показывает его на графике. Неизвестный ID ветки даёт код 2 с подсказкой перечислить ветки; отсутствующий файл спецификации — код 1.

Проверка от начала до конца: прочитайте открытые ветки, измените спецификацию, выполните `ducklocal check`, затем ответьте в каждой ветке тем, что изменилось, и выполните `--resolve`. Используйте `--reply` без `--resolve`, чтобы что-то переспросить у человека.

## Показ активности агента {#agent-presence}

`check` и `comments` автоматически сообщают работающему окну, над каким дашбордом работает агент. `presence` может объявить правку до того, как она произойдёт:

```bash
ducklocal presence sales.dash --doing editing --plot revenue_by_channel,daily_revenue
ducklocal presence sales.dash --doing reading --agent "Analyst"
ducklocal presence sales.dash --doing idle
```

- `--doing` принимает `reading`, `editing` или `idle` (`done` — псевдоним для `idle`).
- `--plot` принимает имена графиков через запятую. При `editing` новые имена разрешены и появляются как заполнители. При `reading` или `idle` неизвестное имя даёт код 2.
- Показываемое имя берётся из `--agent`, затем `DUCKLOCAL_AGENT`, затем из обнаруженного окружения агента (Claude, Codex, Cursor или Gemini), с откатом к `Agent`.
- Вывод — `{delivered}`. Без работающего окна выдаётся `{"delivered":false}` без ошибки и без запуска окна.

Имя остаётся в углу дашборда, пока команды поддерживают сеанс активным. Нажмите на него, чтобы увидеть журнал активности. Тридцать секунд тишины или `--doing idle` завершают сеанс; изменённые и добавленные графики остаются помеченными до просмотра, а уведомления об удалённых графиках — до закрытия. См. [Как агент работает](dashboards.md#agent-presence).

## Редактирование спецификации дашборда с помощью LSP {#edit-a-dashboard-spec-with-lsp}

`ducklocal lsp` — сервер Language Server Protocol для файлов `.dash`, работающий через stdio, который запускают редакторы. Он даёт любому редактору с поддержкой LSP то же, что есть у собственного редактора спецификаций в GUI:

- **Диагностика**: та, которую сообщает `check`, публикуется при каждом открытии и изменении (полная синхронизация документа, все с уровнем Error — это ошибки, а не стиль).
- **Автодополнение**: типы блоков, имена атрибутов, типы графиков и имена после `query.` и `plot.`, каждое с текстовой правкой, которая заменяет набираемое слово.
- **Наведение**: документация по блокам, атрибутам и ссылкам.
- **Переход к определению**: от ссылки `query.name` или `plot.name` к имени её блока.

С `--database PATH` SQL каждого запроса дополнительно проверяется настоящим парсером DuckDB, как это делает `check --database`.

Направьте общую поддержку LSP вашего редактора на `ducklocal lsp` для файлов `*.dash` — команда не принимает аргументов документа; редактор общается с ней через stdio. В Neovim (0.10+):

```lua
vim.api.nvim_create_autocmd("FileType", {
  pattern = "dash",
  callback = function(event)
    vim.lsp.start({
      name = "ducklocal",
      cmd = { "ducklocal", "lsp" },
      root_dir = vim.fs.dirname(vim.api.nvim_buf_get_name(event.buf)),
    })
  end,
})
```

В VS Code любое расширение с поддержкой LSP делает то же с командой `ducklocal`, аргументами `["lsp"]` и селектором документов `dash`. Коды выхода: **0** после чистых `shutdown`/`exit`, **1** когда клиент уходит без них, **2** при плохой командной строке или неудачном рукопожатии протокола.

## Контракт JSON

Успешные запросы записывают в stdout ровно один объект JSON, за которым идёт перевод строки:

```json
{"columns":[{"name":"n","type":"Int32"}],"rows":[[1]],"row_count":1,"truncated":false,"total_rows":1,"total_rows_exact":true,"elapsed_ms":1}
```

`columns` и каждая строка сохраняют порядок столбцов и повторяющиеся имена столбцов. `type` — это **отладочное представление Arrow**, а не исходное имя типа SQL в DuckDB (например, HUGEINT и DECIMAL могут использовать один и тот же носитель Arrow). `row_count` считает возвращённые строки. `total_rows` считает произведённые строки, включая те, что посчитаны после предела вывода; `total_rows_exact: false` означает, что подсчёт остановился, пройдя до 100 000 дополнительных строк, поэтому этот итог — нижняя граница. Ни один из счётчиков не является счётчиком затронутых строк. `elapsed_ms` измеряет подготовку, выполнение и кодирование строк, но не загрузку файлов и установку соединения. Результаты с нулём строк сохраняют метаданные. DDL/DML показывают фактический результат DuckDB, включая столбцы `Count`: INSERT/COPY обычно возвращают `[[N]]`; CREATE TABLE обычно не возвращает строк. Они не классифицируются по первому ключевому слову SQL.

Кодирование ячеек:

| Значение SQL | Кодирование в JSON |
| --- | --- |
| NULL | `null` (никогда строка `"NULL"`) |
| Boolean, конечное float | JSON boolean/number |
| Целое в пределах ±9 007 199 254 740 991 | JSON number |
| Большее целое, включая HUGEINT/UHUGEINT | `{"encoding":"integer","value":"9007199254740992"}` |
| Decimal | `{"encoding":"decimal","value":"123.450"}` с точным десятичным текстом |
| Текст, enum | строка JSON |
| Blob, geometry | `{"encoding":"hex","value":"00ff"}`; байты в нижнем регистре, geometry использует WKB |
| Date | `{"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"}`; дни с 1970-01-01 |
| Timestamp | `{"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"}`; знаковый счётчик с начала эпохи Unix; единица может быть также Second/Millisecond/Microsecond |
| Time | `{"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}`; счётчик с полуночи |
| Interval | `{"encoding":"interval","months":1,"days":2,"nanos":"3000"}` |
| NaN, положительная/отрицательная бесконечность | `{"encoding":"float","value":"NaN"}` / `"inf"` / `"-inf"` |
| List, array | массив JSON, рекурсивно закодированный (включая вложенные null) |
| Struct | `{"encoding":"struct","fields":[["name",VALUE],...]}` |
| Map | `{"encoding":"map","entries":[[KEY,VALUE],...]}`; не объект JSON, поэтому ключи сохраняют свои типы |
| Union | `{"encoding":"union-value","value":VALUE}`; только активное значение, тег члена не сохраняется |

Временные `value` — точные счётчики, поэтому дробная точность не теряется; бесконечные сигнальные значения дат и меток времени остаются исходными счётчиками. Рядом `iso` — то же значение в тексте ISO 8601 для чтения, с таким числом цифр дроби, сколько вмещает единица. Метка времени из столбца с часовым поясом (метаданные Arrow) — это момент в UTC, и её `iso` заканчивается на `Z`. `--format md` также отображает даты и метки времени удобочитаемо. Поскольку закреплённая обёртка Arrow для DuckDB не умеет различать вложенные HUGEINT, UHUGEINT и DECIMAL(38,0), ненулевые вхождения дают явную ошибку вместо молчаливой смены знака или точности. Явно приводите такие поля к VARCHAR в SQL. Неизвестные неподдерживаемые типы тоже дают ошибку; не путайте ошибку с пустым результатом. Кодирование Union — представление активного значения, а не обратимое сохранение union.

Ошибки записывают один объект JSON в **stderr**, оставляя stdout пустым:

```json
{"error":{"kind":"argument","message":"Unknown query option: --limt","hint":"Did you mean --limit?"}}
```

`hint` присутствует, когда следующий шаг известен, в терминах самого CLI: флаг, которым должен был быть опечатанный, `--read-write` для записи, отклонённой на базе данных только для чтения, `ducklocal schema` для несуществующей таблицы, `TRY_CAST` для значения, которое не преобразуется, разбиение скрипта, в котором больше одной инструкции, или `AS` для ключевого слова, использованного как простой псевдоним столбца (`SELECT count(*) AS minutes` или заключите его в кавычки). Агент должен действовать по ней, прежде чем переписывать SQL. Она отсутствует, когда к собственному сообщению DuckDB нечего добавить, например при синтаксической ошибке.

Коды выхода: **0** — успех, **2** — недопустимые аргументы или число инструкций, **1** — сбой SQL, базы данных, ввода-вывода или вывода. Виды ошибок: `argument`, `sql`, `database`, `io`, `output`, `spec` для `check` и `not_running`, `not_open`, `refused`, `timeout` или `launch` для `open`. Проверяйте код выхода перед разбором stdout и смотрите на `truncated` перед тем, как сообщать о полноте. Справка и версия — исключения в виде обычного текста. Сбои транспорта, например закрытый канал stdout, не могут гарантировать пустой или полный поток вывода.

## Установка официального навыка {#install-the-official-skill}

Навык учит агента привычкам, которые делают его ответы честными: изучать схему, смотреть ограниченную выборку, вычислять агрегаты в SQL, проверять `truncated` и отвечать по возвращённым значениям. Он охватывает изучение схемы, статистику столбцов, преобразования, запросы к базам данных, дашборды `.dash` и комментарии к ним, а также передачу работы в окно и чтение её обратно; он не даёт просмотра S3, команд для пространственных данных, памяти сеанса или сервера MCP.

**Из приложения.** Откройте **Command line & AI…** (кнопка с роботом в строке заголовка или меню DuckLocal):

- **Install command** помещает `ducklocal` в ваш `PATH`, чтобы оболочка агента могла его запускать.
- **Add to Claude Code** записывает навык в `~/.claude/skills/ducklocal`, где Claude Code находит его в любом проекте. Записываются только два собственных файла навыка; всё остальное в этой папке сохраняется. Когда обновление DuckLocal приносит более новый навык, диалог предлагает **Update skill**.
- **Copy brief** копирует короткое объяснение для любого другого агента — Codex, Cursor, окна чата, — называя команду и способ её использования.

**Вручную.** Навык находится в [`skills/ducklocal`](https://github.com/JetSquirrel/ducklocal/tree/main/skills/ducklocal). Чтобы добавить его в один проект (пример для Claude Code):

```bash
# Run from the DuckLocal checkout; replace the destination with your project.
mkdir -p /path/to/your-project/.claude/skills
cp -R skills/ducklocal /path/to/your-project/.claude/skills/
```

Сначала изучите существующее место назначения, а не перезаписывайте локальные изменения. Другие агенты могут использовать те же `SKILL.md` и `references/cli.md` в своём поддерживаемом каталоге навыков.
