### GET /api/getGuildList

Source: https://misakatat.github.io/shiro-docs/action

Retrieves a list of all guilds the bot is a part of.

```APIDOC
## 获取频道列表

### Description
Retrieves a list of all guilds the bot is a part of.

### Method
GET

### Endpoint
/api/getGuildList

### Response
#### Success Response (200)
- Returns a list of GuildListResp objects, where each object contains details about a guild.

#### Response Example
```json
[
  {
    "guildId": "12345",
    "guildName": "My Server"
  },
  {
    "guildId": "67890",
    "guildName": "Another Server"
  }
]
```
```

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

### GET /api/getGuildServiceProfile

Source: https://misakatat.github.io/shiro-docs/action

Retrieves the bot's profile information within a guild.

```APIDOC
## 获取频道内 BOT 资料

### Description
Retrieves the bot's profile information within a guild.

### Method
GET

### Endpoint
/api/getGuildServiceProfile

### Response
#### Success Response (200)
- **nickname** (String) - The bot's nickname in the guild.
- **tinyId** (String) - The bot's unique ID.
- **avatarUrl** (String) - The URL of the bot's avatar.

#### Response Example
```json
{
  "nickname": "MyBot",
  "tinyId": "bot456",
  "avatarUrl": "https://example.com/avatar.png"
}
```
```

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

### Initiate Temporary Session

Source: https://misakatat.github.io/shiro-docs/action

Starts a temporary chat session with a user within a specified group. Requires bot to be an admin or owner.

```APIDOC
## POST /sendPrivateMsg (Temporary Session)

### Description
Initiates a temporary chat session with a user in a specified group. The bot must be an administrator or owner of the group.

### Method
POST

### Endpoint
/sendPrivateMsg

### Parameters
#### Request Body
- **groupId** (long) - Required - The group ID from which to initiate the temporary session.
- **userId** (long) - Required - The ID of the target user.
- **msg** (String) - Required - The content of the message.
- **autoEscape** (boolean) - Optional - Whether to send the message content as plain text (does not parse CQ codes).

### Response
#### Success Response (200)
- **messageId** (int) - The ID of the sent message.
```

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

### Get Login Info

Source: https://misakatat.github.io/shiro-docs/action

Retrieves information about the currently logged-in bot account.

```APIDOC
## GET /getLoginInfo

### Description
Retrieves information about the currently logged-in bot account.

### Method
GET

### Endpoint
/getLoginInfo

### Response
#### Success Response (200)
- **userId** (long) - The account ID of the bot.
- **nickname** (String) - The nickname of the bot.
```

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

### Get Group List

Source: https://misakatat.github.io/shiro-docs/action

Retrieves a list of all groups the bot is a member of.

```APIDOC
## GET /getGroupList

### Description
Retrieves a list of all groups the bot is a member of.

### Method
GET

### Endpoint
/getGroupList

### Response
#### Success Response (200)
- **Direct Return** (List<GroupInfoResp>) - A list containing detailed information for each group.
```

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

### Get Online Clients (bot.getOnlineClients)

Source: https://misakatat.github.io/shiro-docs/action

Retrieves a list of online clients connected to the current bot account. Returns a list of client information.

```javascript
bot.getOnlineClients()
```

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

### Get Group Root Files (bot.getGroupRootFiles)

Source: https://misakatat.github.io/shiro-docs/action

Retrieves a list of files and folders in the root directory of a group. Requires the groupId.

```javascript
bot.getGroupRootFiles(groupId)
```

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

### Get Message

Source: https://misakatat.github.io/shiro-docs/action

Retrieves message details using its ID. Returns information like sender, time, and content.

```APIDOC
## GET /getMsg

### Description
Retrieves message details based on the message ID.

### Method
GET

### Endpoint
/getMsg

### Parameters
#### Query Parameters
- **msgId** (int) - Required - The ID of the message to retrieve.

### Response
#### Success Response (200)
- **messageId** (int) - The ID of the message.
- **realId** (boolean) - Indicates if this is the real message ID.
- **sender** (Sender) - Information about the message sender.
- **time** (int) - The timestamp when the message was sent.
- **message** (String) - The content of the message.
- **rawMessage** (String) - The raw, unparsed message content.
```

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

### Get Friend List

Source: https://misakatat.github.io/shiro-docs/action

Retrieves a list of all friends associated with the bot account.

```APIDOC
## GET /getFriendList

### Description
Retrieves a list of all friends of the bot account.

### Method
GET

### Endpoint
/getFriendList

### Response
#### Success Response (200)
- **Direct Return** (List<FriendInfoResp>) - A list containing detailed information for each friend.
```

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

### Process Message Chains with ArrayMsg and MsgTypeEnum in Java

Source: https://misakatat.github.io/shiro-docs/advanced

Demonstrates how to process message chains using ArrayMsg and MsgTypeEnum, available in Shiro v1.1.7 and v1.4.5 respectively. This example filters and prints URLs of all image messages received.

```java
@Component
public class ExamplePlugin extends BotPlugin {

    @Override
    public int onPrivateMessage(Bot bot, PrivateMessageEvent event) {
        event.getArrayMsg()
                .stream()
                .filter(item -> MsgTypeEnum.image == item.getType())
                .forEach(image -> System.out.println(image.getData().get("url")));
        return MESSAGE_IGNORE;
    }

}

```

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

