murRipple · docs/research · 2026-08-20 · 基于主仓 main dca6ff2

知漪 murRipple 技术拆解

给它一个 mp3 加一份歌词，它产出一个零依赖、可双击打开、上限 15 MB 的单文件 index.html（音频、渲染器、分析数据全部内联），和一段逐帧渲染的 1080p60 MP4。 贯穿全部工程决定的主线只有一条：画面必须是时间 t 的纯函数——否则 「网页看到的就是导出视频里的」这句话就不成立。本文把它从素材预处理、分析管线、数据契约、 渲染分层、打包体积账，一直拆到守卫体系与已知缺陷，粒度对齐本仓此前对参考项目的拆解报告： 目标是一个没见过这个仓的 AI，拿着这一份文档能写出行为等价的系统。

Python 7,553 行 / 渲染层 JS 4,162 行 15 个渲染层 · 1 + N 行声部面板 pytest 1,094 passed / 渲染层 301 pass 产物上限 15 MB（MB = 1e6） STEP = 1/120 s · 全链确定性 许可：私仓保留全部权利 / 公开树 PolyForm NC 1.0.0

0边界声明

这份文档是什么。murRipple（中文名「知漪」）私仓的收官版技术拆解， 写作时基于 main 分支提交 dca6ff2（2026-08-20）。它面向两类读者： 想读懂这个项目技术细节的人，以及要据此复现一个行为等价系统的 AI。第二类读者是硬判据—— 所以每一层的输入/输出契约、每个承重常量的取值与理由、以及已知缺陷都在正文里， 不在附录里。一份不写已知缺陷的复现指南，会让复现者把 bug 当成自己的错。

数字纪律。本文遵守本仓介绍站立下的规矩：一个没有出处的数字都不写。 每个承重数字旁边标注出处——murripple/pack.py:22 这样的标记指源码位置， 「实测」指仓内台账（DECISIONS.md / MGMT.md）记录的真实测量或本文写作时当场跑出的数， 「棘轮」指该数值只是被钉住防漂移、不是「这个值是对的」的证据。 全文没有任何准确率数字与性能承诺——本项目没有人量过侦测与听写的准确率，代理指标在这个仓里已被真实结果推翻过多次 README.md「语言」节 · MGMT.md 第七节。

素材纪律。仓内五首歌，只有《Trempe-moi》（音乐由 Suno 生成、歌词由作者本人创作、版权归他） 可以公开点名。其余四首是第三方作品，本文一律以真歌 01–04 指代， 歌名、歌词、目录名一个都不出现——这与公开树的处置口径一致 MGMT.md 第六节 · DECISIONS 2026-08-16。

不覆盖什么。合成曲的音乐质量（M5 第二步，只有耳朵能判、尚未开工）； M6 三维视觉（有方向无 spec）；管理流程本身（那是 MGMT.md 第七节的地盘， 本文只收录其中已固化为代码或规格的部分）。

1一句话定性

所有分析（音源分离、节拍、起音、音高、歌词对齐）在构建期一次做完，固化成一份 timeline.json；渲染器不认识 Demucs 或 librosa，只认识这份文档 murripple/schema.py 模块 docstring。这个「先蒸馏、后重放」的结构， 与本仓的视觉标杆（一个在浏览器里现场合成音乐的单文件项目，拆解见 docs/research/2026-08-13-light-loom-teardown.html）恰好互为镜像：

产物两样 MGMT.md 第二节：

• 单文件 index.html——零外链、可双击本地打开、可发给任何人、可挂静态托管； 音频以 base64 data URI 内嵌，上限 15,000,000 字节（§6）。
• 1080p60 MP4——加载同一份产物逐帧抓 canvas 渲出，音频用原始音源零损耗封装（§8）。

2整体架构与数据流

2.1 物理分块

2.2 数据流

2.3 命令面

3取材层：ingest / fetch / transcribe

取材层的公共哲学写在 murripple/ingest/__init__.py 的 docstring 里： _in/ 是用户仅有的原始素材，这一层只读它——不改、不删、不移动； 产物一律写在歌曲目录下、_in/ 之外。以及两条硬规矩 murripple/ingest/scan.py：拿不准就报错，不猜（目录里有两个 mp4 时报错并列出候选——猜错要跑一小时才发现）； 决策要讲出来（Plan.notes 是打印给人看的句子，不是调试输出）。

3.1 扫描决策表（scan.py）

后缀分档 murripple/ingest/scan.py：无损 .wav/.flac、有损可直用 .m4a/.mp3（两档合起来恰好是 cli.find_source 认的四种——注释明写「往这里加 .ogg 之类之前，先去改 find_source」）； 视频 .mp4/.mov/.mkv/.webm/.avi。音频整理（audio.py）的原则是能不转码就不转码——四种可直用后缀 shutil.copy2 原样拷；只有视频真的动手：-vn 抽成 source.mp3，LAME 质量档 MP3_QUALITY = "2"（约 190 kbps VBR，注释：视频音轨本身有损，再高只是放大前一次压缩的产物）。 抽完做时长比对，容差 DURATION_TOLERANCE = 1.0 秒——因为 ffmpeg 对截断/损坏的文件仍然返回 0（源码注释记有实测）。 已有 source.* 就停下，--force 才覆盖，且覆盖时删掉其它扩展名的旧 source——两份并存时 find_source 按固定顺序取第一个，「用户以为换了源其实没换」。

3.2 硬字幕 OCR（subtitle.py）

这一步的产出不是「一段文字」，而是「文字 + 出现时刻」——字幕从暗变亮的那一刻就是演唱时刻， 这首歌于是可以完全跳过 WhisperX。全部承重常量与理由 murripple/ingest/subtitle.py：

比对键 compare_key() 剥掉全部空白与标点——标点是 OCR 最不稳的部分： 实测同一行「X——」在相邻帧里被读成 X / X- / X— / X一 四种，破折号在三字短句里一变就把相似度拉到 0.67。 OCR 后端做成可注入的 Callable（默认 rapidocr_onnxruntime）：逻辑部分不装 OCR 依赖就能测，换引擎不改这里。

时间戳落在单独的 lyrics.timing.json，不写进 overrides.json： overrides 的歌词补丁按下标打进「对齐之后」的列表，而对齐会丢行 → 下标错位 DECISIONS 2026-08-13「推翻 M4 计划稿」。校对 lyrics.txt 后文字以它为准、时间戳只对行数—— 拆行或并行会让两边对不上，那时报错并退回常规对齐。

3.3 歌词门（lyrics_gate.py）

「这首歌要不要歌词」——全仓唯一那一处判断。它原来是三处且互相矛盾（cli.run 拒绝、 cli.build 沉默降级、web 壳子拿空白也算缺），三次真跑把矛盾坐实后统一成一个只用标准库的叶子模块， 管线与网页壳子都 import 得起 murripple/lyrics_gate.py docstring。设计上把 事实与政策分开：lyrics_missing() 是事实（空白算缺——一份全是空格的 lyrics.txt 骗得过 exists()），两边共用；blocked_reason() 是管线的政策 （默认拦住，--no-lyrics 或 compose.json 放行——后者等于用户已经说过「这是器乐曲」）。 拦下时的消息把四条出路全部写出来（跑 ingest / 自己写 / transcribe 听一遍 / --no-lyrics）—— 「少写一条，那条路对用户就等于不存在」；第四条另起一行带两格缩进，因为 web 的日志分层按行首形状认领， 揉进上一句会把听写那条路的唯一入口提示折进详细区。

