HyperFrames changelog-video 技能的可视化路由表：visualization-registry 如何决定"如何演出来"

HyperFrames 仓库内置了一个面向 Agent 的技能（skill）changelog-video，它把每周的 changelog Markdown 转成 45–60 秒的品牌化视频。本文围绕该技能的核心路由文件 visualization-registry.md 展开：讲清它的四级路由体系（ui-recreate / ui-analog / terminal / checklist）、已验证的界面（surface）与类比特写（analog）目录，以及这些路由决策如何落入单文件骨架 master-skeleton.html 的具体坐标与动效约束中。读完后你可以掌握"show, don't tell"这一原则在 HyperFrames 视频流水线里的完整落地方式。

一、注册表在技能中的位置：先路由，后写脚本

SKILL.md 定义了该技能的第一指令（prime directive）："visualize, don't list"——每个 changelog 主题都必须用一个"实际界面的动画 mock 或忠实类比（faithful analog）"把这次变更"演出来"，而不是罗列文字条目。技能明确规定：

Route every theme/item through references/visualization-registry.md BEFORE writing the script; the registry decides ui-recreate / ui-analog / terminal / checklist.

也就是说，注册表是整条流水线的"分流器"：解析 changelog（Step 1）之后，进入 Step 2 "Visualization routing" 时，必须为每个主题从注册表里挑一个 surface，并写出一行决策记录：

theme → surface → the 2-4 sequenced actions the mock performs, each tied to a script phrase

如果注册表里没有任何 surface 适配、也找不到诚实的类比，就落到 checklist 场景——"don't invent fake UI for something we can't represent honestly"。SKILL.md 的反模式表也呼应了这一点：Fake UI for un-representable items 被列为反面做法，正确做法是 Honest checklist scene。

二、四级路由体系：从最强到最弱

注册表开头即声明："The routing table for 'show, don't tell'. Classes, strongest first"，按表现力从高到低分为四级：

1. ui-recreate——变更发生在"可以被忠实 mock 的界面"上。此时直接按真实界面解剖结构（anatomy）重演，可信度最高。
2. ui-analog——没有精确对应的界面，但存在一个"诚实的 UI 隐喻"（面板、仪表盘、流水线等），且该隐喻的行为本身就是这次变更。
3. terminal——变更是一个 CLI 命令或 flag，那就把它敲出来、展示结果。
4. checklist——非视觉化内容（修复清单、依赖版本升级），最后手段（last resort）。

注册表还有一条红线，值得单独强调：

Never invent UI that implies a screen that doesn't exist — an analog must depict the behavior (speed, batching, caching), not a fake product page.

即类比只允许描绘行为（速度、批处理、缓存），禁止伪造不存在的"产品页面"来暗示某个画面真的存在。这条约束防止了 changelog 视频退化为"PPT 假截图"。

三、已知界面目录（ui-recreate）

注册表的 "Known surfaces" 表为 7 个真实界面积累了**解剖结构（Mock anatomy）+ 已验证编舞（Proven choreography）**两列。前者定义 mock 长什么样，后者定义 mock 该"演"什么动作——两者都是被过往视频验证过可复用的模板。完整继承如下：

Surface	Mock anatomy（解剖结构）	Proven choreography（已验证编舞）
Studio editor / timeline	玻璃拟态应用框架：标题栏（traffic dots 红绿圆点、等宽字应用名、Export 胶囊按钮），带渐变画的预览条、标尺与刻度、轨道（lanes）、播放头（playhead）、等宽字标签的剪辑块（clips）	剪辑块落入/堆叠进轨道；拖拽→吸附到边缘/播放头并闪烁绿色吸附线；框选→整体移动→整体缩放；播放头 scrub 驱动预览画（hue-rotate）
Inspector / design panel	面板：等宽字分节头（INSPECTOR / VARIABLES）、键值行、发丝线分隔、虚线空槽	绑定药丸（{{ var }}）飞入属性槽；值切换用遮罩滑动（旧值上出、新值上入）；画布上画出选框
Canvas + element	迷你舞台卡片、虚线选框、实时文本元素	文本随面板编辑同帧更新（绿色下划线脉冲 = live-preview 时刻）
Variant renders	小卡片：展示字体标题 + 等宽字文件名	沿对角线瀑布式依次出场，间隔（stagger）≤0.15s
Storyboard view	一排场景缩略图 + 等宽字场景标签	缩略图瀑布式填入；其中一个被拖拽重排
Terminal / CLI	玻璃条、等宽字 19–20px、$ 提示符调暗	逐字打字（stagger 0.02s），结果行在 0.3–0.5s 停顿后落定
Render panel	RENDER 头、大号 tabular-nums 帧计数器、进度条（绿色填充 = 高潮时刻）、状态 chips	进度条 + 计数器以 power2.in 运行（慢→快读起来就是"更快"）；chips 落在旁白（VO）对应词上

这张表的设计意图在 "Adding a surface" 一节说得很直白：某个新 UI 区域第一次被 mock 时，就把它的 anatomy + choreography 记一行进来，"so the next changelog reuses it instead of re-deriving it"。注册表因此是一份随项目演进而累积的动画资产库，而非一次性文档。

四、已验证类比目录（ui-analog）

当变更没有可直接复刻的界面时，注册表给出 8 种"变更类型 → 类比 → 行为"的现成方案：

