Adds Webhook doc

docs/demos/demos.md

@@ -19,6 +19,16 @@ title: 示例项目
 该示例项目演示了如何通过订阅到 Kook.Net 中的多个事件，来完成不同的操作。
 当用户在指定的消息上添加或撤销回应时，Bot 会为该用户添加或撤销服务器的角色。
 
+## Webhook
+
+### [Kook.Net.Samples.Webhook.AspNet](https://github.com/gehongyan/Kook.Net/tree/master/samples/Kook.Net.Samples.Webhook.AspNet)
+
+该示例项目演示了如何使用 ASP.NET Core 来创建一个 Webhook 服务，以接收来自 Kook.Net 的事件。
+
+### [Kook.Net.Samples.Webhook.HttpListener](https://github.com/gehongyan/Kook.Net/tree/master/samples/Kook.Net.Samples.Webhook.HttpListener)
+
+该示例项目演示了如何使用 HttpListener 来创建一个 Webhook 服务，以接收来自 Kook.Net 的事件。
+
 ## 文本命令框架
 
 ### [Kook.Net.Samples.TextCommands](https://github.com/gehongyan/Kook.Net/tree/master/samples/Kook.Net.Samples.TextCommands)

docs/quick_reference/http_api/asset.md

@@ -19,13 +19,13 @@ POST `/api/v3/asset/create`
 ```csharp
 Stream stream = null; // 文件流
 string path = null; // 文件路径
-string fileName = null; // 文件名
+string filename = null; // 文件名
 
 // API 请求
-string assertUri = await _socketClient.Rest.CreateAssetAsync(stream, fileName);
-string assertUri = await _socketClient.Rest.CreateAssetAsync(path, fileName);
-string assertUri = await _restClient.CreateAssetAsync(stream, fileName);
-string assertUri = await _restClient.CreateAssetAsync(path, fileName);
+string assertUri = await _socketClient.Rest.CreateAssetAsync(stream, filename);
+string assertUri = await _socketClient.Rest.CreateAssetAsync(path, filename);
+string assertUri = await _restClient.CreateAssetAsync(stream, filename);
+string assertUri = await _restClient.CreateAssetAsync(path, filename);
 ```
 
 

docs/quick_reference/index.md

@@ -9,7 +9,10 @@ title: 快速参考指南
 
 [KOOK 开发者平台]: https://developer.kookapp.cn/
 
-- @Guides.QuickReference.Startup
+- 登录与启动
+  - @Guides.QuickReference.Startup.Rest
+  - @Guides.QuickReference.Startup.WebSocket
+  - @Guides.QuickReference.Startup.Webhook
 - HTTP 接口
   - @Guides.QuickReference.Http.Guild
   - @Guides.QuickReference.Http.Channel

docs/quick_reference/startup/rest.md

@@ -0,0 +1,40 @@
+---
+uid: Guides.QuickReference.Startup.Rest
+title: Rest 客户端
+---
+
+# Rest 客户端
+
+预声明变量
+
+```csharp
+readonly KookRestClient _restClient;
+```
+
+```csharp
+// 使用默认配置创建 Rest 客户端
+_restClient = new KookRestClient();
+// 使用自定义配置创建 Rest 客户端
+_restClient = new KookRestClient(new KookRestConfig()
+{
+    // 请求头 Accept-Language
+    AcceptLanguage = "zh-CN",
+    // 默认重试模式
+    DefaultRetryMode = RetryMode.AlwaysRetry,
+    // 默认超速回调
+    DefaultRatelimitCallback = info => Task.CompletedTask,
+    // 日志级别
+    LogLevel = LogSeverity.Info,
+    // 双向文稿格式化用户名
+    FormatUsersInBidirectionalUnicode = true,
+    // Rest 客户端提供程序
+    RestClientProvider = DefaultRestClientProvider.Instance
+});
+
+// Token
+string token = null;
+// 登录
+await _restClient.LoginAsync(TokenType.Bot, token);
+// 登出
+await _restClient.LogoutAsync();
+```

docs/quick_reference/startup/webhook.md

