From 72347ed2f5332edf1ea1a99437d6503d7f731ab9 Mon Sep 17 00:00:00 2001 From: Meleki Date: Sat, 7 Mar 2026 10:53:03 +0100 Subject: [PATCH] docs: Finalizer-Agent, Web-Search Sources und Multi-Agent System dokumentiert MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- ARCHITECTURE.md | 116 ++++++++++++++++++++++++++++++++++++++---- ARCHITECTURE_QUICK.md | 30 +++++++---- README.md | 2 + 3 files changed, 127 insertions(+), 21 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 1b32e8c..4e73c3e 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -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 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) diff --git a/ARCHITECTURE_QUICK.md b/ARCHITECTURE_QUICK.md index c3a51d2..ff3db2d 100644 --- a/ARCHITECTURE_QUICK.md +++ b/ARCHITECTURE_QUICK.md @@ -55,9 +55,9 @@ 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, ReviewAgentId, MaxReviewIterations) | +| `sessions` | Chat-Sessions (Workspace, Context, Telegram, AvatarScale, AvatarOffsetX/Y, AllowedChatIds, ReviewAgentId, MaxReviewIterations, FinalizerAgentId) | | `chains` | Ein Request-Response-Zyklus (Tokens, Timing, Iterations) | -| `messages` | Einzelne Nachrichten (text / tool_use / tool_result / error) | +| `messages` | Einzelne Nachrichten (text / tool_use / tool_result / error / web_search_result) | | `attachments` | Base64-Anhänge (Bilder, Dokumente) | | `archives` | Archivierte Chain-Gruppen | | `cronjobs` | Geplante Tasks (Cron-Expression + Prompt) | @@ -128,6 +128,9 @@ User-Input → POST /api/chat (SSE) → Bei end_turn + ReviewAgent → Review-Phase: → Review-Agent prüft (eigene Tools, max 25 Iterationen) → [APPROVED] → Fertig | Feedback → Worker korrigiert → erneuter Review + → Bei FinalizerAgent → Finalizer-Phase: + → Finalizer-Agent arbeitet (eigene Tools, z.B. git commit) + → Einmalig, kein Feedback-Loop → Stop-Button: POST /api/chat/stop → StreamingTracker.Cancel() → CancellationToken durchgereicht bis ToolService → Prozess-Kill → client_disconnected @@ -238,20 +241,27 @@ Läuft als `systemd`-Service, Kestrel auf konfigurierbarem Port (Default 19000), --- -## Multi-Agent Review-System +## Multi-Agent System (Review + Finalizer) -Eine Session kann optional einen **Review-Agent** haben (`review_agent_id`, `max_review_iterations`). +Eine Session kann optional einen **Review-Agent** (`review_agent_id`, `max_review_iterations`) und/oder einen **Finalizer-Agent** (`finalizer_agent_id`) haben. -**Flow:** Worker-Agent arbeitet → `end_turn` → Review-Agent prüft (eigener API-Call, eigene Tools, max 25 Iterationen) → `[APPROVED]` = fertig | Feedback → Worker korrigiert → erneuter Review (bis max Runden). +**Flow:** Worker-Agent arbeitet → `end_turn` → Review-Agent prüft → `[APPROVED]` / Feedback-Loop → Finalizer-Agent arbeitet (einmalig, kein Loop) → Fertig. -**Backend:** `ChatService` baut `ReviewContext` (Model, SystemPrompt, Tools). `AnthropicService.RunReview()` orchestriert Review-Runden. `RunReviewAgentChat()` = eigener Claude-API-Call. +**Backend:** `ChatService` baut `ReviewContext` + `FinalizerContext`. `RunReview()` orchestriert Review-Runden. `RunFinalizer()` führt Finalizer aus. Beide nutzen die generische `RunAgentChat()` Methode (eigener Claude-API-Call mit Tool-Loop). -**SSE-Events:** `review_start`, `review_text`, `review_tool_use`, `review_feedback`, `review_approved` +**SSE-Events:** +- Review: `review_start`, `review_text`, `review_tool_use`, `review_feedback`, `review_approved` +- Finalizer: `finalizer_start`, `finalizer_text`, `finalizer_tool_use`, `finalizer_done` **Frontend-Rendering:** -- Streaming: `chat.js` rendert Review-Events als eigene Bubbles (`.review-bubble`) -- History: `renderMarkdown` parst `[Review: AgentName]`, `[Review-Feedback ...]`, filtert `[APPROVED]` -- `history.js` + `shared-page.js`: Review-Nachrichten als `.review-bubble`, kein Merging mit normalen Messages +- Streaming: `chat.js` rendert Review-/Finalizer-Events als eigene Bubbles (`.review-bubble` / `.finalizer-bubble`) +- History: `renderMarkdown` parst `[Review: AgentName]`, `[Finalizer: AgentName]`, `[Review-Feedback ...]`, filtert `[APPROVED]` +- `history.js` + `shared-page.js`: Review-/Finalizer-Nachrichten mit eigenen Bubble-Klassen, kein Merging + +**Web-Search Sources:** +- `web_search_result`-Messages in DB gespeichert (Sources als JSON-Array, leere werden übersprungen) +- History + Shared-Page: Tool-Box mit klickbaren Source-Links (Domain + Title) +- Streaming: `pauseStreamBubble()` hält Bubble offen zwischen Web-Searches (keine Doppel-Bubbles) --- diff --git a/README.md b/README.md index 149e36a..111b23f 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,8 @@ Self-hosted AI-Coding-Agent auf Basis der Anthropic Claude API. Stellt eine Web- - **Multi-Agent-System** – Mehrere Agenten mit eigenen Identitäten, Persönlichkeiten und Tool-Konfigurationen - **Multi-Agent Review** – Optionaler Review-Agent pro Session, der die Arbeit des Worker-Agents prüft und Feedback gibt +- **Finalizer-Agent** – Optionaler Agent, der nach dem Review abschließende Arbeiten durchführt (z.B. Git-Commit, Deployment) +- **Web-Search** – Integrierte Web-Suche mit Quellenangaben (URLs + Titel) in Chat und geteilten Nachrichten - **12 Tools** – `read_file`, `write_file`, `edit_file`, `list_files`, `delete_file`, `execute`, `glob`, `grep`, `todo_write`, `memory_read`, `memory_write`, `memory_list` - **Streaming** – Echtzeit-Antworten via Server-Sent Events (SSE) - **Stop-Button** – Laufende Requests zuverlässig abbrechen (inkl. laufender Shell-Befehle)