0
# Koishi Help Plugin
1

2
The `@koishijs/plugin-help` is a comprehensive help system plugin for the Koishi chatbot framework. It provides automatic help generation for commands, interactive command assistance with fuzzy matching, and multi-language support. The plugin automatically adds help options to all commands, enables help command discovery with intelligent suggestions, and formats command documentation with proper permission filtering.
3

4
## Package Information
5

6
- **Package Name**: @koishijs/plugin-help
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @koishijs/plugin-help`
10
- **Peer Dependencies**: `koishi ^4.18.7`
11

12
## Core Imports
13

14
```typescript
15
import * as help from '@koishijs/plugin-help';
16
```
17

18
CommonJS:
19

20
```javascript
21
const help = require('@koishijs/plugin-help');
22
```
23

24
Named imports:
25

26
```typescript
27
import { name, apply, Config } from '@koishijs/plugin-help';
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { App } from 'koishi';
34
import * as help from '@koishijs/plugin-help';
35

36
const app = new App();
37

38
// Apply the help plugin with default configuration
39
app.plugin(help);
40

41
// Apply with custom configuration
42
app.plugin(help, {
43
  shortcut: true,  // Enable "help" shortcut (default: true)
44
  options: true    // Add -h, --help options to commands (default: true)
45
});
46

47
await app.start();
48
```
49

50
## Architecture
51

52
The help plugin is built around several key components:
53

54
- **Plugin Application**: Main `apply` function that registers the help system
55
- **Command Registration**: Automatic help option injection for all commands
56
- **Help Command**: Core `help [command]` command with fuzzy matching
57
- **Formatting System**: Comprehensive help text generation with permission filtering
58
- **Localization**: Multi-language support with extensible locale system
59
- **Event System**: Hook-based architecture for customizing help output
60

61
## Capabilities
62

63
### Plugin Configuration
64

65
Configuration interface and schema for customizing help plugin behavior.
66

67
```typescript { .api }
68
interface Config {
69
  /** Enable shortcut invocation (default: true) */
70
  shortcut?: boolean;
71
  /** Add -h, --help options to commands (default: true) */
72
  options?: boolean;
73
}
74

75
const Config: Schema<Config>;
76
```
77

78
### Plugin Application
79

80
Main plugin application function that registers the help system with Koishi.
81

82
```typescript { .api }
83
/**
84
 * Main plugin application function that registers the help system
85
 * @param ctx - Koishi context
86
 * @param config - Plugin configuration
87
 */
88
function apply(ctx: Context, config: Config): void;
89
```
90

91
### Plugin Identifier
92

93
Plugin name constant used for identification.
94

95
```typescript { .api }
96
const name: string; // Value: 'help'
97
```
98

99
### Command Extension Types
100

101
TypeScript module augmentations that extend Koishi's command system with help-specific properties.
102

103
**Command Configuration Extension:**
104

105
```typescript { .api }
106
namespace Command {
107
  interface Config {
108
    /** Hide all options by default */
109
    hideOptions?: boolean;
110
    /** Hide command from help display */
111
    hidden?: Computed<boolean>;
112
    /** Localization parameters for help text */
113
    params?: object;
114
  }
115
}
116
```
117

118
**Option Configuration Extension:**
119

120
```typescript { .api }
121
namespace Argv {
122
  interface OptionConfig {
123
    /** Hide option from help display */
124
    hidden?: Computed<boolean>;
125
    /** Localization parameters for help text */
126
    params?: object;
127
  }
128
}
129
```
130

131
### Help Command Registration
132

133
The plugin automatically registers a help command when applied.
134

135
```typescript { .api }
136
/**
137
 * Help command automatically registered by the plugin
138
 * Usage: help [command:string]
139
 * Options:
140
 *   -H, --show-hidden  Show hidden commands and options
141
 * 
142
 * The command also supports:
143
 * - Shortcut invocation with fuzzy matching (configurable via shortcut option)
144
 * - Automatic help options (-h, --help) added to all commands (configurable via options)
145
 * - Command suggestion on typos with fuzzy matching
146
 */
