docs: Architektur-Doku auf aktuellen Stand bringen

Aktualisiert ARCHITECTURE.md, ARCHITECTURE_QUICK.md und README.md für die letzten Feature-Commits: - Auto-Context: SSE-Event, DB-Persistierung (auto_context-Message), History-Filter, Implementierung in Streaming + CLI - Model-Auflösung: Opus 4.7 + [1m]-Varianten (1M Context) - Krea: 5 neue Bildmodelle + MINIMAL_MODELS-Hinweis - Remote: remote.sh (Linux/macOS, embedded Python), OS-aware Tool-Description (PowerShell vs. Bash), Hinweis dass Cronjobs/Telegram remoteOs aktuell nicht durchreichen - CLI-Integration: Sub-Agent-Fallback (Preparer/Review/Finalizer), Python-Detection (python3 -> python -> py) - Workspace: native Pfade (Windows \\, Linux /), Drives-Übersicht - Frontend: addAutoContextBubble() in stream-ui.js - MaxHistory Default 220 (statt 120) - 🪟 -> 🗂️ in QUICK (Unicode-Kompatibilität) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-25 17:02:58 +02:00
1 parent 52ab6ff00c
commit ac1c730f07
@@ -350,7 +350,7 @@ TelegramBot (1) ─── (*) Session  (via telegram_bot_id)
 | `agents`          | AI-Agenten (model – z.B. `claude-sonnet-4-6` oder `nvidia:deepseek-ai/deepseek-r1`, custom_commands, auto_commit, use_soul/identity/user_info/memory/auto_context, use_github_search, use_serper_search, 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, thought_signature (Gemini) |
+| `messages`        | Einzelne Nachrichten (text, tool_use, tool_result, error, web_search_result, auto_context), Tag für Sub-Agent-Markierung oder Import-Herkunft (`openclaw-import`), SortKey für korrekte Reihenfolge, thought_signature (Gemini) |
 | `attachments`     | Datei-Anhänge (base64, image/document)              |
 | `archives`        | Archivierte Chain-Gruppen                           |
 | `agent_skills`    | Agent ↔ Skill Zuordnung                             |
@@ -384,8 +384,8 @@ TelegramBot (1) ─── (*) Session  (via telegram_bot_id)
 - `DurationMs` – Gesamtdauer der Chain

 **MessageRecord** – Eine einzelne Nachricht innerhalb einer Chain:
- `Role` – `user`, `assistant`
- `Type` – `text`, `tool_use`, `tool_result`, `error`, `web_search_result`
+- `Role` – `user`, `assistant`, `system` (für `auto_context`)
+- `Type` – `text`, `tool_use`, `tool_result`, `error`, `web_search_result`, `auto_context`
 - `Content` – Textinhalt oder JSON (bei tool_use: Input-JSON)
 - `ToolName`, `ToolCallId` – Bei Tool-Aufrufen
 - `IsError` – Ob die Nachricht ein Fehler ist
@@ -573,7 +573,7 @@ Das Frontend ist eine **Single-Page Application** ohne Build-Step, komplett in V
 - **msg-actions.js** – Nachrichten-Aktionen (Delete, Mark, Share, Reply-Button, Timestamp)
 - **tool-ui.js** – Tool-Boxes (Diffs, Todos, File-Content), Visibility-Logik
 - **modals.js** – Modale Dialoge (System-Prompt, Command-Output, Krea-Image)
- **stream-ui.js** – Stream-Bubble, Review-Streaming-Rendering
+- **stream-ui.js** – Stream-Bubble, Review-Streaming-Rendering, `addAutoContextBubble()` für Auto-Context-Box
 - **bubbles.js** – Message Bubbles (User, Assistant, Error, Warning, Choice, Review, Attachments)
 - **chat.js** – SSE-Stream-Handling, sendMessage, Plan-Mode
 - **history.js** – Chat-History laden, paginieren, rendern, Polling
@@ -732,13 +732,29 @@ 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)
+- **Max 220 Messages** (`MaxHistory`-Setting, konfigurierbar): Die History wird auf maximal N 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.