3.4 链接取回（fetch.py）

纯模块、零接线成本地并入 ingest --url 与 POST /api/job-from-url。 三级降级链 murripple/fetch.py：

关键常量：音频格式 bestaudio[ext=m4a]/bestaudio[acodec^=mp4a]——挑 AAC 免转码是这条路真正的门道， 落成 opus 会被 scan 归进「忽略（用不上）」整趟白跑；视频合并容器 mkv。降级必须大声说自己走了哪一级、原因原文照登； 我们自己的每一行都带 [取回] 前缀，yt-dlp 原文一字不改透传——「哪些话是这个模块说的」是可判定事实。 静默看门狗 QUIET_SECONDS = 15.0 只挂第 1 级，且只声称「有一阵子没有任何输出了」这个量到的事实—— 原稿那句「在下载工具」是照着一个没量过的假设写的，冷缓存真跑一次就被推翻（uv 自己会把每个包报出来， 含那个 36.7 MB 的 deno 运行时）fetch.py 订正注释 · DECISIONS 2026-08-14。 取回无条件打印版权提醒，承重句是「你对自己处理和分发的素材负责」——一句只有作者看得懂的提醒不是提醒 DECISIONS 2026-08-15。

3.5 听写（ingest/transcribe.py）

机器认字，人断句。产出是 lyrics.draft.txt，管线一个字都不读它—— 「必须过人的确认」是结构事实而不是承诺：这个模块没有任何一条路径写得到 lyrics.txt。 草稿一段一行、不替人断句：实测中文歌 36 行的歌词只吐回 6 段、法语歌 34 行吐回 8 段， 且中文输出一个标点都没有——「按标点断句」这条路根本不存在 transcribe.py docstring · tests/fixtures/whisperx/ 抄件。 听的是混音不听人声轨：人声轨实测明显更准，但要先跑一遍 Demucs，而 build 只认扁平分轨布局、 会原样再分离一遍——那几分钟是纯浪费；管理窗口并拒绝「让 build 认嵌套布局」，因为那会把 「第二次 build 拿旧分轨假装新结果」这个 bug 请回来 DECISIONS 2026-08-15。 草稿不加表头：改名存成 lyrics.txt 时表头会变成第一句歌词。全仓（代码、CLI、网页） 不出现任何听写准确率数字，有守卫扫 %／准确率／字准。

4分析管线：build 的五步

murripple build 的进度输出就是它的结构：[1/5] 分离音源 → [2/5] 读取分轨 → [3/5] 对齐歌词 → [4/5] 编码音频 → [5/5] 组装 timeline。歌词门拦在动 Demucs 之前—— 「忘了放歌词的人不该白烧一小时，这是这道门存在的全部理由」murripple/cli.py::build 注释。 run = build + pack，每步先看产物在不在（全链约一小时：Demucs 约 4 分钟 + Whisper 几分钟 + 导出 33 分钟， 必须可断点续跑）cli.py::run docstring。

4.1 分离（separate.py）

Demucs htdemucs（四条 stem：vocals/drums/bass/other），子进程调用不用 Python API—— CLI 接口跨版本稳定得多，测试可整体替身、不必下载 2 GB 模型；sys.executable -m demucs 保证跑在同一个 uv 环境。 两个承重参数：

