Exec-server、沙箱和远程传输测试工具

fn current_test_binary_helper_paths() -> anyhow::Result<(PathBuf, Option<PathBuf>)>

作用：告诉测试代码：当前这个测试程序在哪里，以及在 Linux 上应该用哪个程序当沙箱 helper。有人要启动子进程做集成测试时，会用它拿到正确路径。

数据流：进去不需要业务参数，只读取操作系统告诉它的当前可执行文件路径，并查看当前是不是 Linux。然后它根据测试分发器里记录的别名路径，决定 Linux 沙箱程序路径；如果没有单独路径，就退回使用当前测试程序自己。出来的是一对路径：当前测试二进制路径，以及可选的 Linux 沙箱二进制路径。

调用关系：它被更高层的测试使用，比如检查进程退出后输出是否还会被保留，以及测试远程环境如何路由加密的 exec-server 调用。它本身不启动任何东西，只把后续测试要用的“工具地址”准备好。

调用图：被 2 处调用（assert_exec_process_retains_output_after_exit_until_streams_close, remote_environment_routes_encrypted_exec_server_rpc）；外部调用 2 个（cfg!, current_exe）。

fn maybe_run_delayed_output_after_exit_from_test_binary()

作用：检查当前测试程序是不是被当成“延迟输出测试小程序”启动了。如果是，它就立刻切换身份，去跑父进程或子进程的那段特殊逻辑。

数据流：进去没有显式参数，它直接读取命令行参数。它跳过程序名，查看第一个真正参数是不是约定好的父进程暗号或子进程暗号；如果是，就继续解析释放文件路径，再调用对应的运行函数；如果不是，就什么也不做，让普通测试继续跑。

调用关系：它在测试二进制启动早期被调用，是测试分发机制的一部分。它把参数解析交给 next_release_path_arg，把真正的父进程行为交给 run_delayed_output_after_exit_parent，把真正的子进程等待和打印交给 run_delayed_output_after_exit_child。

调用图：调用 3 个内部函数（next_release_path_arg, run_delayed_output_after_exit_child, run_delayed_output_after_exit_parent）；外部调用 1 个（args）。

fn next_release_path_arg(mut args: impl Iterator<Item = String>) -> PathBuf

作用：从命令行里取出那个“释放信号文件”的路径，并确保参数数量刚刚好。这样测试小程序不会因为少参数或多参数而悄悄跑错。

数据流：进去是一串还没读完的命令行参数。它取下一个参数当作路径；如果没有，就打印错误并退出进程；如果还有多余参数，也打印错误并退出进程。正常情况下，出来的是一个 PathBuf，也就是 Rust 里表示文件路径的对象。

调用关系：它只服务于 maybe_run_delayed_output_after_exit_from_test_binary。父进程模式和子进程模式都需要同一个释放路径，所以先由这个函数统一把路径读干净，再交给后面的运行函数。

调用图：被 1 处调用（maybe_run_delayed_output_after_exit_from_test_binary）；外部调用 4 个（next, from, eprintln!, exit）。

fn run_delayed_output_after_exit_parent(release_path: &Path)

作用：扮演延迟输出测试里的“父进程”：它启动一个子进程后马上退出。这个设计用来模拟一种麻烦情况：父进程没了，但它留下的子进程之后还会往标准输出写东西。

数据流：进去是释放信号文件的路径。它先找到当前测试二进制文件的位置，然后用这个同一个程序再启动一个子进程，并传入子进程暗号和释放路径；子进程的标准输入被关掉。启动成功后，父进程直接以成功状态退出；启动失败则打印错误并以失败状态退出。

调用关系：它由 maybe_run_delayed_output_after_exit_from_test_binary 在看到父进程暗号时调用。它不自己打印延迟输出，而是把后续工作交给新启动的 run_delayed_output_after_exit_child 对应进程。

调用图：被 1 处调用（maybe_run_delayed_output_after_exit_from_test_binary）；外部调用 5 个（null, new, current_exe, eprintln!, exit）。

fn run_delayed_output_after_exit_child(release_path: &Path)

作用：扮演延迟输出测试里的“子进程”：它等到某个文件出现后，才往标准输出写一行文字。这样可以测试 exec-server 是否会等所有输出流真正关闭，而不是父进程一退出就草草收工。

数据流：进去是释放信号文件的路径。它最多循环 1000 次，每次检查这个路径是否已经存在；还不存在就睡 10 毫秒再试。文件一出现，它就向标准输出写入“late output after exit”，刷新输出并成功退出；如果写入、刷新失败，或一直等不到文件，它会打印错误并失败退出。

调用关系：它由 maybe_run_delayed_output_after_exit_from_test_binary 在看到子进程暗号时调用。通常它是 run_delayed_output_after_exit_parent 启动出来的后代进程，用来制造“父进程退出后才来的输出”这个测试场景。

调用图：被 1 处调用（maybe_run_delayed_output_after_exit_from_test_binary）；外部调用 7 个（from_millis, exists, eprintln!, stdout, exit, sleep, writeln!）。

fn maybe_run_exec_server_from_test_binary(guard: Option<&TestBinaryDispatchGuard>)

作用：检查当前测试程序是不是被要求直接当 exec-server 运行。如果是，它就解析监听地址，搭好运行环境，然后启动真正的 exec-server。

数据流：进去是可选的测试分发守卫，它里面可能记录了一些 helper 程序的临时路径。函数读取命令行参数，只有第一个参数是 exec-server 时才继续；然后要求参数格式必须是 --listen 加一个监听 URL，不能多也不能少。接着它找到当前可执行文件，计算运行时需要的 helper 路径，创建 Tokio runtime（Tokio 是 Rust 常用的异步任务运行器），最后调用 codex_exec_server::run_main。运行成功就以 0 退出，失败就打印错误并以 1 退出。

调用关系：它在测试二进制启动早期被调用，和普通测试抢先判断当前进程该不该变身成服务器。它会调用 linux_sandbox_exe 决定 Linux 沙箱路径，再把监听地址和运行路径交给 codex_exec_server::run_main，真正的服务器主逻辑在那里执行。

调用图：调用 2 个内部函数（new, linux_sandbox_exe）；外部调用 6 个（run_main, args, current_exe, eprintln!, exit, new_multi_thread）。

fn linux_sandbox_exe(
    guard: Option<&TestBinaryDispatchGuard>,
    current_exe: &std::path::Path,
) -> Option<PathBuf>

作用：决定在当前平台上，exec-server 测试应该使用哪个 Linux 沙箱可执行文件。非 Linux 平台不需要这个东西，所以会返回空。

数据流：进去是可选的测试分发守卫，以及当前测试二进制路径。在 Linux 上，它优先使用守卫里记录的 codex_linux_sandbox_exe 路径；如果没有，就用当前测试二进制自己当沙箱入口。在非 Linux 上，它忽略这些输入，直接返回 None，表示没有沙箱程序路径。

调用关系：它被 maybe_run_exec_server_from_test_binary 调用，是启动测试版 exec-server 前准备运行路径的一小步。它不启动沙箱，只负责告诉 ExecServerRuntimePaths 应该把哪个文件当作沙箱 helper。

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

fn drop(&mut self)

作用：这是测试工具被销毁时的兜底清理。它会尽量杀掉正在跑的 exec-server 子进程，防止测试结束后后台还残留一个服务器。

数据流：进去的是 ExecServerHarness 里保存的子进程句柄 → 它调用系统提供的 start_kill 发出终止信号，并且忽略清理时的错误 → 出来没有返回值，但外部进程会被要求停止。

调用关系：它不由测试手动调用，而是在 ExecServerHarness 生命周期结束时自动发生。它把最后的清理工作交给子进程句柄的 start_kill，和 shutdown 的主动关闭形成双保险。

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

fn test_codex_helper_paths() -> anyhow::Result<TestCodexHelperPaths>

作用：这个函数找到测试要启动的 codex 辅助程序路径。测试不能凭空启动服务器，必须先知道可执行文件在哪里。

数据流：进去没有参数 → 它询问外层测试工具 current_test_binary_helper_paths，拿到 codex 主程序路径和可选的 Linux 沙箱程序路径 → 出来是 TestCodexHelperPaths，里面装着这些路径。

调用关系：exec_server_with_env 启动服务器前会先用它找程序位置；create_file_system_context 这类测试辅助也会用它准备文件系统相关环境。

调用图：被 2 处调用（exec_server_with_env, create_file_system_context）；外部调用 1 个（current_test_binary_helper_paths）。

async fn exec_server() -> anyhow::Result<ExecServerHarness>

作用：这是最常用的默认启动入口：用标准环境启动一个 exec-server 测试实例。多数测试只要调用它，就能拿到一个可发消息、可收事件的测试遥控器。

数据流：进去没有参数 → 它传入一个空的环境变量列表，交给 exec_server_with_env 做真正的启动工作 → 出来是一个已经连上 WebSocket 的 ExecServerHarness。

调用关系：大量 exec-server 测试会直接调用它，比如进程上下文、文件读取、句柄容量限制、流读取等测试。它自己不做细节，只是把活儿转给 exec_server_with_env。

调用图：调用 1 个内部函数（exec_server_with_env）；被 24 处调用（create_process_context, completed_streams_release_handle_capacity, file_reads_reject_fifo_without_waiting_for_a_writer, file_reads_reject_named_pipes, open_enforces_the_per_connection_limit_and_close_releases_capacity, open_rejects_handle_ids_longer_than_32_bytes, read_block_supports_non_sequential_offsets_and_lengths, stream_keeps_reading_the_open_file_after_path_replacement, stream_rejects_platform_sandbox, stream_stops_after_an_exact_block_boundary (+14 more)）。

async fn exec_server_with_env(env: I) -> anyhow::Result<ExecServerHarness>

作用：这个函数用指定环境变量启动 exec-server。它适合那些需要改环境来验证特殊行为的测试。

数据流：进去是一组额外环境变量 → 它先找 helper 程序路径，创建临时 CODEX_HOME，配置子进程参数、标准输入输出和环境变量，启动进程；然后从标准输出读出 WebSocket 地址，再等服务器可连接 → 出来是 ExecServerHarness，里面保存临时目录、子进程、地址、WebSocket 连接和下一个请求编号。

调用关系：exec_server 是它的简化包装；需要特殊环境的测试，比如 sandboxed_file_system_helper_finds_bwrap_on_preserved_path，会直接调用它。它把读地址交给 read_listen_url_from_stdout，把连接等待交给 connect_websocket_when_ready。

调用图：调用 3 个内部函数（connect_websocket_when_ready, read_listen_url_from_stdout, test_codex_helper_paths）；被 2 处调用（exec_server, sandboxed_file_system_helper_finds_bwrap_on_preserved_path）；外部调用 5 个（inherit, null, piped, new, new）。

fn websocket_url(&self) -> &str

作用：这个函数把当前 exec-server 的 WebSocket 地址拿出来。测试如果要检查地址，或者自己建立额外连接，就会用到它。

数据流：进去的是 harness 自身 → 它只读取里面保存的 websocket_url 字符串引用 → 出来是这个地址，不改动任何状态。

调用关系：它是 ExecServerHarness 暴露给测试的小窗口，不参与启动或发消息流程，只负责让外部看见服务器监听在哪里。

async fn disconnect_websocket(&mut self) -> anyhow::Result<()>

作用：这个函数主动断开当前 WebSocket 连接。它常用来测试服务器遇到客户端断线时会不会表现正常。

数据流：进去的是当前 harness 和里面的 WebSocket 连接 → 它发送关闭帧，让这根双向通信线正常收口 → 出来是成功或失败结果，连接状态被改为关闭。

调用关系：它把真正的关闭动作交给 WebSocket 库的 close。之后如果测试还想继续通信，可以调用 reconnect_websocket 重新连上。

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

async fn reconnect_websocket(&mut self) -> anyhow::Result<()>

作用：这个函数用原来的地址重新连到 exec-server。它让测试可以模拟“客户端断了又回来”的场景。

数据流：进去的是 harness 中保存的 websocket_url → 它调用 connect_websocket_when_ready，拿到新的 WebSocket 连接 → 出来是成功或失败结果，并把 harness 里的旧连接替换成新连接。

调用关系：它依赖 connect_websocket_when_ready 处理“服务器还没马上接受连接”的等待和重试。通常会在 disconnect_websocket 之后使用。

调用图：调用 1 个内部函数（connect_websocket_when_ready）。

async fn send_request(
        &mut self,
        method: &str,
        params: serde_json::Value,
    ) -> anyhow::Result<RequestId>

作用：这个函数向 exec-server 发送一条 JSON-RPC 请求。请求有编号，所以测试之后可以把服务器回复和这次请求对应起来。

数据流：进去是方法名和 JSON 参数 → 它用当前 next_request_id 生成 RequestId，再把编号加一，组装成 JSONRPCRequest，并交给 send_message 发送 → 出来是这次请求的编号，同时 WebSocket 上已经发出一条请求消息。

调用关系：initialize_exec_server 这类测试初始化流程会用它发正式请求。它不直接碰编码和网络发送，而是把消息交给 send_message 统一处理。

调用图：调用 1 个内部函数（send_message）；被 1 处调用（initialize_exec_server）；外部调用 2 个（Request, Integer）。

async fn send_notification(
        &mut self,
        method: &str,
        params: serde_json::Value,
    ) -> anyhow::Result<()>

作用：这个函数向 exec-server 发送一条 JSON-RPC 通知。通知没有请求编号，意思是“告诉你一件事”，通常不要求服务器按编号回复。

数据流：进去是方法名和 JSON 参数 → 它组装成 JSONRPCNotification，再交给 send_message 编码并发送 → 出来是成功或失败结果，不生成请求编号。

调用关系：initialize_exec_server 会用它发送初始化过程中的通知。它和 send_request 共享 send_message，区别是它发的是无编号消息。

调用图：调用 1 个内部函数（send_message）；被 1 处调用（initialize_exec_server）；外部调用 1 个（Notification）。

async fn send_raw_text(&mut self, text: &str) -> anyhow::Result<()>

作用：这个函数直接往 WebSocket 发一段原始文本，不帮你包装成 JSON-RPC。它常用于故意发送坏消息，测试服务器是否能正确报错而不是崩掉。

数据流：进去是一段字符串 → 它把字符串包成 WebSocket 的文本帧并发送 → 出来是成功或失败结果，服务器会收到这段原始文本。

调用关系：它绕过 send_message，不做 JSON 编码。测试需要模拟异常输入时会直接用它。

调用图：外部调用 2 个（send, Text）。

async fn send_raw_binary(&mut self, bytes: Vec<u8>) -> anyhow::Result<()>

作用：这个函数直接往 WebSocket 发一段原始二进制数据。它用来测试服务器面对非文本或特殊字节内容时的反应。

数据流：进去是一组字节 → 它把这些字节包成 WebSocket 的二进制帧并发送 → 出来是成功或失败结果，服务器会收到这段二进制内容。

调用关系：它也绕过 JSON-RPC 包装，和 send_raw_text 一样服务于“坏输入”或边界情况测试。

调用图：外部调用 2 个（send, Binary）。

async fn next_event(&mut self) -> anyhow::Result<JSONRPCMessage>

作用：这个函数等待服务器发来的下一条 JSON-RPC 消息。它给测试一个简单办法：拿到服务器接下来发生的事件或回复。

数据流：进去的是 harness 当前的 WebSocket 连接 → 它使用默认的 EVENT_TIMEOUT 超时时间调用 next_event_with_timeout → 出来是一条解析好的 JSONRPCMessage，或者超时、断线、解析失败等错误。

调用关系：collect_response_body_deltas 会用它连续收集响应内容片段。它是 next_event_with_timeout 的便捷包装。

调用图：调用 1 个内部函数（next_event_with_timeout）；被 1 处调用（collect_response_body_deltas）。

async fn wait_for_event(
        &mut self,
        mut predicate: F,
    ) -> anyhow::Result<JSONRPCMessage>

作用：这个函数一直收服务器消息，直到某条消息符合测试给出的条件。它适合服务器会发很多事件、测试只关心其中一种的情况。

数据流：进去是一个判断函数 predicate，以及当前 WebSocket 连接 → 它在总超时时间内一条条调用 next_event_with_timeout 取消息，每取到一条就让 predicate 判断 → 出来是第一条匹配的消息；如果一直没有匹配，就返回超时错误。

调用关系：wait_for_response 和 wait_for_error_response 这类辅助会用它等待指定回复。它把单次收消息交给 next_event_with_timeout，自己负责循环和筛选。

调用图：调用 1 个内部函数（next_event_with_timeout）；被 2 处调用（wait_for_error_response, wait_for_response）；外部调用 2 个（now, anyhow!）。

async fn shutdown(&mut self) -> anyhow::Result<()>

作用：这个函数主动关闭测试启动的 exec-server，并等待它真的退出。比起只发杀进程信号，它还会确认收尾完成。

数据流：进去的是 harness 里的子进程句柄 → 它先调用 start_kill 要求进程停止，再用 timeout 包住 child.wait 等待退出 → 出来是成功或错误；成功时子进程已经结束，超时则报告关闭失败。

调用关系：测试如果想在中途明确结束服务器，会调用它。它和 Drop 的自动清理不同：shutdown 会等待并报告结果，Drop 只是兜底尝试杀掉。

调用图：外部调用 3 个（start_kill, wait, timeout）。

async fn send_message(&mut self, message: JSONRPCMessage) -> anyhow::Result<()>

作用：这是发送 JSON-RPC 消息的内部统一出口。它把 Rust 里的消息对象变成 JSON 文本，再通过 WebSocket 发出去。

数据流：进去是一条 JSONRPCMessage → 它用 serde_json 转成字符串，再包成 WebSocket 文本帧发送 → 出来是成功或失败结果，网络上已经发出一段 JSON 文本。

调用关系：send_request 和 send_notification 都把最终发送工作交给它。这样两种消息共享同一套编码和发送方式，减少重复。

调用图：被 2 处调用（send_notification, send_request）；外部调用 3 个（send, to_string, Text）。

async fn next_event_with_timeout(
        &mut self,
        timeout_duration: Duration,
    ) -> anyhow::Result<JSONRPCMessage>

作用：这个函数在指定时间内等下一条服务器消息，并把它解析成 JSON-RPC 消息。它是接收事件的底层工具。

数据流：进去是一个超时时长和当前 WebSocket 连接 → 它等待下一帧；如果是文本，就按 JSON 字符串解析；如果是二进制，就按 JSON 字节解析；如果是关闭帧就报连接关闭；如果是 ping/pong 这类心跳帧就忽略继续等 → 出来是一条 JSONRPCMessage，或超时、断线、解析错误。

调用关系：next_event 用它实现默认超时等待，wait_for_event 用它反复取消息并筛选。它集中处理 WebSocket 帧到 JSON-RPC 消息的转换。

调用图：被 2 处调用（next_event, wait_for_event）；外部调用 5 个（next, anyhow!, from_slice, from_str, timeout）。