+### Auto-Context (Vector-Search)
+
+Wenn am Agent `UseAutoContext` aktiv ist, wird **vor** jedem Request über `VectorSearchService` ein semantisch passender Kontext zur aktuellen User-Anfrage gesucht (aus früheren Chat-Nachrichten + Memory-Files). Der Kontext wird als `<recalled_context>`-Block in den System-Prompt injiziert.
+
+**Header-Anweisung:** Der Block hat eine bewusst direkte Anweisung an das Model:
+
+> *"WICHTIG: Der folgende Kontext wurde automatisch per Vektor-Suche aus früheren Gesprächen und Memory abgerufen. Prüfe diesen Kontext ZUERST, bevor du antwortest. Wenn er zur aktuellen Frage passt, beziehe dich aktiv darauf und nutze die Informationen in deiner Antwort. Ignoriere ihn nur, wenn er eindeutig irrelevant ist."*
+
+Die starke Formulierung verhindert, dass das Model den Kontext ignoriert (Default = Nutzung statt Ignorieren).
+
+**SSE-Event:** Der Auto-Context wird zusätzlich als `auto_context`-SSE-Event vor dem Streaming an das Frontend gesendet, damit der User sieht, was der Agent als Kontext bekommen hat (aufklappbare **Auto-Context-Box** im Chat).
+
+**DB-Persistierung:** Der Block wird auch als Message in der DB gespeichert (`Role = "system"`, `Type = "auto_context"`), damit er beim Laden der History sichtbar bleibt. `BuildHistoryFromDb` filtert `auto_context`-Messages explizit, sie werden also **nicht** an die API zurückgesendet.
+
+**Implementierung:** Sowohl `AnthropicService.Streaming.StreamChat()` als auch `AnthropicService.Cli.StreamChatViaCli()` rufen `BuildAutoContextAsync()` auf, senden das SSE-Event und persistieren die Message – damit funktioniert die Anzeige sowohl im API-Streaming-Pfad als auch im CLI-Pfad.
+
 ---

 ## Tool-System
@@ -843,17 +859,25 @@ Ein **Agent** definiert die Persönlichkeit und Fähigkeiten der AI:
 ### Model-Auflösung

 ```
-"sonnet"     → claude-sonnet-4-6
-"sonnet-4-5" → claude-sonnet-4-5
-"sonnet-4-6" → claude-sonnet-4-6
-"opus"       → claude-opus-4-6
-"opus-4-5"   → claude-opus-4-5
-"opus-4-6"   → claude-opus-4-6
-"haiku"      → claude-haiku-4-5
-"haiku-4-5"  → claude-haiku-4-5
-(default)    → claude-sonnet-4-6
+"sonnet"          → claude-sonnet-4-6
+"sonnet[1m]"      → claude-sonnet-4-6[1m]   (1M Context)
+"sonnet-4-5"      → claude-sonnet-4-5
+"sonnet-4-6"      → claude-sonnet-4-6
+"sonnet-4-6[1m]"  → claude-sonnet-4-6[1m]
+"opus"            → claude-opus-4-7
+"opus[1m]"        → claude-opus-4-7[1m]     (1M Context)
+"opus-4-5"        → claude-opus-4-5
+"opus-4-6"        → claude-opus-4-6
+"opus-4-6[1m]"    → claude-opus-4-6[1m]
+"opus-4-7"        → claude-opus-4-7
+"opus-4-7[1m]"    → claude-opus-4-7[1m]
+"haiku"           → claude-haiku-4-5
+"haiku-4-5"       → claude-haiku-4-5
+(default)         → claude-sonnet-4-6
 ```

+Das `[1m]`-Suffix aktiviert das **1-Million-Token-Context-Fenster** (Anthropic Beta-Feature, längere History/größere Codebases möglich).
+
 ---

 ## System-Prompt-Aufbau
