[+] UgcGenerator新增extraHeaders参数，用于在UGC中添加自定义的头字段

Author: Starrah

README.md

@@ -167,6 +167,7 @@ var (ugcChart, alerts) = new UgcParser().Parse(ugcText); // 解析 UGC 谱面字
 
 var (c2sText, alerts) = new C2sGenerator().Generate(ugcChart);   // UGC -> C2S
 var (ugcText, alerts) = new UgcGenerator().Generate(c2sChart);   // C2S -> UGC
+// 若需在UGC的头部区域写入自定义的字段（如BGM、JACKET等），可向构造函数内传入一个List<(string, string)>参数，例如：new UgcGenerator([("BGM", "xxx.mp3"), ("JACKET", "xxx.png")]);
 // 各种Generator的Generate方法，均接受 ChuChart（可将任一 Parser 产出的 ChuChart 互相传入）。
 // 同上，alerts是生成过程中可能产生的警告信息等，建议打印出来。
 ```
@@ -208,6 +209,9 @@ var (ogkrText, alerts) = new OngekiGenerator().Generate(ogkChart); // 将 OgkCha
     - StrictLevelEnum `strictLevel` (默认为 `Normal`): 解析 Simai 时的严格程度（`Strict` / `Normal` / `Lax`），影响语法容错与报错策略。各个严格程度策略的具体含义，请参见上方[CLI文档](#基本用法)中的相关描述。
   - MA2Generator带有以下选项：
     - bool `isUtage` (默认为false): 仅影响生成的MA2的文件头区域的`FES_MODE`的值是1还是0，一般来说是不重要的。
+  - UgcGenerator带有以下选项：
+    - List<(string, string)> `extraHeaders` (默认为`null`即不添加额外的头字段)：在生成的UGC的头部区域中，写入额外的字段。
+      - `(string, string)`元组的第一项为字段名（不含`@`前缀），第二项为字段值；生成时会输出为 `@{字段名}\t{内容}`。
 
 #### 更多示例（异常处理）
 注意：当解析/生成步骤失败时，会抛出`ConversionException`异常，其中含有`Alerts`属性，是转谱过程中遇到的错误和警告等信息。（类比于C语言编译器会打印出Error和Warning信息）  

generator/chu/UgcGenerator.cs

@@ -10,6 +10,15 @@ public class UgcGenerator : IGenerator<ChuChart>
 {
     private int RSL = 480 * 4;
     private List<Alert> alerts = [];
+    public List<(string, string)> ExtraHeaders = [];
+
+    /**
+     * <param name="extraHeaders">在生成的UGC的HEAD区域，添加上额外的字段。</param>
+     */
+    public UgcGenerator(List<(string, string)>? extraHeaders = null)
+    {
+        if (extraHeaders != null) ExtraHeaders = extraHeaders;
+    }
 
     public (string, List<Alert>) Generate(ChuChart chart)
     {
@@ -48,6 +57,7 @@ void Dfs(ChuNote n)
     private string Serialize(ChuChart ugc)
     {
         ugc.Sort();
+        var extraHeaderKeys = ExtraHeaders.Select(x => x.Item1).ToHashSet();
 
         var sb = new StringBuilder();
         sb.AppendLine($"' Created with MuConvert v{Utils.AppVersion}");
@@ -62,6 +72,10 @@ private string Serialize(ChuChart ugc)
         sb.AppendLine(FormattableString.Invariant($"@CONST\t{ugc.Level:F5}"));
         var songId = !(string.IsNullOrEmpty(ugc.MusicId) || ugc.MusicId == "0") ? ugc.MusicId : $"MuC-{DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()}";
         sb.AppendLine($"@SONGID\t{songId}");
+        foreach (var (key, value) in ExtraHeaders)
+        { // 写入用户传入的ExtraHeaders中要求的字段
+            sb.AppendLine($"@{key}\t{value}");
+        }
         sb.AppendLine("@FLAG\tHIPRECISION\tTRUE"); // 表明，谱面中的高度使用的是两位高度而不是一位高度
         sb.AppendLine($"@TICKS\t{RSL / 4}");
         foreach (var met in ugc.MetList)
@@ -74,15 +88,15 @@ private string Serialize(ChuChart ugc)
             var (m, o) = Utils.BarAndTick(b.Time, RSL);
             sb.AppendLine(FormattableString.Invariant($"@BPM\t{m}'{o}\t{b.Bpm:F5}"));
         }
-        sb.AppendLine("@TIL\t0\t0'0\t1.00000");
+        if (!extraHeaderKeys.Contains("TIL")) sb.AppendLine("@TIL\t0\t0'0\t1.00000"); // 用户没有通过ExtraHeaders指定，则提供一个默认值
 
         foreach (var s in ugc.SflList.OrderBy(x => x.Time)) 
         { 
             var (m, o) = Utils.BarAndTick(s.Time, RSL); 
             sb.AppendLine(FormattableString.Invariant($"@SPDMOD\t{m}'{o}\t{s.Multiplier:0.00000}"));
         }
 
-        sb.AppendLine("@MAINTIL\t0");
+        if (!extraHeaderKeys.Contains("MAINTIL")) sb.AppendLine("@MAINTIL\t0"); // 用户没有通过ExtraHeaders指定，则提供一个默认值
         sb.AppendLine("@ENDHEAD");
         sb.AppendLine();