refactor(docs): clarify docs

Author: Aliorpse

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/dsl/SaltifyPluginContext.kt

@@ -22,14 +22,14 @@ import kotlin.time.Duration
 
 @SaltifyDsl
 public class SaltifyPluginContext internal constructor(
-    name: String,
+    pluginName: String,
     public val client: SaltifyApplication,
     @PublishedApi internal val pluginScope: CoroutineScope
 ) : CoroutineScope by pluginScope {
     internal val onStartHooks = mutableListOf<suspend () -> Unit>()
     internal val onStopHooks = mutableListOf<() -> Unit>()
 
-    public val logger: Logger = KtorSimpleLogger("Saltify/plugin:$name")
+    public val logger: Logger = KtorSimpleLogger("Saltify/plugin:$pluginName")
 
     /**
      * 插件被加载，即 [SaltifyApplication.Companion.invoke] 后执行的逻辑。

saltify-docs/.vitepress/config.mts

@@ -16,14 +16,14 @@ export default defineConfig({
     ],
 
     sidebar: [
-      { text: '快速上手', link: '/quick-tour' },
+      { text: '快速开始', link: '/quick-tour' },
       {
-        text: '开发指南',
+        text: 'saltify-core 文档',
         items: [
-          { text: '核心配置', link: '/guide/application' },
+          { text: '应用配置', link: '/guide/application' },
           { text: '插件开发', link: '/guide/plugin' },
-          { text: '指令系统', link: '/guide/command' },
-          { text: '日志配置', link: '/guide/logging' }
+          { text: '指令开发', link: '/guide/command' },
+          { text: '日志实现', link: '/guide/logging' }
         ]
       }
     ],

saltify-docs/content/guide/application.md

@@ -1,8 +1,8 @@
-# 核心配置
+# 应用配置
 
 ## 初始化 `SaltifyApplication`
 
-可以通过以下方式快速配置一个 Saltify 实例。这里仅展示了核心配置。
+可以通过以下方式创建 Saltify 实例。这里仅展示了核心配置。
 
 ```kotlin
 val client = SaltifyApplication {
@@ -16,7 +16,7 @@ val client = SaltifyApplication {
             autoReconnect = true
         }
     }
-}.start()
+}.start() // 不要忘记这里的 start() 调用！
 ```
 
 事件服务连接不会自动建立，你需要手动调用 `connectEvent()` 才会真正开始监听事件。
@@ -38,7 +38,7 @@ suspend fun main() {
 
 ## 全局异常处理
 
-Saltify 提供了用于监控未显式捕获的异常的 Flow，一般必须收集以实现自定义逻辑，否则**全部异常都会被无视**。
+Saltify 提供了用于监控未显式捕获的异常的 Flow，如果选择使用日志功能，报错等信息会自动打印到控制台。你可以通过以下代码实现自定义逻辑：
 
 ```kotlin
 launch {
@@ -56,6 +56,8 @@ launch {
 }
 ```
 
+如上所见，所有 Saltify 创建的协程都有一个名为 `SaltifyComponent` 的上下文，它包含了组件的元信息。例如这里，Application 代表应用实例。
+
 ## 事件服务状态监听
 
 Saltify 还提供了一个 Flow 用于监控事件服务连接状态的变更：
@@ -67,3 +69,5 @@ launch {
     }
 }
 ```
+
+需要注意的是，由连接状态断开引起的异常不会出现在 Application 异常流，而是会在这个流中出现。

saltify-docs/content/guide/command.md

@@ -1,10 +1,10 @@
-# 指令系统
+# 指令开发
 
 Saltify 提供了一套类型安全的指令构建 DSL，支持参数解析、子指令以及特定上下文的执行逻辑。
 
-## 基础指令与参数解析
+## 定义指令
 
-你可以为指令定义类型安全的参数，并通过 `.value` 快速获取。
+以下是一个简单的指令定义：
 
 ```kotlin
 client.command("order", prefix = "/") {
@@ -14,9 +14,8 @@ client.command("order", prefix = "/") {
     val note = greedyStringParameter("note")
 
     onExecute {
-        respond {
-            text("Order #${id.value} created\nnote：${note.value}")
-        }
+        // some logic...
+        respond("订单 #${id.value} 已创建\nNote：${note.value}")
     }
 
     onFailure { error ->
@@ -32,7 +31,7 @@ onFailure 块是**解析**失败的处理，注意这里不是异常，而是指
 默认情况下，如果不定义这个块，会忽视所有解析错误，并对指令不做回复。
 
 > [!tip]
-> 与 `on` 一样，command 在插件初始化块中也是可以使用的，并且不用手动传 client。
+> 与 `on` 一样，command 在插件初始化块中也是可以，并且推荐使用的。不需要传 `client`。
 
 ## 上下文隔离
 
@@ -41,11 +40,11 @@ onFailure 块是**解析**失败的处理，注意这里不是异常，而是指
 ```kotlin
 client.command("info") {
     onGroupExecute {
-        respond { text("这是群聊专用的信息！") }
+        respond("这是群聊专用的信息！")
     }
 
     onPrivateExecute {
-        respond { text("这是私聊专用的信息！") }
+        respond("这是私聊专用的信息！")
     }
 
     onExecute {
@@ -57,22 +56,50 @@ client.command("info") {
 > [!tip]
 > `onGroupExecute` 和 `onPrivateExecute` 的优先级**高于** `onExecute`。如果群聊触发了指令且你定义了 `onGroupExecute`，那么 `onExecute` 中的兜底逻辑将**不会**被执行。
 
+## 子指令
+
+通过 `subCommand` 函数，可以方便地定义一个任意嵌套层级的指令树：
+
+```kotlin
+command("math") {
+    // /math add <num1> <num2>
+    subCommand("add") {
+        val a = parameter<Int>("a")
+        val b = parameter<Int>("b")
+
+        onExecute {
+            val result = a.value + b.value
+            respond("$result")
+        }
+    }
+
+    // /math power <base>
+    subCommand("power") {
+        val base = parameter<Int>("base")
+        onExecute {
+            val value = base.value
+            respond("$value 的平方是 ${value * value}")
+        }
+    }
+}
+```
+
 ## 上下文交互
 
 在指令执行上下文中，你可以挂起当前协程，等待该用户的下一条回复。
 
 ```kotlin
 client.command("shutdown") {
     onExecute {
-        respond { text("真的要关机吗？") }
+        respond("真的要关机吗？")
 
         // 等待该用户在同一上下文中发送的下一条消息（默认 30 秒超时）
         val replyEvent = awaitNextMessage(timeout = 30.seconds)
 
         if (replyEvent == null) {
-            respond { text("等待超时") }
+            respond("等待超时")
         } else {
-            respond { text("你回复了我，但这不重要，无论如何，我都不想关掉我自己！") }
+            respond("你回复了我，但这不重要，无论如何，我都不想关掉我自己！")
         }
     }
 }

saltify-docs/content/guide/logging.md

@@ -1,16 +1,10 @@
-# 日志配置
+# 日志实现
 
 Saltify 使用 KtorSimpleLogger 输出运行时日志。
 
 ## JVM 平台
 
-在 JVM 平台上，使用 SLF4J 作为日志框架，这里以 Logback 为例：
-
-```kotlin
-dependencies {
-    implementation("ch.qos.logback:logback-classic:$logbackVersion")
-}
-```
+这里依照快速开始中的日志配置，使用 Logback 框架。
 
 ### 配置日志
 

saltify-docs/content/guide/plugin.md

@@ -4,7 +4,7 @@
 
 ## 定义插件
 
-你可以预先定义一个 `SaltifyPlugin`，或者在应用配置时直接使用 `plugin {}` 块。
+可以预先定义一个 `SaltifyPlugin`：
 
 ```kotlin
 class MyPluginConfig(
@@ -14,14 +14,13 @@ class MyPluginConfig(
 
 val myPlugin = SaltifyPlugin("my-awesome-plugin", ::MyPluginConfig) { config ->
     // 插件加载完成后的初始化逻辑
-    // 这里的 `name` 就是 "my-awesome-plugin"
     onStart {
-        println("[$name] 插件已启动！")
+        println("插件已启动！")
     }
 
     // 应用关闭时的清理逻辑
     onStop {
-        println("[$name] 插件已停止！")
+        println("插件已停止！")
     }
 
     // 监听特定事件
@@ -38,16 +37,20 @@ val myPlugin = SaltifyPlugin("my-awesome-plugin", ::MyPluginConfig) { config ->
 }
 ```
 
+> [!tip]
+> 所有 `respond` 函数都有一个为纯文本情况提供的简写形式。如上例，完全可以写成 `event.respond(config.reply)`。
+
+
 ## 安装插件
 
 ```kotlin
 val client = SaltifyApplication {
-    // 安装插件
+    // 1. 安装外部插件
     install(myPlugin) {
         reply = "Hello!!"
     }
 
-    // 或者直接内联定义
+    // 2. 或者直接内联定义
     plugin("another-plugin") {
         onStart { /* ... */ }
     }

