kenaz 0.3.18 → 0.3.19

package/core/.system/dashboard/FRONTEND.md

@@ -1,812 +0,0 @@
-# Dashboard 前端架構 (React/Next.js)
-
-**Kenaz Dashboard** 前端採用 **Next.js 16.1.6 (App Router)** 構建，提供跨平台 UI 能力，支援 **Web**、**Tauri** 和 **Electron** 三種運行模式。本文檔涵蓋前端的目錄結構、核心組件、狀態管理、hooks 系統、平台抽象層、以及與 Tauri 後端的 IPC 通訊機制。
-
----
-
-## 技術棧
-
-| 技術 | 版本 | 用途 |
-|------|------|------|
-| **Next.js** | 16.1.6 | React 框架 (App Router) |
-| **React** | 19.2.3 | UI 函式庫 |
-| **TypeScript** | ^5 | 型別系統 |
-| **Tailwind CSS** | ^4 | 樣式框架 |
-| **Tauri** | ^2.9.1 | 桌面應用整合 |
-| **Electron** | ^40.1.0 | 桌面應用 (備用方案) |
-| **Socket.IO** | ^4.8.3 | 即時通訊 (WebSocket) |
-| **@tanstack/react-query** | ^5.90.20 | 資料狀態管理 |
-| **xterm.js** | ^6.0.0 | 終端模擬器 |
-| **lucide-react** | ^0.563.0 | Icon 庫 |
-| **shaders** | ^2.3.61 | 背景特效 |
-
----
-
-## 目錄結構
-
-```
-dashboard/src/
-├── app/                           # Next.js App Router 路由
-│   ├── layout.tsx                 # 根 Layout（Providers、字體、全局樣式）
-│   ├── page.tsx                   # 主頁（Dashboard 主畫面）
-│   ├── globals.css                # 全局 CSS（TailwindCSS、自定義樣式）
-│   ├── agent-coordination/        # Agent 協作頁面
-│   ├── agents/                    # Agents 管理頁面
-│   ├── api/                       # API Routes（Next.js 後端端點）
-│   ├── docs/                      # 文檔頁面
-│   ├── poc-shaders/               # Shader 特效 PoC
-│   └── spec/                      # Spec 編輯頁面
-│
-├── components/                    # React 組件
-│   ├── agent-monitor/             # Agent 監控面板
-│   ├── agents-page/               # Agents 頁面組件
-│   ├── cli-status/                # CLI 狀態指示器
-│   ├── connection-status/         # 連線狀態指示器
-│   ├── cortex-control/            # Cortex 控制面板
-│   ├── docs/                      # 文檔組件
-│   ├── mobile/                    # 移動端專用組件
-│   ├── optimization/              # 優化建議面板
-│   ├── project-selector/          # 專案選擇器
-│   ├── providers.tsx              # Context Providers 包裝器
-│   ├── quick-actions/             # 快速操作面板
-│   │   ├── QuickActionsPanel.tsx # 主面板（包含所有卡片）
-│   │   ├── ScriptCard.tsx        # 單一腳本卡片
-│   │   ├── ConfirmDialog.tsx     # 確認對話框
-│   │   ├── OutputViewer.tsx      # 腳本輸出檢視器
-│   │   └── SchedulerControlCard.tsx # 排程器控制卡片
-│   ├── session-manager/           # CLI Session 管理
-│   ├── setup-wizard/              # 首次設置精靈
-│   ├── ShaderBackground.tsx       # Shader 背景（動態載入）
-│   ├── ShaderBackgroundLayer.tsx  # Shader 圖層（靜態渲染）
-│   ├── spec/                      # Spec 編輯組件
-│   ├── system-update/             # 系統更新組件
-│   ├── task-board/                # 任務看板
-│   │   ├── TaskBoard.tsx          # 看板主體（Kanban 風格）
-│   │   ├── TaskCard.tsx           # 單一任務卡片
-│   │   ├── TaskColumn.tsx         # 看板欄位（Pending/Active/Done）
-│   │   ├── TaskDetailModal.tsx    # 任務詳情 Modal
-│   │   ├── AgentBadge.tsx         # Agent 標籤
-│   │   ├── LockIndicator.tsx      # 鎖定狀態指示器
-│   │   └── PriorityBadge.tsx      # 優先級標籤
-│   ├── terminal/                  # 終端模擬器組件
-│   ├── ui/                        # UI 基礎組件（按鈕、輸入等）
-│   └── VersionFooter.tsx          # 版本資訊頁尾
-│
-├── hooks/                         # React Hooks
-│   ├── useAgentCoordination.ts    # Agent 協作狀態
-│   ├── use-auto-updater.ts        # 自動更新
-│   ├── use-cli-settings.ts        # CLI 設定
-│   ├── use-directory-autocomplete.ts # 目錄自動補全
-│   ├── use-heartbeat.ts           # Dashboard 心跳（保持 Agent 存活）
-│   ├── useKeyboardShortcuts.ts    # 鍵盤快捷鍵
-│   ├── use-media-query.ts         # 響應式媒體查詢（isMobile、isTablet）
-│   ├── use-polling.ts             # 輪詢 Hook
-│   ├── use-proposals.ts           # 優化建議
-│   ├── use-recent-directories.ts  # 最近目錄
-│   ├── use-scheduler.ts           # Multi-Agent Scheduler 控制
-│   ├── use-scheduler-events.ts    # Scheduler 事件監聽
-│   ├── use-scheduler-heartbeat.ts # Scheduler 心跳
-│   ├── use-self-enhancement.ts    # 自我增強狀態
-│   ├── use-setup-wizard.ts        # 設置精靈狀態
-│   ├── use-socket.ts              # WebSocket 連線
-│   ├── use-socket-state.ts        # WebSocket 狀態（任務、指標）
-│   └── use-viewport-height.ts     # Viewport 高度（iOS Safari 修正）
-│
-├── contexts/                      # React Contexts
-│   ├── ProjectContext.tsx         # 專案狀態（當前專案、專案列表）
-│   └── SocketContext.tsx          # WebSocket 全局狀態
-│
-├── lib/                           # 工具函式庫
-│   ├── api.ts                     # HTTP API 呼叫（Web 模式）
-│   ├── api-adapter.ts             # API 適配器（統一 Tauri/Web API）
-│   ├── agents-parser.ts           # Agent 狀態解析
-│   ├── agent-coordination/        # Agent 協作相關工具
-│   ├── cli/                       # CLI 工具
-│   ├── cortex-cli.ts              # Cortex CLI 包裝器
-│   ├── cortex-client.ts           # Cortex 客戶端
-│   ├── platform/                  # 平台抽象層 ⭐
-│   │   ├── index.ts               # 平台檢測與 Adapter 導出
-│   │   ├── types.ts               # 平台接口定義（PlatformAdapter、PtyConnection）
-│   │   ├── tauri-adapter.ts       # Tauri 平台實作
-│   │   └── web-adapter.ts         # Web 平台實作
-│   ├── scripts/                   # 腳本工具
-│   ├── socket/                    # WebSocket 工具
-│   ├── system/                    # 系統工具
-│   ├── tauri/                     # Tauri 專用工具
-│   ├── tauri-commands.ts          # Tauri IPC 指令包裝器
-│   └── utils.ts                   # 通用工具函式
-│
-└── types/                         # TypeScript 型別定義
-    ├── index.ts                   # 主型別定義（TaskQueue、AgentState、MetricsResponse、CLISession 等）
-    ├── agent-section/             # Agent 區域型別
-    ├── scheduler-events.ts        # Scheduler 事件型別
-    ├── shaders-react.d.ts         # Shaders 函式庫型別聲明
-    ├── socket.ts                  # WebSocket 型別
-    └── spec.ts                    # Spec 型別
-```
-
----
-
-## 核心組件架構
-
-### 1. 主頁佈局 (`app/page.tsx`)
-
-**職責**：Dashboard 主畫面，整合所有核心功能面板。
-
-**佈局模式**：
-- **桌面版**（Desktop）：三欄佈局 + 可調整終端面板
-  - **左側**：Session Manager、Agent Monitor、Cortex Control
-  - **中間**：任務統計卡片 + Task Board（Kanban 風格）
-  - **右側**：Quick Actions、Optimization Panel
-  - **底部**：Terminal Panel（可透過拖曳調整高度）
-- **移動/平板版**（Mobile/Tablet）：Tab 式佈局
-  - **Tab 1: Tasks** - 任務統計 + Task Board
-  - **Tab 2: Agents** - Sessions + Agent Monitor
-  - **Tab 3: Tools** - Quick Actions + Optimization
-  - **Tab 4: Terminal** - 全螢幕終端 Modal
-
-**關鍵功能**：
-- **專案切換**：透過 `ProjectContext` 切換專案，自動清除 Sessions、重新載入任務/Agents/Proposals
-- **響應式設計**：使用 `useIsMobile()` / `useIsTablet()` 自動切換佈局
-- **Shader 背景**：動態載入 `DynamicShaderBackground`（支援 None/Grain/Wave/Mesh 四種模式）
-- **終端拖曳調整**：支援滑鼠拖曳調整終端高度（最小 150px，最大 85vh）
-- **Heartbeat 機制**：每 10 秒發送心跳，保持 Agents 存活，Dashboard 關閉時通知 Agents 停止
-
-**關鍵依賴**：
-- `useProject()`：專案狀態
-- `useTasksSocketState()`：任務 + WebSocket 即時更新
-- `useMetricsSocketState()`：Token 指標 + 即時更新
-- `useHeartbeat()`：Dashboard 心跳
-
----
-
-### 2. Task Board (`components/task-board/`)
-
-**職責**：Kanban 風格的任務看板，顯示任務狀態流轉。
-
-**組件結構**：
-- **TaskBoard.tsx**：主容器，渲染三欄（Pending/Active/Done）
-- **TaskColumn.tsx**：單一狀態欄位（支援折疊/展開、任務計數）
-- **TaskCard.tsx**：任務卡片（顯示 ID、標題、優先級、Agent、鎖定狀態）
-- **TaskDetailModal.tsx**：任務詳情 Modal（YAML 格式、需求、驗收標準、依賴關係）
-
-**特性**：
-- **狀態分類**：`pending` / `in_progress` / `completed` / `blocked` / `cancelled`
-- **優先級標示**：P0（紅）/ P1（橙）/ P2（黃）/ P3（綠）
-- **依賴關係可視化**：顯示任務依賴 ID 列表
-- **路徑鎖定指示**：顯示 `scope_paths` 是否被鎖定
-
----
-
-### 3. Quick Actions Panel (`components/quick-actions/`)
-
-**職責**：快速執行腳本與排程器控制。
-
-**組件結構**：
-- **QuickActionsPanel.tsx**：主面板，整合所有卡片
-  - **ScriptCard**：顯示單一腳本（名稱、描述、執行按鈕）
-  - **SchedulerControlCard**：Multi-Agent Scheduler 控制（啟動/停止、狀態監控）
-  - **Formation Sections**（Unit/Solo/Squad/Legion）：Formation 系統快捷操作
-- **ConfirmDialog.tsx**：執行前確認對話框
-- **OutputViewer.tsx**：腳本輸出檢視器（即時串流、錯誤高亮）
-
-**腳本分類**：
-| 類別 | 說明 | 範例 |
-|------|------|------|
-| **initialization** | 初始化腳本 | INIT_GIT、SETUP_RAG、INIT_PROJECT |
-| **development** | 開發腳本 | START_DEV_AGENT（自我增強）、START_MULTI_AGENT |
-| **tools** | 工具腳本 | - |
-
-**Scheduler 控制**：
-- **啟動**：配置 `maxAgents`、`pollInterval`、`taskTimeout` 並啟動 Multi-Agent Scheduler
-- **停止**：停止排程器，釋放所有路徑鎖定
-- **狀態監控**：即時顯示運行狀態、Active Agents、Path Locks
-
----
-
-### 4. Shader Background (`components/ShaderBackground.tsx`)
-
-**職責**：提供動態背景特效（支援多種模式）。
-
-**模式**：
-- **None**：無特效
-- **Grain**：顆粒雜訊
-- **Wave**：波浪動畫
-- **Mesh**：網格漸變（預設）
-
-**實作方式**：
-- **DynamicShaderBackground**：使用 `dynamic` 動態載入（避免 SSR 錯誤）
-- **ShaderBackgroundLayer**：實際渲染層（使用 `shaders` 套件）
-- **ShaderToggle**：切換按鈕（儲存到 localStorage）
-
-**效能優化**：
-- 使用 `next/dynamic` 延遲載入
-- 支援 `mounted` 狀態避免 hydration mismatch
-- 自動偵測 GPU 性能（低性能裝置自動降級）
-
----
-
-## Hooks 系統
-
-### 1. `use-scheduler.ts` ⭐
-
-**職責**：Multi-Agent Scheduler 控制 Hook。
-
-**API**：
-```typescript
-const {
-  state,        // 當前狀態（isRunning、agents、locks、lastHeartbeat）
-  start,        // 啟動排程器（接受 SchedulerConfig）
-  stop,         // 停止排程器
-  refresh,      // 手動重新整理狀態
-  unlock,       // 手動解鎖路徑
-  terminateAgent, // 終止特定 Agent
-  isAvailable,  // 是否可用（Tauri 模式限定）
-  isLoading     // 是否正在操作
-} = useScheduler({
-  pollInterval: 5000,    // 輪詢間隔（預設 5 秒）
-  autoPoll: true,        // 自動輪詢
-  projectPath: '...',    // 專案路徑
-  onStart: () => {},     // 啟動回調
-  onStop: () => {},      // 停止回調
-  onError: (err) => {},  // 錯誤回調
-  onWarning: (warn) => {}// 警告回調
-});
-```
-
-**特性**：
-- **跨平台**：自動偵測 Tauri/Web 模式，呼叫對應 API
-- **即時事件**：整合 `useSchedulerEvents`，監聽 `heartbeat`、`state_changed`、`warning` 事件
-- **自動輪詢**：當 `isRunning=true` 時自動輪詢狀態
-
----
-
-### 2. `use-socket-state.ts`
-
-**職責**：整合 WebSocket 即時更新與 React Query 資料管理。
-
-**API**：
-```typescript
-// 任務資料 + WebSocket 即時更新
-const { data, isLoading, error, refetch, isConnected } = useTasksSocketState(
-  { projectPath, pipelinePath },
-  enabled
-);
-
-// Token 指標 + WebSocket 即時更新
-const { data, refetch } = useMetricsSocketState(enabled);
-```
-
-**工作原理**：
-1. **初始載入**：透過 `useQuery` 載入初始資料
-2. **WebSocket 訂閱**：監聽 `task:update` / `metrics:update` 事件
-3. **自動重新整理**：收到事件後呼叫 `queryClient.invalidateQueries` 更新資料
-
----
-
-### 3. `use-heartbeat.ts`
-
-**職責**：Dashboard 心跳機制，保持 Agents 存活。
-
-**API**：
-```typescript
-useHeartbeat({
-  enabled: true,
-  interval: 10000 // 10 秒
-});
-```
-
-**行為**：
-- **存活信號**：定期呼叫 `api.system.updateHeartbeat()`，通知 Agents Dashboard 仍在運行
-- **關閉通知**：當 Dashboard 關閉（`beforeunload` 事件），呼叫 `api.system.sendSchedulerStopSignal()` 通知 Agents 停止
-
----
-
-### 4. `use-media-query.ts`
-
-**職責**：響應式媒體查詢（避免 hydration mismatch）。
-
-**API**：
-```typescript
-const isMobile = useIsMobile();   // < 768px
-const isTablet = useIsTablet();   // 768px ~ 1024px
-const isDesktop = useIsDesktop(); // > 1024px
-```
-
-**實作方式**：
-- 使用 `useSyncExternalStore` 同步 `window.matchMedia` 狀態
-- SSR 時回傳 `false`，避免 hydration 錯誤
-
----
-
-## Contexts
-
-### 1. `ProjectContext.tsx` ⭐
-
-**職責**：管理專案列表與當前專案狀態。
-
-**API**：
-```typescript
-const {
-  projects,          // 專案列表
-  currentProject,    // 當前專案
-  currentProjectId,  // 當前專案 ID
-  isLoading,         // 是否正在載入
-  addProject,        // 新增專案
-  removeProject,     // 移除專案
-  setCurrentProject, // 切換專案
-  updateProject      // 更新專案資訊
-} = useProject();
-```
-
-**資料同步**：
-- **localStorage**：本地儲存（`kenaz-projects-config`）
-- **Server API**：`/api/projects` 端點（Next.js API Route）
-- **跨平台路徑遷移**：自動偵測 Windows/Mac/Linux，遷移不相容路徑
-
-**專案結構**：
-```typescript
-interface Project {
-  id: string;               // 唯一 ID
-  name: string;             // 專案名稱
-  path: string;             // 絕對路徑
-  pipelinePath: string;     // Pipeline 相對路徑（如 "dev/pipeline"）
-  createdAt: string;        // 建立時間
-}
-```
-
----
-
-### 2. `SocketContext.tsx`
-
-**職責**：WebSocket 全局連線管理。
-
-**API**：
-```typescript
-const {
-  socket,           // Socket.IO 實例
-  isConnected,      // 是否已連線
-  setProject,       // 設定當前專案路徑
-  subscribe,        // 訂閱事件
-  unsubscribe,      // 取消訂閱
-  emit              // 發送事件
-} = useSocketContext();
-```
-
-**事件訂閱**：
-```typescript
-useEffect(() => {
-  const handler = (data: TaskQueue) => { /* ... */ };
-  subscribe('task:update', handler);
-  return () => unsubscribe('task:update', handler);
-}, [subscribe, unsubscribe]);
-```
-
----
-
-## 平台抽象層 (`lib/platform/`)
-
-### 設計目標
-
-統一 **Tauri（IPC）** 和 **Web（HTTP + WebSocket）** 兩種運行模式的 API 呼叫方式。
-
-### 目錄結構
-
-```
-lib/platform/
-├── index.ts           # 平台檢測與 Adapter 導出
-├── types.ts           # PlatformAdapter 接口定義
-├── tauri-adapter.ts   # Tauri 平台實作
-└── web-adapter.ts     # Web 平台實作
-```
-
-### 接口定義 (`types.ts`)
-
-**PlatformAdapter** 定義了所有模組的統一接口：
-
-```typescript
-interface PlatformAdapter {
-  readonly platform: 'tauri' | 'web';
-
-  pty: { /* PTY 終端操作 */ };
-  tasks: { getTasks, getTaskDetail };
-  agents: { getAgents };
-  metrics: { getMetrics };
-  scripts: { list, execute, getProcessStatus, stop, ... };
-  fs: { readJsonFile, writeJsonFile, listDirectory, ... };
-  scheduler: { start, stop, getStatus, unlock, terminateAgent, ... };
-  singleAgent: { start, stop, getStatus, getLogs, ... };
-  system: { getVersion, getSystemInfo, checkEnvironment, ... };
-  config: { load, save };
-  spec: { parse, validate, save };
-  proposals: { getAll, accept, ignore, create };
-  cli: { getSessions, spawn, close, getSession };
-  cortex: { getStatus, toggle, exportChunks, ... };
-}
-```
-
-### 使用方式
-
-```typescript
-import { api } from '@/lib/platform';
-
-// 自動偵測平台並呼叫對應 API
-const result = await api.tasks.getTasks({ projectPath });
-const agents = await api.agents.getAgents({ projectPath });
-```
-
-### 平台檢測邏輯 (`index.ts`)
-
-```typescript
-export const api: PlatformAdapter = isTauri()
-  ? new TauriAdapter()
-  : new WebAdapter();
-```
-
-**`isTauri()` 判斷**：檢查 `window.__TAURI_INTERNALS__` 是否存在。
-
----
-
-### PTY Connection 抽象
-
-**問題**：Tauri 和 Web 模式的終端 I/O 機制不同：
-- **Tauri**：IPC 指令 + Event 推送（`pty-data` / `pty-exit`）
-- **Web**：WebSocket 雙向串流
-
-**解決方案**：`PtyConnection` 接口統一兩種模式。
-
-```typescript
-interface PtyConnection {
-  onData(callback: (data: Uint8Array) => void): void;
-  onExit(callback: (status: string) => void): void;
-  write(data: string): Promise<void>;
-  resize(cols: number, rows: number): Promise<void>;
-  disconnect(): void;
-}
-```
-
-**使用範例**：
-```typescript
-const conn = await api.pty.connect({ cmd: 'bash', cwd: '...' });
-conn.onData((data) => terminal.write(data));
-conn.onExit((status) => console.log('Exit:', status));
-await conn.write('ls -la\n');
-conn.disconnect();
-```
-
----
-
-## Tauri 後端通訊
-
-### IPC 指令包裝器 (`lib/tauri-commands.ts`)
-
-**職責**：包裝所有 Tauri IPC 指令（`invoke`）與事件監聽（`listen`）。
-
-**範例**：
-```typescript
-import { tauriCommands } from '@/lib/tauri-commands';
-
-// Scheduler 控制
-const status = await tauriCommands.scheduler.getStatus(projectPath);
-await tauriCommands.scheduler.start(projectPath, config);
-await tauriCommands.scheduler.stop(projectPath);
-
-// Task 查詢
-const tasks = await tauriCommands.tasks.getTasks(projectPath);
-
-// PTY 操作
-const session = await tauriCommands.pty.spawn({ cmd: 'bash' });
-await tauriCommands.pty.write(session.id, 'ls\n');
-```
-
-### Tauri Event 監聽
-
-**Scheduler 事件**：
-```typescript
-import { listen } from '@tauri-apps/api/event';
-
-// Scheduler 心跳事件
-const unlisten = await listen<SchedulerHeartbeatPayload>(
-  'scheduler:heartbeat',
-  (event) => {
-    console.log('Heartbeat:', event.payload);
-  }
-);
-
-// 清理
-unlisten();
-```
-
-**PTY 事件**：
-```typescript
-const unlisten = await listen<PtyDataEvent>('pty-data', (event) => {
-  if (event.payload.session_id === sessionId) {
-    terminal.write(event.payload.data);
-  }
-});
-```
-
----
-
-## API Routes (`app/api/`)
-
-**職責**：Next.js API Routes，提供 HTTP 端點（Web 模式使用）。
-
-**範例端點**：
-- `POST /api/tasks` - 取得任務列表
-- `GET /api/agents` - 取得 Agent 狀態
-- `POST /api/scripts/execute` - 執行腳本
-- `POST /api/scheduler/start` - 啟動 Scheduler
-- `GET /api/projects` - 取得專案配置
-
-**實作**：透過 `lib/api-adapter.ts` 呼叫後端 API（如 FastAPI）。
-
----
-
-## 型別定義 (`types/index.ts`)
-
-**核心型別**：
-
-```typescript
-// 任務佇列
-interface TaskQueue {
-  tasks: TaskSummary[];
-  statistics: TaskStatistics;
-}
-
-interface TaskSummary {
-  id: string;
-  title: string;
-  status: 'pending' | 'in_progress' | 'completed' | 'blocked' | 'cancelled';
-  priority: 'P0' | 'P1' | 'P2' | 'P3';
-  role?: string;
-  dependencies: string[];
-  scope_paths: string[];
-  is_locked?: boolean;
-}
-
-// Agent 狀態
-interface AgentState {
-  active_agents: AgentInfo[];
-  locks: LockInfo[];
-  queue_summary: { total: number; pending: number; in_progress: number; completed: number };
-}
-
-// CLI Session
-interface CLISession {
-  id: string;
-  name?: string;
-  status: 'active' | 'idle' | 'error';
-  created_at: string;
-  last_active: string;
-  project_path?: string;
-}
-
-// Metrics
-interface MetricsResponse {
-  total_input_tokens: number;
-  total_output_tokens: number;
-  total_cost: number;
-  history: TokenUsageEntry[];
-}
-```
-
----
-
-## 樣式系統
-
-### Tailwind CSS 配置
-
-**自定義主題**：
-```javascript
-// tailwind.config.ts
-theme: {
-  extend: {
-    colors: {
-      cyber: {
-        cyan: '#00ffff',
-        purple: '#9d00ff',
-        pink: '#ff006e',
-      }
-    },
-    fontFamily: {
-      display: ['Orbitron', 'sans-serif'],
-      tech: ['Share Tech Mono', 'monospace'],
-    }
-  }
-}
-```
-
-### 全局樣式 (`app/globals.css`)
-
-**Grid 背景**：
-```css
-.grid-background {
-  background-image:
-    linear-gradient(rgba(0, 255, 255, 0.05) 1px, transparent 1px),
-    linear-gradient(90deg, rgba(0, 255, 255, 0.05) 1px, transparent 1px);
-  background-size: 50px 50px;
-}
-```
-
-**HUD 卡片**：
-```css
-.hud-card {
-  @apply border border-cyan-400/30 bg-[#0a1628]/80 rounded backdrop-blur-sm;
-}
-```
-
----
-
-## 響應式設計
-
-### 斷點
-
-| 斷點 | 寬度 | 使用場景 |
-|------|------|---------|
-| **Mobile** | < 768px | 手機裝置 |
-| **Tablet** | 768px ~ 1024px | 平板裝置 |
-| **Desktop** | > 1024px | 桌面裝置 |
-
-### 適配策略
-
-**桌面版**：
-- 三欄佈局（280px / 1fr / 300px）
-- 可調整終端高度
-- 完整功能面板
-
-**移動/平板版**：
-- Tab 式佈局（Tasks/Agents/Tools/Terminal）
-- 全螢幕終端 Modal
-- 簡化卡片樣式（`compact` prop）
-
----
-
-## 效能優化
-
-### 1. 動態載入
-
-```typescript
-// ShaderBackground 動態載入（避免 SSR 錯誤）
-const DynamicShaderBackground = dynamic(
-  () => import('./ShaderBackgroundLayer'),
-  { ssr: false }
-);
-```
-
-### 2. React Query 快取
-
-```typescript
-const { data } = useQuery({
-  queryKey: ['tasks', projectPath],
-  queryFn: () => api.tasks.getTasks({ projectPath }),
-  staleTime: 30000,  // 30 秒內不重新請求
-  refetchInterval: 60000 // 每分鐘自動重新整理
-});
-```
-
-### 3. WebSocket 自動重連
-
-```typescript
-// SocketContext 自動重連機制
-socket.on('disconnect', () => {
-  console.log('Socket disconnected, reconnecting...');
-  socket.connect();
-});
-```
-
-### 4. 防抖與節流
-
-```typescript
-// 終端拖曳使用 requestAnimationFrame 節流
-const handleMouseMove = (e: MouseEvent) => {
-  rafId = requestAnimationFrame(() => {
-    setTerminalHeight(newHeight);
-  });
-};
-```
-
----
-
-## 開發指南
-
-### 新增組件
-
-1. 在 `components/` 建立資料夾
-2. 使用 TypeScript + Tailwind CSS
-3. 導出 `index.ts` 方便引用
-
-```typescript
-// components/my-component/MyComponent.tsx
-export function MyComponent({ title }: { title: string }) {
-  return <div className="hud-card">{title}</div>;
-}
-
-// components/my-component/index.ts
-export { MyComponent } from './MyComponent';
-```
-
-### 新增 Hook
-
-```typescript
-// hooks/use-my-hook.ts
-export function useMyHook() {
-  const [state, setState] = useState(false);
-
-  useEffect(() => {
-    // 初始化邏輯
-  }, []);
-
-  return { state, setState };
-}
-```
-
-### 新增 API 端點
-
-```typescript
-// app/api/my-endpoint/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-
-export async function GET(req: NextRequest) {
-  const data = await fetchData();
-  return NextResponse.json({ data });
-}
-```
-
----
-
-## 測試
-
-### 單元測試（Jest）
-
-```bash
-npm test
-npm run test:watch
-npm run test:coverage
-```
-
-**範例**：
-```typescript
-// components/TaskCard.test.tsx
-import { render, screen } from '@testing-library/react';
-import { TaskCard } from './TaskCard';
-
-test('renders task card', () => {
-  render(<TaskCard task={{ id: 'TASK_001', title: 'Test' }} />);
-  expect(screen.getByText('TASK_001')).toBeInTheDocument();
-});
-```
-
----
-
-## 部署
-
-### 開發模式
-
-```bash
-npm run dev          # Next.js 開發伺服器 (http://localhost:3000)
-npm run tauri:dev    # Tauri 開發模式（桌面應用）
-npm run electron:dev # Electron 開發模式
-```
-
-### 生產建置
-
-```bash
-npm run build              # Next.js 靜態建置
-npm run tauri:build        # Tauri 打包（Windows/Mac/Linux）
-npm run electron:build:win # Electron 打包（Windows）
-```
-
----
-
-## 相關文檔
-
-- [Dashboard Tauri 後端架構](./.system/dashboard/BACKEND.md)
-- [Tauri IPC 通訊機制](./.system/dashboard/IPC.md)
-- [Formation 系統](./.system/formation/README.md)
-- [Task Board 設計規格](./docs/specs/task-board.md)
-
----
-
-**最後更新**：2026-02-19
-**維護者**：Kenaz AI Team