fix and build spec document

ARCHITECTURE.md

@@ -0,0 +1,502 @@
+# 系統架構
+
+本文檔詳細說明 Deep Agentic AI Tool 的系統架構、組件設計和工作流程。
+
+## 🏗️ 整體架構
+
+系統採用模組化設計，基於 LangGraph 構建，主要組件包括：
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Gradio Web UI                        │
+│              (gradio_interface.py)                      │
+└────────────────────┬────────────────────────────────────┘
+                     │
+┌────────────────────▼────────────────────────────────────┐
+│              LangGraph Agent Graph                       │
+│              (agent_graph.py)                           │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
+│  │ Planner  │→ │Research  │→ │  Tools   │            │
+│  └──────────┘  └──────────┘  └──────────┘            │
+│       │             │             │                    │
+│       └─────────────┴─────────────┘                    │
+│                    │                                    │
+│              ┌─────▼─────┐                             │
+│              │Note Taker │                             │
+│              └─────┬─────┘                             │
+│                    │                                    │
+│              ┌─────▼─────┐                             │
+│              │ Reporter  │                             │
+│              └───────────┘                             │
+└────────────────────┬────────────────────────────────────┘
+                     │
+        ┌────────────┼────────────┐
+        │            │            │
+┌───────▼───┐  ┌────▼────┐  ┌───▼────────┐
+│   Tools   │  │   RAG   │  │    LLM     │
+│           │  │ System  │  │  Utils     │
+└───────────┘  └─────────┘  └────────────┘
+```
+
+## 📁 專案結構詳解
+
+### 核心模組
+
+#### `deep_agent_rag/agents/`
+
+代理節點實現，每個節點負責特定的任務：
+
+- **`planner.py`**：任務規劃節點
+  - 分析用戶查詢
+  - 識別查詢類型（學術、股票、一般）
+  - 生成任務列表
+  - 避免不必要的工具調用
+
+- **`researcher.py`**：研究執行節點
+  - 執行研究任務
+  - 動態選擇工具
+  - 調用工具並處理結果
+  - 維護對話上下文
+
+- **`note_taker.py`**：筆記整理節點
+  - 整理工具返回結果
+  - 生成研究筆記
+  - 添加到狀態中的研究筆記列表
+
+- **`reporter.py`**：最終報告生成節點
+  - 綜合所有研究筆記
+  - 生成結構化報告
+  - 流式輸出報告內容
+
+- **`email_agent.py`**：郵件生成代理
+  - 根據提示生成郵件草稿
+  - 支援中英文
+  - 整合反思評估
+
+- **`email_reflection_agent.py`**：郵件反思代理
+  - 評估郵件質量
+  - 提供改進建議
+  - 生成改進版本
+
+- **`calendar_agent.py`**：行事曆事件生成代理
+  - 解析事件資訊（日期、時間、地點、參與者）
+  - 生成事件草稿
+  - 整合 Google Maps 驗證
+  - 整合反思評估
+
+- **`calendar_reflection_agent.py`**：行事曆反思代理
+  - 評估事件完整性
+  - 提供改進建議
+  - 生成改進版本（最多 3 輪迭代）
+
+- **`state.py`**：狀態定義
+  - `DeepAgentState`：研究代理狀態
+  - 包含查詢、消息、任務、筆記等
+
+#### `deep_agent_rag/graph/`
+
+LangGraph 圖表構建：
+
+- **`agent_graph.py`**：圖表構建與路由
+  - 定義節點之間的連接
+  - 實現條件路由邏輯
+  - 管理檢查點（checkpoint）
+
+**工作流程：**
+```
+START → Planner → Research Agent
+                    ↓
+                  Tools (if needed)
+                    ↓
+              Note Taking
+                    ↓
+              Final Report → END
+```
+
+#### `deep_agent_rag/tools/`
+
+工具定義，提供各種功能：
+
+- **`agent_tools.py`**：研究工具
+  - `query_stock_info`：股票查詢
+  - `search_web`：網路搜尋（Tavily）
+  - `query_pdf_knowledge_base`：PDF 知識庫查詢（RAG）
+
+- **`email_tool.py`**：郵件工具
+  - `send_email`：發送郵件（Gmail API）
+
+- **`calendar_tool.py`**：行事曆工具
+  - `create_calendar_event`：創建事件
+  - `update_calendar_event`：更新事件
+  - `delete_calendar_event`：刪除事件
+
+- **`googlemaps_tool.py`**：Google Maps 工具
+  - `enrich_location_info`：地點驗證與標準化
+  - 計算交通時間
+  - 建議出發時間
+
+#### `deep_agent_rag/models/`
+
+模型包裝器：
+
+- **`mlx_chat_model.py`**：MLX 模型整合
+  - 將 MLX 模型包裝為 LangChain 兼容格式
+  - 支援流式輸出
+  - 處理模型載入和推理
+
+#### `deep_agent_rag/rag/`
+
+RAG 系統：
+
+- **`rag_system.py`**：RAG 初始化和檢索
+  - PDF 載入和分塊
+  - 向量化（使用 Jina embeddings）
+  - 向量數據庫（ChromaDB）
+  - 語義搜尋
+
+#### `deep_agent_rag/ui/`
+
+用戶界面：
+
+- **`gradio_interface.py`**：Gradio Web UI
+  - 研究代理界面
+  - 郵件工具界面
+  - 行事曆工具界面
+  - 流式更新處理
+
+#### `deep_agent_rag/utils/`
+
+工具函數：
+
+- **`llm_utils.py`**：LLM 實例管理
+  - `get_llm()`：獲取 LLM 實例（自動選擇 Groq 或 MLX）
+  - `handle_groq_error()`：處理 Groq API 錯誤
+  - `is_using_local_llm()`：檢查是否使用本地模型
+  - `get_llm_type()`：獲取當前 LLM 類型
+
+#### `deep_agent_rag/config.py`
+
+系統配置：
+
+- MLX 模型配置
+- RAG 配置
+- Agent 配置
+- API 配置（Groq、Gmail、Calendar、Google Maps）
+- 外部 SSD 路徑配置
+
+## 🔄 工作流程詳解
+
+### 深度研究代理工作流程
+
+```
+1. 用戶輸入查詢
+   ↓
+2. Planner 節點
+   - 分析查詢類型
+   - 生成任務列表
+   ↓
+3. Research Agent 節點
+   - 選擇合適的工具
+   - 調用工具
+   ↓
+4. Tools 節點（如果需要）
+   - 執行工具調用
+   - 返回結果
+   ↓
+5. Research Agent 節點（繼續）
+   - 處理工具結果
+   - 決定是否需要更多工具調用
+   ↓
+6. Note Taking 節點
+   - 整理工具結果
+   - 生成研究筆記
+   ↓
+7. 檢查是否還有未完成任務
+   - 是 → 返回 Research Agent
+   - 否 → 繼續
+   ↓
+8. Final Report 節點
+   - 綜合所有筆記
+   - 生成最終報告
+   ↓
+9. 返回結果給用戶
+```
+
+### 郵件生成工作流程
+
+```
+1. 用戶輸入郵件提示和收件人
+   ↓
+2. Email Agent
+   - 生成郵件草稿（主題和正文）
+   ↓
+3. Email Reflection Agent（可選）
+   - 評估郵件質量
+   - 生成改進建議
+   - 可選生成改進版本
+   ↓
+4. 顯示結果給用戶
+   - 原始版本
+   - 反思評估結果
+   - 改進版本（如有）
+   ↓
+5. 用戶檢查和編輯
+   ↓
+6. 用戶確認發送
+   ↓
+7. Email Tool
+   - 使用 Gmail API 發送郵件
+```
+
+### 行事曆事件生成工作流程
+
+```
+1. 用戶輸入事件提示（或使用快速選擇）
+   ↓
+2. Calendar Agent
+   - 解析事件資訊（日期、時間、地點、參與者）
+   - 生成事件草稿
+   ↓
+3. Google Maps Tool（如果配置）
+   - 驗證和標準化地址
+   - 計算交通時間
+   - 建議出發時間
+   ↓
+4. Calendar Reflection Agent（最多 3 輪迭代）
+   - 第一輪：評估事件完整性
+   - 如有改進建議 → 生成改進版本
+   - 第二輪：評估改進版本
+   - 如有改進建議 → 生成改進版本
+   - 第三輪：最終評估
+   ↓
+5. 檢查缺失資訊
+   - 如有缺失（日期、時間）→ 顯示下拉選單
+   - 用戶選擇後填充
+   ↓
+6. 顯示結果給用戶
+   - 事件詳情
+   - 反思評估結果
+   - 地點驗證資訊（如有）
+   ↓
+7. 用戶檢查和編輯
+   ↓
+8. 用戶確認創建
+   ↓
+9. Calendar Tool
+   - 使用 Google Calendar API 創建事件
+```
+
+## 🔌 外部服務整合
+
+### Groq API
+
+- **用途**：快速 LLM 推理
+- **模型**：`llama-3.3-70b-versatile`
+- **配置**：`GROQ_API_KEY` 環境變數
+- **備援**：自動切換到本地 MLX 模型
+
+### Gmail API
+
+- **用途**：發送郵件
+- **認證**：OAuth2
+- **配置**：`GMAIL_CREDENTIALS_FILE`、`GMAIL_TOKEN_FILE`
+- **權限**：`gmail.send`
+
+### Google Calendar API
+
+- **用途**：管理行事曆事件
+- **認證**：OAuth2（與 Gmail 共用憑證）
+- **配置**：`CALENDAR_CREDENTIALS_FILE`、`CALENDAR_TOKEN_FILE`
+- **權限**：`calendar`
+
+### Google Maps API
+
+- **用途**：地點驗證和交通時間計算
+- **認證**：API Key
+- **配置**：`NORMAL_GOOGLE_MAPS_API_KEY`
+- **API**：Geocoding API、Directions API
+
+### Tavily API
+
+- **用途**：網路搜尋
+- **認證**：API Key
+- **配置**：`TAVILY_API_KEY`
+
+### ChromaDB
+
+- **用途**：向量數據庫（RAG）
+- **存儲**：本地文件系統
+- **配置**：自動管理
+
+## 🧩 模組化設計
+
+### 狀態管理
+
+系統使用 LangGraph 的狀態管理：
+
+- **檢查點（Checkpoint）**：保存會話狀態
+- **線程 ID**：區分不同會話
+- **狀態持久化**：使用 MemorySaver
+
+### 工具系統
+
+- **動態工具綁定**：在運行時綁定工具到 LLM
+- **工具自動發現**：通過 `get_tools_list()` 統一管理
+- **工具結果處理**：自動處理和格式化
+
+### LLM 管理
+
+- **動態切換**：運行時自動切換 LLM 後端
+- **錯誤處理**：自動處理 API 錯誤並切換
+- **統一接口**：所有節點使用相同的 LLM 接口
+
+## 🔧 開發指南
+
+### 添加新工具
+
+1. **創建工具函數**
+
+在 `deep_agent_rag/tools/` 中創建新文件或添加到現有文件：
+
+```python
+from langchain_core.tools import tool
+
+@tool
+def my_new_tool(param: str) -> str:
+    """工具描述，LLM 會看到這個描述"""
+    # 實現邏輯
+    return result
+```
+
+2. **添加到工具列表**
+
+在 `agent_tools.py` 的 `get_tools_list()` 函數中添加：
+
+```python
+def get_tools_list(rag_retriever=None):
+    tools = [
+        query_stock_info,
+        search_web,
+        query_pdf_knowledge_base,
+        my_new_tool,  # 添加新工具
+    ]
+    # ...
+```
+
+3. **代理自動使用**
+
+代理會自動發現並使用新工具，無需修改其他代碼。
+
+### 添加新代理節點
+
+1. **創建節點函數**
+
+在 `deep_agent_rag/agents/` 中創建新文件：
+
+```python
+from ..agents.state import DeepAgentState
+
+def my_new_node(state: DeepAgentState, llm=None):
+    """新節點邏輯"""
+    # 處理狀態
+    # 返回更新後的狀態
+    return {"messages": [...], ...}
+```
+
+2. **添加到圖表**
+
+在 `agent_graph.py` 的 `build_agent_graph()` 函數中：
+
+```python
+def my_node_wrapper(state):
+    llm = get_llm()
+    return my_new_node(state, llm=llm)
+
+builder.add_node("my_node", my_node_wrapper)
+builder.add_edge("previous_node", "my_node")
+```
+
+### 修改 UI
+
+編輯 `gradio_interface.py`：
+
+- **添加新界面**：創建新函數（例如：`_create_my_interface()`）
+- **添加到主界面**：在 `create_gradio_interface()` 中添加 Tab
+- **處理事件**：使用 Gradio 的事件處理機制
+
+### 配置管理
+
+所有配置在 `config.py` 中：
+
+- **添加新配置**：直接添加變數
+- **環境變數**：使用 `os.getenv()` 讀取
+- **預設值**：提供合理的預設值
+
+## 🚀 性能優化
+
+### LLM 選擇
+
+- **Groq API**：快速，適合生產環境
+- **本地 MLX**：隱私保護，適合敏感場景
+- **自動切換**：根據可用性自動選擇
+
+### 緩存策略
+
+- **模型緩存**：使用外部 SSD（如果配置）
+- **RAG 向量庫**：持久化到本地
+- **OAuth Token**：自動刷新
+
+### 並發處理
+
+- **Gradio 會話**：每個用戶獨立的 thread_id
+- **狀態隔離**：使用檢查點系統
+- **工具調用**：順序執行，避免衝突
+
+## 🔒 安全考慮
+
+1. **憑證管理**
+   - 憑證文件不應提交到版本控制
+   - 使用 `.gitignore` 排除敏感文件
+
+2. **API 金鑰**
+   - 使用環境變數存儲
+   - 不在代碼中硬編碼
+
+3. **OAuth 授權**
+   - 自動刷新 token
+   - 安全的 token 存儲
+
+4. **用戶數據**
+   - 會話狀態隔離
+   - 不持久化敏感資訊
+
+## 📊 監控與日誌
+
+- **控制台輸出**：關鍵步驟的日誌
+- **錯誤處理**：友好的錯誤訊息
+- **狀態顯示**：UI 中顯示當前狀態
+
+## 🔮 未來擴展
+
+可能的擴展方向：
+
+1. **更多工具**
+   - 文件處理工具
+   - 數據分析工具
+   - 圖像處理工具
+
+2. **更多代理**
+   - 任務管理代理
+   - 數據分析代理
+   - 內容生成代理
+
+3. **增強功能**
+   - 多語言支援
+   - 語音輸入/輸出
+   - 移動端應用
+
+4. **性能優化**
+   - 並發工具調用
+   - 更智能的緩存
+   - 模型量化優化
+

CONFIGURATION.md

@@ -0,0 +1,363 @@
+# 配置指南
+
+本文檔詳細說明 Deep Agentic AI Tool 的所有配置選項。
+
+## 📋 配置方式
+
+系統配置有兩種方式：
+
+1. **環境變數**：在 `.env` 文件中設置（推薦）
+2. **代碼配置**：在 `deep_agent_rag/config.py` 中直接修改
+
+## 🔧 環境變數配置
+
+在專案根目錄創建 `.env` 文件：
+
+```env
+# ============================================
+# LLM 配置
+# ============================================
+
+# Groq API（可選，用於快速推理）
+GROQ_API_KEY=your_groq_api_key_here
+
+# ============================================
+# 搜尋 API 配置
+# ============================================
+
+# Tavily API（可選，用於網路搜尋）
+TAVILY_API_KEY=your_tavily_api_key_here
+
+# ============================================
+# Google API 配置
+# ============================================
+
+# Gmail API 憑證文件（可選，預設：credentials.json）
+GMAIL_CREDENTIALS_FILE=credentials.json
+GMAIL_TOKEN_FILE=token.json
+
+# Calendar API 憑證文件（可選，可與 Gmail 共用）
+CALENDAR_CREDENTIALS_FILE=credentials.json
+CALENDAR_TOKEN_FILE=token.json
+
+# Google Maps API（可選，用於行事曆地點驗證）
+NORMAL_GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
+
+# 用戶常用位置（可選，用於計算交通時間）
+USER_HOME_ADDRESS=台北市信義區信義路五段7號
+USER_OFFICE_ADDRESS=台北市大安區敦化南路二段216號
+```
+
+## ⚙️ 代碼配置
+
+所有配置選項在 `deep_agent_rag/config.py` 中定義。
+
+### MLX 模型配置
+
+```python
+# MLX 模型 ID
+MLX_MODEL_ID = "mlx-community/Qwen2.5-Coder-7B-Instruct-4bit"
+
+# 最大生成 tokens
+MLX_MAX_TOKENS = 2048
+
+# 溫度參數（控制隨機性，0.0-1.0）
+MLX_TEMPERATURE = 0.7
+```
+
+**說明：**
+- `MLX_MODEL_ID`：HuggingFace 模型 ID，必須是 MLX 兼容格式
+- `MLX_MAX_TOKENS`：生成的最大 token 數，較大值會使用更多記憶體
+- `MLX_TEMPERATURE`：較低值（0.1-0.3）更確定性，較高值（0.7-1.0）更創造性
+
+### Groq API 配置
+
+```python
+# Groq API 金鑰（從環境變數讀取）
+GROQ_API_KEY = os.getenv("GROQ_API_KEY", "")
+
+# Groq 模型名稱
+GROQ_MODEL = "llama-3.3-70b-versatile"
+
+# 最大生成 tokens
+GROQ_MAX_TOKENS = 2048
+
+# 溫度參數
+GROQ_TEMPERATURE = 0.7
+
+# 是否優先使用 Groq API
+USE_GROQ_FIRST = True
+```
+
+**說明：**
+- `GROQ_API_KEY`：從環境變數讀取，如果未設置則為空字串
+- `GROQ_MODEL`：Groq 支援的模型，可選其他模型
+- `USE_GROQ_FIRST`：設為 `True` 時優先使用 Groq，否則優先使用本地模型
+
+### RAG 配置
+
+```python
+# PDF 文件路徑
+PDF_PATH = "./data/Tree_of_Thoughts.pdf"
+
+# 嵌入模型
+EMBEDDING_MODEL = "jinaai/jina-embeddings-v3"
+
+# 文本分塊大小
+CHUNK_SIZE = 1000
+
+# 分塊重疊大小
+CHUNK_OVERLAP = 200
+
+# 檢索結果數量
+RETRIEVER_K = 3
+```
+
+**說明：**
+- `PDF_PATH`：PDF 文件的相對或絕對路徑
+- `EMBEDDING_MODEL`：用於向量化的嵌入模型
+- `CHUNK_SIZE`：每個文本塊的大小（字符數）
+- `CHUNK_OVERLAP`：相鄰塊之間的重疊大小，有助於保持上下文
+- `RETRIEVER_K`：每次檢索返回的結果數量
+
+**調整建議：**
+- 較大的 `CHUNK_SIZE`：適合長文檔，但可能包含無關資訊
+- 較小的 `CHUNK_SIZE`：更精確，但可能丟失上下文
+- 較大的 `CHUNK_OVERLAP`：更好的上下文連續性，但增加存儲
+- 較大的 `RETRIEVER_K`：更多相關結果，但可能包含無關內容
+
+### Agent 配置
+
+```python
+# 最大迭代次數（整體）
+MAX_ITERATIONS = 5
+
+# 最大研究迭代次數
+MAX_RESEARCH_ITERATIONS = 20
+
+# 反思的最大迭代次數（通用）
+MAX_REFLECTION_ITERATION = 0
+```
+
+**說明：**
+- `MAX_ITERATIONS`：整個代理流程的最大迭代次數
+- `MAX_RESEARCH_ITERATIONS`：研究代理節點的最大迭代次數
+- `MAX_REFLECTION_ITERATION`：反思代理的最大迭代次數（0 表示不進行反思）
+
+**調整建議：**
+- 較大的值：允許更深入的研究，但可能耗時更長
+- 較小的值：更快完成，但可能不夠深入
+
+### Email 配置
+
+```python
+# 發件人郵箱地址
+EMAIL_SENDER = "matthuang46@gmail.com"
+
+# Gmail API 憑證文件
+GMAIL_CREDENTIALS_FILE = os.getenv("GMAIL_CREDENTIALS_FILE", "credentials_matthuang.json")
+
+# Gmail API Token 文件
+GMAIL_TOKEN_FILE = os.getenv("GMAIL_TOKEN_FILE", "token.json")
+
+# Gmail API 權限範圍
+GMAIL_SCOPES = ['https://www.googleapis.com/auth/gmail.send']
+```
+
+**說明：**
+- `EMAIL_SENDER`：發送郵件的 Gmail 地址
+- `GMAIL_CREDENTIALS_FILE`：OAuth2 憑證文件路徑
+- `GMAIL_TOKEN_FILE`：Token 存儲文件路徑
+- `GMAIL_SCOPES`：API 權限範圍，目前只請求發送郵件權限
+
+**擴展權限：**
+如果需要讀取郵件等功能，可以添加更多 scope：
+```python
+GMAIL_SCOPES = [
+    'https://www.googleapis.com/auth/gmail.send',
+    'https://www.googleapis.com/auth/gmail.readonly',
+]
+```
+
+### Calendar 配置
+
+```python
+# Calendar API 憑證文件（可與 Gmail 共用）
+CALENDAR_CREDENTIALS_FILE = os.getenv("CALENDAR_CREDENTIALS_FILE", "credentials_matthuang.json")
+
+# Calendar API Token 文件（可與 Gmail 共用）
+CALENDAR_TOKEN_FILE = os.getenv("CALENDAR_TOKEN_FILE", "token.json")
+
+# Calendar API 權限範圍
+CALENDAR_SCOPES = ['https://www.googleapis.com/auth/calendar']
+```
+
+**說明：**
+- Calendar API 可以與 Gmail API 共用相同的 OAuth2 憑證
+- `CALENDAR_SCOPES`：目前請求完整的 Calendar 權限
+
+### Google Maps 配置
+
+```python
+# Google Maps API 金鑰
+NORMAL_GOOGLE_MAPS_API_KEY = os.getenv("NORMAL_GOOGLE_MAPS_API_KEY", "")
+
+# 用戶常用位置（用於計算交通時間）
+USER_HOME_ADDRESS = os.getenv("USER_HOME_ADDRESS", "")
+USER_OFFICE_ADDRESS = os.getenv("USER_OFFICE_ADDRESS", "")
+```
+
+**說明：**
+- `NORMAL_GOOGLE_MAPS_API_KEY`：Google Maps API 金鑰（必需，用於地點驗證）
+- `USER_HOME_ADDRESS`：家庭地址（可選，用於計算交通時間）
+- `USER_OFFICE_ADDRESS`：辦公室地址（可選，優先使用）
+
+**地址格式：**
+- 支援多種格式：完整地址、地標名稱、座標等
+- 例如：`"台北市信義區信義路五段7號"`、`"台北101"`、`"25.0330,121.5654"`
+
+### 外部 SSD 配置
+
+```python
+# 外接 SSD 路徑
+EXTERNAL_SSD_PATH = "/Volumes/T7_SSD"
+
+# HuggingFace 緩存目錄
+HF_CACHE_DIR = os.path.join(EXTERNAL_SSD_PATH, "huggingface_cache")
+```
+
+**說明：**
+- 如果配置了外部 SSD，模型會緩存到外部 SSD
+- 節省本地磁碟空間
+- 如果找不到外部 SSD，會使用預設緩存目錄
+
+**修改路徑：**
+根據您的實際 SSD 掛載路徑修改 `EXTERNAL_SSD_PATH`。
+
+## 🔍 配置驗證
+
+### 檢查配置是否正確
+
+1. **檢查環境變數**
+
+```bash
+# 在專案根目錄
+cat .env
+```
+
+2. **檢查 Python 配置**
+
+```python
+# 在 Python 中
+from deep_agent_rag.config import *
+print(f"Groq API Key: {'已設置' if GROQ_API_KEY else '未設置'}")
+print(f"MLX Model: {MLX_MODEL_ID}")
+print(f"PDF Path: {PDF_PATH}")
+```
+
+3. **測試 API 連接**
+
+- **Groq API**：運行研究代理，查看是否使用 Groq
+- **Gmail API**：嘗試發送測試郵件
+- **Calendar API**：嘗試創建測試事件
+- **Google Maps API**：創建包含地點的事件，查看是否驗證成功
+
+## 🎯 配置最佳實踐
+
+### 開發環境
+
+```env
+# 使用本地 MLX 模型（無需 API 金鑰）
+# 不設置 GROQ_API_KEY
+
+# 可選：設置 Tavily API 用於網路搜尋
+TAVILY_API_KEY=your_key_here
+```
+
+### 生產環境
+
+```env
+# 使用 Groq API（更快）
+GROQ_API_KEY=your_key_here
+
+# 設置所有必要的 API 金鑰
+TAVILY_API_KEY=your_key_here
+NORMAL_GOOGLE_MAPS_API_KEY=your_key_here
+
+# 設置常用位置
+USER_OFFICE_ADDRESS=your_office_address
+```
+
+### 隱私敏感環境
+
+```env
+# 不使用任何外部 API
+# 只使用本地 MLX 模型
+
+# 不設置任何 API 金鑰
+```
+
+## ⚠️ 常見配置問題
+
+### 1. API 金鑰未設置
+
+**問題**：功能無法使用（例如：網路搜尋、地點驗證）
+
+**解決**：
+- 檢查 `.env` 文件是否存在
+- 檢查環境變數名稱是否正確
+- 確認 API 金鑰是否有效
+
+### 2. 憑證文件找不到
+
+**問題**：Gmail/Calendar API 無法使用
+
+**解決**：
+- 確認 `credentials.json` 在專案根目錄
+- 檢查 `GMAIL_CREDENTIALS_FILE` 路徑是否正確
+- 參考 [Gmail API 設置指南](GMAIL_API_SETUP.md)
+
+### 3. 模型緩存問題
+
+**問題**：模型載入失敗或緩存損壞
+
+**解決**：
+- 刪除緩存目錄重新下載
+- 檢查磁碟空間是否足夠
+- 如果使用外部 SSD，確認 SSD 已正確掛載
+
+### 4. PDF 文件找不到
+
+**問題**：RAG 系統無法載入 PDF
+
+**解決**：
+- 確認 PDF 文件存在於指定路徑
+- 檢查 `PDF_PATH` 是否為相對路徑（相對於專案根目錄）
+- 或使用絕對路徑
+
+## 📝 配置備份
+
+建議將配置備份：
+
+1. **環境變數備份**：保存 `.env` 文件（但不要提交敏感資訊）
+2. **代碼配置備份**：`config.py` 可以提交到版本控制
+3. **憑證備份**：安全存儲 `credentials.json`（不要提交到版本控制）
+
+## 🔐 安全建議
+
+1. **不要提交敏感資訊**
+   - 將 `.env` 添加到 `.gitignore`
+   - 將 `credentials.json` 和 `token.json` 添加到 `.gitignore`
+
+2. **使用環境變數**
+   - 優先使用環境變數而非硬編碼
+   - 在生產環境使用密鑰管理服務
+
+3. **限制 API 權限**
+   - 在 Google Cloud Console 中限制 API Key 使用
+   - 只請求必要的 OAuth scope
+
+4. **定期輪換金鑰**
+   - 定期更新 API 金鑰
+   - 監控 API 使用情況
+

FEATURES.md

@@ -0,0 +1,409 @@
+# 功能詳述
+
+本文檔詳細說明 Deep Agentic AI Tool 的所有功能和使用範例。
+
+## 🔍 深度研究代理 (Deep Research Agent)
+
+### 功能概述
+
+深度研究代理是一個智能多步驟研究系統，能夠自動分解複雜問題、選擇合適的工具、執行研究任務，並生成完整的研究報告。
+
+### 核心特性
+
+1. **智能任務分解**
+   - 自動識別查詢類型（學術、股票相關、一般查詢）
+   - 根據查詢類型生成適當的任務列表
+   - 避免不必要的工具調用
+
+2. **動態工具選擇**
+   - 股票查詢工具（yfinance）
+   - 網路搜尋工具（Tavily API）
+   - PDF 知識庫工具（RAG 系統）
+
+3. **即時進度追蹤**
+   - 顯示當前執行的節點
+   - 任務完成進度
+   - 研究筆記即時更新
+
+4. **流式報告生成**
+   - 逐句流式顯示最終報告
+   - 支援中英文標點符號
+   - 完整的結構化報告
+
+### 使用範例
+
+#### 學術/理論問題
+
+**輸入：**
+```
+解釋 Tree of Thoughts 並深入比較它與 Chain of Thought
+```
+
+**系統處理：**
+1. 識別為學術查詢
+2. 使用 PDF 知識庫工具檢索相關內容
+3. 生成比較分析報告
+
+**輸入：**
+```
+分析 Tree of Thoughts 方法的優缺點
+```
+
+#### 股票相關問題
+
+**輸入：**
+```
+比較微軟 (MSFT) 和谷歌 (GOOGL) 在 AI 領域的表現
+```
+
+**系統處理：**
+1. 識別為股票查詢
+2. 使用股票查詢工具獲取兩家公司數據
+3. 使用網路搜尋工具獲取最新 AI 相關新聞
+4. 生成比較分析報告
+
+**輸入：**
+```
+查詢蘋果 (AAPL) 的財務狀況和近期發展
+```
+
+#### 綜合問題
+
+**輸入：**
+```
+比較微軟 (MSFT) 和谷歌 (GOOGL) 在 AI 領域，並結合 Tree of Thoughts 方法論
+```
+
+**系統處理：**
+1. 識別為綜合查詢
+2. 同時使用股票查詢、網路搜尋和 PDF 知識庫工具
+3. 生成綜合分析報告
+
+### 工作流程
+
+1. **規劃節點 (Planner)**
+   - 分析查詢並分解為研究任務
+   - 生成任務列表
+
+2. **研究代理節點 (Research Agent)**
+   - 執行研究任務
+   - 動態選擇並調用工具
+   - 維護對話上下文
+
+3. **工具節點 (Tools)**
+   - 執行工具調用
+   - 返回結果
+
+4. **筆記整理節點 (Note Taking)**
+   - 整理工具結果
+   - 添加到研究筆記
+
+5. **最終報告節點 (Final Report)**
+   - 綜合所有研究筆記
+   - 生成結構化報告
+
+## 📧 智能郵件助手 (Email Agent)
+
+### 功能概述
+
+智能郵件助手使用 AI 自動生成郵件草稿，支援 Gmail API 發送，並提供 AI 反思評估功能以改進郵件質量。
+
+### 核心特性
+
+1. **AI 自動生成**
+   - 根據簡單提示生成完整郵件
+   - 支援中英文郵件
+   - 自動生成主題和正文
+
+2. **AI 反思評估**
+   - 自動評估郵件質量
+   - 提供改進建議
+   - 可選自動改進（生成改進版本）
+
+3. **Gmail API 整合**
+   - 使用官方 API 發送，避免垃圾郵件分類
+   - OAuth2 認證，無需儲存密碼
+   - 更可靠的錯誤處理
+
+4. **可編輯草稿**
+   - 生成後可檢查和修改
+   - 確認無誤後發送
+
+### 使用範例
+
+#### 基本使用
+
+**輸入提示：**
+```
+寫一封感謝信，感謝對方在專案上的幫助
+```
+
+**收件人：**
+```
+colleague@example.com
+```
+
+**系統處理：**
+1. 生成郵件主題和正文
+2. 進行 AI 反思評估
+3. 如有改進建議，顯示評估結果
+4. 用戶可選擇使用改進版本或原始版本
+
+#### 商務郵件
+
+**輸入提示：**
+```
+邀請某人參加下週的產品發布會
+```
+
+**收件人：**
+```
+client@example.com
+```
+
+#### 進度查詢
+
+**輸入提示：**
+```
+詢問專案進度並提供更新
+```
+
+**收件人：**
+```
+team@example.com
+```
+
+### AI 反思評估
+
+系統會自動評估生成的郵件：
+
+- **完整性**：是否包含所有必要資訊
+- **語氣**：是否適合收件人和情境
+- **結構**：邏輯是否清晰
+- **專業性**：是否符合商務郵件標準
+
+如果評估發現需要改進，系統會：
+1. 顯示評估結果和改進建議
+2. 可選自動生成改進版本
+3. 用戶可選擇使用改進版本或原始版本
+
+### 設置要求
+
+- Gmail API 憑證（參考 [Gmail API 設置](GMAIL_API_SETUP.md)）
+- OAuth2 授權（首次使用時自動觸發）
+
+## 📅 智能行事曆管理 (Calendar Agent)
+
+### 功能概述
+
+智能行事曆管理使用 AI 自動生成行事曆事件，整合 Google Calendar API 和 Google Maps，提供地點驗證、交通時間計算等功能。
+
+### 核心特性
+
+1. **AI 自動生成事件**
+   - 根據完整提示生成事件
+   - 自動解析日期、時間、地點、參與者
+   - 支援相對日期（今天、明天、後天）
+
+2. **AI 反思評估與改進**
+   - 最多 3 輪迭代反思
+   - 自動評估事件完整性
+   - 自動生成改進版本
+
+3. **Google Maps 整合**
+   - 自動驗證和標準化地址
+   - 計算交通時間
+   - 建議出發��間
+
+4. **智能缺失資訊處理**
+   - 自動檢測缺失資訊（日期、時間）
+   - 提供下拉選單供選擇
+   - 確認後自動填充
+
+5. **快速選擇按鈕**
+   - 團隊會議
+   - 客戶拜訪
+   - 午餐會議
+   - 一對一會議
+   - 項目討論
+   - 培訓/學習
+   - 社交活動
+   - 自定義輸入
+
+### 使用範例
+
+#### 基本使用
+
+**輸入提示：**
+```
+明天下午2點團隊會議，討論專案進度，地點在會議室A
+```
+
+**系統處理：**
+1. 解析日期：明天
+2. 解析時間：下午2點
+3. 解析事件：團隊會議
+4. 解析地點：會議室A
+5. 生成事件草稿
+6. 進行 AI 反思評估
+7. 驗證地點（如果配置了 Google Maps API）
+8. 計算交通時間（如果配置了常用位置）
+
+#### 包含參與者
+
+**輸入提示：**
+```
+後天上午10點客戶拜訪，地點在台北101，參與者包括 john@example.com 和 mary@example.com
+```
+
+**系統處理：**
+1. 解析所有資訊
+2. 驗證並標準化地址（台北101 → 完整地址）
+3. 計算從辦公室到台北101的交通時間
+4. 建議出發時間（提前10分鐘到達）
+
+#### 使用快速選擇
+
+1. 點擊快速選擇按鈕（例如："📋 團隊會議"）
+2. 系統自動填充提示
+3. 點擊「生成事件草稿」
+4. 如有缺失資訊，系統會提示選擇
+
+### AI 反思評估
+
+系統會進行最多 3 輪迭代反思：
+
+1. **第一輪評估**
+   - 評估事件完整性
+   - 檢查是否有缺失資訊
+   - 評估事件描述是否清晰
+
+2. **改進生成**
+   - 如有改進建議，自動生成改進版本
+   - 改進版本會再次評估
+
+3. **迭代優化**
+   - 重複評估和改進過程
+   - 直到 AI 認為滿意或達到最大迭代次數
+
+### Google Maps 整合
+
+#### 地點驗證
+
+**輸入：**
+```
+明天下午2點會議，地點在台北101
+```
+
+**系統處理：**
+1. 驗證地址是否存在
+2. 標準化為完整格式：`台北市信義區市府路45號（台北101）`
+3. 獲取準確座標
+
+#### 交通時間計算
+
+**前提條件：**
+- 配置了 `USER_HOME_ADDRESS` 或 `USER_OFFICE_ADDRESS`
+- 配置了 `NORMAL_GOOGLE_MAPS_API_KEY`
+
+**系統處理：**
+1. 計算從預設位置到事件地點的距離
+2. 根據事件時間計算交通時間
+3. 建議出發時間（提前10分鐘到達）
+
+**顯示結果：**
+```
+✅ 地址已驗證：台北市信義區市府路45號（台北101）
+📍 從您的預設位置出發，預計需要 25 分鐘（12.5 公里）
+⏰ 建議出發時間：2026-01-26 13:35
+```
+
+### 事件管理功能
+
+- **創建事件**：生成並創建新事件
+- **更新事件**：修改現有事件（需要事件 ID）
+- **刪除事件**：刪除現有事件（需要事件 ID）
+
+### 設置要求
+
+- Google Calendar API 憑證（與 Gmail API 共用）
+- Google Maps API 金鑰（可選，用於地點驗證）
+- 用戶常用位置（可選，用於交通時間計算）
+
+詳細設置請參考：
+- [Gmail API 設置](GMAIL_API_SETUP.md)（Calendar API 設置相同）
+- [Google Maps 整合說明](GOOGLE_MAPS_INTEGRATION.md)
+
+## 📊 研究工具集
+
+### 股票查詢工具
+
+**功能：**
+- 即時股票數據檢索
+- 公司財務數據和營運狀況
+- 市值、P/E 比、營收成長
+- 業務摘要和分析
+
+**使用範例：**
+- 查詢單一股票：`查詢蘋果 (AAPL) 的財務狀況`
+- 比較多個股票：`比較微軟 (MSFT) 和谷歌 (GOOGL)`
+
+### 網路搜尋工具
+
+**功能：**
+- 使用 Tavily Search API
+- 獲取最新新聞和資訊
+- 支援多語言搜尋
+
+**使用範例：**
+- 搜尋最新資訊：`搜尋 AI 領域的最新發展`
+- 獲取新聞：`查找關於 ChatGPT 的最新新聞`
+
+### PDF 知識庫工具
+
+**功能：**
+- 向量化語義搜尋
+- 目前包含 "Tree of Thoughts" 研究論文
+- 可擴展到其他 PDF 文檔
+
+**使用範例：**
+- 查詢論文內容：`解釋 Tree of Thoughts 方法`
+- 比較概念：`比較 Tree of Thoughts 和 Chain of Thought`
+
+## 🔄 LLM 配置
+
+系統支援多種 LLM 後端，並自動切換：
+
+1. **主要：Groq API**（快速，需要 API 金鑰）
+   - 模型：`llama-3.3-70b-versatile`
+   - 如果設置了 `GROQ_API_KEY` 則自動使用
+
+2. **備援：本地 MLX 模型**（保護隱私，無需 API 金鑰）
+   - 模型：`mlx-community/Qwen2.5-Coder-7B-Instruct-4bit`
+   - 當 Groq API 不可用或額度用完時自動使用
+
+系統會根據可用性自動切換後端。
+
+## 💡 使用技巧
+
+1. **研究查詢**
+   - 使用具體的問題描述
+   - 包含股票代碼（如果查詢股票）
+   - 明確指出需要比較的內容
+
+2. **郵件生成**
+   - 提供上下文資訊（例如：專案名稱、時間）
+   - 指定郵件語氣（正式、友好等）
+   - 檢查 AI 反思評估結果
+
+3. **行事曆事件**
+   - 使用完整提示（包含所有必要資訊）
+   - 使用快速選擇按鈕快速開始
+   - 檢查地點驗證和交通時間資訊
+   - 如有缺失資訊，使用系統提供的下拉選單
+
+4. **性能優化**
+   - 使用 Groq API 獲得更快結果
+   - 本地 MLX 模型適合隱私敏感場景
+   - 系統會自動選擇最佳後端
+

GMAIL_API_SETUP.md

@@ -1,5 +1,7 @@
 # Gmail API 設置指南
 
+> 📚 **相關文檔**：[主 README](README.md) | [功能詳述](FEATURES.md#智能郵件助手) | [配置指南](CONFIGURATION.md#email-配置)
+
 本系統使用 Gmail API 發送郵件，相比傳統 SMTP 方式，可以避免被歸類為垃圾郵件的風險。
 
 ## 📋 設置步驟
@@ -101,6 +103,30 @@ GMAIL_TOKEN_FILE=token.json
 4. 點擊「📧 生成並發送郵件」
 5. 如果設置正確，郵件會成功發送並顯示 Message ID
 
+## 📅 Google Calendar API 設置
+
+**注意**：Google Calendar API 與 Gmail API 共用相同的 OAuth2 憑證。
+
+### 啟用 Calendar API
+
+1. 在 Google Cloud Console 中，進入「API 和服務」>「資料庫」
+2. 搜尋「Google Calendar API」
+3. 點擊「Google Calendar API」並點擊「啟用」
+
+### 共用憑證
+
+- Calendar API 使用與 Gmail API 相同的 `credentials.json` 文件
+- 首次使用 Calendar 功能時，系統會自動請求 Calendar 權限
+- Token 會存儲在同一個 `token.json` 文件中
+
+### 權限範圍
+
+系統會自動請求以下權限：
+- `gmail.send`：發送郵件
+- `calendar`：完整的 Calendar 權限（創建、更新、刪除事件）
+
+**詳細使用說明請參考**：[功能詳述 - 智能行事曆管理](FEATURES.md#智能行事曆管理)
+
 ## 🆚 Gmail API vs SMTP
 
 使用 Gmail API 的優勢：

GOOGLE_MAPS_INTEGRATION.md

@@ -1,5 +1,7 @@
 # Google Maps API 整合說明
 
+> 📚 **相關文檔**：[主 README](README.md) | [功能詳述](FEATURES.md#智能行事曆管理) | [配置指南](CONFIGURATION.md#google-maps-配置)
+
 本系統已整合 Google Maps API，為行事曆事件提供智能地點驗證、標準化和交通時間計算功能。
 
 ## 🎯 功能特色

README.md

@@ -1,337 +1,301 @@
 # Deep Agentic AI Tool
 
-A comprehensive deep research agent system with RAG (Retrieval-Augmented Generation) capabilities, built with LangGraph and featuring local MLX model support. This system provides intelligent research assistance with stock queries, web search, PDF knowledge base retrieval, and email generation capabilities.
+一個功能完整的深度研究代理系統，整合 RAG（檢索增強生成）、本地 MLX 模型支援，以及多種智能工具。系統基於 LangGraph 構建，提供智能研究、郵件生成、行事曆管理等全方位 AI 助手功能。
 
-## 🚀 Features
+## 🚀 核心功能
 
-### Core Capabilities
+### 🔍 深度研究代理 (Deep Research Agent)
+- 智能多步驟研究規劃與執行
+- 自動任務分解（學術、股票、一般查詢）
+- 動態工具選擇（股票查詢、網路搜尋、PDF 知識庫）
+- 即時進度追蹤與筆記整理
+- 完整研究報告生成
 
-- **🔍 Deep Research Agent**: Intelligent multi-step research planning and execution
-  - Automatic task decomposition based on query type
-  - Smart tool selection (stocks, web search, PDF knowledge base)
-  - Real-time progress tracking and note-taking
-  - Comprehensive final report generation
+**詳細說明請參考：[功能詳述](FEATURES.md#深度研究代理)**
 
-- **📊 Stock Information Query**: Real-time stock data retrieval
-  - Company financial data and operational status
-  - Market cap, P/E ratio, revenue growth
-  - Business summaries and analysis
+### 📧 智能郵件助手 (Email Agent)
+- AI 自動生成郵件草稿
+- Gmail API 整合（避免垃圾郵件分類）
+- 支援中英文郵件
+- AI 反思評估與自動改進
+- 可編輯草稿後發送
 
-- **🌐 Web Search**: Internet search for latest news and information
-  - Powered by Tavily Search API
-  - Retrieves up-to-date information from the web
+**詳細說明請參考：[功能詳述](FEATURES.md#智能郵件助手)**  
+**設置指南請參考：[Gmail API 設置](GMAIL_API_SETUP.md)**
 
-- **📚 PDF Knowledge Base**: RAG system for document retrieval
-  - Vector-based semantic search
-  - Currently includes "Tree of Thoughts" research paper
-  - Extensible to other PDF documents
+### 📅 智能行事曆管理 (Calendar Agent)
+- AI 自動生成行事曆事件
+- Google Calendar API 整合
+- AI 反思評估與自動改進（最多 3 輪迭代）
+- Google Maps 地點驗證與標準化
+- 自動計算交通時間與建議出發時間
+- 支援創建、更新、刪除事件
 
-- **📧 Email Agent**: AI-powered email generation and sending
-  - Automatic email draft generation from prompts
-  - Gmail API integration (avoids spam classification)
-  - Support for both Chinese and English emails
-  - Editable drafts before sending
+**詳細說明請參考：[功能詳述](FEATURES.md#智能行事曆管理)**  
+**Google Maps 整合說明請參考：[Google Maps 整合](GOOGLE_MAPS_INTEGRATION.md)**
 
-### Technical Highlights
+### 📊 研究工具集
+- **股票查詢**：即時股票數據（財務狀況、市值、P/E 比等）
+- **網路搜尋**：Tavily API 整合，獲取最新資訊
+- **PDF 知識庫**：RAG 系統，向量化語義搜尋（目前包含 "Tree of Thoughts" 論文）
 
-- **Local MLX Models**: Privacy-preserving local inference using Qwen2.5-Coder-7B-Instruct-4bit
-- **Groq API Fallback**: Automatic fallback to Groq API when local model is unavailable
-- **LangGraph Orchestration**: Sophisticated agent workflow management
-- **Gradio Web Interface**: Modern, user-friendly web UI with real-time updates
-- **Modular Architecture**: Clean, extensible codebase structure
+## 🛠️ 技術特色
 
-## 📋 Prerequisites
+- **本地 MLX 模型**：使用 Qwen2.5-Coder-7B-Instruct-4bit，保護隱私，無需 API 金鑰
+- **Groq API 備援**：自動切換到 Groq API（當本地模型不可用或額度用完時）
+- **LangGraph 編排**：複雜的代理工作流程管理
+- **Gradio Web 界面**：現代化、用戶友好的 Web UI，即時更新
+- **模組化架構**：清晰、可擴展的代碼結構
+- **外部 SSD 支援**：可配置模型緩存到外部 SSD（節省本地空間）
+
+**詳細架構說明請參考：[系統架構](ARCHITECTURE.md)**
+
+## 📋 系統需求
 
 - Python >= 3.13
-- macOS (for MLX support) or Linux
-- Google Cloud account (for Gmail API - optional, only needed for email features)
-- Tavily API key (for web search - optional, can be configured in `.env`)
-
-## 🛠️ Installation
-
-1. **Clone the repository**:
-   ```bash
-   git clone <repository-url>
-   cd Deep_Agentic_AI_Tool
-   ```
-
-2. **Install dependencies**:
-   ```bash
-   # Using uv (recommended)
-   uv sync
-   
-   # Or using pip
-   pip install -e .
-   ```
-
-3. **Set up environment variables** (create a `.env` file in the root directory):
-   ```env
-   # Optional: Groq API (for faster inference)
-   GROQ_API_KEY=your_groq_api_key_here
-   
-   # Optional: Tavily API (for web search)
-   TAVILY_API_KEY=your_tavily_api_key_here
-   
-   # Optional: Gmail API credentials
-   GMAIL_CREDENTIALS_FILE=credentials.json
-   GMAIL_TOKEN_FILE=token.json
-   ```
-
-4. **Prepare PDF data** (optional):
-   - Place your PDF files in the `data/` directory
-   - The system currently uses `data/Tree_of_Thoughts.pdf` by default
-   - You can modify the path in `deep_agent_rag/config.py`
-
-5. **Set up Gmail API** (optional, for email features):
-   - Follow the instructions in `GMAIL_API_SETUP.md`
-   - Download OAuth2 credentials and save as `credentials.json` in the root directory
-
-## 🎯 Usage
-
-### Starting the Application
-
-Run the main application:
+- macOS（MLX 支援）或 Linux
+- Google Cloud 帳號（用於 Gmail/Calendar API - 可選，僅郵件/行事曆功能需要）
+- Tavily API 金鑰（用於網路搜尋 - 可選，可在 `.env` 中配置）
+- Google Maps API 金鑰（用於行事曆地點驗證 - 可選，可在 `.env` 中配置）
+
+## 🛠️ 快速開始
+
+### 1. 安裝依賴
 
 ```bash
