From 70ae42d6c77749a59b667839e313381b63937716 Mon Sep 17 00:00:00 2001
From: Shigma <shigma10826@gmail.com>
Date: Wed, 6 Sep 2023 21:52:30 +0800
Subject: [PATCH] logger, close #94

---
 zh-CN/api/core/app.md       |  49 ++---------
 zh-CN/api/core/context.md   |   4 +-
 zh-CN/api/service/logger.md | 161 ------------------------------------
 zh-CN/api/utils/logger.md   |  86 +++++++++++++++++--
 zh-CN/guide/index.md        |   5 +-
 5 files changed, 92 insertions(+), 213 deletions(-)
 delete mode 100644 zh-CN/api/service/logger.md

diff --git a/zh-CN/api/core/app.md b/zh-CN/api/core/app.md
index 81242758da5f..2880e1a7c5df 100644
--- a/zh-CN/api/core/app.md
+++ b/zh-CN/api/core/app.md
@@ -4,12 +4,12 @@
 
 ## 构造函数选项
 
-通过 `new App(options)` 创建一个 App 实例。
+通过 `new App(options)` 创建一个 App 实例。下面的配置项也可以在配置文件中使用。
 
 ### options.host
 
 - 类型：`string`
-- 默认值：`'localhost'`
+- 默认值：`'127.0.0.1'`
 
 服务器监听的 IP 地址。如果将此设置为 `0.0.0.0` 将监听所有地址，包括局域网和公网地址。
 
@@ -78,12 +78,6 @@ Koishi 服务暴露在公网的地址。部分功能（例如 [adapter-telegram]
 
 当获取不到频道数据时，是否将接收到消息的机器人设置为该频道的受理人。
 
-### options.prettyErrors
-
-- 类型：`boolean`
-
-启用报错优化模式。在此模式下 Koishi 会对程序抛出的异常进行整理，过滤掉框架内部的调用记录，输出更易读的提示信息。默认值为 `true`。
-
 ### options.minSimilarity
 
 - 类型：`number`
@@ -99,7 +93,9 @@ Koishi 服务暴露在公网的地址。部分功能（例如 [adapter-telegram]
 
 ## 配置文件选项
 
-下面的配置项来自 Koishi 的命令行工具，仅可用于配置文件。
+::: warning
+下面的配置项来自 Koishi 的命令行工具，仅可在配置文件中编辑，不支持在控制台中修改。
+:::
 
 ### options.plugins
 
@@ -112,42 +108,13 @@ Koishi 服务暴露在公网的地址。部分功能（例如 [adapter-telegram]
 
 ### options.logger
 
