Research

"""
Multi-Agent Workflow CLI - 混合架構編排器

CLI 是控制中心，Agent 是思考引擎。
- 確定性操作（CLI 做）：目錄建立、檔案寫入、日誌記錄、驗證、狀態追蹤
- 不確定性操作（Agent 做）：分析、思考、產出報告內容
"""

__version__ = "3.1.0"

"""
支援 python -m cli 執行
"""

from cli.dependencies import CLI_DEPENDENCIES, ensure_python_dependencies

ensure_python_dependencies(CLI_DEPENDENCIES)

from cli.main import app

if __name__ == "__main__":
    app()

"""
Config 模組 - 配置與定義

包含：
- schema.py: JSON Schema 定義
- actions.py: Action 描述映射
- stages.py: 階段描述
- perspectives.py: 視角描述
- models.py: Pydantic 資料模型
"""

"""
Action 描述映射 - 定義所有 Action 的描述與格式
"""

from typing import Dict, List, TypedDict


class ActionInfo(TypedDict):
    """Action 資訊"""

    name: str
    description: str
    level: str  # info, warning, error
    format: str  # 格式化字串模板


# ─────────────────────────────────────────────────────────────────────────────
# Action 定義
# ─────────────────────────────────────────────────────────────────────────────

ACTIONS: Dict[str, ActionInfo] = {
    "workflow_init": ActionInfo(
        name="工作流初始化",
        description="開始新的工作流",
        level="info",
        format="🚀 工作流開始: {topic}",
    ),
    "stage_start": ActionInfo(
        name="階段開始",
        description="開始執行新階段",
        level="info",
        format="📋 階段開始: {stage_name} ({stage_id})",
    ),
    "stage_complete": ActionInfo(
        name="階段完成",
        description="階段執行完成",
        level="info",
        format="✅ 階段完成: {stage_id}",
    ),
    "agent_start": ActionInfo(
        name="Agent 開始",
        description="Agent 開始執行任務",
        level="info",
        format="🤖 Agent 開始: {agent_name} ({agent_id})",
    ),
    "agent_complete": ActionInfo(
        name="Agent 完成",
        description="Agent 執行完成",
        level="info",
        format="✅ Agent 完成: {agent_id}",
    ),
    "agent_call_error": ActionInfo(
        name="Agent 錯誤",
        description="Agent 調用失敗",
        level="error",
        format="❌ Agent 錯誤: {agent_id} - {reason}",
    ),
    "file_write": ActionInfo(
        name="檔案寫入",
        description="寫入檔案",
        level="info",
        format="📝 寫入: {path} ({size_bytes} bytes)",
    ),
    "gate_check": ActionInfo(
        name="品質閘門檢查",
        description="執行品質閘門檢查",
        level="info",
        format="🔍 閘門檢查: {stage} - {score}/{threshold}",
    ),
    "gate_failed": ActionInfo(
        name="閘門失敗",
        description="品質閘門檢查失敗",
        level="error",
        format="❌ 閘門失敗: {stage} - {failed_criteria}",
    ),
    "rollback_triggered": ActionInfo(
        name="回退觸發",
        description="觸發智慧回退",
        level="warning",
        format="🔙 回退: {from_stage} → {to_stage} (第 {iteration} 次)",
    ),
    "workflow_complete": ActionInfo(
        name="工作流完成",
        description="工作流執行完成",
        level="info",
        format="🎉 工作流完成: {final_status} ({duration_seconds:.1f}s)",
    ),
    "workflow_error": ActionInfo(
        name="工作流錯誤",
        description="工作流執行錯誤",
        level="error",
        format="❌ 工作流錯誤: {error}",
    ),
    "human_intervention": ActionInfo(
        name="人工介入",
        description="需要人工介入",
        level="warning",
        format="👤 需要人工介入: {reason}",
    ),
}


# ─────────────────────────────────────────────────────────────────────────────
# 便捷函數
# ─────────────────────────────────────────────────────────────────────────────


def get_action_info(action: str) -> ActionInfo | None:
    """取得 Action 資訊"""
    return ACTIONS.get(action)


def format_action(action: str, details: Dict) -> str:
    """格式化 Action 訊息"""
    info = ACTIONS.get(action)
    if not info:
        return f"{action}: {details}"

    try:
        return info["format"].format(**details)
    except KeyError:
        return f"{info['name']}: {details}"


def get_action_level(action: str) -> str:
    """取得 Action 等級"""
    info = ACTIONS.get(action)
    return info["level"] if info else "info"


def list_actions() -> List[str]:
    """列出所有 Action"""
    return list(ACTIONS.keys())


def list_error_actions() -> List[str]:
    """列出所有錯誤類型的 Action"""
    return [action for action, info in ACTIONS.items() if info["level"] == "error"]


def list_warning_actions() -> List[str]:
    """列出所有警告類型的 Action"""
    return [action for action, info in ACTIONS.items() if info["level"] == "warning"]

"""
Pydantic 資料模型 - 定義所有資料結構

包含：
- Agent 相關模型
- 階段相關模型
- 工作流相關模型
- 品質閘門相關模型
"""

from datetime import datetime
from enum import Enum
from typing import Any, Dict, List, Optional

from pydantic import BaseModel, Field


# ─────────────────────────────────────────────────────────────────────────────
# 列舉類型
# ─────────────────────────────────────────────────────────────────────────────


class StageID(str, Enum):
    """階段 ID"""

    RESEARCH = "RESEARCH"
    PLAN = "PLAN"
    TASKS = "TASKS"
    IMPLEMENT = "IMPLEMENT"
    REVIEW = "REVIEW"
    VERIFY = "VERIFY"


class AgentStatus(str, Enum):
    """Agent 狀態"""

    PENDING = "pending"
    RUNNING = "running"
    COMPLETED = "completed"
    FAILED = "failed"


class WorkflowStatus(str, Enum):
    """工作流狀態"""

    INITIALIZED = "initialized"
    RUNNING = "running"
    COMPLETED = "completed"
    FAILED = "failed"
    ROLLBACK = "rollback"
    HUMAN_INTERVENTION = "human_intervention"


class WorkflowMode(str, Enum):
    """工作流模式"""

    QUICK = "quick"  # 快速模式：減少視角數量
    NORMAL = "normal"  # 正常模式
    DEEP = "deep"  # 深度模式：更多視角、更嚴格閘門


# ─────────────────────────────────────────────────────────────────────────────
# Agent 模型
# ─────────────────────────────────────────────────────────────────────────────


class AgentConfig(BaseModel):
    """Agent 配置"""

    id: str = Field(..., description="Agent ID")
    name: str = Field(..., description="Agent 名稱")
    description: Optional[str] = Field(None, description="Agent 描述")
    model: str = Field("sonnet", description="使用的模型")
    perspective: Optional[str] = Field(None, description="視角 ID")


