Time Compass 文檔首頁¶

我想快速體驗 Time Compass¶

請點擊👉 快速安裝指南

我想知道專案的價值與技術亮點¶

請點擊 👉 專案概覽

包括:

專案的不可取代性在哪裡
這個專案的價值跟技術亮點在哪裡?
會不會被 Gemini 新功能取代?
我們如何跟 AI 合作(Human in loop)?
我們使用了哪些工具、方法進行開發?
專案的開發理念是什麼? 等等

我想知道專案的技術細節¶

我們如何結合 TOON 格式壓縮傳遞給 AI 的上下文? 👉 toon-format.md
prompt如何設計? 👉 Prompt 設計
有哪些 prompt 範例? 👉 Prompt 範例集

Time Compass 教程與快速開始¶

想安裝 Time Compass?¶

快速開始 請看 👉 Time Compass MCP Edition 啟動指南請依序完成quickstart, mcp安裝, 以及實際安裝三個步驟(三次連結的跳轉)，完成後就可以開始使用 Time Compass MCP Edition 的功能了!
影片版本 請看 👉 影片版安裝指南

想體驗初賽版¶

請先安裝好 uv (可參考Time Compass MCP Edition 啟動指南)，接著在專案根目錄執行以下指令:

uv run time-compass-gradio --with-litellm

應該最後會出現一個類似

http://127.0.0.1:8000

之類的網址，請 ctrl + 左鍵打開。

Time Compass Q&A（給使用者與評審）¶

想看「會不會被取代」的完整回答：👉 不可取代性說明
想看團隊如何和 AI 協作：👉 我們如何使用 AI
想看和其他方案差異：看 Q-DIFF-*

Q-DIFF-001 為什麼不是直接用 ChatGPT + Actions + 個人化 GPT？¶

你可以快速接 OAuth，但實務上資料抓取穩定性不足：
- 日曆列表與逐曆事件抓取容易漏資料
- 難做 async / batch，速度慢
- prompt 過長，難以支援多功能，上下文窗口不夠 - 回傳有很多不需要的東西、token 成本高

Q-DIFF-002 為什麼不是直接用 Gemini 接 Google Workspace？¶

可控性與可觀測性不足：
- thinking 與工具調用不透明
- 不易確認實際抓到哪些資料、時間範圍多大、是否真的抓到 - 不易確定最大能抓到那些範圍 - prompt 過長，難以支援多功能，上下文窗口不夠 - 回傳有很多不需要的東西、token 成本高

Q-DIFF-003 為什麼不是用市面上的 MCP 就好？¶

目前常見 MCP 方案通常不覆蓋你的需求：
- 不支援 NTUST（台科大）Moodle 情境
- 缺少跨來源聚合讀取
- 缺少資料清洗與 TOON 壓縮

Q-DIFF-004 為什麼不是只做成 skills？¶

從 Google 端穩定拿資料不能只靠 skills。
skills 比較像提示層能力；Time Compass 同時處理了資料層、聚合層與輸出層。
另外，MCP 也能接入部分網頁 AI（例如 ChatGPT）作為實際通道。 Prompt 的部分也使用 description 來讓 AI 按需載入，理念與 skills 類似。

教程 (Tutorial)

快速開始 — Mock 模式¶

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

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

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 的版本號(可能更高)
請切換到專案根目錄，執行：
```
uv sync
```
您會看到：終端機顯示下載與安裝進度

macOS / Linux¶

開啟終端機
執行安裝指令：
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
您會看到：終端機顯示安裝進度
驗證 uv 已安裝，執行：
```
uv --version
```
您會看到：如 uv 0.4.0 樣式的版本號(可能更高)
請切換到專案根目錄，執行：
```
uv sync
```
您會看到：終端機顯示下載與安裝進度

Part 2：使用範例資料體驗（兩項功能）¶

體驗 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：IDE 中呼叫 MCP 工具（可選）¶

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

下一站: 點擊👉 MCP 環境建置指南，內含安裝與體驗方法。

MCP 環境建置與整合指南（Mock 模式）¶

本文檔涵蓋 Time Compass MCP Server 的完整安裝與配置流程，提供一套無成本、無 OAuth 的 MCP 快速設置方式，並使用內建 Mock 數據進行完整功能體驗。整體預計可在 5-10 分鐘內完成。

若需要真實數據（Google Calendar / Tasks），完成本步驟後可升級至 30+ 分鐘完整設置體驗（見 README）。

Important

開始前，請先完成快速啟動。

本指南分為兩個主要步驟，從 MCP 客戶端配置到完整驗證。每一步都有明確的目標與執行原因。

TOC - 準備工作 - Step 1: 配置 MCP 客戶端 - Step 2: 驗證連線狀態 - 故障排除

Note

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

Step 1: 配置 MCP 客戶端¶

本步驟會將 MCP Server 配置加入 IDE 或 AI 工具的設定檔。

準備工作¶

記錄專案的完整路徑（例如 C:/Users/YourUserName/Desktop/time_compass，或是你解壓縮、git clone 下來的路徑）
替換以下範例中的 [PROJECT_PATH] 為實際路徑，並且將其中的 \ 都換成 \\。例如
```
C:/Users/YourUserName/Desktop/time_compass
```
要換成
```
C://Users//YourUserName//Desktop//time_compass
```

選擇你的工具¶

此處列出幾個常見工具：Claude Desktop、Windsurf、Cursor、Antigravity、OpenClaw、OpenCode、Claude Cowork、VS Code（Copilot）、Codex、Gemini CLI。請根據你使用的工具選擇對應配置方法。

分成三個部分:

JSON 格式（大多數工具）
外層 key 不同的 JSON 格式（VS Code Copilot）
TOML 格式（Codex）

工具與設定檔對照（Windows）¶

請選擇對應的路徑，貼到終端機以後，按下enter，即可編輯檔案。

工具	設定檔路徑 (Windows)	格式 / 外層 key
Claude Desktop	`%APPDATA%\Claude\claude_desktop_config.json`	JSON / `mcpServers`
Windsurf	`%USERPROFILE%\.codeium\windsurf\mcp_config.json`	JSON / `mcpServers`
Cursor	`%USERPROFILE%\.cursor\mcp.json`（或專案 `.cursor/mcp.json`）	JSON / `mcpServers`
Antigravity	`%USERPROFILE%\.gemini\antigravity\mcp_config.json`	JSON / `mcpServers`
OpenClaw	`%USERPROFILE%\.openclaw\openclaw.json`	JSON / 依 OpenClaw 文件
OpenCode	`~/.config/opencode/opencode.json`（文件定義路徑）	JSON / `mcp`
Claude Cowork	尚未查到官方公開固定本機設定檔路徑	請依產品內設定頁
VS Code (Copilot)	`%APPDATA%\Code\User\mcp.json`（或工作區 `.vscode/mcp.json`）	JSON / `servers`
Codex	`~/.codex/config.toml`	TOML / `[mcp_servers.<name>]`
Gemini CLI	`%USERPROFILE%\.gemini\settings.json`	JSON / `mcpServers`

