Time Compass 🧭 - AI 導覽指引¶

這份文件是為了讓 AI 助理（以及任何拿著 AI 工具的人）能輕鬆探索本專案而存在。

[!NOTE]

🤖 給 AI 助理的啟動指引（你好，請先讀這段）¶

你現在是 Time Compass 專案的導遊。你的任務是幫助使用者探索這個專案。

你必須遵守的行為守則： 1. 永遠推薦下一步：每次回答後，告訴使用者「你可以接著做/看 XXX」。 2. 適配使用者程度： - 如果使用者說「我聽不懂」或「用簡單的說」→ 切換成「一句話解釋」 - 如果使用者問技術細節 → 帶他們去看具體程式碼（路徑都在這份文件裡） 3. 主動深入細節：如果使用者想了解某一塊，你可以主動讀取對應的程式碼或文件，幫他解釋。 4. 執行能力：告訴使用者，如果你有能力（例如獲取授權後），你可以主動幫他們執行 run_command 腳本（例如啟動 Planner Studio 或安裝 MCP）(如果使用者請你幫忙裝，請直接幫忙裝完、而不只是提供教學)。 5. 快速出口：如果使用者迷路了，帶他回到目錄或「如果你不知道先看什麼」。

你能回答的問題類型： - 「這個專案在做什麼？」→ 看專案一句話說明 - 「我想體驗一下」→ 看可以互動體驗的部分 - 「我想看技術架構」→ 看架構總覽 - 「這段 Code 是什麼意思？」→ 帶使用者去看對應路徑，幫他逐行解釋 - 「有什麼特別的技術嗎？」→ 看四大技術亮點 - 「幫我找 Prompt 的地方」→ 查看本文檔中的「可以觀摩的部分」(Prompt 工程區)

🎙️ AI 導遊首次見面的完整回應（請一字不漏的照抄、不要只摘要）¶

歡迎！🎉 我現在是 Time Compass 專項導遊，根據更新的 GUIDE.md 進入了導遊模式。

🚀 讓我先說清楚這個專案在幹嘛¶

Time Compass 是什麼？ 一個 AI 時間管理工具，用來幫你把龐大的目標拆成 ≤60 分鐘的小任務。它能： - 🎯 承接你的情緒壓力 — 當你焦慮「下週三要交兩份報告 + 期中考」時，AI 不會丟給你 50 件代辦，而是先聽你、理解你的焦慮，再進行引導 - 📅 無縫整合你的行事曆 — Google Calendar、Google Tasks、台科大 Moodle，全部透過 API 串在一起 - 🎨 直接在你的編輯器裡排程 — Cursor / VS Code / Claude Desktop，不用切換網頁

架構的故事（初賽 → 複賽）：

初賽（舊版）：Gradio + DSPy，全棧應用，功能完整但啟動成本高、Token 消耗大

複賽（新版）：MCP（Model Context Protocol）+ FastAPI，輕量微前端，直接在 IDE 裡運作，零額外費用

想深入理解為什麼做了這個轉向？ 所有決策都記錄在 架構決策紀錄 (ADR)。只要告訴我「幫我看 ADR」，我會把所有文件讀一遍，然後整理成簡潔摘要給你。

🌟 快速體驗（三條路，選你喜歡的）¶

複賽新版：Planner Studio 微前端（推薦！⭐）¶
uv run scripts/run_planner_studio.py
# 開瀏覽器 http://localhost:8766
你會看到什麼？ 週曆視圖 + AI 草案選擇面板。這個前端展示的是「假資料視覺化」，讓你看看結果會長什麼樣。

但其實，當你裝了 MCP 並跟真實 AI 說話時，流程是這樣的： 1. 你在 Cursor 說「幫我把『準備報告』排進這週，每次不超過 1 小時」 2. AI 首先調用 Prompt 工具分析你的需求、了解你的時間狀況和優先權 3. 根據分析，AI 調用 get_time_context 工具抓取你的行事曆與任務 4. AI 調用 launch_planner_studio 工具 → 在瀏覽器打開視覺化草案 5. 你看著 A/B/C 方案選擇你喜歡的 → AI 一鍵寫入 Google Calendar

零框架 Vanilla JS，超輕量！

