Time Compass 文檔索引¶
本索引文檔記錄了從 GUIDE.md 衍生出的完整參考文檔，幫助開發者快速查找所需信息。
📚 已生成的參考文檔¶
1. DSPY/ ⭐⭐⭐¶
Time Compass 核心 DSPy 模組系統完整指南。
涵蓋內容： - Orchestrator 整體調用流程（C4 架構圖） - Router 決策層 - 判斷後續 pipeline - EmotionSupport 情緒層 - 溫柔陪伴 - Summary 回顧層 - 區間回顧 - Scheduling 排程層 - 任務等級判斷與方案生成 - 兩層路由決策流程（Router + SchedulingRouter） - 完整 Signature 簽章規格目錄
重點亮點： - 四層模組協作與 InteractionContext 通訊 - L1/L2/L3 任務等級判斷流程 - Streaming Listener 設計（漸進式回應） - 所有 Signature 輸入輸出規格
子文檔： - README.md - 模組系統導覽 - C4-DIAGRAM.md - Orchestrator 調用流程與職責 - USER-DIALOG-FLOW.md - Router 與 SchedulingRouter 決策流程 - SIGNATURE-DIRECTORY.md - 完整 Signature 簽章列表
讀者對象： 系統架構、Prompt 設計、DSPy 開發
2. MCP-TOOLS-GUIDE.md ⭐¶
涵蓋 Time Compass 的 15 個 MCP 工具完整實作手冊。
涵蓋內容： - 日曆工具（5 個）：get_all_calendar_events、get_event_from_calendar、list_calendars、create_calendar_event、get_free_busy - 任務工具（4 個）：get_all_tasks、list_tasklists、get_task_from_tasklist、create_task - 整合工具（6 個）：get_moodle_events、get_time_context、launch_google_token_auth、launch_planner_studio、get_planner_studio_status、shutdown_planner_studio
核心主題： - API 呼叫決策矩陣（何時使用哪個工具） - 快取策略（TTL、大弧度判定） - Dev Mode 與時間平移邏輯 - 錯誤處理與復見策略 - Batch API 設計與效能考量
讀者對象： AI 助理開發、MCP 協定整合、API 設計學習
2. PLANNER-STUDIO-FRONTEND.md ⭐¶
零框架微前端的完整實作指南。
涵蓋內容： - 零框架設計的優勢與局限 - 核心模組分解（state、utils、contracts、view、zoom、api） - FullCalendar 6.1 配置與最佳實踐 - Shift+Wheel 物理縮放引擎的實現 - 前後端契約（Payload Schema） - 互動流程與狀態轉移 - 效能優化（DOM 批次化、快取策略） - 開發指南：新增功能案例
重點亮點： - 極速啟動（<500ms）無編譯步驟 - 衝突偵測邏輯細節 - 時間軸縮放的數學模型 - 60fps 動畫實現技巧
讀者對象： 前端開發、UI/UX 設計、Vanilla JS 學習
3. PROMPT-DESIGN-GUIDE.md ⭐⭐⭐¶
Prompt 工程的完整理論與實踐指南。
心理學基礎： - 認知負荷理論（CLT）：3-5 個選項限制 - 認知行為治療（CBT）：去災難化、行為啟動 - 葉杜定律：動機-壓力平衡 - 蔡加尼克效應：成就而非缺陷
舊版 DSPy 架構： - EmotionSupport 模組（INFJ 陪伴者） - RouterSignature（意圖識別與流程決策） - DraftPlan（方案級規劃，L1/L2/L3 分類） - DraftAction（行動級排程，≤60 分鐘） - AskQuestion（缺失資訊轉換為關鍵問題） - SummaryWriter（週回顧與成就解析）
新版 MCP 架構： - Prompt 資源的 MCP 工具化 - 與 DSPy 簽名的對應關係 - 完整流程示例（用戶說「我好累，想學編程」）
讀者對象： Prompt 工程師、AI 產品設計、心理學應用
4. INTERFACE-C4-ARCHITECTURE.md ⭐⭐¶
Gradio 應用介面架構的 C4 模型完整指南。
涵蓋內容： - C1 System Context：用戶、應用、Domain 層、外部整合的高層視圖 - C2 Container：Gradio Blocks web server 的組件分解（5 個 UI Tab、Event Handlers、Streaming Module） - C3 Components：各 Tab 詳細職責 - Chat Tab：聊天面板與事件橋接 - Scheduling Tab：兩段式排程 UI（draft 建立 → render artifacts） - Model Management Tab：模型版本檢視與重新載入 - Moodle Tab：Moodle 事件爬蟲 - Quick Test Tab：開發者快速測試介面 - Streaming Module：統一非同步 chunk 管理 - C4 Code：各 Tab 與 Streaming 的接口簽名、資料流、狀態機
重點亮點： - UI 層薄適配器模式（Tab = UI layout + event binding） - Async-first streaming 設計與 Fallback 機制 - 清晰的分層責任（Gradio ≠ Domain ≠ Integration）
讀者對象： 前端開發、UI/UX 設計、應用架構
5. STREAMING.md ⭐⭐⭐¶
非同步串流管理的深度指南與狀態機設計。
涵蓋內容： - Streaming Module 核心設計（async generator） - 三大函數：format_stream_output()、stream_main_output()、chat_fn() - 詳細狀態機（orchestrator 載入 → chunk 迭代 → 累積與格式化 → yield → sleep） - Domain Orchestrator 整合點與契約（OutputStream 接口期望） - Gradio UI 回調適配 - 環境變數配置（STREAM_DELAY） - 錯誤處理與 Fallback 機制 - CLI 測試工具與本地開發驗證
重點亮點： - 非阻塞型 UI 更新（async generator） - Field/Module 變化偵測與累積重置機制 - 完整的狀態轉移圖與例外流程
讀者對象： 後端流程設計、非同步程式設計、整合層開發
6. DDD-MODEL-ARCHITECTURE.md ⭐⭐¶
領域驅動設計多層模型完整指南。
四層架構： 1. Raw Layer（反腐層）：API 原始映射，47+ 欄位 2. Internal/Domain Layer（業務邏輯）：HTML 清洗、時區轉換 3. Read Layer（應用層）：LLM 最佳化，簡化表示 4. TOON Layer（展示層）：極致壓縮（83.7% Token 節省）
三大整合模組： - Google Calendar：datetime 物件保留，日期元件化 - Google Tasks：Eager-cast 至字串，狀態壓縮 - Moodle：HTML 清洗、時區統一、8 欄位精簡
核心設計決策： - 為何 Google 系列使用基類、Moodle 獨立演進 - 組成 vs 繼承的索引表設計 - 型別安全的 Pydantic 驗證策略 - TOON 編碼的壓縮機制（索引化、元件化、分組）
讀者對象： 後端架構、資料模型設計、型別安全
7. ERROR-HANDLING-DESIGN.md ✅¶
Rust 風格錯誤處理與 Railway-Oriented Programming
涵蓋內容： - Result 型別 vs Exception：為什麼選 Result - Railway-Oriented Programming（ROP）的核心概念 - is_err() / is_ok() / map() / flat_map() / bind() 實際應用 - Google API 認證錯誤 vs 業務邏輯錯誤的完整分類 - Batch API 層級錯誤處理策略與「部分成功」模式 - 日誌與可觀測性設計（模組路徑追蹤、三層級日誌） - 復見策略、重試邏輯、斷路器模式 - async_core 的完整錯誤流轉案例
讀者對象： 後端開發、錯誤處理架構、非同步程式設計
8. TEST-SUITE-GUIDE.md ✅¶
Capture-First TDD 測試策略與實踐
涵蓋內容： - Capture-First TDD 的理念與優點 - 三層測試架構（L0 Live / L1 Unit / L2 Integration / L3 System） - Fixture 與 Snapshot 管理策略（三層數據層級） - Mock Context 與 Dev Mode 的關係 - 常見測試片段與最佳實踐（4 個範例） - CI/CD 整合與覆蓋率目標 - 新增測試的完整檢查表（紅-綠-重構） - Pytest 執行指令與本地開發流程
重點亮點： - 快照從真實 API 直接擷取，永遠保持一致 - 無憑證開發體驗（MCP_DEV_MODE=1） - 測試執行 < 5 秒，回饋迴圈光速
讀者對象： 測試工程、TDD 實踐、QA 工程
9. ../explanation/moodle_api/README.md ✅¶
Moodle 整合的深度指南（NTUST 專用）
涵蓋內容： - NTUST Moodle API 研究結果與 Raw JSON 分析 - 雙路徑架構：
Async OIDC 登入 + Selenium 爬蟲備備的設計哲學 - 課程（Course）、作業（Assignment）、事件（Event）的三層資料模型 - 非同步爬蟲實作模式、月份並發控制、逾時管理 - 認證流程（API 路徑 vs Selenium 路徑）與密碼管理的安全考量 - 快取與更新策略（無狀態設計 + 改善方案） - 功能限制與 8 大已知問題的排除步驟 - 官方 API 升級評估（混合方案最推薦）
重點亮點： - 12 個月份資料從 12 秒（串列）下降至 3-5 秒（並發） - 完整的容錯流程：API 失敗 → Selenium 備備 → 優雅降級 - 三層 DDD 模型：Raw → Internal → Read/TOON - 帳密完全不持久化，內存一次性使用
讀者對象： 爬蟲開發、非同步程式設計、API 整合
10. OAUTH/ ✅¶
Google OAuth、Moodle 帳密驗證的完整指南
涵蓋內容： - Google OAuth 架構（Session 模式 vs File 模式） - 兩條授權路徑（Gradio UI vs MCP 工具） - Moodle 獨立認證（帳密、OIDC 進階方案） - Token 管理與工作流（自動刷新、多程序協調） - 安全邊界與常見問題診斷 - 雲端部署考慮
子文檔： - GOOGLE_OAUTH.md - Google OAuth 架構深度 - MOODLE_AUTH.md - Moodle 驗證邊界
讀者對象： 系統管理、OAuth 授權流程、認證架構
11. INTEGRATION/ ✅¶
Google Calendar、Google Tasks、Moodle 的完整整合層設計
涵蓋內容： - C4 Model（L1 系統視圖到 L4 程式碼） - 四大核心模組（google_calendar、google_tasks、moodle、common） - Batch API 協調器與非同步並行抓取 - 統一例外體系（8 種 GoogleError） - Moodle 爬蟲深度分析與雙路徑架構
子文檔： - C4_MODEL.md - 全景架構（L1-L4） - MOODLE_DEEP_DIVE.md - Moodle 專項深度
讀者對象： Integration 層開發、API 協調、架構設計
🔗 與 GUIDE.md 的對應關係¶
| GUIDE.md 章節 | 對應文檔 | 狀態 |
|---|---|---|
| DSPy 模組系統（核心架構） | DSPY/ | ✅ |
| Orchestrator 與 Pipeline | DSPY/C4-DIAGRAM.md | ✅ |
| Router 與 SchedulingRouter | DSPY/USER-DIALOG-FLOW.md | ✅ |
| Signature 簽章規格 | DSPY/SIGNATURE-DIRECTORY.md | ✅ |
| MCP Tools 實作 | MCP-TOOLS-GUIDE.md | ✅ |
| Gradio App 介面架構 | INTERFACE-C4-ARCHITECTURE.md | ✅ |
| 非同步串流管理 | STREAMING.md | ✅ |
| Planner Studio 前端 | PLANNER-STUDIO-FRONTEND.md | ✅ |
| Prompt 設計（舊/新） | PROMPT-DESIGN-GUIDE.md | ✅ |
| DDD 分層架構 | DDD-MODEL-ARCHITECTURE.md | ✅ |
| Rust 風格錯誤處理 | ERROR-HANDLING-DESIGN.md | ✅ |
| 測試套件（Unit/Live/System） | TEST-SUITE-GUIDE.md | ✅ |
| Google OAuth 架構 | OAUTH/GOOGLE_OAUTH.md | ✅ |
| Moodle 驗證與爬蟲 | OAUTH/MOODLE_AUTH.md、INTEGRATION/MOODLE_DEEP_DIVE.md | ✅ |
| Integration Layer 整合 | INTEGRATION/C4_MODEL.md | ✅ |
| Mock/Dev Mode 系統 | 未規劃 | - |
| Batch API 設計 | MCP-TOOLS-GUIDE.md (部分)、INTEGRATION/C4_MODEL.md | ✅ |
📖 閱讀路徑建議¶
🚀 快速上手（30 分鐘）¶
- 讀 GUIDE.md 的「專案一句話說明」
- 閱讀 MCP-TOOLS-GUIDE.md 的「工具分類與架構模式」
- 試運行 Planner Studio 並測試一個工具
🏗️ 架構深度理解（2 小時）¶
- DDD-MODEL-ARCHITECTURE.md：理解資料流層級
- MCP-TOOLS-GUIDE.md：15 個工具的決策矩陣
- PROMPT-DESIGN-GUIDE.md：理解心理學驅動的排程邏輯
🎨 前端開發（1.5 小時）¶
- PLANNER-STUDIO-FRONTEND.md：零框架設計原則
- 檢查 src/time_compass/mcp/ui/ 程式碼
- 試修改樣式或新增功能
🧠 Prompt 工程（1 小時）¶
- PROMPT-DESIGN-GUIDE.md：心理學基礎 + 六大模組
- 查看 src/time_compass/domain/ 實際 Prompt 內容
- 觀察 src/time_compass/mcp/prompts/ 新版 MCP 資源
🔧 後端開發（2 小時）¶
- DDD-MODEL-ARCHITECTURE.md：型別安全與分層
- ERROR-HANDLING-DESIGN.md（待生成）：錯誤處理策略
- 檢查 src/time_compass/integrations/ 實作
🧪 測試與驗證（1 小時）¶
- TEST-SUITE-GUIDE.md（待生成）：TDD 策略
- tests/ 目錄結構與 Fixture 管理
- 執行現有測試套件
🎓 完整學習（8 小時）¶
按上述順序完整閱讀所有文檔，並搭配程式碼查閱。
💡 使用技巧¶
如何輔助 AI 導遊¶
在 GUIDE.md 附近提問時，告訴 AI：
「請根據 docs/reference/ 中的完整文檔，
幫我解釋 [特定概念] 並列舉程式碼範例。」
AI 可以交叉參照多份文檔，提供更完整的上下文。
搜尋特定概念¶
使用檔案中的「##」標題快速定位：
# 查找所有文檔中的「縮放」
grep -n "縮放\|Zoom" docs/reference/*.md
# 查找「快取策略」
grep -n "快取\|Cache" docs/reference/*.md
📊 文檔統計¶
| 文檔 | 行數 | 重點數量 | 程式碼範例 | 難度 |
|---|---|---|---|---|
| MCP-TOOLS-GUIDE | 320 | 15 工具 + 5 分類 | 10+ | ⭐⭐ |
| INTERFACE-C4-ARCHITECTURE | 280 | 4 層 + 6 Tab + Streaming | 8+ | ⭐⭐ |
| STREAMING | 320 | 3 函數 + 狀態機 + 錯誤處理 | 6+ | ⭐⭐⭐ |
| PLANNER-STUDIO-FRONTEND | 280 | 6 模組 + 8 最佳實踐 | 15+ | ⭐⭐⭐ |
| PROMPT-DESIGN-GUIDE | 250 | 6 模組 + 4 心理學理論 | 8+ | ⭐⭐⭐ |
| DDD-MODEL-ARCHITECTURE | 380 | 4 層 + 3 整合 + 設計決策 | 12+ | ⭐⭐⭐⭐ |
| ERROR-HANDLING-DESIGN | 380 | ROP + 9 層錯誤分類 + Retry | 15+ | ⭐⭐⭐⭐ |
| TEST-SUITE-GUIDE | 340 | 4 層測試 + Capture-First | 12+ | ⭐⭐⭐ |
| OAUTH README | 140 | 3 認證系統 + 工作流 | 5+ | ⭐⭐ |
| OAUTH/GOOGLE_OAUTH | 320 | 2 路徑 + 安全邊界 | 8+ | ⭐⭐ |
| OAUTH/MOODLE_AUTH | 160 | Moodle 帳密 + OIDC | 4+ | ⭐ |
| INTEGRATION/C4_MODEL | 680 | 4 層 + 3 模組 + 決策 | 10+ | ⭐⭐⭐⭐ |
| INTEGRATION/MOODLE_DEEP_DIVE | 350 | 雙路徑 + 3 層模型 + 8 問題 | 14+ | ⭐⭐⭐⭐ |
| 總計 | 4,890+ | 145+ | 127+ | - |
📝 如何貢獻新文檔¶
- 選定主題：從 GUIDE.md 「可以觀摩的部分」中挑選未涵蓋的領域
- 命名規範：
[UPPERCASE-WITH-DASH].md（如CACHE-STRATEGY.md） -
結構模板：
# [標題] ## 簡介 ## 核心概念 ## 實現細節 ## 最佳實踐 ## 常見問題 -
質量檢查：
- [ ] 包含原始程式碼位置引用
- [ ] 附加 1-2 個實務例
- [ ] 包含「為什麼」而非只有「是什麼」
- [ ] 與既有文檔交叉參照
🔄 更新頻率¶
| 文檔 | 最後更新 | 更新頻率 |
|---|---|---|
| MCP-TOOLS-GUIDE | 2026-03-02 | 新工具時更新 |
| INTERFACE-C4-ARCHITECTURE | 2026-03-02 | 新 Tab 或架構調整時 |
| STREAMING | 2026-03-02 | Streaming 邏輯變動時 |
| ERROR-HANDLING-DESIGN | 2026-03-02 | 例外設計變動時 |
| TEST-SUITE-GUIDE | 2026-03-02 | 測試架構調整時 |
| MOODLE-INTEGRATION-DEEP-DIVE | 2026-03-02 | API 變更時 |
| PLANNER-STUDIO-FRONTEND | 2026-03-02 | 前端重構時 |
| PROMPT-DESIGN-GUIDE | 2026-03-02 | Prompt 調整時 |
| DDD-MODEL-ARCHITECTURE | 2026-03-02 | 新資料源時 |
❓ 常見問題¶
Q: 我應該先讀哪份文檔？
A: 看你的背景。工程師讀 DDD，Prompt 工程師讀 PROMPT-DESIGN，前端開發讀 PLANNER-STUDIO。
Q: 文檔會同步程式碼更新嗎？
A: 當前是手動維護。重大功能變更時會更新。 最後更新於 2026-03-02 | 共 7 份完整參考文檔 Q: 能否線上協作編輯？
A: 目前存放於 git repo，歡迎 PR。
索引文檔生成於 2026-03-02 | Time Compass Reference Documentation Hub | 共 13 份完整參考文檔