生态集成（QinhSkills / Legendinlay / MagicGem）

所属：开发者　·　相关：Provider 与桥 · 宝石孔

QI 通过 QinhIntegrationRegistry 统一管理集成（动作处理器、物品源、Provider 桥、外部解析器、层贡献者）。本章讲三大内置集成。

---

1. 集成注册表

object QinhIntegrationRegistry {
    fun initDefaults()
    fun registerProviderBridge(bridge)
    fun registerExternalResolver(resolver)
    fun registerLayerContributor(contributor)
    fun registerBridgeHook(id, hook)
    fun registerActionHandler(handler)

    fun providerBridge(id): QinhProviderBridge?
    fun externalResolver(prefix): QinhExternalItemResolver?
    fun layerContributorsOrdered(): List<QinhItemLayerContributor>
    fun actionHandler(handlerId): QinhActionHandler?
    fun dispatchItemCompiled(event)
}

initDefaults() 注册默认层贡献者：Base / Variables / Section / Affix。

---

2. QinhSkills 集成

物品动作里的 qinhskills:cast 处理器把技能释放交给 QinhSkills（QS）。

链接机制

QinhSkillsLinker 在加载时：

1. 若 QinhSkills 存在，通过 QS 类加载器加载 com.qinhuai.skills.listener.QiListener。
2. 反射适配成 QinhActionHandler，以 QISkillBridge.HANDLER_ID 注册。
3. 调 QinhSkills.linkQinhItemsHandler(force) 双向链接。

QinhSkillsLinker.requestHandlerRegistration(force = true)
QinhSkillsLinker.isRegistered(): Boolean

晚加载支持

QinhSkillsEnableListener 监听 PluginEnableEvent，若 QinhSkills 在 QI 之后启用，自动触发链接。

派发流程

物品动作触发 → refs 含 qinhskills:cast → QI 调用桥处理器 → QS 收到技能释放请求
payload: {"skill":"技能ID","level":1}

---

3. Legendinlay 集成（宝石孔后端 A）

Provider 桥

object LegendinlayProviderBridge : QinhProviderBridge {
    override val providerId = "legendinlay"
    override fun isAvailable() = GemIntegrationBootstrap.isLegendinlayPresent()
    override fun parse(snapshot): BridgeParseResult?    // 解析 set/slot/piece/sockets/socket_lores
}

载荷解析

data class LegendinlayProviderMeta(
    val set: String?, val slot: String?, val piece: Int?,
    val socketIds: List<String>, val inlineSocketLores: Map<String,String>,
)
LegendinlayProviderParser.parse(blob): LegendinlayProviderMeta?

YAML 载荷示例：

providers:
  legendinlay:
    value: '{"set":"sword_set","slot":"enhanced_1","sockets":["normal","bainian"],"socket_lores":{"normal":"十年魂环孔位"}}'

孔目录 integrations/legendinlay_sockets.yml 的 lore 必须与 LI 那边逐字一致（LI 靠 Lore 识别孔），见 宝石孔。

LegendCore 物品桥

LegendCoreItemBridge 通过反射把 QI 注册进 LegendCore 的 ItemManagerAPI，别名 qi / qinhitems / QinhItems，build(id) → QinhItemRegistry.create()。

LegendCoreScriptDeployer 部署 groovy 兜底脚本 QinhItemsModule.groovy 到 LegendCore/groovy/，作为 Kotlin 反射桥失败时的备份（配置 legendinlay.auto-deploy-lc-script）。

---

4. MagicGem 集成（宝石孔后端 B）

object MagicGemProviderBridge : QinhProviderBridge {
    override val providerId = "magicgem"
    override fun isAvailable() = MagicGemBridge.isAvailable()
    override fun parse(snapshot): BridgeParseResult?
}

与 Legendinlay 共用 LegendinlayProviderParser 解析格式。孔目录 integrations/magicgem_sockets.yml。显示提示含 mg.set / mg.slot / mg.sockets / mg.socket_line_count。

---

5. 桥配置

integrations/bridges.yml 独立开关各桥：

azureflow:
  enabled: false

---

6. CoreLib 物品源对接

QI 把自己注册成 CoreLib 的物品源（QinhItemsItemSource，id qinhitems，别名 qi）。其它插件可通过 CoreLib 的 ItemManagerAPI.getHookItem("qi:物品ID") 拿到 QI 物品。

注意：前缀解析（qi: / qinhitems:）在 CoreLib，物品反查（item → id）在 QI。详见 API 概览 → 接入路线。

---

下一步

• Provider 与桥：桥抽象细节
• 导入导出