meleki/gott
1
0 Fork 0
Code Activity

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

Browse Source 
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
This commit is contained in:
Meleki committed 2026-03-07 18:46:29 +01:00
1 parent cb1dff734e
commit f4dc5fd812
3 files changed
+234 -53
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

ARCHITECTURE.md
+191 -26
View File
@@ -29,8 +29,10 @@
15. [Krea-Bildgenerierung](#krea-bildgenerierung) 15. [Krea-Bildgenerierung](#krea-bildgenerierung)
16. [Auth & Multi-User](#auth--multi-user) 16. [Auth & Multi-User](#auth--multi-user)
17. [Admin-Benutzerverwaltung](#admin-benutzerverwaltung) 17. [Admin-Benutzerverwaltung](#admin-benutzerverwaltung)
18. [Multi-Agent System (Review + Finalizer)](#multi-agent-system-review--finalizer) 18. [Multi-Agent System (Preparer + Review + Finalizer)](#multi-agent-system-preparer--review--finalizer)
19. [Nachrichten teilen (Shared Messages)](#nachrichten-teilen-shared-messages) 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) 20. [Workspace & File-Explorer](#workspace--file-explorer)
21. [Avatar-System](#avatar-system) 21. [Avatar-System](#avatar-system)
22. [LaTeX/Math-Rendering](#latexmath-rendering) 22. [LaTeX/Math-Rendering](#latexmath-rendering)
@@ -267,8 +269,8 @@ Message (1) ─── (*) SharedMessage
|-------------------|-----------------------------------------------------| |-------------------|-----------------------------------------------------|
| `users` | Benutzer (username, password_hash, persona, settings, default_path) | | `users` | Benutzer (username, password_hash, persona, settings, default_path) |
| `tokens` | Auth-Tokens (token → user_id) | | `tokens` | Auth-Tokens (token → user_id) |
| `agents` | AI-Agenten (model, soul, identity, memory, tools, avatar_scale, avatar_offset_x/y) | | `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, review_agent_id, max_review_iterations, finalizer_agent_id) | | `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) | | `chains` | Request-Chains (model, tokens, iterations, timing) |
| `messages` | Einzelne Nachrichten (text, tool_use, tool_result, web_search_result) | | `messages` | Einzelne Nachrichten (text, tool_use, tool_result, web_search_result) |
| `attachments` | Datei-Anhänge (base64, image/document) | | `attachments` | Datei-Anhänge (base64, image/document) |
@@ -287,7 +289,8 @@ Message (1) ─── (*) SharedMessage
- `SystemPrompt` – Der vollständige System-Prompt (gespeichert für Nachvollziehbarkeit) - `SystemPrompt` – Der vollständige System-Prompt (gespeichert für Nachvollziehbarkeit)
- `InputTokens`, `OutputTokens`, `CacheCreationTokens`, `CacheReadTokens` – Token-Verbrauch - `InputTokens`, `OutputTokens`, `CacheCreationTokens`, `CacheReadTokens` – Token-Verbrauch
- `Iterations` – Anzahl der Tool-Loop-Durchläufe - `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 - `DurationMs` – Gesamtdauer der Chain
**MessageRecord** – Eine einzelne Nachricht innerhalb einer Chain: **MessageRecord** – Eine einzelne Nachricht innerhalb einer Chain:
@@ -296,6 +299,7 @@ Message (1) ─── (*) SharedMessage
- `Content` – Textinhalt oder JSON (bei tool_use: Input-JSON) - `Content` – Textinhalt oder JSON (bei tool_use: Input-JSON)
- `ToolName`, `ToolCallId` – Bei Tool-Aufrufen - `ToolName`, `ToolCallId` – Bei Tool-Aufrufen
- `IsMarked` – Als wichtig markierte Nachricht (wird in System-Prompt aufgenommen) - `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 - `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_write` | Memory-Datei schreiben (überschreiben/append) |
| `memory_list` | Alle Memory-Dateien des Agents auflisten | | `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) ### Web-Suche (wenn WebSearchVersion konfiguriert)
Nutzt Anthropics eingebaute Web-Suche als Server-Side-Tool. 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 ### Tool-Choice Strategien
- **`any`**: Erste Iteration erzwingt Tool-Nutzung, danach `auto`. Verhindert dass der Agent nur Text antwortet wenn Tools benötigt werden. - **`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 | | `UseUserInfo` | User-Persona in System-Prompt einbinden |
| `UseMemory` | Memory-Tools aktivieren | | `UseMemory` | Memory-Tools aktivieren |
| `WebSearchVersion`| Web-Suche aktivieren (z.B. `web_search_20260209`) | | `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 ### Model-Auflösung
@@ -633,16 +651,20 @@ Der `SystemPromptBuilder` erzeugt den System-Prompt modular aus konfigurierbaren
┌──────────────────────────────────────────┐ ┌──────────────────────────────────────────┐
│ 1. IDENTITY.md (UseIdentity) │ → Wer ist der Agent? │ 1. IDENTITY.md (UseIdentity) │ → Wer ist der Agent?
│ 2. SOUL.md (UseSoul) │ → Persönlichkeit, Verhalten │ 2. SOUL.md (UseSoul) │ → Persönlichkeit, Verhalten
│ 3. User-Persona (UseUserInfo) │ → Infos über den User │ 3. Anweisungen (TaskInstruction) │ → Aufgaben-/Anweisungstext (optional)
│ 4. Tool-Nutzung (Workspace + any) │ → "IMMER Tools benutzen" │ 4. User-Persona (UseUserInfo) │ → Infos über den User
│ 5. Workspace-Info │ → Tools + Workspace-Pfad │ 5. Tool-Nutzung (Workspace + any) │ → "IMMER Tools benutzen"
│ 6. Session-Kontext │ → Freiformtext │ 6. Workspace-Info │ → Tools + Workspace-Pfad
│ 7. Skills (Agent-Skills) │ → Skill-Prompts │ 7. Rückfragen (AllowUserChoice) │ → Hinweis zu ask_user_choice Tool
│ 8. Memory (UseMemory) │ → Memory-Regeln + MEMORY.md Inhalt │ 8. Session-Kontext │ → Freiformtext
│ 9. Git-Verhalten (AutoCommit) │ → Commit-Regeln │ 9. Skills (Agent-Skills) │ → Skill-Prompts
│10. Verhaltensregeln (Workspace + any) │ → "IMMER Tools aufrufen" │10. Memory (UseMemory) │ → Memory-Regeln + MEMORY.md Inhalt
│11. Erinnerung (Workspace + any) │ → Höchste Priorität: Tool-Aufrufe! │11. Git-Verhalten (AutoCommit) │ → Commit-Regeln
│12. Markierte Nachrichten │ → Vom User als wichtig markierte Messages │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 ### 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-Phase (optional):
→ Review-Agent bekommt: Konversation als Kontext → Review-Agent bekommt: Konversation als Kontext
→ Review-Agent prüft (kann Tools nutzen: read_file, execute etc.) → 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 | | 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) | | `review_agent_id` | `ReviewAgentId` | ID des Review-Agents (optional, null = kein Review) |
| `max_review_iterations` | `MaxReviewIterations` | Max. Review-Runden (Default: 3) | | `max_review_iterations` | `MaxReviewIterations` | Max. Review-Runden (Default: 3) |
| `finalizer_agent_id` | `FinalizerAgentId` | ID des Finalizer-Agents (optional, null = kein Finalizer) | | `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: 1. **ChatService.PrepareContext()** – Wenn `session.ReviewAgentId` gesetzt:
- Review-Agent aus DB laden - Review-Agent aus DB laden
@@ -1001,9 +1073,12 @@ public class ReviewContext
### DB-Persistierung ### 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-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 ### 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) 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 - Eigener API-Call an Claude mit Agent-Config
- Tool-Loop mit SSE-Events (`{type}_text`, `{type}_tool_use`) - 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 #### SSE-Events
@@ -1063,13 +1138,103 @@ Der Finalizer wird **nach** dem Review (oder direkt nach dem Worker, falls kein
#### Frontend #### Frontend
- **Session-Page**: Dritter Agent-Picker "Finalizer-Agent" im "Weitere Einstellungen"-Bereich - **Session-Page**: Vierter Agent-Picker: "Vorbereiter-Agent", "Review-Agent", "Finalizer-Agent" im "Weitere Einstellungen"-Bereich
- **Chat-UI**: Finalizer-Bubbles mit eigenem Styling (`.finalizer-bubble`, grüne Farbe, 🏁-Icon) - **Chat-UI**: Preparer-Bubbles (`.preparer-bubble`, Info-Farbe, 🔍-Icon), Finalizer-Bubbles (`.finalizer-bubble`, grüne Farbe, 🏁-Icon)
- **History**: `[Finalizer: AgentName]` Prefix → styled Header, `.finalizer-bubble`-Klasse - **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 - **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 ## Web-Search
Anthropic Claude unterstützt Web-Suche als Server-Tool. Das System integriert Web-Search mit Source-Tracking und Rendering. Anthropic Claude unterstützt Web-Suche als Server-Tool. Das System integriert Web-Search mit Source-Tracking und Rendering.
ARCHITECTURE_QUICK.md
+37 -24
View File
@@ -55,9 +55,9 @@ User 1──* Agent 1──* Session 1──* Chain 1──* Message 1──* At
| `users` | Login, Persona, Settings (JSON), DefaultPath | | `users` | Login, Persona, Settings (JSON), DefaultPath |
| `tokens` | Auth-Tokens → User | | `tokens` | Auth-Tokens → User |
| `agents` | AI-Agenten (Model, Tools, Config, AvatarScale, AvatarOffsetX/Y) | | `agents` | AI-Agenten (Model, Tools, Config, AvatarScale, AvatarOffsetX/Y) |
| `sessions` | Chat-Sessions (Workspace, Context, Telegram, AvatarScale, AvatarOffsetX/Y, AllowedChatIds, ReviewAgentId, MaxReviewIterations, FinalizerAgentId) | | `sessions` | Chat-Sessions (Workspace, Context, Telegram, AvatarScale, AvatarOffsetX/Y, AllowedChatIds, PreparerAgentId, ReviewAgentId, MaxReviewIterations, FinalizerAgentId) |
| `chains` | Ein Request-Response-Zyklus (Tokens, Timing, Iterations) | | `chains` | Ein Request-Response-Zyklus (Tokens, Timing, Iterations, PlanMode) |
| `messages` | Einzelne Nachrichten (text / tool_use / tool_result / error / web_search_result) | | `messages` | Einzelne Nachrichten (text / tool_use / tool_result / error / web_search_result), Tag für Sub-Agent-Markierung |
| `attachments` | Base64-Anhänge (Bilder, Dokumente) | | `attachments` | Base64-Anhänge (Bilder, Dokumente) |
| `archives` | Archivierte Chain-Gruppen | | `archives` | Archivierte Chain-Gruppen |
| `cronjobs` | Geplante Tasks (Cron-Expression + Prompt) | | `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) User-Input → POST /api/chat (SSE)
→ ChatService.BuildContext() → ChatService.BuildContext()
→ History aus DB laden (letzte N Chains) → History aus DB laden (letzte N Chains)
→ SystemPromptBuilder: 12 Blöcke zusammensetzen → SystemPromptBuilder: 14 Blöcke zusammensetzen (+ Plan-Modus/Preparer-Blöcke)
→ Tool-Definitionen vom ToolService holen → 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() → AnthropicService.StreamChat()
→ Claude API Call (SSE) → Claude API Call (SSE)
→ Token-für-Token an Client streamen → Token-für-Token an Client streamen
→ Bei tool_use → ToolService.Execute() → Ergebnis zurück → neuer API Call → 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) → Loop bis end_turn oder max_iterations (100)
→ Bei end_turn + ReviewAgent → Review-Phase: → Bei end_turn + ReviewAgent → Review-Phase:
→ Review-Agent prüft (eigene Tools, max 25 Iterationen) → 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 | | Tool | Funktion |
|------|----------| |------|----------|
@@ -159,6 +164,7 @@ User-Input → POST /api/chat (SSE)
| `memory_read` | Memory-Datei lesen | | `memory_read` | Memory-Datei lesen |
| `memory_write` | Memory-Datei schreiben/appenden | | `memory_write` | Memory-Datei schreiben/appenden |
| `memory_list` | Memory-Dateien auflisten | | `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). **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 1. **Identity** – `IDENTITY.md` des Agents
2. **Soul** – `SOUL.md` des Agents 2. **Soul** – `SOUL.md` des Agents
3. **User** – `USER.md` (globale User-Infos) + Persona 3. **Anweisungen** – `TaskInstruction` des Agents (optional, wenn gesetzt)
4. **Rules** – Verhaltensregeln (Tool-Nutzung, Workspace) 4. **User** – `USER.md` (globale User-Infos) + Persona
5. **Context** – Session-Kontext (custom system prompt) 5. **Rules** – Verhaltensregeln (Tool-Nutzung, Workspace)
6. **Marked Messages** – Als wichtig markierte Nachrichten 6. **Workspace** – Pfad-Info, Tool-Liste
7. **Memory** – Aktueller MEMORY.md-Inhalt 7. **Rückfragen** – Hinweis zu `ask_user_choice` (wenn AllowUserChoice aktiv)
8. **Skills** – Zugeordnete Skill-Prompts 8. **Context** – Session-Kontext (custom system prompt)
9. **Todos** – Aktuelle Todo-Liste 9. **Skills** – Zugeordnete Skill-Prompts
10. **Tools** – Tool-Beschreibungen und -Regeln 10. **Memory** – Aktueller MEMORY.md-Inhalt + Regeln
11. **Workspace** – Pfad-Info, Dateibaum des Workspace 11. **Git** – Commit-Verhalten (wenn AutoCommit konfiguriert)
12. **Date** – Aktuelles Datum/Uhrzeit 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:** **SSE-Events:**
- Preparer: `preparer_start`, `preparer_text`, `preparer_tool_use`, `preparer_done`
- Review: `review_start`, `review_text`, `review_tool_use`, `review_feedback`, `review_approved` - Review: `review_start`, `review_text`, `review_tool_use`, `review_feedback`, `review_approved`
- Finalizer: `finalizer_start`, `finalizer_text`, `finalizer_tool_use`, `finalizer_done` - Finalizer: `finalizer_start`, `finalizer_text`, `finalizer_tool_use`, `finalizer_done`
**Frontend-Rendering:** **Frontend-Rendering:**
- Streaming: `chat.js` rendert Review-/Finalizer-Events als eigene Bubbles (`.review-bubble` / `.finalizer-bubble`) - Streaming: `chat.js` rendert Preparer-/Review-/Finalizer-Events als eigene Bubbles
- History: `renderMarkdown` parst `[Review: AgentName]`, `[Finalizer: AgentName]`, `[Review-Feedback ...]`, filtert `[APPROVED]` - History: `renderMarkdown` parst `[Preparer: AgentName]`, `[Vorbereitet von AgentName]`, `[Review: AgentName]`, `[Finalizer: AgentName]`, filtert `[APPROVED]`, `[FORWARD]`, `[QUESTION]`
- `history.js` + `shared-page.js`: Review-/Finalizer-Nachrichten mit eigenen Bubble-Klassen, kein Merging - Bubble-Klassen: `.preparer-bubble` (Info-Farbe), `.review-bubble` (sekundäre Farbe), `.finalizer-bubble` (grüne Farbe)
**Web-Search Sources:** **Web-Search Sources:**
- `web_search_result`-Messages in DB gespeichert (Sources als JSON-Array, leere werden übersprungen) - `web_search_result`-Messages in DB gespeichert (Sources als JSON-Array, leere werden übersprungen)
README.md
+6 -3
View File
@@ -8,11 +8,14 @@ Self-hosted AI-Coding-Agent auf Basis der Anthropic Claude API. Stellt eine Web-
## Features ## Features
- **Multi-Agent-System** – Mehrere Agenten mit eigenen Identitäten, Persönlichkeiten und Tool-Konfigurationen - **Multi-Agent-System** – Bis zu 4 Agenten pro Session: Worker, Vorbereiter (Preparer), Reviewer, Finalizer
- **Multi-Agent Review** – Optionaler Review-Agent pro Session, der die Arbeit des Worker-Agents prüft und Feedback gibt - **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) - **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 - **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) - **Streaming** – Echtzeit-Antworten via Server-Sent Events (SSE)
- **Stop-Button** – Laufende Requests zuverlässig abbrechen (inkl. laufender Shell-Befehle) - **Stop-Button** – Laufende Requests zuverlässig abbrechen (inkl. laufender Shell-Befehle)
- **Skill-System** – Wiederverwendbare Prompt-Bausteine, zuordenbar pro Agent - **Skill-System** – Wiederverwendbare Prompt-Bausteine, zuordenbar pro Agent