add satori v3 api

package.json

@@ -11,8 +11,8 @@
     "build": "yarn mixin && cross-env NODE_OPTIONS=--max-old-space-size=8192 vitepress build ."
   },
   "devDependencies": {
-    "@koishijs/components": "^1.4.0",
-    "@koishijs/core": "^4.14.4",
+    "@koishijs/components": "^1.4.1",
+    "@koishijs/core": "^4.14.5",
     "@koishijs/market": "^4.1.4",
     "@koishijs/registry": "^6.0.4",
     "@koishijs/vitepress": "^3.0.0",
@@ -22,7 +22,7 @@
     "cross-env": "^7.0.3",
     "element-plus": "2.3.8",
     "esbuild-register": "^3.4.2",
-    "koishi": "^4.14.4",
+    "koishi": "^4.14.5",
     "marked-vue": "^1.2.3",
     "typescript": "^5.1.6",
     "vitepress": "1.0.0-rc.4",

zh-CN/about/upgrade.md

@@ -78,3 +78,22 @@ plugins:
 - 会话对象的属性 `locale` → `locales`
 
 用户无需留意这些改动，但开发者如果使用了上述 API 则需要进行迁移。
+
+## 协议更新 <badge>v4.14.5</badge>
+
+在 4.14.5 版本中，我们将协议库 satori 升级到了新的大版本。新版本引入了与分页 API 相关的不兼容更新。具体受影响的 API 如下：
+
+- `bot.getChannelList()`
+- `bot.getFriendList()`
+- `bot.getGuildList()`
+- `bot.getGuildMemberList()`
+- `bot.getGuildRoleList()`
+- `bot.getMessageList()`
+- `bot.getReactionList()`
+
+上述 API 将不再返回 `Promise<T[]>` 而是返回一个 `Promise<List<T>>`，包含 `data` 属性和可选的 `next` 属性。`data` 包含了当前页的数据，`next` 则表示下一页的分页令牌。此外，对于上述每一个 API，我们还额外提供了返回异步迭代器的版本：
+
+```ts
+for (const item of await bot.getChannelList())  // old
+for await (const item of bot.getChannelIter())  // new
+```

zh-CN/api/core/bot.md

@@ -148,13 +148,20 @@ export interface MessageInfo {
 
 修改特定消息。
 
-### bot.getMessageList(channelId, before?) <badge>实验性</badge>
+### bot.getMessageList(channelId, next?) <badge>实验性</badge>
 
 - **channelId:** `string` 频道 ID
-- **before:** `string` 消息 ID
+- **next:** `string` 分页令牌
 - 返回值: `Promise<List<Message>>` 消息列表
 
-获取机器人的好友列表。
+获取频道消息列表。
+
+### bot.getMessageIter(channelId) <badge>内置</badge> <badge>实验性</badge>
+
+- **channelId:** `string` 频道 ID
+- 返回值: `AsyncIterable<Message>` 迭代器
+
+获取频道消息的异步迭代器。
 
 ### bot.broadcast(channels, content, delay?) <badge>内置</badge>
 
@@ -195,15 +202,25 @@ export interface MessageInfo {
 
 从特定消息清除某个特定表态。如果没有传入表态名称则表示清除所有表态。
 
-### bot.getReactions(channelId, messageId, emoji) <badge type="warning">实验性</badge>
+### bot.getReactionList(channelId, messageId, emoji, next?) <badge type="warning">实验性</badge>
 
 - **channelId:** `string` 频道 ID
 - **messageId:** `string` 消息 ID
 - **emoji:** `string` 表态名称
-- 返回值: `Promise<User[]>`
+- **next:** `string` 分页令牌
+- 返回值: `Promise<List<User>>`
 
 获取添加特定消息的特定表态的用户列表。
 
+### bot.getReactionIter(channelId, messageId, emoji) <badge>内置</badge> <badge type="warning">实验性</badge>
+
+- **channelId:** `string` 频道 ID
+- **messageId:** `string` 消息 ID
+- **emoji:** `string` 表态名称
+- 返回值: `AsyncIterable<User>` 迭代器
+
+获取添加特定消息的特定表态的用户的异步迭代器。
+
 ## 获取数据
 
 ### bot.getSelf()
@@ -227,12 +244,19 @@ export interface UserInfo {
 
 获取用户信息。
 
-### bot.getFriendList() <badge>实验性</badge>
+### bot.getFriendList(next?) <badge>实验性</badge>
 
-- 返回值: `Promise<UserInfo[]>` 好友列表
+- **next:** `string` 分页令牌
+- 返回值: `Promise<List<UserInfo>>` 好友列表
 
 获取机器人的好友列表。
 
+### bot.getFriendIter() <badge>内置</badge> <badge>实验性</badge>
+
+- 返回值: `AsyncIterable<UserInfo>` 迭代器
+
+获取机器人的好友列表的异步迭代器。
+
 ### bot.getGuild(guildId)
 
 - **guildId:** `string` 群组 ID
@@ -247,12 +271,19 @@ export interface GuildInfo {
 }
 ```
 
-### bot.getGuildList() <badge>实验性</badge>
+### bot.getGuildList(next?) <badge>实验性</badge>
 
-- 返回值: `Promise<GuildInfo[]>` 群组列表
+- **next:** `string` 分页令牌
+- 返回值: `Promise<List<GuildInfo>>` 群组列表
 
 获取机器人加入的群组列表。
 
+### bot.getGuildIter() <badge>内置</badge> <badge>实验性</badge>
+
+- 返回值: `AsyncIterable<GuildInfo>` 迭代器
+
+获取机器人加入的群组列表的异步迭代器。
+
 ### bot.getGuildMember(guildId, userId)
 
 - **guildId:** `string` 群组 ID
@@ -274,13 +305,21 @@ export interface GuildMemberInfo extends UserInfo {
 }
 ```
 
-### bot.getGuildMemberList(guildId) <badge>实验性</badge>
+### bot.getGuildMemberList(guildId, next?) <badge>实验性</badge>
 
 - **guildId:** `string` 群组 ID
+- **next:** `string` 分页令牌
 - 返回值: `Promise<List<GuildMemberInfo>>` 群成员列表
 
 获取群成员列表。
 
+### bot.getGuildMemberIter(guildId) <badge>内置</badge> <badge>实验性</badge>
+
+- **guildId:** `string` 群组 ID
+- 返回值: `AsyncIterable<GuildMemberInfo>` 迭代器
+
+获取群成员列表的异步迭代器。
+
 ### bot.getChannel(channelId)
 
 - **channelId:** `string` 频道 ID
@@ -295,13 +334,21 @@ export interface ChannelInfo {
 }
 ```
 
-### bot.getChannelList(guildId) <badge>实验性</badge>
+### bot.getChannelList(guildId, next?) <badge>实验性</badge>
 
 - **guildId:** `string` 群组 ID
-- 返回值: `Promise<ChannelInfo[]>` 频道列表
+- **next:** `string` 分页令牌
+- 返回值: `Promise<List<ChannelInfo>>` 频道列表
 
 获取某个群组的频道列表。
 
+### bot.getChannelIter(guildId) <badge>内置</badge> <badge>实验性</badge>
+
+- **guildId:** `string` 群组 ID
+- 返回值: `AsyncIterable<ChannelInfo>` 迭代器
+
+获取某个群组的频道列表的异步迭代器。
+
 ## 群组管理
 
 ### bot.kickGuildMember(guildId, userId, permanent?)
@@ -341,13 +388,21 @@ export interface ChannelInfo {
 
 取消群组内用户的角色。
 
-### bot.getGuildRoles(guildId) <badge type="warning">实验性</badge>
+### bot.getGuildRoleList(guildId, next?) <badge type="warning">实验性</badge>
 
 - **guildId:** `string` 群组 ID
-- 返回值: `Promise<Role[]>` 角色列表
+- **next:** `string` 分页令牌
+- 返回值: `Promise<List<Role>>` 角色列表
 
 获取群组角色列表。
 
+### bot.getGuildRoleIter(guildId) <badge>内置</badge> <badge type="warning">实验性</badge>
+
+- **guildId:** `string` 群组 ID
+- 返回值: `AsyncIterable<Role>` 迭代器
+
+获取群组角色列表的异步迭代器。
+
 ### bot.createGuildRole(guildId, data) <badge type="warning">实验性</badge>
 
 - **guildId:** `string` 群组 ID

zh-CN/guide/adapter/bot.md

@@ -103,7 +103,7 @@ class DiscordBot extends Bot {
   // 获取群组列表
   async getGuildList() {
     const data = await this.internal.getCurrentUserGuilds()
-    return data.map(decodeGuild)
+    return { data: data.map(decodeGuild) }
   }
 }
 ```

zh-CN/guide/basic/element.md

@@ -142,7 +142,7 @@ h.image(buffer, 'image/png')
 <image url={'data:image/png;base64,' + buffer.toString('base64')}/>
 ```
 
-## 消息组件
+## 消息组件 <badge type="warning">实验性</badge>
 
 **消息组件 (Component)** 是一种对消息元素的扩展和封装。它允许你创建可重用的定制元素，并在渲染时引入自定义逻辑。例如，`<execute>` 组件会将其中的内容作为指令执行，并将执行结果替换该元素：