.. image:: https://errbot.readthedocs.org/en/latest/_static/errbot.png :target: http://errbot.io

|

.. image:: https://github.com/errbotio/errbot/workflows/Python%20package/badge.svg :target: https://github.com/errbotio/errbot/actions

.. image:: https://img.shields.io/pypi/v/errbot.svg :target: https://pypi.python.org/pypi/errbot :alt: 最新版本

.. image:: https://img.shields.io/badge/License-GPLv3-green.svg :target: https://pypi.python.org/pypi/errbot :alt: 许可证

.. image:: https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg :target: https://gitter.im/errbotio/errbot?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge :alt: 加入 https://gitter.im/errbotio/errbot 的聊天室

|

Errbot

Errbot 是一款聊天机器人。它允许您从聊天室中以交互方式启动脚本，用途广泛：随机幽默、ChatOps、启动构建、监控提交、触发告警等。

Errbot 使用 Python 编写，并且易于扩展。

Errbot 作为开源软件发布，采用 GPL v3 许可证。

特性

支持的聊天服务器

**内置**

- IRC 支持
- `Telegram 支持 <https://www.telegram.org/>`_
- `XMPP 支持 <http://xmpp.org>`_

**通过插件支持**

- `Slack 支持 <https://slack.com/>`_（参见 `说明 <https://github.com/errbotio/err-backend-slackv3>`__）
- `Discord <https://www.discordapp.com/>`_（参见 `说明 <https://github.com/errbotio/err-backend-discord>`__）
- `Gitter 支持 <https://gitter.im/>`_（参见 `说明 <https://github.com/errbotio/err-backend-gitter>`__）
- `Webex <https://www.webex.com/>`_（参见 `说明 <https://github.com/marksull/err-backend-cisco-webex-teams>`__）
- `Mattermost <https://about.mattermost.com/>`_（参见 `说明 <https://github.com/Vaelor/errbot-mattermost-backend>`__）
- `RocketChat <https://rocket.chat/>`_（参见 `说明 <https://github.com/cardoso/errbot-rocketchat>`__）
- `Skype <https://www.skype.com/>`_（参见 `说明 <https://github.com/errbotio/errbot-backend-skype>`__）
- `TOX <https://tox.chat/>`_（参见 `说明 <https://github.com/errbotio/err-backend-tox>`__）
- `VK <https://vk.com/>`_（参见 `说明 <https://github.com/Ax3Effect/errbot-vk>`__）
- `Zulip <https://zulipchat.com/>`_（参见 `说明 <https://github.com/zulip/errbot-backend-zulip>`__）


管理
~~~~~~~~~~~~~~

在完成初始安装和安全设置后，只需与机器人聊天即可进行管理（ChatOps）。

- 安装/卸载/更新/启用/禁用托管在 Git 上的私有或公共插件
- 插件可通过聊天进行配置
- 指示机器人加入或退出多人聊天室 (MUC)
- 安全性：ACL 控制功能（按命令划分管理员和用户权限）
- 备份：集成命令 !backup 可创建持久化数据的完整导出。
- 日志：可通过聊天查看日志，或将其流式传输到 Sentry。

开发者功能
~~~~~~~~~~~~~~~~~~

- 极易使用 Python 扩展！（见下文）
- 为每个插件预设存储，例如 ``self['foo'] = 'bar'`` 可持久化该值。
- 对话流程可用于跟踪用户的对话状态。
- 支持 Webhook 回调
- 支持 `markdown extras <https://markdown-extra.readthedocs.io/>`_ 格式，包括表格、嵌入式图片、链接等。
- 配置助手，允许您的插件通过聊天进行配置。
- 文本开发/调试控制台
- 自文档化：您的 docstring 会自动成为帮助信息。
- 提供子命令和多种参数解析选项（正则表达式、命令行类型等）。
- 轮询支持：您可以设置插件定期执行某些操作。
- 端到端测试后端
- Slack 下的卡片渲染

社区和支持
---------------------

如果您有：

- 快速问题，欢迎加入我们在 `Gitter 上的 errbotio/errbot <https://gitter.im/errbotio/errbot>`_ 聊天室。
- 插件开发问题，请使用 `Stackoverflow <http://stackoverflow.com/questions/tagged/errbot>`_ 并标记 `errbot` 和 `python`。
- 需要报告的错误或功能请求，请使用我们的 `GitHub 项目页面 <https://github.com/errbotio/errbot/issues>`_。

您也可以在 Twitter 上使用标签 ``#errbot`` 联系我们。


安装
------------

前提条件
~~~~~~~~~~~~~

Errbot 在 Linux、Windows 和 Mac 上运行于 Python 3.6+。对于某些聊天系统，您需要密钥或登录凭据才能让机器人访问它们。

快速入门
~~~~~~~~~~

我们建议设置一个 `virtualenv <https://pypi.python.org/pypi/virtualenv>`_。

1. 通过 pip 安装 `errbot`
2. 在某个位置创建一个目录（此处称为 `errbot`），用于存放 Errbot 的数据文件
3. 初始化该目录
4. 尝试在文本模式下使用 Errbot

.. code:: bash

    $ pip install errbot
    $ mkdir errbot; cd errbot
    $ errbot --init
    $ errbot

它将显示提示符 `>>>`，以便您可以直接与机器人对话！尝试输入 `!help` 开始使用。

添加对聊天系统的支持

对于内置支持的系统（Telegram、IRC、XMPP），只需使用 pip 安装相应的包即可。您也可以在初始安装完成后，再添加缺失的支持，例如：

