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
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

No files matched your search

+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 |
| `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)