-python Deep_Agent_Gradio_RAG_localLLM_main.py
+# 使用 uv（推薦）
+uv sync
+
+# 或使用 pip
+pip install -e .
 ```
 
-The Gradio interface will be available at:
-- Local: `http://localhost:7860`
-- Network: `http://0.0.0.0:7860`
+### 2. 環境變數配置
 
-### Using the Deep Research Agent
+在專案根目錄創建 `.env` 文件：
 
-1. Navigate to the **"🔍 Deep Research Agent"** tab
-2. Enter your research question in the input box
-3. Click **"🔍 開始研究"** (Start Research)
-4. Watch real-time updates:
-   - **Current Status**: Shows which agent node is executing
-   - **Task List**: Displays the research plan and progress
-   - **Research Notes**: Real-time notes from the research process
-   - **Final Report**: Comprehensive research report (streamed sentence by sentence)
+```env
+# 可選：Groq API（用於更快的推理）
+GROQ_API_KEY=your_groq_api_key_here
 
-#### Example Queries
+# 可選：Tavily API（用於網路搜尋）
+TAVILY_API_KEY=your_tavily_api_key_here
 
-- **Academic/Theory Questions**:
-  - "Explain Tree of Thoughts and deeply compare it with Chain of Thought"
-  - "Analyze the advantages and disadvantages of the Tree of Thoughts method"
+# 可選：Google Maps API（用於行事曆地點驗證）
+NORMAL_GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
 
-- **Stock-Related Questions**:
-  - "Compare Microsoft (MSFT) and Google (GOOGL) in the AI field"
-  - "Query Apple (AAPL) financial status and recent developments"
+# 可選：用戶常用位置（用於計算交通時間）
+USER_HOME_ADDRESS=台北市信義區信義路五段7號
+USER_OFFICE_ADDRESS=台北市大安區敦化南路二段216號
 
-- **Combined Questions**:
-  - "Compare Microsoft (MSFT) and Google (GOOGL) in AI, incorporating Tree of Thoughts methodology"
+# 可選：Gmail/Calendar API 憑證文件路徑
+GMAIL_CREDENTIALS_FILE=credentials.json
+GMAIL_TOKEN_FILE=token.json
+CALENDAR_CREDENTIALS_FILE=credentials.json
+CALENDAR_TOKEN_FILE=token.json
+```
 
