230 lines
7.1 KiB
Markdown
230 lines
7.1 KiB
Markdown
# goralphy
|
||
|
||
## Projekt
|
||
Autonomer Go Coding-Agent ähnlich wie Ralphy.
|
||
Nutzt lokale LLMs via OpenAI-kompatibler API (Docker AI, Port 12434).
|
||
Die lokalen LLMs sind klein und laufen auf einem Rechner mit 16GB RAM –
|
||
daher ist die Planung und Task-Aufteilung in atomare Schritte besonders wichtig.
|
||
|
||
Das Projekt unterstützt mehrere spezialisierte Agenten die zusammenarbeiten:
|
||
- **Planner-Agent**: Zerlegt PRD.md in atomare, ausführbare Tasks
|
||
- **Code-Agent**: Führt Tasks aus, schreibt Code, dokumentiert
|
||
- **Test-Agent**: Führt Tests aus, analysiert Fehler, gibt Feedback an Code-Agent
|
||
- **Research-Agent**: Recherchiert Fragen basierend auf konfigurierbaren Quellen
|
||
(GitHub, Google, Reddit, StackOverflow)
|
||
|
||
Jeder Agent dokumentiert Erkenntnisse in `.agent-session.md` damit Fortschritte
|
||
nachvollziehbar sind und Agenten voneinander lernen können.
|
||
|
||
---
|
||
|
||
## Aktueller Implementierungsstand
|
||
|
||
### Fertig ✅
|
||
- `main.go` – Flag-Parsing, Modell-Auswahl via /v1/models API
|
||
- `agent/loop.go` – Worker-Loop mit Tool Calling + XML-Fallback Parser
|
||
- `agent/tools.go` – ToolExecutor: write_file, read_file, list_files (rekursiv), task_complete
|
||
- `agent/logger.go` – Verbose-Logging mit --verbose Flag
|
||
- `agent/session.go` – Session-Persistenz in .agent-session.md
|
||
- `prd/parser.go` – PRD.md Checkbox-Parser + MarkTaskComplete
|
||
|
||
### In Arbeit 🔄
|
||
- `agent/planner.go` – Planner-Agent (Grundgerüst vorhanden, noch nicht in loop.go integriert)
|
||
|
||
### Geplant 📋
|
||
- `agent/code.go` – Code-Agent
|
||
- `agent/test.go` – Test-Agent
|
||
- `agent/research.go` – Research-Agent
|
||
|
||
---
|
||
|
||
## Architektur
|
||
|
||
### Dateien
|
||
- `main.go` – Einstiegspunkt, Flag-Parsing, Modell-Auswahl
|
||
- `agent/loop.go` – Haupt-Loop, koordiniert alle Agenten
|
||
- `agent/tools.go` – Tool-Executor (Filesystem-Operationen)
|
||
- `agent/logger.go` – Strukturiertes Logging
|
||
- `agent/session.go` – Session-Persistenz
|
||
- `agent/planner.go` – Planner-Agent
|
||
- `agent/code.go` – Code-Agent (geplant)
|
||
- `agent/test.go` – Test-Agent (geplant)
|
||
- `agent/research.go` – Research-Agent (geplant)
|
||
- `prd/parser.go` – PRD.md Parser
|
||
|
||
---
|
||
|
||
## Agent Interface
|
||
|
||
Jeder Agent implementiert dieses Interface:
|
||
|
||
```go
|
||
type Agent interface {
|
||
Run(task Task) (Result, error)
|
||
Name() string
|
||
}
|
||
|
||
type Task struct {
|
||
ID int
|
||
Title string
|
||
Description string
|
||
OriginTask string
|
||
}
|
||
|
||
type Result struct {
|
||
Success bool
|
||
Output string
|
||
Findings string // wird in .agent-session.md dokumentiert
|
||
}
|
||
```
|
||
|
||
Jeder Agent bekommt:
|
||
- Einen `*openai.Client` für LLM-Calls
|
||
- Einen `*ToolExecutor` für Filesystem-Zugriff
|
||
- Einen `*Logger` für strukturiertes Logging
|
||
- Einen `*Session` für Persistenz
|
||
|
||
---
|
||
|
||
## Wichtige Konventionen
|
||
|
||
- **Go Modulname**: `llm-agent`
|
||
- **LLM Endpoint**: `http://127.0.0.1:12434/v1`
|
||
- **Default Modell**: `docker.io/ai/qwen3-coder:latest`
|
||
- **Arbeitsverzeichnis**: `./output` (per `--workdir` Flag)
|
||
- **PRD-Datei**: `PRD.md` (per `--prd` Flag)
|
||
- **Session-Datei**: `{workdir}/.agent-session.md`
|
||
- **Pfade**: immer relativ zum workdir, niemals absolut
|
||
- **Kontext**: frischer Kontext pro Task (kein Context-Bloat)
|
||
- **Fehlerbehandlung**: maxRetries=3 mit exponential Backoff
|
||
|
||
---
|
||
|
||
## Bekannte Probleme & Workarounds
|
||
|
||
| Problem | Workaround |
|
||
|---|---|
|
||
| Modell nutzt XML-Format statt JSON Tool Calling | XML-Fallback Parser in `loop.go` (`parseXMLToolCalls`) |
|
||
| Kleine Modelle (3B) halten sich nicht an Formate | Mindestens 7B Modell empfohlen |
|
||
| `go run` zeigt auf `/tmp` | `os.Getwd()` statt `os.Executable()` |
|
||
| LLM schreibt absoluten Pfad | `sanitizePath()` extrahiert relativen Teil |
|
||
| `TASK_COMPLETE` ohne Arbeit in Turn 0 | Guard in `runTask()` – prüft ob Tool-Call stattfand |
|
||
| API Timeout bei großen Modellen | `context.WithTimeout` auf 5 Minuten |
|
||
|
||
---
|
||
|
||
## Commands
|
||
|
||
```bash
|
||
# Bauen
|
||
go build -o llm-agent .
|
||
|
||
# Starten
|
||
go run main.go --workdir output --prd PRD.md
|
||
go run main.go --workdir output --prd PRD.md --verbose
|
||
go run main.go --workdir output --prd PRD.md --verbose --model docker.io/ai/qwen3-coder:latest
|
||
|
||
# Tests
|
||
go test ./...
|
||
go test -v ./agent/...
|
||
go test -cover ./agent/...
|
||
```
|
||
|
||
---
|
||
|
||
## Vorgehensweise für Claude Code
|
||
|
||
1. Verfeinere Agent-Interface und Basis-Architektur
|
||
2. Integriere `planner.go` in `loop.go`
|
||
3. Implementiere `code.go` (Code-Agent)
|
||
4. Teste Code-Agent mit einfachen Tasks
|
||
5. Implementiere `test.go` (Test-Agent)
|
||
6. Verbinde Code-Agent und Test-Agent in Feedback-Loop
|
||
7. Implementiere `research.go` (Research-Agent)
|
||
|
||
---
|
||
|
||
## Spätere Erweiterungen
|
||
|
||
- **Vektor-Datenbank**: Speicherung von Agenten-Erkenntnissen und Code-Snippets
|
||
für Wiederverwendbarkeit und Lernen zwischen Sessions
|
||
- **Git-Integration**: Automatische Commits pro Task, Steuerung via Pull Requests,
|
||
Zusammenarbeit mehrerer Agenten auf separaten Branches
|
||
- **Discord-Integration**: Echtzeit-Monitoring und Interaktion mit Agenten
|
||
über Discord Chat
|
||
- **Streaming**: LLM-Antworten Wort für Wort ausgeben statt auf einmal warten
|
||
|
||
---
|
||
|
||
## Session-Format (.agent-session.md)
|
||
|
||
```markdown
|
||
# Agent Session
|
||
|
||
Started: 2026-03-04 20:00:00
|
||
Model: docker.io/ai/qwen3-coder:latest
|
||
PRD: output/PRD.md
|
||
|
||
## Plan
|
||
|
||
### Erstelle go.mod[1]
|
||
Origin: Projektstruktur anlegen
|
||
Description: Erstelle go.mod mit Modulname llm-agent...
|
||
|
||
## Tasks
|
||
|
||
### ✅ Erstelle go.mod
|
||
Status: complete
|
||
Started: 2026-03-04 20:00:01
|
||
Completed: 2026-03-04 20:00:45
|
||
|
||
### ❌ Erstelle main.go
|
||
Status: failed
|
||
Attempts: 3
|
||
Error: maximale Turns (10) erreicht ohne task_complete
|
||
|
||
### ⏳ Erstelle README.md
|
||
Status: pending
|
||
```
|
||
|
||
---
|
||
|
||
## Tool-Übersicht
|
||
|
||
## Tool-Übersicht
|
||
|
||
| Tool | Parameter | Beschreibung |
|
||
|---|---|---|
|
||
| `write_file` | `path`, `content` | Datei schreiben, Verzeichnisse werden automatisch erstellt |
|
||
| `read_file` | `path` | Dateiinhalt lesen |
|
||
| `list_files` | `path`, `recursive?` | Verzeichnis auflisten, optional rekursiv |
|
||
| `delete_file` | `path` | Datei löschen |
|
||
| `move_file` | `from`, `to` | Datei verschieben oder umbenennen |
|
||
| `run_command` | `command`, `args[]`, `workdir?` | Beliebigen Shell-Befehl ausführen (z.B. `go build`, `go test`) |
|
||
| `run_tests` | `path?`, `flags[]?` | `go test ./...` ausführen, gibt Ergebnis und Fehler zurück |
|
||
| `git_command` | `args[]` | Beliebigen git-Befehl ausführen (z.B. `["commit", "-m", "msg"]`) |
|
||
| `git_status` | – | `git status` – zeigt geänderte Dateien |
|
||
| `git_diff` | `path?` | `git diff` – zeigt Änderungen |
|
||
| `git_commit` | `message`, `files[]?` | Dateien stagen und committen |
|
||
| `git_log` | `limit?` | Letzte Commits anzeigen |
|
||
| `web_search` | `query`, `sources[]?` | Websuche, optionale Quellen: `github`, `stackoverflow`, `reddit`, `google` |
|
||
| `fetch_url` | `url` | Inhalt einer URL abrufen und als Text zurückgeben |
|
||
| `task_complete` | `summary?` | Task als erledigt markieren, optionale Zusammenfassung |
|
||
| `task_failed` | `reason` | Task explizit als fehlgeschlagen markieren mit Begründung |
|
||
|
||
---
|
||
|
||
## Sicherheitsregeln
|
||
|
||
| Tool | Einschränkung |
|
||
|---|---|
|
||
| `write_file`, `delete_file`, `move_file` | Nur innerhalb `workdir` |
|
||
| `run_command` | Konfigurierbare Whitelist erlaubter Befehle |
|
||
| `git_command` | Nur im Projekt-Root, kein `git push` ohne Bestätigung |
|
||
| `web_search`, `fetch_url` | Optional deaktivierbar per Flag `--no-network` |
|
||
|
||
---
|
||
|
||
## Implementierung
|
||
|