dash-devtools 1.0.0__py3-none-any.whl

dash_devtools/vision/__init__.py

@@ -0,0 +1,368 @@
+"""
+視覺 AI 工具
+使用 agent-browser 截圖 + Gemini AI 進行 UI/UX 分析
+
+功能：
+- 網頁截圖並分析 UI/UX 問題
+- 視覺回歸測試
+- 無障礙設計檢查
+- 效能視覺指標分析
+"""
+
+import subprocess
+import shutil
+import base64
+import tempfile
+from pathlib import Path
+from typing import Optional, Dict, List
+from dataclasses import dataclass
+
+
+@dataclass
+class VisionResult:
+    """視覺分析結果"""
+    success: bool
+    url: str = ""
+    screenshot_path: str = ""
+    analysis: str = ""
+    issues: List[str] = None
+    recommendations: List[str] = None
+    error: str = ""
+
+    def __post_init__(self):
+        if self.issues is None:
+            self.issues = []
+        if self.recommendations is None:
+            self.recommendations = []
+
+
+def check_dependencies() -> Dict[str, bool]:
+    """檢查依賴是否已安裝"""
+    return {
+        'agent-browser': shutil.which('agent-browser') is not None,
+        'gemini': _check_gemini_available()
+    }
+
+
+def _check_gemini_available() -> bool:
+    """檢查 Gemini API 是否可用"""
+    try:
+        from ..ai_engine import AIEngine
+        AIEngine()
+        return True
+    except Exception:
+        return False
+
+
+def take_screenshot(url: str, output_path: Optional[str] = None, wait_ms: int = 3000) -> Optional[str]:
+    """
+    使用 agent-browser 截圖
+
+    Args:
+        url: 要截圖的網址
+        output_path: 輸出路徑 (預設建立臨時檔案)
+        wait_ms: 等待時間 (毫秒)
+
+    Returns:
+        截圖路徑，失敗回傳 None
+    """
+    if not shutil.which('agent-browser'):
+        return None
+
+    if not output_path:
+        output_path = tempfile.mktemp(suffix='.png')
+
+    try:
+        # 開啟頁面
+        result = subprocess.run(
+            ['agent-browser', 'open', url],
+            capture_output=True,
+            text=True,
+            timeout=30
+        )
+
+        if result.returncode != 0:
+            subprocess.run(['agent-browser', 'close'], capture_output=True)
+            return None
+
+        # 等待載入
+        subprocess.run(
+            ['agent-browser', 'wait', '--load', 'networkidle'],
+            capture_output=True,
+            timeout=15
+        )
+
+        # 額外等待 JS 渲染
+        subprocess.run(
+            ['agent-browser', 'wait', str(wait_ms)],
+            capture_output=True,
+            timeout=10
+        )
+
+        # 截圖
+        result = subprocess.run(
+            ['agent-browser', 'screenshot', output_path, '--full'],
+            capture_output=True,
+            timeout=30
+        )
+
+        subprocess.run(['agent-browser', 'close'], capture_output=True)
+
+        if result.returncode == 0 and Path(output_path).exists():
+            return output_path
+
+    except Exception:
+        subprocess.run(['agent-browser', 'close'], capture_output=True)
+
+    return None
+
+
+def analyze_image(
+    image_path: str,
+    prompt: Optional[str] = None,
+    analysis_type: str = "general"
+) -> VisionResult:
+    """
+    使用 AI 分析圖片
+
+    Args:
+        image_path: 圖片路徑
+        prompt: 自訂分析提示 (可選)
+        analysis_type: 分析類型 (general, ui_ux, accessibility, performance)
+
+    Returns:
+        VisionResult 物件
+    """
+    result = VisionResult(success=False)
+
+    # 檢查檔案
+    if not Path(image_path).exists():
+        result.error = f"圖片不存在: {image_path}"
+        return result
+
+    result.screenshot_path = image_path
+
+    # 預設提示
+    prompts = {
+        "general": """分析這張網頁截圖，提供：
+1. 整體 UI/UX 評估
+2. 發現的問題列表
+3. 改善建議
+
+請用正體中文回答，以清單格式呈現。""",
+
+        "ui_ux": """以 UI/UX 專家的角度分析這張網頁截圖：
+
+評估項目：
+1. 視覺層次 - 資訊是否清晰分層
+2. 色彩搭配 - 是否協調、對比是否足夠
+3. 排版布局 - 是否整齊、間距是否合理
+4. 互動元素 - 按鈕、連結是否明顯可點擊
+5. 一致性 - 元件風格是否統一
+
+請列出具體問題和改善建議。用正體中文回答。""",
+
+        "accessibility": """以無障礙設計 (WCAG 2.1) 的角度分析這張網頁截圖：
+
+檢查項目：
+1. 色彩對比度是否足夠 (至少 4.5:1)
+2. 文字大小是否易讀 (至少 16px)
+3. 互動元素是否有足夠點擊範圍 (至少 44x44px)
+4. 是否有僅靠顏色傳達資訊的問題
+5. 表單元素是否有明確標籤
+
+請列出具體問題和改善建議。用正體中文回答。""",
+
+        "performance": """分析這張網頁截圖的視覺效能指標：
+
+評估項目：
+1. 內容是否完整載入
+2. 是否有明顯的版面跳動風險
+3. 圖片是否適當優化
+4. 是否有過多視覺元素影響效能
+5. 首屏內容是否有效利用
+
+請列出具體問題和改善建議。用正體中文回答。"""
+    }
+
+    analysis_prompt = prompt or prompts.get(analysis_type, prompts["general"])
+
+    try:
+        from ..ai_engine import AIEngine
+
+        ai = AIEngine()
+
+        # 讀取圖片並轉為 base64
+        with open(image_path, 'rb') as f:
+            image_data = base64.b64encode(f.read()).decode()
+
+        # 使用 Gemini 的多模態功能
+        from google.genai import types
+
+        # 建立圖片內容
+        image_part = types.Part.from_bytes(
+            data=base64.b64decode(image_data),
+            mime_type="image/png"
+        )
+
+        # 呼叫 API
+        response = ai.client.models.generate_content(
+            model=ai.model_name,
+            contents=[analysis_prompt, image_part]
+        )
+
+        result.success = True
+        result.analysis = response.text
+
+        # 解析問題和建議
+        lines = response.text.split('\n')
+        current_section = None
+
+        for line in lines:
+            line = line.strip()
+            if not line:
+                continue
+
+            lower_line = line.lower()
+            if '問題' in line or 'issue' in lower_line or 'problem' in lower_line:
+                current_section = 'issues'
+            elif '建議' in line or '改善' in line or 'recommend' in lower_line or 'suggest' in lower_line:
+                current_section = 'recommendations'
+            elif line.startswith(('-', '*', '•', '1', '2', '3', '4', '5', '6', '7', '8', '9')):
+                # 移除列表符號
+                clean_line = line.lstrip('-*•0123456789. ')
+                if clean_line:
+                    if current_section == 'issues':
+                        result.issues.append(clean_line)
+                    elif current_section == 'recommendations':
+                        result.recommendations.append(clean_line)
+
+    except ImportError:
+        result.error = "AI 引擎未安裝。請執行: pip install google-genai"
+    except Exception as e:
+        result.error = str(e)
+
+    return result
+
+
+def analyze_url(
+    url: str,
+    analysis_type: str = "general",
+    output_path: Optional[str] = None
+) -> VisionResult:
+    """
+    截圖並分析網頁
+
+    Args:
+        url: 要分析的網址
+        analysis_type: 分析類型
+        output_path: 截圖儲存路徑 (可選)
+
+    Returns:
+        VisionResult 物件
+    """
+    result = VisionResult(success=False, url=url)
+
+    # 檢查 agent-browser
+    if not shutil.which('agent-browser'):
+        result.error = "agent-browser 未安裝。請執行: npm install -g agent-browser && agent-browser install"
+        return result
+
+    # 截圖
+    screenshot = take_screenshot(url, output_path)
+    if not screenshot:
+        result.error = "截圖失敗"
+        return result
+
+    result.screenshot_path = screenshot
+
+    # 分析
+    analysis_result = analyze_image(screenshot, analysis_type=analysis_type)
+
+    result.success = analysis_result.success
+    result.analysis = analysis_result.analysis
+    result.issues = analysis_result.issues
+    result.recommendations = analysis_result.recommendations
+    result.error = analysis_result.error
+
+    return result
+
+
+def compare_screenshots(
+    screenshot1: str,
+    screenshot2: str,
+    description1: str = "版本 A",
+    description2: str = "版本 B"
+) -> VisionResult:
+    """
+    比較兩張截圖 (視覺回歸測試)
+
+    Args:
+        screenshot1: 第一張截圖路徑
+        screenshot2: 第二張截圖路徑
+        description1: 第一張截圖描述
+        description2: 第二張截圖描述
+
+    Returns:
+        VisionResult 物件
+    """
+    result = VisionResult(success=False)
+
+    if not Path(screenshot1).exists():
+        result.error = f"截圖不存在: {screenshot1}"
+        return result
+
+    if not Path(screenshot2).exists():
+        result.error = f"截圖不存在: {screenshot2}"
+        return result
+
+    prompt = f"""比較這兩張網頁截圖的差異：
+
+第一張：{description1}
+第二張：{description2}
+
+請分析：
+1. 視覺上的主要差異
+2. 版面布局的變化
+3. 可能的回歸問題
+4. 改善的地方
+
+用正體中文回答，以清單格式呈現。"""
+
+    try:
+        from ..ai_engine import AIEngine
+        from google.genai import types
+
+        ai = AIEngine()
+
+        # 讀取兩張圖片
+        with open(screenshot1, 'rb') as f:
+            img1_data = f.read()
+        with open(screenshot2, 'rb') as f:
+            img2_data = f.read()
+
+        image1_part = types.Part.from_bytes(data=img1_data, mime_type="image/png")
+        image2_part = types.Part.from_bytes(data=img2_data, mime_type="image/png")
+
+        response = ai.client.models.generate_content(
+            model=ai.model_name,
+            contents=[prompt, image1_part, image2_part]
+        )
+
+        result.success = True
+        result.analysis = response.text
+
+    except Exception as e:
+        result.error = str(e)
+
+    return result
+
+
+__all__ = [
+    'VisionResult',
+    'check_dependencies',
+    'take_screenshot',
+    'analyze_image',
+    'analyze_url',
+    'compare_screenshots'
+]

