📖 概览
🧭 一句话定位
QinhCoreLib（简称 QCL）是「秦淮生态」的核心底座 / 平台库。 它本身不实现任何具体玩法，而是为上层玩法插件与第三方插件提供一整套统一能力：物品源、经济、脚本、数据库、PDC（持久化数据）、占位符、GUI、动作契约、桥接状态与诊断。
主类：com.qinhuai.corelib.QinhCoreLib · 版本：1.2.0
💡 一句话理解：QCL 是「水电煤」，QI/QS/QF/QSt 是建在上面的「房子」。 你装了 QCL 不会多出任何玩法，但缺了它，秦淮系的玩法插件一个都跑不起来。
🏗️ 它在生态里的位置
QCL 处在生态的最底层。所有秦淮系玩法插件都硬依赖它，第三方插件则通过它提供的桥接被「拉进来」统一使用。
┌─────────────────────────────────────────────┐
│ QI 物品 │ QS 技能 │ QF 锻造 │ QSt 强化 │ QCR │ ← 玩法层（硬依赖 QCL）
└─────────────────────────────────────────────┘
│ 硬依赖
▼
┌─────────────────────────────────────────────┐
│ QinhCoreLib (QCL) │ ← 底座层
│ 物品源 · 经济 · 脚本 · 数据库 · PDC · 占位符 │
│ GUI · 动作契约 · 桥接状态 · 诊断 │
└─────────────────────────────────────────────┘
│ 软依赖（反射桥接，未装自动跳过）
▼
┌─────────────────────────────────────────────┐
│ Vault · PlaceholderAPI · ModelEngine · ... │ ← 第三方层
│ MMOItems · NeigeItems · ItemsAdder · Nexo... │
└─────────────────────────────────────────────┘🔗 与各模块 / 第三方的关系
| 关系类型 | 对象 | 说明 |
|---|---|---|
| 硬依赖（必须装 QCL） | QinhItems(QI)、QinhSkills(QS)、QinhForge(QF)、QinhStrengthen(QSt)、QCR | 这些玩法插件没有 QCL 无法加载 |
| 软依赖（装了才桥接） | Vault、ExcellentEconomy、PlayerPoints、PlaceholderAPI、ModelEngine、CustomCrops、CustomFishing、MythicMobs、NeigeItems、MMOItems、CraftEngine、QinhItems、MagicGem、ItemsAdder、Nexo | 全部反射桥接，未装自动跳过，不报错 |
| 协作契约 | QI ↔ QS | QI 的物品动作通过 QCL 的 QISkillUseEvent / QinhActionHandler 把技能释放交给 QS（handlerId qinhskills:cast） |
各模块磁盘路径/职责划分详见生态总览文档。本系列文档只讲 QCL 自身。
✅ 它能做什么（典型场景）
| 能力 | 场景举例 | 详见 |
|---|---|---|
| 🗡️ 原生属性系统 | 不装任何属性插件也能用全套属性与伤害结算（攻击 / 暴击 / 防御 / 闪避 / 元素），支持自定义属性（yml + JS 脚本） | 属性系统 |
| 🎯 统一物品源 | 把 MythicMobs、MMOItems、ItemsAdder、Nexo、QI 等 10 种来源的物品，统一成一套引用字符串（如 mm-龙剑、mi-SWORD-烈焰剑、qi:神剑），任何子插件照抄即用 | 物品源引用 |
| 💰 跨插件经济 | 一套经济 API 同时兼容 Vault / ExcellentEconomy / PlayerPoints，子插件不必各自适配 | 经济动作 |
| 🖼️ 自定义 GUI | 用 YAML 在 guis/ 目录里画界面，配动作与条件，无需写代码 | 自定义GUI |
| 📜 脚本能力 | 内置 GraalJS / Groovy 脚本引擎，写诊断、动作、外部物品模块 | 脚本入门 |
| 🩺 诊断与排错 | 一条 /qcl status 看清整个生态的健康状态、桥接情况、健康码 | 诊断与排错 |
| 🧱 自定义方块 | 统一的方块抽象，桥接 ModelEngine / CraftEngine 等 | 自定义方块 |
🚫 它不做什么
QCL 是平台库，刻意把「玩法」留给上层插件。下面这些它一概不做：
| 不做 | 谁来做 |
|---|---|
| ❌ 不设计具体玩法数值（每件物品给多少属性、技能怎么造成伤害） | 由 QI / QS 等玩法模块决定（QCL 提供属性管道与原生结算，AttributePlus 等为可选后端） |
| ❌ 不定义物品内核（物品的属性、词条、合成怎么算） | QinhItems(QI) |
| ❌ 不实现技能逻辑 | QinhSkills(QS) |
| ❌ 不实现锻造 / 强化玩法 | QinhForge(QF) / QinhStrengthen(QSt) |
🧩 设计原则：QCL 只提供「能力契约」和「统一管道」，不替玩法做决定。 这保证了各玩法插件可以独立演进，而不会被底座绑死。
🗺️ 我该读哪一章？
| 你是谁 / 你想干嘛 | 推荐阅读 |
|---|---|
| 🆕 刚拿到 jar，想先跑起来 | 安装 → 快速上手 |
| 🧠 想搞懂它的整体设计 | 核心概念 |
| 🛠️ 服主：配置 / 命令 / 物品源 / GUI | 02-服主指南 整章 |
| 🐛 出问题了要排查 | 诊断与排错、诊断码 |
| 🔌 想对接外部插件 | 03-外部插件对接 |
| 👨💻 开发者：调 API / 写脚本 | 04-开发者 整章 |
| ❓ 名词不懂 / 常见问题 | 术语表、FAQ |