logger, close #94

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`
 

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) 对象。
 
 ## 静态属性和方法
 

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))。
+:::

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