企业官网建设流程全解析

在 SoundCraft（纯 Rust 的 Pro Tools 风格数字音频工作站实现）中，Aux Input 与 Routing Folder 属于“读取总线”的条带：它们的输入来自其他条带写入的 bus，因此同一块音频内必须先算生产者、后算消费者。本文以 docs/aux-routing-order.md 为主线，结合 crates/mix/src/routing.rs、crates/mix/src/lib.rs 与集成测试 crates/mix/tests/it/aux_routing_order.rs，讲清楚三件事：订单何时被重新计算、无环图如何得到精确深度、以及为什么有环时整体退回旧的“八跳上限”算法。读完你可以据此判断一条深链返回（return）是否会吞掉首块采样，并知道去哪里验证。

1. 问题定位：为什么 Aux 需要一个“执行顺序”

MixEngine::render的信号流在 crates/mix/src/lib.rs 的模块文档里写得很清楚：

clips → trim/phase → inserts → pre-fader sends → fader/mute → pan → post-fader sends → busses → aux inputs → main → master faders

也就是说，Audio/Instrument/MIDI 条带先把信号写进 bus，然后 Aux/Folder 才从 bus 读回来。并且每个 block 开始时总线缓冲区都会被清零：

• crates/mix/src/lib.rs 中render对self.busses的每个通道执行take(frames).for_each(|x| *x = 0.0)。

这个“每 block 清零”的语义决定了顺序错误的后果非常具体：如果消费者先于生产者执行，它读到的不是上一块的残留，而是本块的静音。所以顺序不是优化，而是正确性前提。

原文档对此的开篇说明是：

Aux and Folder strips read audio from busses populated by earlier strips. The mixer prepares their execution order when the existing session-structure fingerprint changes, then reuses that order for subsequent blocks.

2. 什么时候重算顺序：结构指纹决定缓存失效

顺序并非每 block 都算一遍。render内部调用ensure_synced，用一个缓存键比较当前 session 结构：

// crates/mix/src/lib.rs#L340-L347 pub fn ensure_synced(&mut self, s: &Session) { let key = (structure_fingerprint(s), s.tracks.len(), s.busses.len()); if key != self.synced { self.sync(s); self.order = processing_order(s); self.synced = key; } }

structure_fingerprint定义在 crates/mix/src/routing.rs，注释明确写着它是“sync/processing_order依赖的所有东西”的哈希。逐字段看：

反过来也值得注意：音量、声像、静音/独奏、自动化、插件参数都不在指纹里。这意味着拖动推子、改 pan 不会导致重新拓扑计算，也不会重新创建插件；只有结构性编辑（改路由、加删 send、换插件、改格式、改轨道集合）才会让缓存的order失效。这一点与 docs/aux-routing-order.md 中“不改动 PDC 记账、插件处理、声像系数”的边界声明一致。

3. 无环图：最长生产者路径 + 稳定排序

processing_order的实现只有十几行，但把两条阶段边界交代得很清楚：

// crates/mix/src/routing.rs#L36-L51 pub(crate) fn processing_order(s: &Session) -> Vec<usize> { let mut order: Vec<usize> = (0..s.tracks.len()) .filter(|&i| s.tracks.get(i).is_some_and(|t| !matches!(t.kind, TrackKind::Aux | TrackKind::Folder))) .collect(); let mut auxes: Vec<usize> = (0..s.tracks.len()) .filter(|&i| s.tracks.get(i).is_some_and(|t| matches!(t.kind, TrackKind::Aux | TrackKind::Folder))) .collect(); if let Some(depths) = acyclic_aux_depths(s, &auxes) { // Stable sorting preserves session order among auxes at the same longest-path depth. auxes.sort_by_key(|&i| depths.get(i).copied().unwrap_or(0)); } else { // A cycle keeps the existing bounded ordering for the entire graph, ... auxes.sort_by_key(|&i| bounded_aux_depth(s, i)); } order.extend(auxes); order }

要点有四条：

1. 非 Aux/Folder 条带整体排在前面。这正好对应render的两阶段：第一阶段所有独立条带并行渲染并写总线，第二阶段才按order串行处理 Aux/Folder。见 crates/mix/src/lib.rs 与 crates/mix/src/lib.rs。
2. 同深度保持 session 顺序。sort_by_key是稳定排序，配合注释里的 “Stable sorting preserves session order”，这正是原文档所说“Strips at the same depth retain session order, preserving the previous ordering for ordinary short acyclic graphs”。
3. 深度来自最长路径，不是第一条遇到的路径。
4. 图不合法就整体换算法，不做局部混合。

