docs(spec): add network mode design for multi-agent LAN usage
This commit is contained in:
chahinebrini
parent
22f3c7dda6
commit
5531bfa282
167
docs/specs/2026-06-25-agenthub-network-mode-design.md
Normal file
167
docs/specs/2026-06-25-agenthub-network-mode-design.md
Normal file
@ -0,0 +1,167 @@
|
||||
# AgentHub Network Mode — Design Spec
|
||||
|
||||
**Datum:** 2026-06-25
|
||||
**Status:** Entwurf – zur Freigabe
|
||||
**Ziel:** AgentHub für parallele Agenten-Sessions auf mehreren Geräten im gleichen lokalen Netzwerk verwendbar machen (z. B. Kimi auf Mac + Kimi auf Windows).
|
||||
|
||||
---
|
||||
|
||||
## 1. Zusammenfassung
|
||||
|
||||
AgentHub bleibt ein dateibasiertes Tool. Ein Gerät im Netzwerk (hier: der Mac) hostet das Projektverzeichnis inklusive `.agenthub/` und bietet einen optionalen Fastify-Server an. Andere Geräte (z. B. Windows) nutzen die CLI im Remote-Modus und sprechen den Server über HTTP an.
|
||||
|
||||
Lokaler Dateizugriff bleibt der Default. Remote-Modus ist opt-in über `--server <url>` oder die Umgebungsvariable `AGENTHUB_SERVER`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Architektur
|
||||
|
||||
```text
|
||||
┌─────────────────────┐ HTTP ┌─────────────────────┐
|
||||
│ Kimi auf Windows │ ◄──────────────────► │ AgentHub Server │
|
||||
│ agenthub --server │ │ auf Mac (0.0.0.0) │
|
||||
│ http://mac:3377 │ │ │
|
||||
└─────────────────────┘ │ liest/schreibt │
|
||||
│ .agenthub/ auf Mac │
|
||||
│ (Dateien = SSOT) │
|
||||
└─────────────────────┘
|
||||
```
|
||||
|
||||
- **Single Source of Truth:** Die Markdown-Dateien auf dem Mac.
|
||||
- **Server:** Führt die gleichen Lese-/Schreiboperationen aus wie die lokale CLI und aktualisiert den SQLite-Index.
|
||||
- **Client (Remote-Modus):** Dünne HTTP-Schicht; keine eigene Geschäftslogik.
|
||||
|
||||
---
|
||||
|
||||
## 3. CLI-Änderungen
|
||||
|
||||
### Globaler `--server`-Flag
|
||||
|
||||
```bash
|
||||
agenthub --server http://192.168.1.42:3377 task list
|
||||
agenthub --server http://mac.local:3377 status --update
|
||||
```
|
||||
|
||||
Alternativ per Env-Variable:
|
||||
|
||||
```bash
|
||||
export AGENTHUB_SERVER=http://192.168.1.42:3377
|
||||
agenthub task create --title "Foo"
|
||||
```
|
||||
|
||||
### Ausgenommene Befehle
|
||||
|
||||
- `agenthub init` bleibt **immer lokal**. Das Projekt muss auf dem Host-Rechner initialisiert werden, bevor andere Geräte remote darauf zugreifen.
|
||||
|
||||
### Fehlerbehandlung
|
||||
|
||||
- Server nicht erreichbar → `"AgentHub server at http://... is not reachable. Is 'agenthub server start --host 0.0.0.0' running?"`
|
||||
- HTTP-Fehler → Statuscode + Server-Antwort ausgeben.
|
||||
- `--server` fehlt auf Windows → Hinweis, dass entweder `--server` gesetzt oder ein SMB-Share genutzt werden muss.
|
||||
|
||||
---
|
||||
|
||||
## 4. Server-Änderungen
|
||||
|
||||
### Start-Kommando
|
||||
|
||||
```bash
|
||||
agenthub server start --host 0.0.0.0 --port 3377
|
||||
```
|
||||
|
||||
- `--host` ist neu; Default: `127.0.0.1`.
|
||||
- `--port` bleibt wie gehabt; Default: `3377`.
|
||||
- Für LAN-Nutzung muss `--host 0.0.0.0` gesetzt werden.
|
||||
|
||||
### Endpoints
|
||||
|
||||
| Methode | Endpoint | Zweck |
|
||||
|---------|----------|-------|
|
||||
| `GET` | `/status` | Aktuellen Status zurückgeben |
|
||||
| `POST` | `/status/update` | Status neu generieren |
|
||||
| `GET` | `/tasks` | Tasks auflisten |
|
||||
| `POST` | `/tasks` | Task erstellen |
|
||||
| `GET` | `/tasks/:id` | Task anzeigen |
|
||||
| `PATCH` | `/tasks/:id` | Task aktualisieren (claim, done, status) |
|
||||
| `GET` | `/handoffs` | Handoffs auflisten |
|
||||
| `POST` | `/handoffs` | Handoff erstellen |
|
||||
| `GET` | `/handoffs/:id` | Handoff anzeigen |
|
||||
| `GET` | `/decisions` | Decisions auflisten |
|
||||
| `POST` | `/decisions` | Decision erstellen |
|
||||
| `GET` | `/memory` | Memory-Einträge auflisten |
|
||||
| `POST` | `/memory` | Memory-Eintrag erstellen |
|
||||
| `GET` | `/memory/search?q=...` | Volltextsuche |
|
||||
| `POST` | `/delegate` | Delegation vorschlagen/auto |
|
||||
|
||||
Alle Endpoints verwenden die bestehenden Core-Funktionen (`taskCreate`, `taskList`, etc.).
|
||||
|
||||
### Auth (MVP)
|
||||
|
||||
- Keine Authentifizierung im MVP.
|
||||
- Header-Struktur wird so gebaut, dass später `Authorization: Bearer <token>` einfach ergänzt werden kann.
|
||||
|
||||
---
|
||||
|
||||
## 5. Client-Modus
|
||||
|
||||
Jeder CLI-Befehl entscheidet anhand von `--server` / `AGENTHUB_SERVER`, ob er lokal arbeitet oder den `RemoteClient` nutzt.
|
||||
|
||||
Beispiel `task create`:
|
||||
|
||||
```typescript
|
||||
if (serverUrl) {
|
||||
await remoteClient.createTask(serverUrl, options);
|
||||
} else {
|
||||
await localTaskCreate(cwd, options);
|
||||
}
|
||||
```
|
||||
|
||||
Der `RemoteClient` ist eine kleine Wrapper-Klasse um `fetch`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Tests
|
||||
|
||||
1. **Server-Routen-Tests:** Fastify-App direkt testen, ohne Port zu öffnen.
|
||||
2. **RemoteClient-Tests:** Client gegen einen gemockten Server testen.
|
||||
3. **E2E-Test:**
|
||||
- Temporäres Projekt auf dem Mac initialisieren.
|
||||
- Server starten (`--host 127.0.0.1` reicht für E2E).
|
||||
- CLI mit `--server http://127.0.0.1:<port>` aufrufen.
|
||||
- Prüfen, dass die Datei im Projektverzeichnis landet.
|
||||
|
||||
---
|
||||
|
||||
## 7. Beispiel-Workflow
|
||||
|
||||
**Auf dem Mac:**
|
||||
|
||||
```bash
|
||||
cd ~/my-project
|
||||
agenthub init --project-name my-project
|
||||
agenthub server start --host 0.0.0.0 --port 3377
|
||||
```
|
||||
|
||||
**Auf Windows:**
|
||||
|
||||
```bash
|
||||
$env:AGENTHUB_SERVER="http://192.168.1.42:3377"
|
||||
agenthub task create --title "Implement Windows bypass check" --role implementer
|
||||
agenthub status
|
||||
```
|
||||
|
||||
**Auf dem Mac kann parallel weiter lokal gearbeitet werden:**
|
||||
|
||||
```bash
|
||||
agenthub task list
|
||||
agenthub task done TSK-0001
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Offene Punkte / Folgearbeiten
|
||||
|
||||
1. Auth/Token-Support für unsichere Netzwerke.
|
||||
2. Bonjour/mDNS-Autodiscovery des Servers.
|
||||
3. Konflikterkennung bei gleichzeitigen Schreibzugriffen (z. B. via ETags).
|
||||
4. HTTPS/SSL für Produktivnetzwerke.
|
||||
Loading…
x
Reference in New Issue
Block a user