class AgentResponse(BaseModel):
    """Agent 回應"""

    success: bool = Field(..., description="是否成功")
    content: Optional[Dict[str, Any]] = Field(None, description="JSON 回應內容")
    raw_output: Optional[str] = Field(None, description="原始輸出")
    error: Optional[str] = Field(None, description="錯誤訊息")
    tokens_used: Optional[int] = Field(None, description="使用的 token 數")
    duration_seconds: Optional[float] = Field(None, description="執行時間（秒）")


class AgentState(BaseModel):
    """Agent 執行狀態"""

    id: str
    name: str
    description: Optional[str] = None
    model: str = "sonnet"
    status: AgentStatus = AgentStatus.PENDING
    task: Optional[str] = None
    started_at: Optional[datetime] = None
    completed_at: Optional[datetime] = None


# ─────────────────────────────────────────────────────────────────────────────
# 階段模型
# ─────────────────────────────────────────────────────────────────────────────


class StageConfig(BaseModel):
    """階段配置"""

    id: StageID
    name: str
    description: str
    perspectives: List[str] = Field(default_factory=list)
    gate_threshold: float = Field(75.0, description="品質閘門閾值")
    required_outputs: List[str] = Field(default_factory=list)


class StageState(BaseModel):
    """階段狀態"""

    id: StageID
    name: str
    description: str
    index: int = Field(..., description="階段索引 (1-based)")
    total: int = Field(..., description="總階段數")
    status: AgentStatus = AgentStatus.PENDING


class StageResult(BaseModel):
    """階段執行結果"""

    stage_id: StageID
    success: bool
    outputs: Dict[str, str] = Field(default_factory=dict, description="輸出檔案路徑")
    quality_score: Optional[float] = None
    errors: List[str] = Field(default_factory=list)
    duration_seconds: Optional[float] = None


# ─────────────────────────────────────────────────────────────────────────────
# 品質閘門模型
# ─────────────────────────────────────────────────────────────────────────────


class GateCheckResult(BaseModel):
    """品質閘門檢查結果"""

    stage: StageID
    passed: bool
    score: float
    threshold: float
    criteria: Dict[str, bool] = Field(default_factory=dict)
    failed_criteria: List[str] = Field(default_factory=list)
    details: Optional[Dict[str, Any]] = None


class RollbackDecision(BaseModel):
    """回退決策"""

    should_rollback: bool
    from_stage: StageID
    to_stage: StageID
    iteration: int
    reason: str
    require_human: bool = False


# ─────────────────────────────────────────────────────────────────────────────
# 工作流模型
# ─────────────────────────────────────────────────────────────────────────────


class WorkflowConfig(BaseModel):
    """工作流配置"""

    topic: str = Field(..., description="工作流主題/需求描述")
    mode: WorkflowMode = Field(WorkflowMode.NORMAL, description="執行模式")
    start_from: Optional[StageID] = Field(None, description="從指定階段開始")
    skip_stages: List[StageID] = Field(default_factory=list, description="跳過的階段")
    max_iterations: int = Field(10, description="最大迭代次數")


class WorkflowState(BaseModel):
    """工作流狀態"""

    id: str
    topic: str
    status: WorkflowStatus = WorkflowStatus.INITIALIZED
    current_stage: Optional[StageID] = None
    iteration: int = 0
    created_at: datetime = Field(default_factory=datetime.now)
    updated_at: datetime = Field(default_factory=datetime.now)


class WorkflowResult(BaseModel):
    """工作流執行結果"""

    workflow_id: str
    success: bool
    final_status: WorkflowStatus
    quality_score: Optional[float] = None
    stage_results: Dict[str, StageResult] = Field(default_factory=dict)
    total_iterations: int = 0
    duration_seconds: Optional[float] = None
    errors: List[str] = Field(default_factory=list)


# ─────────────────────────────────────────────────────────────────────────────
# 視角模型
# ─────────────────────────────────────────────────────────────────────────────


class PerspectiveConfig(BaseModel):
    """視角配置"""

    id: str = Field(..., description="視角 ID")
    name: str = Field(..., description="視角名稱")
    description: str = Field(..., description="視角描述")
    focus_areas: List[str] = Field(default_factory=list, description="關注領域")
    model: str = Field("sonnet", description="使用的模型")


class PerspectiveReport(BaseModel):
    """視角報告"""

    perspective_id: str
    perspective_name: str
    content: str
    key_findings: List[str] = Field(default_factory=list)
    recommendations: List[str] = Field(default_factory=list)
    concerns: List[str] = Field(default_factory=list)


# ─────────────────────────────────────────────────────────────────────────────
# 輸出格式
# ─────────────────────────────────────────────────────────────────────────────


class CurrentState(BaseModel):
    """即時狀態（current.json 格式）"""

    updated_at: datetime = Field(default_factory=datetime.now)
    workflow: Dict[str, Any]
    stage: Optional[StageState] = None
    agents: List[AgentState] = Field(default_factory=list)
    progress: Dict[str, int] = Field(
        default_factory=lambda: {"agents_completed": 0, "agents_total": 0}
    )

"""
視角配置 - 定義各階段的視角

每個視角代表一個專業角色，負責從特定角度分析問題。
"""

from typing import Dict, List

from .models import PerspectiveConfig, StageID


# ─────────────────────────────────────────────────────────────────────────────
# 視角定義
# ─────────────────────────────────────────────────────────────────────────────

