@koishi-ce/plugin-help 1.0.0

package/lib/assets/en-US-f1RJaaO6.yml

@@ -0,0 +1,22 @@
+commands:
+  help:
+    description: Show help
+    shortcuts:
+      help: <></>
+    options:
+      help: show this message
+      authority: show authority requirements
+      showHidden: show hidden options and commands
+    messages:
+      not-found: Command not found.
+      hint-authority: this minimum authority is marked in parentheses
+      hint-subcommand: those marked with an asterisk have subcommands
+      command-title: 'Command: {0}'
+      command-aliases: 'Aliases: {0}.'
+      command-examples: 'Examples:'
+      command-authority: 'Minimal authority: {0}.'
+      subcommand-prolog: 'Available subcommands{0}:'
+      global-prolog: 'Available commands{0}:'
+      global-epilog: Type "{0}help <command>" to see syntax and examples for a specific command.
+      available-options: 'Available options:'
+      available-options-with-authority: 'Available options (parentheses indicate additional authority requirement):'

package/lib/assets/zh-CN-DmsdBxOO.yml

@@ -0,0 +1,22 @@
+commands:
+  help:
+    description: 显示帮助信息
+    shortcuts:
+      help: 帮助
+    options:
+      help: 显示此信息
+      authority: 显示权限设置
+      showHidden: 查看隐藏的选项和指令
+    messages:
+      not-found: 指令未找到。
+      hint-authority: 括号内为对应的最低权限等级
+      hint-subcommand: 标有星号的表示含有子指令
+      command-title: 指令：{0}
+      command-aliases: 别名：{0}。
+      command-examples: 使用示例：
+      command-authority: 最低权限：{0} 级。
+      subcommand-prolog: 可用的子指令有{0}：
+      global-prolog: 当前可用的指令有{0}：
+      global-epilog: 输入“{0}help 指令名”查看特定指令的语法和使用示例。
+      available-options: 可用的选项有：
+      available-options-with-authority: 可用的选项有（括号内为额外要求的权限等级）：

package/lib/index.d.ts

@@ -0,0 +1,38 @@
+import { Command, Computed, Context, Schema, Session } from "@koishi-ce/koishi";
+//#region src/index.d.ts
+declare module "@koishi-ce/koishi" {
+  interface Events {
+    "help/command"(output: string[], command: Command, session: Session<never, never>): void;
+    "help/option"(output: string, option: Argv.OptionVariant, command: Command, session: Session<never, never>): string;
+  }
+  namespace Command {
+    interface Config {
+      /** 默认隐藏所有选项 */
+      hideOptions?: boolean;
+      /** 在帮助中隐藏此指令 */
+      hidden?: Computed<boolean>;
+      /** 本地化参数 */
+      params?: object;
+    }
+  }
+  namespace Argv {
+    interface OptionConfig<T extends Argv.Type = Argv.Type> {
+      /** 在帮助中隐藏此选项 */
+      hidden?: Computed<boolean>;
+      /** 本地化参数 */
+      params?: object;
+    }
+  }
+}
+/** 配置项 */
+interface Config {
+  /** 是否启用“帮助”快捷调用 */
+  shortcut?: boolean;
+  /** 是否为每个指令注入 `-h, --help` 选项 */
+  options?: boolean;
+}
+declare const Config: Schema<Config>;
+declare const name = "help";
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { Config, apply, name };

package/lib/index.mjs

