/YZXXH++/Vliter/OneBot开发手册-初：前言

生活相关 学业
,
#1

前言：

众所周知，某人花了整整三个月，从零搭建并运行了名为⌈Vliter⌋的平台机器人，其间斥资无数，费心费力，身心受到极大的打击，但是功夫不负有心人，一整套自动响应，自行运转，自我迭代的Bot机制最终被完整的编译并运行了起来。

为了记录这段时光，并为后继有兴趣自行搭建项目的BotMaster们提供参考，我写下这篇开发日志，希望能给同好们一点参考，更希望有更多的人能有兴趣成为开发人员，和我们一起共同探索OneBot的无限可能！！

在开始之前，我们需要了解一些基本概念

关于机器人

机器人（Bot）

在不引发歧义的场合下，指聊天机器人（Chatbot）。

机器人平台（Bot Platform）

官方或非官方提供了聊天机器人 API 的聊天软件平台，例如 QQ、微信、微信公众号、企业微信、飞书、钉钉、Telegram、Discord、Facebook Messenger 等。

OneBot

OneBot 标准是什么？

OneBot 标准是对开发聊天机器人所使用的 API 的一个抽象，是对聊天机器人 API 的通信方式、传输的数据格式和字段等的一个标准化定义。如果将 OneBot 标准类比于 C 语言、ECMAScript、POSIX 标准等，则 OneBot 实现对应 GCC、Chrome V8、Linux 等。

OneBot 标准不是什么？

OneBot 标准，即本网站上的所有内容，只是一个文档，OneBot 标准本身没有一个中心化的官方实现，而是依赖社区中有兴趣、有能力的开发者们针对各个语言/运行时实现 LibOneBot、基于 LibOneBot 针对各个机器人平台实现 OneBot 标准、基于 OneBot 标准实现各种开发框架。

OneBot Connect

OneBot Connect 是 OneBot 应用与 OneBot 实现通过网络连接的规范，由两部分组成：

  • 通信方式规定了 OneBot 应用与 OneBot 实现进行网络连接所使用的通信协议、数据编码

  • 数据协议定义了 OneBot 应用与 OneBot 实现之间在各种通信方式上传输的数据

通信方式

OneBot Connect 目前包含四种通信方式，分别是：

  • HTTP：OneBot 实现作为 HTTP 服务端，提供动作调用服务

  • HTTP Webhook：OneBot 实现作为 HTTP 客户端，向用户配置的地址推送事件

  • 正向 WebSocket：OneBot 实现作为 WebSocket 服务端，接受客户端的接入，提供动作调用和事件推送服务

  • 反向 WebSocket：OneBot 实现作为 WebSocket 客户端，向用户配置的地址发起连接，提供动作调用和事件推送服务

数据协议

OneBot Connect 目前包含三种数据协议，分别是：

  • 事件：OneBot 实现自发产生或从机器人平台获得的消息、通知等，由 OneBot 实现向应用端推送

  • 动作请求：应用端向 OneBot 实现主动请求服务时所发送的动作调用请求

  • 动作响应：OneBot 实现在收到应用端的动作请求并处理完毕后，发回应用端的响应

任何与平台之间的连接，几乎都是基于以上方式实现的。最常见的，如Satori。

GitHub

GitHub 是一个在线软件托管服务平台，用于公开程序或软件的代码。（Wiki）

在部署过程中需要经常访问Github，来查看大佬们编写的插件及使用方法，debug过程中，Github中的Issues中，或许有和你相同的问题供你参考。

同时，魔法环境能让你更流畅的访问Github。

魔法环境

你需要一个稳定快速的魔法环境，由于国内厂商的垄断，大部分存储库都被迁移至非大陆地区。

Koishi

Koishi 是一个跨平台、可扩展、高性能的聊天机器人框架。

它的名字和图标设计来源于东方 Project 中的角色 古明地恋 (Komeiji Koishi)。古明地恋是一个会做出无意识举动的角色，取这个名字既象征着聊天机器人的主题，也蕴含了开发者为之倾注的热爱。

对比NoneBot，Avilla等，Koishi有简洁的控制管理面板，以及丰富的社区资源，更适合入门，同时对于维护和移植也更为友好

了解了这些概念，我们可以开始进行环境部署。

首先，你应该满足以下要求：

操作系统
Windows

同一产品只列出了其最高版本。未列出的版本一律视为不支持。

Windows 8.1​

产品 核心 窗口 增强
Windows 8.1 :white_check_mark: :white_check_mark: :x:
Windows Server 2012 R2 :white_check_mark: :white_check_mark: :x:
Hyper-V Server 2012 R2 :x: :x: :x:
Windows Storage Server 2012 R2 :x: :x: :x:
Windows Embedded 8.1 Pro :x: :x: :x:
Windows Embedded 8.1 Industry :x: :x: :x:

Windows 10​