初賽舊版：Gradio 完整對話體驗¶
uv run python -m time_compass.interface.server
# 開瀏覽器 http://127.0.0.1:8000/gradio
想體驗「情緒承接 + 意圖路由」的完整流程？FastAPI OAuth、DSPy 漏斗、完整對話體驗都在這裡。

技術先行：MCP Inspector（免帳號！⭐）¶
npx @modelcontextprotocol/inspector uv run time-compass-mcp
完全免設定，直接試試 15 個 MCP 工具。

🏆 MCP 安裝：真正的獨特體驗開始 ⭐⭐⭐¶

這才是看到「真實 AI 幫你排時間」的方式！

安裝 MCP 到你的 AI 編輯器（Cursor / VS Code / Claude Desktop），然後你的 AI 會自動獲得排程超能力。我可以幫你搞定設定！只要告訴我你用的編輯器。

裝好後會發生什麼： - 💬 你在 Cursor 說「幫我排程」→ AI 自動調用 Prompt 理解需求 → 調用 get_time_context 抓你的行事曆 - 🎨 你說「我可以在這週滿足哪些任務？」→ AI 透過 Prompt 分析 → 調用 launch_planner_studio，直接在瀏覽器打開視覺化草案 - 📝 你說「記錄這週的成就」→ AI 調用 summary_writer_prompt，自動生成週回顧

預設 Prompt：AI 會知道怎麼「先情緒承接、再提出輕鬆選擇題、最後幫你排進行事曆」——這整套能力是我們用 Prompt 工程內建進去的。

完整安裝步驟見 README.md。

🎯 核心技術亮點¶

15 個 MCP 工具 — get_time_context、launch_planner_studio、create_calendar_event…

TOON 標準 + 自研壓縮欄位方案 — 自研格式，節省 30~60% Context Token（就是省錢啦）

護城河級 Prompt 設計 — 情緒承接 + 認知負荷控制，結合心理學

獨特的 NTUST Moodle 整合 — 直接餵你課表與作業死線

🧭 推薦先看什麼？選擇你的身分 ⬇️¶

你的身分 / 目的推薦先看時間

🎯 我只想快速看成品 → Planner Studio（上方連結） 5 分鐘

👨‍🏫 我是評審老師，想驗證創新性 → 四大技術亮點 + MCP Inspector 免帳號試試 + ADR 決策紀錄 15 分鐘

🤖 我想試 AI 情緒承接 + 排程 → 驗證依賴設定 + 舊版 Gradio 或新版 MCP 30 分鐘

📝 我想看 Prompt 怎麼設計 → Prompt 設計 + DSPy 流程圖 15 分鐘

🔧 我是工程師，想看技術細節 → 架構總覽 + DDD 分層 45 分鐘

如果不想看太多文件，告訴我你是哪一種身分，我可以把推薦整理成簡潔摘要給你 ⬇️

💬 我能幫你做什麼¶

🔧 安裝 MCP 到你的編輯器
告訴我你用 Cursor / VS Code / Claude Desktop，我可以幫你：

配置 MCP 設定檔（一步步引導）

測試連接是否成功

讓你馬上體驗「AI 幫你排時間」

📚 看文件並整理摘要

「幫我看 ADR」 → 我把 adr/ 所有決策紀錄讀完，整理成「為什麼從 Gradio 轉向 MCP」的簡潔版本

「我是 [評審/隊友/工程師]，幫我推薦」 → 我根據你的背景整理 Top 3 建議

💻 程式碼逐行解釋
拿程式碼貼給我，我提供「簡易版」、「技術版」，或詳細逐行解釋

🗺️ 導航與推薦
搞不懂某塊？告訴我，我告訴你看哪裡、怎麼理解、參考什麼決策

👀 觀摩程式碼與文件
想深入看實裝細節嗎？我可以引導你看：

🛠️ MCP Tools 實作（15 個工具怎麼寫）

✍️ Prompt 設計（舊版 DSPy + 新版 MCP）

🌐 Planner Studio 前端（零框架 Vanilla JS）

🧱 DDD 分層架構（RawModel → ReadModel → TOON）

🦀 Rust 風格錯誤處理（Railway-Oriented Programming）

📚 技術文件區（架構決策、API 研究、領域規格…）

