Lagrange

https://lagrangedev.github.io/Lagrange.Doc/v1/
Admin
Lagrange is an open-source NTQQ protocol implementation and bot framework that enables developers to...
Tokens:12,595
Snippets:149
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### 创建 qqclient 实例

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Login

初始化一个空的客户端实例。

```go
// 创建一个空的client
qqclient := client.NewClientEmpty()
```

--------------------------------

### 获取二维码

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/Login/LoginByScanQrCode

使用 FetchQrCode 异步方法获取包含二维码链接和图片数据的元组。

```csharp
var qrCode = await bot.FetchQrCode();
```

--------------------------------

### appsettings.json 完整配置示例

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/Config

Lagrange.OneBot 的核心配置文件，包含日志、签名服务器、账号及服务实现设置。复制到实际文件时请务必删除所有 // 开头的注释。

```json5
{
  "$schema": "https://raw.githubusercontent.com/LagrangeDev/Lagrange.Core/master/Lagrange.OneBot/Resources/appsettings_schema.json",
  "Logging": {
    "LogLevel": {
      "Default": "Information",  // 提 Issue 时请切换到 Trace
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
    },
  },
  "SignServerUrl": "https://sign.lagrangecore.org/api/sign",
  "SignProxyUrl": "", //留空不使用代理,仅支持http代理, example: http://127.0.0.1:7890
  "MusicSignServerUrl": "",
  "Account": {
    "Uin": 0,  // 用于识别 db 和 qrcode 文件, 无任何其他用途
    "Password": "",  // 不再支持
    "Protocol": "Linux",  // 使用 Linux 协议
    "AutoReconnect": true,
    "GetOptimumServer": true,
  },
  "Message": {
    "IgnoreSelf": true,  // 忽略 Bot 自身的消息
    "StringPost": false,
  },
  "QrCode": {
    "ConsoleCompatibilityMode": false,
  },
  "Implementations": [  // 服务实现 支持多链接
    {
      "Type": "ReverseWebSocket",
      "Host": "127.0.0.1",
      "Port": 8080,
      "Suffix": "/onebot/v11/ws",
      "ReconnectInterval": 5000,
      "HeartBeatInterval": 5000,
      "HeartBeatEnable": true,
      "AccessToken": "",
    },
    {
      "Type": "ForwardWebSocket",
      "Host": "127.0.0.1",
      "Port": 8081,
      "HeartBeatInterval": 5000,
      "HeartBeatEnable": true,
      "AccessToken": "",
    },
  ],
}
```

--------------------------------

### 等待扫码登录

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/Login/LoginByScanQrCode

调用 LoginByQrCode 异步方法等待用户完成扫码操作。

```csharp
await bot.LoginByQrCode();
```

--------------------------------

### 执行二维码登录

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Login

在扫码完成后执行登录操作。

```go
// 等待扫码完成后即可登录
_, err := qqclient.QRCodeLogin()
```

--------------------------------

### 轮询二维码状态

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Login

检查二维码的扫码状态以确定是否可以继续登录。

```go
retCode, err := c.GetQRCodeResult()
if retCode.Waitable() {
    // 二维码在等待扫码或等待确认
}
if retCode.Success() {
    // 二维码扫码成功
}
```

--------------------------------

### LoginByQrCode()

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/Login/LoginByScanQrCode

等待用户完成扫码登录的异步方法。

```APIDOC
## LoginByQrCode()

### Description
等待用户扫描二维码并完成登录流程。该方法会阻塞直到扫码完毕。

### Method
Async Method

### Example
```csharp
await bot.LoginByQrCode();
```
```

--------------------------------

### FetchQrCode()

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/Login/LoginByScanQrCode

获取登录二维码数据，返回包含二维码链接和图片字节数组的元组。

```APIDOC
## FetchQrCode()

### Description
异步获取登录二维码。返回一个包含二维码内容链接和 PNG 格式字节数组的元组。

### Method
Async Method

### Returns
- **Url** (string) - 二维码内容链接
- **QrCode** (byte[]) - 二维码 PNG 字节数组

### Example
```csharp
var qrCode = await bot.FetchQrCode();
```
```

--------------------------------

### 创建设备信息

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Login

通过手动定义、自动生成或从文件加载来创建 DeviceInfo 实例。