@@ -0,0 +1,240 @@
+import { Context, Schema, h } from "@koishi-ce/koishi";
+import enUS from "./assets/en-US-f1RJaaO6.yml";
+import zhCN from "./assets/zh-CN-DmsdBxOO.yml";
+//#region src/index.ts
+/**
+* 帮助指令插件（help）。
+*
+* 提供 `help [command]` 指令（权限 0）与全局快捷调用“帮助”，
+* 并默认为所有指令注入 `-h, --help` 选项；输出指令的描述、别名、
+* 用法、选项、示例与子指令列表，支持按权限与 hidden 配置过滤。
+* 其他插件可通过 `help/command`、`help/option` 事件改写帮助输出，
+* 或通过指令 / 选项的 hidden、hideOptions、params 配置定制展示。
+* 配置项：shortcut（启用快捷调用）、options（注入 -h 选项）。
+*/
+const Config = Schema.object({
+	shortcut: Schema.boolean().default(true).description("是否启用快捷调用。"),
+	options: Schema.boolean().default(true).description("是否为每个指令添加 `-h, --help` 选项。")
+});
+/** 在当前会话中转执行 help 指令（供 -h 选项与无 action 的指令复用） */
+function executeHelp(session, name) {
+	if (!session.app.$commander.get("help")) return;
+	return session.execute({
+		name: "help",
+		args: [name]
+	});
+}
+const name = "help";
+function apply(ctx, config) {
+	ctx.i18n.define("zh-CN", zhCN);
+	ctx.i18n.define("en-US", enUS);
+	function enableHelp(command) {
+		command[Context.current] = ctx;
+		command.option("help", "-h", {
+			hidden: true,
+			notUsage: true,
+			descPath: "commands.help.options.help"
+		});
+	}
+	ctx.schema.extend("command", Schema.object({
+		hideOptions: Schema.boolean().description("是否隐藏所有选项。").default(false).hidden(),
+		hidden: Schema.computed(Schema.boolean()).description("在帮助菜单中隐藏指令。").default(false),
+		params: Schema.any().description("帮助信息的本地化参数。").hidden()
+	}), 900);
+	ctx.schema.extend("command-option", Schema.object({
+		hidden: Schema.computed(Schema.boolean()).description("在帮助菜单中隐藏选项。").default(false),
+		params: Schema.any().description("帮助信息的本地化参数。").hidden()
+	}), 900);
+	if (config.options !== false) {
+		ctx.$commander._commandList.forEach(enableHelp);
+		ctx.on("command-added", enableHelp);
+	}
+	ctx.before("command/execute", (argv) => {
+		const { command, options, session } = argv;
+		if (!command || !session || !options) return;
+		if (options["help"] && command._options["help"]) return executeHelp(session, command.name);
+		if (command["_actions"].length) return;
+		return executeHelp(session, command.name);
+	});
+	const $ = ctx.$commander;
+	/**
+	* 按名称解析目标指令；未命中时再按 i18n 快捷调用匹配
+	* @param target 用户输入的指令名或快捷调用文本
+	* @returns 指令对象；仅有模糊命中时返回候选列表
+	*/
+	function findCommand(target, session) {
+		const command = $.resolve(target, session);
+		if (command?.ctx.filter(session)) return command;
+		const data = ctx.i18n.find("commands.(name).shortcuts.(variant)", target).map((item) => ({
+			...item,
+			command: $.resolve(item.data.name, session)
+		})).filter((item) => item.command?.match(session));
+		const perfect = data.filter((item) => item.similarity === 1);
+		if (!perfect.length) return data;
+		return perfect[0]?.command;
+	}
+	const createCollector = (key) => (argv, fields) => {
+		const { args, session } = argv;
+		const [target] = args ?? [];
+		if (!session) return;
+		const result = findCommand(target, session);
+		if (!Array.isArray(result)) {
+			if (result) session.collect(key, {
+				...argv,
+				command: result,
+				args: [],
+				options: { help: true }
+			}, fields);
+			return;
+		}
+		for (const { command } of result) {
+			if (!command) continue;
+			session.collect(key, {
+				...argv,
+				command,
+				args: [],
+				options: { help: true }
+			}, fields);
+		}
+	};
+	/** 推断用户输入对应的指令；仅有模糊命中时发起相似度建议（“您要找的是不是…”） */
+	async function inferCommand(target, session) {
+		const result = findCommand(target, session);
+		if (!Array.isArray(result)) return result;
+		const expect = $.available(session).filter((name) => {
+			return name && session.app.i18n.compare(name, target);
+		});
+		for (const item of result) {
+			if (expect.includes(item.data.name)) continue;
+			expect.push(item.data.name);
+		}
+		const cache = /* @__PURE__ */ new Map();
+		const name = await session.suggest({
+			expect,
+			prefix: session.text(".not-found"),
+			suffix: session.text("internal.suggest-command"),
+			filter: (name) => {
+				const command = $.resolve(name, session);
+				if (!command) return false;
+				return ctx.permissions.test(`command:${command.name}`, session, cache);
+			}
+		});
+		if (!name) return;
+		return $.resolve(name, session);
+	}
+	const cmd = ctx.command("help [command:string]", {
+		authority: 0,
+		...config
+	}).userFields(["authority"]).userFields(createCollector("user")).channelFields(createCollector("channel")).option("showHidden", "-H").action(async ({ session, options }, target) => {
+		if (!session || !options) return;
+		if (!target) {
+			const prefix = session.resolve(session.app.koishi.config.prefix)?.[0] ?? "";
+			const output = await formatCommands(".global-prolog", session, $._commandList.filter((cmd) => cmd.parent === null), options);
+			const epilog = session.text(".global-epilog", [prefix]);
+			if (epilog) output.push(epilog);
+			return output.filter(Boolean).join("\n");
+		}
+		const command = await inferCommand(target, session);
+		if (!command) return;
+		if (!await ctx.permissions.test(`command:${command.name}`, session)) return session.text("internal.low-authority");
+		return showHelp(command, session, options);
+	});
+	if (config.shortcut !== false) cmd.shortcut("help", {
+		i18n: true,
+		fuzzy: true
+	});
+}
+/** 深度优先遍历指令树，产出当前会话可见（未被 hidden 过滤）的指令 */
+function* getCommands(session, commands, showHidden = false) {
+	for (const command of commands) {
+		if (!showHidden && session.resolve(command.config.hidden)) continue;
+		if (command.match(session) && Object.keys(command._aliases).length) yield command;
+		else yield* getCommands(session, command.children, showHidden);
+	}
+}
+/** 将一组指令格式化为帮助列表（标题行 + 每条指令一行的缩进展示） */
+async function formatCommands(path, session, children, options) {
+	const cache = /* @__PURE__ */ new Map();
+	children = Array.from(getCommands(session, children, options.showHidden));
+	children = (await Promise.all(children.map(async (command) => {
+		return [command, await session.app.permissions.test(`command:${command.name}`, session, cache)];
+	}))).filter(([, result]) => result).map(([command]) => command);
+	children.sort((a, b) => a.displayName > b.displayName ? 1 : -1);
+	if (!children.length) return [];
+	const prefix = session.resolve(session.app.koishi.config.prefix)?.[0] ?? "";
+	const output = children.map(({ name, displayName, config }) => {
+		let output = `    ${prefix}${displayName.replace(/\./g, " ")}`;
+		output += `  ${session.text([`commands.${name}.description`, ""], config.params)}`;
+		return output;
+	});
+	const hints = [];
+	const hintText = hints.length ? session.text("general.paren", [hints.join(session.text("general.comma"))]) : "";
+	output.unshift(session.text(path, [hintText]));
+	return output;
+}
+/** 判断选项对当前会话是否可见（权限不足或被 hidden 标记隐藏时不可见） */
+function getOptionVisibility(option, session) {
+	if (session.user && (option.authority ?? 0) > session.user.authority) return false;
+	return !session.resolve(option.hidden);
+}
+/** 生成指令的选项帮助段落（考虑 hideOptions、权限与 hidden 过滤） */
+function getOptions(command, session, config) {
+	if (command.config.hideOptions && !config.showHidden) return [];
+	if (!(config.showHidden ? Object.values(command._options) : Object.values(command._options).filter((option) => getOptionVisibility(option, session))).length) return [];
+	const output = [];
+	Object.values(command._options).forEach((option) => {
+		function pushOption(option, name) {
+			if (!config.showHidden && !getOptionVisibility(option, session)) return;
+			let line = `${h.escape(option.syntax)}`;
+			const description = session.text(option.descPath ?? [`commands.${command.name}.options.${name}`, ""], option.params);
+			if (description) line += `  ${description}`;
+			line = command.ctx.chain("help/option", line, option, command, session);
+			output.push(`    ${line}`);
+		}
+		if (!("value" in option)) pushOption(option, option.name ?? "");
+		for (const value in option.variants) {
+			const variant = option.variants[value];
+			if (!variant) continue;
+			pushOption(variant, `${option.name}.${value}`);
+		}
+	});
+	if (!output.length) return [];
+	output.unshift(session.text(".available-options"));
+	return output;
+}
+/** 生成单个指令的完整帮助文本（标题、描述、别名、用法、选项、示例、子指令） */
+async function showHelp(command, session, config) {
+	const output = [session.text(".command-title", [command.displayName.replace(/\./g, " ") + command.declaration])];
+	const description = session.text([`commands.${command.name}.description`, ""], command.config.params);
+	if (description) output.push(description);
+	if (session.app.database) {
+		const argv = {
+			command,
+			args: [],
+			options: { help: true }
+		};
+		const userFields = session.collect("user", argv);
+		await session.observeUser(userFields);
+		if (!session.isDirect) {
+			const channelFields = session.collect("channel", argv);
+			await session.observeChannel(channelFields);
+		}
+	}
+	if (Object.keys(command._aliases).length > 1) output.push(session.text(".command-aliases", [Array.from(Object.keys(command._aliases).slice(1)).join("，")]));
+	session.app.emit(session, "help/command", output, command, session);
+	if (command._usage) output.push(typeof command._usage === "string" ? command._usage : await command._usage(session));
+	else {
+		const text = session.text([`commands.${command.name}.usage`, ""], command.config.params);
+		if (text) output.push(text);
+	}
+	output.push(...getOptions(command, session, config));
+	if (command._examples.length) output.push(session.text(".command-examples"), ...command._examples.map((example) => `    ${example}`));
+	else {
+		const text = session.text([`commands.${command.name}.examples`, ""], command.config.params);
+		if (text) output.push(session.text(".command-examples"), ...text.split("\n").map((line) => `    ${line}`));
+	}
+	output.push(...await formatCommands(".subcommand-prolog", session, command.children, config));
+	return output.filter(Boolean).join("\n");
+}
+//#endregion
+export { Config, apply, name };