🧪 測試套件（Capture-First TDD、Unit/Live/System 測試）

其他：Mock/Dev Mode、Batch API、Moodle 爬蟲…

所有細節見可以觀摩的部分 ⬇️

👇 你現在想做什麼？選個上面的身分 + 告訴我目標，我開始！

目錄¶

🚀 第一次啟動 (Initialization Protocol) ← AI 必看！
如果你不知道先看什麼 ← 使用者從這裡開始！
專案一句話說明
架構總覽
四大技術亮點
驗證依賴（要先設定什麼才能跑起來）
可以互動體驗的部分
可以觀摩的部分

專案一句話說明¶

給評審老師：Time Compass 是一個實作了四大技術亮點（MCP 協定、TOON 標準+自研壓縮欄位、DDD 分層架構、獨特 Moodle 整合）的 AI 時間管理工具，讓 AI 在你的 IDE 裡幫你把大目標拆成 60 分鐘小任務。

給隊友（簡易版）：就像 Google 行事曆可以提醒你開會，但我們的工具更聰明——它能看你的課表、幫你想「我應該什麼時候寫作業、花多久」，而且是在你寫 code 的軟體裡直接講話給你聽，不用再切換到另外一個網頁。

給 AI（技術版）：本專案是一個符合 Model Context Protocol（MCP）規範的 Server，整合 Google Calendar API、Google Tasks API 與 NTUST Moodle（API + Scraper 雙路徑），透過 TOON 標準與自研壓縮欄位方案壓縮 context，以及嚴格 DDD 分層的 Python 後端，讓使用者的 AI 助理能進行智慧時間規劃。

架覽總覽¶

核心架構圖 (Mermaid)¶

graph TD
    User["使用者 / AI 編輯器\n(Cursor / Claude Desktop)"]

    subgraph MCPServer ["MCP Server (FastMCP)"]
        Tools["15 MCP Tools\n(Thin Wrappers)"]
        Prompts["System Prompts\n(情緒 + 路由 + 排程)"]
    end

    subgraph Runtime ["Time Compass Runtime"]
        DP["DataProvider\n(Data Fetching)"]
        Planner["AIPlanner\n(Schedule Generator)"]
    end

    subgraph External ["外部整合 (Integrations)"]
        GCal["Google Calendar API\n(Batch Request)"]
        GTask["Google Tasks API\n(Batch Request)"]
        Moodle["NTUST Moodle\n(API + Scraper)"]
    end

    subgraph Legacy ["舊版系統 (Legacy)"]
        Gradio["Gradio Web UI\n(Old Interface)"]
        DSPy["DSPy Router/Pipeline\n(Intent Routing)"]
    end

    subgraph Visualization ["視覺化 (UI)"]
        PS["Planner Studio\n(Vanilla JS Micro-frontend)"]
    end

    User -->|MCP Protocol| MCPServer
    MCPServer --> Runtime
    Runtime --> External
    Runtime --> PS

    %% 舊版連結
    User -.-> Gradio
    Gradio -.-> DSPy
    DSPy -.-> Runtime

核心架構圖 (純字元版)¶

使用者的 AI 編輯器 (Cursor / Claude Desktop)
    │
    │ MCP Protocol (stdio/SSE)
    ▼
┌─────────────────────────────────────────────┐
│             MCP Server (FastMCP)             │
│                                             │
│  ┌──────────────┐  ┌────────────────────┐   │
│  │  15 MCP Tools │  │  System Prompts    │   │
│  │  (thin wrappers)│  │  (情緒+路由+排程) │   │
│  └──────────────┘  └────────────────────┘   │
│          │                                  │
│  ┌───────────────────────────────────────┐  │
│  │         Time Compass Runtime          │  │
│  │  (DataProvider + AIPlanner)           │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘
    │
    ├──→ Google Calendar API  (Batch Request)
    ├──→ Google Tasks API     (Batch Request)
    └──→ NTUST Moodle         (API + Scraper 雙路徑)

    另外：
    └──→ Planner Studio (本地 FastAPI + Vanilla JS 微前端)
    └──→ 舊版 DSPy 系統 (位於 domain/ 下的意圖路由管線)

資料與調用流向 (DDD 分層)：

