Add shared bStats API and prepare 1.3.0 release

Author: 54895y

CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to MatrixLib will be documented in this file.
+
+The format is based on Keep a Changelog, and this project follows Semantic Versioning for release tags.
+
+## [1.3.0] - 2026-04-05
+
+### Added
+
+- Added shared `MatrixBStats` API to centralize Matrix-series telemetry registration.
+- Added built-in MatrixLib telemetry charts for currency topology reporting.
+
+### Changed
+
+- MatrixLib now shades and owns the `bStats` runtime for downstream Matrix plugins.
+- MatrixAuth, MatrixCook, MatrixShop, and MatrixStorage now register telemetry through the MatrixLib API instead of direct `Metrics` access.
+- Updated public docs, README entry points, and release materials for the new telemetry layer.
+
+### Validated
+
+- Verified `bash ./gradlew build`.
+- Verified downstream builds for MatrixAuth, MatrixCook, MatrixShop, and MatrixStorage against `matrixlibApiVersion=1.3.0`.

README.md

@@ -3,73 +3,64 @@
 
 # MatrixLib
 
-**Keywords:** Minecraft plugin library, Paper plugin library, Folia plugin library, Bukkit plugin API, Spigot plugin API, TabooLib, Kotlin plugin library, GUI framework, shared runtime, Matrix plugin framework
+`MatrixLib` 是 Matrix 系列插件的共享前置插件，用于统一品牌风格、控制台输出、文本能力、YAML 读取、兼容层、共享菜单能力、共享货币模块，以及共享 `bStats` 遥测封装。
 
