Skip to main content

ZCBOT

通用化 IM 平台 —— 协议无关的事件驱动机器人框架

内核极简 · 扩展点契约 · 官方插件集 · 业务写在自己的插件里


PyPI Python License Release


Gitee(国内) | GitHub(国际) | PyPI | 更新日志 | LLM 索引


ZCBOT 是一个不绑定任何聊天协议的机器人框架。内核只负责事件分发、插件加载、权限与持久化;协议接入端、Web 后台、多轮会话、定时任务、LLM 能力全部是可选插件。换一个接入端就能接入另一种 IM,也可以不接任何平台,只跑定时任务或接收 HTTP 事件。

它把"能跑"做成"能长期稳定地跑"——单实例锁、崩溃守卫、安全模式、平台化依赖诊断、Web 后台安全提醒,都是为生产部署兜底,而不是只给你一套脚手架。

核心特性

  1. 🧩 协议无关内核 —— 内核不含任何协议实现,OneBot 11 只是默认接入端之一。
  2. 🔌 可插拔接入端 —— 内置 OneBot 11、QQ 官方、Telegram、Discord、出站 WS、HTTP 注入 / HTTP API。
  3. 🪝 扩展点(Hook)系统 —— 可挂到启动 / 关闭、Web 请求、事件分发、命令执行、协议动作等几乎每一个运行环节。
  4. 🔥 插件热加载 —— 放进 plugins/ 即生效;用装饰器声明命令、权限、定时任务。
  5. 🖥️ Web 管理后台 —— Vue 3 + Element Plus;插件、用户、权限、日志、数据库一站管理。
  6. 🔐 权限与令牌 —— 节点式权限引擎 + 接口令牌(API Key),细粒度控制到命令级。
  7. ⏱️ 多轮会话 / 定时任务 —— 会话状态与调度器均为官方插件,按需启用。
  8. 🗄️ 双方言数据库 —— SQLite 零配置开箱即用,大环境一键切 MySQL。
  9. 🛡️ 安全加固 —— 蜜罐诱饵、JS 人机验证、认证静默丢弃、可调安全等级(off~paranoid)。
  10. ⚡ 双核心架构 —— 可选 core / host 双进程,插件崩溃不拖垮核心(实验特性,默认关闭)。
  11. 🔒 单实例锁 + 安全模式 —— 防止重复运行;持久配置错误时挂起「假启动」,让 Type=simple 守护进程停止无脑拉起,不再空吃冷启动税(崩溃计数文件 error.log* 清零后自愈)。
  12. 🩺 平台化依赖诊断 —— 插件加载失败自动归类(缺依赖 / 版本不兼容 / 系统运行库缺失),给出中文提示与 pip install 命令,并附原始报错,不再是一串英文堆栈。
  13. 🔑 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 上把域名替换即可)。

反馈交流

开源协议

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)

Source distribution for zcbot 1.10.0
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)

Table of built distributions (wheels) for zcbot 1.10.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page