2016-08-28 21:44:41 +02:00
# Mikubot V2
[![Build Status ](https://travis-ci.org/Akamaru/Mikubot-V2.svg?branch=master )](https://travis-ci.org/Akamaru/Mikubot-V2)
2016-06-15 02:02:12 +02:00
2016-06-22 20:44:51 +02:00
Der multifunktionale Telegram-Bot.
2015-07-08 04:24:12 +02:00
2016-08-28 21:44:41 +02:00
[Offizielle Webseite ](https://ponywave.de/projekte/mikubot-v2/ ) | [Entwickler auf Telegram ](http://telegram.me/Akamaru ) **KEIN SUPPORT!** | [Offizieller Telegram-Kanal ](https://telegram.me/Mikubot_Updates )
2015-07-08 04:24:12 +02:00
2016-08-25 12:16:43 +02:00
Mikubot ist ein auf Plugins basierender Bot, der die [offizielle Telegram Bot API ](http://core.telegram.org/bots/api ) benutzt. Geforkt wurde er von [Brawlbot ](https://github.com/Brawl345/Brawlbot-v2 ) Ursprünglich wurde er 2015 auf Basis von Yagops [Telegram Bot ](https://github.com/yagop/telegram-bot/ ) entwickelt, da aber die Entwicklung von tg-cli [zum Stillstand ](https://brawlbot.tk/posts/ein-neuanfang ) gekommen ist, wurden alle Plugins des bisher proprietären Brawlbots im Juni 2016 auf die Bot-API portiert und open-sourced. Im Juli und August 2016 wurden die zusätzlichen Plugins von Mikubot ebenfalls auf die Bot-API migriert.
2016-08-28 21:44:41 +02:00
**Mikubot V2 basiert auf [otouto ](https://github.com/topkecleon/otouto ) von Topkecleon.**
2015-07-08 04:24:12 +02:00
2016-08-28 21:44:41 +02:00
Mikubot V2 ist freie Software; du darfst ihn modifizieren und weiterverbreiten, allerdings musst du dich an die GNU Affero General Public License v3 halten, siehe **LICENSE** für Details.
2016-05-29 19:08:39 +02:00
2016-06-22 20:44:51 +02:00
##Anleitung
2016-05-31 01:10:58 +02:00
2016-06-22 20:44:51 +02:00
| Für User | Für Entwickler|
2016-05-31 01:10:58 +02:00
|:----------------------------------------------|:------------------------------|
2016-06-15 14:35:39 +02:00
| [Setup ](#setup ) | [Plugins ](#plugins ) |
2016-06-22 20:44:51 +02:00
| [Bot steuern ](#bot-steuern ) | [Bindings ](#bindings ) |
2016-07-05 13:14:22 +02:00
| | [Datenbank ](#datenbank )
2016-03-22 14:38:29 +01:00
2016-06-17 07:13:05 +02:00
* * *
2016-06-22 20:44:51 +02:00
# Für User
2016-03-22 14:38:29 +01:00
## Setup
2016-07-13 01:00:32 +02:00
### Ubuntu und Debian
2016-09-07 19:46:28 +02:00
Falls du Ubuntu oder Debian verwendest, kannst du einfach `./install-dependencies.sh` ausführen, damit alles installiert wird. Ergänze dann noch den `bot_api_key` und die `admin` -ID (Bekommst du in Telegram mit `@Mikubot id` ) und kopiere die config.lua.example nach config.lua.
2016-09-07 16:00:13 +02:00
2016-09-07 20:13:27 +02:00
###Optionale Pakete
Diese Pakete werden für `flip-text.lua` , `shell.lua` , `speedtest_cli.lua` und `youtube_dl.lua` benötigt.
```sudo apt-get install -y cowsay scrot fswebcam vnstat vnstati youtube-dl npm
sudo npm install -g flip-text
wget -O speedtest-cli https://raw.github.com/sivel/speedtest-cli/master/speedtest_cli.py
chmod +x speedtest-cli
sudo mv speedtest-cli /usr/local/bin/speedtest-cli```
2016-09-07 16:02:14 +02:00
Für eine manuelle Installation musst du LuaRocks für 5.2 [selbst kompilieren ](http://stackoverflow.com/a/20359102 ).
2016-07-13 01:00:32 +02:00
### Setup
2016-09-07 16:00:13 +02:00
Du benötigst **Lua 5.2** (Lua 5.3 funktioniert NICHT!), eine aktive **Redis-Instanz** und die folgenden **LuaRocks-Module** :
2016-09-05 13:59:57 +02:00
* luautf8
2016-06-22 20:44:51 +02:00
* luasocket
* luasec
* multipart-post
2016-08-03 19:21:07 +02:00
* dkjson
2016-06-22 20:44:51 +02:00
* lpeg
* redis-lua
2016-07-13 01:00:32 +02:00
* fakeredis
2016-06-22 20:44:51 +02:00
* oauth
* xml
* feedparser
* serpent
2016-04-05 13:10:53 +02:00
2016-06-22 20:44:51 +02:00
Klone danach diese Repo. kopiere die `config.lua.example` nach `config.lua` und trage folgendes ein:
2016-02-25 15:05:08 +01:00
2016-06-22 20:44:51 +02:00
- `bot_api_key` : API-Token vom BotFather
- `admin` : Deine Telegram-ID
2016-04-03 02:46:57 +02:00
2016-08-28 21:44:41 +02:00
Starte danach den Bot mit `sh launch.sh` . Um den Bot anzuhalten, führe erst `/halt` über Telegram aus.
2015-07-08 05:24:40 +02:00
2016-06-22 20:44:51 +02:00
Beim Start werden einige Werte in die Redis-Datenbank unter `telegram:credentials` und `telegram:enabled_plugins` eingetragen. Mit `/plugins enable` kannst du Plugins aktivieren, es sind nicht alle von Haus aus aktiviert.
2016-02-25 15:18:29 +01:00
2016-06-22 20:44:51 +02:00
Einige Plugins benötigen API-Keys, bitte gehe die einzelnen Plugins durch, bevor du sie aktivierst!
2016-02-25 15:17:19 +01:00
2016-01-08 04:30:12 +01:00
* * *
2015-11-25 03:22:04 +01:00
2016-06-22 20:44:51 +02:00
## Bot steuern
Ein Administrator kann den Bot über folgende Plugins steuern:
2016-02-25 15:05:08 +01:00
2016-06-22 20:44:51 +02:00
| Plugin | Kommando | Funktion |
2016-05-27 05:28:44 +02:00
|:----------------|:-----------|:---------------------------------------------------|
2016-06-22 20:44:51 +02:00
| `banhammer.lua` | Siehe /hilfe banhammer| Blockt User vom Bot und kann Whitelist aktivieren
| `control.lua` | /restart | Startet den Bot neu |
| | /halt | Speichert die Datenbank und stoppt den Bot |
| `plugins.lua` | /plugins enable/disable | Aktiviert/deaktiviert Plugins |
2016-08-28 21:44:41 +02:00
| `shell.lua` | /cmd | Führt Shell-Kommandos aus |
2015-11-25 03:22:04 +01:00
2016-01-08 04:30:12 +01:00
* * *
2015-11-25 03:22:04 +01:00
2016-06-22 20:44:51 +02:00
## Liste aller Plugins
2015-07-11 05:43:30 +02:00
2016-08-28 21:44:41 +02:00
Mikubot erhält laufend neue Plugins und wird kontinuierlich weiterentwickelt! Siehe [hier ](https://github.com/Akamaru/Mikubot-V2/tree/master/miku/plugins ) für eine Liste aller Plugins.
2015-07-08 09:38:04 +02:00
2016-06-22 20:44:51 +02:00
* * *
#Für Entwickler
2016-05-31 01:10:58 +02:00
## Plugins
2016-08-25 12:16:43 +02:00
Mikubot benutzt ein Plugin-System, ähnlich Yagops [Telegram-Bot ](http://github.com/yagop/telegram-bot ).
2016-05-31 01:10:58 +02:00
2016-07-15 15:14:31 +02:00
Ein Plugin kann zehn Komponenten haben, aber nur zwei werden benötigt:
2016-05-31 01:10:58 +02:00
2016-06-22 20:44:51 +02:00
| Komponente | Beschreibung | Benötigt? |
2016-06-15 14:35:39 +02:00
|:------------------|:---------------------------------------------|:----------|
2016-06-22 20:44:51 +02:00
| `plugin:action` | Hauptfunktion. Benötigt `msg` als Argument, empfohlen wird auch `matches` als drittes Argument nach `config` | J |
2016-07-15 15:13:00 +02:00
| `plugin.triggers` | Tabelle von Triggern (Lua-Patterns), auf die der Bot reagiert | J |
2016-07-15 15:14:31 +02:00
| `plugin.inline_triggers` | Tabelle von Triggern (Lua-Patterns), auf die der Bot bei Inline-Querys reagiert | N |
2016-06-22 20:44:51 +02:00
| `plugin:init` | Optionale Funkion, die beim Start geladen wird | N |
| `plugin:cron` | Wird jede Minute ausgeführt | N |
| `plugin.command` | Einfaches Kommando mit Syntax. Wird bei `/hilfe` gelistet | N |
| `plugin.doc` | Plugin-Hilfe. Wird mit `/help $kommando` gelistet | N |
| `plugin.error` | Plugin-spezifische Fehlermeldung | N |
2016-08-07 20:45:51 +02:00
| `plugin:callback` | Aktion, die ausgeführt wird, nachdem auf einen Callback-Button gedrückt wird. Siehe `gImages.lua` für ein Beispiel. Argumente: `callback` (enthält Callback-Daten), `msg` , `self` , `config` , `input` (enthält Parameter ohne `callback` ) | N |
2016-07-15 15:13:00 +02:00
| `plugin:inline_callback` | Aktion, die ausgeführt wird, wenn der Bot per Inline-Query ausgelöst wird. Argumente sind `inline_query` für die Daten, `config` und `matches` | N |
2016-05-31 01:10:58 +02:00
2016-06-22 20:44:51 +02:00
Die`bot:on_msg_receive` Funktion fügt einige nützte Variablen zur ` msg` Tabelle hinzu. Diese sind:`msg.from.id_str`, `msg.to.id_str` , `msg.chat.id_str` , `msg.text_lower` , `msg.from.name` .
2016-05-31 01:10:58 +02:00
2016-06-22 20:44:51 +02:00
Interaktionen mit der Bot-API sind sehr einfach. Siehe [Bindings ](#bindings ) für Details.
2016-05-31 01:10:58 +02:00
2016-06-22 20:44:51 +02:00
Einige Funktionen, die oft benötigt werden, sind in `utilites.lua` verfügbar.
2016-05-31 01:10:58 +02:00
* * *
## Bindings
2016-08-25 12:42:52 +02:00
Die Telegram-API wird mithilfe der `binding.lua` über die multipart-post Library kontaktiert. Mikubots Bindings-Datei unterstützt alle Standard API-Methoden und Argumente. Die Hauptufnktion `bindings.request` akzeptiert drei Parameter: `method` , `parameters` und `file` . Bevor du die Bindings-Datei nutzt, initialisiere das Modul mit der `init` -Funktion, wobei der Bot-Token als Argument übergeben werden sollte.
2016-08-24 15:38:29 +02:00
2016-08-25 12:42:52 +02:00
`method` ist der Name der API-Methode (bspw. `sendMessage` ), `parameters` (optional) ist eine Tabelle mit Schlüssel/Werte-Paaren der Parameter dieser Methode. `file` (optional) ist eine Tabelle mit einem einzigen Schlüssel/Werte-Paar, wobei der Schlüssel der Name de Parameters und der Wert der Dateiname oder die File-ID ist (wenn dies in den `parameters` übergeben wird, wird Mikubot den Dateinamen als File-ID senden).
2016-05-31 01:10:58 +02:00
2016-08-25 12:40:06 +02:00
Zusätzlich kann jede Methode als Schlüssel in der `bindings` Tabelle (zum Beispiel `bindings.getMe` ) aufgerufen werden. Die `bindings.gen` Funktion (welche auch die `__index` Funktion in der Metatabelle ist) wird ihre Argumente an `bindings.request` in der richtigen Form übergeben. Mit diesem Weg sind die folgenden zwei Funktionsaufrufe gleich:
2016-05-31 01:10:58 +02:00
```
bindings.request(
2016-08-14 04:46:18 +02:00
'sendMessage',
{
chat_id = 987654321,
2016-08-25 12:42:52 +02:00
text = 'Mikubot is best bot.',
2016-08-14 04:46:18 +02:00
reply_to_message_id = 54321,
disable_web_page_preview = false,
parse_method = 'Markdown'
}
2016-05-31 01:10:58 +02:00
)
2016-08-23 06:16:32 +02:00
bindings.sendMessage{
chat_id = 987654321,
2016-08-25 12:42:52 +02:00
text = 'Mikubot is best bot.',
2016-08-23 06:16:32 +02:00
reply_to_message_id = 54321,
disable_web_page_preview = false,
parse_method = 'Markdown'
}
2016-05-31 01:10:58 +02:00
```
2016-08-25 12:40:06 +02:00
`utilities.lua` hat mehrere "Abkürzungen", die dir das leben einfacher machen. Z.b.:
2016-05-31 01:10:58 +02:00
```
2016-08-25 12:42:52 +02:00
utilities.send_message(987654321, 'Mikubot is best bot.', false, 54321, true)
2016-05-31 01:10:58 +02:00
```
2016-08-25 12:40:06 +02:00
Eine Datei mit `sendPhoto` hochzuladen würde so aussehen:
2016-05-31 01:10:58 +02:00
```
2016-08-25 12:40:06 +02:00
utilites.sendPhoto(987654321, 'photo.jpg', 'Beschreibungstext')
2016-05-31 01:10:58 +02:00
```
2016-08-25 12:40:06 +02:00
oder mit einer File-ID:
2016-05-31 01:10:58 +02:00
```
2016-08-25 12:40:06 +02:00
utilites.sendPhoto(987654321, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789', 'Beschreibungstext')
2016-05-31 01:10:58 +02:00
```
2016-08-25 12:40:06 +02:00
Falls erfolgreich, wird bindings das deserialisierte Ergebniss der API zurückgeben. Falls nicht erfolgreich, wird `false` und das Ergebnis zurückgegeben. Falls es einen Verbindungsfehler gab, werden zwei `false` Werte zurückgegeben. Wenn ein invalider Methodenname übergeben wurde, wird bindings eine Exception ausgeben. Damit sollen "stille Fehler" vermieden werden.
2016-05-31 01:10:58 +02:00
* * *
2016-07-05 13:14:22 +02:00
## Datenbank
2016-08-25 12:16:43 +02:00
Mikubot benutzt eine interne Datenbank, wie Otouto sie benutzt und Redis. Die "Datenbank" ist eine Tabelle, auf die über die Variable `database` zugegriffen werden kann (normalerweise `self.database` ) und die als JSON-encodierte Plaintext-Datei jede Stunde gespeichert wird oder wenn der Bot gestoppt wird (über `/halt` ).
otouto 3.11
"things occurred"
Added some utilities (id_from_username, id_from_message), removed some utilities (latcyr, others?).
Removed cycle-wasting "shortcuts" -- no more automatic id_str or name; text_lower remains.
Moved userdata (nicknames, lastfm, etc) to a different tree in the database (automatic migration will occur). /me now returns userdata.
Speaking of migration, database now stores the latest version run to make future automigration easy.
Database now saves hourly rather than minutely.
Changed readme and some plugins to reflect above changes.
Removed broken rockspec (Brayden, feel free to re-add once it's working).
Added option to automatically block people (via drua) when blacklisted.
Fixed about.lua trigger problems.
administration 1.11 - Removed /kickme and /broadcast. Users should leave manually, and announcements should be made via channel rather than spam. /setqotd now handles forwarded messages correctly. /kick, /ban, /hammer,
/mod, /admin now support multiple arguments. Added get_targets function. No migration is necessary.
2016-07-05 09:29:11 +02:00
2016-07-05 13:14:22 +02:00
Das ist die Datenbank-Struktur:
otouto 3.11
"things occurred"
Added some utilities (id_from_username, id_from_message), removed some utilities (latcyr, others?).
Removed cycle-wasting "shortcuts" -- no more automatic id_str or name; text_lower remains.
Moved userdata (nicknames, lastfm, etc) to a different tree in the database (automatic migration will occur). /me now returns userdata.
Speaking of migration, database now stores the latest version run to make future automigration easy.
Database now saves hourly rather than minutely.
Changed readme and some plugins to reflect above changes.
Removed broken rockspec (Brayden, feel free to re-add once it's working).
Added option to automatically block people (via drua) when blacklisted.
Fixed about.lua trigger problems.
administration 1.11 - Removed /kickme and /broadcast. Users should leave manually, and announcements should be made via channel rather than spam. /setqotd now handles forwarded messages correctly. /kick, /ban, /hammer,
/mod, /admin now support multiple arguments. Added get_targets function. No migration is necessary.
2016-07-05 09:29:11 +02:00
```
{
users = {
["55994550"] = {
id = 55994550,
first_name = "Drew",
username = "topkecleon"
}
},
userdata = {
["55994550"] = {
2016-07-05 13:14:22 +02:00
nickname = "Best coder ever",
otouto 3.11
"things occurred"
Added some utilities (id_from_username, id_from_message), removed some utilities (latcyr, others?).
Removed cycle-wasting "shortcuts" -- no more automatic id_str or name; text_lower remains.
Moved userdata (nicknames, lastfm, etc) to a different tree in the database (automatic migration will occur). /me now returns userdata.
Speaking of migration, database now stores the latest version run to make future automigration easy.
Database now saves hourly rather than minutely.
Changed readme and some plugins to reflect above changes.
Removed broken rockspec (Brayden, feel free to re-add once it's working).
Added option to automatically block people (via drua) when blacklisted.
Fixed about.lua trigger problems.
administration 1.11 - Removed /kickme and /broadcast. Users should leave manually, and announcements should be made via channel rather than spam. /setqotd now handles forwarded messages correctly. /kick, /ban, /hammer,
/mod, /admin now support multiple arguments. Added get_targets function. No migration is necessary.
2016-07-05 09:29:11 +02:00
lastfm = "topkecleon"
}
},
2016-07-05 13:14:22 +02:00
version = "2.1"
otouto 3.11
"things occurred"
Added some utilities (id_from_username, id_from_message), removed some utilities (latcyr, others?).
Removed cycle-wasting "shortcuts" -- no more automatic id_str or name; text_lower remains.
Moved userdata (nicknames, lastfm, etc) to a different tree in the database (automatic migration will occur). /me now returns userdata.
Speaking of migration, database now stores the latest version run to make future automigration easy.
Database now saves hourly rather than minutely.
Changed readme and some plugins to reflect above changes.
Removed broken rockspec (Brayden, feel free to re-add once it's working).
Added option to automatically block people (via drua) when blacklisted.
Fixed about.lua trigger problems.
administration 1.11 - Removed /kickme and /broadcast. Users should leave manually, and announcements should be made via channel rather than spam. /setqotd now handles forwarded messages correctly. /kick, /ban, /hammer,
/mod, /admin now support multiple arguments. Added get_targets function. No migration is necessary.
2016-07-05 09:29:11 +02:00
}
```
2016-07-05 13:14:22 +02:00
`database.users` speichert User-Informationen, wie Usernamen, IDs, etc., wenn der Bot den User sieht. Jeder Tabellen-Key ist die User-ID als String.
2016-05-31 01:10:58 +02:00
2016-08-25 12:42:52 +02:00
`database.userdata` speichert Daten von verschiedenen Plugins, hierzu wird aber für Mikubot-Plugins Redis verwendet.
2016-01-08 04:30:12 +01:00
2016-09-07 16:00:13 +02:00
`database.version` speichert die Bot-Version.