• --shifts 0（必须固定为 0）：Demucs 默认每次跑都做一次随机时间平移再平均、且不接受种子—— 实测同一首歌两次 build 得到不同分轨，歌词对齐从 48 句掉到 33 句而代码一行没改。分离质量略有损失，换来可复现： 好结果能重现，退化能追查 murripple/separate.py 注释。
• 输出布局是嵌套的 stems/<model>/<源名>/*.wav——这一点被 stems.find_flat_stems 刻意利用：它只做非递归 glob("*.wav")，于是「跳过 Demucs」的判据是 扁平布局（外部提供的分轨：compose 合成的九条、或手工放的四条），不是「目录在不在」—— 后者在任何一次正常 build 之后都成立，会让第二次 build 拿旧分轨假装新结果。凑不齐一整套完整名单（缺一条、多一条、混搭） 一律拒绝：半套分轨比没有更危险 murripple/stems.py docstring。

4.2 节拍、起音、音高、段落（analyze.py）

全部纯函数：输入 numpy 数组、输出普通数据，无 IO 无子进程，测试用合成音频即可 murripple/analyze.py docstring。

4.3 六条视觉轨道（lanes.py）——色相权威在这里

Demucs 只有四条 stem，人声不占轨道（它驱动判定环），剩下三条按频段拆成六条视觉轨道。 静音粒度仍是 4——底鼓/军鼓/踩镲从同一条鼓轨滤出来，能分开画、不能分开静音 murripple/lanes.py docstring。LANE_SPECS 是全项目的色相权威表 （网页壳子、介绍站的色板都有守卫钉着必须等于它，见 §12）：

出处：id/hue/stem/band 见 murripple/lanes.py:19-24；中文/英文声部名的真相源是渲染层 renderer/src/ui/voices.js LABELS（lanes.py 里的 label「底鼓/军鼓/…」只是兜底，画面上出的是「撼岳/裂帛/…」）； 心籁 hue 300 由 voices.js 硬编码（人声无 lane）。合成曲另有 arp 165「泠泠」、bell 60「霜铎」，pad/pluck 复用 175/270（§9）。

带通用四阶巴特沃斯 sosfiltfilt，padtype="constant"——默认 "odd" 端点外推对突然起振的信号 会在起点反射出低频伪影，足以让理应带外拒绝的能量在包络第一帧冒头 lanes.py::bandpass 注释。 每条 lane 跑 detect_onsets；只有 bass 跑 track_pitch（单音假设）。 合成曲走 lanes_from_specs 直通：名字、色相、音符表来自真值，不切频段、不猜音符—— 「对着自己刚写完的乐谱再猜一遍，是把已知信息丢掉再找回来」；包络仍从音频算，它本来就是音频属性。

4.4 包络（envelope.py）

RMS(60 Hz 网格，hop = sr/60) → dB（floor −60）→ uint8（0–255）→ base64

一条轨 3 分钟约 10.8 KB。quantize 的 global_peak 取全部轨道 + 人声的共同峰值， 保留各轨相对响度——否则安静的轨和响亮的轨一样亮；个别轨太暗用 overrides 的 per-lane gain 提。 混音包络的峰值故意不计入：mix 是四轨之和、峰值通常高于任何单轨，计入会把六条 lane 按 dB 刻度一并拉暗 murripple/envelope.py · timeline.py 注释。

4.5 歌词对齐（align.py）

用户提供歌词原文，所以这是「对齐」而非「识别」。关键设计：不按整句做精确匹配—— Whisper 的分句边界与用户的换行几乎不可能一致。做法是字符级序列比对 murripple/align.py docstring：

1. WhisperX（MODEL_SIZE="medium"、DEVICE="cpu"、compute_type="int8"）转录人声轨并做词级对齐。 选 medium 的理由：唱歌比说话难认得多，small 在真实曲目上错得厉害、导致大量句子对不上；medium 慢三到五倍， 但 build 是一次性的、调视觉时不重跑，值这个时间 align.py:24-28 注释。
2. 把词级结果拼成一条归一化字符流（繁转简 · 去标点与各类空白含全角空格 · 转小写；opencc 是可选 extra， 装不上就退化为不转换——但 Whisper 在中文歌上会随段落输出繁体，那几句会全部落空），用户歌词同样拼流， difflib.SequenceMatcher（autojunk=False）求最长公共子序列，把每行的字符位置映射回词时间戳。
3. 外推：匹配残缺时由命中的首尾字反推整句窗口——假设句内字速均匀，测出每字时长后向两端外推； 只命中一个字时用全曲中位字速兜底（DEFAULT_CHAR_SEC = 0.35 只在一个可测速率都没有时用得上， 所以换语言速率会自己跟上）。外推封顶 MAX_EXTRAPOLATION = 1.6 倍——实测一句八字的句读句曾被推到 11 秒并倒插回上一句。
4. 单调化 _enforce_monotonic 四步：自身非负 → 重叠取中点分界（「重叠说明两句的估计都不确定， 没有理由让先来的全赢」）→ 短句补到 MIN_LINE_SEC = 0.35 但不越过下一句 → 最后一遍无条件强制不重叠 （「不变式必须由一个无条件的收尾保证」——实测前三步之后仍剩 1 处违例）。不按 t0 重排： LCS 锚点本身单调，歌词顺序是权威，重排曾把第 4 句排到第 5 句后面。
5. 词级（--word-level）是按需精修：把一行的字符线性铺在 [t0, t1] 上，够做卡拉OK高亮； 默认句级——句级差 0.2 秒基本无感，词级差 0.2 秒极其显眼。
6. 没对上的行原样报告给用户，由 overrides.json 的 lyrics.insert 手工补录（§4.7）。

4.6 语言侦测：最响 5 窗投票

「这首歌是什么语言」全仓只有 align.decide_language() 一处在决定，对齐与听写都问它—— 且刻意不写在默认参数上：默认参数在 def 时求值，「唯一那一处」就不存在了 align.py::decide_language docstring。机制：

• Whisper 认一次语言只看头 30 秒（WINDOW_SEC = 30，这是它的性质不是我们挑的参数）。 而歌的前 30 秒常常没人唱：仓内一首中文真歌第一句在 39.50 秒才进来——人声轨前 30 秒 RMS 0.00094（次低那首的 1/43）被认成 en(0.44)，混音前 30 秒 RMS 0.12563（满编制器乐前奏、一点都不轻）被认成 ru align.py::pick_windows docstring 实测表。
• 所以按 16 kHz、30 秒一窗算 RMS，两道门各挡一种失败：SILENCE_FLOOR = 0.25 （低于最响窗口四分之一的窗口不参与投票）挡「对着静音硬猜」；取最响的 VOTE_WINDOWS = 5 个窗口投票取众数 挡「响度正常的器乐前奏」——floor 对后者一点忙都帮不上。
• 「最响 = 有人在唱」是代理指标，源码注释直说它不单独成立——真正兜底的是 Language.unsure：众数不过半即「拿不准」，此时打出票型 + 一条能照着敲的命令（build --language …， 选 build 不选 run 是因为 build 每次真的重做分析、必定有效）。拿不准时不许沉默通过是安全网， 选窗口只是会失效的启发式——两条判据分工写进了裁定 DECISIONS 2026-08-15。
• 侦测结果三种说法都打在主日志（指定的照实说指定、站得住的说几个片段一致并附推翻办法、拿不准的摊开票型）， 并写进 meta.language——它是可选字段：硬字幕、--no-lyrics、器乐曲根本没跑过 Whisper， 往那儿写个 "zh" 正是「沉默地猜」；缺席是一句实话。

4.7 手工精修（overrides.py）

「通用管线打底 + 重点歌精修」里精修的落点：songs/<slug>/overrides.json 在 build 最后一步合并进 timeline， 自动分析不满意就改文件重跑、不动代码。三条设计决定 murripple/overrides.py docstring： 深合并不是替换（浅合并会把整条 lane 换掉、envelope 与 notes 全丢，而产出仍是合法 JSON——只有画面会莫名其妙空掉，最难查）； 未知字段当场报错并点名（静默忽略最坏：用户改了半天没反应会以为是渲染层的问题）； 缺文件不是错误（绝大多数歌不需要精修）。可改字段：meta.title、sections[i].name/energy（按下标）、 lanes[id].gain/hue/label（按 id 不按下标——下标会随管线改动而变）、 lyrics.offset / lines / insert。

lyrics 三样的先后是承重的：整体 offset 先行；insert（整行补录）按 t0 归位不按下标—— 对齐会整句整句地丢，而 lines 只能改已有句子；插入本身在改变数量，再按下标定位是 M4 那一跤的加强版； lines（单句覆盖，绝对时刻）排最后，下标打的是补齐之后的列表。补录必须三样全给（t0/t1/text）—— 缺 t1 渲染层不知道何时暗下去，空 text 是一行看不见的歌词占着时间，比不插更难查。 落点是绝对的，「insert 是一组补录，不是一份要按顺序执行的剧本」——先排序那一行被变异检验证明是死代码后删除 overrides.py::_insert_lines 注释。

4.8 组装（timeline.py）

build_timeline 只做组装与校验，不做分析。人声在场判定 PRESENCE_THRESHOLD = 0.02 （人声 RMS 高于全曲峰值 2% 才算「在唱」，presence 是逐帧 0/255 二值）。纯器乐回退： presence 全 0 时判定环改由整体能量（mix 包络）驱动、跳过歌词层、不中断；presence 本身保持全 0， 诚实反映没有人声，供渲染层据此选择表现。stems 字段 = sorted(stem_audio)； section_marks/lane_specs 真值直通的判断用 is not None 不用真值判断—— 空列表 [] 会被真值判断当「没给」悄悄落回检测老路，is not None 则让它在 schema 的 minItems: 1 上当场炸掉：同一个误用，从「静默出错的产物」变成「构建时就失败」 timeline.py docstring。

5timeline.json——唯一的契约

「这是构建时管线与运行时渲染器之间唯一的接口。渲染器不认识 Demucs 或 librosa，只认识这份文档。」 murripple/schema.py docstring。JSON Schema Draft 2020-12，SCHEMA_VERSION = 1， 顶层八个字段全部必填、additionalProperties: false：

schema 之外还有两层校验，各有分工 murripple/schema.py::validate_timeline：

• base64 真解一次：contentEncoding 在 Draft 2020-12 里只是注解关键字，jsonschema 不强制—— 非法 base64 照样过 schema。所以 base64.b64decode(..., validate=True) 手动验 ring 与每条 lane 的包络。
• 跨字段校验单独的异常类型：lane.stem 必须出现在顶层 stems 里——jsonschema 管不了「这个字符串是否在另一个字段声明的清单里」， 这层用专门的 SchemaError 与 ValidationError（字段形状错误）区分开。
• 源码注释里留着两段死代码解剖：手写的 stems 重名检查永远跑不到（schema 的 uniqueItems 先抛）、 「stems 缺失回退白名单」的兜底在 stems 转为必填后同样死掉——都被变异检验证明后删除。 「不留一段测不到的代码」。

6编码、打包与体积账

6.1 音频编码（encode.py）

选 AAC 不选 Opus：Opus 体积更小，但 Safari 支持历来不稳，而核心场景是「发个链接谁都能开」。 macOS 上优先 AudioToolbox 的 aac_at（音质好于 ffmpeg 原生 aac，探测一次 lru_cache）， 默认码率 64k，-movflags +faststart。每条 stem 一份独立 m4a → base64 data URI 内嵌。 必须走 data URI 而非独立文件：file:// 下 fetch 被 CORS 拦、createMediaElementSource 会因跨域污染而静音， 只有 base64 → ArrayBuffer → decodeAudioData 这条路走得通 murripple/encode.py 注释。

6.2 打包（pack.py）

与 build 拆开的理由：分析约 84 秒、打包约 2 秒，调视觉时每改一次都重跑分析没法忍。流程：

1. npx --yes esbuild src/main.js --bundle --format=iife --global-name=murRippleApp --minify （注意 renderer 自己的 npm run bundle 不带 minify，那份是给测试 harness 用的）。
2. 四样东西一次性正则替换注入模板：__TITLE_JSON__（JS 字符串上下文，json.dumps）、 __TITLE__（HTML 上下文，html.escape——两个落点转义方式不同，不能共用占位符：HTML 实体在 script 里不解码， 以反斜杠结尾的曲名会让整段 script 语法错误）、__TIMELINE__（原文）、__AUDIO__、__BUNDLE__。 不能链式 replace——曲名里写 "__BUNDLE__" 就能把整个 bundle 再插一遍。全部数据过 _js_safe 把 </ 转义成 <\/：数据里出现闭合标签会让浏览器提前闭合脚本， 而 JSON 本身完全合法、任何 JSON 校验都发现不了 murripple/pack.py 注释。
3. 声明的分轨必须全部到齐：缺 timeline.stems 里任何一条的 m4a 即 PackError——只查「至少有一条」会静默产出缺声部的产物， 面板那一行照常渲染、可点、点了什么也不发生（与 find_flat_stems 防的是同一形状：半套比没有更危险）。
4. 先写临时文件、量完体积再原子替换：直接写 out 再在超限时删掉，会把上一次成功的产物一并抹掉—— 「用删除来处理『产物太大』是拿已有资产去赌」pack.py · DECISIONS 2026-08-14。

6.3 15 MB 上限与体积账

出处：前五行为 tests/fixtures/real-songs-baseline.json 锁定值（回归守卫的基线，另配 50 KB 体积漂移棘轮）；合成曲为 DECISIONS 2026-08-14 Task 9 实测。

第十条声部装不下——这笔账不依赖任何开销估计 MGMT.md P1.9 · DECISIONS 2026-08-14： 设非音频开销为 O，十条总量 = O + 10×(14,183,341 − O)/9；要 ≤ 15e6，须 O ≥ 6,833,410 B—— 占产物 48.2%，而产物里绝大部分就是九段 base64 音频，不可能。所以任何 O < 6.83 MB 下第十条都溢出。 同理真歌 270 秒 × 9 条会到约 25.9 MB——九条分轨是合成曲专有的，真歌不走这条路 M5v2 spec 第五节。

7渲染层（本节最重要）

7.1 确定性三铁律

三铁律的落点举例：星云轨道角与浮尘高度写成闭式（a0 + t*sp、(y0 - t*vy) mod H）； 涟漪/冲击弧/光扫/段落大字全部「反查而非累积」——参考实现是 push(...) 逐帧累积再 filter 的， 逐帧导出下跳到第 200 秒直接渲染时数组是空的，涟漪就消失了 ripple.js 注释。 唯一有状态的一层是粒子，靠固定步长 + 种子派生兜住：每次命中的光屑用 mulberry32(0x9e3779b9 ^ ((laneIdx+1)*0x85ebca6b) ^ noteIdx)，不用全局序列 core/particles.js。背景层各有独立字面量种子（星野 0x5eed、流星相位 0x5e11、噪点瓦片 11）。

7.2 时钟与世界推进（core/clock.js）

• STEP = 1/120；时间用整数步数不用累加——「simT += STEP 会累积浮点误差， 1/120 在二进制里不精确，3 分钟下来会少走整整一步」。
• advanceOrRewind(targetT, world)：目标时刻早于 simT - STEP 就 reset（清空世界、从 0 重放到目标——3 分钟 = 21,600 步纯计算只要几十毫秒），否则只前进。 seek 之后的画面因此与离线渲染一致。
• quality 由 mode 决定不由实测帧率决定：MODE_OFFLINE 强制 quality=1， 各层读 state.quality 降级（浮尘/流星/颗粒省略、刻度环齿数减半、谱线 66→40 桶、波形 180→90 点、彗尾 5→2 段）， 不得自行判断帧率——否则同一个 t 在两种模式下画出不同的帧。
• 时间基准只认 AudioContext.currentTime，不用 performance.now()——后者与音频漂移，几分钟能差出小半秒 core/audio.js。

7.3 绘制顺序与图层职责

main.js 的 LAYERS 数组顺序即叠放顺序，注释明令「不要随手往后追加：歌词必须压在波形之上 （否则波形锯齿切碎字形），光屑必须压在环之上（否则命中的爆发感被环盖住）」。

7.4 几何与配色

所有半径以 R 为单位、常量集中在 core/geometry.js，各层不得自己定半径： R = min(W,H) × 0.225（M2-4 之前是 0.28——「实心结构只占 0.225，靠向外发散的谱线撑出 0.43 的轮廓： 骨架细、轮廓大，这才是纤细灵动的来源」）；圆心 cy = H × 0.485；dpr 封顶 2。 半径阶梯：波形 0.55 → 内刻度 0.8 → 判定环 0.9 → 车道弧 1.0 → 外刻度 1.06 → 谱线基 1.02 → 谱线顶 1.95 = 音符出生点 1.95。

配色是两段式：每条 lane 的基色相由 Python 的 LANE_SPECS 定死写进 timeline； 渲染层只做 (hue + palette.hueShift) % 360，其中 hueShift = 段落序号 × HUE_STEP(37)—— 37 与 360 互质，段落再多也不会提前撞色；饱和度 = 45 + 段落能量 × 40 core/palette.js。段落名默认为空，段落结构只能靠颜色传达——「这一层比看上去重要」。 非 lane 图层各有固定基偏移（背景/环/歌词 210，光核/刻度 205，涟漪/光扫/谱线/段落字 200，波形 190）。 同一段落内配色恒定不随 t 漂移是辉光精灵缓存有界的承重前提：全曲多轮扫描（含 1/60 s 逐帧两遍） 精灵稳定 199 个、约 6.6 MB、零增长；把 hueShift 改成随 t 漂移，条目数涨到 3,706 且 palette 测试当场红 core/glow.js 量测注释 · DECISIONS 2026-08-14。

7.5 歌词断行：九个汉字宽的预算

layers/lyrics.js 是 M2 的核心视觉决策「歌词即光核」，也是全仓打磨最狠的一层。断行契约：

• MAX_CHARS_PER_LINE = 9（导出是给守卫用的）：「每一行都放得下」拆成两半验—— lyricsFit.test.mjs 一半在全部真语料上穷举断言没有任何一行超预算（纯函数）， 一半进真浏览器画真的字、扫像素量墨迹的横向范围，证明预算真的落在画面里。 后一半故意跑正方形视口：字号按 min(W,H) 定，16:9 下溢出比例只有正方形的 56%， 宽屏那一档恰好躲开问题 lyricsFit.test.mjs · DECISIONS 2026-08-15。
• 两条断行规则按「这一句用不用空格分词」二选一：整句命中 WORD_SCRIPT = /[A-Za-zÀ-ʯͰ-ϿЀ-ӿ]/（拉丁/希腊/西里尔）→ 贪心装箱、空白原样保留； 否则句读切分 + 全宽 token 装箱。分水岭的理由：「中文里的空格是句读，删掉不丢信息； 法语/英语里的空格是词的边界，删掉就把 spare part 粘成 sparepart」——这个缺陷在已交付产物里存在过， 直到第一首法语歌把它照出来。宽度模型：CJK/假名/全角算 1、其余算 0.5；超长拉丁单词宁可溢出也不断在词里。
• splitLine 必须是纯函数（静态宽度模型，不碰 measureText）—— 量真实字宽会把断行结果绑到字体与设备上，同一个 t 在两台机器上断出不同的行，破确定性铁律。
• 时序：LEAD_IN = 0.5——淡入必须在 t0 之前完成，唱到那一刻字已经在了 （初版从 t0 开始淡入，t0 时刻 alpha 恰好为 0）；TAIL = 0.4 收尾。
• 亮底可读性三件套：压幕椭圆（SCRIM 0.5，取背景基色 rgb(3,5,11) 不是纯黑——纯黑在暖色段落里显出一块灰）、 两道 lighter 柔边、字芯 source-over——「加色混合在亮底上无解：底已经接近 255 时字再亮也加不出差别」。 三条阈值全由变异检验定标（字芯改回加色 → 饱和像素 0→1979；去掉压幕 → 0→6508） lyricsLegibility.test.mjs。中心光核同时「让位」：歌词出现时内芯亮度让掉 72% （coreYield——「让位是必要的但不是充分的，字那边还得有压幕」）。

7.6 音频通路与 WAV 导出

• 播放器 createPlayer 把三种状态分开：running（用户意图）/ ended（到头了，按 elapsed() >= duration 判，duration 用 meta.duration 不用 buffer 时长——实测四首歌 16 条 stem 与声明时长差全部毫秒级，最大 12.99 ms）/ playing（真的出声）。播完再播从头开始 （resumeFrom）。各 stem 同一时刻 start(0, at) 保证采样级同步；静音是 20 ms 增益渐变不是 stop—— stop 之后再起会失去同步。增益节点按 Object.keys(buffers) 建，不写死四条。音量与静音分两级 gain—— 合在一起的话调过音量再取消静音就回不到原响度 core/audio.js。
• 「导出当前混音 WAV」用 OfflineAudioContext 重渲：分轨清单由 buffers 自己的键集合决定 （写死 STEMS 会让合成曲九条只混前四条），取最长一轨为长度（解码后差几个样本是常事，取短会截尾）， 链路里没有压缩器、没有限幅器——只有 0/1 静音增益 + WAV 写盘时的硬钳位 core/mixdown.js。
• WAV 写盘（44 字节 RIFF 头、16 位 PCM 小端交织）两条量化纪律：先钳位再量化 （分轨叠加超过 ±1 是常事，不钳位 Math.round 溢出 int16 回绕、听感是爆音）； 负半轴乘 0x8000、正半轴乘 0x7fff——同一系数会让 +1 溢出 core/wav.js。
• 波形/频谱层的数据源是解码后的单声道混音（只按声道数平均，不按轨数归一）： 1024 点 radix-2 FFT 一帧零点几毫秒，比预存频谱矩阵划算 core/dsp.js · core/mix.js。

7.7 界面：DOM 覆盖层与声部面板

界面全部是 DOM 覆盖层不进 canvas——「M3 逐帧抓 canvas 导出，画进 canvas 的界面会被烤进每一帧视频； DOM 覆盖层让导出天然干净，零额外代价」ui/hud.js。要点：

• 声部面板行数 = 1 + lane 条数（首行恒为心籁/vocals：它驱动判定环、不占 lane；真歌 1+6=7、合成曲 1+8=9）。 点一行静音它所属的 stem；真歌里撼岳/裂帛/碎玉共用 drums、流岚/缥缈共用 other—— 连动组在面板左侧用竖脊连起来，「连动必须在按下之前就看得见」，否则界面在骗人。 归组关系只从 lane.stem 推、只看紧邻两行（非连续时画成两段各自封口的短脊—— 宁可少声称，不要错声称），不硬编码「kick/snare/hat 是鼓」——素材换了、六轨模型上了都不会开始骗人 ui/voices.js · DECISIONS 2026-08-14。
• 十条声部名表（中英双名）是渲染层 LABELS：撼岳/裂帛/碎玉/渊鸣/流岚/缥缈/泠泠/霜铎 + 心籁； mid/pad 共用「流岚」、air/pluck 共用「缥缈」是刻意的——两者永不同时出现在一份 timeline 里。 命名按声部在乐曲里的角色取意，不沿用参考项目那一套（那是它的创作内容，守卫见 §12）。 环外小字有 labelFor 兜底（LABELS[id]?.zh ?? lane.label）——侧栏不进 MP4， 环外小字是声部名在视频里出现的唯一位置，丢了兜底九条档的 MP4 会有 5 个声部无名 DECISIONS 2026-08-14。
• 快捷键：空格永远是播放/暂停（连按钮焦点也不让——否则点过静音钮后按空格切的是静音）； H 收起界面，收起后点画面任意处恢复（触屏上没有键盘）；走带条点击跳转、按住拖拽擦洗 （拖拽中走 previewFrame 不推进世界，松手 seek 一次性补齐）。
• 下载按钮在 file:// 下隐藏——本地双击打开的人手上已经有这个文件了。

7.8 实时跳帧（省电不省确定性）

实时模式下画面只是 state 的函数：state 不变时重画纯属白烧——实测这条白烧循环占一个核的 111%，暂停时也一样烧；修复后暂停 113–115% → 2–9%、播完闲置 → 7–8%（约 13 倍） DECISIONS 2026-08-15 实测。机制 main.js：

• 帧指纹 frameKey = t | simT | hoverLane | audioGen | WxH@dpr；相同则跳过绘制。
• FIELD_ROLE 穷举表把 drawAt 放进 state 的每个字段分类为 t / const / key，首帧与真实 state 的键逐个对、有没分类的当场抛——「能在 t 不变时改变画面的输入」 不靠记性枚举，加字段就被迫分类；测试从这张表推导探针清单，新加 key 字段没写探针会红。
• 两条显式失效通道 invalidate()：resize（给 canvas.width 赋值会清空画布，哪怕值没变）与 previewFrame（画的是另一个 t）。「失效通道漏一处 = 画面卡住不动，比多烧 CPU 严重得多」。
• 离线一个分支都不走：skipUnchanged = mode === REALTIME 写死—— 「MP4 不受影响」是结构性事实不是概率论断；改动前后真导 MP4 比对 sha256 相同 DECISIONS 2026-08-15。

8视频导出

node video/render.mjs ../songs/<slug> [--fps 60] [--size 1920x1080] [--from --to] [--crf 17]。 四条设计决定，每条都有原因 renderer/video/render.mjs 头注释：

1. 加载产物 index.html 本身，不另建渲染路径——另起一条路等于把确定性铁则全作废， 「网页看到的 = 导出视频」就无从谈起。
2. 不点标题页的开始按钮——那会启动实时循环与逐帧推进打架；直接造 mode:"offline" 的实例 （window.__EXPORT__ 钩子）。
3. 用 OfflineAudioContext 解码——无头环境没有音频设备，AudioContext 会被挂起； 实测解 270 秒的轨只要 156 ms。
4. 抓 canvas 不抓整页——DOM 界面不烤进视频；也不用 locator.screenshot（实测 346 ms/帧 vs 读 canvas 89 ms）。

音频用原始音源直接封装零损耗——产物里那份 64k AAC 是为了体积。实测参考：4.5 分钟 · 1080p60 · 16,200 帧约 33 分钟、163 MB README.md（这也是「不做 mp4 下载按钮」的原因之一： GitHub 单文件上限 100 MB，且破坏零外链离线 DECISIONS 2026-08-13）。 调参用 --from 40 --to 50 只导一小段。导出级确定性有专门守卫：60 fps 600 帧两次独立运行逐帧哈希一致、 从中途某帧直接开渲必须与从头渲到那里相同（--from 正是这么用的） renderer/test/export-determinism.test.mjs。

9合成器 compose（私仓专属）

M5：不给音频，摇一个 seed 自己写一首（当前状态：数据契约与分轨已验收，音乐本身尚未过耳朵关—— 第二步未开工）。公开树不带它，CLI 对它 try/except ImportError：合成器不在时不注册 compose 子命令—— 「注册一条跑不了的命令比没有更糟」cli.py 顶部注释。

9.1 结构

9.2 与主管线的接缝——「有真值就别再猜」

compose 写四份真值文件，build 逐一直通：扁平 build/stems/*.wav 九条（跳过 Demucs）、 build/sections.json（段落边界真值，跳过自相似矩阵猜测）、build/lanes.json （轨道真值：id/label/hue/notes，跳过带通切分 + onset 检测——合成曲的音符表直接来自 Score）、 compose.json（过歌词门）。主奏单独进 vocals stem 驱动判定环 （实测与 presence 相关系数 0.925，对鼓只有 0.084），打击声部 pitch 置 null（乐谱里的 0 在 MIDI 上是真实的 C-1， 照搬会把每一记鼓画在最低音位置）。同 seed 逐字节复现；换 seed 重摇会主动作废旧 timeline—— 不作废的话 run 会「分析 跳过」然后打包上一个 seed 的成品，一句警告都没有：timeline.json 就是缓存， 缓存的输入变了就该失效 cli.py::compose · MGMT.md 考卷第 3 题。

10本机壳子 murripple serve

W1：murripple serve 起一个网页——选文件、贴歌词、点开始。它解决的不是「命令行难用」， 是目录约定：「songs/<slug>/source.mp3 + lyrics.txt 那套约定是给我们自己用的，对外人是纯粹的心智负担」 W1 spec 第一节。立身之本两条：不 import 分析管线 （整个包只用标准库，跑歌全靠 subprocess 调 murripple 命令，有干净子进程守卫钉着； 唯一从管线拿的是 DRAFT_FILENAME 这个文件名常量），管线一行不改 （首版合并时 cli.py +11/−0，其余零改动 DECISIONS 2026-08-14）。

10.1 服务骨架（server.py）

• 只绑 127.0.0.1，没有开关也不该有——这个服务拿用户给的路径起子进程、没有认证， 绑 0.0.0.0 等于把文件系统与子进程交给同一个 WiFi 下的任何人。
• 默认端口 8731，被占往上找 PORT_SEARCH_SPAN = 20 个（只接 EADDRINUSE，其它错照抛； 连着二十个都满多半是别处出了问题），终端打印实际拿到的端口。
• ffmpeg 缺席只提醒不拦启动——启动即退的话用户连那句 brew install ffmpeg 都看不到； 但建任务时硬拒：缺了它跑到第 4 步才炸，前面几分钟白等 web/app.py::_create_job。
• ThreadingHTTPServer：页面要一边跑任务一边轮询，单线程一个连接没读完就堵死全部。

10.2 端点与任务模型（app.py / jobs.py）

任务落在 songs/web-<时间戳>-<原名>/，与目录约定同一套。文件名消毒只有一处 （safe_stem，96 字节 = 32 个汉字上限——实测 APFS 单段 255 字符、ext4 255 字节，按字节截两边都活； 消毒散开的话删掉一处还有另一处兜着、变异检验会全绿）；目录建立用不带 exist_ok 的 mkdir 认撞名—— 先 exists 再建在并发下会静默覆盖，「用户只会发现歌变成了另一首」。一次跑一个不做队列； job_id 只活在进程内 dict 里——刷新页面/重启服务接不上（spec 里那句「刷新能接上」是被收口评审 订正过的假声称）；真正成立的是：目录还在，命令行对同一目录跑 run 确实接着跑 web/app.py docstring · DECISIONS 2026-08-14。

10.3 子进程编排（runner.py）——三件跟现实对上过的事

1. stderr=STDOUT 合并：失败消息全走 stderr，不合并的话用户只看到「失败了」而没有原因。 代价说在明处：合并后分不出哪行来自 stderr，spec 那句「stderr 最后 20 行」落成「合并流最后 20 行」。
2. PYTHONUNBUFFERED=1 是承重条件：cli 的 print 不带 flush，管道上 stdout 块缓冲—— 一次 run 的全部输出才一两 KB、4 KB 攒不满一个字也不出来，「实时进度」当场变成「跑完一小时一次性刷出来」。 这一条不在计划稿也不在 spec 里，是真跑撞出来的 DECISIONS 2026-08-14。
3. 「一行 = 一条记录」的前提是非 tty：tqdm 在非 tty 下不画进度条（实测 12 秒 build 的输出 1,546 字节 17 行 \r 零个）。这是前提不是性质——接伪终端它就塌，且没有测试会红（照实记在 docstring）。

另有两处结构纪律：读取线程的 finally 必须收尾且先关管道再 wait—— 直接 wait 的话管道一满子进程永远卡在 write、我们永远卡在 wait，双向死锁连收尸都收不掉； murripple_command() 不许 .resolve()（§13 详述这个真 bug）。 命令拼装不加 --force：同一目录再点开始要接着跑，不是从 Demucs 再来一小时。

10.4 进度解析（progress.py）——分母判层，白名单认领

• 层级看分母不看缩进：[n/2] 是外层、[n/5] 是内层，两者都顶格打印； 缩进在这份输出里标的是子消息不是层级——「按缩进判断」两次被真实输出推翻（第三方的 warnings.warn( 缩两格、我们的 [1/5] 在第 0 列）。分母既不是 2 也不是 5 的行只进日志不动任何层： 「不知道这是哪一层，就照实说不知道」。外层前进不清空内层、两层不压成一个百分比 （压成一个的话 [5/5] 之后来 [2/2] 就是进度条倒退）；None 与 0/2 是两回事（跳过路径下内层该显示「没有内层」）。 真正的六格进度条在前端按 (outer.step − 1 + within) / outer.total 算，无内层细分时按走了一半计。
• 日志分层按内容白名单（_OURS 约 40 条正则，每条带 cli.py 行号出处）： 我们的输出进主日志，第三方噪声（「Bad things might happen unless you revert torch to 1.x」这种会吓到用户的话） 折进「详细输出」。一行都不丢，分错只是位置不对——layers 与 log 平行存、 main + detail 逐行还原得回 log，是恒等式不是承诺。认不出默认进详细区（白名单必然有漏， 放宽默认值的代价是吓人话跳上主日志）。唯一的第三方例外：uv 下载运行时那三行进主日志—— 第一次拉 36.7 MB 的那几分钟里，它们是「没卡死、正在下东西」的唯一证据。
• 取回是编号之外的一段（[取回] 前缀 → phase="fetch"），不是外层第三步—— 分母永远是 2，「有时候 2 步有时候 3 步」是要读代码才懂的东西。
• 降级标记 DEGRADED_MARKERS 14 条（跳过/降级/退回/未找到/未对上/警告/失败/……/听不了：/一个字都没听出来）， 命中的行在页面上标色并挂「查看原因 ▾」。最后一条是 2026-08-16 补的：它是「听不了：」的兄弟句—— 同一条路、同一个结局，白名单里那条「一行都没认出来」是 OCR 路的另一个字符串、一个字都对不上， 很容易误以为已经盖住了 DECISIONS 2026-08-16。

10.5 页面（static/index.html）

单页零外链（与产物同一条规矩；内联 SVG 不写 xmlns——写了会把 w3.org 的命名空间地址带进文件、零外链守卫当场红）。 视觉定稿「极光玻璃」：F 底 + E 玻璃卡 + 六色进度条；七个声部色相 CSS 变量逐个等于产品真画出来的那套—— 2026-08-15 曾照出壳子色板与 lanes.py 不是一套（裂帛 350 被挑成 312，差 38 度是肉眼分得出的两个颜色）， 于淼裁定壳子服从产品（反方向要重打四首歌，且浮点不确定性会产出不同 lanes），现由 tests/test_web_palette.py 钉着：真值从 murripple.lanes.LANE_SPECS import、 心籁从 voices.js 正则读，测试里没有第二份色相表；另单立一条「hsl() 里的值必须等于旁边注释自称的那个数」—— 一句声称了自己没做到的事的注释，比一个错的数值更坏 DECISIONS 2026-08-15。

产品语言上的几条硬决定：音频路歌词必填（没歌词「开始」是灰的并写着为什么； 勾「先让它在本机听一遍」是用户自己按下去的出口，听完停在校对框等人断句）； 网页不给 --no-lyrics——歌词是这个产品的卖点，给「不要歌词」的按钮等于邀请人做一份没有卖点的东西， 命令行留着那条路、那里的用户知道自己在干什么 DECISIONS 2026-08-16 于淼批准； 网页不给语言选择框——侦测存在的意义就是不逼人背 Whisper 语言码，「说出来（页面要）」与 「能推翻（命令行给得了）」是两件事，页面只需要前者 DECISIONS 2026-08-15； 听写等待期页面只报「这一步已经跑了 X」（页面自己量的墙上时间，误差 ≤ 700 ms 轮询间隔）—— 不预测任何事，没有百分比没有「预计还需」，有守卫把 %／预计／还剩一律挡住 DECISIONS 2026-08-16。校对框两条路共用、提醒后半句按路分： OCR 整行整行地漏、听写字会错且根本不断句——「说同一句就有一条在骗人」。

11确定性与可复现性的边界

「确定性」在本仓分三层，混着说就会说错 DECISIONS 2026-08-15「订正『产物可复现』」：

由此派生的验收纪律：真歌回归守卫的判据是「timeline 除新增顶层 stems 外逐字段相同 （canonical 序列化后比 sha256）」——「产物逐字节不变」这个判据数学上不可能成立 （pack 把 timeline 原文内联进 index.html，改 renderer 重新 bundle 后 index.html 又变一次） DECISIONS 2026-08-13。

12守卫体系与发布面

12.1 测试文化：变异检验

规模：pytest 1,094 条（52 份文件 + tools/ 下 2 份，本文写作时在补齐真歌产物与 align extra 后实跑 1,094 passed / 2 skipped——那 2 个 skip 是 test_web_palette 参数化里壳子色板本来就没有的两个声部，私仓恒有）； 渲染层 33 份 .test.mjs、301 pass（node --test + Playwright 三份 harness 页 DECISIONS 2026-08-16 管理窗口实跑）。取向写在 README： 每条断言都要能回答「什么样的错误实现能让它照样绿」——关键守卫都配了破坏实验： 改坏实现、亲眼看它变红、再还原。变异检验分两类不合并记：对实现变异（改坏代码）、对被测数据变异 （把该在的挪走 / 把不该在的塞进去——「守卫放宽后还抓不抓得住该抓的」只能靠后者验） MGMT.md 第七节。几条从血里换来的判据（复现者照抄即可少踩一轮）：

• 跳过是绿色的一种：任何 skip 分支都要问「它在别人的工作树/CI/干净检出上会不会永远走这一支」。 真歌回归守卫因此「缺产物即 fail 不 skip」，连环境变量逃生口都删了（误设即静默全绿）， 只留命令行上看得见的 --ignore=。
• 空集上的断言恒真：参数集由 glob/fixture 推导的测试必须有一条独立的「来源本身非空」锚点断言 （pytest 对空参数集默认给绿 + 跳过；「不带管理台」这类否定式守卫在空树上双双通过）。
• 断言命中的字符串有几个来源：子串断言先问这个问题（同一天栽过三次）；要断言就断结构。 异常消息断 exc.value.message 不断 str(exc)——jsonschema 顶层失败会把整份 schema dump 进 str，match= 随之失去分辨力。
• 断言跑的配置是否恰好躲开了会暴露问题的那一档——本项目最高频的失败形状（M5 第一版出现六次： 低采样率藏削波、短窗口藏滤波方向、16:9 视口躲开歌词溢出……）。对策：至少留一条在生产配置下复核； 对比用同一个种子只改被测参数。

12.2 内容守卫（防泄漏、防挪用）

12.3 公开树生成器（tools/make_public_tree.py）

公开仓是新建的干净树（一笔英文提交、无开发史），不是把私仓翻公开。生成器用 可判定的谓词排除，不用文件清单——「手编清单的固有失败方式就是漏；规则表新增文件时默认也是『进』， 但判据不看名字看性质」。八条第一遍规则 + 一条第二遍规则：

1. mgmt：MGMT/DECISIONS/BOOT 三个写死的名字 + docs/ · .claude/ · .superpowers/ · .replica-local/ 前缀。
2. private-material：songs/ 整棵（白名单例外：示例歌的 lyrics.txt 与 source.mp3 两份， 逐份列不整目录带走；source.mp3 是「版本库里没有、但要进公开树」的唯一一处，取不到就 SystemExit—— 它曾被公开仓自己的 .gitignore 挡在提交外、推送前最后一刻才逮到：用户 clone 下来 README 教的第一条命令当场失败 DECISIONS 2026-08-16）。
3. compose-engine：murripple/compose/ 整包。
4. compose-dependent-test：AST 判定 import 了 compose 的测试——用 AST 不用子串有实测依据： grep -c compose 在三份好测试上分别是 7/3/2，按子串排会误伤。
5. needs-real-songs：正则判定「读仓内 songs/ 目录」的测试（刻意不匹配小写 repo / "songs" 的纯路径比较）。
6. private-corpus：断行真值语料三份（real-lyric-rows.json 装着五首歌 235 句完整歌词， 它不在 songs/ 下、不叫 lyrics.txt、不 import compose——前六条谓词全部放行，是 2026-08-15 挖出的 228 处泄漏主体； 代价明写：公开仓因此没有 CJK 断行回归）。
7. reads-mgmt-docs：读仓内 docs/ 的测试（docs/ 整棵被 mgmt 排掉）。
8. release-tooling：tools/ 自身。
9. 第二遍 orphan-fixture：「排掉了消费者、没排掉被消费的数据」——留下来的夹具必须有活着的消费者， 「有人用」只认字符串字面量（注释与 docstring 不算——实测两句纯注释就能让守卫失守）。 这条规则是三次同形状事故（real-lyric-rows / real-songs-baseline / 04-align-unmatched）之后立的可判定规则，不是修那三次。

此外：候选来自 git ls-files（会被发布的就是版本库里的东西；有未跟踪文件直接停—— 这道防护在真实场景里挡住过一次「两份新 README 还没 add 就生成」）；tools/public/ 是 overlay （三语 README、LICENSE、英文注释版 pyproject、pipeline.svg、shell.png 逐份盖上）； --git-init 存在的理由是违禁词守卫用 git ls-files 取扫描对象、没有版本库会扫到 0 份然后全绿。 验收不信生成目录，要 git clone 一份来验——「端到端验的是生成出来的目录，而用户拿到的是 clone 下来的东西」是 2026-08-16 一天四次「核错了对象」的第四次 DECISIONS 2026-08-16。 发布配套脚本 tools/check_public_residue.py（残余中文与歌词残留扫描）刻意是脚本不是 pytest： 它此刻红得有原因，写成 pytest 会让红色变噪音；其二进制后缀表是 denylist 不是 allowlist—— 白名单曾漏掉没有后缀的 LICENSE（公开仓最重要的那份文件从来没被扫过），「白名单漏了没有声音， denylist 误报有声音——守卫要选有声音的那一边」。

12.4 许可与发布状态

• 私仓无 LICENSE = 保留全部权利（README 明写，早年误写 MIT 已订正）。
• 公开树 PolyForm Noncommercial 1.0.0——可改、可自用、不可商用。「这不是开源」 （OSI 定义里「不得歧视使用领域」是硬条款），对外措辞用「源码可见 + 非商用许可」；不用 CC BY-NC （CC 官方不建议用在软件上）。License 正文有守卫逐字节对照官方原文。
• 公开仓 ymustc/murRipple-public：161 份文件 / 7.3 MB（含示例歌 5.6 MB），三语 README （GitHub 那排标签加不了自定义项，通行做法是三份文件顶端互链），架构图是独立 .svg 相对路径引用—— GitHub 的 Markdown 会把内联 SVG 标签整个剥掉（§13）。从 GitHub 真 clone 验过： 722 passed / 2 skipped，README 教的第一条命令跑通出片 10.9 MB。
• 介绍站 docs/site/ 挂 murripple.miao-yu.com（无构建无依赖，双击可看）， 不进公开仓——它是独立可发布物，带进去等于放一份没人守恒等式的副本。
• 公开 demo 仓 ymustc/murripple-demo：内容是《Trempe-moi》的成品页—— 它能公开的全部理由是版权归作者本人。Pages 的 CDN max-age=600，推完十分钟内看到旧版不算部署失败。

13已知缺陷与复现者会踩的坑

13.1 已知未修缺陷（截至 dca6ff2）

13.2 复现者会踩的坑（第三方与工具链的真实行为）

14复现自检清单

「AI 能据此复现」是可操作的判据。一个没见过这个仓的复现者，做完之后逐条自问——每一条在本文都有唯一出处：

1. 契约：timeline.json 八个顶层字段、meta.language 可选的语义、base64 真解校验、 lane.stem ↔ 顶层 stems 交叉校验分开的异常类型、序列化格式（ensure_ascii=False、默认分隔符、无末尾换行）——§5。
2. 色相权威：六条真歌 lane 的 id/hue/stem/band 逐字等于 §4.3 的表；心籁 300 在渲染层； 合成曲另加 arp 165 / bell 60；任何界面色板必须从这份表派生且有守卫钉着——§4.3、§10.5。
3. 确定性：STEP=1/120 整数步数时钟、mulberry32(SEED ^ id)、禁 shadowBlur、 一切时变量是 t 的闭式或反查、quality 由 mode 决定、离线永不跳帧——§7；三层可复现性边界及「别拿 sha256 当判据」——§11。
4. 体积：15,000,000 字节硬失败（MB=1e6 的三条理由）、原子替换落盘、声明分轨全部到齐才准打包——§6。
5. 断行：9 汉字宽预算、两条规则按「用不用空格分词」二选一、静态宽度模型不 measureText、 LEAD_IN=0.5 在 t0 之前亮满——§7.5。
6. 语言：全仓唯一决定点、30 秒窗口、最响 5 窗 + floor 0.25 各挡一种失败、众数不过半即 unsure 且必须说出来——§4.6。
7. 分离与跳过判据：--shifts 0、扁平 vs 嵌套布局区分「外部提供」与「Demucs 产出」、 半套分轨拒绝、compose 换 seed 作废 timeline——§4.1、§9.2。
8. 包络：60 Hz RMS → dB(−60 floor) → uint8 → base64，global peak 共享且不含 mix——§4.4。
9. 壳子：只绑环回、PYTHONUNBUFFERED、分母判层、白名单认领、降级标记、 主日志截尾但详细区还原得回全量——§10。
10. 已知缺陷照单全收：尤其 onset 力度恒近零——行为等价包括等价的 bug——§13.1。

A附录：参数速查

A1 九声部总表

出处：murripple/lanes.py:19-24（真歌六条 hue/stem/band）· murripple/cli.py LANE_HUES/LANE_LABELS（合成曲八条）· renderer/src/ui/voices.js LABELS（中英名真相源）。声部名是本项目的创作内容 （参考项目那套不得使用，守卫扫着）。

A2 几何与时钟常数

A3 分析与取材层常数

A4 关键实测数字（全部有台账出处）