Dev Mode Guide (Current Behavior)¶

目的¶

這份文件描述 目前程式碼中的實際 Dev Mode 行為，作為唯一維護版本。
重點是避免再以舊設計稿（integration 層切換）解讀系統。

TL;DR¶

目前開關是 MCP_DEV_MODE，不是 TIME_COMPASS_DEV_MODE。
切換點主要在 src/time_compass/mcp/ 與 src/time_compass/domain/，不是 integration async_core。
MCP_DEV_MODE=1 時，大量流程會改走 fixture/mock，許多測試若仍期待真實 API 分支會失敗。

單一開關¶

MCP_DEV_MODE=1   # 開啟 Dev Mode
MCP_DEV_MODE=0   # 關閉 Dev Mode（預設）

核心判斷函式：

src/time_compass/mcp/dev_mode.py:is_dev_mode()

目前 fixture 來源路徑為硬編碼：

assets/fixtures/snapshots

切換層級（實際）¶

1) MCP Tools 層¶

calendar_tools.py / task_tools.py / other_tools.py 在入口直接判斷 is_dev_mode()，為真時 early return mock/fixture 結果。

影響：

不會走真實 Google/Moodle API 呼叫。
參數可能被部分忽略（尤其時間範圍與 auth 相關分支）。

2) MCP Runtime 層¶

src/time_compass/mcp/runtime.py 在 fetch_context() 與 apply 流程也有 is_dev_mode()：

fetch_context() 會改用 get_mock_resource_context()。
套用行程 (_apply_variant_to_calendar) 會回傳 mock success，不寫入真實日曆。

3) Domain 層（Gradio 間接生效）¶

SummaryModule 與 SchedulingModule 內部會檢查 is_dev_mode()，為真時改用 get_mock_resource_context()。

這代表：

gradio_app.py 本身沒有直接讀 env。
但 Gradio 的 scheduling pipeline 會經過 domain module，因此會間接受 Dev Mode 影響。

4) Script 層¶

scripts/run_planner_studio.py 預設會設 MCP_DEV_MODE=1（除非傳 --real）。

行為矩陣¶

元件	`MCP_DEV_MODE=0`	`MCP_DEV_MODE=1`
MCP tools	真實 API / 正常 auth 路徑	直接回 fixture/mock
MCP runtime fetch_context	走 integration 抓資料	走 `get_mock_resource_context()`
Planner apply	真實寫入 Google Calendar	Mock 套用結果，不寫入
Gradio Summary/Scheduling	真實抓取資料	走 mock resource context
run_planner_studio.py	需 `--real` 才進真實模式	預設即 dev mode

測試策略¶

建議明確區分兩組測試：

dev mode suite
測試前設定 MCP_DEV_MODE=1
斷言 fixture 路徑與 mock 行為
real-path suite
測試前確保 MCP_DEV_MODE 未設定或為 0
斷言 auth error、API failure、真實路由行為

若把整包測試在 MCP_DEV_MODE=1 下執行，許多「應該走真實分支」的測試會被短路，出現大量非預期失敗。

常見誤解¶

誤解 1：Dev Mode 在 integration 層切換¶

現況不是。
目前主要是 MCP/domain 層直接分支，integration async_core 並沒有統一的 dev_mode.py 切換架構。

誤解 2：`DEV_MODE_DATA_PATH` 可控制 fixture 路徑¶

現況不是。
目前 mcp/dev_mode.py 使用硬編碼 assets/fixtures/snapshots。