[ZLHad]

What and why · 改了什么、为什么

一组小修：通用的 bug 和机械上的毛刺，不加规则。每一条都先在 3811691 上复现，再改。

#	项	发现	做了什么
1	bin/vh sfx place 空事件表、不给时长	max() 空序列，Python traceback，exit 1	说清楚："has no events, so the track has no length: give one (… <duration_s>)"，exit 1；给了时长照旧写一条那么长的静音轨
2	readcheck 读 canvas-film 页面时 Ctrl-C	subprocess.run 在 Ctrl-C 后只等 node 0.25 s 就 SIGKILL（会打断 profile 的删除），并打印 traceback；30 次探测里 11 次 exit −2 带 traceback	照 tools/shot_source.py 的做法改用 Popen：Ctrl-C 后最多等 node 5 s；没收到信号的 node 发 SIGTERM，再等 5 s，还不退才 kill；等待期间忽略第二次 Ctrl-C；安静地 exit 130
3	storyboard / rhythm 偶尔 exit 2	原因在 uv run：Ctrl-C 刚好落在它的 Python 退出的那一刻，uv 自己报 Failed to get PID of child process / ESRCH 退出 2（80 次里 1 次）。另外 KeyboardInterrupt 一直会打 traceback	storyboard.py、rhythm.py 接住 KeyboardInterrupt，exit 130；bin/vh 给这两条命令加了 on_ctrl_c：命令运行期间收到过 Ctrl-C，就以 130 结束，不管 uv 自己返回什么
4	canvas-film 模板的字体栈	bin/vh fonts check：900 的 serif（Songti SC Black）没有 − 和 –，落到 Times New Roman Bold；mono（Menlo）没有中文，落到 PingFang SC Regular。700 的 serif 本身有这两个符号	两个 unicode-range 的 @font-face，只管缺的那几个字：900 serif 的 U+2013、U+2212，mono 的中文区段；src 写的正是浏览器原来退到的字体（macOS 上 Times New Roman Bold、PingFang SC；Linux 上排在前面的是 Noto Serif CJK Black、Noto Sans Mono CJK SC），所以 macOS 上连用到这些字的帧也逐字节不变
5	textcheck / readcheck 的输出路径	已经不是 bug：#99 以后 readcheck 普通检查用私有临时目录，--export/--out 照写；textcheck 一直有 --out dir，所有输出（裁图、textcheck.json）都走它	没改
6	packcheck 的平台字数	一律按字符数；X 按加权长度算	加 X（x、twitter、推特；单个字母只在单独出现时算，小红书 xhs 不算）：按 X 开发者文档和 twitter-text config/v3.json 的权重，NFC 之后 U+0000–10FF 等四段算 1、其余算 2，emoji 序列算 2，链接一律 23，上限 280。一个标题写了几个平台时，各按自己的算法数，取最紧的那个。playbook/10 的表里加了 X 一行和来源 [S26]
7	bin/vh mix 结果行末尾的 "· 44.9 s)"	是处理用时，读起来像片长	改成 "· mixed in 44.9 s)"
8	非 4/4 小节里的 16 步 pattern	不是 bug：规则早就有，而且写着：每小节从头读，短了循环、长了截断（music.py 的说明自 #13，tools/audio/README.md 自 #62），要按拍数换节奏有字典写法 {"3": …, "*": …}。改成"按小节拍数拉伸"会改变现有语义，不算小修	没改
9	审阅页只回了部分决定	页面没说没回的怎么算（审阅台已经把它们记成按推荐）	审阅页底部和对话消息加一句"没回的决定按推荐走"（英文版同）；templates/REVIEW.md 每道关卡加一行 - 按推荐（没回）：，记决定号和推荐，例如 2 T1 · 3 C2。这一行放在"定了"上面：放在下面时，gatecheck 会把它当成"定了：{…}"下面列出的决定，没填"定了"也算过关（CI 抓到的）
10	bin/vh doctor <project>	没有	doctor 接项目参数（不加新命令），tools/engine_copy.py：canvas-film 或手绘项目里的引擎副本和现在的引擎逐个文件比，列出改过的（加减行数）、缺的（例如 src/06-time-map.js，并说 film.html 有没有加载它）、多出来的（项目自己在 src/ 里加的），附一条看 diff 的命令。片子自己的文件不比（canvas-film 的 src/50-shots.js、audio/、assets/，手绘的 src/scenes/、src/config.js）；ENGINE_README.md 对引擎的 README（老的手绘项目是 README.md）。只读；有差异 exit 1，不是这类项目 exit 2；不带参数还是原来的工具链检查