PERSPECTIVES: Dict[str, PerspectiveConfig] = {
    # ───────────────────────────────────────────────────────────────────────
    # RESEARCH 階段視角
    # ───────────────────────────────────────────────────────────────────────
    "architecture": PerspectiveConfig(
        id="architecture",
        name="架構分析師",
        description="分析系統結構、設計模式、技術選型",
        focus_areas=[
            "系統架構",
            "設計模式",
            "技術棧選擇",
            "可擴展性",
            "模組化",
        ],
        model="sonnet",
    ),
    "cognitive": PerspectiveConfig(
        id="cognitive",
        name="認知研究員",
        description="研究使用者心智模型、認知負荷、學習曲線",
        focus_areas=[
            "使用者心智模型",
            "認知負荷",
            "學習曲線",
            "錯誤預防",
            "直覺性",
        ],
        model="sonnet",
    ),
    "workflow": PerspectiveConfig(
        id="workflow",
        name="工作流設計師",
        description="設計操作流程、狀態轉換、錯誤處理",
        focus_areas=[
            "操作流程",
            "狀態管理",
            "錯誤處理",
            "邊界情況",
            "資料流",
        ],
        model="sonnet",
    ),
    "industry": PerspectiveConfig(
        id="industry",
        name="業界實踐專家",
        description="研究業界最佳實踐、競品分析、趨勢",
        focus_areas=[
            "業界標準",
            "最佳實踐",
            "競品分析",
            "技術趨勢",
            "案例研究",
        ],
        model="sonnet",
    ),
    # ───────────────────────────────────────────────────────────────────────
    # PLAN 階段視角
    # ───────────────────────────────────────────────────────────────────────
    "system_architect": PerspectiveConfig(
        id="system_architect",
        name="系統架構師",
        description="設計系統架構、元件關係、介面定義",
        focus_areas=[
            "系統設計",
            "元件劃分",
            "介面定義",
            "依賴管理",
            "部署架構",
        ],
        model="sonnet",
    ),
    "ux_designer": PerspectiveConfig(
        id="ux_designer",
        name="UX 設計師",
        description="設計使用者體驗、互動流程、介面規格",
        focus_areas=[
            "使用者體驗",
            "互動設計",
            "資訊架構",
            "可用性",
            "無障礙",
        ],
        model="sonnet",
    ),
    "security_analyst": PerspectiveConfig(
        id="security_analyst",
        name="安全分析師",
        description="分析安全風險、設計防護措施",
        focus_areas=[
            "威脅模型",
            "安全控制",
            "資料保護",
            "認證授權",
            "合規要求",
        ],
        model="sonnet",
    ),
    "quality_engineer": PerspectiveConfig(
        id="quality_engineer",
        name="品質工程師",
        description="設計測試策略、品質指標、驗收標準",
        focus_areas=[
            "測試策略",
            "品質指標",
            "驗收標準",
            "效能要求",
            "可靠性",
        ],
        model="sonnet",
    ),
    # ───────────────────────────────────────────────────────────────────────
    # TASKS 階段視角
    # ───────────────────────────────────────────────────────────────────────
    "task_decomposer": PerspectiveConfig(
        id="task_decomposer",
        name="任務分解專家",
        description="將計劃分解為可執行的原子任務",
        focus_areas=[
            "任務粒度",
            "完成定義",
            "驗收條件",
            "可測試性",
            "獨立性",
        ],
        model="sonnet",
    ),
    "dependency_analyst": PerspectiveConfig(
        id="dependency_analyst",
        name="依賴分析師",
        description="分析任務依賴、設計執行順序",
        focus_areas=[
            "依賴關係",
            "執行順序",
            "並行機會",
            "瓶頸識別",
            "關鍵路徑",
        ],
        model="sonnet",
    ),
    "test_planner": PerspectiveConfig(
        id="test_planner",
        name="測試規劃師",
        description="為每個任務設計對應的測試",
        focus_areas=[
            "TDD 映射",
            "測試用例",
            "邊界條件",
            "錯誤路徑",
            "整合測試",
        ],
        model="sonnet",
    ),
    "risk_preventor": PerspectiveConfig(
        id="risk_preventor",
        name="風險預防師",
        description="識別任務風險、設計預防措施",
        focus_areas=[
            "風險識別",
            "影響評估",
            "預防措施",
            "回退計劃",
            "監控指標",
        ],
        model="sonnet",
    ),
    # ───────────────────────────────────────────────────────────────────────
    # IMPLEMENT 階段視角
    # ───────────────────────────────────────────────────────────────────────
    "developer": PerspectiveConfig(
        id="developer",
        name="開發者",
        description="實作功能、撰寫程式碼",
        focus_areas=[
            "功能實作",
            "程式碼品質",
            "效能優化",
            "錯誤處理",
            "文件註解",
        ],
        model="sonnet",
    ),
    "tdd_coach": PerspectiveConfig(
        id="tdd_coach",
        name="TDD 教練",
        description="指導測試驅動開發、確保測試覆蓋",
        focus_areas=[
            "測試先行",
            "紅綠重構",
            "測試覆蓋",
            "測試品質",
            "邊界測試",
        ],
        model="sonnet",
    ),
    "reviewer": PerspectiveConfig(
        id="reviewer",
        name="即時審查者",
        description="即時審查程式碼、提供改進建議",
        focus_areas=[
            "程式碼審查",
            "最佳實踐",
            "一致性",
            "可讀性",
            "改進建議",
        ],
        model="sonnet",
    ),
    # ───────────────────────────────────────────────────────────────────────
    # REVIEW 階段視角
    # ───────────────────────────────────────────────────────────────────────
    "code_quality": PerspectiveConfig(
        id="code_quality",
        name="程式碼品質審查員",
        description="審查程式碼品質、一致性、可讀性",
        focus_areas=[
            "程式碼風格",
            "命名規範",
            "結構清晰",
            "重複程式碼",
            "複雜度",
        ],
        model="sonnet",
    ),
    "security": PerspectiveConfig(
        id="security",
        name="安全審查員",
        description="審查安全漏洞、敏感資料處理",
        focus_areas=[
            "注入攻擊",
            "認證授權",
            "資料暴露",
            "加密處理",
            "日誌安全",
        ],
        model="sonnet",
    ),
    "performance": PerspectiveConfig(
        id="performance",
        name="效能審查員",
        description="審查效能問題、資源使用",
        focus_areas=[
            "時間複雜度",
            "空間複雜度",
            "資源洩漏",
            "並發處理",
            "快取策略",
        ],
        model="sonnet",
    ),
    "maintainability": PerspectiveConfig(
        id="maintainability",
        name="可維護性審查員",
        description="審查可維護性、擴展性、文件",
        focus_areas=[
            "模組化",
            "解耦合",
            "文件完整",
            "測試覆蓋",
            "技術債務",
        ],
        model="sonnet",
    ),
    # ───────────────────────────────────────────────────────────────────────
    # VERIFY 階段視角
    # ───────────────────────────────────────────────────────────────────────
    "functional_tester": PerspectiveConfig(
        id="functional_tester",
        name="功能測試員",
        description="驗證功能正確性、邊界情況",
        focus_areas=[
            "功能驗證",
            "邊界測試",
            "錯誤處理",
            "使用者流程",
            "異常情況",
        ],
        model="sonnet",
    ),
    "regression_tester": PerspectiveConfig(
        id="regression_tester",
        name="回歸測試員",
        description="驗證既有功能未受影響",
        focus_areas=[
            "回歸測試",
            "整合測試",
            "相容性",
            "向後相容",
            "副作用",
        ],
        model="sonnet",
    ),
    "acceptance_validator": PerspectiveConfig(
        id="acceptance_validator",
        name="驗收驗證員",
        description="驗證是否符合驗收標準",
        focus_areas=[
            "驗收標準",
            "需求符合",
            "品質達標",
            "文件完整",
            "發布準備",
        ],
        model="sonnet",
    ),
}


# ─────────────────────────────────────────────────────────────────────────────
# 階段視角映射
# ─────────────────────────────────────────────────────────────────────────────

STAGE_PERSPECTIVES: Dict[StageID, List[str]] = {
    StageID.RESEARCH: ["architecture", "cognitive", "workflow", "industry"],
    StageID.PLAN: ["system_architect", "ux_designer", "security_analyst", "quality_engineer"],
    StageID.TASKS: ["task_decomposer", "dependency_analyst", "test_planner", "risk_preventor"],
    StageID.IMPLEMENT: ["developer", "tdd_coach", "reviewer"],
    StageID.REVIEW: ["code_quality", "security", "performance", "maintainability"],
    StageID.VERIFY: ["functional_tester", "regression_tester", "acceptance_validator"],
}

