kenaz 0.0.0-stage → 0.3.2

package/core/.system/dashboard/README.md

@@ -0,0 +1,737 @@
+# Dashboard Tauri 後端架構
+
+> **專案位置**: `dashboard/src-tauri/src/`
+> **技術棧**: Rust + Tauri + Axum (HTTP Server) + Portable-Pty (Terminal)
+> **職責**: 桌面應用後端 API、進程管理、Scheduler 協調、終端服務
+
+---
+
+## 📋 系統概述
+
+Dashboard Tauri 後端是 **Kenaz AI Desktop Application** 的核心服務層，提供：
+
+1. **Tauri Commands**：桌面應用 IPC（前端呼叫 Rust）
+2. **HTTP Server**：Web 模式 API（Axum + 狀態共享）
+3. **PTY Server**：終端會話管理（Portable-Pty）
+4. **Scheduler 協調**：Multi-Agent 和 Single-Agent 排程器管理
+5. **自動更新**：應用版本檢查與安裝
+
+### 核心設計原則
+
+**「雙模式架構 = Desktop IPC + HTTP API」**
+
+- **Desktop 模式**：透過 Tauri Commands 呼叫 Rust 函數（零網路延遲）
+- **Web 模式**：透過 HTTP Server 呼叫相同邏輯（跨平台）
+- **狀態共享**：`HttpAppState` 持有所有 `Arc<XxxState>`，確保狀態一致性
+
+---
+
+## 🏗️ 架構層級
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ lib.rs (Application Entry)                                      │
+│ ├── Tauri Commands Registration (261 commands)                  │
+│ ├── App State Management (Arc<ProcessState>, Arc<SchedulerState>)│
+│ ├── HTTP Server Setup (Port Fallback + Health Monitoring)       │
+│ ├── PTY Server Setup (Terminal Sessions)                        │
+│ └── Auto-Update Setup (Production Only)                         │
+└─────────────────────────────────────────────────────────────────┘
+         ↓                         ↓                        ↓
+┌─────────────────┐   ┌────────────────────┐   ┌──────────────────┐
+│   features/     │   │  infrastructure/   │   │   pty/          │
+│  (Business)     │   │   (Foundation)     │   │ (Terminal)      │
+│                 │   │                    │   │                 │
+│ • task          │   │ • fs               │   │ • commands/     │
+│ • proposal      │   │ • git              │   │   - spawn       │
+│ • script        │   │ • process_manager  │   │   - io          │
+│ • agent         │   │ • path_lock_mgr    │   │   - resize      │
+│ • metrics       │   │ • recovery         │   │   - lifecycle   │
+│ • progress      │   │ • http_server      │   │   - state       │
+│ • config        │   │ • pty_server       │   │ • pty_manager   │
+│ • autocomplete  │   │                    │   │                 │
+│ • scheduler     │   └────────────────────┘   └──────────────────┘
+│ • single_agent  │
+│ • spec          │
+└─────────────────┘
+```
+
+---
+
+## 📁 目錄結構
+
+### lib.rs（應用入口）
+
+**職責**：
+- 註冊所有 Tauri Commands（261 個）
+- 管理共享狀態（`Arc<T>` 注入）
+- 啟動 HTTP Server + PTY Server
+- 配置自動更新（Production）
+- Debug 模式自動開啟 DevTools
+
+**關鍵邏輯**：
+```rust
+// 狀態注入
+.manage(Arc::new(ProcessState::new()))
+.manage(Arc::new(SchedulerAppState::new()))
+.manage(Arc::new(SingleAgentAppState::new()))
+.manage(Arc::new(PtyManagerState::new()))
+
+// HTTP Server 啟動（Port Fallback）
+for port_offset in 0..max_port_attempts {
+    let port = base_port + port_offset;
+    match HttpServer::from_env().start_with_state(http_state.clone()).await {
+        Ok(handle) => {
+            // Health Monitoring (每 30 秒檢查一次，3 次失敗後警告)
+            break;
+        }
+        Err(e) => continue
+    }
+}
+
+// PTY Server 啟動（Terminal Sessions）
+let pty_launcher = PtyServerLauncher::from_env();
+pty_launcher.start().await;
+pty_launcher.start_health_monitoring();
+```
+
+---
+
+### features/（業務邏輯層）
+
+**設計模式**：每個 feature 獨立模組，遵循 `manager.rs` + `mod.rs` + `manager_tests.rs` 結構。
+
+| Feature | 模組路徑 | 職責 | 關鍵檔案 |
+|---------|---------|------|---------|
+| **task** | `features/task/` | 任務管理、佇列操作、依賴解析 | `manager.rs`, `types.rs`, `queue.rs` |
+| **proposal** | `features/proposal/` | 優化建議管理 | `manager.rs`, `types.rs` |
+| **script** | `features/script/` | 腳本執行管理（ProcessState） | `manager.rs`, `types.rs` |
+| **agent** | `features/agent/` | Agent 狀態管理 | `manager.rs` |
+| **metrics** | `features/metrics/` | Token 統計、RAG 狀態 | `manager.rs` |
+| **progress** | `features/progress/` | 開發進度追蹤 | `manager.rs` |
+| **config** | `features/config/` | 應用配置管理 | `manager.rs`, `types.rs` |
+| **autocomplete** | `features/autocomplete/` | 檔案路徑自動完成 | `manager.rs` |
+| **scheduler** | `features/scheduler/` | Multi-Agent 排程器 | `core.rs`, `commands.rs`, `agent.rs`, `events/` |
+| **single_agent** | `features/single_agent/` | Single-Agent 排程器 | `core.rs`, `commands.rs` |
+| **spec** | `features/spec/` | 規格檔案解析與驗證 | `manager.rs`, `parser.rs`, `validator.rs` |
+
+#### 重點模組：scheduler（Multi-Agent 排程器）
+
+**目錄結構**：
+```
+scheduler/
+├── mod.rs              # 模組定義與 re-export
+├── core.rs             # Scheduler 核心邏輯（鎖定、分派、恢復）
+├── config.rs           # SchedulerConfig（環境變數載入）
+├── agent.rs            # Agent 分派邏輯（dispatch_to_agent）
+├── state.rs            # SchedulerAppState（Arc<Mutex<HashMap>>）
+├── types.rs            # 類型定義（PathLock, LockState, ProcessInfo）
+├── errors.rs           # 錯誤處理（SchedulerError）
+├── commands.rs         # Tauri Commands（start_scheduler, stop_scheduler）
+├── recovery_commands.rs # 錯誤恢復 Commands（full_recovery, check_consistency）
+├── multi_project.rs    # 多專案管理（list_projects, stop_all_schedulers）
+├── events/             # 即時事件系統
+│   ├── mod.rs          # EVENT_* 常量定義
+│   ├── emitter.rs      # SchedulerEventEmitter（Tauri Emit + Heartbeat）
+│   ├── heartbeat.rs    # HeartbeatManager（每 2 秒心跳）
+│   ├── payloads.rs     # AgentUpdatePayload, TaskUpdatePayload, etc.
+│   └── warnings.rs     # WarningPayload, WarningCode（狀態異常警告）
+├── helpers.rs          # 工具函數
+└── helpers_tests.rs    # 工具函數測試
+```
+
+**關鍵機制**：
+- **路徑鎖定**：防止多個 Agent 同時修改同一檔案（`path_lock_manager`）
+- **依賴解析**：Python `dependency_resolver.py` 拓撲排序
+- **即時事件**：透過 Tauri Event System 推送狀態更新（`emit_scheduler_heartbeat`）
+- **錯誤恢復**：檢測 Stale State（長時間未更新）、清理殘留鎖定（`full_recovery`）
+
+#### 重點模組：single_agent（Single-Agent 排程器）
+
+**目錄結構**：
+```
+single_agent/
+├── mod.rs              # 模組定義與 re-export
+├── core.rs             # SingleAgentScheduler 核心邏輯
+├── state.rs            # SingleAgentAppState（Arc<Mutex<HashMap>>）
+├── commands.rs         # Tauri Commands（start_single_agent, stop_single_agent）
+└── types.rs            # 類型定義（SingleAgentInfo, SingleAgentStatus）
+```
+
+**關鍵差異**：
+- **無路徑鎖定**：單 Agent 不需要並行衝突檢測
+- **簡化狀態**：只追蹤 Agent PID、狀態、日誌
+- **適用場景**：單一 Agent 連續開發（Dev Agent Mode）
+
+---
+
+### infrastructure/（基礎設施層）
+
+**設計模式**：跨 feature 的共用基礎能力，零業務邏輯。
+
+| 模組 | 模組路徑 | 職責 | 關鍵檔案 |
+|------|---------|------|---------|
+| **fs** | `infrastructure/fs/` | 檔案系統操作（JSON/Text 讀寫、目錄列表） | `commands.rs`, `helpers.rs`, `types.rs` |
+| **git** | `infrastructure/git/` | Git 操作（Branch 隔離、Repo 狀態） | `manager.rs`, `types.rs` |
+| **process_manager** | `infrastructure/process_manager/` | 進程生命週期管理（Spawn、Kill、Timeout） | `manager.rs`, `config.rs` |
+| **path_lock_manager** | `infrastructure/path_lock_manager/` | 路徑鎖定機制（衝突檢測） | `manager.rs`, `types.rs` |
+| **recovery** | `infrastructure/recovery/` | 錯誤恢復邏輯（Panic Catch、Shutdown Signal） | `manager.rs`, `types.rs` |
+| **http_server** | `infrastructure/http_server/` | HTTP API Server（Axum + 狀態共享） | `mod.rs`, `config.rs`, `routes/` |
+| **pty_server_launcher** | `infrastructure/pty_server_launcher/` | PTY Server 啟動器（Terminal Sessions） | `mod.rs`, `config.rs` |
+
+#### 重點模組：http_server（HTTP API Server）
+
+**目錄結構**：
+```
+http_server/
+├── mod.rs              # HttpServer 啟動邏輯 + HttpAppState
+├── config.rs           # HttpServerConfig（環境變數載入）
+├── config_tests.rs
+└── routes/             # Axum Routes
+    ├── mod.rs          # Router 組裝
+    ├── agents.rs       # /api/agents/*
+    ├── health.rs       # /api/health
+    ├── scheduler.rs    # /api/scheduler/*
+    ├── single_agent.rs # /api/single-agent/*
+    └── tasks.rs        # /api/tasks/*
+```
+
+**關鍵邏輯**：
+```rust
+// HttpAppState（持有所有 Arc<XxxState>）
+pub struct HttpAppState {
+    pub app_handle: Option<tauri::AppHandle>,
+    pub scheduler_state: Arc<SchedulerAppState>,
+    pub single_agent_state: Arc<SingleAgentAppState>,
+    pub process_state: Arc<ProcessState>,
+}
+
+// Port Fallback（5500 → 5501 → 5502 ...）
+let base_port = HttpServerConfig::from_env().port; // 預設 5500
+for port_offset in 0..5 {
+    let port = base_port + port_offset;
+    match HttpServer::start(port).await {
+        Ok(_) => break,
+        Err(_) => continue
+    }
+}
+
+// Health Monitoring（每 30 秒檢查，3 次失敗警告）
+tokio::spawn(async move {
+    loop {
+        tokio::time::sleep(Duration::from_secs(30)).await;
+        match TcpStream::connect(&addr).await {
+            Ok(_) => consecutive_failures = 0,
+            Err(_) => {
+                consecutive_failures += 1;
+                if consecutive_failures >= 3 {
+                    eprintln!("[HTTP Server] crashed after 3 failures");
+                    break;
+                }
+            }
+        }
+    }
+});
+```
+
+#### 重點模組：pty_server_launcher（PTY Server）
+
+**職責**：
+- 啟動 PTY Server（`pty-server/index.ts`）
+- 提供 Terminal Session API（Web 模式用）
+- Health Monitoring（每 15 秒檢查）
+
+**環境變數**：
+```bash
+KENAZ_PTY_PORT=5501              # PTY Server 監聽 Port
+KENAZ_PTY_HEALTH_CHECK_INTERVAL=15  # Health Check 間隔（秒）
+```
+
+**啟動流程**：
+```rust
+// 偵測 pty-server/ 目錄是否存在
+let pty_server_dir = current_dir.join("pty-server");
+if !pty_server_dir.exists() {
+    return Err(PtyServerError::NotFound);
+}
+
+// 啟動 Node.js 進程
+let child = Command::new("node")
+    .arg("index.ts")
+    .current_dir(&pty_server_dir)
+    .spawn()?;
+
+// Health Monitoring
+tokio::spawn(async move {
+    loop {
+        tokio::time::sleep(Duration::from_secs(15)).await;
+        match TcpStream::connect(&addr).await {
+            Ok(_) => {},
+            Err(_) => eprintln!("[PTY Server] Health check FAILED")
+        }
+    }
+});
+```
+
+---
+
+### pty/（終端管理層）
+
+**職責**：提供 Desktop 模式的終端會話管理（Tauri 原生 PTY）。
+
+**目錄結構**：
+```
+pty/
+├── mod.rs              # PTY 核心實作（portable_pty）
+├── pty_manager.rs      # PtyManagerState（Arc<RwLock<HashMap>>）
+└── commands/           # Tauri Commands
+    ├── mod.rs          # 模組定義
+    ├── spawn.rs        # pty_spawn（建立新會話）
+    ├── io.rs           # pty_write（寫入輸入）
+    ├── resize.rs       # pty_resize（調整視窗大小）
+    ├── lifecycle.rs    # pty_close（關閉會話）
+    └── state.rs        # pty_list, pty_get_session（查詢狀態）
+```
+
+**關鍵實作**：
+```rust
+// PtyManager（使用 portable_pty）
+pub struct PtyManager {
+    sessions: Arc<RwLock<HashMap<String, PtySession>>>,
+}
+
+// 建立新會話
+pub fn spawn(&self, id: &str, shell: &str, cwd: &str) -> Result<(), PtyError> {
+    let pair = self.pty_system.openpty(PtySize::default())?;
+    let cmd = CommandBuilder::new(shell);
+    let child = pair.slave.spawn_command(cmd)?;
+
+    // 啟動輸出監聽（Event Emit）
+    let reader = pair.master.try_clone_reader()?;
+    tokio::spawn(async move {
+        // 讀取輸出 → Tauri Event Emit
+    });
+
+    self.sessions.write().insert(id, session);
+    Ok(())
+}
+```
+
+---
+
+### commands/（全域 Commands）
+
+**職責**：不屬於任何 feature 的全域性命令。
+
+**檔案**：
+- `commands/mod.rs`：系統資訊、心跳更新、環境檢查
+
+**關鍵 Commands**：
+```rust
+#[tauri::command]
+fn get_system_info() -> SystemInfo {
+    SystemInfo {
+        os: std::env::consts::OS,
+        arch: std::env::consts::ARCH,
+        version: env!("CARGO_PKG_VERSION"),
+    }
+}
+
+#[tauri::command]
+fn update_heartbeat(project_path: String) -> Result<(), String> {
+    // 更新專案心跳時間戳
+}
+
+#[tauri::command]
+fn check_environment() -> EnvironmentCheckResult {
+    // 檢查 Node.js, Python, Git 版本
+}
+```
+
+---
+
+### updater/（自動更新）
+
+**職責**：Production 模式自動檢查與安裝應用更新（tauri-plugin-updater）。
+
+**關鍵邏輯**：
+```rust
+// 每 5 秒檢查一次更新
+#[cfg(not(debug_assertions))]
+{
+    let handle = app.handle().clone();
+    tauri::async_runtime::spawn(async move {
+        tokio::time::sleep(Duration::from_secs(5)).await;
+        let _ = updater::check_for_updates(handle).await;
+    });
+}
+```
+
+**環境配置**：
+- 更新 Manifest：`tauri.conf.json` → `updater.endpoints`
+- Windows Installer：生成 `.msi` 或 `.exe`
+
+---
+
+## 🔄 狀態管理策略
+
+### 狀態共享模式
+
+所有共享狀態使用 `Arc<T>` 包裝，確保跨執行緒安全：
+
+| 狀態類型 | Arc<T> | 內部鎖 | 用途 |
+|---------|--------|--------|------|
+| `ProcessState` | `Arc<ProcessState>` | `RwLock<HashMap>` | 腳本執行進程追蹤 |
+| `SchedulerAppState` | `Arc<SchedulerAppState>` | `Mutex<HashMap>` | Multi-Agent Scheduler 狀態 |
+| `SingleAgentAppState` | `Arc<SingleAgentAppState>` | `Mutex<HashMap>` | Single-Agent Scheduler 狀態 |
+| `PtyManagerState` | `Arc<PtyManagerState>` | `RwLock<HashMap>` | PTY 會話追蹤 |
+| `HttpAppState` | - | `Arc<T>` 組合 | HTTP Server 持有所有狀態的引用 |
+
+### 狀態注入流程
+
+```rust
+// 1. 建立狀態
+let process_state = Arc::new(ProcessState::new());
+let scheduler_state = Arc::new(SchedulerAppState::new());
+let single_agent_state = Arc::new(SingleAgentAppState::new());
+let pty_state = Arc::new(PtyManagerState::new());
+
+// 2. 注入 Tauri App
+tauri::Builder::default()
+    .manage(process_state.clone())
+    .manage(scheduler_state.clone())
+    .manage(single_agent_state.clone())
+    .manage(pty_state.clone())
+
+// 3. HTTP Server 狀態共享
+let http_state = HttpAppState::with_full_state(
+    app_handle,
+    scheduler_state,
+    single_agent_state,
+    process_state
+);
+
+// 4. Tauri Command 中取得狀態
+#[tauri::command]
+fn my_command(state: tauri::State<Arc<ProcessState>>) -> Result<(), String> {
+    let processes = state.inner().processes.read().unwrap();
+    // ...
+}
+```
+
+---
+
+## 🚀 啟動流程
+
+### Desktop 模式啟動
+
+```bash
+cd dashboard
+npm run tauri dev  # 開發模式
+npm run tauri build  # 生產模式
+```
+
+**啟動順序**：
+1. Tauri 啟動（Rust 後端）
+2. 注入共享狀態（`Arc<ProcessState>`, `Arc<SchedulerAppState>` 等）
+3. 註冊 261 個 Tauri Commands
+4. 啟動 PTY Server（Terminal Sessions）→ Port 5501
+5. 啟動 HTTP Server（Web API）→ Port 5500（Fallback 5501-5504）
+6. HTTP Health Monitoring 開始（每 30 秒檢查）
+7. PTY Health Monitoring 開始（每 15 秒檢查）
+8. [Production Only] 自動更新檢查（5 秒後）
+9. [Debug Only] 自動開啟 DevTools
+
+### Web 模式啟動
+
+**前端連接 HTTP Server**（`http://127.0.0.1:5500`）：
+```typescript
+// dashboard/src/lib/api.ts
+export async function getTasks(projectPath: string) {
+  const response = await fetch(`http://127.0.0.1:5500/api/tasks?path=${projectPath}`);
+  return response.json();
+}
+```
+
+**Port Fallback 策略**：
+```rust
+// 嘗試 5500 → 5501 → 5502 → 5503 → 5504
+for port_offset in 0..5 {
+    let port = 5500 + port_offset;
+    match HttpServer::start(port).await {
+        Ok(handle) => {
+            println!("HTTP Server started on {}", port);
+            break;
+        }
+        Err(_) => continue
+    }
+}
+```
+
+---
+
+## 📡 API 設計
+
+### Tauri Commands（Desktop IPC）
+
+**呼叫方式**（TypeScript）：
+```typescript
+import { invoke } from '@tauri-apps/api/core';
+
+// 取得任務列表
+const tasks = await invoke<Task[]>('get_tasks', { projectPath: '/path/to/project' });
+
+// 啟動 Scheduler
+const result = await invoke<StartSchedulerResponse>('start_scheduler', {
+  projectPath: '/path/to/project',
+  config: { maxAgents: 3 }
+});
+```
+
+**註冊方式**（Rust）：
+```rust
+.invoke_handler(tauri::generate_handler![
+    get_tasks,
+    start_scheduler,
+    stop_scheduler,
+    // ... 258 個其他 Commands
+])
+```
+
+### HTTP REST API（Web 模式）
+
+**Base URL**：`http://127.0.0.1:5500`
+
+| Endpoint | Method | 說明 |
+|----------|--------|------|
+| `/api/health` | GET | 健康檢查 |
+| `/api/tasks` | GET | 取得任務列表 |
+| `/api/tasks/:id` | GET | 取得任務詳情 |
+| `/api/agents` | GET | 取得 Agent 列表 |
+| `/api/scheduler/start` | POST | 啟動 Scheduler |
+| `/api/scheduler/stop` | POST | 停止 Scheduler |
+| `/api/scheduler/status` | GET | 取得 Scheduler 狀態 |
+| `/api/single-agent/start` | POST | 啟動 Single-Agent |
+| `/api/single-agent/stop` | POST | 停止 Single-Agent |
+
+**範例請求**：
+```bash
+# 取得任務列表
+curl "http://127.0.0.1:5500/api/tasks?path=/path/to/project"
+
+# 啟動 Scheduler
+curl -X POST "http://127.0.0.1:5500/api/scheduler/start" \
+  -H "Content-Type: application/json" \
+  -d '{"project_path": "/path/to/project", "max_agents": 3}'
+```
+
+---
+
+## 🛠️ 錯誤處理
+
+### 錯誤類型定義
+
+每個模組定義專屬錯誤類型，統一格式：
+
+```rust
+// features/scheduler/errors.rs
+#[derive(Debug, Serialize, Deserialize)]
+pub enum SchedulerErrorCode {
+    LockConflict,
+    TaskNotFound,
+    AgentTimeout,
+    InvalidState,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct SchedulerError {
+    pub code: SchedulerErrorCode,
+    pub message: String,
+    pub details: Option<String>,
+}
+```
+
+### 錯誤傳播
+
+Tauri Command 回傳 `Result<T, String>`：
+
+```rust
+#[tauri::command]
+pub fn start_scheduler(
+    project_path: String,
+    state: tauri::State<Arc<SchedulerAppState>>
+) -> Result<StartSchedulerResponse, String> {
+    Scheduler::start(&project_path)
+        .map_err(|e| e.to_string())?;
+
+    Ok(StartSchedulerResponse { success: true })
+}
+```
+
+### Panic Recovery
+
+所有關鍵邏輯包裹在 `catch_panic`：
+
+```rust
+use crate::infrastructure::recovery::catch_panic;
+
+pub fn critical_operation() -> Result<(), String> {
+    catch_panic(|| {
+        // 可能 panic 的代碼
+        risky_operation();
+    }, "critical_operation")
+    .map_err(|e| format!("Operation failed: {}", e))
+}
+```
+
+---
+
+## 🧪 測試策略
+
+### 測試檔案命名
+
+所有模組遵循 `*_tests.rs` 命名：
+
+```
+manager.rs         → manager_tests.rs
+config.rs          → config_tests.rs
+helpers.rs         → helpers_tests.rs
+```
+
+### 測試覆蓋範圍
+
+| 模組 | 單元測試 | 整合測試 | E2E 測試 |
+|------|---------|---------|---------|
+| `features/scheduler` | ✅ | ✅ | ⏳ |
+| `infrastructure/fs` | ✅ | ✅ | - |
+| `infrastructure/process_manager` | ✅ | ✅ | - |
+| `pty/` | ✅ | ⏳ | - |
+| `http_server` | ⏳ | ⏳ | - |
+
+### 執行測試
+
+```bash
+cd dashboard/src-tauri
+
+# 執行所有測試
+cargo test
+
+# 執行特定模組測試
+cargo test --package kenaz-dashboard --lib features::scheduler::helpers_tests
+
+# 顯示輸出
+cargo test -- --nocapture
+```
+
+---
+
+## 📊 效能考量
+
+### 狀態鎖定策略
+
+- **讀多寫少**：使用 `RwLock`（如 `PtyManagerState`）
+- **寫操作頻繁**：使用 `Mutex`（如 `SchedulerAppState`）
+- **避免死鎖**：統一鎖定順序，限制鎖持有時間
+
+### 並行處理
+
+```rust
+// HTTP Server 使用 Tokio 異步執行
+#[tokio::main]
+async fn main() {
+    let listener = TcpListener::bind("127.0.0.1:5500").await.unwrap();
+    axum::serve(listener, app).await.unwrap();
+}
+
+// Tauri Commands 在獨立執行緒執行
+tauri::async_runtime::spawn(async move {
+    // 長時間運行的任務
+});
+```
+
+### Port Fallback 優化
+
+避免無限等待，設置最大嘗試次數：
+
+```rust
+let max_port_attempts = 5;
+for port_offset in 0..max_port_attempts {
+    // 嘗試啟動
+}
+
+if _http_handle.is_none() {
+    eprintln!("FATAL: Failed to start after {} attempts", max_port_attempts);
+}
+```
+
+---
+
+## 🔍 監控與日誌
+
+### Health Monitoring
+
+**HTTP Server**：
+- 檢查間隔：30 秒
+- 失敗閾值：3 次連續失敗
+- 檢查方式：TCP 連線測試
+
+**PTY Server**：
+- 檢查間隔：15 秒
+- 檢查方式：TCP 連線測試
+
+### 日誌格式
+
+```rust
+// 統一使用 eprintln! 輸出
+eprintln!("[HTTP Server] Started on http://127.0.0.1:{}", port);
+eprintln!("[PTY Server] Health check FAILED - connection refused");
+eprintln!("[Scheduler] Agent dispatched: {:?}", agent_info);
+```
+
+### Tauri Event System（即時推送）
+
+```rust
+// Scheduler 狀態更新
+app_handle.emit("scheduler:agent_update", AgentUpdatePayload {
+    agent_id: "agent_001",
+    action: "dispatched",
+    timestamp: Utc::now().timestamp(),
+});
+
+// 前端監聽
+import { listen } from '@tauri-apps/api/event';
+
+listen('scheduler:agent_update', (event) => {
+  console.log('Agent update:', event.payload);
+});
+```
+
+---
+
+## 🚧 已知限制與未來改進
+
+### 已知限制
+
+1. **HTTP Server 單執行緒**：目前無多執行緒支援（Axum 預設單執行緒）
+2. **PTY Server 重啟**：PTY Server 崩潰後不會自動重啟（需手動重啟）
+3. **日誌持久化**：目前只輸出到 stderr，未寫入檔案
+4. **測試覆蓋率**：部分模組測試不完整（如 `http_server`）
+
+### 未來改進
+
+- [ ] 實作日誌輪轉（Log Rotation）
+- [ ] 增加 Metrics 收集（Prometheus）
+- [ ] HTTP Server 支援 HTTPS
+- [ ] PTY Server 自動重啟機制
+- [ ] 完善 E2E 測試覆蓋率
+
+---
+
+## 📚 相關文檔
+
+- [Tauri 官方文檔](https://tauri.app/)
+- [Axum Web Framework](https://github.com/tokio-rs/axum)
+- [Portable-Pty](https://github.com/wez/wezterm/tree/main/pty)
+- [Scheduler 系統設計](../.system/pipeline/README.md)
+- [Formation 系統](../.system/formation/README.md)
+- [失敗學習系統](../.system/failure/README.md)