feat(decoration): 添加装饰符支持及解析逻辑

- 新增装饰符类型定义和装饰符对象接口，支持 ABC 标准 v2.1/v2.2 的装饰符解析。
- 引入 DecorationParser 工具类，提供从字符串中提取装饰符的功能，支持符号形式和长格式的装饰符。
- 更新相关解析器以处理音符中的装饰符，确保装饰符与音符的正确关联。
- 在 ABC 解析器中增强对装饰符的支持，提升乐谱解析的准确性和灵活性。

该变更提升了 ABC 解析器对装饰符的处理能力，确保乐谱信息的准确解析和存储。

Author: Encaik

.cursor/rules/lib.mdc

@@ -23,3 +23,7 @@ alwaysApply: true
 - 布局层（layout目录）要尽可能保证不干涉数据，是基于数据进行布局计算，并且不侵入渲染
 - 布局层一定要注意是自底向上构建
 - 渲染层（render目录）要尽可能保证不干涉数据和布局，基于布局层进行渲染，基于数据层进行显示
+
+## 工作习惯
+
+- 除非明确要求，否则不需要输出md文档

packages/simple-notation/src/core/model/decoration.ts

@@ -0,0 +1,177 @@
+/**
+ * 装饰符（Decoration/Ornament）类型定义
+ *
+ * 根据 ABC 标准 v2.1/v2.2
+ * @see https://abcnotation.com/wiki/abc:standard:v2.1#decorations
+ */
+
+/**
+ * 装饰符类型
+ *
+ * ABC 支持两种表示方式：
+ * 1. 符号形式：. ~ H L M O P S T u v 等
+ * 2. 长格式：!trill!, !fermata!, !marcato! 等
+ */
+export enum SNDecorationType {
+  // 基本装饰符
+  STACCATO = 'staccato', // . 断奏
+  TENUTO = 'tenuto', // - 保持音
+  ACCENT = 'accent', // > < 重音
+  MARCATO = 'marcato', // ^ 强音
+
+  // 颤音和回音
+  TRILL = 'trill', // T !trill! 颤音
+  MORDENT = 'mordent', // M !mordent! 波音
+  LOWER_MORDENT = 'lower-mordent', // !lowermordent! 下波音
+  UPPER_MORDENT = 'upper-mordent', // !uppermordent! 上波音
+  PRALLTRILLER = 'pralltriller', // P !pralltriller! 回音
+  TURN = 'turn', // !turn! 回音
+
+  // 滑音和装饰音
+  SLIDE = 'slide', // !slide! 滑音
+  ROLL = 'roll', // R !roll! 滚奏
+
+  // 延音和休止
+  FERMATA = 'fermata', // H !fermata! 延音
+  FERMATA_BELOW = 'fermata-below', // !fermata-below! 下延音
+  FERMATA_ABOVE = 'fermata-above', // !fermata-above! 上延音
+  BREATH = 'breath', // !breath! 换气记号
+
+  // 琶音和和弦装饰
+  ARPEGGIO = 'arpeggio', // !arpeggio! 琶音
+
+  // 弓法（弦乐器）
+  UPBOW = 'upbow', // u !upbow! 上弓
+  DOWNBOW = 'downbow', // v !downbow! 下弓
+
+  // 力度记号
+  CRESCENDO = 'crescendo', // !crescendo(! 渐强开始
+  CRESCENDO_END = 'crescendo-end', // !crescendo)! 渐强结束
+  DIMINUENDO = 'diminuendo', // !diminuendo(! 渐弱开始
+  DIMINUENDO_END = 'diminuendo-end', // !diminuendo)! 渐弱结束
+
+  // 踏板记号（钢琴）
+  PEDAL_DOWN = 'pedal-down', // !ped! 踏板按下
+  PEDAL_UP = 'pedal-up', // !ped-up! 踏板抬起
+
+  // 特殊记号
+  SEGNO = 'segno', // !segno! 反复记号
+  CODA = 'coda', // !coda! 尾声记号
+  D_C = 'd.c.', // !D.C.! 从头反复
+  D_S = 'd.s.', // !D.S.! 从记号反复
+  FINE = 'fine', // !fine! 终止
+
+  // 编辑性记号
+  EDITORIAL = 'editorial', // !editorial! 编辑性记号
+  COURTESY = 'courtesy', // !courtesy! 提示性记号
+
+  // 其他
+  PLUS = 'plus', // + !plus! 加号
+  EMPHASIS = 'emphasis', // !emphasis! 强调
+  FINGERING = 'fingering', // 指法记号
+
+  // 自定义
+  CUSTOM = 'custom', // 自定义装饰符
+}
+
+/**
+ * 装饰符对象
+ */
+export interface SNDecoration {
+  /** 装饰符类型 */
+  type: SNDecorationType;
+  /** 原始文本（如 "!trill!", "T", "." 等） */
+  text: string;
+  /** 位置（above 或 below，某些装饰符支持） */
+  position?: 'above' | 'below';
+  /** 参数（如指法数字、自定义内容） */
+  parameter?: string;
+}
+
+/**
+ * 装饰符符号到类型的映射
+ *
+ * 根据 ABC 标准定义
+ */
+export const DECORATION_SYMBOL_MAP: Record<string, SNDecorationType> = {
+  // 基本符号形式
+  '.': SNDecorationType.STACCATO,
+  '~': SNDecorationType.ROLL,
+  H: SNDecorationType.FERMATA,
+  L: SNDecorationType.ACCENT,
+  M: SNDecorationType.MORDENT,
+  O: SNDecorationType.CODA,
+  P: SNDecorationType.PRALLTRILLER,
+  S: SNDecorationType.SEGNO,
+  T: SNDecorationType.TRILL,
+  u: SNDecorationType.UPBOW,
+  v: SNDecorationType.DOWNBOW,
+};
+
+/**
+ * 装饰符长格式到类型的映射
+ *
+ * 支持 !decoration! 格式
+ */
+export const DECORATION_LONG_MAP: Record<string, SNDecorationType> = {
+  // 颤音和回音
+  trill: SNDecorationType.TRILL,
+  mordent: SNDecorationType.MORDENT,
+  lowermordent: SNDecorationType.LOWER_MORDENT,
+  uppermordent: SNDecorationType.UPPER_MORDENT,
+  pralltriller: SNDecorationType.PRALLTRILLER,
+  turn: SNDecorationType.TURN,
+
+  // 滑音和装饰音
+  slide: SNDecorationType.SLIDE,
+  roll: SNDecorationType.ROLL,
+
+  // 延音
+  fermata: SNDecorationType.FERMATA,
+  'fermata-above': SNDecorationType.FERMATA_ABOVE,
+  'fermata-below': SNDecorationType.FERMATA_BELOW,
+  breath: SNDecorationType.BREATH,
+
+  // 琶音
+  arpeggio: SNDecorationType.ARPEGGIO,
+
+  // 弓法
+  upbow: SNDecorationType.UPBOW,
+  downbow: SNDecorationType.DOWNBOW,
+
+  // 力度
+  'crescendo(': SNDecorationType.CRESCENDO,
+  'crescendo)': SNDecorationType.CRESCENDO_END,
+  'diminuendo(': SNDecorationType.DIMINUENDO,
+  'diminuendo)': SNDecorationType.DIMINUENDO_END,
+  '<(': SNDecorationType.CRESCENDO,
+  '<)': SNDecorationType.CRESCENDO_END,
+  '>(': SNDecorationType.DIMINUENDO,
+  '>)': SNDecorationType.DIMINUENDO_END,
+
+  // 踏板
+  ped: SNDecorationType.PEDAL_DOWN,
+  'ped-up': SNDecorationType.PEDAL_UP,
+
+  // 特殊记号
+  segno: SNDecorationType.SEGNO,
+  coda: SNDecorationType.CODA,
+  'D.C.': SNDecorationType.D_C,
+  'D.S.': SNDecorationType.D_S,
+  fine: SNDecorationType.FINE,
+
+  // 编辑性记号
+  editorial: SNDecorationType.EDITORIAL,
+  courtesy: SNDecorationType.COURTESY,
+
+  // 基本装饰
+  staccato: SNDecorationType.STACCATO,
+  tenuto: SNDecorationType.TENUTO,
+  accent: SNDecorationType.ACCENT,
+  marcato: SNDecorationType.MARCATO,
+  emphasis: SNDecorationType.EMPHASIS,
+
+  // 其他
+  '+': SNDecorationType.PLUS,
+  plus: SNDecorationType.PLUS,
+};

