数据截至 (上游 commit 7803d562546a)
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-96。
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:35 |
| PlatformManager | 管理所有 RuntimeBot,统一启动/停止适配器 | PlatformManager src/langbot/pkg/platform/botmgr.py:523 |
| MessageAggregator | 按会话把多条消息批量/归一化后,add_query 进池 | MessageAggregator src/langbot/pkg/pipeline/aggregator.py:64 |
| QueryPool | 存待处理的 Query,并缓存在途 Query(供插件向后兼容调用) | QueryPool src/langbot/pkg/pipeline/pool.py:114 |
| Controller | 调度 Query 处理,强制全局/单会话并发上限 | Controller src/langbot/pkg/pipeline/controller.py:14 |
| RuntimePipeline | 把 DB 流水线配置物化成运行时阶段链,用责任链执行器跑(支持生成器阶段) | RuntimePipeline src/langbot/pkg/pipeline/pipelinemgr.py:67 |
| PipelineManager | 从 DB 加载各条流水线、注册阶段字典 | PipelineManager src/langbot/pkg/pipeline/pipelinemgr.py:488 |
| ChatMessageHandler | 主 LLM 对话阶段:发插件事件、调 RequestRunner、处理流式/非流式、记遥测、追加历史 | ChatMessageHandler src/langbot/pkg/pipeline/process/handlers/chat.py:48 |
| RequestRunner | 具体「怎么问模型」的执行器(本地 Agent / 各外部工作流) | LocalAgentRunner src/langbot/pkg/provider/runners/localagent.py:159(@runner.runner_class('local-agent')) |
| ToolManager | 聚合四来源工具(原生 / 插件 / 外部 MCP / 技能),供 Runner 调用 | ToolManager src/langbot/pkg/provider/tools/toolmgr.py:26 |
| PluginRuntimeConnector | 通过 stdio/WebSocket 连到插件运行时(langbot-plugin-sdk) | PluginRuntimeConnector src/langbot/pkg/plugin/connector.py:154 |
| BoxService | 沙箱子系统门面:exec、会话、托管进程、技能 CRUD、配额、挂载 | BoxService src/langbot/pkg/box/service.py:102 |
| HTTPController | 建 Quart app、注册路由组、服务 SPA、用 MCP dispatcher 包 ASGI | HTTPController src/langbot/pkg/api/http/controller/main.py:62 |
| LangBotMCPServer | 在 /mcp 暴露一个精选的 agent 面向工具子集 | LangBotMCPServer src/langbot/pkg/api/mcp/server.py:58 |
2.3 主线走一遍(高层,不进代码)
一条消息端到端的旅程(细节见 01):
- 进 —— 某平台的 SDK 回调触发,
src/langbot/pkg/platform/sources/下的适配器把平台专有事件转成 LangBot 的统一消息/事件实体。 - 路由 ——
RuntimeBot套用流水线路由规则,决定:丢弃、推 webhook、还是交给消息聚合器(botmgr.py:475RuntimeBot.run起的适配器循环喂进来的) 。 - 聚合入队 ——
MessageAggregator按会话批量/归一化,add_query把一个Query放进QueryPool(aggregator.py:141/215/230)。 - 调度 ——
Controller在全局并发和单会话并发约束下取出 Query 交给流水线(controller.py:183run→consumer)。 - 跑流水线 ——
RuntimePipeline把该会话配置的阶段物化成一条责任链,逐段执行;责任链支持生成器阶段(某阶段可以yield多个中间结果,分叉出后续执行),这是流式/多轮的基础(pipelinemgr.py:286_execute_from_stage)。 - 对话核心 —— 聊天阶段
ChatMessageHandler发插件事件、调用配置的RequestRunner、处理流式/非流式回复、记遥测、追加对话历史。本地 Agent 循环在此调工具(细节见 03、04)。 - 出 —— 输出阶段把文本/卡片/分片/文件/错误提示,原路经最初那个平台适配器发回去。
注册机制的暗线:流水线的阶段、加载器、runner、适配器都靠装饰器 + 包导入副作用预注册(如
@runner.runner_class('local-agent'))。加新东西时要用对应的预注册机制,别另起一套注册表(见ARCHITECTURE.mdMessage 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:18-24 stage_order):
| 阶段 | 干什么 | 类:行 |
|---|---|---|
| LoadConfigStage | 加载 config.yaml 等配置 | src/langbot/pkg/core/stages/load_config.py:218 |
| 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:55 |
| ShowNotesStage | 打印启动提示 | src/langbot/pkg/core/stages/show_notes.py:13 |
五阶段跑完得到一个 ap,再 await ap.run() 启动平台管理器、查询控制器、HTTP 控制器、遥测/清理循环、插件初始化(boot.py:27-53 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、共享实体、lbpCLI、以及插件运行时(lbp rt)和 Box 运行时(lbp box)。本章及 01–05 只解剖 LangBot 主仓;涉及运行时协议的另一侧代码在那个兄弟仓(见ARCHITECTURE.mdRepository 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.mdRepository 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 定位。
| 主题 | 文件路径 | 符号名 |
|---|---|---|
| 进程入口 shim | main.py | import langbot.__main__ |
| CLI 入口 + 启动交接 | src/langbot/__main__.py | main / main_entry |
| 启动五阶段编排 | src/langbot/pkg/core/boot.py | stage_order(:17)、make_app(:26)、main(:47) |
| 加载配置阶段 | src/langbot/pkg/core/stages/load_config.py | LoadConfigStage |
| 生成密钥阶段 | src/langbot/pkg/core/stages/genkeys.py | GenKeysStage |
| 日志阶段 | src/langbot/pkg/core/stages/setup_logger.py | SetupLoggerStage |
| 构造 Application 阶段 | src/langbot/pkg/core/stages/build_app.py | BuildAppStage |
| 启动提示阶段 | src/langbot/pkg/core/stages/show_notes.py | ShowNotesStage |
| 服务定位器(运行时中心) | src/langbot/pkg/core/app.py | Application(:50)、Application.run(:174) |
| 平台适配器基类落点 | src/langbot/pkg/platform/sources/ | 子类 AbstractMessagePlatformAdapter(SDK) |
| 已配置 bot 运行实例 | src/langbot/pkg/platform/botmgr.py | RuntimeBot(:26)、RuntimeBot.run(:369) |
| 平台管理器 | src/langbot/pkg/platform/botmgr.py | PlatformManager(:402) |
| 消息聚合成 Query | src/langbot/pkg/pipeline/aggregator.py | MessageAggregator(:54)、add_message(:119) |
| 待处理 Query 队列 | src/langbot/pkg/pipeline/pool.py | QueryPool |
| 调度与并发控制 | src/langbot/pkg/pipeline/controller.py | Controller(:12)、consumer(:24)、run(:95) |
| 流水线阶段链执行器 | src/langbot/pkg/pipeline/pipelinemgr.py | RuntimePipeline(:62)、_execute_from_stage(:206) |
| 流水线加载/注册 | src/langbot/pkg/pipeline/pipelinemgr.py | PipelineManager(:390) |
| 主 LLM 对话阶段 | src/langbot/pkg/pipeline/process/handlers/chat.py | ChatMessageHandler(:27) |
| 本地 Agent 执行器 | src/langbot/pkg/provider/runners/localagent.py | LocalAgentRunner(:104) |
| 工具四来源聚合 | src/langbot/pkg/provider/tools/toolmgr.py | ToolManager |
| 外部 MCP 工具加载(客户端) | src/langbot/pkg/provider/tools/loaders/mcp.py | MCP loader |
| 插件运行时连接器 | src/langbot/pkg/plugin/connector.py | PluginRuntimeConnector(:43) |
| Box 沙箱门面 | src/langbot/pkg/box/service.py | BoxService(:42) |
| HTTP/Web + MCP 挂载 | src/langbot/pkg/api/http/controller/main.py | HTTPController(:30) |
| LangBot 自己的 MCP 服务端 | src/langbot/pkg/api/mcp/server.py | LangBotMCPServer(:49) |
| 架构总览(事实核对源) | ARCHITECTURE.md | The Runtime Graph / Message Flow |