核心共享协议与领域类型

fn new() -> Self

作用：生成一个新的 ThreadId。有人要开启一条新的对话线索、任务线索或事件链时，会用它拿到一个新的唯一编号。

数据流：进去不需要任何参数 → 它调用 UUID 库生成一个新的 UUID v7 编号 → 出来一个包着这个编号的 ThreadId，原来的系统状态不被改动。

调用关系：它是创建新线索编号的源头。很多测试和事件构造流程会直接用它；ThreadId::default 也把活儿交给它，所以默认创建 ThreadId 时同样会得到一个新编号。

调用图：被 465 处调用（collab_resume_begin_maps_to_item_started_resume_agent, collab_resume_end_maps_to_item_completed_resume_agent, ignores_user_message_item_lifecycle_events, preserves_user_message_client_id_from_legacy_event, rebuilds_sleep_item_from_persisted_completion, command_execution_started_helper_emits_once, complete_command_execution_item_emits_declined_once_for_pending_command, guardian_assessment_aborted_emits_completed_review_payload, guardian_assessment_completed_emits_review_payload, guardian_assessment_started_uses_event_turn_id_fallback (+15 more)）；外部调用 1 个（now_v7）。

fn from_string(s: &str) -> Result<Self, uuid::Error>

作用：把外部传进来的字符串变成 ThreadId。比如从 JSON、数据库、请求参数里读到一个编号时，需要先确认它真的是合法 UUID。

数据流：进去一个字符串切片 → 它让 UUID 库尝试解析这个字符串 → 如果格式正确，出来一个 ThreadId；如果格式不对，出来一个 uuid::Error 错误，提醒调用方这个编号不能用。

调用关系：它是“从文字恢复 ThreadId”的公共入口。TryFrom 的转换实现会调用它，很多序列化测试、事件重建和请求解析流程也会通过它把字符串编号变回强类型的 ThreadId。

调用图：被 318 处调用（thread_id, compaction_event_ingests_custom_fact, subagent_events_use_inherited_connection_unless_turn_connection_is_explicit, subagent_thread_started_other_serializes_explicit_parent_thread_id, subagent_thread_started_thread_spawn_serializes_thread_lineage, conversation_id_serializes_as_plain_string, serialize_get_conversation_summary, serialize_server_request, rollback_response_rebuilds_pathless_thread_from_stored_history, source_kind_matches_distinguishes_subagent_variants (+15 more)）；外部调用 1 个（parse_str）。

fn try_from(value: String) -> Result<Self, Self::Error>

作用：提供 Rust 标准转换写法，把 String 尝试转换成 ThreadId。这样调用方可以用通用的 try_from 语法，而不用记住专门的 from_string 名字。

数据流：进去一个拥有所有权的 String → 它把这个 String 当作普通字符串引用交给 ThreadId::from_string → 出来合法的 ThreadId，或者出来解析失败的 UUID 错误。

调用关系：它是标准转换接口的一部分，内部不自己解析，而是交给 ThreadId::from_string。需要从已有字符串构造 ThreadId 的测试、模型会话和数据恢复流程会用到这种转换方式。

调用图：被 10 处调用（reconstructs_collab_spawn_end_item_with_model_metadata, reconstructs_interrupted_send_input_as_completed_collab_call, test_model_client_session, fixed_thread_id, try_from, try_from, get_phase2_input_selection, stage1_output_from_row_if_thread_enabled, generic_url_target, suggestion_target）；外部调用 1 个（from_string）。

fn from(value: ThreadId) -> Self

作用：把 ThreadId 转成普通 String。这样需要把编号放进文本、JSON 字段或其他只认字符串的地方时，不用手动拆开它。

数据流：进去一个 ThreadId → 它调用这个编号的 to_string 显示逻辑 → 出来一个 UUID 格式的字符串。

调用关系：它依赖 ThreadId 的显示格式，也就是 ThreadId::fmt 间接提供的字符串样子。它让 ThreadId 能自然进入 Rust 的 From 转换体系。

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

fn default() -> Self

作用：给 ThreadId 提供默认值，但这个默认值不是空号，而是一个新生成的唯一编号。这样代码在需要“随手给一个编号”时也不会拿到危险的全零值。

数据流：进去不需要参数 → 它直接调用 ThreadId::new → 出来一个新的 ThreadId。

调用关系：它是默认构造入口，本质上只是把工作交给 ThreadId::new。很多测试和事件构造代码会用 default 来快速得到一个可用编号。

调用图：被 59 处调用（app_server_event_sink_uses_listener_fifo_for_goal_updates_and_clears, record_initial_history_reconstructs_typed_inter_agent_message, record_initial_history_resumed_aborted_turn_without_id_clears_active_turn_for_compaction_accounting, record_initial_history_resumed_bare_turn_context_does_not_hydrate_previous_turn_settings, record_initial_history_resumed_bare_turn_context_does_not_seed_reference_context_item, record_initial_history_resumed_does_not_seed_reference_context_item_after_compaction, record_initial_history_resumed_hydrates_previous_turn_settings_from_lifecycle_turn_with_missing_turn_context_id, record_initial_history_resumed_replaced_incomplete_compacted_turn_clears_reference_context_item, record_initial_history_resumed_rollback_drops_incomplete_user_turn_compaction_metadata, record_initial_history_resumed_rollback_skips_only_user_turns (+15 more)）；外部调用 1 个（new）。

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

作用：规定 ThreadId 被打印或转成文字时长什么样。它让 ThreadId 显示成内部 UUID 的标准字符串格式。

数据流：进去一个 ThreadId 和一个格式化输出器 → 它把内部 UUID 的显示结果写进输出器 → 出来格式化是否成功的结果。

调用关系：它服务于所有需要把 ThreadId 当文字看的地方，比如 to_string、日志输出，以及 String::from 间接使用的转换。

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

fn serialize(&self, serializer: S) -> Result<S::Ok, S::Error>

作用：规定 ThreadId 写成 JSON 或其他序列化格式时，表现为一个字符串。这样接口里不会暴露复杂内部结构，只看到普通编号文本。

数据流：进去一个 ThreadId 和序列化器 → 它把内部 UUID 收集成字符串形式交给序列化器 → 出来序列化成功后的结果，或者序列化错误。

调用关系：它在发送网络消息、保存数据、生成事件内容时被 serde（Rust 常用的序列化框架）调用。它和 ThreadId::deserialize 正好一进一出，保证写出去和读回来格式一致。

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

fn deserialize(deserializer: D) -> Result<Self, D::Error>

作用：规定从 JSON 或其他序列化格式读 ThreadId 时，应该先读一个字符串，再把它当 UUID 校验。这样错误编号会在入口处被挡住。

数据流：进去一个反序列化器 → 它先读出字符串，再用 UUID 解析器检查格式 → 如果合法，出来 ThreadId；如果不合法，出来带有原因的反序列化错误。

调用关系：它在接收请求、读取保存的数据或恢复事件时由 serde 自动调用。它和 ThreadId::serialize 配套，保证 ThreadId 对外永远像字符串，但内部永远是合法 UUID。

调用图：外部调用 2 个（deserialize, parse_str）。

fn schema_name() -> String

作用：告诉 JSON Schema 生成工具，这个类型在文档里叫 ThreadId。JSON Schema 是用来描述 JSON 数据长什么样、方便校验和生成文档的说明书。

数据流：进去不需要参数 → 它返回固定文字 ThreadId → 没有改动任何状态。

调用关系：它是 JsonSchema 实现的一部分，会在系统生成接口结构说明时被工具调用。它和 ThreadId::json_schema 一起告诉外部工具如何理解这个类型。

fn json_schema(generator: &mut SchemaGenerator) -> Schema

作用：告诉 JSON Schema 生成工具：ThreadId 在 JSON 里按字符串处理。也就是说，文档和校验规则看到的是 string，而不是一个复杂对象。

数据流：进去一个 SchemaGenerator（生成结构说明的工具）→ 它直接复用 String 的 JSON Schema → 出来一份字符串类型的 Schema。

调用关系：它是 JsonSchema 实现的核心部分。生成接口文档、校验规则或前后端契约时，会通过它把 ThreadId 描述成字符串。

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

fn test_thread_id_default_is_not_zeroes()

作用：测试默认生成的 ThreadId 不是全零 UUID。全零 UUID 通常像“空身份证号”，如果默认值是它，很多地方可能误把无效编号当成有效编号。

数据流：进去不需要参数 → 它调用 ThreadId::default 生成一个编号，再和 UUID 的全零值比较 → 如果两者不同，测试通过；如果相同，测试失败。

调用关系：它只在测试时运行，用来保护 ThreadId::default 和 ThreadId::new 的行为。只要有人改动默认生成逻辑，这个测试就能及时提醒不能生成空编号。

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

fn new() -> Self

作用：新建一个会话编号。有人开启新会话、测试里需要假会话，或者系统要给某次交互贴标签时会用它。

数据流：进去不需要任何输入 → 它调用 UUID 库生成一个新的 v7 UUID（带时间顺序特征的唯一编号）→ 出来一个包着这个 UUID 的 SessionId。

调用关系：它是创建会话编号的源头。默认值会间接用它，一些 websocket 测试、事件通知测试和配置摘要测试也会直接调用它，保证每次都有一个真实的新编号。

调用图：被 5 处调用（websocket_harness_with_provider_options, config_summary_entries_include_runtime_workspace_roots, test_send_event_as_notification, test_send_event_as_notification_with_meta, test_send_event_as_notification_with_meta_and_thread_id）；外部调用 1 个（now_v7）。

fn from_string(s: &str) -> Result<Self, uuid::Error>

作用：把外部传进来的字符串变成 SessionId。比如从配置、请求或保存的数据里读到一个会话编号时，就要先确认它真的是合法 UUID。

数据流：进去一个字符串 → 它交给 UUID 库检查并解析 → 如果格式对，出来 SessionId；如果格式错，出来解析错误，不会硬塞进系统。

调用关系：它是“外部文字编号进入程序”的入口。序列化事件、从线程响应配置会话等流程会用它，TryFrom 的转换实现也把具体解析工作交给它。

调用图：被 2 处调用（session_configured_from_thread_response, serialize_event）；外部调用 1 个（parse_str）。

fn try_from(value: String) -> Result<Self, Self::Error>

作用：提供一种 Rust 标准写法，把字符串类输入尝试转换成 SessionId。好处是调用方可以用统一的“尝试转换”习惯，而不用记住具体函数名。

数据流：进去一个字符串值 → 它取出字符串内容并调用 SessionId::from_string → 出来合法的 SessionId，或者 UUID 格式错误。

调用关系：它只是一个方便入口，真正干活的是 SessionId::from_string。它让别的代码能用标准转换接口接入这个会话编号类型。

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

fn from(value: SessionId) -> Self

作用：把 SessionId 变成普通字符串。需要把会话编号写进日志、JSON、网络消息或界面显示时会用到。

数据流：进去一个 SessionId → 它调用这个编号的字符串显示能力 → 出来 UUID 的文本形式。

调用关系：它连接了程序内部的强类型编号和外部常见的字符串格式。底层依赖 SessionId::fmt 提供的显示规则。

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

fn from(value: ThreadId) -> Self

作用：把 ThreadId 转成 SessionId。也就是说，同一个底层 UUID 可以换一个“会话编号”的身份来使用。

数据流：进去一个 ThreadId → 它取出里面的 UUID，不重新生成、不改变值 → 出来一个包着同一个 UUID 的 SessionId。

调用关系：它用于会话和线程概念需要对齐的地方，比如创建会话上下文、恢复子代理会话、生成线程开始事件等。测试也会验证转过去再转回来不会丢信息。

调用图：被 8 处调用（new, emit_subagent_session_started_includes_fork_lineage_from_session_configuration, make_session_and_context, make_session_and_context_with_auth_config_home_and_rx, resumed_subagent_session_keeps_inherited_session_id, session_configured_produces_thread_started_event, stream_stage_one_prompt, converts_to_and_from_thread_id）。

fn from(value: SessionId) -> Self

作用：把 SessionId 转成 ThreadId。它和反方向转换配套使用，让同一个编号能在“会话”和“线程”两个语义之间切换。

数据流：进去一个 SessionId → 它拿出里面的 UUID，原样放进 ThreadId → 出来一个 ThreadId。

调用关系：它是 SessionId::from 的反向搭档。转换测试会用它确认 SessionId 和 ThreadId 来回转换后仍然是同一个编号。

fn default() -> Self

作用：给 SessionId 提供默认创建方式。别人写“给我一个默认会话编号”时，拿到的不是空编号，而是一个新的真实编号。

数据流：进去不需要输入 → 它调用 SessionId::new → 出来一个新生成的 SessionId。

调用关系：它把 Rust 的默认值机制接到 SessionId::new 上。测试 tests::test_session_id_default_is_not_zeroes 专门确认默认值不是全零 UUID。

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

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

作用：规定 SessionId 被打印或转成文本时长什么样。简单说，就是显示里面那串 UUID。

数据流：进去一个 SessionId 和一个输出位置 → 它把内部 UUID 的显示结果写进去 → 调用方得到标准 UUID 字符串形式。

调用关系：String::from 和很多隐式的 to_string 场景都会依赖这个显示规则。它保证日志、调试输出和字符串转换看起来一致。

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

fn serialize(&self, serializer: S) -> Result<S::Ok, S::Error>

作用：把 SessionId 写成可传输、可保存的格式。这里它会被写成一个字符串，而不是复杂对象。

数据流：进去一个 SessionId 和 serde 的序列化器（负责把数据写成 JSON 等格式的工具）→ 它把内部 UUID 当作字符串交给序列化器 → 出来的 JSON 等数据里就是一段 UUID 文本。

调用关系：当协议消息、事件或配置要输出 SessionId 时，serde 会自动调用它。这样外部系统看到的会话编号始终是简单字符串。

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

fn deserialize(deserializer: D) -> Result<Self, D::Error>

作用：从 JSON 等外部数据里读回 SessionId。它会先按字符串读取，再检查是不是合法 UUID。

数据流：进去一个 serde 反序列化器（负责从 JSON 等格式读数据的工具）→ 它先读出字符串，再用 UUID 解析器校验 → 成功就出来 SessionId，失败就返回清楚的反序列化错误。

调用关系：当外部请求或保存的数据带着会话编号进入程序时，serde 会自动调用它。它和 SessionId::serialize 配成一对，保证写出去和读回来格式一致。

调用图：外部调用 2 个（deserialize, parse_str）。

fn schema_name() -> String

作用：告诉 JSON Schema 生成器，这个类型在接口说明里叫 SessionId。JSON Schema 可以理解成给 JSON 数据写的“格式说明书”。

数据流：进去不需要输入 → 它返回固定名字 SessionId → 生成接口文档或校验规则时会用这个名字标识该字段类型。

调用关系：它是 JsonSchema 实现的一部分，配合 SessionId::json_schema 使用，让外部文档既知道名字，也知道实际格式。

fn json_schema(generator: &mut SchemaGenerator) -> Schema

作用：告诉 JSON Schema 生成器：SessionId 在 JSON 里按字符串看待。这样前端或其他服务不用知道 Rust 里的包装结构。

数据流：进去一个 schema 生成器 → 它直接复用 String 的 schema → 出来一份“这是字符串”的 JSON Schema 描述。

调用关系：它和 schema_name 一起服务于接口描述生成。虽然程序内部是 SessionId 类型，协议文档里会表现成普通字符串，方便跨语言使用。

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

fn test_session_id_default_is_not_zeroes()

作用：这个测试确认默认创建出来的 SessionId 不是全零 UUID。全零编号通常像“空值”或“占位符”，不能拿来当真实会话编号。

数据流：进去不需要输入 → 它调用 SessionId::default 生成一个编号 → 检查这个编号不等于 nil UUID（全零 UUID）。

调用关系：它保护 SessionId::default 的行为，防止以后有人把默认值改成无效的空编号。

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

fn converts_to_and_from_thread_id()

作用：这个测试确认 ThreadId 和 SessionId 互相转换时不会改变底层编号。也就是换了名字，但身份证号没变。

数据流：进去不需要输入 → 它新建一个 ThreadId，转成 SessionId，再转回 ThreadId → 最后检查转回来的值和原来完全一样。

调用关系：它覆盖 SessionId::from 和 ThreadId::from 这对转换函数，保证会话和线程之间共享 UUID 的设计不会被破坏。

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

fn root() -> Self

作用：生成系统默认的根 agent 路径，也就是 /root。很多流程需要从根 agent 开始找人、发消息或列出子 agent，所以这是最常用的起点。

数据流：进去不需要任何输入 → 它把固定字符串 /root 包成一个 AgentPath → 出来的是一个已经确定合法的根路径对象，不会改动外部状态。

调用关系：它被很多业务流程当作起点使用，比如列出 agent、恢复 agent、处理父子 agent 通信等。resolve 在遇到引用正好是 /root 时，也会把活交给它来返回标准根路径。

调用图：被 38 处调用（list_agents, encrypted_inter_agent_communication_clears_existing_last_task_message, ensure_v2_agent_loaded_reloads_registered_unloaded_agent, list_agent_subtree_thread_ids_includes_anonymous_and_closed_descendants, multi_agent_v2_completion_ignores_dead_direct_parent, multi_agent_v2_completion_queues_message_for_direct_parent, resume_agent_from_rollout_does_not_reopen_v2_descendants, send_inter_agent_communication_without_turn_queues_message_without_triggering_turn, spawn_agent_can_fork_parent_thread_history_with_sanitized_items, spawn_agent_fork_last_n_turns_keeps_only_recent_turns (+15 more)）。

fn morpheus() -> Self

作用：生成特殊的 /morpheus 路径。这个路径不是普通 /root/... 树上的节点，而是系统允许的一个特别地址。

数据流：进去不需要任何输入 → 它把固定字符串 /morpheus 包成 AgentPath → 出来的是一个特殊但合法的路径对象。

调用关系：目前调用事实里主要由测试 morpheus_has_expected_name 使用，用来确认这个特殊路径能被正确创建和识别。

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

fn from_string(path: String) -> Result<Self, String>

作用：把外部传进来的一段字符串变成 AgentPath。它的重要点是不会盲目信任字符串，而是先检查这是不是合法路径。

数据流：进去是一段 String 路径文本 → 它调用 validate_absolute_path 检查必须是 /root... 或 /morpheus 这种绝对路径 → 如果合法就包成 AgentPath 返回，如果不合法就返回错误文字。

调用关系：这是创建 AgentPath 的核心入口之一。恢复子 agent、按路径筛选 agent 等流程会直接用它；其他转换函数也会绕到这里，确保所有字符串路径都经过同一套检查。

调用图：调用 1 个内部函数（validate_absolute_path）；被 2 处调用（resume_thread_subagent_restores_stored_nickname_and_role, multi_agent_v2_list_agents_filters_by_relative_path_prefix）。

fn as_str(&self) -> &str

作用：把 AgentPath 里面保存的路径当作普通字符串借出来看。它适合用于比较、打印、传给只需要字符串的函数。

数据流：进去是一个 AgentPath 自身 → 它不复制内容，只把内部那段路径字符串的只读引用拿出来 → 出来是 &str，外部不能通过它修改路径。

调用关系：它是很多便捷方法的底层小零件。is_root、name、as_ref、deref、fmt 都会调用它，其他流程如根据路径生成 agent id、释放保留路径、转发子 agent 完成消息时也会读这个字符串。

调用图：被 8 处调用（agent_id_for_path, release_reserved_agent_path, forward_child_completion_to_parent, as_ref, deref, fmt, is_root, name）。

fn is_root(&self) -> bool

作用：判断这个路径是不是根路径 /root。这能帮助代码区分“根节点”和普通子 agent。

数据流：进去是一个 AgentPath → 它通过 as_str 取出路径文字，再和固定的 /root 比较 → 出来是 true 或 false，不改变任何东西。

调用关系：它被 name 用来给根路径返回特殊名字 root，也被匹配路径前缀的逻辑使用，用于判断当前 agent 是否处在根位置。

调用图：调用 1 个内部函数（as_str）；被 2 处调用（agent_matches_prefix, name）。

fn name(&self) -> &str

作用：取出路径最后一段，也就是这个 agent 的名字。比如 /root/researcher/worker 的名字就是 worker。

数据流：进去是一个 AgentPath → 它先用 is_root 判断是不是根路径；如果是就返回 root；否则用 as_str 取字符串并按 / 从后往前找最后一段 → 出来是一段名字文本。

调用关系：它依赖 is_root 和 as_str 来保证根路径和普通路径都能得到合理名字。上层代码需要显示 agent 名称、比较名称或做界面展示时会用这种结果。

调用图：调用 2 个内部函数（as_str, is_root）。

fn join(&self, agent_name: &str) -> Result<Self, String>

作用：在当前路径下面拼出一个子 agent 路径。比如从 /root 加上 researcher，得到 /root/researcher。

数据流：进去是当前 AgentPath 和一个子 agent 名字 → 它先用 validate_agent_name 检查名字不能乱写，再用格式化字符串拼成 当前路径/名字，最后通过 from_string 再做一次完整路径检查 → 出来是新的 AgentPath，或者一条错误原因。

调用关系：它是创建子 agent 路径的安全拼接器。它把“检查单个名字”的活交给 validate_agent_name，再把“检查完整路径”的活交给 from_string，避免手写字符串拼接绕过规则。

调用图：调用 1 个内部函数（validate_agent_name）；外部调用 2 个（from_string, format!）。

fn resolve(&self, reference: &str) -> Result<Self, String>

作用：把一个路径引用解析成真正的绝对 AgentPath。引用可以是绝对路径，比如 /root/other，也可以是相对路径，比如 worker。

数据流：进去是当前路径和一段引用文字 → 如果引用为空就报错；如果正好是 /root 就返回根路径；如果以 / 开头就按绝对路径转换；否则先检查相对路径每一段名字，再拼到当前路径后面 → 出来是解析后的 AgentPath 或错误文字。

调用关系：它用于“从当前 agent 看另一个 agent 在哪里”的场景。它会根据情况调用 root、try_from、validate_relative_reference 和 from_string，把不同写法统一成一个经过校验的绝对路径。

调用图：调用 1 个内部函数（validate_relative_reference）；外部调用 4 个（from_string, root, try_from, format!）。

fn try_from(value: &str) -> Result<Self, Self::Error>

作用：提供 Rust 标准的“尝试转换”入口，把字符串形式的路径转成 AgentPath。名字叫“try”是因为转换可能失败，会返回错误原因。

数据流：进去是一段路径文本 → 它把文本交给 from_string 做完整校验和包装 → 出来是合法 AgentPath，或者说明哪里不合法的错误字符串。

调用关系：很多测试和业务流程会用它从字面量或外部数据创建路径，比如处理中断的子 agent、加密通信、恢复 agent、邮箱投递等。它本身不重复规则，而是统一转交给 from_string。

调用图：被 29 处调用（interrupted_subagent_activity_removes_missing_thread_watch, encrypted_inter_agent_communication_clears_existing_last_task_message, ensure_v2_agent_loaded_reloads_registered_unloaded_agent, send_inter_agent_communication_without_turn_queues_message_without_triggering_turn, spawn_agent_can_fork_parent_thread_history_with_sanitized_items, spawn_agent_fork_last_n_turns_keeps_only_recent_turns, agent_path, input_queue_drains_mailbox_in_delivery_order, input_queue_notifies_mailbox_subscribers, input_queue_tracks_pending_trigger_turn_mail (+15 more)）；外部调用 1 个（from_string）。

fn from(value: AgentPath) -> Self

作用：把 AgentPath 转回普通 String。这样在需要保存、序列化或传给只认字符串的地方，可以取出里面的路径文本。

数据流：进去是一个 AgentPath 值本身 → 它拿走内部保存的 String → 出来是普通字符串；因为是拿走值，所以原来的 AgentPath 会被消费掉。

调用关系：这是配合序列化和类型转换使用的小接口。文件顶部声明 AgentPath 在 serde 中可以转成 String，这个函数就是这种转换的一部分。

fn from_str(s: &str) -> Result<Self, Self::Err>

作用：支持从字符串切片解析 AgentPath，比如调用标准的 "/root/a".parse()。这让 AgentPath 用起来像 Rust 里常见的可解析类型。

数据流：进去是一段 &str 文本 → 它调用 try_from 走统一校验流程 → 出来是合法 AgentPath 或错误文字。

调用关系：它是标准 FromStr 接口的实现。它不自己检查规则，而是把转换工作交给 try_from，保证所有入口的规则一致。

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

fn as_ref(&self) -> &str

作用：让 AgentPath 可以在需要 AsRef<str> 的地方当字符串引用使用。简单说，就是让它更容易传给通用字符串函数。

数据流：进去是 AgentPath 的引用 → 它调用 as_str 取出内部路径的只读字符串引用 → 出来是 &str。

调用关系：它是 Rust 通用接口 AsRef<str> 的实现。具体取字符串的活交给 as_str，自己只负责把 AgentPath 接到标准接口上。

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

fn deref(&self) -> &Self::Target

作用：让 AgentPath 在很多场合能像字符串一样被读取。Deref 可以理解成“自动拆开外壳看里面”。

数据流：进去是 AgentPath 的引用 → 它调用 as_str 拿内部路径 → 出来是字符串切片引用，不复制也不修改。

调用关系：它是 Rust 解引用接口的实现，方便其他代码把 AgentPath 传到一些期望字符串的地方。底层仍然依赖 as_str，保持取值方式统一。

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

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

作用：定义 AgentPath 被打印或格式化时显示什么。结果就是直接显示路径本身，比如 /root/researcher。

数据流：进去是 AgentPath 和一个格式化输出器 → 它用 as_str 取出路径，再用输出器的 write_str 写进去 → 出来是格式化成功或失败的结果。

调用关系：这是 Display 接口的实现。日志、错误信息、字符串拼接里的 {self} 这类显示方式会走到它；它把真正的文本来源交给 as_str。

调用图：调用 1 个内部函数（as_str）；外部调用 1 个（write_str）。

fn validate_agent_name(agent_name: &str) -> Result<(), String>

作用：检查单个 agent 名字是否合法。它像门卫一样，挡住空名字、保留字、带斜杠的名字、大写字母等不安全或不统一的写法。

数据流：进去是一段 agent 名字 → 它逐条检查：不能为空，不能是 root、.、..，不能包含 /，只能有小写字母、数字、下划线 → 如果全部通过就返回成功，否则返回具体错误文字。

调用关系：它被 join、validate_absolute_path 和 validate_relative_reference 调用，是路径规则中最基础的一层。完整路径和相对路径最终都要拆成一段段名字交给它检查。

调用图：被 3 处调用（join, validate_absolute_path, validate_relative_reference）；外部调用 1 个（format!）。

fn validate_absolute_path(path: &str) -> Result<(), String>

作用：检查一整条绝对 agent 路径是否合法。绝对路径就是从根开始写清楚的完整地址。

数据流：进去是一段路径字符串 → 它先允许特殊值 /morpheus；否则要求必须以 / 开头，第一段必须是 root，不能以 / 结尾，然后把后面的每一段交给 validate_agent_name 检查 → 出来是成功或错误原因。

调用关系：它是 from_string 的核心检查器。任何从普通字符串创建 AgentPath 的入口，最后都会通过它确认这是一条可信的完整路径。

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

fn validate_relative_reference(reference: &str) -> Result<(), String>

作用：检查相对路径引用是否合法。相对路径不是从 /root 开始，而是相对于当前 agent 往下找，比如 worker/helper。

数据流：进去是一段相对引用文本 → 它先拒绝以 / 结尾的写法，再按 / 拆成多段，并把每一段交给 validate_agent_name 检查 → 出来是成功或错误原因。

调用关系：它被 resolve 调用。resolve 发现引用不是绝对路径时，会先用它确认相对写法安全，再拼到当前路径后面。

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

fn root_has_expected_name()

作用：测试根路径的基本行为是不是正确。它确认 /root 创建出来后，字符串、名字和根判断都符合预期。

数据流：进去没有外部输入 → 它调用 AgentPath::root 创建根路径，然后用断言检查路径文本是 /root、名字是 root、is_root 为真 → 如果都对测试通过，否则测试失败。

调用关系：这是对 root、as_str、name、is_root 这一组基础行为的保护。以后有人改路径规则时，如果破坏根路径语义，这个测试会及时报错。

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

fn morpheus_has_expected_name()

作用：测试特殊路径 /morpheus 的行为。它确认这个特殊地址能正常创建，名字是 morpheus，但不会被误认为根路径。

数据流：进去没有外部输入 → 它调用 AgentPath::morpheus，再断言字符串、名字和根判断结果 → 全部符合就通过，否则失败。

调用关系：它保护 morpheus 这个例外规则。因为 /morpheus 不走普通 /root/... 树，单独测试可以避免以后被误改成普通根路径逻辑。

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

fn join_builds_child_paths()

作用：测试从父路径拼子路径是否正确。它用最常见的场景确认 /root 加 researcher 会得到 /root/researcher。

数据流：进去没有外部输入 → 它先创建根路径，再调用 join("researcher")，最后断言生成的路径文本和名字都正确 → 符合预期则测试通过。

调用关系：它主要保护 join、名字校验和 name 的配合。子 agent 创建依赖这种拼接，测试能防止拼错斜杠或名字取错。

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

fn resolve_supports_relative_and_absolute_references()

作用：测试 resolve 同时支持相对引用和绝对引用。这样可以确保调用方既能写 worker，也能直接写 /root/other。

数据流：进去没有外部输入 → 它先用 try_from 创建当前路径 /root/researcher，再分别解析 worker 和 /root/other，并和期望的 AgentPath 比较 → 两种情况都正确则通过。

调用关系：它保护 resolve 的分支逻辑，也间接使用 try_from 创建对照路径。这个测试保证路径引用在父子 agent 通信或查找时不会被解析错。

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

fn invalid_names_and_paths_are_rejected()

作用：测试非法名字和非法路径会被拒绝，并且错误信息符合预期。它确保校验规则真的在挡住危险或混乱的输入。

数据流：进去没有外部输入 → 它分别尝试大写名字、错误根路径、包含 .. 的相对路径 → 每次都断言返回的是预期错误文字 → 如果非法输入被放行或错误不对，测试失败。

调用关系：它保护 validate_agent_name、validate_absolute_path、validate_relative_reference 这些校验门槛。只要有人放宽规则或改错错误信息，这个测试就会提醒。

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

fn new(namespace: Option<String>, name: impl Into<String>) -> Self

作用：用一个可有可无的命名空间和一个名字，创建一个 ToolName。适合调用者已经自己判断好了“有没有命名空间”的场景。

数据流：进去的是 namespace，也就是可能存在的分组名，以及 name，也就是工具本身的名字；函数把 name 转成真正存储用的字符串，再连同 namespace 放进 ToolName；出来的是一个完整的工具名对象，原数据不会被额外修改。

调用关系：它会被 from_parts 和 build_tool_call 这类流程使用：前者像是把拆开的文本重新组装，后者像是在生成一次工具调用时给工具贴上准确名字。它自己只做装配，不再把活儿交给别的项目内函数，只用到标准的字符串转换能力。

调用图：被 2 处调用（from_parts, build_tool_call）；外部调用 1 个（into）。

fn plain(name: impl Into<String>) -> Self

作用：创建一个没有命名空间的普通工具名。有人只关心工具叫“什么”，不关心它属于哪个分组时，就会用它。

