跨领域库测试、夹具及遥测或 rollout 支持

fn goal_accounting_uses_turn_start_baseline_for_exact_deltas()

作用：这个测试确认系统会用“轮次开始时的 token 数”当基准，只记录这一轮新增加的 token。它防止记账时把之前已经存在的消耗重复算进去。

数据流：进去的是一个新的 GoalAccountingState，以及两份 token 读数：一份是轮次开始时的旧读数，一份是后来更新后的新读数。测试先调用 start_turn 记住起点，再调用 record_token_usage 记录新读数，然后检查算出来的本轮增量和还没刷新的线程增量都是 28。出来的结果是：如果代码算错，断言会失败；如果算对，测试通过。

调用关系：这是验证正常记账路径的测试。它自己准备状态和 token 数据，其中 token 数据交给 token_usage 这个小帮手生成；随后它触发 GoalAccountingState 的开始轮次和记录用量流程，最后用 assert_eq! 检查结果是不是预期值。

调用图：调用 2 个内部函数（default, token_usage）；外部调用 1 个（assert_eq!）。

fn goal_accounting_ignores_plan_mode_turns()

作用：这个测试确认 Plan 模式的轮次会被忽略，不会产生 token 记账记录。这样可以避免把“规划阶段”的消耗混进正式目标的账里。

数据流：进去的是一个新的 GoalAccountingState、一个 Plan 模式的轮次，以及一份模拟的 token 用量。测试先把 turn-1 标记为 Plan 模式开始，再尝试记录 token 用量。出来的结果应该是 None，也就是“没有记账结果”；如果系统返回了实际记录，就说明 Plan 模式被错误地算进去了。

调用关系：这是验证特殊跳过规则的测试。它同样使用 token_usage 生成测试数据，也会用默认的 TokenUsage 作为开始时的空读数；最后通过 assert_eq! 确认 record_token_usage 没有返回记录。

调用图：调用 2 个内部函数（default, token_usage）；外部调用 2 个（assert_eq!, default）。

fn token_usage(
    input_tokens: i64,
    cached_input_tokens: i64,
    output_tokens: i64,
    reasoning_output_tokens: i64,
    total_tokens: i64,
) -> TokenUsage

作用：这是测试里的小工具函数，用来方便地创建一份 TokenUsage 数据。它让两个测试不用反复手写同样的结构体字段。

数据流：进去的是五个数字：输入 token、缓存输入 token、输出 token、推理输出 token、总 token。函数只是把这些数字按字段装进 TokenUsage 结构里，然后返回这份完整的用量数据；它不读取外部状态，也不改动任何东西。

调用关系：它是测试数据工厂，被 goal_accounting_uses_turn_start_baseline_for_exact_deltas 和 goal_accounting_ignores_plan_mode_turns 调用。两个测试都靠它快速准备不同场景下的 token 读数，然后把这些读数交给记账状态去验证规则。

调用图：被 2 处调用（goal_accounting_ignores_plan_mode_turns, goal_accounting_uses_turn_start_baseline_for_exact_deltas）。

fn path(name: &str) -> PathBuf

作用：这是测试里的小工具，把一个字符串变成文件路径对象。这样测试里写路径更短、更清楚。

数据流：进去一个路径文字，比如“a”或“/tmp/skills” → 它把文字包装成系统能理解的 PathBuf 路径对象 → 出来一个可传给监听器和断言使用的路径。

调用关系：它被多个测试反复使用，特别是节流、防抖、订阅匹配、非递归监听和事件循环过滤测试。它不做判断，只是帮这些测试准备输入数据。

调用图：被 7 处调用（debounced_receiver_coalesces_each_event_batch, debounced_receiver_flushes_pending_on_shutdown, matching_subscribers_are_notified, non_recursive_watch_ignores_grandchildren, spawn_event_loop_filters_non_mutating_events, throttled_receiver_coalesces_within_interval, throttled_receiver_flushes_pending_on_shutdown）；外部调用 1 个（from）。

fn notify_event(kind: EventKind, paths: Vec<PathBuf>) -> Event

作用：这是测试里造“假文件系统事件”的工具。测试不用真的去操作系统等事件，而是自己拼一个事件喂给监听器。

数据流：进去一个事件类型和一组路径 → 它先创建 notify 库的 Event，再把这些路径逐个塞进去 → 出来一个完整的模拟事件。

调用关系：它主要服务于 spawn_event_loop_filters_non_mutating_events。那个测试用它制造“打开文件”和“创建文件”两种事件，验证事件循环只放行真正会改变文件的事件。

调用图：被 1 处调用（spawn_event_loop_filters_non_mutating_events）；外部调用 1 个（new）。

async fn throttled_receiver_coalesces_within_interval()

作用：这个测试确认“节流收件器”不会在很短时间内连续乱发通知。第一次变化会马上出来，紧接着的变化要等节流时间到了再一起出来。

数据流：先创建发送端、接收端和节流接收器 → 发送路径 a，应该立刻收到 a → 再发送 b、c，半个节流间隔内应该收不到 → 时间够了后收到合并后的 b、c。

调用关系：它由异步测试运行器执行，调用 ThrottledWatchReceiver::new 建收件器，用 path 准备路径，用 timeout 防止测试无限等待，最后用 assert_eq! 检查结果。

调用图：调用 2 个内部函数（new, path）；外部调用 3 个（from_secs, assert_eq!, timeout）。

async fn throttled_receiver_flushes_pending_on_shutdown()

作用：这个测试确认节流收件器在发送端关闭时，不会把已经攒着但还没发出的变化弄丢。关闭前的待发消息必须先吐出来，然后才报告通道结束。

数据流：先发送 a 并收到它 → 再发送 b，但马上丢掉发送端表示关闭 → 接收器应该先返回 b → 下一次接收才返回 None，表示再也没有消息了。

调用关系：它验证关闭流程里的兜底行为。测试运行器调用它，它使用 ThrottledWatchReceiver::new、timeout 和 assert_eq! 来观察关闭时的输出顺序。

调用图：调用 2 个内部函数（new, path）；外部调用 3 个（from_secs, assert_eq!, timeout）。

async fn debounced_receiver_coalesces_each_event_batch()

作用：这个测试确认“防抖收件器”会等一小段安静时间，把连续到来的变化合成一批。它适合处理保存文件时一连串小事件的情况。

数据流：先发送 a，等待防抖间隔后收到 a → 再发送 c，半个间隔内应该还不发 → 又发送 d，最后收到 c 和 d 合成的一批。

调用关系：它由 Tokio 异步测试运行器执行，调用 DebouncedWatchReceiver::new 建立防抖接收器，并用 timeout 验证它不是太早发，也不会永远不发。

调用图：调用 2 个内部函数（new, path）；外部调用 2 个（assert_eq!, timeout）。

async fn debounced_receiver_flushes_pending_on_shutdown()

作用：这个测试确认防抖接收器在上游关闭时，会把正在等待防抖时间的消息立即交出来。否则程序退出时可能漏掉最后一次文件变化。

数据流：创建通道和防抖接收器 → 发送路径 a → 丢掉发送端表示没有后续消息 → 接收器先返回 a → 再返回 None 表示结束。

调用关系：它检查 DebouncedWatchReceiver::new 创建出的对象在关闭场景下的行为，依靠 timeout 避免测试卡死，依靠 assert_eq! 判断输出是否符合预期。

调用图：调用 2 个内部函数（new, path）；外部调用 3 个（from_secs, assert_eq!, timeout）。

fn is_mutating_event_filters_non_mutating_event_kinds()

作用：这个测试确认事件过滤规则能分清“真的改了文件”和“只是访问了文件”。创建和修改应该算变化，打开文件不应该算变化。

数据流：构造三类事件：创建、修改、访问打开 → 分别交给 is_mutating_event 判断 → 期望前两个返回 true，访问打开返回 false。

调用关系：它直接验证底层过滤函数 is_mutating_event。这个过滤规则会被事件循环使用，防止普通读文件也触发重新加载之类的动作。

调用图：外部调用 1 个（assert_eq!）。

fn register_dedupes_by_path_and_scope()

作用：这个测试确认同一个路径、同一种监听范围重复注册时，不会让底层监听重复增加。这样可以避免浪费系统资源。

数据流：创建临时目录和两个子目录 → 给同一路径注册两次非递归、一次递归，再给另一路径注册递归 → 查看内部计数 → 同一路径应只按范围记录，另一路径单独记录。

调用关系：它通过 FileWatcher::noop 建一个不碰真实系统的监听器，再由订阅者注册路径，最后用 watch_counts_for_test 查看测试专用计数。

调用图：调用 1 个内部函数（noop）；外部调用 4 个（new, assert_eq!, create_dir, tempdir）。

fn watch_registration_drop_unregisters_paths()

作用：这个测试确认单个注册凭证被丢弃时，对应路径会自动取消监听。注册凭证就像停车票，票没了就不再占车位。