對照表參考來源： Claude Desktop、Windsurf、Cursor、Antigravity、OpenClaw、OpenCode、VS Code、Codex、Gemini CLI

JSON 格式（`mcpServers`，給`Copilot(VScode)`跟`Codex`以外的）¶

開啟設定檔：%APPDATA%\Claude\claude_desktop_config.json (Claude Desktop 為例)
檢查並合併 JSON 配置：
若設定檔中已有 "mcpServers" 物件，請在該物件內新增下方的 "time-compass" 項目
若設定檔中還沒有 "mcpServers" 物件，請將整個下方配置複製到檔案中（確保 JSON 格式正確）

您會看到：設定檔中的 mcpServers 物件內新增了 time-compass 項目

{
  "mcpServers": {
    "time-compass": {
      "command": "uv",
      "args": [
        "--directory",
        "[PROJECT_PATH]",
        "run",
        "time-compass-mcp"
      ]
    }
  }
}

範例：若設定檔已有其他 MCP（如 Anthropic 官方工具），合併後應該看起來像：
{
  "mcpServers": {
    "time-compass": { ... },
    "another_tools": { ... }
  }
}

儲存檔案

引用：mcpServers 格式可參考 Claude Desktop、Windsurf、Cursor、Gemini CLI

VS Code (Copilot)¶

工具	設定檔路徑 (Windows)	格式 / 外層 key
VS Code (Copilot)	`%APPDATA%\Code\User\mcp.json`（或工作區 `.vscode/mcp.json`）	JSON / `servers`

開啟設定檔：工作區的 .vscode/mcp.json 或使用者層級 mcp.json
檢查並合併 JSON 配置：
若設定檔中已有 "servers" 物件，請在該物件內新增下方的 "time-compass" 項目
若設定檔中還沒有 "servers" 物件，請將整個下方配置複製到檔案中（確保 JSON 格式正確）

您會看到：設定檔中的 servers 物件內新增了 time-compass 項目

{
  "servers": {
    "time-compass": {
      "command": "uv",
      "args": [
        "--directory",
        "[PROJECT_PATH]",
        "run",
        "time-compass-mcp"
      ]
    }
  }
}

提示：若已有其他 MCP server，合併後應該看起來像：
{
  "servers": {
    "time-compass": { ... },
    "other-server": { ... }
  }
}

儲存檔案(Ctrl + S) 您會看到：編輯器標題列不再顯示「*」或「改變」標記，表示設定檔已儲存成功

引用：VS Code MCP mcp.json 與 servers 格式見 VS Code 官方文件

Codex¶

開啟 ~/.codex/config.toml
檢查並合併 TOML 配置：
若設定檔中已有 [mcp_servers] 段落，請在該段落內新增下方的 [mcp_servers.time-compass] 項目
若設定檔中還沒有 [mcp_servers] 段落，請將下方配置複製到檔案中

您會看到：設定檔中新增了 [mcp_servers.time-compass] 段落及其配置

[mcp_servers.time-compass]
command = "uv"
args = [
  "--directory",
  "[PROJECT_PATH]",
  "run",
  "time-compass-mcp"
]
enabled = true

提示：若已有其他 MCP server，合併後應該看起來像：
[mcp_servers.time-compass]
...

[mcp_servers.other-server]
...

儲存檔案 您會看到：編輯器標題列不再顯示「*」或「改變」標記，表示設定檔已儲存成功

引用：Codex 的 ~/.codex/config.toml 與 [mcp_servers.*] 格式見 Codex config 文件

Step 2: 驗證連線狀態¶

本步驟會確認 MCP Server 與 IDE 連線正常。

VS Code (Copilot) 特殊步驟¶

因 VS Code 系統限制，您需要手動啟動 MCP 伺服器：

按下 Ctrl + Shift + P
輸入 mcp: List Servers
點選 "time-compass" 項目
點擊 啟動伺服器

基本驗證¶

重啟 IDE 或 Claude Desktop（完全關閉再開啟），VScode可用特殊步驟代替 您會看到：應用程式完全重新啟動，之前的對話窗口關閉
測試 MCP 工具連線，於對話框輸入：
```
List my calendars using time-compass tools
```
您會看到：
IDE 的工具面板應顯示 MCP 工具已載入（如 mcp_time-compass_list_calendars 等）
對話框會呼叫該工具並回傳日曆清單或測試資料
測試微前端介面，叫 AI 呼叫 launch_planner_studio 工具 您會看到：
應有瀏覽器視窗自動開啟（通常在 http://localhost:8766）
Planner Studio 排程管理介面載入完成

或是測試以下範例

幫我看看我這兩周都做了甚麼，我好累喔，還得複習微積分才行，也幫我排未來兩周的複習行程

最後一步: 接入真實資訊¶

注: 在測試前端時， AI 產生的資訊不一定都在當天，需要切換時間來檢查產出成果

請到登入google驗證文件

如果您不想要登入google，也可停留在這一步。

故障排除¶

遇到問題時，按下表快速查找解決方案：

問題	解決方案
MCP Server 無法啟動	檢查 IDE 設定檔中的 `[PROJECT_PATH]` 是否為正確的絕對路徑

Google OAuth 驗證流程（Time Compass）¶

本文檔涵蓋如何驗證 Time Compass 的 Google OAuth 授權流程是否可正常讀寫 Google 資料。

驗證流程概述：本步驟確認授權成功 → 產生 token.json → 測試讀寫能力。

Note

快速進入？ 若您為評審、或已使用 MCP_DEV_MODE=1，可先以 mock data 驗證流程；正式串接 Google 前仍建議完成本文實測。

簡介：完整驗證流程¶

本指南分為四個主要步驟，從啟動 OAuth 授權，到驗證讀取、聚合與寫入能力。

最終目的: 確認 token.json 可正確產生，且 Google Calendar / Tasks 的讀寫流程在 Time Compass 中可用。

準備工作：確認環境變數設定¶

打開 .env 檔案您會看到：檔案內容包含多行環境變數設定
設定 MCP_DEV_MODE=0
儲存 .env 檔案

Note

MCP_DEV_MODE=0 表示使用真實 Google Calendar / Tasks API；若為 1 則使用 Mock 資料。本文檔將引導您完成正式串接。

Step 1：啟動 OAuth 授權流程（擇一）¶

執行以下指令：
```
uv run tools/get_google_token.py
```
您會看到：終端機顯示授權 URL，並嘗試開啟瀏覽器

Step 2：完成瀏覽器授權¶

開啟 Google 授權頁（若未自動開啟，手動貼上工具輸出的 URL）您會看到：看到 Google 登入/授權頁面
登入並同意 OAuth 權限您會看到：授權流程完成，頁面顯示成功導回或完成提示

可能遇到的狀況：Google 未驗證應用程式警告¶

授權過程中可能會看到「這個應用程式未經 Google 驗證」的警告頁面。這是正常現象，因為 Time Compass 是開發中的應用程式。請依照以下步驟繼續：