### Get Guild Metadata by Guest

Source: https://misakatat.github.io/shiro-docs/action

Fetches metadata for a specific guild using its ID. This function provides details such as guild name, profile, creation time, member counts, and owner ID. It is intended for use by guests.

```javascript
bot.getGuildMetaByGuest(guildId)
```

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

### GET /api/getGuildChannelList

Source: https://misakatat.github.io/shiro-docs/action

Retrieves a list of channels within a specific guild. Caching can be disabled.

```APIDOC
## 获取子频道列表

### Description
Retrieves a list of channels within a specific guild. Caching can be disabled.

### Method
GET

### Endpoint
/api/getGuildChannelList

### Parameters
#### Query Parameters
- **guildId** (String) - Required - The ID of the guild for which to retrieve channels.
- **noCache** (String) - Optional - Set to 'true' to disable cache.

### Response
#### Success Response (200)
- **ownerGuildId** (String) - The ID of the parent guild.
- **channelId** (String) - The ID of the channel.
- **channelType** (int) - The type of the channel.
- **channelName** (String) - The name of the channel.
- **createTime** (long) - The timestamp when the channel was created.
- **creatorTinyId** (String) - The ID of the channel creator.
- **talkPermission** (int) - The talk permission type for the channel.
- **visibleType** (int) - The visibility type of the channel.
- **currentSlowMode** (int) - The key for the currently enabled slow mode.
- **slowModes** (List<SlowModeInfo>) - A list of available slow mode options for the channel.

#### Response Example
```json
[
  {
    "ownerGuildId": "12345",
    "channelId": "channel1",
    "channelType": 1,
    "channelName": "General",
    "createTime": 1609459200000,
    "creatorTinyId": "user123",
    "talkPermission": 0,
    "visibleType": 0,
    "currentSlowMode": 0,
    "slowModes": [
      {
        "key": 0,
        "value": "Off"
      }
    ]
  }
]
```
```

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

### Get Guild List

Source: https://misakatat.github.io/shiro-docs/action

Retrieves a list of all guilds the bot is a part of. The function returns a list of GuildListResp objects, each representing a guild.

```javascript
bot.getGuildList()
```

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

### Generate Forwarded Messages with ShiroUtils in Java

Source: https://misakatat.github.io/shiro-docs/advanced

Provides an example of how to use ShiroUtils to create and send forwarded messages, including both group and private messages. This involves constructing a list of messages and then using the bot object to send them.

```java
// 构建消息列表（可以填充 MsgUtils 构建的消息）
List<String> msgList = new ArrayList<String>() {
    msgList.add("这是第一条消息");
    msgList.add("这是第二条消息");
    msgList.add("这是第三条消息");
};

// 构建合并转发消息（selfId为合并转发消息显示的账号，nickname为显示的发送者昵称，msgList为消息列表）
List<Map<String, Object>> forwardMsg = ShiroUtils.generateForwardMsg(selfId, nickname, msgList)

// 发送合并转发内容到群（groupId为要发送的群）
bot.sendGroupForwardMsg(groupId, forwardMsg)

// 发送合并转发内容到私聊（userId为要发送的好友账号）
bot.sendPrivateForwardMsg(userId, forwardMsg)

```

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

### Implement a Custom Message Event Interceptor in Java

Source: https://misakatat.github.io/shiro-docs/advanced

Provides a Java example of a custom message event interceptor that implements the `BotMessageEventInterceptor` interface. The `preHandle` method can be used to intercept and potentially block messages before they are processed by plugins.

```java
@Component
public class InterceptorExample implements BotMessageEventInterceptor {

    @Override
    public boolean preHandle(Bot bot, MessageEvent event) throws Exception {
        // 预处理方法，可以在触发事件前做一些处理，返回值为 false 时本次事件将会被拦截
        // 使用场景可以是黑名单检查或检查权限等等，具体的使用场景可以发挥自己的想象力
        // MessageEvent 可能为右边这三种类型 PrivateMessageEvent、GroupMessageEvent、GuildMessageEvent
        return false;
    }

    @Override
    public void afterCompletion(Bot bot, MessageEvent event) throws Exception {
        // 当 preHandle 返回值为 true 时则会执行 plugin-list，执行完毕后进入到 afterCompletion
    }

}

```

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

### GET /api/getGuildMetaByGuest

Source: https://misakatat.github.io/shiro-docs/action

Retrieves metadata for a specific guild, accessible even without being a member.

```APIDOC
## 通过访客获取频道元数据

### Description
Retrieves metadata for a specific guild, accessible even without being a member.

### Method
GET

### Endpoint
/api/getGuildMetaByGuest

### Parameters
#### Query Parameters
- **guildId** (String) - Required - The ID of the guild for which to retrieve metadata.

### Response
#### Success Response (200)
- **guildId** (String) - The ID of the guild.
- **guildName** (String) - The name of the guild.
- **guildProfile** (String) - The profile description of the guild.
- **createTime** (long) - The timestamp when the guild was created.
- **maxMemberCount** (long) - The maximum number of members the guild can hold.
- **maxRobotCount** (long) - The maximum number of bots allowed in the guild.
- **maxAdminCount** (long) - The maximum number of administrators allowed in the guild.
- **memberCount** (long) - The current number of members in the guild.
- **ownerId** (String) - The ID of the guild owner.

#### Response Example
```json
{
  "guildId": "12345",
  "guildName": "My Server",
  "guildProfile": "A great place to chat!",
  "createTime": 1609459200000,
  "maxMemberCount": 1000,
  "maxRobotCount": 10,
  "maxAdminCount": 5,
  "memberCount": 500,
  "ownerId": "owner789"
}
```
```

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

