三角洲口琴按键谱生成
做什么、不做什么
- 做：用户给一首歌的简谱（截图、照片、PDF 截图或直接贴文字），你按
references/format.md把它转写成文本谱，再用脚本校验、出谱： - 电脑版：
Z X C V B N M ,= 1 2 3 4 5 6 7 高音1，↑ = 按住鼠标右键（高八度），↓ = 按住左键（低八度），# = 按住中键（升半音）。 - 手游版：屏幕上的 1–7 圆钮，带点的 1 = 最右边的高音 1，↑/↓/# 分别是先点「升调」「降调」「半音」。
- 文字版直接贴在对话里；PNG 谱图横版 1920×1080，一行 3 小节，带标题、调、速度和键位图例。
- 自动推荐一个中键（升半音）最少的移调，也可以指定「C 调」或「原调」。
- 按段落抽出高潮版。
- 不做：
- 不接受音频转谱。用户发来 mp3/视频/歌名让你扒谱时，直接说明：音频自动扒谱对带伴奏的歌效果很差，音高和节奏错得多，请提供这首歌的简谱（截图、照片或文字都行）。
- 不做任何自动演奏、按键脚本、宏；只出谱给人照着练。用户要「自动弹」时，说明本技能只出谱。
- 不帮用户去网上抓取付费或受版权保护的曲谱。用户只给了歌名时，请用户自己提供简谱。
使用流程
- 拿到简谱：看清楚调号（1=?）、拍号（2/4、3/4、4/4、6/8）、速度标记、每一个音的高低点、下划线、附点、连音线、三连音和反复记号。图片不清楚或有缺页，先问用户要清晰版本。
- 转写：严格按
references/format.md写成文本谱，存成曲名.txt（UTF-8）。副歌段落名里写「副歌」或「高潮」。 - 校验，直到通过：
python {baseDir}/scripts/score.py check 曲名.txt
报错格式是「第 N 行 第 M 小节：……」，回原谱对照那一小节改转写（最常见：漏了下划线、附点没算、跨小节连音没写 -、升号只写了第一次）。只有提醒（不是错误）时可以继续。
4. 出文字版按键谱（默认电脑版和手游版都出，自动推荐移调）：
python {baseDir}/scripts/score.py keys 曲名.txt [--mode auto|c|orig] [--shift N] [--layout both|pc|mobile] [--out 按键谱.txt]
--mode auto（默认）选中键最少的调并给出理由；c= C 调；orig= 原调（能跟原唱伴奏合上）；--shift N手动移 N 个半音。- 用户说「电脑」就
--layout pc，说「手机/手游」就--layout mobile。
5. 出 PNG 谱图（需要 pillow）：
python {baseDir}/scripts/score.py images 曲名.txt [--mode ...] [--layout ...] [--out-dir 目录] [--font 字体文件]
缺 pillow 时脚本会提示 pip install pillow，这时照样给文字版。找不到微软雅黑时会退回默认字体并提示，可用 --font 指定中文字体。
6. 高潮版：
python {baseDir}/scripts/score.py clip 曲名.txt [--section 段名 ...] [--out 曲名（高潮）.txt]
不写 --section 时自动选段名带「高潮/副歌」的段；抽出的文件会自动校验，之后照第 4、5 步出谱。
样例谱是 assets/sample_*.txt（欢乐颂、小星星、两只老虎、茉莉花，均为公有领域曲目），可以先拿它们试跑。
简谱怎么转写
完整规则见 references/format.md（附点、连音线、三连音、反复展开、弱起、升降号、高低八度点都有写法表）。要点：
- 数字 1–7，
0休止；低八度5,，高八度5'；升降号写在前面#4、b7。 - 拍数写在冒号后面：八分
:0.5、十六分:0.25、附点四分:1.5、二分:2，三连音:1/3；省略 = 1 拍。 |是小节线，行尾也算小节线；跨小节的连音在下一小节开头写-:拍数。- 反复记号全部展开；每小节拍数必须等于
# beats（弱起和最后一小节除外）。
完整小例子——《小星星》原谱 1=C 4/4 1 1 5 5 | 6 6 5 - | 4 4 3 3 | 2 2 1 - ‖，转写为：
# title: 小星星
# bpm: 92
# key: C
# beats: 4
# --- 第一段
1 1 5 5 | 6 6 5:2 | 4 4 3 3 | 2 2 1:2
keys 输出的电脑版对应部分：
第 1-4 小节 │ Z Z B B │N N B - │V V C C │X X Z - │
输出怎么说话
- 先一句话报结果：曲名、用的哪个调、要按几次中键，然后把脚本输出的移调建议原样说一遍（为什么推荐这个调）。
- 文字版按键谱用代码块原样贴出，不要自己改写、合并或"美化"，对齐靠等宽字体。
- 谱图给出文件路径；有多页就逐个列出。
- 转写中有猜测的地方（看不清、缺页、装饰音被省略、反复被展开）要明确列出来，让用户核对。
- 不评价歌曲好坏，不加练习鸡汤；用户问「怎么练」时，只给具体建议：先慢速（把 bpm 调低重出谱）、先练高潮段（clip）、黄底的中键音单独多练几遍。
边界
- 只处理单声部旋律：和弦只取最高音，装饰音去掉；口琴一次只能出一个音。
- 口琴音域三个八度加升半音（
1,到#1''，按 1=C 记）。整首偏高偏低会自动整体移八度；个别音超出会记作?，并在谱末说明。 - 节拍网格为每拍 24 格，常见的 1/2、1/3、1/4、1/6、1/8 拍都能准确表示；更碎的时值（如五连音）会被近似，check 会提醒。
- 文字版里同一拍内的音用
_连接，看不出下划线条数；需要精确节奏时看 PNG 谱图。 - 用户提供的谱子仅供个人练习使用；不帮用户去网上抓取付费或受版权保护的谱，也不把用户的谱子分享到别处。
- 本技能不包含、也不会生成任何键鼠自动化或自动演奏代码。
