🔬 诊断与协议

上一页：脚本 API　·　下一页：数据存储

技能"放不出来"或"放了没效果"时，QS 提供两条诊断命令（/qs protocol、/qs bridge）和一套 debug trace 日志，配合 SkillRuntimeProtocol 协议层定位问题。本章讲清楚 QS ↔ MythicMobs 的协议契约、诊断输出怎么读、trace 各阶段含义。本文档对应 QS 1.0.22。

QS 只有一条运行时管线。trace 反映的是这一条管线的各阶段，不存在多套链路。

1. 协议层：`SkillRuntimeProtocol`

QS → MM 的转发隔着一层协议，明确"身份 / 版本 / 必填字段 / 是否可用 / 失败原因"：

常量 / 方法	值 / 作用
`PROTOCOL_ID`	`"qinhskills:skill_cast_request"`
`PROTOCOL_VERSION`	`1`
`requiredFields()`	`{skillId, casterId}`
`isAvailable()`	桥 id 非空且 MythicMobs 可用
`compatibility()`	`OK` / `BRIDGE_MISSING` / `MYTHIC_MISSING`
`validate(request)`	校验请求，返回 `List<String>` 问题清单（空列表=合法）
`describe()`	返回 `SkillRuntimeProtocolState` 快照

兼容判定逻辑

桥不可用            → BRIDGE_MISSING
桥可用但 MM 不可用   → MYTHIC_MISSING
都可用              → OK

请求：`SkillCastRequest`

kotlin

data class SkillCastRequest(
    val skillId: String,
    val casterId: UUID,
    val targetId: UUID?,
    val context: Map<String, Any>,
)

validate 的三条检查：

skillId 非空白
casterId 不是零 UUID（UUID(0,0)）
context 非空

唯一执行出口

协议校验通过后，真正"放出来"只有一条出口：

MythicExecutor.cast → MythicBukkit apiHelper.castSkill

QS 自己不画粒子、不算伤害。SUCCESS 只代表 QS 把请求成功交给了 MM；具体表现由 MM 技能决定。MM 没装时退化为占位消息 [QinhSkills] 技能名。

2. `/qs protocol`

打印协议层快照（describe()）：

[QS] protocol=qinhskills:skill_cast_request@v1
[QS] required=[skillId, casterId]
[QS] bridge=<bridgeId>, bridgeAvailable=true, mythic=true, ready=true
[QS] compatibility=OK

逐行解读：

字段	含义	异常时
`protocol`	协议 id + 版本	—
`required`	必填字段	—
`bridge`	桥实现 id	空串=桥没注册好
`bridgeAvailable`	桥是否可用	`false` → `BRIDGE_MISSING`
`mythic`	MM 是否可用	`false` → `MYTHIC_MISSING`
`ready`	整体就绪（桥 && MM）	`false`=技能放不出真实效果
`compatibility`	综合兼容码	见上表

看到 compatibility=MYTHIC_MISSING：QS 这侧通了，去装 / 排查 MythicMobs。看到 BRIDGE_MISSING：桥本身没起来，先 /qs reload 重新同步桥。

3. `/qs bridge`

打印桥的实时状态：

[QS] bridgeId=<id>
[QS] bridgeAvailable=true
[QS] lastRequest=fire_wave

字段	含义
`bridgeId`	当前桥实现标识
`bridgeAvailable`	桥是否可用
`lastRequest`	最近一次转发的技能 id（没有则 `null`）

lastRequest 很实用：玩家按了键说没反应，看这里有没有刷新成对应技能 id —— 有=请求到了桥（问题在 MM 侧）；没变=请求根本没走到桥（问题在门控/路由/触发）。

4. debug trace 日志

在 config.yml 开启：

yaml

debug: true

开启后每次释放会按管线阶段打印带标签的 trace，便于看清"卡在哪一步"：

标签	阶段
`[QI]`	QI 侧入口（物品触发）
`[EVENT]`	`QISkillUseEvent` 网关发事件
`[PARSE]`	payload 归一、解析技能 id
`[ROUTE]`	图解析、选节点（起手/续段/连招）
`[GATE]`	门控逐项校验（解锁/冷却/充能/GCD/资源/血祭/冲突/条件/cast_mode）
`[EXEC]`	转交 MythicExecutor 执行
`[POST]`	后处理（进 CD、扣费、`post_js`）
`[FALLBACK]`	走了 `QiListener` 兜底路径
`[BYPASS]`	始终记录（不受 debug 开关影响），表示跳过某段的原因

[BYPASS] 无论 debug 是否开启都会打，专门记录"为什么某段没执行"。排查"技能莫名其妙不放"时优先看它。

典型排查路径

现象	看哪段 trace
按键完全没反应	`[QI]` / `[EVENT]` 是否出现
出现 EVENT 但没 EXEC	`[GATE]` —— 哪一项门控拦下了
EXEC 了但没特效	`/qs bridge` `lastRequest` + `/qs protocol` 的 `mythic`
连招接不上	`[ROUTE]` —— 节点 `require_state` 是否匹配
占位符返回空	该技能档案状态是否存在（见数据存储）

5. 命令总览（与诊断相关）

QS 共 11 个子命令（/qs，别名 /qskills /qskill），诊断相关的是：

命令	权限	说明
`/qs reload`	`qinhskills.admin`	重载定义/graph/路由 + 同步 MM 桥
`/qs protocol`	`qinhskills.use`	协议层快照
`/qs bridge`	`qinhskills.use`	桥状态 + `lastRequest`
`/qs info <技能>`	`qinhskills.use`	技能定义详情
`/qs list [玩家]`	`qinhskills.use`	列技能与解锁/等级/冷却

⚠️ 没有 /qs test、/qs gen 之类命令。文中标注「计划 / 内部」的能力当前未对外开放。诊断只靠 /qs protocol、/qs bridge 和 debug: true 的 trace。

继续阅读

事件 — trace 的 [EVENT] 阶段对应 QISkillUseEvent
API — CastResult 各码与门控阶段对应
数据存储 — 冷却/充能状态来源

🔬 诊断与协议 ​

1. 协议层：SkillRuntimeProtocol ​

兼容判定逻辑 ​

请求：SkillCastRequest ​

唯一执行出口 ​

2. /qs protocol ​

3. /qs bridge ​

4. debug trace 日志 ​

典型排查路径 ​

5. 命令总览（与诊断相关） ​

继续阅读 ​