@napuketto/kernel 0.1.1 → 0.2.1

package/dist/index.mjs

@@ -708,17 +708,17 @@ function videoToCanonical(video) {
 		type: "video",
 		path: ""
 	};
-	const path = video.filePath ?? video.videoUrl ?? "";
-	const url = video.videoUrl;
-	if (url === void 0) return {
+	const base = {
 		type: "video",
-		path
-	};
-	return {
-		type: "video",
-		path,
-		url
+		path: video.filePath ?? video.videoUrl ?? ""
 	};
+	if (video.videoUrl !== void 0) base.url = video.videoUrl;
+	const thumb = video.thumbPath?.get(0);
+	if (thumb !== void 0 && thumb !== "") base.thumbPath = thumb;
+	if (video.thumbWidth !== void 0 && video.thumbWidth > 0) base.width = video.thumbWidth;
+	if (video.thumbHeight !== void 0 && video.thumbHeight > 0) base.height = video.thumbHeight;
+	if (video.fileTime !== void 0 && video.fileTime > 0) base.durationSec = video.fileTime;
+	return base;
 }
 /** FILE 元素 → canonical file。 */
 function fileToCanonical(file) {
@@ -824,7 +824,7 @@ function toSendElements(elements) {
 				}
 			});
 			break;
-		case "video":
+		case "video": throw kernelError("视频发送需经 MsgApi 预处理（prepareVideoElement）", "INVALID_PARAM");
 		case "file":
 		case "forward":
 		case "json":
@@ -1231,6 +1231,27 @@ const PTT_WAVE_AMPLITUDES = [
 	15,
 	17
 ];
+/**
+* VIDEO 元素发送契约值（2026-10-17 收向实测字段 + 发送实测调通）。
+*
+* 依据：历史视频消息 `getLatestDbMsgs` 的 videoElement 实测快照（fileFormat /
+* busiType / subBusiType / storeID / original / videoFrom / sourceVideoCodecFormat
+* 均为实测出现的取值）。2026-10-17 18:12 自建宿主实测调通：`sendMsg` 成功
+* （sendStatus 2/3，群内可播放）；关键坑是**缩略图目标路径必须用视频 md5**
+* （见 prepareVideoElement 注释），与字段取值无关。
+*/
+const VIDEO_FILE_FORMAT = 0;
+const VIDEO_BUSI_TYPE = 0;
+const VIDEO_SUB_BUSI_TYPE = 0;
+const VIDEO_STORE_ID = 1;
+const VIDEO_ORIGINAL = true;
+const VIDEO_FROM = 0;
+const VIDEO_SOURCE_CODEC_FORMAT = 0;
+/** 视频缩略图在 thumbPath Map 中的 key（收向实测 Map<0, path>）。 */
+const VIDEO_THUMB_KEY = 0;
+/** getRichMediaFilePathForGuild 的 downloadType：1 = 原文件，2 = 缩略图。 */
+const RICH_MEDIA_DOWNLOAD_TYPE_ORIGIN = 1;
+const RICH_MEDIA_DOWNLOAD_TYPE_THUMB = 2;
 /** downloadRichMedia 契约值（2026-09-08 B1 实测：downloadType=2 可用 / thumbSize=0）。 */
 const DOWNLOAD_TYPE_COMMON = 2;
 const THUMB_SIZE_NONE = 0;
@@ -1244,20 +1265,20 @@ function sleep$1(ms) {
 	});
 }
 /** 读文件 stat（富媒体发送预处理；文件不存在抛 INVALID_PARAM）。 */
