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

СЛУЖБА ЧАТА BACH — многопользовательский бот Telegram + API управления + системный трей
==========================================================================

ОПИСАНИЕ
------------
Служба чата BACH является преемником Claude Bridge. Он предлагает один
Интегрированный с BACH бот Telegram с подключаемыми серверными модулями LLM, один
API управления HTTP и кроссплатформенный системный трей.

Архитектура (3 уровня):
  - model_backend.py: Подключаемая абстракция серверной части (Ollama, Claude CLI,
                         Codex CLI, Claude API, OpenAI API)
  -chat_runtime.py: независимая от серверной части среда выполнения чата с циклом использования инструментов,
                         Управление контекстом, режимы безопасности, сводка
  - telegram_chat.py: бот Telegram со всеми командами + API управления
  -chat_tray.py: кроссплатформенный системный трей (macOS/Windows/Linux)

Бэкэнды:
  - ollama: локальный сервер Ollama с использованием встроенных инструментов.
  - claude: Claude Code CLI (--продолжить сеанс, собственные инструменты)
  - кодекс: Codex CLI (модели GPT, собственные инструменты)
  - claude-api: Антропный API (требуется ANTHROPIC_API_KEY)
  - openai: OpenAI API (требуется OPENAI_API_KEY)

Режимы безопасности:
  - безопасно: инструменты только для чтения (ls, cat, grep, git, docker и т. д.)
  - полный: также инструменты записи (execute_command, write_file)
           Активация: /mode полное подтверждение


ТЕЛЕГРАММНЫЕ КОМАНДЫ
-----------------
  /начать приветственное сообщение
  /очистить сброс разговора
  /backend [имя] [модель] Переключение бэкэнда (ollama|claude|codex|claude-api|openai)
  /model <имя> Изменить модель
  /mode [safe|full] Безопасный режим
  /think режим мышления включен (тщательно)
  /nothink режим мышления ВЫКЛ (быстро)
  /settings Показать все настройки
  /status Статус системы
  /remember <текст> Память БАХА: Помните
  /recall <поиск> Память БАХа: Поиск
  /facts Память БАХА: Факты
  /bach <cmd> Выполнить команду BACH
  /task <текст> Создать задачу
  /tasks Открытие задач
  /maxrounds [N] Установить максимальное количество ходов инструмента (0=неограниченно)
  Голосовое сообщение Шепот транскрипция -> Чат
  Распознавание текста OCR на фотографиях -> Чат


CONTROL API (порт 8081)
-----------------------
  GET/Веб-панель (HTML)
  GET /api/status Текущий статус (включая активность инструмента)
  GET /api/backends Доступные серверные части со статусом
  GET /api/models Модели текущего бэкэнда
  POST /api/backend Переключить серверную часть: {"name": "claude", "model": "opus"}
  POST /api/mode Установить режим: {"mode": "safe"}
  POST /api/model Установить модель: {"model": "qwen3.5:35b-a3b"}
  POST /api/think Режим мышления: {"думаю": true}
  POST /api/max_tool_rounds Максимальное количество раундов инструмента: {"раунды": 10} (0 = неограниченно)
  POST /api/chat сообщение чата: {"prompt": "...", "chat_id": "..."}


СИСТЕМНЫЙ ЛОТОК
-----------
  Начало: pythonchat_tray.py [--host HOST] [--port PORT]

  Особенности:
    - Значок состояния: зеленый (безопасен), оранжевый (заполнен), красный (не подключен)
    - Подменю серверной части: все доступные серверные части.
    - Подменю модели: модели текущего бэкэнда.
    - Переключение режима: Безопасный/Полный
    - Think Toggle: ВКЛ/ВЫКЛ
    - Максимальное количество раундов инструмента: пресеты (5/10/20/неограниченно)
    - Активность инструмента: текущий инструмент + скругление в названии лотка.
    - Открыть веб-панель
    - Кроссплатформенность: macOS, Windows, Linux (через pystray)

  Удаленный лоток (из другой системы):
    pythonchat_tray.py --host macstudvonlukas --port 8081


ФАЙЛЫ
-------
  Бот:hub/_services/chat/telegram_chat.py
  Время выполнения:hub/_services/chat/chat_runtime.py
  Бэкэнды:hub/_services/llm/model_backend.py
  Лоток:hub/_services/chat/chat_tray.py
  Конфигурация: ~/.config/bach/telegram_chat.json
  Токен: ~/.credentials/telegram_bot_token
  Идентификатор владельца: ~/.credentials/telegram_owner_id
  Подсказка: data/system_prompt_buddha.txt
  Журналы: ~/Library/Logs/bach/telegram-bot.log (macOS), data/logs/ (Windows)

  Агенты запуска (macOS):
    com.bach.telegram-bot Telegram-бот
    com.bach.chat-tray системный трей
    com.bach.gui-server Панель управления графическим интерфейсом (:8000)

  Кронтаб (macOS):
    */5 * * * * sync_mirror.sh Зеркальная синхронизация OneDrive
    0 */6 * * * Rotate_logs.sh Ротация журналов


КОНФИГУРАЦИЯ
-------------
~/.config/bach/telegram_chat.json:
    {
      "bot_token": "...",
      "owner_id": "...",
      "выпечка": {
        "тип": "оллама",
        "base_url": "http://localhost:11434",
        "default_model": "qwen3.5:35b-a3b"
      }
    }

  Переменные среды:
    TELEGRAM_BOT_TOKEN Токен бота (альтернатива файловому)
    TELEGRAM_OWNER_ID Идентификатор чата владельца
    OLLAMA_MODEL Перезаписать стандартную модель
    OLLAMA_URL Перезаписать URL-адрес Олламы
    BACH_CONTROL_PORT Порт API управления (по умолчанию: 8081)
    BACH_HOST Хост по умолчанию для лотка/графического интерфейса (например, macstudvonlukas)
    BACH_NO_BROWSER =1: Не открывать браузер автоматически (удаленный графический интерфейс).
    ANTHROPIC_API_KEY для бэкэнда claude-api
    OPENAI_API_KEY Для серверной части openai


ПРИМЕЧАНИЯ
--------
  Поточность: API управления использует ThreadingHTTPServer (начиная с версии 1.1.1).
  ChatRuntime не имеет блокировок общего состояния (сессии, current_tool,
  tool_round,last_tools). Не критично для однопользовательской работы, но при
  одновременные запросы API во время работы инструмента
  Возникают условия гонки. Обходной путь: одновременно только один чат.


МИГРАЦИЯ Claude BRIDGE
----------------------------
  Служба чата BACH функционально заменяет Claude Bridge:
  - Bridge_daemon.py -> telegram_chat.py (бот Telegram)
  - Bridge_tray.py ->chat_tray.py (системный трей)
  - config.json -> ~/.config/bach/telegram_chat.json

  Преимущества перед Клодом Бриджем:
  - 5 бэкэндов вместо одного Claude CLI
  - Интеграция BACH (память, задачи, инжекторы)
  - API управления + веб-панель
  - Голос (Шепот) + OCR (Тессеракт)
  - Межплатформенный лоток
  - Чистая трехуровневая архитектура


СМОТРИ ТАКЖЕ
----------
  help claude_bridge Старый мост Клода (Наследие)
  справка по разъему Система разъемов
  помощь в общении с llm Методы общения с LLM