English summary. Ten small items found in use. Fixed: sfx place on an empty list; Ctrl-C in readcheck (Popen, wait for node to clean up, exit 130 quietly) and in storyboard/rhythm (no traceback; a bin/vh guard for uv run's own exit 2 race); the canvas-film fonts (unicode-range faces from the fonts the browser already fell back to: no warnings, frames byte-identical on macOS); X's weighted length in packcheck; the mix result line; review pages say unanswered decisions take the recommendation, with a REVIEW.md line; bin/vh doctor <project> compares a project's engine copy with the engine now. Not bugs, left: textcheck/readcheck outputs (already honour --out), non-4/4 step grids (the rule exists and is documented).

How it was verified · 怎么验证的

• tools/ci.sh --committed（VH_BASH=/bin/bash，shellcheck、pyflakes 按 CONTRIBUTING 的办法真的跑了）通过；跳过 1 项（这份干净检出里没有 HyperFrames 运行时）。新加 7 个用例：sfx place 空表；packcheck 的 X；doctor （新项目一致，旧副本列出改过、缺、多出的文件和 diff 命令，项目文件前后 cksum 一致）；审阅页和对话消息的说明；readcheck 和 rhythm 在页面挂起时收到发给整个进程组的 Ctrl-C（exit 130、无 traceback、没留 profile、没留 Chrome）。

• Ctrl-C 前后对比（按终端的做法发给整个进程组）：

  • readcheck，页面挂起时：改前 exit −2 带 traceback，改后 130、无输出；30 次扫 0.15–0.8 s：改前 11 次 −2 带 traceback，改后 9 次 130、无 traceback，都没留 profile。
  • rhythm / storyboard，页面挂起时：改前 130 带 traceback，改后 130 无 traceback。
  • rhythm 收尾时（0.3–0.6 s 扫描）：改前 80 次里 69 次 130 带 traceback、1 次 exit 2（uv 的 Failed to get PID of child process）；改后 150 次里 128 次 130、22 次已经跑完 exit 0，没有 2，也没有 traceback。

• 字体：模板加一镜画 S01 镜头（mono 400）和 −3 – 5（serif 700、900）。改前 bin/vh fonts check 两条 ✗（mono → PingFang SC Regular；900 serif → Times New Roman Bold），改后全部 ✓。原模板和加字的版本各取 7 帧（0.5–20 s，含 16.5 s 那一帧），改前改后逐字节相同（macOS，HeadlessChrome 152）。Linux 上没跑：那里的 src 顺序按 fontconfig 通常的后备排，没实测。

• packcheck：手算对照（139 个中文 278；链接后跟句号 23 + 1；👍🏽、👨‍👩‍👧、🇨🇳 各 2；café NFC 后 4；—… 3）。

• doctor：在一个 9-28 的手绘项目上只读跑过，列出 4 个改过的文件和改名前的 README.md。

• 合并了 main（6846273，Type docs' 禁止 sections split into floors and common misuses; general notes on facts, parallel agents, recordings; canvas-film's optional modules #112）进分支，CHANGELOG.md 两条都留（这条在上），合并后的 tools/ci.sh --committed 照样通过。

Found, not fixed · 发现了没修

• tools/gatecheck.py：关卡 ① 里"定了：{…}"（占位没填）下面只要跟着任何一条列表项（比如"- 改了：……"），就算已经定了；它的"定了下面列出决定"的写法没要求"定了："后面是空的。
• uv run 的 Ctrl-C 竞争（exit 2）不只 storyboard 和 rhythm：bin/vh 里经 uv run 跑的 music、sfx、beats、qa、mix 档位、tts、pace、cover-preview、style compare、sheet 都一样，这次只护了这两条。
• bin/vh sfx place … <duration> 的时长不是数字时是 float() 的 traceback。
• canvas-film 的 loadFonts 只按"family weight"报缺的字体，一台两个 900 serif 都没有的机器会把 "Film Serif 900" 报两遍。

Checklist · 自查

• tools/ci.sh --committed passes · 通过
• User-visible change noted in CHANGELOG.md → Unreleased · 已记进 CHANGELOG
• Ran every command touched · 涉及的子命令都真跑过（sfx place、readcheck、storyboard、rhythm、fonts check、frames、packcheck、mix profile=explainer（结果行是 "· mixed in 0.1 s)"）、review、doctor）
• Changed CLAUDE.md → ran bin/vh sync-agents · 没改 CLAUDE.md