触发器（TriggerType 与 active_triggers）
这一页讲清楚**「玩家这一下到底算哪种触发」**：
- TriggerType —— 触发的「种类」（右键 / 左键 / 潜行右键 / 长按 / 被动…），共 15 种（服主主要用前 10 个点击类，其余为内部用途）。
- active_triggers —— 触发的「来源」（物品按键 / 技能槽快捷键 / 命令 / API），共 4 种，缺省
QI_ACTION。 - trigger.primary —— 技能的主触发，它必须出现在 graph 入口节点的
triggers里，否则放不出。 - atom 映射 —— QinhItems 物品按键（atom）如何对上 TriggerType。
💡 一句话先记住：「来源」决定这下输入从哪进 QS（active_triggers），「种类」决定它走哪个技能（TriggerType）。 两者各管一头，互不替代。
🖼️ [图片占位] 一张「物品按键 → QI 发出 atom → QS 归一成 TriggerType → 命中 graph 节点」的流程图 · 建议
assets/trigger-pipeline.png
一、TriggerType 全集（15 种）
TriggerType 是 QS 内部对「这一下输入是什么动作」的统一枚举。它出现在三个地方：
- 技能定义的
trigger.primary（主触发）； - graph 节点的
triggers:（这个节点接收哪些动作）； - 被动技能内部（被动统一记为
PASSIVE）。
| TriggerType | 含义 | 典型用途 |
|---|---|---|
RIGHT_CLICK | 右键 | 最常用的主动技能触发 |
LEFT_CLICK | 左键 | 近战 / 普攻类技能 |
SHIFT_RIGHT_CLICK | 潜行 + 右键 | 同一物品的「第二套」技能 |
SHIFT_LEFT_CLICK | 潜行 + 左键 | 同上，再分一套 |
SHIFT_TOGGLE | 潜行切换（按下/松开潜行） | 开关 / toggle 类技能 |
DOUBLE_SHIFT_TOGGLE | 潜行切换双击（预留） | 暂未实装，预留枚举 |
DOUBLE_RIGHT_CLICK | 双击右键 | 冲刺、闪避等「快速两下」 |
DOUBLE_LEFT_CLICK | 双击左键 | 同上，左键版 |
HOLD_RIGHT_CLICK | 长按右键 | 蓄力 / 吟唱起手 |
HOLD_LEFT_CLICK | 长按左键 | 持续型起手 |
CI_TEST | 内部测试 | 🔧 内部回归测试用，服主不需要写 |
COMMAND | 命令 | 🔧 内部/非物品按键：/qs cast 触发 |
API | 接口 | 🔧 内部/非物品按键：插件代码调用触发 |
PASSIVE | 被动 | 🔧 内部/非物品按键：被动技能内部统一用它（不写在 primary 里） |
UNKNOWN | 未知 / 内部回退值 | 🔧 内部：配置里不要用，仅作识别失败时的兜底 |
🔧 标注「内部/非物品按键」的 5 个（
CI_TEST/COMMAND/API/PASSIVE/UNKNOWN）不是给物品按键写的，服主主要用前 10 个点击类触发。UNKNOWN是识别失败时的内部回退值，配置里绝不要写。
⚠️ 大小写敏感，必须全大写、原样照抄。写成
right_click会被当作未知触发（归一为UNKNOWN）。
怎么挑 TriggerType？
- 单技能物品：
RIGHT_CLICK就够了。 - 想在一把武器上塞两个技能：右键放 A、潜行右键放 B →
RIGHT_CLICK+SHIFT_RIGHT_CLICK。 - 想做「按一下开、再按一下关」的光环 / buff：用
SHIFT_TOGGLE，技能cast_mode: toggle。 - 蓄力读条技能：起手用
HOLD_RIGHT_CLICK，技能cast_mode: channel。
二、active_triggers —— 主动触发源（4 种）
TriggerType 回答「这下是什么动作」，active_triggers 回答「这下从哪儿来」。它是技能 yml 里的一个列表，缺省值是 [QI_ACTION]（即「只接受 QinhItems 物品按键」）。
| 来源 type | 含义 | 怎么触发 | 备注 |
|---|---|---|---|
QI_ACTION | QinhItems 物品按键 | 玩家拿着带技能的 QI 物品按键 | 默认、最常用，缺省就是它 |
KEY_SLOT | 技能槽快捷键 | 玩家用技能槽快捷键放槽里的技能 | 需配合 slots.active_count（config.yml，默认 5） |
COMMAND | 命令施放 | /qs cast <技能> | 测试 / 命令桥（NI、MI 等）走这里 |
API | 接口调用 | 插件代码调用 QinhSkillsAPI | 开发者集成 |
# 缺省写法：等同 active_triggers: [QI_ACTION]，可以整段不写
active_triggers:
- type: QI_ACTION # 物品按键触发（默认）
# 例：同时允许「物品按键」和「技能槽快捷键」两种来源
active_triggers:
- type: QI_ACTION
- type: KEY_SLOT💡 大多数物品技能整段不写
active_triggers即可——默认QI_ACTION就是你要的。只有要接技能槽 / 命令桥 / API 时才需要显式列出。
三、atom 映射 —— 物品按键怎么变成 TriggerType
QinhItems 物品上配的是 atom（按键原子）。物品按下后，QI 把 atom 发给 QS，QS 再把它归一成一个 TriggerType，去匹配技能与 graph。
| QI 物品 atom | 归一成的 TriggerType |
|---|---|
left_click | LEFT_CLICK |
right_click | RIGHT_CLICK |
shift_left_click | SHIFT_LEFT_CLICK |
shift_right_click | SHIFT_RIGHT_CLICK |
shift_toggle | SHIFT_TOGGLE |
经验法则：物品的 atom 最好对上技能的 trigger.primary。
- atom 对得上 primary：直接命中入口节点，一切正常。
- atom 对不上 primary：QS 仍会回退到入口节点把技能放出来（不会哑火），但「右键 / 左键分别放不同技能」的精细分支就指望不上了。
🔌 物品侧具体怎么配 atom，见 对接 QinhItems。这里只需记住映射关系。
四、trigger.primary 与 graph 入口节点的关系（重点）
这是新手最容易踩的坑。两条铁律：
trigger.primary必须出现在 graph 入口节点的triggers:列表里。- 对不上就放不出（或回退行为不符预期）。
来看正反两个例子。
✅ 正确：primary 在入口节点 triggers 内
skills/combat/blade_slash.yml（节选自自带示例）：
trigger:
primary: LEFT_CLICK # 主触发：左键
graph:
entry: blade_slash # 对应 graph 的入口节点名对应 graphs/combat/blade_slash.graph.yml：
graph_id: blade_slash
entry: blade_slash
nodes:
blade_slash: # ← 入口节点
skill_id: blade_slash
mythic_skill: blade_slash
require_state: IDLE
triggers:
- LEFT_CLICK # ✅ primary(LEFT_CLICK) 在这里，对得上 → 能放❌ 错误：primary 没出现在入口节点
# 技能里：
trigger:
primary: RIGHT_CLICK # 主触发写的是右键
# 但 graph 入口节点：
fire_wave:
triggers:
- LEFT_CLICK # ❌ 只接左键，右键没列进来 → primary 落空⚠️ 改完触发记得
/qs reload，并用/qs info <技能>复核。
五、完整小例子：一把武器两套技能
目标：右键放火焰波、潜行右键放刃斩。
# 技能 fire_wave：右键
trigger:
primary: RIGHT_CLICK
graph:
entry: fire_wave对应 graph 入口节点同时列两种触发，靠 skills 路由分流（见 config.yml 的 skills: 段）：
# config.yml —— 按 TriggerType 分支到不同技能
skills:
fire_wave:
RIGHT_CLICK: fire_wave # 右键 → 火焰波
LEFT_CLICK: blade_slash # 左键 → 刃斩
default: fire_wave # 兜底物品侧给同一把武器配 right_click 和 shift_right_click 两个 atom，分别对上两个技能的 primary 即可。
✅ 自检清单
- [ ]
trigger.primary用的是全大写的合法 TriggerType。 - [ ] 该 primary 出现在 graph 入口节点的
triggers:里。 - [ ] 物品 atom 与 primary 对得上（
right_click↔RIGHT_CLICK）。 - [ ] 若要接技能槽 / 命令桥，已显式写
active_triggers。 - [ ] 改完执行了
/qs reload，并/qs info复核。