or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-koishijs--plugin-help

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

Workspace: tessl
Visibility: Public
Created: 4 months ago
Last updated: 4 months ago
Describes: pkg:npm/@koishijs/plugin-help@2.4.x

To install, run

npx @tessl/cli install tessl/npm-koishijs--plugin-help@2.4.0

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>;