```go
// 手动定义各个字段
deviceInfo := &auth.DeviceInfo{
    GUID:          "cfac208495d565ef66e7dff9f98764da",
    DeviceName:    "Lagrange-DCFCD07E",
    SystemKernel:  "Windows 10.0.22631",
    KernelVersion: "10.0.22631",
}
```

```go
// 自动生成
deviceInfo := auth.NewDeviceInfo(114514)
```

```go
// 从文件读取
deviceInfo,err := auth.LoadOrSaveDevice("path/to/deviceinfo.json")
```

--------------------------------

### 创建 Bot 实例

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/CreateBot

使用 BotFactory 创建 BotContext 实例，需要提供 BotConfig、DeviceInfo 和 KeyStore 参数。

```csharp
var bot = BotFactory.Create(new BotConfig(), _deviceInfo, _keyStore);
```

--------------------------------

### Handle group message events

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Event

Demonstrates how to subscribe to group message events and access event parameters.

```go
qqclient.GroupMessageEvent.Subscribe(func(client *client.QQClient, event *message.GroupMessage) {
	// 你可以从event中获取事件的各个参数
	
	// 这段代码会将群聊收到的消息打印出来
    fmt.Println(event.ToString())
})
```

--------------------------------

### 加入提及 (at)

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/MessageBuilder

向消息中添加提及目标用户的标记。

```csharp
.Mention(_target);
```

--------------------------------

### 加入图片消息

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/MessageBuilder

支持通过文件路径或二进制数据添加图片。

```csharp
.Image(_filePath);
```

```csharp
.Image(_file);
```

--------------------------------

### 配置日志记录器与颜色格式化

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Example

定义 ANSI 颜色常量并初始化 logrus 日志记录器，同时实现 ColoredFormatter 以支持带颜色的日志输出。

```go
const (
	// 定义颜色代码
	colorReset  = "\x1b[0m"
	colorRed    = "\x1b[31m"
	colorYellow = "\x1b[33m"
	colorGreen  = "\x1b[32m"
	colorBlue   = "\x1b[34m"
	colorWhite  = "\x1b[37m"
)

var logger = logrus.New()

func init() {
	logger.SetLevel(logrus.TraceLevel)
	logger.SetFormatter(&ColoredFormatter{})
	logger.SetOutput(colorable.NewColorableStdout())
}

type ColoredFormatter struct{}

func (f *ColoredFormatter) Format(entry *logrus.Entry) ([]byte, error) {
	// 获取当前时间戳
	timestamp := time.Now().Format("2006-01-02 15:04:05")

	// 根据日志级别设置相应的颜色
	var levelColor string
	switch entry.Level {
	case logrus.DebugLevel:
		levelColor = colorBlue
	case logrus.InfoLevel:
		levelColor = colorGreen
	case logrus.WarnLevel:
		levelColor = colorYellow
	case logrus.ErrorLevel, logrus.FatalLevel, logrus.PanicLevel:
		levelColor = colorRed
	default:
		levelColor = colorWhite
	}

	return utils.S2B(fmt.Sprintf("[%s] [%s%s%s]: %s\n",
		timestamp, levelColor, strings.ToUpper(entry.Level.String()), colorReset, entry.Message)), nil
}
```

--------------------------------

### 创建版本信息

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Login

使用内置的版本信息列表获取 AppInfo 实例。

```go
// 使用内置的版本信息
appInfo := auth.AppList["linux"]["3.2.15-30366"]
```

--------------------------------

### 加入文件

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/MessageBuilder

支持通过文件路径或二进制数据及文件名添加文件。

```csharp
.File(_filePath);
```

```csharp
.File(_file,_fileName);
```

--------------------------------

### 执行密码登录

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Login

使用密码进行登录，注意该功能不保证可用性。

```go
err = qqclient.PasswordLogin()
```

--------------------------------

### 加载配置信息

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Login

将生成的设备和版本信息应用到客户端实例中。

```go
// 设备信息
qqclient.UseDevice(deviceInfo)
// 版本信息
qqclient.UseVersion(appInfo)
```

--------------------------------

### 实现协议日志记录器方法

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Example

定义了 Warning、Debug、Error 和 Dump 方法，用于处理不同级别的日志记录及错误数据转储。

