Google OAuth 驗證流程（Time Compass）¶

[!WARNING] ☁️ 完整體驗 (Real Data World) | ⏱️ 預計 10-15 分鐘
此文檔屬於「30+ 分鐘完整設置體驗」的 第二步。此前請確認已完成 Google Cloud Project 設定。若您只希望進行 5 分鐘快速體驗（無任何成本），請回到 README 選擇「Mock 模式快速開始」。

本文檔涵蓋如何驗證 Time Compass 的 Google OAuth 授權流程是否可正常讀寫 Google 資料。

驗證流程概述：本步驟確認授權成功 → 產生 token.json → 測試讀寫能力。

[!NOTE] 快速進入？ 若您為評審、或已使用 MCP_DEV_MODE=1，可先以 mock data 驗證流程；正式串接 Google 前仍建議完成本文實測。

簡介：完整驗證流程¶

本指南分為四個主要步驟，從啟動 OAuth 授權，到驗證讀取、聚合與寫入能力。

最終目的: 確認 token.json 可正確產生，且 Google Calendar / Tasks 的讀寫流程在 Time Compass 中可用。

如果你已經熟悉 MCP 與 OAuth 驗證流程¶

如果您已熟悉 MCP 與 OAuth，可先依下列精簡步驟驗證：如果您不熟悉，請直接從下方「準備工作」開始，依序完成完整流程。

TOC - 準備工作 - Step 1：啟動 OAuth 授權流程（擇一） - Step 2：完成瀏覽器授權 - Step 3：驗證讀取與聚合能力 - Step 4：驗證寫入能力（高風險） - 測試方案（建議） - 常見問題（Cloud / CI / Headless） - 完成後檢查清單 - 官方文檔參考

確認 .env 已設定 GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
執行 uv run tools/get_google_token.py，在瀏覽器完成授權
確認專案根目錄已產生 token.json
呼叫 list_calendars（或 list_tasklists）與 get_time_context；需要時再測試 create_task / create_calendar_event

四大步驟概覽¶

這裡先提供流程概覽，幫您快速掌握整體有哪些步驟，以及每一步會帶來的結果。

啟動 OAuth 授權流程
目的與效果：使用 MCP 工具或腳本啟動授權，進入 Google 同意畫面。
完成後您會得到：✅ 授權頁可開啟、流程進入 Google 同意畫面
完成瀏覽器授權
目的與效果：在 Google 頁面登入並同意權限，完成 callback 並產生授權資料。
完成後您會得到：✅ 專案根目錄出現 token.json
驗證讀取與聚合能力
目的與效果：測試 list 與 context 工具，確認資料讀取與聚合流程可用。
完成後您會得到：✅ list_calendars / list_tasklists、get_time_context 正常回傳
驗證寫入能力（高風險）
目的與效果：用測試日曆或清單驗證寫入流程，確認新增資料可在 Google 端追蹤。
完成後您會得到：✅ 寫入成功且資料可追蹤

[!IMPORTANT] 寫入測試請使用「測試用日曆 / 測試用 Task 清單」，避免污染正式資料。

準備工作¶

[!NOTE] 關於「執行」：本指南中的「執行 [指令]」表示： 1. 複製下方框框內的完整指令 2. 貼到終端機中 3. 按下 Enter 鍵執行

確認已完成 Google Cloud 專案設定您會看到：.env 已包含 GOOGLE_CLIENT_ID 與 GOOGLE_CLIENT_SECRET
確認位於專案根目錄您會看到：可看到 tools/ 目錄（含 get_google_token.py）

Step 1：啟動 OAuth 授權流程（擇一）¶

Step 1.1：MCP 工具入口¶

在 AI 端呼叫 launch_google_token_auth
您會看到：工具回傳授權流程資訊，並嘗試開啟瀏覽器授權頁

[!NOTE] 要使用 MCP 工具入口，需先完成 MCP 環境建置或 Mock 模式設置。

Step 1.2：腳本入口（推薦 - 無需 MCP）¶

