flowchart TD
    %% ── 入口 ────────────────────────────────────────────────
    UserMsg(["👤 使用者訊息\n（文字 ± 圖片）"])
    Checkpoint["📌 LangGraph AsyncPostgresSaver\n從 PostgreSQL 恢復對話 Checkpoint\n（多輪上下文自動還原）"]

    %% ── Node 1：意圖分類 ──────────────────────────────────────
    subgraph N1["Node 1 │ classify_intent（LangGraph）"]
        Rewrite["🔄 Query Rewriting\nLLM 將使用者問題改寫成\n檢索效果更佳的獨立查詢\n（消除代詞、補充隱含脈絡）"]
        Intent{"意圖路由\nstate['intent']"}
    end

    %% ── Node 2a：RAG 檢索 ────────────────────────────────────
    subgraph N2A["Node 2a │ rag_retrieve（現代 RAG）"]
        direction TB
        Embed["📐 Embedding\nllama.cpp nomic-embed-text\n改寫後查詢 → 768 維向量"]
        VecSearch["🔍 pgvector 向量搜尋\nIVFFlat cosine similarity\ntop-k = 5 chunks"]
        KeySearch["🔑 全文搜尋\nPostgreSQL tsvector\nBM25-style 關鍵字比對"]
        Fusion["⚗️ Reciprocal Rank Fusion\n合併向量分數 + 關鍵字分數\n重新排名取 top-3"]
        Filter["🎯 Metadata Filter\n依 document_id / 標籤 / 日期\n縮小搜尋範圍（可選）"]
    end

    %% ── Node 2b：MCP 工具 ────────────────────────────────────
    subgraph N2B["Node 2b │ call_cad_tool（MCP）"]
        MCPRoute{"工具選擇\nLLM function-calling\n決定呼叫哪支 MCP"}
        CADMCP["🔧 CAD Tools MCP\nPort 8100\n指令查詢 / 快捷鍵 / 操作步驟"]
        KMMCP["📚 Knowledge MCP\nPort 8101\n領域術語 / 規範查詢"]
        MCPFallbackRAG["可選：MCP 結果不足\n→ 補充 RAG 檢索"]
    end

    %% ── Node 2c：視覺分析 ────────────────────────────────────
    subgraph N2C["Node 2c │ vision_analyze（Multimodal）"]
        VisionLLM["👁️ llama.cpp Qwen2.5-VL:7b\n圖片 Base64 → 視覺描述\n（工程圖件 / 手稿辨識）"]
        VisionRAG["RAG 補充檢索\n以視覺描述為查詢\n取回相關文件知識"]
    end

    %% ── Node 3：生成回答 ─────────────────────────────────────
    subgraph N3["Node 3 │ generate_response"]
        CtxBuild["📋 Context Assembly\n拼裝 Prompt：\n系統提示 + 歷史訊息（來自 Checkpoint）\n+ 檢索段落 / 工具結果 / 視覺描述"]
        LLMGen["🧠 llama.cpp Qwen2.5-VL:7b\nOpenAI 相容 API\n/v1/chat/completions  stream=true"]
        Stream["⚡ SSE 串流輸出\nFastAPI StreamingResponse\n→ Web Browser 逐 token 顯示"]
    end

    %% ── 儲存 ─────────────────────────────────────────────────
    SaveState["💾 LangGraph 儲存 Checkpoint\n完整 AgentState 寫入 PostgreSQL\n（messages / intent / retrieved_docs / tool_results）"]

    %% ── 連線 ────────────────────────────────────────────────
    UserMsg --> Checkpoint
    Checkpoint --> Rewrite
    Rewrite --> Intent

    Intent -- "rag" --> N2A
    Intent -- "cad_tool" --> N2B
    Intent -- "vision" --> N2C
    Intent -- "general\n（直接生成）" --> CtxBuild

    Embed --> VecSearch
    Embed --> KeySearch
    Filter --> VecSearch
    VecSearch --> Fusion
    KeySearch --> Fusion
    Fusion --> CtxBuild

    MCPRoute --> CADMCP
    MCPRoute --> KMMCP
    CADMCP --> MCPFallbackRAG
    KMMCP --> MCPFallbackRAG
    MCPFallbackRAG --> CtxBuild
    CADMCP --> CtxBuild
    KMMCP --> CtxBuild

    VisionLLM --> VisionRAG
    VisionRAG --> CtxBuild

    CtxBuild --> LLMGen
    LLMGen --> Stream
    Stream --> SaveState

    %% ── 樣式 ────────────────────────────────────────────────
    classDef langgraph fill:#dbeafe,stroke:#2563eb,color:#1e3a5f
    classDef llm       fill:#fce7f3,stroke:#db2777,color:#831843
    classDef db        fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef mcp       fill:#fef9c3,stroke:#ca8a04,color:#713f12
    classDef io        fill:#f3e8ff,stroke:#9333ea,color:#581c87
    classDef stream    fill:#ffedd5,stroke:#ea580c,color:#7c2d12

    class Checkpoint,SaveState langgraph
    class Rewrite,CtxBuild langgraph
    class LLMGen,VisionLLM llm
    class Embed,VecSearch,KeySearch,Fusion,Filter db
    class MCPRoute,CADMCP,KMMCP,MCPFallbackRAG mcp
    class UserMsg,Stream io
    class VisionRAG stream