### Get Group Member List

Source: https://misakatat.github.io/shiro-docs/action

Retrieves a list of all members within a specified group.

```APIDOC
## GET /getGroupMemberList

### Description
Retrieves a list of all members within a specified group.

### Method
GET

### Endpoint
/getGroupMemberList

### Parameters
#### Query Parameters
- **groupId** (long) - Required - The ID of the group.

### Response
#### Success Response (200)
- **Direct Return** (List<GroupMemberInfoResp>) - A list containing detailed information for each group member.
```

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

### Migrate MessageHandler Annotation to AnyMessageHandler (Java)

Source: https://misakatat.github.io/shiro-docs/migration

The @MessageHandler annotation has been replaced with @AnyMessageHandler in Shiro SDK v2. This update standardizes message handling across different event types.

```java
// v1
@MessageHandler
public void fun(Bot bot, AnyMessageEvent event) {}


```

```java
// v2
@AnyMessageHandler
public void fun(Bot bot, AnyMessageEvent event) {}


```

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

### Get Group Files By Folder (bot.getGroupFilesByFolder)

Source: https://misakatat.github.io/shiro-docs/action

Retrieves a list of files and folders within a specific folder in a group. Requires groupId and folderId.

```javascript
bot.getGroupFilesByFolder(groupId, folderId)
```

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

### Enable Forward WebSocket Connection (YAML)

Source: https://misakatat.github.io/shiro-docs/migration

Shiro SDK v2.2.0 introduces support for forward WebSocket connections, addressing an issue in v2.1.9 where messages could fail to send due to abnormal Session closure in reverse connection mode. The configuration details for both client (forward) and server (reverse) WebSocket connections are provided.

```yaml
# v2.1.8
# 该配置为反向连接示例
shiro:
  ws-config:
    ws-url: "/ws/shiro"


```

```yaml
# v2.2.0
shiro:
  ws:
    # 该配置为正向连接示例
    client:
      enable: false
      url: "ws://your-domain:port"
    # 该配置为反向连接示例
    server:
      enable: false
      url: "/ws/shiro"


```

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

### Add @MessageHandlerFilter Annotation (Java)

Source: https://misakatat.github.io/shiro-docs/migration

In Shiro SDK v2.1.0, the @MessageHandlerFilter annotation was introduced to provide more granular control over message handling based on command.

```java
// v2.0.9
@AnyMessageHandler(cmd = "say hello")
public void fun(Bot bot, AnyMessageEvent event) {}


```

```java
// v2.1.0
@AnyMessageHandler
@MessageHandlerFilter(cmd = "say hello")
public void fun(Bot bot, AnyMessageEvent event) {}


```

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

### Migrate BotPlugin @NotNull Annotations (Java)

Source: https://misakatat.github.io/shiro-docs/migration

In Shiro SDK v2, the @NotNull annotations have been removed from all methods within BotPlugin. This change simplifies the API by not requiring explicit null checks for method parameters.

```java
// v1
@Override
public int onAnyMessage(@NotNull Bot bot, @NotNull AnyMessageEvent event) {
    return MESSAGE_IGNORE;
}


```

```java
// v2
@Override
public int onAnyMessage(Bot bot, AnyMessageEvent event) {
    return MESSAGE_IGNORE;
}


```

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

### Get Group Info

Source: https://misakatat.github.io/shiro-docs/action

Retrieves detailed information about a specific group, with an option to disable caching.

```APIDOC
## GET /getGroupInfo

### Description
Retrieves detailed information about a specific group. Caching can be disabled.

### Method
GET

### Endpoint
/getGroupInfo

### Parameters
#### Query Parameters
- **groupId** (long) - Required - The ID of the group.
- **noCache** (boolean) - Optional - If `true`, disables the use of cached data.

### Response
#### Success Response (200)
- [Group Info Object] - Detailed information about the group.
```

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

### Get Unidirectional Friend List (bot.getUnidirectionalFriendList)

Source: https://misakatat.github.io/shiro-docs/action

Retrieves a list of unidirectional friends. Returns a list of friend information.

```javascript
bot.getUnidirectionalFriendList()
```

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

### Get Guild Member List (bot.getGuildMemberList)

Source: https://misakatat.github.io/shiro-docs/action

Retrieves a list of members in a guild (channel). Use with caution due to potential performance issues with large guilds. Supports pagination with nextToken.

```javascript
bot.getGuildMemberList(guildId, nextToken)
```

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

### Get Essence Message List (bot.getEssenceMsgList)

Source: https://misakatat.github.io/shiro-docs/action

Fetches a list of "essence" (pinned or important) messages from a group. Requires groupId.

```javascript
bot.getEssenceMsgList(groupId)
```

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

