wezterm-bidi：面向终端渲染的纯 Rust 双向文本算法（UBA）实现与一致性验证

wezterm-bidi：面向终端渲染的纯 Rust 双向文本算法（UBA）实现与一致性验证

【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by @wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm

导读：bidi/目录下的wezterm-bidicrate 是 wezterm 终端模拟器中负责处理阿拉伯语、希伯来语等双向文本（Bidi）显示的纯 Rust 实现。它以Unicode 双向算法（UBA, UAX #9）为规范，为终端渲染链路提供段落方向解析、嵌入层级求解与行重排能力，并以约 78 万个官方一致性测试用例全数通过为质量基准。读完本文，你将掌握该 crate 的 API 设计、算法规则落地方式、在 wezterm 中的实际用途，以及如何在 Rust 项目中独立复用它。

1. 项目定位：为什么终端需要自己的 Bidi 实现

wezterm 是一个 GPU 加速的跨平台终端模拟器与多路复用器，其渲染管线需要对混合了从左到右（LTR）与从右到左（RTL）脚本的文本做正确排序。Unicode 标准通过 UAX #9：Unicode Bidirectional Algorithm 定义了如何把逻辑顺序的字符序列转换为视觉顺序——这就是wezterm-bidi所实现的核心规范。

根据 bidi/README.md，该 crate 明确声明了三个关键定位：

• 为 wezterm 开发，但不依赖 wezterm 的任何其他代码，可被当作独立库复用；
• 以“一致性（conformance）”为最高目标，而非追求功能堆叠；
• 是no_std兼容的 crate（仅依赖alloc），可运行在无标准库的嵌入式环境。

从 bidi/Cargo.toml 可以看出它的依赖极轻：运行时仅依赖工作区共用的log与wezterm-dynamic（用于为ParagraphDirectionHint等类型派生FromDynamic/ToDynamic，便于在 Lua 配置体系中序列化），开发依赖则是k9（快照断言库）与env_logger。

而终端场景与普通 GUI 有一个显著差异，这一点在代码中多次被强调（见 bidi/src/lib.rs）：

当reorder开启时，重排会应用规则 L3 处理非空格标记（NSM）。这对基于终端的应用更可取，而对会交给 HarfBuzz 等 shaping 引擎的现代 GUI 应用则未必合适。

也就是说，终端模拟器需要在“文本单元尚未合并为字形”的阶段就完成视觉重排，与 GUI 应用先 shaping 再布局的流程并不相同，这正是独立 Bidi 实现存在的意义。

2. 整体能力：能做什么、不能做什么

README 的 Status 一节给出了当前功能边界：

• 已实现：解析嵌入层级（embedding levels）、对行区间（line ranges）执行重排；
• 一致性声明：对 Unicode 官方的BidiTest.txt与BidiCharacterTest.txt测试用例实现 100% 通过，合计约78 万个测试用例。

代码结构上，bidi/src/lib.rs 将实现拆分为五个内部模块，与算法结构一一对应：

模块文件	职责
bidi/src/bidi_class.rs	双向字符类型（Bidi_Class）表与查询
bidi/src/direction.rs	Direction（LTR/RTL）与方向化迭代器
bidi/src/level.rs	嵌入层级Level、最大深度MAX_DEPTH = 125
bidi/src/level_stack.rs	显式嵌入/覆盖/隔离处理所需的层级栈
bidi/src/bidi_brackets.rs	括号配对数据（规则 N0 所需）

公开的 API 面很小：BidiClass、Direction、Level被pub use导出，核心入口是BidiContext与ParagraphDirectionHint。

3. 核心数据结构与使用方式

3.1 ParagraphDirectionHint：段落方向的四种提示

lib.rs 定义了段落方向的四种提示，并指出默认值为LeftToRight：

变体	含义
LeftToRight	直接按 LTR 处理，不做自动检测
RightToLeft	直接按 RTL 处理，不做自动检测
AutoLeftToRight	尝试自动检测，检测失败回退到 LTR
AutoRightToLeft	尝试自动检测，检测失败回退到 RTL

其中自动检测（规则 P2/P3）由 paragraph_level 实现：扫描第一个强类型字符（L/R/AL）决定段落层级，且正确处理隔离符（LRI/RLI/FSI/PDI）的计数；若段落内没有强类型字符，则回退到提示中指定的方向。

3.2 BidiContext：单次处理的上下文

BidiContext（lib.rs）持有算法处理过程中的全部中间状态：