-`MatrixLib` 是 Matrix 系列插件的共享前置插件，用于统一品牌风格、控制台输出、文本能力、YAML 读取、兼容层、共享菜单能力和共享货币模块。
+| 文档 | Release Notes | Releases | Issues |
+| --- | --- | --- | --- |
+| [Docs](https://54895y.github.io/docs/matrixlib) | [1.3.0](https://54895y.github.io/docs/matrixlib/release-notes-1-3-0) | [GitHub Releases](https://github.com/54895y/MatrixLib/releases) | [GitHub Issues](https://github.com/54895y/MatrixLib/issues) |
 
-MatrixLib is a shared Minecraft plugin runtime and dependency library for MatrixShop, MatrixAuth, MatrixCook and MatrixStorage. It targets Paper, Bukkit, Spigot and Folia servers, and provides shared branding, console, menu, YAML, compat, action and economy APIs.
+## 当前发布
 
-**中文关键词：** Minecraft 插件前置, Paper 插件前置, Folia 插件前置, Bukkit 插件 API, Spigot 插件 API, TabooLib 前置, Kotlin 插件库, GUI 菜单框架, 共享运行时, Matrix 插件框架
+- 当前版本：`1.3.0`
+- 依赖坐标：`com.y54895.matrixlib:matrixlib-api:1.3.0`
+- 服务对象：`MatrixShop / MatrixAuth / MatrixCook / MatrixStorage`
+- 支持核心：`Paper / Bukkit / Spigot / Folia`
 
-## Discoverability
+## 核心能力
 
-- English: Minecraft plugin library, Paper plugin framework, Folia plugin framework, Bukkit shared runtime, TabooLib shared API, Kotlin Minecraft library
-- 中文: Minecraft 插件前置, 服务器插件前置, 中文控制台前置, 共享菜单前置, 兼容层前置, GUI 菜单前置, 共享货币前置
+- 共享 `branding / console / text / yaml` API
+- 共享 `menu / compat / action / economy` API
+- 统一中文控制台横幅与生命周期输出
+- 共享 `Economy/currency.yml` 货币定义与运行时同步
+- 共享 Bukkit / Folia 兼容桥接
+- 共享 `bStats` 封装 API `MatrixBStats`
+- 为下游插件统一承接 `bStats` shaded 依赖与图表注册
 
-## What MatrixLib Provides
+## 下游集成
 
-- Shared `branding / console / text / yaml` APIs
-- Shared `menu / compat / action / economy` APIs
-- Unified Chinese terminal banner and lifecycle output
-- Shared Bukkit / Folia compatibility bridge
-- Shared runtime for MatrixShop, MatrixAuth, MatrixCook and MatrixStorage
-- Shared `Economy/currency.yml` with runtime synchronization to MatrixShop and MatrixStorage
+下游项目当前统一引用：
 
-## Current Focus
-
-- Shared `economy` API is now part of MatrixLib
-- `plugins/MatrixLib/Economy/currency.yml` is the source of truth for Matrix series currency definitions
-- Runtime sync targets:
-  - `plugins/MatrixLib/Economy/currency.yml`
-  - `plugins/MatrixShop/Economy/currency.yml`
-  - `plugins/MatrixStorage/Economy/currency.yml`
-- Supported shared currency backends:
-  - `Vault`
-  - `PlayerPoints`
-  - PlaceholderAPI-driven custom currencies
-
-## Downstream Build Integration
-
-Dependency coordinate:
-
-- `com.y54895.matrixlib:matrixlib-api:1.1.0`
+```kotlin
+dependencies {
+    compileOnly("com.y54895.matrixlib:matrixlib-api:1.3.0")
+}
+```
 
-Downstream projects support two build modes:
+如果工作区里存在本地 `MatrixLib` 目录，下游项目会通过 `includeBuild` 直接链接源码；否则会通过 GitHub `sourceControl` 拉取。
 
-1. Local linked mode  
-   If the workspace contains a local `MatrixLib` directory, downstream projects use `includeBuild` for direct local source linkage.
-2. GitHub source mode  
-   If there is no local `MatrixLib` directory, Gradle resolves MatrixLib directly from GitHub through `sourceControl`.
+## bStats 遥测
 
-Reference configuration:
+- Plugin ID: `30557`
+- 共享遥测入口：`com.y54895.matrixlib.api.metrics.MatrixBStats`
 
-```kotlin
-val matrixLibModule = "com.y54895.matrixlib:matrixlib-api"
+当前图表：
 
-sourceControl {
-    gitRepository(uri("https://github.com/54895y/MatrixLib.git")) {
-        producesModule(matrixLibModule)
-    }
-}
-```
+| Chart ID | 类型 | 含义 |
+| --- | --- | --- |
+| `configured_currency_count` | SingleLineChart | 当前已配置货币数量 |
+| `currency_modes` | AdvancedPie | 货币模式分布 |
+| `currency_setup` | SimplePie | 单货币 / 多货币部署类型 |
 
-## Current Public Release
+预留图表位：
 
-- `1.1.0`
+| 预留 Chart ID | 计划用途 |
+| --- | --- |
+| `downstream_plugin_count` | 统计当前安装的 Matrix 系列下游插件数量 |
+| `resource_sync_targets` | 统计共享资源同步目标分布 |
+| `compat_bridge_modes` | 统计兼容桥接启用情况 |
 
-## Links
+## 相关链接
 
-- GitHub Repo: [https://github.com/54895y/MatrixLib](https://github.com/54895y/MatrixLib)
-- Issues: [https://github.com/54895y/MatrixLib/issues](https://github.com/54895y/MatrixLib/issues)
-- Releases: [https://github.com/54895y/MatrixLib/releases](https://github.com/54895y/MatrixLib/releases)
-- Related docs: [https://54895y.github.io/docs/plugins](https://54895y.github.io/docs/plugins)
+- Matrix 插件总文档入口：[https://54895y.github.io/docs/plugins](https://54895y.github.io/docs/plugins)
+- Matrix 系列配置 Skill 文档：[https://54895y.github.io/docs/matrix-agent-skills/matrix-series-config](https://54895y.github.io/docs/matrix-agent-skills/matrix-series-config)
+- MatrixAgentSkills 仓库：[https://github.com/54895y/MatrixAgentSkills](https://github.com/54895y/MatrixAgentSkills)

RELEASE_POST_BBCODE.txt

@@ -0,0 +1,123 @@
+[center][size=6][b]MatrixLib[/b][/size][/center]
+[center][size=4]Matrix 系列统一前置插件 / 共享运行时基础层[/size][/center]
+[center][size=3]当前发布版本：1.3.0[/size][/center]
+
+[hr]
+
+[b]插件简介[/b]
+
+MatrixLib 是 Matrix 系列插件的共享前置插件，用于统一品牌风格、控制台输出、文本能力、YAML 读取、兼容层、共享菜单能力和共享货币模块。
+
+它主要服务于 MatrixShop、MatrixAuth、MatrixCook 和 MatrixStorage，适用于 Paper、Bukkit、Spigot 和 Folia 服务端生态。
+
+[b]核心功能[/b]
+
+[list]
+[*]提供共享的 branding / console / text / yaml API
+[*]提供共享的 menu / compat / action / economy API
+[*]统一中文控制台横幅与生命周期输出
+[*]提供 Bukkit / Folia 兼容桥接能力
+[*]提供共享的 Economy/currency.yml 货币配置入口
+[*]运行时可同步货币配置到 MatrixShop 与 MatrixStorage
+[*]支持 Vault、PlayerPoints 与基于 PlaceholderAPI 的自定义货币动作
+[*]提供共享 JDBC datasource factory
+[*]提供共享 item hook registry，当前已覆盖 CraftEngine、ItemsAdder、Oraxen
+[*]提供共享 Bukkit 插件查找与反射命令注册辅助能力
+[/list]
+
+[b]Wiki / 相关地址[/b]
+
+[list]
+[*]项目仓库：[url]https://github.com/54895y/MatrixLib[/url]
+[*]GitHub Releases：[url]https://github.com/54895y/MatrixLib/releases[/url]
+[*]Issue 地址：[url]https://github.com/54895y/MatrixLib/issues[/url]
+[*]Matrix 插件总文档入口：[url]https://54895y.github.io/docs/plugins[/url]
+[/list]
+
+[b]Skills 使用方法[/b]
+
+如果你希望使用 AI 直接生成 Matrix 系列的共享货币配置、跨插件联动配置或 Kether 脚本，可以使用公开的 MatrixAgentSkills：
+
+[list]
+[*]Matrix Series Config 文档：[url]https://54895y.github.io/docs/matrix-agent-skills/matrix-series-config[/url]
+[*]Codex / OpenAI Skills：
+[url]https://github.com/54895y/MatrixAgentSkills/tree/main/matrix-series-config[/url]
+[*]Claude / Gemini / Cline / Roo / Continue 通用 Prompt：
+[url]https://raw.githubusercontent.com/54895y/MatrixAgentSkills/main/portable/matrix-series-config.md[/url]
+[*]AIChat 知识库入口：
+[url]https://raw.githubusercontent.com/54895y/MatrixAgentSkills/main/aichat/matrix-series-config-kb.md[/url]
+[/list]
+
+推荐使用方式：
+
+[list=1]
+[*]把对应的 Skill 或 Prompt 链接发给你的 AI Agent
+[*]告诉它你要生成 MatrixLib 的共享货币文件，或同时联动 MatrixShop / MatrixStorage
+[*]例如直接让 Agent 生成 plugins/MatrixLib/Economy/currency.yml，并同步规划 MatrixShop 与 MatrixStorage 的货币 key 引用
+[/list]
+
+[b]更新日志[/b]
+
+当前源码主线版本重点如下：
+
+[list]
+[*]当前发布版本已升级到 1.3.0
+[*]共享 economy API 已正式收敛到 MatrixLib
+[*]新增共享 MatrixBStats API，统一承接 Matrix 系列插件的 bStats 遥测注册
+[*]plugins/MatrixLib/Economy/currency.yml 成为 Matrix 系列货币定义主入口
+[*]运行时会同步货币文件到 MatrixShop 与 MatrixStorage
+[*]共享 runtime text / console 能力已经稳定承载下游插件
+[*]共享 YAML bundle factory、item hooks、JDBC datasource factory 已落地
+[*]已提供共享 Bukkit 平台辅助能力，包括插件查找与反射命令注册
+[*]下游 MatrixAuth / MatrixCook / MatrixShop / MatrixStorage 已切到共享遥测 API
+[*]本地开发记录显示 MatrixLib 与全部下游 bash ./gradlew build 已通过
+[/list]
+
+[b]bStats 图表[/b]
+
+[list]
+[*]Plugin ID：30557
+[*]configured_currency_count：当前已配置货币数量
+[*]currency_modes：货币模式分布
+[*]currency_setup：单货币 / 多货币部署类型
+[/list]
+
+[b]预留图表位[/b]
+
+[list]
+[*]downstream_plugin_count
+[*]resource_sync_targets
+[*]compat_bridge_modes
+[/list]
+
+[b]GitHub Issue 提交问题[/b]
+
+[list]
+[*]项目地址：[url]https://github.com/54895y/MatrixLib[/url]
+[*]Issue 地址：[url]https://github.com/54895y/MatrixLib/issues[/url]
+[/list]
+
+如果你在使用过程中遇到以下问题，欢迎直接提交 Issue：
+
+[list]
+[*]前置加载失败
+[*]共享货币模块异常
+[*]下游插件兼容问题
+[*]菜单 / 文本 / YAML API 行为异常
+[*]Folia / Bukkit 兼容层问题
+[*]新功能建议
+[/list]
+
+提交 Issue 时建议附带以下信息：
+
+[list]
+[*]服务端核心与版本
+[*]MatrixLib 版本
+[*]相关下游插件版本，例如 MatrixShop / MatrixStorage
+[*]控制台报错日志
+[*]相关配置文件片段
+[*]复现步骤
+[/list]
+
+[hr]
+[right][size=2][color=red]VibeCoding 声明：本插件在开发过程中使用了 AI / Vibe Coding 作为辅助工具，但实际功能收敛、接口边界、兼容性验证与发布内容仍以仓库代码、文档和实机测试结果为准；如发现问题，请优先通过 GitHub Issues 提交反馈。[/color][/size][/right]