Choose your path
Zhin serves two kinds of people. Pick yours — the rest of this README is split the same way.
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y @zhin.js/[email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add zhin.js-mcp -- npx -y @zhin.js/mcp@1.1.31在終端機中執行。
{ "mcpServers": { "zhin.js-mcp": { "command": "npx", "args": [ "-y", "@zhin.js/[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
Zhin serves two kinds of people. Pick yours — the rest of this README is split the same way.
Model Context Protocol (MCP) service for Zhin.js - AI assistant integration
| You are | A group owner, community operator or support lead. You run the bot; you don't write TypeScript. | Someone who writes commands, plugins, AI tools or platform adapters. |
| You use | The browser Console and a config file | TypeScript, create-zhin-app, the zhin CLI |
| You get | Welcomes, check-ins, reminders, feed pushes, moderation, announcements that wait for approval, a one-switch emergency stop | One codebase on 20+ platforms, a feature is a file, hot reload that can't take you down |
| Start here | Try the live demo → Operator & Group Admin Guide | Developer quick start → First plugin |
Zhin.js is a framework for bots that live in chat apps — operators run them from a browser console, developers build them in TypeScript. Think community bots, personal assistants, notification and support bots, AI chat assistants.
commands/hello/index.ts is the /hello command. Middleware, message cards, scheduled jobs and AI tools work the same way — no registration boilerplate.Zhin is not an in-editor coding agent (like Cursor or Claude Code). Its AI features exist to power bots on chat platforms.
You don't need to write code to run a Zhin bot well. Once a developer (or your ops person) has deployed it once, day-to-day work happens in the browser.
Connect. Open console.zhin.dev and enter the bot's API address and token (HTTP_TOKEN). Use a read-only Demo token for colleagues who only watch. Not deployed yet? Try the live demo first.
Group ops with guardrails. The AI can draft announcements but only a person with approval rights can send them; risky admin actions such as kicking a member become approval cards with a cooldown; every decision is traceable in decision replay.
When to call a developer: first deployment or server moves, a feature no existing plugin provides, a new platform, connecting the AI to your business systems, or errors in the run log you can't interpret.
👉 Full guide: Operator & Group Admin Guide · Console path · Troubleshooting
Everything below is for people writing plugins and adapters in TypeScript.
No platform account and no model key required.
npm create zhin-app my-bot -y
cd my-bot
pnpm dev
http://127.0.0.1:8068) and the HTTP_TOKEN from .env./hello. You should get a reply.-y accepts every default: a browser Sandbox (simulated chat) instead of a real platform, and no AI. Requirements: Node.js ≥22.19.0 and pnpm 9+. Something wrong? Run npx zhin doctor.
Full walkthrough: Quick start · Prefer not to install yet? Try the live demo.
[!IMPORTANT] Upgrading an existing bot from 1.1.13 or earlier? The Runtime now only accepts
configVersion: 2. Stop the Bot first, upgradezhin.js/@zhin.js/clito the latest, then runzhin migrate instances(preview) andzhin migrate instances --apply(backs up first). Full steps and restore: Upgrading to configVersion 2.
chat platform your project (a plugin) chat platform
QQ / Discord … ──▶ Adapter ──▶ Middleware ──▶ Command ──────────────▶ Adapter ──▶ reply
│ no command matched
└──▶ AI Agent (optional) ──▶ Tools
New to these terms? Read Core concepts at a glance — it explains every word the docs use, in plain language.
A whole bot can be one file:
// bot.ts
import { definePlugin } from 'zhin.js'
import { defineCommand } from 'zhin.js/command'
export default definePlugin({
name: 'my-bot',
setup({ addCommand }) {
addCommand('hello', defineCommand({
description: 'Say hello',
execute: () => 'Hello from Zhin!',
}))
},
})
As it grows, move each capability into its own file. The folder path is the name, and the file registers itself:
// commands/remind/index.ts → /remind 10 stretch
import { defineCommand } from 'zhin.js/command'
export default defineCommand({
description: 'Create a reminder',
params: {
minutes: { type: 'integer', min: 1, max: 1440 },
note: { type: 'text', default: 'Take a break' },
},
options: { quiet: { type: 'boolean', default: false } }, // --quiet
execute: ({ params, options }) =>
options.quiet ? 'OK' : `OK, I'll remind you in ${params.minutes} min: ${params.note}`,
})
my-bot/
├── package.json # "zhin" field: entry and child plugins (what is installed)
├── zhin.config.yml # port, platform credentials, models (how it is configured)
├── .env # secrets: HTTP_TOKEN, API keys
├── plugin.ts # entry: definePlugin()
├── commands/ # /commands — folder path = command name
├── middlewares/ # runs on every message
├── components/ # reusable JSX message cards
├── schedules/ # scheduled jobs
├── tools/ # functions the AI may call (optional)
└── pages/ # custom Console pages
npx zhin setup --adapters # pick platforms, enter credentials
pnpm install && pnpm dev
Each adapter has a maturity tier (Stable / Advanced / Experimental) and its own setup guide: Adapters overview.
npx zhin setup --ai # choose a provider (OpenAI, Ollama, …) and write the config
pnpm install && pnpm dev
The wizard installs the Agent runtime and the tool / prompt features, and writes something like this to zhin.config.yml (keys go to .env):
ai:
enabled: true
providers:
openai-main:
sdk: openai
apiKey: ${AI_API_KEY}
agents:
zhin:
provider: openai-main
model: gpt-4o-mini
Messages that match no command now go to the model — in DMs by default, in groups with an ai: prefix or a mention. Give it abilities by adding files to tools/; permissions, approvals and file/network access are enforced by framework policy, not by the prompt.
Detailed table and sizes: Install tiers. Since 1.1, ZhinAgent / AIService are imported from zhin.js/agent / zhin.js/ai, not from zhin.js.
Operators & group owners
Developers
Full site: zhin.js.org (Chinese by default; switch language in the nav).
npx zhin setup # add platforms, AI, database to an existing project
npx zhin doctor # diagnose Node, ports, tokens, manifest
npx @zhin.js/cli new my-plugin --standalone # scaffold a publishable plugin package
npx zhin search <keyword> # find community plugins
npx zhin install <name> # install and mount a plugin
All commands: CLI reference.
How the layers fit together: architecture · repo structure.
git clone https://github.com/zhinjs/zhin.git
cd zhin
pnpm install && pnpm build
pnpm dev # runs examples/minimal-bot
Other entry points: pnpm --filter single-file-bot dev (one-file bot) and pnpm dev:test (maintainers' kitchen-sink test-bot, not a template). See the contributing guide for checks, conventions and the release flow.
Model Context Protocol (MCP) service for Zhin.js - AI assistant integration
{ "mcpServers": { "zhin.js-mcp": { "command": "npx", "args": [ "-y", "@zhin.js/[email protected]" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
@zhin.js/mcp 透過 stdio 在本機執行。
上次檢查時間:2026-11-16。 Model Context Protocol (MCP) service for Zhin.js - AI assistant integration