@karinjs/adapter-qqbot 3.3.1 → 3.4.0

package/dist/apps/qqbot-file-to-url.d.ts

@@ -1,4 +1,81 @@
+import { i as Scene, r as MediaType } from "../base-Dw5yfdft.js";
+import { ElementTypes } from "node-karin";
+//#region src/core/adapter/media-source.d.ts
+/**
+ * 本次发送归属的上传会话。
+ *
+ * QQ 的 openid 按 bot 隔离，上传接口的路径参数只接受该 bot 可见的
+ * group_openid / user_openid。因此把真实发送目标一并交给 fileToUrl 处理器，
+ * 需要借 QQ 通道上传的处理器才能用对会话，而不是猜一个。
+ */
+interface UploadOrigin {
+  /** 会话类型。 */
+  scene: Scene;
+  /** 目标 group_openid 或 user_openid。 */
+  peer: string;
+}
+/**
+ * 拿到 URL 之后的用途。
+ *
+ * - markdown：URL 会被写进 markdown 正文，必须是公网可访问地址；
+ * - media：URL 只是交给 QQ 富媒体接口去下载转存，本地路径同样可用。
+ */
+type UploadPurpose = 'markdown' | 'media';
+/**
+ * 传给 fileToUrl 处理器的附加信息。
+ *
+ * 处理器通过 `args.args` 读取。对不认识这些字段的第三方处理器没有影响，
+ * 行为与之前一致。
+ */
+interface FileToUrlExtra {
+  /** 正在执行本次发送的 bot，用于让上传走同一个 bot。 */
+  selfId: string;
+  /** 本次转换的用途。 */
+  purpose: UploadPurpose;
+  /** 本次发送归属的上传会话；频道场景没有可用 openid 时为 undefined。 */
+  origin?: UploadOrigin;
+  /**
+   * 是否允许适配器内置的 fileToUrl 处理器接手。
+   *
+   * 发送链路会先传 false，让用户处理器和 QQ 素材管理依次尝试；两者都失败后
+   * 再传 true 调用内置图床。用户处理器可以忽略该字段。
+   */
+  allowBuiltinFileToUrl?: boolean;
+}
+//#endregion
 //#region src/apps/qqbot-file-to-url.d.ts
+/**
+ * 内置 `fileToUrl` 处理器：用 QQ 官方分片上传充当临时图床。
+ *
+ * 发送链路会先尝试用户自己的 `fileToUrl` 和 QQ 素材管理；两者都失败后才把
+ * `allowBuiltinFileToUrl` 设为 true，允许本处理器接手。这样图片优先得到
+ * `qqbot-media://`，临时直链只作为 Markdown 内嵌的最后手段，再失败才降级为
+ * 独立的 `msg_type=7` 富媒体消息。
+ *
+ * 只在以下条件全部满足时接手，其余情况一律放行给链路上的其他处理器：
+ * - 资源要被写进 markdown 正文（富媒体上传不需要先换成 URL）；
+ * - 类型是图片 / 视频 / 语音（QQ 不为文件类型返回直链）；
+ * - 允许内置图床接手；
+ * - 能确定执行上传的 bot 与归属会话（频道场景没有可用 openid）。
+ */
+/** 内置 fileToUrl 处理器的接手条件。 */
+interface BuiltinFileToUrlInput {
+  type: MediaType;
+  purpose?: FileToUrlExtra['purpose'];
+  selfId?: string;
+  origin?: FileToUrlExtra['origin'];
+  allowBuiltinFileToUrl?: boolean;
+}
+/**
+ * 判断内置处理器是否应接手本次 fileToUrl 请求。
+ *
+ * 发送链路在用户处理器和素材管理阶段会传 `allowBuiltinFileToUrl: false`，
+ * 此时内置图床必须放行；只有最后兜底阶段才允许接手图片。
+ *
+ * @param input 当前 fileToUrl 请求的媒体类型与上下文。
+ * @returns 是否由内置处理器处理。
+ */
+declare const shouldHandleBuiltinFileToUrl: (input: BuiltinFileToUrlInput) => boolean;
 declare const qqbotFileToUrl: import("node-karin").Handler;
 //#endregion
-export { qqbotFileToUrl };
+export { BuiltinFileToUrlInput, qqbotFileToUrl, shouldHandleBuiltinFileToUrl };

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

