Open7

Errbotチャットボットを育てる

ピン留めされたアイテム
Takei KazuyaTakei Kazuya

このスクラップの前提

  • Arch Linux
  • Python 3.9
  • Errbot 6.1.7
  • Poertry
  • GitIgnore.io 準拠
Takei KazuyaTakei Kazuya

最初の一歩

Poetry環境の準備

$ mkdir /path/to/mybot
$ cd mybot
$ poetry init
-- errbot, blackを登録しておく
$ echo "[virtualenvs]
in-project = true" > poetry.toml
$ poetry install

Errbot環境の準備

$ poetry run errbot --init
Your Errbot directory has been correctly initialized!
Just do "errbot" and it should start in text/development mode.
$ echo '
BOT_PREFIX = "$"' >> config.py

Errbotの初期動作確認

$ poetry run errbot
01:09:46 INFO     errbot.bootstrap          Found Storage plugin: Shelf.
01:09:46 INFO     errbot.bootstrap          Found Backend plugin: Text
.
.
.
[@CHANGE_ME ➡ @errbot] >>> $about
This is Errbot version 6.1.7
• Visit http://errbot.io/ for more information about errbot in general.
• Visit http://errbot.io/en/latest/#user-guide for help with configuration,
  administration and plugin development.
 Errbot is built through the hard work and dedication of everyone who
contributes code, documentation and bug reports at https://github.com/errbotio
but a special thank you should be given to Guillaume Binet, Tali Petrover,
Ben van Daele, Paul Labedan and others at Mondial Telecom, the birthplace of
Errbot, without whom this project never would have grown into what it is today.

QA

BOT_PREFIX って?

Errbot がOpsコマンドとして認識するテキストが持つべき文字を定義している。
(なお、デフォルトでは!が設定されている)

なんで変えたの?

  • ! だと、例えば「!!!!???」みたいな感嘆符テキストのリアクションができなくなるから
  • $だと、エンジニア的にも「これはコマンド」みたいなのがわかりやすいかもしれないから
Takei KazuyaTakei Kazuya

組込されているコマンドを歩く

注意

自分が普段遣いしそうなのだけ、ピックアップします

$help

用意されているボットコマンド一覧を表示する。

>>> $help
All commands

 Backup
 Backup related commands.
• $backup - Backup everything.
 ChatRoom
 This is a basic implementation of a chatroom
• $room create - Create a chatroom.
• $room destroy - Destroy a chatroom.
(多数)

$status

各種プラグインの状況と簡単なシステム情報を表示する。

>>> $status
Yes I am alive...


    Plugins

┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status ┃ Name                  ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ A │ Help                  │
├────────┼───────────────────────┤
│ C │ Webserver             │
└────────┴───────────────────────┘
 A = Activated, D = Deactivated, B = Blacklisted, C = Needs to be configured
 Load 1.45, 1.69, 1.91
GC 0->181 1->6 2->1

$plugins

いくつかのサブコマンドがあり、プラグイン管理を行う。

$repos

いくつかのサブコマンドがあり、Errbotのプラグインリポジトリに対する各種操作を行う。

>>> $repos search weather

┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status ┃ Name                      ┃ Description                                        ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│        │ garmann/err-weather │ displays short weather informations for given city │
├────────┼───────────────────────────┼────────────────────────────────────────────────────┤
│        │ attakei/errbot-jp-weather │ Report weather in Japan                            │
├────────┼───────────────────────────┼────────────────────────────────────────────────────┤
│        │ nelsonam/meryl   │ Displays weather for a zip code                    │
├────────┼───────────────────────────┼────────────────────────────────────────────────────┤
│        │ rvm-xx/weather-bot │ Monsieur Meteo                                     │
└────────┴───────────────────────────┴────────────────────────────────────────────────────┘
Takei KazuyaTakei Kazuya

機能を追加する

Errbotの主要な役割である「メッセージに対する応答」はBotプラグインを追加することで増やすことが出来る。

探す

ErrbotのリポジトリWikiに、不定期に更新されているプラグイン一覧があるので、気になるのを探してみると良い。[1]

実際に追加する

Wikiの方にはインストール時のコマンドが載っている。これをそのままBotに伝えればインストールをしてくれる。

>>> $repos install https://github.com/garmann/err-weather
Installing https://github.com/garmann/err-weather...
A new plugin repository has been installed correctly from https://github.com/garmann/err-weather. Refreshing the plugins commands...
Plugins reloaded.

Enumerating objects: 21, done.
Total 21 (delta 0), reused 0 (delta 0), pack-reused 21
Checking out 8d48a134ca565ebadbd91632babc7716da09b482
>>> $status plugins
Plugins

┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status ┃ Name                  ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ A │ weatherinfo           │
└────────┴───────────────────────┘

使ってみる

コマンドの引数などの情報がわからない場合は、$help {プラグイン名}で確認すると良い。

$help weatherinfo
weatherinfo
 grab short weather informations around the globe
• $weather - ($ berlin) grab weather information for cities an regions

使ってみた結果がこちら。

$weather tokyo

japan/tokyo/tokyo at 19:00: 1 C, sleet showers ( 1.0 mm rain ), 4.1 mps wind from NW.
脚注
  1. 更新頻度が低いので注意が必要 ↩︎

Takei KazuyaTakei Kazuya

Botプラグインを作る...ための事前準備をする

自分の欲しいBotプラグインが存在しない場合は、自分でどうにか作る必要がある。
そのための下準備として、Errbot環境の新規作成時に用意されるサンプルプラグインを追いかけてみる。

※そもそもErrbotにおける「プラグイン」とは何かについては、こちらの記事を参照。

