flowchart TB
    subgraph Client["客戶端"]
        CLI["CLI 指令 app agent/gateway"]
        TG["Telegram 機器人"]
    end
    
    subgraph Core["核心系統"]
        main["main.go 命令分發"]
        agent["Agent 實例 pkg/agent"]
        session["會話管理 pkg/session"]
    end
    
    subgraph LLM["LLM 層"]
        provider["Provider 適配器 pkg/providers"]
        models["OpenAI / DeepSeek / MiniMax / Ollama"]
    end
    
    subgraph Tools["工具層"]
        registry["工具註冊表 pkg/tools"]
        sandbox["沙盒安全 Sandbox"]
        fs["檔案操作 read/write/edit"]
        shell["命令執行 exec"]
        web["網路搜尋 web_search"]
    end
    
    subgraph Workspace["工作區"]
        config["config.json"]
        files["IDENTITY.md / AGENT.md / SOUL.md / USER.md"]
        sessions["sessions/ 對話歷史"]
    end
    
    CLI --> main
    TG --> main
    main --> agent
    agent --> session
    agent --> provider
    agent --> registry
    agent --> files
    
    provider --> models
    registry --> sandbox
    registry --> fs
    registry --> shell
    registry --> web
    
    session --> sessions
    sandbox --> config

flowchart TD
    start(["開始對話"]) --> load_config[載入配置]
    load_config --> build_context[建構系統提示詞]
    build_context --> load_history[載入對話歷史]
    load_history --> build_messages[組裝訊息列表]
    build_messages --> compress{"上下文需要壓縮?"}
    compress -->|是| compress_ctx[壓縮上下文]
    compress -->|否| next
    compress_ctx --> next
    next --> llm_call[呼叫 LLM]
    llm_call --> has_response{AI 有回覆?}
    has_response -->|文字| output_text[輸出文字回覆]
    has_response -->|無| check_tools
    output_text --> check_tools
    check_tools{AI 請求工具呼叫?}
    check_tools -->|是| parse_args[解析工具參數]
    parse_args --> execute_tool[執行工具]
    execute_tool --> tool_result[返回工具結果]
    tool_result --> add_result[將結果加入訊息]
    add_result --> check_iter{"已達最大迭代次數?"}
    check_iter -->|否| llm_call
    check_iter -->|是| max_iter[輸出達到上限訊息]
    check_tools -->|否| no_tool
    no_tool{有文字回覆?}
    no_tool -->|是| save_history
    no_tool -->|否| check_iter
    max_iter --> save_history
    save_history[保存對話歷史] --> finish(["結束"])

sequenceDiagram
    participant U as 使用者
    participant A as Agent
    participant R as ToolRegistry
    participant T as Tool
    participant S as Sandbox
    
    U->>A: 使用者輸入
    A->>R: 執行工具 (name, args)
    R->>S: 檢查路徑安全性
    S-->>R: 安全路徑
    R->>T: 調用工具 Execute()
    
    rect rgb(240, 248, 255)
    note right of T: 工具執行區塊
    T->>T: 執行實際操作 (讀寫檔案/執行命令)
    end
    
    alt 執行成功
        T-->>R: ToolResult{ForLLM: "結果", IsError: false}
    else 執行失敗
        T-->>R: ToolResult{ForLLM: "錯誤訊息", IsError: true}
    end
    
    R-->>A: 返回工具結果
    A->>A: 將結果加入對話歷史
    
    alt 需要更多工具
        A->>A: 繼續下一輪 LLM 呼叫
    else 完成
        A-->>U: 輸出最終回覆
    end

flowchart LR
    subgraph New["新會話"]
        N1["建立會話管理器"] --> N2{"session.json 是否存在"}
        N2 -->|"否"| N3["返回空歷史"]
        N3 --> N4["新建會話"]
    end

    subgraph Exist["已有會話"]
        E1["載入會話管理器"] --> E2{"session.json 是否存在"}
        E2 -->|"是"| E3["讀取 JSON 檔案"]
        E3 --> E4["反序列化為訊息列表"]
    end

    subgraph Compress["上下文壓縮"]
        C1{"訊息數量 gt 12"}
        C1 -->|"是"| C2["保留系統訊息"]
        C2 --> C3["保留最近 10 條"]
        C3 --> C4["丟棄中間部分"]
        C1 -->|"否"| C5["不進行壓縮"]
    end

    subgraph Save["保存會話"]
        S1["序列化訊息為 JSON"] --> S2["寫入 session.json"]
    end

    N4 --> Compress
    E4 --> Compress
    C4 --> Save
    C5 --> Save

flowchart TD
    input["使用者輸入"] --> length{"長度 gt 10000"}
    length -->|"是"| truncate["截斷到 10000"]
    length -->|"否"| sanitize["開始過濾"]
    truncate --> sanitize

    sanitize --> injection{"含注入關鍵字"}
    injection -->|"是"| mark["標記為 FILTERED"]
    injection -->|"否"| xss

    mark --> xss
    xss{"含 script 標籤"}
    xss -->|"是"| escape_html["轉義 HTML"]
    xss -->|"否"| template

    escape_html --> template
    template{"含模板語法"}
    template -->|"是"| escape_template["轉義模板語法"]
    template -->|"否"| bracket

    escape_template --> bracket
    bracket{"含方括號"}
    bracket -->|"是"| escape_bracket["轉義方括號"]
    bracket -->|"否"| wrap

    escape_bracket --> wrap
    wrap["Markdown code block 包裝"] --> output["輸出結果"]