跳轉到

Refactor Roadmap (精確定義版)

本文件紀錄 Time Compass 的核心技術債、重構規劃與架構演進方向，旨在維持系統整潔並確保關鍵資料流的強健性。

1. 核心架構與穩定性 (Core Architecture & Stability)

1.1 Error Handling 統一化

  • 現狀：async_client 在遇到 API 錯誤時會直接 raise Exception，而上層的 async_core.py 則被迫包裹大量 try...except 捕捉並轉化為 Result pattern。
  • 為何如此：專案早期快速迭代，混用了異常機制與結果對象。
  • 目標狀態：將 async_client 改為回傳含有錯誤 ID 或訊息的對象，實現純粹的函數式結果導向設計，移除 async_core 的攔截邏輯。
  • 影響範圍：integrations/google_*/async_core.py, async_client.py
  • 時機：Phase 8
  • 相關紀錄：ADR-0006

1.2 MCP Harden 型別斷層重構

  • 現狀：@mcp_harden 裝飾器在校驗後將 Model 轉回 Dict 傳入原函數，導致原函數的強型別 (Type Hint) 契約斷層。
  • 為何如此：初衷是為了清理 MCP 傳輸層可能導致的字面引號鍵值（如 ' "variants" '）。
  • 目標狀態：修改裝飾器，改為直接注入驗證後的 Pydantic對象，或優化 Dict 傳遞邏輯以保護 IDE 的跨函數追蹤能力。
  • 影響範圍：src/time_compass/mcp/base.py 與各工具實作介面
  • 時機：Phase 8
  • 相關紀錄：用戶回報 (Step 1436)

1.3 Streaming 傳輸順序與分片處理

  • 現狀：Orchestrator 的流式輸出有時會直接傳入 Chunk，導致輸出的區塊順序混亂，前端渲染跳轉。
  • 為何如此：dspy 的 streaming 機制在非同步環境下未對 Chunk 序號進行強邊界控制。
  • 目標狀態：實施 Chunk 序號校驗或在前端 Middleware 增加排序緩衝機制。
  • 影響範圍：src/time_compass/domain/orchestrator.py, 前端 Middleware
  • 時機：Phase 8
  • 相關紀錄：用戶回報 (Step 1436)
  • 狀態：已完成
  • 驗收：Streaming chunk 呈現順序穩定，前端無跳段/亂序渲染。

1.4 Auth Token 跨層同步機制

  • 現狀：當後端重新 Refresh Token 後，更新無法無縫傳達到前端 Middleware；run_planner_studio.py 常因 Token 過期而中斷執行。
  • 為何如此：Middleware 缺乏主動重新讀取 Token 或非切換式 Auth 續約邏輯。
  • 目標狀態：建立中央 Auth 狀態監聽器，確保 Token 更新即時同步至所有 Runtime 組件，避免 Refresh 引發的中斷。
  • 影響範圍：mcp/runtime.py, mcp/planner_routes.py, scripts/run_planner_studio.py
  • 時機：Phase 8
  • 相關紀錄：用戶回報 (Step 1436)

2. 資料模型與 TOON 優化 (Data Models & TOON)

