@karinjs/adapter-qqbot 3.2.0 → 3.3.0

package/dist/index.js

@@ -1,8 +1,8 @@
-import { l as basename, n as config, r as getConfig, s as pkg, t as bindHandlers } from "./config-D1_LqrcJ.js";
+import { l as basename, n as config, r as getConfig, s as pkg, t as bindHandlers } from "./config-BgCU6apn.js";
 import { t as log } from "./logger-sza6kuy3.js";
-import { a as DATA_URL_BASE64_RE, i as BASE64_PREFIX_RE, n as getImageSize, o as HTTP_URL_RE, r as random, t as fakeEvent } from "./common-OHGAoohl.js";
-import "./utils-C0oZi6PR.js";
-import { t as getMessageStore } from "./message-CVJVFAGR.js";
+import { a as DATA_URL_BASE64_RE, i as BASE64_PREFIX_RE, n as getImageSize, o as HTTP_URL_RE, r as random, s as QQ_NUMBER_RE, t as fakeEvent } from "./common-DwVsAvIo.js";
+import "./utils-u17tvC2U.js";
+import { t as getMessageStore } from "./message-CydR-wrX.js";
 import karin, { AdapterBase, app, buttonHandle, common, createDirectMessage, createFriendDecreaseNotice, createFriendIncreaseNotice, createFriendMessage, createGroupApplyRequest, createGroupInviteRequest, createGroupMemberAddNotice, createGroupMemberDelNotice, createGroupMessage, createGuildMessage, fileToUrl, fileToUrlHandlerKey, getMimeType, handler, karin as karin$1, karinToQQBot, logger, registerBot, segment, senderGroup, unregisterBot } from "node-karin";
 import { URL as URL$1 } from "url";
 import lodash from "node-karin/lodash";
