诊断排错
按"现象 → 原因 → 处理"组织的排查手册。先在下面的决策树里对号入座，再看对应小节。
🌳 快速决策树
| 现象 | 最可能的原因 | 跳到 |
|---|---|---|
| QS 根本没启用 | 没装 QinhCoreLib（硬依赖） | §1 |
| 技能放出来只有一条聊天消息 | MM 没写同名技能（那是占位 stub） | §2 |
| 物品按了完全没反应 | 没解锁 / handler 没注册 / atom 不匹配 | §3 |
| 提示"冷却中/资源不足/没有可用目标/未满足条件" | 对应门控拦下了 | §4 |
| 控制台刷 schema 警告 | 技能字段与 graph 文件不一致 | §5 |
| 连招怎么都放不出终结技 | finalize / window / require_state 配错 | §6 |
| 想知道卡在管线哪一步 | 用 debug: true 看 trace | §7 |
| 桥 / MM 状态存疑 | 用 /qs protocol、/qs bridge | §8 |
1. QS 没启用
QinhCoreLib（QCL）是硬依赖。没装它，QS 不会启用，控制台会报缺依赖。先装 QCL，再确认服务端 1.21.11+、Java 25+。
2. 技能只有占位消息
现象：技能门控全过，但只发一条 [QinhSkills] 技能名，没有粒子 / 伤害 / 位移。
原因：MM 里没有同名技能，QS 退化成占位 stub。
处理：
- 去
plugins/MythicMobs/skills/写一个与技能 id 同名的 MM 技能（如fire_wave）； /mm reload；- 必要时
/qs reload同步桥。
看到占位消息其实是好消息——说明 QS 这侧已完全跑通，只差 MM 的表现层。
3. 物品按了没反应
逐项排查：
| 检查点 | 处理 |
|---|---|
| 技能没解锁 | /qs unlock <技能> [玩家]，或配 starter_skills / default_all |
| handler 没注册 | QI 没装或加载晚于 QS；装好 QI 后 /qs reload |
atom 与 trigger.primary 不一致 | 会回退到 entry 节点（技能仍能放），但确认按键映射是否如预期 |
| 技能根本没加载 | /qs list 看技能在不在列表；不在就 /qs reload |
想确认"按下"这一步通没通，直接
/qs cast <技能>绕过物品测一遍，看返回的 结果码。
4. 被门控拦下
收到下面任意提示，都是某个门控拦下的，对应技能配置查即可：
| 提示 | 查这里 |
|---|---|
§c技能冷却中 … / §c充能 … | cooldown.base / charges / 冷却组 |
§c资源不足 | resource.mana 等占位资源 |
§c没有可用目标 | target 的 range / filter / required |
§c未满足释放条件 | conditions: 列表（等级 / 血量 / 目标类型…） |
§c技能冲突 | conflict_groups |
§c当前施法模式不可用 | cast_mode（toggle 状态 / channel 进行中） |
各提示与结果码一一对应，详见 结果码 CastResult。
5. schema 警告
/qs reload 时若控制台报 schema_issues，说明技能定义里的 meta / trigger / state / graph / execution 段与对应 graph 文件对不上：
trigger.primary必须在 graph 入口节点的triggers内；graph.entry要指向真实存在的 graph node id；state.required是合法 SkillState（IDLE等）。
看 /qs reload 日志里点名的具体字段逐个对齐。被动（type: passive）技能 1.0.16 起无需写 trigger.primary，schema 会自动按 PASSIVE 处理。
6. 连招放不出
终结技放不出来，逐项核对 graph 的 combos 段：
| 检查点 | 要求 |
|---|---|
finalize_skill | 必须是本 graph nodes 里的一个 node id（不是 _id，也不能是不存在的名字） |
window_ms | 太短会在按完序列前超时回 IDLE，连招断；适当加大 |
续段节点 require_state | 续段节点必须是 COMBO_WINDOW（起手成功后才进此状态，靠它区分起手 / 续段） |
inputs 序列 | 须含起手那一下，且与实际按键 TriggerType 完全一致 |
详见 服主指南 → graph 与连招。
7. 用 debug 看 trace
给技能加 debug: true，控制台会打出分阶段 trace，能精确定位卡在哪一步：
[QI] [EVENT] [PARSE] [ROUTE] [GATE] [EXEC] [POST] [FALLBACK]| 标签 | 阶段 |
|---|---|
[EVENT] | 收到触发事件 |
[PARSE] | 输入归一为 payload |
[ROUTE] | graph 路由选节点 |
[GATE] | 门控校验（卡这里就是被门控拦下） |
[EXEC] | 交 MM 执行 |
[POST] | 后处理（CD / 资源扣除 / post_js） |
[FALLBACK] | 回退到 entry 节点 |
[BYPASS] | ⚠️ 架构冲突警告——出现说明有绕过管线的调用，需关注 |
debug: true仅排错用，生产环境务必关闭（高频被动会刷屏）。详见 性能与限流。
8. 桥与协议诊断
| 命令 | 看什么 |
|---|---|
/qs protocol | 协议 id / 版本、required 字段、桥可用性、MM 可用性、ready 状态、兼容性 |
/qs bridge | bridgeId、桥是否 available、最近一次请求的技能 id |
MM 装了但技能不执行时，先看这两个命令确认桥与 MM 是否就绪。
继续阅读
- 结果码 CastResult — 每个结果码的处理建议
- 消息文案速查 — 提示原文对照
- 性能与限流 — 被动刷屏 / 卡顿
- FAQ — 高频问题速答