核心用法
taiwan-calendar 是專為台灣地區設計的行政曆查詢工具，透過串接政府開放資料 API，即時取得最新、最準確的國定假日與工作日資訊。主要功能涵蓋：
- 基礎查詢：確認今日日期與工作日狀態（
today）、檢視特定日期屬性（check <date>） - 區間計算：統計日期範圍內的工作日數量（
range <start> <end>），列出期間所有假日 - 進階運算：推算 N 個工作日後的日期（
add-days [date] <n>）、尋找下一個工作日或假日
資料來源為台灣政府開放資料平台（data.gov.tw）與新北市開放資料作為備援，採用 1 小時快取機制兼顧即時性與效能。所有時間均採用台灣時區（Asia/Taipei, UTC+8）。
顯著優點
1. 權威數據：直接對接政府官方 API，避免民間日曆資料的誤差或更新延遲
2. 解決 AI 痛點：有效彌補 Claude 知識截止限制，杜絕「把週二說成週三」或不知當年連假安排的錯誤
3. 完整情境支援：特別處理台灣特有的「補班日」文化，支援跨假日的工作日計算（如「五個工作天後」）
4. 多格式輸入：支援 ISO 標準格式、斜線分隔，甚至無年份的簡寫（自動判定當年）
5. 離線容錯：API 失效時自動啟用備援來源，並可使用過期快取提供降級服務
潛在缺點與侷限性
- 地域限制：僅支援台灣行政曆，無法處理中國大、港澳、日本等其他地區的調休制度
- 曆法限制：不支援農曆（農民曆）查詢、二十四節氣，亦無法查詢歷史年份資料
- 網路依賴：首次使用或快取過期時需連線，雖有備援機制但仍可能受政府 API 穩定性影
- 中文介面：腳本輸出為繁體中文，若用戶需英文回覆需額外轉譯
適合人群
- 台灣上班族：需確認補班日、規劃請假連假的職場工作者
- 專案管理者：計算工作日 deadline、排程需排除國定假日的團隊
- 客服與行政人員：需快速查詢營業日、回覆客戶日期相關詢問
- 任何使用繁體中文的台灣用戶：對「這個月有幾個工作日」有即時查詢需求者
常規風險
| 風險類型 | 說明建議 |
|---------|-----------|
| 資料時效 | 政府 API 可能因年度公告時程而有短暫空窗（通常於前一年年底公布次年曆）。快取過期後若 API 未更新，可能短暫無法查詢新年度資料 |
| 邊界案例 | 極少數「彈性放假」或「颱風假」屬於行政機關自行公告，可能未被納入固定曆檔。建議重大日期仍需與人事行政總處公告交叉確認 |
| 執行環境 | 依賴 Python + `uv` 執行環境，若用戶系統未正確配置可能遇到執行錯誤。須嚴格遵守 `uv run --managed-python` 前綴指令 |
整體而言，此工具在台灣日期查詢場景具備極高實用價值，是彌補通用型 AI 知識缺口的高信賴解決方案。