@karinjs/adapter-qqbot 3.2.0 → 3.3.1

package/README.md

@@ -25,7 +25,6 @@ pnpm add @karinjs/adapter-qqbot
     "qqEnable": true,
     "guildEnable": true,
     "guildMode": 0,
-    "markdown": { "enable": true },
     "event": { "type": 2 }
   }
 ]
@@ -33,7 +32,14 @@ pnpm add @karinjs/adapter-qqbot
 
 - `event.type`: `0` 关闭、`1` Webhook、`2` WebSocket（默认）。
 - `guildMode`: `0` 公域，只收 @ 消息；`1` 私域，接收全部频道消息。
-- `markdown.enable`: 是否让普通文本和图片自动合并为 Markdown 消息，默认开启。关闭后普通图片会改为单独上传发送；插件显式传入的 `segment.markdown` 不受此开关影响。
+
+> 旧版本里的 `markdown.enable` 已移除。发送通道现在由平台能力决定，不再需要用户配置：
+> QQ 单聊和群聊的自定义 Markdown 已对所有机器人开放，固定走 Markdown 通道；频道场景仍需向 QQ
+> 申请内邀开通，适配器会先尝试 Markdown，被平台以权限错误拒绝后自动降级为普通消息，并记住这个
+> 机器人，本次运行内不再重试。开通后重启 Karin（或改一次配置）即可恢复。配置文件里残留的
+> `markdown` 字段会被忽略，下次保存配置时自动清除。
+>
+> 频道降级为普通消息后按钮无法发送——平台的 `keyboard` 只能挂在 Markdown 消息上。
 
 ## 按钮
 

package/dist/apps/cleanup.js

@@ -1,4 +1,4 @@
-import { t as getMessageStore } from "../message-CVJVFAGR.js";
+import { t as getMessageStore } from "../message-CydR-wrX.js";
 import karin from "node-karin";
 
 //#region src/apps/cleanup.ts

package/dist/apps/login.js

@@ -1,4 +1,4 @@
-import { i as getDefaultConfig, n as config, o as writeConfig } from "../config-D1_LqrcJ.js";
+import { i as getDefaultConfig, n as config, o as writeConfig } from "../config-BgCU6apn.js";
 import karin, { segment } from "node-karin";
 import qrcode from "qrcode";
 import axios from "node-karin/axios";

package/dist/apps/qqbot-file-to-url.js

@@ -1,4 +1,4 @@
-import { n as getImageSize } from "../common-OHGAoohl.js";
+import { n as getImageSize } from "../common-DwVsAvIo.js";
 import karin, { getAllBot } from "node-karin";
 
 //#region src/apps/qqbot-file-to-url.ts

package/dist/{common-OHGAoohl.js → common-DwVsAvIo.js}

@@ -11,6 +11,11 @@ const HTTP_URL_RE = /^https?:\/\//i;
 const BASE64_PREFIX_RE = /^base64:\/\//i;
 /** 标准 data URL 的 base64 前缀。 */
 const DATA_URL_BASE64_RE = /^data:[^;,]+;base64,/i;
+/**
+* 纯数字且 5-11 位：一定是 QQ 号/群号。
+* openid 是 32 位十六进制（或带连字符的 UUID 形态），不可能匹配此规则。
+*/
+const QQ_NUMBER_RE = /^\d{5,11}$/;
 
 //#endregion
 //#region src/utils/common.ts
@@ -39,4 +44,4 @@ const getImageSize = async (source) => {
 };
 
 //#endregion
-export { DATA_URL_BASE64_RE as a, BASE64_PREFIX_RE as i, getImageSize as n, HTTP_URL_RE as o, random as r, fakeEvent as t };
+export { DATA_URL_BASE64_RE as a, BASE64_PREFIX_RE as i, getImageSize as n, HTTP_URL_RE as o, random as r, QQ_NUMBER_RE as s, fakeEvent as t };

package/dist/{config-D1_LqrcJ.js → config-BgCU6apn.js}