@@ -1052,11 +1076,16 @@ Die `KreaService` ermöglicht Bildgenerierung über die Krea API.

 ```
 flux, flux-kontext, flux-1.1-pro, flux-1.1-pro-ultra,
-nano-banana, nano-banana-pro, imagen-3, imagen-4, imagen-4-fast, imagen-4-ultra,
-ideogram-2-turbo, ideogram-3, seedream-3, seedream-4,
+nano-banana, nano-banana-pro, nano-banana-2,
+imagen-3, imagen-4, imagen-4-fast, imagen-4-ultra,
+ideogram-2-turbo, ideogram-3,
+seedream-3, seedream-4, seedream-5-lite, seededit,
+z-image, qwen-2512,
 chatgpt-image, runway-gen-4
 ```

+Modelle in `MINIMAL_MODELS` (`seedream-3`, `runway-gen-4`, `seedream-5-lite`, `seededit`) unterstützen kein `width`/`height`/`steps`/`guidance` und werden nur mit Prompt aufgerufen.
+
 ### Flow

 ```
@@ -1351,8 +1380,10 @@ Der Finalizer wird **nach** dem Review (oder direkt nach dem Worker, falls kein

 3. **RunFinalizer()** – Baut Messages auf (gesamte Konversation + Finalisierungs-Anweisung), Provider-Weiche wie bei RunPreparer/RunReview

-4. **RunAgentChat()** / **ChatNonStreaming()** – Provider-Weiche für Preparer/Review/Finalizer:
-   - **Anthropic:** Eigener API-Call an Claude mit Agent-Config (RunAgentChat, Streaming + Tool-Loop)
+4. **RunAgentChat()** / **ChatNonStreaming()** / **RunSubAgentViaCli()** – Provider-Weiche für Preparer/Review/Finalizer:
+   - **Anthropic mit API-Key:** Eigener API-Call an Claude mit Agent-Config (RunAgentChat, Streaming + Tool-Loop)
+   - **Anthropic ohne API-Key + CLI verfügbar:** `RunSubAgentViaCli()` – nutzt `ClaudeCliService.ChatStreamingAsync()`, sammelt Text, sendet identische SSE-Events (`{type}_text`, `{type}_tool_use`, `{type}_done`) und persistiert die Message mit `Tag = agentType`
+   - **Anthropic ohne API-Key + ohne CLI:** Sub-Agent wird übersprungen (kein Hard-Error)
   - **OpenAI-kompatibel:** `OpenAiService.ChatNonStreaming()` (Non-Streaming agentic loop mit Tool-Calling)
   - Tool-Loop mit SSE-Events (`{type}_text`, `{type}_tool_use`)
   - Antwort als Message in DB persistieren (mit `Tag = agentType`, wird aus API-History gefiltert)
@@ -1581,6 +1612,10 @@ Eine Session kann einen **Workspace-Pfad** haben. Dieser wird **relativ** zum `D

 `bin`, `obj`, `node_modules`, `.git`, `.vs`, `.idea`, `publish`, `dist`, `out`, `build`, `target`, `.cache`

