竖笛指法 · 陶笛谱 · 十孔口琴谱：简谱转指法

做什么、不做什么

做：用户给一首歌的简谱（截图、照片、PDF 截图或文字），你按 references/format.md 转写成文本谱，用脚本校验，再出指法谱：
- 竖笛：8 孔高音（Soprano）竖笛，--inst recorder-german（德式）或 --inst recorder-baroque（英式 / 巴洛克式）。小学课堂常用。
- 陶笛：--inst ocarina12（12 孔 AC 调，中音 C 调）或 --inst ocarina6（6 孔：4 指孔 + 2 拇指孔，C 调）。
- 十孔口琴：--inst harmonica（C 调 Richter 布鲁斯口琴），出孔位谱：4吹、4吸、3吸压半（压半音）、2吸压全（压全音）、3吸压1½、10吹压半。
- 竖笛、陶笛出 PNG 指法图：每个音上面画一个指法图（● 实心 = 按住，○ 空心 = 放开，◐ 半实心 = 半按），下面是简谱；另出一张「本曲指法表」。口琴也出 PNG（空心框 = 吹，实心框 = 吸，红字 = 压音）。
- 文字版直接贴在对话里，带「本曲指法」清单。
- 自动选调：在 12 个调里挑吹不出的音最少、特殊指法（半孔、叉指、压音）最少的调，再自动整体挪八度；也可以指定 C 调、原调或移几个半音。
- 吹不出的音（超音域、口琴要超吹才有的音）在谱里标 ? / 红色问号，谱末逐个列出第几小节、为什么。
不做：
- 不接受音频、视频或只给歌名扒谱：请用户提供简谱（截图、照片或文字都行）。
- 不帮用户去网上找付费或受版权保护的曲谱。
- 不做五线谱输出、不做和弦 / 双音；只处理单声部旋律。

先问清楚乐器

用户只说「竖笛」时问一句是德式还是英式：看笛子背面拇指孔下的字母，G = 德式，B = 英式（巴洛克式）；看不到就问「只按 0 1 2 3 4 吹中音 4（fa）准不准」，准的是德式。实在不知道就先出德式（国内小学最常见），并说明德式和英式只有中音 4、#4 和高音 4'、#4'、#5'、倍高音 #1'' 按法不同。
用户只说「陶笛」默认 12 孔 AC；说「6 孔」「挂坠陶笛」「小陶笛」用 ocarina6。
用户只说「口琴」时确认是十孔布鲁斯口琴（24 孔复音口琴、半音阶口琴不在本技能范围）；默认 C 调口琴。

使用流程

拿到简谱：看清调号（1=?）、拍号、速度、每个音的高低点、下划线、附点、连音线、三连音和反复记号。图片不清或缺页，先问用户要清晰版本。
转写：严格按 references/format.md 写成文本谱 曲名.txt（UTF-8）。副歌段落名里写「副歌」或「高潮」。
校验，直到通过（--inst 可顺便看这件乐器吹不吹得下）：
```
python {baseDir}/scripts/score.py check 曲名.txt --inst recorder-german
```
报错格式「第 N 行第 M 小节：……」，回原谱对照那一小节改转写。
文字版指法谱 / 孔位谱：
```
python {baseDir}/scripts/score.py tab 曲名.txt --inst <乐器> [--mode auto|c|orig] [--shift N] [--overblow] [--out 指法谱.txt]
```
- --mode auto（默认）自动选最好吹的调并给出理由；c = C 调；orig = 原调（能跟原唱伴奏合上）；--shift N 手动移 N 个半音。
- 口琴默认不用超吹 / 超吸；用户说自己会超吹再加 --overblow。
PNG 指法图（需要 pillow）：
```
python {baseDir}/scripts/score.py images 曲名.txt --inst <乐器> [--mode ...] [--out-dir 目录] [--font 字体文件]
```
生成 曲名_乐器_调.png（多页时带 _1、_2）和 曲名_乐器_调_指法表.png。缺 pillow 时脚本提示 pip install pillow，照样给文字版。
完整指法表（用户只想要某件乐器的指法表，不带曲子）：
```
python {baseDir}/scripts/score.py chart --inst <乐器> [--out-dir 目录]
```
高潮版：python {baseDir}/scripts/score.py clip 曲名.txt [--section 段名]，之后照第 4、5 步出谱。

样例谱：assets/sample_*.txt（欢乐颂、小星星、两只老虎、茉莉花，均为公有领域曲目）；assets/*_完整指法表.png 是各乐器指法总表。

乐器音域与规则（详见 `references/fingering.md`）

乐器	`--inst`	音域（中音 1 = C5）	半按
8 孔高音竖笛德式	`recorder-german`	1 ～ 2''（C5–D7）	拇指孔捏孔（高音区）、6/7 双孔只盖大孔（#1、#2、#5）
8 孔高音竖笛英式	`recorder-baroque`	1 ～ 2''（C5–D7）	同上
12 孔 AC 陶笛	`ocarina12`	6, ～ 4'（A4–F6）	#1 右小指半按
6 孔陶笛	`ocarina6`	1 ～ 3'（C5–E6）	#1 右上孔半按、#2 右下孔半按
十孔口琴 C 调	`harmonica`	1, ～ 1''（C4–C7）	压音：1、2、3、4、6 孔吸音，8、9、10 孔吹音

简谱一律按乐器的「C 调指法」写：竖笛全按 = 中音 1；12 孔陶笛全按（含副孔）= 低音 6；口琴 4 吹 = 中音 1。
移调后说「按 1=G 吹」的意思是：用这件乐器的 C 调指法体系，把 do 放在 G 上吹（谱面数字已经换好，照着吹就行）。

输出怎么说话

先一句话报结果：曲名、乐器、用的哪个调、有几个音吹不出（或全部吹得出）；然后把脚本输出的**【选调】**理由原样说一遍。
文字版用代码块原样贴出，不要改写、合并或美化；PNG 给出文件路径，多页逐个列出。
吹不出的音：原样列出脚本给的「第几小节、原因」，并给出办法（换调 --shift、让用户跳过、口琴会超吹就加 --overblow）。
转写中有猜测的地方（看不清、缺页、装饰音被省略、反复被展开）要明确列出来。
用户问「怎么练」：只给具体建议——先慢速（把 bpm 调低重出）、先练高潮段（clip）、半按和压音的音单独多练；竖笛高音区拇指捏孔留缝、气要轻；口琴压音先练 4 吸压半。

边界

只处理单声部旋律：和弦只取最高音，装饰音去掉。
指法以主流厂家标准按法为准（Yamaha 竖笛、Pure Ocarinas / 台湾式 12 孔陶笛）；各厂家半音叉指、副孔位置略有差别，提醒用户以乐器自带指法表为准。
12 孔陶笛的图是示意图：左列左手、右列右手、两侧小圈是副孔、下方两个是背面拇指孔，不是陶笛真实外形。
高音竖笛是移高八度记谱的乐器，本技能按书面音（C5 起）记。
用户提供的谱子仅供个人练习；不帮用户去网上抓取付费或受版权保护的谱。