PepperBot

An intuitive multi-platform bot framework, easily forward messages among platforms, support QQ, WeChat, Telegram. 一个符合直觉的跨社交平台机器人框架，轻松地在平台间传递消息，支持QQ、微信、Telegram。

生而跨平台

• QQ 基于 Onebot
• 微信基于 可爱猫
• Telegram基于Pyrogram
• 提供了跨平台、易用的消息类型(片段)
• 通用事件，比如群消息、私聊消息等，提供了统一的接口，只需要写一次代码，就可以无缝应用到各个平台上，跨平台的消息传递从未如此轻松随意
• 可以跨群、跨平台共享指令(的状态)

性能也够用

• 底层基于异步的 Sanic 框架(目前有一定生态的 python web 框架，性能最好的)，性能相当不错
• 轻量，主要处理消息，对于其他功能，暴露底层接口，方便实现深度定制

自带全家桶

• 支持 Django 风格集中化路由、flask 风格装饰器式路由&权限系统
• Django 类视图风格/Vue 生命周期风格的指令系统，Fast Api 风格的依赖注入
• 定时任务

• 日志支持

  • 数据库连接(内置 sqlite)
  • 链式调用 api(行为链，自动跨平台事件等待)
  • cli，快速创建项目，安装社区指令

接口合语义

• api 符合直觉，直观，流畅地把想法映射到代码上
• 基于 python3.6 之后的类型注解，提供了完全的类型提示
• 大部分可以自动获取的参数，都会自动获取，不需要每次手动提供了
• 只会动态注入用到的参数，没必要每次写一长串用不到的参数了！
• API均有可直接复制使用的代码片段，快速开发

安装

使用poetry安装

pip install poetry  # 首先安装poetry
poetry add pepperbot  # 用poetry安装pepperbot

使用pip安装

pip install pepperbot

使用

配置QQ

cqhttp的安装

cqhttp的初始化

# 项目目录结构总览    
AIBot  # 项目名称
└─backend  # backend文件夹
   └─go-cqhttp_windows_amd64.exe  # go-cqhttp 的可执行文件

# 首次运行 go-cqhttp 进行初始化
cd ./backend
./go-cqhttp_xxxxx.exe

第一次运行会提示 未找到配置文件，正在为您生成配置文件中！
接下来会接着提示让我们选择通信方式，我们选择 http通信 和 反向Websocket通信

未找到配置文件，正在为您生成配置文件中！
请选择你需要的通信方式:
> 0: HTTP通信
> 1: 云函数服务
> 2: 正向 Websocket 通信
> 3: 反向 Websocket 通信
请输入你需要的编号(0-9)，可输入多个，同一编号也可输入多
个(如: 233)
您的选择是:03
默认配置文件已生成，请修改 config.yml 后重新启动!

选择通信方式之后，会自动生成默认配置文件 config.yml ,我们需要对此文件进行手动修改

修改 config.yml

• 修改 uin 为自己的 qq 号
• 修改 password 为密码
• 修改 post_format 为 array

• 修改 ws_reverse_servers 中

  • 修改 universal 为 ws://127.0.0.1:端口/onebot/ws
  • 端口需要和 PepperBot 中的端口保持一致
  • ws 的地址，我们可以在 PepperBot 中自定义，不过都需要和 go-cqhttp 保持一致

只需要修改上述说明部分即可，具体修改示例请参考下方代码

# go-cqhttp 默认配置文件
account: # 账号相关
  uin: 1233456 # QQ账号【必填】
  password: '' # 密码为空时使用扫码登录【选填，建议填写】
  encrypt: false  # 是否开启密码加密
  status: 0      # 在线状态 请参考 https://docs.go-cqhttp.org/guide/config.html#在线状态
  relogin: # 重连设置
    delay: 3   # 首次重连延迟, 单位秒
    interval: 3   # 重连间隔
    max-times: 0  # 最大重连次数, 0为无限制

  # 是否使用服务器下发的新地址进行重连
  # 注意, 此设置可能导致在海外服务器上连接情况更差
  use-sso-address: true
  # 是否允许发送临时会话消息
  allow-temp-session: false

heartbeat:
  # 心跳频率, 单位秒
  # -1 为关闭心跳
  interval: 5

