卡林巴拇指琴谱 · 简谱转卡林巴数字谱（17 音 / 10 音）
做什么、不做什么
- 做：用户给一首歌的简谱（截图、照片、PDF 截图或直接贴文字），你按
references/format.md把它转写成文本谱，再用脚本校验、出谱： - 17 音 C 调（默认，
--notes 17）：音域 C4–E6（简谱1…3''）。 - 10 音 C 调（
--notes 10）：音域 C4–E5（简谱1…3'）。 - 数字谱（
num）：和琴键上刻的字一样——数字 1–7，上面一个点 = 高音，两个点 = 倍高音。 - 位置谱（
pos）：中= 中间最长那根，左N/右N= 从中间往左 / 往右数第 N 根。蓝字左手、红字右手。 - 文字版直接贴在对话里；PNG 谱图横版 1920×1080，一行 3 小节，右上角画了琴键示意图（每根键的刻字和位置）。
- 没有半音的处理：自动挑「弹不了的音」最少的移调；躲不开的半音换成相邻的自然音（谱里带
*，PNG 上是橙底），超音域的音挪一个八度；谱末逐个列出改了什么，并给出另一个候选。 - 按段落抽出高潮版。
- 不做：
- 不接受音频转谱。用户发 mp3、视频或只给歌名让你扒谱时，直接说明：带伴奏的歌自动扒谱，音高和节奏会错很多，请提供这首歌的简谱（截图、照片或文字都行）。
- 不帮用户去网上抓付费或受版权保护的曲谱。用户只给歌名时，请用户自己提供简谱。
- 不教改琴调音（把某根键调成半音），出谱一律按标准 C 调。
- 不含任何自动演奏代码。
使用流程
- 拿到简谱：看清调号（1=?）、拍号（2/4、3/4、4/4、6/8）、速度标记，以及每个音的高低点、下划线、附点、连音线、三连音和反复记号。图片不清楚或缺页，先问用户要清晰版本。问一句用户的琴是 17 音还是 10 音（没说就按 17 音）。
- 转写：严格按
references/format.md写成文本谱，存成曲名.txt（UTF-8）。升降号照抄，不要自己为了琴没有半音去改音。副歌段落名里写「副歌」或「高潮」。 - 校验，直到通过：
python {baseDir}/scripts/score.py check 曲名.txt [--notes 17|10]
报错格式是「第 N 行 第 M 小节：……」，回原谱对照那一小节改转写。最常见的错是：漏了下划线、附点没算进拍数、跨小节连音没写 -、升号只写了第一次。只有提醒、没有错误时可以继续。最后一行会说推荐哪个调、还有几个音弹不了。
4. 出文字版琴谱（默认数字谱和位置谱都出，自动推荐移调）：
python {baseDir}/scripts/score.py keys 曲名.txt [--notes 17|10] [--layout both|num|pos] [--mode auto|c|orig] [--shift N] [--replace near|mark] [--out 琴谱.txt]
--mode auto（默认）选弹不了的音最少的调，并给出理由；c= C 调；orig= 原调；--shift N手动移 N 个半音。--replace near（默认）就近替代；mark= 弹不了的音记?空着，谱末只给建议。- 用户只要「数字谱」就
--layout num，只要「位置 / 第几根」就--layout pos。
5. 出 PNG 谱图（需要 pillow）：
python {baseDir}/scripts/score.py images 曲名.txt [同上参数] [--out-dir 目录] [--font 字体文件]
缺 pillow 时脚本会提示 pip install pillow，这时照样给文字版。找不到微软雅黑时会退回默认字体并提示，可以用 --font 指定中文字体。
6. 高潮版：
python {baseDir}/scripts/score.py clip 曲名.txt [--section 段名 ...] [--out 曲名（高潮）.txt]
样例谱在 assets/sample_*.txt：欢乐颂、小星星、两只老虎、茉莉花、致爱丽丝，全部是公有领域曲目。致爱丽丝带 #2、#5，用来演示「就近替代」。assets/ 里还有两张样图。
键位规则
详见 references/keymap.md（17 音和 10 音的排列表、来源、就近替代的挑法）。要点：
- 中间最长那根是 C4（刻字 1），然后左右交替往外：左1 = 2，右1 = 3，左2 = 4，右2 = 5……
- 选调顺序：先比弹不了的音（半音 + 超音域）最少，再比超音域最少，然后依次是 C 调、原调、移动幅度小的。10 音琴装不下的歌多，常常会推荐移调。
完整小例子：《小星星》1=C 4/4 1 1 5 5 | 6 6 5 - | 转写为 1 1 5 5 | 6 6 5:2，17 音出谱：
数字谱 第 1-4 小节 │ 1 1 5 5 │6 6 5 - │4 4 3 3 │2 2 1 - │
位置谱 第 1-4 小节 │ 中 中 右2 右2 │左3 左3 右2 - │左2 左2 右1 右1 │左1 左1 中 - │
输出怎么说话
- 先一句话报结果：曲名、17 音还是 10 音、用的哪个调、有几个音弹不了；然后把脚本输出的移调建议原样说一遍。
- 文字版琴谱用代码块原样贴出，不要自己改写、合并或"美化"，对齐靠等宽字体。谱末的「弹不了的音」清单要一起贴。
- 谱图给出文件路径；有多页就逐个列出。
- 用 10 音出谱时，提醒用户对一下 PNG 右上角的琴键图：有的 10 音琴左右是镜像的。
- 转写中有猜测的地方（看不清、缺页、装饰音省略、反复已展开）要明确列出来，让用户核对。
- 不评价歌曲，不加练习鸡汤。用户问「怎么练」时只给具体建议：先慢速（把 bpm 调低重出谱）、先练高潮段（clip）、先看位置谱找键，熟了再看数字谱。
边界
- 只处理单声部旋律：和弦只取最高音，装饰音去掉（卡林巴可以弹和弦，但本技能不出和弦谱）。
- C 调卡林巴没有半音；带大量半音的曲子替代后会走样，谱末会逐个列出。
- 不支持 21 音、8 音等其他规格，也不支持非 C 调的卡林巴（可以先把琴当 C 调看，再用
--shift自己换算）。 - 节拍网格为每拍 24 格，常见的 1/2、1/3、1/4、1/6、1/8 拍都能准确表示；更碎的时值会被近似，check 会提醒。
- 文字版里同一拍内的音用
_连接，看不出下划线条数；要看精确节奏请看 PNG 谱图。 - 用户提供的谱子仅供个人练习；不帮用户去网上抓付费或受版权保护的谱，也不把用户的谱子分享到别处。
- 本技能不包含、也不会生成任何自动演奏代码。
