bot/app
3
6.9k
Fork 1
mirror of https://github.com/LiteyukiStudio/LiteyukiBot.git synced 2024-11-22 20:17:39 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

📝 文档初步大迁移 vuepress -> vitepress

Browse Source
This commit is contained in:
远野千束 2024-08-31 19:05:37 +08:00
parent 7f198c83b5
commit 8bb3f15bd9
14 changed files with 534 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@ -60,3 +60,7 @@ result.json
docs/zh/dev/api docs/zh/dev/api
docs/en/dev/api docs/en/dev/api
mkdoc.bat mkdoc.bat
# vitepress
docs/.vitepress/dist/
docs/.vitepress/cache

121
docs/.vitepress/config/common.ts Normal file
View File

@ -0,0 +1,121 @@
// 共有配置项，导入index用
import {defineConfig} from 'vitepress'
import {generateSidebar} from 'vitepress-sidebar';
import {zh} from "./zh";
import {en} from "./en";
let defaultLocale = 'zh';
const commonSidebarOptions = {
collapsed: true,
convertSameNameSubFileToGroupIndexPage: true,
useTitleFromFrontmatter: true,
useTitleFromFileHeading: true,
useFolderTitleFromIndexFile: true,
useFolderLinkFromIndexFile: true,
includeFolderIndexFile: true,
sortMenusByFrontmatterOrder: true,
rootGroupText: 'LITEYUKIBOT',
}
/**
* Generate sidebar config
* multiple languages and sections
* @returns {any[]}
*/
function generateSidebarConfig(): any[] {
let sections = ["dev", "store", "usage", "deploy"]
let languages = ['zh', 'en']
let ret = []
for (let language of languages) {
for (let section of sections) {
if (language === defaultLocale) {
ret.push({
basePath: `/${section}/`,
scanStartPath: `${language}/${section}`,
resolvePath: `/${section}/`,
...commonSidebarOptions
})
} else {
ret.push({
basePath: `/${language}/${section}/`,
scanStartPath: `${language}/${section}`,
resolvePath: `/${language}/${section}/`,
...commonSidebarOptions
})
}
}
}
return ret
}
console.log(generateSidebarConfig())
export const common = defineConfig({
head: [
// 配置favicon.ico
['link', {rel: 'icon', type: 'image/x-icon', href: 'favicon.ico'}],
['link', {rel: 'stylesheet', href: 'https://fonts.font.im/css?family=Cousine:400,400i,700,700i|Poppins:100,100i,200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i,900,900i'}],
],
rewrites: {
[`${defaultLocale}/:rest*`]: ":rest*",
},
themeConfig: {
logo: '/liteyuki.svg',
sidebar: generateSidebar(
[
...generateSidebarConfig()
]
),
socialLinks: [
{icon: 'github', link: 'https://github.com/LiteyukiStudio/LiteyukiBot'}
],
search: {
provider: 'local',
options: {
locales: {
root: {
translations: {
button: {
buttonText: '搜索文档',
buttonAriaLabel: '打开搜索框',
},
modal: {
noResultsText: '没有找到搜索结果',
resetButtonTitle: '清除查询条件',
footer: {
selectText: '选择',
navigateText: '切换',
}
}
},
},
en: {
translations: {
button: {
buttonText: 'Search',
buttonAriaLabel: 'Search',
},
modal: {
noResultsText: 'No results found',
resetButtonTitle: 'Reset search query',
footer: {
selectText: 'Select',
navigateText: 'Navigate',
}
}
}
},
}
}
}
},
sitemap: {
hostname: 'https://bot.liteyuki.icu'
},
lastUpdated: true,
locales: {
root: {label: "简体中文", ...zh},
en: {label: "English", ...en},
},
})

28
docs/.vitepress/config/en.ts Normal file
View File

@ -0,0 +1,28 @@
import {defineConfig} from 'vitepress'
import {ThemeConfig} from "./utils";
export const en = defineConfig({
lang: "en-US",
title: "LiteyukiBot",
description: "A high-performance, easy-to-use chatbot framework and application",
themeConfig: {
nav: [
{text: 'Deploy', link: '/en/deploy/install'},
{text: 'Usage', link: '/en/usage/basic'},
{text: 'Extension', link: '/en/store/resource'},
{text: 'Develop', link: '/en/dev/api'},
],
docFooter: {
prev: 'Prev Page',
next: 'Next Page'
},
editLink: ThemeConfig.getEditLink(
'Edit this page on GitHub',
),
footer: {
message: 'Documentation built with <a href="https://vitepress.dev/">VitePress</a> | API references generated by <a href="https://github.com/LiteyukiStudio/litedoc">litedoc</a>',
copyright: ThemeConfig.copyright
},
outline: ThemeConfig.getOutLine("Page Content"),
},
})

