mioku 1.0.7 → 1.0.9

package/dist/index.js

@@ -1,4 +1,4 @@
-import { buildSpawnPlan, commandExists, resolveCommand, runCommand, runCommandInherit, version } from "./exec-BxcCq8G9.js";
+import { buildSpawnPlan, commandExists, resolveCommand, runCommand, runCommandInherit, version } from "./exec-C3QTbHLt.js";
 import { createRequire } from "node:module";
 import * as fs$5 from "node:fs";
 import * as fs$4 from "node:fs";
@@ -13,7 +13,7 @@ import path, { default as path$1 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { hrtime } from "node:process";
 import { box, colorize, colors, colors as colors$1, stripAnsi } from "consola/utils";
-import crypto, { randomUUID } from "node:crypto";
+import crypto, { createHash, randomUUID } from "node:crypto";
 import nodeCron from "node-cron";
 import mriLib from "mri";
 import { Low } from "lowdb";
@@ -870,6 +870,8 @@ var AdapterContextImpl = class {
 	#capabilities;
 	#logger;
 	#emit;
+	#correlator;
+	#commands;
 	#pendingStarts = new Set();
 	constructor(options) {
 		this.#state = options.state;
@@ -879,6 +881,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);
@@ -942,6 +946,7 @@ var AdapterContextImpl = class {
 		};
 	}
 	async dispatch(event) {
+		this.#correlator?.observe(event);
 		if (event.kind === "message") {
 			const senderId = event.user_id;
 			if (senderId != null) {
@@ -952,6 +957,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) {
@@ -1030,6 +1041,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);
 	}
@@ -1064,9 +1078,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");
@@ -1100,6 +1118,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;
@@ -1138,6 +1161,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";
@@ -1904,130 +1978,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,
@@ -2082,6 +2045,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];
@@ -2098,6 +2064,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 或消息已失效。
 	*/
@@ -2128,12 +2147,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);
 		};
@@ -2150,6 +2169,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 = nodeCron.schedule(expression, async (taskContext) => {
@@ -2206,6 +2236,10 @@ var MiokuContext = class {
 	get buses() {
 		return this.#options.bus;
 	}
+	/** 当前运行时的命令管理器 */
+	get commands() {
+		return this.#options.commands;
+	}
 	get segment() {
 		return segment;
 	}
@@ -2246,24 +2280,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);
@@ -2274,19 +2314,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) => 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
@@ -2946,12 +3634,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";
@@ -3543,102 +4225,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();
@@ -3653,15 +4335,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
 	};
 }
@@ -3669,68 +4349,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
@@ -3744,64 +4426,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;
 }
