🧩 核心概念
理解 QCL，关键是理解它的 5 个核心抽象。把这 5 个搞懂，后面所有章节都能顺下来。
| # | 抽象 | 一句话 |
|---|---|---|
| ① | 模块（Module）与 ModuleManager | QCL 由 22 个模块拼成，按优先级加载，单个崩不影响全局 |
| ② | 桥（Bridge）与软依赖 | 反射对接第三方插件，未装自动跳过，状态可查 |
| ③ | 物品源（ItemSource） | 把 10 种来源的物品统一成一套引用字符串 |
| ④ | 诊断与健康码 | 用 /qcl status 一眼看清整个生态健康 |
| ⑤ | API 边界 | 公开包 vs 内部包，apiJar 划清开发者能用的范围 |
① 模块（Module）与 ModuleManager
是什么
QCL 自身被拆成 22 个核心模块。每个模块实现 Module 接口，包含：name、priority、以及生命周期方法 load / enable / disable / unload。所有模块由 ModuleManager 统一管理。
为什么
- 解耦：物品、经济、脚本、GUI…各自成模块，互不纠缠。
- 降级不崩：单个模块
load/enable抛异常，只会把该模块标记为available=false/enabled=false，不影响其它模块。这是「降级而非崩溃」的设计——一个子系统挂了，服务器还能跑。 - 可开关：
config.yml的modules:段（键如config/database/gui/…）可逐个标记启用/禁用（默认全true）。
怎么体现
- 启动时
CoreModules.registerAll注册 22 个模块，moduleManager.loadAll()按 priority 升序逐个load()→enable()。 - 关服时
moduleManager.unloadAll()反向disable()→unload()。 /qcl status detail会逐行列出每个模块的状态。
📋 22 个核心模块与优先级（priority 升序加载）
| priority | 模块 | priority | 模块 |
|---|---|---|---|
| 0 | Config | 50 | Item |
| 5 | Database | 55 | Hologram |
| 8 | Reflection | 58 | Scheduler |
| 9 | ModelEngine | 60 | Condition |
| 10 | CustomCrops | 70 | Expression |
| 11 | CraftEngine | 75 | Script |
| 12 | MythicMobs | 80 | Economy |
| 13 | NeigeItems | 90 | CustomBlock |
| 14 | MMOItems | 100 | Assembly |
| 20 | Gui | ||
| 30 | Action | ||
| 40 | Pdc |
🔢 priority 越小越先加载。基础设施（Config / Database / Reflection）排在最前，组装层（Assembly）最后。详见 模块系统。
② 桥（Bridge）与软依赖
是什么
桥（Bridge） 是 QCL 对接第三方插件的方式：通过反射调用对方 API，把对方的能力接入统一管道。这些第三方都写在 plugin.yml 的 softdepend（软依赖）里。
为什么
- 软依赖只影响加载顺序，不强制：保证 QCL 在这些插件之后加载，从而能正确桥接。
- 未装自动跳过：装了对应插件，桥就点亮；没装，自动跳过不报错，对应能力静默关闭。
- 这让服主可以「按需搭配」——只装自己要用的第三方插件。
怎么体现
- 软依赖清单（全部反射桥接）：
Vault · ExcellentEconomy · PlayerPoints · PlaceholderAPI · ModelEngine CustomCrops · CustomFishing · MythicMobs · NeigeItems · MMOItems CraftEngine · QinhItems · MagicGem · ItemsAdder · Nexo /qcl status会显示经济桥 / PAPI / 数据库 / PDC 等的健康码，以及 QI/QS/QF/QSt 是否可用。/qcl status detail逐行列出每个桥的 BridgeStatus。
🔌 各类第三方的具体对接见 03-外部插件对接。
③ 物品源（ItemSource）统一引用
是什么
物品源 把来自 10 种不同来源的物品，统一成一套引用字符串，由 ItemSourceManager 解析。
为什么
- 不同插件的物品获取方式天差地别。QCL 用一套统一语法抹平差异，子插件照抄即用。
- 任何走
ItemSourceManager的子插件都自动支持全部来源，无需各自适配。
怎么体现
常见引用写法：
| 写法 | 来源 |
|---|---|
vanilla:DIAMOND 或 DIAMOND | 原版 |
mm-龙剑 | MythicMobs |
mi-SWORD-烈焰剑 | MMOItems |
qi:神剑 | QinhItems |
ia-包名_物品 | ItemsAdder |
nx-枪 | Nexo |
📖 完整 10 种来源的对照表与语法细节见 物品源引用。
④ 诊断与健康码
是什么
QCL 内建一套诊断体系，用健康码（health code）和状态文本表达各子系统是否正常，统一通过 /qcl status 暴露。
为什么
- 生态由很多模块和桥拼成，出问题时需要一眼定位到底哪一块挂了。
- 健康码让排错有据可查（对照 诊断码）。
怎么体现
/qcl status 输出涵盖：
- 平台状态（正常 / 异常）、整体健康码
- 模块健康、脚本桥 / 已加载脚本数
- 经济桥 / PAPI / 数据库 / PDC 健康码
- QI / QS / QF / QSt 是否可用
- 配置诊断、API 边界、公开 API 数、apiJar 包数 / 内部包数
- 启动诊断、物品引用诊断
/qcl status detail 额外逐行列模块与桥状态，并执行脚本 global:qcl_status.js:formatStatus 追加自定义诊断行。
🩺 排错流程见 诊断与排错。
⑤ API 边界（公开包 vs 内部包）
是什么
QCL 明确区分公开 API 包（开发者可依赖、稳定）与内部包（实现细节、不保证稳定），并通过 apiJar 划清边界。
为什么
- 平台库被很多插件依赖，必须承诺「哪些能用、哪些别碰」。
- 公开 API 稳定，内部包可自由重构，保护了上下游兼容性。
怎么体现
/qcl status 的 API 边界部分会报告：
- 公开 API 数
- apiJar 包数
- 内部包数
👨💻 开发者请只依赖公开包。详见 API概览。
⏱️ 启动生命周期时序（onEnable）
把上面的概念串起来，就是 QCL 的启动流程：
| 顺序 | 阶段 | 说明 |
|---|---|---|
| 1 | ServerCompat.validateServer | 校验 Java≥25、MC≥1.21.11，不达标禁用插件 |
| 2 | StartupReporter.reset | 重置启动报告 |
| 3 | saveDefaultConfig | 释放默认 config.yml |
| 4 | EconomyBridge.init + QinhScriptBridge.init | 初始化经济桥与脚本桥 |
| 5 | 注册 /qcl 命令 | 用 Cloud 命令框架创建并注册 |
| 6 | CustomGuiManager.init | 加载 guis/ 下所有 GUI |
| 7 | 模块加载 | CoreModules.registerAll 注册 22 模块，loadAll() 按 priority 升序 load()→enable() |
| 8 | 延迟 1 tick | ItemSourceBootstrap.reportAvailable + ItemManagerBootstrap.reloadExternalModules（加载 Groovy 外部物品模块）+ StartupReporter.printSummary（打印启动摘要） |
关服（onDisable）：moduleManager.unloadAll() 反向 disable()→unload()。