# 快速模式視角（減少數量）
QUICK_MODE_PERSPECTIVES: Dict[StageID, List[str]] = {
    StageID.RESEARCH: ["architecture", "workflow"],
    StageID.PLAN: ["system_architect", "quality_engineer"],
    StageID.TASKS: ["task_decomposer", "dependency_analyst"],
    StageID.IMPLEMENT: ["developer", "reviewer"],
    StageID.REVIEW: ["code_quality", "security"],
    StageID.VERIFY: ["functional_tester", "acceptance_validator"],
}


# ─────────────────────────────────────────────────────────────────────────────
# 便捷函數
# ─────────────────────────────────────────────────────────────────────────────


def get_perspective(perspective_id: str) -> PerspectiveConfig | None:
    """取得視角配置"""
    return PERSPECTIVES.get(perspective_id)


def get_stage_perspectives(
    stage_id: StageID,
    quick_mode: bool = False,
) -> List[PerspectiveConfig]:
    """取得階段的視角列表"""
    if quick_mode:
        perspective_ids = QUICK_MODE_PERSPECTIVES.get(stage_id, [])
    else:
        perspective_ids = STAGE_PERSPECTIVES.get(stage_id, [])

    return [PERSPECTIVES[pid] for pid in perspective_ids if pid in PERSPECTIVES]


def list_all_perspectives() -> List[PerspectiveConfig]:
    """列出所有視角"""
    return list(PERSPECTIVES.values())

"""
JSON Schema 定義 - 定義各種輸出格式的 Schema

用於驗證 Agent 返回的 JSON 格式。
"""

from typing import Any, Dict


# ─────────────────────────────────────────────────────────────────────────────
# 視角報告 Schema
# ─────────────────────────────────────────────────────────────────────────────

PERSPECTIVE_REPORT_SCHEMA: Dict[str, Any] = {
    "type": "object",
    "required": ["perspective_id", "perspective_name", "findings", "recommendations"],
    "properties": {
        "perspective_id": {
            "type": "string",
            "description": "視角 ID",
        },
        "perspective_name": {
            "type": "string",
            "description": "視角名稱",
        },
        "summary": {
            "type": "string",
            "description": "摘要（1-2 句話）",
        },
        "findings": {
            "type": "array",
            "description": "主要發現",
            "items": {
                "type": "object",
                "required": ["title", "description"],
                "properties": {
                    "title": {"type": "string"},
                    "description": {"type": "string"},
                    "importance": {
                        "type": "string",
                        "enum": ["high", "medium", "low"],
                    },
                },
            },
        },
        "recommendations": {
            "type": "array",
            "description": "建議",
            "items": {
                "type": "object",
                "required": ["title", "description"],
                "properties": {
                    "title": {"type": "string"},
                    "description": {"type": "string"},
                    "priority": {
                        "type": "string",
                        "enum": ["must", "should", "could"],
                    },
                },
            },
        },
        "concerns": {
            "type": "array",
            "description": "擔憂或風險",
            "items": {
                "type": "object",
                "required": ["title", "description"],
                "properties": {
                    "title": {"type": "string"},
                    "description": {"type": "string"},
                    "severity": {
                        "type": "string",
                        "enum": ["critical", "high", "medium", "low"],
                    },
                },
            },
        },
    },
}


# ─────────────────────────────────────────────────────────────────────────────
# 階段綜合報告 Schema
# ─────────────────────────────────────────────────────────────────────────────

SYNTHESIS_REPORT_SCHEMA: Dict[str, Any] = {
    "type": "object",
    "required": ["stage_id", "consensus", "key_insights", "action_items"],
    "properties": {
        "stage_id": {
            "type": "string",
            "description": "階段 ID",
        },
        "consensus": {
            "type": "object",
            "description": "共識點",
            "properties": {
                "score": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "共識分數 (0-1)",
                },
                "points": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "共識要點",
                },
            },
        },
        "key_insights": {
            "type": "array",
            "description": "關鍵洞察",
            "items": {
                "type": "object",
                "required": ["insight", "source_perspectives"],
                "properties": {
                    "insight": {"type": "string"},
                    "source_perspectives": {
                        "type": "array",
                        "items": {"type": "string"},
                    },
                    "confidence": {
                        "type": "string",
                        "enum": ["high", "medium", "low"],
                    },
                },
            },
        },
        "conflicts": {
            "type": "array",
            "description": "衝突點",
            "items": {
                "type": "object",
                "required": ["topic", "perspectives"],
                "properties": {
                    "topic": {"type": "string"},
                    "perspectives": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "perspective_id": {"type": "string"},
                                "position": {"type": "string"},
                            },
                        },
                    },
                    "resolution": {"type": "string"},
                },
            },
        },
        "action_items": {
            "type": "array",
            "description": "行動項目",
            "items": {
                "type": "object",
                "required": ["action", "priority"],
                "properties": {
                    "action": {"type": "string"},
                    "priority": {
                        "type": "string",
                        "enum": ["critical", "high", "medium", "low"],
                    },
                    "owner": {"type": "string"},
                },
            },
        },
    },
}


# ─────────────────────────────────────────────────────────────────────────────
# 任務清單 Schema
# ─────────────────────────────────────────────────────────────────────────────

TASKS_SCHEMA: Dict[str, Any] = {
    "type": "object",
    "required": ["tasks"],
    "properties": {
        "metadata": {
            "type": "object",
            "properties": {
                "total_tasks": {"type": "integer"},
                "total_waves": {"type": "integer"},
                "estimated_effort": {"type": "string"},
            },
        },
        "tasks": {
            "type": "array",
            "items": {
                "type": "object",
                "required": ["id", "title", "type"],
                "properties": {
                    "id": {
                        "type": "string",
                        "pattern": "^(T-[A-Z]+-[0-9]+|TEST-[0-9]+|SETUP-[0-9]+)$",
                        "description": "任務 ID (如 T-F-01, TEST-01)",
                    },
                    "title": {"type": "string"},
                    "description": {"type": "string"},
                    "type": {
                        "type": "string",
                        "enum": ["feature", "test", "setup", "config", "docs"],
                    },
                    "wave": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "執行波次",
                    },
                    "depends_on": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "依賴的任務 ID",
                    },
                    "acceptance_criteria": {
                        "type": "array",
                        "items": {"type": "string"},
                    },
                    "test_id": {
                        "type": "string",
                        "description": "對應的測試任務 ID (TDD)",
                    },
                },
            },
        },
    },
}


# ─────────────────────────────────────────────────────────────────────────────
# 審查報告 Schema
# ─────────────────────────────────────────────────────────────────────────────