message:
  # 上报数据类型
  # 可选: string,array
  post-format: array  # 此处需要将默认的string更改为array【必填】
  # 是否忽略无效的CQ码, 如果为假将原样发送
  ignore-invalid-cqcode: false
  # 是否强制分片发送消息
  # 分片发送将会带来更快的速度
  # 但是兼容性会有些问题
  force-fragment: false
  # 是否将url分片发送
  fix-url: false
  # 下载图片等请求网络代理
  proxy-rewrite: ''
  # 是否上报自身消息
  report-self-message: false
  # 移除服务端的Reply附带的At
  remove-reply-at: false
  # 为Reply附加更多信息
  extra-reply-data: false
  # 跳过 Mime 扫描, 忽略错误数据
  skip-mime-scan: false

output:
  # 日志等级 trace,debug,info,warn,error
  log-level: warn
  # 日志时效 单位天. 超过这个时间之前的日志将会被自动删除. 设置为 0 表示永久保留.
  log-aging: 15
  # 是否在每次启动时强制创建全新的文件储存日志. 为 false 的情况下将会在上次启动时创建的日志文件续写
  log-force-new: true
  # 是否启用日志颜色
  log-colorful: true
  # 是否启用 DEBUG
  debug: false # 开启调试模式

# 默认中间件锚点
default-middlewares: &default
  # 访问密钥, 强烈推荐在公网的服务器设置
  access-token: ''
  # 事件过滤器文件目录
  filter: ''
  # API限速设置
  # 该设置为全局生效
  # 原 cqhttp 虽然启用了 rate_limit 后缀, 但是基本没插件适配
  # 目前该限速设置为令牌桶算法, 请参考:
  # https://baike.baidu.com/item/%E4%BB%A4%E7%89%8C%E6%A1%B6%E7%AE%97%E6%B3%95/6597000?fr=aladdin
  rate-limit:
    enabled: false # 是否启用限速
    frequency: 1  # 令牌回复频率, 单位秒
    bucket: 1     # 令牌桶大小

database: # 数据库相关设置
  leveldb:
    # 是否启用内置leveldb数据库
    # 启用将会增加10-20MB的内存占用和一定的磁盘空间
    # 关闭将无法使用 撤回 回复 get_msg 等上下文相关功能
    enable: true

  # 媒体文件缓存， 删除此项则使用缓存文件(旧版行为)
  cache:
    image: data/image.db
    video: data/video.db

# 连接服务列表
servers:
  # 添加方式，同一连接方式可添加多个，具体配置说明请查看文档
  #- http: # http 通信
  #- ws:   # 正向 Websocket
  #- ws-reverse: # 反向 Websocket
  #- pprof: #性能分析服务器

  - http: # HTTP 通信设置
      address: 0.0.0.0:5700 # HTTP监听地址
      timeout: 5      # 反向 HTTP 超时时间, 单位秒，<5 时将被忽略
      long-polling:   # 长轮询拓展
        enabled: false       # 是否开启
        max-queue-size: 2000 # 消息队列大小，0 表示不限制队列大小，谨慎使用
      middlewares:
        <<: *default # 引用默认中间件
      post:           # 反向HTTP POST地址列表
      #- url: ''                # 地址
      #  secret: ''             # 密钥
      #  max-retries: 3         # 最大重试，0 时禁用
      #  retries-interval: 1500 # 重试时间，单位毫秒，0 时立即
      #- url: http://127.0.0.1:5701/ # 地址
      #  secret: ''                  # 密钥
      #  max-retries: 10             # 最大重试，0 时禁用
      #  retries-interval: 1000      # 重试时间，单位毫秒，0 时立即
  # 反向WS设置
  - ws-reverse:
      # 反向WS Universal 地址
      # 注意 设置了此项地址后下面两项将会被忽略
      universal: ws://127.0.0.1:5256/onebot/ws  # 此处需要修改填写为 ws://127.0.0.1:5256/onebot/ws 的格式，并且需要自定义端口号，比如我填写端口号为5256【必填】
      # 反向WS API 地址
      api: ws://your_websocket_api.server
      # 反向WS Event 地址
      event: ws://your_websocket_event.server
      # 重连间隔 单位毫秒
      reconnect-interval: 3000
      middlewares:
        <<: *default # 引用默认中间件