147
```
148

149
### Event System Extensions
150

151
Custom events fired during help generation for extensibility.
152

153
```typescript { .api }
154
interface Events {
155
  /** Fired when generating command help output */
156
  'help/command'(
157
    output: string[],
158
    command: Command,
159
    session: Session<never, never>
160
  ): void;
161
  
162
  /** Fired when formatting option help text */
163
  'help/option'(
164
    output: string,
165
    option: Argv.OptionVariant,
166
    command: Command,
167
    session: Session<never, never>
168
  ): string;
169
}
170
```
171

172
## Usage Examples
173

174
### Basic Help System Setup
175

176
```typescript
177
import { App } from 'koishi';
178
import * as help from '@koishijs/plugin-help';
179

180
const app = new App();
181
app.plugin(help);
182

183
// The plugin automatically adds help functionality:
184
// - "help" command lists all available commands
185
// - "help <command>" shows detailed help for specific commands
186
// - All commands get -h, --help options automatically
187
// - Fuzzy matching suggests commands on typos
188
await app.start();
189
```
190

191
### Custom Configuration
192

193
```typescript
194
import { App } from 'koishi';
195
import * as help from '@koishijs/plugin-help';
196

197
const app = new App();
198

199
// Disable automatic help options on commands
200
app.plugin(help, { options: false });
201

202
// Disable help shortcut functionality
203
app.plugin(help, { shortcut: false });
204

205
await app.start();
206
```
207

208
### Command-Specific Help Configuration
209

210
```typescript
211
import { App } from 'koishi';
212
import * as help from '@koishijs/plugin-help';
213

214
const app = new App();
215
app.plugin(help);
216

217
// Create command with custom help configuration
218
app.command('mycommand', 'My command description', {
219
  hideOptions: true,  // Hide all options from help
220
  hidden: false,      // Show command in help listings
221
  params: { customParam: 'value' }  // Custom localization params
222
})
223
  .option('verbose', '-v', 'Enable verbose output', {
224
    hidden: true,  // Hide this specific option from help
225
    params: { level: 'debug' }
226
  })
227
  .action(({ options }) => {
228
    // Command implementation
229
  });
230
```
231

232
### Custom Help Event Handlers
233

234
```typescript
235
import { App } from 'koishi';
236
import * as help from '@koishijs/plugin-help';
237

238
const app = new App();
239
app.plugin(help);
240

241
// Customize command help output
242
app.on('help/command', (output, command, session) => {
243
  if (command.name === 'special') {
244
    output.push('⭐ This is a special command!');
245
  }
246
});
247

248
// Customize option formatting
249
app.on('help/option', (output, option, command, session) => {
250
  if (option.name === 'experimental') {
251
    return output + ' (⚠️ Experimental feature)';
252
  }
253
  return output;
254
});
255
```
256

257
### Multi-language Support
258

259
```typescript
260
import { App } from 'koishi';
261
import * as help from '@koishijs/plugin-help';
262

263
const app = new App();
264
app.plugin(help);
265

266
// The plugin automatically supports multiple locales:
267
// - zh-CN (Simplified Chinese)
268
// - en-US (English)  
269
// - ja-JP (Japanese)
270
// - fr-FR (French)
271
// - zh-TW (Traditional Chinese)
272
// - de-DE (German)
273
// - ru-RU (Russian)
274

275
// Help text will be displayed in the user's preferred language
276
await app.start();
277
```
278

279
## Types
280

281
```typescript { .api }
282
interface HelpOptions {
283
  /** Show hidden commands and options */
284
  showHidden?: boolean;
285
}
286

287
interface Config {
288
  /** Enable shortcut invocation (default: true) */
289
  shortcut?: boolean;
290
  /** Add -h, --help options to commands (default: true) */
291
  options?: boolean;
292
}
293

294
// Koishi framework types used by the plugin
295
type Context = import('koishi').Context;
296
type Session = import('koishi').Session;
297
type Command = import('koishi').Command;
298
type Schema = import('koishi').Schema;
299
type Computed<T> = import('koishi').Computed<T>;
300
```