2025-12-11 16:58:23 +01:00

6.6 KiB

Raw Blame History

Mindnet v2.4 – Entwickler-Workflow

Datei: docs/DEV_WORKFLOW.md Stand: 2025-12-11 (Aktualisiert: Inkl. Async Intelligence & Nomic)

Dieses Handbuch beschreibt den Entwicklungszyklus zwischen Windows PC (IDE), Raspberry Pi (Gitea) und Beelink (Runtime/Server).

1. Die Architektur

Windows 11 (VS Code): Hier schreibst du Code. Nie direkt auf main arbeiten!
Raspberry Pi (Gitea): Der Tresor. Speichert den Code und verwaltet Versionen.
Beelink (Runtime): Hier läuft die Software. Wir nutzen Systemd-Services:
- PROD:
  - API: mindnet-prod (Port 8001). Ordner: ~/mindnet.
  - UI: mindnet-ui-prod (Port 8501).
- DEV:
  - API: mindnet-dev (Port 8002). Ordner: ~/mindnet_dev.
  - UI: mindnet-ui-dev (Port 8502).

2. Der Zyklus: Von der Idee zum Release

Phase 1: Entwicklung (Windows / VS Code)

Hier erstellst du die neue Funktion in einer sicheren Umgebung.

Basis aktualisieren (WICHTIG!): Bevor du startest, muss dein lokales main auf dem Stand des Servers sein.
- Klicke unten links auf den aktuellen Branch und wähle main.
- Klicke links im Menü "Source Control" auf die drei Punkte (...) -> Pull (oder das Synchronisieren-Symbol).
- Erst jetzt hast du alle Dateien!
Branch erstellen:
- Klicke wieder unten links auf main.
- Wähle + Create new branch....
- Gib den Namen ein: feature/was-ich-tue (z.B. feature/wp11-async-fix).
- Drücke Enter.
Sicherheits-Check:
- Steht unten links jetzt dein Feature-Branch? Nur dann darfst du Code ändern!
Coden:
- Nimm deine Änderungen vor (z.B. neue Schemas in decision_engine.yaml oder Async-Logik in ingestion.py).
Sichern & Hochladen:
- Source Control Icon (Gabel-Symbol) -> Nachricht eingeben -> Commit.
- Publish Branch (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.

Phase 2: Testen (Beelink / `mindnet_dev`)

Hier prüfst du, ob dein neuer Code auf dem echten Server läuft.

Einloggen: ssh user@<BEELINK-IP>
In die Werkstatt gehen: cd /home/llmadmin/mindnet_dev

Code holen:

git fetch
# Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
git checkout feature/wp11-async-fix
git pull

Umgebung vorbereiten (WICHTIG für v2.4):

source .venv/bin/activate
pip install -r requirements.txt  # HTTPX usw.
# Sicherstellen, dass das neue Embedding-Modell da ist:
ollama pull nomic-embed-text

Test-Server aktualisieren (WICHTIG): Der Code ist da, aber die Prozesse im RAM sind noch alt. Wir müssen die Services neustarten.

Option A: Standard (Als Service laufen lassen) Ideal, wenn du nur testen willst, ob es läuft.

# 1. API neustarten (Backend)
sudo systemctl restart mindnet-dev
# 2. UI neustarten (Frontend)
sudo systemctl restart mindnet-ui-dev

# Logs prüfen (um Fehler zu sehen):
journalctl -u mindnet-dev -f

Option B: Manuell Debuggen (Direct Output) Ideal, wenn du Print-Ausgaben direkt sehen willst oder der Service dauernd crasht.

# 1. Services stoppen (wichtig, sonst sind Ports 8002/8502 belegt!)
sudo systemctl stop mindnet-dev
sudo systemctl stop mindnet-ui-dev

# 2. Manuell starten (z.B. API)
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env

Validieren (Smoke Tests):
- Browser: Öffne http://<IP>:8502 um die UI zu testen (Intent Badge prüfen!).
- CLI: Führe Testskripte in einem zweiten Terminal aus:
  
  Test A: Intelligence / Aliases (Neu in WP11)
```
python debug_analysis.py
# Erwartung: "✅ ALIAS GEFUNDEN"
```
  Test B: API Check
```
curl -X POST "http://localhost:8002/ingest/analyze" -d '{"text": "mindnet", "type": "journal"}'
```

Phase 3: Release (Gitea / Raspberry Pi)

Wenn der Test auf Port 8002 / 8502 erfolgreich war:

Öffne Gitea im Browser.
Erstelle einen Pull Request (Dein Branch -> main).
Merge den Pull Request.

Phase 4: Deployment (Beelink / `mindnet`)

Jetzt bringen wir die Änderung in das Live-System (Port 8001 / 8501).

Deploy-Agent (Automatisch): Wenn dein deploy.yml aktiv ist, passiert das jetzt von selbst!

Manuell (Falls nötig):

cd /home/llmadmin/mindnet
git pull origin main

# Dependencies updaten & Modelle checken
source .venv/bin/activate
pip install -r requirements.txt
ollama pull nomic-embed-text

# Falls sich die Vektor-Dimension geändert hat (v2.4 Upgrade):
# python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
# python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force

# Produktions-Services neustarten
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod

Phase 5: Aufräumen (Optional aber empfohlen)

Damit das Chaos nicht wächst, löschen wir den fertigen Branch.

Gitea: Im Pull Request auf "Delete Branch" klicken.

Beelink (Dev):

cd ~/mindnet_dev
git checkout main
git pull
git branch -d feature/wp11-async-fix

VS Code:
- Auf main wechseln.
- Sync drücken.
- F1 -> Git: Delete Branch -> Branch auswählen.

3. Cheat Sheet: Die wichtigsten Befehle

Wo?	Befehl	Was tut es?
Beelink	`sudo systemctl restart mindnet-dev`	Neustart Dev-Backend (Port 8002).
Beelink	`journalctl -u mindnet-dev -f`	Live-Logs Backend.
Beelink	`python debug_analysis.py`	Prüft Aliases & Scores.
Beelink	`python -m scripts.reset_qdrant ...`	Löscht & Repariert DB.

4. Troubleshooting

"Vector dimension error: expected 768, got 384"

Ursache: Du hast nomic-embed-text (768) aktiviert, aber die DB ist noch alt (384).
Lösung: scripts.reset_qdrant ausführen und neu importieren.

"Read timed out (300s)" / 500 Error beim Interview

Ursache: Das LLM (Ollama) braucht für den One-Shot Draft länger als das Timeout erlaubt.
Lösung:
1. Erhöhe in .env den Wert: MINDNET_LLM_TIMEOUT=300.0.
2. Starte die Server neu.

"UnicodeDecodeError in .env"

Ursache: Umlaute oder Sonderzeichen in der .env Datei.
Lösung: .env bereinigen (nur ASCII nutzen) und sicherstellen, dass sie UTF-8 ohne BOM ist.

6.6 KiB Raw Blame History Unescape Escape