进阶
**改框架之前读这一层。**这里讲的是骨架本身——分层、加载机制、存储、权限、调度、部署，以及为什么这么设计。
先读这一篇
| 文档 | 解决什么问题 |
|---|---|
| 内核设计哲学 | 全部架构决策的依据：用极小的、稳定的内核，托住无限可变的扩展。改 framework/ 或写官方扩展前先确认符合这些信条 |
骨架与运行机制
| 文档 | 解决什么问题 | 什么时候读 |
|---|---|---|
| 架构总览 | 一条命令从发出到回复经历了什么：分层加载、事件归一、路由匹配、一次服务注册表查询。插件出问题时知道该往哪一层查 | 排查问题 / 想理解全链路 |
| 插件加载机制 | 多文件插件的 from .xxx import Y 为什么失败：包怎么合成、模块名怎么登记、热重载怎么才可靠 | 插件要拆多文件 |
| 可靠性与限流 | 断线重连重推导致重复回复、被刷屏打爆内存：内核在入队前做重放去重与三级限流，插件无需感知 | 消息重复回复 / 要做防刷 |
| 数据库 | 建表、查询、事务。默认 SQLite 零配置即可用，场景放大后切 MySQL，上层接口不变 | 插件要存数据 |
| 数据库迁移 | 表结构怎么演进：账本表记版本、每版只跑一次、失败可重试、已发布的迁移不可改 | 要给框架表加字段 / 排查结构落后 |
| 定时任务 | 到点自动执行（日报、零点重置、每 5 分钟探活）。官方 core_plugins/scheduler 基于 APScheduler，插件用 ctx.task() 注册 | 要做定时自动化 |
| 权限系统 | 谁能用哪个命令：权限节点管细粒度授权、身份轴管粗粒度管理员判断，可配置、可继承、能落到具体群，两者可叠加 | 要控制命令权限 |
| 接口令牌 | 两类 HTTP 接口（别混淆端口）、API Key 的创建与吊销 | 要对外提供 HTTP 接口 |
上线与工程
| 文档 | 解决什么问题 | 什么时候读 |
|---|---|---|
| 部署上线 | 放到服务器长期运行：进程自拉起、端口只对必要来源开放、定期备份 | 要上生产 |
| 项目结构 | 仓库目录、前端构建产物、建表 SQL 分别在哪 | 刚接手仓库 |
| 扩展清单 | 官方扩展 / 内置用户扩展 / 官方扩展仓库（plugin.dir 指向 zcbot_plugins，或后台插件市场安装） | 找现成能力 |
| 双核心架构 | 实验版：core/host 双进程。用户插件把进程拖崩时，核心看门狗自动拉起宿主，接入端与 Web 不中断 | 需要插件崩溃隔离 |
给 AI 编码助手的浓缩版在 速查。