5 分鐘快速開始 — Mock 模式¶

無需 Google 帳號、無 API 費用、無任何認證。

本文檔帶您完成基礎環境設定，並體驗 Time Compass 的三項核心功能。

簡介：完整設定流程¶

本指南分為 2 個主要部分，預計 5 分鐘完成：

最終目的：建立可運作的 Time Compass 環境，體驗 Planner Studio、MCP Inspector、IDE 工具。

TOC - 準備工作 - Part 1：基礎環境設定 - Part 2：Mock 體驗（三項功能） - 完成後檢查清單 - 常見問題

）

如果你已經安裝過 uv 和專案¶

如果您已完成環境設定，可直接進行「Mock 體驗」部分：如果您是新用戶，請從下方「準備工作」開始，依序完成。

快速步驟： 1. 安裝 uv, node 並同步依賴（uv sync） 2. 確認 .env 中 MCP_DEV_MODE=1 3. 啟動 Planner Studio 、 MCP Inspector 4. 在 IDE 中測試工具（可選）: MCP 環境建置指南

2 大部分概覽¶

基礎環境設定（2 分鐘）
目的與效果：安裝 uv 套件管理工具、克隆專案、同步依賴。
完成後您會得到：✅ 可運作的 Time Compass 本地環境
Mock 體驗（3 分鐘）
目的與效果：啟動 Planner Studio 視覺化介面、測試 MCP 工具、在 IDE 中呼叫 MCP。
完成後您會得到：✅ 完整體驗三項核心功能

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

準備工作¶

在開始前，請確認：

您已連接網路您會看到：正常的網路操作
您已打開終端機（PowerShell / Bash / 其他）您會看到：終端機視窗開啟

Part 1：基礎環境設定¶

Step 1.1：安裝 uv 套件管理工具¶

uv 是本專案的依賴管理工具。若已安裝，可直接跳到 Step 1.2。

Windows (PowerShell)¶

開啟 PowerShell 終端機

執行安裝指令：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

您會看到：終端機顯示安裝進度

重啟 PowerShell 終端機（完全關閉再開啟）
驗證 uv 已安裝，執行：
```
uv --version
```
您會看到：類似 uv 0.4.0 的版本號(可能更高)

macOS / Linux¶

開啟終端機
執行安裝指令：
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
您會看到：終端機顯示安裝進度
驗證 uv 已安裝，執行：
```
uv --version
```
您會看到：類似 uv 0.4.0 的版本號(可能更高)

Step 1.2：克隆與初始化專案¶

複製專案（若已有專案檔案可跳過），執行：
```
git clone <repo-url>
cd time_compass
```
您會看到：專案檔案下載完成，當前目錄切換至專案根目錄
同步依賴（⏳ 需要 2-5 分鐘），執行：
```
uv sync
```
您會看到：終端機顯示下載與安裝進度

Step 1.2.5（可選）：安裝 Node.js¶

Node.js 用於執行 MCP Inspector（體驗 2）。若跳過此步驟，可略過體驗 2。

Windows (PowerShell)¶

安裝 Volta（Node.js 版本管理工具），執行：
```
winget install Volta.Volta
```
您會看到：終端機顯示安裝進度，完成後出現成功訊息
重啟 PowerShell 終端機（完全關閉再開啟）您會看到：新的 PowerShell 視窗開啟
安裝 Node.js LTS 版本，執行：
```
volta install node
```
您會看到：終端機顯示下載並安裝 Node.js

macOS / Linux¶

安裝 Volta，執行：
```
curl https://get.volta.sh | bash
```
您會看到：安裝完成
安裝 Node.js LTS 版本，執行：
```
volta install node
```
您會看到：終端機顯示下載並安裝 Node.js
驗證結果，執行
```
node --version
npx --version
```
您會看到：兩者皆輸出版本號（如 v22.x.x）

Step 1.3：設定環境變數¶

若您是評審老師：我們已在專案中準備好一套測試用的 .env，您只需確認 MCP_DEV_MODE=1 即可。

複製環境設定範本，執行：
```
cp .env.example .env
```
您會看到：專案根目錄出現 .env 檔案
驗證 .env 中已包含(打開編輯器並檢視這個檔案)：
```
MCP_DEV_MODE=1
```

[!SUCCESS] ✅ 環境準備完成！ 您現已具備可運作的 Time Compass 基礎環境。

Part 2：Mock 體驗（三項功能）¶

體驗 1：Planner Studio 視覺化排程介面¶

