docs: Dokumentation aktualisiert – Preparer, ask_user_choice, Plan-Modus, TaskInstruction, Message-Tag

ARCHITECTURE.md: - Multi-Agent System: 'Review + Finalizer' → 'Preparer + Review + Finalizer' - Neue Sektion: Vorbereiter-Agent (Preparer) mit Flow, SSE-Events, History-Logik - Neue Sektion: Interaktive Rückfragen (ask_user_choice) mit Tool-Definition, Backend/Frontend-Flow - Neue Sektion: Plan-Modus mit Tool-Filterung, System-Prompt-Anpassungen - System-Prompt-Aufbau: 12 → 14+ Blöcke (Anweisungen, Rückfragen, Plan-Modus, Preparer) - Tool-System: ask_user_choice + Plan-Modus Read-only Filter dokumentiert - Agent-System: AllowUserChoice + TaskInstruction Felder - Datenmodell: preparer_agent_id, plan_mode, Tag, neue StopReasons - DB-Persistierung: Tag-Markierung für Sub-Agent-Messages ARCHITECTURE_QUICK.md: - Sessions/Chains/Messages Tabellen aktualisiert - Chat-Pipeline: Preparer-Phase + ask_user_choice ergänzt - Tool-System: 12 → 13 Tools - System-Prompt: 12 → 14+ Blöcke - Multi-Agent: Preparer + Tag-System README.md: - Features: Vorbereiter-Agent, Interaktive Rückfragen, Plan-Modus - 12 → 13 Tools
2026-03-07 18:46:29 +01:00
1 parent cb1dff734e
commit f4dc5fd812
@@ -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.