$ pip install "errbot[irc]"

对于外部系统（Slack、Discord、Gitter、Skype 等），请按照各自 GitHub 页面上的说明进行操作。

配置

为了配置 Errbot 连接到这些聊天系统之一，您需要调整由 `errbot --init` 生成的 `config.py` 文件。

为了帮助您，我们在此提供一份已记录的模板：`config-template.py <https://raw.githubusercontent.com/errbotio/errbot/master/errbot/config-template.py>`_。

注意：即使您更改了配置中的 BACKEND，仍然可以使用 `errbot -T` 在本地文本模式下测试实例。

以守护进程方式启动 Errbot

如果一切正常，现在可以使用 -d（或 --daemon）参数以分离模式运行：

.. code:: bash

errbot --daemon

与机器人互动

启动 Errbot 后，如果您尚未将其添加到好友列表，请将其添加进去。在某些聊天系统上，您还需要明确邀请机器人进入聊天室。 现在您可以直接向机器人发送命令！

要获取所有可用命令的列表，可以输入：

.. code:: bash

!help

如果您只想了解某个特定命令的更多信息，可以输入：

.. code:: bash

!help command

管理插件

如果您的用户名在 `config.py` 中的 BOT_ADMINS 列表中，您可以在一对一聊天中管理机器人。

例如，要在公共插件仓库中进行关键词搜索，可以输入：

.. code:: bash

    !repos search jira

要从该列表中安装插件，可以输入：

.. code:: bash

    !repos install <仓库名称>


例如 `!repos install errbotio/err-imagebot`。

编写插件
---------------

编写自己的插件非常简单。运行 `errbot --init` 命令后，会在 `plugins` 子目录中安装一个名为 `err-example` 的插件，你可以将其用作基础。

例如，以下代码就是为 Errbot 创建一个“Hello, world!”插件所需的全部内容：

.. code:: python

    from errbot import BotPlugin, botcmd

    class Hello(BotPlugin):
        """Errbot 的“Hello, world!”示例插件"""

        @botcmd
        def hello(self, msg, args):
            """向你返回短语‘Hello, world!’"""
            return "Hello, world!"

这个插件会创建一个命令 `!hello`，当你执行该命令时，它会返回“Hello, world!”给你。有关插件的更多功能和用法，请参阅
`插件开发指南 <https://errbot.io/en/latest/user_guide/plugin_development/>`_。

对 Errbot 本身的贡献
---------------------

欢迎在 `github <https://www.github.com/errbotio/errbot>`_ 上 fork 项目并提出修改建议。

Errbot 快速上手指南

Errbot 是一个用 Python 编写的开源聊天机器人框架，支持通过聊天界面执行脚本、运维操作（ChatOps）、构建触发、监控报警等任务。它易于扩展，并支持多种即时通讯平台。

环境准备

• 操作系统：Linux, Windows, macOS
• Python 版本：Python 3.6 或更高版本
• 前置依赖：
  • 建议安装 virtualenv 以创建独立的虚拟环境。
  • 若需连接特定聊天平台（如 Telegram, Slack 等），需提前准备好相应的 Bot Token 或账号凭证。

安装步骤

推荐使用国内镜像源（如清华源）加速安装过程。

1. 创建并激活虚拟环境（可选但推荐）：

   python -m venv errbot-env
   # Linux/macOS:
   source errbot-env/bin/activate
   # Windows:
   errbot-env\Scripts\activate
   

2. 安装 Errbot：

   pip install -i https://pypi.tuna.tsinghua.edu.cn/simple errbot
   

3. 初始化工作目录： 创建一个目录用于存放配置文件和数据，并进行初始化。

   mkdir errbot-workdir
   cd errbot-workdir
   errbot --init
   

   执行后会在当前目录生成 config.py 等文件。

4. 安装特定后端支持（可选）： 如果需要连接内置支持的特定平台（如 IRC, Telegram, XMPP），需额外安装对应依赖：

   # 示例：安装 IRC 支持
   pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "errbot[irc]"
   
   # 示例：安装 Telegram 支持
   pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "errbot[telegram]"
   

   注：Slack, Discord, Gitter 等外部后端需参考其各自的 GitHub 仓库进行安装配置。

基本使用

1. 文本模式测试（无需配置聊天账号）

这是最快的体验方式，直接在终端与机器人交互。

errbot

启动后会出现 >>> 提示符，你可以直接输入命令：

>>> !help
>>> !hello

2. 编写第一个插件

errbot --init 已在 plugins 目录下生成了示例插件。你也可以手动创建一个简单的插件。

在 plugins 目录下新建文件 hello.py，内容如下：

from errbot import BotPlugin, botcmd

class Hello(BotPlugin):
    """一个简单的问候插件"""

    @botcmd
    def hello(self, msg, args):
        """返回 'Hello, world!'"""
        return "Hello, world!"

保存后，在运行的 Errbot 实例中（或重启后）即可使用 !hello 命令。

3. 连接真实聊天平台

若要连接真实的聊天软件（如 Telegram）：

1. 编辑生成的 config.py 文件。
2. 修改 BACKEND 变量（例如设为 'Telegram'）。
3. 填入对应的认证信息（如 BOT_TOKEN）。
4. 启动机器人：

   errbot
   

   或者以后台守护进程模式运行：

   errbot --daemon
   

启动成功后，在对应的聊天软件中添加机器人为好友或邀请其加入群组，即可通过发送 !help 开始交互。