```go
func (p protocolLogger) Warning(format string, arg ...any) {
	logger.Warnf(fromProtocol+format, arg...)
}

func (p protocolLogger) Debug(format string, arg ...any) {
	logger.Debugf(fromProtocol+format, arg...)
}

func (p protocolLogger) Error(format string, arg ...any) {
	logger.Errorf(fromProtocol+format, arg...)
}

func (p protocolLogger) Dump(data []byte, format string, arg ...any) {
	message := fmt.Sprintf(format, arg...)
	if _, err := os.Stat(dumpspath); err != nil {
		err = os.MkdirAll(dumpspath, 0o755)
		if err != nil {
			logger.Errorf("出现错误 %v. 详细信息转储失败", message)
			return
		}
	}
	dumpFile := path.Join(dumpspath, fmt.Sprintf("%v.dump", time.Now().Unix()))
	logger.Errorf("出现错误 %v. 详细信息已转储至文件 %v 请连同日志提交给开发者处理", message, dumpFile)
	_ = os.WriteFile(dumpFile, data, 0o644)
}
```

--------------------------------

### 添加签名服务器

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Login

配置用于签名请求的服务器 URL。

```go
qqclient.AddSignServer("https://sign.lagrangecore.org/api/sign/30366")
```

--------------------------------

### Update Keystore in C#

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/Login/Extern

Use this method after a successful login to retrieve and save the updated KeyStore for future sessions.

```csharp
_keyStore = bot.UpdateKeystore();
```

--------------------------------

### 获取登录二维码

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Login

获取二维码数据并保存到本地。

```go
qrcode, url, err = qqclient.FecthQRCode()
// 你可以将二维码保存到本地以便扫码
os.WriteFile("path/to/qrcode.png", qrcode, 0666)
```

--------------------------------

### 加入文本消息

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/MessageBuilder

向消息链中添加文本内容。

```csharp
.Text(_text);
```

--------------------------------

### 手动创建设备信息

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/CreateBot

通过实例化 BotDeviceInfo 类来手动配置设备标识、MAC 地址及系统内核信息。

```csharp
private BotDeviceInfo _deviceInfo = new()
{
    Guid = Guid.NewGuid(),
    MacAddress = GenRandomBytes(6),
    DeviceName = $"Lagrange-52D02F",
    SystemKernel = "Windows 10.0.19042",
    KernelVersion = "10.0.19042.0"
};
//手动创建设备信息
```

--------------------------------

### 加入表情

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/MessageBuilder

向消息中添加表情。

```csharp
.Face(_id);
```

--------------------------------

### 遍历并解析消息链实体

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/ParseMessageChain

通过遍历 MessageChain 实例并使用类型模式匹配来提取 TextEntity 中的文本内容。

```csharp
var messageChain = new MessageChain();
//假设有一个 MessageChain
foreach(var entity in messageChain)
{
    if(entity is TextEntity textEntity)
        Console.WriteLine(textEntity.Text);
}
```

--------------------------------

### Perform Password Login

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/Login/LoginByPassword

Use the asynchronous LoginByPassword method to initiate and wait for the password login process.

```csharp
await bot.LoginByPassword();
```

--------------------------------

### 加入回复

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/MessageBuilder

让当前消息回复指定的消息链。

```csharp
.Forward(_text);
```

--------------------------------

### 正向 WebSocket 配置

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/Config

配置正向 WebSocket 服务实现。

```json5
{
	"Type": "ForwardWebSocket",
	"Host": "127.0.0.1",
	"Port": 8081,
	"HeartBeatInterval": 5000,
	"HeartBeatEnable": true,
	"AccessToken": ""
}
```

--------------------------------

### 构造群聊消息 MessageChain

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/MessageBuilder

使用群号初始化一个群聊消息链。

```csharp
var groupMessageChain = MessageBuilder.Group(_uin)
```

--------------------------------

### 自动更新配置文件示例

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/AutoUpdate

配置自动更新功能的 JSON 结构。请注意，实际使用时需删除注释行。

```json
{
   "EnableAutoUpdate": false,  // 启用自动更新
   "CheckInterval": 360,  // 每360s检查一次更新,单位为秒
   "ProxyUrl": "",  //访问Github的代理地址, 为空则不使用代理,和SignServer的ProxyUrl一样只接受http协议
   "LastUpdateTime": "2025-04-24T17:00:00Z"  //由程序自动生成的上次更新时间, 一般情况下请勿修改
}
```

--------------------------------

### Subscribe to an event

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Event