REVIEW_REPORT_SCHEMA: Dict[str, Any] = {
    "type": "object",
    "required": ["perspective_id", "issues"],
    "properties": {
        "perspective_id": {"type": "string"},
        "perspective_name": {"type": "string"},
        "summary": {"type": "string"},
        "issues": {
            "type": "array",
            "items": {
                "type": "object",
                "required": ["id", "title", "severity", "category"],
                "properties": {
                    "id": {"type": "string"},
                    "title": {"type": "string"},
                    "description": {"type": "string"},
                    "severity": {
                        "type": "string",
                        "enum": ["BLOCKER", "HIGH", "MEDIUM", "LOW", "INFO"],
                    },
                    "category": {
                        "type": "string",
                        "enum": [
                            "bug",
                            "security",
                            "performance",
                            "style",
                            "maintainability",
                            "documentation",
                        ],
                    },
                    "file": {"type": "string"},
                    "line": {"type": "integer"},
                    "suggestion": {"type": "string"},
                },
            },
        },
        "approval": {
            "type": "string",
            "enum": ["approved", "approved_with_comments", "changes_requested"],
        },
    },
}


# ─────────────────────────────────────────────────────────────────────────────
# 驗證結果 Schema
# ─────────────────────────────────────────────────────────────────────────────

VERIFICATION_REPORT_SCHEMA: Dict[str, Any] = {
    "type": "object",
    "required": ["perspective_id", "test_results"],
    "properties": {
        "perspective_id": {"type": "string"},
        "perspective_name": {"type": "string"},
        "summary": {"type": "string"},
        "test_results": {
            "type": "array",
            "items": {
                "type": "object",
                "required": ["test_id", "status"],
                "properties": {
                    "test_id": {"type": "string"},
                    "test_name": {"type": "string"},
                    "status": {
                        "type": "string",
                        "enum": ["passed", "failed", "skipped", "error"],
                    },
                    "details": {"type": "string"},
                    "duration_ms": {"type": "number"},
                },
            },
        },
        "coverage": {
            "type": "object",
            "properties": {
                "line_coverage": {"type": "number"},
                "branch_coverage": {"type": "number"},
                "function_coverage": {"type": "number"},
            },
        },
        "verdict": {
            "type": "string",
            "enum": ["pass", "fail", "conditional"],
        },
    },
}


# ─────────────────────────────────────────────────────────────────────────────
# Schema 映射
# ─────────────────────────────────────────────────────────────────────────────

SCHEMAS: Dict[str, Dict[str, Any]] = {
    "perspective_report": PERSPECTIVE_REPORT_SCHEMA,
    "synthesis_report": SYNTHESIS_REPORT_SCHEMA,
    "tasks": TASKS_SCHEMA,
    "review_report": REVIEW_REPORT_SCHEMA,
    "verification_report": VERIFICATION_REPORT_SCHEMA,
}


def get_schema(schema_name: str) -> Dict[str, Any] | None:
    """取得 Schema"""
    return SCHEMAS.get(schema_name)

"""
階段配置 - 定義各階段的描述與配置

6 個階段：RESEARCH → PLAN → TASKS → IMPLEMENT → REVIEW → VERIFY
"""

from typing import Dict, List

from .models import StageConfig, StageID


# ─────────────────────────────────────────────────────────────────────────────
# 階段定義
# ─────────────────────────────────────────────────────────────────────────────

STAGES: Dict[StageID, StageConfig] = {
    StageID.RESEARCH: StageConfig(
        id=StageID.RESEARCH,
        name="研究階段",
        description="多視角並行研究，收集資訊與洞察",
        perspectives=[
            "architecture",
            "cognitive",
            "workflow",
            "industry",
        ],
        gate_threshold=70.0,
        required_outputs=["synthesis.md"],
    ),
    StageID.PLAN: StageConfig(
        id=StageID.PLAN,
        name="規劃階段",
        description="多視角設計，產出實作計劃",
        perspectives=[
            "system_architect",
            "ux_designer",
            "security_analyst",
            "quality_engineer",
        ],
        gate_threshold=75.0,
        required_outputs=["implementation-plan.md"],
    ),
    StageID.TASKS: StageConfig(
        id=StageID.TASKS,
        name="任務分解階段",
        description="將計劃分解為可執行的任務 DAG",
        perspectives=[
            "task_decomposer",
            "dependency_analyst",
            "test_planner",
            "risk_preventor",
        ],
        gate_threshold=80.0,
        required_outputs=["tasks.yaml"],
    ),
    StageID.IMPLEMENT: StageConfig(
        id=StageID.IMPLEMENT,
        name="實作階段",
        description="TDD 驅動、即時審查、品質守護",
        perspectives=[
            "developer",
            "tdd_coach",
            "reviewer",
        ],
        gate_threshold=80.0,
        required_outputs=["implementation.md"],
    ),
    StageID.REVIEW: StageConfig(
        id=StageID.REVIEW,
        name="審查階段",
        description="多視角程式碼審查，問題分類與優先排序",
        perspectives=[
            "code_quality",
            "security",
            "performance",
            "maintainability",
        ],
        gate_threshold=75.0,
        required_outputs=["review-summary.md"],
    ),
    StageID.VERIFY: StageConfig(
        id=StageID.VERIFY,
        name="驗證階段",
        description="多視角測試驗證，驗收標準確認",
        perspectives=[
            "functional_tester",
            "regression_tester",
            "acceptance_validator",
        ],
        gate_threshold=85.0,
        required_outputs=["verification.md"],
    ),
}

# 階段順序
STAGE_ORDER: List[StageID] = [
    StageID.RESEARCH,
    StageID.PLAN,
    StageID.TASKS,
    StageID.IMPLEMENT,
    StageID.REVIEW,
    StageID.VERIFY,
]

# 階段權重（用於進度計算）
STAGE_WEIGHTS: Dict[StageID, float] = {
    StageID.RESEARCH: 0.15,
    StageID.PLAN: 0.15,
    StageID.TASKS: 0.10,
    StageID.IMPLEMENT: 0.35,
    StageID.REVIEW: 0.15,
    StageID.VERIFY: 0.10,
}


# ─────────────────────────────────────────────────────────────────────────────
# 便捷函數
# ─────────────────────────────────────────────────────────────────────────────


def get_stage(stage_id: StageID) -> StageConfig:
    """取得階段配置"""
    return STAGES[stage_id]


def get_stage_index(stage_id: StageID) -> int:
    """取得階段索引 (1-based)"""
    return STAGE_ORDER.index(stage_id) + 1


def get_next_stage(stage_id: StageID) -> StageID | None:
    """取得下一個階段"""
    idx = STAGE_ORDER.index(stage_id)
    if idx < len(STAGE_ORDER) - 1:
        return STAGE_ORDER[idx + 1]
    return None


def get_prev_stage(stage_id: StageID) -> StageID | None:
    """取得上一個階段"""
    idx = STAGE_ORDER.index(stage_id)
    if idx > 0:
        return STAGE_ORDER[idx - 1]
    return None


def is_final_stage(stage_id: StageID) -> bool:
    """是否為最後階段"""
    return stage_id == STAGE_ORDER[-1]


def get_stage_by_name(name: str) -> StageID | None:
    """根據名稱取得階段 ID"""
    name_upper = name.upper()
    for stage_id in StageID:
        if stage_id.value == name_upper:
            return stage_id
    return None

"""Best-effort runtime dependency bootstrap for portable CLI copies."""

from __future__ import annotations