@@ -1460,10 +1460,12 @@ var MetaApi = class extends Http {
 //#endregion
 //#region src/core/api/groups.ts
 /**
-* QQ 群信息接口
+* QQ 群信息与群成员管理接口
 *
 * 注意：以下接口均为白名单接口，未开通权限时平台返回错误码 11253，
-* 需要向平台运营申请后可用。
+* 需要向平台运营申请后可用。接口文档 v1.28.0（2026-09-03）新增的群成员管理
+* 接口（成员列表 / 批量移除 / 黑名单）官方标注为「正在内邀接入中」，
+* 开放范围可能比其它白名单接口更窄。
 */
 var GroupsApi = class extends Http {
 	/**
@@ -1481,8 +1483,25 @@ var GroupsApi = class extends Http {
 		return this.get(`/v2/groups/${groupOpenid}/bot_state`);
 	}
 	/**
+	* 获取群成员列表
+	*
+	* 每次最多返回 30 条，只支持 cursor 翻页：首次不传 `cursor`，之后回传上一次
+	* 响应的 `next_cursor`，`next_cursor` 为空串表示已到末页。
+	*
+	* @param groupOpenid 群 openid
+	* @param params 分页参数
+	*/
+	getGroupMemberList(groupOpenid, params = {}) {
+		const query = new URLSearchParams();
+		if (params.cursor) query.set("cursor", params.cursor);
+		const search = query.toString();
+		return this.get(`/v2/groups/${groupOpenid}/members${search ? `?${search}` : ""}`);
+	}
+	/**
 	* 获取群成员详情
 	*
+	* 昵称字段为 `username`；`nick` 是该接口转为公开文档之前的字段名，仅作兼容。
+	*
 	* @param groupOpenid 群 openid
 	* @param memberOpenid 群成员 openid
 	*/
@@ -1490,9 +1509,48 @@ var GroupsApi = class extends Http {
 		return this.get(`/v2/groups/${groupOpenid}/members/${memberOpenid}`);
 	}
 	/**
+	* 群成员批量移除
+	*
+	* 单次最多 20 个成员，可通过 `add_to_member_blacklist` 在移除的同时拉黑。
+	* 机器人需拥有群管理员身份。
+	*
+	* @param groupOpenid 群 openid
+	* @param body 待移除的成员列表与是否同时拉黑
+	*/
+	batchRemoveGroupMembers(groupOpenid, body) {
+		return this.post(`/v2/groups/${groupOpenid}/batch_remove_members`, body);
+	}
+	/**
+	* 查询群黑名单
+	*
+	* @param groupOpenid 群 openid
+	* @param params 分页参数，`limit` 默认 20、最大 100
+	*/
+	getGroupMemberBlacklist(groupOpenid, params = {}) {
+		const query = new URLSearchParams();
+		if (params.cursor) query.set("cursor", params.cursor);
+		if (params.limit !== void 0) query.set("limit", String(params.limit));
+		const search = query.toString();
+		return this.get(`/v2/groups/${groupOpenid}/member_blacklist${search ? `?${search}` : ""}`);
+	}
+	/**
+	* 群黑名单操作
+	*
+	* 只有目标用户不在群中时才能加入黑名单，需要先移除再拉黑；单次最多 20 个。
+	* 返回的 `fail_openids` 在 `op=add` / `op=del` 下同义，都是操作失败的 openid。
+	*
+	* @param groupOpenid 群 openid
+	* @param body 操作类型与目标成员列表
+	*/
+	setGroupMemberBlacklist(groupOpenid, body) {
+		return this.post(`/v2/groups/${groupOpenid}/member_blacklist`, body);
+	}
+	/**
 	* 设置群成员禁言
 	*
-	* 机器人需拥有群管理员身份，平台限制最大禁言时长为 30 天。
+	* 机器人需拥有群管理员身份，平台限制最大禁言时长为 30 天；
+	* 只能操作普通成员，不能操作群主、管理员与机器人。
+	* 需要一次设置多个成员时用 {@link GroupsApi.setGroupMuteBatch}。
 	*
 	* @param groupOpenid 群 openid
 	* @param memberOpenid 群成员 openid
@@ -1500,11 +1558,24 @@ var GroupsApi = class extends Http {
 	* @param duration 禁言时间使用RFC3339 格式
 	*/
 	setGroupMute(groupOpenid, memberOpenid, op, duration) {
-		return this.post(`/v2/groups/${groupOpenid}/restrict_chat_setting`, { members: [{
+		return this.setGroupMuteBatch(groupOpenid, [{
 			op,
 			member_openid: memberOpenid,
 			mute_expire_at: duration
-		}] });
+		}]);
+	}
+	/**
+	* 批量设置群成员禁言
+	*
+	* 每项通过自身的 `op` 控制增 / 改 / 删，可以在一次请求里混用。
+	* 平台限制单次最多 20 个成员（接口文档 v1.28.0 由 10 提升至 20），
+	* 超出时平台会直接拒绝整个请求。
+	*
+	* @param groupOpenid 群 openid
+	* @param members 成员禁言设置列表
+	*/
+	setGroupMuteBatch(groupOpenid, members) {
+		return this.post(`/v2/groups/${groupOpenid}/restrict_chat_setting`, { members });
 	}
 	/**
 	* 设置群成员禁言
@@ -1530,12 +1601,13 @@ var GroupsApi = class extends Http {
 	* 机器人需拥有群管理员身份。
 	*
 	* @param groupOpenid 群 openid
-	* @param params 分页参数，`limit` 默认 20、最大 100
+	* @param params 分页参数，`limit` 默认 20、最大 50（接口文档 v1.28.0 由 100 下调），
+	* 传入更大的值会被收敛到 50，避免平台直接拒绝
 	*/
 	getJoinRequestList(groupOpenid, params = {}) {
 		const query = new URLSearchParams();
 		if (params.cursor) query.set("cursor", params.cursor);
-		if (params.limit !== void 0) query.set("limit", String(params.limit));
+		if (params.limit !== void 0) query.set("limit", String(Math.min(params.limit, 50)));
 		const search = query.toString();
 		return this.get(`/v2/groups/${groupOpenid}/join_request_list${search ? `?${search}` : ""}`);
 	}
@@ -1758,12 +1830,13 @@ var JoinApprovalApi = class extends Http {
 	* 查询入群自动审批策略列表
 	*
 	* 按创建时间倒序，支持分页。
-	* @param params 分页参数，`limit` 默认 20、最大 100
+	* @param params 分页参数，`limit` 默认 20、最大 50（接口文档 v1.28.0 由 100 下调），
+	* 传入更大的值会被收敛到 50，避免平台直接拒绝
 	*/
 	getStrategyList(params = {}) {
 		const query = new URLSearchParams();
 		if (params.cursor) query.set("cursor", params.cursor);
-		if (params.limit !== void 0) query.set("limit", String(params.limit));
+		if (params.limit !== void 0) query.set("limit", String(Math.min(params.limit, 50)));
 		const search = query.toString();
 		return this.get(`/v2/groups/join_approval_strategy${search ? `?${search}` : ""}`);
 	}
@@ -1903,7 +1976,7 @@ const buildGuildMsg = {
 * - media：富媒体上传
 * - interaction：按钮回调 ack
 * - meta：@me / dms / gateway / 分享链接
-* - groups：群基础信息 / 机器人群内状态 / 禁言 / 入群申请（部分为白名单接口）
+* - groups：群基础信息 / 机器人群内状态 / 群成员列表与详情 / 禁言 / 批量移除 / 群黑名单 / 入群申请（白名单接口）
 * - guilds：频道与子频道的查询和增删改
 * - menu：全局自定义菜单（仅单聊）
 * - panels：指令面板
@@ -2093,6 +2166,9 @@ const collectCommandEnterButtons = (buttons, keyboards) => {
 /**
 * 归一 QQ keyboard 按钮字段。
 *
+* 只重写键盘内唯一的按钮序号，其余字段（含 v1.28.0 新增的 `group_id`、
+* `action.modal`）原样透传。
+*
 * @param button node-karin 转换后的 QQBot 按钮。
 * @param id 当前 keyboard 内唯一按钮序号。
 * @returns 可直接放入 QQ 官方 keyboard 的按钮对象。
@@ -2311,9 +2387,16 @@ const resolvePreferredMediaSource = async (ctx, type, source, filename, origin,
 				via: "fallback"
 			};
 		}
+		/** 只有 image 会带宽高，其余类型按声明就没有这两个字段。 */
+		const { width, height } = result;
+		const size = typeof width === "number" && typeof height === "number" ? {
+			width,
+			height
+		} : void 0;
 		return {
 			source: result.url,
-			via: "file-to-url"
+			via: "file-to-url",
+			size
 		};
 	} catch (err) {
 		ctx.logger("warn", `[sendQQ] ${type} 转 URL 失败，改用 QQ 上传兜底:`, err);
@@ -2375,6 +2458,24 @@ const buildMarkdownImageLine = async (url, alt = "", size) => {
 	return `![${desc} #${resolved.width}px #${resolved.height}px](${url})`;
 };
 /**
+* 生成一行"来源未解析"的 markdown 图片。
+*
+* 用于适配器自己拼 markdown 正文的场景（如合并转发）：只把原始来源写进图片语法，
+* 具体走内置图床、第三方 fileToUrl 还是降级成富媒体，留给发送 pipeline 在
+* `splitMarkdownImages` 之后统一决定，避免在 pipeline 之外重复一套上传逻辑。
+*
+* 本地路径可能带空格、`)` 等会截断图片语法的字符，因此来源统一用尖括号包住——
+* `splitMarkdownImages` 取出时会剥掉。
+*
+* @param source 原始来源：本地路径、`base64://` 或 URL。
+* @param alt 图片描述；`]` 与换行会截断语法，统一压成空格。
+* @param size 已知的真实宽高，写成显式尺寸可省掉 pipeline 的一次探测。
+* @returns markdown 图片行，来源仍是原始 file 字段。
+*/
+const buildPendingMarkdownImageLine = (source, alt = "", size) => {
+	return `![${alt.replace(/[[\]\r\n]/g, " ").trim() || "karin"}${size?.width && size?.height ? ` #${size.width}px #${size.height}px` : ""}](<${normalizeMediaSource(source)}>)`;
+};
+/**
 * 将图片列表合并到一段 markdown 文本内（每张图占一行）
 *
 * @param urls 图片来源列表。
@@ -2447,21 +2548,31 @@ const splitMarkdownImages = (markdown) => {
 //#region src/core/adapter/pipeline-qq.ts
 /**
 * 处理 QQ 场景（单聊 + 群聊）的发送
+*
+* QQ 单聊 / 群聊的自定义 Markdown 自 2026-04-23 起已开放给所有机器人，无需申请
+* （见 `api-docs/server-inter/message/type/markdown.md`），所以这里只保留一条发送通道：
+* text / at / 可转换为公网 URL 的图片通过 markdown content 渲染；无法转换的图片
+* 与视频 / 语音 / 文件由 sendQQMarkdown 内部以 msg_type=7 紧随主消息补发。所有
+* 富媒体都会优先通过 fileToUrl 取得公网地址，QQ 上传只做兜底。只有显式引用的
+* 纯文本消息会降级为 msg_type=0，以保证 QQ 客户端能稳定显示引用气泡。
 */
 const sendQQ = async (ctx, contact, elements) => {
+	assertOpenIdPeer(contact);
 	const target = contact.scene === "friend" ? "user" : "group";
 	const grouping = groupElements(contact.scene, elements);
 	await resolveOutgoingReferenceQQ(ctx, contact, grouping);
-	/**
-	* 自动 Markdown 通道：
-	* text / at / 可转换为公网 URL 的图片通过 markdown content 渲染；无法转换的图片
-	* 与视频 / 语音 / 文件由 sendQQMarkdown 内部以 msg_type=7 单独补发。所有富媒体
-	* 都会优先通过 fileToUrl 取得公网地址，QQ 上传只做兜底。只有显式引用的
-	* 纯文本消息会降级为 msg_type=0，以保证 QQ 客户端能稳定显示引用气泡。
-	* 显式 segment.markdown 不受该自动通道开关影响。
-	*/
-	if (ctx.cfg.markdown.enable) return sendQQMarkdown(ctx, contact, grouping, target);
-	return sendQQClassic(ctx, contact, grouping, target);
+	return sendQQMarkdown(ctx, contact, grouping, target);
+};
+/**
+* QQ 官方接口只接受 openid（32 位十六进制或 UUID 形态）寻址。纯数字 peer 一定是
+* QQ 号/群号，继续走下去只会在媒体上传或消息下发时被平台以 40011028
+* 「请求的资源不存在」拒绝，且平台错误信息没有指向性（上游常见场景：把 karin
+* 主人列表里的 QQ 号直接当私聊目标）。这里提前拦截，给出可操作的说明。
+*/
+const assertOpenIdPeer = (contact) => {
+	if (!QQ_NUMBER_RE.test(contact.peer)) return;
+	const sceneLabel = contact.scene === "friend" ? "私聊" : "群聊";
+	throw new Error(`[sendQQ] ${sceneLabel} peer 不是有效 openid: ${contact.peer}。QQ 官方 Bot API 不使用 QQ 号/群号寻址，请让对方先给机器人发一条消息，从事件中获取其 openid 后填入配置`);
 };
 /**
 * Markdown 通道：合成一条 msg_type=2 + 可选 keyboard
@@ -2500,46 +2611,6 @@ const sendQQMarkdown = async (ctx, contact, grouping, target) => {
 	return flushQQ(ctx, contact, grouping, items);
 };
 /**
-* 经典通道：文本走 msg_type=0，图片 / 富媒体走 msg_type=7。
-*/
-const sendQQClassic = async (ctx, contact, grouping, target) => {
-	const items = [];
-	const lines = [];
-	const images = [...grouping.qqImages];
-	if (grouping.text.length) lines.push(grouping.text.join(""));
-	if (!grouping.markdowns.length && (grouping.buttons.length || grouping.keyboards.length)) ctx.logger("warn", "Markdown 通道已关闭，button / keyboard 无法随普通文本发送，已跳过");
-	const content = lines.join("\n").trim();
-	if (content) items.push(ctx.super.qq.text(content));
-	for (const image of images) items.push(await buildQQMediaItem(ctx, target, contact.peer, "image", image));
-	for (const m of grouping.media) items.push(await buildQQMediaItem(ctx, target, contact.peer, m.kind, m.source, m.name));
-	await appendExplicitMarkdownItems(ctx, contact, grouping, target, items);
-	if (!items.length) items.push(ctx.super.qq.text("不支持发送的消息类型"));
-	return flushQQ(ctx, contact, grouping, items);
-};
-/**
-* 显式 `segment.markdown` 是调用方指定的发送类型，不受 Markdown 自动通道开关影响。
-*/
-const appendExplicitMarkdownItems = async (ctx, contact, grouping, target, items) => {
-	if (!grouping.markdowns.length) return;
-	const lines = [];
-	const fallbackImages = await appendExplicitMarkdown(ctx, lines, grouping, {
-		scene: target,
-		peer: contact.peer
-	});
-	if (contact.scene === "group") {
-		warnUnsupportedCommandEnterButtons$1(ctx, collectCommandEnterButtons(grouping.buttons, grouping.keyboards));
-		warnUnsupportedCommandEnterMarkdowns$1(ctx, grouping.markdowns.map((m) => m.markdown));
-	}
-	const mediaItems = [];
-	for (const file of fallbackImages) {
-		const res = await ctx.super.media.uploadFallback(target, contact.peer, "image", file, false);
-		mediaItems.push(ctx.super.qq.media(res.file_info));
-	}
-	if (lines.length) items.push(ctx.super.qq.markdown({ content: lines.join("\n") }, buildKeyboard$1(grouping)));
-	else attachKeyboardWithoutMarkdown(ctx, grouping, mediaItems, items);
-	items.push(...mediaItems);
-};
-/**
 * 处理「没有任何 markdown 正文，但存在按钮」的边缘情况。
 *
 * 典型触发路径：下游只发一张 markdown 语法图片 + 若干按钮，而这张图片没能通过
@@ -2566,14 +2637,6 @@ const attachKeyboardWithoutMarkdown = (ctx, grouping, mediaItems, items) => {
 	first.keyboard = keyboard;
 	ctx.logger("debug", "图片未能进入 markdown 通道，按钮已随富媒体一起发送，避免拆成两条消息");
 };
-const buildQQMediaItem = async (ctx, target, peer, type, source, name) => {
-	const resolved = await resolvePreferredMediaSource(ctx, type, source, name, {
-		scene: target,
-		peer
-	});
-	const res = resolved.via === "fallback" ? await ctx.super.media.uploadFallback(target, peer, type, resolved.source, false, name) : await ctx.super.media.upload(target, peer, type, resolved.source, false, name);
-	return ctx.super.qq.media(res.file_info);
-};
 /**
 * 将能转成公网 URL 的图片追加到 markdown 行，无法转换的图片返回给富媒体 fallback。
 *
@@ -2591,7 +2654,7 @@ const appendMarkdownImages = async (ctx, lines, files, origin) => {
 			fallback.push(file);
 			continue;
 		}
-		await appendImageUrlLine(lines, resolved.source);
+		lines.push(await buildMarkdownImageLine(resolved.source, "", resolved.size));
 	}
 	return fallback;
 };
@@ -2618,21 +2681,11 @@ const appendExplicitMarkdown = async (ctx, lines, grouping, origin) => {
 			continue;
 		}
 		/** 保留开发者写下的 alt 与显式尺寸，只替换图片来源 */
-		lines.push(await buildMarkdownImageLine(resolved.source, part.alt));
+		lines.push(await buildMarkdownImageLine(resolved.source, part.alt, resolved.size));
 	}
 	return fallback;
 };
 /**
-* 生成单张 markdown 图片行。
-* 尺寸获取失败时使用保守默认尺寸，保证 fileToUrl 成功的图片仍走 markdown。
-*
-* @param lines markdown 行数组。
-* @param url 图片 URL。
-*/
-const appendImageUrlLine = async (lines, url) => {
-	lines.push(await buildMarkdownImageLine(url));
-};
-/**
 * 判断显式引用回复是否应降级为普通文本消息。
 *
 * QQ 的 `message_reference` 对普通文本最稳定；markdown 带引用在客户端渲染上存在兼容问题。
@@ -2850,18 +2903,95 @@ const buildPassiveQQ = (ctx, scene, grouping) => {
 	};
 };
 
+//#endregion
+//#region src/core/adapter/guild-markdown.ts
+/**
+* 频道 Markdown 能力探测。
+*
+* 官方能力说明（`api-docs/server-inter/message/type/markdown.md`）：2026-04-23 起
+* 单聊 / 群聊的自定义 Markdown 已开放到所有机器人，无需申请；**频道场景仍需内邀
+* 开通**。因此单聊 / 群聊直接走 Markdown，频道场景先乐观尝试，被平台以权限类
+* 错误拒绝后记住该 bot 并改走普通消息，避免之后每条消息都白跑一次请求。
+*
+* 状态只存在于当前进程，也不写配置：拿到内邀后重启（或改一次配置触发 bot 重建）
+* 即可重新尝试，用户不需要手动去点任何开关。
+*/
+/** 已确认没有频道 Markdown 权限的 appId。 */
+const forbidden = /* @__PURE__ */ new Set();
+/**
+* 平台拒绝 Markdown 的权限类错误码。
+*
+* - 50056 不允许发送 markdown content；
+* - 304036 没有 markdown 模板的权限。
+*/
+const FORBIDDEN_CODES = [50056, 304036];
+/**
+* 该 bot 当前是否还可以尝试频道 Markdown。
+*
+* @param selfId 机器人 appId。
+* @returns 未被标记为无权限时返回 true。
+*/
+const canSendGuildMarkdown = (selfId) => !forbidden.has(selfId);
+/**
+* 标记该 bot 没有频道 Markdown 权限。
+*
+* @param selfId 机器人 appId。
+* @returns 本次是否是首次标记，供调用方只告警一次。
+*/
+const disableGuildMarkdown = (selfId) => {
+	if (forbidden.has(selfId)) return false;
+	forbidden.add(selfId);
+	return true;
+};
+/**
+* 清除该 bot 的降级标记，让下一条频道消息重新尝试 Markdown。
+*
+* bot 重建（配置变更 / 重新登录）时调用，避免内邀开通后还要重启整个 Karin。
+*
+* @param selfId 机器人 appId。
+*/
+const resetGuildMarkdown = (selfId) => {
+	forbidden.delete(selfId);
+};
+/**
+* 判断发送失败是否来自平台对 Markdown 权限的校验。
+*
+* Http 层把平台错误格式化成普通 Error（`[Code 50056] ...`），这里按错误码优先、
+* 中文文案兜底识别，和 pipeline 里其它降级判断保持一致的做法。
+*
+* @param err 捕获到的发送异常。
+* @returns 是否应降级为普通消息。
+*/
+const isGuildMarkdownForbiddenError = (err) => {
+	const message = err instanceof Error ? err.message : String(err);
+	if (FORBIDDEN_CODES.some((code) => message.includes(`[Code ${code}]`))) return true;
+	return message.includes("不允许发送 markdown") || message.includes("没有 markdown 模板的权限");
+};
+
 //#endregion
 //#region src/core/adapter/pipeline-guild.ts
 /**
 * 处理频道场景（子频道 + 私信）的发送
 *
-* 默认把普通文本 / at / 图片通过 markdown 渲染。关闭自动 Markdown 通道后，
-* 普通文本和图片改走经典发送；显式 segment.markdown 仍按调用方指定走 Markdown。
+* 频道的自定义 Markdown 目前仍需向 QQ 申请内邀开通（见
+* `api-docs/server-inter/message/type/markdown.md`），所以这里不靠用户配置开关，
+* 而是先乐观走 Markdown：被平台以权限类错误拒绝后记住这个 bot，本次立刻降级重发，
+* 之后的频道消息直接走普通消息通道。
 */
 const sendGuild = async (ctx, contact, elements) => {
 	const grouping = groupElements(contact.scene, elements);
-	if (ctx.cfg.markdown.enable) return sendGuildMarkdown(ctx, contact, grouping);
-	return sendGuildClassic(ctx, contact, grouping);
+	if (!canSendGuildMarkdown(ctx.selfId)) return sendGuildClassic(ctx, contact, grouping);
+	try {
+		return await sendGuildMarkdown(ctx, contact, grouping);
+	} catch (err) {
+		if (!isGuildMarkdownForbiddenError(err)) throw err;
+		/**
+		* markdown 主消息一定是 items[0]，被拒时本次还没有任何消息发出去，
+		* 因此可以安全地整条重发，不会出现重复消息。
+		*/
+		if (disableGuildMarkdown(ctx.selfId)) ctx.logger("warn", "频道 Markdown 未开通（需向 QQ 申请内邀），已降级为普通消息发送；本进程后续频道消息不再尝试 Markdown，开通后重启或改一次配置即可恢复");
+		return sendGuildClassic(ctx, contact, grouping);
+	}
 };
 /**
 * Markdown 通道
@@ -2920,53 +3050,37 @@ const sendGuildMarkdown = async (ctx, contact, grouping) => {
 	return flushGuild(ctx, contact, grouping, items);
 };
 /**
-* 经典通道：文本走 content，图片按文档走 image / file_image 单独发送。
+* 降级通道：频道 Markdown 权限不可用时使用。
+*
+* 文本走 content，图片按文档走 image / file_image 单独发送。这条通道不会产出任何
+* markdown 消息体——显式 `segment.markdown` 也一样：内嵌图片被拆出来单独发送，
+* 其余部分按普通文本下发。否则同一条消息只会再被平台以同样的权限错误拒绝一次。
 */
 const sendGuildClassic = async (ctx, contact, grouping) => {
 	const items = [];
 	const lines = [];
 	const images = [...grouping.guildImageUrls, ...grouping.guildImageFiles];
 	if (grouping.text.length) lines.push(grouping.text.join(""));
-	if (!grouping.markdowns.length && (grouping.buttons.length || grouping.keyboards.length)) ctx.logger("warn", "Markdown 通道已关闭，button / keyboard 无法随普通文本发送，已跳过");
+	/** 频道 keyboard 只能挂在 markdown 消息体上，没有 markdown 就无处附着。 */
+	if (grouping.buttons.length || grouping.keyboards.length) ctx.logger("warn", "频道 Markdown 不可用，button / keyboard 无法发送，已跳过");
+	if (grouping.markdowns.length) {
+		/** 内容没有丢，只是渲染成纯文本，用 debug 避免每条消息都刷一条 warn。 */
+		ctx.logger("debug", "[sendGuild] Markdown 不可用，segment.markdown 已按普通文本发送，内嵌图片改为单独发送");
+		for (const markdown of grouping.markdowns) for (const part of splitMarkdownImages(markdown.markdown)) {
+			if (part.type === "text") {
+				const text = part.value.trim();
+				if (text) lines.push(text);
+				continue;
+			}
+			images.push(part.source);
+		}
+	}
 	const content = lines.join("\n").trim();
 	if (content) items.push(ctx.super.guild.text(content));
 	for (const image of images) items.push(await buildGuildImageItem(image));
-	await appendExplicitGuildMarkdownItems(ctx, contact, grouping, items);
 	if (!items.length) items.push(ctx.super.guild.text("不支持发送的消息类型"));
 	return flushGuild(ctx, contact, grouping, items);
 };
-/**
-* 显式 `segment.markdown` 是调用方指定的发送类型，不受 Markdown 自动通道开关影响。
-*/
-const appendExplicitGuildMarkdownItems = async (ctx, contact, grouping, items) => {
-	if (!grouping.markdowns.length) return;
-	const extra = {
-		selfId: ctx.selfId,
-		purpose: "markdown"
-	};
-	const lines = [];
-	const fallbackImages = [];
-	for (const markdown of grouping.markdowns) for (const part of splitMarkdownImages(markdown.markdown)) {
-		if (part.type === "text") {
-			const text = part.value.trim();
-			if (text) lines.push(text);
-			continue;
-		}
-		try {
-			/** 保留开发者写下的 alt 与显式尺寸，只替换图片来源 */
-			lines.push(await markdownPartToLine(part, extra));
-		} catch {
-			ctx.logger("debug", "[sendGuild] markdown 内嵌图片转 URL 失败，改走 file_image 单独发送");
-			fallbackImages.push(part.source);
-		}
-	}
-	warnUnsupportedCommandEnterButtons(ctx, contact.scene, collectCommandEnterButtons(grouping.buttons, grouping.keyboards));
-	warnUnsupportedCommandEnterMarkdowns(ctx, contact.scene, grouping.markdowns.map((m) => m.markdown));
-	const keyboard = buildKeyboard(grouping);
-	const content = lines.length ? lines.join("\n") : "​";
-	items.push(ctx.super.guild.markdown({ content }, keyboard));
-	for (const file of fallbackImages) items.push(await buildGuildImageItem(file));
-};
 const buildGuildImageItem = async (source) => {
 	if (/^https?:\/\//i.test(source)) return {
 		type: "image",
@@ -3078,11 +3192,12 @@ const shouldCacheSelfMessage = (ctx) => {
 *
 * 静态资源只在这里转一次 HTTP URL，之后发送 pipeline 和缓存都复用该 URL。
 */
-const prepareSelfMessageCache = async (ctx, elements) => {
+const prepareSelfMessageCache = async (ctx, contact, elements) => {
 	const sendElements = [];
 	const cacheElements = [];
+	const origin = resolveUploadOrigin(contact);
 	for (const element of elements) {
-		const prepared = await prepareSelfCacheElement(ctx, element);
+		const prepared = await prepareSelfCacheElement(ctx, element, origin);
 		sendElements.push(prepared.send);
 		if (prepared.cache) cacheElements.push(prepared.cache);
 	}
@@ -3129,7 +3244,7 @@ const cacheSelfMessage = (ctx, contact, cacheElements, result) => {
 /**
 * 转换单个自己消息元素为缓存安全形态。
 */
-const prepareSelfCacheElement = async (ctx, element) => {
+const prepareSelfCacheElement = async (ctx, element, origin) => {
 	switch (element.type) {
 		case "text":
 		case "at":
@@ -3145,7 +3260,7 @@ const prepareSelfCacheElement = async (ctx, element) => {
 		case "image":
 		case "video":
 		case "record":
-		case "file": return prepareStaticElement(ctx, element);
+		case "file": return prepareStaticElement(ctx, element, origin);
 		default: return {
 			send: element,
 			cache: null
@@ -3153,9 +3268,9 @@ const prepareSelfCacheElement = async (ctx, element) => {
 	}
 };
 /**
-* 静态资源统一转 HTTP URL 后再缓存；转换失败时跳过该元素。
+* 静态资源统一转 HTTP URL 后再缓存；转换失败或没有处理器接手时跳过该元素。
 */
-const prepareStaticElement = async (ctx, element) => {
+const prepareStaticElement = async (ctx, element, origin) => {
 	if (element.file.startsWith("http")) {
 		const cached = { ...element };
 		return {
@@ -3164,54 +3279,41 @@ const prepareStaticElement = async (ctx, element) => {
 		};
 	}
 	try {
-		switch (element.type) {
-			case "image": {
-				const res = await fileToUrl("image", element.file, element.name || "image.jpg");
-				const cached = {
-					...element,
-					file: res.url,
-					width: res.width,
-					height: res.height
-				};
-				return {
-					send: cached,
-					cache: cached
-				};
-			}
-			case "video": {
-				const res = await fileToUrl("video", element.file, element.name || "video.mp4");
-				const cached = {
-					...element,
-					file: res.url
-				};
-				return {
-					send: cached,
-					cache: cached
-				};
-			}
-			case "record": {
-				const res = await fileToUrl("record", element.file, element.name || "record.mp3");
-				const cached = {
-					...element,
-					file: res.url
-				};
-				return {
-					send: cached,
-					cache: cached
-				};
-			}
-			case "file": {
-				const res = await fileToUrl("file", element.file, element.name || "file.bin");
-				const cached = {
-					...element,
-					file: res.url
-				};
-				return {
-					send: cached,
-					cache: cached
-				};
-			}
+		/**
+		* 和发送链路传同一套附加信息：处理器需要知道是哪个 bot、哪个会话才能用对
+		* openid。用途是 media —— 缓存要的是能长期访问的地址，内置图床给的是会过期的
+		* 临时直链，按 purpose 主动放行正好。
+		*/
+		const extra = {
+			selfId: ctx.selfId,
+			purpose: "media",
+			origin
+		};
+		const res = await fileToUrl(element.type, element.file, element.name || DEFAULT_FILENAME[element.type], extra);
+		/**
+		* 链路上的处理器全部放行时 fileToUrl 实际返回 undefined（类型声明未涵盖
+		* 这种情况），不属于异常：发送继续使用原始来源，仅跳过该元素的缓存。
+		*/
+		if (!res?.url) {
+			ctx.logger("debug", `[getMsg] 没有 fileToUrl 处理器接手 ${element.type}，跳过该元素的缓存`);
+			return {
+				send: element,
+				cache: null
+			};
 		}
+		const cached = {
+			...element,
+			file: res.url
+		};
+		if (cached.type === "image") {
+			const { width, height } = res;
+			cached.width = width;
+			cached.height = height;
+		}
+		return {
+			send: cached,
+			cache: cached
+		};
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		ctx.logger("debug", `[getMsg] 跳过自己消息资源缓存: ${element.type} ${message}`);
@@ -3222,6 +3324,25 @@ const prepareStaticElement = async (ctx, element) => {
 	}
 };
 /**
+* 解析缓存用 URL 转换的归属会话。
+*
+* QQ 的 openid 按 bot 隔离，上传接口只接受该 bot 可见的 group_openid / user_openid；
+* 频道用 channel_id，没有可用 openid，返回 undefined。
+*
+* @param contact 本次发送目标。
+* @returns 可交给 fileToUrl 处理器的上传会话。
+*/
+const resolveUploadOrigin = (contact) => {
+	if (contact.scene === "group") return {
+		scene: "group",
+		peer: contact.peer
+	};
+	if (contact.scene === "friend") return {
+		scene: "user",
+		peer: contact.peer
+	};
+};
+/**
 * 构造机器人自己的 sender。
 */
 const selfSender = (ctx, contact) => {
@@ -3339,10 +3460,37 @@ const getAdapterConfig = (bot) => {
 //#endregion
 //#region src/core/adapter/base.ts
 /**
+* 按 Karin 接口约定构造群成员信息。
+*
+* `sender` 用 getter 即时构建，避免整个适配器被系统接口序列化时带出多余引用。
+*
+* @param userId 成员 openid。
+* @param role 群内角色。
+* @param nick 成员昵称。
+* @param joinTime 入群时间戳（毫秒）。
+* @returns Karin 标准群成员信息。
+*/
+const buildGroupMemberInfo = (userId, role, nick, joinTime) => ({
+	userId,
+	role,
+	nick,
+	joinTime,
+	get sender() {
+		return senderGroup({
+			userId,
+			nick: nick || "",
+			name: nick || "",
+			role
+		});
+	}
+});
+/**
 * 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 紧随主消息补发。
 */
 var AdapterQQBot = class extends AdapterBase {
 	/** 与官方 API 交互 */
@@ -3383,13 +3531,13 @@ var AdapterQQBot = class extends AdapterBase {
 		const normalizedElements = normalizeMediaElements(elements);
 		/** 发送成功后始终记录消息 ID 映射；正文是否入库由 cacheSelfMessage 内部按开关决定。 */
 		if (contact.scene === "direct" || contact.scene === "guild") {
-			const prepared = shouldCacheSelfMessage(this) ? await prepareSelfMessageCache(this, normalizedElements) : void 0;
+			const prepared = shouldCacheSelfMessage(this) ? await prepareSelfMessageCache(this, contact, normalizedElements) : void 0;
 			const result = await sendGuild(this, contact, prepared?.sendElements ?? normalizedElements);
 			cacheSelfMessage(this, contact, prepared?.cacheElements ?? [], result);
 			return result;
 		}
 		if (contact.scene === "group" || contact.scene === "friend") {
-			const prepared = shouldCacheSelfMessage(this) ? await prepareSelfMessageCache(this, normalizedElements) : void 0;
+			const prepared = shouldCacheSelfMessage(this) ? await prepareSelfMessageCache(this, contact, normalizedElements) : void 0;
 			const result = await sendQQ(this, contact, prepared?.sendElements ?? normalizedElements);
 			cacheSelfMessage(this, contact, prepared?.cacheElements ?? [], result);
 			return result;
@@ -3458,8 +3606,16 @@ var AdapterQQBot = class extends AdapterBase {
 	/**
 	* 发送合并转发消息
 	*
-	* 将 NodeElement 拆解为文本 + 图片等元素，拼接成 markdown 发送。
-	* 节点之间仅用换行隔开，不添加任何前缀提示文本。
+	* QQ 官方没有合并转发能力，这里把各节点摊平成一段 Markdown 正文，节点之间用
+	* 强制换行隔开，不添加任何前缀提示文本。
+	*
+	* 图片以 markdown 图片语法写入，**保留原始来源**（本地路径 / base64 / URL）：
+	* 究竟走内置图床、第三方 fileToUrl，还是降级成 msg_type=7 富媒体，由发送
+	* pipeline 统一决定。这里不自己上传，也不自己判断通道——否则频道场景在没有
+	* Markdown 权限时会绕过降级逻辑，直接被平台拒掉。
+	*
+	* 视频 / 语音 / 文件进不了 markdown，作为普通消息段跟随主消息一起交给 pipeline，
+	* 由它在同一次发送里以 msg_type=7 补发。
 	*/
 	async sendForwardMsg(contact, elements, _options) {
 		const parts = [];
@@ -3476,43 +3632,12 @@ var AdapterQQBot = class extends AdapterBase {
 					case "text":
 						lines.push(el.text);
 						break;
-					case "image": {
-						const imageSource = typeof el.file === "string" ? normalizeMediaSource(el.file) : el.file;
-						if (typeof imageSource === "string" && imageSource.startsWith("http")) try {
-							const { width, height } = await getImageSize(imageSource);
-							lines.push(`![${el.name || "图片"} #${width}px #${height}px](${imageSource})`);
-						} catch {
-							lines.push(`![${el.name || "图片"} #300px #300px](${imageSource})`);
-						}
-						else {
-							/**
-							* 必须带上 selfId / purpose / origin：内置图床按这三个字段决定
-							* 是否接手，缺任何一个都会直接放行给后续处理器。频道场景没有
-							* 可用的 openid，origin 只能是 undefined。
-							*/
-							const origin = contact.scene === "group" ? {
-								scene: "group",
-								peer: contact.peer
-							} : contact.scene === "friend" ? {
-								scene: "user",
-								peer: contact.peer
-							} : void 0;
-							try {
-								const result = await fileToUrl("image", imageSource, el.name || "image.jpg", {
-									selfId: this.selfId,
-									purpose: "markdown",
-									origin
-								});
-								if (result?.url) lines.push(`![${el.name || "图片"} #${result.width || 300}px #${result.height || 300}px](${result.url})`);
-								else
- /** 没有处理器接手时不能留空 URL 的图片语法（客户端渲染为空白），改走富媒体补发 */
-								mediaElements.push(el);
-							} catch {
-								mediaElements.push(el);
-							}
-						}
+					case "image":
+						lines.push(buildPendingMarkdownImageLine(el.file, el.name || "图片", el.width && el.height ? {
+							width: el.width,
+							height: el.height
+						} : void 0));
 						break;
-					}
 					case "at":
 						if (contact.scene === "friend" || contact.scene === "direct") break;
 						if (el.targetId === "all") lines.push("<qqbot-at-everyone />");
@@ -3538,10 +3663,21 @@ var AdapterQQBot = class extends AdapterBase {
 			if (block) parts.push(block);
 		}
 		const content = parts.join("\r\r\n\n");
-		const result = await this.sendMsg(contact, [segment.markdown(content)]);
-		if (mediaElements.length) await this.sendMsg(contact, mediaElements);
+		/**
+		* 正文可能整段为空（例如只转发了一个视频节点）。此时不能塞一条空 markdown：
+		* 平台会以 50041「markdown 有空值」拒绝，pipeline 也会因为没有可发内容而
+		* 回落成一条"不支持发送的消息类型"。
+		*/
+		const sendElements = content ? [segment.markdown(content), ...mediaElements] : mediaElements;
+		if (!sendElements.length) {
+			this.logger("warn", "[sendForwardMsg] 转发节点里没有可发送的内容，已跳过");
+			return {
+				messageId: "",
+				forwardId: ""
+			};
+		}
 		return {
-			messageId: result.messageId,
+			messageId: (await this.sendMsg(contact, sendElements)).messageId,
 			forwardId: ""
 		};
 	}
@@ -3664,9 +3800,30 @@ var AdapterQQBot = class extends AdapterBase {
 	}
 	/**
 	* 群踢人
+	*
+	* 走官方 `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 官方不支持，仅在传入时输出提示
 	*/
 	async groupKickMember(_groupId, _targetId, _rejectAddRequest, _kickReason) {
-		this.logger("warn", "[groupKickMember] QQ Official Bot API 暂不支持群踢人");
+		if (_kickReason) this.logger("warn", `[groupKickMember] QQ Official Bot API 不支持踢人理由，已忽略: ${_kickReason}`);
+		try {
+			const failed = (await this.super.groups.batchRemoveGroupMembers(_groupId, {
+				member_openids: [_targetId],
+				..._rejectAddRequest ? { add_to_member_blacklist: true } : {}
+			})).add_to_member_blacklist_fail_openids ?? [];
+			if (failed.length) this.logger("warn", `[groupKickMember] 成员已移除，但加入群黑名单失败: ${failed.join("、")}`);
+		} catch (err) {
+			this.logger("error", "[groupKickMember] 移除群成员失败（该接口为白名单接口，未开通权限会返回 11253）:", err);
+		}
 	}
 	/**
 	* 禁言群成员
@@ -3801,49 +3958,63 @@ var AdapterQQBot = class extends AdapterBase {
 	/**
 	* 获取群成员信息
 	*
-	* - 查询机器人自身（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）或查询失败时降级为占位结构并告警。
 	*/
 	async getGroupMemberInfo(_groupId, _targetId, _refresh) {
-		/** 按 karin 接口约定构造返回值，sender 由 getter 即时构建 */
-		const build = (userId, role, nick, joinTime) => ({
-			userId,
-			role,
-			nick,
-			joinTime,
-			get sender() {
-				return senderGroup({
-					userId,
-					nick: nick || "",
-					name: nick || "",
-					role
-				});
-			}
-		});
 		if (_targetId === this.selfId) try {
 			const state = await this.super.groups.getBotState(_groupId);
-			return build(state.member_openid || _targetId, state.member_role || "member", void 0, state.joined_at ? new Date(state.joined_at).getTime() : void 0);
+			return buildGroupMemberInfo(state.member_openid || _targetId, state.member_role || "member", void 0, state.joined_at ? new Date(state.joined_at).getTime() : void 0);
 		} catch (err) {
 			this.logger("warn", `[getGroupMemberInfo] 获取机器人群内状态失败（该接口为白名单接口，未开通权限会返回 11253）: ${err instanceof Error ? err.message : err}`);
-			return build(_targetId, "member");
+			return buildGroupMemberInfo(_targetId, "member");
 		}
 		try {
 			const member = await this.super.groups.getGroupMember(_groupId, _targetId);
-			if (member.nick) this.nicknameCache.set(_targetId, member.nick);
-			return build(member.member_openid || _targetId, member.member_role || "member", member.nick, member.joined_at ? new Date(member.joined_at).getTime() : void 0);
+			const nick = member.username || member.nick;
+			if (nick) this.nicknameCache.set(_targetId, nick);
+			return buildGroupMemberInfo(member.member_openid || _targetId, member.member_role || "member", nick, member.joined_at ? new Date(member.joined_at).getTime() : void 0);
 		} catch (err) {
-			this.logger("warn", `[getGroupMemberInfo] 获取群成员详情失败（该接口未公开文档，可能不可用）: ${err instanceof Error ? err.message : err}`);
-			return build(_targetId, "member");
+			this.logger("warn", `[getGroupMemberInfo] 获取群成员详情失败（该接口为白名单接口，未开通权限会返回 11253）: ${err instanceof Error ? err.message : err}`);
+			return buildGroupMemberInfo(_targetId, "member");
 		}
 	}
 	/**
 	* 获取群成员列表
+	*
+	* 走官方 `GET /v2/groups/{group_openid}/members`（白名单接口），每页最多 30 条，
+	* 这里按 `next_cursor` 自动翻完所有页；顺便把昵称写入
+	* {@link AdapterQQBot.nicknameCache}，让后续消息事件能直接取到昵称。
+	*
+	* 为防止平台返回的游标不收敛，翻页数有安全上限（约 6000 人），触顶会告警并返回已取到的部分。
+	* 未开通权限（11253）或查询失败时返回已取到的部分并告警。
+	*
+	* @param _groupId 群 openid
 	*/
 	async getGroupMemberList(_groupId, _refresh) {
-		this.logger("warn", "[getGroupMemberList] QQ Official Bot API 暂不支持获取群成员列表");
-		return [];
+		const result = [];
+		let cursor = "";
+		try {
+			for (let page = 0; page < 200; page++) {
+				const data = await this.super.groups.getGroupMemberList(_groupId, cursor ? { cursor } : {});
+				for (const member of data.members ?? []) {
+					if (member.username) this.nicknameCache.set(member.member_openid, member.username);
+					result.push(buildGroupMemberInfo(member.member_openid, member.member_role || "member", member.username, member.joined_at ? new Date(member.joined_at).getTime() : void 0));
+				}
+				const next = data.next_cursor || "";
+				/** 空游标表示末页；游标不前进说明平台返回异常，直接停止避免死循环 */
+				if (!next || next === cursor) return result;
+				cursor = next;
+			}
+			this.logger("warn", `[getGroupMemberList] 翻页数已达上限 ${200} 页，仅返回前 ${result.length} 名成员`);
+		} catch (err) {
+			this.logger("warn", `[getGroupMemberList] 获取群成员列表失败（该接口为白名单接口，未开通权限会返回 11253）: ${err instanceof Error ? err.message : err}`);
+		}
+		return result;
 	}
 	/**
 	* 获取群荣誉信息
@@ -5426,7 +5597,7 @@ const intentBitMap = {
 	[2]: "GUILD_MEMBERS        (频道成员变更)",
 	[512]: "GUILD_MESSAGES       (频道消息-私域)",
 	[4096]: "DIRECT_MESSAGE       (频道私信)",
-	[1 << 24]: "群成员进退群事件",
+	[1 << 24]: "GROUP_MEMBER_EVENT  (群成员进退群/入群申请)",
 	[1 << 25]: "GROUP_AND_C2C_EVENT (群聊/单聊消息)",
 	[1 << 26]: "INTERACTION          (按钮交互回调)",
 	[1 << 30]: "PUBLIC_GUILD_MESSAGES (频道消息-公域)"
@@ -5715,7 +5886,6 @@ const hashConfig = (bot) => JSON.stringify({
 	appId: bot.appId,
 	secret: bot.secret,
 	event: bot.event,
-	markdown: bot.markdown,
 	messageCache: bot.messageCache
 });
 /**
@@ -5743,6 +5913,8 @@ const createBot = async (input) => {
 		stop(appId);
 		offAll(appId);
 		stopTokenRefresh(appId);
+		/** 重建即重新探测频道 Markdown，拿到内邀后不必重启整个 Karin。 */
+		resetGuildMarkdown(appId);
 		logger.info(`[QQ Official Bot][${appId}] 获取 access_token...`);
 		await getAccessToken(appId, bot.secret);
 		const api = new QQBotApi(createAxiosInstance(appId));