概览：QS 是什么、为什么要它
一句话定位
QinhSkills（QS）是一个状态驱动的「技能大脑」：玩家这一下按键，到底能不能放技能、放哪个技能、放之前要过哪些关——解锁、冷却、充能、消耗、目标索敌、连招、吟唱读条、被动触发，全在 QS 里判定。
但 QS 故意不画粒子、不算伤害、不做位移。判定通过之后，真正"放出来是什么样"交给 MythicMobs（MM） 执行，伤害数值交给 AttributePlus（AP） 这类属性插件结算。
一句话记住分工：物品负责"按下"，QS 负责"能不能放"，MythicMobs 负责"放出来啥样"，属性插件负责"打多少伤害"。
🖼️ [图片占位] 一张从按键到火焰特效的连续帧（按键 → QS 门控 → MM 表现） · 建议 assets/overview-pipeline-frames.png
四方分工 —— 谁管什么
很多人第一次看 QS 会问："放技能不就是 MythicMobs 的事吗，为什么还要 QS？" 答案是：放技能其实被拆成了四个互不重叠的职责，每个插件只干自己最擅长的那一块。
| 角色 | 谁来做 | 负责 | 坚决不做 |
|---|---|---|---|
| 按下 | 物品插件（QinhItems / NeigeItems…） | 把"玩家右键了这把剑"变成一个标准触发信号 | 不决定放哪个技能、不管冷却 |
| 能不能放 | QinhSkills（本插件） | 解锁 / 冷却 / 充能 / 消耗 / 目标 / 连招 / 吟唱 / 被动 —— 所有"门" | 不画粒子、不算伤害、不做位移 |
| 放出来啥样 | MythicMobs | 粒子、位移、击退、表现、机制本体 | 不管状态机、不管连招、不管触发解析 |
| 打多少伤害 | AttributePlus 等属性插件 | 伤害数值结算（在 MM 那侧） | 不管技能流程 |
🔑 核心铁律：QS 和 QI 都【不内置属性 / 伤害】。 你在 QS 里永远写不出"造成 30 点伤害"这句话——伤害数值由 AttributePlus 在 MM 那侧结算。QS 只决定"这一刀能不能挥出去"。
这四层像一条流水线：物品把信号递给 QS，QS 判完所有关卡，把"放 fire_wave、目标是那只僵尸、威力参数 power=1.2"这份执行计划递给 MM，MM 负责把它演出来，AP 负责算这一下打了多少。
如果你用过 MythicMobs
最容易混淆的一点：QS 不是 MythicMobs 的替代品，而是驱动 MM 的"大脑"。 它们是上下游，不是竞争关系。
| 你想做的事 | 光用 MythicMobs | 加上 QS |
|---|---|---|
| 一个技能的粒子、伤害、位移 | ✅ MM 本职，QS 不碰 | 还是 MM 做 |
| 右键放技能 | 要自己接 Skill trigger、自己判输入 | QS 统一接管输入 |
| 解锁 / 等级 / 冷却 / 充能 | MM 有 cooldown，但解锁、充能层、冷却组要自己拼 | QS 内置一整套门控 |
| 自动锁最近的怪当目标 | 要写 targeter + 各种过滤 | QS 一行 target: NEAREST |
| 右→右→左 连招放终结技 | 要自己写状态记录与序列匹配 | QS 状态机 + 连招原生支持 |
| 蓄力 2 秒读条、位移打断 | 要自己拼 bossbar 与打断逻辑 | QS 一个 cast_mode: channel |
| 受伤自动反击 | 要写 onDamaged 触发 + 限流 | QS 被动触发 + 内置限流 |
可以这样类比：
| MythicMobs 概念 | QS 对应 | 备注 |
|---|---|---|
| Skill（技能本体） | 仍是 MM Skill | QS 不替它，只调用它 |
Trigger（~onAttack 等） | QS 的输入归一 + 被动触发 | QS 统一收口再分发 |
Targeter（@NearestPlayer…） | target: NEAREST / LOOK … | QS 选好目标当 @Target 传给 MM |
| Cooldown | QS 门控里的冷却 / 充能 / 冷却组 / GCD | 比 MM 原生更细 |
| Conditions | QS 的 conditions: 声明式条件 | 放行前校验 |
💡 简单说：MM 是"手"，QS 是"脑"。 你依然在 MM 里写技能的视觉与机制；QS 站在物品和 MM 之间，决定这只手什么时候、对谁、以什么状态出招。
QS 的三条设计哲学
理解这三条，你就理解了 QS 为什么长这样，也能少踩坑。
1）QS 只管「逻辑」，不管「表现」与「数值」
QS 本身不画一个粒子、不掉一点血、不移动一格。它输出的是一份执行计划：放哪个 MM 技能、目标是谁、带哪些变量参数。表现交给 MM，伤害交给属性插件。
- 「这一刀打多少」由 AttributePlus 决定（在 MM 那侧结算）。
- QS 只负责：判定能不能放 → 选好目标 → 把参数透传给 MM。
- 没装 MM？QS 照常做所有门控判定，只是技能"放出来"退化成一条占位消息
[QinhSkills] 技能名——看到它就说明 QS 这侧通了。
这条边界和 QI 的"不管数值怎么算，只管数值挂在物品上"是同一种思路：职责单一，谁的活谁干。
2）所有触发，都汇入同一条运行管线
无论技能是被物品按键触发、被命令 /qs cast 触发、被 API 触发，还是被被动事件（受伤 / 击杀 / 潜行…）触发，它们都进入同一条管线：
输入 → 状态机(State) → 图解析(Graph)+连招(Combo) → 执行计划(Plan) → 门控(Gate) → 执行(MM) → 后处理(Post)好处是：冷却、充能、连招、目标这些规则只写一遍，对所有触发源一视同仁。你不用为"命令放"和"物品放"维护两套逻辑。详见 核心概念。
3）技能图（graph）+ 状态机，让连招与续段可编排
每个技能除了"技能定义"，还有一张 graph（执行图），回答："在某个状态下按了某个键，走哪个节点、放哪个 MM 技能。"
配合一个 6 状态的状态机（空闲 / 施放中 / 连招窗口 / 恢复 / 被封锁 / 中断），QS 能把"右键起手 → 连招窗口内再右键续段 → 右右左触发终结技"这种有时序的玩法用声明式 YAML 编排出来，而不用你手写一堆状态判断。详见 核心概念 与 graph 与连招。
它能做什么 —— 典型场景
这些都是 QS 开箱就能编排的玩法（表现部分由你在 MM 里补）：
- 左键自动锁最近的怪放刃斩 ——
target: NEAREST+filter: MONSTERS，QS 替你选目标。 - 蓄力 2 秒读条放大招 ——
cast_mode: channel，带 bossbar 进度、位移 / 受伤打断。 - 潜行右键瞬移 —— 位移技不吃全局冷却（
gcd.ignore: true），手感跟手。 - 受伤自动反击 ——
ON_DAMAGED被动触发，内置限流防刷。 - 右→右→左 连招放炎爆终结技 —— graph 里写
inputs: [RIGHT_CLICK, RIGHT_CLICK, LEFT_CLICK]，连招窗口内按出序列触发finalize_skill。
🖼️ [图片占位] 四宫格示意：索敌刃斩 / 蓄力读条 / 潜行瞬移 / 连招终结技 · 建议 assets/overview-scenarios.png
每一个场景背后都是同一句话：QS 决定"能不能放、放哪个、过哪些关"，MM 决定"放出来什么样"。
它在秦淮生态里的位置
QS 是秦淮 RPG 生态的「技能底座」。与它协作的兄弟模块：
| 模块 | 角色 | 与 QS 的关系 |
|---|---|---|
| QinhCoreLib（QCL） | 统一底层库 | QS 硬依赖它，没装 QCL 则 QS 不启用 |
| QinhItems（QI） | 自定义物品引擎 | 物品动作里的 qinhskills:cast 把按键交给 QS（软依赖） |
| QinhSkills（QS） | 技能引擎（本插件） | 决定能不能放、放哪个、过哪些关 |
| MythicMobs（MM） | 技能执行后端 | QS 把执行计划交给它演出（软依赖） |
| AttributePlus（AP） | 属性 / 伤害结算 | 在 MM 那侧算伤害（软依赖） |
🖼️ [图片占位] 秦淮生态模块关系图（QCL 底座、QI 物品、QS 技能、MM 执行、AP 数值） · 建议
assets/ecosystem-diagram.png
注意"硬依赖"和"软依赖"的区别：QCL 必须先装，否则 QS 直接不启用；其余（QI / MM / AP / PlaceholderAPI）都是软依赖，缺了也能启动，只是对应能力降级。具体降级表见下一页 安装。