KokkoroBot

KokkoroBot is a forked version of HoshinoBot and migrates from QQ to other platforms.

本项目是 @Ice-Cirno 的 HoshinoBot 的分支版本，充斥着大量个人魔改产物。若希望体验原汁原味的 HoshinoBot 请自行魔改回去。

web界面敬请期待。

目前已适配以下平台

• Tomon(国内平台)
  • 体验服务器：https://beta.tomon.co/invite/kCA4Qg?t=htMviz
• Discord
  • 体验服务器：https://discord.gg/U9XFCVj
• Telegram
• 企业微信

1. Motivation

HoshinoBot 无论是基础设施还是应用层，大量使用了来自 Nonebot 中的概念如 CQEvent, MessageSegment，这直接导致上层服务与 Nonebot 以及 Nonebot 底层的 CQHttp 极大程度上耦合在一起，难以将 HoshinoBot 移植到其他平台或框架，比如从 QQ 迁移至 Discord。

因此 KokkoroBot 针对这一问题对底层代码进行重构，期望应用服务与 IM 平台解耦合，能够较迅速的迁移至其他平台。~~其实是因为酷Q凉了，mirai随时可能会挂~~

2. 使用方法

2.1 配置文件

首先将 kokkoro 文件夹下的 config_example 在当前文件夹复制一份并重命名为 config。然后修改其中的各个配置文件

cd kokkoro
cp -r config_example config

2.1.1 通用配置

配置文件为 kokkoro/config/__bot__.py

• BOT_TYPE
  • 将 BOT_TYPE 修改为你需要使用的 IM 平台，可填写的值有以下几种
  • discord
  • telegram
  • tomon (国内类discord平台 无墙)
  • wechat_enterprise (企业微信)
• BOT_ID, SUPER_USER, ENABLED_GROUP
  • 这三个参数都是平台相关的。需要在对应平台的配置文件中进行修改
  • BOT_ID：bot 自己的 ID
    • 部分平台 bot 会收到自己的消息，因此使用该参数过滤 bot 自己的消息
  • SUPER_USER：在 bot 中拥有最高权限的用户，通常将自己的 ID 填在这里
  • ENABLED_GROUP：bot 仅会对 ENABLED_GROUP 中的群组作出回应
• LOG_LEVE
  • 开发人员 DEBUG 用，一般用户设置为 "INFO" 即可
• NICK_NAME
  • bot 别称，通过在消息最前面加别称达到与 @bot 相同的效果
• RES_PROTOCOL
  • 加载内置资源文件的方式，可填写的值有以下两种：
  • file （通过文件访问）
  • http （通过 http 协议访问，需另外部署静态资源服务器）
• RES_DIR
  • 资源文件的根目录路径
  • 仅当 RES_PROTOCOL 为 file 时生效
  • 示例：~/.kokkoro/res/
• RES_URL
  • 资源文件的根 URL
  • 仅当 RES_PROTOCOL 为 http 时生效
  • 示例：http://123.123.123.123/
• MODULES_ON
  • 开启的模块
  • 将 kokkoro/modules/ 目录下想要开启的模块名称填写在这个列表中
• FONT_PATH
  • 一般用户无需修改
  • 开发者进行插件开发时，用到的字体文件需要在此配置
  • 插件从该字典变量中获取字体路径

注意：每次更新时，老用户请自行检查 config_example 中的配置文件相较您之前使用的版本是否有修改。如果有，则请更新配置文件后使用。

如果您不确定是否有修改，可在群内提问。

2.1.2 Discord 配置

配置文件为 kokkoro/config/bot/discord.py。

Discord 需要将客户端设置为开发者模式才能查看群组、用户 ID。开发者模式的开启请参考该链接 https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-

修改配置文件之前，先按照以下链接的说明在 Discord 网站上创建好 App，然后在 App 内创建好 Bot。

https://discord.com/developers/docs/intro

此外如果你还没有一个 Discord Server（群组），需要在 Discord 客户端中自行创建。

• DISCORD_TOKEN
  • 填写之前创建的 Bot 的 TOKEN
• ENABLED_GROUP
  • 允许使用 Bot 的 Discord Server ID
• SUPER_USER
  • 填写自己的用户 ID
• BOT_ID
  • 填写之前创建的 App 的 CLIENT ID（在 General Information 页面）

2.1.3 Telegram 配置