6
docs/.vitepress/config/index.ts Normal file
View File

@ -0,0 +1,6 @@
import {defineConfig} from "vitepress";
import {common} from './common'
export default defineConfig({
...common,
})

40
docs/.vitepress/config/utils.ts Normal file
View File

@ -0,0 +1,40 @@
// 本模块储存一些工具函数和引用
/**
* GetEditLink Options
* @param text Edit link text
*/
export const ThemeConfig = {
getEditLink: (editPageText: string): { pattern: (params: { filePath: string; }) => string; text: string; } => {
return {
pattern: ({filePath}: { filePath: string; }): string => {
// 匹配 /dev/api或 /{lang}/dev/api
const regex = /^[^\/]+\/dev\/api/;
console.log(filePath);
if (regex.test(filePath)) {
// remove {lang}/api prefix
filePath = filePath.replace(regex, '')
.replace('index.md', '__init__.py')
.replace('.md', '.py');
// 若文件名（不含扩展）和上级文件夹相同，返回文件夹/__init__.py
if (filePath.split('/').pop().split('.')[0] === filePath.split('/').slice(-2, -1)[0]) {
filePath = filePath.split('/').slice(0, -1).join('/') + '/__init__.py';
}
return `https://github.com/LiteyukiStudio/LiteyukiBot/tree/main/liteyuki${filePath}`;
} else {
return `https://github.com/LiteyukiStudio/LiteyukiBot/tree/main/docs${filePath}`;
}
},
text: editPageText
};
},
getOutLine: (label: string): { label: string; level: [number, number]; } => {
return {
label: label,
level: [2, 6]
};
},
copyright: 'Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved'
}

28
docs/.vitepress/config/zh.ts Normal file
View File

@ -0,0 +1,28 @@
import {defineConfig} from 'vitepress'
import {ThemeConfig} from "./utils";
export const zh = defineConfig({
lang: "zh-Hans",
title: "轻雪机器人",
description: "一个综合性的机器人应用及管理框架",
themeConfig: {
nav: [
{text: '部署', link: '/deploy/install'},
{text: '使用', link: '/usage/basic'},
{text: '扩展', link: '/store/resource'},
{text: '开发', link: '/dev/api'},
],
docFooter: {
prev: '上一页',
next: '下一页'
},
editLink: ThemeConfig.getEditLink(
'在 GitHub 上编辑此页',
),
footer: {
message: '文档由 <a href="https://vitepress.dev/">VitePress</a> 构建 | API引用由 <a href="https://github.com/LiteyukiStudio/litedoc">litedoc</a> 生成',
copyright: ThemeConfig.copyright
},
outline: ThemeConfig.getOutLine("页面内容"),
},
})

2
docs/en/deploy/install.md
View File

@ -54,4 +54,4 @@ python main.py
> [!warning] > [!warning]
> Liteyuki's update function depends on Git. If you do not have Git installed and run the source code directly, you will not be able to use the update function > Liteyuki's update function depends on Git. If you do not have Git installed and run the source code directly, you will not be able to use the update function
#### For other questions, please refer to [FAQ](/deployment/fandq) #### For other questions, please refer to [FAQ](./fandq)

98
docs/en/dev/comm.md Normal file
View File

