feat: Introduce routing system documentation

This commit adds a new documentation page for the routing system,
detailing routing forms, multiple endpoints, `IntoResponse` trait, and
extractors.

It also updates existing development documentation to reflect changes in
`sithra-kit` APIs, including `plugin!`, `matchopt!`, and `msg!` macros,
and clarifies `Initialize` struct and error handling during
initialization.

Author: BERADQ

content/docs/development/index.mdx

@@ -164,19 +164,19 @@ anyhow = "1.0"
 
 ```rust title="src/main.rs"
 use sithra_kit::{
-    plugin::Plugin,
+    matchopt, plugin,
     server::extract::payload::Payload,
     types::{
         message::{Message, SendMessage, common::CommonSegment as H},
-        smsg,
+        msg,
     },
 };
 
 /// 插件入口点
 #[tokio::main]
 async fn main() {
     // 1. 初始化插件
-    let (plugin, _) = Plugin::new::<()>().await.unwrap();
+    let (plugin, _) = plugin!();
 
     // 2. 注册消息处理路由
     let plugin = plugin.map(|r| r.route_typed(Message::on(echo)));
@@ -196,7 +196,7 @@ async fn main() {
 /// 当收到以 "echo " 开头的消息时，返回去掉 "echo " 前缀的内容
 async fn echo(Payload(msg): Payload<Message<H>>) -> Option<SendMessage> {
     // 1. 消息是否为文本开头，如果是则获取文本，否则返回 None
-    let text = msg.content.first()?.text_opt()?;
+    let text = matchopt!(msg.content.first()?, H::Text(t) => t)?;
 
     // 2. 检查消息是否以 "echo " 开头，如果不是则返回 None
     let text = text.strip_prefix("echo ")?.to_owned();
@@ -214,7 +214,7 @@ async fn echo(Payload(msg): Payload<Message<H>>) -> Option<SendMessage> {
     }
 
     // 6. 返回要发送的消息
-    Some(smsg!(content))
+    Some(msg!(content))
 }
 ```
 
@@ -310,7 +310,7 @@ cd my-custom-plugin
 [package]
 name = "my-custom-plugin"
 version = "0.1.0"
-edition = "2021"
+edition.workspace = true
 
 [dependencies]
 sithra-kit.workspace = true
@@ -392,7 +392,7 @@ just run
 </Cards>
 
 <Callout type="info" icon={<Terminal />}>
-  在开发模式下，可以使用 <code>RUST_LOG=debug just run</code> 命令启动
+  在开发模式下，可以使用 <code>SITHRA_LOG=debug just run</code> 命令启动
   sithra-rs，以显示更详细的调试信息。
 </Callout>
 

content/docs/development/initialize.mdx