变更类型	类比（Analog）	行为（Behavior）
Color grading / LUT	素材画旁侧的滑杆行（label + track + knob）	每个旋钮移动同帧重新过滤画面（因果可见）
Render/extraction speed	render panel 计数器 + 进度条	缓动函数讲述故事；若断言是数字，加 before/after 时间 chip
Batching（帧、请求）	一排小刻度（ticks）	括号画出圈住分组；刻度向簇内靠拢
Caching	两条完全相同的请求行	第一行跑满整条进度；第二行瞬间短路到 ✓，带 cache chip
Import/translation pipelines（如 Figma→HF）	源产物卡片变形/对接进 HF comp 卡片——纯 DOM/CSS mock 的源（无 Figma API、无 tokens、不拉取任何东西）	分阶段：源卡片 → 提取出的 chips（tokens、components、motion）飞行 → 组装成 comp；chips 是载体
One-pass / dedupe	N 条并行条目行塌缩到一条共享轨道	各行滑入同一条 bar；计数 chip 递减
Concurrency caps / locks	一串 chips 进入闸门的队列	前 k 个通过，其余被拦；闸门 chip 显示上限值
Error surfacing（toast、reason）	界面角落长出一张 toast 卡片	操作轻微失败 → toast 滑入，等宽字原因文本

注意 Figma→HF 那一行的括号限定："a pure DOM/CSS mock of the source (NO Figma API, no tokens, nothing fetched)"——它精确划出了 mock 与真实集成的边界：视频里呈现的是视觉隐喻，而不是真的去调 API。这与第二节"analog 描绘行为而非假页面"的红线一致。

五、checklist 场景：有纪律的最后手段

对于确实非视觉化的内容（可靠性修复清单、依赖升级），注册表规定了严格的"兜底配方"：

• 玻璃卡片（Glass card），≤6 行等宽字条目；
• 绿色 ✓ 逐个落定，节奏绑定到每个条目的 VO 词上：back.out(1.5)、0.3s，外加该行的亮度脉冲；
• 超过 6 项的：裁掉，"they live in the digest link"（完整清单留在结尾的 digest 指向里）。

这与 SKILL.md Step 1 的预算约束互相咬合：每个主题最多 1 个 hero 可视化 + 3 个口播条目，30 条 item 的 changelog 也只产出 ≤14 个口播 beat；其余全部交给结尾的 "full digest" 指针。

六、路由决策如何落入骨架：坐标、绿色时刻与 VO 时间戳

注册表决定"演什么"，而 mock 最终写在从技能资产复制出来的单文件骨架里。master-skeleton.html 中有三处直接约束了每个主题的 mock：

1. 布局坐标：每个主题 slide 的注释明确写着 <!-- the mock, from references/visualization-registry.md, y ∈ [288, 944] -->——mock 内容必须落在 y 坐标 288–944 的区间内，避开顶部 chrome（kicker chip、sec-chip 在 top: 44/128px）和底部字幕轨（#cap-line 位于 top: 990px、高 52px）。这就是注册表中每条 choreography 的"舞台边界"。
2. 品牌约束：骨架 CSS 定义了品牌色板——奶油白 #f5f6f4、克制的绿色 #5ef17c（"rationed green"）、玻璃卡 rgba(10,12,11,.78) 配绿色调边框；脚本区注释要求 "One green (#5ef17c) moment per scene"。注册表里诸如 "progress bar (green fill = the moment)"、"green underline pulse" 这类措辞，指的就是每场景唯一的高潮绿。
3. 时间锚定：骨架注释 "Every beat lands on a vo-words.json timestamp (local = master − scene start)"——mock 的每个动作节拍都要对齐 TTS 产出的词级时间戳，而非任意时刻。注册表中 "chips land on their VO words"、"✓ ticks landing on each item's VO word" 等描述，落点正是这里的时间模型：音频是时钟（the audio is the clock），视觉 beat 只是对 VO 词的响应。

骨架的 caption-rail IIFE（LINES 数组）与注册表的关系是分工：字幕层由 script-voice.md 描述的双层脚本（display 层给字幕、spoken 层给 TTS）驱动，配合 lexicon.json 的发音词表（如 "JSON": "jay-sawn"、"CLI": "C L I"）保证发音；而视觉层则由本注册表驱动。script-tokens.json 示例展示了双层 token 的实际形态，其中 {"display": "CLI", "spoken": "C L I"} 这样的分叉 token 正是两层分离的具体物证。

七、扩展注册表：一次投入，周周复用

注册表末节 "Adding a surface" 给出维护约定：

When a new UI area ships, add a row here (anatomy + choreography) the first time it's mocked, so the next changelog reuses it instead of re-deriving it.

这使它成为一份"越用越省"的资产：每当 HyperFrames 上线新的 UI 区域，Agent 在第一次 mock 该区域时就把解剖结构与编舞补一行进去，后续每周 changelog 视频直接复用，而不必重新推导。对以 Agent 为使用者的项目（README 标语即 "Write HTML. Render video. Built for agents."），这种把动画决策显式沉淀为可检索表格的做法，比依赖生成模型自由发挥更能保证周更视频的风格一致性与 lint/门禁可验证性。

小结

• 路由优先级固定为 ui-recreate → ui-analog → terminal → checklist，checklist 仅用于真正非视觉化条目；
• 7 个已知 surface 与 8 种已验证 analog 构成可直接复用的"mock 目录"，每条都带解剖结构与编舞；
• 红线：类比只描绘行为，不伪造不存在的界面；
• 决策记录格式为一行 theme → surface → 2–4 个绑定到脚本短语的动作；
• 落地约束在骨架中：mock 限 y∈[288,944]、每场景一个绿色高潮、每个 beat 对齐 VO 词时间戳。