数据流：创建临时目录 → 注册这个目录为递归监听 → 丢弃 registration 对象 → 查看监听计数 → 该路径应该已经没有记录。

调用关系：它验证 WatchRegistration 这类注册对象的 drop 行为。测试用 FileWatcher::noop 避免真实监听，只检查内部登记状态是否清干净。

调用图：调用 1 个内部函数（noop）；外部调用 4 个（new, assert_eq!, create_dir, tempdir）。

fn subscriber_drop_unregisters_paths()

作用：这个测试确认订阅者本身消失时，它注册过的路径也会被清掉。这样某个使用者退出后，不会留下无人需要的监听。

数据流：在一个代码块里创建订阅者并注册路径 → 代码块结束时订阅者被丢弃 → 检查路径监听计数 → 应该已经为空，即使 registration 变量还在外面。

调用关系：它关注订阅者生命周期。FileWatcher::noop 提供测试用监听器，watch_counts_for_test 用来确认订阅者释放时已经触发注销。

调用图：调用 1 个内部函数（noop）；外部调用 4 个（new, assert_eq!, create_dir, tempdir）。

fn missing_path_registers_nearest_existing_parent()

作用：这个测试确认监听一个还不存在的文件时，系统会退一步监听最近存在的父目录。这样文件以后被创建时，监听器还有机会知道。

数据流：创建临时目录，但不创建目标文件 FETCH_HEAD → 注册这个不存在的文件，且非递归 → 内部应该监听临时目录本身，而不是不存在的文件 → 丢弃注册后父目录监听也消失。

调用关系：它验证缺失路径的 fallback，也就是“退到父目录先守着”。这对监听将来才会出现的文件很重要。

调用图：调用 1 个内部函数（noop）；外部调用 3 个（new, assert_eq!, tempdir）。

fn deeply_missing_path_registers_nearest_existing_directory_ancestor()

作用：这个测试确认目标路径缺很多层、而中间某段还是普通文件时，系统会找到最近的真实目录来监听。它不能把普通文件当目录继续往下看。

数据流：创建临时目录，并写入一个名叫 refs 的普通文件 → 请求监听 refs/heads/main 这个不存在的深层路径 → 系统跳过不可用的中间路径，最后监听临时目录，且是非递归。

调用关系：它继续补充 missing_path_registers_nearest_existing_parent 的场景，专门覆盖更复杂的缺失路径。测试用 FileWatcher::noop 和 watch_counts_for_test 观察登记结果。

调用图：调用 1 个内部函数（noop）；外部调用 4 个（new, assert_eq!, write, tempdir）。

async fn receiver_closes_when_subscriber_drops()

作用：这个测试确认订阅者被丢弃后，对应的接收端会收到关闭信号。这样等待消息的人不会永远挂在那里。

数据流：创建监听器、订阅者和接收端 → 丢掉订阅者 → 接收端 recv 应该很快返回 None → 说明这条消息通道已经关闭。

调用关系：它由异步测试运行器执行，用 timeout 防止死等。它验证 add_subscriber 创建出的发送接收关系会随订阅者生命周期正确结束。

调用图：调用 1 个内部函数（noop）；外部调用 4 个（new, from_secs, assert_eq!, timeout）。

fn recursive_registration_downgrades_to_non_recursive_after_drop()

作用：这个测试确认同一路径同时有递归和非递归监听时，递归那份取消后，底层监听会降级成非递归，而不是直接全取消。

数据流：创建真实 FileWatcher 和目录 → 同一路径先注册非递归，再注册递归 → 内部实际监听模式应为递归 → 丢掉递归注册 → 内部模式应变回非递归。

调用关系：它使用 FileWatcher::new 创建真实监听器，并直接查看 inner.watched_paths。它验证多种监听需求叠加时，底层模式能按剩余需求调整。

调用图：调用 1 个内部函数（new）；外部调用 4 个（new, assert_eq!, create_dir, tempdir）。

fn unregister_holds_state_lock_until_unwatch_finishes()

作用：这个测试检查取消监听时的加锁顺序，防止一个线程还没真正取消完，另一个线程就抢先注册造成状态错乱。互斥锁可以理解成一把门锁，一次只让一个人改共享状态。

数据流：创建真实监听器和两个订阅者 → 一个注册递归监听后准备丢弃 → 测试故意抓住内部锁，让注销过程卡住 → 观察状态写锁确实被占住 → 同时另一个线程尝试注册非递归 → 放开内部锁后，两边完成，最终路径应只剩非递归监听。

调用关系：它通过 std::thread::spawn 制造并发场景，验证注销路径没有提前释放关键状态锁。这个测试保护的是很隐蔽的竞态问题，也就是两个线程抢时间导致结果不稳定的问题。

调用图：调用 1 个内部函数（new）；外部调用 5 个（new, assert_eq!, create_dir, spawn, tempdir）。

async fn matching_subscribers_are_notified()

作用：这个测试确认只有路径匹配的订阅者会收到通知。关注 skills 的人不应该收到 plugins 的消息，反过来也一样。

数据流：创建两个订阅者，分别注册 /tmp/skills 和 /tmp/plugins 的递归监听 → 人工发送 /tmp/skills/rust/SKILL.md 的变化 → skills 接收端收到事件 → plugins 接收端在短时间内收不到。

调用关系：它用 FileWatcher::noop 和 send_paths_for_test 模拟变化，再用 ThrottledWatchReceiver::new 接收合并后的通知。它验证事件分发时的订阅匹配规则。

调用图：调用 3 个内部函数（noop, new, path）；外部调用 5 个（new, from_secs, assert_eq!, timeout, vec!）。

async fn non_recursive_watch_ignores_grandchildren()

作用：这个测试确认非递归监听只看指定目录的直接内容，不会看到更深层的孙级路径。这样用户只想看一层时，不会被深层文件刷屏。

数据流：注册 /tmp/skills 为非递归监听 → 人工发送 /tmp/skills/nested/SKILL.md 这个更深层文件的变化 → 接收端在测试时间内不应收到事件。

调用关系：它检查路径匹配规则里的“递归”和“非递归”区别。它调用 path 准备路径，通过 send_paths_for_test 注入事件，用 timeout 验证没有误通知。

调用图：调用 3 个内部函数（noop, new, path）；外部调用 4 个（new, assert_eq!, timeout, vec!）。

async fn ancestor_events_notify_child_watches()

作用：这个测试确认如果监听的是一个具体子文件，而收到的是它上级目录的变化，也能通知到这个监听。因为有些操作系统只报告父目录变了，不一定直接报告文件本身。

数据流：创建 skills/rust/SKILL.md 真实文件 → 注册监听这个文件 → 人工发送 skills 目录变化 → 接收端应该收到 skills 这条事件，说明父级变化能触达子路径监听者。

调用关系：它使用临时目录和真实文件搭场景，再用 FileWatcher::noop 注入测试事件。它补足了操作系统事件粒度不稳定时的兼容行为。

调用图：调用 2 个内部函数（noop, new）；外部调用 8 个（new, from_secs, assert_eq!, create_dir, write, tempdir, timeout, vec!）。

async fn missing_file_watch_reports_requested_path_when_parent_changes()

作用：这个测试确认监听一个原本不存在的文件时，如果父目录变化并且目标文件出现了，通知里应该报告用户真正关心的那个文件路径，而不是只报告父目录。

数据流：注册不存在的 FETCH_HEAD → 先发送同目录下 FETCH_HEAD.lock 的变化，应该不通知 → 创建 FETCH_HEAD 文件 → 发送父目录变化 → 接收端应收到 FETCH_HEAD 这个请求路径。

调用关系：它验证缺失文件 fallback 的精细行为：父目录只是临时看守，目标一旦出现，通知要回到用户申请的路径。

调用图：调用 2 个内部函数（noop, new）；外部调用 7 个（new, from_secs, assert_eq!, write, tempdir, timeout, vec!）。

async fn missing_file_watch_reports_requested_path_when_parent_delete_event_arrives()

作用：这个测试确认缺失文件的监听不只在创建时能通知，在后来删除时也能通知。也就是说目标从无到有、再从有到无，订阅者都能知道。

数据流：注册不存在的 FETCH_HEAD → 创建该文件并发送父目录变化，收到 FETCH_HEAD → 删除该文件并再次发送父目录变化 → 再次收到 FETCH_HEAD。

调用关系：它和 missing_file_watch_reports_requested_path_when_parent_changes 是一组，进一步验证父目录 fallback 能追踪目标文件的存在状态变化。

调用图：调用 2 个内部函数（noop, new）；外部调用 8 个（new, from_secs, assert_eq!, remove_file, write, tempdir, timeout, vec!）。

async fn missing_directory_watch_moves_to_created_directory_for_child_events()

作用：这个测试确认监听一个还不存在的目录时，系统会先监听父目录；等目录被创建后，会把监听位置移到新目录上。这样后续目录里的文件变化也能被看到。

