meleki/gott
1
0 Fork 0
Code Activity
Files
a3f2aa38c1cb18a24e7bc0c66f14141683e40250
gott/ARCHITECTURE_QUICK.md
T

12 KiB
Raw Blame History

ARCHITECTURE_QUICK.md – Schnellreferenz

Kurzfassung der ARCHITECTURE.md für schnelles Nachschlagen beim Entwickeln.

Tech-Stack

.NET 10 Minimal API · SQLite + Dapper · Anthropic Claude API (SSE Streaming) · Vanilla JS SPA · KaTeX (Math) · Kestrel auf Port 19000

Verzeichnisstruktur (nur Schlüssel-Dateien)

gott/
├── Program.cs                  # Startup, DI, Middleware, Routing
├── appsettings.json            # Tokens, API-Keys, Limits
├── Models/                     # Records (reine Daten)
├── Services/                   # Business-Logic (alle Singletons + WorkspaceHelper)
├── Endpoints/                  # HTTP API (Minimal API MapXxx-Pattern)
├── Middleware/                  # AuthMiddleware
├── Templates/                  # Vorlagen für neue Agents (IDENTITY, SOUL, USER)
├── wwwroot/                    # ⚠️ HIER Frontend editieren!
│   ├── js/app.js               # App-Init
│   ├── js/router.js            # Hash-basiertes SPA-Routing
│   ├── js/api.js               # fetch()-Wrapper
│   ├── js/chat.js              # SSE-Stream, Markdown-Rendering
│   ├── js/ui.js                # UI-Helpers, buildAgentCard(), buildSessionCard(), Review-Rendering
│   ├── js/pages/               # Seiten-Komponenten
│   └── css/                    # Styles (theme.css = CSS Variables)
├── WindowsApp/                 # WPF + WebView2 Desktop Client
└── publish/                    # ⛔ NICHT editieren!
    └── data/
        ├── gott.db             # SQLite DB
        ├── agents/{id}/        # Memory-Dateien pro Agent
        ├── skills/{slug}/      # Skill-Dateien
        └── images/             # Krea-generierte Bilder

Datenmodell (Kurzform)

User 1──* Agent 1──* Session 1──* Chain 1──* Message 1──* Attachment
                     Agent *──* Skill (via agent_skills)
                     Session 1──* Cronjob
                     Session 1──* Archive
                     User 1──* SharedMessage ──1 Message
Tabelle Zweck
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)
chains Ein Request-Response-Zyklus (Tokens, Timing, Iterations)
messages Einzelne Nachrichten (text / tool_use / tool_result / error)
attachments Base64-Anhänge (Bilder, Dokumente)
archives Archivierte Chain-Gruppen
cronjobs Geplante Tasks (Cron-Expression + Prompt)
agent_skills N:M Agent ↔ Skill
shared_messages Geteilte Nachrichten (öffentliche Links via Share-Token)
telegram_links Telegram Chat-ID ↔ Session

API-Endpunkte (Übersicht)

