feat: 换用自研MuConvert转谱器 (#58)

* chore: Update MuNET-UI submodule

* add: 添加MuConvert的submodule

* add: 添加新的配置项，名为“导入/导出时，使用旧版转谱器进行转谱（兼容模式）”（仅配置项本身，功能还未实现）。和一些i18n key

* feat&refactor: 导入谱面适配到新MuConvert上。
1. 将原有的MaidataImportService移动到LegacyMaidataImportService.cs
2. MaidataImportService.cs，改为基于MuConvert实现
3. ImportChart API，基于全局配置项决定调用哪一个service；ImportChartCheck API，大部分逻辑改为基于新版MuConvert，只在“尝试转谱一次和计算musicPadding”这步会调用legacy。

* feat: 导出谱面适配到新MuConvert上。
具体包括导出maidata格式，软件内调用Majdata预览、`CopyMusicToDirectory`和`ExportOpt`的MA2_103格式。

* fix: Legacy版本，isDx未正确设置；增强ExportAsMaidata的异常处理，异常时会打印log

* fix: 各种小修改+同步MuConvert版本

* feat: MuConvert汇报的行号，转为在maidata.txt文件中的真实行号

* fix: ReplaceChart 没有遵循 legacy 设置

* refactor & update: 基于IMaidataImportService重构ImportChart；在AppMain.SerLocale中联动设置MuConvert的Locale；拉取最新版本MuConvert

* fix: 优化一下maidata字段的顺序

* fixup

---------

Co-authored-by: Clansty <i@gao4.pw>

Author: Starrah

.gitignore

@@ -10,3 +10,4 @@ riderModule.iml
 node_modules
 nul
 .sisyphus
+*.lscache

.gitmodules

@@ -16,3 +16,6 @@
 [submodule "MuNet-UI"]
 	path = MuNET-UI
 	url = git@github.com:MuNET-OSS/MuNET-UI.git
+[submodule "MuConvert"]
+	path = MuConvert
+	url = https://github.com/MuNET-OSS/MuConvert.git

.idea/.idea.Sitreamai/.idea/vcs.xml

@@ -1,87 +1,109 @@
 # PROJECT KNOWLEDGE BASE
 
-**Generated:** 2026-02-26
-**Commit:** 1cb9a70
-**Branch:** feat/munet-ui
+**Generated:** 2026-04-26
+**Commit:** 232b5cb
+**Branch:** pr/Starrah/58
 
 ## OVERVIEW
 
-MaiChartManager (Sitreamai) — maimai 音游谱面管理工具。C# ASP.NET Core 后端 + WinForms 桌面壳 + Vue 3 前端 SPA，内嵌本地 web server。
+MaiChartManager (Sitreamai) — maimai 音游谱面管理工具。C# ASP.NET Core (net10.0-windows) 后端 + WinForms 桌面壳 + Vue 3 前端 SPA，内嵌本地 Kestrel web server。
 
 ## STRUCTURE
 
 ```
 Sitreamai/
 ├── MaiChartManager/          # 主程序：ASP.NET Core + WinForms 混合桌面应用
-│   ├── Controllers/          # REST API 控制器（按领域分子目录）
-│   ├── Front/                # Vue 3 + TypeScript 前端 SPA
-│   ├── Models/               # DTO / XML 数据模型
+│   ├── Controllers/          # REST API 控制器（按领域分 7 个子目录）
+│   ├── Front/                # Vue 3 + TypeScript 前端 SPA（pnpm workspace 成员）
+│   ├── Models/               # DTO / XML 数据模型（纯数据结构，无业务逻辑）
 │   ├── Services/             # 业务逻辑服务
 │   ├── Utils/                # 音频/视频/图片转换、CRI 工具
-│   ├── WannaCRI/             # CRI 音频格式处理
-│   └── FFMpeg/               # 嵌入式 FFmpeg
+│   ├── Attributes/           # 自定义 Attribute
+│   ├── Locale/               # i18n 资源（resx）
+│   ├── Libs/                 # 打包进来的第三方库
+│   ├── Python/               # ⚠️ 嵌入式 Python 运行时（勿修改）
+│   ├── FFMpeg/               # ⚠️ 嵌入式 FFmpeg（勿修改）
+│   ├── WannaCRI/             # ⚠️ CRI 音频工具（勿修改）
+│   ├── Resources/            # 应用资源
+│   └── wwwroot/              # ⚠️ 前端构建产物（勿手动修改）
 ├── MaiChartManager.CLI/      # 命令行工具 (mcm)，Spectre.Console
+├── MaiChartManager.GenClient/ # API client 生成辅助项目
 ├── AquaMai/                  # [submodule] BepInEx/MelonLoader 游戏 mod
 ├── MaiLib/                   # [submodule] maimai 谱面解析库
+├── MuConvert/                # [submodule] 谱面格式转换工具
+├── MuNET-UI/                 # [submodule] @munet/ui 通用 UI 组件库（pnpm workspace 成员）
 ├── SimaiSharp/               # [submodule] Simai 谱面格式解析
 ├── SonicAudioTools/          # [submodule] CRI 音频工具库
 ├── XV2-Tools/                # [submodule] ACB/HCA 音频格式处理
-└── Packaging/                # MSIX 打包脚本和资源
+└── Packaging/                # MSIX/Appx 打包脚本和资源
 ```
 
 ## WHERE TO LOOK
 
 | Task | Location | Notes |
 |------|----------|-------|
 | 添加/修改 API 接口 | `MaiChartManager/Controllers/` | 按领域分目录，见子目录 AGENTS.md |
-| 前端 UI 修改 | `MaiChartManager/Front/src/` | Vue 3 + Naive UI，见子目录 AGENTS.md |
+| 前端 UI 修改 | `MaiChartManager/Front/src/` | Vue 3 + Naive UI + UnoCSS，见子目录 AGENTS.md |
 | 音频处理逻辑 | `MaiChartManager/Utils/Audio*.cs`, `CriUtils.cs` | FFmpeg + CRI SDK |
-| 谱面导入/解析 | `MaiChartManager/Services/`, `MaiLib/`, `SimaiSharp/` | MaiLib 和 SimaiSharp 是 submodule |
-| 应用启动流程 | `MaiChartManager/Program.cs` → `AppMain.cs` → `ServerManager.cs` | WinForms 单实例 + Kestrel |
-| 桌面窗口 | `Browser.cs`, `Launcher.cs` | WinForms，WebView2 嵌入前端 |
+| 谱面导入/解析 | `Controllers/Charts/Services/`, `MaiLib/`, `SimaiSharp/` | MaiLib 和 SimaiSharp 是 submodule |
+| 应用启动流程 | `Program.cs` → `AppMain.cs` → `ServerManager.cs` | 单实例 + Kestrel + WebView2 |
+| 桌面窗口 | `Browser.cs`, `OobeBrowser.cs`, `Launcher.cs` | Browser=主窗口, OobeBrowser=引导页, Launcher=无WebView2时的旧壳 |
 | IAP/授权 | `IapManager.cs`, `OfflineReg.cs` | Windows Store IAP |
-| CLI 工具 | `MaiChartManager.CLI/` | `makeusm`, `makeacb` 命令 |
+| CLI 工具 | `MaiChartManager.CLI/` | `makeusm`, `makeacb`, `makemp4`, `makeab` 命令 |
 | AquaMai mod 配置 | `Controllers/Mod/`, `Models/AquaMaiConfigDto.cs` | 管理游戏 mod 的安装和配置 |
-| 打包发布 | `Packaging/Build.ps1` | PowerShell，MSIX 打包 |
+| UI 组件库 | `MuNET-UI/` | @munet/ui, defineComponent + JSX，submodule |
+| 谱面格式转换 | `MuConvert/` | ANTLR 解析，submodule |
+| 打包发布 | `Packaging/Build.ps1` | PowerShell, dotnet publish → makeappx |
 
 ## CONVENTIONS
 
-- 构建配置：Debug / Release / Crack（三种，Crack 是特殊功能解锁）
-- 平台：仅 x64
-- 5 个 git submodule，各自有独立仓库，勿直接修改 submodule 内代码
-- 前端 API client 由 `genClient.ts` 自动生成，勿手动编辑 `apiGen.ts`
-- 前端包管理用 pnpm
-- 后端 ASP.NET Core 控制器按领域分子目录（App/AssetDir/Catagory/Charts/Mod/Music/Tools）
-- 注意：`Catagory` 是 typo（应为 Category），但已是既定命名，保持一致
+- **目标框架**：主程序 net10.0-windows，AquaMai net472，MaiLib net9.0
+- **构建配置**：Debug / Release / Crack（Crack 启用 `CRACK` 宏，Canary 发布用）
+- **Nullable + ImplicitUsings**：主程序开启，子项目不一定
+- **平台**：仅 x64
+- **7 个 git submodule**，各自有独立仓库，勿直接修改 submodule 内代码
+- **pnpm workspace**：根 `pnpm-workspace.yaml` 包含 `MaiChartManager/Front` 和 `MuNET-UI`
+- **前端 API client** 由 `genClient.ts` 使用 swagger-typescript-api 自动生成，勿手动编辑 `apiGen.ts`
+- **后端路由**：`[Route("MaiChartManagerServlet/[action]Api")]` 风格
+- **控制器按领域分子目录**：App / AssetDir / Catagory / Charts / Mod / Music / Tools
+- **`Catagory` 是 typo**（应为 Category），但已是既定命名，保持一致
 
 ## ANTI-PATTERNS
 
-- 不要修改 submodule 内的代码（AquaMai/MaiLib/SimaiSharp/SonicAudioTools/XV2-Tools）
+- 不要修改 submodule 内的代码（AquaMai/MaiLib/MuConvert/MuNET-UI/SimaiSharp/SonicAudioTools/XV2-Tools）
 - 不要手动编辑 `Front/src/client/apiGen.ts` 和 `aquaMaiVersionConfigApiGen.ts`
 - 不要修改 `*.Designer.cs` 文件（WinForms 自动生成）
+- 不要手动编辑 `wwwroot/`（前端构建产物，通过 `pnpm build` 生成）
+- 不要修改 `Python/`、`FFMpeg/`、`WannaCRI/` 目录（嵌入式运行时）
+- 不要在 `Models/` 里写业务逻辑，只放纯数据结构
+- 不要用 npm 或 yarn，统一使用 pnpm
 
 ## COMMANDS
 
 ```bash
-# 构建（需要 Visual Studio 或 dotnet CLI）
+# 构建
 dotnet build Sitreamai.slnx -c Release
 
-# 前端开发
+# 前端开发（dev server 端口 5182，代理后端 5181）
 cd MaiChartManager/Front && pnpm install && pnpm dev
 
-# 前端构建
+# 前端构建（输出到 ../wwwroot）
 cd MaiChartManager/Front && pnpm build
 
-# 生成 API client
-cd MaiChartManager/Front && npx ts-node genClient.ts
+# 生成 API client（需先启动后端 localhost:5181）
+cd MaiChartManager/Front && pnpm genClient
 
-# 打包
+# 打包（Release 或 Canary）
 powershell Packaging/Build.ps1
+powershell Packaging/Build.ps1 -Mode Canary
 ```
 
 ## NOTES
 
-- 项目混合了 WinForms（桌面壳）+ ASP.NET Core（本地 API server）+ Vue 3（前端 SPA）的非常规架构
-- Browser.cs 用 WebView2 加载前端，前端通过 localhost API 与后端通信
-- Python 和 FFmpeg 是嵌入式运行时，打包在应用内
-- MaiChartManager.CLI 共享主项目的部分代码，但是独立的 csproj
+- 非常规混合架构：WinForms 桌面壳 + ASP.NET Core 本地 API server + Vue 3 SPA + WebView2
+- Browser.cs 通过 WebView2 加载前端，注入 `globalThis.backendUrl`，前端通过 localhost API 通信
+- Python 和 FFmpeg 是嵌入式运行时，通过 csproj CopyToOutputDirectory 打包
+- MaiChartManager.CLI 共享主项目部分代码，但是独立 csproj
+- CI 构建分两步：Linux 上 pnpm build 前端 → self-hosted Windows 上 dotnet publish + makeappx
+- Canary 发布使用 Crack 配置，产物上传到 Alist 而非 GitHub Release
+- 前端 `genClient.ts` 从两个 OpenAPI 源生成：本地后端 swagger + 远端 AquaMai 版本配置

AGENTS.md

@@ -17,45 +17,51 @@ MaiChartManager/
 ├── Attributes/           # 自定义 Attribute
 ├── Locale/               # i18n 资源文件
 ├── Libs/                 # 打包进来的第三方库
-├── Python/               # 嵌入式 Python 运行时（勿修改）
-├── FFMpeg/               # 嵌入式 FFmpeg（勿修改）
-├── WannaCRI/             # CRI 音频工具，Python 打包（勿修改）
-├── Resources/            # 应用资源
-└── wwwroot/              # 前端构建产物（勿手动修改）
+├── Python/               # ⚠️ 嵌入式 Python 运行时（勿修改）
+├── FFMpeg/               # ⚠️ 嵌入式 FFmpeg（勿修改）
+├── WannaCRI/             # ⚠️ CRI 音频工具（勿修改）
+├── Resources/            # 应用资源（JudgeDisplay4B 等）
+└── wwwroot/              # ⚠️ 前端构建产物（勿手动修改）
 ```
 
 ## WHERE TO LOOK
 
 | 任务 | 文件 | 说明 |
 |------|------|------|
 | 应用启动流程 | `Program.cs` → `AppMain.cs` → `ServerManager.cs` | 单实例 WinForms + Kestrel 启动 |
-| 桌面窗口 | `Browser.cs`, `Launcher.cs` | Browser.cs 用 WebView2 嵌入前端 |
-| Kestrel 配置 | `ServerManager.cs` | 本地 web server 设置 |
+| 桌面窗口 | `Browser.cs`, `OobeBrowser.cs`, `Launcher.cs` | Browser=主窗口(WebView2), OobeBrowser=引导页, Launcher=旧壳 |
+| Kestrel/DI 配置 | `ServerManager.cs` | 注册服务、CORS、Swagger、认证中间件 |
 | 应用配置 | `Config.cs`, `StaticSettings.cs` | 运行时配置和静态常量 |
 | IAP / 授权 | `IapManager.cs`, `OfflineReg.cs` | Windows Store IAP，离线注册 |
-| 请求鉴权 | `AuthenticationMiddleware.cs` | ASP.NET Core 中间件 |
+| 请求鉴权 | `AuthenticationMiddleware.cs` | 可选启用的 ASP.NET Core 中间件 |
 | XML 数据模型 | `Models/MusicXml.cs`, `GenreXml.cs`, `VersionXml.cs` | maimai 谱面元数据结构 |
+| 增强型模型 | `Models/MusicXmlWithABJacket.cs` | API 返回时附带封面等附加信息 |
 | AquaMai 配置模型 | `Models/AquaMaiConfigDto.cs` | mod 配置 DTO |
-| Simai 谱面导入 | `Services/MaidataImportService.cs` | 解析并导入 Simai 格式谱面 |
+| 谱面导入服务 | `Controllers/Charts/Services/` | `IMaidataImportService` 接口 + 新旧两套实现 |
 | 音频处理 | `Utils/Audio.cs`, `AudioConvert.cs`, `CriUtils.cs` | FFmpeg + CRI SDK 封装 |
 | 视频/图片处理 | `Utils/VideoConvert.cs`, `ImageConvert.cs` | 媒体转换工具 |
 | maimai 工具函数 | `Utils/MaiUtils.cs` | 谱面相关通用工具 |
 | Windows 工具函数 | `Utils/WinUtils.cs` | Win32 API 封装 |
-| AquaMai 工具 | `Utils/AquaMaiConfigExtensions.cs`, `AquaMaiSignatureV2.cs` | mod 配置扩展和签名 |
+| AquaMai 签名/配置 | `Utils/AquaMaiConfigExtensions.cs`, `AquaMaiSignatureV2.cs` | mod 配置扩展和签名 |
 | i18n | `Locale/Locale.resx`, `zh-hans/`, `zh-hant/` | 简体/繁体中文本地化 |
 
 ## CONVENTIONS
 
-- 启动顺序：`Program.cs`（入口）→ `AppMain.cs`（生命周期管理）→ `ServerManager.cs`（启动 Kestrel）
-- `Browser.cs` 通过 WebView2 加载前端，前端通过 localhost API 与后端通信
+- 启动顺序：`Program.cs`（单实例检查）→ `AppMain.cs`（生命周期管理、WebView2 检测、窗口选择）→ `ServerManager.cs`（构建并启动 Kestrel）
+- `Browser.cs` 通过 WebView2 加载前端，`InjectBackendUrl()` 注入 `globalThis.backendUrl`
+- `OobeBrowser.cs` 是首次启动引导页，路由到 `/oobe`
+- `Launcher.cs` 仅在无 WebView2 Runtime 时启用
 - `*.Designer.cs` 是 WinForms 自动生成文件，**不要手动编辑**
 - Controllers 按领域分 7 个子目录：App / AssetDir / Catagory / Charts / Mod / Music / Tools
-- `Catagory` 是已知 typo（应为 Category），但已是既定命名，**保持一致，不要修改**
-- `wwwroot/` 是 `Front/` 构建产物，不要手动修改，通过 `pnpm build` 生成
+- `Catagory` 是已知 typo（应为 Category），**保持一致，不要修改**
+- `wwwroot/` 是 `Front/` 构建产物，通过 `pnpm build` 生成
+- 服务注册在 `ServerManager.cs`：`StaticSettings`、导入服务、`MuModService`、`ModConfigService`、HttpClient
+- DI 模式：控制器构造注入服务，业务逻辑不用复杂中间层
 
 ## ANTI-PATTERNS
 
 - 不要修改 `Python/`、`FFMpeg/`、`WannaCRI/` 目录内容（嵌入式运行时）
 - 不要手动编辑 `wwwroot/`（前端构建产物）
 - 不要手动编辑 `*.Designer.cs`（WinForms 自动生成）
 - 不要在 `Models/` 里写业务逻辑，只放纯数据结构
+- 不要将 `AppMain.g.cs` 加入版本控制（由 `Packaging/Build.ps1` 生成版本号）

MaiChartManager/AGENTS.md

@@ -256,6 +256,9 @@ public static void SetLocale(string locale)
         Locale.Culture = culture;
         CultureInfo.CurrentCulture = culture;
         CultureInfo.CurrentUICulture = culture;
+        
+        // 给外部依赖库设置Locale
+        MuConvert.utils.Utils.SetLocale(new CultureInfo(locale));
 
         StaticSettings.Config.Save();
     }

MaiChartManager/AppMain.cs

@@ -3,5 +3,5 @@ namespace MaiChartManager;
 
     public partial class AppMain
     {
-        public const string Version = "26.0.0";
+        public const string Version = "26.1";
     }

MaiChartManager/AppMain.g.cs

@@ -1,4 +1,4 @@
-using System.Text.Json;
+using System.Text.Json;
 using System.Text.Json.Serialization;
 
 namespace MaiChartManager;
@@ -26,6 +26,7 @@ public class Config
     public bool NoScale { get; set; } = false;
     public bool IgnoreLevel { get; set; } = false;
     public bool DisableBga { get; set; } = false;
+    public bool UseLegacyMaiLib { get; set; } = false;
     public int UiZoom { get; set; } = 0;
 
     public void Save()

MaiChartManager/Config.cs

@@ -2,36 +2,39 @@
 
 ## OVERVIEW
 
-ASP.NET Core REST API 控制器，按业务领域分 7 个子目录，共 25 个控制器文件。
+ASP.NET Core REST API 控制器，按业务领域分 7 个子目录。所有控制器继承 `ControllerBase` + `[ApiController]`。
 
 ## STRUCTURE
 
 | 子目录 | 职责 | 主要文件 |
 |--------|------|----------|
-| `App/` | 应用状态、授权、版本、本地化 | AppLicenseController, AppStatusController, AppVersionController, LocaleController |
+| `App/` | 应用状态、授权、版本、本地化、设置 | AppLicenseController, AppStatusController, AppVersionController, LocaleController, SettingsController |
 | `AssetDir/` | 资源目录管理、冲突检测、本地资源、曲目列表 | AssetDirController, CheckConflictController, LocalAssetsController, MusicListController |
 | `Catagory/` | 版本分类、曲风分类管理 | AddVersionController, GenreController |
 | `Charts/` | 谱面 CRUD、预览、导入 | ChartController, ChartPreviewController, ImportChartController |
-| `Mod/` | AquaMai mod 配置、安装、路径管理 | ConfigurationController, InstallationController, ManualInstallController, ModPaths |
+| `Charts/Services/` | 谱面导入业务逻辑（领域内私有服务） | IMaidataImportService, MaidataImportService, LegacyMaidataImportService |
+| `Mod/` | AquaMai mod 配置、安装、路径管理 | ConfigurationController, InstallationController, ManualInstallController, MuModController |
 | `Music/` | 音乐 CRUD、音频/视频转换、批量操作、迁移、VRC 处理 | MusicController, MusicBatchController, CueConvertController, MovieConvertController, MusicTransferController, VrcProcessController |
-| `Tools/` | 独立音频/视频转换工具接口 | AudioConvertToolController, VideoConvertToolController |
+| `Tools/` | 独立音频/视频/图片转换工具接口 | AudioConvertToolController, VideoConvertToolController, ImageToAbToolController |
 
 ## WHERE TO LOOK
 
 | 任务 | 去哪里 |
 |------|--------|
 | 应用授权 / IAP 状态查询 | `App/AppLicenseController.cs` |
 | 应用版本检查 / 更新 | `App/AppVersionController.cs` |
+| 应用设置读写 | `App/SettingsController.cs` |
 | 多语言 / 本地化 | `App/LocaleController.cs` |
 | 资源目录增删改查 | `AssetDir/AssetDirController.cs` |
 | 导入时冲突检测 | `AssetDir/CheckConflictController.cs` |
 | 曲目列表读取 | `AssetDir/MusicListController.cs` |
 | 版本/曲风分类管理 | `Catagory/AddVersionController.cs`, `Catagory/GenreController.cs` |
 | 谱面增删改查 | `Charts/ChartController.cs` |
 | 谱面预览生成 | `Charts/ChartPreviewController.cs` |
-| 谱面导入（Simai/Ma2） | `Charts/ImportChartController.cs` |
+| 谱面导入（Simai/Ma2） | `Charts/ImportChartController.cs`（调用 `Charts/Services/` 的导入服务）|
 | AquaMai mod 配置读写 | `Mod/ConfigurationController.cs` |
 | AquaMai mod 安装/卸载 | `Mod/InstallationController.cs` |
+| MuMod 缓存/路径 | `Mod/MuModController.cs` |
 | 音乐增删改查 | `Music/MusicController.cs` |
 | 音乐批量操作 | `Music/MusicBatchController.cs` |
 | 音频格式转换（ACB/USM） | `Music/CueConvertController.cs` |
@@ -40,10 +43,15 @@ ASP.NET Core REST API 控制器，按业务领域分 7 个子目录，共 25 个
 | VRC 音频处理 | `Music/VrcProcessController.cs` |
 | 独立音频转换工具 | `Tools/AudioConvertToolController.cs` |
 | 独立视频转换工具 | `Tools/VideoConvertToolController.cs` |
+| 图片转 AB 工具 | `Tools/ImageToAbToolController.cs` |
 
 ## CONVENTIONS
 
+- **路由风格**：`[Route("MaiChartManagerServlet/[action]Api")]`，部分带参数如 `{assetDir}/{id:int}/{level:int}`
 - 新增控制器请放入对应业务子目录，不要堆在根目录
 - `Catagory/` 是历史 typo（正确拼写应为 Category），已是既定命名，保持一致，勿重命名
-- 前端 API client（`Front/src/client/apiGen.ts`）由 `genClient.ts` 从这些控制器自动生成，修改接口后需重新运行生成脚本
+- 前端 API client（`Front/src/client/apiGen.ts`）由 `genClient.ts` 从这些控制器自动生成，修改接口后需重新运行 `pnpm genClient`
 - `Mod/ModPaths.cs` 不是控制器，是 Mod 子目录的路径常量辅助类
+- `Charts/Services/` 是领域内私有服务层（非全局 `Services/`），仅 Charts 控制器使用
+- 控制器通过构造注入获取服务，返回强类型 DTO（非统一包装），部分 action 自行 try/catch 转业务结果
+- `ChartController.ReplaceChart()` 根据 `StaticSettings.Config.UseLegacyMaiLib` 在新旧导入实现间切换