點擊「進階」按鈕您會看到：頁面顯示更多選項

點擊「前往『time_compass』(不安全)」連結您會看到：授權流程完成，頁面顯示成功導回或完成提示

Step 3：確認 token.json 產生¶

確認專案根目錄出現 token.json 您會看到：token.json 存在，且檔案內容非空

下一步?¶

到這裡 MCP 的部分已經安裝完成，只要重啟MCP即可。

注: 在測試前端時， AI 產生的資訊不一定都在當天，需要切換時間來檢查產出成果

您可以回到教學首頁繼續體驗舊版的gradio。

概念說明 (Explanation)

Time Compass Q&A（給使用者與評審）¶

想看「會不會被取代」的完整回答：👉 不可取代性說明
想看團隊如何和 AI 協作：👉 我們如何使用 AI
想看和其他方案差異：看 Q-DIFF-*

Q-DIFF-001 為什麼不是直接用 ChatGPT + Actions + 個人化 GPT？¶

你可以快速接 OAuth，但實務上資料抓取穩定性不足：
- 日曆列表與逐曆事件抓取容易漏資料
- 難做 async / batch，速度慢
- prompt 過長，難以支援多功能，上下文窗口不夠 - 回傳有很多不需要的東西、token 成本高

Q-DIFF-002 為什麼不是直接用 Gemini 接 Google Workspace？¶

可控性與可觀測性不足：
- thinking 與工具調用不透明
- 不易確認實際抓到哪些資料、時間範圍多大、是否真的抓到 - 不易確定最大能抓到那些範圍 - prompt 過長，難以支援多功能，上下文窗口不夠 - 回傳有很多不需要的東西、token 成本高

Q-DIFF-003 為什麼不是用市面上的 MCP 就好？¶

目前常見 MCP 方案通常不覆蓋你的需求：
- 不支援 NTUST（台科大）Moodle 情境
- 缺少跨來源聚合讀取
- 缺少資料清洗與 TOON 壓縮

Q-DIFF-004 為什麼不是只做成 skills？¶

從 Google 端穩定拿資料不能只靠 skills。
skills 比較像提示層能力；Time Compass 同時處理了資料層、聚合層與輸出層。
另外，MCP 也能接入部分網頁 AI（例如 ChatGPT）作為實際通道。 Prompt 的部分也使用 description 來讓 AI 按需載入，理念與 skills 類似。

我們如何使用 AI¶

Time Compass 有兩個使用 AI 的核心理念：

AI 應該幫助人類從簡單但很煩的事情中解放出來
人類應該保留最終決策權

這個原則同時用在產品設計，也用在開發流程。

產品上：AI 幫忙整理與提案，人負責選擇¶

在時間管理這件事上，最耗力的常常不是做決定本身，而是先把資料找齊、整理好，再拆成可以開始做的下一步。

這些事情非常適合交給 AI：

整理來自 Google Calendar、Google Tasks、Moodle 的資訊
找出真正值得注意的待辦與事件
將大任務拆成較容易開始的小步驟
產生多個可比較的規劃方案

但我們不希望 AI 直接替使用者做最後決定。

所以 Time Compass 的設計不是「AI 幫你決定」，而是「AI 先提出幾個方案，再由你選擇」。我們相信 AI 可以降低開始規畫時的阻力與拖延情緒。但最終的安排仍應該由人來決定，因為當方案是使用者發自內心選擇的，那麼方案也會更容易落實。

開發上：先規劃，再動手¶

我們和 AI 一起開發時，也遵守同樣的分工邏輯。AI 很擅長探索脈絡、列出方案、補充文件與加速實作，但最後的方向選擇不能外包。

我們目前的開發迴圈可以濃縮成四步：

釐清問題
發現 bug 或想新增功能時，我們會先讓 AI 用 OpenSpec 或其他工具探索現狀，例如相關程式、資料在程式裡長怎麼樣、程式之間如何互相引用，以及需要查閱的最新文件。
選擇方案
在完成 explore 之後，我們會讓 AI 提出 proposal，必要時比較多個方案，再由人決定要採用哪一個方向，並把 proposal 修到滿意為止。
分階段解決
方向確定後，再把工作拆成不同階段，逐步實作、驗證、重構，而不是一次暴衝到底。
驗證結果
最後一定由人驗證成果，確認功能、行為、都符合預期，再進入 git 同步。

這套流程本質上就是三個理念：

先計畫再行動
邊改邊寫很容易陷入「能跑」，但其實不是最佳解的實作方法。因此應該要先調查清楚現狀，先 explore，再整理成 proposal。
先比較方案再選擇，人類最最終決策
不要直接問AI怎麼做。你應該要問 AI 有哪些可能的方法可以達成你的目的、在自己權衡利弊後挑選。事實上，這個部分是最能與AI一起成長的部分，詳細可見下個章節
人類要在最後實際驗證
應該要在最後檢查 AI 做了什麼改動、改動後的效果是否真的解決問題。

為什麼方案挑選不能交給 AI¶

因為開發對我們來說困難的地方，往往不是簡單的把程式碼補到能跑，而在於找出問題的源頭、哪一個修改方案才對長期有利。

在我們的經驗中:

如果人不做判斷，最後會失去整個系統的掌控權，反過來被 AI 控制。

這在工程上通常會表現成幾種問題：

AI 傾向做小修補，而不是重看整體架構
AI 可能知道如何通過測試，但不一定知道這是不是好設計
AI 不一定會主動停下來說真正的問題在哪
如果人不自己做決策，最後連 debug 都會變得困難，因為你已經不知道為什麼變成現在這樣

AI 很擅長提案、加速與補強，但他無法代替人類做決策。

最有價值的是人的成長¶

和 AI 一起開發時，常常會出現我們不熟悉的知識或概念，這時往往就是成長的機會。我們會請 AI 向我解釋概念。AI 能根據現有的程式碼與文檔做出符合我們程度的解釋，我們也能一直追問直到了解為止。我們在一次次的決定中，逐漸學會如何權衡時間、專案規模、成本、可維護性等等方面，最終選出最適合的做法。

跟 AI 還會在其他方面合作嗎?¶

會。除了提到的開發流程以外，AI也會使用到我們設計的全域的 prompt 、 skills 跟 mcp。我們也會使用AI把經驗寫回 skills。

我們的 prompt 會在每一次跟 AI 開始對話時加入。拿來記一些每次都希望他能記住的東西，比如說專案使用了什麼技術、對話時應該使用繁體中文等等。

mcp 這個工具能讓 AI 做到更多事情，而 skills 告訴 AI 如何實際行動。

當需要查詢文檔時，我們會請 AI 調用 context7 這個 mcp，讓 AI 獲得與問題相關的最新文檔。

當需要設計前端時，我們會請 AI 使用 ui-ux-pro-max 選擇前端的風格、配色等等。

當我們發現有一個重複的工作流程時，我們會將他轉換成可重複使用的 skills。例如讓 AI 學會分析 JSON (一種文本的格式)的結構，並轉換成程式方面好用的型態。

