Explains Zhin command registration, middleware flow, and permission checks. Use when building commands or message middleware in Zhin plugins.
Use this skill to add message commands and middleware in Zhin plugins. It maps to MessageCommand, addCommand, and the middleware compose flow.
import { usePlugin, MessageCommand } from '@zhin.js/core'
const plugin = usePlugin()
plugin.addCommand(
new MessageCommand('ping')
.desc('Health check command')
.action(async (message) => {
return 'pong'
})
)
MessageCommand uses segment-matcher syntax. Example with parameters:
new MessageCommand('echo <content:text>')
.usage('echo hello')
.examples('echo 你好')
.action(async (message, result) => {
return `You said: ${result.params.content}`
})
Commands can enforce permissions before matching:
new MessageCommand('admin-only')
.permit('group(123456)')
.permit('adapter(onebot11)')
.action(async (message) => 'ok')
The built-in permission service supports:
adapter(name)group(id) (use * to match any group)private(id)channel(id)user(id)Zhin composes middleware in a Koa-like onion model.
plugin.addMiddleware(async (message, next) => {
plugin.logger.info(`Incoming: ${message.$raw}`)
await next()
})
The core inserts a default middleware that routes messages to registered commands:
commandService.handle(...)message.$replyUse custom middleware for logging, auth, or throttling.
Commands can be auto-generated from ZhinTool definitions. When a tool is registered via plugin.addTool(), a corresponding MessageCommand is created automatically.
Conversely, existing commands can be converted to tools for AI agent use via toolService.commandToTool().
See the zhin-tool-service skill for full details on the unified Tool↔Command system, including ZhinTool, defineTool, permission levels, and tool collection.
usePlugin()..desc/.usage/.examples to enrich help text.next() unless you intentionally stop processing.ZhinTool when you need a tool that works with both AI agents and chat commands (see zhin-tool-service skill).