配置文件为 kokkoro/config/bot/telegram.py

Telegram 获取用户与群组 ID 很麻烦，需要从 API 中自己获取，请参考该链接 https://stackoverflow.com/questions/32423837/telegram-bot-how-to-get-a-group-chat-id

在修改配置文件之前，先在在 Telegram 客户端中找 BotFather 申请好 BOT，并使用 /setprivacy 命令将 bot 设置为允许接受来自群组的消息

https://core.telegram.org/bots

• TELEGRAM_TOKEN
  • 填写从 BotFather 得到的 TOKEN
• ENABLED_GROUP
  • 允许使用 BOT 的 telegram 群组 ID
• SUPER_USER
  • 填写自己的 ID
• BOT_ID
  • 目前 telegram 暂时没有一个比较好的手段获得 BOT_ID，不过 telegram bot 也不会收到自己发的消息，因此设置为 None 即可

2.1.4 Tomon (国内平台)

配置文件为 kokkoro/config/bot/tomon.py

由于 Tomon 目前仍在内测中，请先点击邀请链接注册并加入 Tomon。注册成功后，点击右下角机器人图标的 Bot Master 根据流程申请 Bot。

如有任何疑问可在 Tomon 或 QQ 群中交流。

目前 Tomon 还没有开发者模式，请参考 Tomon 开发者文档获取个人 ID 与群组 ID。

https://developer.tomon.co/docs/user#%E6%9F%A5%E7%9C%8B%E4%B8%AA%E4%BA%BA%E8%B5%84%E6%96%99

• TOMON_TOKEN
  • 填写从 Bot Master 得到的 TOKEN
• ENABLED_GROUP
  • 允许使用 BOT 的 Tomon 群组 ID
• SUPER_USER
  • 填写自己的 ID
• BOT_ID
  • 填写 BOT 的 ID

2.1.5 企业微信

TODO

2.2 部署流程

2.2.1 Linux/macOS (推荐)

使用 Linux 部署可以通过 Docker 省去自行搭建环境的麻烦与各种平台问题。

• 安装 Docker 环境。

  https://docs.docker.com/engine/install/centos/

• 安装 Docker Compose。

  https://docs.docker.com/compose/install/

• 构建 Docker 镜像。

  cd deploy
  docker-compose build
  

• 使用 Docker Compose 部署。

  进行 debug 时请删除 -d 参数。

  # 确保处于 deploy 目录中
  docker-compose up -d
  

  也可以只启动 Bot，不运行 Web 界面。

  # 确保处于 deploy 目录中
  docker-compose up bot -d
  

• 在群里发一句 help，Bot 如果反馈帮助信息则说明初步搭建完成！

• 如果对配置文件或者代码有任何修改，需要重新执行以下命令才能生效。

  # 确保处于 deploy 目录中
  docker-compose build
  docker-compose up -d
  

2.2.2 Windows

• 安装 python 3.8 环境；或者使用 conda / virtualenv 等 python 虚拟环境

  https://www.python.org/downloads/

  https://docs.conda.io/en/latest/

  https://virtualenv.pypa.io/

• 打开 Powershell 或者其他命令行工具，执行以下命令

cd /path/to/this/project # 请自行将该路径替换为你的项目路径
pip install -r requirements.txt # 安装项目依赖
python3.8 run.py # 运行项目

个人推荐使用 linux docker 进行部署，否则遇到奇奇怪怪的环境问题请自行处理

2.2.3 小结

以上步骤如果您都成功执行，那么 KokkoroBot 就已经部署成功了！

但其中部分功能需要用到一些额外的图片资源或者第三方 API。因此请继续阅读 2.3 与 2.4，以保证这些功能都能够正常使用。

2.3 资源文件

目前 KokkoroBot 中的图片等资源文件主要来自 HoshinoBot 群内提供的资源包。在此基础之上额外添加了字体与其他资源，从 KokkoroBot 群中可下载最完整的资源包。

KokkoroBot 群：887897168。

下载好的资源文件放在服务器的 ~/.kokkoro 目录下，保证目录看上去是如下结构 ~/.kokkoro/res/img。

2.4 第三方应用的 API Key

2.4.1 竞技场查询

竞技场查询功能依赖于 https://pcrdfans.com。注册并登陆后可在 https://pcrdfans.com/bot 申请 API Key。由于查询网站服务器限制，暂时可能无法申请到 API Key。

