Hyperframes 轨道级共享自动化车道：把“属性车道”交还给整条轨道而非选中片段

本文解读 Hyperframes 仓库中 plans/automation-lanes-shared-rows.md 这份设计决策记录：当多条音频片段（clip）共享同一条时间线轨道时，自动化包络车道（automation lane）该如何排布才不产生语义误导。核心结论是——车道行属于轨道（track），包络与编辑手势仍属于片段（clip）。读完本文，你将理解“属性即行”的分组模型、为什么分组键不能是 fx.<nodeId>.<param> 这类目标地址，以及 Hyperframes studio 时间线在 automationLaneData.ts 与 TimelineAutomationLaneSlot.tsx 中的具体落地方式。

一、要解决的 bug：单片段车道被误读为“整行特效”

在 Hyperframes 的时间线中，一条轨道行上常常并排摆放多条音频片段——例如四段画外音（narration slice）。此前的渲染方式以选中片段为基准去组织该行的自动化车道，于是出现三处相互叠加的误导：

1. 行头以选中片段命名：行头标签显示的是当前选中的那条片段（如 “Narration 2”），并在徽标上标注 4（表示该行有 4 个元素）；
2. 行头罗列的是该片段的特效：例如 “Peaking EQ 1 kHz / Q” 只属于选中那条 clip 的自动化车道；
3. 选中切换即静默换包络：用户移动选区后，行头上显示的特效名和可见的包络曲线会整体换一套，仿佛“整行的参数被换掉了”。

需要澄清的是：包络 SVG 的几何范围本身一直是正确的。TimelineAutomationLaneSlot 在渲染时就已用 leftPx={element.start * pps} 与 widthPx={element.duration * pps} 把每根包络约束在所属片段的起止区间内（当前源码中宽度还会做 Math.max(element.duration * pps, 4) 的最小 4px 钳制，见 TimelineAutomationLaneSlot.tsx）。真正误导人的是标签列和通栏整行的视觉效果——一根只属于某一片段的曲线，看上去却像在统治整条轨道行。毛病出在“信息架构”，不在“几何绘制”。

二、被否决的方案：为什么不做“轨道级 FX”

面对这个问题，最直觉的解法也许是“既然车道不该只属于一条片段，那就让特效属于整条轨道”。这份决策记录明确否决了该方向，并给出了源码级的理由：

• 没有任何“轨道”实体可以挂载一条 FX 链。data-track-index 在核心运行时中只在 core/src/runtime/timeline.ts 一处被读取（源码 341–350 行用它挑选带时间轴的剪辑元素、592 行注释也确认“轨道归属忠实地沿用作者书写的 data-track-index”），其作用仅仅是为元素选择一行。代码里没有 track 元素、没有 track 清单，做轨道 FX 等于要在两套运行时里凭空发明“存储位置”和“总线节点”。
• 两套音频运行时都是逐元素建图的：每条片段各有一条完整的 source → chain → gain → master 链路（preview 与离线 render 共用同一套 graph builder），轨道级 FX 需要在这两处各插入一个额外的 bus 级节点。
• 领域语义也不支持：同一行里的两条 take 经常需要不同的处理；而画外音 carve（去声/闪避）机制点名作用在具体片段上，轨道级概念表达不了这种细粒度。

一句话总结被否方案的教训：“该行有一个 4 徽标”不等于“该行有一条特效链”，轨道只是排版容器，特效的所有权始终在片段上。

三、拍板的决策：同属性同特效的片段共享一行

最终的取舍是折中而非二选一：

• 特效仍然留在片段上（clip-local）；
• 但多条片段如果自动化的是“同一特效的同一参数”，就在轨道下共享同一行车道——例如四段画外音都自动化了 “Peaking EQ 1 kHz / Q”，那它们就画进同一根 “Peaking EQ 1 kHz / Q” 行，每根包络各自画在自己片段的时间跨度上；
• 不同的参数、或同一参数挂在不同特效上，则是各自独立的行。

