merge filter / permission / i18n

.vitepress/config/zh-CN.json

@@ -119,28 +119,20 @@
               "link": "/manual/usage/market.md"
             },
             {
-              "text": "第一次聊天",
+              "text": "第一次对话",
               "link": "/manual/usage/adapter.md"
             },
             {
               "text": "指令系统",
               "link": "/manual/usage/command.md"
             },
             {
-              "text": "账号系统",
+              "text": "账号登录与绑定",
               "link": "/manual/usage/platform.md"
             },
             {
-              "text": "权限管理",
-              "link": "/manual/usage/permission.md"
-            },
-            {
-              "text": "过滤器",
-              "link": "/manual/usage/filter.md"
-            },
-            {
-              "text": "国际化",
-              "link": "/manual/usage/i18n.md"
+              "text": "深入定制机器人",
+              "link": "/manual/usage/customize.md"
             }
           ]
         },

zh-CN/api/database/built-in.md

@@ -27,7 +27,7 @@ Koishi 的数据库 API 实际上分为两部分：
 
 - **platform:** `string` 平台名
 - **id:** `string` 频道账号
-- **assignee:** `string` [受理人](../../manual/usage/permission.md#受理人机制)
+- **assignee:** `string` [受理人](../../manual/usage/customize.md#受理人机制)
 - **permissions:** `string[]` 权限列表
 - **locales:** `string[]` 语言列表
 

zh-CN/api/glossary.md

@@ -38,7 +38,7 @@
 
 ## 控制台 (Console)
 
-- [入门 > 认识控制台](../manual/usage/index.md)
+- [入门 > 认识控制台](../manual/usage/market.md#认识控制台)
 - [开发 > 控制台](../guide/console/index.md)
 - [API > 控制台](./console/server.md)
 
@@ -69,7 +69,7 @@
 
 ## 过滤器 (Filter)
 
-- [入门 > 过滤器](../manual/usage/filter.md)
+- [入门 > 过滤器](../manual/usage/customize.md#过滤器)
 - [开发 > 模块化 > 过滤器](../guide/plugin/filter.md)
 - [API > 内置服务 > 过滤器](./service/filter.md)
 

zh-CN/guide/basic/advanced.md

@@ -27,7 +27,7 @@ ctx.bots[`${platform}:${selfId}`]
 await bot.broadcast(['123456', '456789'], '全体目光向我看齐')
 ```
 
-但这样写需要知道每一个频道对应哪个机器人。对于启用了多个机器人的场景下，这么写就有点不方便了。幸运的是，Koishi 还有另一个方法：`ctx.broadcast()`。在启用了数据库的情况下，此方法会自动获取每个频道的 [受理人](../../manual/usage/permission.md#受理人机制)，并以对应的账号发送消息：
+但这样写需要知道每一个频道对应哪个机器人。对于启用了多个机器人的场景下，这么写就有点不方便了。幸运的是，Koishi 还有另一个方法：`ctx.broadcast()`。在启用了数据库的情况下，此方法会自动获取每个频道的 [受理人](../../manual/usage/customize.md#受理人机制)，并以对应的账号发送消息：
 
 ```ts
 await ctx.broadcast(['onebot:123456', 'discord:456789'], '全体目光向我看齐')

zh-CN/guide/i18n/index.md

@@ -5,7 +5,7 @@
 :::
 
 ::: tip
-在学习本章之前，建议先完整阅读 [入门 > 国际化](../../manual/usage/i18n.md)。
+在学习本章之前，建议先完整阅读 [入门 > 国际化](../../manual/usage/customize.md#国际化)。
 :::
 
 如果你在运营一个大型社区，那么你可能会遇到这种场景：群组内设立了许多不同语言的频道，每个频道分别供不同地区的用户进行交流。在这种情况下，最合适的做法是让你的机器人在不同的频道下使用不同的语言进行回复。本质上，这不会改变机器人的运行逻辑，因此最好的做法是将涉及的每一段文本都抽离出来，通过统一的方式进行管理，并在发送前进行本地化渲染。

zh-CN/guide/plugin/filter.md

@@ -1,7 +1,7 @@
 # 过滤器
 
 ::: tip
-在学习本节之前，建议先完整阅读 [入门 > 过滤器](../../manual/usage/filter.md)。
+在学习本节之前，建议先完整阅读 [入门 > 过滤器](../../manual/usage/customize.md#过滤器)。
 :::
 
 默认情况下，一个会话事件、中间件或者指令都对所有的会话生效。但如果我们希望这些功能只对部分群聊或者用户生效，我们就需要用到 **过滤器**。

zh-CN/manual/recipe/multiple.md

@@ -12,11 +12,11 @@
 
 在同一个 Koishi 应用中，有些插件可以同时启用多份，有些则不能——这并非插件的实现缺陷，而是预期的行为。事实上，插件的作者可以指定具体哪些功能可以被独立地启用。这表现在插件上就是两种不同的类型：那些可以同时启用多份的插件被称为可重用插件，反之则称为不可重用插件。
 
-典型的可重用插件是 [适配器插件](../console/adapter.md)。每个适配器对应着一个正在运行的机器人，不同平台的机器人由不同的适配器进行配置。因此，如果你想在同一个平台中配置多个机器人，直接按照上一节中的方法添加多个适配器插件即可。
+典型的可重用插件是 [适配器插件](../usage/adapter.md)。每个适配器对应着一个正在运行的机器人，不同平台的机器人由不同的适配器进行配置。因此，如果你想在同一个平台中配置多个机器人，直接按照上一节中的方法添加多个适配器插件即可。
 
 与此同时，绝大多数插件都是不可重用的。对于这类插件，你只能同时拥有一份运行中的配置。如果已经有一份正在运行的配置，那么你会在其他配置处看到一行提示「此插件正在运行且不可重用」。当然，你仍然可以准备多份配置，并在合适的时机将一份配置停用，并启用另一份。
 
-对于那些不可重用的插件，如果希望在不同的场景下切换到不同的配置，就需要插件作者提供带有 [过滤器](../usage/filter.md) 的配置项。如果你想要修改的配置不支持过滤器，那么你可以考虑向插件作者提出建议，或采用下面介绍的 [多实例](#多实例) 方案。
+对于那些不可重用的插件，如果希望在不同的场景下切换到不同的配置，就需要插件作者提供带有 [过滤器](../usage/customize.md#过滤器) 的配置项。如果你想要修改的配置不支持过滤器，那么你可以考虑向插件作者提出建议，或采用下面介绍的 [多实例](#多实例) 方案。
 
 ## 多实例
 

zh-CN/manual/starter/boilerplate.md

@@ -105,5 +105,5 @@ yarn start
 
 恭喜你已经掌握了 Koishi 的基本用法！接下来：
 
-- 如果你希望学习使用 Koishi 控制台，请前往 [认识控制台](../console/index.md)
+- 如果你希望了解 Koishi 的更多功能，请前往 [安装和配置插件](../usage/market.md) (推荐)
 - 如果你希望立即开始你的插件开发，请前往 [开发指南](../../guide/index.md)

zh-CN/manual/usage/adapter.md

@@ -1,4 +1,4 @@
-# 第一次聊天
+# 第一次对话
 
 安装完了 Koishi 并体验了插件市场，想必你已经等不及体验 Koishi 的功能了。现在就让我们立即开始与机器人的第一次对话吧！
 
@@ -16,12 +16,13 @@
 
 如果我们想要模拟群聊，那我们可以再次点击「添加用户」以创建更多的用户。随后，在顶部切换到「群聊模式」。这样，你就可以控制多个虚拟用户与机器人聊天了。如果你要体验的插件是下棋一类的多人交互插件，这会非常有用。
 
-除此以外，如果某些指令需要一定的 [权限等级](../usage/permission.md)，你也可以切换到「用户设置」中进行调整。
+除此以外，如果某些指令需要一定的 [权限等级](../usage/customize.md#权限管理)，你也可以切换到「用户设置」中进行调整。
 
 ## 接入真实聊天平台
 
 仅仅是在沙盒中对话是远远不够的。我们需要将机器人接入到真实的聊天平台中，才能让它真正地为我们服务。Koishi 使用适配器插件来支持各种聊天平台。下面是官方维护的适配器列表：
 
+- [Dingtalk (钉钉)](../../plugins/adapter/dingtalk.md)
 - [Discord](../../plugins/adapter/discord.md)
 - [KOOK](../../plugins/adapter/kook.md)
 - [Lark (飞书)](../../plugins/adapter/lark.md)

zh-CN/manual/usage/command.md

@@ -121,7 +121,7 @@ help 指令后还可以添加一个参数，用于查看特定指令的帮助信
 
 1. `prefix` 是一个列表，默认值为 `['']` 表示无需前缀也能触发；将列表清空会导致所有指令都无法通过 `prefix` 触发 (但仍然可以通过私聊或 `nickname` 或 @机器人 触发)
 2. 如果你在 `prefix` 中设置了多个值，例如 `['.', '/', '']`，那么 `.`, `/` 或无前缀都能触发指令；但由于 Koishi 是按顺序匹配各个前缀的，因此空串 `''` 必须写在最后一个
-3. 可以为不同的会话设置不同的 `prefix`，具体请参考 [过滤器](./filter.md) 一节
+3. 可以为不同的会话设置不同的 `prefix`，具体请参考 [过滤器](./customize.md#过滤器) 一节
 :::
 
 ## 子指令
@@ -159,7 +159,7 @@ help 指令后还可以添加一个参数，用于查看特定指令的帮助信
 熟悉 Git 的用户可能会发现，这种设计正是借鉴了 Git 的二级指令：当一个指令的功能过于复杂时，我们可以将其拆分为多个子指令，从而使得指令的功能更加清晰。
 
 ::: tip
-至于 user.locale 是干什么的，想必大家也已经猜出来了。我们留到 [国际化](./i18n.md) 一节再详细介绍。
+至于 user.locale 是干什么的，想必大家也已经猜出来了。我们留到 [国际化](./customize.md#国际化) 一节再详细介绍。
 :::
 
 ## 指令管理
@@ -184,4 +184,4 @@ help 指令后还可以添加一个参数，用于查看特定指令的帮助信
 
 我们甚至还可以单独设置每一个指令选项的权限等级。例如，我们可以单独给 `-E, --unescape` 选项设置 `authority` 为 3。这样一来，只有 3 级以上权限的用户才能使用 `echo -E` 的功能。
 
-关于用户权限，请参考 [权限管理](./permission.md) 一节。
+关于用户权限，请参考 [权限管理](./customize.md#权限管理) 一节。

zh-CN/manual/usage/customize.md

@@ -0,0 +1,116 @@
+# 深入定制机器人
+
+## 权限管理
+
+既然已经有了用户系统，下一个自然的需求便是权限管理了。
+
+### 用户权限
+
+Koishi 内部有一套默认的权限系统，它为每个用户赋予了一个权限等级，遵循以下的 **核心规则**：
+
+- 数据库中没有的用户默认拥有 0 级权限
+- 高权限者能够执行一切低权限者的操作
+
+在此基础上，我们还扩充出了这样的一套 **设计准则**：
+
+- 0 级：不存在的用户
+- 1 级：所有用户，只能够接触有限的功能
+- 2 级：高级用户，能够接触几乎一切机器人的功能
+- 3 级：管理员，能够直接操作机器人事务
+- 4 级：高级管理员，能够管理其他账号
+
+你可以基于这套准则对指令进行 [权限管理](./command.md#权限管理)，也可以用于部分 [计算属性](#计算属性) 的配置项中。
+
+通过 [配置登录插件](./platform.md#配置登录插件) 的方式，你可以快速拥有一个 5 级权限的管理员账号。接下来，要做的就是为其他用户赋予权限了。
+
+安装 [admin](../../plugins/common/admin.md) 插件。该插件提供了名为 `authorize` 的指令，可以设置其他用户的权限等级：
+
+<chat-panel>
+<chat-message nickname="Alice">authorize -u @Bob 2</chat-message>
+<chat-message nickname="Koishi">用户数据已修改。</chat-message>
+</chat-panel>
+
+任何用户只能对权限等级低于自己的用户进行操作，且操作后的权限等级同样必须低于自己。
+
+### 受理人机制
+
+默认情况下，同一个 Koishi 应用接入的多个机器人账号在同一个频道内，只有一个机器人会响应用户的消息。这是为了防止消息重复发送和循环触发等问题。这个负责响应消息的机器人被称为该频道的「受理人」。默认情况下，第一个收到该频道的消息的机器人会自动成为受理人。
+
+当受理人账号离线时，即便频道内仍有其他机器人，它们也不会响应你的消息。此时如果想要切换受理人，同样请安装 [admin](../../plugins/common/admin.md) 插件，并使用 `@bot assign`，其中 @bot 是你所希望的受理人。
+
+反过来，如果你希望你的 Koishi 实例不主动响应某个频道的消息，可以通过 `assign -r` 的方式来移除该频道的受理人。其他频道不会受到影响。
+
+::: tip
+某个频道处于无受理人状态与该频道被过滤器排除的区别在于：前者仍然可以被通过 @机器人 的方式触发指令，而后者无论如何都无法触发指令。具体请参考 [触发前缀](./command.md#触发前缀) 章节。
+:::
+
+### 自动注册
+
+默认情况下，对于每一条接收到的消息，机器人都会自动向数据库中注册其用户和频道。新注册的用户将默认获得 1 级权限，而新注册的频道会自动以收到消息的机器人为其受理者。如果你不希望有此行为，可以在全局设置中手动配置 `autoAuthorize` 和 `autoAssign`。
+
+上述两个配置项都支持 [计算属性](#计算属性)，这也意味着你可以在不同的聊天环境中配置不同的行为。
+
+## 过滤器
+
+很多时候，我们会希望某些功能只能对于某些群聊或私聊使用。使用权限管理意味着引入数据库，而更轻量的方式是通过 **过滤器 (Filter)** 直接影响插件的作用范围。
+
+### 插件过滤器
+
+::: tip
+少数插件与聊天平台无关，例如控制台、数据库插件等。这些插件也因此没有过滤器设置。
+:::
+
+大部分插件都提供了过滤器设置，就位于插件详情页的顶部。点击「添加条件」按钮可以创建一个过滤条件。可以通过设置过滤条件来包含或排除任意平台 / 用户 / 群组 / 频道 / 机器人。
+
+::: tip
+如果不知道这些 ID 是什么，可以使用 [获取账号信息](./platform.md#获取账号信息) 中介绍的 [inspect](../../plugins/common/inspect.md) 插件。
+:::
+
+添加一个条件后，你会发现下方的按钮变成了「添加『与』条件」和「添加『或』条件」两个。Koishi 的过滤器支持二级结构，内层的一系列条件以「与」的逻辑关系组成条件组，外层的一系列条件组以「或」的逻辑关系组成最终的过滤条件。
+
+### 条件属性
+
+Koishi 不仅支持在插件层级设置过滤器，某些配置项还支持在不同的会话下取不同的值。以全局设置为例，我们可以看到 `prefix`, `autoAssign` 等配置项的右侧有一个「…」按钮：
+
+![computed](/manual/console/computed.dark.webp) {.dark-only}
+
+![computed](/manual/console/computed.light.webp) {.light-only}
+
+点击这个「…」按钮，即可将普通的配置项变成一个计算属性。我们可以配置一系列满足某个过滤器以后的取值，以及一个不满足任何情况下的默认值。
+
+利用此特性，我们可以实现一些比较复杂的功能，例如：
+
+- 屏蔽某些群组内的一切消息
+- 在不同的平台下使用不同的指令前缀
+- 对特定的用户开放额外的使用额度
+
+## 国际化
+
+Koishi 是一个支持国际化的聊天机器人框架，这意味着 Koishi 机器人可以根据不同的环境使用不同的语言。这可能听起来跟你没啥关系……但先别走！读完这一节，或许你能掌握一些非常有用的功能。国际化并没有你想象得那么简单。
+
+### 设置语言偏好
+
+在 Koishi 中，应用本身及其管理的每个用户、每个频道都可以独立地设置语言偏好。其中，应用级别的默认语言通过全局配置项 `locale` 来设置，而用户、频道的语言偏好则通过 [admin](../../plugins/common/admin.md) 插件提供的 `user.locale` 和 `channel.locale` 指令来管理 (还记得指令系统中的 [这个例子](./command.md#子指令) 吧)。
+
+默认情况下，语言偏好的优先级是 频道 > 用户 > 全局。一个群组中可能有大量使用不同母语的用户参与讨论，为了方便交流通常会设置不同的语言频道。而对于此类情况，频道优先策略就可以让机器人在这些频道内始终使用预设好的语言来回答，而对于未设置语言偏好的频道，机器人仍然会遵循用户的偏好设置。当然，你也可以通过全局配置项 `i18n.output` 来更改此行为。
+
+### 本地化文本
+
+当然，绝大部分插件都仅仅支持了中文。如果你希望你的机器人支持其他语言，除了向这些插件的作者提交 Pull Request 外，还可以本地修改插件的文本。
+
+在活动栏中点击「本地化」，你将看到如下的界面：
+
+![locales](/manual/console/locales.dark.webp) {.dark-only}
+
+![locales](/manual/console/locales.light.webp) {.light-only}
+
+左侧可以选择类别，右上角可以选择要显示的语言，而中间则是编辑文本的区域。其中，文本框里的占位符对应于插件本身提供的文本，可以在翻译到其他语言时用做参考。
+
+然而，这个页面还有另一个用法，就是修改已有的文本！例如在上面的截图中，`low-authority` 原本对应到的文本是 `权限不足`，我们可以将它修改为 `哼，不给用`。现在让我们找个带权限等级的指令试试看有什么效果：
+
+<chat-panel>
+<chat-message nickname="Alice">authorize -u @Bob 5</chat-message>
+<chat-message nickname="Koishi">哼，不给用！</chat-message>
+</chat-panel>
+
+只要你如法炮制，就可以配置出一套完全属于你的机器人文案，让你的机器人与众不同。