核心配置 schema、诊断、合并和分层加载

fn default_allow_login_shell() -> Option<bool>

作用：给“是否允许使用登录 shell”这个配置项提供默认值。默认是允许，这样用户不写配置时，命令运行环境更接近普通终端。

数据流：没有输入 → 直接准备一个“是”的默认答案，并包在 Option 里表示“有默认值” → 返回 Some(true)，不会改动任何外部状态。

调用关系：它主要在读取 ConfigToml 时被 serde（把配置文本变成程序数据的库）自动使用，用来填补 allow_login_shell 没写时的空缺。

fn default_history() -> Option<History>

作用：给历史记录配置提供默认设置。用户没写 history 时，Codex 仍然知道该按默认规则保存或处理历史。

数据流：没有输入 → 调用 History 的 default 默认构造 → 返回 Some(History::default())，只是生成一份默认配置。

调用关系：它在配置反序列化时作为 history 字段的默认值来源，把具体默认规则交给 History 自己的 default 实现。

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

fn default_project_doc_max_bytes() -> Option<usize>

作用：规定项目说明文件最多读取多少字节的默认值。这样 AGENTS.md 之类的项目说明不会因为太大而把上下文撑爆。

数据流：没有输入 → 取文件顶部定义的 DEFAULT_PROJECT_DOC_MAX_BYTES 常量 → 返回 Some(32768)，也就是 32KB。

调用关系：ConfigToml 读取 project_doc_max_bytes 字段时会用到它；如果用户没写，就用这个安全上限。

fn default_project_doc_fallback_filenames() -> Option<Vec<String>>

作用：给项目说明文件的备用文件名列表提供默认值。默认没有备用名，表示只按主规则找。

数据流：没有输入 → 新建一个空的字符串列表 → 返回 Some(空列表)，不读取也不修改别的东西。

调用关系：它服务于 ConfigToml 的 project_doc_fallback_filenames 字段，让缺省状态也有明确含义：没有额外备用文件名。

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

fn default_hide_agent_reasoning() -> Option<bool>

作用：给“是否隐藏代理推理过程”提供默认值。默认不隐藏，便于界面或日志正常显示推理事件。

数据流：没有输入 → 直接给出 false → 返回 Some(false)，表示配置项没写时也有清楚的默认行为。

调用关系：读取 ConfigToml 时，如果 hide_agent_reasoning 没写，serde 会借它补上默认值。

fn default_true() -> bool

作用：提供一个通用的 true 默认值。这里用于某些实验功能的 enabled 字段，让没写 enabled 时默认开启。

数据流：没有输入 → 直接返回 true → 不产生副作用。

调用关系：它被 serde 的 default 机制调用，例如 ExperimentalRequestUserInput.enabled 没写时会用它。

fn into_vec(self) -> Vec<String>

作用：把 ChatGPT workspace 限制统一变成列表。因为配置里可能写一个 ID，也可能写多个 ID，后续代码不想分别处理两种形状。

数据流：输入一个 ForcedChatgptWorkspaceIds 枚举值 → 如果是 Single，就把单个字符串装进一个列表；如果是 Multiple，就直接拿出原列表 → 输出 Vec<String>。

调用关系：它通常在配置已经读完之后使用，把兼容旧写法的配置整理成统一格式，方便登录限制逻辑继续处理。

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

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

作用：自定义读取 forced_chatgpt_workspace_id 的规则。它允许单个字符串或 TOML 字符串列表，但故意拒绝“a,b”这种逗号拼接字符串，避免用户以为写了两个 ID，程序却当成一个 ID。

数据流：输入来自 TOML 的原始值 → 先尝试读成单个字符串或字符串列表 → 单个字符串里如果含逗号就返回清楚的报错；否则包装成 Single 或 Multiple → 输出规范化后的枚举值。

调用关系：serde 在读取 ConfigToml.forced_chatgpt_workspace_id 时调用它；它把格式判断和错误提示拦在配置入口处。

调用图：外部调用 4 个（deserialize, Multiple, Single, custom）。

fn is_trusted(&self) -> bool

作用：判断某个项目是否被用户标记为可信。可信项目通常可以使用更宽松的默认权限。

数据流：输入一个 ProjectConfig → 查看 trust_level 是否正好是 Trusted → 返回 true 或 false，不修改配置。

调用关系：它是项目信任判断的小工具；在默认权限选择流程里会被询问，例如 default_builtin_permission_profile_name 会根据这个结果决定怎么选默认权限。

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

fn is_untrusted(&self) -> bool

作用：判断某个项目是否被用户标记为不可信。不可信项目需要更保守的默认行为。

数据流：输入一个 ProjectConfig → 查看 trust_level 是否正好是 Untrusted → 返回 true 或 false，不修改配置。

调用关系：它和 is_trusted 是一对判断工具；默认权限相关流程会用它区分用户是否明确表达了“不信任这个项目”。

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

fn deserialize_optional_web_search_tool_config(
    deserializer: D,
) -> Result<Option<WebSearchToolConfig>, D::Error>

作用：读取 tools.web_search 的新旧两种写法。旧写法可能只是 true/false，新写法可以是一整段详细配置。

数据流：输入 TOML 里的 tools.web_search 值 → 如果没写，返回 None；如果是布尔值，也返回 None，相当于兼容但不再从这里启停；如果是详细配置，就返回 Some(config) → 不改动外部状态。

调用关系：serde 在读取 ToolsToml.web_search 时调用它；它把旧配置的兼容问题挡在配置解析阶段，让后续代码只面对可用的 WebSearchToolConfig 或没有配置。

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

