配置、功能解析和启动策略组装

fn inherit_exec_root_options(&mut self, root: &Self)

作用：这个函数把“根命令”上的通用选项补到当前选项里。它适合在子命令没有自己写某个参数时，自动沿用外层命令给的默认选择。

数据流：进去的是当前这份可修改的选项 self，以及一份根命令选项 root。函数会逐项检查：如果当前没有选模型、配置档、沙箱模式、工作目录等，就从 root 复制过来；如果 root 里有图片或额外可写目录，就放到当前列表前面一起保留。出来时没有返回新对象，而是直接把 self 改好，让它带上继承后的完整设置。

调用关系：它通常出现在命令行参数刚解析完、真正启动任务之前。外层入口先拿到根命令的选择，再让当前命令调用这个函数补齐缺省值。它不把工作交给别的函数，而是在本地把每个字段按规则合并好，给后面的运行流程使用。

fn apply_subcommand_overrides(&mut self, subcommand: Self)

作用：这个函数把“子命令”明确写出来的选项覆盖到当前选项上。它解决的是：根命令有默认设置，但用户在具体子命令里又说了另一套时，应该尊重更具体的选择。

数据流：进去的是当前可修改的选项 self，以及子命令解析出的 subcommand。函数会看子命令哪些字段真的被用户设置了：有新模型就替换模型，有新工作目录就替换目录，有图片就用子命令图片列表，有额外目录就追加进去。对沙箱和危险绕过开关，它会先判断子命令是否真的选择了安全模式，再整体覆盖，避免无意中改掉原来的安全决定。结果同样不返回值，而是直接更新 self。

调用关系：它一般在已有一份基础选项之后调用，用来叠加更靠近用户意图的子命令设置。可以把它看成菜单上的“特殊要求”：先有默认套餐，再把子命令里明确点的内容盖上去。后续真正启动模型、执行命令、设置目录和安全策略的代码，会读取它整理好的最终选项。