@@ -0,0 +1,101 @@
+---
+uid: Guides.QuickReference.Startup.Webhook
+title: Webhook 客户端
+---
+
+# Webhook 客户端
+
+Webhook 客户端的抽象类是 `KookWebhookClient`。
+
+## ASP.NET 实现
+
+```csharp
+// 创建服务主机构建器
+WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
+
+// 添加 KookAspNetWebhookClient 服务并进行必要的配置
+builder.Services.AddKookAspNetWebhookClient(config =>
+{
+    // 包含 KookRestConfig 及 KookSocketConfig 的全部配置项，此处略
+
+    // 由 KookWebhookConfig 提供的配置项
+    // Webhook 负载验证令牌
+    config.VerifyToken = default;
+    // Webhook 负载解密密钥
+    config.EncryptKey = default;
+    // 启动时是否等待 Webhook 验证挑战后再开始启动 Bot 服务
+    config.StartupWaitForChallenge = false;
+    // Webhook 提供程序，此处为由 KookAspNetWebhookConfig 设置的默认值
+    config.WebhookProvider = DefaultAspNetWebhookProvider.Instance;
+
+    // 由 KookAspNetWebhookConfig 提供的配置项
+    // 令牌类型
+    config.TokenType = TokenType.Bot;
+    // 令牌
+    config.Token = default;
+    // 是否验证令牌格式
+    config.ValidateToken = true;
+    // 请求的路由终结点
+    config.RouteEndpoint = "kook";
+    // 配置 KookAspNetWebhookClient
+    config.ConfigureKookClient = (serviceProvider, client) => { };
+});
+
+// 构建服务主机
+WebApplication app = builder.Build();
+
+// 配置 Webhook 终结点
+app.UseKookEndpoint();
+
+// 启动服务主机
+await app.RunAsync();
+```
+
+## HTTP Listener 实现
+
+```csharp
+
+// 使用默认配置创建 WebSocket 客户端
+KookHttpListenerWebhookClient webhookClient = new KookHttpListenerWebhookClient();
+// 使用自定义配置创建 WebSocket 客户端
+KookHttpListenerWebhookClient webhookClient = new KookHttpListenerWebhookClient(new KookHttpListenerWebhookConfig
+{
+    // 包含 KookRestConfig 及 KookSocketConfig 的全部配置项，此处略
+
+    // 由 KookWebhookConfig 提供的配置项
+    // Webhook 负载验证令牌
+    VerifyToken = default,
+    // Webhook 负载解密密钥
+    EncryptKey = default,
+    // 启动时是否等待 Webhook 验证挑战后再开始启动 Bot 服务
+    StartupWaitForChallenge = false,
+    // Webhook 提供程序，此处为由 KookAspNetWebhookConfig 设置的默认值
+    WebhookProvider = DefaultAspNetWebhookProvider.Instance,
+
+    // 由 KookHttpListenerWebhookConfig 提供的配置项
+    // 用于 HttpListener 的 URI 前缀列表
+    UriPrefixes =
+    [
+        "http://localhost:5043/",
+        "http://127.0.0.1:5043/"
+    ],
+    // HttpListener 崩溃后自动重启的时间间隔
+    // Timeout.InfiniteTimeSpan 表示终止服务但不终止进程
+    // 其它小于 0 的时间间隔表示不自动重启并终止进程
+    // TimeSpan.Zero 表示立即重启 HttpListener
+    // 其它大于 0 的时间间隔表示等待指定的时间间隔后重启 HttpListener
+    AutoRestartInterval = TimeSpan.FromSeconds(5),
+
+});
+
+// Token
+string token = null;
+// 登录
+await webhookClient.LoginAsync(TokenType.Bot, token);
+// 启动
+await webhookClient.StartAsync();
+// 停止
+await webhookClient.StopAsync();
+// 登出
+await webhookClient.LogoutAsync();
+```

docs/quick_reference/startup/websocket.md

@@ -0,0 +1,64 @@
+---
+uid: Guides.QuickReference.Startup.WebSocket
+title: WebSocket 客户端
+---
+
+# WebSocket 客户端
+
+预声明变量
+
+```csharp
+readonly KookSocketClient _socketClient;
+```
+
+```csharp
+// 使用默认配置创建 WebSocket 客户端
+_socketClient = new KookRestClient();
+// 使用自定义配置创建 WebSocket 客户端
+_socketClient = new KookSocketClient(new KookSocketConfig()
+{
+    // 包含 KookRestConfig 的全部配置项，此处略
+
+    // 显示指定网关地址
+    GatewayHost = null,
+    // 连接超时（毫秒）
+    ConnectionTimeout = 6000,
+    // 小型 Bot 服务器数量阈值
+    SmallNumberOfGuildsThreshold = 5,
+    // 大型 Bot 服务器数量阈值
+    LargeNumberOfGuildsThreshold = 50,
+    // 处理程序警告耗时阈值（毫秒）
+    HandlerTimeout = 3000,
+    // 消息缓存数量
+    MessageCacheSize = 10,
+    // WebSocket 客户端提供程序
+    WebSocketProvider = DefaultWebSocketProvider.Instance,
+    // UDP 客户端提供程序
+    UdpSocketProvider = DefaultUdpSocketProvider.Instance,
+    // 启动缓存数据获取模式
+    StartupCacheFetchMode = StartupCacheFetchMode.Auto,
+    // 自动下载服务器用户信息
+    AlwaysDownloadUsers = false,
+    // 自动下载服务器用户语音状态信息
+    AlwaysDownloadVoiceStates = false,
+    // 自动下载服务器助力信息
+    AlwaysDownloadBoostSubscriptions = false,
+    // 等待服务器可用状态超时（毫秒）
+    MaxWaitBetweenGuildAvailablesBeforeReady = 10000,
+    // 最大获取新加入服务器信息重试次数
+    MaxJoinedGuildDataFetchingRetryTimes = 10,
+    // 获取新加入服务器信息重试延迟（毫秒）
+    JoinedGuildDataFetchingRetryDelay = 500
+});
+
+// Token
+string token = null;
+// 登录
+await _socketClient.LoginAsync(TokenType.Bot, token);
+// 启动
+await _socketClient.StartAsync();
+// 停止
+await _socketClient.StopAsync();
+// 登出
+await _socketClient.LogoutAsync();
+```

docs/quick_reference/toc.yml

@@ -1,7 +1,13 @@
 - name: 快速参考指南
   topicUid: Guides.QuickReference
 - name: 登录与启动
-  topicUid: Guides.QuickReference.Startup
+  items:
+    - name: Rest 客户端
+      topicUid: Guides.QuickReference.Startup.Rest
+    - name: WebSocket 客户端
+      topicUid: Guides.QuickReference.Startup.WebSocket
+    - name: Webhook 服务端
+      topicUid: Guides.QuickReference.Startup.Webhook
 - name: HTTP 接口
   items:
     - name: 服务器相关接口