fix: stabilize CI and package installs

.github/workflows/build.yml

@@ -143,6 +143,16 @@ jobs:
       - name: Make gradlew executable
         run: chmod +x gradlew
 
+      - name: Validate release tag matches project version
+        shell: bash
+        run: |
+          project_version=$(./gradlew properties -q --no-daemon | awk -F': ' '/^version:/ { print $2; exit }')
+          tag_version="${GITHUB_REF_NAME#v}"
+          if [ "$project_version" != "$tag_version" ]; then
+            echo "Release tag ${GITHUB_REF_NAME} does not match Gradle project version ${project_version}"
+            exit 1
+          fi
+
       - name: Install jpackage system dependencies
         shell: bash
         run: |
@@ -218,7 +228,7 @@ jobs:
         run: |
           mkdir -p release
           # Move all distributable files to release/
-          find . -name "*.jar" -path "*/francium-jar-*" -exec cp {} release/ \;
+          find . -path "*/build/libs/*-all.jar" -exec cp {} release/ \;
           find . -name "*.exe" -exec cp {} release/ \;
           find . -name "*.dmg" -exec cp {} release/ \;
           find . -name "*.deb" -exec cp {} release/ \;

.github/workflows/checkstyle.yml

@@ -11,14 +11,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - name: Make gradlew executable
+        run: chmod +x gradlew
       - name: Set up JDK 21
         uses: actions/setup-java@v5
         with:
           java-version: '21'
           distribution: 'temurin'
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v6
-      - name: Run Checkstyle
-        run: ./gradlew checkstyleMain
-      - name: Run Tests
-        run: ./gradlew test
+      - name: Run Gradle verification
+        run: ./gradlew check --no-daemon

README.md

@@ -107,7 +107,7 @@ public class QuickStart {
 }
 ```
 
-完整的 API 文檔請參閱 [Javadoc](https://jitpack.io/com/github/stanley-1028/francium-loader/v2.2.0/javadoc/)。
+完整的 API 文檔請參閱 [Javadoc](https://jitpack.io/com/github/stanley-1028/francium-loader/v2.3.0/javadoc/)。
 
 ---
 

ROADMAP.md

@@ -24,7 +24,7 @@
 | MultiMC/Prism 匯入 | ✅ v2.3.0 新增 |
 | 文件 (DEVELOPER_GUIDE.md) | ✅ |
 | Maven Central 發布 | ❌ |
-| Nova Launcher 整合 | ❌ |
+| Nova Launcher 整合 | ✅ |
 
 ---
 
@@ -45,13 +45,13 @@
 
 ## 🟡 P1：開發者體驗
 
-- [ ] Nova Launcher 整合端到端驗證
+- [x] Nova Launcher 整合端到端驗證 ✅
 - [x] 範例模組 (Hello World Francium Mod) ✅ v2.3.0
 - [x] 預編譯 example-mod JAR ✅ v2.3.0
 - [x] Gradle 模板專案 (francium-mod-template) ✅
 - [x] 模組開發者文件 (DEVELOPER_GUIDE.md) ✅
 - [x] `francium.json` 完整欄位說明 ✅
-- [ ] API Javadoc 上線
+- [x] API Javadoc 上線 ✅
 
 ---
 
@@ -89,7 +89,6 @@ v2.3.0 (2026-06-18):
 
 下一步:
   ├── Mapping 數據庫繼續擴充至 60 類 / 800+ 方法
-  ├── Nova Launcher 整合驗證
   ├── Maven Central 發布
-  └── API Javadoc 上線
+  └── 社群推廣與文檔完善
 ```

build.gradle

@@ -53,6 +53,39 @@ allprojects {
     }
 }
 