那麼，我們是如何開發的¶

前面提到開發的四個階段，以下我們會具體說明在每個階段我們是怎麼跟 AI 合作的。

釐清問題¶

這步驟包括:

使用 openspec 的 explore 指令。核心是AI先理解我們的 code，但不做更動。
請 copilot 開 subagent 掃描相關檔案。包括上下游、函數的互相調用、pydantic model、已有文檔等等
追蹤 data flow，看看資料是否在某個部分有不合理的轉換、或是哪裡的型別不清楚
使用相關 mcp ，例如前面提到的使用 context7 蒐集第三方相關文檔
使用相關 skills ，例如前面提到的 ui-ux-pro-max
如果問題較為複雜，會讓 AI 寫小程式，嘗試重現問題。

選擇方案¶

這步驟我有時候會請網頁版的 ChatGPT ，在網路上搜尋大家如何解決類似的問題。也會直接讓 AI 使用 openspec propose 產出提案，然後由我持續修改、刪減、補充，直到 proposal 足夠貼近真正想做的事為止。如果有多個方向，也會先要求 AI 列出可選方案，分析每個方案的優缺點，再由人做最後決定。

分階段解決¶

有兩個主要理念，分別是 TDD(Test-Driven Development) 跟 DDD(Domain-Driven Development)。

TDD 是先寫測試，再寫程式碼。這樣可以確保每個階段的改動都有明確的驗證標準。先寫好測試也可以避免 AI 寫出與問題無關的程式碼(另有真實資料抓取、以及資料階段性輸出等檔案裡兩個細節，詳見 [])。
DDD 是先定義好資料模型，再寫程式碼。這樣可以確保每個階段的改動都有明確的資料結構，避免 AI 寫出不合理的資料轉換。並且在 debug 的時候，可以以資料模型為基準，追蹤資料在程式中的流動、並分析哪裡出錯。例如實際內容與模型不符合、或是在哪一部的模型轉換做錯了。

每個 phase 的最後一步當然要馬上 commit 並 push，確保每個階段的成果都被記錄下來。

驗證結果¶

這步驟一個可以從 tests 生出的檔案進行驗證；也可以想edge case、自己操作看看成果、跑一次冒煙測試等等。

Time Compass 的不可取代性¶

這份文件回答兩個相近，但不完全一樣的問題：

這個專案的不可取代性是什麼？
我們會不會很容易被取代？

先講結論：

如果只看單點功能，我們當然可能被取代。
如果看的是整套「資料整合 -> 清洗壓縮 -> 獨特 prompt 引導 AI 規劃 -> 人類比較與決策 -> 實際落第」流程，短期內就沒有那麼容易被取代。

回顧: 專案的定位是什麼¶

我們的定位是「讓 AI 輔助使用者進行時間規劃」。

回顧: 專案的功能有哪些¶

Schedule: 將輸入的任務拆解成子任務，並綜合各方面資料做出有時間概念的規畫建議。
Summary: 協助使用者回顧過去一段時間的事件。
Emotion Support: 在使用者情緒較為激烈、低沉的時候，提供情緒安撫與支持，降低使用者的心理阻力。

我們接下來以 Schedule 為例，因為它同時也會用到跟 Summary 相關的能力。

現行情況下，想用AI安排時間會遇到：¶

我們發現最大的困擾通常不在於「AI無法幫忙」，而在於「用了AI還是無法把事情做好」。

我們認為，有四個常常會卡住的地方(使用者痛點)：

資訊散落在不同來源(有些還只能截圖!)，光是整理與貼上就很麻煩。
如果把原始資料全部丟給 AI，AI 很快就會達到他能處理的資料上限。
如果直接叫 AI 幫忙總結或拆解，最後常常只會得到空泛、難執行的結果。
即使 AI 真的產生了一份規劃，使用者也未必能直觀看懂時間到底花在哪裡、安排是否合理。

那我們的產品做了什麼?¶

我們把使用者的四個痛點接成一條完整流程：

聚合：先用程式聚合多個來源的資訊，降低使用者的整理成本。
壓縮：再清洗與壓縮內容，讓 AI 能在有限 context 內處理真正重要的資訊。請點👉資料壓縮。
Prompt：再用有設計過的 prompt 與流程，把模糊需求轉成比較具體的規劃草案。請點👉Prompt 設計。
前端：最後把結果放進前端介面的日曆視圖，讓使用者可以直觀理解、比較並決定如何採用。

所以，我們會不會很容易被取代？¶

如果只看表面功能，答案其實是：有些部分確實不難重現。

例如：

單次對話式摘要
單一模型產生待辦清單
基礎的 Google OAuth 接入
一般性的 MCP / skills 包裝

因此，這份作品的價值不在單一功能，而在完整的流程。

沒有聚合，使用者連開始都很痛苦。
沒有壓縮，AI 很難理解整段時間。
沒有流程化的 prompt，拆分結果容易空泛。
沒有前端預覽，使用者看不懂草案如何落在自己的時間線上。

少了其中任何一層，體驗都會下降。

Time Compass 的價值從來就不只在於單一功能，而在於我們深入「時間規劃」這個具體場景，把 AI、資料、流程、介面垂直整合，給予使用者一條完整的規劃鏈路。

參考資料 (Reference)

TOON (Token-Oriented Object Notation) 格式規範¶

1. TOON 在四大不可取代性中的位置¶

在 time_compass 的四大不可取代性中，TOON 對應的是壓縮，負責把東西壓縮成模型可有效使用的格式。

👉 不可替代性

2. TOON 要解決的核心問題¶

原始 API JSON 對人類工程師是合理的，但對 LLM 有幾個明顯問題：

重複鍵值太多
同一批事件會一再重複 summary、start、end、location 等 key，浪費大量 token。
巢狀結構不利於快速比較
LLM 要做排程、衝突判斷、期限推理時，真正重要的是時間元件與狀態，而不是一層層物件包裝。
跨來源資料結構不一致
Calendar、Tasks、Moodle 有不同的欄位命名與分組方式，直接塞給模型會增加理解負擔。
高度重複資訊沒有被抽離
地點、重複規則、課程名稱、tasklist metadata 常常在多筆資料中重複出現。
單靠 prompt 無法彌補表示層成本
Prompt 可以教模型如何解讀，但無法消除輸入本身的大量冗餘 token。

3. 壓縮策略與對應收益¶

以下為 TOON 格式達成高壓縮率的核心策略，以及各自解決的問題：

策略	做法	直接收益	實作位置
Schema-less Header	用 `start_here[10]{id,summary,...}` 一次定義欄位，後續各列只放值	消除重複 key 字串	`utils/toon_utils.py` `safe_encode`
索引化	地點、重複規則、課程名稱抽到 `location_index` / `recurrence_index` / `course_index`	降低重複長字串成本	`models_toon.py` `_build_location_index`, `_build_recurrence_index`
依照時間分組	將 ISO DateTime 分解為日期、週幾、時分等元件	提升時間比較與推理效率	`models_toon.py` `_parse_datetime_parts`
語義分組	按月份、任務狀態、學期等自然語意分桶	降低模型先自行整理資料的負擔	`build_toon_calendar`, `build_toon_tasklist`, `to_toon_moodle`
更改值	`null` 改為 `0`，同月改為 `same`	進一步降低 token 並保持可判讀性	`models_toon.py` `build_toon_event`, `build_toon_task`

