xbotlib

面向人类的XMPP机器人

状态：实验性

A friendly lightweight wrapper around slixmpp for writing XMPP bots in Python. The goal is to make writing and running XMPP bots easy and fun. xbotlib is a single file implementation which can easily be understood and extended. The xbotlib source code and ideas are largely borrowed from the XMPP bot experiments going on in Varia.

• 安装
• 入门
• 与您的机器人一起工作
  • 文档
  • 命令
  • 头像
  • 配置
    • 使用.conf配置文件
    • 使用命令行界面
    • 使用环境
  • 存储后端
  • 加载插件
  • 提供HTTP服务
  • 邀请
  • API参考
    • Bot.direct(message)
    • Bot.group(message)
    • Bot.serve(request)
    • Bot.routes()
    • Bot.setup()
    • SimpleMessage
    • Bot
• 聊天室
• 更多示例
• 部署您的机器人
• 路线图
• 变更
• 许可证
• 贡献

安装

$ pip install xbotlib

入门

将以下内容放入echo.py文件中。此机器人会回显您发送给它的任何消息，无论是直接消息还是群组消息。在群聊中，您需要直接向机器人发送消息（例如echobot: hi）（有关更多信息，请参阅命令部分）。

from xbotlib import Bot

class EchoBot(Bot):
    def direct(self, message):
        self.reply(message.text, to=message.sender)

    def group(self, message):
        self.reply(message.content, room=message.room)

EchoBot()

然后执行 python echo.py。系统将询问一些问题，以便加载您的机器人将使用的账户详细信息。这将在同一工作目录中生成一个 echobot.conf 文件，以便进一步使用。更多详情请参见配置部分。

就这些！如果您想了解更多，请继续阅读这里。

与您的机器人一起工作

以下部分尝试涵盖所有使用 xbotlib 配置和扩展您机器人的方法。如果有什么不清楚的地方，请通过聊天告诉我们。

文档

像这样在您的 Bot 类中添加一个 help = "my help"。

class MyBot(Bot):
    help = """This is my cool help.

    I can list some commands too:

      @foo - some command
    """

您的机器人将响应 mybot: @help 调用。这个字符串可以是一个多行字符串，带有缩进。 xbotlib 将尝试在聊天客户端中合理地格式化它。

更多详情请参见命令部分。

命令

在私信中使用 @<command> 和在群聊中使用 <nick>, @<command>（逗号是可选的，这里接受任何内容，在 XMPP 中 '@' 另一个用户的常见方式似乎还没有达成共识）这里列出的是支持的命令。

• @uptime：机器人已运行多长时间
• @help：机器人所做事情的说明文本

还有一些更通用的状态命令，所有机器人都会响应。

• @bots：检查群聊中谁是机器人

这些命令将在发送给机器人的消息的任何部分检测到。因此，您可以编写 echobot, can we see your @uptime，或 I'd love to know which @bots are here.

头像

默认情况下，xbotlib 将在包含您的机器人实现的 Python 脚本旁边查找一个 avatar.png 文件（目前测试了 .png，但其他文件类型可能也有效）。您还可以使用命令行界面的 --avatar 选项指定另一个路径。理想情况下，图像的高度为 64 像素，宽度为 64 像素。

配置

您可以将配置详细信息传递给机器人的所有方式。您可以通过三种方式配置您的机器人：配置文件、命令行界面和环境。使用最适合您的方法。值的加载顺序如下：命令行 > 配置文件 > 环境。这意味着您可以轻松地从命令行覆盖所有内容。

使用.conf配置文件

如果您简单地运行包含机器人的 Python 脚本，xbotlib 将通过询问一些问题为您生成配置。这是在本地运行机器人的最简单方法。

