mioku 1.0.7 → 1.0.9

package/dist/index.cjs

@@ -1,4 +1,4 @@
-const require_exec = require('./exec-CeafLFmG.cjs');
+const require_exec = require('./exec-BUUBQy_V.cjs');
 const node_fs = require_exec.__toESM(require("node:fs"));
 const node_path = require_exec.__toESM(require("node:path"));
 const node_url = require_exec.__toESM(require("node:url"));
@@ -855,6 +855,8 @@ var AdapterContextImpl = class {
 	#capabilities;
 	#logger;
 	#emit;
+	#correlator;
+	#commands;
 	#pendingStarts = new Set();
 	constructor(options) {
 		this.#state = options.state;
@@ -864,6 +866,8 @@ var AdapterContextImpl = class {
 		this.#capabilities = options.capabilities;
 		this.#logger = options.logger;
 		this.#emit = options.emit;
+		this.#correlator = options.correlator;
+		this.#commands = options.commands;
 	}
 	registerBot(bot) {
 		return this.#bots.register(bot);
@@ -927,6 +931,7 @@ var AdapterContextImpl = class {
 		};
 	}
 	async dispatch(event) {
+		this.#correlator?.observe(event);
 		if (event.kind === "message") {
 			const senderId = event.user_id;
 			if (senderId != null) {
@@ -937,6 +942,12 @@ var AdapterContextImpl = class {
 				}
 			}
 		}
+		if (event.kind === "message") {
+			const duplicate = this.#correlator?.observationOf(event)?.duplicate ?? false;
+			if (!duplicate) {
+				if (await this.#commands.dispatch(event)) return;
+			}
+		}
 		await this.#bus.dispatch(event);
 	}
 	listen(route, handler) {
@@ -1015,6 +1026,9 @@ var BotRegistry = class {
 		for (const entry of this.#bots.values()) if (entry.bot_id === key) return entry.bot;
 		return void 0;
 	}
+	find(adapter, bot_id) {
+		return this.#bots.get(connectedBotKey(adapter, bot_id))?.bot;
+	}
 	all() {
 		return Array.from(this.#bots.values()).map((entry) => entry.bot);
 	}
@@ -1049,9 +1063,13 @@ var EventBus = class {
 	#nextOrder = 0;
 	#dispatched = 0;
 	#logger = null;
+	#filter = null;
 	setLogger(logger) {
 		this.#logger = logger;
 	}
+	setFilter(filter$1) {
+		this.#filter = filter$1;
+	}
 	/** 注册事件监听，返回取消注册函数 */
 	register(route, handler, options = {}) {
 		if (!route) throw new Error("EventBus.register: route must be a non-empty string");
@@ -1085,6 +1103,11 @@ var EventBus = class {
 		const matched = [];
 		for (const reg of this.#registrations) {
 			if (reg.disposed) continue;
+			if (this.#filter) try {
+				if (!this.#filter(reg, event)) continue;
+			} catch (err) {
+				this.#logger?.("error", `Event registration filter failed for "${reg.source}"`, err);
+			}
 			if (isWildcardMatch(reg.route, event.type)) {
 				matched.push(reg);
 				continue;
@@ -1123,6 +1146,57 @@ var EventBus = class {
 	}
 };
 
+//#endregion
+//#region src/runtime/permissions.ts
+const isObject$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** 从事件对象中提取发送者 id（支持裸 id / user_id / sender.user_id） */
+const toUserId = (value) => {
+	if (typeof value === "number" || typeof value === "string" || typeof value === "bigint") return String(value);
+	if (isObject$1(value)) {
+		if ("user_id" in value) return toUserId(value.user_id);
+		if ("sender" in value) {
+			const sender = value.sender;
+			if (isObject$1(sender) && "user_id" in sender) return toUserId(sender.user_id);
+		}
+	}
+	return void 0;
+};
+/** 是否群消息 */
+const isGroupMessage = (event) => isObject$1(event) && event.kind === "message" && event.message_type === "group";
+/** 当前群群主（仅限所在群） */
+const isEventGroupOwner = (event) => {
+	if (!isGroupMessage(event)) return false;
+	return event.sender?.role === "owner";
+};
+/** 当前群群主或群管理员（仅限所在群） */
+const isEventGroupAdmin = (event) => {
+	if (!isGroupMessage(event)) return false;
+	const role = event.sender?.role;
+	return role === "owner" || role === "admin";
+};
+/** 仅看 owners 名单：bot 主人（无群身份加成） */
+const isEventMaster$1 = (event) => {
+	const id = toUserId(event);
+	if (!id) return false;
+	return isOwner(id);
+};
+/** 仅看 admins 名单：配置管理员 */
+const isEventAdminConfigOnly = (event) => {
+	const id = toUserId(event);
+	if (!id) return false;
+	return isAdmin(id);
+};
+/**
+* master 或当前群群主
+*/
+const isEventOwner$1 = (event) => isEventMaster$1(event) || isEventGroupOwner(event);
+/**
+* master、配置管理员、当前群群主或群管理员
+*/
+const isEventAdmin$1 = (event) => isEventOwner$1(event) || isEventAdminConfigOnly(event) || isEventGroupAdmin(event);
+const isEventOwnerOrAdmin$1 = (event) => isEventAdmin$1(event);
+const hasEventRight$1 = (event) => isEventOwnerOrAdmin$1(event);
+
 //#endregion
 //#region src/utils.ts
 const ChromeUA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/131.0.0.0";
@@ -1889,130 +1963,19 @@ const Services = {
 };
 
 //#endregion
-//#region src/runtime/cross-adapter-dedup.ts
-const PRUNE_INTERVAL = 128;
-const MESSAGE_TTL_MS = 15e3;
-const EVENT_TTL_MS = 6e4;
-const MAX_SIZE = 4096;
-const MAX_SEGMENTS = 16;
-const MAX_TEXT = 256;
-const contentFingerprintOf = (event) => {
-	const parts = [];
-	for (const seg of event.message) {
-		if (parts.length >= MAX_SEGMENTS) break;
-		if (seg.type === "reply") continue;
-		const data = seg.data ?? {};
-		if (seg.type === "text") {
-			const text$1 = typeof data.text === "string" ? data.text : "";
-			parts.push(`t:${text$1.slice(0, MAX_TEXT)}`);
-		} else if (seg.type === "at") {
-			const target = data.qq ?? data.target;
-			parts.push(`a:${target == null ? "" : String(target)}`);
-		} else if (seg.type === "face") parts.push("f");
-		else parts.push(seg.type);
-	}
-	return parts.join("|");
-};
-const scopeKeyOf = (event, content) => [
-	event.message_type ?? "",
-	event.sender?.nickname?.trim() || event.user_id || "",
-	content
-].join("|");
-const noticeKeyOf = (event) => [
-	event.kind,
-	event.identity.event_type,
-	event.notice_type ?? "",
-	event.sub_type ?? "",
-	event.group_id ?? "",
-	event.user_id ?? "",
-	event.operator_id ?? "",
-	event.identity.fingerprint ?? "",
-	event.identity.timestamp == null ? "" : Math.floor(event.identity.timestamp / 1e3)
-].join("|");
-const requestKeyOf = (event) => [
-	event.kind,
-	event.identity.event_type,
-	event.request_type ?? "",
-	event.sub_type ?? "",
-	event.group_id ?? "",
-	event.user_id ?? "",
-	event.comment ?? "",
-	event.identity.fingerprint ?? "",
-	event.identity.timestamp == null ? "" : Math.floor(event.identity.timestamp / 1e3)
-].join("|");
+//#region src/runtime/mioku-context.ts
+/** 仅看 owners 名单：bot 主人（无群身份加成） */
+const isEventMaster = (event) => isEventMaster$1(event);
 /**
-* 跨适配器消息去重（L2）
+* master 或当前群群主。等价于 `ctx.command({ permission: "owner" })` 的判断。
 */
-var CrossAdapterEventDeduplicator = class {
-	#entries = new Map();
-	#inserts = 0;
-	#dropped = 0;
-	/** 本次运行以来被丢弃的跨适配器重复消息数 */
-	get dropped() {
-		return this.#dropped;
-	}
-	isDuplicate(event) {
-		let key;
-		let ttl;
-		if (event.kind === "message") {
-			key = scopeKeyOf(event, contentFingerprintOf(event));
-			ttl = MESSAGE_TTL_MS;
-		} else if (event.kind === "notice") {
-			key = noticeKeyOf(event);
-			ttl = EVENT_TTL_MS;
-		} else if (event.kind === "request") {
-			key = requestKeyOf(event);
-			ttl = EVENT_TTL_MS;
-		} else return false;
-		const now = Date.now();
-		const existing = this.#entries.get(key);
-		if (existing?.expiresAt != null && existing.expiresAt >= now) {
-			this.#dropped++;
-			return true;
-		}
-		this.#entries.set(key, { expiresAt: now + ttl });
-		this.#inserts++;
-		if (this.#inserts >= PRUNE_INTERVAL || this.#entries.size > MAX_SIZE) {
-			this.#inserts = 0;
-			this.#prune(now);
-		}
-		return false;
-	}
-	#prune(now) {
-		for (const [key, entry] of this.#entries) if (entry.expiresAt < now) this.#entries.delete(key);
-	}
-	clear() {
-		this.#entries.clear();
-	}
-};
-
-//#endregion
-//#region src/runtime/mioku-context.ts
-const isObject$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** 从事件对象中提取发送者 id（支持裸 id / user_id / sender.user_id） */
-const toUserId = (value) => {
-	if (typeof value === "number" || typeof value === "string" || typeof value === "bigint") return String(value);
-	if (isObject$1(value)) {
-		if ("user_id" in value) return toUserId(value.user_id);
-		if ("sender" in value) {
-			const sender = value.sender;
-			if (isObject$1(sender) && "user_id" in sender) return toUserId(sender.user_id);
-		}
-	}
-	return void 0;
-};
-const isEventOwner = (event) => {
-	const id = toUserId(event);
-	if (!id) return false;
-	return isOwner(id);
-};
-const isEventAdmin = (event) => {
-	const id = toUserId(event);
-	if (!id) return false;
-	return isAdmin(id);
-};
-const isEventOwnerOrAdmin = (event) => isEventOwner(event) || isEventAdmin(event);
-const hasEventRight = (event) => isEventOwnerOrAdmin(event);
+const isEventOwner = (event) => isEventOwner$1(event);
+/**
+* master、配置管理员、当前群群主或群管理员。等价于 `ctx.command({ permission: "admin" })` 的判断。
+*/
+const isEventAdmin = (event) => isEventAdmin$1(event);
+const isEventOwnerOrAdmin = (event) => isEventOwnerOrAdmin$1(event);
+const hasEventRight = (event) => hasEventRight$1(event);
 const CTX_UTILS = {
 	localeDate,
 	localeTime,
@@ -2067,6 +2030,9 @@ var MiokuContext = class {
 	get pluginName() {
 		return this.#options.pluginName;
 	}
+	get pluginId() {
+		return this.#options.pluginId;
+	}
 	/** 第一个已连接的 bot（多数单 bot 场景直接用这个） */
 	get bot() {
 		return this.#options.bots.all()[0];
@@ -2083,6 +2049,59 @@ var MiokuContext = class {
 		return this.#options.bots.pick(bot_id);
 	}
 	/**
+	* 取事件所属的跨适配器关联记录。
+	* 同一条逻辑消息被多个适配器/bot 投递时，可从这里读到全部参与方。
+	*/
+	correlation(event) {
+		return this.#options.correlator?.observationOf(event)?.record;
+	}
+	/**
+	* 观察到该事件的全部已连接 bot（首个即 primary）。
+	* 跨适配器去重后，被标记为重复的投递不会进入普通 handler，
+	* 但这里依然能看到全部参与方。
+	*/
+	botsForEvent(event) {
+		const record = this.correlation(event);
+		if (!record) {
+			const bot = event.bot;
+			return bot ? [bot] : [];
+		}
+		const resolved = [];
+		for (const participant of record.participants) {
+			const bot = participant.botId ? this.#options.bots.find(participant.adapter, participant.botId) ?? this.#options.bots.pick(participant.botId) : void 0;
+			if (bot && !resolved.includes(bot)) resolved.push(bot);
+		}
+		return resolved;
+	}
+	/** 事件里被 @ 到的、且本运行时已连接的 bot */
+	mentionedBots(event) {
+		if (event.kind !== "message") return [];
+		const targets = new Set();
+		for (const segment$1 of event.message) {
+			if (segment$1.type !== "at") continue;
+			const data = segment$1.data ?? {};
+			const target = data.qq ?? data.target;
+			if (target != null && String(target) !== "") targets.add(String(target));
+		}
+		if (targets.size === 0) return [];
+		return this.#options.bots.all().filter((bot) => targets.has(String(bot.bot_id)));
+	}
+	/**
+	* 这条消息应当由哪个 bot 回应：优先「被 @ 的 bot」，其次是关联组里首个到达的 bot。
+	* 插件可用它替代隐式的 `event.bot`，从而不受适配器到达顺序影响。
+	*/
+	pickReplyBot(event) {
+		const mentioned = this.mentionedBots(event);
+		if (mentioned.length > 0) return mentioned[0];
+		const participants = this.botsForEvent(event);
+		if (participants.length > 0) return participants[0];
+		return event.bot;
+	}
+	/** 事件关联/去重的运行统计 */
+	correlationStats() {
+		return this.#options.correlator?.stats();
+	}
+	/**
 	* 获取事件引用回复的消息内容。
 	* 返回 null 表示没有引用、拿不到对应 bot 或消息已失效。
 	*/
@@ -2113,12 +2132,12 @@ var MiokuContext = class {
 		const inputRoutes = Array.isArray(route) ? route : [route];
 		const bypassDedup = inputRoutes.some((item) => item.startsWith("!"));
 		const routes = inputRoutes.map((item) => item.startsWith("!") ? item.slice(1) : item);
-		const source = `plugin:${this.#options.pluginName}`;
+		const source = `plugin:${this.#options.pluginId}`;
 		const handledEvents = new WeakSet();
-		const dedup = bypassDedup || this.#options.dedup === false ? null : new CrossAdapterEventDeduplicator();
+		const correlator = bypassDedup ? void 0 : this.#options.correlator;
 		const wrappedHandler = async (event) => {
 			if (handledEvents.has(event)) return;
-			if (dedup?.isDuplicate(event)) return;
+			if (correlator?.isDuplicate(event)) return;
 			handledEvents.add(event);
 			await handler(event);
 		};
@@ -2135,6 +2154,17 @@ var MiokuContext = class {
 		this.#addCleanup(dispose);
 		return dispose;
 	}
+	command(definitionOrMatcher, handler, options = {}) {
+		const dispose = typeof definitionOrMatcher === "object" && definitionOrMatcher !== null && "name" in definitionOrMatcher ? this.#options.commands.register(this.#options.pluginId, {
+			...definitionOrMatcher,
+			priority: definitionOrMatcher.priority ?? this.#options.priority
+		}, this) : this.#options.commands.register(this.#options.pluginId, definitionOrMatcher, handler, {
+			...options,
+			priority: options.priority ?? this.#options.priority
+		}, this);
+		this.#addCleanup(dispose);
+		return dispose;
+	}
 	/** 注册 cron 定时任务，插件卸载时自动停止 */
 	cron(expression, handler) {
 		const task = node_cron.default.schedule(expression, async (taskContext) => {
@@ -2191,6 +2221,10 @@ var MiokuContext = class {
 	get buses() {
 		return this.#options.bus;
 	}
+	/** 当前运行时的命令管理器 */
+	get commands() {
+		return this.#options.commands;
+	}
 	get segment() {
 		return segment;
 	}
@@ -2231,24 +2265,30 @@ var MiokuContext = class {
 		return noticeAdmins(this.#options.bots.all(), this.#options.config.admins, message, options);
 	}
 	isGroupMsg(event) {
-		return isObject$1(event) && event.kind === "message" && event.message_type === "group";
+		return isObject(event) && event.kind === "message" && event.message_type === "group";
 	}
 	isPrivateMsg(event) {
-		return isObject$1(event) && event.kind === "message" && event.message_type === "private";
+		return isObject(event) && event.kind === "message" && event.message_type === "private";
+	}
+	/** 事件发送者是否为 bot 主人（仅看 owners 名单，不识别群身份） */
+	isMaster(event) {
+		return isEventMaster(event);
 	}
-	/** 事件发送者是否为主人 */
+	/** 事件发送者是否为 bot 主人或当前群群主；等价于 `permission: "owner"` */
 	isOwner(event) {
 		return isEventOwner(event);
 	}
-	/** 事件发送者是否为管理员 */
+	/** 事件发送者是否为 bot 主人、配置管理员、当前群群主或群管理员；等价于 `permission: "admin"` */
 	isAdmin(event) {
 		return isEventAdmin(event);
 	}
+	/** 同 `isAdmin`，保留旧名称 */
 	isOwnerOrAdmin(event) {
-		return isEventOwnerOrAdmin(event);
+		return isEventAdmin(event);
 	}
+	/** 同 `isAdmin`，别名 */
 	hasRight(event) {
-		return hasEventRight(event);
+		return isEventAdmin(event);
 	}
 	async dispose() {
 		const all = Array.from(this.#cleanup);
@@ -2259,19 +2299,667 @@ var MiokuContext = class {
 	}
 };
 
+//#endregion
+//#region src/runtime/event-correlator.ts
+const MESSAGE_TTL_MS = 15e3;
+const EVENT_TTL_MS = 6e4;
+const PRUNE_INTERVAL = 128;
+const MAX_SIZE = 4096;
+const MAX_SEGMENTS = 16;
+const MAX_TEXT = 256;
+const HEX32 = /[0-9a-f]{32}/i;
+const HEX40 = /[0-9a-f]{40}/i;
+const MEDIA_URL_QUERY_KEYS = [
+	"fileid",
+	"file_id",
+	"md5",
+	"fid"
+];
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const hashString = (input) => (0, node_crypto.createHash)("sha1").update(input).digest("hex").slice(0, 20);
+/** 稳定序列化：对象键排序、无多余空白，忽略跨适配器的排版差异 */
+const canonicalJson = (value) => {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	const obj = value;
+	return `{${Object.keys(obj).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(obj[key])}`).join(",")}}`;
+};
+/** 结构化载荷（json/xml/ark）的稳定摘要 */
+const structuredDigest = (raw) => {
+	let value = raw;
+	if (typeof raw === "string") {
+		const trimmed = raw.trim();
+		if (!trimmed) return "";
+		try {
+			value = JSON.parse(trimmed);
+		} catch {
+			return `s:${hashString(trimmed.slice(0, MAX_TEXT * 4))}`;
+		}
+	}
+	return `j:${hashString(canonicalJson(value))}`;
+};
+/** 去掉会过期/随会话变化的查询参数，保留跨适配器稳定的媒体定位 */
+const normalizeMediaUrl = (raw) => {
+	try {
+		const url = new URL(raw);
+		const kept = new URLSearchParams();
+		for (const key of MEDIA_URL_QUERY_KEYS) {
+			const value = url.searchParams.get(key);
+			if (value) kept.set(key, value);
+		}
+		const query = kept.toString();
+		return `${url.host}${url.pathname}${query ? `?${query}` : ""}`;
+	} catch {
+		return raw;
+	}
+};
+const firstHex = (value, pattern) => {
+	if (typeof value !== "string" || !value) return void 0;
+	const match$1 = value.match(pattern);
+	return match$1 ? match$1[0].toLowerCase() : void 0;
+};
+/**
+* 媒体段的内容摘要：优先内容哈希（md5/sha1），其次是文件名里嵌的 md5，
+* 再次是规范化 URL。都拿不到时返回空串，由调用方退化为「只看段类型」。
+*/
+const mediaDigest = (data) => {
+	const md5$1 = firstHex(data.md5, HEX32);
+	if (md5$1) return `h:${md5$1}`;
+	const sha1 = firstHex(data.sha1, HEX40);
+	if (sha1) return `h:${sha1}`;
+	for (const key of [
+		"file_unique",
+		"file_id",
+		"fid",
+		"id",
+		"file",
+		"name"
+	]) {
+		const hex = firstHex(data[key], HEX32);
+		if (hex) return `h:${hex}`;
+	}
+	const url = data.url;
+	if (typeof url === "string" && url) return `u:${normalizeMediaUrl(url)}`;
+	for (const key of [
+		"file",
+		"file_id",
+		"fid",
+		"id",
+		"name"
+	]) {
+		const value = data[key];
+		if (typeof value === "string" && value) return `r:${value.toLowerCase()}`;
+	}
+	return "";
+};
+/** 只在载荷跨协议一致时才使用摘要的段类型 */
+const DIGEST_MEDIA_TYPES = new Set(["image", "flash"]);
+const segmentSignature = (segment$1) => {
+	const data = isRecord(segment$1.data) ? segment$1.data : {};
+	switch (segment$1.type) {
+		case "text": {
+			const text$1 = typeof data.text === "string" ? data.text : "";
+			return `t:${text$1.slice(0, MAX_TEXT)}`;
+		}
+		case "at": {
+			const target = data.qq ?? data.target;
+			return `a:${target == null ? "" : String(target)}`;
+		}
+		case "face": {
+			const id = data.id ?? data.face;
+			return `f:${id == null ? "" : String(id)}`;
+		}
+		case "json":
+		case "xml":
+		case "ark": {
+			const digest = structuredDigest(data.data ?? data.content ?? data);
+			return digest ? `${segment$1.type}:${digest}` : segment$1.type;
+		}
+		default: {
+			if (DIGEST_MEDIA_TYPES.has(segment$1.type)) {
+				const digest = mediaDigest(data);
+				return digest ? `${segment$1.type}:${digest}` : segment$1.type;
+			}
+			return segment$1.type;
+		}
+	}
+};
+const contentSignatureOf = (event) => {
+	const parts = [];
+	for (const segment$1 of event.message) {
+		if (parts.length >= MAX_SEGMENTS) break;
+		if (segment$1.type === "reply") continue;
+		parts.push(segmentSignature(segment$1));
+	}
+	return parts.join("|");
+};
+const messageKeyOf = (event) => {
+	const type = event.message_type ?? "";
+	const scope = event.group_id ?? event.user_id ?? "";
+	const sender = event.user_id ?? event.sender?.user_id ?? "";
+	return [
+		"m",
+		type,
+		scope,
+		sender,
+		contentSignatureOf(event)
+	].join("|");
+};
+const noticeKeyOf = (event) => [
+	"n",
+	event.identity.event_type,
+	event.notice_type ?? "",
+	event.sub_type ?? "",
+	event.group_id ?? "",
+	event.user_id ?? "",
+	event.operator_id ?? "",
+	event.identity.timestamp == null ? "" : Math.floor(event.identity.timestamp / 1e3)
+].join("|");
+const requestKeyOf = (event) => [
+	"r",
+	event.identity.event_type,
+	event.request_type ?? "",
+	event.sub_type ?? "",
+	event.group_id ?? "",
+	event.user_id ?? "",
+	event.comment ?? "",
+	event.identity.timestamp == null ? "" : Math.floor(event.identity.timestamp / 1e3)
+].join("|");
+const participantOf = (event) => ({
+	adapter: event.identity.adapter,
+	botId: event.identity.bot_id,
+	eventType: event.identity.event_type,
+	messageId: event.identity.message_id ?? event.identity.native_event_id
+});
+const sameParticipant = (a, b) => a.adapter === b.adapter && (a.botId ?? "") === (b.botId ?? "") && (a.messageId ?? "") === (b.messageId ?? "");
+/**
+* 跨适配器事件关联器
+*/
+var EventCorrelator = class {
+	#groups = new Map();
+	#byEvent = new WeakMap();
+	#logger;
+	#maxSize;
+	#inserts = 0;
+	#observed = 0;
+	#duplicates = 0;
+	#evicted = 0;
+	constructor(options = {}) {
+		this.#logger = options.logger;
+		this.#maxSize = options.maxSize ?? MAX_SIZE;
+	}
+	/** 观察一个事件，登记它所属的关联组并返回其定位（同一事件只登记一次） */
+	observe(event) {
+		const cached = this.#byEvent.get(event);
+		if (cached) return cached;
+		const located = this.#locate(event);
+		if (!located) return null;
+		const { key, ttl } = located;
+		const now = Date.now();
+		this.#observed++;
+		let group = this.#groups.get(key);
+		let duplicate = false;
+		if (group && group.expiresAt >= now) {
+			duplicate = true;
+			this.#duplicates++;
+			const participant = participantOf(event);
+			if (!group.participants.some((item) => sameParticipant(item, participant))) group.participants.push(participant);
+			this.#logger?.debug(`去重命中: key=${key} adapter=${participant.adapter} bot=${participant.botId ?? ""} primary=${group.primary.adapter}:${group.primary.botId ?? ""}`);
+		} else {
+			const participant = participantOf(event);
+			group = {
+				key,
+				expiresAt: now + ttl,
+				firstSeenAt: now,
+				primary: participant,
+				participants: [participant]
+			};
+			this.#groups.set(key, group);
+			this.#inserts++;
+			if (this.#inserts >= PRUNE_INTERVAL || this.#groups.size > this.#maxSize) {
+				this.#inserts = 0;
+				this.#prune(now);
+			}
+		}
+		const observation = {
+			record: group,
+			primary: !duplicate,
+			duplicate
+		};
+		this.#byEvent.set(event, observation);
+		return observation;
+	}
+	/** 读取某事件此前登记的关联定位（未登记或已过期时返回 undefined） */
+	observationOf(event) {
+		const observation = this.#byEvent.get(event);
+		if (!observation) return void 0;
+		if (observation.record.expiresAt < Date.now()) return void 0;
+		return observation;
+	}
+	/** 该事件是否属于关联组里后续到达的重复投递（未登记时会先登记） */
+	isDuplicate(event) {
+		return this.observe(event)?.duplicate === true;
+	}
+	stats() {
+		return {
+			groups: this.#groups.size,
+			observed: this.#observed,
+			duplicates: this.#duplicates,
+			evicted: this.#evicted
+		};
+	}
+	clear() {
+		this.#groups.clear();
+	}
+	#locate(event) {
+		if (event.kind === "message") return {
+			key: messageKeyOf(event),
+			ttl: MESSAGE_TTL_MS
+		};
+		if (event.kind === "notice") return {
+			key: noticeKeyOf(event),
+			ttl: EVENT_TTL_MS
+		};
+		if (event.kind === "request") return {
+			key: requestKeyOf(event),
+			ttl: EVENT_TTL_MS
+		};
+		return null;
+	}
+	#prune(now) {
+		for (const [key, group] of this.#groups) if (group.expiresAt < now) this.#groups.delete(key);
+		if (this.#groups.size <= this.#maxSize) return;
+		const drop = this.#groups.size - this.#maxSize;
+		let dropped = 0;
+		for (const key of this.#groups.keys()) {
+			this.#groups.delete(key);
+			this.#evicted++;
+			if (++dropped >= drop) break;
+		}
+	}
+};
+
+//#endregion
+//#region src/runtime/commands.ts
+const normalizeRole = (role) => {
+	const value = String(role ?? "member").trim().toLowerCase();
+	if (value === "master" || value === "owner" || value === "admin") return value;
+	return "member";
+};
+const userIdOf = (event) => toUserId(event);
+const textHookMatches = (text$1, raw) => {
+	const source = String(raw ?? "").trim();
+	if (!source) return false;
+	if (source.startsWith("/") && source.length > 1) {
+		const end = source.lastIndexOf("/");
+		if (end > 0) try {
+			const flags = source.slice(end + 1);
+			const regex = new RegExp(source.slice(1, end), flags);
+			return regex.test(text$1);
+		} catch {
+			return false;
+		}
+	}
+	return text$1 === source || text$1.startsWith(source);
+};
+const routeMatches = (event, route) => {
+	if (!route) return false;
+	return event.type === route || event.routes.some((item) => item === route);
+};
+const parsePrefixes = (prefixes, defaultPrefix) => {
+	if (prefixes === false) return ["", defaultPrefix];
+	const values = Array.isArray(prefixes) ? prefixes : [prefixes];
+	const normalized = values.map((value) => String(value)).filter((value, index, all) => all.indexOf(value) === index);
+	return normalized.length > 0 ? normalized : [defaultPrefix];
+};
+const commandBody = (text$1, prefixes) => {
+	const prefix = [...prefixes].sort((a, b) => b.length - a.length).find((item) => item === "" || text$1.startsWith(item));
+	if (prefix === void 0) return void 0;
+	return text$1.slice(prefix.length).trimStart();
+};
+const stringMatch = (body, matcher) => {
+	const value = matcher.trim();
+	if (!value) return void 0;
+	if (body !== value && !(body.startsWith(value) && /\s/.test(body[value.length] ?? ""))) return void 0;
+	const rest = body.slice(value.length).trim();
+	return { args: rest ? rest.split(/\s+/) : [] };
+};
+const commandKey$1 = (value) => String(value).trim().replace(/^[#/.]+\s*/, "").split(/\s+/)[0].toLowerCase();
+const displayCommand = (command, defaultPrefix) => {
+	if (command.prefixes === false) return command.name;
+	const prefixes = command.prefixes === void 0 ? [defaultPrefix] : Array.isArray(command.prefixes) ? command.prefixes : [command.prefixes];
+	return `${prefixes.find((prefix) => prefix.length > 0) ?? ""}${command.name}`;
+};
+var CommandManager = class {
+	#getDefaultPrefix;
+	#getOwners;
+	#getAdmins;
+	#logger;
+	#commands = [];
+	#legacy = new Map();
+	#access;
+	#nextOrder = 0;
+	constructor(options) {
+		this.#getDefaultPrefix = options.getDefaultPrefix;
+		this.#getOwners = options.getOwners;
+		this.#getAdmins = options.getAdmins;
+		this.#logger = options.logger;
+	}
+	register(plugin, definitionOrMatcher, handlerOrContext, optionsOrContext = {}, context) {
+		const isDefinition = typeof definitionOrMatcher === "object" && definitionOrMatcher !== null && "name" in definitionOrMatcher;
+		const shortcutOptions = isDefinition ? {} : optionsOrContext;
+		const resolvedContext = isDefinition ? handlerOrContext : context;
+		const handler = isDefinition ? void 0 : handlerOrContext;
+		const definition = isDefinition ? definitionOrMatcher : {
+			...shortcutOptions,
+			name: shortcutOptions.name ?? String(definitionOrMatcher),
+			match: definitionOrMatcher,
+			handler
+		};
+		if (typeof definition.handler !== "function") throw new Error("CommandManager.register: handler must be a function");
+		if (!resolvedContext) throw new Error("CommandManager.register: context is required");
+		const name = String(definition.name ?? "").trim();
+		if (!name) throw new Error("CommandManager.register: name is required");
+		const matcher = definition.match ?? name;
+		const command = {
+			plugin,
+			id: String(definition.id ?? name).trim() || name,
+			name,
+			aliases: (definition.aliases ?? []).map((item) => String(item).trim()).filter(Boolean),
+			matcher,
+			description: String(definition.description ?? "").trim(),
+			usage: definition.usage,
+			permission: normalizeRole(definition.permission),
+			priority: typeof definition.priority === "number" && !Number.isNaN(definition.priority) ? definition.priority : 0,
+			prefixes: definition.prefixes,
+			handler: definition.handler,
+			order: this.#nextOrder++,
+			context: resolvedContext
+		};
+		this.#commands.push(command);
+		return () => {
+			const index = this.#commands.indexOf(command);
+			if (index >= 0) this.#commands.splice(index, 1);
+		};
+	}
+	setAccessControl(config) {
+		this.#access = config;
+	}
+	syncMetadata(metadata) {
+		this.#legacy.set(metadata.name, { metadata });
+	}
+	removePlugin(plugin) {
+		this.#legacy.delete(plugin);
+		for (let i = this.#commands.length - 1; i >= 0; i--) if (this.#commands[i].plugin === plugin) this.#commands.splice(i, 1);
+	}
+	clear() {
+		this.#commands.length = 0;
+		this.#legacy.clear();
+		this.#access = void 0;
+	}
+	list() {
+		return this.#orderedCommands();
+	}
+	#orderedCommands() {
+		return [...this.#commands].sort((a, b) => a.priority - b.priority || a.order - b.order);
+	}
+	getPluginHelp(plugin) {
+		const metadata = this.#legacy.get(plugin)?.metadata;
+		const runtime = this.#commands.filter((item) => item.plugin === plugin);
+		if (!metadata?.config.help && runtime.length === 0) return void 0;
+		const commands = [];
+		const seen = new Set();
+		const runtimeByKey = new Map(runtime.map((command) => [commandKey$1(command.name), command]));
+		for (const command of metadata?.config.help?.commands ?? []) {
+			const key = commandKey$1(command.cmd);
+			const runtimeCommand = runtimeByKey.get(key);
+			if (runtimeCommand) {
+				const cmd = displayCommand(runtimeCommand, this.#getDefaultPrefix());
+				seen.add(key);
+				commands.push({
+					cmd,
+					desc: runtimeCommand.description || command.desc || cmd,
+					usage: runtimeCommand.usage ?? command.usage,
+					role: runtimeCommand.permission
+				});
+			} else if (!seen.has(key)) {
+				seen.add(key);
+				commands.push(command);
+			}
+		}
+		for (const command of runtime) {
+			const cmd = displayCommand(command, this.#getDefaultPrefix());
+			if (seen.has(commandKey$1(cmd))) continue;
+			seen.add(commandKey$1(cmd));
+			commands.push({
+				cmd,
+				desc: command.description || cmd,
+				usage: command.usage,
+				role: command.permission
+			});
+		}
+		const help = metadata?.config.help;
+		return {
+			title: help?.title || plugin,
+			description: help?.description || metadata?.description || "",
+			commands
+		};
+	}
+	catalog() {
+		const items = [];
+		const plugins = new Set([...this.#legacy.keys(), ...this.#commands.map((item) => item.plugin)]);
+		for (const plugin of plugins) {
+			const metadata = this.#legacy.get(plugin)?.metadata;
+			const help = metadata?.config.help;
+			items.push({
+				kind: "plugin",
+				plugin,
+				id: plugin,
+				label: help?.title || plugin,
+				desc: help?.description || metadata?.description,
+				source: metadata ? "manifest" : "runtime"
+			});
+			const seen = new Set();
+			for (const command of this.#commands.filter((item) => item.plugin === plugin)) {
+				seen.add(commandKey$1(command.id));
+				items.push({
+					kind: "command",
+					plugin,
+					id: command.id,
+					label: command.name,
+					desc: command.description,
+					usage: command.usage,
+					permission: command.permission,
+					priority: command.priority,
+					match: command.matcher instanceof RegExp ? command.matcher.toString() : command.matcher,
+					source: "runtime"
+				});
+			}
+			for (const hook of metadata?.config.accessHooks ?? []) {
+				if (seen.has(commandKey$1(hook.id))) continue;
+				seen.add(commandKey$1(hook.id));
+				items.push({
+					kind: "command",
+					plugin,
+					id: hook.id,
+					label: hook.id,
+					desc: hook.description,
+					match: hook.match,
+					event: hook.event,
+					source: "manifest"
+				});
+			}
+			for (const command of help?.commands ?? []) {
+				if (seen.has(commandKey$1(command.cmd))) continue;
+				seen.add(commandKey$1(command.cmd));
+				items.push({
+					kind: "command",
+					plugin,
+					id: command.cmd,
+					label: command.cmd,
+					desc: command.desc,
+					usage: command.usage,
+					permission: command.role,
+					source: "manifest"
+				});
+			}
+		}
+		return items.sort((a, b) => a.kind === b.kind ? a.plugin.localeCompare(b.plugin) || a.id.localeCompare(b.id) : a.kind === "plugin" ? -1 : 1);
+	}
+	async dispatch(event) {
+		const text$1 = String(event.message?.text?.() ?? "").trim();
+		if (!text$1) return false;
+		const match$1 = this.#find(text$1);
+		if (!match$1) return false;
+		if (!this.#canUse(match$1.command, event)) return true;
+		try {
+			await match$1.command.handler({
+				ctx: match$1.command.context,
+				event,
+				command: match$1.command,
+				text: text$1,
+				body: match$1.body,
+				args: match$1.args,
+				match: match$1.match
+			});
+		} catch (error) {
+			this.#logger?.error(`Command "${match$1.command.plugin}:${match$1.command.id}" failed`, error);
+		}
+		return true;
+	}
+	shouldDispatch(source, event) {
+		if (!source.startsWith("plugin:")) return true;
+		const plugin = source.slice(7);
+		const metadata = this.#legacy.get(plugin)?.metadata;
+		if (!metadata) return this.#pluginAllowed(plugin, event);
+		if (!this.#pluginAllowed(plugin, event)) return false;
+		const text$1 = event.kind === "message" ? String(event.message.text()).trim() : "";
+		const matches = (metadata.config.accessHooks ?? []).filter((hook) => event.kind === "message" && textHookMatches(text$1, hook.match) || routeMatches(event, hook.event));
+		return matches.every((hook) => this.#commandAllowed(plugin, hook.id, event));
+	}
+	#find(text$1) {
+		for (const command of this.#orderedCommands()) {
+			const prefixes = parsePrefixes(command.prefixes ?? this.#getDefaultPrefix(), this.#getDefaultPrefix());
+			const body = commandBody(text$1, prefixes);
+			if (body === void 0) continue;
+			if (typeof command.matcher === "string") {
+				const candidates = [
+					command.matcher,
+					command.name,
+					...command.aliases
+				];
+				for (const candidate of candidates) {
+					const result = stringMatch(body, candidate);
+					if (result) return {
+						command,
+						body,
+						args: result.args
+					};
+				}
+				continue;
+			}
+			command.matcher.lastIndex = 0;
+			const matched = body.match(command.matcher);
+			if (!matched) continue;
+			const args = matched.length > 1 ? matched.slice(1).filter((item) => item != null) : body.slice(matched[0].length).trim().split(/\s+/).filter(Boolean);
+			return {
+				command,
+				body,
+				args,
+				match: matched
+			};
+		}
+		return void 0;
+	}
+	#canUse(command, event) {
+		const userId = userIdOf(event);
+		const master = Boolean(userId && this.#isMaster(userId));
+		const owner = master || this.#isGroupOwner(event);
+		const admin = owner || Boolean(userId && this.#isAdmin(userId)) || this.#isGroupAdmin(event);
+		if (command.permission === "master") {
+			if (!master) return false;
+		} else if (command.permission === "owner") {
+			if (!owner) return false;
+		} else if (command.permission === "admin" && !admin) return false;
+		return this.#commandAllowed(command.plugin, command.id, event);
+	}
+	#pluginAllowed(plugin, event) {
+		const userId = event.kind === "message" ? userIdOf(event) : "user_id" in event ? event.user_id : void 0;
+		if (userId && (this.#isMaster(userId) || this.#isAdmin(userId)) || this.#isGroupOwner(event) || this.#isGroupAdmin(event)) return true;
+		return this.#resolveAction(plugin, void 0, event) !== "block";
+	}
+	#commandAllowed(plugin, command, event) {
+		const userId = event.kind === "message" ? userIdOf(event) : "user_id" in event ? event.user_id : void 0;
+		if (userId && (this.#isMaster(userId) || this.#isAdmin(userId)) || this.#isGroupOwner(event) || this.#isGroupAdmin(event)) return true;
+		return this.#resolveAction(plugin, command, event) !== "block";
+	}
+	#resolveAction(plugin, command, event) {
+		const access = this.#access;
+		if (!access) return void 0;
+		const scopes = [
+			(() => {
+				const userId = event.kind === "message" ? userIdOf(event) : "user_id" in event && event.user_id ? String(event.user_id) : void 0;
+				return userId ? access.users[userId] : void 0;
+			})(),
+			(() => {
+				const groupId = "group_id" in event && event.group_id ? String(event.group_id) : void 0;
+				return groupId ? access.groups[groupId] : void 0;
+			})(),
+			access.global
+		];
+		for (const scope of scopes) {
+			if (!scope) continue;
+			const commandRule = command ? scope.commands?.[plugin]?.[command]?.action : void 0;
+			if (commandRule) return commandRule;
+			const pluginRule = scope.plugins?.[plugin]?.action;
+			if (pluginRule) return pluginRule;
+		}
+		return void 0;
+	}
+	#isMaster(userId) {
+		return this.#owners().includes(userId);
+	}
+	#isAdmin(userId) {
+		return this.#isMaster(userId) || this.#admins().includes(userId);
+	}
+	#isGroupOwner(event) {
+		return isEventGroupOwner(event);
+	}
+	#isGroupAdmin(event) {
+		return isEventGroupAdmin(event);
+	}
+	#owners() {
+		return this.#configIds("owners");
+	}
+	#admins() {
+		return this.#configIds("admins");
+	}
+	#configIds(key) {
+		return [...key === "owners" ? this.#getOwners() : this.#getAdmins()].map(String);
+	}
+};
+let activeCommandManager;
+const setActiveCommandManager = (manager) => {
+	activeCommandManager = manager;
+};
+const getActiveCommandManager = () => activeCommandManager;
+
 //#endregion
 //#region src/runtime/plugin-metadata.ts
 const store$1 = getOrCreate("plugin-metadata", () => new Map());
 const setPluginMetadata = (meta) => {
 	store$1.set(meta.name, meta);
+	getActiveCommandManager()?.syncMetadata(meta);
 };
 const removePluginMetadata = (name) => {
 	store$1.delete(name);
+	getActiveCommandManager()?.removePlugin(name);
 };
 const getPluginMetadata = (name) => store$1.get(name);
 const getPluginMetadataList = () => [...store$1.values()];
 const resetPluginMetadata = () => {
 	store$1.clear();
+	getActiveCommandManager()?.clear();
 };
 
 //#endregion
@@ -2931,12 +3619,6 @@ async function sendTextOrForward(options) {
 	}
 }
 
-//#endregion
-//#region src/builtin/core/commands/prefix.ts
-function getCommandPrefix() {
-	return botConfig.prefix ?? ".";
-}
-
 //#endregion
 //#region src/builtin/core/system/package-manager.ts
 const NPM_REGISTRY = "https://registry.npmjs.org";
@@ -3528,102 +4210,102 @@ async function performUpdateAndReport(ctx, event, names) {
 	triggerRestart(marker);
 }
 function registerUpdateCommands(ctx) {
-	const dispose = ctx.handle("message", async (event) => {
-		const text$1 = ctx.text(event)?.trim();
-		if (!text$1 || event?.user_id === event?.self_id) return;
-		const prefix = getCommandPrefix();
-		if (!text$1.startsWith(`${prefix}update`)) return;
-		if (!isEventOwner(event)) {
-			ctx.logger.warn("[core] update 指令仅主人可用");
-			return;
-		}
-		const arg = text$1.slice(prefix.length + 6).trim();
-		const selfId = String(event?.self_id || "");
-		const bot = event.bot;
-		if (!bot) return;
-		if (arg === "all") {
-			const managed = await updateAllManaged();
-			if (managed.names.length === 0) {
-				await replyText(event, "未找到可更新的 mioku 包");
-				return;
-			}
-			await performUpdateAndReport(ctx, event, managed.names);
-			return;
-		}
-		if (arg === "mioku" || arg === "self") {
-			await performUpdateAndReport(ctx, event, ["mioku"]);
-			return;
-		}
-		if (arg.startsWith("plugin ") || arg.startsWith("service ")) {
-			const [typeRaw, ...rest] = arg.split(/\s+/);
-			const name = rest.join(" ").trim();
-			const type = typeRaw === "plugin" ? "plugin" : "service";
-			if (!name) {
-				await replyText(event, `用法：${prefix}update ${type} <名称>`);
+	const dispose = ctx.command({
+		name: "update",
+		aliases: ["更新"],
+		permission: "master",
+		priority: -1e3,
+		description: "检查并选择插件/服务更新",
+		handler: async ({ event, args }) => {
+			const prefix = String(ctx.config.prefix ?? ".");
+			const arg = args.join(" ").trim();
+			const selfId = String(event?.self_id || "");
+			const bot = event.bot;
+			if (!bot) return;
+			if (arg === "all") {
+				const managed = await updateAllManaged();
+				if (managed.names.length === 0) {
+					await replyText(event, "未找到可更新的 mioku 包");
+					return;
+				}
+				await performUpdateAndReport(ctx, event, managed.names);
 				return;
 			}
-			const pkgPrefix = type === "plugin" ? "mioku-plugin-" : "mioku-service-";
-			const fullName = name.startsWith(pkgPrefix) ? name : `${pkgPrefix}${name}`;
-			await performUpdateAndReport(ctx, event, [fullName]);
-			return;
-		}
-		if (arg === "check" || arg === "检查") {
-			const pending = getPendingMap();
-			const key = conversationKey(event);
-			const existing = pending.get(key);
-			if (existing) {
-				existing.disposer();
-				clearTimeout(existing.timer);
-				pending.delete(key);
-			}
-			let items;
-			try {
-				items = await checkUpdates();
-			} catch (error) {
-				ctx.logger.error(`[core] 检查更新失败: ${error}`);
-				await replyText(event, `检查更新失败：${String(error)}`);
+			if (arg === "mioku" || arg === "self") {
+				await performUpdateAndReport(ctx, event, ["mioku"]);
 				return;
 			}
-			if (items.length === 0) {
-				await replyText(event, "所有插件与服务均已是最新版本");
+			if (arg.startsWith("plugin ") || arg.startsWith("service ")) {
+				const [typeRaw, ...rest] = arg.split(/\s+/);
+				const name = rest.join(" ").trim();
+				const type = typeRaw === "plugin" ? "plugin" : "service";
+				if (!name) {
+					await replyText(event, `用法：${prefix}update ${type} <名称>`);
+					return;
+				}
+				const pkgPrefix = type === "plugin" ? "mioku-plugin-" : "mioku-service-";
+				const fullName = name.startsWith(pkgPrefix) ? name : `${pkgPrefix}${name}`;
+				await performUpdateAndReport(ctx, event, [fullName]);
 				return;
 			}
-			await replyText(event, renderUpdateList(items));
-			const timeoutMs = SELECT_TIMEOUT_MS;
-			const listenerDispose = ctx.handle("message", async (ev) => {
-				if (String(ev?.self_id || "") !== selfId) return;
-				if (conversationKey(ev) !== key) return;
-				if (!isEventOwner(ev)) return;
-				const evText = ctx.text(ev)?.trim() || "";
-				if (evText.startsWith(`${prefix}update`)) return;
-				const sel = pending.get(key);
-				if (!sel) return;
-				clearTimeout(sel.timer);
-				sel.disposer();
-				pending.delete(key);
-				const parsed = parseSelection(evText, sel.items.length);
-				const chosen = parsed.all ? sel.items : parsed.indices.map((i) => sel.items[i]).filter(Boolean);
-				if (chosen.length === 0) {
-					await replyText(event, "未选择任何有效项，已取消");
+			if (arg === "check" || arg === "检查") {
+				const pending = getPendingMap();
+				const key = conversationKey(event);
+				const existing = pending.get(key);
+				if (existing) {
+					existing.disposer();
+					clearTimeout(existing.timer);
+					pending.delete(key);
+				}
+				let items;
+				try {
+					items = await checkUpdates();
+				} catch (error) {
+					ctx.logger.error(`[core] 检查更新失败: ${error}`);
+					await replyText(event, `检查更新失败：${String(error)}`);
 					return;
 				}
-				await performUpdateAndReport(ctx, event, chosen.map((i) => i.name));
-			});
-			const timer = setTimeout(async () => {
-				const sel = pending.get(key);
-				if (!sel) return;
-				sel.disposer();
-				pending.delete(key);
-				await replyText(event, "操作超时，已取消更新");
-			}, timeoutMs);
-			pending.set(key, {
-				disposer: listenerDispose,
-				timer,
-				items
-			});
-			return;
+				if (items.length === 0) {
+					await replyText(event, "所有插件与服务均已是最新版本");
+					return;
+				}
+				await replyText(event, renderUpdateList(items));
+				const timeoutMs = SELECT_TIMEOUT_MS;
+				const listenerDispose = ctx.handle("message", async (ev) => {
+					if (String(ev?.self_id || "") !== selfId) return;
+					if (conversationKey(ev) !== key) return;
+					if (!isEventMaster(ev)) return;
+					const evText = ctx.text(ev)?.trim() || "";
+					if (evText.startsWith(`${prefix}update`)) return;
+					const sel = pending.get(key);
+					if (!sel) return;
+					clearTimeout(sel.timer);
+					sel.disposer();
+					pending.delete(key);
+					const parsed = parseSelection(evText, sel.items.length);
+					const chosen = parsed.all ? sel.items : parsed.indices.map((i) => sel.items[i]).filter(Boolean);
+					if (chosen.length === 0) {
+						await replyText(event, "未选择任何有效项，已取消");
+						return;
+					}
+					await performUpdateAndReport(ctx, event, chosen.map((i) => i.name));
+				});
+				const timer = setTimeout(async () => {
+					const sel = pending.get(key);
+					if (!sel) return;
+					sel.disposer();
+					pending.delete(key);
+					await replyText(event, "操作超时，已取消更新");
+				}, timeoutMs);
+				pending.set(key, {
+					disposer: listenerDispose,
+					timer,
+					items
+				});
+				return;
+			}
+			await replyText(event, `用法：\n${prefix}update check  检查并选择更新\n${prefix}update all  更新全部\n${prefix}update mioku  更新框架\n${prefix}update plugin <名称>\n${prefix}update service <名称>`);
 		}
-		await replyText(event, `用法：\n${prefix}update check  检查并选择更新\n${prefix}update all  更新全部\n${prefix}update mioku  更新框架\n${prefix}update plugin <名称>\n${prefix}update service <名称>`);
 	});
 	return () => {
 		dispose();
@@ -3638,15 +4320,13 @@ function registerUpdateCommands(ctx) {
 
 //#endregion
 //#region src/builtin/core/commands/install.ts
-function parseTargetArgs(text$1, head) {
-	if (!text$1.startsWith(head)) return null;
-	const rest = text$1.slice(head.length).trim();
-	const matched = rest.match(/^(plugin|service)\s+([\s\S]+)$/);
-	if (!matched) return null;
-	const name = matched[2].trim();
+function parseTargetArgs(args) {
+	const type = args[0];
+	if (type !== "plugin" && type !== "service") return null;
+	const name = args.slice(1).join(" ").trim();
 	if (!name) return null;
 	return {
-		type: matched[1],
+		type,
 		name
 	};
 }
@@ -3654,68 +4334,70 @@ function typeLabel(type) {
 	return type === "plugin" ? "插件" : "服务";
 }
 function registerInstallCommands(ctx) {
-	const dispose = ctx.handle("message", async (event) => {
-		const text$1 = ctx.text(event)?.trim();
-		if (!text$1 || event?.user_id === event?.self_id) return;
-		const prefix = getCommandPrefix();
-		const installHead = `${prefix}install`;
-		const uninstallHead = `${prefix}uninstall`;
-		if (!text$1.startsWith(installHead) && !text$1.startsWith(uninstallHead)) return;
-		if (!isEventOwner(event)) {
-			ctx.logger.warn("[core] install/uninstall 指令仅主人可用");
-			return;
-		}
-		if (text$1.startsWith(installHead)) {
-			const parsed$1 = parseTargetArgs(text$1, installHead);
-			if (!parsed$1) {
-				await replyText(event, `用法：${prefix}install plugin <名称> 或 ${prefix}install service <名称>`);
+	const register = (name) => ctx.command({
+		name,
+		aliases: name === "install" ? ["安装"] : ["卸载"],
+		permission: "master",
+		priority: -1e3,
+		description: name === "install" ? "从 npm 安装插件/服务" : "卸载插件/服务",
+		handler: async ({ event, args }) => {
+			if (name === "install") {
+				const parsed$1 = parseTargetArgs(args);
+				if (!parsed$1) {
+					await replyText(event, `用法：${ctx.config.prefix ?? "."}install plugin <名称> 或 ${ctx.config.prefix ?? "."}install service <名称>`);
+					return;
+				}
+				await replyText(event, `正在从 npm 安装${typeLabel(parsed$1.type)} ${parsed$1.name}...`);
+				try {
+					const result = await installPackage(parsed$1.type, parsed$1.name);
+					if (!result.ok) {
+						ctx.logger.error(`[core] 安装失败: ${result.error || result.output}`);
+						await replyText(event, `安装失败：${result.error || result.output}`);
+						return;
+					}
+					const lines = [
+						`已安装 ${result.packageName}`,
+						result.enabled ? "已在 plugins 中启用" : "",
+						"重启后生效"
+					].filter(Boolean);
+					await replyText(event, lines.join("\n"));
+				} catch (error) {
+					ctx.logger.error(`[core] 安装失败: ${error}`);
+					await replyText(event, `安装失败：${String(error)}`);
+				}
+				return;
+			}
+			const parsed = parseTargetArgs(args);
+			if (!parsed) {
+				await replyText(event, `用法：${ctx.config.prefix ?? "."}uninstall plugin <名称> 或 ${ctx.config.prefix ?? "."}uninstall service <名称>`);
 				return;
 			}
-			await replyText(event, `正在从 npm 安装${typeLabel(parsed$1.type)} ${parsed$1.name}...`);
+			await replyText(event, `正在卸载${typeLabel(parsed.type)} ${parsed.name}...`);
 			try {
-				const result = await installPackage(parsed$1.type, parsed$1.name);
+				const result = await uninstallPackage(parsed.type, parsed.name);
 				if (!result.ok) {
-					ctx.logger.error(`[core] 安装失败: ${result.error || result.output}`);
-					await replyText(event, `安装失败：${result.error || result.output}`);
+					ctx.logger.error(`[core] 卸载失败: ${result.error || result.output}`);
+					await replyText(event, `卸载失败：${result.error || result.output}`);
 					return;
 				}
 				const lines = [
-					`已安装 ${result.packageName}`,
-					result.enabled ? "已在 plugins 中启用" : "",
+					`已卸载 ${result.packageName}`,
+					result.removedFromConfig ? "已从 plugins 中移除" : "",
 					"重启后生效"
 				].filter(Boolean);
 				await replyText(event, lines.join("\n"));
 			} catch (error) {
-				ctx.logger.error(`[core] 安装失败: ${error}`);
-				await replyText(event, `安装失败：${String(error)}`);
+				ctx.logger.error(`[core] 卸载失败: ${error}`);
+				await replyText(event, `卸载失败：${String(error)}`);
 			}
-			return;
-		}
-		const parsed = parseTargetArgs(text$1, uninstallHead);
-		if (!parsed) {
-			await replyText(event, `用法：${prefix}uninstall plugin <名称> 或 ${prefix}uninstall service <名称>`);
-			return;
-		}
-		await replyText(event, `正在卸载${typeLabel(parsed.type)} ${parsed.name}...`);
-		try {
-			const result = await uninstallPackage(parsed.type, parsed.name);
-			if (!result.ok) {
-				ctx.logger.error(`[core] 卸载失败: ${result.error || result.output}`);
-				await replyText(event, `卸载失败：${result.error || result.output}`);
-				return;
-			}
-			const lines = [
-				`已卸载 ${result.packageName}`,
-				result.removedFromConfig ? "已从 plugins 中移除" : "",
-				"重启后生效"
-			].filter(Boolean);
-			await replyText(event, lines.join("\n"));
-		} catch (error) {
-			ctx.logger.error(`[core] 卸载失败: ${error}`);
-			await replyText(event, `卸载失败：${String(error)}`);
 		}
 	});
-	return dispose;
+	const install = register("install");
+	const uninstall = register("uninstall");
+	return () => {
+		install();
+		uninstall();
+	};
 }
 
 //#endregion
@@ -3729,64 +4411,76 @@ function renderMarketText(kind, items) {
 	return [`Mioku ${label}市场（共 ${items.length} 个）`, ...lines].join("\n");
 }
 function registerMarketCommands(ctx) {
-	const dispose = ctx.handle("message", async (event) => {
-		const text$1 = ctx.text(event)?.trim();
-		if (!text$1 || event?.user_id === event?.self_id) return;
-		const prefix = getCommandPrefix();
-		const kind = text$1 === `${prefix}plugin-market` || text$1 === `${prefix}插件市场` ? "plugin" : text$1 === `${prefix}service-market` || text$1 === `${prefix}服务市场` ? "service" : null;
-		if (!kind) return;
-		if (!isEventOwner(event)) {
-			ctx.logger.warn("[core] market 指令仅主人可用");
-			return;
-		}
-		let items;
-		try {
-			items = await getMarketItems(kind);
-		} catch (error) {
-			ctx.logger.error(`[core] 获取市场信息失败: ${error}`);
-			await replyText(event, `获取市场失败：${String(error)}`);
-			return;
-		}
-		await sendTextOrForward({
-			ctx,
-			event,
-			text: renderMarketText(kind, items),
-			source: `Mioku ${kind === "plugin" ? "插件" : "服务"}市场`,
-			summary: `共 ${items.length} 个`
-		});
+	const pluginMarket = ctx.command({
+		id: "market",
+		name: "plugin-market",
+		aliases: ["插件市场"],
+		permission: "master",
+		priority: -1e3,
+		description: "查看插件市场",
+		handler: (input) => handleMarket(ctx, input.event, "plugin")
+	});
+	const serviceMarket = ctx.command({
+		id: "market",
+		name: "service-market",
+		aliases: ["服务市场"],
+		permission: "master",
+		priority: -1e3,
+		description: "查看服务市场",
+		handler: (input) => handleMarket(ctx, input.event, "service")
+	});
+	return () => {
+		pluginMarket();
+		serviceMarket();
+	};
+}
+async function handleMarket(ctx, event, kind) {
+	let items;
+	try {
+		items = await getMarketItems(kind);
+	} catch (error) {
+		ctx.logger.error(`[core] 获取市场信息失败: ${error}`);
+		await replyText(event, `获取市场失败：${String(error)}`);
+		return;
+	}
+	await sendTextOrForward({
+		ctx,
+		event,
+		text: renderMarketText(kind, items),
+		source: `Mioku ${kind === "plugin" ? "插件" : "服务"}市场`,
+		summary: `共 ${items.length} 个`
 	});
-	return dispose;
 }
 
 //#endregion
 //#region src/builtin/core/commands/restart.ts
 function registerRestartCommand(ctx) {
-	const dispose = ctx.handle("message", async (event) => {
-		const text$1 = ctx.text(event)?.trim();
-		if (!text$1 || event?.user_id === event?.self_id) return;
-		const prefix = getCommandPrefix();
-		if (text$1 !== `${prefix}restart` && text$1 !== `${prefix}重启`) return;
-		if (!isEventOwner(event)) {
-			ctx.logger.warn("[core] restart 指令仅主人可用");
-			return;
-		}
-		const uptimeMs = process.uptime() * 1e3;
-		const selfId = Number(event?.self_id || 0);
-		const groupId = event?.message_type === "group" && event?.group_id ? Number(event.group_id) : null;
-		const userId = Number(event?.user_id || 0);
-		const marker = {
-			initiatedAt: Date.now(),
-			selfId,
-			groupId,
-			userId
-		};
-		try {
-			await replyText(event, `Bot已运行${formatUptime(uptimeMs)}，正在重启...`);
-		} catch (error) {
-			ctx.logger.warn(`[core] 发送重启提示失败: ${error}`);
+	const dispose = ctx.command({
+		name: "restart",
+		aliases: ["重启"],
+		permission: "master",
+		priority: -1e3,
+		description: "重启机器人进程",
+		handler: async ({ event }) => {
+			if (event?.user_id === event?.self_id) return;
+			const uptimeMs = process.uptime() * 1e3;
+			const selfId = Number(event?.self_id || 0);
+			const groupId = event?.message_type === "group" && event?.group_id ? Number(event.group_id) : null;
+			const userId = Number(event?.user_id || 0);
+			const marker = {
+				initiatedAt: Date.now(),
+				selfId,
+				groupId,
+				userId
+			};
+			try {
+				await replyText(event, `Bot已运行${formatUptime(uptimeMs)}，正在重启...`);
+			} catch (error) {
+				ctx.logger.warn(`[core] 发送重启提示失败: ${error}`);
+			}
+			ctx.logger.info(`[core] 正在执行重启命令 ${formatUptime(uptimeMs)}`);
+			triggerRestart(marker);
 		}
-		ctx.logger.info(`[core] 正在执行重启命令 ${formatUptime(uptimeMs)}`);
-		triggerRestart(marker);
 	});
 	return dispose;
 }
@@ -3824,63 +4518,63 @@ function chunk(arr, size) {
 	return result;
 }
 function registerLogCommand(ctx) {
-	const dispose = ctx.handle("message", async (event) => {
-		const text$1 = ctx.text(event)?.trim();
-		if (!text$1 || event?.user_id === event?.self_id) return;
-		const prefix = getCommandPrefix();
-		if (text$1 !== `${prefix}log` && text$1 !== `${prefix}日志`) return;
-		if (!isEventOwner(event)) {
-			ctx.logger.warn("[core] 日志指令仅主人可用");
-			return;
-		}
-		const selfId = String(event?.self_id || "");
-		const bot = event.bot;
-		if (!bot) return;
-		const logFile = getActiveLogFile();
-		if (!logFile) {
-			await replyText(event, "未找到日志文件。");
-			return;
-		}
-		let lines;
-		try {
-			lines = readLastLines(logFile, LOG_LINE_COUNT);
-		} catch (error) {
-			ctx.logger.error(`[core] 读取日志失败: ${error}`);
-			await replyText(event, `读取日志失败：${String(error)}`);
-			return;
-		}
-		if (lines.length === 0) {
-			await replyText(event, "日志为空。");
-			return;
-		}
-		let infoCount = 0;
-		let warnCount = 0;
-		let errorCount = 0;
-		for (const line of lines) if (/\bERROR\b|\berror\b/i.test(line)) errorCount++;
-		else if (/\bWARN\b|\bwarn\b/i.test(line)) warnCount++;
-		else if (/\bINFO\b|\binfo\b/i.test(line)) infoCount++;
-		const summary = `info ${infoCount} warn ${warnCount} error ${errorCount}`;
-		const chunks = chunk(lines, LINES_PER_NODE);
-		const nodes = chunks.map((chunkLines, idx) => ({
-			user_id: selfId,
-			nickname: `第${idx + 1}条日志`,
-			content: [ctx.segment.text(chunkLines.join("\n"))]
-		}));
-		try {
-			const target = event?.message_type === "group" && event?.group_id ? {
-				type: "group",
-				group_id: event.group_id
-			} : event?.user_id ? {
-				type: "private",
-				user_id: event.user_id
-			} : void 0;
-			if (target) await bot.sendForward(target, nodes, {
-				source: "最近100条运行日志",
-				summary
-			});
-		} catch (error) {
-			ctx.logger.error(`[core] 发送日志转发失败: ${error}`);
-			await replyText(event, `发送日志失败：${String(error)}`);
+	const dispose = ctx.command({
+		name: "log",
+		aliases: ["日志"],
+		permission: "master",
+		priority: -1e3,
+		description: "查看最近100条日志",
+		handler: async ({ event }) => {
+			if (event?.user_id === event?.self_id) return;
+			const selfId = String(event?.self_id || "");
+			const bot = event.bot;
+			if (!bot) return;
+			const logFile = getActiveLogFile();
+			if (!logFile) {
+				await replyText(event, "未找到日志文件。");
+				return;
+			}
+			let lines;
+			try {
+				lines = readLastLines(logFile, LOG_LINE_COUNT);
+			} catch (error) {
+				ctx.logger.error(`[core] 读取日志失败: ${error}`);
+				await replyText(event, `读取日志失败：${String(error)}`);
+				return;
+			}
+			if (lines.length === 0) {
+				await replyText(event, "日志为空。");
+				return;
+			}
+			let infoCount = 0;
+			let warnCount = 0;
+			let errorCount = 0;
+			for (const line of lines) if (/\bERROR\b|\berror\b/i.test(line)) errorCount++;
+			else if (/\bWARN\b|\bwarn\b/i.test(line)) warnCount++;
+			else if (/\bINFO\b|\binfo\b/i.test(line)) infoCount++;
+			const summary = `info ${infoCount} warn ${warnCount} error ${errorCount}`;
+			const chunks = chunk(lines, LINES_PER_NODE);
+			const nodes = chunks.map((chunkLines, idx) => ({
+				user_id: selfId,
+				nickname: `第${idx + 1}条日志`,
+				content: [ctx.segment.text(chunkLines.join("\n"))]
+			}));
+			try {
+				const target = event?.message_type === "group" && event?.group_id ? {
+					type: "group",
+					group_id: event.group_id
+				} : event?.user_id ? {
+					type: "private",
+					user_id: event.user_id
+				} : void 0;
+				if (target) await bot.sendForward(target, nodes, {
+					source: "最近100条运行日志",
+					summary
+				});
+			} catch (error) {
+				ctx.logger.error(`[core] 发送日志转发失败: ${error}`);
+				await replyText(event, `发送日志失败：${String(error)}`);
+			}
 		}
 	});
 	return dispose;
@@ -4107,7 +4801,6 @@ const core = definePlugin({
 	description: "mioku 内置核心插件",
 	async setup(ctx) {
 		const rawPrefix = ctx.config.prefix ?? ".";
-		const cmdPrefix = new RegExp(`^${escapeRegExp(rawPrefix)}`);
 		const displayPrefix = rawPrefix;
 		const statusAdminOnly = ctx.config.status_permission === "admin-only";
 		rootLogger.info("========================================");
@@ -4125,12 +4818,17 @@ const core = definePlugin({
 			}));
 		} else ctx.logger.warn("config-service 未加载，core 插件将使用默认配置");
 		let accessRules = ensureAccessControlConfig();
+		ctx.commands.setAccessControl(accessRules);
 		if (configService) {
 			await configService.registerConfig("core", "access-control", accessRules);
 			const persisted = await configService.getConfig("core", "access-control");
-			if (persisted) accessRules = normalizeAccessConfig(persisted);
+			if (persisted) {
+				accessRules = normalizeAccessConfig(persisted);
+				ctx.commands.setAccessControl(accessRules);
+			}
 			disposers.push(configService.onConfigChange("core", "access-control", (next) => {
 				accessRules = normalizeAccessConfig(next);
+				ctx.commands.setAccessControl(accessRules);
 			}));
 		}
 		rootLogger.info(`访问控制已挂载: ${ctx.bots.length} 个 bot`);
@@ -4192,17 +4890,49 @@ const core = definePlugin({
 			bots: collectBots(),
 			adapters: collectAdapters()
 		}));
+		ctx.command({
+			name: "help",
+			aliases: ["帮助"],
+			permission: "master",
+			priority: -1e3,
+			description: "显示帮助信息",
+			handler: async ({ event }) => {
+				await event.reply(buildCoreHelpText(displayPrefix));
+			}
+		});
+		ctx.command({
+			name: "status",
+			aliases: ["状态"],
+			priority: -1e3,
+			description: "显示框架状态",
+			handler: async ({ event }) => {
+				if (statusAdminOnly && !isEventOwnerOrAdmin(event)) return;
+				await event.reply(await formatMiokuStatus(await getStatus()));
+			}
+		});
+		ctx.command({
+			name: "adapter",
+			aliases: ["适配器"],
+			priority: -1e3,
+			description: "显示适配器与连接实例",
+			handler: async ({ event }) => {
+				if (statusAdminOnly && !isEventOwnerOrAdmin(event)) return;
+				await event.reply(await getAdapterText());
+			}
+		});
 		const atTarget = (event) => {
 			const at = event.message.find((seg) => seg.type === "at");
 			const qq = at?.data?.qq ?? at?.data?.target;
 			return qq != null ? String(qq) : void 0;
 		};
-		disposers.push(ctx.handle("message", async (event) => {
+		const handleCoreMessage = async (event) => {
 			const ev = event;
 			const text$1 = ev.message.text();
-			if (!cmdPrefix.test(text$1)) return;
+			const currentPrefix = String(ctx.config.prefix ?? ".");
+			const currentCmdPrefix = new RegExp(`^${escapeRegExp(currentPrefix)}`);
+			if (!currentCmdPrefix.test(text$1)) return;
 			if (statusAdminOnly && !isEventOwnerOrAdmin(ev)) return;
-			const bare = text$1.replace(cmdPrefix, "").trim();
+			const bare = text$1.replace(currentCmdPrefix, "").trim();
 			if (bare === "状态" || bare === "status") {
 				await ev.reply(await formatMiokuStatus(await getStatus()));
 				return;
@@ -4211,10 +4941,10 @@ const core = definePlugin({
 				await ev.reply(await getAdapterText());
 				return;
 			}
-			if (!isEventOwner(ev)) return;
+			if (!isEventMaster(ev)) return;
 			const { cmd, params } = createCmd(text$1);
 			if (!cmd) return;
-			const subCmd = cmd.replace(cmdPrefix, "").replace(/\s+/g, "");
+			const subCmd = cmd.replace(currentCmdPrefix, "").replace(/\s+/g, "");
 			const target = params[0];
 			switch (subCmd) {
 				case "help":
@@ -4436,7 +5166,29 @@ const core = definePlugin({
 					process.exit(0);
 				}
 			}
-		}));
+		};
+		for (const command of [
+			{
+				name: "plugin",
+				aliases: ["插件"],
+				description: "插件管理"
+			},
+			{
+				name: "settings",
+				aliases: ["设置"],
+				description: "框架设置管理"
+			},
+			{
+				name: "exit",
+				aliases: ["退出"],
+				description: "退出框架进程"
+			}
+		]) ctx.command({
+			...command,
+			permission: "master",
+			priority: -1e3,
+			handler: ({ event }) => handleCoreMessage(event)
+		});
 		rootLogger.info("========================================");
 		rootLogger.info("          Mioku 服务初始化完成");
 		rootLogger.info("========================================");
@@ -4843,7 +5595,8 @@ var MiokuRuntime = class {
 	#enabledPlugins = new Map();
 	#driverFactory;
 	#builtinPlugins;
-	#dedupEnabled;
+	#correlator;
+	#commands;
 	#started = false;
 	#stopped = false;
 	constructor(options) {
@@ -4851,7 +5604,7 @@ var MiokuRuntime = class {
 		this.#logger = options.logger;
 		this.#driverFactory = options.driverFactory ?? (() => createDefaultDriver());
 		this.#builtinPlugins = options.builtinPlugins ?? BUILTIN_PLUGINS$1;
-		this.#dedupEnabled = options.dedup?.crossAdapter !== false;
+		this.#correlator = options.dedup?.crossAdapter === false ? void 0 : new EventCorrelator({ logger: this.#logger.child({ scope: "dedup" }) });
 		this.#driver = this.#driverFactory();
 		this.#bus = new EventBus();
 		this.#bus.setLogger((level, message, detail) => {
@@ -4861,6 +5614,14 @@ var MiokuRuntime = class {
 		});
 		this.#bots = new BotRegistry();
 		this.#capabilities = new CapabilityRegistry();
+		this.#commands = new CommandManager({
+			getDefaultPrefix: () => String(botConfig.prefix ?? "."),
+			getOwners: () => botConfig.owners,
+			getAdmins: () => botConfig.admins,
+			logger: this.#logger
+		});
+		this.#bus.setFilter((registration, event) => this.#commands.shouldDispatch(registration.source, event));
+		setActiveCommandManager(this.#commands);
 	}
 	get cwd() {
 		return this.#cwd;
@@ -4874,6 +5635,13 @@ var MiokuRuntime = class {
 	get bus() {
 		return this.#bus;
 	}
+	get commands() {
+		return this.#commands;
+	}
+	/** 事件关联器（跨适配器去重）；为 undefined 时表示已禁用 */
+	get correlator() {
+		return this.#correlator;
+	}
 	get bots() {
 		return this.#bots.all();
 	}
@@ -4888,14 +5656,16 @@ var MiokuRuntime = class {
 		return this.#bots.pick(bot_id);
 	}
 	listPlugins() {
-		return Array.from(this.#enabledPlugins.entries()).map(([key, entry]) => {
+		return Array.from(this.#enabledPlugins.entries()).map(([key]) => {
 			const colon = key.indexOf(":");
 			const type = key.slice(0, colon);
 			const name = key.slice(colon + 1);
+			const isExternal = type !== "builtin";
+			const version$2 = isExternal ? getPluginMetadata(name)?.version : void 0;
 			return {
 				name,
 				type: type === "builtin" ? "builtin" : "external",
-				version: entry.plugin.version
+				version: version$2
 			};
 		});
 	}
@@ -4981,13 +5751,17 @@ var MiokuRuntime = class {
 			driver: this.#driver,
 			capabilities: this.#capabilities,
 			logger: this.#logger.child({ adapter: state.definition.name }),
-			emit: (event) => this.#emitLifecycle(event)
+			emit: (event) => this.#emitLifecycle(event),
+			correlator: this.#correlator,
+			commands: this.#commands
 		});
 	}
 	async #loadPlugin(plugin, type) {
 		const cleanupTasks = [];
 		const ctx = new MiokuContext({
 			pluginName: `${type}:${plugin.name}`,
+			pluginId: plugin.name === "mioku-core" ? "core" : plugin.name,
+			commands: this.#commands,
 			bus: this.#bus,
 			bots: this.#bots,
 			driver: this.#driver,
@@ -4995,7 +5769,7 @@ var MiokuRuntime = class {
 			config: botConfig,
 			logger: this.#logger.child({ plugin: plugin.name }),
 			priority: plugin.priority ?? 100,
-			dedup: this.#dedupEnabled,
+			correlator: this.#correlator,
 			getAdapter: (name) => this.getAdapter(name),
 			listAdapters: () => this.adapters,
 			onUpdateConfig: async (updater) => {
@@ -5284,6 +6058,9 @@ var MiokuRuntime = class {
 		this.#enabledPlugins.clear();
 		this.#capabilities.clear();
 		this.#bots.clear();
+		this.#correlator?.clear();
+		this.#commands.clear();
+		setActiveCommandManager(void 0);
 		resetPluginMetadata();
 		try {
 			await this.#driver.shutdown();
@@ -5300,22 +6077,38 @@ const createRuntime = (options) => {
 
 //#endregion
 //#region src/runtime/plugin-artifacts.ts
+const commandKey = (value) => String(value).trim().replace(/^[#/.]+\s*/, "").split(/\s+/)[0].toLowerCase();
 async function registerPluginArtifacts(ctx) {
 	const helpService = ctx ? getService(ctx, Services.Help) : servicesRegistry["help"];
 	const plugins = getPluginMetadataList();
+	const commandManager = getActiveCommandManager();
+	const metadataByName = new Map(plugins.map((meta) => [meta.name, meta]));
+	const pluginNames = new Set([...metadataByName.keys(), ...(commandManager?.catalog() ?? []).filter((item) => item.kind === "plugin").map((item) => item.plugin)]);
 	let helpCount = 0;
-	for (const meta of plugins) {
-		if (meta.config?.help) if (helpService) {
-			helpService.registerHelp(meta.name, meta.config.help);
+	for (const pluginName of pluginNames) {
+		const meta = metadataByName.get(pluginName);
+		const generated = commandManager?.getPluginHelp(pluginName) ?? meta?.config?.help;
+		const existing = helpService?.getHelp(pluginName);
+		const help = generated ? {
+			...generated,
+			title: existing?.title || generated.title,
+			description: existing?.description || generated.description,
+			commands: [...existing?.commands ?? [], ...generated.commands.filter((command) => {
+				const key = commandKey(command.cmd);
+				return !(existing?.commands ?? []).some((item) => commandKey(item.cmd) === key);
+			})]
+		} : existing;
+		if (help) if (helpService) {
+			helpService.registerHelp(pluginName, help);
 			helpCount++;
-		} else rootLogger.warn(`[plugin-artifacts] 帮助服务未加载，跳过插件 "${meta.name}" 的帮助注册`);
-		const required = meta.config?.services;
+		} else rootLogger.warn(`[plugin-artifacts] 帮助服务未加载，跳过插件 "${pluginName}" 的帮助注册`);
+		const required = meta?.config?.services;
 		if (required && required.length > 0) {
 			const missing = required.filter((name) => !servicesRegistry[name]);
-			if (missing.length > 0) rootLogger.warn(`插件 "${meta.name}" 声明依赖服务 [${missing.join(", ")}]，但它们未加载`);
+			if (missing.length > 0) rootLogger.warn(`插件 "${pluginName}" 声明依赖服务 [${missing.join(", ")}]，但它们未加载`);
 		}
 	}
-	rootLogger.info(`[plugin-artifacts] 已处理 ${plugins.length} 个插件的元数据，注册帮助 ${helpCount} 个`);
+	rootLogger.info(`[plugin-artifacts] 已处理 ${pluginNames.size} 个插件，注册帮助 ${helpCount} 个`);
 }
 
 //#endregion
@@ -5446,6 +6239,7 @@ async function start(options = {}) {
 	};
 	process.on("SIGINT", () => void shutdown("SIGINT"));
 	process.on("SIGTERM", () => void shutdown("SIGTERM"));
+	installProcessErrorGuards();
 	return { stop: (reason) => stopRuntime(reason) };
 }
 function readVersion() {
@@ -5458,6 +6252,15 @@ function readVersion() {
 	}
 }
 const version$1 = readVersion();
+function installProcessErrorGuards() {
+	if (process.listenerCount("unhandledRejection") === 0) process.on("unhandledRejection", (reason) => {
+		const detail = reason instanceof Error ? reason.stack ?? reason.message : reason;
+		rootLogger.error(`[unhandledRejection] ${String(detail)}`);
+	});
+	if (process.listenerCount("uncaughtException") === 0) process.on("uncaughtException", (err) => {
+		rootLogger.error(`[uncaughtException] ${err.stack ?? err.message ?? String(err)}`);
+	});
+}
 
 //#endregion
 exports.AI_GEMINI_THINKING_LEVELS = AI_GEMINI_THINKING_LEVELS;
@@ -5471,8 +6274,10 @@ exports.BotRegistry = BotRegistry;
 exports.CORE_PLUGINS = CORE_PLUGINS;
 exports.CapabilityRegistry = CapabilityRegistry;
 exports.ChromeUA = ChromeUA;
+exports.CommandManager = CommandManager;
 exports.DriverShutdownError = DriverShutdownError;
 exports.EventBus = EventBus;
+exports.EventCorrelator = EventCorrelator;
 exports.HttpRequestError = HttpRequestError;
 exports.MessageSegmentImpl = MessageSegmentImpl;
 exports.MiokuContext = MiokuContext;
@@ -5582,6 +6387,7 @@ Object.defineProperty(exports, 'fs', {
     return node_fs.default;
   }
 });
+exports.getActiveCommandManager = getActiveCommandManager;
 exports.getAllPluginRuntimeStates = getAllPluginRuntimeStates;
 exports.getBuiltinPlugins = getBuiltinPlugins;
 exports.getConfigDir = getConfigDir;
@@ -5615,6 +6421,10 @@ exports.isBoolean = isBoolean;
 exports.isBotEvent = isBotEvent;
 exports.isDefined = isDefined;
 exports.isEventAdmin = isEventAdmin;
+exports.isEventAdminConfigOnly = isEventAdminConfigOnly;
+exports.isEventGroupAdmin = isEventGroupAdmin;
+exports.isEventGroupOwner = isEventGroupOwner;
+exports.isEventMaster = isEventMaster;
 exports.isEventOwner = isEventOwner;
 exports.isEventOwnerOrAdmin = isEventOwnerOrAdmin;
 exports.isFunction = isFunction;
@@ -5701,6 +6511,7 @@ exports.segment = segment;
 exports.sendMessage = sendMessage;
 exports.serviceManager = manager_default;
 exports.servicesRegistry = servicesRegistry;
+exports.setActiveCommandManager = setActiveCommandManager;
 exports.setBotCwd = setBotCwd;
 exports.setBuiltinPlugins = setBuiltinPlugins;
 exports.setPluginMetadata = setPluginMetadata;