dash_devtools/watch.py

@@ -0,0 +1,266 @@
+"""
+即時監控模式
+
+監控檔案變更並自動執行驗證：
+- 檔案儲存時自動驗證
+- 即時顯示問題
+- 可選自動修復
+"""
+
+import time
+import hashlib
+from pathlib import Path
+from datetime import datetime
+from typing import Dict, Set, Optional
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from rich.layout import Layout
+
+console = Console()
+
+# 監控的檔案類型
+WATCH_EXTENSIONS = {'.js', '.ts', '.jsx', '.tsx', '.py', '.html', '.css', '.scss', '.vue'}
+
+# 忽略的目錄
+IGNORE_DIRS = {
+    'node_modules', '.git', 'dist', 'build', '.next', '__pycache__',
+    'venv', '.venv', '.angular', '.cache', 'coverage'
+}
+
+
+class FileWatcher:
+    """檔案監控器"""
+
+    def __init__(self, project_path: str, auto_fix: bool = False):
+        self.project_path = Path(project_path)
+        self.project_name = self.project_path.name
+        self.auto_fix = auto_fix
+        self.file_hashes: Dict[str, str] = {}
+        self.change_log: list = []
+        self.error_count = 0
+        self.warning_count = 0
+        self.fix_count = 0
+        self.start_time = datetime.now()
+
+    def _get_file_hash(self, file_path: Path) -> Optional[str]:
+        """計算檔案 hash"""
+        try:
+            content = file_path.read_bytes()
+            return hashlib.md5(content).hexdigest()
+        except Exception:
+            return None
+
+    def _scan_files(self) -> Dict[str, str]:
+        """掃描所有監控的檔案"""
+        files = {}
+        for file_path in self.project_path.rglob('*'):
+            if file_path.is_dir():
+                continue
+
+            # 跳過忽略的目錄
+            if any(ignore in file_path.parts for ignore in IGNORE_DIRS):
+                continue
+
+            # 只監控特定類型
+            if file_path.suffix.lower() not in WATCH_EXTENSIONS:
+                continue
+
+            file_hash = self._get_file_hash(file_path)
+            if file_hash:
+                rel_path = str(file_path.relative_to(self.project_path))
+                files[rel_path] = file_hash
+
+        return files
+
+    def _check_changes(self) -> Set[str]:
+        """檢查檔案變更"""
+        current_files = self._scan_files()
+        changed_files = set()
+
+        # 檢查修改和新增的檔案
+        for path, hash_value in current_files.items():
+            if path not in self.file_hashes:
+                changed_files.add(path)
+                self._log_change(path, 'new')
+            elif self.file_hashes[path] != hash_value:
+                changed_files.add(path)
+                self._log_change(path, 'modified')
+
+        # 檢查刪除的檔案
+        for path in self.file_hashes:
+            if path not in current_files:
+                self._log_change(path, 'deleted')
+
+        self.file_hashes = current_files
+        return changed_files
+
+    def _log_change(self, path: str, change_type: str):
+        """記錄變更"""
+        timestamp = datetime.now().strftime('%H:%M:%S')
+        icons = {'new': '+', 'modified': '*', 'deleted': '-'}
+        colors = {'new': 'green', 'modified': 'yellow', 'deleted': 'red'}
+
+        self.change_log.append({
+            'time': timestamp,
+            'path': path,
+            'type': change_type,
+            'icon': icons[change_type],
+            'color': colors[change_type]
+        })
+
+        # 只保留最近 20 筆
+        if len(self.change_log) > 20:
+            self.change_log = self.change_log[-20:]
+
+    def _validate_file(self, file_path: str) -> dict:
+        """驗證單一檔案"""
+        full_path = self.project_path / file_path
+        issues = []
+        warnings = []
+        fixes = []
+
+        try:
+            content = full_path.read_text(encoding='utf-8')
+            lines = content.splitlines()
+
+            # 檢查檔案行數
+            if len(lines) > 500:
+                warnings.append(f'檔案過長 ({len(lines)} 行)')
+
+            # 檢查 console.log (JS/TS)
+            if full_path.suffix in ['.js', '.ts', '.jsx', '.tsx']:
+                for i, line in enumerate(lines, 1):
+                    if 'console.log' in line and '//' not in line.split('console.log')[0]:
+                        warnings.append(f'第 {i} 行: console.log 需移除')
+
+            # 檢查 TODO/FIXME
+            for i, line in enumerate(lines, 1):
+                if 'TODO' in line or 'FIXME' in line:
+                    warnings.append(f'第 {i} 行: 有待處理項目')
+
+            # 檢查 Emoji（禁止在程式碼中使用）
+            import re
+            emoji_pattern = re.compile(
+                "["
+                "\U0001F600-\U0001F64F"
+                "\U0001F300-\U0001F5FF"
+                "\U0001F680-\U0001F6FF"
+                "\U0001F1E0-\U0001F1FF"
+                "]+",
+                flags=re.UNICODE
+            )
+            for i, line in enumerate(lines, 1):
+                if emoji_pattern.search(line):
+                    issues.append(f'第 {i} 行: 程式碼中禁止使用 Emoji')
+
+        except Exception as e:
+            issues.append(f'讀取錯誤: {e}')
+
+        return {
+            'path': file_path,
+            'issues': issues,
+            'warnings': warnings,
+            'fixes': fixes
+        }
+
+    def generate_display(self) -> Panel:
+        """產生顯示畫面"""
+        layout = Layout()
+
+        # 標題
+        elapsed = datetime.now() - self.start_time
+        elapsed_str = f"{int(elapsed.total_seconds() // 60)}:{int(elapsed.total_seconds() % 60):02d}"
+
+        header = Text()
+        header.append(f"  {self.project_name}", style="bold cyan")
+        header.append(f"  [監控中]", style="bold green")
+        header.append(f"  {elapsed_str}", style="dim")
+        if self.auto_fix:
+            header.append("  [自動修復]", style="yellow")
+
+        # 狀態列
+        status = Text()
+        status.append(f"\n  檔案: {len(self.file_hashes)}", style="dim")
+        status.append(f"  |  錯誤: ", style="dim")
+        status.append(f"{self.error_count}", style="red" if self.error_count else "green")
+        status.append(f"  |  警告: ", style="dim")
+        status.append(f"{self.warning_count}", style="yellow" if self.warning_count else "green")
+        if self.fix_count:
+            status.append(f"  |  已修復: ", style="dim")
+            status.append(f"{self.fix_count}", style="cyan")
+
+        # 變更日誌
+        log_text = Text()
+        log_text.append("\n  最近變更:\n", style="dim")
+
+        if self.change_log:
+            for entry in reversed(self.change_log[-8:]):
+                log_text.append(f"    {entry['time']} ", style="dim")
+                log_text.append(f"[{entry['icon']}] ", style=entry['color'])
+                log_text.append(f"{entry['path']}\n", style="white")
+        else:
+            log_text.append("    等待檔案變更...\n", style="dim")
+
+        # 說明
+        footer = Text()
+        footer.append("\n  按 Ctrl+C 停止監控", style="dim")
+
+        content = Text()
+        content.append_text(header)
+        content.append_text(status)
+        content.append_text(log_text)
+        content.append_text(footer)
+
+        return Panel(
+            content,
+            title="[bold]Dash Watch[/bold]",
+            border_style="cyan",
+            padding=(1, 2)
+        )
+
+    def run(self, interval: float = 1.0):
+        """執行監控"""
+        # 初始掃描
+        self.file_hashes = self._scan_files()
+
+        console.print(f"\n[cyan]開始監控 {self.project_name}...[/cyan]")
+        console.print(f"[dim]監控 {len(self.file_hashes)} 個檔案[/dim]\n")
+
+        try:
+            with Live(self.generate_display(), refresh_per_second=2, console=console) as live:
+                while True:
+                    changed_files = self._check_changes()
+
+                    # 驗證變更的檔案
+                    for file_path in changed_files:
+                        result = self._validate_file(file_path)
+
+                        if result['issues']:
+                            self.error_count += len(result['issues'])
+                        if result['warnings']:
+                            self.warning_count += len(result['warnings'])
+
+                    # 更新顯示
+                    live.update(self.generate_display())
+
+                    time.sleep(interval)
+
+        except KeyboardInterrupt:
+            console.print("\n[yellow]監控已停止[/yellow]")
+
+        return {
+            'duration': str(datetime.now() - self.start_time),
+            'files_watched': len(self.file_hashes),
+            'changes': len(self.change_log),
+            'errors': self.error_count,
+            'warnings': self.warning_count
+        }
+
+
+def run_watch(project_path: str, auto_fix: bool = False, interval: float = 1.0) -> dict:
+    """執行監控模式"""
+    watcher = FileWatcher(project_path, auto_fix=auto_fix)
+    return watcher.run(interval=interval)