From 9ce210ab0c408edd6d2222e203e65c2bb29f9dcf Mon Sep 17 00:00:00 2001 From: Meleki Date: Mon, 9 Mar 2026 06:40:13 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20tool=5Fchoice=20automatisch,=20System-P?= =?UTF-8?q?rompt-Bl=C3=B6cke=20reduziert,=20History-Limit=20+=20Reminder?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ARCHITECTURE.md + ARCHITECTURE_QUICK.md: - tool_choice aus agents-Tabelle entfernt (nicht mehr konfigurierbar) - Tool-Choice automatisch: any wenn Workspace/Skills/Memory, sonst auto - System-Prompt-Blöcke 14 → 11 (Rules, Verhaltensregeln, Erinnerung entfernt) - History-Limit: max 120 Messages dokumentiert - System-Prompt-Reminder alle ~30 Messages dokumentiert (Lost-in-the-Middle) - SystemPromptBuilder: + Reminder-Generierung - ChatContext: PromptBlocks Property dokumentiert - buildAgentCard: toolChoice-Badge entfernt - Plan-Modus: übersprungene Blöcke aktualisiert --- ARCHITECTURE.md | 46 ++++++++++++++++++++++--------------------- ARCHITECTURE_QUICK.md | 35 ++++++++++++++++---------------- 2 files changed, 42 insertions(+), 39 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 3daf422..d74d8fd 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -285,7 +285,7 @@ TelegramBot (1) ─── (*) Session (via telegram_bot_id) |-------------------|-----------------------------------------------------| | `users` | Benutzer (username, password_hash, display_name, is_admin, persona, settings, default_path) | | `tokens` | Auth-Tokens (token → user_id) | -| `agents` | AI-Agenten (model, tool_choice, custom_commands, auto_commit, use_soul/identity/user_info/memory, use_web_search, web_search_version, allow_user_choice, task_instruction, avatar_scale/offset, avatar_small, is_public) | +| `agents` | AI-Agenten (model, custom_commands, auto_commit, use_soul/identity/user_info/memory, use_web_search, web_search_version, allow_user_choice, task_instruction, avatar_scale/offset, avatar_small, is_public) | | `sessions` | Chat-Sessions (description, image, image_small, workspace, context, custom_commands, telegram_bot_id, telegram_chat_id, avatar_scale/offset, preparer_agent_id, review_agent_id, max_review_iterations, finalizer_agent_id) | | `chains` | Request-Chains (model, tokens, iterations, timing, tool_choice, tool_names, stream_error_info, plan_mode, archive_id) | | `messages` | Einzelne Nachrichten (text, tool_use, tool_result, error, web_search_result), Tag für Sub-Agent-Markierung oder Import-Herkunft (`openclaw-import`), SortKey für korrekte Reihenfolge | @@ -307,7 +307,7 @@ TelegramBot (1) ─── (*) Session (via telegram_bot_id) - `InputTokens`, `OutputTokens`, `CacheCreationTokens`, `CacheReadTokens` – Token-Verbrauch - `Iterations` – Anzahl der Tool-Loop-Durchläufe - `StopReason` – `end_turn`, `tool_use`, `max_iterations`, `error`, `client_disconnected`, `awaiting_user_choice`, `preparer_query` -- `ToolChoice` – Verwendete Tool-Choice-Strategie +- `ToolChoice` – Verwendete Tool-Choice-Strategie (automatisch: `any` wenn Workspace/Skills/Memory, sonst `auto`) - `ToolNames` – Komma-separierte Liste der verwendeten Tools - `ArchiveId` – Zugehöriges Archiv (wenn archiviert) - `StreamErrorInfo` – Fehlerdetails bei Stream-Abbrüchen @@ -371,7 +371,7 @@ AuthService → DatabaseService → EnsureDefaultUser | `AnthropicService` | Singleton | Claude API Kommunikation (Streaming SSE + Non-Streaming) | | `ToolService` | Singleton | Tool-Definitionen bereitstellen, Tool-Aufrufe ausführen | | `WorkspaceHelper` | Static | Workspace-Pfad-Auflösung (relativ → absolut), Path-Traversal-Schutz | -| `SystemPromptBuilder` | Static | Modularer System-Prompt aus konfigurierbaren Blöcken | +| `SystemPromptBuilder` | Static | Modularer System-Prompt aus konfigurierbaren Blöcken + Reminder-Generierung | | `MemoryService` | Singleton | Agent-Gedächtnis auf Dateisystem (MEMORY.md, IDENTITY.md etc.) | | `SkillService` | Singleton | Skill-Discovery und -Management aus Dateisystem | | `TelegramService` | Singleton | Telegram Bot API, Webhook-Handling, Nachrichten senden | @@ -429,7 +429,8 @@ Die Models in `Models/` sind reine Daten-Records ohne Business-Logic (Ausnahme: **ChatContext** ist ein Runtime-Objekt das den vollständigen Kontext eines Chat-Requests hält: - Chain-ID, Session-ID, Model-ID - Aufgelöster System-Prompt (Text + strukturierte Blöcke) -- Workspace-Pfad, Tool-Choice +- Workspace-Pfad, Tool-Choice (automatisch bestimmt) +- Prompt-Blöcke (`PromptBlocks`) – für Reminder-Generierung in der History - Referenzen auf Agent und Session Records ### Templates @@ -489,7 +490,7 @@ Das Frontend ist eine **Single-Page Application** ohne Build-Step, komplett in V ### Wiederverwendbare Card-Builder (cards.js) -- **`buildAgentCard(agent)`** – Erzeugt ein `.card` DOM-Element für einen Agent (Avatar, Name, Model-Badge, Feature-Badges: toolChoice, autoCommit, useSoul, useIdentity, useUserInfo, useMemory, webSearch, Skills, Public/Fremd). Skills werden inline vom API-Endpunkt mitgeliefert. Wird im Dashboard und im Agent-Picker-Modal (Session-Formular) verwendet. +- **`buildAgentCard(agent)`** – Erzeugt ein `.card` DOM-Element für einen Agent (Avatar, Name, Model-Badge, Feature-Badges: autoCommit, useSoul, useIdentity, useUserInfo, useMemory, webSearch, Skills, Public/Fremd). Skills werden inline vom API-Endpunkt mitgeliefert. Wird im Dashboard und im Agent-Picker-Modal (Session-Formular) verwendet. - **`buildSessionCard(session, agent)`** – Erzeugt ein `.card` DOM-Element für eine Session (Avatar, Name, Badges: Agent, Kontext, Telegram, Meta: Nachrichten/Archiv/Workspace, Git-Status). Git-Status wird inline vom API-Endpunkt mitgeliefert. Wird im Dashboard und im Session-Picker-Modal (Cronjob-Formular) verwendet. - **`buildTelegramBotCard(bot)`** – Erzeugt ein `.card` DOM-Element für einen Telegram Bot (Name, maskierter Token, Session-Count, Public/Fremd-Badges). Wird im Dashboard und im Bot-Picker-Modal (Session-Formular) verwendet. - **Picker-Modals** – Agent- und Session-Auswahl in Formularen (Session-/Cronjob-Seiten) erfolgt über modale Dialoge mit den Card-Buildern statt über Dropdowns. @@ -595,10 +596,12 @@ Der Stop-Mechanismus arbeitet auf zwei Ebenen: Die History-Rekonstruktion in `BuildHistoryFromDb()` ist optimiert: +- **Max 120 Messages**: Die History wird auf maximal 120 Messages begrenzt (älteste entfernt) - **Ältere Chains**: Nur `text`-Messages (user + assistant), keine Tool-Calls - **Letzte Chain**: Vollständig mit allen Tool-Use/Tool-Result Blöcken - **Attachments**: Nur für die letzte User-Message geladen (spart enorme Token) - **Tool-Results**: In der History auf 20.000 Zeichen gekürzt (vollständig in DB) +- **System-Prompt-Reminder**: Alle ~30 Messages wird ein automatisch generierter Reminder als User/Assistant-Paar injiziert (z.B. `[System Reminder] Beachte weiterhin den System-Prompt (Identity, Workspace, Kontext, Memory, ...)`). Bekämpft das "Lost-in-the-Middle"-Problem bei langen Konversationen. Der Reminder-Text wird aus den aktiven Prompt-Block-Labels generiert (`SystemPromptBuilder.BuildReminder()`). Nur aktiv wenn ≥2 Blöcke vorhanden. --- @@ -644,10 +647,13 @@ Nutzt Anthropics eingebaute Web-Suche als Server-Side-Tool. 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 (automatisch) -- **`any`**: Erste Iteration erzwingt Tool-Nutzung, danach `auto`. Verhindert dass der Agent nur Text antwortet wenn Tools benötigt werden. -- **`auto`**: Claude entscheidet frei ob Tools nötig sind. +Die Tool-Choice-Strategie wird automatisch bestimmt (nicht konfigurierbar pro Agent): + +- **`any`**: Automatisch wenn Workspace, Skills oder Memory vorhanden. Erste Iteration erzwingt Tool-Nutzung, danach `auto`. Verhindert dass der Agent nur Text antwortet wenn Tools benötigt werden. +- **`auto`**: Wenn keine Tools verfügbar. Claude entscheidet frei. +- **`none`**: Im `/no-tools`-Modus. ### Pfad-Sicherheit @@ -664,7 +670,6 @@ Ein **Agent** definiert die Persönlichkeit und Fähigkeiten der AI: | `Name` | Anzeigename | | `Avatar` | Base64 Data-URL (WebP, 512px) + `AvatarSmall` (WebP, 256px Thumbnail) | | `Model` | `sonnet`, `sonnet-4-5`, `sonnet-4-6`, `opus`, `opus-4-5`, `opus-4-6`, `haiku`, `haiku-4-5` | -| `ToolChoice` | `any` oder `auto` | | `CustomCommands` | JSON-Array mit Slash-Commands (Label + Prompt) | | `AutoCommit` | `""` (nichts), `"mention"` (anmerken – nur auf User-Request), `"enforce"` (erzwingen – nach jeder Änderung), `"forbid"` (strikt verboten) | | `UseSoul` | SOUL.md in System-Prompt einbinden | @@ -702,17 +707,14 @@ Der `SystemPromptBuilder` erzeugt den System-Prompt modular aus konfigurierbaren │ 2. SOUL.md (UseSoul) │ → Persönlichkeit, Verhalten │ 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) +│ 5. Workspace-Info │ → Tools + Workspace-Pfad +│ 6. Rückfragen (AllowUserChoice) │ → Hinweis zu ask_user_choice Tool +│ 7. Session-Kontext │ → Freiformtext +│ 8. Skills (Agent-Skills) │ → Skill-Prompts +│ 9. Memory (UseMemory) │ → Memory-Regeln + MEMORY.md Inhalt +│10. Git-Verhalten (AutoCommit) │ → Commit-Regeln +│11. Markierte Nachrichten │ → Vom User als wichtig markierte Messages +│ [Plan-Modus-Block] │ → Nur wenn planMode=true (überspringt 10) │ [Preparer-Instruktionsblock] │ → Nur für Preparer-Agents └──────────────────────────────────────────┘ ``` @@ -1278,12 +1280,12 @@ Der Plan-Modus ist ein **Read-only-Betriebsmodus**, in dem der Agent den Code an |--------|--------|-----------| | **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) | +| **toolChoice** | `"any"` (automatisch wenn Workspace/Skills/Memory) | 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. +Folgende Blöcke werden **übersprungen**: Git-Commits. Der Tools-Block listet nur Read-only-Tools auf. Skills werden als "nur zur Kenntnis, nicht ausführbar" markiert. ### Frontend diff --git a/ARCHITECTURE_QUICK.md b/ARCHITECTURE_QUICK.md index c1acdeb..6676582 100644 --- a/ARCHITECTURE_QUICK.md +++ b/ARCHITECTURE_QUICK.md @@ -66,7 +66,7 @@ User 1──* TelegramBot 1──* Session (via telegram_bot_id) |---------|-------| | `users` | Login, DisplayName, IsAdmin, Persona, Settings (JSON), DefaultPath | | `tokens` | Auth-Tokens → User | -| `agents` | AI-Agenten (Model, ToolChoice, CustomCommands, AutoCommit, UseSoul/Identity/UserInfo/Memory, WebSearch, AllowUserChoice, TaskInstruction, AvatarScale/Offset, AvatarSmall, IsPublic) | +| `agents` | AI-Agenten (Model, CustomCommands, AutoCommit, UseSoul/Identity/UserInfo/Memory, WebSearch, AllowUserChoice, TaskInstruction, AvatarScale/Offset, AvatarSmall, IsPublic) | | `sessions` | Chat-Sessions (Description, Image, ImageSmall, Workspace, Context, CustomCommands, TelegramBotId, TelegramChatId, AvatarScale/Offset, PreparerAgentId, ReviewAgentId, MaxReviewIterations, FinalizerAgentId) | | `chains` | Ein Request-Response-Zyklus (Tokens, Timing, Iterations, PlanMode, ToolChoice, ToolNames, StreamErrorInfo, ArchiveId) | | `messages` | Einzelne Nachrichten (text / tool_use / tool_result / error / web_search_result), Tag für Sub-Agent-Markierung oder Import-Herkunft (`openclaw-import`) | @@ -114,7 +114,7 @@ User 1──* TelegramBot 1──* Session (via telegram_bot_id) | **AnthropicService** | Claude API: SSE Streaming + Non-Streaming | | **ToolService** | Tool-Definitionen + Ausführung (13 Tools) | | **WorkspaceHelper** | Workspace-Pfad-Auflösung (relativ → absolut), Path-Traversal-Schutz (static) | -| **SystemPromptBuilder** | System-Prompt aus modularen Blöcken zusammenbauen (static) | +| **SystemPromptBuilder** | System-Prompt aus modularen Blöcken zusammenbauen + Reminder-Generierung (static) | | **MemoryService** | Agent-Gedächtnis auf Dateisystem | | **SkillService** | Skill-Discovery aus Dateisystem | | **TelegramService** | Telegram Bot API (Bot-basiert, Multi-Session-Routing) | @@ -131,7 +131,7 @@ User 1──* TelegramBot 1──* Session (via telegram_bot_id) User-Input → POST /api/chat (SSE) → ChatService.BuildContext() → History aus DB laden (letzte N Chains) - → SystemPromptBuilder: 14 Blöcke zusammensetzen (+ Plan-Modus/Preparer-Blöcke) + → SystemPromptBuilder: 11 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") @@ -155,7 +155,7 @@ User-Input → POST /api/chat (SSE) → Chain + Messages in DB speichern ``` -**History-Optimierung:** Ältere Chains nur Text-Messages (keine Tool-Calls). Letzte Chain vollständig. Tool-Results auf 20.000 Zeichen gekürzt. Attachments nur für letzte User-Message. +**History-Optimierung:** Max 120 Messages. Ältere Chains nur Text-Messages (keine Tool-Calls). Letzte Chain vollständig. Tool-Results auf 20.000 Zeichen gekürzt. Attachments nur für letzte User-Message. System-Prompt-Reminder alle ~30 Messages. **Rendering:** Markdown via marked.js + LaTeX via KaTeX (`$$...$$` Block, `$...$` Inline). Timestamps im Format `dd.MM.yyyy HH:mm:ss` on hover. @@ -181,29 +181,30 @@ User-Input → POST /api/chat (SSE) **Sicherheit:** Alle Pfade werden auf das Workspace-Verzeichnis beschränkt (`..` wird blockiert). Tools sind pro Agent konfigurierbar (Feld `tools` als komma-separierte Liste). -**Tool-Choice:** Standard `auto`. Wird zu `none` bei `/no-tools`. Einzelne Tools forcierbar via `/tool:toolname`. +**Tool-Choice:** Automatisch `any` wenn Workspace/Skills/Memory vorhanden, sonst `auto`. Wird zu `none` bei `/no-tools`. Einzelne Tools forcierbar via `/tool:toolname`. --- -## System-Prompt (14+ Blöcke, in Reihenfolge) +## System-Prompt (11+ Blöcke, in Reihenfolge) 1. **Identity** – `IDENTITY.md` des Agents 2. **Soul** – `SOUL.md` des Agents 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" +5. **Workspace** – Pfad-Info, Tool-Liste +6. **Rückfragen** – Hinweis zu `ask_user_choice` (wenn AllowUserChoice aktiv) +7. **Context** – Session-Kontext (custom system prompt) +8. **Skills** – Zugeordnete Skill-Prompts +9. **Memory** – Aktueller MEMORY.md-Inhalt + Regeln +10. **Git** – Commit-Verhalten (wenn AutoCommit konfiguriert) +11. **Markierte Nachrichten** – Vom User als wichtig markiert +- **[Plan-Modus]** – Überspringt 10; Read-only Tools; "Nur analysieren" - **[Preparer-Block]** – Instruktionen für Vorbereiter-Agents +**Tool-Choice:** Automatisch `any` wenn Workspace/Skills/Memory vorhanden, sonst `auto`. Nicht konfigurierbar pro Agent. + +**History-Reminder:** Alle ~30 Messages wird ein automatisch generierter Reminder injiziert (`[System Reminder] Beachte weiterhin den System-Prompt (...)`) – bekämpft "Lost-in-the-Middle"-Problem. + --- ## Frontend-Routing