package/locales/de-DE.yml

@@ -0,0 +1,22 @@
+commands:
+  help:
+    description: 显示帮助信息
+    shortcuts:
+      help: Hilfe
+    options:
+      help: 显示此信息
+      authority: 显示权限设置
+      showHidden: 查看隐藏的选项和指令
+    messages:
+      not-found: 指令未找到。
+      hint-authority: 括号内为对应的最低权限等级
+      hint-subcommand: 标有星号的表示含有子指令
+      command-title: 指令：{0}
+      command-aliases: 别名：{0}。
+      command-examples: 使用示例：
+      command-authority: 最低权限：{0} 级。
+      subcommand-prolog: 可用的子指令有{0}：
+      global-prolog: 当前可用的指令有{0}：
+      global-epilog: 输入“{0}help 指令名”查看特定指令的语法和使用示例。
+      available-options: 可用的选项有：
+      available-options-with-authority: 可用的选项有（括号内为额外要求的权限等级）：

package/locales/en-US.yml

@@ -0,0 +1,22 @@
+commands:
+  help:
+    description: Show help
+    shortcuts:
+      help: <></>
+    options:
+      help: show this message
+      authority: show authority requirements
+      showHidden: show hidden options and commands
+    messages:
+      not-found: Command not found.
+      hint-authority: this minimum authority is marked in parentheses
+      hint-subcommand: those marked with an asterisk have subcommands
+      command-title: 'Command: {0}'
+      command-aliases: 'Aliases: {0}.'
+      command-examples: 'Examples:'
+      command-authority: 'Minimal authority: {0}.'
+      subcommand-prolog: 'Available subcommands{0}:'
+      global-prolog: 'Available commands{0}:'
+      global-epilog: Type "{0}help <command>" to see syntax and examples for a specific command.
+      available-options: 'Available options:'
+      available-options-with-authority: 'Available options (parentheses indicate additional authority requirement):'

package/locales/fr-FR.yml

@@ -0,0 +1,22 @@
+commands:
+  help:
+    description: Afficher l'aide
+    shortcuts:
+      help: Aide
+    options:
+      help: afficher cette aide
+      authority: afficher les droits nécessaires
+      showHidden: afficher les options et commandes cachées
+    messages:
+      not-found: Commande inconnue.
+      hint-authority: les droits minimums sont indiqués entre parenthèses
+      hint-subcommand: ces commandes avec un astérisque ont des sous-commandes
+      command-title: 'Commande : {0}'
+      command-aliases: 'Alias : {0}.'
+      command-examples: 'Exemples :'
+      command-authority: 'Droit minimum : {0}.'
+      subcommand-prolog: 'Commandes disponibles{0} :'
+      global-prolog: 'Commandes disponibles{0} :'
+      global-epilog: Tapez "{0}help <commande>" pour voir la syntaxe et les exemples pour une commande spécifique.
+      available-options: 'Options disponibles :'
+      available-options-with-authority: 'Options disponibles (les parenthèses indiquent un droit supplémentaire) :'