数据流：进去的是一个名字；函数把它变成字符串，并把 namespace 固定设成 None，也就是“没有命名空间”；出来的是一个只带普通名字的 ToolName。

调用关系：它是最常用的快捷入口，很多工具定义、权限检查、测试和描述生成都会用它来表示内置或简单工具。它不需要判断分组，只负责把一个普通名字包装成统一格式。

调用图：被 73 处调用（augment_tool_definition_appends_typed_declaration, augment_tool_definition_includes_property_descriptions_as_comments, code_mode_only_description_includes_nested_tools, blocking_tool, danger_full_access_tool_attempts_do_not_enforce_managed_network, guardian_allows_shell_command_additional_permissions_requests_past_policy_validation, guardian_allows_unified_exec_additional_permissions_requests_past_policy_validation, shell_command_allows_sticky_turn_permissions_without_inline_request_permissions_feature, strict_auto_review_turn_grant_forces_guardian_for_shell_command_policy_skip, rejects_escalated_permissions_when_policy_not_on_request (+15 more)）；外部调用 1 个（into）。

fn namespaced(namespace: impl Into<String>, name: impl Into<String>) -> Self

作用：创建一个带命名空间的工具名。适合表示“某个来源下面的某个工具”，比如外部服务提供的一组工具。

数据流：进去的是 namespace 和 name；函数把两者都转成字符串，把 namespace 放进 Some 里表示“确实有分组”；出来的是一个保留了分组和名字两部分的 ToolName。

调用关系：它会被工具名规范化、MCP 工具处理、工具描述生成等流程调用。简单说，凡是系统需要清楚区分“这个工具来自哪个命名空间”时，就会走到这里。

调用图：被 32 处调用（code_mode_only_description_groups_namespace_instructions_once, code_mode_only_description_omits_empty_namespace_sections, code_mode_only_description_renders_shared_mcp_types_once, canonical_tool_name, tool_name, image_generation_publication_is_finalized_by_core, mcp_post_tool_use_payload_uses_prefixed_tool_name_args_and_result, mcp_updated_input_rewrites_builtin_like_tool_names_as_mcp, tool_name, tool_name (+15 more)）；外部调用 1 个（into）。

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

作用：把 ToolName 变成人能看见的一段文字。这样日志、提示词、错误信息里就能直接显示工具名。

数据流：进去的是一个 ToolName 和一个输出位置；如果有命名空间，它就把命名空间和名字连在一起写出去；如果没有命名空间，就只写名字；出来的是格式化是否成功的结果。

调用关系：它属于 Rust 的 Display 显示接口，别人只要把 ToolName 当成文字打印，就会自动用到它。它不参与创建工具名，只负责最后展示。

调用图：外部调用 2 个（write_str, write!）。

fn cmp(&self, other: &Self) -> Ordering

作用：比较两个 ToolName 谁应该排在前面。这样工具名放进排序列表、树形集合或需要稳定顺序的地方时，不会乱跳。

数据流：进去的是两个 ToolName；函数先把每个工具名整理成可比较的形式：带命名空间的用“命名空间、名字”比较，普通工具名用“名字、无额外名字”比较；出来的是小于、等于或大于这样的排序结果。

调用关系：它是 ToolName 的正式排序规则，partial_cmp 会直接借用它。任何需要对 ToolName 排序的标准库功能，最终都会依赖这个规则。

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

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

作用：提供“可比较大小”的接口，让 ToolName 能用在更多需要排序的通用代码里。它其实是把工作交给完整排序函数 cmp。

数据流：进去的是两个 ToolName；函数调用 cmp 得到确定的排序结果，再把结果包成 Option，表示“比较一定有结果”；出来的是这个包装后的排序结果，不改动任何数据。

调用关系：它站在通用排序接口和真正排序逻辑之间。外部排序工具可能先找 partial_cmp，而它会立刻转给 cmp，保证所有地方用同一套排序规则。

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

fn from(name: &str) -> Self

作用：让普通字符串可以方便地变成 ToolName。这样调用者不用每次都手写 ToolName::plain，代码更顺手。

数据流：进去的是一个字符串形式的名字；函数把它当作没有命名空间的普通工具名，交给 plain 来包装；出来的是 namespace 为空、name 为输入内容的 ToolName。

调用关系：它是 Rust 的 From 转换接口的一部分，常在代码需要“自动把字符串变成工具名”时触发。它把实际创建工作交给 plain，所以普通字符串转换和手动创建普通工具名保持完全一致。

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

fn new(text: String) -> Self

作用：创建一份最普通的文本输出记录。调用者给它一段文字，它会默认认为这段输出没有被截断。

数据流：进去的是一个字符串 → 它把这个字符串放进 StreamOutput 的 text 字段，并把 truncated_after_lines 设成空，表示没有截断信息 → 出来的是一个可继续传递的输出对象。

调用关系：很多执行命令的流程都会用它来包装输出，比如生成执行结果、发出执行结束事件、检查沙箱拒绝信息时。它是把散落的字符串变成统一输出格式的入口小零件。

调用图：被 15 处调用（make_exec_output, includes_timed_out_message, execute_user_shell_command, run, map_exec_result, emit_exec_end_for_unified_exec, emit_failed_exec_end_for_unified_exec, check_for_sandbox_denial_with_text, formats_basic_record, uses_aggregated_output_over_streams (+5 more)）。

fn from_utf8_lossy(&self) -> StreamOutput<String>

作用：把一份“字节形式”的输出变成“字符串形式”的输出。名字里有 lossy，意思是必要时会用尽力而为的方式避免程序崩掉，但这里会先智能判断编码，尽量少丢信息。

数据流：进去的是 StreamOutput<Vec<u8>>，也就是字节输出和截断记录 → 它把字节交给 bytes_to_string_smart 转成文字，同时原样保留截断记录 → 出来的是 StreamOutput<String>。

调用关系：它站在原始进程输出和最终展示文字之间。真正复杂的识别编码工作交给 bytes_to_string_smart，自己负责保持 StreamOutput 这个外壳不变。

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

fn default() -> Self

作用：提供一个“空的命令执行结果”。当代码需要先占个位，或者遇到没有真实输出的情况时，可以拿它当安全默认值。

数据流：进去没有参数 → 它创建退出码为 0、三份空输出、耗时为 0、未超时的结果 → 出来的是一份完整但内容为空的 ExecToolCallOutput。

调用关系：它会调用 StreamOutput::new 来生成空的标准输出、错误输出和合并输出。它服务于需要默认执行结果的地方，让别的代码不用手工拼每个字段。

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

fn bytes_to_string_smart(bytes: &[u8]) -> String

作用：把任意一串字节尽量正确地变成可读字符串。它解决的核心问题是：外部命令输出可能不是 UTF-8，不能简单粗暴地直接读。

数据流：进去的是字节切片 → 如果为空就返回空字符串；如果本来就是 UTF-8，就直接转成字符串；否则先调用 detect_encoding 猜编码，再调用 decode_bytes 解码 → 出来是一段尽量不乱码的文字。

调用关系：收集子进程输出的 spawn_process_output、collect_spawn_process_output 会用它，StreamOutput::from_utf8_lossy 也会用它。它是整个文件里“字节变文字”的主通道。

调用图：调用 2 个内部函数（decode_bytes, detect_encoding）；被 3 处调用（spawn_process_output, collect_spawn_process_output, from_utf8_lossy）；外部调用 2 个（new, from_utf8）。

fn detect_encoding(bytes: &[u8]) -> &'static Encoding

作用：猜一串字节最可能用了哪种文字编码。它还修正一个常见误判：把 Windows 的弯引号错当成 IBM866 俄文编码。

数据流：进去的是原始字节 → 它用 chardetng 这个编码探测器猜测编码；如果猜成 IBM866，又发现字节更像 Windows-1252 的弯引号、破折号之类标点，就改判为 Windows-1252 → 出来的是一个编码规则。

调用关系：它只被 bytes_to_string_smart 调用，是智能解码的判断步骤。遇到 IBM866 的可疑情况时，它会把细查工作交给 looks_like_windows_1252_punctuation。

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

