From bac575a212f1961431c3c0613b3e84146d6ecc3e Mon Sep 17 00:00:00 2001 From: "Lain." Date: Fri, 26 Apr 2024 23:28:49 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=8F=92=E4=BB=B6=E6=94=B6=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vitepress/config.mts | 50 +++++++++-------- docs/develop/elements.md | 39 ++++++++++---- docs/develop/plugin.md | 12 +++-- docs/event/message.md | 4 +- docs/index.md | 11 ++-- docs/plugins/index.md | 108 +++++++++++++++++++++++++++++++++++++ docs/start.md | 50 ++++++++++++++--- 7 files changed, 215 insertions(+), 59 deletions(-) create mode 100644 docs/plugins/index.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 51af98db..f55ec944 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -8,35 +8,33 @@ export default defineConfig({ themeConfig: { siteTitle: '主页', nav: [ - { text: '主页', link: '/' }, { text: '快速开始', link: '/start' }, { text: '开发文档', link: '/develop/index' }, - { text: 'elements', link: '/develop/elements' } - ], - sidebar: [ - { - text: '目录', - items: [ - { text: '主页', link: '/' }, - { text: '快速开始', link: '/start' } - ] - }, - { - text: '事件', - items: [ - { text: '消息事件', link: '/event/message' } - ] - }, - { - text: '插件开发', - items: [ - { text: 'elements', link: '/develop/elements' }, - { text: '#karin', link: '/develop/karin' }, - { text: 'YamlEditor', link: '/develop/YamlEditor' }, - { text: '插件编写', link: '/develop/plugin' }, - ] - } + { text: 'elements', link: '/develop/elements' }, + { text: '插件索引', link: '/plugins/index' }, ], + sidebar: { + '/event/': [ + { + text: '事件', + items: [ + { text: '目录', link: '/event/index' }, + { text: '消息事件', link: '/event/message' } + ], + } + ], + '/develop/': [ + { + text: '插件开发', + items: [ + { text: 'elements', link: '/develop/elements' }, + { text: '#karin', link: '/develop/karin' }, + { text: 'YamlEditor', link: '/develop/YamlEditor' }, + { text: '插件编写', link: '/develop/plugin' }, + ] + } + ] + }, socialLinks: [ { icon: 'github', link: 'https://github.com/KarinJS/Karin' } ], diff --git a/docs/develop/elements.md b/docs/develop/elements.md index 8f823a03..4445ffa2 100644 --- a/docs/develop/elements.md +++ b/docs/develop/elements.md @@ -1,4 +1,4 @@ -## elements +# elements 本文档介绍了 Krita 的消息元素结构和 `segment` 模块的使用方法。 @@ -7,6 +7,7 @@ ::: ## 导入 + ::: tip 温馨提示 以下所有的示例都假设你已经导入了 `segment` 模块。 ::: @@ -26,17 +27,20 @@ karin对于多媒体资源的标准化处理，遵循以下规则： ::: tip 注意 对于`file://`格式，请开发者注意以下几点： + - 请确保用户的协议端和karin运行环境一致，否则可能导致文件读取失败 - 对于Linux系统，由于绝对路径前方有`/`，格式为`file:///root/...`，请注意区分`///`和`//` ::: ## 文本 text + ```js const text = segment.text('Hello, world!') console.log(text) ``` 输出： + ```js { type: 'text', @@ -56,6 +60,7 @@ console.log(face) ``` 输出： + ```js { type: 'face', @@ -63,7 +68,6 @@ console.log(face) } ``` - ## 图片 image ::: tip 温馨提示 @@ -79,6 +83,7 @@ console.log(image) ``` 输出： + ```js { // 对于网络图片，要求传入的url必须为https://或http://开头 type: 'image', @@ -110,6 +115,7 @@ console.log(record) ``` 输出： + ```js { type:'record', @@ -117,11 +123,11 @@ console.log(record) } ``` - ## 视频 video + ::: tip 温馨提示 遵循 [多媒体资源标准](#多媒体资源标准) -::: +::: ```js const video = segment.video('https://example.com/video.mp4') @@ -129,6 +135,7 @@ console.log(video) ``` 输出： + ```js { type: 'video', @@ -148,6 +155,7 @@ console.log(at) ``` 输出： + ```js { type: 'at', @@ -166,6 +174,7 @@ console.log(poke) ``` 输出： + ```js { type: 'poke', @@ -183,6 +192,7 @@ console.log(share) ``` 输出： + ```js { type:'share', @@ -200,8 +210,8 @@ const contact = segment.contact('qq', '12345') console.log(contact) ``` - 输出： + ```js { type: 'contact', @@ -217,8 +227,8 @@ const location = segment.location('121.527328', '31.21515', '上海市浦东新 console.log(location) ``` - 输出： + ```js { type: 'location', @@ -231,14 +241,13 @@ console.log(location) ## 音乐分享 music - ```js const music = segment.music('qq', '12345') console.log(music) ``` - 输出： + ```js { type:'music', @@ -254,8 +263,8 @@ const customMusic = segment.customMusic('https://example.com/music.mp3', 'https: console.log(customMusic) ``` - 输出： + ```js { type: 'customMusic', @@ -275,6 +284,7 @@ console.log(reply) ``` 输出： + ```js { type:'reply', @@ -290,6 +300,7 @@ console.log(forward) ``` 输出： + ```js { type: 'forward', @@ -305,6 +316,7 @@ console.log(node) ``` 输出： + ```js { type: 'node', @@ -327,6 +339,7 @@ console.log(xml) ``` 输出： + ```js { type: 'xml', @@ -343,6 +356,7 @@ console.log(json) ``` 输出： + ```js { type: 'json', @@ -367,8 +381,8 @@ const markdown = segment.markdown({ console.log(markdown) ``` - 输出： + ```js // 原生markdown内容 { @@ -550,6 +564,7 @@ rows和button的键入值一致，且比较复杂，请查看最下方的构建 ::: ### 跳转按钮 + ```js:line-numbers {1} // 快速构建 segment.rows({ link: 'https://example.com' }) @@ -569,6 +584,7 @@ segment.rows({ ``` ### 回调按钮 + ```js:line-numbers {1} // 快速构建 segment.rows({ type: 1, text: '回调按钮'}) @@ -589,6 +605,7 @@ segment.rows({ ``` ### 指令按钮 + ```js:line-numbers {1} // 快速构建 segment.rows({ text: '指令按钮' }) @@ -606,4 +623,4 @@ segment.rows({ list: ['用户ID1', '用户ID2'], // 设置后，只有这些用户可以点击，与admin互斥 role: ['用户ID1', '用户ID2'], // 设置后，只有这些用户可以点击，与admin互斥 （仅频道可用） tips: '指令提示' // 客户端不支持本 action 的时候，弹出的 toast 文案 -}) \ No newline at end of file +}) diff --git a/docs/develop/plugin.md b/docs/develop/plugin.md index 5f992250..cad26548 100644 --- a/docs/develop/plugin.md +++ b/docs/develop/plugin.md @@ -68,11 +68,13 @@ app.reg({ export const hello = app.plugin(app) ``` + 3. 保存，对机器人输入`你好`，机器人会回复`hello`。 以上，是一个最基本的插件构建方法。 ### 方法2 + ```js import { plugin } from '#Karin' @@ -111,9 +113,11 @@ export class hello extends plugin { ``` ## 完整参数 +> > 以下是一个完整的插件编写示例。 ### 方法1 + ```js import { App } from '#Karin' @@ -148,6 +152,7 @@ export const hello = app.plugin(app) ``` ### 方法2 + ```js import { plugin } from '#Karin' @@ -195,14 +200,12 @@ export class hello extends plugin { >高级监听事件： - | | 结构 | 参考 | 说明 | | -------- | -------------------------------- | -------------------- | ------------ | | 一级事件 | `post_type` | `message` | 所有消息事件 | | 二级事件 | `post_type.notice_type` | `message.group` | 群消息事件 | | 三级事件 | `post_type.notice_type.sub_type` | `notice.notify.poke` | 群内戳一戳 | - ## 消息匹配规则 | 参数 | 必须 | 类型 | 说明 | @@ -212,7 +215,6 @@ export class hello extends plugin { | log | | boolean | 是否显示操作日志 | | permission | | string | 权限 master,owner,admin,all | - > 一些正则... | 正则 | 说明 | | 正则 | 说明 | @@ -227,11 +229,11 @@ export class hello extends plugin { | [^] | 非字符集 | | \B | 非单词边界 | | () | 分组 | | \| | 或 | - ## 快速回复 + | 参数 | 必须 | 类型 | 说明 | | --------- | ---- | ------- | ---------------------------------------------- | | at | | boolean | 是否@回复发送者消息 | | recallMsg | | number | 单位秒，设置后，将在指定时间撤回本次回复的消息 | | reply | | boolean | 是否引用回复发送者消息 | -| button | | boolean | 是否加入按钮，暂未实现 | \ No newline at end of file +| button | | boolean | 是否加入按钮，暂未实现 | diff --git a/docs/event/message.md b/docs/event/message.md index b2872c01..307c6e59 100644 --- a/docs/event/message.md +++ b/docs/event/message.md @@ -9,6 +9,7 @@ ::: ### 标准属性对象 + ```js const message = { self_id: 'string', // 机器人的ID，默认为uin @@ -79,7 +80,6 @@ e.reply('Hello', { retry_count: 1 }) // 重试次数 e.reply('Hello', { at: true, reply: true, recallMsg: 10, button: false, retry_count: 1 }) ``` - | 参数 | 类型 | 说明 | | ------------------- | ------- | -------------------------------- | | message | string | 回复消息内容 | @@ -88,4 +88,4 @@ e.reply('Hello', { at: true, reply: true, recallMsg: 10, button: false, retry_co | options.reply | boolean | 是否引用回复消息本身 | | options.recallMsg | number | 发送成功后，撤回消息时间，单位秒 | | options.button | boolean | 暂未实现 | -| options.retry_count | number | 发送失败后，重试次数 | \ No newline at end of file +| options.retry_count | number | 发送失败后，重试次数 | diff --git a/docs/index.md b/docs/index.md index 28ac65d7..142f6fdd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,18 +5,15 @@ hero: name: Karin tagline: 基于 Kritor 标准进行开发的nodejs机器人框架 actions: - - theme: alt - text: kritor标准 - link: https://github.com/KarinJS/kritor - theme: alt text: onebots link: https://docs.onebots.org/ - - theme: brand - text: 开发文档 - link: /develop/index - - theme: brand + - theme: alt text: 快速上手 link: /start + - theme: brand + text: 插件索引 + link: /plugins/index features: - title: 轻量级 diff --git a/docs/plugins/index.md b/docs/plugins/index.md new file mode 100644 index 00000000..d4ded0a3 --- /dev/null +++ b/docs/plugins/index.md @@ -0,0 +1,108 @@ +--- +layout: home +--- + +# 📜用户须知 + +**Karin开发团队（以下简称“我们”）在此特别提醒用户注意：** + +1. 插件的责任和风险： + - 本列表收录的所有的插件（以下简称“插件”）。 + - 我们对于插件的功能性、兼容性或安全性不提供任何明示或暗示的保证。 + - 用户在选择下载或使用插件时，应自行评估插件的适用性、稳定性及安全性。 + - 用户因使用插件而可能遭受的任何形式的数据丢失或损害，我们概不负责。 +2. 知识产权和合规性： + - 用户在使用插件时，应确保其遵守相关的知识产权法律法规。 + - 我们不承担用户因违反知识产权法律法规而产生的任何法律责任。 + - 用户应遵守各插件的开源协议，确保其合法使用插件并遵守相关规定。 +3. 自主选择： + - 我们强烈建议用户在下载或使用插件前，仔细阅读并理解插件的用户文档和开源协议。 + - 用户应确保所选插件的功能和性能符合其个人或业务的需求。 + +**用户使用插件所产生的一切后果由用户自行承担，我们不承担任何由此引发的任何问题或责任。** + +## 🎉插件收录规范 + +
+ +点击查看提交插件说明 + +- 欢迎提交插件，但请遵守插件收录规范。 +- 如果您的插件存在违反插件收录规范的行为，我们会立即删除您的插件。 +- 打开[plugins][plugins]页面，按照已有的格式新增插件信息 +- 填写提交信息，使用`feat: 插件名称`、`feat: 添加测试插件`等格式 +- 拓展描述信息，请尽量提供，非必需 +- 填写完成提交，等待审核 + +
+ +
+ +点击查看插件收录规范 + +- 对于本页面收录的所有插件，我们要求开发者遵守以下规定 +- 必须包含开源协议，并在仓库中提供 +- 禁止存在侵犯第三方知识产权的行为 +- 禁止存在恶意破坏、恶意修改、恶意删除、恶意添加等恶意行为 +- 禁止存在恶意推广、恶意宣传等恶意行为 +- 禁止存在恶意破坏用户隐私、恶意收集用户信息等恶意行为 +- 禁止存在恶意利用插件进行违法犯罪活动等恶意行为 +- 禁止存在恶意收集、泄露用户数据、恶意泄露用户隐私等恶意行为 +- 禁止存在恶意修改插件的源代码、恶意删除插件的源代码等恶意行为 +- 禁止在插件中包含任何形式的**后门**、**木马**、**病毒**等恶意代码或程序 +- 对于加密、混淆的插件，必须在仓库主页声明哪些文件是加密、混淆的，并注明代码混淆的目的 + +
+ +**禁止存在任何形式的一键安装插件，如一键脚本、容器等。希望各位可以尊重每一个开发者来之不易的劳动成果。** + +## 📖官方仓库 + +> 请不要往这里提交插件~ + +| 名称 | 作者 | 仓库地址 | 镜像仓库 | 开源协议 | 简介 | +| --------------------- | -------------------- | ---------------------------- | -------- | ------------------------ | --------------------------------------- | +| Karin | [Karin团队][KarinJS] | [Karin][Karin] | - | [GPL-3.0][Karin-tab] | 基于 Kritor 进行开发的nodejs机器人框架 | +| Karin-docs | [Karin团队][KarinJS] | [Karin-docs][docs] | - | [GPL-3.0][Karin-tab] | Kritor的文档仓库(也就是本页面) | +| karin-puppeteer | [Karin团队][KarinJS] | [karin-puppeteer][puppeteer] | - | [GPL-3.0][puppeteer-tab] | Puppeteer渲染器 | +| karin-plugin-template | [Karin团队][KarinJS] | [template][template] | - | [GPL-3.0][template-tab] | 插件模板仓库 | +| karin-plugin-basic | [Karin团队][KarinJS] | [karin-plugin-basic][pbasic] | - | [GPL-3.0][basic-tab] | 基础插件，`#状态`、`#更新`、`#更新日志` | + +## 🎨插件包列表 + +> 请省略前缀哦~ + +| 名称 | 作者 | 仓库地址 | 镜像仓库 | 开源协议 | 简介 | +| -------------- | -------------------------- | -------------------------------- | -------- | ----------------------------- | -------------------- | +| server-watcher | [ikechan8370][ikechan8370] | [server-watcher][server-watcher] | - | [GPL-3.0][server-watcher-tab] | 监控服务器状态的插件 | + +## 📖其他插件 + +> 可提交一些单个`js`插件，请省略前缀哦~ + +| 名称 | 作者 | 仓库地址 | 镜像仓库 | 开源协议 | 简介 | +| ---- | ---- | -------- | -------- | -------- | ---- | + +## 🌐其他 + +> 可以存放一些脚本类、工具类、资源类，但请不要制作一键安装插件~ + +| 名称 | 作者 | 仓库地址 | 镜像仓库 | 开源协议 | 简介 | +| ---- | ---- | -------- | -------- | -------- | ---- | + +--- + +[KarinJS]: https://github.com/KarinJS +[Karin]: https://github.com/KarinJS/Karin +[docs]: https://github.com/KarinJS/Karin/tree/docs +[Karin-tab]: https://github.com/KarinJS/Karin?tab=GPL-3.0-1-ov-file#readme +[pbasic]: https://github.com/KarinJS/karin-plugin-basic +[basic-tab]: https://github.com/KarinJS/karin-plugin-basic?tab=GPL-3.0-1-ov-file#readme +[template]: https://github.com/KarinJS/karin-plugin-template +[template-tab]: https://github.com/KarinJS/karin-plugin-template?tab=GPL-3.0-1-ov-file#readme +[puppeteer]: https://github.com/KarinJS/karin-puppeteer +[puppeteer-tab]: https://github.com/KarinJS/karin-puppeteer?tab=GPL-3.0-1-ov-file#readme +[plugins]: https://github.com/KarinJS/Karin/edit/docs/docs/plugins/index.md +[ikechan8370]: https://github.com/ikechan8370 +[server-watcher]: https://github.com/ikechan8370/karin-plugin-server-watcher +[server-watcher-tab]: https://github.com/ikechan8370/karin-plugin-server-watcher?tab=GPL-3.0-1-ov-file#readme diff --git a/docs/start.md b/docs/start.md index 093e0925..0c0e8717 100644 --- a/docs/start.md +++ b/docs/start.md @@ -2,7 +2,7 @@ --- -### 环境 +## 环境 > 支持 Windows、Linux、MacOS、Docker 等环境 > 推荐安装的没有强制性需求，可根据个人需求进行安装 @@ -13,7 +13,7 @@ | [git][git] | 推荐安装 | 分布式版本控制软件，国内用户推荐使用 [腾讯软件管家][腾讯软件管家] 进行加速下载 | | [redis][redis] | 推荐安装 | 用于存储数据，大多数插件都用到，推荐安装 | -### 安装 +## 安装 > 以下命令均为默认您安装了`NodeJs`、`git` @@ -27,44 +27,66 @@ npm install pnpm -g ```sh [国内源] npm --registry=https://registry.npmmirror.com install pnpm -g ``` -::: +::: 2. 使用git克隆项目 -```sh +::: tip +中国大陆服务器推荐使用`Gitee`镜像源 +`Karin`官方的所有项目，均可通过将域名中的`github`更换为`gitee`进行加速下载~ +::: + +::: code-group + +```sh [Github] git clone --depth=1 https://github.com/KarinJS/Karin.git ``` -3. 初始化项目 +```sh [Gitee] +git clone --depth=1 https://gitee.com/KarinJS/Karin.git +``` + +::: + +1. 初始化项目 > 进入项目目录 + ```sh cd Karin ``` -> ~~拉取子模块~~ +2. ~~拉取子模块~~ + > 可跳过，karin会自动拉取子模块 + ```sh git submodule update --init --recursive ``` -> 安装依赖 +3. 安装依赖 ::: code-group ```sh [安装生产依赖] pnpm install -P ``` -```sh [安装全部依赖] +```sh [安装开发依赖] pnpm install ``` + ::: > 你可以选择其中任何一种方式进行依赖安装。 4. 启动项目 +::: tip +开发模式支持`plugins/apps`文件夹热更新、插件包的`index.js`热更新 +正常启动下，仅支持热更新非插件包例如自带的`karin-plugin-example` +::: + ::: code-group ```sh [正常启动] @@ -74,9 +96,21 @@ node . ```sh [开发模式启动] node . --dev ``` + ::: +## 渲染器 + +::: tip +`Karin`开放了`Renderer`接口，开发者可自行注册渲染器，实现自定义渲染器 +::: + +如果你不需要进行渲染`html`页面等操作，可跳过此步骤。 + +默认提供[karin-puppeteer][karin-puppeteer]作为渲染器，可根据需求自行安装。 +通过`WebSocketServer`进行通信，详情请查看[karin-puppeteer][karin-puppeteer] +[karin-puppeteer]: https://github.com/KarinJS/karin-puppeteer [NodeJs]: https://nodejs.org/en [git]: https://git-scm.com/ [腾讯软件管家]: https://sw.pcmgr.qq.com/1e05804bd17b358a8c88284df8331fcd/65fcde89/spcmgr/download/Git-2.44.0-64-bit.exe