诊断与排错大全
QI 提供一组诊断命令帮你定位问题。本页讲每个命令输出什么、各项指标怎么读。
一、诊断命令一览
| 命令 | 用途 |
|---|---|
/qi status | 简要加载状态（物品数 / 问题 / 编译失败） |
/qi inspect | 详细状态检查 |
/qi diagnose | 完整诊断报告（各子系统可用性） |
/qi problems | 列出所有已知问题 |
/qi problems summary | 问题摘要 |
/qi trigger report | 动作触发配置报告 |
二、启动日志怎么读
启动 / 重载时 QinhItemsStartupLog 打印摘要：
物品定义: 123 · ActionTable 45
Bridge: 3 · Layer: 4 · Handler: 12
Combat: 启用 · 属性后端: attributeplus (已接入)
宝石: LI(LC✔·8孔) · MG(2孔)
诊断: 30/30 项可用| 行 | 含义 | 怎么读 |
|---|---|---|
| 物品定义 / ActionTable | 加载的物品数、动作表数 | 数字明显偏少 → 有文件没加载，查 /qi problems |
| Bridge / Layer / Handler | 桥、层贡献者、处理器数量 | Handler 里应含 qinhskills:cast（若装了 QS） |
| Combat | 战斗模块状态 | 关闭(纯物品库) = 没开 combat |
| 属性后端 | AP 接入情况 | noop = 没检测到 AP |
| 宝石 | LI / MG 后端孔数 | LC✔ = LegendCore 桥已注册 |
| 诊断 | 可用项 / 总项 | 分母分子不等 → 有子系统异常 |
三、/qi diagnose 报告项
诊断会逐项列出各实体的健康状态（ItemsDiagnostics）：
| 报告实体 | 含义 | 附带提示 |
|---|---|---|
QinhItem:<id> | 物品定义健康度 | 类型 / 品质 / 动作文件 / 配置版本 |
ActionTable:<itemId> | 动作表 | 绑定数量 |
ActionTableProblem | 动作加载错误 | |
FailureFile:<kind> | YAML 解析失败文件 | item / action |
ProviderBridge:<id> | Provider 桥 | 是否可用 |
ExternalResolver:<prefix> | 外部物品解析器 | |
LayerContributor:<namespace> | 层贡献者 | order |
ActionHandler:<id> | 动作处理器 |
摘要还会给：物品 / 段 / 词缀 / 动作表计数、各来源格式与分类、编译失败、重载问题、失败文件分组。
四、常见问题定位流程
问题：某个物品没加载
1. /qi status → 看「问题」数是否 > 0
2. /qi problems → 找到对应物品的报错
3. 对照 校验报错速查 → 按报错修 YAML
4. /qi reload → 重新加载报错含义见 校验报错速查。
问题：动作不触发
1. /qi trigger report → 确认该物品的触发器配置被加载
2. /qi trigger test <id> <player> → 手动执行首个触发绑定，看是否生效
3. 检查触发原子是否合适（right_click 对空气可能不触发，改 left_click）
4. 检查 handler 是否注册（diagnose 看 ActionHandler 列表）
5. 改了 YAML 记得 /qi reload（动作只在 reload 加载）问题：属性不上身
1. 启动日志看「属性后端」
· noop → 没装 AP，或 combat.enabled: false
· attributeplus → 正常
2. 控制台有无「映射名不存在」警告 → 改 attribute-mapping 对齐 AP
3. 装备物品后 /qi refresh hand 强制刷新详见 属性与数值。
问题：宝石孔识别不到
1. 启动日志看「宝石」行，LI/MG 后端是否启用、孔数是否 > 0
2. 核对 integrations/legendinlay_sockets.yml 的 lore 与 LI 那边逐字一致
3. LegendCore 桥：看日志「检查 LegendCore/groovy/QinhItemsModule.groovy」五、健康度指标解读
物品 healthIssues() 为空才算健康。不健康物品仍加载但列入问题。常见不健康原因见 校验报错速查 §1。
/qi diagnose 的「N/M 项可用」：M 是总诊断项，N 是当前可用项。差值就是异常子系统数，逐项看哪个 不可用。
六、刷新相关
配置改了但玩家身上旧物品没更新？用刷新命令重渲染：
/qi refresh all # 所有在线玩家
/qi refresh hand # 仅主手（自测快）刷新 = 对每件 QI 物品 rebuild() + variables().refresh()，保留实例 / 种子。见 随机生成 → 刷新服务。