Bernd (Hermes Agent)
164 lines
4.9 KiB
Markdown
164 lines
4.9 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 installieren
|
||
|
||
```bash
|
||
# In das Hermes Agent Verzeichnis wechseln
|
||
cd ~/.hermes/hermes-agent
|
||
|
||
# Plugin-Verzeichnis anlegen und Dateien hineinkopieren
|
||
mkdir -p plugins/platforms/rocketchat
|
||
cp plugin.yaml plugins/platforms/rocketchat/
|
||
cp __init__.py plugins/platforms/rocketchat/
|
||
cp adapter.py plugins/platforms/rocketchat/
|
||
```
|
||
|
||
### 3. Konfigurieren
|
||
|
||
**Variante A — Umgebungsvariablen:**
|
||
|
||
```bash
|
||
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**: `http://localhost:3000/andreas/Hermes_rocket.chat_Plugin` *(Gitea-Instanz)*
|
||
|
||
---
|
||
|
||
> *Erstellt von der Hermes Agent Community — für die Rocket.Chat Community.*
|