4. 壓縮效益實測數據¶

根據 scripts/analyze_toon_compression.py 分析 assets/fixtures/snapshots（清洗後的真實資料）的結果：

分析腳本: scripts/analyze_toon_compression.py
執行/測試指令 (uv): uv run python scripts/analyze_toon_compression.py
資料規模: Google Calendar 188 事件、Google Tasks 47 任務、Moodle 10 課程事件
Token 計數工具: tiktoken (Encoding: o200k_base / GPT-4o)
資料流: fixtures JSON -> AllCalendarEventsSnapshot (Layer 2) -> AllCalendarEventsResult.from_snapshot() (Layer 3) -> ResourceContext -> TOON
完整報告: TOON_STATS_REPORT.md
TOON 成品: get_time_context_composite.toon

指標	標準 JSON	TOON 格式	改善幅度
字元數 (Chars)	304,082	28,789	-90.5%
精確 Token (GPT-4o)	96,772	15,800	-83.7%
資訊密度	1.0x	6.1x	大幅提升

格式對比：雙事件範例¶

原始 Google Calendar API JSON（兩筆事件）：

[
  {
    "id": "evt_a",
    "summary": "書法及習作（一）",
    "location": "臺科大 TR-510 教室",
    "start": { "dateTime": "2025-11-03T13:20:00+08:00", "timeZone": "Asia/Taipei" },
    "end": { "dateTime": "2025-11-03T15:10:00+08:00", "timeZone": "Asia/Taipei" },
    "recurrence": null,
    "description": null
  },
  {
    "id": "evt_b",
    "summary": "計算機程式與應用實習",
    "location": "臺科大 TR-510 教室",
    "start": { "dateTime": "2025-11-10T13:20:00+08:00", "timeZone": "Asia/Taipei" },
    "end": { "dateTime": "2025-11-10T15:10:00+08:00", "timeZone": "Asia/Taipei" },
    "recurrence": null,
    "description": null
  }
]

TOON 格式（兩筆事件）：

location_index[1]{lid,location}:
  L1,臺科大 TR-510 教室
month:
  "2025-11":
    start_here[2]{id,summary,lid,rid,notes,st_d,st_wd,st_hm,en_m,en_d,en_wd,en_hm}:
      evt_a,書法及習作（一）,L1,0,0,3,1,"13:20",same,3,1,"15:10"
      evt_b,計算機程式與應用實習,L1,0,0,10,1,"13:20",same,10,1,"15:10"

關鍵差異：JSON 兩筆事件都重複完整欄位名稱與巢狀 key；TOON 只宣告一次欄位 header，後續每列只放值，並以 L1 參照共享 location。

關鍵優勢¶

極致節省 Token: 讓 AI 能在單次請求中載入數個月份的完整排程，而非僅限於當週。
模型推理精準度: 結構化表格式資料減少模型對冗餘格式噪音的注意力分散。
人類可讀性: 雖為壓縮格式，但仍保留層次與索引，方便開發者 debug 與追蹤資料分布。

5. TOON 結構總覽¶

對於 AI 最常用的 time_context 工具來說，TOON 會把資料組成 meta、google_tasks、google_calendar、moodle 等區塊；在各區塊內再依資料源或語意分組。

A. 區塊分組¶

資料依來源分為 meta, google_tasks, google_calendar, moodle 四大區塊。每個區塊下以資源 ID 或資源名稱作為鍵值。

B. 外部索引¶

為了避免在每個項目中重複寫入冗長字串，TOON 會在區塊頂部建立索引：

location_index: 映射為 L1, L2 ...（如 L1,臺科大教室）
recurrence_index: 映射為 R1, R2 ...（如 R1,每週一重複）
course_index: 映射為 c1, c2 ...（如 c1,EC1012301 計算機程式與應用實習）

C. CSV 型 Header¶

每個資料列表都有一個帶有欄位定義的標題：

start_here[數量]{欄位1,欄位2,...}

緊接著是數行簡化資料，以逗號分隔。
解讀時，應永遠以 header 內欄位順序為準。

D. 語義分組¶

不同來源採用不同分組方式：

Google Calendar: 以月份分組；目前實際使用 start_here，另預留 end_from_past
Google Tasks: 以月份 + 狀態分組，分為 due_open、due_done、done，另有 undated
Moodle: 以學期 -> 月份雙層分組

6. 真實資料範例¶

A. Google Calendar¶

按月份鍵分組（"2025-11"），每月內含 start_here（當月開始的事件）：

month:
  "2025-11":
    start_here[23]{id,summary,lid,rid,notes,st_d,st_wd,st_hm,en_m,en_d,en_wd,en_hm}:
      event_id,書法及習作,L1,0,0,3,1,"13:20",same,3,1,"15:10"

實作位置：models_toon.py build_toon_calendar

B. Google Tasks¶

每個 Tasklist 下按截止日期月份分組，任務再依狀態細分：

due_open: 有截止日期、尚未完成
due_done: 有截止日期、已完成
done: 無截止日期、但已完成（按完成時間分月）
undated: 無截止日期且未完成的任務

另外，parent_tree 記錄了父子任務的從屬關係，以節省在每支葉任務上重複記錄父任務資訊：

"Project-big":
  parent_tree:
    "Coding101開發"[6]: 海報&程式碼,出席資料回報,refresh掛回去,掛litellm,...
  month:
    "2026-03":
      due_open[2]{...}:
        ...
  undated[16]{...}:
    ...

實作位置：models_toon.py build_toon_tasklist, _build_parent_tree

C. Moodle¶

課程名稱提取至 course_index，內部使用 c1, c2 短標識。事件按學期 (semester) -> 月份雙層分組：

moodle:
  course_index[3]{cid,course}:
    c1,EC1012301 計算機程式與應用實習
    c2,EC163A011 物理(上)
  semester:
    "114-1":
      "2025-11":
        due[10]{title,description,cid,status,due_d,due_wd,due_hm}:
          Week 9作業繳交截止,Masked,c1,Closed,2,7,"00:00"

實作位置：moodle/models/models_read.py to_toon_moodle

D. Google Calendar 完整片段¶

google_calendar:
  "台科大課表":
    location_index[1]{lid,location}:
      L1,臺科大 TR-510 教室
    recurrence_index[1]{rid,rule}:
      R1,每週一重複
    month:
      "2025-10":
        start_here[1]{id,summary,lid,rid,notes,st_d,st_wd,st_hm,en_m,en_d,en_wd,en_hm}:
          evt_03iq,線代,L1,R1,"導師：...",13,1,"13:20",same,13,1,"15:10"

欄位解讀重點：