async fn derive_permission_profile(
        &self,
        sandbox_mode_override: Option<SandboxMode>,
        windows_sandbox_level: WindowsSandboxLevel,
        active_project: Option<&ProjectConfig

作用：把旧的 sandbox_mode 配置翻译成真正执行时用的 PermissionProfile（权限档案：能读写哪里、能不能联网、是否完全放开）。这很关键，因为它决定命令执行时有多安全。

数据流：输入当前 ConfigToml、可选的沙盒覆盖值、Windows 沙盒级别、当前项目配置、以及权限约束 → 先决定最终沙盒模式；如果项目有信任决定但没写 sandbox_mode，会给一个默认沙盒；在某些 Windows 情况下把 workspace-write 降成 read-only；再生成 read_only、workspace_write、workspace_write_with 或 Disabled 权限档案；如果默认档案违反外部约束，就警告并退回只读 → 输出 PermissionProfile。

调用关系：load_config_with_layer_stack 在组装最终配置时会调用它，测试里的 derive_legacy_sandbox_policy_for_test 也会用它验证旧沙盒规则。它把具体档案创建交给 PermissionProfile 的 read_only、workspace_write、workspace_write_with 等函数。

调用图：调用 3 个内部函数（read_only, workspace_write, workspace_write_with）；被 2 处调用（load_config_with_layer_stack, derive_legacy_sandbox_policy_for_test）；外部调用 3 个（cfg!, matches!, warn!）。

fn get_active_project(
        &self,
        resolved_cwd: &Path,
        repo_root: Option<&Path>,
    ) -> Option<ProjectConfig>

作用：根据当前目录找出匹配的项目配置。这样 Codex 才知道这个目录有没有被标记为可信或不可信。

数据流：输入当前工作目录 resolved_cwd 和可选的代码仓库根目录 repo_root → 先从 ConfigToml.projects 里取项目表；把当前目录规范化成一个或多个查找键并查表；找不到再用仓库根目录重复查找 → 找到就返回对应 ProjectConfig 的副本，找不到返回 None。

调用关系：load_config_with_layer_stack 在加载配置时调用它，用当前所在目录决定哪份项目级信任设置生效；它把路径整理交给 normalized_project_lookup_keys，把查表细节交给 project_config_for_lookup_key。

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

fn normalized_project_lookup_keys(path: &Path) -> Vec<String>

作用：把路径变成适合查项目配置表的 key。它会同时考虑原始路径和系统规范化后的路径，减少“同一个目录写法不同导致匹配失败”的问题。

数据流：输入一个 Path 路径 → 先把原路径转成字符串并做平台相关规范化；再尝试用 normalize_for_path_comparison 得到更标准的路径，也做同样规范化 → 如果两个结果一样就返回一个 key，否则返回两个候选 key。

调用关系：ConfigToml::get_active_project 调用它来准备查表用的路径字符串；它内部再调用 normalize_project_lookup_key 做 Windows 等平台差异处理。

调用图：调用 1 个内部函数（normalize_project_lookup_key）；被 1 处调用（get_active_project）；外部调用 3 个（to_string_lossy, normalize_for_path_comparison, vec!）。

fn normalize_project_lookup_key(key: String) -> String

作用：对项目查找 key 做最基础的平台整理。主要是 Windows 上把大小写统一，避免路径大小写不同却指向同一个地方。

数据流：输入一个字符串 key → 如果是 Windows，就转成小写；其他系统保持原样 → 输出整理后的 key。

调用关系：normalized_project_lookup_keys 会调用它；project_config_for_lookup_key 也用同样规则比较配置表里的 key，保证两边口径一致。

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

fn project_config_for_lookup_key(
    projects: &HashMap<String, ProjectConfig>,
    lookup_key: &str,
) -> Option<ProjectConfig>

作用：在 projects 配置表里按路径 key 找项目配置。它既尝试直接匹配，也尝试规范化后匹配。

数据流：输入项目配置表和一个 lookup_key → 先直接用 lookup_key 查；如果没有，就遍历所有配置 key，规范化后再比较；如果有多个匹配，按 key 排序后取第一个，保证结果稳定 → 返回 ProjectConfig 的副本或 None。

调用关系：ConfigToml::get_active_project 把具体查表工作交给它；它确保用户配置里的路径写法稍有不同也尽量能匹配上。

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

fn validate_reserved_model_provider_ids(
    model_providers: &HashMap<String, ModelProviderInfo>,
) -> Result<(), String>

作用：检查用户自定义模型提供商有没有用了保留名字。保留名字像内置品牌名，不能随便覆盖，否则程序可能把自定义配置误当官方内置配置。

数据流：输入 model_providers 表 → 找出冲突的 key，排除允许特殊处理的 Amazon Bedrock → 如果没有冲突返回 Ok；如果有，就拼出一条说明哪些名字不能用的错误信息 → 返回 Err(String)。

调用关系：validate_model_providers 会先调用它做第一道检查；它只负责“名字是否占用保留 ID”这一件事。

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

fn validate_model_providers(
    model_providers: &HashMap<String, ModelProviderInfo>,
) -> Result<(), String>

作用：完整检查用户写的模型提供商配置是否合理。它防止空名字、错误的 AWS 配置、覆盖内置提供商等问题进入运行期。

数据流：输入 model_providers 表 → 先调用 validate_reserved_model_provider_ids 查保留 ID；再逐个检查：Amazon Bedrock 走特殊规则，其他 provider 不能带 aws 配置，name 不能为空，还要调用 provider.validate 做更细检查 → 全部通过返回 Ok，否则返回带位置说明的错误字符串。

调用关系：deserialize_model_providers 在读配置时调用它，load_config_with_layer_stack 在加载配置流程中也会用它。它是模型提供商配置进入系统前的主要验收关。

调用图：调用 1 个内部函数（validate_reserved_model_provider_ids）；被 2 处调用（deserialize_model_providers, load_config_with_layer_stack）；外部调用 1 个（format!）。

fn deserialize_model_providers(
    deserializer: D,
) -> Result<HashMap<String, ModelProviderInfo>, D::Error>

作用：读取 model_providers 配置，并立刻做合法性检查。这样坏配置不会悄悄混进 ConfigToml。

数据流：输入 TOML 反序列化器 → 先把数据读成 HashMap<String, ModelProviderInfo> → 调用 validate_model_providers 检查 → 通过就返回这张表；失败就把错误转成 serde 能报告的配置读取错误。

调用关系：serde 在读取 ConfigToml.model_providers 字段时调用它；它把“解析”和“验收”连在一起，避免后续流程拿到未检查的数据。

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

fn validate_oss_provider(provider: &str) -> std::io::Result<()>

作用：检查本地开源模型提供商名字是否合法。它只接受当前支持的 lmstudio 和 ollama，并对已经移除的旧 ollama-chat 给专门提示。

数据流：输入一个 provider 字符串 → 如果是 lmstudio 或 ollama，返回 Ok；如果是旧的 ollama-chat，返回带移除说明的 InvalidInput 错误；其他值返回“必须是哪些值之一”的 InvalidInput 错误 → 不修改任何配置。

调用关系：set_default_oss_provider 会调用它，先确认用户指定的 OSS provider 能用，再把它设成默认本地模型提供商。

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

fn forced_chatgpt_workspace_id_accepts_single_string()

作用：测试 forced_chatgpt_workspace_id 写成单个字符串时能被接受。它保证旧的简单写法不会被破坏。

数据流：构造一段只含一个 workspace ID 的 TOML 字符串 → 用 toml::from_str 读成 ConfigToml → 取出配置并转成列表 → 断言列表里正好是这个 ID。

调用关系：这是本文件内部的单元测试，专门验证 ForcedChatgptWorkspaceIds::deserialize 和 into_vec 配合后能正确处理单字符串。

调用图：外部调用 3 个（assert_eq!, format!, from_str）。

fn forced_chatgpt_workspace_id_accepts_string_list()

作用：测试 forced_chatgpt_workspace_id 写成字符串列表时能被接受。它保证多个 workspace ID 的正式写法可用。

数据流：构造一段包含两个 workspace ID 的 TOML 列表 → 读成 ConfigToml → 取出字段并转成 Vec<String> → 断言结果正好包含这两个 ID，顺序也一致。

调用关系：这是针对 ForcedChatgptWorkspaceIds::deserialize 的单元测试，覆盖 Multiple 分支，也顺带验证 into_vec 不会改变列表内容。

调用图：外部调用 3 个（assert_eq!, format!, from_str）。

fn forced_chatgpt_workspace_id_rejects_comma_separated_string()

作用：测试逗号拼接的 workspace ID 字符串会被拒绝。它防止用户写出看似多个 ID、实际只是一个字符串的危险配置。

数据流：构造一段值为“ID_A,ID_B”的 TOML → 尝试读成 ConfigToml 并期待失败 → 检查错误信息里包含“应该用 TOML 字符串列表”和“不支持逗号分隔字符串”的提示。

调用关系：这是 ForcedChatgptWorkspaceIds::deserialize 的错误路径测试，确保用户写错时能得到明确提示，而不是被静默接受。

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

fn is_empty(&self) -> bool

作用：检查所有 hook 事件列表是不是都没有配置。别人可以用它来判断这份 hook 配置是否等于“什么都没写”。

数据流：进去的是一个 HookEventsToml，也就是按事件分类放好的 hook 列表；它逐个查看十类事件的列表是否为空；出来的是 true 或 false，不修改原来的配置。

调用关系：它是配置读取后的一个小检查点，适合在保存、合并或判断是否需要继续处理 hook 时使用。它不把工作交给其他函数，只做一个总开关式的空值判断。

fn handler_count(&self) -> usize

作用：统计一共配置了多少个具体 hook 动作。这里数的是每个分组里的 hooks 数量，而不是事件种类数量。

数据流：进去的是按十类事件分好的配置；它把所有事件列表摊开，再把每个 MatcherGroup 里的 hooks 长度加起来；出来的是一个数字，表示总共有多少个处理器，不改动配置本身。

调用关系：它被 ManagedHooksRequirementsToml::handler_count 复用，因为“受管理 hook”里面也包含同样的一套事件配置。这样外层结构不需要重新写一遍统计逻辑。

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

fn into_matcher_groups(self) -> [(HookEventName, Vec<MatcherGroup>); 10]

作用：把按字段保存的 hook 配置，转换成“事件名 + 对应规则列表”的固定顺序数组。这样后续代码可以统一遍历，不用一个字段一个字段地手写处理。

数据流：进去的是一个 HookEventsToml，并且会把它消耗掉；它把 pre_tool_use、post_tool_use 等字段分别配上正式的 HookEventName；出来的是包含十项的数组，每项都是一个事件名和它的 MatcherGroup 列表。

调用关系：append_hook_events 会调用它，把配置里的事件规则追加进运行时使用的 hook 系统。它相当于把“配置文件格式”翻译成“程序内部好遍历的格式”。

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

fn is_empty(&self) -> bool

作用：检查“受管理 hook”的要求是不是完全没写。它不仅看 hook 列表，也看是否指定了管理目录。

数据流：进去的是 ManagedHooksRequirementsToml；它查看 managed_dir、windows_managed_dir 是否都是空，再检查内部 hooks 是否为空；出来的是 true 或 false，不改变任何字段。

调用关系：它用于判断这段受管理 hook 配置有没有实际内容。它会借助 HookEventsToml::is_empty 完成内部 hook 列表的空值检查。

fn handler_count(&self) -> usize

作用：统计受管理 hook 配置里一共有多少个具体 hook 动作。它只是把问题转交给里面那份普通 hook 事件配置。

数据流：进去的是 ManagedHooksRequirementsToml；它读取其中的 hooks 字段，并调用 HookEventsToml::handler_count 来计算数量；出来的是处理器总数，不修改配置。

调用关系：它处在外层包装位置，让调用者不用先拆开 ManagedHooksRequirementsToml 再统计。真正的统计工作由 HookEventsToml::handler_count 完成。

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

fn managed_dir_for_current_platform(&self) -> Option<&Path>

作用：根据当前运行的操作系统，选出应该使用的受管理 hook 目录。Windows 和非 Windows 的路径可能不同，这个函数负责自动挑对的那个。

数据流：进去的是 ManagedHooksRequirementsToml；如果程序编译在 Windows 上，就读取 windows_managed_dir，否则读取 managed_dir；出来的是一个可选路径引用，原配置不会被移动或修改。

调用关系：managed_hooks_source_path 会调用它来决定到哪里找受管理的 hook 文件。它把平台差异藏在一个地方，避免其他代码到处写“如果是 Windows 就……”这种判断。

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

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

作用：把“这个 MCP 服务器为什么被禁用”变成给人看的文字。这样命令行或界面上显示的不是代码里的枚举名字，而是用户能理解的原因。

数据流：进去的是一个禁用原因和一个写文字的输出位置 → 它判断原因是未知，还是因为某个配置要求导致禁用 → 出来的是写好的短文本，比如“unknown”或“requirements (...)”，不会改动配置本身。

调用关系：它是显示层会自动用到的小翻译器。当界面、日志或命令行想打印 McpServerDisabledReason 时，会走到这里；它只负责写文字，把实际写入动作交给 Rust 的 write! 宏。

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

fn name(&self) -> &str

作用：取出一个环境变量配置里的变量名。不管用户是只写了名字，还是写了带来源的完整配置，都能用同一个办法拿到名字。

数据流：进去的是一个 McpServerEnvVar → 它看这个值是哪种写法：简单字符串或带 name/source 的对象 → 出来的是环境变量名的文本引用，不新建数据，也不修改原值。

调用关系：它是环境变量配置的基础读取函数。AsRef 转换会调用它，让其他代码可以把 McpServerEnvVar 当成普通字符串名字来用。

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

fn source(&self) -> Option<&str>

作用：取出环境变量的来源说明。来源可以为空，也可以是 local 或 remote，用来说明这个变量应该从哪里拿。

数据流：进去的是一个环境变量配置 → 如果它只是一个名字，就认为没有显式来源；如果它带 source 字段，就取出这个字段 → 出来的是可选的来源文字，不改变原配置。

调用关系：它被 is_remote_source 和 validate_source 使用。前者用它判断是不是远程来源，后者用它检查用户有没有写错来源值。

调用图：被 2 处调用（is_remote_source, validate_source）。

fn is_remote_source(&self) -> bool

作用：判断这个环境变量是不是标成了 remote，也就是来自远程环境。调用者可以用它快速决定变量该从哪里绑定。

数据流：进去的是一个环境变量配置 → 它先调用 source 拿到来源 → 如果来源正好是“remote”，出来就是 true，否则是 false；配置本身不变。

调用关系：它站在更高一层，复用 source 的读取结果。其他需要区分本地变量和远程变量的流程，可以直接问它，而不用自己比较字符串。

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

fn validate_source(&self) -> Result<(), String>

作用：检查环境变量来源写得是否合法。它只接受没写来源、local、remote，避免用户写了拼错或项目不支持的来源后还继续运行。

数据流：进去的是一个环境变量配置 → 它调用 source 取出来源，再和允许值比较 → 如果合法，出来是成功；如果不合法，出来是一段明确的错误信息，告诉用户只能写 local 或 remote。

调用关系：它在 MCP 配置从原始格式转换成正式配置时被用到。McpServerConfig::try_from 会逐个检查 env_vars，发现错误就停止转换并返回报错。

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

fn from(value: &str) -> Self

作用：把一个普通字符串快速变成环境变量配置。这样代码里只想写变量名时，不必手动包一层结构。

数据流：进去的是一个字符串值 → 它把这个字符串放进 McpServerEnvVar 的 Name 形式里 → 出来的是一个只包含变量名、没有来源说明的环境变量配置。

调用关系：它是便利转换函数，常在代码或测试里让写法更短。它不做校验，也不参与复杂流程，只负责把简单文本包装成统一类型。

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

fn as_ref(&self) -> &str

作用：让 McpServerEnvVar 可以像字符串一样被借用。这样需要变量名的通用代码，不一定要知道它内部有几种写法。

数据流：进去的是一个环境变量配置 → 它调用 name 取出变量名 → 出来的是变量名字符串引用，不复制内容，也不改变配置。

调用关系：它把 McpServerEnvVar 接到 Rust 常见的 AsRef<str> 用法上。内部真正取名字的工作交给 McpServerEnvVar::name。

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

fn is_local_environment(&self) -> bool

作用：判断这个 MCP 服务器是不是运行在默认的本地环境里。很多地方需要知道服务器是在本机，还是在某个远程环境中。

数据流：进去的是已经整理好的 MCP 服务器配置 → 它把 environment_id 和默认值“local”比较 → 出来是 true 或 false，不改动配置。

调用关系：它会被绑定环境变量、解析服务器环境、序列化配置等流程使用。那些流程不需要自己记住默认环境名，只要调用这个函数问一句即可。

调用图：被 4 处调用（bind_environment_env_vars, resolve_server_environment, serialize_mcp_server, serialize_mcp_server_table）。

fn oauth_client_id(&self) -> Option<&str>

作用：取出 OAuth 客户端 ID。OAuth 是一种常见登录授权流程，这个 ID 用来告诉授权服务“是谁在申请登录”。

数据流：进去的是 MCP 服务器配置 → 它查看 oauth 配置是否存在，再看里面有没有 client_id → 出来是可选的客户端 ID 文本引用；如果没配置就返回空。

调用关系：它给启动 MCP OAuth 登录流程的代码使用。调用者不用自己一层层拆 oauth 配置，只要通过这个函数安全地取值。

fn try_from(raw: RawMcpServerConfig) -> Result<Self, Self::Error>

作用：把刚从配置文件读出来的原始 MCP 配置，变成程序真正使用的、已经检查过的配置。它是这个文件里最关键的“验收关”。

数据流：进去的是 RawMcpServerConfig，里面可能有 command、url、环境变量、超时、工具列表等原始字段 → 它先处理启动超时，再判断到底是 stdio 方式还是 HTTP 方式，并拒绝混用不该出现的字段；接着检查 env_vars 的来源、补上默认 environment_id、检查远程 stdio 的 cwd 是否合格 → 出来是 McpServerConfig；如果配置矛盾或非法，出来是一段给用户看的错误信息。

调用关系：它被 McpServerConfig::deserialize 间接触发，也就是读配置文件时会走这里。它会把远程 stdio 工作目录检查交给 validate_remote_stdio_cwd，并使用 Duration 的转换函数把秒或毫秒变成程序内部的时间长度。

调用图：调用 1 个内部函数（validate_remote_stdio_cwd）；外部调用 2 个（from_millis, try_from_secs_f64）。

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

作用：告诉反序列化系统：读取 McpServerConfig 时，不能直接照字段塞进去，而要先按原始配置读取，再做完整校验。反序列化就是把配置文件文字变成程序数据。

数据流：进去的是配置解析器提供的数据流 → 它先把内容读成 RawMcpServerConfig → 再调用转换逻辑变成 McpServerConfig；成功时输出正式配置，失败时把字符串错误包装成解析错误。

调用关系：它是配置加载时的入口钩子。外部代码只要声明要读 McpServerConfig，serde 这个解析库就会调用它；真正的规则判断交给 McpServerConfig::try_from。

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

fn default_enabled() -> bool

作用：给 MCP 服务器的 enabled 字段提供默认值 true。也就是说，如果用户没写是否启用，就默认启用这个服务器。

数据流：没有输入 → 它直接返回 true → 用在配置缺省值上，不读取也不修改任何外部状态。

调用关系：它被 serde 的默认值机制使用，也在转换配置时用于补齐 enabled。这样默认行为集中在一个地方，不会到处散落魔法值。

fn validate_remote_stdio_cwd(
    transport: &McpServerTransportConfig,
    environment_id: &str,
) -> Result<(), String>

作用：检查远程环境里的 stdio MCP 服务器有没有写正确的工作目录。远程启动命令时，如果目录不是绝对路径，程序很难确定它到底会在哪儿运行。

数据流：进去的是传输方式配置和 environment_id → 如果是本地环境，直接通过；如果不是 stdio 方式，也通过；如果是远程 stdio，则要求 cwd 必须存在且是绝对路径 → 出来是成功，或一段说明 cwd 缺失/不是绝对路径的错误信息。

调用关系：它由 McpServerConfig::try_from 调用，属于配置验收的一部分。它只管这一条安全规则，不负责判断 command/url 等其他配置是否冲突。

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

fn serialize(value: &Option<Duration>, serializer: S) -> Result<S::Ok, S::Error>

作用：把可选的 Duration 时间长度写成“秒”的数字，方便存进配置或输出成 JSON/TOML。Duration 是程序内部表示时间段的类型。

数据流：进去的是 Option<Duration>，也就是“可能有时间，也可能没有” → 如果有时间，就转成带小数的秒数并写出去；如果没有，就写成空值 → 输出交给序列化器，不改变原时间。

调用关系：它被带有 option_duration_secs 标记的配置字段使用，比如启动超时和工具调用超时。实际写出 Some/None 的动作交给 serde 的 serialize_some 或 serialize_none。

调用图：外部调用 2 个（serialize_none, serialize_some）。

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

作用：把配置里写的秒数读成程序内部的 Duration。这样用户可以写 1.5 秒，程序内部仍然拿到标准的时间长度对象。

数据流：进去的是配置解析器中的一个可选数字 → 它先读成 Option<f64>，再把数字秒转换成 Duration；如果数字不合法，就变成解析错误 → 出来是 Option<Duration>。

调用关系：它被配置字段的反序列化标记使用。McpServerConfig::try_from 之外，一些字段在读入 RawMcpServerConfig 时就会通过它完成秒数到 Duration 的转换。

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

fn as_str(&self) -> &str

作用：把已经标准化好的快捷键拿出来当普通字符串用。别人不需要知道里面怎么存，只要拿到像 ctrl-a 这样的文本即可。

数据流：进去的是一个 KeybindingSpec 对象 → 它读取对象内部保存的字符串 → 出来的是这个字符串的只读引用，不修改任何东西。

调用关系：这是很小的取值入口。运行时代码或显示提示时，拿到快捷键对象后会用它查看标准写法；它不再把工作交给别的函数。

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

作用：在读取配置文件时，把用户写的快捷键文本变成安全的 KeybindingSpec。如果用户写错，它会立刻报一个面向人的错误。

数据流：进去的是配置解析器给出的原始字符串 → 它先按普通字符串读出来，再交给 normalize_keybinding_spec 清理和检查 → 出来的是保存了标准快捷键的 KeybindingSpec，或者一个解析错误。

调用关系：它是配置读取过程里的关卡。Serde（一个把配置文本变成程序对象的工具）调用它；它再调用 normalize_keybinding_spec 做真正的按键规则检查。

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

fn specs(&self) -> Vec<&KeybindingSpec>

作用：把“一个快捷键”或“一组快捷键”统一拿成一个列表来用。这样后面的代码不用分别处理两种写法。

数据流：进去的是一个动作的绑定配置，可能是单个键，也可能是多个键 → 它把单个键包装成一项列表，或把原来的多项按顺序取出来 → 出来的是一组只读的快捷键引用，不改变配置。

调用关系：它被 parse_bindings 使用，通常是在运行时准备快捷键表时调用。它保证后续流程总能按列表方式处理，并保留用户写配置时的顺序。

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

fn normalize_keybinding_spec(raw: &str) -> Result<String, String>

作用：把用户输入的快捷键写法整理成统一格式，并拒绝含糊或不合法的写法。比如把 Control-A 变成 ctrl-a，也会发现重复修饰键、缺少主键等错误。

数据流：进去的是原始按键字符串 → 它去掉首尾空格、转成小写、拆分出 ctrl、alt、shift 这类修饰键（一种按住不放配合别的键的键），检查顺序和重复情况，再把主键交给 normalize_key_name → 出来的是按 ctrl-alt-shift-主键 顺序拼好的标准字符串，或一段清楚的错误说明。

调用关系：它是快捷键标准化的核心。KeybindingSpec::deserialize 在读配置时调用它；它再把单个主键的合法性检查交给 normalize_key_name。

调用图：调用 1 个内部函数（normalize_key_name）；被 1 处调用（deserialize）；外部调用 3 个（from, new, format!）。

fn normalize_key_name(key: &str, original: &str) -> Result<String, String>

作用：检查快捷键里的“主键”是不是支持的键，并把常见别名改成统一名字。比如 return 统一成 enter，pgdn 统一成 page-down。

数据流：进去的是拆出来的主键文本和原始整条快捷键 → 它先替换别名，再判断是不是单个可打印字符、常见特殊键、方向键、页面键，或者 f1 到 f24 这样的功能键 → 出来的是标准主键名，或者说明哪个键未知的错误信息。

调用关系：它只处理主键这一小块规则，由 normalize_keybinding_spec 调用。这样外层函数负责组合键结构，内层函数负责“这个键名认不认”。

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

fn misplaced_action_at_keymap_root_is_rejected()

作用：测试把动作直接写在快捷键配置根部时会被拒绝。这样可以防止用户把配置写错位置却没有发现。

数据流：进去的是一段故意写错位置的 TOML 配置文本 → 测试尝试把它解析成 TuiKeymap → 期望出来的是错误，而不是被当成有效配置。

调用关系：这是测试运行时由测试框架调用的检查项。它验证结构体上的“拒绝未知字段”规则确实生效。

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

fn misspelled_action_under_context_is_rejected()

作用：测试某个场景里的动作名拼错时会报错。这样用户写错 open_transcript 这类名字时，不会被系统静默跳过。

数据流：进去的是一段在 global 场景下拼错动作名的 TOML → 它尝试解析配置并捕获错误 → 出来要确认错误信息里包含那个拼错的字段名。

调用关系：这是测试框架运行的用例。它主要保护配置 schema，也就是“允许哪些字段”的规则。

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

fn misspelled_vim_text_object_action_is_rejected()

作用：测试 Vim 文本对象场景里的动作名拼错也会被拒绝。Vim 文本对象可以理解成“按词、括号、引号等范围选中文本”的快捷操作。

数据流：进去的是一段把 double_quote 错写成 double_quotes 的配置 → 它尝试解析并拿到错误 → 出来要确认错误确实提到了这个错误字段。

调用关系：这是测试框架调用的用例。它专门覆盖 Vim 文本对象这一组配置，避免某些场景漏掉严格检查。

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

fn removed_backtrack_actions_are_rejected()

作用：测试已经删除的旧动作名不能继续出现在配置里。这样旧文档或旧配置不会被误认为仍然可用。

数据流：进去的是一批已移除动作名和它们所在场景 → 测试逐个拼出 TOML 配置并尝试解析 → 每次都应该得到错误，并且错误里要写出对应动作名。

调用关系：这是测试框架调用的回归测试。它防止后来有人不小心又让这些废弃字段被接受。

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

fn action_under_global_context_is_accepted()

作用：测试正确写在 global 场景下的动作能被接受。它确认正常用户配置不会被严格规则误伤。

数据流：进去的是一段合法的 global.open_transcript = "ctrl-s" 配置 → 它解析成 TuiKeymap → 出来检查 open_transcript 确实有值。

调用关系：这是测试框架调用的正向用例。前面的测试检查错误会被拒绝，这个测试检查正确写法能通过。

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

fn minus_bindings_under_global_context_are_accepted()

作用：测试 minus 以及 alt-minus 这样的减号键绑定是允许的。因为 - 同时也用来分隔组合键，所以这里特别容易出错，需要单独保护。

数据流：进去的是两种减号相关快捷键配置 → 它们分别被解析成 TuiKeymap → 出来和手工构造的期望结果比较，确认标准化后仍是 minus 或 alt-minus。

调用关系：这是测试框架调用的边界用例。它间接验证 normalize_keybinding_spec 和 normalize_key_name 对减号键的处理没有把它误拆坏。

调用图：外部调用 5 个（assert_eq!, One, default, format!, from_str）。

fn function_keys_through_f24_are_accepted()

作用：测试功能键支持到 f24，但不接受 f25。功能键就是键盘上常见的 F1、F2 这类键。

数据流：进去的是 F13、f24、f25 三个按键写法 → 它直接调用 normalize_keybinding_spec → 出来确认前两个成功变成小写标准写法，最后一个失败。

调用关系：这是测试框架调用的边界测试。它保护 MAX_FUNCTION_KEY 这条上限规则，避免支持范围被无意改变。

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

fn new(config: EnvironmentsToml) -> Result<Self, ExecServerError>

作用：这是测试里常用的简化构造入口，用一份已经解析好的配置创建 TOML 环境提供者。它不带配置目录，所以相对路径不会被自动补全。

数据流：输入是一份 EnvironmentsToml 配置 → 它把配置原样交给 TomlEnvironmentProvider::new_with_config_dir，并明确说“没有配置目录” → 输出是创建好的提供者，或者配置不合法时返回错误。

调用关系：它主要被本文件里的测试调用，用来快速验证各种配置情况。真正干活的是 new_with_config_dir，它只是一个方便入口。

调用图：被 13 处调用（toml_provider_can_disable_local_environment, toml_provider_default_none_disables_default, toml_provider_default_omitted_selects_local, toml_provider_includes_local_and_adds_configured_environments, toml_provider_parses_configured_transport_timeouts, toml_provider_rejects_duplicate_ids, toml_provider_rejects_invalid_environments, toml_provider_rejects_local_default_when_local_is_disabled, toml_provider_rejects_malformed_websocket_url, toml_provider_rejects_overlong_id (+3 more)）；外部调用 1 个（new_with_config_dir）。

fn new_with_config_dir(
        config: EnvironmentsToml,
        config_dir: Option<&Path>,
    ) -> Result<Self, ExecServerError>

作用：这是创建 TOML 环境提供者的核心函数。它把配置里的环境逐个检查、转换，并确定默认环境该是谁。

数据流：输入是一份 EnvironmentsToml，以及可选的配置文件所在目录 → 它先决定是否包含本机环境，再逐个调用 parse_environment_toml 解析远程环境，同时用集合检查环境名是否重复，最后调用 normalize_default_environment_id 校准默认环境 → 输出一个 TomlEnvironmentProvider，里面保存默认环境、本机环境开关和所有远程连接方式；如果发现重复名或非法配置，就返回错误。

调用关系：environment_provider_from_codex_home 在读到 environments.toml 后会调用它。测试也会直接调用它，特别是检查相对 cwd 能否按配置目录正确展开。

调用图：调用 2 个内部函数（normalize_default_environment_id, parse_environment_toml）；被 2 处调用（environment_provider_from_codex_home, toml_provider_resolves_relative_stdio_cwd_from_config_dir）；外部调用 4 个（new, with_capacity, Protocol, format!）。

fn snapshot(&self) -> EnvironmentProviderFuture<'_>

作用：这个函数把提供者当前保存的配置整理成一份“环境快照”。快照就是给外部使用的一次性环境清单。

数据流：输入是 TomlEnvironmentProvider 自己保存的远程环境列表、默认环境和 include_local 开关 → 它把每个连接参数包装成 Environment::remote_with_transport 表示的远程环境 → 输出 EnvironmentProviderSnapshot，里面有远程环境列表、默认选择和是否包含本机环境。

调用关系：它实现 EnvironmentProvider 这个接口时会被包装成异步任务。其他代码只要拿到 EnvironmentProvider，就会通过 snapshot 来获取可用环境。

调用图：调用 1 个内部函数（remote_with_transport）；外部调用 3 个（pin, with_capacity, clone）。

fn parse_environment_toml(
    item: EnvironmentToml,
    config_dir: Option<&Path>,
) -> Result<(String, ExecServerTransportParams), ExecServerError>

作用：这个函数负责解析 environments.toml 里的单个环境条目。它会判断这个环境是通过 WebSocket 连接，还是通过启动一个命令来连接。

数据流：输入是一个 EnvironmentToml 条目和可选配置目录 → 它先调用 validate_environment_id 检查环境名，再检查字段组合是否合法，比如 args/env/cwd 必须配 program，connect_timeout_sec 必须配 url；然后根据 url 或 program 二选一生成 ExecServerTransportParams → 输出环境 id 和对应的连接参数；配置矛盾时返回错误。

调用关系：new_with_config_dir 会对配置文件里的每个环境调用它。它内部会把 URL 检查交给 validate_websocket_url，把命令工作目录处理交给 normalize_stdio_cwd。

调用图：调用 3 个内部函数（normalize_stdio_cwd, validate_environment_id, validate_websocket_url）；被 1 处调用（new_with_config_dir）；外部调用 2 个（Protocol, format!）。

fn normalize_stdio_cwd(
    id: &str,
    cwd: Option<PathBuf>,
    config_dir: Option<&Path>,
) -> Result<Option<PathBuf>, ExecServerError>

作用：这个函数处理命令型环境的工作目录 cwd。它保证最终传给命令的目录要么没有，要么是明确的完整路径。

数据流：输入是环境 id、可选 cwd、可选配置目录 → 如果没写 cwd，就输出 None；如果 cwd 本来就是绝对路径，就原样输出；如果是相对路径且知道配置目录，就把两者拼起来；如果是相对路径但不知道配置目录，就返回错误 → 输出规范化后的 cwd。

调用关系：parse_environment_toml 在处理 program 这种命令连接方式时会调用它。这样 ssh 或其他启动命令拿到的工作目录不会含糊。

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

fn environment_provider_from_codex_home(
    codex_home: &Path,
) -> Result<Box<dyn EnvironmentProvider>, ExecServerError>

作用：这是从 Codex 的家目录创建环境提供者的入口。它会寻找 environments.toml，存在就按文件配置来，不存在就使用默认配置。

数据流：输入是 codex_home 路径 → 它拼出 codex_home/environments.toml，先检查文件是否存在；不存在时返回 DefaultEnvironmentProvider::from_env；存在时调用 load_environments_toml 读文件，再调用 TomlEnvironmentProvider::new_with_config_dir 转成提供者 → 输出一个装箱的 EnvironmentProvider，供外部统一使用。

调用关系：更上层的 from_codex_home 会用它来建立环境来源。它是本文件和外部启动流程之间的主要连接点。

调用图：调用 3 个内部函数（from_env, new_with_config_dir, load_environments_toml）；被 3 处调用（from_codex_home, environment_provider_from_codex_home_falls_back_when_file_is_missing, environment_provider_from_codex_home_uses_present_environments_file）；外部调用 2 个（new, join）。

fn normalize_default_environment_id(
    default: Option<&str>,
    include_local: bool,
    ids: &HashSet<String>,
) -> Result<EnvironmentDefault, ExecServerError>

作用：这个函数决定“默认环境”最终应该是什么。它会处理没写默认值、写 none、写了不存在环境名等情况。

数据流：输入是可选 default 字符串、是否包含本机环境、已知环境名集合 → 如果没写 default，包含本机就默认 local，不包含本机就禁用默认；如果写的是 none，就禁用默认；如果写了其他名字，就确认它确实在已知环境里 → 输出 EnvironmentDefault，表示默认环境名或禁用；写空字符串或未知名字时返回错误。

调用关系：new_with_config_dir 在所有环境都解析完、知道有哪些 id 后调用它。这样默认环境不会指向一个根本不存在的环境。

调用图：被 1 处调用（new_with_config_dir）；外部调用 3 个（Protocol, EnvironmentId, format!）。

fn validate_environment_id(id: &str) -> Result<(), ExecServerError>

作用：这个函数检查环境名是否安全、清楚、不会和系统保留字冲突。它防止用户写出看起来能用、实际容易出问题的名字。

数据流：输入是环境 id 字符串 → 它检查是否为空、前后是否有空格、是否叫 local 或 none、是否太长、是否只包含英文数字以及 - 和 _ → 全部通过就输出成功；任何一条不通过就返回带说明的错误。

调用关系：parse_environment_toml 在解析每个环境条目的最开始调用它。它像门卫一样，先把不合格的环境名挡住。

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

fn validate_websocket_url(url: String) -> Result<String, ExecServerError>

作用：这个函数检查远程环境的 WebSocket 地址是否像一个真正可连接的地址。WebSocket 可以理解成一种长期保持的网络连接。

数据流：输入是 URL 字符串 → 它先去掉前后空格，检查不能为空，必须以 ws:// 或 wss:// 开头，再用 WebSocket 客户端库尝试把它解析成请求 → 输出清理后的 URL；格式错误时返回错误。

调用关系：parse_environment_toml 在处理 url 型环境时调用它。它保证后面的连接代码拿到的地址至少格式正确。

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

fn load_environments_toml(path: &Path) -> Result<EnvironmentsToml, ExecServerError>

作用：这个函数负责从磁盘读取 environments.toml，并把文本解析成程序里的配置结构。它还会把读文件和解析失败包装成更友好的错误。

数据流：输入是配置文件路径 → 它先用 read_to_string 读出文件内容，再用 toml::from_str 按 TOML 格式解析 → 输出 EnvironmentsToml；文件读不到或格式不对时，输出带文件路径的错误。

调用关系：environment_provider_from_codex_home 在发现配置文件存在后会调用它。相关测试也直接调用它，验证正常解析和未知字段报错。

调用图：被 3 处调用（environment_provider_from_codex_home, load_environments_toml_reads_root_environment_list, load_environments_toml_rejects_unknown_fields）；外部调用 2 个（read_to_string, from_str）。

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

作用：这个函数告诉 serde 如何把 TOML 里的秒数转换成 Duration。Duration 是程序里表示一段时间的类型。

数据流：输入是反序列化器提供的值，通常是一个可选小数秒数 → 它先把值读成 Option<f64>，再把秒数转换成 Duration；没写就是 None → 输出 Option<Duration>，如果秒数非法就返回解析错误。

调用关系：EnvironmentToml 的 connect_timeout_sec 和 initialize_timeout_sec 字段通过 serde 自动使用它。用户写 12.0 秒，程序里就变成 Duration。

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

async fn toml_provider_includes_local_and_adds_configured_environments()

作用：这个测试确认默认情况下会包含本机环境，并且 TOML 里配置的 WebSocket 环境和命令环境都能被加入。

数据流：输入是一份测试配置，包含一个 ws 地址环境和一个 ssh 命令环境 → 它调用 TomlEnvironmentProvider::new 创建提供者，再取 snapshot → 检查环境 id、URL、远程标记、默认环境和 include_local 是否符合预期。

调用关系：它覆盖 new 到 snapshot 的主流程，证明 parse_environment_toml、默认值处理和快照输出能一起正常工作。

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

async fn toml_provider_default_omitted_selects_local()

作用：这个测试确认用户不写 default 时，如果本机环境可用，就自动把 local 当默认环境。

数据流：输入是空配置 → 创建提供者并取快照 → 检查 include_local 为真，默认环境是 local。

调用关系：它主要验证 normalize_default_environment_id 在“没写默认值”情况下的默认行为。

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

async fn toml_provider_default_none_disables_default()

作用：这个测试确认 default = "none" 会关闭默认环境选择。也就是说系统不会自动替用户选一个环境。

数据流：输入是 default 写成 none 的配置 → 创建提供者并取快照 → 检查本机环境仍可包含，但 default 被标记为 Disabled。

调用关系：它验证 normalize_default_environment_id 对保留字 none 的特殊处理。

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

async fn toml_provider_can_disable_local_environment()

作用：这个测试确认用户可以通过 include_local = false 禁用本机环境，并把某个远程环境设为默认。

数据流：输入是关闭本机环境、配置 ssh-dev 命令环境、默认值也设为 ssh-dev 的配置 → 创建提供者并取快照 → 检查 include_local 为假，默认环境是 ssh-dev。

调用关系：它验证 new_with_config_dir 对 include_local 和默认环境集合的配合处理。

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

async fn toml_provider_without_local_and_default_omitted_disables_default()

作用：这个测试确认如果本机环境被关掉，用户又没写默认环境，那么默认环境会被禁用。

数据流：输入是 include_local = false 且没有环境列表的配置 → 创建提供者并取快照 → 检查 include_local 为假，default 是 Disabled。

调用关系：它补充验证 normalize_default_environment_id 在“没写 default 且没有 local”时不会乱选环境。

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

fn toml_provider_rejects_local_default_when_local_is_disabled()

作用：这个测试确认如果用户关闭了本机环境，却还把 local 写成默认环境，程序会报错。

数据流：输入是 include_local = false 且 default = local 的配置 → 调用 new 期望失败 → 检查错误信息说明 local 没有配置。

调用关系：它验证 new_with_config_dir 和 normalize_default_environment_id 会共同阻止默认环境指向不可用的 local。

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

fn toml_provider_rejects_invalid_environments()

作用：这个测试用一组坏配置确认程序会拒绝明显错误的环境条目。这样用户配置错时能尽早得到明确提示。

数据流：输入是一批测试用的非法 EnvironmentToml，比如 id 叫 local、id 带空格、URL 用 http、同时写 url 和 program、program 为空等 → 每个都调用 new → 检查返回的错误文字符合预期。

调用关系：它集中覆盖 validate_environment_id、validate_websocket_url、parse_environment_toml 的多种错误分支。

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

fn toml_provider_resolves_relative_stdio_cwd_from_config_dir()

作用：这个测试确认命令环境里的相对 cwd 会根据配置目录补成完整路径。

数据流：输入是临时配置目录和 cwd = workspace 的命令环境 → 调用 new_with_config_dir → 检查生成的 StdioCommand 里 cwd 变成 配置目录/workspace，并且初始化超时使用默认值。

调用关系：它主要验证 normalize_stdio_cwd 在知道 config_dir 时的路径拼接行为。

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

fn toml_provider_parses_configured_transport_timeouts()

作用：这个测试确认用户写的连接超时和初始化超时会被正确保存到连接参数里。

数据流：输入是一个 WebSocket 环境和一个命令环境，分别带不同 timeout → 创建提供者 → 检查 WebSocket 参数里的 connect_timeout、initialize_timeout，以及命令参数里的 initialize_timeout。

调用关系：它验证 parse_environment_toml 对两类传输方式的超时字段处理。

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

fn toml_provider_rejects_relative_stdio_cwd_without_config_dir()

作用：这个测试确认如果没有配置目录，相对 cwd 会被拒绝。因为程序无法知道它该相对哪个目录。

数据流：输入是 cwd = workspace 的命令环境，但通过 new 创建、没有 config_dir → 期望创建失败 → 检查错误提示 cwd 必须是绝对路径。

调用关系：它验证 normalize_stdio_cwd 的保护逻辑，防止命令在不确定目录下启动。

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

fn toml_provider_rejects_duplicate_ids()

作用：这个测试确认两个环境不能使用同一个 id。环境名重复会让默认选择和用户选择都变得含糊。

数据流：输入是两个都叫 devbox 的环境，一个用 url，一个用 program → 调用 new → 期望失败，并检查错误说明 id 重复。

调用关系：它验证 new_with_config_dir 里用集合检查重复 id 的逻辑。

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

fn toml_provider_rejects_overlong_id()

作用：这个测试确认环境 id 不能超过规定长度。过长的名字不适合作为稳定、可读的配置标识。

数据流：输入是比 MAX_ENVIRONMENT_ID_LEN 多 1 个字符的 id → 调用 new → 期望失败，并检查错误说明超过长度限制。

调用关系：它直接覆盖 validate_environment_id 的长度检查。

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

fn toml_provider_rejects_unknown_default()

作用：这个测试确认默认环境必须已经被配置出来。不能把 default 指向一个不存在的名字。

数据流：输入是 default = missing 且没有环境列表的配置 → 调用 new → 期望失败，并检查错误说明 missing 没有配置。

调用关系：它验证 normalize_default_environment_id 会用已知 id 集合检查默认环境。

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

fn load_environments_toml_reads_root_environment_list()

作用：这个测试确认 load_environments_toml 能从真实文件里读出完整配置，包括默认值、本机开关、环境列表、超时、参数、环境变量和 cwd。

数据流：输入是在临时目录写出的 environments.toml 文本 → 调用 load_environments_toml → 检查解析后的 EnvironmentsToml 每个字段都和文件内容一致。

调用关系：它直接验证磁盘读取和 TOML 解析这条路径，是 environment_provider_from_codex_home 的前置能力。

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

fn load_environments_toml_rejects_unknown_fields()

作用：这个测试确认配置文件里写了不认识的字段会报错。这样可以避免用户拼错字段名却以为配置生效了。

数据流：输入是两份带 unknown 字段的 TOML 文件，一份在顶层，一份在环境条目里 → 调用 load_environments_toml → 期望失败，并检查错误包含 unknown field。

调用关系：它验证 EnvironmentsToml 和 EnvironmentToml 上 deny_unknown_fields 的效果，也就是“未知字段不放过”。

调用图：调用 1 个内部函数（load_environments_toml）；外部调用 4 个（assert!, format!, write, tempdir）。

fn toml_provider_rejects_malformed_websocket_url()

作用：这个测试确认看起来以 ws:// 开头但实际不完整的 URL 也会被拒绝。

数据流：输入是 url = ws:// 的环境配置 → 调用 new → 期望失败，并检查错误里说明 URL 无效。

调用关系：它主要覆盖 validate_websocket_url 里借助 WebSocket 请求解析器做的更严格检查。

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

async fn environment_provider_from_codex_home_uses_present_environments_file()

作用：这个测试确认只要 Codex 家目录里有 environments.toml，就会使用这个文件里的配置。

数据流：输入是临时 codex_home，里面写入 default = none 和 include_local = false 的 environments.toml → 调用 environment_provider_from_codex_home 并取快照 → 检查本机环境未包含，默认环境被禁用。

调用关系：它覆盖 environment_provider_from_codex_home 的“文件存在”分支，也间接验证 load_environments_toml 和 new_with_config_dir 被串起来。

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

async fn environment_provider_from_codex_home_falls_back_when_file_is_missing()

作用：这个测试确认没有 environments.toml 时，系统会退回默认环境提供者，而不是报错。

数据流：输入是一个没有配置文件的临时 codex_home → 调用 environment_provider_from_codex_home 并取快照 → 检查 include_local 为真，默认环境是 local。

调用关系：它覆盖 environment_provider_from_codex_home 的“文件不存在”分支，证明新用户不写配置也能正常启动。

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

fn from(loader_overrides: LoaderOverrides) -> Self

作用：把一组加载器覆盖项包装成完整的配置加载选项。这样调用方只提供想改的加载来源，其余选项就用安全的默认值。

数据流：输入是一份 LoaderOverrides → 函数把它放进 ConfigLoadOptions，同时把严格配置检查设为关闭，并创建默认的云配置加载器 → 输出一份完整的 ConfigLoadOptions。

调用关系：它是从 LoaderOverrides 快速变成 ConfigLoadOptions 的小入口；内部只补默认值，不继续做真正的配置读取。

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

fn without_managed_config_for_tests() -> Self

作用：为测试创建一套“不要读取真实机器托管配置”的覆盖设置。这样测试不会被开发者电脑或公司设备上的真实配置影响。

数据流：输入为空 → 函数拿系统临时目录拼出几条测试用配置路径，并把 macOS 托管偏好等来源置空或指向空内容 → 输出一份适合测试隔离环境的 LoaderOverrides。

调用关系：很多测试和进程内服务器启动流程会用它，目的是先切断宿主机器的真实托管配置，再让测试自己提供可控的配置文件。

调用图：被 49 处调用（without_managed_config_for_tests, write_value_rejects_feature_requirement_conflict, refresh_test_state, get_conversation_summary_by_thread_id_reads_pathless_store_thread, mcp_resource_read_returns_error_for_unknown_thread, cold_thread_resume_reuses_non_local_history_probe, start_in_process_server, thread_list_includes_store_thread_without_rollout_path, thread_read_loaded_include_turns_reads_store_history_without_rollout_path, thread_turns_list_reads_store_history_without_rollout_path (+15 more)）；外部调用 2 个（new, temp_dir）。

fn with_managed_config_path_for_tests(managed_config_path: PathBuf) -> Self

作用：为测试指定一份假的托管配置文件。它适合测试“公司/系统托管配置会怎样覆盖用户配置”这类场景。

数据流：输入是一个 managed_config_path 路径 → 函数把同目录下的 requirements.toml 当作要求文件，并继承“不要用真实托管配置”的测试默认设置 → 输出一份带指定托管配置路径的 LoaderOverrides。

调用关系：它建立在 LoaderOverrides::without_managed_config_for_tests 之上；测试代码用它把托管配置来源换成 fixture，也就是测试样本文件。

调用图：被 21 处调用（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_reports_managed_override, write_value_reports_override, write_value_succeeds_when_managed_preferences_expand_home_directory_paths, experimental_feature_list_returns_feature_metadata_with_stage, explicit_remote_control_startup_fails_when_disabled_by_requirements (+11 more)）；外部调用 2 个（with_file_name, without_managed_config_for_tests）。

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

作用：算出应该读取哪一个用户配置文件。调用方可以提前指定路径；如果没指定，就使用默认的 CODEX_HOME/config.toml。

数据流：输入是 codex_home 目录，并读取 self.user_config_path → 如果已经有覆盖路径就直接返回；否则把默认配置文件名拼到 codex_home 下并转成绝对路径 → 输出用户配置文件的绝对路径或错误。

调用关系：配置加载主流程会在找用户配置时调用它；它把“测试或特殊运行时指定的路径”和“正常默认路径”统一成一个结果。

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

fn new(name: ConfigLayerSource, config: TomlValue) -> Self

作用：创建一层正常启用的配置。每一层都带来源、内容和一个根据内容算出的版本号。

数据流：输入是配置来源 name 和 TOML 配置内容 → 函数根据配置内容计算版本号，并把禁用原因、原始文本等附加信息留空 → 输出一个 ConfigLayerEntry。

调用关系：配置加载、用户配置替换、项目配置生成等地方都会用它来造一层标准配置；它会把版本计算交给 version_for_toml。

调用图：调用 1 个内部函数（version_for_toml）；被 33 处调用（create_empty_user_layer, enterprise_layers_precede_user_and_override_system, load_config_layers_state, load_user_config_layer, project_layer_entry, with_user_config_profile, active_user_layer_is_highest_precedence_user_layer, origins_use_canonical_key_aliases, with_user_config_updates_matching_user_layer_without_replacing_active_profile, thread_config_source_to_layer (+15 more)）。

fn new_with_raw_toml(
        name: ConfigLayerSource,
        config: TomlValue,
        raw_toml: String,
        raw_toml_base_dir: AbsolutePathBuf,
    ) -> Self

作用：创建一层配置，同时保存它最原始的 TOML 文本和所在目录。这样后面需要展示原文或按原位置解析路径时，还能找到原始信息。

数据流：输入是来源、解析后的 TOML、原始 TOML 字符串和原始文件所在目录 → 函数计算版本号，并把原始文本和基准目录一起存起来 → 输出一个带 raw_toml 信息的 ConfigLayerEntry。

调用关系：云配置片段和部分配置加载流程会用它；后续渲染非文件配置值时，可以通过 raw_toml 取回原文。

调用图：调用 1 个内部函数（version_for_toml）；被 2 处调用（cloud_config_layers_from_fragments_impl, load_config_layers_state）。

fn new_disabled(
        name: ConfigLayerSource,
        config: TomlValue,
        disabled_reason: impl Into<String>,
    ) -> Self

作用：创建一层“存在但不参与生效”的配置，并记录为什么被禁用。这样界面或调试信息可以告诉用户：这层配置被看到了，但没有用上。

数据流：输入是来源、配置内容和禁用原因 → 函数计算版本号，把禁用原因转成字符串存下 → 输出一个 disabled_reason 不为空的 ConfigLayerEntry。

调用关系：项目层生成时可能会用到它；之后 ConfigLayerStack::get_layers 默认会跳过这种被禁用的层，除非调用方明确要求也看禁用层。

调用图：调用 1 个内部函数（version_for_toml）；被 1 处调用（project_layer_entry）；外部调用 1 个（into）。

fn is_disabled(&self) -> bool

作用：判断这一层配置是不是被禁用了。调用方用它决定合并配置时要不要跳过这一层。

数据流：输入是当前配置层 → 函数查看 disabled_reason 有没有内容 → 输出 true 或 false，不改动任何数据。

调用关系：ConfigLayerStack::get_layers 会用它过滤掉不应生效的配置层。

fn raw_toml(&self) -> Option<&str>

作用：取出这一层保存的原始 TOML 文本。如果这一层不是从原文创建的，就返回空。

数据流：输入是当前配置层 → 函数查看 raw_toml 字段 → 输出原始文本的只读引用，或 None。

调用关系：渲染非文件配置层内容时会调用它，用来尽量展示用户或服务端原本提供的文本。

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

fn raw_toml_base_dir(&self) -> Option<&AbsolutePathBuf>

作用：取出原始 TOML 所在的基准目录。这个目录常用于解释配置里的相对路径。

数据流：输入是当前配置层 → 函数查看 raw_toml 字段里的 base_dir → 输出目录引用，或 None。

调用关系：它和 raw_toml 配套存在；当某层配置保存了原始文本时，调用方也能知道这段文本应该按哪个目录来理解。

fn with_hooks_config_folder_override(
        mut self,
        hooks_config_folder_override: Option<AbsolutePathBuf>,
    ) -> Self

作用：给这一层配置设置一个专门用于查找 hook 的目录覆盖值。hook 可以理解成“在特定时机自动触发的小脚本或动作”。

数据流：输入是当前配置层和一个可选目录 → 函数把目录写入 hooks_config_folder_override → 输出修改后的配置层本身。

调用关系：它用于少数特殊项目结构，比如 Git worktree；后面 ConfigLayerEntry::hooks_config_folder 会优先使用这里设置的目录。

fn metadata(&self) -> ConfigLayerMetadata

作用：把一层配置压缩成对外展示用的元信息，只包含来源和版本号。这样不用暴露整份配置内容，也能说明某个值来自哪一层。

数据流：输入是当前配置层 → 函数复制 name 和 version → 输出 ConfigLayerMetadata。

调用关系：ConfigLayerStack::origins 会用它记录字段来源；对外 API 也可以用这类元信息展示配置层身份。

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

fn as_layer(&self) -> ConfigLayer

作用：把内部的配置层转换成协议层可发送的 ConfigLayer。协议层就是进程之间或前后端之间约定好的数据格式。

数据流：输入是当前配置层 → 函数复制来源、版本、禁用原因，并把 TOML 配置转成 JSON 值；如果转换失败就用 Null → 输出 ConfigLayer。

调用关系：它把内部数据模型翻译成 app server 协议能理解的格式，方便配置层被 API 返回给客户端。

调用图：外部调用 2 个（clone, to_value）。

fn config_folder(&self) -> Option<AbsolutePathBuf>

作用：找出这一层配置对应的 .codex 文件夹。不是所有配置层都有文件夹，比如托管配置或启动参数通常没有。

数据流：输入是当前配置层 → 函数按来源类型判断：系统/用户配置取文件父目录，项目配置直接取项目的 .codex 目录，托管和会话参数返回 None → 输出可选的绝对目录。

调用关系：它是 hooks_config_folder 的默认来源，也帮助其他代码知道某层配置在磁盘上的位置。

fn hooks_config_folder(&self) -> Option<AbsolutePathBuf>

作用：返回查找 hook 声明时应该使用的 .codex 目录。正常情况下用配置层自己的目录，特殊情况下用覆盖目录。

数据流：输入是当前配置层 → 函数先看有没有 hooks_config_folder_override；如果没有，再调用 config_folder 的逻辑 → 输出可选目录。

调用关系：config_toml_source_path 等查找配置来源路径的流程会用它；它把普通项目和 linked worktree 的特殊情况统一起来。

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

fn new(
        layers: Vec<ConfigLayerEntry>,
        requirements: ConfigRequirements,
        requirements_toml: ConfigRequirementsToml,
    ) -> std::io::Result<Self>

作用：创建一整叠配置层，并先检查它们的顺序是否合法。配置顺序错了，最后合并出来的结果就会错，所以这里会提前拦住。

数据流：输入是一组配置层、强制要求 requirements、以及原始 requirements_toml → 函数调用 verify_layer_ordering 检查优先级，并找出当前最高优先级的用户层 → 输出 ConfigLayerStack，或返回顺序错误。

调用关系：配置加载完成后会用它封装结果；很多测试和后续配置计算都从这个栈开始。

调用图：调用 1 个内部函数（verify_layer_ordering）；被 83 处调用（enterprise_layers_precede_user_and_override_system, load_config_layers_state, active_user_layer_is_highest_precedence_user_layer, origins_use_canonical_key_aliases, with_user_config_updates_matching_user_layer_without_replacing_active_profile, policy_from_config_parts, configured_plugins_from_stack_merges_user_layers, hooks_only_scope_shares_plugin_resolution_without_loading_other_capabilities, load_plugins_ignores_project_config_files, loads_skills_from_home_agents_dir_for_user_scope (+15 more)）。

fn with_user_and_project_exec_policy_rules_ignored(
        mut self,
        ignore_user_and_project_exec_policy_rules: bool,
    ) -> Self

作用：返回一份新的配置栈，标记执行策略要忽略用户和项目目录里的 .rules 文件。.rules 可以理解成控制命令能不能执行的规则文件。

数据流：输入是当前配置栈和一个布尔值 → 函数把 ignore_user_and_project_exec_policy_rules 字段改成这个值 → 输出修改后的配置栈。

调用关系：它通常在加载阶段根据选项设置；后面加载执行策略时会通过 ignore_user_and_project_exec_policy_rules 读取这个决定。

fn ignore_user_and_project_exec_policy_rules(&self) -> bool

作用：告诉调用方是否应该跳过用户和项目配置目录里的执行策略规则文件。

数据流：输入是当前配置栈 → 函数读取一个布尔字段 → 输出 true 或 false，不改动配置栈。

调用关系：load_exec_policy 会调用它，决定是否把用户/项目的 .rules 文件纳入执行安全策略。

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

fn with_startup_warnings(mut self, startup_warnings: Vec<String>) -> Self

作用：给配置栈附上启动时发现的警告。警告不是致命错误，但需要在启动后告诉用户或上层系统。

数据流：输入是当前配置栈和一组警告字符串 → 函数把 startup_warnings 设置为 Some → 输出带警告的新配置栈。

调用关系：配置加载器在构建栈时可能调用它；之后 load_config_with_layer_stack 可以读取这些警告并继续上报。

fn startup_warnings(&self) -> Option<&[String]>

作用：读取启动期间记录的警告列表。如果没有检查过警告，返回 None；检查过但没发现问题，则返回空列表。

数据流：输入是当前配置栈 → 函数把内部 Option<Vec<String>> 转成只读切片形式 → 输出可选的警告列表引用。

调用关系：load_config_with_layer_stack 会用它把配置栈上的启动警告带到最终加载结果里。

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

fn get_active_user_layer(&self) -> Option<&ConfigLayerEntry>

作用：找到当前真正可写的用户配置层。启用 profile 时，它会返回 profile 那层，而不是基础用户配置。

数据流：输入是当前配置栈 → 函数读取 user_layer_index，并按索引从 layers 里取配置层 → 输出可选的 ConfigLayerEntry 引用。

调用关系：计算覆盖信息、获取用户配置文件、构造可信配置栈等流程会用它；它依赖 ConfigLayerStack::new 时记录好的用户层索引。

调用图：被 3 处调用（compute_override_metadata, get_user_config_file, trusted_config_layer_stack）。

fn get_user_config_file(&self) -> Option<&AbsolutePathBuf>

作用：返回当前活动用户配置层对应的文件路径。如果当前没有用户层，或活动层不是用户来源，就返回空。

数据流：输入是当前配置栈 → 函数先调用 get_active_user_layer，再确认来源是 User 并取出 file → 输出可选的绝对路径引用。

调用关系：它是 get_active_user_layer 的更具体版本，给只关心“要写哪个用户配置文件”的调用方使用。

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

fn get_user_layers(
        &self,
        ordering: ConfigLayerStackOrdering,
        include_disabled: bool,
    ) -> Vec<&ConfigLayerEntry>

作用：取出所有用户配置层，并按调用方要求的优先级顺序排列。启用 profile 时，基础用户配置和 profile 覆盖层都会被包含。

数据流：输入是排序方式和是否包含禁用层 → 函数先调用 get_layers 拿到全部符合条件的层，再筛选来源为 User 的层 → 输出用户配置层引用列表。

调用关系：effective_user_config 会用它只合并用户自己的配置；它把“从整栈筛选用户层”的细节集中在一个地方。

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

fn effective_user_config(&self) -> Option<TomlValue>

作用：只合并用户配置层，得到“用户自己实际设置了什么”。它不把系统、公司、项目或启动参数混进来。

数据流：输入是当前配置栈 → 函数按从低到高的顺序取用户层；如果没有用户层就返回 None；否则从空 TOML 表开始，把每层用户配置依次合并进去 → 输出合并后的用户 TOML。

调用关系：插件、市场源和 Git marketplace 等只关心用户配置的流程会调用它；合并动作交给 merge_toml_values。

调用图：调用 2 个内部函数（merge_toml_values, get_user_layers）；被 4 处调用（installed_marketplace_roots_from_layer_stack, configured_plugins_from_stack, configured_plugins_from_stack, configured_git_marketplaces）；外部调用 2 个（Table, new）。

fn requirements(&self) -> &ConfigRequirements

作用：返回已经整理好的配置强制要求。requirements 可以理解成“哪些配置必须满足公司或系统规定”。

数据流：输入是当前配置栈 → 函数直接返回 requirements 的只读引用 → 输出 ConfigRequirements 引用，不改动状态。

调用关系：加载最终配置、网络代理、安全执行策略、插件 MCP 服务要求、调试输出等流程都会读取它，用来套用强制规则。

调用图：被 6 处调用（apply_plugin_mcp_server_requirements, load_config_with_layer_stack, network_proxy_spec_for_active_permission_profile, load_exec_policy, append_managed_requirement_handlers, render_debug_config_lines）。

fn requirements_toml(&self) -> &ConfigRequirementsToml

作用：返回原始 requirements.toml 形式的要求数据。它保留更接近文件原貌的信息，方便 API 或调试展示。

数据流：输入是当前配置栈 → 函数直接返回 requirements_toml 的只读引用 → 输出 ConfigRequirementsToml 引用。

调用关系：受保护功能键、托管网络要求、最终配置加载和调试输出会用它；它和 requirements 不同，偏向“展示原始来源”，不是只给执行判断用。

调用图：被 5 处调用（protected_feature_keys, new, load_config_with_layer_stack, managed_network_requirements_enabled, render_debug_config_lines）。

fn with_user_config(&self, config_toml: &AbsolutePathBuf, user_config: TomlValue) -> Self

作用：用一份新的用户配置替换栈中对应的用户层。如果这个文件属于某个 profile，它会尽量保留这个 profile 信息。

数据流：输入是用户配置文件路径和新的 TOML 内容 → 函数在现有层中寻找同一路径的用户层，提取 profile 名；然后把工作交给 with_user_config_profile → 输出更新后的配置栈。

调用关系：trusted_config_layer_stack 会用它把可信后的用户配置放回栈里；它主要负责自动识别 profile，再调用更底层的 with_user_config_profile。

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

fn with_user_config_profile(
        &self,
        config_toml: &AbsolutePathBuf,
        profile: Option<&ProfileV2Name>,
        user_config: TomlValue,
    ) -> Self

作用：按指定文件和 profile 创建或替换用户配置层，并把它插回正确的优先级位置。

数据流：输入是用户配置文件路径、可选 profile 名和新的 TOML 内容 → 函数先创建一个 User 来源的 ConfigLayerEntry，删除栈中同文件旧层，再按优先级插入新层，最后重新计算最高优先级用户层索引 → 输出新的 ConfigLayerStack，保留 requirements、警告等其他信息。

调用关系：ConfigLayerStack::with_user_config 会调用它；它内部用 ConfigLayerEntry::new 造新层，是更新用户配置时真正重排栈的地方。

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

fn with_user_layer_from(&self, other: &Self) -> Self

作用：把另一个配置栈里的用户配置层复制到当前栈，同时保留当前栈自己的系统、托管、项目等非用户层。

数据流：输入是当前配置栈和另一个配置栈 → 函数从 other 里收集所有 User 层，从当前栈里保留非 User 层，然后把用户层按优先级插入进去，并重新计算用户层索引 → 输出新的配置栈。

调用关系：它适合需要“换掉用户设置，但别动其他环境配置”的场景；不调用合并逻辑，只重组层列表。

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

fn effective_config(&self) -> TomlValue

作用：把所有启用的普通配置层合并成最终配置视图。这里不合并 requirements，因为强制要求是单独处理的。

数据流：输入是当前配置栈 → 函数从空 TOML 表开始，按低优先级到高优先级取启用层，并逐层合并；高层同名设置会覆盖低层 → 输出最终合并后的 TOML 配置。

调用关系：应用配置、技能开关、网络代理、工具建议等功能会调用它获取“普通配置最终长什么样”；实际合并交给 merge_toml_values。

调用图：调用 2 个内部函数（merge_toml_values, get_layers）；被 6 处调用（protected_feature_keys, apps_config_from_layer_stack, bundled_skills_enabled_from_stack, deserialize_effective_config, network_proxy_spec_for_active_permission_profile, resolve_tool_suggest_config_from_layer_stack）；外部调用 2 个（Table, new）。

fn origins(&self) -> HashMap<String, ConfigLayerMetadata>

作用：告诉调用方最终配置里的每个字段来自哪一层。它像给每个配置项贴上“来源标签”。

数据流：输入是当前配置栈 → 函数按低到高遍历启用层，先把别名键规范化，再把每个字段路径和这一层的元信息记录到表里；后面的高优先级层会覆盖来源记录 → 输出字段路径到 ConfigLayerMetadata 的映射。

调用关系：它调用 normalized_with_key_aliases 处理老名字/别名，再调用 record_origins 记录来源；适合调试和对外说明为什么某个配置值是现在这样。

调用图：调用 3 个内部函数（record_origins, normalized_with_key_aliases, get_layers）；外部调用 2 个（new, new）。

fn layers_high_to_low(&self) -> Vec<&ConfigLayerEntry>

作用：按从最高优先级到最低优先级返回启用的配置层。适合查找“哪个层最先决定了某件事”。

数据流：输入是当前配置栈 → 函数调用 get_layers，指定最高优先级在前，并排除禁用层 → 输出配置层引用列表。

调用关系：find_effective_layer 会用它从最有决定权的层开始找；它只是 get_layers 的常用封装。

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

fn get_layers(
        &self,
        ordering: ConfigLayerStackOrdering,
        include_disabled: bool,
    ) -> Vec<&ConfigLayerEntry>

作用：按指定顺序取出配置层，并决定要不要包含被禁用的层。这是很多查询配置层功能的基础工具。

数据流：输入是排序方式和 include_disabled 开关 → 函数先从 layers 里过滤出需要的层；如果要求最高优先级在前，就把列表反转 → 输出配置层引用列表。

调用关系：effective_config、get_user_layers、origins、技能配置、项目根标记、插件根目录等很多流程都通过它拿层列表；它集中处理排序和禁用过滤，避免各处重复写。

调用图：被 17 处调用（first_layer_config_error, effective_config, get_user_layers, layers_high_to_low, origins, skill_config_rules_from_stack, project_root_markers_from_stack, skill_roots_from_layer_stack_inner, rebuild_preserving_session_layers, load_agent_roles (+7 more)）。

fn verify_layer_ordering(layers: &[ConfigLayerEntry]) -> std::io::Result<Option<usize>>

作用：检查配置层是不是按规定顺序排列，并找出最高优先级的用户层位置。没有这个检查，后面的覆盖规则可能悄悄算错。

数据流：输入是一组配置层 → 函数先检查整体是否按来源优先级排序；再检查多个项目层是否从项目根目录到当前目录排列；同时记录最后一个用户层的索引 → 输出用户层索引，或返回说明顺序错误的 IO 错误。

调用关系：ConfigLayerStack::new 创建配置栈时一定会调用它；它是配置栈进入系统前的“验货员”，确保后续合并和查找都建立在正确顺序上。

调用图：被 1 处调用（new）；外部调用 3 个（new, iter, matches!）。

fn record_origins(
    value: &TomlValue,
    meta: &ConfigLayerMetadata,
    path: &mut Vec<String>,
    origins: &mut HashMap<String, ConfigLayerMetadata>,
)

作用：这个函数会遍历一份 TOML 配置，把每个真正的配置值对应的“来源信息”记下来。它的作用是让系统之后能回答：这个配置项是从哪个配置层来的。

数据流：进去的是一段 TOML 值、当前配置层的元信息、一条正在走的路径，以及一张用来保存结果的表。它如果看到表，就继续走每个键；如果看到数组，就把下标也放进路径；如果走到普通值，就把类似 a.b.0.c 这样的路径和来源信息存进表里。出来时没有返回值，但 origins 这张表会被填好，path 会在递归进出时保持干净。

调用关系：它是在构建配置来源信息时被 origins 调用的。它自己不把工作交给别的项目内函数，只是在递归调用自己，并在需要保存来源时克隆一份元信息，像给每个叶子配置项盖一个来源章。

调用图：被 1 处调用（origins）；外部调用 1 个（clone）。

fn version_for_toml(value: &TomlValue) -> String

作用：这个函数给一份 TOML 配置生成稳定的版本号，也就是配置内容的指纹。有人会用它来判断两份配置是不是内容相同，而不是看文件文字是不是一模一样。

数据流：进去的是一份 TOML 配置。它先把 TOML 转成 JSON，失败就当成空值；再交给 canonical_json 把 JSON 对象的键统一排序；然后把排序后的 JSON 序列化成字节；最后用 SHA-256 算出哈希，并转成 sha256:xxxx 这样的字符串。出来的是这个指纹字符串，原配置不会被改动。

调用关系：它会在配置对象创建时被 new、new_disabled、new_with_raw_toml 调用，用来给当前配置打版本标记。它把“整理顺序”的活交给 canonical_json，再调用外部库完成 JSON 转换、字节序列化和哈希计算。

调用图：调用 1 个内部函数（canonical_json）；被 3 处调用（new, new_disabled, new_with_raw_toml）；外部调用 4 个（new, format!, to_value, to_vec）。

fn canonical_json(value: &JsonValue) -> JsonValue

作用：这个函数把 JSON 整理成固定顺序，特别是把对象里的键按字母排序。这样同样内容的配置，不会因为书写顺序不同而算出不同指纹。

数据流：进去的是一个 JSON 值。它如果看到对象，就取出所有键、排序，然后按排序后的顺序递归整理每个值；如果看到数组，就按原顺序整理数组里的每一项；如果是数字、字符串、布尔值等普通值，就直接复制出来。出来的是一份内容相同但顺序更稳定的 JSON。

调用关系：它只被 version_for_toml 调用，是生成配置指纹前的“整理台”。version_for_toml 需要它先把结构摆正，之后才能把 JSON 变成字节并计算哈希。

调用图：被 1 处调用（version_for_toml）；外部调用 3 个（Array, Object, new）。

fn merge_toml_values(base: &mut TomlValue, overlay: &TomlValue)

作用：这是对外使用的入口函数，用来把一份覆盖配置合进基础配置里。调用者只要把“底稿”和“新配置”交给它，它就会按规则修改底稿。

数据流：进去的是一个可修改的 base 配置和一个只读取的 overlay 配置；它先准备一个空路径，用来记录当前合并到配置树的哪个位置；然后把真正的递归合并工作交给 merge_toml_values_at_path。出来时没有单独返回值，但 base 已经被改成合并后的最终配置。

调用关系：它会被 load_config_layers_state、merge_permission_profiles、compose、effective_config、effective_user_config 等配置组装流程调用。它自己不做复杂判断，只负责开启合并流程，并把活儿交给 merge_toml_values_at_path。

调用图：调用 1 个内部函数（merge_toml_values_at_path）；被 5 处调用（load_config_layers_state, merge_permission_profiles, compose, effective_config, effective_user_config）；外部调用 1 个（new）。

fn merge_toml_values_at_path(base: &mut TomlValue, overlay: &TomlValue, path: &mut Vec<String>)

作用：这是实际干合并活儿的函数，会沿着配置的层级往下走，决定哪些地方继续合并、哪些地方直接覆盖。它还会在合并时统一配置键的别名和特殊域名写法。

数据流：进去的是当前要合并的 base 片段、overlay 片段，以及当前所在的路径。它先判断两边是不是都是表格：如果都是，就先把键名别名标准化，再在需要时把网络域名键标准化，然后逐个处理 overlay 里的键；已有键就递归合并，新键就标准化后插入。若两边不都是表格，它就把 base 当前这一块直接替换成标准化后的 overlay。出来时 base 的对应片段已经被更新，path 在进入和离开子项时会临时变化但最终恢复。

调用关系：它由 merge_toml_values 启动，是整个合并过程的核心。合并过程中，它会调用 normalize_key_aliases 和 normalized_with_key_aliases 来统一别名；会调用 is_permission_network_domains_path 判断当前是不是网络权限域名位置；如果是，就调用 normalize_network_domain_keys 统一域名键。

调用图：调用 4 个内部函数（normalize_key_aliases, normalized_with_key_aliases, is_permission_network_domains_path, normalize_network_domain_keys）；被 1 处调用（merge_toml_values）。

fn is_permission_network_domains_path(path: &[String]) -> bool

作用：这个函数用来判断当前合并位置是不是“权限配置里的网络域名列表”。只有在这个位置，域名键才需要用专门规则标准化。

数据流：进去的是一串路径片段，比如表示当前走到了配置树的哪一层；它检查这串路径是否符合 permissions → 某个权限名 → network → domains 这种结构。出来的是 true 或 false，告诉调用者这里是不是网络域名配置区域。

调用关系：它只被 merge_toml_values_at_path 调用。merge_toml_values_at_path 在每次处理表格时先问它“这里是不是域名列表”，如果答案是是，才会继续调用 normalize_network_domain_keys。

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

fn normalize_network_domain_keys(table: &mut toml::map::Map<String, TomlValue>)

作用：这个函数把网络域名表里的键统一成规范写法。这样用户即使用不同大小写或不同主机名写法，后续权限判断也能按同一种格式处理。

数据流：进去的是一个可修改的 TOML 表格，表格里的键是域名或域名模式，值是对应配置。它先把表格内容整体取出来清空，再逐项把原来的域名键交给 normalize_host 转成规范格式，最后用规范后的键重新插回表格。出来时原表格还在，但键名已经被标准化，值保持对应关系。

调用关系：它由 merge_toml_values_at_path 在特定路径下调用，也就是只在权限网络域名配置那里工作。它把具体的主机名规范化交给 normalize_host，自己负责把表格拆开、改键、再装回去。

调用图：被 1 处调用（merge_toml_values_at_path）；外部调用 3 个（insert, normalize_host, take）。

fn default_empty_table() -> TomlValue

作用：创建一个空的 TOML 表，也就是一张还没有任何配置项的空配置表。别的函数会拿它当作命令行覆盖配置的起点。

数据流：进去时不需要任何输入 → 它调用 TOML 库创建一个默认的空表 → 出来的是一个 TomlValue::Table，也就是可以继续往里面塞配置项的空 TOML 值。

调用关系：它是搭建覆盖层的第一步。build_cli_overrides_layer 会先调用它拿到空根节点，然后再把每条命令行覆盖项填进去。

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

fn build_cli_overrides_layer(cli_overrides: &[(String, TomlValue)]) -> TomlValue

作用：把一组命令行传来的“路径和值”变成一整棵 TOML 配置树。这样后面的配置加载流程就可以把这棵树当成一个独立配置层来合并。

数据流：进去的是一组 (路径, 值)，路径像 a.b.c，值是 TOML 能表示的数字、字符串、表等 → 它先创建空表，再逐条把每个路径和值交给 apply_toml_override 放到正确位置 → 出来的是一个 TOML 根值，里面包含所有命令行覆盖项；它不会改动输入列表本身，只会生成新结果。

调用关系：它被 load_config_layers_state 在加载配置层时调用。它自己负责总流程：先找 default_empty_table 要一个空表，再反复请 apply_toml_override 把每条覆盖写进去。

调用图：调用 2 个内部函数（apply_toml_override, default_empty_table）；被 1 处调用（load_config_layers_state）。

fn apply_toml_override(root: &mut TomlValue, path: &str, value: TomlValue)

作用：把一条单独的点号路径配置写进 TOML 树里。比如把 database.host 和某个值，放到 database 表下面的 host 项里。

数据流：进去的是一个可修改的 TOML 根节点、一条用点号分隔的路径、以及要写入的值 → 它按点号把路径拆成多段，从根节点一层层往下走；中间缺表就创建表，走到最后一段就写入新值 → 出来时没有单独返回值，但传入的 TOML 根节点已经被改好，包含这条覆盖配置。

调用关系：它是实际动手写入的底层函数。build_cli_overrides_layer 每处理一条命令行覆盖项，就调用它一次；它不再调用项目里的其他函数，只使用 TOML 库来创建表。

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

fn new(
        code: ThreadConfigLoadErrorCode,
        status_code: Option<u16>,
        message: impl Into<String>,
    ) -> Self

作用：创建一个线程配置加载错误。调用方用它把“出了什么类的问题、有没有 HTTP 状态码、给人看的错误信息”打包成一个统一错误。

数据流：进去的是错误类别、可选状态码和一段错误说明；它把说明转成字符串，连同类别和状态码放进 ThreadConfigLoadError；出来的是一个可传递、可显示的错误对象。

调用关系：它是错误入口工具。远程加载、解析错误处理和把远程状态转换成错误时都会用它，这样不同地方报错时长得一样，后面的人不用猜错误格式。

调用图：被 3 处调用（load, parse_error, remote_status_to_error）；外部调用 1 个（into）。

fn code(&self) -> ThreadConfigLoadErrorCode

作用：取出错误的大类，比如认证失败、超时、解析失败。调用方可以不用读错误文字，就知道该怎么处理。

数据流：进去的是一个已经创建好的错误对象；它读取里面的 code 字段；出来的是稳定的 ThreadConfigLoadErrorCode 枚举值，不改动原错误。

调用关系：它通常在上层决定恢复策略时使用，比如看到 Auth 就提示登录，看到 Timeout 就考虑重试。它不调用别的本文件函数，只负责安全地暴露错误类别。

fn status_code(&self) -> Option<u16>

作用：取出错误里带的 HTTP 状态码，如果有的话。HTTP 状态码就是服务器返回的数字结果，比如 401 表示未授权。

数据流：进去的是一个错误对象；它读取 status_code 字段；出来的是一个可选数字，有就返回 Some，没有就返回 None，不改动任何内容。

调用关系：它给调用方补充更细的信息，尤其是远程配置加载失败时有用。它和 code 搭配，一个说大类，一个说服务器具体返回了什么。

fn load_config_layers(
        &self,
        context: ThreadConfigContext,
    ) -> ThreadConfigLoaderFuture<'_, Vec<ConfigLayerEntry>>

作用：把加载器拿到的线程配置，转换成系统通用的配置层。多数调用方应该用它，而不是直接用 load，因为它会把线程配置接入原来的配置合并流程。

数据流：进去的是线程上下文，比如线程 ID 或当前目录；它先调用同一个加载器的 load 拿到多个 ThreadConfigSource，再逐个交给 thread_config_source_to_layer 转成 ConfigLayerEntry，并丢掉空结果；出来的是可以放进配置栈的一组配置层，失败时出来的是加载错误。

调用关系：它是 trait 里的默认流程，像一条传送带：具体加载器只负责“取货”，它负责把货物包装成配置层。内部用异步 Future，所以加载可以等待网络或其他慢操作。

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

fn new(sources: Vec<ThreadConfigSource>) -> Self

作用：创建一个固定内容的线程配置加载器。它常用于测试，或者某些已经提前知道配置、不需要去远程取的场景。

数据流：进去的是一组现成的 ThreadConfigSource；它把这些来源保存到 StaticThreadConfigLoader 里；出来的是一个以后每次加载都会返回同样内容的加载器。

调用关系：测试里会用它搭出可预测的配置环境，也有配置派生流程会用它验证会话线程配置是否生效。它本身不加载网络，只是给 StaticThreadConfigLoader::load 准备数据。

调用图：被 4 处调用（derive_config_from_params_uses_session_thread_config_model_provider, loader_returns_session_and_user_sources, loader_translates_sources_to_config_layers, includes_thread_config_layers_in_stack）。

fn load(
        &self,
        _context: ThreadConfigContext,
    ) -> ThreadConfigLoaderFuture<'_, Vec<ThreadConfigSource>>

作用：从固定加载器里返回预先存好的线程配置。它的价值是简单、可预测，适合测试或静态配置。

数据流：进去的是线程上下文，但这个实现不使用它；它克隆自己保存的 sources；出来的是这些配置来源的副本，包在异步结果里。

调用关系：这是 StaticThreadConfigLoader 对 ThreadConfigLoader 接口的实现。上层调用 load_config_layers 时会先走到这里，再把返回的来源转换成配置层。

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

fn load(
        &self,
        _context: ThreadConfigContext,
    ) -> ThreadConfigLoaderFuture<'_, Vec<ThreadConfigSource>>

作用：什么配置都不加载，直接返回空列表。它用于没有外部线程配置来源时，让系统仍然能按同一套接口运行。

数据流：进去的是线程上下文，但它不读取；它创建一个空 Vec；出来的是成功结果，里面没有任何配置来源，也不会改动系统状态。

调用关系：它是“空实现”，像插座上的保护盖：没有外部配置时也能占住接口位置。上层仍然可以调用 load_config_layers，只是最后得到空配置层。

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

fn thread_config_source_to_layer(
    source: ThreadConfigSource,
) -> Result<Option<ConfigLayerEntry>, ThreadConfigLoadError>

作用：把一个有类型的线程配置来源，翻译成系统配置栈认识的 ConfigLayerEntry。也就是说，把“这是谁给的配置”变成“系统该按哪一层来合并”。

数据流：进去的是一个 ThreadConfigSource；如果是 Session，就先交给 session_thread_config_to_toml 变成 TOML 配置，再检查是否为空，非空就包成 SessionFlags 配置层；如果是 User，目前还没有可写入 TOML 的字段，所以返回空；出来的是可选配置层或错误。

调用关系：它被 ThreadConfigLoader::load_config_layers 批量调用，是来源配置进入普通配置栈前的翻译员。它会调用 is_empty_table 避免制造空层，也会调用 session_thread_config_to_toml 做具体格式转换。

调用图：调用 3 个内部函数（new, is_empty_table, session_thread_config_to_toml）。

fn is_empty_table(config: &TomlValue) -> bool

作用：判断一份 TOML 配置是不是空表。空表就像一张没有任何内容的表格，放进配置栈没有意义。

数据流：进去的是一个 TOML 值；它先看这个值是不是表，再看表里有没有键；出来的是布尔值，true 表示这是空表。

调用关系：它由 thread_config_source_to_layer 调用，用来决定要不要生成 ConfigLayerEntry。这样可以避免把没有实际内容的 Session 配置塞进后续流程。

调用图：被 1 处调用（thread_config_source_to_layer）；外部调用 1 个（as_table）。

fn session_thread_config_to_toml(
    config: SessionThreadConfig,
) -> Result<TomlValue, ThreadConfigLoadError>

作用：把会话拥有的线程配置转成 TOML。TOML 是一种常见配置文件格式，类似“键 = 值”和分组表格。

数据流：进去的是 SessionThreadConfig，里面可能有模型提供方名称、模型提供方详情和功能开关；它新建一张 TOML 表，有值才写入对应字段，把功能开关写成布尔值，把模型提供方详情尝试序列化；出来的是 TOML 表。如果模型提供方详情不能转换，就出来一个 Parse 类型的 ThreadConfigLoadError。

调用关系：它被 thread_config_source_to_layer 调用，是 Session 配置转成普通配置层的核心步骤。转换失败时会用 ThreadConfigLoadError::new 包装成统一错误。

调用图：被 1 处调用（thread_config_source_to_layer）；外部调用 4 个（String, Table, try_from, new）。

async fn loader_returns_session_and_user_sources()

作用：测试固定加载器会原样返回会话配置和用户配置。它确保 StaticThreadConfigLoader 不会偷偷改内容或丢内容。

数据流：进去的是测试里手工构造的 StaticThreadConfigLoader 和线程 ID；测试调用 load；出来的是加载结果，然后和预期的两个配置来源逐项比较。

调用关系：它通过 StaticThreadConfigLoader::new 建立测试对象，再调用加载接口。这个测试守住最基础承诺：静态加载器保存什么，就返回什么。

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

async fn loader_translates_sources_to_config_layers()

作用：测试线程配置来源能正确转换成配置层。它确认用户空配置会被忽略，而会话配置会变成 SessionFlags 这一层。

数据流：进去的是包含一个空用户配置和一个会话配置的固定加载器，以及一个临时项目目录；测试调用 load_config_layers；出来的是配置层列表，然后和手写的 TOML 配置层比较。

调用关系：它使用 StaticThreadConfigLoader::new 准备输入，再走 ThreadConfigLoader::load_config_layers 的完整转换路线。这个测试覆盖了 thread_config_source_to_layer、is_empty_table 和 session_thread_config_to_toml 配合后的效果。

调用图：调用 2 个内部函数（new, from_absolute_path_checked）；外部调用 4 个（default, assert_eq!, temp_dir, vec!）。

fn test_provider(name: &str) -> ModelProviderInfo

作用：生成一个测试用的模型提供方信息。这样测试里不用反复写一大堆字段，也能得到结构完整的 ModelProviderInfo。

数据流：进去的是提供方名称；它把名称、测试用 base_url、协议类型、认证要求、WebSocket 支持等字段填好；出来的是一个可放进 SessionThreadConfig 的 ModelProviderInfo。

调用关系：它被本文件测试拿来构造 model_providers。它不是生产流程的一部分，只是让测试数据更清楚、更少重复。

fn validate_bundle(
    bundle: &CloudConfigBundle,
    base_dir: &AbsolutePathBuf,
) -> Result<(), CloudConfigBundleLoadError>

作用：检查传进来的云端配置包是否有效。有人在读取缓存配置包或收到远程配置包后，会先调用它做把关，防止系统继续使用坏配置。

数据流：进去的是一份 CloudConfigBundle（云端配置包）和 base_dir（解析相对路径时用的基础目录）→ 它先复制一份配置包，并调用 from_bundle 把配置包拆成系统可检查的配置层；如果拆不开，就生成一个“InvalidBundle”的错误 → 然后取出企业下发的 requirements，并交给 compose_requirements 尝试合成；如果合成失败，也生成同样类型的无效配置错误 → 全部通过后，返回 Ok，表示这份配置包可以继续使用；它不会改动原始配置包。

调用关系：它处在配置进入系统前的质检环节。load_valid_cached_bundle 在使用本地缓存的配置包前会调用它，validate_and_cache_remote_bundle 在校验并缓存远程下载的配置包时也会调用它。它自己把具体检查工作交给 from_bundle 和 compose_requirements：前者负责把包展开成配置层，后者负责确认企业要求规则能正确组合。

调用图：调用 1 个内部函数（from_bundle）；被 2 处调用（load_valid_cached_bundle, validate_and_cache_remote_bundle）；外部调用 2 个（compose_requirements, clone）。

fn is_empty(&self) -> bool

作用：判断这个云端配置包是不是完全没有内容。调用者可以用它来决定“有没有必要继续处理云端配置”。

数据流：输入是一个 CloudConfigBundle 自身。它查看里面 config_toml 的 enterprise_managed 列表，以及 requirements_toml 的 enterprise_managed 列表；如果两个列表都为空，就返回 true，否则返回 false。它不改动任何数据。

调用关系：optional_bundle 会用它来判断可选的云端配置包是否真的有东西。它是一个很早期的筛子，避免后续流程为一个空包做无意义的转换。

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

fn from_bundle(
        bundle: CloudConfigBundle,
        base_dir: &AbsolutePathBuf,
    ) -> Result<Self, CloudConfigLayerError>

作用：把云端配置包转换成程序可合并的配置层，但采用普通模式：遇到某些配置问题时按常规规则处理。调用者拿到的不是最终配置，而是一批准备插入总配置栈的云端层。

数据流：输入是 CloudConfigBundle 和一个 base_dir（基础目录，用来解释相对路径）。它把这些参数交给内部的 from_bundle_impl，并告诉它不要使用严格配置检查；成功时得到 CloudConfigBundleLayers，失败时得到 CloudConfigLayerError。

调用关系：validate_bundle、bundle_layers_preserve_enterprise_managed_bucket_order 和 load_config_layers_state 会调用它。它自己不做细活，而是把活交给 from_bundle_impl，这样普通模式和严格模式可以共用同一套转换流程。

调用图：被 3 处调用（validate_bundle, bundle_layers_preserve_enterprise_managed_bucket_order, load_config_layers_state）；外部调用 1 个（from_bundle_impl）。

fn from_bundle_strict_config(
        bundle: CloudConfigBundle,
        base_dir: &AbsolutePathBuf,
    ) -> Result<Self, CloudConfigLayerError>

作用：把云端配置包转换成配置层，但开启严格配置检查。它适合需要更早、更明确发现云端配置错误的场景。

数据流：输入同样是 CloudConfigBundle 和 base_dir。它调用 from_bundle_impl，并把 strict_config 设为 true；如果云端配置片段不符合严格规则，转换会失败并返回 CloudConfigLayerError。

调用关系：bundle_layers_can_strict_validate_enterprise_managed_config 和 load_config_layers_state 会用它。它和 from_bundle 是一对入口：一个普通，一个严格，最后都汇入 from_bundle_impl。

调用图：被 2 处调用（bundle_layers_can_strict_validate_enterprise_managed_config, load_config_layers_state）；外部调用 1 个（from_bundle_impl）。

fn from_bundle_impl(
        bundle: CloudConfigBundle,
        base_dir: &AbsolutePathBuf,
        strict_config: bool,
    ) -> Result<Self, CloudConfigLayerError>

作用：真正完成“云端原始配置包 → 可合并配置层”的转换。它负责把配置碎片和要求碎片分开处理，并把它们整理成正确的优先级顺序。

数据流：输入是一个云端配置包、基础目录 base_dir，以及 strict_config 开关。它先拆开 bundle 中的 config_toml 和 requirements_toml；配置片段会根据 strict_config 选择调用 cloud_config_layers_from_fragments_strict 或 cloud_config_layers_from_fragments 来生成配置层；要求片段会变成 RequirementsLayerEntry，并带上来源信息和基础目录。最后它会把要求层列表反转，因为收到的顺序和合并需要的顺序相反；成功返回 CloudConfigBundleLayers，失败返回 CloudConfigLayerError。

调用关系：它是 from_bundle 和 from_bundle_strict_config 背后的共同加工车间。它把配置片段的解析工作交给 cloud_config_layers_from_fragments_strict 或 cloud_config_layers_from_fragments，自己负责整体拆包、组装和顺序调整。

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

fn new(
        code: CloudConfigBundleLoadErrorCode,
        status_code: Option<u16>,
        message: impl Into<String>,
    ) -> Self

作用：创建一个“加载云端配置失败”的错误对象。它把错误类别、HTTP 状态码和人能看懂的提示文字放在一起，方便上层判断要不要重新登录、要不要重试或怎样报错。

数据流：输入包括错误代码 code、可选的 status_code，以及 message。message 会被转换成 String，然后和其他信息一起存进 CloudConfigBundleLoadError。输出是一个新的错误值，不会改动外部状态。

调用关系：很多失败场景会调用它，比如 fetch_remote_bundle_and_update_cache_with_retries、handle_unauthorized，以及若干测试。它是统一造错误的地方，上层再通过 code 和 status_code 读取具体原因。

调用图：被 6 处调用（config_load_error_marks_cloud_config_bundle_failures_for_relogin, config_load_error_marks_invalid_cloud_config_bundle_failures_without_relogin, config_load_error_marks_non_auth_cloud_config_bundle_failures_without_relogin, fetch_remote_bundle_and_update_cache_with_retries, handle_unauthorized, load_config_layers_fails_when_cloud_config_bundle_loader_fails）；外部调用 1 个（into）。

fn code(&self) -> CloudConfigBundleLoadErrorCode

作用：取出云端配置加载失败的错误类别。调用者用它来区分是认证问题、超时、请求失败、包内容无效，还是内部错误。

数据流：输入是一个已有的 CloudConfigBundleLoadError。它读取内部保存的 code 字段，并把这个错误代码返回；不修改错误对象。

调用关系：它通常会在错误处理流程里被调用，用来决定下一步动作。例如认证错误可能提示重新登录，而普通请求失败可能只是显示错误或重试。

fn status_code(&self) -> Option<u16>

作用：取出加载失败时关联的 HTTP 状态码。HTTP 状态码就是服务器返回的数字结果，比如 401 表示未授权。

数据流：输入是一个 CloudConfigBundleLoadError。它读取内部的 status_code 字段；如果当时有服务器状态码，就返回 Some(数字)，否则返回 None。它不改动任何数据。

调用关系：它服务于更细的错误判断。错误处理代码可以先看 code 的大类，再用 status_code 判断服务器到底给了什么回应。

fn new(fut: F) -> Self

作用：创建一个共享的云端配置加载器。它把一个异步任务包装起来，让多个调用者等待同一次加载结果，而不是每个人都重新请求云端。

数据流：输入是一个 Future，也就是“以后会完成的异步任务”，结果类型是可能有 CloudConfigBundle，也可能失败。它把这个任务 boxed（装箱，变成统一大小、方便保存的对象），再 shared（共享，让多个等待者复用同一个结果），最后放进 CloudConfigBundleLoader 返回。

调用关系：cloud_config_bundle_loader、shared_future_runs_once、into_loader 和一些加载失败测试会创建它。它是 CloudConfigBundleLoader::get 的前置步骤：new 负责把任务存好，get 负责等待这个任务完成。

调用图：被 4 处调用（cloud_config_bundle_loader, shared_future_runs_once, into_loader, load_config_layers_fails_when_cloud_config_bundle_loader_fails）；外部调用 1 个（boxed）。

async fn get(&self) -> Result<Option<CloudConfigBundle>, CloudConfigBundleLoadError>

作用：等待共享加载器里的云端配置加载结果。调用者用它来拿到“有配置包、没有配置包、或加载失败”这三种结果之一。

数据流：输入是 CloudConfigBundleLoader 自身。它克隆内部共享任务的句柄，然后 await 等待完成；成功时返回 Option<CloudConfigBundle>，None 表示没有云端配置，失败时返回 CloudConfigBundleLoadError。它不会重新创建加载任务。

调用关系：它是实际取结果的入口。因为 new 已经把异步任务做成 shared，所以即使多个地方调用 get，也是在等同一个加载结果，而不是重复跑网络请求或读取动作。

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

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

作用：给 CloudConfigBundleLoader 提供调试打印方式。它让日志或调试工具能显示这个对象的名字，但不会暴露内部异步任务的细节。

数据流：输入是加载器和格式化器 f。它向格式化器写入一个名为 CloudConfigBundleLoader 的调试结构，然后返回格式化是否成功的结果；不读取云端配置，也不启动加载。

调用关系：这是 Rust 的 Debug 打印机制会用到的函数。它只负责“怎么显示这个对象”，和真正的配置加载流程分开。

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

fn default() -> Self

作用：提供一个默认加载器，表示“默认没有云端配置”。这让测试或不启用云端配置的运行方式不用额外写一套空实现。

数据流：没有外部输入。它创建一个立即成功的异步任务，结果是 Ok(None)，意思是没有云端配置包；然后调用 CloudConfigBundleLoader::new 把它包装成共享加载器并返回。

调用关系：很多启动和测试场景会用它，比如 runtime_start_args_forward_environment_manager、without_managed_config_for_tests、read_includes_origins_and_layers 等。它把“没有云端配置”做成和正常加载器同样的形状，这样后续流程不用写特殊分支。

调用图：被 34 处调用（runtime_start_args_forward_environment_manager, runtime_start_args_use_remote_thread_config_loader_when_configured, start_test_client_with_capacity, without_managed_config_for_tests, 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_reports_managed_override (+15 more)）；外部调用 1 个（new）。

fn source_ref(&self) -> CloudConfigFragmentSource

作用：这个函数从一整段云端配置里取出“来源名片”：只保留 id 和 name。这样报错时可以告诉人，究竟是哪一段云配置出问题，而不用带上整段配置正文。

数据流：进去的是一个 CloudConfigFragment，里面有 id、name 和 contents → 它复制 id 和 name，丢开 contents → 出来一个 CloudConfigFragmentSource，用来代表这段配置的来源。

调用关系：在真正解析配置前，cloud_config_layers_from_fragments_impl 会先调用它做一张来源名片。后面如果解析失败或严格校验失败，就用这张名片生成清楚的错误信息。

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

作用：这个函数规定云配置来源在文字里怎么显示。它把名称和 id 拼成类似“名称 (id)”的样子，方便错误信息让人一眼看懂。

数据流：进去的是一个 CloudConfigFragmentSource 和一个格式化输出位置 → 它把 name 和 id 写成固定格式 → 出来的是格式化结果，通常会进入错误消息或日志文字。

调用关系：严格校验时，validate_fragment_strictly 会把来源对象转成字符串；这个格式化函数就在那时发挥作用。它内部只把文字交给标准的 write! 写出。

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

fn cloud_config_layers_from_fragments(
    fragments: impl IntoIterator<Item = CloudConfigFragment>,
    base_dir: &AbsolutePathBuf,
) -> Result<Vec<ConfigLayerEntry>, CloudConfigLayerError>

作用：这是普通模式的入口：把云端配置片段转成配置层。普通模式会解析和修正路径，但不会因为有未知字段就报错。

数据流：进去的是一批 CloudConfigFragment 和一个云配置基础目录 base_dir → 它把这些原样交给内部实现，并说明不启用严格检查 → 出来是一组按配置栈顺序排好的 ConfigLayerEntry，或者一个说明哪段配置坏了的错误。

调用关系：调用者想正常加载云配置时会用它。它自己不做细节工作，而是把活交给 cloud_config_layers_from_fragments_impl，并传入 strict_config=false。

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

fn cloud_config_layers_from_fragments_strict(
    fragments: impl IntoIterator<Item = CloudConfigFragment>,
    base_dir: &AbsolutePathBuf,
) -> Result<Vec<ConfigLayerEntry>, CloudConfigLayerError>

作用：这是严格模式的入口：同样把云端配置片段转成配置层，但会额外检查有没有不被系统认识的配置字段。它适合在需要“配置必须完全正确”的场景使用。

数据流：进去的是云端配置片段和基础目录 → 它调用内部实现，并打开严格检查开关 → 出来是配置层列表，或者在解析错误、路径错误、未知字段等情况下返回错误。

调用关系：根据调用关系，它会被 from_bundle_impl 使用，说明它常用于从云配置包加载时的严格处理。它把具体解析、路径处理、倒序排列等工作交给 cloud_config_layers_from_fragments_impl。

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

fn cloud_config_layers_from_fragments_impl(
    fragments: impl IntoIterator<Item = CloudConfigFragment>,
    base_dir: &AbsolutePathBuf,
    strict_config: bool,
) -> Result<Vec<ConfigLayerEntry>, Cl

作用：这是本文件的核心流水线。它逐段读取云端配置，解析 TOML，必要时做严格检查，修正相对路径，再打包成配置层，并把顺序调成程序真正需要的顺序。

数据流：进去的是一批配置片段、一个基础目录、以及是否严格检查的开关 → 它对每段配置先做来源名片，再用 toml::from_str 把文本解析成结构化值；如果严格模式打开，就调用 validate_fragment_strictly；然后调用 resolve_relative_paths_in_config_toml 把相对路径按 base_dir 补好；最后用 ConfigLayerEntry::new_with_raw_toml 包成配置层 → 全部处理完后把列表反转，出来的是可放进配置栈的层列表；如果中间失败，就返回带片段来源的 Parse 或 Invalid 错误。

调用关系：cloud_config_layers_from_fragments 和 cloud_config_layers_from_fragments_strict 都只是它的两个入口包装。它在中间会把严格检查交给 validate_fragment_strictly，把路径修正交给 resolve_relative_paths_in_config_toml，把最终配置层创建交给 ConfigLayerEntry::new_with_raw_toml。

调用图：调用 4 个内部函数（validate_fragment_strictly, resolve_relative_paths_in_config_toml, new_with_raw_toml, as_path）；被 2 处调用（cloud_config_layers_from_fragments, cloud_config_layers_from_fragments_strict）；外部调用 3 个（new, from_str, clone）。

fn validate_fragment_strictly(
    source_ref: &CloudConfigFragmentSource,
    raw_toml: &str,
    value: &TomlValue,
    base_dir: &AbsolutePathBuf,
) -> Result<(), CloudConfigLayerError>

作用：这个函数专门做严格检查：确认云端配置里没有会被系统忽略的未知字段。这样可以避免管理员写错配置名却没有发现。

数据流：进去的是配置来源、原始 TOML 文本、已经解析出的 TOML 值，以及基础目录 → 它先用 AbsolutePathBufGuard 临时确认路径环境，再调用 config_error_from_ignored_toml_value_fields_for_source_name 按 ConfigToml 的规则检查未知字段 → 如果发现问题，出来的是 Invalid 错误；如果没问题，出来的是成功的空结果，不改动配置内容。

调用关系：只有 cloud_config_layers_from_fragments_impl 在 strict_config=true 时会调用它。它不负责解析，也不负责生成配置层，只在流水线中间当“质检员”。

调用图：调用 2 个内部函数（as_path, new）；被 1 处调用（cloud_config_layers_from_fragments_impl）；外部调用 3 个（clone, clone, to_string）。

fn from(error: CloudConfigLayerError) -> Self

作用：这个函数把本文件自己的云配置错误，转换成标准的 io::Error，也就是 Rust 里常见的输入输出错误类型。这样外层代码如果统一用 io::Error 处理错误，也能接住这里的问题。

数据流：进去的是 CloudConfigLayerError，里面说明解析失败或配置无效 → 它用 io::Error::new 包装成 InvalidData 类型的标准错误 → 出来的是 io::Error，原来的错误内容仍然被保留下来。

调用关系：它是错误类型之间的桥梁。云配置解析流程内部会产生 CloudConfigLayerError；当外部接口需要标准 io::Error 时，就通过这个转换函数交出去。

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

async fn load_config_layers_internal(
    fs: &dyn ExecutorFileSystem,
    codex_home: &Path,
    overrides: LoaderOverrides,
    strict_config: bool,
) -> io::Result<LoadedConfigLayers>

作用：这是本文件的主入口，用来一次性加载所有“管理员配置层”。它会读系统配置文件，并在 macOS 上顺便读取 MDM 下发的配置。

数据流：进去的是文件系统接口、codex_home 目录、加载时的覆盖参数，以及是否严格检查配置。它先从覆盖参数或默认规则里算出管理员配置文件路径，把路径确认成绝对路径，再调用 read_config_from_path 读取和解析文件；在 macOS 上还会调用 load_managed_admin_config_layer 读取 MDM 配置。出来的是 LoadedConfigLayers，里面可能有文件配置、可能有 MDM 配置，也可能两者都没有；如果路径不合法、文件内容坏了或读取失败，就返回错误。

调用关系：它被 load_config_layers_state 调用，属于更大配置加载流程中的“把外部配置拿回来”阶段。它自己不解析所有业务含义，而是把读文件的活交给 read_config_from_path，把 macOS 管理配置的活交给 load_managed_admin_config_layer，最后把结果装成统一结构交回上层。

调用图：调用 3 个内部函数（read_config_from_path, load_managed_admin_config_layer, from_absolute_path）；被 1 处调用（load_config_layers_state）。

fn map_managed_admin_layer(layer: ManagedAdminConfigLayer) -> ManagedConfigFromMdm

作用：这个函数只在 macOS 上使用，用来把 macOS 管理配置读取出来的结果，换成这个文件内部统一使用的格式。

数据流：进去的是 ManagedAdminConfigLayer，里面有已经解析好的配置值和原始 TOML 文本。它把两个字段拆出来，重新装进 ManagedConfigFromMdm。出来的是更贴合本文件返回结构的 MDM 配置对象，不额外修改内容。

调用关系：它接在 load_managed_admin_config_layer 后面使用。前者负责真正从 macOS 管理偏好里拿数据，这个函数只是做一次“换包装”，方便 load_config_layers_internal 把文件配置和 MDM 配置一起放进 LoadedConfigLayers。

async fn read_config_from_path(
    fs: &dyn ExecutorFileSystem,
    path: &AbsolutePathBuf,
    log_missing_as_info: bool,
    strict_config: bool,
) -> io::Result<Option<TomlValue>>

作用：这个函数负责从指定路径读取一个 TOML 配置文件，并把它变成程序能处理的配置值。它也会区分“文件不存在”和“文件坏了”：不存在可以继续，用默认值；坏了就必须报错。

数据流：进去的是文件系统接口、一个绝对路径、缺文件时日志级别的选择，以及是否开启严格检查。它先把路径转成文件系统接口能理解的 URI，然后读文本；读到后用 TOML 解析器解析。解析成功时，如果要求严格检查，就调用 validate_config_toml_strictly 再验一遍字段；最后返回 Some(配置值)。如果文件不存在，记录日志并返回 None。如果解析失败，会把 TOML 错误转换成带位置和上下文的配置错误；如果读取失败，则直接把读文件错误返回。

调用关系：它由 load_config_layers_internal 调用，是加载管理员配置文件的核心小工。它会调用文件系统的 read_file_text 真正读磁盘，调用 validate_config_toml_strictly 做严格检查，并借助 config_error_from_toml、io_error_from_config_error 把底层错误包装成用户更能看懂的配置错误。

调用图：调用 6 个内部函数（config_error_from_toml, io_error_from_config_error, validate_config_toml_strictly, read_file_text, as_path, from_abs_path）；被 1 处调用（load_config_layers_internal）；外部调用 3 个（debug!, error!, info!）。

fn validate_config_toml_strictly(
    path: &AbsolutePathBuf,
    contents: &str,
    value: &TomlValue,
) -> io::Result<()>

作用：这个函数在“严格配置”模式下使用，用来发现配置文件里那些程序不认识、可能是写错的字段。这样能避免用户以为配置生效了，其实程序默默忽略了。

数据流：进去的是配置文件路径、原始文本内容，以及已经解析出的 TOML 值。它先确认这个文件有父目录，并临时把这个目录设成解析相对路径时的基准。然后调用 config_error_from_ignored_toml_value_fields，用 ConfigToml 这份正式配置结构来检查是否有多余字段。没有问题就返回成功；发现问题就把配置错误转成 io::Error 返回。

调用关系：它只被 read_config_from_path 在 strict_config 为真时调用。read_config_from_path 负责读和解析文件；这个函数负责“挑错”，专门防止未知字段被忽略。发现错误后，它通过 io_error_from_config_error 把问题交回上层加载流程。

调用图：调用 3 个内部函数（io_error_from_config_error, as_path, new）；被 1 处调用（read_config_from_path）；外部调用 3 个（clone, new, format!）。

fn managed_config_default_path(codex_home: &Path) -> PathBuf

作用：这个函数给出管理员配置文件的默认位置。调用方没有明确指定路径时，就靠它决定去哪找配置。

数据流：进去的是 codex_home 目录。Unix 系统上，它忽略这个目录，直接返回 /etc/codex/managed_config.toml；非 Unix 系统上，它返回 codex_home/managed_config.toml。出来的是一个 PathBuf，也就是可拥有的文件路径对象。

调用关系：它被 load_config_layers_internal 用在没有覆盖路径的时候。这样上层不必关心不同操作系统的默认位置差异，只要问这个函数要一个默认路径，再交给 read_config_from_path 去读取即可。

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

fn managed_preferences_requirements_source() -> RequirementSource

作用：这个函数生成一个“来源标签”，说明 requirements 内容是从 macOS 受管偏好设置里来的。这样后面如果报错，系统能说清楚是哪一个管理域和键出了问题。

数据流：进去时不需要外部输入 → 它把固定的应用标识 com.openai.codex 和 requirements_toml_base64 这个键名包装成 RequirementSource → 出来的是一个带有来源信息的对象，供后续 requirements 层使用。

调用关系：它是 requirements 加载流程里的身份牌制造器。load_managed_admin_requirements_layer 拿到 requirements 文本后，会用它给这份文本标明来源。

async fn load_managed_admin_config_layer(
    override_base64: Option<&str>,
    strict_config: bool,
    base_dir: &Path,
) -> io::Result<Option<ManagedAdminConfigLayer>>

作用：这个异步函数负责加载管理员下发的主配置层。调用方只要问它“有没有管理员配置”，它就会返回没有、成功解析后的配置，或者一个可说明原因的错误。

数据流：进去的是可选的 base64 覆盖值、是否严格检查、以及配置相关的基础目录 → 如果给了覆盖值，它先去掉首尾空白，空字符串就当作没有配置，否则直接解析；如果没给覆盖值，它把读取 macOS 偏好设置的工作丢到后台阻塞任务里 → 出来的是 Option：有配置就返回 ManagedAdminConfigLayer，没有就返回 None；如果后台任务崩了或解析失败，就返回 io 错误。

调用关系：它被 load_config_layers_internal 在组装所有配置层时调用。它自己不直接碰 macOS 系统接口，而是把这件事交给 load_managed_admin_config；拿到 base64 内容后，再交给 parse_managed_config_base64 解析。

调用图：调用 1 个内部函数（parse_managed_config_base64）；被 1 处调用（load_config_layers_internal）；外部调用 4 个（to_path_buf, other, spawn_blocking, error!）。

fn load_managed_admin_config(
    strict_config: bool,
    base_dir: &Path,
) -> io::Result<Option<ManagedAdminConfigLayer>>

作用：这个函数实际去读取 macOS 里的管理员配置值，并把它转成配置层。它是同步函数，所以通常被放到后台任务里跑，避免卡住主流程。

数据流：进去的是严格检查开关和基础目录 → 它用固定键名读取 macOS 受管偏好设置；如果没读到，就返回 None；如果读到了，就去掉空白并解析 base64 里的 TOML → 出来的是可选的 ManagedAdminConfigLayer，或者读取、解码、解析时产生的错误。

调用关系：它由 load_managed_admin_config_layer 放进 spawn_blocking 后台任务调用。它负责拿原始字符串，真正的系统读取交给 load_managed_preference，真正的配置解析交给 parse_managed_config_base64。

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

async fn load_managed_admin_requirements_layer(
    override_base64: Option<&str>,
) -> io::Result<Option<RequirementsLayerEntry>>

作用：这个异步函数负责加载管理员下发的 requirements 内容。requirements 可以理解成管理员给运行环境加的一组额外要求或约束。

数据流：进去的是可选的 base64 覆盖值 → 如果有覆盖值，去掉空白后为空就返回 None，不为空就解码；如果没有覆盖值，就在后台任务里读取 macOS 受管偏好设置 → 出来的是可选的 RequirementsLayerEntry；读取失败、后台任务失败或解码失败时返回 io 错误。

调用关系：它被 load_config_layers_state 在准备配置状态时调用。它把解码工作交给 parse_managed_requirements_base64，把系统读取交给 load_managed_admin_requirements；拿到文本后，再用 managed_preferences_requirements_source 标记这份内容的来源。

调用图：调用 1 个内部函数（parse_managed_requirements_base64）；被 1 处调用（load_config_layers_state）；外部调用 3 个（other, spawn_blocking, error!）。

fn load_managed_admin_requirements() -> io::Result<Option<String>>

作用：这个函数从 macOS 受管偏好设置里读取 requirements 的原始值，并解码成普通文本。它只做同步读取和转换，不负责包装成更高层的配置对象。

数据流：进去时不需要额外参数 → 它用固定的 requirements 键名读取 macOS 偏好设置；没读到就返回 None；读到后去掉空白并做 base64 解码 → 出来的是可选的 requirements 文本，或者读取、解码时的错误。

调用关系：它由 load_managed_admin_requirements_layer 放到后台任务里调用。它通过 load_managed_preference 拿系统里的值，再通过 parse_managed_requirements_base64 把编码字符串还原。

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

fn load_managed_preference(key_name: &str) -> io::Result<Option<String>>

作用：这个函数是本文件真正接触 macOS 系统偏好设置的地方。给它一个键名，它就去 com.openai.codex 这个受管应用域里找对应的字符串值。

数据流：进去的是一个偏好设置键名 → 它调用 Apple CoreFoundation 的 CFPreferencesCopyAppValue，在固定应用域下查值；如果没有值，就记录一条调试日志并返回 None；如果有值，就把 macOS 的 CFString 转成 Rust 字符串 → 出来的是可选字符串，代表管理员下发的原始内容。

调用关系：它是底层取件员，被 load_managed_admin_config 和 load_managed_admin_requirements 调用。上层函数不用知道 CoreFoundation 的细节，只需要拿到字符串或知道没有配置。

调用图：被 2 处调用（load_managed_admin_config, load_managed_admin_requirements）；外部调用 3 个（new, wrap_under_create_rule, debug!）。

fn parse_managed_config_base64(
    encoded: &str,
    strict_config: bool,
    base_dir: &Path,
) -> io::Result<ManagedAdminConfigLayer>

作用：这个函数把管理员下发的 base64 配置字符串变成系统能用的配置层。它还负责在严格模式下把配置错误变成更友好的诊断信息。

数据流：进去的是 base64 字符串、严格检查开关和基础目录 → 它先解码成 TOML 文本，再解析成 TOML 值；解析失败时会记录错误，严格模式下还会生成带来源位置的配置错误；解析成功后会按需做严格字段检查；最后确认 TOML 根部必须是表 → 出来的是 ManagedAdminConfigLayer，里面有解析后的配置和原始 TOML 文本；如果根部不是表或有错误，就返回 InvalidData。

调用关系：它由 load_managed_admin_config_layer 在拿到配置字符串后调用。它先依赖 decode_managed_preferences_base64 还原文本，再调用 validate_managed_config_toml_strictly_if_requested 做严格校验。

调用图：调用 2 个内部函数（decode_managed_preferences_base64, validate_managed_config_toml_strictly_if_requested）；被 1 处调用（load_managed_admin_config_layer）；外部调用 4 个（Table, new, format!, error!）。

fn validate_managed_config_toml_strictly_if_requested(
    strict_config: bool,
    source_name: &str,
    raw_toml: &str,
    parsed: &TomlValue,
    base_dir: &Path,
) -> io::Result<()>

作用：这个函数只在严格配置模式下工作，用来检查管理员配置里有没有系统不认识或会被忽略的字段。它的作用是尽早发现拼错字段名这类隐蔽问题。

数据流：进去的是严格模式开关、来源名称、原始 TOML、解析后的 TOML 值和基础目录 → 如果没开严格模式，它什么也不做直接成功；如果开了，它临时设置基础目录环境，然后用 ConfigToml 的规则检查被忽略的字段 → 出来是成功，或者一个带诊断信息的 InvalidData 错误。

调用关系：它只被 parse_managed_config_base64 调用，位于“已成功解析 TOML”之后、“正式接受配置”之前。它把发现的配置问题交给 io_error_from_config_error 转成统一的输入输出错误。

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

fn parse_managed_requirements_base64(encoded: &str) -> io::Result<String>

作用：这个函数把管理员下发的 requirements base64 字符串还原成普通文本。它目前只是一个很薄的包装，但让配置解析和 requirements 解析在代码上分得更清楚。

数据流：进去的是 base64 字符串 → 它直接调用通用解码函数 → 出来的是 UTF-8 文本形式的 requirements 内容，或者 base64/文本编码错误。

调用关系：它被 load_managed_admin_requirements_layer 和 load_managed_admin_requirements 用来解码 requirements。真正的解码细节交给 decode_managed_preferences_base64。

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

fn decode_managed_preferences_base64(encoded: &str) -> io::Result<String>

作用：这个函数负责把 macOS 受管偏好设置里的 base64 字符串解开，并确认里面是正常的 UTF-8 文本。没有它，上层就无法安全地把管理员下发的值当作 TOML 或 requirements 文本来读。

数据流：进去的是一段 base64 编码字符串 → 它先按标准 base64 解码成字节；如果解码失败，就记录错误并返回 InvalidData；然后再把字节转成 UTF-8 字符串；如果不是合法文本，也记录错误并返回 InvalidData → 出来的是普通字符串。

调用关系：它是配置和 requirements 共用的底层解码器。parse_managed_config_base64 用它还原配置 TOML，parse_managed_requirements_base64 用它还原 requirements 文本。

调用图：被 2 处调用（parse_managed_config_base64, parse_managed_requirements_base64）；外部调用 1 个（from_utf8）。

fn new(path: PathBuf, range: TextRange, message: impl Into<String>) -> Self

作用：创建一个配置错误记录，里面装着出错文件、出错范围和给用户看的错误话。别人需要统一表达“配置哪里错了”时会用它。

数据流：进去的是文件路径、文本范围和错误消息 → 它把消息转成字符串并和路径、范围打包 → 出来一个完整的 ConfigError，不会读文件，也不会改外部状态。

调用关系：它是很多诊断流程的最后打包步骤。比如 TOML 解析失败、按类型校验失败、发现未知字段时，都会先定位位置，再用它生成统一的错误对象。

调用图：被 4 处调用（config_error_from_toml_for_source, config_error_from_typed_toml_for_source, config_error_from_ignored_toml_value_fields_for_source, unknown_field_error_from_paths）；外部调用 1 个（into）。

fn new(error: ConfigError, source: Option<toml::de::Error>) -> Self

作用：把一个给用户看的配置错误，和一个可选的底层 TOML 错误绑在一起。这样既能显示友好信息，也不丢掉原始技术原因。

数据流：进去的是 ConfigError 和可选的 TOML 原始错误 → 它们被保存到 ConfigLoadError 里 → 出来一个可以作为标准错误传播的加载错误。

调用关系：它主要被 io_error_from_config_error 使用，用来把配置错误包装成标准的输入输出错误，方便上层加载配置的代码统一返回失败。

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

fn config_error(&self) -> &ConfigError

作用：取出里面那份面向用户的配置错误。调用者如果想拿到文件、行列和消息，而不是只打印整段错误，会用它。

数据流：进去的是一个 ConfigLoadError 自身 → 它直接借出内部的 ConfigError → 出来的是只读引用，不会改任何内容。

调用关系：它是读取错误细节的小窗口。上层捕获到 ConfigLoadError 后，可以通过它继续做格式化显示或测试断言。

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

作用：定义这个加载错误被直接打印时长什么样。它会输出成类似“文件:行:列: 错误原因”的短句。

数据流：进去的是格式化器和错误对象 → 它把路径、行号、列号、消息写进格式化器 → 出来的是可打印文本，错误对象本身不变。

调用关系：这是 Rust 的 Display 展示接口。任何地方把 ConfigLoadError 当普通错误打印时，都会走这里，确保用户看到的是简洁位置提示。

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

fn source(&self) -> Option<&(dyn std::error::Error + 'static)>

作用：提供底层原始错误，方便调试工具或日志继续追根溯源。普通用户看友好信息，开发者还可以看到 TOML 解析器的原始错误。

数据流：进去的是 ConfigLoadError → 它检查里面有没有保存 toml::de::Error → 出来的是可选的底层错误引用。

调用关系：这是 Rust 标准错误链的一部分。上层错误处理框架如果想显示“由什么导致”，会自动询问这个函数。

fn to_path_buf(self) -> PathBuf

作用：把诊断来源统一变成一个路径样子的值。来源可能是真文件路径，也可能只是一个显示名称，比如某个内存里的配置层。

数据流：进去的是 ConfigDiagnosticSource → 如果是真路径就复制路径，如果是显示名就把名字转成 PathBuf → 出来的是统一的 PathBuf。

调用关系：它被多种错误构造流程调用。这样后面的 ConfigError 不用关心来源到底是真文件，还是一个给用户看的配置层名字。

调用图：被 4 处调用（config_error_from_toml_for_source, config_error_from_typed_toml_for_source, config_error_from_ignored_toml_value_fields_for_source, unknown_field_error_from_paths）；外部调用 1 个（from）。

fn io_error_from_config_error(
    kind: io::ErrorKind,
    error: ConfigError,
    source: Option<toml::de::Error>,
) -> io::Error

作用：把配置错误包装成标准的 io::Error，也就是 Rust 常用的输入输出错误类型。这样配置加载失败可以和读文件失败走同一条错误通道。

数据流：进去的是错误种类、ConfigError 和可选 TOML 原始错误 → 它先创建 ConfigLoadError，再塞进 io::Error → 出来一个标准 io::Error。

调用关系：读取配置、严格校验配置、加载配置层等上层流程会用它。它像一个转接头，把本文件的详细诊断接到系统通用错误机制上。

调用图：调用 1 个内部函数（new）；被 5 处调用（read_config_from_path, validate_config_toml_strictly, load_config_layers_state, validate_managed_config_toml_strictly_if_requested, validate_config_toml_strictly）；外部调用 1 个（new）。

fn config_error_from_toml(
    path: impl AsRef<Path>,
    contents: &str,
    err: toml::de::Error,
) -> ConfigError

作用：把 TOML 解析器报出的错误，转成项目自己的 ConfigError。这样错误就带上了文件路径和人能看懂的行列范围。

数据流：进去的是路径、文件内容和 TOML 解析错误 → 它把路径作为诊断来源交给内部函数定位 → 出来一个 ConfigError。

调用关系：它被 read_config_from_path 这类读配置文件的流程使用。它自己不做复杂工作，而是把活交给 config_error_from_toml_for_source。

调用图：调用 1 个内部函数（config_error_from_toml_for_source）；被 1 处调用（read_config_from_path）；外部调用 2 个（as_ref, Path）。

fn config_error_from_toml_for_source(
    source: ConfigDiagnosticSource<'_>,
    contents: &str,
    err: toml::de::Error,
) -> ConfigError

作用：把 TOML 原始错误转成带来源、带位置的配置错误。它支持真实路径，也支持只是显示名称的配置来源。

数据流：进去的是诊断来源、配置文本和 TOML 错误 → 它读取错误里的字节跨度，换算成行列范围；如果没有位置就用默认 1 行 1 列 → 出来 ConfigError。

调用关系：它是 TOML 语法错误转换的核心。config_error_from_toml 和类型化 TOML 解析失败时都会调用它，最后由 ConfigError::new 打包。

调用图：调用 2 个内部函数（to_path_buf, new）；被 3 处调用（config_error_from_toml, config_error_from_typed_toml_for_source, config_error_from_ignored_toml_fields）；外部调用 2 个（message, span）。

fn config_error_from_typed_toml(
    path: impl AsRef<Path>,
    contents: &str,
) -> Option<ConfigError>

作用：检查一段 TOML 能不能变成指定的配置类型。能变成就说明结构没问题，不能变成就返回一个定位好的配置错误。

数据流：进去的是路径和配置文本，以及调用者指定的目标类型 T → 它把路径转成诊断来源并交给内部校验函数 → 出来是可选的 ConfigError，None 表示没错。

调用关系：它是对外更好用的入口。真正的解析、反序列化和定位都在 config_error_from_typed_toml_for_source 里完成。

调用图：外部调用 2 个（as_ref, Path）。

fn config_error_from_typed_toml_for_source(
    source: ConfigDiagnosticSource<'_>,
    contents: &str,
) -> Option<ConfigError>

作用：按指定配置类型校验 TOML，并尽量指出具体是哪一个配置项不合要求。反序列化就是把文本配置变成程序里的结构体。

数据流：进去的是来源、配置文本和目标类型 T → 它先解析 TOML，再用 serde_path_to_error 记录失败路径；失败时根据路径找 TOML 里的位置 → 出来 Some(ConfigError)，成功则 None。

调用关系：它是类型校验诊断的核心。它会在语法错误时退回 config_error_from_toml_for_source，在结构或类型不匹配时调用 span_for_config_path 找更精确的位置。

调用图：调用 4 个内部函数（to_path_buf, new, config_error_from_toml_for_source, span_for_config_path）；外部调用 2 个（deserialize, parse）。

async fn first_layer_config_error(
    layers: &ConfigLayerStack,
    config_toml_file: &str,
) -> Option<ConfigError>

作用：当多层配置合并后校验失败时，它尝试找出第一份真正有问题的配置层。这样用户能知道该改哪个具体文件或配置来源。

数据流：进去的是配置层堆栈和配置文件名 → 它按“低优先级到高优先级”的顺序取出启用的层 → 出来是第一个发现的 ConfigError，或者 None。

调用关系：它是多层配置诊断的外部入口。它先从 ConfigLayerStack 取层，再把逐层检查交给 first_layer_config_error_for_entries。

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

async fn first_layer_config_error_from_entries(
    layers: &[ConfigLayerEntry],
    config_toml_file: &str,
) -> Option<ConfigError>

作用：对一组已经拿到的配置层逐个查错。它适合调用者手里已经有配置层列表，不需要再从堆栈对象取。

数据流：进去的是配置层切片和配置文件名 → 它把切片转成迭代器并交给通用检查函数 → 出来第一个配置错误，或 None。

调用关系：它是 first_layer_config_error_for_entries 的便捷包装。和 first_layer_config_error 做同类事情，只是输入形态不同。

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

async fn first_layer_config_error_for_entries(
    layers: I,
    config_toml_file: &str,
) -> Option<ConfigError>

作用：真正逐层检查配置错误的函数。它会处理内存里的原始 TOML，也会去磁盘读取文件里的 TOML。

数据流：进去的是一串配置层和配置文件名 → 它逐层取内容或路径，设置相对路径解析基准，然后按目标类型校验 TOML → 一旦发现错误就返回，全部没错就返回 None。

调用关系：它被 first_layer_config_error 和 first_layer_config_error_from_entries 驱动。过程中会用 config_path_for_layer 找文件路径，用格式化来源名给非文件层报错，并调用类型化 TOML 诊断函数。

调用图：调用 2 个内部函数（config_path_for_layer, new）；外部调用 4 个（DisplayName, format_config_layer_source, read_to_string, debug!）。

fn config_path_for_layer(layer: &ConfigLayerEntry, config_toml_file: &str) -> Option<PathBuf>

作用：从一个配置层里找出它对应的真实配置文件路径。有些配置层来自系统、用户或项目文件，有些来自命令行或管理策略，没有文件路径。

数据流：进去的是一个配置层和默认配置文件名 → 它按配置层来源种类判断该拼哪个路径，或判断没有文件 → 出来 Some(PathBuf) 或 None。

调用关系：它只服务于 first_layer_config_error_for_entries。逐层检查时，需要先靠它知道哪些层能从磁盘重新读取，哪些层只能跳过文件读取。

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

fn text_range_from_span(contents: &str, span: std::ops::Range<usize>) -> TextRange

作用：把 TOML 库给的字节范围，换成人能看懂的起止行列。字节范围是机器位置，行列才适合展示给用户。

数据流：进去的是完整文本和一个字节区间 → 它分别计算起点和终点位置，结束位置会落到最后一个实际字符上 → 出来 TextRange。

调用关系：它被 TOML 错误转换流程使用。里面把具体偏移量换成行列的工作交给 position_for_offset。

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

fn format_config_error(error: &ConfigError, contents: &str) -> String

作用：把配置错误格式化成带源码片段的提示。它不只说第几行错，还会把那一行打印出来，并用 ^ 指出位置。

数据流：进去的是 ConfigError 和文件内容 → 它先写“路径:行:列:消息”，再取出对应行，计算要画几个 ^ → 出来一段适合显示在终端里的字符串。

调用关系：它被 format_config_error_with_source 调用。其他地方如果已经有文件内容，也可以直接用它避免重复读文件。

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

fn format_config_error_with_source(error: &ConfigError) -> String

作用：根据错误里的路径自动读文件，然后生成带源码片段的错误文本。读不到文件时，也会退化成只有位置和消息的提示。

数据流：进去的是 ConfigError → 它尝试从 error.path 读文件内容，成功就带内容格式化，失败就用空内容格式化 → 出来一段错误说明字符串。

调用关系：它是更省事的展示入口。它把读文件的活做完后，真正排版交给 format_config_error。

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

fn position_for_offset(contents: &str, index: usize) -> TextPosition

作用：把文本里的某个字节下标换成第几行第几列。它还注意处理 UTF-8 字符，因为中文等字符不是一个字节。

数据流：进去的是文本和字节下标 → 它找到所在行的开头，数换行符得到行号，再按字符数算列号 → 出来 TextPosition。

调用关系：它是 text_range_from_span 的底层工具。所有从解析器字节位置到用户行列位置的换算，最终都依赖它。

调用图：被 1 处调用（text_range_from_span）；外部调用 1 个（from_utf8）。

fn default_range() -> TextRange

作用：提供一个兜底位置：第 1 行第 1 列。当错误没有明确位置时，至少还能给用户一个合法的位置。

数据流：进去没有参数 → 它创建起点和终点都在 1:1 的 TextRange → 出来默认文本范围。

调用关系：它在 TOML 错误没有 span，也就是没有字节范围时被使用。这样诊断流程不会因为缺少位置而失败。

fn span_for_path(contents: &str, path: &SerdePath) -> Option<std::ops::Range<usize>>

作用：根据 serde 报出的配置路径，在 TOML 文档里找到对应节点的字节范围。路径就像“features.foo”这种配置项地址。

数据流：进去的是配置文本和 serde 路径 → 它把文本解析成可编辑 TOML 文档，再沿路径找到节点并取 span → 出来可选的字节范围。

调用关系：它被 span_for_config_path 调用，是普通配置路径定位的实现。路径导航工作交给 node_for_path。

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

fn span_for_config_path(
    contents: &str,
    path: &SerdePath,
) -> Option<std::ops::Range<usize>>

作用：为配置路径找出最合适的 TOML 位置。它还特别照顾 features 表，因为这个表里的值类型错误需要指到具体坏值。

数据流：进去的是配置文本和 serde 路径 → 它先判断是不是 features 表路径，是的话优先找 features 里第一个非布尔值；否则按普通路径查找 → 出来可选字节范围。

调用关系：它被类型化 TOML 校验错误使用。它把特殊规则交给 is_features_table_path 和 span_for_features_value，普通规则交给 span_for_path。

调用图：调用 3 个内部函数（is_features_table_path, span_for_features_value, span_for_path）；被 2 处调用（config_error_from_typed_toml_for_source, config_error_from_ignored_toml_value_fields_for_source）。

fn span_for_toml_key_path(
    contents: &str,
    path: &[String],
) -> Option<std::ops::Range<usize>>

作用：根据一串 TOML 键名，尽量定位到“键本身”的位置，而不只是键对应的值。发现未知字段时，这能把 ^ 标在字段名上。

数据流：进去的是配置文本和字符串路径数组 → 它解析 TOML 文档，逐段走表、内联表或数组，最后优先取最后一个键的 span → 出来可选字节范围。

调用关系：它被 unknown_field_error_from_paths 使用。遍历过程中遇到普通键会用 map_child，遇到数组下标会用 seq_child。

调用图：调用 2 个内部函数（map_child, seq_child）；被 1 处调用（unknown_field_error_from_paths）；外部调用 1 个（Item）。

fn is_features_table_path(path: &SerdePath) -> bool

作用：判断 serde 路径是不是刚好指向顶层 features 表。这个判断用来触发 features 的特殊定位规则。

数据流：进去的是 serde 路径 → 它检查第一段是否是名为 features 的 map 键，并确认没有第二段 → 出来 true 或 false。

调用关系：它只被 span_for_config_path 调用。它像一个小开关，决定要不要走 span_for_features_value 的特殊逻辑。

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

fn span_for_features_value(contents: &str) -> Option<std::ops::Range<usize>>

作用：在 features 表里找到第一个不符合预期的值的位置。这里期望 feature 开关是布尔值，也就是 true 或 false。

数据流：进去的是配置文本 → 它解析 TOML，找到顶层 features 表，逐项检查；布尔值跳过，非布尔值就取它的位置 → 出来可选字节范围。

调用关系：它被 span_for_config_path 在 features 表出错时调用。这样错误提示会指向坏的值，而不是笼统指向整个 features 表。

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

fn node_for_path(item: &'a Item, path: &SerdePath) -> Option<TomlNode<'a>>

作用：沿着 serde 给出的路径，在 TOML 文档树里一步步找到对应节点。可以理解成在配置这棵树里按路标找房间。

数据流：进去的是 TOML 根节点和 serde 路径 → 它把路径段逐个处理：键名走 map_child，数组下标走 seq_child，不认识就放弃 → 出来可选的 TomlNode。

调用关系：它被 span_for_path 调用。它负责“走到哪里”，span_for_path 负责“拿这个地方的字节范围”。

调用图：调用 2 个内部函数（map_child, seq_child）；被 1 处调用（span_for_path）；外部调用 2 个（iter, Item）。

fn map_child(node: &TomlNode<'a>, key: &str) -> Option<TomlNode<'a>>

作用：从当前 TOML 节点里按键名取子节点。它处理普通表和内联表，内联表就是写在一行花括号里的小表。

数据流：进去的是当前节点和键名 → 它判断节点能不能像表一样查键，能就取出对应子项并包装成 TomlNode → 出来可选子节点。

调用关系：它被 node_for_path 和 span_for_toml_key_path 使用。凡是路径下一步是字段名，都靠它往下走。

调用图：被 2 处调用（node_for_path, span_for_toml_key_path）。

fn seq_child(node: &TomlNode<'a>, index: usize) -> Option<TomlNode<'a>>

作用：从当前 TOML 节点里按数组下标取子节点。数组就是一串值，数组表则是一串表。

数据流：进去的是当前节点和数字下标 → 它判断当前节点是不是数组或数组表，是就取指定位置的元素 → 出来可选子节点。

调用关系：它被 node_for_path 和 span_for_toml_key_path 使用。凡是路径下一步是第几个元素，都靠它往下走。

调用图：被 2 处调用（node_for_path, span_for_toml_key_path）。

fn config_error_from_ignored_toml_fields(
    path: impl AsRef<Path>,
    contents: &str,
) -> Option<ConfigError>

作用：这是从配置文件文本开始做严格检查的入口。别人把文件路径和 TOML 内容交给它，它会告诉你里面有没有未知字段或语法错误。

数据流：输入是一个文件路径和一整段配置文本。它先把文本解析成 TOML 数据；如果 TOML 本身写坏了，就把解析错误包装成 ConfigError 返回；如果 TOML 能读懂，就继续做未知字段检查。输出是 Some(ConfigError) 表示有问题，或者 None 表示没有发现这类问题。

调用关系：它位于严格配置检查的最外层，适合配置加载代码直接调用。它会使用路径作为错误来源，并在 TOML 解析失败时把底层错误交给 config_error_from_toml_for_source 转成项目统一的错误格式；解析成功后，后续检查由内部的严格校验流程完成。

调用图：调用 1 个内部函数（config_error_from_toml_for_source）；外部调用 2 个（as_ref, Path）。

fn config_error_from_ignored_toml_value_fields(
    path: impl AsRef<Path>,
    contents: &str,
    value: TomlValue,
) -> Option<ConfigError>

作用：这个函数用于：TOML 已经被别处解析好了，现在只想检查里面有没有项目不认识的字段。它省去了重新解析文本的步骤。

数据流：输入是文件路径、原始文本、以及已经解析好的 TomlValue。它把路径包装成错误来源，然后把这些信息送进真正的检查函数。输出同样是可选的 ConfigError：有未知字段就返回错误，没有就返回空。

调用关系：它是一个便捷包装层，给已经拿到 TOML 数据的调用方使用。它自己不做复杂判断，只负责把“文件路径来源”整理好，再把活交给核心检查逻辑。

调用图：外部调用 2 个（as_ref, Path）。

fn config_error_from_ignored_toml_value_fields_for_source_name(
    source_name: &str,
    contents: &str,
    value: TomlValue,
) -> Option<ConfigError>

作用：这个函数和上一个类似，但错误来源不是实际文件路径，而是一个展示用名字。适合检查内存里的配置片段、命令行传入的配置，或者没有真实文件的配置。

数据流：输入是一个来源名字、原始文本和解析好的 TOML 数据。它把来源名字包装成可显示的错误来源，再进入统一的严格检查流程。输出是 Some(ConfigError) 或 None。

调用关系：它给“没有真实路径但也要报清楚来源”的场景用。它通过 DisplayName 标记来源，然后把后面的解析和未知字段判断交给核心函数。

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

fn config_error_from_ignored_toml_value_fields_for_source(
    source: ConfigDiagnosticSource<'_>,
    contents: &str,
    value: TomlValue,
) -> Option<ConfigError>

作用：这是本文件的核心检查器。它真正负责把 TOML 数据按目标配置类型读一遍，收集没人认识的字段，并把发现的问题变成用户能看懂的配置错误。

数据流：输入是错误来源、原始文本和 TOML 数据。它先额外扫描 features 和各个 profile 里的 features，找未知功能开关键；然后用 serde 的“忽略字段记录器”尝试把 TOML 读成目标配置类型，同时记下被忽略的路径。如果解析成功，它优先报告普通未知字段，其次报告未知功能开关；如果解析失败，它尽量根据出错路径或 TOML 自带位置算出文本范围，再生成 ConfigError。输出是一个错误或空结果。

调用关系：它是几个公开/内部包装函数共同汇入的地方。它会调用 unknown_feature_toml_value_path 找功能开关问题，调用 unknown_field_error_from_paths 把路径变成错误信息；如果遇到真正的反序列化错误，则直接构造统一的 ConfigError。

调用图：调用 5 个内部函数（to_path_buf, new, span_for_config_path, unknown_feature_toml_value_path, unknown_field_error_from_paths）；外部调用 3 个（new, new, deserialize）。

fn ignored_toml_value_field(value: TomlValue) -> Option<String>

作用：这个函数只想快速知道：给定 TOML 里第一个被配置类型忽略的字段叫什么。它更像一个小工具，返回字段名字符串，而不是完整错误对象。

数据流：输入是一个已经解析好的 TOML 数据。它尝试按目标配置类型读取，并收集被忽略的字段路径；如果读取过程本身失败，就返回空，因为这时不能可靠判断“只是多了字段”；如果读取成功，就取第一个忽略路径并用点号连起来，比如 a.b.c。输出是可选的字段名字符串。

调用关系：它复用了 serde 的忽略字段能力，但不走完整的错误定位流程。通常适合测试、辅助校验，或者只需要字段名而不需要文件位置和详细诊断的地方。

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

fn unknown_feature_toml_value_field(value: &TomlValue) -> Option<String>

作用：这个函数专门找第一个不认识的功能开关键。它把复杂路径压成一个点号连接的字符串，方便上层直接提示用户。

数据流：输入是 TOML 数据的引用。它调用 unknown_feature_toml_value_path 找出所有未知功能开关的路径，然后拿第一个路径，用点号拼成字符串。输出是可选的字段名，例如 features.some_flag 或 profiles.dev.features.some_flag。

调用关系：它是未知功能开关扫描的简化出口。调用关系里显示它会被 validate_cli_overrides_strictly 使用，说明命令行覆盖配置时也需要检查用户有没有写了不存在的功能开关。

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

fn unknown_field_error_from_paths(
    source: ConfigDiagnosticSource<'_>,
    contents: &str,
    ignored_paths: Vec<Vec<String>>,
) -> Option<ConfigError>

作用：这个函数把“未知字段的路径”变成一条真正能展示给用户的配置错误。它负责写出类似“unknown configuration field x.y”这样的提示。

数据流：输入是错误来源、原始配置文本、以及一组未知字段路径。它取第一个路径，用点号拼成字段名；再尝试在原始文本中找到这个键的位置，换算成可高亮的文本范围；如果找不到位置，就用默认范围。输出是一个 ConfigError；如果没有路径可报，就返回空。

调用关系：它被核心函数 config_error_from_ignored_toml_value_fields_for_source 调用。核心函数负责发现问题，它负责把发现的问题包装成统一、可定位、可显示的错误。

调用图：调用 3 个内部函数（to_path_buf, new, span_for_toml_key_path）；被 1 处调用（config_error_from_ignored_toml_value_fields_for_source）；外部调用 1 个（format!）。

fn unknown_feature_toml_value_path(value: &TomlValue) -> Vec<Vec<String>>

作用：这个函数扫描 TOML 配置里所有功能开关位置，找出项目不认识的开关键路径。它不仅看顶层 features，也看每个 profile 下面的 features。

数据流：输入是 TOML 数据。它先确认根节点是表；如果不是表，就没有可检查的功能开关，直接返回空列表。然后它检查顶层 features，再遍历 profiles 下每个 profile 的 features，把未知键的完整路径收集起来。输出是一组路径，每条路径都是字符串片段列表。

调用关系：它是功能开关严格检查的中心。核心配置检查函数会用它生成错误，unknown_feature_toml_value_field 也会用它提取第一个未知功能开关；具体把某个 features 表里的未知键放进列表，则交给 push_unknown_feature_paths。

调用图：调用 1 个内部函数（push_unknown_feature_paths）；被 2 处调用（config_error_from_ignored_toml_value_fields_for_source, unknown_feature_toml_value_field）；外部调用 2 个（as_table, new）。

fn push_unknown_feature_paths(
    paths: &mut Vec<Vec<String>>,
    prefix: &[&str],
    features: Option<&TomlValue>,
)

作用：这个函数检查某一个 features 表，把里面不认识的功能开关键追加到结果列表里。它像一个小筛子，只留下未知的 key。

数据流：输入是待追加的路径列表、当前位置的路径前缀，以及可能存在的 features TOML 值。它先确认 features 真的是一个表；如果不是，就什么也不做。然后逐个看表里的 key，凡是不属于已知功能开关的，就把“前缀 + 这个 key”组成完整路径并追加到列表。它没有单独返回值，而是修改传入的列表。

调用关系：它只被 unknown_feature_toml_value_path 调用。外层函数决定要检查哪些位置，比如顶层或某个 profile；这个函数负责在具体位置里逐项筛查。

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

fn ignored_path_segments(path: &serde_ignored::Path<'_>) -> Vec<String>

作用：这个函数把 serde 记录的内部路径格式，转换成普通人更容易处理的字符串片段列表。比如把嵌套路径拆成 profiles、dev、features 这样的段。

数据流：输入是一个 serde_ignored::Path，这是 serde 用来描述“被忽略字段在哪里”的内部结构。它创建一个空列表，然后调用递归函数把路径一段段塞进去。输出是字符串列表，供后续拼成 a.b.c 或定位 TOML 键使用。

调用关系：它是字段路径转换的小工具。记录忽略字段的回调会用它把 serde 的路径变成项目自己的路径格式；真正逐层拆路径的工作交给 push_ignored_path_segments。

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

fn push_ignored_path_segments(path: &serde_ignored::Path<'_>, segments: &mut Vec<String>)

作用：这个函数递归拆解 serde 的路径结构，把每一层的名字或数组下标按顺序放进列表。它处理的是底层细活，保证路径顺序正确。

数据流：输入是一个 serde 路径节点和一个可修改的字符串列表。它从当前节点往父节点追溯：遇到根节点就停；遇到数组就加入下标；遇到表里的键就加入键名；遇到一些包装层就跳过包装继续看父节点。结果是传入的列表被补齐成完整路径。

调用关系：它被 ignored_path_segments 调用，是路径转换过程中的递归执行者。上层只想要最终路径；它负责理解 serde 路径各种形状，并把它们统一变成普通字符串段。

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

async fn first_layer_config_error_from_entries(layers: &[ConfigLayerEntry]) -> Option<ConfigError>

作用：从一堆配置层里找出第一个能解释清楚的配置错误。它主要用来在总加载流程失败时，给用户报一个更准确、更靠近源头的错误。

数据流：输入是一组已经读到的配置层 → 它按 ConfigToml 的格式检查这些层里最早出现的问题 → 输出一个可选的 ConfigError；如果没发现可归因的错误，就返回空。

调用关系：它只被 load_config_layers_state 使用。当总流程在解析项目根标记或信任配置时出错，这个小函数会帮忙把错误归回具体的配置文件，而不是只抛一个模糊失败。

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

async fn load_config_layers_state(
    fs: &dyn ExecutorFileSystem,
    codex_home: &Path,
    cwd: Option<AbsolutePathBuf>,
    cli_overrides: &[(String, TomlValue)],
    options: impl Into<ConfigLoa

作用：这是本文件的主入口，负责把所有配置来源读成一个完整的 ConfigLayerStack。别人想知道“这次 Codex 到底该用什么配置”，基本就是走它。

数据流：输入包括文件系统、Codex 主目录、当前工作目录、命令行覆盖项、加载选项和线程配置加载器 → 它读取托管要求、系统配置、云端配置、用户配置、项目配置、线程配置和运行时覆盖，并做严格校验、相对路径修正、项目信任判断、旧配置兼容转换 → 输出一个 ConfigLayerStack，同时可能带启动警告；遇到坏配置或读文件失败就返回错误。

调用关系：它被更外层的配置加载、插件配置加载、应用启动和大量测试调用。它自己把活分给 load_requirements_toml、load_config_toml_for_required_layer、load_user_config_layer、project_trust_context、load_project_layers、insert_layer_by_precedence 等函数，像一个排班员把每种配置来源放到正确位置。

调用图：调用 25 个内部函数（from_bundle, from_bundle_strict_config, io_error_from_config_error, first_layer_config_error_from_entries, insert_layer_by_precedence, load_config_layers_internal, load_config_toml_for_required_layer, load_project_layers, load_requirements_toml, load_user_config_layer (+15 more)）；被 41 处调用（load_config_layers, load_plugins_config, build_inner, cli_overrides_with_relative_paths_do_not_break_trust_check, codex_home_is_not_loaded_as_project_layer_from_home_dir, codex_home_within_project_tree_is_not_double_loaded, hooks_allow_managed_hooks_only_in_user_config_does_not_enable_requirements_policy, ignore_rules_marks_config_stack_for_exec_policy_rule_skip, ignore_user_config_keeps_empty_user_layer, includes_thread_config_layers_in_stack (+15 more)）；外部调用 9 个（into, Table, new, new, new, load_config_layers, compose_requirements, format!, new）。

async fn load_user_config_layer(
    fs: &dyn ExecutorFileSystem,
    user_file: &AbsolutePathBuf,
    profile: Option<&ProfileV2Name>,
    ignore_user_config: bool,
    strict_config: bool,
) -> io::

作用：读取用户自己的 config.toml 或某个用户 profile 配置。它也支持“忽略用户配置”的模式，用空配置占位。

数据流：输入是文件系统、用户配置文件路径、可选 profile 名、是否忽略用户配置、是否严格检查 → 如果被要求忽略，就直接生成一个空的用户层；否则读取并解析文件 → 输出一个标记为 User 来源的 ConfigLayerEntry。

调用关系：它由 load_config_layers_state 在加载基础用户配置和 profile 配置时调用。真正读文件和解析 TOML 的细活交给 load_config_toml_for_required_layer。

调用图：调用 2 个内部函数（load_config_toml_for_required_layer, new）；被 1 处调用（load_config_layers_state）；外部调用 3 个（Table, new, clone）。

fn insert_layer_by_precedence(layers: &mut Vec<ConfigLayerEntry>, layer: ConfigLayerEntry)

作用：把一个配置层按优先级插进已有列表。这样后面的合并才知道谁该覆盖谁。

数据流：输入是已有配置层列表和一个新层 → 它查找第一个优先级比新层更高的位置 → 把新层插到那里；如果没找到就放到末尾，直接修改传入的列表。

调用关系：它由 load_config_layers_state 用来插入线程级配置层。它不读文件，只负责维护“层的顺序”这个关键规则。

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

async fn load_config_toml_for_required_layer(
    fs: &dyn ExecutorFileSystem,
    toml_file: &AbsolutePathBuf,
    strict_config: bool,
    create_entry: impl FnOnce(TomlValue) -> ConfigLayerEntry,
)

作用：读取一个必须在配置栈中出现的 config.toml 层。文件不存在时不算错，而是生成空配置层。

数据流：输入是文件系统、配置文件路径、是否严格检查，以及一个把 TOML 变成配置层的回调 → 它尝试读文件，存在就解析 TOML、可选严格检查、修正相对路径；不存在就用空表 → 输出回调创建出的 ConfigLayerEntry；读失败或语法错则返回错误。

调用关系：它被 load_config_layers_state 和 load_user_config_layer 调用，用于系统层和用户层。它会把严格检查交给 validate_config_toml_strictly，把路径处理交给 resolve_relative_paths_in_config_toml。

调用图：调用 5 个内部函数（resolve_relative_paths_in_config_toml, validate_config_toml_strictly, read_file_text, as_path, from_abs_path）；被 2 处调用（load_config_layers_state, load_user_config_layer）；外部调用 5 个（Table, new, format!, from_str, new）。

fn validate_config_toml_strictly(
    toml_file: &Path,
    contents: &str,
    value: &TomlValue,
    base_dir: &Path,
) -> io::Result<()>

作用：严格检查 config.toml 里有没有不认识或会被忽略的字段。这样用户写错字段名时能尽早发现，而不是悄悄失效。

数据流：输入是文件路径、原始文本、解析后的 TOML 值和相对路径基准目录 → 它在这个基准目录下按 ConfigToml 结构检查字段 → 如果发现问题就输出 io 错误；否则什么也不改，返回成功。

调用关系：它被 load_config_toml_for_required_layer 和 load_project_layers 调用。错误格式化依赖 io_error_from_config_error，让用户能看到具体文件和字段。

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

fn validate_cli_overrides_strictly(
    cli_overrides_layer: &TomlValue,
    base_dir: &Path,
) -> io::Result<()>

作用：严格检查命令行 -c/--config 传进来的临时配置。它防止用户在命令行里写了不存在的配置项还以为生效了。

数据流：输入是命令行覆盖形成的 TOML 层和路径基准目录 → 它检查普通未知字段和未知 feature 字段 → 如果有未知项就返回带字段名的错误；没有就返回成功。

调用关系：它只在 load_config_layers_state 中被调用，发生在命令行覆盖层加入配置栈之前。它和 validate_config_toml_strictly 类似，但错误文案专门指向 -c/--config。

调用图：调用 2 个内部函数（unknown_feature_toml_value_field, new）；被 1 处调用（load_config_layers_state）；外部调用 3 个（clone, new, format!）。

async fn load_requirements_toml(
    fs: &dyn ExecutorFileSystem,
    requirements_toml_file: &AbsolutePathBuf,
) -> io::Result<Option<RequirementsLayerEntry>>

作用：读取系统级 requirements.toml，也就是管理员强制约束。比如允许哪些沙箱模式、审批策略等。

数据流：输入是文件系统和 requirements.toml 路径 → 它尝试读取文件；读到就包装成 RequirementsLayerEntry 并记录基准目录；文件不存在就返回空；其他读取错误就返回错误。

调用关系：它被 load_config_layers_state 用来加载系统约束，也被相关测试直接调用。后续这些约束会交给 compose_requirements 合成最终的硬性规则。

调用图：调用 5 个内部函数（from_toml, read_file_text, from_absolute_path, parent, from_abs_path）；被 4 处调用（load_config_layers_state, cloud_config_bundle_are_not_overwritten_by_system_requirements, load_single_requirements_toml, system_remote_sandbox_config_keeps_cloud_sandbox_modes）；外部调用 3 个（new, format!, clone）。

fn system_requirements_toml_file() -> io::Result<AbsolutePathBuf>

作用：给出当前操作系统默认的系统级 requirements.toml 路径。不同系统放的位置不一样，这个函数负责统一入口。

数据流：没有业务输入 → 在 Unix 上返回 /etc/codex/requirements.toml，在 Windows 上转交给 Windows 专用函数 → 输出一个绝对路径或路径构造错误。

调用关系：它被 system_requirements_toml_file_with_overrides 调用。总加载流程不会直接写死路径，而是通过这里适配平台。

调用图：调用 2 个内部函数（windows_system_requirements_toml_file, from_absolute_path）；被 1 处调用（system_requirements_toml_file_with_overrides）；外部调用 1 个（new）。

fn system_requirements_toml_file_with_overrides(
    overrides: &LoaderOverrides,
) -> io::Result<AbsolutePathBuf>

作用：决定实际要读哪个系统 requirements.toml。测试或特殊启动参数可以覆盖默认路径。

数据流：输入是 LoaderOverrides → 如果里面指定了 system_requirements_path，就把它转成绝对路径；否则使用 system_requirements_toml_file 的默认路径 → 输出最终路径。

调用关系：它由 load_config_layers_state 调用，位于加载管理员约束之前。这样生产环境走默认位置，测试和特殊场景可以指定别的位置。

调用图：调用 2 个内部函数（system_requirements_toml_file, from_absolute_path）；被 1 处调用（load_config_layers_state）。

fn system_config_toml_file() -> io::Result<AbsolutePathBuf>

作用：给出当前操作系统默认的系统级 config.toml 路径。它是系统配置层的默认来源。

数据流：没有业务输入 → Unix 返回 /etc/codex/config.toml，Windows 转交给 Windows 专用路径函数 → 输出绝对路径或错误。

调用关系：它被 system_config_toml_file_with_overrides 调用。load_config_layers_state 间接用它来找到系统配置层。

调用图：调用 2 个内部函数（windows_system_config_toml_file, from_absolute_path）；被 1 处调用（system_config_toml_file_with_overrides）；外部调用 1 个（new）。

fn system_config_toml_file_with_overrides(
    overrides: &LoaderOverrides,
) -> io::Result<AbsolutePathBuf>

作用：决定实际要读哪个系统 config.toml。它允许覆盖默认系统配置路径。

数据流：输入是 LoaderOverrides → 如果有 system_config_path 就使用它；否则使用 system_config_toml_file 的平台默认路径 → 输出最终绝对路径。

调用关系：它由 load_config_layers_state 调用，随后路径会交给 load_config_toml_for_required_layer 去读取。

调用图：调用 2 个内部函数（system_config_toml_file, from_absolute_path）；被 1 处调用（load_config_layers_state）。

fn windows_codex_system_dir() -> PathBuf

作用：在 Windows 上找到 Codex 的系统配置目录，通常是 ProgramData\OpenAI\Codex。

数据流：没有业务输入 → 它先尝试向 Windows 系统询问 ProgramData 的真实位置；失败时退回 C:\ProgramData → 输出拼好的 Codex 系统目录路径。

调用关系：它只在 Windows 相关路径函数里使用，被 windows_system_config_toml_file 和 windows_system_requirements_toml_file 调用。

调用图：调用 1 个内部函数（windows_program_data_dir_from_known_folder）；被 2 处调用（windows_system_config_toml_file, windows_system_requirements_toml_file）。

fn windows_system_requirements_toml_file() -> io::Result<AbsolutePathBuf>

作用：在 Windows 上拼出系统 requirements.toml 的完整路径。

数据流：没有业务输入 → 它取得 Windows 的 Codex 系统目录，再加上 requirements.toml 文件名 → 输出绝对路径或转换错误。

调用关系：它被 system_requirements_toml_file 在 Windows 编译时调用，也被 Windows 路径测试验证。

调用图：调用 2 个内部函数（windows_codex_system_dir, try_from）；被 1 处调用（system_requirements_toml_file）。

fn windows_system_config_toml_file() -> io::Result<AbsolutePathBuf>

作用：在 Windows 上拼出系统 config.toml 的完整路径。

数据流：没有业务输入 → 它取得 Windows 的 Codex 系统目录，再加上 config.toml 文件名 → 输出绝对路径或转换错误。

调用关系：它被 system_config_toml_file 在 Windows 编译时调用，也被 Windows 路径测试验证。

调用图：调用 2 个内部函数（windows_codex_system_dir, try_from）；被 1 处调用（system_config_toml_file）。

fn windows_program_data_dir_from_known_folder() -> io::Result<PathBuf>

作用：向 Windows 系统查询 ProgramData 文件夹的真实位置。这样不会盲目假设系统盘一定是 C 盘。

数据流：没有业务输入 → 它调用 Windows API SHGetKnownFolderPath，拿到 UTF-16 路径字符串，转成 Rust 的 PathBuf，并释放系统分配的内存 → 输出 ProgramData 路径；系统调用失败则返回错误。

调用关系：它被 windows_codex_system_dir 使用，也被 Windows 单元测试直接调用。它是少数接触操作系统底层 API 的函数。

调用图：被 3 处调用（windows_system_config_toml_file_uses_expected_suffix, windows_system_requirements_toml_file_uses_expected_suffix, windows_codex_system_dir）；外部调用 6 个（from_wide, from, other, format!, from_raw_parts, try_from）。

fn requirements_layers_from_legacy_scheme(
    loaded_config_layers: LoadedConfigLayers,
) -> io::Result<Vec<RequirementsLayerEntry>>

作用：把旧版 managed_config.toml 当成新版 requirements.toml 约束来补救读取。这样老的管理员配置不会因为升级而失效。

数据流：输入是已经加载到的旧托管配置层 → 它分别处理文件版和 MDM 版，解析成 LegacyManagedConfigToml，再转换成 requirements 风格的 TOML → 输出一组 RequirementsLayerEntry。

调用关系：它被 load_config_layers_state 调用，位置在合成 requirements 之前。具体字段转换交给 legacy_requirements_to_toml_value。

调用图：调用 2 个内部函数（legacy_requirements_to_toml_value, from_toml_value）；被 1 处调用（load_config_layers_state）；外部调用 2 个（with_capacity, from）。

fn legacy_requirements_to_toml_value(legacy: LegacyManagedConfigToml) -> io::Result<TomlValue>

作用：把旧托管配置里的单个强制值，翻译成新版“允许值列表”。比如旧的 sandbox_mode 会变成 allowed_sandbox_modes。

数据流：输入是 LegacyManagedConfigToml → 它检查 approval_policy、approvals_reviewer、sandbox_mode 三类旧字段，逐个生成新版 requirements 字段；某些情况会额外允许 read-only 或 user → 输出一个 TOML 表。

调用关系：它被 requirements_layers_from_legacy_scheme 调用，也被单元测试覆盖。它用 toml_value_from_serializable 把 Rust 枚举安全地变成 TOML 值。

调用图：调用 1 个内部函数（toml_value_from_serializable）；被 1 处调用（requirements_layers_from_legacy_scheme）；外部调用 3 个（Table, new, vec!）。

fn toml_value_from_serializable(value: T) -> io::Result<TomlValue>

作用：把可序列化的数据转成 TOML 值。这里主要用来把枚举列表写进 requirements 表。

数据流：输入是任意支持 serde 序列化的值 → 它调用 TOML 的转换逻辑 → 输出 TomlValue；转换失败就包装成 InvalidData 错误。

调用关系：它被 legacy_requirements_to_toml_value 调用，是一个很小的辅助函数，让错误类型和本文件其他 io 错误保持一致。

调用图：被 1 处调用（legacy_requirements_to_toml_value）；外部调用 1 个（try_from）。

fn is_trusted(&self) -> bool

作用：判断某个项目信任决定是不是“可信”。这是启用项目本地配置的关键开关。

数据流：输入是 ProjectTrustDecision 自己保存的 trust_level → 它检查值是否等于 Trusted → 输出 true 或 false，不修改任何东西。

调用关系：它被 ProjectTrustContext::disabled_reason_for_decision、load_project_layers 间接相关流程使用。它把信任判断浓缩成一个简单布尔值。

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

fn decision_for_dir(&self, dir: &AbsolutePathBuf) -> ProjectTrustDecision

作用：针对某个目录判断它应该按可信、不可信，还是未知来处理。项目层配置能不能生效，就看这个决定。

数据流：输入是当前 ProjectTrustContext 和一个目录 → 它尝试用目录自身、项目根、仓库根的多种规范化路径去用户配置的 projects 信任表里查 → 输出 ProjectTrustDecision，里面有信任级别和建议使用的信任 key。

调用关系：它被 load_project_layers 在扫描每个 .codex 目录时调用。它依赖 normalized_project_trust_keys 和 project_trust_for_lookup_key 处理路径匹配细节。

调用图：调用 3 个内部函数（normalized_project_trust_keys, project_trust_for_lookup_key, as_path）；被 1 处调用（load_project_layers）。

fn disabled_reason_for_decision(&self, decision: &ProjectTrustDecision) -> Option<String>

作用：如果项目不可信或还没被标记可信，就生成一段告诉用户为什么禁用项目配置的说明。

数据流：输入是一个信任决定 → 如果已经可信就返回空；如果明确不可信或未设置，就结合用户配置文件路径生成提示文字 → 输出可选的禁用原因。

调用关系：它被 load_project_layers 调用。返回的文字会放进被禁用的 ConfigLayerEntry，供之后诊断或展示。

调用图：调用 2 个内部函数（is_trusted, as_path）；被 1 处调用（load_project_layers）；外部调用 1 个（format!）。

fn root_checkout_hooks_folder_for_dir(&self, dir: &AbsolutePathBuf) -> Option<AbsolutePathBuf>

作用：处理 Git linked worktree 的特殊情况：普通项目配置留在当前工作树，但 hooks 配置要从主 checkout 对应目录拿。

数据流：输入是一个目录 → 它比较 checkout_root 和 repo_root；如果两者相同就不需要覆盖；如果不同，就算出这个目录在主仓库里对应的 .codex 路径 → 输出可选的 hooks 配置目录。

调用关系：它被 load_project_layers 调用。后续 merge_root_checkout_project_hooks 会用它提供的位置替换 hooks 部分。

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

fn project_layer_entry(
    dot_codex_folder: &AbsolutePathBuf,
    config: TomlValue,
    disabled_reason: Option<String>,
    hooks_config_folder_override: Option<AbsolutePathBuf>,
) -> ConfigLayerE

作用：把某个 .codex 文件夹的配置包装成项目配置层。它也能把这一层标成“已读取但被禁用”。

数据流：输入是 .codex 文件夹路径、配置 TOML、可选禁用原因、可选 hooks 目录覆盖 → 它创建 Project 来源的 ConfigLayerEntry；有禁用原因就创建 disabled 层；最后附上 hooks 覆盖信息 → 输出配置层。

调用关系：它被 load_project_layers 多次调用。load_project_layers 负责读和判断，这个函数负责统一生成层对象。

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

fn sanitize_project_config(config: &mut TomlValue) -> Vec<String>

作用：清理项目本地配置里不允许出现的敏感字段。项目仓库不该决定用户凭据发往哪里，也不该改某些全局行为。

数据流：输入是可修改的 TOML 配置 → 如果它是表，就删除 PROJECT_LOCAL_CONFIG_DENYLIST 中列出的键，并记录被删掉的名字 → 输出被忽略的键列表，同时原配置已被修改。

调用关系：它被 load_project_layers 在项目配置解析成功后调用。若删除了字段，load_project_layers 会再用 project_ignored_config_keys_warning 生成启动警告。

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

fn project_ignored_config_keys_warning(
    dot_codex_folder: &AbsolutePathBuf,
    ignored_keys: &[String],
) -> String

作用：为被项目配置禁用清单删掉的字段生成用户可读警告。它告诉用户这些设置应该放到用户级 config.toml。

数据流：输入是 .codex 文件夹路径和被忽略的键名列表 → 它拼出 config.toml 的路径和字段名 → 输出一段完整警告文字。

调用关系：它只被 load_project_layers 调用。它不改变配置，只负责把安全限制解释给用户。

调用图：调用 1 个内部函数（join）；被 1 处调用（load_project_layers）；外部调用 1 个（format!）。

async fn project_trust_context(
    fs: &dyn ExecutorFileSystem,
    merged_config: &TomlValue,
    cwd: &AbsolutePathBuf,
    project_root_markers: &[String],
    config_base_dir: &Path,
    user_con

作用：收集判断项目是否可信所需的全部背景信息。比如项目根在哪、Git 仓库根在哪、用户配置里哪些项目被标记可信。

数据流：输入是文件系统、已经合并到目前为止的配置、当前目录、项目根标记、配置基准目录、用户配置文件路径 → 它解析 projects 信任表，寻找项目根、Git checkout 根和仓库根，并准备多种路径 key → 输出 ProjectTrustContext。

调用关系：它被 load_config_layers_state 在加载项目配置前调用。它把 find_project_root、find_git_checkout_root、resolve_root_git_project_for_trust 和路径规范化结果集中起来，供 load_project_layers 使用。

调用图：调用 4 个内部函数（find_git_checkout_root, find_project_root, normalized_project_trust_keys, new）；被 1 处调用（load_config_layers_state）；外部调用 3 个（clone, resolve_root_git_project_for_trust, clone）。

fn project_trust_key(path: &Path) -> String

作用：把一个项目路径变成可写进用户配置的信任 key。用户标记项目可信时会用到它。

数据流：输入是路径 → 它尝试生成规范化路径 key；如果失败，就用原路径字符串再做平台规范化 → 输出字符串 key。

调用关系：它被设置信任、编辑可信项目和相关测试调用。内部依赖 normalized_project_trust_keys 保持与加载时的查找规则一致。

调用图：调用 1 个内部函数（normalized_project_trust_keys）；被 5 处调用（thread_start_with_elevated_sandbox_trusts_project_and_followup_loads_project_config, thread_start_with_nested_git_cwd_trusts_repo_root, test_set_project_trusted_migrates_top_level_inline_projects_preserving_entries, set_project_trust_level_inner, trusted_project_edit）。

fn normalized_project_trust_keys(path: &Path) -> Vec<String>

作用：为同一个路径生成一组可能匹配的信任 key。这样符号链接、大小写差异或规范化路径差异不容易导致信任记录失效。

数据流：输入是路径 → 它生成原始路径字符串和 canonicalize 后的真实路径字符串，再按平台规则规范化；如果两者相同就返回一个，否则返回两个 → 输出 key 列表。

调用关系：它被 project_trust_key、project_trust_context 和 ProjectTrustContext::decision_for_dir 调用，是项目路径匹配的基础。

调用图：调用 1 个内部函数（normalize_project_trust_lookup_key）；被 3 处调用（decision_for_dir, project_trust_context, project_trust_key）；外部调用 3 个（to_string_lossy, canonicalize, vec!）。

fn normalize_project_trust_lookup_key(key: String) -> String

作用：按操作系统规则规范化信任 key。Windows 路径大小写不敏感，所以会转成小写。

数据流：输入是一个路径 key 字符串 → 如果当前是 Windows，就转小写；其他系统保持原样 → 输出规范化后的字符串。

调用关系：它被 normalized_project_trust_keys 和 project_trust_for_lookup_key 使用，确保查表时比较规则一致。

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

fn project_trust_for_lookup_key(
    projects_trust: &std::collections::HashMap<String, TrustLevel>,
    lookup_key: &str,
) -> Option<(String, TrustLevel)>

作用：在用户配置的项目信任表里查某个路径 key。它既支持直接命中，也支持规范化后匹配。

数据流：输入是信任表和待查 key → 它先直接查；查不到就把表里的 key 也规范化后比较，并在多个匹配时按 key 排序取第一个 → 输出匹配到的原始 key 和 TrustLevel，或空。

调用关系：它被 ProjectTrustContext::decision_for_dir 调用。它让用户配置里不同写法的路径仍有机会匹配当前项目路径。

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

fn resolve_relative_paths_in_config_toml(
    value_from_config_toml: TomlValue,
    base_dir: &Path,
) -> io::Result<TomlValue>

作用：把配置里的相对路径改成基于配置文件所在目录的绝对路径。这样不同目录的配置层合并时，路径不会被误解。

数据流：输入是解析后的 TOML 和基准目录 → 它临时设置路径解析基准，把 TOML 尝试转成 ConfigToml 再转回 TOML，让路径字段被解析；如果无法按 ConfigToml 解析，就原样返回；最后保留原始结构中的额外字段 → 输出修正后的 TOML。

调用关系：它被系统/用户/项目/云端/角色配置加载流程调用，也被单元测试验证。内部用 copy_shape_from_original 避免转换过程丢掉未知字段。

调用图：调用 2 个内部函数（copy_shape_from_original, new）；被 7 处调用（cloud_config_layers_from_fragments_impl, load_config_layers_state, load_config_toml_for_required_layer, load_project_layers, merge_root_checkout_project_hooks, ensure_resolve_relative_paths_in_config_toml_preserves_all_fields, load_role_layer_toml）；外部调用 2 个（clone, try_from）。

fn copy_shape_from_original(original: &TomlValue, resolved: &TomlValue) -> TomlValue

作用：在路径修正后，把原 TOML 的形状尽量保留下来。它避免因为结构体转换而丢掉未知但可能仍有用的字段。

数据流：输入是原始 TOML 和已解析修正后的 TOML → 它递归走表和数组，同名位置优先用修正后的值，没有就保留原值 → 输出一个既有修正路径、又保留原结构的新 TOML。

调用关系：它只被 resolve_relative_paths_in_config_toml 调用。它是相对路径处理中的保险步骤。

调用图：被 1 处调用（resolve_relative_paths_in_config_toml）；外部调用 4 个（Array, Table, new, new）。

async fn find_project_root(
    fs: &dyn ExecutorFileSystem,
    cwd: &AbsolutePathBuf,
    project_root_markers: &[String],
) -> io::Result<AbsolutePathBuf>

作用：从当前目录往上找项目根。项目根由配置里的标记文件或文件夹决定，比如类似 .git 这样的标记。

数据流：输入是文件系统、当前目录和一组项目根标记 → 如果标记列表为空，直接返回当前目录；否则从当前目录一路向父目录查找这些标记 → 找到就输出对应祖先目录，找不到就返回当前目录。

调用关系：它被 project_trust_context 调用。找到的根决定后续要扫描哪些 .codex 项目配置层。

调用图：调用 2 个内部函数（ancestors, from_abs_path）；被 1 处调用（project_trust_context）；外部调用 2 个（get_metadata, clone）。

async fn find_git_checkout_root(
    fs: &dyn ExecutorFileSystem,
    cwd: &AbsolutePathBuf,
) -> Option<AbsolutePathBuf>

作用：寻找当前目录所在的 Git checkout 根，也就是往上第一个含 .git 的目录。

数据流：输入是文件系统和当前目录 → 它先判断 cwd 是目录还是文件路径，再从合适的起点向上找 .git → 找到返回目录，找不到返回空。

调用关系：它被 project_trust_context 调用。结果主要用于 linked worktree 下 hooks 配置的特殊处理。

调用图：调用 2 个内部函数（parent, from_abs_path）；被 1 处调用（project_trust_context）；外部调用 2 个（get_metadata, clone）。

async fn load_project_layers(
    fs: &dyn ExecutorFileSystem,
    cwd: &AbsolutePathBuf,
    project_root: &AbsolutePathBuf,
    trust_context: &ProjectTrustContext,
    codex_home: &Path,
    strict

作用：读取从项目根到当前目录之间每个 .codex 文件夹里的项目配置层。它同时执行信任检查和项目本地配置安全过滤。

数据流：输入是文件系统、当前目录、项目根、信任上下文、Codex 主目录和严格检查开关 → 它按从项目根到当前目录的顺序扫描 .codex，跳过 Codex 主目录本身，读取 config.toml，按信任状态决定启用或禁用，清理不允许的字段，修正相对路径，合并 linked worktree hooks → 输出 LoadedProjectLayers，里面有配置层和启动警告。

调用关系：它由 load_config_layers_state 在已有系统和用户层之后调用。它把信任判断交给 ProjectTrustContext 的方法，把层创建交给 project_layer_entry，把 hooks 特例交给 merge_root_checkout_project_hooks。

调用图：调用 13 个内部函数（decision_for_dir, disabled_reason_for_decision, root_checkout_hooks_folder_for_dir, merge_root_checkout_project_hooks, project_ignored_config_keys_warning, project_layer_entry, resolve_relative_paths_in_config_toml, sanitize_project_config, validate_config_toml_strictly, read_file_text (+3 more)）；被 1 处调用（load_config_layers_state）；外部调用 8 个（Table, new, new, canonicalize, get_metadata, format!, from_str, new）。

async fn merge_root_checkout_project_hooks(
    fs: &dyn ExecutorFileSystem,
    mut config: TomlValue,
    hooks_config_folder_override: Option<&AbsolutePathBuf>,
    is_trusted: bool,
) -> io::Resul

作用：在 Git linked worktree 场景下，用主 checkout 对应位置的 hooks 替换当前工作树配置里的 hooks。这样 hooks 跟主仓库保持一致，而其他项目配置仍然用当前工作树的。

数据流：输入是文件系统、当前项目配置、可选的主 checkout hooks 配置目录、项目是否可信 → 没有覆盖目录就原样返回；有的话读取那边的 config.toml，解析并修正路径，然后删除当前配置里的 hooks，若主配置有 hooks 就插入 → 输出更新后的 TOML。

调用关系：它被 load_project_layers 调用。解析错误在可信项目中会报错；不可信项目中则更保守地忽略坏 hooks 配置。

调用图：调用 3 个内部函数（resolve_relative_paths_in_config_toml, read_file_text, from_abs_path）；被 1 处调用（load_project_layers）；外部调用 6 个（Table, as_table_mut, new, format!, from_str, new）。

fn ensure_resolve_relative_paths_in_config_toml_preserves_all_fields() -> anyhow::Result<()>

作用：测试相对路径修正不会把未知字段弄丢。它保护的是“修路径但不乱删配置”的行为。

数据流：输入是测试里临时创建的目录和一段 TOML 文本 → 它调用 resolve_relative_paths_in_config_toml，把相对路径字段转成绝对路径，同时保留 model 和未知 foo 字段 → 用断言确认输出符合预期。

调用关系：这是单元测试，只在测试生命周期运行。它直接验证 resolve_relative_paths_in_config_toml 和 copy_shape_from_original 的配合效果。

调用图：调用 2 个内部函数（resolve_relative_paths_in_config_toml, resolve_path_against_base）；外部调用 5 个（String, assert_eq!, tempdir, from_str, new）。

fn legacy_managed_config_backfill_includes_read_only_sandbox_mode() -> io::Result<()>

作用：测试旧托管配置转换沙箱模式时，会自动包含 read-only。read-only 是 Codex 正常工作需要保留的安全模式。

数据流：输入是一个旧配置，sandbox_mode 为 workspace-write → 它调用 legacy_requirements_to_toml_value → 断言输出的 allowed_sandbox_modes 同时包含 read-only 和 workspace-write。

调用关系：这是测试函数，保护 legacy_requirements_to_toml_value 的兼容规则，避免升级后管理员约束过窄。

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

fn legacy_managed_config_backfill_allows_user_when_guardian_is_required() -> io::Result<()>

作用：测试旧配置要求 auto_review 审批者时，新规则还允许 user。这样用户可以选择退出自动审查。

数据流：输入是 approvals_reviewer 为 AutoReview 的旧配置 → 转换成新版 requirements TOML → 断言 allowed_approvals_reviewers 里有 auto_review 和 user。

调用关系：这是测试函数，直接覆盖 legacy_requirements_to_toml_value 中关于审批者的兼容逻辑。

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

fn legacy_managed_config_backfill_preserves_user_only_approvals_reviewer() -> io::Result<()>

作用：测试旧配置只要求 user 审批者时，不会额外加入 auto_review。它保证转换不会放宽管理员原本的限制。

数据流：输入是 approvals_reviewer 为 User 的旧配置 → 转换成新版 requirements TOML → 断言 allowed_approvals_reviewers 只有 user。

调用关系：这是测试函数，保护 legacy_requirements_to_toml_value 的精确转换行为。

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

fn windows_system_requirements_toml_file_uses_expected_suffix()

作用：测试 Windows 上系统 requirements.toml 的路径后缀正确。也就是必须落在 OpenAI\Codex\requirements.toml 下。

数据流：输入来自 Windows 系统或默认 ProgramData 路径 → 它拼出期望路径，再调用 windows_system_requirements_toml_file → 用断言比较完整路径和后缀。

调用关系：这是只在 Windows 编译运行的测试。它验证 windows_program_data_dir_from_known_folder、windows_codex_system_dir 和 requirements 路径函数的组合结果。

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

fn windows_system_config_toml_file_uses_expected_suffix()

作用：测试 Windows 上系统 config.toml 的路径后缀正确。也就是必须落在 OpenAI\Codex\config.toml 下。

数据流：输入来自 Windows 系统或默认 ProgramData 路径 → 它拼出期望路径，再调用 windows_system_config_toml_file → 用断言比较完整路径和后缀。

调用关系：这是只在 Windows 编译运行的测试。它验证 Windows 系统配置文件路径不会拼错。

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

async fn load_agent_roles(
    fs: &dyn ExecutorFileSystem,
    cfg: &ConfigToml,
    config_layer_stack: &ConfigLayerStack,
    startup_warnings: &mut Vec<String>,
) -> std::io::Result<BTreeMap<Strin

作用：这是读取代理角色配置的总入口。它负责把多层配置、显式声明的角色、自动发现的角色文件合在一起，最后得到一张“角色名到角色配置”的表。

数据流：进去的是文件系统、主配置、配置层列表和启动警告列表。它先看有没有配置层；没有就走旧的单层读取方式。若有配置层，它按从低到高的优先级逐层读取 agents 配置，读取声明的角色，再扫描 agents 目录里的角色文件，处理重复名、补齐缺字段、检查说明是否存在。出来的是整理好的角色表；同时会把坏配置的提示追加到启动警告里。

调用关系：它由 load_config_with_layer_stack 在加载整体配置时调用，是代理角色配置的总调度者。它会把具体小活交给 agents_toml_from_layer、read_declared_role、discover_agent_roles_in_dir、merge_missing_role_fields 和 validate_required_agent_role_description，遇到可跳过的问题则交给 push_agent_role_warning 记录。

调用图：调用 8 个内部函数（get_layers, agents_toml_from_layer, discover_agent_roles_in_dir, load_agent_roles_without_layers, merge_missing_role_fields, push_agent_role_warning, read_declared_role, validate_required_agent_role_description）；被 1 处调用（load_config_with_layer_stack）；外部调用 4 个（new, new, new, format!）。

fn push_agent_role_warning(startup_warnings: &mut Vec<String>, err: std::io::Error)

作用：这个函数把一个坏角色配置的问题变成统一格式的启动警告。它的作用是：告诉用户哪里错了，但在允许跳过的场景下不让整个程序立刻崩掉。

数据流：进去的是一个警告列表和一个错误。它把错误包装成“忽略格式不正确的代理角色定义”这类消息，写入日志，再把同样的文字放进启动警告列表。出来没有新值，但警告列表被更新了。

调用关系：它是 load_agent_roles 和 discover_agent_roles_in_dir 的“报错记录员”。当这些流程发现某个角色文件坏了、重复了或字段不合格时，会把错误交给它，让启动阶段能继续处理其他角色。

调用图：被 2 处调用（discover_agent_roles_in_dir, load_agent_roles）；外部调用 2 个（format!, warn!）。

async fn load_agent_roles_without_layers(
    fs: &dyn ExecutorFileSystem,
    cfg: &ConfigToml,
) -> std::io::Result<BTreeMap<String, AgentRoleConfig>>

作用：这是没有配置层时的简化读取方式。它只从主配置里的 agents 段读取角色，而且比较严格：出错就直接返回错误。

数据流：进去的是文件系统和主配置。它查看 cfg.agents 里声明的角色，一个个调用 read_declared_role 读成正式配置，再检查每个角色必须有说明，并防止同名角色重复。出来是一张角色表；如果缺说明、重复或文件有问题，就返回错误。

调用关系：它只会被 load_agent_roles 在发现没有配置层时调用。和分层模式不同，它不使用 push_agent_role_warning 来跳过坏角色，而是把问题直接交回上层，让配置加载失败。

调用图：调用 2 个内部函数（read_declared_role, validate_required_agent_role_description）；被 1 处调用（load_agent_roles）；外部调用 3 个（new, new, format!）。

async fn read_declared_role(
    fs: &dyn ExecutorFileSystem,
    declared_role_name: &str,
    role_toml: &AgentRoleToml,
) -> std::io::Result<(String, AgentRoleConfig)>

作用：这个函数读取一个在配置里明确写出来的角色。它既能处理直接写在 agents 表里的字段，也能继续打开这个角色指向的单独配置文件。

数据流：进去的是文件系统、声明时用的角色名和这个角色的 TOML 配置。它先把 TOML 字段转换成 AgentRoleConfig；如果里面有 config_file，就检查路径并读取那个文件。文件里的 name 可以改掉最终角色名，文件里的 description 和 nickname_candidates 也可以补充配置里没写的内容。出来是最终角色名和角色配置。

调用关系：它被 load_agent_roles 和 load_agent_roles_without_layers 调用，用来处理“显式声明”的角色。它内部先交给 agent_role_config_from_toml 做基础转换，再在需要时交给 read_resolved_agent_role_file 读取外部角色文件。

调用图：调用 3 个内部函数（agent_role_config_from_toml, read_resolved_agent_role_file, from_absolute_path）；被 2 处调用（load_agent_roles, load_agent_roles_without_layers）。

fn merge_missing_role_fields(role: &mut AgentRoleConfig, fallback: &AgentRoleConfig)

作用：这个函数用旧配置给新配置补空。它让高优先级配置可以只覆盖一部分字段，而不用把整个角色重新写一遍。

数据流：进去的是一个准备保存的新角色配置，以及一个低优先级的备用角色配置。它检查 description、config_file、nickname_candidates 这些字段，如果新角色没写，就从备用配置里复制过来。出来没有单独返回值，但新角色对象被补齐了。

调用关系：它只被 load_agent_roles 在合并多层配置时使用。场景是同名角色在更高层出现了，但只写了部分内容，于是这个函数负责把低层已有内容接上，避免因为覆盖而丢字段。

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

fn agents_toml_from_layer(
    layer_toml: &TomlValue,
    config_base_dir: Option<&Path>,
) -> std::io::Result<Option<AgentsToml>>

作用：这个函数从某一层配置里取出 agents 这一段，并把它变成程序能用的结构。它还会让相对路径按该配置文件所在目录来解释。

数据流：进去的是一层原始 TOML 值和可选的配置目录。它先找有没有 agents 字段；没有就返回 None。若有，它在配置目录的上下文里反序列化，也就是把通用 TOML 数据变成 AgentsToml 这种明确结构。出来是可选的 AgentsToml；格式不对时返回错误。

调用关系：它被 load_agent_roles 在读取每一层配置时调用。它只负责“把这一层的 agents 段拿出来并看懂”，后续每个角色怎么读则交给 read_declared_role。

调用图：被 1 处调用（load_agent_roles）；外部调用 1 个（get）。

async fn agent_role_config_from_toml(
    fs: &dyn ExecutorFileSystem,
    role_name: &str,
    role: &AgentRoleToml,
) -> std::io::Result<AgentRoleConfig>

作用：这个函数把单个角色在 agents 表里的配置，转换成内部使用的 AgentRoleConfig。它顺手做基础检查，避免空说明、坏昵称或不存在的配置文件混进去。

数据流：进去的是文件系统、角色名和角色的 TOML 配置。它把 config_file 转成绝对路径并检查文件是否存在，再清理 description 两边空格，检查 nickname_candidates 是否合格。出来是整理后的 AgentRoleConfig。

调用关系：它被 read_declared_role 调用，是显式声明角色的第一道加工工序。它会把验证工作分给 validate_agent_role_config_file、normalize_agent_role_description 和 normalize_agent_role_nickname_candidates。

调用图：调用 3 个内部函数（normalize_agent_role_description, normalize_agent_role_nickname_candidates, validate_agent_role_config_file）；被 1 处调用（read_declared_role）；外部调用 1 个（format!）。

fn parse_agent_role_file_contents(
    contents: &str,
    role_file_label: &Path,
    config_base_dir: &Path,
    role_name_hint: Option<&str>,
) -> std::io::Result<ResolvedAgentRoleFile>

作用：这个函数解析一个单独的代理角色文件内容。它把文件里的角色名字、说明、昵称和剩余配置拆开，并检查这个文件是不是一个合格的角色文件。

数据流：进去的是文件文字内容、用于报错显示的文件路径、相对路径基准目录，以及可选的角色名提示。它先把文本解析成 TOML，再转成 RawAgentRoleFileToml，清理说明，检查 developer_instructions 是否需要且不能为空，确定最终角色名，检查昵称列表。最后它从原始配置里移除 name、description、nickname_candidates，只留下真正要作为角色配置使用的内容。出来是 ResolvedAgentRoleFile，包含角色名、说明、昵称和剩余配置。

调用关系：它被 read_resolved_agent_role_file 用于读取磁盘文件后的解析，也会被 load_role_layer_toml 用于把角色文件当配置层加载。它内部调用多个校验和规范化函数，是角色文件格式的核心把关者。

调用图：调用 4 个内部函数（normalize_agent_role_description, normalize_agent_role_nickname_candidates, validate_agent_role_file_developer_instructions, new）；被 2 处调用（load_role_layer_toml, read_resolved_agent_role_file）；外部调用 3 个（new, format!, from_str）。

async fn read_resolved_agent_role_file(
    fs: &dyn ExecutorFileSystem,
    path: &AbsolutePathBuf,
    role_name_hint: Option<&str>,
) -> std::io::Result<ResolvedAgentRoleFile>

作用：这个函数负责从磁盘读一个代理角色文件，并把它解析成程序能理解的结果。它把“读文件”和“解析内容”连起来。

数据流：进去的是文件系统、角色文件的绝对路径，以及可选的角色名提示。它先把路径变成文件系统接口使用的 URI，读取文本内容，再用文件所在目录作为相对路径基准，调用 parse_agent_role_file_contents 解析。出来是 ResolvedAgentRoleFile。

调用关系：它被 read_declared_role 用来读取 config_file 指向的角色文件，也被 discover_agent_roles_in_dir 用来读取自动发现的角色文件。真正的格式检查交给 parse_agent_role_file_contents。

调用图：调用 5 个内部函数（parse_agent_role_file_contents, read_file_text, as_path, parent, from_abs_path）；被 2 处调用（discover_agent_roles_in_dir, read_declared_role）。

fn normalize_agent_role_description(
    field_label: &str,
    description: Option<&str>,
) -> std::io::Result<Option<String>>

作用：这个函数清理角色说明字段。它允许没写说明，但如果写了，就不能只是空格。

数据流：进去的是字段标签和可选的说明文字。它把说明前后的空白去掉；如果去完为空，就返回错误；如果有内容，就返回清理后的字符串；如果原本没有，就返回 None。

调用关系：它被 agent_role_config_from_toml 和 parse_agent_role_file_contents 调用。它只做字段级的小检查，至于“某个角色最终必须有说明”则由 validate_required_agent_role_description 负责。

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

fn validate_required_agent_role_description(
    role_name: &str,
    description: Option<&str>,
) -> std::io::Result<()>

作用：这个函数检查一个角色最终有没有说明。说明是给人看的角色介绍，所以缺了就不允许这个角色通过。

数据流：进去的是角色名和可选说明。它只看说明是否存在；存在就通过，不存在就返回带角色名的错误。它不修改任何数据。

调用关系：它被 load_agent_roles 和 load_agent_roles_without_layers 在角色即将进入最终角色表前调用。前面的 normalize_agent_role_description 只保证“写了就不能空”，这个函数保证“最终必须写”。

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

fn validate_agent_role_file_developer_instructions(
    role_file_label: &Path,
    developer_instructions: Option<&str>,
    require_present: bool,
) -> std::io::Result<()>

作用：这个函数检查角色文件里的 developer_instructions，也就是给这个角色的工作指令。自动发现的独立角色文件必须写这项，写了也不能是空白。

数据流：进去的是文件路径、可选的 developer_instructions 文本，以及是否强制要求存在。它会去掉空白后判断：空字符串报错；有内容通过；没有内容但被要求存在时报错；没有内容且不强制时通过。出来是成功或错误。

调用关系：它只被 parse_agent_role_file_contents 调用。这样无论角色文件是被显式引用，还是从 agents 目录里自动发现，都会在解析时接受这条规则检查。

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

async fn validate_agent_role_config_file(
    fs: &dyn ExecutorFileSystem,
    role_name: &str,
    config_file: Option<&AbsolutePathBuf>,
) -> std::io::Result<()>

作用：这个函数确认角色声明里写的 config_file 真的是一个存在的文件。这样后面读取时不会才发现路径写错或指向了文件夹。

数据流：进去的是文件系统、角色名和可选的绝对路径。如果没有 config_file，它直接通过。若有路径，它查询文件元数据；查不到就返回带路径的错误，查到了但不是普通文件也返回错误，是文件则通过。

调用关系：它被 agent_role_config_from_toml 调用，是显式声明角色时对 config_file 的提前检查。读取文件内容本身则稍后由 read_resolved_agent_role_file 完成。

调用图：调用 1 个内部函数（from_abs_path）；被 1 处调用（agent_role_config_from_toml）；外部调用 3 个（new, get_metadata, format!）。

fn normalize_agent_role_nickname_candidates(
    field_label: &str,
    nickname_candidates: Option<&[String]>,
) -> std::io::Result<Option<Vec<String>>>

作用：这个函数清理并检查角色的候选昵称列表。它保证昵称好读、不会重复，也不会带奇怪字符。

数据流：进去的是字段标签和可选昵称数组。没有昵称就返回 None；有昵称时，它要求列表不能为空，每个名字去掉前后空格后不能空，不能重复，只能包含 ASCII 字母、数字、空格、连字符和下划线。出来是清理后的昵称列表，或一条说明具体问题的错误。

调用关系：它被 agent_role_config_from_toml 和 parse_agent_role_file_contents 调用。也就是说，不管昵称写在主配置里，还是写在单独角色文件里，都走同一套规则。

调用图：被 2 处调用（agent_role_config_from_toml, parse_agent_role_file_contents）；外部调用 4 个（new, with_capacity, new, format!）。

async fn discover_agent_roles_in_dir(
    fs: &dyn ExecutorFileSystem,
    agents_dir: &AbsolutePathBuf,
    declared_role_files: &BTreeSet<PathBuf>,
    startup_warnings: &mut Vec<String>,
) -> std::

作用：这个函数自动扫描 agents 目录，发现没有在配置里明确声明的角色文件。它让用户只要把一个 TOML 文件放到指定目录，就能增加一个角色。

数据流：进去的是文件系统、agents 目录路径、已经声明过的角色文件集合和启动警告列表。它先收集目录下所有 TOML 文件，跳过已经被显式声明引用的文件，然后逐个读取解析。解析失败或角色名重复时，它记录警告并跳过。成功时，它把文件路径作为该角色的 config_file，连同说明和昵称放进角色表。出来是一张自动发现的角色表。

调用关系：它被 load_agent_roles 在处理每个配置层时调用。它把找文件的事交给 collect_agent_role_files，把读文件和解析的事交给 read_resolved_agent_role_file，把可忽略错误交给 push_agent_role_warning。

调用图：调用 3 个内部函数（collect_agent_role_files, push_agent_role_warning, read_resolved_agent_role_file）；被 1 处调用（load_agent_roles）；外部调用 4 个（new, contains, new, format!）。

async fn collect_agent_role_files(
    fs: &dyn ExecutorFileSystem,
    dir: &AbsolutePathBuf,
) -> std::io::Result<Vec<AbsolutePathBuf>>

作用：这个函数递归找出某个目录下所有 .toml 角色文件。它像在文件夹里翻箱倒柜，只挑出扩展名是 toml 的文件。

数据流：进去的是文件系统和要扫描的目录。它用一个待访问目录列表从根目录开始读；遇到子目录就继续放进列表，遇到普通文件且扩展名是 toml 就收集起来。目录不存在时直接跳过。最后把文件路径排序后返回。

调用关系：它只被 discover_agent_roles_in_dir 调用，是自动发现角色流程的第一步。它不解析文件内容，只负责把候选文件找齐，后续判断这些文件是否合格交给 read_resolved_agent_role_file 和 parse_agent_role_file_contents。

调用图：调用 2 个内部函数（join, from_abs_path）；被 1 处调用（discover_agent_roles_in_dir）；外部调用 3 个（new, read_directory, vec!）。

async fn read_config_lock_from_path(
    path: &AbsolutePathBuf,
) -> io::Result<ConfigLockfileToml>

作用：从指定路径读取配置锁文件，并把它解析成程序能用的结构。有人启动程序、需要按锁文件固定配置时，会先用它把锁文件拿进来。

数据流：进去的是一个绝对路径。它先从磁盘读取文本，再按 TOML（一种常见配置文件格式）解析成 ConfigLockfileToml，接着检查锁文件版本是否支持。出来的是解析好的锁文件；如果文件读不了、内容不合法或版本不对，就出来一个带说明的输入输出错误。

调用关系：它被 build_inner 在构建配置时调用，是配置锁流程的入口之一。它自己会把版本检查交给 validate_config_lock_metadata_shape，把读文件和解析 TOML 的具体活儿交给外部库函数。

调用图：调用 1 个内部函数（validate_config_lock_metadata_shape）；被 1 处调用（build_inner）；外部调用 2 个（read_to_string, from_str）。

fn config_lockfile(config: ConfigToml) -> ConfigLockfileToml

作用：把一份普通配置包装成配置锁文件。它会加上锁文件格式版本和当前 Codex 程序版本，方便以后判断是不是同一代工具生成的。

数据流：进去的是 ConfigToml，也就是已经整理好的配置。它把固定的 CONFIG_LOCK_VERSION、编译时记录的当前软件版本，以及这份配置放到一个 ConfigLockfileToml 里。出来的是完整的锁文件结构。

调用关系：它被 to_config_lockfile_toml 调用，用在“把当前配置导出成锁文件”的流程中。它只负责打包，不负责写磁盘，也不负责比较。

调用图：被 1 处调用（to_config_lockfile_toml）；外部调用 1 个（env!）。

fn validate_config_lock_replay(
    expected_lock: &ConfigLockfileToml,
    actual_lock: &ConfigLockfileToml,
    options: ConfigLockReplayOptions,
) -> io::Result<()>

作用：检查“锁文件里记录的配置”和“现在重新算出来的配置”是否一致。它是防止配置漂移的核心关卡。

数据流：进去的是期望的锁文件、实际生成的锁文件，以及一个选项：是否允许 Codex 版本不同。它先检查两个锁文件的格式版本，再按选项决定要不要比较 Codex 版本。之后它会清理掉不该参与比较的调试项和兼容性遗留项，再比较两边是否完全相同。出来是成功的空结果；如果不一致，就返回错误，并尽量附上人能看懂的差异文本。

调用关系：它被 validate_config_lock_if_configured 在真正启用锁检查时调用，也被多项测试调用来确认各种边界情况。它会借助 config_lock_for_comparison 先把两份锁文件整理成可公平比较的样子；发现差异时交给 compact_diff 生成差异说明，并用 config_lock_error 包成统一错误。

调用图：调用 4 个内部函数（compact_diff, config_lock_error, config_lock_for_comparison, validate_config_lock_metadata_shape）；被 5 处调用（lock_validation_can_ignore_codex_version_mismatch, lock_validation_ignores_removed_apps_mcp_path_override, lock_validation_rejects_codex_version_mismatch_by_default, lock_validation_reports_config_diff, validate_config_lock_if_configured）；外部调用 1 个（format!）。

fn lock_layer_from_config(
    lock_path: &AbsolutePathBuf,
    lockfile: &ConfigLockfileToml,
) -> io::Result<ConfigLayerEntry>

作用：把锁文件里的配置变成配置系统的一层输入。这样锁文件就能像普通用户配置文件一样参与后续合并。

数据流：进去的是锁文件路径和锁文件内容。它先拿出锁文件里的配置，并去掉锁文件控制用的调试开关，再转成 TOML 值，最后包装成 ConfigLayerEntry，标明来源是某个用户文件。出来的是一个配置层；如果转换失败，就返回错误。

调用关系：它被 build_inner 调用，用在配置构建过程中。它把清理工作交给 config_without_lock_controls，把序列化成 TOML 值的工作交给 toml_value，最后用 ConfigLayerEntry::new 做成配置层。

调用图：调用 3 个内部函数（new, config_without_lock_controls, toml_value）；被 1 处调用（build_inner）；外部调用 1 个（clone）。

fn config_without_lock_controls(config: &ConfigToml) -> ConfigToml

作用：复制一份配置，并去掉专门控制配置锁的调试开关。这样这些“控制锁怎么工作的按钮”不会被当作普通业务配置保存或比较。

数据流：进去的是一份配置引用。它先克隆出一份新配置，再在新配置上清除 config_lockfile 相关调试项。出来的是清理后的配置；原来的配置不会被改动。

调用关系：它被 build_inner 和 lock_layer_from_config 使用。它本身不懂具体清理规则，而是把修改动作交给 clear_config_lock_debug_controls。

调用图：调用 1 个内部函数（clear_config_lock_debug_controls）；被 2 处调用（build_inner, lock_layer_from_config）；外部调用 1 个（clone）。

fn clear_config_lock_debug_controls(config: &mut ConfigToml)

作用：直接在一份配置里删除“配置锁调试控制项”。这些项只影响锁文件验证方式，不应该成为被锁住的配置内容。

数据流：进去的是一份可修改的 ConfigToml。它查看 debug 区域，如果里面有 config_lockfile 设置就删掉；如果 debug 区域因此变空，也把整个 debug 区域去掉。出来没有单独返回值，但传入的配置会被改干净。

调用关系：它是多个流程共用的小清洁工。config_without_lock_controls 用它清理副本，config_lock_for_comparison 用它清理比较对象，drop_lockfile_inputs 也会用它避免锁文件输入污染最终配置。

调用图：被 3 处调用（config_lock_for_comparison, config_without_lock_controls, drop_lockfile_inputs）。

fn validate_config_lock_metadata_shape(lock: &ConfigLockfileToml) -> io::Result<()>

作用：检查配置锁文件的基础元信息是否是当前程序支持的形状。现在主要是检查锁文件版本号。

数据流：进去的是一个配置锁文件。它看 lock.version 是否等于当前代码支持的 CONFIG_LOCK_VERSION。版本正确就成功返回；版本不对就返回一个说明“支持不了这个锁文件版本”的错误。

调用关系：read_config_lock_from_path 读完锁文件后会调用它，validate_config_lock_replay 在比较前也会调用它。它发现问题时用 config_lock_error 生成统一风格的错误。

调用图：调用 1 个内部函数（config_lock_error）；被 2 处调用（read_config_lock_from_path, validate_config_lock_replay）；外部调用 1 个（format!）。

fn config_lock_for_comparison(
    lockfile: &ConfigLockfileToml,
    options: ConfigLockReplayOptions,
) -> ConfigLockfileToml

作用：把锁文件整理成适合比较的样子。它会去掉那些不应该影响“配置是否相同”判断的内容。

数据流：进去的是锁文件和比较选项。它先克隆一份锁文件，再清掉配置锁调试控制项；如果配置里有 features，就清理掉已经移除的兼容性旧条目；如果允许忽略 Codex 版本差异，就把版本字段清空。出来的是一份可公平比较的锁文件副本。

调用关系：它只被 validate_config_lock_replay 调用，是正式比较前的整理步骤。它把调试项清理交给 clear_config_lock_debug_controls，自己负责按选项处理版本字段。

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

fn config_lock_error(message: impl Into<String>) -> io::Error

作用：把一段错误说明包装成标准的输入输出错误。这样这个文件里各种失败都能用同一种错误类型往外传。

数据流：进去的是可以变成字符串的错误信息。它把信息转成 String，再放进 io::Error::other。出来的是一个 io::Error，调用者可以直接返回给上层。

调用关系：它被 toml_round_trip、validate_config_lock_metadata_shape、validate_config_lock_replay 等函数用来统一报错方式。它不判断业务对错，只负责把错误话术装进标准错误容器。

调用图：被 3 处调用（toml_round_trip, validate_config_lock_metadata_shape, validate_config_lock_replay）；外部调用 2 个（into, other）。

fn compact_diff(root: &str, expected: &T, actual: &T) -> io::Result<String>

作用：当两份配置锁不一样时，生成一段精简的差异文本。这样人不需要自己从大段配置里找不同。

数据流：进去的是一个根名称，以及期望值和实际值。它先把两边都序列化成漂亮排版的 TOML 文本，再用文本对比工具生成 unified diff（一种常见的“减号表示旧内容、加号表示新内容”的差异格式），并只保留少量上下文。出来的是差异字符串；如果序列化失败，就返回错误。

调用关系：它只在 validate_config_lock_replay 发现两份锁文件不同后被调用。它负责把机器比较结果翻译成人能读的差异说明。

调用图：被 1 处调用（validate_config_lock_replay）；外部调用 2 个（from_lines, to_string_pretty）。

fn toml_value(value: &T, label: &str) -> io::Result<toml::Value>

作用：把任意可序列化的数据转成 TOML 的通用值。它像一个转换插头，让内部结构能放进配置层或继续做 TOML 往返检查。

数据流：进去的是某个可序列化的值和一个用于报错的标签。它尝试把这个值转成 toml::Value。出来的是 TOML 值；如果转换失败，就返回带标签的错误，告诉人是哪类东西转不出来。

调用关系：lock_layer_from_config 用它把配置变成配置层需要的 TOML 值，toml_round_trip 用它检查某个值是否能完整表示成 TOML。

调用图：被 2 处调用（lock_layer_from_config, toml_round_trip）；外部调用 1 个（try_from）。

fn toml_round_trip(value: &impl Serialize, label: &'static str) -> io::Result<T>

作用：检查一个值能不能完整、无损地用 TOML 表达，并把它转成目标类型。它用于防止某些内部配置结构看似能写成 TOML，实际写完再读回来却变了样。

数据流：进去的是一个可序列化的值和标签，并指定要转成的目标类型 T。它先转成 TOML 通用值，再尝试转成目标类型，然后再把目标类型转回 TOML 值做对比。如果前后 TOML 值一样，就返回目标类型；如果转换失败或前后不一致，就返回错误。

调用关系：它被 resolved_config_to_toml 调用，用在把已经解析好的最终配置重新表达为 TOML 的流程里。它内部依赖 toml_value 做转换，出错时用 config_lock_error 包装说明。

调用图：调用 2 个内部函数（config_lock_error, toml_value）；被 1 处调用（resolved_config_to_toml）；外部调用 2 个（clone, format!）。