### Get Guild Service Profile

Source: https://misakatat.github.io/shiro-docs/action

Fetches the service profile of the bot within a specific guild. This includes the bot's nickname, its unique tinyId, and its avatar URL.

```javascript
bot.getGuildServiceProfile()
```

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

### Get Guild Channel List

Source: https://misakatat.github.io/shiro-docs/action

Retrieves a list of channels within a specified guild. Parameters include the guild ID and an option to disable caching. The returned list contains channel details like ID, type, name, creation time, and permissions.

```javascript
bot.getGuildChannelList(guildId, noCache)
```

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

### Get Word Slices (bot.getWordSlices)

Source: https://misakatat.github.io/shiro-docs/action

Performs Chinese word segmentation on a given content string. Returns a list of word slices.

```javascript
bot.getWordSlices(content)
```

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

### Handle Group Add Requests in Java

Source: https://misakatat.github.io/shiro-docs/event

Defines methods to handle incoming group add requests for the Shiro bot. It includes a basic handler and an example using the @GroupAddRequestHandler annotation. These methods receive Bot and GroupAddRequestEvent objects.

```java
public int onGroupAddRequest(Bot bot, GroupAddRequestEvent event) {
    // do something···
    return MESSAGE_IGNORE;
}

@GroupAddRequestHandler
public void example(Bot bot, GroupAddRequestEvent event){
    // do something···
}
```

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

### Get Group File URL (bot.getGroupFileUrl)

Source: https://misakatat.github.io/shiro-docs/action

Obtains the URL for a specific group file. Requires groupId, fileId, and busId (file type).

```javascript
bot.getGroupFileUrl(groupId, fileId, busId)
```

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

### Handle Friend Add Request Event in Java

Source: https://misakatat.github.io/shiro-docs/event

This code example demonstrates handling incoming friend add requests, using the `onFriendAddRequest` method or the `@FriendAddRequestHandler` annotation. It receives the bot instance and a `FriendAddRequestEvent`. The method should return `MESSAGE_IGNORE` if the request is handled.

```java
public int onFriendAddRequest(Bot bot, FriendAddRequestEvent event) {
    // do something···
    return MESSAGE_IGNORE;
}

@FriendAddRequestHandler
public void example(Bot bot, FriendAddRequestEvent event){
    // do something···
}
```

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

### Get Group At All Remain Count (bot.getGroupAtAllRemain)

Source: https://misakatat.github.io/shiro-docs/action

Retrieves the remaining count for mentioning all members in a group. Returns whether @all is possible and the remaining counts for the group and the logged-in user.

```javascript
bot.getGroupAtAllRemain(groupId)
```

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

### Handle Group Message Event in Java

Source: https://misakatat.github.io/shiro-docs/event

This example demonstrates handling group messages via the `onGroupMessage` method or the `@GroupMessageHandler` annotation. It includes the bot instance and a `GroupMessageEvent`. The method should return `MESSAGE_IGNORE` if the message is handled and no further action is needed.

```java
public int onGroupMessage(Bot bot, GroupMessageEvent event) {
    // do something···
    return MESSAGE_IGNORE;
}

@GroupMessageHandler
public void example(Bot bot, GroupMessageEvent event, Matcher matcher){
    // do something···
}
```

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

### Get Guild Member Profile

Source: https://misakatat.github.io/shiro-docs/action

Fetches the profile information for a specific member within a guild. It requires the guild ID and the user's ID. The returned data includes the user's tinyId, nickname, avatar URL, join time, and roles.

```javascript
bot.getGuildMemberProfile(guildId, userId)
```

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

### Handle Group File Upload Event in Java

Source: https://misakatat.github.io/shiro-docs/event

This code example shows how to respond to file upload events within a group using the `onGroupUploadNotice` method. It receives the bot instance and a `GroupUploadNoticeEvent`. The method should return `MESSAGE_IGNORE` if the event is handled.

```java
public int onGroupUploadNotice(Bot bot, GroupUploadNoticeEvent event) {
    // do something···
    return MESSAGE_IGNORE;
}

@GroupUploadNoticeHandler
public void example(Bot bot, GroupUploadNoticeEvent event){
    // do something···
}
```

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

### Shiro 插件开发 - 编译插件

Source: https://misakatat.github.io/shiro-docs/index

展示了使用 Gradle 编译 Shiro 插件的命令。编译成功后，生成的 JAR 文件位于 `build/libs/` 目录下，需要手动移至 Shiro 的 `plugins` 目录。

```bash
./gradlew build
```

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

### Shiro 插件开发 - 目录结构示例

Source: https://misakatat.github.io/shiro-docs/index

展示了一个典型的 Shiro 插件项目目录结构，包括源代码、SPI 配置文件、Gradle 构建脚本和可执行文件。此结构是开发和打包 Shiro 插件的基础。

```text
ForeignPluginExample/
├── src/
│   ├── main/java/com/mikuac/demo/DemoPlugin.java
│   ├── main/resources/META-INF/services/com.mikuac.shiro.core.BotPlugin
├── build.gradle.kts
├── settings.gradle.kts
├── gradlew
├── gradlew.bat
└── gradle/wrapper/
```

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

### GET /api/getGuildMemberProfile

