# Delta Harmonica Tablature Generation Skill

> 把歌曲简谱转成《三角洲行动》守夜人口琴的键盘琴谱并渲染成 PNG 图片（升调红底、降调绿底、歌词逐字对齐、长按/半长按框内标注）；无中文字体的环境退回零依赖 HTML 网页。当用户上传或粘贴简谱、要求做三角洲口琴谱、琴谱对照表、口琴简化谱、把五线谱/简谱转成 ZXCVBNM 键位图时使用。

- Skill: `super-nius/delta-harmonica-tablature-generation-skill` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add super-nius/delta-harmonica-tablature-generation-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/super-nius/delta-harmonica-tablature-generation-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: SUPER-NIUs (https://skillmd.com/u/super-nius)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/super-nius/delta-harmonica-tablature-generation-skill

---


# 三角洲口琴谱生成 · 三角洲行动守夜人口琴

把简谱转成《三角洲行动》「守夜人口琴」的键盘键位谱，出**一张白底 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

```bash
# 解释器：Linux / macOS 上通常叫 python3，Windows 上是 python，能跑通就用哪个
python <skill_dir>/scripts/render_score.py <输入.txt> -o <输出.png>
```

**一律先出 PNG。** 图能直接发群、存相册，不用点链接。

**只有 PNG 真的做不出来时，才改出 HTML**，就两种情况：

1. 脚本报缺 Pillow；
2. 脚本打印「需要换输出格式：未找到任何系统中文字体」（硬出 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`。