Google Calendar 資料流

回到 資料流索引

層級結構

層	檔案	主要類別/函數
Raw	models_raw.py	GoogleEventRaw (47+ fields), DateTimeRaw, FreeBusyQuery 等
Read	models_read.py	GoogleEventRead (Contains title for UI compatibility)
Core	async_core.py	async_get_all_events(), async_get_calendar_events()
TOON	models_read.py	to_toon_calendar(), to_toon_event(), _build_location_index()
MCP	calendar_tools.py	get_all_calendar_events(), get_event_from_calendar(), list_calendars()

轉換函數詳解

GoogleEventRead.from_dict(data: Dict) → GoogleEventRead

• 輸入：Google Calendar API 原始 JSON dict
• 做了什麼：
• 提取 start/end 中的 dateTime 或 date，用 to_datetime() 轉為 Python datetime
• 將 datetime 透過 format_for_llm() 轉為 UTC+8 的 "YYYY-MM-DD HH:MM" 字串
• 處理 reminders（覆寫 → popup:10m / 預設 → default）
• 處理 recurrence（若為 list 取第一個 RRULE 字串，並轉換為人類可讀格式）
• 處理 originalStartTime（改期事件的原始起始時間）
• 全天事件偵測：優先檢查 start.date 欄位，次要檢查 08:00 邊界（雙重魯棒性）
• Source ID：保留 id 欄位以支持後續操作（如刪除、更新事件）

GoogleEventRead.from_raw_model(obj: Any) → GoogleEventRead

• 輸入：dict、GoogleEventRead 本身、或任何有 id+summary 屬性的物件
• 做了什麼：多態分派 — 自動判斷輸入類型並路由到 from_dict() 或直接回傳

GoogleEventRead.from_raw(raw: Any) → GoogleEventRead

• ⚠️ Deprecated：相容舊程式碼的適配器，內部委派給 from_dict() 或 from_raw_model()

to_toon_event(event: GoogleEventRead, location_map, recurrence_map) → dict

• 做了什麼：將單一事件壓縮為 TOON 格式，包含 summary, st_hm, en_hm 等，並處理全天事件邏輯。

to_toon_calendar(events, calendar_name, calendar_id) → dict

• 輸入：List[GoogleEventRead] + 日曆名稱/ID
• 做了什麼：
• 呼叫 _build_location_index() 建立地點縮寫表（loc_1, loc_2...）
• 按月份分組事件
• 每個事件透過 to_toon_event() 壓縮
• 回傳 {name, id, location_index, month} 結構

_build_location_index(events) → dict

• 做了什麼：掃描所有事件的 location，建立 {"臺科大 TR-510 教室": "loc_1"} 的去重索引

list_calendars 工具

list_calendars 不經過 TOON 轉換函數，直接在 Tool 層組裝：

_list_writable_calendars() → {calendars: [{id, summary, primary, accessRole}]} → safe_encode()

回傳的 TOON 結構僅包含 calendars 陣列（無 count 欄位，TOON 的 key[N] 語法已包含數量資訊）。