面向 IM 平台的 Agentic AI 个人/群聊助手 | AstrBot

🌟 感谢您使用 AstrBot！
AstrBot 是一款可接入多种 IM 平台的Agentic AI 个人/群聊助手，内置多项强大功能，希望能为您带来高效、愉快的使用体验。❤️

功能特性 ✨

• 多平台接入：支持接入多种即时通讯（IM）平台，如 QQ、微信、飞书、Discord 等，一处开发，多平台运行。
• Agentic AI 核心：不仅仅是聊天，内置 Agent 能力，能够进行任务规划、调用工具、分解复杂指令，实现自动化辅助。
• 强大的插件系统：拥有丰富的内置插件（如联网搜索、会话管理、管理员工具），并允许开发者通过简单的 Python 代码创建自己的插件，无限扩展功能。
• 可视化 WebUI：提供现代化的仪表板界面，方便用户进行可视化的配置管理、插件安装、对话查看和系统监控，开箱即用。
• 智能会话管理：支持多轮对话、会话隔离、人格设定（Persona）、上下文管理，让 AI 更懂你和你的群聊。
• 工具调用（Function Calling）：AI 可以自主调用外部工具，如进行联网搜索、获取实时信息、执行计算等，突破模型自身的知识局限。
• 内置实用命令：提供/help、/plugin、/provider、/reset等一系列开箱即用的管理命令，方便用户与机器人交互。
• 安全健康模式：内置内容安全机制，引导 AI 输出健康、友善的内容，并可选择开启或关闭“健康模式”（默认开启）。

安装指南 🛠️

系统要求

• Python 3.10 或更高版本
• (可选) Node.js 和 pnpm，用于开发或运行 WebUI 仪表板

分步安装

1. 克隆仓库

   gitclone https://github.com/AstrBotDevs/AstrBot.gitcdAstrBot

2. 安装核心后端
   我们推荐使用uv进行快速的 Python 依赖管理。

   # 安装 uv (如果尚未安装)pipinstalluv# 同步依赖并运行uvsyncuv run main.py

   首次运行后，AstrBot 默认会在http://localhost:6185启动一个 API 服务。

3. 启动管理面板 (WebUI)
   为了方便管理，建议启动可视化仪表板。

   cddashboard# 安装 pnpm (如果尚未安装: npm install -g pnpm)pnpminstallpnpmdev

   管理面板默认运行在http://localhost:3000。你可以在面板中完成后续的 LLM 提供商配置、插件管理等操作。

使用说明 📖

基础使用

启动 AstrBot 后，你可以向机器人发送/help命令来查看所有可用指令。

典型使用场景

• 多轮对话与角色扮演：通过/persona命令切换 AI 的人设，让其以不同风格与你对话。
• 群聊管理：管理员可以使用/op、/deop命令授权或撤销管理员，使用/plugin off <插件名>来禁用特定插件。
• 联网搜索：在对话中提及需要实时信息的问题，配置好搜索插件后，AI 会自动调用联网搜索工具来获取最新资讯。
• 切换 AI 模型：如果你配置了多个 LLM 提供商（如 OpenAI、Azure、Gemini 等），可以使用/provider命令在它们之间快速切换。
• 重置对话上下文：当对话偏离主题或想开始新话题时，可以使用/reset命令清空当前会话的上下文。

API 概览 (面向开发者)

AstrBot 提供了丰富的 Python API，方便开发者进行插件开发。

核心概念：

• Star: 插件的基础类，所有插件都需要继承它。
• AstrMessageEvent: 消息事件对象，包含了消息内容、发送者、会话等所有上下文信息。
• Context: 插件上下文，用于获取配置、管理器实例等核心组件。
• filter: 装饰器，用于定义插件如何处理不同类型的消息（如命令、正则匹配、事件监听）。

插件示例片段：

fromastrbot.apiimportstarfromastrbot.api.eventimportAstrMessageEvent,filterfromastrbot.api.message_componentsimportPlainclassMyPlugin(star.Star):def__init__(self,context:star.Context)->None:self.context=context@filter.command("hello")asyncdefhello_world(self,event:AstrMessageEvent):'''当用户发送 /hello 时触发'''yieldevent.plain_result("Hello, AstrBot!")# 简单回复文本

核心代码 💡

以下为核心启动流程与插件系统实现的几个关键片段。

