@koishi-ce/plugin-help 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,120 @@
+# @koishi-ce/plugin-help
+
+**简体中文** | [English](#english)
+
+帮助指令插件，移植自上游 [koishijs/koishi](https://github.com/koishijs/koishi) 的 `plugins/common/help`。列出当前可用的指令清单，或输出某条指令的详细帮助（描述、别名、用法、选项、示例与子指令），并按权限与隐藏标记过滤展示内容。
+
+## 指令
+
+| 指令 | 权限 | 说明 |
+| --- | --- | --- |
+| `help [command:string]` | 0 | 显示帮助信息，选项 `-H, --showHidden` 查看隐藏的选项和指令 |
+
+- 不带参数时列出当前可用的全部指令（按显示名排序），带参数时输出目标指令的详细帮助。
+- 注册全局快捷调用「帮助」（fuzzy 匹配）。
+- 指令参数除指令名外，也可以直接输入某条指令的快捷调用文本来定位指令。
+- 未找到指令时，按相似度给出「您要找的是不是…」建议。
+
+## 配置项
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `shortcut` | boolean | `true` | 是否启用快捷调用 |
+| `options` | boolean | `true` | 是否为每个指令添加 `-h, --help` 选项 |
+
+### 指令与选项配置扩展
+
+本插件经 `ctx.schema.extend` 为每条指令及指令选项追加以下配置（出现在各指令的配置中，而非本插件的配置）：
+
+| 位置 | 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| 指令 | `hidden` | 计算属性 boolean | `false` | 在帮助菜单中隐藏指令 |
+| 指令 | `hideOptions` | boolean | `false` | 是否隐藏所有选项 |
+| 指令 | `params` | any | — | 帮助信息的本地化参数 |
+| 选项 | `hidden` | 计算属性 boolean | `false` | 在帮助菜单中隐藏选项 |
+| 选项 | `params` | any | — | 帮助信息的本地化参数 |
+
+## 用法
+
+```bash
+bun add @koishi-ce/plugin-help
+```
+
+也可以在控制台的插件市场中直接安装。随后在配置文件中启用：
+
+```yaml
+plugins:
+  help: {}
+```
+
+## 备注
+
+- 为所有指令注入隐藏的 `-h, --help` 选项；带 `-h` 调用、或调用本身没有 action 的指令时，自动转而输出该指令的帮助。
+- 详细帮助依次输出：指令标题、描述、别名、用法、可用选项、使用示例与子指令列表。
+- 选项的权限要求高于当前用户、或被 `hidden` 标记隐藏时不展示，`-H` 可查看。
+- 指令列表与详情均按 `command:<name>` 权限过滤，无权限的指令不展示。
+- 提供 `help/command` 与 `help/option` 事件，供其他插件改写帮助输出。
+
+## 许可证
+
+[MIT](https://github.com/Koishi-CE/koishi/blob/main/LICENSE)。本包是上游 [koishijs/koishi](https://github.com/koishijs/koishi) 的社区再分发，版权归属见 [NOTICE](https://github.com/Koishi-CE/koishi/blob/main/NOTICE)。
+
+---
+
+## English
+
+A help command plugin, ported from `plugins/common/help` of the upstream [koishijs/koishi](https://github.com/koishijs/koishi) repository. It lists the available commands, or shows detailed help for a specific command (description, aliases, usage, options, examples and subcommands), filtered by authority and hidden flags.
+
+## Commands
+
+| Command | Authority | Description |
+| --- | --- | --- |
+| `help [command:string]` | 0 | Show help; the `-H, --showHidden` option reveals hidden options and commands |
+
+- Without arguments it lists all available commands; with an argument it shows detailed help for the target command.
+- Registers the global shortcut "帮助" (Chinese, fuzzy matching).
+- Besides command names, the argument also accepts a command's shortcut text to locate it.
+- When a command is not found, it suggests similar ones.
+
+## Configuration
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `shortcut` | boolean | `true` | Whether to enable the shortcut |
+| `options` | boolean | `true` | Whether to add a `-h, --help` option to every command |
+
+### Command and Option Config Extensions
+
+Via `ctx.schema.extend`, the following fields are appended to every command and option config (on each command, not on this plugin):
+
+| Scope | Field | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| Command | `hidden` | computed boolean | `false` | Hide the command from help menus |
+| Command | `hideOptions` | boolean | `false` | Hide all options |
+| Command | `params` | any | — | Localization params for help output |
+| Option | `hidden` | computed boolean | `false` | Hide the option from help menus |
+| Option | `params` | any | — | Localization params for help output |
+
+## Usage
+
+```bash
+bun add @koishi-ce/plugin-help
+```
+
+The plugin can also be installed from the console plugin market, then enabled in the config file:
+
+```yaml
+plugins:
+  help: {}
+```
+
+## Notes
+
+- Injects a hidden `-h, --help` option into every command; calling with `-h`, or calling a command without an action, shows its help instead.
+- Options whose authority exceeds the user or marked as `hidden` are not shown unless `-H` is used.
+- Command lists and details are filtered by the `command:<name>` permission.
+- Provides `help/command` and `help/option` events for other plugins to customize the output.
+
+## License
+
+[MIT](https://github.com/Koishi-CE/koishi/blob/main/LICENSE). This package is a community redistribution of upstream koishijs/koishi; see [NOTICE](https://github.com/Koishi-CE/koishi/blob/main/NOTICE) for attribution.

package/lib/assets/{en-US-f1RJaaO6.yml → en-US-DRtqxx3I.yml}

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-present Shigma and Koishijs contributors.
+
 commands:
   help:
     description: Show help

package/lib/assets/{zh-CN-DmsdBxOO.yml → zh-CN-DCysH3jk.yml}

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-present Shigma and Koishijs contributors.
+
 commands:
   help:
     description: 显示帮助信息

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import { Command, Computed, Context, Schema, Session } from "@koishi-ce/koishi";
+import { Computed, Context, Schema, Session } from "@koishi-ce/koishi";
 //#region src/index.d.ts
 declare module "@koishi-ce/koishi" {
   interface Events {
@@ -25,14 +25,13 @@ declare module "@koishi-ce/koishi" {
   }
 }
 /** 配置项 */
-interface Config {
+export 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 };
+export declare const Config: Schema<Config>;
+export declare const name = "help";
+export declare function apply(ctx: Context, config: Config): void;
+//#endregion

package/lib/index.mjs

@@ -1,6 +1,6 @@
 import { Context, Schema, h } from "@koishi-ce/koishi";
-import enUS from "./assets/en-US-f1RJaaO6.yml";
-import zhCN from "./assets/zh-CN-DmsdBxOO.yml";
+import enUS from "./assets/en-US-DRtqxx3I.yml";
+import zhCN from "./assets/zh-CN-DCysH3jk.yml";
 //#region src/index.ts
 /**
 * 帮助指令插件（help）。

package/locales/de-DE.yml

@@ -1,22 +1,25 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-present Shigma and Koishijs contributors.
+
 commands:
   help:
-    description: 显示帮助信息
+    description: Hilfe anzeigen
     shortcuts:
       help: Hilfe
     options:
-      help: 显示此信息
-      authority: 显示权限设置
-      showHidden: 查看隐藏的选项和指令
+      help: Diese Meldung anzeigen
+      authority: Berechtigungsanforderungen anzeigen
+      showHidden: Versteckte Optionen und Befehle anzeigen
     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: 可用的选项有（括号内为额外要求的权限等级）：
+      not-found: Befehl nicht gefunden.
+      hint-authority: die minimale Berechtigung ist in Klammern angegeben
+      hint-subcommand: mit einem Sternchen markierte Befehle besitzen Unterbefehle
+      command-title: 'Befehl: {0}'
+      command-aliases: 'Aliase: {0}.'
+      command-examples: 'Beispiele:'
+      command-authority: 'Minimale Berechtigung: {0}.'
+      subcommand-prolog: 'Verfügbare Unterbefehle{0}:'
+      global-prolog: 'Verfügbare Befehle{0}:'
+      global-epilog: Geben Sie „{0}help <Befehl>“ ein, um Syntax und Beispiele für einen bestimmten Befehl anzuzeigen.
+      available-options: 'Verfügbare Optionen:'
+      available-options-with-authority: 'Verfügbare Optionen (in Klammern angegebene zusätzlich erforderliche Berechtigung):'

package/locales/en-US.yml

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-present Shigma and Koishijs contributors.
+
 commands:
   help:
     description: Show help

package/locales/fr-FR.yml

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-present Shigma and Koishijs contributors.
+
 commands:
   help:
     description: Afficher l'aide

package/locales/ja-JP.yml

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-present Shigma and Koishijs contributors.
+
 commands:
   help:
     description: ヘルプを表示

package/locales/ru-RU.yml

@@ -1,22 +1,25 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-present Shigma and Koishijs contributors.
+
 commands:
   help:
-    description: 显示帮助信息
+    description: Показать справку
     shortcuts:
       help: Справка
     options:
-      help: 显示此信息
-      authority: 显示权限设置
-      showHidden: 查看隐藏的选项和指令
+      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: 可用的选项有（括号内为额外要求的权限等级）：
+      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

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-present Shigma and Koishijs contributors.
+
 commands:
   help:
     description: 显示帮助信息

package/locales/zh-TW.yml

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-present Shigma and Koishijs contributors.
+
 commands:
   help:
     description: 顯示幫助信息

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@koishi-ce/plugin-help",
     "description": "Help plugin for Koishi",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "type": "module",
     "main": "lib/index.mjs",
     "typings": "lib/index.d.ts",
@@ -47,13 +47,12 @@
         ]
     },
     "peerDependencies": {
-        "koishi": "^4.18.11"
+        "@koishi-ce/koishi": "^1.0.0"
     },
     "devDependencies": {
+        "@koishi-ce/koishi": "^1.0.8",
         "@koishi-ce/plugin-mock": "^1.0.0",
-        "@minatojs/driver-memory": "^3.7.0",
-        "@koishi-ce/koishi": "^1.0.0",
-        "minato": "^3.7.0"
+        "@koishijs/plugin-database-memory": "^3.7.0"
     },
     "exports": {
         ".": {

package/src/extra.test.ts

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+/**
+ * help 插件补充用例（bun:test 断言）：
+ * 父指令对当前会话不可见时下钻子指令（getCommands else 分支）、
+ * 选项权限不足时从帮助中隐藏、i18n 定义的示例文本逐行展示、
+ * 以及快捷调用的模糊命中给出的纠错建议（候选字段收集循环）。
+ *
+ * 备注：inferCommand 里 session.suggest 的 filter 回调（index.ts 223-225）
+ * 经 help 插件路径不可达——suggest 仅在传入 actual 时才调用 filter，
+ * 而 help 的 suggest 调用不传 actual（见 core/src/session/interact.ts）。
+ */
+import { beforeAll, describe, expect, 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 * as memoryModule from "@koishijs/plugin-database-memory";
+
+// CJS 实现配 ESM 声明，Bun 互操作视图多包一层 default，穿透取真实驱动
+const memory =
+	memoryModule.default as unknown as typeof memoryModule.default.default;
+
+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",
+	"",
+);
+
+const client = app.mock.client("123", "456");
+
+beforeAll(async () => {
+	await app.start();
+	await app.mock.initUser("123", 2);
+	await app.mock.initChannel("456");
+});
+
+describe("@koishi-ce/plugin-help 补充用例", () => {
+	it("父指令对当前会话不可见时不进入全局列表", async () => {
+		// 限定 telegram 平台的指令对 mock 会话 match 失败，全局列表不展示
+		const parent = app
+			.platform("telegram")
+			.command("tg", "T");
+		parent.subcommand("tgc", "C");
+		const [reply] = await client.receive("help");
+		expect(reply).toContain("help");
+		expect(reply).not.toContain("tg");
+	});
+
+	it("选项权限不足时从帮助中隐藏", async () => {
+		app
+			.command("adv", "D")
+			.option("top", "-t", { authority: 3 });
+		const [reply] = await client.receive("help adv");
+		expect(reply).toBe("指令：adv\nD");
+	});
+
+	it("i18n 定义的示例文本逐行展示", async () => {
+		app.command("demo", "D");
+		app.i18n.define(
+			"$zh-CN",
+			"commands.demo.examples",
+			"first\nsecond",
+		);
+		const [reply] = await client.receive("help demo");
+		expect(reply).toBe(
+			"指令：demo\nD\n使用示例：\n    first\n    second",
+		);
+	});
+
+	it("快捷调用的模糊命中给出纠错建议", async () => {
+		const probe = app.command("probe", "DESCRIPTION");
+		probe.shortcut("ask", { i18n: true });
+		app.i18n.define(
+			"$zh-CN",
+			"commands.probe.shortcuts.ask",
+			"quickbrownfox",
+		);
+		// 与快捷调用文本相差一字母：非精确命中，走候选列表与建议流程
+		await client.shouldReply(
+			"help quickbrownfo",
+			"指令未找到。您要找的是不是“probe”？回复句号以使用推测的指令。",
+		);
+		// 回复句号确认后展示推测指令的帮助
+		await client.shouldReply(
+			".",
+			"指令：probe\nDESCRIPTION",
+		);
+	});
+});

package/src/index.test.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026-present Koishi-CE contributors.
+
 /**
  * help 插件测试：覆盖帮助列表、指令属性（别名 / 用法 / 示例 / 权限）、
  * 选项展示、子指令、无数据库场景与 shortcut / options 配置开关。
@@ -6,7 +9,11 @@ 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";
+import * as memoryModule from "@koishijs/plugin-database-memory";
+
+// CJS 实现配 ESM 声明，Bun 互操作视图多包一层 default，穿透取真实驱动
+const memory =
+	memoryModule.default as unknown as typeof memoryModule.default.default;
 
 const app = new App({
 	minSimilarity: 0.64,
@@ -16,7 +23,11 @@ app.plugin(mock);
 app.plugin(help);
 app.plugin(memory);
 
-app.i18n.define("$zh-CN", "commands.help.messages.global-epilog", "EPILOG");
+app.i18n.define(
+	"$zh-CN",
+	"commands.help.messages.global-epilog",
+	"EPILOG",
+);
 
 const client = app.mock.client("123", "456");
 
@@ -68,20 +79,30 @@ describe("@koishi-ce/plugin-help", () => {
 		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("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 foobar",
+			"指令：foo3\nDESCRIPTION",
+		);
 		await client.shouldReply(
 			"help foo4",
 			"指令：foo4\nDESCRIPTION\nUSAGE TEXT",
 		);
-		await client.shouldReply("help foo5", "指令：foo5\nDESCRIPTION\n123");
+		await client.shouldReply(
+			"help foo5",
+			"指令：foo5\nDESCRIPTION\n123",
+		);
 		await client.shouldReply(
 			"help foo6",
 			"指令：foo6\nDESCRIPTION\n使用示例：\n    EXAMPLE TEXT",
@@ -92,7 +113,9 @@ describe("@koishi-ce/plugin-help", () => {
 	// 验证 hideOptions、选项权限与 hidden 选项的过滤，以及 -H 的全量展示
 	it("command options", async () => {
 		const bar = app
-			.command("bar <arg:number>", "DESCRIPTION", { hideOptions: true })
+			.command("bar <arg:number>", "DESCRIPTION", {
+				hideOptions: true,
+			})
 			.option("opt1", "选项1", { authority: 2 })
 			.option("opt1", "-n  选项2", { value: false })
 			.option("opt2", "[arg:boolean]  选项3")
@@ -132,7 +155,9 @@ describe("@koishi-ce/plugin-help", () => {
 
 	// 验证多级子指令在父指令帮助中的逐层呈现
 	it("subcommand", async () => {
-		const foo2 = app.command("foo2", "DESCRIPTION", { authority: 0 });
+		const foo2 = app.command("foo2", "DESCRIPTION", {
+			authority: 0,
+		});
 		const foo1 = foo2.subcommand("foo1");
 		foo1.subcommand("foo3");
 
@@ -163,7 +188,11 @@ describe("@koishi-ce/plugin-help", () => {
 		const app = new App();
 		app.plugin(help);
 		app.plugin(mock);
-		app.i18n.define("$zh-CN", "commands.help.messages.global-epilog", "");
+		app.i18n.define(
+			"$zh-CN",
+			"commands.help.messages.global-epilog",
+			"",
+		);
 		await app.start();
 
 		const client = app.mock.client("123");
@@ -203,7 +232,9 @@ describe("@koishi-ce/plugin-help", () => {
 		const app = new App();
 		app.plugin(help);
 		app.plugin(mock);
-		app.command("test <arg>", { checkArgCount: true }).action(() => "pass");
+		app
+			.command("test <arg>", { checkArgCount: true })
+			.action(() => "pass");
 		await app.start();
 
 		const client = app.mock.client("123");

package/src/index.ts

@@ -1,3 +1,7 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
 /**
  * 帮助指令插件（help）。
  *
@@ -48,7 +52,9 @@ declare module "@koishi-ce/koishi" {
 	}
 
 	namespace Argv {
-		interface OptionConfig<T extends Argv.Type = Argv.Type> {
+		interface OptionConfig<
+			T extends Argv.Type = Argv.Type,
+		> {
 			/** 在帮助中隐藏此选项 */
 			hidden?: Computed<boolean>;
 			/** 本地化参数 */
@@ -72,14 +78,19 @@ export interface Config {
 }
 
 export const Config: Schema<Config> = Schema.object({
-	shortcut: Schema.boolean().default(true).description("是否启用快捷调用。"),
+	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) {
+function executeHelp(
+	session: Session<never, never>,
+	name: string,
+) {
 	if (!session.app.$commander.get("help")) return;
 	return session.execute({
 		name: "help",
@@ -114,7 +125,9 @@ export function apply(ctx: Context, config: Config) {
 			hidden: Schema.computed(Schema.boolean())
 				.description("在帮助菜单中隐藏指令。")
 				.default(false),
-			params: Schema.any().description("帮助信息的本地化参数。").hidden(),
+			params: Schema.any()
+				.description("帮助信息的本地化参数。")
+				.hidden(),
 		}),
 		900,
 	);
@@ -125,7 +138,9 @@ export function apply(ctx: Context, config: Config) {
 			hidden: Schema.computed(Schema.boolean())
 				.description("在帮助菜单中隐藏选项。")
 				.default(false),
-			params: Schema.any().description("帮助信息的本地化参数。").hidden(),
+			params: Schema.any()
+				.description("帮助信息的本地化参数。")
+				.hidden(),
 		}),
 		900,
 	);
@@ -139,7 +154,14 @@ export function apply(ctx: Context, config: Config) {
 	// 指令执行前的拦截：带 -h 或指令本身没有 action 时，转而输出帮助
 	ctx.before(
 		"command/execute",
-		(argv: Argv<never, never, unknown[], { help?: boolean }>) => {
+		(
+			argv: Argv<
+				never,
+				never,
+				unknown[],
+				{ help?: boolean }
+			>,
+		) => {
 			const { command, options, session } = argv;
 			if (!command || !session || !options) return;
 			if (options["help"] && command._options["help"]) {
@@ -158,16 +180,24 @@ export function apply(ctx: Context, config: Config) {
 	 * @param target 用户输入的指令名或快捷调用文本
 	 * @returns 指令对象；仅有模糊命中时返回候选列表
 	 */
-	function findCommand(target: string, session: Session<never, never>) {
+	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) }))
+			.map((item) => ({
+				...item,
+				command: $.resolve(item.data.name, session),
+			}))
 			.filter((item) => item.command?.match(session));
-		const perfect = data.filter((item) => item.similarity === 1);
+		const perfect = data.filter(
+			(item) => item.similarity === 1,
+		);
 		if (!perfect.length) return data;
 		return perfect[0]?.command;
 	}
@@ -175,7 +205,9 @@ export function apply(ctx: Context, config: Config) {
 	// 字段收集器：help 指令自身只用 authority，
 	// 但被查询的目标指令可能声明了额外的 user / channel 观察字段
 	const createCollector =
-		<T extends "user" | "channel">(key: T): FieldCollector<T> =>
+		<T extends "user" | "channel">(
+			key: T,
+		): FieldCollector<T> =>
 		(argv, fields) => {
 			const { args, session } = argv;
 			const [target] = args ?? [];
@@ -186,7 +218,12 @@ export function apply(ctx: Context, config: Config) {
 				if (result) {
 					session.collect(
 						key,
-						{ ...argv, command: result, args: [], options: { help: true } },
+						{
+							...argv,
+							command: result,
+							args: [],
+							options: { help: true },
+						},
 						fields,
 					);
 				}
@@ -196,14 +233,22 @@ export function apply(ctx: Context, config: Config) {
 				if (!command) continue;
 				session.collect(
 					key,
-					{ ...argv, command, args: [], options: { help: true } },
+					{
+						...argv,
+						command,
+						args: [],
+						options: { help: true },
+					},
 					fields,
 				);
 			}
 		};
 
 	/** 推断用户输入对应的指令；仅有模糊命中时发起相似度建议（“您要找的是不是…”） */
-	async function inferCommand(target: string, session: Session) {
+	async function inferCommand(
+		target: string,
+		session: Session,
+	) {
 		const result = findCommand(target, session);
 		if (!Array.isArray(result)) return result;
 
@@ -223,7 +268,11 @@ export function apply(ctx: Context, config: Config) {
 			filter: (name) => {
 				const command = $.resolve(name, session);
 				if (!command) return false;
-				return ctx.permissions.test(`command:${command.name}`, session, cache);
+				return ctx.permissions.test(
+					`command:${command.name}`,
+					session,
+					cache,
+				);
 			},
 		});
 		if (!name) return;
@@ -232,7 +281,10 @@ export function apply(ctx: Context, config: Config) {
 
 	// 主指令：无参数时列出全局指令清单，带参数时输出目标指令的详细帮助
 	const cmd = ctx
-		.command("help [command:string]", { authority: 0, ...config })
+		.command("help [command:string]", {
+			authority: 0,
+			...config,
+		})
 		.userFields(["authority"])
 		.userFields(createCollector("user"))
 		.channelFields(createCollector("channel"))
@@ -241,25 +293,40 @@ export function apply(ctx: Context, config: Config) {
 			if (!session || !options) return;
 			if (!target) {
 				const prefix =
-					session.resolve(session.app.koishi.config.prefix)?.[0] ?? "";
-				const commands = $._commandList.filter((cmd) => cmd.parent === null);
+					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]);
+				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))) {
+			if (
+				!(await ctx.permissions.test(
+					`command:${command.name}`,
+					session,
+				))
+			) {
 				return session.text("internal.low-authority");
 			}
-			return showHelp(command, session, options as HelpOptions);
+			return showHelp(
+				command,
+				session,
+				options as HelpOptions,
+			);
 		});
 
 	// 注册全局快捷调用“帮助”（具体文本由各语言的 i18n 文本提供）
@@ -274,12 +341,23 @@ function* getCommands(
 	showHidden = false,
 ): Generator<Command> {
 	for (const command of commands) {
-		if (!showHidden && session.resolve(command.config.hidden)) continue;
+		if (
+			!showHidden &&
+			session.resolve(command.config.hidden)
+		)
+			continue;
 		// 自身可用则产出，否则下钻子指令（子指令可能单独可用）
-		if (command.match(session) && Object.keys(command._aliases).length) {
+		if (
+			command.match(session) &&
+			Object.keys(command._aliases).length
+		) {
 			yield command;
 		} else {
-			yield* getCommands(session, command.children, showHidden);
+			yield* getCommands(
+				session,
+				command.children,
+				showHidden,
+			);
 		}
 	}
 }
@@ -293,7 +371,9 @@ async function formatCommands(
 ) {
 	const cache = new Map<string, Promise<boolean>>();
 	// 第一步：按可见性过滤
-	children = Array.from(getCommands(session, children, options.showHidden));
+	children = Array.from(
+		getCommands(session, children, options.showHidden),
+	);
 	// 第二步：按权限过滤（并行检测并缓存结果）
 	children = (
 		await Promise.all(
@@ -312,18 +392,27 @@ async function formatCommands(
 		.filter(([, result]) => result)
 		.map(([command]) => command);
 	// 第三步：按显示名排序
-	children.sort((a, b) => (a.displayName > b.displayName ? 1 : -1));
+	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 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"))])
+		? session.text("general.paren", [
+				hints.join(session.text("general.comma")),
+			])
 		: "";
 	output.unshift(session.text(path, [hintText]));
 	return output;
@@ -334,7 +423,10 @@ function getOptionVisibility(
 	option: Argv.OptionConfig,
 	session: Session<"authority">,
 ) {
-	if (session.user && (option.authority ?? 0) > session.user.authority) {
+	if (
+		session.user &&
+		(option.authority ?? 0) > session.user.authority
+	) {
 		return false;
 	}
 	return !session.resolve(option.hidden);
@@ -346,7 +438,8 @@ function getOptions(
 	session: Session<"authority">,
 	config: HelpOptions,
 ) {
-	if (command.config.hideOptions && !config.showHidden) return [];
+	if (command.config.hideOptions && !config.showHidden)
+		return [];
 	const options = config.showHidden
 		? Object.values(command._options)
 		: Object.values(command._options).filter((option) =>
@@ -356,20 +449,37 @@ function getOptions(
 
 	const output: string[] = [];
 	Object.values(command._options).forEach((option) => {
-		function pushOption(option: Argv.OptionVariant, name: string) {
-			if (!config.showHidden && !getOptionVisibility(option, session)) return;
+		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.descPath ?? [
+					`commands.${command.name}.options.${name}`,
+					"",
+				],
 				option.params,
 			);
 			if (description) line += `  ${description}`;
-			line = command.ctx.chain("help/option", line, option, command, session);
+			line = command.ctx.chain(
+				"help/option",
+				line,
+				option,
+				command,
+				session,
+			);
 			output.push(`    ${line}`);
 		}
 
 		// 无值选项直接输出；带值选项再逐个输出其语法变体
-		if (!("value" in option)) pushOption(option, option.name ?? "");
+		if (!("value" in option))
+			pushOption(option, option.name ?? "");
 		for (const value in option.variants) {
 			const variant = option.variants[value];
 			if (!variant) continue;
@@ -390,7 +500,8 @@ async function showHelp(
 ) {
 	const output = [
 		session.text(".command-title", [
-			command.displayName.replace(/\./g, " ") + command.declaration,
+			command.displayName.replace(/\./g, " ") +
+				command.declaration,
 		]),
 	];
 
@@ -402,11 +513,18 @@ async function showHelp(
 
 	// 有数据库时按目标指令的声明预取 user / channel 字段（usage 等钩子可能用到）
 	if (session.app.database) {
-		const argv: Argv = { command, args: [], options: { help: true } };
+		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);
+			const channelFields = session.collect(
+				"channel",
+				argv,
+			);
 			await session.observeChannel(channelFields);
 		}
 	}
@@ -414,12 +532,20 @@ async function showHelp(
 	if (Object.keys(command._aliases).length > 1) {
 		output.push(
 			session.text(".command-aliases", [
-				Array.from(Object.keys(command._aliases).slice(1)).join("，"),
+				Array.from(
+					Object.keys(command._aliases).slice(1),
+				).join("，"),
 			]),
 		);
 	}
 
-	session.app.emit(session, "help/command", output, command, session);
+	session.app.emit(
+		session,
+		"help/command",
+		output,
+		command,
+		session,
+	);
 
 	if (command._usage) {
 		output.push(
@@ -441,7 +567,9 @@ async function showHelp(
 	if (command._examples.length) {
 		output.push(
 			session.text(".command-examples"),
-			...command._examples.map((example) => `    ${example}`),
+			...command._examples.map(
+				(example) => `    ${example}`,
+			),
 		);
 	} else {
 		const text = session.text(