数据流：注册不存在的 skills 目录，先看到实际监听在临时父目录上 → 创建 skills 并发送父目录变化 → 收到 skills 被创建的通知，内部监听转移到 skills → 再创建 skills/SKILL.md 并发送变化 → 接收端收到子文件变化。

调用关系：它验证缺失目录从“借父目录看守”到“目标目录自己接管”的完整流程。这个行为对动态创建目录的项目很关键。

调用图：调用 2 个内部函数（noop, new）；外部调用 8 个（new, from_secs, assert_eq!, create_dir, write, tempdir, timeout, vec!）。

async fn spawn_event_loop_filters_non_mutating_events()

作用：这个测试确认事件循环会过滤掉不改变文件内容的事件，比如只是打开文件。否则程序可能因为普通读取操作而反复触发刷新。

数据流：创建监听器和订阅者，注册 /tmp/skills 递归监听 → 启动测试用事件循环 → 发送一个 Access/Open 事件，接收端不应收到 → 再发送 Create/File 事件，接收端应收到对应路径。

调用关系：它调用 notify_event 制造原始事件，调用 spawn_event_loop_for_test 把事件喂给监听器。它把 is_mutating_event 的过滤规则放到真实事件循环路径里验证。

调用图：调用 4 个内部函数（noop, new, notify_event, path）；外部调用 9 个（Open, new, from_secs, Access, Create, assert_eq!, unbounded_channel, timeout, vec!）。

async fn dropping_live_watcher_releases_inner_watcher()

作用：这个测试确认真实 FileWatcher 被丢弃后，内部监听器也能释放。这样程序关闭或重建监听器时，不会留下后台资源。

数据流：创建真实 FileWatcher → 对内部对象做一个弱引用，弱引用不会阻止对象释放 → 丢掉 FileWatcher → 弱引用无法再升级，说明内部对象已经释放。

调用关系：它验证 FileWatcher::new 创建的真实监听器在生命周期结束时会干净收尾。这个测试关注资源释放，而不是事件通知。

调用图：调用 1 个内部函数（new）；外部调用 2 个（downgrade, assert_eq!）。

async fn small_hook_output_remains_inline() -> Result<()>

作用：这个测试确认：很短的钩子输出不应该被写进额外文件，而是原样返回。这样能保证普通短消息不会被复杂化，用户直接看到内容就行。

数据流：进去的是一个临时目录、一个新的线程编号，以及文本 "short"。测试把临时目录转换成程序使用的绝对路径，拼出钩子输出目录，再让 HookOutputSpiller 处理这段短文本。出来的结果应该仍然是 "short"，并且磁盘上不应该出现专门保存钩子输出的目录；测试用断言检查这两点。

调用关系：它由 Tokio 的异步测试框架在跑测试时调用。它会用 tempdir 创建安全的临时目录，用 from_absolute_path 把系统路径变成项目自己的路径类型，用 new 创建线程编号，然后调用被测对象的 maybe_spill_text。最后通过 assert_eq! 和 assert! 判断“短输出保持原样”这条规则有没有被破坏。

调用图：调用 2 个内部函数（new, from_absolute_path）；外部调用 3 个（assert!, assert_eq!, tempdir）。

async fn large_hook_output_spills_to_file() -> Result<()>

作用：这个测试确认：很长的钩子输出会被“溢出”保存到文件里，返回内容只保留提示信息。这样既不会丢数据，也不会把主输出撑得很长。

数据流：进去的是一个临时目录、一大段由 "hook output " 重复 1000 次组成的文本，以及一个新的线程编号。测试让 HookOutputSpiller 处理这段长文本；返回结果应该包含“tokens truncated”这类截断提示，还应该有一行写着完整输出保存到哪个路径。测试从返回文字里取出这个路径，再从磁盘读取文件内容，确认读出来的内容和最初那段长文本完全一样。

调用关系：它同样由 Tokio 的异步测试框架运行。它先用 tempdir 准备隔离环境，用 from_absolute_path 生成输出目录路径，用 new 创建线程编号，然后把核心检查交给 maybe_spill_text。之后它靠 assert! 检查返回文字像不像“截断后的提示”，靠 assert_eq! 检查落盘文件是否真的保存了完整原文；如果找不到保存路径，会用 anyhow 的 Context 给错误补一句更容易理解的说明。

调用图：调用 2 个内部函数（new, from_absolute_path）；外部调用 3 个（assert!, assert_eq!, tempdir）。

fn searches_only_new_bytes_after_partial_line()

作用：这个测试确认 LineBuffer 在遇到半行数据时，会记住已经看过的位置；后续追加新字节后，只需要检查新增部分。有人改 LineBuffer 时，可以靠它发现“漏掉换行”或“重复扫描旧数据”这类问题。

数据流：一开始创建一个空的 LineBuffer。它先放入“partial”，尝试取一行，结果应该没有完整行，并留下这些字节和已扫描长度；接着追加“ line”，仍然取不到完整行；最后追加“\nnext”，这次取出“partial line\n”作为完整行，同时把剩下的“next”留在缓冲区里，并把已扫描长度重置为 0。

调用关系：它是测试框架运行时自动执行的测试函数。它先通过默认构造创建 LineBuffer，然后多次喂入字节、调用 LineBuffer 的取行能力，并用 assert_eq! 对比实际状态和预期状态，证明 LineBuffer 在分段输入下行为正确。

调用图：外部调用 2 个（assert_eq!, default）。

fn new() -> Self

作用：创建一个干净的假环境，里面没有任何环境变量，tmux 信息也是默认空值。测试用它作为起点，再按需要一点点加条件。

数据流：进去不需要任何参数 → 它新建一个空的字符串表，用来放环境变量，并准备默认的 tmux 信息和空的 Zellij 版本 → 出来一个 FakeEnvironment，后续测试可以继续往里面塞变量。

调用关系：几乎所有测试都会先调用它，像先拿一张白纸，再用 with_var、with_tmux_client_info 或 with_zellij_version 写上本次测试需要的线索。它内部用到标准库的新建表和默认值能力。

调用图：被 21 处调用（detects_alacritty, detects_apple_terminal, detects_ghostty, detects_gnome_terminal, detects_iterm2, detects_kitty, detects_konsole, detects_term_fallbacks, detects_term_program, detects_tmux_client_termname (+11 more)）；外部调用 2 个（new, default）。

fn with_var(mut self, key: &str, value: &str) -> Self

作用：给假环境加一个环境变量。测试用它模拟真实系统里 TERM_PROGRAM、TERM、TMUX 这类变量的值。

数据流：进去一个已有的假环境、变量名和值 → 它把这对名字和值存进假环境的表里 → 出来同一个假环境的更新版，方便继续链式添加更多变量。

调用关系：它通常接在 FakeEnvironment::new 后面，被各个检测测试用来搭建场景。识别代码之后会通过 FakeEnvironment::var 读到这些值。

fn with_tmux_client_info(mut self, termtype: Option<&str>, termname: Option<&str>) -> Self

作用：给假环境设置 tmux 客户端看到的终端信息。tmux 是终端复用器，简单说像一个“终端里的多窗口外壳”，它可能遮住真正终端的身份，所以要单独模拟。

数据流：进去一个假环境，以及可选的 termtype 和 termname → 它把这些值转成字符串，放进 tmux_client_info 字段 → 出来带有 tmux 客户端信息的假环境。

调用关系：tmux 相关测试会在 FakeEnvironment::new 后调用它。识别代码需要 tmux 信息时，会通过 FakeEnvironment::tmux_client_info 拿到这里设置的数据。

fn with_zellij_version(mut self, version: &str) -> Self

作用：给假环境设置通过命令探测到的 Zellij 版本。Zellij 也是终端复用器，测试要确认识别代码能拿到它的版本。

数据流：进去一个假环境和版本字符串 → 它把版本保存到 zellij_version 字段里 → 出来带有这个 Zellij 版本的假环境。

调用关系：Zellij 命令版本相关测试会用它。之后 FakeEnvironment::zellij_version 会优先把这个版本交给被测的识别流程。

fn var(&self, name: &str) -> Option<String>

作用：让被测代码像读取真实环境变量一样，从假环境里取值。这样测试不用真的改电脑上的环境变量。

数据流：进去一个变量名 → 它在假环境的变量表里查找 → 找到就返回这个值的拷贝，找不到就返回空。

调用关系：这是 FakeEnvironment 实现 Environment 接口的一部分。终端识别代码在测试中读取环境变量时，实际会走到这里。

fn tmux_client_info(&self) -> TmuxClientInfo

作用：把测试预先设置好的 tmux 客户端信息交给被测代码。这样可以模拟“人在 tmux 里面，但真正外层终端是什么”的情况。

数据流：进去不需要额外参数，只读取假环境自身保存的 tmux_client_info → 它复制一份信息 → 返回给调用方，原数据不被改动。

调用关系：这是 FakeEnvironment 实现 Environment 接口的一部分。tmux 识别场景中，被测代码会向它要客户端信息；这些信息通常来自 with_tmux_client_info。

