mioku 1.0.8 → 1.0.9

package/dist/index.cjs

@@ -1,4 +1,4 @@
-const require_exec = require('./exec-BzdYBQLQ.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"));
@@ -856,6 +856,7 @@ var AdapterContextImpl = class {
 	#logger;
 	#emit;
 	#correlator;
+	#commands;
 	#pendingStarts = new Set();
 	constructor(options) {
 		this.#state = options.state;
@@ -866,6 +867,7 @@ var AdapterContextImpl = class {
 		this.#logger = options.logger;
 		this.#emit = options.emit;
 		this.#correlator = options.correlator;
+		this.#commands = options.commands;
 	}
 	registerBot(bot) {
 		return this.#bots.register(bot);
@@ -940,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) {
@@ -1055,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");
@@ -1091,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;
@@ -1129,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";
@@ -1896,31 +1964,18 @@ const Services = {
 
 //#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);
+/** 仅看 owners 名单：bot 主人（无群身份加成） */
+const isEventMaster = (event) => isEventMaster$1(event);
+/**
+* master 或当前群群主。等价于 `ctx.command({ permission: "owner" })` 的判断。
+*/
+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,
@@ -1975,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];
@@ -2074,7 +2132,7 @@ 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 correlator = bypassDedup ? void 0 : this.#options.correlator;
 		const wrappedHandler = async (event) => {
@@ -2096,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) => {
@@ -2152,6 +2221,10 @@ var MiokuContext = class {
 	get buses() {
 		return this.#options.bus;
 	}
+	/** 当前运行时的命令管理器 */
+	get commands() {
+		return this.#options.commands;
+	}
 	get segment() {
 		return segment;
 	}
@@ -2192,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);
@@ -2500,19 +2579,387 @@ var EventCorrelator = class {
 	}
 };
 
+//#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
@@ -3172,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";
@@ -3769,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();
@@ -3879,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
 	};
 }
@@ -3895,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
@@ -3970,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;
 }
@@ -4065,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;
@@ -4348,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("========================================");
@@ -4366,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`);
@@ -4433,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;
@@ -4452,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":
@@ -4677,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("========================================");
@@ -5085,6 +5596,7 @@ var MiokuRuntime = class {
 	#driverFactory;
 	#builtinPlugins;
 	#correlator;
+	#commands;
 	#started = false;
 	#stopped = false;
 	constructor(options) {
@@ -5102,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;
@@ -5115,6 +5635,9 @@ var MiokuRuntime = class {
 	get bus() {
 		return this.#bus;
 	}
+	get commands() {
+		return this.#commands;
+	}
 	/** 事件关联器（跨适配器去重）；为 undefined 时表示已禁用 */
 	get correlator() {
 		return this.#correlator;
@@ -5133,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
 			};
 		});
 	}
@@ -5227,13 +5752,16 @@ var MiokuRuntime = class {
 			capabilities: this.#capabilities,
 			logger: this.#logger.child({ adapter: state.definition.name }),
 			emit: (event) => this.#emitLifecycle(event),
-			correlator: this.#correlator
+			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,
@@ -5531,6 +6059,8 @@ var MiokuRuntime = class {
 		this.#capabilities.clear();
 		this.#bots.clear();
 		this.#correlator?.clear();
+		this.#commands.clear();
+		setActiveCommandManager(void 0);
 		resetPluginMetadata();
 		try {
 			await this.#driver.shutdown();
@@ -5547,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
@@ -5728,6 +6274,7 @@ 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;
@@ -5840,6 +6387,7 @@ Object.defineProperty(exports, 'fs', {
     return node_fs.default;
   }
 });
+exports.getActiveCommandManager = getActiveCommandManager;
 exports.getAllPluginRuntimeStates = getAllPluginRuntimeStates;
 exports.getBuiltinPlugins = getBuiltinPlugins;
 exports.getConfigDir = getConfigDir;
@@ -5873,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;
@@ -5959,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;