執行以下指令：
```
uv run tools/get_google_token.py
```
您會看到：終端機顯示授權 URL，並嘗試開啟瀏覽器

Step 2：完成瀏覽器授權¶

開啟 Google 授權頁（若未自動開啟，手動貼上工具輸出的 URL）您會看到：看到 Google 登入/授權頁面
登入並同意 OAuth 權限您會看到：授權流程完成，頁面顯示成功導回或完成提示
確認專案根目錄出現 token.json 您會看到：token.json 存在，且檔案內容非空

Step 3：驗證讀取與聚合能力¶

Step 3.1：讀取能力（建議先做）¶

先定義呼叫
呼叫名稱：list_calendars 或 list_tasklists
呼叫目的：確認 OAuth token 可用，且具備至少一種 Google 讀取能力
成功判準：回傳非空資料，且不是 AUTH_REQUIRED
呼叫 list_calendars 或 list_tasklists 您會看到：回傳非空資料，且不是 AUTH_REQUIRED

Step 3.2：聚合能力¶

先定義呼叫
呼叫名稱：get_time_context
呼叫目的：驗證 Time Compass 可聚合 Google Calendar/Tasks 資料進入統一 context
成功判準：回傳內容含 Google 資料，且非授權錯誤
呼叫 get_time_context 您會看到：回傳內容含 Google 資料，且非授權錯誤

Step 4：驗證寫入能力（高風險）¶

Tasks 寫入測試：呼叫 create_task（或 task draft 寫入流程）您會看到：成功回傳建立結果，Google Tasks 可看到新增項目
Calendar 寫入測試：呼叫 create_calendar_event（或 Planner apply）您會看到：成功回傳建立結果，Google Calendar 可看到新增事件

[!IMPORTANT] 若寫入失敗，優先檢查 OAuth scope、目標日曆/清單權限、以及目前使用帳號是否與 Test Users 一致。

測試方案（建議）¶

Smoke Test（最小可行）¶

專案根目錄可看到 token.json
list_calendars 成功
get_time_context 成功

Functional Test（功能測試）¶

Calendar 讀取/寫入各執行一次
Tasks 讀取/寫入各執行一次
Planner Studio（非 dev mode）可載入 context

Regression Test（回歸測試）¶

刪除 token.json 後重新授權
重啟 MCP/IDE 後再次呼叫工具
驗證 token refresh 後仍可持續使用

常見問題（Cloud / CI / Headless）¶

Redirect URI 不匹配
症狀：redirect_uri_mismatch
原因：Google Console 設定與實際 callback URL 不一致（包含 port/path）
無法開瀏覽器完成授權
症狀：流程卡在等待 callback
原因：雲端或無頭環境缺少互動式瀏覽器
Session / Token 落地策略不相容
症狀：重啟後授權遺失、或多實例行為不一致
原因：仍使用本地 session / token.json，未改為持久化儲存
憑證注入不完整
症狀：啟動即報 GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET missing
原因：執行環境未正確注入環境變數
多租戶或共享機器安全風險
症狀：token 管理混亂、權限邊界不清
原因：共用檔案或 runtime，但未設計隔離機制

完成後檢查清單¶

[ ] token.json 已成功建立
[ ] list_calendars 或 list_tasklists 可正常讀取
[ ] get_time_context 可取得 Google 資料
[ ] Calendar / Tasks 寫入測試至少各成功一次（使用測試資料）
[ ] 未洩露 CLIENT SECRET、token.json 等敏感資訊

下一步：

前往 Gradio Web UI 獨立式，了解如何使用 Web 界面進行完整的時間規劃與任務管理體驗。

官方文檔參考¶

Google OAuth 2.0 for Web Server Applications https://developers.google.com/identity/protocols/oauth2/web-server
Google OAuth Consent Screen 設定 https://developers.google.com/workspace/guides/configure-oauth-consent
Google Calendar API Auth https://developers.google.com/workspace/calendar/api/auth
Google Tasks API Auth https://developers.google.com/tasks/auth