Defines the method signature for subscribing to events in LagrangeGo.

```go
EventHandle[T].Subscribe(func(client *QQClient, event T))
```

--------------------------------

### MessageBuilder.Friend(uint uin)

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/MessageBuilder

Initializes a new MessageChain instance for a private chat.

```APIDOC
## MessageBuilder.Friend(uint uin)

### Description
Creates a MessageChain instance targeted at a specific friend.

### Parameters
- **uin** (uint) - Required - The target user's uin.
```

--------------------------------

### 发送消息链示例

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/Send/SendMessage

使用 bot 实例发送构建好的消息链，并异步等待返回结果。

```csharp
var messageChain;
//假设之前已经构建好了消息链
var result = await bot.SendMessage(messageChain.Build());
```

--------------------------------

### MessageBuilder.Group(uint uin)

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/MessageBuilder

Initializes a new MessageChain instance for a group chat.

```APIDOC
## MessageBuilder.Group(uint uin)

### Description
Creates a MessageChain instance targeted at a specific group.

### Parameters
- **uin** (uint) - Required - The target group number.
```

--------------------------------

### 构造私聊消息 MessageChain

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/MessageBuilder

使用用户 UIN 初始化一个私聊消息链。

```csharp
var privateMessageChain = MessageBuilder.Friend(_uin)
```

--------------------------------

### 正向 HTTP 配置

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/Config

配置正向 HTTP 服务实现。

```json5
{
	"Type": "Http",
	"Host": "*",
	"Port": 8083,
	"AccessToken": ""
}
```

--------------------------------

### 加入 XML

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/MessageBuilder

向消息中添加 XML 内容。

```csharp
.Xml(_xml);
```

--------------------------------

### 反向 WebSocket 配置

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/Config

配置反向 WebSocket 服务实现。

```json5
{
	"Type": "ReverseWebSocket",
	"Host": "127.0.0.1",
	"Port": 8080,
	"Suffix": "/onebot/v11/ws",
	"ReconnectInterval": 5000,
	"HeartBeatInterval": 5000,
	"HeartBeatEnable": true,
	"AccessToken": ""
}
```

--------------------------------

### EventHandle[T].Subscribe

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Event

Registers a callback function to handle specific events triggered by the QQ client.

```APIDOC
## EventHandle[T].Subscribe

### Description
Subscribes to a specific event type. When the event occurs, the provided callback function is executed with the client instance and the event data.

### Signature
`EventHandle[T].Subscribe(func(client *QQClient, event T))`

### Supported Events
| EventHandle[T] | Description |
| --- | --- |
| `EventHandle[*message.GroupMessage]` | 群聊消息事件 |
| `PrivateMessageEvent[*message.PrivateMessage]` | 私聊消息事件 |
| `TempMessageEvent[*message.TempMessage]` | 临时会话消息事件 |
| `GroupInvitedEvent[*event.GroupInvite]` | 被邀请入群 |
| `GroupMemberJoinRequestEvent[*event.GroupMemberJoinRequest]` | 加群申请 |
| `GroupMemberJoinEvent[*event.GroupMemberIncrease]` | 成员入群 |
| `GroupMemberLeaveEvent[*event.GroupMemberDecrease]` | 成员退群 |
| `GroupMuteEvent[*event.GroupMute]` | 群聊禁言 |
| `GroupRecallEvent[*event.GroupRecall]` | 群聊撤回消息 |
| `FriendRequestEvent[*event.FriendRequest]` | 好友申请 |
| `FriendRecallEvent[*event.FriendRecall]` | 好友消息撤回 |
| `RenameEvent[*event.Rename]` | 昵称变动 |

### Example
```go
qqclient.GroupMessageEvent.Subscribe(func(client *client.QQClient, event *message.GroupMessage) {
    fmt.Println(event.ToString())
})
```
```

--------------------------------

### 加入合并转发

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/MessageBuilder

向消息中添加合并转发内容。

```csharp
.MultiMsg();
```

--------------------------------

### 运行 Lagrange.OneBot

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/Config

根据操作系统选择对应的运行方式。

```text
双击 Lagrange.OneBot.exe 运行即可
```

```shell
# 可执行权限（可选）
chmod +x ./Lagrange.OneBot
# 运行
./Lagrange.OneBot
```

--------------------------------

### 使用 Nonebot 发送合并转发消息

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