产品 核心 窗口 增强
Version 1507 :x: :x: :x:
Version 1511 :x: :x: :x:
Version 1607 :x: :x: :x:
Version 1703 :x: :x: :x:
Version 1709 :x: :white_check_mark: :x:
Version 1803 :x: :white_check_mark: :x:
Version 1809 :x: :white_check_mark: :white_check_mark:
Version 1903 :x: :white_check_mark: :white_check_mark:
Version 1909 :x: :white_check_mark: :white_check_mark:
Version 2004 :x: :white_check_mark: :white_check_mark:
Version 20H2 :x: :white_check_mark: :white_check_mark:
Version 21H1 :x: :white_check_mark: :white_check_mark:
Version 21H2 :white_check_mark: :white_check_mark: :white_check_mark:
Version 22H2 :white_check_mark: :white_check_mark: :white_check_mark:
Windows 10 2015 LTSB :white_check_mark: :x: :x:
Windows 10 2016 LTSB :white_check_mark: :x: :x:
Windows 10 Enterprise 2015 LTSC :white_check_mark: :white_check_mark: :x:
Windows 10 Enterprise 2016 LTSC :white_check_mark: :white_check_mark: :x:
Windows 10 Enterprise LTSC 2019 :white_check_mark: :white_check_mark: :white_check_mark:
Windows 10 Enterprise LTSC 2021 :white_check_mark: :white_check_mark: :white_check_mark:
Windows 10 Enterprise multi-session :white_check_mark: :white_check_mark: :x:
Windows Server 2016 :white_check_mark: :white_check_mark: :x:
Hyper-V Server 2016 :x: :x: :x:
Windows Storage Server 2016 :x: :x: :x:
Windows Server 2019 :white_check_mark: :white_check_mark: :x:
Hyper-V Server 2019 :x: :x: :x:
Windows Server 2022 :white_check_mark: :white_check_mark: :x:
Windows 10 IoT Core :x: :x: :x:
Windows 10 IoT Core Services :x: :x: :x:
Windows 10 IoT Core LTSC :x: :x: :x:
Windows 10 IoT LTSC 2019 Core :x: :x: :x:
Windows 10 IoT Enterprise :x: :x: :x:
Windows 10 IoT Enterprise 2019 :x: :x: :x:
Windows 10 IoT Enterprise LTSB 2015 :x: :x: :x:
Windows 10 IoT Enterprise LTSB 2016 :x: :x: :x:
Windows 10 IoT Enterprise LTSC 2019 :x: :x: :x:
Windows 10 IoT Enterprise LTSC 2021 :x: :x: :x:
Windows Server IoT 2019 :x: :x: :x:
Windows Server IoT 2019 for Storage :x: :x: :x:
Windows Server IoT 2022 :x: :x: :x:

Windows 11​

产品 核心 窗口 增强
Version 21H2 :white_check_mark: :white_check_mark: :white_check_mark:
Version 22H2 :white_check_mark: :white_check_mark: :white_check_mark:
Windows 365 :white_check_mark: :white_check_mark: :white_check_mark:
Linux

Arch，Ubuntu等常规发版，前提是你可以驾驭

MacOS

建议选用M系列，版本不限，但是需要支持新版Chromiun内核

Android

Koishi支持在安卓系统部署，但是因为文件结构差异，目前此项目仍在早期开发中。部分功能可能不可用。

同时需要注意，PC与移动端插件迁移，也因此变得困难。

硬件

内存大小决定了你可以同时运行多少插件

硬盘容量决定了你可以同时安装多少插件，其速度会影响插件运行的稳定性和速率，同时，你需要足够的容量存放插件的配置文件，数据库以及log

CPU性能决定了运行的稳定性，以及启动停止的速度

足够大的显示器，用于Koishi窗口和浏览器一起查看，通常情况下，你会同时打开很多网页

GPU，没有特殊要求，但是请确保你的电脑能正常显示与渲染网页

一个你用的顺手的键盘/鼠标

一副耳机（相信我，音乐将缓解你在这个枯燥漫长的过程中大部分情绪问题）

现在开始部署基本的运行环境

安装
为Windows安装

MSI

更多版本

为MacOS安装

.pkg

更多版本

对于Linux，Docker与Android，请查看官方文档

基本的入门操作，官方文档有详细介绍，这里不再赘述

初始化完成后，你的桌面角标将出现Koishi的logo，在管理界面，你可以实时查看机器人的状态与数据信息

截屏2025-03-17 17.41.14
截屏2025-03-17 17.41.142760×2092 318 KB

首先我们要明确，你现在看到的界面，本质上是一个网页，基于系统自带的webview实现，其中的功能全部由插件提供，Koishi提供了基本的插件，使得用户可以基于可视化操作面板运行、维护Bot，以及添加社区提供的插件。

开始之前，你需要确保你的所有依赖保持在最新，如图：

截屏2025-03-17 17.49.56
截屏2025-03-17 17.49.562760×2092 526 KB

现在，你的Koishi已经基本能正常运行

1個讚