import importlib
import os
import site
import subprocess
import sys
import sysconfig
import venv
from dataclasses import dataclass
from pathlib import Path
from typing import Iterable


@dataclass(frozen=True)
class PythonDependency:
    import_name: str
    package_name: str


CLI_DEPENDENCIES = [
    PythonDependency('typer', 'typer[all]>=0.9.0'),
    PythonDependency('rich', 'rich>=13.0.0'),
    PythonDependency('pydantic', 'pydantic>=2.0.0'),
    PythonDependency('yaml', 'PyYAML>=6.0'),
]


def ensure_python_dependencies(dependencies: Iterable[PythonDependency]) -> None:
    missing = [dep for dep in dependencies if not _can_import(dep.import_name)]
    if not missing:
        return

    if os.environ.get('MAW_DISABLE_AUTO_INSTALL') == '1':
        names = ', '.join(dep.package_name for dep in missing)
        raise RuntimeError(f'Missing Python dependencies: {names}')

    packages = [dep.package_name for dep in missing]
    install_commands = [
        [sys.executable, '-m', 'pip', 'install', '--quiet', *packages],
        [sys.executable, '-m', 'pip', 'install', '--quiet', '--user', *packages],
    ]

    installed = False
    for command in install_commands:
        try:
            subprocess.run(
                command,
                check=True,
                stdout=subprocess.DEVNULL,
                stderr=subprocess.DEVNULL,
                timeout=180,
            )
            installed = True
            break
        except Exception:
            continue

    if not installed:
        installed = _install_into_managed_venv(packages)

    still_missing = [dep.package_name for dep in missing if not _can_import(dep.import_name)]
    if still_missing:
        joined = ', '.join(still_missing)
        if installed:
            raise RuntimeError(f'Installed dependencies, but imports still failed: {joined}')
        raise RuntimeError(f'Unable to install Python dependencies: {joined}')


def _can_import(import_name: str) -> bool:
    try:
        importlib.import_module(import_name)
        return True
    except ImportError:
        return False


def _install_into_managed_venv(packages: list[str]) -> bool:
    """Install dependencies into a managed user venv for PEP 668 systems."""
    venv_dir = Path(
        os.environ.get(
            'MAW_PYTHON_ENV',
            str(Path.home() / '.cache' / 'multi-agent-workflow' / 'python-env'),
        )
    )

    try:
        if not venv_dir.exists():
            venv.EnvBuilder(with_pip=True, clear=False).create(venv_dir)

        python = venv_dir / ('Scripts/python.exe' if os.name == 'nt' else 'bin/python')
        subprocess.run(
            [str(python), '-m', 'pip', 'install', '--quiet', *packages],
            check=True,
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
            timeout=240,
        )

        purelib = subprocess.check_output(
            [
                str(python),
                '-c',
                'import sysconfig; print(sysconfig.get_paths()["purelib"])',
            ],
            text=True,
        ).strip()
        platlib = subprocess.check_output(
            [
                str(python),
                '-c',
                'import sysconfig; print(sysconfig.get_paths()["platlib"])',
            ],
            text=True,
        ).strip()

        for path in [purelib, platlib, *site.getsitepackages(), sysconfig.get_paths().get('purelib', '')]:
            if path and path not in sys.path:
                sys.path.insert(0, path)
        return True
    except Exception:
        return False

"""
I/O 模組 - 讀寫層

包含：
- memory.py: Memory 讀寫
- logging.py: Action Log
- state.py: 即時狀態追蹤
- report.py: 報告生成
"""

"""
Action Log 模組 - 記錄所有操作

所有操作都以 JSONL 格式記錄到 logs/actions.jsonl

Actions:
- workflow_init: 工作流開始
- stage_start: 階段開始
- agent_start: Agent 開始
- agent_complete: Agent 完成
- agent_call_error: Agent 失敗
- file_write: 寫入檔案
- gate_check: 品質閘門
- gate_failed: 閘門失敗
- rollback_triggered: 觸發回退
- workflow_complete: 完成
"""

import json
import os
from datetime import datetime
from pathlib import Path
from typing import Any, Dict, List, Literal, Optional

from .memory import get_memory


# Action 類型
ActionType = Literal[
    "workflow_init",
    "stage_start",
    "stage_complete",
    "agent_start",
    "agent_complete",
    "agent_call_error",
    "file_write",
    "gate_check",
    "gate_failed",
    "rollback_triggered",
    "workflow_complete",
    "workflow_error",
    "human_intervention",
]


