TypeScript · ESM · Plugin Runtime

Zhin.js

A multi-channel IM framework built for assistant bots. Plugins are Lego blocks, hot reload is the norm, and Console lives in your browser.

Quick Start Examples GitHub ↗

IM core <10MBNode ≥20.19MIT

zsh

$ npm create zhin-app my-bot
$ cd my-bot && pnpm dev
✔ IM golden path started — no model key required

Start from your role

You do not need the full architecture first. Choose the outcome you need now.

BUILDBuild your first Bot

Move from Sandbox to one real platform through a repeatable message path.

Run the golden path AUTHORShip a plugin

Close capability, configuration, lifecycle, testing, and release as one loop.

Open the delivery path OPERATEDeploy and operate

Own TLS, supervision, monitoring, backup, upgrades, and rollback.

Open production guide AGENTBuild an Agent team

Govern Prompt, Tool, Workroom, and repository collaboration boundaries.

Choose an Agent solution

Why Zhin.js

Plugin-based Core

A package.json#zhin manifest plus a plugin.ts is all you need. Commands, components, and adapters are discovered from convention directories. Edit a file, get instant hot reload.

Multi-platform, One Message Flow

QQ, OneBot, Discord, Telegram, Slack, KOOK, DingTalk, Lark, WeCom, LINE… 20+ adapters mount on demand, all sharing the same send chain.

Zero-deploy Console

Host exposes only API. Open your browser to manage plugins, view instances, browse logs, and edit config — the frontend does not need to run alongside the bot.

Opt-in AI

Only the IM core ships by default. Install @zhin.js/agent when you need it — providers, MCP, sub-agents, and scheduled tasks unlock layer by layer.

Plugin as Application

Drop a zhin.config.yml in a plugin directory and zhin runtime start runs it directly. No host project required.

Unidirectional Layers

basic → kernel → ai → core → agent → zhin. Dependencies only flow downward. Each layer is usable standalone — kernel is a pure plugin engine, ai is a pure LLM engine.

One file, one bot

bot.ts — your entire bot can be just this one file.

import { defineCommand } from 'zhin.js/command';
import { definePlugin } from 'zhin.js';

export default definePlugin({
  name: 'my-bot',
  setup({ addCommand }) {
    addCommand('hello', defineCommand({
      description: 'Say hello',
      execute: () => 'Hello from Zhin!',
    }));
  },
});

Three steps to get running (no model key needed):

bash

npm create zhin-app my-bot -y
cd my-bot && pnpm dev

Open console.zhin.dev → Sandbox → /hello.

Want convention directories instead? Default-export the same defineCommand(...) from commands/hello.ts — see minimal-bot.

Full single-file example: single-file-bot. Database, cron, proactive push, Agent? Check out definePlugin overview for what setup can do.