lid / rid: 對應外部索引。若為 0 則代表無。
st_d: Start Day（日期）
st_wd: Start Weekday（1-7）
st_hm: Start Hour:Minute（如 "08:00"）
same: 代表該欄位與當前分組 month 或起始月份相同，用以減少重複字串。

7. 實際欄位總表¶

上面的範例只是在說明 TOON 的壓縮方式，不是完整 schema。
實際解讀時應以 header 內的欄位列表為準。

A. Google Tasks¶

Tasklist 容器欄位

欄位	說明
`source.id`	tasklist id
`source.title`	tasklist 標題
`parent_tree`	父任務標題 -> 子任務標題列表
`month`	以 `YYYY-MM` 分組的任務集合
`undated`	無 due 且未完成的任務列表

任務列固定 header

{id,title,tl_id,tl_title,notes,done_m,done_d,done_wd,done_hm,due_m,due_d,due_wd,due_hm}

欄位	說明
`id`	task id
`title`	任務標題；若同 tasklist 內重名，可能被自動改成 `標題#1`、`標題#2`
`tl_id`	tasklist id；通常與外層 `source.id` 相同，缺值為 `0`
`tl_title`	tasklist 標題；通常與外層 `source.title` 相同，缺值為 `0`
`notes`	任務說明；缺值為 `0`
`done_m/done_d/done_wd/done_hm`	完成時間元件；若未完成則整組通常為 `0`
`due_m/due_d/due_wd/due_hm`	截止時間元件；若無 due 則整組通常為 `0`

B. Google Calendar¶

Calendar 容器欄位

欄位	說明
`source.id`	calendar id
`source.summary`	calendar 標題
`location_index`	`lid -> location` 對照表
`recurrence_index`	`rid -> recurrence rule` 對照表
`month`	以 `YYYY-MM` 分組的事件集合

事件列固定 header

{id,summary,lid,rid,notes,st_d,st_wd,st_hm,en_m,en_d,en_wd,en_hm}

欄位	說明
`id`	event id
`summary`	事件標題
`lid`	地點索引 id；無地點為 `0`
`rid`	recurrence 索引 id；無 recurrence 為 `0`
`notes`	事件 description；缺值為 `0`
`st_d/st_wd/st_hm`	開始時間元件；全天事件 `st_hm="full_day"`
`en_m/en_d/en_wd/en_hm`	結束時間元件；若與開始月份相同則 `en_m="same"`

C. Moodle¶

Moodle 容器欄位

欄位	說明
`course_index`	`cid -> course` 對照表
`semester`	以學期 -> 月份雙層分組的截止事件集合

截止事件常見 header

{title,description,cid,status,due_d,due_wd,due_hm}

欄位	說明
`title`	事件標題
`description`	事件說明；缺值為 `0`
`cid`	課程索引 id
`status`	`Open` / `Closed` / `Not yet open` / `Overdue (Grace period)`
`due_d/due_wd/due_hm`	截止時間元件

8. TOON 解讀規則（Prompt Description）¶

以下為目前使用的 TOON 解讀規則字串（提供給模型先讀索引再解讀事件/任務）：

此資料為 TOON 壓縮格式，請先讀索引再解讀事件/任務列。
[共通規則]
- 0 表示無值或未提供。
- "same" 表示與當前分組 month 相同。
- weekday: 1=週一, 7=週日。

[google_tasks]
- source: tasklist 基本資訊。
- parent_tree: 父任務標題 -> 子任務標題列表。
- month[YYYY-MM] 分組語意：
  - due_open: 有 due 且未完成。
  - due_done: 有 due 且已完成。
  - done: 無 due 且已完成（按 completed 分月）。
- undated: 無 due 且未完成。
- 任務時間欄位：due_m/done_m = same | 月份數字(1-12) | 0；due_d/done_d=日期；due_wd/done_wd=週幾；due_hm/done_hm=HH:MM 或 0。

[google_calendar]
- source: calendar 基本資訊。
- location_index: lid -> location（事件內用 lid 參照）。
- recurrence_index: rid -> recurrence rule（事件內用 rid 參照）。
- month[YYYY-MM] 分組語意：
  - start_here: 事件起始時間在本月。
  - end_from_past: 從前月延續到本月（欄位預留，若出現才解讀）。
- 事件時間欄位：st_d/st_wd/st_hm 為開始；en_m/en_d/en_wd/en_hm 為結束。en_m = same | 月份數字 | 0；全天事件 st_hm/en_hm="full_day"。
- lid/rid=0 表示該事件無 location/recurrence。

[moodle]
- course_index: cid -> 課程名稱。
- semester[學期][YYYY-MM].due[]: 截止事件列表。
- 每筆 due 常見欄位：title, description, cid, status, due_d, due_wd, due_hm。

Time Compass 提示詞設計完整指南¶

簡介¶

Time Compass 的提示詞系統以心理學驅動的漸進式決策為核心，將使用者的模糊想法逐步轉化為可執行的行動方案。整個系統從判斷意圖的路由開始，經過情感承接、方案規劃、行動拆解、質詢確認，最後到總結回顧，形成一個完整的時間管理閉環。

我們有兩個架構，分別是dspy （舊版本）以及 mcp （新版本），兩者有相似的功能，新版本新增可以將方案可視化供使用者選擇。

核心設計理念： - 非評判性：絕不責備使用者的拖延、混亂或情緒 - 認知友善：減少使用者的理解負擔（CLT 認知負荷理論） - 動機平衡：在「適度挑戰」與「可達成」間找到平衡點（葉杜法則） - 循序漸進：從模糊目標 → 可行方案 → 具體行動 → 實踐驗收

核心理念與心理學基礎¶

1. 認知負荷理論（Cognitive Load Theory, CLT）¶

應用原則： - 聚焦與分段：不一次呈現超過 3–5 個選項或要點 - 漸進揭示：先給方向，再補細節 - 層級清晰：用標題與列點減少理解成本

在各模組中的實踐： - Router：只輸出 1–3 句承接文案，不超過 15 個單詞 - DraftPlan：候選時段限制在 2–5 個 - AskQuestion：題數 3–5，每題 3–5 選項

2. 認知行為治療（Cognitive Behavioral Therapy, CBT）¶

核心技巧： - 去災難化：「這分心情很正常，你不是唯一的」 - 共感不同情：認可情緒，但不表示憐憫 - 行為啟動：提供 1–2 個簡單的立刻可做活動（≤2 分鐘）

在 EmotionSupport 中的實踐： - 點出具體情緒（沮喪、焦慮、疲勞）而非籠統接受 - 將情緒正常化：「這是很多人都有的狀態」 - 提供微行動建議：喝杯熱水、深呼吸等可立即執行的小步驟

3. 葉杜心理定律（Yerkes-Dodson Law）¶

原理： 適度的壓力與挑戰能提升動機，但過多則導致焦慮，過少則無法激發。

動機-壓力曲線應用： - 重度情緒（焦慮、低落）→ 降低難度，給極小步驟 - 輕度情緒（開心、中立）→ 提供適度挑戰 - 語氣調整：避免指令句（「你應該...」→ 「我們一起...」）

