Lian MCP Llm Agent

🚀 Lian-MCP-LLM Agent 系統

本地多專家智能體調度系統 + 工具調用協議管理 + 可擴展知識庫，由 Lian 開發於 2025 年。

🚀 快速開始

本系統由多個層次構成，各層次有不同的功能和使用方式，以下是各層的開發進度和使用說明：

✨ 主要特性

🌟 項目核心

| 頂層：多專家協作與調度 (論文亮點)

• 專家自動生成（Auto - spawn agents）：管理員 LLM 會依據任務自動生成 n 個專家，專家擁有角色標籤（Role），且有生命週期（create → run → exit）。
• 管理員 LLM 的職責：管理員並非執行者，而是調度中心。它接收用戶輸入，分解任務，調度不同專家，路由消息，控制專家的創建與銷燬，最後收斂所有專家的輸出並返回結果。
• 專家間的通信協議（Agent → Agent, Agent → Admin）：需要明確的路由、管理規則。例如請求類型有詢問、協作、評估；數據格式為 JSON schema；ID 標識有 session_id、agent_id；管理員決定每次迭代的動作。

📦 安裝指南

文檔未提及安裝步驟，暫無法提供。

💻 使用示例

基礎用法

工具層 MCP Server 啟動

生產模式：

uv run python ./main.py server
# 自定義地址和端口
uv run python ./main.py server --host 127.0.0.1 --port 8888

交互層 LLM Client 使用

終端客戶端（交互式命令行）：

uv run python ./main.py client

Web UI（Streamlit 網頁界面）：

uv run python ./main.py web

高級用法

文檔未提及高級使用示例，暫無法提供。

📚 詳細文檔

🚀 開發進度

💾 (1) 數據庫層: LianORM --done--

完全自研的輕量級 ORM 系統，採用分層架構設計。

• 核心架構：
  • Schema：基於 FSM 的 SQL 解析器，脫離數據庫提取元數據。
  • Mapper：智能類型轉換系統，支持 JSON/Vector 自動映射。
  • Repository：業務對象 CRUD 的具體實現。
  • Database：封裝連接池與原子操作客戶端。
  • ORM：統一入口與資源管理。
• 📚 文檔中心：
  • LianORM 模塊使用文檔
  • 數據模型 (Models) | 元數據 (Schema) | 類型映射 (Mapper)
  • 倉儲層 (Repository) | 數據庫層 (Database) | 頂層接口 (ORM)
  • 配置說明 (Config)

🔌 (2) 工具層: MCP Server --done--

基於 FastAPI 實現的工具聚合服務器，提供統一的工具發現與調用接口。

• 核心功能：
  • 工具管理：自動發現和加載工具模塊，支持熱重載。
  • RESTful API：提供完整的工具查詢、調用接口。
  • 元數據提取：自動從工具代碼中提取函數簽名、參數類型、文檔說明。
  • 工具分類：
    • file_tool：文件讀寫、複製、移動、刪除等操作。
    • dir_tool：目錄創建、列表、樹形展示、統計信息。
    • web_tool：HTTP 請求、網頁內容提取、HTML/JSON 解析。
• 啟動方式：見上述使用示例。
• 文檔：MCP Server API 文檔 (點擊跳轉)

🤖 (3) 交互層: LLM Client --done-- (等待重構)

LLM 客戶端封裝，支持多種模型提供商與工具調用 (目前測試使用 deepseek - chat)。

• 核心功能：
  • 工具調用：自動集成 MCP Server 工具，支持 function calling。
  • 連續調用：支持工具的多輪連續調用，直到 LLM 返回 TOOL_CALL_END。
  • 對話管理：完整的對話上下文管理和歷史記錄。
  • 雙界面：終端交互式界面 + Streamlit Web UI。
• 使用方式：見上述使用示例。
• Web UI 特性：
  • 📱 左右分欄佈局：左側對話，右側即時日誌。
  • 🎨 美觀的消息氣泡樣式。
  • 📊 可視化工具調用流程。
  • 🔄 即時顯示工具執行進度。
  • 📚 側邊欄顯示所有可用工具。
• 環境配置：需要在 mylib/llm/llm_config.toml 填入 DEEPSEEK_API_KEY 和 MCP Server 地址。

⚙️ (4) 配置層: Config --done--

用於配置加載，已經完備。

• 測試：uv run python ./tests/config.test.py
• 文檔：UserGuide.md (點擊跳轉)

🧠 (5) 智能體層: Agent --pedding--

定義了智能體的基類與核心行為模式。

• 設計哲學：自我認知是一切的起點。每個 Agent 都必須擁有三個核心要素：身份 (Identity)，明確角色定位與能力邊界；目標 (Objectives)，當前任務目標與工作範圍；記憶 (Memory)，短期操作記錄、長期經驗積累與元認知反思。
• 文檔：Agent 設計文檔 (點擊跳轉)

🕹️ (6) 核心層: Core --pedding--

系統的核心樞紐，負責多專家智能體的調度與協作管理。

