概览：QI 是什么
一句话定位
QinhItems（QI）是一个数据驱动的自定义物品引擎：服主用 YAML（或游戏内 GUI）描述「一件物品长什么样、有什么属性、按什么键触发什么效果」，QI 负责把这份描述编译成真正的 Minecraft ItemStack，并在运行时维护它的显示、属性、动作、绑定状态。
如果你用过 MMOItems，可以这样类比：
| MMOItems 概念 | QI 对应 | 备注 |
|---|---|---|
| Item Types | 物品类型 | QI 的类型自带「能力矩阵」 |
| Stats | 属性 providers.ap / 变量 | 数值交给 AttributePlus |
| Abilities | 动作系统 | 触发器 + 处理器 |
| Tiers | 品质 Tier | 权重抽取 + 容量 |
| Gem Stones | 宝石孔 | 双后端 |
| Sets | 套装 | 按件数激活 |
/mi 命令 | /qi 命令 | |
| Editor GUI | 编辑器 GUI |
但 QI 不是 MMOItems 的复刻。它有几个根本性的设计差异，理解它们能帮你少踩坑。
QI 的三条设计哲学
1）QI 不管「数值怎么算」，只管「数值挂在物品上」
QI 本身不计算战斗伤害。它把属性以一段 JSON（providers.ap.value）的形式挂在物品上，装备时交给 AttributePlus（AP）去真正作用到玩家身上。这意味着：
- 「攻击力 = 22」这种数字的含义由 AP 决定（你在 AP 里定义了什么叫"物理伤害"）。
- QI 只负责：把物品上的属性读出来 → 格式化 → 交给 AP，以及在物品 Lore 上显示它们。
- 没装 AP？QI 进入「纯物品库模式」，物品照样能造、能触发动作、能显示，只是数值不上身。
详见 属性与数值。
2）物品 = 模板（Definition） + 实例数据（Instance） + 层（Layers）
一件 QI 物品在内存里由三部分叠加而成：
- 模板（Definition）：YAML 里写死的那份「设计图」，所有同 ID 物品共享。
- 实例数据（Instance）：写在这一个具体 ItemStack 的 NBT 里的、每件不同的状态——例如随机滚出来的数值、绑定者、种子。
- 层（Layer）：创建之后追加上去的「补丁」——例如打孔、镶嵌、强化、附加词缀。层有归属域（owner domain）和优先级，受策略保护。
最终展示给玩家的物品，是这三者经过**装配管线（Assembly Pipeline）**合成的结果。开发者改物品时要分清自己在改哪一层，详见 层与装配。
3）配置层（YAML）只描述「是什么」，逻辑交给处理器（Handler）
QI 的动作系统故意不支持 YAML 里写 if / else / switch / 条件分支。一个触发器底下只是「按顺序执行一串处理器引用」。需要复杂逻辑？由开发者实现一个动作处理器（QinhActionHandler），把逻辑写在 Kotlin/Java 里，YAML 只负责引用它并传 payload。
这条边界让配置保持简单、可被 GUI 完整编辑，同时把复杂度收纳进代码。详见 动作系统概览 与 动作处理器开发。
它能做什么 —— 典型场景
- 造一把左键召唤雷鸣、3 秒冷却、消耗 1 红石的史诗剑。
- 造一套穿 4 件触发狂暴、附加 +15 物理伤害与急迫 II 的战士套装。
- 造一件绑定后无法交易、死亡不掉落的灵魂武器。
- 让武器带 2 个宝石孔，玩家用 Legendinlay 镶嵌宝石。
- 配一张随机掉落表：按品质权重抽稀有度，再按容量抽词缀，生成千变万化的装备。
- 从旧的 MMOItems 配置批量导入到 QI。
它在秦淮生态里的位置
QI 是秦淮系列的「物品底座」。与它协作的兄弟模块：
- QinhCoreLib（QCL） — 统一底层库（物品源管理、属性管道、动作契约）。QI 硬依赖它。
- QinhSkills（QS） — 技能引擎。物品动作里的
qinhskills:cast把技能释放交给 QS。 - AttributePlus（AP） — 第三方属性插件，QI 的数值后端。
🖼️ [图片占位] 秦淮生态模块关系图（QCL 底座、QI 物品、QS 技能、AP 数值） · 建议
assets/ecosystem-diagram.png