paulstraw/g-scheduler

g-scheduler 是做什麼的？

找出每位參與者都有空且位於其工作時間內的會議時段，然後（僅在被要求時）建立邀請。兩個內建腳本負責處理 Google API 呼叫與時間計算。切勿自行處理時區或夏令時間算術：請直接使用腳本輸出。

使用 python3（在 Windows 上使用 python 或 py）從此技能的目錄執行腳本：scripts/gcal.py 和 scripts/slots.py。它們需要 Python 3.9 以上版本。

1. 檢查存取權

執行 python3 scripts/gcal.py check。

• 如果執行失敗，原因是缺少 gws 或未登入，或者 Python 錯誤要求安裝 tzdata，請停止並逐步引導使用者完成 SETUP.md。沒有它就無法繼續。
• 如果成功，請繼續。my_working_hours: "not set" 是正常的。

2. 收集輸入

• 參與者： 將所有人解析為 Google Workspace 電子郵件地址。對於沒有電子郵件的名稱，執行 python3 scripts/gcal.py find "Ada Lovelace" "Grace"，它會搜尋組織目錄；你擁有的其他工具（Slack、使用者的訊息）也可用。如果 find 失敗（缺少範圍、accessNotConfigured，或管理員已停用目錄分享），表示無法查詢名稱：說明原因一次，指引至 SETUP.md 的疑難排解，然後使用其他工具。如果電子郵件遺失、不明確或看似位於使用者組織之外，請提問。使用者會自動被加入；僅在使用者表示不會參加時才傳遞 --exclude-me。
• 日期範圍： 保持簡單。「接下來兩週」表示從今天到大約 18 天後（較近的時段已優先排序）。特定日期就只表示那一天。日期格式為 YYYY-MM-DD；結束日期包含在內。
• 長度： 預設為 60 分鐘。無需詢問；告知使用者你已假定此值。
• 選擇性參與者： 不要預先詢問。將所有人視為必要。

3. 尋找時段

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

gather 選項：--duration MIN、--optional EMAIL（可重複）、--exclude-me、--time-zone TZ（預設為使用者的日曆時區，也用於排序與顯示）。

輸出包含 slots（最多 5 個，每天最多 2 個，最早優先）、all_required_free、attendees 和 warnings。每個時段包含每位參與者所在地時間與使用者時區的時間、missing、missing_optional 以及 at_day_edge（對該參與者而言，此時段位於其工作日的首 30 分鐘或末 30 分鐘）。

讀取整個輸出。不要過濾它（例如使用 jq 或 python -c），因為這會遺漏 warnings。

若要檢查特定時間（使用者提出一個時間、時段未列出，或後來加入參與者），請對所有參與者執行相同的管線，並將 --start 和 --end 設定為該會議的確切時間，格式為帶偏移的 RFC3339 時間：--start 2026-11-19T11:00:00-08:00 --end 2026-11-19T12:00:00-08:00。輸出中的單一時段會顯示誰無法參加。切勿自行從原始忙碌時間判斷可用性。

4. 呈現結果

• 以使用者時區列出時段，並在時區不同時顯示每位參與者的當地時間。
• 用白話文重複每個警告。指出那些工作時間被假設為當地時間週一至週五 09:00-17:00 的人，以及那些因為日曆無法讀取而未被納入的人。
• 如果使用者未提供會議長度，請說明假設的長度。
• 如果 all_required_free 為 false，請指出每個時段中誰無法參加，並詢問是否要將他們中的某些人設為 --optional 重新執行。只有使用者能決定誰是選擇性參與者；切勿自行將任何人標記為選擇性。
• 如果 slots 為空，請說明並建議更廣的範圍或更短的會議。

5. 建立邀請（僅在被要求時）

1. 根據上下文草擬標題，以及包含來源連結（例如 Slack 討論串）的簡短描述。

2. 詢問是否要加入視訊會議連結。如果提供，請將其放入 location 和描述中。不要建立 Meet 或 Zoom 會議。

3. 顯示確切活動（標題、當地時間、參與者、描述、地點），並等待明確的「是，請發送」。發送會通知每個人，且無法復原。

4. 將活動寫入臨時 JSON 檔案，格式為日曆 Events 資源，時間使用使用者時區：

   {
     "summary": "專案啟動會議",
     "description": "從 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. 執行 python3 scripts/gcal.py invite EVENT.json。它總是會向所有參與者發送邀請。如果你只想檢查請求，請先使用 --dry-run。

6. 提供使用者輸出中的 htmlLink，然後刪除臨時檔案。

規則

• 除了 invite 之外，所有操作皆為唯讀。切勿更改任何人的日曆或工作時間。
• 未經使用者明確確認預覽的活動，切勿發送邀請。
• 如果某時區的時間看起來差了一個小時，可能是機器上的時區資料過舊（時區規則會變動，例如 2026 年加拿大英屬哥倫比亞省的變更）。請參閱 SETUP.md 的疑難排解。