-### Using the Email Tool
+**詳細配置說明請參考：[配置指南](CONFIGURATION.md)**
 
-1. Navigate to the **"📧 Email Tool"** tab
-2. Enter an email prompt (e.g., "Write a thank you letter")
-3. Enter the recipient's email address
-4. Click **"📝 生成郵件草稿"** (Generate Email Draft)
-5. Review and edit the generated subject and body
-6. Click **"📧 發送郵件"** (Send Email) to send
+### 3. 準備數據（可選）
 
-#### Example Email Prompts
+- 將 PDF 文件放在 `data/` 目錄
+- 系統預設使用 `data/Tree_of_Thoughts.pdf`
+- 可在 `deep_agent_rag/config.py` 中修改路徑
 
-- "Write a thank you letter for help with the project"
-- "Invite someone to next week's product launch"
-- "Ask about project progress and provide updates"
+### 4. 設置 API（可選）
 
-## 🏗️ Architecture
+- **Gmail API**：參考 [Gmail API 設置指南](GMAIL_API_SETUP.md)
+- **Google Calendar API**：與 Gmail API 共用相同的 OAuth2 憑證
+- **Google Maps API**：參考 [Google Maps 整合說明](GOOGLE_MAPS_INTEGRATION.md)
 
-### Project Structure
+### 5. 啟動應用
 