具體措施： - 任務時限 ≤60 分鐘（「可達成感」） - 層級化選項（「無壓力選項」 vs 「挑戰選項」） - 緩衝時間設定（+10–20%）

架構¶

我們根據功能，將prompt 分成三個部分，分別是：情緒承接(emotion support)、計劃安排(schedule)、過去總結(summary)，此外還有負責分配路徑的router 。情緒承接根據使用者情緒狀態決定要呼叫幾次以及具體位置，同時需要計劃安排以及過去總結時，先執行過去總結再執行計畫安排。

router¶

兩組架構的router 從本質上就是完全不同的： - DSPy： router.md - DSPy 架構下的路由是將 ‘router.md’ 作為prompt 交給ai 讓它判斷使用者的需求與情緒，將會需要的功能與功能的順序製成pipeline_description 交給程式用if…else 判斷需要呼叫其他哪些prompt 。 - 情緒分流策略： - 重度情緒（低落/憤怒/焦慮/疲勞） - 第一輪：["EmotionSupport", <task>, "EmotionSupport"]（前後夾擊） - 後續：[<task>, "EmotionSupport"]（尾部收尾）

    - **中度情緒**（開心/輕度負面）
        - 第一輪：`[<task>, "EmotionSupport"]`（後置收尾）
        - 後續：可省略或選擇性收尾

    - **無明顯情緒**
        - 直接路由至任務模組

MCP：
- MCP 架構內沒有一個專門的 router.md ，我們將各個功能的觸發條件用docstring 的方式呈現給AI ，讓它自己判斷需要使用什麼功能。

情緒承接¶

兩組下架構的情緒承接是幾乎一樣的（分別domain/ mcp資料夾中的emotion_support.md)，AI 扮演INFJ 的溫柔學長姐，承接使用者的負面情緒，並作為承接其他功能的橋樑。我們將這個功能分成四段：

A1/A2情緒處理：分為承接與收攏
- 負責正常化使用者的情緒
B溫柔過度：
- 如有有承接功能則引出接下來的功能
- 若沒有承接功能，則告訴使用者情緒是正常的
C微行動建議：
- 提供簡單的、快速的放鬆小活動
D輕鬆收尾

規劃安排¶

兩個架構中的規劃安排的流程是一樣的，但是MCP 架構中只有一個完整的’ tem.md ’； DSPy 架構中則拆分成 ‘ draft_plane.md ’ 、‘draft_action.md’ 、‘(scheduling)router.md’以及’ask_question.md’。

MCP 架構 — tem.md ： MCP 架構中的’ tem.md ’將整個schaduling 功能融合近一個prompt內:
- 將計劃分為三級：
  - L1 ：模糊且空泛
    - 任務：確認具體目標與截止時間
    - 輸出：
    - 對齊目標 — 透過復述和使用者確認目標和現有資訊
    - AI 能為你做什麼 — (可能包含)介紹能提供的協助/淺再困難與風險/可用的網路資源
    - 初步規劃 — 提供計畫的大方向
    - 缺失的資訊或潛在風險
    - 資訊追問 — 用 1–5 題選項題確認規劃方向與必要資訊
    - 說明回復完後如何細化
    - 收尾 — 低調鼓勵，口吻輕鬆
  - L2 ：有具體目標 — 可以進行規劃
    - 任務：進行任務差分與資訊追問
    - 輸出：
    - 確認任務邊界 — 複述確切目標、已知條件、完成期限
    - 粗流程 — 計畫的大致流程和整體節奏
    - 行動任務清單 — 具體的規劃細節
    - 向使用者提議進入排程，並主動詢問計畫是否足夠詳細(若判斷仍不足排成則會跳過)
    - 最小追問 — 用 1–5 題選項題確認必要資訊
  - L3 ：認為拆分完成
    - 任務：可以生成計畫方案
    - 輸出：
    - 提供備選方案 — 含「詳細任務、產出物、完成定義、風險」
    - 啟動視覺化頁面
    - 詢問 — 詢問使用者要選擇哪個方案以及有沒有需要更改的地方
    - 情緒辨識收尾 — 判斷是否呼叫emotion_support
DSPy 架構： DSPy 架構中，為了加速回復產出，我們將schaduling 功能prompt 拆分為四個檔案
- 四個檔案：
  - router 模組： router.md
    - 任務：判斷並路由使用者至適當的排程子模組（draft_plan 或 draft_action）
    - 輸出：
    - 對齊目標 — 透過復述和使用者確認目標和現有資訊
    - AI 能為你做什麼 — (可能包含)介紹能提供的協助/淺再困難與風險/可用的網路資源
    - task_level: 判定的任務等級：L1 / L2 / L3。(是內部用，使用者不可見)
  - DraftPlan 模組： draft_plan.md
    - 任務：把使用者較抽象或方案級的需求，轉成「可立刻開始的粗規劃」
    - 輸出：
    - 梳理規劃 — 提供計畫的大方向
    - constraints_and_missing_info: 缺失的資訊或潛在風險 — 輸出給AskQuestion 模組的缺失資訊
    - 要怎麼排出更詳細的計畫 — 為問問題做鋪墊
  - DraftAction 模組： draft_action.md
    - 任務：把需求轉成「行事曆可執行」的具體行動與候選時段
    - 輸出：
    - action_description : 備選方案 — 提供計畫的規劃/步驟
    - start_instructions : 開始的第一步
    - constraints_and_missing_info: 缺失的資訊或潛在風險 — 輸出給AskQuestion 模組的缺失資訊
    - action_metadata: List[GoogleTaskCreate] — 用於直接在 Google Tasks 建立任務
  - AskQuestion 模組： ask_question.md
    - 任務：進行資訊追問
    - 觸發方式 :由DraftPlan 模組或
    - 輸出：
    - 簡介 — 告訴使用者為了規劃需要確認更多資訊，以及知道這些資訊後，能為他做甚麼」
    - 3–5 題選項題（每題含「我不確定/我不知道」）
    - next_steps_suggestion — 告訴使用者回完後的具體交付

過去回顧¶

兩組下架構的過去回顧是幾乎一樣的（分別domain/ mcp資料夾中的summary_writer.md)，讓AI 做為過去計畫完成進度總結助手，扮演一位溫和的觀察者。我們將這個功能分成四段： 1. 每日回顧: - 摘要指定的時間段都做了些什麼 - 完成度分析 2. 改進建議: - 若有未完成規劃，則提出替代方案 3. 總結: - 提供整個時間段的總結，包含: 1. 各個任務事項的時間占比 2. 情緒大致狀態 3. 代辦事項提醒 4. 若是使用者有記帳，則分析財務資料 5. 此時間段達成的成就與亮點 6. 結尾

情緒與狀態(只在詢問是否需要後觸發):
- 使用者健康、精神狀態分析
- 效能分析

實作位置¶