class ActionLogger:
    """Action 日誌記錄器"""

    def __init__(self, workflow_id: str, base_path: Optional[str] = None):
        """
        初始化 Action Logger

        Args:
            workflow_id: 工作流 ID
            base_path: Memory 根目錄
        """
        self.workflow_id = workflow_id
        self.memory = get_memory(base_path)

        workflow_dir = self.memory.get_workflow_dir(workflow_id)
        if workflow_dir:
            self.log_file = workflow_dir / "logs" / "actions.jsonl"
        else:
            # 工作流尚未建立，使用臨時路徑
            self.log_file = self.memory.base_path / "workflows" / workflow_id / "logs" / "actions.jsonl"

        self.log_file.parent.mkdir(parents=True, exist_ok=True)

    def log(
        self,
        action: ActionType,
        details: Optional[Dict[str, Any]] = None,
        level: str = "info",
    ) -> Dict:
        """
        記錄一個 Action

        Args:
            action: Action 類型
            details: 詳細資訊
            level: 日誌等級 (info, warning, error)

        Returns:
            記錄的完整內容
        """
        record = {
            "timestamp": datetime.now().isoformat(),
            "workflow_id": self.workflow_id,
            "action": action,
            "level": level,
            "details": details or {},
        }

        self.memory.append_jsonl(self.log_file, record)
        return record

    # ─────────────────────────────────────────────────────────────────────────
    # 便捷方法
    # ─────────────────────────────────────────────────────────────────────────

    def workflow_init(self, topic: str, config: Optional[Dict] = None) -> Dict:
        """記錄工作流初始化"""
        return self.log(
            "workflow_init",
            {"topic": topic, "config": config or {}},
        )

    def stage_start(
        self,
        stage_id: str,
        stage_name: str,
        perspectives: Optional[List[str]] = None,
    ) -> Dict:
        """記錄階段開始"""
        return self.log(
            "stage_start",
            {
                "stage_id": stage_id,
                "stage_name": stage_name,
                "perspectives": perspectives or [],
            },
        )

    def stage_complete(
        self,
        stage_id: str,
        success: bool,
        duration_seconds: Optional[float] = None,
    ) -> Dict:
        """記錄階段完成"""
        return self.log(
            "stage_complete",
            {
                "stage_id": stage_id,
                "success": success,
                "duration_seconds": duration_seconds,
            },
            level="info" if success else "warning",
        )

    def agent_start(
        self,
        agent_id: str,
        agent_name: str,
        model: str,
        task: str,
    ) -> Dict:
        """記錄 Agent 開始"""
        return self.log(
            "agent_start",
            {
                "agent_id": agent_id,
                "agent_name": agent_name,
                "model": model,
                "task": task,
            },
        )

    def agent_complete(
        self,
        agent_id: str,
        success: bool,
        response_tokens: Optional[int] = None,
        duration_seconds: Optional[float] = None,
    ) -> Dict:
        """記錄 Agent 完成"""
        return self.log(
            "agent_complete",
            {
                "agent_id": agent_id,
                "success": success,
                "response_tokens": response_tokens,
                "duration_seconds": duration_seconds,
            },
            level="info" if success else "warning",
        )

    def agent_call_error(
        self,
        agent_id: str,
        reason: str,
        attempt: int,
        retryable: bool,
    ) -> Dict:
        """記錄 Agent 調用錯誤"""
        return self.log(
            "agent_call_error",
            {
                "agent_id": agent_id,
                "reason": reason,
                "attempt": attempt,
                "retryable": retryable,
            },
            level="error",
        )

    def file_write(self, path: str, size_bytes: int) -> Dict:
        """記錄檔案寫入"""
        return self.log(
            "file_write",
            {"path": path, "size_bytes": size_bytes},
        )

    def gate_check(
        self,
        stage: str,
        passed: bool,
        score: float,
        threshold: float,
    ) -> Dict:
        """記錄品質閘門檢查"""
        return self.log(
            "gate_check",
            {
                "stage": stage,
                "passed": passed,
                "score": score,
                "threshold": threshold,
            },
            level="info" if passed else "warning",
        )

    def gate_failed(self, stage: str, failed_criteria: List[str]) -> Dict:
        """記錄閘門失敗"""
        return self.log(
            "gate_failed",
            {"stage": stage, "failed_criteria": failed_criteria},
            level="error",
        )

    def rollback_triggered(
        self,
        from_stage: str,
        to_stage: str,
        iteration: int,
        reason: str,
    ) -> Dict:
        """記錄回退觸發"""
        return self.log(
            "rollback_triggered",
            {
                "from_stage": from_stage,
                "to_stage": to_stage,
                "iteration": iteration,
                "reason": reason,
            },
            level="warning",
        )

    def workflow_complete(
        self,
        duration_seconds: float,
        final_status: str,
        quality_score: Optional[float] = None,
    ) -> Dict:
        """記錄工作流完成"""
        return self.log(
            "workflow_complete",
            {
                "duration_seconds": duration_seconds,
                "final_status": final_status,
                "quality_score": quality_score,
            },
        )

    def workflow_error(self, error: str, stage: Optional[str] = None) -> Dict:
        """記錄工作流錯誤"""
        return self.log(
            "workflow_error",
            {"error": error, "stage": stage},
            level="error",
        )

    def human_intervention(self, reason: str, context: Optional[Dict] = None) -> Dict:
        """記錄需要人工介入"""
        return self.log(
            "human_intervention",
            {"reason": reason, "context": context or {}},
            level="warning",
        )

    # ─────────────────────────────────────────────────────────────────────────
    # 查詢方法
    # ─────────────────────────────────────────────────────────────────────────

    def get_logs(
        self,
        action_filter: Optional[List[ActionType]] = None,
        level_filter: Optional[List[str]] = None,
        limit: Optional[int] = None,
    ) -> List[Dict]:
        """
        取得日誌記錄

        Args:
            action_filter: 只包含指定的 action 類型
            level_filter: 只包含指定的 level
            limit: 限制返回數量（最新的）

        Returns:
            日誌記錄列表
        """
        records = self.memory.read_jsonl(self.log_file)

        if action_filter:
            records = [r for r in records if r.get("action") in action_filter]

        if level_filter:
            records = [r for r in records if r.get("level") in level_filter]

        if limit:
            records = records[-limit:]

        return records

    def get_errors(self) -> List[Dict]:
        """取得所有錯誤記錄"""
        return self.get_logs(level_filter=["error"])

    def get_stage_logs(self, stage: str) -> List[Dict]:
        """取得指定階段的日誌"""
        records = self.memory.read_jsonl(self.log_file)
        return [
            r
            for r in records
            if r.get("details", {}).get("stage_id", "").upper() == stage.upper()
            or r.get("details", {}).get("stage", "").upper() == stage.upper()
        ]


# 全域 Logger 實例快取
_loggers: Dict[str, ActionLogger] = {}


def get_logger(workflow_id: str, base_path: Optional[str] = None) -> ActionLogger:
    """取得 Action Logger 實例"""
    if workflow_id not in _loggers:
        _loggers[workflow_id] = ActionLogger(workflow_id, base_path)
    return _loggers[workflow_id]

"""
Memory 讀寫模組 - 管理 .claude/memory/ 目錄結構

負責：
- 工作流目錄建立與管理
- YAML/JSON 檔案讀寫
- 路徑解析與驗證
"""

import json
import os
from datetime import datetime
from pathlib import Path
from typing import Any, Dict, List, Optional, Union

from ..dependencies import ensure_python_dependencies, PythonDependency

ensure_python_dependencies([PythonDependency('yaml', 'PyYAML>=6.0')])

import yaml  # type: ignore