Source: https://misakatat.github.io/shiro-docs/action

Retrieves the profile information of a specific member within a guild.

```APIDOC
## 单独获取频道成员信息

### Description
Retrieves the profile information of a specific member within a guild.

### Method
GET

### Endpoint
/api/getGuildMemberProfile

### Parameters
#### Query Parameters
- **guildId** (String) - Required - The ID of the guild.
- **userId** (String) - Required - The ID of the user whose profile to retrieve.

### Response
#### Success Response (200)
- **tinyId** (String) - The user's unique ID.
- **nickname** (String) - The user's nickname in the guild.
- **avatarUrl** (String) - The URL of the user's avatar.
- **joinTime** (long) - The timestamp when the user joined the guild.
- **roles** (List<RoleInfo>) - A list of role information for the user.

#### Response Example
```json
{
  "tinyId": "user123",
  "nickname": "TestUser",
  "avatarUrl": "https://example.com/avatar.png",
  "joinTime": 1678886400000,
  "roles": [
    {
      "roleId": "role1",
      "roleName": "Member"
    }
  ]
}
```
```

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

### Go-CQHTTP Instance Configuration for Reverse WebSocket (YAML)

Source: https://misakatat.github.io/shiro-docs/index

This YAML configuration demonstrates how to set up the Go-CQHTTP client to connect to a Shiro SDK WebSocket server using reverse connection. It includes settings for the universal, API, and event WebSocket URLs, along with reconnection intervals.

```yaml
#连接服务列表
servers:
  #反向WS设置
  - ws-reverse:
      #反向WS Universal 地址
      #注意 设置了此项地址后下面两项将会被忽略
      universal: ws://127.0.0.1:5555/ws/shiro
      #反向WS API 地址
      api: ws://your_websocket_api.server
      #反向WS Event 地址
      event: ws://your_websocket_event.server
      #重连间隔 单位毫秒
      reconnect-interval: 3000
      middlewares:
        <<: *default #引用默认中间件
```

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

### Shiro 插件配置 - 自定义插件扫描路径 (YAML)

Source: https://misakatat.github.io/shiro-docs/index

演示了如何在 Shiro 的 `application.yml` 文件中配置 `pluginScanPath` 属性，以指定一个自定义的插件目录。这允许 Shiro 从非默认位置加载插件。

```yaml
shiro:
  pluginScanPath: "/home/user/mybot"
```

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

### Shiro 插件开发 - Gradle 构建脚本配置 (Kotlin)

Source: https://misakatat.github.io/shiro-docs/index

提供了 `build.gradle.kts` 的配置示例，用于正确打包插件 JAR 文件。它配置了 JAR 的 `duplicatesStrategy`、`from` 输出以及 `manifest` 信息，包括依赖列表。

```kotlin
tasks.withType<Jar> {
    // 处理JAR中的重复文件，INCLUDE策略表示保留所有重复项
    duplicatesStrategy = DuplicatesStrategy.INCLUDE

    // 将主源集的所有编译输出加入JAR包
    from(sourceSets.main.get().output)

    manifest {
        // 添加基本信息到 MANIFEST.MF
        attributes(
            mapOf(
                "Implementation-Title" to project.name,       // 使用项目名称
                "Implementation-Version" to project.version,  // 添加版本信息
                "Built-By" to System.getProperty("user.name"),
                "Created-By" to "Gradle ${gradle.gradleVersion}"
            )
        )
        
        // 生成并添加依赖清单
        val dependenciesString = configurations
            .getByName("runtimeClasspath")  // 获取运行时实际解析的依赖
            .resolvedConfiguration
            .resolvedArtifacts
            .map {
                // 将依赖格式化为 "groupId:artifactId:version" 格式
                "${it.moduleVersion.id.group}:${it.moduleVersion.id.name}:${it.moduleVersion.id.version}"
            }
            .distinct()  // 移除重复项
            .filterNot { coordinates ->
                // 过滤掉不应由插件加载的依赖
                // 这些依赖应当由 Shiro 主程序提供，避免类加载冲突
                coordinates.startsWith("org.springframework") ||  // Spring框架
                coordinates.startsWith("com.mikuac:shiro") ||     // Shiro
                coordinates.startsWith("org.slf4j") ||            // 日志门面
                coordinates.startsWith("ch.qos.logback")          // 日志实现
            }
            .joinToString(", ")  // 使用逗号分隔依赖列表

        // 添加依赖列表到 manifest 中，Shiro 将解析此属性来下载所需依赖
        attributes(mapOf("Dependencies" to dependenciesString))
    }
}

// 可选：配置依赖项
dependencies {
    // Shiro 本身仅在编译时需要，运行时由主程序提供
    compileOnly("com.mikuac:shiro:latest")
    
    // 添加其他依赖，这些将被包含在Dependencies清单中
    implementation("com.example:some-library:1.0.0")
}

```

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

### Send Media Files with MsgUtils in Java

Source: https://misakatat.github.io/shiro-docs/advanced

Shows how to use MsgUtils to build messages containing media files, including local files from Windows and Linux, base64 encoded images, and network images. This allows for flexible media sharing in bot responses.

