@napuketto/kernel 0.5.3 → 0.6.0

package/dist/index.cjs

@@ -1541,6 +1541,72 @@ var GroupApi = class {
 		} else res = await this.service.removeGroupEssence(param);
 		checkLooseResult(label, res);
 	}
+	/**
+	* 群公告列表（get_group_announcements；getGroupBulletin 返回形状待探测校准，
+	* 兼容 result 数组 / result.bulletins 等宽松提取）。
+	*/
+	async getGroupAnnouncements(groupCode) {
+		let raw;
+		try {
+			raw = await this.service.getGroupBulletin(groupCode);
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`getGroupBulletin 调用失败: ${errMsgString$3(e)}`, "UNKNOWN");
+		}
+		unwrap("getGroupBulletin", toResultNumber(raw.result), raw.errMsg);
+		return extractBulletins(raw.result);
+	}
+	/**
+	* 发群公告（send_group_announcement；imagePath 提供时先 uploadGroupBulletinPic
+	* 再带 picId 发布——两步参数形状均待探测校准）。
+	*/
+	async publishGroupAnnouncement(groupCode, content, imagePath) {
+		let picId;
+		if (imagePath !== void 0 && imagePath !== "") picId = await this.uploadBulletinPic(groupCode, imagePath);
+		try {
+			checkLooseResult("publishGroupBulletin", await this.service.publishGroupBulletin({
+				groupCode,
+				content,
+				...picId !== void 0 ? { picId } : {}
+			}));
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`publishGroupBulletin 调用失败: ${errMsgString$3(e)}`, "UNKNOWN");
+		}
+	}
+	/** 删群公告（delete_group_announcement；参数待探测校准）。 */
+	async deleteGroupAnnouncement(groupCode, announcementId) {
+		try {
+			checkLooseResult("deleteGroupBulletin", await this.service.deleteGroupBulletin(groupCode, announcementId));
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`deleteGroupBulletin 调用失败: ${errMsgString$3(e)}`, "UNKNOWN");
+		}
+	}
+	/** 专属头衔（set_group_member_special_title；setIdentityTitleInfo 参数待校准）。 */
+	async setMemberSpecialTitle(groupCode, uid, title) {
+		try {
+			checkLooseResult("setIdentityTitleInfo", await this.service.setIdentityTitleInfo(groupCode, uid, title));
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`setIdentityTitleInfo 调用失败: ${errMsgString$3(e)}`, "UNKNOWN");
+		}
+	}
+	/** 群头像（set_group_avatar；GroupService.setHeader 参数待校准）。 */
+	async setGroupAvatar(groupCode, imagePath) {
+		try {
+			checkLooseResult("setHeader", await this.service.setHeader(groupCode, imagePath));
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`setHeader(group) 调用失败: ${errMsgString$3(e)}`, "UNKNOWN");
+		}
+	}
+	/** 公告图片上传（uploadGroupBulletinPic 返回 picId 待校准，失败原样上抛）。 */
+	async uploadBulletinPic(groupCode, imagePath) {
+		const res = await this.service.uploadGroupBulletinPic(groupCode, imagePath);
+		checkLooseResult("uploadGroupBulletinPic", res);
+		return typeof res?.picId === "string" ? res.picId : "";
+	}
 	/** @all 剩余次数（get_group_at_all_remain）。 */
 	async getGroupRemainAtTimes(groupCode) {
 		const raw = await this.service.getGroupRemainAtTimes(groupCode);
@@ -1552,6 +1618,29 @@ var GroupApi = class {
 		};
 	}
 };
