paulstraw/g-scheduler

Was macht g-scheduler?

Finde Besprechungszeitfenster, in denen alle Teilnehmer frei und innerhalb ihrer Arbeitszeiten sind, und erstelle (nur wenn explizit gefragt) die Einladung. Zwei gebündelte Skripte erledigen die Google-Aufrufe und die Zeitberechnung. Führe niemals selbst Zeitzonen- oder DST-Arithmetik durch; verwende stattdessen deren Ausgabe.

Führe die Skripte mit python3 (unter Windows python oder py) aus dem Verzeichnis dieser Fähigkeit aus: scripts/gcal.py und scripts/slots.py. Sie benötigen Python 3.9+.

1. Zugriff prüfen

Führe python3 scripts/gcal.py check aus.

• Wenn es fehlschlägt, weil gws fehlt oder nicht angemeldet ist, oder ein Python-Fehler nach tzdata fragt, stoppe und führe den Benutzer Schritt für Schritt durch die SETUP.md. Ohne sie kann nicht fortgefahren werden.
• Wenn es erfolgreich ist, fahre fort. my_working_hours: "not set" ist in Ordnung.

2. Eingaben sammeln

• Teilnehmer: Löse alle zu Google Workspace-E-Mail-Adressen auf. Für Namen ohne E-Mail führe python3 scripts/gcal.py find "Ada Lovelace" "Grace" aus, das das Organisationsverzeichnis durchsucht; andere dir verfügbare Tools (Slack, die Nachricht des Benutzers) funktionieren ebenfalls. Wenn find fehlschlägt (fehlender Bereich, accessNotConfigured oder der Administrator hat die Verzeichnisfreigabe deaktiviert), ist die Namenssuche nicht verfügbar: erwähne den Grund einmal, verweise auf die Fehlerbehebung in SETUP.md und verwende andere Tools. Wenn eine E-Mail fehlt, mehrdeutig ist oder außerhalb der Organisation des Benutzers zu liegen scheint, frage nach. Der Benutzer wird automatisch hinzugefügt; verwende --exclude-me nur, wenn er sagt, dass er nicht teilnehmen wird.
• Zeitraum: Bleibe einfach. „Nächste 2 Wochen“ bedeutet heute bis etwa 18 Tage in der Zukunft (frühere Slots werden zuerst aufgeführt). Ein bestimmter Tag bedeutet genau diesen Tag. Daten sind YYYY-MM-DD; das Enddatum ist inklusive.
• Dauer: Standard 60 Minuten. Frage nicht; sage, dass du sie angenommen hast.
• Optionale Personen: Frage nicht im Voraus. Behandle alle als erforderlich.

3. Slots finden

python3 scripts/gcal.py gather [email protected] [email protected] --start 2026-11-10 --end 2026-11-27 \
  | python3 scripts/slots.py

Optionen für gather: --duration MIN, --optional EMAIL (wiederholbar), --exclude-me, --time-zone TZ (standardmäßig die Zeitzone des Kalenders des Benutzers, die auch für die Sortierung und Anzeige verwendet wird).

Die Ausgabe enthält slots (bis zu 5, maximal 2 pro Tag, die frühesten zuerst), all_required_free, attendees und warnings. Jeder Slot hat local-Zeiten für jeden Teilnehmer und die Zeitzone des Benutzers, missing, missing_optional und at_day_edge (Personen, für die es in den ersten oder letzten 30 Minuten ihres Tages liegt).

Lies die gesamte Ausgabe. Filtere sie nicht (z. B. mit jq oder python -c), da dadurch warnings verloren gehen.

Um eine bestimmte Zeit zu überprüfen (der Benutzer schlägt eine Zeit vor, ein Slot wird nicht aufgelistet oder ein Teilnehmer wird später hinzugefügt), führe dieselbe Pipeline für alle Teilnehmer mit --start und --end aus, die genau auf dieses Meeting als RFC3339-Zeiten mit Offset gesetzt sind: --start 2026-11-19T11:00:00-08:00 --end 2026-11-19T12:00:00-08:00. Der einzelne Slot in der Ausgabe sagt, wer fehlt. Ermittle niemals selbst die Verfügbarkeit aus rohen belegten Zeiten.

4. Ergebnisse präsentieren

• Liste die Slots in der Zeitzone des Benutzers auf, mit der lokalen Zeit jedes Teilnehmers, wenn die Zeitzonen unterschiedlich sind.
• Wiederhole jede Warnung in einfachen Worten. Nenne Personen, deren Arbeitszeiten angenommen wurden (09:00-17:00 Werktage in ihrer Zeitzone) und alle, die ausgeschlossen wurden, weil ihr Kalender nicht gelesen werden konnte.
• Gib die angenommene Länge an, wenn der Benutzer keine angegeben hat.
• Wenn all_required_free falsch ist, sage, wer bei jedem Slot fehlt, und frage, ob erneut mit einigen von ihnen als --optional ausgeführt werden soll. Nur der Benutzer entscheidet, wer optional ist; markiere niemals selbst jemanden als optional.
• Wenn slots leer ist, sage es und schlage einen größeren Bereich oder ein kürzeres Meeting vor.

5. Einladung erstellen (nur wenn gefragt)

1. Verfasse einen Titel aus dem Kontext und eine kurze Beschreibung, die den Quelllink (z. B. den Slack-Thread) enthält, falls vorhanden.

2. Frage, ob ein Videokonferenzlink hinzugefügt werden soll. Wenn angegeben, setze ihn in location und in die Beschreibung. Erstelle keine Meet- oder Zoom-Meetings.

3. Zeige das genaue Ereignis (Titel, lokale Zeit, Teilnehmer, Beschreibung, Ort) und warte auf ein explizites „Ja, sende es ab“. Das Versenden benachrichtigt alle und kann nicht rückgängig gemacht werden.

4. Schreibe das Ereignis in eine temporäre JSON-Datei als Calendar-Events-Ressource, mit Zeiten in der Zeitzone des Benutzers:

   {
     "summary": "Projekt Kick-off",
     "description": "Geplant von https://example.slack.com/archives/...",
     "location": "https://zoom.us/j/123",
     "start": {"dateTime": "2026-11-18T10:00:00", "timeZone": "America/Los_Angeles"},
     "end": {"dateTime": "2026-11-18T11:00:00", "timeZone": "America/Los_Angeles"},
     "attendees": [{"email": "[email protected]"}, {"email": "[email protected]"}]
   }
   

5. Führe python3 scripts/gcal.py invite EVENT.json aus. Es sendet immer Einladungen an alle Teilnehmer. Verwende zuerst --dry-run, wenn du die Anfrage überprüfen möchtest.

6. Gib dem Benutzer den htmlLink aus der Ausgabe und lösche die temporäre Datei.

Regeln

• Alles außer invite ist schreibgeschützt. Ändere niemals den Kalender oder die Arbeitszeiten einer Person.
• Sende niemals eine Einladung ohne die explizite Bestätigung des Benutzers für das Vorschau-Ereignis.
• Wenn Zeiten für eine Zone um eine Stunde abweichen, sind die Zeitzonendaten des Rechners wahrscheinlich veraltet (Zonenregeln ändern sich, wie es British Columbia 2026 tat). Siehe Fehlerbehebung in SETUP.md.