diff --git a/docs/Instanzmanager-Konzept.md b/docs/Instanzmanager-Konzept.md index 0c490a9..3a7fdf3 100644 --- a/docs/Instanzmanager-Konzept.md +++ b/docs/Instanzmanager-Konzept.md @@ -695,3 +695,143 @@ Hochfahren hinterlegte, stillschweigend ein anderer Test als beabsichtigt — de sagt eine Antwort „diese Instanz läuft bereits", er übernimmt sie, und der Starter wird nie angefasst. Das ist mir dreimal passiert. Der falsche Socket hängt jetzt am falschen Starter: Er antwortet nur, wenn wirklich ein Prozess läuft. + +--- + +## 11 — Übergabe an den Frontend-Agenten + +Stand 2026-09-09. Der C#-Teil des Instanzmanagers ist fertig; was fehlt, ist die +Oberfläche. Dieser Abschnitt ist die Übergabe dafür. + +### 11.1 Der Auftrag, in einem Satz + +**Bringe der Weboberfläche bei, dass es mehrere Instanzen gibt** — Vorhaben **#531**, +alles in `src/ClawdDotNet.Manager.Web/wwwroot/`. + +Heute spricht sie `/api/…` an und bekommt die eine laufende Instanz. Laufen zwei, +antwortet der Manager mit **HTTP 409** und der Bitte, die Kopfzeile `X-Instanz` zu setzen. +Dann ist die Oberfläche unbedienbar — und das ist der einzige Punkt, der den +Mehrinstanzbetrieb im Browser noch aufhält. + +### 11.2 Die Grenze, und sie ist hart + +| Nicht anfassen | Warum | +|---|---| +| **Jede `.cs`-Datei, überall** | Dahinter stehen Prozessaufsicht, Lizenz, Token und die Weiterleitung. Ein Fehler dort beendet Instanzen oder lässt einen Absturz unbemerkt | +| `*.csproj`, `ClawdDotNet.slnx`, `deploy/`, `NuGet.Config` | Bauplan und Release-Strecke | +| `docs/Roadmap.md` zwischen den ``-Markern | Erzeugte Kopie | + +**Ein Griff nach C# ist kein Regelverstoß, sondern ein Befund:** Er heißt, dass die API +etwas nicht hergibt, was sie hergeben müsste. Dann melden (`dc_report`, Projekt +`clawddotnet`) und an der Oberfläche weiterbauen — nicht selbst in den Kern greifen. + +Zur Kontrolle vor jeder Abgabe: `git status` darf **ausschließlich** Dateien unter +`src/ClawdDotNet.Manager.Web/wwwroot/` zeigen. + +### 11.3 Was sich seit dem WebUI-Leitfaden geändert hat + +Der [WebUI-Leitfaden](WebUI-Leitfaden.md) gilt weiter für Stil, Sicherheit und Aufbau der +Oberfläche. Vier Dinge darin sind überholt: + +| Damals | Heute | +|---|---| +| `wwwroot` liegt in `src/ClawdDotNet.Web/` | **`src/ClawdDotNet.Manager.Web/`** | +| Die Oberfläche läuft im Prozess der Instanz | Sie läuft im **Instanzmanager**, einem eigenen Prozess | +| `http://127.0.0.1:7001`, Token in `InstanceSettings.json` | **`webUiPort` und `webUiToken` in `manager.json`** (Vorgabe 7000) | +| Eine Instanz, ein `/api` | **N Instanzen**, der Manager leitet weiter | + +Der Rest des Leitfadens — kein `innerHTML`, kein Paketmanager, Token nur im +`sessionStorage`, Farben aus `app.css` — gilt unverändert. + +### 11.4 Die API, gegen die du baust + +**Was den Manager selbst angeht** (wird *nicht* weitergeleitet): + +| Aufruf | Was er tut | +|---|---| +| `GET /api/verwaltung/instanzen` | Liste: `{ id, name, zustand, prozess, autostart }` | +| `POST /api/verwaltung/instanzen` `{ "name": "…" }` | Legt eine an | +| `POST /api/verwaltung/instanzen/{id}/start` | Startet sie | +| `POST /api/verwaltung/instanzen/{id}/stop` | Hält sie an | +| `POST /api/verwaltung/instanzen/{id}/fenster` | Holt ihr Desktop-Fenster nach vorn | + +`id` ist der Ordnername (`Instance-Test`). `zustand` ist einer von `Unknown`, `Stopped`, +`Running`, `Silent`, `Crashed`. + +**Alles andere unter `/api`** geht unverändert an eine Instanz — `/api/info`, +`/api/agents`, `/api/chat`, `/api/jobs`, `/api/tasks`, `/api/staging`, `/api/usage`, +`/api/logs/modules`. Die Übertragungstypen sind dieselben wie bisher; hier ändert sich +nichts außer der Adressierung. + +**Welche Instanz gemeint ist**, sagt die Kopfzeile `X-Instanz` mit der `id`. Fehlt sie: +Läuft genau eine, ist sie gemeint. Laufen mehrere, kommt **409** mit einem erklärenden +Text — dann muss die Oberfläche eine wählen lassen. Läuft keine, ebenfalls 409. + +**Der Ereignisstrom** (`/events`, `/events/logs`) führt alle laufenden Instanzen zusammen. +Jedes Ereignis hat **zusätzlich** `instanz` (die `id`) und `instanzName`. Die bisherigen +Felder bleiben unverändert — vorhandene Ansichten funktionieren weiter, sie wissen nur +noch nicht, von wem etwas kommt. + +**Antwortcodes, die eine eigene Behandlung verdienen:** + +| Code | Bedeutung | +|---|---| +| 401 | Token fehlt oder taugt nicht → zurück zur Anmeldung (gibt es schon) | +| **402** | Ohne gültige Lizenz startet keine Instanz | +| **409** | Unklar, welche Instanz gemeint ist — oder eine Aktion passt nicht zum Zustand | +| **502** | Die Instanz antwortet nicht. **Kein Fehler des Managers** — sag das auch so | + +### 11.5 Reihenfolge + +1. **`X-Instanz` mitschicken.** In `modules/api.js` gibt es genau eine Stelle, an der + `fetch` aufgerufen wird — dort die Kopfzeile aus einer gewählten Instanz setzen. Beim + Ereignisstrom geht das nicht (`EventSource` kann keine Kopfzeilen); dort ist es auch + nicht nötig, der Manager führt ohnehin alle zusammen. +2. **Instanzauswahl im Rahmen.** Eine Liste aus `/api/verwaltung/instanzen`, die gewählte + Instanz im `sessionStorage` neben dem Token. Zustand sichtbar machen — `Silent` und + `Crashed` sind keine Nebensache, sondern der Grund, warum es den Manager gibt. +3. **Verwaltungsansicht.** Anlegen, starten, anhalten, Fenster nach vorn. Die Liste nach + jeder Aktion neu holen; die Zustände ändern sich im Hintergrund. +4. **Herkunft der Ereignisse zeigen.** `instanzName` an Chat-, Schritt- und + Protokollzeilen, damit in einem Fenster mit drei Instanzen erkennbar ist, wer spricht. + +### 11.6 Zwei Fallen + +**Der Zustand ändert sich, ohne dass jemand klickt.** Der Manager sieht alle paar Sekunden +nach; eine Instanz kann abstürzen oder verstummen, während die Liste offen steht. Eine +Ansicht, die nur beim Öffnen lädt, zeigt dann etwas Falsches — und zwar genau in dem +Moment, für den es diese Ansicht gibt. + +**Der Manager beendet beim Schließen keine Instanz.** Wer die Weboberfläche zumacht oder +den Manager beendet, beendet nichts. Was läuft, läuft weiter, und der nächste Manager +findet es wieder. Eine Oberfläche, die „Manager beenden" mit „alles beenden" beschriftet, +sagt die Unwahrheit. + +### 11.7 Wie du es ausprobierst + +```bash +dotnet build +``` + +`manager.json` liegt unter `%APPDATA%\ClawdDotNet\` (Windows) beziehungsweise +`~/.config/ClawdDotNet/`; ein anderer Ort geht über `--config `. Nötig sind +mindestens `webUiToken` (≥ 20 Zeichen) und `instanceExecutable`, wenn Manager und Instanz +nicht im selben Ausgabeordner liegen. + +```bash +dotnet run --project src/ClawdDotNet.ManagerApp +``` + +Der Manager schreibt seine Adresse auf die Standardausgabe und protokolliert nach +`/Logs/Manager/`. Zum Prüfen mit zwei Instanzen: eine zweite über +`POST /api/verwaltung/instanzen` anlegen, beide starten — dann muss die Oberfläche eine +wählen lassen. + +### 11.8 Was ausdrücklich liegen bleibt + +Diese drei Punkte sind **C#** und warten auf den Kern-Agenten. Nicht anfangen: + +1. **`webServerPort` aus der Instanz entfernen.** Erst sinnvoll, wenn 11.5 steht. +2. **Lizenzprüfung aus der Instanz nehmen** (E-M3 vollständig). Braucht vorher einen + Handschlag, an dem eine Instanz erkennt, ob ein Manager da ist. +3. **Verstummte Instanzen neu starten?** Nicht entschieden — siehe Abschnitt 7. diff --git a/docs/WebUI-Leitfaden.md b/docs/WebUI-Leitfaden.md index 4f6742d..6001679 100644 --- a/docs/WebUI-Leitfaden.md +++ b/docs/WebUI-Leitfaden.md @@ -8,7 +8,27 @@ Gegenstück zum [Oberflächen-Leitfaden](Oberflaechen-Leitfaden.md), der für Avalonia gilt. Vorhaben im Deploymentcenter: -**#494** (Weboberfläche), **#493** (Fachlogik nach `App`). +**#494** (Weboberfläche), **#493** (Fachlogik nach `App`), **#531** (Instanzen in der +Oberfläche). + +--- + +## Vorweg: Vier Dinge in diesem Leitfaden sind überholt + +Seit dem 2026-09-09 trägt der **Instanzmanager** die Weboberfläche (#528). Der Leitfaden +gilt weiter für Stil, Sicherheit und Aufbau — kein `innerHTML`, kein Paketmanager, Token +nur im `sessionStorage`, Farben aus `app.css`. Vier Angaben darin stimmen nicht mehr: + +| Im Text | Tatsächlich | +|---|---| +| `wwwroot` liegt in `src/ClawdDotNet.Web/` | **`src/ClawdDotNet.Manager.Web/wwwroot/`** | +| Die Oberfläche läuft im Prozess der Instanz | Sie läuft im **Instanzmanager**, einem eigenen Prozess. Er spricht mit den Instanzen über einen Socket und **leitet weiter** | +| `http://127.0.0.1:7001`, Einstellungen in `InstanceSettings.json` | **`webUiPort`, `webUiBinding`, `webUiToken` in `manager.json`**, Vorgabe 7000 | +| Ein `/api` für eine Instanz | **N Instanzen.** `/api/verwaltung/…` gehört dem Manager, alles andere unter `/api` geht an die Instanz aus der Kopfzeile `X-Instanz` | + +**Der aktuelle Auftrag und die vollständige API stehen in** +[Instanzmanager-Konzept.md, Abschnitt 11](Instanzmanager-Konzept.md#11--übergabe-an-den-frontend-agenten). +Lies den zuerst; dieser Leitfaden ist das Nachschlagewerk daneben. ---