Bridge Local

Высокопроизводительная модульная платформа межмашинного взаимодействия (LAN Backbone)
Прямой P2P мост Linux <-> Windows | Модульная слоистая архитектура | Двойной режим: TUI для человека и Headless JSON для ИИ-агентов

---

1. Назначение платформы

Bridge Local — это легковесный, высокопроизводительный P2P мост между рабочими станциями Linux и Windows в локальной сети (LAN).

Платформа спроектирована как универсальная шина межмашинного взаимодействия, исключающая зависимость от тяжеловесных сторонних протоколов (Samba, SMB, NFS, WebDAV) и внешних облачных сервисов:

• Общее хранилище («Карман» / Pocket Storage): Потоковая передача файлов блоками по 64 КБ с валидацией контрольных сумм SHA-256 и атомарным переименованием.
• Мгновенный обмен заметками (Notes Engine): Оперативная отправка текста, гиперссылок и кодовых фрагментов между экранами с сохранением в JSONL-журнале.
• Удаленное выполнение PowerShell (Remote Execution): Запуск административных скриптов на Windows с консоли Linux с принудительной кодировкой UTF-8 (chcp 65001), контролем таймаутов и автоматическим каскадным уничтожением зависших дочерних процессов.
• Двойной интерфейс оператора:

  • Для человека: Полноэкранный терминальный TUI с палитрой Titanium Vivid, переключением 8 вкладок через стрелки ← / →, цифры 1..8, Tab и скроллингом списков.

  • Для ИИ-агентов (Antigravity agy_cli): Строгий машиночитаемый режим --json с детерминированными кодами возврата (0..5), нулевым ANSI-мусором и отсутствием блокировок ввода.

---

2. Архитектура и стек технологий

+-------------------------------------------------------------------------------+
|                             ОПЕРАТОРСКИЙ СЛОЙ                                 |
|   ┌──────────────────────────────┐        ┌───────────────────────────────┐   |
|   │   Human Operator (TUI/CLI)   │        │     AI Operator (agy_cli)     │   |
|   │   Rich, 8 Tabs, Spinners     │        │     --json, Strict Exit Codes │   |
|   └──────────────┬───────────────┘        └───────────────┬───────────────┘   |
+──────────────────┼────────────────────────────────────────┼───────────────────+
|                  ▼                                        ▼                   |
|   ┌───────────────────────────────────────────────────────────────────────┐   |
|   │                         bridge_client_linux                           │   |
|   │     ConnectionManager | ExecClient | PocketClient | NotesClient       │   |
|   │     Interactive TUI Engine (8 Tabs, Arrows/Digits/Tab Nav)            │   |

|   └──────────────────────────────────┬────────────────────────────────────┘   |
+──────────────────────────────────────┼────────────────────────────────────────+
|                                      ▼                                        |
|   ┌───────────────────────────────────────────────────────────────────────┐   |
|   │                             bridge_core                               │   |
|   │  ┌───────────────────────┐ ┌──────────────────────┐ ┌──────────────┐  │   |
|   │  │   protocol.py ('BR')  │ │  security.py (HMAC)  │ │ models.py    │  │   |
|   │  └───────────────────────┘ └──────────────────────┘ └──────────────┘  │   |
|   │  ┌───────────────────────┐ ┌──────────────────────┐ ┌──────────────┐  │   |
|   │  │ transport.py (Async)  │ │  pocket.py (Storage) │ │ notes.py     │  │   |
|   │  └───────────────────────┘ └──────────────────────┘ └──────────────┘  │   |
|   │  ┌───────────────────────┐ ┌──────────────────────┐ ┌──────────────┐  │   |
|   │  │  heartbeat.py (Probe) │ │  logger.py (JSONL)   │ │ codec.py     │  │   |
|   │  └───────────────────────┘ └──────────────────────┘ └──────────────┘  │   |
|   └──────────────────────────────────┬────────────────────────────────────┘   |
+──────────────────────────────────────┼────────────────────────────────────────+
|                                      │ TCP Streaming (Port 9732)              |
|                                      ▼                                        |
|   ┌───────────────────────────────────────────────────────────────────────┐   |
|   │                          bridge_agent_win                             │   |
|   │  ┌───────────────────────┐ ┌──────────────────────┐ ┌──────────────┐  │   |
|   │  │  service.py (SCM)     │ │  executor.py (Posh)  │ │ tray.py      │  │   |
|   │  └───────────────────────┘ └──────────────────────┘ └──────────────┘  │   |
|   │  ┌───────────────────────┐ ┌──────────────────────┐ ┌──────────────┐  │   |
|   │  │  context_menu.py      │ │  Watchdog PocketSync │ │ process_kill │  │   |
|   │  └───────────────────────┘ └──────────────────────┘ └──────────────┘  │   |
|   └───────────────────────────────────────────────────────────────────────┘   |
+-------------------------------------------------------------------------------+