async fn connect_websocket_when_ready(
    websocket_url: &str,
) -> anyhow::Result<(
    tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>,
    tokio_tungst

作用：这个函数负责连接 exec-server 的 WebSocket，并处理“服务器刚启动还没准备好”的短暂空窗。它会在一段时间内反复重试连接。

数据流：进去是 WebSocket 地址字符串 → 它调用 connect_async 尝试连接；如果只是连接被拒绝，并且还没超过总超时，就睡一小会儿再试；如果连上就返回连接和握手响应；如果是别的错误或超时后仍失败，就返回错误 → 出来是可用的 WebSocket 连接或失败原因。

调用关系：exec_server_with_env 启动服务器后用它建立第一次连接；reconnect_websocket 用它重新连接。它把“等服务器准备好”的细节从测试代码里藏起来。

调用图：被 2 处调用（reconnect_websocket, exec_server_with_env）；外部调用 4 个（now, matches!, sleep, connect_async）。

async fn read_listen_url_from_stdout(child: &mut Child) -> anyhow::Result<String>

作用：这个函数从 exec-server 的标准输出里读出它实际监听的 WebSocket 地址。因为测试让服务器使用端口 0，意思是让系统随机挑一个空闲端口，所以必须读回真实地址。

数据流：进去是子进程句柄 → 它取走子进程的 stdout，用按行读取器一行行读，在超时前寻找以 ws:// 开头的行 → 出来是监听地址字符串；如果 stdout 没抓到、提前关闭、或等太久都没地址，就返回错误。

调用关系：exec_server_with_env 启动子进程后马上调用它拿地址，然后再把地址交给 connect_websocket_when_ready 去连接。它是从“进程已启动”走到“客户端知道去哪连”的关键桥梁。

调用图：被 1 处调用（exec_server_with_env）；外部调用 4 个（new, now, anyhow!, timeout）。

fn parse_listen_url_accepts_default_websocket_url()

作用：这个测试确认服务器内置的默认监听地址能被正确理解成 WebSocket 地址。它保证“什么都不特别配置”时，默认入口不会一启动就解析失败。

数据流：输入是 DEFAULT_LISTEN_URL 这个默认字符串 → 测试把它交给 parse_listen_url 解析 → 结果应该变成 WebSocket，并且地址是 127.0.0.1:0；如果不是，就用断言让测试失败。

调用关系：它直接检查 parse_listen_url 这个解析函数的默认场景。这个测试不再把工作交给别的本文件函数，只负责守住默认配置这条路。

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

fn parse_listen_url_accepts_stdio()

作用：这个测试确认用户写 --listen stdio 时，服务器会选择标准输入输出通信。这样命令行或父进程用管道启动服务器时，就能用最简单的写法。

数据流：输入是字符串 stdio → parse_listen_url 把它解析成内部的 Stdio 选项 → 测试比较结果，确认没有被误认成网络地址或报错。

调用关系：它覆盖 parse_listen_url 的 stdio 简写形式。它和后面的 stdio:// 测试一起保证同一种通信方式的两种写法都可用。

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

fn parse_listen_url_accepts_stdio_url()

作用：这个测试确认 stdio:// 这种像网址一样的写法也能表示标准输入输出通信。它让配置写法更宽容，减少用户因为格式小差异踩坑。

数据流：输入是字符串 stdio:// → parse_listen_url 解析它 → 输出应该仍然是 Stdio；测试用断言确认这一点。

调用关系：它同样围绕 parse_listen_url，只是检查 stdio 的 URL 形式。它补上了 parse_listen_url_accepts_stdio 没覆盖的写法。

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

async fn stdio_listen_transport_serves_initialize()

作用：这个异步测试确认 stdio 通道不只是能被解析出来，还真的能跑通一次初始化通信。也就是说，客户端发 initialize 请求后，服务器要能回一个有效会话号，并在客户端断开后正常收尾。

数据流：一开始它把 stdio 字符串解析成 Stdio，然后用内存里的双向管道模拟客户端和服务器之间的输入输出 → 启动 run_stdio_connection_with_io 作为服务器任务，并构造 JSON-RPC initialize 请求写进去 → 从客户端读回服务器响应，解析成 InitializeResponse，检查请求 id 对得上、session_id 不是空的 → 再发送 initialized 通知，关闭客户端写入端和读取端 → 最后等待服务器任务结束，确认它没有超时、没有崩溃、没有返回错误。

调用关系：这是本文件里最接近真实使用的一条端到端测试。它调用 test_runtime_paths 准备服务器运行时需要的路径，用 write_jsonrpc_line 把请求和通知写成一行一条的 JSON-RPC 消息，然后驱动 run_stdio_connection_with_io 验证 stdio 传输层真的能服务初始化流程。

调用图：调用 2 个内部函数（test_runtime_paths, write_jsonrpc_line）；外部调用 16 个（new, from_secs, Notification, Request, Integer, assert!, assert_eq!, panic!, from_str, from_value (+6 more)）。

fn parse_listen_url_accepts_websocket_url()

作用：这个测试确认合法的 WebSocket 监听地址会被接受。它保护的是网络模式下最基本的配置入口。

数据流：输入是 ws://127.0.0.1:1234 → parse_listen_url 解析这个字符串 → 输出应该是 WebSocket，并带着 127.0.0.1:1234 这个 socket 地址；测试用比较确认结果准确。

调用关系：它直接测试 parse_listen_url 的 WebSocket 正常路径。和默认 WebSocket 测试相比，它检查的是用户显式写出的地址。

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

fn parse_listen_url_rejects_invalid_websocket_url()

作用：这个测试确认 ws://localhost:1234 会被拒绝，因为这里要求写明确的 IP 地址，而不是 localhost 这种主机名。这样可以避免绑定地址含糊不清，减少运行时意外。

数据流：输入是 ws://localhost:1234 → parse_listen_url 尝试解析但应该失败 → 测试拿到错误信息，并确认它清楚说明期望格式是 ws://IP:PORT。

调用关系：它检查 parse_listen_url 的错误路径。它和接受合法 WebSocket 的测试配对，说明这个解析器不是随便放行，而是有明确格式要求。

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

fn parse_listen_url_rejects_unsupported_url()

作用：这个测试确认不支持的协议，比如 http://，会被明确拒绝。它防止用户以为服务器能用普通 HTTP 方式监听，结果后面才出现更难懂的问题。

数据流：输入是 http://127.0.0.1:1234 → parse_listen_url 判断协议不在允许范围内 → 返回错误；测试检查错误文字是否说明只支持 ws://IP:PORT 或 stdio。

调用关系：它守住 parse_listen_url 的边界条件。它和其他解析测试一起，把“哪些写法能用、哪些写法不能用”固定下来。

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

async fn write_jsonrpc_line(writer: &mut tokio::io::DuplexStream, message: &JSONRPCMessage)

作用：这个小工具函数把一条 JSON-RPC 消息写进模拟连接里，并在末尾加换行。服务器按“一行一条消息”来读，所以这个换行很关键。

数据流：输入是一条 JSONRPCMessage 和一个可写的内存流 → 函数先把消息序列化成 JSON 字节 → 写入流里，再写入一个换行符 → 输出没有单独返回值，但会改变流里的内容，让对面能读到完整消息。

调用关系：它被 stdio_listen_transport_serves_initialize 调用两次：一次写 initialize 请求，一次写 initialized 通知。它把测试里的“发消息”动作包装起来，让主测试不用重复关心 JSON 编码和换行细节。

调用图：被 1 处调用（stdio_listen_transport_serves_initialize）；外部调用 2 个（write_all, to_vec）。

fn test_runtime_paths() -> ExecServerRuntimePaths

作用：这个小工具函数给测试里的服务器准备运行时路径。服务器启动时需要知道当前可执行文件等位置，所以测试也要给它一份看起来真实的路径配置。

数据流：它读取当前正在运行的测试可执行文件路径 → 用这个路径创建 ExecServerRuntimePaths，并把 Linux sandbox 可执行文件位置设为空 → 返回可用的运行时路径对象；如果路径读取或创建失败，测试会直接失败。

调用关系：它被 stdio_listen_transport_serves_initialize 在启动 stdio 服务器任务前调用。它负责补齐服务器运行所需的环境信息，让主测试能专心验证通信流程。

调用图：调用 1 个内部函数（new）；被 1 处调用（stdio_listen_transport_serves_initialize）；外部调用 1 个（current_exe）。

async fn exec_server_accepts_initialize() -> anyhow::Result<()>

作用：这个测试函数检查 exec-server 的初始化流程是否真的能跑通。有人改了初始化协议、返回格式或测试服务器启动方式后，它能第一时间发现“客户端刚连上就失败”的问题。

数据流：进去的是一个测试环境：函数先通过 exec_server 启动服务器；然后把 InitializeParams 转成 JSON，发送 initialize 请求；服务器返回一条消息后，函数检查它是不是 JSON-RPC 响应、响应编号是不是刚才那次请求的编号；接着把响应内容转成 InitializeResponse，并用 UUID 解析器检查 session_id 格式正确；最后关闭服务器。出来的结果是 Ok，表示初始化成功；如果中间任何一步不对，测试就会报错或 panic。

调用关系：它是测试框架 Tokio 在运行测试时调用的异步测试。它把启动服务器的工作交给 common 里的 exec_server，把参数和结果的 JSON 转换交给 serde_json，把会话编号格式检查交给 Uuid::parse_str，并用 assert_eq! 确认请求和响应对得上。整个流程模拟了一个真实客户端第一次连接服务器时会做的事情。

调用图：调用 1 个内部函数（exec_server）；外部调用 5 个（parse_str, assert_eq!, panic!, from_value, to_value）。

async fn exec_server_serves_readyz_alongside_websocket_endpoint() -> anyhow::Result<()>

作用：这个测试确认 exec-server 的健康检查地址 /readyz 是可用的。也就是说，服务器在提供 WebSocket 功能的同时，也能用普通 HTTP 告诉外界“我准备好了”。

数据流：测试先启动一个临时 exec-server，拿到它的 WebSocket 地址；然后把地址里的 ws:// 换成普通 HTTP 可访问的基础地址，拼出 /readyz；接着用 reqwest 发 GET 请求；最后检查返回状态是不是 OK。测试结束前会关闭这个临时服务器。

调用关系：它先调用 common 里的 exec_server 来启动测试服务器，再用 format! 拼出健康检查网址，用 reqwest::get 发请求，最后用 assert_eq! 核对状态码。这个测试站在外部使用者角度，验证服务启动后健康检查入口确实能被访问。

调用图：调用 1 个内部函数（exec_server）；外部调用 3 个（assert_eq!, format!, get）。

async fn remote_environment_fetches_info_from_exec_server() -> anyhow::Result<()>

作用：这个测试确认远程环境对象真的会通过 exec-server 取信息，而且取到的信息和本地环境一致。这样可以防止远程模式看起来启用了，实际却拿错或漏拿环境数据。

数据流：测试先启动一个临时 exec-server；再用它的 WebSocket 地址创建一个测试用 Environment，并确认这个 Environment 是远程模式；随后向远程 Environment 要环境信息，同时也从默认本地 Environment 取一份信息；最后比较两份信息必须相同。测试完成后关闭服务器。

调用关系：它调用 exec_server 准备远程服务，用 Environment::create_for_tests 创建连接到该服务的远程环境，用 Environment::default_for_tests 创建本地对照组，再用 assert! 和 assert_eq! 检查模式和结果。它验证的是 Environment 和 exec-server 之间的配合是否正确。

调用图：调用 3 个内部函数（create_for_tests, default_for_tests, exec_server）；外部调用 2 个（assert!, assert_eq!）。

async fn exec_server_reports_malformed_websocket_json_and_keeps_running() -> anyhow::Result<()>

作用：这个测试确认服务器收到一条完全不是 JSON 的 WebSocket 文本消息时，不会直接崩掉。它还会继续发正常的初始化请求，证明服务器在报错后仍然能正常工作。

数据流：测试先启动一个临时 exec-server，然后往 WebSocket 里发入字符串“not-json”。服务器应当吐出一个 JSON-RPC 错误，测试检查错误 id、错误码和错误消息开头是否符合预期。接着测试再发送 initialize 请求，把客户端名称和空的恢复会话 id 传进去，等待服务器返回初始化结果，并把返回的 session_id 当作 UUID（一种标准格式的唯一编号）解析，确认它真的是合法会话编号。最后关闭服务器。

调用关系：它在测试流程里扮演“坏输入后还能不能继续服务”的检查员。它先通过 common 测试工具 exec_server 启动服务器，再用服务器测试句柄发送原始文本、等待事件、发送正式请求；过程中借助 JSON 解析和断言工具确认服务器给出的错误与后续响应都正确。

调用图：调用 1 个内部函数（exec_server）；外部调用 6 个（parse_str, assert!, assert_eq!, panic!, from_value, to_value）。

async fn exec_server_accepts_binary_websocket_json() -> anyhow::Result<()>

作用：这个测试确认服务器不只接受普通文本 WebSocket 消息，也能接受二进制 WebSocket 消息里的 JSON-RPC 请求。这样客户端用不同帧类型发送同一份 JSON 时，服务器不会误拒绝。

数据流：测试先启动临时 exec-server，手动组装一个 initialize JSON-RPC 请求，里面包含请求 id、方法名 initialize 和初始化参数。然后它把这条请求序列化成字节数组，也就是二进制数据，通过 WebSocket 发给服务器。服务器返回响应后，测试检查响应 id 和原请求 id 一样，再把 result 解析成 InitializeResponse，并验证 session_id 是合法 UUID。最后关闭服务器。

调用关系：它位于 WebSocket 输入兼容性的测试环节。它同样依赖 exec_server 测试工具拉起服务器，但这次不走普通请求封装，而是自己构造 JSONRPCMessage::Request，再交给原始二进制发送接口，最后等待对应 id 的响应来证明这条通路是通的。

调用图：调用 1 个内部函数（exec_server）；外部调用 8 个（parse_str, Request, Integer, assert_eq!, panic!, from_value, to_value, to_vec）。

async fn exec_server_rejects_browser_origin_websocket_handshake() -> anyhow::Result<()>

作用：这个测试确认带有浏览器网页来源 Origin 的 WebSocket 握手会被拒绝。它是在防止恶意网页偷偷连到本机 exec-server。

数据流：测试先启动临时 exec-server，拿到它的 WebSocket 地址，并构造一个连接请求。然后它往请求头里塞入 Origin: https://evil.example，模拟一个网页从外部站点发起连接。测试尝试连接服务器：如果连接成功就立刻报错；如果失败，则要求失败原因是 HTTP 响应，并检查状态码是 403 Forbidden。最后关闭服务器。

调用关系：它是安全边界测试的一部分。它通过 exec_server 启动真实测试服务器，再直接调用 connect_async 发起 WebSocket 握手，而不是使用已封装好的服务器客户端；这样可以精确控制 Origin 请求头，验证服务器在握手阶段就把这类连接挡住。

调用图：调用 1 个内部函数（exec_server）；外部调用 4 个（from_static, bail!, assert_eq!, connect_async）。

fn exec_params(process_id: &str) -> ExecParams

作用：给测试快速做一份“启动进程”的参数，默认启动一个很短时间就结束的睡眠命令。测试不关心具体命令时，就用它省事。

数据流：进去一个进程编号字符串 → 它先向 sleep_argv 要到适合当前系统的睡眠命令，再交给 exec_params_with_argv 组装完整启动参数 → 出来一份 ExecParams，里面带着进程编号、命令、当前目录和环境变量。

调用关系：它是更省心的包装函数。terminate_reports_false_after_process_exit 和 output_and_exit_are_retained_after_notification_receiver_closes 会用它启动默认短命令；它自己把具体组装工作交给 exec_params_with_argv 和 sleep_argv。

调用图：调用 2 个内部函数（exec_params_with_argv, sleep_argv）；被 2 处调用（output_and_exit_are_retained_after_notification_receiver_closes, terminate_reports_false_after_process_exit）。

fn exec_params_with_argv(process_id: &str, argv: Vec<String>) -> ExecParams

作用：把“进程编号”和“要执行的命令参数”包装成服务器能看懂的启动请求。需要测试不同命令时，会直接用它。

数据流：进去一个进程编号和一组命令参数 → 它把编号转成 ProcessId，把当前工作目录转成路径 URI（一种能在协议里传输的路径写法），再只继承 PATH 环境变量 → 出来一份完整 ExecParams，并明确关闭伪终端和标准输入管道。

调用关系：exec_params 会调用它生成默认参数；long_poll_read_fails_after_session_resume 和 output_and_exit_are_retained_after_notification_receiver_closes 会直接调用它，传入自己定制的命令脚本。它还依赖 inherited_path_env 准备环境变量。

调用图：调用 3 个内部函数（from, inherited_path_env, from_path）；被 3 处调用（exec_params, long_poll_read_fails_after_session_resume, output_and_exit_are_retained_after_notification_receiver_closes）；外部调用 1 个（current_dir）。

fn inherited_path_env() -> HashMap<String, String>

作用：只从当前测试进程里继承 PATH 环境变量。PATH 是系统用来找可执行程序的搜索路径，保留它可以让 shell、cmd 等命令更容易被找到。

数据流：它不接收参数 → 它新建一个环境变量表，查看系统里有没有 PATH，如果有就放进去 → 出来一个 HashMap，也就是键值表，最多包含 PATH 这一项。

调用关系：它只服务于 exec_params_with_argv。这样测试启动子进程时环境尽量干净，但仍保留找到系统命令所需的最基本信息。

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

fn sleep_argv() -> Vec<String>

作用：生成一个“短暂等待后退出”的命令参数列表，用来做不需要复杂输出的测试进程。

数据流：它不接收参数 → 它准备 Unix 和 Windows 两套等价脚本，再交给 shell_argv 按当前系统选择 → 出来一组可以传给服务器执行的命令参数。

调用关系：exec_params 会调用它。它不直接关心操作系统差异，而是把这件事交给 shell_argv。

调用图：调用 1 个内部函数（shell_argv）；被 1 处调用（exec_params）。

fn shell_argv(unix_script: &str, windows_script: &str) -> Vec<String>

作用：把一段 Unix 脚本或 Windows 脚本变成当前系统能执行的命令参数。这样同一套测试可以在不同操作系统上跑。

数据流：进去两段脚本：一段给 Unix/Linux/macOS 的 /bin/sh，一段给 Windows 的命令处理器 → 它判断当前是不是 Windows → 出来一组参数：Windows 下类似 cmd /C xxx，非 Windows 下类似 /bin/sh -c xxx。

调用关系：sleep_argv 用它生成默认睡眠命令；long_poll_read_fails_after_session_resume 和 output_and_exit_are_retained_after_notification_receiver_closes 用它生成更特殊的测试脚本。它是这些跨平台测试命令的转换器。

调用图：被 3 处调用（long_poll_read_fails_after_session_resume, output_and_exit_are_retained_after_notification_receiver_closes, sleep_argv）；外部调用 2 个（cfg!, vec!）。

fn windows_command_processor() -> String

作用：找出 Windows 上应该用哪个命令解释器来跑脚本。通俗说，就是找“打开命令行并执行这段话”的程序。

数据流：它不接收参数 → 它读取 COMSPEC 环境变量；如果读不到，就用 cmd.exe 当默认值 → 出来一个命令处理器名称或路径。

调用关系：它是 Windows 命令构造时的小帮手。在这个文件的意图里，它配合 shell_argv 让 Windows 测试也能执行脚本。

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

fn test_runtime_paths() -> ExecServerRuntimePaths

作用：为测试准备服务器运行时需要知道的程序路径。没有这些路径，ExecServerHandler 可能不知道当前可执行文件在哪里。

数据流：它不接收参数 → 它读取当前正在运行的测试可执行文件路径，并把 Linux 沙箱程序路径设为空 → 出来一份 ExecServerRuntimePaths，供测试里的服务器处理器使用。

调用关系：initialized_handler、long_poll_read_fails_after_session_resume、active_session_resume_is_rejected 和 output_and_exit_are_retained_after_notification_receiver_closes 都会用它创建测试用 handler。它把路径准备这件重复活集中在一个地方。

调用图：调用 1 个内部函数（new）；被 4 处调用（active_session_resume_is_rejected, initialized_handler, long_poll_read_fails_after_session_resume, output_and_exit_are_retained_after_notification_receiver_closes）；外部调用 1 个（current_exe）。

async fn initialized_handler() -> Arc<ExecServerHandler>

作用：快速创建一个已经完成初始化的测试服务器处理器。很多测试只想验证后续行为，不想每次都手写初始化步骤。

数据流：它不接收参数 → 它创建通知通道、会话登记表和 ExecServerHandler，再调用 initialize 建立会话，检查返回的会话编号确实是 UUID（一种标准随机唯一编号），最后调用 initialized 标记初始化完成 → 出来一个可共享的 Arc<ExecServerHandler>。Arc 可以理解成多人共用同一个对象的安全引用。

调用关系：duplicate_process_ids_allow_only_one_successful_start 和 terminate_reports_false_after_process_exit 用它拿到现成 handler。它内部会调用 test_runtime_paths，并创建 SessionRegistry 和 RpcNotificationSender。

调用图：调用 4 个内部函数（new, new, test_runtime_paths, new）；被 2 处调用（duplicate_process_ids_allow_only_one_successful_start, terminate_reports_false_after_process_exit）；外部调用 3 个（new, parse_str, channel）。

async fn duplicate_process_ids_allow_only_one_successful_start()

作用：测试两个请求同时用同一个进程编号启动进程时，服务器只允许一个成功。这样可以避免同一个编号背后对应两个真实进程，后面读取和终止都会乱套。

数据流：进去的是测试框架自动启动的异步测试环境 → 它先拿到初始化好的 handler，再复制两个共享引用，同时发起两个 exec 请求，进程编号都叫 proc-1 → 出来是断言结果：一个成功、一个失败，失败错误码是 -32600，错误信息说明进程已存在，最后等待一下并关闭 handler。

调用关系：这是一个顶层测试，由测试框架调用。它使用 initialized_handler 搭环境，用 exec_params 准备请求，并通过 tokio::join 同时发起两次启动，专门检查并发下的去重保护。

调用图：调用 1 个内部函数（initialized_handler）；外部调用 5 个（clone, from_millis, assert_eq!, join!, sleep）。

async fn terminate_reports_false_after_process_exit()

作用：测试进程自然退出后，再请求终止它时，服务器会回答 running: false。也就是说，它不会假装已经退出的进程还在跑。

数据流：测试开始 → 它创建 handler，启动一个短命进程，然后在最多 1 秒内反复调用 terminate；如果返回 running: false 就通过，否则每隔 25 毫秒再试 → 最后关闭 handler。

调用关系：这是测试框架直接运行的异步测试。它借 initialized_handler 和 exec_params 做准备，然后重点调用 handler.terminate，验证终止接口在“进程已经结束”这个边界情况上的说法是否准确。

调用图：调用 3 个内部函数（from, exec_params, initialized_handler）；外部调用 5 个（from_millis, from_secs, assert!, now, sleep）。

async fn long_poll_read_fails_after_session_resume()

作用：测试旧连接正在长时间等待读取输出时，如果会话被新连接恢复接管，旧连接的等待请求必须失败。这样可以避免一个会话同时有两个连接都以为自己还有效。

数据流：测试开始 → 它创建第一个 handler 并初始化会话，启动一个安静但存活较久的进程，然后开一个后台任务执行 exec_read，并设置 wait_ms 让它长轮询等待；接着关闭第一个 handler，再用同一个会话编号创建第二个 handler 恢复会话 → 后台读取任务返回错误，错误信息说明会话已被另一个连接恢复，最后关闭第二个 handler。

调用关系：这是一个完整的断线重连场景测试。它直接创建 SessionRegistry，让两个 handler 共享同一个会话登记表；它用 exec_params_with_argv 和 shell_argv 准备一个不会马上输出的命令，让读取请求只能因为会话接管而结束，而不是因为进程自己输出或退出。

调用图：调用 7 个内部函数（from, new, new, exec_params_with_argv, shell_argv, test_runtime_paths, new）；外部调用 7 个（clone, new, from_millis, assert_eq!, channel, spawn, sleep）。

async fn active_session_resume_is_rejected()

作用：测试一个仍然活跃的会话不能被第二个连接恢复。这样可以防止两个客户端同时控制同一个会话，造成命令和输出归属混乱。

数据流：测试开始 → 它创建第一个 handler 并初始化出一个会话编号，但不调用 initialized 完成接管后的释放；然后创建第二个 handler，尝试用同一个会话编号恢复 → 出来的是一个错误，错误码为 -32600，消息说明该会话已连接到另一个连接，最后关闭第一个 handler。

调用关系：这是会话登记表规则的测试。它让两个 handler 共用同一个 SessionRegistry，并通过第二次 initialize 触发冲突，确认服务器会拒绝恢复仍被占用的会话。

调用图：调用 4 个内部函数（new, new, test_runtime_paths, new）；外部调用 4 个（clone, new, assert_eq!, channel）。

async fn output_and_exit_are_retained_after_notification_receiver_closes()

作用：测试通知接收端关闭后，服务器仍然保存进程输出和退出码。通知失败不应该导致用户之后读不到已经发生的结果。

数据流：测试开始 → 它创建 handler 和通知通道，启动一个会打印 first、second 并正常退出的进程；随后故意丢掉通知接收端，模拟通知发不出去 → 它通过 read_process_until_closed 主动读取，确认输出完整、退出码是 0；再等一会儿，用同一个进程编号启动新进程，确认旧记录清理后编号可以复用，最后关闭 handler。

调用关系：这是通知失败场景的测试。它用 exec_params_with_argv 和 shell_argv 制造可验证输出，用 read_process_until_closed 读取直到关闭，再用 exec_params 检查进程编号复用。

调用图：调用 9 个内部函数（from, new, new, exec_params, exec_params_with_argv, read_process_until_closed, shell_argv, test_runtime_paths, new）；外部调用 5 个（new, from_millis, assert_eq!, channel, sleep）。

async fn read_process_until_closed(
    handler: &ExecServerHandler,
    process_id: ProcessId,
) -> (String, Option<i32>)

作用：反复读取某个进程的输出，直到服务器告诉它这个进程的输出流已经关闭。它是测试里的小读者，负责把分批到来的输出拼成完整文本。

数据流：进去一个 handler 引用和进程编号 → 它设置 5 秒截止时间，从 after_seq 为空开始调用 exec_read；每次拿到若干输出块，就按顺序追加到字符串，并记录最新序号；如果响应说进程已退出，就保存退出码；如果响应说已关闭，就返回完整输出和退出码 → 如果太久没关闭，就触发测试失败。

调用关系：output_and_exit_are_retained_after_notification_receiver_closes 调用它来验证输出没有丢。它直接把活交给 handler.exec_read，并用返回的序号继续追读下一批内容。

调用图：调用 1 个内部函数（exec_read）；被 1 处调用（output_and_exit_are_retained_after_notification_receiver_closes）；外部调用 6 个（from_secs, from_utf8_lossy, new, assert!, clone, now）。

async fn exec_server_starts_process_over_websocket() -> anyhow::Result<()>

作用：这个测试确认：客户端通过 WebSocket 发起 process/start 请求后，exec-server 能真的启动一个进程，并把正确的进程编号回给客户端。它用最简单的 true 命令当样例，因为这个命令几乎不会出错，适合验证“启动流程本身”。

数据流：测试先启动一个测试用服务器，再发送 initialize 初始化请求，并等待服务器回话。接着发送 initialized 通知，表示客户端准备好了。然后它发送 process/start，内容里带着进程编号 proc-1、要运行的命令 true、当前目录、环境变量等。服务器返回一条 JSON-RPC 响应后，测试把响应里的 JSON 转成 ExecResponse，再检查返回的 process_id 是否正好是 proc-1。最后关闭测试服务器。

调用关系：它在测试流程中扮演最基础的冒烟测试：先通过 exec_server 搭好一台真实可通信的测试服务器，再用 to_value 和 json! 拼请求，用 from_value 解读返回结果，用 assert_eq! 判断服务器有没有按约定回答。如果返回消息类型不对，就用 panic! 直接让测试失败。

调用图：调用 1 个内部函数（exec_server）；外部调用 5 个（assert_eq!, panic!, from_value, json!, to_value）。

async fn exec_server_defaults_omitted_pipe_stdin_to_closed_stdin() -> anyhow::Result<()>

作用：这个测试确认：如果启动进程时没有写 pipeStdin 这个参数，服务器会把标准输入默认当作关闭，而不是默认保持可写。这样可以避免客户端误以为还能往进程里塞输入，导致行为不清楚。

数据流：测试先启动服务器并完成初始化。然后它启动一个 shell 脚本进程，这个脚本会等一下，再尝试从标准输入读一行；如果读不到，就输出 eof。启动请求里故意省略 pipeStdin。服务器确认进程启动后，测试又发送 process/write，试图往这个进程写入一段 base64 编码的内容。服务器返回写入结果后，测试把 JSON 转成 WriteResponse，并检查状态必须是 StdinClosed，意思是标准输入已经关闭，写不进去。最后关闭服务器。

调用关系：它接在初始化和进程启动这条主流程之后，专门验证一个容易被忽略的默认值。它通过 exec_server 建立测试环境，用 json! 构造少了 pipeStdin 的请求，用 from_value 读取服务器回答，再用 assert_eq! 确认默认行为符合约定。如果服务器没有返回预期的 JSON-RPC 响应，就用 panic! 标记测试失败。

调用图：调用 1 个内部函数（exec_server）；外部调用 5 个（assert_eq!, panic!, from_value, json!, to_value）。

async fn exec_server_resumes_detached_session_without_killing_processes() -> anyhow::Result<()>

作用：这个测试确认：客户端 WebSocket 断开后，如果用原来的会话编号重新连接，之前启动的进程不会被服务器误杀。它验证的是“断线重连后进程还活着”这个很关键的稳定性场景。

数据流：测试先启动服务器并初始化，保存服务器返回的 session_id，也就是这次会话的身份号码。随后它启动一个会睡眠 5 秒的 shell 进程 proc-resume，让这个进程保持运行。接着测试主动断开 WebSocket，再重新连接，并用之前保存的 session_id 再次发送 initialize，表示要恢复旧会话。服务器返回的初始化结果必须和第一次一样。恢复完成后，测试读取 proc-resume 的状态，确认没有失败、没有退出、也没有关闭。最后它发送 process/terminate 终止这个进程，并确认服务器认为该进程当时仍在运行，然后关闭测试服务器。

调用关系：它是这个文件里最完整的一条端到端测试：从 exec_server 建立服务器开始，经历初始化、启动进程、断线、重连、恢复会话、读取进程状态、终止进程。它用 to_value 和 json! 准备请求，用 from_value 解析 InitializeResponse、ReadResponse、TerminateResponse，再用 assert_eq! 和 assert! 检查关键事实。如果某一步收到的不是预期响应，就用 panic! 让问题暴露出来。

调用图：调用 1 个内部函数（exec_server）；外部调用 6 个（assert!, assert_eq!, panic!, from_value, json!, to_value）。

async fn create_process_context(use_remote: bool) -> Result<ProcessContext>

作用：创建测试用的执行环境。它会按参数决定是直接在本机跑命令，还是先启动一个真正的远程 exec-server 再通过网络连过去。

数据流：进去的是 use_remote 这个开关 → 如果为真，就启动测试服务器并把服务器地址交给测试环境；如果为假，就创建不带远程地址的本地环境 → 出来的是 ProcessContext，里面有统一的执行后端，远程模式下还保存服务器句柄，方便后面关掉它。

调用关系：几乎所有测试辅助函数一开始都会调用它，因为后续测试不关心命令到底是在本地跑还是通过服务器跑。它把环境准备好后，具体启动进程的活交给 backend.start。

调用图：调用 2 个内部函数（create_for_tests, exec_server）；被 12 处调用（assert_exec_process_preserves_queued_events_before_subscribe, assert_exec_process_pushes_events, assert_exec_process_rejects_write_without_pipe_stdin, assert_exec_process_replays_events_after_close, assert_exec_process_retains_output_after_exit_until_streams_close, assert_exec_process_signal_interrupts_process, assert_exec_process_signal_reports_unsupported_on_windows, assert_exec_process_starts_and_exits, assert_exec_process_streams_output, assert_exec_process_write_then_read (+2 more)）。

async fn assert_exec_process_starts_and_exits(use_remote: bool) -> Result<()>

作用：确认最基本的事情：一个进程能启动，并且能正常退出。这里用 true 命令，因为它什么都不做，只会成功退出。

数据流：进去的是是否远程执行的开关 → 它创建环境，启动 process_id 为 proc-1 的 true 命令，再持续读取进程状态 → 出来没有业务结果，但会断言退出码是 0，并且会话已经关闭；不符合就让测试失败。

调用关系：这是 exec_process_starts_and_exits 这个测试入口真正干活的部分。它依赖 create_process_context 准备环境，并把读到结束的工作交给 collect_process_output_from_reads。

调用图：调用 4 个内部函数（from, collect_process_output_from_reads, create_process_context, from_path）；被 1 处调用（exec_process_starts_and_exits）；外部调用 5 个（default, assert!, assert_eq!, current_dir, vec!）。

async fn read_process_until_change(
    session: Arc<dyn ExecProcess>,
    wake_rx: &mut watch::Receiver<u64>,
    after_seq: Option<u64>,
) -> Result<ReadResponse>

作用：读取一次进程状态；如果暂时没新内容，就等到进程通知“有变化了”再读。它避免测试因为太早读取而误以为什么都没有。

数据流：进去的是一个进程会话、一个唤醒通知接收器，以及从哪个序号之后开始读 → 它先立即读一次；如果没有输出、没关闭、没失败，就最多等 2 秒等变化通知，再读一次 → 出来是一份 ReadResponse，里面可能有新输出、退出信息、关闭状态或失败信息。

调用关系：它是读取类测试的底层小工具。collect_process_output_from_reads 用它循环等输出；信号测试用它等到进程打印 ready；断线测试也用它确认断线错误能被读出来。

调用图：被 3 处调用（assert_exec_process_signal_interrupts_process, collect_process_output_from_reads, remote_exec_process_reports_transport_disconnect）；外部调用 3 个（from_secs, changed, timeout）。

async fn collect_process_output_from_reads(
    session: Arc<dyn ExecProcess>,
    mut wake_rx: watch::Receiver<u64>,
) -> Result<(String, Option<i32>, bool)>

作用：用“主动读取”的方式，把一个进程从开始到关闭期间的输出和退出码收集完整。可以把它理解成一直翻收件箱，直到看到“这封邮件结束了”。

数据流：进去的是进程会话和唤醒通知 → 它反复调用 read_process_until_change，把每个输出块转成文字拼起来，记录退出码，遇到失败就报错，直到 closed 为真 → 出来的是三样东西：完整输出文字、可选退出码、以及表示已关闭的布尔值。

调用关系：很多断言函数都用它做最后验收，比如启动退出、输出流、stdin 写入、信号中断、排队事件等。它自己不启动进程，只负责把已经启动的进程读到结束。

调用图：调用 1 个内部函数（read_process_until_change）；被 9 处调用（assert_exec_process_preserves_queued_events_before_subscribe, assert_exec_process_rejects_write_without_pipe_stdin, assert_exec_process_replays_events_after_close, assert_exec_process_retains_output_after_exit_until_streams_close, assert_exec_process_signal_interrupts_process, assert_exec_process_starts_and_exits, assert_exec_process_streams_output, assert_exec_process_write_then_read, assert_exec_process_write_then_read_without_tty）；外部调用 4 个（clone, from_utf8_lossy, new, bail!）。

async fn collect_process_output_from_events(
    session: Arc<dyn ExecProcess>,
) -> Result<(String, String, Option<i32>, bool)>

作用：用“事件订阅”的方式收集进程输出。事件订阅就像订阅快递通知：有 stdout、stderr、退出、关闭等消息会主动推过来。

数据流：进去的是进程会话 → 它订阅事件通道，最多每次等 2 秒，按事件类型把 stdout 和 stderr 分开累加，记录退出码，遇到关闭就返回，遇到失败就报错 → 出来的是 stdout 文本、stderr 文本、退出码和关闭标记。

调用关系：它主要服务于“进程关闭后还能重放事件”的测试。该测试先用读取接口读完，再用它确认事件接口也能拿到同样的历史输出。

调用图：被 1 处调用（assert_exec_process_replays_events_after_close）；外部调用 5 个（from_secs, from_utf8_lossy, new, bail!, timeout）。

async fn collect_process_event_snapshots(
    session: Arc<dyn ExecProcess>,
) -> Result<Vec<ProcessEventSnapshot>>

作用：把进程推送出来的事件按顺序拍成快照，方便精确比较事件顺序和序号。它关心的不只是内容，还有先后顺序。

数据流：进去的是进程会话 → 它订阅事件，把输出事件、退出事件、关闭事件转换成 ProcessEventSnapshot；遇到失败就报错；遇到关闭就停止 → 出来是一串事件快照列表。

调用关系：它被 assert_exec_process_pushes_events 使用，用来确认 stdout、stderr、退出、关闭这几类事件按预期顺序出现，并且序号连续。

调用图：被 1 处调用（assert_exec_process_pushes_events）；外部调用 6 个（from_secs, from_utf8_lossy, new, bail!, matches!, timeout）。

async fn assert_exec_process_streams_output(use_remote: bool) -> Result<()>

作用：确认进程运行时产生的标准输出能被读取出来。这里让 shell 稍微等一下再打印一句话，模拟真实程序边跑边输出。

数据流：进去的是本地或远程开关 → 它创建环境，启动一个会打印 session output 的 shell 命令，然后通过读取接口收集输出 → 出来通过断言确认输出文字完全匹配、退出码为 0、进程已关闭。

调用关系：它是 exec_process_streams_output 测试入口背后的实际检查逻辑。它依赖 create_process_context 启动环境，依赖 collect_process_output_from_reads 收尾。

调用图：调用 3 个内部函数（collect_process_output_from_reads, create_process_context, from_path）；被 1 处调用（exec_process_streams_output）；外部调用 5 个（default, assert!, assert_eq!, current_dir, vec!）。

async fn assert_exec_process_pushes_events(use_remote: bool) -> Result<()>

作用：确认进程的输出和退出信息会以事件形式推送出来，而且 stdout、stderr、退出、关闭的顺序正确。

数据流：进去的是本地或远程开关 → 它启动一个先打印 stdout、再打印 stderr、最后以退出码 7 结束的 shell 命令 → 出来是一组事件快照，并断言它们正好是预期的四个事件。

调用关系：它由 exec_process_pushes_events 调用。它把环境准备交给 create_process_context，把事件收集交给 collect_process_event_snapshots。

调用图：调用 3 个内部函数（collect_process_event_snapshots, create_process_context, from_path）；被 1 处调用（exec_process_pushes_events）；外部调用 4 个（default, assert_eq!, current_dir, vec!）。

async fn assert_exec_process_replays_events_after_close(use_remote: bool) -> Result<()>

作用：确认进程结束后，后来才订阅事件的人也能拿到已经发生过的输出。也就是说，消息不会因为订阅晚了就丢掉。

数据流：进去的是本地或远程开关 → 它启动一个快速打印两行后退出的进程，先用读取接口读到结束，再改用事件接口收集历史事件 → 出来通过断言确认两种方式看到的输出和退出码一致。

调用关系：它由 exec_process_replays_events_after_close 这个测试入口调用。它同时使用 collect_process_output_from_reads 和 collect_process_output_from_events，专门比较“拉取读取”和“事件订阅”两条路径。

调用图：调用 4 个内部函数（collect_process_output_from_events, collect_process_output_from_reads, create_process_context, from_path）；被 1 处调用（exec_process_replays_events_after_close）；外部调用 5 个（clone, default, assert_eq!, current_dir, vec!）。

async fn assert_exec_process_retains_output_after_exit_until_streams_close(
    use_remote: bool,
) -> Result<()>

作用：测试一个很容易漏的情况：父进程已经退出了，但它留下的子进程稍后还会往输出流写字。系统必须等输出流真的关了，不能只看父进程退出就把会话关掉。

数据流：进去的是本地或远程开关 → 它启动一个测试辅助程序，让父进程先退出，子进程等文件信号再输出；先读到退出码但未关闭，再写入释放文件让晚到输出出现 → 出来断言晚到文字被完整读到，最后退出码仍是 0，进程会话关闭。

调用关系：它由 exec_process_retains_output_after_exit_until_streams_close 调用。它需要 current_test_binary_helper_paths 找到测试辅助二进制，并用 collect_process_output_from_reads 做最终完整读取。

调用图：调用 4 个内部函数（current_test_binary_helper_paths, collect_process_output_from_reads, create_process_context, from_path）；被 1 处调用（exec_process_retains_output_after_exit_until_streams_close）；外部调用 11 个（default, from_secs, from_utf8_lossy, new, new, assert!, assert_eq!, current_dir, write, timeout (+1 more)）。

async fn assert_exec_process_write_then_read(use_remote: bool) -> Result<()>

作用：确认带伪终端的进程可以接收输入，再把处理结果输出回来。伪终端可以理解成给程序装了一个像真人键盘和屏幕一样的交互环境。

数据流：进去的是本地或远程开关 → 它启动一个 shell，等待从 stdin 读一行；测试稍等后写入 hello 换行，再读取所有输出 → 出来断言输出里包含 from-stdin:hello，退出码为 0，并且已关闭。

调用关系：它由 exec_process_write_then_read 测试入口调用。它先直接调用进程的 write 写输入，再用 collect_process_output_from_reads 验证结果。

调用图：调用 3 个内部函数（collect_process_output_from_reads, create_process_context, from_path）；被 1 处调用（exec_process_write_then_read）；外部调用 7 个（default, from_millis, assert!, assert_eq!, current_dir, sleep, vec!）。

async fn assert_exec_process_write_then_read_without_tty(use_remote: bool) -> Result<()>

作用：确认不使用伪终端时，只要打开了 pipe_stdin，也能通过普通管道给进程写输入。管道就是一根程序之间传字节的“水管”。

数据流：进去的是本地或远程开关 → 它启动一个从 stdin 读一行的 shell，并设置 pipe_stdin 为真；随后写入 hello 换行 → 出来断言写入被接受，读到 from-stdin:hello，退出码为 0，进程关闭。

调用关系：它由 exec_process_write_then_read_without_tty 调用。它验证的是 write 接口在非 TTY 模式下的另一条输入路径，最后仍交给 collect_process_output_from_reads 收集结果。

调用图：调用 3 个内部函数（collect_process_output_from_reads, create_process_context, from_path）；被 1 处调用（exec_process_write_then_read_without_tty）；外部调用 6 个（default, from_millis, assert_eq!, current_dir, sleep, vec!）。

async fn assert_exec_process_rejects_write_without_pipe_stdin(use_remote: bool) -> Result<()>

作用：确认如果进程没有打开 stdin 管道，往里面写东西会被明确拒绝，而不是悄悄吞掉或卡住。

数据流：进去的是本地或远程开关 → 它启动一个尝试读取 stdin 的 shell，但设置 tty 为假、pipe_stdin 也为假；测试调用 write → 出来断言写入状态是 StdinClosed，并且进程自己读到的是 eof，正常退出。

调用关系：它由 exec_process_rejects_write_without_pipe_stdin 调用。它先检查 write 的返回状态，再用 collect_process_output_from_reads 确认进程看到的确实是输入结束。

调用图：调用 3 个内部函数（collect_process_output_from_reads, create_process_context, from_path）；被 1 处调用（exec_process_rejects_write_without_pipe_stdin）；外部调用 5 个（default, assert!, assert_eq!, current_dir, vec!）。

async fn assert_exec_process_signal_interrupts_process(use_remote: bool) -> Result<()>

作用：确认可以给正在运行的进程发送中断信号。中断信号可以理解成按下 Ctrl+C，请程序停下来或执行自己的收尾逻辑。

数据流：进去的是本地或远程开关 → 它启动一个无限循环的 shell，并让 shell 收到 INT 时打印 signal:2 后以 7 退出；测试先等到 ready，再发送 Interrupt → 出来断言输出包含 signal:2，退出码是 7，进程关闭。

调用关系：它由 exec_process_signal_interrupts_process 调用。它用 read_process_until_change 等待进程准备好，发送 signal 后用 collect_process_output_from_reads 收集剩余输出和退出状态。

调用图：调用 4 个内部函数（collect_process_output_from_reads, create_process_context, read_process_until_change, from_path）；被 1 处调用（exec_process_signal_interrupts_process）；外部调用 9 个（clone, default, from_utf8_lossy, new, bail!, assert!, assert_eq!, current_dir, vec!）。

async fn assert_exec_process_signal_reports_unsupported_on_windows(use_remote: bool) -> Result<()>

作用：确认 Windows 上某些不支持的中断方式会清楚报错。测试要的不是成功中断，而是错误信息必须明确。

数据流：进去的是本地或远程开关 → 它启动一个 Windows cmd 命令，然后尝试发送 Interrupt → 出来如果意外成功就让测试失败；如果失败，则检查错误文字包含“发送失败”和“不支持”的说明，最后主动终止进程。

调用关系：它由 exec_process_signal_reports_unsupported_on_windows 调用，只在 Windows 测试条件下运行。它复用 create_process_context 建环境，但主要验证 signal 接口的错误路径。

调用图：调用 3 个内部函数（from, create_process_context, from_path）；被 1 处调用（exec_process_signal_reports_unsupported_on_windows）；外部调用 5 个（default, bail!, assert!, current_dir, vec!）。

async fn assert_exec_process_preserves_queued_events_before_subscribe(
    use_remote: bool,
) -> Result<()>

作用：确认进程很快输出并结束时，测试稍晚才开始读取也不会丢掉已经排队的输出。

数据流：进去的是本地或远程开关 → 它启动一个马上打印 queued output 的 shell，故意等 200 毫秒再订阅唤醒和读取 → 出来断言仍能读到完整输出、退出码为 0、会话关闭。

调用关系：它由 exec_process_preserves_queued_events_before_subscribe 调用。它专门覆盖“先发生、后订阅”的场景，最终靠 collect_process_output_from_reads 验证缓存没有丢。

调用图：调用 4 个内部函数（from, collect_process_output_from_reads, create_process_context, from_path）；被 1 处调用（exec_process_preserves_queued_events_before_subscribe）；外部调用 7 个（default, from_millis, assert!, assert_eq!, current_dir, sleep, vec!）。

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

作用：测试远程 exec-server 连接断开时，进程会话会把这个坏消息通知所有相关方。不能让读操作一直傻等，也不能让写操作假装成功。

数据流：进去没有业务参数，由测试框架直接运行 → 它启动远程服务器和一个长时间 sleep 的进程，同时挂起一次长读；随后关掉服务器 → 出来断言事件通道收到 Failed，挂起的 read 返回失败，新的 read 也显示失败且关闭，之后 write 也返回断线错误。

调用关系：这是一个完整的远程断线测试入口，不通过额外包装函数。它调用 create_process_context 建远程环境，用 read_process_until_change 检查断线后的读取状态，并直接操作测试服务器的 shutdown。

调用图：调用 4 个内部函数（from, create_process_context, read_process_until_change, from_path）；外部调用 9 个（clone, default, from_secs, bail!, assert!, current_dir, spawn, timeout, vec!）。

async fn exec_process_starts_and_exits(use_remote: bool) -> Result<()>

作用：这是测试框架会直接运行的入口，用来覆盖“进程能启动并退出”这个基础场景。

数据流：进去的是 test_case 提供的 use_remote 参数 → 它不自己写细节，只调用 assert_exec_process_starts_and_exits → 出来是测试成功或失败的 Result。

调用关系：它是外层测试壳，负责把本地和远程两种参数送进真正的检查函数 assert_exec_process_starts_and_exits。

调用图：调用 1 个内部函数（assert_exec_process_starts_and_exits）。

async fn exec_process_streams_output(use_remote: bool) -> Result<()>

作用：这是测试框架入口，用来确认进程运行时输出能被流式读到。

数据流：进去的是 use_remote 参数 → 它调用 assert_exec_process_streams_output 完成实际启动、读取和断言 → 出来是测试结果。

调用关系：它本身只做分发，真实逻辑在 assert_exec_process_streams_output 中。test_case 会让它分别跑本地和远程两遍。

调用图：调用 1 个内部函数（assert_exec_process_streams_output）。

async fn exec_process_pushes_events(use_remote: bool) -> Result<()>

作用：这是测试入口，用来确认进程输出、错误输出、退出和关闭都会按事件推送。

数据流：进去的是 use_remote 参数 → 它交给 assert_exec_process_pushes_events → 出来是测试成功或失败。

调用关系：它连接测试框架和具体断言函数，让同一套事件检查覆盖本地后端和远程后端。

调用图：调用 1 个内部函数（assert_exec_process_pushes_events）。

async fn exec_process_replays_events_after_close(use_remote: bool) -> Result<()>

作用：这是测试入口，用来确认进程结束后再订阅事件，也能看到历史输出。

数据流：进去的是 use_remote 参数 → 它调用 assert_exec_process_replays_events_after_close → 出来是 Result，失败时说明事件重放机制有问题。

调用关系：它只是外层包装，实际比较读取接口和事件接口的工作由 assert_exec_process_replays_events_after_close 完成。

调用图：调用 1 个内部函数（assert_exec_process_replays_events_after_close）。

async fn exec_process_retains_output_after_exit_until_streams_close(
    use_remote: bool,
) -> Result<()>

作用：这是测试入口，用来确认父进程退出后，晚到的输出仍会被保留到输出流真正关闭。

数据流：进去的是 use_remote 参数 → 它调用同名 assert 辅助函数执行复杂场景 → 出来是测试结果。

调用关系：它把测试框架的本地/远程参数传给 assert_exec_process_retains_output_after_exit_until_streams_close，后者负责启动辅助程序和验证晚到输出。

调用图：调用 1 个内部函数（assert_exec_process_retains_output_after_exit_until_streams_close）。

async fn exec_process_write_then_read(use_remote: bool) -> Result<()>

作用：这是测试入口，用来验证带伪终端的进程可以写入输入并读回响应。

数据流：进去的是 use_remote 参数 → 它调用 assert_exec_process_write_then_read → 出来是 Result。

调用关系：它是测试壳，真正的写 stdin、读 stdout 和断言都在 assert_exec_process_write_then_read 中。

调用图：调用 1 个内部函数（assert_exec_process_write_then_read）。

async fn exec_process_write_then_read_without_tty(use_remote: bool) -> Result<()>

作用：这是测试入口，用来验证没有伪终端时，通过 stdin 管道也能写入进程。

数据流：进去的是 use_remote 参数 → 它调用 assert_exec_process_write_then_read_without_tty → 出来是测试结果。

调用关系：它把本地和远程两种执行方式送进同一个管道输入测试，具体逻辑由 assert_exec_process_write_then_read_without_tty 执行。

调用图：调用 1 个内部函数（assert_exec_process_write_then_read_without_tty）。

async fn exec_process_rejects_write_without_pipe_stdin(use_remote: bool) -> Result<()>

作用：这是测试入口，用来验证未打开 stdin 管道时，写入会被拒绝。

数据流：进去的是 use_remote 参数 → 它调用 assert_exec_process_rejects_write_without_pipe_stdin → 出来是 Result。

调用关系：它只是触发具体检查；实际验证 WriteStatus::StdinClosed 和进程输出 eof 的工作在 assert_exec_process_rejects_write_without_pipe_stdin 中。

调用图：调用 1 个内部函数（assert_exec_process_rejects_write_without_pipe_stdin）。

async fn exec_process_signal_interrupts_process(use_remote: bool) -> Result<()>

作用：这是测试入口，用来验证 Unix 类系统上中断信号能传到进程。

数据流：进去的是 use_remote 参数 → 它调用 assert_exec_process_signal_interrupts_process → 出来是测试成功或失败。

调用关系：它在 Unix 条件下运行，并把参数交给真正的信号测试函数。实际等待 ready、发送 Interrupt、检查退出码都由 assert_exec_process_signal_interrupts_process 完成。

调用图：调用 1 个内部函数（assert_exec_process_signal_interrupts_process）。

async fn exec_process_signal_reports_unsupported_on_windows(use_remote: bool) -> Result<()>

作用：这是 Windows 专用测试入口，用来验证不支持的进程中断会明确报错。

数据流：进去的是 use_remote 参数 → 它调用 assert_exec_process_signal_reports_unsupported_on_windows → 出来是测试结果。

调用关系：它只在 Windows 条件下启用。它把测试框架参数交给具体断言函数，让本地和远程路径都检查同样的错误提示。

调用图：调用 1 个内部函数（assert_exec_process_signal_reports_unsupported_on_windows）。

async fn exec_process_preserves_queued_events_before_subscribe(use_remote: bool) -> Result<()>

作用：这是测试入口，用来确认进程输出先发生、读取订阅后发生时，消息仍然保留。

数据流：进去的是 use_remote 参数 → 它调用 assert_exec_process_preserves_queued_events_before_subscribe → 出来是 Result。

调用关系：它负责把本地和远程两种模式接到具体排队事件测试上。真正延迟订阅并检查输出不丢的逻辑在 assert_exec_process_preserves_queued_events_before_subscribe 中。

调用图：调用 1 个内部函数（assert_exec_process_preserves_queued_events_before_subscribe）。

fn find_python() -> Option<String>

作用：寻找当前机器上能用的 Python 命令。测试里很多地方要临时启动 Python，如果找不到就跳过相关测试，避免因为环境缺少 Python 而误报代码坏了。

数据流：它不接收参数，只依次尝试运行 python3 --version 和 python --version → 哪个命令能成功返回，就把这个命令名保存下来 → 返回可用的命令名；如果两个都不行，就返回空。

调用关系：需要 Python 的测试会先问它，例如 PTY 交互测试、管道输入回显测试、大量 stderr 输出测试、继承文件描述符的 Python REPL 测试。它自己只负责探路，不负责启动真正被测的进程。

调用图：被 4 处调用（pipe_drains_stderr_without_stdout_activity, pipe_process_round_trips_stdin, pty_preserving_inherited_fds_keeps_python_repl_running, pty_python_repl_emits_output_and_exits）；外部调用 1 个（new）。

fn setsid_available() -> bool

作用：检查当前系统有没有 setsid 这个工具。setsid 可以让进程脱离原来的会话，测试终止逻辑时需要它。

数据流：它先看是不是 Windows；Windows 没有这套 Unix 会话机制，就直接说不可用 → 在非 Windows 上尝试执行 setsid true → 成功就返回 true，失败或命令不存在就返回 false。

调用关系：只有 pipe_terminate_aborts_detached_readers 会用它。那个测试开始前先确认工具存在，不存在就跳过，避免把机器环境问题当成程序问题。

调用图：被 1 处调用（pipe_terminate_aborts_detached_readers）；外部调用 2 个（cfg!, new）。

fn shell_command(program: &str) -> (String, Vec<String>)

作用：把一段 shell 脚本文字包装成当前系统能执行的命令。这样同一类测试可以同时跑在 Windows 和 Unix 上。

数据流：输入是一段要执行的命令字符串 → 如果是 Windows，就用 cmd.exe /C ...；否则用 /bin/sh -c ... → 输出可执行程序名和参数列表。

调用关系：多个测试都通过它准备小脚本，比如管道和 PTY 共用接口测试、拆分 stdout/stderr 测试、检查子进程会话测试、终止后台进程测试。它把跨平台差异挡在测试外面。

调用图：被 5 处调用（pipe_and_pty_share_interface, pipe_process_can_expose_split_stdout_and_stderr, pipe_process_detaches_from_parent_session, pipe_terminate_aborts_detached_readers, pty_terminate_kills_background_children_in_same_process_group）；外部调用 3 个（cfg!, var, vec!）。

fn echo_sleep_command(marker: &str) -> String

作用：生成一段“先打印标记，再稍微等一下”的命令。测试用它确认进程真的输出了指定文字，并且不是一启动就立刻消失导致读不到。

数据流：输入是一个标记文字 → Windows 上生成 echo 加 ping 延时的命令，Unix 上生成 echo 加 sleep 的命令 → 输出完整命令字符串。

调用关系：pipe_and_pty_share_interface 用它分别生成管道和 PTY 的小任务，再交给 shell_command 包装成可运行命令。

调用图：被 1 处调用（pipe_and_pty_share_interface）；外部调用 2 个（cfg!, format!）。

fn split_stdout_stderr_command() -> String

作用：生成一段会分别向标准输出和标准错误写固定内容的命令。标准输出可以理解为正常说话，标准错误是报错/诊断通道。

数据流：它不接收参数 → 按系统选择 Windows 的 cmd 写法或 Unix 的 shell 写法 → 返回一段确定会输出 split-out 和 split-err 的脚本。

调用关系：pipe_process_can_expose_split_stdout_and_stderr 用它制造可预测的两路输出，从而检查库有没有把 stdout 和 stderr 混在一起。

调用图：被 1 处调用（pipe_process_can_expose_split_stdout_and_stderr）；外部调用 1 个（cfg!）。

async fn collect_split_output(mut output_rx: tokio::sync::mpsc::Receiver<Vec<u8>>) -> Vec<u8>

作用：把一个输出通道里的所有小块字节收集成一整段。测试里用它等待 stdout 或 stderr 被读完。

数据流：输入是一个异步接收器，里面会陆续收到字节块 → 它循环接收，收到一块就追加到总列表里，直到通道关闭 → 返回合并后的字节数组。

调用关系：拆分 stdout/stderr 的测试和驱动器测试会把它放进异步任务里，让 stdout、stderr 两路同时被排空，避免某一路没人读而堵住。

调用图：调用 1 个内部函数（recv）；被 3 处调用（driver_backed_process_can_expose_split_stdout_and_stderr, driver_backed_process_drains_output_that_arrives_after_exit_signal, pipe_process_can_expose_split_stdout_and_stderr）；外部调用 1 个（new）。

fn combine_spawned_output(
    spawned: SpawnedProcess,
) -> (
    crate::ProcessHandle,
    tokio::sync::broadcast::Receiver<Vec<u8>>,
    tokio::sync::oneshot::Receiver<i32>,
)

作用：把一个已启动进程的标准输出和标准错误合成一条输出流，同时保留进程句柄和退出通知。这样很多测试不用关心两路输出的区别。

数据流：输入是 SpawnedProcess，里面有进程会话、stdout 接收器、stderr 接收器、退出接收器 → 它拆开这些字段，并调用合并输出的工具 → 输出进程句柄、合并后的输出接收器、退出码接收器。

调用关系：大多数测试启动进程后都会先经过它做“整理”。它把底层返回的复杂结构变成测试更方便使用的三件东西。

调用图：被 11 处调用（pipe_and_pty_share_interface, pipe_drains_stderr_without_stdout_activity, pipe_process_detaches_from_parent_session, pipe_process_round_trips_stdin, pipe_spawn_no_stdin_can_preserve_inherited_fds, pipe_terminate_aborts_detached_readers, pty_preserving_inherited_fds_keeps_python_repl_running, pty_python_repl_emits_output_and_exits, pty_spawn_can_preserve_inherited_fds, pty_spawn_with_inherited_fds_supports_resize (+1 more)）；外部调用 1 个（combine_output_receivers）。

async fn collect_output_until_exit(
    mut output_rx: tokio::sync::broadcast::Receiver<Vec<u8>>,
    exit_rx: tokio::sync::oneshot::Receiver<i32>,
    timeout_ms: u64,
) -> (Vec<u8>, i32)

作用：一边收集输出，一边等待进程退出，并带有超时保护。它解决了测试最常见的问题：不能无限等，也不能漏掉退出前后的最后几字节。

数据流：输入是输出接收器、退出码接收器和超时时间 → 它同时监听输出、退出和总超时；收到输出就累计，收到退出码后还会再短暂等待一会儿，把晚到的尾部输出也收掉 → 返回收集到的字节和退出码；超时则用 -1 表示没等到正常退出。

调用关系：很多测试都把最终收尾交给它，比如 PTY Python 测试、管道回显测试、stderr 排空测试、继承文件描述符测试、resize 测试。它是测试里的通用“等进程结束并拿结果”的工具。

调用图：被 8 处调用（pipe_and_pty_share_interface, pipe_drains_stderr_without_stdout_activity, pipe_process_round_trips_stdin, pipe_spawn_no_stdin_can_preserve_inherited_fds, pty_preserving_inherited_fds_keeps_python_repl_running, pty_python_repl_emits_output_and_exits, pty_spawn_can_preserve_inherited_fds, pty_spawn_with_inherited_fds_supports_resize）；外部调用 5 个（new, pin!, select!, from_millis, now）。

async fn wait_for_output_contains(
    output_rx: &mut tokio::sync::broadcast::Receiver<Vec<u8>>,
    needle: &str,
    timeout_ms: u64,
) -> anyhow::Result<Vec<u8>>

作用：等待 PTY 输出里出现某段指定文字。适合那种必须先看到“准备好了”或“当前尺寸是某值”后，才能进行下一步的测试。

数据流：输入是输出接收器、要找的文字和超时时间 → 它不断收输出并转成可读文本检查 → 找到就返回已收集的字节；通道关闭或超时就返回错误，错误里带上已经看到的内容方便排查。

调用关系：pty_spawn_with_inherited_fds_supports_resize 用它先等 shell 报告初始终端大小，然后才发送 resize 和继续执行的输入。

调用图：调用 1 个内部函数（recv）；被 1 处调用（pty_spawn_with_inherited_fds_supports_resize）；外部调用 6 个（from_utf8_lossy, new, bail!, from_millis, now, timeout）。

async fn wait_for_python_repl_ready(
    output_rx: &mut tokio::sync::broadcast::Receiver<Vec<u8>>,
    timeout_ms: u64,
    ready_marker: &str,
) -> anyhow::Result<Vec<u8>>

作用：等待 Python 交互解释器（REPL，也就是输入一行执行一行的 Python 窗口）打印出准备完成的标记。

数据流：输入是输出接收器、超时时间和准备标记 → 它持续收集 PTY 输出，直到文本里包含这个标记 → 成功返回已收集输出；如果输出关闭或等太久，就返回带上下文的错误。

调用关系：pty_python_repl_emits_output_and_exits 启动 Python 后用它确认解释器已经能接收命令，然后再写入 print 和 exit()。

调用图：调用 1 个内部函数（recv）；被 1 处调用（pty_python_repl_emits_output_and_exits）；外部调用 6 个（from_utf8_lossy, new, bail!, from_millis, now, timeout）。

async fn wait_for_python_repl_ready_via_probe(
    writer: &tokio::sync::mpsc::Sender<Vec<u8>>,
    output_rx: &mut tokio::sync::broadcast::Receiver<Vec<u8>>,
    timeout_ms: u64,
    newline: &str,
)

作用：通过反复给 Python 发送一条打印标记的小命令，来确认 Python 交互窗口已经能响应输入。它比单纯等提示符更稳，因为不同环境的提示符可能不一样。

数据流：输入是写入通道、输出接收器、超时时间和换行符 → 它隔一小段时间发送 print('标记')，同时收集输出 → 一旦看到标记就返回已收集输出；如果一直没看到或通道关闭，就返回错误。

调用关系：pty_preserving_inherited_fds_keeps_python_repl_running 用它确认带继承文件描述符启动的 Python REPL 还活着、还能执行输入。它既向进程写，也从进程读。

调用图：调用 1 个内部函数（recv）；被 1 处调用（pty_preserving_inherited_fds_keeps_python_repl_running）；外部调用 10 个（send, from_utf8_lossy, new, bail!, cfg!, format!, min, from_millis, now, timeout）。

fn process_exists(pid: i32) -> anyhow::Result<bool>

作用：在 Unix 上检查某个进程 ID 是否还存在。它用来判断被终止的后台子进程有没有真的死掉。

数据流：输入是进程 ID → 它调用 kill(pid, 0)，这个调用不会杀进程，只是问系统“这个进程在不在” → 返回 true 表示存在，false 表示不存在；遇到其他系统错误就返回错误。

调用关系：wait_for_process_exit 会反复调用它。终止 PTY 后台子进程的测试靠它确认目标进程是否已经退出。

调用图：被 1 处调用（wait_for_process_exit）；外部调用 2 个（last_os_error, kill）。

async fn wait_for_marker_pid(
    output_rx: &mut tokio::sync::broadcast::Receiver<Vec<u8>>,
    marker: &str,
    timeout_ms: u64,
) -> anyhow::Result<i32>

作用：从输出里等到某个标记后面的进程 ID。测试让子进程打印“标记+PID”，这个函数负责把 PID 抠出来。

数据流：输入是输出接收器、标记字符串和超时时间 → 它不断收字节、转成文本、寻找标记，找到后继续读取紧跟着的数字 → 成功返回解析出的进程 ID；超时或输出异常就返回错误。

调用关系：PTY 终止后台子进程测试和 Python REPL 存活测试都会用它拿到真实子进程 PID，随后再用 process_exists 或 wait_for_process_exit 做检查。

调用图：调用 1 个内部函数（recv）；被 2 处调用（pty_preserving_inherited_fds_keeps_python_repl_running, pty_terminate_kills_background_children_in_same_process_group）；外部调用 6 个（from_utf8_lossy, new, bail!, from_millis, now, timeout）。

async fn wait_for_process_exit(pid: i32, timeout_ms: u64) -> anyhow::Result<bool>

作用：在限定时间内等待某个 Unix 进程消失。它让测试可以说“最多等几秒，看这个进程有没有被杀掉”。

数据流：输入是进程 ID 和超时时间 → 它循环调用 process_exists，如果发现进程不存在就返回 true；如果超过期限还存在就返回 false；中间每 20 毫秒睡一下，避免忙等占 CPU。

调用关系：pty_terminate_kills_background_children_in_same_process_group 在调用终止后用它验证后台 sleep 进程是否真的退出。它的底层判断交给 process_exists。

调用图：调用 1 个内部函数（process_exists）；被 1 处调用（pty_terminate_kills_background_children_in_same_process_group）；外部调用 3 个（from_millis, now, sleep）。

async fn pty_python_repl_emits_output_and_exits() -> anyhow::Result<()>

作用：测试通过 PTY 启动 Python 交互模式后，能写入命令、读到输出，并正常退出。它模拟真实用户在终端里敲 Python。

数据流：它先找 Python，准备启动参数和环境变量 → 用 PTY 启动 Python，合并输出，等待准备标记 → 向 Python 写入 print('hello from pty') 和 exit() → 收集退出前后的输出，断言看到了文字且退出码是 0。

调用关系：它依赖 find_python 找命令，依赖 combine_spawned_output 整理进程结果，依赖 wait_for_python_repl_ready 等 REPL 可用，最后交给 collect_output_until_exit 收尾。

调用图：调用 5 个内部函数（default, collect_output_until_exit, combine_spawned_output, find_python, wait_for_python_repl_ready）；外部调用 10 个（new, from_utf8_lossy, assert!, assert_eq!, cfg!, spawn_pty_process, eprintln!, format!, vars, vec!）。

async fn pipe_process_round_trips_stdin() -> anyhow::Result<()>

作用：测试普通管道启动的进程能收到标准输入，并把内容回显出来。简单说，就是确认“写进去一行，能读回来一行”。

数据流：它按系统选择一个会读取一行并打印的程序：Windows 用 cmd，Unix 用 Python → 启动管道进程，拿到写入端和输出端 → 写入 roundtrip 后关闭输入 → 等进程退出并检查输出包含这段文字，退出码为 0。

调用关系：它会在 Unix 上先用 find_python，启动后用 combine_spawned_output 和 collect_output_until_exit 完成通用的输出收集与退出检查。

调用图：调用 3 个内部函数（collect_output_until_exit, combine_spawned_output, find_python）；外部调用 11 个（new, from_utf8_lossy, assert!, assert_eq!, cfg!, spawn_pipe_process, eprintln!, format!, var, vars (+1 more)）。

async fn pipe_process_detaches_from_parent_session() -> anyhow::Result<()>

作用：在 Unix 上测试用管道启动的子进程会脱离父进程会话，并成为自己的会话 leader。这样终端信号和进程组管理会更可控。

数据流：它先读取父进程的会话 ID → 启动一个会打印自身 PID 的 shell → 从输出里解析子进程 PID，再读取子进程会话 ID → 断言子会话 ID 等于子 PID，并且不同于父会话 ID，最后确认进程正常退出。

调用关系：它用 shell_command 生成跨 shell 命令，用 spawn_pipe_process 启动，再用 combine_spawned_output 拿输出和退出通知。

调用图：调用 2 个内部函数（combine_spawned_output, shell_command）；外部调用 10 个（new, from_utf8_lossy, bail!, assert_eq!, assert_ne!, spawn_pipe_process, getsid, vars, from_millis, timeout）。

async fn pipe_and_pty_share_interface() -> anyhow::Result<()>

作用：测试管道进程和 PTY 进程暴露出来的使用方式是一致的。调用者不应该因为底层连接方式不同，就被迫写两套完全不同的代码。

数据流：它分别准备一个管道命令和一个 PTY 命令，各自打印不同标记 → 启动两个进程并整理输出接口 → 分别等它们退出 → 检查两者都退出成功，而且输出中包含各自标记。

调用关系：它用 echo_sleep_command 生成测试脚本，用 shell_command 包装命令，再通过 combine_spawned_output 和 collect_output_until_exit 用同一种方式读取结果。

调用图：调用 5 个内部函数（default, collect_output_until_exit, combine_spawned_output, echo_sleep_command, shell_command）；外部调用 7 个（new, assert!, assert_eq!, cfg!, spawn_pipe_process, spawn_pty_process, vars）。

async fn pipe_drains_stderr_without_stdout_activity() -> anyhow::Result<()>

作用：测试即使标准输出没有动静，标准错误里大量数据也能被持续读走。否则子进程可能因为错误输出管道塞满而卡死。

数据流：它先找 Python → 运行一段只往 stderr 写大量字符的脚本 → 启动管道进程并合并输出 → 等进程退出，确认退出码为 0 且确实收到了输出。

调用关系：它通过 find_python 准备环境，使用 spawn_pipe_process 启动，随后由 combine_spawned_output 和 collect_output_until_exit 验证输出排空能力。

调用图：调用 3 个内部函数（collect_output_until_exit, combine_spawned_output, find_python）；外部调用 7 个（new, assert!, assert_eq!, spawn_pipe_process, eprintln!, vars, vec!）。

async fn pipe_process_can_expose_split_stdout_and_stderr() -> anyhow::Result<()>

作用：测试无标准输入的管道进程能把标准输出和标准错误分开暴露给调用者。调用者有时需要知道一段文字到底是正常输出还是错误输出。

数据流：它生成一段同时写 stdout 和 stderr 的命令 → 用无 stdin 的管道方式启动 → 分别开异步任务收集 stdout 和 stderr → 等进程退出，再断言两路内容分别等于预期文本。

调用关系：它用 split_stdout_stderr_command 和 shell_command 准备命令，用 collect_split_output 同时排空两路输出，不走 combine_spawned_output，因为这里正是要检查两路分离。

调用图：调用 3 个内部函数（collect_split_output, shell_command, split_stdout_stderr_command）；外部调用 8 个（new, assert_eq!, cfg!, spawn_pipe_process_no_stdin, vars, spawn, from_millis, timeout）。

async fn driver_backed_process_can_expose_split_stdout_and_stderr() -> anyhow::Result<()>

作用：测试由自定义 ProcessDriver 包出来的进程对象，也能分开提供 stdout 和 stderr。ProcessDriver 可以理解为一套手工接好的输入、输出、退出信号。

数据流：它先手动建立写入通道、stdout 广播通道、stderr 广播通道和退出通道 → 用这些拼成 ProcessDriver 并转换成 SpawnedProcess → 分别发送 stdout/stderr 数据和退出码 → 收集后断言两路内容和退出码正确。

调用关系：它直接测试 spawn_from_driver 的包装能力，并用 collect_split_output 收完两路输出。它不启动真实外部程序，而是用人工通道模拟。

调用图：调用 1 个内部函数（collect_split_output）；外部调用 5 个（assert_eq!, spawn_from_driver, spawn, from_secs, timeout）。

async fn driver_backed_process_can_resize_via_resizer_hook() -> anyhow::Result<()>

作用：测试驱动器封装的进程能响应终端尺寸调整。resize 就是把终端窗口改成多少行、多少列。

数据流：它创建一个 ProcessDriver，里面放入一个 resize 回调；这个回调收到尺寸后通过一次性通道发出去 → 调用进程会话的 resize，传入 40 行 120 列 → 等回调传回尺寸，并断言尺寸完全一致。

调用关系：它专门验证 spawn_from_driver 是否把会话的 resize 操作正确转发给驱动器提供的 resizer hook。

调用图：外部调用 7 个（new, assert_eq!, spawn_from_driver, new, new, from_secs, timeout）。

async fn driver_backed_process_drains_output_that_arrives_after_exit_signal() -> anyhow::Result<()>

作用：测试即使退出信号先到了，稍后才到的尾部输出也不会被丢掉。这是异步系统里很容易出现的竞态问题。

数据流：它创建一个只有 stdout 的驱动器进程 → 先发送退出码，再等 50 毫秒发送 tail 输出并关闭输出通道 → 等退出通知和收集任务完成 → 断言最终仍然收到了 tail，退出码也是 0。

调用关系：它用 spawn_from_driver 构造被测对象，用 collect_split_output 检查 stdout 是否被完整排空。这个测试补强了退出和输出到达顺序不固定的场景。

调用图：调用 1 个内部函数（collect_split_output）；外部调用 7 个（assert_eq!, spawn_from_driver, spawn, from_millis, from_secs, sleep, timeout）。

async fn pipe_terminate_aborts_detached_readers() -> anyhow::Result<()>

作用：测试管道进程被终止后，后台脱离会话的输出读取也会停下来。否则测试或真实程序可能继续收到不该来的输出，甚至泄漏读线程。

数据流：它先检查 setsid 是否可用 → 启动一个后台不断打印 tick 的脚本 → 等确认有输出后调用 terminate → 再短时间监听新输出；如果没有输出或通道关闭就算成功，若还收到内容就报错。

调用关系：它用 setsid_available 做环境门槛，用 shell_command 生成命令，用 combine_spawned_output 取得会话和输出流，然后重点验证 session.terminate() 的效果。

调用图：调用 3 个内部函数（combine_spawned_output, setsid_available, shell_command）；外部调用 7 个（new, bail!, spawn_pipe_process, eprintln!, vars, from_millis, timeout）。

async fn pty_terminate_kills_background_children_in_same_process_group() -> anyhow::Result<()>

作用：在 Unix 上测试 PTY 进程被终止时，同一进程组里的后台子进程也会被杀掉。否则主 shell 死了，后台 sleep 之类的进程还会残留。

数据流：它启动一个 shell，让它后台运行 sleep 1000 并打印后台进程 PID → 从 PTY 输出里解析 PID，并确认该进程存在 → 调用 terminate → 等这个 PID 消失；如果没消失，会尝试强杀清理，然后让测试失败。

调用关系：它用 shell_command 准备脚本，combine_spawned_output 拿输出，wait_for_marker_pid 抠出 PID，wait_for_process_exit 等待终止效果。

调用图：调用 5 个内部函数（default, combine_spawned_output, shell_command, wait_for_marker_pid, wait_for_process_exit）；外部调用 6 个（new, assert!, spawn_pty_process, format!, kill, vars）。

async fn pty_spawn_can_preserve_inherited_fds() -> anyhow::Result<()>

作用：在 Unix 上测试通过 PTY 启动进程时，可以保留指定的文件描述符。文件描述符可以理解为系统给打开文件、管道等资源发的号码。

数据流：它创建一根系统管道，把写端的号码放进环境变量并指定要继承 → 启动 shell，让它通过 /dev/fd/号码 写入 __preserved__ → 等进程正常退出 → 从管道读端读内容，确认正好收到这段文字。

调用关系：它直接调用 spawn_process_with_inherited_fds 测 PTY 的继承能力，再用 combine_spawned_output 和 collect_output_until_exit 等进程收尾。

调用图：调用 4 个内部函数（default, spawn_process_with_inherited_fds, collect_output_until_exit, combine_spawned_output）；外部调用 7 个（new, new, assert_eq!, last_os_error, pipe, vars, from_raw_fd）。

async fn pty_preserving_inherited_fds_keeps_python_repl_running() -> anyhow::Result<()>

作用：在 Unix 上测试“保留文件描述符”这个功能不会破坏 Python 交互模式。也就是说，额外继承资源后，PTY 里的 Python 仍然能正常活着、接收命令、退出。

数据流：它先找 Python，创建一根管道并把写端设为要继承 → 通过 PTY 启动 Python → 关闭父进程这边的管道句柄后，反复探测直到 Python 能响应 → 让 Python 打印自己的 PID，确认进程仍存在 → 发送 exit()，收集输出并检查退出码为 0。

调用关系：它组合了多个辅助函数：find_python 找程序，wait_for_python_repl_ready_via_probe 确认 REPL 可用，wait_for_marker_pid 拿 PID，collect_output_until_exit 收尾。核心被测入口是 spawn_process_with_inherited_fds。

调用图：调用 7 个内部函数（default, spawn_process_with_inherited_fds, collect_output_until_exit, combine_spawned_output, find_python, wait_for_marker_pid, wait_for_python_repl_ready_via_probe）；外部调用 9 个（new, assert!, assert_eq!, last_os_error, eprintln!, format!, pipe, vars, from_raw_fd）。

async fn pty_spawn_with_inherited_fds_reports_exec_failures() -> anyhow::Result<()>

作用：在 Unix 上测试使用“继承文件描述符”的 PTY 启动方式时，如果可执行文件不存在，会把错误报告出来，而不是假装启动成功。

数据流：它创建一根管道并指定写端要继承 → 尝试启动一个肯定不存在的命令 /definitely/missing/command → 如果意外启动成功就终止并失败；如果返回错误，就检查错误文字包含“找不到文件”一类信息。

调用关系：它直接针对 spawn_process_with_inherited_fds 的失败路径。这个测试确保复杂启动路径也能正确把 exec 失败传给调用者。

调用图：调用 2 个内部函数（default, spawn_process_with_inherited_fds）；外部调用 7 个（new, bail!, assert!, last_os_error, pipe, vars, from_raw_fd）。

async fn pty_spawn_with_inherited_fds_supports_resize() -> anyhow::Result<()>

作用：在 Unix 上测试带继承文件描述符启动的 PTY 仍然支持调整终端大小。继承额外资源不应该影响 resize 功能。

数据流：它创建管道并启动 shell，初始终端大小设为 31 行 101 列 → shell 先打印 stty size 看到的大小并等待输入 → 测试等到初始大小输出后，把终端改成 45 行 132 列，再发送一行让 shell 继续 → 收集最终输出，确认 shell 看到的新大小正确且退出码为 0。

调用关系：它使用 spawn_process_with_inherited_fds 启动，靠 wait_for_output_contains 等初始输出，用会话的 resize 发起尺寸变化，最后由 collect_output_until_exit 验证结果。

调用图：调用 4 个内部函数（spawn_process_with_inherited_fds, collect_output_until_exit, combine_spawned_output, wait_for_output_contains）；外部调用 8 个（new, from_utf8_lossy, assert!, assert_eq!, last_os_error, pipe, vars, from_raw_fd）。

async fn pipe_spawn_no_stdin_can_preserve_inherited_fds() -> anyhow::Result<()>

作用：在 Unix 上测试无标准输入的管道启动方式也能保留指定文件描述符。也就是说，不接 stdin 的进程仍可以继承额外打开的资源。

数据流：它创建系统管道，把写端号码放进环境变量并声明要继承 → 用无 stdin 的方式启动 shell，让它往这个继承来的 fd 写入 __pipe_preserved__ → 等进程退出并确认退出码为 0 → 从读端读出内容并断言完全一致。

调用关系：它测试的是 spawn_process_no_stdin_with_inherited_fds，并复用 combine_spawned_output 和 collect_output_until_exit 做通用的进程结果收集。

调用图：调用 3 个内部函数（spawn_process_no_stdin_with_inherited_fds, collect_output_until_exit, combine_spawned_output）；外部调用 7 个（new, new, assert_eq!, last_os_error, pipe, vars, from_raw_fd）。

fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result

作用：把文件系统实现类型变成好读的文字，比如把 Local 显示成“local”，把 Remote 显示成“remote”。这通常用于测试名字、日志或错误信息，让人一眼知道当前测的是哪一种实现。

数据流：进去的是一个 FileSystemImplementation 值和一个格式化输出器 → 函数根据值是 Local 还是 Remote 选出对应的小写字符串 → 把字符串写进输出器，返回写入是否成功的结果。

调用关系：它是 Rust 的 Display 显示接口的一部分。外部代码在需要把 FileSystemImplementation 放进字符串、日志或测试参数说明时会间接调用它；它本身只把文字交给标准的 write_str 写出，不参与文件系统测试的实际读写。

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

async fn create_file_system_context(
    implementation: FileSystemImplementation,
) -> Result<FileSystemContext>

作用：按测试要求创建一个可用的文件系统测试环境。测试可以传入 Local 或 Remote，然后拿到同一种 ExecutorFileSystem 接口，不用关心背后是本地实现还是远程服务器。

数据流：进去的是想测试的实现类型 → 如果是 Local，就找到测试辅助程序路径，组装运行时路径，再创建 LocalFileSystem；如果是 Remote，就启动测试用 exec-server，按它的 websocket 地址创建测试环境，再从环境里取出文件系统接口 → 出来的是 FileSystemContext，里面有文件系统接口，并保留必要的辅助路径或服务器句柄，防止测试运行中资源消失。

调用关系：很多文件系统测试在开头都会调用它，比如测试复制、创建目录、读取元数据、沙箱路径解析等。它是测试和真实实现之间的接线板：本地分支会交给 test_codex_helper_paths、ExecServerRuntimePaths::new 和 LocalFileSystem::with_runtime_paths；远程分支会先交给 exec_server 启动服务，再用 Environment::create_for_tests 接上这个服务。

调用图：调用 5 个内部函数（create_for_tests, with_runtime_paths, new, exec_server, test_codex_helper_paths）；被 34 处调用（assert_canonicalize_resolves_directory_alias, assert_sandboxed_canonicalize_resolves_directory_alias, file_system_copy_copies_directory_recursively, file_system_copy_copies_file, file_system_copy_rejects_copying_directory_into_descendant, file_system_copy_rejects_directory_without_recursive, file_system_create_directory_creates_nested_directories, file_system_get_metadata_reports_files_and_directories, file_system_read_directory_lists_entries, file_system_read_file_returns_bytes (+15 more)）；外部调用 1 个（new）。

fn absolute_path(path: std::path::PathBuf) -> AbsolutePathBuf

作用：确认传进来的路径一定是绝对路径，并把它转换成项目里专门表示“绝对路径”的类型。这样后面的沙箱规则不会拿到含糊的相对路径。

数据流：进去的是一个普通 PathBuf 路径 → 函数先检查它是不是绝对路径，不是就让测试立刻失败并说明是哪条路径有问题 → 如果检查通过，就转换成 AbsolutePathBuf 并返回；它不改文件系统，只做路径校验和包装。

调用关系：read_only_sandbox 和 workspace_write_sandbox 都会先调用它，因为权限边界必须建立在明确的绝对路径上。另有测试会直接用它确认权限配置能正确保留绝对路径。它把路径转换这件小事集中起来，避免每个测试自己写断言。

调用图：调用 1 个内部函数（try_from）；被 3 处调用（sandbox_context_from_profile_preserves_workspace_write_read_only_subpaths, read_only_sandbox, workspace_write_sandbox）；外部调用 1 个（assert!）。

fn read_only_sandbox(readable_root: std::path::PathBuf) -> FileSystemSandboxContext

作用：创建一个“某个根目录只能读，不能写”的沙箱上下文。测试用它来验证文件系统实现是否真的尊重只读权限。

数据流：进去的是一个应该可读的根目录路径 → 函数先把它确认并转换成绝对路径 → 再做成一条沙箱规则：这个路径允许 Read（读取）访问 → 最后交给 sandbox_context 包装成完整的 FileSystemSandboxContext 返回。

调用关系：很多沙箱读写测试会调用它，比如确认可读根目录能读取、不可写路径会被拒绝、符号链接不能绕出允许范围。它自己不直接构造完整权限配置，而是只准备“只读目录”这一条规则，然后把最后的组装交给 sandbox_context。

调用图：调用 2 个内部函数（absolute_path, sandbox_context）；被 7 处调用（assert_sandboxed_canonicalize_resolves_directory_alias, file_system_sandboxed_metadata_and_read_allow_readable_root, file_system_sandboxed_write_allows_additional_write_root, file_system_read_directory_rejects_symlink_escape, file_system_sandboxed_read_rejects_symlink_escape, file_system_sandboxed_read_rejects_symlink_parent_dotdot_escape, file_system_sandboxed_write_rejects_unwritable_path）；外部调用 1 个（vec!）。

fn workspace_write_sandbox(
    writable_root: std::path::PathBuf,
) -> FileSystemSandboxContext

作用：创建一个“某个工作区可以写”的沙箱上下文。测试用它来模拟正常工作区：允许创建、删除、复制文件，但仍要挡住越界访问。

数据流：进去的是一个应该可写的根目录路径 → 函数先保证这是绝对路径 → 再做成一条沙箱规则：这个路径允许 Write（写入）访问 → 最后调用 sandbox_context，把规则变成文件系统操作会使用的沙箱上下文并返回。

调用关系：涉及写操作的测试经常调用它，比如复制文件、创建目录、删除文件、检查符号链接是否能逃出工作区。它位于测试准备阶段，负责把“这个目录可写”这句人话翻译成底层权限对象，再交给 sandbox_context 完成统一包装。

调用图：调用 2 个内部函数（absolute_path, sandbox_context）；被 11 处调用（sandbox_context_from_profile_preserves_workspace_write_read_only_subpaths, file_system_copy_preserves_symlink_source, file_system_copy_rejects_symlink_escape_destination, file_system_copy_rejects_symlink_escape_source, file_system_create_directory_rejects_symlink_escape, file_system_remove_rejects_symlink_escape, file_system_remove_removes_symlink_not_target, file_system_sandboxed_write_allows_explicit_alias_roots, file_system_sandboxed_write_preserves_existing_hard_link, file_system_sandboxed_write_rejects_symlink_escape (+1 more)）；外部调用 1 个（vec!）。

fn sandbox_context(entries: Vec<FileSystemSandboxEntry>) -> FileSystemSandboxContext

作用：把一组文件系统沙箱规则包装成完整的沙箱上下文。它是只读沙箱和可写沙箱的共同收口点，避免两边重复写同样的权限组装代码。

数据流：进去的是若干条 FileSystemSandboxEntry，也就是“哪些路径有什么访问权限”的清单 → 函数先把这些条目做成受限制的文件系统策略，再配上受限制的网络策略，形成运行时权限配置 → 最后从这个权限配置生成 FileSystemSandboxContext 返回。

调用关系：read_only_sandbox 和 workspace_write_sandbox 都会把准备好的规则交给它。它再调用权限模型里的 restricted、from_runtime_permissions 和 from_permission_profile，把简单规则变成执行器真正能理解的沙箱上下文。这样测试文件只需要关心“读”或“写”，不用到处了解权限对象的内部拼装方式。

调用图：调用 3 个内部函数（from_permission_profile, from_runtime_permissions, restricted）；被 2 处调用（read_only_sandbox, workspace_write_sandbox）。

fn sandbox_context_from_profile_preserves_workspace_write_read_only_subpaths() -> Result<()>

作用：检查从工作区写权限沙箱转换成权限配置后，工作区里本该只读的子目录不会被弄丢。这里重点看的是 .git 目录，因为它通常不希望被随便改。

数据流：它先创建一个临时工作区和里面的 .git 目录，再生成“工作区可写”的沙箱配置。接着把沙箱权限转成运行时权限策略，取出可写根目录列表。最后确认这个工作区仍然是可写根，并且 .git 这个子路径仍在只读名单里。

调用关系：这是一个独立测试。它直接使用 workspace_write_sandbox 创建沙箱，用 absolute_path 统一路径格式，并用系统的建目录和路径规范化能力准备测试场景。它不测试文件读写接口，而是专门守住权限转换这一步。

调用图：调用 2 个内部函数（absolute_path, workspace_write_sandbox）；外部调用 5 个（new, assert!, panic!, canonicalize, create_dir_all）。

async fn file_system_get_metadata_reports_files_and_directories(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认文件系统接口能正确分辨“文件”和“目录”，并报告大小、创建时间、修改时间等基本信息。

数据流：它拿到某种文件系统实现后，在临时目录里创建一个文本文件和一个目录。然后分别调用 get_metadata 查询它们。结果应该显示文本文件是文件、不是目录、大小为 5；目录则是目录、不是文件，并且修改时间有效。

调用关系：这个测试通过 create_file_system_context 同时适配本地和远程实现。它把路径转成 PathUri 后交给 file_system.get_metadata，再用断言比较返回的 FileMetadata，确保两种实现给出的信息一致。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 5 个（new, assert!, assert_eq!, create_dir, write）。

async fn file_system_create_directory_creates_nested_directories(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认创建目录接口在 recursive 为 true 时，能一次性创建多层不存在的目录。通俗说，就是 mkdir -p 这种效果。

数据流：它先准备一个临时根目录，然后指定一个还不存在的 source/nested 路径。调用 create_directory 并打开 recursive 选项后，测试检查这个嵌套目录确实已经出现在磁盘上。

调用关系：这个测试仍然通过 create_file_system_context 拿到本地或远程文件系统。它把真实路径包装成 PathUri 后交给 file_system.create_directory，最后用系统路径检查结果。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 2 个（new, assert!）。

async fn file_system_write_file_writes_bytes(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认写文件接口能把一串原始字节写进指定文件。这里测的是最基本的“把内容落到文件里”。

数据流：它创建临时目录，指定 note.txt 作为目标文件。然后调用 write_file 写入字节内容 hello from trait。最后直接从磁盘读取这个文件，确认内容一字不差。

调用关系：它用 create_file_system_context 获取被测实现，用 PathUri 表示目标路径，然后把写入动作交给 file_system.write_file。测试最后用标准文件读取来验证接口真的改了磁盘内容。

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

fn path_uri_join_and_parent_preserve_lexical_paths() -> Result<()>

作用：检查 PathUri 拼接路径和取父路径时，会保留字面上的路径写法，不会偷偷把 .. 这类路径片段提前化简掉。

数据流：它从一个 source 目录生成 PathUri，然后拼接 nested/note.txt，确认结果等于手工拼出的路径。接着取父路径，确认得到 nested。最后拼接 ../outside，确认这个带上级跳转的写法仍按字面保留。

调用关系：这是一个不依赖 file_system 实现的路径工具测试。它直接验证 PathUri::from_path、join 和 parent 的行为，避免后续文件系统操作因为路径对象自己改写路径而产生误判。

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

async fn file_system_read_file_returns_bytes(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认读文件接口能把文件内容作为字节读回来。它不假设内容一定是文字，所以适合任意文件。

数据流：它先在临时目录写入 note.txt，内容是 hello from trait。然后通过 file_system.read_file 读取这个路径。返回的字节数组应该和原始内容完全一致。

调用关系：测试先用系统写文件准备材料，再用被测 file_system.read_file 读取。这样能清楚地区分“准备数据”和“验证接口读取能力”。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 3 个（new, assert_eq!, write）。

async fn file_system_read_file_stream_returns_bounded_chunks(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认流式读文件会把大文件拆成大小受限的小块，而且拼回去后内容不变。流式读取可以理解成“分批搬货”，避免一次把大文件全塞进内存。

数据流：它生成一个比两个读取块还大一点的二进制文件。然后调用 read_file_stream 得到一串数据块。测试先确认每块都不是空的，并且长度不超过 FILE_READ_CHUNK_SIZE；再把所有块拼起来，确认和原文件内容完全一样。

调用关系：它通过 create_file_system_context 测本地和远程实现，用 futures 的 try_collect 收集流里的块。这个测试重点卡住 read_file_stream 的两个承诺：块大小有上限，内容顺序和数据不丢。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 4 个（new, assert!, assert_eq!, write）。

async fn file_system_read_file_text_returns_string(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认读文本文件接口能直接返回字符串，而不是原始字节。适合读取普通文本配置、代码或说明文件。

数据流：它先创建一个文本文件并写入 hello from trait。随后调用 read_file_text 读取。返回结果应该是同样的字符串。

调用关系：这个测试和字节读取测试相似，但走的是 file_system.read_file_text。它验证文本解码这条更方便的读取通道在本地和远程实现上都可用。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 3 个（new, assert_eq!, write）。

async fn file_system_copy_copies_file(implementation: FileSystemImplementation) -> Result<()>

作用：确认复制接口能复制单个文件。也就是源文件还在，目标文件出现，并且内容一样。

数据流：它在临时目录创建 source.txt，并写入文本。然后调用 copy，把它复制到 copy.txt，recursive 设为 false，因为复制单文件不需要递归。最后读取目标文件，确认内容正确。

调用关系：测试把源路径和目标路径都转成 PathUri，然后交给 file_system.copy。它验证 CopyOptions 在普通文件场景下的最小用法。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 3 个（new, assert_eq!, write）。

async fn file_system_copy_copies_directory_recursively(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认复制目录时，如果 recursive 为 true，可以连同里面的子目录和文件一起复制。递归复制可以理解成“连箱子里的小箱子一起搬走”。

数据流：它创建 source/nested/note.txt 这样的目录树，并写入文件内容。然后调用 copy，把 source 整个复制到 copied。最后检查 copied/nested/note.txt 是否存在且内容正确。

调用关系：这个测试使用 file_system.copy 的目录复制路径，并明确传入 CopyOptions { recursive: true }。它和拒绝非递归复制目录的测试互相补充，一个证明允许场景，一个证明错误场景。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 4 个（new, assert_eq!, create_dir_all, write）。

async fn file_system_read_directory_lists_entries(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认列目录接口能列出目录里的直接成员，并标明每个成员是文件还是目录。

数据流：它创建一个 source 目录，里面放一个 nested 子目录和一个 root.txt 文件。调用 read_directory 后得到条目列表。测试先按文件名排序，再确认列表里正好有这两个成员，并且类型标记正确。

调用关系：它通过 file_system.read_directory 获取 ReadDirectoryEntry 列表。排序是为了避免不同系统返回目录顺序不同导致测试不稳定，真正要验证的是名字和类型。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 4 个（new, assert_eq!, create_dir_all, write）。

async fn file_system_remove_removes_directory(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认删除接口能删除目录，哪怕目录里还有子目录。这里使用 recursive 和 force，表示“递归删除，并且尽量强制完成”。

数据流：它先创建 remove-me/nested 目录结构。然后调用 remove，传入 recursive: true 和 force: true。最后检查 remove-me 已经不存在。

调用关系：这个测试覆盖 file_system.remove 的目录删除能力。它用临时目录保证不会误删真实文件，并用最终的 exists 检查确认删除真的发生了。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 3 个（new, assert!, create_dir_all）。

async fn file_system_write_file_reports_missing_parent(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认写文件时，如果父目录不存在，接口会报“找不到”的错误，而不是偷偷创建目录或留下半成品文件。

数据流：它构造 missing/note.txt 这个路径，但不创建 missing 目录。调用 write_file 后，测试期待失败。如果意外成功就直接报错；如果失败，就检查错误类型是 NotFound，并确认目标文件没有被创建。

调用关系：这个测试保护 write_file 的边界行为。它使用 anyhow::bail 在不该成功时立刻让测试失败，并用错误类型断言要求本地和远程实现行为一致。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 4 个（new, bail!, assert!, assert_eq!）。

async fn file_system_copy_rejects_directory_without_recursive(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认复制目录时如果没有打开 recursive，接口会明确拒绝。这样可以避免用户以为复制了整个目录，结果只复制了一部分或行为不清楚。

数据流：它创建一个 source 目录，然后调用 copy 试图把目录复制到 dest，但 recursive 设为 false。测试期待得到 InvalidInput 错误，并确认错误文字说明必须设置 recursive: true。

调用关系：这个测试和目录递归复制测试成对存在。file_system.copy 在这里应该走错误分支，返回清楚的错误，而不是执行复制。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 3 个（new, assert_eq!, create_dir_all）。

async fn file_system_sandboxed_metadata_and_read_allow_readable_root(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认在只读沙箱里，位于允许读取范围内的文件可以查询信息，也可以读取内容。沙箱是访问围栏，只读表示能看不能改。

数据流：它创建 allowed 目录和 note.txt 文件，再用 read_only_sandbox 把 allowed 设成可读范围。随后带着这个沙箱调用 get_metadata 和 read_file。返回的文件信息和内容都应该正确。

调用关系：这个测试把普通读取能力和权限检查结合起来。file_system 方法收到 Some(&sandbox) 后，必须先尊重沙箱规则，再完成元数据查询和读取。

调用图：调用 3 个内部函数（create_file_system_context, read_only_sandbox, from_path）；外部调用 4 个（new, assert_eq!, create_dir_all, write）。

async fn assert_canonicalize_resolves_directory_alias(
    implementation: FileSystemImplementation,
    create_directory_alias: impl FnOnce(&Path, &Path) -> Result<()>,
) -> Result<()>

作用：这是给其他测试复用的辅助函数，用来确认目录别名能被解析成真实路径。目录别名可能是符号链接或 Windows junction，简单说就是“一个门牌指向另一个真实目录”。

数据流：它创建真实目录 source/nested/note.txt，再通过传入的 create_directory_alias 创建一个指向 source 的别名目录。然后构造经由别名访问文件的路径，以及文件的真实规范路径。先确认两者表面上不同，再调用 file_system.canonicalize，最后确认解析结果等于真实路径。

调用关系：它会被 file_system_canonicalize_resolves_directory_symlink 和 file_system_canonicalize_resolves_directory_junction 这类具体测试调用。具体怎么创建别名由调用者传进来；本函数只负责搭场景、调用 canonicalize、验证结果。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；被 2 处调用（file_system_canonicalize_resolves_directory_symlink, file_system_canonicalize_resolves_directory_junction）；外部调用 6 个（new, assert_eq!, assert_ne!, canonicalize, create_dir_all, write）。

async fn assert_sandboxed_canonicalize_resolves_directory_alias(
    implementation: FileSystemImplementation,
    create_directory_alias: impl FnOnce(&Path, &Path) -> Result<()>,
) -> Result<()>

作用：这是带沙箱版本的目录别名解析辅助测试。它确认即使开启文件访问围栏，只要路径在允许范围内，别名仍能被解析成真实路径。

数据流：它创建真实目录和文件，再创建一个目录别名。接着把整个临时目录设成只读沙箱范围。它用别名路径作为请求路径，用系统 canonicalize 得到真实期望路径，然后调用 file_system.canonicalize 并带上沙箱，最后确认两者一致。

调用关系：它被 sandboxed 版本的符号链接和 junction 测试调用。它和 assert_canonicalize_resolves_directory_alias 的区别是多了一层 read_only_sandbox，用来验证 canonicalize 既正确解析路径，又遵守沙箱入口。

调用图：调用 3 个内部函数（create_file_system_context, read_only_sandbox, from_path）；被 2 处调用（file_system_sandboxed_canonicalize_resolves_directory_symlink, file_system_sandboxed_canonicalize_resolves_directory_junction）；外部调用 6 个（new, assert_eq!, assert_ne!, canonicalize, create_dir_all, write）。

async fn file_system_sandboxed_write_allows_additional_write_root(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认一个原本只读的沙箱，可以通过“额外权限”临时增加一个可写目录。这样某些操作能只开放很小的写入范围，而不是放开整个文件系统。

数据流：它先创建 readable 和 writable 两个目录，并从只读 readable 沙箱开始。然后构造 AdditionalPermissionProfile，把 writable 加成读写根目录。接着计算合并后的文件系统和网络沙箱策略，更新 sandbox.permissions。最后带着新沙箱写入 writable/note.txt，并确认文件内容是 created。

调用关系：这个测试串起了权限模型转换和文件写入。它调用 effective_file_system_sandbox_policy、effective_network_sandbox_policy 计算最终权限，再用 PermissionProfile::from_runtime_permissions_with_enforcement 生成可执行的权限配置，最后交给 file_system.write_file 验证效果。

调用图：调用 7 个内部函数（create_file_system_context, read_only_sandbox, from_read_write_roots, from_runtime_permissions_with_enforcement, effective_file_system_sandbox_policy, effective_network_sandbox_policy, from_path）；外部调用 4 个（new, assert_eq!, create_dir_all, vec!）。

async fn file_system_copy_rejects_copying_directory_into_descendant(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：确认不能把一个目录复制到它自己的子目录里面。否则就像把一个箱子复制进自己内部，可能造成无限套娃或混乱结果。

数据流：它创建 source/nested 目录，然后试图把 source 递归复制到 source/nested/copy。测试期待 copy 返回 InvalidInput 错误，并检查错误文字说明不能复制到自身或后代路径。

调用关系：这个测试保护 file_system.copy 的安全边界。它和正常递归复制目录测试一起说明：目录可以复制，但目标位置不能落在源目录里面。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 3 个（new, assert_eq!, create_dir_all）。

fn assert_sandbox_denied(error: &std::io::Error)

作用：检查一次失败是不是真的因为沙箱拦住了，而不是因为别的奇怪错误。这样测试不会只看到“失败了”就算通过，而是确认失败原因符合安全预期。

数据流：输入一个系统错误 → 它查看错误类型和错误文字，比如“没有权限”“不允许操作”“只读文件系统” → 如果文字和类型像沙箱拒绝，就什么也不返回；如果不像，就让测试直接失败。

调用关系：多个“应该被沙箱挡住”的测试都会调用它。那些测试先故意通过符号链接或只读目录做危险操作，拿到错误后交给它统一判断，避免每个测试重复写同样的检查。

调用图：被 8 处调用（file_system_copy_rejects_symlink_escape_destination, file_system_copy_rejects_symlink_escape_source, file_system_create_directory_rejects_symlink_escape, file_system_read_directory_rejects_symlink_escape, file_system_remove_rejects_symlink_escape, file_system_sandboxed_read_rejects_symlink_escape, file_system_sandboxed_write_rejects_symlink_escape, file_system_sandboxed_write_rejects_unwritable_path）；外部调用 4 个（assert!, kind, to_string, panic!）。

fn assert_normalized_path_rejected(error: &std::io::Error)

作用：检查带有 .. 的路径被整理后，失败原因仍然是合理的。.. 可以理解成“回到上一级目录”，它可能让路径在进入文件系统前就变了样。

数据流：输入一个系统错误 → 它接受两类合理结果：文件不存在，或被沙箱/权限机制拒绝 → 如果错误不属于这些情况，就让测试失败。

调用关系：它只服务于 file_system_sandboxed_read_rejects_symlink_parent_dotdot_escape。那个测试专门验证路径规范化之后，系统不会被符号链接和 .. 的组合骗过。

调用图：被 1 处调用（file_system_sandboxed_read_rejects_symlink_parent_dotdot_escape）；外部调用 4 个（assert!, kind, to_string, panic!）。

fn alias_root_candidate() -> Result<Option<PathBuf>>

作用：找一个适合测试“路径别名”的临时目录根路径。路径别名指同一个真实目录可能有不同写法，比如 /tmp 可能实际指向别的位置。

数据流：它读取 /tmp 和系统临时目录 → 检查这些目录是否存在，并且规范化后的真实路径是否和原路径不同 → 找到就返回这个候选路径，找不到就返回空。

调用关系：file_system_sandboxed_write_allows_explicit_alias_roots 用它决定这个平台有没有可测的别名根目录。如果没有，那个测试会安全跳过。

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

fn create_directory_symlink(target: &Path, alias: &Path) -> Result<()>

作用：创建一个指向目录的符号链接，用来模拟“一个目录有快捷方式入口”的情况。

数据流：输入目标目录和链接路径 → 调用 Unix 的 symlink 创建链接 → 成功时返回空结果，失败时把系统错误传出去。

调用关系：它作为小工具传给共享测试 assert_canonicalize_resolves_directory_alias 和 assert_sandboxed_canonicalize_resolves_directory_alias，让共享测试能在 Unix 上用真正的符号链接来验证路径解析。

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

fn write_fake_bwrap(bin_dir: &Path) -> Result<PathBuf>

作用：在测试目录里写一个假的 bwrap 程序。bwrap 是 Linux 上常用的沙箱工具，这里用假程序确认文件系统 helper 确实从 PATH 找到了它。

数据流：输入一个 bin 目录 → 创建目录，写入名为 bwrap 的 shell 脚本，脚本会记录收到的参数并执行真正的内部命令 → 给脚本加可执行权限，最后返回这个假 bwrap 的路径。

调用关系：Linux 专用测试 sandboxed_file_system_helper_finds_bwrap_on_preserved_path 会先调用它布置假工具，再启动服务并做一次沙箱写文件，最后检查假工具留下的日志。

调用图：被 1 处调用（sandboxed_file_system_helper_finds_bwrap_on_preserved_path）；外部调用 5 个（join, create_dir_all, metadata, set_permissions, write）。

async fn file_system_canonicalize_resolves_directory_symlink(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试普通路径规范化能把目录符号链接解析到真实目录。路径规范化就是把“快捷方式、相对写法”等整理成真实路径。

数据流：输入测试参数：本地实现或远程实现 → 把实现类型和创建目录符号链接的小工具交给共享断言 → 如果共享断言发现解析不对，测试失败；否则通过。

调用关系：这是共享测试在 Unix 上的落地点。它不自己搭全部场景，而是把 Unix 的符号链接创建方式交给 shared::assert_canonicalize_resolves_directory_alias。

调用图：调用 1 个内部函数（assert_canonicalize_resolves_directory_alias）。

async fn file_system_sandboxed_canonicalize_resolves_directory_symlink(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试在沙箱限制下，路径规范化仍能正确处理目录符号链接。它确认安全限制没有把合法的链接解析搞坏。

数据流：输入本地或远程实现 → 调用共享的沙箱版规范化测试，并提供 Unix 符号链接创建函数 → 共享测试完成检查后返回成功或错误。

调用关系：它连接本文件的 Unix 专用链接能力和共享测试逻辑，实际检查交给 shared::assert_sandboxed_canonicalize_resolves_directory_alias。

调用图：调用 1 个内部函数（assert_sandboxed_canonicalize_resolves_directory_alias）。

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

作用：测试 Linux 下沙箱文件系统 helper 能从保留下来的 PATH 环境变量里找到 bwrap。这很重要，因为找不到沙箱工具，安全写文件流程就可能无法启动。

数据流：它创建临时目录和假 bwrap → 把假工具目录放到 PATH 前面启动执行服务器 → 通过文件系统 helper 在沙箱内写文件 → 检查文件内容真的写入，并检查假 bwrap 日志里出现了预期参数。

调用关系：这个测试会调用 write_fake_bwrap 布置假工具，调用 exec_server_with_env 启动带指定环境的服务，再用 Environment::create_for_tests 拿到文件系统接口执行一次真实写入。

调用图：调用 5 个内部函数（create_for_tests, exec_server_with_env, workspace_write_sandbox, write_fake_bwrap, from_path）；外部调用 9 个（new, assert!, assert_eq!, join_paths, split_paths, var_os, create_dir_all, read_to_string, vec!）。

async fn file_system_get_metadata_reports_symlink_targets(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试读取元数据时，符号链接既要被标记为链接，又要报告它指向的文件或目录属性。元数据就是文件大小、类型、修改时间这些“身份证信息”。

数据流：它创建普通文件、目录，以及分别指向它们的符号链接 → 调用文件系统的 get_metadata → 对比返回值，确认文件链接显示为文件、目录链接显示为目录，同时 is_symlink 为真、大小和时间合理。

调用关系：它先通过 create_file_system_context 拿到本地或远程文件系统，再用 PathUri::from_path 把系统路径包装成接口需要的路径格式，然后直接验证 get_metadata 的行为。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 6 个（new, assert!, assert_eq!, create_dir, write, symlink）。

async fn file_system_sandboxed_write_rejects_unwritable_path(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试只读沙箱里不能写文件。只读沙箱就像“只能看不能改”的房间。

数据流：它创建临时目录和一个准备写入的文件路径 → 给这个目录套上只读沙箱 → 尝试写入内容 → 预期拿到拒绝错误，并确认文件没有被创建。

调用关系：它用 read_only_sandbox 制造禁止写入的规则，调用文件系统的 write_file，再把错误交给 assert_sandbox_denied 判断是不是正确的安全拒绝。

调用图：调用 4 个内部函数（create_file_system_context, read_only_sandbox, assert_sandbox_denied, from_path）；外部调用 3 个（new, bail!, assert!）。

async fn file_system_sandboxed_write_allows_explicit_alias_roots(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试如果沙箱明确允许一个带别名的根目录，那么通过这个别名路径写文件应该成功。它避免安全检查过度严格，把合法路径误拦掉。

数据流：它先找一个路径别名候选根目录 → 在这个根目录下建临时目录和文件路径 → 创建允许写这个根的沙箱 → 写入文件并读取回来确认内容是 created。

调用关系：它依赖 alias_root_candidate 判断当前机器是否有可测场景；如果有，再通过 workspace_write_sandbox 创建可写沙箱，最后调用文件系统的 write_file。

调用图：调用 4 个内部函数（create_file_system_context, workspace_write_sandbox, alias_root_candidate, from_path）；外部调用 2 个（assert_eq!, new）。

async fn file_system_sandboxed_read_rejects_symlink_escape(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试读文件时不能通过目录符号链接逃出沙箱。所谓逃出沙箱，就是路径看起来在允许目录下，真实目标却在外面。

数据流：它创建 allowed 和 outside 两个目录，把 allowed 里的 link 指向 outside → outside 里放 secret 文件 → 在只允许读 allowed 的沙箱里读取 allowed/link/secret.txt → 预期被拒绝。

调用关系：它调用 read_only_sandbox 设置读边界，调用 read_file 触发越界尝试，再用 assert_sandbox_denied 确认拦截生效。

调用图：调用 4 个内部函数（create_file_system_context, read_only_sandbox, assert_sandbox_denied, from_path）；外部调用 5 个（new, bail!, create_dir_all, write, symlink）。

async fn file_system_sandboxed_read_rejects_symlink_parent_dotdot_escape(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试符号链接和 .. 组合时，读取操作仍不能绕过沙箱。这个场景容易出错，因为路径在进入文件系统前可能先被整理。

数据流：它创建 allowed、outside 和 secret 文件 → 在 allowed 里放一个指向 outside 的 link → 请求读取 link/../secret.txt 这种会被规范化的路径 → 预期要么被拒绝，要么因为规范化后的文件不存在而失败。

调用关系：它用 read_only_sandbox 限定 allowed，然后调用 read_file。错误不交给普通沙箱断言，而是交给 assert_normalized_path_rejected，因为这个测试允许“路径先被整理导致不存在”这种合理结果。

调用图：调用 4 个内部函数（create_file_system_context, read_only_sandbox, assert_normalized_path_rejected, from_path）；外部调用 5 个（new, bail!, create_dir_all, write, symlink）。

async fn file_system_sandboxed_write_rejects_symlink_escape(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试写文件时不能通过符号链接写到沙箱外。否则攻击者可以在允许目录里放个链接，把内容写到不该碰的地方。

数据流：它创建 allowed 和 outside → 把 allowed/link 指向 outside → 在允许写 allowed 的沙箱中尝试写 allowed/link/blocked.txt → 预期写入失败，并确认 outside 里没有生成文件。

调用关系：它使用 workspace_write_sandbox 创建可写边界，调用 write_file 发起越界写，再用 assert_sandbox_denied 验证是沙箱挡下来的。

调用图：调用 4 个内部函数（create_file_system_context, workspace_write_sandbox, assert_sandbox_denied, from_path）；外部调用 5 个（new, bail!, assert!, create_dir_all, symlink）。

async fn file_system_sandboxed_write_preserves_existing_hard_link(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试写入已有硬链接时，会保留硬链接关系。硬链接可以理解成同一个文件有两个门牌号，改一个门牌号看到的内容，另一个也会变。

数据流：它在 outside 创建真实文件，在 allowed 创建指向同一文件的硬链接 → 在允许写 allowed 的沙箱里写这个硬链接路径 → 读取两个路径，确认内容都变了，并比较设备号和 inode 确认它们仍是同一个底层文件。

调用关系：它通过 workspace_write_sandbox 只允许 allowed 路径，然后调用 write_file。之后用系统元数据检查硬链接关系，确保文件系统实现没有用“替换文件”的方式破坏链接。

调用图：调用 3 个内部函数（create_file_system_context, workspace_write_sandbox, from_path）；外部调用 6 个（new, assert_eq!, create_dir_all, hard_link, metadata, write）。

async fn file_system_create_directory_rejects_symlink_escape(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试创建目录时不能通过符号链接在沙箱外创建新目录。创建目录也是写操作，同样需要边界保护。

数据流：它创建 allowed 和 outside，并让 allowed/link 指向 outside → 尝试在 allowed/link/created 创建目录 → 预期失败，并确认 outside 里没有多出 created。

调用关系：它用 workspace_write_sandbox 定义 allowed 可写，调用 create_directory，失败后交给 assert_sandbox_denied 判断拦截是否符合预期。

调用图：调用 4 个内部函数（create_file_system_context, workspace_write_sandbox, assert_sandbox_denied, from_path）；外部调用 5 个（new, bail!, assert!, create_dir_all, symlink）。

async fn file_system_read_directory_rejects_symlink_escape(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试读取目录列表时不能通过符号链接查看沙箱外目录。即使只是列文件名，也可能泄露不该看的信息。

数据流：它创建 allowed 和 outside，outside 中放 secret 文件，并让 allowed/link 指向 outside → 在只读 allowed 的沙箱中读取 allowed/link 的目录内容 → 预期被拒绝。

调用关系：它调用 read_directory 发起目录读取，使用 read_only_sandbox 限定范围，再用 assert_sandbox_denied 检查安全拒绝。

调用图：调用 4 个内部函数（create_file_system_context, read_only_sandbox, assert_sandbox_denied, from_path）；外部调用 5 个（new, bail!, create_dir_all, write, symlink）。

async fn file_system_copy_rejects_symlink_escape_destination(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试复制文件时，目标位置不能通过符号链接指到沙箱外。否则一次看似安全的复制会把文件写到外部目录。

数据流：它在 allowed 中放 source 文件，让 allowed/link 指向 outside → 尝试把 source 复制到 allowed/link/copied.txt → 预期失败，并确认 outside 里没有 copied 文件。

调用关系：它用 workspace_write_sandbox 设置 allowed 可写，调用 copy，再用 assert_sandbox_denied 验证目标路径越界被拦住。

调用图：调用 4 个内部函数（create_file_system_context, workspace_write_sandbox, assert_sandbox_denied, from_path）；外部调用 6 个（new, bail!, assert!, create_dir_all, write, symlink）。

async fn file_system_remove_removes_symlink_not_target(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试删除符号链接时，只删除链接本身，不删除它指向的真实文件。这是 Unix 用户通常期望的安全行为。

数据流：它在 outside 创建真实文件，在 allowed 创建指向该文件的符号链接 → 在允许写 allowed 的沙箱中删除这个链接路径 → 确认链接没了，但 outside 的真实文件还在且内容不变。

调用关系：它调用 remove 来验证删除语义。这个测试和其他越界拒绝测试不同，它允许操作成功，但要求成功的对象只能是链接本身。

调用图：调用 3 个内部函数（create_file_system_context, workspace_write_sandbox, from_path）；外部调用 6 个（new, assert!, assert_eq!, create_dir_all, write, symlink）。

async fn file_system_copy_preserves_symlink_source(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试复制一个符号链接时，复制出来的仍是符号链接，而不是把链接指向的文件内容复制出来。

数据流：它创建 outside 文件和 allowed 里的 source_symlink → 调用 copy 把这个链接复制成 copied_symlink → 检查 copied_symlink 的类型确实是符号链接，并且它指向的目标路径和原链接一致。

调用关系：它通过 workspace_write_sandbox 允许在 allowed 内写，调用 copy。之后用系统的符号链接元数据读取函数确认复制策略是“保留链接”。

调用图：调用 3 个内部函数（create_file_system_context, workspace_write_sandbox, from_path）；外部调用 7 个（new, assert!, assert_eq!, create_dir_all, symlink_metadata, write, symlink）。

async fn file_system_remove_rejects_symlink_escape(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试删除操作不能通过目录符号链接删掉沙箱外文件。删除是破坏性操作，所以必须特别严格。

数据流：它创建 outside/secret.txt，并让 allowed/link 指向 outside → 尝试删除 allowed/link/secret.txt → 预期被拒绝，并确认 outside 的 secret 文件内容仍然存在。

调用关系：它用 workspace_write_sandbox 给 allowed 写权限，调用 remove 尝试越界删除，错误交给 assert_sandbox_denied 检查。

调用图：调用 4 个内部函数（create_file_system_context, workspace_write_sandbox, assert_sandbox_denied, from_path）；外部调用 6 个（new, bail!, assert_eq!, create_dir_all, write, symlink）。

async fn file_system_copy_rejects_symlink_escape_source(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试复制时，源文件也不能通过符号链接读到沙箱外。否则用户可能把外部秘密文件复制进允许区域，从而泄露内容。

数据流：它创建 outside/secret.txt，让 allowed/link 指向 outside，并准备 allowed/copied.txt 作为目标 → 尝试从 allowed/link/secret.txt 复制 → 预期失败，并确认目标文件没有生成。

调用关系：它调用 copy 来触发源路径越界场景，使用 workspace_write_sandbox 设置边界，再用 assert_sandbox_denied 验证读取源文件也受沙箱限制。

调用图：调用 4 个内部函数（create_file_system_context, workspace_write_sandbox, assert_sandbox_denied, from_path）；外部调用 6 个（new, bail!, assert!, create_dir_all, write, symlink）。

async fn file_system_copy_preserves_symlinks_in_recursive_copy(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试递归复制目录时，目录里的符号链接也要被原样保留。递归复制就是把整个目录树一起复制。

数据流：它创建 source/nested 目录，并在 source 里创建指向 nested 的相对符号链接 → 递归复制 source 到 copied → 检查 copied/nested-link 仍是符号链接，并且目标仍是相对路径 nested。

调用关系：它调用 copy 并把 recursive 设为 true。复制完成后，它用系统元数据和读链接函数确认文件系统实现没有把链接跟随成真实目录。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 6 个（new, assert!, assert_eq!, create_dir_all, symlink_metadata, symlink）。

async fn file_system_copy_ignores_unknown_special_files_in_recursive_copy(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试递归复制目录时，会跳过不认识的特殊文件，比如 FIFO 命名管道，但普通文件仍会复制。这样复制目录不会因为一个特殊节点就全部失败。

数据流：它创建 source 目录，里面放普通文本文件和一个用 mkfifo 命令创建的命名管道 → 递归复制到 copied → 确认普通文件内容复制成功，命名管道没有出现在目标目录。

调用关系：它先用系统命令 mkfifo 布置 Unix 特殊文件，再调用文件系统 copy 的递归模式。这个测试补充了单独复制 FIFO 会失败的场景。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 7 个（new, bail!, assert!, assert_eq!, new, create_dir_all, write）。

async fn file_system_copy_rejects_standalone_fifo_source(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：测试把单独的 FIFO 当作复制源时必须失败，并给出明确错误。FIFO 不是普通文件，直接复制它容易造成阻塞或不可预期行为。

数据流：它用 mkfifo 创建一个命名管道 → 调用 copy 尝试把它复制成普通目标 → 预期得到 InvalidInput 错误，并确认错误文字说明只支持普通文件、目录和符号链接。

调用关系：它直接验证 copy 对单个特殊文件的拒绝行为，和 file_system_copy_ignores_unknown_special_files_in_recursive_copy 一起说明：递归目录里遇到特殊文件会跳过，单独复制特殊文件会报错。

调用图：调用 2 个内部函数（create_file_system_context, from_path）；外部调用 4 个（new, bail!, assert_eq!, new）。

fn create_directory_junction(target: &Path, alias: &Path) -> Result<()>

作用：这个函数在 Windows 上创建一个目录联接点，也就是让一个路径看起来像目录，其实指向另一个真实目录。测试需要它来搭出“路径别名”这个场景。

数据流：输入是真实目标目录 target 和别名目录 alias → 它启动 Windows 命令行 cmd，执行 mklink /J，把 alias 做成指向 target 的目录联接点 → 如果命令成功就返回成功；如果失败，就把命令输出的错误信息整理出来并返回失败。

调用关系：它是后面两个测试交给共享测试逻辑使用的“造场景工具”。共享断言函数需要先制造一个目录别名，再检查文件系统是否能把这个别名解析回真实目录；这里负责 Windows 上具体怎么制造这个别名。

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

async fn file_system_canonicalize_resolves_directory_junction(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：这个测试确认普通的路径标准化功能能识别 Windows 目录联接点，并最终得到真实目录路径。它会分别测试本地实现和远程实现。

数据流：输入是测试框架传进来的 FileSystemImplementation，表示这次要测本地文件系统还是远程文件系统 → 它把这个实现类型和 create_directory_junction 交给共享测试函数 → 共享测试函数负责建目录、建联接点、调用 canonicalize 并判断结果是否正确，最后返回测试成功或失败。

调用关系：它本身不写完整测试步骤，而是像一个 Windows 专用入口，把“用 mklink /J 创建目录联接点”这件事告诉 shared::assert_canonicalize_resolves_directory_alias。真正的通用检查流程由共享测试模块执行。

调用图：调用 1 个内部函数（assert_canonicalize_resolves_directory_alias）。

async fn file_system_sandboxed_canonicalize_resolves_directory_junction(
    implementation: FileSystemImplementation,
) -> Result<()>

作用：这个测试确认在沙箱模式下，路径标准化也能正确解析 Windows 目录联接点。沙箱可以理解成给文件访问加了围栏，测试是为了确保加了围栏后仍然不会认错路。

数据流：输入是要测试的文件系统实现类型，本地或远程 → 它把实现类型和 create_directory_junction 传给共享的沙箱测试函数 → 共享函数搭建目录联接点和沙箱环境，再检查沙箱版 canonicalize 是否能返回正确的真实路径，并把测试结果传回来。

调用关系：它是沙箱路径解析测试的 Windows 版本入口。它把平台特有的“怎么创建目录联接点”交代清楚，然后把主要验证工作交给 shared::assert_sandboxed_canonicalize_resolves_directory_alias。

调用图：调用 1 个内部函数（assert_sandboxed_canonicalize_resolves_directory_alias）。

async fn direct_file_system_rejects_non_native_uri_as_invalid_input()

作用：这是一个异步测试，用来确认 DirectFileSystem 遇到非本机文件 URI 时会拒绝它，并把错误类型标成“无效输入”。有人改动文件读取逻辑时，这个测试能防止把不该接受的路径放进来。

数据流：它先调用 non_native_uri 得到一个当前系统不该接受的文件地址 → 把这个地址交给 DirectFileSystem.read_file，并且不启用 sandbox（沙箱，可以理解成限制文件访问范围的保护栏）→ 期望读文件失败，然后检查失败原因必须是 io::ErrorKind::InvalidInput。它不产生文件内容，也不改动磁盘，只验证错误是否符合预期。

调用关系：它是这个测试文件的主角，由测试框架 tokio 在运行测试时自动执行。它把“构造特殊 URI”的小活交给 non_native_uri，最后用 assert_eq! 对比实际错误类型和期望错误类型。

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

fn non_native_uri() -> PathUri

作用：这个辅助函数专门造出一个“能被解析、但不是当前操作系统原生写法”的文件 URI。这样测试可以稳定地拿到一个应该被拒绝的输入。

数据流：它根据当前编译平台选择一段字符串：在 Unix 上用类似网络共享的 file://server/share/file.txt，在 Windows 上用类似 Unix 路径的 file:///usr/local/file.txt → 调用 PathUri::parse 把字符串解析成 PathUri → 如果解析成功就返回这个 PathUri；如果连解析都失败，就 panic，也就是直接让测试崩掉，因为测试前提不成立。

调用关系：它只被 direct_file_system_rejects_non_native_uri_as_invalid_input 调用，作用是提供测试材料。它自己依赖 PathUri::parse 来确认这个地址在语法上是合法 URI；如果不是合法 URI，就用 panic! 明确告诉测试作者：这里准备的样本有问题。

调用图：调用 1 个内部函数（parse）；被 1 处调用（direct_file_system_rejects_non_native_uri_as_invalid_input）；外部调用 1 个（panic!）。

async fn remote_file_system_sends_path_and_sandbox_cwd_uris_without_native_conversion()

作用：这是主测试。它验证远程读文件时，Windows 风格路径、网络共享路径，以及沙箱里的当前目录 URI，都会被照原样发送，不会按运行测试的这台机器的路径规则转换。

数据流：它先启动一个会记录请求参数的假服务器，拿到一个 WebSocket 地址；然后创建远程文件系统客户端，准备两条特殊路径和一个带当前目录的沙箱设置；接着分别调用 read_file。每次调用都会让客户端发出读文件请求，假服务器把请求参数存下来并回一个空文件。最后测试把服务器抓到的参数和自己预先算好的参数比较，确认进去的 URI 和沙箱信息，出来时仍是同一套信息，没有被改写。

调用关系：它是整个文件的入口测试。它会调用 record_read_file_params 搭建假服务器，用 non_native_cwd 生成“不是本机风格”的当前目录，并通过项目里的权限构造函数做出沙箱。真正的网络消息读取、写入和初始化握手，都交给下面几个辅助函数完成。

调用图：调用 8 个内部函数（new, websocket_url, new, non_native_cwd, record_read_file_params, from_permission_profile_with_cwd, from_runtime_permissions, restricted）；外部调用 2 个（assert_eq!, vec!）。

async fn record_read_file_params(
    expected_requests: usize,
) -> (
    String,
    oneshot::Receiver<Vec<FsReadFileParams>>,
    tokio::task::JoinHandle<()>,
)

作用：这个函数搭一个临时的假远程服务器，用来接收客户端发来的读文件请求，并把请求参数录下来。它让测试不用连接真正的服务器，也能看清客户端到底发了什么。

数据流：输入是预计要收到多少个读文件请求。它绑定本机一个随机空闲端口，生成 WebSocket 地址；再开一个后台任务，等待客户端连进来。连接成功后，它先完成初始化握手，然后循环读取指定数量的 JSON-RPC 请求，只接受 fs/readFile，请求里的参数会被反序列化成 FsReadFileParams 并放进列表。每收到一个请求，它都会回一个空的读文件响应。最后它通过一次性通道把收集到的参数发回给测试，并返回服务器地址、接收结果的通道和后台任务句柄。

调用关系：它由主测试 remote_file_system_sends_path_and_sandbox_cwd_uris_without_native_conversion 调用，是测试里的“录音机”。它自己会调用 complete_websocket_initialize 先走完协议开场白，再用 read_jsonrpc_websocket 收请求，用 write_jsonrpc_websocket 发回复。

调用图：调用 3 个内部函数（complete_websocket_initialize, read_jsonrpc_websocket, write_jsonrpc_websocket）；被 1 处调用（remote_file_system_sends_path_and_sandbox_cwd_uris_without_native_conversion）；外部调用 11 个（new, bind, with_capacity, Response, format!, channel, panic!, from_value, to_value, spawn (+1 more)）。

fn non_native_cwd() -> PathUri

作用：这个函数造出一个“故意不像当前系统本地路径”的当前目录 URI。这样测试才能发现代码有没有擅自把远端路径改成本机路径。

数据流：它不接收外部输入，而是根据编译目标选择一个字符串：在 Unix 系统上用类似 Windows 网络共享的 file://server/share/checkout，在 Windows 上用类似 Unix 的 file:///usr/local/checkout。然后它把这个字符串解析成 PathUri 并返回。

调用关系：它只被主测试调用，用来填进沙箱上下文。它的作用像一个试金石：如果后续发送请求时路径被本机化，这种非本机风格的地址很容易暴露问题。

调用图：调用 1 个内部函数（parse）；被 1 处调用（remote_file_system_sends_path_and_sandbox_cwd_uris_without_native_conversion）。

async fn complete_websocket_initialize(websocket: &mut WebSocketStream<TcpStream>)

作用：这个函数帮假服务器完成客户端启动时必须经过的握手。没有这一步，客户端还没进入正式工作状态，后面的读文件请求可能不会按正常流程发送。

数据流：它拿到已经建立好的 WebSocket 连接。先从连接里读一条 JSON-RPC 消息，要求它必须是 initialize 请求；然后写回一个带 session_id 的 initialize 响应；接着再读一条消息，要求它是 initialized 通知。完成后不返回业务数据，只是把这条连接推进到“已初始化”的状态。

调用关系：它由 record_read_file_params 在后台服务器里调用，发生在接收 fs/readFile 请求之前。它内部复用 read_jsonrpc_websocket 读消息，复用 write_jsonrpc_websocket 写响应。

调用图：调用 2 个内部函数（read_jsonrpc_websocket, write_jsonrpc_websocket）；被 1 处调用（record_read_file_params）；外部调用 3 个（Response, panic!, to_value）。

async fn read_jsonrpc_websocket(websocket: &mut WebSocketStream<TcpStream>) -> JSONRPCMessage

作用：这个函数从 WebSocket 连接里读出一条 JSON-RPC 消息。它把底层的网络帧转换成测试能直接判断的请求、响应或通知。

数据流：输入是一条可读写的 WebSocket 连接。它最多等 1 秒读取下一帧；如果读到文本帧，就按 JSON 文本解析；如果读到二进制帧，就按 JSON 字节解析；如果是 ping 或 pong 这类心跳包，就跳过继续等。成功时返回 JSONRPCMessage；如果超时、连接断开、内容不是合法 JSON-RPC，测试会直接失败。

调用关系：它是本文件几个测试辅助函数的底层读消息工具。complete_websocket_initialize 用它读初始化相关消息，record_read_file_params 用它读真正的 fs/readFile 请求。

调用图：被 2 处调用（complete_websocket_initialize, record_read_file_params）；外部调用 6 个（from_secs, next, panic!, from_slice, from_str, timeout）。

async fn write_jsonrpc_websocket(
    websocket: &mut WebSocketStream<TcpStream>,
    message: JSONRPCMessage,
)

作用：这个函数把一条 JSON-RPC 消息写进 WebSocket 连接。测试里的假服务器用它给客户端回话。

数据流：输入是一条 WebSocket 连接和一个 JSONRPCMessage。它先把消息序列化成 JSON 字符串，再包装成 WebSocket 文本帧发出去。发送成功后不返回内容；如果消息不能序列化或网络写入失败，测试会直接失败。

调用关系：它是本文件的底层写消息工具。complete_websocket_initialize 用它回复初始化请求，record_read_file_params 用它回复每个 fs/readFile 请求。

调用图：被 2 处调用（complete_websocket_initialize, record_read_file_params）；外部调用 3 个（send, to_string, Text）。

async fn sandboxed_file_system_rejects_non_native_uri_as_invalid_input()

作用：这是主测试函数，用来确认沙盒文件系统会拒绝非当前系统原生格式的文件 URI。有人改动文件读取或路径处理代码时，这个测试能及时发现“把不该接受的地址接受了”的问题。

数据流：它先读取当前可执行文件的位置，创建运行时路径信息；再用这些信息创建一个沙盒文件系统。接着它构造一个权限很紧的沙盒配置，并从 non_native_uri 拿到一个“格式合法但不适合当前系统”的文件地址。然后它让文件系统去读这个地址，预期会失败；最后检查失败原因是不是 InvalidInput。结果是：没有读出文件，而是得到一个明确的“输入无效”错误。

调用关系：这是整个文件的核心测试入口，由测试框架 tokio 在运行异步测试时调用。它自己负责搭好测试环境，调用 non_native_uri 准备特殊输入，再把这个输入交给 SandboxedFileSystem.read_file。最后用 assert_eq! 检查错误类型，证明沙盒文件系统在第一道关口就正确拒绝了这个地址。

调用图：调用 6 个内部函数（new, new, non_native_uri, from_permission_profile, from_runtime_permissions, restricted）；外部调用 3 个（new, assert_eq!, current_exe）。

fn non_native_uri() -> PathUri

作用：这个辅助函数负责制造一个“不是当前操作系统原生文件路径”的 URI，专门给测试使用。它让主测试不用关心 Unix 和 Windows 的差异。

数据流：它不接收外部参数，而是根据编译目标判断当前系统：在 Unix 上使用类似 Windows 网络共享的 file://server/share/file.txt；在 Windows 上使用类似 Unix 路径的 file:///usr/local/file.txt。然后它把这段文字交给 PathUri::parse 解析成 PathUri 对象。解析成功就返回这个 URI；如果解析失败，就直接 panic，表示测试数据本身写错了。

调用关系：它只被 sandboxed_file_system_rejects_non_native_uri_as_invalid_input 调用，作用是提供测试用的特殊输入。它把“跨平台差异”藏在自己内部，让主测试能专心验证沙盒文件系统的行为：遇到这种非原生 URI 时必须拒绝读取。

调用图：调用 1 个内部函数（parse）；被 1 处调用（sandboxed_file_system_rejects_non_native_uri_as_invalid_input）；外部调用 1 个（panic!）。

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

作用：这个测试确认：当文件大小刚好等于两个完整读取块时，流式读取会正好返回两个块，不会额外吐出一个空块，也不会漏掉最后一块。

数据流：它先启动测试用执行服务器，连上文件系统接口，再创建一个临时文件，内容是 2 个 1MB 的字节块。然后它用流式读取把文件读成一串数据块，最后检查结果长度是不是正好是两个 1MB。输入是临时文件路径和文件内容；输出是断言通过或失败；过程中不会保留长期状态。

调用关系：这是对高层文件系统接口的黑盒测试。它先通过 exec_server 启动服务，再用 connect_file_system 拿到远程文件系统对象，接着借助 PathUri::from_path 把普通路径变成接口能识别的路径格式。它不直接碰底层打开/关闭协议，而是验证上层 read_file_stream 的整体行为。

调用图：调用 3 个内部函数（exec_server, connect_file_system, from_path）；外部调用 4 个（new, assert_eq!, write, vec!）。

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

作用：这个测试确认：一个流式读文件操作结束后，服务器会把占用的打开文件名额还回来。否则读很多次小文件后，即使每次都读完，也可能因为名额耗尽而失败。

数据流：它启动服务器，连接文件系统，创建一个只含有 repeated 的小文件。然后循环读这个文件，次数比允许同时打开的文件上限还多一次。每次都把流收集成完整内容，并检查内容正确。进去的是同一个文件路径；每轮读完后服务器应该释放内部文件句柄；出来的是每轮都成功读到同样内容。

调用关系：它走的是和真实使用最接近的高层路径：exec_server 启动服务，connect_file_system 取得文件系统接口，然后反复调用 read_file_stream。它关心的不是单次读取是否能成功，而是多次完成后的资源回收是否正常。

调用图：调用 3 个内部函数（exec_server, connect_file_system, from_path）；外部调用 3 个（new, assert_eq!, write）。

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

作用：这个测试确认：流式读文件目前不支持平台沙箱时，会明确报“不支持”，而不是假装支持或绕过限制。沙箱可以理解成给文件访问划出的安全边界。

数据流：它创建一个临时文件，并用 read_only_sandbox 做出一个只允许读该目录的沙箱配置。然后它尝试在这个沙箱下进行流式读取。结果应该不是文件内容，而是一个 Unsupported 类型的错误，并且错误文字说明“streaming file reads do not support platform sandboxing”。

调用关系：这个测试先用 connect_file_system 拿到高层文件系统接口，再调用 read_only_sandbox 生成沙箱上下文，最后交给 read_file_stream。它验证的是接口在遇到暂不支持的安全模式时，会主动拒绝，而不是继续往下读文件。

调用图：调用 4 个内部函数（exec_server, connect_file_system, read_only_sandbox, from_path）；外部调用 4 个（new, assert_eq!, panic!, write）。

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

作用：这个 Unix 专用测试确认：读取 FIFO（命名管道，一种像文件但会等待另一端写入的通信口）时，普通读取和流式读取都会立刻拒绝，而不是一直等写入者导致测试或程序卡死。

数据流：它在临时目录里用 mkfifo 创建一个 FIFO，然后分别调用普通 read_file 和流式 read_file_stream。每个调用都包在 1 秒超时里。正确结果是：两种读取都在超时前返回错误，错误内容说明这个路径不是普通文件。输入是 FIFO 路径；处理是尝试读取并等待错误；输出是两个相同的拒绝错误。

调用关系：它通过 exec_server 和 connect_file_system 使用真实的远程文件读取路径。它还借助系统命令 mkfifo 制造特殊文件，并用 timeout 防止测试真的卡住。这个测试覆盖的是 Unix 系统上很容易被忽略的“特殊文件不能当普通文件读”的安全边界。

调用图：调用 3 个内部函数（exec_server, connect_file_system, from_path）；外部调用 8 个（from_secs, new, bail!, assert_eq!, new, format!, panic!, timeout）。

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

作用：这个 Windows 专用测试确认：读取命名管道时会快速失败，不会挂住。命名管道也是一种进程间通信入口，不是普通磁盘文件。

数据流：它先启动服务器并连接文件系统，然后创建两个 Windows 命名管道路径：一个用于普通读取测试，一个用于流式读取测试。每次读取都设置 1 秒超时。正确结果是两个读取都返回 InvalidInput 错误。输入是命名管道路径；输出是明确的无效输入错误；过程中不应等待另一端连接。

调用关系：它和 Unix 的 FIFO 测试作用相似，只是换成 Windows 的命名管道机制。它通过 connect_file_system 走高层读取接口，通过 Windows 的 ServerOptions 创建测试用管道，确保服务端文件读取逻辑不会误把管道当普通文件。

调用图：调用 4 个内部函数（exec_server, connect_file_system, new, from_path）；外部调用 6 个（from_secs, assert_eq!, format!, panic!, new, timeout）。

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

作用：这个 Unix 专用测试确认：流式读取一旦打开了某个文件，后续就继续读这个已打开的文件本身，而不是每次按路径重新找文件。这样即使原路径被替换，正在读的流也不会突然读到另一个文件。

数据流：它先创建一个内容为很多个 a 的文件，并开始流式读取。读完第一个大块后，它把原路径上的文件删除，再把另一个内容为 b 的文件改名到同一路径。随后继续读取流。正确结果是剩下的内容仍然是原文件里的 a，而不是新文件里的 b；最后流正常结束。

调用关系：它通过高层 read_file_stream 验证底层打开文件句柄的语义。connect_file_system 负责连到服务端，PathUri::from_path 把路径交给接口；remove_file 和 rename 用来模拟“有人在读取过程中替换了文件”。这个测试说明流读取依赖已打开的文件，而不是依赖会变化的路径名。

调用图：调用 3 个内部函数（exec_server, connect_file_system, from_path）；外部调用 6 个（new, assert_eq!, remove_file, rename, write, vec!）。

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

作用：这个测试直接检查底层协议的按块读取能力：客户端可以指定任意偏移位置和长度来读文件，不必从头到尾顺序读取。

数据流：它启动服务器，建立 ExecServerClient 连接，创建一个内容为 0123456789 的文件。然后用 fs_open 打开文件拿到 handle_id（文件读取的临时编号），接着多次调用 fs_read_block，分别读取不同位置和不同长度的数据。最后检查每次返回的字节和 eof（是否到文件末尾）标记是否正确，并用 fs_close 关闭句柄。

调用关系：这个测试绕过高层 read_file_stream，直接使用协议级的 fs_open、fs_read_block、fs_close。它用于确认服务端最底层的分段读取规则没问题，因为高层流式读取也是建立在这种“打开句柄、按块读、关闭句柄”的能力之上的。

调用图：调用 2 个内部函数（exec_server, from_path）；外部调用 7 个（new, new_v4, new, assert_eq!, connect_websocket, new, write）。

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

作用：这个测试确认：同一条连接最多只能同时打开 128 个文件读取句柄，超过就会被拒绝；但关闭一个句柄后，又可以继续打开新的。这样可以防止一个客户端把服务器文件资源占满。

数据流：它启动服务器并创建一个测试文件，然后用同一个客户端连接连续打开 128 次，每次都保存返回的 handle_id。第 129 次打开应该失败，并返回固定错误码和说明。随后它关闭其中一个旧句柄，再尝试打开一次，应该成功。输入是同一个文件路径和多个新句柄编号；处理是反复打开、触发上限、关闭一个、再打开；输出是限制被正确执行且容量能恢复。

调用关系：它直接使用 ExecServerClient 的底层 fs_open 和 fs_close，而不是高层流式读取接口。这样能精确测试“每连接打开文件上限”这条协议规则。exec_server 提供服务端，connect_websocket 建立客户端连接，Uuid 用来生成不同的句柄编号。

调用图：调用 2 个内部函数（exec_server, from_path）；外部调用 8 个（new, new_v4, with_capacity, bail!, assert_eq!, connect_websocket, new, write）。

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

作用：这个测试确认：客户端传来的文件读取句柄编号不能超过 32 字节。限制编号长度可以避免协议里出现过大的、恶意的或不合理的标识符。

数据流：它启动服务器，连上客户端，创建一个临时文件。然后调用 fs_open，但故意传入 33 个 x 组成的 handle_id。正确结果是服务端拒绝请求，返回固定错误码和“file read handle ID must not exceed 32 bytes”的错误信息。

调用关系：它直接测协议入口 fs_open 的输入校验。和高层流式读取不同，这里故意构造异常参数，确认服务器在真正打开文件前就拦下坏请求。exec_server 启动测试服务，connect_websocket 建立协议连接。

调用图：调用 2 个内部函数（exec_server, from_path）；外部调用 6 个（new, bail!, assert_eq!, connect_websocket, new, write）。

fn connect_file_system(websocket_url: &str) -> Result<Arc<dyn ExecutorFileSystem>>

作用：这个小工具函数把测试服务器的 WebSocket 地址包装成一个可用的文件系统接口。测试里不想每次都重复写连接环境的创建代码，所以把这一步抽出来。

数据流：它接收一个 websocket_url 字符串，调用 Environment::create_for_tests 创建测试环境，然后从环境里取出 ExecutorFileSystem。进去的是服务地址；处理是搭好测试环境；出来的是一个可共享的文件系统对象 Arc<dyn ExecutorFileSystem>，Arc 可以理解成多人共用同一个对象的安全引用。

调用关系：多个高层文件读取测试都会先调用它，包括流式读取、沙箱拒绝、FIFO/命名管道拒绝、路径替换等测试。它本身不读文件，只负责把 exec_server 给出的地址变成测试可以调用的文件系统门面。

调用图：调用 1 个内部函数（create_for_tests）；被 6 处调用（completed_streams_release_handle_capacity, file_reads_reject_fifo_without_waiting_for_a_writer, file_reads_reject_named_pipes, stream_keeps_reading_the_open_file_after_path_replacement, stream_rejects_platform_sandbox, stream_stops_after_an_exact_block_boundary）。

fn read_only_sandbox(path: std::path::PathBuf) -> FileSystemSandboxContext

作用：这个小工具函数创建一个“只允许读取指定路径”的沙箱配置，用来测试流式读取遇到平台沙箱时是否会拒绝。

数据流：它接收一个本地路径，先把它转换成 AbsolutePathBuf（绝对路径格式，避免相对路径带来歧义），再创建一个受限文件系统策略：这个路径只给读权限，网络也设为受限。最后把这些权限包装成 FileSystemSandboxContext 返回。

调用关系：它只被 stream_rejects_platform_sandbox 调用。那个测试需要一个真实的沙箱上下文来触发“不支持平台沙箱”的分支；这个函数就是专门造出这份测试输入的工具。

调用图：调用 4 个内部函数（from_permission_profile, from_runtime_permissions, restricted, from_absolute_path）；被 1 处调用（stream_rejects_platform_sandbox）；外部调用 1 个（vec!）。

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

作用：检查普通的缓冲式 HTTP 请求是否一定按“一次性返回完整响应”的方式发送。即使调用方误填了流式相关字段，客户端也应该把它改成非流式，避免服务器按错误模式处理。

数据流：测试先启动假服务器；假服务器读到客户端发来的 http/request，检查里面的 method、url、request_id 和 stream_response 已被改成正确的缓冲模式；然后假服务器返回状态码 200 和 body。客户端调用 http_request 后，测试拿到完整响应并比对内容，最后关闭客户端并等待假服务器结束。

调用关系：这是一个顶层测试。它先调用 spawn_scripted_exec_server 搭好假服务器，再通过 ScriptedExecServer::connect_client 连接真实客户端；假服务器内部用 JsonRpcPeer::read_http_request 读请求，用 JsonRpcPeer::write_response 回响应。timeout 用来防止测试挂住。

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

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

作用：检查流式 HTTP 响应是否用客户端自己生成的请求编号，并且响应体碎片能按顺序送到调用方。这样可以防止调用方重复使用同一个编号时，不同请求的数据混在一起。

数据流：测试让客户端发起第一个流式请求；假服务器确认线上实际 request_id 是 http-1，而不是调用方随便给的值；随后先返回响应头，再连续发送 hello、world、感叹号三个 body 片段。测试从 body_stream 里逐块读取并拼成完整字节串。然后它再发第二个流式请求，确认客户端已经清理了上一个流，并使用新的 http-2 编号。

调用关系：这是流式响应的主路径测试。它依赖 spawn_scripted_exec_server 建假服务器；测试脚本通过 JsonRpcPeer::read_http_request 接收请求，通过 JsonRpcPeer::write_response 发响应头，通过 JsonRpcPeer::write_body_delta 发 body 片段；客户端侧通过 http_request_stream 暴露响应头和可读取的 body 流。

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

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

作用：检查一种微妙情况：服务器先把“结束帧”排进队列，调用方却没读就丢掉 body 流。客户端必须清掉这条旧路由，让下一次请求使用新的编号。

数据流：假服务器先收到第一个流式请求，立刻发送一个 done=true 的空 body 结束通知，再返回响应头。客户端拿到响应头后直接丢弃 body_stream，不读取已经排队的结束帧。随后客户端发起第二个流式请求；假服务器确认它用的是 http-2，并返回 204 响应。测试确认第二次请求不受第一次残留结束帧影响。

调用关系：这是流清理逻辑的边界测试。它由 spawn_scripted_exec_server 启动假服务器；假服务器用 JsonRpcPeer::write_body_delta 故意把终止消息提前塞进去，再用 JsonRpcPeer::read_http_request 观察下一次请求是否拿到新编号。

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

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

作用：检查流式请求在还没等到响应头时被取消后，旧请求后来到达的 body 片段会不会被忽略。这样可以避免一个已经取消的请求把脏数据塞进后面的新请求里。

数据流：测试先启动一个流式请求，并等假服务器确认已经看见它；随后测试主动中止这个等待响应头的任务。假服务器之后接收第二个请求，先故意发送一条属于旧 http-1 的 stale 数据，再正常给 http-2 返回响应和 fresh 数据。测试读取第二个 body 流，只应该得到 fresh。

调用关系：这是取消场景测试。它使用 oneshot channel（一条只能发一次信号的小通道）协调“服务器已看到请求”和“测试可以取消任务”的时机；使用 tokio::spawn 启动可中止的客户端请求；假服务器用 JsonRpcPeer 写入旧 delta 和新 delta，验证客户端路由不会串台。

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

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

作用：检查调用方拿到响应头后直接丢掉 body 流时，客户端是否会删除旧路由，并忽略随后才来的旧 body 数据。这样后续请求不会收到前一个请求的残留内容。

数据流：第一个请求返回响应头后，测试立刻 drop 掉 body_stream，并用信号通知假服务器。假服务器收到信号后发送一条属于旧 http-1 的 stale 数据，再接收第二个请求并给 http-2 发送 fresh 数据。测试读取第二个 body 流，确认只拼出 fresh。

调用关系：这是“丢弃已返回 body 流”的清理测试。它用 spawn_scripted_exec_server 搭服务端，用两个 oneshot channel 控制旧数据发送的先后顺序；JsonRpcPeer 负责收请求、写响应、写 body 通知；客户端 http_request_stream 的内部清理行为是被验证对象。

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

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

作用：检查流式响应还没收到结束帧时，如果底层 WebSocket 连接断开，body 流会不会明确报错。正确行为是告诉调用方“传输断了”，而不是一直等下去。

数据流：假服务器收到流式请求后只返回响应头，不发送 done=true 的结束 body 帧，然后服务器任务结束，相当于连接断开。客户端拿到响应头后继续读 body_stream；测试期望下一次读取返回错误，并且错误信息说明 http-1 因传输断开失败。

调用关系：这是断线处理测试。它通过 spawn_scripted_exec_server 让假服务器自然结束连接；JsonRpcPeer::write_response 只发送头部响应；客户端 body_stream.recv 是最终观察点，用来确认内部传输断开事件被转成了流错误。

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

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

作用：检查 body 片段队列已经满了时，如果连接又断开，客户端仍然能在读完已排队数据后报告断线错误。这样调用方不会把“队列满后断线”误认为正常结束。

数据流：假服务器在响应头到达前，先发送刚好填满客户端 body 队列容量的 256 个小片段，然后返回响应头并结束连接。客户端拿到 body_stream 后不断读取，先读出这些已排队片段；读完后应该得到一个传输断开的错误，而不是 None 这种干净结束信号。

调用关系：这是队列满加断线的组合边界测试。它使用常量 HTTP_BODY_DELTA_CHANNEL_CAPACITY 控制发送数量；假服务器用 JsonRpcPeer::write_body_delta 填满队列；测试循环读取 body_stream，并用 bail 在出现错误的干净 EOF 时立刻判失败。

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

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

作用：检查当服务器发送 body 片段太快、超过客户端内部队列承受能力时，客户端会明确报“响应体被截断”。这比静悄悄结束更安全，因为调用方不会误用缺了一截的数据。

数据流：假服务器在响应头之前发送 1024 个 body 片段，数量超过客户端队列容量；然后返回响应头，但保持连接不断开，避免错误被误判成网络断线。客户端读取 body_stream，先读到一部分已排队片段，随后应该收到“body delta channel filled before delivery”的明确错误。测试最后发信号让服务器任务结束。

调用关系：这是背压测试。背压可以理解为“下游来不及收，上游还在倒水，水桶满了”。它用 oneshot channel 暂停假服务器关闭连接；JsonRpcPeer 负责快速写入大量 delta；测试读取 body_stream 来确认客户端把队列溢出报告成协议错误。

调用图：调用 1 个内部函数（spawn_scripted_exec_server）；外部调用 5 个（new, assert_eq!, bail!, channel, timeout）。

async fn connect_client(&self) -> Result<ExecServerClient>

作用：把真实的 ExecServerClient 连接到这个测试刚启动的假 WebSocket 服务器。测试用它来走真实的公开连接路径，而不是绕过客户端内部逻辑。

数据流：它读取自己保存的 websocket_url 和固定的 CLIENT_NAME，组装 RemoteExecServerConnectArgs；然后调用 ExecServerClient::connect_websocket 建立连接。成功时返回一个可用于发 HTTP 请求的客户端；失败时把错误包装成更好懂的上下文。

调用关系：各个顶层测试在 spawn_scripted_exec_server 返回 ScriptedExecServer 后调用它。它把测试服务器和真实客户端接起来，后续通信再由客户端和 JsonRpcPeer 在 WebSocket 上完成。

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

async fn finish(self) -> Result<()>

作用：等待假服务器脚本跑完，并把服务器任务里的错误传回测试。没有它，测试可能在后台任务还没结束时就退出，漏掉服务器侧发现的问题。

数据流：它接收并消耗 ScriptedExecServer 本身，等待内部 tokio 任务结束；如果任务 join 失败或脚本返回错误，就把错误继续往外传；全部正常时返回 Ok。

调用关系：每个测试最后都会 drop 客户端，然后调用 finish。它是测试收尾步骤，确保 spawn_scripted_exec_server 启动的后台服务端没有悄悄失败。

async fn spawn_scripted_exec_server(script: F) -> Result<ScriptedExecServer>

作用：启动一个只服务一个客户端的假 exec-server，并把测试提供的“剧本”接到连接后面。它让每个测试都能精确规定服务器收什么、发什么。

数据流：它先在本机随机端口绑定 TCP 监听器，生成 ws:// 地址；然后启动后台任务等待客户端连接，完成 WebSocket 握手，创建 JsonRpcPeer，先完成初始化握手，再执行测试传入的脚本。函数返回 ScriptedExecServer，里面有连接地址和后台任务句柄。

调用关系：所有顶层测试都先调用它。它创建 JsonRpcPeer，并在内部调用 JsonRpcPeer::complete_initialize；之后把控制权交给测试脚本，脚本再用 JsonRpcPeer 的读写函数模拟服务器行为。

调用图：被 8 处调用（http_request_forces_buffered_request_params, http_response_body_stream_drops_queued_terminal_before_next_generated_id, http_response_body_stream_fails_when_transport_disconnects, http_response_body_stream_ignores_late_deltas_after_cancelled_request, http_response_body_stream_ignores_late_deltas_after_drop, http_response_body_stream_reports_backpressure_truncation, http_response_body_stream_reports_disconnect_when_queue_is_full, http_response_body_stream_uses_generated_ids_and_receives_ordered_deltas）；外部调用 5 个（bind, format!, spawn, timeout, accept_async）。

async fn complete_initialize(&mut self) -> Result<()>

作用：完成客户端连接后的初始化握手，并检查客户端发来的初始化内容是否正确。它相当于假服务器先和客户端“互相报到”，确认可以开始后续测试。

数据流：它先读取 initialize 请求，解析出 InitializeParams，并确认 client_name 是测试客户端名、没有恢复旧会话；然后回一个带 session_id 的成功响应；最后读取 initialized 通知。完成后，连接就进入可发送 HTTP 请求的状态。

调用关系：spawn_scripted_exec_server 在执行每个测试脚本前都会调用它。它内部把读取请求交给 JsonRpcPeer::read_request，把参数解析交给 decode_request_params，把响应发送交给 JsonRpcPeer::write_response，并用 JsonRpcPeer::read_notification 等待最后通知。

调用图：调用 4 个内部函数（read_notification, read_request, write_response, decode_request_params）；外部调用 1 个（assert_eq!）。

async fn read_http_request(&mut self) -> Result<(RequestId, HttpRequestParams)>

作用：从客户端读取一条类型明确的 http/request 调用，并把里面的参数解析成 HttpRequestParams。测试用它来检查客户端到底把什么 HTTP 请求发到了线上。

数据流：它等待下一条 JSON-RPC 请求，要求方法名必须是 http/request；然后取出请求参数并反序列化成 HttpRequestParams；最后返回 JSON-RPC 请求 id 和解析后的 HTTP 参数。

调用关系：几乎每个测试脚本都会调用它来接收客户端请求。它把通用读取工作交给 JsonRpcPeer::read_request，把参数转换交给 decode_request_params，返回的信息随后通常会被 assert_eq 检查，并被 JsonRpcPeer::write_response 用来回包。

调用图：调用 2 个内部函数（read_request, decode_request_params）。

async fn read_request(&mut self, expected_method: &str) -> Result<JSONRPCRequest>

作用：读取下一条 JSON-RPC 消息，并确认它是一条指定方法名的“请求”。如果收到的不是预期请求，它会立刻报错，让测试失败。

数据流：它从 WebSocket 读取一条 JSON-RPC 消息；如果消息不是 Request 类型，或 method 和 expected_method 不一致，就返回错误；如果匹配，就把 JSONRPCRequest 返回给调用方。

调用关系：JsonRpcPeer::complete_initialize 和 JsonRpcPeer::read_http_request 都靠它做基础检查。它再往下调用 JsonRpcPeer::read_message 处理 WebSocket 和 JSON 解码细节。

调用图：调用 1 个内部函数（read_message）；被 2 处调用（complete_initialize, read_http_request）；外部调用 1 个（bail!）。

async fn read_notification(&mut self, expected_method: &str) -> Result<JSONRPCNotification>

作用：读取下一条 JSON-RPC 消息，并确认它是一条指定方法名的“通知”。通知是不需要响应的消息，这里主要用来验证初始化完成信号。

数据流：它先读取一条底层消息；如果不是 Notification 类型，或者方法名不等于 expected_method，就返回错误；符合预期时返回 JSONRPCNotification。

调用关系：目前主要由 JsonRpcPeer::complete_initialize 调用，用来等待 initialized 通知。它依赖 JsonRpcPeer::read_message 做实际网络读取和 JSON 解析。

调用图：调用 1 个内部函数（read_message）；被 1 处调用（complete_initialize）；外部调用 1 个（bail!）。

async fn write_response(&mut self, id: RequestId, result: T) -> Result<()>

作用：向客户端发送一条成功的 JSON-RPC 响应。测试用它模拟服务器对 initialize 或 http/request 的正常回答。

数据流：它接收请求 id 和任意可序列化的 result；先把 result 转成 JSON 值，再包装成 JSONRPCResponse，最后通过 WebSocket 发出去。发送成功返回 Ok，编码或网络发送失败则返回错误。

调用关系：初始化握手和多个测试脚本都会用它回客户端。它把具体写 WebSocket 的工作交给 JsonRpcPeer::write_message。

调用图：调用 1 个内部函数（write_message）；被 1 处调用（complete_initialize）；外部调用 2 个（Response, to_value）。

async fn write_body_delta(&mut self, delta: HttpRequestBodyDeltaNotification) -> Result<()>

作用：向客户端发送一条流式 HTTP 响应体片段通知。测试用它模拟服务器把 body 一块一块推给客户端。

数据流：它接收 HttpRequestBodyDeltaNotification，其中包含 request_id、顺序号、字节片段、是否结束和错误信息；把它转成 JSON，并包装成 method 为 http/request/bodyDelta 的通知；最后写入 WebSocket。

调用关系：所有流式响应测试都用它制造正常片段、结束帧、旧请求残留片段、队列溢出片段等场景。它底层调用 JsonRpcPeer::write_message 完成实际发送。

调用图：调用 1 个内部函数（write_message）；外部调用 2 个（Notification, to_value）。

async fn read_message(&mut self) -> Result<JSONRPCMessage>

作用：从 WebSocket 连接里读取一条原始消息，并解析成 JSON-RPC 消息。它是所有“读请求、读通知”的底层入口。

数据流：它在固定超时时间内等待 WebSocket 下一条消息；如果连接提前关闭、读取失败、收到关闭帧或收到非文本/二进制消息，就报错。若收到文本或二进制内容，就按 JSON 解析成 JSONRPCMessage 并返回。

调用关系：JsonRpcPeer::read_request 和 JsonRpcPeer::read_notification 都调用它。它把网络层的 Message 转换成测试脚本更容易使用的协议层对象。

调用图：被 2 处调用（read_notification, read_request）；外部调用 5 个（next, bail!, from_slice, from_str, timeout）。

async fn write_message(&mut self, message: JSONRPCMessage) -> Result<()>

作用：把一条 JSON-RPC 消息编码成文本，并通过 WebSocket 发给客户端。它是所有服务器侧发送动作的底层出口。

数据流：它接收 JSONRPCMessage，先序列化成字符串，再包装成 WebSocket 文本消息；随后在超时时间内发送。成功时没有额外输出；超时、编码失败或发送失败都会变成错误。

调用关系：JsonRpcPeer::write_response 和 JsonRpcPeer::write_body_delta 都调用它。上层决定要发响应还是通知，它负责统一完成编码和网络发送。

调用图：被 2 处调用（write_body_delta, write_response）；外部调用 4 个（send, to_string, timeout, Text）。

fn decode_request_params(request: &JSONRPCRequest) -> Result<T>

作用：把 JSON-RPC 请求里的 params 字段转换成测试需要的具体类型。它让测试不用手动从 JSON 里一个字段一个字段抠数据。

数据流：它接收一个 JSONRPCRequest，先确认里面有 params；然后用反序列化把 JSON 值转成调用方指定的 Rust 类型。成功时返回这个具体类型；缺少 params 或格式不匹配时返回带说明的错误。

调用关系：JsonRpcPeer::complete_initialize 用它解析 InitializeParams，JsonRpcPeer::read_http_request 用它解析 HttpRequestParams。它是协议 JSON 和强类型测试断言之间的小桥梁。

调用图：被 2 处调用（complete_initialize, read_http_request）；外部调用 1 个（from_value）。

async fn exec_server_http_request_buffers_response_body() -> anyhow::Result<()>

作用：测试普通 HTTP 请求模式：exec-server 发出一次 POST 请求，并把整个 HTTP 响应体攒好后放进 JSON-RPC 响应里返回。有人改动 HTTP 请求功能时，这个测试能确认“非流式返回”没有坏。

数据流：测试先启动 exec-server，并发送初始化请求；然后创建本地 HTTP 监听器，把一个带请求头和请求体的 http/request 发给 exec-server。监听器收到真实 HTTP 请求后检查请求行、请求头、请求体，再回一个固定长度的 201 响应。最后测试从 exec-server 等到对应 JSON-RPC 响应，确认状态码、响应头和完整响应体都和假服务器写出的一样。

调用关系：它是一个完整场景测试，开头调用 exec_server 和 initialize_exec_server 准备服务；中间用 accept_http_request 抓住 exec-server 发来的 HTTP 请求，用 respond_with_status_and_headers 回包；最后用 wait_for_response 取回 JSON-RPC 结果，并用 response_header 辅助检查响应头。

调用图：调用 5 个内部函数（exec_server, accept_http_request, initialize_exec_server, respond_with_status_and_headers, wait_for_response）；外部调用 5 个（bind, assert_eq!, format!, to_value, vec!）。

async fn exec_server_http_request_streams_response_body_notifications() -> anyhow::Result<()>

作用：测试流式 HTTP 响应：exec-server 应该先返回响应状态和响应头，然后把响应体分成多条通知按顺序发出来。这样可以验证大响应或持续响应不会被错误地一次性缓存。

数据流：测试启动并初始化 exec-server 后，请它用 GET 请求访问本地监听器，并设置 stream_response: true。监听器确认收到的请求正确，然后写出分块传输的 HTTP 响应。测试先读取第一条 JSON-RPC 事件，确认它是请求结果，里面有状态和响应头但没有响应体；之后继续收集 bodyDelta 通知，把每段字节拼起来，检查序号连续、内容是 hello world，最后一帧标记完成且没有错误。

调用关系：这个场景依赖 initialize_exec_server 做握手，accept_http_request 抓请求，respond_with_chunked_body 制造分块 HTTP 响应，collect_response_body_deltas 收尾读取所有流式通知。它刻意检查响应事件和 bodyDelta 通知的先后顺序。

调用图：调用 5 个内部函数（exec_server, accept_http_request, collect_response_body_deltas, initialize_exec_server, respond_with_chunked_body）；外部调用 7 个（bind, bail!, assert_eq!, format!, from_value, to_value, vec!）。

async fn exec_server_http_request_rejects_duplicate_stream_request_ids() -> anyhow::Result<()>

作用：测试流式请求的 requestId 不能在上一个流还没结束时重复使用。这个规则很重要，因为客户端要靠这个 ID 分清哪些 bodyDelta 属于哪一次请求。

数据流：测试先发起一个流式 GET 请求，假 HTTP 服务器返回一段分块数据但暂时不结束连接。exec-server 先返回这次请求的响应头信息，此时流还活着。测试随后用同一个 requestId 再发第二个流式请求，期待 exec-server 立刻返回 JSON-RPC 参数错误。最后测试放行第一个响应结束，收完它的 bodyDelta，再关闭服务。

调用关系：它使用 respond_with_chunked_body_until_finish 故意把第一个流卡住，让 ID 保持占用；用 wait_for_response 等第一个请求进入流式阶段；再通过 exec-server 的事件等待机制确认第二个请求变成错误；结束时调用 collect_response_body_deltas 把第一个流收干净。

调用图：调用 6 个内部函数（exec_server, accept_http_request, collect_response_body_deltas, initialize_exec_server, respond_with_chunked_body_until_finish, wait_for_response）；外部调用 8 个（bind, new, bail!, assert_eq!, format!, channel, to_value, spawn）。

async fn exec_server_http_request_honors_optional_timeout() -> anyhow::Result<()>

作用：测试 timeoutMs 这个超时参数确实是可选的：不填就不要超时，填了很短时间就应该按时失败。这样可以避免慢服务被误杀，也避免需要超时时一直挂住。

数据流：测试先发一个没有超时的 GET，请本地服务器延迟 100 毫秒再回复，最后确认 exec-server 仍然拿到了 slow-success。接着再发一个超时只有 10 毫秒的请求，同样让服务器延迟 100 毫秒，测试期待 exec-server 返回 JSON-RPC 错误。由于客户端超时后可能已经断开连接，测试还会判断写响应时出现的断管、连接重置或意外 EOF 是否属于正常现象。

调用关系：它复用 initialize_exec_server 做启动握手，用 accept_http_request 接住两次 HTTP 请求，用 respond_with_status_and_headers 模拟慢响应；成功路径通过 wait_for_response 检查，失败路径通过 wait_for_error_response 检查，并用 is_expected_peer_disconnect 分辨超时导致的正常断连。

调用图：调用 7 个内部函数（exec_server, accept_http_request, initialize_exec_server, is_expected_peer_disconnect, respond_with_status_and_headers, wait_for_error_response, wait_for_response）；外部调用 9 个（from_millis, bind, new, assert!, assert_eq!, format!, to_value, spawn, sleep）。

async fn initialize_exec_server(server: &mut ExecServerHarness) -> anyhow::Result<()>

作用：完成 exec-server 在测试里必须先做的 JSON-RPC 初始化握手。没有这一步，后面的 executor 方法通常还不能合法调用。

数据流：它接收一个测试用的 exec-server 连接，发送 initialize 请求，里面带客户端名字和空的恢复会话 ID；等到服务器返回初始化响应后，再发一条 initialized 通知。完成后不返回业务数据，只表示服务已经进入可用状态。

调用关系：四个主要测试都会先调用它。它内部把发送请求、等待响应、发送通知这三步串起来，其中等待响应交给 wait_for_response，实际通信由测试框架的 send_request 和 send_notification 完成。

调用图：调用 3 个内部函数（send_notification, send_request, wait_for_response）；被 4 处调用（exec_server_http_request_buffers_response_body, exec_server_http_request_honors_optional_timeout, exec_server_http_request_rejects_duplicate_stream_request_ids, exec_server_http_request_streams_response_body_notifications）；外部调用 2 个（json!, to_value）。

async fn wait_for_response(
    server: &mut ExecServerHarness,
    request_id: RequestId,
) -> anyhow::Result<T>

作用：等待某个指定 JSON-RPC 请求 ID 对应的成功响应，并把里面的 JSON 结果转成测试想要的类型。它让测试不用手写一遍遍“找响应、拆响应、反序列化”的代码。

数据流：它拿到 exec-server 连接和请求 ID 后，不断等事件，直到看到 ID 匹配的 JSON-RPC Response。随后取出 result 字段，把 JSON 数据转换成调用者指定的类型；如果等到的不是成功响应，或者转换失败，就返回错误。

调用关系：初始化流程和多个测试场景都会用它来拿成功结果。它把找事件的工作交给 wait_for_event，把 JSON 转 Rust 类型的工作交给 serde_json::from_value。

调用图：调用 1 个内部函数（wait_for_event）；被 4 处调用（exec_server_http_request_buffers_response_body, exec_server_http_request_honors_optional_timeout, exec_server_http_request_rejects_duplicate_stream_request_ids, initialize_exec_server）；外部调用 2 个（bail!, from_value）。

async fn wait_for_error_response(
    server: &mut ExecServerHarness,
    request_id: RequestId,
) -> anyhow::Result<codex_app_server_protocol::JSONRPCErrorError>

作用：等待某个指定 JSON-RPC 请求 ID 对应的错误响应。它主要用来测试“应该失败”的情况，比如短超时触发错误。

数据流：它接收 exec-server 连接和请求 ID，然后等到 ID 匹配的 JSON-RPC Error 事件。拿到后返回里面的错误对象，让测试检查错误码和错误消息；如果事件类型不对，就把情况当成测试失败。

调用关系：目前由超时测试 exec_server_http_request_honors_optional_timeout 使用。它和 wait_for_response 是一对：一个等成功结果，一个等失败结果，都依赖测试框架的 wait_for_event 来筛选事件。

调用图：调用 1 个内部函数（wait_for_event）；被 1 处调用（exec_server_http_request_honors_optional_timeout）；外部调用 1 个（bail!）。

async fn accept_http_request(listener: &TcpListener) -> anyhow::Result<CapturedHttpRequest>

作用：在测试里的假 HTTP 服务器上接收一条 HTTP/1.1 请求，并把肉眼可见的请求行、请求头、请求体都抓出来。它让测试能确认 exec-server 真正发到网络上的内容是否正确。

数据流：它从 TCP 监听器等待一个连接，最多等 5 秒。连上后逐行读取第一行请求行，再读取所有请求头，头名统一转成小写方便比较；如果有 content-length，就按长度继续读请求体。最后返回一个 CapturedHttpRequest，里面保留原始连接流，方便后续继续写 HTTP 响应。

调用关系：所有主测试都用它接住 exec-server 发出的真实 HTTP 请求。它是测试中“假网站”的入口，后续通常会把它返回的 stream 交给 respond_with_status_and_headers、respond_with_chunked_body 或 respond_with_chunked_body_until_finish 来回响应。

调用图：被 4 处调用（exec_server_http_request_buffers_response_body, exec_server_http_request_honors_optional_timeout, exec_server_http_request_rejects_duplicate_stream_request_ids, exec_server_http_request_streams_response_body_notifications）；外部调用 7 个（new, new, from_secs, new, accept, timeout, vec!）。

async fn respond_with_status_and_headers(
    mut stream: TcpStream,
    status: &str,
    headers: &[(&str, &str)],
    body: &[u8],
) -> anyhow::Result<()>

作用：向已经接收到的 TCP 连接写回一个普通的、带固定长度响应体的 HTTP 响应。它用于模拟简单服务器回包。

数据流：它拿到连接、状态文本、额外响应头和响应体字节。先拼出 HTTP 状态行、默认 content-type、content-length、关闭连接头和额外头；然后把这些头部和响应体写进 TCP 流并刷新。完成后返回成功或写入错误。

调用关系：普通缓存响应测试和超时测试会调用它。它通常接在 accept_http_request 后面，用来给 exec-server 一个明确长度的响应，从而测试 exec-server 是否正确读取完整响应体。

调用图：被 2 处调用（exec_server_http_request_buffers_response_body, exec_server_http_request_honors_optional_timeout）；外部调用 3 个（flush, write_all, format!）。

fn is_expected_peer_disconnect(err: &anyhow::Error) -> bool

作用：判断一个错误是不是测试中可以接受的“对方已经断开连接”。在超时测试里，exec-server 可能先超时关连接，假服务器再写数据时出错，这不代表功能坏了。

数据流：它接收一个错误对象，沿着错误链一层层查看有没有底层的输入输出错误。如果错误类型是断管、连接重置或意外 EOF，就返回 true；否则返回 false。

调用关系：只有超时测试会用它。它帮助 exec_server_http_request_honors_optional_timeout 区分两类情况：因为超时导致的正常断连可以忽略，其他写响应错误则应该让测试失败。

调用图：被 1 处调用（exec_server_http_request_honors_optional_timeout）；外部调用 1 个（chain）。

async fn respond_with_chunked_body(
    mut stream: TcpStream,
    headers: &[(&str, &str)],
    chunks: &[&[u8]],
) -> anyhow::Result<()>

作用：写出一个使用 HTTP 分块传输的响应，让 exec-server 必须走流式读取路径。分块传输可以理解成“边做边端上菜”，不是一次把整盘菜端完。

数据流：它拿到连接、额外响应头和若干块字节数据。先写 HTTP 200 响应头，并声明 transfer-encoding: chunked；然后每一块都按 HTTP 分块格式写入长度、内容和换行，并刷新；最后写入长度为 0 的结束块，表示响应体结束。

调用关系：流式响应测试调用它来制造真实的 chunked 响应。exec_server_http_request_streams_response_body_notifications 依靠它触发 exec-server 发送多条 http/request/bodyDelta 通知。

调用图：被 1 处调用（exec_server_http_request_streams_response_body_notifications）；外部调用 3 个（flush, write_all, format!）。

async fn respond_with_chunked_body_until_finish(
    mut stream: TcpStream,
    headers: &[(&str, &str)],
    chunks: &[&[u8]],
    finish_rx: oneshot::Receiver<()>,
) -> anyhow::Result<()>

作用：写出分块响应，但在最后结束前故意等测试放行。它用来制造一个“响应还没结束”的流式请求，从而测试重复 requestId 会不会被拒绝。

数据流：它先像普通分块响应一样写状态行、响应头和若干数据块，并刷新到连接里。然后等待一个一次性信号；收到信号后才写入 HTTP 分块结束标记并刷新。也就是说，输入的 finish_rx 决定这个响应什么时候真正结束。

调用关系：重复流 ID 测试会把它放到后台任务里运行。测试先不发送结束信号，让第一个流保持活跃；确认重复 ID 被拒绝后，再通过信号让它收尾，之后由 collect_response_body_deltas 收完通知。

调用图：被 1 处调用（exec_server_http_request_rejects_duplicate_stream_request_ids）；外部调用 3 个（flush, write_all, format!）。

async fn collect_response_body_deltas(
    server: &mut ExecServerHarness,
    request_id: &str,
) -> anyhow::Result<Vec<HttpRequestBodyDeltaNotification>>

作用：持续收集 exec-server 发来的流式响应体通知，直到看到最后一帧。它把一条条 http/request/bodyDelta 事件整理成一个列表，方便测试检查顺序和内容。

数据流：它接收 exec-server 连接和期望的请求 ID。循环读取下一个 JSON-RPC 事件，要求它必须是 http/request/bodyDelta 通知；再把通知参数转成 HttpRequestBodyDeltaNotification，并确认里面的 request_id 正确。每条都放进数组，直到某条通知的 done 为 true，然后返回全部通知。

调用关系：流式响应测试和重复 ID 测试都会在响应进入流式阶段后调用它。它依赖 next_event 从服务器取消息，并把 JSON 参数解析成通知结构，是测试检查流式 body 的统一收集器。

调用图：调用 1 个内部函数（next_event）；被 2 处调用（exec_server_http_request_rejects_duplicate_stream_request_ids, exec_server_http_request_streams_response_body_notifications）；外部调用 4 个（new, bail!, assert_eq!, from_value）。

fn response_header(headers: &[HttpHeader], name: &str) -> Option<String>

作用：从响应头列表里按名字找一个头的值，而且不在乎大小写。HTTP 头名本来就不区分大小写，所以测试不能因为 X-Test 和 x-test 写法不同就失败。

数据流：它接收一组 HttpHeader 和要找的头名，逐个比较头名，比较时忽略大小写。找到后返回这个头的值；找不到就返回空。

调用关系：主测试用它检查 exec-server 返回的 HTTP 响应头。它是一个小辅助函数，避免每个断言都重复写大小写无关的查找逻辑。

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

fn hybrid_ik_roundtrip_authenticates_both_endpoints()

作用：测试一整套正常握手流程：发起方和响应方都能确认对方身份，并且握手后能双向加密通信。它证明这条加密通道在最基本、最重要的成功场景下是可用的。

数据流：进去的是两端新生成的身份、公钥、同一份 prologue，以及一段授权数据 → 测试让发起方生成握手请求，响应方读取并确认请求里带着正确的发起方公钥和授权数据，再完成握手 → 出来的是两端各自拿到的加密传输对象；随后明文 request 和 response 被加密成不同于原文的密文，再被另一端成功解回原文。

调用关系：这是测试运行器执行的主成功路径测试。它会用 generate 准备双方身份，用 noise_channel_prologue 准备双方共同认可的上下文，用 start 发起握手，再用 read_request 让响应方接住请求；最后通过断言检查认证和加密收发都成立。

调用图：调用 3 个内部函数（start, generate, read_request）；外部调用 3 个（assert_eq!, assert_ne!, noise_channel_prologue）。

fn initiator_rejects_wrong_responder_key()

作用：测试发起方指定了一个期望的响应方公钥时，真正收到请求的另一个响应方不能冒充成功。换句话说，消息不能被拿去给“错的人”解开。

数据流：进去的是发起方身份、一个期望响应方身份、一个实际响应方身份，以及同一份 prologue → 发起方按期望响应方的公钥制作握手请求 → 实际响应方尝试读取这个请求时失败，结果是错误而不是握手成功。

调用关系：测试运行器调用它来覆盖冒名响应方的情况。它先用 generate 造出三套身份，用 noise_channel_prologue 造上下文，再把 start 产生的请求交给错误的接收者，最后用断言确认 read_request 不会放行。

调用图：调用 2 个内部函数（start, generate）；外部调用 2 个（assert!, noise_channel_prologue）。

fn responder_rejects_mismatched_prologue()

作用：测试双方握手时的上下文必须完全一致。即使身份都对，只要 prologue 不同，也不能建立通道。

数据流：进去的是同一对身份，但发起方和响应方各用一份不同的 prologue，其中数据流编号不同 → 发起方按自己的 prologue 创建请求 → 响应方用另一份 prologue 读取时失败，输出是错误结果。

调用关系：测试运行器用它检查“同一把钥匙不能跨场景乱用”。它调用 generate 准备身份，调用 noise_channel_prologue 做出两份不同上下文，调用 start 生成请求，再确认响应方读取请求时会拒绝。

调用图：调用 2 个内部函数（start, generate）；外部调用 2 个（assert!, noise_channel_prologue）。

fn prologue_encoding_is_stable_and_unambiguous()

作用：测试 prologue 的字节格式是固定且不含糊的。这样不同版本、不同机器生成的上下文才能一致，不会因为字符串拼接歧义导致安全判断出错。

数据流：进去的是环境名、注册名和数据流名三个文本 → noise_channel_prologue 把它们连同协议版本名编码成一串字节，并给每段加上长度 → 测试把生成结果和预期字节逐个比较，确认格式没有悄悄变。

调用关系：测试运行器调用它来保护协议格式不被无意改坏。它只依赖 noise_channel_prologue 生成结果，再用 assert_eq! 把结果钉死在一个明确的字节模板上。

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

fn transport_rejects_tampered_ciphertext()

作用：测试加密后的消息被改动一个字节后，接收方会发现并拒绝。它验证的不只是保密，还包括防篡改。

数据流：进去的是正常生成的双方身份、prologue 和授权数据 → 测试先完成一次正常握手，并让发起方加密 request → 然后故意翻转密文里的一个比特，再交给响应方解密；出来的是解密失败，而不是错误地得到某段明文。

调用关系：这个测试先复用正常握手流程：generate、noise_channel_prologue、start、read_request。建立通道后，它不测正常收发，而是人为破坏密文，再用断言确认传输层不会接受被改过的内容。

调用图：调用 3 个内部函数（start, generate, read_request）；外部调用 2 个（assert!, noise_channel_prologue）。

fn transport_rejects_replayed_ciphertext()

作用：测试同一段密文不能被重复使用。第一次收到可以解密，第二次再发同样内容应该被当成可疑消息拒绝。

数据流：进去的是正常握手所需的身份、prologue 和授权数据 → 发起方加密一条 request，响应方第一次解密成功并得到原文 → 同一段密文第二次送进去时，结果变成传输错误，说明系统记住了消息顺序或编号，拒绝重放。

调用关系：测试运行器调用它来覆盖重放攻击。它和正常握手测试一样先调用 generate、noise_channel_prologue、start、read_request 建好通道，再用一次成功解密作为对照，随后用断言确认重复解密会失败。

调用图：调用 3 个内部函数（start, generate, read_request）；外部调用 3 个（assert!, assert_eq!, noise_channel_prologue）。

fn public_key_validation_rejects_unknown_suite()

作用：测试公钥里写着未知加密套件时，不能拿来发起握手。加密套件可以理解为“用哪套加密配方”，配方不认识就不能硬用。

数据流：进去的是一个正常生成的公钥 → 测试先把它转成 JSON，再把其中 suite 字段改成 unknown，然后再读回公钥对象 → 用这个被改过的公钥发起握手时，结果应该是错误。

调用关系：测试运行器用它检查公钥的安全校验。它调用 generate 生成原始身份，借助 to_value、json!、Object 和 from_value 模拟一个外部传来的异常公钥，最后让 start 尝试使用它，并断言会被拒绝。

调用图：调用 1 个内部函数（generate）；外部调用 5 个（assert!, Object, from_value, json!, to_value）。

fn public_key_serializes_with_expected_suite()

作用：测试公钥导出成 JSON 时，会写上项目期望的加密套件名称。这样别的组件收到公钥后，能知道该按哪套加密规则处理。

数据流：进去的是一个新生成身份的公钥 → 测试把公钥序列化成 JSON → 出来的是 JSON 里的 suite 字段；它必须等于 NOISE_CHANNEL_SUITE 这个固定值。

调用关系：测试运行器调用它来保护对外数据格式。它用 generate 造身份，用 to_value 把公钥变成可检查的 JSON，再用 assert_eq! 确认 suite 字段没有偏离约定。

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

fn initiator_rejects_oversized_handshake_payload()

作用：测试握手时附带的载荷太大时，发起方会直接拒绝。这样可以避免有人塞入超大数据，把握手流程拖垮或造成资源浪费。

数据流：进去的是两端身份，以及一段长度达到 MAX_MESSAGE_LEN 的零字节载荷 → 测试调用 start 试图把这段数据放进握手请求 → 出来的是 InvalidMessage 错误，错误信息说明握手载荷太大，没有生成请求。

调用关系：测试运行器调用它来检查大小限制。它用 generate 准备身份，用 vec! 构造过大的载荷，然后把数据交给 start，最后用断言确认返回的是预期的错误类型和提示。

调用图：调用 2 个内部函数（start, generate）；外部调用 2 个（assert!, vec!）。

fn fragments_and_reassembles_large_jsonrpc_message()

作用：这个测试确认：一条很大的 JSON-RPC 通知消息被切成多个 Noise 记录后，接收端还能完整拼回原来的消息。简单说，就是检查“拆开寄”和“收齐再组装”不会丢字、乱序或损坏内容。

数据流：进去的是一个带有 128KB 字符串数据的 JSON-RPC 通知消息。测试先调用 frame_jsonrpc_message 把它编码成适合传输的字节数据，并确认它确实很大；然后按 NOISE_RECORD_PLAINTEXT_LEN 这个每段最大明文长度切块，逐块喂给 JsonRpcMessageDecoder。最后出来的是 decoder 还原出的消息列表，测试要求它正好只包含原来那一条消息。

调用关系：这个测试站在发送端和接收端之间模拟完整流程：先把活交给 frame_jsonrpc_message 做打包，再把每个小块交给 JsonRpcMessageDecoder 的 push 方法做解包。它用断言确认两边配合正常，防止以后改协议或改大小限制时把大消息传输弄坏。

调用图：外部调用 7 个（new, Notification, assert!, assert_eq!, default, json!, frame_jsonrpc_message）。

fn rejects_declared_message_length_above_limit_without_payload()

作用：这个测试确认：只要消息头里声明的长度超过上限，解码器马上报错，不会等正文真的发过来。这样可以防止别人用一个假的超大长度吓唬或拖垮服务器。

数据流：进去的是 4 个字节，表示一个比 MAX_NOISE_JSONRPC_MESSAGE_LEN 还大 1 的消息长度。测试把这几个字节直接交给默认创建的 JsonRpcMessageDecoder。结果应该是 ExecServerError::Protocol，并且错误文字说明 JSON-RPC 消息长度无效；解码器不会继续等待后续 payload，也不会分配大内存。

调用关系：这个测试只检查接收端解码器的第一道门槛。它不需要调用打包函数，因为它是在模拟一个不可信对方直接发来坏长度的情况，用来保证 JsonRpcMessageDecoder 在刚看到长度字段时就能拦住问题。

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

fn rejects_oversized_plaintext_record()

作用：这个测试确认：单个 Noise 明文记录如果比允许的最大长度还大，解码器会拒绝。也就是说，每一小包本身也要守规矩，不能因为总消息还没解析就放过超大输入。

数据流：进去的是一段全是 0 的字节数组，长度是 NOISE_RECORD_PLAINTEXT_LEN 加 1，刚好超过单个明文记录的上限。测试把它交给默认创建的 JsonRpcMessageDecoder。出来的结果应是协议错误，并带有“plaintext record exceeds maximum length”这类明确提示；解码器不会尝试把这段超大数据当正常消息处理。

调用关系：这个测试模拟接收端收到一个过大的传输块。它直接调用 JsonRpcMessageDecoder 的 push 方法，确认解码器在真正解析 JSON-RPC 消息前，先检查每个传输记录的大小，作为协议安全边界的一部分。

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

fn releases_ciphertexts_only_in_nonce_order()

作用：这个测试确认密文只能按序号顺序放出来。即使编号 1 先到，也必须等编号 0 到了以后，才能一起交给后续处理。

数据流：进去的是一个空的 OrderedCiphertextFrames 队列，以及两段带序号的字节数据：先放入序号 1 的“second”，再放入序号 0 的“first”。第一次放入后，因为缺少序号 0，所以出来的是空列表；第二次放入后，队列发现 0 和 1 都连续齐了，就按“first”“second”的顺序输出。

调用关系：它直接创建默认队列，然后调用队列的 push 行为，并用 assert_eq! 检查结果是否符合预期。它验证的是整个排序缓存最核心的承诺：外面即使乱序送进来，里面也只能按正确顺序吐出去。

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

fn ignores_duplicate_ciphertexts_without_replacing_buffered_record()

作用：这个测试确认重复序号不会覆盖已经缓存的密文。也就是说，第一次收到的那份会被保留，后来的同号“替换品”会被忽略。

数据流：进去的是一个空队列。先放入序号 1 的“first copy”，它被暂存但不输出；再放入同样序号 1 的“replacement”，队列不让它替换原来的内容，也不输出；之后放入序号 0 的“zero”，队列终于能连续输出 0 和 1，于是结果是“zero”和最早那份“first copy”。最后再放一次序号 0 的“duplicate”，因为它已经处理过了，所以输出空列表。

调用关系：它也是围绕 OrderedCiphertextFrames 的 push 行为做检查，用 assert_eq! 对比输出。它补上了乱序场景里的另一个安全细节：重复包不能改变已经等待释放的数据，否则后来的重复数据可能悄悄篡改结果。

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

fn rejects_unbounded_reordering()

作用：这个测试确认队列不会接受无限乱序或超大缓存。它防止有人发很远的序号或特别大的数据，让程序一直攒着不释放，最终耗光内存。

数据流：进去的是一个空队列。第一次尝试放入序号 65 的空数据，因为它离当前期待的序号太远，push 返回错误；第二次尝试放入序号 1、但内容大小超过 MAX_PENDING_BYTES 的数据，也返回错误。测试用 assert! 确认这两种情况都会失败。

调用关系：它创建默认队列后，把两个危险输入交给 push，并只关心是否报错。它在整体测试里负责检查资源保护这条底线：排序缓存可以临时等一等，但不能无限等、无限存。

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

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

作用：这个测试函数检查：当虚拟流里的处理器结束时，系统会不会把“流关闭了”这件事报告出来。有人改动加密流、连接处理器或关闭通知机制时，可以靠它发现是否破坏了这个保证。

数据流：进去的是测试里临时造出来的两套通信身份、一个测试用握手前缀、一个虚拟流编号和实例编号。它先让两端完成加密握手，再创建虚拟流和一个用来接关闭通知的通道；然后把一条 JSON-RPC 响应消息打包、加密，作为 RelayData 喂给虚拟流。出来的结果不是普通返回值，而是断言：关闭通知通道里必须在 1 秒内收到一条 ClosedNoiseVirtualStream，并且 stream_id 是 “stream-1”、instance_id 是 7；如果没有收到或内容不对，测试失败。

调用关系：它是由 Tokio 测试运行器在测试阶段调用的异步测试。它会调用 NoiseChannelIdentity::generate 生成双方身份，用 InitiatorHandshake::start 和 PendingResponderHandshake::read_request/complete 模拟握手，用 ExecServerRuntimePaths::new 和 ConnectionProcessor::new 准备执行器侧处理环境，再用 spawn_noise_virtual_stream 启动被测的虚拟流。消息部分交给 frame_jsonrpc_message 打包，再交给加密传输对象加密，最后通过 stream.receive_data 触发整个关闭流程，并从 closed_stream_rx 里观察结果。

调用图：调用 6 个内部函数（start, generate, read_request, frame_jsonrpc_message, new, new）；外部调用 6 个（Response, Integer, assert!, channel, current_exe, spawn_noise_virtual_stream）。

fn validate_harness_key(
        &self,
        _harness_public_key: &NoiseChannelPublicKey,
        _authorization: &str,
    ) -> impl std::future::Future<Output = Result<(), ExecServerError>> + Sen

作用：这是测试用的假认证函数。它不像真实认证那样立刻判断 key 对不对，而是先把调用次数加一，然后一直等别人放行，用来制造“认证还没完成”的场景。

数据流：进去的是 harness 的公钥和认证字符串，但这个假实现并不真的检查它们。它读取共享的计数器和通知器，把计数器加一，然后等待通知；等通知来了，就返回成功。结果是测试可以知道认证被触发了几次，也可以故意让认证悬在那里不结束。

调用关系：它实现了 HarnessKeyValidator，所以 run_multiplexed_environment 在收到握手后会调用它。各个测试把 BlockingValidator 交给环境任务，用它来观察握手是否进入认证阶段，以及认证卡住时中继的其他行为是否正常。

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

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

作用：这个测试确认：第一个握手的认证如果卡住了，不应该挡住第二个 stream 的握手。也就是说，一条连接里某个小通道慢了，不能把其他小通道也堵死。

数据流：它先在本机开一个临时 TCP/WebSocket 连接，生成环境端和 harness 端的 Noise 身份，然后启动中继环境，并交给它一个会卡住的 BlockingValidator。接着它连续发送两个不同 stream 的握手帧。最后它等计数器变成 2，证明两个握手都进入了认证流程；随后关闭客户端连接，等待环境任务正常结束。

调用关系：这个函数由 tokio 的异步测试框架启动。它用 NoiseChannelIdentity::generate 造身份，用 InitiatorHandshake::start 造握手请求，用 noise_channel_prologue 绑定环境、注册号和 stream，用 encode_relay_message_frame 包成中继帧，再把真正的运行交给 run_multiplexed_environment。

调用图：调用 6 个内部函数（start, generate, noise_channel_prologue, encode_relay_message_frame, new, new）；外部调用 16 个（clone, new, new, from_secs, new, bind, handshake, format!, current_exe, run_multiplexed_environment (+6 more)）。

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

作用：这个测试检查同一个 stream 反复发送握手时，服务器会先用 reset 拒绝这些重复请求，次数到达上限后会关闭整条 WebSocket 连接。它防止恶意客户端靠重复握手无限消耗服务器。

数据流：它建立本地 WebSocket，生成双方身份，启动一个认证会卡住的环境任务。然后它为同一个 stream 生成一份握手帧，先发一次让认证挂起，再不断重发同一帧。每次重复握手后，它从 WebSocket 里读回 reset 帧，并检查 reset 的 stream_id 和类型是否正确。重复失败次数达到预算后，它再发一次，等待环境任务结束，说明物理连接已经被关闭。

调用关系：这个测试同样由异步测试框架调用。它把帧编码后发给 run_multiplexed_environment，收到回应后用 decode_relay_message_frame 解回中继帧，再用 validate 判断是不是 reset。它围绕 MAX_FAILED_NOISE_HANDSHAKES 这个失败预算，验证中继层的限流和断连规则。

调用图：调用 7 个内部函数（start, generate, noise_channel_prologue, decode_relay_message_frame, encode_relay_message_frame, new, new）；外部调用 18 个（clone, new, new, from_secs, new, bind, bail!, assert_eq!, handshake, format! (+8 more)）。

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

作用：这个测试确认：如果握手里带的认证字符串太大，服务器会在调用认证器之前就拒绝它。这样可以避免别人塞一个超大字段，逼服务器做没必要的认证工作。

数据流：它启动本地 WebSocket 和环境任务，准备一个长度超过 MAX_HARNESS_KEY_AUTHORIZATION_BYTES 的认证内容，并用它生成握手请求。发出握手帧后，它等待服务器返回二进制 reset 帧，解码并确认类型是 reset。最后它检查 BlockingValidator 的调用次数仍然是 0，说明请求在真正认证前就被挡下来了。

调用关系：这个测试连接了握手生成、帧编码、环境处理和帧解码几步。InitiatorHandshake::start 负责造出带超大认证内容的握手，run_multiplexed_environment 负责处理，decode_relay_message_frame 负责把服务器回包拆开检查。

调用图：调用 7 个内部函数（start, generate, noise_channel_prologue, decode_relay_message_frame, encode_relay_message_frame, new, new）；外部调用 18 个（clone, new, new, from_secs, new, bind, bail!, assert_eq!, handshake, format! (+8 more)）。

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

作用：这个测试检查：连续发送损坏的握手包，服务器不会一直陪它耗，而是在失败次数达到上限后关闭整条中继连接。这里的“损坏”就是故意把握手请求最后一个字节改坏。

数据流：它建立本地 WebSocket，生成身份并启动环境任务。然后循环多次，每次创建一个新的 stream 握手请求，再把请求的最后一个字节翻转，让它变成无法通过 Noise 校验的坏包。它把这些坏握手发给服务器。循环次数达到失败预算后，它等待环境任务结束，结果表示服务器已经关闭物理 relay。

调用关系：这个测试由测试框架触发，主要把 InitiatorHandshake::start 生成的正常请求改坏，再通过 encode_relay_message_frame 发入 run_multiplexed_environment。它验证的是中继环境面对解析或加密校验失败时的整体断连策略。

调用图：调用 6 个内部函数（start, generate, noise_channel_prologue, encode_relay_message_frame, new, new）；外部调用 14 个（new, new, from_secs, new, bind, handshake, format!, current_exe, run_multiplexed_environment, spawn (+4 more)）。

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

作用：这个测试确认：如果客户端在握手认证还没完成时就急着发数据，反复这么做会被当成严重错误，最终关闭整条连接。它防止客户端跳过“先握手再传数据”的规矩。

数据流：它先启动本地 WebSocket 和环境任务，并使用会卡住的 BlockingValidator，让每个握手都停在认证中。然后循环创建多个 stream：每个 stream 先发送握手帧，紧接着马上发送一帧普通数据。因为此时握手还没完成，这些数据都属于过早数据。发送次数达到失败预算后，它等待环境任务结束，说明服务器关闭了物理连接。

调用关系：这个测试把 RelayMessageFrame::handshake 和 RelayMessageFrame::data 组合起来，模拟“不等握手完成就发业务数据”的客户端。run_multiplexed_environment 接收这些帧并执行规则，测试只关心最后是否按 MAX_FAILED_NOISE_HANDSHAKES 的限制断开连接。

调用图：调用 6 个内部函数（start, generate, noise_channel_prologue, encode_relay_message_frame, new, new）；外部调用 16 个（new, new, from_secs, new, bind, data, handshake, format!, current_exe, run_multiplexed_environment (+6 more)）。

fn add_auth_headers(&self, headers: &mut HeaderMap)

作用：这个函数给发往假注册服务的 HTTP 请求加上固定的认证头。简单说，它像是在测试请求上贴一张固定的“通行证”，让测试服务器能确认请求带了正确身份。

数据流：进去的是一组还没补完的 HTTP 请求头 → 它往里面插入 Authorization: Bearer registry-token 这个固定值 → 出来时请求头被改过，后续发请求时就会带上这个测试用令牌。

调用关系：它是测试用认证提供者 StaticRegistryAuthProvider 的核心动作。后面的测试通过 static_registry_auth_provider 拿到它，再交给环境注册客户端使用；注册客户端真正发请求前会调用它来补认证信息。

调用图：外部调用 2 个（insert, from_static）。

fn static_registry_auth_provider() -> SharedAuthProvider

作用：这个函数创建一个测试用的认证提供者，方便多个测试重复使用同一套固定认证方式。它避免每个测试都手写一遍“怎么加认证头”。

数据流：进去不需要参数 → 它新建一个 StaticRegistryAuthProvider，并用可共享的指针包起来 → 出来的是一个可以传给注册客户端或远程环境配置的认证对象。

调用关系：它被三个测试使用：重连注册测试、harness key 明确拒绝测试、以及错误信息不泄密测试。它把认证这件小事封装起来，让这些测试可以专心检查连接和安全规则。

调用图：被 3 处调用（reconnect_reuses_registration_until_url_is_rejected, validate_harness_key_does_not_expose_error_body, validate_harness_key_requires_explicit_valid_response）；外部调用 1 个（new）。

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

作用：这个测试确认远程环境断线重连时不会乱重新注册，但如果连接地址被明确拒绝，就会丢掉旧注册再注册。它保护的是连接状态的正确性，避免系统一断线就反复登记，或被拒绝后还死抱着旧地址不放。

数据流：开始时它启动一个本地 TCP 监听器当假的中继地址，又启动一个假的环境注册服务 → 注册服务被设置成最多收到两次注册请求，并返回同一个中继地址和注册编号 → 测试启动远程环境任务，让它先成功连上 WebSocket，然后主动关闭连接 → 第二次连接时，测试假装中继返回 HTTP 401 拒绝 → 之后远程环境应该重新注册并再次连接 → 最后测试确认注册服务确实被调用了预期次数，并停止后台任务。

调用关系：这个测试会调用 static_registry_auth_provider 准备认证，也会创建 RemoteEnvironmentConfig 并启动 run_remote_environment。它像导演一样安排假注册服务、假中继服务器和远程环境任务互动，用这些互动来验证重连策略。

调用图：调用 3 个内部函数（new, static_registry_auth_provider, new）；外部调用 13 个（from_secs, given, start, new, bind, format!, json!, current_exe, spawn, timeout (+3 more)）。

async fn validate_harness_key_requires_explicit_valid_response()

作用：这个测试确认 harness key 的校验必须得到“明确有效”的回答才算成功。即使注册服务正常返回 HTTP 200，只要内容说 valid: false，系统也必须拒绝，不能侥幸放行。

数据流：开始时它启动假的注册服务，并生成一个测试用的 Noise 公钥 → 假服务被设置为只接受带正确认证头、注册编号、公钥和授权字符串的校验请求，然后返回 { valid: false } → 测试创建注册客户端和 key 校验器，发起校验 → 结果必须是错误，并且错误内容必须表明注册服务拒绝了这个 harness key。

调用关系：它使用 static_registry_auth_provider 给客户端加认证，使用 EnvironmentRegistryClient 访问假注册服务，再通过 RegistryHarnessKeyValidator::validate_harness_key 执行真正的校验。它重点验证校验器在“服务明确说无效”时会安全地失败。

调用图：调用 3 个内部函数（generate, new, static_registry_auth_provider）；外部调用 9 个（given, start, new, assert!, json!, body_partial_json, header, method, path）。

async fn validate_harness_key_does_not_expose_error_body()

作用：这个测试确认注册服务报错时，错误信息里不会泄露敏感的 harness key 授权字符串。它防的是一种常见安全事故：把服务器返回的原始错误内容直接打印出来，结果把秘密写进日志或界面。

数据流：开始时它启动假的注册服务，并生成一个测试用公钥 → 假服务在校验接口上返回 HTTP 500，而且响应正文故意放入敏感授权字符串 → 测试发起 harness key 校验并期待失败 → 然后把错误转成文字检查，确认里面不包含那段敏感字符串，同时确认错误被归类为注册服务校验失败。

调用关系：它同样通过 static_registry_auth_provider 创建带认证能力的注册客户端，再把客户端交给 RegistryHarnessKeyValidator。它和前一个校验测试互补：一个检查“拒绝时不能放行”，另一个检查“报错时不能泄密”。

调用图：调用 3 个内部函数（generate, new, static_registry_auth_provider）；外部调用 6 个（given, start, new, assert!, method, path）。

fn add_auth_headers(&self, headers: &mut HeaderMap)

作用：给发往假注册中心的 HTTP 请求加上固定的认证头。简单说，就是给请求贴上一张“我有权限”的票。

数据流：进去的是一组还可以修改的 HTTP 请求头 → 它往里面放入 Authorization: Bearer registry-token → 出来时请求头被改过，后面的假注册中心就能按这个固定令牌识别请求。

调用关系：这个方法属于测试里的固定认证提供者。static_registry_auth_provider 会把这个提供者包装起来，远程环境注册和校验自己时会间接用到它，这样测试里的 wiremock 假注册中心才能验证请求确实带了认证信息。

调用图：外部调用 2 个（insert, from_static）。

fn connect_bundle(
        &self,
        _: NoiseChannelPublicKey,
    ) -> BoxFuture<'_, Result<NoiseRendezvousConnectBundle, ExecServerError>>

作用：故意模拟“拿不到 Noise 中继连接资料”的失败情况。它的价值是测试系统失败后会不会重新尝试，而不是缓存坏结果。

数据流：进去的是对方的 Noise 公钥，但这个测试实现不使用它 → 它先把尝试次数加一 → 然后返回一个协议错误，错误文字固定为 test registry connect failure。

调用关系：它被放进 noise_environment_refreshes_bundle_for_each_connection_attempt 创建的测试环境里。每次后端尝试启动进程时，都会来这里拿连接包并失败；测试最后通过计数器确认它被调用了两次。

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

fn static_registry_auth_provider() -> codex_api::SharedAuthProvider

作用：创建一个共享的固定认证提供者，供测试里的远程环境访问假注册中心时使用。

数据流：进去没有参数 → 它新建一个 StaticRegistryAuthProvider，再用 Arc 包起来；Arc 可以理解成多人共用同一个对象的安全引用 → 出来的是注册中心客户端可使用的共享认证对象。

调用关系：它只在 remote_environment_routes_encrypted_exec_server_rpc 这个大测试里被调用。这个认证对象随后进入 RemoteEnvironmentConfig，让远程环境注册和校验时都带上正确的测试令牌。

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

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

作用：测试 Noise 环境每次连接失败后，下一次连接都会重新获取连接资料。这样可以避免网络或注册中心短暂出错后，系统一直卡在旧的失败结果上。

数据流：进去没有外部输入，测试自己创建一个尝试次数计数器和一个空环境管理器 → 它把一个总是失败的连接提供者塞进环境，再连续两次启动同一个后端里的进程 → 两次都应该得到同样的协议错误，同时计数器最后必须是 2，说明确实试了两次。

调用关系：这是一个独立的异步测试。它使用 FailingNoiseConnectProvider::connect_bundle 来制造失败，并通过执行后端的 start 入口触发连接流程；最后用断言检查系统没有把第一次失败缓存起来。

调用图：调用 3 个内部函数（without_environments, new, from_path）；外部调用 9 个（clone, new, new, new, assert!, assert_eq!, format!, current_dir, vec!）。

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

作用：这是本文件最完整的端到端测试：确认远程环境、客户端、假注册中心、假中继站一起工作时，执行命令和读文件都能成功，并且中继站看到的是密文。

数据流：进去没有外部输入，测试自己启动 TCP 监听、wiremock 假注册中心和远程环境任务 → 它接受环境端 WebSocket，取出远程环境注册时提交的公钥，再创建客户端连接；随后让一个代理任务在客户端和环境端之间转发所有帧并记录它们 → 出来时客户端成功执行 true，成功读取一个 128KB 文件，记录到的中继数据也通过加密检查；最后测试主动停止后台任务。

调用关系：这个测试串起了本文件几乎所有辅助函数。它用 static_registry_auth_provider 准备认证，用 accept_websocket 接住两端连接，用 registered_executor_public_key 从注册请求里拿公钥，用 proxy_relay_frames 假装中继站搬运消息，最后调用 assert_relay_data_is_encrypted 确认搬运过程中没有泄露明文。

调用图：调用 11 个内部函数（generate, from, new, new, current_test_binary_helper_paths, accept_websocket, assert_relay_data_is_encrypted, proxy_relay_frames, registered_executor_public_key, static_registry_auth_provider (+1 more)）；外部调用 23 个（clone, new, new, given, start, new, new, bind, new, new (+13 more)）。

async fn accept_websocket(
    listener: &TcpListener,
    role: &str,
) -> Result<WebSocketStream<TcpStream>>

作用：在测试里的假中继服务器上等待一方连进来，并把普通 TCP 连接升级成 WebSocket 连接。WebSocket 可以理解成一条持续打开、双方都能随时发消息的通道。

数据流：进去的是 TCP 监听器和一个角色名，比如 environment 或 harness → 它在限定时间内等待连接，再完成 WebSocket 握手 → 出来的是可收发 WebSocket 消息的连接；如果超时或握手失败，就返回带说明的错误。

调用关系：它被 remote_environment_routes_encrypted_exec_server_rpc 调用两次：一次接住远程环境端，一次接住测试客户端端。拿到这两条连接后，测试才可以交给 proxy_relay_frames 来模拟真正的中继转发。

调用图：被 1 处调用（remote_environment_routes_encrypted_exec_server_rpc）；外部调用 3 个（accept, timeout, accept_async）。

async fn registered_executor_public_key(registry: &MockServer) -> Result<NoiseChannelPublicKey>

作用：从假注册中心收到的注册请求里，找出远程执行器上报的 Noise 公钥。客户端需要这个公钥，才能和远程环境建立加密通道。

数据流：进去的是 wiremock 假注册中心 → 它读取已经收到的 HTTP 请求，找到路径以 /register 结尾的那一条，把请求体当 JSON 解析，再取出 executor_public_key 字段 → 出来的是可用于连接参数的 NoiseChannelPublicKey。

调用关系：它在 remote_environment_routes_encrypted_exec_server_rpc 中使用。远程环境先向假注册中心注册自己，测试随后用这个函数把注册时的公钥挖出来，再把公钥放进客户端的连接包里，让双方能完成加密握手。

调用图：被 1 处调用（remote_environment_routes_encrypted_exec_server_rpc）；外部调用 3 个（received_requests, from_slice, from_value）。

async fn proxy_relay_frames(
    mut environment: WebSocketStream<TcpStream>,
    mut harness: WebSocketStream<TcpStream>,
    captured_frames: Arc<Mutex<Vec<Vec<u8>>>>,
) -> Result<()>

作用：扮演一个最简单的中继站：环境端发来的消息转给客户端端，客户端端发来的消息转给环境端。它不理解消息内容，只负责搬运。

数据流：进去的是环境端 WebSocket、客户端端 WebSocket，以及一个用来保存原始二进制帧的共享列表 → 它在循环里同时等两边消息，哪边来了就先记录二进制内容，再原样发给另一边 → 出来通常是连接关闭后返回成功；过程中共享列表会积累所有经过中继的二进制数据。

调用关系：它由 remote_environment_routes_encrypted_exec_server_rpc 启动成后台任务。每收到一条消息，它会调用 capture_binary_frame 保存可检查的原始数据；测试完成后，这些数据会交给 assert_relay_data_is_encrypted 判断是否泄露明文。

调用图：被 1 处调用（remote_environment_routes_encrypted_exec_server_rpc）；外部调用 1 个（select!）。

fn capture_binary_frame(captured_frames: &Mutex<Vec<Vec<u8>>>, message: &Message)

作用：把 WebSocket 消息里的二进制帧保存下来，方便测试结束后检查中继站看到的内容。非二进制消息会被忽略。

数据流：进去的是共享的帧列表和一条 WebSocket 消息 → 如果消息是二进制，它就加锁打开列表，把字节复制进去；如果不是二进制，就什么也不做 → 出来没有返回值，但共享列表可能多了一条记录。

调用关系：它服务于 proxy_relay_frames。中继代理每转发一条消息前都会让它看一眼，这样既不影响转发，又能留下证据给后面的加密断言使用。

fn assert_relay_data_is_encrypted(captured_frames: &Mutex<Vec<Vec<u8>>>) -> Result<()>

作用：检查中继站记录到的数据看起来确实是加密后的内容，而不是能直接读懂的请求文字。它不是破解加密，而是确认常见明文关键词没有裸露出来。

数据流：进去的是保存了中继二进制帧的共享列表 → 它加锁读取所有帧，把每一帧按 RelayMessageFrame 这种外层消息格式解码；遇到真正的数据帧时，把载荷当作可能的文字查看，确认里面不包含 initialize、process/start、noise-relay-test 等明文 → 出来是成功或断言失败；同时要求至少看到 4 个数据帧，避免测试根本没传数据却误判通过。

调用关系：它在 remote_environment_routes_encrypted_exec_server_rpc 的命令执行和文件读取都完成后调用。前面的 proxy_relay_frames 和 capture_binary_frame 负责留下原始中继数据，这个函数负责做最后的安全检查。

调用图：被 1 处调用（remote_environment_routes_encrypted_exec_server_rpc）；外部调用 3 个（from_utf8_lossy, assert!, decode）。

fn reassembles_client_message_chunks()

作用：这个测试确认：客户端把一条 JSON-RPC 消息拆成两片发来时，系统能把它们重新拼成原来的完整消息。JSON-RPC 可以理解成一种用 JSON 格式表达请求和通知的通信格式。

数据流：进去的是一条假的 initialized 通知，它先被转成原始字节，再人为切成前后两半。测试把第一半交给重组器，应该只得到“还在等待”；再把第二半交给重组器，应该得到完整消息。出来的结果要保留原来的 client_id、stream_id、seq_id，并且消息内容和一开始那条通知完全一样。

调用关系：它是最基础的拼接成功案例。测试中会用 chunk_envelope 造出分片外壳，再把这些外壳交给 ClientSegmentReassembler 的 observe 方法，最后用断言检查重组器有没有把拼好的消息往后传。

调用图：调用 1 个内部函数（chunk_envelope）；外部调用 8 个（Notification, new, new, default, assert!, assert_eq!, panic!, to_vec）。

fn splits_large_server_messages_into_wire_chunks()

作用：这个测试确认：服务器要发的消息很大时，系统会自动把它拆成多个能在线路上传的小块。这样可以避免单个网络包或协议消息超过限制。

数据流：进去的是一个服务器发给客户端的配置警告通知，里面故意放了很长的 summary 文本，让它超过单片限制。测试调用 split_server_envelope_for_transport 后，出来应该是多个分片；每个分片都应该是 ServerMessageChunk，序号 seq_id 仍然保持为 9，并且每片序列化成 JSON 后都不超过 REMOTE_CONTROL_SEGMENT_MAX_BYTES 这个最大字节数。

调用关系：它直接验证 split_server_envelope_for_transport 这个拆包函数。这个测试站在“消息准备发到传输层之前”的位置，检查大消息是否已经被切成安全大小，避免真正发送时出问题。

调用图：调用 1 个内部函数（split_server_envelope_for_transport）；外部调用 6 个（new, ConfigWarning, AppServerNotification, new, new, assert!）。

fn invalidates_incomplete_stream_assemblies()

作用：这个测试确认：某个通信流已经被判定失效后，之前没拼完的消息不能再被后续碎片补齐。简单说，就是“已经作废的拼图不能突然又拼成有效消息”。

数据流：进去的是一条被切成两半的客户端通知。测试先送入第一半，重组器返回 Pending，表示还差一半；然后调用 invalidate_stream，把这个 client_id 和 stream_id 对应的未完成拼接作废。之后再送入第二半，出来应该是 Dropped，也就是被丢弃，而不是拼成完整消息。

调用关系：它验证 ClientSegmentReassembler 在流被取消或重置时的清理行为。这个场景通常发生在远程控制连接切换、关闭或重新开始时，确保旧数据不会在之后误伤新流程。

调用图：外部调用 6 个（Notification, new, new, default, assert!, to_vec）。

fn resets_incomplete_client_assembly_when_stream_changes()

作用：这个测试确认：同一个客户端换了新的 stream_id 后，旧流里没拼完的消息会被替换掉，不会和新流的数据混在一起。stream_id 可以理解成一次通信会话的编号。

数据流：进去的是同一条消息的两半，以及同一个 client_id 下两个不同的 stream_id。测试先给旧流送第一半，再给新流送第一半；随后给新流送第二半，应该成功拼出新流的完整消息。最后再把旧流剩下的第二半送来，应该被 Dropped，说明旧流的半截消息已经不能复活。

调用关系：它用 chunk_envelope 构造不同 stream_id 的分片，然后交给重组器 observe。这个测试补上了“客户端没变，但会话变了”的边界情况，防止旧会话残留数据干扰新会话。

调用图：调用 1 个内部函数（chunk_envelope）；外部调用 8 个（Notification, new, new, default, assert!, assert_eq!, panic!, to_vec）。

fn ignores_stale_chunks_without_dropping_newer_assembly()

作用：这个测试确认：如果系统正在拼一条较新的消息，突然来了更旧序号的碎片，旧碎片会被忽略，但新的拼接不会被破坏。stale 这里就是“过期的、来晚的”。

数据流：进去的是同一个客户端和同一个流里的两组分片序号：新的 seq_id 是 8，旧的 seq_id 是 7。测试先送入 seq_id 8 的第一片，重组器开始等待；再送入 seq_id 7 的旧第一片，应该直接 Dropped；最后送入 seq_id 8 的第二片，应该 Forward，表示新消息仍然能正常拼好并继续往后传。

调用关系：它检查重组器对消息序号的保护。这个测试模拟网络里旧包晚到的情况，确保 observe 不会因为看到旧包就清空当前正在进行的正常拼接。

调用图：外部调用 6 个（Notification, new, new, default, assert!, to_vec）。

fn ignores_invalid_stale_chunks_without_dropping_newer_assembly()

作用：这个测试确认：哪怕过期碎片本身还是坏的，比如内容为空，也只能丢掉它，不能影响当前较新的正常拼接。

数据流：进去的是 seq_id 8 的正常第一片、seq_id 7 的过期坏第二片，以及 seq_id 8 的正常第二片。测试先让重组器开始拼 seq_id 8；再喂一个旧序号且内容为空的坏碎片，结果应该是 Dropped；最后喂 seq_id 8 的第二片，仍然应该 Forward，说明新消息没有被坏旧包拖下水。

调用关系：它是在“忽略过期碎片”基础上的更严格测试。它验证 observe 在遇到又旧又不合法的数据时，不会误删当前状态，也不会把错误扩散到新消息。

调用图：外部调用 6 个（Notification, new, new, default, assert!, to_vec）。

fn ignores_invalid_duplicate_chunks_without_dropping_current_assembly()

作用：这个测试确认：如果同一条消息的同一片又来了一次，而且这次还是坏内容，系统会丢掉这个重复坏片，但继续保留原来那片好的数据。

数据流：进去的是 seq_id 8 的第一片正常数据、同一个 seq_id 和同一个 segment_id 的空内容重复片，以及 seq_id 8 的第二片。重组器先进入 Pending；遇到重复的空片时返回 Dropped；最后收到第二片后仍然 Forward，说明一开始保存的好碎片没有被坏的重复碎片覆盖。

调用关系：它测试的是重复包场景。网络或重试机制可能让同一个分片出现多次，这个测试保证 ClientSegmentReassembler 不会让后来的坏副本覆盖先来的好副本。

调用图：外部调用 6 个（Notification, new, new, default, assert!, to_vec）。

fn chunk_envelope(
    client_id: ClientId,
    stream_id: Option<StreamId>,
    seq_id: u64,
    segment_id: usize,
    segment_count: usize,
    message_size_bytes: usize,
    chunk: &[u8],
) -> Cli

作用：这是测试用的小帮手，用来把一段原始字节包装成“客户端消息分片”的格式。这样每个测试不用重复手写一大段 ClientEnvelope 结构。

数据流：进去的是 client_id、可选的 stream_id、消息序号 seq_id、当前是第几片、总共有几片、原消息总大小，以及这一片的原始字节。函数会把字节用 base64 编码成文本；base64 是一种把二进制数据安全写成普通字符串的方式。出来的是一个 ClientEnvelope，里面的 event 是 ClientMessageChunk，并带上这些编号和大小信息。

调用关系：它被测试函数在需要伪造客户端分片时调用，特别是在拼接成功和切换流的测试里很关键。它不做真正的重组，只负责把测试材料包装成重组器 observe 能看懂的输入。

调用图：被 2 处调用（reassembles_client_message_chunks, resets_incomplete_client_assembly_when_stream_changes）。

fn remote_control_auth_manager() -> Arc<AuthManager>

作用：造一个测试用的登录管理器。它不用真的登录 ChatGPT，而是塞入一份假的、可用的 ChatGPT 身份，方便测试远程控制需要认证的流程。

数据流：进去没有参数 → 它创建一份测试专用的假 ChatGPT 登录信息，再交给测试辅助函数包装成 AuthManager（登录管理器）→ 出来一个可共享的登录管理器，测试可以拿它当作已登录用户来用。

调用关系：很多测试在启动远程控制前会先调用它，例如启动、启用禁用、WebSocket 连接和消息转发测试。它把造假身份的活交给 create_dummy_chatgpt_auth_for_testing 和 auth_manager_from_auth。

调用图：调用 2 个内部函数（auth_manager_from_auth, create_dummy_chatgpt_auth_for_testing）；被 12 处调用（ephemeral_enable_preserves_durable_preference, explicit_disabled_start_ignores_persisted_enable, managed_disable_overrides_startup_and_persisted_enablement, plain_start_resolves_persisted_remote_control_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, remote_control_start_allows_remote_control_invalid_url_when_disabled, remote_control_start_reports_missing_state_db_as_disabled_when_enabled, remote_control_transport_clears_outgoing_buffer_when_backend_acks, remote_control_transport_manages_virtual_clients_and_routes_messages (+2 more)）。

fn remote_control_auth_manager_with_home(codex_home: &TempDir) -> Arc<AuthManager>

作用：造一个带指定用户目录的测试登录管理器。这样测试可以把登录文件和状态文件都放进临时目录，避免污染真实环境。

数据流：进去一个临时目录 → 它取出目录路径，配上一份假 ChatGPT 登录信息 → 出来一个绑定这个目录的 AuthManager，后续测试可以验证从磁盘读写登录和登记信息的行为。

调用关系：需要测试“已保存登记”“刷新旧登记”“按客户端名区分登记”的用例会调用它。它底层依赖 auth_manager_from_auth_with_home 和假登录创建函数。

调用图：调用 2 个内部函数（auth_manager_from_auth_with_home, create_dummy_chatgpt_auth_for_testing）；被 6 处调用（remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, remote_control_http_mode_preserves_stale_enrollment_when_reenrollment_fails, remote_control_http_mode_reenrolls_after_explicit_missing_server_404, remote_control_http_mode_reenrolls_when_refresh_reports_stale_enrollment, remote_control_http_mode_refreshes_persisted_enrollment_before_connecting, remote_control_stdio_mode_waits_for_client_name_before_connecting）；外部调用 1 个（path）。

fn remote_control_auth_dot_json(account_id: Option<&str>) -> AuthDotJson

作用：生成一份假的 auth.json 登录文件内容。它可以选择带不带账号 ID，用来测试远程控制是否会等待账号 ID 准备好。

数据流：进去一个可选账号 ID → 它拼出一个假的 JWT（登录令牌格式），解析出用户信息，再填入访问令牌、刷新令牌和账号字段 → 出来一份 AuthDotJson，可被保存到临时用户目录。

调用关系：等待账号 ID 和切换账号的测试会用它先写入不同登录状态。它会调用 parse_chatgpt_jwt_claims 来把假 JWT 解析成测试可用的数据。

调用图：调用 1 个内部函数（parse_chatgpt_jwt_claims）；被 2 处调用（persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, remote_control_waits_for_account_id_before_enrolling）；外部调用 4 个（now, format!, json!, to_vec）。

async fn remote_control_state_runtime(codex_home: &TempDir) -> Arc<StateRuntime>

作用：创建测试用的状态数据库运行时。远程控制会把“这个账号是否启用、登记过哪个服务器”这类信息存进去。

数据流：进去一个临时目录 → 它在这个目录下初始化 StateRuntime（状态数据库运行环境）→ 出来一个可共享的数据库句柄，测试用它写入或读取远程控制登记记录。

调用关系：几乎所有涉及持久化偏好、登记记录、启用禁用的测试都会先调用它。它把真正初始化数据库的工作交给 StateRuntime::init。

调用图：调用 1 个内部函数（init）；被 19 处调用（ephemeral_enable_preserves_durable_preference, explicit_disabled_start_ignores_persisted_enable, managed_disable_overrides_startup_and_persisted_enablement, persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, plain_start_resolves_persisted_remote_control_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, remote_control_http_mode_preserves_stale_enrollment_when_reenrollment_fails, remote_control_http_mode_reenrolls_after_explicit_missing_server_404 (+9 more)）；外部调用 1 个（path）。

async fn plain_start_resolves_persisted_remote_control_preference()

作用：测试普通启动时，远程控制会不会正确读取以前保存的启用偏好。重点是确认“已启用”会继续启用，而“禁用、未设置、缺失”都不会误启用。

数据流：进去没有外部输入 → 它先在临时数据库里写入几种不同偏好，再创建 RemoteControlWebsocket 并让它解析 Unknown 状态 → 出来是断言后的期望状态，同时 desired_state_tx 里的期望状态被更新。

调用关系：这是直接测试 RemoteControlWebsocket::resolve_unknown_desired_state 的用例。它会借助 remote_control_state_runtime、remote_control_auth_manager 和 test_server_name 搭好测试环境。

调用图：调用 7 个内部函数（new, normalize_remote_control_url, remote_control_auth_manager, remote_control_state_runtime, test_server_name, new, new）；外部调用 9 个（new, new, new, new, assert!, assert_eq!, format!, channel, channel）。

async fn explicit_disabled_start_ignores_persisted_enable()

作用：测试如果启动参数明确说“这次先禁用”，即使数据库里以前保存的是启用，也不能偷偷连上。

数据流：进去没有参数 → 它写入一条持久化启用记录，再用 DisabledEphemeral 模式启动远程控制 → 出来是断言：当前状态为 Disabled，数据库里的旧记录仍原样保留。

调用关系：它围绕 start_remote_control 做启动行为验证。它会用 remote_control_state_runtime 准备数据库，用 remote_control_auth_manager 准备登录。

调用图：调用 3 个内部函数（normalize_remote_control_url, remote_control_auth_manager, remote_control_state_runtime）；外部调用 4 个（new, new, assert_eq!, channel）。

async fn managed_disable_overrides_startup_and_persisted_enablement()

作用：测试“被管理策略禁用”时，任何启动模式和历史启用记录都不能覆盖它。这里的管理策略类似公司管控开关，优先级最高。

数据流：进去没有参数 → 它准备一个假的后端监听器和一条已启用的数据库记录，再用 DisabledByRequirements 策略启动 → 出来是断言：状态是 Disabled，启用和禁用接口都返回权限错误，而且后端没有收到连接。

调用关系：它测试 start_remote_control 和 RemoteControlHandle 的策略检查。会调用 remote_control_url_for_listener、remote_control_state_runtime 和 remote_control_auth_manager 来搭场景。

调用图：调用 4 个内部函数（normalize_remote_control_url, remote_control_auth_manager, remote_control_state_runtime, remote_control_url_for_listener）；外部调用 8 个（new, from_millis, bind, new, assert!, assert_eq!, channel, timeout）。

fn remote_control_url_for_listener(listener: &TcpListener) -> String

作用：把测试用 TCP 监听器的地址转换成远程控制 URL。这样本来要连真实后端的代码，会改连本机假服务器。

数据流：进去一个 TcpListener → 它读取监听器实际绑定的 IP 和端口 → 出来一个形如 http://地址/backend-api/ 的字符串。

调用关系：大量网络测试都会先开本地监听器，再调用它生成配置 URL。它只负责拼地址，不参与真正通信。

调用图：被 17 处调用（managed_disable_overrides_startup_and_persisted_enablement, persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, remote_control_http_mode_preserves_stale_enrollment_when_reenrollment_fails, remote_control_http_mode_reenrolls_after_explicit_missing_server_404, remote_control_http_mode_reenrolls_when_refresh_reports_stale_enrollment, remote_control_http_mode_refreshes_persisted_enrollment_before_connecting, remote_control_start_allows_missing_auth_when_enabled (+7 more)）；外部调用 2 个（local_addr, format!）。

fn test_server_name() -> String

作用：取得当前机器名，作为测试里的服务器名称。远程控制登记时会把这个名字报给后端。

数据流：进去没有参数 → 它读取系统主机名，转成字符串并去掉两端空白 → 出来一个服务器名字符串。

调用关系：需要比较状态通知或登记信息里的 server_name 时会调用它。它依赖 gethostname 这个系统调用包装。

调用图：被 5 处调用（plain_start_resolves_persisted_remote_control_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_handle_with_current_enrollment, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, remote_control_http_mode_preserves_stale_enrollment_when_reenrollment_fails）；外部调用 1 个（gethostname）。

fn remote_control_handle_with_current_enrollment(
    remote_control_url: &str,
    auth_manager: Arc<AuthManager>,
) -> RemoteControlHandle

作用：手工造一个已经有当前登记信息的 RemoteControlHandle。它用来测试句柄本身的行为，不需要真的启动网络任务。

数据流：进去远程控制 URL 和登录管理器 → 它创建期望状态通道、状态通道、规范化后的目标地址和一份带令牌的当前登记 → 出来一个 RemoteControlHandle，里面已经装好可用的登记状态。

调用关系：目前由 ephemeral_enable_preserves_durable_preference 使用。它会调用 normalize_remote_control_url 和 test_server_name 来填齐远程控制句柄所需字段。

调用图：调用 3 个内部函数（new, normalize_remote_control_url, test_server_name）；被 1 处调用（ephemeral_enable_preserves_durable_preference）；外部调用 4 个（new, from_unix_timestamp, new, channel）。

async fn ephemeral_enable_preserves_durable_preference()

作用：测试“临时启用”不会破坏用户已经保存的长期偏好。临时启用像临时开灯，不应该改掉墙上的总开关设置。

数据流：进去没有参数 → 它造一个带当前登记的句柄，先设置持久偏好为启用再临时启用，又设置为禁用后再临时启用 → 出来是断言：已有持久启用偏好被保留，从禁用临时启用时偏好为空。

调用关系：它直接调用 remote_control_handle_with_current_enrollment 来得到测试对象，并用 remote_control_state_runtime 补上数据库。核心验证对象是 RemoteControlHandle::enable_ephemeral。

调用图：调用 3 个内部函数（remote_control_auth_manager, remote_control_handle_with_current_enrollment, remote_control_state_runtime）；外部调用 2 个（new, assert_eq!）。

fn remote_control_server_token_response(
    server_id: &str,
    environment_id: &str,
    remote_control_token: &str,
) -> serde_json::Value

作用：生成后端返回的远程控制服务器令牌 JSON。测试用它模拟登记或刷新成功后的响应。

数据流：进去 server_id、environment_id 和 remote_control_token → 它把这些字段加上固定的过期时间组成 JSON → 出来一个 serde_json::Value，可直接写进 HTTP 响应体。

调用关系：所有需要假装后端返回登记结果或刷新结果的测试都会用它。它只负责造数据，通常随后交给 respond_with_json 发回客户端。

调用图：被 13 处调用（persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, remote_control_http_mode_reenrolls_after_explicit_missing_server_404, remote_control_http_mode_reenrolls_when_refresh_reports_stale_enrollment, remote_control_http_mode_refreshes_persisted_enrollment_before_connecting, remote_control_stdio_mode_waits_for_client_name_before_connecting, remote_control_transport_clears_outgoing_buffer_when_backend_acks, remote_control_transport_manages_virtual_clients_and_routes_messages (+3 more)）；外部调用 1 个（json!）。

async fn expect_remote_control_status(
    status_rx: &mut watch::Receiver<RemoteControlStatusChangedNotification>,
    expected_status: Option<RemoteControlConnectionStatus>,
    expected_environment

作用：等待远程控制状态发生一次变化，并检查状态内容是否符合预期。它帮测试避免“还没更新就断言”的竞态问题。

数据流：进去状态接收器、可选的期望连接状态、可选环境 ID → 它最多等 5 秒收到状态变化，再检查服务器名、安装 ID、环境 ID 和可选状态 → 出来没有返回值，失败时测试直接报错。

调用关系：连接、重连、刷新、登记等测试都会用它确认状态通知。它读取 watch 通道中的 RemoteControlStatusChangedNotification。

调用图：被 9 处调用（remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, remote_control_http_mode_reenrolls_after_explicit_missing_server_404, remote_control_http_mode_reenrolls_when_refresh_reports_stale_enrollment, remote_control_transport_clears_outgoing_buffer_when_backend_acks, remote_control_transport_manages_virtual_clients_and_routes_messages, remote_control_transport_reconnects_after_disconnect, remote_control_transport_refreshes_server_token_after_websocket_unauthorized）；外部调用 5 个（from_secs, assert_eq!, borrow, changed, timeout）。

async fn expect_remote_control_status_snapshot(
    status_rx: &mut watch::Receiver<RemoteControlStatusChangedNotification>,
    expected_status: RemoteControlStatusChangedNotification,
)

作用：等待状态通道最终出现某个完整快照。它适合状态可能跳几次的场景，只要最后等到目标状态就算通过。

数据流：进去状态接收器和完整期望状态 → 如果当前已经匹配就立即返回，否则循环等待变化，最多等 5 秒 → 出来没有返回值，超时会打印期望状态和当前最新状态。

调用关系：启用禁用切换、泛化 404 后恢复连接等测试会用它。它比 expect_remote_control_status 更严格，因为要整条通知完全相等。

调用图：被 2 处调用（remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404）；外部调用 6 个（from_secs, clone, assert!, borrow, changed, timeout）。

async fn remote_control_transport_manages_virtual_clients_and_routes_messages()

作用：测试远程控制能把云端来的“虚拟客户端”当成普通客户端接入，并正确转发双方消息。这里的虚拟客户端就是通过 WebSocket 远程连进来的客户端。

数据流：进去没有参数 → 它启动远程控制、模拟登记和 WebSocket，发送 ping、非初始化消息、initialize 请求、后续通知和关闭事件 → 出来是断言：连接打开、消息转入主传输层、服务端消息转回 WebSocket、关闭后状态回到 unknown。

调用关系：这是文件里覆盖面很大的端到端测试。它调用 accept_http_request、accept_remote_control_connection、send_client_event、read_server_event 等工具，来驱动 start_remote_control 创建的后台任务。

调用图：调用 11 个内部函数（new, normalize_remote_control_url, accept_http_request, accept_remote_control_connection, expect_remote_control_status, remote_control_auth_manager, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json (+1 more)）；外部调用 15 个（new, from_secs, ConfigWarning, bind, new, Notification, Request, Integer, AppServerNotification, new (+5 more)）。

async fn remote_control_transport_reconnects_after_disconnect()

作用：测试 WebSocket 断开后远程控制会自动重连。网络连接掉线很常见，这个测试保证通道不会一次断开就彻底死掉。

数据流：进去没有参数 → 它先完成登记并接受第一次 WebSocket，再主动关闭它，然后等待第二次连接并发送 initialize → 出来是断言：第二次连接仍带正确令牌，并能打开新的远程客户端连接。

调用关系：它通过 accept_remote_control_backend_connection 捕获两次握手请求，通过 transport_event_rx 验证重连后仍会产生 ConnectionOpened。

调用图：调用 9 个内部函数（accept_http_request, accept_remote_control_backend_connection, expect_remote_control_status, remote_control_auth_manager, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json, send_client_event）；外部调用 11 个（new, from_secs, bind, new, Request, Integer, new, assert_eq!, json!, panic! (+1 more)）。

async fn remote_control_transport_refreshes_server_token_after_websocket_unauthorized()

作用：测试 WebSocket 连接收到 401 Unauthorized（令牌无效）后，会先刷新服务器令牌再重新连接。

数据流：进去没有参数 → 它让第一次 WebSocket 握手返回 401，再模拟后端 refresh 接口返回新令牌 → 出来是断言：后续 WebSocket 握手使用刷新后的 Bearer 令牌。

调用关系：它测试登记令牌失效时的恢复路径。它用 accept_http_request 捕获普通 HTTP 请求，用 accept_remote_control_backend_connection 捕获最终成功的 WebSocket 握手。

调用图：调用 9 个内部函数（accept_http_request, accept_remote_control_backend_connection, expect_remote_control_status, remote_control_auth_manager, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json, respond_with_status）；外部调用 4 个（new, bind, new, assert_eq!）。

async fn remote_control_start_allows_remote_control_invalid_url_when_disabled()

作用：测试远程控制处于禁用启动路径时，不会因为 URL 看起来不适合连接就启动失败。禁用状态下本来就不会连，没必要过早报错。

数据流：进去没有参数 → 它传入一个不可用于测试连接的 URL，并用 ResolvePersisted 模式启动但没有状态数据库 → 出来是断言：启动成功，取消令牌后后台任务能正常退出。

调用关系：它直接验证 start_remote_control 的宽容启动行为。只需要 remote_control_auth_manager 和取消令牌，不需要假后端真正接收连接。

调用图：调用 1 个内部函数（remote_control_auth_manager）；外部调用 3 个（new, from_secs, timeout）。

async fn remote_control_start_allows_missing_auth_when_enabled()

作用：测试即使用户还没登录，远程控制也可以先启动后台任务，但必须等登录可用后才连接后端。

数据流：进去没有参数 → 它创建一个没有登录凭据的 AuthManager，按启用模式启动远程控制，然后短时间监听后端是否有连接 → 出来是断言：启动成功，但假后端没有收到任何请求。

调用关系：它围绕 start_remote_control 的“等待认证”行为。它使用 remote_control_state_runtime 准备数据库，用 remote_control_url_for_listener 指向本地假后端。

调用图：调用 4 个内部函数（remote_control_state_runtime, remote_control_url_for_listener, default, shared）；外部调用 6 个（new, from_millis, from_secs, bind, new, timeout）。

async fn remote_control_start_reports_missing_state_db_as_disabled_when_enabled()

作用：测试没有状态数据库时，即使请求启用远程控制，也应该报告不可用并保持禁用。因为没有数据库就无法安全保存登记和偏好。

数据流：进去没有参数 → 它不给 state_db，却用启用模式启动远程控制，再尝试临时启用 → 出来是断言：状态保持 Disabled、不会连接后端、enable_ephemeral 返回 Unavailable。

调用关系：它验证 start_remote_control 和 RemoteControlHandle 在缺少 StateRuntime 时的保护逻辑。网络侧用 remote_control_url_for_listener 创建但不应收到连接。

调用图：调用 2 个内部函数（remote_control_auth_manager, remote_control_url_for_listener）；外部调用 6 个（new, from_millis, from_secs, bind, assert_eq!, timeout）。

async fn remote_control_handle_enable_disable_stops_and_restarts_connections()

作用：测试通过句柄禁用远程控制会关闭已有 WebSocket，通过句柄重新启用又会重新连接。它确认开关真的控制网络连接，而不是只改状态文字。

数据流：进去没有参数 → 它启动并连上假后端，然后调用 disable，检查连接关闭且不重连，再调用 enable，检查状态变为 Connecting 并建立第二条 WebSocket → 出来是多次状态和连接行为的断言。

调用关系：它重点测试 RemoteControlHandle::disable 和 RemoteControlHandle::enable。辅助函数 accept_http_request、accept_remote_control_connection、expect_remote_control_status_snapshot 负责模拟后端和确认状态。

调用图：调用 10 个内部函数（accept_http_request, accept_remote_control_connection, expect_remote_control_status, expect_remote_control_status_snapshot, remote_control_auth_manager, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json, test_server_name）；外部调用 7 个（new, from_millis, from_secs, bind, new, assert_eq!, timeout）。

async fn remote_control_transport_clears_outgoing_buffer_when_backend_acks()

作用：测试后端确认收到某条服务端消息后，本地会清掉对应的待发送缓存。这样断线重连后不会把已经确认的旧消息再发一遍。

数据流：进去没有参数 → 它建立远程客户端连接，发送一条服务端通知，读取其 stream_id，再让后端发 Ack 确认，随后关闭客户端和 WebSocket 并重连 → 出来是断言：重连后的 ping 只显示 unknown，不会重放那条 stale 消息。

调用关系：它测试远程传输层的确认和缓存清理机制。它会调用 read_server_event_with_stream_id 拿到消息流 ID，再用 send_client_event 发送 Ack。

调用图：调用 11 个内部函数（new, accept_http_request, accept_remote_control_connection, expect_remote_control_status, read_server_event_with_stream_id, remote_control_auth_manager, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json (+1 more)）；外部调用 13 个（new, from_secs, ConfigWarning, bind, new, Request, Integer, AppServerNotification, new, assert_eq! (+3 more)）。

async fn remote_control_http_mode_enrolls_before_connecting()

作用：测试 HTTP 模式下必须先向后端登记，再用登记返回的服务器令牌建立 WebSocket。登记就像先办通行证，再进门。

数据流：进去没有参数 → 它启动远程控制，捕获 enroll 请求并检查认证头、安装 ID、机器信息，请求成功后捕获 WebSocket 握手，再模拟远程客户端 initialize 和服务端回包 → 出来是断言：请求顺序、请求头、消息转发都正确。

调用关系：这是登记流程的端到端测试。它使用 accept_http_request 检查 HTTP 登记，用 accept_remote_control_backend_connection 检查 WebSocket 头，用 send_client_event 和 read_server_event 验证消息通路。

调用图：调用 10 个内部函数（new, accept_http_request, accept_remote_control_backend_connection, expect_remote_control_status, remote_control_auth_manager, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json, send_client_event）；外部调用 15 个（new, from_secs, ConfigWarning, bind, new, Request, Integer, AppServerNotification, Response, new (+5 more)）。

async fn remote_control_http_mode_refreshes_persisted_enrollment_before_connecting()

作用：测试如果本地已经保存过登记信息，启动时会先刷新旧登记，而不是重新登记。这样能复用原来的 server_id。

数据流：进去没有参数 → 它先把一条没有令牌的登记写入数据库，再启动远程控制，捕获 refresh 请求并返回新令牌，最后捕获 WebSocket 握手 → 出来是断言：握手使用原 server_id 和刷新后的令牌，数据库里的登记仍可加载。

调用关系：它调用 update_persisted_remote_control_enrollment 预置旧登记，再通过 accept_http_request 和 accept_remote_control_backend_connection 验证刷新后连接。

调用图：调用 9 个内部函数（update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, remote_control_auth_manager_with_home, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json）；外部调用 4 个（new, bind, new, assert_eq!）。

async fn remote_control_stdio_mode_waits_for_client_name_before_connecting()

作用：测试 stdio 模式下会先等客户端名称到达，再读取对应的持久化登记并连接。stdio 是标准输入输出通信方式，客户端名用于区分不同调用方。

数据流：进去没有参数 → 它保存一条带 app_server_client_name 的登记，启动时传入一个还没发送名称的 oneshot 通道，确认不会连接；发送名称后，再检查 refresh 和 WebSocket → 出来是断言：只有拿到客户端名后才连接，并使用对应 server_id。

调用关系：它测试 start_remote_control 对 app_server_client_name_rx 的等待。预置登记由 update_persisted_remote_control_enrollment 完成，网络请求由测试辅助函数捕获。

调用图：调用 9 个内部函数（update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, remote_control_auth_manager_with_home, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json）；外部调用 6 个（new, from_millis, bind, new, assert_eq!, timeout）。

async fn remote_control_waits_for_account_id_before_enrolling()

作用：测试登录信息里还没有账号 ID 时，远程控制不会急着登记；等账号 ID 出现后，会立刻继续。

数据流：进去没有参数 → 它先保存一份不带 account_id 的登录文件并启动远程控制，确认后端没请求；再写入带 account_id 的登录文件并 reload → 出来是断言：远程控制被唤醒，发出 enroll 请求并成功连接 WebSocket。

调用关系：它使用 remote_control_auth_dot_json 制造两种登录文件，通过 auth_manager.reload 触发认证变化。accept_http_request 和 accept_remote_control_backend_connection 负责观察后续网络动作。

调用图：调用 10 个内部函数（normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, remote_control_auth_dot_json, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json, default, shared）；外部调用 8 个（new, from_millis, bind, new, assert_eq!, save_auth, gethostname, timeout）。

async fn persisted_enable_does_not_follow_auth_to_an_account_without_a_preference()

作用：测试“账号 A 保存了启用”不会在切换到没有偏好的账号 B 后继续启用。每个账号的远程控制开关必须分开算。

数据流：进去没有参数 → 它给账号 A 写入启用登记并启动连接，然后把登录切到账号 B，关闭旧 WebSocket → 出来是断言：期望状态变为 Disabled，后端不再收到账号 B 的登记请求，数据库也没有账号 B 的登记。

调用关系：它覆盖账号切换后的持久化偏好隔离。它用 remote_control_auth_dot_json 写不同账号登录，用 desired_state_rx 等待远程控制自动禁用。

调用图：调用 11 个内部函数（update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, remote_control_auth_dot_json, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json, default (+1 more)）；外部调用 8 个（new, from_millis, from_secs, bind, new, assert_eq!, save_auth, timeout）。

async fn remote_control_http_mode_reenrolls_when_refresh_reports_stale_enrollment()

作用：测试刷新旧登记时如果后端说 404，说明本地登记过期了，此时应该重新登记并保存新记录。

数据流：进去没有参数 → 它保存一条 stale 旧登记，启动后让 refresh 返回 404，再让 enroll 返回新 server_id 和环境 ID，最后接受 WebSocket → 出来是断言：连接用新 server_id，数据库记录也更新为新登记且保留启用偏好。

调用关系：它测试 refresh 失败后的重新登记路径。会用 expect_remote_control_status 观察环境 ID 从旧登记切换到新登记。

调用图：调用 11 个内部函数（update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, expect_remote_control_status, remote_control_auth_manager_with_home, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json (+1 more)）；外部调用 5 个（new, bind, new, assert_eq!, gethostname）。

async fn remote_control_http_mode_reenrolls_after_explicit_missing_server_404()

作用：测试 WebSocket 握手阶段如果后端明确说“远程服务器不存在”，也要重新登记。这里的 404 带有特定错误内容，不是普通网页找不到。

数据流：进去没有参数 → 它先刷新旧登记成功，再让 WebSocket GET 返回包含 Remote app server not found 的 404，然后模拟重新 enroll 并连接 → 出来是断言：新连接使用新的 server_id，数据库更新成新登记。

调用关系：它覆盖“刷新成功但连接时发现 server_id 已失效”的恢复路径。accept_http_request 捕获失败握手，respond_with_status 返回明确 404，随后走重新登记流程。

调用图：调用 11 个内部函数（update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, expect_remote_control_status, remote_control_auth_manager_with_home, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener, respond_with_json (+1 more)）；外部调用 6 个（new, bind, new, assert_eq!, gethostname, json!）。

async fn remote_control_http_mode_preserves_stale_enrollment_when_reenrollment_fails()

作用：测试旧登记失效后，如果重新登记也失败，本地不能把旧登记删掉。保留旧数据可以让后续重试还有线索。

数据流：进去没有参数 → 它保存一条旧登记，让 refresh 返回 404，再让 enroll 返回 500，随后下一轮 refresh 也失败 → 出来是断言：内存中的 current_enrollment 和数据库里的旧登记都还在。

调用关系：它测试失败恢复时的数据保护。它用 respond_with_status 制造 404 和 500，最后直接检查 RemoteControlHandle 的当前登记和 StateRuntime 里的记录。

调用图：调用 8 个内部函数（update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, remote_control_auth_manager_with_home, remote_control_state_runtime, remote_control_url_for_listener, respond_with_status, test_server_name）；外部调用 4 个（new, bind, new, assert_eq!）。

async fn remote_control_http_mode_preserves_enrollment_after_generic_websocket_404()

作用：测试 WebSocket 遇到普通 404 时，不要误以为登记失效。只有明确的“服务器不存在”错误才该重新登记。

数据流：进去没有参数 → 它刷新旧登记成功，然后让 WebSocket GET 返回普通 404 和一些追踪头，再检查数据库仍保留旧登记，之后接受下一次 WebSocket 连接 → 出来是断言：仍然使用旧 server_id 和刷新令牌，并最终连接成功。

调用关系：它区分两种 404 的处理方式。respond_with_status_and_headers 用来模拟普通 404，expect_remote_control_status_snapshot 用来确认后续成功连接。

调用图：调用 13 个内部函数（update_persisted_remote_control_enrollment, normalize_remote_control_url, accept_http_request, accept_remote_control_backend_connection, expect_remote_control_status, expect_remote_control_status_snapshot, remote_control_auth_manager_with_home, remote_control_server_token_response, remote_control_state_runtime, remote_control_url_for_listener (+3 more)）；外部调用 4 个（new, bind, new, assert_eq!）。

async fn accept_remote_control_connection(listener: &TcpListener) -> WebSocketStream<TcpStream>

作用：在测试假服务器上接受一个 WebSocket 连接。它只关心连接成功，不额外保存握手请求头。

数据流：进去一个 TcpListener → 它最多等 5 秒接收 TCP 连接，并完成 WebSocket 握手 → 出来一个 WebSocketStream，测试可以继续收发远程控制消息。

调用关系：虚拟客户端路由、启用禁用、Ack 缓存清理等测试会调用它。它把底层握手交给 tokio_tungstenite 的 accept_async。

调用图：被 3 处调用（remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_transport_clears_outgoing_buffer_when_backend_acks, remote_control_transport_manages_virtual_clients_and_routes_messages）；外部调用 4 个（from_secs, accept, timeout, accept_async）。

async fn accept_http_request(listener: &TcpListener) -> CapturedHttpRequest

作用：在测试假服务器上接收一条普通 HTTP 请求，并把请求行、请求头、请求体都拆出来。这样测试可以精确检查远程控制发了什么。

数据流：进去一个 TcpListener → 它等待连接，逐行读取请求行和头部，再按 content-length 读取请求体 → 出来 CapturedHttpRequest，里面保留原始 TcpStream 以便继续回响应。

调用关系：登记、刷新、401、404 等 HTTP 场景都依赖它。通常调用后会把它返回的 stream 交给 respond_with_json 或 respond_with_status。

调用图：被 14 处调用（persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, remote_control_http_mode_preserves_stale_enrollment_when_reenrollment_fails, remote_control_http_mode_reenrolls_after_explicit_missing_server_404, remote_control_http_mode_reenrolls_when_refresh_reports_stale_enrollment, remote_control_http_mode_refreshes_persisted_enrollment_before_connecting, remote_control_stdio_mode_waits_for_client_name_before_connecting, remote_control_transport_clears_outgoing_buffer_when_backend_acks (+4 more)）；外部调用 8 个（new, new, from_secs, from_utf8, new, accept, timeout, vec!）。

async fn respond_with_json(mut stream: TcpStream, body: serde_json::Value)

作用：给测试捕获到的 HTTP 请求回一个 200 OK 的 JSON 响应。它用来假装后端接口成功返回。

数据流：进去一个 TCP 流和 JSON 值 → 它把 JSON 转成字符串，拼出带 content-type 和 content-length 的 HTTP 响应 → 写入并刷新到连接中，没有返回值。

调用关系：所有登记成功、刷新成功的测试都会用它。它通常接在 accept_http_request 后面，响应体常来自 remote_control_server_token_response。

调用图：被 13 处调用（persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, remote_control_handle_enable_disable_stops_and_restarts_connections, remote_control_http_mode_enrolls_before_connecting, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, remote_control_http_mode_reenrolls_after_explicit_missing_server_404, remote_control_http_mode_reenrolls_when_refresh_reports_stale_enrollment, remote_control_http_mode_refreshes_persisted_enrollment_before_connecting, remote_control_stdio_mode_waits_for_client_name_before_connecting, remote_control_transport_clears_outgoing_buffer_when_backend_acks, remote_control_transport_manages_virtual_clients_and_routes_messages (+3 more)）；外部调用 4 个（flush, write_all, to_string, format!）。

async fn respond_with_status(stream: TcpStream, status: &str, body: &str)

作用：给 HTTP 请求回一个指定状态码的简单响应。它适合测试 401、404、500 这类错误分支。

数据流：进去 TCP 流、状态文本和响应体 → 它不加额外头，直接转交给 respond_with_status_and_headers → 出来没有返回值，连接收到指定错误响应。

调用关系：它是 respond_with_status_and_headers 的简化版。令牌无效、旧登记失效、重新登记失败等测试会调用它制造后端错误。

调用图：调用 1 个内部函数（respond_with_status_and_headers）；被 4 处调用（remote_control_http_mode_preserves_stale_enrollment_when_reenrollment_fails, remote_control_http_mode_reenrolls_after_explicit_missing_server_404, remote_control_http_mode_reenrolls_when_refresh_reports_stale_enrollment, remote_control_transport_refreshes_server_token_after_websocket_unauthorized）。

async fn respond_with_status_and_headers(
    mut stream: TcpStream,
    status: &str,
    headers: &[(&str, &str)],
    body: &str,
)

作用：给 HTTP 请求回一个指定状态码、可附加自定义响应头的响应。它用于模拟更接近真实后端的错误返回。

数据流：进去 TCP 流、状态文本、额外响应头列表和响应体 → 它拼出完整 HTTP 响应，写入并刷新 → 出来没有返回值，客户端会看到指定状态和头部。

调用关系：普通 404 保留登记的测试会直接调用它；respond_with_status 也会把简单错误响应交给它处理。

调用图：被 2 处调用（remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, respond_with_status）；外部调用 3 个（flush, write_all, format!）。

async fn accept_remote_control_backend_connection(
    listener: &TcpListener,
) -> (CapturedWebSocketRequest, WebSocketStream<TcpStream>)

作用：接受一个 WebSocket 连接，同时把握手请求的路径和请求头抓下来。它让测试能确认远程控制带了正确令牌、server_id 和协议版本。

数据流：进去一个 TcpListener → 它等待 TCP 连接，用带回调的 WebSocket 握手读取请求 URI 和 headers → 出来一份 CapturedWebSocketRequest 加一个 WebSocketStream。

调用关系：需要检查 WebSocket 握手头的测试都会用它，比如登记后连接、刷新后连接、重连和令牌刷新。它底层使用 accept_hdr_async 来边握手边捕获请求。

调用图：被 10 处调用（persisted_enable_does_not_follow_auth_to_an_account_without_a_preference, remote_control_http_mode_enrolls_before_connecting, remote_control_http_mode_preserves_enrollment_after_generic_websocket_404, remote_control_http_mode_reenrolls_after_explicit_missing_server_404, remote_control_http_mode_reenrolls_when_refresh_reports_stale_enrollment, remote_control_http_mode_refreshes_persisted_enrollment_before_connecting, remote_control_stdio_mode_waits_for_client_name_before_connecting, remote_control_transport_reconnects_after_disconnect, remote_control_transport_refreshes_server_token_after_websocket_unauthorized, remote_control_waits_for_account_id_before_enrolling）；外部调用 6 个（new, from_secs, accept, new, timeout, accept_hdr_async）。

async fn send_client_event(
    websocket: &mut WebSocketStream<TcpStream>,
    client_envelope: ClientEnvelope,
)

作用：把一个远程客户端事件发进 WebSocket。测试用它模拟云端客户端发 ping、initialize、Ack 或关闭事件。

数据流：进去一个可写的 WebSocket 和 ClientEnvelope → 它把事件序列化成 JSON 文本帧 → 发送到 WebSocket，没有返回值，发送失败会让测试报错。

调用关系：消息路由、重连后初始化、Ack 缓存清理、HTTP 模式消息转发测试都会调用它。它是驱动远程控制协议输入的主要小工具。

调用图：被 4 处调用（remote_control_http_mode_enrolls_before_connecting, remote_control_transport_clears_outgoing_buffer_when_backend_acks, remote_control_transport_manages_virtual_clients_and_routes_messages, remote_control_transport_reconnects_after_disconnect）；外部调用 3 个（send, to_string, Text）。

async fn read_server_event(websocket: &mut WebSocketStream<TcpStream>) -> serde_json::Value

作用：从 WebSocket 读取一条服务端发给远程客户端的事件，但忽略 stream_id。适合测试只关心消息内容的情况。

数据流：进去一个 WebSocket → 它调用 read_server_event_with_stream_id 读取完整事件，然后丢掉 stream_id → 出来一个 JSON 值。

调用关系：它是 read_server_event_with_stream_id 的简化包装。需要检查服务端消息内容但不需要确认流 ID 的测试会用它。

调用图：调用 1 个内部函数（read_server_event_with_stream_id）。

async fn read_server_event_with_stream_id(
    websocket: &mut WebSocketStream<TcpStream>,
) -> (serde_json::Value, StreamId)

作用：从 WebSocket 读取服务端事件，并额外取出 stream_id。stream_id 可以理解为消息所在的编号通道，Ack 时要用它告诉对方确认了哪条流。

数据流：进去一个 WebSocket → 它循环等文本帧，遇到 Ping 会回 Pong，遇到关闭或二进制帧会报错；读到文本后解析 JSON，并从里面移除 stream_id → 出来事件 JSON 和 StreamId。

调用关系：Ack 缓存清理测试直接用它拿 stream_id；read_server_event 也调用它作为底层实现。它保证测试不会被 WebSocket 心跳帧干扰。

调用图：被 2 处调用（read_server_event, remote_control_transport_clears_outgoing_buffer_when_backend_acks）；外部调用 8 个（from_secs, next, send, new, panic!, from_str, timeout, Pong）。

async fn pipes_stdin_and_stdout_through_socket() -> anyhow::Result<()>

作用：这个测试函数验证 codex-stdio-to-uds 程序真的能把 stdin（标准输入）通过 Unix socket 发出去，并把 socket 的回复写到 stdout（标准输出）。有人改了这个工具后，可以靠它发现转发方向错了、没有退出、输出不对等问题。

数据流：进去的是一段测试输入 request、一个临时 socket 路径，以及真实启动的 codex-stdio-to-uds 子进程。函数先把 request 写成文件，建立 socket 监听；然后假服务器读取 socket 收到的数据并写回 response；同时子进程从文件读取标准输入，连接 socket，再把回复写到标准输出。出来的结果是几条断言：子进程必须正常退出，stdout 必须等于 response，服务器收到的内容必须等于 request；过程中还会收集 stderr 和服务器事件，方便失败时看清现场。

调用关系：这是整个文件唯一的测试入口，由 Tokio 测试框架自动运行。它自己搭好临时服务器，并通过系统命令启动 codex-stdio-to-uds 这个真正的可执行程序；中途会调用 socket 绑定、文件写入、进程启动、通道通信和断言等外部能力。测试完成时，它用断言把两边的结果对上：服务器证明“输入被送出去了”，子进程 stdout 证明“回复被带回来了”。

调用图：调用 1 个内部函数（bind）；外部调用 11 个（Ok, assert!, assert_eq!, eprintln!, format!, channel, write, new, spawn, spawn_blocking (+1 more)）。

fn danger_full_access_defaults_to_no_sandbox_without_network_requirements()

作用：检查在文件系统完全开放、网络也允许、并且没有额外网络托管要求时，系统默认不会套沙箱。意思是：既然用户选择了危险的完全访问，就不要假装还有隔离。

数据流：输入是一份“不限制文件访问”的策略、允许网络的策略、自动选择沙箱的偏好，以及“没有受管网络要求”的标记。测试把这些交给 SandboxManager 做初始选择。结果应该是 SandboxType::None，也就是不使用沙箱；测试用断言确认这一点。

调用关系：它直接测试 SandboxManager::select_initial 的一个基础分支。这个场景是其他限制场景的对照组：没有限制、没有特殊网络要求时，不应该调用平台沙箱。

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

fn danger_full_access_uses_platform_sandbox_with_network_requirements()

作用：检查即使文件系统是完全开放的，只要有受管网络要求，系统也会尽量选择平台沙箱。这里的重点是网络要求会改变沙箱选择。

数据流：输入仍然是不限制文件访问和允许网络，但这次“有受管网络要求”为真。测试先算出当前平台可用的沙箱类型作为期望值，再让 SandboxManager 选择。输出必须等于平台支持的沙箱；如果平台没有可用沙箱，就退回 None。

调用关系：它验证 SandboxManager::select_initial 会把网络托管要求纳入决策。它还通过 get_platform_sandbox 取得当前操作系统上理论应选的沙箱，用来和实际结果对比。

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

fn restricted_file_system_uses_platform_sandbox_without_managed_network()

作用：检查只要文件系统权限被限制，即使没有受管网络要求，也应该使用平台沙箱。因为限制文件访问必须有真正的围栏来执行。

数据流：输入是一份受限文件策略：根目录只读；网络允许；沙箱偏好为自动；没有受管网络要求。测试让 SandboxManager 选择初始沙箱。结果应等于当前平台可用沙箱，没有可用沙箱时才是 None。

调用关系：它测试 SandboxManager::select_initial 的文件权限分支。和完全开放的测试相对，它说明“文件系统受限”本身就足以触发沙箱选择。

调用图：调用 2 个内部函数（restricted, new）；外部调用 3 个（assert_eq!, get_platform_sandbox, vec!）。

fn transform_preserves_unrestricted_file_system_policy_for_restricted_network()

作用：检查把命令转换成执行请求时，如果文件系统原本是完全开放的，不会因为网络受限就把文件策略改掉。也就是说，网络限制和文件限制不能互相串味。

数据流：输入包括当前工作目录、一个简单的 true 命令、一份“文件不限制但网络受限”的权限档案，以及不启用沙箱的设置。transform 会把 URI 形式的路径转成绝对路径，并生成可执行请求。输出中工作目录保持正确，文件系统策略仍是 unrestricted，网络策略仍是 Restricted。

调用关系：它测试 SandboxManager::transform 的权限翻译过程。它用 PermissionProfile::from_runtime_permissions 先把运行时权限包装成权限档案，再检查 transform 拆回执行请求时没有改变含义。

调用图：调用 5 个内部函数（from_runtime_permissions, unrestricted, new, current_dir, from_abs_path）；外部调用 3 个（new, new, assert_eq!）。

fn transform_additional_permissions_enable_network_for_external_sandbox()

作用：检查外部沙箱模式下，命令自带的额外权限可以把网络从受限改成允许。这个测试防止额外权限被忽略。

数据流：输入是一份 External 权限档案，网络原本是 Restricted；命令里额外声明 network.enabled=true，并附带一个临时目录的文件权限。transform 合并这些信息后，输出的 permission_profile 和 network_sandbox_policy 都应该变成 Enabled。

调用关系：它测试 SandboxManager::transform 合并 AdditionalPermissionProfile 的行为。临时目录和文件权限主要用来模拟真实命令携带额外授权的情况，但这个测试关注的核心是网络权限是否被正确放开。

调用图：调用 5 个内部函数（from_read_write_roots, new, current_dir, from_absolute_path, from_abs_path）；外部调用 6 个（new, new, new, assert_eq!, canonicalize, vec!）。

fn transform_additional_permissions_preserves_denied_entries()

作用：检查新增文件权限时，原来明确禁止访问的路径不会被覆盖。这个很重要，因为“禁止”通常应该比“允许”更硬。

数据流：输入是一份受限文件策略：根目录只读，并且某个 denied 路径明确 Deny；命令额外请求另一个 allowed 路径的写权限。transform 合并后，输出策略应该依次保留根目录只读、保留 denied 路径禁止访问，再追加 allowed 路径写权限；网络仍保持 Restricted。

调用关系：它测试 SandboxManager::transform 在合并文件系统权限时的安全性。它特别防止一个危险错误：追加允许权限时不小心丢掉原有的拒绝规则。

调用图：调用 7 个内部函数（from_read_write_roots, from_runtime_permissions, restricted, new, current_dir, from_absolute_path, from_abs_path）；外部调用 7 个（default, new, new, new, assert_eq!, canonicalize, vec!）。

fn managed_mitm_ca_bundle_becomes_readable_for_restricted_sandbox()

作用：检查当使用受限沙箱时，受管的 MITM CA 证书包会被加入可读名单。MITM CA 可以理解成公司或系统用来检查 HTTPS 流量的可信证书文件；如果沙箱看不到它，网络请求可能会失败。

数据流：输入是一份只允许读取当前工作目录的受限权限档案，以及一个受管 CA 证书文件路径。with_managed_mitm_ca_readable_root 会把证书路径作为只读文件权限加入档案。输出再转回运行时文件策略时，应同时包含工作目录只读和证书文件只读。

调用关系：它直接测试 with_managed_mitm_ca_readable_root 这个辅助逻辑。它位于权限生成和命令执行之间，保证受限环境里仍能读取必要的证书文件。

调用图：调用 3 个内部函数（from_runtime_permissions, restricted, from_absolute_path）；外部调用 5 个（new, assert_eq!, canonicalize, with_managed_mitm_ca_readable_root, vec!）。

fn transform_linux_seccomp_request(
    codex_linux_sandbox_exe: &std::path::Path,
) -> super::SandboxExecRequest

作用：这是 Linux 专用的测试辅助函数，用来快速造出一个使用 LinuxSeccomp 沙箱的执行请求。seccomp 是 Linux 的系统调用过滤机制，可以限制程序能向操作系统请求什么操作。

数据流：输入是 codex-linux-sandbox 辅助程序的路径。函数创建 SandboxManager、取得当前目录、构造一个运行 true 命令的请求，并指定沙箱类型为 LinuxSeccomp。输出是 transform 生成的 SandboxExecRequest，供后面的测试检查其中的启动参数。

调用关系：它不是独立测试，而是被 transform_linux_seccomp_preserves_helper_path_in_arg0_when_available 和 transform_linux_seccomp_uses_helper_alias_when_launcher_is_not_helper_path 调用。这样两个测试不用重复搭建同样的 Linux seccomp 请求。

调用图：调用 3 个内部函数（new, current_dir, from_abs_path）；被 2 处调用（transform_linux_seccomp_preserves_helper_path_in_arg0_when_available, transform_linux_seccomp_uses_helper_alias_when_launcher_is_not_helper_path）；外部调用 2 个（new, new）。

fn wsl1_rejects_linux_bubblewrap_path()

作用：检查在 WSL1 环境下，需要走 bubblewrap 的 Linux 沙箱路径会被拒绝。WSL1 是早期 Windows Linux 子系统，和真正 Linux 内核行为不完全一样；bubblewrap 是一种 Linux 沙箱工具，在这里不能安全依赖。

数据流：输入包括受限文件策略、是否使用旧版 landlock、是否为了代理允许网络、以及 is_wsl1=true。测试多次调用 ensure_linux_bubblewrap_is_supported。只要这些组合会走 bubblewrap，就应该返回 Wsl1UnsupportedForBubblewrap 错误。

调用关系：它测试 Linux 平台兼容性检查函数 ensure_linux_bubblewrap_is_supported。这个检查发生在 transform 生成执行请求之前，用来提前阻止不支持的沙箱方案。

调用图：调用 1 个内部函数（restricted）；外部调用 2 个（assert!, vec!）。

fn wsl1_allows_non_bubblewrap_linux_paths()

作用：检查 WSL1 并不是一律禁止所有 Linux 沙箱路径，只禁止会用到 bubblewrap 的情况。这样可以避免过度拦截本来安全可用的路径。

数据流：输入是两组 WSL1 情况：一种是文件系统不限制且不需要代理网络，另一种是受限文件策略但使用旧版 landlock 且不允许代理网络。测试调用 ensure_linux_bubblewrap_is_supported，输出都应该是 Ok。

调用关系：它和 wsl1_rejects_linux_bubblewrap_path 配成一组：前者确认该拒绝的会拒绝，这个确认不该拒绝的会放行。两者一起锁住 WSL1 兼容性判断的边界。

调用图：调用 1 个内部函数（restricted）；外部调用 2 个（assert!, vec!）。

fn transform_linux_seccomp_preserves_helper_path_in_arg0_when_available()

作用：检查当提供的 Linux seccomp 辅助程序路径本身就是 codex-linux-sandbox 时，执行请求会把这个完整路径放进 arg0。arg0 是程序启动时看到的“自己叫什么”的名字。

数据流：输入是 /tmp/codex-linux-sandbox 这个辅助程序路径。测试通过 transform_linux_seccomp_request 生成执行请求。输出中的 exec_request.arg0 应该等于这个完整路径的字符串。

调用关系：它调用 transform_linux_seccomp_request 来搭建标准请求，然后只检查 arg0。它验证 transform 在辅助程序路径明确可用时，不会把路径改成别名。

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

fn transform_linux_seccomp_uses_helper_alias_when_launcher_is_not_helper_path()

作用：检查当启动器路径不是 codex-linux-sandbox 本身时，执行请求会把 arg0 改成 codex-linux-sandbox 这个别名。这样辅助程序即使通过别的启动器进入，也能按正确身份运行。

数据流：输入是 /tmp/codex 这个路径，它不是辅助程序的标准名字。测试用 transform_linux_seccomp_request 生成执行请求。输出中的 exec_request.arg0 应该是 codex-linux-sandbox，而不是原始路径。

调用关系：它也复用 transform_linux_seccomp_request。它和上一个 arg0 测试一起覆盖两种分支：路径已经是辅助程序时保留路径，不是时使用辅助程序别名。

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

fn legacy_landlock_flag_is_included_when_requested()

作用：这个测试确认：只有明确要求使用旧版 Landlock 时，生成的沙箱命令里才会出现 --use-legacy-landlock。这样能防止默认情况下误用旧兼容模式，也能保证需要兼容旧环境时不会漏掉开关。

数据流：它先准备一个简单命令 /bin/true，再准备命令工作目录 /tmp/link 和实际当前目录 /tmp。第一次生成沙箱参数时不要求旧版 Landlock，于是检查结果里没有对应开关；第二次把要求打开，再检查结果里确实有这个开关。输入是命令、路径和布尔开关，输出不是新数据，而是测试通过或失败。

调用关系：这个测试会在测试运行器执行测试套件时被调用。它主要把样例输入交给沙箱参数生成函数，然后用断言检查结果，像质检员一样确认“旧版 Landlock”这个开关没有被漏加或误加。它还会用 Path::new 准备路径，用 vec! 准备命令列表，用 assert_eq! 判断结果是否符合预期。

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

fn proxy_flag_takes_precedence_over_legacy_landlock()

作用：这个测试确认：当代理需要联网时，--allow-network-for-proxy 要优先于 --use-legacy-landlock。也就是说，即使同时传入“使用旧版 Landlock”的请求，代理联网模式也不能和它混在一起。

数据流：它准备一个只读权限配置、一个简单命令和两个路径，然后调用按权限配置生成沙箱参数的函数，并同时打开“旧版 Landlock”和“允许代理联网”两个输入开关。生成结果出来后，它检查参数里有代理联网开关，同时没有旧版 Landlock 开关。结果是测试通过或失败，不会修改外部状态。

调用关系：这个测试位于沙箱参数规则的冲突检查位置：当两个开关看起来都可能被加入时，它确认真正生效的是代理联网。它会先通过 PermissionProfile::read_only 准备只读权限配置，再把这些输入交给参数生成函数，最后用断言判断生成出来的命令参数是否遵守优先级规则。

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

fn permission_profile_flag_is_included()

作用：这个测试确认：使用权限配置生成沙箱参数时，命令参数里必须包含权限配置开关，并且命令工作目录也要正确写进去。这样沙箱才知道该按什么权限运行、从哪个目录启动命令。

数据流：它准备 /bin/true 这个命令、/tmp/link 这个命令工作目录、/tmp 这个当前目录，以及一个只读权限配置。然后生成沙箱参数，并在参数列表里找两组相邻内容：一组是 --permission-profile 后面跟着非空配置值，另一组是 --command-cwd 后面跟着 /tmp/link。如果都找到了，测试通过；否则说明参数生成有问题。

调用关系：这个测试检查的是权限配置这条路径是否把关键信息带进最终命令。它使用 PermissionProfile::read_only 创建测试用的权限档案，用路径构造函数准备目录，再调用沙箱参数生成函数。之后它不关心参数完整长什么样，只关心关键片段是否按顺序出现。

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

fn proxy_network_requires_managed_requirements()

作用：这个测试确认：代理联网不是随便就能打开，必须在“强制托管网络”开启时才允许。这样可以避免代理绕过项目对网络访问的统一控制。

数据流：它直接把 false 和 true 两种输入分别传给 allow_network_for_proxy。输入为 false 时，期望输出也是 false；输入为 true 时，期望输出是 true。它只验证这个判断规则，不创建命令，也不改动任何状态。

调用关系：这个测试处在更小、更基础的规则检查层。其他生成沙箱参数的逻辑会依赖“代理是否允许联网”这个判断，而这个测试专门确认这个判断没有变形。它把两个最简单的布尔值交给判断函数，再用断言确认结果。

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

fn assert_seatbelt_denied(stderr: &[u8], path: &Path)

作用：检查一个被沙盒拦下来的命令，报错信息是不是符合预期。这样测试不只看“失败了”，还确认失败原因确实是沙盒拒绝。

数据流：输入是一段标准错误输出和被访问的路径 → 它把错误输出转成文字，并拼出理想中的“Operation not permitted”提示 → 如果实际提示不匹配，就让测试失败；它不返回业务结果，只负责断言。

调用关系：在真正运行 sandbox-exec 的测试里使用，尤其是写 .codex、.git 等敏感文件失败后调用。它是这些集成式测试的验收员，确认失败来自 Seatbelt 拦截。

调用图：被 2 处调用（create_seatbelt_args_with_read_only_git_and_codex_subpaths, create_seatbelt_args_with_read_only_git_pointer_file）；外部调用 3 个（from_utf8_lossy, assert!, format!）。

fn absolute_path(path: &str) -> AbsolutePathBuf

作用：把测试里写死的绝对路径字符串变成项目使用的绝对路径类型。这样后面的沙盒策略不会误拿相对路径当安全路径。

数据流：输入是一个路径字符串 → 它把字符串变成 Path，再要求它必须是绝对路径 → 输出 AbsolutePathBuf；如果不是绝对路径，测试会直接失败。

调用关系：多个测试用它快速准备不可读路径或 Unix socket 路径。它把测试数据整理成 create_seatbelt_command_args 和 dynamic_network_policy 能接受的格式。

调用图：调用 1 个内部函数（from_absolute_path）；被 2 处调用（explicit_unreadable_paths_are_excluded_from_full_disk_read_and_write_access, explicit_unreadable_paths_are_excluded_from_readable_roots）；外部调用 1 个（new）。

fn seatbelt_policy_arg(args: &[String]) -> &str

作用：从生成出来的一串 sandbox-exec 命令参数里，找出真正的策略文本。测试需要直接检查策略内容时会用它。

数据流：输入是命令参数列表 → 它找到 “-p” 这个参数的位置，并取后面的字符串 → 输出 Seatbelt 策略文本；如果没有找到，说明参数生成错了，测试失败。

调用关系：很多测试先调用沙盒参数生成函数，再用它抽出策略文本检查。它像从包装盒里拿出说明书，方便后续断言逐条核对规则。

调用图：被 7 处调用（create_seatbelt_args_allowlists_explicit_unix_socket_paths_without_proxy, create_seatbelt_args_block_first_time_dot_codex_creation_with_metadata_name_regex, create_seatbelt_args_for_cwd_as_git_repo, create_seatbelt_args_preserves_full_network_with_explicit_unix_socket_paths, create_seatbelt_args_with_read_only_git_and_codex_subpaths, explicit_unreadable_paths_are_excluded_from_full_disk_read_and_write_access, explicit_unreadable_paths_are_excluded_from_readable_roots）。

fn seatbelt_protected_metadata_name_requirements(root: &Path) -> String

作用：生成一段用于保护敏感元数据目录名的 Seatbelt 检查文本，比如 .git、.codex 这类目录。它帮助测试确认策略会阻止新建或改写这些危险位置。

数据流：输入是一个根目录路径 → 它去掉多余的结尾斜杠，把路径和敏感目录名转义成正则表达式安全文本 → 输出一串 require-not 规则，表示这些敏感名字不能被写入。

调用关系：它主要服务于后面的策略文本断言。测试生成 Seatbelt 策略后，会拿它拼出的标准片段去比对，确认 metadata 保护确实出现在策略里。

调用图：外部调用 5 个（ends_with, len, pop, to_string_lossy, escape）。