@@ -3839,63 +4533,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;
@@ -4122,7 +4816,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("========================================");
@@ -4140,12 +4833,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`);
@@ -4207,17 +4905,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;
@@ -4226,10 +4956,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":
@@ -4451,7 +5181,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("========================================");
@@ -4858,7 +5610,8 @@ var MiokuRuntime = class {
 	#enabledPlugins = new Map();
 	#driverFactory;
 	#builtinPlugins;
-	#dedupEnabled;
+	#correlator;
+	#commands;
 	#started = false;
 	#stopped = false;
 	constructor(options) {
@@ -4866,7 +5619,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) => {
@@ -4876,6 +5629,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;
@@ -4889,6 +5650,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();
 	}
@@ -4903,14 +5671,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
 			};
 		});
 	}
@@ -4996,13 +5766,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,
@@ -5010,7 +5784,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) => {
@@ -5299,6 +6073,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();
@@ -5315,22 +6092,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
@@ -5461,6 +6254,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() {
@@ -5473,7 +6267,16 @@ 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
-export { AI_GEMINI_THINKING_LEVELS, AI_THINKING_LEVELS, AdapterContextImpl, AdapterRegistrationConflictError, ArchMap, BOT_CWD, BUILTIN_PLUGINS, BotRegistry, CORE_PLUGINS, CapabilityRegistry, ChromeUA, DriverShutdownError, EventBus, HttpRequestError, MessageSegmentImpl, MiokuContext, MiokuRuntime, ServiceManager, Services, SystemMap, TOOL_RESULT_FOLLOWUP_KEY, UnsupportedCapabilityError, WebSocketConnectTimeoutError, addService, applyLogLevel, asMessage, atOf, avatarGet, avatarSet, base64Decode, base64Encode, bindCapabilities, botConfig, botStatus, box, buildAdapterReport, buildMiokuStatus, buildRoutes, buildSpawnPlan, clamp, collectBotStats, colorize, colors, commandExists, connectedBotKey, connectedBots, conversationGetHistory, createCmd, createDB, createDefaultDriver, createFriendRef, createGroupRef, createImportContext, createMessage, createMiokuLogger, createRuntime, createStore, dayjs, dedent, defineAdapter, defineCapability, definePlugin, defineService, defineState, deleteServiceConfig, discoverAdapterCandidates, discoverPluginCandidates, displayAdapterId, ensureDataDir, filesize, filter, find, findLocalPlugins, formatAdapterReport, formatDuration, formatMiokuStatus, formatMiokuStatusFn, forwardSend, friendDelete, friendGetInfo, friendGetList, fs, getAllPluginRuntimeStates, getBuiltinPlugins, getConfigDir, getDataDir, getGTk, getPluginConfigDir, getPluginDataDir, getPluginMetadata, getPluginMetadataList, getPluginRuntimeState, getService, getServiceConfig, getServiceConfigDir, getServiceConfigs, getServiceDataDir, getTerminalInput, groupGetInfo, groupGetList, groupGetMembers, groupLeave, groupSetName, groupSetPortrait, groupSetWholeBan, hasEventRight, hasPluginState, hasRight, hasService, isAdapterEvent, isAdmin, isBoolean, isBotEvent, isDefined, isEventAdmin, isEventOwner, isEventOwnerOrAdmin, isFunction, isMessage, isMessageEvent, isMetaEvent, isMiokuPlugin, isNoticeEvent, isNumber, isObject, isOwner, isOwnerOrAdmin, isRequestEvent, isSegment, isString, loadAdapterDefinition, loadLocalPlugin, loadNpmPlugin, localNum, localeDate, localeTime, rootLogger as logger, match, md5, memberBan, memberGetInfo, memberKick, memberPoke, memberSetAdmin, memberSetCard, memberSetTitle, messageGet, messageGetForward, messageRecall, messageSend, mriLib as mri, noNullish, normalizeAIThinkingLevel, normalizeAdmins, normalizeOwners, normalizePlugins, normalizeSkillPermissionRole, noticeAdmins, noticeFriends, noticeGroups, noticeOwners, path, prettyMs, profileSet, qs, randomId, randomInt, randomItem, randomItems, readMiokuConfig, readPackageJson, readPackageJsonSafe, registerPluginArtifacts, registerServiceConfig, registerStatusProvider, reloadMiokuConfig, removePluginMetadata, requireService, resetPluginMetadata, resetPluginRuntimeState, resolveCommand, resolveEntry, resolveLocalPluginEntry, resolveLocalPluginPath, rootLogger, runCommand, runCommandInherit, segment, sendMessage, manager_default as serviceManager, servicesRegistry, setBotCwd, setBuiltinPlugins, setPluginMetadata, setPluginRuntimeState, setService, setWritableConfig, start, startRuntime, string2argv, stringifyError, stripAnsi, text, toArray, toId, toUserId, unique, updateMiokuConfig, updateServiceConfig, uuid, version$1 as version, wait, writePackageJson };
+export { AI_GEMINI_THINKING_LEVELS, AI_THINKING_LEVELS, AdapterContextImpl, AdapterRegistrationConflictError, ArchMap, BOT_CWD, BUILTIN_PLUGINS, BotRegistry, CORE_PLUGINS, CapabilityRegistry, ChromeUA, CommandManager, DriverShutdownError, EventBus, EventCorrelator, HttpRequestError, MessageSegmentImpl, MiokuContext, MiokuRuntime, ServiceManager, Services, SystemMap, TOOL_RESULT_FOLLOWUP_KEY, UnsupportedCapabilityError, WebSocketConnectTimeoutError, addService, applyLogLevel, asMessage, atOf, avatarGet, avatarSet, base64Decode, base64Encode, bindCapabilities, botConfig, botStatus, box, buildAdapterReport, buildMiokuStatus, buildRoutes, buildSpawnPlan, clamp, collectBotStats, colorize, colors, commandExists, connectedBotKey, connectedBots, conversationGetHistory, createCmd, createDB, createDefaultDriver, createFriendRef, createGroupRef, createImportContext, createMessage, createMiokuLogger, createRuntime, createStore, dayjs, dedent, defineAdapter, defineCapability, definePlugin, defineService, defineState, deleteServiceConfig, discoverAdapterCandidates, discoverPluginCandidates, displayAdapterId, ensureDataDir, filesize, filter, find, findLocalPlugins, formatAdapterReport, formatDuration, formatMiokuStatus, formatMiokuStatusFn, forwardSend, friendDelete, friendGetInfo, friendGetList, fs, getActiveCommandManager, getAllPluginRuntimeStates, getBuiltinPlugins, getConfigDir, getDataDir, getGTk, getPluginConfigDir, getPluginDataDir, getPluginMetadata, getPluginMetadataList, getPluginRuntimeState, getService, getServiceConfig, getServiceConfigDir, getServiceConfigs, getServiceDataDir, getTerminalInput, groupGetInfo, groupGetList, groupGetMembers, groupLeave, groupSetName, groupSetPortrait, groupSetWholeBan, hasEventRight, hasPluginState, hasRight, hasService, isAdapterEvent, isAdmin, isBoolean, isBotEvent, isDefined, isEventAdmin, isEventAdminConfigOnly, isEventGroupAdmin, isEventGroupOwner, isEventMaster, isEventOwner, isEventOwnerOrAdmin, isFunction, isMessage, isMessageEvent, isMetaEvent, isMiokuPlugin, isNoticeEvent, isNumber, isObject, isOwner, isOwnerOrAdmin, isRequestEvent, isSegment, isString, loadAdapterDefinition, loadLocalPlugin, loadNpmPlugin, localNum, localeDate, localeTime, rootLogger as logger, match, md5, memberBan, memberGetInfo, memberKick, memberPoke, memberSetAdmin, memberSetCard, memberSetTitle, messageGet, messageGetForward, messageRecall, messageSend, mriLib as mri, noNullish, normalizeAIThinkingLevel, normalizeAdmins, normalizeOwners, normalizePlugins, normalizeSkillPermissionRole, noticeAdmins, noticeFriends, noticeGroups, noticeOwners, path, prettyMs, profileSet, qs, randomId, randomInt, randomItem, randomItems, readMiokuConfig, readPackageJson, readPackageJsonSafe, registerPluginArtifacts, registerServiceConfig, registerStatusProvider, reloadMiokuConfig, removePluginMetadata, requireService, resetPluginMetadata, resetPluginRuntimeState, resolveCommand, resolveEntry, resolveLocalPluginEntry, resolveLocalPluginPath, rootLogger, runCommand, runCommandInherit, segment, sendMessage, manager_default as serviceManager, servicesRegistry, setActiveCommandManager, setBotCwd, setBuiltinPlugins, setPluginMetadata, setPluginRuntimeState, setService, setWritableConfig, start, startRuntime, string2argv, stringifyError, stripAnsi, text, toArray, toId, toUserId, unique, updateMiokuConfig, updateServiceConfig, uuid, version$1 as version, wait, writePackageJson };
 //# sourceMappingURL=index.js.map