• account：机器人的账户
• password：机器人账户的密码
• nick：机器人的昵称
• avatar：机器人的头像（默认：avatar.png）
• redis_url：Redis 连接 URL
• rooms：要自动加入的房间列表（逗号分隔）
• no_auto_join：被邀请时不自动加入（默认：False）
• template：要服务的端口（默认：index.html.j2）
• serve：开启网络服务器（默认：False）
• port：要服务的端口（默认：8080）
• storage：存储后端（默认：file）
• output：输出目录的路径（默认：./）

使用命令行界面

每个机器人都接受一些命令行参数来加载配置。您可以使用 --help 选项查看可用选项（例如，python bot.py --help）。

• -h, --help：显示此帮助消息并退出
• -d, --debug：启用详细的调试日志
• -a ACCOUNT, --account ACCOUNT：机器人账户
• -p PASSWORD, --password PASSWORD：机器人账户密码
• -n NICK, --nick NICK：机器人账户昵称
• -av AVATAR, --avatar AVATAR：机器人账户头像（默认：avatar.png）
• -ru REDIS_URL, --redis-url REDIS_URL：Redis 存储连接 URL
• -r 房间 [房间 ...], --rooms 房间 [房间 ...]：自动加入的房间
• -naj, --no-auto-join：禁用邀请时自动加入房间（默认：False）
• -pt PORT, --port PORT：服务的端口（默认：8080）
• -t 模板, --template 模板：要渲染的模板（默认：index.html.j2）
• -s, --serve：开启网络服务器（默认：False）
• -st {file,redis}, --storage {file,redis}：选择存储后端（默认：file）
• -o 输出, --output 输出：输出目录的路径（默认：./）

使用环境

如果无法从配置文件或命令行界面中读取以下配置值，它将尝试从环境变量中读取。这在进行远程服务器部署时非常有用。

• XBOT_ACCOUNT：机器人账户
• XBOT_PASSWORD：机器人密码
• XBOT_NICK：机器人昵称
• XBOT_AVATAR：机器人头像图标（默认：avatar.png）
• XBOT_REDIS_URL：Redis键存储连接URL
• XBOT_ROOMS：自动加入的房间
• XBOT_NO_AUTO_JOIN：邀请时禁用自动加入（默认：False）
• XBOT_TEMPLATE：要渲染的模板（默认：index.html.j2）
• XBOT_SERVE：开启网络服务器（默认：False）
• XBOT_PORT：服务的端口（默认：8080）
• XBOT_STORAGE：选择存储后端（默认：file）
• XBOT_OUTPUT：输出目录的路径（默认：./）

存储后端

为了存储数据，您可以使用Bot类的self.db属性。它是一个Python字典，将自动保存到磁盘，以<nick>.json的形式保存在您的工作目录中。您可以使用输出选项（例如python bot.py --output /var/www/html）配置此文件名和路径。

def group(self, message):
    if not message.room in self.db.keys():
        self.db[message.room] = "visited"

如果您在机器人不运行时想要检查数据库，可以直接查看文件。

$ cat <nick>.json

对于更高级的使用场景，xbotlib还支持Redis作为存储后端。您需要配置它（例如--storage redis），因为默认使用上面提到的文件系统方法。然后，相同的self.db将被作为Redis连接对象传递。您还需要使用pip install xbotlib[redis]安装额外的依赖项。

加载插件

您可以在您的机器人定义中指定plugins = [...]，它们将在您启动机器人时自动加载。

class MyBot(Bot):
    plugins = ["xep_0066"]

有关支持插件的列表，请参阅此处。

提供HTTP服务

首先，您需要安装额外的依赖项。

$ pip install xbotlib[web]

如果您的机器人配置为这样做，它将运行一个网络服务器。使用命令行上的--serve选项、serve = True配置选项或XBOT_SERVE=True环境变量。

如果您在本地运行机器人，只需访问0.0.0.0:8080即可查看。默认响应只是一些占位符文本。您可以使用Bot.serve函数编写自己的响应。

xbotlib提供了一个小型包装API，用于Jinja2，允许您轻松地进行模板化并生成HTML。网络服务器由aiohttp提供。

