ZCBOT
通用化 IM 平台 —— 协议无关的事件驱动机器人框架
内核极简 · 扩展点契约 · 官方插件集 · 业务写在自己的插件里
Gitee(国内) | GitHub(国际) | PyPI | 更新日志 | LLM 索引
ZCBOT 是一个不绑定任何聊天协议的机器人框架。内核只负责事件分发、插件加载、权限与持久化;协议接入端、Web 后台、多轮会话、定时任务、LLM 能力全部是可选插件。换一个接入端就能接入另一种 IM,也可以不接任何平台,只跑定时任务或接收 HTTP 事件。
它把"能跑"做成"能长期稳定地跑"——单实例锁、崩溃守卫、安全模式、平台化依赖诊断、Web 后台安全提醒,都是为生产部署兜底,而不是只给你一套脚手架。
核心特性
- 🧩 协议无关内核 —— 内核不含任何协议实现,OneBot 11 只是默认接入端之一。
- 🔌 可插拔接入端 —— 内置 OneBot 11、QQ 官方、Telegram、Discord、出站 WS、HTTP 注入 / HTTP API。
- 🪝 扩展点(Hook)系统 —— 可挂到启动 / 关闭、Web 请求、事件分发、命令执行、协议动作等几乎每一个运行环节。
- 🔥 插件热加载 —— 放进
plugins/即生效;用装饰器声明命令、权限、定时任务。 - 🖥️ Web 管理后台 —— Vue 3 + Element Plus;插件、用户、权限、日志、数据库一站管理。
- 🔐 权限与令牌 —— 节点式权限引擎 + 接口令牌(API Key),细粒度控制到命令级。
- ⏱️ 多轮会话 / 定时任务 —— 会话状态与调度器均为官方插件,按需启用。
- 🗄️ 双方言数据库 —— SQLite 零配置开箱即用,大环境一键切 MySQL。
- 🛡️ 安全加固 —— 蜜罐诱饵、JS 人机验证、认证静默丢弃、可调安全等级(
off~paranoid)。 - ⚡ 双核心架构 —— 可选 core / host 双进程,插件崩溃不拖垮核心(实验特性,默认关闭)。
- 🔒 单实例锁 + 安全模式 —— 防止重复运行;持久配置错误时挂起「假启动」,让
Type=simple守护进程停止无脑拉起,不再空吃冷启动税(崩溃计数文件error.log*清零后自愈)。 - 🩺 平台化依赖诊断 —— 插件加载失败自动归类(缺依赖 / 版本不兼容 / 系统运行库缺失),给出中文提示与
pip install命令,并附原始报错,不再是一串英文堆栈。 - 🔑 Web 后台安全提醒 —— 用默认密码(
admin/admin123)登录后,后台顶部提示「建议修改密码」并可一键跳转(建议,非强制)。
快速上手
方式一 · pip 安装(推荐)
pip install zcbot
zcbot
首次启动会在 ~/.zcbot 自动生成配置与数据(可用环境变量 ZCBOT_HOME 指定其它目录)。
看到 框架启动完成,等待消息... 即启动成功。
升级:pip install -U zcbot。
方式二 · 源码运行
git clone https://gitee.com/liquanfeng123/zcbot.git # 或 GitHub 镜像
cd zcbot
pip install -r requirements.txt
python main.py
配置与数据落在仓库目录下(行为同旧版)。依赖缺了启动时会自动补装。
官方插件默认全部关闭。 需要哪种能力就启用哪个:把
core_plugins.yaml里对应块的enabled改成true,或运行python tools/scan_core_plugins.py --enable <插件名>,重启生效。 例如进 Web 后台要启用webui(127.0.0.1:8080,默认账号admin/admin123,登录后后台会自动建议改密,一键跳转设置); 要收发聊天消息要启用某个接入端(如onebot_adapter)。
更多方式(Docker、反向代理、HTTPS、纯 API 部署)见 安装 · 部署。
支持的接入端
| 接入端 | 说明 |
|---|---|
| OneBot 11 | 反向 WebSocket,默认接入端(QQ 生态) |
| QQ 官方 | QQ 开放平台机器人 |
| Telegram | Bot API |
| Discord | Bot |
| 出站 WS / HTTP 注入 / HTTP API | 自定义协议或外部系统对接 |
不接任何平台也可以:内核可直接跑定时任务、或接收 HTTP 事件。
写一个插件
plugins/hello/main.py:
__plugin_meta__ = {"name": "Hello", "version": "1.0.0",
"author": "你", "desc": "打招呼", "priority": 50}
def register(ctx):
ctx.command("/hello", handle_hello, description="打个招呼")
async def handle_hello(event, match):
await ctx.asend_msg(user_id=event.user_id,
group_id=event.group_id if event.is_group else None,
message="Hello, World!")
放进 plugins/ 后点「重载」即可。权限用 require_perm="myplugin.ban" 声明式拦截;
想插到几乎每个运行环节就用 ctx.hook(...)(见
扩展点)。
完整教程见 编写插件。
文档
文档随仓库分发,Gitee 与 GitHub 同步(下方链接指向 Gitee,GitHub 上把域名替换即可)。
- 指南:安装 · 开始使用 · 配置 · 对接 IM · 编写插件 · 多轮会话 · 接入 LLM · 最佳实践
- API:ctx · Event · 扩展点 Hook · 协议适配器 · Framework · 服务注册表 · 插件装饰器
- 进阶:内核设计哲学 · 架构详解 · 加载机制 · 数据库 · 定时任务 · 权限 · 接口令牌 · 部署 · 双核心 · 项目结构 · 扩展清单
- LLM / Agent:LLM.md · 框架结构 · 插件开发 · 调试排错
反馈交流
- 交流群(QQ):1060129201
- 问题反馈:Gitee Issues | GitHub Issues
- 官方扩展仓库:zcbot_plugins
开源协议
MIT OR Apache-2.0,任选其一适用。
本项目以 AI 生成为主、人工辅助完成。用着顺手的话,给个 Star 吧 ⭐
Metadata
Release files for zcbot 1.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| zcbot-1.10.0.tar.gz | 10.1 MB | Without provenance | Details for zcbot-1.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zcbot-1.10.0-py3-none-any.whl | Python 3 | none | any | Details for zcbot-1.10.0-py3-none-any.whl |
Total release size: 20.4 MB
Release files / zcbot-1.10.0.tar.gz
| Download URL | zcbot-1.10.0.tar.gz |
|---|---|
| Size | 10.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
83c2c22455355580b8aa47bea44e87a470379cb26915182f7129fd161aeb9f16
|
|
BLAKE2b-256 checksum How to use checksums |
7d8f20de2f7391d8b61ed6242d68c2f61bf1d4169b5f824d7804db818dfdfc83
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.5
|
Release files / zcbot-1.10.0-py3-none-any.whl
| Download URL | zcbot-1.10.0-py3-none-any.whl |
|---|---|
| Size | 10.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
360ae490649f3551eee51ca4a2a39d52fe17e10f3213f76e912c6e174ba4b2d7
|
|
BLAKE2b-256 checksum How to use checksums |
11b219df09857c80a84407cefed83b35df06df4b071840ac629ee97dabc50d8b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.5
|
Security for zcbot 1.10.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.