diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 4e73c3e..de6f8cf 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -29,8 +29,10 @@ 15. [Krea-Bildgenerierung](#krea-bildgenerierung) 16. [Auth & Multi-User](#auth--multi-user) 17. [Admin-Benutzerverwaltung](#admin-benutzerverwaltung) -18. [Multi-Agent System (Review + Finalizer)](#multi-agent-system-review--finalizer) -19. [Nachrichten teilen (Shared Messages)](#nachrichten-teilen-shared-messages) +18. [Multi-Agent System (Preparer + Review + Finalizer)](#multi-agent-system-preparer--review--finalizer) +19. [Interaktive Rückfragen (ask_user_choice)](#interaktive-rückfragen-ask_user_choice) +20. [Plan-Modus](#plan-modus) +21. [Nachrichten teilen (Shared Messages)](#nachrichten-teilen-shared-messages) 20. [Workspace & File-Explorer](#workspace--file-explorer) 21. [Avatar-System](#avatar-system) 22. [LaTeX/Math-Rendering](#latexmath-rendering) @@ -267,8 +269,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) | -| `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) | +| `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) | | `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) | @@ -287,7 +289,8 @@ Message (1) ─── (*) SharedMessage - `SystemPrompt` – Der vollständige System-Prompt (gespeichert für Nachvollziehbarkeit) - `InputTokens`, `OutputTokens`, `CacheCreationTokens`, `CacheReadTokens` – Token-Verbrauch - `Iterations` – Anzahl der Tool-Loop-Durchläufe -- `StopReason` – `end_turn`, `tool_use`, `max_iterations`, `error`, `client_disconnected` +- `StopReason` – `end_turn`, `tool_use`, `max_iterations`, `error`, `client_disconnected`, `awaiting_user_choice`, `preparer_query` +- `PlanMode` – Ob die Chain im Plan-Modus erstellt wurde (informativ) - `DurationMs` – Gesamtdauer der Chain **MessageRecord** – Eine einzelne Nachricht innerhalb einer Chain: @@ -296,6 +299,7 @@ Message (1) ─── (*) SharedMessage - `Content` – Textinhalt oder JSON (bei tool_use: Input-JSON) - `ToolName`, `ToolCallId` – Bei Tool-Aufrufen - `IsMarked` – Als wichtig markierte Nachricht (wird in System-Prompt aufgenommen) +- `Tag` – Sub-Agent-Markierung (`null` = normal, `"preparer"/"review"/"finalizer"` = Sub-Agent-Message, wird aus API-History gefiltert) - `DeletedOn` – Soft-Delete Zeitstempel --- @@ -576,10 +580,22 @@ Der Agent hat Zugriff auf folgende Tools, abhängig von Konfiguration: | `memory_write` | Memory-Datei schreiben (überschreiben/append) | | `memory_list` | Alle Memory-Dateien des Agents auflisten | +### Interaktive Rückfragen (wenn AllowUserChoice aktiviert) + +| Tool | Beschreibung | +|--------------------|-----------------------------------------------------| +| `ask_user_choice` | Stellt dem User eine Frage mit 2-5 Auswahlmöglichkeiten | + +Dieses Tool wird **nicht ausgeführt**, sondern als SSE-Event an den Client weitergeleitet. Siehe [Interaktive Rückfragen](#interaktive-rückfragen-ask_user_choice). + ### Web-Suche (wenn WebSearchVersion konfiguriert) Nutzt Anthropics eingebaute Web-Suche als Server-Side-Tool. +### Plan-Modus: Read-only Tools + +Im Plan-Modus werden nur folgende Tools bereitgestellt: `read_file`, `list_files`, `glob`, `grep`, `execute`, `todo_write`, `memory_*`, `ask_user_choice`. Write-Tools (`write_file`, `edit_file`, `delete_file`) werden gefiltert. + ### Tool-Choice Strategien - **`any`**: Erste Iteration erzwingt Tool-Nutzung, danach `auto`. Verhindert dass der Agent nur Text antwortet wenn Tools benötigt werden. @@ -608,6 +624,8 @@ Ein **Agent** definiert die Persönlichkeit und Fähigkeiten der AI: | `UseUserInfo` | User-Persona in System-Prompt einbinden | | `UseMemory` | Memory-Tools aktivieren | | `WebSearchVersion`| Web-Suche aktivieren (z.B. `web_search_20260209`) | +| `AllowUserChoice` | `ask_user_choice`-Tool verfügbar (Default: true) | +| `TaskInstruction` | Aufgabe/Anweisung – optionaler Text, wird als `## Anweisungen`-Block in System-Prompt eingefügt | ### Model-Auflösung @@ -633,16 +651,20 @@ Der `SystemPromptBuilder` erzeugt den System-Prompt modular aus konfigurierbaren ┌──────────────────────────────────────────┐ │ 1. IDENTITY.md (UseIdentity) │ → Wer ist der Agent? │ 2. SOUL.md (UseSoul) │ → Persönlichkeit, Verhalten -│ 3. User-Persona (UseUserInfo) │ → Infos über den User -│ 4. Tool-Nutzung (Workspace + any) │ → "IMMER Tools benutzen" -│ 5. Workspace-Info │ → Tools + Workspace-Pfad -│ 6. Session-Kontext │ → Freiformtext -│ 7. Skills (Agent-Skills) │ → Skill-Prompts -│ 8. Memory (UseMemory) │ → Memory-Regeln + MEMORY.md Inhalt -│ 9. Git-Verhalten (AutoCommit) │ → Commit-Regeln -│10. Verhaltensregeln (Workspace + any) │ → "IMMER Tools aufrufen" -│11. Erinnerung (Workspace + any) │ → Höchste Priorität: Tool-Aufrufe! -│12. Markierte Nachrichten │ → Vom User als wichtig markierte Messages +│ 3. Anweisungen (TaskInstruction) │ → Aufgaben-/Anweisungstext (optional) +│ 4. User-Persona (UseUserInfo) │ → Infos über den User +│ 5. Tool-Nutzung (Workspace + any) │ → "IMMER Tools benutzen" +│ 6. Workspace-Info │ → Tools + Workspace-Pfad +│ 7. Rückfragen (AllowUserChoice) │ → Hinweis zu ask_user_choice Tool +│ 8. Session-Kontext │ → Freiformtext +│ 9. Skills (Agent-Skills) │ → Skill-Prompts +│10. Memory (UseMemory) │ → Memory-Regeln + MEMORY.md Inhalt +│11. Git-Verhalten (AutoCommit) │ → Commit-Regeln +│12. Verhaltensregeln (Workspace + any) │ → "IMMER Tools aufrufen" +│13. Erinnerung (Workspace + any) │ → Höchste Priorität: Tool-Aufrufe! +│14. Markierte Nachrichten │ → Vom User als wichtig markierte Messages +│ [Plan-Modus-Block] │ → Nur wenn planMode=true (überspringt 5,11,12,13) +│ [Preparer-Instruktionsblock] │ → Nur für Preparer-Agents └──────────────────────────────────────────┘ ``` @@ -912,14 +934,21 @@ Admins können für jeden User einen **Autologin-Link** generieren – z.B. für --- -## Multi-Agent System (Review + Finalizer) +## Multi-Agent System (Preparer + Review + Finalizer) -Das Multi-Agent-System ermöglicht bis zu **drei Agents** pro Session: einen **Worker**, einen optionalen **Reviewer** und einen optionalen **Finalizer**. +Das Multi-Agent-System ermöglicht bis zu **vier Agents** pro Session: einen **Worker**, einen optionalen **Vorbereiter (Preparer)**, einen optionalen **Reviewer** und einen optionalen **Finalizer**. ### Architektur ``` -User-Message → Worker-Agent arbeitet (Tools, Iterationen) → end_turn +User-Message + → Preparer-Phase (optional): + → Preparer-Agent bekommt: User-Message + History (inkl. eigener vorheriger Messages) + → Preparer arbeitet (kann Tools nutzen: read_file, execute etc.) + → Erledigt Vorarbeit mit seinen Fähigkeiten (z.B. JSON bauen, Daten aufbereiten) + → [QUESTION] → Rückfrage an User, Flow stoppt, User muss erneut eingeben + → Antwort ohne [QUESTION] → automatisch weiterleiten an Worker + → Worker-Agent arbeitet (Tools, Iterationen) → end_turn → Review-Phase (optional): → Review-Agent bekommt: Konversation als Kontext → Review-Agent prüft (kann Tools nutzen: read_file, execute etc.) @@ -940,11 +969,54 @@ Auf **Session-Ebene** (nicht Agent-Ebene): | DB-Feld | SessionRecord | Beschreibung | |---------|---------------|-------------| +| `preparer_agent_id` | `PreparerAgentId` | ID des Vorbereiter-Agents (optional, null = kein Preparer) | | `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 +### Vorbereiter-Agent (Preparer) + +Der Preparer wird **vor** dem Worker-Agent aufgerufen. Er analysiert die User-Anfrage, kann Vorarbeit leisten (z.B. Daten aufbereiten, JSON bauen, Code analysieren) und gibt das Ergebnis an den Worker weiter. Bei unklaren Anfragen stellt er Rückfragen. + +#### Logik-Pattern: Default = Forward + +Die Logik ist **invertiert** gegenüber dem Review-Pattern: Jede Antwort wird automatisch weitergeleitet, **außer** sie enthält explizit `[QUESTION]`. Das ist robuster als ein Pflicht-Tag wie `[FORWARD]`, weil LLMs dazu neigen, Tags zu vergessen. + +| Antwort | Ergebnis | +|---------|----------| +| Ohne `[QUESTION]` | Automatisch weitergeleitet (`ShouldForward = true`) | +| Mit `[QUESTION]` | Rückfrage an User, Flow stoppt (`ShouldForward = false`) | + +#### Backend-Flow (Preparer) + +1. **ChatEndpoint** – Prüft ob `ctx.Preparer` vorhanden +2. **AnthropicService.RunPreparer()** – Ruft `RunAgentChat()` auf mit `agentType = "preparer"` +3. **Entscheidung** – `ShouldForward` prüft ob `[QUESTION]` im Text: + - **Forward**: Aufbereiteter Text wird als `[Vorbereitet von AgentName]:`-User-Message in DB gespeichert, History wird neu geladen, StreamChat startet + - **Rückfrage**: SSE `preparer_done` mit `forwarded: false`, Stream endet mit `stopReason: "preparer_query"`, User muss erneut eingeben + +#### Preparer-History + +Der Preparer bekommt seine eigene History (`BuildHistoryFromDb(sessionId, includeTag: "preparer")`), damit er seine vorherigen Rückfragen und User-Antworten sieht. Der Session-Agent bekommt die History **ohne** Preparer-Messages (Tag-Filter). + +#### System-Prompt + +Der Preparer bekommt einen speziellen Instruktionsblock an seinen System-Prompt angehängt: +- Erklärt die Rolle als Vorbereiter +- Definiert `[QUESTION]`-Mechanismus für Rückfragen +- Instruiert aktive Vorarbeit mit eigenen Fähigkeiten und Tools +- Betont: Antworten werden automatisch weitergeleitet + +#### SSE-Events (Preparer) + +| Event | Daten | Beschreibung | +|-------|-------|-------------| +| `preparer_start` | `{ agent: "Name" }` | Preparer-Phase beginnt | +| `preparer_text` | `{ text: "..." }` | Preparer-Agent-Text (Token-Stream) | +| `preparer_tool_use` | `{ tool: "name", input: "..." }` | Preparer nutzt Tool | +| `preparer_done` | `{ forwarded: true/false }` | Preparer-Phase beendet | + +### Backend-Flow (Review) 1. **ChatService.PrepareContext()** – Wenn `session.ReviewAgentId` gesetzt: - Review-Agent aus DB laden @@ -1001,9 +1073,12 @@ public class ReviewContext ### DB-Persistierung -- **Worker-Antworten**: Normale Messages (role=assistant, type=text) +- **Worker-Antworten**: Normale Messages (role=assistant, type=text, tag=null) +- **Preparer-Antworten**: Messages mit `tag="preparer"` (aus API-History gefiltert, nur für Frontend-Anzeige) +- **Aufbereiteter Prompt**: Als User-Message mit Prefix `[Vorbereitet von AgentName]:` - **Review-Feedback**: Als User-Messages mit Prefix `[Review-Feedback von AgentName (Runde X/Y)]:` -- **Review-Agent-Antworten**: Werden **nicht** in der Chat-History persistiert (nur als SSE-Events gestreamt), da sie Zwischenergebnisse sind +- **Review-Agent-Antworten**: Messages mit `tag="review"` (aus API-History gefiltert) +- **Finalizer-Antworten**: Messages mit `tag="finalizer"` (aus API-History gefiltert) ### Frontend @@ -1047,10 +1122,10 @@ Der Finalizer wird **nach** dem Review (oder direkt nach dem Worker, falls kein 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: +4. **RunAgentChat()** – Generische Methode für Preparer/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 + - Antwort als Message in DB persistieren (mit `Tag = agentType`, wird aus API-History gefiltert) #### SSE-Events @@ -1063,13 +1138,103 @@ Der Finalizer wird **nach** dem Review (oder direkt nach dem Worker, falls kein #### 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 +- **Session-Page**: Vierter Agent-Picker: "Vorbereiter-Agent", "Review-Agent", "Finalizer-Agent" im "Weitere Einstellungen"-Bereich +- **Chat-UI**: Preparer-Bubbles (`.preparer-bubble`, Info-Farbe, 🔍-Icon), Finalizer-Bubbles (`.finalizer-bubble`, grüne Farbe, 🏁-Icon) +- **History**: `[Preparer: AgentName]` → styled Header mit `fa-filter` Icon, `[Vorbereitet von AgentName]` → styled Forwarded-Header, `[Finalizer: AgentName]` → styled Header, `[FORWARD]`/`[QUESTION]` werden ausgeblendet - **Dashboard**: 🏁-Badge auf Session-Cards mit Finalizer --- +## Interaktive Rückfragen (ask_user_choice) + +Das `ask_user_choice`-Tool ermöglicht dem Agent, dem User **klickbare Auswahlmöglichkeiten** zu präsentieren, wenn es mehrere sinnvolle Wege gibt oder eine Entscheidung vom User getroffen werden muss. + +### Tool-Definition + +```json +{ + "name": "ask_user_choice", + "description": "Stellt dem User eine Frage mit Auswahlmöglichkeiten", + "input_schema": { + "properties": { + "question": { "type": "string" }, + "choices": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 5 } + } + } +} +``` + +### Agent-Konfiguration + +- **`allow_user_choice`** (AgentRecord) – Boolean, Default `true`. Steuert ob das Tool verfügbar ist. +- Dashboard-Badge: `🔵 Rückfragen` wenn aktiv +- System-Prompt-Hinweis: "Nutze `ask_user_choice` sparsam – nur wenn die Entscheidung vom User getroffen werden soll" +- Bei Review/Finalizer/Cronjobs: **Immer deaktiviert** (kein User zum Fragen) + +### Backend-Flow + +1. Claude ruft `ask_user_choice` auf → Backend erkennt im `ProcessStream` +2. Tool wird **nicht ausgeführt** – stattdessen SSE-Event `user_choice` gesendet +3. `stopReason` wird auf `"awaiting_user_choice"` gesetzt (Guard-Clause verhindert Überschreibung durch `message_delta`) +4. `tool_use`-Block wird in DB gespeichert, Chain wird finalisiert +5. User wählt Option → Frontend sendet `POST /api/chat` mit `choiceToolCallId` + `choiceResult` +6. Backend findet die Chain mit dem offenen `tool_use`, speichert `tool_result` dort +7. Neuer `StreamChat` startet – History enthält `tool_use` + `tool_result`, Claude arbeitet weiter + +### Frontend-Flow + +- **Live**: SSE-Event `user_choice` → `addChoiceBubble()` rendert Frage + klickbare Buttons +- **History**: `tool_use` mit `toolName === 'ask_user_choice'` → Voraus-Suche nach `tool_result`: + - Gefunden: `addChoiceBubbleStatic()` mit ausgewählter Option (hervorgehoben, andere ausgegraut) + - Nicht gefunden: Aktive Buttons (klickbar, z.B. nach Page-Refresh) +- **Robustheit**: Guards gegen `choices` als String statt Array (`Array.isArray()` Check) +- **CSS**: `.choice-bubble`, `.choice-btn` (Primary-Color-Outline), `.choice-selected`/`.choice-unselected` + +### SSE-Events + +| Event | Daten | Beschreibung | +|-------|-------|-------------| +| `user_choice` | `{ toolCallId, question, choices[] }` | Rückfrage mit Auswahloptionen | + +--- + +## Plan-Modus + +Der Plan-Modus ist ein **Read-only-Betriebsmodus**, in dem der Agent den Code analysieren, Rückfragen stellen und Pläne erstellen kann – aber keine Dateien ändern oder Befehle ausführen darf. + +### Aktivierung + +- **Frontend**: Toggle-Button (🗺️ `fa-map`) im Chat-Input-Bereich +- **API**: `planMode: true` im `ChatRequest` +- **Pro Chain**: `plan_mode` Feld in der Chain (rein informativ für History-Anzeige) +- Kein Agent-Setting – wird **pro Nachricht** vom User gesteuert + +### Backend-Auswirkungen + +| Aspekt | Normal | Plan-Modus | +|--------|--------|-----------| +| **Tools** | Alle (read_file, write_file, edit_file, delete_file, execute, ...) | Nur read-only: `read_file`, `list_files`, `glob`, `grep`, `execute`, `todo_write`, `memory_*`, `ask_user_choice` | +| **System-Prompt** | Normal | + Plan-Modus-Block: "Du darfst NUR lesen und analysieren, KEINE Änderungen vornehmen" | +| **toolChoice** | `"any"` (wenn Agent so konfiguriert) | Immer `"auto"` (Claude darf frei antworten) | +| **Chain-Speicherung** | `plan_mode = 0` | `plan_mode = 1` | + +### System-Prompt-Anpassungen im Plan-Modus + +Folgende Blöcke werden **übersprungen**: KRITISCH (Tool-Nutzung erzwingen), Verhalten ("handle sofort"), Erinnerung ("MUSS Tool aufrufen"), Git-Commits. Der Tools-Block listet nur Read-only-Tools auf. Skills werden als "nur zur Kenntnis, nicht ausführbar" markiert. + +### Frontend + +- **Toggle**: `#planModeBtn` – wechselt `_planModeActive`, ändert Button-Styling + Placeholder-Text +- **Chain-Meta**: Badge `📋 Plan-Modus` bei Chains die im Plan-Modus erstellt wurden +- **System-Prompt-Modal**: Zeigt den angepassten System-Prompt wenn Plan-Modus aktiv +- **Session-Wechsel**: Plan-Modus wird zurückgesetzt + +### Choice-Response im Plan-Modus + +Wenn im Plan-Modus eine `ask_user_choice`-Rückfrage kommt und der User antwortet, erbt die Choice-Response den `planMode` des vorherigen Chains. + +--- + ## Web-Search Anthropic Claude unterstützt Web-Suche als Server-Tool. Das System integriert Web-Search mit Source-Tracking und Rendering. diff --git a/ARCHITECTURE_QUICK.md b/ARCHITECTURE_QUICK.md index ff3db2d..c1f9a5e 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, FinalizerAgentId) | -| `chains` | Ein Request-Response-Zyklus (Tokens, Timing, Iterations) | -| `messages` | Einzelne Nachrichten (text / tool_use / tool_result / error / web_search_result) | +| `sessions` | Chat-Sessions (Workspace, Context, Telegram, AvatarScale, AvatarOffsetX/Y, AllowedChatIds, PreparerAgentId, ReviewAgentId, MaxReviewIterations, FinalizerAgentId) | +| `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) | | `archives` | Archivierte Chain-Gruppen | | `cronjobs` | Geplante Tasks (Cron-Expression + Prompt) | @@ -118,12 +118,17 @@ User 1──* Agent 1──* Session 1──* Chain 1──* Message 1──* At User-Input → POST /api/chat (SSE) → ChatService.BuildContext() → History aus DB laden (letzte N Chains) - → SystemPromptBuilder: 12 Blöcke zusammensetzen - → Tool-Definitionen vom ToolService holen + → SystemPromptBuilder: 14 Blöcke zusammensetzen (+ Plan-Modus/Preparer-Blöcke) + → Tool-Definitionen vom ToolService holen (im Plan-Modus: nur Read-only) + → Preparer-Phase (optional, wenn PreparerAgentId gesetzt): + → RunPreparer() → RunAgentChat(agentType: "preparer") + → Antwort ohne [QUESTION] → automatisch weiterleiten (Default = Forward) + → [QUESTION] → Rückfrage an User, Flow stoppt → AnthropicService.StreamChat() → Claude API Call (SSE) → Token-für-Token an Client streamen → Bei tool_use → ToolService.Execute() → Ergebnis zurück → neuer API Call + → Bei ask_user_choice → SSE user_choice Event → Flow stoppt (awaiting_user_choice) → Loop bis end_turn oder max_iterations (100) → Bei end_turn + ReviewAgent → Review-Phase: → Review-Agent prüft (eigene Tools, max 25 Iterationen) @@ -143,7 +148,7 @@ User-Input → POST /api/chat (SSE) --- -## Tool-System (12 Tools) +## Tool-System (13 Tools) | Tool | Funktion | |------|----------| @@ -159,6 +164,7 @@ User-Input → POST /api/chat (SSE) | `memory_read` | Memory-Datei lesen | | `memory_write` | Memory-Datei schreiben/appenden | | `memory_list` | Memory-Dateien auflisten | +| `ask_user_choice` | Interaktive Rückfrage mit 2-5 Auswahlmöglichkeiten (wenn AllowUserChoice aktiv) | **Sicherheit:** Alle Pfade werden auf das Workspace-Verzeichnis beschränkt (`..` wird blockiert). Tools sind pro Agent konfigurierbar (Feld `tools` als komma-separierte Liste). @@ -166,20 +172,24 @@ User-Input → POST /api/chat (SSE) --- -## System-Prompt (12 Blöcke, in Reihenfolge) +## System-Prompt (14+ Blöcke, in Reihenfolge) 1. **Identity** – `IDENTITY.md` des Agents 2. **Soul** – `SOUL.md` des Agents -3. **User** – `USER.md` (globale User-Infos) + Persona -4. **Rules** – Verhaltensregeln (Tool-Nutzung, Workspace) -5. **Context** – Session-Kontext (custom system prompt) -6. **Marked Messages** – Als wichtig markierte Nachrichten -7. **Memory** – Aktueller MEMORY.md-Inhalt -8. **Skills** – Zugeordnete Skill-Prompts -9. **Todos** – Aktuelle Todo-Liste -10. **Tools** – Tool-Beschreibungen und -Regeln -11. **Workspace** – Pfad-Info, Dateibaum des Workspace -12. **Date** – Aktuelles Datum/Uhrzeit +3. **Anweisungen** – `TaskInstruction` des Agents (optional, wenn gesetzt) +4. **User** – `USER.md` (globale User-Infos) + Persona +5. **Rules** – Verhaltensregeln (Tool-Nutzung, Workspace) +6. **Workspace** – Pfad-Info, Tool-Liste +7. **Rückfragen** – Hinweis zu `ask_user_choice` (wenn AllowUserChoice aktiv) +8. **Context** – Session-Kontext (custom system prompt) +9. **Skills** – Zugeordnete Skill-Prompts +10. **Memory** – Aktueller MEMORY.md-Inhalt + Regeln +11. **Git** – Commit-Verhalten (wenn AutoCommit konfiguriert) +12. **Verhaltensregeln** – "IMMER Tools aufrufen" (wenn Workspace + any) +13. **Erinnerung** – Höchste Priorität: Tool-Aufrufe! (wenn Workspace + any) +14. **Markierte Nachrichten** – Vom User als wichtig markiert +- **[Plan-Modus]** – Überspringt 5, 11, 12, 13; Read-only Tools; "Nur analysieren" +- **[Preparer-Block]** – Instruktionen für Vorbereiter-Agents --- @@ -241,22 +251,25 @@ Läuft als `systemd`-Service, Kestrel auf konfigurierbarem Port (Default 19000), --- -## Multi-Agent System (Review + Finalizer) +## Multi-Agent System (Preparer + Review + Finalizer) -Eine Session kann optional einen **Review-Agent** (`review_agent_id`, `max_review_iterations`) und/oder einen **Finalizer-Agent** (`finalizer_agent_id`) haben. +Eine Session kann bis zu **vier Agents** haben: Worker (Pflicht), Preparer (optional, `preparer_agent_id`), Review (optional, `review_agent_id`, `max_review_iterations`), Finalizer (optional, `finalizer_agent_id`). -**Flow:** Worker-Agent arbeitet → `end_turn` → Review-Agent prüft → `[APPROVED]` / Feedback-Loop → Finalizer-Agent arbeitet (einmalig, kein Loop) → Fertig. +**Flow:** Preparer analysiert User-Anfrage (→ Vorarbeit leisten oder `[QUESTION]` Rückfrage) → Worker-Agent arbeitet → Review-Agent prüft (`[APPROVED]` / Feedback-Loop) → Finalizer-Agent arbeitet (einmalig) → Fertig. -**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). +**Preparer:** Default = Forward (jede Antwort wird automatisch weitergeleitet, `[QUESTION]` stoppt). Bekommt eigene History mit `includeTag: "preparer"`. Aufbereiteter Prompt wird als `[Vorbereitet von AgentName]:` User-Message gespeichert. + +**Backend:** `ChatService` baut `PreparerContext` + `ReviewContext` + `FinalizerContext`. `RunPreparer()` im ChatEndpoint (vor StreamChat). `RunReview()` + `RunFinalizer()` in AnthropicService. Alle nutzen `RunAgentChat()` (mit `Tag`-Markierung, Sub-Agent-Messages aus API-History gefiltert). **SSE-Events:** +- Preparer: `preparer_start`, `preparer_text`, `preparer_tool_use`, `preparer_done` - 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-/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 +- Streaming: `chat.js` rendert Preparer-/Review-/Finalizer-Events als eigene Bubbles +- History: `renderMarkdown` parst `[Preparer: AgentName]`, `[Vorbereitet von AgentName]`, `[Review: AgentName]`, `[Finalizer: AgentName]`, filtert `[APPROVED]`, `[FORWARD]`, `[QUESTION]` +- Bubble-Klassen: `.preparer-bubble` (Info-Farbe), `.review-bubble` (sekundäre Farbe), `.finalizer-bubble` (grüne Farbe) **Web-Search Sources:** - `web_search_result`-Messages in DB gespeichert (Sources als JSON-Array, leere werden übersprungen) diff --git a/README.md b/README.md index 111b23f..48b1e05 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,14 @@ Self-hosted AI-Coding-Agent auf Basis der Anthropic Claude API. Stellt eine Web- ## Features -- **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 +- **Multi-Agent-System** – Bis zu 4 Agenten pro Session: Worker, Vorbereiter (Preparer), Reviewer, Finalizer +- **Vorbereiter-Agent** – Optionaler Preparer, der User-Anfragen analysiert, Vorarbeit leistet und aufbereitete Prompts an den Worker weitergibt +- **Multi-Agent Review** – Optionaler Review-Agent, 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) +- **Interaktive Rückfragen** – `ask_user_choice`-Tool: Agent stellt dem User klickbare Auswahlmöglichkeiten +- **Plan-Modus** – Read-only-Modus zum Analysieren und Planen ohne Änderungen (Toggle im Chat) - **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` +- **13 Tools** – `read_file`, `write_file`, `edit_file`, `list_files`, `delete_file`, `execute`, `glob`, `grep`, `todo_write`, `memory_read`, `memory_write`, `memory_list`, `ask_user_choice` - **Streaming** – Echtzeit-Antworten via Server-Sent Events (SSE) - **Stop-Button** – Laufende Requests zuverlässig abbrechen (inkl. laufender Shell-Befehle) - **Skill-System** – Wiederverwendbare Prompt-Bausteine, zuordenbar pro Agent