Facade 層 (入口)：src/time_compass/integrations/get_all_information_from_api.py (調用下方所有 Integration)
Integration 層 (業務邏輯)：moodle/, google_calendar/, tasks/ 的 async_core.py
Common 層 (基礎建設)：common/google_api_dispatcher.py 與 common/http_batch_tool.py (負責 Batch HTTP)
Client 層 (底層發送)：各項目的 api_client_async.py 或 scraper.py
Model 流轉：RawModel (API 原始數據) → ReadModel (業務轉換) → TOON (Token 壓縮輸出)

四大技術亮點¶

🎨 1. MCP 專屬微前端 (Planner Studio)¶

內建輕量級「日曆視圖 + AI 多草案選擇面板」。在 AI 編輯器中輸入一句話，即可呼叫 launch_planner_studio 工具，看到視覺化排程結果。

程式碼位置：src/time_compass/mcp/ui/
後端 API：MCP 工具編排邏輯（Browse Mode & Plan Mode）
啟動指令：uv run scripts/run_planner_studio.py --real

🧠 2. 護城河級 Prompt 骨架¶

實踐認知負荷控制（CLT）與葉杜二式法則。透過「選擇題」引導，把大目標拆解成 ≤60 分鐘的微任務，並在使用者有壓力時先進行「情緒承接」。

情緒承接 Prompt：src/time_compass/domain/emotion/
意圖路由 Prompt（L1/L2/L3 漏斗）：src/time_compass/domain/router/
任務排程 Prompt：src/time_compass/domain/schedule/
總結 Prompt：src/time_compass/domain/summary/
MCP-native Prompt（新版）：src/time_compass/mcp/prompts/

🗜️ 3. TOON 標準 + 自研壓縮欄位方案¶

自行研發的 Token-Oriented Object Notation 與自研壓縮欄位，將大量日曆事件壓縮，節省 30~60% 的 Context Token 消耗。Verbose JSON 傳遞是當前 MCP 生態的痛點，TOON 標準加上我們的自研方案是完整的答案。

實際輸出範例：assets/ 目錄底下的 .toon 檔案

🎓 4. 獨特的 NTUST Moodle 整合¶

獨特針對台科大 Moodle 的 MCP 方案，支援 API（官方 Web Service）和網頁爬蟲（Playwright）雙路徑。直接將課時與作業死線餵給 AI。

Async API 路徑：src/time_compass/integrations/moodle/async_core.py
爬蟲路徑：src/time_compass/integrations/moodle/scraper.py
API 研究文件：docs/time_compass/integration/moodle/（含 raw.json + cleaned.json）
⚠️ 限制說明：Moodle 的官方 API 文件極差，許多 API 僅開放給手機 App 或是根本未開放，本專案透過逆向工程與爬蟲補齊了這塊拼圖。
⚠️ 僅限台科大 Moodle

🔑 驗證依賴¶

[!IMPORTANT] 把這些環境設定好，才能完整跑起來。評審老師會收到一組測試用的 Google 和 Gemini 憑證。

Google 帳號憑證¶

你需要 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET，用以下任一方式取得 Token：前置設定可先看：docs/how-to/google-cloud-project-prerequisites.md

方法 A（MCP 啟動時）：在 AI 編輯器中呼叫 launch_google_token_auth MCP 工具

方法 B（手動執行）：

# 確保已設好 .env 中的 GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
uv run tools/get_google_token.py

Token 會儲存到專案根目錄的 token.json。

⚠️ 非 Windows 使用者請注意：TIME_COMPASS_DISABLE_WMI_SYSTEM_QUERY 環境變數會自動偵測 Windows 系統的 WMI query 卡頓，非 Windows 環境完全不受影響，無需關心。

Moodle 憑證（台科大帳密）¶

在 .env 中設定：

MOODLE_ACCOUNT=你的學號
MOODLE_PASSWORD=你的密碼

⚠️ 密碼若含特殊字元，請用雙引號包起來：MOODLE_PASSWORD="你的密碼" ⚠️ 僅適用台科大（NTUST）Moodle

LiteLLM Proxy（選填，Gradio 舊版介面才需要）¶

Gradio 介面需要 LLM API Key，透過 LiteLLM Proxy 轉接：

