CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-koishijs--plugin-help

Help plugin for Koishi chatbot framework providing comprehensive command assistance and documentation generation

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Koishi Help Plugin

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.

Package Information

  • Package Name: @koishijs/plugin-help
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @koishijs/plugin-help
  • Peer Dependencies: koishi ^4.18.7

Core Imports

import * as help from '@koishijs/plugin-help';

CommonJS:

const help = require('@koishijs/plugin-help');

Named imports:

import { name, apply, Config } from '@koishijs/plugin-help';

Basic Usage

import { App } from 'koishi';
import * as help from '@koishijs/plugin-help';

const app = new App();

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

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

await app.start();

Architecture

The help plugin is built around several key components:

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

Capabilities

Plugin Configuration

Configuration interface and schema for customizing help plugin behavior.

interface Config {
  /** Enable shortcut invocation (default: true) */
  shortcut?: boolean;
  /** Add -h, --help options to commands (default: true) */
  options?: boolean;
}

const Config: Schema<Config>;

Plugin Application

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

/**
 * Main plugin application function that registers the help system
 * @param ctx - Koishi context
 * @param config - Plugin configuration
 */
function apply(ctx: Context, config: Config): void;

Plugin Identifier

Plugin name constant used for identification.

const name: string; // Value: 'help'

Command Extension Types

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

Command Configuration Extension:

namespace Command {
  interface Config {
    /** Hide all options by default */
    hideOptions?: boolean;
    /** Hide command from help display */
    hidden?: Computed<boolean>;
    /** Localization parameters for help text */
    params?: object;
  }
}

Option Configuration Extension:

namespace Argv {
  interface OptionConfig {
    /** Hide option from help display */
    hidden?: Computed<boolean>;
    /** Localization parameters for help text */
    params?: object;
  }
}

Help Command Registration

The plugin automatically registers a help command when applied.

/**
 * Help command automatically registered by the plugin
 * Usage: help [command:string]
 * Options:
 *   -H, --show-hidden  Show hidden commands and options
 * 
 * The command also supports:
 * - Shortcut invocation with fuzzy matching (configurable via shortcut option)
 * - Automatic help options (-h, --help) added to all commands (configurable via options)
 * - Command suggestion on typos with fuzzy matching
 */

Event System Extensions

Custom events fired during help generation for extensibility.

interface Events {
  /** Fired when generating command help output */
  'help/command'(
    output: string[],
    command: Command,
    session: Session<never, never>
  ): void;
  
  /** Fired when formatting option help text */
  'help/option'(
    output: string,
    option: Argv.OptionVariant,
    command: Command,
    session: Session<never, never>
  ): string;
}

Usage Examples

Basic Help System Setup

import { App } from 'koishi';
import * as help from '@koishijs/plugin-help';

const app = new App();
app.plugin(help);

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

Custom Configuration

import { App } from 'koishi';
import * as help from '@koishijs/plugin-help';

const app = new App();

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

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

await app.start();

Command-Specific Help Configuration

import { App } from 'koishi';
import * as help from '@koishijs/plugin-help';

const app = new App();
app.plugin(help);

// Create command with custom help configuration
app.command('mycommand', 'My command description', {
  hideOptions: true,  // Hide all options from help
  hidden: false,      // Show command in help listings
  params: { customParam: 'value' }  // Custom localization params
})
  .option('verbose', '-v', 'Enable verbose output', {
    hidden: true,  // Hide this specific option from help
    params: { level: 'debug' }
  })
  .action(({ options }) => {
    // Command implementation
  });

Custom Help Event Handlers

import { App } from 'koishi';
import * as help from '@koishijs/plugin-help';

const app = new App();
app.plugin(help);

// Customize command help output
app.on('help/command', (output, command, session) => {
  if (command.name === 'special') {
    output.push('⭐ This is a special command!');
  }
});

// Customize option formatting
app.on('help/option', (output, option, command, session) => {
  if (option.name === 'experimental') {
    return output + ' (⚠️ Experimental feature)';
  }
  return output;
});

Multi-language Support

import { App } from 'koishi';
import * as help from '@koishijs/plugin-help';

const app = new App();
app.plugin(help);

// The plugin automatically supports multiple locales:
// - zh-CN (Simplified Chinese)
// - en-US (English)  
// - ja-JP (Japanese)
// - fr-FR (French)
// - zh-TW (Traditional Chinese)
// - de-DE (German)
// - ru-RU (Russian)

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

Types

interface HelpOptions {
  /** Show hidden commands and options */
  showHidden?: boolean;
}

interface Config {
  /** Enable shortcut invocation (default: true) */
  shortcut?: boolean;
  /** Add -h, --help options to commands (default: true) */
  options?: boolean;
}

// Koishi framework types used by the plugin
type Context = import('koishi').Context;
type Session = import('koishi').Session;
type Command = import('koishi').Command;
type Schema = import('koishi').Schema;
type Computed<T> = import('koishi').Computed<T>;
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@koishijs/plugin-help@2.4.x
Publish Source
CLI
Badge
tessl/npm-koishijs--plugin-help badge