Errbotチャットボットを育てる
このスクラップの前提
- Arch Linux
- Python 3.9
- Errbot 6.1.7
- Poertry
- GitIgnore.io 準拠
最初の一歩
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コマンドとして認識するテキストが持つべき文字を定義している。
(なお、デフォルトでは!
が設定されている)
なんで変えたの?
-
!
だと、例えば「!!!!???」みたいな感嘆符テキストのリアクションができなくなるから -
$
だと、エンジニア的にも「これはコマンド」みたいなのがわかりやすいかもしれないから
組込されているコマンドを歩く
注意
自分が普段遣いしそうなのだけ、ピックアップします
$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 │
└────────┴───────────────────────────┴────────────────────────────────────────────────────┘
機能を追加する
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.
-
更新頻度が低いので注意が必要 ↩︎
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バックエンドへ届けるように処理が続行される。
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
ファイルを生成を行う。
(次:テンプレートの中身を読む)