Уведомления Telegram

ThreadCells может отправлять ненавязчивые уведомления жизненного цикла одному адресату в Telegram. Это общая для всей установки возможность ThreadCells: она не принадлежит текущему выбранному проекту, не читает его конфигурацию и не зависит от него.

Click to expand

Настройка назначения

1. Создайте или выберите Telegram-бота через официальный механизм управления ботами Telegram.
2. Получите ID чата назначения. Для темы форума также получите его положительный ID ветви сообщений.
3. Откройте Settings → Telegram и разблокируйте изменения оператора.
4. Введите токен бота, ID чата и необязательный ID темы/ветви.
5. Сохраните, пока уведомления отключены.
6. Используйте Check connection для проверки учётных данных бота, затем Send test notification для проверки назначения.
7. Включите уведомления и сохраните снова.

Проверки запускаются только явно: открытие Settings никогда не обращается к Telegram. Отключение уведомлений сохраняет настроенные адресат и токен, чтобы их можно было включить позднее. Clear bot token — отдельное подтверждаемое действие оператора: оно удаляет учётные данные, отключает уведомления и сохраняет несекретные поля назначения.

Обращение с секретами

Web UI отправляет новый токен только при защищённом обновлении и затем очищает его поле пароля. API чтения сообщают только Configured, Not configured или Invalid; они никогда не возвращают токен. ThreadCells не помещает токен в хранилище браузера, запросы терминала, метаданные сессии или агента, обычные журналы или строку настроек SQLite.

Сервер хранит токен в:

$CAO_HOME_DIR/secrets/telegram-bot-token

Родительский каталог ограничен runtime account, а файл токена использует режим 0600. Замена использует атомарное переименование файловой системы; очистка удаляет учётные данные без перехода по ссылке и синхронизирует каталог секретов. CAO_HOME_DIR — корень приватного изменяемого состояния установки, а не путь публичного репозитория.

Считайте этот файл учётными данными. Не копируйте его в исходный контроль версий, обычные пакеты поддержки, экспорт базы данных, историю оболочки или снимки экрана. При подозрении на раскрытие смените его через Telegram.

Политика уведомлений

Политика первого релиза отправляет не более одной попытки для каждого сохранённого события рабочего процесса верхнего уровня:

• успешное завершение верхнего уровня;
• ворота верхнего уровня, требующие внимания owner;
• неожиданная ошибка терминала верхнего уровня, пока его рабочий процесс открыт.

ThreadCells не уведомляет о завершении дочерних агентов, делегировании, опросе, обновлениях прогресса, внутренних циклах повторов или каждом ходе модели/инструмента. Сохранённые ключи событий не позволяют повторному наблюдению или перезапуску дублировать уже заявленную доставку.

Сообщения содержат только краткий безопасный контекст: идентичность ThreadCells, сессию, отображаемое имя проекта при наличии, состояние жизненного цикла, фиксированную сводку и отметку времени UTC. Они не содержат запросы, вывод модели, дампы файловой системы, тела исключений, секреты оператора или токен бота.

Поведение при сбое

Доставка Telegram не блокирует работу агентов. Тайм-аут, отклонённые учётные данные или недоступный сервис Telegram записывают безопасный код результата, но не могут завершить с ошибкой или повторно открыть рабочий процесс. Доставка ограничена одной попыткой; ThreadCells не повторяет бесконечно и не воспроизводит исторические события после включения уведомлений.

Check connection проверяет токен бота через Telegram. Send test notification также проверяет маршрутизацию настроенного чата/темы. Успешная проверка соединения не доказывает, что бот может писать в выбранное назначение, поэтому при настройке нового назначения используйте оба действия.

Резервное копирование и восстановление

Несекретные состояние включения/назначения и журнал доставки находятся в базе данных ThreadCells. Токен бота хранится отдельно. Если уведомления должны пережить аварийное восстановление, сохраняйте токен как отдельные зашифрованные учётные данные с сохранением владельца и режима; не добавляйте его в обычный незашифрованный архив базы данных.

После восстановления проверьте путь к секрету и разрешения, сначала оставьте уведомления отключёнными, выполните обе явные проверки, затем включите доставку. Восстановление базы данных без токена безопасно сообщает Not configured.

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

• Не настроено: перед включением укажите и действительный токен бота, и ID чата.
• Недопустимое хранилище токена: убедитесь, что токен является обычным файлом, не символьной ссылкой, принадлежит runtime account и не имеет разрешений для группы/остальных.
• Соединение не удалось: проверьте исходящие HTTPS/DNS и смените или замените отклонённый токен бота; безопасные ошибки UI намеренно не раскрывают детали ответа Telegram.
• Соединение работает, но тест не проходит: убедитесь, что бот состоит в назначении и может там писать; проверьте ID чата и необязательной темы.
• Нет сообщения о жизненном цикле: убедитесь, что включено Enabled, и помните, что уведомляются только завершение верхнего уровня, внимание owner и неожиданная ошибка верхнего уровня. События, произошедшие во время отключения, не воспроизводятся.