packages/simple-notation/src/core/model/index.ts

@@ -1,2 +1,3 @@
 export * from './music';
 export * from './ticks';
+export * from './decoration';

packages/simple-notation/src/data/model/abc.ts

@@ -25,8 +25,9 @@ export interface SNRootMeta {
  * 2. ABC 特有的元数据仅存储在 meta 中（不参与布局渲染）：
  *    - origin, area, notes, copyright, noteLength 等
  *
- * 根据 ABC 标准 v2.1
+ * 根据 ABC 标准 v2.1/v2.2
  * @see https://abcnotation.com/wiki/abc:standard:v2.1
+ * @see https://abcnotation.com/wiki/abc:standard:v2.2
  */
 export interface SNScoreMeta {
   /** 来源/国家（O: 字段）- ABC 特有 */
@@ -35,11 +36,27 @@ export interface SNScoreMeta {
   area?: string;
   /** 注释（N: 字段）- ABC 特有 */
   notes?: string;
-  /** 版权信息（S: 字段在头部时）- ABC 特有 */
+  /** 版权信息/来源（S: 字段在头部时）- ABC 特有 */
   copyright?: string;
+  /** 节奏类型（R: 字段，如 "Jig", "Reel", "Waltz"）- ABC 特有 */
+  rhythm?: string;
+  /** 转录者信息（Z: 字段）- ABC 特有 */
+  transcription?: string;
+  /** 历史信息（H: 字段）- ABC 特有 */
+  history?: string;
+  /** 唱片信息（D: 字段）- ABC 特有 */
+  discography?: string;
+  /** 书籍来源（B: 字段）- ABC 特有 */
+  book?: string;
+  /** 文件 URL（F: 字段）- ABC 特有 */
+  fileUrl?: string;
+  /** 组/集合（G: 字段）- ABC 特有 */
+  group?: string;
+  /** 乐曲结构（P: 字段，如 "AABB", "ABAC"）- ABC 特有 */
+  parts?: string;
   /** 默认音符长度（L: 字段，如 "1/4", "1/8"）- ABC 特有，已转换为 timeUnit 存储在 props 中 */
   noteLength?: string;
-  /** 其他 ABC 特有的字段（H:, G:, R:, Z:, D:, F:, B: 等） */
+  /** 其他 ABC 特有的字段 */
   [key: string]: unknown;
 }
 

packages/simple-notation/src/data/node/note.ts

@@ -1,4 +1,4 @@
-import { SNPitch } from '@core/model/music';
+import { SNPitch, SNDecoration } from '@core/model';
 import { SNParserNode, SNParserChord } from '@data/node';
 
 /**
@@ -11,6 +11,7 @@ import { SNParserNode, SNParserChord } from '@data/node';
  * - duration: 时值（以 ticks 为单位）
  * - articulation: 演奏方式（断奏、连奏、保持音等）
  * - chords: 关联的和弦标记（可选）
+ * - decorations: 装饰符列表（颤音、波音、延音等）
  */
 export class SNParserNote extends SNParserNode {
   /** 音高信息（音名、八度、变音记号） */
@@ -19,6 +20,8 @@ export class SNParserNote extends SNParserNode {
   articulation?: 'staccato' | 'legato' | 'tenuto';
   /** 关联的和弦标记（可选，用于显示和弦符号） */
   chords?: SNParserChord;
+  /** 装饰符列表（颤音、波音、延音等） */
+  decorations?: SNDecoration[];
 
   /**
    * 创建音符节点

packages/simple-notation/src/data/parser/abc-parser.ts

@@ -304,7 +304,8 @@ export class AbcParser extends BaseParser<SNAbcInput> {
     const musicMeasures = musicContent
       .split('|')
       .map((measure) => measure.trim())
-      .filter(Boolean);
+      .filter(Boolean)
+      .filter((measure) => this.isValidMeasure(measure));
 
     // 解析歌词
     const lyricsMap = this.lyricParser.parseLyrics(lyricLines, musicMeasures);
@@ -326,6 +327,33 @@ export class AbcParser extends BaseParser<SNAbcInput> {
     );
   }
 
+  /**
+   * 判断是否为有效的小节
+   *
+   * 有效的小节应该包含实际的音乐内容（音符、休止符等），
+   * 而不是只包含行内标记（如 [K:C]、[V:1]、[M:4/4] 等）
+   *
+   * @param measureData - 小节数据字符串
+   * @returns 是否为有效小节
+   */
+  private isValidMeasure(measureData: string): boolean {
+    // 移除所有行内标记
+    const withoutInlineFields = measureData
+      .replace(/\[[A-Za-z]:[^\]]*\]/g, '')
+      .trim();
+
+    // 移除小节线标记
+    const withoutBarlines = withoutInlineFields.replace(/^:|:$/g, '').trim();
+
+    // 如果移除行内标记和小节线后还有内容，说明包含实际音乐内容
+    if (withoutBarlines.length > 0) {
+      return true;
+    }
+
+    // 如果只剩空白，说明这不是有效的小节
+    return false;
+  }
+
   /**
    * 从父节点获取时间单位
    */

packages/simple-notation/src/data/parser/abc/parsers/element-parser.ts

@@ -9,7 +9,7 @@ import {
   SNParserNode,
 } from '@data/node';
 import { noteValueToDuration } from '@core/utils/time-unit';
-import { AbcTokenizer } from '../utils';
+import { AbcTokenizer, DecorationParser } from '../utils';
 import { ElementParseError } from '../errors';
 
 /**
@@ -69,8 +69,12 @@ export class AbcElementParser {
       throw new ElementParseError(elementData);
     }
 
+    // 0. 提取装饰符（如果有）
+    const { decorations, noteStr } =
+      DecorationParser.separateDecorations(trimmed);
+
     // 1. 解析连音线
-    if (trimmed === '-') {
+    if (noteStr === '-') {
       return new SNParserTie({
         id: this.getNextId('tie'),
         style: 'slur',
@@ -79,7 +83,7 @@ export class AbcElementParser {
     }
 
     // 2. 解析连音（Tuplet）
-    const tupletMatch = trimmed.match(/^\((\d+)([\s\S]*?)\)?$/);
+    const tupletMatch = noteStr.match(/^\((\d+)([\s\S]*?)\)?$/);
     if (tupletMatch) {
       return this.parseTuplet(
         tupletMatch,
@@ -90,16 +94,26 @@ export class AbcElementParser {
     }
 
     // 3. 解析休止符
-    if (trimmed.startsWith('z')) {
-      return this.parseRest(trimmed, elementData, timeUnit, defaultNoteLength);
+    if (noteStr.startsWith('z')) {
+      return this.parseRest(noteStr, elementData, timeUnit, defaultNoteLength);
     }
 
-    // 4. 解析音符
-    const noteMatch = trimmed.match(
+    // 4. 解析音符（带装饰符）
+    const noteMatch = noteStr.match(
       /^(\^+\/?|_+\/?|=?)([A-Ga-g])([,']*)(\d*)(\.*)$/,
     );
     if (noteMatch) {
-      return this.parseNote(noteMatch, trimmed, timeUnit, defaultNoteLength);
+      const note = this.parseNote(
+        noteMatch,
+        noteStr,
+        timeUnit,
+        defaultNoteLength,
+      );
+      // 将装饰符附加到音符
+      if (decorations.length > 0) {
+        note.decorations = decorations;
+      }
+      return note;
     }
 
     throw new ElementParseError(elementData);