saltify-docs/content/index.md

@@ -6,7 +6,7 @@ hero:
   tagline: 跨平台、可扩展的 QQ Bot 框架 & Milky SDK
   actions:
     - theme: brand
-      text: 快速上手
+      text: 快速开始
       link: /quick-tour
 
 features:

saltify-docs/content/quick-tour.md

@@ -1,6 +1,6 @@
 # 快速上手
 
-欢迎来到 Saltify 的文档！本页面将会通过简单的示例介绍如何快速上手 Saltify。
+欢迎来到 Saltify 的文档！
 
 ## 开始之前
 
@@ -13,95 +13,16 @@
 ```kotlin
 dependencies {
     implementation("org.ntqqrev:saltify-core:$saltifyVersion")
+
+    // 你可以选择为 Ktor client 使用不同的引擎而不是 cio，这里只是一个推荐。
     implementation("io.ktor:ktor-client-cio:$ktorVersion")
+
+    // 日志相关实现。同样，可以选择你所需要的平台日志实现。
+    implementation("ch.qos.logback:logback-classic:$logbackVersion")
 }
 ```
 
-你可以选择为 Ktor client 使用不同的引擎而不是 cio，这里只是一个推荐。
-
 > [!warning]
 > 本项目仍处于开发阶段，**强烈建议自行构建项目并依赖你的本地构建**，目前本文档将基于最新提交而不是最新发行版。待项目稳定会区分稳定文档与开发文档。
 