package/locales/ja-JP.yml

@@ -0,0 +1,22 @@
+commands:
+  help:
+    description: ヘルプを表示
+    shortcuts:
+      help: ヘルプ
+    options:
+      help: このメッセージを表示
+      authority: コマンドやオプションの権限を表示
+      showHidden: 隠しコマンドやオプションを表示
+    messages:
+      not-found: コマンドが見つかりません。
+      hint-authority: 最低権限は括弧にで表示されています
+      hint-subcommand: サブコマンドがあるコマンドはアスタリスクで表示されています
+      command-title: コマンド：{0}
+      command-aliases: 別名：{0}。
+      command-examples: 例：
+      command-authority: 最低権限：{0}。
+      subcommand-prolog: 利用可能なサブコマンド{0}：
+      global-prolog: 利用可能なコマンド{0}：
+      global-epilog: '「{0}help <command>」を送信してコマンドの使い方を表示します。'
+      available-options: 利用可能なオプション：
+      available-options-with-authority: 利用可能なオプション（必要な権限は括弧にで表示されています）：

package/locales/ru-RU.yml

@@ -0,0 +1,22 @@
+commands:
+  help:
+    description: 显示帮助信息
+    shortcuts:
+      help: Справка
+    options:
+      help: 显示此信息
+      authority: 显示权限设置
+      showHidden: 查看隐藏的选项和指令
+    messages:
+      not-found: 指令未找到。
+      hint-authority: 括号内为对应的最低权限等级
+      hint-subcommand: 标有星号的表示含有子指令
+      command-title: 指令：{0}
+      command-aliases: 别名：{0}。
+      command-examples: 使用示例：
+      command-authority: 最低权限：{0} 级。
+      subcommand-prolog: 可用的子指令有{0}：
+      global-prolog: 当前可用的指令有{0}：
+      global-epilog: 输入“{0}help 指令名”查看特定指令的语法和使用示例。
+      available-options: 可用的选项有：
+      available-options-with-authority: 可用的选项有（括号内为额外要求的权限等级）：

package/locales/zh-CN.yml

@@ -0,0 +1,22 @@
+commands:
+  help:
+    description: 显示帮助信息
+    shortcuts:
+      help: 帮助
+    options:
+      help: 显示此信息
+      authority: 显示权限设置
+      showHidden: 查看隐藏的选项和指令
+    messages:
+      not-found: 指令未找到。
+      hint-authority: 括号内为对应的最低权限等级
+      hint-subcommand: 标有星号的表示含有子指令
+      command-title: 指令：{0}
+      command-aliases: 别名：{0}。
+      command-examples: 使用示例：
+      command-authority: 最低权限：{0} 级。
+      subcommand-prolog: 可用的子指令有{0}：
+      global-prolog: 当前可用的指令有{0}：
+      global-epilog: 输入“{0}help 指令名”查看特定指令的语法和使用示例。
+      available-options: 可用的选项有：
+      available-options-with-authority: 可用的选项有（括号内为额外要求的权限等级）：

package/locales/zh-TW.yml

@@ -0,0 +1,22 @@
+commands:
+  help:
+    description: 顯示幫助信息
+    shortcuts:
+      help: 幫助
+    options:
+      help: 顯示此信息
+      authority: 顯示權限設定
+      showHidden: 查看隱藏的選項和指令
+    messages:
+      not-found: 指令未找到。
+      hint-authority: 括號內為對應的最低權限等級
+      hint-subcommand: 標有星號的表示含有子指令
+      command-title: 指令：{0}
+      command-aliases: 別名：{0}。
+      command-examples: 使用示例：
+      command-authority: 最低權限：{0} 級。
+      subcommand-prolog: 可用的子指令有{0}：
+      global-prolog: 當前可用的指令有{0}：
+      global-epilog: 輸入“{0}help 指令名”查看特定指令的語法和使用示例。
+      available-options: 可用的選項有：
+      available-options-with-authority: 可用的選項有（括號內為額外要求的權限等級）：

package/package.json

@@ -0,0 +1,66 @@
+{
+    "name": "@koishi-ce/plugin-help",
+    "description": "Help plugin for Koishi",
+    "version": "1.0.0",
+    "type": "module",
+    "main": "lib/index.mjs",
+    "typings": "lib/index.d.ts",
+    "files": [
+        "lib",
+        "src",
+        "locales"
+    ],
+    "contributors": [
+        "Shigma <shigma10826@gmail.com>",
+        "Oppenheymu <oppenheymu@gmail.com>"
+    ],
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Koishi-CE/koishi.git",
+        "directory": "plugins/common/help"
+    },
+    "bugs": {
+        "url": "https://github.com/Koishi-CE/koishi/issues"
+    },
+    "homepage": "https://koishi.chat/plugins/common/help.html",
+    "keywords": [
+        "bot",
+        "chatbot",
+        "koishi",
+        "plugin",
+        "help"
+    ],
+    "koishi": {
+        "browser": true,
+        "category": "tool",
+        "description": {
+            "en": "Show help for commands",
+            "zh": "显示指令的帮助信息"
+        },
+        "locales": [
+            "zh",
+            "en",
+            "ja",
+            "fr",
+            "zh-TW"
+        ]
+    },
+    "peerDependencies": {
+        "koishi": "^4.18.11"
+    },
+    "devDependencies": {
+        "@koishi-ce/plugin-mock": "^1.0.0",
+        "@minatojs/driver-memory": "^3.7.0",
+        "@koishi-ce/koishi": "^1.0.0",
+        "minato": "^3.7.0"
+    },
+    "exports": {
+        ".": {
+            "source": "./src/index.ts",
+            "types": "./lib/index.d.ts",
+            "import": "./lib/index.mjs",
+            "default": "./lib/index.mjs"
+        }
+    }
+}

