系列首篇。本篇不深入任何一个子系统，目标是给你一张地图：LangBot 要解决什么问题、整体怎么分层、用了哪些技术、有哪些贯穿始终的设计原则。后续每一篇都能在这张地图上对号入座。

一、它到底是个什么东西

一句话：LangBot 是一个开源的、LLM 原生的即时通讯机器人开发平台。

把这句话拆开看，正好对应它的三块核心职责：

  1. 即时通讯（IM）——对接全球主流 IM 平台（QQ、微信全家桶、Discord、Telegram、飞书、Slack、钉钉……18+ 个适配器），把它们五花八门的消息格式归一成统一模型。
  2. LLM 原生——内置 Agent、RAG、MCP、工具调用（Function-Calling）等大模型应用能力，通过 LiteLLM 统一接入 100+ 模型。
  3. 平台（Platform）——不是一个写死的机器人，而是一套可配置、可扩展、带完整 Web 管理面板和丰富 API 的开发平台，面向 toC 和 toB 两类场景。

关键认知：LangBot 几乎所有操作都能在 Web 前端完成，并且对外暴露了 HTTP API 和 MCP 工具——它从设计之初就是「给人用」和「给 Agent 用」并重的。

二、技术栈一览

层 技术 说明
语言/依赖 Python >=3.11,<4.0，uv 管理 版本号写在 pyproject.toml
后端框架 Quart（Flask 的异步版） HTTP API 与预构建的 Web UI 都由它在 http://127.0.0.1:5300 提供
前端 Vite + React Router 7 + shadcn/ui + Tailwind，pnpm 管理 注意：不是 Next.js，dev 脚本就是 vite
持久化 SQLAlchemy（async）+ Alembic 一套脚本同时支持 SQLite（默认零配置）和 PostgreSQL
插件/沙箱 独立进程 + RPC 插件 Runtime 和 Box 沙箱都跑在 LangBot 进程之外

pyproject.toml 里有两个值得记住的钉子：

name = "langbot"
version = "4.10.4"
requires-python = ">=3.11,<4.0"
# ...
    "langbot-plugin==0.4.6",   # 插件 SDK/Runtime 来自独立仓库，这里精确钉版本

langbot-plugin 这个依赖是个伏笔——它指向一个独立的代码仓库 langbot-plugin-sdk，插件系统的 SDK、CLI（lbp）、Runtime 全在那边。这个「把插件运行时拆出去」的决定，第六、七篇会展开讲。

三、分层全景

LangBot 的后端代码全在 src/langbot/pkg/ 下，目录划分基本就是子系统划分。把它们按职责摆开：

flowchart TB
    subgraph platform["① Platform 平台层 · pkg/platform"]
        ADP["18+ 适配器<br>sources/*"]
        RB["RuntimeBot<br>事件监听 + 路由"]
    end

    subgraph pipeline["② Pipeline 流水线 · pkg/pipeline"]
        POOL["QueryPool"]
        CTRL["Controller<br>并发消费"]
        STAGES["12 个 Stage 责任链"]
    end

    subgraph provider["③ Provider 能力层 · pkg/provider"]
        MM["ModelManager<br>LLM/Embedding/Rerank"]
        TM["ToolManager<br>Native/Plugin/MCP/Skill"]
    end

    subgraph ext["④ 扩展子系统（独立进程）"]
        PLG["pkg/plugin<br>插件桥"]
        BOX["pkg/box<br>代码沙箱"]
    end

    subgraph data["⑤ 数据与服务"]
        PER["pkg/persistence<br>ORM + 迁移"]
        RAG["pkg/rag + pkg/vector"]
        API["pkg/api<br>HTTP + MCP"]
    end

    CORE["pkg/core<br>启动 / Application / 任务管理"]

    platform --> pipeline
    pipeline <--> provider
    provider <--> ext
    pipeline <--> data
    CORE -.组装并托管.-> platform
    CORE -.-> pipeline
    CORE -.-> provider
    CORE -.-> data

逐块速览（每块都有专篇）：