super-dev 2.0.0__py3-none-any.whl

super_dev/orchestrator/engine.py

@@ -0,0 +1,958 @@
+"""
+开发：Excellent（11964948@qq.com）
+功能：工作流编排引擎 - 协调 12 阶段工作流（含第 0 阶段）
+作用：管理任务执行、专家调度、质量门禁
+创建时间：2025-12-30
+最后修改：2026-02-24
+"""
+
+import asyncio
+import json
+import traceback
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+try:
+    from rich.console import Console
+    from rich.panel import Panel
+    from rich.table import Table
+    RICH_AVAILABLE = True
+except ImportError:
+    RICH_AVAILABLE = False
+
+from ..config.manager import ConfigManager, get_config_manager
+from ..exceptions import PhaseExecutionError, QualityGateError
+from ..utils import get_logger
+
+
+class Phase(Enum):
+    """工作流阶段"""
+    DISCOVERY = "discovery"
+    INTELLIGENCE = "intelligence"
+    DRAFTING = "drafting"
+    REDTEAM = "redteam"
+    QA = "qa"
+    DELIVERY = "delivery"
+    DEPLOYMENT = "deployment"
+
+
+@dataclass
+class PhaseResult:
+    """阶段执行结果"""
+    phase: Phase
+    success: bool
+    duration: float
+    output: Any = None
+    errors: list = field(default_factory=list)
+    quality_score: float = 0.0
+
+
+@dataclass
+class WorkflowContext:
+    """工作流上下文"""
+    project_dir: Path
+    config: ConfigManager
+    results: dict = field(default_factory=dict)
+    metadata: dict = field(default_factory=dict)
+
+    # 共享数据
+    user_input: dict = field(default_factory=dict)
+    research_data: dict = field(default_factory=dict)
+    documents: dict = field(default_factory=dict)
+    quality_reports: dict = field(default_factory=dict)
+
+
+class WorkflowEngine:
+    """工作流编排引擎"""
+
+    def __init__(self, project_dir: Path | None = None):
+        self.project_dir = Path.cwd() if project_dir is None else project_dir
+        self.config_manager = get_config_manager(self.project_dir)
+        self.console = Console() if RICH_AVAILABLE else None
+        self.logger = get_logger(
+            'workflow_engine',
+            level='INFO',
+            log_file=self.project_dir / 'logs' / 'workflow.log'
+        )
+
+        # 阶段注册表
+        self._phase_handlers: dict[Phase, Callable] = {}
+
+        # 注册默认阶段处理器
+        self._register_default_handlers()
+
+        self.logger.info("工作流引擎初始化完成", extra={'project_dir': str(self.project_dir)})
+
+    def _register_default_handlers(self) -> None:
+        """注册默认阶段处理器"""
+        self._phase_handlers[Phase.DISCOVERY] = self._phase_discovery
+        self._phase_handlers[Phase.INTELLIGENCE] = self._phase_intelligence
+        self._phase_handlers[Phase.DRAFTING] = self._phase_drafting
+        self._phase_handlers[Phase.REDTEAM] = self._phase_redteam
+        self._phase_handlers[Phase.QA] = self._phase_qa
+        self._phase_handlers[Phase.DELIVERY] = self._phase_delivery
+        self._phase_handlers[Phase.DEPLOYMENT] = self._phase_deployment
+
+    def register_phase_handler(self, phase: Phase, handler: Callable) -> None:
+        self._phase_handlers[phase] = handler
+
+    async def run(
+        self,
+        phases: list[Phase] | None = None,
+        context: WorkflowContext | None = None,
+        stop_requested: Callable[[], bool] | None = None,
+    ) -> dict[Phase, PhaseResult]:
+        if context is None:
+            context = WorkflowContext(
+                project_dir=self.project_dir,
+                config=self.config_manager
+            )
+        self._seed_context_user_input(context)
+
+        if phases is None:
+            phases = self._get_phases_from_config()
+
+        results = {}
+        self._print_workflow_start(phases)
+
+        for phase in phases:
+            if stop_requested and stop_requested():
+                self.logger.warning(
+                    f"工作流收到停止请求，在阶段 {phase.value} 开始前终止",
+                    extra={"phase": phase.value}
+                )
+                break
+
+            try:
+                result = await self._run_phase(phase, context)
+                results[phase] = result
+
+                # 红队审查必须通过，避免风险进入后续阶段
+                if phase == Phase.REDTEAM and isinstance(result.output, dict):
+                    if not bool(result.output.get("passed", True)):
+                        reasons = result.output.get("blocking_reasons") or ["红队审查未通过"]
+                        reason_text = "; ".join(str(r) for r in reasons)
+                        quality_error = QualityGateError(
+                            score=float(result.output.get("score", result.quality_score)),
+                            threshold=float(result.output.get("pass_threshold", 70)),
+                            details={"phase": phase.value, "reasons": reasons},
+                        )
+                        result.success = False
+                        result.errors.append(reason_text)
+                        raise quality_error
+
+                # 质量门禁只在 QA 阶段执行，避免前置阶段被全局阈值误杀
+                if phase == Phase.QA and result.quality_score < self.config_manager.config.quality_gate:
+                    self._print_quality_gate_failed(phase, result)
+                    quality_error = QualityGateError(
+                        score=result.quality_score,
+                        threshold=self.config_manager.config.quality_gate,
+                        details={'phase': phase.value}
+                    )
+                    result.success = False
+                    result.errors.append(str(quality_error))
+                    raise quality_error
+
+                self._print_phase_complete(phase, result)
+
+            except QualityGateError as e:
+                self.logger.error(
+                    f"工作流在阶段 {phase.value} 因质量门禁终止",
+                    extra={'error': str(e), 'phase': phase.value}
+                )
+                if phase in results:
+                    results[phase].success = False
+                    if str(e) not in results[phase].errors:
+                        results[phase].errors.append(str(e))
+                break
+
+            except PhaseExecutionError as e:
+                self.logger.error(
+                    f"工作流在阶段 {phase.value} 终止",
+                    extra={'error': str(e), 'phase': phase.value}
+                )
+                results[phase] = PhaseResult(
+                    phase=phase,
+                    success=False,
+                    duration=0.0,
+                    errors=[str(e)]
+                )
+                break
+
+        self._print_workflow_complete(results)
+        self._save_report(results)
+        return results
+
+    def _get_phases_from_config(self) -> list[Phase]:
+        config_phases = self.config_manager.config.phases
+        phases = []
+        phase_map = {
+            "discovery": Phase.DISCOVERY,
+            "intelligence": Phase.INTELLIGENCE,
+            "drafting": Phase.DRAFTING,
+            "redteam": Phase.REDTEAM,
+            "qa": Phase.QA,
+            "delivery": Phase.DELIVERY,
+            "deployment": Phase.DEPLOYMENT,
+        }
+        for p in config_phases:
+            if p in phase_map:
+                phases.append(phase_map[p])
+        return phases
+
+    async def _run_phase(self, phase: Phase, context: WorkflowContext) -> PhaseResult:
+        start_time = datetime.now()
+        phase_name = phase.value.upper()
+
+        self.logger.info(f"开始执行阶段: {phase_name}", extra={'phase': phase_name})
+
+        try:
+            handler = self._phase_handlers.get(phase)
+            if handler is None:
+                raise PhaseExecutionError(
+                    phase=phase_name,
+                    message=f"No handler registered for phase: {phase}",
+                    details={'available_phases': list(self._phase_handlers.keys())}
+                )
+
+            output = await self._execute_handler(handler, context)
+            duration = (datetime.now() - start_time).total_seconds()
+
+            # 兼容自定义处理器直接返回 PhaseResult 的场景
+            if isinstance(output, PhaseResult):
+                result = output
+                if result.phase != phase:
+                    result.phase = phase
+                if result.duration <= 0:
+                    result.duration = duration
+                if result.quality_score <= 0:
+                    result.quality_score = self._calculate_quality_score(phase, context)
+                return result
+
+            quality_score = self._calculate_quality_score(phase, context)
+
+            self.logger.info(
+                f"阶段执行成功: {phase_name}",
+                extra={
+                    'phase': phase_name,
+                    'duration': duration,
+                    'quality_score': quality_score
+                }
+            )
+
+            return PhaseResult(
+                phase=phase,
+                success=True,
+                duration=duration,
+                output=output,
+                quality_score=quality_score
+            )
+
+        except PhaseExecutionError:
+            raise
+        except QualityGateError:
+            raise
+        except Exception as e:
+            duration = (datetime.now() - start_time).total_seconds()
+            error_details = {
+                'error_type': type(e).__name__,
+                'error_message': str(e),
+                'traceback': traceback.format_exc(),
+                'phase': phase_name,
+                'duration': duration
+            }
+            self.logger.error(f"阶段执行失败: {phase_name}", extra=error_details)
+            raise PhaseExecutionError(
+                phase=phase_name,
+                message=f"Phase execution failed: {str(e)}",
+                details=error_details
+            ) from e
+
+    async def _execute_handler(self, handler: Callable, context: WorkflowContext) -> Any:
+        if asyncio.iscoroutinefunction(handler):
+            return await handler(context)
+        else:
+            return handler(context)
+
+    def _calculate_quality_score(self, phase: Phase, context: WorkflowContext) -> float:
+        """使用真实质量评分引擎计算分数"""
+        try:
+            from .quality import QualityScorer
+            configured_name = "project"
+            config_obj = getattr(context, "config", None)
+            if config_obj is not None:
+                # 兼容 WorkflowContext.config 为 ConfigManager 或 ProjectConfig 两种形态
+                manager_cfg = getattr(config_obj, "config", None)
+                if manager_cfg is not None:
+                    configured_name = getattr(manager_cfg, "name", None) or configured_name
+                else:
+                    configured_name = getattr(config_obj, "name", None) or configured_name
+
+            name = str(context.user_input.get("name", configured_name))
+            scorer = QualityScorer(project_dir=self.project_dir, name=name)
+            score = scorer.score_phase(
+                phase_name=phase.value,
+                context_data=context.user_input,
+            )
+            return float(score)
+        except Exception as e:
+            self.logger.warning(f"质量评分失败，使用默认值: {e}")
+            return 75.0
+
+    # ==================== 阶段处理器（真实实现）====================
+
+    async def _phase_discovery(self, context: WorkflowContext) -> Any:
+        """
+        第 0 阶段：需求增强
+        - 解析用户输入的自然语言需求
+        - 注入领域知识库
+        - 联网检索补充背景信息（可选）
+        """
+        from ..creators.requirement_parser import RequirementParser
+        from .knowledge import KnowledgeAugmenter
+
+        user_input = context.user_input
+        description = user_input.get("enriched_description", user_input.get("description", ""))
+        domain = user_input.get("domain", "")
+        offline = user_input.get("offline", False)
+
+        # 1. 解析结构化需求
+        parser = RequirementParser()
+        requirements = parser.parse_requirements(description)
+        scenario = parser.detect_scenario(self.project_dir)
+        context.user_input["scenario"] = scenario
+        context.user_input["requirements"] = requirements
+
+        # 2. 需求知识增强（本地知识库 + 联网检索）
+        try:
+            augmenter = KnowledgeAugmenter(project_dir=self.project_dir, web_enabled=not offline)
+            knowledge_bundle = augmenter.augment(requirement=description, domain=domain)
+            context.research_data["knowledge_bundle"] = knowledge_bundle
+            context.user_input["knowledge_enhanced"] = bool(knowledge_bundle.get("local_knowledge"))
+            context.user_input["web_research"] = bool(knowledge_bundle.get("web_knowledge"))
+            context.user_input["enriched_description"] = knowledge_bundle.get("enriched_requirement", description)
+        except Exception as e:
+            self.logger.warning(f"需求知识增强跳过: {e}")
+            context.user_input["knowledge_enhanced"] = False
+            context.user_input["web_research"] = False
+
+        return {
+            "status": "discovery_complete",
+            "scenario": scenario,
+            "requirements_count": len(requirements),
+            "knowledge_enhanced": context.user_input.get("knowledge_enhanced"),
+            "web_research": context.user_input.get("web_research"),
+        }
+
+    async def _phase_intelligence(self, context: WorkflowContext) -> Any:
+        """
+        第 0.5 阶段：市场情报
+        - 基于需求进行深度联网检索
+        - 竞品分析
+        - 技术趋势调研
+        """
+        description = context.user_input.get(
+            "enriched_description",
+            context.user_input.get("description", ""),
+        )
+        offline = context.user_input.get("offline", False)
+
+        intelligence: dict[str, list[dict[str, str]]] = {
+            "trends": [],
+            "competitors": [],
+            "best_practices": [],
+        }
+
+        if not offline and description:
+            try:
+                # 技术趋势检索
+                trend_results = await self._web_search(f"{description} best practices 2024 2025")
+                if trend_results:
+                    intelligence["trends"] = trend_results[:3]
+
+                # 竞品检索
+                competitor_results = await self._web_search(f"{description} top alternatives tools")
+                if competitor_results:
+                    intelligence["competitors"] = competitor_results[:3]
+
+            except Exception as e:
+                self.logger.info(f"市场情报检索跳过: {e}")
+
+        context.research_data["intelligence"] = intelligence
+
+        return {
+            "status": "intelligence_complete",
+            "trends_count": len(intelligence["trends"]),
+            "competitors_count": len(intelligence["competitors"]),
+        }
+
+    async def _phase_drafting(self, context: WorkflowContext) -> Any:
+        """
+        第 1 阶段：专家协作生成文档
+        - PM 专家：生成 PRD
+        - ARCHITECT 专家：生成架构文档
+        - UI/UX 专家：生成 UI/UX 文档
+        """
+        from .experts import ExpertDispatcher
+
+        user_input = context.user_input
+        name = user_input.get("name", self.config_manager.config.name or "project")
+        description = user_input.get("enriched_description", user_input.get("description", ""))
+        platform = user_input.get("platform", "web")
+        frontend = user_input.get("frontend", "react")
+        backend = user_input.get("backend", "node")
+        domain = user_input.get("domain", "")
+
+        dispatcher = ExpertDispatcher(self.project_dir)
+        result = dispatcher.dispatch_document_generation(
+            name=name,
+            description=description,
+            platform=platform,
+            frontend=frontend,
+            backend=backend,
+            domain=domain,
+        )
+
+        # 保存生成的文档到 output/ 目录
+        output_dir = self.project_dir / "output"
+        output_dir.mkdir(exist_ok=True)
+
+        saved_docs = []
+        for expert_output in result.outputs:
+            doc_path = output_dir / f"{name}-{expert_output.document_type}.md"
+            doc_path.write_text(expert_output.content, encoding="utf-8")
+            saved_docs.append(str(doc_path))
+            context.documents[expert_output.document_type] = expert_output.content
+
+        return {
+            "status": "documents_generated",
+            "documents": saved_docs,
+            "team_score": result.total_score,
+            "summary": result.summary,
+        }
+
+    async def _phase_redteam(self, context: WorkflowContext) -> Any:
+        """
+        第 5 阶段：红队审查
+        - SECURITY 专家：安全审查（注入、XSS、CSRF 等）
+        - 性能审查（N+1、缓存、分页）
+        - 架构审查（可扩展性、可维护性）
+        """
+        from .experts import ExpertDispatcher
+
+        user_input = context.user_input
+        name = user_input.get("name", self.config_manager.config.name or "project")
+        tech_stack = {
+            "platform": user_input.get("platform", "web"),
+            "frontend": user_input.get("frontend", "react"),
+            "backend": user_input.get("backend", "node"),
+            "domain": user_input.get("domain", ""),
+        }
+
+        dispatcher = ExpertDispatcher(self.project_dir)
+        expert_output = dispatcher.dispatch_redteam_review(name=name, tech_stack=tech_stack)
+
+        # 保存红队报告
+        output_dir = self.project_dir / "output"
+        output_dir.mkdir(exist_ok=True)
+        redteam_path = output_dir / f"{name}-redteam.md"
+        redteam_path.write_text(expert_output.content, encoding="utf-8")
+
+        # 保存报告到上下文（供 QA 阶段使用）
+        context.quality_reports["redteam"] = expert_output.metadata
+
+        return {
+            "status": "redteam_complete",
+            "report_path": str(redteam_path),
+            "score": expert_output.quality_score,
+            "passed": expert_output.metadata.get("passed", False),
+            "pass_threshold": expert_output.metadata.get("pass_threshold", 70),
+            "blocking_reasons": expert_output.metadata.get("blocking_reasons", []),
+            "critical_count": expert_output.metadata.get("critical_count", 0),
+            "high_count": expert_output.metadata.get("high_count", 0),
+            "issues": {
+                "security": expert_output.metadata.get("security_issues", []),
+                "performance": expert_output.metadata.get("performance_issues", []),
+                "architecture": expert_output.metadata.get("architecture_issues", []),
+            },
+        }
+
+    async def _phase_qa(self, context: WorkflowContext) -> Any:
+        """
+        第 6 阶段：质量门禁
+        - QA 专家：多维度质量门禁检查
+        - 场景化检查但统一 80+ 通过标准（支持手动覆盖）
+        - 生成详细质量报告
+        """
+        from ..reviewers.redteam import RedTeamReviewer
+        from .experts import ExpertDispatcher
+
+        user_input = context.user_input
+        name = user_input.get("name", self.config_manager.config.name or "project")
+        tech_stack = {
+            "platform": user_input.get("platform", "web"),
+            "frontend": user_input.get("frontend", "react"),
+            "backend": user_input.get("backend", "node"),
+            "domain": user_input.get("domain", ""),
+        }
+        threshold_override = user_input.get("quality_threshold")
+
+        # 重新加载红队报告（如果存在）
+        redteam_report = None
+        try:
+            reviewer = RedTeamReviewer(
+                project_dir=self.project_dir,
+                name=name,
+                tech_stack=tech_stack,
+            )
+            redteam_report = reviewer.review()
+        except Exception as e:
+            self.logger.warning(f"红队报告加载失败，跳过: {e}")
+
+        dispatcher = ExpertDispatcher(self.project_dir)
+        expert_output = dispatcher.dispatch_quality_gate(
+            name=name,
+            tech_stack=tech_stack,
+            redteam_report=redteam_report,
+            threshold_override=threshold_override,
+        )
+
+        # 保存质量门禁报告
+        output_dir = self.project_dir / "output"
+        output_dir.mkdir(exist_ok=True)
+        qg_path = output_dir / f"{name}-quality-gate.md"
+        qg_path.write_text(expert_output.content, encoding="utf-8")
+
+        passed = expert_output.metadata.get("passed", False)
+        if not passed:
+            raise QualityGateError(
+                score=expert_output.quality_score,
+                threshold=threshold_override or 80,
+                details={"phase": "qa", "report_path": str(qg_path)}
+            )
+
+        return {
+            "status": "quality_gate_passed",
+            "score": expert_output.quality_score,
+            "scenario": expert_output.metadata.get("scenario"),
+            "report_path": str(qg_path),
+        }
+
+    async def _phase_delivery(self, context: WorkflowContext) -> Any:
+        """
+        第 7-8 阶段：代码审查指南 + AI 提示词生成
+        - CODE 专家：代码审查指南
+        - CODE 专家：AI 提示词（用户复制给 AI 即可开始开发）
+        """
+        from .experts import ExpertDispatcher
+
+        user_input = context.user_input
+        name = user_input.get("name", self.config_manager.config.name or "project")
+        tech_stack = {
+            "platform": user_input.get("platform", "web"),
+            "frontend": user_input.get("frontend", "react"),
+            "backend": user_input.get("backend", "node"),
+            "domain": user_input.get("domain", ""),
+        }
+
+        dispatcher = ExpertDispatcher(self.project_dir)
+        output_dir = self.project_dir / "output"
+        output_dir.mkdir(exist_ok=True)
+        saved = []
+        step_errors: list[str] = []
+
+        # 代码审查指南
+        try:
+            cr_output = dispatcher.dispatch_code_review(name=name, tech_stack=tech_stack)
+            cr_path = output_dir / f"{name}-code-review.md"
+            cr_path.write_text(cr_output.content, encoding="utf-8")
+            saved.append(str(cr_path))
+        except Exception as e:
+            msg = f"代码审查指南生成失败: {e}"
+            self.logger.error(msg)
+            step_errors.append(msg)
+
+        # AI 提示词
+        try:
+            ai_output = dispatcher.dispatch_ai_prompt(name=name)
+            ai_path = output_dir / f"{name}-ai-prompt.md"
+            ai_path.write_text(ai_output.content, encoding="utf-8")
+            saved.append(str(ai_path))
+        except Exception as e:
+            msg = f"AI 提示词生成失败: {e}"
+            self.logger.error(msg)
+            step_errors.append(msg)
+
+        if step_errors:
+            raise PhaseExecutionError(
+                phase=Phase.DELIVERY.value.upper(),
+                message="Delivery phase failed",
+                details={"errors": step_errors},
+            )
+
+        return {
+            "status": "delivery_complete",
+            "files": saved,
+        }
+
+    async def _phase_deployment(self, context: WorkflowContext) -> Any:
+        """
+        第 9-11 阶段：CI/CD 配置 + 数据库迁移 + 交付包
+        - DEVOPS 专家：生成 5 大 CI/CD 平台配置
+        - DBA 专家：生成 6 种 ORM 数据库迁移脚本
+        - 交付收敛：生成 manifest/report/zip 交付包
+        """
+        from .. import __version__
+        from ..deployers import DeliveryPackager
+        from .experts import ExpertDispatcher
+
+        user_input = context.user_input
+        name = user_input.get("name", self.config_manager.config.name or "project")
+        tech_stack = {
+            "platform": user_input.get("platform", "web"),
+            "frontend": user_input.get("frontend", "react"),
+            "backend": user_input.get("backend", "node"),
+            "domain": user_input.get("domain", ""),
+        }
+        cicd_platform = user_input.get("cicd", "github")
+        orm = user_input.get("orm", self._detect_orm())
+
+        dispatcher = ExpertDispatcher(self.project_dir)
+        output_dir = self.project_dir / "output"
+        output_dir.mkdir(exist_ok=True)
+        saved = []
+        step_errors: list[str] = []
+
+        # CI/CD 配置
+        try:
+            cicd_output = dispatcher.dispatch_cicd(
+                name=name,
+                tech_stack=tech_stack,
+                cicd_platform=cicd_platform,
+            )
+            cicd_path = output_dir / f"{name}-cicd.md"
+            cicd_path.write_text(cicd_output.content, encoding="utf-8")
+            saved.append(str(cicd_path))
+            generated = cicd_output.metadata.get("generated_file_contents", {})
+            saved.extend(self._write_generated_files(generated))
+        except Exception as e:
+            msg = f"CI/CD 配置生成失败: {e}"
+            self.logger.error(msg)
+            step_errors.append(msg)
+
+        # 数据库迁移
+        try:
+            migration_output = dispatcher.dispatch_migration(
+                name=name,
+                tech_stack=tech_stack,
+                orm=orm,
+            )
+            migration_path = output_dir / f"{name}-migration.md"
+            migration_path.write_text(migration_output.content, encoding="utf-8")
+            saved.append(str(migration_path))
+            generated = migration_output.metadata.get("generated_file_contents", {})
+            saved.extend(self._write_generated_files(generated))
+        except Exception as e:
+            msg = f"数据库迁移脚本生成失败: {e}"
+            self.logger.error(msg)
+            step_errors.append(msg)
+
+        # 交付包
+        try:
+            packager = DeliveryPackager(
+                project_dir=self.project_dir,
+                name=name,
+                version=__version__,
+            )
+            delivery_outputs = packager.package(cicd_platform=cicd_platform)
+            saved.append(str(delivery_outputs["manifest_file"]))
+            saved.append(str(delivery_outputs["report_file"]))
+            saved.append(str(delivery_outputs["archive_file"]))
+        except Exception as e:
+            msg = f"交付包生成失败: {e}"
+            self.logger.error(msg)
+            step_errors.append(msg)
+
+        if step_errors:
+            raise PhaseExecutionError(
+                phase=Phase.DEPLOYMENT.value.upper(),
+                message="Deployment phase failed",
+                details={"errors": step_errors},
+            )
+
+        return {
+            "status": "deployment_ready",
+            "cicd_platform": cicd_platform,
+            "orm": orm,
+            "files": saved,
+        }
+
+    # ==================== 联网检索 ====================
+
+    async def _web_search(self, query: str, max_results: int = 5) -> list[dict]:
+        """
+        联网检索（优先使用 DuckDuckGo，自动降级到离线模式）
+
+        中国大陆环境：DuckDuckGo API 通常可访问；
+        如需国内可访问的备选，可配置 TAVILY_API_KEY。
+        """
+        # 优先尝试 Tavily（如配置了 API Key）
+        import os
+        tavily_key = os.environ.get("TAVILY_API_KEY") or os.environ.get("SUPER_DEV_TAVILY_KEY")
+        if tavily_key:
+            try:
+                return await self._search_tavily(query, tavily_key, max_results)
+            except Exception as e:
+                self.logger.debug(f"Tavily 检索失败，降级到 DuckDuckGo: {e}")
+
+        # 降级到 DuckDuckGo（无需 API Key）
+        try:
+            return await self._search_duckduckgo(query, max_results)
+        except Exception as e:
+            self.logger.debug(f"DuckDuckGo 检索失败，进入完全离线模式: {e}")
+            return []
+
+    async def _search_duckduckgo(self, query: str, max_results: int = 5) -> list[dict]:
+        """使用 DuckDuckGo Instant Answer API 检索"""
+        import urllib.parse
+        import urllib.request
+
+        encoded_query = urllib.parse.quote(query)
+        url = f"https://api.duckduckgo.com/?q={encoded_query}&format=json&no_html=1&skip_disambig=1"
+
+        # 在线程池中执行阻塞 IO
+        loop = asyncio.get_event_loop()
+        response_text = await loop.run_in_executor(
+            None,
+            lambda: self._http_get(url, timeout=5)
+        )
+
+        if not response_text:
+            return []
+
+        data = json.loads(response_text)
+        results = []
+
+        # 摘要结果
+        if data.get("Abstract"):
+            results.append({
+                "title": data.get("Heading", query),
+                "snippet": data.get("Abstract", ""),
+                "url": data.get("AbstractURL", ""),
+                "source": "DuckDuckGo",
+            })
+
+        # 相关主题
+        for topic in data.get("RelatedTopics", [])[:max_results - 1]:
+            if isinstance(topic, dict) and topic.get("Text"):
+                results.append({
+                    "title": topic.get("Text", "")[:80],
+                    "snippet": topic.get("Text", ""),
+                    "url": topic.get("FirstURL", ""),
+                    "source": "DuckDuckGo",
+                })
+
+        return results[:max_results]
+
+    async def _search_tavily(self, query: str, api_key: str, max_results: int = 5) -> list[dict]:
+        """使用 Tavily API 进行深度检索"""
+        import json as json_mod
+
+        payload = json_mod.dumps({
+            "api_key": api_key,
+            "query": query,
+            "search_depth": "basic",
+            "max_results": max_results,
+        }).encode("utf-8")
+
+        loop = asyncio.get_event_loop()
+        response_text = await loop.run_in_executor(
+            None,
+            lambda: self._http_post(
+                "https://api.tavily.com/search",
+                payload,
+                headers={"Content-Type": "application/json"},
+                timeout=10,
+            )
+        )
+
+        if not response_text:
+            return []
+
+        data = json.loads(response_text)
+        results = []
+        for item in data.get("results", [])[:max_results]:
+            results.append({
+                "title": item.get("title", ""),
+                "snippet": item.get("content", "")[:300],
+                "url": item.get("url", ""),
+                "source": "Tavily",
+            })
+        return results
+
+    def _http_get(self, url: str, timeout: int = 5) -> str | None:
+        """同步 HTTP GET（在 executor 中执行）"""
+        import urllib.request
+        from urllib.parse import urlparse
+        try:
+            parsed = urlparse(url)
+            if parsed.scheme not in {"http", "https"}:
+                return None
+            req = urllib.request.Request(url, headers={"User-Agent": "super-dev/1.0"})
+            with urllib.request.urlopen(req, timeout=timeout) as resp:  # nosec B310
+                raw: bytes = resp.read()
+                decoded = raw.decode("utf-8", errors="ignore")
+                return str(decoded)
+        except Exception:
+            return None
+
+    def _http_post(self, url: str, data: bytes, headers: dict, timeout: int = 10) -> str | None:
+        """同步 HTTP POST（在 executor 中执行）"""
+        import urllib.request
+        from urllib.parse import urlparse
+        try:
+            parsed = urlparse(url)
+            if parsed.scheme not in {"http", "https"}:
+                return None
+            req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+            with urllib.request.urlopen(req, timeout=timeout) as resp:  # nosec B310
+                raw: bytes = resp.read()
+                decoded = raw.decode("utf-8", errors="ignore")
+                return str(decoded)
+        except Exception:
+            return None
+
+    def _detect_orm(self) -> str:
+        """自动检测项目使用的 ORM"""
+        if (self.project_dir / "prisma").exists():
+            return "prisma"
+        if (self.project_dir / "requirements.txt").exists():
+            req = (self.project_dir / "requirements.txt").read_text(encoding="utf-8", errors="ignore")
+            if "sqlalchemy" in req.lower():
+                return "sqlalchemy"
+            if "django" in req.lower():
+                return "django"
+        if (self.project_dir / "package.json").exists():
+            pkg = (self.project_dir / "package.json").read_text(encoding="utf-8", errors="ignore")
+            if "typeorm" in pkg.lower():
+                return "typeorm"
+            if "sequelize" in pkg.lower():
+                return "sequelize"
+            if "mongoose" in pkg.lower():
+                return "mongoose"
+        return "prisma"
+
+    # ==================== 打印方法 ====================
+
+    def _print_workflow_start(self, phases: list[Phase]) -> None:
+        if self.console:
+            self.console.print(Panel.fit(
+                f"[bold cyan]Super Dev 工作流引擎[/bold cyan]\n\n"
+                f"项目: {self.config_manager.config.name}\n"
+                f"阶段: {len(phases)} 个",
+                title="启动"
+            ))
+
+    def _print_phase_complete(self, phase: Phase, result: PhaseResult) -> None:
+        if self.console:
+            self.console.print(
+                f"[green]✓[/green] {phase.value}: "
+                f"完成 ({result.duration:.1f}s, 质量分: {result.quality_score:.0f})"
+            )
+
+    def _print_phase_failed(self, phase: Phase, result: PhaseResult) -> None:
+        if self.console:
+            self.console.print(
+                f"[red]✗[/red] {phase.value}: "
+                f"失败 ({', '.join(result.errors)})"
+            )
+
+    def _print_quality_gate_failed(self, phase: Phase, result: PhaseResult) -> None:
+        if self.console:
+            gate = self.config_manager.config.quality_gate
+            self.console.print(
+                f"[yellow]⚠[/yellow] {phase.value}: "
+                f"质量分 ({result.quality_score:.0f}) 低于门禁 ({gate})"
+            )
+
+    def _print_workflow_complete(self, results: dict[Phase, PhaseResult]) -> None:
+        if self.console:
+            table = Table(title="工作流执行结果")
+            table.add_column("阶段", style="cyan")
+            table.add_column("状态", style="green")
+            table.add_column("耗时", style="yellow")
+            table.add_column("质量分", style="magenta")
+
+            total_duration = 0.0
+            success_count = 0
+
+            for phase, result in results.items():
+                status = "[green]成功[/green]" if result.success else "[red]失败[/red]"
+                duration = f"{result.duration:.1f}s"
+                quality = f"{result.quality_score:.0f}"
+
+                table.add_row(phase.value, status, duration, quality)
+                total_duration += result.duration
+                if result.success:
+                    success_count += 1
+
+            self.console.print(table)
+            self.console.print(
+                f"\n总计: {success_count}/{len(results)} 成功, "
+                f"总耗时: {total_duration:.1f}s"
+            )
+
+    def _save_report(self, results: dict[Phase, PhaseResult]) -> None:
+        output_dir = self.project_dir / self.config_manager.config.output_dir
+        output_dir.mkdir(exist_ok=True)
+
+        report_path = output_dir / f"workflow_report_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+
+        report_data = {
+            "timestamp": datetime.now().isoformat(),
+            "project": self.config_manager.config.name,
+            "results": {
+                phase.value: {
+                    "success": result.success,
+                    "duration": result.duration,
+                    "quality_score": result.quality_score,
+                    "errors": result.errors
+                }
+                for phase, result in results.items()
+            }
+        }
+
+        with open(report_path, "w", encoding="utf-8") as f:
+            json.dump(report_data, f, indent=2, ensure_ascii=False)
+
+    def _seed_context_user_input(self, context: WorkflowContext) -> None:
+        cfg = self.config_manager.config
+        defaults = {
+            "name": cfg.name or self.project_dir.name,
+            "description": cfg.description,
+            "platform": cfg.platform,
+            "frontend": cfg.frontend,
+            "backend": cfg.backend,
+            "domain": cfg.domain,
+            "cicd": "github",
+            "offline": False,
+        }
+        for key, value in defaults.items():
+            context.user_input.setdefault(key, value)
+
+    def _write_generated_files(self, generated_files: Any) -> list[str]:
+        if not isinstance(generated_files, dict):
+            return []
+        saved_paths: list[str] = []
+        for relative_path, content in generated_files.items():
+            if not isinstance(relative_path, str) or not isinstance(content, str):
+                continue
+            full_path = self.project_dir / relative_path
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+            full_path.write_text(content, encoding="utf-8")
+            saved_paths.append(str(full_path))
+        return saved_paths