@@ -55,10 +55,10 @@ async fn main() {
 初始化结果封装在 `Initialize` 结构体中，它的定义如下：
 
 ```rust
-pub struct Initialize<C> {
+pub struct Initialize<C = ()> {
     pub config:    C,
-    pub data_path: String,
     pub id:        String,
+    pub data_path: String,
 }
 ```
 
@@ -67,8 +67,8 @@ pub struct Initialize<C> {
 这个结构体包含了两个重要字段：
 
 - `config` 字段表示插件的配置信息，可以为任何可反序列化类型
-- `data_path` 字段表示插件的数据路径，我们约定插件的所有数据都存储在该路径下
 - `id` 字段表示插件的唯一标识符，用于在框架中区分不同的插件实例。
+- `data_path` 字段表示插件的数据路径，我们约定插件的所有数据都存储在该路径下
 
 </Callout>
 
@@ -77,6 +77,7 @@ pub struct Initialize<C> {
 通过为 `plugin!` 宏指定泛型参数，我们可以定义插件专属的配置类型：
 
 ```rust
+#[derive(Debug, Clone, Deserialize)]
 struct Config {
   admins: Vec<String>,
 }
@@ -112,6 +113,30 @@ tokio::select! {
 }
 ```
 
+### 错误处理
+
+在初始化过程中，插件应捕获并处理所有错误。`plugin` 提供了以下方法来响应初始化状态：
+
+- `plugin.err(error)`: 响应错误并终止初始化过程（返回 `never`）。
+- `plugin.ok()`: 响应初始化完成消息并允许插件继续执行。
+- `plugin.expect(result)`: 这是一个特殊方法。如果 `result` 是 `Err(error)`，其行为与调用 `plugin.err(error)` 一致，终止初始化。如果 `result` 是 `Ok(value)`，则返回 `value` 并继续初始化。
+
+签名:
+```rust
+type Self = Plugin;
+
+/// Send an initialization response indicating failure.
+async fn err(&mut self, err: impl Into<PluginInitError>) -> !;
+/// Send an initialization response indicating success.
+fn ok(&mut self);
+/// Tool used to handle errors and continue initialization.
+async fn expect<T, E: Display>(&mut self, r: Result<T, E>) -> T;
+```
+
+**隐式行为：**
+
+如果在调用 `plugin.run()` 之前没有显式地通过 `plugin.ok()` 或 `plugin.err()` 确认初始化状态，框架将自动调用 `plugin.ok()` 来确认初始化完成。一旦 `plugin.ok()` 被调用，框架将停止等待初始化消息，并将插件视为已成功启动，不再捕获初始化错误信息。因此，除非有特殊需求，否则不建议手动调用 `plugin.ok()` 来完成初始化。
+
 <Callout type="warn" icon={<Terminal />}>
 
 当插件退出时，框架内部会直接丢弃插件实例，析构时插件会被 kill。
@@ -151,9 +176,12 @@ tokio::select! {
 
 ```rust
 pub struct Plugin {
-    peer:   Peer,
-    server: Server,
-    router: Router,
+    peer:            Peer,
+    pub server:      Server,
+    router:          Router,
+    name:            String,
+    version:         String,
+    initialize_done: bool,
 }
 ```
 
@@ -174,22 +202,19 @@ pub struct Plugin {
 让我们拆解 `Plugin::new` 方法，了解其内部实现：
 
 ```rust
-pub async fn new<Config>(version: &str, name: &str) -> (Self, Initialize<Config>)
+pub async fn new<Config, F>(version: &str, name: &str, init_fn: F) -> (Self, Initialize<Config>)
 where
     Config: for<'de> Deserialize<'de>,
+    F: FnOnce(&mut Initialize<Config>) -> InitializeResult,
 {
-    // 处理命令行选项，如 --version
     if handle_options(version, name) {
         process::exit(0);
     }
-    // 创建对等节点、服务端和路由表
     let peer = Peer::new();
     let server = Server::new();
     let router = Router::new();
-    // 从对等节点创建帧序列
     let mut framed = crate::transport::util::framed(peer);
 
-    // 执行初始化循环，等待框架发送初始化消息
     let init = loop {
         let Some(msg) = <FramedPeer as StreamExt>::next(&mut framed).await else {
             break Err(PluginInitError::ConnectionClosed);
@@ -203,47 +228,46 @@ where
         }
     };
 
-    // 处理初始化结果
-    let init = match init {
+    let mut init = match init {
         Ok(init) => init,
         Err(err) => {
-            // 发送错误信息给框架
             framed
                 .send(
                     DataPack::builder()
                         .path(Initialize::<Config>::path())
-                        .build_with_payload(InitializeResult::Err(err)),
+                        .build_with_payload(&InitializeResult::Err(err)),
                 )
-                .await.ok();
-            // 等待退出信号
+                .await
+                .ok();
             tokio::signal::ctrl_c().await.ok();
-            // 退出进程
             process::exit(1);
         }
     };
 
-    // 初始化日志系统
     init_log(server.client().sink());
 
-    // 发送初始化成功响应给框架
-    server
-        .client()
-        .send(
-            RequestDataPack::default()
-                .path(Initialize::<Config>::path())
-                .payload(InitializeResult::Ok(())),
-        )
-        .unwrap_or_else(|_| panic!("Failed to send initialization response: [{name}]"));
+    if let Err(err) = init_fn(&mut init) {
+        framed
+            .send(
+                DataPack::builder()
+                    .path(Initialize::<Config>::path())
+                    .build_with_payload(&InitializeResult::Err(err)),
+            )
+            .await
+            .ok();
+        tokio::signal::ctrl_c().await.ok();
+        process::exit(1);
+    }
 
-    // 用不到帧序列了，我们换回对等节点
     let peer = framed.into_inner();
-    
-    // 返回实例
     (
         Self {
             peer,
             server,
             router,
+            name: name.to_owned(),
+            version: version.to_owned(),
+            initialize_done: false,
         },
         init,
     )
@@ -259,7 +283,7 @@ where
 3. 等待并解析框架的初始化消息
 4. 如果初始化失败，向框架报告错误并退出
 5. 初始化日志系统
-6. 向框架发送初始化成功响应
+6. 执行用户提供的初始化函数
 7. 返回插件实例和初始化结果
 
 </Callout>
@@ -269,11 +293,16 @@ where
 `Plugin::run` 方法的实现相对简洁：
 
 ```rust
-pub fn run(self) -> JoinSet<Result<(), ServerError>> {
+pub fn run(mut self) -> JoinSet<Result<(), ServerError>> {
+    // 如果初始化未完成，则隐式发送成功响应
+    if !self.initialize_done {
+        self.ok();
+    }
     let Self {
         peer,
         server,
         router,
+        ..
     } = self;
     // 分割对等节点为写入和读取部分
     let (write, read) = peer.split();
@@ -345,16 +374,8 @@ pub fn run(self) -> JoinSet<Result<(), ServerError>> {
 
     // 初始化日志
     init_log(server.client().sink());
-    
-    // 发送初始化成功响应
-    server
-        .client()
-        .send(
-            RequestDataPack::default()
-                .path(Initialize::<Config>::path())
-                .payload(InitializeResult::Ok(())),
-        )
-        .unwrap_or_else(|_| panic!("Failed to send initialization response: [{NAME}]"));
+
+
 
     // 用不到帧序列了，我们换回对等节点
     let peer = framed.into_inner();
@@ -413,7 +434,13 @@ pub fn run(self) -> JoinSet<Result<(), ServerError>> {
 
     // 初始化日志
     init_log(server.client().sink());
-    
+
+    // 这里是自定义初始化逻辑的地方，对应 `plugin!` 宏的第二个参数
+    // 例如:
+    // if let Err(e) = some_init_task(&init.config).await {
+    //     // report error and exit
+    // }
+
     // 发送初始化成功响应
     server
         .client()
@@ -458,4 +485,4 @@ pub fn run(self) -> JoinSet<Result<(), ServerError>> {
 恭喜您已经深入了解了 sithra-rs 插件的初始化流程！接下来，您可以：
 
 - 了解如何[注册和处理路由](/docs/development/router)
-- 探索[内部服务](/docs/development/server)的实现和使用
+- 探索[内部服务](/docs/development/server)的实现和使用

content/docs/development/meta.json

@@ -8,6 +8,7 @@
         "index",
         "standards",
         "---逐步深入---",
-        "initialize"
+        "initialize",
+        "route"
     ]
 }