Gradio Web UI 獨立啟動教學（time-compass-gradio）¶

[!WARNING] ☁️ 完整體驗 (Real Data World) | ⏱️ 預計 5-10 分鐘
此文檔屬於「30+ 分鐘完整設置體驗」的 第三步。請確認已完成： 1. Google Cloud Project 設定(至少必須完成第一階段: 建立專案) 2. OAuth 驗證流程
3. Gemini API 設定（啟用 Gradio AI 功能必要條件） 4. litellm-proxy 設定（極度推薦）若您只希望進行 5 分鐘快速體驗（無任何成本），請回到 README 選擇「Mock 模式快速開始」。

本文檔涵蓋如何使用 time-compass-gradio 啟動 Time Compass 的 Gradio Web UI，進行 Web 介面的時間規劃與任務管理。

[!NOTE] time-compass-gradio 對應 entrypoint 為 time_compass.interface.server:main，預設啟動在 127.0.0.1:8000，並將 UI 掛載在 /gradio。

簡介：完整設定流程¶

本指南分為 4 個主要步驟，從啟動服務到驗證 Gradio 各分頁可操作。

最終目的: 成功開啟 http://127.0.0.1:8000/gradio，並確認主要 Tab 可互動。

如果你已經熟悉 Gradio 啟動流程¶

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

TOC - 準備工作 - Step 1：啟動 time-compass-gradio - Step 2：驗證獨立測試範圍 - Step 3：呼叫與啟動方式補充 - Step 4：關閉與故障排除 - 完成後檢查清單 - 官方文檔參考

進入專案根目錄並確認依賴已安裝（uv sync）。
執行 uv run time-compass-gradio。
在瀏覽器開啟 http://127.0.0.1:8000/gradio。
檢查頁面可見 OAuth / Debug / Google Tasks / Scheduling / Moodle 等區塊。

4 大步驟概覽¶

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

確認執行環境
目的與效果：確認可使用專案腳本啟動，避免因依賴或路徑問題造成啟動失敗。
完成後您會得到：✅ 可執行的 Gradio 啟動環境
啟動 Gradio Server
目的與效果：使用 time-compass-gradio entrypoint 啟動本地服務與 UI。
完成後您會得到：✅ 本地 Gradio Web UI
驗證 UI 可用性
目的與效果：確認路由與頁面載入正確，確保測試流程可重現。
完成後您會得到：✅ 可重現的 UI 測試流程
關閉與故障排除
目的與效果：安全停止服務並排除常見錯誤，維持可持續的本地測試流程。
完成後您會得到：✅ 可維運的本地測試流程

準備工作¶

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

進入專案根目錄您會看到：終端機路徑位於 time_compass
同步依賴（若尚未安裝）
```
uv sync
```
您會看到：終端機顯示同步完成
確認 .env 檔案存在您會看到：專案根目錄可看到 .env

Step 1：啟動 time-compass-gradio¶

Step 1.1：執行啟動指令¶

執行：
```
uv run time-compass-gradio
```
您會看到：終端機進入服務執行狀態（持續佔用，不會立即結束）
開啟： http://127.0.0.1:8000/gradio 您會看到：瀏覽器顯示 Gradio 介面

Step 1.2：確認路徑正確¶

檢查 URL 是否為 /gradio 您會看到：網址列為 http://127.0.0.1:8000/gradio
確認頁面標題/內容包含 Time Compass 相關文字您會看到：可看到「Time Compass AI 助手」與多個功能區塊

[!IMPORTANT] 根路徑 / 是 FastAPI app，Gradio UI 掛在 /gradio。若只開 http://127.0.0.1:8000 可能看不到主介面內容。

Step 2：驗證獨立測試範圍¶

Step 2.1：可直接測試的區塊¶

測試 Debug / UI 載入是否正常您會看到：可進入頁面並與元件互動
測試 Scheduling Tab 基本流程（不寫入真實資料）您會看到：可操作表單與看到回應

Step 2.2：需要外部憑證的區塊¶

測試 OAuth / Google Tasks / Moodle 前，先確認 .env 相關設定您會看到：有設定時功能可往下執行；未設定時會出現對應錯誤訊息

[!NOTE] 本文件定位為「獨立 UI 測試」。未配置 OAuth 時，仍可先完成介面載入與基本互動驗證。

Step 3：呼叫與啟動方式補充¶

Step 3.1：先定義呼叫¶

先定義呼叫
呼叫名稱：uv run time-compass-gradio
呼叫目的：啟動 Gradio Web UI（FastAPI + mounted Gradio）
成功判準：http://127.0.0.1:8000/gradio 可開啟且元件可互動

Step 3.2：替代啟動（除錯用）¶

執行：
```
uv run python -m time_compass.interface.server
```
您會看到：行為等同 time-compass-gradio

Step 4：關閉與故障排除¶

Step 4.1：正常關閉¶

回到執行中的終端機
按下 Ctrl+C 您會看到：服務停止，8000 埠釋放

Step 4.2：常見問題¶

若 8000 埠被占用，先關閉占用程序再重跑您會看到：服務可正常啟動
若 OAuth 失敗，檢查 .env 的 GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET 您會看到：修正後可進行 OAuth 流程
若頁面空白或 404，確認路徑是 /gradio 您會看到：改成 /gradio 後正常載入

完成後檢查清單¶

[ ] 可成功執行 uv run time-compass-gradio
[ ] 可開啟 http://127.0.0.1:8000/gradio
[ ] UI 可看到 Time Compass 主要功能區塊
[ ] OAuth / Tasks / Scheduling 等功能區塊可正常互動
[ ] 可用 Ctrl+C 正常關閉服務

恭喜！ 🎉 您已完成 30+ 分鐘完整設置體驗。現在可以：

✨ 在 Gradio Web UI 中使用完整的時間規劃功能
📅 將規劃結果同步到 Google Calendar 與 Tasks
🔄 整合 Moodle 課程資訊進行智能規劃
💬 使用 AI 助手優化您的時間安排

官方文檔參考¶

Gradio 官方文件 https://www.gradio.app/docs
Uvicorn 官方文件 https://www.uvicorn.org/