@karinjs/adapter-qqbot 3.1.0 → 3.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AdapterBase, AdapterType, Contact, CreateGroupFolderResponse, DownloadFileOptions, DownloadFileResponse, ElementTypes, ForwardOptions, GetAiCharactersResponse, GetAtAllCountResponse, GetGroupFileListResponse, GetGroupFileSystemInfoResponse, GetGroupHighlightsResponse, GetGroupMuteListResponse, GetRkeyResponse, GroupInfo, GroupMemberInfo, LogMethodNames, Message, MessageResponse, NodeElement, QQGroupHonorInfo, SendMsgResults, Sender, UserInfo, karinToQQBot } from "node-karin";
+import { AdapterBase, AdapterType, Contact, CreateGroupFolderResponse, DownloadFileOptions, DownloadFileResponse, ElementTypes, ForwardOptions, GetAiCharactersResponse, GetAtAllCountResponse, GetGroupFileListResponse, GetGroupFileSystemInfoResponse, GetGroupHighlightsResponse, GetGroupMuteListResponse, GetRkeyResponse, GroupInfo, GroupMemberInfo, LogMethodNames, Message, MessageResponse, NodeElement, QQGroupHonorInfo, SendMsgResults, Sender, UserInfo } from "node-karin";
 import { AxiosRequestConfig, AxiosResponse } from "node-karin/axios";
 import FormData from "form-data";
 //#region src/core/api/types.d.ts
