# KD Context beta: подключение без путаницы

KD Context запускается на вашем компьютере между IDE и KeyDealer API. В режиме
`smart` он удаляет точные повторы и сокращает старые длинные результаты
инструментов до отправки запроса.

Схема работы:

```text
IDE → KD Context на вашем компьютере → KeyDealer API
```

## Что понадобится

- macOS или Linux;
- Node.js 22 или новее;
- полный API-ключ вида `kd_live_…`.

Полный `kd_live_…` показывается в кабинете только один раз при создании. Если
вы видите `kd_live_••••••••abcd`, это маска. Создайте новый ключ и скопируйте
его до закрытия окна.

## Шаг 1. Установите KD Context

Скопируйте весь блок, вставьте в Terminal и нажмите Enter:

```bash
curl -fsSLo kd-context-beta.tgz https://keydealer.ru/downloads/kd-context-beta.tgz
tar -xzf kd-context-beta.tgz
cd kd-context-beta
./install.sh
```

## Шаг 2. Сохраните настоящий ключ

### macOS

Сначала скопируйте полный `kd_live_…` в кабинете. Затем выполните:

```bash
pbpaste | kd-context key set
printf '' | pbcopy
```

Ключ сохранится в Keychain, а буфер обмена очистится.

### Linux

Выполните блок. После первой строки вставьте `kd_live_…` и нажмите Enter.
Символы на экране не появятся — так и должно быть.

```bash
read -s KD_KEY
printf '%s' "$KD_KEY" | kd-context key set
unset KD_KEY
```

## Шаг 3. Включите умную экономию

```bash
kd-context mode smart
kd-context start
```

Не закрывайте это окно Terminal во время работы. Если его закрыть, локальный
помощник остановится.

## Шаг 4. Подключите IDE

Откройте второе окно Terminal и выполните:

```bash
kd-context token
```

Команда покажет локальный токен `kd_local_…`. Укажите в настройках
OpenAI-compatible provider:

```text
Base URL: http://127.0.0.1:4187/v1
API key:  kd_local_… из команды kd-context token
```

Не вставляйте `kd_live_…` в IDE. Настоящий ключ хранит операционная система;
IDE получает только локальный `kd_local_…`.

## Шаг 5. Проверьте подключение

```bash
kd-context status
```

В JSON должны быть:

```json
{
  "mode": "smart",
  "api_key_configured": true
}
```

Остальные поля можно не запоминать. Если эти два значения совпали, настройка
готова.

## Если не получилось

### В кабинете виден только ключ с точками

Полное значение восстановить нельзя. Создайте новый ключ и скопируйте его до
закрытия окна.

### IDE пишет `Connection refused`

KD Context не запущен. Выполните `kd-context start` и оставьте это окно
Terminal открытым.

### IDE пишет об ошибке авторизации

Проверьте, что в IDE указан `kd_local_…` из `kd-context token`, а не настоящий
`kd_live_…`.

### Нужно сменить проектный ключ

Повторите шаг 2 с другим полным ключом. На одном компьютере KD Context хранит
один активный настоящий ключ за раз.

## Режимы

- `smart` — рекомендуемый: консервативно сокращает отправляемый контекст;
- `strict` — считает и предупреждает, но не меняет запрос;
- `passthrough` — передаёт запрос без изменений, удобно для сравнения.

Переключение:

```bash
kd-context mode smart
kd-context mode strict
kd-context mode passthrough
```

## Что KD Context хранит

- настоящий ключ — в Keychain macOS или Secret Service Linux;
- локально — только технические метрики: модель, режим, число токенов,
  стоимость и технический ID операции;
- тексты запросов и ответов на диск не записываются.

KD Context не создаёт model-side KV-cache и не обещает скидку за повторный
префикс. `smart` уменьшает только тот контекст, который действительно уходит в
API.

## Проверка агентом

Агент с доступом к Terminal может сам прочитать машиночитаемый статус:

```bash
kd-context status
```

Готовая фраза для агента:

> Выполни `kd-context status`. По полученному JSON назови активный режим, скажи,
> может ли KD Context менять тело запроса, сохраняются ли тексты запросов и
> поддерживается ли model-side prompt cache. Не угадывай.