展示了如何通过 Nonebot 适配器构造自定义节点消息并发送合并转发。

```python
from nonebot.adapters.onebot.v11 import MessageSegment, Message, Bot

async def test_send_forward_message(bot: Bot, target_id: int):
    messages = MessageSegment.node_custom(
        user_id=2854196310, nickname="小助手", content=Message(MessageSegment.text("测试消息"))
    )
    res_id = await bot.call_api("send_forward_msg", messages=Message(messages))
    await bot.send_group_msg(group_id=target_id, message=Message(MessageSegment.forward(res_id)))
```

--------------------------------

### MessageChain Fluent Methods

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/MessageChain/MessageBuilder

Methods used to append content to a MessageChain instance.

```APIDOC
## MessageChain Fluent Methods

### .Text(string text)
Appends a text message.

### .Image(string filePath) / .Image(byte[] file)
Appends an image from a file path or binary data.

### .Mention(uint target, string display = null)
Appends a mention (at) to a specific user.

### .Face(ushort id, bool isLarge = false)
Appends an expression/face by ID.

### .Forward(MessageChain target)
Appends a reply to a specific message.

### .Xml(string xml)
Appends XML content.

### .File(string filePath) / .File(byte[] file, string fileName)
Appends a file from a path or binary data.
```

--------------------------------

### Event Delegates

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/Event/EventInvoker

A list of available event delegates that can be subscribed to within the Lagrange framework.

```APIDOC
## Event Delegates

### Description
List of subscribable event delegates for monitoring bot lifecycle, messages, and group events.

### Available Events
- **OnBotOnlineEvent** (LagrangeEvent<BotOnlineEvent>?) - Triggered when the bot comes online.
- **OnBotOfflineEvent** (LagrangeEvent<BotOfflineEvent>?) - Triggered when the bot goes offline.
- **OnBotLogEvent** (LagrangeEvent<BotLogEvent>?) - Triggered when a log is generated.
- **OnBotCaptchaEvent** (LagrangeEvent<BotCaptchaEvent>?) - Triggered when the bot requires a captcha.
- **OnGroupInvitationReceived** (LagrangeEvent<GroupInvitationEvent>?) - Triggered when the bot is invited to a group.
- **OnFriendMessageReceived** (LagrangeEvent<FriendMessageEvent>?) - Triggered when a private message is received.
- **OnGroupMessageReceived** (LagrangeEvent<GroupMessageEvent>?) - Triggered when a group message is received.
- **OnTempMessageReceived** (LagrangeEvent<TempMessageEvent>?) - Triggered when a temporary group message is received.
- **OnGroupAdminChangedEvent** (LagrangeEvent<GroupAdminChangedEvent>?) - Triggered when group admin status changes.
- **OnGroupMemberIncreaseEvent** (LagrangeEvent<GroupMemberIncreaseEvent>?) - Triggered when a member joins a group.
- **OnGroupMemberDecreaseEvent** (LagrangeEvent<GroupMemberDecreaseEvent>?) - Triggered when a member leaves a group.
- **FriendRequestEvent** (LagrangeEvent<FriendRequestEvent>?) - Triggered when a friend request is received.
```

--------------------------------

### HTTP POST 配置

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/Config

配置 HTTP POST 服务实现。Host 字段支持填写协议前缀如 https://。

```json5
{
  "Type": "HttpPost",
  "Host": "127.0.0.1", // 可以填写前缀协议, 例如 `https://`
  "Port": 8082,
  "Suffix": "/",
  "HeartBeatInterval": 5000,
  "HeartBeatEnable": true,
  "AccessToken": "",
  "Secret": ""
}
```

--------------------------------

### fetch_custom_face

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Retrieves a list of download URLs for custom collected emojis.

```APIDOC
## fetch_custom_face

### Description
Retrieves a list of download URLs for custom collected emojis.

### Response
- **[RootElement]** (List[string]) - List of emoji download URLs
```

--------------------------------

### LagrangeGo 核心功能示例

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/LagrangeGo/Example

展示了客户端初始化、设备配置、登录流程处理以及消息事件订阅的完整实现。

```go
package main

