From 8568c7bb99ce00d9f0a9ba6f9a2e100294902b30 Mon Sep 17 00:00:00 2001 From: snowy Date: Mon, 12 Aug 2024 05:26:36 +0800 Subject: [PATCH] =?UTF-8?q?:sparkles:=20=E6=96=B0=E5=A2=9Eobserver?= =?UTF-8?q?=E7=B1=BB=E5=92=8C=E5=BC=80=E5=8F=91=E8=B0=83=E8=AF=95=E5=99=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vuepress/navbar.ts | 9 ++- docs/.vuepress/sidebar.ts | 8 ++- docs/deployment/config.md | 53 ++++++++++------- docs/dev/README.md | 8 +++ docs/{usage/lyfunc.md => dev/dev_lyfunc.md} | 12 ++-- docs/dev/dev_lyplugin.md | 59 +++++++++++++++++++ .../dev_resource_pack.md} | 21 +++++-- docs/store/README.md | 7 ++- liteyuki/__init__.py | 3 +- liteyuki/bot/__init__.py | 1 + liteyuki/dev/observer.py | 4 +- liteyuki/plugins/plugins_loader/__init__.py | 6 ++ 12 files changed, 153 insertions(+), 38 deletions(-) create mode 100644 docs/dev/README.md rename docs/{usage/lyfunc.md => dev/dev_lyfunc.md} (89%) create mode 100644 docs/dev/dev_lyplugin.md rename docs/{usage/resource_pack.md => dev/dev_resource_pack.md} (89%) diff --git a/docs/.vuepress/navbar.ts b/docs/.vuepress/navbar.ts index 2686b1b5..fddb094b 100644 --- a/docs/.vuepress/navbar.ts +++ b/docs/.vuepress/navbar.ts @@ -8,13 +8,18 @@ export default navbar([ prefix: "deployment/", }, { - text: "使用及开发", + text: "使用及功能", link: "/usage/", prefix: "usage/", }, { text: "资源及插件", - link: "/store/resource", + link: "/store/", prefix: "store/", + }, + { + text: "开发及贡献", + link: "/dev/", + prefix: "dev/", } ]); diff --git a/docs/.vuepress/sidebar.ts b/docs/.vuepress/sidebar.ts index 5a144421..938fec84 100644 --- a/docs/.vuepress/sidebar.ts +++ b/docs/.vuepress/sidebar.ts @@ -10,7 +10,7 @@ export default sidebar({ children: "structure", }, { - text: "使用及开发", + text: "使用及功能", icon: "book", prefix: "usage/", children: "structure", @@ -20,6 +20,12 @@ export default sidebar({ icon: "store", prefix: "store/", children: "structure", + }, + { + text: "开发及贡献", + icon: "pen-nib", + prefix: "dev/", + children: "structure", } ], }); diff --git a/docs/deployment/config.md b/docs/deployment/config.md index 385c070d..50067718 100644 --- a/docs/deployment/config.md +++ b/docs/deployment/config.md @@ -13,14 +13,25 @@ tag: 首次运行后生成`config.yml`和`config`目录，你可修改配置项后重启轻雪，绝大多数情况下，你只需要修改`superusers`及`nickname`字段即可 启动时会加载项目目录下`config.yml/yaml/json/toml`和`config`目录下的所有配置文件，你可在`config`目录下创建多个配置文件，轻雪会自动合并这些配置文件 + ## **基础配置项** ```yaml -command_start: [ "/", "" ] # 指令前缀，若没有""空命令头，请开启alconna_use_command_start保证alconna解析正常 -host: 127.0.0.1 # 监听地址，默认为本机，若要接收外部请求请填写0.0.0.0 -port: 20216 # 绑定端口 -nickname: [ "liteyuki" ] # 机器人昵称列表 -superusers: [ "1919810" ] # 超级用户列表 +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: [ ] # 轻雪插件目录列表 ``` ## **其他配置** @@ -28,27 +39,29 @@ superusers: [ "1919810" ] # 超级用户列表 以下为默认值，如需自定义请手动添加 ```yaml -onebot_access_token: "" # 访问令牌，对公开放时建议设置 -default_language: "zh-CN" # 默认语言 -alconna_auto_completion: false # alconna是否自动补全指令，默认false，建议开启 +# 高级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" + # 开发者选项 -allow_update: true # 是否允许更新 -log_level: "INFO" # 日志等级 -log_icon: true # 是否显示日志等级图标（某些控制台字体不可用） -auto_report: true # 是否自动上报问题给轻雪服务器 -auto_update: true # 是否自动更新轻雪，每天4点检查更新 -debug: false # 轻雪调试，开启会自动重载Bot或者资源，其他插件自带的调试功能也将开启 -safe_mode: false # 安全模式，开启后将不会加载任何第三方插件 -# 其他Nonebot插件的配置项 -custom_config_1: "custom_value1" -custom_config_2: "custom_value2" +liteyuki: + allow_update: true # 是否允许更新 + debug: false # 轻雪调试，开启会自动重载Bot或者资源，其他插件自带的调试功能也将开启 + dev_mode: false # 开发者模式，开启后将会启动监视者，监视文件变化并自动重载 + ... ``` > [!tip] -> 如果要使用dotenv配置文件，请自行创建`.env.{ENVIRONMENT}`，并在`config.yml`中添加`environment:{ENVIRONMENT}`字段 +> 如果要使用NoneBot和dotenv配置文件，请自行创建`.env.{ENVIRONMENT}`，并在`config.yml`中添加`nonebot.environment:{ENVIRONMENT}`字段 -## **OneBot实现端配置** +## **与NoneBot对接的OneBot实现端配置** 生产环境中推荐反向WebSocket 不同的实现端给出的字段可能不同，但是基本上都是一样的，这里给出一个参考值 diff --git a/docs/dev/README.md b/docs/dev/README.md new file mode 100644 index 00000000..947ed654 --- /dev/null +++ b/docs/dev/README.md @@ -0,0 +1,8 @@ +--- +title: 开发及贡献 +index: false +icon: laptop-code +category: 开发 +--- + + \ No newline at end of file diff --git a/docs/usage/lyfunc.md b/docs/dev/dev_lyfunc.md similarity index 89% rename from docs/usage/lyfunc.md rename to docs/dev/dev_lyfunc.md index 846080b5..db33a2db 100644 --- a/docs/usage/lyfunc.md +++ b/docs/dev/dev_lyfunc.md @@ -1,15 +1,13 @@ --- title: 轻雪函数 icon: code -order: 4 -category: 使用指南 -tag: - - 配置 +order: 2 +category: 开发 --- ## **轻雪函数** -轻雪函数 Liteyuki Function 是轻雪的一个功能，它允许你在轻雪中运行一些自定义的由数据驱动的命令，类似于Minecraft的mcfunction. +轻雪函数 Liteyuki Function 是轻雪的一个功能，它允许你在轻雪中运行一些自定义的由数据驱动的命令，类似于Minecraft的mcfunction，属于资源包的一部分，但需单独起篇幅. ### **函数文件** @@ -70,3 +68,7 @@ await > [!warning] > 但若出现非单function的情况，有一个task任务没有完成而await被执行了，那么当前所有函数包的task都会被截停销毁 + + +> [!tip] +> 编写轻雪函数推荐你使用VS Code插件[Liteyuki Function](https://github.com/LiteyukiStudio/lyfunctionTextmate)实现语法高亮 \ No newline at end of file diff --git a/docs/dev/dev_lyplugin.md b/docs/dev/dev_lyplugin.md new file mode 100644 index 00000000..6bd5e948 --- /dev/null +++ b/docs/dev/dev_lyplugin.md @@ -0,0 +1,59 @@ +--- +title: 轻雪插件开发 +icon: laptop-code +order: 3 +category: 开发 +--- + +# 简介 + +轻雪插件是轻雪内置的一部分功能，运行在主进程中，可以很高程度地扩展轻雪的功能 + +## 开始 + +### 创建插件 + +在标准项目中，位于liteyuki/plugins和src/liteyuki_plugins下的Python modules均会被当作插件加载，你可自行添加配置文件以指定插件的加载路径 +一个`.py`文件或一个包含`__init__.py`的文件夹即可被识别为插件 +创建一个文件夹，例如`my_plugin`，并在其中创建一个`__init__.py`文件，即可创建一个插件 + +```python +from liteyuki.plugin import PluginMetadata + +__plugin_meta__ = PluginMetadata( + name="My Plugin", + version="1.0.0", + description="A simple plugin" +) + +# 你的插件代码 +``` + +### 编写逻辑部分 + +轻雪主进程不涉及聊天部分，因此插件主要是一些后台任务或者与聊天机器人的通信 +以下我们会编写一个简单的插件，用于开发NoneBot时进行文件系统变更重载 + +```python +from liteyuki.dev import observer +from liteyuki import get_bot, logger +from watchdog.events import FileSystemEvent + +liteyuki = get_bot() + +exclude_extensions = (".pyc", ".pyo") + + +# 用observer的on_file_system_event装饰器监听文件系统事件 +@observer.on_file_system_event( + directories=("src/nonebot_plugins",), + event_filter=lambda event: not event.src_path.endswith(exclude_extensions) and ("__pycache__" not in event.src_path) and os.path.isfile(event.src_path) +) +def restart_nonebot_process(event: FileSystemEvent): + logger.debug(f"File {event.src_path} changed, reloading nonebot...") + liteyuki.restart_process("nonebot") +``` + +### 加载插件 + +在配置文件中的`liteyuki.plugins`中添加你的插件路径，例如`my_plugin`，重启轻雪即可加载插件。然后我们在src/nonebot_plugins下创建一个文件，例如`test.py`，并在其中写入一些代码，保存后轻雪会自动重载NoneBot进程 \ No newline at end of file diff --git a/docs/usage/resource_pack.md b/docs/dev/dev_resource_pack.md similarity index 89% rename from docs/usage/resource_pack.md rename to docs/dev/dev_resource_pack.md index 78138e03..494748ca 100644 --- a/docs/usage/resource_pack.md +++ b/docs/dev/dev_resource_pack.md @@ -1,12 +1,14 @@ --- -title: 资源包 -icon: paint-brush -order: 3 -category: 使用手册 +title: 资源包开发 +icon: box +order: 1 +category: 开发 --- -## 简介 +## 简介 + 资源包,亦可根据用途称为主题包、字体包、语言包等，它允许你一定程度上自定义轻雪的外观,并且不用修改源代码 + - [资源/主题商店](/store/)提供了一些资源包供你选择，你也可以自己制作资源包 - 资源包的制作很简单，如果你接触过`Minecraft`的资源包，那么你能够很快就上手，仅需按照原有路径进行文件替换即可，讲起打包成一个新的资源包。 - 部分内容制作需要一点点前端基础,例如`html`，`css` @@ -16,8 +18,11 @@ category: 使用手册 请注意，主题包中的html渲染使用Js来规定数据的渲染位置，请确保您所编写的html代码能被Bot解析，否则会导致渲染失败或渲染结果不理想/异常/错位等无法预料的事情发生。推荐在编写html时同时更改对应Js代码，以避免出现无法预料的问题。 --- + ## 加载资源包 + - 资源包通常是以`.zip`格式压缩的，只需要将其解压到根目录`resources`目录下即可，注意不要嵌套文件夹,正常的路径应该是这样的 + ```shell main.py resources @@ -29,8 +34,10 @@ resources ├─metadata.yml └─... ``` + - 你自己制作的资源包也应该遵循这个规则,并且应该在`metadata.yml`中填写一些信息 - 若没有`metadata.yml`文件，则该文件夹不会被识别为资源包 + ```yaml name: "资源包名称" version: "1.0.0" @@ -38,5 +45,9 @@ description: "资源包描述" # 你可以自定义一些信息,但请保证以上三个字段 ... ``` + - 资源包加载遵循一个优先级，即后加载的资源包会覆盖前面的资源包，例如，你在A包中定义了一个`index.html`文件，B包也定义了一个`index.html`文件，那么加载B包后，A包中的`index.html`文件会被覆盖 - 对于不同资源包的不同文件，是可以相对引用的，例如你在A中定义了`templates/index.html`，在B中定义了`templates/style.css`，可以在A的`index.html`中用`./style.css`相对路径引用B中的css + +> [!tip] +> 资源包的结构会随着轻雪的更新而有变动，第三方资源包开发者需要注意版本兼容性，同时用户也应该自行选择可用的资源包 \ No newline at end of file diff --git a/docs/store/README.md b/docs/store/README.md index 837257a9..e7619de2 100644 --- a/docs/store/README.md +++ b/docs/store/README.md @@ -1,5 +1,8 @@ --- -title: 资源商店 -icon: store +title: 资源及插件商店 index: false +icon: store +category: 商店 --- + + \ No newline at end of file diff --git a/liteyuki/__init__.py b/liteyuki/__init__.py index 1e195c2e..ea4561fa 100644 --- a/liteyuki/__init__.py +++ b/liteyuki/__init__.py @@ -1,7 +1,8 @@ from liteyuki.bot import ( LiteyukiBot, get_bot, - get_config + get_config, + get_config_with_compat ) from liteyuki.comm import ( diff --git a/liteyuki/bot/__init__.py b/liteyuki/bot/__init__.py index fd298b79..118d2981 100644 --- a/liteyuki/bot/__init__.py +++ b/liteyuki/bot/__init__.py @@ -20,6 +20,7 @@ __all__ = [ "LiteyukiBot", "get_bot", "get_config", + "get_config_with_compat", ] diff --git a/liteyuki/dev/observer.py b/liteyuki/dev/observer.py index d61f540d..844c4498 100644 --- a/liteyuki/dev/observer.py +++ b/liteyuki/dev/observer.py @@ -9,7 +9,7 @@ from typing import Callable, TypeAlias from watchdog.events import FileSystemEvent, FileSystemEventHandler from watchdog.observers import Observer -from liteyuki import get_bot, get_config, logger +from liteyuki import get_bot, get_config_with_compat, logger liteyuki_bot = get_bot() @@ -37,7 +37,7 @@ def debounce(wait): return decorator -if get_config("dev_mode", False): +if get_config_with_compat("liteyuki.dev_mode", ("dev_mode",), False): logger.debug("Liteyuki Reload enabled, watching for file changes...") observer.start() diff --git a/liteyuki/plugins/plugins_loader/__init__.py b/liteyuki/plugins/plugins_loader/__init__.py index e8f7010d..8b90c530 100644 --- a/liteyuki/plugins/plugins_loader/__init__.py +++ b/liteyuki/plugins/plugins_loader/__init__.py @@ -8,6 +8,7 @@ Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved @File : __init__.py.py @Software: PyCharm """ +from liteyuki import get_config_with_compat, load_plugin from liteyuki.plugin import PluginMetadata, load_plugins __plugin_meta__ = PluginMetadata( @@ -18,3 +19,8 @@ __plugin_meta__ = PluginMetadata( ) load_plugins("src/liteyuki_plugins") +for plugin in get_config_with_compat("liteyuki.plugins", ("plugins", ), []): + load_plugin(plugin) + +for plugin_dir in get_config_with_compat("liteyuki.plugin_dirs", ("plugins_dirs", ), []): + load_plugins(plugin_dir) \ No newline at end of file