跳到主要内容

LangBot 是什么 + 全景与阅读地图

30 秒导读: LangBot 是一个开源、生产级的「把大模型/Agent 接到聊天软件」的平台。你写好一个 AI 机器人，它负责把这个机器人同时上架到 Discord、Telegram、Slack、微信、QQ、飞书、钉钉等十几个平台;一个进程内就包办了 HTTP 服务、Web 管理面板、各平台协议适配、消息流水线、插件、知识库(RAG)、沙箱和 MCP。本章讲大盘——它是什么、整体怎么转、有哪些部件、以及后面 01–05 章各讲什么。

1. 这是什么(零基础也能懂)​

一句话定义: LangBot 是一个生产级 IM(即时通讯)机器人平台——它站在「大模型」和「聊天软件」中间,把前者接到后者上去。

它解决谁的什么问题。 假设你想做一个客服机器人:用 DeepSeek 或 GPT 回答问题,还要能查你的知识库。麻烦在于——你的用户分散在很多个聊天平台:有人用微信,有人用 Discord,公司内部用飞书/钉钉。每个平台的接入协议、消息格式、鉴权方式都不一样。

如果自己从零做,你要为每个平台写一遍「收消息 → 调模型 → 发回去」,还要各自处理限流、权限、敏感词、多轮上下文、掉线重连……LangBot 把这些一次性做完:你只配置「用哪个模型、接哪些平台、走什么流程」,它负责剩下的脏活。

它能做什么(核心能力):

  • 多平台接入 —— 一套代码适配 Discord / Telegram / Slack / LINE / QQ / 微信 / 企业微信 / 飞书 / 钉钉 / KOOK / Matrix / 邮件等(见 README 的 Supported Platforms 表)。
  • AI 对话与 Agent —— 多轮对话、工具调用(tool calling)、多模态、流式输出;内置 RAG 知识库,并能对接 Dify / Coze / n8n / Langflow 等外部工作流。
  • 生产特性 —— 访问控制、限流、敏感词过滤、监控、异常处理。
  • 可视化管理 —— 浏览器里的 Web 面板配置一切,不用手改 YAML。
  • 可扩展 —— 插件生态 + 组件扩展 + MCP 协议支持。

用起来什么样。 最小启动就是一行命令(README「One-Line Launch」):

uvx langbot
# 然后打开 http://localhost:5300 —— 在 Web 面板里配模型、接平台、建流水线

一个进程起来后,它自己就是一个 HTTP 服务(默认 :5300)、带一个 React 写的 Web 管理面板、并同时挂着你配置的那些平台适配器。

一句话直觉/类比: 把 LangBot 想成一台多制式的信号中继站。左边接了十几种「制式」不同的聊天网络(每种一根适配器天线),右边接了大模型和工具;中间是一条可配置的流水线,负责把进来的每条消息按你定的规则处理后再原路发回。你只调「用哪根天线、走哪条流水线」,不碰底层协议。

事实核对:name = "langbot"、version = "4.10.4"、description = "Production-grade platform for building agentic IM bots",见 pyproject.toml:2-4。依赖群也印证了它的定位——各 IM SDK(discord-py、python-telegram-bot、slack-sdk、lark-oapi、dingtalk-stream、line-bot-sdk、matrix-nio…)、模型 SDK(openai、anthropic、ollama、dashscope…)、向量库(chromadb、qdrant-client、pymilvus)、以及自家的 langbot-plugin==0.4.6,见 pyproject.toml:7-95。

2. 顶层全景(它大概怎么转)​

本节给一张主线骨架图 + 各部件职责表 + 主线走一遍。只讲大盘,不进单个机制的代码(细节留给 01–05 章)。

2.1 主线骨架:Runtime Graph​

ARCHITECTURE.md 明确说「最有用的心智模型是这张图」(见 ARCHITECTURE.md 的 The Runtime Graph 一节)。它就是一条消息从平台进来、到回复出去的主干道。