```java
MsgUtils.builder()
        .img("file:///C:/img/1.png")    // Windows 本地图片
        .img("file:///root/1.png")      // Linux   本地图片
        .img("base64://")               // Base64
        .img("https://test.com/1.png")  // 网络图片
        .build();

```

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

### Shiro 插件开发 - META-INF/services 配置

Source: https://misakatat.github.io/shiro-docs/index

说明了如何配置 META-INF/services 文件，以便 ServiceLoader 能够发现插件。该文件应包含插件的完整类名，确保 Shiro 能够正确加载插件实现。

```text
com.mikuac.demo.DemoPlugin
```

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

### Plugin Configuration for Annotation-based Handlers (YAML)

Source: https://misakatat.github.io/shiro-docs/index

This YAML snippet shows how to configure the Shiro server to load your custom plugins. Add the fully qualified name of your plugin class to the `plugin-list`.

```yaml
shiro:
  plugin-list:
    - com.example.bot.plugins.ExamplePlugin
```

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

### Build Rich Messages with MsgUtils in Java

Source: https://misakatat.github.io/shiro-docs/advanced

Illustrates how to use the MsgUtils builder to construct complex messages that include various elements like at-mentions, images, and text. This utility simplifies the creation of rich message content for bots.

```java
String msg = MsgUtils.builder()
        .atAll()                        // @全体成员
        .img("https://test.com/1.png")  // 包含一张图片
        .text("hello~")                 // 包含一段文本内容
        .build();                       // 构建消息

```

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

### Get Stranger Info

Source: https://misakatat.github.io/shiro-docs/action

Fetches information about a user who is not a friend, with an option to disable caching.

```APIDOC
## GET /getStrangerInfo

### Description
Retrieves information about a user, even if they are not a friend. Caching can be disabled.

### Method
GET

### Endpoint
/getStrangerInfo

### Parameters
#### Query Parameters
- **userId** (long) - Required - The ID of the target user.
- **noCache** (boolean) - Optional - If `true`, disables the use of cached data.

### Response
#### Success Response (200)
- **userId** (long) - The account ID of the user.
- **nickname** (String) - The nickname of the user.
- **sex** (String) - The gender of the user.
- **age** (int) - The age of the user.
- **qid** (String) - The user's unique identifier card.
- **level** (int) - The user's level.
- **loginDays** (int) - The number of days the user has been online.
```

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

### Shiro 插件开发 - 插件类定义 (Java)

Source: https://misakatat.github.io/shiro-docs/index

演示了如何创建一个 Shiro 插件类，该类必须继承 BotPlugin 接口并使用 @Component 注解。它展示了如何处理群消息事件，并在收到 'ping' 时回复 'pong'。

```java
package com.mikuac.demo;

import com.mikuac.shiro.core.Bot;
import com.mikuac.shiro.core.BotPlugin;
import com.mikuac.shiro.dto.event.message.GroupMessageEvent;
import org.springframework.stereotype.Component;

@Component
public class DemoPlugin extends BotPlugin {
    @Override
    public int onGroupMessage(Bot bot, GroupMessageEvent event) {
        String msg = event.getMessage();
        if (msg.equals("ping")) {
            bot.sendGroupMsg(event.getGroupId(), "pong", false);
            return MESSAGE_BLOCK;
        }
        return MESSAGE_IGNORE;
    }
}
```

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

### GET /api/getGuildMsg

Source: https://misakatat.github.io/shiro-docs/action

Retrieves messages from a specific guild channel. It allows for an option to bypass cache.

```APIDOC
## 获取频道消息

### Description
Retrieves messages from a specific guild channel. It allows for an option to bypass cache.

### Method
GET

### Endpoint
/api/getGuildMsg

### Parameters
#### Query Parameters
- **guildMsgId** (String) - Required - The ID of the guild message to retrieve.
- **noCache** (String) - Optional - Set to 'true' to bypass the cache.

### Response
#### Success Response (200)
- **guildId** (String) - The ID of the guild.
- **channelId** (String) - The ID of the channel.
- **message** (String) - The content of the message.
- **messageId** (String) - The ID of the message.
- **messageSeq** (int) - The sequence number of the message.
- **messageSource** (String) - The source of the message.
- **sender** (GuildSender) - Information about the message sender.
- **time** (long) - The timestamp when the message was sent.

#### Response Example
```json
{
  "guildId": "12345",
  "channelId": "67890",
  "message": "Hello, world!",
  "messageId": "abcde",
  "messageSeq": 1,
  "messageSource": "user",
  "sender": {
    "tinyId": "user123",
    "nickname": "TestUser"
  },
  "time": 1678886400000
}
```
```

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

### Advanced Shiro Configuration (YAML)

Source: https://misakatat.github.io/shiro-docs/advanced

This YAML configuration file outlines advanced settings for Shiro, including plugin lists, interceptors, WebSocket client/server configurations, rate limiting, and task pool parameters. Most settings can be left as default unless specific optimizations are required.