# 非 Windows（手動）
uv run scripts/serve_litellm_proxy.py

相關環境變數請參考 .env.example（如 GEMINI_API_KEY_1，可以無限擴充）。

🎮 可以互動體驗的部分¶

1. Planner Studio 主視覺體驗（新版 MCP 架構）¶

本專案 複賽新版 的直接成品展示：

# 使用真實 Google 資料 (需先完成 OAuth)
uv run scripts/run_planner_studio.py --real

# 使用假資料 (建議開發與快速預覽時使用，請一定也要開啟 DEV_MODE)
uv run scripts/run_planner_studio.py

開啟後在瀏覽器查看 http://localhost:8766。能看到： - 週曆視圖（顯示你的 Google Calendar 事件） - AI 草案選擇面板（A/B/C 方案對比） - Browse Mode（快速查行事曆）和 Plan Mode（AI 生成排程建議）

重點：這個頁面展示的是「假資料視覺化」，讓你看看結果會長什麼樣。但當你裝了 MCP 並跟真實 AI（Cursor/Claude Desktop）說話時，AI 會用這個流程： 1. 你說「幫我把『準備報告』排進這週，每次不超過 1 小時」 2. AI 首先調用 Prompt 工具分析你的需求、了解你的時間狀況和優先權 3. 根據分析，AI 調用 get_time_context 工具抓取你的行事曆與任務 4. AI 調用 launch_planner_studio 工具 → 在瀏覽器打開視覺化草案 5. 你看著 A/B/C 方案選擇你喜歡的 → AI 一鍵寫入 Google Calendar

AI 導遊推薦：想看 AI 是怎麼生成草案的嗎？可以在 ADR 0005 - 認知負荷驅動提示找到相關設計說明，或問我幫你逐行解釋。

2. Gradio 舊版互動體驗（初賽架構）¶

想體驗 初賽版本（Gradio + DSPy） 的完整對話流？這個版本展示了早期的「情緒承接 + 意圖路由」設計：

# 確保環境變數設定完成（.env 內含 Google + Gemini Key）
# 若沒有 LiteLLM proxy，也可以直接跑（但功能會受限）
uv run python -m time_compass.interface.server

開啟瀏覽器查看 http://127.0.0.1:8000/gradio。

舊版的特色： - FastAPI OAuth 集成，完整的 Google Calender + Tasks + Moodle 拉取 - Gradio 介面的自然語言對話體驗 - DSPy 意圖路由漏斗（L1/L2/L3）與情緒承接流程 - 完整的排程生成與回顧功能

舊 vs 新的對比：初賽版本是來自 Cursor/傳統方式的全棧應用，複賽版本則是專為 MCP 協定重新架構，在 IDE 裡更輕量、更零成本。詳見 README.md 與架構決策紀錄。如果你想深入了解為什麼做了這個轉向，告訴我「幫我看 ADR」，我會把所有決策文件讀一遍，然後整理成簡潔的摘要給你。

3. MCP Inspector 不需要帳號的快速體驗（新版）¶

完全免帳號，可以手動呼叫任何 MCP 工具：

npx @modelcontextprotocol/inspector uv run time-compass-mcp

這個方法不需要 Google OAuth！可以先體驗工具介面，再決定要不要完整設定。

4. MCP 安裝：獨特體驗的開始 ⭐¶

這才是看到「真實 AI 幫你排時間」的方式！ 安裝 MCP 到你的 AI 編輯器（Cursor / VS Code / Claude Desktop），然後你的 AI 會自動獲得排程超能力。

完整安裝步驟見 README.md。我可以幫你搞定這個配置！ 只要告訴我你用的編輯器，我會一步步引導。

裝好後，你的 AI 會自動獲得 15 個 MCP 工具的能力： - 💬 自然語言請求「幫我排程」→ AI 自動調用 get_time_context 抓你的行事曆 - 🎨 提出「我可以在這週滿足哪些任務？」→ AI 調用 launch_planner_studio，在瀏覽器打開草案 - 📝 說「記錄這週的成就」→ AI 調用 summary_writer_prompt，生成週回顧

預設 Prompt：AI 會知道怎麼「先情緒承接、再提出輕鬆選擇題、最後幫你排進行事曆」——這是我們用 Prompt 工程內建上去的能力。

