| name | orryx-station-mechanic-skill |
| description | Design and review Orryx station YAML mechanics for event-driven combat and passive behavior. Use for Event, Weight, Priority, Async, Actions, damage Pre/Post direction, shields, flags, cooldown handoff, accumulated damage, and Bukkit thread-safety checks. |
| license | MIT |
| activation | {"command":"/orryx-station-mechanic-skill","intents":["create or review an Orryx station","wire attack or damaged events","implement passive, shield, flag, or accumulated-damage mechanics"]} |
| metadata | {"author":"NarraFork","version":"1.1.0","created":"2026-07-13T00:00:00.000Z","last_reviewed":"2026-07-13T00:00:00.000Z","review_interval_days":90} |
| provenance | {"repository":"Orryx","sources":["core/station/stations/StationLoader.kt","core/station/stations/StationLoaderManager.kt","example/Orryx/stations"],"generated_for":"orryx-creation-suite"} |
/orryx-station-mechanic-skill
创建或审查 Orryx stations/*.yml 中转站。目标是把事件方向、执行阶段、权重、线程和 Kether 副作用写成可验证的配置，而不是仅拼接一段 Actions。
输入
优先读取用户提供的事件名、触发方向、阶段、职业/技能 ID、Flag、伤害类型、依赖资源和现有 YAML。信息不足时采用最保守的同步、NORMAL 优先级和显式方向，并在报告中列出假设。
必须建立的语义
- 事件方向：
Player Damage * 以攻击者为脚本主体；Player Damaged * 以受击者为主体。攻击加成使用前者，护盾减伤使用后者。
- 阶段：
Pre 用于改伤、取消事件和预判；Post 用于记录已结算伤害、收集目标或后续反馈。不要在 Post 假装撤销已发生的伤害。
- 执行顺序：同一 Event 与 Priority 内，
Weight 越大越先执行；Priority 必须为 Bukkit 的 LOWEST/LOW/NORMAL/HIGH/HIGHEST/MONITOR。
- 脚本契约：顶层必须有
Options.Event 和 Actions。按需加入 BaffleAction、IgnoreCancelled、Variables、Async。
- 取消状态：读取伤害结果的逻辑先判断
&isCancelled；需要取消时在 Pre 使用 event cancelled true。
机制模式
Passive（被动）与攻击修正
参考“拳修内劲”：监听 Player Damage Pre，读取职业后修改 &event[damage]。加成公式必须说明是加法、乘法还是固定段，避免把最大生命等单位混入未标注比例。
护盾与受击修正
参考“凝灵盾受击”：监听 Player Damaged Pre。护盾足够时取消事件并扣盾；不足时只扣除剩余盾值；破盾分支只执行一次，并明确 Flag 的 remove、timeout 与零值语义。反震范围必须排除 @self、盔甲架和队友。
Flag 生命周期与冷却交接
参考“刹那冷却”：监听 Flag Change Post，在 newFlag == null 时设置技能冷却，确保持续态结束后才进入冷却。不要在创建 Flag 时提前结算。
累计伤害
参考“咒恶之锋”：监听 Player Damage Post，跳过取消事件，将 defender 合入容器并累加已结算 &event[damage]。容器、累计值与主 Flag 必须有一致的创建、读取和清理周期。
Bukkit 线程安全
Options.Async: true 会把站点脚本放入插件协程作用域；它不等于所有 Bukkit API 都线程安全。涉及事件取消/改写、实体/世界、背包、声音、粒子、移动、伤害调用或 Bukkit 对象访问时保持同步。只有确认整个动作链为异步安全的纯计算或异步 I/O 时才启用 Async；数据库与 Redis I/O 由对应异步 API 处理，不能阻塞事件线程。
工作流
- 解析目标机制并确定攻击者/受击者方向。
- 选择 Pre 或 Post，再确定 Priority、Weight、IgnoreCancelled 与 Async。
- 建立 Flag、容器、累计值和冷却的生命周期表。
- 编写
Options 与 Actions，保留 Orryx Kether 语法和事件字段。
- 检查事件阶段是否允许该副作用，检查线程风险和重复触发。
- 运行：
py -3 scripts/run_pipeline.py --input assets/request.example.json --output station-report.json。
- 仅输出建议文件与验证报告；除非上层编排器明确进入 materialize 阶段，否则不写入服务器配置，也不重载服务器。
输出要求
输出应包含固定组件 station、状态、错误与警告、事件方向、阶段判断、线程风险、引用 ID，以及建议的 YAML artifact。任何 error 都必须阻止 materialize。
禁止事项
- 不把
Player Damage 与 Player Damaged 当同义词。
- 不在 Post 阶段修改或取消已结算伤害。
- 不在异步站点中直接调用主线程敏感 Bukkit 操作。
- 不忽略取消状态后继续累计伤害。
- 不生成不存在的事件字段、动作或真实密钥。
- 不自动执行 Orryx/服务器重载。
详细字段见 references/contract.md，依据见 references/source-evidence.md。
