这页专门说明一个最近很重要的变化：

HNCore 现在已经把“开发依赖”和“运行插件”分开了。

如果你是：

• HN 系列下游插件作者
• 自己写 Bukkit / Paper 插件并复用 HNCore 能力的二开作者

这页建议必看。

一、现在有两个产物

1）hncore-api

这是给下游插件编译时依赖的模块。

它包含的主要是：

• HNCoreAPI
• ClusterBus 相关公共接口
• 共享数据库 / 共享物品库 / PubSub 的公共接口
• 命令公共基类
• 维护任务公共基类
• GUI / 公式 / 配置 / 日志等对外能力

2）hncore

这是给服务器实际运行的插件 jar。

它包含：

• Bukkit / Paper 插件主类
• API 实现
• Redis / MySQL / transport / provider 等运行实现
• GroovyScripts 运行时
• 其他内部逻辑

二、下游项目现在应该怎么依赖

推荐写法：

dependencies {
    compileOnly("com.github.hnplugins:hncore-api:x.y.z")
}

其中 x.y.z 应替换为你当前部署的 HNCore 对应版本。

也就是说：

• 编译时依赖 hncore-api
• 不要再用运行版 hncore 作为开发依赖
• 当你接入 1.1.0 新增的物品协议 / PlaceholderProvider / ItemSpec 能力时，依赖版本也要同步到 1.1.0

三、服务器运行时要怎么放

服务器端仍然只需要安装：

• HNCore 的运行版插件 jar

也就是说：

• 开发机 / 构建机需要 hncore-api
• 服务器 plugins/ 目录里需要的是 hncore

通常不需要额外再把单独的 hncore-api.jar 放进服务器插件目录。

四、为什么要这样拆

主要原因有 4 个：

1）让下游依赖更清晰

下游项目现在只依赖真正对外的 API 面，不再直接拿整份运行插件做编译依赖。

2）让运行实现更容易演进

像这些内部实现：

• storage
• cluster transport
• provider
• GroovyScripts 运行时

以后可以继续调整，而不需要把每个实现细节都暴露给下游项目。

3）让公共 API 更容易稳定

以后二开作者主要看：

• HNCoreAPI
• ClusterBus
• ItemLibraryGateway / ItemFacade
• SharedPubSubService
• ConfigManager
• Logger

这批公共入口，而不是直接绑死在实现类上。

4）为后续运行实现处理留空间

比如以后想做：

• 更明确的 API 分层
• 更严格的内部实现边界
• 更细粒度发布策略

都会更容易。

五、下游项目会受什么影响

影响最小的一点

只要你把 Gradle 依赖改成与当前 HNCore 发布版本一致，例如：

compileOnly("com.github.hnplugins:hncore-api:x.y.z")

通常源码本身不需要大改。

当前已验证的项目

目前已验证能正常基于 hncore-api 构建的下游包括：

• HNAttribute
• HNMail
• HNEconomy

六、推荐的理解方式

你可以把现在的 HNCore 理解成：

• hncore-api：给开发者看的稳定公共入口
• hncore：给服务器运行的完整实现

如果你只是复用能力，优先看：

• 开发者 API 与集成指南
• HNCore Java API

七、一句话结论

对二开作者来说

现在最推荐的方式就是：

• 开发依赖 hncore-api
• 运行时安装 hncore

这样依赖关系更清楚，后续接入也更稳定。