feat(dev_session): Add agent-driven Notion status reporting
Implements the functionality in , allowing the Gemini agent to non-interactively update a Notion task with a detailed progress summary. The agent can now be prompted to: - Collect the new task status and any open to-dos. - Generate a summary of Git changes () and commit messages. - Post a formatted report as a comment to the Notion task. - Update the task's status property. The has been updated to document this new agent-centric workflow, detailing how to start a session, work within it, and use the agent to report progress and push changes seamlessly.
This commit is contained in:
@@ -2,40 +2,41 @@
|
||||
|
||||
## Übersicht
|
||||
|
||||
`dev_session.py` ist ein interaktives Kommandozeilen-Tool (CLI), das den Entwicklungs-Workflow durch die Integration mit Notion optimiert. Es ermöglicht Entwicklern, ein Projekt und einen Task auszuwählen und den Task-Status automatisch zu aktualisieren.
|
||||
`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 generiert es einen formatierten Kontext und gibt diesen auf der Standardausgabe aus. Das übergeordnete `start-gemini.sh`-Skript fängt diesen Kontext auf und startet dann die Gemini CLI in einer sauberen, interaktiven Sitzung mit dem korrekten Startkontext. Dieser zweistufige Prozess stellt sicher, dass die Gemini CLI mit allen erforderlichen Tools und in der korrekten Umgebung läuft.
|
||||
**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.
|
||||
* **Automatisches Status-Update:** Der Status des ausgewählten Tasks wird automatisch auf 'Doing' (oder den ersten verfügbaren Status in neuen Projekten) gesetzt, um deinen Fortschritt in Notion widerzuspiegeln.
|
||||
* **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.
|
||||
* **Dynamische Status-Erkennung:** Fragt Notion API nach verfügbaren Status-Optionen ab, um Kompatibilität mit verschiedenen Notion-Templates zu gewährleisten.
|
||||
* **Gemini CLI Kontext-Generierung:** Erzeugt einen strukturierten Kontext-Prompt, der alle relevanten Informationen (Projekt, Task, Task-ID, vorgeschlagener Git-Branch-Name) für die Gemini CLI enthält.
|
||||
* **Vorgeschlagene Git Branch-Benennung:** Erstellt einen konsistenten Git-Branch-Namen basierend auf der Task-ID und dem Task-Titel.
|
||||
* **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, um Abhängigkeitskonflikte zu vermeiden.
|
||||
* **Docker:** Das gesamte Setup ist containerisiert.
|
||||
* **Notion Integration Token:** Ein Notion API-Token mit Zugriff auf Ihre "Projects"- und "Tasks"-Datenbanken.
|
||||
|
||||
## Installation und Einrichtung
|
||||
|
||||
Das Setup ist so konzipiert, dass es mit minimalem Aufwand sofort einsatzbereit ist.
|
||||
|
||||
1. **Notion API Key:**
|
||||
* Stellen Sie sicher, dass Sie einen Notion Integration Token haben.
|
||||
* Das Skript fragt beim ersten Start interaktiv nach dem Token. Sie können es auch als Umgebungsvariable `NOTION_API_KEY` in einer `.env`-Datei im Hauptverzeichnis speichern, um diesen Schritt zu überspringen.
|
||||
* Gewähren Sie Ihrer Notion-Integration Zugriff auf die relevanten "Projects"- und "Tasks"-Datenbanken.
|
||||
* 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 notwendigen Abhängigkeiten (Python, `requests`, `python-dotenv`) sind im Dockerfile (`gemini.Dockerfile`) definiert und werden automatisch im Container installiert. Es ist keine manuelle Installation via `pip` erforderlich.
|
||||
2. **Abhängigkeiten:** Alle Abhängigkeiten sind im `gemini.Dockerfile` definiert und werden automatisch im Container installiert.
|
||||
|
||||
## Nutzung
|
||||
## Der Entwicklungs-Workflow
|
||||
|
||||
Der Workflow ist in drei Hauptphasen unterteilt: Sitzung starten, in der Sitzung arbeiten und Ergebnisse zurückmelden.
|
||||
|
||||
### 1. Sitzung starten
|
||||
|
||||
Das `start-gemini.sh`-Skript orchestriert den gesamten Startvorgang.
|
||||
Der gesamte Startvorgang wird über das `start-gemini.sh`-Skript orchestriert.
|
||||
|
||||
```bash
|
||||
./start-gemini.sh
|
||||
@@ -44,104 +45,72 @@ Das `start-gemini.sh`-Skript orchestriert den gesamten Startvorgang.
|
||||
**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 Projekt und Task wie gewohnt.
|
||||
3. Nach Ihrer Auswahl gibt `dev_session.py` den generierten Kontext für die Gemini CLI aus und beendet sich.
|
||||
4. `start-gemini.sh` fängt diese Ausgabe ab und extrahiert den Kontext.
|
||||
5. Anschließend startet das Skript einen neuen, sauberen Docker-Container mit der Gemini CLI und übergibt den extrahierten Kontext als Start-Prompt.
|
||||
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-API-Logik entkoppelt ist und in einer stabilen Umgebung läuft.
|
||||
Dieser Prozess stellt sicher, dass Ihre interaktive Gemini-Sitzung von der Notion-Logik entkoppelt ist und mit allen relevanten Informationen beginnt.
|
||||
|
||||
### 2. Sitzung abschließen
|
||||
### 2. Arbeiten in der Gemini CLI
|
||||
|
||||
Wenn Sie die Arbeit an einem Task beendet haben, können Sie die Sitzung über den folgenden Befehl abschließen. Dieser Befehl muss **im Terminal des Hosts** ausgeführt werden, während der Container (`gemini-session`) noch läuft.
|
||||
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" (oder den finalen Status in Ihrer Konfiguration).
|
||||
* Löscht die lokale Session-Datei (`.session_info.json`).
|
||||
* Deinstalliert den Git-Hook.
|
||||
|
||||
### 3. Automatisches Notion-Feedback (Git-Hook)
|
||||
|
||||
Beim Starten einer Sitzung wird automatisch ein `post-commit`-Git-Hook installiert.
|
||||
|
||||
* **Funktion:** Nach jedem `git commit` wird die Commit-Nachricht automatisch als Kommentar an den verknüpften Notion-Task gesendet.
|
||||
* **Voraussetzung:** Funktioniert nur für Commits, die im `gemini-session`-Container oder auf dem Host-System (mit installiertem `requests`) gemacht werden, während die Session aktiv ist.
|
||||
* **Deinstallation:** Der Hook wird beim Abschluss der Sitzung mit `--done` automatisch wieder entfernt.
|
||||
|
||||
### Beispiel-Interaktion (gekürzt)
|
||||
|
||||
Die interaktive Auswahl von Projekt und Task bleibt unverändert:
|
||||
|
||||
```
|
||||
Starte interaktive Entwicklungs-Session...
|
||||
Bitte gib deinen Notion API Key ein (Eingabe wird nicht angezeigt): ****************
|
||||
Suche nach Datenbank 'Projects [UT]' in Notion...
|
||||
Datenbank 'Projects [UT]' gefunden mit ID: <PROJEKTE_DB_ID>
|
||||
|
||||
An welchem Projekt möchtest du arbeiten?
|
||||
[1] My Awesome Project
|
||||
[2] Sync Engine
|
||||
[...]
|
||||
Bitte wähle eine Nummer: 2
|
||||
...
|
||||
```
|
||||
|
||||
Nach der Auswahl wird automatisch die Gemini CLI gestartet.
|
||||
* 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.
|
||||
* `feature/task-`: Ein Präfix, das den Branch-Typ und die Beziehung zu einem Notion-Task anzeigt.
|
||||
* `{kurze_task_id}`: Die ersten 8 Zeichen der Notion Task ID, für eine eindeutige Referenz.
|
||||
* `{task_titel_slug}`: Eine "Slugified"-Version des Task-Titels (Kleinbuchstaben, Leerzeichen durch Bindestriche ersetzt, Sonderzeichen entfernt).
|
||||
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-create-readmemd-for-devsessionpy`
|
||||
|
||||
## Wichtige Hinweise
|
||||
|
||||
* Stelle sicher, dass deine Notion-Datenbanken die Property `Status` mit mindestens einer Statusoption haben.
|
||||
* Der `Readme Path` wird dynamisch aus dem in Notion ausgewählten Projekt geladen. Falls in Notion kein spezifischer Pfad hinterlegt ist, wird standardmäßig `readme.md` verwendet. Dies eliminiert die Notwendigkeit einer manuellen `project_to_path_map` im Skript.
|
||||
**Beispiel:** `feature/task-2f388f42-update-readme-for-reporting`
|
||||
|
||||
## Entwicklung & Troubleshooting des Start-Skripts
|
||||
|
||||
Das Start-Skript (`start-gemini.sh` und die Entwicklungsversion `start-gemini-dev.sh`) hat mehrere Iterationen durchlaufen, um die aktuelle, stabile Funktionalität zu erreichen. Die wesentlichen Herausforderungen und deren Lösungen sind hier dokumentiert.
|
||||
Das `start-gemini.sh`-Skript wurde entwickelt, um mehrere Herausforderungen zu lösen:
|
||||
|
||||
### Problem 1: Fehlende Interaktivität
|
||||
* **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.
|
||||
|
||||
Die erste Version des Skripts hat die Ausgabe von `dev_session.py` direkt in eine Variable umgeleitet (`OUTPUT=$(docker run ...)`), um den Kontext für Gemini zu extrahieren.
|
||||
* **Problem: Fehlerhafter Start-Parameter:** Die Gemini CLI erwartet den initialen Prompt über `--prompt-interactive`.
|
||||
* **Lösung:** Korrektur des Arguments im `docker run`-Befehl.
|
||||
|
||||
* **Problem:** Die interaktiven `input()`-Aufforderungen von Python wurden nicht im Terminal des Benutzers angezeigt, da die Standardausgabe (stdout) vollständig in die Variable geschrieben wurde. Die Sitzung schien zu hängen.
|
||||
* **Lösung:** Umstellung auf den `tee`-Befehl. Der `docker run`-Befehl wird nun so ausgeführt, dass seine Ausgabe gleichzeitig (`tee`) auf dem Bildschirm angezeigt UND in eine temporäre Datei geschrieben wird. Nachdem der Benutzer seine Auswahl getroffen hat, wird der Kontext aus dieser temporären Datei ausgelesen.
|
||||
* **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.
|
||||
|
||||
```bash
|
||||
# Gekürztes Beispiel
|
||||
TEMP_FILE=$(mktemp)
|
||||
docker run -it ... python3 dev_session.py | tee "$TEMP_FILE"
|
||||
CLI_CONTEXT=$(sed ... "$TEMP_FILE")
|
||||
rm "$TEMP_FILE"
|
||||
```
|
||||
|
||||
### Problem 2: Fehlerhafter Start-Parameter für Gemini
|
||||
|
||||
Die Gemini CLI erwartet den initialen Prompt über das Argument `--prompt-interactive`.
|
||||
|
||||
* **Problem:** Falsche Verwendung von `--initial-prompt` führte zu einem Fehler und verhinderte, dass der Kontext korrekt an die CLI übergeben wurde.
|
||||
* **Lösung:** Korrektur des Arguments im `docker run`-Befehl für die Gemini CLI zu `--prompt-interactive`.
|
||||
|
||||
### Problem 3: Konflikt durch nicht aufgeräumte Container
|
||||
|
||||
Der interaktive `docker run`-Befehl für `dev_session.py` erstellte einen temporären Container (z.B. `gemini-dev-session-temp`).
|
||||
|
||||
* **Problem:** Wenn das Skript vorzeitig beendet wurde, blieb dieser Container bestehen und blockierte den nächsten Start mit einem "container name already in use"-Fehler.
|
||||
* **Lösung:** Am Anfang des Start-Skripts wurde eine explizite Aufräum-Anweisung hinzugefügt, die sowohl den Haupt-Container als auch den temporären Container vor dem Start entfernt.
|
||||
|
||||
```bash
|
||||
docker rm -f "gemini-dev-session" > /dev/null 2>&1
|
||||
docker rm -f "gemini-dev-session-temp" > /dev/null 2>&1
|
||||
```
|
||||
|
||||
Diese Anpassungen haben zu dem robusten, zweistufigen Startprozess geführt, der nun eine nahtlose interaktive Auswahl und den anschließenden Start der Gemini CLI ermöglicht.
|
||||
|
||||
Reference in New Issue
Block a user