这带来一个读者视角的极简规则：一行 = 一个“可读的参数身份”。行的存在不依赖“谁被选中”，而依赖“这条轨道上有哪些 clip、它们各自的链上存在哪些参数”。

四、实现要点：五个必须守住的边界

决策记录给出了五条实现准则，每一条在仓库源码里都能找到对应的印证。

1. 分组键必须是语义标签，绝不能是 lane target

自动化数据模型里，lane 的 target 形如 volume 或 fx.<nodeId>.<param>（见 plans/audio-automation-lanes/SPEC.md 中 data-automation 的 JSON 结构）。node id 是按链铸造的（per-chain minted），因此一条片段里的 fx.n1.q 与另一条片段里的 fx.n1.q 完全可能是两个不同的特效——拿 target 做分组键，会把无关的包络拼进同一行，又把真正同源的包络拆到不同行。

所以分组键采用 automationLaneData.ts 中已经存在的 automationLaneLabelParts 计算出的人类可读标签：特效名 + 区分同门特效的特征值（如滤波器的中心频率）+ 参数名。这正是 laneGroupKey 的实现——直接委托给 automationLaneLabel 返回整行标签，从而保证“行的身份”与“行显示的名字”永不脱节。纯 volume 车道的键就是它自己（没有特效名与频率，靠 range.label 即参数名来分组）。

automationLaneLabelParts 会把标签拆成两行以便在窄列中排版：name 是特效名（必要时带上格式化后的频率，如 “Peaking EQ 1.6 kHz”，formatHz 负责把 1600 显示成 “1.6 kHz”），param 是被驱动的旋钮（如 Q、gain）。三根都叫 “Peaking EQ” 的带通如果不写频率，读者根本分不清谁是谁；而光写频率又区分不了 bell 与 shelf，所以两个部分缺一不可。

2. 行来自轨道，而不是来自选区

此前 TimelineAutomationLaneSlot 只绑定一个元素，这正是包络随选区“闪现/消失”的根源。决策要求它改为接收“该行上的全部 clip、它们的链、以及各自分组后车道的并集”。

源码中该重构已经完成：TimelineAutomationLaneSlot.tsx 的 props 是 elements: readonly TimelineElement[]——注释明确写着“轨上所有 clip，按行序，而非仅选中的那一个”。组件内部先用 groupAutomationLanes(clips) 得到轨道级分组，再用 getTimelineElementIdentity(element) 反向建立 rowsByClip 映射，最后为每条 clip 渲染一个 ClipAutomationLanes。这一层“轨道算行、按 clip 回查”的数据流，就是“车道不再随选区跳动”的保证。

3. 手势与选区仍逐片段保留

“共享一行”共享的是车道轨道（lane track），绝不是把两条 clip 的包络合并成一条可整体拖拽的曲线。源码把每条 clip 的包络渲染拆成独立的 ClipAutomationLanes 组件（TimelineAutomationLaneSlot.tsx），其注释点明了 React 层面不得不这么做的原因：hooks 不能跑在循环里，所以“遍历 clip”要写成“遍历组件”。每条 clip 由此保有自己的 SVG、自己的手势绑定（lanes.bind(element, isSelected)）、自己的选择框，两条曲线永远不可能被当成一个对象去拖动。

其中还包含一个值得注意的细节——stale-selection 守卫：如果选中的 lane target 因特效被从链上删除而消失，组件会主动 onRangeClear() 清掉指向不存在目标的矩形选区，避免留下“选中了空气”的残留 UI。另有按 lane 而非按绑定生效的只读策略：isCarveLane 会把 carve 生成的包络标为只读并附上引导文案（“改强度，或关闭 carve 后手动编辑”），因为 carve 每次重分析都会重写这些包络，拖了也白拖。

4. 行高按“分组行数”计算，而不是按“片段的车道数”

一条分组行里可能有 4 条片段，但行数只取决于分组的数量。组件中每根包络的纵向位置为 topPx={top + rowIndex * AUTOMATION_LANE_H}（rowIndex 来自 groupAutomationLanes 返回组的序号），第一行的 y 值则来自 getTimelineLaneTop。也因此，getTimelineLaneTop 与行头行的位置都必须跟随分组计数，而不是跟随任一 clip 自己的车道数。

