燕云十六声琴谱 · 36 键 / 21 键按键谱
做什么、不做什么
- 做：用户给一首歌的简谱（截图、照片、PDF 截图或直接贴文字），你按
references/format.md把它转写成文本谱，再用脚本校验、出谱： - 燕云十六声 · 36 键（默认，
--game yysls36）：三排，上排Q W E R T Y U= 高音、中排A S D F G H J= 中音、下排Z X C V B N M= 低音；每排 12 个音，升半音按住 Shift（#1、#4、#5），降半音按住 Ctrl（b3、b7）。 - 燕云十六声 · 21 键（
--game yysls21）：同样三排字母，只有自然音，没有半音。 - 游戏里自由演奏按 F1 可以在 36 键和 21 键之间切换；用户没说就出 36 键，并提一句「如果你用的是 21 键模式告诉我」。
- 电脑版写键名：
↑A= 按住 Shift 按 A，↓D= 按住 Ctrl 按 D；红字上排、黑字中排、蓝字下排。 - 手机版写简谱数字（带 #/b）：上面带点 = 上排，下面带点 = 下排，按琴面上的数字找键。
- 文字版直接贴在对话里；PNG 谱图横版 1920×1080，一行 3 小节，右上角带琴面示意图。
- 自动选调：36 键挑要按 Shift/Ctrl 最少的调；21 键挑弹不了的音最少的调，躲不开的半音换成相邻的自然音（谱里带
*，PNG 上是橙底），谱末逐个写「原来是哪个音、换成了什么、另一个候选是什么」；超音域的音挪一个八度。 - 按段落抽出高潮版。
- 不做：
- 逆水寒（手游、端游）不支持：查不到可靠的默认键位表，手游键位还能随便改（见
references/keymap.md）。用户要逆水寒谱时如实说明；可以给燕云 36 键的手机版谱（简谱数字 + 高低点 + 升降号）让他当音高参考，但要讲清楚这不是逆水寒的按键谱。 - 不接受音频转谱。用户发 mp3、视频或只给歌名让你扒谱时，直接说明：带伴奏的歌自动扒谱，音高和节奏会错很多，请提供这首歌的简谱（截图、照片或文字都行）。
- 不做任何自动演奏、按键脚本、宏、连点器；只出谱给人照着练。用户要「自动弹」，就说明本技能只出谱。
- 不帮用户去网上抓付费或受版权保护的曲谱。用户只给歌名时，请用户自己提供简谱。
- 不管 NPC 选曲小游戏（6 键音游），那个跟着屏幕提示按就行。
使用流程
- 拿到简谱：看清调号（1=?）、拍号（2/4、3/4、4/4、6/8）、速度标记，以及每个音的高低点、下划线、附点、连音线、三连音和反复记号。图片不清楚或缺页，先问用户要清晰版本。
- 转写：严格按
references/format.md写成文本谱，存成曲名.txt（UTF-8）。升降号照抄，不要自己改音，选调和替代交给脚本。副歌段落名里写「副歌」或「高潮」。 - 校验，直到通过：
python {baseDir}/scripts/score.py check 曲名.txt [--game yysls36|yysls21]
报错格式是「第 N 行 第 M 小节：……」，回原谱对照那一小节改转写。最常见的错是：漏了下划线、附点没算进拍数、跨小节连音没写 -、升号只写了第一次。只有提醒、没有错误时可以继续。check 最后会说推荐哪个调、还有几个音弹不了。
4. 出文字版按键谱（默认电脑版和手机版都出，自动推荐移调）：
python {baseDir}/scripts/score.py keys 曲名.txt [--game yysls36|yysls21] [--layout both|pc|mobile] [--mode auto|c|orig] [--shift N] [--replace near|mark] [--out 琴谱.txt]
--mode auto（默认）按上面的规则挑调，并给出理由；c= C 调；orig= 原调（能跟原唱伴奏合上）；--shift N手动移 N 个半音。--replace near（默认）就近替代；mark= 弹不了的音记?空着，谱末只给建议。- 用户说「电脑」就
--layout pc，说「手机」就--layout mobile；说「21 键」就加--game yysls21。
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]
不写 --section 时自动选段名带「高潮/副歌」的段；抽出的文件会自动校验，之后照第 4、5 步出谱。
样例谱在 assets/sample_*.txt：欢乐颂、小星星、两只老虎、茉莉花、致爱丽丝、绿袖子，全部是公有领域曲目。致爱丽丝、绿袖子带半音，用来演示 36 键的 Shift/Ctrl 和 21 键的就近替代。assets/ 里还有四张样图。
键位要点
详见 references/keymap.md（键位表、来源链接、核对日期、没核实的地方）。
| 琴面 | 1 | #1 | 2 | b3 | 3 | 4 | #4 | 5 | #5 | 6 | b7 | 7 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 上排（高音） | Q | ↑Q | W | ↓E | E | R | ↑R | T | ↑T | Y | ↓U | U |
| 中排（中音） | A | ↑A | S | ↓D | D | F | ↑F | G | ↑G | H | ↓J | J |
| 下排（低音） | Z | ↑Z | X | ↓C | C | V | ↑V | B | ↑B | N | ↓M | M |
↑ = 按住 Shift，↓ = 按住 Ctrl。21 键模式只有不带箭头的 21 个键。音域两种模式都是 1,…7'（C3–B5）。
完整小例子：《小星星》1=C 4/4 1 1 5 5 | 6 6 5 - | 转写为 1 1 5 5 | 6 6 5:2，36 键电脑版出谱：
第 1-4 小节 │ A A G G │H H G - │F F D D │S S A - │
输出怎么说话
- 先一句话报结果：曲名、36 键还是 21 键、用的哪个调、要按 Shift/Ctrl 的音几个（36 键）或要替代几个音（21 键）；然后把脚本输出的移调建议原样说一遍。
- 文字版按键谱用代码块原样贴出，不要自己改写、合并或"美化"，对齐靠等宽字体。谱末的「弹不了的音」清单要一起贴。
- 谱图给出文件路径；有多页就逐个列出。
- 转写中有猜测的地方（看不清、缺页、装饰音省略、反复已展开）要明确列出来，让用户核对。
- 手机版要提醒一句：手机琴面的样子没核实到官方图文，按琴面上的简谱数字找键；对不上告诉我。
- 不评价歌曲，不加练习鸡汤。用户问「怎么练」时只给具体建议：先慢速（把 bpm 调低重出谱）、先练高潮段（clip）、Shift/Ctrl 的音单独多练几遍；21 键带
*的替代音觉得别扭就换谱末写的另一个候选，或者切到 36 键模式。
边界
- 只处理单声部旋律：和弦只取最高音，装饰音去掉。
- 21 键没有半音，带大量半音的曲子替代后会走样；谱末会逐个列出。36 键没有这个问题。
- 节拍网格为每拍 24 格，常见的 1/2、1/3、1/4、1/6、1/8 拍都能准确表示；更碎的时值（如五连音）会被近似，check 会提醒。
- 文字版里同一拍内的音用
_连接，看不出下划线条数；要看精确节奏请看 PNG 谱图。 - 键位来自玩家社区的开源项目源码和讨论，不是官方文字说明；手机琴面、各乐器是否共用同一块键盘没有逐个核实，见
references/keymap.md。 - 用户提供的谱子仅供个人练习；不帮用户去网上抓付费或受版权保护的谱，也不把用户的谱子分享到别处。
- 本技能不包含、也不会生成任何键鼠自动化或自动演奏代码。