@@ -80,19 +80,16 @@ const writeConfig = (data) => {
 	syncCache(normalized);
 };
 /**
-* 用默认值补齐用户配置
+* 用默认值补齐用户配置，并清理已废弃字段
 */
 const formatConfig = (user) => {
 	const def = getDefaultConfig()[0];
 	return user.map((item) => {
+		/** markdown 是历史字段，解构出来即丢弃，见 {@link LegacyQQBotConfig}。 */
 		const { markdown, messageCache, event, ...rest } = item;
 		return {
 			...def,
 			...rest,
-			markdown: {
-				...def.markdown,
-				...markdown
-			},
 			messageCache: normalizeMessageCache(def.messageCache, messageCache),
 			event: {
 				...def.event,
@@ -153,7 +150,6 @@ const getDefaultConfig = () => [{
 		reg: "^/",
 		rep: "#"
 	}],
-	markdown: { enable: true },
 	messageCache: {
 		enable: false,
 		self: false,

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 消息请求参数 */
@@ -308,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;
 }
@@ -676,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 {
   /** 群级禁言规则 */
@@ -724,7 +843,7 @@ interface JoinRequest {
 interface GetJoinRequestListParams {
   /** 分页游标，首次请求可不传或传空串 */
   cursor?: string;
-  /** 单页数量，默认 20，最大 100 */
+  /** 单页数量，默认 20，最大 50 */
   limit?: number;
 }
 /** 入群申请列表响应（GET /v2/groups/{group_openid}/join_request_list） */
@@ -745,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 */
@@ -770,7 +969,7 @@ interface JoinApprovalStrategy {
 interface GetJoinApprovalStrategyListParams {
   /** 分页游标，首次请求可不传或传空串 */
   cursor?: string;
-  /** 单页数量，默认 20，最大 100 */
+  /** 单页数量，默认 20，最大 50 */
   limit?: number;
 }
 /** 查询入群自动审批策略列表响应 */
@@ -1176,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 {
   /**
@@ -1192,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
@@ -1210,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}
@@ -1230,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>;
   /**
@@ -1404,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>;
   /**
@@ -1455,7 +1710,7 @@ declare class JoinApprovalApi extends Http {
  * - media：富媒体上传
  * - interaction：按钮回调 ack
  * - meta：@me / dms / gateway / 分享链接
- * - groups：群基础信息 / 机器人群内状态 / 禁言 / 入群申请（部分为白名单接口）
+ * - groups：群基础信息 / 机器人群内状态 / 群成员列表与详情 / 禁言 / 批量移除 / 群黑名单 / 入群申请（白名单接口）
  * - guilds：频道与子频道的查询和增删改
  * - menu：全局自定义菜单（仅单聊）
  * - panels：指令面板
@@ -1534,11 +1789,6 @@ interface QQBotConfig {
     reg: string | RegExp;
     rep: string;
   }[];
-  /** Markdown 通道 */
-  markdown: {
-    /** 是否启用 Markdown 通道发送消息 */
-    enable: boolean;
-  };
   /** 消息缓存配置 */
   messageCache: {
     /** 是否启用数据库消息缓存，用于 bot.getMsg */
@@ -1977,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 交互 */
@@ -2022,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;
@@ -2031,6 +2291,10 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   }>;
   /**
    * 获取头像 url
+   *
+   * 第三方头像 CDN 的模式是 `qqapp/{appId}/{openid}/{size}`，只有拼用户 openid 才有效；
+   * 机器人自身没有可用的 openid（selfId 就是 appId，拼出 appId/appid 只会得到默认头像），
+   * 因此目标是自己时改走官方 `GET /users/@me` 返回的 avatar 字段，取值与缓存见 self-avatar。
    */
   getAvatarUrl(_userId: string, _size?: 0 | 40 | 100 | 140): Promise<string>;
   /**
@@ -2079,6 +2343,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>;
   /**
@@ -2144,14 +2420,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>>;
   /**