怎么读这张图: 从上到下是一条入站消息的处理顺序;每个方框是一个长生命周期部件,箭头是「交给下一棒」。左侧标注了这一步大概在做什么。

          ┌─────────────────────────┐
 平台事件 │  平台适配器 (sources/*)  │  把 Discord/微信/… 的原始事件
   ─────► │   AbstractAdapter        │  翻译成统一的消息/事件实体
          └────────────┬────────────┘
                       ▼
          ┌─────────────────────────┐
 每个 bot │  RuntimeBot (botmgr)     │  套用路由规则:丢弃 / 推 webhook /
 一个实例 │                          │  交给聚合器
          └────────────┬────────────┘
                       ▼
          ┌─────────────────────────┐
 攒一攒   │  MessageAggregator       │  按会话批量/归一化,组装成一个 Query
          └────────────┬────────────┘
                       ▼
          ┌─────────────────────────┐
 排队     │  QueryPool               │  待处理 Query 的队列 + 在途缓存
          └────────────┬────────────┘
                       ▼
          ┌─────────────────────────┐
 调度     │  Controller              │  受全局并发 + 单会话并发约束地取 Query
          └────────────┬────────────┘
                       ▼
          ┌─────────────────────────┐
 跑流程   │  RuntimePipeline         │  把 DB 里的流水线配置物化成一条
          │  → PipelineStage 责任链  │  「阶段责任链」,逐段处理(支持生成器分叉)
          └────────────┬────────────┘
                       ▼
   ┌───────────────────────────────────────────────┐
   │  RequestRunner / ToolManager /                 │  聊天阶段:发插件事件、
   │  PluginRuntimeConnector / BoxService           │  跑 Agent 循环、调工具
   └────────────────────┬──────────────────────────┘
                        ▼
              原路经适配器把回复发回平台

HTTP/Web 面板和 MCP 是平行的入口,它们不走上面这条消息主干,而是直接调同一套 service 层:

HTTP 客户端 / Web UI ─► Quart 路由组 ─► api/http/service/* ─► Application 管理器 / 持久化 / 运行时连接器
MCP 客户端           ─► /mcp 挂载点  ─► api/mcp/server.py 里的工具 ─► 同一套 service 层

2.2 部件一句话职责​

下表是上图各方框的职责和落点。所有部件都是长生命周期的,统一挂在 Application 这个「服务定位器」上(见 §2.4)。

部件干什么(一句话)类 / 文件:行
平台适配器把某个平台的原始事件翻译成统一消息/事件实体src/langbot/pkg/platform/sources/*,基类来自 SDK AbstractMessagePlatformAdapter
RuntimeBot一个已配置 bot 的运行实例;套路由规则、记事件、推 webhook、管适配器生命周期RuntimeBot src/langbot/pkg/platform/botmgr.py:26
PlatformManager管理所有 RuntimeBot,统一启动/停止适配器PlatformManager src/langbot/pkg/platform/botmgr.py:402
MessageAggregator按会话把多条消息批量/归一化后,add_query 进池MessageAggregator src/langbot/pkg/pipeline/aggregator.py:54
QueryPool存待处理的 Query,并缓存在途 Query(供插件向后兼容调用)QueryPool src/langbot/pkg/pipeline/pool.py:13
Controller调度 Query 处理,强制全局/单会话并发上限Controller src/langbot/pkg/pipeline/controller.py:12
RuntimePipeline把 DB 流水线配置物化成运行时阶段链,用责任链执行器跑(支持生成器阶段)RuntimePipeline src/langbot/pkg/pipeline/pipelinemgr.py:62
PipelineManager从 DB 加载各条流水线、注册阶段字典PipelineManager src/langbot/pkg/pipeline/pipelinemgr.py:390
ChatMessageHandler主 LLM 对话阶段:发插件事件、调 RequestRunner、处理流式/非流式、记遥测、追加历史ChatMessageHandler src/langbot/pkg/pipeline/process/handlers/chat.py:27
RequestRunner具体「怎么问模型」的执行器(本地 Agent / 各外部工作流)LocalAgentRunner src/langbot/pkg/provider/runners/localagent.py:104(@runner.runner_class('local-agent'))
ToolManager聚合四来源工具(原生 / 插件 / 外部 MCP / 技能),供 Runner 调用ToolManager src/langbot/pkg/provider/tools/toolmgr.py:22
PluginRuntimeConnector通过 stdio/WebSocket 连到插件运行时(langbot-plugin-sdk)PluginRuntimeConnector src/langbot/pkg/plugin/connector.py:43
BoxService沙箱子系统门面:exec、会话、托管进程、技能 CRUD、配额、挂载BoxService src/langbot/pkg/box/service.py:42
HTTPController建 Quart app、注册路由组、服务 SPA、用 MCP dispatcher 包 ASGIHTTPController src/langbot/pkg/api/http/controller/main.py:30
LangBotMCPServer在 /mcp 暴露一个精选的 agent 面向工具子集LangBotMCPServer src/langbot/pkg/api/mcp/server.py:49

2.3 主线走一遍(高层,不进代码)​

一条消息端到端的旅程(细节见 01):

  1. 进 —— 某平台的 SDK 回调触发,src/langbot/pkg/platform/sources/ 下的适配器把平台专有事件转成 LangBot 的统一消息/事件实体。
  2. 路由 —— RuntimeBot 套用流水线路由规则,决定:丢弃、推 webhook、还是交给消息聚合器(botmgr.py:369 RuntimeBot.run 起的适配器循环喂进来的)。
  3. 聚合入队 —— MessageAggregator 按会话批量/归一化,add_query 把一个 Query 放进 QueryPool(aggregator.py:141/215/230)。
  4. 调度 —— Controller 在全局并发和单会话并发约束下取出 Query 交给流水线(controller.py:95 run → consumer)。
  5. 跑流水线 —— RuntimePipeline 把该会话配置的阶段物化成一条责任链,逐段执行;责任链支持生成器阶段(某阶段可以 yield 多个中间结果,分叉出后续执行),这是流式/多轮的基础(pipelinemgr.py:206 _execute_from_stage)。
  6. 对话核心 —— 聊天阶段 ChatMessageHandler 发插件事件、调用配置的 RequestRunner、处理流式/非流式回复、记遥测、追加对话历史。本地 Agent 循环在此调工具(细节见 03、04)。
  7. 出 —— 输出阶段把文本/卡片/分片/文件/错误提示,原路经最初那个平台适配器发回去。

注册机制的暗线:流水线的阶段、加载器、runner、适配器都靠装饰器 + 包导入副作用预注册(如 @runner.runner_class('local-agent'))。加新东西时要用对应的预注册机制,别另起一套注册表(见 ARCHITECTURE.md Message Flow 末段)。

2.4 一个进程,一个 Application​

启动只有五步。 入口很薄:main.py → langbot.__main__.main() 解析 --standalone-runtime/--standalone-box/--debug、查依赖、按需生成配置文件(src/langbot/__main__.py),再调 src/langbot/pkg/core/boot.py::main。真正的启动骨架是 boot.py 里按顺序跑的五个阶段(boot.py:17-23 stage_order):

阶段干什么类:行
LoadConfigStage加载 config.yaml 等配置src/langbot/pkg/core/stages/load_config.py:107
GenKeysStage生成缺失的密钥src/langbot/pkg/core/stages/genkeys.py:9
SetupLoggerStage建日志系统src/langbot/pkg/core/stages/setup_logger.py:36
BuildAppStage构造 Application——把所有管理器/服务/运行时连接器/控制器接线到位src/langbot/pkg/core/stages/build_app.py:45
ShowNotesStage打印启动提示src/langbot/pkg/core/stages/show_notes.py:14

五阶段跑完得到一个 ap,再 await ap.run() 启动平台管理器、查询控制器、HTTP 控制器、遥测/清理循环、插件初始化(boot.py:26-44 make_app,app.py:174-201 Application.run)。

Application 是「服务定位器」。 ARCHITECTURE.md 坦承这是当前的架构中心,「不算优雅,但就是它」:几乎每个子系统都拿到 ap: Application,通过它互相协作。Application 类里就是一长串长生命周期管理器的声明——platform_mgr、pipeline_mgr、ctrl、query_pool、msg_aggregator、tool_mgr、plugin_connector、box_service、mcp_service、model_mgr、rag_mgr、persistence_mgr 等等(见 app.py:50-166 class Application 的字段)。

# 摘自 src/langbot/pkg/core/app.py:60-112(节选,示意其「服务定位器」形态)
class Application:
    platform_mgr: im_mgr.PlatformManager = None      # 平台层
    tool_mgr: llm_tool_mgr.ToolManager = None        # 工具聚合
    box_service: box_service_module.BoxService = None # 沙箱
    plugin_connector: plugin_connector.PluginRuntimeConnector = None  # 插件运行时
    query_pool: pool.QueryPool = None                # 待处理 Query 队列
    msg_aggregator: message_aggregator.MessageAggregator = None
    ctrl: controller.Controller = None               # 调度
    pipeline_mgr: pipelinemgr.PipelineManager = None # 流水线

跨仓边界(重要,读源码前先知道):LangBot 不是单仓系统。langbot-plugin-sdk(发布为 langbot-plugin,在 pyproject.toml 里 pin 成 ==0.4.6)是独立仓库,提供插件开发 API、共享实体、lbp CLI、以及插件运行时(lbp rt)和 Box 运行时(lbp box)。本章及 01–05 只解剖 LangBot 主仓;涉及运行时协议的另一侧代码在那个兄弟仓(见 ARCHITECTURE.md Repository Boundary)。

3. 阅读地图(01–05 各讲什么、按什么顺序读)​

本组文档由浅入深拆成 6 章。建议顺序就是编号顺序——它正好沿着 §2.1 那张 Runtime Graph 从左到右走一遍,再拐进扩展面。

主线(强烈建议按序)

  • 本章 index.md —— 大盘:是什么、整体怎么转、部件职责、启动五阶段与 Application、代码地图。先读我。
  • 01-message-lifecycle.md —— 一条消息的旅程:从平台事件到进入流水线。放大 §2.1 图的前半段:适配器 → RuntimeBot 路由 → MessageAggregator 聚合 → QueryPool → Controller 调度。回答「消息怎么从平台变成一个待处理 Query,又怎么被取出」。
  • 02-pipeline-engine.md —— 流水线引擎:配置驱动的责任链 + 生成器分叉执行。放大中段:RuntimePipeline 怎么把 DB 配置物化成阶段链,责任链执行器怎么处理「某阶段返回生成器」的分叉(_execute_from_stage)。这是理解流式与多阶段的钥匙。
  • 03-local-agent-loop.md —— 本地 Agent 循环:工具调用、流式、模型回退。放大对话核心:LocalAgentRunner 怎么组织「模型 ↔ 工具」多轮循环、流式输出、以及模型回退(fallback)。

扩展面(可按需跳读)

  • 04-tool-aggregation.md —— 工具从哪来:四来源聚合与调用路由。ToolManager 如何把原生工具 / 插件工具 / 外部 MCP / 技能四个来源聚合成统一工具集,以及一次调用怎么路由回正确的来源。
  • 05-extensibility-and-surfaces.md —— 扩展性与 Agent 面向的对外表面。三块:插件运行时(PluginRuntimeConnector)、Box 沙箱(BoxService)、以及 LangBot 自己的 MCP 服务器(/mcp,LangBotMCPServer)。注意区分:LangBot 既是 MCP 客户端(连外部 MCP 取工具,见 04),又是 MCP 服务端(在 /mcp 暴露自己给 agent,见 05)——两个不同的面。

建议路径: 想懂「消息怎么流」→ 读 01→02→03;想懂「Agent 能力从哪来、怎么被外部驱动」→ 读 04→05。两条线都以本章的 Runtime Graph 为地基。

4. 边界与局限(本章范围内的诚实交代)​

  • 本章只讲大盘。 各机制的真实代码走读、数据结构、算法都在 01–05,本章刻意不深入。
  • Application 是服务定位器,不是依赖注入。 ARCHITECTURE.md 自己承认这「不优雅」;好处是子系统间协作简单,代价是耦合到一个巨型上下文对象(app.py:50 起的大量字段,含若干标了 # deprecated 的旧配置管理器)。
  • 跨仓依赖是硬边界。 插件/Box 的运行时实现不在本仓;MessageChain、Image、At 等平台实体也来自 SDK 而非本仓。要改运行时协议,必须同时动 langbot-plugin-sdk(见 ARCHITECTURE.md Repository Boundary / Box Runtime and Skills)。
  • MCP 的两个面易混。 「LangBot 连出去的外部 MCP 工具」(客户端,src/langbot/pkg/provider/tools/loaders/mcp.py)和「LangBot 自己在 /mcp 暴露的服务」(服务端,src/langbot/pkg/api/mcp/server.py)是不同的东西,ARCHITECTURE.md 专门警告不要混。

5. 代码地图(顶层跳转表)​

从本章直接跳进源码的关键落点。行号以 sourceCommit 为准;行号漂移时优先用符号名 grep 定位。

主题文件路径符号名
进程入口 shimmain.pyimport langbot.__main__
CLI 入口 + 启动交接src/langbot/__main__.pymain / main_entry
启动五阶段编排src/langbot/pkg/core/boot.pystage_order(:17)、make_app(:26)、main(:47)
加载配置阶段src/langbot/pkg/core/stages/load_config.pyLoadConfigStage
生成密钥阶段src/langbot/pkg/core/stages/genkeys.pyGenKeysStage
日志阶段src/langbot/pkg/core/stages/setup_logger.pySetupLoggerStage
构造 Application 阶段src/langbot/pkg/core/stages/build_app.pyBuildAppStage
启动提示阶段src/langbot/pkg/core/stages/show_notes.pyShowNotesStage
服务定位器(运行时中心)src/langbot/pkg/core/app.pyApplication(:50)、Application.run(:174)
平台适配器基类落点src/langbot/pkg/platform/sources/子类 AbstractMessagePlatformAdapter(SDK)
已配置 bot 运行实例src/langbot/pkg/platform/botmgr.pyRuntimeBot(:26)、RuntimeBot.run(:369)
平台管理器src/langbot/pkg/platform/botmgr.pyPlatformManager(:402)
消息聚合成 Querysrc/langbot/pkg/pipeline/aggregator.pyMessageAggregator(:54)、add_message(:119)
待处理 Query 队列src/langbot/pkg/pipeline/pool.pyQueryPool
调度与并发控制src/langbot/pkg/pipeline/controller.pyController(:12)、consumer(:24)、run(:95)
流水线阶段链执行器src/langbot/pkg/pipeline/pipelinemgr.pyRuntimePipeline(:62)、_execute_from_stage(:206)
流水线加载/注册src/langbot/pkg/pipeline/pipelinemgr.pyPipelineManager(:390)
主 LLM 对话阶段src/langbot/pkg/pipeline/process/handlers/chat.pyChatMessageHandler(:27)
本地 Agent 执行器src/langbot/pkg/provider/runners/localagent.pyLocalAgentRunner(:104)
工具四来源聚合src/langbot/pkg/provider/tools/toolmgr.pyToolManager
外部 MCP 工具加载(客户端)src/langbot/pkg/provider/tools/loaders/mcp.pyMCP loader
插件运行时连接器src/langbot/pkg/plugin/connector.pyPluginRuntimeConnector(:43)
Box 沙箱门面src/langbot/pkg/box/service.pyBoxService(:42)
HTTP/Web + MCP 挂载src/langbot/pkg/api/http/controller/main.pyHTTPController(:30)
LangBot 自己的 MCP 服务端src/langbot/pkg/api/mcp/server.pyLangBotMCPServer(:49)
架构总览(事实核对源)ARCHITECTURE.mdThe Runtime Graph / Message Flow