申请到以后可在 kokkoro/config/modules/priconne.py 中将您申请到的 API Key 填写在里面

# kokkoro/config/modules/priconne.py
class arena:
    AUTH_KEY = "YOUR_API_KEY"

3. 指令集

多个匹配指令以逗号分隔，实际操作时可匹配指令更多，该表格仅显示最标准的命令。后续会有更多功能实装，敬请期待~

Bot 底层会自动将简中指令转为繁中指令一起注册到 Bot 中。因此表格中不再单独列出繁中指令。

3.1 基本指令

3.1 推送服务指令

对于所有推送服务，都会自动生成如下表所示的指令。

对于 tomon、discord 等同一个群组内有多个频道的平台，推送服务将会把内容推送到所有名称里包含标签的频道。频道名中包含其中一个标签就会收到推送消息。

示例：

群组 "KokkoroBot" 中包含三个频道："🐂国服推送🐂"、"🐎台服推送🐎"、"🐏日服推送🐏"、"debug"。

weibo-pcr 服务默认的推送标签为["国服推送"]。因此当服务 weibo-pcr 启用时，会将微博内容推送至"🐂国服推送🐂"频道。

若通过命令 weibo-pcr set-bc-tag 台服推送 debug 将该服务的推送标签设置为 ["国服推送", "debug"]。那么当服务 weibo-pcr 启用时，会将微博内容推送至"🐎台服推送🐎"与"debug"频道。

4. 二次开发与新平台适配

详情见 DEVELOPER-README.md .这里只做简要介绍。

4.1 接口设计

KokkoroBot 在基础设施与应用层中加一层统一接口 common_interface 以达到解耦合的目的。

任何平台的机器人都需要实现 kokkoro.common_interface.KokkoroBot 接口。

任何平台的事件(Event)都需要转化为 kokkoro.common_interface.EventInterface 供上层服务使用。同理，任何平台的用户(User)都需要转化为 kokkoro.common_interface.UserInterface。

发送图片时不再依赖任何平台相关逻辑，直接将 common_interface.SupportedMessageType 格式的消息传给 kokkoro.common_interface.KokkoroBot.kkr_send 函数，在具体实现类中实现具体平台相关的处理逻辑。

上层服务与平台彻底解耦合。平台依赖于 kokkoro.common_interface，上层服务依赖于 kokkoro.commmon_interface。因此能够兼容多种平台。

• 在这样的设计下，将 KokkoroBot 移植到其他平台便不再困难。只需要以下三步：
  • 完成平台相关的机器人
    • 机器人需要实现 kokkoro.common_interface.KokkoroBot 接口
    • 需要支持 common_interface.SupportedMessageType 中所有消息类型的发送
    • 示例: kokkoro.bot.discord.KokkroDiscordBot
  • 实现 Event 的适配
    • 将平台相关 Event 适配为 common_interface.EventInterface
      • 平台相关 Event：CQEvent, discord.Message
    • 示例：kokkoro.bot.discord.discord_adaptor.DiscordEvent 将 discord.Message 适配为 EventInterface
  • 实现 User 的适配
    • 将平台相关 User 适配为 common_interface.UserInterface
      • 平台相关 User：discord.User
    • 示例：kokkoro.bot.discord.discord_adaptor.DiscordUser 将 discord.User 适配为 UserInterface

4.2 新 IM 平台适配

以 telegram 为例，从零对 telegram 平台进行开发主要包含以下几步。

• kokkoro.config.__bot__ 中配置 BOT_TYPE = 'telegram'
• kokkoro.config.bot 中添加 telegram.py 配置文件
• 在 kokkoro.bot.telegram 包中实现相关适配
• 在 kokkoro.bot.__init__ 中添加 telegram bot

TODO

• [ ] Web
  • Doing by @SonodaHanami
• [x] Isolate platform specific logic from application services
• [x] Multi-platform
  • [x] Discord
    • [ ] Audio
    • [x] Image
    • [x] Text
    • [x] Permission control with admin
  • [x] Telegram
    • [ ] Audio
    • [x] Image
    • [x] Text
    • [x] Permission control with admin
  • [x] Tomon
    • [ ] Audio
    • [x] Image
    • [x] Text
    • [x] Permission control with admin
  • [x] Wechat Enterprise
    • [ ] Audio
    • [ ] Image
    • [x] Text
    • [ ] Permission control with admin