模块系统（bootstrap 包）
QinhCoreLib（QCL）把各项能力拆成模块（Module），由 ModuleManager 统一注册、按优先级加载、健康上报与降级隔离。本页介绍模块生命周期、22 个核心模块、降级机制、自定义模块写法，以及配套的诊断模型与启动探测。
Module 接口
| 成员 | 说明 |
|---|---|
name | 模块名 |
priority | 优先级，默认 0，升序加载 |
load() | 加载阶段 |
enable() | 启用阶段 |
disable() | 禁用阶段 |
unload() | 卸载阶段 |
AbstractModule(name) 提供以上方法的默认空实现，只需重写关心的钩子。
class MyModule : AbstractModule("MyModule") {
override val priority: Int = 50
override fun load() {
// 资源准备、读取配置
}
override fun enable() {
// 注册监听器、命令
}
override fun disable() {
// 注销监听器
}
override fun unload() {
// 释放资源
}
}ModuleManager（模块管理器）
| 方法 | 说明 |
|---|---|
register(module) | 注册模块 |
unregister(module) | 注销模块 |
getModule(name) | 按名取模块 |
statuses(): List<ModuleStatus> | 取全部模块状态 |
healthReport(): HealthReport | 健康报告 |
loadAll() | 按 priority 升序 load 再 enable 全部 |
unloadAll() | 卸载全部 |
reloadAll() | 重载全部 |
加载顺序与降级
loadAll()按priority升序：先对所有模块load，再对所有模块enable。- 降级隔离：单个模块抛异常时，只把该模块标记为
available = false/enabled = false，不影响其它模块。这意味着某个桥接（如脚本、经济）缺失或报错，核心不会整体崩溃，而是局部降级。 - 模块可被 config 的
modules.*开关控制启停。
CoreModules.registerAll 一次性注册 22 个核心模块到 ModuleManager。
22 个核心模块（优先级升序加载）
模块由
CoreModules.registerAll统一注册，按各自priority升序load→enable。基础设施类（数据库、配置、文本）优先级最低、最先加载；依赖它们的桥接与业务类随后加载。下表为概念分层（具体数值以源码CoreModules为准），帮助理解加载先后与依赖关系。
| 分层 | 典型模块职责 |
|---|---|
| 基础设施（最先） | 配置、数据库、调试/日志、文本 |
| 统一管道 | 物品源管理、属性管道、经济、占位符 |
| 外部桥接 | CraftEngine 方块桥、ModelEngine 模型桥、各物品源桥（MMOItems/NeigeItems/QinhItems/MythicMobs/CustomFishing/MagicGem/ItemsAdder/Nexo 等） |
| 脚本 | 脚本引擎（GraalVM） |
| 业务/界面（最后） | GUI、命令、启动报告等 |
提示：桥接类模块若对应软依赖未安装，会以反射桥方式跳过并标记为
NO_HOOK，属正常降级，不算错误。详见 诊断码。
子插件的正确接入方式
虽然开发者可以实现自定义 Module 并 register 到 QinhCoreLib.moduleManager，但通常不建议这样做。
子插件一般应使用自己的插件主类（JavaPlugin），在自己的 onEnable 中初始化，并通过 QCL 的对外 API 与服务（物品源、属性管道、调度、文本等）协作。只有当某能力确实需要纳入 QCL 的统一生命周期/健康上报时，才考虑注册为 QCL 模块。
// 推荐：子插件用自己的主类
class MySubPlugin : JavaPlugin() {
override fun onEnable() {
// 直接调用 QCL 的对外 API / 工具
}
}// 可选：确需纳入 QCL 生命周期时，注册为模块
QinhCoreLib.moduleManager.register(MyModule())诊断模型
QCL 的诊断模型提供结构化的状态与结果对象，便于排错与健康上报。
ModuleStatus
| 字段 | 说明 |
|---|---|
name | 模块名 |
enabled | 是否启用 |
available | 是否可用 |
message | 状态消息 |
BridgeStatus
| 字段 | 说明 |
|---|---|
name | 桥名 |
available | 是否可用 |
enabled | 是否启用 |
source | 来源 |
message | 消息 |
recoverable | 是否可恢复 |
HealthReport
| 字段 / 方法 | 说明 |
|---|---|
ok | 是否健康 |
code | 健康码（OK / NO_HOOK / DEGRADED） |
message | 消息 |
suggestion | 建议 |
healthy() | 构造健康报告 |
degraded(code, message, suggestion) | 构造降级报告 |
DiagnosticResult<T>
统一诊断结果容器。
| 字段 / 方法 | 说明 |
|---|---|
success | 是否成功 |
value | 结果值 |
code | 结果码 |
message | 消息 |
source | 来源 |
recoverable | 是否可恢复 |
suggestion | 建议 |
traceId | 追踪 ID |
ok(...) | 构造成功结果 |
fail(...) | 构造失败结果 |
val result: DiagnosticResult<ItemStack> = parseItem(ref)
if (result.success) {
val item = result.value
} else {
logger.warning("解析失败[${result.code}]：${result.message}，建议：${result.suggestion}")
}Trace*（调试追踪）
TraceModels 提供：TraceEvent、TraceReport、TraceBuilder、DebugTraceRegistry，用于记录与回放一次操作的内部步骤，便于深度排错。
BridgeStatusRegistry（桥状态注册表）
集中登记各外部桥的当前状态，/qcl status 等命令据此汇总。
| 方法 | 说明 |
|---|---|
register(status) | 登记桥状态 |
unregister(name) | 移除 |
get(name) | 取某桥状态 |
all() | 取全部 |
clear() | 清空 |
启动探测与报告
EcosystemStartupProbe（生态启动探针）
启动期探测可用的物品源、经济与插件挂钩，并构建平台状态摘要。
| 方法 | 说明 |
|---|---|
availableItemSources() | 可用物品源 |
availableEconomies() | 可用经济 |
probePluginHooks() | 探测插件挂钩 |
buildPlatformStatus() | 构建平台状态 |
formatSummary() | 格式化摘要 |
StartupReporter（启动报告器）
汇总并打印启动摘要。
| 方法 | 说明 |
|---|---|
reset() | 重置 |
setGuiCount(n) | 设置 GUI 数量 |
hookedItemSource(...) | 记录已挂钩的物品源 |
hookedBridge(...) | 记录已挂钩的桥 |
hookedEconomy(...) | 记录已挂钩的经济 |
printSummary() | 打印摘要 |