默认模板搜索路径是当前工作目录中的index.html.j2。这可以通过常规配置入口进行配置。您也可以在没有内置服务器的情况下使用模板！

以下是一个小示例，它渲染一个随机的ASCII字母并使用样式表。

index.html.j2

<html>
<head>
  <style> h1 { color: red; } </style>
</head>
<body>
  <h1>{{ letter }}</h1>
</body>
</html>

bot.py

from string import ascii_letters

async def serve(self, request):
    letter = choice(ascii_letters)
    rendered = self.template.render(letter=letter)
    return self.respond(rendered)

请注意这里对 return 关键词的使用。必须使 serve 函数返回一个响应，该响应将被传递给 web 服务器。同时，还有 async 关键词。此函数可以处理异步操作，并且必须被标记为异步。你可以返回网络上的任何内容类型（例如 HTML、XML、JSON、音频甚至视频），但必须在 respond 中指定 content_type=... 关键字参数。

更多内容类型请见 可用内容类型列表。

如果你想在 direct/group 函数中将数据传递给 serve 函数，你需要使用某种类型的持久存储。你的 serve 函数可以读取存储后端，然后响应。这通常只是访问 self.db 属性那么简单。

邀请

只要没有设置 --no-auto-join 选项（通过配置文件或环境设置），那么你的机器人将自动加入它被邀请加入的任何房间。你的机器人被邀请加入的房间将被存储在 .xbotlib/data.json 文件中。如果你的机器人被关闭或由于某种原因失败，则当它再次打开时，它将读取此文件以查看它应该自动重新加入哪些房间。可以自由手动编辑 data.json 文件。

API参考

当编写自己的机器人时，你始终是继承自 xbotlib 提供的 Bot 类。然后，如果你想对直接消息做出响应，你将编写一个 direct 函数。如果你想对群聊消息做出响应，你将编写一个 group 函数。这就是基础知识。

Bot.direct(message)

对直接消息做出响应。

参数

• message：接收到的消息（有关可用的属性，请参阅下面的 SimpleMessage）

Bot.group(message)

对群聊中的消息做出响应。

参数

• message：接收到的消息（有关可用的属性，请参阅下面的 SimpleMessage）

Bot.serve(request)

通过内置的 web 服务器处理请求。

有关更多信息，请参阅 本节。

参数

• request：web 请求

Bot.routes()

为 web 服务注册额外的路由。

有关更多信息，请参阅 本节。

这是一个高级功能。使用 self.web.add_routes。

from aiohttp.web import get

def routes(self):
    self.web.add_routes([get("/foo", self.foo)])

Bot.setup()

在启动你的机器人之前运行一些设置逻辑。

SimpleMessage

一个简单的消息接口。

属性

• text：消息的全部文本
• content：消息中昵称后的文本
• sender：消息来源的用户
• room：消息来源的房间
• receiver：消息的接收者
• nick：发送者的昵称
• type：消息的类型
• url：发送的文件的 URL

Bot

Bot.reply(message, to=None, room=None)

发送一条回复。

参数

• message：要发送的消息
• to：要发送回复的用户
• room：要发送回复的房间

Bot.respond(response, content_type="text/html")

通过 web 服务器返回一个响应。

参数

• response：响应的文本
• content_type：响应的类型

Bot 类上还有其他一些有用的属性

• self.db：存储后端。

聊天室

如果你想要聊天或者只是邀请你的机器人进行测试，请访问 xbotlibtest@muc.vvvvvvaria.org。

更多示例

有关更多示例，请参阅 git.vvvvvvaria.org。

部署您的机器人

文档即将推出。

路线图

请参阅 问题跟踪器。

变更

请参阅 CHANGELOG.md。

许可证

请参阅 LICENSE。

贡献

欢迎所有和任何的贡献！很高兴听到你如何使用这个库或从可用性角度可以改进什么。

为了测试，请安装 Tox (pip install tox) 并运行 tox 在本地运行测试套件。