MCP 註冊：src/time_compass/mcp/prompts/domain_prompts.py
MCP Prompt 內容：src/time_compass/mcp/prompts/content
Domain Prompt 來源：src/time_compass/domain/*/prompt

使用者輸入 AI 應做的事與預期回復¶

預期回復¶

第一輪對話
輸入 : 幫我看看我這兩周都做了甚麼，我好累喔，還得複習微積分才行，也幫我排未來兩周的複習行程
1. 思考:
2. 使用者想要： - 回顧過去兩週完成的事項 - 感到疲憊（為中度情緒，需要情感支持） - 需要複習微積分 - 規劃未來兩週的學習進度表
3. 判斷:
  - 需要呼叫:
    - emotion support prompt (emotion_support.md)
    - summary writer prompt (summary_writer.md)
    - time management master prompt (MCP 架構中只有一個完整的’ tem.md ’；或 DSPy 架構中的 ‘ draft_plane.md ’ 、‘draft_action.md’ 、‘(scheduling)router.md’以及’ask_question.md’。)
    - 使用者過去兩周的行事曆
    - 使用者未來兩周的行事曆
4. 輸出(使用AI 為 Cloude Opus 4.6):
  - emotion support:
    1. 我有聽到你的疲憊
    2. 我們一起慢慢來
    3. 現在可以先這麼做
    4. 準備好了的話，我們就開始吧
  - summary:
    1. 大標題: 讓我們來看看過去兩週發生了什麼吧
    2. 事件回顧:
      - 各種類事件
    3. 完成度分析與改進建議
    4. 總結:
      - 時間分配概覽
      - 情緒大致狀態
      - 待辦事項提醒
      - 這段時間的小成就與亮點
      - 詢問是否需要狀態分析
  - scheduling:
    1. 我們來對齊一下你的目標
    2. 我可以幫你做的事
    3. 我需要知道以下資訊
    4. 四題選擇題
    5. 知道這些之後，我就能幫你拆出具體的複習任務，再排進你的行事曆裡 💪(停頓等待回復)
第二輪對話
輸入 : 選擇題的答案
- scheduling:
  1. 我來確認一下資訊
  2. 我們來看看計畫大致流程
  3. 以下是詳細的複習任務拆解
    - 擷取部分:
    - 📘 單元一：極限與連續性
      - 任務 1-1｜極限的直觀概念與定義
        
        📄 產出物：在講義上標記重點公式，寫出 3 個極限定義的關鍵句
        
        ✅ 完成定義：能用自己的話解釋 ε-δ 定義的意思
        
        ⚠️ 風險：ε-δ 定義較抽象，可能需要多看幾次
        
        ⏱️ 約 30 分鐘
  4. 確認一下(計畫是否拆分的足夠細緻，足以進入日曆安排)
第三輪對話
輸入 : 好幫我安排
- scheduling:
  1. 方案出爐啦！我們來看看有哪些選擇吧
    - 方案 A：穩定每日型 📅
    - 方案 B：課後連結型 🔗
    - 方案 C：週末集中型 🌙
  2. 開啟前端視覺化方案
第四輪對話
輸入 : C 但是幫我在假日複習時間內加入休息時間
- scheduling:
  1. 方案 C 改良版來囉！加入休息時間的三個子方案
    - 方案 A：早鳥型（週末 09:30 開始）🌅
    - 方案 B：午後型（週末 14:00 開始）☀️
    - 方案 C：折衷型（週末 10:00 開始）⚖️
  2. 開啟前端視覺化方案
第五輪對話
輸入 : 用C 吧幫我寫進日曆
- scheduling:
  1. 全部寫進 Google Calendar 了！✅
    - 計畫的全部任務與時間
    - 動作: 寫入 Google Calendar
- emotion support:
  - 你其實做得很好 ✨

Time Compass 文檔首頁¶

我想快速體驗 Time Compass¶

我想知道專案的價值與技術亮點¶

我想知道專案的技術細節¶

Time Compass 教程與快速開始¶

想安裝 Time Compass?¶

想體驗初賽版¶

Time Compass Q&A（給使用者與評審）¶

Q-DIFF-001 為什麼不是直接用 ChatGPT + Actions + 個人化 GPT？¶

Q-DIFF-002 為什麼不是直接用 Gemini 接 Google Workspace？¶

Q-DIFF-003 為什麼不是用市面上的 MCP 就好？¶

Q-DIFF-004 為什麼不是只做成 skills？¶

教程 (Tutorial)

快速開始 — Mock 模式¶

準備工作¶

Part 1：基礎環境設定¶

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

Windows (PowerShell)¶

macOS / Linux¶

Part 2：使用範例資料體驗（兩項功能）¶

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

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

MCP 環境建置與整合指南（Mock 模式）¶

Step 1: 配置 MCP 客戶端¶

準備工作¶

選擇你的工具¶

工具與設定檔對照（Windows）¶

JSON 格式（mcpServers，給Copilot(VScode)跟Codex以外的）¶

VS Code (Copilot)¶

Codex¶

Step 2: 驗證連線狀態¶

VS Code (Copilot) 特殊步驟¶

基本驗證¶

最後一步: 接入真實資訊¶

故障排除¶

Google OAuth 驗證流程（Time Compass）¶

簡介：完整驗證流程¶

準備工作：確認環境變數設定¶

Step 1：啟動 OAuth 授權流程（擇一）¶

Step 2：完成瀏覽器授權¶

可能遇到的狀況：Google 未驗證應用程式警告¶

Step 3：確認 token.json 產生¶

下一步?¶

概念說明 (Explanation)

Time Compass Q&A（給使用者與評審）¶

Q-DIFF-001 為什麼不是直接用 ChatGPT + Actions + 個人化 GPT？¶

Q-DIFF-002 為什麼不是直接用 Gemini 接 Google Workspace？¶

Q-DIFF-003 為什麼不是用市面上的 MCP 就好？¶

Q-DIFF-004 為什麼不是只做成 skills？¶

我們如何使用 AI¶

產品上：AI 幫忙整理與提案，人負責選擇¶

開發上：先規劃，再動手¶

為什麼方案挑選不能交給 AI¶

最有價值的是人的成長¶

跟 AI 還會在其他方面合作嗎?¶

那麼，我們是如何開發的¶

釐清問題¶

選擇方案¶

分階段解決¶

驗證結果¶

Time Compass 的不可取代性¶

回顧: 專案的定位是什麼¶

回顧: 專案的功能有哪些¶

現行情況下，想用AI安排時間會遇到：¶

那我們的產品做了什麼?¶

所以，我們會不會很容易被取代？¶

參考資料 (Reference)

TOON (Token-Oriented Object Notation) 格式規範¶

目次¶

1. TOON 在四大不可取代性中的位置¶

2. TOON 要解決的核心問題¶

3. 壓縮策略與對應收益¶

4. 壓縮效益實測數據¶

格式對比：雙事件範例¶

關鍵優勢¶

5. TOON 結構總覽¶

A. 區塊分組¶

B. 外部索引¶

C. CSV 型 Header¶

D. 語義分組¶

JSON 格式（`mcpServers`，給`Copilot(VScode)`跟`Codex`以外的）¶