上一页：物品源引用 · 下一页：概览（外部插件对接）
🩺 诊断与排错
/qcl status 是排查一切问题的第一站。本页逐行解读它的输出、给出健康码表、常见问题的处理办法，并附一棵「排查决策树」。
🔐 命令权限：
/qcl status需要qcl.status，别名/qcl probe；详细版/qcl status detail（别名/qcl status full）。见 命令与权限。
🟢 健康码表
诊断输出里到处是「健康码」，常见取值：
| 健康码 | 含义 | 是否要处理 |
|---|---|---|
OK | 正常 | ✅ 无需处理 |
NO_HOOK | 无对应软依赖（外部插件没装） | ⚪ 正常情况，按需安装 |
DEGRADED | 降级，但可恢复 | ⚠️ 关注，多为软依赖缺失/未就绪 |
📌
NO_HOOK不是错误——只是说你没装对应的外部插件，相关对接自然没启用。
📋 /qcl status 摘要逐项解读
/qcl status 摘要包含下列项。下表给出每项含义、正常值、异常处理。
| 诊断项 | 含义 | 正常表现 | 异常怎么办 |
|---|---|---|---|
| 软依赖探测 · 物品源 | 已注册物品源数量 + 列表 | 列出你装的物品插件对应源 | 缺某源 → 装对应插件 + 确认模块未禁用 |
| 软依赖探测 · 经济 | 探测到的经济插件 | 显示 Vault/EE/PlayerPoints | 缺经济 → 装经济插件 |
| 软依赖探测 · 属性插件 | 探测到的属性插件 | 按你装的显示 | — |
| 软依赖探测 · 已接入插件 | 已接入的外部插件列表 | 列出已接入项 | — |
| 平台状态 | 整体平台是否正常 | 正常 | 异常 → 看健康码/建议 |
| 健康码 | 平台健康码 | OK | DEGRADED → 按健康建议处理 |
| 健康建议 | 平台给出的修复建议 | 无/提示 | 照建议处理 |
| 模块健康码 | 模块整体健康 | OK | 用 detail 看是哪个模块 |
| 脚本桥接 | 脚本桥是否可用 + 已加载脚本数 | 可用 | 不可用 → 见下文 |
| 经济桥健康码 | 经济桥健康 | OK | NO_HOOK/DEGRADED → 见下文 |
| PAPI 桥健康码 | PlaceholderAPI 桥健康 | OK/NO_HOOK | 装 PAPI |
| 数据库健康码 | 数据库桥健康 | OK | 查 config.yml database 段 |
| PDC 健康码 | PDC 存储健康 | OK | — |
| QI/QS/QF/QSt 状态 | 各子插件状态及桥/协议数 | 按已装子插件显示 | 子插件没装即不显示/不可用 |
| 配置诊断码 | 配置加载诊断 | OK | 检查 config.yml 语法 |
| API 边界码 | API 边界检查 | OK | 见参考诊断码 |
| 公开 API 数 / apiJar 包数 / 内部包数 | API 统计 | 数字 | 一般无需关注 |
| apiJar 诊断码 / 可导出 API 类数 | API jar 诊断 | OK / 数字 | 见参考诊断码 |
| 启动诊断码 | 启动流程诊断 | OK | 看启动日志 |
| 物品引用诊断码 | 实测解析 vanilla:stone | OK | 物品模块异常 → 检查 modules.item |
🔬 /qcl status detail 额外项
详细版在摘要基础上额外输出：
- 桥接数、模块数、TraceId（报问题时附上它便于定位）。
- 逐模块：每个模块显示「启用/未启用」+「可用/不可用」+ 消息。
- 逐桥：每个桥显示「启用/未启用」+「可用/不可用」+ 来源 + 消息。
- 脚本扩展行：脚本
global:qcl_status.js:formatStatus追加的自定义行。
💡 「启用/未启用」由
config.yml的modules开关决定；「可用/不可用」由软依赖是否就绪决定。两者含义不同，排查时要分清。
🧰 常见问题排查
❓ 某个桥显示「不可用」
- 先
/qcl status detail看该桥的「启用/未启用」。- 未启用 → 是
config.yml里modules把对应模块关了，改回true并重启。 - 已启用但不可用 → 看该桥的「来源」和「消息」，通常是对应外部插件没装/版本不符/未就绪。
- 未启用 → 是
- 健康码若是
NO_HOOK→ 正常，装上对应软依赖即可。 - 健康码若是
DEGRADED→ 按摘要的「健康建议」处理。
❓ 脚本桥不可用
- 检查
config.yml→javascript.enabled是否为true。 - 检查
modules.script是否为true。 - 开
javascript.debug.print-stacktrace: true，/qcl reload后看控制台报错堆栈。 - 确认脚本路径格式正确：
命名空间:相对路径.js[:函数名]。
❓ 经济桥不可用 / NO_HOOK
NO_HOOK说明没探测到任何经济插件 → 安装 Vault / ExcellentEconomy / PlayerPoints 之一。- 装了仍不可用 → 检查
economy.default-provider是否指定了一个没装的提供者；设回auto让它自动挑。 - 用 EE 多货币时确认
economy.default-currency是有效的 EE 货币 id。
❓ 某个物品引用失败
按错误码对症（详见 物品源引用）：
| 错误码 | 处理 |
|---|---|
PARSE_FAILED | 检查引用格式（分隔符、段数） |
MATERIAL_NOT_FOUND | 核对原版材料名（全大写枚举） |
SOURCE_NOT_FOUND | 对应插件没装 / 模块被禁用 |
ITEM_NOT_FOUND | 物品 id 写错 / 该物品未配置 |
先看 /qcl status 末尾「物品引用诊断码」是否 OK（它实测 vanilla:stone）；若连原版都不行，多半是 modules.item 被禁用了。
❓ 模块未启用
/qcl status detail 中某模块显示「未启用」→ 去 config.yml 的 modules 段把它改回 true，然后重启服务器（模块开关影响装载，reload 不够）。
🌲 排查决策树
某功能异常？
│
├─ /qcl status detail 里相关项「未启用」？
│ └─ 是 → config.yml modules 改回 true → 重启
│
├─ 显示「不可用」？
│ ├─ 健康码 NO_HOOK → 装对应外部插件（正常情况）
│ ├─ 健康码 DEGRADED → 按「健康建议」处理
│ └─ 看「来源」「消息」→ 多为外部插件没装/版本不符
│
├─ 物品引用失败？
│ ├─ PARSE_FAILED → 改引用格式
│ ├─ MATERIAL_NOT_FOUND→ 改原版材料名
│ ├─ SOURCE_NOT_FOUND → 装插件 / 开模块
│ └─ ITEM_NOT_FOUND → 改物品 id
│
├─ 改了配置不生效？
│ ├─ database / modules → 必须重启
│ └─ 其它 → /qcl reload
│
└─ 还搞不定？
└─ /qcl status detail 截图（含 TraceId）→ 查 ../05-参考/诊断码.md / FAQ.md