跨模块对接（秦淮生态数据流）

所属：开发者　·　相关：集成 · 集成实操 · 属性与数值

QI 不是孤岛。它与 QinhCoreLib（QCL）、QinhSkills（QS）、AttributePlus（AP） 协同。本章讲它们之间的数据怎么流、职责怎么分。

一、模块职责分工

QinhCoreLib（QCL）  ── 底座：统一物品源管理、属性管道契约、动作契约
       ▲
       │ 依赖
QinhItems（QI）     ── 物品：定义/装配/动作/套装/绑定/宝石（不算数值、不施法）
       │ 透传技能          │ 交属性
       ▼                   ▼
QinhSkills（QS）    AttributePlus（AP）
  技能引擎             数值后端

模块	负责	不负责
QCL	物品源注册表、`ItemManagerAPI` 前缀解析、动作契约类型	具体物品内容
QI	物品模板 / 装配 / Lore / 动作 / 套装 / 绑定 / 宝石孔	数值计算、技能施法
QS	技能定义与释放	物品
AP	属性数值真正作用到玩家	物品

核心原则：QI 不算数值、不施法。数值交 AP，技能交 QS。

二、QI ↔ CoreLib

QI 注册成物品源

QI 启动时把自己注册进 CoreLib 的物品源系统（QinhItemsItemSource，id qinhitems，别名 qi），并注册物品模块进 ItemManagerAPI（别名 qinhitems / qi / QinhItems）。

别人通过 CoreLib 取 QI 物品

java

// 前缀解析在 CoreLib —— 任何接了 CoreLib 的插件都能这样取 QI 物品
ItemStack s = ItemManagerAPI.getHookItem("qi:demo_thunder_edge");

CoreLib 统一物品源前缀表

ItemManagerAPI.getHookItem(ref) / ItemSourceManager.parseItemReference(ref) 认下面这些前缀（ItemSourceType）。QI 物品的 material 字段、其它插件取 QI 物品，走的都是这同一套：

物品源	id	别名
原版	`vanilla`	`minecraft` / `mc` / `v` / `material` / `type`
CraftEngine	`craftengine`	`ce` / `craft-engine`
ItemsAdder	`itemsadder`	`ia`
Nexo	`nexo`	`nx`
MMOItems	`mmoitems`	`mi`
NeigeItems	`neigeitems`	`ni`
MythicMobs	`mythicmobs`	`mm` / `mythic`
MagicGem	`magicgem`	`mg` / `magic-gem`
CustomFishing	`customfishing`	`cf`
QinhItems	`qinhitems`	`qi`

引用语法（ItemReferenceParser）：

<前缀>:<物品ID>            ce:dragon_blade   /   nexo:ruby
<前缀>-<物品ID>            ce-dragon_blade（: 与 - 等价；前缀取第一个 - 之前）
<前缀>-<物品ID>::{json}    ni-blade::{"品质":"传说"}（末尾给后端传参）
mi-<类型>-<ID>            mi-SWORD-Legendary（MMOItems 特例 → SWORD:Legendary）
<无分隔>                  iron_sword（按原版 Material 解析）

诊断：ItemManagerAPI.diagnose(ref) 返回 DiagnosticResult，码含 SOURCE_NOT_FOUND（前缀没注册=插件没装）、ITEM_NOT_FOUND（源里没这 ID）、ITEM_REF_PARSE_FAILED（格式错）。服主侧见物品定义 §5.1。

关键分界

能力	在哪
`qi:id` / `qinhitems:id` 前缀解析	CoreLib 的 `ItemManagerAPI`
物品反查（item → id）、`isQinhItem`	QI 的 `QinhItemsAPI`
按 ID 生成	两边都行（CoreLib 转发给 QI，或直接 QI `assembly().build`）

所以：要 qi: 前缀解析依赖 CoreLib；要反查 / 直接生成只依赖 QI。接入路线见 API 概览。

三、QI ↔ AttributePlus

数据流

物品 providers.ap = {"attack_damage":18}
   │ ICVM 键 attack_damage ──(config.yml attribute-mapping)──► AP 名 "物理伤害"
   ▼
装备变化 → EquipmentScanner 读取 → ApBlobParser 格式化 → "物理伤害: 18"
   ▼
AttributeBackend.apply(player, "qi:equip:mainhand", lines) → AttributePlus 应用

六槽位独立源 qi:equip:<slot>，套装源 qi:set:<id>。
没 AP → NoopAttributeBackend（纯物品库模式）。

完整说明见属性与数值。

自定义属性后端

不用 AP？实现 AttributeBackend 注册，QI 就把属性交给你的系统：

kotlin

QinhCombatAPI.registerAttributeBackend(MyBackend())

四、QI ↔ QinhSkills

数据流

物品动作 / 套装 abilities 里的
   - handler: qinhskills:cast
     payload: {"skill":"fireball","level":1}
   │
   ▼
QI 动作派发 → QISkillBridge 处理器 → QinhSkills 收到技能释放请求
   │
   ▼
QS 真正施法（可能再调 MythicMobs）

QI 只声明并透传 payload，不解析技能、不施法。
链接由 QinhSkillsLinker 完成，支持晚加载（QinhSkillsEnableListener）。

链接机制见集成 → QinhSkills，接入步骤见集成实操。

五、QI ↔ Legendinlay / MagicGem

物品 gem-sockets: [qi_weapon]
   │ GemSocketService.syncProviders
   ▼
providers.legendinlay = {"sockets":["qi_weapon"],...}
   │
   ▼ 桥解析（LegendinlayProviderBridge）
LI/MG 后端按 socket lore 识别孔 → 玩家镶嵌

孔类型映射在 gem_socket_types.yml，孔目录 lore 须与后端逐字一致。
LegendCore 桥（含 groovy 兜底）让 qi- 前缀在 LegendCore 可用。

见宝石孔与集成 → Legendinlay。

六、一次完整调用链示例（玩家左键放技能并造成伤害）

玩家左键武器
  → QI ActionTriggerListener 捕获 left_click
  → 校验 conditions / cooldown / consume
  → 派发 refs:
        · combat:swing (heavy) → QinhCombatSwingEvent → player.attack()
              → 伤害由 AttributePlus 按物品 providers.ap 结算
        · qinhskills:cast {"skill":"...","level":1}
              → QISkillBridge → QinhSkills 施法 → (可能) MythicMobs 技能
  → 扣 consume、记 cooldown
  → QinhActionDispatchedEvent（供监听统计）

每一环的职责清晰：QI 调度、AP 算伤害、QS 放技能。

七、加载顺序与依赖

关系	说明
QCL → QI	硬依赖，QCL 必须先启动
QI ↔ QS	软依赖，谁先都行（QI 支持晚加载链接）
QI ↔ AP	软依赖，自动检测
QI ↔ LI/MG	软依赖

启动顺序细节见配置文件 → 启动顺序。

下一步

集成（架构）：注册表 / 桥
集成实操：逐插件接入
API 配方集：成品代码

跨模块对接（秦淮生态数据流） ​

一、模块职责分工 ​

二、QI ↔ CoreLib ​

QI 注册成物品源 ​

别人通过 CoreLib 取 QI 物品 ​

CoreLib 统一物品源前缀表 ​

关键分界 ​

三、QI ↔ AttributePlus ​

数据流 ​

自定义属性后端 ​

四、QI ↔ QinhSkills ​