```yaml
shiro:
  # 注解方式编写的插件无需在插件列表（plugin-list）定义
  # 插件列表为顺序执行，如果前一个插件返回了 MESSAGE_BLOCK 将不会执行后续插件
  plugin-list:
    - com.mikuac.example.plugins.PluginOne
    - com.mikuac.example.plugins.PluginTwo
  # 拦截器
  interceptor: com.mikuac.example.interceptor.InterceptorExample
  # WebSocket 配置
  ws:
    # 访问密钥，强烈推荐在公网的服务器设置
    access-token: ""
    # 超时回收，默认10秒
    timeout: 10
    # 最大文本消息缓冲区
    max-text-message-buffer-size: 512000
    # 二进制消息的最大长度
    max-binary-message-buffer-size: 512000
    client:
      # 是否启用
      enable: false
      url: "ws://websocket_server:port"
    server:
      # 是否启用
      enable: true
       # 反向 Websocket 连接地址，无需该配置字段可删除，将使用默认值 "/ws/shiro"
      url: "/ws/shiro"
      # 最大空闲时间，超过这个时间将关闭会话
      max-session-idle-timeout: 900000
  # 限速器（令牌桶算法）
  limiter:
    # 是否启用限速器
    enable: false
    # 补充速率（每秒补充的令牌数量）
    rate: 1
    # 令牌桶容量
    capacity: 1
    # 如果该值为 false 时，当令牌获取失败则会直接丢次本次请求
    # 如果该值为 true 时，当令牌获取失败则会阻塞当前线程，后续任务将被添加到等待队列
    awaitTask: true
    # 等待超时
    timeout: 10
  # 线程池配置
  task-pool:
    # 核心线程数（默认线程数）
    core-pool-size: 10
    # 缓冲队列大小
    queue-capacity: 200
    # 允许线程空闲时间（单位：默认为秒）
    keep-alive-time: 10
    # 最大线程数
    max-pool-size: 30
    # 线程池名前缀
    thread-name-prefix: "ShiroTaskPool-"

```

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

### Clients Structure

Source: https://misakatat.github.io/shiro-docs/types

Information about a client application or device.

```APIDOC
## Clients

### Description
Information about a client application or device.

### Fields
- **appId** (long) - Client application ID
- **deviceName** (String) - Device name
- **deviceKind** (String) - Device type
```

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

### Use Matcher for Regex Command Parsing in Java

Source: https://misakatat.github.io/shiro-docs/advanced

Demonstrates how to use the Matcher class with the @MessageHandlerFilter annotation to parse command parameters using regular expressions. This is useful for creating plugins that respond to specific command patterns and extract arguments from user input.

```java
@Shiro
@Component
public class ExamplePlugin {

    @GroupMessageHandler
    @MessageHandlerFilter(cmd = "开启|关闭")
    public void test1(Bot bot, GroupMessageEvent event, Matcher matcher) {
        String action = matcher.group();
        switch (action) {
            case "开启":
                System.out.println("开启事件触发");
                break;
            case "关闭":
                System.out.println("关闭事件触发");
                break;
            default:
        }
    }

    @GroupMessageHandler
    @MessageHandlerFilter(cmd = "^战绩查询\s(.*)?$")
    public void test2(Bot bot, GroupMessageEvent event, Matcher matcher) {
        String gameID = matcher.group(1);
        queryGameStats(gameID)
    }

}

```

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

### Client-side Forward WebSocket Configuration (YAML)

Source: https://misakatat.github.io/shiro-docs/index

This YAML configuration snippet enables and configures the Shiro SDK to connect as a WebSocket client for forward connections. It requires the URL of the WebSocket server.

```yaml
#该配置为正向连接示例
shiro:
  ws:
    client:
        enable: true
        url: "ws://websocket_server:port"
```

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

### Execute Custom API Requests with Parameters (Java)

Source: https://misakatat.github.io/shiro-docs/advanced

This Java code snippet shows how to initiate a custom API request using Shiro. It involves defining the target action via `CustomActionPath`, constructing request parameters in a `Map`, and then calling the `bot.customRequest` method to send the request.

```java
import java.util.HashMap;
import java.util.Map;

// 定义需要删除的好友账号
val friend = 12345678L;
// 获取 Endpoint
val action = CustomActionPath.DELETE_FRIEND;
// 构建请求参数
Map<String, Object> params = new HashMap<>() {
    {
        put("friend_id", friend);
    }
};
// 参考 Bot 类对响应结果进行处理
val result = bot.customRequest(action, params);

```

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

### Get Group Member Info

Source: https://misakatat.github.io/shiro-docs/action

Fetches detailed information about a specific member within a group, with an option to disable caching.

```APIDOC
## GET /getGroupMemberInfo

### Description
Retrieves detailed information about a specific member within a group. Caching can be disabled.

### Method
GET

### Endpoint
/getGroupMemberInfo

### Parameters
#### Query Parameters
- **groupId** (long) - Required - The ID of the group.
- **userId** (long) - Required - The ID of the member.
- **noCache** (boolean) - Optional - If `true`, disables the use of cached data.

### Response
#### Success Response (200)
- **Direct Return** (GroupMemberInfoResp) - Detailed information about the group member.
```

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

### Build Image Messages with Cache Disabled using OneBotMedia in Java

Source: https://misakatat.github.io/shiro-docs/advanced

Demonstrates how to use OneBotMedia to build an image message and specifically disable client-side caching using the `cache(false)` option. This allows for more control over how media is presented.

