Telegram-боты — Руководство пользователя

Arc OS использует двухуровневую архитектуру Telegram-ботов: один Master Bot управляет всеми проектами, а каждый проект получает собственного Child Bot с AI-воркерами.

Обзор архитектуры

Система построена на двух уровнях:

Master Bot («Батя») — оркестратор, без AI. Управляет жизненным циклом всех проектов: создание, удаление, мониторинг здоровья, деплой, аварийная остановка.
Child Bot — один на проект. Прокси между Telegram и Claude CLI. Содержит AI-воркеров (Consultant, Developer, кастомные), обрабатывает сообщения, сохраняет контекст диалога.

Как это работает

Telegram-канал:
  Пользователь → Telegram → Child Bot → Claude CLI → Ответ → Telegram

CRM Dashboard:
  Пользователь → CRM → crm_inbox.jsonl → Child Bot (поллинг 500 мс) → Claude CLI → Ответ → Telegram + CRM

Child Bot постоянно поллит файл crm_inbox.jsonl каждые 500 мс, поэтому сообщения из CRM Dashboard обрабатываются почти мгновенно.

Команды Master Bot

Команда	Описание
`/start`	Показать список доступных команд
`/status`	Статус всех проектов: активные потоки, uptime, использование ресурсов
`/list`	Список всех child-ботов с индикаторами здоровья (🟢/🔴)
`/health`	Матрица здоровья: состояние Bot, Bridge, tmux-сессии для каждого проекта
`/deploy <name\|all>`	Git pull + рестарт для конкретного проекта или всех сразу
`/new_project <name>`	Запуск онбординга нового проекта (создание child bot, tmux, конфигурации)
`/remove_project <name>`	Удаление проекта с подтверждением (inline-кнопка «Да, удалить»)
`/emergency_stop`	3-уровневая каскадная остановка: SIGINT → `/exit` → SIGKILL. Останавливает всё.
`/watchdog`	Мониторинг child-ботов: автоматический рестарт, если бот не отвечает
`/cancel`	Отменить текущую активную операцию (деплой, онбординг и т. д.)

Команды Child Bot

Основные префиксы

Префикс	Воркер	Модель	Доступ
`/c <сообщение>`	Consultant	Sonnet	Read-only, стратегический советник
`/d <сообщение>`	Developer	Opus	Полный доступ к файлам и терминалу
`/w:<worker_id> <сообщение>`	Кастомный воркер	Зависит от конфигурации	Определяется в `workers_registry.json`
(без префикса)	Активный воркер	—	По умолчанию — Consultant

Пример:

/c Проанализируй архитектуру модуля авторизации
/d Исправь баг в форме входа
/w:sentinel Проведи security-аудит последних изменений

Информационные команды

Команда	Описание
`/ping`	Проверка здоровья бота + uptime
`/thread`	Размер текущей истории диалога (количество сообщений)
`/quality`	Метрики качества: количество вызовов, фидбек (👍/👎), средняя длительность ответа
`/learnings`	Список накопленных правил коррекции (learnings)
`/specs`	Список спецификаций со статусами (draft / review / approved)
`/approve <id>`	Одобрить спецификацию по ID
`/reject <id> [reason]`	Отклонить спецификацию с опциональной причиной

Inline-кнопки

Под ответом воркера

После каждого ответа AI-воркера появляются три ряда кнопок:

Ряд 1 — Управление процессом Claude:

Кнопка	Действие
🛑 STOP	Убивает процесс Claude (SIGKILL). Используй, если ответ пошёл не туда или завис.
⏸️ PAUSE	Приостанавливает процесс Claude (SIGSTOP). Удобно, чтобы дождаться чего-то перед продолжением.
▶️ RESUME	Возобновляет приостановленный процесс (SIGCONT).

Ряд 2 — Контекст и фидбек:

Кнопка	Действие
💡 BTW	Режим сбора дополнительного контекста. Следующие сообщения попадают в очередь и будут инжектированы в следующий GSD-промпт.
🛠️ Fix It	Повторный запуск задачи с автоматическими исправлениями на основе предыдущего ответа.
👍	Положительный фидбек — фиксируется в метриках качества.
👎	Отрицательный фидбек — автоматически создаёт learning rule, которое будет инжектироваться в каждый следующий промпт воркера.

Ряд 3 — Навигация:

Кнопка	Действие
🏷️ Skills	Показать список скиллов, использованных для ответа.
📊 View Log	Открыть CRM-лог этой сессии.

Кнопки Master Bot

На карточке каждого проекта в Master Bot доступны кнопки:

Restart — перезапуск child bot
Delete — удаление проекта (с подтверждением)
Manifest — показать конфигурацию проекта
Skills — список скиллов проекта
Quality — метрики качества
CRM — ссылка на CRM Dashboard

Контекст и память

История диалога хранится per-worker (максимум 50 записей). У каждого воркера отдельная память.
Reply на конкретное сообщение → его текст инжектируется как CONTEXT в промпт Claude.
Context Router автоматически подбирает top-5 скиллов, релевантных твоему сообщению.
Learnings из 👎 → автоматически инжектируются в каждый следующий GSD-промпт, чтобы воркер не повторял ошибки.

Переключение воркеров

Каждый Child Bot поддерживает несколько воркеров. Активный воркер хранится в файле active_role.json.

/c — переключает на Consultant (Sonnet, read-only анализ)
/d — переключает на Developer (Opus, полный доступ)
/w:<worker_id> — переключает на кастомного воркера по его ID

Сообщение без префикса идёт к текущему активному воркеру. Если ты отправил /d Исправь баг, Developer становится активным — следующие сообщения без префикса тоже пойдут к Developer.

Связь с CRM

Telegram и CRM Dashboard — это два канала к одному и тому же воркеру:

CRM Dashboard записывает сообщения в файл crm_inbox.jsonl
Child Bot поллит этот файл каждые 500 мс и обрабатывает новые сообщения
Ответы появляются и в Telegram, и в CRM одновременно
Вложения (изображения, PDF) поддерживаются через CRM Dashboard

Это означает, что можно начать диалог в Telegram, продолжить в CRM, и наоборот — контекст сохраняется.

Устранение неполадок

Проблема	Решение
Бот не отвечает	Проверь `/health` в Master Bot. Если child bot 🔴 — нажми Restart или используй `/deploy <name>`. Проверь `/watchdog` для автоматического мониторинга.
Долгое время ответа	Переключись на Consultant (`/c`) — он использует Sonnet, который быстрее Opus. Для простых вопросов этого достаточно.
Сообщение обрезается	Telegram имеет лимит 4096 символов на сообщение. Бот автоматически делит длинные ответы на части: `[1/3]`, `[2/3]`, `[3/3]`.
Бот отвечает медленно через CRM	Убедись, что tmux-сессия child bot активна: `/health` должен показывать tmux 🟢.
👎 не создаёт learning	Убедись, что нажал 👎 именно под ответом воркера, а не под системным сообщением.