[!WARNING] 安裝或修改 MCP 設定後，必須完全重啟 IDE，甚至開一個新的聊天視窗，變更才會生效。如果想再次啟動 AI 導覽模式，可以告訴你的 AI：「請閱讀 GUIDE.md 並以導遊模式協助我探索這個專案。」

5. 互動範例體驗¶

先確認環境：要體驗完整的 AI 任務拆分功能，你需要： - 路徑 A（新版 MCP）：安裝 MCP 到 Cursor/Claude Desktop 後，和你的 AI 說話 - 路徑 B（舊版 Gradio）：啟動 Gradio 舊版介面（需設定 LiteLLM Proxy + Google Auth）

範例對話 1（壓力情境）：

「我下週三要交兩份報告，還有期中考，我現在超級焦慮覺得完蛋了。」

AI 會先情緒承接，再提供輕鬆的選擇題讓你排程，不會一次倒給你 50 件代辦事項。

範例對話 2（查行事曆）：

「這週我有哪些空檔？」

AI 會用 get_time_context 工具，用 TOON 標準加自研壓縮欄位格式抓取你的行事曆，再整理成易讀的清單。

範例對話 3（請求排程）：

「幫我把『準備報告』排進這週的行事曆，每次不超過一小時。」

AI 會透過 launch_planner_studio 工具，讓你用視覺化方式選擇你喜歡的草案，再一鍵寫入 Google Calendar。

👀 可以觀摩的部分¶

🛠️ MCP Tools 實作¶

路徑：src/time_compass/mcp/tools/、src/time_compass/mcp/prompts/

15 支高精度 MCP Tools，每支 Tool 的 Docstring 本身就是 AI 的觸發條件。代表性工具：

工具	功能
`get_time_context`	取得 TOON 標準+自研壓縮欄位的時間環境大局（Calendar + Tasks + Moodle）
`launch_planner_studio`	啟動視覺化 Planner Studio 微前端
`launch_google_token_auth`	自動開瀏覽器完成 Google OAuth 授權
`create_calendar_event`	建立 Google Calendar 事件
`summary_writer_prompt`	生成週回顧/區間報告的 AI 反思

簡易版解釋：什麼是 MCP Tools？

如果把 AI 視為一位助理，MCP Tools 就是賦予這位助理「實際操作能力」的工具箱。 AI 本身只能處理文字資訊，但透過 MCP Tools，它可以連接外部系統來執行具體任務，例如：「查詢行事曆」、「設定提醒」或「產生視覺化圖表」。每一個工具都附帶一段功能說明，AI 在接收到你的指令後，會自動判斷並使用最適合的工具來完成工作。

🌐 Planner Studio 前端¶

路徑：src/time_compass/mcp/ui/

零框架的 Vanilla JS 微前端，包含： - planner_studio.html：主介面 - js/core/：核心資料流邏輯 - js/contracts/planner_payload.schema.js：前後端契約（Zod-like Schema） - styles/：CSS 樣式

🎒 簡易版解釋：什麼是「零框架前端」？

一般工程師寫網頁都會用「框架」，就像是用樂高直接拼。但我們不用任何現成的組合版，全部自己從原生 JS/HTML/CSS 程式碼開始寫。這樣的好處是：更輕量、載入更快、也更能控制細節。

✍️ Prompt 設計¶

舊版 DSPy 架構 Prompt（位於 `src/time_compass/domain/`）¶

這些模組構成了舊版的「智慧意圖路由 (L1/L2/L3)」管線。

意圖路由流程圖 (Legacy Pipeline)：

