KiviBot: Lightweight, Efficient, Cross-Platform QQ Bot#
date: January 27, 2023
slug: 18
status: Published
tags: Technology
type: Post
Bot Introduction#
KiviBot is a lightweight, elegant, cross-platform, developer-friendly, just works QQ bot framework written in TypeScript.
The framework provides comprehensive state monitoring, plugin management (supporting hot updates), a main and sub-admin mechanism, message notifications, request handling capabilities, and a friendly scaffolding, ready to use out of the box. The framework is fully open-source, highly extensible, and simple to develop plugins for, using the core underlying protocol oicq v2, with numerous APIs and powerful features. Additionally, the framework is driven by node, and thanks to Node and its efficient V8 engine, KiviBot's performance is impressive.
Installation#
1. Using on Linux Platform#
i. Install Node.js#
You can install it using the corresponding package manager or go to the official website (I chose Baota). It is recommended to use version 18, with a minimum of version 14, and ensure that environment variables (including
NODE_HOME
variable) are configured properly to ensure that the command line can access
node
and
npm
commands normally.
If you still cannot start the bot after configuring the environment variables, running the following code can work wonders:
echo -e "export PATH=(npmprefix−g)/bin:(npm prefix -g)/bin:(npmprefix−g)/bin:PATH" >> ~/.bashrc && source ~/.bashrc
(Should be my fault too)
ii. Globally Install KiviBot CLI#
CLI (Command Line Interface) refers to a way of operating a computer system by entering text commands in a terminal or command line. In CLI, users input commands via the keyboard, and the computer executes corresponding operations based on those commands. CLI is more flexible and powerful compared to graphical interfaces (GUI), making it the preferred choice for programmers and system administrators.
npm i -g kivibot@latest
Of course, you can also choose not to install globally and use npm kivi to execute CLI commands.
iii. Generate Configuration File via CLI#
# Create an empty directory as the framework directory, and switch to this directory
mkdir ~/bot && cd ~/bot
# Generate a configuration file in the current directory via CLI
kivi init
iv. Start KiviBot#
kivi start
v. Background Deployment (Optional)#
kivi deploy
# The CLI will use pm2 to deploy the framework process in the background
2. Using on Windows Platform#
Deployment method is the same as above.
3. Using KiviBot on Android Platform#
i. Download and Install Termux#
This step should be self-explanatory, right?
ii. Configure Termux Domestic Mirror Source#
sed -i 's@^\(deb.*stable main\)$@#\1\ndeb https://mirrors.aliyun.com/termux/termux-packages-24 stable main@' $PREFIX/etc/apt/sources.list
sed -i 's@^\(deb.*games stable\)$@#\1\ndeb https://mirrors.aliyun.com/termux/game-packages-24 games stable@' $PREFIX/etc/apt/sources.list.d/game.list
sed -i 's@^\(deb.*science stable\)$@#\1\ndeb https://mirrors.aliyun.com/termux/science-packages-24 science stable@' $PREFIX/etc/apt/sources.list.d/science.list
pkg update
iii. Install Node.js#
pkg install nodejs
The Remaining Steps are the Same as Linux Installation#
In fact, all installation methods run Node through a simulated/installed Linux environment, so theoretically, even your electronic watch can run KiviBot, and it might even have enough performance.
Configuration#
After installing according to the steps, you should receive a notification that the Bot is online. Now, you can send the command
/help
to view the list of commands supported by the framework.
Message Commands#
KiviBot
has no UI interface; operations like plugin management, admin changes, and state monitoring are all implemented through
QQ Message Commands.
Send the bot
/help
to view all framework commands,
for admin use only,
valid in both private and group chats. The list of all message commands for the framework:
KiviBot CLI Commands#
KiviBot CLI is the framework's scaffolding, also known as the command line tool, which is the command you use to start the framework:
kivi
You can use it to assist in generating configuration files, installing plugins and dependencies, starting the framework, etc. Entering
kivi
will show you the detailed usage of the CLI. The table below lists all CLI commands and their descriptions.
Configuration File#
The
kivi.json
in the framework directory is the configuration file for
KiviBot
```, containing a series of framework configurations that can be manually modified and will take effect after a restart.
> kivi start
>
>
> ```
> kivi.json
> ```
>
> ```
> app.js
> ```
>
{
// Bot QQ account, generated by CLI
"account": 114514,
// Login method, generated by CLI, options are password (password login) and qrcode (QR code login)
"login_mode": "password",
// Device lock verification method, generated by CLI when choosing password login; if choosing QR code, defaults to verification code login
// Options are sms (SMS verification code) and qrcode (QR code verification)
"device_mode": "sms",
// Framework log message display mode, defaults to short (concise mode, ignores CQ code, consumes less resources)
// Can also be set to detail (detailed mode, will show CQ code specific content, helpful for debugging plugins)
"message_mode": "short",
// Bot account password, generated by CLI when choosing password login; if choosing QR code, defaults to empty
"password": "",
// Framework log output level, defaults to info; set to off to not output logs, can be set to debug for debugging plugins
"log_level": "info",
// Admin list, generated by CLI, the first is the main admin (required), the rest are sub-admins (optional)
"admins": [1141284758],
// List of enabled plugins, including npm plugins (starting with kivibot-plugin-) and plugins in the plugins directory
// For npm plugins (starting with kivibot-plugin-), ignore the kivibot-plugin- prefix
"plugins": ["demo"],
// Bot event notifications
"notice": {
// Whether to enable, can be switched in real-time via message commands /config notice on and /config notice off
"enable": true,
// Friend list related configurations
"friend": {
// Friend request
"request": {
// Whether to enable friend request notification, defaults to enabled (true), set to false to disable
"enable": true,
// Handle friend requests, options: ignore (ignore, default), accept (agree), refuse (reject)
"action": "ignore"
},
// New friend notification, defaults to enabled (true), set to false to disable
"increase": true,
// Friend decrease notification, defaults to enabled (true), set to false to disable
"decrease": true,
// Friend private message notification, defaults to disabled (false), set to true to enable
"message": false
},
// Group chat related configurations
"group": {
// Invite bot to group
"request": {
// Whether to enable notification, defaults to enabled (true), set to false to disable
"enable": true,
// Handle group invitations, options: ignore (ignore, default), accept (agree), refuse (reject)
"action": "ignore"
},
// New group chat notification, defaults to enabled (true), set to false to disable
"increase": true,
// Group chat decrease notification, defaults to enabled (true), set to false to disable
"decrease": true,
// Bot being muted notification, defaults to enabled (true), set to false to disable
"ban": true,
// Group admin change notification, defaults to enabled (true), set to false to disable
"admin": true,
// Group transfer notification, defaults to enabled (true), set to false to disable
"transfer": true
}
},
// oicq protocol configuration, refer to oicq documentation, data directory limited to data/oicq, cannot be manually modified
"oicq_config": {
// Login protocol: 1 for Android phone, 2 for Android tablet, 3 for Android watch, 4 for MacOS, 5 for iPad
"platform": 5,
// oicq log level, oicq logs will be output to the logs folder in the framework directory
"log_level": "info",
// In group chat, whether to ignore the bot's own messages, defaults to ignore, set to false to not ignore
"ignore_self": true,
// Whether to automatically select the optimal server, defaults to enabled, set to false to disable
// If disabled, will always use msfwifi.3g.qq.com:8080 for connection
"auto_server": true,
// Whether to cache group member list, defaults to cache for efficiency; disabling will significantly reduce memory usage
"cache_group_member": true,
// Reconnection interval when disconnected due to network issues, defaults to 5 (seconds), set to 0 for no automatic reconnection
"reconn_interval": 5,
// Whether to attempt to send in fragments when being risk-controlled, defaults to true; set to false to not send in fragments
"resend": true,
// Specify ffmpeg path
"ffmpeg_path": "ffmpeg",
// Specify ffprobe path
"ffprobe_path": "ffprobe"
}
}
## **Common Issues**
There will be many common issues, but I'm too lazy to look at them, just make do with it.
# **Plugins**
The plugins for
KiviBot
are divided into two types:
- `npm plugins`
- `local plugins` Regardless of whether they are npm plugins or local plugins, they should conform to the `CommonJS` specification of node modules. Plugin configuration files are uniformly placed in the `framework directory/data/plugins/<name>` corresponding directory (usually the `config.json` file), **unless otherwise specified, most official plugin configurations should be modified here; directly modifying the source code will lead to configuration being overwritten during updates, making it invalid.**
> Node module, i.e., there exists
>
>
> ```
> index.js
> ```
>
> ```
> package.json
> ```
>
> ```
> package.json
> ```
>
> ```
> main
> ```
>
## **npm Plugins**
Npm plugins are those that can be directly installed from npm using the message command
/plugin add
(also can be installed via
npm
or
kivi
commands in the terminal). Typically, these plugins follow the naming convention starting with
kivibot-plugin-
Official plugins will be released in this format on npm to enhance user experience. Npm plugins need to be installed before use; once installed, they will be stored in the framework directory under
node_modules
where you can find the source code of the plugins.
**When using message commands to install or enable plugins, there is no need to include the `kivibot-plugin-` prefix.**
## **Local Plugins**
As the name suggests, local plugins refer to those not published to npm (such as user-developed plugins or some private plugins) and do not need to be downloaded. They are stored in the framework directory under the
plugins
directory. Like npm plugins, each plugin should also be a node module that conforms to the
CommonJS
specification.
# **User Experience**
This bot is easy to configure, has many plugins, and is developer-friendly, but unfortunately, the author has run away. Although its conversation function has more bugs than the first version and does not support personality training settings, it has many flashy features (which are generally practical for me).
Let's wait for the ChatGPT API to open; the current 3.0 is too rigid.