Gruppe Route Wichtigstes
Auth /api/auth/ POST login, POST logout, GET me, GET autologin
Chat /api/chat POST → SSE Stream, POST stop
History /api/history GET history, poll, archive, marks, delete
Sessions /api/sessions/ CRUD + system-prompt, exec, git-status
Agents /api/agents/ CRUD
Admin /api/admin/ User CRUD, impersonate, login-link (Admin-only)
Workspace /api/workspace/ tree, file read/write, mkdir, rmdir, browse, agent-files
Telegram /api/telegram/ webhook (unauth), config, registration
Cronjobs /api/cronjobs/ CRUD + toggle, manual run
Krea /api/images/ generate, list, file-serve, thumb, status (file/* ohne Auth)
Skills /api/skills list, agent-mapping, output-files
Profile /api/profile GET, PUT, password
Settings /api/settings GET, PUT (JSON blob)
Backup /api/backup POST → tar.gz download (Admin)
Shared /api/shared/, /api/messages/{id}/share Share erstellen, öffentlich abrufen, löschen
Info /api/info GET → Build-Zeitstempel
ServerSettings /api/admin/server-settings GET, PUT (Admin-only, liest/schreibt appsettings.Production.json)

Services (alle Singletons)

Service Was es tut
DatabaseService Alles DB: Schema, Migrationen, CRUD
AuthService Token-Auth, Passwort-Hashing (SHA256)
ChatService Chat-Kontext aufbauen, History aus DB laden
AnthropicService Claude API: SSE Streaming + Non-Streaming
ToolService Tool-Definitionen + Ausführung (12 Tools)
WorkspaceHelper Workspace-Pfad-Auflösung (relativ → absolut), Path-Traversal-Schutz (static)
SystemPromptBuilder System-Prompt aus modularen Blöcken zusammenbauen (static)
MemoryService Agent-Gedächtnis auf Dateisystem
SkillService Skill-Discovery aus Dateisystem
TelegramService Telegram Bot API
CronjobService BackgroundService, minütlicher Cron-Check
KreaService Krea API Bildgenerierung + Job-Polling
ImageService Bild-Resize (ImageSharp, max 512px)
StreamingTracker Tracking aktiver Streams + CancellationTokenSource pro Session für Stop

Chat-Pipeline (Flow)

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
  → AnthropicService.StreamChat()
    → Claude API Call (SSE)
    → Token-für-Token an Client streamen
    → Bei tool_use → ToolService.Execute() → Ergebnis zurück → neuer API Call
    → Loop bis end_turn oder max_iterations (100)
    → Bei end_turn + ReviewAgent → Review-Phase:
      → Review-Agent prüft (eigene Tools, max 25 Iterationen)
      → [APPROVED] → Fertig | Feedback → Worker korrigiert → erneuter Review
    → Stop-Button: POST /api/chat/stop → StreamingTracker.Cancel()
    → CancellationToken durchgereicht bis ToolService → Prozess-Kill
    → client_disconnected
  → 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.

Rendering: Markdown via marked.js + LaTeX via KaTeX ($$...$$ Block, $...$ Inline). Timestamps im Format dd.MM.yyyy HH:mm:ss on hover.

Tool-System (12 Tools)

Tool Funktion
read_file Datei lesen
write_file Datei erstellen/überschreiben
edit_file Exakten Textabschnitt ersetzen
list_files Verzeichnisinhalt auflisten
delete_file Datei/leeres Verzeichnis löschen
execute Shell-Befehl ausführen (bash, 180s Timeout)
glob Dateien per Glob-Pattern finden
grep Dateien per Regex/Text durchsuchen
todo_write Aufgabenliste schreiben (wird im Prompt angezeigt)
memory_read Memory-Datei lesen
memory_write Memory-Datei schreiben/appenden
memory_list Memory-Dateien auflisten

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.

System-Prompt (12 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

Frontend-Routing

Hash-Route Page-Datei Beschreibung
#/ dashboard.js Session-Übersicht
#/chat/{id} chat-page.js Chat
#/session/{id} session-page.js Session-Settings
#/agent/{id} agent-page.js Agent-Editor
#/cronjobs cronjob-page.js Cronjobs
#/profile profile-page.js Profil
#/settings settings-page.js Einstellungen
#/admin admin-page.js Benutzerverwaltung (Admin)
#/server-settings server-settings-page.js Servereinstellungen (Admin)
#/login login-page.js Login
#/shared/{token} shared-page.js Geteilte Nachricht (öffentlich, kein Auth)

Auth-Flow

  1. POST /api/auth/login → Token generiert, als gott_token HttpOnly Cookie gesetzt
  2. Jeder /api/-Request → AuthMiddleware prüft Cookie → setzt UserId + IsAdmin
  3. Ausnahmen: Login, Autologin, Telegram-Webhook, GET /api/shared/{token}, GET /api/images/file/* brauchen kein Auth
  4. Krea API-Key: /api/images/-Routen akzeptieren X-Api-Key-Header (Config: KreaApiKey) für Automation ohne User-Kontext
  5. Impersonate: Admin kann via POST /api/admin/users/{id}/impersonate als anderer User einloggen
  6. Login-Link: Admin generiert via POST /api/admin/users/{id}/login-link einen Autologin-Link (Token-basiert, GET /api/auth/autologin?token=xxx)
  7. DefaultPath: Pro User ein Basis-Ordner (nur vom Admin setzbar), Session-Workspaces sind relativ dazu

Konfiguration (appsettings.json)

{
  "Port": 19000,                // Server-Port (erfordert Neustart)
  "AnthropicToken": "",         // Anthropic API Key (REQUIRED)
  "MaxIterations": 100,         // Max Tool-Loop Iterationen pro Chat
  "PayloadLogging": false,      // API-Payloads loggen (Debug)
  "PayloadLoggingGzip": false,  // Payload-Logs als .gz komprimieren
  "KreaToken": "",               // Krea API Token (optional)
  "KreaApiKey": ""               // API-Key für Krea-Endpoints ohne User-Auth (optional)
}

Verwaltung über Admin-UI (#/server-settings): Liest appsettings.Production.json (Fallback: appsettings.json → Default). Schreibt immer in appsettings.Production.json. Die Datei wird nicht beim Publish mitkopiert.

Deployment

./deploy.sh    # dotnet publish → systemctl restart gott

Läuft als systemd-Service, Kestrel auf konfigurierbarem Port (Default 19000), typisch hinter Nginx/Caddy Reverse Proxy.

Multi-Agent Review-System

Eine Session kann optional einen Review-Agent haben (review_agent_id, max_review_iterations).

Flow: Worker-Agent arbeitet → end_turn → Review-Agent prüft (eigener API-Call, eigene Tools, max 25 Iterationen) → [APPROVED] = fertig | Feedback → Worker korrigiert → erneuter Review (bis max Runden).

Backend: ChatService baut ReviewContext (Model, SystemPrompt, Tools). AnthropicService.RunReview() orchestriert Review-Runden. RunReviewAgentChat() = eigener Claude-API-Call.

SSE-Events: review_start, review_text, review_tool_use, review_feedback, review_approved

Frontend-Rendering:

  • Streaming: chat.js rendert Review-Events als eigene Bubbles (.review-bubble)
  • History: renderMarkdown parst [Review: AgentName], [Review-Feedback ...], filtert [APPROVED]
  • history.js + shared-page.js: Review-Nachrichten als .review-bubble, kein Merging mit normalen Messages

Wichtige Regeln beim Entwickeln

  • ⚠️ Quelldateien in wwwroot/ editieren, NICHT in publish/wwwroot/
  • ⛔ publish/data/gott.db niemals manuell modifizieren/löschen
  • ⛔ publish/ generell nicht anfassen
  • 🔧 .NET 10 ohne Nullable, ohne Implicit Usings
  • 📦 DB-Migrationen sind idempotent (IF NOT EXISTS Pattern in DatabaseService)
View Git Blame Copy Permalink