顺带一提，行高常量 AUTOMATION_LANE_H 独立成模块 automationLaneHeight.ts，最终取值为 72px。其注释交代了从 48px 演进到 72px 的体感依据：车道携带“值轴”而非一排菱形关键帧，48px 扣掉上下各 6px 内边距后只剩 36px 画整个 0..1 推子，11px 的抓取手柄就盖掉了三分之一的值域；72px 留下 60px 的绘图区，才让“指哪打哪”和“相近取值的两点可分别抓取”成为可能。

5. 行头标签跟随“轨道”而不是“某条片段”

当一行里躺了多条 clip 时，行头（如 “Narration 2” 这种以选中片段命名的标签）不再有意义。决策规定：多片段的行按轨道身份命名，车道标签则只需表达“属性本身”——它已经是该分组的身份了，不需要再带 clip 限定词。仓库中 TimelineTrackHeader.tsx 与 TimelineGroupLaneLabels.tsx 承担了行头与分组标签列的渲染，标签列的拆分逻辑（name / param 两行）与画布车道读取的是同一个 automationLaneData.ts，从根本上避免了“标签列与包络行列不一致”这种比排序更难修的错位。

五、留给实现者的一个语义判断题：空档怎么办

决策记录最后留了一条“值得在实现中定夺”的边界：某条在行上的 clip 如果没有自动化该分组属性，那么它在这一行里的区间应当是留白——包络在那里“本来就不存在”，因此什么都不画；绝不画一条停留在存储值上的水平直线，因为一条平直的线会让人误以为“这里确实有一条包络，只是恰好是平的”，从而把“未自动化”伪装成“自动化为恒定值”。

源码落实了这条语义：groupAutomationLaneData.ts 中 AutomationLaneGroup.entries 的注释写明“未自动化该属性的 clip 直接缺席（absent），给它在行里留下空档”，groupAutomationLanes 也只在 clip 实际携带对应 lane 时才把它 push 进组的 entries。

六、配套验证与测试

分组与渲染的关键逻辑均有测试背书，仓库中可以找到：

• automationLaneData.test.ts：覆盖标签解析、分组键与轨道级分组等纯函数；
• TimelineAutomationLaneSlot.test.tsx：验证“每条 clip 各自落进共享行”的槽位渲染行为；
• groupAutomationElement.test.ts 与 useTimelineTrackLayout.test.ts：覆盖分组元素与行布局的关联逻辑。

结合这份决策记录自称已在提交 1e21d763b（2026-08-07）落地，以及上述源码/测试的实际存在，可以确认共享车道行并非停留在纸面 spec，而是已成为 studio 时间线的既成实现。

七、小结

自动化车道共享行这一决策，本质是在回答一个所有非线性编辑器都要面对的问题：“当一行里有很多条 clip 时，行下面的参数车道到底属于谁？” Hyperframes 的答案是三层清晰的所有权划分——

层面	归属	体现
特效链与参数	片段（clip）	逐元素 source → chain → gain → master，data-fx-chain 序列化在元素上
车道行（lane track）	轨道上的属性分组	groupAutomationLanes 按键并集，TimelineAutomationLaneSlot 以全轨元素为输入
包络与编辑手势	片段（clip）	每 clip 独立 SVG、独立手势、独立选区，拖拽互不合并
行高与头部标签	分组	AUTOMATION_LANE_H（72px）按分组行计数，行头跟随轨道

最值得迁移到其他设计决策中的经验是两条：其一，永远不要拿会随实例变化的技术标识符（per-chain 的 node id）去充当面向读者的分组键，能稳定代表“同一参数”的只有语义标签；其二，行容器与内容手势必须分层解耦——共享的是“排布的位置”，绝不共享“可被整体拖拽的对象”。这两条原则既修掉了选区跳动换包络的 bug，也让未来任何一条新 clip 落到轨道上时，都能自动、稳定地并入它应属的那一行。