class MemoryManager:
    """Memory 目錄管理器"""

    def __init__(self, base_path: Optional[str] = None):
        """
        初始化 Memory 管理器

        Args:
            base_path: Memory 根目錄，預設為 .claude/memory/
        """
        if base_path:
            self.base_path = Path(base_path)
        else:
            self.base_path = Path(".claude/memory")

        self._ensure_base_dirs()

    def _ensure_base_dirs(self) -> None:
        """確保基礎目錄存在"""
        dirs = [
            self.base_path,
            self.base_path / "workflows",
            self.base_path / "research",
            self.base_path / "plans",
            self.base_path / "tasks",
            self.base_path / "implement",
            self.base_path / "review",
            self.base_path / "verify",
        ]
        for d in dirs:
            d.mkdir(parents=True, exist_ok=True)

    # ─────────────────────────────────────────────────────────────────────────
    # 工作流管理
    # ─────────────────────────────────────────────────────────────────────────

    def create_workflow_dir(
        self,
        workflow_id: str,
        topic: str,
        config: Optional[Dict] = None,
    ) -> Path:
        """
        建立工作流目錄結構

        Args:
            workflow_id: 工作流 ID
            topic: 工作流主題
            config: 額外配置

        Returns:
            工作流目錄路徑
        """
        workflow_dir = self.base_path / "workflows" / workflow_id
        workflow_dir.mkdir(parents=True, exist_ok=True)

        # 建立子目錄
        subdirs = ["stages", "agents", "logs", "exports"]
        for subdir in subdirs:
            (workflow_dir / subdir).mkdir(exist_ok=True)

        # 建立 meta.yaml
        meta = {
            "id": workflow_id,
            "topic": topic,
            "status": "initialized",
            "created_at": datetime.now().isoformat(),
            "date": datetime.now().strftime("%Y-%m-%d"),
            "config": config or {},
            "current_stage": None,
            "stages": {},
        }
        self.write_yaml(workflow_dir / "meta.yaml", meta)

        return workflow_dir

    def get_workflow_dir(self, workflow_id: str) -> Optional[Path]:
        """取得工作流目錄"""
        workflow_dir = self.base_path / "workflows" / workflow_id
        if workflow_dir.exists():
            return workflow_dir
        return None

    def list_workflows(self, limit: int = 10) -> List[Dict]:
        """列出所有工作流"""
        workflows_dir = self.base_path / "workflows"
        if not workflows_dir.exists():
            return []

        workflows = []
        for wf_dir in workflows_dir.iterdir():
            if wf_dir.is_dir():
                meta_file = wf_dir / "meta.yaml"
                if meta_file.exists():
                    meta = self.read_yaml(meta_file)
                    if meta:
                        workflows.append(meta)

        # 按日期排序
        workflows.sort(key=lambda x: x.get("created_at", ""), reverse=True)
        return workflows[:limit]

    def get_active_workflow(self) -> Optional[Dict]:
        """取得當前活動的工作流"""
        workflows = self.list_workflows()
        for wf in workflows:
            if wf.get("status") in ["running", "in_progress", "initialized"]:
                return wf
        return workflows[0] if workflows else None

    # ─────────────────────────────────────────────────────────────────────────
    # 階段目錄管理
    # ─────────────────────────────────────────────────────────────────────────

    def create_stage_dir(
        self,
        workflow_id: str,
        stage: str,
    ) -> Path:
        """
        建立階段目錄

        Args:
            workflow_id: 工作流 ID
            stage: 階段名稱

        Returns:
            階段目錄路徑
        """
        workflow_dir = self.get_workflow_dir(workflow_id)
        if not workflow_dir:
            raise FileNotFoundError(f"Workflow not found: {workflow_id}")

        stage_dir = workflow_dir / "stages" / stage.lower()
        stage_dir.mkdir(parents=True, exist_ok=True)

        # 建立子目錄
        (stage_dir / "perspectives").mkdir(exist_ok=True)
        (stage_dir / "summaries").mkdir(exist_ok=True)

        return stage_dir

    def get_stage_dir(self, workflow_id: str, stage: str) -> Optional[Path]:
        """取得階段目錄"""
        workflow_dir = self.get_workflow_dir(workflow_id)
        if not workflow_dir:
            return None

        stage_dir = workflow_dir / "stages" / stage.lower()
        if stage_dir.exists():
            return stage_dir
        return None

    # ─────────────────────────────────────────────────────────────────────────
    # 檔案讀寫
    # ─────────────────────────────────────────────────────────────────────────

    def read_yaml(self, path: Union[str, Path]) -> Optional[Dict]:
        """讀取 YAML 檔案"""
        path = Path(path)
        if not path.exists():
            return None

        try:
            with open(path, "r", encoding="utf-8") as f:
                return yaml.safe_load(f) or {}
        except Exception:
            return None

    def write_yaml(self, path: Union[str, Path], data: Dict) -> bool:
        """寫入 YAML 檔案"""
        path = Path(path)
        path.parent.mkdir(parents=True, exist_ok=True)

        try:
            with open(path, "w", encoding="utf-8") as f:
                yaml.dump(
                    data,
                    f,
                    allow_unicode=True,
                    default_flow_style=False,
                    sort_keys=False,
                )
            return True
        except Exception:
            return False

    def read_json(self, path: Union[str, Path]) -> Optional[Dict]:
        """讀取 JSON 檔案"""
        path = Path(path)
        if not path.exists():
            return None

        try:
            with open(path, "r", encoding="utf-8") as f:
                return json.load(f)
        except Exception:
            return None

    def write_json(self, path: Union[str, Path], data: Dict) -> bool:
        """寫入 JSON 檔案"""
        path = Path(path)
        path.parent.mkdir(parents=True, exist_ok=True)

        try:
            with open(path, "w", encoding="utf-8") as f:
                json.dump(data, f, ensure_ascii=False, indent=2)
            return True
        except Exception:
            return False

    def read_text(self, path: Union[str, Path]) -> Optional[str]:
        """讀取文字檔案"""
        path = Path(path)
        if not path.exists():
            return None

        try:
            with open(path, "r", encoding="utf-8") as f:
                return f.read()
        except Exception:
            return None

    def write_text(self, path: Union[str, Path], content: str) -> bool:
        """寫入文字檔案"""
        path = Path(path)
        path.parent.mkdir(parents=True, exist_ok=True)

        try:
            with open(path, "w", encoding="utf-8") as f:
                f.write(content)
            return True
        except Exception:
            return False

    def append_jsonl(self, path: Union[str, Path], data: Dict) -> bool:
        """追加 JSONL 記錄"""
        path = Path(path)
        path.parent.mkdir(parents=True, exist_ok=True)

        try:
            with open(path, "a", encoding="utf-8") as f:
                f.write(json.dumps(data, ensure_ascii=False) + "\n")
            return True
        except Exception:
            return False

    def read_jsonl(self, path: Union[str, Path]) -> List[Dict]:
        """讀取 JSONL 檔案"""
        path = Path(path)
        if not path.exists():
            return []

        records = []
        try:
            with open(path, "r", encoding="utf-8") as f:
                for line in f:
                    line = line.strip()
                    if line:
                        records.append(json.loads(line))
        except Exception:
            pass

        return records

    # ─────────────────────────────────────────────────────────────────────────
    # 工作流狀態更新
    # ─────────────────────────────────────────────────────────────────────────

    def update_workflow_meta(
        self,
        workflow_id: str,
        updates: Dict[str, Any],
    ) -> bool:
        """更新工作流 meta.yaml"""
        workflow_dir = self.get_workflow_dir(workflow_id)
        if not workflow_dir:
            return False

        meta_file = workflow_dir / "meta.yaml"
        meta = self.read_yaml(meta_file) or {}
        meta.update(updates)
        meta["updated_at"] = datetime.now().isoformat()

        return self.write_yaml(meta_file, meta)

    def update_stage_status(
        self,
        workflow_id: str,
        stage: str,
        status: str,
        details: Optional[Dict] = None,
    ) -> bool:
        """更新階段狀態"""
        workflow_dir = self.get_workflow_dir(workflow_id)
        if not workflow_dir:
            return False

        meta_file = workflow_dir / "meta.yaml"
        meta = self.read_yaml(meta_file) or {}

        if "stages" not in meta:
            meta["stages"] = {}

        meta["stages"][stage.lower()] = {
            "status": status,
            "updated_at": datetime.now().isoformat(),
            **(details or {}),
        }

        if status == "running":
            meta["current_stage"] = stage.upper()
            meta["status"] = "running"

        return self.write_yaml(meta_file, meta)


# 全域實例
_memory: Optional[MemoryManager] = None


def get_memory(base_path: Optional[str] = None) -> MemoryManager:
    """取得全域 Memory 管理器實例"""
    global _memory
    if _memory is None or base_path:
        _memory = MemoryManager(base_path)
    return _memory