故障排除手冊 (Troubleshooting)¶
本文件列出了在使用 Time Compass 過程中可能遇到的常見問題與解決方案。
1. Google OAuth 授權問題¶
❌ 問題：啟動授權時瀏覽器未自動開啟¶
- 原因：作業系統預設瀏覽器設定失效。
- 解法：手動在瀏覽器輸入終端機出現的
http://127.0.0.1:8765URL。 - 注意：Windows 使用者若遇到
localhost連線失敗，請改用127.0.0.1。
❌ 問題：點擊「確定」後出現 "Invalid Grant" 或 "Token Expired"¶
- 原因：之前的
token.json已過期或與現在的credentials.json不匹配。 - 解法：刪除專案根目錄的
token.json並重啟 MCP Server 進行重新授權。
2. Moodle 整合問題¶
❌ 問題：無法獲取 Moodle 事件 (Timeout)¶
- 原因：NTUST Moodle 伺服器對外連線較慢，或網頁結構變動。
- 解法：
- 檢查
.env中的NTUST_ACCOUNT與NTUST_PASSWORD是否正確。 - 嘗試延長請求逾時時間（目前預設為 30 秒）。
3. MCP 與 Planner Studio 網路問題¶
❌ 問題：Planner Studio 啟動失敗 (Port Conflict)¶
- 原因：埠號
8766被其他應用程式佔用。 - 解法：
- 呼叫
shutdown_planner_studio強制關閉舊實例。 - 在
launch_planner_studio時指定其他埠號。
❌ 問題：MCP Inspector 無法載入¶
- 原因：防火牆攔截或
uv環境未啟動。 - 解法：確保執行指令前已執行
uv sync，且使用了正確的本地位址127.0.0.1:6274。
4. 資料渲染問題¶
⚠️ 現象：行事曆事件顯示為「農曆新年 (整天)」但渲染位置偏移¶
- 現狀：系統目前對全天事件 (All-day) 的處理採用 UTC 轉 local。若跨時區可能會有 +-1 天的偏移。
- 解法：請檢查
docs/architecture/data-flow-timing.md確認時間戳處理原則。