调用图：外部调用 1 个（clone）。

fn zellij_version(&self) -> Option<String>

作用：把 Zellij 的版本交给被测代码。它既支持测试直接设置的版本，也支持从 ZELLIJ_VERSION 环境变量里读版本。

数据流：进去不需要额外参数 → 它先看 zellij_version 字段有没有值；没有的话，再尝试读取非空的 ZELLIJ_VERSION 环境变量 → 返回找到的版本，或者返回空。

调用关系：这是 FakeEnvironment 实现 Environment 接口的一部分。Zellij 相关测试会用它验证两种来源：命令探测结果和环境变量。

fn terminal_info(
    name: TerminalName,
    term_program: Option<&str>,
    version: Option<&str>,
    term: Option<&str>,
    multiplexer: Option<Multiplexer>,
) -> TerminalInfo

作用：这是测试里的小帮手，用更短的写法创建预期的 TerminalInfo。TerminalInfo 可以理解为“识别结果卡片”，记录终端名字、版本、TERM 值和是否套了 tmux/Zellij。

数据流：进去终端名称，以及若干可选字符串和复用器信息 → 它把可选字符串转成真正拥有的字符串值 → 出来一个完整的 TerminalInfo，用来和实际识别结果比较。

调用关系：很多测试用它减少重复代码。terminal_info_reports_is_zellij 明确调用它来构造 Zellij 和非 Zellij 的样例，其它测试也用它写出期望结果。

调用图：被 1 处调用（terminal_info_reports_is_zellij）。

fn detects_term_program()

作用：检查 TERM_PROGRAM 这条线索是否会被优先使用，并且版本号为空时不会被误当成有效版本。TERM_PROGRAM 是很多终端会设置的“我是谁”标记。

数据流：进去是测试自己搭出的几组假环境 → 每组环境都放入不同的 TERM_PROGRAM、TERM_PROGRAM_VERSION 或 WEZTERM_VERSION → 它调用识别流程并断言结果卡片和 user agent 字符串都符合预期。

调用关系：它从 FakeEnvironment::new 开始搭环境，用断言宏比较结果。这个测试守住一个关键规则：明确的 TERM_PROGRAM 比其它旁路线索更有优先级。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn terminal_info_reports_is_zellij()

作用：检查 TerminalInfo 的 is_zellij 判断是否只在复用器是 Zellij 时返回真。也就是说，它确认“是不是 Zellij”不会和 tmux 混淆。

数据流：进去是测试构造的两个识别结果：一个带 Zellij，一个带 tmux → 它分别调用 is_zellij → 断言前者是真，后者是假。

调用关系：它调用 terminal_info 来造样例，再用断言确认行为。它不测试环境变量，而是直接测试结果对象自己的判断方法。

调用图：调用 1 个内部函数（terminal_info）；外部调用 1 个（assert!）。

fn detects_iterm2()

作用：检查只靠 ITERM_SESSION_ID 也能认出 iTerm2。iTerm2 是 macOS 上常见的终端应用。

数据流：进去一个带 ITERM_SESSION_ID 的假环境 → 识别流程读取这个线索 → 出来应是 Iterm2，并生成 iTerm.app 这个 user agent 字符串。

调用关系：它用 FakeEnvironment::new 搭场景，再用断言检查结果。它覆盖的是没有 TERM_PROGRAM 时的 iTerm2 备用识别方式。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_apple_terminal()

作用：检查 Apple Terminal，也就是 macOS 自带终端，能通过不同线索被识别出来。

数据流：进去两种假环境：一种有 TERM_PROGRAM=Apple_Terminal，另一种有 TERM_SESSION_ID → 识别流程分别判断 → 输出都应指向 AppleTerminal，并给出正确的 user agent。

调用关系：它从 FakeEnvironment::new 创建两个场景，用断言宏分别核对。它保证主线索和备用线索都能识别 macOS 自带终端。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_ghostty()

作用：检查 Ghostty 终端能通过 TERM_PROGRAM 被识别。Ghostty 是一种终端应用名。

数据流：进去一个 TERM_PROGRAM=Ghostty 的假环境 → 识别流程读到这个名字 → 返回 Ghostty 识别结果，并生成 Ghostty 字符串。

调用关系：它用 FakeEnvironment::new 和 with_var 搭环境，再用断言确认。它覆盖 Ghostty 的基础识别规则。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_vscode()

作用：检查 VS Code 内置终端能被识别，并且版本号能带进结果。VS Code 是代码编辑器，它里面也有终端窗口。

数据流：进去一个带 TERM_PROGRAM=vscode 和版本号的假环境 → 识别流程读取名称和版本 → 返回 VsCode，并生成 vscode/版本号 这样的 user agent。

调用关系：它用 FakeEnvironment::new 建场景，用断言比较结果。它验证 TERM_PROGRAM 与 TERM_PROGRAM_VERSION 搭配时的正常路径。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_warp_terminal()

作用：检查 WarpTerminal 能被识别，并且较长的版本字符串不会被弄丢。Warp 是一种现代终端应用。

数据流：进去一个带 WarpTerminal 名称和完整版本号的假环境 → 识别流程保存这些信息 → 输出 WarpTerminal 结果和带版本的 user agent。

调用关系：它通过 FakeEnvironment::new 搭出 Warp 场景，再用断言核对。它保证特殊格式的版本号也能原样保留。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_tmux_multiplexer()

作用：检查在 tmux 里面运行时，识别结果会标出“套了一层 tmux”，并尽量使用 tmux 客户端提供的真实终端信息。

数据流：进去一个带 TMUX、TERM_PROGRAM=tmux，以及 tmux 客户端 termtype/termname 的假环境 → 识别流程判断当前在 tmux 中，并读取客户端信息 → 输出带 Tmux 标记的 TerminalInfo。

调用关系：它用 FakeEnvironment::new 搭环境，并借助 with_tmux_client_info 设置 tmux 看到的外层信息。它测试的是复用器场景，不是普通终端场景。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_zellij_multiplexer()

作用：检查只要有 ZELLIJ 标记，就能知道当前运行在 Zellij 复用器里。Zellij 类似 tmux，也是一个终端里的工作区工具。

数据流：进去一个带 ZELLIJ=1 的假环境 → 识别流程看到这个标记 → 输出 Unknown 终端名，但 multiplexer 字段标为 Zellij。

调用关系：它用 FakeEnvironment::new 创建最小 Zellij 场景，用断言确认复用器字段。它验证“知道套了 Zellij”这件事本身。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_zellij_multiplexer_version()

作用：检查 ZELLIJ_VERSION 环境变量里的版本号能被识别出来。版本号有助于后续按能力或兼容性做判断。

数据流：进去一个带 ZELLIJ_VERSION=0.43.1 的假环境 → 识别流程读取这个版本 → 输出带 Zellij 标记和对应版本号的结果。

调用关系：它用 FakeEnvironment::new 和 with_var 设置环境变量。识别流程会通过 FakeEnvironment::zellij_version 这条接口拿到版本。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_zellij_multiplexer_command_version()

作用：检查通过“命令探测”得到的 Zellij 版本也能进入识别结果。这里用假环境直接模拟命令返回值，不真的运行命令。

数据流：进去一个带 ZELLIJ 标记、并通过 with_zellij_version 设置版本的假环境 → 识别流程优先拿到这个版本 → 输出 Zellij 复用器和 0.44.1 版本。

调用关系：它用 FakeEnvironment::new 后接 with_zellij_version 搭场景。它和读取 ZELLIJ_VERSION 的测试互补，覆盖另一条版本来源。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn parses_zellij_version_output()

作用：检查 Zellij 版本输出文本能被正确拆出版本号。比如命令可能输出“zellij 0.44.1”，代码需要拿到后面的“0.44.1”。

数据流：进去几段示例文本：带命令名前缀、只有版本号、以及空字符串 → 解析函数处理这些文本 → 输出版本字符串或空值，并由断言确认。

调用关系：它直接测试 parse_zellij_version 这个解析小函数，不需要 FakeEnvironment。它守住的是 Zellij 版本文本格式的边界情况。

调用图：外部调用 1 个（assert_eq!）。

fn detects_tmux_client_termtype()

作用：检查 tmux 客户端的 termtype 可以帮助识别真正的外层终端。这里模拟 tmux 说外层是 WezTerm。

数据流：进去一个带 TMUX 和 TERM_PROGRAM=tmux 的假环境，并设置 tmux_client_info.termtype=WezTerm → 识别流程读取客户端 termtype → 输出 WezTerm，同时标记仍在 tmux 中。

调用关系：它用 FakeEnvironment::new 建 tmux 场景，用 with_tmux_client_info 填客户端信息，再断言结果。它验证 tmux 内部识别时 termtype 的优先作用。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_tmux_client_termname()