+### Native Pfade (Windows vs. Linux)
+
+`WorkspaceHelper.GetRelativePath()` und `WorkspaceEndpoint.HandleBrowse()` liefern **native Pfade** zurück (Windows: `\`, Linux/macOS: `/`). Das Frontend (`file-explorer.js`) unterstützt beide Separatoren über Regex-Patterns wie `[\\/]+$`. Auf Windows kann von `C:\` aus zur Laufwerksübersicht (`""` = leerer Pfad) navigiert werden.
+
 ### Session-Exec

 `POST /api/sessions/{id}/exec` führt Shell-Befehle im Workspace aus:
@@ -1743,10 +1778,22 @@ Remote-Clients (z.B. Windows-PCs) können sich via **WebSocket** mit dem Server

 ### Verbindungsaufbau

-1. Remote-Client führt `irm https://server/remote | iex` aus → lädt `remote.ps1`
-2. Script baut WebSocket-Verbindung zu `/api/remote` auf
-3. Sendet `hello`-Message mit Hostname, Username, OS-Version
-4. `RemoteConnectionManager` registriert die Verbindung
+**Windows (PowerShell):**
+```powershell
+irm https://server/remote.ps1 | iex
+```
+
+**Linux/macOS (Bash):**
+```bash
+curl -s https://server/remote.sh | bash
+```
+
+Beide Scripts werden über den `RemoteEndpoint` ausgeliefert, wobei der `{{WS_URL}}`-Platzhalter beim Request mit der korrekten WebSocket-URL ersetzt wird. Das Bash-Script enthält einen embedded Python WebSocket-Client (RFC 6455) und sucht automatisch `python3` → `python` → `py`.
+
+1. Remote-Client lädt das Script und baut WebSocket-Verbindung zu `/api/remote` auf
+2. Sendet `hello`-Message mit Hostname, Username, OS-Version
+3. `RemoteConnectionManager` registriert die Verbindung
+4. Modal-UI auf Dashboard / Chat zeigt beide Befehle (Windows + Linux/macOS)

 ### Session-Zuweisung

@@ -1755,6 +1802,15 @@ Remote-Clients (z.B. Windows-PCs) können sich via **WebSocket** mit dem Server
 - AI-Agent bekommt `remote_execute`-Tool → führt Befehle auf dem Remote-Client aus
 - Ergebnis wird synchron via WebSocket zurückgeliefert (Timeout: konfigurierbarer `ExecuteTimeout`)

+### OS-aware Tool-Description
+
+Das `remote_execute`-Tool (sowohl im internen ToolService als auch im MCP-Server) bekommt eine **dynamische Tool-Description** basierend auf dem OS des verbundenen Remote-Clients:
+
+- **Linux:** *"Bash-Befehl auf der verbundenen Remote-Linux-Workstation ausführen"*
+- **Windows:** *"PowerShell-Befehl auf der verbundenen Remote-Windows-Workstation ausführen"*
+
+Das OS wird aus der `hello`-Message des Clients (`RemoteConnection.OsVersion`) bezogen und über `ChatEndpoint` → `ChatService.PrepareContext(remoteOs)` → `ToolPayloadOptions.RemoteOs` → `ToolDefinitionOptions.RemoteOs` bis zu `ToolService.GetRemoteExecuteTool(remoteOs)` durchgereicht. Im CLI-Pfad zusätzlich an die MCP-Config (`GenerateMcpConfig(remoteOs)`) und von dort als Env-Variable `GOTT_REMOTE_OS` an den Python-MCP-Server. Damit generiert Claude direkt passende Befehle für die jeweilige Shell. Cronjobs/Telegram-Bots rufen `PrepareContext` aktuell ohne `remoteOs` auf (Default = leer → PowerShell-Description als Fallback).
+
 ### Protokoll (JSON über WebSocket)

 | Richtung | Type | Payload |
@@ -1932,6 +1988,14 @@ Die Claude Code CLI kann als alternativer Streaming-Weg verwendet werden (OAuth-
 - Claude Code CLI installiert (`~/.claude/local/claude`)
 - Gültiges OAuth-Token in `~/.claude/.credentials.json`

+### CLI-Fallback für Sub-Agents
+
+Wenn ein **Sub-Agent** (Preparer, Review, Finalizer) keinem API-Key zugewiesen ist, wird – sofern die CLI verfügbar ist – automatisch `RunSubAgentViaCli()` (in `AnthropicService.Agents.cs`) aufgerufen. Damit funktionieren optionale Sub-Agents auch ohne explizit zugewiesenen Anthropic-Key. Erst wenn weder Key noch CLI vorhanden sind, wird der Sub-Agent übersprungen statt mit einem Hard-Error abzubrechen.
+
+### Python-Detection für MCP-Config
+
+Die MCP-Config (`AnthropicService.Cli.GenerateMcpConfig()`) sucht beim Start dynamisch nach einer Python-Installation in der Reihenfolge `python3` → `python` → `py` (das Ergebnis wird gecached). Auf Linux ist üblicherweise `python3` da, auf Windows oft nur `python` oder `py`. Wird kein Python gefunden, wird im Chat ein SSE-`warning`-Event gesendet (*"Python wurde nicht gefunden... MCP-Tools sind nicht verfügbar."*) – die normalen Tools funktionieren weiterhin.
+
 ---

 ## Datenbank-Explorer