+/** result 字段宽松取数（数字直接用，缺省 0 = 成功语义）。 */
+function toResultNumber(result) {
+	return typeof result === "number" ? result : 0;
+}
+/** 公告列表宽松提取（result 数组 / { bulletins } / { result: 数组 } 兼容，形状待校准）。 */
+function extractBulletins(result) {
+	const candidates = [result];
+	if (result !== null && typeof result === "object") {
+		const rec = result;
+		for (const key of [
+			"bulletins",
+			"announcementList",
+			"result",
+			"list"
+		]) candidates.push(rec[key]);
+	}
+	for (const candidate of candidates) if (Array.isArray(candidate)) return candidate.filter((item) => item !== null && typeof item === "object");
+	return [];
+}
+/** 未知异常 → 消息字符串。 */
+function errMsgString$3(e) {
+	return e instanceof Error ? e.message : String(e);
+}
 /**
 * 从 getGroupDetailInfo 返回提取群详情（兼容三种形状）：
 *  - result 为对象 → 详情直接在其中（最常见）
@@ -1725,6 +1814,28 @@ function sleep$1(ms) {
 		setTimeout(resolve, ms);
 	});
 }
+/** 未知异常 → 消息字符串。 */
+function errMsgString$2(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+/** 语音下载完成判定：有路径且（传输完成或末次轮询）才返回元素，否则 null。 */
+function pttDownloadResult(latest, isLastPoll) {
+	if (latest === void 0) return null;
+	const hasPath = latest.filePath !== void 0 && latest.filePath !== "";
+	const done = latest.transferStatus === 2 || latest.transferStatus === 4;
+	return hasPath && (done || isLastPoll) ? latest : null;
+}
+/** 收藏表情项 → url（字段名待校准，url/imageUrl/emojiUrl 逐个兜底）。 */
+function extractFavEmojiUrls(list) {
+	const out = [];
+	for (const item of list) {
+		if (item === null || typeof item !== "object") continue;
+		const rec = item;
+		const url = rec["url"] ?? rec["imageUrl"] ?? rec["emojiUrl"];
+		if (typeof url === "string" && url !== "") out.push(url);
+	}
+	return out;
+}
 /** 读文件 stat（富媒体发送预处理；文件不存在抛 INVALID_PARAM）。 */
 async function statFile(path, label = "图片") {
 	try {
@@ -1834,6 +1945,9 @@ var MsgApi = class {
 			case "video":
 				out.push(await this.prepareVideoElement(el));
 				break;
+			case "file":
+				out.push(await this.prepareFileElement(el));
+				break;
 			default: out.push(...toSendElements([el]));
 		}
 		return out;
@@ -1954,6 +2068,28 @@ var MsgApi = class {
 		};
 	}
 	/**
+	* FILE 元素预处理（P2-2 预留口子，upload_private/group_file 落地）：
+	* pic/ptt/video 同款 NapCat 式链路——md5 → getRichMediaFilePathForGuild(FILE)
+	* → copyFile → 完整 fileElement。链路模式已验证（三类媒体同构）；fileElement
+	* 字段值（fileSize 字符串形态、fileUuid 空串等）待探测校准。
+	*/
+	async prepareFileElement(el) {
+		const file = await statFile(el.path, "文件");
+		const md5 = await hashFile(el.path, "文件");
+		const fileName = el.name !== void 0 && el.name !== "" ? el.name : (0, node_path.basename)(el.path);
+		const relPath = await this.placeMediaFile(el.path, ElementType.FILE, md5, fileName);
+		return {
+			elementType: ElementType.FILE,
+			elementId: "",
+			fileElement: {
+				fileName,
+				filePath: relPath,
+				fileSize: String(file.size),
+				fileUuid: ""
+			}
+		};
+	}
+	/**
 	* 富媒体文件放置（PIC/PTT/VIDEO 共用）：md5 + 文件名 → QQ 内部目标路径
 	* （getRichMediaFilePathForGuild）→ util.copyFile 放置 → 返回目标路径。
 	*
@@ -2047,31 +2183,72 @@ var MsgApi = class {
 	* 调用方），完全无路径抛 NOT_FOUND。
 	*/
 	async downloadPtt(msgId, target) {
-		const el = findPttElement(await this.fetchMsgsByMsgId(target, [msgId]));
-		const ptt = el?.pttElement;
-		if (el === null || ptt === void 0) throw kernelError("消息中不包含语音", "NOT_FOUND");
-		const elemId = el.elementId ?? "";
+		const found = await this.pttElementOf(msgId, target);
+		if (found === null) throw kernelError("消息中不包含语音", "NOT_FOUND");
 		await this.service.downloadRichMedia({
 			msgId,
-			elemId,
+			elemId: found.elemId,
 			chatType: target.chatType,
 			downloadType: DOWNLOAD_TYPE_COMMON,
 			thumbSize: THUMB_SIZE_NONE
 		});
 		for (let i = 0; i < PTT_POLL_TIMES; i++) {
 			await sleep$1(PTT_POLL_INTERVAL_MS);
-			const latest = findPttElement(await this.fetchMsgsByMsgId(target, [msgId]))?.pttElement;
-			if (latest === void 0) continue;
-			const done = latest.transferStatus === 2 || latest.transferStatus === 4;
-			if (latest.filePath !== void 0 && latest.filePath !== "" && done) return latest;
-			if (i === 33 && latest.filePath !== void 0 && latest.filePath !== "") return latest;
+			const result = pttDownloadResult(findPttElement(await this.fetchMsgsByMsgId(target, [msgId]))?.pttElement, i === 33);
+			if (result !== null) return result;
 		}
 		throw kernelError("语音下载未完成（超时）", "TIMEOUT");
 	}
+	/** 取消息内语音元素（无则 null；附 elemId 供主动下载）。 */
+	async pttElementOf(msgId, target) {
+		const el = findPttElement(await this.fetchMsgsByMsgId(target, [msgId]));
+		const ptt = el?.pttElement;
+		if (el === null || ptt === void 0) return null;
+		return {
+			elemId: el.elementId ?? "",
+			ptt
+		};
+	}
 	/** 发送输入状态（set_input_status；eventType=1 输入中，0 停止）。 */
 	async setInputStatus(target, eventType) {
 		await this.service.sendShowInputStatusReq(target.chatType, eventType, target.peerUid);
 	}
+	/** 戳一戳发送（send_friend/group_nudge；参数形状待探测校准，失败抛 UNKNOWN）。 */
+	async sendNudge(target, opts) {
+		const param = {
+			receiverUid: opts.receiverUid,
+			callerUid: opts.callerUid,
+			...target.chatType === ChatType.GROUP ? { confId: target.peerUid } : {}
+		};
+		try {
+			checkLooseResult("sendNudge", await this.service.sendNudge(param));
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`sendNudge 调用失败: ${errMsgString$2(e)}`, "UNKNOWN");
+		}
+	}
+	/** 会话置顶（set_peer_pin；setContactLocalTop 参数待探测校准）。 */
+	async setContactTop(target, isTop) {
+		try {
+			checkLooseResult("setContactLocalTop", await this.service.setContactLocalTop(target, isTop));
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`setContactLocalTop 调用失败: ${errMsgString$2(e)}`, "UNKNOWN");
+		}
+	}
+	/** 收藏表情列表（get_custom_face_url_list；queryFavEmojiByDesc 形状待校准）。 */
+	async queryFavEmojis() {
+		let raw;
+		try {
+			raw = await this.service.queryFavEmojiByDesc("");
+		} catch (e) {
+			throw kernelError(`queryFavEmojiByDesc 调用失败: ${errMsgString$2(e)}`, "UNKNOWN");
+		}
+		checkLooseResult("queryFavEmojiByDesc", raw);
+		const list = raw.emojiInfoList;
+		if (!Array.isArray(list)) return [];
+		return extractFavEmojiUrls(list);
+	}
 	/**
 	* 发送合并转发（send_group/private_forward_msg）。
 	* buildMultiForwardMsg 组装 MULTI_FORWARD 元素 → 直接作 sendMsg 元素发送。
@@ -2238,6 +2415,76 @@ var ProfileLikeApi = class {
 	}
 };
 //#endregion
+//#region src/apis/recent-contact.ts
+/**
+* RecentContactApi：会话列表语义化 API（P2 批次二，get_peer_pins 数据源）
+*
+* 2026-10-31 实机探测确认 getRecentContactService 有 getRecentContactList /
+* setContactListTop 等方法；返回形状待探测校准（宽松提取）。
+* 置顶数据源：isTop 过滤（ChatType 区分 friend/group 场景）。
+*/
+/** 会话列表拉取条数（覆盖置顶集合足够大；参数值待探测校准）。 */
+const RECENT_CONTACT_FETCH_COUNT = 200;
+/** 会话列表 API：从 session 拿 recent contact service，包装成语义化方法。 */
+var RecentContactApi = class {
+	service;
+	constructor(session) {
+		const service = session.getRecentContactService();
+		if (service === null || service === void 0) throw kernelError("getRecentContactService() 返回空（session 未 init）", "INVALID_STATE");
+		this.service = service;
+	}
+	/** 置顶会话列表（get_peer_pins；getRecentContactList 返回形状待探测校准）。 */
+	async getPinnedContacts() {
+		let raw;
+		try {
+			raw = await this.service.getRecentContactList({ count: RECENT_CONTACT_FETCH_COUNT });
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`getRecentContactList 调用失败: ${errMsgString$1(e)}`, "UNKNOWN");
+		}
+		checkLooseResult("getRecentContactList", raw);
+		return extractPinnedContacts(raw);
+	}
+};
+/** 从返回形状提取置顶会话（result 数组 / 顶层 contacts / 嵌套容器兼容，待校准）。 */
+function extractPinnedContacts(raw) {
+	const candidates = [raw.result, raw];
+	for (const container of [raw.result, raw]) {
+		if (container === null || typeof container !== "object") continue;
+		const rec = container;
+		for (const key of [
+			"contacts",
+			"data",
+			"result",
+			"list"
+		]) candidates.push(rec[key]);
+	}
+	for (const candidate of candidates) {
+		if (!Array.isArray(candidate)) continue;
+		return candidate.flatMap((item) => pinnedOf(item));
+	}
+	return [];
+}
+/** 单条会话 → 置顶项（isTop 为真且场景可判定才产出）。 */
+function pinnedOf(item) {
+	if (item === null || typeof item !== "object") return [];
+	const contact = item;
+	if (contact.isTop !== true || typeof contact.peerUid !== "string") return [];
+	if (contact.chatType === ChatType.GROUP) return [{
+		peerUid: contact.peerUid,
+		scene: "group"
+	}];
+	if (contact.chatType === ChatType.C2C) return [{
+		peerUid: contact.peerUid,
+		scene: "friend"
+	}];
+	return [];
+}
+/** 未知异常 → 消息字符串。 */
+function errMsgString$1(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+//#endregion
 //#region src/apis/richmedia.ts
 /**
 * RichMediaApi：富媒体语义化 API（ADR-009 统一错误语义，P2-14）
@@ -2283,10 +2530,11 @@ var RichMediaApi = class {
 			showOnlinedocFolder: HIDE_ONLINEDOC_FOLDER
 		};
 		const raw = await this.service.getGroupFileList(groupCode, params);
-		if (raw.result !== 0) unwrap("getGroupFileList", raw.result, raw.errMsg);
+		checkLooseResult("getGroupFileList", raw);
 		const list = extractFileList(raw.result);
-		if (parentFolderId === "") return list;
-		return list.filter((item) => item.fileInfo !== void 0 && item.fileInfo.parent === parentFolderId || item.folderInfo !== void 0 && item.folderInfo.folderUid === parentFolderId);
+		const items = list.length > 0 ? list : extractFileList(raw);
+		if (parentFolderId === "") return items;
+		return items.filter((item) => item.fileInfo !== void 0 && item.fileInfo.parent === parentFolderId || item.folderInfo !== void 0 && item.folderInfo.folderUid === parentFolderId);
 	}
 	/** 群文件系统信息（get_group_file_system_info；getGroupFileList 的 groupSpaceResult）。 */
 	async getGroupFileSystemInfo(groupCode) {
@@ -2335,6 +2583,26 @@ var RichMediaApi = class {
 		const raw = await this.service.moveGroupFile(groupCode, [GROUP_FILE_BIZ_TYPE], fileIds, "", targetFolderId);
 		if (raw.result !== 0) unwrap("moveGroupFile", raw.result, raw.errMsg);
 	}
+	/** 重命名群文件夹（rename_group_folder；形态镜像 renameGroupFile，待校准）。 */
+	async renameGroupFolder(groupCode, folderId, newName) {
+		await this.service.renameGroupFolder(groupCode, GROUP_FILE_BIZ_TYPE, folderId, newName, "");
+	}
+	/**
+	* 群文件下载链接（get_group_file_download_url）：getGroupFileList 根列表按
+	* fileId 查找取 url 字段（字段待实机确认）。已知差异：仅根目录可达——
+	* 子目录文件需 parentFolderId 逐层定位，暂不支持。
+	*/
+	async getGroupFileDownloadUrl(groupCode, fileId) {
+		const items = await this.getGroupFileList(groupCode);
+		for (const item of items) {
+			const info = item.fileInfo;
+			if (info !== void 0 && info.fileId === fileId) {
+				if (typeof info.url === "string" && info.url !== "") return info.url;
+				throw kernelError(`群文件 ${fileId} 无下载链接（url 字段缺失，待实机校准）`, "NOT_FOUND");
+			}
+		}
+		throw kernelError(`群文件 ${fileId} 不在根目录或不存在（仅支持根目录查找）`, "NOT_FOUND");
+	}
 	/** 转存群文件（trans_group_file）。 */
 	async transGroupFile(groupCode, fileId) {
 		const raw = await this.service.transGroupFile(groupCode, fileId);
@@ -5012,6 +5280,7 @@ exports.PathWrapper = PathWrapper;
 exports.ProfileApi = ProfileApi;
 exports.ProfileLikeApi = ProfileLikeApi;
 exports.QrLoginSession = QrLoginSession;
+exports.RecentContactApi = RecentContactApi;
 exports.RichMediaApi = RichMediaApi;
 exports.TicketApi = TicketApi;
 exports.TipGroupElementType = TipGroupElementType;

package/dist/index.d.cts

@@ -337,6 +337,19 @@ interface SendMessageElement {
   arkElement?: {
     bytesData: string;
   };
+  /** 文件（upload_private/group_file；字段值待探测校准，pic/ptt 同款发送链）。 */
+  fileElement?: FileElement;
+}
+/** 戳一戳参数（sendNudge，说明书参考，字段值待探测校准）。 */
+interface NudgeParam {
+  /** 被戳者 uid。 */
+  receiverUid: string;
+  /** 发起者 uid（机器人自己）。 */
+  callerUid: string;
+  /** 会话 id（群场景 = 群号；好友场景缺省）。 */
+  confId?: string;
+  /** 场景操作码（接收侧 aioOp 同名；发送取值待校准）。 */
+  aioOp?: number;
 }
 /** 消息服务：apis/msg 用到的核心方法面。 */
 interface NodeIKernelMsgService {
@@ -411,6 +424,14 @@ interface NodeIKernelMsgService {
       faceType: string;
     };
   }): Promise<GeneralCallResult>;
+  /** 戳一戳发送（send_friend/group_nudge；参数形状待探测校准）。 */
+  sendNudge(param: NudgeParam): Promise<unknown>;
+  /** 会话置顶（set_peer_pin；参数待探测校准）。 */
+  setContactLocalTop(peer: Peer, isTop: boolean): Promise<unknown>;
+  /** 收藏表情查询（get_custom_face_url_list；desc 空串 = 全量，形状待校准）。 */
+  queryFavEmojiByDesc(desc: string): Promise<GeneralCallResult & {
+    emojiInfoList?: unknown;
+  }>;
 }
 //#endregion
 //#region src/types/services/group-service.d.ts
@@ -562,6 +583,25 @@ interface GroupMember {
   isRobot?: boolean;
   [key: string]: unknown;
 }
+/** 群公告（getGroupBulletin 返回项，说明书参考，待探测校准）。 */
+interface GroupBulletin {
+  /** 公告 id（delete_group_announcement 的 announcement_id）。 */
+  announcementId?: string;
+  /** 发送者 uid。 */
+  senderUid?: string;
+  /** 发送时间（秒）。 */
+  publishTime?: number;
+  /** 文本内容。 */
+  content?: string;
+  /** 公告图片（url 待实机确认）。 */
+  pic?: {
+    url?: string;
+    width?: number;
+    height?: number;
+    id?: string;
+  };
+  [key: string]: unknown;
+}
 /** 群服务：apis/group 用到的核心方法面。 */
 interface NodeIKernelGroupService {
   addKernelGroupListener(listener: unknown): number;
@@ -648,6 +688,24 @@ interface NodeIKernelGroupService {
       postscript: string;
     };
   }): Promise<void>;