fn new(
        codex_home: PathBuf,
        cli_overrides: Vec<(String, TomlValue)>,
        loader_overrides: LoaderOverrides,
        strict_config: bool,
        cloud_config_bundle: CloudConfigBu

作用：创建一个新的配置管理器，把后面加载配置要用的各种材料先收好。别人通常在服务启动或测试搭环境时调用它。

数据流：进去的是 Codex 家目录、命令行覆盖项、加载器设置、是否严格检查配置、云端配置加载器、可执行文件路径、线程配置加载器。它把其中会被运行中替换的东西放进 Arc 和 RwLock 里；Arc 可以让多处共享同一份东西，RwLock 是读写锁，防止一边读一边改。出来的是一个可以被复制引用的 ConfigManager。

调用关系：它是整个配置流程的起点。服务启动、主运行流程和测试构造环境时会先建它；后面的 load_latest_config、load_for_cwd 等方法都依赖它保存的这些基础材料。

调用图：被 5 处调用（start_uninitialized, refresh_test_state, build_test_processor, derive_config_from_params_uses_session_thread_config_model_provider, run_main_with_transport_options）；外部调用 3 个（new, new, new）。

fn codex_home(&self) -> &Path

作用：返回 Codex 的家目录，也就是配置和相关文件通常放在哪里。调用者用它来定位用户配置或发出配置相关事件。

数据流：进去的是已经存在的 ConfigManager。它只读取里面保存的 codex_home，并把它作为路径引用交出去，不复制也不修改任何东西。

调用关系：它是一个小型取值口。user_config_path 会用它算用户配置文件位置，load_default_config 也会用它处理默认配置，其他地方也会拿它判断当前配置根目录。

调用图：被 3 处调用（load_default_config, user_config_path, emit_plugin_toggle_events）；外部调用 1 个（as_path）。

fn user_config_path(&self) -> std::io::Result<AbsolutePathBuf>

作用：算出当前应该使用的用户配置文件路径。这样调用者不用自己猜配置文件到底放在哪。

数据流：进去的是 ConfigManager。它先通过 ConfigManager::codex_home 拿到家目录，再交给 loader_overrides 的 user_config_path 规则计算路径；出来的是绝对路径，或者一个输入输出错误。

调用关系：它站在“配置路径解析”这一步。load_default_config 需要它把默认配置层和指定用户配置文件接上，外部也可以调用它拿到当前选中的用户配置文件。

调用图：调用 2 个内部函数（codex_home, user_config_path）。

fn current_cli_overrides(&self) -> Vec<(String, TomlValue)>

作用：取出当前保存的命令行覆盖配置。命令行覆盖配置就是启动程序时临时指定的配置值，通常优先级较高。

数据流：进去的是 ConfigManager。它尝试读取 cli_overrides 这把读写锁，读到就复制一份列表返回；如果锁出问题，就返回空列表，避免整个服务崩掉。它不改动原始数据。

调用关系：很多加载配置的入口都会先调用它，比如 load_latest_config、load_for_cwd、load_with_overrides 和 load_config_layers。它提供的是“启动时用户明确说过要覆盖什么”。

调用图：被 6 处调用（load_config_layers, load_default_config, load_for_cwd, load_latest_config, load_with_overrides, thread_start_task）。

fn current_cloud_config_bundle(&self) -> CloudConfigBundleLoader

作用：取出当前的云端配置加载器。云端配置加载器负责从云端或登录态相关位置拿受管理的配置包。

数据流：进去的是 ConfigManager。它读取 cloud_config_bundle 这把锁，成功就复制当前加载器，失败就返回默认加载器。它不会立即加载云端配置，只是把加载工具交出去。

调用关系：load_with_cli_overrides 和 load_config_layers 会在真正构造配置时用它。登录完成后如果换了认证信息，replace_cloud_config_bundle_loader 会先更新这里保存的加载器。

调用图：被 2 处调用（load_config_layers, load_with_cli_overrides）。

fn extend_runtime_feature_enablement(&self, enablement: I) -> Result<(), ()>

作用：在程序运行中追加一批功能开关设置，比如临时打开某个实验功能。这里的功能开关是“不重启也能调整”的开关。

数据流：进去的是一组“功能名 → 是否启用”的值。它拿到 runtime_feature_enablement 的写锁，把这些值并入已有表里；成功返回空成功结果，锁失败就返回错误。它会改变 ConfigManager 内部保存的运行时开关状态。

调用关系：set_experimental_feature_enablement 会调用它。之后再加载配置时，ConfigManager::apply_runtime_feature_enablement 会把这些运行时开关套到最终 Config 上。

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

fn replace_cloud_config_bundle_loader(
        &self,
        auth_manager: Arc<AuthManager>,
        chatgpt_base_url: String,
    )

作用：登录状态变化后，换掉云端配置加载器。这样后续读取配置时，会使用新的账号认证和新的云端地址。

数据流：进去的是认证管理器、ChatGPT 基础地址，以及 ConfigManager 里已有的 Codex 家目录。它用这些创建新的 cloud_config_bundle_loader，然后拿写锁替换旧加载器；如果写锁失败，就只写一条警告日志。

调用关系：登录拿到新 token 或登录完成通知时会调用它。它不直接重新加载配置，只是更新“下次加载配置时该用谁去拿云端配置”。

调用图：被 2 处调用（login_chatgpt_auth_tokens_response, send_chatgpt_login_completion_notifications）；外部调用 3 个（clone, cloud_config_bundle_loader, warn!）。

fn replace_thread_config_loader(
        &self,
        thread_config_loader: Arc<dyn ThreadConfigLoader>,
    )

作用：替换线程配置加载器。线程配置加载器可以理解为“按某个会话或线程读取它自己的配置补丁”的工具。

数据流：进去的是新的 ThreadConfigLoader。它尝试拿写锁，把内部保存的加载器换成新的；失败时记录警告。成功后，后续配置加载会用新加载器。

调用关系：它是给外部热替换线程配置来源用的。之后 current_thread_config_loader 会把这个新加载器交给 load_with_cli_overrides 或 load_config_layers。

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

fn current_thread_config_loader(&self) -> Arc<dyn ThreadConfigLoader>

作用：取出当前线程配置加载器，供配置构建过程使用。这样线程级别的配置不会被主配置流程漏掉。

数据流：进去的是 ConfigManager。它读取 thread_config_loader 锁，成功就复制 Arc 指针返回；如果锁坏了，就返回一个 NoopThreadConfigLoader，也就是“什么都不做”的备用加载器。

调用关系：load_with_cli_overrides 和 load_config_layers 会调用它。它把“线程自己的配置来源”接到真正的配置加载管线里。

调用图：被 2 处调用（load_config_layers, load_with_cli_overrides）。

async fn sync_default_client_residency_requirement(&self)

作用：把最新配置里的数据驻留要求同步给默认客户端。数据驻留要求就是“请求或数据必须留在哪个地区处理”的限制。

数据流：进去的是 ConfigManager。它先调用 load_latest_config 读取最新配置；成功后取出 enforce_residency 的值并设置到默认客户端；失败就记录警告，不中断服务。

调用关系：登录刷新或登录完成通知后会调用它。它把配置系统的结果传给登录/客户端系统，让后续网络请求遵守最新的地区要求。

调用图：调用 2 个内部函数（load_latest_config, set_default_client_residency_requirement）；被 2 处调用（login_chatgpt_auth_tokens_response, send_chatgpt_login_completion_notifications）；外部调用 1 个（warn!）。

async fn load_latest_config(
        &self,
        fallback_cwd: Option<PathBuf>,
    ) -> std::io::Result<Config>

作用：读取当前最新的完整配置，不额外添加请求级覆盖项。它是很多地方获取“现在应该怎么运行”的常用入口。

数据流：进去的是一个可选 fallback_cwd，意思是没有明确工作目录时可用的备用目录。它先拿当前命令行覆盖项，再调用 load_with_cli_overrides，并传入空的请求覆盖和默认类型安全覆盖；出来的是最终 Config 或错误。

调用关系：它把简单调用转到更通用的 load_with_cli_overrides。同步驻留要求、刷新插件缓存、严格刷新、线程配置刷新等场景都会用它拿最新配置。

调用图：调用 2 个内部函数（current_cli_overrides, load_with_cli_overrides）；被 10 处调用（load_latest_config_for_thread, sync_default_client_residency_requirement, queue_strict_refresh, maybe_refresh_plugin_caches_for_current_config, load_latest_config, load_latest_config, load_latest_config, load_latest_config, load_latest_config, load_latest_config）；外部调用 1 个（default）。

async fn load_latest_config_for_thread(
        &self,
        thread_config: &Config,
    ) -> std::io::Result<Config>

作用：为已有线程刷新配置，同时保留这个线程会话里应该保留的配置层。它避免线程运行一半时因为全局配置刷新而丢掉会话自己的设置。

数据流：进去的是这个线程当前使用的 Config。它先用线程的 cwd 作为备用目录读取最新配置，再调用 rebuild_preserving_session_layers 把新配置和原线程会话层重新拼好，最后套用运行时功能开关和可执行文件路径；出来的是刷新后的 Config。

调用关系：build_refresh_config、实验功能列表、MCP 服务器状态列表等需要“站在线程视角看配置”的地方会调用它。它内部依赖 load_latest_config，再补上 ConfigManager 自己的运行时修正。

调用图：调用 3 个内部函数（apply_arg0_paths, apply_runtime_feature_enablement, load_latest_config）；被 3 处调用（build_refresh_config, experimental_feature_list_response, list_mcp_server_status）；外部调用 1 个（rebuild_preserving_session_layers）。

async fn load_default_config(&self) -> std::io::Result<Config>

作用：读取默认配置，主要用于需要一个基础配置而不是按具体请求定制配置的场景。它也会尊重启动时的命令行覆盖项。

数据流：进去的是 ConfigManager。它调用底层的默认配置加载函数，传入 Codex 家目录和当前命令行覆盖项；如果 loader_overrides 指定了用户配置路径或 profile，它还会把配置层记录调整到对应用户配置文件；最后套用运行时功能开关和可执行文件路径，返回 Config。

调用关系：它是“默认配置”入口，内部会调用 codex_home、current_cli_overrides、user_config_path、ConfigManager::apply_runtime_feature_enablement 和 ConfigManager::apply_arg0_paths。

调用图：调用 5 个内部函数（apply_arg0_paths, apply_runtime_feature_enablement, codex_home, current_cli_overrides, user_config_path）；外部调用 4 个（clone, Table, load_default_with_cli_overrides_for_codex_home, new）。

async fn load_with_overrides(
        &self,
        request_overrides: Option<HashMap<String, serde_json::Value>>,
        typesafe_overrides: ConfigOverrides,
    ) -> std::io::Result<Config>

作用：按请求临时覆盖一些配置后，读取完整配置。比如某个接口请求想临时指定模型、沙箱设置或其他选项。

数据流：进去的是可选的 JSON 形式请求覆盖项，以及类型安全覆盖项。它取当前命令行覆盖项，把这些一起交给 load_with_cli_overrides；出来的是合并后的 Config 或错误。

调用关系：persist_session 和 thread_start_task 会调用它。它是“我有额外请求参数，但不关心工作目录”的便捷入口。

调用图：调用 2 个内部函数（current_cli_overrides, load_with_cli_overrides）；被 2 处调用（persist_session, thread_start_task）。

async fn load_for_cwd(
        &self,
        request_overrides: Option<HashMap<String, serde_json::Value>>,
        typesafe_overrides: ConfigOverrides,
        cwd: Option<PathBuf>,
    ) -> std::io

作用：按指定工作目录读取配置。不同项目目录可能有不同配置，所以执行命令、恢复线程、列 hooks 时需要这个入口。

数据流：进去的是请求覆盖项、类型安全覆盖项，以及可选 cwd。它拿当前命令行覆盖项，然后调用 load_with_cli_overrides，把 cwd 作为 fallback_cwd 传下去；出来的是针对这个目录生效的 Config。

调用关系：hooks 列表、一次性命令执行、线程 fork/resume、Windows 沙箱设置等流程会调用它。它把“目录上下文”带进统一配置加载流程。

调用图：调用 2 个内部函数（current_cli_overrides, load_with_cli_overrides）；被 6 处调用（hooks_list_response, exec_one_off_command_inner, thread_fork_inner, thread_resume_inner, build_thread_settings_overrides, windows_sandbox_setup_start_inner）。

async fn load_with_cli_overrides(
        &self,
        cli_overrides: &[(String, TomlValue)],
        request_overrides: Option<HashMap<String, serde_json::Value>>,
        mut typesafe_overrides: C

作用：这是本文件最核心的配置加载函数。它把命令行覆盖、请求覆盖、类型安全覆盖、云端配置、线程配置等全部合并，生成最终 Config。

数据流：进去的是命令行覆盖列表、可选请求覆盖、类型安全覆盖和备用工作目录。它先特别处理 bypass_hook_trust，要求它必须是布尔值；再把请求里的 JSON 值转成 TOML 值，和命令行覆盖合并。随后用 ConfigBuilder 填入家目录、覆盖项、加载器设置、严格模式、云端加载器、线程加载器等，异步构建 Config。最后再应用运行时功能开关和可执行文件路径，返回最终配置。

调用关系：load_latest_config、load_with_overrides、load_for_cwd 和 thread_start_task 都会把工作交给它。它又会取 current_cloud_config_bundle、current_thread_config_loader，并调用 ConfigManager::apply_runtime_feature_enablement 和 ConfigManager::apply_arg0_paths 做最后修正。

调用图：调用 4 个内部函数（apply_arg0_paths, apply_runtime_feature_enablement, current_cloud_config_bundle, current_thread_config_loader）；被 4 处调用（load_for_cwd, load_latest_config, load_with_overrides, thread_start_task）；外部调用 3 个（clone, clone, default）。

async fn load_config_layers_for_cwd(
        &self,
        cwd: AbsolutePathBuf,
    ) -> std::io::Result<ConfigLayerStack>

作用：读取某个目录下配置的“分层信息”。分层信息说明最终配置分别来自默认值、用户文件、云端管理、会话等哪些层。

数据流：进去的是一个绝对工作目录。它只是把这个目录包成 Some，转给 load_config_layers；出来的是 ConfigLayerStack 或错误。

调用关系：resolve_cwd_config 会调用它。它是面向“指定目录查配置层”的便捷包装，真正工作由 load_config_layers 完成。

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

async fn load_config_layers(
        &self,
        cwd: Option<AbsolutePathBuf>,
    ) -> std::io::Result<ConfigLayerStack>

作用：读取配置层本身，而不只是最终合成后的配置值。这样界面或接口可以解释“这个值为什么是这样、是谁覆盖了谁”。

数据流：进去的是可选 cwd。它取当前线程配置加载器、命令行覆盖项、云端配置加载器和加载选项，然后调用 load_config_layers_state，从本地文件系统和各配置来源读取配置层；出来的是 ConfigLayerStack。

调用关系：load_config_layers_for_cwd 和 permission_profile_list_response 会调用它。它把 ConfigManager 保存的各种加载条件交给底层 load_config_layers_state。

调用图：调用 4 个内部函数（current_cli_overrides, current_cloud_config_bundle, current_thread_config_loader, load_config_layers_state）；被 2 处调用（load_config_layers_for_cwd, permission_profile_list_response）；外部调用 1 个（clone）。

fn apply_runtime_feature_enablement(&self, config: &mut Config)

作用：把 ConfigManager 里记录的运行时功能开关应用到某份 Config 上。它是方法版包装，方便内部在每次加载配置后调用。

数据流：进去的是一份可修改的 Config。它先复制当前 runtime_feature_enablement 表，再调用同名的文件级函数 apply_runtime_feature_enablement；结果是 Config 里的 features 可能被打开或关闭。

调用关系：load_default_config、load_latest_config_for_thread 和 load_with_cli_overrides 在返回配置前都会调用它。真正判断哪些功能能改、怎么改，由文件级 apply_runtime_feature_enablement 完成。

调用图：调用 2 个内部函数（current_runtime_feature_enablement, apply_runtime_feature_enablement）；被 3 处调用（load_default_config, load_latest_config_for_thread, load_with_cli_overrides）。

fn current_runtime_feature_enablement(&self) -> BTreeMap<String, bool>

作用：取出当前运行时功能开关表。调用者通常不会直接改这份表，而是拿它来应用到配置上。

数据流：进去的是 ConfigManager。它读取 runtime_feature_enablement 锁，成功就复制一份 BTreeMap 返回；失败就返回空表。它不改变内部状态。

调用关系：ConfigManager::apply_runtime_feature_enablement 会调用它。它提供“运行中临时打开或关闭了哪些功能”的快照。

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

fn apply_arg0_paths(&self, config: &mut Config)

作用：把当前程序实际使用的几个可执行文件路径写进 Config。这样后续需要重新调用 Codex 自己或沙箱程序时，能找到正确文件。

数据流：进去的是一份可修改的 Config。它从 arg0_paths 里复制 codex_self_exe、codex_linux_sandbox_exe、main_execve_wrapper_exe 三个路径，写到 Config 对应字段；没有返回值，但 Config 被更新。

调用关系：load_default_config、load_latest_config_for_thread 和 load_with_cli_overrides 都会在配置加载完成后调用它。它把启动时识别到的程序路径补进最终配置。

调用图：被 3 处调用（load_default_config, load_latest_config_for_thread, load_with_cli_overrides）。

fn new_for_tests(
        codex_home: PathBuf,
        cli_overrides: Vec<(String, TomlValue)>,
        loader_overrides: LoaderOverrides,
        cloud_config_bundle: CloudConfigBundleLoader,
    ) -

作用：给测试创建一个简化版 ConfigManager。测试不需要完整的严格配置、真实 arg0 路径或真实线程加载器。

数据流：进去的是测试用 Codex 家目录、命令行覆盖、加载器覆盖和云端配置加载器。它调用 ConfigManager::new，固定 strict_config 为 false，使用默认 arg0 路径和什么都不做的线程配置加载器；出来的是测试用 ConfigManager。

调用关系：多种配置读写测试会调用它。它让测试能专注验证配置规则，而不用搭完整服务运行环境。

调用图：被 9 处调用（invalid_user_value_rejected_even_if_overridden_by_managed, load_default_config_preserves_selected_user_config_path_after_load_error, read_includes_origins_and_layers, read_reports_managed_overrides_user_and_session_flags, write_value_defaults_to_selected_user_config_path, write_value_rejects_feature_requirement_conflict, write_value_reports_managed_override, write_value_reports_override, write_value_succeeds_when_managed_preferences_expand_home_directory_paths）；外部调用 3 个（new, new, default）。

fn without_managed_config_for_tests(codex_home: PathBuf) -> Self

作用：给测试创建一个“不带受管理配置”的 ConfigManager。受管理配置通常来自组织或云端，测试某些本地规则时需要排除它。

数据流：进去的是测试用 Codex 家目录。它准备空命令行覆盖、测试专用的“没有 managed config”加载器覆盖、默认云端配置加载器，然后调用 new_for_tests；出来的是简化测试管理器。

调用关系：很多写配置、清配置、冲突检查测试会调用它。它建立一个干净环境，避免云端或组织配置影响测试结果。

调用图：调用 2 个内部函数（default, without_managed_config_for_tests）；被 12 处调用（batch_write_rejects_legacy_profile_selector, clear_missing_nested_config_is_noop, reserved_builtin_provider_override_rejected, upsert_merges_tables_replace_overwrites, version_conflict_rejected, write_value_defaults_to_user_config_path, write_value_preserves_comments_and_order, write_value_rejects_legacy_profile_selector, write_value_rejects_legacy_profile_table, write_value_supports_custom_mcp_server_default_tool_approval_mode (+2 more)）；外部调用 2 个（new_for_tests, new）。

fn protected_feature_keys(config_layer_stack: &ConfigLayerStack) -> BTreeSet<String>

作用：找出哪些功能开关不能被运行时随便改。这些功能要么已经在有效配置里写明，要么被 requirements 文件明确要求。

数据流：进去的是 ConfigLayerStack。它先查看最终生效配置里的 features 表，把里面出现过的功能名收集起来；再查看 requirements_toml 里的功能要求，把那些功能名也加入集合；出来的是一个功能名集合。

调用关系：文件级 apply_runtime_feature_enablement 会先调用它。它相当于列出“受保护名单”，防止运行时开关覆盖更高优先级或强制要求的配置。

调用图：调用 2 个内部函数（effective_config, requirements_toml）；被 1 处调用（apply_runtime_feature_enablement）。

fn apply_runtime_feature_enablement(
    config: &mut Config,
    runtime_feature_enablement: &BTreeMap<String, bool>,
)

作用：把一张运行时功能开关表应用到 Config，但会跳过受保护或未知的功能。这样既能临时开关实验功能，又不会破坏配置文件和组织要求。

数据流：进去的是可修改的 Config，以及“功能名 → 是否启用”的表。它先用 protected_feature_keys 找出不能动的功能；然后逐个检查运行时开关：受保护的跳过，系统不认识的跳过，认识且允许改的就调用 config.features.set_enabled 设置；如果设置失败就写警告。结果是 Config 的功能状态可能被改变。

调用关系：ConfigManager::apply_runtime_feature_enablement 会调用它。它是运行时功能开关真正落地的地方，并依赖 feature_for_key 把字符串名字转换成系统认识的功能对象。

调用图：调用 1 个内部函数（protected_feature_keys）；被 1 处调用（apply_runtime_feature_enablement）；外部调用 2 个（feature_for_key, warn!）。

fn project_root_markers_from_config(config: &TomlValue) -> io::Result<Option<Vec<String>>>

作用：从已经合并好的 config.toml 配置内容里，读出 project_root_markers 这一项。它会区分三种情况：没写、写了正确的字符串列表、写错格式。

数据流：输入是一份 TOML 配置值，也就是配置文件被解析后的结构。它先确认最外层是不是表格，再找 project_root_markers 字段；如果找不到，就返回“没有配置”。如果找到了，它要求这个字段必须是数组，并且数组里每一项都必须是字符串；检查通过后输出字符串列表。它不会修改配置，只负责读取和校验；如果格式不对，就返回一个输入数据无效的错误。

调用关系：它会在 load_config_layers_state 读取配置层时被调用，用来把配置文件里的项目根目录规则变成程序能直接使用的列表。它内部只借助 TOML 值的表格读取能力和标准错误创建方法，不把工作再交给项目里的其他函数。

调用图：被 1 处调用（load_config_layers_state）；外部调用 3 个（as_table, new, new）。

fn default_project_root_markers() -> Vec<String>

作用：提供默认的项目根目录标记列表。当前默认只有“.git”，意思是看到 Git 仓库目录就把那里当作项目根目录。

数据流：它没有外部输入，只读取文件里写死的默认标记常量。然后把这些默认字符串转换成一份新的字符串列表返回给调用者。它不修改任何全局状态，所以每次调用都会得到一份可独立使用的列表。

调用关系：当配置里没有指定 project_root_markers 时，其他配置加载流程可以用它拿到默认规则。它是一个简单的兜底工具函数，不调用项目里的其他函数，也没有在提供的调用图里显示被谁直接调用。

fn default() -> Self

作用：给旧版 ghost_snapshot 配置准备默认值。这个功能现在只是为了兼容老配置，不再真的生成快照。

数据流：进去没有参数 → 填上默认的大文件、大目录忽略阈值和不关闭警告 → 出来一份 GhostSnapshotConfig 默认配置。

调用关系：Config::load_config_with_layer_stack 在组装总配置时会用它兜底，测试里的 new_config 也会依赖这份默认值。

调用图：被 2 处调用（load_config_with_layer_stack, new_config）。

fn default_multi_agent_v2_usage_hint_text(usage_hint_text: &str, max_concurrency: usize) -> String

作用：拼出多代理 V2 的默认使用说明。它会把角色说明、共享规则和并发数量写成一段模型能看的提示文字。

数据流：进去一段基础说明和最大并发数 → 用固定共享说明把它们拼起来 → 出来完整的多代理提示文本。

调用关系：MultiAgentV2Config::defaults_for_max_concurrency 调它来生成 root agent 和子 agent 的默认提示。

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

fn resolve_sqlite_home_env(resolved_cwd: &Path) -> Option<PathBuf>

作用：读取环境变量里的 SQLite 数据目录。SQLite 是一个本地小数据库，用来存 Codex 状态。

数据流：进去当前工作目录 → 读取 CODEX 的 SQLite home 环境变量，空值忽略，相对路径补到当前目录下 → 出来一个可用路径或 None。

调用关系：总配置加载时用它决定 sqlite_home；如果配置文件没写，就允许环境变量接管。

调用图：外部调用 3 个（join, from, var）。

fn resolve_cli_auth_credentials_store_mode(
    configured: AuthCredentialsStoreMode,
    package_version: &str,
) -> AuthCredentialsStoreMode

作用：决定 CLI 登录凭据放文件还是系统钥匙串。开发版会强制用文件，避免本地调试时误碰系统钥匙串。

数据流：进去配置的存储模式和包版本 → 如果是 0.0.0 开发版且配置是 keyring/auto，就改成 file → 出来最终存储模式。

调用关系：Config::load_config_with_layer_stack 在填 cli_auth_credentials_store_mode 时调用它。

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

fn resolve_mcp_oauth_credentials_store_mode(
    configured: OAuthCredentialsStoreMode,
    package_version: &str,
) -> OAuthCredentialsStoreMode

作用：决定 MCP OAuth 凭据放文件还是钥匙串。它和 CLI 凭据规则类似，也对开发版做安全简化。

数据流：进去配置的 OAuth 存储模式和包版本 → 开发版把 keyring/auto 改成 file，其他保持原样 → 出来最终模式。

调用关系：Config::load_config_with_layer_stack 在生成 MCP 配置相关字段时使用它。

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

async fn test_config() -> Config

作用：给测试快速造一份默认 Config。它不读真实用户配置，避免测试受本机环境影响。

数据流：进去没有参数 → 创建临时 Codex home，用默认 ConfigToml 和默认覆盖项加载 → 出来一份可用于测试的 Config。

调用关系：大量测试会调用它，底层交给 Config::load_from_base_config_with_overrides 完成实际构造。

调用图：调用 1 个内部函数（from_absolute_path）；被 32 处调用（interrupted_v2_agent_is_lost_after_residency_eviction, residency_slot_reservation_unloads_oldest_idle_v2_agent, guardian_review_session_compact_scope_change_invalidates_cached_session, guardian_review_session_config_change_invalidates_cached_session, guardian_review_session_config_disables_hooks, guardian_review_session_config_disables_skill_instructions, guardian_review_session_config_allows_pinned_disabled_feature, guardian_review_session_config_clears_legacy_notify, guardian_review_session_config_clears_parent_developer_instructions, guardian_review_session_config_disables_mcp_apps_plugins_and_memories (+15 more)）；外部调用 4 个（load_from_base_config_with_overrides, default, default, tempdir）。

fn from_approval_and_profile(
        approval_policy: Constrained<AskForApproval>,
        permission_profile: Constrained<PermissionProfile>,
    ) -> ConstraintResult<Self>

作用：用最少信息造一份权限配置。调用者只要给“何时审批”和“允许什么权限档案”，它补齐其他默认项。

数据流：进去审批策略和权限档案 → 转成内部 PermissionProfileState，并填空工作区、网络、shell、Windows 沙箱默认值 → 出来 Permissions。

调用关系：测试和简化配置构造会用它，内部依赖 PermissionProfileState::from_constrained_legacy。

调用图：调用 2 个内部函数（from_constrained_legacy, default）；被 3 处调用（permission_snapshot_setter_preserves_permission_constraints, new_config, debug_config_output_filters_sandbox_modes_blocked_by_deny_read_requirements）；外部调用 1 个（new）。

fn permission_profile_state(&self) -> &PermissionProfileState

作用：借出内部保存的权限档案状态。这个状态不只是权限本身，还记着它来自哪个命名档案。

数据流：进去一个 Permissions 引用 → 不修改任何东西，只返回内部状态引用 → 出来 PermissionProfileState 的只读视图。

调用关系：供同模块内部需要看完整权限状态的代码使用。

fn set_permission_profile_state(
        &mut self,
        permission_profile_state: PermissionProfileState,
    )

作用：直接替换内部权限档案状态。它用于已经解析好完整状态、只需要塞回 Permissions 的场景。

数据流：进去新的 PermissionProfileState → 覆盖旧状态 → Permissions 的有效权限来源被更新。

调用关系：apply_permission_profile_to_permissions 会用它把外部选好的权限状态应用进来。

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

fn set_permission_profile_from_session_snapshot(
        &mut self,
        snapshot: PermissionProfileSnapshot,
    ) -> ConstraintResult<()>

作用：把核心会话发出的权限快照应用到本地权限中。快照就是“当前会话实际在用的权限照片”。

数据流：进去 PermissionProfileSnapshot → 交给内部状态验证并设置 → 成功则当前权限变成快照描述的权限。

调用关系：用于客户端同步核心会话状态，内部调用 set_permission_profile_snapshot。

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

fn replace_permission_profile_from_session_snapshot(
        &mut self,
        snapshot: PermissionProfileSnapshot,
    ) -> ConstraintResult<()>

作用：在本地约束不接受快照时，强行用可信会话快照替换权限。它是一个“以核心会话为准”的桥。

数据流：进去快照 → 把快照权限包装成只允许这一种的约束，再转成已解析状态 → 覆盖当前权限状态。

调用关系：给必须镜像核心会话的客户端使用，内部会调用 allow_only、permission_profile 和 from_constrained_resolved。

调用图：调用 4 个内部函数（allow_only, into_resolved_permission_profile, permission_profile, from_constrained_resolved）。

fn permission_profile(&self) -> &PermissionProfile

作用：取出还没套入运行期工作区根目录的原始权限档案。它回答“配置本身允许什么”。

数据流：进去 Permissions → 读取内部状态里的权限档案 → 出来 PermissionProfile 引用。

调用关系：materialized_permission_profile 和 network_sandbox_policy 会从这里继续计算。

调用图：调用 1 个内部函数（permission_profile）；被 2 处调用（materialized_permission_profile, network_sandbox_policy）。

fn can_set_permission_profile(
        &self,
        permission_profile: &PermissionProfile,
    ) -> ConstraintResult<()>

作用：检查某个权限档案能不能被当前约束接受。它只检查，不真的改。

数据流：进去候选 PermissionProfile → 用内部约束判断是否合法 → 出来成功或约束错误。

调用关系：sandbox_mode_is_allowed_by_permissions 等调用方用它提前判断用户选择是否可用。

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

fn set_workspace_roots(&mut self, workspace_roots: Vec<AbsolutePathBuf>)

作用：替换运行期工作区根目录列表。工作区根目录就是工具被允许围绕操作的项目目录。

数据流：进去一组绝对路径 → 覆盖旧 workspace_roots → 后续权限物化会按新目录计算。

调用关系：当会话或调用方重新指定工作区时使用。

fn workspace_roots(&self) -> &[AbsolutePathBuf]

作用：查看当前运行期工作区根目录。它不会包含额外推导，只返回保存的列表。

数据流：进去 Permissions → 读取 workspace_roots → 出来路径切片。

调用关系：Config::set_legacy_sandbox_policy 在同步 Config 字段时会读取它。

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

fn user_visible_workspace_roots(&self) -> &[AbsolutePathBuf]

作用：返回用户可见的工作区根目录。内部专用的可写目录不会混进来。

数据流：进去 Permissions → 直接返回 workspace_roots → 出来用户应该看到的路径列表。

调用关系：给界面或外部展示使用，避免把 Codex 内部辅助目录暴露成用户选择。

fn profile_workspace_roots(&self) -> &[AbsolutePathBuf]

作用：返回权限档案自己声明的工作区根目录。它和运行期额外传入的根目录分开保存。

数据流：进去 Permissions → 从 PermissionProfileState 取 profile_workspace_roots → 出来路径列表。

调用关系：Config::effective_workspace_roots 会把它和运行期根目录合并。

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

fn materialized_permission_profile(&self) -> PermissionProfile

作用：把权限档案里的“工作区占位符”替换成真实目录。这样后面的沙箱策略才能落到具体路径。

数据流：进去 Permissions → 克隆原权限档案，并用 workspace_roots 填充项目根目录 → 出来可直接执行的 PermissionProfile。

调用关系：effective_permission_profile、file_system_sandbox_policy 和 legacy_sandbox_policy 都依赖它。

调用图：调用 1 个内部函数（permission_profile）；被 3 处调用（effective_permission_profile, file_system_sandbox_policy, legacy_sandbox_policy）。

fn effective_permission_profile(&self) -> PermissionProfile

作用：得到运行时真正生效的权限档案。它已经把工作区目录这些运行期信息算进去了。

数据流：进去 Permissions → 调 materialized_permission_profile → 出来最终 PermissionProfile。

调用关系：给执行命令、展示权限、会话同步等流程使用。

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

fn active_permission_profile(&self) -> Option<ActivePermissionProfile>

作用：返回当前是否选中了某个命名权限档案。命名档案像“只读”“工作区可写”这类可复选的预设。

数据流：进去 Permissions → 从状态里取 active profile → 出来 Some 档案信息或 None。

调用关系：界面和会话配置会用它告诉用户当前权限来自哪个档案。

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

fn file_system_sandbox_policy(&self) -> FileSystemSandboxPolicy

作用：把权限档案转换成文件系统沙箱策略。沙箱策略就是限制程序能读写哪些文件的规则。

数据流：进去 Permissions → 先物化权限档案，再提取文件系统规则 → 出来 FileSystemSandboxPolicy。

调用关系：执行 shell 或统一执行工具时会用这份规则。

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

fn network_sandbox_policy(&self) -> NetworkSandboxPolicy

作用：把权限档案转换成网络沙箱策略。它说明工具进程能不能访问网络。

数据流：进去 Permissions → 从原始权限档案读取网络规则 → 出来 NetworkSandboxPolicy。

调用关系：网络代理和执行环境会依据它决定是否放通网络。

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

fn legacy_sandbox_policy(&self, cwd: &Path) -> SandboxPolicy

作用：把新权限档案投影成旧版 SandboxPolicy。这样老代码还能看懂当前权限。

数据流：进去当前工作目录 → 物化权限档案，再转换成兼容旧接口的沙箱策略 → 出来 SandboxPolicy。

调用关系：Config::legacy_sandbox_policy 会调用它，给仍使用旧沙箱表达方式的流程。

调用图：调用 1 个内部函数（materialized_permission_profile）；被 1 处调用（legacy_sandbox_policy）；外部调用 1 个（compatibility_sandbox_policy_for_permission_profile）。

fn can_set_legacy_sandbox_policy(
        &self,
        sandbox_policy: &SandboxPolicy,
        cwd: &Path,
    ) -> ConstraintResult<()>

作用：检查旧版沙箱策略能不能应用到当前权限约束。它先把旧策略翻译成新权限档案再验证。

数据流：进去 SandboxPolicy 和 cwd → 转成文件、网络和执行强度组合，再组成 PermissionProfile → 出来是否允许设置。

调用关系：Permissions::set_legacy_sandbox_policy 会先调用它防止非法修改。

调用图：调用 5 个内部函数（can_set_legacy_permission_profile, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, from_legacy_sandbox_policy_for_cwd, from）；被 1 处调用（set_legacy_sandbox_policy）。

fn set_legacy_sandbox_policy(
        &mut self,
        sandbox_policy: SandboxPolicy,
        cwd: &Path,
    ) -> ConstraintResult<()>

作用：用旧版 SandboxPolicy 更新当前权限，并保持工作区根目录同步。它用于兼容老入口。

数据流：进去 SandboxPolicy 和 cwd → 先检查合法，再转成新权限档案，按策略重建 workspace_roots → 更新内部权限状态并返回结果。

调用关系：Config::set_legacy_sandbox_policy 会把用户或旧接口传来的策略交给它。

调用图：调用 6 个内部函数（can_set_legacy_sandbox_policy, set_legacy_permission_profile, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, from_legacy_sandbox_policy_for_cwd, from）；被 1 处调用（set_legacy_sandbox_policy）；外部调用 1 个（vec!）。

fn set_permission_profile(
        &mut self,
        permission_profile: PermissionProfile,
    ) -> ConstraintResult<()>

作用：直接设置新的规范权限档案。它是新权限系统的普通写入口。

数据流：进去 PermissionProfile → 交给内部状态按约束保存 → 成功后当前权限档案被替换。

调用关系：适合已经拿到规范 PermissionProfile 的调用方，不需要走旧 SandboxPolicy。

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

fn profile_allows_configured_network_proxy(permission_profile: &PermissionProfile) -> bool

作用：判断某个权限档案能不能继承配置里的网络代理。没有外层沙箱的“完全禁用权限档案”不会开启托管代理。

数据流：进去 PermissionProfile → 看它是托管/外部且网络启用，还是完全禁用 → 出来 true 或 false。

调用关系：Config::load_config_with_layer_stack 和 Config::network_proxy_spec_for_active_permission_profile 用它决定是否构造代理。

调用图：被 2 处调用（load_config_with_layer_stack, network_proxy_spec_for_active_permission_profile）。

fn build_network_proxy_spec(
    configured_network_proxy_config: NetworkProxyConfig,
    network_requirements: Option<Sourced<codex_config::NetworkConstraints>>,
    permission_profile: &PermissionPr

作用：把网络代理配置、管理员网络要求和权限档案合成最终代理规格。代理规格说明是否要启动受控网络通道。

数据流：进去配置的 NetworkProxyConfig、可选网络要求和权限档案 → 调 NetworkProxySpec::from_config_and_constraints，并包装错误来源 → 出来 Some 代理规格或 None。

调用关系：总配置加载和切换权限档案时都会调用它。

调用图：调用 1 个内部函数（from_config_and_constraints）；被 2 处调用（load_config_with_layer_stack, network_proxy_spec_for_active_permission_profile）。

fn defaults_for_max_concurrency(max_concurrent_threads_per_session: usize) -> Self

作用：按指定并发数生成多代理 V2 默认配置。并发数会写进模型提示，告诉它最多能同时有几个代理活跃。

数据流：进去最大并发数 → 填默认等待时间、提示开关、提示文本、命名空间和展示选项 → 出来 MultiAgentV2Config。

调用关系：resolve_multi_agent_v2_config 用它作为用户配置的底板。

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

fn default() -> Self

作用：生成多代理 V2 的全局默认配置。默认允许 4 个并发线程。

数据流：进去没有参数 → 调 defaults_for_max_concurrency 使用默认并发数 → 出来默认 MultiAgentV2Config。

调用关系：默认 Config 或测试构造会间接依赖它。

调用图：被 1 处调用（new_config）；外部调用 1 个（defaults_for_max_concurrency）。

fn codex_home(&self) -> PathBuf

作用：把 Config 里的 Codex home 目录提供给认证模块。Codex home 是保存配置、凭据和状态的主目录。

数据流：进去 Config → 克隆 codex_home 路径 → 出来 PathBuf。

调用关系：这是 AuthManagerConfig trait 的实现，登录管理器通过它找本地目录。

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

fn cli_auth_credentials_store_mode(&self) -> AuthCredentialsStoreMode

作用：告诉认证模块 CLI 凭据应该怎么存。比如存在文件里，还是系统钥匙串里。

数据流：进去 Config → 读取 cli_auth_credentials_store_mode → 出来存储模式。

调用关系：认证管理器通过 AuthManagerConfig trait 调用它。

fn auth_keyring_backend_kind(&self) -> AuthKeyringBackendKind

作用：告诉认证模块该用哪种系统钥匙串后端。钥匙串就是操作系统提供的安全凭据保险箱。

数据流：进去 Config → 调配置的 keyring 解析逻辑 → 出来 AuthKeyringBackendKind。

调用关系：to_mcp_config_with_plugin_registrations 也会用它给 MCP OAuth 配置凭据存储。

调用图：被 1 处调用（to_mcp_config_with_plugin_registrations）；外部调用 1 个（auth_keyring_backend_kind）。

fn forced_chatgpt_workspace_id(&self) -> Option<Vec<String>>

作用：返回是否限制只能登录某些 ChatGPT 工作区。它用于受管环境控制账号范围。

数据流：进去 Config → 克隆 forced_chatgpt_workspace_id → 出来工作区 ID 列表或 None。

调用关系：认证管理器通过 AuthManagerConfig trait 查询这个限制。

fn chatgpt_base_url(&self) -> String

作用：返回 ChatGPT 后端地址。登录和某些服务请求会用这个地址。

数据流：进去 Config → 克隆 chatgpt_base_url → 出来字符串 URL。

调用关系：认证管理器和 MCP 配置生成流程都会需要这个基础地址。

fn codex_home(mut self, codex_home: PathBuf) -> Self

作用：给配置构建器指定 Codex home。它让调用方不必依赖默认的 ~/.codex。

数据流：进去构建器和路径 → 把路径存进 builder → 出来更新后的 builder。

调用关系：这是链式 builder 方法，最后由 ConfigBuilder::build_inner 使用。

fn cli_overrides(mut self, cli_overrides: Vec<(String, TomlValue)>) -> Self

作用：给配置构建器设置命令行覆盖项。命令行覆盖项优先级通常比配置文件高。

数据流：进去 builder 和一组 TOML 路径/值 → 存进 builder → 出来更新后的 builder。

调用关系：Config::load_with_cli_overrides 等入口会用它再调用 build。

fn harness_overrides(mut self, harness_overrides: ConfigOverrides) -> Self

作用：设置运行框架专用覆盖项。这里包含 cwd、可执行文件路径等不能写进 config.toml 的值。

数据流：进去 builder 和 ConfigOverrides → 存起来 → 出来 builder。

调用关系：Config::load_with_cli_overrides_and_harness_overrides 用它构建最终配置。

fn loader_overrides(mut self, loader_overrides: LoaderOverrides) -> Self

作用：设置配置加载器本身的覆盖项。它控制加载哪些层、是否跳过托管配置等。

数据流：进去 builder 和 LoaderOverrides → 存进 builder → 出来 builder。

调用关系：测试和 profile 加载路径会用它改变加载行为。

fn strict_config(mut self, strict_config: bool) -> Self

作用：打开或关闭严格配置模式。严格模式会更认真地把配置问题当成错误。

数据流：进去 builder 和布尔值 → 更新 strict_config 字段 → 出来 builder。

调用关系：ConfigBuilder::build_inner 会把这个选项传给 load_config_layers_state。

fn cloud_config_bundle(mut self, cloud_config_bundle: CloudConfigBundleLoader) -> Self

作用：设置云端配置包加载器。它用于把远端或托管下发的配置也纳入合并。

数据流：进去 builder 和 CloudConfigBundleLoader → 保存它 → 出来 builder。

调用关系：ConfigBuilder::build_inner 会把它放进 ConfigLoadOptions。

fn thread_config_loader(
        mut self,
        thread_config_loader: Arc<dyn ThreadConfigLoader>,
    ) -> Self

作用：设置线程级配置加载器。线程级配置就是某个会话或线程单独带来的配置层。

数据流：进去 builder 和加载器对象 → 用 Arc 保存共享引用 → 出来 builder。

调用关系：build_inner 加载配置层时会把它传给 load_config_layers_state。

fn fallback_cwd(mut self, fallback_cwd: Option<PathBuf>) -> Self

作用：设置备用当前目录。如果 harness 覆盖里没指定 cwd，就用这个目录。

数据流：进去 builder 和可选路径 → 保存为 fallback_cwd → 出来 builder。

调用关系：build_inner 解析 cwd 时会在 harness cwd 和当前进程目录之间使用它。

async fn build(self) -> std::io::Result<Config>

作用：启动配置构建流程。它把真正的大型异步加载任务包起来，避免小线程栈被撑爆。

数据流：进去 builder → 把 build_inner pin 住并等待 → 出来 Config 或 IO 错误。

调用关系：build_config_on_runtime_worker 等上层入口调用它，实际工作交给 build_inner。

调用图：调用 1 个内部函数（build_inner）；被 1 处调用（build_config_on_runtime_worker）；外部调用 1 个（pin）。

async fn build_inner(self) -> std::io::Result<Config>

作用：配置构建器的核心流程。它找目录、算 cwd、加载配置层、处理 lockfile，最后生成 Config。

数据流：进去 builder 内所有选项 → 解析 codex_home/cwd，调用 load_config_layers_state 合并 TOML，必要时读取配置锁文件，再调用 Config::load_config_with_layer_stack → 出来最终 Config。

调用关系：由 ConfigBuilder::build 调用，是普通启动配置加载的主通道。

调用图：调用 9 个内部函数（load_config_layers_state, new, find_codex_home, config_without_lock_controls, lock_layer_from_config, read_config_lock_from_path, current_dir, from_absolute_path, relative_to_current_dir）；被 1 处调用（build）；外部调用 5 个（new, load_config_with_layer_stack, new, io_error_from_config_error, vec!）。

fn without_managed_config_for_tests() -> Self

作用：给测试创建一个不加载托管配置的 builder。这样测试不会被机器上的公司策略影响。

数据流：进去没有参数 → 从默认 builder 开始，加上测试用 LoaderOverrides → 出来 builder。

调用关系：很多配置测试会先调用它，再设置 CLI 或文件内容。

调用图：调用 1 个内部函数（without_managed_config_for_tests）；被 58 处调用（test_config_with_cli_overrides, inline_instructions_set_base_instructions, active_profile_is_cleared_when_requirements_force_fallback, agent_role_file_metadata_overrides_config_toml_metadata, agent_role_file_name_takes_precedence_over_config_key, agent_role_file_without_developer_instructions_is_dropped_with_warning, agent_role_relative_config_file_resolves_against_config_toml, agent_role_without_description_after_merge_is_dropped_with_warning, approvals_reviewer_can_be_set_in_config_without_guardian_approval, approvals_reviewer_defaults_to_manual_only_without_guardian_feature (+15 more)）；外部调用 1 个（default）。

fn multi_agent_version_from_features(&self) -> MultiAgentVersion

作用：根据功能开关判断当前使用哪一代多代理。功能开关就是集中控制某功能是否启用的开关。

数据流：进去 Config → 查看 MultiAgentV2 和 Collab 是否启用 → 出来 V2、V1 或 Disabled。

调用关系：运行时决定代理工具表面时会查询它。

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

fn validate_multi_agent_v2_config(&self) -> std::io::Result<()>

作用：检查多代理 V2 和旧 agents.max_threads 配置是否冲突。V2 有自己的并发设置，不能再混用旧字段。

数据流：进去 Config → 如果 MultiAgentV2 启用且 agent_max_threads 被设置，就返回错误 → 否则成功。

调用关系：启动或会话配置验证阶段会用它阻止含糊配置。

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

fn effective_agent_max_threads(
        &self,
        multi_agent_version: MultiAgentVersion,
    ) -> Option<usize>

作用：算出实际允许的子代理线程数。V2 要给主代理占一个并发槽，所以会减一。

数据流：进去多代理版本 → V2 用 max_concurrent_threads_per_session 减一，V1/禁用用旧配置或默认值 → 出来可选线程数。

调用关系：代理调度器会用它限制同时打开的代理数量。

fn legacy_sandbox_policy(&self) -> SandboxPolicy

作用：从整份 Config 里取旧版沙箱策略。它把工作目录一起传给 Permissions。

数据流：进去 Config → 用 cwd 调 Permissions::legacy_sandbox_policy → 出来 SandboxPolicy。

调用关系：给仍依赖旧 SandboxPolicy 的调用方使用。

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

fn set_legacy_sandbox_policy(
        &mut self,
        sandbox_policy: SandboxPolicy,
    ) -> ConstraintResult<()>

作用：用旧版沙箱策略修改整份 Config 的权限，并同步 workspace_roots 字段。

数据流：进去 SandboxPolicy → 标记工作区根是否显式设置，交给 Permissions 更新，再把 Permissions 的 roots 拷回 Config → 出来成功或约束错误。

调用关系：外部旧接口设置沙箱时调用它，核心修改交给 Permissions::set_legacy_sandbox_policy。

调用图：调用 3 个内部函数（set_legacy_sandbox_policy, workspace_roots, as_path）；外部调用 1 个（matches!）。

fn effective_workspace_roots(&self) -> Vec<AbsolutePathBuf>

作用：算出最终工作区根目录列表。它把运行期 roots 和权限档案自带 roots 合并并去重。

数据流：进去 Config → 克隆 workspace_roots，加上 permissions.profile_workspace_roots，再去重 → 出来路径列表。

调用关系：工具执行、界面展示和权限判断都可能用这份最终列表。

调用图：调用 2 个内部函数（profile_workspace_roots, dedupe_absolute_paths）。

fn to_models_manager_config(&self) -> ModelsManagerConfig

作用：把大 Config 中和模型管理有关的部分摘出来。模型管理器不需要知道权限、TUI 等杂项。

数据流：进去 Config → 拷贝模型窗口、压缩阈值、提示、个性功能和模型目录字段 → 出来 ModelsManagerConfig。

调用关系：模型管理子系统初始化时用它获得自己需要的设置。

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

fn plugins_config_input(&self) -> PluginsConfigInput

作用：为插件管理器准备输入。它告诉插件系统配置层、插件功能开关和后端地址。

数据流：进去 Config → 克隆 config_layer_stack，读取 Plugins/RemotePlugin 开关和 ChatGPT URL → 出来 PluginsConfigInput。

调用关系：to_mcp_config_with_plugin_registrations 会先调用它来加载可用插件。

调用图：调用 1 个内部函数（new）；被 1 处调用（to_mcp_config_with_plugin_registrations）；外部调用 2 个（clone, enabled）。

fn apply_plugin_mcp_server_requirements(
        &self,
        plugin_id: &str,
        mcp_servers: &mut HashMap<String, McpServerConfig>,
    )

作用：把托管要求应用到某个插件声明的 MCP 服务器上。MCP 是模型上下文协议，用来接工具服务器。

数据流：进去插件 ID 和可变服务器表 → 先按插件要求过滤，再按全局空白名单要求过滤 → 服务器会被禁用或清除禁用原因。

调用关系：to_mcp_config_with_plugin_registrations 在注册插件 MCP 服务器前调用它。

调用图：调用 3 个内部函数（requirements, filter_mcp_servers_by_requirements, filter_plugin_mcp_servers_by_requirements）；被 1 处调用（to_mcp_config_with_plugin_registrations）。

async fn to_mcp_config(
        &self,
        plugins_manager: &codex_core_plugins::PluginsManager,
    ) -> McpConfig

作用：把 Config 转成 MCP 子系统需要的配置。普通调用方不用额外塞插件注册项。

数据流：进去 Config 和插件管理器 → 调带额外注册项的版本且传空迭代器 → 出来 McpConfig。

调用关系：它是公开简化入口，实际组装交给 to_mcp_config_with_plugin_registrations。

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

async fn to_mcp_config_with_plugin_registrations(
        &self,
        plugins_manager: &codex_core_plugins::PluginsManager,
        additional_plugin_registrations: impl IntoIterator<Item = McpServ

作用：完整组装 MCP 配置。它合并插件提供的服务器、额外注册项和用户配置的服务器。

数据流：进去 Config、插件管理器和额外注册项 → 加载活跃插件，过滤服务器，登记来源和顺序，再填 OAuth、沙箱、能力开关等字段 → 出来 McpConfig。

调用关系：Config::to_mcp_config 调用它，内部还会用 plugins_config_input、apply_plugin_mcp_server_requirements、prefix_mcp_tool_names。

调用图：调用 11 个内部函数（new, from_config, from_plugin, builder, get, plugins_for_config, apply_plugin_mcp_server_requirements, auth_keyring_backend_kind, plugins_config_input, prefix_mcp_tool_names (+1 more)）；被 1 处调用（to_mcp_config）；外部调用 5 个（default, default, default, enabled, use_legacy_landlock）。

fn prefix_mcp_tool_names(&self) -> bool

作用：判断 MCP 工具名是否要加前缀。加前缀能避免不同服务器的工具同名冲突。

数据流：进去 Config → 查看 NonPrefixedMcpToolNames 功能是否关闭 → 出来 true 表示要加前缀。

调用关系：to_mcp_config_with_plugin_registrations 会把这个决定写进 McpConfig。

调用图：被 1 处调用（to_mcp_config_with_plugin_registrations）；外部调用 1 个（enabled）。

async fn rebuild_preserving_session_layers(
        &self,
        refreshed_config: &Config,
    ) -> std::io::Result<Self>

作用：刷新配置时保留当前会话层。这样用户改了全局配置，也不会丢掉本会话启动时带的临时参数。

数据流：进去旧 Config 和刷新后的 Config → 取刷新后的非会话层，加回旧配置中的会话层，重新排序并重新加载 → 出来新的 Config。

调用关系：运行中热刷新配置时使用，最后仍交给 load_config_with_layer_stack 重新构造。

调用图：调用 3 个内部函数（get_layers, new, to_path_buf）；外部调用 2 个（default, load_config_with_layer_stack）。

async fn load_with_cli_overrides(
        cli_overrides: Vec<(String, TomlValue)>,
    ) -> std::io::Result<Self>

作用：用命令行覆盖项加载完整 Config。这是推荐的普通加载入口。

数据流：进去 CLI 覆盖列表 → 创建默认 ConfigBuilder，设置 cli_overrides 并 build → 出来 Config 或错误。

调用关系：CLI 启动路径通常从这里进入配置系统。

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

async fn load_default_with_cli_overrides(
        cli_overrides: Vec<(String, TomlValue)>,
    ) -> std::io::Result<Self>

作用：当用户配置坏掉时，用默认配置加 CLI 覆盖项启动。它给程序一个可恢复的保底方案。

数据流：进去 CLI 覆盖列表 → 找 codex_home，再调用指定 home 的默认加载函数 → 出来 Config。

调用关系：错误恢复路径会用它跳过用户配置文件。

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

async fn load_default_with_cli_overrides_for_codex_home(
        codex_home: PathBuf,
        cli_overrides: Vec<(String, TomlValue)>,
    ) -> std::io::Result<Self>

作用：在指定 Codex home 下加载默认配置，不读用户、项目或系统配置层。

数据流：进去 codex_home 和 CLI 覆盖 → 把默认 ConfigToml 转成 TOML，合并 CLI 层，反序列化后加载 → 出来 Config。

调用关系：Config::load_default_with_cli_overrides 调它；内部用 deserialize_config_toml_with_base 和 load_config_with_layer_stack。

调用图：调用 2 个内部函数（deserialize_config_toml_with_base, from_absolute_path_checked）；外部调用 7 个（load_config_with_layer_stack, build_cli_overrides_layer, merge_toml_values, default, default, default, try_from）。

async fn load_with_cli_overrides_and_harness_overrides(
        cli_overrides: Vec<(String, TomlValue)>,
        harness_overrides: ConfigOverrides,
    ) -> std::io::Result<Self>

作用：同时使用命令行覆盖和运行框架覆盖来加载 Config。适合 exec 这类需要强制某些行为的入口。

数据流：进去 CLI 覆盖和 ConfigOverrides → 设置到默认 ConfigBuilder 后 build → 出来 Config。

调用关系：特殊子命令或测试框架通过它进入完整配置加载流程。

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

fn resolve_profile_v2_config_path(
    codex_home: &Path,
    profile_name: &ProfileV2Name,
) -> AbsolutePathBuf

作用：把 profile 名字转换成对应的配置文件路径。profile 是一套可选配置预设。

数据流：进去 codex_home 和 ProfileV2Name → 拼成 <name>.config.toml 并按 codex_home 解析成绝对路径 → 出来 AbsolutePathBuf。

调用关系：profile 加载、主程序启动和归档 app-server 启动会用它找配置文件。

调用图：调用 1 个内部函数（resolve_path_against_base）；被 3 处调用（loader_overrides_for_profile, run_main, start_app_server_for_archive_command）；外部调用 1 个（format!）。

async fn load_config_as_toml_with_cli_overrides(
    codex_home: &Path,
    cwd: Option<&AbsolutePathBuf>,
    cli_overrides: Vec<(String, TomlValue)>,
    loader_overrides: LoaderOverrides,
) -> std:

作用：旧接口：只加载合并后的 ConfigToml，而不是完整 Config。注释明确提醒多数调用方不该再用它。

数据流：进去 codex_home、cwd、CLI 覆盖和 loader 覆盖 → 转交给下一层旧接口 → 出来 ConfigToml。

调用关系：它只是兼容包装，实际调用 load_config_as_toml_with_cli_and_loader_overrides。

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

async fn load_config_as_toml_with_cli_and_loader_overrides(
    codex_home: &Path,
    cwd: Option<&AbsolutePathBuf>,
    cli_overrides: Vec<(String, TomlValue)>,
    loader_overrides: LoaderOverrides

作用：旧接口：带 loader 覆盖加载 ConfigToml。风险是还没应用托管要求。

数据流：进去目录、cwd、CLI 覆盖和 LoaderOverrides → 转给更通用的 load options 函数 → 出来 ConfigToml。

调用关系：由 load_config_as_toml_with_cli_overrides 调用，继续委托给 load_config_as_toml_with_cli_and_load_options。

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

async fn load_config_as_toml_with_cli_and_load_options(
    codex_home: &Path,
    cwd: Option<&AbsolutePathBuf>,
    cli_overrides: Vec<(String, TomlValue)>,
    options: impl Into<ConfigLoadOptions>

作用：旧接口：用加载选项得到半成品 ConfigToml。它只取结果中的 config_toml。

数据流：进去 codex_home、cwd、CLI 覆盖和加载选项 → 调 load_config_toml_with_layer_stack → 出来其中的 ConfigToml。

调用关系：这是几个旧 TOML 加载包装的最后一层。

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

async fn load_config_toml_with_layer_stack(
    codex_home: &Path,
    cwd: Option<&AbsolutePathBuf>,
    cli_overrides: Vec<(String, TomlValue)>,
    options: impl Into<ConfigLoadOptions>,
) -> std::

作用：加载合并后的原始配置和它的配置层堆栈。配置层堆栈记录每个值来自哪里。

数据流：进去 codex_home、cwd、CLI 覆盖和加载选项 → 调 load_config_layers_state 合并层，再反序列化成 ConfigToml → 出来 ConfigTomlLoadResult。

调用关系：启动早期需要先看原始配置的路径会调用它，比如 bootstrap 配置加载。

调用图：调用 2 个内部函数（load_config_layers_state, deserialize_config_toml_with_base）；被 4 处调用（load_config_as_toml_with_cli_and_load_options, load_bootstrap_config_or_exit, load_bootstrap_config_or_exit, start_app_server_for_archive_command）。

fn deserialize_config_toml_with_base(
    root_value: TomlValue,
    config_base_dir: &Path,
) -> std::io::Result<ConfigToml>

作用：把 TOML 值变成 ConfigToml，并让相对路径按指定目录解析。这样配置里的相对路径不会乱飘。

数据流：进去 TOML 根值和基础目录 → 临时设置 AbsolutePathBufGuard，再 try_into → 出来 ConfigToml 或数据错误。

调用关系：配置编辑、角色层加载、默认加载和半成品加载都会用它。

调用图：调用 1 个内部函数（new）；被 5 处调用（apply_edits, load_role_layer_toml, deserialize_effective_config, load_default_with_cli_overrides_for_codex_home, load_config_toml_with_layer_stack）；外部调用 1 个（try_into）。

fn validate_feature_requirements_for_config_toml(
    cfg: &ConfigToml,
    feature_requirements: Option<&Sourced<FeatureRequirementsToml>>,
) -> std::io::Result<()>

作用：检查用户配置的功能开关是否违反托管要求。托管要求就是管理员或系统强制的规则。

数据流：进去 ConfigToml 和可选功能要求 → 先检查显式设置，再检查要求本身 → 出来成功或错误。

调用关系：apply_edits 在写配置前会调用它，避免保存不合规配置。

调用图：调用 2 个内部函数（validate_explicit_feature_settings_in_config_toml, validate_feature_requirements_in_config_toml）；被 1 处调用（apply_edits）。

fn load_catalog_json(path: &AbsolutePathBuf) -> std::io::Result<ModelsResponse>

作用：从 JSON 文件读取模型目录。模型目录告诉程序有哪些模型可用。

数据流：进去 JSON 文件路径 → 读文件、解析成 ModelsResponse，并确保至少有一个模型 → 出来模型目录或错误。

调用关系：load_model_catalog 在用户配置了 model_catalog_json 时调用它。

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

fn load_model_catalog(
    model_catalog_json: Option<AbsolutePathBuf>,
) -> std::io::Result<Option<ModelsResponse>>

作用：按需加载模型目录文件。没配置路径时就什么也不加载。

数据流：进去可选路径 → 有路径就调用 load_catalog_json，没有就返回 None → 出来可选 ModelsResponse。

调用关系：Config::load_config_with_layer_stack 用它填 Config.model_catalog。

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

fn filter_mcp_servers_by_requirements(
    mcp_servers: &mut HashMap<String, McpServerConfig>,
    mcp_requirements: Option<&Sourced<BTreeMap<String, McpServerRequirement>>>,
)

作用：按全局 MCP 服务器白名单过滤服务器。没在要求里或身份不匹配的服务器会被禁用。

数据流：进去可变服务器表和可选要求 → 对每个服务器检查名称和命令/URL 是否匹配 → 修改 enabled 和 disabled_reason。

调用关系：Config::apply_plugin_mcp_server_requirements 会用它处理全局 MCP 要求。

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

fn filter_plugin_mcp_servers_by_requirements(
    plugin_config_name: &str,
    mcp_servers: &mut HashMap<String, McpServerConfig>,
    plugin_requirements: Option<&Sourced<BTreeMap<String, PluginRequ

作用：按插件专属要求过滤插件提供的 MCP 服务器。不同插件可以有各自允许的服务器清单。

数据流：进去插件配置名、服务器表和插件要求 → 找到该插件要求后逐个匹配服务器 → 不允许的服务器被禁用并记录原因。

调用关系：Config::apply_plugin_mcp_server_requirements 会先用它过滤插件服务器。

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

fn constrain_mcp_servers(
    mcp_servers: HashMap<String, McpServerConfig>,
    mcp_requirements: Option<&Sourced<BTreeMap<String, McpServerRequirement>>>,
) -> ConstraintResult<Constrained<HashMap<S

作用：把 MCP 服务器表包成带约束的值。带约束的值会在以后设置时自动套用规则。

数据流：进去服务器表和可选要求 → 没要求就 allow_any，有要求就创建 normalized 包装并在内部过滤 → 出来 Constrained 服务器表。

调用关系：Config::load_config_with_layer_stack 在最终保存 mcp_servers 前调用它。

调用图：调用 2 个内部函数（allow_any, normalized）；被 1 处调用（load_config_with_layer_stack）。

fn apply_requirement_constrained_value(
    field_name: &'static str,
    configured_value: T,
    constrained_value: &mut ConstrainedWithSource<T>,
    startup_warnings: &mut Vec<String>,
) -> std::i

作用：把一个配置值写进受要求限制的字段。如果不被允许，它会退回要求允许的值并记录启动警告。

数据流：进去字段名、配置值、受约束值和警告列表 → 尝试 set，失败则取 fallback、写日志和警告，再设置 fallback → 出来是否发生过回退。

调用关系：Config::load_config_with_layer_stack 多次调用它处理审批、权限、Web 搜索、Windows 沙箱等字段。

调用图：被 1 处调用（load_config_with_layer_stack）；外部调用 4 个（get, set, format!, warn!）。

fn mcp_server_matches_requirement(
    requirement: &McpServerRequirement,
    server: &McpServerConfig,
) -> bool

作用：判断一个 MCP 服务器是否符合要求里的身份。身份可以是启动命令，也可以是 HTTP URL。

数据流：进去 McpServerRequirement 和 McpServerConfig → 比较 stdio command 或 streamable HTTP url → 出来 true 或 false。

调用关系：两个 MCP 过滤函数会用它做具体匹配判断。

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

async fn load_global_mcp_servers(
    codex_home: &Path,
) -> std::io::Result<BTreeMap<String, McpServerConfig>>

作用：只读取全局 MCP 服务器配置，用来支持 mcp add/remove 等命令。它故意不带项目上下文。

数据流：进去 codex_home → 加载无 cwd 的配置层，取 mcp_servers，检查不支持的 bearer_token，再反序列化 → 出来服务器表。

调用关系：MCP 增删命令和相关测试会调用它，内部用 ensure_no_inline_bearer_tokens。

调用图：调用 2 个内部函数（load_config_layers_state, ensure_no_inline_bearer_tokens）；被 11 处调用（run_add, run_remove, add_and_remove_server_updates_global_config, add_cant_add_command_and_url, add_streamable_http_rejects_removed_flag, add_streamable_http_with_custom_env_var, add_streamable_http_with_oauth_options, add_streamable_http_without_manual_token, add_with_env_preserves_key_order_and_values, get_disabled_server_shows_single_line (+1 more)）；外部调用 3 个（new, new, default）。

fn ensure_no_inline_bearer_tokens(value: &TomlValue) -> std::io::Result<()>

作用：拒绝 MCP 配置里直接写明文 bearer_token。它要求用户改用环境变量，避免秘密泄漏。

数据流：进去 TOML 值 → 如果是服务器表，就检查每个服务器是否有 bearer_token 字段 → 有则返回错误，否则成功。

调用关系：load_global_mcp_servers 在解析全局服务器前调用它。

调用图：被 1 处调用（load_global_mcp_servers）；外部调用 3 个（as_table, new, format!）。

fn set_project_trust_level_inner(
    doc: &mut DocumentMut,
    project_path: &Path,
    trust_level: TrustLevel,
) -> anyhow::Result<()>

作用：在 TOML 文档里设置某个项目的信任级别。信任级别会影响默认审批和权限选择。

数据流：进去可编辑 TOML 文档、项目路径和信任级别 → 确保 projects 表结构是人类友好的普通表，再写入 trust_level → 文档被原地修改。

调用关系：配置编辑 apply 流程会调用它做实际文档修改。

调用图：调用 1 个内部函数（project_trust_key）；被 1 处调用（apply）；外部调用 7 个（as_table_mut, anyhow!, to_string, Table, new, table, value）。

fn set_project_trust_level(
    codex_home: &Path,
    project_path: &Path,
    trust_level: TrustLevel,
) -> anyhow::Result<()>

作用：把某项目的信任级别写入 CODEX_HOME/config.toml。它是对编辑器流程的便捷包装。

数据流：进去 codex_home、项目路径和信任级别 → 创建 ConfigEditsBuilder，添加设置信任级别操作并阻塞应用 → 出来成功或 anyhow 错误。

调用关系：线程启动、配置读取、插件/MCP/权限列表等流程会用它记录项目是否可信。

调用图：调用 1 个内部函数（new）；被 10 处调用（thread_start_task, config_read_includes_project_layers_for_cwd, hooks_list_uses_each_cwds_effective_feature_enablement, hooks_list_uses_root_repo_hooks_for_linked_worktrees, mcp_server_status_list_uses_thread_project_local_config, permission_profile_list_discovers_project_profiles_without_default_selection, permission_profile_list_resolves_project_profiles_and_paginates, plugin_list_uses_home_config_for_enabled_state, thread_start_respects_project_config_from_cwd, thread_start_skips_trust_write_when_project_is_already_trusted）。

fn set_default_oss_provider(codex_home: &Path, provider: &str) -> std::io::Result<()>

作用：保存默认开源模型提供商偏好。写入前会先验证提供商名称合法。

数据流：进去 codex_home 和 provider 字符串 → 验证 provider，构造设置 oss_provider 的编辑并写 config.toml → 出来 IO 结果。

调用关系：本地/开源模型选择流程会调用它持久化用户选择。

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

fn resolve_tool_suggest_config(
    config_toml: &ConfigToml,
    config_layer_stack: &ConfigLayerStack,
) -> ToolSuggestConfig

作用：解析工具建议配置。工具建议就是界面或模型可以发现、隐藏某些工具的设置。

数据流：进去 ConfigToml 和配置层堆栈 → 取 cfg.tool_suggest，再交给通用解析函数 → 出来 ToolSuggestConfig。

调用关系：Config::load_config_with_layer_stack 在生成总 Config 时调用它。

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

fn resolve_tool_suggest_config_from_layer_stack(
    config_layer_stack: &ConfigLayerStack,
) -> ToolSuggestConfig

作用：只从配置层堆栈解析工具建议配置。适合运行中刷新某一层配置后重新计算。

数据流：进去 ConfigLayerStack → 从 effective_config 里取 tool_suggest 并反序列化，再走通用解析 → 出来 ToolSuggestConfig。

调用关系：refresh_runtime_config 和 reload_user_config_layer 会用它热更新工具建议。

调用图：调用 2 个内部函数（effective_config, resolve_tool_suggest_config_from_config）；被 2 处调用（refresh_runtime_config, reload_user_config_layer）。

fn resolve_tool_suggest_config_from_config(
    tool_suggest: Option<&ToolSuggestConfig>,
    config_layer_stack: &ConfigLayerStack,
) -> ToolSuggestConfig

作用：工具建议解析的核心逻辑。它会清理空 ID，并按配置层顺序合并禁用工具且去重。

数据流：进去可选 ToolSuggestConfig 和层堆栈 → 过滤 discoverables，逐层收集 disabled_tools，规范化并去重 → 出来干净的 ToolSuggestConfig。

调用关系：resolve_tool_suggest_config 和 resolve_tool_suggest_config_from_layer_stack 都委托它。

调用图：调用 1 个内部函数（get_layers）；被 2 处调用（resolve_tool_suggest_config, resolve_tool_suggest_config_from_layer_stack）；外部调用 2 个（new, new）。

fn thread_store_config(thread_store: Option<ThreadStoreToml>) -> ThreadStoreConfig

作用：把 TOML 里的线程存储设置转成运行时枚举。线程存储决定会话记录存在本地还是内存里。

数据流：进去可选 ThreadStoreToml → Local 变 Local，InMemory 带 id，None 默认 Local → 出来 ThreadStoreConfig。

调用关系：Config::load_config_with_layer_stack 用它填 experimental_thread_store。

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

fn is_session_layer(source: &ConfigLayerSource) -> bool

作用：判断一个配置层是不是会话临时参数层。会话层需要在刷新配置时特殊保留。

数据流：进去 ConfigLayerSource → 判断是否等于 SessionFlags → 出来布尔值。

调用关系：Config::rebuild_preserving_session_layers 用它筛选旧配置和新配置的层。

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

fn has_profiles(&self) -> bool

作用：判断当前是否有可用的命名权限档案。空表不算真正有 profiles。

数据流：进去 EffectivePermissionSelection → 查看 profiles 是否存在且不为空 → 出来 true 或 false。

调用关系：load_config_with_layer_stack 用它决定缺少 default_permissions 时是否报错。

fn profiles_are_active(
        &self,
        default_permissions_override: Option<&str>,
        permission_config_syntax: Option<PermissionConfigSyntax>,
    ) -> bool

作用：判断命名权限档案模式是否应该生效。它会考虑管理员要求、命令行覆盖和配置语法。

数据流：进去 default_permissions 覆盖和解析出的权限语法 → 任一条件说明 profiles 应生效就返回 true → 出来布尔值。

调用关系：Config::load_config_with_layer_stack 用它决定走 profiles 逻辑还是旧 sandbox_mode 逻辑。

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

fn resolve_permission_config_syntax(
    config_layer_stack: &ConfigLayerStack,
    cfg: &ConfigToml,
    sandbox_mode_override: Option<SandboxMode>,
) -> Option<PermissionConfigSyntax>

作用：判断用户正在用旧 sandbox_mode 语法还是新 permissions profiles 语法。两种语法不能混着糊涂用。

数据流：进去配置层堆栈、ConfigToml 和 sandbox override → 按最高优先级会话层、各层顺序、最终 cfg 判断 → 出来 Legacy、Profiles 或 None。

调用关系：Config::load_config_with_layer_stack 在解析权限前调用它决定分支。

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

fn apply_managed_filesystem_constraints(
    file_system_sandbox_policy: &mut FileSystemSandboxPolicy,
    filesystem_constraints: &codex_config::FilesystemConstraints,
)

作用：把托管文件系统限制加进沙箱策略。主要是追加禁止读取的路径或通配规则。

数据流：进去可变 FileSystemSandboxPolicy 和 filesystem constraints → 把 deny_read 转成沙箱条目，避免重复后追加 → 策略被原地收紧。

调用关系：Config::load_config_with_layer_stack 在最终权限档案成形前调用它。

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

fn dedupe_absolute_paths(paths: &mut Vec<AbsolutePathBuf>)

作用：给绝对路径列表去重，同时保留原顺序。这样同一个工作区不会出现多次。

数据流：进去可变路径 Vec → 用 HashSet 记录见过的路径并 retain → 原列表变成去重版本。

调用关系：effective_workspace_roots 和 load_config_with_layer_stack 都用它清理工作区根目录。

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

fn resolve_oss_provider(
    explicit_provider: Option<&str>,
    config_toml: &ConfigToml,
) -> Option<String>

作用：决定使用哪个开源模型提供商。命令行显式指定会覆盖全局配置。

数据流：进去可选显式 provider 和 ConfigToml → 有显式值就返回它，否则返回 config_toml.oss_provider → 出来可选字符串。

调用关系：run_main 和归档 app-server 启动会用它选择本地提供商。

调用图：被 3 处调用（run_main, run_main, start_app_server_for_archive_command）。

fn resolve_web_search_mode(config_toml: &ConfigToml, features: &Features) -> Option<WebSearchMode>

作用：从配置和功能开关决定 Web 搜索模式。Web 搜索可以是实时、缓存或关闭。

数据流：进去 ConfigToml 和 Features → 配置里写了就优先用，否则看 WebSearchCached/WebSearchRequest 开关 → 出来可选 WebSearchMode。

调用关系：Config::load_config_with_layer_stack 用它生成受约束的 web_search_mode。

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

fn resolve_web_search_config(config_toml: &ConfigToml) -> Option<WebSearchConfig>

作用：读取 Web 搜索工具的附加配置。比如工具参数之类的细节。

数据流：进去 ConfigToml → 沿 tools.web_search 找配置并转换 → 出来 WebSearchConfig 或 None。

调用关系：总配置加载时填 Config.web_search_config。

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

fn resolve_experimental_request_user_input_enabled(config_toml: &ConfigToml) -> bool

作用：判断实验性的 request_user_input 工具是否启用。没写配置时默认启用。

数据流：进去 ConfigToml → 查 tools.experimental_request_user_input.enabled，缺省视为 true → 出来布尔值。

调用关系：Config::load_config_with_layer_stack 用它决定是否注册该实验工具。

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

fn resolve_code_mode_config(config_toml: &ConfigToml) -> CodeModeConfig

作用：解析实验性 code mode 的配置。它目前主要关心要排除哪些工具命名空间。

数据流：进去 ConfigToml → 从 features.code_mode 中取配置型开关，提取 excluded_tool_namespaces 或默认空列表 → 出来 CodeModeConfig。

调用关系：总配置加载时调用，内部依赖 code_mode_toml_config。

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

fn resolve_multi_agent_v2_config(config_toml: &ConfigToml) -> MultiAgentV2Config

作用：解析多代理 V2 配置，并用默认值补齐缺项。它还处理空字符串表示关闭某些提示文本。

数据流：进去 ConfigToml → 取 features.multi_agent_v2 配置，先建默认值，再逐项覆盖等待时间、提示、命名空间和展示选项 → 出来 MultiAgentV2Config。

调用关系：Config::load_config_with_layer_stack 调用它，后续还会做合法性校验。

调用图：调用 3 个内部函数（defaults_for_max_concurrency, multi_agent_v2_toml_config, resolve_optional_prompt_text）；被 1 处调用（load_config_with_layer_stack）。

fn resolve_terminal_resize_reflow_config(config_toml: &ConfigToml) -> TerminalResizeReflowConfig

作用：解析终端窗口大小变化时的重排限制。0 表示不限制保留行，缺省表示自动。

数据流：进去 ConfigToml → 如果没有 tui 配置就默认；否则把 terminal_resize_reflow_max_rows 映射成 Auto、Disabled 或 Limit → 出来 TerminalResizeReflowConfig。

调用关系：总配置加载时用它填 TUI 重排配置。

调用图：被 1 处调用（load_config_with_layer_stack）；外部调用 2 个（default, Limit）。

fn resolve_optional_prompt_text(
    configured: Option<&Option<String>>,
    default: Option<String>,
) -> Option<String>

作用：解析可选提示文本。它区分“没配置”“配置为空字符串”和“配置了内容”。

数据流：进去配置值和默认值 → 空字符串变 None，有内容用内容，没配置用默认 → 出来可选字符串。

调用关系：resolve_multi_agent_v2_config 用它处理 root/subagent 的提示文本。

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

fn code_mode_toml_config(features: Option<&FeaturesToml>) -> Option<&CodeModeConfigToml>

作用：从 features 表里取 code_mode 的详细配置。单纯 enabled 不带详细配置时返回 None。

数据流：进去可选 FeaturesToml → 找 code_mode，如果是 Config 就返回引用，如果是 Enabled 或缺失就 None → 出来可选配置引用。

调用关系：resolve_code_mode_config 调用它。

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

fn multi_agent_v2_toml_config(features: Option<&FeaturesToml>) -> Option<&MultiAgentV2ConfigToml>

作用：从 features 表里取 multi_agent_v2 的详细配置。它只关心配置型开关。

数据流：进去可选 FeaturesToml → 找 multi_agent_v2，Config 返回配置引用，Enabled/缺失返回 None → 出来可选配置引用。

调用关系：resolve_multi_agent_v2_config 调用它。

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

fn network_proxy_toml_config(features: Option<&FeaturesToml>) -> Option<&NetworkProxyConfigToml>

作用：从 features 表里取 network_proxy 的详细配置。它用于进一步调整托管网络代理。

数据流：进去可选 FeaturesToml → 如果 network_proxy 是 Config 就返回配置，否则 None → 出来可选配置引用。

调用关系：Config::load_config_with_layer_stack 和 network_proxy_spec_for_active_permission_profile 用它。

调用图：被 2 处调用（load_config_with_layer_stack, network_proxy_spec_for_active_permission_profile）。

fn resolve_web_search_mode_for_turn(
    web_search_mode: &Constrained<WebSearchMode>,
    permission_profile: &PermissionProfile,
) -> WebSearchMode

作用：为某一轮对话决定真正使用的 Web 搜索模式。它会避开当前权限不允许的模式。

数据流：进去受约束的 WebSearchMode 和权限档案 → 先看偏好值，权限禁用时优先降级，再按允许列表寻找可用模式 → 出来最终模式，最坏关闭。

调用关系：每轮请求准备工具时会用它把配置偏好和权限约束对齐。

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

fn validate_multi_agent_v2_wait_timeout(label: &str, value: i64) -> std::io::Result<()>

作用：检查多代理 V2 等待超时时间是否在硬性范围内。太小或太大都直接报错。

数据流：进去字段名和毫秒值 → 比较硬最小值和硬最大值 → 出来成功或 InvalidInput 错误。

调用关系：Config::load_config_with_layer_stack 校验 multi_agent_v2 三个 timeout 时调用它。

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

fn validate_multi_agent_v2_tool_namespace(namespace: Option<&str>) -> std::io::Result<()>

作用：检查多代理工具命名空间是否合法。命名空间就是工具名前面的分组名。

数据流：进去可选 namespace → None 通过；有值则检查非空、无首尾空白、字符集、长度和保留名 → 出来成功或错误。

调用关系：Config::load_config_with_layer_stack 在接受 multi_agent_v2 配置前调用它。

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

async fn load_from_base_config_with_overrides(
        cfg: ConfigToml,
        overrides: ConfigOverrides,
        codex_home: AbsolutePathBuf,
    ) -> std::io::Result<Self>

作用：测试专用：从给定 ConfigToml 和覆盖项构造 Config。它故意忽略 requirements.toml 强制规则。

数据流：进去基础 cfg、overrides 和 codex_home → 创建默认 ConfigLayerStack，再调用 load_config_with_layer_stack → 出来 Config。

调用关系：test_config 和多种配置单元测试会用它。

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

async fn load_config_with_layer_stack(
        fs: &dyn ExecutorFileSystem,
        cfg: ConfigToml,
        overrides: ConfigOverrides,
        codex_home: AbsolutePathBuf,
        config_layer_stack

作用：这是本文件最核心的装配函数。它把已经合并的 ConfigToml、运行时覆盖项、Codex home 和配置层堆栈，变成最终 Config。

数据流：进去文件系统接口、ConfigToml、覆盖项、codex_home 和 ConfigLayerStack → 校验废弃字段和模型提供商，解析功能开关、权限、沙箱、网络代理、MCP、模型、提示文件、路径、TUI、代理配置，并应用托管要求 → 出来完整 Config 或明确错误。

调用关系：ConfigBuilder::build_inner、默认加载、测试加载、刷新配置都会交给它；它又调用本文件大量 resolve/validate/helper 函数，是配置系统的中枢。

调用图：调用 47 个内部函数（derive_permission_profile, get_active_project, validate_model_providers, requirements, requirements_toml, startup_warnings, default, load_agent_roles, apply_managed_filesystem_constraints, apply_requirement_constrained_value (+15 more)）；外部调用 19 个（pin, default, try_read_non_empty_file, new, new, sandbox_mode_requirement_for_permission_profile, resolve_root_git_project_for_trust, memory_root, built_in_model_providers, merge_configured_model_providers (+9 more)）。

async fn try_read_non_empty_file(
        fs: &dyn ExecutorFileSystem,
        path: Option<&AbsolutePathBuf>,
        context: &str,
    ) -> std::io::Result<Option<String>>

作用：读取一个可选文本文件，并要求内容非空。它常用于从文件加载提示词。

数据流：进去文件系统、可选绝对路径和上下文说明 → 没路径返回 None，有路径就读文本、trim，空内容报错 → 出来 Some 文本或错误。

调用关系：Config::load_config_with_layer_stack 用它读取 model instructions 和 compact prompt 文件。

调用图：调用 2 个内部函数（read_file_text, from_abs_path）；外部调用 2 个（new, format!）。

fn set_windows_sandbox_enabled(&mut self, value: bool)

作用：打开或关闭 Windows 非提升沙箱。非提升沙箱就是用较低权限运行子进程。

数据流：进去布尔值 → true 设置为 Unelevated；false 只在当前正是 Unelevated 时清掉 → 更新 permissions.windows_sandbox_mode。

调用关系：运行时 UI 或控制接口切换 Windows 沙箱时可调用它。

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

fn set_windows_elevated_sandbox_enabled(&mut self, value: bool)

作用：打开或关闭 Windows 提升沙箱模式。它只会清掉自己设置的 Elevated 状态，不误删其他模式。

数据流：进去布尔值 → true 设置 Elevated；false 且当前是 Elevated 时设 None，否则保持 → 更新权限里的 Windows 沙箱模式。

调用关系：Windows 沙箱相关控制路径会用它。

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

fn managed_network_requirements_enabled(&self) -> bool

作用：判断当前是否有托管网络要求正在生效。权限完全禁用时不算启用。

数据流：进去 Config → 检查权限档案不是 Disabled，且 requirements_toml 里有 network 要求 → 出来布尔值。

调用关系：界面或执行层可用它决定是否展示/使用托管网络限制。

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

fn network_proxy_spec_for_active_permission_profile(
        &self,
        active_permission_profile: &ActivePermissionProfile,
        permission_profile: &PermissionProfile,
    ) -> std::io::Resul

作用：为某个被选中的权限档案重新计算网络代理规格。切换权限时网络代理也要跟着变。

数据流：进去 active profile 和 PermissionProfile → 如果档案允许代理，就从有效配置重读该 profile 的代理设置并套功能配置，再合并托管网络要求 → 出来可选 NetworkProxySpec。

调用关系：权限档案切换流程会用它，内部复用 profile_allows_configured_network_proxy、network_proxy_toml_config 和 build_network_proxy_spec。

调用图：调用 8 个内部函数（effective_config, requirements, build_network_proxy_spec, network_proxy_toml_config, apply_network_proxy_feature_config, network_proxy_config_for_profile_selection, profile_allows_configured_network_proxy, network_sandbox_policy）；外部调用 2 个（enabled, default）。

fn bundled_skills_enabled(&self) -> bool

作用：判断内置 skills 是否启用。skills 可以理解为随程序打包的能力说明或工具包。

数据流：进去 Config → 把 config_layer_stack 交给 manager 的判断函数 → 出来布尔值。

调用关系：技能管理相关流程会通过它读取最终开关。

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

fn guardian_policy_config_from_requirements(
    requirements_toml: &ConfigRequirementsToml,
) -> Option<String>

作用：从托管要求里取 Guardian 策略配置。Guardian 是审查/安全判断相关的策略层。

数据流：进去 ConfigRequirementsToml → 取 guardian_policy_config 字符串并规范化空白 → 出来可选策略文本。

调用关系：Config::load_config_with_layer_stack 在准备 guardian_policy_config 时调用它。

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

fn merge_managed_permission_profiles(
    configured_permissions: Option<&PermissionsToml>,
    requirements_toml: &ConfigRequirementsToml,
) -> std::io::Result<Option<PermissionsToml>>

作用：把管理员下发的权限档案合并进用户配置。若同名冲突就报错，避免谁覆盖谁不清楚。

数据流：进去用户 permissions 和 requirements_toml → 没托管档案就返回用户档案，有则复制用户档案再插入托管档案 → 出来合并结果或冲突错误。

调用关系：resolve_effective_permission_selection 调用它作为权限选择解析的第一步。

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

fn resolve_effective_permission_selection(
    configured_permissions: Option<&PermissionsToml>,
    default_permissions_override: Option<&'a str>,
    configured_default_permissions: Option<&'a str>,

作用：解析最终可用的权限档案目录和当前选中的档案名。它同时检查用户命名和管理员要求。

数据流：进去配置档案、命令行默认权限、配置默认权限、requirements 和警告列表 → 合并托管档案、验证名称和目录、解析默认选择 → 出来 EffectivePermissionSelection。

调用关系：Config::load_config_with_layer_stack 在权限大分支前调用它。

调用图：调用 4 个内部函数（merge_managed_permission_profiles, validate_user_permission_profile_names, resolve_default_permissions, validate_required_permission_profile_catalog）；被 1 处调用（load_config_with_layer_stack）。

fn resolve_default_permissions(
    default_permissions_override: Option<&'a str>,
    configured_default_permissions: Option<&'a str>,
    requirements_toml: &'a ConfigRequirementsToml,
    startup_w

作用：决定 default_permissions 最终是哪一个。管理员白名单存在时，不允许的选择会回退并写启动警告。

数据流：进去命令行选择、配置选择、requirements 和警告列表 → 若无白名单直接用选择；有白名单则找 fallback 并检查 selected 是否允许 → 出来可选档案名。

调用关系：resolve_effective_permission_selection 调用它。

调用图：调用 1 个内部函数（is_permission_allowed）；被 1 处调用（resolve_effective_permission_selection）；外部调用 2 个（new, format!）。

fn validate_required_permission_profile_catalog(
    requirements_toml: &ConfigRequirementsToml,
    available_permissions: Option<&PermissionsToml>,
) -> std::io::Result<()>

作用：校验 requirements.toml 里提到的权限档案都存在且默认值被允许。否则托管要求本身就是坏的。

数据流：进去 requirements_toml 和可用权限档案 → 检查 allowed_permission_profiles 引用是否已定义、default_permissions 是否合理 → 出来成功或错误。

调用关系：resolve_effective_permission_selection 在选档案前调用它。

调用图：调用 1 个内部函数（is_permission_allowed）；被 1 处调用（resolve_effective_permission_selection）；外部调用 2 个（new, format!）。

fn implicit_default_permissions(
    allowed_permission_profiles: &BTreeMap<String, bool>,
) -> Option<&'static str>

作用：在允许列表同时允许工作区和只读时，给出隐式默认工作区权限。否则无法安全猜默认值。

数据流：进去 allowed_permission_profiles → 检查 :workspace 和 :read-only 是否都允许 → 出来 Some(':workspace') 或 None。

调用关系：resolve_default_permissions 和 validate_required_permission_profile_catalog 会用它补默认值。

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

fn is_permission_allowed(
    allowed_permission_profiles: &BTreeMap<String, bool>,
    profile_id: &str,
) -> bool

作用：检查某个权限档案 ID 是否在允许列表里且值为 true。

数据流：进去允许列表和 profile_id → 查表并把缺失当 false → 出来布尔值。

调用关系：implicit_default_permissions、resolve_default_permissions 和 validate_required_permission_profile_catalog 都用它做白名单判断。

调用图：被 3 处调用（implicit_default_permissions, resolve_default_permissions, validate_required_permission_profile_catalog）。

fn normalize_guardian_policy_config(value: Option<&str>) -> Option<String>

作用：清理 Guardian 策略文本。全是空白的配置会被当成没配置。

数据流：进去可选字符串引用 → trim 后如果非空就复制成 String，否则 None → 出来可选文本。

调用关系：guardian_policy_config_from_requirements 和 Config::load_config_with_layer_stack 的配置回退逻辑会用它。

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

fn find_codex_home() -> std::io::Result<AbsolutePathBuf>

作用：找到 Codex 配置目录。可以由 CODEX_HOME 环境变量指定，否则默认 ~/.codex。

数据流：进去没有参数 → 调底层 home-dir 工具解析并校验环境变量目录 → 出来 AbsolutePathBuf 或 IO 错误。

调用关系：主程序、CLI、登录、配置编辑、profile 加载等许多启动路径都会先调用它。

调用图：被 21 处调用（from_listen_url, default_control_socket_path, run_main_with_transport_options, cli_main, disable_feature_in_config, fallback_state_check, enable_feature_in_config, loader_overrides_for_profile, run_add, run_remove (+11 more)）；外部调用 1 个（find_codex_home）。

fn log_dir(cfg: &Config) -> std::io::Result<PathBuf>

作用：返回当前配置指定的日志目录。它只读配置，不检查目录是否存在。

数据流：进去 Config → 克隆 cfg.log_dir → 出来 PathBuf。

调用关系：init_login_file_logging 用它决定登录相关日志写到哪里。

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

fn from_optional_paths(
        codex_self_exe: Option<PathBuf>,
        codex_linux_sandbox_exe: Option<PathBuf>,
    ) -> std::io::Result<Self>

作用：这个函数用来从“可能有、也可能没有”的路径配置里生成运行时路径。它会强制要求 Codex 主程序路径必须存在，因为没有它就没法可靠地启动后续助手进程。

数据流：进去的是两个可选路径：Codex 自己的可执行文件路径，以及可选的 Linux 沙箱别名路径。它先检查第一个路径有没有；如果没有，就产出一个“输入无效”的错误。若有，就把这两个值交给 ExecServerRuntimePaths::new 继续检查并整理，最后出来的是一份可用的 ExecServerRuntimePaths，或者一个说明哪里不对的错误。

调用关系：它通常被更上层的启动流程调用，比如 run_main、run_main_with_transport_options、build_prompt_input 以及启动归档命令的流程。这些地方拿到外部传入或配置出来的路径后，会先通过它做一道入口检查；它自己不做全部细节，而是把真正的路径规范化工作交给 ExecServerRuntimePaths::new。

调用图：被 8 处调用（run_main_with_transport_options, list_accessible_connectors_from_mcp_tools_with_options_and_status, build_prompt_input, run_main, run_main, run_main, run_main, start_app_server_for_archive_command）；外部调用 1 个（new）。

fn new(
        codex_self_exe: PathBuf,
        codex_linux_sandbox_exe: Option<PathBuf>,
    ) -> std::io::Result<Self>

作用：这个函数是正式创建 ExecServerRuntimePaths 的地方。它把传入的路径转换成经过验证的绝对路径，确保后面用这些路径启动程序时不会受当前目录影响。

数据流：进去的是一个必填的 Codex 可执行文件路径，以及一个可选的 Linux 沙箱别名路径。它会分别调用 absolute_path 检查这些路径是不是合格的绝对路径；可选路径如果没有就保持为空，如果有也必须通过检查。出来的是一个包含干净路径的 ExecServerRuntimePaths；如果任一路径不合格，就返回输入错误。

调用关系：它既会被 ExecServerRuntimePaths::from_optional_paths 调用，也会被很多已经拿到确定路径的代码直接调用，比如运行 exec-server 命令、构建测试环境、权限相关测试等。它是这份“运行时地址卡”的核心装配点，具体的单个路径检查则交给 absolute_path。

调用图：调用 1 个内部函数（absolute_path）；被 27 处调用（runtime_start_args_forward_environment_manager, run_exec_server_command, test_runtime_paths, build_with_home_and_base_url, test_runtime_paths, helper_permissions_include_helper_read_root_without_additional_permissions, helper_permissions_include_linux_sandbox_alias_parent, helper_permissions_preserve_existing_writes, sandbox_exec_request_carries_helper_env, processor_exit_reports_closed_virtual_stream (+15 more)）。

fn absolute_path(path: PathBuf) -> std::io::Result<AbsolutePathBuf>

作用：这个小函数专门检查并转换一个路径，确认它是绝对路径。它把底层路径库给出的错误包装成普通的输入错误，方便上层统一处理。

数据流：进去的是一个 PathBuf，也就是一段文件路径。它先把路径借出来给 AbsolutePathBuf::from_absolute_path 检查；如果路径确实是绝对路径，就出来一个 AbsolutePathBuf；如果不是或不合法，就出来一个 std::io::Error，错误类型表示“传入参数不对”。它不修改外部状态。

调用关系：它只被 ExecServerRuntimePaths::new 调用，是创建运行时路径时的基础检查工具。new 负责决定要检查哪些路径，absolute_path 负责把每个单独路径变成安全可靠的绝对路径。

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

fn request_user_input_available_modes(features: &Features) -> Vec<ModeKind>

作用：这个函数决定哪些协作模式可以向用户要输入。它把固定可见的模式列表过滤一遍，只留下本来允许请求用户输入的模式，或者在功能开关允许时把默认模式也放进来。

数据流：进去的是一组功能开关 Features，以及文件里引用的可见协作模式列表。函数逐个检查模式：如果模式本身允许请求用户输入，就保留；如果打开了 DefaultModeRequestUserInput，并且这个模式是 Default，也保留。出来的是一个模式列表，供后面展示或选择。

调用关系：它处在界面和配置之间，像给菜单做筛选的人。调用图里没有显示它再调用本文件的其他函数，它主要依赖模式自身的判断和功能开关来给外部提供可用选项。

fn shell_command_backend_for_features(features: &Features) -> ShellCommandBackendConfig

作用：这个函数判断普通 shell 命令应该走哪种后端。简单说，如果 shell 工具和 zsh-fork 这两个开关都开了，就用 zsh-fork；否则用经典方式。

数据流：进去的是 Features，也就是当前启用的功能开关。它读取 ShellTool 和 ShellZshFork 两个开关：两者都开，输出 ShellCommandBackendConfig::ZshFork；只要有一个没开，输出 ShellCommandBackendConfig::Classic。它不改动任何外部状态。

调用关系：它被 shell_type_for_model_and_features 调用，是后者做最终 shell 类型选择时的一块小拼图。它自己只调用 enabled 来问“某个功能有没有打开”。

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

fn unified_exec_feature_mode_for_features(features: &Features) -> UnifiedExecFeatureMode

作用：这个函数先只看功能开关，判断“统一执行”这条路在政策上能不能走，以及要不要走 zsh-fork 变体。它还特意防止一个组合开关偷偷启用底层功能。

数据流：进去的是 Features。函数先检查 ShellTool 和 UnifiedExec：只要 shell 工具没开，或统一执行没开，就输出 Disabled。然后看 ShellZshFork：如果 zsh-fork 打开，还必须 UnifiedExecZshFork 也打开，才输出 ZshFork；否则仍然 Disabled。如果没有 zsh-fork 这层需求，就输出 Direct。

调用关系：它被 shell_type_for_model_and_features 调用，负责先给出“功能政策层面”的统一执行选择。它自己只通过 enabled 查询功能开关，不处理平台、用户 shell、路径这些运行时信息。

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

fn shell_type_for_model_and_features(
    model_info: &ModelInfo,
    features: &Features,
) -> ConfigShellToolType

作用：这个函数决定最终给模型使用哪种 shell 工具类型。它把模型偏好、功能开关、后端选择和系统能力合在一起，避免选出一个当前机器不能用或配置不允许的方式。

数据流：进去的是 ModelInfo 里的模型 shell 偏好，以及 Features 功能开关。它先问 unified_exec_feature_mode_for_features：统一执行是否允许；再把模型声明里的 Default、Local 等情况折成普通 ShellCommand。如果 shell 命令后端是 zsh-fork，它也会把类型压回 ShellCommand。接着如果 ShellTool 没开，直接输出 Disabled。若统一执行被允许，还会检查 conpty_supported，也就是当前系统是否支持需要的伪终端能力；支持就输出 UnifiedExec，不支持就退回 ShellCommand。

调用关系：它是本文件里最核心的总判断器。它调用 shell_command_backend_for_features 和 unified_exec_feature_mode_for_features，把两个较小判断合成最终结果；也调用外部的 conpty_supported 来确认系统能力。其他配置流程需要知道“到底启用哪种 shell 工具”时，就应该依赖它。

调用图：调用 3 个内部函数（enabled, shell_command_backend_for_features, unified_exec_feature_mode_for_features）；外部调用 2 个（conpty_supported, matches!）。

fn for_session(
        feature_mode: UnifiedExecFeatureMode,
        user_shell_type: ToolUserShellType,
        shell_zsh_path: Option<&PathBuf>,
        main_execve_wrapper_exe: Option<&PathBuf>,

作用：这个函数为一次具体会话决定统一执行该直接运行，还是走 zsh-fork 特殊模式。它不只看功能开关，还要看系统是不是 Unix、用户是不是 zsh、相关程序路径是不是有效。

数据流：进去的是功能层面的 UnifiedExecFeatureMode、用户 shell 类型、zsh 路径、execve 包装程序路径。函数按条件逐个过关：必须是 Unix，功能模式必须是 ZshFork，用户 shell 必须是 Zsh，两个路径都必须存在，并且都能转成绝对路径。全部满足时，输出 UnifiedExecShellMode::ZshFork，并带上两个绝对路径；任一条件不满足，就输出 Direct。路径转换失败时会写警告日志，但仍然安全退回 Direct。

调用关系：它在会话创建阶段使用，调用图显示会被 spawn_review_thread 和 make_turn_context 调用，测试 unified_exec_shell_mode_uses_zsh_fork_only_when_all_inputs_match 也会验证它的边界行为。它会调用路径转换 try_from，并在条件满足时构造 ZshFork 配置。

调用图：调用 1 个内部函数（try_from）；被 3 处调用（spawn_review_thread, make_turn_context, unified_exec_shell_mode_uses_zsh_fork_only_when_all_inputs_match）；外部调用 3 个（ZshFork, cfg!, matches!）。

fn from_count(count: usize) -> Self

作用：这个函数把工具环境的数量翻译成更好理解的三种状态：没有、一个、多个。这样其他代码不用到处写数字判断。

数据流：进去的是一个数量 count。count 是 0 时输出 None；是 1 时输出 Single；大于 1 时输出 Multiple。它只做分类，不读取也不修改外部数据。

调用关系：它被 tool_environment_mode 调用，处在“把原始数量变成配置语义”的位置。可以把它理解成把人数 0、1、2+ 翻译成“没人、单人、多人”的小标签机。

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

fn has_environment(self) -> bool

作用：这个函数回答一个简单问题：当前有没有可用的工具环境。它把 None 当成没有，Single 和 Multiple 都当成有。

数据流：进去的是一个 ToolEnvironmentMode 值。函数检查它是不是 None：如果不是 None，输出 true；如果是 None，输出 false。它不改变这个值，也不影响外部状态。

调用关系：它是给其他代码做判断用的小帮手，避免每个调用者都重复写“不是 None 就算有环境”。它内部只用 matches! 这样的模式匹配工具来完成判断。

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

async fn validate_config_lock_if_configured(
    session_configuration: &SessionConfiguration,
) -> anyhow::Result<()>

作用：如果这次会话配置了“要按锁文件重放”，它就检查当前实际配置和锁文件是否一致。这样可以及时发现配置变了，避免用户以为自己在复现同一个环境，其实已经不是了。

数据流：进去的是一个 SessionConfiguration，也就是会话已经整理好的配置。它先跳过非根 agent，因为子 agent 不负责这件事；再看原始配置里有没有 config lock；有的话就把当前会话转成锁文件格式，再调用对比函数。出来是成功的空结果，或者带上下文信息的错误；它不改动会话本身。

调用关系：它通常在会话建立阶段被调用。它把“生成当前锁文件”的活交给 SessionConfiguration::to_config_lockfile_toml，再把“逐项比较”的活交给 validate_config_lock_replay。

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

async fn export_config_lock_if_configured(
    session_configuration: &SessionConfiguration,
    conversation_id: ThreadId,
) -> anyhow::Result<()>

作用：如果配置要求导出锁文件，它就把当前会话的配置锁写成一个 TOML 文件。TOML 是一种人能读的配置文件格式，类似带层级的键值表。

数据流：进去的是会话配置和会话编号 conversation_id。它读取导出目录；没有目录就什么也不做。有目录时，它把会话转成锁文件对象，再转成漂亮格式的 TOML 字符串，创建目录，最后写入名为“会话编号.config.lock.toml”的文件。出来是成功或文件创建、写入、序列化失败的错误。

调用关系：它在需要留档或调试复现时被调用。它依赖 SessionConfiguration::to_config_lockfile_toml 生成内容，再使用异步文件操作 create_dir_all 和 write 落盘。

调用图：外部调用 5 个（to_config_lockfile_toml, format!, create_dir_all, write, to_string_pretty）。

fn to_config_lockfile_toml(&self) -> anyhow::Result<ConfigLockfileToml>

作用：这是把一个会话配置变成完整锁文件对象的入口。别人不需要知道内部怎么清理、补全配置，只要调用它就能拿到可保存、可比较的锁文件结构。

数据流：进去的是当前 SessionConfiguration。它先调用 session_configuration_to_lock_config_toml 得到锁文件里的 config 部分，再用 config_lockfile 包上一层锁文件元信息，比如锁文件版本等。出来是 ConfigLockfileToml，失败时返回错误。

调用关系：validate_config_lock_if_configured 和 export_config_lock_if_configured 都会走到这里。它自己不做细活，而是把配置整理交给 session_configuration_to_lock_config_toml，把最后包装交给 config_lockfile。

调用图：调用 2 个内部函数（config_lockfile, session_configuration_to_lock_config_toml）。

fn session_configuration_to_lock_config_toml(
    sc: &SessionConfiguration,
) -> anyhow::Result<ConfigToml>

作用：这个函数负责把“会话实际运行用的配置”整理成锁文件里的 config 内容。它是锁文件内容是否靠谱的核心。

数据流：进去的是 SessionConfiguration。它先从已经合并好的配置层栈中取出有效配置，转成 ConfigToml；如果配置允许，还会补上会话初始化后才知道的模型、提示词、审批策略等；接着补上 Config 上已经解析、默认化或物化后的字段；最后删掉不适合写进锁文件的输入项。出来是一份干净、可重放的 ConfigToml。

调用关系：它只被 SessionConfiguration::to_config_lockfile_toml 调用。它像流水线总工，依次安排 save_session_resolved_fields、save_config_resolved_fields 和 drop_lockfile_inputs 完成补全与清理。

调用图：调用 3 个内部函数（drop_lockfile_inputs, save_config_resolved_fields, save_session_resolved_fields）；被 1 处调用（to_config_lockfile_toml）。

fn save_session_resolved_fields(sc: &SessionConfiguration, lock_config: &mut ConfigToml)

作用：它把会话创建过程中才确定下来的值写进锁配置，比如最终模型、提示词、服务等级和审批规则。没有它，锁文件可能只记录用户原始输入，却漏掉真正运行时的关键决定。

数据流：进去的是 SessionConfiguration 和一份可修改的 ConfigToml。它从会话里读取模型、推理强度、摘要设置、基础提示词、开发者提示词、压缩提示词、人格、审批策略等，然后填到 lock_config 对应字段里。出来没有新对象，但 lock_config 被补全了。

调用关系：它由 session_configuration_to_lock_config_toml 在允许保存模型目录解析字段时调用。它专门处理“会话层面才知道”的配置，和 save_config_resolved_fields 处理的 Config 层字段互补。

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

fn save_config_resolved_fields(
    config: &Config,
    lock_config: &mut ConfigToml,
) -> anyhow::Result<()>

作用：它把 Config 里已经解析好的最终值写进锁配置。重点是保存“程序实际按什么运行”，而不是只保存用户文件里最初写了什么。

数据流：进去的是 Config 和可修改的 ConfigToml。它写入网页搜索模式、模型供应商、计划模式推理强度、详细程度、是否加入权限说明、环境上下文、后台终端超时等；还把功能开关展开成明确状态，把 multi-agent v2 和 memories 通过 TOML 往返转换成锁文件能保存的形式；最后补上 agent 和 skills 的相关配置。出来是成功或转换失败；lock_config 会被大量补全。

调用关系：它由 session_configuration_to_lock_config_toml 调用，是锁文件“贴近真实运行行为”的关键步骤。遇到复杂配置对象时，它把转换工作交给 resolved_config_to_toml。

调用图：调用 1 个内部函数（resolved_config_to_toml）；被 1 处调用（session_configuration_to_lock_config_toml）；外部调用 1 个（Config）。

fn drop_lockfile_inputs(lock_config: &mut ConfigToml)

作用：它负责从锁配置里删掉不该进入锁文件的“输入来源”。这些东西会影响当时怎么得出配置，但不适合用来重放最终配置。

数据流：进去的是一份可修改的 ConfigToml。它清空 profile 和 profiles，清掉配置锁相关调试控制，移除模型提示文件、压缩提示文件、模型目录 JSON、沙箱模式、权限输入等字段。出来没有新对象，但 lock_config 变得更稳定、更适合重放。

调用关系：它由 session_configuration_to_lock_config_toml 在最后调用，像装箱前的清洁工。它还会调用 clear_config_lock_debug_controls，专门清理调试控制字段。

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

fn resolved_config_to_toml(
    value: &impl serde::Serialize,
    label: &'static str,
) -> anyhow::Result<Toml>

作用：这是一个小转换工具，用来把已经解析好的配置对象变成对应的 TOML 配置结构。它让复杂内部对象也能被锁文件保存。

数据流：进去的是一个能序列化的值和一个 label，label 用来说明出错时是哪块配置。它通过 toml_round_trip 先序列化再反序列化，相当于让数据走一遍 TOML 格式检查和转换。出来是目标 TOML 类型，或者转换错误。

调用关系：它被 save_config_resolved_fields 用来处理 multi_agent_v2 和 memories 这类嵌套配置。真正的转换细节交给 toml_round_trip。

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

async fn lock_contains_prompts_and_materializes_features()

作用：这个测试确认生成的锁文件确实包含会话里解析后的提示词和功能开关状态。它防止以后有人改代码时不小心漏掉这些关键运行信息。

数据流：进去的是测试创建出的会话配置。测试手动设置基础提示词、开发者提示词和压缩提示词，再生成锁文件，检查提示词、模型、profile 清理、memories、所有 feature 状态、multi_agent_v2 配置和锁文件版本是否符合预期。出来是测试通过，或断言失败指出哪里不一致。

调用关系：它通过 make_session_configuration_for_tests 准备假会话，再间接覆盖 SessionConfiguration::to_config_lockfile_toml 以及后面的补全、清理流程。

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

async fn lock_skips_session_values_when_model_catalog_fields_are_not_saved()

作用：这个测试确认当配置明确说“不保存模型目录解析出来的会话字段”时，锁文件不会偷偷写入这些字段。这样可以保证开关的含义是真的。

数据流：进去的是测试会话配置。测试把 config_lock_save_fields_resolved_from_model_catalog 设为 false，再设置一批会话字段；生成锁文件后，检查模型、推理强度、提示词、服务等级、人格和审批字段都还是空。出来是测试通过或断言失败。

调用关系：它验证 session_configuration_to_lock_config_toml 对 save_session_resolved_fields 的条件调用是否正确。准备数据同样依赖 make_session_configuration_for_tests。

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

async fn lock_validation_reports_config_diff()

作用：这个测试确认当实际配置和锁文件不一样时，校验会报出能看懂的差异信息。它关心的不只是失败，还关心失败原因是否有用。

数据流：进去的是一个测试会话生成的锁文件。测试复制一份锁文件并把 model 改成不同值，然后调用 validate_config_lock_replay；预期得到错误，并检查错误消息里包含“有效配置不匹配”和 model 字段。出来是测试通过或错误消息不符合预期。

调用关系：它直接测试 validate_config_lock_replay 的报错行为，同时用 make_session_configuration_for_tests 和 SessionConfiguration::to_config_lockfile_toml 准备对比材料。

调用图：调用 2 个内部函数（validate_config_lock_replay, make_session_configuration_for_tests）；外部调用 2 个（assert!, default）。

async fn lock_validation_ignores_removed_apps_mcp_path_override()

作用：这个测试确认一个已经废弃的旧配置项不会让锁文件校验误报失败。它保证旧锁文件在兼容范围内还能用。

数据流：进去的是测试会话生成的当前锁文件。测试把 expected 转成 TOML 值，手动塞入旧的 features.apps_mcp_path_override 字段，再转回 ConfigLockfileToml；然后拿它和当前锁文件校验，预期成功。出来是测试通过或校验错误。

调用关系：它直接调用 validate_config_lock_replay，验证配置锁回放校验里的兼容性规则。测试数据仍由 make_session_configuration_for_tests 生成。

调用图：调用 2 个内部函数（validate_config_lock_replay, make_session_configuration_for_tests）；外部调用 6 个（default, from_iter, Boolean, String, Table, try_from）。

async fn lock_validation_rejects_codex_version_mismatch_by_default()

作用：这个测试确认默认情况下，锁文件里的 Codex 版本和当前版本不一致会被拒绝。因为不同版本的程序可能用同一份配置跑出不同结果。

数据流：进去的是测试会话生成的 expected 和 actual 两份锁文件。测试把 expected 的 codex_version 改成旧版本，再调用 validate_config_lock_replay；预期失败，并检查错误信息提示版本不一致以及如何打开忽略开关。出来是测试通过或断言失败。

调用关系：它直接测试 validate_config_lock_replay 的版本保护规则。make_session_configuration_for_tests 负责提供基础会话配置。

调用图：调用 2 个内部函数（validate_config_lock_replay, make_session_configuration_for_tests）；外部调用 2 个（assert!, default）。

async fn lock_validation_can_ignore_codex_version_mismatch()

作用：这个测试确认如果用户明确允许忽略 Codex 版本差异，校验就不会因为版本号不同而失败。它验证的是那个“我知道风险，继续”的开关。

数据流：进去的是测试会话生成的两份锁文件，其中 expected 被改成旧版本。测试调用 validate_config_lock_replay，并传入 allow_codex_version_mismatch 为 true 的选项。出来预期是成功；如果仍然报错，测试失败。

调用关系：它补充测试 validate_config_lock_replay 的另一条路径：和上一个测试相反，这里版本不一致但选项允许通过。

调用图：调用 2 个内部函数（validate_config_lock_replay, make_session_configuration_for_tests）。

fn new_debug_config_output(
    config: &Config,
    session_network_proxy: Option<&SessionNetworkProxyRuntime>,
) -> PlainHistoryCell

作用：生成一块可以放进聊天历史里的 /debug-config 输出。有人想看当前配置和会话网络代理时，就会用它。

数据流：它接收当前配置和可选的会话网络代理信息 → 先让 render_debug_config_lines 把配置层和限制变成多行文字 → 如果有代理，再追加 HTTP_PROXY 和 ALL_PROXY 地址 → 最后包装成 PlainHistoryCell，交给界面显示。

调用关系：它由 add_debug_config_output 调用，是用户触发调试配置命令后的主要入口。它把大部分配置渲染工作交给 render_debug_config_lines，把代理地址选择交给 session_all_proxy_url，最后调用 PlainHistoryCell::new 生成界面需要的历史单元。

调用图：调用 3 个内部函数（render_debug_config_lines, session_all_proxy_url, new）；被 1 处调用（add_debug_config_output）；外部调用 1 个（format!）。

fn sandbox_mode_is_allowed_by_permissions(
    permissions: &Permissions,
    mode: SandboxModeRequirement,
) -> bool

作用：判断某个沙箱模式现在到底能不能用。沙箱模式可以理解成“程序被关在多严的安全笼子里”。

数据流：它接收权限设置和一个沙箱要求 → 把这个沙箱要求换成对应的权限档案，比如只读、工作区可写、完全不限制、外部沙箱 → 再问权限系统是否允许切到这个档案 → 返回 true 或 false。

调用关系：它是 render_debug_config_lines 的过滤依据之一，通过 new_debug_config_output 传进去。这样调试输出不会只照搬配置文件，而是显示当前权限真正允许的沙箱选项。

调用图：调用 3 个内部函数（can_set_permission_profile, read_only, workspace_write）。

fn session_all_proxy_url(http_addr: &str, socks_addr: &str, socks_enabled: bool) -> String

作用：决定 ALL_PROXY 这个代理环境变量该写 HTTP 地址还是 SOCKS 地址。SOCKS 是另一种代理协议，常用于更通用的网络转发。

数据流：它接收 HTTP 代理地址、SOCKS 代理地址，以及 SOCKS 是否启用 → 如果启用 SOCKS，就生成 socks5h:// 开头的地址 → 否则生成 http:// 开头的地址 → 返回这段字符串。

调用关系：它被 new_debug_config_output 调用，用来补齐会话运行时代理信息。两个单元测试分别确认启用和不启用 SOCKS 时输出正确。

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

fn render_debug_config_lines(
    stack: &ConfigLayerStack,
    sandbox_mode_is_effectively_allowed: impl Fn(SandboxModeRequirement) -> bool,
) -> Vec<Line<'static>>

作用：把配置栈和各种要求整理成终端界面可显示的一行行文字。这是本文件最核心的“排版员”。

数据流：它接收配置层栈，以及一个判断沙箱模式是否实际允许的小函数 → 先列出所有配置层，包含被禁用的层和禁用原因 → 再读取配置要求和原始要求文件内容 → 把审批策略、沙箱、联网、文件系统、托管钩子等要求逐项变成文字行 → 返回 Line 列表。

调用关系：它被 new_debug_config_output 用于真实界面输出，也被测试辅助函数 render_stack_to_text_with_sandbox_mode_filter 调用。它会把具体小活分给 render_non_file_layer_details、requirement_line、join_or_empty、normalize_allowed_web_search_modes、format_managed_hooks_requirements、format_network_constraints 等函数。

调用图：调用 10 个内部函数（get_layers, requirements, requirements_toml, format_managed_hooks_requirements, format_network_constraints, format_residency_requirement, join_or_empty, normalize_allowed_web_search_modes, render_non_file_layer_details, requirement_line）；被 2 处调用（new_debug_config_output, render_stack_to_text_with_sandbox_mode_filter）；外部调用 4 个（new, format_config_layer_source, format!, vec!）。

fn render_non_file_layer_details(layer: &ConfigLayerEntry) -> Vec<Line<'static>>

作用：为不是普通配置文件的配置层补充细节，比如启动参数层、企业托管层、MDM 管理层。

数据流：它接收一个配置层 → 看这个层的来源类型 → 如果是会话启动参数，就展开成键值对；如果是托管配置，就显示原始配置值；如果是普通系统、用户、项目文件，就不额外显示 → 返回若干显示行。

调用关系：它只在 render_debug_config_lines 列出每一层配置时被调用。它根据情况把工作交给 render_session_flag_details 或 render_non_file_layer_value。

调用图：调用 2 个内部函数（render_non_file_layer_value, render_session_flag_details）；被 1 处调用（render_debug_config_lines）；外部调用 1 个（new）。

fn render_session_flag_details(config: &TomlValue) -> Vec<Line<'static>>

作用：把启动时传入的配置参数展开成容易读的“键 = 值”列表。

数据流：它接收一段 TOML 配置值，TOML 是常见的配置文件格式 → 调用 flatten_toml_key_values 把嵌套结构压平成点号路径，比如 a.b.c → 如果没有内容就返回“none” → 否则返回每个键值对对应的一行文字。

调用关系：它由 render_non_file_layer_details 在遇到 SessionFlags 配置层时调用。它依赖 flatten_toml_key_values 做真正的展开。

调用图：调用 1 个内部函数（flatten_toml_key_values）；被 1 处调用（render_non_file_layer_details）；外部调用 2 个（new, vec!）。

fn format_managed_hooks_requirements(hooks: &ManagedHooksRequirementsToml) -> String

作用：把托管钩子要求压缩成一句摘要。钩子就是在某些操作前后自动运行的小脚本或处理器。

数据流：它接收托管钩子的配置 → 如果有托管目录或 Windows 托管目录，就写进摘要 → 再加上处理器数量 → 用 join_or_empty 拼成逗号分隔的字符串 → 返回给调试输出使用。

调用关系：它被 render_debug_config_lines 调用，用在 Requirements 里的 hooks 一项。它把复杂的钩子配置变成短句，避免调试页太长。

调用图：调用 1 个内部函数（join_or_empty）；被 1 处调用（render_debug_config_lines）；外部调用 2 个（new, format!）。

fn render_non_file_layer_value(layer: &ConfigLayerEntry) -> Vec<Line<'static>>

作用：显示托管配置层的实际内容，让人看到企业或 MDM 下发了什么。

数据流：它接收一个配置层 → 先决定显示标签，比如“MDM value”或“Enterprise-managed config value” → 优先取原始 TOML 文本，没有的话就把已解析的配置值转成字符串 → 如果为空显示 empty，如果有多行就缩进成多行 → 返回显示行。

调用关系：它由 render_non_file_layer_details 调用，专门处理 MDM、企业托管这类不是普通文件路径的配置层。标签由 non_file_layer_value_label 提供。

调用图：调用 2 个内部函数（raw_toml, non_file_layer_value_label）；被 1 处调用（render_non_file_layer_details）；外部调用 1 个（vec!）。

fn non_file_layer_value_label(source: &ConfigLayerSource) -> &'static str

作用：给非文件配置层选择一个人能看懂的标题。

数据流：它接收配置来源类型 → 如果是 MDM，就返回“MDM value” → 如果是企业托管，就返回“Enterprise-managed config value” → 其他情况返回通用的“Layer value”。

调用关系：它被 render_non_file_layer_value 调用，只负责取标签，不处理具体配置内容。

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

fn flatten_toml_key_values(
    value: &TomlValue,
    prefix: Option<&str>,
    out: &mut Vec<(String, String)>,
)

作用：把嵌套的 TOML 配置摊平成一串键值对，方便在终端里逐行展示。

数据流：它接收一个 TOML 值、当前路径前缀、输出列表 → 如果当前值是表，就按键名排序后递归进入每个子项 → 如果是普通值，就把完整路径和格式化后的值加入输出列表 → 最终改动传入的列表。

调用关系：它由 render_session_flag_details 调用，是展开 session flags 的底层工具。它用 format_toml_value 把具体值转成文字。

调用图：调用 1 个内部函数（format_toml_value）；被 1 处调用（render_session_flag_details）；外部调用 1 个（format!）。

fn format_toml_value(value: &TomlValue) -> String

作用：把一个 TOML 值转成字符串，供调试输出显示。

数据流：它接收 TOML 值 → 调用该值自己的 to_string 能力 → 返回字符串。

调用关系：它被 flatten_toml_key_values 使用。这个函数很小，但让值格式化的入口集中在一个地方。

调用图：被 1 处调用（flatten_toml_key_values）；外部调用 1 个（to_string）。

fn requirement_line(
    name: &str,
    value: String,
    source: Option<&RequirementSource>,
) -> Line<'static>

作用：把一条配置要求做成统一格式的显示行，并附上来源。

数据流：它接收要求名称、要求值、可选来源 → 如果来源不存在，就写成“unspecified” → 拼成“名称: 值 (source: 来源)” → 返回一行终端文字。

调用关系：它被 render_debug_config_lines 反复调用，用来保证 Requirements 区域的每一项格式一致。

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

fn join_or_empty(values: Vec<String>) -> String

作用：把多个字符串用逗号连起来；如果一个都没有，就明确写成“empty”。

数据流：它接收字符串列表 → 如果列表为空，返回“<empty>” → 否则把所有字符串用“, ”连接 → 返回结果。

调用关系：它被 render_debug_config_lines、format_managed_hooks_requirements、format_network_constraints 使用。它避免空列表在调试输出里看起来像漏显示。

调用图：被 3 处调用（format_managed_hooks_requirements, format_network_constraints, render_debug_config_lines）。

fn normalize_allowed_web_search_modes(
    modes: &[WebSearchModeRequirement],
) -> Vec<WebSearchModeRequirement>

作用：整理允许的网页搜索模式列表，保证“disabled（关闭搜索）”这个选项被合理表达。

数据流：它接收网页搜索模式数组 → 如果数组本来为空，就返回只包含 Disabled 的列表 → 如果不为空但没有 Disabled，就补上 Disabled → 返回整理后的列表。

调用关系：它被 render_debug_config_lines 调用，用于 Requirements 里的 allowed_web_search_modes。这样输出会体现：即使允许某些搜索模式，关闭搜索通常也是一个可选状态。

调用图：被 1 处调用（render_debug_config_lines）；外部调用 3 个（is_empty, to_vec, vec!）。

fn format_sandbox_mode_requirement(mode: SandboxModeRequirement) -> String

作用：把沙箱模式枚举值转成配置里常见的短横线文本，比如 read-only。

数据流：它接收一个沙箱模式 → 按类型匹配成对应字符串 → 返回这个字符串。

调用关系：它作为 render_debug_config_lines 格式化沙箱要求时的小工具使用，让内部类型名变成人能读的配置名。

fn format_residency_requirement(requirement: ResidencyRequirement) -> String

作用：把数据驻留要求转成显示文字。数据驻留指数据必须留在哪个地区。

数据流：它接收一个驻留要求 → 目前只有美国 Us 这一种 → 返回“us”。

调用关系：它被 render_debug_config_lines 调用，用来显示 enforce_residency 这一项。

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

fn format_network_constraints(network: &NetworkConstraints) -> String

作用：把网络限制整理成一句摘要，说明代理端口、域名权限、本地绑定等网络规则。

数据流：它接收 NetworkConstraints → 逐个检查里面哪些字段有值 → 有值的字段就写成 key=value，例如 enabled=true、http_port=3128、domains={example.com=allow} → 最后用 join_or_empty 拼成一串 → 返回摘要字符串。

调用关系：它被 render_debug_config_lines 调用，用于 Requirements 里的 experimental_network。它会借助网络权限条目格式化函数把域名和 Unix socket 规则写清楚。

调用图：调用 1 个内部函数（join_or_empty）；被 1 处调用（render_debug_config_lines）；外部调用 2 个（new, format!）。

fn format_network_permission_entries(
    entries: &std::collections::BTreeMap<String, T>,
    format_value: impl Fn(T) -> &'static str,
) -> String

作用：把一组网络许可规则变成花括号里的列表，比如 {example.com=allow}。

数据流：它接收一个按名称排序的映射表，以及一个把权限值转成文字的小函数 → 逐项生成“名称=权限” → 用逗号连接并包上花括号 → 返回字符串。

调用关系：它是 format_network_constraints 这类网络摘要逻辑的通用小帮手，可配合 format_network_domain_permission 或 format_network_unix_socket_permission 使用。

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

fn format_network_domain_permission(permission: NetworkDomainPermissionToml) -> &'static str

作用：把域名访问权限转成文字：允许就是 allow，拒绝就是 deny。

数据流：它接收一个域名权限枚举 → 如果是 Allow 返回“allow” → 如果是 Deny 返回“deny”。

调用关系：它用于网络权限条目的显示，通常配合 format_network_permission_entries 把域名规则写进 format_network_constraints 的输出。

fn format_network_unix_socket_permission(
    permission: NetworkUnixSocketPermissionToml,
) -> &'static str

作用：把 Unix socket 的访问权限转成文字。Unix socket 可以理解成同一台机器上程序之间通信的本地接口。

数据流：它接收一个 Unix socket 权限枚举 → 如果是 Allow 返回“allow” → 如果是 Deny 返回“deny”。

调用关系：它用于网络权限条目的显示，通常配合 format_network_permission_entries 把 socket 规则写进 format_network_constraints 的输出。

fn empty_toml_table() -> TomlValue

作用：给测试快速造一个空的 TOML 表。

数据流：它不接收输入 → 创建一个空的 TOML map → 包成 TomlValue::Table 返回。

调用关系：多个测试用它来构造“有配置层但内容为空”的场景，避免每个测试重复写创建空表的代码。

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

fn absolute_path(path: &str) -> AbsolutePathBuf

作用：给测试把字符串变成项目要求的绝对路径类型。

数据流：它接收路径字符串 → 调用 from_absolute_path 检查并转换 → 如果不是绝对路径测试就失败 → 返回 AbsolutePathBuf。

调用关系：它被涉及系统文件、用户文件、项目目录、托管目录的测试调用，用来生成合法路径。

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

fn render_to_text(lines: &[Line<'static>]) -> String

作用：把终端界面用的 Line 列表转成普通字符串，方便测试用 contains 检查。

数据流：它接收多行 Line → 逐行取出里面所有 span 的文字内容 → 拼成每一行文本 → 再用换行符连接 → 返回普通字符串。

调用关系：它是测试辅助工具，被 render_stack_to_text_with_sandbox_mode_filter 间接使用，让测试不用关心颜色、加粗等终端样式。

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

fn render_stack_to_text(stack: &ConfigLayerStack) -> String

作用：用最简单的方式把配置栈渲染成纯文本，默认不额外过滤沙箱模式。

数据流：它接收配置栈 → 调用 render_stack_to_text_with_sandbox_mode_filter，并传入永远返回 true 的过滤函数 → 返回渲染后的文本。

调用关系：大多数测试通过它检查 render_debug_config_lines 的输出。需要特殊沙箱过滤时，测试会直接用 render_stack_to_text_with_sandbox_mode_filter。

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

fn render_stack_to_text_with_sandbox_mode_filter(
        stack: &ConfigLayerStack,
        sandbox_mode_is_effectively_allowed: impl Fn(SandboxModeRequirement) -> bool,
    ) -> String

作用：测试专用：带自定义沙箱过滤规则地渲染配置栈。

数据流：它接收配置栈和一个判断沙箱模式是否允许的函数 → 调用 render_debug_config_lines 得到界面行 → 再用 render_to_text 转成普通文本 → 返回字符串。

调用关系：它连接被测的 render_debug_config_lines 和测试断言。debug_config_output_filters_sandbox_modes_blocked_by_deny_read_requirements 会用它模拟部分沙箱被禁用的情况。

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

fn debug_config_output_lists_all_layers_including_disabled()

作用：确认调试输出会列出所有配置层，包括被禁用的层。

数据流：它构造一个启用的系统层和一个禁用的项目层 → 渲染成文本 → 检查文本包含 enabled、disabled、禁用原因和空 Requirements 提示。

调用关系：这是 render_debug_config_lines 的基础行为测试，确保排查配置时不会把禁用层隐藏掉。

调用图：调用 1 个内部函数（new）；外部调用 7 个（default, assert!, cfg!, default, absolute_path, render_stack_to_text, vec!）。

fn debug_config_output_lists_requirement_sources()

作用：确认各种配置要求都会显示它们来自哪里。

数据流：它构造一大组要求，比如审批策略、沙箱、网页搜索、MCP 服务器、网络限制、文件禁止读取等 → 渲染配置栈 → 检查每一项值和 source 来源文字都出现在输出里。

调用关系：它覆盖 render_debug_config_lines 中 Requirements 区域的大部分分支，也通过快照测试固定非 Windows 平台上的整体输出格式。

调用图：调用 5 个内部函数（new, new, allow_any, new, read_only）；外部调用 9 个（from, default, default, assert!, cfg!, assert_snapshot!, absolute_path, render_stack_to_text, vec!）。

fn debug_config_output_filters_sandbox_modes_blocked_by_deny_read_requirements()

作用：确认调试输出里的沙箱模式会按真实权限过滤，而不是盲目显示配置文件写了什么。

数据流：它构造允许多种沙箱模式的要求，又构造一个只允许只读和工作区可写的权限对象 → 渲染时传入 sandbox_mode_is_allowed_by_permissions 作为过滤器 → 检查危险全权限和外部沙箱没有显示。

调用关系：它验证 sandbox_mode_is_allowed_by_permissions 与 render_debug_config_lines 的配合，防止调试页误导用户。

调用图：调用 7 个内部函数（new, new, allow_any, new, new, from_approval_and_profile, read_only）；外部调用 9 个（new, default, assert!, cfg!, default, assert_snapshot!, absolute_path, render_stack_to_text_with_sandbox_mode_filter, vec!）。

fn debug_config_output_lists_approvals_reviewer_as_requirement()

作用：确认 approvals reviewer（审批复核者）也会作为要求显示出来。

数据流：它构造一个允许 auto_review 的复核者要求 → 渲染配置栈 → 检查输出包含对应文字，并且 Requirements 不再显示 none。

调用关系：它专门覆盖 render_debug_config_lines 里 allowed_approvals_reviewers 这一项，防止以后改代码时漏掉。

调用图：调用 3 个内部函数（new, allow_any, new）；外部调用 6 个（new, default, assert!, default, render_stack_to_text, vec!）。

fn debug_config_output_formats_unix_socket_permissions()

作用：确认 Unix socket 的允许和拒绝规则能正确显示。

数据流：它构造两个 socket 路径，一个 allow、一个 deny → 渲染配置栈 → 检查 experimental_network 行里包含按路径排序后的 socket 权限摘要。

调用关系：它验证 format_network_constraints 以及 Unix socket 权限格式化相关逻辑。

调用图：调用 2 个内部函数（new, new）；外部调用 7 个（from, default, new, default, assert!, default, render_stack_to_text）。

fn debug_config_output_lists_session_flag_key_value_pairs()

作用：确认会话启动参数会被展开成清楚的键值对。

数据流：它从一段 TOML 文本解析出 session flags → 放进 SessionFlags 配置层 → 渲染后检查 model、嵌套 network_access、writable_roots 等内容都出现。

调用关系：它覆盖 render_session_flag_details 和 flatten_toml_key_values，确保嵌套配置不会只显示成一坨难读的结构。

调用图：调用 1 个内部函数（new）；外部调用 5 个（default, assert!, default, render_stack_to_text, vec!）。

fn debug_config_output_shows_legacy_mdm_layer_value()

作用：确认旧版 MDM 管理配置的原始内容会显示出来。

数据流：它构造一段带注释的 managed_config.toml 原文 → 放入 LegacyManagedConfigTomlFromMdm 配置层 → 渲染后检查标题是 MDM value，并且注释和配置项都保留。

调用关系：它验证 render_non_file_layer_value 对 MDM 层优先显示 raw_toml 的行为。

调用图：调用 1 个内部函数（new）；外部调用 7 个（default, assert!, cfg!, default, absolute_path, render_stack_to_text, vec!）。

fn debug_config_output_shows_enterprise_managed_layer_value()

作用：确认企业托管配置会用企业托管的标题显示，而不是误标成 MDM。

数据流：它构造一段企业云端下发的 TOML 原文 → 放入 EnterpriseManaged 配置层 → 渲染后检查显示 enterprise-managed 信息和 Enterprise-managed config value 标题，并确认没有 MDM value。

调用关系：它覆盖 non_file_layer_value_label 和 render_non_file_layer_value 中企业托管配置的分支。

调用图：调用 1 个内部函数（new）；外部调用 7 个（default, assert!, cfg!, default, absolute_path, render_stack_to_text, vec!）。

fn debug_config_output_normalizes_empty_web_search_mode_list()

作用：确认网页搜索模式列表为空时，会显示为 disabled，而不是空白或漏掉。

数据流：它构造一个 allowed_web_search_modes 为空数组的要求 → 渲染配置栈 → 检查输出写着 disabled，并带有正确来源。

调用关系：它验证 normalize_allowed_web_search_modes 被 render_debug_config_lines 正确使用。

调用图：调用 3 个内部函数（new, allow_any, new）；外部调用 4 个（new, default, assert!, render_stack_to_text）。

fn debug_config_output_lists_managed_hooks_requirement()

作用：确认托管钩子要求能显示摘要，尤其是处理器数量。

数据流：它构造一个托管钩子配置，里面有目录和一个命令处理器 → 渲染配置栈 → 检查输出包含 hooks、handlers=1 和来源。

调用关系：它覆盖 format_managed_hooks_requirements 和 render_debug_config_lines 的 hooks 显示逻辑。

调用图：调用 3 个内部函数（new, allow_any, new）；外部调用 9 个（default, new, default, assert!, cfg!, default, from, render_stack_to_text, vec!）。

fn session_all_proxy_url_uses_socks_when_enabled()

作用：确认 SOCKS 代理启用时，ALL_PROXY 使用 socks5h 地址。

数据流：它传入 HTTP 地址、SOCKS 地址和 socks_enabled=true → 调用 session_all_proxy_url → 检查返回值是 socks5h:// 加 SOCKS 地址。

调用关系：它直接测试 session_all_proxy_url 的一个分支，保证 new_debug_config_output 显示代理时不会选错协议。

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

fn session_all_proxy_url_uses_http_when_socks_disabled()

作用：确认 SOCKS 代理没启用时，ALL_PROXY 使用 HTTP 地址。

数据流：它传入 HTTP 地址、SOCKS 地址和 socks_enabled=false → 调用 session_all_proxy_url → 检查返回值是 http:// 加 HTTP 地址。

调用关系：它直接测试 session_all_proxy_url 的另一个分支，和 SOCKS 启用测试一起覆盖代理选择逻辑。

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

fn is_empty(&self) -> bool

作用：检查整份权限配置里有没有任何 profile。外部代码可以用它快速判断“用户是不是根本没写权限配置”。

数据流：进去的是一个 PermissionsToml 对象 → 它只看里面的 entries 这张表是不是空 → 出来一个 true 或 false，不改动任何数据。

调用关系：它是一个很轻的小检查工具，通常会在加载配置后被调用，用来决定后面还要不要继续解析权限 profile。

fn resolve_profile(
        &self,
        profile_name: &str,
        mut parent_profile: F,
    ) -> Result<PermissionProfileToml, PermissionProfileResolutionError>

作用：把一个指定名字的权限 profile，以及它一路继承的父 profile，合成一份最终配置。这样使用者只需要拿到“最后结果”，不用自己处理继承关系。

数据流：进去的是 profile 名字，以及一个可选的父级查找函数 → 它从当前配置和外部父配置里逐层找 profile，检查有没有找不到、继承内置但不支持、或者循环继承 → 然后从最老的父配置开始一层层合并，出来一份 PermissionProfileToml；如果有问题就出来明确的错误。

调用关系：它会被 resolve_permission_profile 调用，是权限 profile 继承链的核心入口。内部在最终合并阶段把具体合并工作交给 merge_permission_profiles；它还用到标准库的 once 来拼出循环继承的错误路径。

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

fn merge_permission_profiles(
    mut parent: PermissionProfileToml,
    mut child: PermissionProfileToml,
) -> Result<PermissionProfileToml, PermissionProfileResolutionError>

作用：把父 profile 和子 profile 合成一个 profile，并保证子 profile 的设置覆盖父 profile。它解决的是“继承后到底谁说了算”的问题。

数据流：进去的是父配置和子配置 → 它先去掉父配置的 description 和 extends，避免父级说明文字污染当前 profile；如果双方都有网络域名规则，就先规范化域名写法 → 再把两份结构转成 TOML 值，用通用合并函数叠在一起 → 最后转回 PermissionProfileToml，成功返回合并结果，失败返回序列化或反序列化错误。

调用关系：它由 PermissionsToml::resolve_profile 在整理继承链时调用。真正的“两个 TOML 值怎么覆盖”交给 merge_toml_values；域名统一写法交给 normalize_profile_network_domains。

调用图：调用 2 个内部函数（merge_toml_values, normalize_profile_network_domains）；外部调用 1 个（try_from）。

fn normalize_profile_network_domains(profile: &mut PermissionProfileToml)

作用：把 profile 里的网络域名规则统一成标准写法。这样 example.com、大小写不同的域名之类不会被当成完全不同的规则。

数据流：进去的是一份可修改的 PermissionProfileToml → 它找到 network.domains 里的每个域名模式，用 normalize_host 规范化键名 → 再把整理后的表放回去；如果没有域名规则，就什么也不做。

调用关系：它只在 merge_permission_profiles 发现父子双方都写了域名规则时使用。它像合并前的“整理名单”，避免后续覆盖规则因为写法不同而失效。

调用图：被 1 处调用（merge_permission_profiles）；外部调用 1 个（take）。

fn enabled_roots(&self) -> impl Iterator<Item = &String>

作用：列出被启用的工作目录根路径。配置里可以写某个目录 true 或 false，这个函数只挑出 true 的那些。

数据流：进去的是 workspace_roots 这张路径到开关的表 → 它逐个查看布尔值 → 出来一个迭代器，里面只有启用状态为 true 的路径引用；不改原始配置。

调用关系：它通常在把配置转换成实际工作区权限时使用，给后续代码一份“真正允许作为工作区根目录”的清单。

fn is_empty(&self) -> bool

作用：检查文件系统权限表是不是没有任何规则。它让调用者能快速判断有没有必要继续处理文件权限。

数据流：进去的是 FilesystemPermissionsToml → 它查看 entries 是否为空 → 返回 true 或 false，不读取具体每条权限，也不改数据。

调用关系：它是文件权限配置的小辅助函数，常用于配置加载或合并后做快速判断。

fn is_empty(&self) -> bool

作用：检查网络域名权限表是不是空的。也就是用户有没有写“允许或禁止访问哪些域名”。

数据流：进去的是 NetworkDomainPermissionsToml → 它查看 entries 表里有没有项目 → 返回 true 或 false，不修改配置。

调用关系：它服务于网络权限配置处理流程，帮助上层代码决定是否需要应用域名限制。

fn allowed_domains(&self) -> Option<Vec<String>>

作用：从域名权限表里挑出所有明确允许访问的域名模式。它给需要白名单的地方提供一份简单列表。

数据流：进去的是域名到 allow/deny 的表 → 它过滤出权限为 Allow 的项，并复制这些域名模式 → 如果有结果就返回 Some(Vec<String>)，没有允许项就返回 None。

调用关系：它是把配置拆成更直接清单的辅助函数，常给网络限制或展示逻辑使用。

fn denied_domains(&self) -> Option<Vec<String>>

作用：从域名权限表里挑出所有明确禁止访问的域名模式。它给需要黑名单的地方提供一份简单列表。

数据流：进去的是域名到 allow/deny 的表 → 它过滤出权限为 Deny 的项，并复制这些域名模式 → 如果有结果就返回 Some(Vec<String>)，没有禁止项就返回 None。

调用关系：它和 allowed_domains 是一对，一个整理允许名单，一个整理禁止名单，方便后续网络策略使用。

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

作用：把域名权限值显示成普通文字，比如 allow 或 deny。这样错误信息、日志、界面展示时能看懂。

数据流：进去的是 Allow 或 Deny 这个枚举值，以及一个格式化输出器 → 它选择对应的小写字符串 → 写入输出器，返回格式化是否成功。

调用关系：它实现的是 Rust 的 Display 显示接口。别人用字符串格式化这个权限值时，会自动走到这里，并把写字符串的动作交给 write_str。

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

fn is_empty(&self) -> bool

作用：检查 Unix socket 权限表是不是空的。Unix socket 可以理解成本机程序之间通信的一种特殊文件通道。

数据流：进去的是 NetworkUnixSocketPermissionsToml → 它查看 entries 里有没有路径规则 → 返回 true 或 false，不改变原数据。

调用关系：它是网络本地通道权限处理里的快速判断工具，上层代码可以据此跳过不必要的转换。

fn allow_unix_sockets(&self) -> Vec<String>

作用：列出所有明确允许连接的 Unix socket 路径。这样运行时代理可以知道哪些本机通信通道能放行。

数据流：进去的是路径到 allow/deny 的表 → 它只保留权限为 Allow 的路径，并复制成字符串列表 → 出来一个 Vec<String>，不修改原表。

调用关系：它服务于网络权限转换流程，把 TOML 里带权限标记的表变成更容易消费的允许列表。

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

作用：把 Unix socket 权限值显示成 allow 或 deny。这样日志和错误信息不会打印成难懂的内部名字。

数据流：进去的是 Allow 或 Deny，以及格式化输出器 → 它选出对应的小写文字 → 写入输出器并返回结果。

调用关系：它实现 Rust 的 Display 显示接口。任何地方格式化这个权限枚举时，都会自动使用它；实际写入文字交给 write_str。

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

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

作用：读取 network.mitm 这段 TOML 配置，并在读完后立刻做基础检查。MITM 在这里指代理“夹在中间”查看或改写请求的机制。

数据流：进去的是 serde 反序列化器，也就是正在读配置的工具 → 它先读成一个未检查的临时结构 → 再组成 NetworkMitmToml，并调用 validate_action_definitions 检查动作和 hook 是否基本有效 → 成功就返回配置对象，失败就把错误交给 serde 报出去。

调用关系：它是 NetworkMitmToml 的自定义读取入口。配置文件被解析到 network.mitm 时会自动调用它，确保坏配置不会悄悄进入后续运行流程。

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

fn validate_action_definitions(&self) -> Result<(), String>

作用：检查网络拦截配置里的动作定义是不是空的，以及 hook 有没有指定动作。没有这些检查，配置可能看似存在但实际什么也不会做。

数据流：进去的是 NetworkMitmToml → 它先看每个 action 是否至少包含一个操作，比如删请求头或注入请求头；再看每个 hook 的 action 列表是否为空 → 如果发现问题，返回带具体路径的错误文字；都正常就返回 Ok。

调用关系：它会在 NetworkMitmToml::deserialize 读配置时使用，也会被 validate_action_references 先调用，作为更深入引用检查前的第一道门。

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

fn validate_action_references(
        &self,
        actions_by_name: &IndexMap<String, NetworkMitmActionToml>,
    ) -> Result<(), String>

作用：检查每个 hook 引用的动作名字是不是真的存在。它防止配置里写了一个动作名，但实际没有定义，导致拦截规则运行时缺胳膊少腿。

数据流：进去的是当前 MITM 配置，以及一张按名字保存的动作表 → 它先调用 validate_action_definitions 做基础检查 → 再逐个 hook、逐个 action 名检查动作表里是否有这个名字 → 找不到就返回清楚的错误，全部存在就返回 Ok。

调用关系：它建立在 validate_action_definitions 之上，属于配置最终校验的一步。它用 contains_key 查动作表，确保 hook 和 action 两个零件能接上。

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

fn to_runtime_hooks(
        &self,
        actions_by_name: Option<&IndexMap<String, NetworkMitmActionToml>>,
    ) -> Vec<MitmHookConfig>

作用：把 TOML 里的网络拦截 hook 转成代理运行时能直接使用的 hook 配置。也就是把“配置文件文字”变成“程序执行规则”。

数据流：进去的是 NetworkMitmToml，以及可选的动作定义表 → 它遍历 hooks，把每个 hook 交给 NetworkMitmHookToml::to_runtime 转换 → 返回 MitmHookConfig 列表；如果没有 hooks，就返回空列表。

调用关系：它在 NetworkToml::apply_to_network_proxy_config 应用网络配置时被调用。它是 MITM 配置进入网络代理运行时之前的转换桥梁。

fn is_empty(&self) -> bool

作用：判断一个 MITM 动作是不是完全没操作。空动作没有意义，所以校验时需要抓出来。

数据流：进去的是一个 NetworkMitmActionToml → 它检查 strip_request_headers 和 inject_request_headers 两个列表是否都为空 → 返回 true 或 false，不改配置。

调用关系：它被 validate_action_definitions 用来判断 action 是否有效。它像检查菜单上某道菜是不是没有任何配料。

fn apply_to_network_proxy_config(&self, config: &mut NetworkProxyConfig)

作用：把用户写在 TOML 里的网络配置覆盖到真正的网络代理配置上。它让“配置文件里的选择”真正影响程序联网行为。

数据流：进去的是 NetworkToml，以及一个可修改的 NetworkProxyConfig → 它逐项检查配置是否填写：开关、代理地址、SOCKS5、网络模式、域名规则、Unix socket、本地绑定、MITM hook 等；填了就覆盖运行时配置，没填就保留原值 → 最后还会根据网络模式或 hook 是否存在，决定是否启用 MITM。

调用关系：它被 to_network_proxy_config 用来从零生成配置，也会被 apply_network 在更大的配置应用流程里调用。域名规则的叠加交给 overlay_network_domain_permissions，MITM hook 的转换交给 NetworkMitmToml::to_runtime_hooks。

调用图：调用 1 个内部函数（overlay_network_domain_permissions）；被 2 处调用（to_network_proxy_config, apply_network）。

fn to_network_proxy_config(&self) -> NetworkProxyConfig

作用：从一份 NetworkToml 直接生成完整的 NetworkProxyConfig。调用者不需要先手动创建默认配置再应用。

数据流：进去的是 NetworkToml → 它先创建一个默认的 NetworkProxyConfig → 再调用 apply_to_network_proxy_config 把 TOML 里的设置盖上去 → 返回最终的运行时网络代理配置。

调用关系：它是一个方便入口，内部真正干活的是 apply_to_network_proxy_config。适合只需要把单份网络配置变成运行时配置的场景。

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

fn to_runtime(
        &self,
        actions_by_name: Option<&IndexMap<String, NetworkMitmActionToml>>,
    ) -> MitmHookConfig

作用：把单个 MITM hook 从 TOML 形式转换成运行时 hook。hook 可以理解成“当请求符合这些条件时，就执行某些动作”的规则。

数据流：进去的是一个 hook 配置，以及可选的动作表 → 它复制 host、请求方法、路径前缀、查询参数、请求头、请求体匹配规则 → 再调用 selected_actions 找出要执行的动作 → 出来一个 MitmHookConfig。

调用关系：它由 NetworkMitmToml::to_runtime_hooks 对每个 hook 调用。它自己不展开动作细节，而是把动作挑选和合并交给 selected_actions。

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

fn selected_actions(
        &self,
        actions_by_name: Option<&IndexMap<String, NetworkMitmActionToml>>,
    ) -> MitmHookActionsConfig

作用：根据 hook 里写的动作名字，收集这些动作真正要做的事，比如删除请求头或注入请求头。它把多个命名动作合并成一份执行清单。

数据流：进去的是 hook 自己的 action 名字列表，以及可选的动作表 → 如果没有动作表，就返回空动作配置 → 如果有，就按名字查找每个动作，把要删除的请求头追加进去，把要注入的请求头转换成运行时格式后追加进去 → 返回合并后的 MitmHookActionsConfig。

调用关系：它只由 NetworkMitmHookToml::to_runtime 调用，是 hook 转运行时配置时的动作装配步骤。注入请求头的单项转换由 NetworkMitmInjectedHeaderToml::to_runtime 完成。

调用图：被 1 处调用（to_runtime）；外部调用 1 个（default）。

fn to_runtime(&self) -> InjectedHeaderConfig

作用：把 TOML 里“要注入的请求头”转换成代理运行时使用的格式。注入请求头通常用于给特定请求自动加认证信息或其他隐藏值。

数据流：进去的是请求头配置，包括名字、从哪个环境变量或文件取秘密值、可选前缀 → 它逐项复制这些字段 → 出来一个 InjectedHeaderConfig，不读取秘密本身，也不改原配置。

调用关系：它在 NetworkMitmHookToml::selected_actions 合并动作时被调用。它只负责单个请求头配置的形状转换，不负责判断什么时候注入。

fn overlay_network_domain_permissions(
    config: &mut NetworkProxyConfig,
    domains: &NetworkDomainPermissionsToml,
)

作用：把 TOML 里的域名允许/禁止规则叠加到网络代理配置上。它解决的是“新配置要覆盖或补充已有域名规则”的问题。

数据流：进去的是可修改的 NetworkProxyConfig，以及 NetworkDomainPermissionsToml → 它遍历每个域名模式，把 Allow/Deny 转成代理模块认识的权限类型 → 再调用网络配置里的 upsert_domain_permission 写入或更新规则，同时用 normalize_host 统一域名写法 → 最终改变传入的代理配置。

调用关系：它被 NetworkToml::apply_to_network_proxy_config 调用，也会被 apply_network_constraints 使用。它是域名权限从配置层进入网络代理层的关键连接点。

调用图：被 2 处调用（apply_to_network_proxy_config, apply_network_constraints）。

fn default_builtin_permission_profile_name(
    active_project: &ProjectConfig,
    windows_sandbox_level: WindowsSandboxLevel,
) -> &'static str

作用：根据当前项目是否可信，以及 Windows 沙箱是否可用，选一个默认的内置权限方案。它的作用是让新项目在没有明确配置时也有一个安全、合理的起点。

数据流：输入当前项目状态和 Windows 沙箱级别 → 查看项目是不是可信或不可信，并避开 Windows 沙箱被关闭的特殊情况 → 输出内置方案名，通常是“工作区可写”，否则是“只读”。

调用关系：它是权限选择的前置判断之一，会调用项目配置里的 is_trusted 和 is_untrusted 来看项目状态；后续真正生成权限规则时，会用这里选出的名字进入内置或自定义方案流程。

调用图：调用 2 个内部函数（is_trusted, is_untrusted）；外部调用 1 个（cfg!）。

fn is_builtin_permission_profile_name(profile_name: &str) -> bool

作用：判断一个权限方案名字是不是 Codex 自带的那几个固定名字。这样程序能区分“系统内置方案”和“用户自己写的方案”。

数据流：输入一个方案名字符串 → 和只读、工作区、完全访问这三个内置名字比较 → 输出 true 或 false。

调用关系：它会被 network_proxy_config_for_profile_selection 和 compile_permission_profile_workspace_roots 使用；这两个流程先靠它判断是否可以直接走内置规则，还是必须去读取用户配置。

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

fn builtin_permission_profile(
    profile_name: &str,
    workspace_write: Option<&SandboxWorkspaceWrite>,
) -> Option<PermissionProfile>

作用：把内置权限方案名直接变成运行时能用的权限对象。有人选择内置方案时，就不用再去配置文件里查详细规则。

数据流：输入方案名和可选的工作区写入设置 → 如果是只读就生成只读权限；如果是工作区方案，就按是否允许网络、是否排除临时目录等设置生成规则；如果是完全访问就关闭沙箱限制 → 输出一个权限对象，或在名字不认识时输出空。

调用关系：它会被 compile_permission_profile_selection 调用来优先处理内置方案，也会被配置加载流程 load_config_with_layer_stack 直接使用；内部把具体创建工作交给 PermissionProfile 的 read_only、workspace_write 和 workspace_write_with。

调用图：调用 3 个内部函数（read_only, workspace_write, workspace_write_with）；被 2 处调用（load_config_with_layer_stack, compile_permission_profile_selection）。

fn validate_user_permission_profile_names(
    permissions: Option<&PermissionsToml>,
) -> io::Result<()>

作用：检查用户自定义权限方案名有没有占用系统保留前缀。冒号开头的名字留给内置特殊含义，用户不能拿来当普通方案名。

数据流：输入可选的权限配置表 → 如果没有配置就直接通过；如果有，就逐个看方案名是否以冒号开头 → 没问题返回成功，有问题返回配置错误。

调用关系：它会在 resolve_effective_permission_selection 中被调用，属于正式解析权限前的把关步骤，防止用户名字和内置名字体系撞车。

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

fn network_proxy_config_from_profile_network(
    network: Option<&NetworkToml>,
) -> NetworkProxyConfig

作用：从某个权限方案里的网络配置提取网络代理设置，但故意不让它直接启用代理。这样权限方案可以提供代理参数，却不能单独决定启动代理功能。

数据流：输入可选的 network 配置 → 有配置就转换成代理配置，没有就用默认值 → 最后强制把代理启用开关设为 false → 输出代理配置。

调用关系：它会被 network_proxy_config_for_profile_selection 调用，用在用户选择某个自定义权限方案后提取相关代理信息。

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

fn apply_network_proxy_feature_config(
    config: &mut NetworkProxyConfig,
    feature_config: &NetworkProxyConfigToml,
)

作用：把功能开关里的网络代理配置套用到已有代理配置上。它像把“全局功能设置”覆盖到“权限方案带来的基础设置”上。

数据流：输入一个可修改的代理配置和功能配置 → 把启用状态、代理地址、SOCKS5、域名允许/拒绝、Unix socket 规则等字段转换成统一格式 → 直接改写传入的代理配置。

调用关系：它会被 load_config_with_layer_stack 和 network_proxy_spec_for_active_permission_profile 调用；它不自己决定权限，只负责把功能配置转换后交给 NetworkToml 的 apply_to_network_proxy_config 合并。

调用图：被 2 处调用（load_config_with_layer_stack, network_proxy_spec_for_active_permission_profile）。

fn resolve_permission_profile(
    permissions: &PermissionsToml,
    profile_name: &str,
) -> io::Result<PermissionProfileToml>

作用：按名字找到并展开一个用户权限方案。它还允许用户方案继承部分内置方案，就像在现成模板上加自己的规则。

数据流：输入完整权限配置和方案名 → 调用配置对象的 resolve_profile，并提供可继承的内置父方案查找方法 → 成功输出展开后的方案配置，失败转成输入错误。

调用关系：compile_permission_profile、compile_permission_profile_workspace_roots 和 network_proxy_config_for_profile_selection 都会先用它拿到完整方案，再继续编译文件、工作区或网络规则。

调用图：调用 1 个内部函数（resolve_profile）；被 3 处调用（compile_permission_profile, compile_permission_profile_workspace_roots, network_proxy_config_for_profile_selection）。

fn extensible_builtin_parent_profile(profile_name: &str) -> Option<PermissionProfileToml>

作用：提供可以被用户方案继承的内置父方案。目前只允许继承只读和工作区写入这类安全模板。

数据流：输入一个父方案名 → 如果是支持继承的内置名，就先生成对应文件系统沙箱策略，再转成 TOML 风格的配置对象 → 输出可继承配置；不支持则输出空。

调用关系：它被 resolve_permission_profile 作为回调使用；内部会调用 permission_profile_toml_from_file_system_policy，把运行时策略转回可合并的配置形态。

调用图：调用 3 个内部函数（permission_profile_toml_from_file_system_policy, read_only, workspace_write）。

fn permission_profile_toml_from_file_system_policy(
    file_system: FileSystemSandboxPolicy,
) -> PermissionProfileToml

作用：把内部文件系统沙箱策略倒回成配置文件那种结构。这样内置方案也能像普通配置一样被用户方案继承和扩展。

数据流：输入文件系统沙箱策略 → 新建一个文件系统配置表 → 把每条沙箱规则插入成 TOML 权限项 → 输出一个权限方案配置对象。

调用关系：它由 extensible_builtin_parent_profile 调用；具体每条规则怎么写进表里，会交给 insert_filesystem_permission_toml。

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

fn insert_filesystem_permission_toml(
    entries: &mut BTreeMap<String, FilesystemPermissionToml>,
    entry: FileSystemSandboxEntry,
)

作用：把一条内部文件权限规则写进配置表。它负责区分普通路径、通配符模式和特殊路径。

数据流：输入配置表和一条文件系统规则 → 如果是普通路径就用路径字符串做键；如果是通配符就用模式字符串做键；如果是特殊路径就交给专门函数处理 → 配置表被新增或更新一项。

调用关系：它由 permission_profile_toml_from_file_system_policy 逐条调用；遇到特殊路径时会继续交给 insert_special_filesystem_permission_toml。

调用图：调用 1 个内部函数（insert_special_filesystem_permission_toml）；被 1 处调用（permission_profile_toml_from_file_system_policy）；外部调用 1 个（Access）。

fn insert_special_filesystem_permission_toml(
    entries: &mut BTreeMap<String, FilesystemPermissionToml>,
    value: FileSystemSpecialPath,
    access: FileSystemAccessMode,
)

作用：把“特殊路径”规则写回配置表，比如根目录、最小必需目录、工作区根目录、临时目录。特殊路径不是普通磁盘路径，所以需要单独翻译。

数据流：输入配置表、特殊路径类型和访问权限 → 把内部特殊路径变成配置里使用的冒号名字；如果带子路径，就写成分层权限 → 配置表被更新。

调用关系：它被 insert_filesystem_permission_toml 调用；当特殊路径还有下级范围时，会把细节交给 insert_scoped_filesystem_permission_toml。

调用图：调用 1 个内部函数（insert_scoped_filesystem_permission_toml）；被 1 处调用（insert_filesystem_permission_toml）；外部调用 1 个（Access）。

fn insert_scoped_filesystem_permission_toml(
    entries: &mut BTreeMap<String, FilesystemPermissionToml>,
    path: String,
    subpath: PathBuf,
    access: FileSystemAccessMode,
)

作用：把某个路径下面的子路径权限写成“分层配置”。这适合表达“工作区根目录下的某个目录可写”这种规则。

数据流：输入配置表、父路径名、子路径和访问权限 → 如果父路径还没有分层项就创建；如果原来是简单权限，就替换成分层权限 → 子路径权限被写入表中。

调用关系：它由 insert_special_filesystem_permission_toml 调用，是把特殊路径的子范围保存回 TOML 结构的最后一步。

调用图：被 1 处调用（insert_special_filesystem_permission_toml）；外部调用 3 个（from, to_string_lossy, Scoped）。

fn network_proxy_config_for_profile_selection(
    permissions: Option<&PermissionsToml>,
    profile_name: &str,
) -> io::Result<NetworkProxyConfig>

作用：根据当前选择的权限方案，拿到它对应的网络代理配置。内置方案没有自定义代理设置，所以直接给默认值。

数据流：输入可选权限配置和方案名 → 如果是内置方案就返回默认代理配置；如果是冒号开头但未知的内置名就报错；否则解析用户方案并提取 network 部分 → 输出代理配置或错误。

调用关系：它被 load_config_with_layer_stack 和 network_proxy_spec_for_active_permission_profile 调用；内部会用 is_builtin_permission_profile_name、reject_unknown_builtin_permission_profile、resolve_permission_profile 和 network_proxy_config_from_profile_network 串起整个判断链。

调用图：调用 4 个内部函数（is_builtin_permission_profile_name, network_proxy_config_from_profile_network, reject_unknown_builtin_permission_profile, resolve_permission_profile）；被 2 处调用（load_config_with_layer_stack, network_proxy_spec_for_active_permission_profile）；外部调用 1 个（default）。

fn compile_permission_profile(
    permissions: &PermissionsToml,
    profile_name: &str,
    policy_cwd: &Path,
    startup_warnings: &mut Vec<String>,
) -> io::Result<(FileSystemSandboxPolicy, Netwo

作用：把一个已经命名的用户权限方案编译成真正运行时使用的文件系统沙箱策略和网络沙箱策略。这里是自定义权限配置落地的核心步骤。

数据流：输入权限配置、方案名、配置相对路径基准目录和启动警告列表 → 解析方案，检查文件系统规则是否为空，提示平台不支持的通配符写法，逐条编译路径权限，验证 glob_scan_max_depth，再编译网络开关 → 输出文件系统策略和网络策略，并可能追加警告。

调用关系：它由 compile_permission_profile_selection 调用；内部把配置解析交给 resolve_permission_profile，把每条文件权限交给 compile_filesystem_permission，把网络部分交给 compile_network_sandbox_policy，还用多个检查函数生成友好警告。

调用图：调用 9 个内部函数（compile_filesystem_permission, compile_network_sandbox_policy, missing_filesystem_entries_warning, push_warning, resolve_permission_profile, unbounded_unreadable_globstar_paths, unsupported_read_write_glob_paths, validate_glob_scan_max_depth, restricted）；被 1 处调用（compile_permission_profile_selection）；外部调用 3 个（new, cfg!, format!）。

fn compile_permission_profile_selection(
    permissions: Option<&PermissionsToml>,
    profile_name: &str,
    workspace_write: Option<&SandboxWorkspaceWrite>,
    policy_cwd: &Path,
    startup_warn

作用：根据用户最终选中的权限方案，生成运行时权限。它先处理内置方案，处理不了才进入自定义方案编译。

数据流：输入可选权限配置、方案名、工作区写入设置、路径基准目录和警告列表 → 尝试把名字当内置方案生成权限；如果不是内置，就拒绝未知冒号方案，再要求存在 permissions 配置表并编译自定义方案 → 输出文件系统和网络沙箱策略。

调用关系：它被 load_config_with_layer_stack 调用，是配置加载时生成最终沙箱权限的总入口之一；它会调用 builtin_permission_profile、reject_unknown_builtin_permission_profile 和 compile_permission_profile。

调用图：调用 3 个内部函数（builtin_permission_profile, compile_permission_profile, reject_unknown_builtin_permission_profile）；被 1 处调用（load_config_with_layer_stack）。

fn compile_permission_profile_workspace_roots(
    permissions: Option<&PermissionsToml>,
    profile_name: &str,
    policy_cwd: &Path,
) -> io::Result<Vec<AbsolutePathBuf>>

作用：从自定义权限方案里提取额外的工作区根目录。工作区根目录会影响哪些项目目录被当成“允许范围”的一部分。

数据流：输入可选权限配置、方案名和路径基准目录 → 内置方案直接返回空列表；自定义方案先解析，再读取 workspace_roots 配置并转成绝对路径 → 输出绝对路径列表。

调用关系：它被 load_config_with_layer_stack 调用；它先用 is_builtin_permission_profile_name 和 reject_unknown_builtin_permission_profile 做名字判断，再用 resolve_permission_profile 和 compile_workspace_roots 完成实际转换。

调用图：调用 4 个内部函数（compile_workspace_roots, is_builtin_permission_profile_name, reject_unknown_builtin_permission_profile, resolve_permission_profile）；被 1 处调用（load_config_with_layer_stack）；外部调用 1 个（new）。

fn compile_workspace_roots(
    workspace_roots: Option<&WorkspaceRootsToml>,
    policy_cwd: &Path,
) -> Vec<AbsolutePathBuf>

作用：把配置里的工作区根目录列表变成绝对路径列表。这样后续沙箱不用猜相对路径到底相对哪里。

数据流：输入可选的 workspace_roots 配置和基准目录 → 没配置就返回空列表；有配置就只取启用的根目录，并逐个按基准目录解析成绝对路径 → 输出绝对路径数组。

调用关系：它只被 compile_permission_profile_workspace_roots 调用，是工作区根目录编译流程里的小转换器。

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

fn reject_unknown_builtin_permission_profile(profile_name: &str) -> io::Result<()>

作用：拒绝看起来像内置方案、但当前版本不认识的方案名。这样可以避免用户拼错内置名字后被当成普通自定义方案。

数据流：输入方案名 → 如果以冒号开头就返回“未知内置方案”的错误；否则返回成功 → 不产生其他改动。

调用关系：compile_permission_profile_selection、compile_permission_profile_workspace_roots 和 network_proxy_config_for_profile_selection 都会调用它，用来统一守住内置名字空间。

调用图：被 3 处调用（compile_permission_profile_selection, compile_permission_profile_workspace_roots, network_proxy_config_for_profile_selection）；外部调用 2 个（new, format!）。

fn get_readable_roots_required_for_codex_runtime(
    codex_home: &Path,
    zsh_path: Option<&PathBuf>,
    main_execve_wrapper_exe: Option<&PathBuf>,
) -> Vec<AbsolutePathBuf>

作用：列出 Codex 自己运行时必须能读取的几个路径，比如 shell 或执行包装器的位置。即使用户权限很严，也不能把这些基础工具完全挡住，否则 Codex 自己会跑不起来。

数据流：输入 Codex 主目录、可选 zsh 路径、可选 execve 包装器路径 → 尝试把这些路径转成绝对路径，并对位于 arg0 临时目录下的包装器取父目录 → 输出必须额外可读的路径列表。

调用关系：它被 load_config_with_layer_stack 调用，用在加载配置时补齐运行所需的最低可读路径。

调用图：调用 1 个内部函数（from_absolute_path）；被 1 处调用（load_config_with_layer_stack）；外部调用 2 个（join, new）。

fn compile_network_sandbox_policy(
    network: Option<&NetworkToml>,
    base_network_sandbox_policy: NetworkSandboxPolicy,
) -> NetworkSandboxPolicy

作用：把权限方案里的网络 enabled 开关变成运行时网络沙箱策略。简单说，就是决定网络是放开还是受限。

数据流：输入可选网络配置和基础网络策略 → 没有配置就沿用基础策略；enabled 为 true 就允许网络；enabled 为 false 就限制网络；没写 enabled 也沿用基础策略 → 输出网络策略。

调用关系：它由 compile_permission_profile 调用，是自定义权限方案编译到最后生成网络策略的步骤。

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

fn compile_filesystem_permission(
    path: &str,
    permission: &FilesystemPermissionToml,
    policy_cwd: &Path,
    startup_warnings: &mut Vec<String>,
) -> io::Result<Vec<FileSystemSandboxEntry>>

作用：把配置表里一条文件系统权限编译成一条或多条沙箱规则。它处理简单路径，也处理“某个父路径下多个子路径”的分层写法。

数据流：输入路径键、权限值、基准目录和警告列表 → 如果是简单权限，就编译路径本身；如果是分层权限，就逐个处理子路径，必要时把 deny 通配符变成模式规则 → 输出沙箱规则列表。

调用关系：它由 compile_permission_profile 对每条配置调用；内部会根据情况把工作交给 compile_filesystem_access_path、compile_scoped_filesystem_path、compile_scoped_filesystem_pattern 或 compile_read_write_glob_path。

调用图：调用 6 个内部函数（compile_filesystem_access_path, compile_read_write_glob_path, compile_scoped_filesystem_path, compile_scoped_filesystem_pattern, contains_glob_chars, parse_special_path）；被 1 处调用（compile_permission_profile）；外部调用 1 个（new）。

fn compile_filesystem_access_path(
    path: &str,
    access: FileSystemAccessMode,
    startup_warnings: &mut Vec<String>,
) -> io::Result<FileSystemPath>

作用：编译一条没有分层子项的文件路径权限。它特别处理通配符：拒绝访问可以用模式，读写访问则只允许安全的尾部 /** 写法。

数据流：输入路径字符串、访问权限和警告列表 → 如果没有通配符就按普通路径编译；如果是 deny 通配符，就先要求它是绝对路径再变成模式；如果是读写通配符，就检查并去掉尾部 /** 后再按普通路径处理 → 输出内部文件路径表达。

调用关系：它由 compile_filesystem_permission 调用；普通路径会继续交给 compile_filesystem_path，复杂读写通配符会交给 compile_read_write_glob_path 检查。

调用图：调用 4 个内部函数（compile_filesystem_path, compile_read_write_glob_path, contains_glob_chars, parse_absolute_path）；被 1 处调用（compile_filesystem_permission）。

fn compile_filesystem_path(
    path: &str,
    startup_warnings: &mut Vec<String>,
) -> io::Result<FileSystemPath>

作用：把一个顶层路径字符串变成内部文件路径对象。它能识别冒号开头的特殊路径，也能要求普通路径必须是绝对路径。

数据流：输入路径字符串和警告列表 → 先看是不是特殊路径；未知特殊路径会记录警告但仍保留为可忽略对象；普通路径则解析为绝对路径 → 输出内部路径对象或错误。

调用关系：它被 compile_filesystem_access_path 和 compile_scoped_filesystem_path 使用；它会调用 parse_special_path、maybe_push_unknown_special_path_warning 和 parse_absolute_path。

调用图：调用 3 个内部函数（maybe_push_unknown_special_path_warning, parse_absolute_path, parse_special_path）；被 2 处调用（compile_filesystem_access_path, compile_scoped_filesystem_path）。

fn compile_scoped_filesystem_path(
    path: &str,
    subpath: &str,
    startup_warnings: &mut Vec<String>,
) -> io::Result<FileSystemPath>

作用：编译“父路径 + 子路径”这种分层文件权限。比如把“/repo”下面的“src”拼成“/repo/src”，或者把“工作区根目录”下面的子目录保留成特殊规则。

数据流：输入父路径、子路径和警告列表 → 子路径是点号时直接当父路径处理；如果父路径是特殊路径，就检查子路径必须是干净的相对路径并生成特殊子路径规则；如果父路径是普通绝对路径，就把两者拼成绝对路径 → 输出内部路径对象。

调用关系：它由 compile_filesystem_permission 调用；它会借助 parse_special_path、parse_relative_subpath、parse_absolute_path 和 resolve_path_against_base，并在未知特殊路径时调用 maybe_push_unknown_special_path_warning。

调用图：调用 6 个内部函数（compile_filesystem_path, maybe_push_unknown_special_path_warning, parse_absolute_path, parse_relative_subpath, parse_special_path, resolve_path_against_base）；被 1 处调用（compile_filesystem_permission）；外部调用 4 个（project_roots, unknown, new, format!）。

fn compile_scoped_filesystem_pattern(
    path: &str,
    subpath: &str,
    access: FileSystemAccessMode,
    _policy_cwd: &Path,
) -> io::Result<String>

作用：把分层配置里的通配符 deny 子路径编译成沙箱模式。这里目前只支持拒绝访问，不支持用通配符来放开读写。

数据流：输入父路径、通配符子路径、访问权限和基准目录 → 先确认访问权限必须是 deny，再检查子路径是安全相对路径；如果父路径是工作区根目录，就生成符号化的工作区 glob 模式；如果是普通绝对路径，就拼成完整模式 → 输出模式字符串或错误。

调用关系：它由 compile_filesystem_permission 在遇到可编译的 deny 通配符子项时调用；内部使用 parse_relative_subpath、parse_special_path、parse_absolute_path 和 project_roots_glob_pattern。

调用图：调用 4 个内部函数（parse_absolute_path, parse_relative_subpath, parse_special_path, project_roots_glob_pattern）；被 1 处调用（compile_filesystem_permission）；外部调用 2 个（new, format!）。

fn compile_read_write_glob_path(path: &str, access: FileSystemAccessMode) -> io::Result<&str>

作用：检查读写权限里的通配符路径是否安全。当前只允许“某个目录/**”这种表示整棵子树的写法，不允许更复杂的读写 glob。

数据流：输入路径和访问权限 → 如果没有通配符就原样返回；如果只有尾部 /**，就去掉这个后缀返回目录路径；如果还有其他通配符，就返回错误并说明只能用于 deny 或改成安全写法 → 输出可继续解析的路径字符串。

调用关系：它被 compile_filesystem_access_path 和 compile_filesystem_permission 调用，是读写权限遇到通配符时的安全阀。

调用图：调用 2 个内部函数（contains_glob_chars, remove_trailing_glob_suffix）；被 2 处调用（compile_filesystem_access_path, compile_filesystem_permission）；外部调用 2 个（new, format!）。

fn unsupported_read_write_glob_paths(filesystem: &FilesystemPermissionsToml) -> Vec<String>

作用：找出文件权限里那些在非 macOS 平台上不太可靠的读写通配符。它不直接报错，而是帮助生成启动警告。

数据流：输入文件系统权限配置 → 遍历顶层和分层条目，找出非 deny 权限里除尾部 /** 之外还带通配符的路径 → 输出这些问题路径列表。

调用关系：它由 compile_permission_profile 在非 macOS 平台调用；找到的路径会被包装成警告，通过 push_warning 放进启动警告列表。

调用图：调用 2 个内部函数（contains_glob_chars, remove_trailing_glob_suffix）；被 1 处调用（compile_permission_profile）；外部调用 2 个（new, format!）。

fn unbounded_unreadable_globstar_paths(filesystem: &FilesystemPermissionsToml) -> Vec<String>

作用：找出 deny 规则里没有深度限制的 通配符。因为某些平台不能原生处理无限层级的 ，需要提醒用户设置扫描深度。

数据流：输入文件系统权限配置 → 如果已经设置 glob_scan_max_depth 就不用警告；否则遍历 deny 规则，找出包含 ** 的路径或子路径 → 输出这些路径列表。

调用关系：它由 compile_permission_profile 调用；结果会变成启动警告，提示用户设置 glob_scan_max_depth 或枚举明确深度。

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

fn validate_glob_scan_max_depth(max_depth: Option<usize>) -> io::Result<Option<usize>>

作用：检查通配符扫描最大深度是否合法。深度不能是 0，因为 0 没有实际扫描意义。

数据流：输入可选最大深度 → 如果是 Some(0) 就返回配置错误；其他值原样通过 → 输出合法的可选深度。

调用关系：它由 compile_permission_profile 调用，用来在把 glob_scan_max_depth 写入运行时策略前做最后校验。

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

fn contains_glob_chars(path: &str) -> bool

作用：判断路径字符串里有没有通配符字符，比如 *、?、[、]。这决定后面要按普通路径还是模式路径处理。

数据流：输入路径字符串 → 按当前平台选择是否做 Windows 路径规范化 → 检查是否包含通配符字符 → 输出 true 或 false。

调用关系：它被 compile_filesystem_access_path、compile_filesystem_permission、compile_read_write_glob_path 和 unsupported_read_write_glob_paths 调用；实际平台差异交给 contains_glob_chars_for_platform。

调用图：调用 1 个内部函数（contains_glob_chars_for_platform）；被 4 处调用（compile_filesystem_access_path, compile_filesystem_permission, compile_read_write_glob_path, unsupported_read_write_glob_paths）；外部调用 1 个（cfg!）。

fn contains_glob_chars_for_platform(path: &str, is_windows: bool) -> bool

作用：按指定平台规则检查路径中是否有通配符。Windows 下会先把某些特殊设备路径写法变成普通写法，避免误判。

数据流：输入路径字符串和是否 Windows 的标志 → 如果是 Windows，先尝试规范化设备路径；然后扫描字符 → 输出是否含有 glob 通配符。

调用关系：它由 contains_glob_chars 调用；Windows 特殊路径处理会交给 normalize_windows_device_path。

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

fn remove_trailing_glob_suffix(path: &str) -> &str

作用：去掉路径末尾的 /** 后缀。这个后缀在配置里表示“整个目录树”，但真正用于读写路径时需要还原成目录本身。

数据流：输入路径字符串 → 如果末尾是 /** 就返回去掉后的部分，否则返回原字符串 → 不分配新路径，只返回原字符串的一段。

调用关系：它被 compile_read_write_glob_path 和 unsupported_read_write_glob_paths 使用，用来判断通配符是否只是安全的尾部子树写法。

调用图：被 2 处调用（compile_read_write_glob_path, unsupported_read_write_glob_paths）。

fn parse_special_path(path: &str) -> Option<FileSystemSpecialPath>

作用：识别冒号开头的特殊文件路径名，比如 :root、:workspace_roots、:tmpdir。它还会保留未知特殊路径，方便旧版本遇到新配置时给警告而不是直接崩掉。

数据流：输入路径字符串 → 和已知特殊名比较；已知就生成对应特殊路径对象；冒号开头但未知就生成 Unknown；普通路径返回空 → 输出可选特殊路径对象。

调用关系：它被 compile_filesystem_path、compile_filesystem_permission、compile_scoped_filesystem_path 和 compile_scoped_filesystem_pattern 调用，是特殊路径解析的统一入口。

调用图：被 4 处调用（compile_filesystem_path, compile_filesystem_permission, compile_scoped_filesystem_path, compile_scoped_filesystem_pattern）；外部调用 2 个（project_roots, unknown）。

fn parse_absolute_path(path: &str) -> io::Result<AbsolutePathBuf>

作用：把字符串解析成绝对路径对象，并使用当前系统的平台规则。普通文件权限必须是绝对路径、家目录写法，或者特殊冒号路径。

数据流：输入路径字符串 → 按当前是否 Windows 调用平台版解析 → 输出绝对路径对象或配置错误。

调用关系：它被 compile_filesystem_access_path、compile_filesystem_path、compile_scoped_filesystem_path 和 compile_scoped_filesystem_pattern 调用；真正检查逻辑在 parse_absolute_path_for_platform。

调用图：调用 1 个内部函数（parse_absolute_path_for_platform）；被 4 处调用（compile_filesystem_access_path, compile_filesystem_path, compile_scoped_filesystem_path, compile_scoped_filesystem_pattern）；外部调用 1 个（cfg!）。

fn parse_absolute_path_for_platform(path: &str, is_windows: bool) -> io::Result<AbsolutePathBuf>

作用：按指定平台规则验证并创建绝对路径。它处理 Unix 和 Windows 对“绝对路径”的不同判断方式。

数据流：输入路径字符串和是否 Windows → 先规范化可能的 Windows 特殊路径，再判断是不是绝对路径或家目录写法；不符合就报错；符合就转成 AbsolutePathBuf → 输出绝对路径对象。

调用关系：它由 parse_absolute_path 调用；内部会用 normalize_absolute_path_for_platform 和 is_absolute_path_for_platform 做平台差异处理。

调用图：调用 3 个内部函数（is_absolute_path_for_platform, normalize_absolute_path_for_platform, from_absolute_path）；被 1 处调用（parse_absolute_path）；外部调用 2 个（new, format!）。

fn is_absolute_path_for_platform(path: &str, normalized_path: &Path, is_windows: bool) -> bool

作用：判断一个路径在指定平台上算不算绝对路径。Windows 的盘符和网络路径规则跟 Unix 不一样，所以要分开看。

数据流：输入原始路径、规范化后的 Path、是否 Windows → Windows 下检查盘符绝对路径或反斜杠网络路径；非 Windows 下调用系统路径的 is_absolute → 输出 true 或 false。

调用关系：它被 parse_absolute_path_for_platform 调用；Windows 情况下会继续使用 is_windows_absolute_path。

调用图：调用 1 个内部函数（is_windows_absolute_path）；被 1 处调用（parse_absolute_path_for_platform）；外部调用 2 个（is_absolute, to_string_lossy）。

fn normalize_absolute_path_for_platform(path: &str, is_windows: bool) -> Cow<'_, Path>

作用：在需要时把 Windows 的设备路径写法转换成普通路径写法。非 Windows 平台则不动原路径。

数据流：输入路径字符串和是否 Windows → 非 Windows 直接借用原路径；Windows 下尝试规范化 \\?\ 或 \\.\ 这类前缀 → 输出借用路径或新建路径。

调用关系：它由 parse_absolute_path_for_platform 调用；具体 Windows 前缀识别交给 normalize_windows_device_path。

调用图：调用 1 个内部函数（normalize_windows_device_path）；被 1 处调用（parse_absolute_path_for_platform）；外部调用 4 个（Borrowed, Owned, new, from）。

fn normalize_windows_device_path(path: &str) -> Option<String>

作用：把 Windows 的特殊设备路径前缀改成更普通的路径形式。比如把某些 UNC 设备路径还原成网络共享路径。

数据流：输入路径字符串 → 识别 \\?\UNC\、\\.\UNC\、\\?\C:\、\\.\C:\ 等形式 → 如果能规范化就输出新字符串，否则输出空。

调用关系：它被 contains_glob_chars_for_platform 和 normalize_absolute_path_for_platform 调用；识别盘符绝对路径时会使用 is_windows_drive_absolute_path。

调用图：调用 1 个内部函数（is_windows_drive_absolute_path）；被 2 处调用（contains_glob_chars_for_platform, normalize_absolute_path_for_platform）；外部调用 1 个（format!）。

fn is_windows_absolute_path(path: &str) -> bool

作用：判断字符串是不是 Windows 绝对路径。它覆盖盘符路径和网络共享路径两种常见形式。

数据流：输入路径字符串 → 检查是不是 C:\ 这类盘符绝对路径，或者是否以双反斜杠开头 → 输出 true 或 false。

调用关系：它被 is_absolute_path_for_platform 调用；盘符部分的细节交给 is_windows_drive_absolute_path。

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

fn is_windows_drive_absolute_path(path: &str) -> bool

作用：判断路径是不是 Windows 盘符开头的绝对路径，比如 C:\foo 或 D:/bar。

数据流：输入路径字符串 → 查看前三个字节是否符合“字母 + 冒号 + 斜杠或反斜杠” → 输出 true 或 false。

调用关系：它被 is_windows_absolute_path 和 normalize_windows_device_path 调用，是 Windows 路径判断里最底层的小检查。

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

fn parse_relative_subpath(subpath: &str) -> io::Result<PathBuf>

作用：检查子路径是不是安全的相对后代路径。它禁止空路径、点号、双点号等可能跳出父目录的写法。

数据流：输入子路径字符串 → 转成 Path 并检查每个组成部分都只是普通名字 → 合法则输出 PathBuf；否则返回配置错误。

调用关系：它被 compile_scoped_filesystem_path 和 compile_scoped_filesystem_pattern 调用，用来保证分层权限不会通过 ../ 之类写法绕出父路径。

调用图：被 2 处调用（compile_scoped_filesystem_path, compile_scoped_filesystem_pattern）；外部调用 3 个（new, new, format!）。

fn push_warning(startup_warnings: &mut Vec<String>, message: String)

作用：统一记录启动警告。它既写日志，也把警告文字放进列表，方便之后展示给用户。

数据流：输入可修改的警告列表和一条消息 → 通过 tracing 写一条 warn 日志 → 把消息追加到列表里。

调用关系：它被 compile_permission_profile 和 maybe_push_unknown_special_path_warning 调用，是权限配置警告的集中出口。

调用图：被 2 处调用（compile_permission_profile, maybe_push_unknown_special_path_warning）；外部调用 1 个（warn!）。

fn missing_filesystem_entries_warning(profile_name: &str) -> String

作用：生成“这个权限方案没有可识别文件系统规则”的提示文字。这样用户知道当前文件权限会保持受限，不是程序默默忽略了。

数据流：输入权限方案名 → 拼出一段说明该方案没有被当前版本识别到文件系统条目的警告文本 → 输出字符串。

调用关系：它被 compile_permission_profile 调用；生成的文字会再交给 push_warning 记录。

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

fn maybe_push_unknown_special_path_warning(
    special: &FileSystemSpecialPath,
    startup_warnings: &mut Vec<String>,
)

作用：如果配置里用了当前版本不认识的特殊路径，就给用户一条警告。这样新版本配置被旧版本读取时，不会直接失败，但用户能知道有规则被忽略了。

数据流：输入特殊路径对象和警告列表 → 如果不是 Unknown 就什么都不做；如果是未知特殊路径，就根据是否带子路径生成警告 → 调用 push_warning 记录。

调用关系：它被 compile_filesystem_path 和 compile_scoped_filesystem_path 调用；它把未知特殊路径问题转交给 push_warning 做统一日志和收集。

调用图：调用 1 个内部函数（push_warning）；被 2 处调用（compile_filesystem_path, compile_scoped_filesystem_path）；外部调用 1 个（format!）。

fn from_str(id: &str) -> Option<Self>

作用：把外部传进来的档案名字，认成系统内置的三种权限档案之一。认不出来就说明它不是内置档案，可能是用户自定义档案。

数据流：输入一个字符串 id → 和三个固定的内置名字逐个比较 → 如果匹配就输出对应的内置枚举值，不匹配就输出空值。

调用关系：ResolvedPermissionProfile::from_active_profile 在整理当前激活档案时会先问它一句：这个名字是不是内置的？如果是，就走内置档案分支；如果不是，就当作命名档案处理。

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

fn as_str(self) -> &'static str

作用：把系统内部保存的内置档案编号，转换回对外使用的固定字符串名字。这样会话状态或前端界面能看到熟悉的档案 id。

数据流：输入一个内置档案枚举值 → 按 ReadOnly、Workspace、DangerFullAccess 三种情况选择固定常量 → 输出对应的字符串。

调用关系：它是 from_str 的反向操作。系统需要把已解析的内置档案重新包装成 ActivePermissionProfile 时，会用它恢复原来的公开名字。

fn from_active_profile(
        permission_profile: PermissionProfile,
        active_permission_profile: Option<ActivePermissionProfile>,
        profile_workspace_roots: Vec<AbsolutePathBuf>,
    )

作用：把“具体权限规则”和“当前激活的档案信息”合成一个已解析的权限档案。它会分清这是老式无名权限、内置档案，还是用户自定义档案。

数据流：输入具体 PermissionProfile、可选的 ActivePermissionProfile、以及档案声明的工作区根路径 → 如果没有激活档案信息，就做成 Legacy；如果有，就先判断 id 是否内置，再分别做成 BuiltIn 或 Named → 输出统一的 ResolvedPermissionProfile。

调用关系：PermissionProfileSnapshot::active_with_profile_workspace_roots 和 PermissionProfileState::from_constrained_active_profile 都会调用它。它在权限配置刚被选中或加载时，把零散信息装进统一容器，后面其他代码就不用反复判断来源。

调用图：调用 1 个内部函数（from_str）；被 2 处调用（active_with_profile_workspace_roots, from_constrained_active_profile）；外部调用 3 个（BuiltIn, Named, legacy）。

fn legacy(permission_profile: PermissionProfile) -> Self

作用：创建一种老式权限档案：只有具体权限规则，没有“当前选中了哪个档案”的名字。用于兼容旧配置或临时覆盖。

数据流：输入一个 PermissionProfile → 包进 LegacyPermissionProfile → 输出 ResolvedPermissionProfile::Legacy。

调用关系：很多入口会用它处理无名权限，例如 PermissionProfileSnapshot::legacy、PermissionProfileState::from_constrained_legacy、以及运行中检查或设置老式权限时。

调用图：被 4 处调用（legacy, can_set_legacy_permission_profile, from_constrained_legacy, set_legacy_permission_profile）；外部调用 1 个（Legacy）。

fn permission_profile(&self) -> &PermissionProfile

作用：不管权限档案来自哪里，都取出里面真正的权限规则。调用者不用关心它是老式、内置，还是自定义。

数据流：输入一个已解析权限档案的引用 → 按当前变体找到内部的 permission_profile 字段 → 输出这份具体权限规则的只读引用。

调用关系：PermissionProfileSnapshot 和 PermissionProfileState 的同名读取方法都会靠它取实际规则。它是其他模块查看“真正允许什么”的统一出口。

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

fn active_permission_profile(&self) -> Option<ActivePermissionProfile>

作用：取出当前激活档案的身份信息。老式权限没有身份，所以会返回空。

数据流：输入一个已解析权限档案 → 如果是 Legacy，输出空值；如果是 BuiltIn，就把内置编号转成字符串并带上 extends；如果是 Named，就复制自定义 id 和 extends → 输出可选的 ActivePermissionProfile。

调用关系：PermissionProfileSnapshot 和 PermissionProfileState 需要向会话、界面或其他配置层报告当前选中档案时，会通过它恢复“档案名字”。

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

fn profile_workspace_roots(&self) -> &[AbsolutePathBuf]

作用：取出这个权限档案自己声明的工作区根目录。老式权限没有这类附加目录，所以返回空列表。

数据流：输入一个已解析权限档案 → 如果是 BuiltIn 或 Named，就返回保存的 profile_workspace_roots；如果是 Legacy，就返回空切片 → 不复制数据，只给只读视图。

调用关系：PermissionProfileSnapshot 和 PermissionProfileState 的读取方法会调用它，让权限系统能把档案自带的工作目录和运行时临时工作目录区分开。

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

fn legacy(permission_profile: PermissionProfile) -> Self

作用：创建一个没有激活档案名字的权限快照。适合旧数据，或确实不属于任何命名档案的本地覆盖。

数据流：输入具体 PermissionProfile → 调用 ResolvedPermissionProfile::legacy 包成老式已解析档案 → 输出 PermissionProfileSnapshot。

调用关系：设置权限投影、继承父线程运行时设置、更新功能开关、同步会话配置等流程会用它保存无名权限状态。它明确表示“这里只有规则，没有档案身份”。

调用图：调用 1 个内部函数（legacy）；被 4 处调用（set_permission_profile_projection, side_fork_config_inherits_parent_thread_runtime_settings, update_feature_flags_disabling_guardian_clears_review_policy_and_restores_default, session_configured_syncs_widget_config_permissions_and_cwd）。

fn active(
        permission_profile: PermissionProfile,
        active_permission_profile: ActivePermissionProfile,
    ) -> Self

作用：创建一个带当前激活档案名字的权限快照。用于调用者已经可信地知道“这个名字”和“这套权限规则”是一起解析出来的场景。

数据流：输入具体 PermissionProfile 和 ActivePermissionProfile → 用空的档案工作区根路径调用 active_with_profile_workspace_roots → 输出 PermissionProfileSnapshot。

调用关系：运行时应用配置、处理事件、同步界面权限选择、测试权限约束等很多地方会用它。它是最常用的“保存当前选中权限档案”的快捷入口。

调用图：被 21 处调用（permission_snapshot_setter_preserves_permission_constraints, apply, sync_auto_review_runtime_state_from_effective_config, try_set_builtin_active_permission_profile_on_config, handle_event, permission_settings_sync_updates_active_snapshot_without_rewriting_side_thread, profile_permissions_selection_emits_active_custom_profile, profile_permissions_selection_emits_auto_review_mode_event, profile_permissions_selection_emits_named_profile_event_only, profile_permissions_selection_popup_snapshot (+11 more)）；外部调用 2 个（active_with_profile_workspace_roots, new）。

fn active_with_profile_workspace_roots(
        permission_profile: PermissionProfile,
        active_permission_profile: ActivePermissionProfile,
        profile_workspace_roots: Vec<AbsolutePathBuf>

作用：创建一个带档案身份、并且保留档案自带工作区根目录的权限快照。适合选中的档案自己声明了额外可用目录的情况。

数据流：输入具体 PermissionProfile、ActivePermissionProfile、以及一组绝对路径根目录 → 调用 ResolvedPermissionProfile::from_active_profile 统一分类并打包 → 输出 PermissionProfileSnapshot。

调用关系：设置权限投影和检查状态栏工作区根目录时会用它。它比 active 多保留一份“这些目录是档案声明的”信息，避免和临时运行目录混在一起。

调用图：调用 1 个内部函数（from_active_profile）；被 2 处调用（set_permission_profile_projection, status_permissions_workspace_roots_include_profile_defined_directories）。

fn from_session_snapshot(
        permission_profile: PermissionProfile,
        active_permission_profile: Option<ActivePermissionProfile>,
    ) -> Self

作用：从会话里保存下来的信息重新拼出权限快照。它用于恢复 core 已经发出过的可信会话状态。

数据流：输入具体 PermissionProfile 和可选 ActivePermissionProfile → 如果有激活档案，就走 active；如果没有，就走 legacy → 输出 PermissionProfileSnapshot。

调用关系：应用权限选择、运行时策略覆盖、功能开关更新、线程设置应用等流程会调用它。它的定位是“恢复已保存状态”，不是拿来随便解析用户新输入。

调用图：被 6 处调用（apply_permission_profile_selection, apply_runtime_policy_overrides, update_feature_flags, on_session_configured_with_display_and_fork_parent_title, apply_thread_settings, set_permission_profile_with_active_profile）；外部调用 2 个（active, legacy）。

fn permission_profile(&self) -> &PermissionProfile

作用：从快照里取出真正的权限规则。调用者可以忽略快照里是否带档案名字。

数据流：输入一个 PermissionProfileSnapshot → 转给内部的 ResolvedPermissionProfile::permission_profile → 输出只读的 PermissionProfile 引用。

调用关系：替换会话快照中的权限档案时会用它查看快照里的实际规则。它是快照对外暴露具体权限内容的小窗口。

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

fn active_permission_profile(&self) -> Option<ActivePermissionProfile>

作用：从快照里取出“当前激活的是哪个权限档案”。如果这个快照是老式无名权限，就返回空。

数据流：输入一个 PermissionProfileSnapshot → 询问内部 ResolvedPermissionProfile 的 active_permission_profile → 输出可选的 ActivePermissionProfile。

调用关系：它把内部分类细节藏起来，让外部只需要问快照本身，就能知道是否有当前档案身份。

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

fn profile_workspace_roots(&self) -> &[AbsolutePathBuf]

作用：从快照里取出档案声明的工作区根目录列表。这个列表说明该档案额外认可哪些目录范围。

数据流：输入一个 PermissionProfileSnapshot → 转给内部 ResolvedPermissionProfile::profile_workspace_roots → 输出只读路径列表。

调用关系：它服务于需要安装或展示权限工作区范围的代码。外部不用知道这些根目录只存在于内置或命名档案里。

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

fn into_resolved_permission_profile(self) -> ResolvedPermissionProfile

作用：把快照拆开，拿出里面的已解析权限档案本体。调用后快照会被消耗掉。

数据流：输入一个 PermissionProfileSnapshot 本身 → 取出 resolved_permission_profile 字段 → 输出 ResolvedPermissionProfile，并不再保留原快照。

调用关系：替换会话快照权限、或 PermissionProfileState::set_permission_profile_snapshot 安装快照时会用它。它是从“传递用快照”进入“运行中状态”的交接口。

调用图：被 2 处调用（replace_permission_profile_from_session_snapshot, set_permission_profile_snapshot）。

fn from_constrained_legacy(
        constrained_permission_profile: Constrained<PermissionProfile>,
    ) -> ConstraintResult<Self>

作用：用一份已经带限制的老式权限规则，创建运行中的权限状态。限制会继续保留，防止以后改成越界权限。

数据流：输入 Constrained<PermissionProfile>，也就是带规则限制的权限盒子 → 取出当前权限规则并包装成 Legacy → 交给 from_constrained_resolved 重新套上针对已解析档案的限制 → 输出 PermissionProfileState 或限制错误。

调用关系：从审批模式和权限档案创建配置时会调用它。它负责把旧格式权限接入新的统一状态模型。

调用图：调用 2 个内部函数（get, legacy）；被 1 处调用（from_approval_and_profile）；外部调用 1 个（from_constrained_resolved）。

fn from_constrained_active_profile(
        constrained_permission_profile: Constrained<PermissionProfile>,
        active_permission_profile: Option<ActivePermissionProfile>,
        profile_workspac

作用：用一份已经带限制的权限规则，加上当前激活档案信息，创建运行中的权限状态。它既保留档案身份，也保留权限约束。

数据流：输入 Constrained<PermissionProfile>、可选 ActivePermissionProfile、以及档案工作区根路径 → 取出当前权限规则，调用 from_active_profile 组合成已解析档案 → 交给 from_constrained_resolved 安装限制 → 输出 PermissionProfileState 或错误。

调用关系：加载带层级的配置时会调用它。它是配置文件里的权限选择变成运行时状态的关键一步。

调用图：调用 2 个内部函数（get, from_active_profile）；被 1 处调用（load_config_with_layer_stack）；外部调用 1 个（from_constrained_resolved）。

fn from_constrained_resolved(
        constrained_permission_profile: Constrained<PermissionProfile>,
        resolved_permission_profile: ResolvedPermissionProfile,
    ) -> ConstraintResult<Self>

作用：把已解析权限档案放进一个带限制的状态盒子里。以后无论设置哪个档案，都必须先通过原来的权限约束检查。

数据流：输入带限制的 PermissionProfile 和一个 ResolvedPermissionProfile → 建立新的 Constrained<ResolvedPermissionProfile>；检查候选档案时，只看候选档案里的具体 PermissionProfile 是否被原限制允许 → 成功则输出 PermissionProfileState，失败则返回限制错误。

调用关系：老式构造、激活档案构造、以及从会话快照替换权限时都会走到这里。它是把“限制规则”从普通权限迁移到已解析权限档案上的核心关卡。

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

fn permission_profile(&self) -> &PermissionProfile

作用：读取当前运行状态里的实际权限规则。外部模块用它判断当前允许读写、执行或联网到什么程度。

数据流：输入 PermissionProfileState → 从内部 Constrained 盒子取出当前 ResolvedPermissionProfile → 再取出具体 PermissionProfile → 输出只读引用。

调用关系：权限查询、网络沙箱策略等流程会调用它。它是运行时读取当前权限规则的常规入口。

调用图：调用 1 个内部函数（get）；被 3 处调用（permission_profile, network_sandbox_policy, permission_profile）。

fn active_permission_profile(&self) -> Option<ActivePermissionProfile>

作用：读取当前运行状态里记录的激活权限档案身份。没有身份时返回空，表示这是老式或无名权限。

数据流：输入 PermissionProfileState → 从内部受限状态取出当前已解析档案 → 调用 active_permission_profile → 输出可选的 ActivePermissionProfile。

调用关系：外层配置对象或会话状态需要显示、同步当前选中权限档案时会调用它。它把状态里的档案身份安全地传出去。

调用图：调用 1 个内部函数（get）；被 2 处调用（active_permission_profile, active_permission_profile）。

fn profile_workspace_roots(&self) -> &[AbsolutePathBuf]

作用：读取当前权限档案声明的工作区根目录。权限系统可用它决定哪些目录属于档案允许范围。

数据流：输入 PermissionProfileState → 从内部受限状态取出当前已解析档案 → 调用 profile_workspace_roots → 输出只读路径列表。

调用关系：外层权限对象或配置对象需要汇总工作区根目录时会调用它。它保证读取的是当前已安装档案的目录信息。

调用图：调用 1 个内部函数（get）；被 2 处调用（profile_workspace_roots, profile_workspace_roots）。

fn can_set_legacy_permission_profile(
        &self,
        permission_profile: &PermissionProfile,
    ) -> ConstraintResult<()>

作用：预先检查：如果把当前状态改成某个老式无名权限，会不会违反限制。它只检查，不真正修改。

数据流：输入一个想要设置的 PermissionProfile 引用 → 复制这份权限并包装成 Legacy 候选值 → 交给内部 Constrained 的 can_set 检查 → 输出成功或限制错误，原状态不变。

调用关系：检查是否能设置老式沙箱策略或权限档案时会调用它。它像试穿衣服，不合身就提前告诉你，不会真的换上。

调用图：调用 2 个内部函数（can_set, legacy）；被 2 处调用（can_set_legacy_sandbox_policy, can_set_permission_profile）；外部调用 1 个（clone）。

fn set_legacy_permission_profile(
        &mut self,
        permission_profile: PermissionProfile,
    ) -> ConstraintResult<()>

作用：把当前权限状态真正改成一份老式无名权限。修改前仍然必须通过内部限制。

数据流：输入新的 PermissionProfile → 包装成 Legacy 候选值 → 调用内部 Constrained 的 set；如果限制允许就替换当前值，不允许就返回错误并保持原状。

调用关系：设置老式沙箱策略、设置权限档案、测试中设置权限时会调用它。它是老接口修改当前权限的实际执行点。

调用图：调用 2 个内部函数（set, legacy）；被 3 处调用（set_legacy_sandbox_policy, set_permission_profile, set_permission_profile_for_tests）。

fn set_permission_profile_snapshot(
        &mut self,
        snapshot: PermissionProfileSnapshot,
    ) -> ConstraintResult<()>

作用：用一个可信权限快照替换当前运行状态。它会保留快照里的档案身份和工作区根目录，但仍要过权限限制。

数据流：输入 PermissionProfileSnapshot → 先把快照拆成 ResolvedPermissionProfile → 调用内部 Constrained 的 set 尝试安装 → 成功则当前状态变成快照内容，失败则返回限制错误。

调用关系：从会话快照设置权限、或设置权限投影时会调用它。它是“外部已经整理好的权限快照”进入 PermissionProfileState 的主要入口。

调用图：调用 2 个内部函数（set, into_resolved_permission_profile）；被 2 处调用（set_permission_profile_from_session_snapshot, set_permission_profile_projection）。

fn legacy_compatible_permission_profile(
    permission_profile: &PermissionProfile,
    cwd: &Path,
) -> PermissionProfile

作用：把一个新的权限配置转换成旧接口也能使用的权限配置。如果原配置本来就能直接转换成旧格式，它就不改；如果不能，它会做一个尽量等价、但旧系统能理解的替代版本。

数据流：进去的是一个 PermissionProfile 和当前工作目录 cwd。它先调用 to_legacy_sandbox_policy 检查能不能直接投影成旧权限；能的话就 clone 一份返回。不能的话，它读取文件系统权限和网络权限，找出当前工作目录以外仍然允许写入的目录，再检查 TMPDIR 环境变量指向的临时目录和固定的 /tmp 是否可写。最后把这些信息交给 workspace_write_with，产出一个旧格式可接受的新 PermissionProfile。

调用关系：它在权限下发前充当“翻译员”。turn_permissions_overrides 会调用它，把用户或系统给出的权限改造成老接口可接收的形状。它自己会借助 PermissionProfile 上的 file_system_sandbox_policy、network_sandbox_policy、to_legacy_sandbox_policy 和 workspace_write_with 来完成判断和重建。测试函数 tests::compatibility_profile_preserves_unbridgeable_write_roots 也会调用它，确认它没有丢掉额外的可写目录。

调用图：调用 5 个内部函数（file_system_sandbox_policy, network_sandbox_policy, to_legacy_sandbox_policy, workspace_write_with, from_absolute_path）；被 2 处调用（turn_permissions_overrides, compatibility_profile_preserves_unbridgeable_write_roots）；外部调用 3 个（new, clone, var_os）。

fn compatibility_profile_preserves_unbridgeable_write_roots()

作用：这是一个测试，用来确认兼容转换不会把旧格式不好表达的额外可写目录弄丢。换句话说，它检查这个“翻译员”有没有漏翻重要权限。

数据流：它先造出一个场景：当前目录是 /workspace/project，另一个允许写入的目录是 /workspace/extra，根目录只允许读取。然后把这个权限配置交给 legacy_compatible_permission_profile。得到兼容配置后，它再转成旧权限格式，取出可写目录列表，最后用 assert_eq! 检查结果必须包含额外目录和当前工作目录。

调用关系：它只在测试运行时生效，不参与正常程序流程。它直接调用 legacy_compatible_permission_profile，模拟真实的权限转换过程，并用断言保护这个文件最关键的行为：为了兼容旧接口而重建权限时，不能丢失原本允许写入的额外路径。

调用图：调用 2 个内部函数（legacy_compatible_permission_profile, try_from）；外部调用 2 个（assert_eq!, vec!）。

fn add_dir_warning_message(
    additional_dirs: &[PathBuf],
    permission_profile: &PermissionProfile,
    cwd: &std::path::Path,
) -> Option<String>

作用：判断用户传入的额外可写目录会不会因为当前权限设置而被忽略；如果会，就返回一条给用户看的警告。这样用户不会误以为 --add-dir 已经生效。

数据流：输入是一组额外目录、当前权限档案，以及当前工作目录。它先检查目录列表是不是空的，再检查权限是不是完全开放或由外部系统接管，然后读取文件系统沙盒策略，看是否已有足够写权限；如果这些检查都说明没问题，就返回 None，表示不用提醒；如果额外目录会被忽略，就调用 format_warning 拼出警告文字并返回。

调用关系：它是这份文件的核心判断函数。启动流程里的 run_main 会用它决定是否向用户显示警告；测试里的 warns_for_read_only 会验证只读权限下确实会报警。它自己不负责打印，只负责把该不该提醒、提醒什么算出来；真正拼文字的活交给 format_warning。

调用图：调用 2 个内部函数（file_system_sandbox_policy, format_warning）；被 2 处调用（warns_for_read_only, run_main）；外部调用 2 个（is_empty, matches!）。

fn format_warning(additional_dirs: &[PathBuf]) -> String

作用：把一组额外目录变成一段完整、可读的警告信息。它让用户明确知道哪些 --add-dir 被忽略，以及应该切换到什么权限模式。

数据流：输入是一组路径。它把每个路径转成适合显示的文字，用逗号连起来，然后塞进固定的英文提示模板里；输出是一整条警告字符串，不改动任何外部状态。

调用关系：它是 add_dir_warning_message 的小帮手。前面的权限判断确认需要警告后，才会把目录列表交给它来整理成最终要展示给用户的话。

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

fn returns_none_for_workspace_write()

作用：测试“工作区可写”权限下不会出现警告。因为这种模式本来就允许在工作区内写文件，额外目录不应该被误判为无效。

数据流：测试里准备一个 workspace-write 权限档案和一个额外目录，再把结果拿去和 None 比较。期望结果是没有警告，也就是函数不要多嘴提醒。

调用关系：它由 Rust 的测试运行器执行。它通过构造 workspace_write 权限、创建目录列表，并用 assert_eq! 做比较，守住“正常可写时不报警”这条规则。

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

fn returns_none_for_danger_full_access()

作用：测试完全开放权限下不会出现警告。因为这种模式已经允许程序访问磁盘，额外目录限制就不是问题。

数据流：测试准备一个 Disabled 权限档案，这里表示沙盒限制关闭，再准备一个额外目录。检查结果应为 None，也就是没有警告文字产生。

调用关系：它由测试运行器调用，主要用断言确认完全开放场景不会被误报。它保护的是“权限足够大时不要吓用户”这个行为。

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

fn returns_none_for_external_sandbox()

作用：测试外部沙盒接管权限时不会出现这个文件生成的警告。因为这种情况下权限规则由外部系统决定，本文件不该擅自判断 --add-dir 无效。

数据流：测试构造一个 External 权限档案，并设置网络沙盒状态，再准备一个额外目录。最后检查返回值是 None，表示本地逻辑不发警告。

调用关系：它由测试运行器执行，通过断言确保外部沙盒模式被跳过。这样 add_dir_warning_message 不会在自己无法完整判断的场景里给出误导信息。

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

fn warns_for_read_only()

作用：测试只读权限下会正确报警。只读模式不允许添加额外可写根目录，所以用户传 --add-dir 时必须被提醒。

数据流：测试创建只读权限档案，准备一个相对路径和一个绝对路径，然后调用 add_dir_warning_message。它期望拿到一条完整警告，并用断言确认文字里列出了这些目录，还说明应切换到 workspace-write 或 danger-full-access。

调用关系：它由测试运行器执行，是核心报警路径的直接验证者。它把只读场景交给 add_dir_warning_message，再检查返回的警告是否正好符合预期。

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

fn warns_when_profile_can_write_elsewhere_but_not_cwd()

作用：测试一种容易搞混的情况：权限允许写别的地方，但不允许写当前项目目录时，仍然要报警。这样可以避免用户以为“有某处可写”就等于额外目录会生效。

数据流：测试手工搭出一个受管理的权限档案：根目录只读，只有 /tmp/writable 可写；当前工作目录却是 /tmp/project。再传入 /tmp/extra 作为额外目录，期望得到警告字符串，说明这些额外可写根目录不会被接受。

调用关系：它由测试运行器调用，用较复杂的权限组合覆盖边界情况。它确保核心判断不是简单看“有没有任何可写目录”，而是要看当前有效权限是否真的支持额外可写根。

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

fn returns_none_when_no_additional_dirs()

作用：测试用户没有传任何额外目录时不会报警。没有 --add-dir，就没有什么会被忽略，也就不该打扰用户。

数据流：测试创建只读权限档案，但额外目录列表是空的。它检查结果是 None，表示即使权限严格，只要用户没请求额外目录，就不生成警告。

调用关系：它由测试运行器执行，守住函数最前面的快速退出逻辑。这个测试防止程序在没有问题时也显示无意义警告。

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

fn cap_sid_file(codex_home: &Path) -> PathBuf

作用：算出保存能力 SID 的文件位置。调用者只要给它 Codex 的家目录，它就告诉你那份权限身份记录应该放在哪里。

数据流：进去的是 codex_home 这个目录路径；它在后面拼上固定文件名 cap_sid；出来的是完整文件路径，比如“某个家目录/cap_sid”。它不读写磁盘，只负责算路径。

调用关系：这是很多流程的第一步。load_or_create_cap_sids 用它找到要读写的记录文件，workspace_cap_sid_for_cwd 和 writable_root_cap_sid_for_path 用它知道更新后该存回哪里，外部的权限拒绝逻辑也会通过它定位同一份 SID 记录。

调用图：被 4 处调用（apply_capability_denies_for_world_writable_for_permissions, load_or_create_cap_sids, workspace_cap_sid_for_cwd, writable_root_cap_sid_for_path）；外部调用 1 个（join）。

fn make_random_cap_sid_string() -> String

作用：生成一个新的随机能力 SID 字符串。它像是给沙箱发一张新的随机身份牌，避免和别的沙箱身份混在一起。

数据流：进去没有业务输入；它从随机数生成器拿 4 个随机数字，再拼成 Windows SID 形式的字符串；出来是一段类似 S-1-5-21-... 的身份编号。它不保存结果，只负责制造新编号。

调用关系：当 load_or_create_cap_sids 发现还没有身份记录，或者 workspace_cap_sid_for_cwd、writable_root_cap_sid_for_path 发现某个路径还没有专属 SID 时，就会叫它生成一个新的。生成后通常会交给 persist_caps 保存。

调用图：被 3 处调用（load_or_create_cap_sids, workspace_cap_sid_for_cwd, writable_root_cap_sid_for_path）；外部调用 2 个（from_entropy, format!）。

fn persist_caps(path: &Path, caps: &CapSids) -> Result<()>

作用：把当前的能力 SID 列表写进磁盘文件。这样程序重启后还能记得以前给哪些目录发过哪些身份牌。

数据流：进去的是目标文件路径和 CapSids 这包数据；它先确保父目录存在，再把数据转成 JSON 文本，最后写入文件；出来是成功或错误结果，同时磁盘上的 cap_sid 文件会被创建或覆盖。

调用关系：它是保存环节。load_or_create_cap_sids 在新建或升级旧格式时会用它，workspace_cap_sid_for_cwd 和 writable_root_cap_sid_for_path 在新增某个路径 SID 后也会用它把变化落盘。

调用图：被 3 处调用（load_or_create_cap_sids, workspace_cap_sid_for_cwd, writable_root_cap_sid_for_path）；外部调用 4 个（parent, create_dir_all, write, to_string）。

fn load_or_create_cap_sids(codex_home: &Path) -> Result<CapSids>

作用：读取已有的能力 SID；如果没有，就创建一套新的并保存。它保证沙箱权限身份有一个稳定来源。

数据流：进去的是 codex_home；它先通过 cap_sid_file 找到记录文件。如果文件存在，就尝试读取 JSON 格式的 CapSids；如果发现是旧版的单个 SID 文本，就把它升级成新版结构并补上只读 SID；如果文件不存在或内容不可用，就生成全新的 workspace 和 readonly SID。出来是一份 CapSids，同时必要时会把新数据写回磁盘。

调用关系：这是权限准备流程的核心入口之一。很多外部流程会先调用它拿到 SID，比如 Windows 沙箱启动、提升权限启动准备、旧版会话安全准备，以及针对全局可写目录的拒绝规则。它内部会调用 cap_sid_file、make_random_cap_sid_string 和 persist_caps。

调用图：调用 3 个内部函数（cap_sid_file, make_random_cap_sid_string, persist_caps）；被 9 处调用（apply_capability_denies_for_world_writable_for_permissions, equivalent_cwd_spellings_share_workspace_sid_key, write_roots_get_path_scoped_sids, workspace_cap_sid_for_cwd, writable_root_cap_sid_for_path, run_windows_sandbox_capture_for_permission_profile, prepare_elevated_spawn_context_for_permissions, prepare_legacy_session_security, root_capability_sids_only_include_active_roots）；外部调用 2 个（new, read_to_string）。

fn workspace_cap_sid_for_cwd(codex_home: &Path, cwd: &Path) -> Result<String>

作用：拿到某个工作区目录专属的写入能力 SID。它确保同一个工作区无论路径写法怎么变，都拿到同一张身份牌。

数据流：进去的是 codex_home 和当前工作目录 cwd；它先读取或创建总的 CapSids，再把 cwd 规范化成统一钥匙。如果表里已有 SID，就直接返回；如果没有，就生成新的 SID，放进 workspace_by_cwd，并保存到磁盘。出来是这个工作区对应的 SID。

调用关系：workspace_write_cap_sid_for_root 在判断写入根目录就是工作区本身时会用它。测试 equivalent_cwd_spellings_share_workspace_sid_key 也专门验证它不会被大小写或斜杠写法骗到。它把路径规范化交给 canonical_path_key，把保存交给 persist_caps。

调用图：调用 5 个内部函数（cap_sid_file, load_or_create_cap_sids, make_random_cap_sid_string, persist_caps, canonical_path_key）；被 2 处调用（equivalent_cwd_spellings_share_workspace_sid_key, workspace_write_cap_sid_for_root）。

fn writable_root_cap_sid_for_path(codex_home: &Path, root: &Path) -> Result<String>

作用：拿到某个额外可写根目录专属的能力 SID。它把“工作区本身”和“额外允许写的目录”分开，避免权限串门。

数据流：进去的是 codex_home 和额外可写目录 root；它读取或创建 CapSids，把 root 规范化成统一钥匙。已有记录就返回已有 SID；没有记录就生成新 SID，写入 writable_root_by_path，并保存。出来是这个可写根目录对应的 SID。

调用关系：workspace_write_cap_sid_for_root 在发现目标根目录不是当前工作区时会调用它。测试 write_roots_get_path_scoped_sids 会检查它确实给额外根目录分配了不同于工作区的 SID。

调用图：调用 5 个内部函数（cap_sid_file, load_or_create_cap_sids, make_random_cap_sid_string, persist_caps, canonical_path_key）；被 1 处调用（workspace_write_cap_sid_for_root）。

fn workspace_write_cap_sid_for_root(
    codex_home: &Path,
    cwd: &Path,
    root: &Path,
) -> Result<String>

作用：根据一个可写根目录到底是不是当前工作区，选出该用哪种 SID。它是“给这个写入范围挑身份牌”的分流口。

数据流：进去的是 codex_home、当前工作区 cwd、待授权的写入根目录 root；它把 cwd 和 root 都规范化后比较。如果两个其实是同一个目录，就返回工作区 SID；否则返回额外可写根目录 SID。出来是应该放进写入权限里的那一个 SID。

调用关系：权限构建逻辑 root_capability_sids 会用它收集当前可写根目录需要的 SID；一些测试也用它确认只包含当前活跃根目录、嵌套路径拒绝规则不会误放权。它自己把具体取 SID 的工作交给 workspace_cap_sid_for_cwd 或 writable_root_cap_sid_for_path。

调用图：调用 3 个内部函数（workspace_cap_sid_for_cwd, writable_root_cap_sid_for_path, canonical_path_key）；被 4 处调用（write_roots_get_path_scoped_sids, root_capability_sids, legacy_deny_path_includes_nested_active_root_sid, root_capability_sids_only_include_active_roots）。

fn workspace_write_root_contains_path(root: &Path, path: &Path) -> bool

作用：判断一个可写根目录是否包含某个路径。简单说，就是看“这个文件或目录是不是在允许写的范围里面”。

数据流：进去的是 root 和 path 两个路径；它先把两者都规范化，消除大小写、斜杠等写法差异，再检查 path 是否以 root 开头；出来是 true 或 false。

调用关系：它被 workspace_write_root_overlaps_path 使用，作为判断两个路径有没有包含关系的基础小零件。它依赖 canonicalize_path 来避免路径写法不同导致误判。

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

fn workspace_write_root_overlaps_path(root: &Path, path: &Path) -> bool

作用：判断一个可写根目录和另一个路径是否有重叠。重叠的意思是：要么根目录包含它，要么它反过来包含根目录。

数据流：进去的是 root 和 path；它分别检查 root 是否包含 path，以及 path 是否包含 root；只要有一个方向成立，出来就是 true，否则是 false。它不改动任何数据。

调用关系：它把判断工作交给 workspace_write_root_contains_path 做两次。这个函数适合用在权限规则里，判断两个目录范围会不会互相影响。

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

fn workspace_write_root_specificity(root: &Path) -> usize

作用：计算一个可写根目录有多“具体”。路径层级越深，通常越具体，比如 C:\a\b 比 C:\a 更具体。

数据流：进去的是 root 路径；它先规范化路径，再数路径里有多少个组成部分；出来是一个数字，数字越大表示路径越深、范围通常越窄。

调用关系：它是给权限选择或排序用的小工具。虽然这里没有显示调用者，但它通常用于在多个根目录里判断谁更精确，避免宽范围规则盖过窄范围规则。

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

fn equivalent_cwd_spellings_share_workspace_sid_key()

作用：测试同一个工作区用不同写法表示时，会不会拿到同一个工作区 SID。它防止因为大小写或斜杠不同而重复创建权限身份。

数据流：进去是测试临时创建的一组目录；它建立一个临时 codex_home 和工作区，把工作区路径变成一种标准写法，再造一个大小写和斜杠不同的写法。然后分别调用 workspace_cap_sid_for_cwd，比较两个结果是否相同，并读取 CapSids 确认只存了一条工作区记录。出来是测试通过或失败。

调用关系：这是 workspace_cap_sid_for_cwd 和 load_or_create_cap_sids 的安全网。它模拟真实用户可能用不同路径写法进入同一目录的情况，确认 canonical_path_key 的规范化确实起作用。

调用图：调用 2 个内部函数（load_or_create_cap_sids, workspace_cap_sid_for_cwd）；外部调用 5 个（from, assert_eq!, canonicalize, create_dir_all, tempdir）。

fn write_roots_get_path_scoped_sids()

作用：测试工作区和额外可写目录会拿到不同 SID。它防止一个目录的写权限不小心扩大到另一个目录。

数据流：进去是测试创建的临时 codex_home、workspace 和 extra_root；它分别向 workspace_write_cap_sid_for_root 要工作区 SID 和额外根目录 SID，确认两者不同，再确认直接查询额外根目录时拿到同一个 SID。最后读取 CapSids，检查工作区表和额外根目录表各有一条记录。出来是测试通过或失败。

调用关系：这是 workspace_write_cap_sid_for_root、writable_root_cap_sid_for_path 和 load_or_create_cap_sids 的配合测试。它验证分流逻辑正确：工作区走工作区 SID，额外可写根目录走路径专属 SID。

调用图：调用 2 个内部函数（load_or_create_cap_sids, workspace_write_cap_sid_for_root）；外部调用 4 个（assert_eq!, assert_ne!, create_dir_all, tempdir）。

fn resolve_windows_deny_read_paths(
    file_system_sandbox_policy: &FileSystemSandboxPolicy,
    cwd: &AbsolutePathBuf,
) -> Result<Vec<AbsolutePathBuf>, String>

作用：这是本文件的主入口：把沙箱策略里的“禁止读取”规则变成 Windows 可以使用的绝对路径清单。调用它的人拿到这份清单后，就能去设置真正的 Windows 拒读权限。

数据流：输入是一份文件系统沙箱策略和当前工作目录。它先读取明确禁止读取的路径，转成绝对路径并去重；再读取禁止读取的通配规则，构造一个专门判断“这个路径是否该禁止读”的匹配器；接着按每条通配规则制定扫描计划，到磁盘上找已经存在且匹配的文件或目录。输出是去重后的绝对路径列表；如果通配规则本身写错，输出错误信息。

调用关系：它站在整个转换流程的最前面。它会调用策略对象的读取函数拿规则，用 push_absolute_path 放入明确路径，用 glob_scan_plan 决定从哪里扫，再把实际扫描工作交给 collect_existing_glob_matches。测试里的多个用例会直接调用它，检查通配展开、错误通配、符号链接别名等情况。

调用图：调用 8 个内部函数（get_unreadable_globs_with_cwd, get_unreadable_roots_with_cwd, restricted, try_new, as_path, collect_existing_glob_matches, glob_scan_plan, push_absolute_path）；被 3 处调用（aliased_glob_roots_each_preserve_their_lexical_matches, glob_patterns_expand_to_existing_matches, invalid_glob_patterns_fail_before_expansion）；外部调用 2 个（new, new）。

fn collect_existing_glob_matches(
    path: &Path,
    matcher: &ReadDenyMatcher,
    paths: &mut Vec<AbsolutePathBuf>,
    seen_paths: &mut HashSet<PathBuf>,
    seen_scan_dirs: &mut HashSet<PathBuf>

作用：这个函数负责在磁盘上实际走一遍目录树，找出现在已经存在、并且命中拒读通配规则的路径。它像一个带规则的文件夹搜索器。

数据流：输入是要扫描的起点路径、匹配器、结果列表、去重集合、已扫描目录集合、最大深度和当前深度。它先确认路径存在；如果匹配拒读规则，就把它加入结果；如果这是目录，就检查是否已经扫描过同一个真实目录，避免符号链接绕圈；如果还没超过深度限制，就读取目录项并递归扫描子项。输出本身是成功或错误；主要改动是往结果列表和去重集合里加入匹配路径。

调用关系：resolve_windows_deny_read_paths 在处理每条通配规则时会调用它。它自己不决定规则怎么来，只负责拿着 ReadDenyMatcher 判断路径是否该禁止读，并在命中时交给 push_absolute_path 做绝对路径整理和去重。

调用图：调用 2 个内部函数（is_read_denied, push_absolute_path）；被 1 处调用（resolve_windows_deny_read_paths）；外部调用 5 个（exists, metadata, to_path_buf, canonicalize, read_dir）。

fn push_absolute_path(
    paths: &mut Vec<AbsolutePathBuf>,
    seen: &mut HashSet<PathBuf>,
    path: PathBuf,
) -> Result<(), String>

作用：这个小工具把一个路径整理成项目认可的绝对路径，并保证同一个路径只加入一次。它避免结果里出现重复项或不规范路径。

数据流：输入是结果列表、已见过路径的集合，以及一个待加入的路径。它先用 dunce::simplified 简化路径写法，再用 AbsolutePathBuf::from_absolute_path 确认它确实是绝对路径；如果这个路径以前没加入过，就放进结果列表。输出是成功或错误；成功时可能会新增一个路径。

调用关系：它被 resolve_windows_deny_read_paths 用来加入明确拒读路径，也被 collect_existing_glob_matches 用来加入通配扫描命中的路径。也就是说，所有最终进入结果清单的路径都会经过它这道“整理和去重”的门。

调用图：调用 1 个内部函数（from_absolute_path）；被 2 处调用（collect_existing_glob_matches, resolve_windows_deny_read_paths）；外部调用 1 个（simplified）。

fn glob_scan_plan(pattern: &str, configured_max_depth: Option<usize>) -> GlobScanPlan

作用：这个函数为一条通配规则制定“从哪里开始扫、最多扫多深”的计划。这样可以少扫很多无关目录，避免为了找几个文件把整个磁盘翻一遍。

数据流：输入是一条通配字符串和可选的最大扫描深度配置。它先找到第一个通配符，比如 *、? 或 [；再取它前面最深的普通目录作为扫描根目录；最后把剩下的规则片段交给 effective_glob_scan_max_depth 算深度。输出是一个 GlobScanPlan，里面有扫描起点和最大深度。

调用关系：resolve_windows_deny_read_paths 每处理一条通配规则，都会先调用它做路线规划。它内部再调用 effective_glob_scan_max_depth，把“该扫多深”这件事单独算清楚。测试会检查它是否正确选择普通前缀目录，比如不会从盘符根目录乱扫。

调用图：调用 1 个内部函数（effective_glob_scan_max_depth）；被 1 处调用（resolve_windows_deny_read_paths）；外部调用 1 个（from）。

fn effective_glob_scan_max_depth(
    pattern_suffix: &str,
    configured_max_depth: Option<usize>,
) -> Option<usize>

作用：这个函数计算通配扫描的实际深度上限。它的目的很简单：能少扫就少扫，但遇到 ** 这种“任意层级”的规则时，也尊重外部配置的安全上限。

数据流：输入是通配规则中扫描根目录后面的那段，以及用户配置的最大深度。它把后缀按路径分隔符拆成几段；如果里面有 **，说明可能要递归很多层，就直接使用配置的最大深度；如果没有 **，它会用规则本身的层数作为天然上限，并和配置上限取更小值。输出是一个可选数字：有数字表示最多扫这么多层，没有数字表示不限制。

调用关系：它只被 glob_scan_plan 调用，是扫描计划里的深度计算零件。上层不直接关心这些细节，只拿最终的 GlobScanPlan 去扫描。

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

fn unreadable_glob_entry(pattern: String) -> FileSystemSandboxEntry

作用：这是测试用的小帮手，用来快速造一条“禁止读取某个通配模式”的沙箱规则。它让测试代码不用每次都手写同样的结构。

数据流：输入是一条通配字符串。它把这条字符串包装成 FileSystemSandboxEntry，路径类型是通配模式，访问权限是拒绝。输出是一条可放进测试策略里的拒读通配规则。

调用关系：它服务于本文件的测试用例。测试在构造沙箱策略时会用它生成规则，然后把规则交给 FileSystemSandboxPolicy::restricted，最后再检查解析结果是否符合预期。

fn unreadable_path_entry(path: PathBuf) -> FileSystemSandboxEntry

作用：这是测试用的小帮手，用来快速造一条“禁止读取某个明确路径”的沙箱规则。它主要用于测试没有通配符的情况。

数据流：输入是一个路径。它先把路径确认并包装成绝对路径，然后生成一条访问权限为拒绝的沙箱规则。输出是一条明确路径的拒读规则；如果测试传入的不是绝对路径，会在测试里直接失败。

调用关系：它被测试用例用来准备策略数据，尤其是检查“明确路径即使不存在也要保留”的场景。它调用 from_absolute_path，确保测试数据符合生产代码对绝对路径的要求。

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

fn scan_root_uses_literal_prefix_before_glob()

作用：这个测试确认通配扫描不会从太大的范围开始，而是从第一个通配符前面最深的普通目录开始。这样能避免无谓地扫描整台机器。

数据流：输入是几条典型通配规则，包括 Unix 风格路径和 Windows 盘符路径。测试调用 glob_scan_plan 得到扫描根目录，然后用断言比较它和预期目录是否一致。输出是测试通过或失败。

调用关系：它专门检查 glob_scan_plan 的根目录选择逻辑。这个逻辑会影响 resolve_windows_deny_read_paths 后续扫描的范围，所以这个测试是在保护性能和安全边界。

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

fn scan_depth_is_bounded_for_non_recursive_globs()

作用：这个测试确认普通通配规则不会无限递归扫描。比如 *.env 只该看当前层，*/*.env 只该看下一层。

数据流：输入是几条不含或含 ** 的通配规则。测试调用 glob_scan_plan，读取它算出的最大深度，然后和预期值比较。输出是测试通过或失败。

调用关系：它验证 glob_scan_plan 和 effective_glob_scan_max_depth 配合得是否正确。这个结果会直接影响 collect_existing_glob_matches 是否继续往子目录里走。

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

fn configured_depth_caps_recursive_glob_scans()

作用：这个测试确认外部配置的最大扫描深度真的会生效。它防止 ** 这种递归通配把目录扫得太深。

数据流：输入是带配置深度的通配规则。测试调用 glob_scan_plan，检查最终最大深度是否被配置值限制住。输出是测试通过或失败。

调用关系：它保护的是 effective_glob_scan_max_depth 的上限逻辑。实际运行时，resolve_windows_deny_read_paths 会把这个深度交给扫描函数，用来控制磁盘遍历范围。

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

fn exact_missing_paths_are_preserved()

作用：这个测试确认明确写出的拒读路径，即使文件现在还不存在，也会出现在最终结果里。这样后续权限设置阶段还能处理未来才会出现的敏感路径。

数据流：测试先创建临时目录，把其中一个还不存在的文件路径写进拒读策略。然后调用解析函数，检查结果是否包含这个缺失文件的绝对路径。输出是测试通过或失败。

调用关系：它覆盖 resolve_windows_deny_read_paths 处理明确路径的分支，也间接覆盖 push_absolute_path 的路径整理行为。它说明明确路径和通配路径不一样：明确路径不需要磁盘上已经存在。

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

fn glob_patterns_expand_to_existing_matches()

作用：这个测试确认通配规则会展开成磁盘上真实存在的匹配文件。比如规则写所有 .env，结果就应该包含当前已有的 .env 文件，而不是普通文本文件。

数据流：测试创建临时目录、根目录下的 .env、子目录里的 .env 和一个不该匹配的 notes.txt。然后构造 **/*.env 拒读规则，调用 resolve_windows_deny_read_paths，把结果转成集合后和预期集合比较。输出是测试通过或失败。

调用关系：它直接验证主流程：策略读取、匹配器创建、glob_scan_plan 规划、collect_existing_glob_matches 扫描，以及 push_absolute_path 加入结果。它是通配展开功能的核心测试之一。

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

fn invalid_glob_patterns_fail_before_expansion()

作用：这个测试确认通配规则如果写错，会在扫描磁盘前就报错。这样可以尽早告诉调用者规则不合法，而不是悄悄忽略或得到奇怪结果。

数据流：测试构造一个非法通配规则，比如字符范围 [z-a]。然后调用 resolve_windows_deny_read_paths，期待它返回错误，并检查错误信息里包含“非法拒读通配”和具体的范围错误。输出是测试通过或失败。

调用关系：它验证 resolve_windows_deny_read_paths 在创建 ReadDenyMatcher::try_new 时会正确拦截坏规则。这个测试保证后面的 collect_existing_glob_matches 不会拿着错误规则去扫描。

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

fn non_recursive_globs_do_not_expand_nested_matches()

作用：这个测试确认不带 ** 的通配规则不会误匹配更深层目录里的文件。比如 /*.env 只能匹配根目录下的 .env，不能匹配 app/.env。

数据流：测试创建一个根目录 .env 和一个子目录 .env，再构造只匹配当前层的通配规则。然后解析结果，检查只返回根目录那个文件。输出是测试通过或失败。

调用关系：它保护的是扫描深度控制。glob_scan_plan 算出的深度会限制 collect_existing_glob_matches 递归，所以这个测试能发现扫描过深导致的错误匹配。

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

fn aliased_glob_roots_each_preserve_their_lexical_matches()

作用：这个测试确认当两个不同路径其实指向同一个目录时，结果仍保留用户写的那两个路径形式。简单说，就是两个门通向同一个房间，权限名单里仍要按两个门的名字记录。

数据流：测试创建一个真实目录和两个指向它的符号链接，再在真实目录里放一个 .env 文件。它分别对两个链接路径写通配拒读规则，调用解析函数，最后检查结果包含 alias-a/secret.env 和 alias-b/secret.env 这两个表面路径。输出是测试通过或失败。

调用关系：它验证 collect_existing_glob_matches 的一个细节：扫描时用规范化后的真实目录防止循环，但加入结果时保留原始路径写法。它通过 resolve_windows_deny_read_paths 走完整流程，并依赖符号链接创建来模拟目录别名。

调用图：调用 3 个内部函数（restricted, from_absolute_path, resolve_windows_deny_read_paths）；外部调用 6 个（new, assert_eq!, create_dir_all, write, symlink, vec!）。

fn token_mode_for_permission_profile(
    permission_profile: &PermissionProfile,
    workspace_roots: &[AbsolutePathBuf],
    cwd: &Path,
    env_map: &HashMap<String, String>,
) -> Result<WindowsSan

作用：根据一份权限档案判断 Windows 沙箱该用哪类受限令牌启动程序：纯只读，还是带可写目录能力。这样后面的启动代码就知道要给子进程发哪种“通行证”。

数据流：输入是一份权限档案、工作区根目录列表、当前目录和环境变量表。它先把权限档案解析成 Windows 可用的权限；如果发现要求全盘写入，就直接报错，因为 Windows 沙箱无法安全执行；然后查看当前目录下有没有可写根目录，有就输出 WritableRootsCapability，没有就输出 ReadOnlyCapability。

调用关系：它先把实际解析工作交给 ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots。测试 token_mode_for_profile_with_writable_roots_uses_write_capabilities、token_mode_for_profile_without_writable_roots_uses_readonly_capability 和 token_mode_rejects_full_disk_write_entries 用它来确认令牌选择和错误拒绝是否正确。

调用图：调用 1 个内部函数（try_from_permission_profile_for_workspace_roots）；被 3 处调用（token_mode_for_profile_with_writable_roots_uses_write_capabilities, token_mode_for_profile_without_writable_roots_uses_readonly_capability, token_mode_rejects_full_disk_write_entries）；外部调用 1 个（bail!）。

fn try_from_permission_profile(permission_profile: &PermissionProfile) -> Result<Self>

作用：把通用权限档案转换成 Windows 本地沙箱权限对象。它只接受“受管理且受限制”的权限，因为只有这种权限 Windows 沙箱能可靠执行。

数据流：输入是一份 PermissionProfile。它先检查这份档案是不是 Managed（受管理的权限方案），再调用 to_runtime_permissions 得到运行时的文件系统规则和网络规则；如果文件系统不是 Restricted（受限制模式），就报错；成功时输出 ResolvedWindowsSandboxPermissions。

调用关系：这是最基础的转换入口。ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots 会在它的基础上继续展开工作区根目录；多个测试用它验证正常转换、拒绝禁用权限档案、拒绝不受限文件系统权限。

调用图：调用 1 个内部函数（to_runtime_permissions）；被 3 处调用（permission_profile_rejects_disabled_profiles, permission_profile_rejects_unrestricted_managed_filesystem, permission_profile_workspace_write_uses_windows_temp_env_vars）；外部调用 2 个（bail!, matches!）。

fn try_from_permission_profile_for_workspace_roots(
        permission_profile: &PermissionProfile,
        workspace_roots: &[AbsolutePathBuf],
    ) -> Result<Self>

作用：在普通解析的基础上，把“工作区根目录”这种占位说法换成运行时真正的目录路径。这样沙箱拿到的是明确的 Windows 路径，而不是抽象标签。

数据流：输入是一份权限档案和一组实际工作区根目录。它先调用 ResolvedWindowsSandboxPermissions::try_from_permission_profile 得到基础权限，再把文件系统规则里的 :workspace_roots 之类符号项展开成传入的真实路径，最后输出更新后的权限对象。

调用关系：这是很多 Windows 沙箱准备流程会用的入口，例如 run_elevated_setup、spawn_world_writable_scan、world_writable_warning_details、compute_allow_paths、run_windows_sandbox_capture_for_permission_profile 等都会在真正设置沙箱前调用它。相关测试也用它确认工作区根目录会正确展开。

调用图：被 19 处调用（run_elevated_setup, spawn_world_writable_scan, world_writable_warning_details, run_elevated_setup, compute_allow_paths, run_windows_sandbox_capture_for_permission_profile, permission_profile_workspace_root_uses_runtime_workspace_roots, permission_profile_workspace_roots_expand_all_runtime_workspace_roots, token_mode_for_permission_profile, run_setup_refresh (+9 more)）；外部调用 1 个（try_from_permission_profile）。

fn should_apply_network_block(&self) -> bool

作用：判断这份权限是否要求禁用网络。外部代码可以用它决定要不要给沙箱加上“不能联网”的限制。

数据流：输入是已经解析好的权限对象。它读取里面的网络策略，调用 is_enabled 判断网络是否开启；如果网络没有开启，就输出 true，表示应该拦网络，否则输出 false。

调用关系：它是网络限制设置时的一个小查询口。它不自己修改系统网络，只把网络策略翻译成一个简单的是/否答案。

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

fn network_policy(&self) -> NetworkSandboxPolicy

作用：直接取出当前权限里的网络策略。需要完整网络规则的代码可以通过它拿到原始判断依据。

数据流：输入是权限对象本身。它读取内部保存的 network 字段，并把这个 NetworkSandboxPolicy 返回出去，不做额外加工。

调用关系：from_permissions 会调用它，把这里解析出的网络策略继续交给后续配置或执行环节。

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

fn is_enforceable_by_windows_sandbox(&self) -> bool

作用：判断这份文件系统权限是不是 Windows 沙箱能够执行的类型。简单说，就是确认它是否处在“受限制”模式。

数据流：输入是权限对象。它查看 file_system.kind，如果是 Restricted 就输出 true，否则输出 false。

调用关系：apply_capability_denies_for_world_writable_for_permissions 会用它先做把关：只有 Windows 沙箱能执行的权限，才继续应用后面的能力限制。

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

fn has_full_disk_read_access(&self) -> bool

作用：判断这份权限是否允许读取整个磁盘。后续收集可读目录时，需要知道是不是已经拥有全盘读取能力。

数据流：输入是权限对象。它把问题转交给内部的文件系统策略，得到一个布尔值：允许全盘读就是 true，否则是 false。

调用关系：gather_read_roots 会调用它。如果已经全盘可读，后续可能就不需要再逐个列很多可读目录。

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

fn include_platform_defaults(&self) -> bool

作用：判断是否要自动加入平台默认可读路径。比如系统运行常常需要读一些 Windows 基础目录，这个函数告诉后续流程要不要加上。

数据流：输入是权限对象。它读取内部文件系统策略里的默认路径开关，并返回 true 或 false。

调用关系：gather_read_roots 会调用它，在收集可读路径时决定是否额外加入 Windows 平台默认目录。

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

fn readable_roots_for_cwd(&self, cwd: &Path) -> Vec<PathBuf>

作用：算出在某个当前目录下，沙箱允许读取哪些根目录。它把抽象权限变成普通 PathBuf 路径，方便 Windows 侧代码使用。

数据流：输入是权限对象和当前工作目录 cwd。它调用内部文件系统策略的 get_readable_roots_with_cwd，根据 cwd 解析出可读根目录；然后把 AbsolutePathBuf 转成普通 PathBuf 列表输出。

调用关系：gather_read_roots 会调用它，把这里得到的可读目录加入最终沙箱配置。

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

fn uses_write_capabilities_for_cwd(
        &self,
        cwd: &Path,
        env_map: &HashMap<String, String>,
    ) -> bool

作用：快速判断在某个当前目录下是否需要写权限能力。它不关心具体能写哪里，只问“有没有任何可写目录”。

数据流：输入是权限对象、当前目录和环境变量表。它调用 ResolvedWindowsSandboxPermissions::writable_roots_for_cwd 算出可写根目录；如果列表非空就输出 true，否则输出 false。

调用关系：apply_capability_denies_for_world_writable_for_permissions、legacy_session_capability_roots 和 prepare_elevated_spawn_context_for_permissions 会用它决定是否走带写能力的沙箱路径。

调用图：调用 1 个内部函数（writable_roots_for_cwd）；被 3 处调用（apply_capability_denies_for_world_writable_for_permissions, legacy_session_capability_roots, prepare_elevated_spawn_context_for_permissions）。

fn writable_roots_for_cwd(
        &self,
        cwd: &Path,
        env_map: &HashMap<String, String>,
    ) -> Vec<WindowsWritableRoot>

作用：算出当前目录下真正允许写入的 Windows 目录列表，并附带这些目录里仍然只读的子路径。它是设置写权限时最关键的清单生成器。

数据流：输入是权限对象、当前目录和环境变量表。它先复制一份文件系统规则，并暂时移除特殊临时目录项，避免普通路径解析把 tmp 处理错；再调用 get_writable_roots_with_cwd 算出可写根目录；接着把路径转成 Windows 本地 PathBuf。如果原权限里有可写 Tmpdir，它还会调用 windows_temp_env_roots，从 TEMP、TMP 找到实际临时目录并追加到结果里。最后输出 WindowsWritableRoot 列表。

调用关系：compute_allow_paths_for_permissions、gather_full_read_roots_for_permissions、gather_write_roots_for_permissions 会用它生成实际允许路径；ResolvedWindowsSandboxPermissions::uses_write_capabilities_for_cwd 也靠它判断是否需要写能力。它内部会调用 ResolvedWindowsSandboxPermissions::has_writable_tmpdir_entry 和 windows_temp_env_roots。

调用图：调用 2 个内部函数（has_writable_tmpdir_entry, windows_temp_env_roots）；被 4 处调用（compute_allow_paths_for_permissions, uses_write_capabilities_for_cwd, gather_full_read_roots_for_permissions, gather_write_roots_for_permissions）；外部调用 1 个（clone）。

fn has_writable_tmpdir_entry(&self) -> bool

作用：检查权限规则里是否明确允许写入临时目录。这个判断用于决定要不要把 Windows 的 TEMP、TMP 目录加入可写列表。

数据流：输入是权限对象。它遍历文件系统规则里的每一项，寻找路径类型为 Tmpdir 且访问模式允许写入的条目；找到就输出 true，找不到就输出 false。

调用关系：它只服务于 ResolvedWindowsSandboxPermissions::writable_roots_for_cwd。后者用这个结果决定是否继续调用 windows_temp_env_roots。

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

fn windows_temp_env_roots(env_map: &HashMap<String, String>) -> Vec<PathBuf>

作用：从环境变量里找出 Windows 当前使用的临时目录。这样“允许写临时目录”不会停留在抽象说法，而是变成具体路径。

数据流：输入是一张环境变量表。它依次查看 TEMP 和 TMP：优先用传入表里的值，找不到再读系统环境变量；然后只保留绝对路径，最后输出路径列表。

调用关系：ResolvedWindowsSandboxPermissions::writable_roots_for_cwd 在发现权限允许写 Tmpdir 时调用它，把真实临时目录追加进可写根目录。

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

fn workspace_roots_for(root: &Path) -> Vec<AbsolutePathBuf>

作用：测试用的小帮手，把一个普通路径包装成测试需要的工作区根目录列表。这样每个测试不用重复写同样的转换代码。

数据流：输入是一个路径。它把这个路径转成 AbsolutePathBuf，也就是确认过的绝对路径，再放进一个只有一个元素的 Vec 列表输出。

调用关系：多个测试会调用它来准备 workspace_roots 参数，比如工作区写入、只读令牌、写令牌等测试。

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

fn permission_profile_workspace_write_uses_windows_temp_env_vars()

作用：验证“工作区可写”权限会把 Windows 临时目录也算进可写范围。否则程序可能在沙箱里无法写临时文件。

数据流：测试先创建临时工作区和临时目录，再把 TEMP、TMP 环境变量指向这个临时目录。它解析 workspace_write 权限，调用 writable_roots_for_cwd 拿到可写根目录，最后断言结果里同时包含当前工作区和临时目录。

调用关系：它调用 ResolvedWindowsSandboxPermissions::try_from_permission_profile 和权限对象的 writable_roots_for_cwd，专门覆盖 windows_temp_env_roots 参与的路径。

调用图：调用 2 个内部函数（workspace_write, try_from_permission_profile）；外部调用 5 个（new, new, assert_eq!, canonicalize, create_dir_all）。

fn permission_profile_workspace_root_uses_runtime_workspace_roots()

作用：验证权限里的“项目根目录”会使用运行时传入的工作区根目录，而不是简单使用命令当前目录。这样子目录里执行命令时，仍然能正确授权整个工作区。

数据流：测试创建一个工作区和它下面的子目录，把权限设置成允许写 project_roots。然后传入真实工作区根目录进行解析，再以子目录作为 cwd 查询可写根目录，最后断言结果是工作区根目录本身。

调用关系：它调用 tests::workspace_roots_for 准备输入，再调用 ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots 验证工作区占位符展开逻辑。

调用图：调用 1 个内部函数（try_from_permission_profile_for_workspace_roots）；外部调用 6 个（new, new, assert_eq!, create_dir_all, vec!, workspace_roots_for）。

fn permission_profile_workspace_roots_expand_all_runtime_workspace_roots()

作用：验证当有多个工作区根目录时，权限里的项目根目录、子路径和通配规则都会为每个根目录展开一份。这样多工作区场景不会漏授权或漏拒绝。

数据流：测试准备 first 和 second 两个绝对工作区根目录，并设置三类规则：允许写项目根、拒绝 .git、拒绝匹配 **/*.env 的文件。解析后，它断言内部文件系统策略被展开成对应两个根目录的六条具体规则。

调用关系：它调用 ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots，重点检查 materialize_project_roots_with_workspace_roots 的效果是否反映到最终权限对象里。

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

fn token_mode_for_profile_without_writable_roots_uses_readonly_capability()

作用：验证没有可写目录的权限档案会选择只读令牌。这样只读场景不会被错误地授予写能力。

数据流：测试创建一个工作区目录，构造 read_only 权限档案和工作区根目录，然后调用 token_mode_for_permission_profile。最后断言输出是 WindowsSandboxTokenMode::ReadOnlyCapability。

调用关系：它通过 tests::workspace_roots_for 准备工作区输入，并直接测试 token_mode_for_permission_profile 的只读分支。

调用图：调用 2 个内部函数（read_only, token_mode_for_permission_profile）；外部调用 5 个（new, new, assert_eq!, create_dir_all, workspace_roots_for）。

fn token_mode_for_profile_with_writable_roots_uses_write_capabilities()

作用：验证有可写目录的权限档案会选择带写能力的令牌。否则需要写工作区的命令会在沙箱里失败。

数据流：测试创建工作区目录，构造 workspace_write 权限档案和工作区根目录，然后调用 token_mode_for_permission_profile。最后断言输出是 WindowsSandboxTokenMode::WritableRootsCapability。

调用关系：它通过 tests::workspace_roots_for 准备输入，并覆盖 token_mode_for_permission_profile 的可写分支。

调用图：调用 2 个内部函数（workspace_write, token_mode_for_permission_profile）；外部调用 5 个（new, new, assert_eq!, create_dir_all, workspace_roots_for）。

fn permission_profile_rejects_disabled_profiles()

作用：验证禁用沙箱的权限档案不能被解析成 Windows 沙箱权限。因为“禁用”代表不受沙箱管理，不能假装可以执行限制。

数据流：测试把 PermissionProfile::Disabled 传给 ResolvedWindowsSandboxPermissions::try_from_permission_profile，期望得到错误。然后检查错误信息里包含“only managed permission profiles can be enforced”。

调用关系：它直接测试 ResolvedWindowsSandboxPermissions::try_from_permission_profile 的第一道拒绝逻辑。

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

fn permission_profile_rejects_unrestricted_managed_filesystem()

作用：验证即使权限档案是 Managed，只要文件系统是不受限制的，也不能交给 Windows 沙箱执行。因为不受限文件系统和沙箱限制目标相冲突。

数据流：测试构造一个 Managed 权限档案，其中 file_system 是 Unrestricted，network 是 Restricted。调用 ResolvedWindowsSandboxPermissions::try_from_permission_profile 后期望报错，并检查错误信息说明只支持受限制文件系统权限。

调用关系：它直接覆盖 ResolvedWindowsSandboxPermissions::try_from_permission_profile 的第二道拒绝逻辑。

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

fn token_mode_rejects_full_disk_write_entries()

作用：验证要求全盘写入的权限不会被转换成任何 Windows 沙箱令牌模式。这样可以避免给出一个看似受限、实际无法安全实现的配置。

数据流：测试创建工作区目录，构造一份允许写 Root（磁盘根）的受管理权限档案，然后调用 token_mode_for_permission_profile。它期望得到错误，并检查错误信息提到 Windows 沙箱无法执行全盘写入。

调用关系：它通过 tests::workspace_roots_for 准备工作区输入，并专门测试 token_mode_for_permission_profile 在发现全盘写入时的拒绝分支。

调用图：调用 1 个内部函数（token_mode_for_permission_profile）；外部调用 6 个（new, new, assert!, create_dir_all, vec!, workspace_roots_for）。

fn compute_allow_paths_for_permissions(
    permissions: &ResolvedWindowsSandboxPermissions,
    command_cwd: &Path,
    env_map: &HashMap<String, String>,
) -> AllowDenyPaths

作用：把已经解析好的权限配置，换算成一份“允许写”和“禁止写”的路径清单。沙箱启动前会用它决定哪些地方能被命令改动，哪些地方必须保护起来。

数据流：输入是权限对象、命令的当前目录、环境变量表。它先向权限对象询问当前目录下有哪些可写根目录，再把存在的根目录加入 allow；同时把这些根目录里被标记为只读的子路径，如果确实存在，就加入 deny。输出是 AllowDenyPaths，不直接改文件系统，只产出路径名单。

调用关系：它是这个文件的核心函数。上游会在构建沙箱写入限制、套用旧版会话访问规则、计算旧版会话能力根目录、准备提权启动上下文时调用它；测试里的 tests::compute_allow_paths 也会调用它。它把“具体哪些根目录可写”的判断交给 writable_roots_for_cwd，并用 canonicalize 尽量统一路径写法。

调用图：调用 1 个内部函数（writable_roots_for_cwd）；被 5 处调用（compute_allow_paths, build_payload_deny_write_paths, apply_legacy_session_acl_rules, legacy_session_capability_roots, prepare_elevated_spawn_context_for_permissions）；外部调用 2 个（new, canonicalize）。

fn workspace_write_profile(
        writable_roots: &[AbsolutePathBuf],
        exclude_tmpdir_env_var: bool,
        exclude_slash_tmp: bool,
    ) -> PermissionProfile

作用：测试用的小帮手，用来快速造出一种“工作区可写”的权限配置。这样每个测试不用重复写一大段权限创建代码。

数据流：输入是额外可写根目录，以及是否排除临时目录环境变量、是否排除 /tmp 的两个开关。它把这些参数交给 PermissionProfile::workspace_write_with，得到一个测试用的权限配置并返回。

调用关系：它只在测试里被各个测试函数调用。它负责准备测试场景的“规则纸”，后续 tests::compute_allow_paths 会把这张规则纸转换成真正的允许和禁止路径。

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

fn workspace_roots_for(root: &Path) -> Vec<AbsolutePathBuf>

作用：测试用的小帮手，把一个普通路径包装成“工作区根目录列表”。测试通常只需要一个工作区，所以它返回只含一个元素的列表。

数据流：输入是一个路径。它把这个路径转换成 AbsolutePathBuf，也就是明确表示“这是绝对路径”的类型，然后放进一个列表返回。

调用关系：它被多个测试函数调用，用来准备 ResolvedWindowsSandboxPermissions 需要的工作区根目录参数。它不参与生产代码，只让测试写起来更清楚。

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

fn compute_allow_paths(
        permission_profile: &PermissionProfile,
        workspace_roots: &[AbsolutePathBuf],
        command_cwd: &Path,
        env_map: &HashMap<String, String>,
    ) -> All

作用：测试用的包装函数，把测试里的权限配置先解析，再调用真正的 compute_allow_paths_for_permissions。它让测试能从高层权限配置开始验证最终结果。

数据流：输入是权限配置、工作区根目录、命令当前目录和环境变量。它先调用 try_from_permission_profile_for_workspace_roots 把权限配置解析成 Windows 沙箱需要的形式，再调用 compute_allow_paths_for_permissions 得到 allow 和 deny 清单并返回。

调用关系：它夹在测试用例和生产核心函数之间。各个测试函数调用它，它再把真正计算工作交给 compute_allow_paths_for_permissions。这样测试既能覆盖权限解析，也能覆盖最终路径计算。

调用图：调用 2 个内部函数（compute_allow_paths_for_permissions, try_from_permission_profile_for_workspace_roots）。

fn includes_additional_writable_roots()

作用：验证如果权限配置里额外声明了可写目录，最终 allow 清单里应该同时包含工作区和这个额外目录。

数据流：它先创建临时目录、工作区目录和额外目录，再构造带额外可写根目录的权限配置。然后调用 tests::compute_allow_paths，最后检查 allow 里有工作区和额外目录，deny 为空。

调用关系：这是一个测试用例，由 Rust 测试运行器执行。它通过 workspace_write_profile、workspace_roots_for 和 tests::compute_allow_paths 串起测试准备、权限解析和核心计算。

调用图：外部调用 8 个（new, new, assert!, create_dir_all, vec!, compute_allow_paths, workspace_roots_for, workspace_write_profile）。

fn uses_runtime_workspace_roots_for_workspace_root()

作用：验证工作区根目录来自运行时传入的 workspace_roots，而不是简单拿命令所在的子目录当根目录。

数据流：它创建一个工作区和其中的子目录，把命令当前目录设为子目录。计算后检查 allow 包含真正的工作区根目录，而不包含子目录本身；deny 为空。

调用关系：这个测试保护一个容易出错的点：命令可能在工作区的子文件夹里运行，但可写范围应该是整个工作区。它调用测试帮手生成配置和路径，再间接验证 compute_allow_paths_for_permissions。

调用图：外部调用 7 个（new, new, assert!, create_dir_all, compute_allow_paths, workspace_roots_for, workspace_write_profile）。

fn excludes_tmp_env_vars_when_requested()

作用：验证当配置要求排除 TEMP、TMP 这类临时目录环境变量时，这些目录不会被加入可写清单。

数据流：它创建工作区和临时目录，并在环境变量表里放入 TEMP 和 TMP。权限配置打开“排除临时目录环境变量”开关后，计算结果应只允许工作区，不允许临时目录，deny 为空。

调用关系：这个测试关注环境变量对沙箱可写路径的影响。它把环境变量传给 tests::compute_allow_paths，最终由权限解析和 compute_allow_paths_for_permissions 共同决定哪些路径进入 allow。

调用图：外部调用 7 个（new, new, assert!, create_dir_all, compute_allow_paths, workspace_roots_for, workspace_write_profile）。

fn includes_tmp_env_vars_when_requested()

作用：验证当配置允许使用 TEMP、TMP 环境变量时，临时目录会被加入可写清单。

数据流：它创建工作区和临时目录，把 TEMP、TMP 都指向该临时目录。权限配置不排除这些环境变量，计算后期望 allow 正好包含工作区和临时目录，deny 为空。

调用关系：这个测试和 tests::excludes_tmp_env_vars_when_requested 是一对反向检查。它调用同样的测试帮手，但用不同开关确认临时目录是否按配置进入 allow。

调用图：外部调用 9 个（new, new, assert!, assert_eq!, canonicalize, create_dir_all, compute_allow_paths, workspace_roots_for, workspace_write_profile）。

fn ignores_unix_slash_tmp_for_windows_allow_roots()

作用：验证 Windows 沙箱计算可写路径时，不会把 Unix 系统常见的 /tmp 当成 Windows 上要允许的目录。

数据流：它只创建一个工作区，并把配置设成不排除 /tmp。计算后仍然只期望 allow 包含工作区，deny 为空，说明 /tmp 没有被误加进 Windows 路径清单。

调用关系：这个测试防止跨平台规则误伤 Windows。它通过 tests::compute_allow_paths 间接检查 compute_allow_paths_for_permissions 和权限解析在 Windows 语境下的行为。

调用图：外部调用 9 个（new, new, assert!, assert_eq!, canonicalize, create_dir_all, compute_allow_paths, workspace_roots_for, workspace_write_profile）。

fn denies_git_dir_inside_writable_root()

作用：验证工作区虽然整体可写，但里面真实存在的 .git 目录会被放进禁止写清单，避免破坏版本库元数据。

数据流：它创建工作区和其中的 .git 目录。计算后期望 allow 包含工作区，同时 deny 包含 .git 目录。

调用关系：这个测试检查“可写根目录里的受保护子目录”机制。它先用测试帮手得到路径结果，再和预期的 allow、deny 集合比较，间接保护 compute_allow_paths_for_permissions 的过滤行为。

调用图：外部调用 8 个（new, new, assert_eq!, canonicalize, create_dir_all, compute_allow_paths, workspace_roots_for, workspace_write_profile）。

fn denies_git_file_inside_writable_root()

作用：验证 .git 即使是文件而不是目录，也会被禁止写入。某些 Git worktree 场景里 .git 就是一个指向真实目录的文件。

数据流：它创建工作区，并写入一个名为 .git 的文件。计算后期望 allow 包含工作区，deny 包含这个 .git 文件。

调用关系：这个测试补上 .git 文件形态的情况，避免只保护 .git 目录而漏掉 worktree。它调用 tests::compute_allow_paths，最终验证核心计算产出的 deny 清单。

调用图：外部调用 9 个（new, new, assert_eq!, canonicalize, create_dir_all, write, compute_allow_paths, workspace_roots_for, workspace_write_profile）。

fn denies_codex_and_agents_inside_writable_root()

作用：验证工作区里的 .codex 和 .agents 目录会被禁止写入，避免命令改动工具自身或代理相关的敏感配置。

数据流：它创建工作区，以及 .codex、.agents 两个目录。计算后期望 allow 只有工作区，deny 包含这两个受保护目录。

调用关系：这个测试和 .git 相关测试类似，关注受保护子路径。它通过测试帮手走完整权限解析和路径计算流程，确认敏感目录会进入 deny。

调用图：外部调用 8 个（new, new, assert_eq!, canonicalize, create_dir_all, compute_allow_paths, workspace_roots_for, workspace_write_profile）。

fn skips_protected_subdirs_when_missing()

作用：验证如果 .git、.codex、.agents 这类受保护子路径根本不存在，就不会凭空加入 deny 清单。

数据流：它只创建工作区，不创建任何受保护子目录。计算后检查 allow 只有一个路径，deny 为空。

调用关系：这个测试对应 compute_allow_paths_for_permissions 里“只加入存在路径”的规则。它防止系统把不存在的路径也写进禁止名单，造成不必要或混乱的沙箱规则。

调用图：外部调用 8 个（new, new, assert!, assert_eq!, create_dir_all, compute_allow_paths, workspace_roots_for, workspace_write_profile）。

fn from_config(config: &Config) -> WindowsSandboxLevel

作用：从完整配置里判断当前 Windows 沙盒应该处于什么等级。有人会用它来把用户写的设置变成程序内部能直接判断的状态。

数据流：进去的是一份 Config 配置；它先看用户是否明确写了 Windows 沙盒模式，如果写了 elevated 就返回高权限沙盒，如果写了 unelevated 就返回受限令牌沙盒；如果没写，就继续看功能开关；出来的是一个 WindowsSandboxLevel。

调用关系：它是配置判断的第一站。windows_sandbox_level_from_config 会调用它；当配置里没有明确模式时，它会把判断交给 WindowsSandboxLevel::from_features。

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

fn from_features(features: &Features) -> WindowsSandboxLevel

作用：只根据功能开关判断 Windows 沙盒等级。它用于没有明确配置时，按实验功能或默认开关来决定走哪条路。

数据流：进去的是 Features 功能开关集合；它先问 elevated 沙盒开关有没有打开，再问普通 Windows 沙盒开关有没有打开；最后输出 elevated、restricted token 或 disabled 三种结果之一。

调用关系：它被 WindowsSandboxLevel::from_config 作为后备判断使用，也被 windows_sandbox_level_from_features 包一层给外部调用。它依赖 Features 的 enabled 方法查询具体开关。

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

fn windows_sandbox_level_from_config(config: &Config) -> WindowsSandboxLevel

作用：这是一个小包装函数，让别的代码不用直接调用 trait 方法，也能从配置得到沙盒等级。

数据流：进去的是 Config；它原样交给 WindowsSandboxLevel::from_config；出来的是判断好的 WindowsSandboxLevel，不额外改动配置。

调用关系：它像一个门面入口，把外部调用引到 WindowsSandboxLevel::from_config，方便调用方少知道一点内部写法。

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

fn windows_sandbox_level_from_features(features: &Features) -> WindowsSandboxLevel

作用：这是另一个小包装函数，用来从功能开关直接得到 Windows 沙盒等级。

数据流：进去的是 Features；它交给 WindowsSandboxLevel::from_features 查询开关；出来的是对应的沙盒等级。

调用关系：它把外部调用转给 WindowsSandboxLevel::from_features，适合只有功能开关、还没有完整配置的场景。

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

fn resolve_windows_sandbox_mode(cfg: &ConfigToml) -> Option<WindowsSandboxModeToml>

作用：读取配置文件里的 Windows 沙盒模式，并兼容老版本配置。没有它，老用户以前写的沙盒开关可能升级后就不生效了。

数据流：进去的是 ConfigToml，也就是从配置文件读出的原始设置；它先找新的 windows.sandbox 字段，找不到再去旧的 features 开关里推断；出来的是可选的 WindowsSandboxModeToml，有就表示用户或旧配置指定了模式。

调用关系：它在 load_config_with_layer_stack 加载配置时被调用，是配置从“文件文字”变成“程序决定”的一环。找不到新字段时，它会交给 legacy_windows_sandbox_mode 处理旧写法。

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

fn resolve_windows_sandbox_private_desktop(cfg: &ConfigToml) -> bool

作用：决定 Windows 沙盒是否使用 private desktop，也就是一个更隔离的桌面环境。它给这个选项提供默认值，避免配置缺失时行为不确定。

数据流：进去的是 ConfigToml；它读取 windows.sandbox_private_desktop，如果用户写了就用用户的值，如果没写就默认 true；出来的是一个布尔值。

调用关系：它同样在 load_config_with_layer_stack 加载配置时被调用，负责把这个 Windows 专属选项补成明确的 true 或 false。

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

fn legacy_windows_sandbox_mode(
    features: Option<&FeaturesToml>,
) -> Option<WindowsSandboxModeToml>

作用：从老版本的 features 配置里推断 Windows 沙盒模式。它是升级兼容用的“翻译器”。

数据流：进去的是可能存在的 FeaturesToml；如果没有 features，就直接没有结果；如果有，就取出里面的开关表，再交给下一层函数判断；出来的是可选的沙盒模式。

调用关系：它被 resolve_windows_sandbox_mode 在新配置缺失时调用。它自己不细看每个开关，而是把开关表交给 legacy_windows_sandbox_mode_from_entries。

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

fn legacy_windows_sandbox_mode_from_entries(
    entries: &BTreeMap<String, bool>,
) -> Option<WindowsSandboxModeToml>

作用：根据老功能开关的名字，具体判断应该映射成哪种 Windows 沙盒模式。

数据流：进去的是一张“开关名到 true/false”的表；它先看 elevated 沙盒开关，如果开了就返回 Elevated；再看普通 Windows 沙盒开关和更早的实验开关名，如果开了就返回 Unelevated；都没有就返回 None。

调用关系：它是 legacy_windows_sandbox_mode 的实际判断核心。这样老配置名、旧实验配置名都能被统一翻译成新的配置模式。

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

fn sandbox_setup_is_complete(_codex_home: &Path) -> bool

作用：检查 elevated Windows 沙盒的准备工作是否已经做完。这样程序不用每次都重复跑昂贵或打扰用户的设置流程。

数据流：进去的是 codex_home 路径，也就是 Codex 放自己数据的目录；在 Windows 上，它把这个路径交给 Windows 沙盒库检查；在非 Windows 上，它直接返回 false；出来的是“是否已完成设置”。

调用关系：run_windows_sandbox_setup_and_persist 在 elevated 模式下会先用它检查。如果已经完成，就跳过 run_elevated_setup；如果没完成，才继续执行设置。

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

fn elevated_setup_failure_details(_err: &anyhow::Error) -> Option<(String, String)>

作用：从 elevated 沙盒设置失败的错误里提取适合记录指标的失败码和失败信息。它会清洗信息，避免把不适合当标签的内容直接上报。

数据流：进去的是 anyhow::Error 错误对象；在 Windows 上，它尝试抽出沙盒设置失败详情，再把错误码转成字符串，并清洗错误消息；在非 Windows 上返回 None；出来的是可选的“错误码、错误消息”。

调用关系：emit_windows_sandbox_setup_failure_metrics 在 elevated 模式失败时会调用它，用这些详情给失败指标加标签。它依赖底层 Windows 沙盒库的 extract_setup_failure 和 sanitize_setup_metric_tag_value。

调用图：被 1 处调用（emit_windows_sandbox_setup_failure_metrics）；外部调用 2 个（extract_setup_failure, sanitize_setup_metric_tag_value）。

fn elevated_setup_failure_metric_name(_err: &anyhow::Error) -> &'static str

作用：给 elevated 沙盒设置失败选择正确的指标名字。它把“用户取消”和“真正失败”分开统计。

数据流：进去的是错误对象；在 Windows 上，它检查错误里是否是 orchestrator helper 启动被取消，如果是就返回 canceled 指标名，否则返回 failure 指标名；在非 Windows 上调用会直接 panic，也就是程序明确报错。

调用关系：emit_windows_sandbox_setup_failure_metrics 在记录 elevated 失败计数时会调用它。它让监控数据能区分用户主动取消和系统出错。

调用图：被 1 处调用（emit_windows_sandbox_setup_failure_metrics）；外部调用 2 个（extract_setup_failure, panic!）。

fn run_elevated_setup(
    _permission_profile: &PermissionProfile,
    _workspace_roots: &[AbsolutePathBuf],
    _command_cwd: &Path,
    _env_map: &HashMap<String, String>,
    _codex_home: &Path,
)

作用：执行 elevated Windows 沙盒的正式准备工作。它把用户权限设置翻译成 Windows 沙盒库能理解的权限清单，然后启动底层设置流程。

数据流：进去的是权限方案、工作区根目录、命令工作目录、环境变量和 codex_home；在 Windows 上，它先根据权限方案和工作区生成沙盒权限，再构造设置请求交给底层库；在非 Windows 上直接返回“不支持”的错误；成功时没有额外返回值，只表示设置完成。

调用关系：run_windows_sandbox_setup_and_persist 在 elevated 模式且检测到还没设置完成时会走到它。它把上层的通用请求交给 codex_windows_sandbox::run_elevated_setup 真正执行。

调用图：调用 1 个内部函数（try_from_permission_profile_for_workspace_roots）；外部调用 3 个（bail!, run_elevated_setup, default）。

fn run_elevated_provisioning_setup(_codex_home: &Path, _real_user: &str) -> anyhow::Result<()>

作用：执行 elevated 沙盒的预配置准备，通常用于为真实用户提前准备所需环境。

数据流：进去的是 codex_home 和真实用户名；在 Windows 上，它直接交给底层 Windows 沙盒库做 provisioning setup；在非 Windows 上返回“不支持”的错误；出来是成功或失败。

调用关系：调用图显示它会被 run_elevated 使用。它是更专门的 elevated 准备入口，不负责普通沙盒判断。

调用图：被 1 处调用（run_elevated）；外部调用 2 个（bail!, run_elevated_provisioning_setup）。

fn run_legacy_setup_preflight(
    _permission_profile: &PermissionProfile,
    _workspace_roots: &[AbsolutePathBuf],
    _command_cwd: &Path,
    _env_map: &HashMap<String, String>,
    _codex_home:

作用：执行旧版、非 elevated Windows 沙盒的预检查。它在真正使用旧沙盒前确认当前权限和路径设置能不能工作。

数据流：进去的是权限方案、工作区根目录、命令目录、环境变量和 codex_home；在 Windows 上，它把这些交给旧版沙盒 preflight 检查；在非 Windows 上返回“不支持”的错误；出来是检查成功或错误。

调用关系：run_windows_sandbox_setup_and_persist 在 Unelevated 模式下会调用它。它对应旧沙盒路线，和 run_elevated_setup 是两条不同准备路径。

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

fn run_setup_refresh_with_extra_read_roots(
    _permission_profile: &PermissionProfile,
    _workspace_roots: &[AbsolutePathBuf],
    _command_cwd: &Path,
    _env_map: &HashMap<String, String>,

作用：刷新 Windows 沙盒设置，并额外允许一些只读目录。它解决的是运行中临时需要读更多文件，但又不想放开写权限的问题。

数据流：进去的是权限方案、工作区根、命令目录、环境变量、codex_home，以及额外只读目录列表；在 Windows 上，它把这些传给底层刷新函数，并标记 proxy_enforced 为 false；在非 Windows 上返回“不支持”的错误；结果是刷新成功或失败。

调用关系：调用图显示 grant_read_root_non_elevated 会用它。也就是说，当非 elevated 沙盒需要新增只读访问范围时，会通过它更新底层设置。

调用图：被 1 处调用（grant_read_root_non_elevated）；外部调用 2 个（bail!, run_setup_refresh_with_extra_read_roots）。

async fn run_windows_sandbox_setup(request: WindowsSandboxSetupRequest) -> anyhow::Result<()>

作用：这是对外的 Windows 沙盒设置总入口。它负责计时、执行设置、成功或失败后记录指标。

数据流：进去的是 WindowsSandboxSetupRequest，里面装着模式、权限、目录和环境变量；它记录开始时间，取得 originator，也就是这次操作来自哪里，再清洗成适合指标标签的字符串；然后调用真正执行和保存配置的函数；成功就记录成功指标并返回 Ok，失败就记录失败指标并把错误原样返回。

调用关系：它被 windows_sandbox_setup_start_inner 调用，是用户触发沙盒设置后的主流程入口。它把实际工作交给 run_windows_sandbox_setup_and_persist，并根据结果分别调用成功或失败的埋点函数。

调用图：调用 4 个内部函数（emit_windows_sandbox_setup_failure_metrics, emit_windows_sandbox_setup_success_metrics, run_windows_sandbox_setup_and_persist, originator）；被 1 处调用（windows_sandbox_setup_start_inner）；外部调用 2 个（now, sanitize_metric_tag_value）。

async fn run_windows_sandbox_setup_and_persist(
    request: WindowsSandboxSetupRequest,
) -> anyhow::Result<()>

作用：真正执行 Windows 沙盒设置，并在成功后把选择的模式写回配置文件。它保证“做完设置”和“记住设置”连在一起。

数据流：进去的是设置请求；它拆出模式、权限、目录、环境变量等信息，然后用 spawn_blocking 把可能阻塞的 Windows 设置工作放到后台线程；elevated 模式会先检查是否已完成，没完成才跑 elevated 设置，unelevated 模式会跑旧版 preflight；全部成功后，它用 ConfigEditsBuilder 写入 windows sandbox mode，并清掉旧配置键；出来是成功或带原因的错误。

调用关系：它只被 run_windows_sandbox_setup 调用，是主入口下面的实干层。它会用 windows_sandbox_setup_mode_tag 把模式变成配置里要保存的文字，并通过 ConfigEditsBuilder 完成持久化。

调用图：调用 2 个内部函数（new, windows_sandbox_setup_mode_tag）；被 1 处调用（run_windows_sandbox_setup）；外部调用 1 个（spawn_blocking）。

fn emit_windows_sandbox_setup_success_metrics(
    mode: WindowsSandboxSetupMode,
    originator_tag: &str,
    duration: std::time::Duration,
)

作用：记录 Windows 沙盒设置成功的统计数据。这样开发者能看到成功次数和耗时。

数据流：进去的是设置模式、来源标签和耗时；它先拿全局 metrics 记录器，如果没有就什么也不做；有的话，它把模式转成标签，记录一次耗时，并把成功计数加一；它不改变沙盒本身，只发送统计信息。

调用关系：run_windows_sandbox_setup 在设置成功后调用它。它会调用 windows_sandbox_setup_mode_tag 生成统一的 mode 标签，并依赖 codex_otel::global 取得指标系统。

调用图：调用 1 个内部函数（windows_sandbox_setup_mode_tag）；被 1 处调用（run_windows_sandbox_setup）；外部调用 1 个（global）。

fn emit_windows_sandbox_setup_failure_metrics(
    mode: WindowsSandboxSetupMode,
    originator_tag: &str,
    duration: std::time::Duration,
    _err: &anyhow::Error,
)

作用：记录 Windows 沙盒设置失败的统计数据。它不仅记失败次数，还会尽量区分 elevated 失败、用户取消和旧版 preflight 失败。

数据流：进去的是模式、来源标签、耗时和错误；它先拿全局 metrics 记录器，没有就退出；有的话记录失败耗时和失败计数；如果是 elevated 模式，在 Windows 上还会提取失败详情并选择更具体的指标名；如果是 unelevated 模式，则记录旧版预检查失败指标。

调用关系：run_windows_sandbox_setup 在设置失败后调用它。它会用 windows_sandbox_setup_mode_tag 生成标签；在 elevated 失败时，还会调用 elevated_setup_failure_details 和 elevated_setup_failure_metric_name。

调用图：调用 3 个内部函数（elevated_setup_failure_details, elevated_setup_failure_metric_name, windows_sandbox_setup_mode_tag）；被 1 处调用（run_windows_sandbox_setup）；外部调用 3 个（global, matches!, vec!）。

fn windows_sandbox_setup_mode_tag(mode: WindowsSandboxSetupMode) -> &'static str

作用：把内部的沙盒设置模式变成固定的小写文字标签。这个标签既用于写配置，也用于指标统计。

数据流：进去的是 WindowsSandboxSetupMode；如果是 Elevated，就输出字符串 "elevated"；如果是 Unelevated，就输出 "unelevated"；没有副作用。

调用关系：run_windows_sandbox_setup_and_persist 用它决定写回配置的值；成功和失败的指标函数也用它保证统计标签写法一致。

调用图：被 3 处调用（emit_windows_sandbox_setup_failure_metrics, emit_windows_sandbox_setup_success_metrics, run_windows_sandbox_setup_and_persist）。

fn record_user_marketplace(
    codex_home: &Path,
    marketplace_name: &str,
    update: &MarketplaceConfigUpdate<'_>,
) -> std::io::Result<()>

作用：把一个 marketplace 的信息写入用户配置文件。有人添加或更新 marketplace 来源时，会用它把这件事落到磁盘上，保证下次启动还能记得。

数据流：输入是用户配置目录、marketplace 名字，以及一包更新信息。它先拼出 config.toml 的路径，读取已有配置；如果没有文件，就从空配置开始。然后把这条 marketplace 写入配置内容，最后确保目录存在，并把新配置写回文件。

调用关系：它是写入流程的对外入口。内部先把读文件的活交给 read_or_create_document，再把改 TOML 内容的活交给 upsert_marketplace，最后自己负责创建目录和写文件。测试里会用它先准备配置，再验证删除功能。

调用图：调用 2 个内部函数（read_or_create_document, upsert_marketplace）；被 2 处调用（remove_user_marketplace_config_reports_case_mismatch, remove_user_marketplace_removes_requested_entry）；外部调用 3 个（join, create_dir_all, write）。

fn remove_user_marketplace(codex_home: &Path, marketplace_name: &str) -> std::io::Result<bool>

作用：用最简单的方式删除一个 marketplace，并只告诉调用者“删没删成功”。它适合那些不关心细节、只需要布尔结果的地方。

数据流：输入是用户配置目录和要删除的名字。它调用更详细的删除函数拿到结果，然后把“Removed”翻译成 true，把其他情况翻译成 false。它本身不直接改文件。

调用关系：它是 remove_user_marketplace_config 的简化包装。普通调用方如果只想知道是否删除成功，可以走这里；需要知道是不是大小写写错的调用方，则应直接走 remove_user_marketplace_config。

调用图：调用 1 个内部函数（remove_user_marketplace_config）；被 2 处调用（remove_user_marketplace_removes_requested_entry, remove_user_marketplace_returns_false_when_missing）。

fn remove_user_marketplace_config(
    codex_home: &Path,
    marketplace_name: &str,
) -> std::io::Result<RemoveMarketplaceConfigOutcome>

作用：从配置文件里删除指定 marketplace，并返回更细的结果：删掉了、没找到，或者名字大小写不一致。它用于需要给用户准确提示的删除场景。

数据流：输入是用户配置目录和要删的 marketplace 名。它读取 config.toml；如果文件不存在，直接返回“没找到”。如果文件内容不是合法 TOML，就报错。读成功后，它让 remove_marketplace 修改内存里的配置；只有真的删掉了，才把新配置写回磁盘。

调用关系：它是删除流程的主要入口。它负责文件读写和错误处理，把真正“在配置结构里找并删”的工作交给 remove_marketplace。remove_user_marketplace 会调用它并把详细结果压缩成 true/false，测试也直接调用它来检查大小写和内联表情况。

调用图：调用 1 个内部函数（remove_marketplace）；被 3 处调用（remove_user_marketplace, remove_user_marketplace_config_removes_inline_table_entry, remove_user_marketplace_config_reports_case_mismatch）；外部调用 4 个（join, create_dir_all, read_to_string, write）。

fn read_or_create_document(config_path: &Path) -> std::io::Result<DocumentMut>

作用：读取 config.toml，并把它变成可编辑的 TOML 文档；如果文件还不存在，就给一份空文档。这样写入流程不用自己到处判断文件有没有。

数据流：输入是配置文件路径。它尝试读文件；读到了就解析成 DocumentMut，也就是可修改的 TOML 文档。文件不存在时，它返回一个新的空文档；其他读文件错误或解析错误会变成错误返回。

调用关系：它只服务于 record_user_marketplace。record_user_marketplace 需要先拿到一份可改的配置，再交给 upsert_marketplace 写入具体内容。

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

fn upsert_marketplace(
    doc: &mut DocumentMut,
    marketplace_name: &str,
    update: &MarketplaceConfigUpdate<'_>,
)

作用：在内存里的 TOML 配置中新增或替换一个 marketplace 条目。“upsert”可以理解成“有就更新，没有就插入”。

数据流：输入是一份可编辑配置、marketplace 名字和更新信息。它先确保根部有 marketplaces 这个表；如果原来不是表，就改成表。然后建立该 marketplace 的配置项，写入更新时间、版本、来源类型、来源地址、分支名和稀疏路径，最后放到 marketplaces 下面。

调用关系：它不碰磁盘，只负责改内存里的配置结构。record_user_marketplace 先读出配置，再调用它填内容，之后再把结果写回文件。它会用 new_implicit_table 创建 TOML 里需要的隐式表。

调用图：调用 1 个内部函数（new_implicit_table）；被 1 处调用（record_user_marketplace）；外部调用 6 个（as_table_mut, Table, Value, new, Array, value）。

fn remove_marketplace(
    doc: &mut DocumentMut,
    marketplace_name: &str,
) -> RemoveMarketplaceConfigOutcome

作用：在内存里的 TOML 配置中找到并删除一个 marketplace。它还会识别“名字大小写不同但看起来是同一个”的情况，方便给用户更友好的提示。

数据流：输入是一份可编辑配置和要删除的名字。它寻找 marketplaces 区块，支持普通表和内联表两种写法；找到精确名字就删除。没找到时，它会检查是否存在大小写不同的同名项。删除后如果 marketplaces 已经空了，就把整个 marketplaces 区块也移掉。

调用关系：它是删除配置内容的核心零件，由 remove_user_marketplace_config 调用。它把大小写检查交给 case_mismatched_key，自己负责根据结果决定返回 Removed、NotFound 还是 NameCaseMismatch。

调用图：调用 1 个内部函数（case_mismatched_key）；被 1 处调用（remove_user_marketplace_config）；外部调用 1 个（as_table_mut）。

fn case_mismatched_key(
    mut keys: impl Iterator<Item = &'a str>,
    requested_name: &str,
) -> Option<String>

作用：检查一堆已有名字里，是否有一个和请求名字只差大小写。比如配置里是 debug，用户输入 Debug，它就能找出来。

数据流：输入是一串已有 key 和用户请求的名字。它逐个比较：必须不是完全一样，但忽略大小写后相同。找到就返回配置里真实的名字；找不到就返回空。

调用关系：它是 remove_marketplace 的小助手。remove_marketplace 删除失败时会调用它，判断这是“真的没有”，还是“用户大小写写错了”。

调用图：被 1 处调用（remove_marketplace）；外部调用 1 个（find）。

fn new_implicit_table() -> TomlTable

作用：创建一个 TOML 隐式表。隐式表可以理解成为了容纳子项自动出现的表，不一定要用户显式写出完整表头。

数据流：它不需要输入。它新建一个 TOML 表，并把它标记为隐式，然后返回给调用者使用。

调用关系：它服务于 upsert_marketplace。upsert_marketplace 在发现 marketplaces 不存在或需要重建时，会用它生成合适的表结构。

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

fn remove_user_marketplace_removes_requested_entry()

作用：测试删除一个已有 marketplace 时，只会删掉指定那一条，不会误删别的条目。

数据流：它先创建临时配置目录，再写入 debug 和 other 两个 marketplace。然后删除 debug，读取配置文件检查结果：删除返回 true，配置里只剩 other。

调用关系：这是删除主流程的安全网。它先借 record_user_marketplace 准备数据，再调用 remove_user_marketplace，最后用读取和解析配置文件的方式确认磁盘上的结果真的正确。

调用图：调用 2 个内部函数（record_user_marketplace, remove_user_marketplace）；外部调用 5 个（new, assert!, assert_eq!, read_to_string, from_str）。