# Компаньон-приложения

## Что такое компаньон-приложения?

Компаньон-приложения, это нативные приложения для iOS, Android и macOS, которые подключаются к вашему Gateway как **узлы**. Узлы открывают возможности устройства, камеру, canvas, запись экрана, геолокацию, голос и выполнение команд системы, для ваших агентов.

Думайте об этом так: Gateway, это мозг, а компаньон-приложения, это руки и глаза на ваших устройствах.

## Как работают узлы

1. **Подключение**, компаньон-приложение подключается к вашему Gateway через WebSocket
2. **Сопряжение**, новые устройства проходят процесс подтверждения сопряжения
3. **Регистрация возможностей**, приложение сообщает Gateway, что оно умеет (камера, canvas, геолокация и т.д.)
4. **Агенты вызывают**, во время разговоров агенты могут запрашивать у узла сделать фото, записать экран, отрисовать canvas и многое другое

Узлы, это **не шлюзы**, они не запускают собственный ИИ. Это периферийные устройства, расширяющие возможности ваших агентов.

## Компаньон-приложение для macOS

Приложение для macOS находится в строке меню и выполняет роль как компаньон-узла, так и менеджера Gateway.

### Возможности
- **Canvas**, отрисовка интерактивного веб-контента в нативном окне
- **Камера**, съёмка фото и видеоклипов (передняя/задняя камера)
- **Запись экрана**, полноэкранная или по приложениям запись
- **Выполнение команд системы**, запуск команд оболочки на Mac (ограничено подтверждением exec)
- **Уведомления**, отправка нативных уведомлений macOS с параметрами приоритета
- **Геолокация**, GPS при наличии

### Дополнительные функции
- **Управление Gateway**, запуск, остановка и мониторинг Gateway
- **Управление разрешениями**, управляет разрешениями macOS TCC (уведомления, специальные возможности, запись экрана, микрофон, распознавание речи, AppleScript)
- **Глубокие ссылки**, схема URL `neotask://` для запуска агентов с параметрами
- **Установка CLI**, устанавливает инструмент командной строки `neotask`

## Приложение для iOS

Приложение для iOS подключается как узел к вашему Gateway, предоставляя мобильные возможности вашим агентам.

### Возможности
- **Canvas**, отрисовка интерактивного контента на основе SwiftUI
- **Камера**, фото и видеоклипы (передняя и задняя камеры)
- **Запись аудио**, захват с микрофона
- **Геолокация**, GPS с выбором точности
- **Уведомления**, нативные push-уведомления iOS

### Функции
- **Обнаружение**, находит ваш Gateway через Bonjour (LAN), Tailscale (VPN) или ввод вручную
- **Сопряжение**, безопасное сопряжение устройства с подтверждением от Gateway
- **Голосовое пробуждение**, активация ключевым словом для работы без рук
- **Режим разговора**, непрерывный голосовой диалог
- **Расширение для шаринга**, делитесь контентом из других приложений напрямую с вашим агентом
- **A2UI**, отрисовка UI, управляемого агентом, на canvas устройства

### Ограничения
- Дизайн, ориентированный на передний план (iOS приостанавливает WebSocket-соединения в фоновом режиме)
- Строгие ограничения на фоновые команды
- В настоящее время находится в режиме внутреннего превью

## Приложение для Android

Приложение для Android подключается как узел с возможностями, аналогичными iOS.

### Возможности
- **Canvas**, отрисовка UI на основе Jetpack Compose
- **Камера**, фото и видео (передняя/задняя, с запросом разрешения)
- **Запись экрана**, системный захват экрана (Android 10+)
- **Геолокация**, GPS с режимами точности
- **Отправка SMS**, на устройствах с поддержкой телефонии
- **Чат и история**, просмотр истории разговоров на устройстве

### Функции
- **Сервис переднего плана**, постоянное уведомление поддерживает соединение активным
- **Общие сессии**, одна сессия на всех подключённых узлах
- **Современный Android**, требует Android 12+ (API 31)

## Безголовой хост узла

Запускайте узел без какого-либо UI, идеально подходит для серверов сборки, удалённых машин или безголовых Linux-серверов.

### Возможности
- **Выполнение команд системы**, запуск команд на хосте узла
- **Белый список команд**, настройка того, какие команды может выполнять узел
- **Постоянный сервис**, установить как службу launchd/systemd

### Варианты использования
- Агенты сборки CI/CD, позвольте вашему ИИ-агенту запускать сборки на удалённом сервере
- Автоматизация домашней лаборатории, запуск команд на Raspberry Pi или домашнем сервере
- Оркестрация нескольких машин, координация задач на нескольких машинах

## Сопряжение устройств

### Процесс сопряжения
1. Компаньон-приложение представляет свою идентичность устройства (отпечаток + публичный ключ)
2. Gateway выдаёт запрос на подтверждение сопряжения
3. Вы подтверждаете устройство через десктопное приложение или дашборд
4. Gateway выдаёт токен устройства для будущих соединений

### Модель доверия
- **Локальные устройства** (loopback) автоматически одобряются для удобства
- **Нелокальные устройства** требуют явного подтверждения
- Токены устройств хранятся локально и повторно используются при переподключении

## Подтверждение выполнения команд

Для узлов, которые могут выполнять системные команды (macOS, безголовые хосты), подтверждения exec управляют тем, что разрешено:

- **Режим белого списка**, выполняются только предварительно одобренные команды
- **Режим запроса**, неизвестные команды запрашивают у вас подтверждение
- **Полный режим**, без ограничений (используйте с осторожностью)

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