docs: Finalizer-Agent, Web-Search Sources und Multi-Agent System dokumentiert

ARCHITECTURE.md: - Kapitel 18 umbenannt: Multi-Agent Review-System → Multi-Agent System (Review + Finalizer) - Finalizer-Agent komplett dokumentiert (Konfiguration, Backend-Flow, SSE-Events, Frontend) - RunAgentChat() als generische Methode für Review/Finalizer dokumentiert - Neues Kapitel Web-Search (Backend, Streaming pauseStreamBubble, History, Shared-Page) - Sessions-Tabelle: finalizer_agent_id, Message-Typ: web_search_result - Entity-Relationship: Finalizer-Agent Beziehung - Chat-Pipeline: Phase 4c (Finalizer) ARCHITECTURE_QUICK.md: - Multi-Agent System Sektion erweitert (Finalizer-Flow, SSE-Events, Frontend-Rendering) - Web-Search Sources Sektion (DB, History, Shared-Page, Streaming) - Tabellen + Message-Typen aktualisiert README.md: - Finalizer-Agent und Web-Search als Features
2026-03-07 10:53:03 +01:00
1 parent 6c38ccfe12
commit 72347ed2f5
@@ -29,7 +29,7 @@
 15. [Krea-Bildgenerierung](#krea-bildgenerierung)
 16. [Auth & Multi-User](#auth--multi-user)
 17. [Admin-Benutzerverwaltung](#admin-benutzerverwaltung)
-18. [Multi-Agent Review-System](#multi-agent-review-system)
+18. [Multi-Agent System (Review + Finalizer)](#multi-agent-system-review--finalizer)
 19. [Nachrichten teilen (Shared Messages)](#nachrichten-teilen-shared-messages)
 20. [Workspace & File-Explorer](#workspace--file-explorer)
 21. [Avatar-System](#avatar-system)
@@ -249,6 +249,7 @@ User (1) ─── (*) Agent
 User (1) ─── (*) Session
 Agent (1) ─── (*) Session     (Session hat optional einen Agent)
 Agent (1) ─── (*) Session     (Session hat optional einen Review-Agent)
+Agent (1) ─── (*) Session     (Session hat optional einen Finalizer-Agent)
 Agent (*) ─── (*) Skill       (via agent_skills Tabelle)
 Session (1) ─── (*) Chain     (ein Chat-Request = eine Chain)
 Session (1) ─── (*) Archive   (archivierte Chains)
@@ -267,9 +268,9 @@ 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) |
-| `sessions`        | Chat-Sessions (workspace, context, telegram-config, avatar_scale, avatar_offset_x/y, telegram_allowed_chat_ids, review_agent_id, max_review_iterations) |
+| `sessions`        | Chat-Sessions (workspace, context, telegram-config, avatar_scale, avatar_offset_x/y, telegram_allowed_chat_ids, review_agent_id, max_review_iterations, finalizer_agent_id) |
 | `chains`          | Request-Chains (model, tokens, iterations, timing)  |
-| `messages`        | Einzelne Nachrichten (text, tool_use, tool_result)   |
+| `messages`        | Einzelne Nachrichten (text, tool_use, tool_result, web_search_result) |
 | `attachments`     | Datei-Anhänge (base64, image/document)              |
 | `archives`        | Archivierte Chain-Gruppen                           |
 | `agent_skills`    | Agent ↔ Skill Zuordnung                             |
@@ -291,7 +292,7 @@ Message (1) ─── (*) SharedMessage

 **MessageRecord** – Eine einzelne Nachricht innerhalb einer Chain:
 - `Role` – `user`, `assistant`, `system`
- `Type` – `text`, `tool_use`, `tool_result`, `error`
+- `Type` – `text`, `tool_use`, `tool_result`, `error`, `web_search_result`
 - `Content` – Textinhalt oder JSON (bei tool_use: Input-JSON)
 - `ToolName`, `ToolCallId` – Bei Tool-Aufrufen
 - `IsMarked` – Als wichtig markierte Nachricht (wird in System-Prompt aufgenommen)
@@ -496,6 +497,15 @@ Der Chat-Flow von User-Input bis zur gerenderten Antwort:
   │    → Max Review-Runden → Fertig          │
   └─────────────────────────────────────────┘
   ↓
+4c. Finalizer-Phase (optional, wenn FinalizerAgent konfiguriert):
+   ┌─────────────────────────────────────────┐
+   │  Nach Review (oder direkt nach Worker):  │
+   │    → RunFinalizer() mit Finalizer-Agent  │
+   │    → Finalizer arbeitet (eigene Tools)   │
+   │    → z.B. git commit, deploy, cleanup    │
+   │    → Kein Feedback-Loop (einmalig)       │
+   └─────────────────────────────────────────┘
+   ↓
 5. Frontend: SSE Events empfangen und rendern
   • "text" → Markdown parsen, Token für Token anzeigen
   • "tool_*" → Tool-Aufrufe collapsible darstellen
@@ -902,21 +912,26 @@ Admins können für jeden User einen **Autologin-Link** generieren – z.B. für

 ---

-## Multi-Agent Review-System
+## Multi-Agent System (Review + Finalizer)

-Das Review-System ermöglicht es, einen zweiten Agent als **Reviewer** einzusetzen. Nach jeder Antwort des Worker-Agents prüft der Review-Agent das Ergebnis und gibt entweder `[APPROVED]` oder konstruktives Feedback.
+Das Multi-Agent-System ermöglicht bis zu **drei Agents** pro Session: einen **Worker**, einen optionalen **Reviewer** und einen optionalen **Finalizer**.

 ### Architektur

 ```
 User-Message → Worker-Agent arbeitet (Tools, Iterationen) → end_turn
-  → Review-Phase:
+  → Review-Phase (optional):
      → Review-Agent bekommt: Konversation als Kontext
      → Review-Agent prüft (kann Tools nutzen: read_file, execute etc.)
      → [APPROVED] → Fertig, Antwort an User
      → Feedback-Text → wird als User-Message an Worker-Agent eingefügt
      → Worker-Agent korrigiert → end_turn → Review-Agent prüft erneut
      → Max Review-Runden erreicht → Fertig (mit letzter Worker-Antwort)
+  → Finalizer-Phase (optional):
+      → Finalizer-Agent bekommt: gesamte Konversation
+      → Finalizer arbeitet (eigene Tools, z.B. git commit, deploy)
+      → Kein Feedback-Loop – einmalige Ausführung
+      → Fertig
 ```

 ### Konfiguration
@@ -927,6 +942,7 @@ Auf **Session-Ebene** (nicht Agent-Ebene):
 |---------|---------------|-------------|
 | `review_agent_id` | `ReviewAgentId` | ID des Review-Agents (optional, null = kein Review) |
 | `max_review_iterations` | `MaxReviewIterations` | Max. Review-Runden (Default: 3) |
+| `finalizer_agent_id` | `FinalizerAgentId` | ID des Finalizer-Agents (optional, null = kein Finalizer) |

 ### Backend-Flow

@@ -945,7 +961,7 @@ Auf **Session-Ebene** (nicht Agent-Ebene):
 4. **RunReview()** – Orchestriert eine einzelne Review-Runde:
   - Baut Review-Messages auf: Konversation als Context + Prüfanweisung
   - SSE-Event `review_start` an Client senden
-   - Ruft `RunReviewAgentChat()` auf (eigener API-Call an Claude mit Review-Agent-Config)
+   - Ruft `RunAgentChat()` auf (generische Methode für Review/Finalizer, eigener API-Call an Claude)
   - Review-Agent kann Tools nutzen (eigener Tool-Loop mit max. 25 Iterationen)
   - SSE-Events `review_text` und `review_tool_use` für Live-Streaming
   - Prüft ob Antwort `[APPROVED]` enthält:
@@ -958,17 +974,19 @@ Auf **Session-Ebene** (nicht Agent-Ebene):
   - `continue` → nächste while-Loop-Iteration → Worker korrigiert → Review erneut
   - `reviewRound++` bis `MaxReviewIterations` erreicht

-### ReviewContext (Model)
+### ReviewContext / FinalizerContext (Model)

 ```csharp
+// Identische Struktur für Review und Finalizer
 public class ReviewContext
 {
-    public string Model { get; set; }          // Claude-Modell des Review-Agents
+    public string Model { get; set; }          // Claude-Modell des Agents
    public string SystemPrompt { get; set; }   // Eigener System-Prompt
    public AgentRecord Agent { get; set; }     // Agent-Record für Name/Avatar
    public List<object> Tools { get; set; }    // Tool-Definitionen
-    public int MaxReviewIterations { get; set; } // Max Runden
+    public int MaxReviewIterations { get; set; } // Max Runden (nur bei Review relevant)
 }
+// ChatContext hat: ReviewContext Review + ReviewContext Finalizer
 ```

 ### SSE-Events
@@ -1007,6 +1025,82 @@ public class ReviewContext
 **Shared-Page** (`shared-page.js`):
 - Gleiche Review-Bubble-Erkennung für geteilte Nachrichten

+### Finalizer-Agent
+
+Der Finalizer wird **nach** dem Review (oder direkt nach dem Worker, falls kein Review-Agent konfiguriert) aufgerufen. Er führt abschließende Arbeiten durch (z.B. Git-Commit, Deployment, Cleanup) – **ohne Feedback-Loop**.
+
+#### Konfiguration
+
+| DB-Feld | SessionRecord | Beschreibung |
+|---------|---------------|-------------|
+| `finalizer_agent_id` | `FinalizerAgentId` | ID des Finalizer-Agents (optional, null = kein Finalizer) |
+
+#### Backend-Flow
+
+1. **ChatService.PrepareContext()** – Wenn `session.FinalizerAgentId` gesetzt:
+   - Finalizer-Agent aus DB laden
+   - `FinalizerContext` aufbauen (analog zu `ReviewContext`: Model, SystemPrompt, Tools)
+
+2. **AnthropicService.StreamChat()** – Nach Review-Phase (oder direkt nach Worker):
+   - Prüft ob `FinalizerContext` vorhanden
+   - Ruft `RunFinalizer()` auf
+
+3. **RunFinalizer()** – Baut Messages auf (gesamte Konversation + Finalisierungs-Anweisung), ruft `RunAgentChat()` auf (generische Methode, auch vom Review genutzt)
+
+4. **RunAgentChat()** – Generische Methode für Review/Finalizer:
+   - Eigener API-Call an Claude mit Agent-Config
+   - Tool-Loop mit SSE-Events (`{type}_text`, `{type}_tool_use`)
+   - Antwort als Message in DB persistieren
+
+#### SSE-Events
+
+| Event | Daten | Beschreibung |
+|-------|-------|-------------|
+| `finalizer_start` | `{ agent: "Name" }` | Finalizer-Phase beginnt |
+| `finalizer_text` | `{ text: "..." }` | Finalizer-Agent-Text (Token-Stream) |
+| `finalizer_tool_use` | `{ tool: "name", input: "..." }` | Finalizer nutzt Tool |
+| `finalizer_done` | `{}` | Finalizer-Phase beendet |
+
+#### Frontend
+
+- **Session-Page**: Dritter Agent-Picker "Finalizer-Agent" im "Weitere Einstellungen"-Bereich
+- **Chat-UI**: Finalizer-Bubbles mit eigenem Styling (`.finalizer-bubble`, grüne Farbe, 🏁-Icon)
+- **History**: `[Finalizer: AgentName]` Prefix → styled Header, `.finalizer-bubble`-Klasse
+- **Dashboard**: 🏁-Badge auf Session-Cards mit Finalizer
+
+---
+
+## Web-Search
+
+Anthropic Claude unterstützt Web-Suche als Server-Tool. Das System integriert Web-Search mit Source-Tracking und Rendering.
+
+### Backend
+
+- **Streaming**: `server_tool_use` (Suchanfrage) → `web_search_tool_result` (Ergebnisse mit Sources)
+- **Sources extrahieren**: Aus `web_search_tool_result`-Block werden `url` + `title` als JSON-Array extrahiert
+- **Persistierung**: `web_search_result`-Messages in DB (type=`web_search_result`, content = JSON-Array der Sources). Leere Ergebnisse (Sources=[]) werden **nicht** gespeichert.
+- **SSE-Events**: `web_search_start` (Suche beginnt) → `web_search_end` (Suche fertig, mit Sources)
+
+### Frontend – Streaming
+
+- `web_search_start` → Tool-Box mit Spinner erstellen, Stream-Bubble **pausieren** (nicht finalisieren)
+- `web_search_end` → Tool-Box mit Sources finalisieren
+- `text_start` → in bestehende Bubble weiter schreiben (kein neuer Block)
+- `pauseStreamBubble()` / `endStreamBubble()` Konzept: Text-Blöcke zwischen Web-Searches werden in **einer** Bubble zusammengefasst
+- `text_end` pausiert nur (Cursor weg), `endStreamBubble()` nur bei finalen Events (`done`, `tool_start`, `error`)
+
+### Frontend – History
+
+- `web_search_result`-Messages werden als Tool-Box mit klickbaren Source-Links gerendert (Domain + Title)
+- `_mergeConsecutiveAssistantTexts()` fügt Text-Messages zusammen, `web_search_result`-Messages dazwischen unterbrechen die Merge-Kette nicht
+- Leere `web_search_result`-Messages (Sources=[]) werden übersprungen
+
+### Frontend – Shared-Page
+
+- `SharedEndpoint` gibt `web_search_result`-Messages mit aus (Typ-Filter: `text` + `web_search_result`)
+- `shared-page.js` rendert `web_search_result` als Tool-Box mit Source-Links
+- Merge-Funktion überspringt `web_search_result` beim Rückwärts-Suchen, damit Texte zusammengeführt werden
+
 ---

 ## Nachrichten teilen (Shared Messages)