import (
	"errors"
	"fmt"
	"os"
	"os/signal"
	"path"
	"strings"
	"syscall"
	"time"

	"github.com/mattn/go-colorable"
	"github.com/sirupsen/logrus"

	"github.com/LagrangeDev/LagrangeGo/client"
	"github.com/LagrangeDev/LagrangeGo/client/auth"
	"github.com/LagrangeDev/LagrangeGo/message"
	"github.com/LagrangeDev/LagrangeGo/utils"
)

var (
	dumpspath = "dump"
)

func main() {
    // 使用特定的协议版本
	appInfo := auth.AppList["linux"]["3.2.15-30366"]
	// 创建设备信息
	deviceInfo := &auth.DeviceInfo{
		GUID:          "cfcd208495d565ef66e7dff9f98764da",
		DeviceName:    "Lagrange-DCFCD07E",
		SystemKernel:  "Windows 10.0.22631",
		KernelVersion: "10.0.22631",
	}
    
    // 创建qqclient实例
	qqclient := client.NewClient(0, "")
	// 设置qqclient的logger
	qqclient.SetLogger(protocolLogger{})
	// 使用协议版本
	qqclient.UseVersion(appInfo)
	// 添加signserver，注意要和appinfo版本匹配
	qqclient.AddSignServer("https://sign.lagrangecore.org/api/sign/30366")
	// 使用设备信息
	qqclient.UseDevice(deviceInfo)
	
	// 从保存的sig.bin文件读取登录信息
	data, err := os.ReadFile("sig.bin")
	if err != nil {
		logrus.Warnln("read sig error:", err)
	} else {
	    // 将登录信息反序列化
		sig, err := auth.UnmarshalSigInfo(data, true)
		if err != nil {
			logrus.Warnln("load sig error:", err)
		} else {
		    // 如果登录信息有效，则使用登录信息登录
			qqclient.UseSig(sig)
		}
	}
    
    // 订阅群消息事件
	qqclient.GroupMessageEvent.Subscribe(func(client *client.QQClient, event *message.GroupMessage) {
		if event.ToString() == "114514" {
			img, _ := message.NewFileImage("testgroup.png")
			_, err := client.SendGroupMessage(event.GroupUin, []message.IMessageElement{img})
			if err != nil {
				return
			}
		}
	})

	qqclient.PrivateMessageEvent.Subscribe(func(client *client.QQClient, event *message.PrivateMessage) {
		img, _ := message.NewFileImage("testprivate.png")
		_, err := client.SendPrivateMessage(event.Sender.Uin, []message.IMessageElement{img})
		if err != nil {
			return
		}
	})

	qqclient.DisconnectedEvent.Subscribe(func(client *client.QQClient, event *client.DisconnectedEvent) {
		logger.Infof("连接已断开：%v", event.Message)
	})

	err = func(c *client.QQClient, passwordLogin bool) error {
		logger.Info("login with password")
		// 如果登录信息存在，可以使用fastlogin
		err := c.FastLogin()
		if err == nil {
			return nil
		}

		if passwordLogin {
		    // 密码登录，目前无法使用
			ret, err := c.PasswordLogin()
			for {
				if err != nil {
					logger.Errorf("密码登录失败: %s", err)
					break
				}
				if ret.Success {
					return nil
				}
				switch ret.Error {
				case client.SliderNeededError:
					logger.Warnln("captcha verification required")
					logger.Warnln(ret.VerifyURL)
					aid := strings.Split(strings.Split(ret.VerifyURL, "sid=")[1], "&")[0]
					logger.Warnln("ticket?->")
					ticket := utils.ReadLine()
					logger.Warnln("rand_str?->")
					randStr := utils.ReadLine()
					ret, err = c.SubmitCaptcha(ticket, randStr, aid)
					continue
				case client.UnsafeDeviceError:
					vf, err := c.GetNewDeviceVerifyURL()
					if err != nil {
						return err
					}
					logger.Infoln(vf)
					err = c.NewDeviceVerify(vf)
					if err != nil {
						return err
					}
				default:
					logger.Errorf("Unhandled exception raised: %s", ret.ErrorMessage)
				}
			}
		}
		logger.Infoln("login with qrcode")
		
		// 扫码登录流程
		// 首先获取二维码
		png, _, err := c.FetchQRCodeDefault()
		if err != nil {
			return err
		}
		qrcodePath := "qrcode.png"
		// 保存到本地以供扫码
		err = os.WriteFile(qrcodePath, png, 0666)
		if err != nil {
			return err
		}
		logger.Infof("qrcode saved to %s", qrcodePath)
		for {
		    // 轮询二维码扫描结果
			retCode, err := c.GetQRCodeResult()
			if err != nil {
				logger.Errorln(err)
				return err
			}
			// 等待扫码
			if retCode.Waitable() {
				time.Sleep(3 * time.Second)
				continue
			}
			if !retCode.Success() {
				return errors.New(retCode.Name())
			}
			break
		}
		// 扫码完成后就可以进行登录
		_, err = c.QRCodeLogin()
		return err
	}(qqclient, false)

	if err != nil {
		logger.Errorln("login err:", err)
		return
	}
	logger.Infoln("login successed")

	defer qqclient.Release()

	defer func() {
	    // 序列化登录信息以便下次使用
		data, err = qqclient.Sig().Marshal()
		if err != nil {
			logger.Errorln("marshal sig.bin err:", err)
			return
		}
		err = os.WriteFile("sig.bin", data, 0644)
		if err != nil {
			logger.Errorln("write sig.bin err:", err)
			return
		}
		logger.Infoln("sig saved into sig.bin")
	}()

	// setup the main stop channel
	mc := make(chan os.Signal, 2)
	signal.Notify(mc, os.Interrupt, syscall.SIGTERM)
	for {
		switch <-mc {
		case os.Interrupt, syscall.SIGTERM:
			return
		}
	}
}