2.1 TOON 冗餘 Resource ID 清理

  • 現狀：get_time_context_composite.toon 成品中，各項目內部的 source.id 在層次化 Grouping 下顯得冗餘。
  • 為何如此：沿用早期扁平化結構設計。
  • 目標狀態：移除項目內部的重複 ID，僅保留跨資源索引。
  • 影響範圍：src/time_compass/integrations/*/models/models_toon.py
  • 時機：Phase 8
  • 相關紀錄：詳見上游 assets 目錄中的 get_time_context_composite.toon 檔案

2.2 Moodle 模型與 Google 體系對齊

  • 現狀：Moodle 的 Read Model 與 Google 的 groups/items 標準模式不對齊。
  • 為何如此：Moodle 模組為後期加入，尚未完全完成向 DDD 架構的過渡。
  • 目標狀態：重構 Moodle 整合層模型，使其支援標準的 All*Result 固定模式。
  • 影響範圍：src/time_compass/integrations/moodle/models/
  • 時機：Phase 8
  • 相關紀錄：models_read.py

2.3 Common 整合層解析邏輯 DDD 化

  • 現狀：common/models.py 處理 Response 時使用較為脆弱的正則 Fallback 邏輯。
  • 為何如此：處理 Google Multipart Batch 反應雜訊的權宜之計。
  • 目標狀態：替換為基於 Domain 契約的嚴謹解析。
  • 影響範圍：src/time_compass/integrations/common/models.py
  • 時機：Phase 9
  • 相關紀錄：用戶回報 (Step 1436)

2.4 AllCalendarEventsResult 雙欄位清理

  • 現狀：同時保留 groups/calendars 等 Alias。
  • 為何如此：向後相容 Legacy callers。
  • 目標狀態：Deprecate 舊欄位，移除 runtime.py 裡的 getattr() 防禦代碼。
  • 影響範圍：domain/models.py, runtime.py
  • 時機：Phase 9
  • 相關紀錄：詳見本節（2.4）與對應實作清理任務

2.5 base_models.py 繼承鏈優化

  • 現狀：工具回傳模型的繼承關係與 Pydantic 設定（如額外欄位處理）不一致。
  • 為何如此：不同階段定義的工具結果缺乏統一父類約束。
  • 目標狀態：釐清 Internal/Base Tool Result 的歸屬。
  • 影響範圍：src/time_compass/utils/base_models.py
  • 時機：Phase 9

2.6 核心模組資料注入改用 TOON 格式

  • 現狀：Summary 與 Schedule 模組內部仍使用舊的 JSON-like 注入流程。
  • 為何如此：尚未對接 TOON 高層次 API。
  • 目標狀態：將資料注入點全面替換為壓縮後的 TOON 字串，降低 LLM 首層推理負荷。
  • 影響範圍：src/time_compass/domain/summary/, schedule/
  • 時機：Phase 9

2.7 Model Validation Strict Typing 與 Polymorphic Factory 改造 (Deferred)

  • 現狀：為了方便測試生成 (Dev Mode) 與 Mock 資料的彈性，GoogleEventRead 等模型維持了寬鬆的 from_dict 邏輯與較少的 @model_validator，導致部分 Mock 資料缺乏嚴格結構約束。
  • 曾嘗試過但退回的原因：實施嚴格的 DDD 多型工廠 (Polymorphic Factory) 與推導邏輯下沉後，揭露了大量過去單元測試 (Mock Data) 的結構不完整，引發連鎖紅燈。為了不阻礙核心產品進度，暫時回退。
  • 目標狀態：
  • 修正所有測試場景的 Mock 資料，使其符合 GoogleEventRaw 的正規結構。
  • 重新將 GoogleEventRead.from_raw_model() 強型別化，不再接受 Any，並委派給純粹處理注入的 from_dict()。
  • 將 start/due 到 all_day 的推導邏輯完全下沉至 Pydantic V2 @model_validator(mode="before")，並保持冪等性 (Idempotency)。
  • 時機：Phase 10 (等測試資料集完全重構後)

3. 前端視圖與互動 (Frontend & Visualization)

3.1 Planner Studio 全天事件渲染與 Dev Mode 顯示 Bug

  • 現狀：全天事件在某些時段會因 all_day 標籤遺失導致渲染斷裂；此外，在 dev_mode 下草擬案 (Draft Variants) 經常無法正確顯示。
  • 為何如此：Backend 到 Frontend 的資料傳遞鏈路屬性映射不全，且 Mock 資料與實體渲染邏輯在處理多變體時存在不對齊。
  • 目標狀態：確保資料流在 dev_mode 與 real_mode 下皆能正確標註全天屬性並正常顯示所有草擬變體。
  • 影響範圍：scripts/run_planner_studio.py, mcp/dev_mode.py, 前端 JS
  • 時機：Phase 8
  • 相關紀錄：用戶回報 (Step 1436, 1501)
  • 狀態：已完成

3.2 UI 風格 Premium 化

  • 現狀：風格被回饋較為單調、不夠 Premium。
  • 為何如此：偏重功能實作，美學投入（如玻璃擬態、動態過渡）較少。
  • 目標狀態：引進玻璃擬態、微互動，符合極致美學標準。
  • 影響範圍：src/time_compass/mcp/ui/styles/
  • 時機：Phase 10
  • 狀態：待審核

4. 工作區治理與文件化 (Workspace & Audit)

4.1 README 與安裝指南大整合

  • 現狀：README.md 未整合 CODEX_INSTALL 與 COPILOT_INSTALL；且 README_OLD.md 不符標準。
  • 目標狀態：全面更新 README，融入 MCP 支援細節，並參考 readme skill 進行高品質寫入。
  • 影響範圍：根目錄所有 README 文件
  • 時機：Phase 8
  • 狀態：其他完成（OLD 未完成）

4.2 腳本與代碼「斷捨離」

  • 現狀：scripts/ 下存在廢棄腳本（serve_mlflow.py 等）；domain/optimize 已不使用。
  • 目標狀態：清理所有無效資源，維持系統純淨性。
  • 時機：Phase 9
  • 狀態：完成

4.2.1 安全刪除 src/time_compass/domain/main.py

  • 現狀：domain/main.py 為示範性入口，與正式啟動腳本（time-compass-mcp、time-compass-gradio）無直接綁定。
  • 目標狀態：在不影響現有啟動流程與測試的前提下移除該檔案。
  • 修復步驟：
  • 以 rg 全域確認無 import/reference。
  • 刪除 src/time_compass/domain/main.py。
  • 執行最小啟動驗證：uv run time-compass-mcp、uv run time-compass-gradio。
  • 驗收：啟動命令與主要測試不受影響；若失敗則回補替代入口或文件說明。
  • 時機：Phase 9
  • 狀態：待執行

4.3 文檔審計與 Archive 搬移

  • 現狀：docs/architecture 存在過時文件；archive/old_sessions 資料雜亂。
  • 目標狀態：審查所有文檔的 Up-to-date 狀態，搬移有價值內容，刪除過期廢棄文件。
  • 時機：Phase 9
  • 相關紀錄：docs/ 目錄結構

4.4 評審導向之 WMI 坑位告知

  • 現狀：Windows WMI 穩定性問題為隱藏大坑。
  • 目標狀態：在顯眼處（README）提醒評審如何使用環境變數（如 TIME_COMPASS_DISABLE_WMI_SYSTEM_QUERY）避開。
  • 時機：Phase 8

5. 架構決策與互動深度 (Architecture Decisions & Interaction)

5.1 Gradio 與 DSPy 決策回顧

  • 現狀：舊版 Web UI 使用 Gradio 且後端依賴 DSPy。
  • 為何如此：Gradio 旨在快速原型開發；DSPy 則提供了類似 Pydantic 的結構化輸出與自動回退機制。
  • 目標狀態：在文件（README 或 ADR）中明確記錄此決策背景，並指導使用者依需求選擇：
  • MCP 工作流：uv run time-compass-mcp
  • 舊版 Web UI (Gradio)：uv run time-compass (打開 http://localhost:8000/gradio)
  • 相關紀錄：用戶回饋 (Step 1540)

5.2 Planner Studio API 與 Payload 規範

  • 現狀：前端極度仰賴 /api/context/fetch、/api/plan/generate 與 PlannerDraftVariants 格式，但缺乏契約文檔。
  • 為何如此：前後端目前由同一開發者維護，約定大於配置。
  • 目標狀態：撰寫正式的 API Spec，明確定義變體 (Variants) 傳遞時的 JSON 結構，以釐清前後端邊界。
  • 影響範圍：src/time_compass/mcp/planner_routes.py
  • 時機：Phase 9

5.3 智慧意圖路由 (L1/L2/L3) 與強制停頓機制

  • 現狀：SchedulingRouter 具備 L1/L2/L3 漏斗架構與「強制停頓詢問」機制，但外部文檔完全未提及。
  • 為何如此：核心邏輯隱藏在 Prompt 與 orchestrator.py 中。
  • 目標狀態：建立系統互動流程圖，展示非線性對話如何避免 AI 暴走，並解釋 L1 (模稜兩可) 到 L3 (行動級) 的轉換邏輯。
  • 時機：Phase 8
  • 相關紀錄：用戶回饋 (Step 1540)

5.4 MCP 互動設計：Docstring 與 Tool 聯動

  • 現狀：MCP 工具的 Docstring 對 AI 的觸發至關重要，但目前部分 Prompt 缺乏對 Tool 使用的明確指引。
  • 目標狀態：重構 MCP 工具的 Docstring，確保其與系統 Prompt 形成合力：
  • 若有對應 Tool，Docstring 需精確描述觸發條件。
  • 若僅需 Prompt 回應，Prompt 內部應有引導使用其他對應 Tool 的邏輯。
  • 時機：Phase 8

6. 治理與文檔遺留項 (Governance & Docs Legacy)

6.1 DEV_MODE 文件合併

  • 現狀（已完成）：舊文件已下線，統一為 DEV_MODE_GUIDE.md。
  • 結果：以現況實作（MCP_DEV_MODE、MCP/domain 切換點）為單一說明來源，降低文檔漂移。
  • 時機：Phase 9（完成）

6.2 Data Flow 索引整合

  • 現狀：存在 10 多份細部的 data-flow-*.md。
  • 目標狀態：確保 data-flow.md 成為完美的總合索引，並精簡不必要的細碎分頁。
  • 時機：Phase 9

6.3 README 進階需求 (由 Comparison Report 追蹤)

  • 遺留項：
  • 補齊 Python 3.12+ 標註、不需獨立 DB 的聲明。
  • 加入目錄樹 (Tree) 與 Request Lifecycle 圖表。
  • 補充 Google Cloud 申請步驟 (How-to-get)。
  • 展示測試分層矩陣、對話範例 (Sample Interaction)。
  • 時機：Phase 8
  • 相關紀錄：readme_comparison_report.md.resolved

7. 新增技術債與未來計畫 (Newly Tracked Items)

7.1 output_result 測試細化需求

  • 現狀：測試套件中 output_result 快照覆蓋度不足，目前難以從測試輸出直觀判斷每個函數在每種行為下的結果，調試時仍需手動 print。
  • 目標狀態：每個核心函數（尤其是 integrations/ 的 Adapter 層）在每種行為（成功/失敗/邊界）下均有對應的 output_result 快照或斷言，方便 DDD 除錯時直接比對。
  • 影響範圍：tests/ 目錄（主要是 tests/unit/ 與 tests/snapshots/）
  • 時機：Phase 9

7.2 from_dict → validate-before 資料推導分離重構

  • 現狀：多個 Read Model 的 from_dict 方法混合了「欄位推導（如 all_day 推斷）」與「額外參數注入」兩種責任，語義模糊、不易測試。
  • 目標狀態：
  • validate-before：所有欄位推導邏輯下沉至 Pydantic @model_validator(mode="before")，實現資料內部自洽推導。
  • 額外參數注入：需要外部注入的資料（如 calendar_id）改用明確的 @classmethod 工廠方法，名稱清楚標示其注入語義（如 from_raw_with_calendar）。
  • 移除僅用於相容性的寬鬆 from_dict，統一工廠命名規範。
  • 影響範圍：integrations/*/models/models_read.py（主要影響 Google Calendar、Google Tasks、Moodle）
  • 時機：Phase 10（與 2.7 Model Validation 改造同期）
  • 相關紀錄：本條目由 GUIDE.md 開發規劃觸發（2026-02-28）