1. 主程序入口 (main.py)

# ... (导入模块)if__name__=="__main__":# 解析命令行参数，如指定 WebUI 目录parser=argparse.ArgumentParser(description="AstrBot")parser.add_argument("--webui-dir",type=str,help="指定 WebUI 静态文件目录路径",default=None)args=parser.parse_args()# 检查 Python 版本、创建必要的目录check_env()# 初始化日志代理和数据库log_broker=LogBroker()LogManager.set_queue_handler(logger,log_broker)db=db_helper# 打印 Logologger.info(logo_tmpl)# 检查或下载管理面板文件webui_dir=asyncio.run(check_dashboard_files(args.webui_dir))# 创建并启动核心生命周期管理器core_lifecycle=InitialLoader(db,log_broker)core_lifecycle.webui_dir=webui_dir asyncio.run(core_lifecycle.start())

代码注释：这是 AstrBot 的启动入口。它负责初始化运行环境（检查 Python 版本、建立目录）、设置日志系统、连接数据库，并确保 WebUI 管理面板的资源就绪。最后，它会创建InitialLoader实例并启动整个核心生命周期。

2. 核心生命周期管理器 (core/core_lifecycle.py)

classAstrBotCoreLifecycle:"""AstrBot 核心生命周期管理类"""def__init__(self,log_broker:LogBroker,db:BaseDatabase)->None:# ... 初始化配置管理器、Provider管理器、平台管理器、插件管理器、事件总线等asyncdefinitialize(self)->None:"""初始化所有组件"""# 1. 加载配置# 2. 初始化数据库和各个管理器# 3. 加载所有插件# 4. 启动平台适配器（连接到 IM 平台）passasyncdefstart(self)->None:"""启动事件循环"""# 启动事件总线，开始分发消息事件asyncio.create_task(self.event_bus.dispatch())# ... 其他后台任务asyncdefstop(self)->None:"""优雅地停止所有组件"""# 停止平台适配器、关闭数据库连接、停止插件等pass

代码注释：AstrBotCoreLifecycle是 AstrBot 的心脏。它负责组装和管理所有核心组件，从配置文件、数据库、AI 提供商到各个即时通讯平台的连接。initialize方法按顺序加载所有部分，而start方法则启动事件循环，等待并处理来自各个平台的消息。

3. 插件定义 (api/star/star.py)

classStar:'''所有插件必须继承的基类'''def__init__(self,context:Context)->None:self.context=context@propertydefname(self)->str:'''插件名称，默认返回类名，建议重写'''returnself.__class__.__name__@propertydefdesc(self)->str:'''插件描述'''return""@propertydefauthor(self)->str:'''插件作者'''return""asyncdefterminate(self):'''当插件被卸载或 AstrBot 关闭时调用，用于清理资源'''pass

代码注释：Star类是 AstrBot 插件体系的基础。任何 Python 模块想要成为 AstrBot 的一个功能单元，都必须定义一个继承自Star的类。这个基类为插件提供了访问核心系统 (context) 的入口，并定义了名称、描述等元数据。插件开发者可以通过实现terminate方法来确保资源的正确释放。

4. 消息事件装饰器 (api/event/filter.py)

defcommand(name:str,alias:Optional[list[str]]=None,**kwargs):""" 用于将插件方法标记为一个命令处理器。 当用户发送以 "/<name>" 开头的消息时，该方法会被调用。 """defdecorator(func):# 将函数元数据注册到全局处理器注册表中star_handlers_registry.register_handler(handler=func,event_type=EventType.EventMessageType,# 表示这是一个普通消息事件filters=[CommandFilter(name,alias)],# 添加命令过滤器**kwargs)returnfuncreturndecorator

代码注释：这个装饰器（以及@filter.regex、@filter.on_llm_request等）是 AstrBot 插件灵活性的关键。通过声明式地将函数与特定的过滤器（如命令名称、正则表达式、事件类型）绑定，AstrBot 的事件系统能够准确地将消息路由到正确的插件处理函数上，大大简化了插件开发者的逻辑判断。FINISHED
coYqvf9hN1C/b63wfHSKMiC+dSuDrPhHcORwv/E1qE4=
更多精彩内容 请关注我的个人公众号 公众号（办公AI智能小助手）
对网络安全、黑客技术感兴趣的朋友可以关注我的安全公众号（网络安全技术点滴分享）