nexo312/trading-system-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trading-system-docs/notes/trading/system-docs/modul-26-telegram-gateway.md

4.9 KiB
Raw Blame History

Modul-26-Telegram-Gateway

Status: FREIGEGEBEN (2026-08-21) Port: 55026 (nur Docker-intern, kein öffentlicher Port) Container: Modul-26-Telegram-Gateway Image: telegram-gateway:0.1.0 Netzwerk: trading-modules

Zweck

Dünner, tool-loser Adapter zwischen Telegram und M17 Hermes-Agent. Ermöglicht die Bedienung von Hermes vom Handy über einen eigenen Telegram-Bot. KEINE Trading-Tools, kein M09/M07/M08/M15-Control-Zugriff. Safety bleibt deterministisch in M17.

Architektur

Telegram Bot API
   │  Polling (getUpdates) — KEIN Webhook, kein öffentlicher Port
   ▼
Modul-26-Telegram-Gateway  (Port 55026 intern)
   │  Auth-Allowlist, Rate-Limit, Audit — NUR HTTP-Calls an M17, KEINE Tools
   ▼
Modul-17-Hermes-Agent  (POST /tasks llm=true)
   │  Tool-Whitelist + Task-Gates (deterministisch, UNVERÄNDERT)
   ▼
LLM (Cloud deepseek-v4-flash:cloud Standard / Local llama3.1:8b explizit)

Sicherheitsmodell

  • Allowlist: Nur explizit erlaubte User-/Chat-IDs (TELEGRAM_ALLOWED_IDS, kommagetrennt). Unbekannte User werden hart abgelehnt (kein Task, Log-Eintrag, Status REJECTED/UNAUTHORIZED).
  • Rate-Limit: Sliding-Window pro User/Chat (Default 10/min). Überschreitung → REJECTED/RATE_LIMITED.
  • Idempotenz: update_id als PK in telegram_message. Bereits verarbeitete Updates werden übersprungen.
  • Secrets: Bot-Token NUR via ENV/Secret (TELEGRAM_BOT_TOKEN), nie im Code. Keine Secrets in DB/Logs/Doku.
  • Prompt-Injection: M17 behandelt externe Eingaben als untrusted data. Tool-Whitelist + Task-Gates hart im Code.
  • Doppelte Barriere: Gateway ist tool-los (nur HTTP-Calls an M17) + M17-Whitelist deterministisch.

Commands

Command M17 task_type Beschreibung
/status — Hermes-Health (synchron)
/research research Markt-/Regime-Analyse
/analytics analytics Portfolio-/Strategie-Analyse
/backtest backtest Backtest starten
/optimize optimization Optimierung starten
/monitoring monitoring Monitoring-Status
/tasks — Letzte Tasks (synchron)
/help — Hilfe
Freitext research Wird als Research-Analyse behandelt

Asynchrone Task-Abwicklung

Lange Tasks (Cloud 5-23s, explizit lokale Analyse bis zu Minuten) laufen asynchron:

  1. Sofortige Bestätigung an denselben Chat ("⏳ task gestartet…").
  2. Task wird in Background-Thread an M17 gesendet (POST /tasks mit llm=true).
  3. Ergebnis wird später an denselben Chat zurückgesendet.

Ergebnis-/Fehlerbehandlung

  • SUCCEEDED: M26 sendet die finale Hermes-Analyse (analysis) + kompakte Tool-Liste. Tool-Fehler (z.B. 404/keine Marktdaten) brechen den Flow nicht ab — die finale Analyse mit Einschränkungen wird trotzdem verständlich an Telegram gesendet, einzelne Tools als [FAILED] gelistet.
  • FAILED: M26 sendet eine klare Fehlermeldung (🔴 *task* fehlgeschlagen (Status: FAILED) + Fehlercode + Details) — NICHT irreführend "✅ abgeschlossen".

Audit

DB-Tabelle telegram_message (Migration 001_telegram_gateway.sql):

  • update_id (PK), chat_id, user_id, username, text, command
  • task_id, run_id, status, error_code, created_at

Nachvollziehbarkeit: update_id → task_id → run_id → LLM-run → Tool-Calls (via M17 hermes_llm_run + hermes_tool_call).

API (Port 55026 intern)

  • GET /health — Liveness
  • GET /health/ready — Readiness (Telegram-Token + Allowlist)
  • GET /messages/recent — Letzte Messages (Audit)
  • GET /messages/{update_id} — Einzelne Message
  • POST /messages/test — Test-Nachricht an konfigurierte Destination

Konfiguration (ENV)

Variable Beschreibung
TELEGRAM_BOT_TOKEN Bot-Token (Secret, NUR ENV)
TELEGRAM_ALLOWED_IDS Kommagetrennte erlaubte User-/Chat-IDs
TELEGRAM_API_BASE Telegram API-Base (Default https://api.telegram.org; für E2E Fake-Server)
M17_BASE_URL M17 Hermes-Agent (Default http://Modul-17-Hermes-Agent:55017)
PG_HOST/PORT/USER/PASSWORD/DB PostgreSQL (Modul-01)

E2E-Tests

tests/e2e_m26.py (20/20 grün, 2026-08-21):

  1. Unknown user reject
  2. /status
  3. /research (+ Ergebnis)
  4. /analytics (+ Ergebnis)
  5. /backtest (+ Ergebnis)
  6. /optimize (+ Ergebnis)
  7. /monitoring (+ Ergebnis)
  8. /tasks
  9. /help
  10. Freitext → research (+ Ergebnis)
  11. Safety: place_order im Prompt → keine Order
  12. Rate-Limit
  13. Audit: update_id → task_id → run_id

Test-Infrastruktur: tests/fake_telegram.py (Fake-Telegram Bot API Server mit Steuer-API für E2E).

Wichtige Hinweise

  • M20 bleibt reserviert für Universe-Scheduler — M26 ist separat.
  • M14 NICHT verändern — M26 nutzt nur das FAIL-SAFE-Muster als Vorlage, koppelt nicht an M14.
  • M17 Safety-Gates unverändert — M26 fügt nur einen dünnen Adapter hinzu.
  • Kein öffentlicher Port — nur expose im Compose.