This repository has been archived on 2021-04-24. You can view files and clone it, but cannot push or open issues or pull requests.
Mikubot-2/README.md

190 lines
9.3 KiB
Markdown
Raw Normal View History

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-09-11 14:07:55 +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-06-22 20:44:51 +02:00
##Anleitung
2016-06-22 20:44:51 +02:00
| Für User | Für Entwickler|
|:----------------------------------------------|:------------------------------|
| [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-22 20:44:51 +02:00
# Für User
2016-03-22 14:38:29 +01:00
## Setup
### 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
####Optionale Pakete
2016-09-07 20:13:27 +02:00
Diese Pakete werden für `flip-text.lua`, `shell.lua`, `speedtest_cli.lua` und `youtube_dl.lua` benötigt.
2016-09-07 20:18:59 +02:00
* `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 20:13:27 +02:00
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).
### 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
* fakeredis
2016-06-22 20:44:51 +02:00
* oauth
* xml
* feedparser
* serpent
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-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.
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-06-22 20:44:51 +02:00
## Bot steuern
Ein Administrator kann den Bot über folgende Plugins steuern:
2016-06-22 20:44:51 +02:00
| Plugin | Kommando | Funktion |
|:----------------|:-----------|:---------------------------------------------------|
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 |
* * *
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
## 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-07-15 15:14:31 +02:00
Ein Plugin kann zehn Komponenten haben, aber nur zwei werden benötigt:
2016-06-22 20:44:51 +02:00
| Komponente | Beschreibung | Benötigt? |
|:------------------|:---------------------------------------------|:----------|
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 |
| `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 |
| `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 |
| `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-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-06-22 20:44:51 +02:00
Interaktionen mit der Bot-API sind sehr einfach. Siehe [Bindings](#bindings) für Details.
2016-06-22 20:44:51 +02:00
Einige Funktionen, die oft benötigt werden, sind in `utilites.lua` verfügbar.
* * *
## 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-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).
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:
```
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'
}
)
bindings.sendMessage{
chat_id = 987654321,
2016-08-25 12:42:52 +02:00
text = 'Mikubot is best bot.',
reply_to_message_id = 54321,
disable_web_page_preview = false,
parse_method = 'Markdown'
}
```
`utilities.lua` hat mehrere "Abkürzungen", die dir das leben einfacher machen. Z.b.:
```
2016-08-25 12:42:52 +02:00
utilities.send_message(987654321, 'Mikubot is best bot.', false, 54321, true)
```
Eine Datei mit `sendPhoto` hochzuladen würde so aussehen:
```
utilites.sendPhoto(987654321, 'photo.jpg', 'Beschreibungstext')
```
oder mit einer File-ID:
```
utilites.sendPhoto(987654321, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789', 'Beschreibungstext')
```
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-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`).
2016-07-05 13:14:22 +02:00
Das ist die Datenbank-Struktur:
```
{
users = {
["55994550"] = {
id = 55994550,
first_name = "Drew",
username = "topkecleon"
}
},
userdata = {
["55994550"] = {
2016-07-05 13:14:22 +02:00
nickname = "Best coder ever",
lastfm = "topkecleon"
}
},
2016-07-05 13:14:22 +02:00
version = "2.1"
}
```
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-08-25 12:42:52 +02:00
`database.userdata` speichert Daten von verschiedenen Plugins, hierzu wird aber für Mikubot-Plugins Redis verwendet.
2016-09-07 16:00:13 +02:00
`database.version` speichert die Bot-Version.