Anleitung fuer den Umbau zur reinen WebUI und Englisch komplett (#764); Desktop eingefroren
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Richard
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
2725d02a1a
commit
2a225129e9
@@ -0,0 +1,171 @@
|
||||
# WebUI als einzige Oberfläche — und Englisch komplett
|
||||
|
||||
Auftrag für einen eigenen Agenten. Beschlossen am 2026-10-02 (Mensch). Roadmap-Eintrag im
|
||||
Deploymentcenter: **#764** (Themenbereich UI). Teil davon: #661 (Englisch als Hauptsprache).
|
||||
|
||||
**Lies das ganz, bevor du die erste Datei anfasst.** Die Stufen bauen aufeinander auf, und
|
||||
mehrere Grenzen in Abschnitt 2 sind keine Stilfragen, sondern Datenverlust oder
|
||||
Sicherheitslücken, wenn man sie übersieht.
|
||||
|
||||
---
|
||||
|
||||
## 1 — Worum es geht
|
||||
|
||||
1. **Eine Oberfläche statt zwei.** Gepflegt wird nur noch die WebUI
|
||||
(`src/ClawdDotNet.Manager.Web/wwwroot/`), getragen vom Instanzmanager. Die Avalonia-Fenster
|
||||
in `src/ClawdDotNet.Desktop/Views` verschwinden. Übrig bleibt eine **Hülle**, die den
|
||||
Manager startet und die WebUI zeigt.
|
||||
2. **Englisch komplett.** Seit #661 (2026-09-19) entsteht Neues auf Englisch, Texte kommen aus
|
||||
Sprachpaketen (`wwwroot/i18n/en.json`, `de.json`). Der Bestand ist noch gemischt. Dieser
|
||||
Auftrag räumt ihn auf: Bezeichner, Kommentare und Oberflächentexte auf Englisch, jeder
|
||||
sichtbare Text über einen Sprachschlüssel, Deutsch nur noch als Sprachpaket.
|
||||
|
||||
**Warum:** Jede Funktion zweimal zu bauen kostet, die Desktop-Oberfläche hat keine
|
||||
Testabdeckung, und der Zielbetrieb (Linux, 24/7) läuft ohnehin über Manager und WebUI. Seit
|
||||
0.1.17 kennt die Desktop-Oberfläche Einheiten, Stichproben, Abstimmungen, Vorlagen, Trigger,
|
||||
MCP-Server und Automatisierung nicht mehr — die Lücke ist schon da.
|
||||
|
||||
---
|
||||
|
||||
## 2 — Was nicht passieren darf
|
||||
|
||||
| Grenze | Warum |
|
||||
|---|---|
|
||||
| **Die Programmdatei `ClawdDotNet` bleibt.** `Program.cs`, `CommandLine.cs`, `HeadlessRun.cs`, `McpBridgeRun.cs` bleiben lauffähig | Sie ist der Instanzprozess (`--headless --managed --instance …`, so startet der Manager jede Instanz) und die MCP-Brücke. Fällt sie weg, startet keine Instanz mehr |
|
||||
| **Gespeicherte Namen nicht umbenennen** — ohne Migration und Test mit einer alten Datei | Sonst sind Einstellungen, Rechte oder Datenbanken nach dem Update leer oder kaputt. Siehe Abschnitt 6 |
|
||||
| **Begründungskommentare übersetzen, nie löschen** | Sie erklären, *warum* etwas so ist (oft ein Vorfall). Ein früherer Umbau durch ein Flash-Modell hat sie stillschweigend entfernt. Übersetzen: ja. Kürzen auf „was der Code tut“: nein |
|
||||
| **Texte, die ein Modell liest, nicht nebenbei umformulieren** | Werkzeugbeschreibungen, `ToolResult`-Meldungen, Rahmen um Fremdinhalt (`UntrustedContent`), Systemhinweise — das sind Prompts. Übersetzen ändert das Verhalten der Agenten. Eigene Stufe, eigener Test auf der VM (Stufe 4d) |
|
||||
| **Sicherheitsstellen nicht anfassen**, außer in Stufe 2 und nur wie dort beschrieben | `AccessToken.cs`, `TokenGate.cs`, `McpTransport.cs`, alles unter `Security/`, `ConfigSecrets`, Lizenzprüfung |
|
||||
| **Kein `innerHTML`, kein Paketmanager, keine neuen CDN-Abhängigkeiten** in der WebUI | Siehe [WebUI-Leitfaden](../WebUI-Leitfaden.md) |
|
||||
| **Radius 0, App-Akzent `var(--accent)`, keine zugeklappten Ebenen** | Hausstil, Entscheidung 2026-09-24 |
|
||||
| **Nur pushen, wenn alle vier Suiten grün sind** — unter Windows **und** Linux | Siehe [Teststrategie](../Teststrategie.md); Linux auf der Test-VM |
|
||||
|
||||
---
|
||||
|
||||
## 3 — Die Stufen
|
||||
|
||||
Jede Stufe ist ein eigener Branch und ein eigener Merge. Nach jeder Stufe: Suiten grün,
|
||||
Kommentar am Roadmap-Eintrag (`dc_comment`), dann die nächste.
|
||||
|
||||
### Stufe 0 — Bestandsaufnahme (Flash: ja)
|
||||
|
||||
Lege eine Tabelle an (in dieser Datei, Abschnitt 7): **jede Funktion der Desktop-Oberfläche**
|
||||
und ob die WebUI sie hat. Quelle sind die Fenster in `src/ClawdDotNet.Desktop/Views`:
|
||||
|
||||
`AddAgentWindow`, `AddJobWindow`, `AddServiceWindow`, `AgentChatsPageView`, `AgentsPageView`,
|
||||
`BackupPageView`, `ChatPageView`, `InfoPageView`, `InstancePickerWindow`, `LicenseWindow`,
|
||||
`LogPageView`, `MainWindow`, `RestoreBackupWindow`, `SettingsPageView`, `TasksPageView`,
|
||||
`TextEditorWindow`, `TokenUsagePageView`, `ToolSettingsView`.
|
||||
|
||||
Verdächtig, nur im Desktop zu stehen — besonders genau prüfen:
|
||||
- Erstinstallation und **Lizenz** (`LicenseWindow`)
|
||||
- **Wiederherstellungs-Passphrase** des Schlüsselbunds (im Start-Log steht die Warnung „kein
|
||||
Wiederherstellungsfach“ — wo setzt man sie heute?)
|
||||
- Instanz anlegen / wählen (`InstancePickerWindow`)
|
||||
- Sicherung zurückspielen (`RestoreBackupWindow`)
|
||||
- Dateiauswahl-Dialoge, Texteditor für Identity/Soul (`TextEditorWindow`)
|
||||
|
||||
Ergebnis: Liste „fehlt in der WebUI“. Nichts bauen in dieser Stufe.
|
||||
|
||||
### Stufe 1 — Lücken der WebUI schließen (Flash: ja für reine Ansichten, nein sobald C# nötig ist)
|
||||
|
||||
Für jede Zeile aus Stufe 0 mit „fehlt“: zuerst prüfen, ob die API den Endpunkt hat.
|
||||
- **Hat sie ihn:** Ansicht bauen, Texte in beide Sprachpakete.
|
||||
- **Hat sie ihn nicht:** Endpunkt in `src/ClawdDotNet.Web/Endpoints` (Instanz) oder
|
||||
`src/ClawdDotNet.Manager.Web/Endpoints.cs` (Manager), Fachlogik in `ClawdDotNet.App`
|
||||
(nie im Endpunkt), mit Test in `tests/ClawdDotNet.Web.Tests` oder `App.Tests`.
|
||||
Lizenz und Schlüsselbund sind Sicherheitsstellen → starkes Modell.
|
||||
|
||||
### Stufe 2 — Die Hülle (Flash: nein)
|
||||
|
||||
Empfehlung (vom Menschen noch zu bestätigen, bevor du anfängst — frage im Roadmap-Eintrag):
|
||||
|
||||
**Starter mit Systembrowser** statt eingebettetem Browser.
|
||||
- Startet den Instanzmanager, wenn er nicht läuft (unter Linux ist das der systemd-Dienst
|
||||
`clawddotnet-manager.service` — nicht doppelt starten).
|
||||
- Öffnet die WebUI im Standardbrowser, angemeldet über einen **Einmal-Link**: der Manager
|
||||
erzeugt auf Anfrage über seinen lokalen Socket (nicht über TCP) einen Zufallswert, gültig
|
||||
einmal und höchstens 60 Sekunden; die WebUI tauscht ihn gegen das Sitzungstoken. Das Token
|
||||
selbst steht nie in einer Adresse.
|
||||
- Taskleistensymbol mit Zustand (läuft / gestoppt / Fehler) und „WebUI öffnen“.
|
||||
- Begründung: keine neue Abhängigkeit (ein eingebetteter Browser braucht unter Linux
|
||||
WebKitGTK als Systempaket), am wenigsten Code.
|
||||
|
||||
Der Einmal-Link ist eine neue Anmeldeart — Test für: zweimal benutzt, zu spät benutzt, über
|
||||
TCP statt Socket angefordert. Alle drei müssen scheitern.
|
||||
|
||||
### Stufe 3 — Avalonia-Fenster entfernen (Flash: mit Vorsicht)
|
||||
|
||||
- `Views/`, `Controls/`, `Converters/`, ViewModels der Fenster, `App.axaml` — weg.
|
||||
- Avalonia-Pakete aus der `.csproj`, soweit die Hülle sie nicht braucht.
|
||||
- `Program.cs`: ohne `--headless`/`--managed`/MCP-Brücke startet künftig die Hülle.
|
||||
- `deploy/publish.py` und das Paket prüfen: Was fällt weg, was muss dabei bleiben? Ein
|
||||
Probepaket mit `--dry-run` bauen und auf der VM `--headless` starten.
|
||||
- `docs/Oberflaechen-Leitfaden.md` → nach `docs/archiv/`, Verweise in `CLAUDE.md` anpassen.
|
||||
|
||||
### Stufe 4 — Englisch komplett
|
||||
|
||||
| Teil | Was | Flash? |
|
||||
|---|---|---|
|
||||
| **4a** | WebUI: jeder sichtbare Text über `t("…")`, Schlüssel in `en.json` **und** `de.json`. Heute stehen noch Umlaut-Texte direkt in `.js`-Dateien | ja |
|
||||
| **4b** | WebUI: deutsche Bezeichner in JS (`erstelleElement`, `zeigeMeldung`, `lade` …, 28 Dateien) und CSS-Klassen (`karte`, `schaltflaeche`, `gedaempft` …, ~49) auf Englisch. Mechanisch, aber groß: **eine Umbenennung je Commit**, danach jede Ansicht im Browser öffnen | ja, in kleinen Schritten |
|
||||
| **4c** | C#: Kommentare und nicht gespeicherte Bezeichner (Klassen, Methoden, Variablen) in ~167 Dateien. `StagingAktion`, `Vorgabe`, `Rahmen`, `Werkzeugrechte` … Öffentliche Namen ändern bricht Aufrufer — nach jedem Schritt bauen und testen | ja, dateiweise |
|
||||
| **4d** | C#: **Texte, die Modelle lesen** — Werkzeugbeschreibungen, Fehlermeldungen an Agenten, Systemhinweise (~23 Werkzeugdateien, ~20 Meldungen). Danach eine Nacht Testinstanz auf der VM und Audit-Vergleich: arbeiten die Agenten wie vorher? | **nein** |
|
||||
| **4e** | API-Pfade: `/api/verwaltung`, `/api/instanz`, `/instanzen`, `/hooks/{instanz}` → englisch. Das bricht Absender von außen (n8n, Claude Code über MCP). Alte Pfade eine Version lang als Umleitung behalten | nein |
|
||||
|
||||
Prüfung der Sprachpakete nach jeder Stufe:
|
||||
```
|
||||
python -c "import json;e=json.load(open('src/ClawdDotNet.Manager.Web/wwwroot/i18n/en.json',encoding='utf-8'));d=json.load(open('src/ClawdDotNet.Manager.Web/wwwroot/i18n/de.json',encoding='utf-8'));print(set(e)^set(d) or 'gleich')"
|
||||
```
|
||||
Besser: als Test in `tests/ClawdDotNet.Web.Tests` anlegen, dann prüft ihn jeder Lauf.
|
||||
|
||||
---
|
||||
|
||||
## 4 — Wer was macht
|
||||
|
||||
Der Mensch fragte, ob ein Gemini Flash genügt. Antwort: **für etwa zwei Drittel ja** — für
|
||||
Stufe 0, 1 (reine Ansichten), 3 und 4a–4c, wenn diese Datei mitgegeben wird und jede Stufe
|
||||
vor dem Merge von einem starken Modell gegengelesen wird. **Nicht** für Stufe 2 (neue
|
||||
Anmeldeart), 4d (Prompts) und 4e (Pfade nach außen) und nicht für Lizenz/Schlüsselbund in
|
||||
Stufe 1.
|
||||
|
||||
Gegenlesen heißt mindestens: `git diff --stat` auf unerwartet große Löschungen prüfen; nach
|
||||
gelöschten Kommentarblöcken suchen (`git diff | grep '^-\s*//'`); Sprachpakete gleich; alle
|
||||
vier Suiten grün auf Windows und Linux.
|
||||
|
||||
---
|
||||
|
||||
## 5 — Fertig ist es, wenn
|
||||
|
||||
- `src/ClawdDotNet.Desktop` keine Avalonia-Fenster mehr enthält und die Hülle unter Windows
|
||||
und Linux die WebUI angemeldet öffnet
|
||||
- jede Funktion aus der Tabelle in Abschnitt 7 in der WebUI erreichbar ist
|
||||
- `grep -rn "[äöüÄÖÜß]" src --include=*.cs --include=*.js --include=*.css` nur noch
|
||||
Treffer in `i18n/de.json`-Inhalten, Testdaten und Kommentaren mit Zitaten liefert
|
||||
- die Testinstanz auf der VM eine Nacht mit der neuen Fassung läuft und das Audit keine
|
||||
neuen Fehlerbilder zeigt
|
||||
|
||||
---
|
||||
|
||||
## 6 — Gespeicherte Namen: nicht umbenennen
|
||||
|
||||
Diese Namen stehen in Dateien und Datenbanken bestehender Installationen. Eine Umbenennung
|
||||
braucht eine Migration (alt lesen, neu schreiben) **und** einen Test mit einer alten Datei.
|
||||
Im Zweifel: deutsch lassen und im Code mit einem englischen Namen kapseln.
|
||||
|
||||
| Wo | Beispiele |
|
||||
|---|---|
|
||||
| Werkzeugeinstellungen der Agenten (`AgentSettings.json`, `Tools.<Name>`) | `erlaubt`, `verboten` (Datenbank-/Werkzeugrechte), `sharedAccessLevel`, … |
|
||||
| Tabellen in `state.db` (`SqliteStorage.cs`) | `Dauerfreigaben`, Spalten aller Tabellen |
|
||||
| Audit-Einträge, `Source`-Werte, `DecidedBy`-Präfixe | werden gelesen und ausgewertet |
|
||||
| Aufgabendateien (Frontmatter), Taskboard-Felder | `onlyWhenMarketOpen`, `require_approval` … |
|
||||
| `manager.json`, `InstanceSettings.json` (PascalCase-Altbestand) | Schlüssel exakt so lassen |
|
||||
| Sprachschlüssel selbst | sind schon englisch — gut so |
|
||||
|
||||
---
|
||||
|
||||
## 7 — Bestandsaufnahme (Stufe 0 füllt das aus)
|
||||
|
||||
| Desktop-Funktion | Fenster | In der WebUI? | Endpunkt vorhanden? | Bemerkung |
|
||||
|---|---|---|---|---|
|
||||
| | | | | |
|
||||
Reference in New Issue
Block a user