```java
// 该示例构建了一条图片消息，并且告诉客户端不要使用缓存
OneBotMedia img = OneBotMedia.builder().file("https://example.com/1.jpg").cache(false);
// 构建消息
String msg = MsgUtils.builder().img(img).build();

```

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

### Server-side Reverse WebSocket Configuration (YAML)

Source: https://misakatat.github.io/shiro-docs/index

This YAML configuration snippet enables and configures the Shiro SDK to act as a WebSocket server for reverse connections. It specifies the port and the WebSocket URL path.

```yaml
#该配置为反向连接示例
server:
  port: 5555

shiro:
  ws:
    server:
      enable: true
      url: "/ws/shiro"
```

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

### Get Group Honor Info

Source: https://misakatat.github.io/shiro-docs/action

Retrieves honor information for a group, such as 'king of the hill' or 'most active'. Can fetch specific types or all.

```APIDOC
## GET /getGroupHonorInfo

### Description
Retrieves various honorific titles and statistics for a group, such as the 'king of the hill' or 'most active' members.

### Method
GET

### Endpoint
/getGroupHonorInfo

### Parameters
#### Query Parameters
- **groupId** (long) - Required - The ID of the group.
- **type** (String) - Optional - The type of honor information to retrieve. Can be `talkative`, `performer`, `legend`, `strong_newbie`, `emotion`, or `all` (default).

### Response
#### Success Response (200)
- **groupId** (long) - The ID of the group.
- **currentTalkative** (CurrentTalkative) - Information about the current 'king of the hill'.
- **talkativeList** (List<OtherHonor>) - List of past 'kings of the hill'.
- **performerList** (List<OtherHonor>) - List of members with 'group chat performer' honor.
- **legendList** (List<OtherHonor>) - List of members with 'group chat legend' honor.
- **strongNewbieList** (List<OtherHonor>) - List of members with 'emerging talent' honor.
- **emotionList** (List<OtherHonor>) - List of members with 'source of joy' honor.
```

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

### Folders Structure

Source: https://misakatat.github.io/shiro-docs/types

Information about a folder, including its ID, name, creation details, and file count.

```APIDOC
## Folders

### Description
Information about a folder, including its ID, name, creation details, and file count.

### Fields
- **folderId** (String) - Folder ID
- **folderName** (String) - Folder name
- **createTime** (long) - Folder creation timestamp
- **creator** (long) - Creator's user ID
- **creatorName** (String) - Creator's name
- **totalFileCount** (int) - Total number of files in the folder
```

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

### Create Group File Folder (bot.createGroupFileFolder)

Source: https://misakatat.github.io/shiro-docs/action

Creates a new folder within a group's file storage. Requires groupId and the desired folderName.

```javascript
bot.createGroupFileFolder(groupId, folderName)
```

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

### Extending BotPlugin for Message Handling (Java)

Source: https://misakatat.github.io/shiro-docs/index

This Java code demonstrates creating a plugin by extending the `BotPlugin` class. It overrides `onPrivateMessage` and `onGroupMessage` to handle specific messages and control plugin execution flow.

```java
@Component
public class ExamplePlugin extends BotPlugin {

    @Override
    public int onPrivateMessage(Bot bot, PrivateMessageEvent event) {
        if ("hi".equals(event.getMessage())) {
            //构建消息
            String sendMsg = MsgUtils.builder()
                    .face(66)
                    .text("hello, this is shiro example plugin.")
                    .build();
            //发送私聊消息
            bot.sendPrivateMsg(event.getUserId(), sendMsg, false);
        }
        //返回 MESSAGE_IGNORE 执行 plugin-list 下一个插件，返回 MESSAGE_BLOCK 则不执行下一个插件
        return MESSAGE_IGNORE;
    }

    @Override
    public int onGroupMessage(Bot bot, GroupMessageEvent event) {
        if ("hi".equals(event.getMessage())) {
            //构建消息
            String sendMsg = MsgUtils.builder()
                    .at(event.getUserId())
                    .face(66)
                    .text("hello, this is shiro example plugin.")
                    .build();
            //发送群消息
            bot.sendGroupMsg(event.getGroupId(), sendMsg, false);
        }
        //返回 MESSAGE_IGNORE 执行 plugin-list 下一个插件，返回 MESSAGE_BLOCK 则不执行下一个插件
        return MESSAGE_IGNORE;
    }

}
```

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

### Files Structure

Source: https://misakatat.github.io/shiro-docs/types

Information about a file, including its ID, name, size, and upload details.

```APIDOC
## Files

### Description
Information about a file, including its ID, name, size, and upload details.

### Fields
- **fileId** (String) - File ID
- **fileName** (String) - File name
- **busId** (int) - File type identifier
- **fileSize** (long) - File size in bytes
- **uploadTime** (long) - File upload timestamp
- **deadTime** (long) - File expiration timestamp
- **modifyTime** (long) - File modification timestamp
- **downloadTimes** (int) - Number of downloads
- **uploader** (long) - Uploader's user ID
- **uploaderName** (String) - Uploader's name
```

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

### Get Guild Message

Source: https://misakatat.github.io/shiro-docs/action

Retrieves messages from a specific guild channel. It accepts a guild message ID and a flag to disable caching. The function returns detailed information about the message, including sender and timestamps.

```javascript
bot.getGuildMsg(guildMsgId, noCache)
```