Time Compass 教程與快速開始¶
專案 README - 專案總覽、核心特色、環境建置與使用方式
歡迎來到 Time Compass！本文檔幫助您選擇合適的開始路線。
快速判斷：選擇您的體驗階段¶
Time Compass 提供兩個體驗階段，其中階段 B 是在既有安裝上切換到真實模式（不需額外安裝外掛）：
🎯 階段 A：Mock 模式（5 分鐘快速開始）¶
特點： - ✅ 完全無需認證（無 Google OAuth、無 Gemini API Key） - ✅ 內建 2025-11 的 Mock 數據，開箱即用 - ✅ 逐個體驗完整功能：MCP Inspector、IDE Extension、Planner Studio - ⏱️ 預計時間：5 分鐘
適合： - 想快速了解功能的新用戶 - 無須連接真實數據的評審或演示 - 開發和測試 MCP Server
起點：Mock 模式快速開始
☁️ 階段 B：真實模式切換（接入真實數據、30+ 分鐘完整設置）¶
給評審老師: 這部分只要關閉dev mode（
MCP_DEV_MODE=0）即可切換到真實模式，無需重裝或額外安裝外掛。我們團隊會準備好一套測試用的.env!
特點： - ✅ 在既有 Mock 環境上切換，不需重做整套安裝 - ✅ 不需額外安裝外掛，核心是補齊 .env 並完成授權 - ✅ 關閉 dev mode（MCP_DEV_MODE=0）後接入真實服務 - ✅ 連接真實 Google Calendar / Tasks 數據 - ✅ 使用 Gemini AI 進行智能規劃 - ✅ 完整的時間管理和排程功能 - ⏱️ 預計時間：30-40 分鐘（分階段進行）
適合： - 需要實際生產環境使用 - 希望與 Google 服務深度集成 - 需要實際 AI 驅動的規劃功能
起點：Google Cloud 專案設定（15-20 分鐘）
快速導航¶
階段 A：我只有 5 分鐘¶
👉 推薦：Mock 模式快速開始
- 依照 quickstart-mock.md 完成設置
- 立即體驗 Planner Studio 或 MCP 工具
階段 B：我有 30+ 分鐘，想要完整功能¶
👉 推薦路線： 這是「Mock data -> Real data 的模式切換」，不是重裝一套新系統。
Step 1：Google 基礎設置（15-20 分鐘） 1. Google Cloud 專案設定 2. Google OAuth 驗證流程
Step 2：可選 — 啟用 gradio 的 AI 功能（5-10 分鐘）
Step 3：選擇您的介面 - Web UI：Gradio Web UI(強力推薦先打開litellm) - IDE 集成：MCP 環境建置 - 視覺化規劃：Planner Studio（草案內容仍為模擬資料、但 google 日曆內容升級至實際模式）
關鍵概念說明¶
| 功能 | Mock 模式 | 完整體驗 |
|---|---|---|
| MCP Inspector / IDE | ✅ Mock 數據 | ✅ 完全可用 |
| Planner Studio | ✅ Mock 數據 | ✅ 真實數據 |
| Gradio Web UI | ❌ 主要 AI 功能不可用 | ✅ 可用（需 Gemini） |
| 設置時間 | ~5 分鐘 | ~30+ 分鐘 |
常見問題¶
Q：Mock 模式有什麼限制？¶
A： - 所有數據都是預設的 Mock 數據（非真實 Google 數據） - Gradio 無法使用（無 Gemini API Key） - 所有功能在邏輯上完整可測試
Q：如何在 Mock 和 Real Data 之間切換？¶
A：修改 .env 中的 MCP_DEV_MODE：
MCP_DEV_MODE=1 # Mock 模式
MCP_DEV_MODE=0 # Real Data 模式
請注意：切到 MCP_DEV_MODE=0 後，仍需完成階段 B 的 Google OAuth / API 設定。
下一步¶
根據您的選擇，前往相應的開始指南：
- 5 分鐘快速上手：MCP 環境建置 (Mock 模式)
- 30+ 分鐘完整體驗：Google Cloud 專案設定
文檔說明¶
本教程遵循統一的編寫標準。如需新增或更新文檔，請參考：
👉 教學文件模板
模板定義了： - 標準的文檔結構 - 一致的寫作風格 - 可驗證的步驟說明 - 適當的安全提醒