flowchart TD
    U["使用者輸入"] --> C1{"是否是第一個使用者輸入？"}
    C1 -->|"是"| C2{"是否要調用核心功能（Summary 或 Scheduling）？"}
    C1 -->|"否"| UNKNOWN["還沒想好怎麼處理"]
    C2 -->|"只需要情緒"| EM_ONLY["Emotion：單獨回應"]
    C2 -->|"需要核心功能"| E["情緒判斷"]
    C2 -->|"無關"| OUT_UNSUPPORTED["Router：提示目前不支援此請求"]
    OUT_UNSUPPORTED --> R

    EM_ONLY --> R["根據決定的流程，直接輸出結果"]

    E -->|"低落"| P0["Router：接住1到2句、但情緒交給Emotion"]
    P0 --> EM1["Emotion：前置"]
    EM1 --> I{"意圖判斷"}

    E -->|"普通或高漲"| P1["Router：接住1句"]
    P1 --> I

    I -->|"Summary"| T["Python：時間段粗判"]
    I -->|"Scheduling"| S["Pass"]

    T --> D["interval_data_tool：拉資料"]
    D --> SUM["Summary：生成總結"]
    SUM --> EM2{"是否收尾Emotion"}
    S --> EM2

    EM2 -->|"低落或需要暖收"| EM3["Emotion：後置收尾"]
    EM2 -->|"不需要"| R
    EM3 --> R

emotion/：情緒承接（HEAVY/MODERATE 模式），利用 CBT 技巧平復使用者心情。
router/：意圖路由漏斗，判斷使用者需求是模糊發想 (L1) 還是具體行動 (L3)。
schedule/：任務規劃核心，遵循 CLT 與時長 ≤ 60 分鐘原則。
summary/：週回顧與行動反思生成。
orchestrator.py：負責協同各 DSPy 模組與流式傳輸輸出。
src/time_compass/mcp/prompts/：直接透過 MCP 協定回傳的 Prompt 資源

🎒 簡易版解釋：什麼是 Prompt 設計？

Prompt（提示詞）是引導 AI 產生回覆的具體指令。由於 AI 的輸出品質高度依賴輸入的內容，「Prompt 設計」就是精確規劃這些指令的過程。透過 Prompt，我們可以規範 AI 的對話邏輯與處理步驟。例如，明確規定 AI：「在偵測到使用者表現焦慮時，必須先給予安撫，再進行後續提問」。我們在設計這些 Prompt 時，結合了心理學原則來優化 AI 的回應方式。例如，限制 AI 單次提供的選項數量，以避免造成使用者的資訊過載與認知負荷。

📚 技術文件區¶

路徑：docs/

文件/目錄	內容
`architecture/refactor-roadmap.md`	技術債追蹤與重構計畫
`docs/adr/`	Architecture Decision Records（為什麼做這個決策）
`docs/time_compass/domain/`	舊版領域規格（可能有些已過時）
`docs/time_compass/integration/moodle/`	台科大 Moodle API 研究文件（含 raw + cleaned JSON）

AI 提示：如果你不確定某份文件是否 up-to-date，可以告訴我，我幫你比對對應的程式碼！

🎒 亮點：Moodle API 研究

我真的去翻了台科大 Moodle 的 API，記錄了學校有開放哪些功能，甚至保留了原始的 API Response（`raw.json`）和整理過的版本（`cleaned.json`），方便之後轉換成 Pydantic 模型用。這件事不是每個開源專案都願意做——通常 Moodle 的文件很差，要自己一支一支試。路徑：`docs/time_compass/integration/moodle/`

🧱 DDD 多層 Model 架構¶

資料流遵循嚴格 DDD 分層：

外部 API
  └──→ RawModel      (google_calendar/models/models_raw.py 等)
       └──→ ReadModel (models_read.py)
            └──→ TOON  (models_toon.py)

Google Calendar Model：src/time_compass/integrations/google_calendar/models/
Google Tasks Model：src/time_compass/integrations/google_tasks/models/
Moodle Model：src/time_compass/integrations/moodle/models/
核心 Domain Model：src/time_compass/domain/models.py
Planner Model（前後端契約）：src/time_compass/mcp/planner_models.py

🎒 簡易版解釋：什麼是 DDD 分層？

想像你在搬家： 1. **搬家公司（Raw Model）**：把你的東西照原樣裝箱（不管有沒有用） 2. **你整理箱子（Read Model）**：你拆開箱子，把「有用的東西」分類整理好 3. **極簡收納（TOON 格式）**：把整理好的資訊再壓縮，只留下 AI 真正需要看的部分每一層有自己的職責，不互相混用，這樣改一層不會影響其他層。這就是 DDD（領域驅動設計）的精神。

🦀 Rust 風格錯誤處理¶

受 Rust 語言啟發的函數式錯誤處理（Railway-Oriented Programming）。核心理念：不用 try-catch，改用 Result<T, E> 返回值——讓錯誤成為正常資料流的一部分，而非例外。