+```bash
+python Deep_Agent_Gradio_RAG_localLLM_main.py
 ```
-Deep_Agentic_AI_Tool/
-├── deep_agent_rag/          # Main package
-│   ├── agents/              # Agent nodes
-│   │   ├── planner.py      # Task planning node
-│   │   ├── researcher.py   # Research execution node
-│   │   ├── note_taker.py   # Note-taking node
-│   │   ├── reporter.py     # Final report generation
-│   │   ├── email_agent.py  # Email generation agent
-│   │   └── state.py        # State definition
-│   ├── graph/              # LangGraph orchestration
-│   │   └── agent_graph.py  # Graph construction and routing
-│   ├── models/             # Model wrappers
-│   │   └── mlx_chat_model.py  # MLX model integration
-│   ├── rag/                # RAG system
-│   │   └── rag_system.py   # PDF loading and retrieval
-│   ├── tools/              # Tool definitions
-│   │   ├── agent_tools.py  # Stock, web search, PDF tools
-│   │   └── email_tool.py   # Email sending tool
-│   ├── ui/                 # User interface
-│   │   └── gradio_interface.py  # Gradio web UI
-│   ├── utils/              # Utilities
-│   │   └── llm_utils.py    # LLM instance management
-│   └── config.py           # Configuration
-├── data/                   # Data directory
-│   └── Tree_of_Thoughts.pdf
-├── Deep_Agent_Gradio_RAG_localLLM_main.py  # Main entry point
-├── main.py                 # Simple entry point
-├── pyproject.toml          # Project dependencies
-└── README.md               # This file
-```
-
-### Agent Workflow
-
-The system uses a multi-agent workflow orchestrated by LangGraph:
 
-1. **Planner Node**: Analyzes the query and decomposes it into research tasks
-   - Detects query type (academic, stock-related, general)
-   - Generates appropriate task list based on query type
-   - Avoids unnecessary tool calls
+Gradio 界面將在以下地址可用：
+- 本地：`http://localhost:7860`
+- 網路：`http://0.0.0.0:7860`
 