7.3 uv 套件管理技術棧說明補充

  • 現狀：pyproject.toml 使用 uv 進行套件管理，但 README 與 docs/ 中缺乏「為什麼選擇 uv」的明確說明，容易讓貢獻者困惑。
  • 目標狀態：在 README 的技術棧章節，以及 docs/adr/ 中新增一份 ADR，記錄選擇 uv 的決策理由（速度、環境隔離、pyproject.toml 標準相容性）與棄用 pip 的原因。
  • 影響範圍：README.md、docs/adr/（新增 ADR 文件）
  • 時機：Phase 8（與 README 整合同期，4.1 一起做）

7.4 Moodle JSON Analysis Skill 計畫

  • 現狀：docs/explanation/moodle_api/ 已記錄 raw.json（Moodle 原始 API Response）與 cleaned.json（手動整理版），但缺乏自動化工具將 raw 轉為 Pydantic 友善的 cleaned 格式。
  • 目標狀態：撰寫一個 Agent Skill（analysis-json-to-pydantic 或類似名稱），支援：
  • 從 raw JSON 推導結構（感知 Optional、型別、巢狀層次）
  • 輸出結構清晰的 cleaned JSON（保留原始值）
  • 增量寫入 docs/ 而非覆蓋全部
  • 可選：自動生成對應的 Pydantic BaseModel 骨架
  • 影響範圍：.agent/skills/（新技能）、docs/explanation/moodle_api/
  • 時機：Phase 9（先完成 Moodle 模型與 Google 體系對齊後進行，參照 2.2）

