開發歷程與架構演進 (Development Journey)¶

1. 典範轉移：從「笨重」到「精煉」¶

Time Compass 經歷了兩次重大的技術路徑選擇，這反映了我們對 AI 代理套件未來發展的理解。

第一階段：Standalone Web App (v1)¶

架構: Gradio + DSPy + FastAPI + SQLite。
決策背景: 為了快速產出一個具備 UI 的 Web 產品。
反思與棄用:
啟動摩擦力: 使用者需要維護一套 Python 環境只為了用一個外掛，這不符合「工具在手邊」的邏輯。
DSPy 的代價: DSPy 的優化流程消耗了驚人的 Token 成本，對實際生成的邊際效益在模型進步後逐漸遞減。

第二階段：Agentic MCP Extension (v2)¶

架構: MCP Server + Planner Studio (Vite/React) + Library-first Core。
優點: 寄生於 IDE (如 Cursor/Claude)，使用者可原地呼叫。資料流變得極致純粹，去除了冗長的對話管理邏輯。

2. 工程美學：誠實的面對¶

在開發過程中，我們建立了幾項堅不可摧的指導原則： - Capture-First: 我們拒絕憑空想像 Mock。所有測試都是從 Google/Moodle 攔截真實 JSON，這保證了系統在面對真實 API 變動時的韌性。 - FP over Classes: 大部分的業務邏輯（特別是資料清洗層）均採用函數式編程。這不僅讓 snapshots 測試變得異常簡單，也大幅減少了狀態副作用。 - 反文件驅動 (Anti-SDD): 我們停止撰寫容易過期的詳細介面文件，取而代之的是強大的型別定義與架構資料流圖。

3. 自我批判與持續改進¶

我們在開發中曾模擬了不同專家的視角來批判我們的 README 與架構。這種「紅隊思考」幫助我們識別出： - OAuth 的地獄度: 雖然實作很難，但我們堅持完成正統 OAuth 流程以保障使用者隱私。 - 技術債坦白: 我們公開在 ADR 中記錄了 async_client 的例外處理混亂，這彰顯了我們對工程品質的真實要求與後續演進的決心。