作用：检查 tmux 客户端只有 termname 时，识别结果至少能保留 TERM 风格的名字。termname 可以理解为终端能力名称，比如 xterm-256color。

数据流：进去一个 tmux 假环境，termtype 为空，termname=xterm-256color → 识别流程拿不到具体终端品牌，但能记录 termname → 输出 Unknown 终端名、term 字段为 xterm-256color，并标记 tmux。

调用关系：它通过 FakeEnvironment::new 和 with_tmux_client_info 创建缺少 termtype 的场景。它补上 tmux 信息不完整时的 fallback，也就是退一步保留可用信息。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_tmux_term_program_uses_client_termtype()

作用：检查在 tmux 中，即使 TERM_PROGRAM 写的是 tmux，也应该用客户端 termtype 识别真正终端，并保留 tmux 自己的版本。这样不会把外层 Ghostty 错认成 tmux 本身。

数据流：进去一个带 TMUX、TERM_PROGRAM=tmux、TERM_PROGRAM_VERSION=3.6a，并且 tmux 客户端 termtype 为 ghostty 1.2.3 的假环境 → 识别流程把 tmux 当复用器，把 ghostty 当真实终端 → 输出 Ghostty、版本 1.2.3、termname，以及 tmux 版本 3.6a。

调用关系：它用 FakeEnvironment::new 和 with_tmux_client_info 搭复杂 tmux 场景，再用断言验证优先级。它是 tmux 相关测试里最关键的组合场景之一。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_wezterm()

作用：检查 WezTerm 能通过多种线索识别，包括 WEZTERM_VERSION、TERM_PROGRAM、TERM=wezterm 和 TERM=wezterm-mux。WezTerm 的标记来源比较多，所以这里一次覆盖多条路。

数据流：进去多组假环境，有的给版本变量，有的给 TERM_PROGRAM，有的只给 TERM → 识别流程按规则判断并保存版本或 TERM 值 → 每组都输出对应的 WezTerm 结果和 user agent。

调用关系：它多次从 FakeEnvironment::new 开始搭不同场景，并用断言逐个检查。它也验证空的 WEZTERM_VERSION 只表示有 WezTerm 线索，不表示有版本号。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_kitty()

作用：检查 Kitty 终端能通过窗口编号、TERM_PROGRAM 或 TERM=xterm-kitty 被识别。Kitty 是一种终端应用。

数据流：进去多组假环境：KITTY_WINDOW_ID、TERM_PROGRAM=kitty，以及 TERM=xterm-kitty 加上另一个终端的干扰变量 → 识别流程分别判断 → 输出 Kitty，并确认 Kitty 的 TERM 线索能压过 Alacritty 的干扰线索。

调用关系：它用 FakeEnvironment::new 创建多个 Kitty 场景，再用断言核对。它特别测试了优先级，避免同时出现多个线索时认错终端。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_alacritty()

作用：检查 Alacritty 能通过 socket、TERM_PROGRAM 或 TERM=alacritty 被识别。Alacritty 是一种常见终端应用。

数据流：进去三组假环境，分别带 ALACRITTY_SOCKET、TERM_PROGRAM=Alacritty 加版本、或 TERM=alacritty → 识别流程读这些线索 → 输出 Alacritty，并在有版本时带上版本号。

调用关系：它用 FakeEnvironment::new 分别搭三种现实场景。它和 Kitty 测试一起保证相近或冲突线索下的识别顺序合理。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_konsole()

作用：检查 KDE 的 Konsole 终端能被识别，并正确处理有版本、通过 TERM_PROGRAM 给版本、以及版本为空的情况。

数据流：进去三组假环境：KONSOLE_VERSION 有值、TERM_PROGRAM=Konsole 加版本、KONSOLE_VERSION 为空 → 识别流程读取线索 → 输出 Konsole，有版本时带版本，空版本时不填版本。

调用关系：它用 FakeEnvironment::new 创建 Konsole 的几种常见环境。它验证版本字段既不会丢，也不会把空字符串误当版本。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_gnome_terminal()

作用：检查 GNOME Terminal 能通过 GNOME_TERMINAL_SCREEN 或 TERM_PROGRAM 被识别。GNOME Terminal 是 Linux 桌面环境里常见的终端。

数据流：进去两组假环境：一种只有 GNOME_TERMINAL_SCREEN，另一种有 TERM_PROGRAM=gnome-terminal 和版本 → 识别流程判断终端类型 → 输出 GnomeTerminal，并在第二种情况下带版本。

调用关系：它从 FakeEnvironment::new 开始搭两种场景，用断言确认。它覆盖 GNOME Terminal 的专用变量和通用 TERM_PROGRAM 两条路径。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_vte()

作用：检查基于 VTE 的终端能被识别。VTE 是一套终端控件，很多 Linux 终端应用会用它；这里把它作为一种可识别来源。

数据流：进去三组假环境：VTE_VERSION 有值、TERM_PROGRAM=VTE 加版本、VTE_VERSION 为空 → 识别流程读取线索 → 输出 Vte，有版本时 user agent 带版本，空版本时只写 VTE。

调用关系：它用 FakeEnvironment::new 搭 VTE 相关场景，并通过断言锁定行为。它保证 VTE 版本的处理方式和其它终端一致。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_windows_terminal()

作用：检查 Windows Terminal 能通过 WT_SESSION 或 TERM_PROGRAM 被识别。Windows Terminal 是 Windows 上的现代终端应用。

数据流：进去两组假环境：一种有 WT_SESSION，另一种有 TERM_PROGRAM=WindowsTerminal 和版本 → 识别流程判断 → 输出 WindowsTerminal，并在有版本时生成带版本的 user agent。

调用关系：它用 FakeEnvironment::new 建两个 Windows Terminal 场景。它覆盖 Windows 专用变量和通用 TERM_PROGRAM 两种入口。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn detects_term_fallbacks()

作用：检查所有更具体线索都没有时，代码会退回看 TERM；如果连 TERM 都没有，就返回 unknown。TERM 是传统终端类型变量，像最后兜底的标签。

数据流：进去三组假环境：TERM=xterm-256color、TERM=dumb、以及完全空环境 → 识别流程在缺少其它线索时使用 TERM 或默认值 → 输出 Unknown 加 TERM、Dumb 加 TERM，或 Unknown 且 user agent 为 unknown。

调用关系：它用 FakeEnvironment::new 创建兜底场景，用断言确认。它处在整套测试的最后防线位置，保证没有明确识别结果时也有稳定、可预期的输出。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn split_string_works()

作用：这个测试检查最基本的拆字符串行为：给一段普通英文，要求保留前面几个字节和后面几个字节，中间被删掉的部分数量要算对。

数据流：进去的是字符串“hello world”和两个预算：开头保留 5 个字节、结尾保留 5 个字节。测试调用被测的拆分逻辑后，拿结果和期望值比较：中间删掉 1 个字符，留下“hello”和“world”。它还检查预算都为 0 时，“abc”会被全部视为删掉，头尾都为空。

调用关系：这是最基础的用例，像先确认剪刀能正常剪纸。它通过 assert_eq! 检查结果是否完全一致；如果这个测试失败，说明后面更复杂的截断测试也很可能不可靠。

调用图：外部调用 1 个（assert_eq!）。

fn split_string_handles_empty_string()

作用：这个测试确认空字符串不会让拆分逻辑出错。空输入应该安静地返回空结果，而不是报错或算出奇怪的删除数量。

数据流：进去的是空字符串，以及开头、结尾各 4 个字节的预算。因为原文什么都没有，所以测试期望删除数量是 0，保留的开头和结尾也都是空字符串。

调用关系：它覆盖的是边界情况，也就是最容易被忽略的小角落。测试用 assert_eq! 把实际输出和期望输出对齐，防止未来改动时把空输入处理坏。

调用图：外部调用 1 个（assert_eq!）。

fn split_string_only_keeps_prefix_when_tail_budget_is_zero()

作用：这个测试检查一种特殊预算：只允许保留开头，不允许保留结尾。它确保函数不会偷偷从尾部留下内容。

数据流：进去的是“abcdef”，开头预算是 3，结尾预算是 0。测试期望结果是删掉中间或剩余的 3 个字符，只留下开头“abc”，结尾为空。

调用关系：它专门盯住“尾部预算为零”这个分支。通过 assert_eq! 判断结果，帮助保证调用者在只想看开头摘要时不会得到多余尾巴。

调用图：外部调用 1 个（assert_eq!）。

fn split_string_only_keeps_suffix_when_prefix_budget_is_zero()

作用：这个测试和上一个相反：只允许保留结尾，不允许保留开头。它确认函数能正确做“只看尾部”的截取。

数据流：进去的是“abcdef”，开头预算是 0，结尾预算是 3。测试期望删掉前面的 3 个字符，开头为空，结尾保留“def”。

调用关系：它覆盖“开头预算为零”的情况。这个测试用 assert_eq! 守住行为，避免以后改代码时把前缀和后缀预算混在一起。

调用图：外部调用 1 个（assert_eq!）。