@@ -26,7 +26,12 @@ interface QQMessageID {
   msg_id?: string;
   /** 回复消息的序号，与 msg_id 联合使用，避免相同消息id回复重复发送，不填默认是1。相同的 msg_id + msg_seq 重复发送会失败。 */
   msg_seq?: number;
-  /** 指明发送消息为互动召回消息，与 msg_id，event_id 互斥使用 */
+  /**
+   * 指明发送消息为互动召回消息，与 msg_id、event_id 互斥使用
+   *
+   * 接口文档 v1.28.0（2026-09-03）起该字段已从群消息发送接口移除，
+   * 目前仅单聊 `POST /v2/users/{user_openid}/messages` 可用。
+   */
   is_wakeup?: boolean;
   /** 引用消息对象，QQ单聊和群聊场景均支持 */
   message_reference?: MessageReference;
@@ -46,10 +51,101 @@ interface Markdown {
   /** markdown 文本 */
   content: string;
 }
+/** keyboard 按钮渲染（Button.render_data） */
+interface KeyboardButtonRenderData {
+  /** 按钮文字，最多 10 字符 */
+  label?: string;
+  /** 点击后文字，不传则保持不变 */
+  visited_label?: string;
+  /**
+   * 按钮样式
+   * - `0` 灰色线框
+   * - `1` 蓝色线框
+   * - `3` 白色背景 + 红色字体
+   * - `4` 蓝色背景 + 白色字体
+   *
+   * 接口文档 v1.28.0（2026-09-03）重定义了取值，旧文档中的 `2`（白字）已被移除。
+   */
+  style?: number;
+}
+/** keyboard 按钮点击权限（Button.action.permission） */
+interface KeyboardButtonPermission {
+  /** 0 指定用户可操作，1 仅管理者可操作，2 所有人可操作，3 指定身份组可操作（仅频道可用） */
+  type?: number;
+  /** 有权限的用户 id 的列表 */
+  specify_user_ids?: string[];
+  /** 有权限的身份组 id 的列表（仅频道可用） */
+  specify_role_ids?: string[];
+}
+/**
+ * 按钮二次确认（Button.action.modal）
+ *
+ * 接口文档 v1.28.0（2026-09-03）新增：点击按钮后先弹确认框，确认后才触发按钮行为。
+ */
+interface KeyboardButtonModal {
+  /** 二次确认的提示文本，不为空则进行二次确认；最多 40 个字符，不能有 URL */
+  content?: string;
+  /** 确认按钮上展示的文字，可为空，默认「确认」；最多 4 个字符 */
+  confirm_text?: string;
+  /** 取消按钮上展示的文字，可为空，默认「取消」；最多 4 个字符 */
+  cancel_text?: string;
+}
+/** keyboard 按钮点击行为（Button.action） */
+interface KeyboardButtonAction {
+  /** 0 跳转按钮（http / 小程序 scheme），1 回调按钮（回调后台接口），2 指令按钮（在输入框插入 @bot data） */
+  type?: number;
+  /** 权限设置 */
+  permission?: KeyboardButtonPermission;
+  /** 操作相关的数据 */
+  data?: string;
+  /** 客户端不支持本 action 的时候，弹出的 toast 文案 */
+  unsupport_tips?: string;
+  /** 指令按钮可用，点击按钮后直接自动发送 data，仅单聊可用，默认 false（支持版本 8983） */
+  enter?: boolean;
+  /** 指令按钮可用，指令是否带引用回复本消息，默认 false（支持版本 8983） */
+  reply?: boolean;
+  /**
+   * 仅在指令按钮下有效，设置后会忽略 `enter` 配置。
+   * 设为 1 时点击按钮自动唤起手 Q 选图器（仅手机端 8983+ 的单聊场景）。
+   */
+  anchor?: number;
+  /** 用户点击后的二次确认操作 */
+  modal?: KeyboardButtonModal;
+  /** @deprecated 官方已弃用：可操作点击的次数 */
+  click_limit?: number;
+  /** @deprecated 官方已弃用：指令按钮弹出子频道选择器 */
+  at_bot_show_channel_list?: boolean;
+}
+/**
+ * keyboard 按钮（Button）
+ *
+ * 字段与官方文档一致，并且是 node-karin `QQBotButton` 的结构超集，
+ * 因此 `karinToQQBot()` 的输出可以直接放进 {@link Keyboard}。
+ */
+interface KeyboardButton {
+  /** 按钮 ID，同一键盘内唯一 */
+  id?: string;
+  /** 按钮渲染 */
+  render_data?: KeyboardButtonRenderData;
+  /** 按钮点击行为 */
+  action?: KeyboardButtonAction;
+  /**
+   * 分组 ID，同一分组内有一个按钮被操作后，其它按钮变灰不可点击
+   *
+   * 接口文档 v1.28.0（2026-09-03）新增，仅当 `action.type = 1` 时有效。
+   */
+  group_id?: string;
+}
+/** keyboard 一行按钮 */
+interface KeyboardRow {
+  /** 该行的按钮，官方限制每行最多 5 个 */
+  buttons: KeyboardButton[];
+}
 /** 按钮消息结构（官方已全量开放自定义 keyboard，2.0 不再支持模板按钮） */
 interface Keyboard {
+  /** 键盘内容，官方限制最多 5 行 */
   content: {
-    rows: ReturnType<typeof karinToQQBot>;
+    rows: KeyboardRow[];
   };
 }
 /** 发送QQ Markdown 消息请求参数 */
@@ -89,6 +185,18 @@ interface SendQQMediaMessageRequest extends SendQQMessageRequest, QQMessageID {
     /** 文件信息，用于发消息接口的 media 字段使用 */
     file_info: string;
   };
+  /**
+   * 按钮。
+   *
+   * `keyboard` 在官方发消息接口中是与 `content` / `markdown` / `media` 平级的独立字段，
+   * 文档未声明它与 `media` 互斥（互斥约束只写在 `content` / `markdown` / `ark` 之间），
+   * 接口说明也写明「支持文本/Markdown/富媒体等类型，可附带内嵌键盘」。
+   *
+   * 用于图片走 QQ 上传兜底（无法进入 markdown）时，让按钮随富媒体一起发出，
+   * 避免额外产生一条只有按钮的空消息。若平台拒绝（305007），发送层会去掉
+   * keyboard 重试一次，保证富媒体本身能送达。
+   */
+  keyboard?: Keyboard;
 }
 /** 发送QQ流式消息请求参数（POST /v2/users/{openid}/stream_messages，仅单聊） */
 interface SendQQStreamMessageRequest {
@@ -296,19 +404,29 @@ interface GroupBotStateResponse {
 /**
  * 获取群成员详情接口响应（GET /v2/groups/{group_openid}/members/{member_openid}）
  *
- * 该接口未出现在公开文档中，仅在腾讯官方 openclaw 插件
- * （@tencent-connect/openclaw-qqbot v2.0.0）中被作为一等接口使用，返回结构未公开，
- * 字段全部按可选处理，实际以平台返回为准。
+ * 该接口在接口文档 v1.28.0（2026-09-03）转为公开文档，属「内邀接入」的白名单接口，
+ * 未获权限时平台返回错误码 11253。官方昵称字段为 `username`，`nick` 是转公开之前
+ * 腾讯官方 openclaw 插件（@tencent-connect/openclaw-qqbot v2.0.0）使用的字段名，
+ * 保留以兼容旧返回。
  */
 interface QQGroupMemberResponse {
   /** 群成员 openid */
   member_openid?: string;
-  /** 群成员昵称 */
+  /** 用户昵称 */
+  username?: string;
+  /**
+   * 群成员昵称
+   * @deprecated 官方公开文档中的字段名是 {@link QQGroupMemberResponse.username}
+   */
   nick?: string;
   /** 入群时间，RFC3339 格式 */
   joined_at?: string;
   /** 群内角色：owner / admin / member */
   member_role?: 'owner' | 'admin' | 'member';
+  /** 是否机器人 */
+  bot?: boolean;
+  /** 用户在应用/开放平台下的统一标识（如有） */
+  union_openid?: string;
   /** 其余未公开字段原样保留 */
   [key: string]: unknown;
 }
@@ -329,6 +447,16 @@ interface UploadMediaResponse {
   ttl: number;
   /** 发送消息的唯一ID，当srv_send_msg设置为true时返回 */
   id: string;
+  /**
+   * 文件下载链接（COS 预签名 GET URL），有效期与 `ttl` 一致。
+   *
+   * 仅分片上传合并（走 `upload_id` 路径）且 `file_type` 为图片/视频/语音时返回；
+   * URL 直传和文件类型（`file_type=4`）不返回该字段。
+   *
+   * 这是把 QQ 分片上传当图床用的关键：拿到该直链后，图片就能以 markdown
+   * 图片语法嵌入 msg_type=2，不必再走 msg_type=7 富媒体单独发送。
+   */
+  raw_url?: string;
 }
 /** 自定义菜单按钮类型 */
 type MenuItemType = 'switch' | 'send_message' | 'link' | 'menu';
@@ -654,6 +782,19 @@ interface MemberMuteState {
   /** 用户在应用/开放平台下的统一标识 */
   union_openid?: string;
 }
+/**
+ * 设置成员禁言项（POST /v2/groups/{group_openid}/restrict_chat_setting）
+ *
+ * 单次请求最多 20 项（接口文档 v1.28.0 由 10 提升至 20）。
+ */
+interface SetMemberMuteState {
+  /** 操作类型：add 增加禁言，update 更新禁言到期时间，del 解除禁言 */
+  op: 'add' | 'update' | 'del';
+  /** 被禁言成员的 openid；增加 / 更新时只能操作普通成员，不能操作群主、管理员、机器人 */
+  member_openid: string;
+  /** 禁言到期时间（RFC3339 格式）；op=del 时可传空串表示立即解除禁言 */
+  mute_expire_at?: string;
+}
 /** 查询群禁言状态响应（GET /v2/groups/{group_openid}/restrict_chat_setting） */
 interface GetGroupMuteSettingResponse {
   /** 群级禁言规则 */
@@ -702,7 +843,7 @@ interface JoinRequest {
 interface GetJoinRequestListParams {
   /** 分页游标，首次请求可不传或传空串 */
   cursor?: string;
-  /** 单页数量，默认 20，最大 100 */
+  /** 单页数量，默认 20，最大 50 */
   limit?: number;
 }
 /** 入群申请列表响应（GET /v2/groups/{group_openid}/join_request_list） */
@@ -723,6 +864,86 @@ interface ApprovalJoinRequestBody {
   /** 是否同时加入群黑名单，默认 false，op=decline 时可填 */
   add_to_member_blacklist?: boolean;
 }
+/** 群成员（GET /v2/groups/{group_openid}/members 列表项） */
+interface GroupMemberItem {
+  /** 成员 openid */
+  member_openid: string;
+  /** 用户昵称 */
+  username?: string;
+  /** 群成员角色：member 普通成员 / owner 群主 / admin 管理员 */
+  member_role?: 'owner' | 'admin' | 'member';
+  /** 是否机器人 */
+  bot?: boolean;
+  /** 入群时间戳（RFC3339 格式） */
+  joined_at?: string;
+  /** 用户在应用/开放平台下的统一标识（如有） */
+  union_openid?: string;
+}
+/** 群成员列表查询参数（GET /v2/groups/{group_openid}/members） */
+interface GetGroupMemberListParams {
+  /** 分页游标，首次请求可不传或传空串；后续传上一次响应的 next_cursor */
+  cursor?: string;
+}
+/** 群成员列表响应（GET /v2/groups/{group_openid}/members） */
+interface GetGroupMemberListResponse {
+  /** 成员列表，每次最多返回 30 条 */
+  members: GroupMemberItem[];
+  /** 下一页游标，空串表示已到末页 */
+  next_cursor: string;
+}
+/** 群成员批量移除请求体（POST /v2/groups/{group_openid}/batch_remove_members） */
+interface BatchRemoveGroupMembersBody {
+  /** 需要移除的成员 member_openid 列表，单次最多 20 个 */
+  member_openids: string[];
+  /** 是否同时加入群黑名单，默认 false */
+  add_to_member_blacklist?: boolean;
+}
+/** 群成员批量移除响应 */
+interface BatchRemoveGroupMembersResponse {
+  /** 成功时返回 success */
+  remove_members_result?: string;
+  /** 拉黑失败的 openid */
+  add_to_member_blacklist_fail_openids?: string[];
+}
+/** 群黑名单用户（GET /v2/groups/{group_openid}/member_blacklist 列表项） */
+interface GroupBlacklistUser {
+  /** 用户在应用/开放平台下的统一标识（如有） */
+  union_openid?: string;
+  /** 用户 openid */
+  member_openid: string;
+  /** 用户昵称 */
+  username?: string;
+  /** 拉黑时间戳（RFC3339 格式） */
+  banned_at?: string;
+  /** 是否为机器人账号 */
+  bot?: boolean;
+}
+/** 群黑名单查询参数（GET /v2/groups/{group_openid}/member_blacklist） */
+interface GetGroupMemberBlacklistParams {
+  /** 分页游标，首次请求可不传或传空串 */
+  cursor?: string;
+  /** 单页数量，默认 20，最大 100 */
+  limit?: number;
+}
+/** 群黑名单查询响应（GET /v2/groups/{group_openid}/member_blacklist） */
+interface GetGroupMemberBlacklistResponse {
+  /** 黑名单用户列表 */
+  users: GroupBlacklistUser[];
+  /** 下一页游标，空串表示已到末页 */
+  next_cursor: string;
+}
+/** 群黑名单操作请求体（POST /v2/groups/{group_openid}/member_blacklist） */
+interface SetGroupMemberBlacklistBody {
+  /** 操作类型：add 加入黑名单（目标成员在群中时无法加入），del 移出黑名单 */
+  op: 'add' | 'del';
+  /** 目标成员 openid 列表，单次最多 20 个 */
+  member_openids: string[];
+}
+/** 群黑名单操作响应 */
+interface SetGroupMemberBlacklistResponse {
+  /** 操作失败的 openid 列表，op=add / op=del 同义 */
+  fail_openids?: string[];
+}
 /** 入群自动审批策略 */
 interface JoinApprovalStrategy {
   /** 策略 ID */
@@ -748,7 +969,7 @@ interface JoinApprovalStrategy {
 interface GetJoinApprovalStrategyListParams {
   /** 分页游标，首次请求可不传或传空串 */
   cursor?: string;
-  /** 单页数量，默认 20，最大 100 */
+  /** 单页数量，默认 20，最大 50 */
   limit?: number;
 }
 /** 查询入群自动审批策略列表响应 */
@@ -1046,6 +1267,29 @@ declare class MediaApi extends Http {
    * @returns 上传结果，包含后续发送消息所需的 file_info
    */
   uploadFallback(scene: Scene, peer: string, type: MediaType, source: string, srvSendMsg?: boolean, fileName?: string): Promise<UploadMediaResponse>;
+  /**
+   * 上传资源并取回它的公网直链。
+   *
+   * 分片上传的合并响应里带 `raw_url`，等价于一个临时图床：拿到地址后图片就能以
+   * markdown 图片语法嵌进 msg_type=2，和文本、按钮合成一条消息，不必退化成
+   * 独立的 msg_type=7 富媒体消息。
+   *
+   * 与 `uploadFallback` 的差别只有一处：那边按体积决定是否分片，目标是拿
+   * `file_info`；这里必须无条件分片，否则服务端不会给出 `raw_url`。
+   *
+   * 直链的存活时间等于响应里的 `ttl`，属于临时地址，只适合当次发送使用。
+   *
+   * @param scene user(单聊) / group(群聊)
+   * @param peer openid 或 group_openid，决定上传归属的会话
+   * @param type 文件类型；`file` 无直链可取
+   * @param source 本地路径、http url、data URL、base64:// 或裸 base64
+   * @param fileName 文件名，同时用于推断直链声明的 MIME
+   * @returns 可直接嵌入消息的直链，以及原始上传响应
+   */
+  uploadForUrl(scene: Scene, peer: string, type: MediaType, source: string, fileName?: string): Promise<{
+    url: string;
+    response: UploadMediaResponse;
+  }>;
   /**
    * 确认单个分片已完成上传。
    *
@@ -1131,10 +1375,12 @@ declare class MetaApi extends Http {
 //#endregion
 //#region src/core/api/groups.d.ts
 /**
- * QQ 群信息接口
+ * QQ 群信息与群成员管理接口
  *
  * 注意：以下接口均为白名单接口，未开通权限时平台返回错误码 11253，
- * 需要向平台运营申请后可用。
+ * 需要向平台运营申请后可用。接口文档 v1.28.0（2026-09-03）新增的群成员管理
+ * 接口（成员列表 / 批量移除 / 黑名单）官方标注为「正在内邀接入中」，
+ * 开放范围可能比其它白名单接口更窄。
  */
 declare class GroupsApi extends Http {
   /**
@@ -1147,17 +1393,58 @@ declare class GroupsApi extends Http {
    * @param groupOpenid 群 openid
    */
   getBotState(groupOpenid: string): Promise<GroupBotStateResponse>;
+  /**
+   * 获取群成员列表
+   *
+   * 每次最多返回 30 条，只支持 cursor 翻页：首次不传 `cursor`，之后回传上一次
+   * 响应的 `next_cursor`，`next_cursor` 为空串表示已到末页。
+   *
+   * @param groupOpenid 群 openid
+   * @param params 分页参数
+   */
+  getGroupMemberList(groupOpenid: string, params?: GetGroupMemberListParams): Promise<GetGroupMemberListResponse>;
   /**
    * 获取群成员详情
    *
+   * 昵称字段为 `username`；`nick` 是该接口转为公开文档之前的字段名，仅作兼容。
+   *
    * @param groupOpenid 群 openid
    * @param memberOpenid 群成员 openid
    */
   getGroupMember(groupOpenid: string, memberOpenid: string): Promise<QQGroupMemberResponse>;
+  /**
+   * 群成员批量移除
+   *
+   * 单次最多 20 个成员，可通过 `add_to_member_blacklist` 在移除的同时拉黑。
+   * 机器人需拥有群管理员身份。
+   *
+   * @param groupOpenid 群 openid
+   * @param body 待移除的成员列表与是否同时拉黑
+   */
+  batchRemoveGroupMembers(groupOpenid: string, body: BatchRemoveGroupMembersBody): Promise<BatchRemoveGroupMembersResponse>;
+  /**
+   * 查询群黑名单
+   *
+   * @param groupOpenid 群 openid
+   * @param params 分页参数，`limit` 默认 20、最大 100
+   */
+  getGroupMemberBlacklist(groupOpenid: string, params?: GetGroupMemberBlacklistParams): Promise<GetGroupMemberBlacklistResponse>;
+  /**
+   * 群黑名单操作
+   *
+   * 只有目标用户不在群中时才能加入黑名单，需要先移除再拉黑；单次最多 20 个。
+   * 返回的 `fail_openids` 在 `op=add` / `op=del` 下同义，都是操作失败的 openid。
+   *
+   * @param groupOpenid 群 openid
+   * @param body 操作类型与目标成员列表
+   */
+  setGroupMemberBlacklist(groupOpenid: string, body: SetGroupMemberBlacklistBody): Promise<SetGroupMemberBlacklistResponse>;
   /**
    * 设置群成员禁言
    *
-   * 机器人需拥有群管理员身份，平台限制最大禁言时长为 30 天。
+   * 机器人需拥有群管理员身份，平台限制最大禁言时长为 30 天；
+   * 只能操作普通成员，不能操作群主、管理员与机器人。
+   * 需要一次设置多个成员时用 {@link GroupsApi.setGroupMuteBatch}。
    *
    * @param groupOpenid 群 openid
    * @param memberOpenid 群成员 openid
@@ -1165,6 +1452,17 @@ declare class GroupsApi extends Http {
    * @param duration 禁言时间使用RFC3339 格式
    */
   setGroupMute(groupOpenid: string, memberOpenid: string, op: 'add' | 'update' | 'del', duration: string): Promise<{}>;
+  /**
+   * 批量设置群成员禁言
+   *
+   * 每项通过自身的 `op` 控制增 / 改 / 删，可以在一次请求里混用。
+   * 平台限制单次最多 20 个成员（接口文档 v1.28.0 由 10 提升至 20），
+   * 超出时平台会直接拒绝整个请求。
+   *
+   * @param groupOpenid 群 openid
+   * @param members 成员禁言设置列表
+   */
+  setGroupMuteBatch(groupOpenid: string, members: SetMemberMuteState[]): Promise<{}>;
   /**
    * 设置群成员禁言
    * @deprecated 方法名拼写错误，请使用 {@link GroupsApi.setGroupMute}
@@ -1185,7 +1483,8 @@ declare class GroupsApi extends Http {
    * 机器人需拥有群管理员身份。
    *
    * @param groupOpenid 群 openid
-   * @param params 分页参数，`limit` 默认 20、最大 100
+   * @param params 分页参数，`limit` 默认 20、最大 50（接口文档 v1.28.0 由 100 下调），
+   * 传入更大的值会被收敛到 50，避免平台直接拒绝
    */
   getJoinRequestList(groupOpenid: string, params?: GetJoinRequestListParams): Promise<GetJoinRequestListResponse>;
   /**
@@ -1359,7 +1658,8 @@ declare class JoinApprovalApi extends Http {
    * 查询入群自动审批策略列表
    *
    * 按创建时间倒序，支持分页。
-   * @param params 分页参数，`limit` 默认 20、最大 100
+   * @param params 分页参数，`limit` 默认 20、最大 50（接口文档 v1.28.0 由 100 下调），
+   * 传入更大的值会被收敛到 50，避免平台直接拒绝
    */
   getStrategyList(params?: GetJoinApprovalStrategyListParams): Promise<GetJoinApprovalStrategyListResponse>;
   /**
@@ -1410,7 +1710,7 @@ declare class JoinApprovalApi extends Http {
  * - media：富媒体上传
  * - interaction：按钮回调 ack
  * - meta：@me / dms / gateway / 分享链接
- * - groups：群基础信息 / 机器人群内状态 / 禁言 / 入群申请（部分为白名单接口）
+ * - groups：群基础信息 / 机器人群内状态 / 群成员列表与详情 / 禁言 / 批量移除 / 群黑名单 / 入群申请（白名单接口）
  * - guilds：频道与子频道的查询和增删改
  * - menu：全局自定义菜单（仅单聊）
  * - panels：指令面板
@@ -1449,7 +1749,7 @@ declare class QQBotApi {
     text(content: string): SendQQTextMessageRequest;
     markdown(markdown: Markdown, keyboard?: Keyboard): SendQQMarkdownMessageRequest;
     ark(ark: SendQQArkMessageRequest["ark"]): SendQQArkMessageRequest;
-    media(fileInfo: string): SendQQMediaMessageRequest;
+    media(fileInfo: string, keyboard?: Keyboard): SendQQMediaMessageRequest;
   };
   readonly guild: {
     text(content: string, image?: string): SendGuildTextMessageRequest;
@@ -1489,11 +1789,6 @@ interface QQBotConfig {
     reg: string | RegExp;
     rep: string;
   }[];
-  /** Markdown 通道 */
-  markdown: {
-    /** 是否启用 Markdown 通道发送消息 */
-    enable: boolean;
-  };
   /** 消息缓存配置 */
   messageCache: {
     /** 是否启用数据库消息缓存，用于 bot.getMsg */
@@ -1932,8 +2227,10 @@ declare class MessageStore {
 /**
  * QQ Official Bot 适配器
  *
- * 全场景统一走 msg_type=2 Markdown 通道（详见 pipeline-qq / pipeline-guild）。
- * 视频 / 语音 / 文件由 pipeline 内部以 msg_type=7 紧随主消息补发。
+ * 发送通道由平台能力决定，没有对应的用户配置项：QQ 单聊 / 群聊的自定义 Markdown
+ * 已对所有机器人开放，固定走 msg_type=2；频道场景仍需内邀开通，先乐观尝试
+ * Markdown，被拒后自动降级为普通消息（详见 pipeline-qq / pipeline-guild 与
+ * guild-markdown）。视频 / 语音 / 文件由 pipeline 内部以 msg_type=7 紧随主消息补发。
  */
 declare class AdapterQQBot extends AdapterBase implements AdapterType {
   /** 与官方 API 交互 */
@@ -1977,8 +2274,16 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   /**
    * 发送合并转发消息
    *
-   * 将 NodeElement 拆解为文本 + 图片等元素，拼接成 markdown 发送。
-   * 节点之间仅用换行隔开，不添加任何前缀提示文本。
+   * QQ 官方没有合并转发能力，这里把各节点摊平成一段 Markdown 正文，节点之间用
+   * 强制换行隔开，不添加任何前缀提示文本。
+   *
+   * 图片以 markdown 图片语法写入，**保留原始来源**（本地路径 / base64 / URL）：
+   * 究竟走内置图床、第三方 fileToUrl，还是降级成 msg_type=7 富媒体，由发送
+   * pipeline 统一决定。这里不自己上传，也不自己判断通道——否则频道场景在没有
+   * Markdown 权限时会绕过降级逻辑，直接被平台拒掉。
+   *
+   * 视频 / 语音 / 文件进不了 markdown，作为普通消息段跟随主消息一起交给 pipeline，
+   * 由它在同一次发送里以 msg_type=7 补发。
    */
   sendForwardMsg(contact: Contact, elements: Array<NodeElement>, _options?: ForwardOptions): Promise<{
     messageId: string;
@@ -2034,6 +2339,18 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   sendLike(_targetId: string, _count: number): Promise<void>;
   /**
    * 群踢人
+   *
+   * 走官方 `POST /v2/groups/{group_openid}/batch_remove_members`，机器人需拥有群
+   * 管理员身份。Karin 的 `rejectAddRequest` 映射为官方的 `add_to_member_blacklist`：
+   * 移除的同时拉入群黑名单，该用户之后无法再次入群。官方接口没有踢人理由字段，
+   * `kickReason` 只会被记录到日志。
+   *
+   * 需要一次移除多人时用 `bot.super.groups.batchRemoveGroupMembers()`，单次最多 20 个。
+   *
+   * @param _groupId 群 openid
+   * @param _targetId 群成员 openid
+   * @param _rejectAddRequest 是否同时拉入群黑名单，默认 false
+   * @param _kickReason 官方不支持，仅在传入时输出提示
    */
   groupKickMember(_groupId: string, _targetId: string, _rejectAddRequest?: boolean, _kickReason?: string): Promise<void>;
   /**
@@ -2099,14 +2416,25 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   /**
    * 获取群成员信息
    *
-   * - 查询机器人自身（targetId 为 selfId）走官方 `GET /v2/groups/{group_openid}/bot_state`（白名单）。
-   * - 查询其他成员走 `GET /v2/groups/{group_openid}/members/{member_openid}`，
-   *   该接口未公开文档，来自腾讯官方 openclaw 插件 v2.0.0，返回结构以平台实际为准。
-   * 接口不可用（如白名单未开通返回 11253）时降级为占位结构并告警。
+   * - 查询机器人自身（targetId 为 selfId）走官方 `GET /v2/groups/{group_openid}/bot_state`。
+   * - 查询其他成员走 `GET /v2/groups/{group_openid}/members/{member_openid}`，该接口在
+   *   接口文档 v1.28.0（2026-09-03）转为公开文档，昵称字段为 `username`，`nick` 是
+   *   转公开之前的字段名，仅作兼容回退。
+   *
+   * 两者都是白名单接口，未开通权限（11253）或查询失败时降级为占位结构并告警。
    */
   getGroupMemberInfo(_groupId: string, _targetId: string, _refresh?: boolean): Promise<GroupMemberInfo>;
   /**
    * 获取群成员列表
+   *
+   * 走官方 `GET /v2/groups/{group_openid}/members`（白名单接口），每页最多 30 条，
+   * 这里按 `next_cursor` 自动翻完所有页；顺便把昵称写入
+   * {@link AdapterQQBot.nicknameCache}，让后续消息事件能直接取到昵称。
+   *
+   * 为防止平台返回的游标不收敛，翻页数有安全上限（约 6000 人），触顶会告警并返回已取到的部分。
+   * 未开通权限（11253）或查询失败时返回已取到的部分并告警。
+   *
+   * @param _groupId 群 openid
    */
   getGroupMemberList(_groupId: string, _refresh?: boolean): Promise<Array<GroupMemberInfo>>;
   /**