-#### options.logger.levels
-
-- 类型：`number | object`
-- 默认值：`{}`
-
-默认的输出等级。参见 [设置输出等级](../utils/logger.md#logger-level) 一节。
-
-#### options.logger.showTime
-
-- 类型：`string | boolean`
-- 默认值：`false`
-
-输出日志所使用的时间格式。参见 [输出时间](../utils/logger.md#not-exist) 一节。
-
-#### options.logger.showDiff
-
-- 类型：`boolean`
-- 默认值：初始未设置，在 ready 事件触发后修改为 `!options.logTime`
-
-是否标注相邻两次输出的时间差。参见 [输出时间](../utils/logger.md#not-exist) 一节。
-
-### options.watch
-
-- 类型：[`WatchOptions`](https://github.com/paulmillr/chokidar#api) 外加下面的属性：
-  - **watch.root:** `string` 要监听的根目录，相对于工作路径
-  - **watch.debounce:** `number` 延迟触发更新的等待时间，默认为 `100`
-
-监听文件变化的选项。参见 [模块热替换](../../guide/develop/script.md#模块热替换) 一节。
-
-### options.timezoneOffset
+- 类型：`Logger.Config`
 
-### options.stackTraceLimit
+参见 [输出日志](../utils/logger.md) 一节。
 
 ## 实例属性和方法
 
-### app.config
+### app.options
 
 - 类型: `AppOptions`
 
diff --git a/zh-CN/api/core/context.md b/zh-CN/api/core/context.md
index 10ebd14dc12d..19fa01932041 100644
--- a/zh-CN/api/core/context.md
+++ b/zh-CN/api/core/context.md
@@ -70,9 +70,9 @@ Koishi 使用了面向切面编程 (AOP) 的开发方式，绝大部分上下文
 ### ctx.logger(scope?)
 
 - **scope:** `string` 要指定的类型，默认为 `''`
-- 返回值: [`Logger`](../service/logger.md)
+- 返回值: [`Logger`](../utils/logger.md)
 
-根据 namespace 生成一个 [Logger 对象](../service/logger.md)。
+根据命名空间生成一个 [Logger](../utils/logger.md) 对象。
 
 ## 静态属性和方法
 
diff --git a/zh-CN/api/service/logger.md b/zh-CN/api/service/logger.md
deleted file mode 100644
index ef6ec3a2a618..000000000000
--- a/zh-CN/api/service/logger.md
+++ /dev/null
@@ -1,161 +0,0 @@
-# 输出与日志
-
-::: danger 注意
-此页文档正在施工，其中的内容可能不是最新。
-:::
-
-本章主要介绍如何控制 Koishi 命令行工具的输出。
-
-## 配置输出
-
-### 控制输出等级
-
-**输出等级**控制了所有输出到命令行的内容的重要性。在 Koishi 内置的输出系统中，所有信息被分为了 3 种不同的等级：
-
-1. error, success
-2. warning, info
-3. debug
-
-相应地，当设置输出等级为 x 时，Koishi 只会输出重要性小于等于 x 的信息。当输出等级被设置为 0 时，Koishi 将不产生任何输出；而当输出等级被设置为 3 时，Koishi 产生的全部信息都会被显示在屏幕上（当然下面还会介绍过滤器，你可以通过手动设置过滤器减少输出。）
-
-需要注意的是，运行时产生的错误（如请求失败，数据库访问失败等）都属于 warning，只有在创建阶段和连接阶段抛出的错误才会通过 error 输出（参见 [生命周期](./events.md)）。
-
-默认情况下 Koishi 的输出等级为 2。同时你有多种方法修改这个值。
-
-你可以在配置文件中控制输出等级：
-
-```js title=koishi.js
-module.exports = {
-  logLevel: 3,
-}
-```
-
-在使用 `koishi start` 指令时，你也可以加入一个 `--log-level` 选项，它的值可以是 0~3 之间的一个整数，表示不同的输出等级。例如，`--log-level=0` 就表示不产生任何输出。
-
-上述两种方法的功能类似，但是 CLI 选项将具有更高的优先级，这样允许你临时覆盖一些配置。
-
-### 在日志中显示时间
-
-如果你希望在每行输出前打印当前的时间，可以使用配置项 `logTime` 或者命令行选项 `--log-time`。这个选项既可以单纯地配置，也可以传入一个字符串作为输出时间的格式。基本语法如下：
-
-- yyyy: 四位数年份
-- yy: 年份末两位
-- MM: 两位数月份
-- dd: 两位数日期
-- hh: 两位数小时
-- mm: 两位数分钟
-- ss: 两位数秒
-- SSS: 三位数毫秒
-
-当配置为 `true` 时，这一项时的默认格式为 `yyyy/MM/dd hh:mm:ss`。
-
-## 命名空间
-
-### 在插件中输出
-
-如果你是插件开发者，你也可以主动调用 Koishi 内置的 Logger API 来输出调试信息，这样用户就可以用上述的方法来控制你的插件的输出等级了。具体使用方法是这样的：
-
-```js title=my-plugin.js
-module.exports = (ctx) => {
-  // 生成一个 Logger 对象，foo 作为它的命名空间
-  const logger = ctx.logger('foo')
-
-  doSomething()
-    // 调用 logger 方法来产生输出
-    .then(() => logger.success('hello'))
-    .catch(() => logger.warn('failed'))
-}
-```
-
-上面的这个 Logger 对象有下面的方法，它们的函数签名与 `console.log` 一致：
-
-```ts no-extra-header
-export interface Logger {
-  warn(format: any, ...param: any[]): void
-  info(format: any, ...param: any[]): void
-  debug(format: any, ...param: any[]): void
-  success(format: any, ...param: any[]): void
-  error(format: any, ...param: any[]): void
-}
-```
-
-### 过滤命名空间
-
-前面所说的命名空间不仅会作为输出的前缀，还能用于过滤输出。用户可以通过将 `logLevel` 配置成对象的形式，指定每一个插件产生的输出的等级，就像这样：
-
-```js title=koishi.js
-module.exports = {
-  logLevel: {
-    // 基础输出等级，当没有找到对应的配置项时将使用这个值
-    // 如果配置了 koishi start --log-level，将覆盖这个值
-    base: 3,
-    // 过滤掉所有等级大于 2 的来自命名空间 foo 的输出
-    foo: 2,
-  },
-}
-```
-
-Koishi 也支持多级命名空间，每一级之间用冒号分隔，你可以用下面的方式声明一个子命名空间：
-
-```js title=plugin-foo.js
-module.exports = (ctx) => {
-  // 这两种写法是等价的
-  const logger = ctx.logger('foo:temp')
-  const logger = ctx.logger('foo').extend('temp')
-  // 执行其他代码并使用 logger 产生输出
-}
-```
-
-然后，你也可以将你的配置项具体到每一级命名空间中：
-
-```js title=koishi.js
-module.exports = {
-  logLevel: {
-    foo: {
-      // 这里也支持配置 base，当然你也可以不写，表示继承上一级的默认等级
-      base: 1,
-      temp: 3,
-    },
-  },
-}
-```
-
-### 配置调试输出
-
-此外，koishi 还提供了一个 `--debug` 选项，你可以临时配置那些要以等级 3 进行输出的命名空间，中间用逗号隔开。例如，`--debug=onebot,foo:temp` 就表示输出来自 onebot 和 foo:temp 的全部内容。
-
-同 `--log-level` 类似，这个选项也将覆盖配置文件中的相关配置。
-
-## 手动调用 Logger
-
-如果你不希望使用 Koishi 的命令行工具，同时又想使用上述种种特性，你可以考虑直接调用 Logger 的底层方法来进行配置。
-
-::: warning
-由于手动调用 Logger 并不是我们所推荐的行为，本节中介绍的属性和方法不会记录在文档中，Koishi 也不会保证这些功能不会在版本更新中发生变化。在开发时，请尽量以 @koishijs/utils 包提供的 dts 文件，而非本页面为准。
-:::
-
-### Logger.showTime
-
-- 类型：`string`
-
-对应配置项 [`logTime`](../../api/core/app.md#options-logtime)，只支持字符串格式。默认值为空串。
-
-### Logger.showDiff
-
-- 类型：`boolean`
-
-对应配置项 [`logDiff`](../../api/core/app.md#options-logdiff)。默认值为 `false`。
-
-### Logger.levels
-
-- 类型：`LogLevelConfig`
-
-对应配置项 [`logLevel`](../../api/core/app.md#options-loglevel) 和 [`logFilter`](../../api/core/app.md#options-logfilter)，只支持对象格式。默认值为 `{ base: 2 }`。
-
-## 内置的输出
-
-Koishi 自身会产生下列类型的 logger 输出：
-
-TODO
-
-利用上面的方法，你可以借助 koishi 的输出对你的机器人进行调试。
diff --git a/zh-CN/api/utils/logger.md b/zh-CN/api/utils/logger.md
index 8d533f53cd52..70d07826faf4 100644
--- a/zh-CN/api/utils/logger.md
+++ b/zh-CN/api/utils/logger.md
@@ -1,17 +1,87 @@
 # 输出日志 (Logger)
 
-## new Logger(name)
+::: tip
+本节中的源码位于 [reggol](https://github.com/shigma/reggol)。
+:::
 
-## logger.level
+## 输出等级
 
-## logger.extend()
+**输出等级**控制了所有输出到命令行的内容的重要性。在 Koishi 内置的输出日志中，所有信息被分为了 3 种不同的等级：
 
-## logger.error()
+1. error, success
+2. warning, info
+3. debug
 
-## logger.success()
+当设置输出等级为 x 时，Koishi 只会输出重要性小于等于 x 的信息。当输出等级被设置为 0 时，Koishi 将不产生任何输出；而当输出等级被设置为 3 时，Koishi 产生的全部信息都会被显示在屏幕上 (你还可以通过配置 [`levels`](#options-logger-levels) 的方式影响具体插件的输出)。
 
-## logger.warn()
+默认情况下 Koishi 的输出等级为 2。你可以在配置文件中修改这个值。
 
-## logger.info()
+## 配置文件选项
 
-## logger.debug()
+### options.logger.levels
+
+- 类型：`number | object`
+- 默认值：`{}`
+
+设置输出等级。例如：
+
+```yaml
+logger:
+  levels:
+    # 将 app 命名空间的输出等级设置为 3
+    app: 3
+```
+
+### options.logger.showTime
+
+- 类型：`string | boolean`
+- 默认值：`'yyyy/MM/dd hh:mm:ss'`
+
+输出日志所使用的时间格式。它的基本语法如下：
+
+- yyyy: 四位数年份
+- yy: 年份末两位
+- MM: 两位数月份
+- dd: 两位数日期
+- hh: 两位数小时
+- mm: 两位数分钟
+- ss: 两位数秒
+- SSS: 三位数毫秒
+
+如设置为 `false`，则不会输出时间。如设置为 `true`，将视为上述默认值。
+
+### options.logger.showDiff
+
+- 类型：`boolean`
+- 默认值：`!config.logger.showTime`
+
+是否标注相邻两次输出的时间差。
+
+## 类：Logger
+
+通常使用 `Logger` 类来进行日志输出。
+
+### new Logger(name)
+
+创建一个新的 Logger 实例。
+
+`name` 参数用于指定命名空间，它将作为输出的前缀，并且可以被过滤。
+
+### logger.error(format, ...param)
+
+### logger.success(format, ...param)
+
+### logger.warn(format, ...param)
+
+### logger.info(format, ...param)
+
+### logger.debug(format, ...param)
+
+- **format:** `any` 格式化字符串
+- **param:** `any[]` 要输出的内容
+
+以不同的输出等级输出日志。参数的使用方法与 [`console.log`](https://developer.mozilla.org/zh-CN/docs/Web/API/Console/log) 相同。
+
+::: tip
+运行时产生的错误 (如请求失败，数据库访问失败等) 都属于 warning，只有在创建阶段和连接阶段抛出的错误才会通过 error 输出 (参见 [生命周期](../../guide/plugin/lifecycle.md))。
+:::
diff --git a/zh-CN/guide/index.md b/zh-CN/guide/index.md
index 5fa79a962c36..1fff28b3fad4 100644
--- a/zh-CN/guide/index.md
+++ b/zh-CN/guide/index.md
@@ -16,7 +16,10 @@ Koishi 是一个强大的机器人框架，因此有大量的内容可供学习
 
 ## 预备知识
 
-Koishi 是一个 Node.js 框架，因此我们假定你已经拥有了一定的 JavaScript 和 Node.js 开发基础。如果你对自己的基础不自信，这里有一篇 [JavaScript 教程](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Language_Overview)。这可能会花费你 30 分钟到 1 个小时的时间，但这样做的好处是你不会觉得同时在学习 Koishi 和 JavaScript。
+Koishi 是一个 Node.js 框架，因此我们假定你已经拥有了一定的 JavaScript 和 Node.js 开发基础。如果你对自己的基础不自信，可以参考下面的两篇教程：
+
+- [JavaScript 语言概览](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Language_Overview)
+- [现代 JavaScript 教程](https://zh.javascript.info/)
 
 ### 关于 TypeScript