相關檔案（由外向內追蹤資料流）：

get_all_information_from_api.py        ← 最頂層 Facade (統一並行調用)
  └── [moodle|google|tasks]/async_core.py  ← 各項目 Integration 層 (業務邏輯)
       └── common/google_api_dispatcher.py  ← 統一 Google API 路由
            └── common/http_batch_tool.py   ← 基礎實作：Batch HTTP 發送
                 └── google_calendar/api_client_async.py  ← 最底層 Client

🎒 簡易版解釋：Rust 風格錯誤處理是什麼？

一般寫程式，如果出錯了就「丟出例外（Exception）」，就像你搬東西，一碰到問題就直接摔在地板上，讓旁邊的人去撿。 Rust 風格是：出錯了也「保持優雅」——把結果包在一個盒子裡（`Result`），盒子上標記「是成功還是失敗」，讓每個人都能預期可能有失敗，安全地處理它。就像搬東西的人習慣用「我搬到了/我搬不到」兩種訊號，而不是直接崩潰。

🗂️ Mock / Dev Mode 系統¶

在開發時不想真的打 API？有完整的 Mock 系統：

src/time_compass/mcp/dev_mode.py：Dev Mode 控制器
src/time_compass/utils/planner_utils.py：Mock 資料生成
assets/：清洗過的真實 API 回應快照（.json, .toon 等）

# 開啟 Dev Mode（不會真正呼叫 Google API）
MCP_DEV_MODE=1 uv run time-compass-mcp

📦 Batch API 設計¶

透過 multipart/mixed 批次請求，大幅提升效率：

統一接收 List[RequestModel]
也拿到 RawModel（保留完整 API 回應）
理念：全程 async，batch > async gather

路徑：src/time_compass/integrations/common/

🧪 測試套件¶

路徑：tests/

奉行 Capture-First TDD（攔截優先測試）：先用真實 API 抓快照，再用快照寫單元測試。

測試路徑	需要憑證	說明
`tests/unit/`	❌ 不需要	用本地 JSON 快照模擬，跑最快
`tests/live/`	✅ 全部帳密	真實打外部 API，更新快照用
`tests/system/`	✅ Google + Gemini	完整系統集成測試

# 只跑不需要帳號的測試
uv run pytest tests/unit -v

注意：部分測試在 MCP_DEV_MODE=1 下可能無法通過，這是預期行為，已記錄在 refactor-roadmap.md。

🕸️ Moodle 爬蟲¶

雙路徑取得學校資訊： - API 路徑：src/time_compass/integrations/moodle/async_core.py（Moodle Web Service API） - 爬蟲路徑：src/time_compass/integrations/moodle/scraper.py（Playwright 非同步爬蟲）

兩者都是全 async 設計，支援批次處理。

🔧 套件管理：為什麼用 uv？¶

路徑：pyproject.toml

uv 是 Astral 出品的新世代 Python 套件管理工具，特點： - 速度：比 pip 快 10-100 倍 - 環境隔離：自動管理 .venv，不污染全域環境 - 標準：完全相容 pyproject.toml 規範

uv sync          # 同步依賴
uv run <script>  # 在虛擬環境中執行腳本（不需要手動 activate）

📎 快速連結¶

README.md：安裝與使用指南
refactor-roadmap.md：技術債與未來計畫
docs/adr/：架構決策紀錄
openspec/changes/：功能開發規劃文件

最後更新：2026-02-28 | Time Compass 🧭

你的身分 / 目的	推薦先看	時間
🎯 我只想快速看成品	→ Planner Studio（上方連結）	5 分鐘
👨‍🏫 我是評審老師，想驗證創新性	→ 四大技術亮點 + MCP Inspector 免帳號試試 + ADR 決策紀錄	15 分鐘
🤖 我想試 AI 情緒承接 + 排程	→ 驗證依賴設定 + 舊版 Gradio 或新版 MCP	30 分鐘
📝 我想看 Prompt 怎麼設計	→ Prompt 設計 + DSPy 流程圖	15 分鐘
🔧 我是工程師，想看技術細節	→ 架構總覽 + DDD 分層	45 分鐘