Initial commit: ClawdDotNet

Import des bestehenden Projektstands in Git. - .NET 10 WinForms Anwendung (Multi-Agent / Tool-System) - .gitignore fuer Build-Artefakte, Secrets und Runtime-Daten ergaenzt Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-26 18:21:46 +02:00
commit 2fed388c99
154 changed files with 29736 additions and 0 deletions
@@ -0,0 +1,503 @@
+# ClawdDotNet – Instanz-Setup-Guide
+
+Anleitung für die vollständige Planung, Erstellung und Konfiguration einer neuen ClawdDotNet-Instanz. Richtet sich an menschliche Nutzer und AI-Agenten gleichermaßen.
+
+---
+
+## 1. Planung: Was soll die Instanz leisten?
+
+Bevor eine Instanz erstellt wird, muss klar definiert werden:
+
+| Frage | Beispiel |
+|-------|---------|
+| Welche Aufgabe(n) soll die Instanz als Ganzes erledigen? | "Social-Media-Monitoring mit automatischer Zusammenfassung" |
+| Wie viele Agenten werden benötigt? | 1–5 (mehr = höhere Koordinationskosten) |
+| Welche externen Systeme sind beteiligt? | Telegram, E-Mail, Datenbank, APIs |
+| Wie hoch ist das Token-Budget pro Tag? | z.B. $1/Tag, $10/Tag |
+| Soll die Instanz autonom arbeiten oder manuell getriggert werden? | Cron-Jobs vs. manueller Start |
+
+### Agentenanzahl richtig wählen
+
+| Szenario | Empfehlung |
+|----------|-----------|
+| Eine klar abgegrenzte Aufgabe | 1 Agent |
+| Aufgabe mit getrennten Zuständigkeiten (z.B. Recherche + Bericht) | 2–3 Agenten |
+| Komplexes System mit Koordination | 3–5 Agenten, davon 1 Koordinator |
+| Mehr als 5 Agenten | Kritisch hinterfragen — Koordinationsoverhead steigt quadratisch |
+
+**Faustregel:** Jeder Agent, der mit einem anderen kommuniziert, kostet Token auf beiden Seiten. Zwei Agenten, die jeweils 3 Nachrichten austauschen = 6 LLM-Runs.
+
+---
+
+## 2. Verzeichnisstruktur einer Instanz
+
+Eine Instanz hat folgende Struktur. `CreateInstance()` und `CreateAgent()` im InstanceDirectoryManager erzeugen diese automatisch.
+
+```
+Instance-{Name}/
+├── InstanceSettings.json          ← Instanz-Konfiguration + API-Key
+├── TokenUsage.json                ← Verbrauchsprotokoll (leer bei Start)
+├── state.db                       ← SQLite StateStore (wird zur Laufzeit erzeugt)
+└── Agents/
+    ├── AgentList.json             ← Agenten-Register (Name, Beschreibung, Ordner)
+    ├── SharedWorkspace/           ← Geteilter Arbeitsbereich
+    │   └── coordination/          ← Status-Dateien für Inter-Agenten-Kommunikation
+    └── Agent-{Name}/
+        ├── AgentSettings.json     ← Agent-Konfiguration (Modell, Tools, Scheduler)
+        ├── Identity.md            ← WER ist der Agent (Rolle, Expertise)
+        ├── Soul.md                ← WIE arbeitet der Agent (Persönlichkeit, Methodik)
+        ├── ChatContext.json       ← Aktueller Konversationskontext
+        ├── ChatHistory.json       ← Vollständiger Chatverlauf
+        ├── Logs/                  ← Agent-spezifische Logs
+        └── Workspace/             ← Persönlicher Arbeitsbereich
+```
+
+---
+
+## 3. Schritt-für-Schritt: Instanz erstellen
+
+### 3.1 Instanz anlegen
+
+Über die UI: **Instanz-Manager → Neue Instanz erstellen**
+
+Oder manuell die Ordnerstruktur erzeugen. Die `InstanceSettings.json` hat dieses Format:
+
+```json
+{
+  "instanceId": "<8-Zeichen-GUID>",
+  "instanceName": "MeinProjekt",
+  "openRouterApiKey": "",
+  "workingDirectory": "",
+  "logDirectory": "./Logs",
+  "webServerPort": 8080,
+  "agents": [],
+  "services": []
+}
+```
+
+**Wichtig:** Der `openRouterApiKey` muss gesetzt werden, bevor Agenten funktionieren.
+
+### 3.2 Agenten anlegen
+
+Pro Agent wird ein Ordner `Agent-{Name}` unter `Agents/` erstellt.
+
+**AgentList.json** — Register aller Agenten:
+
+```json
+{
+  "agents": [
+    {
+      "name": "Analyst",
+      "description": "Recherchiert und analysiert Daten aus externen Quellen",
+      "folderName": "Agent-Analyst"
+    },
+    {
+      "name": "Reporter",
+      "description": "Erstellt Berichte und versendet sie per E-Mail",
+      "folderName": "Agent-Reporter"
+    }
+  ]
+}
+```
+
+### 3.3 AgentSettings.json
+
+Jeder Agent bekommt eine `AgentSettings.json`:
+
+```json
+{
+  "agentId": "analyst",
+  "displayName": "Analyst",
+  "model": "google/gemini-2.5-flash",
+  "systemPrompt": "",
+  "tools": {
+    "WebFetch": {
+      "allowedDomains": ["example.com", "api.example.com"]
+    },
+    "FileRW": {
+      "sharedAccessLevel": "ReadWrite",
+      "personalAllowedExtensions": [".txt", ".json", ".md", ".csv"],
+      "sharedAllowedExtensions": [".txt", ".json", ".md"]
+    }
+  },
+  "scheduler": {
+    "cron": "0 8 * * 1-5",
+    "runOnStart": false,
+    "taskMessage": "Recherchiere die neuesten Daten und speichere sie im SharedWorkspace."
+  },
+  "toolJobs": [],
+  "loopGuard": {
+    "maxSteps": 15,
+    "maxTokens": 50000,
+    "timeoutSeconds": 300,
+    "maxContextTokens": 100000,
+    "compactionThreshold": 0.8
+  }
+}
+```
+
+### 3.4 Identity.md schreiben
+
+Definiert **WER** der Agent ist. Kurz, prägnant, rollenspezifisch.
+
+```markdown
+# Analyst
+
+Du bist ein Datenanalyst im ClawdDotNet-Team "MeinProjekt".
+
+## Rolle
+- Recherche und Aufbereitung externer Daten
+- Ergebnisse im SharedWorkspace als JSON ablegen
+
+## Expertise
+- Web-Recherche, Datenextraktion, strukturierte Zusammenfassungen
+
+## Kontext
+- Deine Ergebnisse werden vom Reporter-Agenten weiterverarbeitet
+- Lege Dateien im SharedWorkspace unter coordination/ ab
+```
+
+### 3.5 Soul.md schreiben
+
+Definiert **WIE** der Agent arbeitet.
+
+```markdown
+# Arbeitsweise
+
+## Persönlichkeit
+- Gründlich und faktenbasiert
+- Komprimiert Informationen auf das Wesentliche
+
+## Methodik
+1. Quellen prüfen und Daten abrufen
+2. Relevante Informationen extrahieren
+3. Strukturiertes JSON erstellen
+4. Im SharedWorkspace ablegen
+
+## Ausgabeformat
+- Ergebnisse immer als JSON mit Timestamp
+- Keine Prosa, nur strukturierte Daten
+```
+
+---
+
+## 4. Modellwahl: Kosten vs. Leistung
+
+Die Modellwahl hat den größten Einfluss auf die laufenden Kosten. Nicht jeder Agent braucht das teuerste Modell.
+
+### Modell-Empfehlungen nach Aufgabentyp
+
+| Aufgabentyp | Empfohlenes Modell | Kosten (ca.) | Begründung |
+|-------------|-------------------|-------------|------------|
+| **Einfache Routineaufgaben** (Dateien verschieben, Status prüfen, weiterleiten) | `google/gemini-2.5-flash` | ~$0.15/M input | Schnell, günstig, zuverlässiger Tool-Use |
+| **Textverarbeitung** (Zusammenfassungen, Berichte, E-Mails) | `google/gemini-2.5-flash` oder `anthropic/claude-haiku-4-5` | $0.15–0.80/M input | Gutes Preis/Leistungs-Verhältnis |
+| **Analyse & Reasoning** (Datenanalyse, Entscheidungen, komplexe Logik) | `anthropic/claude-sonnet-4-5` | ~$3/M input | Starkes Reasoning bei akzeptablen Kosten |
+| **Koordinator-Agent** (orchestriert andere, trifft Entscheidungen) | `anthropic/claude-sonnet-4-5` | ~$3/M input | Braucht gutes Verständnis der Gesamtsituation |
+| **Maximale Qualität** (kritische Entscheidungen, kreative Aufgaben) | `anthropic/claude-opus-4` | ~$15/M input | Nur wenn Qualität wichtiger als Kosten |
+| **Budget-Minimum** | `google/gemini-2.5-flash-lite` | ~$0.02/M input | Für einfachste Aufgaben, schlechterer Tool-Use |
+
+### Kostenberechnung
+
+```
+Kosten pro Run ≈ (Input-Tokens × Inputpreis) + (Output-Tokens × Outputpreis)
+
+Beispiel: Gemini 2.5 Flash, typischer Run (5000 in, 1000 out):
+  = 5000 × $0.00000015 + 1000 × $0.0000006
+  = $0.00075 + $0.0006
+  = $0.00135 pro Run
+
+Beispiel: Claude Sonnet, typischer Run (5000 in, 1000 out):
+  = 5000 × $0.000003 + 1000 × $0.000015
+  = $0.015 + $0.015
+  = $0.03 pro Run
+```
+
+**Cron alle 5 Minuten mit Gemini Flash:** ~288 Runs/Tag × $0.00135 = **~$0.39/Tag**
+**Cron alle 5 Minuten mit Claude Sonnet:** ~288 Runs/Tag × $0.03 = **~$8.64/Tag**
+
+### LoopGuard für Kostenkontrolle anpassen
+
+| Szenario | maxSteps | maxTokens | timeoutSeconds |
+|----------|----------|-----------|----------------|
+| Einfache Routine | 5–10 | 20.000 | 120 |
+| Standard-Aufgabe | 10–20 | 50.000 | 300 |
+| Komplexe Analyse | 20–30 | 80.000 | 600 |
+| Budget-kritisch | 3–5 | 10.000 | 60 |
+
+---
+
+## 5. Tool-Zuweisung
+
+### Verfügbare Tools
+
+| Tool | Zweck | Benötigte Config | Background Jobs |
+|------|-------|-----------------|-----------------|
+| **FileRW** | Dateien lesen/schreiben im Workspace | (optional) sharedAccessLevel, allowedExtensions | Nein |
+| **Database** | SQL/NoSQL-Zugriff | type, connectionString | Nein |
+| **Mail** | E-Mails senden/empfangen | smtpHost, imapHost, username, password | Ja: `mail_check_unread` |
+| **Telegram** | Telegram-Nachrichten | botToken | Ja: `telegram_poll` |
+| **WebFetch** | Webseiten/RSS abrufen | allowedDomains | Nein |
+| **WebMonitor** | Webseiten auf Änderungen prüfen | monitors (mit url, parser, idPattern) | Nein |
+| **FTP** | Datei-Upload/Download | host | Nein |
+| **DirectAPI** | Finanzdaten (Aktien, Crypto, Forex) | providers (mit apiKey pro Provider) | Nein |
+| **SocialMediaManager** | X, Reddit, YouTube-Transkripte | (je nach Aktion) xApiKey, openRouterApiKey | Ja: `sm_yt_monitor`, `sm_transcript_notifier` |
+| **AgentComm** | Nachrichten an andere Agenten senden | (keine) | Nein |
+| **AgentSpawn** | Andere Agenten starten und beauftragen | (keine) | Nein |
+
+### Zuweisungsregeln
+
+1. **Minimalprinzip:** Nur Tools zuweisen, die der Agent tatsächlich braucht
+2. **Tool = Berechtigung:** Ein Tool in `tools` aufzunehmen gewährt sofort Zugriff (PermissionGate prüft nur Existenz im Dictionary)
+3. **Config = Sicherheitsgrenze:** `allowedDomains`, `allowedTables`, `allowedRecipients` etc. sind die echten Einschränkungen
+4. **AgentComm/AgentSpawn:** Nur dem Koordinator-Agenten zuweisen, nicht jedem
+5. **Tool Jobs prüfen:** Ein ToolJob funktioniert nur wenn der Agent das Tool auch zugewiesen hat — die Laufzeitprüfung deaktiviert den Job sonst automatisch
+
+### Typische Tool-Kombinationen
+
+| Agenten-Rolle | Tools |
+|--------------|-------|
+| Koordinator | FileRW, AgentComm, AgentSpawn |
+| Recherche-Agent | FileRW, WebFetch, WebMonitor |
+| Kommunikations-Agent | FileRW, Mail, Telegram |
+| Datenbank-Agent | FileRW, Database |
+| Social-Media-Agent | FileRW, SocialMediaManager, WebFetch |
+| Finanz-Agent | FileRW, DirectAPI, Database |
+
+---
+
+## 6. Kritische Analyse: Ist die Idee umsetzbar?
+
+Vor dem Aufbau einer Instanz systematisch prüfen:
+
+### Checkliste: Machbarkeit
+
+| Prüfpunkt | Frage | Risiko wenn nein |
+|-----------|-------|-----------------|
+| **Tool-Abdeckung** | Gibt es für jeden externen Zugang ein passendes Tool? | Hoch — ohne Tool kein Zugriff |
+| **API-Verfügbarkeit** | Haben alle externen APIs die nötigen Endpunkte? | Hoch — Tool ist nutzlos ohne funktionierende API |
+| **Datenformat** | Kann das Tool die Daten in einem Format liefern, das das LLM verarbeiten kann? | Mittel — große/binäre Daten überfordern den Context |
+| **Autonomie-Level** | Kann die Aufgabe ohne menschliche Zwischenschritte laufen? | Mittel — wenn nicht, braucht es manuelle Trigger statt Cron |
+| **Budget** | Reicht das Token-Budget für die geplante Frequenz? | Hoch — unterschätzter Verbrauch ist der häufigste Fehler |
+| **Koordination** | Brauchen Agenten wirklich Echtzeit-Kommunikation oder reicht SharedWorkspace? | Mittel — AgentComm kostet Token auf beiden Seiten |
+
+### Häufige Fallstricke und Lösungen
+
+#### Fallstrick 1: Token-Explosion durch Polling
+
+**Problem:** Agent wird per Cron alle 2 Minuten geweckt → 720 LLM-Runs/Tag, auch wenn nichts passiert ist.
+
+**Lösung:** Tool Jobs (`IToolJobProvider`) statt Agent-Wakeup verwenden. Das Tool prüft selbst (kein LLM) und weckt den Agenten nur bei Bedarf. Kostet ~0 Token pro Leer-Check.
+
+```json
+"scheduler": null,
+"toolJobs": [
+  {
+    "toolName": "Telegram",
+    "jobTypeId": "telegram_poll",
+    "cron": "*/1 * * * *",
+    "enabled": true
+  }
+]
+```
+
+#### Fallstrick 2: Context-Overflow bei großen Daten
+
+**Problem:** WebFetch liefert 50 KB HTML, Database-Query liefert 200 Zeilen → Context voll, Compaction verliert wichtige Infos.
+
+**Lösung:**
+- `maxResponseKb` in WebFetch begrenzen (Standard: 512 KB — oft zu viel)
+- Database-Queries mit LIMIT versehen (in SystemPrompt anweisen)
+- LoopGuard `maxContextTokens` angemessen setzen
+- Agent in der Identity anweisen, Ergebnisse sofort zu verarbeiten und zusammenzufassen
+
+#### Fallstrick 3: Agenten reden aneinander vorbei
+
+**Problem:** AgentComm-Nachrichten ohne klare Struktur → Missverständnisse, Endlosschleifen.
+
+**Lösung:**
+- In Soul.md ein festes Nachrichtenformat definieren (JSON mit `type`, `content`, `expectedAction`)
+- SharedWorkspace für asynchronen Datenaustausch bevorzugen (Dateien statt Nachrichten)
+- Koordinator-Agent als einzigen mit AgentSpawn/AgentComm ausstatten
+
+#### Fallstrick 4: Scheduler ohne sichtbares Ergebnis
+
+**Problem:** Agent wird per Cron geweckt, arbeitet im Hintergrund, aber niemand sieht ob es funktioniert.
+
+**Lösung:**
+- Agent soll Ergebnisse in den SharedWorkspace schreiben (prüfbar per FileRW)
+- Wichtige Ergebnisse per Mail oder Telegram melden lassen
+- TokenUsage.json regelmäßig prüfen (Kosten vs. erwarteter Output)
+
+#### Fallstrick 5: Tool-Config Fehler erst zur Laufzeit sichtbar
+
+**Problem:** Falscher `botToken`, fehlender `connectionString` → Agent startet, Tool schlägt beim ersten Aufruf fehl.
+
+**Lösung:**
+- Vor dem Scheduler-Start einen manuellen Test-Run durchführen
+- Agent manuell starten mit einer Test-Aufgabe: "Sende eine Test-Nachricht über Telegram"
+- Logs unter `Agent-{Name}/Logs/` prüfen
+
+#### Fallstrick 6: Kosten unterschätzt bei Multi-Agent-Setup
+
+**Problem:** 3 Agenten × Cron alle 10 Min × Claude Sonnet = ~$130/Tag.
+
+**Lösung:**
+- Billige Modelle für Routinearbeit (Gemini Flash, Haiku)
+- Teure Modelle nur für Koordinator oder komplexe Analyse
+- LoopGuard `maxTokens` aggressiv begrenzen für Routine-Agenten
+- Tool Jobs statt Agent-Wakeup wo möglich
+
+#### Fallstrick 7: YouTube-Transkription braucht externes Tool
+
+**Problem:** `SocialMediaManager` mit `sm_yt_monitor` Job braucht `yt-dlp` als externes CLI-Tool auf dem System installiert.
+
+**Lösung:**
+- Vor Instanz-Setup prüfen ob `yt-dlp` installiert und im PATH ist
+- Ohne `yt-dlp` funktionieren `x_search` und `reddit_search` trotzdem
+
+---
+
+## 7. Beispiel-Instanz: "TelegramBot"
+
+Einfache Instanz mit einem Agenten, der über Telegram kommuniziert.
+
+### Planung
+
+- **Aufgabe:** Auf Telegram-Nachrichten antworten, einfache Fragen beantworten, Dateien im Workspace verwalten
+- **Agenten:** 1 (kein Koordinationsbedarf)
+- **Budget:** ~$0.50/Tag
+- **Modell:** `google/gemini-2.5-flash` (günstig, ausreichend für Chat)
+
+### Verzeichnisstruktur
+
+```
+Instance-TelegramBot/
+├── InstanceSettings.json
+├── TokenUsage.json
+└── Agents/
+    ├── AgentList.json
+    ├── SharedWorkspace/
+    └── Agent-Assistent/
+        ├── AgentSettings.json
+        ├── Identity.md
+        ├── Soul.md
+        ├── Logs/
+        └── Workspace/
+```
+
+### AgentList.json
+
+```json
+{
+  "agents": [
+    {
+      "name": "Assistent",
+      "description": "Beantwortet Telegram-Nachrichten und verwaltet Notizen",
+      "folderName": "Agent-Assistent"
+    }
+  ]
+}
+```
+
+### AgentSettings.json
+
+```json
+{
+  "agentId": "assistent",
+  "displayName": "Assistent",
+  "model": "google/gemini-2.5-flash",
+  "systemPrompt": "",
+  "tools": {
+    "Telegram": {
+      "botToken": "123456:ABC-DEF...",
+      "defaultChatId": "987654321",
+      "allowedChatIds": ["987654321"]
+    },
+    "FileRW": {
+      "sharedAccessLevel": "Denied",
+      "personalAllowedExtensions": [".txt", ".json", ".md"]
+    }
+  },
+  "scheduler": null,
+  "toolJobs": [
+    {
+      "jobId": "tgpoll01",
+      "toolName": "Telegram",
+      "jobTypeId": "telegram_poll",
+      "cron": "*/1 * * * *",
+      "enabled": true,
+      "runOnStart": true
+    }
+  ],
+  "loopGuard": {
+    "maxSteps": 10,
+    "maxTokens": 30000,
+    "timeoutSeconds": 120,
+    "maxContextTokens": 100000,
+    "compactionThreshold": 0.8
+  }
+}
+```
+
+### Kostenabschätzung
+
+- Telegram-Polling: 1440 Ticks/Tag, ~0 Token (Tool Job, kein LLM)
+- Agent-Wakeups: geschätzt 20 Nachrichten/Tag × ~$0.00135/Run = **~$0.03/Tag**
+- Deutlich unter dem $0.50 Budget
+
+---
+
+## 8. Beispiel-Instanz: "Recherche-Team"
+
+Multi-Agent-Setup für automatisierte Web-Recherche mit Berichterstattung.
+
+### Planung
+
+- **Aufgabe:** Täglich Webseiten/RSS-Feeds prüfen, relevante Infos sammeln, Bericht per E-Mail senden
+- **Agenten:** 3 (Recherche, Analyse, Bericht)
+- **Budget:** ~$5/Tag
+
+### Agenten-Design
+
+| Agent | Modell | Tools | Scheduler | Zweck |
+|-------|--------|-------|-----------|-------|
+| Crawler | `google/gemini-2.5-flash` | FileRW, WebFetch, WebMonitor | Cron `0 7 * * *` | Daten sammeln, in SharedWorkspace ablegen |
+| Analyst | `anthropic/claude-sonnet-4-5` | FileRW | Cron `0 8 * * *` | Daten analysieren, Zusammenfassung erstellen |
+| Reporter | `google/gemini-2.5-flash` | FileRW, Mail | Cron `0 9 * * *` | Zusammenfassung als E-Mail versenden |
+
+### Warum dieses Setup?
+
+- **Crawler** braucht kein teures Modell — holt nur Daten ab und speichert sie
+- **Analyst** bekommt Sonnet weil Analyse-Qualität hier den Unterschied macht
+- **Reporter** braucht kein teures Modell — formatiert nur und sendet
+- **Zeitversatz** (7:00 → 8:00 → 9:00) statt AgentComm — günstiger und zuverlässiger
+- **SharedWorkspace** statt Echtzeit-Kommunikation — keine doppelten Token-Kosten
+
+### Kostenabschätzung
+
+- Crawler: 1 Run/Tag × ~$0.002 = $0.002
+- Analyst: 1 Run/Tag × ~$0.03 = $0.03
+- Reporter: 1 Run/Tag × ~$0.002 = $0.002
+- **~$0.034/Tag** — weit unter Budget
+
+---
+
+## 9. Checkliste: Neue Instanz aufsetzen
+
+- [ ] Aufgabe und Agenten-Aufteilung definiert
+- [ ] Kostenabschätzung durchgeführt (Modell × Frequenz × Agenten)
+- [ ] Prüfung: Alle nötigen Tools vorhanden?
+- [ ] Prüfung: Alle externen APIs/Zugangsdaten verfügbar?
+- [ ] Prüfung: Externe Abhängigkeiten installiert? (z.B. yt-dlp)
+- [ ] Instanz-Ordner erstellt (manuell oder über UI)
+- [ ] `InstanceSettings.json` mit API-Key konfiguriert
+- [ ] `AgentList.json` mit allen Agenten erstellt
+- [ ] Pro Agent: `AgentSettings.json` mit Modell, Tools, LoopGuard
+- [ ] Pro Agent: `Identity.md` (Rolle, Expertise, Kontext)
+- [ ] Pro Agent: `Soul.md` (Persönlichkeit, Methodik, Ausgabeformat)
+- [ ] Pro Agent: Tool-Configs mit echten Zugangsdaten befüllt
+- [ ] Tool Jobs konfiguriert (statt Agent-Wakeup wo sinnvoll)
+- [ ] Manueller Test-Run pro Agent durchgeführt
+- [ ] Logs geprüft — keine Tool-Fehler?
+- [ ] Scheduler aktiviert
+- [ ] Nach 24h: TokenUsage.json prüfen, Kosten validieren