From b4c844b7c2230f9a3c750c3d112f32f290b1ce9f Mon Sep 17 00:00:00 2001 From: Meleki Date: Sat, 7 Mar 2026 20:29:12 +0100 Subject: [PATCH] docs: Dokumentation aktualisieren (JS-Refactoring, Dashboard-Optimierung, WebP/Thumbnails) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ARCHITECTURE.md: - JS-Projektstruktur: ui.js → 13 modulare Dateien dokumentiert - Kern-Module: Vollständige Liste aller neuen Module mit Beschreibungen - Card-Builder: Referenzen von ui.js auf cards.js aktualisiert - History-Rendering: Referenz von ui.js auf bubbles.js aktualisiert - Markdown-Rendering: Referenz von ui.js auf markdown.js aktualisiert - Avatar-System: PNG/JPEG → WebP, neue Felder avatar_small/image_small - ImageService: Beschreibung aktualisiert (512px + 256px Thumbnail, WebP) - Neue Records: SessionWithStats, GitStatusSummary dokumentiert - Endpoints: Sessions-Liste inkl. inline Git-Status, Agents inkl. inline Skills - Tabellen: avatar_small, image_small Felder ergänzt - Datenbank-Migrationen: Bild-Migration (WebP + Thumbnails) dokumentiert ARCHITECTURE_QUICK.md: - JS-Verzeichnisstruktur: Alle 13 neuen Module aufgelistet - Tabellen: avatar_small, image_small ergänzt - ImageService: WebP + Thumbnail-Beschreibung README.md: - JS-Verzeichnisbeschreibung: 'UI-Module (modular aufgeteilt)' --- ARCHITECTURE.md | 82 ++++++++++++++++++++++++++++++++----------- ARCHITECTURE_QUICK.md | 21 ++++++++--- README.md | 2 +- 3 files changed, 79 insertions(+), 26 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index de6f8cf..27f539b 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -126,7 +126,7 @@ gott/ │ ├── TelegramService.cs # Telegram Bot API Integration │ ├── CronjobService.cs # BackgroundService für Cron-Tasks │ ├── KreaService.cs # Krea Image Generation API -│ ├── ImageService.cs # Bild-Resize (Avatar, Session-Image) +│ ├── ImageService.cs # Bild-Resize + WebP-Konvertierung (512px + 256px Thumbnail) │ ├── StreamingTracker.cs # Tracking aktiver Streams + CancellationTokenSource für Stop │ └── WorkspaceHelper.cs # Workspace-Pfad-Auflösung (relativ → absolut) │ @@ -183,9 +183,19 @@ gott/ │ │ ├── app.js # App-Initialisierung, Auth-Check │ │ ├── router.js # Client-side SPA Router │ │ ├── api.js # API-Client (fetch wrapper) -│ │ ├── ui.js # UI-Utilities (Modal, Toast, etc.) -│ │ ├── chat.js # Chat-Logic, SSE-Streaming -│ │ ├── history.js # History-Rendering, Pagination +│ │ ├── ui-helpers.js # DOM-Helpers ($, esc, truncate), Toast, ScrollDown, Meta-Bar +│ │ ├── markdown.js # Markdown-Rendering (renderMarkdown, LaTeX/Code-Schutz) +│ │ ├── cards.js # Card-Builder (buildSessionCard, buildAgentCard) +│ │ ├── msg-actions.js # Nachrichten-Aktionen (Delete, Mark, Share, Reply, Timestamp) +│ │ ├── tool-ui.js # Tool-Boxes, Diffs, Todo-Liste, Visibility-Logik +│ │ ├── modals.js # Modale Dialoge (System-Prompt, Command-Output, Krea-Image) +│ │ ├── stream-ui.js # Stream-Bubble, Review-Streaming +│ │ ├── bubbles.js # Message Bubbles (User, Assistant, Error, Warning, Choice, Review) +│ │ ├── chat.js # Chat-Logic, SSE-Streaming, Plan-Mode +│ │ ├── history.js # History-Rendering, Polling +│ │ ├── archive.js # Archiv-Loading +│ │ ├── reply.js # Reply/Quote-Handling +│ │ ├── files.js # File-Upload, Workspace-Refs │ │ ├── session.js # Session-Verwaltung │ │ ├── file-explorer.js # File-Explorer Komponente │ │ ├── avatar-editor.js # Wiederverwendbares Avatar-Editor-Modal @@ -269,8 +279,8 @@ Message (1) ─── (*) SharedMessage |-------------------|-----------------------------------------------------| | `users` | Benutzer (username, password_hash, persona, settings, default_path) | | `tokens` | Auth-Tokens (token → user_id) | -| `agents` | AI-Agenten (model, soul, identity, memory, tools, avatar_scale, avatar_offset_x/y, allow_user_choice, task_instruction) | -| `sessions` | Chat-Sessions (workspace, context, telegram-config, avatar_scale, avatar_offset_x/y, telegram_allowed_chat_ids, preparer_agent_id, review_agent_id, max_review_iterations, finalizer_agent_id) | +| `agents` | AI-Agenten (model, soul, identity, memory, tools, avatar_scale, avatar_offset_x/y, allow_user_choice, task_instruction, avatar_small) | +| `sessions` | Chat-Sessions (workspace, context, telegram-config, avatar_scale, avatar_offset_x/y, telegram_allowed_chat_ids, preparer_agent_id, review_agent_id, max_review_iterations, finalizer_agent_id, image_small) | | `chains` | Request-Chains (model, tokens, iterations, timing) | | `messages` | Einzelne Nachrichten (text, tool_use, tool_result, web_search_result) | | `attachments` | Datei-Anhänge (base64, image/document) | @@ -302,6 +312,15 @@ Message (1) ─── (*) SharedMessage - `Tag` – Sub-Agent-Markierung (`null` = normal, `"preparer"/"review"/"finalizer"` = Sub-Agent-Message, wird aus API-History gefiltert) - `DeletedOn` – Soft-Delete Zeitstempel +**SessionWithStats** – Erweitertes Session-Objekt für Listen-Endpunkt: +- Enthält alle `SessionRecord`-Felder + `MessageCount`, `ArchiveCount` +- `GitStatus` – Inline Git-Status-Summary (`Add`, `Edit`, `Delete`, `Outgoing`) oder `null` wenn kein Workspace +- `Image` wird durch `ImageSmall` ersetzt (Thumbnail für Dashboard-Performance) + +**GitStatusSummary** – Kompakte Git-Status-Info: +- `Add`, `Edit`, `Delete` – Anzahl geänderter Dateien nach Typ +- `Outgoing` – Anzahl ausgehender (nicht gepushter) Commits + --- ## Backend-Architektur @@ -342,7 +361,7 @@ AuthService → DatabaseService → EnsureDefaultUser | `TelegramService` | Singleton | Telegram Bot API, Webhook-Handling, Nachrichten senden | | `CronjobService` | Background | Minütlicher Check auf fällige Cronjobs, Ausführung via Claude | | `KreaService` | Singleton | Krea API für Bildgenerierung, Job-Polling, Image-Download | -| `ImageService` | Singleton | Bild-Resize (max 512px) für Avatare und Session-Bilder | +| `ImageService` | Singleton | Bild-Resize + WebP-Konvertierung (512px + 256px Thumbnail) für Avatare und Session-Bilder | | `StreamingTracker` | Singleton | Trackt aktive Streams + CancellationTokenSource pro Session für Stop-Button | ### Endpoints (API) @@ -354,8 +373,8 @@ Alle Endpoints folgen dem **Minimal API**-Pattern mit Extension Methods (`MapXxx | **Auth** | `/api/auth/` | `POST login`, `POST logout`, `GET me`, `GET autologin` | | **Chat** | `/api/chat` | `POST` (SSE Streaming), `POST stop` | | **History** | `/api/history` | `GET history`, `GET poll`, `POST archive`, `GET archives`, `GET archive/{id}`, `GET attachments/{id}`, `PUT messages/{id}/mark`, `PUT messages/{id}/delete`, `GET chains/{id}` | -| **Sessions** | `/api/sessions/` | CRUD + `GET system-prompt`, `GET system-prompt-blocks`, `GET streaming`, `POST exec`, `GET git-status` | -| **Agents** | `/api/agents/` | CRUD | +| **Sessions** | `/api/sessions/` | CRUD + `GET system-prompt`, `GET system-prompt-blocks`, `GET streaming`, `POST exec`, `GET git-status` (Liste inkl. inline Git-Status + Thumbnail) | +| **Agents** | `/api/agents/` | CRUD (Liste inkl. inline Skills + Thumbnail) | | **Admin** | `/api/admin/` | `GET users`, `POST users`, `PUT users/{id}`, `PUT users/{id}/password`, `DELETE users/{id}`, `POST users/{id}/impersonate`, `POST users/{id}/login-link` (Admin-only) | | **Workspace** | `/api/workspace/` | `GET tree`, `GET/PUT file`, `GET browse`, `POST mkdir`, `DELETE dir`, `POST browse/mkdir`, `GET agent/tree`, `GET/PUT agent/file`, `POST agent/mkdir`, `GET raw` | | **Telegram** | `/api/telegram/` | `POST webhook/{sessionId}` (unauthenticated), Session-Config CRUD, Webhook-Management | @@ -432,18 +451,28 @@ Das Frontend ist eine **Single-Page Application** ohne Build-Step, komplett in V - **app.js** – Initialisierung, Auth-Check, globale Event-Handler - **api.js** – Zentraler API-Client mit `fetch()`-Wrapper, Auth-Redirect bei 401 -- **ui.js** – UI-Utilities (Modals, Toasts, Confirmations), Card-Builder (`buildAgentCard()`, `buildSessionCard()`), Markdown-Rendering-Helpers (`esc()`, `prettyModelName()`) -- **chat.js** – SSE-Stream-Handling, Markdown-Rendering (mit KaTeX), Tool-Output-Darstellung -- **history.js** – Chat-History laden, paginieren, rendern +- **ui-helpers.js** – DOM-Helpers (`$`, `esc`, `truncate`), Toast-System, ScrollDown, Meta-Bar, Button-Builder +- **markdown.js** – Markdown-Rendering (`renderMarkdown`), LaTeX/Code-Schutz, Krea-Gallery-Wrapping +- **cards.js** – Card-Builder (`buildAgentCard()`, `buildSessionCard()`) +- **msg-actions.js** – Nachrichten-Aktionen (Delete, Mark, Share, Reply-Button, Timestamp) +- **tool-ui.js** – Tool-Boxes (Diffs, Todos, File-Content), Visibility-Logik +- **modals.js** – Modale Dialoge (System-Prompt, Command-Output, Krea-Image) +- **stream-ui.js** – Stream-Bubble, Review-Streaming-Rendering +- **bubbles.js** – Message Bubbles (User, Assistant, Error, Warning, Choice, Review, Attachments) +- **chat.js** – SSE-Stream-Handling, sendMessage, Plan-Mode +- **history.js** – Chat-History laden, paginieren, rendern, Polling +- **archive.js** – Archiv-Loading und -Rendering +- **reply.js** – Reply/Quote-Handling (Set, Clear, Format) +- **files.js** – File-Upload, Workspace-Refs - **session.js** – Session-State-Management - **file-explorer.js** – Workspace File-Explorer Panel (Dateien, Ordner erstellen/löschen, Folder-Browser) - **avatar-editor.js** – Wiederverwendbares Avatar-Editor-Modal (Upload, Paste, AI-Generate, Scale) - **commands-ui.js** – Custom-Commands UI-Komponente -### Wiederverwendbare Card-Builder (ui.js) +### Wiederverwendbare Card-Builder (cards.js) -- **`buildAgentCard(agent, skills)`** – Erzeugt ein `.card` DOM-Element für einen Agent (Avatar, Name, Model-Badge, Feature-Badges: toolChoice, autoCommit, useSoul, useIdentity, useUserInfo, useMemory, webSearch, Skills). Wird im Dashboard und im Agent-Picker-Modal (Session-Formular) verwendet. -- **`buildSessionCard(session, agent)`** – Erzeugt ein `.card` DOM-Element für eine Session (Avatar, Name, Badges: Agent, Kontext, Telegram, Meta: Nachrichten/Archiv/Workspace). Wird im Dashboard und im Session-Picker-Modal (Cronjob-Formular) verwendet. +- **`buildAgentCard(agent)`** – Erzeugt ein `.card` DOM-Element für einen Agent (Avatar, Name, Model-Badge, Feature-Badges: toolChoice, autoCommit, useSoul, useIdentity, useUserInfo, useMemory, webSearch, Skills). Skills werden inline vom API-Endpunkt mitgeliefert. Wird im Dashboard und im Agent-Picker-Modal (Session-Formular) verwendet. +- **`buildSessionCard(session, agent)`** – Erzeugt ein `.card` DOM-Element für eine Session (Avatar, Name, Badges: Agent, Kontext, Telegram, Meta: Nachrichten/Archiv/Workspace, Git-Status). Git-Status wird inline vom API-Endpunkt mitgeliefert. Wird im Dashboard und im Session-Picker-Modal (Cronjob-Formular) verwendet. - **Picker-Modals** – Agent- und Session-Auswahl in Formularen (Session-/Cronjob-Seiten) erfolgt über modale Dialoge mit den Card-Buildern statt über Dropdowns. - **emoji.js** – Emoji-Picker mit Kategorien und Suche - **tooltip.js** – Tooltip-System für Hover-Infos @@ -614,7 +643,7 @@ Ein **Agent** definiert die Persönlichkeit und Fähigkeiten der AI: | Eigenschaft | Beschreibung | |-------------------|------------------------------------------------------------------| | `Name` | Anzeigename | -| `Avatar` | Base64 Data-URL (auf 512px resized) | +| `Avatar` | Base64 Data-URL (WebP, 512px) + `AvatarSmall` (WebP, 256px Thumbnail) | | `Model` | `sonnet`, `sonnet-4-5`, `sonnet-4-6`, `opus`, `opus-4-5`, `opus-4-6`, `haiku`, `haiku-4-5` | | `ToolChoice` | `any` oder `auto` | | `CustomCommands` | JSON-Array mit Slash-Commands (Label + Prompt) | @@ -1090,7 +1119,7 @@ public class ReviewContext - SSE-Event-Handler für `review_start`, `review_text`, `review_tool_use`, `review_feedback`, `review_approved` - Review-Bubbles mit eigenem Styling (sekundäre Farbe, Agent-Name-Header) -**History-Rendering** (`history.js`, `ui.js`): +**History-Rendering** (`history.js`, `bubbles.js`): - `renderMarkdown` parst `[Review: AgentName]` → styled Header mit Icon - `renderMarkdown` parst `[Review-Feedback von AgentName (...)]` → styled Feedback-Header - `renderMarkdown` filtert `[APPROVED]` aus (wird ausgeblendet) @@ -1366,13 +1395,25 @@ Sessions und Agents können ein **Bild/Avatar** haben mit konfigurierbarem Zoom. | Feld | Tabellen | Beschreibung | |------|----------|-------------| -| `image` / `avatar` | `sessions` / `agents` | Base64-kodiertes Bild (JPEG, max 512px via ImageService) | +| `image` / `avatar` | `sessions` / `agents` | Base64-kodiertes Bild (WebP, max 512px via ImageService) | +| `image_small` / `avatar_small` | `sessions` / `agents` | Thumbnail (WebP, 256px, Q70) für Listen/Dashboard | | `avatar_scale` | `sessions`, `agents` | Zoom-Faktor (0.5× – 3×, Default 1.0) | | `avatar_offset_x` | `sessions`, `agents` | Horizontale Position (-50% – +50%, Default 0), via CSS `translate()` | | `avatar_offset_y` | `sessions`, `agents` | Vertikale Position (-50% – +50%, Default 0), via CSS `translate()` | Darstellung via CSS `transform: scale(S) translate(X%, Y%)` im `.card-image` Container (`overflow: hidden`). +### Bild-Verarbeitung (ImageService) + +Alle Bilder werden beim Upload in **WebP** konvertiert (statt PNG), was ~60-80% Speicherersparnis bringt: + +| Variante | Methode | Max. Größe | Qualität | Verwendung | +|----------|---------|------------|----------|------------| +| Voll | `ResizeDataUrl()` | 512px | Q80 | Editor, Detail-Ansicht (`GET /api/agents/{id}`, `GET /api/sessions/{id}`) | +| Thumbnail | `ResizeDataUrlSmall()` | 256px | Q70 | Listen, Dashboard (`GET /api/agents`, `GET /api/sessions`) | + +Die Listen-Endpoints liefern das Thumbnail als `avatar`/`image`-Feld (Fallback auf Voll-Bild wenn kein Thumbnail existiert). Die Detail-Endpoints liefern das volle Bild. + ### Avatar-Editor (`avatar-editor.js`) Wiederverwendbares Modal-Modul, genutzt in Session- und Agent-Pages: @@ -1400,7 +1441,7 @@ const editor = AvatarEditor.init({ ### Dashboard-Darstellung -Cards zeigen Avatare mit `transform: scale(S) translate(X%, Y%)` im `.card-image` Container (`overflow: hidden`). Die Helper `buildAgentCard()` und `buildSessionCard()` in `ui.js` nutzen `buildTransformStyle(scale, offsetX, offsetY)` dafür. +Cards zeigen Avatare mit `transform: scale(S) translate(X%, Y%)` im `.card-image` Container (`overflow: hidden`). Die Helper `buildAgentCard()` und `buildSessionCard()` in `cards.js` nutzen `buildTransformStyle(scale, offsetX, offsetY)` dafür. --- @@ -1413,7 +1454,7 @@ Chat-Nachrichten unterstützen **LaTeX-Formeln** via KaTeX: - `$$...$$` → **Block-Math** (zentriert, eigene Zeile) - `$...$` → **Inline-Math** (im Fließtext) -### Rendering-Pipeline (in `ui.js` `renderMarkdown()`) +### Rendering-Pipeline (in `markdown.js` `renderMarkdown()`) ``` 1. Code-Blöcke extrahieren und schützen (Platzhalter) @@ -1510,6 +1551,7 @@ Die `DatabaseService.InitializeDatabase()` handhabt Schema-Erstellung und Migrat 1. **Tabellen-Erstellung** via `CREATE TABLE IF NOT EXISTS` 2. **Spalten-Migration** via `TryAddColumn()` – fängt "column already exists" ab 3. **Daten-Migration** (z.B. `auto_commit` von INTEGER zu TEXT, `use_web_search` zu `web_search_version`) +4. **Bild-Migration** – Konvertierung bestehender PNG/JPEG-Avatare zu WebP + Generierung von Thumbnails (`avatar_small`, `image_small`) Dieses Pattern ermöglicht: - Idempotente Ausführung bei jedem App-Start diff --git a/ARCHITECTURE_QUICK.md b/ARCHITECTURE_QUICK.md index 2647327..3b16c0e 100644 --- a/ARCHITECTURE_QUICK.md +++ b/ARCHITECTURE_QUICK.md @@ -25,8 +25,19 @@ gott/ │ ├── js/app.js # App-Init │ ├── js/router.js # Hash-basiertes SPA-Routing │ ├── js/api.js # fetch()-Wrapper -│ ├── js/chat.js # SSE-Stream, Markdown-Rendering -│ ├── js/ui.js # UI-Helpers, buildAgentCard(), buildSessionCard(), Review-Rendering +│ ├── js/ui-helpers.js # DOM-Helpers ($, esc, truncate), Toast, ScrollDown +│ ├── js/markdown.js # Markdown-Rendering (renderMarkdown, LaTeX-Schutz) +│ ├── js/cards.js # Card-Builder (buildSessionCard, buildAgentCard) +│ ├── js/msg-actions.js # Nachrichten-Aktionen (Delete, Mark, Share, Reply) +│ ├── js/tool-ui.js # Tool-Boxes, Diffs, Visibility-Logik +│ ├── js/modals.js # Modale Dialoge (System-Prompt, Command-Output) +│ ├── js/stream-ui.js # Stream-Bubble, Review-Streaming +│ ├── js/bubbles.js # Message Bubbles (User, Assistant, Error, Choice) +│ ├── js/chat.js # SSE-Stream-Handling, sendMessage, Plan-Mode +│ ├── js/history.js # History laden, Polling, Rendering +│ ├── js/archive.js # Archiv-Loading +│ ├── js/reply.js # Reply/Quote-Handling +│ ├── js/files.js # File-Upload, Workspace-Refs │ ├── js/pages/ # Seiten-Komponenten │ └── css/ # Styles (theme.css = CSS Variables) ├── WindowsApp/ # WPF + WebView2 Desktop Client @@ -54,8 +65,8 @@ User 1──* Agent 1──* Session 1──* Chain 1──* Message 1──* At |---------|-------| | `users` | Login, Persona, Settings (JSON), DefaultPath | | `tokens` | Auth-Tokens → User | -| `agents` | AI-Agenten (Model, Tools, Config, AvatarScale, AvatarOffsetX/Y) | -| `sessions` | Chat-Sessions (Workspace, Context, Telegram, AvatarScale, AvatarOffsetX/Y, AllowedChatIds, PreparerAgentId, ReviewAgentId, MaxReviewIterations, FinalizerAgentId) | +| `agents` | AI-Agenten (Model, Tools, Config, AvatarScale, AvatarOffsetX/Y, AvatarSmall) | +| `sessions` | Chat-Sessions (Workspace, Context, Telegram, AvatarScale, AvatarOffsetX/Y, AllowedChatIds, PreparerAgentId, ReviewAgentId, MaxReviewIterations, FinalizerAgentId, ImageSmall) | | `chains` | Ein Request-Response-Zyklus (Tokens, Timing, Iterations, PlanMode) | | `messages` | Einzelne Nachrichten (text / tool_use / tool_result / error / web_search_result), Tag für Sub-Agent-Markierung | | `attachments` | Base64-Anhänge (Bilder, Dokumente) | @@ -107,7 +118,7 @@ User 1──* Agent 1──* Session 1──* Chain 1──* Message 1──* At | **TelegramService** | Telegram Bot API | | **CronjobService** | BackgroundService, minütlicher Cron-Check | | **KreaService** | Krea API Bildgenerierung + Job-Polling | -| **ImageService** | Bild-Resize (ImageSharp, max 512px) | +| **ImageService** | Bild-Resize + WebP-Konvertierung (512px + 256px Thumbnail) | | **StreamingTracker** | Tracking aktiver Streams + CancellationTokenSource pro Session für Stop | --- diff --git a/README.md b/README.md index 48b1e05..1cf1bc7 100644 --- a/README.md +++ b/README.md @@ -138,7 +138,7 @@ gott/ ├── Middleware/ # Auth-Middleware ├── Templates/ # Vorlagen (IDENTITY.md, SOUL.md, USER.md) ├── wwwroot/ # Frontend (Vanilla JS SPA) -│ ├── js/ # App, Router, API, Chat, UI-Helpers, Pages +│ ├── js/ # App, Router, API, Chat, UI-Module (modular aufgeteilt), Pages │ └── css/ # Styles (theme.css = CSS Variables) ├── WindowsApp/ # WPF + WebView2 Desktop Client └── publish/ # Build-Output + Laufzeit-Daten