[30388f42] Infrastructure Hardening: Repaired CE/Connector DB schema, fixed frontend styling build, implemented robust echo shield in worker v2.1.1, and integrated Lead Engine into gateway.
This commit is contained in:
116
docs/README_dev_session.md
Normal file
116
docs/README_dev_session.md
Normal file
@@ -0,0 +1,116 @@
|
||||
# `dev_session.py` - Notion Development Session Manager
|
||||
|
||||
## Übersicht
|
||||
|
||||
`dev_session.py` ist ein Kommandozeilen-Tool (CLI), das den Entwicklungs-Workflow durch die Integration mit Notion und Git optimiert. Es dient als Brücke zwischen der interaktiven Gemini CLI-Sitzung und dem Projektmanagement in Notion.
|
||||
|
||||
**Wichtige Architekturänderung:** Das Skript `dev_session.py` startet die Gemini CLI nicht mehr direkt. Stattdessen durchläuft der Entwickler einen interaktiven Setup-Prozess, an dessen Ende ein Kontext für die Gemini CLI generiert wird. Das übergeordnete `start-gemini.sh`-Skript fängt diesen Kontext auf und startet die Gemini CLI in einer sauberen, isolierten Docker-Sitzung. Dieser zweistufige Prozess gewährleistet eine stabile und kontextbezogene Entwicklungsumgebung.
|
||||
|
||||
## Funktionen
|
||||
|
||||
* **Interaktive Projekt- und Task-Auswahl:** Wähle Projekte und Tasks direkt aus deinen Notion-Datenbanken.
|
||||
* **Automatischer Start-Status:** Setzt den Status des ausgewählten Tasks beim Start der Sitzung automatisch auf 'Doing'.
|
||||
* **Task-Erstellung:** Erstelle neue Tasks direkt über das CLI im Kontext des ausgewählten Projekts.
|
||||
* **Agent-gesteuerte Statusberichte:** Ermöglicht dem Gemini-Agenten, nach Abschluss eines Arbeitspakets einen detaillierten Statusbericht an Notion zu senden, Code zu committen und zu pushen.
|
||||
* **Automatisches Commit-Feedback:** Ein `post-commit` Git-Hook sendet jede Commit-Nachricht als kurzen Kommentar an den Notion-Task.
|
||||
* **Kontext-Generierung für Gemini CLI:** Erzeugt einen strukturierten Start-Prompt mit allen relevanten Informationen (Projekt, Task, Beschreibung, Git-Branch).
|
||||
* **Vorgeschlagene Git Branch-Benennung:** Erstellt einen konsistenten Git-Branch-Namen basierend auf der Task-ID und dem Titel.
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
* **Docker:** Das gesamte Setup ist containerisiert.
|
||||
* **Notion Integration Token:** Ein Notion API-Token mit Zugriff auf Ihre "Projects"- und "Tasks"-Datenbanken.
|
||||
|
||||
## Installation und Einrichtung
|
||||
|
||||
1. **Notion API Key:**
|
||||
* Stellen Sie sicher, dass Sie einen Notion Integration Token haben.
|
||||
* Das Skript fragt beim ersten Start interaktiv nach dem Token. Alternativ kann er als Umgebungsvariable `NOTION_API_KEY` in einer `.env`-Datei im Hauptverzeichnis gespeichert werden.
|
||||
* Gewähren Sie Ihrer Notion-Integration Zugriff auf die relevanten Datenbanken.
|
||||
|
||||
2. **Abhängigkeiten:** Alle Abhängigkeiten sind im `gemini.Dockerfile` definiert und werden automatisch im Container installiert.
|
||||
|
||||
## Der Entwicklungs-Workflow
|
||||
|
||||
Der Workflow ist in drei Hauptphasen unterteilt: Sitzung starten, in der Sitzung arbeiten und Ergebnisse zurückmelden.
|
||||
|
||||
### 1. Sitzung starten
|
||||
|
||||
Der gesamte Startvorgang wird über das `start-gemini.sh`-Skript orchestriert.
|
||||
|
||||
```bash
|
||||
./start-gemini.sh
|
||||
```
|
||||
|
||||
**Was im Hintergrund passiert:**
|
||||
|
||||
1. Das Skript führt `dev_session.py` in einem temporären Docker-Container aus.
|
||||
2. Sie durchlaufen den interaktiven Auswahlprozess für Ihr Projekt und Ihren Task in Notion.
|
||||
3. Nach der Auswahl generiert `dev_session.py` den Kontext, speichert die Session-Informationen (z.B. Task-ID) in `.dev_session/SESSION_INFO`, installiert die Git-Hooks und gibt den Kontext an die Standardausgabe aus.
|
||||
4. `start-gemini.sh` fängt diese Ausgabe ab, extrahiert den Kontext und startet einen neuen, sauberen Docker-Container (`gemini-session`) mit der Gemini CLI, wobei der Kontext als Start-Prompt übergeben wird.
|
||||
|
||||
Dieser Prozess stellt sicher, dass Ihre interaktive Gemini-Sitzung von der Notion-Logik entkoppelt ist und mit allen relevanten Informationen beginnt.
|
||||
|
||||
### 2. Arbeiten in der Gemini CLI
|
||||
|
||||
Nach dem Start befinden Sie sich in der Gemini CLI. Hier findet die eigentliche Entwicklungsarbeit statt.
|
||||
|
||||
* **Commits:** Wenn Sie oder der Agent `git commit` ausführen, greift der `post-commit`-Hook. Er liest die Task-ID aus der Session-Datei und sendet die Commit-Nachricht automatisch als kurzen Kommentar an den verknüpften Notion-Task. Dies sorgt für eine granulare Nachverfolgung des Fortschritts.
|
||||
|
||||
### 3. Fortschritt melden und Änderungen pushen (Agent-gesteuerter Workflow)
|
||||
|
||||
Dies ist der primäre Weg, um ein logisches Arbeitspaket abzuschließen und den Fortschritt zu dokumentieren. Anstatt Git-Befehle und Notion-Updates manuell zu koordinieren, geben Sie dem Agenten eine übergeordnete Anweisung.
|
||||
|
||||
**Beispiel-Anweisung an den Gemini-Agenten:**
|
||||
|
||||
> "Okay, die Implementierung ist abgeschlossen. Fasse die Arbeit zusammen, erstelle einen Statusbericht für Notion, committe alle Änderungen und pushe sie."
|
||||
|
||||
**Was der Agent im Hintergrund tut:**
|
||||
|
||||
1. **Informationen sammeln:** Der Agent führt einen kurzen Dialog mit Ihnen, um den neuen Status (`Bereit für Review`, `Blockiert` etc.) und eventuelle offene To-Dos zu erfragen.
|
||||
2. **Git-Änderungen analysieren:** Der Agent generiert eine Zusammenfassung der geänderten Dateien und der neuen Commit-Nachrichten.
|
||||
3. **Notion-Update (nicht-interaktiv):** Der Agent ruft `dev_session.py` mit den gesammelten Informationen als Parameter auf.
|
||||
```bash
|
||||
python3 dev_session.py --report-status \
|
||||
--status "Ready for Review" \
|
||||
--todos "- Finale Doku prüfen" \
|
||||
--git-changes "..." \
|
||||
--commit-messages "..."
|
||||
```
|
||||
4. **Bericht erstellen:** Das Skript formatiert diese Informationen zu einem sauberen Status-Update, postet es als Kommentar an den Notion-Task und aktualisiert gleichzeitig dessen Status-Feld.
|
||||
5. **Git-Operationen:** Nachdem Notion aktualisiert wurde, führt der Agent die `git add`, `git commit` und `git push` Befehle aus.
|
||||
|
||||
Dieser Prozess stellt sicher, dass der Code-Stand im Repository immer synchron mit dem dokumentierten Fortschritt in Notion ist, ohne dass Sie die Gemini CLI verlassen müssen.
|
||||
|
||||
### 4. Sitzung abschließen
|
||||
|
||||
Wenn der gesamte Task abgeschlossen ist, können Sie die Sitzung über den folgenden Befehl **vom Host-Terminal aus** beenden.
|
||||
|
||||
```bash
|
||||
docker exec -it gemini-session python3 dev_session.py --done
|
||||
```
|
||||
|
||||
Dieser Befehl:
|
||||
* Setzt den Status des Notion-Tasks auf "Done".
|
||||
* Löscht die lokale Session-Datei (`.dev_session/SESSION_INFO`).
|
||||
* Deinstalliert den `post-commit` Git-Hook.
|
||||
|
||||
## Git Branch Benennungs-Konvention
|
||||
|
||||
Das Skript schlägt automatisch einen Git-Branch-Namen vor, der dem Muster `feature/task-{kurze_task_id}-{task_titel_slug}` folgt, um eine direkte Verbindung zwischen Code und Task herzustellen.
|
||||
|
||||
**Beispiel:** `feature/task-2f388f42-update-readme-for-reporting`
|
||||
|
||||
## Entwicklung & Troubleshooting des Start-Skripts
|
||||
|
||||
Das `start-gemini.sh`-Skript wurde entwickelt, um mehrere Herausforderungen zu lösen:
|
||||
|
||||
* **Problem: Fehlende Interaktivität:** Frühe Versionen leiteten die Ausgabe von `dev_session.py` direkt in eine Variable um, was die interaktiven `input()`-Aufforderungen blockierte.
|
||||
* **Lösung:** Einsatz des `tee`-Befehls, der die Ausgabe gleichzeitig auf dem Bildschirm anzeigt und in eine temporäre Datei schreibt, aus der der Kontext später gelesen wird.
|
||||
|
||||
* **Problem: Fehlerhafter Start-Parameter:** Die Gemini CLI erwartet den initialen Prompt über `--prompt-interactive`.
|
||||
* **Lösung:** Korrektur des Arguments im `docker run`-Befehl.
|
||||
|
||||
* **Problem: Konflikt durch nicht aufgeräumte Container:** Vorzeitig beendete Skripte hinterließen Container, die den nächsten Start blockierten.
|
||||
* **Lösung:** Explizite `docker rm -f`-Befehle am Anfang des Skripts, um alte Container zu bereinigen.
|
||||
|
||||
Reference in New Issue
Block a user