• 核心職責 (Admin Agent)：
  • 任務編排：接收用戶輸入，分解為可執行的子任務序列。
  • 專家調度：根據任務需求自動生成 (Spawn) 或喚醒特定角色的專家 Agent。
  • 生命週期管理：控制 Agent 的創建、運行與銷燬。
  • 消息路由：管理 Agent 之間以及 Agent 與 Admin 之間的通信協議。
  • 結果收斂：彙總各專家的輸出，生成最終響應。 這是整個系統的“大腦”，實現了論文中提到的多專家協作架構。

🛠️ (7) 工具庫: Kit (原 Utils)

包含了一系列自研的基礎工具庫，為上層模塊提供支持。

• 🎨 終端美化：
  • Printer：基礎彩色打印工具。簡單輕量，開箱即用，適合快速輸出帶顏色的調試信息或日誌，無需複雜配置。
  • Loutput：高級終端輸出庫，支持 ANSI/256 色/真彩色 (RGB 24bit)，提供色彩降級兼容。內置了豐富的顏色映射表和樣式處理器，能夠自動檢測終端色彩支持能力並進行適配，讓終端界面開發像前端一樣優雅。
    • Loutput 使用文檔 | 終端顏色指南 | RGBColor 指南
• 🧩 算法與數據結構：
  • Lstack：封裝的標準棧結構。提供了嚴謹的壓棧、出棧接口，支持迭代器模式，是實現下推自動機和遞歸算法的基礎容器。
    • Lstack 設計文檔 (點擊跳轉)
  • Lfsm：通用有限狀態機 (Finite State Machine) 基類。通過繼承方式定義狀態與轉換規則，邏輯清晰且易於維護，廣泛應用於協議解析和流程控制場景。
    • Lfsm 設計文檔 (點擊跳轉)
  • Lpda：下推自動機 (Pushdown Automaton)，支持嵌套結構解析。結合了有限狀態機與棧的特性，專門用於處理括號匹配、代碼塊解析等具有遞歸特性的語法結構。
    • Lpda 設計文檔 (點擊跳轉)
• 📝 文本處理：
  • Ltokenizer：基於狀態機的通用分詞器基類。支持流式處理和位置追蹤（行號/列號），能夠高效地將原始文本轉換為結構化的 Token 序列，為解析器提供標準輸入。
    • Ltokenizer 設計文檔 (點擊跳轉)
  • Lparser：基於 LPDA 的通用解析器基類，用於構建複雜的語法分析器。提供了靈活的解析鉤子和上下文管理機制，開發者只需關注語法規則的定義，即可快速構建出功能強大的自定義語言解析器。
    • Lparser 設計文檔 (點擊跳轉)
  • Lfind：向量嵌入 (Embedding) 工具封裝，用於知識庫檢索。集成了主流的 Embedding 模型接口，提供了開箱即用的文本向量化和相似度匹配功能，是實現 RAG（檢索增強生成）系統的核心組件。

🎓 學術使用聲明

本項目為 2025 屆畢業設計作品。

⚠️ 重要提醒

• 保護期：2025 年 11 月 10 日 - 2026 年 1 月 19 日
• 在此期間，禁止同校同學使用本項目進行畢業設計
• 禁止任何形式的學術作業提交
• 詳細條款請參閱 LICENSE 文件

🧪 測試與示例

項目包含完整的測試用例，位於 tests/ 目錄下。

• 運行方式：使用 uv 運行測試文件。

uv run python tests/{TEST_FILE_NAME}

• 測試文件列表： | 文件名 | 描述 | 運行命令 | | :------------------------------- | :------------------------------------------------------------------------------------------------ | :--------------------------------------------------- | | config_loader.test.py | 配置加載測試
  測試配置文件的讀取、解析和默認值處理。 | uv run python tests/config_loader.test.py | | lian_orm_schema_parser.test.py | SQL 解析器測試
  測試 SQL 文件解析功能，驗證 Schema 提取的正確性。 | uv run python tests/lian_orm_schema_parser.test.py | | test_sql_complete.py | ORM 完整功能測試
  包含 CRUD、關聯查詢、事務、批量操作等全功能測試，也是最佳的使用教程。 | uv run python tests/test_sql_complete.py | | Loutput.test.py | 終端輸出測試
  展示 Loutput 庫的各種顏色、樣式和特效輸出能力。 | uv run python tests/Loutput.test.py | | psql_connect.test.py | 數據庫連接測試
  測試 PostgreSQL 數據庫的連接狀態，並列出所有公共表。 | uv run python tests/psql_connect.test.py | | rgb_demo.py | RGB 顏色演示
  展示 RGBColor 和 ANSItoRGB 工具的高級色彩處理能力。 | uv run python tests/rgb_demo.py |

🐷 小豬話

開發過程中留下的感悟，其實一直都沒有記錄……丟掉了好多有趣的想法。

• 📅 2025 - 11 - 24：完了完了我的開發習慣疑似有點太極端了，再這麼下去開發不完了呀！
• 📅 2025 - 12 - 02：整個項目的規模已經達到 48 個目錄 144 個文件了……有時候我自己都記不清哪些文件是幹嘛的。lian_orm 我是真喜歡，但目前時間不夠了……只能暫時留著等以後重構。