Bernd (Hermes Agent)
192 lines
5.4 KiB
Markdown
192 lines
5.4 KiB
Markdown
# Hermes Rocket.Chat Plugin — Community Release
|
||
|
||
> **Nützliches Add-on für [Hermes Agent](https://hermes-agent.nousresearch.com/)**
|
||
> Verbindet Hermes Agent mit einem selbst-gehosteten Rocket.Chat-Server.
|
||
|
||
---
|
||
|
||
## Was ist das?
|
||
|
||
Dieses Plugin verwandelt Hermes Agent in einen **nativen Rocket.Chat-Benutzer** — mit Echtzeit-Nachrichten, Präsenz-Status und interaktiven Buttons.
|
||
|
||
Statt über ein separates Gateway-Binary zu kommunizieren, spricht Hermes Agent direkt mit Rocket.Chat:
|
||
- **Eingehend**: WebSocket/DDP für sofortige Nachrichten
|
||
- **Ausgehend**: REST-API für Antworten, Buttons, Dateien
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
| Feature | Beschreibung |
|
||
|---------|-------------|
|
||
| 🚀 Echtzeit-Streaming | DDP/WebSocket für instant eingehende Nachrichten |
|
||
| 🟢 Präsenz | Grüner Online-Status im Rocket.Chat |
|
||
| ✍️ Markdown | Fett, kursiv, `Code`, Blöcke, Links |
|
||
| 🔘 Interaktive Buttons | Ja/Nein, Bestätigen/Abbrechen, Mehrfachauswahl |
|
||
| 📢 Räume | Kanäle, private Gruppen, Direktnachrichten |
|
||
| 🔒 Allowlist | Nur erlaubte Benutzer dürfen den Bot nutzen |
|
||
| 📦 Zero-Dependency | Nutzt ausschließlich Python-Standardbibliothek |
|
||
|
||
---
|
||
|
||
## Schnellstart
|
||
|
||
### 1. Voraussetzungen
|
||
|
||
- Hermes Agent installiert ([Setup-Guide](https://hermes-agent.nousresearch.com/docs))
|
||
- Laufender Rocket.Chat-Server (v5+ empfohlen)
|
||
- Bot-Benutzer auf Rocket.Chat mit Login-Daten
|
||
|
||
### 2. Plugin herunterladen
|
||
|
||
```bash
|
||
git clone https://gitea.thomander.de/andreas/Hermes_rocket.chat_Plugin.git
|
||
cd Hermes_rocket.chat_Plugin
|
||
```
|
||
|
||
### 3. Interaktive Installation (empfohlen)
|
||
|
||
```bash
|
||
./install.sh
|
||
```
|
||
|
||
Das Script führt dich durch alle Schritte, fragt deine Zugangsdaten ab, testet die Verbindung und schreibt die Konfiguration. Fertig in unter 2 Minuten.
|
||
|
||
**Nicht sicher?** Probiere erst die Simulation:
|
||
|
||
```bash
|
||
./install.sh --dry-run
|
||
```
|
||
|
||
Zeigt alles an, ändert nichts.
|
||
|
||
**Hilfe anzeigen:**
|
||
|
||
```bash
|
||
./install.sh --help
|
||
```
|
||
|
||
### 4. Manuelles Setup (für Experten)
|
||
|
||
Wer lieber per Hand konfigurieren möchte:
|
||
|
||
```bash
|
||
mkdir -p ~/.hermes/hermes-agent/plugins/platforms/rocketchat
|
||
cp plugin.yaml __init__.py adapter.py \
|
||
~/.hermes/hermes-agent/plugins/platforms/rocketchat/
|
||
```
|
||
|
||
Dann `~/.hermes/.env` oder `config.yaml` bearbeiten.
|
||
|
||
### 5. Konfigurieren
|
||
|
||
Falls du manuell konfigurierst, hier die zwei Varianten:
|
||
|
||
**Variante A — Umgebungsvariablen:**
|
||
export ROCKETCHAT_BASE_URL="https://rocketchat.example.com"
|
||
export ROCKETCHAT_USER="bernd"
|
||
export ROCKETCHAT_PASSWORD="dein-passwort"
|
||
export ROCKETCHAT_ROOM_ID="J3jvMyrKTMzKvKHSh" # optional
|
||
export ROCKETCHAT_ALLOWED_USERS="andreas,max" # optional
|
||
export ROCKETCHAT_ALLOW_ALL_USERS="false" # default
|
||
```
|
||
|
||
**Variante B — `config.yaml`:**
|
||
|
||
```yaml
|
||
plugins:
|
||
platforms:
|
||
rocketchat:
|
||
enabled: true
|
||
base_url: "https://rocketchat.example.com"
|
||
user: "bernd"
|
||
password: "dein-passwort"
|
||
room_id: "J3jvMyrKTMzKvKHSh"
|
||
allowed_users: ["andreas", "max"]
|
||
allow_all_users: false
|
||
```
|
||
|
||
### 4. Starten
|
||
|
||
```bash
|
||
hermes gateway start
|
||
```
|
||
|
||
Hermes Agent verbindet sich automatisch mit Rocket.Chat und erscheint als Online-Benutzer.
|
||
|
||
---
|
||
|
||
## Architektur
|
||
|
||
```
|
||
┌─────────────┐ DDP/WebSocket ┌─────────────────┐
|
||
│ Hermes Agent│ ◄────────────────────► │ Rocket.Chat │
|
||
│ (Plugin) │ │ Server │
|
||
│ │ REST API │ │
|
||
│ │ ─────────────────────► │ (v5+) │
|
||
└─────────────┘ └─────────────────┘
|
||
```
|
||
|
||
- **Adapter.py** (~20 k LOC): DDP-Client, Session-Handling, Nachrichten-Parsing, Button-Rendering
|
||
- **__init__.py**: Plugin-Registrierung, Template-Definitionen für Buttons
|
||
- **plugin.yaml**: Metadaten, Env-Vars, Dependency-Check
|
||
|
||
---
|
||
|
||
## Button-Templates
|
||
|
||
Das Plugin bringt vordefinierte Interaktionen mit — kein YAML, keine Extra-Config:
|
||
|
||
| Template | Nutzung |
|
||
|----------|---------|
|
||
| `yes_no` | ✅ Ja / ❌ Nein |
|
||
| `confirm_cancel` | ✅ Bestätigen / 🚫 Abbrechen |
|
||
| `ok` | 👍 OK |
|
||
| `multi_choice_3` | 1. Links / 2. Rechts / 3. Zwei Runden |
|
||
|
||
Custom-Buttons werden aus reinen Label-Strings generiert (Rocket.Chat schneidet nach ~11–12 Zeichen ab — daher kurze Labels mit Emoji).
|
||
|
||
---
|
||
|
||
## Aktueller Status
|
||
|
||
- **Version**: 1.0.0
|
||
- **Stabilität**: Produktiv im Einsatz (seit Mai 2026)
|
||
- **Getestet mit**: Rocket.Chat v5.x, Hermes Agent Gateway
|
||
- **Lizenz**: [Unlicense](LICENSE) — Public Domain
|
||
|
||
---
|
||
|
||
## Roadmap / Offen
|
||
|
||
- [ ] OAuth / Token-Auth neben Passwort-Login
|
||
- [ ] Threading-Unterstützung für Kanäle
|
||
- [ ] Datei-Upload (Bilder, Dokumente)
|
||
- [ ] Slash-Command-Integration auf Rocket.Chat-Seite
|
||
- [ ] Mehrsprachige Button-Templates
|
||
|
||
---
|
||
|
||
## Mitmachen
|
||
|
||
Da das Plugin reines Python und nur Standardbibliothek nutzt, ist der Einstieg niedrig:
|
||
|
||
1. Repo clonen
|
||
2. `adapter.py` bearbeiten
|
||
3. Testen mit `hermes gateway start --debug`
|
||
4. Pull Request oder Patch schicken
|
||
|
||
Kein Build-Step, keine Node-Dependencies, kein Docker nötig.
|
||
|
||
---
|
||
|
||
## Links
|
||
|
||
- **Hermes Agent**: https://hermes-agent.nousresearch.com/
|
||
- **Rocket.Chat**: https://www.rocket.chat/
|
||
- **Dieses Repo**: `https://gitea.thomander.de/andreas/Hermes_rocket.chat_Plugin`
|
||
|
||
---
|
||
|
||
> *Erstellt von der Hermes Agent Community — für die Rocket.Chat Community.*
|