168 lines
5.3 KiB
Markdown
168 lines
5.3 KiB
Markdown
# 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.
|