-2. **Research Agent Node**: Executes research tasks
-   - Dynamically selects and calls appropriate tools
-   - Can call multiple tools in sequence
-   - Maintains conversation context
+## 🎯 使用指南
 
-3. **Tool Node**: Executes tool calls
-   - Stock query tool
-   - Web search tool
-   - PDF knowledge base tool
+### 深度研究代理
 
-4. **Note-Taking Node**: Consolidates research findings
-   - Summarizes tool results
-   - Adds to research notes
+1. 切換到 **"🔍 Deep Research Agent"** 標籤
+2. 輸入研究問題
+3. 點擊 **"🔍 開始研究"**
+4. 查看即時更新：
+   - **當前狀態**：顯示正在執行的節點
+   - **任務列表**：顯示研究計劃與進度
+   - **研究筆記**：即時研究過程筆記
+   - **最終報告**：完整研究報告（逐句流式顯示）
 
-5. **Final Report Node**: Generates comprehensive report
-   - Synthesizes all research notes
-   - Creates structured final report
+**使用範例請參考：[功能詳述](FEATURES.md#使用範例)**
 
-### LLM Configuration
+### 郵件工具
 
-The system supports multiple LLM backends with automatic fallback:
+1. 切換到 **"📧 Email Tool"** 標籤
+2. 輸入郵件提示（例如："寫一封感謝信"）
+3. 輸入收件人郵箱
+4. 點擊 **"📝 生成郵件草稿"**
+5. 查看 AI 反思評估結果（如有改進建議）
+6. 檢查並編輯生成的主題和正文
+7. 點擊 **"📧 發送郵件"** 發送
 
-1. **Primary**: Groq API (fast, requires API key)
-   - Model: `llama-3.3-70b-versatile`
-   - Automatically used if `GROQ_API_KEY` is set
+**詳細使用說明請參考：[功能詳述](FEATURES.md#智能郵件助手)**
 
-2. **Fallback**: Local MLX Model (privacy-preserving, no API key needed)
-   - Model: `mlx-community/Qwen2.5-Coder-7B-Instruct-4bit`
-   - Automatically used when Groq API is unavailable or quota exhausted
+### 行事曆工具
 
-The system automatically switches between backends based on availability.
+1. 切換到 **"📅 Calendar Tool"** 標籤
+2. 使用快速選擇按鈕或輸入完整事件提示
+3. 點擊 **"📝 生成事件草稿"**
+4. 查看 AI 反思評估結果和地點驗證資訊
+5. 如有缺失資訊，系統會顯示下拉選單供選擇
+6. 檢查並修改事件內容
+7. 點擊 **"創建事件"** 確認
 
-## ⚙️ Configuration
+**詳細使用說明請參考：[功能詳述](FEATURES.md#智能行事曆管理)**
 
-Key configuration options in `deep_agent_rag/config.py`:
+## 🏗️ 專案結構
 
-### MLX Model Settings
-```python
-MLX_MODEL_ID = "mlx-community/Qwen2.5-Coder-7B-Instruct-4bit"
-MLX_MAX_TOKENS = 2048
-MLX_TEMPERATURE = 0.7
 ```
-
-### RAG Settings
-```python
-PDF_PATH = "./data/Tree_of_Thoughts.pdf"
-EMBEDDING_MODEL = "jinaai/jina-embeddings-v3"
-CHUNK_SIZE = 1000
-CHUNK_OVERLAP = 200
-RETRIEVER_K = 3
+Deep_Agentic_AI_Tool/
+├── deep_agent_rag/              # 主套件
+│   ├── agents/                  # 代理節點
+│   │   ├── planner.py          # 任務規劃節點
+│   │   ├── researcher.py       # 研究執行節點
+│   │   ├── note_taker.py       # 筆記整理節點
+│   │   ├── reporter.py         # 最終報告生成
+│   │   ├── email_agent.py      # 郵件生成代理
+│   │   ├── email_reflection_agent.py  # 郵件反思代理
+│   │   ├── calendar_agent.py    # 行事曆事件生成代理
+│   │   ├── calendar_reflection_agent.py  # 行事曆反思代理
+│   │   └── state.py            # 狀態定義
+│   ├── graph/                   # LangGraph 編排
+│   │   └── agent_graph.py      # 圖表構建與路由
+│   ├── models/                  # 模型包裝器
+│   │   └── mlx_chat_model.py   # MLX 模型整合
+│   ├── rag/                     # RAG 系統
+│   │   └── rag_system.py       # PDF 載入與檢索
+│   ├── tools/                   # 工具定義
+│   │   ├── agent_tools.py      # 股票、網路搜尋、PDF 工具
+│   │   ├── email_tool.py       # 郵件發送工具
+│   │   ├── calendar_tool.py    # 行事曆管理工具
+│   │   └── googlemaps_tool.py  # Google Maps 整合工具
+│   ├── ui/                      # 用戶界面
+│   │   └── gradio_interface.py # Gradio Web UI
+│   ├── utils/                   # 工具函數
+│   │   └── llm_utils.py        # LLM 實例管理
+│   └── config.py                # 配置
+├── data/                        # 數據目錄
+│   └── Tree_of_Thoughts.pdf
+├── Deep_Agent_Gradio_RAG_localLLM_main.py  # 主入口點
+├── main.py                      # 簡單入口點
+├── pyproject.toml               # 專案依賴
+└── README.md                    # 本文件
 ```
 
-### Agent Settings
-```python
-MAX_ITERATIONS = 5
-MAX_RESEARCH_ITERATIONS = 20
-```
+**詳細架構說明請參考：[系統架構](ARCHITECTURE.md)**
 
-### Email Settings
-```python
-EMAIL_SENDER = "wenliangmatt@gmail.com"  # Change to your email
-GMAIL_CREDENTIALS_FILE = "credentials.json"
-GMAIL_TOKEN_FILE = "token.json"
-```
+## ⚙️ 配置
 
-## 🔧 Development
+主要配置選項在 `deep_agent_rag/config.py`：
 
-### Adding New Tools
+- **MLX 模型設定**：模型 ID、最大 tokens、溫度
+- **RAG 設定**：PDF 路徑、嵌入模型、分塊大小
+- **代理設定**：最大迭代次數、反思迭代次數
+- **API 設定**：Groq、Gmail、Calendar、Google Maps
+- **外部 SSD 路徑**：模型緩存目錄
 
-1. Create a new tool function in `deep_agent_rag/tools/agent_tools.py`:
-   ```python
-   @tool
-   def my_new_tool(param: str) -> str:
-       """Tool description for the LLM."""
-       # Implementation
-       return result
-   ```
+**詳細配置說明請參考：[配置指南](CONFIGURATION.md)**
 
-2. Add the tool to `get_tools_list()` in the same file
+## 🔧 開發指南
 
-3. The agent will automatically discover and use the new tool
+### 添加新工具
 
-### Modifying Agent Logic
+1. 在 `deep_agent_rag/tools/` 中創建新工具函數
+2. 使用 `@tool` 裝飾器
+3. 在 `get_tools_list()` 中添加工具
+4. 代理會自動發現並使用新工具
 
-- **Planning logic**: Edit `deep_agent_rag/agents/planner.py`
-- **Research logic**: Edit `deep_agent_rag/agents/researcher.py`
-- **Report generation**: Edit `deep_agent_rag/agents/reporter.py`
+### 修改代理邏輯
 
-### Customizing UI
+- **規劃邏輯**：編輯 `deep_agent_rag/agents/planner.py`
+- **研究邏輯**：編輯 `deep_agent_rag/agents/researcher.py`
+- **報告生成**：編輯 `deep_agent_rag/agents/reporter.py`
 
-Edit `deep_agent_rag/ui/gradio_interface.py` to modify the web interface.
+### 自定義 UI
 
-## 📦 Dependencies
+編輯 `deep_agent_rag/ui/gradio_interface.py` 修改 Web 界面。
 
-Key dependencies (see `pyproject.toml` for complete list):
+**詳細開發指南請參考：[系統架構](ARCHITECTURE.md#開發指南)**
 
-- **LangChain**: Agent framework and tool integration
-- **LangGraph**: Agent orchestration and workflow management
-- **MLX/MLX-LM**: Local model inference (Apple Silicon optimized)
-- **Gradio**: Web interface
-- **ChromaDB**: Vector database for RAG
-- **Tavily**: Web search API
-- **yfinance**: Stock data retrieval
-- **Google API Client**: Gmail API integration
+## 📦 主要依賴
 
-## 🐛 Troubleshooting
+- **LangChain & LangGraph**：代理框架與工作流程管理
+- **MLX/MLX-LM**：本地模型推理（Apple Silicon 優化）
+- **Gradio**：Web 界面
+- **ChromaDB**：RAG 向量數據庫
+- **Tavily**：網路搜尋 API
+- **yfinance**：股票數據檢索
+- **Google API Client**：Gmail/Calendar API 整合
+- **googlemaps**：Google Maps API 整合
 
-### MLX Model Issues
+完整依賴列表請參考 `pyproject.toml`。
 
-- **Model not loading**: Ensure you have sufficient disk space and memory
-- **Slow inference**: This is normal for local models. Consider using Groq API for faster results
+## 🐛 故障排除
 
-### Groq API Issues
+### MLX 模型問題
+- **模型無法載入**：確保有足夠的磁碟空間和記憶體
+- **推理速度慢**：這是本地模型的正常現象，可考慮使用 Groq API 獲得更快結果
 
-- **Quota exhausted**: The system automatically falls back to local MLX model
-- **API errors**: Check your `GROQ_API_KEY` in `.env` file
+### Groq API 問題
+- **額度用完**：系統會自動切換到本地 MLX 模型
+- **API 錯誤**：檢查 `.env` 文件中的 `GROQ_API_KEY`
 
-### RAG System Issues
+### RAG 系統問題
+- **PDF 找不到**：確保 PDF 文件存在於 `config.py` 中指定的路徑
+- **嵌入模型錯誤**：系統會嘗試重新下載模型（如果緩存損壞）
 
-- **PDF not found**: Ensure the PDF file exists at the path specified in `config.py`
-- **Embedding model errors**: The system will attempt to re-download the model if cache is corrupted
+### Gmail/Calendar API 問題
+- **授權錯誤**：刪除 `token.json` 並���新授權
+- **憑證找不到**：確保 `credentials.json` 在專案根目錄
+- 詳細說明請參考 [Gmail API 設置指南](GMAIL_API_SETUP.md)
 
-### Gmail API Issues
+### Google Maps API 問題
+- **地點驗證失敗**：檢查 API 金鑰是否正確設置
+- **交通時間無法計算**：確保設置了 `USER_HOME_ADDRESS` 或 `USER_OFFICE_ADDRESS`
+- 詳細說明請參考 [Google Maps 整合說明](GOOGLE_MAPS_INTEGRATION.md)
 
-- **Authorization errors**: Delete `token.json` and re-authorize
-- **Credentials not found**: Ensure `credentials.json` is in the project root
-- See `GMAIL_API_SETUP.md` for detailed setup instructions
+## 📚 相關文檔
 
-## 📝 License
+- **[功能詳述](FEATURES.md)** - 所有功能的詳細說明與使用範例
+- **[系統架構](ARCHITECTURE.md)** - 系統架構、工作流程與開發指南
+- **[配置指南](CONFIGURATION.md)** - 完整的配置選項說明
+- **[Gmail API 設置](GMAIL_API_SETUP.md)** - Gmail API 設置步驟
+- **[Google Maps 整合](GOOGLE_MAPS_INTEGRATION.md)** - Google Maps API 整合說明
 
-[Add your license information here]
+## 📝 授權
 
-## 🤝 Contributing
+[添加您的授權資訊]
 
-[Add contribution guidelines here]
+## 🤝 貢獻
 
-## 📧 Contact
+[添加貢獻指南]
 
-[Add contact information here]
+## 📧 聯絡
 
-## 🙏 Acknowledgments
+[添加聯絡資訊]
 
-- **LangChain & LangGraph**: For the excellent agent framework
-- **MLX Team**: For efficient local model inference
-- **Qwen Team**: For the Qwen2.5 model
-- **Jina AI**: For the embedding model
+## 🙏 致謝
 
----
+- **LangChain & LangGraph**：優秀的代理框架
+- **MLX Team**：高效的本地模型推理
+- **Qwen Team**：Qwen2.5 模型
+- **Jina AI**：嵌入模型
 
-**Note**: This system is designed to work primarily on macOS with Apple Silicon for optimal MLX performance. Linux support is available but may have different performance characteristics.
+---
 
+**注意**：本系統主要設計用於 macOS（Apple Silicon）以獲得最佳 MLX 性能。Linux 支援可用，但性能特徵可能不同。