7.5 Streaming WAIT Payload 語義化（Deferred）

  • 現狀：StreamingCollector 的 WAIT 事件目前直接攜帶最終顯示文字（含 Markdown/emoji），presentation 細節仍在 collector 內。
  • 問題：這會讓傳輸層與呈現層耦合，後續若調整 UI 文案或多視圖輸出，需修改 collector，維護成本偏高。
  • 目標狀態：
  • WAIT 僅承載語義資料（例如 phase/dots_count/timestamp），不直接承載最終 UI 文案。
  • 最終等待文字由 presenter/formatter 組裝，collector 僅提供事件語義。
  • 保持事件型別不變（WAIT/FIELD_START/CHUNK/DONE/ERROR），降低遷移風險。
  • 時機：Deferred（本輪先不處理，待 streaming contract 穩定後再開獨立 change）
  • 備註：目前決策為「先修好 typing 與終止語義」，不擴大範圍到 payload/presenter 深度重構。

7.6 Draft Plan 階段前置產生 TaskList

  • 現狀：Scheduling 流程中，TaskList 主要在後段（如 DraftAction metadata）才被具體化，DraftPlan 階段尚未穩定輸出可直接操作的任務清單。
  • 目標狀態：在 DraftPlan 產生時同步輸出結構化 TaskList（至少包含 title/notes/due/list_id 或等價欄位），讓前端可提早預覽與編修。
  • 影響範圍：src/time_compass/domain/schedule/、src/time_compass/interface/ui/scheduling/
  • 時機：Phase 8

