Bridge Local

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

---

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

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

В версии v0.3.0 платформа перешла на архитектуру Dual-Role Peer (Universal Node): любой узел может одновременно выступать сервером-демоном (BridgeService) и клиентом (BridgeClient):

• Симметричное удаленное исполнение (Remote Execution):
  • С Linux на Windows: запуск скриптов PowerShell с UTF-8 (chcp 65001), контролем таймаутов и каскадным уничтожением процессов.
  • С Windows на Linux: запуск Bash-скриптов и утилит (bridge-agent exec "uname -a; df -h").
• Общее хранилище («Карман» / Pocket Storage): Потоковая передача файлов блоками по 64 КБ с валидацией контрольных сумм SHA-256, атомарным переименованием и удаленной навигацией (ls, find, pocket clear).
• Мгновенный обмен заметками (Notes Engine): Двунаправленная отправка текста, ссылок и сниппетов с ACID-журналом SQLite.
• Фоновые службы и автозапуск:
  • На Linux: демон bridge-cli service с встроенной генерацией служб пользователя systemd --user.
  • На Windows: системная служба Windows SCM (BridgeLocalAgent), значок в трее и контекстное меню Проводника.
• Двойной интерфейс оператора:
  • Для человека: Компактный терминальный Mini HUD (4-5 строк) с палитрой Titanium Vivid и единой строкой команд Omnibar.
  • Для ИИ-агентов (Antigravity agy_cli): Строгий машиночитаемый режим --json с детерминированными кодами возврата (0..5), нулевым ANSI-мусором и отсутствием блокировок ввода.

---

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

+-------------------------------------------------------------------------------+
|                             ОПЕРАТОРСКИЙ СЛОЙ                                 |
|   ┌──────────────────────────────┐        ┌───────────────────────────────┐   |
|   │   Human Operator (Mini HUD)  │        │     AI Operator (agy_cli)     │   |
|   │   Mini HUD, Omnibar          │        │     --json, Strict Exit Codes │   |
|   └──────────────┬───────────────┘        └───────────────┬───────────────┘   |
+──────────────────┼────────────────────────────────────────┼───────────────────+
|                  ▼                                        ▼                   |
|   ┌───────────────────────────────────────────────────────────────────────┐   |
|   │               bridge_client_linux  /  bridge_agent_win                │   |
|   │       ConnectionManager | BridgeClient | TUI Engine | SCM / Tray      │   |
|   └──────────────────────────────────┬────────────────────────────────────┘   |
+──────────────────────────────────────┼────────────────────────────────────────+
|                                      ▼                                        |
|   ┌───────────────────────────────────────────────────────────────────────┐   |
|   │                             bridge_core                               │   |
|   │  ┌───────────────────────┐ ┌──────────────────────┐ ┌──────────────┐  │   |
|   │  │   codec.py ('BR')     │ │ security.py (AEAD)   │ │ models.py    │  │   |
|   │  └───────────────────────┘ └──────────────────────┘ └──────────────┘  │   |
|   │  ┌───────────────────────┐ ┌──────────────────────┐ ┌──────────────┐  │   |
|   │  │ executor.py (Bash/PWSH│ │ service.py (Daemon)  │ │ client.py    │  │   |
|   │  └───────────────────────┘ └──────────────────────┘ └──────────────┘  │   |
|   │  ┌───────────────────────┐ ┌──────────────────────┐ ┌──────────────┐  │   |
|   │  │ pocket.py (Storage)   │ │ notes.py (SQLite)    │ │ logger.py    │  │   |
|   │  └───────────────────────┘ └──────────────────────┘ └──────────────┘  │   |
|   └──────────────────────────────────┬────────────────────────────────────┘   |
|                                      │ TCP Stream + AEAD / HMAC (Port 9732)   |
|                                      ▼                                        |
|   ┌───────────────────────────────────────────────────────────────────────┐   |
|   │            Dual-Role Peer Node (Linux <=======> Windows)              │   |
|   └───────────────────────────────────────────────────────────────────────┘   |
+-------------------------------------------------------------------------------+

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

• Среда выполнения: Python 3.12 - 3.14 (протестировано на Arch Linux, Ubuntu, Windows 10/11 x64).
• Тестовое покрытие: 378/378 тестов проходят (100% pass rate). Строгий mypy + ruff.
• Типизация и контракты: Pydantic V2 с полной изоляцией DTO-моделей (bridge_core.models).
• Бинарный транспорт: Length-Prefixed Wire Framing: 2 байта маркера 'BR', 4 байта длины (uint32) и полезная нагрузка до 64 МБ.
• Криптография и безопасность: Сквозное AEAD-шифрование (AES-256-GCM / HKDF RFC 5869) + защитный конверт HMAC-SHA256, контроль дрейфа часов (Clock Skew) и LRU-кэш Nonce от Replay-атак.
• Удаленные исполнители: Платформенные BashExecutor (Linux) и PowerShellExecutor (Windows) с UTF-8, контролем таймаутов и уничтожением деревьев процессов.

---

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

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

1. В корне репозитория (или распакованного архива) запустите start.bat.
2. Выберите пункт [1] QUICK START (Recommended):
   • Автоматически откроет порты 9732 TCP и 9735 UDP в Windows Firewall.
   • Зарегистрирует пункт «Отправить в Карман» в Проводнике Windows.
   • Запустит фонового агента и значок в системном трее.

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

1. В корне репозитория запустите ./start.sh (или bridge-cli):
2. Подключитесь к машине Windows:

   bridge-cli connect 192.168.1.150:9732

3. Проверьте связь и запустите TUI:

   bridge-cli ping
   bridge-cli tui

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

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

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

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

# 4. Удаленная файловая навигация:
bridge-cli ls "C:\Projects"
bridge-cli find "*.log" "C:\Projects"

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

---

4. Терминальный микро-интерфейс (Mini HUD)

Интерфейс запускается командой bridge-cli tui (или bridge-cli без аргументов в интерактивном терминале). Он представляет собой компактный HUD высотой в 4–5 строк, не загромождающий терминал и отображающий состояние подключения, пинг, количество файлов в кармане и статус последней операции:

┌── BRIDGE LOCAL [MINI] ─────────────────────────────────────────────────────┐
│ ● WIN-PC (192.168.100.6:9732) | 1.8ms | POCKET: Local (3) | ONLINE         │
│ LAST: ✓ [exec] exit 0                                                      │
└────────────────────────────────────────────────────────────────────────────┘
  >  █

Команды Omnibar:

• e <команда> — выполнение удаленной команды на Windows (PowerShell) или Linux (Bash).
• send <путь> / drop <путь> — прямая отправка файла на удаленный узел.
• drop -B — двусторонняя синхронизация кармана (Sync Pocket).
• pocket ls — просмотр содержимого локального кармана.
• pocket clear -f — очистка файлов локального кармана.
• note <текст> — отправка быстрой текстовой заметки.
• token [-g|-c] — просмотр, генерация (-g) или копирование (-c) токена безопасности.
• connect <IP:PORT> — быстрое переключение целевого узла с проверкой пинга.
• scan [-a] — поиск узлов в локальной сети (UDP broadcast 9735). Флаг -a — автоподключение.
• clear — очистка строки статуса последней операции.
• q / quit / exit / :q — выход из Mini HUD.

---

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/:

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

---

7. Лицензия

Проект лицензирован под условиями GNU Affero General Public License v3.0 (AGPLv3).
Автор: Кратюк Матвей (2026).