+  /** 群公告列表（get_group_announcements；返回形状待探测校准）。 */
+  getGroupBulletin(groupCode: string): Promise<GeneralCallResult & {
+    result?: unknown;
+  }>;
+  /** 发群公告（send_group_announcement；参数形状待探测校准）。 */
+  publishGroupBulletin(param: {
+    groupCode: string;
+    content: string;
+    picId?: string;
+  }): Promise<unknown>;
+  /** 上传公告图片（image_uri 落盘后调用；返回 picId 待校准）。 */
+  uploadGroupBulletinPic(groupCode: string, imagePath: string): Promise<unknown>;
+  /** 删群公告（delete_group_announcement；参数待校准）。 */
+  deleteGroupBulletin(groupCode: string, announcementId: string): Promise<unknown>;
+  /** 专属头衔（set_group_member_special_title；待校准，备选 setGroupIdentitySpec）。 */
+  setIdentityTitleInfo(groupCode: string, uid: string, title: string): Promise<unknown>;
+  /** 群头像（set_group_avatar；参数待校准；Profile setHeader 同名方法）。 */
+  setHeader(groupCode: string, imagePath: string): Promise<unknown>;
 }
 //#endregion
 //#region src/types/listeners/group.d.ts
@@ -992,6 +1050,32 @@ interface NodeIKernelProfileService {
   isNull(): boolean;
 }
 //#endregion