7.7 TaskList 變動自動展開 UI

  • 現狀：TaskList 區塊是否展開目前偏向靜態控制（或依既有事件觸發），當內容有更新時不一定會自動提醒使用者。
  • 目標狀態：當 TaskList 有新增/刪除/修改時，自動展開對應 UI 區塊並高亮更新，降低「有資料但沒看到」風險。
  • 影響範圍：src/time_compass/interface/ui/scheduling/scheduling_tab.py、相關 formatter/helper
  • 時機：Phase 8
  • Gradio 可行性（Context7 驗證）：
  • 可透過事件回傳 gr.update(open=True) 直接控制 gr.Accordion 展開狀態。
  • gr.ChatInterface 支援 additional_outputs，可在 chat stream 回傳時同步更新 TaskList 區塊相關元件。
  • 無內建「暫時高亮動畫」API，建議先用 gr.Markdown / gr.HTML 狀態訊息（例如「TaskList 已更新」）作為第一版提示，再視需要補 CSS 動畫。
  • 最小落地方案（small change）：
  • 在 scheduling_tab.py 為 TaskList Accordion 命名（如 tasklist_acc），並納入 additional_outputs。
  • 每次拿到新的 TaskList 後，比對前次快照；若有變動則回傳 gr.update(open=True) 展開區塊。
  • 同步回傳更新提示訊息（例如「新增 2 筆、修改 1 筆」），降低使用者漏看風險。

7.8 Gradio Server 掛載 LiteLLM Proxy 與後端 LLM Config 整併

  • 現狀：Gradio 與 LiteLLM 目前為相對鬆散的佈署與設定關係，啟動與設定對齊成本高，且 backend LLM config 切換點較分散。
  • 目標狀態：在同一 server/runtime 掛載可用的 LiteLLM service entry（或統一反向代理入口），並重整 backend LLM config（llm_config.py）使路由與 fallback 規則集中可控。
  • 影響範圍：src/time_compass/domain/llm_config.py、Gradio 啟動腳本/伺服器入口、litellm_config.yaml
  • 時機：Phase 8

7.9 掛載 MCP Web Server 能力 + DraftAction 輸出規劃時間草案與網址回傳

  • 現狀：現行 server 入口與 MCP web server 能力仍有分離；DraftAction 主要著重 action 描述與 metadata，缺少「規劃時間草案 + 可跳轉網址」的前後端一體流程。
  • 目標狀態：
  • server 入口掛載原本 MCP web server 的核心功能（至少維持既有 API 能力）。
  • DraftAction 增加「規劃時間草案」輸出欄位（可供排程建議/預檢）。
  • backend 回傳可跳轉網址（URL）至前端，前端透過 additional_outputs 穩定顯示該 URL。
  • 影響範圍：src/time_compass/mcp/、src/time_compass/domain/schedule/、src/time_compass/interface/ui/scheduling/scheduling_tab.py
  • 時機：Phase 9