诊断码
本页汇总 QinhCoreLib（QCL）各子系统的状态码与错误码，按子系统分组。每个码给出含义、触发场景与处理建议。
这些码会出现在三个地方：
| 出现位置 | 谁产生 | 怎么看到 |
|---|---|---|
/qcl status / /qcl status detail 的诊断行 | 各诊断器（DiagnosticResult.code） | 游戏内或控制台执行命令 |
| 开发者 API 返回值 | ResolveResult.code（物品）、ScriptExecutionResult.code（脚本）、EconomyTransactionResult.code（经济） | 代码里读取返回对象 |
| 控制台日志 | 启动探针 / 各桥 | 服务端日志文件 |
🧱 两层状态：启用 vs 可用
读码之前先理解 QCL 对「模块」和「桥」区分的两层状态（/qcl status detail 会同时显示）：
| 维度 | 字段 | 含义 | 由什么决定 |
|---|---|---|---|
| 启用 / 未启用 | enabled | 这个模块/桥是否被开启 | config.yml 的 modules.* 开关 + load()/enable() 是否成功 |
| 可用 / 不可用 | available | 运行期是否真的能工作 | 对应软依赖是否安装、运行时是否就绪 |
一个桥可以「启用但不可用」（开关开着，但对应插件没装 →
NO_HOOK），也可以「未启用」（被modules.*关掉）。排错时先分清是哪一层。详见 模块系统。
❤️ 健康码（HealthReport / 桥状态）
HealthReport.code，也是 /qcl status 里「健康码 / 模块健康 / 各桥健康」显示的值。
| 码 | 含义 | 触发场景 | 处理建议 |
|---|---|---|---|
OK | 正常 | 模块/桥已挂钩并正常运行 | 无需处理 |
NO_HOOK | 无软依赖挂钩 | 对应外部插件未安装，桥按设计跳过 | 属正常降级；需要该能力时安装对应插件 |
DEGRADED | 降级（可恢复） | 装了对应插件但运行受损（API 变动、版本不匹配等） | 看 message / suggestion，修复后 /qcl reload 或重启 |
⚠️
NO_HOOK不是错误，是「没装软依赖」的正常状态；只有DEGRADED才需要关注。一个全新、未装任何软依赖的服务器，/qcl status大量显示NO_HOOK是完全正常的。
📦 物品解析码（ItemSource）
走 ItemSourceManager.parseItemReference 的物品引用解析返回，也是开发者 API ItemManagerAPI.resolve(...) 的 ResolveResult.code。
| 码 | 含义 | 触发场景 | 处理建议 |
|---|---|---|---|
OK | 解析成功 | 引用有效，物品已构建 | 无需处理 |
PARSE_FAILED | 引用串解析失败 | 引用格式错误（空串、非法分隔等） | 核对引用格式，见 物品源引用 |
MATERIAL_NOT_FOUND | 原版材质未找到 | vanilla: 材质名拼写错或该版本不存在 | 检查 Material 枚举名（全大写）拼写 |
SOURCE_NOT_FOUND | 物品源未找到 | 引用所指的源未注册（对应插件没装/没启用） | 安装对应物品源插件，或改用其它源 |
MODULE_BUILD_FAILED | 模块构建失败 | 物品源模块构建物品时抛错 | 查日志，检查该源自身配置是否有效 |
ITEM_NOT_FOUND | 物品未找到 | 该源中不存在此 ID | 核对物品 ID 是否真实存在于对应源 |
🔎
/qcl status末尾的「物品引用诊断」用vanilla:stone做自检——它返回OK表示物品源解析链路本身正常；某个具体引用失败要单独用ItemManagerAPI.diagnose(ref, player)排查。详见 物品 API。
📜 脚本错误码（JavaScript / GraalVM）
ScriptExecutionResult.code，脚本执行（GUI 条件/动作、API 调用）返回。
| 码 | 含义 | 触发场景 | 处理建议 |
|---|---|---|---|
SCRIPT_UNAVAILABLE | 脚本子系统不可用 | GraalJS 运行时缺失（多为纯 Spigot 没拉到库），或 javascript.enabled=false | 用 Paper/Purpur；检查 config javascript.enabled |
SCRIPT_PARSE_FAILED | 引用串解析失败 | 脚本引用格式错（非 命名空间:路径.js[:函数名]） | 修正引用格式 |
SCRIPT_NOT_FOUND | 脚本文件未找到 | 指定脚本文件不存在 | 核对脚本所在目录与路径 |
SCRIPT_FUNCTION_MISSING | 函数缺失 | 脚本中没有目标函数 | 检查函数名，或 config javascript.default-function |
SCRIPT_FAILED | 执行失败 | 脚本运行期抛异常 | 开 javascript.debug.print-stacktrace 看堆栈 |
💰 经济码（Economy）
EconomyTransactionResult.code，经济操作（查/存/取/设）返回。
| 码 | 含义 | 触发场景 | 处理建议 |
|---|---|---|---|
OK | 成功 | 经济操作完成 | 无需处理 |
CURRENCY_REQUIRED | 需要指定货币 | 用 ExcellentEconomy 但未指定货币且无默认 | 设 economy.default-currency，或调用/动作里显式传货币 |
INSUFFICIENT_FUNDS | 余额不足 | 玩家资金不够（多见于 take_money） | 正常业务结果，按需提示玩家 |
NO_PROVIDER | 无经济提供方 | 未安装任何经济插件，或指定的 provider 未注册 | 安装经济插件并配 economy.default-provider |
EconomyDiagnostics（经济诊断）
/qcl status 的经济桥诊断与开发者诊断 API 使用。
| 码 | 含义 | 触发场景 | 处理建议 |
|---|---|---|---|
ECONOMY_UNAVAILABLE | 经济整体不可用 | 经济子系统无任何可用后端 | 检查 Vault/ExcellentEconomy/PlayerPoints 是否安装并启用 |
ECONOMY_PROVIDER_MISSING | 缺少提供方 | 指定的 provider 未注册 | 核对 economy.default-provider，或确认该后端插件已装 |
ECONOMY_CURRENCY_MISSING | 缺少货币 | 指定/默认货币在 ExcellentEconomy 中不存在 | 配 economy.default-currency 或核对货币 ID（money/silver/gold…） |
🧰 DiagnosticResult 字段（开发者）
所有诊断结果统一用 DiagnosticResult<T> 容器承载，理解字段有助于读懂状态：
| 字段 | 类型 | 含义 |
|---|---|---|
success | Boolean | 本次诊断是否成功 |
value | T? | 诊断附带的数据（如解析出的物品、桥状态列表） |
code | String | 状态码（即上表各码） |
message | String | 人类可读消息 |
source | String | 诊断来源（模块/桥名） |
recoverable | Boolean | 是否可恢复（DEGRADED 类一般 true） |
suggestion | String | 修复建议 |
traceId | String | 追踪 ID，便于串联日志 |
构造用伴生方法 DiagnosticResult.ok(...) / DiagnosticResult.fail(...)。详见 模块系统 · 诊断模型。
🕹️ 相关命令
| 命令 | 别名 | 权限 | 说明 |
|---|---|---|---|
/qcl status | probe | qcl.status | 状态摘要 |
/qcl status detail | full | qcl.status | 完整状态（逐模块/逐桥 + 脚本扩展行） |
/qcl reload | rl | qcl.admin | 重载配置/经济/脚本/外部物品模块/GUI |