+//#region src/types/services/recent-contact-service.d.ts
+/** 会话联系人（getRecentContactList 项，说明书参考，待探测校准）。 */
+interface RecentContact {
+  /** 会话 id（群场景 = 群号，好友场景 = uid）。 */
+  peerUid: string;
+  /** 会话类型（ChatType 值域）。 */
+  chatType: number;
+  /** 置顶标记（get_peer_pins 数据源）。 */
+  isTop?: boolean;
+  /** 对端 uin（部分返回形态带）。 */
+  peerUin?: string;
+  [key: string]: unknown;
+}
+/** 会话列表拉取参数（getRecentContactList，字段值待探测校准）。 */
+interface RecentContactFetchParam {
+  /** 拉取条数（缺省覆盖置顶集合足够大）。 */
+  count: number;
+}
+/** 会话列表服务：apis/recent-contact 用到的核心方法面。 */
+interface NodeIKernelRecentContactService {
+  /** 会话列表（get_peer_pins 数据源；返回形状待探测校准）。 */
+  getRecentContactList(param: RecentContactFetchParam): Promise<GeneralCallResult & {
+    result?: unknown;
+  }>;
+}
+//#endregion
 //#region src/types/services/richmedia-service.d.ts
 /** 群文件列表参数（getGroupFileList，说明书参考）。 */
 interface GetFileListParam {
@@ -1008,6 +1092,8 @@ interface GroupFileItemInfo {
   fileSize: string;
   fileUuid?: string;
   parent?: string;
+  /** 下载链接（get_group_file_download_url 数据源，字段待实机确认）。 */
+  url?: string;
   uploadTime?: number;
   modifyTime?: number;
   uploaderUid?: string;
@@ -1052,6 +1138,8 @@ interface NodeIKernelRichMediaService {
   deleteGroupFolder(groupCode: string, folderId: string): Promise<GeneralCallResult>;
   /** 重命名群文件（rename_group_file；参数待探测校准）。 */
   renameGroupFile(arg1: string, arg2: number, arg3: string, arg4: string, arg5: string): Promise<unknown>;
+  /** 重命名群文件夹（rename_group_folder；形态镜像 renameGroupFile，待校准）。 */
+  renameGroupFolder(arg1: string, arg2: number, arg3: string, arg4: string, arg5: string): Promise<unknown>;
   /** 移动群文件（move_group_file）。 */
   moveGroupFile(groupCode: string, busId: number[], fileList: string[], currentParentDirectory: string, targetParentDirectory: string): Promise<GeneralCallResult>;
   /** 转存群文件（trans_group_file）。 */
@@ -1231,6 +1319,8 @@ interface NodeIQQNTWrapperSession {
   /** 闪传服务（诊断用：调查 rich media transfer failed 时验证初始化触发点）。 */
   getFlashTransferService(): unknown;
   getProfileService(): unknown;
+  /** 会话列表（P2 批次二 get_peer_pins 数据源；2026-10-31 探测方法面）。 */
+  getRecentContactService(): unknown;
   getProfileLikeService(): unknown;
   getTipOffService(): unknown;
 }
@@ -1467,6 +1557,24 @@ declare class GroupApi {
   removeGroupEssence(groupCode: string, msgId: string): Promise<void>;
   /** 精华消息公共流程：按 msgId 拉消息 → add/removeGroupEssence。 */
   private setEssence;
+  /**
+   * 群公告列表（get_group_announcements；getGroupBulletin 返回形状待探测校准，
+   * 兼容 result 数组 / result.bulletins 等宽松提取）。
+   */
+  getGroupAnnouncements(groupCode: string): Promise<GroupBulletin[]>;
+  /**
+   * 发群公告（send_group_announcement；imagePath 提供时先 uploadGroupBulletinPic
+   * 再带 picId 发布——两步参数形状均待探测校准）。
+   */
+  publishGroupAnnouncement(groupCode: string, content: string, imagePath?: string): Promise<void>;
+  /** 删群公告（delete_group_announcement；参数待探测校准）。 */
+  deleteGroupAnnouncement(groupCode: string, announcementId: string): Promise<void>;
+  /** 专属头衔（set_group_member_special_title；setIdentityTitleInfo 参数待校准）。 */
+  setMemberSpecialTitle(groupCode: string, uid: string, title: string): Promise<void>;
+  /** 群头像（set_group_avatar；GroupService.setHeader 参数待校准）。 */
+  setGroupAvatar(groupCode: string, imagePath: string): Promise<void>;
+  /** 公告图片上传（uploadGroupBulletinPic 返回 picId 待校准，失败原样上抛）。 */
+  private uploadBulletinPic;
   /** @all 剩余次数（get_group_at_all_remain）。 */
   getGroupRemainAtTimes(groupCode: string): Promise<{
     canAtAll: boolean;
@@ -1640,6 +1748,13 @@ declare class MsgApi {
    *  3. `thumbMd5` 是缩略图**内容**的 md5，与文件名无关；`fileTime` 为秒。
    */
   private prepareVideoElement;
+  /**
+   * FILE 元素预处理（P2-2 预留口子，upload_private/group_file 落地）：
+   * pic/ptt/video 同款 NapCat 式链路——md5 → getRichMediaFilePathForGuild(FILE)
+   * → copyFile → 完整 fileElement。链路模式已验证（三类媒体同构）；fileElement
+   * 字段值（fileSize 字符串形态、fileUuid 空串等）待探测校准。
+   */
+  private prepareFileElement;
   /**
    * 富媒体文件放置（PIC/PTT/VIDEO 共用）：md5 + 文件名 → QQ 内部目标路径
    * （getRichMediaFilePathForGuild）→ util.copyFile 放置 → 返回目标路径。
@@ -1681,8 +1796,19 @@ declare class MsgApi {
    * 调用方），完全无路径抛 NOT_FOUND。
    */
   downloadPtt(msgId: string, target: Peer): Promise<PttElement>;
+  /** 取消息内语音元素（无则 null；附 elemId 供主动下载）。 */
+  private pttElementOf;
   /** 发送输入状态（set_input_status；eventType=1 输入中，0 停止）。 */
   setInputStatus(target: Peer, eventType: number): Promise<void>;
+  /** 戳一戳发送（send_friend/group_nudge；参数形状待探测校准，失败抛 UNKNOWN）。 */
+  sendNudge(target: Peer, opts: {
+    receiverUid: string;
+    callerUid: string;
+  }): Promise<void>;
+  /** 会话置顶（set_peer_pin；setContactLocalTop 参数待探测校准）。 */
+  setContactTop(target: Peer, isTop: boolean): Promise<void>;
+  /** 收藏表情列表（get_custom_face_url_list；queryFavEmojiByDesc 形状待校准）。 */
+  queryFavEmojis(): Promise<string[]>;
   /**
    * 发送合并转发（send_group/private_forward_msg）。
    * buildMultiForwardMsg 组装 MULTI_FORWARD 元素 → 直接作 sendMsg 元素发送。
@@ -1751,6 +1877,22 @@ declare class ProfileLikeApi {
   sendLike(uid: string, count?: number): Promise<void>;
 }
 //#endregion
+//#region src/apis/recent-contact.d.ts
+/** 置顶会话（get_peer_pins 数据项）：peerUid 按 chatType 归 friend/group。 */
+interface PinnedContact {
+  /** 会话 id（好友 = uid，群 = 群号）。 */
+  peerUid: string;
+  /** 场景：friend（C2C）/ group（GROUP）；temp 不产出。 */
+  scene: "friend" | "group";
+}
+/** 会话列表 API：从 session 拿 recent contact service，包装成语义化方法。 */
+declare class RecentContactApi {
+  private readonly service;
+  constructor(session: NodeIQQNTWrapperSession);
+  /** 置顶会话列表（get_peer_pins；getRecentContactList 返回形状待探测校准）。 */
+  getPinnedContacts(): Promise<PinnedContact[]>;
+}
+//#endregion
 //#region src/apis/richmedia.d.ts
 /** 群文件列表条目（fileInfo/folderInfo 取其一）。 */
 interface GroupFileListItem {
@@ -1784,6 +1926,14 @@ declare class RichMediaApi {
   renameGroupFile(groupCode: string, fileId: string, newName: string): Promise<void>;
   /** 移动群文件（move_group_file；targetFolder 空为根目录）。 */
   moveGroupFile(groupCode: string, fileIds: string[], targetFolderId: string): Promise<void>;
+  /** 重命名群文件夹（rename_group_folder；形态镜像 renameGroupFile，待校准）。 */
+  renameGroupFolder(groupCode: string, folderId: string, newName: string): Promise<void>;
+  /**
+   * 群文件下载链接（get_group_file_download_url）：getGroupFileList 根列表按
+   * fileId 查找取 url 字段（字段待实机确认）。已知差异：仅根目录可达——
+   * 子目录文件需 parentFolderId 逐层定位，暂不支持。
+   */
+  getGroupFileDownloadUrl(groupCode: string, fileId: string): Promise<string>;
   /** 转存群文件（trans_group_file）。 */
   transGroupFile(groupCode: string, fileId: string): Promise<void>;
 }
@@ -2790,5 +2940,5 @@ interface QQVersionInfo {
   qua: string;
 }
 //#endregion
-export { type BootEnv, BuddyCache, type BuddyCacheEventChannel, type BuddyCacheListener, type BuddyCacheOptions, type BuddyCategory, type BuddyCoreInfo, type BuddyEventChannel, type BuddyListEntry, type BuddyListener, type BuddyReq, type CanonicalElement, ChatType, ConfigBase, ConfigError, type ConfigFormat, type ConfigOptions, type ConfigSchema, type CoreContext, type CoreContextOptions, type CoreLoginOptions, DEFAULT_DATA_ROOT_NAME, type DesktopPathConfig, type DeviceInfo, type DoubtBuddyReq, type DoubtFriendRequestInfo, EXIT_CONFIG_INVALID, ElementType, type EnginInitDesktopConfig, type EssenceMsgItem, type ForceFetchClientKeyRetType, type Friend, FriendApi, FriendBridge, type FriendCategory, type GeneralCallResult, type GetFileListParam, type GrayTipElement, type GrayTipRevokeElement, GrayTipSubType, type Group, GroupApi, GroupBridge, GroupCache, type GroupCacheOptions, type GroupDetailInfo, type GroupEventChannel, type GroupFileItemInfo, type GroupFolderInfo, type GroupHonorWebInfo, GroupListUpdateType, type GroupListener, type GroupMember, type GroupMemberDataSource, type GroupMemberListChange, type GroupNotify, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, type GroupSpaceInfo, type HonorListItem, KERNEL_ERROR_CODES, KernelError, type KernelErrorCode, type ListenerEvents, type LogConfig, type LogEnvSource, type LogFileConfig, type LogFormat, type LogLevel, type LogModuleName, type LoggerOptions, type LoginAccountInfo, type LoginListItem, type LoginProgress, type LoginResult, type LoginState, MAIN_CONFIG_FILE, MsgApi, MsgBridge, type MsgEventChannel, type MsgListener, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, type NapukettoCoreOptions, type NodeIDependsAdapter, type NodeIDispatcherAdapter, type NodeIGlobalAdapter, type NodeIKernelBuddyService, type NodeIKernelGroupService, type NodeIKernelLoginService, type NodeIKernelMsgService, type NodeIKernelProfileLikeService, type NodeIKernelProfileService, type NodeIKernelRichMediaService, type NodeIKernelSessionListener, type NodeIKernelTicketService, type NodeIQQNTStartupSessionWrapper, type NodeIQQNTWrapperEngine, type NodeIQQNTWrapperSession, type NodeQQNTWrapperUtil, type PathOptions, PathWrapper, type Peer, type PlatformType, ProfileApi, ProfileLikeApi, type QQVersionContext, type QQVersionInfo, type QrCodeData, QrLoginSession, type RDeliveryConfig, type RawElement, type RawMessage, RichMediaApi, type SelfInfo, type SendMessageElement, type SessionConfigOptions, type ShutUpGroupMember, type StartNapukettoOptions, type StrangerInfo, TicketApi, type TimestampMode, type TipAioOpGrayTipElement, type TipGroupElement, TipGroupElementType, type UserDetailInfoByUin, type VendorType, WebApi, WebHonorType, type WrapperContext, type WrapperNodeApi, type WrapperSessionInitConfig, buildEngineConfig, buildLoginConfig, buildSessionConfig, configError, createCoreContext, createSessionListener as createLifecycleSessionListener, createSessionListener, createLogger, createLoginListener, createSession, createWrapper, electronProcessType, getExistingSession, getMainSession, initAndStartSession, initEngine, initSession, isKernelError, kernelError, listLoginAccounts, listQQVersions, narrowBuddyCategories, parseAppidFromMajor, parseLogConfig, parseToml, probeRuntime, quickLogin, readMachineGuid, resolveAppidQua, resolveConfigPath, resolveDataRoot, resolveQQVersion, resolveQqGlobalPath, resolveQqUserDataRoot, resolveWrapperPath, startNapuketto, startSession, stringifyToml, toCanonicalElements, toSendElements, waitForNetworkConnection, waitSessionReady };
+export { type BootEnv, BuddyCache, type BuddyCacheEventChannel, type BuddyCacheListener, type BuddyCacheOptions, type BuddyCategory, type BuddyCoreInfo, type BuddyEventChannel, type BuddyListEntry, type BuddyListener, type BuddyReq, type CanonicalElement, ChatType, ConfigBase, ConfigError, type ConfigFormat, type ConfigOptions, type ConfigSchema, type CoreContext, type CoreContextOptions, type CoreLoginOptions, DEFAULT_DATA_ROOT_NAME, type DesktopPathConfig, type DeviceInfo, type DoubtBuddyReq, type DoubtFriendRequestInfo, EXIT_CONFIG_INVALID, ElementType, type EnginInitDesktopConfig, type EssenceMsgItem, type ForceFetchClientKeyRetType, type Friend, FriendApi, FriendBridge, type FriendCategory, type GeneralCallResult, type GetFileListParam, type GrayTipElement, type GrayTipRevokeElement, GrayTipSubType, type Group, GroupApi, GroupBridge, type GroupBulletin, GroupCache, type GroupCacheOptions, type GroupDetailInfo, type GroupEventChannel, type GroupFileItemInfo, type GroupFolderInfo, type GroupHonorWebInfo, GroupListUpdateType, type GroupListener, type GroupMember, type GroupMemberDataSource, type GroupMemberListChange, type GroupNotify, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, type GroupSpaceInfo, type HonorListItem, KERNEL_ERROR_CODES, KernelError, type KernelErrorCode, type ListenerEvents, type LogConfig, type LogEnvSource, type LogFileConfig, type LogFormat, type LogLevel, type LogModuleName, type LoggerOptions, type LoginAccountInfo, type LoginListItem, type LoginProgress, type LoginResult, type LoginState, MAIN_CONFIG_FILE, MsgApi, MsgBridge, type MsgEventChannel, type MsgListener, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, type NapukettoCoreOptions, type NodeIDependsAdapter, type NodeIDispatcherAdapter, type NodeIGlobalAdapter, type NodeIKernelBuddyService, type NodeIKernelGroupService, type NodeIKernelLoginService, type NodeIKernelMsgService, type NodeIKernelProfileLikeService, type NodeIKernelProfileService, type NodeIKernelRecentContactService, type NodeIKernelRichMediaService, type NodeIKernelSessionListener, type NodeIKernelTicketService, type NodeIQQNTStartupSessionWrapper, type NodeIQQNTWrapperEngine, type NodeIQQNTWrapperSession, type NodeQQNTWrapperUtil, type NudgeParam, type PathOptions, PathWrapper, type Peer, type PlatformType, ProfileApi, ProfileLikeApi, type QQVersionContext, type QQVersionInfo, type QrCodeData, QrLoginSession, type RDeliveryConfig, type RawElement, type RawMessage, type RecentContact, RecentContactApi, type RecentContactFetchParam, RichMediaApi, type SelfInfo, type SendMessageElement, type SessionConfigOptions, type ShutUpGroupMember, type StartNapukettoOptions, type StrangerInfo, TicketApi, type TimestampMode, type TipAioOpGrayTipElement, type TipGroupElement, TipGroupElementType, type UserDetailInfoByUin, type VendorType, WebApi, WebHonorType, type WrapperContext, type WrapperNodeApi, type WrapperSessionInitConfig, buildEngineConfig, buildLoginConfig, buildSessionConfig, configError, createCoreContext, createSessionListener as createLifecycleSessionListener, createSessionListener, createLogger, createLoginListener, createSession, createWrapper, electronProcessType, getExistingSession, getMainSession, initAndStartSession, initEngine, initSession, isKernelError, kernelError, listLoginAccounts, listQQVersions, narrowBuddyCategories, parseAppidFromMajor, parseLogConfig, parseToml, probeRuntime, quickLogin, readMachineGuid, resolveAppidQua, resolveConfigPath, resolveDataRoot, resolveQQVersion, resolveQqGlobalPath, resolveQqUserDataRoot, resolveWrapperPath, startNapuketto, startSession, stringifyToml, toCanonicalElements, toSendElements, waitForNetworkConnection, waitSessionReady };
 //# sourceMappingURL=index.d.cts.map