@ -0,0 +1,98 @@
---
title: 进程通信
order: 4
---
# **Channel Communication**
### Introduction
LiteyukiBot is running in the main process MainProcess, and other plugin framework processes are child processes that come with it.
Therefore, it is impossible to communicate through shared memory and direct object transfer.
Liteyuki provides a channel [`Channel`](./api/comm/channel#class-channel-generic-t) for inter-process communication like `go`.
You can send messages to other processes through [`Channel`](./api/comm/channel#class-channel-generic-t) and listen to messages from other processes.
### Example
The channel is full-duplex, with two receiving modes, but only one mode can be used for a channel, that is, passive mode and active mode, passive mode is implemented by the `chan.on_receive()` decorator callback function, and active mode needs to call `chan.receive()` to implement
- 创建子进程的同时会初始化一个被动通道和一个主动通道，且通道标识为`{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)

72
docs/en/dev/lyfunc.md Normal file
View File

@ -0,0 +1,72 @@
---
title: 轻雪函数
order: 2
---
# **轻雪函数**
轻雪函数 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 <var1=value1> [var2=value2] ... # 定义变量
cmd <command> # 在设备上执行命令
api <api_name> [var=value...] # 调用Bot API
function <func_name> # 调用函数，可递归
sleep <time> # 异步等待，单位s
nohup <command> # 使用新的task执行命令，即不等待
end # 结束函数关键字，包括子task
await # 等待所有异步任务结束，若函数中启动了其他task，需要在最后调用，否则task对象会被销毁
```
#### **示例**
```shell
# 疯狂戳好友
# 使用 /function poke user_id=123456 执行
# 每隔0.2s戳两次，无限戳，会触发最大递归深度限制
# 若要戳20s后停止，则需要删除await，添加sleep 20和end
api friend_poke user_id=user_id
api friend_poke user_id=user_id
sleep 0.2
nohup function poke
await
```
### **API**
理论上所有基于onebotv11的api都可调用，不同Adapter api也有差别.
[Onebot v11 API文档](https://283375.github.io/onebot_v11_vitepress/api/index.html)
### **结束关键字**
由于LiteyukiBot基于异步运行, 所以在编写lyfunction时也要注意异步的调用，避免出现"单线程走到底"的情况是效率提升的关键.
`await` 异步任务结束关键字，用于结束当前已完成function的执行
> [!warning]
> 但若出现非单function的情况，有一个task任务没有完成而await被执行了，那么当前所有函数包的task都会被截停销毁
> [!tip]
> 编写轻雪函数推荐你使用VS Code插件[Liteyuki Function](https://github.com/LiteyukiStudio/lyfunctionTextmate)实现语法高亮

80
docs/en/dev/plugin.md Normal file
View File

@ -0,0 +1,80 @@
---
title: 轻雪插件开发
order: 3
---
# 简介
轻雪插件是轻雪内置的一部分功能，运行在主进程中，可以很高程度地扩展轻雪的功能
## 开始
### 创建插件
一个`.py`文件或一个包含`__init__.py`的文件夹即可被识别为插件
首先创建一个文件夹，例如`watchdog_plugin`，并在其中创建一个`__init__.py`文件，即可创建一个插件
`__init__.py`
```python
from liteyuki.plugin import PluginMetadata, PluginType
from .watch_dog import * # 导入逻辑部分
# 定义插件元数据
__plugin_meta__ = PluginMetadata(
name="NoneDog", # 插件名称
version="1.0.0", # 插件版本
description="A simple plugin for nonebot developer", # 插件描述
type=PluginType.SERVICE # 插件类型
)
# 你的插件代码
...
```
### 编写逻辑部分
轻雪主进程不涉及聊天部分，因此插件主要是一些后台任务或者与聊天机器人的通信
以下我们会编写一个简单的插件，用于开发NoneBot时进行文件系统变更重载
`watch_dog.py`
```python
import os
from liteyuki.dev import observer # 导入文件系统观察器
from liteyuki import get_bot, logger # 导入轻雪Bot和日志
from watchdog.events import FileSystemEvent # 导入文件系统事件
liteyuki = get_bot() # 获取唯一的轻雪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") # 调用重启进程方法
```
### 加载插件
#### 方法1
- 在配置文件中的`liteyuki.plugins`中添加你的插件路径，例如`watchdog_plugin`，重启轻雪即可加载插件。
#### 方法2
- 使用开发工具快速运行插件，无需手动创建实例
- 创建入口文件，例如`main.py`，并在其中写入以下代码
```python
from liteyuki.dev.plugin import run_plugins
run_plugins("watchdog_plugin")
```
然后运行`python main.py`即可启动插件
启用插件后，我们在src/nonebot_plugins下创建一个文件，例如`test.py`，并在其中写入一些代码，保存后轻雪会自动重载NoneBot进程

51
docs/en/dev/resource.md Normal file
View File

@ -0,0 +1,51 @@
---
title: 资源包开发
order: 1
---
# 简介
资源包,亦可根据用途称为主题包、字体包、语言包等，它允许你一定程度上自定义轻雪的外观,并且不用修改源代码
- [资源/主题商店](../store/resource)提供了一些资源包供你选择，你也可以自己制作资源包
- 资源包的制作很简单，如果你接触过`Minecraft`的资源包，那么你能够很快就上手，仅需按照原有路径进行文件替换即可，讲起打包成一个新的资源包。
- 部分内容制作需要一点点前端基础,例如`html`，`css`
- 轻雪原版资源包请查看`LiteyukiBot/liteyuki/resources`，可以在此基础上进行修改
- 欢迎各位投稿资源包到轻雪资源商店
请注意，主题包中的html渲染使用Js来规定数据的渲染位置，请确保您所编写的html代码能被Bot解析，否则会导致渲染失败或渲染结果不理想/异常/错位等无法预料的事情发生。推荐在编写html时同时更改对应Js代码，以避免出现无法预料的问题。
---
## 加载资源包
- 资源包通常是以`.zip`格式压缩的，只需要将其解压到根目录`resources`目录下即可，注意不要嵌套文件夹,正常的路径应该是这样的
```shell
main.py
resources
└─resource_pack_1
├─metadata.yml
├─templates
└───...
└─resource_pack_2
├─metadata.yml
└─...
```
- 你自己制作的资源包也应该遵循这个规则,并且应该在`metadata.yml`中填写一些信息
- 若没有`metadata.yml`文件，则该文件夹不会被识别为资源包
```yaml
name: "资源包名称"
version: "1.0.0"
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]
> 资源包的结构会随着轻雪的更新而有变动，第三方资源包开发者需要注意版本兼容性，同时用户也应该自行选择可用的资源包

2
docs/zh/deploy/install.md
View File

@ -52,4 +52,4 @@ python main.py
> [!warning] > [!warning]
> 轻雪的更新功能依赖Git，如果你没有安装Git直接下载源代码运行，你将无法使用更新功能 > 轻雪的更新功能依赖Git，如果你没有安装Git直接下载源代码运行，你将无法使用更新功能
#### 其他问题请移步至[答疑](/deployment/fandq) #### 其他问题请移步至[答疑](./fandq)

4
docs/zh/dev/comm.md
View File

@ -8,8 +8,8 @@ order: 4
### 简介 ### 简介
轻雪运行在主进程 MainProcess 里，其他插件框架进程是伴随的子进程，因此无法通过内存共享和直接对象传递的方式进行通信， 轻雪运行在主进程 MainProcess 里，其他插件框架进程是伴随的子进程，因此无法通过内存共享和直接对象传递的方式进行通信，
轻雪提供了一个通道[`Channel`](http://localhost:5173/en/dev/api/comm/channel.html#class-channel-generic-t)用于跨进程通信， 轻雪提供了一个通道[`Channel`](./api/comm/channel#class-channel-generic-t)用于跨进程通信，
你可以通过[`Channel`](http://localhost:5173/en/dev/api/comm/channel.html#class-channel-generic-t)发送消息给其他进程，也可以监听其他进程的消息。 你可以通过[`Channel`](./api/comm/channel#class-channel-generic-t)发送消息给其他进程，也可以监听其他进程的消息。
例如子进程接收到用户信息需要重启机器人，这时可以通过通道对主进程发送消息，主进程接收到消息后重启对应子进程。 例如子进程接收到用户信息需要重启机器人，这时可以通过通道对主进程发送消息，主进程接收到消息后重启对应子进程。

2
docs/zh/dev/resource.md
View File

@ -7,7 +7,7 @@ order: 1
资源包,亦可根据用途称为主题包、字体包、语言包等，它允许你一定程度上自定义轻雪的外观,并且不用修改源代码 资源包,亦可根据用途称为主题包、字体包、语言包等，它允许你一定程度上自定义轻雪的外观,并且不用修改源代码
- [资源/主题商店](/store/)提供了一些资源包供你选择，你也可以自己制作资源包 - [资源/主题商店](../store/resource)提供了一些资源包供你选择，你也可以自己制作资源包
- 资源包的制作很简单，如果你接触过`Minecraft`的资源包，那么你能够很快就上手，仅需按照原有路径进行文件替换即可，讲起打包成一个新的资源包。 - 资源包的制作很简单，如果你接触过`Minecraft`的资源包，那么你能够很快就上手，仅需按照原有路径进行文件替换即可，讲起打包成一个新的资源包。
- 部分内容制作需要一点点前端基础,例如`html`，`css` - 部分内容制作需要一点点前端基础,例如`html`，`css`
- 轻雪原版资源包请查看`LiteyukiBot/liteyuki/resources`，可以在此基础上进行修改 - 轻雪原版资源包请查看`LiteyukiBot/liteyuki/resources`，可以在此基础上进行修改