From f97feb32c4b6ddca1617ae53935bf854054499ae Mon Sep 17 00:00:00 2001
From: Him188 <Him188@mamoe.net>
Date: Tue, 14 Jun 2022 10:38:54 +0100
Subject: [PATCH] Add docs for mirai-console Logging and update UserManual
---
docs/UserManual.md | 28 ++++++++++++
mirai-console/docs/Logging.md | 63 ++++++++++++++++++++++++++
mirai-console/docs/plugin/JVMPlugin.md | 38 +---------------
3 files changed, 92 insertions(+), 37 deletions(-)
create mode 100644 mirai-console/docs/Logging.md
diff --git a/docs/UserManual.md b/docs/UserManual.md
index cfad5debb..f76827ce2 100644
--- a/docs/UserManual.md
+++ b/docs/UserManual.md
@@ -127,6 +127,34 @@ Mirai Console 内置一些指令，输入 `?` 并回车可以查看指令列表
详见 [`PermissionCommand`](/mirai-console/docs/BuiltInCommands.md#permissioncommand)
+### 配置
+
+Mirai Console 支持一些自定义配置。各项配置可以在 `config` 目录中找到。
+
+### 自动登录
+
+修改 `AutoLogin.yml` 可配置自动登录。也可以使用 `/autologin` 指令。
+
+### 指令前缀
+
+可以在 `Command.yml` 配置指令前缀，默认为 `/`。注意，部分指令可不需要前缀也能使用，这取决于插件开发者的选择。
+
+### 管理日志
+
+Mirai Console 会记录运行时的日志并保存到 `logs` 目录中，其中 `latest.log` 为最新日志。
+
+可以参考[日志文档](../mirai-console/docs/Logging.md)了解如何配置日志的详略程度。
+
+若要向插件开发者提交问题，建议将日志等级调整为 `ALL` 并复现问题后附加 `latest.log` 一并提交。
+
+### 配置权限
+
+`grantedPermissionMap.yml` 包含权限授予信息。通常建议使用指令 `/perm` 来修改权限，而不建议直接修改配置。
+
+### 远程仓库
+
+`repoLoc.yml` 包含对远程仓库的配置，通常不需要修改，除非某个插件要求。
+
## 解决问题
如果遇到使用问题或想提建议，可以在 [issues](https://github.com/mamoe/mirai/issues)
diff --git a/mirai-console/docs/Logging.md b/mirai-console/docs/Logging.md
new file mode 100644
index 000000000..ebf1e52fc
--- /dev/null
+++ b/mirai-console/docs/Logging.md
@@ -0,0 +1,63 @@
+# Mirai Console Backend - Logging
+
+Console 的日志一共有五个级别：
+
+| 级别（由高到低） | 用途 | 默认启用 |
+|:----------:|--------------|:------:|
+| ERROR | 记录影响程序运行的错误 | 是 |
+| WARNING | 记录不影响程序运行的警告 | 是 |
+| INFO | 记录一条普通信息 | 是 |
+| DEBUG | 记录普通调试信息 | 否 |
+| VERBOSE | 记录详细调试信息 | 否 |
+
+`DEBUG` 和 `VERBOSE`
+作为调试信息，默认关闭。插件开发者可能会使用这两个级别来输出调试信息。如果你在使用中遇到问题，启用这个两个级别获得更多日志后再报告开发者可能更有帮助。
+
+特别地，`ALL` 表示启用全部日志，`NONE` 表示禁用全部日志。
+
+在终端前端（或 [MCL](https://github.com/iTXTech/mirai-console-loader)
+），日志配置文件默认路径为 `config/Console/Logger.yml`。示例内容为如下。
+
+```yaml
+# 默认日志输出等级 可选值: ALL, VERBOSE, DEBUG, INFO, WARNING, ERROR, NONE
+defaultPriority: INFO
+# 特定日志记录器输出等级
+loggers:
+ example.logger: NONE
+ console.debug: NONE
+ Bot: ALL
+```
+
+## 调整全局默认日志等级
+
+修改 `defaultPriority` 即可修改全局默认日志等级。
+
+例如设置为 DEBUG，则启用上表中 DEBUG 及更高级别的日志，即
+DEBUG、INFO、WARNING、ERROR。
+
+## 调整特定日志等级
+
+每个插件被分配的日志的 ID 为插件的显示名称。
+
+提示：该 ID 也可以在日志中找到。如下面的日志中，`Bot 12345678` 就是其所属日志的 ID。（`V`
+代表等级为 VERBOSE，以首字母识别）
+
+```text
+2022-05-02 11:09:28 V/Bot 12345678: Event: BotOnlineEvent(bot=Bot(12345678))
+```
+
+如果在日志配置这样修改：
+
+```yaml
+loggers:
+ "Bot 12345678": NONE
+```
+
+那么将禁用来自该 Bot 的所有日志。
+
+假设要启用名为 `Chat Command` 的插件的 DEBUG 及更高级别的日志：
+
+```yaml
+loggers:
+ "Chat Command": DEBUG
+```
diff --git a/mirai-console/docs/plugin/JVMPlugin.md b/mirai-console/docs/plugin/JVMPlugin.md
index 41ba7b181..ac2c9c02e 100644
--- a/mirai-console/docs/plugin/JVMPlugin.md
+++ b/mirai-console/docs/plugin/JVMPlugin.md
@@ -330,43 +330,7 @@ public final class JExample extends JavaPlugin {
}
```
-Console 的日志一共有五个级别：
-
-| 级别（由高到低） | 用途 | 默认启用 |
-|:----------:|--------------|:------:|
-| ERROR | 记录影响程序运行的错误 | 是 |
-| WARNING | 记录不影响程序运行的警告 | 是 |
-| INFO | 记录一条普通信息 | 是 |
-| DEBUG | 记录普通调试信息 | 否 |
-| VERBOSE | 记录详细调试信息 | 否 |
-
-由于 DEBUG 和 VERBOSE
-默认是禁用的，插件开发者可以自由使用这两个级别的日志来辅助进行调试工作。也可以在当用户遇到问题时，让用户单独启用这些日志来获取调试信息。
-
-可以在配置 `config/Console/Logger.yml` 中进行如下操作：
-
-### 调整全局日志等级
-
-修改 `defaultPriority`，若设置为 DEBUG，则启用上表中 DEBUG 及更高级别的日志，即
-DEBUG、INFO、WARNING、ERROR。
-
-### 调整特定日志等级
-
-每个插件被分配的 MiraiLogger 的 ID (identity) 为插件描述的名称（name）。
-
-在 `loggers` 增加对名称的配置，示例（启用名为 `Chat Command` 的插件的 DEBUG 及更高级别的日志）：
-
-```yaml
-loggers:
- "Chat Command": DEBUG
-```
-
-提示：该 ID 也可以在日志中找到。如下面的日志中，`Bot 12345678` 就是其所属 MiraiLogger 的 ID。（其前 V
-代表等级为 VERBOSE）
-
-```text
-2022-05-02 11:09:28 V/Bot 12345678: Event: BotOnlineEvent(bot=Bot(12345678))
-```
+有关日志的配置方式可以参考 [Logging](../Logging.md)
## 插件生命周期与依赖管理