啟動本地排程規劃 Web 介面。

執行 Planner Studio：
```
uv run python scripts/run_planner_studio.py
```
您會看到：終端機顯示 Planner Studio 關鍵字、與可開啟的 URL
Ctrl+點擊 終端機輸出的 URL 開啟瀏覽器您會看到：終端機顯示類似以下內容：
```
✨ Planner Studio is LIVE with real data!
🔗 URL: http://127.0.0.1:8766/planner/dev-data-xxxxxxxxxx
```
Ctrl+點擊該網址，瀏覽器將自動開啟 Planner Studio 介面(或著手動複製到瀏覽器)
驗證 Mock 模式，確認：
✅ URL 路徑包含 dev-data-（表示 Mock 模式）
✅ 右側提示區域顯示「Mock 測試模式」
✅ 上方切換按鈕可切換多個排程方案（至少 5 種）
關閉服務，回到終端機、按 Ctrl+C 您會看到：服務停止，終端機恢復

✅ Planner Studio 體驗完成！

體驗 2：MCP Inspector 工具檢視¶

手動輸入參數、測試 MCP 工具是否能正常呼叫。

[!NOTE] 此體驗需要 Node.js。若未安裝，可跳過此部分。若您想直接體驗與 AI 整合的內容，可跳過此一步驟

執行 Inspector（在新終端機，專案根目錄）：
```
npx @modelcontextprotocol/inspector uv run time-compass-mcp
```
您會看到：終端機顯示 Inspector 服務位址（如 http://localhost:3000）
複製並開啟 終端機輸出的 URL 您會看到：瀏覽器打開 MCP Inspector 介面
測試工具，選擇任意工具（如 list_calendars）並執行您會看到：工具列表、輸入参數欄位、執行結果
關閉終端機，按 Ctrl+C 您會看到：Inspector 服務停止

✅ MCP Inspector 體驗完成！

體驗 3：IDE 中呼叫 MCP 工具（可選）¶

在 IDE（如 VS Code、Claude Desktop）中原生呼叫 MCP 工具。

此體驗需先完成 IDE MCP 配置。詳見 MCP 環境建置指南，內含安裝與體驗方法。

✅ IDE 工具體驗完成！

完成後檢查清單¶

恭喜！您已完成所有 Mock mode 體驗。請勾選以確認：

[ ] uv --version 可執行
[ ] uv sync 未報錯，已完成依賴安裝
[ ] .env 檔案存在且包含 MCP_DEV_MODE=1
[ ] Planner Studio 可開啟，URL 包含 dev-data-
[ ] MCP Inspector 可測試工具（若安裝 Node.js）
[ ] IDE 中 MCP 工具可呼叫（若完成 IDE 配置）

常見問題¶

Q：找不到 uv 指令？
A：重啟終端機讓環境變數重新載入。若仍無法找到，檢查安裝日誌。

Q：uv sync 卡住或報錯？
A：可多等待數分鐘，或按 Ctrl+C 重試。若仍失敗，檢查網路連線並清除快取：rm -rf .venv

Q：埠 8766 被占用？
A：改用其他埠啟動：

uv run python scripts/run_planner_studio.py --port 8777

Q：為什麼 URL 顯示 dev-data-？
A：這是 Mock 模式的標記，表示使用測試數據，完全符合預期。

下一步¶

恭喜！您已體驗完 Mock 模式的所有功能！ 🎉

從這裡，您可以：

升級至完整體驗（連接真實數據） - 前往 README，進行第二部分的設定 - 依序完成 Google Cloud / OAuth / Gemini 設置 - 預計 30+ 分鐘

5 分鐘快速開始 — Mock 模式¶

簡介：完整設定流程¶

如果你已經安裝過 uv 和專案¶

2 大部分概覽¶

準備工作¶

Part 1：基礎環境設定¶

Step 1.1：安裝 uv 套件管理工具¶

Windows (PowerShell)¶

macOS / Linux¶

Step 1.2：克隆與初始化專案¶

Step 1.2.5（可選）：安裝 Node.js¶

Windows (PowerShell)¶

macOS / Linux¶

Step 1.3：設定環境變數¶

Part 2：Mock 體驗（三項功能）¶

體驗 1：Planner Studio 視覺化排程介面¶

體驗 2：MCP Inspector 工具檢視¶

體驗 3：IDE 中呼叫 MCP 工具（可選）¶

完成後檢查清單¶

常見問題¶

下一步¶

相關文檔¶