Skip to content

Commit

Permalink
docs: fix broken links
Browse files Browse the repository at this point in the history
  • Loading branch information
shigma committed Apr 27, 2022
1 parent 8883c98 commit b32a9b3
Show file tree
Hide file tree
Showing 7 changed files with 37 additions and 40 deletions.
19 changes: 9 additions & 10 deletions docs/.vuepress/config.js
Original file line number Diff line number Diff line change
Expand Up @@ -298,7 +298,6 @@ module.exports = {
text: '其他官方插件',
isGroup: true,
children: [
'/plugins/other/github.md',
'/plugins/other/mock.md',
'/plugins/other/puppeteer.md',
],
Expand All @@ -311,20 +310,20 @@ module.exports = {
text: '教学系统 (Teach)',
isGroup: true,
children: [
'/community/teach/index.md',
'/community/teach/interp.md',
'/community/teach/prob.md',
'/community/teach/regexp.md',
'/community/teach/context.md',
// '/community/teach/prev-succ.md',
'/community/teach/misc.md',
'/community/teach/config.md',
'/community/dialogue/',
'/community/dialogue/interp.md',
'/community/dialogue/prob.md',
'/community/dialogue/regexp.md',
'/community/dialogue/context.md',
// '/community/dialogue/prev-succ.md',
'/community/dialogue/misc.md',
'/community/dialogue/config.md',
],
}, {
text: '接入 GitHub (GitHub)',
isGroup: true,
children: [
'/community/github/github.md',
'/community/github/index.md',
],
}, {
text: '执行脚本 (Eval)',
Expand Down
2 changes: 0 additions & 2 deletions docs/.vuepress/markdown/header.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,8 @@ import {} from '@koishijs/plugin-adapter-discord'
import {} from '@koishijs/plugin-adapter-onebot'
import {} from '@koishijs/plugin-adapter-telegram'
import {} from '@koishijs/plugin-console'
import {} from '@koishijs/plugin-eval'
import {} from '@koishijs/plugin-rate-limit'
import { Schedule } from '@koishijs/plugin-schedule'
import {} from '@koishijs/plugin-teach'

declare global {
// utils
Expand Down
2 changes: 1 addition & 1 deletion docs/community/dialogue/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebarDepth: 2
# 基本用法

::: tip 提示
本章介绍的功能都由 koishi-plugin-teach 插件提供。
本章介绍的功能都由 koishi-plugin-dialogue 插件提供。
:::

**问答**是 Koishi 教学系统中的基本单位。一个问答包含一个问题、其对应的回答以及其他相关的设置。**问题**用于匹配 Bot 收到的消息,如果匹配成功,则会将**回答**作为该消息的响应。一个问题可以对应多种回答,每种回答也可能包含多条消息。但无论如何这都可以用一条问答来表示。
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/plugin/lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ const dispose = ctx.on('foo', (...args) => {
- 对于相关的大量事件,推荐通过命名空间进行管理,使用 `/` 作为分隔符
- 配对使用 xxx 和 before-xxx 命名时序相关的事件

举个例子,@koishijs/plugin-teach 扩展了多达 20 个自定义事件。为了防止命名冲突,所有的事件都以 `dialogue/` 开头,并且在特定操作前触发的事件都包含了 `before-` 前缀,例如:
举个例子,koishi-plugin-dialogue 扩展了多达 20 个自定义事件。为了防止命名冲突,所有的事件都以 `dialogue/` 开头,并且在特定操作前触发的事件都包含了 `before-` 前缀,例如:

- dialogue/before-search: 获取搜索结果前触发
- dialogue/search: 获取完搜索结果后触发
Expand Down
44 changes: 22 additions & 22 deletions docs/guide/plugin/service.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,67 +30,67 @@ Koishi 中的服务可以分为大致三种类型。对于每一种我都给出

- ctx.console
- ctx.puppeteer
- ctx.teach
- ctx.worker

## 声明依赖关系

前面从服务提供者的角度提供了解决方案,现在让我们把视角转换到服务的使用者上。假设你正在开发名为 teach 的教学系统,并且这个插件依赖多个服务:
前面从服务提供者的角度提供了解决方案,现在让我们把视角转换到服务的使用者上。假设你正在开发名为 dialogue 的问答系统,并且这个插件依赖多个服务:

- database: 你使用数据库存储教学内容,离开数据库你的插件将无法运行
- assets: 你需要使用资源存储服务来做图片转存,离开此服务将可能导致部分图片无法正常显示,但短时间内不会对插件的运行造成影响
- console: 你为你的插件编写了控制台扩展,当控制台存在时你可以在网页中进行操作,但它并非教学系统的主要功能

那么你应该怎么写呢?先让我们来看一段标准错误答案:

::: code-group language plugin-teach
::: code-group language plugin-dialogue
```js
// 标准错误答案!别抄这个!
module.exports.name = 'teach'
module.exports.name = 'dialogue'

module.exports.apply = (ctx) => {
// 检查数据库服务是否存在
if (!ctx.database) return

ctx.command('teach').action((_, content) => {
ctx.command('dialogue').action((_, content) => {
// 检查资源存储服务是否存在
if (ctx.assets) ctx.assets.transform(content)
})

// 检查控制台服务是否存在
if (ctx.console) {
ctx.console.addEntry('/path/to/teach/extension')
ctx.console.addEntry('/path/to/dialogue/extension')
}
}
```
```ts
// 标准错误答案!别抄这个!
export const name = 'teach'
export const name = 'dialogue'

export function apply(ctx: Context) {
// 检查数据库服务是否存在
if (!ctx.database) return

ctx.command('teach').action((_, content) => {
ctx.command('dialogue').action((_, content) => {
// 检查资源存储服务是否存在
if (ctx.assets) ctx.assets.transform(content)
})

// 检查控制台服务是否存在
if (ctx.console) {
ctx.console.addEntry('/path/to/teach/extension')
ctx.console.addEntry('/path/to/dialogue/extension')
}
}
```
:::

你很快会发现这样写完全无法运行。首先,数据库服务需要等到应用启动完成后才可以访问,换言之即使安装了数据库插件,你也无法立即判断数据库服务是否存在。此外,一旦上述服务所在插件在运行时被重载,由于上面的代码属于 teach 插件,因此 if 中代码的副作用将无法被有效清理;而当相应的服务重新被注册时,这部分的代码也不会被重新运行,从而导致一系列难以检测的问题。
你很快会发现这样写完全无法运行。首先,数据库服务需要等到应用启动完成后才可以访问,换言之即使安装了数据库插件,你也无法立即判断数据库服务是否存在。此外,一旦上述服务所在插件在运行时被重载,由于上面的代码属于 dialogue 插件,因此 if 中代码的副作用将无法被有效清理;而当相应的服务重新被注册时,这部分的代码也不会被重新运行,从而导致一系列难以检测的问题。

### using 属性

为了解决这种问题,Koishi 为插件声明提供了一个独特的 `using` 属性:

```ts title=plugin-teach.ts
export const name = 'teach'
```ts title=plugin-dialogue.ts
export const name = 'dialogue'
export const using = ['database'] as const
// 上面的 as const 的作用是固定 `using` 的内部类型

Expand All @@ -110,14 +110,14 @@ export function apply(ctx: Context) {

```ts
ctx.using(['console'], (ctx) => {
ctx.console.addEntry('/path/to/teach/extension')
ctx.console.addEntry('/path/to/dialogue/extension')
})

// 等价于
ctx.plugin({
using: ['console'],
apply: (ctx) => {
ctx.console.addEntry('/path/to/teach/extension')
ctx.console.addEntry('/path/to/dialogue/extension')
},
})
```
Expand All @@ -128,44 +128,44 @@ ctx.plugin({

### 最佳实践

现在让我们回到一开始的问题。对于 teach 插件所使用的三个服务 database, assets 和 console,分别应该如何声明呢?下面给出了一个最佳实践,请注意不同服务的处理方式之间的区别:
现在让我们回到一开始的问题。对于 dialogue 插件所使用的三个服务 database, assets 和 console,分别应该如何声明呢?下面给出了一个最佳实践,请注意不同服务的处理方式之间的区别:

::: code-group language plugin-teach
::: code-group language plugin-dialogue
```js
// 正确答案!抄这个!
module.exports.name = 'teach'
module.exports.name = 'dialogue'

// 对于整体依赖的服务,使用 using 属性声明依赖关系
module.exports.using = ['database']

module.exports.apply = (ctx) => {
ctx.command('teach').action((_, content) => {
ctx.command('dialogue').action((_, content) => {
// 对于可选的依赖服务,在运行时检测即可
if (ctx.assets) ctx.assets.transform(content)
})

// 对于部分功能依赖的服务,使用 ctx.using() 注册为子插件
ctx.using(['console'], (ctx) => {
ctx.console.addEntry('/path/to/teach/extension')
ctx.console.addEntry('/path/to/dialogue/extension')
})
}
```
```ts
// 正确答案!抄这个!
export const name = 'teach'
export const name = 'dialogue'

// 对于整体依赖的服务,使用 using 属性声明依赖关系
export const using = ['database'] as const

export function apply(ctx: Context) {
ctx.command('teach').action((_, content) => {
ctx.command('dialogue').action((_, content) => {
// 对于可选的依赖服务,在运行时检测即可
if (ctx.assets) ctx.assets.transform(content)
})

// 对于部分功能依赖的服务,使用 ctx.using() 注册为子插件
ctx.using(['console'], (ctx) => {
ctx.console.addEntry('/path/to/teach/extension')
ctx.console.addEntry('/path/to/dialogue/extension')
})
}
```
Expand Down
6 changes: 3 additions & 3 deletions docs/guide/service/assets.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ export interface FileInfo {
- [@koishijs/plugin-assets-remote](../../plugins/assets/local.md)
- [@koishijs/plugin-assets-s3](../../plugins/assets/s3.md)

以下是使用此服务的官方插件
以下是使用此服务的插件

- [@koishijs/plugin-github](../../plugins/other/github.md) (可选)
- [@koishijs/plugin-teach](../../plugins/teach/) (可选)
- [koishi-plugin-github](../../community/github/) (可选)
- [koishi-plugin-dialogue](../../community/dialogue/) (可选)
2 changes: 1 addition & 1 deletion docs/plugins/common/respondent.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ export default {
['Koishi', '一直挖坑一直爽'],
]"/>

如果想要加入更高级和用户可定义的问答系统,可以参见 [@koishijs/plugin-teach](../teach/index.md)
如果想要加入更高级和用户可定义的问答系统,可以参见 [koishi-plugin-dialogue](../../community/dialogue/)

## 配置项

Expand Down

0 comments on commit b32a9b3

Please sign in to comment.