-## 初始化 `SaltifyApplication`
-
-```kotlin
-val client = SaltifyApplication {
-    connection {
-        baseUrl = "http://localhost:3000"
-        accessToken = "your_token"
-
-        // 事件服务相关配置
-        events {
-            type = EventConnectionType.WebSocket
-            autoReconnect = true
-        }
-    }
-}.start()
-```
-
-更多内容请参见[核心配置](guide/application.md)。请在浏览完本页后**一定仔细阅读**这一页。
-
-## 调用 API
-
-```kotlin
-// 获取登录信息
-val loginInfo = client.getLoginInfo()
-
-// 发送群消息
-client.sendGroupMessage(123456789L) {
-    text("Hello from Saltify!")
-    image("https://example.com/example.jpg")
-}
-```
-
-更多 API 请参见项目源码与 [Milky 文档](https://milky.ntqqrev.org/)。
-
-## 定义插件
-
-插件是一系列功能的集合，建议将功能逻辑封装在插件中。
-
-```kotlin
-val myPlugin = SaltifyPlugin("my-plugin") {
-    onStart {
-        println("插件已启动")
-    }
-
-    on<Event.GroupMemberIncrease> { event ->
-        println("新成员加入: ${event.userId}")
-    }
-}
-
-val client = SaltifyApplication {
-    // ...
-
-    // 在初始化时安装插件
-    install(myPlugin)
-    
-    // 也可以直接定义插件并安装
-    plugin {
-        // ...
-    }
-}
-```
-
-更多内容请参见[插件开发](guide/plugin.md)。
-
-## 定义指令
-
-```kotlin
-client.command("say") {
-    val content = greedyStringParameter("content", "要重复的内容")
-
-    onExecute {
-        respond {
-            text(content.value)
-        }
-    }
-}
-```
-
-更多内容请参见[指令系统](guide/command.md)。
-
-## 日志输出
-
-请参见[日志配置](guide/logging.md)
+在完成了以上配置后，点击页面下方的按钮，了解如何使用 Saltify 构建应用！