// protocolLogger from https://github.com/Mrs4s/go-cqhttp/blob/a5923f179b360331786a6509eb33481e775a7bd1/cmd/gocq/main.go#L501
type protocolLogger struct{}

const fromProtocol = "Lgr -> "

func (p protocolLogger) Info(format string, arg ...any) {
	logger.Infof(fromProtocol+format, arg...)
}
```

--------------------------------

### upload_private_file

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Uploads a file to a private chat.

```APIDOC
## upload_private_file

### Description
Uploads a file to a private chat.

### Parameters
- **user_id** (int) - Required - Target QQ number
- **file** (string) - Required - Local file path
- **name** (string) - Required - File name
```

--------------------------------

### subscribe(event, handler)

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/lagrange-python/Event

Subscribes a handler function to a specific event type. The handler function receives the client instance and the event object.

```APIDOC
## subscribe(event, handler)

### Description
Registers a callback function to be executed when a specific event occurs. The handler function must accept two arguments: the client instance (`lagrange.client.client.Client`) and the event object.

### Parameters
- **event** (dataclass) - Required - The event data class to subscribe to (e.g., GroupMessage, FriendMessage).
- **handler** (function) - Required - The callback function to execute when the event is triggered.
```

--------------------------------

### SendMessage(MessageChain)

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.Core/Send/SendMessage

Sends a message chain using the bot instance. After a successful send, the corresponding message event is triggered.

```APIDOC
## SendMessage

### Description
Sends a constructed message chain through the bot instance. Upon success, the operation returns a message result and triggers the corresponding message event.

### Method
Async Method

### Signature
`SendMessage(MessageChain _messageChain)`

### Parameters
- **_messageChain** (MessageChain) - Required - The message chain to be sent, constructed via the message builder.

### Returns
- **MessageResult** - The result of the message sending operation.

### Example
```csharp
var messageChain;
// Assuming the message chain is already constructed
var result = await bot.SendMessage(messageChain.Build());
```
```

--------------------------------

### get_group_root_files

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Retrieves the file list of the group root directory.

```APIDOC
## get_group_root_files

### Description
Retrieves the file list of the group root directory.

### Parameters
- **group_id** (int) - Required - Group ID

### Response
- **files** (List[File]) - File list
- **folders** (List[Folder]) - Folder list
```

--------------------------------

### friend_poke

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Pokes a friend.

```APIDOC
## friend_poke

### Description
Pokes a friend.

### Parameters
- **user_id** (int) - Required - Target QQ number
```

--------------------------------

### send_forward_msg

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Constructs a forward message.

```APIDOC
## send_forward_msg

### Description
Constructs a forward message.

### Parameters
- **messages** (List[Node]) - Required - List of nodes containing name, uin, and content

### Response
- **resid** (string) - Resid
```

--------------------------------

### get_group_files_by_folder

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Retrieves the file list of a specific group sub-directory.

```APIDOC
## get_group_files_by_folder

### Description
Retrieves the file list of a specific group sub-directory.

