# Архитектура (/ru/docs/architecture)

`tg` и `max` — два инструмента командной строки на одном общем ядре. Здесь показано, как это ядро
собрано: какой пакет за что отвечает, как команда идёт из терминала в мессенджер и обратно, как
подключается новый мессенджер и где у устройства есть пределы. Страница для тех, кто хочет понимать,
как работает инструмент, и для тех, кто хочет участвовать в разработке.

Описан код, прочитанный 4 октября 2026 года. Ссылки на исходники зафиксированы на конкретных
коммитах, поэтому и после изменений кода показывают то, о чём здесь сказано. Как работают поиск,
граф разговоров и поисковые векторы — отдельная страница: [архитектура поиска](/llms.mdx/docs/ru/search-architecture/content.md).

Слои в нынешнем виде, границы, которые держат правила линтера, и то, какие части можно заменить, описаны
на странице [устройство кода](/llms.mdx/docs/ru/code-design/content.md); там более поздний снимок.

Ссылки на пакеты и слои ниже описывают датированный снимок. Пример MCP использует текущий компактный интерфейс: [реализация MCP](https://github.com/WireCatLabs/cli-core/blob/v0.213.0/src/mcp/surface.ts).

Названия пакетов используют текущую область `@wirecat`; ссылки на реализацию сохраняют указанный выше снимок исходников.

## Пакеты [#пакеты]

**Пакеты и зависимости между ними**

1. **@wirecat/tg-cli** — адаптер Telegram, вход, настройка; **@wirecat/max-cli** — протокол MAX, сессия, max serve, Bot API
2. **@wirecat/cli-core** — модель, сервисы, хранилище, защита отправки, команды, MCP
3. **@wirecat/cli-base** — вывод, ошибки и коды выхода, ключница, настройки, генератор; **cli-core-sqlite · -onnx** — закреплённые сборки SQLite и ONNX Runtime
4. снаружи: **@mtcute/node** — MTProto Telegram, только в tg; **ws · msgpack** — WebSocket MAX, только в max

Четыре собственных пакета и две закреплённые сборки, все опубликованы в npm под `@wirecat`:

| Пакет | За что отвечает |
| --- | --- |
| [`@wirecat/cli-base`](https://github.com/WireCatLabs/cli-base/tree/8648e39) | То, что нужно любому инструменту командной строки и не связано с мессенджерами: режимы вывода, отрисовка в терминале, закрытый список ошибок и их коды выхода, ключница, файлы настроек, часы, повторы, HTTP-клиент, генератор кода для HTTP API, самообновление. Его использует и `braze-cli`, который к переписке отношения не имеет. |
| [`@wirecat/cli-messaging`](https://github.com/WireCatLabs/cli-core/tree/c7cd479) | Всё о переписке, что не относится к одному мессенджеру: модель данных, поиск по именам, локальное хранилище SQLite, защита отправки, сервисы (сценарии), дерево команд, MCP-сервер, распознавание речи, фоновые процессы. |
| `@wirecat/cli-messaging-sqlite` | Сборки SQLite 3.53; загружаются только там, где собственный SQLite среды слишком старый (Bun на macOS, Node из дистрибутива Linux). |
| `@wirecat/cli-messaging-onnx` | ONNX Runtime в WebAssembly для локальных моделей embeddings. Распознавание речи использует `sherpa-onnx`. |
| [`@wirecat/tg-cli`](https://github.com/WireCatLabs/tg-cli/tree/4a36e85) | Адаптер Telegram поверх [mtcute](https://github.com/mtcute/mtcute), сессия Telegram, пошаговая настройка. Почти все команды `tg` приходят из cli-messaging. |
| [`@wirecat/max-cli`](https://github.com/WireCatLabs/max-cli/tree/fff19ff) | Протокол MAX (WebSocket, двоичные кадры), сессия MAX, фоновое соединение `max serve`, собственный MCP-сервер поверх общих сервисов и отдельная часть для официального Bot API MAX. |

Каждый инструмент закрепляет точную версию cli-messaging и cli-base. Изменение общего кода доходит
до пользователей через выпуск общего пакета, а затем выпуск каждого инструмента; обычно оба
инструмента выходят в один день.

**Главное правило общего пакета: в нём ничего не знает о конкретном мессенджере.** Правило линтера
запрещает импорт `@mtcute/*`, `ws` и папок адаптеров в `src/` cli-messaging
([настройки линтера](https://github.com/WireCatLabs/cli-core/blob/c7cd479/biome.json)). То, что есть только у
одного мессенджера, передаётся в поле `providerMetadata` общих типов.

## Одна команда от начала до конца [#одна-команда-от-начала-до-конца]

**Одна команда от начала до конца**

1. **argv** — tg work messages send "Book club" …
2. **run()** — профиль, настройки, тайм-аут, запись запуска; не бросает исключений
3. **команда** — разбирает свои параметры, просит сервисы
4. **защита отправки** — права → получатели → лимит в час; только для записи
5. **сервис** — сценарий, общий с MCP-инструментом
6. **адаптер + обёртки** — замеряют каждый вызов, сохраняют прочитанное; **локальная копия** — SQLite, одна транзакция на вызов
7. **мессенджер** — Telegram или MAX
8. **stdout · код выхода** — данные в stdout, заметки в stderr, всё закрыто

Возьмём `tg work messages send "Book club" "See you at 7"`:

1. **`run()`** ([program.ts](https://github.com/WireCatLabs/cli-core/blob/c7cd479/src/cli/program.ts))
   берёт `work` как профиль, вычисляет настройки в постоянном порядке (флаг → окружение → файл →
   значение по умолчанию), начинает запись запуска и ставит срок `--timeout`. Исключений он не
   бросает: любой исход становится кодом выхода.
2. **Команда** разбирает свои параметры и просит сервисы. О Telegram она ничего не знает.
3. **Защита отправки** ([guard.ts](https://github.com/WireCatLabs/cli-core/blob/c7cd479/src/sends/guard.ts))
   проверяет `permissions`, список получателей и лимит в час — до любого подключения. Чтение её не
   проходит. Каждая попытка записи — отправленная, отклонённая, неудачная или с неизвестным исходом —
   попадает в журнал отправок без текста.
4. **Сервис** выполняет сценарий. MCP-инструмент `tg_write` с командой `messages send` вызывает тот же метод, поэтому
   команда и инструмент дают одинаковый ответ и одинаковую ошибку на одинаковый ввод.
5. **Адаптер** превращает вызов в запросы Telegram, а ответ Telegram — в доменный `Message`. Вокруг
   него две обёртки: одна замеряет каждый вызов для записи запуска, другая сохраняет прочитанное в
   локальное хранилище.
6. **Вывод**: в stdout — результат и больше ничего; заметки и предупреждения — в stderr. Затем всё,
   что команда открыла, — сокет, таймер, база — закрывается, и процесс завершается.

Одноразовая команда, которая напечатала результат и продолжает работать, считается дефектом.
Соединение держат только `watch`, `serve` и `mcp serve`, и только пока работают.

## Слои [#слои]

**Слои: каждый вызывает только нижние**

1. **интерфейс** — команды CLI · MCP-инструменты
2. **сервисы** — messages, chats, people, inbox, archive, conversations…
3. **порты** — MessengerAdapter · MessageStore
4. **адаптеры** — TelegramAdapter (tg) · maxAdapter (max); **хранилище SQLite** — драйверы Node и Bun
5. **модель** — Chat, Message, Person, Page… только типы

Пять слоёв, каждый вызывает только нижние:

- **Модель** ([models.ts](https://github.com/WireCatLabs/cli-core/blob/c7cd479/src/domain/models.ts)) —
  `Chat`, `Message`, `Person`, `Page` и остальное. Только типы, без поведения и без мессенджера.
- **Адаптеры** — по одному на мессенджер, каждый в своём репозитории:
  [TelegramAdapter](https://github.com/WireCatLabs/tg-cli/blob/4a36e85/src/telegram/adapter.ts) в tg,
  [maxAdapter](https://github.com/WireCatLabs/max-cli/blob/fff19ff/src/adapter/max-adapter.ts) в max.
- **Порты** — два интерфейса, от которых зависят сервисы:
  [`MessengerAdapter`](https://github.com/WireCatLabs/cli-core/blob/c7cd479/src/cli/messenger/port.ts)
  и [`MessageStore`](https://github.com/WireCatLabs/cli-core/blob/c7cd479/src/store/store.ts).
- **Сервисы** ([services/](https://github.com/WireCatLabs/cli-core/blob/c7cd479/src/services/index.ts)) —
  messages, chats, people, inbox, archive, conversations, moderation и другие; каждый — простой
  объект, который создаёт фабрика.
- **Интерфейс** — команды CLI и MCP-инструменты.

Направление проверяется, а не подразумевается. Правила линтера запрещают импорт `commander` и файлов
команд из сервисов, защиты отправки и MCP-сервера; в tg импортировать mtcute может только
`src/telegram/`; в max команды не могут импортировать протокол, описания операций и сгенерированный
код. Запрещённый импорт ломает сборку с объяснением, почему.

**Сервисы открывают нужное при первом обращении.** Соединение, хранилище и аккаунт сервис получает
лениво ([deps.ts](https://github.com/WireCatLabs/cli-core/blob/c7cd479/src/services/deps.ts)), поэтому
чтение из локального хранилища не подключается к сети. Команда получает сервисы через `withServices`,
который закрывает открытое; MCP-инструмент строит их поверх соединения своей сессии.

**Инструмент заменяет сценарий, а не команду.** Мессенджер может переопределить один метод сервиса и
вызвать общий внутри своего; и команда, и MCP-инструмент видят замену:

```ts
services: (base) => ({
  messages: { ...base.messages, list: (chat, window) => maxList(base.messages, chat, window) },
}),
```

## Адаптеры [#адаптеры]

Чтобы подключить мессенджер, пишут две вещи: **адаптер**, который говорит с мессенджером, и
описание **`Messenger`**, которое рассказывает о нём общим командам: имя приложения, имя провайдера
в хранилище, как подключаться, как листать историю. cli-messaging при этом не меняют. Полное
руководство — [руководство по адаптерам](https://github.com/WireCatLabs/cli-core/blob/c7cd479/docs/dev/ADAPTERS.md).

**Обязательное ядро и необязательные группы.** `MessengerCore` — `self`, `me`, `resolve`, `chat`,
`send`, `logout`, `close` — обязателен. Остальное разбито на группы: `ServerReads`, `MessageEditing`,
`MessagePins`, `MessageReactions`, `MessagePolls`, `ReadState`, `LiveUpdates`, `PushedHistory`,
`MessageMedia`, `GroupAdmin`, `ChatFolders`, `ContactBook` и другие. Команда обращается к
необязательному методу через `capability()`; если у адаптера его нет, команда отвечает «этот
мессенджер не умеет …», а не падает.

**Отказать, а не выбросить.** Параметр, который мессенджер не может выполнить, — например, тихое
сообщение там, где таких нет, — отклоняется с `validation_error`. Молча он не игнорируется никогда.

**Номера — всегда строки.** Чаты, сообщения, люди, опросы. Номера сообщений MAX — 18 цифр, больше,
чем точно вмещает число JavaScript, и общий код не делает с номерами арифметики. Мессенджер, у
которого номера не маленькие целые, листает историю по времени.

**У отправки есть идентичность.** Каждая отправка получает `sendId`; он передаётся мессенджеру как
собственный номер сообщения клиента, если такой есть, и сервер отбрасывает повтор. Если запрос ушёл, а
ответ не пришёл, адаптер бросает `outcome_unknown`, а не `network_error`, который означал бы, что
сообщение не ушло. Повтор с тем же `sendId` даёт одно сообщение, а не два. При явном повторе нужно использовать тот же номер: измерено, что MAX убирает дубли по нему. Это не означает автоматический повтор.

**Ошибки переводятся на границе.** Любая ошибка библиотеки становится одним кодом из закрытого списка
cli-base, у каждого свой код выхода, поэтому скрипт может ветвиться по `$?`:

| Код | Выход | Код | Выход |
| --- | --- | --- | --- |
| `validation_error` | 2 | `timeout` | 9 |
| `configuration_error` | 3 | `network_error` | 10 |
| `authentication_error` | 4 | `provider_error` | 11 |
| `permission_error` | 5 | `provider_unavailable` | 12 |
| `not_found` | 6 | `invalid_response` | 13 |
| `confirmation_required` | 7 | `outcome_unknown` | 14 |
| `rate_limited` | 8 | `cancelled` | 130 |

**Типы библиотеки не выходят за адаптер.** Выше него — только доменные типы. Поэтому mtcute или
собственный код протокола max можно заменить.

**История с сервера или присланная.** Telegram отвечает на запрос истории чата, поэтому tg реализует
`ServerReads`. Мессенджер, который сам присылает историю клиенту, ставит `history: "store"`: общие
сервисы отвечают на чтение из локального хранилища, а `PushedHistory.feed()` адаптера передаёт пачки в
`serve`, который их сохраняет.

**Как два инструмента выполняют контракт.** Адаптер tg оборачивает mtcute, и только один файл,
[map.ts](https://github.com/WireCatLabs/tg-cli/blob/4a36e85/src/telegram/map.ts), знает форму объектов
mtcute. Адаптер max стоит на собственном
[`MaxClient`](https://github.com/WireCatLabs/max-cli/blob/fff19ff/src/client.ts), который владеет протоколом
MAX; [messenger.ts](https://github.com/WireCatLabs/max-cli/blob/fff19ff/src/messenger.ts) описывает MAX
общим командам, а большинство файлов команд max — тонкие обёртки над общими, добавляющие параметры MAX.

## Локальное хранилище [#локальное-хранилище]

Один файл SQLite, `~/.local/share/cli-messaging/wirecat.db` в Linux (`MESSAGING_STORE` указывает другой путь), хранит все мессенджеры и аккаунты —
профили tg, аккаунт max и его ботов — с ключом по провайдеру и аккаунту.

- **Две среды.** Под Node открывается `node:sqlite`, под Bun — `bun:sqlite`, каждый динамическим
  импортом: статический импорт модуля другой среды падает при загрузке.
- **Проверенный SQLite.** Перед открытием хранилище проверяет, что в SQLite среды есть
  полнотекстовый поиск, нужный схеме; номер версии этого не говорит. Где его нет, его место
  занимает закреплённая сборка: всегда в Bun на macOS, а в Node из дистрибутива Linux команда
  перезапускает себя с закреплённой библиотекой первой — до того, как что-то прочитано или отправлено
  ([sqlite-runtime.ts](https://github.com/WireCatLabs/cli-core/blob/c7cd479/src/sqlite-runtime.ts)).
- **Один метод — одна транзакция.** Каждый метод хранилища — одна целая операция: один синхронный
  `BEGIN IMMEDIATE` … `COMMIT` без `await` между ними. Два вызова в одном долгоживущем процессе не
  перемешаются внутри транзакции. Единственное намеренное исключение — перестройка разговоров чата:
  новая сборка пишется короткими транзакциями и включается ещё одной, поэтому наполовину записанная
  сборка никогда не читается.
- **Миграции только вперёд.** Пронумерованы, только добавляют, после выпуска не меняются
  ([manifest.ts](https://github.com/WireCatLabs/cli-core/blob/c7cd479/src/store/sqlite/manifest.ts)).
  Версия `min_compatible` позволяет старому инструменту работать с файлом, который мигрировал новый;
  её повышение требует выпуска с изменением совместимости и согласованного обновления обоих инструментов.
- **Запросы через Drizzle, встроенный в сборку.** Построитель запросов встроен в опубликованный
  пакет, а не устанавливается отдельно: это снизило его стоимость загрузки примерно с 200 мс до
  6 мс на процесс.

Хранилище держит тексты сообщений, чтобы отвечать без сети. Оно не зашифровано; что это значит для вас —
на странице [безопасность](/llms.mdx/docs/ru/security/content.md).

Что лежит в хранилище — сущности, связи между ними и то, как поиск сужает круг до контекста, — объясняет
страница [модель данных](/llms.mdx/docs/ru/data-model/content.md).

В хранилище два вида записей: **сущности** — сами люди, события и документы — и **записи источников** — то, что о них
знает один источник, с id провайдера в `external_id`. Инструмент пишет свои записи источников через cli-core и никогда
не выполняет SQL над файлом сам ([правила хранилища](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/store.md), [правила модели данных](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/data-model.md)).
**Появится в следующем выпуске cli-core:** каждый инструмент при запуске записывает своего провайдера в хранилище, и
другие инструменты узнают о новом источнике без выпуска cli-core; строки провайдера, которого ни один инструмент не
записал, пропускаются с пояснением и никогда не ищутся как сообщения ([правила архитектуры](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/architecture.md)).

## Приёмы, на которых всё держится [#приёмы-на-которых-всё-держится]

- **В машинном режиме stdout несёт только данные**: ни спиннера, ни цвета, ни предупреждений. На это
  опираются агенты и скрипты, и это проверяют тесты.
- **Одноразовая команда завершается.** Всё, что открывает сокет, таймер или слушатель, закрывает их
  на каждом пути выхода.
- **Чтение только наблюдает.** Чтение чата никогда не отмечает его прочитанным; для этого есть
  отдельная явная команда. Тест проверяет, что чтение не отправляет запрос «прочитано».
- **Имя никогда не угадывается.** Название, подходящее к нескольким чатам, — ошибка со списком, а не
  выбор наугад.
- **Одна модель прав, одна защита** — для каждой команды, каждого MCP-инструмента и, в max, для
  фонового `max serve` на всё, что через него проходит.
- **В событиях запуска нет содержимого.** Запись запуска хранит командную строку, номера, счётчики и
  время, агента, запустившего команду, и для упавшего запуска — ошибку с замаскированным текстом. Секрет,
  набранный в командной строке, всегда записан как `[redacted]`. Инструмент, у которого `config show` показывает
  `record_input`, хранит остальные слова так, как их набрали, чтобы владелец мог посмотреть, что запускалось; с
  `record_input: false` и в инструменте без этой настройки каждое значение аргумента, которое может быть содержимым,
  тоже записано как `[redacted]`. Текст сообщений, токены и номера телефонов в события запуска не попадают
  никогда; документация и тесты используют вымышленные примеры.
- **Сгенерировано и проверено.** Справочник команд (`commands.md`), обёртки операций max и типы Bot API
  генерируются; CI падает, если закоммиченная копия расходится с генератором.

## Сторона MAX [#сторона-max]

MAX не публикует API для личных аккаунтов, поэтому в max больше собственного кода, чем в tg:

- **Каждая операция описана один раз.** Каждый запрос MAX описан в
  [`src/spec/operations/`](https://github.com/WireCatLabs/max-cli/tree/fff19ff/src/spec/operations) со
  схемой и происхождением формы — измерено на живом соединении, записано из веб-клиента или прочитано
  в чужой обратной инженерии. Обёртки в `src/generated/` генерируются из этих описаний и руками не
  правятся.
- **Двоичные кадры, как у веб-клиента.** MessagePack со сжатием LZ4; весь кодек — один файл,
  [frame.ts](https://github.com/WireCatLabs/max-cli/blob/fff19ff/src/protocol/frame.ts). Число, которое
  потеряло бы цифры, приходит как `bigint` и выше кодека становится строкой.
- **Выглядит как официальный клиент.** User agent и все поля, по которым узнают клиента, взяты у
  web.max.ru; собственного имени на проводе нет.
- **Соединение держит `max serve`.** Его запускает в фоне первая команда, которой нужен MAX;
  следующие команды идут через него, а сам он останавливается через 15 минут без дела.
- **Собственный MCP-сервер.** `max <профиль> mcp serve` держит одно соединение со входом на сессию агента и
  закрывает его после короткого простоя; его инструменты вызывают те же общие сервисы, что и команды.
- **Bot API — отдельная часть.** `max bot …` работает с официальным HTTP Bot API MAX. Его типы и схемы
  генерируются из официального документа OpenAPI генератором cli-base, и ничто в `src/bot/` не делит с
  личным аккаунтом ни транспорт, ни сессию, ни сгенерированный код.

## Тесты [#тесты]

- **Тесты не трогают ваши данные.** Настройки, состояние, кэш и временная папка на время прогона
  лежат в песочнице ([sandbox.ts](https://github.com/WireCatLabs/max-cli/blob/fff19ff/src/testing/sandbox.ts)).
- **Контрактные проверки адаптеров.** cli-messaging поставляет набор данных, поддельный адаптер и
  контрактные проверки ([src/kit](https://github.com/WireCatLabs/cli-core/tree/c7cd479/src/kit)).
  Адаптер мессенджера прогоняет те же проверки поверх своего поддельного клиента; ни одна не ходит в
  живой сервис.
- **Команды проверяются целиком** через `run(argv, environment)`: с мессенджером по сценарию,
  ключницей в памяти и перехваченным выводом.
- **Обе среды.** CI работает на Linux, macOS и Windows, под Node и Bun, и на старом Node — чтобы
  увидеть, как хранилище отказывается от SQLite без полнотекстового поиска.
- **Паритет между инструментами** проверяет общий аудитор: он сравнивает команды, параметры, схемы MCP
  и тесты tg и max.
- **Живые проверки отдельны и ручные**: только на тестовых аккаунтах и тестовых чатах, с согласия
  владельца, с записью формы каждого ответа и никогда — его содержимого.

## Пределы и компромиссы [#пределы-и-компромиссы]

- **Протокол MAX неофициальный.** Всё, что max о нём знает, измерено или получено обратной
  инженерией. Он может перестать работать без предупреждения; тогда команда скажет об этом в stderr,
  а не покажет пустой список.
- **Одна запись за раз на хранилище.** Запись блокирует цикл событий процесса, пока идёт, а другой
  процесс ждёт блокировку до 5 секунд. Большие записи разбиваются на ограниченные пачки.
- **Нет векторного индекса.** Поиск разговоров сравнивает векторы в JavaScript постранично; работа
  растёт с числом фрагментов в области поиска ([подробнее](/llms.mdx/docs/ru/search-architecture/content.md)).
- **Защита живёт внутри инструмента.** Она останавливает агента, которого уговорили отправить, а не
  агента с оболочкой, который решил поменять настройки. Внешняя граница — песочница или отдельный
  пользователь ОС.
- **Локальное хранилище не зашифровано.** От потерянного компьютера защищает шифрование всего диска.

## Участие в разработке: с чего начать [#участие-в-разработке-с-чего-начать]

- Новый инструмент на общем хранилище: [Разработка на WireCat](/llms.mdx/docs/ru/build-concepts/content.md), от основ до соответствия стандартам.
- Новый мессенджер: [руководство по адаптерам](https://github.com/WireCatLabs/cli-core/blob/c7cd479/docs/dev/ADAPTERS.md),
  затем контрактные проверки.
- Общий код: [заметки об архитектуре cli-messaging](https://github.com/WireCatLabs/cli-core/blob/c7cd479/docs/dev/ARCHITECTURE.md).
- Telegram: [заметки об архитектуре tg](https://github.com/WireCatLabs/tg-cli/blob/4a36e85/docs/dev/ARCHITECTURE.md).
- MAX: [заметки об архитектуре max](https://github.com/WireCatLabs/max-cli/blob/fff19ff/docs/dev/ARCHITECTURE.md)
  и [заметки о протоколе](https://github.com/WireCatLabs/max-cli/blob/fff19ff/docs/dev/protocol.md).
- Вопросы: [чат поддержки](https://t.me/wirecatdev).

## Проверки поведения агента [#проверки-поведения-агента]

Архитектура выше описывает снимок от 4 октября. Отдельный [отчёт от 8 октября](https://github.com/WireCatLabs/cli-core/blob/73a57e1d229441d27f8325677808c3ae09175803/docs/dev/evaluations/2026-10-08-independent-stats-agent-evaluation.md)
фиксирует собственные версии SDK, искусственные данные, границы контекстов моделей, первые
ошибки и наблюдения CLI/MCP. Шесть контекстов содержат 38 проверенных сценариев; общие задачи
делают результаты зависимыми. Они не доказывают корректность реального сетевого адаптера или
агента в целом. Точная модель первых запусков не записана; MCP вызывался через shell proxy.

[Стенд воспроизведения](https://github.com/WireCatLabs/cli-core/tree/main/scripts/evals) находится в cli-messaging. При сравнении нового запуска
запишите модель, runner и SDK, clock/seed, prompts и первые ошибки. Проверки транспорта и
fixtures отделены от независимых модельных запусков. [Руководство безопасности](/llms.mdx/docs/ru/security/content.md)
объясняет, что проверять перед использованием статистического вывода агента.