3.1acyclic_aux_depths的算法结构

acyclic_aux_depths（crates/mix/src/routing.rs）本质上是 Kahn 拓扑排序的一个变体，但把“邻接关系”压缩成按 bus 聚合的依赖计数：

struct BusDependencies { remaining: usize, // 还有多少生产者没处理 depth: usize, // 生产者中的最大深度 last_producer: Option<usize>, // 去重：同一生产者多次路由到同一 bus last_processed: Option<usize>, // 去重：同一生产者只减一次计数 consumers: Vec<usize>, // 读这条 bus 的 Aux/Folder }

流程分三步：

第一步：登记生产者依赖。对每个 Aux/Folder 条带，枚举它写入的所有 bus：

// crates/mix/src/routing.rs#L110-L114 fn aux_output_busses(t: &Track) -> impl Iterator<Item = BusId> + '_ { std::iter::once(&t.mixer.output) .chain(t.mixer.sends.iter().flatten().map(|send| &send.target)) .filter_map(|route| if let Route::Bus(bus) = route { Some(*bus) } else { None }) }

mixer.output和每个 send 的target都被视作依赖边，这对应原文档的 “Output and send routes both create dependencies”。Route的取值在 crates/model/src/mixer.rs（None/Main/Bus(BusId)/Hardware(String)），只有Bus参与路由图；SendSlot的结构见 crates/model/src/mixer.rs。

去重逻辑就在这段：

// crates/mix/src/routing.rs#L67-L74 let dependency = busses.entry(bus).or_default(); // Output and multiple sends from this producer may name the same bus. if dependency.last_producer != Some(i) { dependency.last_producer = Some(i); dependency.remaining = dependency.remaining.checked_add(1)?; }

于是“某个 Producer 同时用 output 和 send 指向同一条 bus”只贡献一个生产者依赖，但音频依然按两路正常叠加（route_strip会分别写入，见 crates/mix/src/lib.rs）。这正是原文档的表述：“Multiple routes from the same producer to the same bus contribute audio normally but count as one producer dependency.”

第二步：把入度为零的消费者放入 ready 队列。读取的 bus 上没有未完成生产者时，该消费者可以被调度；Route::Bus(bus)之外的输入（Main、None、Hardware）直接视为就绪、深度 0：

// crates/mix/src/routing.rs#L77-L86 for &i in auxes { if let Route::Bus(bus) = &s.tracks.get(i)?.mixer.input { let dependency = busses.entry(*bus).or_default(); dependency.consumers.push(i); if dependency.remaining > 0 { continue; } } ready.push(i); }

第三步：出队、传播深度、递减计数。生产者出队时把depth提升到max(depth, 自己深度 + 1)，计数归零时把该深度一次性写给所有消费者：

// crates/mix/src/routing.rs#L88-L106 while let Some(&i) = ready.get(processed) { processed = processed.checked_add(1)?; let next_depth = depths.get(i)?.checked_add(1)?; for bus in aux_output_busses(s.tracks.get(i)?) { let dependency = busses.get_mut(&bus)?; if dependency.last_processed == Some(i) { continue; } dependency.last_processed = Some(i); dependency.depth = dependency.depth.max(next_depth); dependency.remaining = dependency.remaining.checked_sub(1)?; if dependency.remaining == 0 { for &consumer in &dependency.consumers { *depths.get_mut(consumer)? = dependency.depth; ready.push(consumer); } } } } (processed == auxes.len()).then_some(depths)

这里有三个容易被忽略的工程细节，都能从源码直接读出：

• 没有生产者 × 消费者邻接矩阵。BusDependencies只保存计数、最大深度和消费者列表，函数上方的注释写着 “Bus joins retain only producer counts and consumers, avoiding a producer-by-consumer adjacency matrix”。对于“多个上游汇入同一条 bus”（join）的会话，这比稠密矩阵省内存。
• 所有算术都用checked_*。checked_add/checked_sub一旦失败就返回None，而None的语义是“不把它当作无环图”，于是整个图退回有界算法。这是保守的失败方式：宁可保留旧序，也不产出越界或错乱的顺序。
• processed == auxes.len()是环检测。只要有节点因入度永不归零而无法入队（自身成环或位于环下游），计数就不相等，返回None，触发整图回退。

routing.rs自带的单元测试把这两条路径都钉住了：

// crates/mix/src/routing.rs#L158-L182：汇入 + 重复 send + Folder + 同深度会话序 assert_eq!(processing_order(&s), vec![0, 2, 3, 4, 1]); // crates/mix/src/routing.rs#L184-L203：整图回退，含自环与八跳并列 assert_eq!(processing_order(&s), vec![9, 8, 7, 6, 5, 4, 3, 2, 1, 0]); assert_eq!(processing_order(&s), vec![9, 8, 7, 6, 5, 4, 3, 2, 0, 1, 10]);

第一个用例构造了一条first_root → Folder → join的较长路径，同时second_root用 output + 两条 send 指向同一join；输入总线为first_bus的 Folder 必须先于消费者，而second_root与 Folder 同深度时保持 session 顺序（下标 3 在 4 之前，消费者 1 最后）。

4. 深度上限 8 的历史缺陷

原文档用一段话记录了被修掉的 bug：

The earlier ordering calculation capped every depth at eight. In a sufficiently deep reverse-created chain, that made a consumer tie with its producer and execute first. Because bus buffers are cleared each block, the consumer could receive silence. Exact acyclic depths remove that tie.

旧实现保留在 crates/mix/src/routing.rs，现在仅作为有环图的回退：

fn bounded_aux_depth(s: &Session, i: usize) -> usize { let mut d = 0; let mut cur = vec![i]; for _ in 0..8 { // 上限：8 跳 let inputs: Vec<&Route> = cur.iter().filter_map(|&k| s.tracks.get(k)).map(|t| &t.mixer.input).collect(); let feeders: Vec<usize> = auxes_feeding(s, &inputs); if feeders.is_empty() { break; } d += 1; cur = feeders; } d }

auxes_feeding（crates/mix/src/routing.rs）反向查找“输出或 send 指向这些 route 的 Aux/Folder”。因为循环被写死为0..8，一条 12 级返回链上，第 9 级之后的条带深度会被压到 8，与它的下游消费者并列；稳定排序随后按 session 顺序决定谁先执行——如果 session 是“逆序创建”的（消费者在数组里更靠前），消费者就会先跑，读到已被清零的 bus，输出静音。

这正是原文档所说 “even when tracks were created in reverse routing order or the chain contains more than eight returns” 的动机：同一个路由图，仅因创建顺序不同，音频就可能丢失。

5. 有环图：整图回退、确定性 tie、不改反馈策略

生成顺序的分支是有意“全有或全无”的：

// crates/mix/src/routing.rs#L41-L48 if let Some(depths) = acyclic_aux_depths(s, &auxes) { auxes.sort_by_key(|&i| depths.get(i).copied().unwrap_or(0)); } else { // A cycle keeps the existing bounded ordering for the entire graph, including any // independent acyclic branches. Feedback does not have a finite longest-path depth. auxes.sort_by_key(|&i| bounded_aux_depth(s, i)); }

代码注释补上了原文档没有展开的一点：回退作用于整张图，连那些本身无环的独立分支也一起退回。原因写在注释里——反馈环没有有限的最长路径深度，混用两套深度语义会让不同分支的排序不可比较。

原文档同时明确了三条“不做”的承诺：

If any cycle exists, the whole graph retains the previous bounded depth calculation and deterministic session-order ties. Preparation does not reject a cyclic session or change its feedback policy.

对应到代码：acyclic_aux_depths返回None后不报错、不 panic、不剔除条带，只是换排序键；render也从未因环而拒绝渲染。集成测试two_aux_cycle_preserves_session_order_audio_and_whole_graph_fallback（crates/mix/tests/it/aux_routing_order.rs）把“确定性”写成了可断言的事实：A→B、B→A 的两条返回，若 A 先则两者都听到源信号（增益 2.0），若 B 先则 B 读到空 bus（增益 1.0），并且“Buses clear each block, so neither order feeds a previous block back into this one”。

6. 改动边界：这个增量没有动什么

原文档用整整一段划边界，这一段对读者理解 PR 范围很关键：

This increment does not alter PDC accounting, plugin processing or failure containment, render-helper APIs, pan coefficients, Master insert order, playback ownership, or device selection.

这些“未改动项”都能在源码里找到各自的归属，说明它们与排序是正交的：

7. 与 #394 的关系：这只是运行时重写中的一个增量

原文档最后两段是范围声明，也是本文最容易被摘要工具引用的句子：

This is the routing-order increment of the remaining runtime work discussed in #394. Further runtime changes require independent treatment of prepared routing coefficients, workspace and instance lifetime, hosted automation delivery, graph latency, and explicit render failures. This increment does not claim to complete that rewrite or move all preparation off the audio callback.

拆开看，作者列出了五项仍需独立处理的后续工作：

1. prepared routing coefficients（预先准备好的路由系数）；
2. workspace and instance lifetime（工作区与插件实例生命周期）；
3. hosted automation delivery（宿主插件自动化投递）；
4. graph latency（图级延迟）；
5. explicit render failures（显式渲染失败）。

并且明确否认了两件事：本增量没有完成那次重写，也没有把全部准备工作移出音频回调。后一句在代码里可以观察到证据：ensure_synced是在render内部调用的（crates/mix/src/lib.rs），结构变化时它会走sync——而sync的文档自己就写着 “Allocates; call outside the realtime thread when the document changes, or letrenderdo it”（crates/mix/src/lib.rs）。换句话说，音频线程上仍可能发生同步与拓扑计算，这正是“未移出回调”的含义。

8. 回归测试：用公共 API 断言 PCM，而不是断言内部顺序

原文档的测试段落给出了明确的证据标准：

Regression tests use synthetic source samples and public mixer APIs. They cover deep reverse-created chains, output/send dependencies, duplicate routes, branching, Folder consumers, callback-size invariance, edits on an existing mixer and preserved cyclic behavior with PDC enabled or disabled. The same public fixture can run against the previous main to demonstrate the depth-cap failure independently of the new preparation helper.

测试文件的头注释也点明了意图（crates/mix/tests/it/aux_routing_order.rs），并且统一挂在 crates/mix/tests/it/main.rs 下作为一个测试二进制。下面把“文档描述 → 测试实现”逐条对齐。

8.1 夹具（fixture）设计

信号源通过SourceId(session.alloc())分配并插入session.pool，再落成Clip::audio(...)；SendSlot的level_db被显式设为0.0（因为默认是-144.0，见 crates/model/src/mixer.rs）。

8.2 覆盖矩阵

几个值得单独说明的断言细节：

• “回调大小不变性”怎么测出来的：render允许任意frames ≤ max_block，测试用MixEngine::new(48_000.0, 1024)后按不规则序列切片累积，最后与整段离线结果比较。这同时验证了“顺序在块之间保持稳定”，因为顺序若在某块被重算错位，拼接就会出现样本错位。
• 格式测试解释了 pan 语义：立体声转单声道用 -6 dB 折叠，保留的硬左 pan 让单声道只出现在左通道；而单声道总线送入立体声 Aux 时 unity 复制到两通道。这两条期望值都是从build_matrix的矩阵行为推导出来的，属于“实现事实”，不是文档声明。
• “可以跑在旧 main 上”的方法论：原文档说同一份公共 fixture 能在旧实现上复现深度上限缺陷。这不是一句空话——夹具只依赖Session、add_track、add_bus、render_range、MixEngine::render这些公开 API，不引用processing_order或acyclic_aux_depths，因此可以原样编译到旧版本上对比。

9. 如何在本地验证

仓库只读，以下是查看与运行方式（不涉及修改仓库）：

# 只跑路由顺序相关的集成测试二进制（每个文件是一个模块） cargo test -p soundcraft-mix --test it aux_routing_order # 跑 routing.rs 内的单元测试（拓扑与回退两条路径） cargo test -p soundcraft-mix processing_order # 一并查看与总线/延迟相关的相邻回归 cargo test -p soundcraft-mix --test it

阅读顺序建议：先看 docs/aux-routing-order.md 的结论与边界，再看 crates/mix/src/routing.rs 的两个算法，最后回到 crates/mix/src/lib.rs 看顺序如何被消费；需要更宏观的信号链上下文时参考 docs/architecture.md。

10. 修订历史

原文档末尾记录的版本事实：

Revision history: 2026-10-14 — exact acyclic routing order with the existing whole-graph cyclic fallback.

对应地，文档头部的Updated: 2026-10-14与本文引用的源码、测试处于同一增量。阅读时请以仓库当前内容为准：如果acyclic_aux_depths的签名、processed == auxes.len()的环判定或bounded_aux_depth的 8 跳常量发生变化，本文第 3、4、5 节的具体结论需要重新核对。