### Parameters
- **group_id** (int) - Required - Group ID
- **folder_id** (string) - Required - Folder ID

### Response
- **files** (List[File]) - File list
- **folders** (List[Folder]) - Folder list
```

--------------------------------

### upload_group_file

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Uploads a file to a group.

```APIDOC
## upload_group_file

### Description
Uploads a file to a group.

### Parameters
- **group_id** (int) - Required - Group ID
- **file** (string) - Required - Local file path
- **name** (string) - Required - Storage name
- **folder** (string) - Optional - Parent folder ID
```

--------------------------------

### set_group_reaction

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Sets a reaction for a group message.

```APIDOC
## set_group_reaction

### Description
Sets a reaction for a group message.

### Parameters
- **group_id** (uint) - Required - Group ID
- **message_id** (int) - Required - Message ID
- **code** (string) - Required - Emoji ID
- **is_add** (bool) - Required - Add or remove reaction
```

--------------------------------

### get_group_file_url

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Retrieves the download URL for a group file.

```APIDOC
## get_group_file_url

### Description
Retrieves the download URL for a group file.

### Parameters
- **group_id** (int) - Required - Group ID
- **file_id** (string) - Required - File ID
- **busid** (int) - Required - File type

### Response
- **url** (string) - File download URL
```

--------------------------------

### group_poke

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Pokes a member in a group.

```APIDOC
## group_poke

### Description
Pokes a member in a group.

### Parameters
- **group_id** (int) - Required - Group ID
- **user_id** (int) - Required - Target QQ number
```

--------------------------------

### get_essence_msg_list

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Retrieves the list of essence messages for a group.

```APIDOC
## get_essence_msg_list

### Description
Retrieves the list of essence messages for a group.

### Parameters
- **group_id** (int) - Required - Group ID
```

--------------------------------

### send_private_forward_msg

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Sends a forward message to a friend.

```APIDOC
## send_private_forward_msg

### Description
Sends a forward message to a friend.

### Parameters
- **user_id** (uint) - Required - Friend QQ number
- **messages** (List[Node]) - Required - Custom forward messages

### Response
- **message_id** (int) - Message ID
- **forward_id** (string) - Forward message ID
```

--------------------------------

### send_group_forward_msg

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Sends a forward message to a group.

```APIDOC
## send_group_forward_msg

### Description
Sends a forward message to a group.

### Parameters
- **group_id** (uint) - Required - Group ID
- **messages** (List[Node]) - Required - Custom forward messages

### Response
- **message_id** (int) - Message ID
- **forward_id** (string) - Forward message ID
```

--------------------------------

### set_essence_msg

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Sets a message as a group essence message.

```APIDOC
## set_essence_msg

### Description
Sets a message as a group essence message.

### Parameters
- **message_id** (int) - Required - Message ID
```

--------------------------------

### set_group_special_title

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Sets a special title for a group member.

```APIDOC
## set_group_special_title

### Description
Sets a special title for a group member.

### Parameters
- **group_id** (uint) - Required - Group ID
- **user_id** (uint) - Required - Target QQ number
- **special_title** (string) - Required - Special title (empty string to delete)
```

--------------------------------

### get_friend_msg_history

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Retrieves historical message records for a specific friend.

```APIDOC
## get_friend_msg_history

### Description
Retrieves historical message records for a specific friend.

### Parameters
- **user_id** (uint) - Required - Friend ID
- **message_id** (int) - Required - ID of the last message to retrieve
- **count** (int) - Required - Number of messages to retrieve

### Response
- **messages** (List[OneBotPrivateMessage]) - Retrieved messages
```

--------------------------------

### get_group_msg_history

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Retrieves historical message records for a specific group.

```APIDOC
## get_group_msg_history

### Description
Retrieves historical message records for a specific group.

### Parameters
- **group_id** (uint) - Required - Group ID
- **message_id** (int) - Required - ID of the last message to retrieve
- **count** (int) - Required - Number of messages to retrieve

### Response
- **messages** (List[OneBotGroupMessage]) - Retrieved messages
```

--------------------------------

### delete_essence_msg

Source: https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/API/Extend

Deletes a group essence message.

```APIDOC
## delete_essence_msg

### Description
Deletes a group essence message.

### Parameters
- **message_id** (int) - Required - Message ID
```
Tokens:
Raw