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)登录后,后台顶部提示「建议修改密码」并可一键跳转(建议,非强制)。 - LLM 子系统(可选插件) —— 提供商与工具双总线、工具调用闭环、会话窗口、多模态与 MCP;内置本地知识库(混合检索 RAG,向量 + 全文,单 SQLite 文件)与调用链追踪面板。不启用时内核毫无感知。
- 可观测性 ——
/healthz存活、/readyz就绪(带逐项检查明细)、/metrics(Prometheus 文本格式);插件元数据可用requires声明加载依赖,配置改完即时告诉你哪些要重启。
快速上手
前置:一定要用虚拟环境
框架会在运行期自己调 pip 装插件依赖(sys.executable -m pip)。不隔离环境会有三类问题:
- 现代发行版(Debian 12 / Ubuntu 23+ / 各类容器镜像)系统 Python 禁止全局 pip,
直接报
error: externally-managed-environment,启动时所有自动补装全部失败; - 装到系统 Python 里,插件之间版本冲突无法回退,也污染系统包管理器;
- 升级 / 回滚框架时无法整体丢弃旧依赖。
python3 -m venv .venv
# Linux / macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate
之后所有 pip / python 都在这个环境里,不要用 sudo pip。
方式一 · pip 安装(推荐)
pip install zcbot
zcbot
首次启动会在 ~/.zcbot 自动生成配置与数据(可用环境变量 ZCBOT_HOME 指定其它目录)。
看到 框架启动完成,等待消息... 即启动成功。
升级:pip install -U zcbot。
方式二 · 源码运行
git clone https://gitee.com/liquanfeng123/zcbot.git # 或 GitHub 镜像
cd zcbot
python3 -m venv .venv && source .venv/bin/activate # Windows: py -m venv .venv && .venv\Scripts\activate
pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
python main.py
配置与数据落在仓库目录下(行为同旧版)。requirements.txt 只装内核必需依赖;
官方插件专属依赖在启用该插件后自动补装到当前环境——webui 要 flask/flask-cors/waitress,
image_renderer 要 Pillow,llm_load 要 sqlite-vec,aiwriter 要 textual。所以上一步的 venv 不是可选项。
国内网络建议始终带镜像源参数;插件自动补装也内置了清华→阿里→豆瓣→官方 的回退列表。
官方插件默认关闭,但
echo/help/scheduler/webui默认开启。 需要哪种能力就启用哪个:把core_plugins.yaml里对应块的enabled改成true,或运行python tools/scan_core_plugins.py --enable <插件名>,重启生效。webui默认监听127.0.0.1:8080(默认账号admin/admin123,登录后后台会自动建议改密,一键跳转设置); 端口与监听地址在config.yaml的web段改(core_plugins.yaml里同名键已废弃)。 要收发聊天消息要启用某个接入端(如onebot_adapter),接入端凭证仍写在core_plugins.yaml。
更多方式(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,任选其一适用(双授权,与 Rust 生态惯例一致)。
| 文件 | 内容 |
|---|---|
LICENSE |
MIT 全文(最常见的选用入口) |
LICENSE-APACHE |
Apache License 2.0 全文 |
THIRD-PARTY-NOTICES.md |
WebUI 打包的第三方组件(element-plus / vue / vue-router,均为 MIT)版权声明 |
版权人:zgric。
选 Apache-2.0 的话额外获得明确的专利授权条款;只想要最简单条款就用 MIT。
WebUI 产物里的
THIRD-PARTY-NOTICES.txt是上述第三方声明的纯文本副本 —— 构建时的压缩与混淆会把源码里的版权注释删干净,MIT 要求副本保留声明, 所以它必须随产物一起分发,CI 有门禁校验。
本项目以 AI 生成为主、人工辅助完成。用着顺手的话,给个 Star 吧 ⭐
Metadata
Release files for zcbot 1.20.2
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.20.2.tar.gz | 10.3 MB | Without provenance | Details for zcbot-1.20.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zcbot-1.20.2-py3-none-any.whl | Python 3 | none | any | Details for zcbot-1.20.2-py3-none-any.whl |
Total release size: 20.7 MB
Release files / zcbot-1.20.2.tar.gz
| Download URL | zcbot-1.20.2.tar.gz |
|---|---|
| Size | 10.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
65deae82cb86d41096c8c9b62ebe3e64a5f8f9e2f65b4855e04ff9da15510f7b
|
|
BLAKE2b-256 checksum How to use checksums |
430b33c4c41aee92eef826d617be65f4dd5867f8a6ca462eae973c59011201a1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / zcbot-1.20.2-py3-none-any.whl
| Download URL | zcbot-1.20.2-py3-none-any.whl |
|---|---|
| Size | 10.4 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d40c517063b15d1be092b3b35872aa87dfac61f88bc3fa8da76945e257cfdc3e
|
|
BLAKE2b-256 checksum How to use checksums |
cf396276cf3b8fdf07969bfc8091c848c5c3cc7bc10f245ab661b9588778bdc9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for zcbot 1.20.2
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.