Технологический стек:

• Среда выполнения: Python 3.12 - 3.14. Доступны автономные x64-дистрибутивы без внешних зависимостей.
• Типизация и контракты: Pydantic V2 с полной изоляцией DTO-моделей (bridge_core.models).
• Бинарный транспорт: Собственный Length-Prefixed Wire Framing: 2 байта маркера 'BR' (0x42 0x52), 4 байта длины (Big-Endian uint32) и полезная нагрузка до 64 МБ.
• Криптография и безопасность: HMAC-SHA256 подпись каждого фрейма на базе Pre-Shared Key (PSK), контроль дрейфа часов (Clock Skew) и LRU-кэш одноразовых номеров Nonce для защиты от Replay-атак.
• Удаленный исполнитель: Асинхронный PowerShell Runner с принудительной инициализацией UTF-8 (chcp 65001), контролем таймаутов и уничтожителем дерева процессов (taskkill /F /T).
• Служба Windows: Демон Windows SCM на базе pywin32 (servicemanager) с политикой автоматического восстановления при сбоях.
• Терминальный клиент: Typer CLI + Rich TUI с полноэкранным рендерингом в альтернативном экранном буфере.

---

3. Быстрый старт

Шаг 1: Запуск агента на Windows

1. Скачайте и распакуйте релизный архив BridgeLocal-Windows-x64.zip (например, в C:\BridgeLocal).
2. Запустите двойным кликом setup_connection.bat:
   • Мастер определит активный IPv4-адрес сетевой карты (например, 192.168.1.150).
   • Подтвердите порт 9732 и секретный токен PSK.
3. Выберите режим запуска:
   • Единый центр управления: Запустите start.bat (главное интерактивное меню).
   • В системном трее Windows: Запустите run_tray.bat (значок в области уведомлений рядом с часами).
   • Для отладки в окне: Запустите run_agent.bat.
   • Для постоянной фоновой службы: Кликните правой кнопкой по install_service.bat -> «Запуск от имени администратора».

Шаг 2: Подключение с Linux

1. Распакуйте BridgeLocal-Linux-x64.zip (или установите через uv tool install .):

   chmod +x bridge-cli

2. Подключитесь к машине Windows:

   bridge-cli connect 192.168.1.150:9732

3. Проверьте качество связи:

   bridge-cli ping

4. Запустите терминальный интерфейс:

   bridge-cli tui

Шаг 3: Основные повседневные команды CLI

# 1. Прямая отправка файлов в удаленный карман Windows (Direct File Drop):
bridge-cli send document.pdf archive.zip

# 2. Мгновенная отправка заметки или ссылки:
bridge-cli note send "https://github.com/Anhelm01/Bridge_Local"

# 3. Удаленное выполнение команды PowerShell:
bridge-cli exec "Get-Service -Name BridgeLocalAgent"

# 4. Просмотр сводного статуса всех подсистем:
bridge-cli status

# 5. Двунаправленная синхронизация общего хранилища файлов:
bridge-cli pocket sync

---

4. Терминальный интерфейс TUI

Интерфейс запускается командой bridge-cli tui (или bridge-cli без аргументов в интерактивном терминале). Он построен на базе палитры Titanium Vivid и разделен на 8 функциональных экранов:

[BRIDGE] █ [SPLASH] │ [DASH] │ [POCKET] │ [NOTES] │ [EXEC] │ [CONFIG] │ [DEV] │ [CONNECT]

Назначение вкладок и клавиши прямого перехода (1..8, ← / →, Tab, F1..F8):

