SUPER-NIUs 三角洲口琴谱生成 · 三角洲行动守夜人口琴
把简谱转成《三角洲行动》「守夜人口琴」的键盘键位谱，出一张白底 PNG 图。
产物是一张给人照着弹的图 —— 优先级永远是 清楚 > 好看 > 信息量，不是考据报告。
〇、四条铁律
1. 读谱只读一遍。 看不清的细节（八度点、附点、小节线）按最常见的情况处理，交付时提一句。 禁止分区放大重读、重复 OCR、"验证识别结果"、为同一行做二次核对。
例外：用户给的是低清图片时，"读一遍"要读得聪明。用
python3 scripts/read_jianpu.py 简谱.png -o 工作目录把八度点跑出来， 看一眼它生成的overlay.png（红圈=检测到的点，圈错圈漏一眼可见），再动手转写。 这仍然只算一轮，但远比肉眼看糊图可靠。方法细节见references/read-jianpu-image.md。
2. 不许追查版本。 同一首歌的 G 调 / D 调、简谱 / 吉他谱 / 弹唱谱来源必然对不上。 选一个用，交付时一行说明（如"按 D 调版本"），然后继续往下做。 禁止为确定"原版是什么调"去比对多个谱源、试唱验证、逐句交叉核对、判定"唯一标准"。
3. 核对最多一轮。 转写完扫一眼第六节清单，就可以交付。 不允许出现"我正在进一步验证……"这类反复推进。宁可交一份 95% 准的谱让用户指错， 也不要为了最后几个音无限核对。
4. 多出来的音符直接丢。 弹唱谱天然带装饰音，音符数多于歌词数是常态。按歌词取骨干音， 不要为了"用上"多余音符去改歌词，也不要去凑数。
这四条是硬性预算。超预算的核对 = 任务失败，不是认真。
一、范围
用户给了谱 → 按他给的那张谱做，给多少做多少，不要自己挑一段出来。 （他会给一张，说明那整张都是他要的。）
用户没给谱（只给歌名/音频）→ 才启用下面的预算，目的是防止为了找谱无限搜索：
- 只做一个段落：默认副歌；判断不出哪段是副歌，就取开头。不要搜整首歌。
- 长度 8–12 句，约一副歌即可。
- 检索次数 ≤ 2 次（找谱 1 次 + 补细节最多 1 次）。搜不到就直接说"需要你提供简谱"，不要硬凑。
- 交付时明确告诉用户：只做了副歌（N 句），要主歌 / 第二段 / 换个段落说一声。
- 用户给的谱读不清（糊、排版乱）：说明哪一段看不清，请他补一张或给文本版。 不要硬猜，也不要去找别的谱源交叉验证。
二、核心映射（硬规则，不许自行改动）
音级 → 键盘：
| 简谱 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 1̇ |
|---|---|---|---|---|---|---|---|---|
| 按键 | Z | X | C | V | B | N | M | , |
八度 → 修饰键 + 底色：
| 简谱记号 | 游戏内操作 | 图上底色 |
|---|---|---|
| 中音（数字无点） | 直接按键 | 白底黑字 |
| 高音（数字上方一点） | 按住鼠标右键 | 红底 |
| 低音（数字下方一点） | 按住鼠标左键 | 绿底 |
升/降号 # b |
按住鼠标中键 | 黄底（用到才出现图例） |
时长 → 框内符号：3- 长按（框内短横）；3· / 3. 半长按（框内圆点）。
全量音域表、超音域降级、映射的实测依据见 references/mapping.md。
三、工作流
取谱（第一节）→ 转写 DSL 到当前目录的 <歌名>.txt → 渲染（第五节）→
交付（和输出图放在同一目录并展示，WorkBuddy 用 present_files）+ 附一句范围说明。
用户说"某句不对 / 某段漏了"：只改 DSL 对应行重跑，不要重写整份谱。
四、DSL 格式
一个乐句一行，音符和歌词用 | 分开：
# 歌名
// # 开头是曲名（不含书名号），// 是注释，空行忽略
// 记号： ^1 高音(红底) _6 低音(绿底) #4 升半音 b7 降半音 3- 长按 1· 半长按 0 休止
3 2 4 3 1 5 7 ^1 7 5 1 | 刮 风 这 天 我 试 过 握 着 你 手
1 6 6 / 6 5 5 5 4 3 2 3 4 3- | 但 偏 偏 雨 渐 渐 大 到 我 看 你 不 见
对齐规则（重要 —— 别在这上面纠结）：
- 以歌词为骨架：一个汉字 / 一个英文词 = 一个槽位 = 一个音。先数歌词定出槽位数， 再给每个槽位填音级。不要反过来把谱面上印出来的每个音符都抄一遍。
- 音符数与歌词数不必相等。脚本按左对齐渲染：多出的歌词忽略，缺歌词的音符留空。
- 歌词整段可以省：只写音符、不写
| 歌词也能出图。 - 一个音配两个汉字（少见）：两个字写在同一槽位里，不空格。
- 一字多音（拖腔）：只取主音一个，时长用
-表达；不要把拖腔拆成好几个槽位。
记号要点：
- 正则
([#b]?)(\^+|_+)?[0-7]([#b]?)(\^+|_+)?([-.·]?)——^高八度、_低八度、#/b半音、-长按、·/.半长按。 - 八度记号和升降号写在数字前面或后面都认：
_6和6_等价，^2和2^等价。 简谱里的点是画在数字上/下方的，线性化时两种写法都常见，不用纠结用哪种。 /是句内换气间隔，只影响排版；歌词行里写不写/都会被忽略。- 长乐句自动折行，不用手动拆行。换段（主歌→副歌）时另起一行，版面更清楚。
五、渲染：默认出 PNG
# 解释器：Linux / macOS 上通常叫 python3，Windows 上是 python，能跑通就用哪个
python <skill_dir>/scripts/render_score.py <输入.txt> -o <输出.png>
一律先出 PNG。 图能直接发群、存相册，不用点链接。
只有 PNG 真的做不出来时，才改出 HTML，就两种情况：
- 脚本报缺 Pillow；
- 脚本打印「需要换输出格式：未找到任何系统中文字体」（硬出 PNG 汉字会是方块）。
这时改成 -o <输出.html> 再跑一次。HTML 零依赖、字体交给浏览器，是唯一需要它的场合。
不要为了出 PNG 去装字体、改字体配置、换解释器。
参数：--scale 默认 2（约 2300px 宽，手机看很清楚）；--title 晴天 覆盖曲名。
脚本对「音符数 ≠ 歌词数」「记号看不懂」「超音域」只打印提示到 stdout，注明"无需处理"， 照常出图。它是提示不是报错 —— 看一眼确认没理解错就行，不要为消掉提示去反复改谱。
六、交付前扫一眼
扫一眼即可，不必逐条死磕、不必回头重读原谱：
- 八度点有没有明显漏（漏一个红/绿底就错一个音）。
- 长音、延音线、附点是否转成了
-或·。 - 曲名和歌词有没有错别字（歌词按原样，不要润色）。
- 图里有没有多余空行，或只有一两个音符的碎行。
反复记号（D.C. / 反复号）只做第一遍，交付时提一句即可，不要展开成线性顺序。
七、边界
- 只处理单声部主旋律（人声那条）。默认直接取，不要回头问用户取哪一声部。
- 音域：中音 / 高音 / 低音各一组稳妥；倍高音只有
^^1（右键 +,）可达。 超音域的就近挪到相邻八度并提一句，不要卡住。 - 半音（中键）实战里操作别扭：偶尔出现没问题，整首大面积才提醒用户。
- 快歌里密集的十六分音符普通人弹不出来：密集段只保留骨干音，回复里说明做了简化。
跨平台：标准 Agent Skill（SKILL.md + 纯 Python 脚本），WorkBuddy、Claude Code、Cursor、 豆包等都能直接用，渲染器不依赖任何 agent 能力。 装到豆包用「技能·连接器·伙伴 → + → 上传技能」 （落在
workspace/.user_skills/delta-harmonica-tablature-generation-skill/）。
读谱细节见 references/jianpu.md；图片读不准时见 references/read-jianpu-image.md
（含 scripts/read_jianpu.py，把八度点检测出来并画回原图供核对）；
样例见 examples/晴天.txt，输出效果见 examples/demo-晴天.png 与 examples/demo-晴天.html。