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

qife122
0 阅读6分钟

Soulter%2FAstrBot | Trendshift Featured｜HelloGitHub

python

🌟 感谢您使用 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. 克隆仓库

    git clone https://github.com/AstrBotDevs/AstrBot.git
cd AstrBot

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

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

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

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

    cd dashboard
# 安装 pnpm (如果尚未安装: npm install -g pnpm)
pnpm install
pnpm dev

    管理面板默认运行在 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: 装饰器，用于定义插件如何处理不同类型的消息（如命令、正则匹配、事件监听）。

插件示例片段：

from astrbot.api import star
from astrbot.api.event import AstrMessageEvent, filter
from astrbot.api.message_components import Plain

class MyPlugin(star.Star):
    def __init__(self, context: star.Context) -> None:
        self.context = context

    @filter.command("hello")
    async def hello_world(self, event: AstrMessageEvent):
        '''当用户发送 /hello 时触发'''
        yield event.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

    # 打印 Logo
    logger.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)

class AstrBotCoreLifecycle:
    """AstrBot 核心生命周期管理类"""
    def __init__(self, log_broker: LogBroker, db: BaseDatabase) -> None:
        # ... 初始化配置管理器、Provider管理器、平台管理器、插件管理器、事件总线等

    async def initialize(self) -> None:
        """初始化所有组件"""
        # 1. 加载配置
        # 2. 初始化数据库和各个管理器
        # 3. 加载所有插件
        # 4. 启动平台适配器（连接到 IM 平台）
        pass

    async def start(self) -> None:
        """启动事件循环"""
        # 启动事件总线，开始分发消息事件
        asyncio.create_task(self.event_bus.dispatch())
        # ... 其他后台任务

    async def stop(self) -> None:
        """优雅地停止所有组件"""
        # 停止平台适配器、关闭数据库连接、停止插件等
        pass

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

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

class Star:
    '''所有插件必须继承的基类'''
    def __init__(self, context: Context) -> None:
        self.context = context

    @property
    def name(self) -> str:
        '''插件名称，默认返回类名，建议重写'''
        return self.__class__.__name__

    @property
    def desc(self) -> str:
        '''插件描述'''
        return ""

    @property
    def author(self) -> str:
        '''插件作者'''
        return ""

    async def terminate(self):
        '''当插件被卸载或 AstrBot 关闭时调用，用于清理资源'''
        pass

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

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

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

代码注释：这个装饰器（以及 @filter.regex、@filter.on_llm_request 等）是 AstrBot 插件灵活性的关键。通过声明式地将函数与特定的过滤器（如命令名称、正则表达式、事件类型）绑定，AstrBot 的事件系统能够准确地将消息路由到正确的插件处理函数上，大大简化了插件开发者的逻辑判断。FINISHED coYqvf9hN1C/b63wfHSKMiC+dSuDrPhHcORwv/E1qE4=

avatar
文章
阅读
粉丝