Клавиша	Вкладка	Описание
1 / F1	SPLASH	Фирменный экран приветствия BRIDGES Master и аппаратная Neofetch-сводка.
2 / F2	DASH	Главная операционная панель: статус связи, пинг, ресурсы Windows-агента, очереди файлов.
3 / F3	POCKET	Таблица файлов кармана, направление синхронизации, хэши SHA-256 и строка прямой отправки файлов (PUSH FILE >).
4 / F4	NOTES	Лента текстовых сообщений и ссылок с отметками времени и автором, строка ввода новой заметки (NOTE >).
5 / F5	EXEC	Удаленный терминал PowerShell: журнал выполненных команд, потоки stdout/stderr и строка ввода (PS C:\>).
6 / F6	CONFIG	Реестр зарегистрированных узлов сети, сетевые адреса, тайминги и статус HMAC-SHA256.
7 / F7	DEV	Диагностический журнал трассировки сетевых пакетов, таймингов fail-fast и системных путей.
8 / F8	CONNECT	Быстрая перенастройка целевого узла (IP, порт, токен) без выхода из TUI.

Горячие клавиши управления:

• Стрелка Влево (←) / Стрелка Вправо (→): Мгновенное переключение на предыдущую / следующую вкладку.
• Цифры 1..8: Прямой переход к вкладке 1..8 в режимах просмотра (или через Alt+1..Alt+8).
• Tab / Shift+Tab: Последовательное переключение вкладок вперед и назад.
• Стрелка Вверх / Стрелка Вниз (↑ / ↓): Построчный вертикальный скроллинг списков файлов в POCKET, заметок в NOTES и журнала в DEV.
• Page Up / Page Down: Постраничный скроллинг списков на высоту экрана.
• Enter: Отправка введенного текста (команды, пути файла или заметки).
• Escape: Очистка строки ввода / быстрый возврат на вкладку DASH.
• Ctrl+C / Ctrl+Q: Выход из TUI с корректным закрытием экранного буфера.

---

5. Протокол взаимодействия для ИИ-агентов (agy_cli)

Для интеграции с ИИ-агентами (Antigravity CLI agy_cli) каждая команда bridge-cli поддерживает флаг --json:

bridge-cli exec "Get-Process -Name BridgeLocalAgent" --json

• Вывод в stdout представляет собой чистый JSON без ANSI-последовательностей оформления.
• Процесс гарантированно не блокируется на stdin.
• Стандартизированные коды завершения процесса (ExitCode):
  • 0 (SUCCESS): Успешное завершение.
  • 1 (GENERAL_ERROR): Ошибка синтаксиса аргументов или внутренняя ошибка.
  • 2 (NETWORK_ERROR): Целевой хост недоступен, соединение отклонено.
  • 3 (AUTH_ERROR): Ошибка PSK-токена, неверная подпись HMAC, replay-атака.
  • 4 (COMMAND_FAILED): Команда PowerShell завершилась с ненулевым кодом.
  • 5 (TIMEOUT): Превышен лимит времени выполнения команды или ответа RPC.

---

6. Навигация по документации

Вся техническая и эксплуатационная документация проекта полностью консолидирована в каталоге docs/ в виде 5 структурированных руководств:

1. docs/01_DEV.md — Полный справочник разработчика и архитектурная спецификация: внутреннее устройство слоев (bridge_core, bridge_agent_win, bridge_client_linux), спецификация сетевого фрейма 'BR' (6-байтовый заголовок), криптографический конверт HMAC-SHA256, JSON-RPC 2.0 DTO, SQLite-журнал заметок, атомарные операции Кармана и нюансы кодировок (UTF-8 / CP65001).
2. docs/02_SETUP_NAKED_LINUX.md — Пошаговое руководство по развертыванию из исходного кода на чистой ОС Linux: установка зависимостей, настройка uv/venv, конфигурирование bridge.toml, управление через консоль start.sh, справочник команд CLI/TUI и фоновая служба systemd --user.
3. docs/03_SETUP_NAKED_WINDOWS.md — Пошаговое руководство по развертыванию из исходного кода на чистой ОС Windows: установка Python/Git через winget, инициализация pywin32, настройка Брандмауэра Windows Defender, запуск интерактивной консоли Live Monitor, контекстное меню Проводника, отправка буфера обмена и локальная компиляция.
4. docs/04_BINARY_GUIDE_LINUX.md — Руководство по эксплуатации скомпилированного / автономного исполняемого файла bridge-cli на Linux: установка в ~/.local/bin, регламент взаимодействия для AI-агентов (agy_cli --json), таблица кодов возврата процесса и автозапуск через systemd.
5. docs/05_BINARY_GUIDE_WINDOWS.md — Руководство по эксплуатации скомпилированного автономного агента bridge-agent.exe на Windows: панель управления start.bat (все 12 пунктов), установка службы SCM (BridgeLocalAgent), значок в системном трее, интеграция с Проводником и глобальное развертывание в C:\BridgeLocal.