@@ -1,23 +1,19 @@
-import { n as getImageSize } from "../common-DwVsAvIo.js";
+import { n as getImageSize } from "../common-D4MDcmOI.js";
 import karin, { getAllBot } from "node-karin";
 
 //#region src/apps/qqbot-file-to-url.ts
 /**
-* 内置 `fileToUrl` 处理器：用 QQ 官方分片上传充当临时图床。
+* 判断内置处理器是否应接手本次 fileToUrl 请求。
 *
-* 分片上传完成后，合并响应会带上资源的下载直链。有了这个地址，本地图片、截图、
-* base64 图片就能以 markdown 图片语法进入消息正文，和文本、按钮合并成一条消息，
-* 而不是退化成一条独立的富媒体消息。
+* 发送链路在用户处理器和素材管理阶段会传 `allowBuiltinFileToUrl: false`，
+* 此时内置图床必须放行；只有最后兜底阶段才允许接手图片。
 *
-* 无需任何配置：适配器发送消息时会把执行发送的 bot 和真实发送目标一并交给本
-* 处理器，上传因此总是发生在同一个 bot、同一个会话下。QQ 的 openid 按 bot
-* 隔离，这一点不能靠猜。上传只借用会话的上传通道，不会往会话里发任何消息。
-*
-* 只在以下条件全部满足时接手，其余情况一律放行给链路上的其他处理器：
-* - 资源要被写进 markdown 正文（富媒体上传不需要先换成 URL）；
-* - 类型是图片 / 视频 / 语音（QQ 不为文件类型返回直链）；
-* - 能确定执行上传的 bot 与归属会话（频道场景没有可用 openid）。
+* @param input 当前 fileToUrl 请求的媒体类型与上下文。
+* @returns 是否由内置处理器处理。
 */
+const shouldHandleBuiltinFileToUrl = (input) => {
+	return input.purpose === "markdown" && input.type !== "file" && input.allowBuiltinFileToUrl !== false && !!input.selfId && !!input.origin;
+};
 /**
 * 判断已注册的 bot 是否由本插件提供。
 *
@@ -53,23 +49,23 @@ const toUploadSource = (file) => {
 const qqbotFileToUrl = karin.handler("fileToUrl", async (payload, next) => {
 	/** fileToUrl 把第四个参数原样放在 args 字段下。 */
 	const { file, type, filename, args: extra } = payload;
-	/**
-	* 富媒体上传接受本地文件与 base64，先换成 URL 再交给 QQ 反而多一次往返，
-	* 而且那次往返仍然是 QQ 自己下载转存，没有收益。
-	*/
-	if (extra?.purpose !== "markdown") return next();
-	/** QQ 只对图片 / 视频 / 语音返回下载直链。 */
-	if (type === "file") return next();
-	/** 频道场景用 channel_id，没有上传接口要求的 openid。 */
-	const origin = extra.origin;
-	if (!extra.selfId || !origin) return next();
-	const bot = findBot(extra.selfId);
+	const selfId = extra?.selfId;
+	const origin = extra?.origin;
+	if (!selfId || !origin) return next();
+	if (!shouldHandleBuiltinFileToUrl({
+		type,
+		purpose: extra?.purpose,
+		selfId,
+		origin,
+		allowBuiltinFileToUrl: extra?.allowBuiltinFileToUrl
+	})) return next();
+	const bot = findBot(selfId);
 	if (!bot) return next();
 	try {
 		const { url, response } = await bot.super.media.uploadForUrl(origin.scene, origin.peer, type, toUploadSource(file), filename);
 		bot.logger("debug", `[内置图床] 已取得直链，有效期 ${response.ttl}s: ${url}`);
 		if (type !== "image") return { url };
-		/** markdown 图片语法需要宽高；解析不出来时 getImageSize 会给出保守默认值。 */
+		/** Markdown 图片必须携带宽高，否则 QQ 客户端会使用极小的默认尺寸。 */
 		const { width, height } = await getImageSize(file);
 		return {
 			url,
@@ -91,4 +87,4 @@ const qqbotFileToUrl = karin.handler("fileToUrl", async (payload, next) => {
 });
 
 //#endregion
-export { qqbotFileToUrl };
+export { qqbotFileToUrl, shouldHandleBuiltinFileToUrl };