安装
想把 ZCBOT 跑起来，按下面走完就行。不需要编程基础；依赖装漏了启动时也会自动补。
方式 A · pip 安装（推荐，最省事）
pip install zcbot
zcbot- 配置与数据落在
~/.zcbot（可用环境变量ZCBOT_HOME指定其它目录）；首次启动自动生成config.yaml、core_plugins.yaml和data/。 - 升级：
pip install -U zcbot（~/.zcbot下的配置/数据不会被动）。
方式 B · 源码安装（想改内核 / 二次开发时用）
开始前先备好这些
| 需要 | 说明 |
|---|---|
| Python 3.10+ | 建议 3.10–3.14；Windows / Linux / macOS 均可 |
| （可选）聊天接入端 | 只有要收发聊天消息才需要；纯定时 / Webhook 可以先不接。对接见 对接 IM 平台 |
第 1 步：下载代码
git clone https://gitee.com/liquanfeng123/zcbot.git
cd zcbot没有 git 的话，也可以在 GitHub 页面点 Code → Download ZIP，解压后进入目录。
第 2 步：虚拟环境（必做）
# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate
# Windows（PowerShell / cmd）
py -m venv .venv
.venv\Scripts\activate不要跳过。 框架运行期会自己调 sys.executable -m pip 补装插件依赖，不隔离会踩三类问题：
| 问题 | 现象 |
|---|---|
| 系统 Python 禁止全局 pip | Debian 12 / Ubuntu 23+ / 多数容器镜像报 error: externally-managed-environment，所有自动补装静默失败，插件全部加载不出来 |
| 版本冲突无法回退 | 插件 A 要 flask<3、插件 B 要 flask>=3，装到系统里只能二选一且污染系统包 |
| 无法整体回滚 | 升级框架后要退回旧版本，依赖没隔离只能手工收拾 |
激活后所有 pip / python 都指向 .venv，不要用 sudo pip（会绕过 venv 装到系统里）。
第 3 步：装依赖
pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple依赖也写在
pyproject.toml里，两处保持同步：日常启动自检读requirements.txt，工具链读pyproject.toml。 改依赖时两处都要改；只使用的话装requirements.txt就够了。
常用核心包：websockets（连接）、apscheduler（定时）、bcrypt（密码）、psutil（监控）。 flask + flask-cors + waitress（Web 管理后台）默认不装：纯机器人部署下 API 层注册假节点；启用 core_plugins/webui 后由插件加载器自动补装。
这一步漏了也能救，但别指望
python main.py 启动时会自检 requirements.txt，缺包会走内置镜像（清华→阿里→豆瓣→官方）自动装； 插件自己的依赖也会在加载时自动装。但在系统 Python 下这套自愈会因为上面第一条直接失败， 而且自动装在事件循环里同步执行，首次启动会阻塞几秒到几十秒。手动装一次最省事。
MySQL 用户额外需要 pymysql、DBUtils（切到 MySQL 时平台内核会提示并安装）。
第 4 步：启动
python main.py首次启动会生成 config.yaml、core_plugins.yaml 和 data/。
注意：官方插件大部分默认关闭，但
echo/help/scheduler/webui默认开启（core_plugins.yaml中其余插件enabled为false）。 需要哪个能力，就把对应插件enabled改为true，或用python tools/scan_core_plugins.py --enable <插件名>，然后重启框架。 例如要进 Web 后台就得启用webui；要收发聊天消息就得启用某个接入端（如onebot_adapter）。
看到类似输出即成功（默认仅启用 echo / help / scheduler / webui 几个官方插件）：
ZCBOT 框架 启动中...
框架启动完成，等待消息...接着做：
目录结构（以后会用到的）
zcbot/
├── main.py # 启动入口：python main.py [自定义配置路径]
├── config.yaml # 全局配置（首次启动自动生成）
├── core_plugins.yaml # 官方插件开关/配置（启动自动同步）
├── requirements.txt # 依赖清单（启动自检读它）
├── pyproject.toml # 项目元数据（与 requirements 同步）
├── framework/ # 平台内核
├── core_plugins/ # 官方插件（在 yaml 里开关）
│ ├── onebot_adapter/ # OneBot 11（默认关，需启用）
│ ├── webui/ # Web 后台（默认关，需启用）
│ ├── session/ # 多轮会话（默认关，需启用）
│ ├── scheduler/ # 定时任务（默认关，需启用）
│ ├── telegram/ discord/ # 其它接入端（默认关，填凭证后开）
│ ├── kook/ matrix/ # KOOK 与 Matrix 接入端（默认关）
│ ├── qq_official/ ws_client/ http_inject/ http_api/
├── plugins/ # 你的插件（每个一个文件夹）
├── data/ # 运行数据：logs/、数据库、plugins_dat/
├── web/ # 后台前端静态资源
├── sql/ # 建表脚本
├── tests/ # 自测
└── docs/ # 本文档日常最常碰：plugins/（写功能）、core_plugins.yaml（开关/接平台）、data/（日志与数据）。
升级
git pull
pip install -r requirements.txt # 补全新依赖插件配置和数据库都在 data/ 下，升级不会清空。旧版散落在插件目录里的配置会自动迁到 data/plugins_dat/<名>/。