fn split_string_handles_overlapping_budgets_without_removal()

作用：这个测试检查当开头预算和结尾预算加起来超过原字符串长度时，函数不会错误地说中间删了东西。

数据流：进去的是“abcdef”，开头预算 4，结尾预算 4。因为总预算已经足够覆盖整个字符串，测试期望删除数量是 0，结果保留“abcd”和“ef”，没有凭空制造被删除内容。

调用关系：它验证的是预算重叠时的安全行为。assert_eq! 在这里像一把尺子，确认函数面对“预算太宽松”的情况不会乱算。

调用图：外部调用 1 个（assert_eq!）。

fn split_string_respects_utf8_boundaries()

作用：这个测试确认拆字符串时不会把 UTF-8 字符切成半个。UTF-8 是常见文字编码，emoji、中文等字符可能占多个字节，随便按字节切会切坏。

数据流：进去的是包含 emoji 的字符串，以及不同的字节预算。测试检查函数会自动避开字符边界：预算不够放下完整 emoji 时就不保留；预算够时才保留完整 emoji。出来的结果必须是合法、完整、可显示的字符串片段。

调用关系：这是这个测试文件里最重要的安全检查之一。它通过多组 assert_eq! 确认底层拆分逻辑不会产生坏字符串；这对日志、界面显示、模型输出截断都很关键。

调用图：外部调用 1 个（assert_eq!）。

fn truncate_with_token_budget_returns_original_when_under_limit()

作用：这个测试检查：如果字符串本来就短，没有超过 token 预算，就应该原样返回。token 可以粗略理解为文本被系统计数时用的小块，不完全等于字符。

数据流：进去的是“short output”和很大的限制 100。测试调用 truncate_middle_with_token_budget 后，期望出来的文本还是原文，并且“原始 token 数”这一项是 None，意思是没有发生截断，不需要报告原始长度。

调用关系：它直接测试 truncate_middle_with_token_budget，并用 assert_eq! 检查两个结果：输出文本和是否截断。它保证正常短文本不会被多此一举地加上截断提示。

调用图：外部调用 2 个（assert_eq!, truncate_middle_with_token_budget）。

fn truncate_with_token_budget_reports_truncation_at_zero_limit()

作用：这个测试检查极端情况：token 限制是 0 时，函数仍然要给出清楚的截断提示，而不是返回混乱内容。

数据流：进去的是“abcdef”和最大 token 数 0。函数没有预算保留正文，所以输出应变成“……有 2 个 token 被截断……”这样的提示，并返回 Some(2)，表示原文大约有 2 个 token。

调用关系：它测试 truncate_middle_with_token_budget 在最严限制下的行为，并用 assert_eq! 固定住提示格式和返回信息。这样调用者即使不给文本空间，也能知道内容确实被省略了。

调用图：外部调用 2 个（assert_eq!, truncate_middle_with_token_budget）。

fn truncate_middle_tokens_handles_utf8_content()

作用：这个测试确认按 token 预算截断时，包含 emoji 和换行的文本也能被正确处理。重点是既要控制长度，又不能把多字节字符切坏。

数据流：进去的是一段包含很多 emoji、换行和英文的长字符串，以及 token 限制 8。函数会保留开头和结尾，中间放入“8 tokens truncated”的提示；同时返回 Some(16)，说明原文的 token 数量。测试检查最终字符串和 token 数都符合预期。

调用关系：它直接调用 truncate_middle_with_token_budget，再用 assert_eq! 检查结果。这个测试把 token 截断、UTF-8 安全、跨行文本这几件事放在一起验证，接近真实使用场景。

调用图：外部调用 2 个（assert_eq!, truncate_middle_with_token_budget）。

fn truncate_middle_bytes_handles_utf8_content()

作用：这个测试检查另一种截断方式：按字节上限截断字符串中间。它确认即使限制是字节数，结果也不会破坏 emoji 这类 UTF-8 字符。

数据流：进去的是包含 emoji、换行和英文的长字符串，以及最大字节数 20。truncate_middle_chars 会保留一部分开头和结尾，中间插入“21 chars truncated”的提示。测试期望最终结果是完整可读的字符串，而不是半个 emoji 或乱码。

调用关系：它直接测试 truncate_middle_chars，并用 assert_eq! 验证输出。它和 token 预算测试互相补充：一个看 token 限制，一个看字节限制，共同保证截断工具在不同入口下都安全。

调用图：外部调用 2 个（assert_eq!, truncate_middle_chars）。

fn image_bytes(image: &ImageBuffer<Rgba<u8>, Vec<u8>>, format: ImageFormat) -> Vec<u8>

作用：把测试里临时造出来的一张 RGBA 图片，编码成指定格式的原始字节。别人用它来快速得到一份像真实文件一样的 PNG、WebP、GIF 等图片数据。

数据流：进去的是一张内存里的图片和目标格式；它先开一个内存写入器，把图片克隆成可编码的动态图片，再按指定格式写进去；出来的是一串图片文件字节，后面的测试会把它当作真实上传或读取到的图片。

调用关系：它是很多测试的“造图工具”。小图保留、大图缩放、竖图缩放、原图模式、data URL、缓存更新和自定义限制这些测试都会先调用它生成输入图片，再把结果交给图片处理流程检查。

调用图：调用 1 个内部函数（new）；被 8 处调用（data_url_processing_converts_gif_to_png, data_url_processing_preserves_supported_source_bytes, downscales_large_image, downscales_tall_image_to_fit_square_bounds, preserves_large_image_in_original_mode, reprocesses_updated_file_contents, resize_with_limits_respects_dimension_and_patch_budgets, returns_original_image_when_within_bounds）；外部调用 3 个（ImageRgba8, clone, new）。

fn image_bytes_with_metadata(
    image: &ImageBuffer<Rgba<u8>, Vec<u8>>,
    format: ImageFormat,
    icc_profile: &[u8],
) -> Vec<u8>

作用：生成带有元数据的测试图片字节。这里的元数据包括 ICC 色彩配置（告诉软件颜色该怎么解释）和 EXIF 信息（照片附带的方向等说明）。

数据流：进去的是一张图片、目标格式和一段 ICC 配置；它按 PNG、JPEG 或 WebP 分别选择对应编码器，把 ICC 配置和固定的“旋转 90 度”EXIF 信息写进去，再写入图片像素；出来的是一份带元数据的图片字节。

调用关系：它只服务于元数据相关测试。保留 RGB 元数据的测试和丢弃非 RGB ICC 的测试会用它造出特殊图片，然后再让图片处理代码缩放并检查这些附带信息是否按规则留下或移除。

调用图：被 2 处调用（resizing_drops_non_rgb_icc_profile, resizing_preserves_supported_metadata）；外部调用 10 个（ImageRgba8, as_raw, clone, height, width, new_with_quality, new, new, new_lossless, panic!）。

async fn returns_original_image_when_within_bounds()

作用：确认图片本来就足够小时，处理流程不会多此一举地重新压缩或改动它。这样可以避免画质损失，也节省时间。

数据流：它造出 64×32 的 PNG 和 WebP 小图，转成原始字节后送进提示词图片加载流程；处理后检查宽高、媒体类型和输出字节；结果必须和输入完全一样。

调用关系：这个测试先借助 image_bytes 造图，再调用被测的图片加载处理函数。它站在最基础入口处，确保“没超限就原样返回”这条规则没有被破坏。

调用图：调用 1 个内部函数（image_bytes）；外部调用 4 个（from_pixel, new, assert_eq!, Rgba）。

async fn downscales_large_image()

作用：确认很大的图片会被自动缩小到允许范围内。这样可以防止把过大的图片塞进模型或后续流程，浪费内存和计算量。

数据流：它造出 4096×2048 的大图，编码成 PNG 和 WebP 后交给处理流程；处理流程返回缩小后的图片；测试检查宽高没有超过最大限制、格式没变，并且输出字节真的还能被图片库读回来。

调用关系：它通过 image_bytes 准备大图输入，然后检查被测缩放逻辑的结果。它还调用格式猜测和内存读图功能，像验货一样确认输出不是一串看似正确但实际打不开的数据。

调用图：调用 1 个内部函数（image_bytes）；外部调用 7 个（from_pixel, new, assert!, assert_eq!, Rgba, guess_format, load_from_memory）。

async fn downscales_tall_image_to_fit_square_bounds()

作用：确认特别高的竖图也会按比例缩小，而不是只顾宽度或把图片压扁。这个测试防止长图在缩放时比例出错。

数据流：它造出 1024×4096 的竖向 PNG，送进自动适配大小的处理模式；处理后检查输出变成 512×最大高度，并且仍然是 PNG；结果说明图片比例被正确保留。

调用关系：它使用 image_bytes 生成输入，再调用图片处理流程。它补充覆盖了横向大图之外的另一种常见情况：竖图如何塞进方形边界。

