Table of Contents

使用 Kook.Net 构建你的第一个 Bot

本指南将引导您使用 Kook.Net 构建一个简单的 Bot。在此之前，请先确保您已参与 KOOK 开发者，并获得开发权限。

创建一个 KOOK 应用

在开始编写代码前，您需要通过 KOOK 开发者中心创建一个 Bot。

  1. 访问并登录到 KOOK 开发者中心；

  2. 点击 新建应用；

  3. 填写应用名称；

  4. 点击刚刚创建好的应用；

  5. 点击左侧的 机器人；

    img.png

  6. 确保机器人的连接模式为 WebSocket；

    img.png

  7. (可选) 如果要创建公共 Bot，开启 开启公共机器人 开关。

    img.png

将 Bot 添加到服务器

Bot 无法通过访问服务器的邀请链接进入频道，因此需要 Bot 的邀请链接将 Bot 添加到服务器。

  1. 在 KOOK 开发者中心 中访问要添加到服务器的 Bot 应用；

  2. 点击左侧的 邀请链接；

    img.png

  3. 在右侧的 角色权限设置 中勾选要在 Bot 进入服务器后直接拥有的权限；

    Note

    这将会在服务器内创建一个仅可授予给该 Bot 的托管角色，该 Bot 将会在进入服务器后自动获得该角色。 如需在进入服务器后变更权限，可通过 服务器设置 中的 角色权限 进行修改。

  4. 打开上方生成的邀请链接；

  5. 选择要将 Bot 添加到的服务器；

  6. 点击邀请。

    img.png

    Note

    列表中仅显示您拥有 管理服务器 权限的服务器。

将 Bot 连接至 KOOK

如果您已创建工程，并安装了 Kook.Net，可参考以下步骤， 否则，请参考 安装 Kook.Net 。

异步启动

Kook.Net 广泛采用 .NET 的 异步编程模型，绝大多数操作都是以异步方式完成， 请尽可能地在异步上下文中等待这些操作。

C# 9.0 引入了顶级语句，可以在不显式创建 Program 类和 Main 方法的情况下编写代码， 顶级语句中使用 await 来调用异步方法，会自动建立一个在异步上下文中启动的程序。

Warning

应用程序中异步上下文抛出的任何异常都会被持续向上层抛出直到首个同步方法， 抛出至顶级语句的所有未经处理的异常将导致程序退出。

Kook.Net 会捕获事件处理函数中发生的异常，以避免该异常导致程序退出， 但需要注意的是，如果异常发生在 async void 所标记的方法中， 尽管异常发生在异步上下文中，但该异常仍会导致程序退出。 因此，请合理使用 async Task 与 await 的组合。

创建日志方法

在创建并配置 KOOK Bot 客户端程序前，我们需要创建一个事件处理程序来订阅 Kook.Net 的日志事件。

为了尽可能地广泛支持各种日志提供程序，Kook.Net 通过 Log 事件来记录日志信息， 其事件参数为 LogMessage。有关该事件地详细信息，可参考 API 文档。

如需要使用自己的日志记录框架，请在此该事件行调用。此处，为了简单起见，我们仅将日志记录到控制台中。

// Log 事件，此处以直接输出到控制台为例
Task LogAsync(LogMessage log)
{
    Console.WriteLine(log.ToString());
    return Task.CompletedTask;
}

创建 KOOK Bot 客户端程序

为了编写一个能与 KOOK 服务端实时互动的 Bot，请使用 KookSocketClient 作为客户端， 使用 Socket 实体，如您不了解 Kook.Net 的多种实现，请参考 术语 。 在异步入口点中创建一个 KookSocketClient 的实例，用于与 KOOK 服务端建立连接， 如有需要，也可向构造函数中传递一个 KookSocketConfig 的可选参数， 多数情况下，默认值即可。

在连接前，将刚刚创建的日志事件处理程序订阅到客户端的 Log 事件中。 Kook.Net 中的事件与 C# 中的任何其他事件的工作机制类似。

使用 LoginAsync 方法登录到 KOOK 服务端，登录过程采用的身份认证信息为机器人的 Token。

img.png

通过调用客户端的 StartAsync 方法，客户端启动与服务端的连接/重连机制， 该方法会在连接/重连机制启动后立刻返回，因此，任何依赖于客户端状态的方法 都应以事件处理程序的形式执行。

为了阻止程序在运行期间的异步入口点返回，请在 MainAsync 方法退出前等待一个无限时长的延迟， 获取其它可以阻止程序继续运行的方法，例如，等待控制台中输入信息。

Important

Token 可允许您获得对 Bot 的所有访问权限，因此，不要与任何无关人员共享 Token！ 如您要公开 Bot 的源代码，请将该 Token 存储在外部源中。

在下面的示例中，我们从预定义的变量中获取变量，这是极其不安全的， 尤其是在有计划将应用程序以任何形式发布的情况下。

为了能够安全地处理该机密信息，建议以 环境变量、配置文件、机密管理 等形式存储 Token。

using KookSocketClient client = new();
client.Log += LogAsync;

//  将 Token 写入字符串变量，用于 Bot 登录过程的身份认证
//  这很不安全，尤其是在有公开源代码的情况下，不应该这么做
string token = "token";

// 一些其它存储 Token 的方案，如环境变量、文件等
// string token = Environment.GetEnvironmentVariable("NameOfYourEnvironmentVariable");
// string token = File.ReadAllText("token.txt");
// string token = JsonConvert.DeserializeObject<AConfigurationClass>(File.ReadAllText("config.json")).Token;

await client.LoginAsync(TokenType.Bot, token);
await client.StartAsync();

// 阻塞程序直到关闭
await Task.Delay(Timeout.Infinite);

到这里，客户端应该可以连接到 KOOK 服务端，运行程序，等待片刻，应该可以在 KOOK 客户端中看到 Bot 上线。

Edit this page