diff --git a/docs/.vuepress/config.ts b/docs/.vuepress/config.ts index 264b04e8..11a424b2 100644 --- a/docs/.vuepress/config.ts +++ b/docs/.vuepress/config.ts @@ -5,7 +5,16 @@ import viteBundler from "@vuepress/bundler-vite"; export default defineUserConfig({ base: "/", - lang: "zh-CN", + locales: { + "/": { + // 设置正在使用的语言 + lang: "zh-CN", + }, + "/en/": { + // 设置正在使用的语言 + lang: "en-US", + }, + }, title: "LiteyukiBot 轻雪机器人", description: "LiteyukiBot | 轻雪机器人 | An OneBot Standard ChatBot | 一个OneBot标准的聊天机器人", head: [ diff --git a/docs/en/README.md b/docs/en/README.md new file mode 100644 index 00000000..846b8221 --- /dev/null +++ b/docs/en/README.md @@ -0,0 +1,83 @@ +--- +home: true +icon: home +title: Home +heroImage: https://cdn.liteyuki.icu/static/svg/lylogo-full.svg +heroImageDark: https://cdn.liteyuki.icu/static/svg/lylogo-full-dark.svg +bgImage: +bgImageDark: +bgImageStyle: + background-attachment: fixed +heroText: LiteyukiBot +tagline: LiteyukiBot A high-performance, easy-to-use chatbot framework and application + +actions: + - text: Get Started + icon: rocket + link: ./deployment/install.html + type: primary + + - text: Usage + icon: book + link: ./usage/basic_command.html + +highlights: + - header: Simple and Efficient + image: /assets/image/layout.svg + bgImage: https://theme-hope-assets.vuejs.press/bg/2-light.svg + bgImageDark: https://theme-hope-assets.vuejs.press/bg/2-dark.svg + bgImageStyle: + background-repeat: repeat + background-size: initial + features: + - title: 支持多种框架 + icon: robot + details: 兼容nonebot,melobot等,拥有良好的生态支持 + link: https://nonebot.dev/ + + - title: 便捷管理 + icon: plug + details: 使用包管理器,便捷管理插件及资源包 + + - title: 主题支持 + icon: paint-brush + details: 使用资源包对外观进行完全自定义 + link: https://bot.liteyuki.icu/usage/resource_pack.html + + - title: 国际化 + icon: globe + details: 通过资源包支持多种语言 + link: https://baike.baidu.com/item/i18n/6771940 + + - title: 简易使用 + icon: cog + details: 无需繁琐前期过程,开箱即用 + link: https://bot.liteyuki.icu/deployment/config.html + + - title: 超高性能 + icon: tachometer-alt + details: 500个插件,2s内启动 + + - title: 滚动更新 + icon: cloud-download + details: 让你的机器人保持最新提交 + + - title: 开源项目 + icon: code + details: 项目遵循MIT LICENCE开源,欢迎各位的贡献 + + - header: 快速部署 + image: /assets/image/box.svg + bgImage: https://theme-hope-assets.vuejs.press/bg/3-light.svg + bgImageDark: https://theme-hope-assets.vuejs.press/bg/3-dark.svg + highlights: + - title: 安装 Git 及 Python3.10+ + - title: 使用 git clone https://github.com/LiteyukiStudio/LiteyukiBot --depth=1 以克隆项目至本地。 + details: 如果无法连接到GitHub,可以使用 git clone https://gitee.com/snowykami/LiteyukiBot --depth=1。 + - title: 使用 cd LiteyukiBot 切换到项目目录。 + - title: 使用 pip install -r requirements.txt 安装项目依赖。 + details: 如果你有多个 Python 环境,请使用 pythonx -m pip install -r requirements.txt。 + - title: 使用 python main.py 启动项目。 +copyright: © 2021-2024 SnowyKami All Rights Reserved + +--- diff --git a/docs/en/deployment/README.md b/docs/en/deployment/README.md new file mode 100644 index 00000000..934c319e --- /dev/null +++ b/docs/en/deployment/README.md @@ -0,0 +1,8 @@ +--- +title: 项目部署 +index: false +icon: laptop-code +category: 部署 +--- + + diff --git a/docs/en/deployment/cfg.txt b/docs/en/deployment/cfg.txt new file mode 100644 index 00000000..af5aecd2 --- /dev/null +++ b/docs/en/deployment/cfg.txt @@ -0,0 +1,9 @@ +# note +开发者选项 +allow_update: true # 是否允许更新 +log_level: "INFO" # 日志等级 +log_icon: true # 是否显示日志等级图标(某些控制台字体不可用) +auto_report: true # 是否自动上报问题给轻雪服务器 +auto_update: true # 是否自动更新轻雪,每天4点检查更新 +safe_mode: false # 安全模式,开启后将不会加载任何第三方插件 +dev_mode: false # 开发者模式,开启后将会启动看门狗 \ No newline at end of file diff --git a/docs/en/deployment/config.md b/docs/en/deployment/config.md new file mode 100644 index 00000000..50067718 --- /dev/null +++ b/docs/en/deployment/config.md @@ -0,0 +1,78 @@ +--- +title: 配置 +icon: cog +order: 2 +category: 使用指南 +tag: + - 配置 + - 部署 +--- + +轻雪支持`yaml`、`json`和`toml`作为配置文件,取决于你个人的喜好 + +首次运行后生成`config.yml`和`config`目录,你可修改配置项后重启轻雪,绝大多数情况下,你只需要修改`superusers`及`nickname`字段即可 + +启动时会加载项目目录下`config.yml/yaml/json/toml`和`config`目录下的所有配置文件,你可在`config`目录下创建多个配置文件,轻雪会自动合并这些配置文件 + +## **基础配置项** + +```yaml +nonebot: + # Nonebot机器人的配置,以前的最外层配置项仍可为Nonebot服务,但是部分内容会被覆盖,请尽快迁移 + command_start: [ "/", "" ] # 指令前缀,若没有""空命令头,请开启alconna_use_command_start保证alconna解析正常 + host: 127.0.0.1 # 监听地址,默认为本机,若要接收外部请求请填写0.0.0.0 + port: 20216 # 绑定端口 + nickname: [ "liteyuki" ] # 机器人昵称列表 + superusers: [ "1919810" ] # 超级用户列表 +liteyuki: + # 写在外层的配置项将会被覆盖,建议迁移到liteyuki下 + log_level: "INFO" # 日志等级 + log_icon: true # 是否显示日志等级图标(某些控制台字体不可用) + auto_report: true # 是否自动上报问题给轻雪服务器 + auto_update: true # 是否自动更新轻雪,每天4点检查更新 + plugins: [ ] # 轻雪插件列表 + plugin_dirs: [ ] # 轻雪插件目录列表 +``` + +## **其他配置** + +以下为默认值,如需自定义请手动添加 + +```yaml +# 高级NoneBot配置 +nonebot: + onebot_access_token: "" # 访问令牌,对公开放时建议设置 + default_language: "zh-CN" # 默认语言 + alconna_auto_completion: false # alconna是否自动补全指令,默认false,建议开启 + safe_mode: false # 安全模式,开启后将不会加载任何第三方NoneBot插件 + # 其他Nonebot插件的配置项 + custom_config_1: "custom_value1" + custom_config_2: "custom_value2" + +# 开发者选项 +liteyuki: + allow_update: true # 是否允许更新 + debug: false # 轻雪调试,开启会自动重载Bot或者资源,其他插件自带的调试功能也将开启 + dev_mode: false # 开发者模式,开启后将会启动监视者,监视文件变化并自动重载 + +... +``` + +> [!tip] +> 如果要使用NoneBot和dotenv配置文件,请自行创建`.env.{ENVIRONMENT}`,并在`config.yml`中添加`nonebot.environment:{ENVIRONMENT}`字段 + +## **与NoneBot对接的OneBot实现端配置** + +生产环境中推荐反向WebSocket +不同的实现端给出的字段可能不同,但是基本上都是一样的,这里给出一个参考值 + +| 字段 | 参考值 | 说明 | +|-------------|------------------------------------|----------------------------------| +| 协议 | 反向WebSocket | 推荐使用反向ws协议进行通信,即轻雪作为服务端 | +| 地址 | ws://127.0.0.1:20216/onebot/v11/ws | 地址取决于配置文件,本机默认为`127.0.0.1:20216` | +| AccessToken | `""` | 如果你给轻雪配置了`AccessToken`,请在此填写相同的值 | + +## **其他** + +- 要使用其他通信方式请访问[OneBot Adapter](https://onebot.adapters.nonebot.dev/)获取详细信息 +- 轻雪不局限于OneBot适配器,你可以使用NoneBot2支持的任何适配器 diff --git a/docs/en/deployment/fandq.md b/docs/en/deployment/fandq.md new file mode 100644 index 00000000..13d7d020 --- /dev/null +++ b/docs/en/deployment/fandq.md @@ -0,0 +1,58 @@ +--- +title: 答疑 +icon: question +order: 3 +category: 使用指南 +tag: + - 配置 + - 部署 +--- + +## **常见问题** + +- 设备上Python环境太乱了,pip和python不对应怎么办? + - 请使用`/path/to/python -m pip install -r requirements.txt`来安装依赖, + 然后用`/path/to/python main.py`来启动Bot, + 其中`/path/to/python`是你要用来运行Bot的可执行文件 + +- 为什么我启动后机器人没有反应? + - 请检查配置文件的`command_start`或`superusers`,确认你有权限使用命令并按照正确的命令发送 + - 确认命令头没有和`nickname{}`冲突,例如一个命令是`help`,但是`Bot`昵称有一个`help`,那么将会被解析为nickname而不是命令 + +- 更新轻雪失败,报错`InvalidGitRepositoryError` + - 请正确安装`Git`,并使用克隆而非直接下载的方式部署轻雪 + +- 怎么登录聊天平台,例如QQ? + - 你有这个问题说明你不是很了解这个项目,本项目不负责实现登录功能,只负责处理和回应消息,登录功能由实现端(协议端)提供, + 实现端本身不负责处理响应逻辑,将消息按照OneBot标准处理好上报给轻雪 + 你需要使用Onebot标准的实现端来连接到轻雪并将消息上报给轻雪,下面已经列出一些推荐的实现端 +- `Playwright`安装失败 + - 输入`playwright install`安装浏览器 +- 有的插件安装后报错无法启动 + - 请先查阅插件文档,确认插件必要配置项完好后,仍然出现问题,请联系插件作者或在安全模式`safe_mode: true`下启动轻雪,在安全模式下你可以使用`npm uninstall`卸载问题插件 +- 其他问题 + - + 加入QQ群[775840726](http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&k=SzmDYbfR6jY94o9KFNon7AwelRyI6M_u&authKey=ygeBdEmdFNyCWuNR4w0M1M8%2B5oDg7k%2FDfN0tzBkYcnbB%2FGHNnlVEnCIGbdftsnn7&noverify=0&group_code=775840726) + +## **推荐方案(QQ)** + +1. [Lagrange.OneBot](https://github.com/KonataDev/Lagrange.Core),基于NTQQ的OneBot实现,目前Markdown消息支持Lagrange +2. [LLOneBot](https://github.com/LLOneBot/LLOneBot),NTQQ的OneBot插件,需要安装NTQQ +3. [OpenShamrock](https://github.com/whitechi73/OpenShamrock),基于Lsposed的OneBot11实现 +4. [TRSS-Yunzai](https://github.com/TimeRainStarSky/Yunzai),基于`node.js`,可使用`ws-plugin`进行通信 +5. [go-cqhttp](https://github.com/Mrs4s/go-cqhttp),`go`语言实现的OneBot11实现端,目前可用性较低 +6. [Gensokyo](https://github.com/Hoshinonyaruko/Gensokyo),基于 OneBot QQ官方机器人Api Golang 原生实现,需要官方机器人权限 +7. 人工实现的`Onebot`协议,自己整一个WebSocket客户端,看着QQ的消息,然后给轻雪传输数据 + +## **推荐方案(Minecraft)** + +1. [MinecraftOneBot](https://github.com/snowykami/MinecraftOnebot),我们专门为Minecraft开发的服务器Bot,支持OneBotV11标准 + +使用其他项目连接请先自行查阅文档,若有困难请联系对应开发者而不是Liteyuki的开发者 + +## **鸣谢** + +- [Nonebot2](https://nonebot.dev)提供的框架支持 +- [nonebot-plugin-htmlrender](https://github.com/kexue-z/nonebot-plugin-htmlrender/tree/master)提供的渲染功能 +- [nonebot-plugin-alconna](https://github.com/ArcletProject/nonebot-plugin-alconna)提供的命令解析功能 +- [MiSans](https://hyperos.mi.com/font/zh/),[MapleMono](https://gitee.com/mirrors/Maple-Mono)提供的字体,且遵守了相关字体开源协议 diff --git a/docs/en/deployment/install.md b/docs/en/deployment/install.md new file mode 100644 index 00000000..814a37cf --- /dev/null +++ b/docs/en/deployment/install.md @@ -0,0 +1,60 @@ +--- +title: 安装 +icon: download +order: 1 +category: 使用指南 +tag: + - 安装 +--- + +## **开始安装** + +### **常规部署** + +1. 安装 [`Git`](https://git-scm.com/download/) 和 [`Python3.10+`](https://www.python.org/downloads/release/python-31010/) 环境 + +```bash +# 克隆项目到本地,轻雪使用Git进行版本管理,该步骤为必要项 +git clone https://github.com/LiteyukiStudio/LiteyukiBot --depth=1 +# 切换到Bot目录下 +cd LiteyukiBot +# 安装依赖 +pip install -r requirements.txt +# 启动Bot +python main.py +``` + +> [!tip] +> 推荐使用虚拟环境来运行轻雪,以避免依赖冲突,你可以使用`python -m venv .venv`来创建虚拟环境,然后使用`.venv\Scripts\activate`来激活虚拟环境(Linux下使用`source .venv/bin/activate`激活) + +### **使用Docker构建镜像部署** + +1. 安装 [`Docker`](https://docs.docker.com/get-docker/) +2. 克隆项目 `git clone https://github.com/LiteyukiStudio/LiteyukiBot --depth=1` +3. 进入轻雪目录 `cd LiteyukiBot` +4. 构建镜像 `docker build -t liteyukibot .` +5. 启动容器 `docker run -p 20216:20216 -v $(pwd):/liteyukibot -v $(pwd)/.cache:/root/.cache liteyukibot` + +> [!tip] +> Windows请使用项目绝对目录`/path/to/LiteyukiBot`代替`$(pwd)`
+> 若你修改了端口号请将`20216:20216`中的`20216`替换为你的端口号 + +### **使用TRSS Scripts部署** + [TRSS_Liteyuki轻雪机器人管理脚本](https://timerainstarsky.github.io/TRSS_Liteyuki/),该功能由TRSS提供支持,不是LiteyukiBot官方提供的功能,推荐使用`Arch Linux` + + +## **设备要求** + +- Windows系统版本最低`Windows10+`/`Windows Server 2019+` +- Linux系统要支持Python3.10+,推荐`Ubuntu 20.04+`(~~别用你那b CentOS~~) +- CPU: 至少`1vCPU` +- 内存: Bot无其他插件会占用`300~500MB`,包括`chromium` 及 `node`等进程,其他插件占用视具体插件而定,建议`1GB`以上 +- 硬盘: 至少`1GB`空间 + +> [!warning] +> 如果设备上有多个环境,请使用`path/to/python -m pip install -r requirements.txt`来安装依赖,`path/to/python`为你的Python可执行文件路径 + +> [!warning] +> 轻雪的更新功能依赖Git,如果你没有安装Git直接下载源代码运行,你将无法使用更新功能 + +#### 其他问题请移步至[答疑](/deployment/fandq) \ No newline at end of file diff --git a/docs/en/dev/README.md b/docs/en/dev/README.md new file mode 100644 index 00000000..947ed654 --- /dev/null +++ b/docs/en/dev/README.md @@ -0,0 +1,8 @@ +--- +title: 开发及贡献 +index: false +icon: laptop-code +category: 开发 +--- + + \ No newline at end of file diff --git a/docs/en/dev/dev_comm.md b/docs/en/dev/dev_comm.md new file mode 100644 index 00000000..5de4517b --- /dev/null +++ b/docs/en/dev/dev_comm.md @@ -0,0 +1,99 @@ +--- +title: 进程通信 +icon: exchange-alt +order: 4 +category: 开发 +--- + +## **通道通信** + +### 简介 + +轻雪运行在主进程 MainProcess 里,其他插件框架进程是伴随的子进程,因此无法通过内存共享和直接对象传递的方式进行通信,轻雪提供了一个通道`Channel`用于跨进程通信,你可以通过`Channel`发送消息给其他进程,也可以监听其他进程的消息。 + +例如子进程接收到用户信息需要重启机器人,这时可以通过通道对主进程发送消息,主进程接收到消息后重启对应子进程。 + +### 示例 + +通道是全双工的,有两种接收模式,但一个通道只能使用一种,即被动模式和主动模式,被动模式由`chan.on_receive()`装饰回调函数实现,主动模式需调用`chan.receive()`实现 + +- 创建子进程的同时会初始化一个被动通道和一个主动通道,且通道标识为`{process_name}-active`和`{process_name}-passive`, +- 主进程中通过`get_channel`函数获取通道对象 +- 子进程中导入单例`active_channel`及`passive_channel`即可 + +> 在轻雪插件中(主进程中) + +```python +import asyncio + +from liteyuki.comm import get_channel, Channel +from liteyuki import get_bot + +# get_channel函数获取通道对象,参数为调用set_channel时的通道标识 +channel_passive = get_channel("nonebot-passive") # 获取被动通道 +channel_active = get_channel("nonebot-active") # 获取主动通道 +liteyuki_bot = get_bot() + + +# 注册一个函数在轻雪启动后运行 +@liteyuki_bot.on_after_start +async def send_data(): + while True: + channel_passive.send("I am liteyuki main process passive") + channel_active.send("I am liteyuki main process active") + await asyncio.sleep(3) # 每3秒发送一次消息 +``` + +> 在子进程中(例如NoneBot插件中) + +```python +from nonebot import get_driver +from liteyuki.comm import active_channel, passive_channel # 子进程中获取通道直接导入进程全局单例即可 +from liteyuki.log import logger + +driver = get_driver() + + +# 被动模式,通过装饰器注册一个函数在接收到消息时运行,每次接收到字符串数据时都会运行 +@passive_channel.on_receive(filter_func=lambda data: isinstance(data, str)) +async def on_passive_receive(data): + logger.info(f"Passive receive: {data}") + + +# 注册一个函数在NoneBot启动后运行 +@driver.on_startup +def on_startup(): + while True: + data = active_channel.receive() + logger.info(f"Active receive: {data}") +``` + +> 启动后控制台输出 + +```log +0000-00-00 00:00:00 [ℹ️信息] Passive receive: I am liteyuki main process passive +0000-00-00 00:00:00 [ℹ️信息] Active receive: I am liteyuki main process active +0000-00-00 00:00:03 [ℹ️信息] Passive receive: I am liteyuki main process passive +0000-00-00 00:00:03 [ℹ️信息] Active receive: I am liteyuki main process active +... +``` + +## **共享内存通信** + +### 简介 + +- 相比于普通进程通信,内存共享使得代码编写更加简洁,轻雪框架提供了一个内存共享通信的接口,你可以通过`storage`模块实现内存共享通信,该模块封装通道实现 +- 内存共享是线程安全的,你可以在多个线程中读写共享内存,线程锁会自动保护共享内存的读写操作 + +### 示例 + +> 在任意进程中均可使用 + +```python +from liteyuki.comm.storage import shared_memory + +shared_memory.set("key", "value") # 设置共享内存 +value = shared_memory.get("key") # 获取共享内存 +``` + +- 源代码:[liteyuki/comm/storage.py](https://github.com/LiteyukiStudio/LiteyukiBot/blob/main/liteyuki/comm/storage.py) \ No newline at end of file diff --git a/docs/en/dev/dev_lyfunc.md b/docs/en/dev/dev_lyfunc.md new file mode 100644 index 00000000..db33a2db --- /dev/null +++ b/docs/en/dev/dev_lyfunc.md @@ -0,0 +1,74 @@ +--- +title: 轻雪函数 +icon: code +order: 2 +category: 开发 +--- + +## **轻雪函数** + +轻雪函数 Liteyuki Function 是轻雪的一个功能,它允许你在轻雪中运行一些自定义的由数据驱动的命令,类似于Minecraft的mcfunction,属于资源包的一部分,但需单独起篇幅. + +### **函数文件** + +函数文件放在资源包的`functions`目录下,文件名以`.mcfunction` `.lyfunction` `.lyf`结尾,例如`test.mcfunction`,文件内容为一系列的命令,每行一个命令,支持单行注释`#`(编辑时的语法高亮可采取`shell`格式),例如: + +```shell +# 在发信器输出"hello world" +cmd echo hello world + +# 如果你想同时输出多行内容可以尝试换行符(Python格式) +cmd echo hello world\nLiteyuki bot +``` + +也支持句末注释,例如: +```shell +cmd echo hello world # 输出"hello world" +``` + +### **命令文档** + +```shell +var [var2=value2] ... # 定义变量 +cmd # 在设备上执行命令 +api [var=value...] # 调用Bot API +function # 调用函数,可递归 +sleep