位置関係とファイル構造の確認

$ ls
config.py  data  errbot.log  plugins  poetry.lock  poetry.toml  __pycache__  pyproject.toml
$ ls -R plugins
plugins:
err-example

plugins/err-example:
example.plug  example.py

環境のトップにpluginsフォルダがあり、さらにその中にerr-exampleというフォルダがある。
この中が自作Botプラグインを管理する場所となっていて、基本的にはErrbotの動作設定系が終わった後は、この中しか見ない。

このpluginsフォルダはconfig.py内にBOT_EXTRA_PLUGIN_DIRとして指定されているので、もし変更したい場合はそちらを変更して引っ越す。

example.pyとexample.plug

plugins/err-example内には、example.plug,example.pyという2個のファイルが存在する。
このうちexample.plugがプラグインのメタデータファイルとなっており、.plugファイルの存在を持ってコアはプラグインを認識する。

極論plugins直下に.plugファイルを並べて様々なコードを並べることも可能かもしれないが、
なるべく1個のプラグインに複数の役割を持たせずに「1プラグイン1フォルダ」を保つほうが管理しやすい。

example.plug

シンプルなので、まずはもともとの全文にコメントを添えて解説する。

; プラグインのErrbot上の振る舞いに関する定義
[Core]
Name = Example   ; プラグインの名前、Errbot環境全体で重複できない
Module = example ; プラグインが実際にロードするPythonソース名

[Documentation]
Description = This is a simple plugin example to get you started. ; プラグインの説明

[Python]
Version = 2+ ; プラグインが対応しているPythonのバージョン

Core.Moduleについて

plugファイルのコメントにも書いたとおり、ModuleにはPythonソースを指定するのだが、
次のようなルールとなっている。

  • plugファイルと同じ階層配下である
  • その階層から、Moduleの末尾に.pyをつけたときのファイル名が存在する

それぞれ注意しないといけない点があり、「親フォルダのものは一切指定不可能」「サブフォルダの指定時は.ではなく/」ということを忘れないようにしたい。

例えば、

err-example/
  example.plug
  hello/
    hello.py

といった構造の場合、hello/hello.pyを指定するためには、Module = hello.helloではなくModule = hello/helloと指定する。

example.py

こちらもまずは全文を記載する。

from errbot import BotPlugin, botcmd

class Example(BotPlugin):
    @botcmd  # flags a command
    def tryme(self, msg, args):  # a command callable with !tryme
        return "It *works* !"  # This string format is markdown.

BotPluginを継承したExampleが定義されている。これがplug経由で利用されるBotプラグインの本体となる。
補足点として、

  • クラス名はあまり重要ではない
  • このモジュールにBotPluginを継承したクラスは1個だけしか存在してはいけない

このクラスには、インスタンスメソッドとしてtrymeが定義されており、@botcmdでデコレートされている。
この、「『BotPluginを継承したクラス』内で定義された『@botcmdでデコレートされたメソッド』」が全てErrbotのBotコマンドとして登録される。

このプラグインをロードした場合は、$trymeというコマンドが登録される。

登録されたコマンドをBotバックエンド上で呼び出すと、Example.trymeを実行して、その返り値をもとにBotバックエンドに結果を返す。
今回の場合はIt *works* !というテキストを返している。文字列を返した場合は粗文字列をそのままBotバックエンドへ届けるように処理が続行される。

Takei KazuyaTakei Kazuya

Botプラグインを作る...ので最初のコードを読む

今回は、Errbotの機能に則って実際にプラグインの自作部分に手を付けるまで。

Errbotが提供するプラグインの新規作成コマンド

ErrbotのCLIコマンドのerrbotにはプラグインをテンプレートから作成する機能がある。

$ poetry run errbot --new-plugin plugins/web-search
This wizard will create a new plugin for you in "plugins/web-search".
What should the name of your new plugin be?
> Custom Web Search
What may I use as a short (one-line) description of your plugin?
> Provide web search by keyword
Which minimum version of errbot will your plugin work with? Leave blank to support any version or input CURRENT to select the current version 6.1.7.
>
Which maximum version of errbot will your plugin work with? Leave blank to support any version or input CURRENT to select the current version 6.1.7.
>
Success! You'll find your new plugin at 'plugins/web-search/custom_web_search.plug'
(Don't forget to include a LICENSE file if you are going to publish your plugin).

--new-plugin に「どのフォルダでプラグインを管理するか」を指定することで、ウィザードが開始される。

ウィザードの簡単な解説

このウィザードでは、基本的にplugファイルの中身を入力していくことになる。

What should the name of your new plugin be?

Errbot内で使われるBotプラグイン名を指定する。(Core.nameの部分)
以前の投稿でも書いたとおり、Errbot環境下で同じプラグイン名は使用できないので注意が必要。

What may I use as a short (one-line) description of your plugin?

いわゆるプラグインの説明でDocumentation.description用の領域。
ここに関しては、あまり気にせず指定して良い。

Which minimum version of errbot will your plugin work with? Leave blank to support any version or input CURRENT to select the current version 6.1.7.

Which maximum version of errbot will your plugin work with? Leave blank to support any version or input CURRENT to select the current version 6.1.7.

それぞれ、プラグインが対象としているErrbotのコアバージョンの下限と上限。
デフォルトでは、コマンド実行時のCLIバージョンになる。

公開を前提するならある程度下のバージョンを考慮したほうが良いかもしれないが、
普段はあまり気にする必要がない。

この4項目を入力し終えると、引数で指定したフォルダの作成と、プラグイン名をもとにしたplugファイルとpyファイルを生成を行う。