-async function statFile(path) {
+async function statFile(path, label = "图片") {
 	try {
 		return await stat(path);
 	} catch {
-		throw kernelError(`图片文件不存在: ${path}`, "INVALID_PARAM");
+		throw kernelError(`${label}文件不存在: ${path}`, "INVALID_PARAM");
 	}
 }
 /** 计算文件 md5（十六进制小写）。 */
-async function hashFile(path) {
+async function hashFile(path, label = "图片") {
 	try {
 		const buf = await readFile(path);
 		return createHash("md5").update(buf).digest("hex");
 	} catch {
-		throw kernelError(`图片文件读取失败: ${path}`, "INVALID_PARAM");
+		throw kernelError(`${label}文件读取失败: ${path}`, "INVALID_PARAM");
 	}
 }
 /**
@@ -1349,6 +1370,9 @@ var MsgApi = class {
 			case "voice":
 				out.push(await this.preparePttElement(el.path));
 				break;
+			case "video":
+				out.push(await this.prepareVideoElement(el));
+				break;
 			default: out.push(...toSendElements([el]));
 		}
 		return out;
@@ -1420,10 +1444,61 @@ var MsgApi = class {
 		};
 	}
 	/**
-	* 富媒体文件放置（PIC/PTT 共用）：md5 + 文件名 → QQ 内部目标路径
-	* （getRichMediaFilePathForGuild）→ util.copyFile 放置 → 返回相对数据根路径。
+	* VIDEO 元素预处理：md5 → 目标路径 → copyFile → 完整 videoElement。
+	*
+	* 字段依据：2026-10-17 收向实测（历史视频消息 videoElement 全字段快照）+
+	* 发送实测（2026-10-17 18:12 自建宿主发送成功，群内可播放）：
+	*  1. `thumbPath` 必须是真实 `Map<number, string>`（收向实测 `Map<0, path>`）——
+	*     经 JSON/IPC 传参会退化成 `{}`，wrapper 转换失败；
+	*  2. **缩略图目标路径用视频 md5**（`Video/<YYYY-MM>/Thumb/<videoMd5>_0.png`）：
+	*     真实消息实测 videoMd5=`3d27…`、thumbMd5=`46da…`，落盘文件名却是
+	*     `3d27…_0.png`；此前按 thumbMd5 放置 → native 传输按视频 md5 找不到缩略图
+	*     → `rich media transfer failed`（20+ 组字段变体都无效的真正原因）；
+	*  3. `thumbMd5` 是缩略图**内容**的 md5，与文件名无关；`fileTime` 为秒。
+	*/
+	async prepareVideoElement(el) {
+		const file = await statFile(el.path, "视频");
+		const md5 = await hashFile(el.path, "视频");
+		const fileName = basename(el.path);
+		const videoElement = {
+			fileName,
+			filePath: await this.placeMediaFile(el.path, ElementType.VIDEO, md5, fileName, RICH_MEDIA_DOWNLOAD_TYPE_ORIGIN),
+			fileSize: String(file.size),
+			videoMd5: md5,
+			fileTime: el.durationSec ?? 0,
+			fileFormat: VIDEO_FILE_FORMAT,
+			busiType: VIDEO_BUSI_TYPE,
+			subBusiType: VIDEO_SUB_BUSI_TYPE,
+			fileUuid: "",
+			fileSubId: "",
+			storeID: VIDEO_STORE_ID,
+			original: VIDEO_ORIGINAL,
+			videoFrom: VIDEO_FROM,
+			sourceVideoCodecFormat: VIDEO_SOURCE_CODEC_FORMAT
+		};
+		if (el.thumbPath !== void 0 && el.thumbPath !== "") {
+			const thumbSize = await statFile(el.thumbPath, "视频缩略图");
+			const thumbMd5 = await hashFile(el.thumbPath, "视频缩略图");
+			const thumbRelPath = await this.placeMediaFile(el.thumbPath, ElementType.VIDEO, md5, `${md5}${extname(el.thumbPath)}`, RICH_MEDIA_DOWNLOAD_TYPE_THUMB);
+			videoElement.thumbMd5 = thumbMd5;
+			videoElement.thumbSize = thumbSize.size;
+			videoElement.thumbWidth = el.width ?? 0;
+			videoElement.thumbHeight = el.height ?? 0;
+			videoElement.thumbPath = /* @__PURE__ */ new Map([[VIDEO_THUMB_KEY, thumbRelPath]]);
+		}
+		return {
+			elementType: ElementType.VIDEO,
+			elementId: "",
+			videoElement
+		};
+	}
+	/**
+	* 富媒体文件放置（PIC/PTT/VIDEO 共用）：md5 + 文件名 → QQ 内部目标路径
+	* （getRichMediaFilePathForGuild）→ util.copyFile 放置 → 返回目标路径。
+	*
+	* `downloadType`：1 = 原文件（Ori），2 = 缩略图（Thumb，视频缩略图必须）。
 	*/
-	async placeMediaFile(path, elementType, md5, fileName) {
+	async placeMediaFile(path, elementType, md5, fileName, downloadType = RICH_MEDIA_DOWNLOAD_TYPE_ORIGIN) {
 		const service = this.service;
 		const util = this.util;
 		const relPath = service.getRichMediaFilePathForGuild({
@@ -1433,7 +1508,7 @@ var MsgApi = class {
 			elementSubType: 0,
 			thumbSize: 0,
 			needCreate: true,
-			downloadType: 1,
+			downloadType,
 			file_uuid: ""
 		});
 		if (util !== null) {