package/src/index.test.ts

@@ -0,0 +1,214 @@
+/**
+ * help 插件测试：覆盖帮助列表、指令属性（别名 / 用法 / 示例 / 权限）、
+ * 选项展示、子指令、无数据库场景与 shortcut / options 配置开关。
+ */
+import { beforeAll, describe, it } from "bun:test";
+import { App } from "@koishi-ce/koishi";
+import * as help from "@koishi-ce/plugin-help";
+import mock from "@koishi-ce/plugin-mock";
+import memory from "@minatojs/driver-memory";
+
+const app = new App({
+	minSimilarity: 0.64,
+});
+
+app.plugin(mock);
+app.plugin(help);
+app.plugin(memory);
+
+app.i18n.define("$zh-CN", "commands.help.messages.global-epilog", "EPILOG");
+
+const client = app.mock.client("123", "456");
+
+beforeAll(async () => {
+	await app.start();
+	await app.mock.initUser("123", 2);
+	await app.mock.initChannel("456");
+});
+
+let message: string;
+
+describe("@koishi-ce/plugin-help", () => {
+	// 验证全局帮助列表、“帮助”快捷调用、-h 选项与相似度建议（“您要找的是不是…”）
+	it("basic support", async () => {
+		await client.shouldReply(
+			"help",
+			(message = [
+				"当前可用的指令有：",
+				"    help  显示帮助信息",
+				"EPILOG",
+			].join("\n")),
+		);
+
+		// 全局快捷调用
+		await client.shouldReply("帮助", message);
+
+		await client.shouldReply(
+			"help help",
+			(message = [
+				"指令：help [command]",
+				"显示帮助信息",
+				"可用的选项有：",
+				"    -H, --show-hidden  查看隐藏的选项和指令",
+			].join("\n")),
+		);
+
+		await client.shouldReply("help xxxx", "指令未找到。");
+		await client.shouldReply(
+			"help heip",
+			"指令未找到。您要找的是不是“help”？回复句号以使用推测的指令。",
+		);
+		await client.shouldReply(".", message);
+		await client.shouldReply("help -h", message);
+		await client.shouldReply("help 帮助", message);
+	});
+
+	// 验证 description / 别名 / usage / example / authority 等指令属性在帮助中的呈现
+	it("command attributes", async () => {
+		app.command("foo1", "DESCRIPTION").alias("foo");
+		app.command("foo3", "DESCRIPTION").shortcut(/foobar/);
+		app.command("foo4", "DESCRIPTION").usage("USAGE TEXT");
+		app.command("foo5", "DESCRIPTION").usage(({ userId }) => `${userId}`);
+		app.command("foo6", "DESCRIPTION").example("EXAMPLE TEXT");
+		app.command("foo7", "DESCRIPTION", { authority: 3 });
+
+		await client.shouldReply(
+			"help foo1",
+			"指令：foo1\nDESCRIPTION\n别名：foo。",
+		);
+		await client.shouldReply("help foobar", "指令：foo3\nDESCRIPTION");
+		await client.shouldReply(
+			"help foo4",
+			"指令：foo4\nDESCRIPTION\nUSAGE TEXT",
+		);
+		await client.shouldReply("help foo5", "指令：foo5\nDESCRIPTION\n123");
+		await client.shouldReply(
+			"help foo6",
+			"指令：foo6\nDESCRIPTION\n使用示例：\n    EXAMPLE TEXT",
+		);
+		await client.shouldReply("help foo7", "权限不足。");
+	});
+
+	// 验证 hideOptions、选项权限与 hidden 选项的过滤，以及 -H 的全量展示
+	it("command options", async () => {
+		const bar = app
+			.command("bar <arg:number>", "DESCRIPTION", { hideOptions: true })
+			.option("opt1", "选项1", { authority: 2 })
+			.option("opt1", "-n  选项2", { value: false })
+			.option("opt2", "[arg:boolean]  选项3")
+			.option("opt3", "-o [arg:boolean]", { hidden: true });
+
+		await client.shouldReply(
+			"help bar",
+			(message = "指令：bar <arg>\nDESCRIPTION"),
+		);
+
+		bar.config.hideOptions = false;
+
+		await client.shouldReply(
+			"help bar",
+			[
+				message,
+				"可用的选项有：",
+				"    --opt1  选项1",
+				"    -n  选项2",
+				"    --opt2 [arg]  选项3",
+			].join("\n"),
+		);
+
+		await client.shouldReply(
+			"help bar -H",
+			[
+				message,
+				"可用的选项有：",
+				"    -h, --help  显示此信息",
+				"    --opt1  选项1",
+				"    -n  选项2",
+				"    --opt2 [arg]  选项3",
+				"    -o, --opt3 [arg]",
+			].join("\n"),
+		);
+	});
+
+	// 验证多级子指令在父指令帮助中的逐层呈现
+	it("subcommand", async () => {
+		const foo2 = app.command("foo2", "DESCRIPTION", { authority: 0 });
+		const foo1 = foo2.subcommand("foo1");
+		foo1.subcommand("foo3");
+
+		await client.shouldReply(
+			"help foo2",
+			[
+				"指令：foo2",
+				"DESCRIPTION",
+				"可用的子指令有：",
+				"    foo1  DESCRIPTION",
+			].join("\n"),
+		);
+
+		await client.shouldReply(
+			"help foo1",
+			[
+				"指令：foo1",
+				"DESCRIPTION",
+				"别名：foo。",
+				"可用的子指令有：",
+				"    foo3  DESCRIPTION",
+			].join("\n"),
+		);
+	});
+
+	// 无数据库环境下 help 仍能正常列出指令
+	it("no database", async () => {
+		const app = new App();
+		app.plugin(help);
+		app.plugin(mock);
+		app.i18n.define("$zh-CN", "commands.help.messages.global-epilog", "");
+		await app.start();
+
+		const client = app.mock.client("123");
+		await client.shouldReply(
+			"help",
+			"当前可用的指令有：\n    help  显示帮助信息",
+		);
+	});
+
+	// options: false 时不为指令注入 -h 选项
+	it("disable help options", async () => {
+		const app = new App();
+		app.plugin(help, { options: false });
+		app.plugin(mock);
+		app.command("foo").action(() => {});
+		await app.start();
+
+		const client = app.mock.client("123");
+		await client.shouldReply("help");
+		await client.shouldNotReply("foo -h");
+	});
+
+	// shortcut: false 时不注册“帮助”全局快捷调用
+	it("disable help shortcut", async () => {
+		const app = new App();
+		app.plugin(help, { shortcut: false });
+		app.plugin(mock);
+		await app.start();
+
+		const client = app.mock.client("123");
+		await client.shouldReply("help");
+		await client.shouldNotReply("帮助");
+	});
+
+	// 带 checkArgCount 的指令在缺参追问后仍可用 -h 查看帮助（回归 #769）
+	it("checkArgCount (#769)", async () => {
+		const app = new App();
+		app.plugin(help);
+		app.plugin(mock);
+		app.command("test <arg>", { checkArgCount: true }).action(() => "pass");
+		await app.start();
+
+		const client = app.mock.client("123");
+		await client.shouldReply("test", "请发送arg。");
+		await client.shouldReply("foo", "pass");
+		await client.shouldReply("test -h", "指令：test <arg>");
+	});
+});

