Files

4.5 KiB

Plugin API v1

Loading

Built-in plugin files are discovered recursively under the compiled dist/plugins directory. External directories are listed in pluginDirectories. Entry files end in .plugin.js and export a default manifest via CommonJS (exports.default = ...). TypeScript built-ins use .plugin.ts during development and compile to JavaScript. External TypeScript plugins must be compiled first. External dependencies should be packaged alongside the plugin or installed by the server operator.

A manifest declares:

  • apiVersion: 1, a unique lowercase id, a version, optional name aliases and bilingual description.
  • validate(config), returning validated configuration or throwing an error.
  • Optional allowedRooms(config), declaring additional target rooms for membership actions and reads.
  • create(context, config), returning an instance with a command list and optional start, stop, onMember and onPowerLevel hooks.

Duplicate plugin IDs/name aliases and incompatible manifests reject discovery. Command alias collisions reject that plugin's activation before its start hook runs. A failed activation cancels registered jobs and leaves the host's management commands available. Installed plugins with missing required configuration appear as failed until configuration is corrected and activation is retried.

Plugins are trusted code running in the host process. Context room checks and abort signals prevent accidental use outside declared scopes, but are not a security sandbox. Only operators install files; chat commands cannot fetch packages or execute uploaded code.

Context

The public interfaces live in src/core/plugin/types.ts. The context provides:

  • account, botUserId, roomId, locale, timeZone, adminPowerLevel, signal, now().
  • t({ 'zh-CN': ..., en: ... }, values) for shared interpolation and language selection.
  • db.get/set/create/remove/entries, already isolated to the account/room/plugin instance. create is atomic and returns false for an existing key.
  • send(text) and reply(message, text) to the current room.
  • members(roomId?), power(userId), isAdmin(userId); lookup failures propagate from members/power while administrative checks deny on failure.
  • kick(roomId, userId, reason) and invite(roomId, userId) to declared rooms.
  • schedule(name, cron, callback) using the room timezone. The host serializes callbacks with commands, lifecycle changes and events.
  • audit(action, actor, details) for room-scoped administrative history.

Use context.schedule instead of unmanaged timers. Disable waits behind already running room work, unregisters scheduled callbacks, aborts the instance signal, calls stop and retains data. Async work started outside host callbacks must observe the abort signal and release its resources in stop. A stalled plugin can stall its room; plugins should use bounded I/O and cancellation. A process shutdown additionally prevents new transport operations while queues drain.

Use context.t and declarative command aliases instead of branching on language in handlers. context.locale is a live getter so an enabled plugin sees language changes immediately.

Commands

Each command declares id, paths, optional exact bare aliases, optional admin: true, localized description and usage, and run(invocation).

The host matches the longest registered command path, normalizes command words and fullwidth prefixes, preserves quoted arguments and recognizes --raw / --原始. The handler receives { message, args, raw }. Prefix-free aliases must match the entire message, preventing ordinary conversation from accidentally executing a command. The host handles the primary administrator check, help generation and errors. Plugins should also validate arguments and recheck permissions immediately before delayed or confirmed mutations.

Complete example

Copy examples/greeting.plugin.js into an external directory listed in configuration. After restarting to discover the file, use !plugin enable greeting or !插件 启用 问候. Then !greet World and !问候 世界 invoke the same handler. !language en changes the response language without reinstalling the plugin. No changes to the application module, dispatcher or session manager are needed.

A future RSS plugin can use the same API to register subscription commands, persist subscriptions/deduplication keys and schedule polling. Feed retrieval and parsing belong inside that plugin. The host does not currently include an RSS feed parser or subscription implementation.