# Portability: UNIVERSAL
# Last validated: 2026-05-17
# Next review: 2027-05-17

ИМЯ ОБРАБОТЧИКА
------------
multi_llm_protocol.py - Координация параллельных агентов LLM

ОПИСАНИЕ
------------
Протокол V3 для безопасной параллельной работы нескольких агентов ИИ (Claude, Gemini,
Второй пилот, Оллама, Перплексити, Мистраль). Контролирует присутствие, управляет
эксклюзивный доступ к файлам и синхронизация действий агентов
Файлы присутствия, блокировки и сигналы подтверждения. Дополнительно: на базе БД
Система карточек штампов для текущего статуса в таблице Partner_presence.

ОПЕРАЦИИ
-----------
bach llm presence [dir] [task]      Создать присутствие в каталоге
bach llm check [dir]                Проверить других агентов в каталоге
bach llm lock <datei|ordner>        Получить блокировку файла или каталога
bach llm unlock [datei]             Снять собственные блокировки
bach llm handshake [dir]            Начать рукопожатие с другими агентами
bach llm status [dir]               Состояние Multi-LLM + DB показать текущий статус

БАЗОВЫЙ ПРОТОКОЛ V3
-----------------
1. Система ПРИСУТСТВИЯ (файлы)
   - .<agent>_presence: Heartbeat, статус, рабочий статус
   - Таймаут после 120 секунд бездействия
   - Статус: АКТИВНО, ЗАВЕРШЕНО

2. Система БЛОКИРОВКИ (файлы+папки)
   - Файл: <файл>.lock.<агент>
   - Папка: <папка>/.dirlock.<агент>
   - Таймаут блокировки: 300 секунд (снятие устаревших блокировок)
   - Отсрочка: 5 секунд между попытками

3. РЕЗЕРВНАЯ система
   - <файл>.bak перед изменением
   - Автоматически в Safe_write/safe_append

4. Протокол рукопожатия
   - файлы .handshake_<агент>
   - Автоматическое обнаружение агента
   - Ждет макс. 30 секунд для подтверждения

5. КАРТОЧКИ ШТАМПОВ БД (v1.1.71)
   - таблица Partner_presence
   - clock_in/ clock_out при запуске/выключении
   - current_task + Last_heartbeat для текущего статуса
   - Тайм-аут контрольного сигнала: 5 минут (настраиваемый)

ПРИМЕРЫ
---------
# Активировать агент
bach llm presence /c/Users/User/project processing

# Проверить другие агенты
bach llm check /c/Users/User/project

# Получить блокировку файла
bach llm lock /c/Users/User/project/results.txt

# Снять блокировку
bach llm unlock /c/Users/User/project/results.txt

# Начать рукопожатие
bach llm handshake /c/Users/User/project

# Полный статус (включая текущий статус БД)
bach llm status /c/Users/User/project

# Безопасная операция записи (API)
протокол.safe_write(Path("data.txt"), "Content", timeout=60)

# Безопасное добавление (API)
протокол.safe_append(Path("log.txt"), "Новая строка\n", timeout=60)

# DB: Clock In при запуске
db = PartnerPresenceDB(Path("data/bach.db"), имя_агента='claude')
db.clock_in(task="Research",work_dir="/project", session_id="uuid-123")

# БД: Получить текущий статус
партнеры = db.get_online_partners(timeout_MINUT=5)

ФАЙЛЫ
-------
Доступ к файлам (относительно системы/):
  Hub/multi_llm_protocol.py Классы MultiLLMProtocol, MultiLLMHandler
  data/bach.db таблица Partner_presence (карточки марок)

Сгенерированные файлы (в рабочем каталоге):
  .<agent>_presence Маркер присутствия
  <файл>.lock.<агент> Блокировка файла
  <папка>/.dirlock.<агент> Блокировка папки
  <файл>.bak резервная копия перед изменением
  .handshake_<agent> Сигнал/ответ рукопожатия

СМОТРИ ТАКЖЕ
----------
bach --help                 Общая страница справки
hub/base.py Класс BaseHandler
Определение таблицы data/schema.sql Partner_presence
Урок № 62, № 63 История развития (эксперимент Клод + Близнецы)
