<p align="center">
<a href="https://zhin.js.org">
<img src="https://raw.githubusercontent.com/zhinjs/zhin/HEAD/docs/public/logo.svg" alt="Zhin.js" width="120" height="120" />
</a>
</p>
<h1 align="center">Zhin.js</h1>
<p align="center">
<strong>TypeScript로 한 번 작성하고 20개 이상의 채팅 플랫폼에서 봇을 실행하세요.</strong><br />파일 기반 명령어, 크로스 플랫폼 JSX 카드, 메모리 누수 없는 핫 리로드(hot reload), 옵트인 AI 에이전트를 브라우저에서 관리할 수 있습니다.<br />QQ · WeChat · WeCom · DingTalk · Lark · Discord · Telegram · Slack · KOOK · LINE · …
</p>
<p align="center">
<a href="https://github.com/zhinjs/zhin/actions/workflows/ci.yml"><img src="https://github.com/zhinjs/zhin/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
<a href="https://www.npmjs.com/package/zhin.js"><img src="https://img.shields.io/npm/v/zhin.js.svg?color=cb3837" alt="npm" /></a>
<a href="https://www.npmjs.com/package/zhin.js"><img src="https://img.shields.io/npm/dm/zhin.js.svg?color=cb3837" alt="npm downloads" /></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/node/v/zhin.js.svg?color=339933" alt="Node" /></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
<a href="https://codecov.io/gh/zhinjs/zhin"><img src="https://codecov.io/gh/zhinjs/zhin/graph/badge.svg" alt="codecov" /></a>
<a href="https://zhin.js.org"><img src="https://img.shields.io/badge/docs-zhin.js.org-0ea5e9" alt="Docs" /></a>
</p>
<p align="center">
<b >영어</b> ·
<a href="./README.zh-CN.md">간체 중국어</a>
</p>
<p align="center">
<a href="https://zhin.js.org/en/">문서(Documentation)</a> ·
<a href="./docs/en/authoring/define-plugin.md">플러그인 작성(Plugin Authoring)</a> ·
<a href="./docs/en/customer/index.md">운영자 가이드(Operator Guide)</a> ·
<a href="https://demo.zhin.dev">실시간 데모(Live Demo)</a> ·
<a href="https://console.zhin.dev">원격 콘솔(Remote Console)</a> ·
<a href="./docs/contributing/development.md">기여하기(Contributing)</a>
</p>
코드를 작성하지 않고 봇을 실행하는 방법이 궁금하신가요? Operator & Group Admin Guide로 이동하거나 Live Demo를 사용해 보세요. TypeScript로 플러그인이나 어댑터를 구축하고 싶으신가요? 바로 아래에서 시작하거나 Plugin Authoring을 살펴보세요.
30초 만에 시작하기 (Quick Start)
플랫폼 계정이나 모델 키가 필요하지 않습니다 (Node.js ≥22.19.0, pnpm 9+):
npm create zhin-app my-bot -- -y --adapter sandbox
cd my-bot
pnpm dev
- 콘솔에서 설정 완료하기: 터미널에 출력된 콘솔 링크(
https://console.zhin.dev/?apiBaseUrl=…#token=…; # 뒤의 부트스트랩 토큰은 브라우저를 벗어나지 않습니다)를 열고, 기본 SQLite 데이터베이스를 유지한 채 소유자 계정을 생성합니다.
- 샌드박스와 채팅하기:
http://127.0.0.1:8068/sandbox (또는 콘솔의 Conversations → Sandbox)를 열고 /hello를 전송합니다.
- 백그라운드에서 실행하기:
npx zhin start를 실행합니다 (이후 zhin status, zhin logs -f, zhin stop 사용).
전체 워크스루: Quick start · 문제가 발생했나요? npx zhin doctor를 실행하세요.
[!중요]
1.1.13 버전 이하의 기존 봇을 업그레이드하는 경우? Runtime은 이제 configVersion: 2만 허용합니다. 먼저 봇을 중지한 후, zhin.js / @zhin.js/cli를 최신 버전으로 업그레이드하고, zhin migrate instances (preview) 및 zhin migrate instances --apply (먼저 백업)를 실행하세요. 전체 단계 및 복원: configVersion 2로 업그레이드하기.
단일 프로세스 zhin runtime start에서 업그레이드하는 경우? zhin start는 이제 봇을 감독하는 장기 실행 관리 게이트웨이(management gateway)를 실행합니다. 콘솔 계정이 http.tokens를 대체합니다. 동일한 버전의 zhin.js / @zhin.js/cli와 함께 @zhin.js/gateway를 설치하고 관리 게이트웨이로 업그레이드하기를 따르세요.
왜 Zhin.js인가요?
Zhin.js는 **채팅 앱에서 작동하는 봇(bots that live in chat apps)**을 위한 TypeScript 프레임워크입니다. 이 프레임워크는 커뮤니티 봇, 개인 비서, 알림 및 지원 봇, 그리고 관리되는 AI 채팅 비서 등을 포괄합니다.
- 단일 코드베이스로 20개 이상의 플랫폼 지원. 어댑터(Adapters)가 각 플랫폼을 하나의 통일된 메시지 모델로 변환합니다. 단일 봇으로 여러 플랫폼에 걸쳐 다수의 계정을 동시에 운영할 수 있습니다.
- 기능은 파일입니다.
commands/, middlewares/, components/, schedules/, 또는 tools/ 폴더에 파일을 드롭하기만 하면 자동으로 등록됩니다. 별도의 연결(wiring) 코드가 필요 없습니다 (zero wiring boilerplate).
- Generation 격리형 핫 리로드(Generation-isolated hot reload). 파일을 저장하면 Zhin이 원자적으로(atomically) 새로운 Generation을 교체합니다. 진행 중인 메시지는 이전 버전을 통해 완료되며, 새 코드가 시작 시 오류를 발생시켜도 이전 버전은 다운타임 없이 계속 서비스를 제공합니다.
- 기본적으로 작고(<10MB), 필요할 때만 AI 사용. IM 코어는 LLM(대규모 언어 모델) 의존성이 없습니다.
npx zhin setup --ai 명령을 사용하여 언제든지 AI 에이전트, 도구, 3계층 마크다운 메모리, 그리고 MCP를 추가할 수 있습니다.
- 브라우저 콘솔 및 서버 기반 블루프린트 포함. console.zhin.dev에서 계정을 관리하고, 스키마 기반 양식(schema-driven forms)을 편집하며, AI 결정을 재실행하고, 비상 정지(emergency stops)를 트리거할 수 있습니다. 플러그인은 순수 TypeScript의
definePageBlueprint 페이지(pages/<name>/index.ts — .tsx나 esbuild 번들링 없음)를 작성하여 웹 콘솔에 렌더링하고, IM 카드(projectBlueprintToImCard) 또는 CLI TUI 패널(projectBlueprintToCliPanel)로 투영합니다.
Zhin은 에디터 내 코딩 에이전트(Cursor나 Claude Code와 같은)가 아닙니다. 이 AI 스택은 채팅 플랫폼, 그룹 권한, 다중 사용자 대화에 특화되어 설계되었습니다.
보여주고, 말하지 마라: 3가지 핵심 기능 (Show, Don't Tell: 3 Killer Features)
1. 명령어 + 크로스 플랫폼 JSX 카드 및 인터랙티브 버튼
JSX에서 인터랙티브 카드를 한 번 작성하기만 하면 됩니다 (commands/poll/index.tsx). 버튼을 지원하는 플랫폼에서는 사용자가 직접 클릭하며, 일반 텍스트 기반 플랫폼에서는 Zhin이 자동으로 <button> 태그를 번호가 매겨진 텍스트 선택지로 변환하고, 그 답장을 onClick 콜백으로 다시 라우팅합니다:
// commands/poll/index.tsx → /poll "Release v1.2 today?"
import { defineCommand } from 'zhin.js/command'
...
2. 보일러플레이트 코드 없는(Zero-Boilerplate) AI 도구
zhin.js의 defineAgentTool과 Schema.object(...)를 사용하여 tools/<name>/index.ts에 파일을 추가합니다. 프레임워크 보안 정책은 모델이 이를 호출하기 전에 권한(permissions), 가시성(visibility), 그리고 인간의 승인(human approval)을 강제합니다:
import { Schema } from 'zhin.js'
import { defineAgentTool } from '@zhin.js/tool'
...
3. 누수 방지(Leak-Free) 핫 리로드 및 다중 플랫폼 configVersion: 2
프로젝트의 package.json#zhin.entry는 plugin.ts (또는 단일 파일 봇의 경우 bot.ts)를 가리키며, 마운트된 어댑터(mounted adapters), 자식 플러그인(child plugins), 그리고 인스턴스별 설정은 모두 zhin.config.yml에 깔끔하게 존재합니다:
봇이 구성되는 방식 (How a Bot is Put Together)
chat platform 사용자 프로젝트 (플러그인) chat platform
QQ / Discord … ──▶ Adapter ──▶ Middleware ──▶ Command ──────────────▶ Adapter ──▶ reply
│ no command matched
...
| 파트 | 정의 | 위치 |
|---|
| 플러그인 | 사용자의 프로젝트 자체가 루트 플러그인(Root plugin)이며, 성장함에 따라 자식 플러그인으로 분할됩니다. | package.json#zhin.entry (plugin.ts)에 진입점(Entry)이 있고, 자식 인스턴스는 zhin.config.yml의 plugins:에 마운트됩니다. |
| ... | | |
my-bot/
├── package.json # "zhin" 필드: 진입점 ("./plugin.ts") 및 기능(capability) 특징
├── zhin.config.yml # configVersion: 2 — 마운트된 플러그인, 플랫폼 엔드포인트, HTTP 포트
...
다음 내용:
핵심 개념 한눈에 보기 · 첫 재사용 가능한 플러그인 작성하기 · 모든 컨벤션 폴더 · Command 심층 분석
npx zhin setup --adapters
pnpm install && pnpm dev
| Platform | Package | Platform | Package |
|---|
| Sandbox (로컬 테스트) | @zhin.js/adapter-sandbox | QQ (ICQQ) | @zhin.js/adapter-icqq |
| ... | | | |
| 각 어댑터는 성숙도 단계(Stable / Advanced / Experimental)를 가지며 자체 설정 가이드가 있습니다: Adapters overview. | | | |
AI 추가하기 (선택 사항)
npx zhin setup --ai
pnpm install && pnpm dev
위자드는 @zhin.js/agent를 @zhin.js/tool 및 @zhin.js/prompt-section과 함께 설치하고, zhin.config.yml에서 AI를 활성화하며, 첫 시작 시 런타임 카탈로그에 자동으로 시딩되는 ai.plan.yml (API 키는 .env에 저장됨)을 생성합니다:
이제 어떤 명령어와도 일치하지 않는 메시지는 모델로 전달됩니다. 기본적으로 DM에서, 또는 그룹 채팅에서 ai: 접두사나 @mention과 함께 사용될 때 그렇습니다. 새로운 기능을 부여하려면 tools/에 파일을 추가하세요.
Claude subscription 및 Antigravity는 실험적인 채널입니다: 实验 · 공식 지원 안 함 · 공급업체 약관 위반 가능성 있음 · 사용자는 자체 위험 부담 (experimental · not officially supported · may violate vendor terms · use at your own risk). AI providers를 참조하세요.
다음: AI 개요 · 에이전트 도구, 스킬 및 프롬프트 섹션 · AI 에이전트 학습 경로
필요한 것만 설치하기
|
| Tier | Install | Adds |
|---|
| IM (기본값) | zhin.js + @zhin.js/cli + 어댑터; CLI는 개발 및 프로덕션 환경에 필요한 zhin start와 관리 게이트웨이(@zhin.js/gateway)를 제공합니다 | 내장 명령어, 컴포넌트, 미들웨어, 스케줄, 핫 리로드 — <10MB |
| ... | | |
상세 테이블 및 크기: Install tiers. 1.1 버전부터는 ZhinAgent / AIService를 zhin.js가 아닌 zhin.js/agent / zhin.js/ai에서 가져와야 합니다.
운영자 및 그룹 소유자를 위한 기능 (코딩 불필요)
봇이 배포되면, 일상적인 작업은 브라우저 콘솔(console.zhin.dev)에서 이루어집니다. 이 콘솔은 프로젝트의 **관리 게이트웨이(management gateway)**와 통신합니다: 로그인, 권한 관리, 인스턴스 시작 및 중지, 의존성 설치 및 터미널 작업 등이 이곳에서 처리되므로, 봇 인스턴스가 충돌하거나 업그레이드되는 동안에도 콘솔은 계속 작동하며 — 로그인, 상태, 로그 등을 확인할 수 있습니다.
첫 방문 시: 첫 번째 소유자 계정을 생성하려면 설정 링크인 zhin start가 출력하는 값(또는 .env 파일의 HTTP_TOKEN)을 사용해야 합니다. 이 이후에는 부트스트랩 토큰이 작동하지 않으며, 모든 사용자는 계정으로 로그인합니다. 서버에서는 대신 zhin console init을 실행할 수 있습니다.
콘솔은 네 가지 수준의 객체 — global → adapter → account → conversation — 로 구성되어 있으며, 모든 수준은 동일한 페이지 레이아웃을 가집니다:
| 섹션 | 보이는 것 및 할 수 있는 작업 |
|---|
| 개요 (Overview) | 해당 수준의 온라인 상태 및 통계 정보 |
| ... | |
계정(Account) 페이지에는 연결(Connection) 기능(로그인, QR 코드, 연결 확인)이 추가되고, 대화(Conversation) 페이지에는 채팅(Chat) 기능(읽은 기록 조회 및 메시지 전송)이 추가됩니다.
관리: