222 lines
7.7 KiB
Markdown
222 lines
7.7 KiB
Markdown
# DEV TASK: Telegram-уведомления из Orchestrator
|
||
|
||
**Статус:** Ready for dev
|
||
**Проект:** multi-agent
|
||
**Приоритет:** High
|
||
|
||
---
|
||
|
||
## Контекст
|
||
|
||
Orchestrator ведёт полный журнал всех этапов (events, tasks, agent_runs), но **не отправляет уведомления** в Telegram. Сейчас `notifications.py` только пишет в stdout (docker logs).
|
||
|
||
Слава хочет получать **детерминированные уведомления** в Telegram — без моделей, без галлюцинаций. Чистый скрипт: событие → HTTP POST → Telegram Bot API.
|
||
|
||
---
|
||
|
||
## Цель
|
||
|
||
Добавить отправку уведомлений в Telegram при каждом значимом событии конвейера.
|
||
|
||
---
|
||
|
||
## Что должно приходить в Telegram
|
||
|
||
| Событие | Формат сообщения |
|
||
|---------|-----------------|
|
||
| Stage change | `🔄 ET-007: analysis → architecture (запущен architect)` |
|
||
| Agent started | `🚀 ET-007: analyst запущен (run_id=26)` |
|
||
| Agent finished OK | `✅ ET-007: analyst завершил (8 мин, exit_code=0)` |
|
||
| Agent failed | `❌ ET-007: developer упал (exit_code=1)` |
|
||
| Agent timeout | `⏰ ET-007: developer убит по таймауту (30 мин)` |
|
||
| QG passed | `✅ ET-007: QG check_ci_green — passed` |
|
||
| QG failed | `⚠️ ET-007: QG check_ci_green — failed: CI state: pending` |
|
||
| Analyst requests approve | `📋 ET-007: BRD/ТЗ/AC готовы. Жду :approved: в Plane` |
|
||
| Task done | `🎉 ET-007: задача завершена! PR merged.` |
|
||
| Error | `🔴 ET-007: ERROR — Failed to launch agent` |
|
||
|
||
---
|
||
|
||
## Реализация
|
||
|
||
### 1. Добавить переменные в `.env`
|
||
|
||
**Файл:** `/home/slin/repos/orchestrator/.env`
|
||
|
||
```
|
||
ORCH_TELEGRAM_BOT_TOKEN=8298776127:AAGGbOYY7arq_WLD6vo8kJ8B1Ns7lTf6NT8
|
||
ORCH_TELEGRAM_CHAT_ID=126472752
|
||
```
|
||
|
||
### 2. Добавить в config.py
|
||
|
||
**Файл:** `src/config.py`
|
||
|
||
```python
|
||
# Telegram notifications
|
||
telegram_bot_token: str = ""
|
||
telegram_chat_id: str = ""
|
||
```
|
||
|
||
### 3. Обновить notifications.py
|
||
|
||
**Файл:** `src/notifications.py`
|
||
|
||
Добавить функцию `send_telegram(text: str)` и вызывать её из всех `notify_*`:
|
||
|
||
```python
|
||
import httpx
|
||
from .config import settings
|
||
|
||
TELEGRAM_URL = f"https://api.telegram.org/bot{settings.telegram_bot_token}/sendMessage"
|
||
|
||
def send_telegram(text: str):
|
||
"""Send notification to Telegram. Fire-and-forget, never raises."""
|
||
if not settings.telegram_bot_token or not settings.telegram_chat_id:
|
||
return
|
||
try:
|
||
httpx.post(
|
||
TELEGRAM_URL,
|
||
json={
|
||
"chat_id": settings.telegram_chat_id,
|
||
"text": text,
|
||
"parse_mode": "HTML",
|
||
"disable_notification": False,
|
||
},
|
||
timeout=5,
|
||
)
|
||
except Exception:
|
||
pass # Never crash orchestrator due to notification failure
|
||
|
||
|
||
def notify_stage_change(task_id: int, old_stage: str, new_stage: str, agent: str = None):
|
||
"""Log and notify stage transition."""
|
||
# Get work_item_id from DB
|
||
work_item_id = _get_work_item_id(task_id)
|
||
msg = f"🔄 {work_item_id}: {old_stage} → {new_stage}"
|
||
if agent:
|
||
msg += f" (запущен {agent})"
|
||
logger.info(msg)
|
||
send_telegram(msg)
|
||
|
||
|
||
def notify_agent_started(run_id: int, agent: str, task_id: int):
|
||
"""Notify agent launch."""
|
||
work_item_id = _get_work_item_id(task_id)
|
||
msg = f"🚀 {work_item_id}: {agent} запущен (run_id={run_id})"
|
||
logger.info(msg)
|
||
send_telegram(msg)
|
||
|
||
|
||
def notify_agent_finished(run_id: int, agent: str, exit_code: int, task_id: int = None, duration_s: int = None):
|
||
"""Notify agent completion."""
|
||
work_item_id = _get_work_item_id(task_id) if task_id else "?"
|
||
if exit_code == 0:
|
||
dur = f" ({duration_s // 60} мин)" if duration_s else ""
|
||
msg = f"✅ {work_item_id}: {agent} завершил{dur}"
|
||
elif exit_code == -9:
|
||
msg = f"⏰ {work_item_id}: {agent} убит по таймауту (30 мин)"
|
||
else:
|
||
msg = f"❌ {work_item_id}: {agent} упал (exit_code={exit_code})"
|
||
logger.info(msg)
|
||
send_telegram(msg)
|
||
|
||
|
||
def notify_qg_failure(task_id: int, stage: str, check: str, reason: str):
|
||
"""Notify QG failure."""
|
||
work_item_id = _get_work_item_id(task_id)
|
||
msg = f"⚠️ {work_item_id}: QG {check} — failed: {reason}"
|
||
logger.warning(msg)
|
||
send_telegram(msg)
|
||
|
||
|
||
def notify_error(task_id: int, error: str):
|
||
"""Notify error."""
|
||
work_item_id = _get_work_item_id(task_id) if task_id else "system"
|
||
msg = f"🔴 {work_item_id}: ERROR — {error}"
|
||
logger.error(msg)
|
||
send_telegram(msg)
|
||
|
||
|
||
def notify_approve_requested(task_id: int):
|
||
"""Notify that analyst requests :approved:."""
|
||
work_item_id = _get_work_item_id(task_id)
|
||
msg = f"📋 {work_item_id}: BRD/ТЗ/AC готовы. Жду :approved: в Plane"
|
||
logger.info(msg)
|
||
send_telegram(msg)
|
||
|
||
|
||
def notify_done(task_id: int):
|
||
"""Notify task completion."""
|
||
work_item_id = _get_work_item_id(task_id)
|
||
msg = f"🎉 {work_item_id}: задача завершена!"
|
||
logger.info(msg)
|
||
send_telegram(msg)
|
||
|
||
|
||
def _get_work_item_id(task_id: int) -> str:
|
||
"""Get work_item_id from DB by task_id."""
|
||
try:
|
||
from .db import get_db
|
||
conn = get_db()
|
||
row = conn.execute("SELECT work_item_id FROM tasks WHERE id=?", (task_id,)).fetchone()
|
||
conn.close()
|
||
return row["work_item_id"] if row and row["work_item_id"] else f"task-{task_id}"
|
||
except Exception:
|
||
return f"task-{task_id}"
|
||
```
|
||
|
||
### 4. Обновить вызовы в launcher.py
|
||
|
||
**Файл:** `src/agents/launcher.py`
|
||
|
||
- В `launch()` после записи в БД: `notify_agent_started(run_id, agent, task_id)`
|
||
- В `_monitor_agent()` после обновления exit_code: `notify_agent_finished(run_id, agent, exit_code, task_id, duration_s)`
|
||
- В `_try_advance_stage()` при запросе approve: `notify_approve_requested(task_id)`
|
||
|
||
### 5. Обновить вызовы в plane.py и gitea.py
|
||
|
||
Убедиться, что все `notify_stage_change()`, `notify_qg_failure()`, `notify_error()` передают `task_id` (уже передают).
|
||
|
||
---
|
||
|
||
## Файлы для изменения
|
||
|
||
| Файл | Изменения |
|
||
|------|-----------|
|
||
| `.env` | Добавить `ORCH_TELEGRAM_BOT_TOKEN`, `ORCH_TELEGRAM_CHAT_ID` |
|
||
| `src/config.py` | Добавить `telegram_bot_token`, `telegram_chat_id` |
|
||
| `src/notifications.py` | Полная переработка: `send_telegram()` + обновлённые `notify_*` |
|
||
| `src/agents/launcher.py` | Вызовы `notify_agent_started`, `notify_agent_finished`, `notify_approve_requested` |
|
||
|
||
---
|
||
|
||
## Ограничения
|
||
|
||
- **Никаких моделей** — только детерминированный код
|
||
- **Fire-and-forget** — если Telegram недоступен, orchestrator НЕ падает
|
||
- **parse_mode: HTML** — для форматирования (bold, code)
|
||
- НЕ менять порт 8500
|
||
- НЕ ломать существующий цикл
|
||
|
||
---
|
||
|
||
## Команды проверки
|
||
|
||
```bash
|
||
# 1. Тест отправки
|
||
docker exec orchestrator python -c "
|
||
from src.notifications import send_telegram
|
||
send_telegram('🧪 Тест уведомлений из Orchestrator')
|
||
print('sent')
|
||
"
|
||
|
||
# 2. Health
|
||
curl -s http://localhost:8500/health
|
||
```
|
||
|
||
---
|
||
|
||
## Результат
|
||
|
||
После деплоя Слава получает в Telegram **каждое** значимое событие конвейера в реальном времени. Без моделей, без галлюцинаций — чистый детерминированный скрипт. |