fn decode_bytes(bytes: &[u8], encoding: &'static Encoding) -> String

作用：按照指定编码把字节翻译成字符串。如果指定编码翻译时出错，它会退回到宽容的 UTF-8 读法，保证至少能给出结果。

数据流：进去的是字节和一个编码规则 → 它用这个编码规则解码；如果报告有错误，就改用 String::from_utf8_lossy 这种“坏字节用替代字符兜底”的方式 → 出来是一段字符串。

调用关系：它被 bytes_to_string_smart 在选好编码后调用。前面的 detect_encoding 负责“选字典”，它负责“查字典翻译”。

调用图：被 1 处调用（bytes_to_string_smart）；外部调用 2 个（decode, from_utf8_lossy）。

fn looks_like_windows_1252_punctuation(bytes: &[u8]) -> bool

作用：判断一串字节是不是很像 Windows-1252 的智能标点夹在普通英文里。这个检查用来避免把弯引号、长破折号误显示成奇怪的俄文字母。

数据流：进去的是字节 → 它逐个查看：如果出现太高的字节就否定；如果出现 0x80 到 0x9F 之间的字节，必须是允许的 Windows-1252 标点；同时还要看到 ASCII 英文字母 → 最后返回真或假。

调用关系：它被 detect_encoding 在探测器猜到 IBM866 时调用。它再用 is_windows_1252_punct 检查单个字节是不是允许的标点白名单成员。

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

fn is_windows_1252_punct(byte: u8) -> bool

作用：检查某个字节是不是 Windows-1252 里常见的智能标点，比如弯引号、项目符号、长短破折号、商标符号。

数据流：进去的是一个字节 → 它在预先列好的 WINDOWS_1252_PUNCT_BYTES 清单里查找 → 出来的是布尔值，表示这个字节是不是认可的标点。

调用关系：它只服务于 looks_like_windows_1252_punctuation。这个小函数像门卫，只回答“这个可疑字节是不是我们允许的那几种标点”。

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

fn is_protected_metadata_name(name: &OsStr) -> bool

作用：判断一个文件名是不是受保护的项目元数据名，比如 .git、.codex、.agents。调用方用它来快速识别“这里不能随便写”。

数据流：输入一个操作系统文件名 → 和内置的受保护名字列表逐个比较 → 输出 true 或 false，不改任何数据。

调用关系：这是保护元数据规则的入口小工具，后面的元数据路径判断会用同一套名字表来决定哪些目录要额外小心。

fn is_protected_metadata_directory_name(name: &OsStr) -> bool

作用：判断一个目录名是不是受保护的元数据目录名，当前重点是 .agents 和 .codex。它比完整列表更窄，只看特定目录。

数据流：输入一个目录名 → 分别和 .agents、.codex 对比 → 返回是否命中，不改外部状态。

调用关系：它是给外部检查用的轻量判断，和更通用的 is_protected_metadata_name 一起服务于元数据保护规则。

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

fn forbidden_agent_metadata_write(
    path: &Path,
    cwd: &Path,
    file_system_sandbox_policy: &FileSystemSandboxPolicy,
) -> Option<&'static str>

作用：判断代理是不是正在尝试写受保护的元数据路径，并在禁止时告诉调用方命中了哪个元数据名。它用于给用户或上层逻辑一个明确原因，而不只是说“不能写”。

数据流：输入目标路径、当前工作目录、文件系统沙箱规则 → 只在受限沙箱下继续检查；先把相对路径变成绝对路径，再看它是否落在可写根目录里的受保护元数据区；如果没有明确写入放行且普通写权限也不允许，就返回元数据名，否则返回 None。

调用关系：它把路径解析、可写根目录检查、显式放行检查和普通写权限判断串起来；内部会调用 resolve_candidate_path、metadata_child_of_writable_root、has_explicit_write_entry_for_metadata_path 和 can_write_path_with_cwd。

调用图：调用 4 个内部函数（can_write_path_with_cwd, has_explicit_write_entry_for_metadata_path, metadata_child_of_writable_root, resolve_candidate_path）；外部调用 1 个（matches!）。

fn is_enabled(self) -> bool

作用：回答网络沙箱策略是否允许联网。很多地方只需要一个简单的是/否结果。

数据流：输入一个网络策略值 → 判断它是不是 Enabled → 输出布尔值，不改任何数据。

调用关系：创建沙箱、兼容旧策略、决定是否安装网络限制时都会问它；它是网络权限判断里最基础的小开关。

调用图：被 10 处调用（spawn_debug_sandbox_child, should_install_network_seccomp, bwrap_network_mode, network_access_from_policy, from, to_legacy_sandbox_policy, compatibility_workspace_write_policy, should_require_platform_sandbox, dynamic_network_policy_for_network, should_apply_network_block）；外部调用 1 个（matches!）。

fn can_read(self) -> bool

作用：判断某种文件权限是否允许读取。只要不是明确拒绝，就算可读。

数据流：输入一个访问模式 → 如果不是 Deny 就返回 true，否则 false。

调用关系：更高层的 access_covers 和各种路径权限判断会用它，把“读不读得了”统一成一个简单规则。

调用图：被 1 处调用（access_covers）；外部调用 1 个（matches!）。

fn can_write(self) -> bool

作用：判断某种文件权限是否允许写入。只有 Write 才算真正可写。

数据流：输入一个访问模式 → 检查是否等于 Write → 返回 true 或 false。

调用关系：写权限收窄、可写根目录计算、元数据保护检查都会依赖它。

调用图：被 1 处调用（access_covers）；外部调用 1 个（matches!）。

fn project_roots(subpath: Option<PathBuf>) -> Self

作用：创建一个代表“项目根目录”的特殊路径，可以附带子路径。它让规则不用立刻知道真实路径，也能表达“当前项目下面某处”。

数据流：输入可选子路径 → 包装成 ProjectRoots 这个特殊路径值 → 返回这个值。

调用关系：workspace_write 和旧策略投影会用它表达项目根可写，后续再由 materialize 或 resolve 系列函数换成真实绝对路径。

fn unknown(path: impl Into<String>, subpath: Option<PathBuf>) -> Self

作用：创建一个系统暂时不认识的特殊路径标记。这样配置里出现新类型时，不至于直接丢掉信息。

数据流：输入路径名字和可选子路径 → 转成字符串并保存 → 返回 Unknown 特殊路径。

调用关系：它主要是数据兼容用，后续匹配和解析函数会把 Unknown 当成不能直接解析的特殊项。

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

fn from(value: FileSystemSandboxEntry<AbsolutePathBuf>) -> Self

作用：把使用绝对路径的沙箱规则项转换成使用路径 URI 的规则项。URI 可以理解成更适合传输或序列化的路径写法。

数据流：输入一条绝对路径规则 → 转换其中的 path 字段，保留 access 权限不变 → 输出新规则项。

调用关系：这是模型转换层的小桥，帮助权限规则在内部绝对路径和外部传输格式之间来回走。

fn try_from(value: FileSystemSandboxEntry<PathUri>) -> Result<Self, Self::Error>

作用：把使用路径 URI 的沙箱规则项尽量转回绝对路径规则项。如果 URI 不是合法绝对路径，就返回错误。

数据流：输入一条 URI 路径规则 → 尝试把 path 转成绝对路径，保留 access → 成功返回规则项，失败返回转换错误。

调用关系：它和 FileSystemSandboxEntry::from 成对出现，用在配置或协议数据进入内部权限判断之前。

fn new(file_system_sandbox_policy: &FileSystemSandboxPolicy, cwd: &Path) -> Option<Self>

作用：为“禁止读取”的规则创建匹配器。匹配器就像筛子，之后拿一个路径过来就能判断是否被禁止读。

数据流：输入沙箱规则和当前工作目录 → 用 fail-closed 策略构建匹配器；fail-closed 的意思是规则坏了也按更安全的方式处理 → 返回可能存在的匹配器。

调用关系：is_read_denied 需要先有这个匹配器；它把实际构建工作交给 ReadDenyMatcher::build。

调用图：被 1 处调用（is_read_denied）；外部调用 2 个（build, unreachable!）。

fn try_new(
        file_system_sandbox_policy: &FileSystemSandboxPolicy,
        cwd: &Path,
    ) -> Result<Option<Self>, String>

作用：尝试创建禁止读取匹配器，但遇到错误会把错误返回给调用方。它适合需要把配置错误明确报告出来的场景。

数据流：输入沙箱规则和当前工作目录 → 用 ReturnError 策略构建 → 成功返回匹配器或 None，失败返回错误文字。

调用关系：resolve_windows_deny_read_paths 会用它；实际构建仍交给 ReadDenyMatcher::build。

调用图：被 1 处调用（resolve_windows_deny_read_paths）；外部调用 1 个（build）。

fn build(
        file_system_sandbox_policy: &FileSystemSandboxPolicy,
        cwd: &Path,
        invalid_glob_behavior: InvalidDenyReadGlobBehavior,
    ) -> Result<Option<Self>, String>

作用：真正组装禁止读取匹配器。它把精确路径和通配符规则分别整理好，方便后续快速判断。

数据流：输入沙箱规则、当前工作目录和坏通配符的处理方式 → 如果没有拒读规则就返回 None；否则收集不可读根目录的不同路径写法，再编译不可读通配符 → 输出匹配器，或在要求报错时输出错误。

调用关系：ReadDenyMatcher::new 和 try_new 都靠它；它会读取策略里的 get_unreadable_roots_with_cwd、get_unreadable_globs_with_cwd，并调用 build_glob_matcher。

调用图：调用 4 个内部函数（get_unreadable_globs_with_cwd, get_unreadable_roots_with_cwd, has_denied_read_restrictions, build_glob_matcher）；外部调用 2 个（new, format!）。

fn is_read_denied(&self, path: &Path) -> bool

作用：判断某个路径是否被禁止读取。它同时考虑精确目录规则和通配符规则。

数据流：输入一个路径 → 如果之前有坏通配符且采用保守处理，直接禁止；否则生成普通写法和真实路径写法，再看是否落在禁止根目录下或匹配禁止通配符 → 返回 true 或 false。

调用关系：collect_existing_glob_matches 会用它检查实际文件；它依赖 normalized_and_canonical_candidates 来处理符号链接和规范路径。

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

fn from(value: FileSystemPath<AbsolutePathBuf>) -> Self

作用：把内部绝对路径形式的 FileSystemPath 转成 URI 形式，方便传输或保存。

数据流：输入一个 FileSystemPath<AbsolutePathBuf> → 如果是普通路径就转成 PathUri；如果是通配符或特殊路径就原样保留 → 输出 FileSystemPath<PathUri>。

调用关系：它是路径模型转换的一部分，和 try_from 反向配合。

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

fn try_from(value: FileSystemPath<PathUri>) -> Result<Self, Self::Error>

作用：把 URI 形式的 FileSystemPath 转回内部绝对路径形式。普通路径可能失败，所以它返回 Result。

数据流：输入 FileSystemPath<PathUri> → 普通路径尝试转绝对路径，通配符和特殊路径原样保留 → 成功输出内部路径，失败输出错误。

调用关系：配置或协议传来的权限路径进入内部判断前，会通过这类转换变成可计算的绝对路径。

fn project_roots_glob_pattern(subpath: &Path) -> String

作用：生成一个表示“项目根目录下某个子路径”的通配符模式字符串。它让通配符规则也能先写成相对项目根的形式。

数据流：输入子路径 → 拼上项目根通配符前缀 → 输出字符串模式。

调用关系：compile_scoped_filesystem_pattern 会用它；后续 parse_project_roots_glob_pattern 和 resolve_project_roots_glob_pattern 会把它解析和落地。

调用图：被 1 处调用（compile_scoped_filesystem_pattern）；外部调用 1 个（format!）。

fn read_only_file_system_entries() -> Vec<FileSystemSandboxEntry>

作用：生成最基础的只读文件系统规则：整个文件系统根目录可读，但不可写。

数据流：无输入 → 创建一条 Root=Read 的规则 → 返回规则列表。

调用关系：FileSystemSandboxPolicy::read_only 调用它来构建默认只读策略。

调用图：被 1 处调用（read_only）；外部调用 1 个（vec!）。

fn default() -> Self

作用：给文件系统沙箱提供默认策略。默认是只读，比较安全。

数据流：无输入 → 调用 read_only → 返回只读策略。

调用关系：测试和默认配置会依赖它；它把默认选择委托给 FileSystemSandboxPolicy::read_only。

调用图：被 8 处调用（file_system_sandbox_context_uses_active_attempt, default_exec_approval_requirement_keeps_prompt_when_granular_allows_sandbox_approval, default_exec_approval_requirement_rejects_sandbox_prompt_when_granular_disables_it, extension_tool_receives_turn_environment_sandbox, view_image_tool_applies_local_sandbox_read_denies, default_policy_with_unreadable_glob, default_policy_with_unreadable_glob, unreadable_glob_policy_includes_canonicalized_static_prefix）；外部调用 1 个（read_only）。

fn read_only() -> Self

作用：创建一个受限的只读沙箱策略。工具可以看文件，但不能改文件。

数据流：无输入 → 生成只读规则列表 → 包装成 Restricted 策略返回。

调用关系：default 会调用它；它用 read_only_file_system_entries 准备规则，再交给 restricted。

调用图：调用 1 个内部函数（read_only_file_system_entries）；被 2 处调用（extensible_builtin_parent_profile, read_only）；外部调用 1 个（restricted）。

fn unrestricted() -> Self

作用：创建一个文件系统完全不受限的策略。它表示对磁盘读写没有沙箱限制。

数据流：无输入 → 设置 kind 为 Unrestricted，清空规则 → 返回策略。

调用关系：从旧的 DangerFullAccess 策略转换、全盘访问场景都会用它。

调用图：被 15 处调用（managed_full_disk_with_restricted_network_reports_external_sandbox, windows_restricted_token_rejects_network_only_restrictions, exec_server_params_use_path_uri_and_env_policy_overlay_contract, full_disk_write_full_network_returns_unwrapped_command, full_disk_write_proxy_only_keeps_full_filesystem_but_unshares_network, managed_proxy_preflight_argv_is_wrapped_for_full_access_policy, to_sandbox_policy, file_system_sandbox_policy, disabled_permission_profile_ignores_runtime_network_policy, permission_profile_from_runtime_permissions_preserves_unrestricted_managed_network (+5 more)）；外部调用 1 个（new）。

fn external_sandbox() -> Self

作用：创建一个由外部系统负责限制文件访问的策略。当前代码不再自己列具体文件规则。

数据流：无输入 → 设置 kind 为 ExternalSandbox，规则为空 → 返回策略。

调用关系：旧策略 ExternalSandbox 转换和权限配置保留时会用它。

调用图：被 4 处调用（external_sandbox_auto_approves_in_on_request, file_system_sandbox_policy, permission_profile_from_runtime_permissions_preserves_external_sandbox, from）；外部调用 1 个（new）。

fn restricted(entries: Vec<FileSystemSandboxEntry>) -> Self

作用：用给定规则创建一个受限文件系统策略。它是大多数精细权限控制的外壳。

数据流：输入规则列表 → 设置 kind 为 Restricted，保存这些规则 → 返回策略。

调用关系：read_only、workspace_write、权限 profile 编译和很多测试都会用它作为受限策略构造器。

调用图：被 138 处调用（requested_permissions_trust_project_uses_permission_profile_intent, permission_profile_override_keeps_memories_root_out_of_legacy_projection, permission_profile_override_preserves_split_write_roots, compile_permission_profile, workspace_write_permission_profile_with_private_denials, managed_cwd_write_profile_has_filesystem_restrictions, managed_full_disk_write_profile_has_no_filesystem_restrictions, managed_unresolvable_write_profile_has_filesystem_restrictions, writable_windows_policy_without_sandbox_backend_still_requires_approval, windows_elevated_allows_split_restricted_read_policies (+15 more)）。

fn has_root_access(&self, predicate: impl Fn(FileSystemAccessMode) -> bool) -> bool

作用：检查受限策略里是否对文件系统根目录有某种访问能力，比如能读或能写。

数据流：输入一个权限判断函数 → 只在 Restricted 下检查规则里是否有 Root 且满足该判断 → 返回 true 或 false。

调用关系：has_full_disk_read_access 和 has_full_disk_write_access 用它判断是否拥有全盘级别访问。

调用图：被 2 处调用（has_full_disk_read_access, has_full_disk_write_access）；外部调用 1 个（matches!）。

fn has_denied_read_restrictions(&self) -> bool

作用：判断策略里有没有明确的“禁止读取”规则。即使有全盘读权限，只要有拒读条目，也不能算完全可读。

数据流：读取当前策略的 kind 和 entries → 如果是 Restricted 且存在 Deny 规则，返回 true → 否则 false。

调用关系：ReadDenyMatcher::build、全盘读判断和是否允许无沙箱执行等流程都会用它。

调用图：被 3 处调用（unsandboxed_execution_allowed, has_full_disk_read_access, build）；外部调用 1 个（matches!）。

fn from_legacy_sandbox_policy_preserving_deny_entries(
        sandbox_policy: &SandboxPolicy,
        cwd: &Path,
        existing: &Self,
    ) -> Self

作用：从旧沙箱策略重建新文件系统策略，同时保留已有的拒读规则。这样更新旧配置时，不会把更细的安全限制弄丢。

数据流：输入旧沙箱策略、当前目录、已有新策略 → 先按旧策略重建；如果结果不是受限策略就直接返回；否则复制扫描深度，并补上已有 Deny 条目 → 返回合并后的策略。

调用关系：配置 apply 和兼容旧策略时会用它；它调用 from_legacy_sandbox_policy_for_cwd 做基础转换。

调用图：被 2 处调用（apply, legacy_bridge_preserves_explicit_deny_entries）；外部调用 2 个（from_legacy_sandbox_policy_for_cwd, matches!）。

fn preserve_deny_read_restrictions_from(&mut self, existing: &Self)

作用：把另一个策略里的拒读限制保留到当前策略里。它防止权限变更时意外放开本来禁止读取的区域。

数据流：输入已有策略 → 如果当前是不受限但已有拒读规则，就先降成根目录可写的受限策略；再复制扫描深度和不存在的 Deny 条目 → 修改当前策略本身。

调用关系：它用于策略叠加或替换时的安全兜底；内部会在必要时调用 restricted。

调用图：外部调用 3 个（restricted, matches!, vec!）。

fn has_write_narrowing_entries(&self) -> bool

作用：判断写权限是否被更窄的规则收紧了。比如根目录可写，但某个子目录只读，这就不是“真正全盘可写”。

数据流：读取受限策略里的每条规则 → 跳过可写规则；对路径、通配符和特殊路径判断是否形成写入限制 → 返回是否存在这种收窄。

调用关系：has_full_disk_write_access 用它排除“看似全盘写、实际有例外”的策略。

调用图：被 1 处调用（has_full_disk_write_access）；外部调用 1 个（matches!）。

fn has_same_target_write_override(&self, entry: &FileSystemSandboxEntry) -> bool

作用：检查某个非写规则是否被同一目标上的更强写规则覆盖。这样可以避免把已经明确放行的地方误判为受限。

数据流：输入一条规则 → 遍历当前策略规则，找访问权限更高且指向同一目标的写规则 → 返回是否找到。

调用关系：has_write_narrowing_entries 会用它判断非写规则是否真的收窄了写权限。

fn workspace_write(
        writable_roots: &[AbsolutePathBuf],
        exclude_tmpdir_env_var: bool,
        exclude_slash_tmp: bool,
    ) -> Self

作用：创建“工作区可写”的常用策略：整体可读，项目根、指定目录和临时目录可写，但敏感元数据默认只读。

数据流：输入额外可写根目录，以及是否排除 TMPDIR 和 /tmp → 先加入根目录只读、项目根可写、临时目录可写规则；再加入用户指定可写目录；最后给 .git、.agents、.codex 等敏感位置补只读规则 → 返回受限策略。

调用关系：旧 WorkspaceWrite 策略转换和多处工作区写权限配置都会调用它；它会用 default_read_only_subpaths_for_writable_root 和 append_default_read_only 系列函数补保护规则。

调用图：调用 4 个内部函数（restricted, append_default_read_only_path_if_no_explicit_rule, append_default_read_only_project_root_subpath_if_no_explicit_rule, default_read_only_subpaths_for_writable_root）；被 8 处调用（extensible_builtin_parent_profile, test_writable_roots_constraint, write_permissions_for_paths_keep_dirs_outside_workspace_root, write_permissions_for_paths_skip_dirs_already_writable_under_workspace_root, ignores_missing_writable_roots, mounts_dev_before_writable_dev_binds, workspace_write_with, from）；外部调用 3 个（project_roots, iter, vec!）。

fn from_legacy_sandbox_policy_for_cwd(sandbox_policy: &SandboxPolicy, cwd: &Path) -> Self

作用：把旧版沙箱策略转换成新版文件系统策略，并按当前目录补上默认保护项。

数据流：输入旧策略和当前工作目录 → 先做基础转换；如果是工作区可写策略，就为当前目录和额外可写根目录补 .git、.codex 等只读保护 → 返回新策略。

调用关系：一次性命令执行、设置旧策略、会话配置更新等兼容路径会用它；它依赖 default_read_only_subpaths_for_writable_root 和 append_default_read_only_path_if_no_explicit_rule。

调用图：调用 3 个内部函数（append_default_read_only_path_if_no_explicit_rule, default_read_only_subpaths_for_writable_root, from_absolute_path）；被 19 处调用（exec_one_off_command_inner, can_set_legacy_sandbox_policy, set_legacy_sandbox_policy, file_system_policy_with_unreadable_glob, session_configuration_apply_permission_profile_preserves_existing_deny_read_entries, session_configuration_apply_retargets_legacy_workspace_root_on_cwd_update, non_legacy_file_system_sandbox_policy, build_agent_spawn_config_uses_turn_context_values, spawn_agent_reapplies_runtime_sandbox_after_role_config, network_approval_retry_keeps_deny_read_sandbox_for_escalated_command (+9 more)）；外部调用 1 个（from）。

fn has_full_disk_read_access(&self) -> bool

作用：判断策略是否等同于拥有全盘读取能力。受限策略必须根目录可读，并且没有拒读例外，才算全盘可读。

数据流：读取策略类型 → 不受限或外部沙箱直接算 true；受限时检查根目录可读且没有 Deny 读限制 → 输出布尔值。

调用关系：生成沙箱参数、计算可读根、语义签名和权限扩展都会问它。

调用图：调用 2 个内部函数（has_denied_read_restrictions, has_root_access）；被 7 处调用（add_helper_runtime_permissions, create_filesystem_args, get_readable_roots_with_cwd, include_platform_defaults, semantic_signature, with_additional_readable_roots, has_full_disk_read_access）。

fn has_full_disk_write_access(&self) -> bool

作用：判断策略是否等同于拥有全盘写入能力。受限策略必须根目录可写，并且没有更窄的写入限制。

数据流：读取策略类型 → 不受限或外部沙箱直接算 true；受限时检查根目录可写且没有写权限收窄条目 → 输出布尔值。

调用关系：沙箱命令生成、写权限判断、旧策略转换和提示文案都会用它。

调用图：调用 2 个内部函数（has_root_access, has_write_narrowing_entries）；被 10 处调用（patch_rejection_reason, create_bwrap_command_args, create_filesystem_args, sandbox_prompt_from_policy, can_write_path_with_cwd, get_writable_roots_with_cwd, semantic_signature, to_legacy_sandbox_policy, ensure_linux_bubblewrap_is_supported, should_require_platform_sandbox）。

fn include_platform_defaults(&self) -> bool

作用：判断是否应该加入平台默认可读位置。平台默认位置可以理解成系统运行所需的一些基础文件。

数据流：读取策略 → 如果没有全盘读、是受限策略，并且 Minimal 特殊路径可读，就返回 true → 否则 false。

调用关系：创建文件系统沙箱参数和生成语义签名时会用它。

调用图：调用 1 个内部函数（has_full_disk_read_access）；被 3 处调用（create_filesystem_args, semantic_signature, include_platform_defaults）；外部调用 1 个（matches!）。

fn resolve_access_with_cwd(&self, path: &Path, cwd: &Path) -> FileSystemAccessMode

作用：计算某个路径在当前工作目录下最终是什么权限：拒绝、可读，还是可写。

数据流：输入路径和当前目录 → 不受限或外部沙箱直接返回 Write；受限时先把路径转绝对，再找所有能覆盖它的规则，选最具体且权限优先级最高的一条 → 返回访问模式。

调用关系：can_read_path_with_cwd、can_write_path_with_cwd 和请求内授权判断都会以它为核心。

调用图：调用 2 个内部函数（resolved_entries_with_cwd, resolve_candidate_path）；被 3 处调用（can_read_path_with_cwd, can_write_path_with_cwd, granted_file_system_entry_within_request）。

fn can_read_path_with_cwd(&self, path: &Path, cwd: &Path) -> bool

作用：判断某个路径在当前目录下能不能读。它是 resolve_access_with_cwd 的简单读权限包装。

数据流：输入路径和当前目录 → 先算最终访问模式 → 调用 can_read → 返回是否可读。

调用关系：增加可读根、Windows 根读判断等流程会调用它。

调用图：调用 1 个内部函数（resolve_access_with_cwd）；被 3 处调用（windows_policy_has_root_read_access, add_helper_runtime_permissions, with_additional_readable_roots）。

fn can_write_path_with_cwd(&self, path: &Path, cwd: &Path) -> bool

作用：判断某个路径在当前目录下能不能写。除了普通写权限，它还额外检查受保护元数据目录。

数据流：输入路径和当前目录 → 先算规则是否允许写；如果不允许就返回 false；如果全盘写就返回 true；否则再检查是否被元数据保护挡住 → 输出最终是否可写。

调用关系：添加可写根、元数据写入拒绝、兼容策略和可写根保护名计算都会用它。

调用图：调用 3 个内部函数（has_full_disk_write_access, is_metadata_write_denied, resolve_access_with_cwd）；被 4 处调用（with_additional_writable_roots, forbidden_agent_metadata_write, compatibility_workspace_write_policy, protected_metadata_names_for_writable_root）。

fn is_metadata_write_denied(&self, path: &Path, cwd: &Path) -> bool

作用：判断某次写入是不是被“.git/.codex/.agents 等元数据保护”拦住。它只在受限策略下生效。

数据流：输入路径和当前目录 → 解析成绝对路径；如果目标位于可写根里的受保护元数据目录，就检查是否有明确写入放行；没有放行则返回 true → 否则 false。

调用关系：can_write_path_with_cwd 在普通写权限通过后会调用它，作为额外安全门。

调用图：调用 3 个内部函数（has_explicit_write_entry_for_metadata_path, metadata_child_of_writable_root, resolve_candidate_path）；被 1 处调用（can_write_path_with_cwd）；外部调用 1 个（matches!）。

fn materialize_project_roots_with_cwd(mut self, cwd: &Path) -> Self

作用：把规则里的“项目根”特殊写法，按当前工作目录换成真实路径。这样后续沙箱运行时不用再理解这个抽象名字。

数据流：输入当前策略和当前目录 → 遍历规则；ProjectRoots 特殊路径转成普通绝对路径，项目根通配符也改成真实路径通配符 → 返回修改后的策略。

调用关系：它依赖 resolve_file_system_path、parse_project_roots_glob_pattern 和 resolve_project_roots_glob_pattern，是规则落地的一步。

调用图：调用 4 个内部函数（parse_project_roots_glob_pattern, resolve_file_system_path, resolve_project_roots_glob_pattern, from_absolute_path）；外部调用 1 个（as_ref）。

fn materialize_project_roots_with_workspace_roots(
        mut self,
        workspace_roots: &[AbsolutePathBuf],
    ) -> Self

作用：把“项目根”规则展开成多个工作区根目录的真实规则。一个抽象规则可以变成多条具体规则。

数据流：输入策略和工作区根目录列表 → 遍历每条规则；ProjectRoots 被展开到每个根目录，相关通配符也分别展开；其他规则原样保留 → 返回新策略。

调用关系：多工作区场景会用它把抽象权限变成实际可执行的路径列表。

调用图：调用 1 个内部函数（parse_project_roots_glob_pattern）；外部调用 2 个（with_capacity, iter）。

fn with_materialized_project_roots_for_workspace_roots(
        mut self,
        workspace_roots: &[AbsolutePathBuf],
    ) -> Self

作用：在保留原规则的同时，额外补上按工作区根目录展开后的规则。它既不丢抽象规则，也提供具体规则。

数据流：输入策略和工作区根目录 → 克隆一份并展开项目根规则 → 把展开后当前策略没有的条目追加进来 → 返回增强后的策略。

调用关系：它包了一层 materialize_project_roots_with_workspace_roots，用于需要兼容两种表示的地方。

fn with_additional_readable_roots(
        mut self,
        cwd: &Path,
        additional_readable_roots: &[AbsolutePathBuf],
    ) -> Self

作用：给策略补充额外可读目录，但不会重复添加已经可读的目录。全盘可读时什么也不用做。

数据流：输入当前目录和额外可读根列表 → 如果已有全盘读则原样返回；否则逐个检查是否已可读，未可读的追加 Read 规则 → 返回新策略。

调用关系：它用 has_full_disk_read_access 和 can_read_path_with_cwd 做避免重复和避免无效添加的判断。

调用图：调用 2 个内部函数（can_read_path_with_cwd, has_full_disk_read_access）。

fn with_additional_writable_roots(
        mut self,
        cwd: &Path,
        additional_writable_roots: &[AbsolutePathBuf],
    ) -> Self

作用：给策略补充额外可写目录，但跳过已经可写的目录。

数据流：输入当前目录和额外可写根列表 → 逐个检查能不能写；不能写的追加 Write 规则 → 返回新策略。

调用关系：它调用 can_write_path_with_cwd；常用于根据运行请求临时扩大写入范围。

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

fn with_additional_legacy_workspace_writable_roots(
        mut self,
        additional_writable_roots: &[AbsolutePathBuf],
    ) -> Self

作用：按旧工作区写入规则给策略加可写目录，并补上默认元数据只读保护。

数据流：输入额外可写根目录 → 只在受限策略下处理；没有同路径写规则就添加 Write；然后为每个根目录补 .git、.codex 等只读保护 → 返回策略。

调用关系：它服务于旧 WorkspaceWrite 兼容路径，内部调用 default_read_only_subpaths_for_writable_root 和 append_default_read_only_path_if_no_explicit_rule。

调用图：调用 2 个内部函数（append_default_read_only_path_if_no_explicit_rule, default_read_only_subpaths_for_writable_root）；外部调用 1 个（matches!）。

fn needs_direct_runtime_enforcement(
        &self,
        network_policy: NetworkSandboxPolicy,
        cwd: &Path,
    ) -> bool

作用：判断当前新权限规则是否必须由新运行时直接执行，而不能只靠旧沙箱模型表达。旧模型表达不了时，必须启用更直接的检查。

数据流：输入文件系统策略、网络策略和当前目录 → 非受限策略返回 false；尝试转旧策略，失败则返回 true；再检查受保护元数据和整体语义是否和旧运行时投影一致 → 不一致就返回 true。

调用关系：ensure_legacy_landlock_mode_supports_policy 会用它决定旧沙箱是否够用；它调用 to_legacy_sandbox_policy、protected_metadata_names_need_direct_runtime_enforcement 和 semantic_signature。

调用图：调用 4 个内部函数（semantic_signature, to_legacy_sandbox_policy, legacy_runtime_file_system_policy_for_cwd, protected_metadata_names_need_direct_runtime_enforcement）；被 1 处调用（ensure_legacy_landlock_mode_supports_policy）；外部调用 1 个（matches!）。

fn is_semantically_equivalent_to(&self, other: &Self, cwd: &Path) -> bool

作用：判断两个策略在实际效果上是否一样，而不是只看规则写法是否一模一样。

数据流：输入另一个策略和当前目录 → 分别生成语义签名 → 比较签名是否相等 → 返回布尔值。

调用关系：它把比较工作交给 semantic_signature，适合测试或配置更新判断。

调用图：调用 1 个内部函数（semantic_signature）；外部调用 1 个（semantic_signature）。

fn get_readable_roots_with_cwd(&self, cwd: &Path) -> Vec<AbsolutePathBuf>

作用：列出当前策略明确允许读取的根目录。全盘可读时返回空列表，因为没必要列出每个目录。

数据流：输入当前目录 → 如果全盘可读返回空；否则解析规则，筛出可读且实际可读的路径，去重并规范化 → 返回绝对路径列表。

调用关系：创建沙箱参数、生成语义签名和查询可读根都会用它。

调用图：调用 3 个内部函数（has_full_disk_read_access, resolved_entries_with_cwd, dedup_absolute_paths）；被 3 处调用（create_filesystem_args, semantic_signature, readable_roots_for_cwd）；外部调用 1 个（new）。

fn get_writable_roots_with_cwd(&self, cwd: &Path) -> Vec<WritableRoot>

作用：列出当前策略明确允许写入的根目录，并附带每个可写根下面仍要只读保护的子路径。它是落地沙箱文件挂载规则的重要来源。

数据流：输入当前目录 → 全盘可写时返回空；否则解析可写条目、去重，逐个可写根计算受保护元数据名、默认只读子路径和更窄的只读 carveout → 输出 WritableRoot 列表。

调用关系：沙箱参数生成、权限提示、旧策略兼容和直接运行时判断都会用它；它会调用 protected_metadata_names_for_writable_root、default_read_only_subpaths_for_writable_root 和 dedup_absolute_paths 等辅助函数。

调用图：调用 3 个内部函数（has_full_disk_write_access, resolved_entries_with_cwd, dedup_absolute_paths）；被 6 处调用（patch_rejection_reason, create_filesystem_args, sandbox_prompt_from_policy, semantic_signature, protected_metadata_names_need_direct_runtime_enforcement, compatibility_workspace_write_policy）；外部调用 1 个（new）。

fn get_unreadable_roots_with_cwd(&self, cwd: &Path) -> Vec<AbsolutePathBuf>

作用：列出明确禁止读取的具体根路径。它不会把文件系统根目录本身随便物化成拒读项，以免覆盖更细的可读例外。

数据流：输入当前目录 → 非受限策略返回空；受限策略中解析 Deny 条目，筛出实际不可读且不是根目录整体的路径，去重规范化 → 返回不可读根列表。

调用关系：创建沙箱参数、拒读文案、语义签名和 ReadDenyMatcher::build 都会用它。

调用图：调用 3 个内部函数（resolved_entries_with_cwd, dedup_absolute_paths, from_absolute_path）；被 5 处调用（create_filesystem_args, denied_reads_text, semantic_signature, build, resolve_windows_deny_read_paths）；外部调用 2 个（new, matches!）。

fn get_unreadable_globs_with_cwd(&self, cwd: &Path) -> Vec<String>

作用：列出明确禁止读取的通配符规则。通配符就是像 *.secret 这样能匹配一批路径的模式。

数据流：输入当前目录 → 非受限策略返回空；受限策略中找 Deny 且是 GlobPattern 的条目，把它们按当前目录转成字符串，排序去重 → 返回模式列表。

调用关系：沙箱参数生成、拒读文案、语义签名、ReadDenyMatcher::build 和平台特定拒读策略都会用它。

调用图：被 7 处调用（create_bwrap_command_args, create_filesystem_args, denied_reads_text, semantic_signature, build, build_seatbelt_unreadable_glob_policy, resolve_windows_deny_read_paths）；外部调用 2 个（new, matches!）。

fn to_legacy_sandbox_policy(
        &self,
        network_policy: NetworkSandboxPolicy,
        cwd: &Path,
    ) -> io::Result<SandboxPolicy>

作用：把新版文件系统策略尽量翻译成旧版 SandboxPolicy。旧版表达能力较弱，所以有些新规则会无法翻译并返回错误。

数据流：输入文件系统策略、网络策略和当前目录 → 外部沙箱、不受限和受限策略分别映射；受限时统计工作区是否可写、额外可写根、临时目录是否可写；如果旧模型能表达就返回旧策略，否则返回 InvalidInput 错误。

调用关系：needs_direct_runtime_enforcement 会调用它来判断旧运行时是否够用；它还依赖 NetworkSandboxPolicy::is_enabled、has_full_disk_write_access 和 resolve_file_system_special_path。

调用图：调用 5 个内部函数（has_full_disk_write_access, is_enabled, dedup_absolute_paths, resolve_file_system_special_path, from_absolute_path）；被 1 处调用（needs_direct_runtime_enforcement）；外部调用 2 个（new, new）。

fn resolved_entries_with_cwd(&self, cwd: &Path) -> Vec<ResolvedFileSystemEntry>

作用：把策略里的路径规则解析成真实绝对路径规则。不能解析的通配符或抽象项会被跳过。

数据流：输入当前目录 → 先把 cwd 变成绝对路径；遍历 entries，把每条可解析路径转成 ResolvedFileSystemEntry，保留权限 → 返回解析后的列表。

调用关系：访问判断、可读/可写/不可读根计算、元数据检查都会用它；它内部调用 resolve_entry_path。

调用图：调用 1 个内部函数（from_absolute_path）；被 6 处调用（get_readable_roots_with_cwd, get_unreadable_roots_with_cwd, get_writable_roots_with_cwd, resolve_access_with_cwd, has_explicit_write_entry_for_metadata_path, metadata_child_of_writable_root）。

fn semantic_signature(&self, cwd: &Path) -> FileSystemSemanticSignature

作用：生成策略的“语义签名”，也就是把实际效果整理成一个可比较的摘要。规则顺序或写法不同，但效果相同，就应该得到相同签名。

数据流：输入当前目录 → 计算是否全盘读写、是否包含平台默认、可读根、可写根、不可读根和拒读通配符 → 排序整理后返回签名对象。

调用关系：is_semantically_equivalent_to 和 needs_direct_runtime_enforcement 都靠它比较策略效果。

调用图：调用 9 个内部函数（get_readable_roots_with_cwd, get_unreadable_globs_with_cwd, get_unreadable_roots_with_cwd, get_writable_roots_with_cwd, has_full_disk_read_access, has_full_disk_write_access, include_platform_defaults, sorted_absolute_paths, sorted_writable_roots）；被 2 处调用（is_semantically_equivalent_to, needs_direct_runtime_enforcement）。

fn from(value: &SandboxPolicy) -> Self

作用：从旧版 SandboxPolicy 提取新版网络策略。旧策略如果有完整网络访问，就转成 Enabled，否则 Restricted。

数据流：输入旧沙箱策略 → 调用旧策略的 has_full_network_access → 输出新版网络策略。

调用关系：会话配置、执行命令和代理启动时从旧配置迁移网络权限会用它。

调用图：被 14 处调用（exec_one_off_command_inner, can_set_legacy_sandbox_policy, set_legacy_sandbox_policy, apply, session_configuration_apply_preserves_profile_file_system_policy_on_cwd_only_update, session_configuration_apply_retargets_legacy_workspace_root_on_cwd_update, build_agent_spawn_config_uses_turn_context_values, spawn_agent_reapplies_runtime_sandbox_after_role_config, from_legacy_sandbox_policy, from_legacy_sandbox_policy (+4 more)）；外部调用 1 个（has_full_network_access）。

fn from(value: &SandboxPolicy) -> Self

作用：从旧版 SandboxPolicy 生成新版文件系统策略。它是旧权限模型进入新模型的基础转换。

数据流：输入旧沙箱策略 → DangerFullAccess 转不受限，ExternalSandbox 转外部沙箱，ReadOnly 转根只读，WorkspaceWrite 转工作区可写策略 → 输出新版策略。

调用关系：from_legacy_sandbox_policy 和 legacy_runtime_file_system_policy_for_cwd 会用它作为基础桥梁。

调用图：调用 4 个内部函数（external_sandbox, restricted, unrestricted, workspace_write）；被 2 处调用（from_legacy_sandbox_policy, legacy_runtime_file_system_policy_for_cwd）；外部调用 1 个（vec!）。

fn resolve_file_system_path(
    path: &FileSystemPath,
    cwd: Option<&AbsolutePathBuf>,
) -> Option<AbsolutePathBuf>

作用：把一个 FileSystemPath 尽量解析成绝对路径。普通路径可直接用，特殊路径要按当前目录或环境变量解释，通配符不在这里解析。

数据流：输入路径表达和可选当前目录 → 普通路径克隆返回；通配符返回 None；特殊路径交给 resolve_file_system_special_path → 输出可选绝对路径。

调用关系：materialize_project_roots_with_cwd 和 resolve_entry_path 会调用它。

调用图：调用 1 个内部函数（resolve_file_system_special_path）；被 2 处调用（materialize_project_roots_with_cwd, resolve_entry_path）；外部调用 1 个（clone）。

fn resolve_entry_path(
    path: &FileSystemPath,
    cwd: Option<&AbsolutePathBuf>,
) -> Option<AbsolutePathBuf>

作用：解析规则条目的路径，特别处理 Root：Root 会变成当前文件系统的根目录，比如 /。

数据流：输入路径表达和可选当前目录 → 如果是 Root，就从 cwd 找系统根；否则调用 resolve_file_system_path → 返回可选绝对路径。

调用关系：resolved_entries_with_cwd 间接使用它把规则落成可比较的绝对路径。

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

fn parse_project_roots_glob_pattern(pattern: &str) -> Option<&Path>

作用：识别一个通配符字符串是不是“项目根通配符”格式，并取出里面的子路径。

数据流：输入模式字符串 → 检查是否有固定前缀 → 有则返回前缀后的 Path，没有返回 None。

调用关系：项目根规则落地到当前目录或多个工作区根时会调用它。

调用图：被 2 处调用（materialize_project_roots_with_cwd, materialize_project_roots_with_workspace_roots）。

fn resolve_project_roots_glob_pattern(subpath: &Path, root: &AbsolutePathBuf) -> String

作用：把项目根通配符里的子路径，和某个真实项目根拼成实际通配符字符串。

数据流：输入子路径和项目根绝对路径 → 按项目根解析子路径 → 转成字符串返回。

调用关系：materialize_project_roots_with_cwd 和工作区根展开流程会用它生成真实模式。

调用图：调用 2 个内部函数（as_path, resolve_path_against_base）；被 1 处调用（materialize_project_roots_with_cwd）。

fn resolve_candidate_path(path: &Path, cwd: &Path) -> Option<AbsolutePathBuf>

作用：把用户传入的候选路径转成绝对路径。相对路径会按当前工作目录补全。

数据流：输入路径和当前目录 → 如果路径本来是绝对路径就验证并返回；否则把 cwd 变成绝对路径后拼接相对路径 → 返回可选绝对路径。

调用关系：访问判断和元数据写入保护都会先调用它，保证后面比较的是同一种路径形态。

调用图：调用 1 个内部函数（from_absolute_path）；被 3 处调用（is_metadata_write_denied, resolve_access_with_cwd, forbidden_agent_metadata_write）；外部调用 1 个（is_absolute）。

fn file_system_paths_share_target(left: &FileSystemPath, right: &FileSystemPath) -> bool

作用：判断两个文件系统路径规则是不是指向同一个目标。它能比较普通路径、特殊路径和通配符。

数据流：输入两个 FileSystemPath → 根据类型分别比较：普通路径比绝对路径，特殊路径比含义，特殊路径和绝对路径按少数已知情况匹配，通配符只和相同通配符匹配 → 返回是否同目标。

调用关系：写规则覆盖判断和追加默认只读规则时会用它，避免重复或冲突。

调用图：调用 2 个内部函数（special_path_matches_absolute_path, special_paths_share_target）。

fn special_paths_share_target(left: &FileSystemSpecialPath, right: &FileSystemSpecialPath) -> bool

作用：判断两个特殊路径是否代表同一类位置，比如两个都是 /tmp 或两个都是同一个项目根子路径。

数据流：输入两个特殊路径值 → 按具体枚举种类比较，ProjectRoots 比子路径，Unknown 比名字和子路径 → 返回是否相同。

调用关系：file_system_paths_share_target 会调用它处理特殊路径之间的比较。

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

fn special_path_matches_absolute_path(
    value: &FileSystemSpecialPath,
    path: &AbsolutePathBuf,
) -> bool

作用：判断一个特殊路径是否能对应到某个绝对路径。目前只处理少数明确情况，比如 Root 和 /tmp。

数据流：输入特殊路径和绝对路径 → Root 检查该路径是否没有父目录，SlashTmp 检查是否等于 /tmp，其他返回 false。

调用关系：file_system_paths_share_target 在比较特殊路径和普通绝对路径时会调用它。

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

fn resolved_entry_precedence(entry: &ResolvedFileSystemEntry) -> (usize, FileSystemAccessMode)

作用：给已解析规则算优先级。路径越具体，优先级越高；同样具体时再看访问模式。

数据流：输入一条已解析规则 → 统计路径组件数量作为具体程度，并带上访问模式 → 返回排序用的二元组。

调用关系：resolve_access_with_cwd 用它从多条覆盖同一路径的规则里挑最终生效的一条。

fn absolute_root_path_for_cwd(cwd: &AbsolutePathBuf) -> AbsolutePathBuf

作用：从当前工作目录找出所在文件系统的根目录。比如 Unix 上通常是 /。

数据流：输入绝对 cwd → 取 ancestors 的最后一个作为根 → 验证它是绝对路径并返回；异常时会 panic，因为 cwd 理论上必须有根。

调用关系：Root 特殊路径解析和不可读根过滤会用它。

调用图：调用 2 个内部函数（as_path, from_absolute_path）。

fn normalized_and_canonical_candidates(path: &Path) -> Vec<PathBuf>

作用：为一个路径生成几种可比较的写法：普通绝对写法和真实解析后的写法。这样符号链接不会轻易绕过拒读规则。

数据流：输入路径 → 先保存规范化后的绝对路径，失败则保存原路径；再尝试 canonicalize，也就是跟随系统解析真实目标，并加入列表 → 返回去重后的候选路径。

调用关系：ReadDenyMatcher::build 和 is_read_denied 用它比较拒读根和待检查路径。

调用图：调用 2 个内部函数（push_unique, from_absolute_path）；被 1 处调用（is_read_denied）；外部调用 3 个（canonicalize, to_path_buf, new）。

fn push_unique(candidates: &mut Vec<PathBuf>, candidate: PathBuf)

作用：往列表里追加路径，但如果已经有相同路径就不加。它是简单去重工具。

数据流：输入路径列表和候选路径 → 检查列表里是否已有 → 没有就追加，有就保持不变。

调用关系：normalized_and_canonical_candidates 用它避免同一路径的多种解析结果重复出现。

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

fn build_glob_matcher(pattern: &str) -> Result<GlobMatcher, String>

作用：把通配符字符串编译成可执行的匹配器。匹配器之后可以拿来判断路径是否符合模式。

数据流：输入通配符模式 → 设置匹配规则：星号和问号不跨路径分隔符，未闭合的方括号按普通字符处理 → 编译成功返回 GlobMatcher，失败返回错误文字。

调用关系：ReadDenyMatcher::build 用它处理拒读通配符。

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

fn resolve_file_system_special_path(
    value: &FileSystemSpecialPath,
    cwd: Option<&AbsolutePathBuf>,
) -> Option<AbsolutePathBuf>

作用：把特殊路径名解析成机器上的真实绝对路径，比如项目根、TMPDIR、/tmp。不能确定的特殊路径返回 None。

数据流：输入特殊路径和可选当前目录 → ProjectRoots 依赖 cwd 解析，Tmpdir 读取环境变量 TMPDIR，SlashTmp 检查 /tmp 是否存在，Root/Minimal/Unknown 不在这里解析 → 返回可选绝对路径。

调用关系：to_legacy_sandbox_policy 和 resolve_file_system_path 会调用它，把抽象规则落成实际路径。

调用图：调用 2 个内部函数（from_absolute_path, resolve_path_against_base）；被 2 处调用（to_legacy_sandbox_policy, resolve_file_system_path）；外部调用 2 个（from, var_os）。

fn dedup_absolute_paths(
    paths: Vec<AbsolutePathBuf>,
    normalize_effective_paths: bool,
) -> Vec<AbsolutePathBuf>

作用：对绝对路径列表去重，可选择先按实际有效路径规范化。它用来减少重复挂载或重复规则。

数据流：输入绝对路径列表和是否规范化的开关 → 逐个路径可选调用 normalize_effective_absolute_path，再用集合记录见过的路径 → 返回去重后的列表。

调用关系：可读根、可写根、不可读根、旧策略转换和默认只读子路径计算都会用它。

调用图：调用 1 个内部函数（normalize_effective_absolute_path）；被 5 处调用（get_readable_roots_with_cwd, get_unreadable_roots_with_cwd, get_writable_roots_with_cwd, to_legacy_sandbox_policy, default_read_only_subpaths_for_writable_root）；外部调用 2 个（new, with_capacity）。

fn sorted_absolute_paths(mut paths: Vec<AbsolutePathBuf>) -> Vec<AbsolutePathBuf>

作用：把绝对路径列表按路径文字排序。排序让比较结果稳定。

数据流：输入路径列表 → 按路径大小排序 → 返回排序后的列表。

调用关系：semantic_signature 和 sorted_writable_roots 用它生成稳定的语义摘要。

调用图：被 2 处调用（semantic_signature, sorted_writable_roots）。

fn sorted_writable_roots(mut roots: Vec<WritableRoot>) -> Vec<WritableRoot>

作用：把可写根列表和其中的只读子路径、受保护元数据名整理成稳定顺序。这样两个等价策略更容易比较。

数据流：输入 WritableRoot 列表 → 每个根内部对子路径排序、元数据名排序去重；再按根路径排序 → 返回整理后的列表。

调用关系：semantic_signature 调用它生成可比较的写权限摘要。

调用图：调用 1 个内部函数（sorted_absolute_paths）；被 1 处调用（semantic_signature）；外部调用 1 个（take）。

fn normalize_effective_absolute_path(path: AbsolutePathBuf) -> AbsolutePathBuf

作用：尽量把路径规范成系统实际会访问的有效路径，同时保留路径末尾可能还不存在的部分。它主要处理符号链接和系统别名。

数据流：输入绝对路径 → 从路径祖先开始找存在的部分，尝试 canonicalize_preserving_symlinks，然后把剩余后缀接回去 → 成功返回规范路径，失败返回原路径。

调用关系：dedup_absolute_paths 在需要按实际路径去重时会调用它。

调用图：调用 2 个内部函数（from_absolute_path, to_path_buf）；被 1 处调用（dedup_absolute_paths）；外部调用 2 个（canonicalize_preserving_symlinks, symlink_metadata）。

fn default_read_only_subpaths_for_writable_root(
    writable_root: &AbsolutePathBuf,
    protect_missing_dot_codex: bool,
) -> Vec<AbsolutePathBuf>

作用：为一个可写根目录找出默认仍应只读保护的子路径，重点是 .git、.agents、.codex。这样项目可写时也不会轻易破坏仓库和代理元数据。

数据流：输入可写根和是否保护尚未存在的 .codex → 检查 .git 是目录还是指针文件，必要时解析真实 gitdir；检查 .agents 和 .codex 是否存在或是否要预先保护 → 去重后返回只读子路径列表。

调用关系：workspace_write、旧策略转换、追加旧工作区可写根和运行时投影都会用它。

调用图：调用 4 个内部函数（dedup_absolute_paths, is_git_pointer_file, resolve_gitdir_from_file, join）；被 5 处调用（from_legacy_sandbox_policy_for_cwd, with_additional_legacy_workspace_writable_roots, workspace_write, legacy_runtime_file_system_policy_for_cwd, legacy_workspace_write_projection_accepts_relative_cwd）；外部调用 1 个（new）。

fn legacy_runtime_file_system_policy_for_cwd(
    sandbox_policy: &SandboxPolicy,
    cwd: &Path,
) -> FileSystemSandboxPolicy

作用：模拟旧运行时真正会执行出的文件系统策略。它用于和新策略比较，看旧运行时是否能完整表达新规则。

数据流：输入旧沙箱策略和当前目录 → 如果不是 WorkspaceWrite，直接转新策略；如果是，就按旧运行时规则重建根只读、项目根可写、临时目录和额外可写根，并补默认元数据只读保护 → 返回受限策略。

调用关系：needs_direct_runtime_enforcement 会用它和当前策略的 semantic_signature 对比。

调用图：调用 5 个内部函数（from, restricted, append_default_read_only_path_if_no_explicit_rule, default_read_only_subpaths_for_writable_root, from_absolute_path）；被 4 处调用（needs_direct_runtime_enforcement, legacy_projection_runtime_enforcement_ignores_entry_order, missing_symbolic_metadata_carveouts_need_direct_runtime_enforcement, split_only_nested_carveouts_need_direct_runtime_enforcement）；外部调用 1 个（vec!）。

fn append_default_read_only_project_root_subpath_if_no_explicit_rule(
    entries: &mut Vec<FileSystemSandboxEntry>,
    subpath: impl Into<PathBuf>,
)

作用：给项目根下某个子路径追加默认只读规则，但前提是没有已有规则明确提到同一目标。

数据流：输入规则列表和子路径 → 把子路径包装成 ProjectRoots 特殊路径 → 交给通用追加函数处理 → 可能修改规则列表。

调用关系：workspace_write 用它默认保护项目根下的 .git、.agents、.codex。

调用图：调用 1 个内部函数（append_default_read_only_entry_if_no_explicit_rule）；被 1 处调用（workspace_write）；外部调用 2 个（into, project_roots）。

fn append_default_read_only_path_if_no_explicit_rule(
    entries: &mut Vec<FileSystemSandboxEntry>,
    path: AbsolutePathBuf,
)

作用：给某个具体绝对路径追加默认只读规则，但不会覆盖已有显式规则。

数据流：输入规则列表和绝对路径 → 包装成 FileSystemPath::Path → 交给通用追加函数 → 可能追加 Read 规则。

调用关系：旧策略转换、工作区写策略和旧运行时投影都会用它补敏感路径保护。

调用图：调用 1 个内部函数（append_default_read_only_entry_if_no_explicit_rule）；被 4 处调用（from_legacy_sandbox_policy_for_cwd, with_additional_legacy_workspace_writable_roots, workspace_write, legacy_runtime_file_system_policy_for_cwd）。

fn append_default_read_only_entry_if_no_explicit_rule(
    entries: &mut Vec<FileSystemSandboxEntry>,
    path: FileSystemPath,
)

作用：通用的“补默认只读规则”函数。它只有在没有任何规则指向同一目标时才追加，避免和用户明确配置冲突。

数据流：输入规则列表和路径表达 → 先检查是否已有同目标规则；有则不动，没有则追加 access=Read 的规则 → 修改规则列表。

调用关系：append_default_read_only_path_if_no_explicit_rule 和 append_default_read_only_project_root_subpath_if_no_explicit_rule 都把实际追加工作交给它。

调用图：被 2 处调用（append_default_read_only_path_if_no_explicit_rule, append_default_read_only_project_root_subpath_if_no_explicit_rule）。

fn has_explicit_resolved_path_entry(
    entries: &[ResolvedFileSystemEntry],
    path: &AbsolutePathBuf,
) -> bool

作用：检查已解析规则里是否有某个确切路径。它用于判断默认保护项是不是已经被显式规则覆盖。

数据流：输入已解析规则列表和目标路径 → 遍历比较路径是否相等 → 返回 true 或 false。

调用关系：get_writable_roots_with_cwd 在计算只读子路径时用它避免重复加入已有显式规则。

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

fn metadata_path_name(name: &OsStr) -> Option<&'static str>

作用：如果一个文件名属于受保护元数据名，就返回对应的标准字符串。否则返回 None。

数据流：输入文件名 → 在受保护名字表里查找相等项 → 命中返回静态字符串，未命中返回 None。

调用关系：metadata_child_of_writable_root 用它识别可写根下的第一层路径是不是敏感元数据目录。

fn metadata_child_of_writable_root(
    policy: &FileSystemSandboxPolicy,
    target: &Path,
    cwd: &Path,
) -> Option<(AbsolutePathBuf, &'static str)>

作用：判断目标路径是否位于某个可写根目录下的受保护元数据区域里。比如项目可写，但项目/.git/config 就应被识别出来。

数据流：输入策略、目标路径和当前目录 → 解析策略里的可写根；对每个可写根尝试取目标的相对路径；如果第一层目录是受保护元数据名，就返回该元数据目录路径和名字 → 否则返回 None。

调用关系：is_metadata_write_denied 和 forbidden_agent_metadata_write 会调用它，判断写入是否碰到敏感区。

调用图：调用 1 个内部函数（resolved_entries_with_cwd）；被 2 处调用（is_metadata_write_denied, forbidden_agent_metadata_write）。

fn protected_metadata_names_for_writable_root(
    policy: &FileSystemSandboxPolicy,
    root: &AbsolutePathBuf,
    raw_writable_roots: &[&AbsolutePathBuf],
    cwd: &Path,
) -> Vec<String>

作用：计算某个可写根下哪些受保护元数据名仍然不能写。结果会交给下游沙箱去遮住这些名字。

数据流：输入策略、规范化后的可写根、原始可写根别名和当前目录 → 对每个受保护名字生成可能路径；如果这些路径全都不可写，就把名字加入结果 → 返回字符串列表。

调用关系：get_writable_roots_with_cwd 用它给每个 WritableRoot 附带 protected_metadata_names。

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

fn protected_metadata_names_need_direct_runtime_enforcement(
    policy: &FileSystemSandboxPolicy,
    legacy_policy: &SandboxPolicy,
    cwd: &Path,
) -> bool

作用：判断受保护元数据名的限制是否超出了旧沙箱能表达的范围。如果旧沙箱没有正确保护这些名字，就需要新运行时直接管。

数据流：输入新策略、旧策略和当前目录 → 取旧策略和新策略的可写根；逐个比较新策略要求保护的元数据名，在旧策略对应根的只读子路径里是否存在 → 有缺失就返回 true。

调用关系：needs_direct_runtime_enforcement 调用它作为旧运行时能力检查的一部分。

调用图：调用 1 个内部函数（get_writable_roots_with_cwd）；被 1 处调用（needs_direct_runtime_enforcement）；外部调用 1 个（get_writable_roots_with_cwd）。

fn has_explicit_write_entry_for_metadata_path(
    policy: &FileSystemSandboxPolicy,
    protected_metadata_path: &AbsolutePathBuf,
    target: &Path,
    cwd: &Path,
) -> bool

作用：判断受保护元数据目录里是否有明确的写入放行规则。只有这种明确规则才能绕过默认保护。

数据流：输入策略、受保护元数据目录、目标路径和当前目录 → 解析所有规则；寻找一条可写规则，它既覆盖目标路径，又位于受保护元数据目录之内 → 找到返回 true，否则 false。

调用关系：is_metadata_write_denied 和 forbidden_agent_metadata_write 用它决定元数据写入是否被明确允许。

调用图：调用 1 个内部函数（resolved_entries_with_cwd）；被 2 处调用（is_metadata_write_denied, forbidden_agent_metadata_write）。

fn is_git_pointer_file(path: &AbsolutePathBuf) -> bool

作用：判断某个路径是不是名为 .git 的普通文件。Git 工作树里 .git 可能是一个指向真实 git 目录的文件。

数据流：输入绝对路径 → 检查它是文件，并且文件名等于 .git → 返回 true 或 false。

调用关系：default_read_only_subpaths_for_writable_root 用它决定是否需要解析 .git 文件里的真实 gitdir 并一起保护。

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

fn resolve_gitdir_from_file(dot_git: &AbsolutePathBuf) -> Option<AbsolutePathBuf>

作用：读取一个 .git 文件里的“gitdir: 路径”指针，找出真正的 Git 元数据目录。这样工作树使用 Git 的分离目录时，沙箱仍然知道该保护哪里。

数据流：输入是一个绝对路径，通常指向名叫 .git 的文件 → 它读取文件内容，检查格式是不是 gitdir: <path>，把里面的路径按 .git 文件所在目录解析成绝对路径，并确认目标存在 → 成功时返回真实 git 目录路径；失败时记录错误并返回空值，不改动外部状态。

调用关系：它被 default_read_only_subpaths_for_writable_root 使用；当系统准备给一个可写项目根目录自动加上只读保护区时，会靠它识别 .git 文件背后真正的 Git 目录。它内部把具体读文件、路径拼接和报错分别交给标准库、AbsolutePathBuf::resolve_path_against_base 和日志宏。

调用图：调用 2 个内部函数（as_path, resolve_path_against_base）；被 1 处调用（default_read_only_subpaths_for_writable_root）；外部调用 2 个（error!, read_to_string）。

fn symlink_dir(original: &Path, link: &Path) -> std::io::Result<()>

作用：测试用的小工具，用来创建目录符号链接。符号链接可以理解成文件系统里的“快捷方式”。

数据流：输入是真实目录路径和要创建的链接路径 → 它调用 Unix 系统的 symlink 功能 → 返回创建成功或失败的结果，并在磁盘上多出一个链接。

调用关系：多个测试会用它搭出带符号链接的目录结构，然后检查权限计算是否保留用户看到的链接路径，而不是随便改成真实路径。

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

fn unknown_special_paths_are_ignored_by_legacy_bridge() -> std::io::Result<()>

作用：确认新版本里未来可能出现的特殊路径规则，转换到老沙箱格式时不会把系统搞坏。未知规则会被忽略，而不是误放权限。

数据流：输入是一组权限规则：根目录只读，另一个未知特殊路径可写 → 转成旧版 SandboxPolicy → 输出应是只读沙箱，并且网络不开放。

调用关系：由测试运行器执行，用来保护新旧权限格式之间的桥接代码。它间接检查 to_legacy_sandbox_policy 在遇到不认识的特殊路径时选择安全退让。

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

fn writable_roots_proactively_protect_missing_dot_codex()

作用：确认即使项目里暂时没有 .codex 目录，沙箱也会提前把这个位置当成受保护区域。这样程序不能先创建它再写入敏感配置。

数据流：输入是一个临时工作目录和“项目根可写”的规则 → 计算可写根目录 → 输出里应该包含该根目录，同时把根下的 .codex 放进只读子路径。

调用关系：测试 get_writable_roots_with_cwd 的默认保护行为，确保后续运行时执行权限时有足够信息拦住 .codex 写入。

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

fn legacy_workspace_write_projection_preserves_symbolic_project_root()

作用：确认旧版“工作区可写”策略转换成新版规则时，仍然用“项目根”这个符号概念，而不是硬编码某一个路径。

数据流：输入是旧版工作区可写策略 → 转成 FileSystemSandboxPolicy → 输出应包含根目录只读、项目根可写，以及 .git、.agents、.codex 在项目根下只读的规则。

调用关系：测试 FileSystemSandboxPolicy::from 的转换结果，防止老策略升级后丢失项目元数据保护。

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

fn legacy_current_working_directory_special_path_deserializes_as_project_roots() -> serde_json::Result<()>

作用：确认老 JSON 里叫 current_working_directory 的特殊路径，读进来后会当成现在的 project_roots。这是为了兼容旧配置文件。

数据流：输入是一段旧格式 JSON → 反序列化成 FileSystemSpecialPath → 得到项目根特殊路径；再序列化回 JSON 时输出新名字 project_roots。

调用关系：测试 serde JSON 读写兼容层，确保用户升级版本后旧配置还能用，但保存时会变成新格式。

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

fn writable_roots_skip_default_dot_codex_when_explicit_user_rule_exists()

作用：确认用户如果明确允许写 .codex，这条显式规则会压过默认保护。也就是说默认安全规则不是不可覆盖的死规则。

数据流：输入是项目根可写规则，加上一条明确的 .codex 可写路径规则 → 计算可写根并检查写权限 → 输出中 .codex 不再被列为受保护名字或只读子路径，写 .codex/config.toml 返回允许。

调用关系：测试 get_writable_roots_with_cwd 和 can_write_path_with_cwd 的配合，说明显式用户意图会影响默认元数据保护。

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

fn filesystem_policy_blocks_protected_metadata_path_writes_by_default()

作用：确认只要把项目目录设为可写，系统仍会默认挡住 .git、.agents、.codex 这些敏感目录里的写入。

数据流：输入是一个可写根路径规则 → 分别询问三个元数据配置文件能不能写，并计算可写根 → 输出都是不能写，且可写根记录了三个受保护名字。

调用关系：测试普通路径可写规则下的默认安全保护，防止“一整个目录可写”意外包含仓库和代理元数据。

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

fn legacy_workspace_write_projection_accepts_relative_cwd()

作用：确认旧版工作区策略在当前目录是相对路径时也能正确转换。相对路径就是像 workspace 这样不从根开始的路径。

数据流：输入是相对工作目录和旧版工作区可写策略 → 转成新版文件系统策略，并补上默认只读保护路径 → 输出应等于预期规则；同时检查 .git、.codex、.agents 下写入会被挡住。

调用关系：测试 from_legacy_sandbox_policy_for_cwd、default_read_only_subpaths_for_writable_root、forbidden_agent_metadata_write 和写权限判断，保证老策略在非绝对 cwd 下也安全。

调用图：调用 3 个内部函数（from_legacy_sandbox_policy_for_cwd, default_read_only_subpaths_for_writable_root, from_absolute_path）；外部调用 5 个（new, assert!, assert_eq!, current_dir, vec!）。

fn effective_runtime_roots_preserve_symlinked_paths()

作用：确认可写根是符号链接时，运行时看到的权限根仍保留这个链接路径。这样报给底层沙箱的路径和用户使用的路径一致。

数据流：输入是一个真实目录、指向它的链接目录，以及链接目录下的拒绝规则 → 计算不可读根和可写根 → 输出使用链接路径表示根、被拒绝子路径和 .codex 保护路径。

调用关系：测试 get_unreadable_roots_with_cwd 和 get_writable_roots_with_cwd，防止符号链接被规范化后破坏权限规则的匹配。

调用图：调用 2 个内部函数（restricted, from_absolute_path）；外部调用 6 个（new, assert!, assert_eq!, create_dir_all, symlink_dir, vec!）。

fn project_roots_special_path_preserves_symlinked_root()

作用：确认当当前项目根本身是符号链接时，特殊路径 project_roots 展开后仍保留链接形式。

数据流：输入是一个链接形式的当前目录，以及项目根可写、某子目录拒绝的规则 → 计算可读、不可读、可写根 → 输出都应以链接路径为准，并把 .agents、.codex 和拒绝子目录列为只读保护。

调用关系：测试特殊路径展开逻辑和符号链接处理，保证项目根规则不会偷偷变成真实目录路径。

调用图：调用 2 个内部函数（restricted, from_absolute_path）；外部调用 6 个（new, assert!, assert_eq!, create_dir_all, symlink_dir, vec!）。

fn writable_roots_preserve_symlinked_protected_subpaths()

作用：确认像 .codex 这种受保护子目录如果本身是符号链接，保护的是用户路径里的 .codex，不是它最终指向的目标目录名。

数据流：输入是一个可写根，根下 .codex 链接到 decoy-codex → 计算可写根 → 输出只读子路径是根下的 .codex，不把真实目标 decoy-codex 当成保护项。

调用关系：测试默认元数据保护与符号链接相遇时的路径表达方式，避免保护规则变成难以理解的真实路径。

调用图：调用 2 个内部函数（restricted, from_absolute_path）；外部调用 6 个（new, assert!, assert_eq!, create_dir_all, symlink_dir, vec!）。

fn writable_roots_preserve_explicit_symlinked_carveouts_under_symlinked_roots()

作用：确认在一个符号链接形式的可写根里，显式拒绝的链接子目录会按链接路径保留下来。

数据流：输入是链接根可写，以及链接根下 linked-private 拒绝 → 计算可写根 → 输出根是链接根，只读子路径是链接根下的 linked-private，不改成它指向的真实目录。

调用关系：测试显式拒绝规则进入可写根的只读 carveout（可写区域里挖掉的一块只读区）时，仍尊重用户写的路径。

调用图：调用 2 个内部函数（restricted, from_absolute_path）；外部调用 6 个（new, assert!, assert_eq!, create_dir_all, symlink_dir, vec!）。

fn writable_roots_preserve_explicit_symlinked_carveouts_that_escape_root()

作用：确认拒绝的链接子目录即使指向可写根外面，也仍按原来的链接位置作为保护洞处理。

数据流：输入是链接根可写，根内一个链接目录指向外部私密目录，并对这个链接目录设拒绝 → 计算可写根 → 输出只读子路径是根内链接路径，不把外部真实目录塞进列表。

调用关系：测试沙箱对“链接逃出根目录”的情况不改变规则语义，避免路径解析导致保护范围看起来跳到别处。

调用图：调用 2 个内部函数（restricted, from_absolute_path）；外部调用 6 个（new, assert!, assert_eq!, create_dir_all, symlink_dir, vec!）。

fn writable_roots_preserve_explicit_symlinked_carveouts_that_alias_root()

作用：确认一个拒绝子路径如果是指回根目录自身的符号链接，也会作为根下的那个别名路径被保护。

数据流：输入是可写根，以及根下 alias-root 链接回根本身并被拒绝 → 计算可写根 → 输出根为规范后的根路径，只读子路径为根下 alias-root。

调用关系：测试显式拒绝规则遇到“自我别名”符号链接时不会被消掉，避免绕过只读 carveout。

调用图：调用 2 个内部函数（restricted, from_absolute_path）；外部调用 5 个（new, assert_eq!, create_dir_all, symlink_dir, vec!）。

fn tmpdir_special_path_preserves_symlinked_tmpdir()

作用：确认临时目录 TMPDIR 如果是符号链接，特殊路径 Tmpdir 展开后也保留这个链接路径。测试用子进程运行，是为了安全地改环境变量。

数据流：第一次进入时如果没有测试环境标记，就启动当前测试二进制的子进程并设置标记 → 子进程里创建真实临时目录和链接临时目录，设置 TMPDIR 指向链接 → 根据 Tmpdir 可写和子路径拒绝规则计算权限 → 输出应使用链接形式的临时目录、被拒绝子路径和 .codex 保护路径。

调用关系：测试 FileSystemSpecialPath::Tmpdir 的展开逻辑。它通过重新执行自己来隔离 TMPDIR 环境变量，避免影响同一进程里的其他测试。

调用图：调用 2 个内部函数（restricted, from_absolute_path）；外部调用 10 个（new, assert!, assert_eq!, new, create_dir_all, symlink_dir, current_exe, set_var, var_os, vec!）。

fn resolve_access_with_cwd_uses_most_specific_entry()

作用：确认多条权限规则互相重叠时，最具体的路径规则优先。就像“整栋楼可进，但某个房间禁入，房间里的展柜又可进”这种层层覆盖。

数据流：输入是项目根可写、docs 只读、docs/private 拒绝、docs/private/public 可写的规则 → 分别查询几个路径权限 → 输出依次是写、读、拒绝、写。

调用关系：测试 resolve_access_with_cwd 的核心判定规则，很多读写检查最终都依赖这个“谁更具体谁说了算”的逻辑。

调用图：调用 2 个内部函数（restricted, resolve_path_against_base）；外部调用 3 个（new, assert_eq!, vec!）。

fn split_only_nested_carveouts_need_direct_runtime_enforcement()

作用：确认如果可写区域里挖了只读子区域，这种细规则需要运行时直接执行，不能只靠老沙箱格式表达。

数据流：输入是项目根可写但 docs 只读的规则 → 判断是否需要直接运行时强制执行 → 输出为需要；同时检查旧版工作区策略产生的元数据保护也需要直接执行。

调用关系：测试 needs_direct_runtime_enforcement，说明有些新规则太细，旧 SandboxPolicy 不能完整表达，必须由新权限系统自己守住。

调用图：调用 3 个内部函数（restricted, legacy_runtime_file_system_policy_for_cwd, resolve_path_against_base）；外部调用 4 个（new, new_workspace_write_policy, assert!, vec!）。

fn legacy_projection_runtime_enforcement_ignores_entry_order()

作用：确认权限条目的排列顺序不影响最终语义。否则同一批规则换个顺序就变成另一种权限，会很危险。

数据流：输入是旧版工作区策略转换出的规则，再把规则顺序倒过来 → 比较两者语义和是否需要直接执行 → 输出应完全一致。

调用关系：测试 is_semantically_equivalent_to 和 needs_direct_runtime_enforcement，保证判断逻辑按规则内容算，不按列表顺序碰运气。

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

fn missing_symbolic_metadata_carveouts_need_direct_runtime_enforcement()

作用：确认对还不存在的 .git、.agents 等元数据路径的符号保护，也必须走直接运行时执行。老沙箱只认识具体存在的路径，表达不了“将来出现也要保护”。

数据流：输入是旧版工作区可写策略 → 分别生成配置投影和运行时投影 → 两者判断是否需要直接执行 → 输出都应为需要。

调用关系：测试旧策略转换后的保护强度，防止因为元数据目录暂时不存在就漏掉保护。

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

fn root_write_with_read_only_child_is_not_full_disk_write()

作用：确认“根目录可写但里面有只读子目录”不能被当成真正的全盘可写。因为有例外，就不是无限制写入。

数据流：输入是文件系统根可写、某个 docs 子路径只读的规则 → 检查全盘写权限、查询 docs 权限、判断是否需直接执行、尝试转老策略 → 输出为没有全盘写、docs 只读、需要直接执行、老策略转换失败。

调用关系：测试 has_full_disk_write_access、resolve_access_with_cwd、needs_direct_runtime_enforcement 和旧桥接，保证复杂根级规则不会被简化错。

调用图：调用 2 个内部函数（restricted, resolve_path_against_base）；外部调用 4 个（new, assert!, assert_eq!, vec!）。

fn root_deny_does_not_materialize_as_unreadable_root()

作用：确认“根目录拒绝”不会被直接展开成一个不可读根列表项，否则几乎会封死整个文件系统。更具体的允许规则仍应生效。

数据流：输入是根拒绝、docs 可读的规则 → 查询 docs 权限，并计算可读根和不可读根 → 输出 docs 可读，可读根只有 docs，不可读根为空。

调用关系：测试根级拒绝和具体允许规则的配合，确保物化运行时根列表时不会把抽象根拒绝处理得过头。

调用图：调用 3 个内部函数（restricted, from_absolute_path, resolve_path_against_base）；外部调用 5 个（new, assert!, assert_eq!, canonicalize_preserving_symlinks, vec!）。

fn duplicate_root_deny_prevents_full_disk_write_access()

作用：确认同一个根目录既有写又有拒绝时，拒绝会赢，不能算作全盘写。

数据流：输入是根写入规则和根拒绝规则 → 检查全盘写权限并查询根路径权限 → 输出没有全盘写，根路径最终是拒绝。

调用关系：测试同等范围规则冲突时的优先级，配合 FileSystemAccessMode 的冲突顺序使用。

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

fn same_specificity_write_override_keeps_full_disk_write_access()

作用：确认如果一个只读子路径后来又被同样具体的可写规则覆盖，全盘写权限可以恢复成立。

数据流：输入是根可写、docs 只读、同一个 docs 又可写的规则 → 检查全盘写权限并查询 docs 权限 → 输出有全盘写，docs 最终可写。

调用关系：测试同一具体路径上后续写规则覆盖只读规则的效果，防止已经被抵消的例外还影响全盘写判断。

调用图：调用 2 个内部函数（restricted, resolve_path_against_base）；外部调用 4 个（new, assert!, assert_eq!, vec!）。

fn with_additional_readable_roots_skips_existing_effective_access()

作用：确认给策略追加可读根时，如果这个根本来就有效可读，就不会重复添加规则。

数据流：输入是项目根可读策略和同一个当前目录作为额外可读根 → 调用追加方法 → 输出策略保持不变。

调用关系：测试 with_additional_readable_roots 的去重和有效权限判断，避免生成冗余规则。

调用图：调用 2 个内部函数（restricted, from_absolute_path）；外部调用 4 个（new, assert_eq!, from_ref, vec!）。

fn with_additional_writable_roots_skips_existing_effective_access()

作用：确认给策略追加可写根时，如果这个根本来就有效可写，也不会重复添加。

数据流：输入是项目根可写策略和同一个当前目录作为额外可写根 → 调用追加方法 → 输出策略保持不变。

调用关系：测试 with_additional_writable_roots 的去重逻辑，避免相同权限被反复塞进规则列表。

调用图：调用 2 个内部函数（restricted, from_absolute_path）；外部调用 4 个（new, assert_eq!, from_ref, vec!）。

fn with_additional_writable_roots_adds_new_root()

作用：确认额外的可写根如果当前没有权限，会被真正加入策略。

数据流：输入是工作区可写策略，以及另一个 extra 目录作为额外可写根 → 调用追加方法 → 输出是在原规则后新增 extra 可写规则。

调用关系：测试 with_additional_writable_roots 在需要扩权时的正常添加路径。

调用图：调用 2 个内部函数（restricted, from_absolute_path）；外部调用 4 个（new, assert_eq!, from_ref, vec!）。

fn materialize_project_roots_with_workspace_roots_expands_exact_and_glob_entries()

作用：确认把“项目根”这种符号规则落到多个实际工作区根时，普通路径和通配符规则都会分别展开。

数据流：输入是项目根可写、项目根下 .git 只读、项目根下 **/*.env 拒绝的规则，以及两个实际根目录 → 物化项目根 → 输出为每个根各自生成可写、.git 只读和 .env 通配拒绝规则。

调用关系：测试 materialize_project_roots_with_workspace_roots，这是把抽象策略变成具体路径策略的重要步骤。

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

fn materialize_project_roots_with_cwd_expands_symbolic_glob_entries()

作用：确认只有当前目录一个项目根时，带项目根占位的通配符规则会展开到当前目录下。

数据流：输入是项目根下 **/*.env 拒绝的通配规则和当前目录 → 物化项目根 → 输出是以当前目录为 base 的绝对通配模式。

调用关系：测试 materialize_project_roots_with_cwd 对符号通配规则的展开，保证运行时匹配拿到具体路径模式。

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

fn with_additional_legacy_workspace_writable_roots_protects_metadata()

作用：确认按旧版工作区方式追加可写根时，会顺手保护里面已有的 .git 等元数据目录。

数据流：输入是项目根可写策略和一个额外目录，额外目录里已有 .git → 调用旧版追加可写根方法 → 输出新增额外目录可写规则，并新增额外目录下 .git 只读规则。

调用关系：测试 with_additional_legacy_workspace_writable_roots，保证老接口扩展工作区时也不放开仓库元数据写入。

调用图：调用 2 个内部函数（restricted, from_absolute_path）；外部调用 5 个（new, assert_eq!, create_dir_all, from_ref, vec!）。

fn file_system_access_mode_orders_by_conflict_precedence()

作用：确认权限模式的大小顺序符合冲突优先级：拒绝最高，写高于读。

数据流：输入是权限枚举的比较 → 执行断言 → 输出没有实际数据，只要比较关系不对测试就失败。

调用关系：测试 FileSystemAccessMode 的排序约定，因为多条规则冲突时会用这个顺序决定谁赢。

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

fn legacy_bridge_preserves_explicit_deny_entries()

作用：确认从旧策略重建新策略时，原来用户明确写下的拒绝规则不会丢。

数据流：输入是已有策略里拒绝 /tmp/private，以及一个旧版工作区策略 → 调用保留拒绝规则的转换方法 → 输出的新策略中仍能找到这条拒绝规则。

调用关系：测试 from_legacy_sandbox_policy_preserving_deny_entries，防止桥接旧策略时把用户的安全限制洗掉。

调用图：调用 3 个内部函数（from_legacy_sandbox_policy_preserving_deny_entries, restricted, try_from）；外部调用 4 个（new, new_workspace_write_policy, assert!, vec!）。

fn preserving_deny_entries_keeps_unrestricted_policy_enforceable()

作用：确认一个原本不限制的策略，如果要保留旧策略里的拒绝读取规则，会变成可执行的受限策略，而不是继续完全放开。

数据流：输入是带拒绝 glob 的现有受限策略，以及一个 unrestricted（不受限）替换策略 → 从现有策略保留拒绝读取限制 → 输出策略变成根可写加拒绝 glob，并继承 glob 扫描深度。

调用关系：测试 preserve_deny_read_restrictions_from，保证“放开大部分权限”时仍能保留专门的不可读文件规则。

调用图：调用 2 个内部函数（restricted, unrestricted）；外部调用 3 个（assert_eq!, unreadable_glob_entry, vec!）。

fn deny_policy(path: &Path) -> FileSystemSandboxPolicy

作用：测试辅助函数：快速做一个只拒绝某个绝对路径的文件系统策略。

数据流：输入是一个路径 → 转成绝对路径并包成一条 Deny 规则 → 输出包含这一条规则的受限策略。

调用关系：被后面多组读取拒绝测试复用，用来少写重复的策略搭建代码。

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

fn unreadable_glob_entry(pattern: String) -> FileSystemSandboxEntry

作用：测试辅助函数：创建一条按通配符拒绝读取的规则。

数据流：输入是 glob 模式字符串 → 放进 FileSystemPath::GlobPattern，权限设为 Deny → 输出一条沙箱规则。

调用关系：被多个 glob 相关测试和策略构造辅助函数使用，用来统一创建不可读通配规则。

fn default_policy_with_unreadable_glob(pattern: String) -> FileSystemSandboxPolicy

作用：测试辅助函数：在默认策略上加一条不可读通配规则。

数据流：输入是 glob 模式字符串 → 创建默认文件系统策略，把拒绝 glob 规则追加进去 → 输出这个新策略。

调用关系：被通配符匹配测试复用，用来专注测试匹配行为，而不是每个测试都手写策略。

调用图：调用 1 个内部函数（default）；外部调用 1 个（unreadable_glob_entry）。

fn is_read_denied(
        path: &Path,
        file_system_sandbox_policy: &FileSystemSandboxPolicy,
        cwd: &Path,
    ) -> bool

作用：测试辅助函数：问某个路径在某个策略和当前目录下是否被禁止读取。

数据流：输入是待检查路径、文件系统策略和当前目录 → 创建 ReadDenyMatcher（读取拒绝匹配器，用来判断路径是否命中禁止读取规则）并询问路径 → 输出布尔值；如果没有匹配器，就返回 false。

调用关系：被读取拒绝相关测试反复调用。它把测试和底层 ReadDenyMatcher::new、matcher.is_read_denied 连接起来。

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

fn exact_path_and_descendants_are_denied()

作用：确认拒绝一个目录时，这个目录本身和它下面的文件都会被拒绝读取。

数据流：输入是临时目录里的 denied 目录和其中的文件 → 建立拒绝该目录的策略 → 输出判断结果：目录和子文件被拒绝，旁边的其他文件不被拒绝。

调用关系：测试 ReadDenyMatcher 对精确路径和后代路径的基本行为。

调用图：外部调用 5 个（new, assert!, deny_policy, create_dir_all, write）。

fn canonical_target_matches_denied_symlink_alias()

作用：确认即使通过符号链接别名访问被拒绝目录里的文件，也会被识别并拒绝读取。

数据流：输入是真实目录、指向它的链接目录、真实目录下的秘密文件 → 策略拒绝真实目录 → 用链接路径检查秘密文件 → 输出为读取被拒绝。

调用关系：测试读取拒绝匹配器会考虑路径的真实目标，防止用符号链接绕开拒绝规则。

调用图：外部调用 6 个（new, assert!, deny_policy, symlink_dir, create_dir_all, write）。

fn literal_patterns_and_globs_are_denied()

作用：确认普通拒绝路径和 glob 通配拒绝规则可以同时生效。

数据流：输入是一个私有目录和一个文本文件 → 策略拒绝私有目录，并追加匹配所有 txt 的通配拒绝 → 输出私有目录和文本文件都被拒绝读取。

调用关系：测试 ReadDenyMatcher 同时处理路径规则和通配规则的能力。

调用图：外部调用 7 个（new, assert!, format!, deny_policy, unreadable_glob_entry, create_dir_all, write）。

fn glob_patterns_deny_matching_paths()

作用：确认简单 glob 通配模式能拒绝匹配到的文件。

数据流：输入是路径 private/secret1.txt 和模式 private/secret?.txt → 创建带该模式的策略并检查文件 → 输出为读取被拒绝。

调用关系：测试 glob 匹配里 ? 这类单字符通配的基本效果。

调用图：外部调用 6 个（new, assert!, format!, default_policy_with_unreadable_glob, create_dir_all, write）。

fn glob_patterns_do_not_cross_path_separators()

作用：确认普通 glob 的 * 不会跨过目录分隔符。也就是说它只匹配一层路径，不会一下钻进更深目录。

数据流：输入是同层文件、嵌套文件、长度不匹配文件和字母不匹配文件，以及模式 */file[0-9]?.txt → 检查这些路径 → 输出只有同层且格式匹配的文件被拒绝。

调用关系：测试 glob 语法细节，防止拒绝范围比用户写的模式更宽。

调用图：外部调用 6 个（new, assert!, format!, default_policy_with_unreadable_glob, create_dir_all, write）。

fn globstar_patterns_deny_root_and_nested_matches()

作用：确认 ** 这种 globstar 通配能匹配根目录下和更深目录里的文件。

数据流：输入是根下 .env、子目录里的 .env 和普通 notes 文件，以及模式 **/*.env → 检查这些路径 → 输出两个 .env 被拒绝，普通文件不被拒绝。

调用关系：测试递归通配规则，常用于保护所有层级的环境变量文件。

调用图：外部调用 6 个（new, assert!, format!, default_policy_with_unreadable_glob, create_dir_all, write）。

fn unclosed_character_classes_match_literal_brackets()

作用：确认不完整的字符类写法，比如单独一个 [，会按普通字符处理，而不是导致匹配器崩掉或乱匹配。

数据流：输入是名为 [ 的文件、普通 notes 文件，以及模式末尾也是 [ → 检查读取拒绝 → 输出只有 [ 文件被拒绝。

调用关系：测试 glob 解析的容错行为，保证用户写了特殊字符也能得到可预期的安全结果。

调用图：外部调用 5 个（new, assert!, format!, default_policy_with_unreadable_glob, write）。

fn requires_escalated_permissions(self) -> bool

作用：判断这次请求是不是明确要求“提权”，也就是要比默认沙箱更大的权限。调用方用它来决定是否需要走更严格的批准流程。

数据流：输入是一个沙箱权限选项 → 它只检查这个选项是不是 RequireEscalated → 输出 true 或 false，不改任何数据。

调用关系：它被执行环境、网络权限和首次尝试沙箱覆盖等逻辑调用，用来把“是否要提权”这个判断集中到一个地方。

调用图：被 4 处调用（exec_env_for_sandbox_permissions, managed_network_for_sandbox_permissions, sandbox_override_for_first_attempt, sandbox_permissions_preserving_denied_reads）；外部调用 1 个（matches!）。

fn requests_sandbox_override(self) -> bool

作用：判断请求有没有想改变默认沙箱设置。只要不是 UseDefault，就说明它提出了某种覆盖要求。

数据流：输入是当前权限选项 → 它检查是否不是默认值 → 返回一个布尔值，表示是否请求覆盖默认沙箱。

调用关系：命令事件和 shell 事件生成时会用它标记这次执行是否带有特殊权限意图，方便后续审批和记录。

调用图：被 3 处调用（exec_command_event, shell_event_with_prefix_rule, exec_command_event）；外部调用 1 个（matches!）。

fn uses_additional_permissions(self) -> bool

作用：判断这次请求是不是要使用额外授予的权限，而不是直接完全提权。它区分“加一点权限”和“全量提权”。

数据流：输入是沙箱权限选项 → 检查是否为 WithAdditionalPermissions → 输出 true 或 false。

调用关系：授予回合权限和隐式权限计算会调用它，用来决定是否把额外权限合并进当前执行。

调用图：被 2 处调用（apply_granted_turn_permissions, implicit_granted_permissions）；外部调用 1 个（matches!）。

fn try_from(value: FileSystemPermissions<PathUri>) -> Result<Self, Self::Error>

作用：把用 URI 表示路径的文件权限，转换成真正的绝对本地路径版本。这样运行时就能安全地按本机路径检查访问。

数据流：输入是一组 PathUri 形式的文件权限 → 逐条把权限里的路径转成 AbsolutePathBuf → 成功返回新权限，失败返回输入输出错误。

调用关系：这是路径格式转换的一道关口，常用于从外部协议数据进入本地运行时之前。

fn default() -> Self

作用：生成一个空的文件系统权限设置。意思是没有额外允许的路径，也没有通配符扫描深度限制。

数据流：没有输入 → 创建 entries 为空、glob_scan_max_depth 为空的对象 → 返回这个默认权限对象。

调用关系：测试和权限归一化会用它作为“什么都没配置”的基准。

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

fn is_empty(&self) -> bool

作用：判断文件系统权限里有没有任何路径规则。外部可以用它快速知道这份权限是不是空壳。

数据流：输入是权限对象本身 → 查看 entries 列表是否为空 → 返回 true 或 false。

调用关系：它是权限对象上的小检查器，常被更大的配置判断逻辑使用。

fn from_read_write_roots(
        read: Option<Vec<PathType>>,
        write: Option<Vec<PathType>>,
    ) -> Self

作用：把老式的“可读目录列表”和“可写目录列表”变成新的统一权限条目。这样老配置还能继续被新系统理解。

数据流：输入是可选的读路径列表和写路径列表 → 每个读路径变成 Read 条目，每个写路径变成 Write 条目 → 返回新的 FileSystemPermissions。

调用关系：反序列化旧格式、测试权限授予、远程执行授权等场景会用它把老数据接入新权限模型。

调用图：被 39 处调用（request_permissions_response_materializes_session_cwd_grants_before_recording, write_permissions_for_paths, file_system_permissions, file_system_sandbox_context_uses_active_attempt, preapproved_additional_permissions_escalate_intercepted_exec, shell_request_escalation_execution_is_explicit, extension_tool_uses_granted_turn_permissions, remote_request_permissions_grant_unblocks_later_remote_exec, normalized_directory_write_permissions, partial_request_permissions_grants_do_not_preapprove_new_permissions (+15 more)）；外部调用 1 个（new）。

fn explicit_path_entries(&self) -> impl Iterator<Item = (&PathType, FileSystemAccessMode)>

作用：只拿出明确写了具体路径的权限条目，忽略通配符和特殊路径。适合那些只关心“某个真实目录”的地方。

数据流：输入是权限对象 → 遍历 entries → 对 Path 类型条目输出路径和访问模式，其他类型跳过。

调用关系：它像一个过滤器，把复杂权限列表中最直接的路径规则交给调用方使用。

fn legacy_read_write_roots(&self) -> Option<LegacyReadWriteRoots<PathType>>

作用：尝试把新格式权限还原成老式 read/write 根目录格式。只有足够简单、老格式能表达时才会成功。

数据流：输入是新权限对象 → 先调用 as_legacy_permissions 尝试转换 → 成功时返回读列表和写列表，失败返回 None。

调用关系：它依赖 as_legacy_permissions 做实际判断，主要服务于需要兼容旧接口的地方。

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

fn as_legacy_permissions(&self) -> Option<LegacyFileSystemPermissions<PathType>>

作用：检查一份新文件权限能不能安全地用老格式表示。遇到通配符、拒绝规则或扫描深度这类老格式不懂的内容，就拒绝转换。

数据流：输入是新权限对象 → 检查是否没有 glob_scan_max_depth，且每条都是普通路径的读或写 → 输出老格式权限；不兼容则输出 None。

调用关系：legacy_read_write_roots 和 serialize 都调用它，保证只有不丢信息时才写成老格式。

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

fn serialize(&self, serializer: S) -> Result<S::Ok, S::Error>

作用：把文件权限写成 JSON 时，优先用旧系统也认识的简单格式；如果表达不了，就用新格式。这样兼顾兼容和完整性。

数据流：输入是权限对象和序列化器 → 先尝试 as_legacy_permissions → 能转就写旧格式，不能转就写 canonical 新格式。

调用关系：它在保存配置、发协议数据时自动工作，是新旧权限格式之间的出口适配器。

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

fn deserialize(deserializer: D) -> Result<Self, D::Error>

作用：读取 JSON 里的文件权限，既能读新格式，也能读老格式。这样升级后不会把旧配置读坏。

数据流：输入是 JSON 反序列化器 → 解析成新格式或老格式枚举 → 新格式直接返回，老格式通过 from_read_write_roots 转成新对象。

调用关系：它和 serialize 配套，负责权限数据进入系统时的兼容处理。

调用图：外部调用 2 个（from_read_write_roots, deserialize）。

fn is_empty(&self) -> bool

作用：判断网络权限有没有被明确设置。enabled 为空就表示这块没有配置。

数据流：输入是网络权限对象 → 查看 enabled 是否为 None → 返回是否为空。

调用关系：它帮助上层判断额外权限配置里是否真的包含网络设置。

fn is_empty(&self) -> bool

作用：判断额外权限配置是不是完全没写网络和文件系统部分。注意：只要字段存在，即使里面是空的，也不算完全空。

数据流：输入是额外权限配置 → 检查 network 和 file_system 两个字段是否都为 None → 返回 true 或 false。

调用关系：权限合并和配置清理会用它区分“没提供配置”和“提供了一个空配置”。

fn from_legacy_sandbox_policy(sandbox_policy: &SandboxPolicy) -> Self

作用：把老的沙箱策略翻译成新的“由谁执行沙箱”分类：关闭、外部执行、系统自己管理。它是旧权限模型迁移到新模型的入口之一。

数据流：输入是旧 SandboxPolicy → 根据策略类型映射到 Disabled、External 或 Managed → 返回新的 enforcement 值。

调用关系：配置应用、旧策略设置、执行一次性命令等流程都用它保持旧策略语义不变。

调用图：被 12 处调用（exec_one_off_command_inner, can_set_legacy_sandbox_policy, set_legacy_sandbox_policy, apply, session_configuration_apply_permission_profile_preserves_existing_deny_read_entries, session_configuration_apply_preserves_profile_file_system_policy_on_cwd_only_update, session_configuration_apply_retargets_legacy_workspace_root_on_cwd_update, build_agent_spawn_config_uses_turn_context_values, spawn_agent_reapplies_runtime_sandbox_after_role_config, from_legacy_sandbox_policy (+2 more)）。

fn from(value: ManagedFileSystemPermissions<AbsolutePathBuf>) -> Self

作用：把本地绝对路径版的受管文件权限转换成 URI 路径版，方便通过协议发送或存储。

数据流：输入是 AbsolutePathBuf 路径的 ManagedFileSystemPermissions → Restricted 时逐条路径转为 PathUri，Unrestricted 时保持不受限 → 返回转换后的对象。

调用关系：它承担本地运行时模型到协议模型的路径翻译。

fn try_from(value: ManagedFileSystemPermissions<PathUri>) -> Result<Self, Self::Error>

作用：把 URI 路径版的受管文件权限转换成本地绝对路径版。转换可能失败，所以返回结果类型。

数据流：输入是 PathUri 版本的权限 → Restricted 时逐条尝试转成本地绝对路径，Unrestricted 直接保留 → 成功返回新对象，失败返回 IO 错误。

调用关系：它通常出现在协议数据进入本地执行前，确保路径能被本机识别。

fn from_sandbox_policy(file_system_sandbox_policy: &FileSystemSandboxPolicy) -> Self

作用：从运行时的文件沙箱策略生成权限配置里的文件系统部分。它把底层策略包装成更适合配置和传输的模型。

数据流：输入是 FileSystemSandboxPolicy → Restricted 复制规则和扫描深度，Unrestricted 转为不受限，ExternalSandbox 被认为不该走这里 → 返回 ManagedFileSystemPermissions。

调用关系：PermissionProfile 构造读写预设、运行时权限转换时都会调用它。

调用图：被 4 处调用（from_runtime_permissions_with_enforcement, materialize_project_roots_with_workspace_roots, read_only, workspace_write_with）；外部调用 1 个（unreachable!）。

fn to_sandbox_policy(&self) -> FileSystemSandboxPolicy

作用：把权限配置里的文件系统部分还原成运行时真正执行的沙箱策略。

数据流：输入是 ManagedFileSystemPermissions → Restricted 转成带规则的 FileSystemSandboxPolicy，Unrestricted 转成不限制策略 → 返回运行时策略。

调用关系：PermissionProfile 输出运行时权限、转换旧策略时依赖它。

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

fn try_from(value: PermissionProfile<PathUri>) -> Result<Self, Self::Error>

作用：把 URI 路径版的权限档案转换成本地绝对路径版。这样收到的配置可以进入本地运行时。

数据流：输入是 PermissionProfile<PathUri> → Managed 时转换文件系统路径，Disabled 和 External 原样保留网络信息 → 返回本地路径版或错误。

调用关系：它是权限档案跨协议边界后的落地转换。

fn new(id: impl Into<String>) -> Self

作用：创建一个当前启用的权限档案引用，只填档案 id，不继承其他档案。

数据流：输入是可转成字符串的 id → 转成 String，extends 设为 None → 返回 ActivePermissionProfile。

调用关系：read_only 等便捷构造会用它创建内置权限档案引用。

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

fn read_only() -> Self

作用：创建一个指向内置只读权限档案的当前档案引用。

数据流：没有输入 → 使用内置只读档案名调用 new → 返回 ActivePermissionProfile。

调用关系：它是选择只读内置权限档案的快捷方式。

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

fn default() -> Self

作用：给权限档案一个保守默认值：文件系统受限且没有允许条目，网络也受限。默认情况下先保护起来。

数据流：没有输入 → 创建 Managed 档案，文件 entries 为空，网络 Restricted → 返回默认权限档案。

调用关系：很多工具列表和缓存相关测试会用到它，表示没有特别放权的起点。

调用图：被 14 处调用（list_all_tools_accepts_canonical_namespaced_tool_names, list_all_tools_adds_server_metadata_to_cached_tools, list_all_tools_applies_legacy_mcp_prefix_by_default, list_all_tools_blocks_while_client_is_pending_without_cached_tool_info_snapshot, list_all_tools_does_not_block_when_cached_tool_info_snapshot_is_empty, list_all_tools_uses_cached_tool_info_snapshot_when_client_startup_fails, list_all_tools_uses_cached_tool_info_snapshot_while_client_is_pending, list_available_server_infos_uses_cache_while_client_is_pending, no_local_runtime_fails_local_stdio_but_keeps_local_http_server, shutdown_cancels_pending_tool_listing (+4 more)）；外部调用 1 个（new）。

fn read_only() -> Self

作用：生成内置“只读”权限档案。它允许读，但不允许随便写，网络仍受限。

数据流：没有输入 → 从 FileSystemSandboxPolicy::read_only 得到底层文件策略 → 转成受管文件权限并配上受限网络 → 返回 Managed 权限档案。

调用关系：线程恢复、Windows 沙箱请求、默认权限和配置推导等场景会用它。

调用图：调用 2 个内部函数（from_sandbox_policy, read_only）；被 153 处调用（rollback_response_rebuilds_pathless_thread_from_stored_history, cancellation_expiration_keeps_process_alive_until_terminated, timeout_or_cancellation_reports_cancellation_without_timeout_exit_code, windows_sandbox_exec_request, requested_permissions_trust_project_uses_permission_profile_intent, summary_from_stored_thread_preserves_millisecond_precision, default, try_from, derive_permission_profile, load_config_with_layer_stack (+15 more)）。

fn workspace_write() -> Self

作用：生成内置“工作区可写”权限档案。它通常允许在项目工作区内写文件，但网络仍默认受限。

数据流：没有输入 → 调用 workspace_write_with，传空的额外可写根、受限网络和默认临时目录选项 → 返回权限档案。

调用关系：权限推导、调试沙箱和配置测试会用它作为常见开发模式。

调用图：被 77 处调用（requested_permissions_trust_project_uses_permission_profile_intent, debug_sandbox_honors_explicit_builtin_permission_profile, derive_permission_profile, derive_sandbox_policy_preserves_windows_downgrade_for_unsupported_fallback, permission_snapshot_setter_preserves_permission_constraints, managed_allowed_domains_only_disables_default_mode_allowlist_expansion, managed_allowed_domains_only_ignores_user_allowlist_and_hard_denies_misses, managed_allowed_domains_only_without_managed_allowlist_blocks_all_user_domains, requirements_allowed_domains_do_not_override_user_denies_for_same_pattern, requirements_allowlist_expansion_keeps_user_entries_mutable (+15 more)）；外部调用 1 个（workspace_write_with）。

fn workspace_write_with(
        writable_roots: &[AbsolutePathBuf],
        network: NetworkSandboxPolicy,
        exclude_tmpdir_env_var: bool,
        exclude_slash_tmp: bool,
    ) -> Self

作用：生成一个可定制的工作区可写权限档案，可以指定哪些根目录可写、网络策略以及是否排除临时目录。

数据流：输入是可写根列表、网络策略和两个临时目录开关 → 构造底层 workspace_write 文件沙箱策略 → 转成 Managed 权限档案。

调用关系：配置解析、远程沙箱匹配和权限推导会调用它创建具体工作区权限。

调用图：调用 2 个内部函数（from_sandbox_policy, workspace_write）；被 33 处调用（deserialize_allowed_sandbox_modes, remote_sandbox_config_first_match_overrides_top_level, derive_permission_profile, builtin_permission_profile, windows_restricted_token_allows_workspace_write_profiles, granular_sandbox_approval_false_rejects_out_of_root_patch, granular_with_all_flags_true_matches_on_request_for_out_of_root_patch, missing_project_dot_codex_config_requires_approval, restrictive_workspace_write_profile, restrictive_workspace_write_profile (+15 more)）。

fn materialize_project_roots_with_workspace_roots(
        self,
        workspace_roots: &[AbsolutePathBuf],
    ) -> Self

作用：把权限档案里的“项目根”占位含义落到实际工作区路径上。这样抽象规则能变成具体路径规则。

数据流：输入是权限档案和工作区根目录列表 → Managed 时把文件策略 materialize 后再包回档案，Disabled 和 External 原样返回 → 输出新权限档案。

调用关系：它在项目路径确定后使用，连接配置阶段的抽象权限和运行时的真实路径。

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

fn from_runtime_permissions(
        file_system_sandbox_policy: &FileSystemSandboxPolicy,
        network_sandbox_policy: NetworkSandboxPolicy,
    ) -> Self

作用：从运行时已经有的文件沙箱策略和网络策略，推导出一个权限档案。它自动判断这是系统管理沙箱还是外部沙箱。

数据流：输入是文件沙箱策略和网络策略 → 根据文件策略 kind 选择 enforcement → 调用 from_runtime_permissions_with_enforcement → 返回 PermissionProfile。

调用关系：配置加载和权限意图保存会用它把底层运行时状态变成可展示、可存储的档案。

调用图：被 65 处调用（requested_permissions_trust_project_uses_permission_profile_intent, load_config_with_layer_stack, permission_profile_override_keeps_memories_root_out_of_legacy_projection, workspace_write_permission_profile_with_private_denials, managed_cwd_write_profile_has_filesystem_restrictions, managed_full_disk_write_profile_has_no_filesystem_restrictions, managed_unresolvable_write_profile_has_filesystem_restrictions, writable_windows_policy_without_sandbox_backend_still_requires_approval, windows_elevated_allows_split_restricted_read_policies, windows_elevated_rejects_reopened_writable_descendants (+15 more)）；外部调用 1 个（from_runtime_permissions_with_enforcement）。

fn from_runtime_permissions_with_enforcement(
        enforcement: SandboxEnforcement,
        file_system_sandbox_policy: &FileSystemSandboxPolicy,
        network_sandbox_policy: NetworkSandboxPolic

作用：按明确的执行方式，把运行时权限转换成权限档案。它能正确区分外部沙箱、完全关闭沙箱和受管沙箱。

数据流：输入是 enforcement、文件策略、网络策略 → ExternalSandbox 生成 External；不受限且 enforcement 为 Disabled 生成 Disabled；其他文件策略生成 Managed → 返回档案。

调用关系：旧策略转换、配置应用、权限投影设置等核心流程都用它，避免权限语义在转换中丢失。

调用图：调用 1 个内部函数（from_sandbox_policy）；被 23 处调用（managed_full_disk_with_restricted_network_reports_external_sandbox, exec_one_off_command_inner, load_config_with_layer_stack, can_set_legacy_sandbox_policy, set_legacy_sandbox_policy, permission_profile_override_preserves_split_write_roots, apply, set_permission_profile_projection, record_context_updates_and_set_reference_context_item_persists_split_file_system_policy_to_rollout, session_configuration_apply_permission_profile_preserves_existing_deny_read_entries (+13 more)）。

fn from_legacy_sandbox_policy(sandbox_policy: &SandboxPolicy) -> Self

作用：把老的 SandboxPolicy 完整转换成新的 PermissionProfile。它同时处理文件、网络和沙箱执行方式。

数据流：输入是旧沙箱策略 → 分别转 enforcement、文件策略、网络策略 → 调用 from_runtime_permissions_with_enforcement → 返回新权限档案。

调用关系：旧策略回归测试和兼容层用它确保老配置还能得到同样的行为。

调用图：调用 3 个内部函数（from_legacy_sandbox_policy, from, from）；被 2 处调用（permission_profile_round_trip_preserves_disabled_sandbox, permission_profile_round_trip_preserves_external_sandbox）；外部调用 1 个（from_runtime_permissions_with_enforcement）。

fn from_legacy_sandbox_policy_for_cwd(sandbox_policy: &SandboxPolicy, cwd: &Path) -> Self

作用：按当前工作目录把旧沙箱策略转换成新权限档案。某些旧策略里的工作区含义需要依赖 cwd 才能落成具体路径。

数据流：输入是旧 SandboxPolicy 和 cwd → 生成 enforcement、按 cwd 转文件策略、转网络策略 → 返回 PermissionProfile。

调用关系：提交回合、线程设置恢复和界面展示权限档案时会用它处理旧数据。

调用图：调用 3 个内部函数（from_legacy_sandbox_policy, from_legacy_sandbox_policy_for_cwd, from）；被 6 处调用（submit_turn_with_policies, deserialize, apply_thread_settings_to_session, display_permission_profile_from_thread_response, thread_session_state_from_thread_resume_response, apply_thread_settings）；外部调用 1 个（from_runtime_permissions_with_enforcement）。

fn enforcement(&self) -> SandboxEnforcement

作用：告诉调用方这个权限档案的沙箱到底是系统管理、完全关闭，还是交给外部沙箱。

数据流：输入是权限档案 → 根据枚举分支返回 Managed、Disabled 或 External → 不修改对象。

调用关系：权限投影、文件系统沙箱上下文和有效权限计算会用它决定后续执行路径。

调用图：被 4 处调用（set_permission_profile_projection, file_system_sandbox_context, with_managed_mitm_ca_readable_root, effective_permission_profile）。

fn file_system_sandbox_policy(&self) -> FileSystemSandboxPolicy

作用：从权限档案中取出运行时需要的文件系统沙箱策略。不同档案类型会映射成受限、不受限或外部沙箱。

数据流：输入是 PermissionProfile → Managed 转出内部文件策略，Disabled 返回不受限，External 返回外部沙箱策略 → 输出 FileSystemSandboxPolicy。

调用关系：运行时执行、沙箱模式判断和权限标签生成都会调用它。

调用图：调用 2 个内部函数（external_sandbox, unrestricted）；被 13 处调用（sandbox_policy_mode, permission_profile_trusts_project, sandbox_mode_requirement_for_permission_profile, profile_has_managed_filesystem_restrictions, permission_profile_policy_tag, file_system_sandbox_policy, sandbox_mode_from_permission_profile, from_permission_profile, to_runtime_permissions, add_dir_warning_message (+3 more)）。

fn network_sandbox_policy(&self) -> NetworkSandboxPolicy

作用：从权限档案中取出网络沙箱策略。完全关闭沙箱时网络被视为可用。

数据流：输入是 PermissionProfile → Managed 或 External 返回保存的 network，Disabled 返回 Enabled → 输出 NetworkSandboxPolicy。

调用关系：网络代理、Linux 沙箱启动和运行时权限转换会用它。

调用图：被 11 处调用（sandbox_policy_mode, network_proxy_spec_for_active_permission_profile, spawn_command_under_linux_sandbox, network_sandbox_policy, sandbox_mode_from_permission_profile, from_permission_profile, to_runtime_permissions, sandbox_mode_from_permission_profile, preset_matches_current, legacy_compatible_permission_profile (+1 more)）。

fn to_legacy_sandbox_policy(&self, cwd: &Path) -> io::Result<SandboxPolicy>

作用：把新的权限档案尽量转换回旧 SandboxPolicy。这样旧接口、旧记录和旧展示还能继续工作。

数据流：输入是权限档案和当前目录 → Managed 通过文件策略转旧策略，Disabled 转 DangerFullAccess，External 转 ExternalSandbox 并带网络状态 → 返回旧策略或 IO 错误。

调用关系：回合权限字段、兼容权限档案和权限摘要会调用它。

调用图：被 4 处调用（turn_permission_fields, compatibility_sandbox_policy_for_permission_profile, legacy_compatible_permission_profile, summarize_permission_profile）。

fn to_runtime_permissions(&self) -> (FileSystemSandboxPolicy, NetworkSandboxPolicy)

作用：把权限档案拆成运行时真正使用的文件系统策略和网络策略。

数据流：输入是 PermissionProfile → 分别调用 file_system_sandbox_policy 和 network_sandbox_policy → 返回二元组。

调用关系：构建执行请求、沙箱上下文和当前线程权限应用会用它。

调用图：调用 2 个内部函数（file_system_sandbox_policy, network_sandbox_policy）；被 12 处调用（build_exec_request, resolve_windows_elevated_filesystem_overrides, resolve_windows_restricted_token_filesystem_overrides, new, set_permission_profile_projection, file_system_sandbox_context, sandbox_exec_request, apply_permission_profile_to_current_thread, should_warn_about_system_bwrap, with_managed_mitm_ca_readable_root (+2 more)）。

fn from(value: LegacyPermissionProfile<PathType>) -> Self

作用：把旧版权限档案结构转换成新版 PermissionProfile。缺少文件权限时按空的受限文件权限处理。

数据流：输入是 LegacyPermissionProfile → 文件部分存在就取规则，不存在就建空受限规则；网络 enabled 为 true 才放开网络 → 返回 Managed 档案。

调用关系：PermissionProfile::deserialize 读到旧形状数据时会交给它完成升级。

fn deserialize(deserializer: D) -> Result<Self, D::Error>

作用：读取权限档案 JSON，既支持带标签的新格式，也支持旧 rollout 形状。这样数据格式升级不会破坏老记录。

数据流：输入是反序列化器 → 先解析成 Tagged 或 Legacy → 分别转换成 PermissionProfile → 返回结果。

调用关系：它是权限档案从磁盘或网络进入系统时的兼容入口。

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

fn from(value: NetworkSandboxPolicy) -> Self

作用：把运行时网络沙箱策略转成可序列化的网络权限对象。

数据流：输入是 NetworkSandboxPolicy → 调用 is_enabled 得到是否允许联网 → 放进 enabled 字段并返回。

调用关系：权限策略需要写入配置或协议数据时会用到这类转换。

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

fn from(value: &FileSystemSandboxPolicy) -> Self

作用：把运行时文件沙箱策略转成可序列化的文件权限对象。不受限或外部沙箱会被表示成根目录可写。

数据流：输入是 FileSystemSandboxPolicy 引用 → Restricted 复制规则；Unrestricted 或 ExternalSandbox 生成 Root 写权限条目 → 带上扫描深度后返回。

调用关系：它服务于运行时权限向协议权限的投影。

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

fn from(value: &FileSystemPermissions) -> Self

作用：把可序列化的文件权限对象转回运行时的受限文件沙箱策略。

数据流：输入是 FileSystemPermissions → 用 entries 创建 restricted 策略 → 把 glob_scan_max_depth 转成 usize 写回 → 返回 FileSystemSandboxPolicy。

调用关系：当配置权限需要真正执行时，会通过它落到运行时策略。

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

fn plaintext_agent_message_content(content: &[AgentMessageInputContent]) -> Option<String>

作用：把代理消息里的纯文本片段合并成一段文字。如果里面夹了加密内容，就拒绝返回，避免把不该看的内容当明文处理。

数据流：输入是一组 AgentMessageInputContent → 收集 InputText，遇到 EncryptedContent 立刻返回 None → 文本用换行拼接，空白则返回 None。

调用关系：收集守护进程转录、构建当前线程内容和推送可见消息时会用它提取可展示文本。

调用图：被 3 处调用（collect_guardian_transcript_entries, build_current_thread_section, push_visible_message）；外部调用 2 个（with_capacity, len）。

fn is_user_message(&self) -> bool

作用：判断一个响应条目是不是用户消息。它只看类型是不是 Message 且 role 等于 user。

数据流：输入是 ResponseItem → 匹配消息类型和角色 → 返回 true 或 false。

调用关系：这是消息处理中的小分类器，帮助上层区分用户发言和其他系统事件。

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

fn turn_id(&self) -> Option<&str>

作用：读取响应条目上的回合编号，并且过滤掉空字符串。回合编号用来把消息归到某一次对话回合。

数据流：输入是 ResponseItem → 调用 metadata 取元数据 → 取 turn_id，若为空则丢弃 → 返回 Option<&str>。

调用关系：stamp_turn_id_if_missing 会先调用它，避免覆盖已有的有效回合编号。

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

fn stamp_turn_id_if_missing(&mut self, turn_id: &str)

作用：给响应条目补上回合编号，但只在编号非空且原本没有编号时补。它不会覆盖已有编号。

数据流：输入是可变 ResponseItem 和 turn_id 字符串 → 若输入为空或已有 turn_id 就退出 → 找到可写元数据槽并写入 turn_id。

调用关系：它依赖 turn_id 和 metadata_mut，在整理历史消息或补全回合信息时使用。

调用图：调用 2 个内部函数（metadata_mut, turn_id）。

fn clear_metadata(&mut self)

作用：清掉响应条目上的元数据。适合在发给不需要内部信息的一方之前做脱敏。

数据流：输入是可变 ResponseItem → 找到元数据槽 → 把它设为 None；没有元数据槽则不做事。

调用关系：它通过 metadata_mut 统一处理各种 ResponseItem 分支。

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

fn metadata(&self) -> Option<&ResponseItemMetadata>

作用：从各种响应条目里统一读取元数据。不同条目字段不同，这个函数把读取方式统一起来。

数据流：输入是 ResponseItem → 对支持 metadata 的分支返回 metadata.as_ref()，Other 返回 None → 不修改数据。

调用关系：turn_id 调用它读取回合编号，避免每个调用方都写一长串匹配。

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

fn metadata_mut(&mut self) -> Option<&mut Option<ResponseItemMetadata>>

作用：从各种响应条目里统一拿到可修改的元数据槽。这样写元数据和清元数据不用关心具体条目类型。

数据流：输入是可变 ResponseItem → 支持 metadata 的分支返回可变 Option 引用，Other 返回 None → 调用方可据此修改。

调用关系：stamp_turn_id_if_missing 和 clear_metadata 都依赖它完成元数据写入或清除。

调用图：被 2 处调用（clear_metadata, stamp_turn_id_if_missing）。

fn default() -> Self

作用：提供默认基础指令文本。基础指令就是系统给模型的默认行为说明。

数据流：没有输入 → 把 BASE_INSTRUCTIONS_DEFAULT 转成 String → 返回 BaseInstructions。

调用关系：线程持久化、摘要和默认配置相关流程会用它保证没有自定义指令时仍有基础指令。

调用图：被 12 处调用（get_conversation_summary_by_thread_id_reads_pathless_store_thread, thread_delete_with_non_local_thread_store_does_not_create_local_persistence, seed_pathless_store_thread, thread_unarchive_preserves_pathless_store_metadata, default, attach_thread_persistence, shutdown_complete_does_not_append_to_thread_store_after_shutdown, find_locates_rollout_file_written_by_recorder, persist_reports_filesystem_error_and_retries_buffered_items, recorder_materializes_on_flush_with_pending_items (+2 more)）。

fn format_allow_prefixes(prefixes: Vec<Vec<String>>) -> Option<String>

作用：把允许执行的命令前缀列表整理成给人看的文本，并限制数量和长度，防止输出太长。

数据流：输入是多组命令 token 前缀 → 先排序，再最多取 MAX_RENDERED_PREFIXES 条，每条渲染成列表行 → 如超数量或超字节长度就截断并加省略标记。

调用关系：执行策略变更消息和批准命令前缀展示会用它，把机器规则变成用户能读的清单。

调用图：被 5 处调用（record_execpolicy_amendment_message, approved_command_prefixes_text, format_allow_prefixes_limits_output, render_command_prefix_list_limits_output_to_max_prefixes, render_command_prefix_list_sorts_by_len_then_total_len_then_alphabetical）；外部调用 1 个（format!）。

fn prefix_combined_str_len(prefix: &[String]) -> usize

作用：计算一个命令前缀里所有字符串 token 的总长度。它用于排序时比较前缀复杂度。

数据流：输入是一组字符串 → 把每个字符串长度相加 → 返回总长度。

调用关系：format_allow_prefixes 在排序规则里调用它，让短而简单的前缀先显示。

fn render_command_prefix(prefix: &[String]) -> String

作用：把一组命令 token 渲染成像 JSON 数组一样的可读文本。这样空格、引号等字符也能看清楚。

数据流：输入是字符串 token 列表 → 每个 token 尽量用 JSON 字符串格式转义 → 用逗号拼接并加方括号 → 返回文本。

调用关系：format_allow_prefixes 用它把每条允许前缀变成一行展示内容。

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

fn should_serialize_reasoning_content(content: &Option<Vec<ReasoningItemContent>>) -> bool

作用：决定推理内容字段是否应该被序列化。只要里面包含普通推理文本，就不序列化这个字段。

数据流：输入是可选的推理内容列表 → None 返回 false；Some 时检查是否没有 ReasoningText → 返回是否应该写出。

调用关系：它通常作为序列化条件使用，控制哪些推理内容能进入 JSON。

fn local_image_error_placeholder(
    path: &std::path::Path,
    error: impl std::fmt::Display,
) -> ContentItem

作用：当本地图片读取或处理失败时，生成一段普通文本作为占位说明。这样用户和模型都能知道图片没附上，而不是静默丢失。

数据流：输入是图片路径和错误 → 拼出说明文字 → 返回 ContentItem::InputText。

调用关系：本地图片准备失败时，local_image_content_items_with_label_number 和用户输入转换会使用它。

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

fn image_open_tag_text() -> String

作用：返回通用图片开始标签文本。这个标签用于在文本流里标出图片位置。

数据流：没有输入 → 把常量 IMAGE_OPEN_TAG 转成 String → 返回。

调用关系：图片占位和解析逻辑用它保持标签文本一致。

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

fn image_close_tag_text() -> String

作用：返回通用图片结束标签文本。它和开始标签配对，标明图片占位结束。

数据流：没有输入 → 把 IMAGE_CLOSE_TAG 转成 String → 返回。

调用关系：解析用户消息和生成图片占位时会依赖同一套标签。

fn local_image_label_text(label_number: usize) -> String

作用：按编号生成本地图片标签，比如“[Image #1]”。这让多张图片在消息里能被清楚地区分。

数据流：输入是图片编号 → 格式化成标签字符串 → 返回。

调用关系：附加图片、重新标号图片和生成本地图片开始标签都会调用它。

调用图：被 12 处调用（local_image_open_tag_text_with_path, attach_image, relabel_local_images, apply_external_edit_drops_missing_attachments, apply_external_edit_limits_duplicates_to_occurrences, apply_external_edit_rebuilds_text_and_attachments, apply_external_edit_renumbers_image_placeholders, clear_for_ctrl_c_preserves_image_draft_state, deleting_reordered_image_one_renumbers_text_in_place, set_text_content_reattaches_images_without_placeholder_metadata (+2 more)）；外部调用 1 个（format!）。

fn local_image_open_tag_text_with_path(label_number: usize, path: &std::path::Path) -> String

作用：生成带编号和文件路径的本地图片开始标签。它让文本记录里既能看到第几张图，也能看到来自哪个文件。

数据流：输入是图片编号和路径 → 先生成标签，再把路径显示字符串嵌入模板 → 返回开始标签文本。

调用关系：local_image_content_items 用它包装本地图片内容。

调用图：调用 1 个内部函数（local_image_label_text）；被 1 处调用（local_image_content_items）；外部调用 2 个（display, format!）。

fn is_local_image_open_tag_text(text: &str) -> bool

作用：判断一段文本是不是本地图片开始标签。它不解析细节，只确认前后固定格式匹配。

数据流：输入是文本 → 检查是否有指定前缀且以指定后缀结尾 → 返回 true 或 false。

调用关系：parse_user_message 用它识别文本里的本地图片占位。

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

fn is_local_image_close_tag_text(text: &str) -> bool

作用：判断一段文本是不是本地图片结束标签。本地图片的结束标签复用通用图片结束标签。

数据流：输入是文本 → 调用 is_image_close_tag_text → 返回判断结果。

调用关系：parse_user_message 用它识别本地图片占位结束。

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

fn is_image_open_tag_text(text: &str) -> bool

作用：判断文本是否正好是通用图片开始标签。

数据流：输入是文本 → 和 IMAGE_OPEN_TAG 常量比较 → 返回 true 或 false。

调用关系：用户消息解析会用它识别图片边界。

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

fn is_image_close_tag_text(text: &str) -> bool

作用：判断文本是否正好是通用图片结束标签。

数据流：输入是文本 → 和 IMAGE_CLOSE_TAG 常量比较 → 返回 true 或 false。

调用关系：parse_user_message 和 is_local_image_close_tag_text 都用它保持结束标签判断一致。

调用图：被 2 处调用（parse_user_message, is_local_image_close_tag_text）。

fn invalid_image_error_placeholder(
    path: &std::path::Path,
    error: impl std::fmt::Display,
) -> ContentItem

作用：当文件看起来是图片但内容无效时，生成一段说明文字。它把“无效图片”和普通读取失败区分开。

数据流：输入是路径和错误 → 格式化成“图片无效”的文本 → 返回 InputText 内容项。

调用关系：local_image_content_items_with_label_number 在图片解码发现无效数据时调用它。

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

fn unsupported_image_error_placeholder(path: &std::path::Path, mime: &str) -> ContentItem

作用：当图片格式不支持时，生成一段可读的错误占位文本。

数据流：输入是路径和 MIME 类型（文件内容类型说明） → 格式化说明不支持该图片类型 → 返回 InputText。

调用关系：本地图片处理遇到 UnsupportedImageFormat 时会调用它。

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

fn local_image_content_items_with_label_number(
    path: &std::path::Path,
    file_bytes: Vec<u8>,
    label_number: Option<usize>,
    detail: ImageDetail,
) -> Vec<ContentItem>

作用：把本地图片文件字节变成模型可接收的内容项，并可带编号标签。失败时不会崩溃，而是返回错误文字占位。

数据流：输入是路径、文件字节、可选编号和图片清晰度要求 → 根据 detail 选择原图或缩放处理 → 成功时转成 data URL 并包装成内容项；失败时按错误类型返回对应文本占位。

调用关系：ResponseInputItem::from_user_input 读取本地图片后会调用它；它再把成功结果交给 local_image_content_items。

调用图：调用 1 个内部函数（local_image_content_items）；外部调用 2 个（load_for_prompt_bytes, vec!）。

fn local_image_content_items(
    path: &std::path::Path,
    image_url: String,
    label_number: Option<usize>,
    detail: ImageDetail,
) -> Vec<ContentItem>

作用：把一张已经准备好的图片 URL 包装成消息内容项，可选地在前后加本地图片标签。

数据流：输入是路径、图片 data URL、可选编号和 detail → 有编号时先加开始标签，再加 InputImage，最后加结束标签 → 返回内容项列表。

调用关系：local_image_content_items_with_label_number 和延迟处理本地图片的路径都会用它。

调用图：调用 1 个内部函数（local_image_open_tag_text_with_path）；被 1 处调用（local_image_content_items_with_label_number）；外部调用 1 个（with_capacity）。

fn from(item: ResponseInputItem) -> Self

作用：把输入给模型的响应项转换成系统内部保存的响应项。转换时会补上内部字段的默认值，比如 id 和 metadata。

数据流：输入是 ResponseInputItem → 按类型映射成对应 ResponseItem；MCP 工具输出会先转成功能调用输出载荷 → 返回 ResponseItem。

调用关系：用户输入转响应项、测试消息阶段保留等流程会用它统一输入和历史记录格式。

调用图：被 2 处调用（response_item_from_user_input, response_input_message_conversion_preserves_phase）。

fn from(items: Vec<UserInput>) -> Self

作用：把一组用户输入直接转换成一条用户消息输入项，并默认处理本地图片。

数据流：输入是 Vec<UserInput> → 调用 from_user_input，LocalImagePreparation 设为 Process → 返回 ResponseInputItem。

调用关系：紧凑任务和图片输入测试用它作为便捷转换入口。

调用图：被 8 处调用（run_compact_task_inner_impl, image_user_input_preserves_requested_detail, local_image_non_image_adds_placeholder, local_image_read_error_adds_placeholder, local_image_unsupported_image_format_adds_placeholder, local_image_user_input_preserves_requested_detail, mixed_remote_and_local_images_share_label_sequence, serializes_image_user_input_without_tags）；外部调用 1 个（from_user_input）。

fn from_user_input(
        items: Vec<UserInput>,
        local_image_preparation: LocalImagePreparation,
    ) -> Self

作用：把用户输入列表整理成模型能接收的一条 user 消息。它处理文字、远程图片、本地图片，并忽略稍后才注入的技能和提及内容。

数据流：输入是用户输入列表和本地图片处理方式 → 逐项转换为 ContentItem；本地图片会读文件，成功后处理或延迟包装，失败则放错误占位 → 输出 ResponseInputItem::Message。

调用关系：ResponseInputItem::from 和 response_item_from_user_input 会调用它，是用户输入进入协议模型的主要入口。

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

fn function_call_output_content_items_to_text(
    content_items: &[FunctionCallOutputContentItem],
) -> Option<String>

作用：从工具调用输出的内容项里提取可读文本，忽略图片、加密内容和空白文本。需要日志或纯文本回退时会用它。

数据流：输入是内容项切片 → 过滤出非空 InputText → 用换行拼接；没有文本则返回 None。

调用关系：FunctionCallOutputBody::to_text、日志预览和调用处理逻辑会用它获得纯文本版本。

调用图：被 9 处调用（into_text, log_preview, handle_call, handle_call, handle_call, expect_text_output, to_text, function_call_output_content_items_to_text_ignores_blank_text_and_images, function_call_output_content_items_to_text_joins_text_segments）；外部调用 1 个（iter）。

fn from(item: crate::dynamic_tools::DynamicToolCallOutputContentItem) -> Self

作用：把动态工具输出内容项转换成协议里的工具输出内容项。图片会带上默认清晰度。

数据流：输入是动态工具的文本或图片项 → 文本原样转 InputText，图片转 InputImage 并设置默认 detail → 返回 FunctionCallOutputContentItem。

调用关系：动态工具系统把输出交给通用协议层时会用到这个转换。

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

作用：把功能调用输出正文尽量变成纯文本。纯文本正文直接返回，混合内容则提取其中的文字。

数据流：输入是 FunctionCallOutputBody → Text 克隆字符串返回，ContentItems 调用 function_call_output_content_items_to_text → 返回可选文本。

调用关系：日志、断言和调用处理需要文本形式时会用它。

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

fn default() -> Self

作用：提供一个默认的空文本工具输出正文。

数据流：没有输入 → 创建 Text(String::new()) → 返回。

调用关系：当没有显式输出正文时，序列化或结构初始化可使用这个默认值。

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

fn from_text(content: String) -> Self

作用：用一段纯文本创建工具调用输出载荷。success 字段不预设，让上层决定是否标成功。

数据流：输入是字符串 → 包成 FunctionCallOutputBody::Text，success 设为 None → 返回 payload。

调用关系：自定义工具输出、历史种子、响应请求构建等场景会用它。

调用图：被 9 处调用（dynamic_tool_call_round_trip_sends_text_content_items_to_model, custom_tool_call_output, record_items_truncates_custom_tool_call_output_content, ensure_call_outputs_present, seed_guardian_parent_history, external_context_pollution_items_exclude_local_tool_calls, to_response_item, azure_responses_request_includes_store_and_reasoning_ids, serializes_success_as_plain_string）；外部调用 1 个（Text）。

fn from_content_items(content_items: Vec<FunctionCallOutputContentItem>) -> Self

作用：用一组文本或图片内容项创建工具调用输出载荷。适合工具返回图片或混合内容时使用。

数据流：输入是内容项列表 → 包成 FunctionCallOutputBody::ContentItems，success 设为 None → 返回 payload。

调用关系：图片输出估算和工具输出序列化测试会用它构造混合内容。

调用图：被 12 处调用（encrypted_function_output_uses_plaintext_byte_estimate, image_data_url_payload_does_not_dominate_custom_tool_call_output_estimate, image_data_url_payload_does_not_dominate_function_call_output_estimate, non_base64_image_urls_are_unchanged, non_image_base64_data_url_is_unchanged, original_detail_images_are_capped_at_max_patch_count, original_detail_images_scale_with_dimensions, original_detail_webp_images_scale_with_dimensions, image_output, to_response_item (+2 more)）；外部调用 1 个（ContentItems）。

fn text_content(&self) -> Option<&str>

作用：如果工具输出是纯文本，就借出这段文本；如果是混合内容，就返回 None。

数据流：输入是 payload → 检查 body 分支 → Text 返回 &str，ContentItems 返回 None。

调用关系：需要只处理纯文本输出的调用方可用它安全判断。

fn text_content_mut(&mut self) -> Option<&mut String>

作用：如果工具输出是纯文本，就拿到可修改的字符串引用。混合内容不能用这个接口修改。

数据流：输入是可变 payload → Text 返回 &mut String，ContentItems 返回 None → 调用方可直接改文本。

调用关系：输出截断、清洗或追加说明时可用它处理纯文本载荷。

fn content_items(&self) -> Option<&[FunctionCallOutputContentItem]>

作用：如果工具输出是内容项列表，就借出这些内容项；纯文本输出则返回 None。

数据流：输入是 payload → ContentItems 返回切片，Text 返回 None。

调用关系：output_image_urls 等函数用它从工具输出里找图片。

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

fn content_items_mut(&mut self) -> Option<&mut Vec<FunctionCallOutputContentItem>>

作用：如果工具输出是内容项列表，就拿到可修改列表。纯文本输出不能通过这里修改。

数据流：输入是可变 payload → ContentItems 返回可变 Vec 引用，Text 返回 None。

调用关系：需要调整图片或内容项的后处理代码可使用它。

fn serialize(&self, serializer: S) -> Result<S::Ok, S::Error>

作用：把工具调用输出写成 JSON 时，保持兼容：纯文本写成字符串，混合内容写成数组。

数据流：输入是 payload 和序列化器 → Text 调 serialize_str，ContentItems 调列表序列化 → 输出 JSON 序列化结果。

调用关系：响应输入项序列化时自动调用它，保证外部看到简单直观的 output 字段。

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

fn deserialize(deserializer: D) -> Result<Self, D::Error>

作用：从 JSON 读取工具调用输出载荷，并把 success 初始化为空。

数据流：输入是反序列化器 → 先读成 FunctionCallOutputBody → 包成 FunctionCallOutputPayload，success 为 None → 返回。

调用关系：它和 serialize 配套，支持字符串或内容项数组两种 wire 格式。

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

fn from_result(result: Result<Self, String>) -> Self

作用：把 Result 形式的工具调用结果变成统一的 CallToolResult。失败字符串会被包装成错误结果。

数据流：输入是 Result<CallToolResult, String> → Ok 直接取出，Err 调 from_error_text → 返回 CallToolResult。

调用关系：工具执行层可以用它把 Rust 的成功/失败结果转成协议对象。

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

fn from_error_text(text: String) -> Self

作用：用一段错误文字创建标准工具错误结果。内容里会放一个 text 类型 JSON，并标记 is_error 为 true。

数据流：输入是错误字符串 → 构造 content JSON 数组，structured_content 和 meta 为空，is_error 为 Some(true) → 返回 CallToolResult。

调用关系：from_result 和工具错误处理会调用它。

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

fn success(&self) -> bool

作用：判断工具结果是否成功。只有 is_error 明确等于 true 才算失败。

数据流：输入是 CallToolResult → 检查 is_error != Some(true) → 返回布尔值。

调用关系：as_function_call_output_payload 用它把成功状态写进输出载荷。

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

fn as_function_call_output_payload(&self) -> FunctionCallOutputPayload

作用：把 MCP 工具结果转换成模型能接收的功能调用输出。它优先使用结构化内容，其次尝试把文本和图片转换成内容项。

数据流：输入是 CallToolResult → 若 structured_content 非空就序列化成文本；否则序列化 content，并尝试 convert_mcp_content_to_items；有图片时输出内容项，否则输出 JSON 文本 → success 带上成功状态。

调用关系：into_function_call_output_payload 调用它，ResponseItem::from 处理 MCP 工具输出时也间接依赖它。

调用图：调用 2 个内部函数（success, convert_mcp_content_to_items）；被 1 处调用（into_function_call_output_payload）；外部调用 3 个（ContentItems, Text, to_string）。

fn into_function_call_output_payload(self) -> FunctionCallOutputPayload

作用：消费一个 CallToolResult，并转换成功能调用输出载荷。当前实现直接借用自身转换逻辑。

数据流：输入是 CallToolResult 本身 → 调用 as_function_call_output_payload → 返回 FunctionCallOutputPayload。

调用关系：ResponseInputItem::McpToolCallOutput 转内部响应项时会用它。

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

fn convert_mcp_content_to_items(
    contents: &[serde_json::Value],
) -> Option<Vec<FunctionCallOutputContentItem>>

作用：把 MCP 内容数组尽量转换成协议里的文本和图片内容项。只有看到图片时才返回内容项列表，否则让调用方继续用纯 JSON 文本。

数据流：输入是 JSON 内容数组 → 每项按 type 解析成 text、image 或 unknown；图片 data 没有 data: 前缀时补成 data URL，并读取图片 detail 元数据 → 如果至少有图片则返回列表，否则返回 None。

调用关系：CallToolResult::as_function_call_output_payload 用它把工具返回的图片保留下来，而不是压成普通字符串。

调用图：被 3 处调用（as_function_call_output_payload, convert_mcp_content_to_items_builds_data_urls_when_missing_prefix, convert_mcp_content_to_items_preserves_data_urls）；外部调用 4 个（len, with_capacity, format!, to_string）。

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

作用：定义工具调用输出载荷显示成字符串时的样子。纯文本直接显示，内容项列表显示成 JSON 字符串。

数据流：输入是 payload 和格式化器 → Text 写入原文本；ContentItems 先转 JSON 字符串再写入 → 返回格式化结果。

调用关系：日志、调试输出或任何 Display 使用场景都会经过它。

调用图：外部调用 2 个（write_str, to_string）。

fn plaintext_agent_message_content_rejects_mixed_encrypted_content()

作用：测试纯文本提取遇到加密内容时会拒绝返回。它防止加密内容被误当作普通文本拼进去。

数据流：输入是一个含文本和加密片段的测试列表 → 调 plaintext_agent_message_content → 断言结果是 None。

调用关系：它覆盖 plaintext_agent_message_content 的安全边界。

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

fn response_input_message_conversion_preserves_phase()

作用：测试 ResponseInputItem 转 ResponseItem 时不会丢掉消息阶段 phase。

数据流：构造一条带 Commentary 阶段的输入消息 → 调 ResponseItem::from → 断言输出消息仍带相同 phase。

调用关系：它保护 ResponseItem::from 的字段保留行为。

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

fn response_item_metadata_round_trips_and_stamps_turn_ids() -> Result<()>

作用：测试响应条目的元数据能序列化往返，并且补回合编号时遵守不覆盖已有值的规则。

数据流：构造带元数据的消息 → JSON 往返后比较；再测试未知字段被忽略、已有 turn_id 不被覆盖、空或缺失 turn_id 可被补上、Other 不可补 → 返回测试结果。

调用关系：它覆盖 ResponseItem 的 metadata、turn_id 和 stamp_turn_id_if_missing 行为。

调用图：外部调用 6 个（assert_eq!, response_item_metadata, response_item_with_metadata, from_value, json!, to_value）。

fn response_item_with_metadata(metadata: Option<ResponseItemMetadata>) -> ResponseItem

作用：为测试创建一条带可选元数据的用户消息。它减少重复构造代码。

数据流：输入是可选 ResponseItemMetadata → 构造 role 为 user、内容为 hello 的 ResponseItem::Message → 返回。

调用关系：response_item_metadata_round_trips_and_stamps_turn_ids 调用它准备样本。

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

fn response_item_metadata(turn_id: &str) -> ResponseItemMetadata

作用：为测试创建只包含 turn_id 的元数据对象。

数据流：输入是 turn_id 字符串 → 转成 Some(String) 放入 ResponseItemMetadata → 返回。

调用关系：元数据往返测试用它生成不同 turn_id 的样本。

fn image_detail_roundtrips_all_wire_values() -> Result<()>

作用：测试图片清晰度 detail 的 JSON 值能正确读写，尤其是 auto 和 low。

数据流：输入是几个 JSON 字符串和图片内容 JSON → 反序列化、序列化并比较预期枚举和值 → 成功返回 Ok。

调用关系：它保护 ImageDetail 的协议兼容性。

调用图：外部调用 3 个（assert_eq!, from_value, json!）。

fn sandbox_permissions_helpers_match_documented_semantics()

作用：测试 SandboxPermissions 三个辅助判断和文档语义一致。

数据流：准备三个权限枚举及预期布尔值 → 逐个调用 requires_escalated_permissions、requests_sandbox_override、uses_additional_permissions → 断言结果相等。

调用关系：它覆盖 SandboxPermissions 的三个小判断函数。

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

fn convert_mcp_content_to_items_preserves_data_urls()

作用：测试 MCP 图片内容如果已经是 data URL，就不会被重复包装。

数据流：构造带 data:image/png;base64 前缀的图片 JSON → 调 convert_mcp_content_to_items → 断言输出图片 URL 原样保留。

调用关系：它保护 convert_mcp_content_to_items 对已有 data URL 的处理。

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

fn response_item_parses_image_generation_call()

作用：测试图片生成调用响应项能从 JSON 正确解析，包括 revised_prompt。

数据流：输入一段 image_generation_call JSON → 反序列化成 ResponseItem → 断言各字段符合预期。

调用关系：它覆盖 ResponseItem 里图片生成调用分支的反序列化。

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

fn response_item_parses_image_generation_call_without_revised_prompt()

作用：测试图片生成调用没有 revised_prompt 时也能解析成功。

数据流：输入缺少 revised_prompt 的 JSON → 反序列化 → 断言 revised_prompt 为 None 且其他字段正确。

调用关系：它保证可选字段缺失不会导致 ResponseItem 解析失败。

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

fn additional_permission_profile_is_empty_when_all_fields_are_none()

作用：测试额外权限配置在网络和文件系统都没写时被认为是空的。

数据流：创建默认 AdditionalPermissionProfile → 调 is_empty → 断言为 true。

调用关系：它覆盖 AdditionalPermissionProfile::is_empty 的全空情况。

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

fn additional_permission_profile_is_not_empty_when_field_is_present_but_nested_empty()

作用：测试只要字段存在，即使里面没有具体值，也不算完全空配置。

数据流：构造 network 为 Some 但 enabled 为 None 的配置 → 调 is_empty → 断言为 false。

调用关系：它保护 AdditionalPermissionProfile::is_empty 对“字段存在”的语义。

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

fn permission_profile_round_trip_preserves_glob_scan_max_depth()

作用：测试权限档案转换不会丢掉通配符扫描最大深度。

数据流：构造带 Deny 通配符和 glob_scan_max_depth 的文件沙箱策略 → 转成 PermissionProfile → 再取回文件策略并比较。

调用关系：它覆盖 PermissionProfile::from_runtime_permissions 和 file_system_sandbox_policy 的往返。

调用图：调用 2 个内部函数（from_runtime_permissions, restricted）；外部调用 2 个（assert_eq!, vec!）。

fn permission_profile_deserializes_legacy_rollout_shape() -> Result<()>

作用：测试旧版 rollout 形状的权限档案 JSON 还能被新版读取。

数据流：输入旧 JSON，包含 network 和 file_system → 反序列化成 PermissionProfile → 断言变成预期 Managed 档案。

调用关系：它覆盖 PermissionProfile::deserialize 和 LegacyPermissionProfile 转换。

调用图：外部调用 3 个（assert_eq!, from_value, json!）。

fn permission_profile_presets_match_legacy_defaults()

作用：测试新版内置只读和工作区可写档案，与旧默认沙箱策略转换结果一致。

数据流：分别生成 PermissionProfile::read_only/workspace_write 和旧策略转换结果 → 断言相等。

调用关系：它保护内置权限预设的向后兼容性。

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

fn permission_profile_round_trip_preserves_disabled_sandbox() -> Result<()>

作用：测试完全关闭沙箱的旧策略转换到新档案后，再转回旧策略和运行时权限都保持语义。

数据流：输入 DangerFullAccess → 转 PermissionProfile → 断言为 Disabled；再转旧策略和运行时权限并比较。

调用关系：它覆盖 PermissionProfile::from_legacy_sandbox_policy、to_legacy_sandbox_policy 和 to_runtime_permissions。

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

fn disabled_permission_profile_ignores_runtime_network_policy()

作用：测试当沙箱执行方式是 Disabled 时，即使传入受限网络，最终也表示为 Disabled 档案。

数据流：输入 Disabled enforcement、不受限文件策略和受限网络 → 调 from_runtime_permissions_with_enforcement → 断言结果为 Disabled。

调用关系：它保护 PermissionProfile::from_runtime_permissions_with_enforcement 对关闭沙箱的特殊处理。

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

fn permission_profile_from_runtime_permissions_preserves_external_sandbox()

作用：测试外部沙箱文件策略会被保存为 External 权限档案，并保留网络策略。

数据流：输入 external_sandbox 文件策略和受限网络 → 转 PermissionProfile → 断言为 External；再用显式 enforcement 转换并比较。

调用关系：它覆盖 PermissionProfile::from_runtime_permissions 对外部沙箱的处理。

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

fn permission_profile_from_runtime_permissions_preserves_unrestricted_managed_network()

作用：测试“不限制文件但网络受限”的组合不会被误折叠成旧式外部沙箱含义。

数据流：输入 External enforcement、不受限文件策略和受限网络 → 转 PermissionProfile → 断言是 Managed 且文件 Unrestricted、网络 Restricted，并检查运行时权限往返。

调用关系：它保护 from_runtime_permissions_with_enforcement 对拆分文件/网络权限的精确表达。

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

fn permission_profile_round_trip_preserves_external_sandbox() -> Result<()>

作用：测试旧的 ExternalSandbox 策略转换到新档案后，转回旧策略和运行时权限都保持外部沙箱语义。

数据流：构造旧 ExternalSandbox 且网络受限 → 转 PermissionProfile → 断言为 External；再转旧策略和运行时权限比较。

调用关系：它覆盖外部沙箱兼容转换链路。

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

fn file_system_permissions_with_glob_scan_depth_uses_canonical_json() -> Result<()>

作用：测试带 glob_scan_max_depth 的文件权限必须使用新 canonical JSON，而不是旧 read/write JSON。

数据流：构造带普通读路径和扫描深度的 FileSystemPermissions → 序列化成 JSON → 断言没有 read/write、有 entries 和 glob_scan_max_depth，并能反序列化回来。

调用关系：它覆盖 FileSystemPermissions::serialize/deserialize 对新旧格式的选择。

调用图：调用 1 个内部函数（try_from）；外部调用 7 个（new, from, assert!, assert_eq!, cfg!, to_value, vec!）。

fn file_system_permissions_rejects_zero_glob_scan_depth()

作用：测试 glob_scan_max_depth 不能为 0。0 没有实际意义，所以反序列化应失败。

数据流：输入 glob_scan_max_depth 为 0 的 JSON → 尝试反序列化 FileSystemPermissions → 断言得到错误。

调用关系：它保护文件权限模型中 NonZeroUsize 的约束。

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

fn convert_mcp_content_to_items_builds_data_urls_when_missing_prefix()

作用：测试 MCP 图片只给 base64 数据时，系统会补成完整 data URL。

数据流：构造 data 为 Zm9v、mimeType 为 image/png 的图片 JSON → 调 convert_mcp_content_to_items → 断言输出 image_url 带 data:image/png;base64 前缀。

调用关系：它覆盖 convert_mcp_content_to_items 的图片 URL 补全逻辑。

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

fn convert_mcp_content_to_items_returns_none_without_images()

作用：测试 MCP 内容只有文本时不会转换成内容项列表，而是让调用方保留 JSON 文本路径。

数据流：输入一个 text 类型 JSON → 调 convert_mcp_content_to_items → 断言返回 None。

调用关系：它保护 convert_mcp_content_to_items 的“只有图片才启用内容项输出”规则。

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

fn function_call_output_content_items_to_text_joins_text_segments()

作用：测试从混合内容项提取文本时，会跳过图片并用换行连接文字。

数据流：构造文本、图片、文本三个内容项 → 调 function_call_output_content_items_to_text → 断言得到两行文本。

调用关系：它覆盖工具输出文本提取的正常混合内容场景。

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

fn function_call_output_content_items_to_text_ignores_blank_text_and_images()

作用：测试空白文本、图片和加密内容都不会产生纯文本输出。

数据流：构造空白文本、图片和加密内容项 → 调 function_call_output_content_items_to_text → 断言返回 None。

调用关系：它保护文本提取函数不会把无意义或不可读内容当成文本。

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

fn function_call_output_body_to_text_returns_plain_text_content()

作用：测试纯文本工具输出正文调用 to_text 会直接返回文本。

数据流：构造 FunctionCallOutputBody::Text("ok") → 调 to_text → 断言返回 Some("ok")。

调用关系：它覆盖 FunctionCallOutputBody::to_text 的 Text 分支。

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

fn function_call_output_body_to_text_uses_content_item_fallback()

作用：测试内容项形式的工具输出也能通过 to_text 提取其中的文字。

数据流：构造包含文本和图片的 ContentItems 正文 → 调 to_text → 断言只返回文字。

调用关系：它覆盖 FunctionCallOutputBody::to_text 的 ContentItems 分支。

调用图：外部调用 3 个（assert_eq!, ContentItems, vec!）。

fn function_call_deserializes_optional_namespace()

作用：测试 function_call JSON 中可选的 namespace 字段能被正确读取。

数据流：输入带 namespace 的 function_call JSON → 反序列化为 ResponseItem → 断言 namespace 和其他字段正确。

调用关系：它保护 ResponseItem::FunctionCall 的协议字段兼容性。

调用图：外部调用 3 个（assert_eq!, from_value, json!）。

fn render_command_prefix_list_sorts_by_len_then_total_len_then_alphabetical()

作用：测试允许命令前缀展示时的排序规则：先按 token 数，再按总长度，最后按字母顺序。

数据流：输入多组乱序前缀 → 调 format_allow_prefixes → 断言输出顺序符合规则。

调用关系：它覆盖 format_allow_prefixes、prefix_combined_str_len 和 render_command_prefix 的组合效果。

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

fn render_command_prefix_list_limits_output_to_max_prefixes()

作用：测试前缀太多时，展示内容会限制条数并加截断标记。

数据流：生成超过 MAX_RENDERED_PREFIXES 的前缀 → 调 format_allow_prefixes → 断言末尾有截断标记且行数符合预期。

调用关系：它保护 format_allow_prefixes 的数量上限。

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

fn format_allow_prefixes_limits_output()

作用：测试允许前缀展示文本不会超过最大字节限制加截断标记长度。

数据流：构造很多很长的允许前缀规则 → 获取前缀并格式化 → 断言输出长度在限制内。

调用关系：它覆盖 format_allow_prefixes 的字节级截断逻辑，避免界面或消息被撑爆。

调用图：调用 1 个内部函数（format_allow_prefixes）；外部调用 3 个（assert!, empty, format!）。

fn serializes_success_as_plain_string() -> Result<()>

作用：测试成功的功能调用输出序列化时，output 字段是普通字符串。

数据流：构造 FunctionCallOutputPayload::from_text("ok") 的输出项 → 序列化再读成 JSON 值 → 断言 output 是字符串 ok。

调用关系：它保护 FunctionCallOutputPayload::serialize 的纯文本兼容格式。

调用图：调用 1 个内部函数（from_text）；外部调用 3 个（assert_eq!, from_str, to_string）。

fn serializes_failure_as_string() -> Result<()>

作用：测试失败的功能调用输出即使带 success=false，output 本身仍序列化成字符串内容。

数据流：构造 body 为 Text("bad")、success 为 Some(false) 的输出项 → 序列化成 JSON → 断言 output 是字符串 bad。

调用关系：它确保失败状态不会改变 output 字段的 wire 形状。

调用图：外部调用 4 个（assert_eq!, Text, from_str, to_string）。

fn serializes_image_outputs_as_array() -> Result<()>

作用：这个测试确认：工具返回文字加图片时，最终给模型看的输出必须是一个数组，而不是一整段普通字符串。这样模型才能分别识别“这是文字”“这是图片”。

数据流：进去的是一个模拟的工具结果，里面有一条文字和一张 base64 图片 → 测试把它转换成函数调用输出，再序列化成 JSON → 出来应当是 success 为真、内容里有文字项和图片项，并且 JSON 的 output 字段是数组。

调用关系：测试运行器会调用它；它主要验证 CallToolResult 到 FunctionCallOutputPayload，再到 ResponseInputItem JSON 的整条链路，防止图片工具输出被错误压成字符串。

调用图：外部调用 6 个（assert!, assert_eq!, panic!, from_str, to_string, vec!）。

fn serializes_custom_tool_image_outputs_as_array() -> Result<()>

作用：这个测试确认：自定义工具返回图片时，output 也要按数组写进 JSON。它防的是自定义工具和普通函数工具格式不一致。

数据流：进去的是一个自定义工具输出项，里面只有一张图片 → 测试用 from_content_items 组成输出载荷，再转成 JSON → 出来的 output 字段必须是数组。

调用关系：测试运行器会调用它；它补充验证 CustomToolCallOutput 这条路径，确保它和普通 FunctionCallOutput 用同一套图片输出规则。

调用图：调用 1 个内部函数（from_content_items）；外部调用 4 个（assert!, from_str, to_string, vec!）。

fn serializes_encrypted_function_output_content_as_array() -> Result<()>

作用：这个测试确认：加密内容作为函数输出时，也要放在数组里，并保留 encrypted_content 字段。加密内容是不透明的，程序不能擅自改它。

数据流：进去的是一个带 encrypted_content 的输出项 → 测试把它包成函数调用输出并转成 JSON 值 → 出来应当正好是 type 为 function_call_output、call_id 正确、output 为加密内容数组的 JSON。

调用关系：测试运行器会调用它；它验证 FunctionCallOutputContentItem::EncryptedContent 的序列化规则，防止加密载荷被包错或字段名被改坏。

调用图：调用 1 个内部函数（from_content_items）；外部调用 3 个（assert_eq!, to_value, vec!）。

fn preserves_existing_image_data_urls() -> Result<()>

作用：这个测试确认：如果工具返回的图片数据本来已经是完整的 data URL，就不要再给它套一层前缀。否则图片地址会坏掉。

数据流：进去的是一个图片工具结果，data 字段已经是 data:image/png;base64,... → 转成函数输出载荷 → 出来的图片 URL 应保持原样，并带默认图片清晰度。

调用关系：测试运行器会调用它；它盯住 CallToolResult 转换图片时的特殊分支，确保已有的图片地址不会被重复加工。

调用图：外部调用 3 个（assert_eq!, panic!, vec!）。

fn preserves_original_detail_metadata_on_mcp_images() -> Result<()>

作用：这个测试确认：MCP 工具返回图片时，如果元数据说要原始清晰度，就要照做。MCP 可以理解成外部工具接入协议，元数据是工具附带的小纸条。

数据流：进去的是一个图片工具结果，_meta 里写着 codex/imageDetail 为 original → 转成函数输出载荷 → 出来的图片项应使用 data URL，并把 detail 设成 Original。

调用关系：测试运行器会调用它；它验证 MCP 图片元数据到 ImageDetail 的转换，避免用户或工具指定的图片质量被默认值覆盖。

调用图：外部调用 3 个（assert_eq!, panic!, vec!）。

fn preserves_standard_detail_metadata_on_mcp_images() -> Result<()>

作用：这个测试确认：MCP 图片元数据里写 high 时，图片清晰度会保留为 high。它保证标准清晰度选项不会在转换时丢失。

数据流：进去的是一个带 _meta.codex/imageDetail=high 的图片结果 → 转换成函数输出载荷 → 出来的图片项应是 png 的 data URL，detail 应为 High。

调用关系：测试运行器会调用它；它和 original 清晰度测试一起覆盖图片元数据解析，确保不同清晰度值都能被正确识别。

调用图：外部调用 3 个（assert_eq!, panic!, vec!）。

fn deserializes_array_payload_into_items() -> Result<()>

作用：这个测试确认：当 JSON 本身就是一个输出项数组时，程序能把它读成内部的内容列表。也就是说，外面发来的数组格式不会被误读。

数据流：进去的是一段 JSON 数组，包含 input_text 和 input_image → 反序列化成 FunctionCallOutputPayload → 出来应当没有 success 标记，body 是对应的内容项列表，再转回 JSON 时仍是同样的数组。

调用关系：测试运行器会调用它；它验证 FunctionCallOutputPayload 的读取和写回规则，保证数组载荷可以稳定来回转换。

调用图：外部调用 3 个（assert_eq!, from_str, vec!）。

fn deserializes_encrypted_array_payload_into_items() -> Result<()>

作用：这个测试确认：加密内容数组也能被读成内部内容项，并能原样写回。这样旧数据或远端返回的加密片段不会被破坏。

数据流：进去的是只有 encrypted_content 的 JSON 数组 → 反序列化成 FunctionCallOutputPayload → 出来应当是 ContentItems 形式，success 为空，再序列化时保持为同样的数组。

调用关系：测试运行器会调用它；它补齐加密内容在数组载荷里的反序列化路径，和普通文字、图片数组测试配套。

调用图：外部调用 3 个（assert_eq!, from_str, vec!）。

fn deserializes_compaction_alias() -> Result<()>

作用：这个测试确认：旧名字 compaction_summary 还能被读成现在的 Compaction。这样历史记录或旧版本产生的数据不会突然打不开。

数据流：进去的是 type 为 compaction_summary、带 encrypted_content 的 JSON → 读成 ResponseItem → 出来应当是 ResponseItem::Compaction，里面保存 abc，metadata 为空。

调用关系：测试运行器会调用它；它验证 ResponseItem 的兼容别名逻辑，让新代码能接住旧协议名字。

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

fn deserializes_context_compaction() -> Result<()>

作用：这个测试确认：context_compaction 类型能被正确读出来。它表示一次上下文压缩信息，也就是把长对话整理成更短内容。

数据流：进去的是 type 为 context_compaction 的 JSON → 反序列化成 ResponseItem → 出来应当是 ContextCompaction，并保留 encrypted_content。

调用关系：测试运行器会调用它；它验证 ResponseItem 对上下文压缩消息的识别，确保相关记录不会被当成未知类型。

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

fn serializes_compaction_trigger_without_payload() -> Result<()>

作用：这个测试确认：压缩触发信号即使没有额外内容，也能写成合法 JSON。它像一个“该整理上下文了”的空铃声。

数据流：进去的是 metadata 为空的 CompactionTrigger → 转成 JSON 值 → 出来应当只有 type: compaction_trigger，没有多余空字段。

调用关系：测试运行器会调用它；它检查 ResponseItem::CompactionTrigger 的最小输出格式，避免无意义的 null 字段影响协议。

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

fn serializes_stamped_compaction_trigger_metadata() -> Result<()>

作用：这个测试确认：压缩触发信号可以补上 turn_id，也就是标记它属于哪一轮对话。这样后续追踪时知道信号从哪里来。

数据流：进去的是一个没有 metadata 的 CompactionTrigger → 调用 stamp_turn_id_if_missing 写入 turn-1 → 转成 JSON 后应带 metadata.turn_id。

调用关系：测试运行器会调用它；它验证 ResponseItem 上给元数据盖章的行为，确保压缩触发消息能被关联到具体回合。

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

fn deserializes_compaction_trigger_without_payload() -> Result<()>

作用：这个测试确认：只有 type、没有额外字段的 compaction_trigger 也能被读回来。它保证最简消息格式双向可用。

数据流：进去的是 {"type":"compaction_trigger"} 这段 JSON → 反序列化成 ResponseItem → 出来应当是 metadata 为空的 CompactionTrigger。

调用关系：测试运行器会调用它；它和序列化测试成对出现，保证压缩触发信号发出去和收回来都没问题。

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

fn deserializes_legacy_ghost_snapshot_as_other() -> Result<()>

作用：这个测试确认：老版本的 ghost_snapshot 消息现在会被当成 Other，而不是让解析失败。这样遇到废弃消息时系统能平稳跳过。

数据流：进去的是一段旧 ghost_snapshot JSON，里面有 ghost_commit 信息 → 反序列化成 ResponseItem → 出来应当是 ResponseItem::Other。

调用关系：测试运行器会调用它；它验证旧协议兼容策略：不认识或不再使用的历史类型，不崩溃，只归为其他。

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

fn roundtrips_web_search_call_actions() -> Result<()>

作用：这个测试确认：网页搜索动作的几种形态都能正确读写，包括搜索、打开网页、在网页里查找。roundtrip 的意思是“读进来再写出去还一样”。

数据流：进去是一组 web_search_call JSON 样例 → 每个样例先读成 ResponseItem，再转回 JSON → 出来应匹配预期的 action、status 和 id；对于不该原样保留 id 的部分样例，也按规则去掉 id 后比较。

调用关系：测试运行器会调用它；它覆盖 WebSearchAction 的多个分支，确保 ResponseItem::WebSearchCall 在不同搜索状态下都能稳定通信。

调用图：外部调用 4 个（assert_eq!, from_str, to_value, vec!）。

fn serializes_image_user_input_without_tags() -> Result<()>

作用：这个测试确认：用户直接输入远程图片时，不会额外加文字标签，只会变成一条图片内容。没有指定清晰度时，用默认清晰度。

数据流：进去的是一个 UserInput::Image，只有 image_url、没有 detail → 转成 ResponseInputItem → 出来应当是 Message，内容里只有 InputImage，并带默认 detail。

调用关系：测试运行器会调用它；它验证 UserInput 到 ResponseInputItem 的转换，特别是远程图片和本地图片不同：远程图片不需要包裹说明标签。

调用图：调用 1 个内部函数（from）；外部调用 3 个（assert_eq!, panic!, vec!）。

fn image_user_input_preserves_requested_detail() -> Result<()>

作用：这个测试确认：用户给远程图片指定原始清晰度时，转换后不会被改成默认值。用户的明确要求优先。

数据流：进去的是一个带 ImageDetail::Original 的 UserInput::Image → 转成 ResponseInputItem → 出来的 Message 第一项应是同一个 image_url，并保留 Original detail。

调用关系：测试运行器会调用它；它紧跟默认清晰度测试，验证图片输入转换时既会补默认值，也会尊重用户指定值。

调用图：调用 1 个内部函数（from）；外部调用 3 个（assert_eq!, panic!, vec!）。

fn tool_search_call_roundtrips() -> Result<()>

作用：这个测试确认：工具搜索请求能从 JSON 读出来，也能再写回 JSON。工具搜索就是先查有哪些工具可用，而不是马上执行某个工具。

数据流：进去的是一段 tool_search_call JSON，包含 call_id、执行位置和查询参数 → 读成 ResponseItem::ToolSearchCall → 再转成 JSON，输出应保留原来的关键字段和值。

调用关系：测试运行器会调用它；它验证 ResponseItem 对工具搜索调用的协议支持，确保客户端发来的搜索请求不会丢参数。

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

fn tool_search_output_roundtrips() -> Result<()>

作用：这个测试确认：工具搜索结果能在输入项和响应项之间转换，并能写成正确 JSON。结果里包含找到的工具说明。

数据流：进去的是 ResponseInputItem::ToolSearchOutput，里面有 call_id、状态、执行位置和一个工具定义 → 转成 ResponseItem 后应字段一致 → 序列化成 JSON 后也应完整保留工具列表。

调用关系：测试运行器会调用它；它验证工具搜索“返回结果”这条链路，连接 ResponseInputItem、ResponseItem 和 JSON 输出格式。

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

fn tool_search_server_items_allow_null_call_id() -> Result<()>

作用：这个测试确认：服务端执行的工具搜索可以没有 call_id，也就是 JSON 里 call_id 为 null 时不算错误。这样服务端内部搜索不必伪造一个调用编号。

数据流：进去的是两段 JSON：一个 tool_search_call、一个 tool_search_output，call_id 都是 null → 分别读成 ResponseItem → 出来应当 call_id 为 None，其他状态和参数保留。

调用关系：测试运行器会调用它；它验证工具搜索协议对服务端场景更宽松的规则，避免因为没有 call_id 而拒绝合法消息。

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

fn mixed_remote_and_local_images_share_label_sequence() -> Result<()>

作用：这个测试确认：远程图片和本地图片混在一起时，图片编号按同一套顺序走。本地图片会加文字标签，方便模型知道它对应哪个文件。

数据流：进去的是一个远程图片和一个临时创建的本地 PNG 文件 → 转成 ResponseInputItem::Message → 出来第一项是远程图片，第二项是本地图片的打开标签且编号为 Image #2，后面跟本地图片内容和关闭标签。

调用关系：测试运行器会调用它；它会用临时目录和写文件模拟真实本地图片，验证 UserInput 转换时远程、本地图片共享编号规则。

调用图：调用 1 个内部函数（from）；外部调用 6 个（assert!, assert_eq!, panic!, write, tempdir, vec!）。

fn local_image_open_tag_preserves_path()

作用：这个测试确认：本地图片的打开标签会原样保留文件路径，即使路径里有特殊字符。这样提示文字能准确指向用户选择的文件。

数据流：进去的是编号 1 和一个包含特殊字符的路径 → 调用 local_image_open_tag_text_with_path → 出来的字符串应包含 Image #1 和未被改写的原始路径。

调用关系：测试运行器会调用它；它直接检查本地图片标签生成的小工具函数，防止路径被转义或截断导致用户看不懂。

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

fn local_image_user_input_preserves_requested_detail() -> Result<()>

作用：这个测试确认：用户上传本地图片并指定原始清晰度时，读文件并转成图片内容后仍保留这个清晰度要求。

数据流：进去的是一个临时写出的本地 PNG 路径，detail 为 Original → 转成 ResponseInputItem::Message → 出来的图片内容项应带 ImageDetail::Original。

调用关系：测试运行器会调用它；它通过真实临时文件走本地图片读取路径，验证本地图片和远程图片一样尊重用户指定的 detail。

调用图：调用 1 个内部函数（from）；外部调用 5 个（assert!, panic!, write, tempdir, vec!）。

fn local_image_read_error_adds_placeholder() -> Result<()>

作用：这个测试确认：本地图片文件不存在或读不到时，程序不会崩溃，而是放一段说明文字。占位文字会告诉模型和用户哪个路径出了问题。

数据流：进去的是一个不存在的本地图片路径 → 转成 ResponseInputItem → 因为读文件失败，出来的 Message 只有一条 InputText，文字里包含路径和 could not read。

调用关系：测试运行器会调用它；它验证本地图片读取失败时的兜底行为，保证请求还能继续发出，只是用文字说明替代图片。

调用图：调用 1 个内部函数（from）；外部调用 5 个（assert!, assert_eq!, panic!, tempdir, vec!）。

fn local_image_non_image_adds_placeholder() -> Result<()>

作用：这个测试确认：如果用户把非图片文件当图片传入，程序会用占位说明提示“不支持这种图片类型”。比如 JSON 文件不能当图片发给模型。

数据流：进去的是一个临时写出的 example.json 文件路径 → 转成 ResponseInputItem → MIME 类型被识别为 application/json，不是支持的图片，于是出来一条说明文字，包含类型和路径。

调用关系：测试运行器会调用它；它验证本地附件的类型检查，防止把普通文件错误包装成图片内容。

调用图：调用 1 个内部函数（from）；外部调用 6 个（assert!, assert_eq!, panic!, write, tempdir, vec!）。

fn local_image_unsupported_image_format_adds_placeholder() -> Result<()>

作用：这个测试确认：即使文件确实是图片类格式，比如 SVG，只要系统不支持，也会给出清楚的占位错误文字。这样用户知道不是文件丢了，而是格式不行。

数据流：进去的是一个临时写出的 SVG 文件路径 → 转成 ResponseInputItem → 因为 image/svg+xml 不受支持，出来的 Message 只有一条固定格式的 InputText，说明该路径的图片无法附加。

调用关系：测试运行器会调用它；它补充覆盖“是图片但格式不支持”的情况，和读不到文件、非图片文件两个测试一起保护本地图片错误处理。

调用图：调用 1 个内部函数（from）；外部调用 6 个（assert_eq!, format!, panic!, write, tempdir, vec!）。

fn is_team_like(self) -> bool

作用：判断一个套餐是不是“团队类”套餐。有人需要根据套餐决定是否展示团队相关功能时，会用到它。

数据流：进去的是一个 PlanType 套餐值 → 它检查这个值是不是 Team 或 SelfServeBusinessUsageBased → 出来一个 true 或 false，不改动任何数据。

调用关系：它是 PlanType 这个套餐类型上的小判断工具。业务代码拿到账号套餐后，可以调用它来把普通套餐和团队类套餐分开；内部用 matches! 这个 Rust 匹配工具做简单判断。

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

fn is_business_like(self) -> bool

作用：判断一个套餐是不是“商业类”套餐。它帮助代码把 Business 和按量计费的企业商业套餐归到同一组。

数据流：进去的是一个套餐值 → 它看这个值是不是 Business 或 EnterpriseCbpUsageBased → 返回 true 或 false，不产生其他副作用。

调用关系：它和 is_team_like 类似，都是给套餐分类用的便捷入口。后续如果界面或权限规则需要识别商业套餐，就可以直接问它，而不用到处重复写判断条件。

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

fn is_workspace_account(self) -> bool

作用：判断这个套餐是否属于“工作区账号”。工作区账号通常不是单纯个人账号，可能涉及团队、企业或教育组织。

数据流：进去的是一个套餐值 → 它把这个值和 Team、Business、Enterprise、Edu 等工作区相关套餐逐一对照 → 返回这个套餐是否算工作区账号。

调用关系：这是更大的分类判断，覆盖团队类、商业类、企业类和教育类套餐。账号展示、权限开关或组织功能判断时，可以用它快速知道用户是否属于某种组织空间。

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

fn from(plan: KnownPlan) -> Self

作用：把认证模块里认识的套餐名转换成这个协议文件里的套餐名。这样登录系统说的套餐，可以安全地变成接口对外返回的套餐。

数据流：进去的是认证模块中的 KnownPlan 套餐值 → 它按一一对应关系把 Free、Go、Plus、Pro、Team、Business 等转换成本文件里的 PlanType → 出来的是可用于账号协议的 PlanType。

调用关系：它站在“认证结果”和“账号接口数据”之间，像翻译员一样做名称对齐。文件里还配套有从更宽泛的认证套餐类型转换的逻辑，遇到未知套餐会落到 Unknown，避免程序因为新套餐名直接崩掉。

fn usage_based_plan_types_use_expected_wire_names()

作用：测试特殊套餐在 JSON 里是否使用约定好的名字。这样可以防止改代码时不小心把对外接口名字改坏。

数据流：进去的是几个 PlanType 测试值和几段 JSON 字符串 → 测试把套餐转成 JSON，再从 JSON 转回套餐 → 检查结果是否和预期完全一样，不会修改正式数据。

调用关系：这是测试环境里运行的保护网。它用 assert_eq! 比较实际结果和期望结果，重点保护 self_serve_business_usage_based、enterprise_cbp_usage_based、prolite 这些容易写错的对外名字。

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

fn plan_family_helpers_group_usage_based_variants_with_existing_plans()

作用：测试套餐分类函数是否把按量计费的新套餐归到正确家族里。它防止新旧套餐分组规则出现偏差。

数据流：进去的是 Team、SelfServeBusinessUsageBased、Business、EnterpriseCbpUsageBased 等套餐值 → 分别调用团队类和商业类判断函数 → 检查返回的 true 或 false 是否符合预期。

调用关系：它专门验证 PlanType::is_team_like 和 PlanType::is_business_like。也就是说，当分类函数被修改时，这个测试会提醒开发者有没有把团队套餐和商业套餐混在一起。

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

fn workspace_account_helper_includes_usage_based_workspace_plans()

作用：测试工作区账号判断是否包含所有该算进去的套餐。它确保团队、商业、企业、教育套餐会被识别为工作区账号，而个人 Pro 不会。

数据流：进去的是多个套餐值 → 调用 PlanType::is_workspace_account → 对每个返回结果做真假校验，确认工作区和非工作区没有分错。

调用关系：它保护 PlanType::is_workspace_account 这条大分类规则。以后如果新增或调整套餐，这个测试能帮助发现工作区相关功能是否会漏开或误开。

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

fn auth_plan_type_converts_to_account_plan_type()

作用：测试认证模块里的套餐能不能正确转换成本文件里的账号套餐。它也检查未知套餐会不会被安全地标成 Unknown。

数据流：进去的是认证模块的套餐值，包括已知套餐和一个模拟的未知字符串 → 调用 PlanType::from 做转换 → 检查输出是不是对应的账号 PlanType。

调用关系：它验证认证层和协议层之间的“翻译”是否可靠。这样登录系统返回套餐后，账号接口拿到的类型就能保持一致；未知套餐也会被稳妥处理，而不是造成错误。

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

fn new(command: Vec<String>) -> Self

作用：创建一个“执行策略补丁”，意思是把某个命令开头加入允许名单，以后类似命令可以少问一次批准。调用者传入一串命令词，它包装成统一的数据格式。

数据流：进去的是一个字符串列表，比如命令及参数的前缀 → 函数把它放进 ExecPolicyAmendment 的 command 字段里 → 出来的是一个新的 ExecPolicyAmendment 对象，没有改动外部状态。

调用关系：这是 ExecPolicyAmendment 的便捷构造入口。别的代码在准备向用户展示“以后允许这类命令吗”时，可以用它快速生成提案。

fn command(&self) -> &[String]

作用：取出这个策略补丁里保存的命令前缀。它让外部只读查看命令内容，而不是直接拿走内部数据。

数据流：进去的是已有的 ExecPolicyAmendment 自身 → 函数读取其中的 command 字段 → 出来的是对命令字符串列表的只读引用，不复制也不修改。

调用关系：它是读取 ExecPolicyAmendment 内容的小窗口。需要展示、比较或写入策略时，其他代码可以通过它看到这条补丁要允许哪类命令。

fn from(command: Vec<String>) -> Self

作用：把一个普通的字符串列表直接转换成 ExecPolicyAmendment。这样调用者可以用更自然的写法生成策略补丁。

数据流：进去的是 Vec<String>，也就是一串命令词 → 函数把这串词放入 command 字段 → 出来的是 ExecPolicyAmendment，原来的列表所有权被移进去。

调用关系：这是 Rust 的 From 转换接口，用来配合通用转换写法。它和 ExecPolicyAmendment::new 做的事基本一样，只是让调用方式更顺手。

fn effective_approval_id(&self) -> String

作用：找出这次审批真正应该使用的编号。有些审批有单独的 approval_id；没有的话，就退回使用命令本身的 call_id。

数据流：进去的是一个 ExecApprovalRequestEvent，里面可能有 approval_id，也一定有 call_id → 函数先看 approval_id 是否存在，存在就复制它，不存在就复制 call_id → 出来的是一个字符串编号，不修改原请求。

调用关系：handle_exec_approval 和 handle_exec_approval_now 在处理命令审批时会用它。这样无论是普通命令审批，还是被拦截出来的子命令审批，后续流程都能拿到一个统一可用的审批编号。

调用图：被 2 处调用（handle_exec_approval, handle_exec_approval_now）。

fn effective_available_decisions(&self) -> Vec<ReviewDecision>

作用：算出这次审批界面应该给用户哪些选择。新请求可以直接带 available_decisions；老请求没带时，它会按旧规则自己推导。

数据流：进去的是一个命令审批请求，可能包含明确的可选决定，也可能只包含网络、策略补丁、额外权限等信息 → 如果 available_decisions 存在，就复制这份列表；如果不存在，就把相关字段交给默认规则计算 → 出来的是 ReviewDecision 列表，也就是用户可点的选项。

调用关系：handle_exec_approval_now 在马上处理审批时会调用它。它在新旧协议之间起桥梁作用：新客户端按新字段走，旧发送方也不会因为少字段而坏掉；需要推导时，它把工作交给 ExecApprovalRequestEvent::default_available_decisions。

调用图：被 1 处调用（handle_exec_approval_now）；外部调用 1 个（default_available_decisions）。

fn default_available_decisions(
        network_approval_context: Option<&NetworkApprovalContext>,
        proposed_execpolicy_amendment: Option<&ExecPolicyAmendment>,
        proposed_network_policy_

作用：按老规则生成默认审批选项。它根据请求的类型决定给用户“允许一次”“本会话允许”“修改网络策略”“修改执行策略”或“中止”等选择。

数据流：进去的是几类可选上下文：是否是网络审批、是否有执行策略补丁、是否有网络策略补丁、是否申请额外权限 → 函数按优先级判断：网络请求走网络选项，额外权限请求只给允许或中止，普通命令请求给允许、可选的策略放行、再加中止 → 出来的是一个 ReviewDecision 列表。

调用关系：它是 effective_available_decisions 的后备规则库。当前端或上游没有明确告诉系统该显示哪些按钮时，这个函数负责补上一套兼容旧行为的按钮组合。

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

fn message(&self) -> &str

作用：从一次“向用户追问信息”的请求里取出要展示给用户看的提示语。不管请求是表单模式还是网址模式，都能用同一个方法拿到 message。

数据流：进去的是 ElicitationRequest，可能是 Form，也可能是 Url → 函数匹配具体类型，并读取其中的 message 字段 → 出来的是一段字符串引用，不复制也不修改请求。

调用关系：它给展示层或处理层提供统一入口。调用者不用关心追问是表单还是链接，只要想显示提示文字，就调用这个方法。

fn guardian_assessment_action_deserializes_command_shape()

作用：测试“命令审查动作”的 JSON 能不能正确读成 Rust 数据。简单说，就是确认外部传来的 command 格式不会被系统误解。

数据流：进去的是测试里手写的一段 JSON，包含 type、source、command 和 cwd → 测试用 serde_json 把它解析成 GuardianAssessmentAction → 最后断言解析结果等于预期的 Command 结构，测试通过则说明格式兼容。

调用关系：这是测试代码，只在跑测试时活跃。它调用 JSON 构造、反序列化和断言工具，保护 GuardianAssessmentAction::Command 这种协议形状不被后续改代码时弄坏。

调用图：外部调用 3 个（assert_eq!, from_value, json!）。

fn guardian_assessment_action_round_trips_execve_shape()

作用：测试 execve 形式的审查动作能“读进来再写出去”仍保持原样。execve 可以理解为更底层的程序启动格式，包含程序名和参数列表。

数据流：进去的是一段 execve JSON，里面有 program、argv 和 cwd → 测试先把 JSON 解析成 GuardianAssessmentAction，再把这个对象序列化回 JSON → 最后检查回写的 JSON 和原始 JSON 一样，并检查内部数据也符合预期。

调用关系：这是 Unix 平台上的测试，只在测试阶段运行。它用来保证 GuardianAssessmentAction::Execve 的协议格式稳定，避免前端、后端或审查器之间因为字段变化而对不上。

调用图：外部调用 3 个（assert_eq!, from_value, json!）。

fn from_raw_value(raw: &str) -> Self

作用：把服务器或配置里拿到的原始套餐字符串，转换成系统内部认识的 PlanType。这样后面的代码不用到处比较字符串，只要判断标准化后的套餐类型。

数据流：进去的是一个原始文本，比如“PLUS”“hc”或一个从没见过的新套餐名。它先把文本转成小写，再按已知名单逐个匹配；匹配上就产出 KnownPlan 包装成的已知套餐，匹配不上就把原文保存成 Unknown。结果是一个 PlanType，不会因为遇到陌生套餐名就丢信息。

调用关系：它是套餐字符串进入系统后的翻译入口之一。它会创建 KnownPlan 对应的已知值，或者创建 Unknown 保存未知值；后续显示、权限判断、账号类型判断就可以基于这个结果继续做。

调用图：外部调用 2 个（Known, Unknown）。

fn display_name(self) -> &'static str

作用：把内部套餐枚举变成适合给人看的名字。比如内部叫 ProLite，显示时变成“Pro Lite”。

数据流：进去的是一个已知套餐值。它根据套餐是哪一种，挑出固定的英文展示名；不修改任何状态。出来的是一段静态文本，可以直接放到界面、日志或提示信息里。

调用关系：它通常用在需要把套餐信息展示给用户或写进可读日志的时候。它不再调用别的项目函数，只负责把机器内部的代号换成人更容易读的名称。

fn raw_value(self) -> &'static str

作用：把内部套餐枚举变回服务器使用的原始字符串。这样系统要发请求、保存数据或比较协议值时，可以用统一的标准写法。

数据流：进去的是一个已知套餐值。它查表返回对应的协议字符串，比如 ProLite 返回“prolite”，Enterprise 返回“enterprise”。出来的是固定字符串，不改动外部数据。

调用关系：它和 PlanType::from_raw_value 像一进一出两道门：from_raw_value 负责把外部字符串读进来，raw_value 负责把内部套餐再按协议格式写出去。

fn is_workspace_account(self) -> bool

作用：判断一个套餐是不是工作区类账号，也就是更像团队、企业、教育组织使用的账号，而不是个人免费或个人付费账号。

数据流：进去的是一个已知套餐。它检查这个套餐是否属于 Team、Business、Enterprise、Edu 等组织类套餐名单；如果是就返回 true，否则返回 false。不改变任何数据。

调用关系：它会在代码需要区分个人账号和组织/工作区账号时被调用。内部用 matches! 这个 Rust 匹配工具做判断，像拿套餐去一张名单上勾选一样。

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

fn new(reason: RefreshTokenFailedReason, message: impl Into<String>) -> Self

作用：创建一个“刷新令牌失败”的错误对象，同时带上失败原因和给人看的错误信息。这样调用方既能机器判断原因，也能把信息展示或记录下来。

数据流：进去的是一个失败原因，比如过期或被撤销，以及一段错误说明。它把说明转换成 String 字符串，和原因一起装进 RefreshTokenFailedError。出来的是一个完整错误值，供上层返回、记录或继续分类处理。

调用关系：它会被刷新登录令牌的流程使用，例如 refresh_token、next、classify_refresh_token_failure 这些地方在确认失败原因后，会调用它把原因和说明打包成统一错误。测试 refresh_failure_is_scoped_to_the_matching_auth_snapshot 也会用它来验证错误是否只影响对应的认证状态。

调用图：被 4 处调用（refresh_failure_is_scoped_to_the_matching_auth_snapshot, refresh_token, next, classify_refresh_token_failure）；外部调用 1 个（into）。

fn plan_type_deserializes_raw_aliases()

作用：这是一个测试，用来确认旧别名或替代名字也能被正确读成标准套餐。比如“hc”应该算 Enterprise，“education”应该算 Edu。

数据流：进去的是两段 JSON 字符串测试数据：“hc”和“education”。测试用 serde_json 把它们读成 PlanType，然后用 assert_eq! 比较结果是不是预期的已知套餐。如果不一致，测试会失败，提醒开发者别把兼容规则改坏了。

调用关系：它由测试运行器在跑测试时调用，不参与正式运行。它保护的是 PlanType 和 KnownPlan 上的反序列化规则，确保服务器还在使用旧名字或别名时，客户端仍然能正确理解。

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

fn as_str(&self) -> &str

作用：把已经验证过的 profile 名字当作普通字符串拿出来用。别人需要拼配置文件名或显示这个名字时，会用它。

数据流：进去的是一个 ProfileV2Name 对象 → 它不改任何内容，只取出内部保存的那段文字 → 出来的是一个字符串引用，还是原来的名字。

调用关系：它是 ProfileV2Name 最基础的取值口。ProfileV2Name::deref 会调用它，让这个类型在很多地方可以像普通字符串一样使用。

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

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

作用：把 profile 名字解析失败的原因写成人能看懂的错误消息。这样用户输错 --profile 时，不会只看到生硬的内部错误。

数据流：进去的是错误对象和一个用来写文字的格式化器 → 它把错误里保存的原始输入塞进提示语 → 出来的是格式化结果，外面可以显示给用户。

调用关系：当 ProfileV2Name::from_str 发现名字不合法时会生成这个错误；之后错误被打印或展示时，这个函数负责把它变成一句清楚的话。

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

fn from_str(value: &str) -> Result<Self, Self::Err>

作用：检查用户给的 profile 名是不是安全的普通名字。它拒绝空名字，也拒绝点号、斜杠等路径字符，防止用户借 profile 参数去读任意文件。

数据流：进去的是一段用户输入的文字 → 它逐个检查字符，只允许英文字母、数字、下划线和短横线 → 合法就产出 ProfileV2Name，不合法就产出 ProfileV2NameParseError。

调用关系：这是把命令行或配置里的 profile 字符串变成安全类型的入口。后面的代码只要拿到 ProfileV2Name，就可以相信它不是路径。

fn deref(&self) -> &Self::Target

作用：让 ProfileV2Name 在需要字符串的场合更顺手地使用。可以把它理解成给这个安全名字开了一个“像字符串一样看待”的小门。

数据流：进去的是 ProfileV2Name → 它调用 ProfileV2Name::as_str 取内部文字 → 出来的是字符串引用，不会复制也不会修改。

调用关系：它把实际取值工作交给 ProfileV2Name::as_str。很多 Rust 标准用法会自动借助这个函数，把自定义名字类型当作 str 来读。

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

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

作用：决定 ProfileV2Name 被打印时显示什么。它直接显示内部保存的 profile 名字。

数据流：进去的是 ProfileV2Name 和格式化器 → 它把内部字符串写入格式化器 → 出来的是格式化结果，内容就是 profile 名。

调用关系：当日志、错误提示或界面需要展示 profile 名时会间接用到它。它不做校验，因为校验已经在 ProfileV2Name::from_str 做过。

fn schema_name() -> String

作用：给“审批由谁来审”这个配置项生成 JSON Schema 名字。JSON Schema 是一种机器可读的配置说明书。

数据流：进去没有业务数据 → 它返回固定文字 ApprovalsReviewer → 出来的是 schema 里使用的类型名。

调用关系：它属于 JsonSchema 支持代码。生成配置文档或校验规则时，schema 系统会调用它来给这个枚举命名。

fn json_schema(_generator: &mut SchemaGenerator) -> Schema

作用：告诉配置文档：审批审查人这个字段允许填哪些字符串，以及这些值是什么意思。它还保留旧名字 guardian_subagent，方便老配置继续可用。

数据流：进去的是 schema 生成器，但这里不用它 → 它列出 user、auto_review、guardian_subagent，并附上一段说明 → 出来的是一份字符串枚举 schema。

调用关系：它把具体造 schema 的活交给 string_enum_schema_with_description。配置文档生成器或校验器需要描述 ApprovalsReviewer 时会用到它。

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

fn default() -> Self

作用：给运行 shell 命令时的环境变量策略提供默认值。没有用户特殊配置时，系统就按这套安全且兼容的规则来。

数据流：进去没有输入 → 它创建一个策略：继承全部环境变量、不启用默认敏感名过滤、没有额外排除或只保留规则、不使用 shell profile → 出来的是完整的默认 ShellEnvironmentPolicy。

调用关系：很多创建运行环境的流程会把它当起点，例如从审批和 profile 生成配置、给 agent 启动配置补环境变量、测试默认环境行为等。

调用图：被 7 处调用（from_approval_and_profile, populate_env_inserts_thread_id, populate_env_omits_thread_id_when_missing, test_core_inherit_defaults_keep_sensitive_vars, build_agent_spawn_config_uses_turn_context_values, create_env_from_core_vars, create_env_from_core_vars）；外部调用 2 个（new, new）。

fn string_enum_schema_with_description(values: &[&str], description: &str) -> Schema

作用：快速造一份“这个字段只能是这些字符串之一”的 JSON Schema，并带上人类说明。它避免每个枚举都重复写同样的 schema 组装代码。

数据流：进去的是一组允许值和一段说明文字 → 它创建一个字符串类型的 schema，把允许值放进枚举列表，把说明放进元数据 → 出来的是 Schema 对象。

调用关系：ApprovalsReviewer::json_schema 调用它。它是这个文件里的小工具，只负责把一组选项包装成标准说明书格式。

调用图：被 1 处调用（json_schema）；外部调用 3 个（new, default, Object）。

fn merge(&self, other: &Self) -> Self

作用：把两份网页搜索地点信息合成一份，并让后来的配置优先。就像先填默认地址，再用用户新填的字段覆盖其中一部分。

数据流：进去的是当前地点和另一份地点 → 对国家、地区、城市、时区逐项检查，另一份有值就用另一份，没有就保留当前值 → 出来的是合并后的新地点。

调用关系：WebSearchToolConfig::merge 在合并网页搜索工具配置时会用到它，专门处理 location 这个嵌套字段。

fn merge(&self, other: &Self) -> Self

作用：把两份网页搜索工具配置合并成一份，适合处理“默认配置 + 用户覆盖配置”的场景。

数据流：进去的是当前配置和另一份配置 → context_size 和 allowed_domains 优先采用另一份的非空值；location 如果两边都有，就逐项合并 → 出来的是新的 WebSearchToolConfig，不会改原对象。

调用关系：它是网页搜索配置叠加时的核心方法。遇到地点信息时，它把更细的合并工作交给 WebSearchLocation::merge。

fn from(location: WebSearchLocation) -> Self

作用：把内部使用的网页搜索地点格式，转换成发送给网页搜索接口的用户地点格式。

数据流：进去的是 WebSearchLocation，里面可能有国家、地区、城市、时区 → 它把这些字段原样搬过去，并把类型设为 approximate（大致位置）→ 出来的是 WebSearchUserLocation。

调用关系：WebSearchConfig::from 在把工具配置转成最终搜索配置时会调用这个转换。它负责地点这一小块格式对接。

fn from(config: WebSearchToolConfig) -> Self

作用：把较简洁的网页搜索工具配置，转换成接口真正需要的网页搜索配置结构。

数据流：进去的是 WebSearchToolConfig → 它把 allowed_domains 包成 filters，把 location 转成 user_location，把 context_size 改名放到 search_context_size → 出来的是 WebSearchConfig。

调用关系：当系统准备调用网页搜索功能时，会需要这种更贴近接口的配置。地点转换会交给 WebSearchUserLocation::from。

fn request_value(self) -> &'static str

作用：把内部的服务等级选项转换成请求接口认识的字符串。比如内部叫 Fast，请求里实际要写 priority。

数据流：进去的是 ServiceTier 枚举值 → 它按固定表转换：Fast 变 priority，Flex 变 flex → 出来的是可放进请求的字符串。

调用关系：发送模型请求时会用它来填写服务等级字段。它把用户和内部代码的叫法，翻译成后端接口的叫法。

fn from_request_value(value: &str) -> Option<Self>

作用：把请求或配置里的服务等级字符串读回内部枚举。它兼容 fast 和 priority 两种说法，都当作 Fast。

数据流：进去的是一段字符串 → 它匹配 fast、priority、flex → 匹配成功就返回对应 ServiceTier，匹配不到就返回 None 表示不认识。

调用关系：配置应用流程 apply 会调用它，把外部传来的文字解释成内部能安全使用的选项。

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

fn timeout(&self) -> Duration

作用：把模型供应商认证命令的超时时间，从毫秒数字变成 Duration（时间长度对象）。这样运行命令的代码可以直接拿去计时。

数据流：进去的是 ModelProviderAuthInfo → 它读取 timeout_ms 这个非零毫秒数 → 出来的是对应的 Duration。

调用关系：执行获取 bearer token（访问令牌）命令时会用到它。它只负责把配置里的数字翻译成计时器能用的格式。

调用图：外部调用 2 个（from_millis, get）。

fn refresh_interval(&self) -> Option<Duration>

作用：决定缓存的认证令牌多久主动刷新一次。配置为 0 时，表示不主动刷新，只等接口返回 401 之类的失败后再重试。

数据流：进去的是 ModelProviderAuthInfo → 它读取 refresh_interval_ms；如果是 0，就返回 None；如果非零，就转成 Duration → 出来的是可选的刷新间隔。

调用关系：认证令牌缓存逻辑会用它判断何时重新运行取 token 的命令。它把“0 有特殊含义”这件事封装起来。

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

fn default_provider_auth_timeout_ms() -> NonZeroU64

作用：提供模型供应商认证命令的默认超时时间：5000 毫秒。这样用户没配置时，命令不会无限等下去。

数据流：进去没有输入 → 它把默认数字 5000 交给 non_zero_u64 检查并包装成非零数 → 出来的是 NonZeroU64。

调用关系：反序列化 ModelProviderAuthInfo 时，如果 timeout_ms 没写，会调用它。它依赖 non_zero_u64 保证默认值绝不为 0。

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

fn default_provider_auth_refresh_interval_ms() -> u64

作用：提供模型供应商认证令牌的默认主动刷新间隔：300000 毫秒，也就是 5 分钟。

数据流：进去没有输入 → 它直接返回固定数字 300000 → 出来的是毫秒数。

调用关系：反序列化 ModelProviderAuthInfo 时，如果 refresh_interval_ms 没写，会用它填默认值。后续 ModelProviderAuthInfo::refresh_interval 会把它转成时间长度。

fn non_zero_u64(value: u64, field_name: &str) -> NonZeroU64

作用：把普通整数变成“保证不是 0 的整数”。如果传进来的是 0，它会立刻报错，因为某些配置字段不能接受 0。

数据流：进去的是一个 u64 数字和字段名 → 它尝试创建 NonZeroU64；成功就返回，失败就用字段名 panic 报错 → 出来的是非零整数，或者程序在开发错误下停止。

调用关系：default_provider_auth_timeout_ms 调用它来保护默认超时时间。这个函数主要防止代码里写错默认值，而不是处理普通用户输入。

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

fn default_provider_auth_cwd() -> AbsolutePathBuf

作用：给运行认证命令时的工作目录提供默认值。优先表示当前目录，实在解析不了才取进程当前目录。

数据流：进去没有输入 → 它先尝试把字符串 . 解析成绝对路径；成功就返回；失败则读取当前工作目录；如果连当前目录也拿不到，就 panic → 出来的是 AbsolutePathBuf。

调用关系：ModelProviderAuthInfo 的 cwd 字段没配置时会用这个默认值。is_default_provider_auth_cwd 也会调用它来判断某个路径是不是默认值。

调用图：调用 2 个内部函数（current_dir, deserialize）；被 1 处调用（is_default_provider_auth_cwd）；外部调用 2 个（panic!, new）。

fn is_default_provider_auth_cwd(path: &AbsolutePathBuf) -> bool

作用：判断某个认证命令工作目录是不是默认目录。这个判断常用于序列化时省略默认字段，让输出配置更干净。

数据流：进去的是一个绝对路径 → 它调用 default_provider_auth_cwd 得到默认路径，再和输入路径比较 → 出来的是 true 或 false。

调用关系：它服务于 ModelProviderAuthInfo 的 schema/序列化行为。为了知道默认值是什么，它把计算默认目录的工作交给 default_provider_auth_cwd。

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

fn display_name(self) -> &'static str

作用：把协作模式的内部名字变成界面上好读的名字。比如 PairProgramming 会显示成 Pair Programming。

数据流：进去的是 ModeKind → 它按固定表选择展示文字 → 出来的是静态字符串。

调用关系：当系统需要告诉用户某个模式叫什么，比如生成“当前模式不能请求用户输入”的提示时，会调用它。

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

fn is_tui_visible(self) -> bool

作用：判断某个协作模式是否应该出现在 TUI（终端用户界面）的可选列表里。隐藏的旧模式或内部模式不会显示给用户。

数据流：进去的是 ModeKind → 它检查是否为 Plan 或 Default → 出来的是布尔值，表示界面是否可见。

调用关系：mask_for_kind 会用它筛选可展示模式。测试也会确认可见模式列表和这个判断保持一致。

调用图：被 1 处调用（mask_for_kind）；外部调用 1 个（matches!）。

fn allows_request_user_input(self) -> bool

作用：判断这个协作模式是否允许主动请求用户补充输入。目前只有 Plan 模式允许。

数据流：进去的是 ModeKind → 它检查是否为 Plan → 出来的是 true 或 false。

调用关系：需要决定能不能打断流程、向用户提问时会用它。它把这个规则集中放在模式类型旁边，避免各处写散。

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

fn settings_ref(&self) -> &Settings

作用：拿到协作模式里的 settings 配置引用。它是内部小帮手，避免其他方法重复写取字段的代码。

数据流：进去的是 CollaborationMode → 它返回内部 settings 的只读引用 → 出来的是 Settings 引用，不会复制也不会修改。

调用关系：CollaborationMode::model、reasoning_effort、with_updates 和 apply_mask 都会调用它，先拿到设置，再读取或生成更新后的设置。

调用图：被 4 处调用（apply_mask, model, reasoning_effort, with_updates）。

fn model(&self) -> &str

作用：读取当前协作模式使用的模型名。外部需要知道当前会调用哪个模型时会用它。

数据流：进去的是 CollaborationMode → 它通过 settings_ref 找到设置，再取 model 字符串 → 出来的是模型名引用。

调用关系：thread_config_snapshot 会调用它，把当前线程或会话的模型配置记录成快照。实际取 settings 的动作交给 CollaborationMode::settings_ref。

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

fn reasoning_effort(&self) -> Option<ReasoningEffort>

作用：读取当前协作模式设置的推理强度。推理强度可以理解成让模型思考得更省、更普通或更深入的选项。

数据流：进去的是 CollaborationMode → 它通过 settings_ref 读取 reasoning_effort，并复制出一个可选值 → 出来的是 Some 强度或 None。

调用关系：thread_config_snapshot 会调用它记录当前配置。它不判断默认值，只如实返回这个模式里存的设置。

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

fn with_updates(
        &self,
        model: Option<String>,
        effort: Option<Option<ReasoningEffort>>,
        developer_instructions: Option<Option<String>>,
    ) -> Self

作用：基于当前协作模式生成一份更新后的新模式，可以改模型、推理强度和开发者说明，也可以选择保持原样。

数据流：进去的是当前 CollaborationMode，以及三个可选更新项 → 它没给更新的字段保留旧值，给了更新的字段就替换；可选字段还能被明确清空 → 出来的是新的 CollaborationMode，原对象不变。

调用关系：with_model 会调用它来做局部更新。它先通过 settings_ref 读取旧设置，再拼出新的 Settings。

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

fn apply_mask(&self, mask: &CollaborationModeMask) -> Self

作用：把一个“遮罩配置”套到当前协作模式上，只覆盖遮罩里明确写了的字段。遮罩像一张透明改字贴，没写的地方就露出原配置。

数据流：进去的是当前 CollaborationMode 和 CollaborationModeMask → 它忽略 mask 的 name，只用其中非空的 mode、model、reasoning_effort、developer_instructions 覆盖旧值 → 出来的是新 CollaborationMode。

调用关系：它用于根据预设或配置片段调整协作模式。读取旧设置时调用 settings_ref；测试 apply_mask_can_clear_optional_fields 专门确认它能清空可选字段。

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

fn apply_mask_can_clear_optional_fields()

作用：验证 apply_mask 不只会设置新值，也能把原本有值的可选字段清空。这对关闭推理强度或开发者说明很重要。

数据流：进去的是测试里手工构造的模式和遮罩 → 遮罩把 reasoning_effort 和 developer_instructions 设为 Some(None) → 断言输出的新模式里这两个字段确实变成 None。

调用关系：这是 CollaborationMode::apply_mask 的安全网。以后有人改合并规则，如果破坏“可以清空字段”的行为，这个测试会失败。

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

fn mode_kind_deserializes_alias_values_to_default()

作用：验证旧的协作模式名字仍然能被读进来，并统一变成 Default。这样老配置不会因为改名就坏掉。

数据流：进去的是测试里的别名列表 code、pair_programming、execute、custom → 每个别名被包装成 JSON 字符串并反序列化 → 断言结果都是 ModeKind::Default。

调用关系：它保护 ModeKind 上的 serde alias 设置。配置加载代码依赖这些别名兼容历史配置。

调用图：外部调用 3 个（assert_eq!, format!, from_str）。

fn approvals_reviewer_serializes_auto_review_and_accepts_legacy_guardian_subagent()

作用：验证审批审查人字段的读写格式正确，尤其是新名字 auto_review 和旧名字 guardian_subagent 的兼容。

数据流：进去的是几个固定枚举值和字符串 → 它检查序列化输出是不是 user 或 auto_review，再把 user、auto_review、guardian_subagent 读回来 → 断言读出的枚举符合预期。

调用关系：它保护 ApprovalsReviewer 的配置兼容性。生成 schema 的代码说明了旧值可接受，这个测试确认实际解析也真的接受。

调用图：外部调用 3 个（assert_eq!, format!, from_str）。

fn profile_v2_name_rejects_paths_and_empty_names()

作用：验证 profile 名不会接受路径或空字符串。这是防止用户通过 profile 参数访问任意文件的重要安全测试。

数据流：进去的是 ../foo 和空字符串两个非法输入 → 它调用 ProfileV2Name::from_str → 断言得到的错误里保留了对应输入。

调用关系：它直接保护 ProfileV2Name::from_str 的校验规则。以后如果有人放宽字符限制，这个测试会提醒风险。

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

fn tui_visible_collaboration_modes_match_mode_kind_visibility()

作用：验证 TUI 显示的协作模式列表和 ModeKind::is_tui_visible 的判断一致。这样界面不会漏显示或误显示内部模式。

数据流：进去的是固定的可见模式数组 → 它断言数组等于 Default 和 Plan，并逐个检查它们可见，同时确认隐藏模式不可见 → 出来是测试通过或失败。

调用关系：它保护 TUI_VISIBLE_COLLABORATION_MODES 常量和 ModeKind::is_tui_visible 之间的一致性。界面筛选逻辑依赖这两者不打架。

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

fn web_search_location_merge_prefers_overlay_values()

作用：验证网页搜索地点合并时，覆盖配置里的字段优先，但没写的字段会保留原值。

数据流：进去的是 base 地点和 overlay 地点 → 调用 WebSearchLocation::merge → 断言地区和城市采用 overlay，国家和时区保留 base。

调用关系：它保护 WebSearchLocation::merge 的覆盖规则。WebSearchToolConfig::merge 依赖这个规则合并嵌套地点。

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

fn web_search_tool_config_merge_prefers_overlay_values()

作用：验证整份网页搜索工具配置合并时，覆盖配置优先，同时嵌套地点会逐项合并。

数据流：进去的是带 context_size、allowed_domains、location 的 base 配置，以及一份 overlay 配置 → 调用 WebSearchToolConfig::merge → 断言 context_size 被覆盖，allowed_domains 被保留，location 被逐项合并。

调用关系：它保护 WebSearchToolConfig::merge 的整体行为，并间接确认它正确使用 WebSearchLocation::merge。

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

fn normalize_dynamic_tool_specs(
    values: Vec<JsonValue>,
) -> Result<Vec<DynamicToolSpec>, serde_json::Error>

作用：这个函数把一批动态工具配置整理成系统现在统一使用的格式。它的用处是兼容新旧两种写法，但不允许一半新格式、一半旧格式混在一起，避免系统误解工具清单。

数据流：进去的是一组 JSON 值，也就是还没完全确定形状的工具配置。函数先看里面有没有旧格式特征，比如 namespace、exposeToContext，或者缺少 type；也看有没有新格式特征，也就是带 type。如果发现新旧混用，就返回错误。若全是新格式，就直接逐个解析成 DynamicToolSpec。若是旧格式，就先解析成 LegacyDynamicToolSpec，再把 exposeToContext 这种旧字段换算成 deferLoading，最后按命名空间重新分组，输出新的 DynamicToolSpec 列表。

调用关系：它是动态工具配置进入系统时的“格式清洗员”。命令行参数解析 parse_dynamic_tools_arg 会用它，反序列化入口 deserialize_dynamic_tool_specs 也会用它。遇到旧格式需要整理时，它会把分组工作交给 group_dynamic_tools_by_namespace。

调用图：调用 1 个内部函数（group_dynamic_tools_by_namespace）；被 2 处调用（parse_dynamic_tools_arg, deserialize_dynamic_tool_specs）；外部调用 1 个（custom）。

fn group_dynamic_tools_by_namespace(
    tools: Vec<(Option<String>, DynamicToolFunctionSpec)>,
) -> Vec<DynamicToolSpec>

作用：这个函数把带有可选命名空间的工具函数整理成最终的工具列表。没有命名空间的工具保持为单独函数；有同一个命名空间的工具会被放进同一个工具组里。

数据流：进去的是一串二元组：每项包含一个可能为空的命名空间名字，以及一个工具函数说明。函数从头遍历：如果没有命名空间，就直接放进结果列表；如果有命名空间，就查这个命名空间之前有没有创建过。创建过就把工具追加进去；没创建过就新建一个命名空间条目，并记录它在结果列表里的位置。最后出来的是按新结构组织好的 DynamicToolSpec 列表。

调用关系：它是 normalize_dynamic_tool_specs 处理旧格式时调用的“小整理工”。normalize_dynamic_tool_specs 先把旧工具读成函数，再让它按 namespace 合并成新格式里的 Namespace。它本身不读取外部数据，也不负责判断新旧格式，只专心做分组。

调用图：被 1 处调用（normalize_dynamic_tool_specs）；外部调用 8 个（new, new, with_capacity, Function, Function, Namespace, unreachable!, vec!）。

fn deserialize_dynamic_tool_specs(
    deserializer: D,
) -> Result<Option<Vec<DynamicToolSpec>>, D::Error>

作用：这个函数专门给 serde 反序列化使用。serde 是 Rust 里常用的“把 JSON 等数据变成程序结构”的工具；这里它负责在读取动态工具字段时，顺手做格式兼容和规范化。

数据流：进去的是一个反序列化器，也就是 serde 提供的数据读取通道。函数先尝试把字段读成可选的 JSON 数组：如果字段不存在或是空的可选值，就返回 None。若读到了数组，就交给 normalize_dynamic_tool_specs 统一整理；成功后包成 Some 返回，失败则把错误转换成反序列化错误返回。

调用关系：它位于配置或会话数据被读取的入口处。外部代码不需要先手动判断工具格式，只要在字段上使用这个反序列化函数，它就会调用 normalize_dynamic_tool_specs 完成新旧格式兼容。

调用图：调用 1 个内部函数（normalize_dynamic_tool_specs）；外部调用 1 个（deserialize）。

fn from(_: CancelErr) -> Self

作用：把取消操作的错误转换成 Codex 自己认识的错误。这样别的地方只需要处理 CodexErr，不用到处认识各种外部错误类型。

数据流：进去的是一个 CancelErr，也就是“任务被取消”的信号；函数不关心里面的细节，直接把它解释成一次对话回合被中止；出来的是 CodexErr::TurnAborted。

调用关系：它是自动转换用的小桥。任何地方遇到取消错误并需要返回 CodexErr 时，Rust 可以自动走到这里，让上层统一按“本轮中止”处理。

fn is_retryable(&self) -> bool

作用：判断一个错误值不值得自动再试一次。比如网络断了可能能重试，额度用完或请求本身不合法就不该重试。

数据流：进去的是一个 CodexErr；函数按错误种类查表式地分类；出来的是 true 或 false，表示上层流程是否可以自动重试。

调用关系：它通常被会话循环、请求发送逻辑或重试控制器使用。它不修复错误，只给出“要不要再试”的判断，避免对永久失败做无意义重试。

fn downcast_ref(&self) -> Option<&T>

作用：提供一个兼容旧代码的小接口，让旧代码还能用“看看这个错误是不是某种具体类型”的写法。

数据流：进去的是当前 CodexErr 和想检查的目标类型；函数把自己临时当成通用类型来尝试匹配；如果类型对得上就返回引用，对不上就返回空。

调用关系：它主要是迁移时期的兼容垫片。旧代码原来可能依赖 anyhow 这类通用错误库的 downcast_ref，这里让调用方不用大改也能继续编译。

fn to_codex_protocol_error(&self) -> CodexErrorInfo

作用：把内部错误翻译成协议层能理解的错误类别。客户端不需要知道 Rust 内部有多少错误分支，只需要收到一个稳定的错误类型。

数据流：进去的是一个具体的 CodexErr；函数按类别把它映射成 CodexErrorInfo，比如额度问题、服务器过载、沙箱错误、认证失败等；有些网络类错误还会带上 HTTP 状态码，也就是网页请求返回的数字状态。

调用关系：它会调用 CodexErr::http_status_code_value 取状态码，并被 CodexErr::to_error_event 使用。它站在内部错误和外部协议之间，像翻译官一样把复杂错误压成客户端可消费的信息。

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

fn to_error_event(&self, message_prefix: Option<String>) -> ErrorEvent

作用：把一个错误包装成可以发给客户端的错误事件。这个事件里既有人看的文字，也有机器看的错误分类。

数据流：进去的是 CodexErr 和一个可选的消息前缀；函数先把错误转成文字，再按需加上前缀，然后调用 to_codex_protocol_error 得到协议错误类型；出来的是 ErrorEvent。

调用关系：当系统需要把错误通过协议流发出去时会用它。它把展示文案和机器分类合在一起，方便前端既能显示，也能做特殊处理。

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

fn http_status_code_value(&self) -> Option<u16>

作用：从错误里尽量取出 HTTP 状态码。HTTP 状态码就是服务器请求结果的数字，比如 403 表示禁止访问、500 表示服务器内部错误。

数据流：进去的是一个 CodexErr；函数只检查那些可能带状态码的错误，如重试耗尽、异常状态、连接失败、响应流失败；出来的是一个可选的 u16 数字，没有就返回空。

调用关系：它被 CodexErr::to_codex_protocol_error 使用，也会被其他错误上报路径使用，比如 from_codex_err 和 notify_stream_error。它负责把藏在底层网络错误里的状态码挖出来。

调用图：被 3 处调用（from_codex_err, notify_stream_error, to_codex_protocol_error）。

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

作用：把“连接失败”错误变成一句能打印的文字。这样日志和用户提示里不会只看到难懂的结构体。

数据流：进去的是 ConnectionFailedError，里面包含 reqwest 的网络错误；函数把底层错误拼到“Connection failed”后面；出来的是写入格式化器的一段文本。

调用关系：当有人调用 to_string、打印错误或把它放进 CodexErr 显示时，会走到这里。它不改变错误，只负责把它说清楚。

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

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

作用：把“读取服务器响应流时失败”变成一段说明文字，并尽量带上请求编号，方便排查。

数据流：进去的是 ResponseStreamFailed，里面有网络错误和可选 request id；函数生成“读取服务器响应时出错”的消息，如果有请求编号就附上；出来的是可打印文本。

调用关系：服务器已经开始回应但中途断掉时，这类错误会被显示或记录。它给排障人员留下 request id 这类线索。

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

fn display_body(&self) -> String

作用：决定服务器异常响应的正文该怎么显示。它会优先提取清楚的错误消息，不行再显示截短后的原文。

数据流：进去的是 UnexpectedResponseError，主要读取 body；函数先调用 extract_error_message 尝试从 JSON 里拿 error.message，拿不到就去掉空白并检查是否为空，最后必要时调用 truncate_with_ellipsis 截短；出来的是适合显示的正文文字。

调用关系：它被 UnexpectedResponseError::fmt 调用，是异常 HTTP 响应文案的一部分。它让错误提示既尽量有用，又不会被超长响应淹没。

调用图：调用 2 个内部函数（extract_error_message, truncate_with_ellipsis）；被 1 处调用（fmt）。

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

作用：从服务器返回的 JSON 正文里找出真正的人类可读错误消息。很多接口会把错误放在 error.message 这个位置。

数据流：进去的是响应正文字符串；函数尝试把它当 JSON 解析，再一路找到 error.message，并去掉首尾空白；如果成功且非空就返回这段消息，否则返回空。

调用关系：它只被 display_body 使用。它承担“从机器格式里抠出人话”的小任务，失败时让上层继续用原文兜底。

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

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

作用：专门识别 Cloudflare 拦截访问的情况，并生成更友好的提示。Cloudflare 是常见的网络防护服务，可能会因为地区等原因拦截请求。

数据流：进去的是 UnexpectedResponseError；函数先确认状态码是 403 禁止访问，再检查正文里是否同时出现 Cloudflare 和 blocked；如果符合，就把状态、网址、cf-ray、request id、认证错误等线索拼成一句解释；不符合就返回空。

调用关系：它被 UnexpectedResponseError::fmt 优先调用。它让某些常见但晦涩的网页拦截错误，变成用户和客服都更容易理解的信息。

调用图：被 1 处调用（fmt）；外部调用 1 个（format!）。

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

作用：把“服务器返回了没想到的状态码”整理成最终可打印的错误消息。

数据流：进去的是 UnexpectedResponseError；函数先问 friendly_message 有没有更友好的说法，有就直接用；否则调用 display_body 得到正文摘要，再拼上状态码、网址、cf-ray、request id、认证错误等信息；出来的是写入格式化器的文本。

调用关系：当 UnexpectedResponseError 被打印、记录或放进 CodexErr::UnexpectedStatus 显示时会用到它。它是这类 HTTP 异常错误的最终出口。

调用图：调用 2 个内部函数（display_body, friendly_message）；外部调用 2 个（format!, write!）。