调用图：调用 1 个内部函数（image_bytes）；外部调用 4 个（from_pixel, new, assert_eq!, Rgba）。

async fn resizing_preserves_supported_metadata()

作用：确认图片缩放以后，支持的附带信息不会丢。比如色彩配置和拍摄方向信息，丢了可能导致颜色不准或方向解释不对。

数据流：它分别造出带 RGB ICC 配置和 EXIF 旋转信息的 PNG、JPEG、WebP 大图；处理流程会把宽度缩到限制内；然后测试重新用解码器读取输出，检查尺寸、方向、ICC 配置和 EXIF 数据都还在。

调用关系：它依赖 image_bytes_with_metadata 造出带“说明书”的图片，再用图片解码器验收处理结果。它验证的是缩放流程和元数据复制逻辑之间能否配合好。

调用图：调用 2 个内部函数（new, image_bytes_with_metadata）；外部调用 5 个（from_pixel, with_format, new, assert_eq!, Rgba）。

async fn resizing_drops_non_rgb_icc_profile()

作用：确认遇到非 RGB 的 ICC 色彩配置时，处理流程会主动丢掉它。这样做是为了避免把不适合当前输出图片的色彩说明继续带下去，导致显示或解码问题。

数据流：它造出一张带 CMYK ICC 配置的 JPEG 图，同时带 EXIF 方向信息；处理后重新解码输出；结果应该是 ICC 配置为空，但 EXIF 信息仍然保留。

调用关系：它也使用 image_bytes_with_metadata 准备特殊输入。和保留元数据的测试不同，它专门检查“该丢的要丢、该留的要留”这条更细的规则。

调用图：调用 2 个内部函数（new, image_bytes_with_metadata）；外部调用 5 个（from_pixel, with_format, new, assert_eq!, Rgba）。

async fn preserves_large_image_in_original_mode()

作用：确认在“原图模式”下，即使图片很大，也不能被自动缩小。这个模式的意义就是尊重调用者要原始图片的选择。

数据流：它造出 4096×2048 的大 PNG，并保存原始字节；以 Original 模式交给处理流程；输出应保持原宽高、PNG 类型和完全相同的字节。

调用关系：它先用 image_bytes 造大图，再用不同于普通缩放的模式调用图片处理入口。它和 downscales_large_image 形成对照：同样的大图，模式不同，结果就应该不同。

调用图：调用 1 个内部函数（image_bytes）；外部调用 4 个（from_pixel, new, assert_eq!, Rgba）。

async fn data_url_processing_preserves_supported_source_bytes()

作用：确认 data URL 形式的小 PNG 图片能被正确识别，而且大小合格时不会被改动。它还检查 data URL 里的大小写变化不会影响识别。

数据流：它造出一张小 PNG，把图片字节包装成 data URL，并故意把 data 和 base64 的字母大小写改掉；处理流程解析 URL、解码图片；输出应保持原尺寸、PNG 类型和原始字节。

调用关系：它用 image_bytes 准备图片内容，再走 data URL 的处理入口。它验证的是文本形式图片输入到普通图片处理之间的衔接是否可靠。

调用图：调用 1 个内部函数（image_bytes）；外部调用 3 个（from_pixel, assert_eq!, Rgba）。

async fn data_url_processing_converts_gif_to_png()

作用：确认 GIF 格式通过 data URL 输入时，会被转换成 PNG。这样后续流程可以拿到更统一、更容易处理的图片格式。

数据流：它造出一张 GIF 图片字节，包装成 image/gif 的 data URL；处理流程解析并转换；输出的媒体类型应是 image/png，实际字节也应被识别为 PNG。

调用关系：它借助 image_bytes 生成 GIF 输入，然后检查 data URL 处理入口是否把不适合直接保留的格式交给转换逻辑处理。

调用图：调用 1 个内部函数（image_bytes）；外部调用 3 个（from_pixel, assert_eq!, Rgba）。

fn data_url_processing_rejects_malformed_input()

作用：确认坏掉的 data URL 会被明确拒绝，而不是被误当成图片继续处理。这样可以避免用户输入格式错误时出现奇怪的后续错误。

数据流：它准备几种常见坏输入：缺少 data: 开头、缺少逗号、没有 base64 标记、base64 内容非法；每个都交给 data URL 图片处理函数；结果都应该是 InvalidDataUrl 这类清楚的错误。

调用关系：这个测试不需要造真实图片，而是直接攻击 data URL 解析入口。它保证错误会在最靠前的解析阶段被拦下。

调用图：外部调用 1 个（assert!）。

async fn resize_with_limits_respects_dimension_and_patch_budgets()

作用：确认调用者自定义图片限制时，处理流程会同时考虑最大边长和“补丁数量”预算。补丁可以理解成模型看图时切出来的小格子，太多会消耗更多资源。

数据流：它造出 2048×2048 的正方形 PNG，并设置最大边长 2048、最大补丁数 2500；处理流程按这些限制重新计算大小；输出应变成 1600×1600。

调用关系：它用 image_bytes 准备输入，再通过 ResizeWithLimits 模式调用处理流程。它验证的不只是固定默认值，而是外部传入限制时缩放算法也能遵守。

调用图：调用 1 个内部函数（image_bytes）；外部调用 5 个（from_pixel, new, assert_eq!, Rgba, ResizeWithLimits）。

async fn fails_cleanly_for_invalid_images()

作用：确认输入根本不是图片时，函数会干净地返回错误。这样调用者能知道问题出在解码或格式不支持，而不是程序崩溃。

数据流：它把字符串“not an image”当作图片字节送进去；处理流程尝试识别和解码失败；输出应是 Decode 或 UnsupportedImageFormat 这类可预期错误。

调用关系：它直接测试图片字节处理入口的防御能力。这个测试覆盖了正常造图工具不会产生的异常输入场景。

调用图：外部调用 2 个（new, assert!）。

async fn reprocesses_updated_file_contents()

作用：确认同一个路径名下，如果图片内容变了，处理结果也会跟着变，而不是错误地复用旧缓存。否则用户更新图片后可能还看到旧结果。

数据流：它先清空全局图片缓存；用同一个路径名处理第一张 32×16 图片；再用同一个路径名处理第二张 96×48 图片；最后检查两次输出尺寸不同、字节也不同。

调用关系：它用 image_bytes 连续生成两份内容不同的图片，并故意使用同一个路径。它验证缓存键里确实考虑了内容变化，而不只是看文件名。

调用图：调用 1 个内部函数（image_bytes）；外部调用 5 个（from_pixel, new, assert_eq!, assert_ne!, Rgba）。

async fn bounds_cache_by_encoded_byte_size()

作用：确认图片缓存按编码后的字节大小限制容量，而不是只按图片数量限制。这样可以防止少数大图片把内存吃满。

数据流：它新建一个小缓存，准备几个固定键和不同大小的假 EncodedImage；先放入两个 3 字节图片，再尝试放入一个超过 5 字节容量的 6 字节图片；结果第一个会被挤掉，第二个还在，过大的第三个不会缓存。

调用关系：这个测试绕开真实图片处理，直接检查 cache_image 和 ImageCache 的容量规则。它是缓存系统的边界测试，确保图片处理流程背后的存储不会无限膨胀。

调用图：外部调用 3 个（new, new, assert!）。

fn main()

作用：这是基准测试程序的入口。运行这个文件生成的测试程序时，它会把控制权交给 divan，让 divan 找到并执行各个测速项目。

数据流：进去没有业务输入 → 调用 divan 的主运行器 → divan 负责发现带有基准测试标记的函数并输出测速结果，这个函数本身不产出图片数据。

调用关系：它站在最外层，像按下秒表测试台的总开关。它只调用外部的 divan 主函数，之后具体测哪些图片、怎么测，就由下面那些带基准测试标记的函数接手。

调用图：外部调用 1 个（main）。

fn small_png_screenshot_fresh_attachment(bencher: Bencher)

作用：这个测速项模拟“第一次上传一张较小 PNG 截图”。它主要看没有缓存帮忙时，截图处理流程要花多久。

数据流：进去是 divan 给的计时器 → 先用 small 的尺寸造一张 PNG 截图，再生成多份会让缓存认不出来的变体 → 把这些变体交给统一的“新附件”测速流程，最后由基准工具记录耗时。

调用关系：它是一个具体测试场景的包装函数。它先找 screenshot_png 造图，再找 cache_miss_variants 做缓存未命中的多份样本，最后把活交给 bench_fresh_attachment 来统一跑计时。

调用图：调用 3 个内部函数（bench_fresh_attachment, cache_miss_variants, screenshot_png）。

fn large_png_screenshot_fresh_attachment(bencher: Bencher)

作用：这个测速项模拟“第一次上传一张大 PNG 截图”。它用更大的屏幕尺寸，观察大截图在无缓存情况下的处理成本。

数据流：进去是 divan 的计时器 → 按大截图尺寸生成 PNG 数据 → 把这张图扩成多份不同内容指纹的版本 → 交给新附件测速流程，得到一组处理耗时。

