校验报错速查（Troubleshooting）
保存 / 重载物品时，QI 会跑一整套校验（PolicyEngine 及各 validator）。本页把每一条可能出现的报错原文、触发原因、是错误（阻止保存）还是警告（允许保存）、以及修法列全。
报错出现在：
/qi reload控制台、GUI 保存提示、/qi status//qi diagnose//qi problems。
1. 物品健康检查（QinhItemDefinition.healthIssues）
物品结构完整性。全部为 错误（物品 unhealthy，列入问题清单）。
| 报错原文 | 原因 | 修法 |
|---|---|---|
id 为空 | 物品 ID 缺失 | 补顶层键 |
type 为空 | 类型缺失 | 补 type 或确认文件名是合法类型 |
material 为空 | 材质缺失 | 补 material |
sourceFile 为空 | 来源文件丢失（内部） | 重新保存 |
缺少 displayName/lore | 名和 Lore 都没有 | 至少给 display_name 或 lore 之一 |
maxStackSize 非法 | options.max_stack_size ≤ 0 | 改成 1–99 |
configVersion 非法 | 版本号 ≤ 0 | 改 update.version 为正整数 |
unknown type=$type | 类型不在 item_types.yml | 用合法类型，见 物品类型 |
unknown material=$material | 材质不是合法 Bukkit 材质 | 用合法原版材质名或外部源引用 |
2. PolicyEngine（总校验）
| 报错原文 | 原因 | 类型 |
|---|---|---|
变量键 '$key' 违反 ICVM 红线 | 变量键用了语义保留字（见 §8） | 错误 |
物品 $id ($sourceFile) 内联 actions 无法解析 | 内联 actions 块解析失败（缩进 / 格式错） | 错误 |
「内联 actions 无法解析」最常见原因是 缩进错位：
actions块必须与material/type同级，错一格整段失效。
3. 资源包字段校验（ResourcePackValidator）
全部为 错误。详见 资源包 → 校验约束。
| 报错原文 | 原因 |
|---|---|
resource_pack.custom_model_data 不能为负数 ($cmd) | CMD < 0 |
resource_pack.model 不能为空字符串 | model 空白 |
resource_pack.model 需 namespace:path 格式，got '$trimmed' | model 缺命名空间（无冒号） |
resource_pack.model 不能含空格 | model 含空格 |
resource_pack.model 禁止与状态/变量绑定 ($deny) | model 含禁止子串 { } $ star tier layer |
resource_pack 含禁止字段 $forbidden — 仅允许 custom_model_data / model | resource_pack 出现非法键 |
resource_pack 仅允许两个键：custom_model_data、model。
4. 资源包隔离扫描（ResourcePackReferenceScanner）
全部为 错误，前缀 [RP_POLICY]。设计意图：模型外观必须静态、不能随物品状态变化。
| 报错原文 | 原因 |
|---|---|
[RP_POLICY] ResourcePack cannot reference ICVM variables — $field: '...' | model 含 { } % ${ 或变量引用 |
[RP_POLICY] ResourcePack cannot bind layers — $field: '...' | model 含层 token：layer/layers/patch/patch_pack/layerstack/write_domain/instance/runtime/compiled/compile_epoch |
[RP_POLICY] ResourcePack cannot depend on actions — $field: '...' | model 含动作 token：action/actions/trigger/triggers/handler/refs/dispatch/cooldown/routing |
[RP_POLICY] ResourcePack cannot contain conditional rendering — $field: '...' | model 含条件 token：if/when/unless/condition/switch/random/weight |
5. 动作引用校验（ActionRefDeclarationValidator）
| 报错原文 | 原因 | 类型 |
|---|---|---|
ActionTable id 不能为空 | 动作表无物品 ID | 错误 |
trigger '$trigger' 无 refs | 触发器没配处理器 | 警告 |
trigger '$trigger' ref[$i] 缺少 handler | ref 缺 handler | 错误 |
trigger '$trigger' ref[$i] handler 不能含空格 | handler 含空格 | 错误 |
trigger '$trigger' ref[$i] handler 建议使用 namespace:id 格式（如 qinhskills:cast） | handler 无冒号前缀 | 警告 |
trigger '$trigger' ref[$i] handler '...' — QinhSkills 未加载，runtime 将为 HANDLER_UNAVAILABLE | 用了 qinhskills:cast 但 QS 未装 | 警告 |
trigger '$trigger' ref[$i] handler '...' 未注册 — runtime 将为 HANDLER_UNAVAILABLE | handler 未注册 | 警告 |
警告不阻止保存，但运行时该处理器会返回
HANDLER_UNAVAILABLE。处理器列表见 处理器。
6. Provider 校验（ProviderDeclarationValidator）
全部为 错误。
| 报错原文 | 原因 |
|---|---|
providers.$id 含非载体键 $illegal — 仅允许 [value, raw, data, payload] | provider 用了非法载体键 |
providers.$id 载荷为空 | provider 载荷为空 |
允许的载体键：value / raw / data / payload。详见 Provider 与桥。
7. 动作路由红线（ActionRoutingPolicy）
| 报错原文 | 原因 | 类型 |
|---|---|---|
[QinhItems] Action 路由红线: trigger '$trigger' 禁止字段 $forbidden — 只允许 trigger→refs/cooldown/conditions；复杂流程(if/else/when/switch…)请放 Handler 内 | 触发器出现逻辑字段 | strict: true 阻止，false 仅警告 |
禁止字段（FORBIDDEN_TRIGGER_KEYS）： if else when unless switch match filter require rules flow chain pipeline logic tree variables layer providers priority weight random
复杂逻辑请开发处理器。
8. 层语义红线（LayerSemanticGuard）
变量键不能复用「战斗语义」保留字（防破坏平衡）。
| 报错原文 | 原因 |
|---|---|
[QinhItems] Layer 红线: 禁止语义变量键 '$key' ($context)。请用 star/quality 等状态键。 | 变量键命中拒绝列表 |
[QinhItems] Layer 红线: 可疑语义键 '$key' ($context) | 变量键含 attack（除 attack_count） |
拒绝列表（SEMANTIC_KEY_DENYLIST）： attack_damage attack damage crit critical crit_rate crit_damage defense armor health hp mana mp physical_attack magic_attack element fire ice lightning skill skills ability abilities strength dexterity intelligence vitality attack_speed movement_speed lifesteal
想表达品质 / 星级，用
star/quality等状态键，别用属性名当变量键。属性请走providers.ap。
9. 写域违规（WriteDomainPolicy）
strict: true（默认）为错误，false 为警告。三个域：INSTANCE / LAYER / RUNTIME，详见 层与装配 → 写域策略。
| 报错原文 | 原因 |
|---|---|
runtime owner 不能为空 | 运行时写入 owner 空 |
owner '$o' 保留给 instance 域（give/init）；runtime 请用 qi_admin / qi_ui / buff_* | 运行时用了 instance 保留 owner |
owner '$o' 属于 layer 系统域；请用 QinhItemsAPI.assembly().applyLayerPatch() | 运行时用了 layer 域 owner |
runtime override 只允许 UI/admin/临时 buff owner（如 qi_admin, qi_ui, buff_*） | 运行时 owner 不匹配 |
layer id / owner 不能为空 | 层写入缺 owner/id |
layer owner '$o' 不能来自 runtime 域（ui/admin/buff） | 层用了 runtime owner |
layer owner 不能使用 instance 保留 owner '$o' | 层用了 instance 保留 owner |
layer 只允许系统插件 owner/id（forge/gem/enchant/strengthen 等，见 write-domains.layer-owners） | 层 owner 不匹配 |
默认 owner / 前缀：
| 域 | owner | 前缀 |
|---|---|---|
| RUNTIME | qi_admin qi_ui admin | buff_ temp_ ui_ |
| LAYER | strengthen forge gem enchant socket refine embed upgrade | sys_ layer_ |
| INSTANCE 保留 | qi_core give init template | — |
10. 排错速查：最常见 8 类问题
- 动作不生效 / 整段失效 → 缩进错位，
actions必须与material同级；改完/qi reload。 - 变量键报红线 → 别用
attack_damage等属性名当变量键，用star/quality。 - resource_pack 报错 → 只能有
custom_model_data/model，model不能含变量 / 层 / 条件。 - provider 报错 → 载体键只能是
value/raw/data/payload，且非空。 - handler 警告 → 用
命名空间:id格式；qinhskills:cast需装 QinhSkills。 - 触发器禁止字段 → 别在 YAML 写 if/switch，逻辑放处理器。
- 写域违规 → 改物品状态分清是 instance / layer / runtime 域，用对应 API。
- unknown type / material → 类型查
item_types.yml，材质用合法原版名。