package/src/index.ts

@@ -0,0 +1,468 @@
+/**
+ * 帮助指令插件（help）。
+ *
+ * 提供 `help [command]` 指令（权限 0）与全局快捷调用“帮助”，
+ * 并默认为所有指令注入 `-h, --help` 选项；输出指令的描述、别名、
+ * 用法、选项、示例与子指令列表，支持按权限与 hidden 配置过滤。
+ * 其他插件可通过 `help/command`、`help/option` 事件改写帮助输出，
+ * 或通过指令 / 选项的 hidden、hideOptions、params 配置定制展示。
+ * 配置项：shortcut（启用快捷调用）、options（注入 -h 选项）。
+ */
+import {
+	type Argv,
+	type Command,
+	type Computed,
+	Context,
+	type FieldCollector,
+	h,
+	Schema,
+	type Session,
+} from "@koishi-ce/koishi";
+import enUS from "../locales/en-US.yml";
+import zhCN from "../locales/zh-CN.yml";
+
+declare module "@koishi-ce/koishi" {
+	interface Events {
+		"help/command"(
+			output: string[],
+			command: Command,
+			session: Session<never, never>,
+		): void;
+		"help/option"(
+			output: string,
+			option: Argv.OptionVariant,
+			command: Command,
+			session: Session<never, never>,
+		): string;
+	}
+
+	namespace Command {
+		interface Config {
+			/** 默认隐藏所有选项 */
+			hideOptions?: boolean;
+			/** 在帮助中隐藏此指令 */
+			hidden?: Computed<boolean>;
+			/** 本地化参数 */
+			params?: object;
+		}
+	}
+
+	namespace Argv {
+		interface OptionConfig<T extends Argv.Type = Argv.Type> {
+			/** 在帮助中隐藏此选项 */
+			hidden?: Computed<boolean>;
+			/** 本地化参数 */
+			params?: object;
+		}
+	}
+}
+
+/** 帮助输出的行为选项 */
+interface HelpOptions {
+	/** 显示被 hidden 标记隐藏的指令与选项（对应 -H 选项） */
+	showHidden?: boolean;
+}
+
+/** 配置项 */
+export interface Config {
+	/** 是否启用“帮助”快捷调用 */
+	shortcut?: boolean;
+	/** 是否为每个指令注入 `-h, --help` 选项 */
+	options?: boolean;
+}
+
+export const Config: Schema<Config> = Schema.object({
+	shortcut: Schema.boolean().default(true).description("是否启用快捷调用。"),
+	options: Schema.boolean()
+		.default(true)
+		.description("是否为每个指令添加 `-h, --help` 选项。"),
+});
+
+/** 在当前会话中转执行 help 指令（供 -h 选项与无 action 的指令复用） */
+function executeHelp(session: Session<never, never>, name: string) {
+	if (!session.app.$commander.get("help")) return;
+	return session.execute({
+		name: "help",
+		args: [name],
+	});
+}
+
+export const name = "help";
+
+export function apply(ctx: Context, config: Config) {
+	ctx.i18n.define("zh-CN", zhCN);
+	ctx.i18n.define("en-US", enUS);
+
+	// 为指令注入隐藏的 -h, --help 选项（不展示、不计入用法）
+	function enableHelp(command: Command) {
+		command[Context.current] = ctx;
+		command.option("help", "-h", {
+			hidden: true,
+			// @ts-expect-error
+			notUsage: true,
+			descPath: "commands.help.options.help",
+		});
+	}
+
+	ctx.schema.extend(
+		"command",
+		Schema.object({
+			hideOptions: Schema.boolean()
+				.description("是否隐藏所有选项。")
+				.default(false)
+				.hidden(),
+			hidden: Schema.computed(Schema.boolean())
+				.description("在帮助菜单中隐藏指令。")
+				.default(false),
+			params: Schema.any().description("帮助信息的本地化参数。").hidden(),
+		}),
+		900,
+	);
+
+	ctx.schema.extend(
+		"command-option",
+		Schema.object({
+			hidden: Schema.computed(Schema.boolean())
+				.description("在帮助菜单中隐藏选项。")
+				.default(false),
+			params: Schema.any().description("帮助信息的本地化参数。").hidden(),
+		}),
+		900,
+	);
+
+	if (config.options !== false) {
+		// 已注册的指令立即注入，之后新增的指令通过事件注入
+		ctx.$commander._commandList.forEach(enableHelp);
+		ctx.on("command-added", enableHelp);
+	}
+
+	// 指令执行前的拦截：带 -h 或指令本身没有 action 时，转而输出帮助
+	ctx.before(
+		"command/execute",
+		(argv: Argv<never, never, unknown[], { help?: boolean }>) => {
+			const { command, options, session } = argv;
+			if (!command || !session || !options) return;
+			if (options["help"] && command._options["help"]) {
+				return executeHelp(session, command.name);
+			}
+
+			if (command["_actions"].length) return;
+			return executeHelp(session, command.name);
+		},
+	);
+
+	const $ = ctx.$commander;
+
+	/**
+	 * 按名称解析目标指令；未命中时再按 i18n 快捷调用匹配
+	 * @param target 用户输入的指令名或快捷调用文本
+	 * @returns 指令对象；仅有模糊命中时返回候选列表
+	 */
+	function findCommand(target: string, session: Session<never, never>) {
+		const command = $.resolve(target, session);
+		if (command?.ctx.filter(session)) return command;
+
+		// 指令名未命中：转为在各语言的指令快捷调用文本中检索
+		const data = ctx.i18n
+			.find("commands.(name).shortcuts.(variant)", target)
+			.map((item) => ({ ...item, command: $.resolve(item.data.name, session) }))
+			.filter((item) => item.command?.match(session));
+		const perfect = data.filter((item) => item.similarity === 1);
+		if (!perfect.length) return data;
+		return perfect[0]?.command;
+	}
+
+	// 字段收集器：help 指令自身只用 authority，
+	// 但被查询的目标指令可能声明了额外的 user / channel 观察字段
+	const createCollector =
+		<T extends "user" | "channel">(key: T): FieldCollector<T> =>
+		(argv, fields) => {
+			const { args, session } = argv;
+			const [target] = args ?? [];
+			if (!session) return;
+			// target 是消息中的指令名；FieldCollector 擦除后 args 为 unknown[]
+			const result = findCommand(target as string, session);
+			if (!Array.isArray(result)) {
+				if (result) {
+					session.collect(
+						key,
+						{ ...argv, command: result, args: [], options: { help: true } },
+						fields,
+					);
+				}
+				return;
+			}
+			for (const { command } of result) {
+				if (!command) continue;
+				session.collect(
+					key,
+					{ ...argv, command, args: [], options: { help: true } },
+					fields,
+				);
+			}
+		};
+
+	/** 推断用户输入对应的指令；仅有模糊命中时发起相似度建议（“您要找的是不是…”） */
+	async function inferCommand(target: string, session: Session) {
+		const result = findCommand(target, session);
+		if (!Array.isArray(result)) return result;
+
+		// 候选 = 当前会话可见的相似指令名 + 快捷调用命中的指令名
+		const expect = $.available(session).filter((name) => {
+			return name && session.app.i18n.compare(name, target);
+		});
+		for (const item of result) {
+			if (expect.includes(item.data.name)) continue;
+			expect.push(item.data.name);
+		}
+		const cache = new Map<string, Promise<boolean>>();
+		const name = await session.suggest({
+			expect,
+			prefix: session.text(".not-found"),
+			suffix: session.text("internal.suggest-command"),
+			filter: (name) => {
+				const command = $.resolve(name, session);
+				if (!command) return false;
+				return ctx.permissions.test(`command:${command.name}`, session, cache);
+			},
+		});
+		if (!name) return;
+		return $.resolve(name, session);
+	}
+
+	// 主指令：无参数时列出全局指令清单，带参数时输出目标指令的详细帮助
+	const cmd = ctx
+		.command("help [command:string]", { authority: 0, ...config })
+		.userFields(["authority"])
+		.userFields(createCollector("user"))
+		.channelFields(createCollector("channel"))
+		.option("showHidden", "-H")
+		.action(async ({ session, options }, target) => {
+			if (!session || !options) return;
+			if (!target) {
+				const prefix =
+					session.resolve(session.app.koishi.config.prefix)?.[0] ?? "";
+				const commands = $._commandList.filter((cmd) => cmd.parent === null);
+				const output = await formatCommands(
+					".global-prolog",
+					session,
+					commands,
+					options as HelpOptions,
+				);
+				const epilog = session.text(".global-epilog", [prefix]);
+				if (epilog) output.push(epilog);
+				return output.filter(Boolean).join("\n");
+			}
+
+			const command = await inferCommand(target, session);
+			if (!command) return;
+			if (!(await ctx.permissions.test(`command:${command.name}`, session))) {
+				return session.text("internal.low-authority");
+			}
+			return showHelp(command, session, options as HelpOptions);
+		});
+
+	// 注册全局快捷调用“帮助”（具体文本由各语言的 i18n 文本提供）
+	if (config.shortcut !== false)
+		cmd.shortcut("help", { i18n: true, fuzzy: true });
+}
+
+/** 深度优先遍历指令树，产出当前会话可见（未被 hidden 过滤）的指令 */
+function* getCommands(
+	session: Session<"authority">,
+	commands: Command[],
+	showHidden = false,
+): Generator<Command> {
+	for (const command of commands) {
+		if (!showHidden && session.resolve(command.config.hidden)) continue;
+		// 自身可用则产出，否则下钻子指令（子指令可能单独可用）
+		if (command.match(session) && Object.keys(command._aliases).length) {
+			yield command;
+		} else {
+			yield* getCommands(session, command.children, showHidden);
+		}
+	}
+}
+
+/** 将一组指令格式化为帮助列表（标题行 + 每条指令一行的缩进展示） */
+async function formatCommands(
+	path: string,
+	session: Session<"authority">,
+	children: Command[],
+	options: HelpOptions,
+) {
+	const cache = new Map<string, Promise<boolean>>();
+	// 第一步：按可见性过滤
+	children = Array.from(getCommands(session, children, options.showHidden));
+	// 第二步：按权限过滤（并行检测并缓存结果）
+	children = (
+		await Promise.all(
+			children.map(async (command) => {
+				return [
+					command,
+					await session.app.permissions.test(
+						`command:${command.name}`,
+						session,
+						cache,
+					),
+				] as const;
+			}),
+		)
+	)
+		.filter(([, result]) => result)
+		.map(([command]) => command);
+	// 第三步：按显示名排序
+	children.sort((a, b) => (a.displayName > b.displayName ? 1 : -1));
+	if (!children.length) return [];
+
+	const prefix = session.resolve(session.app.koishi.config.prefix)?.[0] ?? "";
+	const output = children.map(({ name, displayName, config }) => {
+		let output = `    ${prefix}${displayName.replace(/\./g, " ")}`;
+		output += `  ${session.text([`commands.${name}.description`, ""], config.params)}`;
+		return output;
+	});
+	const hints: string[] = [];
+	const hintText = hints.length
+		? session.text("general.paren", [hints.join(session.text("general.comma"))])
+		: "";
+	output.unshift(session.text(path, [hintText]));
+	return output;
+}
+
+/** 判断选项对当前会话是否可见（权限不足或被 hidden 标记隐藏时不可见） */
+function getOptionVisibility(
+	option: Argv.OptionConfig,
+	session: Session<"authority">,
+) {
+	if (session.user && (option.authority ?? 0) > session.user.authority) {
+		return false;
+	}
+	return !session.resolve(option.hidden);
+}
+
+/** 生成指令的选项帮助段落（考虑 hideOptions、权限与 hidden 过滤） */
+function getOptions(
+	command: Command,
+	session: Session<"authority">,
+	config: HelpOptions,
+) {
+	if (command.config.hideOptions && !config.showHidden) return [];
+	const options = config.showHidden
+		? Object.values(command._options)
+		: Object.values(command._options).filter((option) =>
+				getOptionVisibility(option, session),
+			);
+	if (!options.length) return [];
+
+	const output: string[] = [];
+	Object.values(command._options).forEach((option) => {
+		function pushOption(option: Argv.OptionVariant, name: string) {
+			if (!config.showHidden && !getOptionVisibility(option, session)) return;
+			let line = `${h.escape(option.syntax)}`;
+			const description = session.text(
+				option.descPath ?? [`commands.${command.name}.options.${name}`, ""],
+				option.params,
+			);
+			if (description) line += `  ${description}`;
+			line = command.ctx.chain("help/option", line, option, command, session);
+			output.push(`    ${line}`);
+		}
+
+		// 无值选项直接输出；带值选项再逐个输出其语法变体
+		if (!("value" in option)) pushOption(option, option.name ?? "");
+		for (const value in option.variants) {
+			const variant = option.variants[value];
+			if (!variant) continue;
+			pushOption(variant, `${option.name}.${value}`);
+		}
+	});
+
+	if (!output.length) return [];
+	output.unshift(session.text(".available-options"));
+	return output;
+}
+
+/** 生成单个指令的完整帮助文本（标题、描述、别名、用法、选项、示例、子指令） */
+async function showHelp(
+	command: Command,
+	session: Session<"authority">,
+	config: HelpOptions,
+) {
+	const output = [
+		session.text(".command-title", [
+			command.displayName.replace(/\./g, " ") + command.declaration,
+		]),
+	];
+
+	const description = session.text(
+		[`commands.${command.name}.description`, ""],
+		command.config.params,
+	);
+	if (description) output.push(description);
+
+	// 有数据库时按目标指令的声明预取 user / channel 字段（usage 等钩子可能用到）
+	if (session.app.database) {
+		const argv: Argv = { command, args: [], options: { help: true } };
+		const userFields = session.collect("user", argv);
+		await session.observeUser(userFields);
+		if (!session.isDirect) {
+			const channelFields = session.collect("channel", argv);
+			await session.observeChannel(channelFields);
+		}
+	}
+
+	if (Object.keys(command._aliases).length > 1) {
+		output.push(
+			session.text(".command-aliases", [
+				Array.from(Object.keys(command._aliases).slice(1)).join("，"),
+			]),
+		);
+	}
+
+	session.app.emit(session, "help/command", output, command, session);
+
+	if (command._usage) {
+		output.push(
+			typeof command._usage === "string"
+				? command._usage
+				: // _usage 存储为擦除签名（见 core 的 CommandDefinition），此处还原实参
+					await command._usage(session as never),
+		);
+	} else {
+		const text = session.text(
+			[`commands.${command.name}.usage`, ""],
+			command.config.params,
+		);
+		if (text) output.push(text);
+	}
+
+	output.push(...getOptions(command, session, config));
+
+	if (command._examples.length) {
+		output.push(
+			session.text(".command-examples"),
+			...command._examples.map((example) => `    ${example}`),
+		);
+	} else {
+		const text = session.text(
+			[`commands.${command.name}.examples`, ""],
+			command.config.params,
+		);
+		if (text)
+			output.push(
+				session.text(".command-examples"),
+				...text.split("\n").map((line) => `    ${line}`),
+			);
+	}
+
+	output.push(
+		...(await formatCommands(
+			".subcommand-prolog",
+			session,
+			command.children,
+			config,
+		)),
+	);
+
+	return output.filter(Boolean).join("\n");
+}