add websocket client functions

docs/components/common/global-defines.md

@@ -405,3 +405,7 @@ $socket->send('hello world', $event->getFd()); // 客户端的连接 fd 编号
 ### zm_create_plugin()
 
 创建一个炸毛单文件模式的插件对象，效果等同于 `new \ZM\Plugin\ZMPlugin()`。
+
+### zm_websocket_client()
+
+创建一个 WebSocket 客户端。详情见 [框架内置 WebSocket 客户端](/components/http/websocket-client)。

docs/components/http/websocket-client.md

@@ -1,3 +1,87 @@
 # 框架内置 WebSocket 客户端
 
-> 框架的内置 WebSocket 客户端还没有抽象完接口，文档暂时先鸽了。这部分会尽快写完的！
+> 框架内置客户端在 `3.1.8` 及以后版本可用。
+
+炸毛框架内置了 WebSocket 客户端，可以使用它发起一个 WebSocket 连接，接入其他类型的服务端。例如与另一个框架节点通信、调用第三方 WebSocket API 等。
+
+## 创建
+
+一般情况下，在 `#[Init]` 初始化的注解事件中创建 WebSocket 客户端，并通过一个单独的全局变量保存它：
+
+```php
+class Demo 
+{
+    private static ?\OneBot\Driver\Interfaces\WebSocketClientInterface $client = null;
+
+    #[Init]
+    public function onInit()
+    {
+        self::$client = zm_websocket_client('ws://192.168.1.3:20001/');
+        self::$client->setMessageCallback(function(\Choir\WebSocket\FrameInterface $frame) {
+            logger()->info('收到了服务端发来的消息：' . $frame->getData());
+        });
+        if (self::$client->connect()) {
+            logger()->info('连接成功！');
+        } elseif (!self::$client->reconnect()) {
+            logger()->warning('连接失败！');
+        }
+        self::$client->send('hello');
+    }
+}
+```
+
+::: tip 提示
+
+- 最好不要在 `#[Route]`、`#[BotEvent]` 等非可控注解中创建过多 WebSocket 客户端，避免出现资源耗尽的情况。
+- `connect()` 只能调用一次，如果第一次连接失败则必须调用 `reconnect()` 进行重连。
+
+:::
+
+创建连接时的定义如下：
+
+`zm_websocket_client(string $address, array $header = [], $set = null)`
+
+其中，`$address` 为目标的地址，`$header` 为附带的请求头。`$set` 参数一般无需设置，只有在使用 Swoole 驱动且需要配置的时候传入。
+
+## 设置回调
+
+如果要接收服务端发来的消息，你可以通过 `setMessageCallback()` 设置回调：
+
+```php
+// 直接打印收到的消息
+$client->setMessageCallback(function(\Choir\WebSocket\FrameInterface $frame) {
+    dump($frame->getData());
+});
+
+// 做个复读机，收到后立刻发回原消息
+$client->setMessageCallback(function(\Choir\WebSocket\FrameInterface $frame, $client) {
+    dump($frame->getData());
+    $client->send($frame);
+});
+```
+
+如果要在服务端主动断开连接时触发事件，可以通过 `setCloseCallback()` 设置回调：
+
+```php
+$client->setCloseCallback(function(\Choir\WebSocket\CloseFrameInterface $frame) {
+    logger()->info('连接断开！');
+});
+```
+
+## 发送消息帧
+
+连接成功后，你可以通过调用 `send()` 来发送消息帧。这个方法支持消息帧对象（`\Choir\WebSocket\FrameInterface`）和字符串。
+在使用字符串发送时，底层会自动打包为 UTF-8 格式的消息帧发送。
+
+```php
+$result = $client->send('hello');
+$result = $client->send(\Choir\WebSocket\FrameFactory::createTextFrame('hello using frame'));
+```
+
+## 检查连接状态
+
+你可以使用 `isConnected()` 来检查连接状态：
+
+```php
+dump($client->isConnected());
+```