+tasks.register('verifyReleaseMetadata') {
+    group = 'verification'
+    description = 'Verify release metadata matches the Gradle project version.'
+
+    doLast {
+        def projectVersion = project.version.toString()
+
+        def metadataFile = file('francium-core/src/main/resources/francium-loader.properties')
+        def metadata = new Properties()
+        metadataFile.withInputStream { metadata.load(it) }
+        def metadataVersion = metadata.getProperty('francium.version')
+        if (metadataVersion != projectVersion) {
+            throw new GradleException(
+                "francium.version (${metadataVersion}) must match Gradle version (${projectVersion})"
+            )
+        }
+
+        def readme = file('README.md').getText('UTF-8')
+        def expectedJitPack = "francium-loader:v${projectVersion}"
+        def expectedMaven = "francium-loader:${projectVersion}"
+        def expectedJavadocs = "/francium-loader/v${projectVersion}/javadoc/"
+        [expectedJitPack, expectedMaven, expectedJavadocs].each { expected ->
+            if (!readme.contains(expected)) {
+                throw new GradleException("README.md is missing release metadata: ${expected}")
+            }
+        }
+    }
+}
+
+tasks.named('check') {
+    dependsOn tasks.named('verifyReleaseMetadata')
+}
+
 // Common configuration for all subprojects
 subprojects {
     apply plugin: 'java'

build_dist.bat

@@ -6,9 +6,17 @@ REM ============================================
 setlocal enabledelayedexpansion
 
 set PROJECT_DIR=%~dp0
-set VERSION=1.2.0
 set DIST_DIR=%PROJECT_DIR%build\dist
 
+for /f "tokens=2 delims=:" %%v in ('call "%PROJECT_DIR%gradlew.bat" properties -q --no-daemon ^| findstr /b "version:"') do (
+    set "VERSION=%%v"
+)
+set "VERSION=!VERSION: =!"
+if not defined VERSION (
+    echo FAILED: Unable to determine Gradle project version
+    exit /b 1
+)
+
 echo ==========================================
 echo   Francium Loader v%VERSION% - Distribution
 echo ==========================================

docs/DEVELOPMENT_PLAN.md

@@ -0,0 +1,140 @@
+# 🚀 Francium Mod Loader — 開發計劃書 (Development Proposal)
+
+> **下一代 Minecraft 模組加載器 — 由 AI 驅動的版本橋接與 DAG 並行加載**
+>
+> 本計劃書旨在規劃 Francium Mod Loader 從目前的 **v2.3.0（核心功能完備階段）** 邁向 **v3.0.0（生態繁榮與工業級穩定階段）** 的技術演進路線、開發時程與社群推廣策略。
+
+---
+
+## 1. 項目背景與定位 (Background & Positioning)
+
+### 1.1 現有生態痛點
+現有的 Minecraft 模組加載器（Forge, Fabric, NeoForge, Quilt）雖然成熟，但仍面臨以下結構性痛點：
+1. **加載時間過長**：模組呈循序加載，當安裝 100+ 個模組時，啟動時間通常需要 2-3 分鐘。
+2. **依賴地獄與衝突**：模組之間的版本依賴衝突需要玩家手動比對與排除，缺乏自動化求解方案。
+3. **版本斷層與不相容**：Minecraft 每次大版本更新，模組作者都必須手動修改程式碼並重新編譯，導致大量優秀模組停留在舊版本。
+4. **效能與記憶體損耗**：所有模組共用同一個 ClassLoader，容易發生類別污染；且缺乏統一的記憶體與物件池管理，導致頻繁的 GC 停頓。
+
+### 1.2 Francium 的定位
+Francium 不是另一個「輕量化」的加載器，而是**從底層重新設計的下一代模組加載器**。我們通過 **DAG 並行加載**、**SAT 依賴求解** 與 **AI 字節碼適配橋接**，徹底解決上述痛點，實現「不要等待模組更新，讓 AI 替你橋接未來」的願景。
+
+---
+
+## 2. 核心技術架構與演進 (Technical Architecture)
+
+Francium 的架構由六大核心模組組成，未來將在穩定性與精準度上持續演進：
+
+```
+                    ┌────────────────────────────────────────┐
+                    │          Francium Bootstrap            │
+                    └───────────────────┬────────────────────┘
+                                        │
+                                        ▼
+                    ┌────────────────────────────────────────┐
+                    │         SAT Dependency Resolver        │ (依賴衝突自動求解)
+                    └───────────────────┬────────────────────┘
+                                        │
+                                        ▼
+                    ┌────────────────────────────────────────┐
+                    │               Mod Graph                │ (Kahn 算法拓撲分層)
+                    └───────────────────┬────────────────────┘
+                                        │
+                                        ▼
+                    ┌────────────────────────────────────────┐
+                    │       ParallelModClassLoader           │ (ForkJoinPool 並行加載)
+                    └───────────┬────────────────┬───────────┘
+                                │                │
+                                ▼                ▼
+                    ┌──────────────────┐  ┌──────────────────┐
+                    │ AI Version Bridge│  │  Memory Profiler │ (洩漏偵測/物件池/GC)
+                    └──────────────────┘  └──────────────────┘
+```
+
+### 2.1 DAG 並行加載 (Parallel Loading)
+* **原理**：將模組依賴關係構建為有向無環圖（DAG），使用 Kahn 算法進行拓撲分層。同層模組互不依賴，利用 `ForkJoinPool` 進行多執行緒並行加載。
+* **v3.0 演進目標**：
+  * 引入**動態加載權重調度**：根據模組歷史加載時間，動態調整並行加載順序，最大化 CPU 利用率。
+  * 支援**非阻塞式非同步初始化**：允許部分非核心模組在遊戲主介面載入後，於背景繼續初始化。
+
+### 2.2 AI 版本橋接 (AI Version Bridge) — *核心創新*
+* **原理**：使用 ASM 進行字節碼分析，提取模組對 Minecraft 核心 API 的調用；通過多維相似度計算與加權特徵模型，自動生成適配器字節碼（Adapter Bytecode），實現跨版本透明轉發。
+* **v3.0 演進目標**：
+  * **Mapping 數據庫擴充**：從目前的 38 類 / 400 方法，擴充至 **60 類 / 800+ 方法**，覆蓋 95% 以上的常用 Modding API。
+  * **機器學習模型本地推論**：整合 ONNX Runtime，在本地運行輕量化注意力預測模型（Attention Predictor），提高未知 API 映射的精準度。
+  * **極速本地快取**：優化快取機制，避免重複分析未變更的模組，使二次啟動達到「零延遲」橋接。
+
+### 2.3 SAT 依賴解析 (SAT Resolver)
+* **原理**：將模組版本約束轉化為命題公式，使用 DPLL 算法配合 MRV/LCV 啟發式進行求解，自動推薦最優版本組合。
+* **v3.0 演進目標**：
+  * **衝突可視化**：當依賴無解時，生成直觀的衝突路徑圖，並提供「一鍵自動升級/降級」的修復建議。
+
+---
+
+## 3. 未來開發里程碑與優先級 (Milestones & Roadmap)
+
+我們將開發計劃分為四個階段，以確保項目的穩健推進：
+
+### 🟥 階段一：工業級穩定性與基礎建設 (P0) — *當前重點*
+* **目標**：確保現有功能在各種極端環境下的穩定性，打通發布管道。
+* **核心任務**：
+  1. **Maven Central 發布**：配置完整的 GPG 簽名與 Maven Central Portal 發布管道，使開發者能直接通過 Maven Central 引入 Francium API。
+  2. **套件管理器穩定化**：完成 `PackageManager` 與真實 Modrinth/CurseForge API 註冊表適配器的對接，確保 `francium install` 能夠穩定解析並下載模組。
+  3. **CI/CD 自動化發布**：完善 GitHub Actions，在發布 Tag 時自動構建 Windows (.exe)、macOS (.dmg) 與 Linux (.deb) 的原生安裝包。
+
+### 🟨 階段二：開發者生態與工具鏈 (P1)
+* **目標**：降低模組開發難度，吸引更多開發者加入 Francium 生態。
+* **核心任務**：
+  1. **API Javadoc 自動化部署**：配置 GitHub Pages，使每次版本發布時自動更新並上線最新 API 的線上文檔。
+  2. **Gradle 插件 (Francium Gradle Plugin)**：開發專屬的 Gradle 構建插件，自動生成 `francium.json` 並簡化開發調試流程。
+  3. **模組開發模板 (Template Project)**：完善 `francium-mod-template`，提供開箱即用的開發環境。
+
+### 🟩 階段三：Mapping 數據庫社群化 (P2)
+* **目標**：通過社群力量快速擴充跨版本映射數據庫，實現版本適配的良性循環。
+* **核心任務**：
+  1. **開放社群貢獻工作流 (Community Contribution Workflow)**：
+     * 建立一個基於 GitHub Issues/PRs 的半自動化審核系統。
+     * 開發者只需提交 API 映射的 JSON 片段，CI 會自動運行驗證測試（如現有的 83 項 Mapping 測試），通過後自動合併至主數據庫。
+  2. **自動化映射生成工具**：開發一個 CLI 工具，輸入兩個不同版本的 Minecraft 核心 JAR，自動比對並生成種子映射數據。
+
+### 🟦 階段四：AI 橋接精準度躍升 (P3)
+* **目標**：引入機器學習技術，使 AI 版本橋接具備自我學習與高精度預測能力。
+* **核心任務**：
+  1. **注意力預測模型 (Attention Predictor)**：基於 Transformer 架構，分析方法上下文與調用圖特徵，預測跨版本重命名方法的相似度。
+  2. **本地推論引擎整合**：在 `francium-ai-bridge` 中引入 `onnxruntime` 依賴，實現無網路環境下的高精度本地預測。
+
+---
+
+## 4. 技術選型與依賴管理 (Tech Stack)
+
+為保持加載器的輕量與高效，我們嚴格控制外部依賴：
+
+| 模組 | 核心技術 | 外部依賴 | 說明 |
+|------|----------|----------|------|
+| **francium-core** | Java 21, ForkJoin | 無 | 保持核心加載器的極致輕量與零依賴 |
+| **francium-ai-bridge** | ASM 9.6, ONNX Runtime | `org.ow2.asm:asm` | 字節碼解析與本地 AI 推論 |
+| **francium-resolver** | DPLL 算法 | 無 | 純 Java 實現的 SAT 求解器 |
+| **francium-manager** | Java HttpClient | `com.google.code.gson:gson` | 輕量化套件管理與 JSON 解析 |
+| **francium-profiler** | Java Instrument, JVM TI | 無 | 記憶體洩漏偵測與自適應 GC |
+| **francium-server** | Netty | `io.netty:netty-all` | 高性能伺服器同步協議 |
+
+---
+
+## 5. 風險評估與應對策略 (Risk & Mitigation)
+
+### 5.1 Minecraft 核心架構劇烈變更
+* **風險**：Mojang 在未來大版本中重構底層引擎（如將 Java 換成其他語言，或徹底重構註冊表系統），導致現有 Mapping 失效。
+* **應對**：Francium 的 AI Bridge 設計為**架構無關**。只要字節碼語義結構存在相似性，AI 就能通過重新訓練特徵權重來適應新的架構。此外，我們將保持與 Mojang 官方映射（Mojmap）的即時同步。
+
+### 5.2 AI 橋接帶來的效能損耗
+* **風險**：在啟動時進行字節碼分析與動態適配器生成，可能會抵消 DAG 並行加載帶來的加速效果。
+* **應對**：
+  1. **極速本地快取**：引入 SHA-256 雜湊驗證，只有在模組 JAR 變更或 Minecraft 版本更新時才進行重新分析，二次啟動時直接加載已生成的適配器 JAR。
+  2. **多執行緒分析**：將字節碼分析任務納入 ForkJoin 執行緒池，與模組掃描並行執行。
+
+---
+
+## 6. 總結 (Conclusion)
+
+Francium Mod Loader 代表了 Minecraft 模組加載技術的未來。通過這份開發計劃，我們將在確保**核心穩定性 (P0)** 的前提下，逐步構建**開發者生態 (P1)**、**社群化數據庫 (P2)** 與 **AI 智慧橋接 (P3)**。
+
+我們相信，Francium 將徹底打破 Minecraft 版本斷層的魔咒，為玩家與開發者帶來前所未有的極速、智慧與相容體驗。

francium-api/src/main/java/com/francium/api/PublicApi.java

@@ -19,13 +19,13 @@
  * time without notice. Consumers should avoid depending on them directly.
  * </p>
  *
- * <h3>Usage</h3>
+ * <h2>Usage</h2>
  * <pre>{@code
  * @PublicApi
  * public class FranciumLoader { ... }
  * }</pre>
  *
- * <h3>Stability guarantees</h3>
+ * <h2>Stability guarantees</h2>
  * <ul>
  *   <li>Patch version: bug fixes only, no API changes</li>
  *   <li>Minor version: additions only, no removals or backward-incompatible changes</li>

francium-core/src/main/resources/francium-loader.properties

@@ -1,5 +1,5 @@
 # Francium Mod Loader version properties
 # Auto-detected by Nova Launcher and other consumers
-francium.version=1.2.0
-francium.build.date=2026-05-12
+francium.version=2.3.0
+francium.build.date=2026-06-18
 francium.minimum.java=21