AstrBot — 架构与原理
30 秒导读： AstrBot 是一个开源的「多平台聊天机器人 + Agent 平台」。你把它接到 QQ / 微信 / 飞书 / Telegram / Slack 等十几个聊天软件上，它就能在那里用大模型跟人对话、调用工具、跑 Agent。本组文档讲清楚:一条消 息进来后，它怎么一步步变成一条带 AI 能力的回复。
1. 这是什么(零基础也能懂)
一句话定义: AstrBot 是一个把「大模型 Agent」装进「主流聊天软件」的中间层——它在一边连接 QQ、微信、飞书、Telegram 这些 IM 平台,在另一边连接 OpenAI、Anthropic、Gemini 这些大模型,中间用一条统一的消息流水线把两者粘起来。
解决什么问题 / 给谁用:
假设你想做一个「在 QQ 群里能聊天、能查资料、能记住你是谁的 AI 助手」。直接做的话,你要分别去啃 QQ 的协议、微信的协议、每个大模型厂商的 SDK,还要自己写「被 @ 了才回复」「群聊白名单」「多轮记忆」这些通用逻辑。AstrBot 把这些全做好了,你只管配置和写插件。
它的典型用户:
| 用户 | 拿它干嘛 |
|---|---|
| 个人玩家 | 部署一个 QQ/微信 AI 伴侣、角色扮演机器人 |
| 开发者 | 写插件扩展功能,或接入自己的 Agent 平台(Dify / Coze) |
| 团队/企业 | 智能客服、企业知识库问答、自动化助手 |
它能做什么(功能):
- 接入 18 个 IM 平台(QQ、企业微信、飞书、钉钉、Telegram、Slack、Discord……见
astrbot/core/platform/sources/)。 - 接入 20+ 模型提供商(OpenAI、Anthropic、Gemini、各家国产模型,见
astrbot/core/provider/sources/)。 - 本地 Agent:工具调用(function calling)、多模态、MCP、网页搜 索、知识库、人格、自动上下文压缩。
- Agent 沙箱:在隔离环境里安全执行代码、shell。
- 1000+ 社区插件,一键安装。
- 自带 WebUI 管理面板 + Web ChatUI。
用起来什么样: 一条命令起服务,然后在 WebUI 里配模型、连平台:
uv tool install astrbot --python 3.12
astrbot init # 首次初始化
astrbot run # 启动,默认在 http://localhost:6185 开 WebUI
(命令出自 README.md 的 Quick Start;入口在 main.py 的 main_async。)
一句话直觉/类比: 把 AstrBot 想成一个邮局总局。各个 IM 平台是不同国家的邮政系统(信封格式各不相同),各个大模型是不同的「专家顾问」。邮局总局做的事:把各国寄来的信统一拆成标准内部信件(事件),在内部走一条标准化的处理流水线(检查、安全、找谁处理),需要时请专家顾问出主意(调 LLM/Agent),最后按收件人所在国的格式重新封装寄回去。
2. 顶层全景(它大概怎么转)
AstrBot 的运行可以拆成「三段一循环」:平台适配器把外部消息转成内部事件 → 事件总线把事件派发给 流水线 → 流水线的核心阶段把请求交给 Agent / 插件 → 结果回到平台发出去。
外部 IM 平台 AstrBot 内部 大模型 / 工具
┌──────────┐ ┌──────────┐
│ QQ/微信/ │ 原始消息 ┌─────────────┐ │ OpenAI │
│ 飞书/TG/ │ ─────────► │ Platform │ AstrMessageEvent │ Claude │
│ Slack ... │ │ 适配器(转换) │ ───┐ │ Gemini.. │
└──────────┘ └─────────────┘ │ └────▲─────┘
▲ ▼ │
│ ┌──────────────┐ │
│ 回复(转回平台格式) │ 事件总线 │ event_queue │
│ │ EventBus │ │
│ └──────┬───────┘ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ 流水线 Pipeline │ │
│ │ (9 个阶段,洋葱模型) │ │
│ │ 唤醒→白名单→安全→ │ │
│ │ 处理(Agent/插件)→ │── LLM 请求 ─┘
└──────────────────────────│ 装饰→发送 │
MessageChain └─────────────────────┘
怎么读这张图: 从左上「收到消息」开始顺时针走一圈,回到左下「发出回复」。中间那个「流水线」是全系统的主干,所有消息都要从它走一遍。
部件一句话职责:
| 部件 | 干什么 | 在哪个文件 |
|---|---|---|
| 启动器 / 生命周期 | 初始化所有管理器,启动事件总线和各平台 | astrbot/core/core_lifecycle.py(AstrBotCoreLifecycle) |
| Platform 适配器 | 把某个 IM 的原始消息转成 AstrMessageEvent,把结果转回去发出 | astrbot/core/platform/(PlatformManager、AstrMessageEvent) |
| 事件总线 EventBus | 维护事件队列,把每个事件派给对应配置的流水线调度器 | astrbot/core/event_bus.py(EventBus.dispatch) |
| 流水线 Pipeline | 按固定顺序跑 9 个阶段处理事件,核心阶段调 Agent | astrbot/core/pipeline/(PipelineScheduler) |
| 本地 Agent | 工具循环:LLM↔工具反复来回,直到给出最终回复 | astrbot/core/agent/runners/tool_loop_agent_runner.py |
| Provider 管理器 | 实例化、切换各个模型提供商 | astrbot/core/provider/(ProviderManager、Provider) |
| Star 插件系统 | 加载第三方插件,注册指令/钩子/工具 | astrbot/core/star/(PluginManager、star_handlers_registry) |
主线走一遍(高层,不进代码):
- 用户在 QQ 群里发「@机器人 帮我查下今天天气」。
- QQ 平台适配器收到原始消息,转成统一的
AstrMessageEvent,塞进事件队列。 - 事件总线取出事件,找到该会话对应的流水线调度器,启动一次流水线执行。
- 流水线依次跑:唤醒检查(被 @ 了,唤醒)→ 白名单 → 会话开关 → 频率限制 → 内容安全 → 预处理 → 处理阶段。
- 处理阶段发现没有插件指令命中,于是走 Agent 分支:构建主 Agent(注入人格、工具、上下文),进入工具循环——LLM 决定调「网页搜索」工具,工具返回天气,LLM 再据此生成回答。
- 装饰阶段给回答加前缀/转图片/转语音(按配置),发送阶段把结果交给 QQ 适配器,转成 QQ 消息格式发回群里。
3. 阅读地图(按这个顺序读)
这套文档按「主线由浅入深」排列,建议顺序:
- 01-pipeline.md — 消息流水线:理解全系统骨架。一条消息怎么被 9 个阶段处理,「洋葱模型」是什么,机器人怎么判断「该不该回复」。读完你能讲清楚 AstrBot 的主控制流。
- 02-agent-loop.md — 本地 Agent 工具循环:理解核心价值。一次对话怎么从「单次问答」升级成「能调工具、能多步推理」的 Agent。这是项目名里「Agent」三个字的所在。
- 03-providers-platforms.md — Provider 与 Platform 适配器:理解「抹平差异」的两套机制——怎么用统一抽象接住 20+ 模型和 18 个 IM。
- 04-plugins-tools.md — 插件与工具:理解扩展性。第三方代码怎么用装饰器挂进系统,工具怎么被 Agent 调用。
- 05-context-and-extras.md — 上下文管理与高级能力:理解「让 Agent 更强」的配套机制:上下文压缩、人格、子 Agent、沙箱。
4. 巧妙之处(预告)
几个值得带走的设计,详见各章:
- 流水线用「异步生成器 + 递归」实现真正的洋葱模型:一个阶段可以在
yield前做前置处理、yield后做后置处理,把后续所有阶段包在中间(§01)。 - 工具 schema 双模式(
full/skills_like):工具描述很长时,先给 LLM「轻 量 schema」决定调哪个工具,再用「仅参数 schema」二次查询,省 token(§02)。 - 重复工具调用的「三级递进提醒」:同一个工具连调 3/4/5 次,系统会自动注入语气逐渐加重的提示,劝 LLM 换策略(§02)。
- 上下文「先按轮次截断,再按 token 压缩」两级策略:既有硬上限保护,又能用 LLM 智能压缩历史(§05)。
5. 横向对比(预告)
AstrBot 在 ai-agent-reference 货架里属于 chat-agents(聊天型 Agent)一类。和「编码 Agent」「通用任务 Agent」的兄弟项目相比,它的取舍很鲜明:它不追求单一强大的自主任务执行,而是追求「多平台接入 + 插件生态 + 会话级配置」。它的工具循环(tool_loop_agent_runner.py)在能力上是标准的 ReAct 式循环,但它把大量精力花在「一条消息从 IM 平台到 LLM 再回 IM 平台」这条管道的工程细节上(唤醒判定、多模态降级、引用消息解析、各平台格式转换)。详细对比见 §03 与各章末尾。