调用关系：它和小截图测速项结构一样，只是图片更大。它调用 screenshot_png 造大图，调用 cache_miss_variants 避开缓存，再调用 bench_fresh_attachment 执行实际计时。

调用图：调用 3 个内部函数（bench_fresh_attachment, cache_miss_variants, screenshot_png）。

fn large_jpeg_photo_fresh_attachment(bencher: Bencher)

作用：这个测速项模拟“第一次上传一张大 JPEG 照片”。它用照片类图片，而不是截图，来覆盖另一种常见输入。

数据流：进去是 divan 的计时器 → 生成一张大尺寸、带颜色渐变和纹理的 JPEG 照片 → 做出多份缓存未命中的变体 → 交给新附件测速流程记录处理时间。

调用关系：它代表照片场景。它先调用 photo_jpeg 生成测试照片，再调用 cache_miss_variants 让每轮像新图片，最后由 bench_fresh_attachment 统一安排计时。

调用图：调用 3 个内部函数（bench_fresh_attachment, cache_miss_variants, photo_jpeg）。

fn small_png_screenshot_repeated_attachment(bencher: Bencher)

作用：这个测速项模拟“同一张小 PNG 截图反复上传或反复使用”。它用来观察缓存命中时，图片处理能省下多少时间。

数据流：进去是 divan 的计时器 → 生成一张固定的小截图 PNG → 把同一份图片交给重复附件测速流程 → 基准工具记录反复处理同一内容的耗时。

调用关系：它是缓存命中场景的入口。它调用 screenshot_png 造出固定样本，然后把样本交给 bench_repeated_attachment；后者会先预热一次，再开始正式计时。

调用图：调用 2 个内部函数（bench_repeated_attachment, screenshot_png）。

fn bench_fresh_attachment(bencher: Bencher, path: &'static str, images: Vec<Vec<u8>>)

作用：这个函数把“每一轮都像新图片”的测速方式封装起来。调用者只要给它文件名和一批图片字节，它就负责一轮换一张，尽量测到缓存未命中的真实开销。

数据流：进去是计时器、一个假文件路径、以及多份图片字节 → 它维护一个下标，每轮从图片列表取一份并复制出来，取完循环回开头 → 这些输入被交给 divan 的本地值基准流程去计时，函数本身不返回业务结果。

调用关系：三个“fresh_attachment”场景都会调用它：小 PNG 截图、大 PNG 截图、大 JPEG 照片。它主要依赖 divan 的 with_inputs，把准备输入这件事排除在计时之外，让测速更专注于后面的图片处理。

调用图：被 3 处调用（large_jpeg_photo_fresh_attachment, large_png_screenshot_fresh_attachment, small_png_screenshot_fresh_attachment）；外部调用 1 个（with_inputs）。

fn bench_repeated_attachment(bencher: Bencher, path: &'static str, image: Vec<u8>)

作用：这个函数封装“同一张图片重复处理”的测速方式。它先跑一次来填好缓存，再开始正式测，像先让机器热身再看稳定速度。

数据流：进去是计时器、文件路径和一份图片字节 → 先调用 prepare_prompt_data_url 处理一次，通常用于预热缓存 → 正式计时时每轮复制同一张图片，再把它送入图片准备流程，最后由 divan 记录耗时。

调用关系：它由 small_png_screenshot_repeated_attachment 调用，专门服务重复附件场景。它自己会调用 prepare_prompt_data_url 做预热和后续处理，并使用 divan 的 with_inputs 避免把每轮复制输入的时间算进去。

调用图：调用 1 个内部函数（prepare_prompt_data_url）；被 1 处调用（small_png_screenshot_repeated_attachment）；外部调用 1 个（with_inputs）。

fn prepare_prompt_data_url(path: &str, image: Vec<u8>) -> String

作用：这个函数是真正把图片字节变成提示词可用格式的地方。它会按给定路径判断图片类型，按“缩到合适大小”的模式加载图片，最后转成 data URL 文本。

数据流：进去是一个文件路径字符串和图片原始字节 → 把路径变成 Path，再调用 load_for_prompt_bytes 按 ResizeToFit 模式读取、校验、必要时缩放图片 → 成功后输出一个 data URL 字符串；如果测试夹具坏了，它会直接报错，因为基准测试不应该吞掉这种问题。

调用关系：它处在测速流程的核心位置，是 bench_repeated_attachment 会直接调用的图片处理动作。它把本文件造出的测试图片交给 codex_utils_image 里的真实加载逻辑，所以测速结果能反映那条实际处理流水线的成本。

调用图：被 1 处调用（bench_repeated_attachment）；外部调用 2 个（new, load_for_prompt_bytes）。

fn cache_miss_variants(image: Vec<u8>) -> Vec<Vec<u8>>

作用：这个函数把一张图片复制成多份“内容指纹不同”的版本。这样测试时缓存认不出它们，就能稳定测到新图片的处理速度。

数据流：进去是一份图片字节 → 循环生成固定数量的变体，每份都先复制原图，再在末尾追加一个不同的小数字 → 出来是一组 Vec<Vec<u8>>，也就是多份图片字节，供 fresh 测试轮流使用。

调用关系：三个新附件测速项都会先调用它。它不负责真正处理图片，只负责准备“别让缓存命中”的输入，让 bench_fresh_attachment 测到的是冷启动路径，而不是被缓存加速后的路径。

调用图：被 3 处调用（large_jpeg_photo_fresh_attachment, large_png_screenshot_fresh_attachment, small_png_screenshot_fresh_attachment）。

fn screenshot_png(size: ImageSize) -> Vec<u8>

作用：这个函数现场生成一张假的软件界面截图，并编码成 PNG。它避免依赖外部图片文件，让基准测试在任何机器上都能稳定复现。

数据流：进去是图片宽高 → 按每个像素的位置画出工具栏、侧边栏、面板边框、文字行和不同底色区域 → 把这张 RGBA 图片交给 encode_fixture 编成 PNG 字节并返回。

调用关系：小截图、大截图和重复小截图三个场景都会调用它。它负责提供截图类测试材料，最后把编码工作交给 encode_fixture，这样生成图片和写成 PNG 文件格式这两步分开。

调用图：调用 1 个内部函数（encode_fixture）；被 3 处调用（large_png_screenshot_fresh_attachment, small_png_screenshot_fresh_attachment, small_png_screenshot_repeated_attachment）；外部调用 2 个（ImageRgba8, from_fn）。

fn photo_jpeg(size: ImageSize) -> Vec<u8>

作用：这个函数现场生成一张假的照片，并编码成 JPEG。它用渐变和纹理模拟真实照片里比较复杂的颜色变化。

数据流：进去是图片宽高 → 对每个像素计算横向渐变、纵向渐变和一点伪随机纹理 → 组合成 RGB 颜色后形成整张图，再交给 encode_fixture 编成 JPEG 字节返回。

调用关系：大 JPEG 照片的新附件测速项会调用它。它负责提供照片类测试材料；颜色通道的混合由 blend_channel 帮忙算，最后编码成文件字节的活交给 encode_fixture。

调用图：调用 1 个内部函数（encode_fixture）；被 1 处调用（large_jpeg_photo_fresh_attachment）；外部调用 2 个（ImageRgb8, from_fn）。

fn blend_channel(gradient: u32, texture: u8, divisor: u32) -> u8

作用：这个小函数把平滑渐变和纹理噪点混在一起，算出一个颜色通道的值。它让假照片看起来不只是单调色块，更接近真实图片。

数据流：进去是一个渐变值、一个纹理值、以及一个控制纹理强弱的除数 → 把纹理按比例变小后加到渐变上，再限制到 0 到 255 的字节范围 → 出来是一个 u8 颜色值，可用于红、绿、蓝中的某一个通道。

调用关系：它是 photo_jpeg 生成像素颜色时用到的细小零件。外部不会单独使用它；它的存在是为了让照片生成逻辑更清楚，也方便不同颜色通道用不同强度的纹理。

调用图：外部调用 1 个（from）。

fn encode_fixture(image: DynamicImage, format: ImageFormat) -> Vec<u8>

作用：这个函数把内存里的图片对象写成真正的 PNG 或 JPEG 字节。没有它，前面造出来的只是像素矩阵，不是图片加载器平时会收到的文件内容。

数据流：进去是一张 DynamicImage 和目标图片格式 → 创建一个内存缓冲区，用 image 库把图片按指定格式写进去 → 返回缓冲区里的字节；如果编码失败，测试会直接报错，因为夹具生成失败说明基准本身有问题。

调用关系：screenshot_png 和 photo_jpeg 都把最终编码工作交给它。它像统一的打包机：不管上游造的是截图还是照片，都由它把像素数据打包成后续图片处理流程能读取的真实图片格式。

调用图：调用 1 个内部函数（new）；被 2 处调用（photo_jpeg, screenshot_png）；外部调用 2 个（write_to, new）。