pub struct BidiContext { orig_char_types: Vec<BidiClass>, // 原始字符类型（规则 L1/N0 需回溯使用） char_types: Vec<BidiClass>, // 正在被逐条规则改写的工作副本 levels: Vec<Level>, // 解析出的嵌入层级 base_level: Level, // 段落基础层级 runs: Vec<Run>, // 层级 run 列表 reorder_nsm: bool, // 是否启用 L3 重排非空格标记 }

它暴露的方法形成了一个典型的两阶段使用模式：

1. resolve_paragraph(&paragraph, hint)—— 以Vec<char>为输入（注意 API 与字符索引强耦合），解析整段文本的嵌入层级；
2. 之后按需调用runs()、line_runs(range)或reordered_runs(range)获取用于排版/渲染的结果。

3.3 BidiRun：同向连续片段的载体

BidiRun（lib.rs）代表原段落中一段具有相同嵌入层级（从而相同方向）的连续码点区间：

• direction：由层级推导出的方向；
• level：该 run 的嵌入层级；
• range：对应原段落的码点索引区间start..end；
• removed_by_x9：被算法 X9 规则“逻辑删除”的控制字符索引列表。

源码注释特别提醒（lib.rs）：X9 阶段删除的控制字符理论上可能出现在 run 中间，因此强烈建议使用indices()方法遍历时自动跳过这些元素，而不是直接使用range。ReorderedRun（lib.rs）则在BidiRun基础上额外携带indices字段——这是 L2 重排之后按视觉顺序排列的索引数组，是终端渲染时真正要消费的数据。

4. 算法落地：UBA 规则如何在源码中一一对应

resolve()方法（lib.rs）的调用序列完整映射了 UBA 的规则链，每一行都有对应的规则编号注释：

base_level 计算 → 规则 P2/P3（paragraph_level） explicit_embedding_levels → 规则 X1–X8（层级栈驱动） delete_format_characters → 规则 X9（删除格式化字符，置 NO_LEVEL） identify_runs + identify_isolating_run_sequences → 规则 X10/BD13 resolve_combining_marks → W1 resolve_european_numbers → W2 resolve_arabic_letters → W3 resolve_separators → W4 resolve_terminators → W5 resolve_es_cs_et → W6 resolve_en → W7 resolve_paired_brackets → N0（UBA63 新增） resolve_neutrals_by_context → N1 resolve_neutrals_by_level → N2 resolve_implicit_levels → I1/I2

其中几个值得展开的实现细节：

• 层级栈（X1–X8）：LevelStack（bidi/src/level_stack.rs）以固定数组实现，同时维护embedding_level、override_status（Neutral/LTR/RTL）与isolate_status三组状态，最大深度对应MAX_DEPTH = 125（见 bidi/src/level.rs），并显式跟踪overflow_isolate/overflow_embedding计数器来处理溢出控制字符。
• NO_LEVEL 与 X9：被 X9 删除的字符（RLE/LRE/RLO/LRO/PDF/BN）的层级被置为Level(NO_LEVEL)，其中NO_LEVEL = -1（lib.rs）。后续所有规则都通过removed_by_x9()判断跳过这些“已删除”位置——这是该实现处理控制字符的一贯策略。
• 规则 N0（括号配对）：resolve_paired_brackets（lib.rs）实现了 UBA 63 新增的括号方向解析。源码注释详细讨论了规范演进：UBA63/70 未定义栈溢出行为，而 UBA80 将栈深度明确指定为63，且规定溢出时仅中止当前隔离 run 序列的处理而非报错（lib.rs）。配对查找还针对 U+2329/U+232A 与 U+3009 之间的规范化等价做了硬编码兼容（见 seek_matching_open_bracket）。
• 规则 L1（行内空白重置）：reset_whitespace_levels（lib.rs）基于原始字符类型回溯，将段分隔符/换行符附近以及行尾的连续空白重置回段落基础层级，保证折行时空白不会破坏视觉顺序。
• 规则 L2/L3（重排）：reverse_levels（lib.rs）从最高层级向最低奇数层级逐级反转连续区间；reorder_non_spacing_marks（lib.rs）实现可选的 L3 规则，且注释说明“UAX9 规定 L3 在 L2 之后执行，但这里为了与 FriBidi 的实现保持一致而在 L2 之前处理”。

每个关键阶段之间都有dump_state跟踪点（通过log::trace!输出），配合env_logger可对算法过程做逐规则的可视化调试。

5. 一致性验证：约 78 万官方用例与快照测试

“conformance”不是口号，bidi/tests/conformance.rs 直接include_str!引入了 Unicode 官方数据文件：

• bidi/data/BidiTest.txt：以字符类型序列为输入，校验层级与重排结果；
• bidi/data/BidiCharacterTest.txt：以真实码点为输入，额外校验段落方向。

两个测试函数都实现了失败即停止（break）的策略以限制输出，并在末尾断言通过数与预期完全一致：

• bidi_character_test：断言level_passes == 91707且reorder_passes == 91707（conformance.rs）；
• bidi_test：断言level_passes == 770241且reorder_passes == 770241（conformance.rs）。

91707 + 770241 = 861948，这正是 README 中所说“约 780,000 个测试用例”的来源。测试还会核对context.base_level()是否符合BidiCharacterTest.txt给出的段落方向字段（conformance.rs）。

除此之外，lib.rs 内部还内置了三组单元测试：

• runs：对['א','ב','ג','a','b','c']输入，快照断言解析出 RTL run（level 1，范围 0..3）与 LTR run（level 2，范围 3..6），直观展示混排文本被拆分为同向片段；
• mirror：验证lookup_closing对{/[/]的括号类型判定；
• bidi_class_resolve：验证bidi_class_for_char对控制符、分隔符、空白、L/R 字符的分类；
• reorder_nsm：以 Terminal WG 推荐文档（combining.html）中的希伯来语“שלום”示例为输入，开启 L3 后验证 NSM 随基字符正确重排——这是终端场景下 L3 规则价值的直接证据。

6. 在 Rust 项目中独立使用 wezterm-bidi

6.1 直接依赖

由于 crate 不依赖 wezterm 其他模块（README），任何 Rust 项目都可以把它作为独立库引入。若以 path 依赖方式引用仓库内版本：

[dependencies] wezterm-bidi = { path = "bidi" }

或直接使用 crates.io 上发布的wezterm-bidi（当前版本见 bidi/Cargo.toml）。由于 crate 是#![no_std]（lib.rs）且只需alloc，在#![no_std]的宿主代码中也能使用。

6.2 官方示例：驱动一个 shaper

bidi/examples/shaping.rs 给出了完整的使用范式，它模拟了与 HarfBuzz buffer 兼容的 shaper 接口：

use wezterm_bidi::{BidiContext, Direction, ParagraphDirectionHint}; fn main() { // 输入是 Vec<char>，API 与原始码点索引强耦合 let paragraph = vec!['א', 'ב', 'ג', 'a', 'b', 'c']; let mut context = BidiContext::new(); // 交给算法自动检测段落方向；有更高层判断时可改用手动方向 let hint = ParagraphDirectionHint::AutoLeftToRight; // 解析整段文本的嵌入层级 context.resolve_paragraph(&paragraph, hint); struct ShaperBuffer {} impl ShaperBuffer { pub fn add_codepoint(&mut self, _codepoint: char) { /* hb_buffer_add_codepoints() */ } pub fn set_direction(&mut self, _direction: Direction) { /* hb_buffer_set_direction() */ } pub fn reset(&mut self) {} pub fn shape(&mut self) {} } let mut buffer = ShaperBuffer {}; for run in context.runs() { buffer.reset(); buffer.set_direction(run.direction); // 用 indices() 跳过 X9 删除的控制字符 for idx in run.indices() { buffer.add_codepoint(paragraph[idx]); } buffer.shape(); // 此后由调用方决定如何将 run 折行 } }

该示例点明了 API 设计的核心约束：UBA 与码点和原始文本索引强耦合，因此输入必须是Vec<char>，所有输出（range、indices）也都是指向原始段落的索引。

6.3 按行重排与折行

对于终端常见的折行场景，建议先对整个段落调用resolve_paragraph，再对每个行区间使用reordered_runs(line_range)（lib.rs）。该方法内部会先执行 L1 规则重置行界空白层级，再执行 L2 重排，并返回带indices（视觉顺序）的ReorderedRun列表；reorder_line则是更底层的变体，直接返回(levels, reordered)二元组供需要原始层级信息的调用方使用。值得注意的是，reordered_runs的重排数组与reorder_line在是否包含 X9 删除项上略有差异（lib.rs），消费方需按需选择。

7. 在 wezterm 中的实际落点

虽然 crate 是独立的，但它是 wezterm 渲染管线的一环。从源码检索可见其在 GUI 侧的引用：

• wezterm-gui/src/main.rs 引入wezterm_bidi::Direction；
• wezterm-gui/src/shapecache.rs 在 shape 缓存逻辑中使用Direction；
• wezterm-gui/src/termwindow/render/screen_line.rs 与 wezterm-gui/src/termwindow/box_model.rs 分别用于屏幕行渲染与盒模型布局中的方向判定。

这说明wezterm-bidi提供的Direction、run 划分与重排能力，最终服务于 wezterm-gui 中屏幕行的视觉顺序生成。这与 README 中“The focus for this crate is conformance”的定位互为表里：一个 78 万用例全过、与 Unicode 规范逐条对应的 Bidi 引擎，是终端在 LTR/RTL 混排场景下正确渲染的基石。

8. 关键结论速览

维度	事实（附依据）
实现目标	纯 Rust 的 Unicode 双向算法（UAX #9），面向终端场景，README
独立性与环境	不依赖 wezterm 其他代码；no_std+alloc，lib.rs
功能边界	解析嵌入层级 + 行区间重排，README
一致性成绩	BidiTest / BidiCharacterTest 100% 通过，约 78 万用例，conformance.rs
公开 API	BidiContext、ParagraphDirectionHint、BidiRun、ReorderedRun、BidiClass、Direction、Level
与规则对应	P1–P3、X1–X10、W1–W7、N0–N2、I1/I2、L1–L3 均有同名方法/注释落地，lib.rs
在 wezterm 中的使用	方向与重排结果被 GUI 渲染/缓存模块引用，如 screen_line.rs
可复用示例	bidi/examples/shaping.rs 演示驱动 shaper 的完整流程

若你的项目需要处理希伯来语、阿拉伯语等 RTL 文本，又希望把控制字符、括号配对与 NSM 处理等终端特有的边界情况交给一个经过官方一致性套件验证的实现，那么wezterm-bidi是值得直接复用或对照研读的参考实现。

【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by @wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm