---
name: flight-to-calendar
description: 把已訂的航班行程加進使用者的 Google Calendar，一段航班建一個事件、正確處理跨時區、傍晚抵達或清晨起飛的航段標夕陽/日出座位。當使用者提供機票訂位 / e-ticket / PNR / 航班明細（或指向一個訂位檔），並說「把航班加到行事曆」「行程上 calendar」「加這趟飛機到日曆」之類時使用。 English triggers: "add my flights to the calendar", "put the trip on my calendar", "add this flight to my calendar".
---

# flight-to-calendar — 航班上行事曆

把使用者**已經訂好**的航班行程加進 Google Calendar。

> 🤖 R2-D2 時刻：astromech droid 的本職就是導航 —— 算航線、記座標、
> 在 Luke 分心的時候把該記的都記好。

## 🚦 鐵則（每一條都是踩過坑換來的）

1. **絕不編造航班**。所有航班號、起降時刻、機型一律來自使用者提供的訂位明細或檔案。缺哪一段、哪個時間沒寫 → **直接問**，不要猜、不要用「常見班表」腦補。動手前先把每段資料對齊。

2. **一段航班 = 一個事件**。經轉機的去程 = 2 個事件，中間的轉機空檔就會自然顯示在行事曆上。不要把整趟塞成一個大事件。

3. **跨時區處理（最容易錯，務必照做）**：
   - 每個事件的 `timeZone` = **出發機場**的 IANA 時區。
   - `startTime` = 出發地當地時刻；`endTime` = **把抵達地當地時刻換算回「出發時區」**後的時刻（這樣事件時長才正確）。
   - ⚠️ 不同機場時區可能不同，鄰近國家尤其小心（+9 vs +8 這種一小時差最會漏）：
     - **UTC+8**：台北 TPE / 香港 HKG / 馬尼拉 MNL / 上海 PVG / 吉隆坡 KUL / 新加坡 SIN
     - **UTC+9**：首爾 ICN / 東京 NRT·HND / 大阪 KIX / 名古屋 NGO / 福岡 FUK / 札幌 CTS
     - **UTC+7**：曼谷 BKK / 河內 HAN / 胡志明 SGN / 雅加達 CGK
   - Google 會依使用者「當下所在時區」自動換算顯示，所以只要存進去的**時刻點（instant）正確**就好；當地時刻寫進描述欄供對照。

   **換算範例**（CX418 HKG 14:25 → ICN 19:05）：
   - HKG 是 +8、ICN 是 +9。
   - `timeZone` = `Asia/Hong_Kong`、`startTime` = `...T14:25:00`。
   - 抵達 ICN 當地 19:05（+9）換回 HKG（+8）= **18:05** → `endTime` = `...T18:05:00`。
   - 時長 = 3h40m（正確）；描述欄註明「抵 ICN 當地 19:05（KST/UTC+9）」。

4. **標題格式**：`✈️ <航班號> <出發機場>→<抵達機場>（<PNR>）`
   - 預設**不寫艙等**（行事曆是給自己看的，不是炫耀用的；使用者要就照加）。
   - 例：`✈️ CX489 TPE→HKG（D8M7E7）`

5. **夕陽 / 日出座位**：若航段會撞到 magic hour（傍晚抵達看夕陽、清晨起飛看日出），算出該坐哪側並標在標題或描述。
   - 原則（夕陽＝太陽在西）：往**東北**飛→**左(A)**；往**東南**→**右(K)**；往**西南**→**右(K)**；往**西北**→**左(A)**；正東/正西兩側皆可。
   - **日出（太陽在東）一律反過來**。
   - 已知例：HKG→TPE（東北）夕陽左(A)、HKG→MNL（東南）夕陽右(K)。

6. **顏色**：`colorId` = `7`（Peacock 藍綠），統一標航班，一眼掃出旅程。

7. **描述欄**放：航班號＋機型、起降機場（含航廈）＋當地時刻、PNR、與前後段的接續關係、夕陽提示、跨時區註記。

## 步驟

1. **取資料**：對每一段航班，確認 航班號、出發機場（含航廈）、抵達機場（含航廈）、當地起降時刻、機型、PNR。資料若在某個檔案（e-ticket、行程主檔），先讀檔逐段核對；不確定就問使用者。
2. **算時區**：每段定 `timeZone`（出發機場）、`startTime`（出發當地）、`endTime`（抵達當地換回出發時區）。
3. **逐段建立**：用 Google Calendar 的 `create_event`（預設主行事曆）建每一段；可在一則訊息裡並行建多段。
4. **回報**：建完回貼每個事件的連結＋一句重點（總段數、跨時區段的「當地 vs 顯示」提醒、夕陽座位）。

## 工具需求

- **Google Calendar MCP**（connector）的 `create_event` / `update_event` —— 這是本 skill 的硬依賴，沒接 Calendar connector 跑不了。
- 若為 deferred 工具，先用 ToolSearch 以 `select:...create_event` 載入。
- 預設主行事曆，除非使用者指定別的 calendar。

## 注意

- 這是把**已訂航班**登錄上行事曆，不是訂票、不是改票 → 不需要付款/外部送出動作，直接建事件即可。
- 若使用者後續要改時間/刪行程，用 `update_event` / 刪除，沿用同樣的時區與標題規則。