docs: decouple introductions from one file

Author: Aliorpse

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

@@ -29,14 +29,14 @@ public class SaltifyCommandContext internal constructor() {
     internal var failureBlock: (suspend SaltifyCommandExecutionContext.(CommandError) -> Unit)? = null
 
     /**
-     * 注册一个子命令。
+     * 注册一个子指令。
      */
     public fun subCommand(name: String, block: SaltifyCommandContext.() -> Unit) {
         subCommands.add(name to SaltifyCommandContext().apply(block))
     }
 
     /**
-     * 定义一个命令参数。请搭配 [SaltifyCommandExecutionContext.capture] 使用。
+     * 定义一个指令参数。请搭配 [SaltifyCommandExecutionContext.capture] 使用。
      */
     public fun <T : Any> parameter(
         type: KClass<T>,
@@ -57,7 +57,7 @@ public class SaltifyCommandContext internal constructor() {
     }
 
     /**
-     * 设置通用的命令执行逻辑。
+     * 设置通用的指令执行逻辑。
      */
     public fun onExecute(block: suspend SaltifyCommandExecutionContext.() -> Unit) {
         executionBlock = block
@@ -78,7 +78,7 @@ public class SaltifyCommandContext internal constructor() {
     }
 
     /**
-     * 当命令**解析**失败时执行的逻辑。
+     * 当指令**解析**失败时执行的逻辑。
      */
     public fun onFailure(block: suspend SaltifyCommandExecutionContext.(CommandError) -> Unit) {
         failureBlock = block
@@ -109,14 +109,14 @@ public class SaltifyCommandExecutionContext(
         get() = capture(this)
 
     /**
-     * 响应命令。
+     * 响应指令。
      */
     public suspend fun respond(
         block: MutableList<OutgoingSegment>.() -> Unit
     ): SendMessageOutput = event.respond(client, block)
 
     /**
-     * 响应命令，并在指定延迟后撤回消息。
+     * 响应指令，并在指定延迟后撤回消息。
      */
     @ContextParametersMigrationNeeded
     public suspend inline fun respondWithRecall(
@@ -132,7 +132,7 @@ public class SaltifyCommandExecutionContext(
     }
 
     /**
-     * 获取由命令触发者发送的下一条消息事件。超时返回 null。
+     * 获取由指令触发者发送的下一条消息事件。超时返回 null。
      */
     public suspend fun awaitNextMessage(timeout: Duration = 30.seconds): Event.MessageReceive? {
         val messageFlow = client.eventFlow.filterIsInstance<Event.MessageReceive>()
@@ -155,7 +155,7 @@ public class SaltifyCommandExecutionContext(
 }
 
 /**
- * 命令参数
+ * 指令参数
  */
 public class SaltifyCommandParamDef<T : Any>(
     public val type: KClass<T>,

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

@@ -47,7 +47,7 @@ public class SaltifyPluginContext internal constructor(
     ): Job = client.on(pluginScope, block)
 
     /**
-     * 注册一个命令。
+     * 注册一个指令。
      */
     public fun command(
         name: String,

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/extension/ApplicationExtension.kt

@@ -35,7 +35,7 @@ public inline fun <reified T : Event> SaltifyApplication.on(
 private val spaceRegex = Regex("\\s+")
 
 /**
- * 注册一个命令。
+ * 注册一个指令。
  */
 public fun SaltifyApplication.command(
     name: String,

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/extension/CommandContextExtension.kt

@@ -5,7 +5,7 @@ import org.ntqqrev.saltify.dsl.SaltifyCommandExecutionContext
 import org.ntqqrev.saltify.dsl.SaltifyCommandParamDef
 
 /**
- * 定义一个命令参数。请搭配 [SaltifyCommandExecutionContext.capture] 使用。
+ * 定义一个指令参数。请搭配 [SaltifyCommandExecutionContext.capture] 使用。
  */
 public inline fun <reified T : Any> SaltifyCommandContext.parameter(
     name: String,

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/model/CommandError.kt

@@ -3,7 +3,7 @@ package org.ntqqrev.saltify.model
 import org.ntqqrev.saltify.dsl.SaltifyCommandParamDef
 
 /**
- * 命令解析错误
+ * 指令解析错误
  */
 public sealed class CommandError {
     public abstract val message: String

saltify-docs/.vitepress/config.mts

@@ -1,20 +1,29 @@
 import { defineConfig } from 'vitepress';
 
-// https://vitepress.dev/reference/site-config
 export default defineConfig({
   srcDir: 'content',
 
   title: 'Saltify 文档',
   description: 'Documentation of Saltify',
   themeConfig: {
-    // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: '主页', link: '/' },
       { text: 'Milky', link: 'https://milky.ntqqrev.org/' },
     ],
 
     sidebar: [
-      { text: '快速上手', link: '/quick-tour' },
+      {
+        text: '快速上手',
+        items: [ { text: 'API 概览', link: '/quick-tour' } ]
+      },
+      {
+        text: '开发指南',
+        items: [
+          { text: '核心配置与异常处理', link: '/guide/application' },
+          { text: '插件开发', link: '/guide/plugin' },
+          { text: '指令系统', link: '/guide/command' }
+        ]
+      }
     ],
 
     socialLinks: [

saltify-docs/content/guide/application.md

@@ -0,0 +1,61 @@
+# 核心配置与异常处理
+
+## 应用实例化与基础配置
+
+可以通过以下方式快速配置一个 Saltify 实例。这里仅展示了核心配置。
+
+```kotlin
+val client = SaltifyApplication {
+    addressBase = "http://localhost:3000"
+    accessToken = "your_token" // 选填：访问令牌（不用加 Bearer）
+
+    // 事件服务连接配置
+    eventConnection {
+        type = EventConnectionType.WebSocket // 可选 WebSocket 或 SSE
+        autoReconnect = true
+    }
+}
+```
+
+事件服务连接不会自动建立，你需要手动调用 `connectEvent()` 才会真正开始监听事件。
+
+```kotlin
+suspend fun main() {
+    val client = SaltifyApplication { /* ... */ }
+
+    client.connectEvent() 
+    
+    // 其他逻辑
+
+    // 断开事件连接服务，可复用
+    client.disconnectEvent()
+}
+```
+
+另外，应用和插件都有生命周期管理。在程序退出时，务必调用 `close()` 方法释放资源，这会触发所有已加载插件的 `onStop` 钩子并关闭 HTTP 客户端。
+
+## 全局异常处理与事件服务状态
+
+Saltify 提供了用于监控连接状态和异常的 Flow，一般必须收集以实现自定义逻辑，否则**全部异常都会被无视**。
+
+```kotlin
+launch {
+    client.eventConnectionStateFlow.collect { state ->
+        println("连接状态变更: $state")
+    }
+}
+
+launch {
+    client.exceptionFlow.collect { (context, exception) ->
+        val component = context.saltifyComponent!!
+
+        when (component.type) {
+            SaltifyComponentType.Application -> throw exception
+            else -> println(
+                "组件 ${component.name}(${component.type}) 抛出了一个异常: " +
+                        exception.stackTraceToString()
+            )
+        }
+    }
+}
+```

saltify-docs/content/guide/command.md

@@ -0,0 +1,75 @@
+# 指令系统
+
+Saltify 提供了一套类型安全的指令构建 DSL，支持参数解析、子指令以及特定上下文的执行逻辑。
+
+## 基础指令与参数解析
+
+你可以为指令定义类型安全的参数（支持自动类型转换），并通过 `.value` 快速获取。
+
+```kotlin
+client.command("order", prefix = "/") {
+    // 定义一个 Int 类型的参数
+    val id = parameter<Int>("id")
+    // 定义一个贪婪字符串参数，即将之后所有内容视为一个参数
+    val note = greedyStringParameter("note")
+
+    onExecute {
+        respond {
+            text("Order #${id.value} created\nnote：${note.value}")
+        }
+    }
+
+    /**
+     * **解析**失败的处理，注意这里不是异常，而是指令参数类型不匹配、过多参数、参数缺失等预期内错误
+     * 这里的 error 是一个 `Typed error`，说的简单点，密封类。你可以用 when 判断到底是什么问题，并加以处理。
+     * 默认情况下，如果不定义这个块，会忽视所有解析错误，并对指令不做回复。
+     */
+    onFailure { error ->
+        respond { /** ... */ }
+    }
+}
+```
+
+## 上下文隔离
+
+指令可以针对不同的聊天场景执行不同的逻辑：
+
+```kotlin
+client.command("info") {
+    onGroupExecute {
+        respond { text("这是群聊专用的信息！") }
+    }
+    
+    onPrivateExecute {
+        respond { text("这是私聊专用的信息！") }
+    }
+    
+    onExecute {
+        // 只有当没有定义上述两个块时，或者在其他未知上下文中，才会执行兜底逻辑
+    }
+}
+```
+
+> [!tip]
+> `onGroupExecute` 和 `onPrivateExecute` 的优先级**高于** `onExecute`。如果群聊触发了指令且你定义了 `onGroupExecute`，那么 `onExecute` 中的兜底逻辑将**不会**被执行。
+
+## 上下文交互
+
+在指令执行上下文中，你可以挂起当前协程，等待该用户的下一条回复（如实现分步对话）。
+
+```kotlin
+client.command("shutdown") {
+    onExecute {
+        respond { text("真的要关机吗？") }
+        
+        // 等待该用户在同一上下文中发送的下一条消息（默认 30 秒超时）
+        val replyEvent = awaitNextMessage(timeout = 30.seconds)
+        
+        if (replyEvent == null) {
+            respond { text("等待超时") }
+        } else {
+            respond { text("你回复了我，但这不重要，无论如何，我都不想关掉我自己！") }
+        }
+    }
+}
+```

saltify-docs/content/guide/plugin.md

@@ -0,0 +1,50 @@
+# 插件开发
+
+使用插件是 Saltify 组织代码逻辑的最佳实践。通过将相关联的事件监听和指令封装在一个插件中，可以大幅提升代码的可维护性。
+
+## 定义插件
+
+你可以预先定义一个 `SaltifyPlugin`，或者在应用配置时直接使用 `plugin {}` 块。
+
+```kotlin
+class MyPluginConfig(
+    var reply: String = "Hello!",
+    var enableFeatureX: Boolean = true
+)
+
+val myPlugin = SaltifyPlugin("my-awesome-plugin", ::MyPluginConfig) { config ->
+    // 插件加载完成后的初始化逻辑
+    // 这里的 `name` 就是 "my-awesome-plugin"
+    onStart {
+        println("[$name] 插件已启动！")
+    }
+
+    // 应用关闭时的清理逻辑
+    onStop {
+        println("[$name] 插件已停止！")
+    }
+
+    // 监听特定事件
+    on<Event.GroupMemberIncrease> { event ->
+        event.respond { text(config.reply) }
+    }
+}
+```
+
+## 安装插件
+
+```kotlin
+val client = SaltifyApplication {
+    // 安装插件
+    install(myPlugin) {
+        reply = "Hello!!"
+    }
+    
+    // 或者直接内联定义
+    plugin("another-plugin") {
+        onStart { /* ... */ }
+    }
+}
+```
+
+外部定义的插件的配置是可选的，在应用初始化块内定义的插件不可配置。

saltify-docs/content/index.md

@@ -15,5 +15,5 @@ features:
   - title: 跨平台支持
     details: 兼容 Kotlin JVM / Native / JS / WASM 平台，一套代码覆盖更多运行环境
   - title: 丰富功能
-    details: 支持 Milky 协议所有 API / 事件，支持插件化开发、命令路由、事件监听等 DSL
+    details: 支持 Milky 协议所有 API / 事件，支持插件化开发、指令路由、事件监听等 DSL
 ---