进入backend目录，再次运行 go-cqhttp 即可

cd ./backend
./go-cqhttp_xxxxx.exe

配置 PepperBot 的端口和协议

我们需要在自己的项目目录下新建一个比如newbot文件夹，在此目录下新建一个 main.py 的 python 文件进行一些信息的配置

# 项目目录结构总览    
AIBot  # 项目名称
├─newbot  # newbot文件夹
│   └─main.py  # python文件用来执行一些命令和命令
└─backend  # backend文件夹
    ├─go-cqhttp_windows_amd64.exe  # go-cqhttp 的可执行文件
    ├─config.yml  # go-cqhttp 的配置文件
    └─...  # 其他文件夹或文件

在 main.py 中输入以下代码进行配置

配置 PepperBot 的接收端口

仅端口需要修改，修改后直接复制粘贴

bot = PepperBot(
    port=5256,  # 此处端口需要和上面 go-cqhttp 的配置文件中自定义的端口保持一致
    debug=True,
)

配置 PepperBot 接受协议和方式

直接复制粘贴，不需要修改

bot.register_adapter(
    bot_protocol="onebot",  # 配置协议
    receive_protocol="websocket",  # 配置 PepperBot 接收协议端推送事件的方式
    backend_protocol="http",
    backend_host="127.0.0.1",
    backend_port=5700,
)

全局事件响应器&指令

bot.apply_routes(
    [
        BotRoute(
            friends=None,  # 设置为 None，即可不响应该类型的消息
            groups={
                "onebot":[  # 填写群号即可在对应群响应消息(比如下面两个群)
                    "123456789",
                    "987654321",
                ],
            },
            handlers=[],
            commands=[指令1, 指令2, 指令3],  # 此处输入你写好的指令
        ),
    ]
)

当然，我们需要写一些指令才能看到效果
我们需要在自己的项目目录下的newbot文件夹下新建一个 commands 的文件夹，用来存放我们写的一些指令

# 项目目录结构总览    
AIBot  # 项目名称
├─newbot  # newbot文件夹
    ├─commands  # 用来存放我们写的一些指令
│   └─main.py  # python文件用来执行一些命令和命令
└─backend  # backend文件夹
    ├─go-cqhttp_windows_amd64.exe  # go-cqhttp 的可执行文件
    ├─config.yml  # go-cqhttp 的配置文件
    └─...  # 其他文件夹或文件

假如我们写一个最简单的消息指令，发送今天天气怎么样，机器人回复今天天气真不错
在commands目录下新建一个名为 weather.py 的 python 文件，然后输入以下代码

from typing import Dict
from pepperbot.core.message.segment import Text
from pepperbot.extensions.command import as_command
from pepperbot.extensions.command.handle import CommandSender


@as_command(
    need_prefix=False,
    prefixes=[
        "/",
        "#",
    ],  # 都是正则，自动加上^
    aliases=["今天天气怎么样"],  # 都是正则
    include_class_name=True,  # 类名本身不作为指令
    exit_patterns=["^/exit", "^退出", "我?退出(对话)?"],  # 都是正则
    require_at=False,  # 是否需要at机器人
    timeout=30,  # 会话超时时间，单位秒
)
class 天气:
    async def initial(
        self,
        sender: CommandSender,
        raw_event: Dict,
    ):
        print(raw_event)
        print(sender)

        await sender.send_message(Text("今天天气真不错"))

下面附上 main.py 的完整代码

from pepperbot.initial import PepperBot
from pepperbot.core.route import BotRoute
from commands.weather import 天气
bot = PepperBot(
    port=5256,
    debug=True,
)

bot.register_adapter(
    bot_protocol="onebot",
    receive_protocol="websocket",
    backend_protocol="http",
    backend_host="127.0.0.1",
    backend_port=5700,
)

bot.apply_routes(
    [
        BotRoute(
            friends=None,
            groups={
                "onebot":[
                    "123456789",
                    "987654321",
                ],
            },
            handlers=[],
            commands=[天气],
        ),
    ]
)

bot.run()

OK，至此所有文件配置完毕，命令也已经写好，接下来让我们运行一下看看效果

cd ./newbot
python main.py

配置微信

敬请期待