@karinjs/adapter-qqbot 3.3.0 → 3.4.0

package/dist/index.js

@@ -1,7 +1,7 @@
 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, s as QQ_NUMBER_RE, t as fakeEvent } from "./common-DwVsAvIo.js";
-import "./utils-u17tvC2U.js";
+import { a as DATA_URL_BASE64_RE, c as QQ_NUMBER_RE, i as BASE64_PREFIX_RE, n as getImageSize, o as HTTP_URL_RE, r as random, s as QQBOT_MEDIA_RE, t as fakeEvent } from "./common-D4MDcmOI.js";
+import "./utils-YkZrLNvO.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";
@@ -32,13 +32,6 @@ const FILE_TYPE = {
 	record: 3,
 	file: 4
 };
-/** 各类资源的 QQ 上传上限。 */
-const MAX_UPLOAD_SIZE = {
-	image: 30 * 1024 * 1024,
-	video: 100 * 1024 * 1024,
-	record: 20 * 1024 * 1024,
-	file: 100 * 1024 * 1024
-};
 /** 上传错误中展示的资源类型名称。 */
 const MEDIA_TYPE_LABEL = {
 	image: "图片",
@@ -63,7 +56,7 @@ const DEFAULT_MIME = {
 	video: "video/mp4",
 	record: "audio/mpeg"
 };
-/** fallback 上传超过该大小时走 QQ 分片上传。 */
+/** 二进制直传超过该大小时改用分片；这不是平台硬限制。 */
 const LARGE_UPLOAD_THRESHOLD = 5 * 1024 * 1024;
 /** COS 用于覆盖下载响应类型的 query 参数名。 */
 const RESPONSE_TYPE_PARAM = "response-content-type";
@@ -937,24 +930,6 @@ const normalizeUploadFileName = (type, name) => {
 	return path.basename(value) || DEFAULT_FILENAME[type];
 };
 /**
-* 检查 fallback 资源大小是否超过 QQ 对应类型上限。
-* @param type 富媒体类型。
-* @param size 文件大小。
-*/
-const assertUploadSize = (type, size) => {
-	const limit = MAX_UPLOAD_SIZE[type];
-	if (size <= limit) return;
-	throw new Error(`${MEDIA_TYPE_LABEL[type]}过大：${formatBytes(size)}，QQ 上传上限为 ${formatBytes(limit)}`);
-};
-/**
-* 读取本地媒体文件并转为 QQ 上传接口需要的 base64。
-* @param source 本地路径或 file:// URL。
-* @returns 文件内容的 base64 字符串。
-*/
-const readLocalFileAsBase64 = async (source) => {
-	return readFile(normalizeLocalPath(source), "base64");
-};
-/**
 * 下载远程媒体并返回 Buffer。
 * @param url 远程媒体 URL。
 * @returns 文件内容。
@@ -977,18 +952,6 @@ const downloadRemoteAsBase64 = async (url) => {
 	return (await downloadRemoteAsBuffer(url)).toString("base64");
 };
 /**
-* 将 Karin 的 file 字段归一为 QQ 上传接口支持的 url / file_data。
-* @param source HTTP URL、本地路径、data URL、base64:// 或裸 base64。
-* @returns 可合并进上传请求体的来源字段。
-*/
-const buildUploadSource = async (source) => {
-	const value = source.trim();
-	if (HTTP_URL_RE.test(value)) return { url: value };
-	if (DATA_URL_BASE64_RE.test(value) || BASE64_PREFIX_RE.test(value)) return { file_data: stripBase64Prefix(value) };
-	if (isLocalPathSource(value)) return { file_data: await readLocalFileAsBase64(value) };
-	return { file_data: value };
-};
-/**
 * 将 fallback 来源归一为可判断大小、可分片读取的形式。
 *
 * @param type 富媒体类型。
@@ -1198,24 +1161,25 @@ var MediaApi = class extends Http {
 	* @param fileName 文件消息的展示文件名
 	*/
 	async upload(scene, peer, type, source, srvSendMsg = false, fileName) {
-		const sourceBody = await buildUploadSource(source);
+		const value = source.trim();
+		/** 本地 / Base64 属于二进制直传路径，统一交给按体积选择直传或分片的实现。 */
+		if (!HTTP_URL_RE.test(value)) return this.uploadFallback(scene, peer, type, value, srvSendMsg, fileName);
 		const body = {
 			file_type: FILE_TYPE[type],
-			srv_send_msg: srvSendMsg
+			srv_send_msg: srvSendMsg,
+			url: value
 		};
-		Object.assign(body, sourceBody);
-		if (type === "file" && fileName) body.file_name = fileName;
-		const path = `/v2/${scene}s/${peer}/files`;
+		if (fileName) body.file_name = fileName;
+		const requestPath = `/v2/${scene}s/${peer}/files`;
 		try {
-			return await this.post(path, body, { timeout: MEDIA_UPLOAD_TIMEOUT });
+			return await this.post(requestPath, body, { timeout: MEDIA_UPLOAD_TIMEOUT });
 		} catch (err) {
-			if (!sourceBody.url) throw err;
-			const fallbackBody = {
-				...body,
-				file_data: await downloadRemoteAsBase64(sourceBody.url)
-			};
-			delete fallbackBody.url;
-			return this.post(path, fallbackBody, { timeout: MEDIA_UPLOAD_TIMEOUT });
+			/**
+			* 文档明确提示 URL 上传可能因服务端网络失败；下载后走同一套
+			* 二进制直传 / 分片兜底，避免再次把公网 URL 交给平台。
+			*/
+			const base64 = await downloadRemoteAsBase64(value);
+			return this.uploadFallback(scene, peer, type, `base64://${base64}`, srvSendMsg, fileName);
 		}
 	}
 	/**
@@ -1230,27 +1194,32 @@ var MediaApi = class extends Http {
 	* @param source 本地路径、http url、data URL、base64:// 或裸 base64
 	* @param srvSendMsg 上传后是否由服务端直接发送
 	* @param fileName 文件消息的展示文件名
+	* @param forceChunk 是否强制走分片上传，不按 5MB 阈值判断
 	* @returns 上传结果，包含后续发送消息所需的 file_info
 	*/
-	async uploadFallback(scene, peer, type, source, srvSendMsg = false, fileName) {
+	async uploadFallback(scene, peer, type, source, srvSendMsg = false, fileName, forceChunk = false) {
+		/**
+		* 不在适配器侧按固定体积拦截；平台硬限制可能调整，由上传接口返回错误。
+		* 这里的 5MB 只用于选择二进制直传还是分片传输。
+		*/
 		const fallbackSource = await buildFallbackSource(type, source, fileName);
-		assertUploadSize(type, fallbackSource.size);
-		const hashes = !srvSendMsg ? await computeUploadHashes(fallbackSource) : void 0;
-		if (hashes) {
+		const needsChunk = forceChunk || fallbackSource.size > 5242880;
+		const hashes = !srvSendMsg || needsChunk ? await computeUploadHashes(fallbackSource) : void 0;
+		if (!srvSendMsg && hashes) {
 			const cached = await getCachedUpload(scene, peer, type, hashes.md5);
 			if (cached) return cached;
 		}
-		if (!srvSendMsg && fallbackSource.size >= 5242880) {
-			const response = await this.uploadChunked(scene, peer, type, fallbackSource, hashes);
-			if (hashes) await setCachedUpload(scene, peer, type, hashes.md5, response);
+		if (needsChunk) {
+			const response = await this.uploadChunked(scene, peer, type, fallbackSource, hashes, srvSendMsg);
+			if (!srvSendMsg && hashes) await setCachedUpload(scene, peer, type, hashes.md5, response);
 			return response;
 		}
 		const body = {
 			file_type: FILE_TYPE[type],
 			srv_send_msg: srvSendMsg,
+			file_name: fallbackSource.fileName,
 			file_data: await readFallbackSourceAsBase64(fallbackSource)
 		};
-		if (type === "file") body.file_name = fallbackSource.fileName;
 		const response = await this.post(`/v2/${scene}s/${peer}/files`, body, { timeout: MEDIA_UPLOAD_TIMEOUT });
 		if (hashes) await setCachedUpload(scene, peer, type, hashes.md5, response);
 		return response;
@@ -1276,8 +1245,8 @@ var MediaApi = class extends Http {
 	*/
 	async uploadForUrl(scene, peer, type, source, fileName) {
 		if (type === "file") throw new Error(`QQ 不为${MEDIA_TYPE_LABEL.file}类型返回下载直链，无法当图床使用`);
+		/** 同样不在本地拦截体积；平台限制由 upload_prepare / files 接口返回。 */
 		const prepared = await buildFallbackSource(type, source, fileName);
-		assertUploadSize(type, prepared.size);
 		const hashes = await computeUploadHashes(prepared);
 		const reused = await getCachedUpload(scene, peer, type, hashes.md5);
 		const response = reused?.raw_url ? reused : await this.uploadChunked(scene, peer, type, prepared, hashes);
@@ -1346,9 +1315,10 @@ var MediaApi = class extends Http {
 	* @param uploadId upload_prepare 返回的上传任务 ID
 	* @returns 上传结果
 	*/
-	async completeChunkedUpload(scene, peer, uploadId) {
+	async completeChunkedUpload(scene, peer, uploadId, srvSendMsg = false) {
 		let lastError;
 		const body = { upload_id: uploadId };
+		if (srvSendMsg) body.srv_send_msg = true;
 		for (let attempt = 0; attempt <= 2; attempt++) try {
 			return await this.post(`/v2/${scene}s/${peer}/files`, body, { timeout: MEDIA_UPLOAD_TIMEOUT });
 		} catch (err) {
@@ -1369,7 +1339,7 @@ var MediaApi = class extends Http {
 	* @param preparedHashes 预计算的文件 hash
 	* @returns 上传结果，包含后续发送消息所需的 file_info
 	*/
-	async uploadChunked(scene, peer, type, source, preparedHashes) {
+	async uploadChunked(scene, peer, type, source, preparedHashes, srvSendMsg = false) {
 		const hashes = preparedHashes || await computeUploadHashes(source);
 		const prepareBody = {
 			file_type: FILE_TYPE[type],
@@ -1404,7 +1374,154 @@ var MediaApi = class extends Http {
 		} finally {
 			await handle?.close().catch(() => void 0);
 		}
-		return this.completeChunkedUpload(scene, peer, prepare.upload_id);
+		return this.completeChunkedUpload(scene, peer, prepare.upload_id, srvSendMsg);
+	}
+};
+
+//#endregion
+//#region src/core/api/media-images.ts
+/** 素材图片缓存提前失效时间，避免临界点继续引用刚过期的 URL。 */
+const MEDIA_IMAGE_TTL_SAFETY_MARGIN_SECONDS = 60;
+/**
+* 根据文件头识别官方支持的图片类型。
+*
+* 素材接口要求文件名扩展名与 Content-Type 一致，因此不能只依赖调用方传入的
+* 文件名；Buffer 内容才是最终可信来源。
+*
+* @param buffer 图片内容。
+* @returns 图片 MIME 与标准扩展名。
+*/
+const detectMediaImageType = (buffer) => {
+	if (buffer.subarray(0, 8).equals(Buffer.from("89504e470d0a1a0a", "hex"))) return {
+		mime: "image/png",
+		ext: "png"
+	};
+	if (buffer[0] === 255 && buffer[1] === 216 && buffer[2] === 255) return {
+		mime: "image/jpeg",
+		ext: "jpg"
+	};
+	const header = buffer.subarray(0, 6).toString("ascii");
+	if (header === "GIF87a" || header === "GIF89a") return {
+		mime: "image/gif",
+		ext: "gif"
+	};
+	if (buffer.subarray(0, 4).toString("ascii") === "RIFF" && buffer.subarray(8, 12).toString("ascii") === "WEBP") return {
+		mime: "image/webp",
+		ext: "webp"
+	};
+	throw new Error("素材图片格式不支持：仅支持 png / jpeg / gif / webp");
+};
+/**
+* 让文件名扩展名与真实图片格式一致。
+*
+* @param fileName 调用方传入的文件名。
+* @param type 识别出的图片类型。
+* @returns 可直接交给 QQ 的文件名。
+*/
+const normalizeMediaImageName = (fileName, type) => {
+	const fallback = `image.${type.ext}`;
+	const base = path.basename(fileName?.trim() || fallback);
+	const currentExt = path.extname(base).slice(1).toLowerCase();
+	if (currentExt === type.ext || type.ext === "jpg" && currentExt === "jpeg") return base;
+	return `${(currentExt ? base.slice(0, -(currentExt.length + 1)) : base) || "image"}.${type.ext}`;
+};
+/**
+* 读取素材图片内容。支持 Buffer、URL、本地路径、data URL 与 base64://。
+*
+* @param source 图片来源。
+* @returns 图片二进制。
+*/
+const readMediaImageBuffer = async (source) => {
+	if (Buffer.isBuffer(source)) return source;
+	if (source instanceof Uint8Array) return Buffer.from(source);
+	const normalized = source.trim().replace(/^data:([^;,]+);base64,/i, "base64://");
+	const compact = normalized.replace(/\s+/g, "");
+	/** Karin 消息段可能直接给裸 base64，不一定是 `base64://` 前缀。 */
+	if (compact.length >= 8 && compact.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(compact)) {
+		const decoded = Buffer.from(compact, "base64");
+		try {
+			detectMediaImageType(decoded);
+			return decoded;
+		} catch {}
+	}
+	const data = await common.buffer(normalized);
+	return Buffer.from(data);
+};
+/**
+* Markdown 素材图片管理。
+*
+* 官方接口文档 v1.42.0 新增 `/v2/media-images` 系列接口，用于把本地图片
+* 上传为可长期复用的 `qqbot-media://` Markdown 引用。
+*/
+var MediaImagesApi = class extends Http {
+	/** 当前 bot 进程内按内容 MD5 复用的素材缓存。 */
+	cache = /* @__PURE__ */ new Map();
+	/** 申请上传图片，获取 upload_id 与预签名 PUT 地址。 */
+	prepare(body) {
+		return this.post("/v2/media-images/prepare", body);
+	}
+	/** 完成图片上传，获取可写入 Markdown 的 `qqbot-media://` 引用。 */
+	complete(body) {
+		return this.post("/v2/media-images/complete", body);
+	}
+	/** 查询当前机器人的有效素材图片。 */
+	list(params = {}) {
+		return this.get("/v2/media-images", { params: params.cursor ? { cursor: params.cursor } : void 0 });
+	}
+	/** 删除素材图片并释放数量配额。 */
+	delete(imageId) {
+		this.cache.clear();
+		return super.delete(`/v2/media-images/${encodeURIComponent(imageId)}/delete`);
+	}
+	/**
+	* 上传图片并返回可写入 Markdown 的 `qqbot-media://` 引用。
+	*
+	* 自动完成文件头识别、文件名规范化、MD5/SHA1 计算、预签名 PUT 与 complete。
+	*
+	* @param source 图片来源：Buffer、URL、本地路径、data URL 或 base64://。
+	* @param fileName 可选文件名；未提供时按真实图片格式生成。
+	* @returns complete 接口响应。
+	*/
+	async upload(source, fileName) {
+		/**
+		* 不在适配器侧限制图片体积；平台当前素材接口限制为 10MB，但限制策略
+		* 可能调整，统一由 prepare / complete 接口返回的错误决定。
+		*/
+		const buffer = await readMediaImageBuffer(source);
+		if (!buffer.length) throw new Error("素材图片内容为空");
+		const type = detectMediaImageType(buffer);
+		const normalizedName = normalizeMediaImageName(fileName, type);
+		const md5 = crypto.createHash("md5").update(buffer).digest("hex");
+		const cached = this.cache.get(md5);
+		if (cached && (cached.expiresAt === 0 || cached.expiresAt > Date.now())) return cached.response;
+		const sha1 = crypto.createHash("sha1").update(buffer).digest("hex");
+		const prepared = await this.prepare({
+			file_name: normalizedName,
+			file_size: buffer.length,
+			content_type: type.mime,
+			md5,
+			sha1
+		});
+		await axios.put(prepared.presigned_url, buffer, {
+			headers: {
+				"Content-Type": type.mime,
+				"Content-Length": String(buffer.length)
+			},
+			timeout: 12e4,
+			maxBodyLength: Infinity,
+			maxContentLength: Infinity
+		});
+		const response = await this.complete({
+			upload_id: prepared.upload_id,
+			md5
+		});
+		const ttl = Number(response.ttl);
+		const expiresAt = ttl > 0 ? Date.now() + Math.max(ttl - MEDIA_IMAGE_TTL_SAFETY_MARGIN_SECONDS, 10) * 1e3 : 0;
+		this.cache.set(md5, {
+			response,
+			expiresAt
+		});
+		return response;
 	}
 };
 
@@ -1452,8 +1569,11 @@ var MetaApi = class extends Http {
 	*
 	* @param body 分享链接参数，均为可选
 	*/
-	generateUrlLink(body = {}) {
-		return this.post("/v2/generate_url_link", body);
+	async generateUrlLink(body = {}) {
+		const response = await this.post("/v2/generate_url_link", body);
+		/** 兼容旧版接口返回；新文档的正式结构是 `{ data: { url } }`。 */
+		if (!("data" in response) && response.url_link) return { data: { url: response.url_link } };
+		return response;
 	}
 };
 
@@ -1974,6 +2094,7 @@ const buildGuildMsg = {
 * 子模块按职能拆分：
 * - messages：发送 / 撤回
 * - media：富媒体上传
+* - mediaImages：Markdown 素材图片管理
 * - interaction：按钮回调 ack
 * - meta：@me / dms / gateway / 分享链接
 * - groups：群基础信息 / 机器人群内状态 / 群成员列表与详情 / 禁言 / 批量移除 / 群黑名单 / 入群申请（白名单接口）
@@ -2003,6 +2124,7 @@ var QQBotApi = class {
 	request;
 	messages;
 	media;
+	mediaImages;
 	interaction;
 	meta;
 	groups;
@@ -2018,6 +2140,7 @@ var QQBotApi = class {
 		this.request = new RequestApi(axios);
 		this.messages = new MessagesApi(axios);
 		this.media = new MediaApi(axios);
+		this.mediaImages = new MediaImagesApi(axios);
 		this.interaction = new InteractionApi(axios);
 		this.meta = new MetaApi(axios);
 		this.groups = new GroupsApi(axios);
@@ -2063,6 +2186,16 @@ const getAccessToken = async (appId, secret) => {
 		} else log("error", `[${appId}] 获取 access_token 失败:`, err);
 		throw err;
 	}
+	/**
+	* access_token 接口的业务错误即使失败也会返回 HTTP 200，必须优先检查
+	* 响应体中的 code，不能只依赖 axios 的 HTTP 状态。
+	*/
+	const code = res.data?.code;
+	if (typeof code === "number" && code !== 0) {
+		const detail = formatOpenAPIError(200, code, res.data?.message);
+		log("error", `[${appId}] 获取 access_token 失败 | ${detail}`);
+		throw new Error(`获取 access_token 失败 | ${detail}`);
+	}
 	const accessToken = res.data?.access_token;
 	const expiresIn = Number(res.data?.expires_in);
 	if (!accessToken || !expiresIn || Number.isNaN(expiresIn)) throw new Error(`获取 access_token 失败: ${JSON.stringify(res.data)}`);
@@ -2345,10 +2478,11 @@ const hasFileToUrlHandler = () => handler.has(fileToUrlHandlerKey);
 */
 const isHttpMediaSource = (source) => HTTP_URL_RE.test(source);
 /**
-* 优先把本地/base64 富媒体转换为公网 URL；没有处理器或转换失败时返回原始来源。
+* 解析本地 / Base64 富媒体来源。
 *
-* QQ 官方的普通 file_data 上传对视频等资源更容易失败，因此 adapter 层始终把
-* fileToUrl 作为主路径，QQ 上传只做兜底。
+* 优先级为：用户自己的 `fileToUrl` 处理器 -> Markdown 图片素材管理 ->
+* 适配器内置 fileToUrl 图床 -> QQ 富媒体上传兜底。内置图床只在前两步都失败后
+* 才被允许接手，避免临时直链抢占 `qqbot-media://`；视频 / 语音仍可由内置图床取直链。
 *
 * @param ctx 适配器实例，用于记录降级日志并标明执行发送的 bot。
 * @param type 富媒体类型。
@@ -2360,51 +2494,76 @@ const isHttpMediaSource = (source) => HTTP_URL_RE.test(source);
 */
 const resolvePreferredMediaSource = async (ctx, type, source, filename, origin, purpose = "media") => {
 	const normalized = normalizeMediaSource(source);
-	if (isHttpMediaSource(normalized)) return {
+	if (isHttpMediaSource(normalized) || QQBOT_MEDIA_RE.test(normalized)) return {
 		source: normalized,
 		via: "public-url"
 	};
-	if (!hasFileToUrlHandler()) return {
-		source: normalized,
-		via: "fallback"
-	};
-	try {
-		const extra = {
-			selfId: ctx.selfId,
-			purpose,
-			origin
-		};
-		const result = await fileToUrl(type, normalized, filename || DEFAULT_FILENAME[type], extra);
-		/**
-		* `handler.has` 只判断该 key 下是否注册过处理器，不代表真的有处理器接手：
-		* 所有处理器都调用 next() 放行时，fileToUrl 会返回 undefined。此时不属于
-		* 异常，安静地走 QQ 上传兜底即可，不必输出 warn 噪音。
-		*/
-		if (!result?.url) {
-			ctx.logger("debug", `[sendQQ] 没有 fileToUrl 处理器接手 ${type}，改用 QQ 上传兜底`);
-			return {
-				source: normalized,
-				via: "fallback"
-			};
-		}
-		/** 只有 image 会带宽高，其余类型按声明就没有这两个字段。 */
-		const { width, height } = result;
-		const size = typeof width === "number" && typeof height === "number" ? {
-			width,
-			height
+	/** 将 fileToUrl 结果归一为发送链路需要的来源结构。 */
+	const toPreferred = (result) => {
+		const size = typeof result.width === "number" && typeof result.height === "number" ? {
+			width: result.width,
+			height: result.height
 		} : void 0;
 		return {
 			source: result.url,
 			via: "file-to-url",
 			size
 		};
-	} catch (err) {
-		ctx.logger("warn", `[sendQQ] ${type} 转 URL 失败，改用 QQ 上传兜底:`, err);
-		return {
-			source: normalized,
-			via: "fallback"
-		};
-	}
+	};
+	/**
+	* 调用 fileToUrl 链。
+	*
+	* 第一次传 `allowBuiltinFileToUrl: false`，内置处理器会主动放行；素材管理
+	* 失败后再传 true，允许内置图床接手。用户自己的处理器在两轮中都可以响应。
+	*/
+	const tryFileToUrl = async (allowBuiltinFileToUrl) => {
+		if (!hasFileToUrlHandler()) return {};
+		try {
+			const extra = {
+				selfId: ctx.selfId,
+				purpose,
+				origin,
+				allowBuiltinFileToUrl
+			};
+			const result = await fileToUrl(type, normalized, filename || DEFAULT_FILENAME[type], extra);
+			return { result: result?.url ? result : void 0 };
+		} catch (err) {
+			return { error: err };
+		}
+	};
+	/**
+	* 图片要进入 Markdown 时，如果用户图床不可用，优先使用官方素材管理。
+	* 该接口返回的 `qqbot-media://` 可以直接写进 Markdown，且不依赖公网 URL。
+	*/
+	const tryQQBotMedia = async () => {
+		if (type !== "image" || purpose !== "markdown") return void 0;
+		try {
+			const size = await getImageSize(normalized).catch(() => void 0);
+			const uploaded = await ctx.super.mediaImages.upload(normalized, filename);
+			ctx.logger("debug", `[sendQQ] 素材管理上传成功，ttl=${uploaded.ttl}s: ${uploaded.url}`);
+			return {
+				source: uploaded.url,
+				via: "qqbot-media",
+				size
+			};
+		} catch (err) {
+			ctx.logger("debug", `[sendQQ] ${type} 素材管理上传失败，继续尝试内置图床:`, err);
+			return;
+		}
+	};
+	const userStage = await tryFileToUrl(false);
+	if (userStage.result) return toPreferred(userStage.result);
+	const material = await tryQQBotMedia();
+	if (material) return material;
+	const builtinStage = await tryFileToUrl(true);
+	if (builtinStage.result) return toPreferred(builtinStage.result);
+	const failure = builtinStage.error || userStage.error;
+	if (failure) ctx.logger("warn", `[sendQQ] ${type} 转 URL 失败，改用 QQ 上传兜底:`, failure);
+	else ctx.logger("debug", `[sendQQ] 没有 fileToUrl 处理器接手 ${type}，改用 QQ 上传兜底`);
+	return {
+		source: normalized,
+		via: "fallback"
+	};
 };
 
 //#endregion
@@ -2419,6 +2578,8 @@ const MARKDOWN_IMAGE_RE = /!\[([^\]]*)]\(\s*(<[^>]+>|[^\s)]+)(?:\s+["'][^"']*["'
 * 保留。
 */
 const EXPLICIT_IMAGE_SIZE_RE = /#(\d+)px\s+#(\d+)px/;
+/** 已经是可直接写入 Markdown 的图片地址。 */
+const isDirectImageSource = (source) => /^https?:\/\//i.test(source) || QQBOT_MEDIA_RE.test(source);
 /**
 * 调用 fileToUrl 并确认真的拿到了 URL。
 *
@@ -2451,6 +2612,7 @@ const buildMarkdownImageLine = async (url, alt = "", size) => {
 	const explicit = alt.match(EXPLICIT_IMAGE_SIZE_RE);
 	if (explicit) return `![${alt.replace(EXPLICIT_IMAGE_SIZE_RE, "").trim()} #${explicit[1]}px #${explicit[2]}px](${url})`;
 	const desc = alt.trim() || "karin";
+	/** QQ 客户端对缺失尺寸的图片会使用很小的默认值，探测失败也必须写入兜底尺寸。 */
 	const resolved = size ?? await getImageSize(url).catch(() => ({
 		width: 300,
 		height: 300
@@ -2484,7 +2646,7 @@ const buildPendingMarkdownImageLine = (source, alt = "", size) => {
 */
 const imagesToMarkdown = async (urls, extra) => {
 	return Promise.all(urls.map(async (file) => {
-		if (file.startsWith("http")) return buildMarkdownImageLine(file);
+		if (isDirectImageSource(file)) return buildMarkdownImageLine(file);
 		const { url, width, height } = await imageToUrl(file, extra);
 		return buildMarkdownImageLine(url, "", {
 			width,
@@ -2500,7 +2662,7 @@ const imagesToMarkdown = async (urls, extra) => {
 * @returns markdown 图片行。
 */
 const markdownPartToLine = async (part, extra) => {
-	if (part.source.startsWith("http")) return buildMarkdownImageLine(part.source, part.alt);
+	if (isDirectImageSource(part.source)) return buildMarkdownImageLine(part.source, part.alt);
 	const { url, width, height } = await imageToUrl(part.source, extra);
 	return buildMarkdownImageLine(url, part.alt, {
 		width,
@@ -2595,7 +2757,8 @@ const sendQQMarkdown = async (ctx, contact, grouping, target) => {
 	}
 	const mediaItems = [];
 	for (const file of fallbackImages) {
-		const res = await ctx.super.media.uploadFallback(target, contact.peer, "image", file, false);
+		/** 图片兜底固定走分片上传，避免普通二进制直传在本地/Base64 场景下不稳定。 */
+		const res = await ctx.super.media.uploadFallback(target, contact.peer, "image", file, false, void 0, true);
 		mediaItems.push(ctx.super.qq.media(res.file_info));
 	}
 	for (const m of grouping.media) {
@@ -3457,6 +3620,34 @@ const getAdapterConfig = (bot) => {
 	return cfg;
 };
 
+//#endregion
+//#region src/core/adapter/self-avatar.ts
+/**
+* 机器人自身头像的在途请求存储。
+*
+* 机器人没有可拼进 qlogo CDN 的自身 openid（selfId 就是 appId），只能走官方
+* `GET /users/@me` 取 avatar。在途请求挂在 WeakMap 而不是实例字段上，保持
+* AdapterQQBot 只包含 AdapterType 约束的成员；bot 重建后旧实例随之释放。
+*/
+const pending = /* @__PURE__ */ new WeakMap();
+/**
+* 获取机器人自身的真实头像，并发调用只请求一次，失败后释放以便下次重试。
+* @param bot 适配器实例。
+* @returns `/users/@me` 的 avatar，拉取失败时退回 qlogo 拼接模式（默认头像）。
+*/
+const selfAvatarUrl = (bot) => {
+	const existed = pending.get(bot);
+	if (existed) return existed;
+	const fallback = `https://thirdqq.qlogo.cn/qqapp/${bot.cfg.appId}/${bot.selfId}/0`;
+	const task = bot.super.meta.getMe().then((me) => me.avatar || fallback).catch((err) => {
+		bot.logger("warn", `[getAvatarUrl] 获取机器人自身头像失败，退回默认拼接: ${err instanceof Error ? err.message : err}`);
+		pending.delete(bot);
+		return fallback;
+	});
+	pending.set(bot, task);
+	return task;
+};
+
 //#endregion
 //#region src/core/adapter/base.ts
 /**
@@ -3683,8 +3874,13 @@ var AdapterQQBot = class extends AdapterBase {
 	}
 	/**
 	* 获取头像 url
+	*
+	* 第三方头像 CDN 的模式是 `qqapp/{appId}/{openid}/{size}`，只有拼用户 openid 才有效；
+	* 机器人自身没有可用的 openid（selfId 就是 appId，拼出 appId/appid 只会得到默认头像），
+	* 因此目标是自己时改走官方 `GET /users/@me` 返回的 avatar 字段，取值与缓存见 self-avatar。
 	*/
 	async getAvatarUrl(_userId, _size = 0) {
+		if (_userId && (_userId === this.selfId || _userId === this.selfSubId("id"))) return selfAvatarUrl(this);
 		return `https://thirdqq.qlogo.cn/qqapp/${this.cfg.appId}/${_userId}/${_size}`;
 	}
 	/**
@@ -4322,7 +4518,7 @@ const pushMarkdownText = (text, elements) => {
 * 图片和原生 Markdown；这里按原顺序恢复为 Karin `text`、`image`、`markdown`。
 */
 const pushQQMarkdown = (text, elements) => {
-	const imageReg = /!\[([^\]]*)\]\((https?:\/\/[^\s)]+)\)/g;
+	const imageReg = /!\[([^\]]*)\]\(((?:https?:\/\/|qqbot-media:\/\/)[^\s)]+)\)/g;
 	let lastIndex = 0;
 	let matched = false;
 	let match;
@@ -4350,7 +4546,7 @@ const pushQQMarkdown = (text, elements) => {
 */
 const tokenizeContent = (content = "") => {
 	const tokens = [];
-	const knownTag = /<faceType=\d+,faceId="[^"]*",ext="[^"]*">|<qqbot-at-user id="[^"]+"\s*\/?>|<qqbot-at-everyone\s*\/?>|<@!?[A-Za-z0-9]+>/g;
+	const knownTag = /<faceType=\d+,faceId="[^"]*",ext="[^"]*">|<qqbot-at-user id="[^"]+"\s*\/?>|<qqbot-at-everyone\s*\/?>|<@!?[^>]+>/g;
 	let lastIndex = 0;
 	let match;
 	while (match = knownTag.exec(content)) {
@@ -6110,4 +6306,4 @@ const bootstrap = async () => {
 bootstrap();
 
 //#endregion
-export { Http, QQBotApi, RequestApi };
+export { QQBotApi };

package/dist/{utils-u17tvC2U.js → utils-YkZrLNvO.js}

@@ -1,5 +1,5 @@
 import "./config-BgCU6apn.js";
 import "./logger-sza6kuy3.js";
-import "./common-DwVsAvIo.js";
+import "./common-D4MDcmOI.js";
 
 export {  };

package/dist/web.config.js

@@ -1,5 +1,5 @@
 import { a as readConfigFile, n as config, o as writeConfig, s as pkg } from "./config-BgCU6apn.js";
-import "./utils-u17tvC2U.js";
+import "./utils-YkZrLNvO.js";
 import karin, { components, defineConfig } from "node-karin";
 
 //#region src/web.config.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karinjs/adapter-qqbot",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "karin adapter for QQ Official Bot (2.0)",
   "homepage": "https://github.com/KarinJS/karin-plugin-adapter-qqbot",
   "bugs": {