插件与连接器生态管理

fn is_openai_curated_marketplace_name(marketplace_name: &str) -> bool

作用：这个函数用来判断一个插件市场名字是不是 OpenAI 官方精选市场。有人需要区分“官方精选来源”和普通第三方来源时，就会用它。

数据流：进去的是一个市场名字字符串。函数把它分别和两个固定官方名字比较：openai-curated 和 openai-api-curated。如果匹配其中任何一个，就出来 true；否则出来 false。它不改动任何数据，只做一次简单判断。

调用关系：它是这个库对外提供的小工具函数，配合文件里定义的官方市场常量使用。其他插件管理、市场读取或展示流程在需要识别官方精选市场时，可以调用它，而它本身不再把任务交给别的函数。

fn plugin(&self) -> &ResolvedPlugin

作用：返回已经解析好的插件描述。别人需要知道这个插件叫什么、入口在哪里、声明了什么能力时，会用它来取出这些信息。

数据流：进去的是这个已绑定插件对象本身 → 它不做复制，也不重新读取文件，只是把里面保存的插件描述借出来 → 出来的是一个只读的插件描述引用，原对象没有变化。

调用关系：它通常在后续的 load 流程里被调用。前面 resolve_bound 已经把插件解析好并放进 ResolvedExecutorPlugin，load 再通过这个函数拿到插件说明，继续决定怎么加载。

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

fn file_system(&self) -> &dyn ExecutorFileSystem

作用：返回解析这个插件时用过的那个文件系统。这样后续读取插件包里的文件时，还会从同一个执行环境里读，不会跑到别的地方。

数据流：进去的是这个已绑定插件对象本身 → 它取出内部保存的文件系统对象，并把它当作通用的 ExecutorFileSystem 使用 → 出来的是一个只读的文件系统引用，方便后面继续读文件。

调用关系：它也会在 load 流程里被调用。plugin 函数给出“插件说明”，file_system 函数给出“去哪里读插件文件”，两者一起保证加载阶段既知道读什么，也知道从哪里读。

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

fn new(environment_manager: Arc<EnvironmentManager>) -> Self

作用：创建一个插件提供者，并把执行环境管理器交给它。执行环境管理器可以理解成一张登记表，记录当前有哪些可用环境。

数据流：进去的是一个共享的 EnvironmentManager → 它把这个管理器保存到 ExecutorPluginProvider 里面 → 出来的是一个新的提供者对象，以后可以靠它查环境、找插件。

调用关系：这是使用这个提供者前的准备步骤。测试里会直接调用它来搭建场景，正常系统启动或组装组件时也会创建它，然后后续通过 resolve 或 resolve_bound 去真正解析插件。

调用图：被 6 处调用（host_and_executor_sources_parse_the_same_manifest, executor_root_must_be_an_explicit_absolute_path, malformed_preferred_manifest_does_not_fall_through_to_alternate, standalone_capability_root_is_not_a_plugin, unavailable_environment_does_not_fall_back_to_host_filesystem, new）。

async fn resolve_bound(
        &self,
        selected_root: &SelectedCapabilityRoot,
    ) -> Result<Option<ResolvedExecutorPlugin>, ExecutorPluginProviderError>

作用：根据用户选中的根目录，解析出一个插件，并且把插件和读取它的文件系统绑在一起返回。它的重点是“找到插件”之外，还记住“从哪个环境读到的”。

数据流：进去的是一个 SelectedCapabilityRoot，也就是用户选中的能力根目录信息 → 它先调用 selected_plugin_root 检查并转换路径，再用环境编号从 EnvironmentManager 找到对应环境，拿到该环境的文件系统，然后把目录和文件系统交给 resolve_plugin_root 查找并解析清单 → 出来的是可能存在的 ResolvedExecutorPlugin；如果目录里没有插件清单，就返回空；如果环境不存在或读取失败，就返回明确错误。

调用关系：它是这个文件的核心入口之一。PluginProvider 的 resolve 会调用它，只是最后丢掉文件系统绑定；resolve_snapshot 这类需要保留文件系统的流程也会调用它。它自己把路径检查交给 selected_plugin_root，把实际看目录、找清单、读清单、构造插件描述的工作交给 resolve_plugin_root。

调用图：调用 2 个内部函数（resolve_plugin_root, selected_plugin_root）；被 2 处调用（resolve, resolve_snapshot）。

async fn resolve(
        &self,
        selected_root: &SelectedCapabilityRoot,
    ) -> Result<Option<ResolvedPlugin>, Self::Error>

作用：实现通用的 PluginProvider 接口，返回普通的插件描述。它适合只关心“有没有插件、插件是什么”，不需要继续持有文件系统的调用者。

数据流：进去的是用户选中的能力根目录 → 它调用 resolve_bound 完成真正解析 → 如果解析到了已绑定插件，就只取出里面的 ResolvedPlugin 返回；如果没有插件就返回空；如果出错就把错误原样传出去。

调用关系：这是对外接口的一层适配。真正干活的是 resolve_bound；它存在的原因是让 ExecutorPluginProvider 能符合 codex_plugin::PluginProvider 这个通用约定，被其他只认识 PluginProvider 的代码直接使用。

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

fn selected_plugin_root(
    selected_root: &SelectedCapabilityRoot,
) -> Result<AbsolutePathBuf, ExecutorPluginProviderError>

作用：检查用户选中的插件根目录路径是否合格，并把它变成系统内部认可的绝对路径。绝对路径就是从磁盘根部开始写清楚的位置，避免相对路径造成“到底从哪儿算起”的混乱。

数据流：进去的是 SelectedCapabilityRoot，里面带有根目录编号和路径字符串 → 它取出环境位置里的 path，先确认这个路径是绝对路径，再用 from_absolute_path_checked 做更严格的合法性检查 → 出来的是 AbsolutePathBuf；如果路径不是绝对路径或格式不合法，就返回 InvalidRootPath 错误，并带上根目录编号和原因。

调用关系：resolve_bound 一开始就会调用它。只有路径先过关，后面 resolve_plugin_root 才会去访问文件系统；这样可以把“路径本身不可信”的问题挡在最前面。

调用图：调用 1 个内部函数（from_absolute_path_checked）；被 1 处调用（resolve_bound）；外部调用 1 个（from）。

async fn resolve_plugin_root(
    selected_root: &SelectedCapabilityRoot,
    plugin_root: AbsolutePathBuf,
    file_system: &dyn ExecutorFileSystem,
) -> Result<Option<ResolvedPlugin>, ExecutorPlugin

作用：在指定执行环境的文件系统里，检查一个目录是否是插件包，并把它变成系统可用的插件描述。它负责真正的“进目录找清单、读清单、解析清单”。

数据流：进去的是选中的根目录信息、已经确认过的插件根路径、以及对应环境的文件系统 → 它先把路径转成文件 URI（一种把文件路径写成统一地址的格式），检查根路径是不是文件夹；然后按预设的清单文件位置逐个尝试，找到第一个真实文件；接着读取清单文本，调用 parse_plugin_manifest 解析内容；最后用 ResolvedPlugin::from_environment 把根目录、环境编号、清单路径和清单内容组合成插件描述 → 出来的是 Some 插件描述；如果没有任何清单文件，出来的是 None；如果检查、读取、解析或构造失败，就返回对应的详细错误。

调用关系：它由 resolve_bound 调用，是解析插件的实际工作台。它会依次使用文件系统的 get_metadata 检查目录和候选清单，用 read_file_text 读取清单，用 parse_plugin_manifest 理解清单内容，再用 from_environment 生成最终的插件描述。

调用图：调用 5 个内部函数（parse_plugin_manifest, read_file_text, from_environment, join, from_abs_path）；被 1 处调用（resolve_bound）；外部调用 1 个（get_metadata）。

fn load_plugin_manifest(plugin_root: &Path) -> Option<PluginManifest>

作用：从本机磁盘上的某个插件目录里，找到并读取插件清单文件。别人想知道一个插件的基本信息时，通常会先调用它。

数据流：输入是插件根目录路径。它先找清单文件的位置，再把文件内容读成文字，然后交给 parse_plugin_manifest 解析；如果找不到、读不了或解析失败，就返回空值，并在解析失败时记一条警告。

调用关系：它是这个文件对外最常用的入口。插件加载、读取插件应用、读取插件 MCP 服务器、生成遥测信息、市场页详情等流程都会用它；它自己把真正的理解和整理工作交给 parse_plugin_manifest。

调用图：调用 1 个内部函数（parse_plugin_manifest）；被 12 处调用（load_declared_plugin_mcp_servers, load_plugin, load_plugin_apps, plugin_telemetry_metadata_from_root, load_sources, read_plugin_detail_for_marketplace_plugin, host_and_executor_sources_parse_the_same_manifest, load_manifest, resolve_marketplace_plugin_entry, extract_remote_plugin_bundle_to_path (+2 more)）；外部调用 3 个（find_plugin_manifest_path, read_to_string, warn!）。

fn parse_plugin_manifest(
    plugin_root: &Path,
    manifest_path: &Path,
    contents: &str,
) -> Result<PluginManifest, serde_json::Error>

作用：把 plugin.json 的原始文字，变成系统内部使用的插件清单对象。它不只是“读 JSON”，还会补默认值、清理字段、检查路径。

数据流：输入是插件根目录、清单文件路径和 JSON 文本。它先按宽松的原始结构读出字段，再决定插件名、修剪版本号、整理界面信息、解析默认提示词和各种文件路径，最后输出一个 PluginManifest。

调用关系：load_plugin_manifest 会在读到文件后调用它；其他解析插件根目录的流程也会直接用它。它把路径检查交给 resolve_manifest_path、resolve_manifest_path_value、resolve_manifest_hooks 等小函数，把默认提示词整理交给 resolve_default_prompts。

调用图：调用 3 个内部函数（resolve_manifest_hooks, resolve_manifest_path, resolve_manifest_path_value）；被 3 处调用（load_plugin_manifest, resolve_plugin_root, plugin_root_resolution_uses_supplied_executor_file_system）；外部调用 1 个（file_name）。

fn resolve_manifest_hooks(
    plugin_root: &Path,
    hooks: Option<RawPluginManifestHooks>,
) -> Option<PluginManifestHooks>

作用：整理清单里的 hooks 字段。hooks 可以理解成“插件在某些时机自动执行的规则”，这个函数负责接受几种写法并转成统一格式。

数据流：输入是插件根目录和原始 hooks 值。它根据 hooks 是单个路径、多个路径、内联对象、对象数组还是错误格式来处理：路径会被安全解析，内联内容会直接包装起来，错误格式会被警告并忽略；输出是可用的 hooks 配置或空值。

调用关系：parse_plugin_manifest 在组装最终清单时调用它。它遇到路径时继续交给 resolve_manifest_path 检查，遇到明显不合规的内容则只记录警告，不阻断整个清单解析。

调用图：调用 1 个内部函数（resolve_manifest_path）；被 1 处调用（parse_plugin_manifest）；外部调用 4 个（Inline, Paths, warn!, vec!）。

fn resolve_interface_asset_path(
    plugin_root: &Path,
    field: &'static str,
    path: Option<&str>,
) -> Option<AbsolutePathBuf>

作用：解析界面资源文件的路径，比如插件图标、Logo、截图。它存在是为了让这些展示资源也走同一套安全路径规则。

数据流：输入是插件根目录、字段名和用户写的路径字符串。它直接把这些信息交给 resolve_manifest_path，得到插件目录内的绝对路径，或者在路径不合规时得到空值。

调用关系：parse_plugin_manifest 整理 interface 展示信息时会用它。它本身只是一个薄包装，让图标、Logo、截图这些字段的代码读起来更清楚。

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

fn resolve_default_prompts(
    manifest_path: &Path,
    value: Option<&RawPluginManifestDefaultPrompt>,
) -> Option<Vec<String>>

作用：整理插件界面里的默认提示词。默认提示词就是用户打开插件时可以直接点选或预填的一小段话。

数据流：输入是清单文件路径和 defaultPrompt 原始值。它支持旧的单字符串写法，也支持字符串数组；每条会交给 resolve_default_prompt_str 清理和检查，遇到数字、对象等错误内容会警告，超过最多 3 条就停止；输出是整理好的提示词列表或空值。

调用关系：parse_plugin_manifest 在处理 interface.defaultPrompt 时调用它。它负责整体形状判断，具体每条文字的空白清理和长度限制交给 resolve_default_prompt_str，错误提示交给 warn_invalid_default_prompt。

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

fn resolve_default_prompt_str(manifest_path: &Path, field: &str, prompt: &str) -> Option<String>

作用：检查并清理一条默认提示词。它保证展示给用户的提示词不是空的，也不会长到不适合放在界面里。

数据流：输入是清单路径、字段名和原始提示词。它会把连续空白压成普通单空格，去掉前后多余空白；如果结果为空或超过 128 个字符，就记录警告并返回空值；合格时返回清理后的文字。

调用关系：resolve_default_prompts 会对每一条候选提示词调用它。它发现问题时不自己拼复杂日志，而是交给 warn_invalid_default_prompt 统一记录。

调用图：调用 1 个内部函数（warn_invalid_default_prompt）；被 1 处调用（resolve_default_prompts）；外部调用 1 个（format!）。

fn warn_invalid_default_prompt(manifest_path: &Path, field: &str, message: &str)

作用：专门记录默认提示词格式不对的警告。这样相关警告的格式统一，排查问题时更容易看懂。

数据流：输入是清单文件路径、出问题的字段名和说明文字。它把这些信息写进日志；没有返回有业务意义的数据，也不会修改清单。

调用关系：resolve_default_prompts 和 resolve_default_prompt_str 发现默认提示词不合格时会调用它。它是错误提示的小出口，负责把“哪里错了”讲清楚。

调用图：被 2 处调用（resolve_default_prompt_str, resolve_default_prompts）；外部调用 1 个（warn!）。

fn json_value_type(value: &JsonValue) -> &'static str

作用：把 JSON 值的真实类型翻译成容易写进警告里的英文词，比如 string、array、object。这样日志能说清楚“期望什么，实际来了什么”。

数据流：输入是一个 JSON 值。它判断这个值是空、布尔值、数字、字符串、数组还是对象，然后返回对应的类型名称字符串。

调用关系：多个校验函数在发现字段类型不对时会用它来生成警告文字。它不参与解析主流程，只负责让报错信息更明白。

fn resolve_manifest_path_value(
    plugin_root: &Path,
    field: &'static str,
    path: Option<&RawPluginManifestPath>,
) -> Option<AbsolutePathBuf>

作用：处理那种“应该是一个路径字符串”的清单字段，比如 skills。它先确认字段确实是字符串，再交给统一路径检查。

数据流：输入是插件根目录、字段名和原始路径值。值如果是字符串，就调用 resolve_manifest_path 解析成安全的绝对路径；如果是别的 JSON 类型，就记录警告并返回空值。

调用关系：parse_plugin_manifest 在处理 skills 字段时调用它。它是原始 JSON 类型和安全路径解析之间的过渡层。

调用图：调用 1 个内部函数（resolve_manifest_path）；被 1 处调用（parse_plugin_manifest）；外部调用 1 个（warn!）。

fn resolve_manifest_path(
    plugin_root: &Path,
    field: &'static str,
    path: Option<&str>,
) -> Option<AbsolutePathBuf>

作用：把清单里的相对路径变成安全的绝对路径。它是防止插件路径乱指、越界访问的重要守门员。

数据流：输入是插件根目录、字段名和路径字符串。它要求路径必须以 ./ 开头，不能只是 ./，不能包含 ..，也不能包含会逃出插件目录的特殊路径片段；通过检查后，把它拼到插件根目录下并转成绝对路径，失败则记录警告并返回空值。

调用关系：parse_plugin_manifest、resolve_interface_asset_path、resolve_manifest_hooks、resolve_manifest_path_value 都依赖它。凡是清单里提到本地文件的位置，基本都要经过这道安全检查。

调用图：调用 1 个内部函数（try_from）；被 4 处调用（parse_plugin_manifest, resolve_interface_asset_path, resolve_manifest_hooks, resolve_manifest_path_value）；外部调用 4 个（join, new, new, warn!）。

fn write_manifest(plugin_root: &Path, version: Option<&str>, interface: &str)

作用：测试用的小帮手，用来快速在临时插件目录里写一个标准位置的 plugin.json。这样每个测试不用重复写建目录和写文件的代码。

数据流：输入是插件根目录、可选版本号和 interface JSON 片段。它创建 .codex-plugin 目录，把这些内容拼成完整清单文件并写到磁盘上；输出不返回清单，只改变测试临时目录里的文件。

调用关系：多个测试在准备测试插件时调用它。后续测试再通过 tests::load_manifest 或 load_plugin_manifest 读取它刚写好的文件。

调用图：外部调用 4 个（join, format!, create_dir_all, write）。

fn write_alternate_plugin_manifest(plugin_root: &Path, contents: &str)

作用：测试用来写备用位置的插件清单文件。它验证系统不只认识默认清单路径，也认识另一种可发现路径。

数据流：输入是插件根目录和清单内容。它创建备用清单所在目录，把内容写入 .claude-plugin/plugin.json；输出主要是磁盘上多了这个测试文件。

调用关系：tests::plugin_manifest_uses_alternate_discoverable_path 会调用它，然后再调用加载流程确认备用路径能被发现。

调用图：外部调用 3 个（join, create_dir_all, write）。

fn load_manifest(plugin_root: &Path) -> PluginManifest

作用：测试里的简化读取函数。它把 load_plugin_manifest 的空值情况直接当成测试失败，方便测试代码更短。

数据流：输入是插件根目录。它调用 load_plugin_manifest，期望一定能得到 PluginManifest；如果没得到，测试会失败；成功时返回清单对象。

调用关系：多个测试用它读取前面写好的临时清单。它是测试代码和正式加载函数之间的一层方便包装。

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

fn plugin_interface_accepts_legacy_default_prompt_string()

作用：确认旧版写法还能用：defaultPrompt 如果是单个字符串，也会被接受。这样老插件不会因为格式升级突然坏掉。

数据流：它创建临时目录，写入一个 defaultPrompt 为字符串的清单，然后加载清单，最后检查提示词被清理成单元素列表，并且多余空格被压掉。

调用关系：这个测试通过 write_manifest 准备文件，通过 tests::load_manifest 走正式加载流程，最终验证 resolve_default_prompts 和 resolve_default_prompt_str 的效果。

调用图：外部调用 4 个（assert_eq!, load_manifest, write_manifest, tempdir）。

fn plugin_interface_normalizes_default_prompt_array()

作用：确认 defaultPrompt 数组会被正确筛选和清理。它覆盖了正常文字、错误类型、太长、空字符串、超过数量上限等情况。

数据流：它写入一个混合了多种情况的提示词数组，加载后检查结果只保留 3 条合格提示词，并且每条都被整理掉多余空白。

调用关系：这个测试主要验证 resolve_default_prompts 的列表处理规则，也间接验证单条提示词清理函数和最多 3 条的限制。

调用图：外部调用 5 个（assert_eq!, load_manifest, write_manifest, format!, tempdir）。

fn plugin_interface_ignores_invalid_default_prompt_shape()

作用：确认 defaultPrompt 如果写成对象这类不支持的形状，会被忽略而不是误解析。这样坏字段不会污染最终清单。

数据流：它写入一个 defaultPrompt 为对象的清单，加载后取出 interface，检查 default_prompt 是空值。

调用关系：这个测试走 write_manifest 和 tests::load_manifest，重点覆盖 resolve_default_prompts 对整体类型错误的处理。

调用图：外部调用 4 个（assert_eq!, load_manifest, write_manifest, tempdir）。

fn plugin_manifest_reads_trimmed_version()

作用：确认版本号两边的空格会被去掉。这样插件作者不小心多打空格时，系统内部仍拿到干净版本号。

数据流：它写入带前后空格的 version 字段，加载清单，然后断言最终 version 是修剪后的 1.2.3-beta+7。

调用关系：这个测试通过正式加载流程检查 parse_plugin_manifest 对 version 字段的清理逻辑。

调用图：外部调用 4 个（assert_eq!, load_manifest, write_manifest, tempdir）。

fn plugin_manifest_reads_keywords()

作用：确认清单里的 keywords 关键字列表能被读出来。关键字通常用于描述插件用途，方便搜索、分类或展示。

数据流：它手动创建清单目录并写入带 keywords 的 JSON，加载后检查最终清单里的关键字列表和文件内容一致。

调用关系：这个测试直接准备文件，再通过 tests::load_manifest 进入正式读取流程，验证 parse_plugin_manifest 没有漏掉 keywords 字段。

调用图：外部调用 5 个（assert_eq!, load_manifest, create_dir_all, write, tempdir）。

fn plugin_manifest_uses_alternate_discoverable_path()

作用：确认系统能从备用清单路径发现插件。这样兼容不同来源或历史格式的插件目录。

数据流：它在备用位置写入 plugin.json，里面包含版本号和显示名；加载后检查版本号被修剪，显示名也被正确读出。

调用关系：这个测试调用 write_alternate_plugin_manifest 准备备用路径文件，再通过 tests::load_manifest 间接验证 load_plugin_manifest 使用的清单发现逻辑。

调用图：外部调用 4 个（assert_eq!, load_manifest, write_alternate_plugin_manifest, tempdir）。

async fn host_and_executor_sources_parse_the_same_manifest()

作用：确认主机端和执行器端看到的是同一个插件结果。简单说，就是不同入口读同一份插件清单，不能读出两套不一样的解释。

数据流：它创建临时插件并写入清单，先用 load_plugin_manifest 得到主机端清单；再创建执行器插件提供者，让它解析同一个插件目录；最后手工构造期望的 ResolvedPlugin，并比较两边完全一致。

调用关系：这是跨模块的集成测试。它既调用本文件的 load_plugin_manifest，也调用 ExecutorPluginProvider 的解析流程，用来保证这个文件的清单解析规则和执行器那边使用的规则保持一致。

调用图：调用 5 个内部函数（load_plugin_manifest, new, default_for_tests, from_environment, from_absolute_path_checked）；外部调用 4 个（new, assert_eq!, write_manifest, tempdir）。

fn apps_route_available(auth_mode: Option<AuthMode>) -> bool

作用：这个函数判断当前登录或认证方式是否支持“应用路由”。简单说，就是看系统现在是不是能走 Codex 后端；能走才允许这些应用声明继续存在。

数据流：输入是一份可能存在也可能不存在的 AuthMode（认证模式，也就是系统怎么确认用户身份和后端能力）。函数检查它是否存在，并询问这个认证模式是否使用 Codex 后端。最后输出一个布尔值：true 表示应用路由可用，false 表示不可用。

调用关系：它是这条规则的第一道门槛。apply_app_mcp_routing_policy 会先调用它决定要不要清空应用声明；load_plugin_mcp_servers 也会用它判断加载插件 MCP 服务器时是否要考虑应用路由。

调用图：被 2 处调用（apply_app_mcp_routing_policy, load_plugin_mcp_servers）。

fn apply_app_mcp_routing_policy(
    apps: &mut Vec<AppDeclaration>,
    mcp_servers: &mut HashMap<String, M>,
    auth_mode: Option<AuthMode>,
    plugin_active: bool,
)

作用：这个函数把“应用声明”和“MCP 服务器”之间的冲突处理掉。它会在应用路由不可用时清空应用声明；在可用且插件启用时，删除和应用同名的 MCP 服务器，避免重复登记。

数据流：输入包括一份可修改的应用声明列表、一份可修改的 MCP 服务器表、当前认证模式，以及插件是否启用。它先用 apps_route_available 判断应用路由能不能用；不能用就把应用列表清空。能用时，如果插件启用且应用列表不为空，它会收集所有应用名字，再把 MCP 服务器表里同名的条目删掉。结果是：应用列表和 MCP 服务器表被原地改好，不额外返回新对象。

调用关系：它是插件加载和展示前的一道统一整理步骤。load_plugin_mcp_servers、read_plugin_detail_for_marketplace_plugin、resolve_loaded_plugins_for_auth、build_remote_plugin_detail 会在不同场景下调用它，确保无论是加载插件、读取市场详情，还是按认证状态解析插件，最终都遵守同一套去重和可用性规则。它自己只把“是否可用”的判断交给 apps_route_available。

调用图：调用 1 个内部函数（apps_route_available）；被 4 处调用（load_plugin_mcp_servers, read_plugin_detail_for_marketplace_plugin, resolve_loaded_plugins_for_auth, build_remote_plugin_detail）。

fn from(value: MarketplacePluginInstallPolicy) -> Self

作用：把本文件内部使用的安装策略，转换成应用服务器协议里要用的安装策略。这样市场读出来的规则可以直接交给外层接口展示或传输。

数据流：进去的是一个市场里的安装规则，比如不可用、可用、默认安装；函数按同名含义做一一对应；出来的是协议层认识的 PluginInstallPolicy，不改动其他数据。

调用关系：它是两个类型之间的翻译器。市场解析代码先得到内部规则，之后当这些规则要发给应用服务器协议时，就靠这个转换保持说法一致。

fn from(value: MarketplacePluginAuthPolicy) -> Self

作用：把市场里的认证策略转换成协议层的认证策略。认证策略就是说明插件是在安装时要授权，还是使用时才授权。

数据流：进去的是内部 MarketplacePluginAuthPolicy；函数把 OnInstall 或 OnUse 映射成协议里的同等值；出来的是 PluginAuthPolicy，不读取文件也不产生副作用。

调用关系：它和 PluginInstallPolicy::from 类似，负责把市场模块的内部说法翻译成外部接口能理解的说法。

fn io(context: &'static str, source: io::Error) -> Self

作用：快速包装一个文件读写错误，并附上一句固定的上下文说明。这样报错时不是只说“失败”，而是能说清楚是在读市场文件时失败。

数据流：进去的是一段简短场景文字和底层 io::Error（输入输出错误，比如读文件失败）；函数把它们装进 MarketplaceError::Io；出来的是统一的市场错误对象。

调用关系：它被 load_raw_marketplace_manifest 用来把系统文件错误变成市场模块自己的错误格式，方便上层统一处理和展示。

fn find_marketplace_plugin(
    marketplace_path: &AbsolutePathBuf,
    plugin_name: &str,
) -> Result<ResolvedMarketplacePlugin, MarketplaceError>

作用：在指定的市场清单里按名字找一个插件，并把它整理成系统能使用的完整插件信息。别人想从某个市场拿到某个插件时，会先用它。

数据流：进去的是市场文件路径和插件名；它先调用 load_raw_marketplace_manifest 读取原始清单，再逐个插件比较名字，命中后交给 resolve_marketplace_plugin_entry 校验和整理来源、策略、界面信息；出来的是 ResolvedMarketplacePlugin，找不到就返回 PluginNotFound 错误。

调用关系：它是按名查插件的入口。read_plugin_for_config 和 find_installable_marketplace_plugin 会调用它；它自己把读文件交给 load_raw_marketplace_manifest，把单个插件的细节整理交给 resolve_marketplace_plugin_entry。

调用图：调用 2 个内部函数（load_raw_marketplace_manifest, resolve_marketplace_plugin_entry）；被 2 处调用（read_plugin_for_config, find_installable_marketplace_plugin）。

fn find_installable_marketplace_plugin(
    marketplace_path: &AbsolutePathBuf,
    plugin_name: &str,
    restriction_product: Option<Product>,
) -> Result<ResolvedMarketplacePlugin, MarketplaceError

作用：找插件的同时确认它真的允许安装。它会检查插件市场写的安装规则，以及这个插件是否允许当前产品使用。

数据流：进去的是市场路径、插件名和可选的产品限制；它先用 find_marketplace_plugin 找到插件，再看安装策略是不是 NotAvailable，并检查 products 列表是否匹配当前产品；通过就原样返回插件，不通过就返回 PluginNotAvailable。

调用关系：安装流程 install_plugin 和 install_plugin_with_remote_sync 会用它做最后把关。它站在 find_marketplace_plugin 之后，相当于“找到了不等于能装，还要过许可检查”。

调用图：调用 1 个内部函数（find_marketplace_plugin）；被 2 处调用（install_plugin, install_plugin_with_remote_sync）。

fn list_marketplaces(
    additional_roots: &[AbsolutePathBuf],
) -> Result<MarketplaceListOutcome, MarketplaceError>

作用：列出系统能发现的所有插件市场。调用者只要给额外的搜索位置，它会自动把用户主目录也算进去。

数据流：进去的是额外根目录列表；它调用 home_dir 找用户主目录，再调用 list_marketplaces_with_home 做实际发现和加载；出来的是 MarketplaceListOutcome，里面有成功加载的市场和加载失败的错误列表。

调用关系：它是对外常用的市场列表入口。刷新插件缓存、按配置发现市场、列出市场配置时会调用它；真正的细活交给 list_marketplaces_with_home。

调用图：调用 2 个内部函数（home_dir, list_marketplaces_with_home）；被 3 处调用（refresh_non_curated_plugin_cache_with_mode, discover_marketplaces_for_config, list_marketplaces_for_config）。

fn home_dir() -> Option<PathBuf>

作用：找当前用户的主目录，也就是通常放用户级配置的地方。它尽量兼容不同系统和环境变量。

数据流：它不需要参数；先看 HOME 和 USERPROFILE 环境变量，要求值非空且是绝对路径，找不到再问系统库 dirs::home_dir；出来的是一个可选路径，找不到就是 None。

调用关系：list_marketplaces 用它把用户主目录纳入市场搜索范围，checkout_remote_plugin_share 也会用它决定远程插件共享内容放在哪里。

调用图：被 2 处调用（list_marketplaces, checkout_remote_plugin_share）。

fn validate_marketplace_root(root: &Path) -> Result<String, MarketplaceError>

作用：检查一个目录是不是合法的插件市场根目录，并返回这个市场的名字。它常用于用户配置或升级时，防止把普通文件夹误当成市场。

数据流：进去的是一个目录路径；它先用 find_marketplace_manifest_path 看目录下有没有支持的 marketplace.json 位置，再用 load_marketplace 真正读取并校验；出来的是市场名，失败时返回说明清楚的 MarketplaceError。

调用关系：查找、安装、升级已配置市场时会调用它。它先找清单位置，再把完整加载工作交给 load_marketplace。

调用图：调用 2 个内部函数（find_marketplace_manifest_path, load_marketplace）；被 4 处调用（find_marketplace_root_by_name, installed_marketplace_root_for_source, validate_marketplace_source_root, upgrade_configured_git_marketplace）；外部调用 1 个（to_path_buf）。

fn find_marketplace_manifest_path(root: &Path) -> Option<AbsolutePathBuf>

作用：在一个根目录下面寻找支持的市场清单文件。它知道系统认可的几个固定相对位置。

数据流：进去的是根目录；它依次拼出 .agents/plugins/marketplace.json、.agents/plugins/api_marketplace.json、.claude-plugin/marketplace.json，哪个真实存在就转成绝对路径返回；都不存在就返回 None。

调用关系：导入插件、检查配置快照、发现市场路径、验证市场根目录、升级市场配置都会用它。它是“这个目录里有没有市场清单”的基础探测器。

调用图：被 5 处调用（import_plugins, configured_marketplace_snapshot_issues, discover_marketplace_paths_from_roots, validate_marketplace_root, upgrade_configured_git_marketplace）。

fn supported_marketplace_manifest_path(path: &Path) -> Option<AbsolutePathBuf>

作用：判断传入的路径本身是不是一个受支持位置上的市场清单文件。它比只看文件存在更严格，还会检查目录布局对不对。

数据流：进去的是一个文件路径；它先确认这是文件，再用受支持的布局规则反推市场根目录，最后转成绝对路径；符合就返回 Some，失败就返回 None。

调用关系：discover_marketplace_paths_from_roots 会先用它处理那些直接指向 marketplace.json 的输入。这样用户既可以给目录，也可以给清单文件。

调用图：调用 1 个内部函数（try_from）；被 1 处调用（discover_marketplace_paths_from_roots）；外部调用 2 个（is_file, to_path_buf）。

fn invalid_marketplace_layout_error(path: &AbsolutePathBuf) -> MarketplaceError

作用：生成“市场文件放错位置了”的错误。它把这种布局问题统一包装成 InvalidMarketplaceFile。

数据流：进去的是市场清单路径；函数复制这个路径，并附上固定提示“marketplace file is not in a supported location”；出来的是 MarketplaceError。

调用关系：marketplace_root_dir 在无法从清单路径推出合法市场根目录时会调用它，避免各处手写不一致的错误消息。

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

fn marketplace_root_from_layout(marketplace_path: &Path, relative_path: &str) -> Option<PathBuf>

作用：根据一个已知的清单相对位置，反推出市场的根目录。简单说，就是从 marketplace.json 往上倒着数目录。

数据流：进去的是市场文件路径和一种支持的相对布局；它从相对路径的最后一段开始，逐段检查文件名和目录名是否吻合，吻合就一路往父目录走；出来的是根目录路径，不吻合就 None。

调用关系：marketplace_root_dir 用它尝试每一种支持布局。它是判断“这个 marketplace.json 是不是摆在规定位置”的核心小工具。

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

fn load_marketplace(path: &AbsolutePathBuf) -> Result<Marketplace, MarketplaceError>

作用：把一个市场清单文件加载成对外可用的 Marketplace 对象。它不仅读 JSON，还会过滤坏插件、补齐本地插件信息。

数据流：进去的是 marketplace.json 的绝对路径；它调用 load_raw_marketplace_manifest 读原始清单，再对每个插件调用 resolve_marketplace_plugin_entry，坏插件会被警告并跳过；它从本地插件 manifest 中取版本和关键词，最后调用 resolve_marketplace_interface 整理市场显示信息；出来的是 Marketplace。

调用关系：刷新精选插件缓存、列出市场、验证市场根目录都会用它。它是从“文件里的原始清单”变成“系统可展示市场”的主加工线。

调用图：调用 3 个内部函数（load_raw_marketplace_manifest, resolve_marketplace_interface, resolve_marketplace_plugin_entry）；被 3 处调用（refresh_curated_plugin_cache, list_marketplaces_with_home, validate_marketplace_root）；外部调用 3 个（new, clone, warn!）。

fn list_marketplaces_with_home(
    additional_roots: &[AbsolutePathBuf],
    home_dir: Option<&Path>,
) -> Result<MarketplaceListOutcome, MarketplaceError>

作用：按指定的用户主目录和额外位置发现并加载所有市场。这个函数把“发现路径”和“读取市场”串起来，还会收集失败原因。

数据流：进去的是额外根目录列表和可选主目录；它先用 discover_marketplace_paths_from_roots 找到候选清单，再逐个调用 load_marketplace；成功的放进 marketplaces，失败的写警告并放进 errors；出来的是 MarketplaceListOutcome。

调用关系：list_marketplaces 调用它做实际工作。它像一个批处理器：路径发现交给 discover_marketplace_paths_from_roots，单个市场读取交给 load_marketplace。

调用图：调用 2 个内部函数（discover_marketplace_paths_from_roots, load_marketplace）；被 1 处调用（list_marketplaces）；外部调用 2 个（default, warn!）。

fn discover_marketplace_paths_from_roots(
    additional_roots: &[AbsolutePathBuf],
    home_dir: Option<&Path>,
) -> Vec<AbsolutePathBuf>

作用：从用户主目录和一批额外路径里找出所有可能的市场清单文件，并去重。它支持给根目录、给清单文件、也支持从 Git 仓库根目录推断。

数据流：进去的是额外根目录列表和可选主目录；它先在主目录找默认市场，再逐个处理额外路径：如果路径本身是支持的清单就加入，如果目录里有清单就加入，否则尝试找 Git 仓库根目录再找清单；出来的是不重复的绝对清单路径列表。

调用关系：list_marketplaces_with_home 调用它作为第一步。它把各种用户可能给出的路径形式整理成统一的 marketplace.json 路径。

调用图：调用 3 个内部函数（find_marketplace_manifest_path, supported_marketplace_manifest_path, try_from）；被 1 处调用（list_marketplaces_with_home）；外部调用 2 个（new, get_git_repo_root）。

fn load_raw_marketplace_manifest(
    path: &AbsolutePathBuf,
) -> Result<RawMarketplaceManifest, MarketplaceError>

作用：读取并解析 marketplace.json 的原始内容。它只负责把文件变成 RawMarketplaceManifest，不做太多业务判断。

数据流：进去的是清单绝对路径；它用 read_to_string 读文件，文件不存在会变成 MarketplaceNotFound，其他读取失败会包装成 Io；读到字符串后用 serde_json 解析 JSON，格式错就返回 InvalidMarketplaceFile；出来的是原始清单结构。

调用关系：find_marketplace_plugin 和 load_marketplace 都从它开始。它是所有市场信息进入程序的文件读取入口。

调用图：调用 1 个内部函数（as_path）；被 2 处调用（find_marketplace_plugin, load_marketplace）；外部调用 2 个（read_to_string, from_str）。

fn resolve_marketplace_plugin_entry(
    marketplace_path: &AbsolutePathBuf,
    marketplace_name: &str,
    plugin: RawMarketplaceManifestPlugin,
) -> Result<Option<ResolvedMarketplacePlugin>, Market

作用：把清单里一个原始插件条目，整理成系统真正能理解的插件条目。它会处理来源、插件 ID、策略、界面分类和本地 manifest。

数据流：进去的是市场路径、市场名和一个原始插件条目；它先用 resolve_supported_plugin_source 判断来源是否支持并规范化，本地插件会调用 load_plugin_manifest 读取插件说明书，然后用 plugin_interface_with_marketplace_category 合并分类；最后创建 PluginId，并组装 ResolvedMarketplacePlugin；如果来源不支持则返回 None。

调用关系：find_marketplace_plugin 和 load_marketplace 都会对命中的或遍历到的插件调用它。它把来源解析交给 resolve_supported_plugin_source，把界面分类合并交给 plugin_interface_with_marketplace_category。

调用图：调用 4 个内部函数（load_plugin_manifest, plugin_interface_with_marketplace_category, resolve_supported_plugin_source, new）；被 2 处调用（find_marketplace_plugin, load_marketplace）。

fn resolve_supported_plugin_source(
    marketplace_path: &AbsolutePathBuf,
    plugin_name: &str,
    source: RawMarketplaceManifestPluginSource,
) -> Option<MarketplacePluginSource>

作用：判断插件来源是不是系统支持的，并把可支持的来源解析出来。遇到不支持或解析失败的来源，它不会让整个市场崩掉，而是跳过这个插件。

数据流：进去的是市场路径、插件名和原始来源；如果来源是不认识的 JSON，就写警告并返回 None；否则调用 resolve_plugin_source 做具体解析，成功返回 Some，失败也写警告并返回 None。

调用关系：resolve_marketplace_plugin_entry 会先用它过滤来源。它把“能不能处理这个来源”的温和失败逻辑包起来，避免一个坏插件拖垮整个市场。

调用图：调用 1 个内部函数（resolve_plugin_source）；被 1 处调用（resolve_marketplace_plugin_entry）；外部调用 1 个（warn!）。

fn resolve_plugin_source(
    marketplace_path: &AbsolutePathBuf,
    source: RawMarketplaceManifestPluginSource,
) -> Result<MarketplacePluginSource, MarketplaceError>

作用：把插件来源转换成统一的内部表示：要么是本地路径，要么是 Git 仓库地址。它负责识别清单里几种不同写法。

数据流：进去的是市场路径和原始来源；本地路径会交给 resolve_local_plugin_source_path 变成绝对路径，Git 地址会交给 normalize_git_plugin_source_url 整理，子目录交给 normalize_remote_plugin_subdir 检查，ref 和 sha 交给 normalize_optional_git_selector 清理；出来的是 MarketplacePluginSource。

调用关系：resolve_supported_plugin_source 在确认来源类型可处理后调用它。它是插件来源解析的分岔路口，把不同来源分别交给专门的小函数。

调用图：调用 4 个内部函数（normalize_git_plugin_source_url, normalize_optional_git_selector, normalize_remote_plugin_subdir, resolve_local_plugin_source_path）；被 1 处调用（resolve_supported_plugin_source）；外部调用 1 个（unreachable!）。

fn resolve_local_plugin_source_path(
    marketplace_path: &AbsolutePathBuf,
    path: &str,
) -> Result<AbsolutePathBuf, MarketplaceError>

作用：把本地插件的相对路径变成安全的绝对路径。它会防止清单用 ../ 之类的写法跑到市场目录外面。

数据流：进去的是市场清单路径和本地来源字符串；它要求路径必须以 ./ 开头，去掉 ./ 后不能为空，并且每一段都必须是普通目录名；然后调用 marketplace_root_dir 找市场根目录，再拼出插件绝对路径；失败时返回 InvalidMarketplaceFile。

调用关系：resolve_plugin_source 在遇到本地插件来源时调用它。它承担安全边界检查，确保本地插件只能来自市场根目录内部。

调用图：调用 2 个内部函数（marketplace_root_dir, to_path_buf）；被 1 处调用（resolve_plugin_source）；外部调用 1 个（new）。

fn normalize_remote_plugin_subdir(
    marketplace_path: &AbsolutePathBuf,
    path: &str,
) -> Result<String, MarketplaceError>

作用：整理 Git 仓库里插件所在的子目录，并检查它不会越界。它处理的是“仓库下载下来后，插件在里面哪个文件夹”。

数据流：进去的是市场路径和子目录字符串；它先去掉首尾空白，也允许开头的 ./，然后要求剩下内容不为空，且不能包含 .、.. 这类特殊路径段；出来的是干净的子目录字符串。

调用关系：resolve_plugin_source 在 Git 来源带 path 或 git-subdir 写法时调用它。它防止远程插件路径指向仓库根目录之外。

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

fn normalize_git_plugin_source_url(
    marketplace_path: &AbsolutePathBuf,
    url: &str,
) -> Result<String, MarketplaceError>

作用：把清单里的 Git 来源地址整理成系统能使用的形式，并拒绝明显不合法的地址。它支持完整网址、相对路径、本地 file、SSH、以及 GitHub 简写。

数据流：进去的是市场路径和 URL 字符串；它先 trim 去空白，空字符串报错；http/https 会交给 normalize_github_git_url 补 .git，./ 或 ../ 开头会交给 normalize_relative_git_plugin_source_url，本地 file、绝对路径、SSH 直接接受，像 owner/repo 的 GitHub 简写交给 normalize_github_shorthand_url；都不符合就返回错误。

调用关系：resolve_plugin_source 在解析 Git 插件来源时调用它。它把各种用户友好写法统一成后续下载代码能理解的地址。

调用图：调用 4 个内部函数（normalize_github_git_url, normalize_github_shorthand_url, normalize_relative_git_plugin_source_url, to_path_buf）；被 1 处调用（resolve_plugin_source）；外部调用 1 个（format!）。

fn normalize_relative_git_plugin_source_url(
    marketplace_path: &AbsolutePathBuf,
    url: &str,
) -> Result<String, MarketplaceError>

作用：把相对的 Git 来源路径转换成市场根目录内的本地路径字符串。它明确禁止 ..，防止路径跳出市场目录。

数据流：进去的是市场清单路径和相对 URL；它先用 marketplace_root_dir 找到市场根目录，再按 / 或 \ 分段拼路径，忽略空段和 .，遇到 .. 就报错；出来的是拼好的路径字符串。

调用关系：normalize_git_plugin_source_url 在发现 URL 是相对路径时调用它。它专门处理“这个 Git 来源就在市场目录旁边”的情况。

调用图：调用 2 个内部函数（marketplace_root_dir, to_path_buf）；被 1 处调用（normalize_git_plugin_source_url）。

fn normalize_optional_git_selector(value: &Option<String>) -> Option<String>

作用：清理可选的 Git 选择器，比如分支名、标签名或提交号。空白值会被当成没有填写。

数据流：进去的是 Option<String>；如果有值就去掉首尾空白，空了就丢弃，不空就转成新的 String；出来的是 Option<String>。

调用关系：resolve_plugin_source 在处理 Git 来源的 ref 和 sha 时调用它。它避免把空字符串误当成有效的分支或提交。

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

fn normalize_github_git_url(url: &str) -> String

作用：把 GitHub 的 HTTPS 仓库地址补成更标准的 .git 结尾。其他地址保持不变。

数据流：进去的是一个 URL 字符串；如果它以 https://github.com/ 开头且没有 .git 结尾，就在末尾加 .git；否则原样复制；出来的是整理后的字符串。

调用关系：normalize_git_plugin_source_url 在处理 http 或 https 地址时调用它。它让 GitHub 地址更适合后续 Git 克隆使用。

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

fn normalize_github_shorthand_url(source: &str) -> Option<String>

作用：把 owner/repo 这种 GitHub 简写变成完整的 HTTPS Git 地址。比如 openai/example 会变成 https://github.com/openai/example.git。

数据流：进去的是来源字符串；它先用 looks_like_github_shorthand 判断是不是刚好两段合法名字，再取出 owner 和 repo，去掉 repo 末尾可能已有的 .git，最后拼成完整 GitHub 地址；不符合就返回 None。

调用关系：normalize_git_plugin_source_url 在其他 URL 形式都不匹配时会尝试调用它。它让清单作者可以写更短的 GitHub 地址。

调用图：调用 1 个内部函数（looks_like_github_shorthand）；被 1 处调用（normalize_git_plugin_source_url）；外部调用 1 个（format!）。

fn looks_like_github_shorthand(source: &str) -> bool

作用：判断一个字符串看起来是不是 GitHub 的 owner/repo 简写。它只接受两段，中间一个斜杠，没有多余段。

数据流：进去的是字符串；它按 / 分成 owner、repo 和可能的 extra，要求 owner 和 repo 都通过 is_github_shorthand_segment 检查，并且没有第三段；出来的是 true 或 false。

调用关系：normalize_github_shorthand_url 先用它做外形检查。它负责挡掉不像 GitHub 简写的字符串，避免误转换。

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

fn is_github_shorthand_segment(segment: &str) -> bool

作用：检查 GitHub 简写里的某一段名字是否合法。它要求非空，并且只包含常见的字母、数字、横线、下划线和点。

数据流：进去的是 owner 或 repo 这一小段字符串；它逐个字符检查是否是 ASCII 字母数字，或 -、_、.；全部合格就返回 true，否则 false。

调用关系：looks_like_github_shorthand 用它分别检查 owner 和 repo。它是 GitHub 简写判断里最小的字符级校验。

fn plugin_interface_with_marketplace_category(
    mut interface: Option<PluginManifestInterface>,
    category: Option<String>,
) -> Option<PluginManifestInterface>

作用：把市场清单里的分类合并进插件界面信息里，并且市场分类优先。这样市场可以覆盖插件自己 manifest 里的分类。

数据流：进去的是可选的插件界面信息和可选分类；如果市场给了分类，它会确保 interface 存在，然后把 category 设置成市场分类；如果市场没给分类，就原样返回原来的 interface。

调用关系：resolve_marketplace_plugin_entry 会在整理插件时调用它，read_plugin_detail_for_marketplace_plugin 也会用它。它解决“插件自己说一个分类，市场又给一个分类时听谁的”的问题。

调用图：被 2 处调用（read_plugin_detail_for_marketplace_plugin, resolve_marketplace_plugin_entry）。

fn marketplace_root_dir(
    marketplace_path: &AbsolutePathBuf,
) -> Result<AbsolutePathBuf, MarketplaceError>

作用：从 marketplace.json 的路径反推出市场根目录。因为清单文件可能放在几个固定子目录下，很多相对路径都要先知道根目录才能算。

数据流：进去的是市场清单绝对路径；它遍历支持的清单相对位置，逐个调用 marketplace_root_from_layout 尝试反推根目录，成功后转成 AbsolutePathBuf；全部失败就调用 invalid_marketplace_layout_error 返回布局错误。

调用关系：resolve_local_plugin_source_path 和 normalize_relative_git_plugin_source_url 会用它把相对路径变成根目录内路径，run_list 也会用它。它是所有“相对市场根目录”计算的基础。

调用图：调用 4 个内部函数（invalid_marketplace_layout_error, marketplace_root_from_layout, as_path, try_from）；被 3 处调用（run_list, normalize_relative_git_plugin_source_url, resolve_local_plugin_source_path）。

fn resolve_marketplace_interface(
    interface: Option<RawMarketplaceManifestInterface>,
) -> Option<MarketplaceInterface>

作用：把原始市场界面信息整理成对外可用的 MarketplaceInterface。当前它只保留有实际内容的显示名。

数据流：进去的是可选的 RawMarketplaceManifestInterface；没有 interface 就返回 None，有 interface 但 display_name 也是空的也返回 None；如果有 display_name，就包装成 MarketplaceInterface 返回。

调用关系：load_marketplace 在组装最终 Marketplace 时调用它。它负责把 JSON 里的界面小配置清理成更干净的内部结构。

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

fn log_plugin_load_errors(plugins: &[LoadedPlugin<McpServerConfig>])

作用：把已经加载过的插件里出现的错误写到日志里，方便启动时排查哪个插件坏了。它不修复问题，只负责把问题说清楚。

数据流：输入是一组已加载插件 → 它逐个查看有没有 error 字段 → 对有错误的插件输出警告日志，不改变插件内容。

调用关系：在插件重新加载流程中被上层调用；它站在加载结束之后，专门负责把 load_plugin 等步骤留下的失败原因展示出来。

调用图：被 1 处调用（plugins_for_config_with_force_reload）；外部调用 2 个（iter, warn!）。

async fn load_plugins_from_layer_stack(
    config_layer_stack: &ConfigLayerStack,
    extra_plugins: HashMap<String, PluginConfig>,
    store: &PluginStore,
    restriction_product: Option<Product>,

作用：按当前配置一次性加载所有插件的完整能力，包括技能、MCP 工具服务器、应用和钩子。它是外部最常用的插件加载入口之一。

数据流：输入是配置层、额外插件配置、插件仓库、产品限制和冲突偏好 → 先从配置层算出技能启停规则 → 再交给更底层的加载函数 → 输出已加载插件列表。

调用关系：它被插件配置加载、强制重载和测试流程使用；自己不逐个读文件，而是把范围设成“加载全部能力”后交给 load_plugins_from_layer_stack_with_scope。

调用图：调用 2 个内部函数（load_plugins_from_layer_stack_with_scope, skill_config_rules_from_stack）；被 3 处调用（plugins_for_config_with_force_reload, plugins_for_layer_stack, load_plugins_ignores_project_config_files）。

async fn load_plugins_from_layer_stack_with_scope(
    config_layer_stack: &ConfigLayerStack,
    extra_plugins: HashMap<String, PluginConfig>,
    store: &PluginStore,
    prefer_remote_curated_confl

作用：按指定范围加载插件：可以加载全部能力，也可以只加载钩子。它负责把“要加载哪些插件”和“每个插件怎么加载”串起来。

数据流：输入是配置、额外插件、插件仓库、冲突偏好和加载范围 → 合并配置插件与远端已安装插件，排序，逐个调用 load_plugin → 输出加载结果列表，并记录重复的 MCP 服务器名警告。

调用关系：load_plugins_from_layer_stack 和 load_plugin_hooks_from_layer_stack 都靠它干实际编排；它再把单个插件的细活交给 load_plugin。

调用图：调用 3 个内部函数（configured_plugins_from_stack, load_plugin, merge_configured_plugins_with_remote_installed）；被 2 处调用（load_plugin_hooks_from_layer_stack, load_plugins_from_layer_stack）；外部调用 3 个（new, with_capacity, warn!）。

async fn load_plugin_hooks_from_layer_stack(
    config_layer_stack: &ConfigLayerStack,
    extra_plugins: HashMap<String, PluginConfig>,
    store: &PluginStore,
    prefer_remote_curated_conflicts:

作用：只加载已启用插件的钩子，不加载技能、MCP 服务器或应用。这样启动时需要钩子信息时，可以更快、更轻地完成。

数据流：输入是配置层、额外插件、插件仓库和冲突偏好 → 用“只加载钩子”的范围读取插件 → 从活跃插件里收集钩子来源和警告 → 输出 PluginHookLoadOutcome。

调用关系：被插件钩子汇总流程调用；它复用 load_plugins_from_layer_stack_with_scope，但刻意跳过大部分能力加载。

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

fn merge_configured_plugins_with_remote_installed(
    mut configured_plugins: HashMap<String, PluginConfig>,
    extra_plugins: HashMap<String, PluginConfig>,
    store: &PluginStore,
    prefer_remo

作用：把用户本地配置的插件和远端同步来的已安装插件合成一份清单。它还处理“同一个精选插件本地版和远端版打架”时该保留谁。

数据流：输入是本地配置、额外插件配置、插件仓库和冲突偏好 → 找出已安装的本地精选插件，再逐个合并额外插件 → 输出最终插件配置表，可能移除或跳过冲突项。

调用关系：在 load_plugins_from_layer_stack_with_scope 开始逐个加载前使用；它会调用 installed_plugin_name_for_marketplace 来判断远端精选插件是否和本地精选插件对应。

调用图：调用 3 个内部函数（installed_plugin_name_for_marketplace, active_plugin_version, parse）；被 1 处调用（load_plugins_from_layer_stack_with_scope）；外部调用 2 个（new, is_openai_curated_marketplace_name）。

fn installed_plugin_name_for_marketplace(
    plugin_key: &str,
    marketplace_name: &str,
    store: &PluginStore,
) -> Option<String>

作用：判断一个插件配置键是否属于指定市场，并且本地确实已经安装。符合条件时返回插件名。

数据流：输入是插件键、市场名和插件仓库 → 解析插件 ID，检查市场名和本地活跃安装目录 → 输出插件名，或在不匹配时输出空。

调用关系：只被 merge_configured_plugins_with_remote_installed 使用，用来识别远端精选插件和本地精选插件之间的冲突。

调用图：调用 2 个内部函数（active_plugin_root, parse）；被 1 处调用（merge_configured_plugins_with_remote_installed）。

fn remote_installed_plugins_to_config(
    plugins: &[RemoteInstalledPlugin],
    store: &PluginStore,
) -> HashMap<String, PluginConfig>

作用：把服务器告诉本机的“远端已安装插件列表”转换成普通插件配置。这样后续加载流程不用关心这些插件来自远端还是用户手写配置。

数据流：输入是远端插件列表和插件仓库 → 检查插件名是否合法、插件包是否已经在本地缓存中 → 输出插件键到 PluginConfig 的映射，坏数据会被跳过并记警告。

调用关系：被远端插件配置生成流程调用；它产出的配置之后会进入合并和加载流程。

调用图：被 1 处调用（remote_installed_plugin_configs）；外部调用 1 个（iter）。

fn refresh_curated_plugin_cache(
    codex_home: &Path,
    plugin_version: &str,
    configured_curated_plugin_ids: &[PluginId],
) -> Result<bool, String>

作用：刷新 OpenAI 精选市场插件的本地缓存，确保用户配置的精选插件对应当前程序版本里的插件包。它也会清理市场里已经不存在的旧插件。

数据流：输入是 codex_home、插件版本号和已配置的精选插件 ID → 找到精选市场文件，读取市场清单，比较本地缓存版本 → 必要时安装新版或卸载过期缓存 → 输出是否真的刷新过。

调用关系：这是精选插件缓存同步的主流程；它依赖 curated_marketplace_paths_for_cache_refresh 找市场文件，依赖 curated_plugin_cache_version 生成缓存版本，并通过插件仓库执行安装和卸载。

调用图：调用 5 个内部函数（curated_marketplace_paths_for_cache_refresh, curated_plugin_cache_version, load_marketplace, try_new, new）；外部调用 4 个（new, new, to_path_buf, warn!）。

fn curated_marketplace_paths_for_cache_refresh(
    codex_home: &Path,
) -> Result<Vec<AbsolutePathBuf>, String>

作用：找出刷新精选插件缓存时要读取的市场清单文件路径。它知道默认清单和可选 API 清单放在哪里。

数据流：输入是 codex_home → 拼出本地精选 marketplace.json 路径，并在存在时加入 api_marketplace.json → 输出绝对路径列表，路径不合法时返回错误。

调用关系：只在 refresh_curated_plugin_cache 中使用；它给后续 load_marketplace 提供要读取的文件位置。

调用图：调用 1 个内部函数（try_from）；被 1 处调用（refresh_curated_plugin_cache）；外部调用 2 个（join, vec!）。

fn curated_plugin_cache_version(plugin_version: &str) -> String

作用：把插件版本号整理成适合缓存目录使用的版本字符串。完整 Git 提交号太长时，它只取前 8 位。

数据流：输入是版本字符串 → 判断它是否像 40 位完整 Git SHA → 如果是就截短，否则原样返回。

调用关系：刷新精选缓存和安装已解析插件时都会用它；它内部靠 is_full_git_sha 判断是否需要截短。

调用图：调用 1 个内部函数（is_full_git_sha）；被 2 处调用（refresh_curated_plugin_cache, install_resolved_plugin）。

fn refresh_non_curated_plugin_cache(
    codex_home: &Path,
    additional_roots: &[AbsolutePathBuf],
) -> Result<bool, String>

作用：刷新非精选市场插件缓存，但只有在插件版本变化时才重新安装。适合后台循环里温和地保持插件最新。

数据流：输入是 codex_home 和额外市场根目录 → 带着“版本变了才刷新”的模式调用通用刷新函数 → 输出是否有缓存被更新。

调用关系：被非精选插件缓存刷新循环调用；它只是给 refresh_non_curated_plugin_cache_with_mode 选择普通模式。

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

fn refresh_non_curated_plugin_cache_force_reinstall(
    codex_home: &Path,
    additional_roots: &[AbsolutePathBuf],
) -> Result<bool, String>

作用：强制重装非精选市场插件缓存，不管版本有没有变化。适合升级或修复缓存时使用。

数据流：输入是 codex_home 和额外市场根目录 → 带着“强制重装”的模式调用通用刷新函数 → 输出是否有缓存被更新。

调用关系：被刷新循环和市场升级流程调用；它和 refresh_non_curated_plugin_cache 共用同一个底层实现，只是模式不同。

调用图：调用 1 个内部函数（refresh_non_curated_plugin_cache_with_mode）；被 2 处调用（run_non_curated_plugin_cache_refresh_loop, upgrade_configured_marketplaces_for_config）。

fn refresh_non_curated_plugin_cache_with_mode(
    codex_home: &Path,
    additional_roots: &[AbsolutePathBuf],
    mode: NonCuratedCacheRefreshMode,
) -> Result<bool, String>

作用：真正执行非精选插件缓存刷新的核心函数。它会从用户配置里找插件，再从发现到的市场里找到来源并安装到缓存。

数据流：输入是 codex_home、额外市场根目录和刷新模式 → 读取配置中的非精选插件，列出市场，定位每个插件来源，必要时把 Git 来源临时拉下来，再按版本安装 → 输出是否刷新过。

调用关系：普通刷新和强制刷新两个公开函数都调用它；它会用 configured_plugins_from_codex_home 读配置，用 materialize_marketplace_plugin_source 准备插件源码。

调用图：调用 7 个内部函数（configured_plugins_from_codex_home, materialize_marketplace_plugin_source, non_curated_plugin_ids_from_config_keys, list_marketplaces, try_new, plugin_version_for_source, new）；被 2 处调用（refresh_non_curated_plugin_cache, refresh_non_curated_plugin_cache_force_reinstall）；外部调用 4 个（new, to_path_buf, is_openai_curated_marketplace_name, warn!）。

fn configured_plugins_from_stack(
    config_layer_stack: &ConfigLayerStack,
) -> HashMap<String, PluginConfig>

作用：从当前配置层里取出用户最终生效的插件配置。配置层可以理解成多份配置叠加后的结果。

数据流：输入是 ConfigLayerStack → 取出有效用户配置，如果没有就返回空表 → 有的话交给 configured_plugins_from_user_config_value 解析 plugins 部分。

调用关系：load_plugins_from_layer_stack_with_scope 在决定加载哪些插件前调用它；它把配置系统和插件加载系统接起来。

调用图：调用 2 个内部函数（effective_user_config, configured_plugins_from_user_config_value）；被 1 处调用（load_plugins_from_layer_stack_with_scope）；外部调用 1 个（new）。

fn is_full_git_sha(value: &str) -> bool

作用：判断一个字符串是不是 40 位十六进制 Git 提交号。Git 提交号可以理解成代码版本的身份证。

数据流：输入是字符串 → 检查长度是否为 40，且每个字符都是十六进制字符 → 输出 true 或 false。

调用关系：curated_plugin_cache_version 用它决定是否把版本号截短。

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

fn configured_plugins_from_user_config_value(
    user_config: &toml::Value,
) -> HashMap<String, PluginConfig>

作用：从用户配置内容里解析 plugins 这一段。解析失败时不会让程序崩掉，而是记录警告并当作没有插件配置。

数据流：输入是 TOML 配置值 → 找 plugins 字段并尝试转换成插件配置表 → 成功输出配置表，缺失或失败则输出空表。

调用关系：configured_plugins_from_stack 和 configured_plugins_from_codex_home 都调用它；它是配置文本变成插件配置对象的共同入口。

调用图：被 2 处调用（configured_plugins_from_codex_home, configured_plugins_from_stack）；外部调用 3 个（new, get, warn!）。

fn configured_plugins_from_codex_home(
    codex_home: &Path,
    read_error_message: &str,
    parse_error_message: &str,
) -> HashMap<String, PluginConfig>

作用：直接从 codex_home 下的 config.toml 读取插件配置。它用于不经过完整配置层、只需要本地用户配置的场景。

数据流：输入是 codex_home 和两段错误提示文字 → 读取 config.toml，解析成 TOML，再提取 plugins → 输出插件配置表；文件不存在、读取失败或解析失败时返回空表并可能记警告。

调用关系：精选插件 ID 提取和非精选缓存刷新都会调用它；它把磁盘上的配置文件交给 configured_plugins_from_user_config_value 继续处理。

调用图：调用 1 个内部函数（configured_plugins_from_user_config_value）；被 2 处调用（configured_curated_plugin_ids_from_codex_home, refresh_non_curated_plugin_cache_with_mode）；外部调用 4 个（new, join, read_to_string, warn!）。

fn configured_plugin_ids(
    configured_plugins: HashMap<String, PluginConfig>,
    invalid_plugin_key_message: &str,
) -> Vec<PluginId>

作用：把插件配置表里的字符串键转换成结构化的 PluginId。无效的插件键会被跳过并写警告。

数据流：输入是插件配置表和无效键提示语 → 逐个解析配置键 → 输出成功解析出的 PluginId 列表。

调用关系：curated_plugin_ids_from_config_keys 和 non_curated_plugin_ids_from_config_keys 都用它做基础解析，然后再按市场类型筛选。

调用图：被 2 处调用（curated_plugin_ids_from_config_keys, non_curated_plugin_ids_from_config_keys）。

fn curated_plugin_ids_from_config_keys(
    configured_plugins: HashMap<String, PluginConfig>,
) -> Vec<PluginId>

作用：从配置键里筛出 OpenAI 精选市场插件的 ID，并排好序。这样刷新精选缓存时处理顺序稳定。

数据流：输入是插件配置表 → 先解析成 PluginId → 只保留精选市场的插件 → 按插件键排序后输出列表。

调用关系：configured_curated_plugin_ids_from_codex_home 调用它；它建立在 configured_plugin_ids 的通用解析结果之上。

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

fn non_curated_plugin_ids_from_config_keys(
    configured_plugins: HashMap<String, PluginConfig>,
) -> Vec<PluginId>

作用：从配置键里筛出非精选市场插件的 ID，并排好序。它用于刷新第三方或自定义市场插件缓存。

数据流：输入是插件配置表 → 先解析成 PluginId → 去掉精选市场插件 → 按插件键排序后输出列表。

调用关系：refresh_non_curated_plugin_cache_with_mode 调用它；它和精选筛选函数是同一套解析逻辑的两个分支。

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

fn configured_curated_plugin_ids_from_codex_home(codex_home: &Path) -> Vec<PluginId>

作用：从本地 config.toml 里直接拿到已配置的精选插件 ID。它是刷新精选插件缓存前的准备工具。

数据流：输入是 codex_home → 读取用户配置中的插件表 → 筛选精选市场插件 ID → 输出排序后的 PluginId 列表。

调用关系：它把 configured_plugins_from_codex_home 和 curated_plugin_ids_from_config_keys 串起来，供缓存同步前使用。

调用图：调用 2 个内部函数（configured_plugins_from_codex_home, curated_plugin_ids_from_config_keys）。

async fn load_plugin(
    config_name: String,
    plugin: &PluginConfig,
    store: &PluginStore,
    scope: &PluginLoadScope<'_>,
) -> LoadedPlugin<McpServerConfig>

作用：加载单个插件，把它的各种能力读成一个 LoadedPlugin。它负责处理禁用、未安装、配置损坏、manifest 缺失等常见情况。

数据流：输入是配置名、插件配置、插件仓库和加载范围 → 解析插件 ID，定位安装目录，读取 plugin.json，再按范围加载技能、MCP 服务器、应用和钩子 → 输出 LoadedPlugin，里面可能带错误信息。

调用关系：load_plugins_from_layer_stack_with_scope 逐个插件调用它；它再分派给 load_plugin_skills、load_mcp_servers_from_file、load_plugin_apps、load_plugin_hooks 等专门函数。

调用图：调用 10 个内部函数（apply_plugin_mcp_server_policy, load_mcp_servers_from_file, load_plugin_apps, load_plugin_hooks, load_plugin_skills, plugin_mcp_config_paths, plugin_skill_roots, load_plugin_manifest, plugin_data_root, parse）；被 1 处调用（load_plugins_from_layer_stack_with_scope）；外部调用 4 个（new, new, new, warn!）。

fn apply_plugin_mcp_server_policy(config: &mut McpServerConfig, policy: &PluginMcpServerConfig)

作用：把用户配置里的 MCP 服务器开关和工具审批规则覆盖到插件声明的服务器配置上。简单说，就是让用户的偏好生效。

数据流：输入是可修改的 MCP 服务器配置和用户策略 → 覆盖启用状态、默认审批模式、允许或禁用的工具，以及单个工具的审批设置 → 输出通过原地修改后的配置。

调用关系：load_plugin 在读到插件 MCP 服务器后调用它；它夹在“插件声明的默认配置”和“最终运行配置”之间。

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

fn has_enabled_skills(&self) -> bool

作用：判断插件是否还有可用技能。即使加载技能时出过错，也会认为需要显示“有技能相关内容”，避免把问题悄悄藏掉。

数据流：输入是已解析技能结果自身 → 如果曾有错误直接返回 true，否则检查是否存在未被禁用的技能 → 输出布尔值。

调用关系：load_plugin 在加载技能后用它设置 has_enabled_skills；它帮助上层知道插件是否应该被当成有技能能力。

async fn load_plugin_skills(
    plugin_root: &AbsolutePathBuf,
    plugin_id: &PluginId,
    manifest_paths: &PluginManifestPaths,
    restriction_product: Option<Product>,
    skill_config_rules: &S

作用：读取一个插件里的技能文件，并按当前产品和用户规则过滤。技能可以理解成插件提供给助手的“做事说明书”。

数据流：输入是插件根目录、插件 ID、manifest 路径设置、产品限制和技能配置规则 → 找技能目录，加载技能元数据，过滤不适用于当前产品的技能，再算出被禁用的技能路径 → 输出 ResolvedPluginSkills。

调用关系：load_plugin 和市场插件详情读取流程会调用它；它依赖 plugin_skill_roots 找目录，并把真正读技能的工作交给 load_skills_from_roots。

调用图：调用 3 个内部函数（plugin_skill_roots, resolve_disabled_skill_paths, load_skills_from_roots）；被 2 处调用（load_plugin, read_plugin_detail_for_marketplace_plugin）。

fn plugin_skill_roots(
    plugin_root: &AbsolutePathBuf,
    manifest_paths: &PluginManifestPaths,
) -> Vec<AbsolutePathBuf>

作用：找出一个插件可能存放技能的目录。它会同时考虑默认 skills 文件夹和 manifest 里明确写的路径。

数据流：输入是插件根目录和 manifest 路径配置 → 先找默认 skills 目录，再追加 manifest 指定目录，排序去重 → 输出技能根目录列表。

调用关系：load_plugin、load_plugin_skills 和遥测信息生成都会用它；它底层会调用 default_skill_roots。

调用图：调用 1 个内部函数（default_skill_roots）；被 3 处调用（load_plugin, load_plugin_skills, plugin_telemetry_metadata_from_root）。

fn default_skill_roots(plugin_root: &AbsolutePathBuf) -> Vec<AbsolutePathBuf>

作用：检查插件根目录下有没有默认的 skills 文件夹。有就把它当作技能目录，没有就返回空。

数据流：输入是插件根目录 → 拼出 root/skills 并检查是否为目录 → 输出一个包含该目录的列表或空列表。

调用关系：只被 plugin_skill_roots 调用；它提供“约定俗成的默认位置”。

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

fn plugin_mcp_config_paths(
    plugin_root: &Path,
    manifest_paths: &PluginManifestPaths,
) -> Vec<AbsolutePathBuf>

作用：找出插件的 MCP 配置文件路径。manifest 指定了就用指定路径，否则找默认 .mcp.json。

数据流：输入是插件根目录和 manifest 路径配置 → 如果 manifest 有 mcp_servers 路径就返回它 → 否则调用 default_mcp_config_paths 找默认文件。

调用关系：load_plugin、load_declared_plugin_mcp_servers 和遥测信息生成都会用它；它决定哪些 MCP 配置文件会被读取。

调用图：调用 1 个内部函数（default_mcp_config_paths）；被 3 处调用（load_declared_plugin_mcp_servers, load_plugin, plugin_telemetry_metadata_from_root）；外部调用 1 个（vec!）。

fn default_mcp_config_paths(plugin_root: &Path) -> Vec<AbsolutePathBuf>

作用：查找插件根目录下默认的 .mcp.json 文件。这个文件声明插件提供哪些 MCP 工具服务器。

数据流：输入是插件根目录 → 拼出 .mcp.json，确认它是文件并转成绝对路径 → 排序去重后输出路径列表。

调用关系：plugin_mcp_config_paths 在 manifest 没有显式路径时调用它。

调用图：调用 1 个内部函数（try_from）；被 1 处调用（plugin_mcp_config_paths）；外部调用 2 个（join, new）。

async fn load_plugin_apps(plugin_root: &Path) -> Vec<AppDeclaration>

作用：读取插件声明的应用连接信息。应用声明告诉系统插件和哪些外部应用或连接器有关。

数据流：输入是插件根目录 → 如果能读到 manifest，就按 manifest 或默认路径找应用配置；否则直接找默认 .app.json → 读取并解析后输出 AppDeclaration 列表。

调用关系：load_plugin、load_plugin_mcp_servers 和市场插件详情读取都会调用它；它把文件读取交给 load_apps_from_paths。

调用图：调用 4 个内部函数（default_app_config_paths, load_apps_from_paths, plugin_app_config_paths, load_plugin_manifest）；被 3 处调用（load_plugin, load_plugin_mcp_servers, read_plugin_detail_for_marketplace_plugin）。

fn plugin_app_declarations_from_value(value: &JsonValue) -> Vec<AppDeclaration>

作用：从一段 JSON 值里直接解析应用声明。它适合配置内容已经在内存里、不需要再读文件的场景。

数据流：输入是 JSON 值 → 尝试解析成 PluginAppFile，再转换成 AppDeclaration → 去掉重复 connector_id 后输出应用列表。

调用关系：被根据应用 ID 查询分类的流程调用；它复用 app_declarations_from_file 做实际转换。

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

fn plugin_app_config_paths(
    plugin_root: &Path,
    manifest_paths: &PluginManifestPaths,
) -> Vec<AbsolutePathBuf>

作用：确定插件应用配置文件在哪里。manifest 指定了就用指定文件，否则找默认 .app.json。

数据流：输入是插件根目录和 manifest 路径配置 → 优先返回 manifest 中的 apps 路径 → 没有则调用 default_app_config_paths。

调用关系：load_plugin_apps 和遥测信息生成都会调用它；它决定 load_apps_from_paths 接下来读哪些文件。

调用图：调用 1 个内部函数（default_app_config_paths）；被 2 处调用（load_plugin_apps, plugin_telemetry_metadata_from_root）；外部调用 1 个（vec!）。

fn default_app_config_paths(plugin_root: &Path) -> Vec<AbsolutePathBuf>

作用：查找插件根目录下默认的 .app.json 文件。这个文件保存插件的应用连接声明。

数据流：输入是插件根目录 → 拼出 .app.json，确认存在且是文件后转成绝对路径 → 排序去重后输出路径列表。

调用关系：plugin_app_config_paths 和 load_plugin_apps 在没有 manifest 指定路径时会用它。

调用图：调用 1 个内部函数（try_from）；被 2 处调用（load_plugin_apps, plugin_app_config_paths）；外部调用 2 个（join, new）。

fn load_plugin_hooks(
    plugin_root: &AbsolutePathBuf,
    plugin_id: &PluginId,
    plugin_data_root: &AbsolutePathBuf,
    manifest_paths: &PluginManifestPaths,
) -> (Vec<PluginHookSource>, Vec<St

作用：读取插件自带的钩子配置。钩子可以让插件在特定时机插入动作，比如启动或执行前后。

数据流：输入是插件根目录、插件 ID、插件数据目录和 manifest 路径配置 → 根据 manifest 的 hooks 字段读取文件或内联配置；没有声明时尝试默认 hooks/hooks.json → 输出钩子来源列表和加载警告。

调用关系：load_plugin 和市场插件详情读取会调用它；读取单个钩子文件的工作交给 append_plugin_hook_file。

调用图：调用 3 个内部函数（append_plugin_hook_file, as_path, join）；被 2 处调用（load_plugin, read_plugin_detail_for_marketplace_plugin）；外部调用 5 个（new, find_plugin_manifest_path, format!, clone, clone）。

fn append_plugin_hook_file(
    plugin_root: &AbsolutePathBuf,
    plugin_id: &PluginId,
    plugin_data_root: &AbsolutePathBuf,
    path: &AbsolutePathBuf,
    sources: &mut Vec<PluginHookSource>,

作用：读取并解析一个具体的钩子配置文件，然后把它加入钩子来源列表。读取或解析失败时，它把问题放进警告列表。

数据流：输入是插件路径信息、钩子文件路径、可追加的来源列表和警告列表 → 读 JSON，解析 HooksFile，跳过空钩子 → 成功时追加 PluginHookSource，失败时追加警告。

调用关系：只被 load_plugin_hooks 调用；它负责把“一个文件”变成运行时可报告、可使用的钩子来源。

调用图：调用 1 个内部函数（as_path）；被 1 处调用（load_plugin_hooks）；外部调用 4 个（format!, read_to_string, clone, clone）。

async fn load_apps_from_paths(
    plugin_root: &Path,
    app_config_paths: Vec<AbsolutePathBuf>,
) -> Vec<AppDeclaration>

作用：从一组应用配置文件路径里读取应用声明。坏文件会被跳过，不会阻止其他文件继续加载。

数据流：输入是插件根目录和应用配置路径列表 → 逐个异步读取文件，解析 JSON，再转换为应用声明 → 输出合并后的 AppDeclaration 列表。

调用关系：load_plugin_apps 和遥测信息生成会调用它；它把每个解析成功的文件交给 app_declarations_from_file 转换。

调用图：调用 1 个内部函数（app_declarations_from_file）；被 2 处调用（load_plugin_apps, plugin_telemetry_metadata_from_root）；外部调用 3 个（new, read_to_string, warn!）。

fn app_declarations_from_file(
    parsed: PluginAppFile,
    plugin_root: Option<&Path>,
) -> Vec<AppDeclaration>

作用：把已经解析好的应用配置变成程序统一使用的应用声明。它会丢掉缺少应用 ID 的条目。

数据流：输入是 PluginAppFile 和可选插件根目录 → 遍历 apps，把非空 id 转成 AppConnectorId，并清理分类字段 → 输出 AppDeclaration 列表；缺 id 时可能写警告。

调用关系：load_apps_from_paths 和 plugin_app_declarations_from_value 都调用它；它是应用配置格式到内部模型的转换点。

调用图：被 2 处调用（load_apps_from_paths, plugin_app_declarations_from_value）。

fn cleaned_app_category(category: Option<String>) -> Option<String>

作用：清理应用分类字符串，去掉前后空白，并把空字符串当成没有分类。这样后续看到的是干净数据。

数据流：输入是可选分类字符串 → 如果存在就 trim，若结果为空则丢弃 → 输出清理后的可选字符串。

调用关系：app_declarations_from_file 在生成每个应用声明时使用它。

async fn plugin_telemetry_metadata_from_root(
    plugin_id: &PluginId,
    plugin_root: &AbsolutePathBuf,
) -> PluginTelemetryMetadata

作用：从插件目录生成遥测元数据，也就是用于统计和事件上报的插件能力摘要。它尽量只收集名称、能力概况等信息。

数据流：输入是插件 ID 和插件根目录 → 读取 manifest，检查是否有技能，读取 MCP 服务器名和应用连接器 ID → 输出 PluginTelemetryMetadata；manifest 缺失时退回只含插件 ID 的信息。

调用关系：安装插件和查询已安装插件遥测信息时调用它；它复用技能路径、MCP 配置路径和应用配置路径等加载辅助函数。

调用图：调用 9 个内部函数（load_apps_from_paths, load_mcp_servers_from_file, plugin_app_config_paths, plugin_mcp_config_paths, plugin_skill_roots, load_plugin_manifest, from_plugin_id, as_key, as_path）；被 2 处调用（installed_plugin_telemetry_metadata, install_resolved_plugin）；外部调用 3 个（new, app_connector_ids_from_declarations, clone）。

async fn load_plugin_mcp_servers(
    plugin_root: &Path,
    auth_mode: Option<AuthMode>,
) -> HashMap<String, McpServerConfig>

作用：读取插件声明的 MCP 服务器，并根据登录/授权模式决定是否应用应用路由策略。路由策略会影响某些应用相关工具如何暴露。

数据流：输入是插件根目录和可选授权模式 → 先读取声明的 MCP 服务器；如果应用路由可用且有服务器，再加载应用声明并调整服务器配置 → 输出 MCP 服务器配置表。

调用关系：市场插件详情读取会调用它；它先用 load_declared_plugin_mcp_servers 读原始声明，再视情况交给 apply_app_mcp_routing_policy。

调用图：调用 4 个内部函数（apply_app_mcp_routing_policy, apps_route_available, load_declared_plugin_mcp_servers, load_plugin_apps）；被 1 处调用（read_plugin_detail_for_marketplace_plugin）。

async fn load_declared_plugin_mcp_servers(plugin_root: &Path) -> HashMap<String, McpServerConfig>

作用：只读取插件自己声明的 MCP 服务器，不应用运行时路由策略。它提供一份原始服务器清单。

数据流：输入是插件根目录 → 读取 manifest，找 MCP 配置路径，逐个解析服务器配置 → 输出名称到 McpServerConfig 的映射，重复名称保留先看到的。

调用关系：load_plugin_mcp_servers 调用它作为第一步；它依赖 load_mcp_servers_from_file 解析具体文件。

调用图：调用 3 个内部函数（load_mcp_servers_from_file, plugin_mcp_config_paths, load_plugin_manifest）；被 1 处调用（load_plugin_mcp_servers）；外部调用 1 个（new）。

async fn installed_plugin_telemetry_metadata(
    codex_home: &Path,
    plugin_id: &PluginId,
) -> PluginTelemetryMetadata

作用：为一个已安装插件生成遥测信息。它会先从本地插件仓库找到当前活跃安装目录。

数据流：输入是 codex_home 和插件 ID → 打开插件仓库，定位活跃插件目录 → 找到则调用 plugin_telemetry_metadata_from_root，失败或未安装则返回只含插件 ID 的默认信息。

调用关系：插件启停事件和卸载流程会调用它；它把“插件 ID”转换成“插件目录上的能力摘要”。

调用图：调用 3 个内部函数（plugin_telemetry_metadata_from_root, try_new, from_plugin_id）；被 2 处调用（emit_plugin_toggle_events, uninstall_plugin_id）；外部调用 2 个（to_path_buf, warn!）。

async fn load_mcp_servers_from_file(
    plugin_root: &Path,
    mcp_config_path: &AbsolutePathBuf,
) -> PluginMcpDiscovery

作用：读取并解析一个 MCP 配置文件，得到插件声明的工具服务器列表。解析失败时返回空结果并写警告。

数据流：输入是插件根目录和 MCP 配置文件路径 → 异步读取文件内容，调用 MCP 配置解析器，记录每个服务器解析错误 → 输出 PluginMcpDiscovery。

调用关系：load_plugin、load_declared_plugin_mcp_servers 和遥测信息生成都会用它；它是 MCP 配置文件进入系统的实际入口。

调用图：调用 1 个内部函数（as_path）；被 3 处调用（load_declared_plugin_mcp_servers, load_plugin, plugin_telemetry_metadata_from_root）；外部调用 4 个（parse_plugin_mcp_config, default, read_to_string, warn!）。

fn materialize_marketplace_plugin_source(
    codex_home: &Path,
    source: &MarketplacePluginSource,
) -> Result<MaterializedMarketplacePluginSource, String>

作用：把市场里的插件来源变成本地可读取的目录。本地来源直接使用；Git 来源会先克隆到临时目录。

数据流：输入是 codex_home 和市场插件来源 → 如果是本地路径，直接包装返回；如果是 Git，创建暂存临时目录，克隆仓库并可选进入子路径 → 输出 MaterializedMarketplacePluginSource，临时目录会随对象保留。

调用关系：非精选插件缓存刷新时调用它；Git 克隆的细节交给 clone_git_plugin_source。

调用图：调用 2 个内部函数（clone_git_plugin_source, try_from）；被 1 处调用（refresh_non_curated_plugin_cache_with_mode）；外部调用 3 个（join, create_dir_all, new）。

fn clone_git_plugin_source(
    url: &str,
    ref_name: Option<&str>,
    sha: Option<&str>,
    sparse_checkout_path: Option<&str>,
    destination: &Path,
) -> Result<(), String>

作用：把 Git 仓库里的插件源码克隆到指定目录。它支持稀疏检出，也就是只拿仓库里的某个子目录。

数据流：输入是 Git 地址、可选分支或引用、可选提交号、可选子路径和目标目录 → 组合 git clone、sparse-checkout、checkout 命令 → 成功返回空结果，失败返回错误字符串。

调用关系：materialize_marketplace_plugin_source 在处理 Git 来源时调用它；实际执行外部命令的工作交给 run_git。

调用图：调用 1 个内部函数（run_git）；被 1 处调用（materialize_marketplace_plugin_source）；外部调用 1 个（to_string_lossy）。

fn run_git(args: &[&str], cwd: Option<&Path>) -> Result<(), String>

作用：执行一条 git 命令，并把失败时的状态、标准输出和错误输出整理成可读错误。它还关闭终端交互提示，避免后台流程卡住等用户输入。

数据流：输入是 git 参数和可选工作目录 → 启动 git 进程，设置 GIT_TERMINAL_PROMPT=0，等待输出 → 成功返回 Ok，失败返回包含命令输出的错误文本。

调用关系：clone_git_plugin_source 用它执行 clone、sparse-checkout 和 checkout；它是这个文件里和外部 git 程序打交道的最底层函数。

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

fn new(
        config_layer_stack: ConfigLayerStack,
        plugins_enabled: bool,
        remote_plugin_enabled: bool,
        chatgpt_base_url: String,
    ) -> Self

作用：创建一份插件运行所需的配置输入，里面包括配置层、插件总开关、远程插件开关和服务地址。

数据流：进去的是配置层栈、两个开关和 ChatGPT 服务地址；函数把它们原样装进一个 PluginsConfigInput；出来的是后续所有插件管理流程都能使用的配置包。

调用关系：它通常由配置加载流程调用，用来把零散设置整理成插件管家能看懂的一份输入。

调用图：被 2 处调用（load_plugins_config, plugins_config_input）。

fn remote_plugin_service_config(config: &PluginsConfigInput) -> RemotePluginServiceConfig

作用：把插件配置里和远程服务有关的部分抽出来，做成远程插件 API 能用的小配置。

数据流：进去的是完整 PluginsConfigInput；它取出 chatgpt_base_url；出来的是 RemotePluginServiceConfig，供远程安装状态、推荐插件、精选插件等请求使用。

调用关系：很多远程相关函数都会先调用它，相当于每次联系服务器前先写好收件地址。

调用图：被 9 处调用（build_and_cache_remote_installed_plugin_marketplaces, cached_global_remote_discoverable_plugins_for_config, featured_plugin_ids_for_config, install_plugin_with_remote_sync, maybe_start_global_remote_catalog_cache_refresh, maybe_start_plugin_startup_tasks_for_config, maybe_start_remote_installed_plugin_bundle_sync, maybe_start_remote_installed_plugins_cache_refresh_with_notify, uninstall_plugin_with_remote_sync）。

fn featured_plugin_ids_cache_key(
    config: &PluginsConfigInput,
    auth: Option<&CodexAuth>,
) -> FeaturedPluginIdsCacheKey

作用：生成“精选插件列表”的缓存钥匙，确保不同账号或不同服务地址不会误用同一份缓存。

数据流：进去的是插件配置和可选登录信息；它取出服务地址、账号 ID、用户 ID、是否工作区账号；出来的是一个用于查缓存的键。

调用关系：featured_plugin_ids_for_config 会用它先查缓存，缓存不命中才去远程拉取。

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

fn recommended_plugins_cache_key(config: &PluginsConfigInput) -> RecommendedPluginsCacheKey

作用：生成“推荐插件模式”的缓存钥匙，目前主要按服务地址区分。

数据流：进去的是插件配置；它取出 chatgpt_base_url；出来的是推荐插件缓存用的键。

调用关系：recommended_plugins_mode_for_config 用它避免同一个服务地址重复请求推荐插件信息。

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

fn from(value: PluginDetail) -> Self

作用：把详细插件信息压缩成一份能力摘要，方便给提示词或上层界面使用。

数据流：进去的是 PluginDetail；它检查是否还有未禁用的技能，清理描述文本，并带上 MCP 服务名和应用连接器 ID；出来的是 PluginCapabilitySummary。

调用关系：它是类型转换入口，会调用 prompt_safe_plugin_description 把描述变成更安全、适合放进提示里的文字。

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

fn new(codex_home: PathBuf) -> Self

作用：用默认限制创建插件管家，适合大多数 Codex 场景直接使用。

数据流：进去的是 codex_home 路径；它交给 new_with_options，并默认指定产品限制；出来的是初始化好的 PluginsManager。

调用关系：很多命令行和运行流程都会从这里拿到插件管家，再去列插件、安装插件或加载插件。

调用图：被 84 处调用（detect_migrations, import_plugins, run_list, run_upgrade, run_get, run_list, run_login, run_logout, load_plugin_command_context, deduplicates_configured_marketplace_plugin (+15 more)）；外部调用 1 个（new_with_options）。

fn new_with_options(
        codex_home: PathBuf,
        restriction_product: Option<Product>,
        auth_mode: Option<AuthMode>,
    ) -> Self

作用：创建可定制的插件管家，可以指定产品限制和当前登录模式。

数据流：进去的是主目录、可选产品限制、可选认证模式；它建立插件存储、各种缓存、后台刷新状态、锁和信号量；出来的是完整的 PluginsManager。

调用关系：new 会调用它；测试和特殊运行场景也会直接用它来控制认证模式或产品限制。

调用图：调用 1 个内部函数（new）；被 14 处调用（featured_plugin_ids_for_config_defaults_query_param_to_codex, featured_plugin_ids_for_config_uses_restriction_product_query_param, load_plugins_from_config, plugin_auth_projection_hides_apps_without_chatgpt_auth, plugin_auth_projection_hides_dual_surface_mcp_with_agent_identity_apps_route, plugin_auth_projection_hides_matching_mcp_with_chatgpt_apps_route, plugin_auth_projection_keeps_non_conflicting_mcp_with_chatgpt_apps_route, plugin_auth_projection_preserves_duplicate_connector_declaration_names, plugin_auth_projection_reprojects_cached_plugins_when_auth_changes, plugins_manager_tracks_auth_mode (+4 more)）；外部调用 9 个（new, clone, new, new, default, default, default, default, default）。

fn set_auth_mode(&self, auth_mode: Option<AuthMode>) -> bool

作用：更新当前登录/认证模式，并告诉调用者这个值有没有真的变。

数据流：进去的是新的 AuthMode；它拿写锁比较旧值和新值，不同就替换；出来的是布尔值，true 表示发生变化。

调用关系：认证模式会影响应用和 MCP 能力的展示，所以更新后上层可以决定是否刷新插件能力。

fn auth_mode(&self) -> Option<AuthMode>

作用：读取当前认证模式。

数据流：进去不需要业务参数；它从读写锁里取出 AuthMode；出来的是可选认证模式。

调用关系：加载插件能力和读取插件详情时会调用它，用来决定哪些应用或 MCP 服务应该露出来。

调用图：被 2 处调用（read_plugin_detail_for_marketplace_plugin, resolve_loaded_plugins_for_auth）。

fn set_analytics_events_client(&self, analytics_events_client: AnalyticsEventsClient)

作用：设置 analytics 事件客户端，也就是用来记录安装、卸载等统计事件的对象。

数据流：进去的是 AnalyticsEventsClient；它写入管理器内部；出来没有返回值，但之后安装卸载插件时会发送统计事件。

调用关系：安装和卸载内部流程会读取这个客户端，存在时就上报插件事件。

fn restriction_product_matches(&self, products: Option<&[Product]>) -> bool

作用：判断某个插件声明的产品限制是否允许当前产品使用。

数据流：进去的是插件允许的产品列表；没有限制就允许，空列表就拒绝，有列表则和管理器当前产品比较；出来是能不能使用的布尔值。

调用关系：列插件、读插件详情时会用它过滤不该出现在当前产品里的插件。

调用图：被 2 处调用（read_plugin_detail_for_marketplace_plugin, read_plugin_for_config）。

async fn plugins_for_config(&self, config: &PluginsConfigInput) -> PluginLoadOutcome

作用：按当前配置加载可用插件，是外部最常用的插件加载入口。

数据流：进去的是 PluginsConfigInput；它默认不强制刷新，转交给 plugins_for_config_with_force_reload；出来的是 PluginLoadOutcome，里面是可生效的插件能力。

调用关系：构建 MCP 配置和钩子配置时会调用它，是运行时拿插件能力的主门。

调用图：调用 1 个内部函数（plugins_for_config_with_force_reload）；被 2 处调用（to_mcp_config_with_plugin_registrations, build_hooks_for_config）。

async fn plugins_for_config_with_force_reload(
        &self,
        config: &PluginsConfigInput,
        force_reload: bool,
    ) -> PluginLoadOutcome

作用：真正执行插件加载，并支持绕过缓存强制重载。

数据流：进去的是配置和 force_reload；它先看插件开关，再用配置、技能规则、远程开关组成缓存键，能命中就直接返回；否则排队加载插件、记录错误、写缓存，再按认证模式整理能力；出来是 PluginLoadOutcome。

调用关系：plugins_for_config 调用它；它把实际加载交给 load_plugins_from_layer_stack，并用缓存相关小函数保护性能和一致性。

调用图：调用 10 个内部函数（load_plugins_from_layer_stack, log_plugin_load_errors, cache_loaded_plugins_if_current, cached_loaded_plugins, loaded_plugins_cache_generation, remote_installed_plugin_configs, resolve_loaded_plugins_for_auth, configured_plugins_from_stack, skill_config_rules_from_stack, default）；被 1 处调用（plugins_for_config）；外部调用 2 个（acquire, warn!）。

fn resolve_loaded_plugins_for_auth(&self, mut plugins: Vec<LoadedPlugin>) -> PluginLoadOutcome

作用：根据当前认证模式调整已加载插件的应用和 MCP 服务。

数据流：进去的是一组 LoadedPlugin；它读取 auth_mode，对每个插件应用路由策略，可能隐藏或保留某些能力；出来的是 PluginLoadOutcome。

调用关系：插件从缓存取出或刚加载完成后都会经过它，确保同一份插件在不同登录状态下表现正确。

调用图：调用 3 个内部函数（apply_app_mcp_routing_policy, auth_mode, from_plugins）；被 2 处调用（plugins_for_config_with_force_reload, plugins_for_layer_stack）。

fn clear_cache(&self)

作用：清掉插件加载缓存和精选插件缓存，让下次重新计算。

数据流：进去无业务参数；它先清 loaded plugins 缓存，再把 featured ids 缓存置空；出来没有返回值，但内部缓存变干净。

调用关系：市场升级、非官方缓存刷新等发现本地内容变了时会调用它。

调用图：调用 1 个内部函数（clear_loaded_plugins_cache）；被 2 处调用（run_non_curated_plugin_cache_refresh_loop, upgrade_configured_marketplaces_for_config）。

fn clear_recommended_plugins_cache(&self)

作用：清掉推荐插件相关缓存和正在进行的刷新记录。

数据流：进去无业务参数；它清空推荐模式缓存，也清空 OnceCell 刷新占位；出来没有返回值。

调用关系：当上层知道推荐插件信息不能再信时，可以调用它让下次重新请求。

fn clear_loaded_plugins_cache(&self)

作用：只清掉已加载插件缓存，并把代数加一，防止旧加载结果回写覆盖新状态。

数据流：进去无业务参数；它拿写锁，把 generation 加一并删除缓存条目；出来没有返回值。

调用关系：远程安装状态变化、本地缓存变化、clear_cache 都会调用它。

调用图：被 3 处调用（clear_cache, clear_remote_installed_plugins_cache, write_remote_installed_plugins_cache）。

async fn plugins_for_layer_stack(
        &self,
        config_layer_stack: &ConfigLayerStack,
        config: &PluginsConfigInput,
    ) -> PluginLoadOutcome

作用：按指定配置层加载插件，但不使用也不改动主缓存。

数据流：进去的是配置层栈和配置输入；插件关闭就返回空结果，否则直接加载插件，再按认证模式调整；出来是 PluginLoadOutcome。

调用关系：effective_skill_roots_for_layer_stack 调用它，适合临时查看某套配置下的插件能力。

调用图：调用 4 个内部函数（load_plugins_from_layer_stack, remote_installed_plugin_configs, resolve_loaded_plugins_for_auth, default）；被 1 处调用（effective_skill_roots_for_layer_stack）。

async fn plugin_hooks_for_layer_stack(
        &self,
        config_layer_stack: &ConfigLayerStack,
        config: &PluginsConfigInput,
    ) -> PluginHookLoadOutcome

作用：只加载插件钩子，不加载技能、应用等其他能力。

数据流：进去的是配置层栈和配置输入；插件关闭则返回空钩子结果，否则读取远程安装配置并加载钩子；出来是 PluginHookLoadOutcome。

调用关系：它把工作交给 load_plugin_hooks_from_layer_stack，用于只关心事件钩子的场景。

调用图：调用 2 个内部函数（load_plugin_hooks_from_layer_stack, remote_installed_plugin_configs）；外部调用 1 个（default）。

async fn effective_skill_roots_for_layer_stack(
        &self,
        config_layer_stack: &ConfigLayerStack,
        config: &PluginsConfigInput,
    ) -> Vec<PluginSkillRoot>

作用：拿到某套配置下真正生效的插件技能目录。

数据流：进去的是配置层栈和配置输入；它先临时加载插件，再从加载结果里提取有效技能根目录；出来是 PluginSkillRoot 列表。

调用关系：它建立在 plugins_for_layer_stack 之上，专门服务需要技能路径的调用者。

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

fn cached_loaded_plugins(&self, key: &PluginLoadCacheKey) -> Option<Vec<LoadedPlugin>>

作用：尝试从已加载插件缓存里取结果。

数据流：进去的是缓存键；它读缓存，如果键完全一致就克隆插件列表返回，否则返回空；不改动状态。

调用关系：plugins_for_config_with_force_reload 在加载前后都会查它，减少重复加载。

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

fn loaded_plugins_cache_generation(&self) -> u64

作用：读取当前加载缓存的代数，用来判断后面能不能安全写回缓存。

数据流：进去无业务参数；它读锁里取 generation；出来是一个数字。

调用关系：plugins_for_config_with_force_reload 在开始慢加载前记下它，加载完交给 cache_loaded_plugins_if_current 判断缓存是否已被别人清过。

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

fn cache_loaded_plugins_if_current(
        &self,
        generation: u64,
        key: PluginLoadCacheKey,
        plugins: Vec<LoadedPlugin>,
    )

作用：只有缓存代数没变时，才把新加载的插件写入缓存。

数据流：进去的是旧代数、缓存键和插件列表；它拿写锁确认 generation 仍相同，相同就保存，不同就丢弃；出来没有返回值。

调用关系：plugins_for_config_with_force_reload 用它避免后台刷新期间旧结果覆盖新状态。

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

fn remote_installed_plugin_configs(&self) -> HashMap<String, PluginConfig>

作用：把远程账号安装的插件缓存转换成本地加载器能读懂的插件配置。

数据流：进去无业务参数；它读取 remote_installed_plugins_cache，没有缓存就返回空表，有缓存就调用 remote_installed_plugins_to_config；出来是插件配置映射。

调用关系：加载插件和钩子时会把它作为额外配置，让远程安装状态也能参与本地能力加载。

调用图：调用 1 个内部函数（remote_installed_plugins_to_config）；被 3 处调用（plugin_hooks_for_layer_stack, plugins_for_config_with_force_reload, plugins_for_layer_stack）；外部调用 1 个（new）。

fn build_remote_installed_plugin_marketplaces_from_cache(
        &self,
        visible_marketplaces: &[&str],
    ) -> Option<Vec<crate::remote::RemoteMarketplace>>

作用：把缓存里的远程已安装插件按市场分组，做成界面可展示的市场列表。

数据流：进去的是可见市场名列表；它读取远程安装缓存，没有缓存返回 None，有缓存就按市场分组；出来是远程市场列表。

调用关系：它不联网，只复用已有缓存，适合快速展示远程安装状态。

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

fn cached_global_remote_discoverable_plugins_for_config(
        &self,
        config: &PluginsConfigInput,
        auth: Option<&CodexAuth>,
    ) -> Vec<crate::remote::RemoteDiscoverablePlugin>

作用：读取已经缓存的全球远程可发现插件列表。

数据流：进去的是配置和登录信息；它先检查插件、远程插件、后端登录、账号 ID 是否满足；满足后从本地远程目录缓存读数据；出来是插件列表，条件不满足则为空。

调用关系：它依赖 remote_plugin_service_config，并调用 remote 模块的缓存读取函数，不主动刷新网络数据。

调用图：调用 2 个内部函数（remote_plugin_service_config, cached_global_remote_discoverable_plugins）；外部调用 2 个（as_path, new）。

async fn build_and_cache_remote_installed_plugin_marketplaces(
        &self,
        config: &PluginsConfigInput,
        auth: Option<&CodexAuth>,
        visible_marketplaces: &[&str],
        on_e

作用：联网获取远程已安装插件，写入缓存，并返回按市场整理后的结果。

数据流：进去的是配置、登录信息、可见市场和变化回调；它请求远程安装列表，分组成市场，写入本地缓存；如果缓存变了就触发回调；出来是市场列表或错误。

调用关系：它用于需要立即拿到最新远程安装状态的路径，内部会调用 write_remote_installed_plugins_cache。

调用图：调用 4 个内部函数（write_remote_installed_plugins_cache, remote_plugin_service_config, fetch_remote_installed_plugins, group_remote_installed_plugins_by_marketplaces）。

fn write_remote_installed_plugins_cache(&self, plugins: Vec<RemoteInstalledPlugin>) -> bool

作用：更新远程已安装插件缓存，并在内容变化时让已加载插件缓存失效。

数据流：进去的是远程插件列表；如果和旧缓存一样就返回 false，否则写入新列表、清掉 loaded plugins 缓存；出来是是否发生变化。

调用关系：远程安装刷新循环和手动构建远程市场都会调用它。

调用图：调用 1 个内部函数（clear_loaded_plugins_cache）；被 2 处调用（build_and_cache_remote_installed_plugin_marketplaces, run_remote_installed_plugins_cache_refresh_loop）。

fn clear_remote_installed_plugins_cache(&self) -> bool

作用：清空远程已安装插件缓存，并让插件加载结果重新计算。

数据流：进去无业务参数；缓存本来为空就返回 false，否则置空并清 loaded plugins 缓存；出来是是否真的清掉了东西。

调用关系：远程刷新遇到未登录或认证不支持时会调用它。

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

fn maybe_start_remote_plugin_caches_refresh(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth: Option<CodexAuth>,
        on_effective_plugins_changed: Option<Arc<dyn Fn() +

作用：在后台启动远程插件相关缓存刷新，但只在需要时排任务。

数据流：进去的是配置、登录信息和变化回调；它安排远程已安装插件刷新，并异步刷新推荐插件模式；立刻返回，不等待网络完成。

调用关系：插件列表后台任务会调用它；它进一步调用 maybe_start_remote_installed_plugins_cache_refresh_with_notify。

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

fn maybe_start_remote_installed_plugins_cache_refresh_after_mutation(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth: Option<CodexAuth>,
        on_effective_plugins_chang

作用：远程插件安装或卸载后，安排一次更严格的已安装缓存刷新。

数据流：进去的是配置、登录信息和回调；它要求刷新成功后通知，即使安装集合看起来没变也通知；出来没有同步结果。

调用关系：远程 bundle 同步或远程变更后使用它，确保 MCP 刷新顺序在远程安装缓存之后。

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

fn maybe_start_remote_installed_plugins_cache_refresh_with_notify(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth: Option<CodexAuth>,
        notify: RemoteInstalledPlugin

作用：统一安排远程已安装插件缓存刷新，并决定刷新后何时通知。

数据流：进去的是配置、登录信息、通知策略和回调；插件关闭就不做事，否则组装刷新请求并提交调度；出来没有返回值。

调用关系：普通远程缓存刷新和变更后刷新都会走它，再交给 schedule_remote_installed_plugins_cache_refresh。

调用图：调用 2 个内部函数（schedule_remote_installed_plugins_cache_refresh, remote_plugin_service_config）；被 2 处调用（maybe_start_remote_installed_plugins_cache_refresh_after_mutation, maybe_start_remote_plugin_caches_refresh）。

fn maybe_start_remote_installed_plugin_bundle_sync(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth: Option<CodexAuth>,
        on_effective_plugins_changed: Option<Arc<dyn

作用：启动远程已安装插件本地包的同步，让远程插件在本机也有可加载的文件。

数据流：进去的是配置、登录信息和变化回调；插件关闭就退出，否则注册本地缓存变化后的回调，并调用 remote 模块启动同步；出来没有立即结果。

调用关系：插件列表后台任务和启动任务会调用它；本地包变动后会反过来触发远程安装缓存刷新。

调用图：调用 1 个内部函数（remote_plugin_service_config）；被 1 处调用（maybe_start_plugin_list_background_tasks_for_config）；外部调用 5 个（clone, new, clone, clone, maybe_start_remote_installed_plugin_bundle_sync）。

fn maybe_start_global_remote_catalog_cache_refresh(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth: Option<CodexAuth>,
    )

作用：在后台刷新全球远程插件目录缓存。

数据流：进去的是配置和登录信息；只有插件与远程插件都开启才组装请求并提交；出来没有同步结果。

调用关系：插件列表后台任务可按选项调用它，然后由调度器启动刷新循环。

调用图：调用 2 个内部函数（schedule_global_remote_catalog_cache_refresh, remote_plugin_service_config）；被 1 处调用（maybe_start_plugin_list_background_tasks_for_config）。

fn maybe_start_plugin_list_background_tasks_for_config(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth: Option<CodexAuth>,
        roots: &[AbsolutePathBuf],
        optio

作用：列插件时顺手启动一批后台维护任务，让列表和缓存逐步变新。

数据流：进去的是配置、登录信息、市场根目录、选项和回调；它依次安排非官方缓存刷新、可选远程目录刷新、远程安装缓存刷新和远程包同步；出来立即返回。

调用关系：这是插件列表流程的后台管家，负责把多个刷新任务串起来。

调用图：调用 4 个内部函数（maybe_start_global_remote_catalog_cache_refresh, maybe_start_non_curated_plugin_cache_refresh, maybe_start_remote_installed_plugin_bundle_sync, maybe_start_remote_plugin_caches_refresh）。

fn cached_featured_plugin_ids(
        &self,
        cache_key: &FeaturedPluginIdsCacheKey,
    ) -> Option<Vec<String>>

作用：读取精选插件 ID 缓存，并自动丢掉过期或账号不匹配的缓存。

数据流：进去的是缓存键；它先读缓存，看是否没过期且键一致，命中就返回列表；不命中时会清掉无效缓存并返回 None。

调用关系：featured_plugin_ids_for_config 先调用它，避免频繁访问远程接口。

调用图：被 1 处调用（featured_plugin_ids_for_config）；外部调用 1 个（now）。

fn write_featured_plugin_ids_cache(
        &self,
        cache_key: FeaturedPluginIdsCacheKey,
        featured_plugin_ids: &[String],
    )

作用：写入精选插件 ID 缓存，并设置过期时间。

数据流：进去的是缓存键和 ID 列表；它记录当前时间加上固定有效期，并保存列表副本；出来没有返回值。

调用关系：featured_plugin_ids_for_config 从远程成功拉取后会调用它。

调用图：被 1 处调用（featured_plugin_ids_for_config）；外部调用 1 个（now）。

async fn featured_plugin_ids_for_config(
        &self,
        config: &PluginsConfigInput,
        auth: Option<&CodexAuth>,
    ) -> Result<Vec<String>, RemotePluginFetchError>

作用：获取当前配置和账号下的精选插件 ID 列表。

数据流：进去的是配置和登录信息；插件关闭返回空列表，缓存命中返回缓存，否则请求远程服务并写缓存；出来是 ID 列表或远程错误。

调用关系：启动预热任务和界面展示精选插件时会用它。

调用图：调用 5 个内部函数（cached_featured_plugin_ids, write_featured_plugin_ids_cache, featured_plugin_ids_cache_key, remote_plugin_service_config, fetch_remote_featured_plugin_ids）；外部调用 1 个（new）。

async fn recommended_plugins_mode_for_config(
        &self,
        config: &PluginsConfigInput,
        auth: Option<&CodexAuth>,
    ) -> RecommendedPluginsMode

作用：判断推荐插件功能该用新远程模式还是旧模式。

数据流：进去的是配置和登录信息；如果条件不满足直接返回 Legacy；否则查缓存，没缓存就用 OnceCell 合并并发请求，联网获取并写缓存，失败也回退 Legacy；出来是 RecommendedPluginsMode。

调用关系：远程缓存刷新会后台调用它；它用 cached_recommended_plugins_mode 和 recommended_plugins_cache_key 管住重复请求。

调用图：调用 2 个内部函数（cached_recommended_plugins_mode, recommended_plugins_cache_key）。

fn cached_recommended_plugins_mode(
        &self,
        cache_key: &RecommendedPluginsCacheKey,
    ) -> Option<RecommendedPluginsMode>

作用：从内存缓存读取推荐插件模式。

数据流：进去的是推荐插件缓存键；它读哈希表并克隆命中的模式；出来是可选 RecommendedPluginsMode。

调用关系：recommended_plugins_mode_for_config 在发起网络请求前后都会检查它。

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

async fn install_plugin(
        &self,
        request: PluginInstallRequest,
    ) -> Result<PluginInstallOutcome, PluginInstallError>

作用：安装一个市场里的插件，只做本地安装流程。

数据流：进去的是插件名和市场路径；它先在市场里找到可安装插件，再交给 install_resolved_plugin；出来是安装结果或错误。

调用关系：它把查找交给 find_installable_marketplace_plugin，把真正复制和配置修改交给 install_resolved_plugin。

调用图：调用 2 个内部函数（install_resolved_plugin, find_installable_marketplace_plugin）。

async fn install_plugin_with_remote_sync(
        &self,
        config: &PluginsConfigInput,
        auth: Option<&CodexAuth>,
        request: PluginInstallRequest,
    ) -> Result<PluginInstallOutc

作用：安装插件前先通知远程后端启用该插件，然后再做本地安装。

数据流：进去的是配置、登录信息和安装请求；它解析市场插件，调用远程启用接口，成功后执行本地安装；出来是安装结果或错误。

调用关系：这是旧版远程同步安装路径，先调用 enable_remote_plugin，再复用 install_resolved_plugin。

调用图：调用 4 个内部函数（install_resolved_plugin, remote_plugin_service_config, find_installable_marketplace_plugin, enable_remote_plugin）。

async fn install_resolved_plugin(
        &self,
        resolved: ResolvedMarketplacePlugin,
    ) -> Result<PluginInstallOutcome, PluginInstallError>

作用：执行已经解析好的插件安装：准备源文件、写入插件存储、打开用户配置，并记录统计。

数据流：进去的是 ResolvedMarketplacePlugin；它判断官方精选插件版本，在线程池中物化源代码并安装到 store，然后把用户配置设为启用，最后可选上报安装事件；出来是插件 ID、版本、安装路径和认证策略。

调用关系：install_plugin 和 install_plugin_with_remote_sync 都会调用它，它是安装流程的核心落地点。

调用图：调用 3 个内部函数（curated_plugin_cache_version, plugin_telemetry_metadata_from_root, read_curated_plugins_sha）；被 2 处调用（install_plugin, install_plugin_with_remote_sync）；外部调用 6 个（as_path, clone, set_user_plugin_enabled, clone, is_openai_curated_marketplace_name, spawn_blocking）。

async fn uninstall_plugin(&self, plugin_id: String) -> Result<(), PluginUninstallError>

作用：按字符串形式的插件 ID 卸载插件，只做本地卸载。

数据流：进去的是 plugin_id 字符串；它先解析成 PluginId，再交给 uninstall_plugin_id；出来是成功或卸载错误。

调用关系：它是本地卸载的外部入口，把实际工作交给 uninstall_plugin_id。

调用图：调用 2 个内部函数（uninstall_plugin_id, parse）。

async fn uninstall_plugin_with_remote_sync(
        &self,
        config: &PluginsConfigInput,
        auth: Option<&CodexAuth>,
        plugin_id: String,
    ) -> Result<(), PluginUninstallError>

作用：卸载插件前先通知远程后端，再清理本地。

数据流：进去的是配置、登录信息和插件 ID 字符串；它解析 ID，调用远程卸载接口，成功后执行本地卸载；出来是成功或错误。

调用关系：这是旧版远程同步卸载路径，先调用 uninstall_remote_plugin，再复用 uninstall_plugin_id。

调用图：调用 4 个内部函数（uninstall_plugin_id, remote_plugin_service_config, uninstall_remote_plugin, parse）。

async fn uninstall_plugin_id(&self, plugin_id: PluginId) -> Result<(), PluginUninstallError>

作用：真正执行本地插件卸载，并清理用户配置和统计记录。

数据流：进去的是 PluginId；它先准备卸载统计信息，在线程池里从 store 删除插件，再从用户配置清掉插件项，最后可选上报卸载事件；出来是成功或错误。

调用关系：uninstall_plugin 和 uninstall_plugin_with_remote_sync 都调用它。

调用图：调用 3 个内部函数（installed_plugin_telemetry_metadata, active_plugin_root, as_key）；被 2 处调用（uninstall_plugin, uninstall_plugin_with_remote_sync）；外部调用 5 个（as_path, clear_user_plugin, clone, clone, spawn_blocking）。

fn list_marketplaces_for_config(
        &self,
        config: &PluginsConfigInput,
        additional_roots: &[AbsolutePathBuf],
        include_openai_curated: bool,
    ) -> Result<ConfiguredMarke

作用：列出当前配置下可见的插件市场和插件，并标出哪些已安装、哪些已启用。

数据流：进去的是配置、额外市场根目录和是否包含官方精选市场；插件关闭返回空结果，否则收集配置状态和市场路径，读取市场文件，过滤重复插件和产品不匹配插件，补充版本与启用信息；出来是市场列表和读取错误列表。

调用关系：安装验证、查找插件市场、界面列市场等流程会调用它。

调用图：调用 3 个内部函数（configured_plugin_states, marketplace_roots, list_marketplaces）；被 3 处调用（configured_marketplace_plugins, find_marketplace_for_plugin, verified_plugin_install_completed）；外部调用 2 个（new, default）。

fn discover_marketplaces_for_config(
        &self,
        config: &PluginsConfigInput,
        additional_roots: &[AbsolutePathBuf],
    ) -> Result<MarketplaceListOutcome, MarketplaceError>

作用：发现当前配置下有哪些市场文件或市场目录。

数据流：进去的是配置和额外根目录；插件关闭返回空结果，否则计算市场根目录并读取市场；出来是 MarketplaceListOutcome。

调用关系：它比 list_marketplaces_for_config 更轻，主要用于发现市场本身。

调用图：调用 2 个内部函数（marketplace_roots, list_marketplaces）；外部调用 1 个（default）。

async fn read_plugin_for_config(
        &self,
        config: &PluginsConfigInput,
        request: &PluginReadRequest,
    ) -> Result<PluginReadOutcome, MarketplaceError>

作用：读取某个市场插件的完整详情。

数据流：进去的是配置和读插件请求；插件关闭会报错，否则找到市场插件，检查产品限制，判断安装和启用状态，再交给详情读取函数；出来是 PluginReadOutcome。

调用关系：它是外部读单个插件详情的入口，内部调用 read_plugin_detail_for_marketplace_plugin。

调用图：调用 5 个内部函数（configured_plugin_states, read_plugin_detail_for_marketplace_plugin, restriction_product_matches, find_marketplace_plugin, active_plugin_version）。

async fn read_plugin_detail_for_marketplace_plugin(
        &self,
        config: &PluginsConfigInput,
        marketplace_name: &str,
        plugin: ConfiguredMarketplacePlugin,
    ) -> Result<Plu

作用：把一个市场插件展开成详细信息，包括描述、技能、钩子、应用、MCP 服务等。

数据流：进去的是配置、市场名和市场插件摘要；它检查产品限制，构造插件 ID，必要时提示远程 Git 插件需先安装；否则确定源目录、读取 manifest、加载技能、钩子、应用和 MCP 服务，并按认证模式过滤；出来是 PluginDetail。

调用关系：read_plugin_for_config 调用它；它把具体读取工作分发给 loader、hooks、skills 和 app/MCP 相关函数。

调用图：调用 14 个内部函数（apply_app_mcp_routing_policy, load_plugin_apps, load_plugin_hooks, load_plugin_mcp_servers, load_plugin_skills, auth_mode, restriction_product_matches, remote_plugin_install_required_description, load_plugin_manifest, plugin_interface_with_marketplace_category (+4 more)）；被 1 处调用（read_plugin_for_config）；外部调用 9 个（new, new, clone, new, plugin_hook_declarations, app_connector_ids_from_declarations, InvalidPlugin, matches!, spawn_blocking）。

fn maybe_start_plugin_startup_tasks_for_config(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth_manager: Arc<AuthManager>,
        on_effective_plugins_changed: Option<Arc<

作用：应用启动时启动插件系统的后台维护任务。

数据流：进去的是配置、认证管理器和变化回调；插件开启时，它启动官方精选仓库同步、配置市场自动升级、远程安装缓存刷新、远程包同步、远程目录预热和精选插件预热；出来立即返回。

调用关系：这是启动阶段的总入口，会调用 start_curated_repo_sync，并派生多个后台线程或异步任务。

调用图：调用 3 个内部函数（start_curated_repo_sync, remote_plugin_service_config, fetch_and_cache_global_remote_plugin_catalog）；外部调用 5 个（clone, clone, new, spawn, warn!）。

fn upgrade_configured_marketplaces_for_config(
        &self,
        config: &PluginsConfigInput,
        marketplace_name: Option<&str>,
    ) -> Result<ConfiguredMarketplaceUpgradeOutcome, String>

作用：升级配置中的 Git 插件市场，并刷新由这些市场安装出的插件缓存。

数据流：进去的是配置和可选市场名；它先确认指定市场确实是 Git 市场，再执行升级；如果有根目录升级，就强制重装/刷新非官方缓存，成功时清缓存，失败时记录错误；出来是升级结果或字符串错误。

调用关系：启动自动升级线程会调用它，也可被手动升级命令使用。

调用图：调用 4 个内部函数（refresh_non_curated_plugin_cache_force_reinstall, clear_cache, configured_git_marketplace_names, upgrade_configured_git_marketplaces）；外部调用 2 个（as_path, format!）。

fn maybe_start_non_curated_plugin_cache_refresh(
        self: &Arc<Self>,
        roots: &[AbsolutePathBuf],
    )

作用：安排非官方插件缓存刷新。

数据流：进去的是市场根目录列表；它选择“版本变化才刷新”的模式，交给调度函数；出来没有同步结果。

调用关系：列插件后台任务会调用它，实际去重和开线程由 schedule_non_curated_plugin_cache_refresh 做。

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

fn schedule_remote_installed_plugins_cache_refresh(
        self: &Arc<Self>,
        mut request: RemoteInstalledPluginsCacheRefreshRequest,
    )

作用：把远程已安装插件刷新请求放入队列，并保证同一时间只有一个刷新循环在跑。

数据流：进去的是刷新请求；它合并已有请求的通知策略和回调，记录最新请求，如果没有任务在跑就启动异步循环；出来没有返回值。

调用关系：maybe_start_remote_installed_plugins_cache_refresh_with_notify 调用它，后台工作由 run_remote_installed_plugins_cache_refresh_loop 完成。

调用图：被 1 处调用（maybe_start_remote_installed_plugins_cache_refresh_with_notify）；外部调用 3 个（clone, matches!, spawn）。

fn schedule_global_remote_catalog_cache_refresh(
        self: &Arc<Self>,
        request: GlobalRemoteCatalogCacheRefreshRequest,
    )

作用：安排全球远程插件目录缓存刷新，并避免重复开多个刷新任务。

数据流：进去的是刷新请求；它保存请求，若当前没有 in_flight 任务就 spawn 一个刷新循环；出来没有返回值。

调用关系：maybe_start_global_remote_catalog_cache_refresh 调用它，实际联网由 run_global_remote_catalog_cache_refresh_loop 做。

调用图：被 1 处调用（maybe_start_global_remote_catalog_cache_refresh）；外部调用 2 个（clone, spawn）。

fn schedule_non_curated_plugin_cache_refresh(
        self: &Arc<Self>,
        roots: &[AbsolutePathBuf],
        mode: NonCuratedCacheRefreshMode,
    )

作用：安排非官方插件缓存刷新，并合并重复请求。

数据流：进去的是根目录列表和刷新模式；它排序去重，空列表直接返回；然后根据当前状态判断是否重复、是否已有更强的强制刷新请求，必要时启动后台线程；出来没有返回值。

调用关系：maybe_start_non_curated_plugin_cache_refresh 调用它，后台线程运行 run_non_curated_plugin_cache_refresh_loop。

调用图：被 1 处调用（maybe_start_non_curated_plugin_cache_refresh）；外部调用 7 个（clone, new, dedup, is_empty, sort_unstable, to_vec, warn!）。

fn start_curated_repo_sync(self: &Arc<Self>)

作用：启动官方精选插件仓库同步，而且全进程只启动一次。

数据流：进去无业务参数；它用原子布尔值防重复，开线程同步仓库，成功后刷新精选插件缓存，缓存变化则清管理器缓存；失败会重置启动标记并记录警告。

调用关系：启动任务 maybe_start_plugin_startup_tasks_for_config 会调用它。

调用图：被 1 处调用（maybe_start_plugin_startup_tasks_for_config）；外部调用 4 个（clone, clone, new, warn!）。

async fn run_remote_installed_plugins_cache_refresh_loop(self: Arc<Self>)

作用：后台循环处理远程已安装插件刷新请求。

数据流：进去的是 Arc<Self>；它不断取出最新请求，联网拉取远程安装列表，成功则写缓存并按策略通知，认证问题则清缓存，其他错误只记录；没有请求时标记空闲并退出。

调用关系：由 schedule_remote_installed_plugins_cache_refresh 启动，是远程安装缓存真正工作的后台循环。

调用图：调用 3 个内部函数（clear_remote_installed_plugins_cache, write_remote_installed_plugins_cache, fetch_remote_installed_plugins）；外部调用 2 个（matches!, warn!）。

async fn run_global_remote_catalog_cache_refresh_loop(self: Arc<Self>)

作用：后台循环刷新全球远程插件目录缓存。

数据流：进去的是 Arc<Self>；它不断取请求并调用远程目录获取与缓存函数，认证类错误忽略，其他错误记录；请求用完后退出并标记空闲。

调用关系：由 schedule_global_remote_catalog_cache_refresh 启动。

调用图：调用 1 个内部函数（fetch_and_cache_global_remote_plugin_catalog）；外部调用 2 个（as_path, warn!）。

fn run_non_curated_plugin_cache_refresh_loop(self: Arc<Self>)

作用：后台刷新非官方插件缓存，并根据是否有新请求决定是否继续跑。

数据流：进去的是 Arc<Self>；它读取当前请求，按模式执行普通刷新或强制重装刷新；成功且缓存变化就清缓存，失败也清缓存并警告；最后更新刷新状态，没有新请求则退出。

调用关系：由 schedule_non_curated_plugin_cache_refresh 开线程运行。

调用图：调用 3 个内部函数（refresh_non_curated_plugin_cache, refresh_non_curated_plugin_cache_force_reinstall, clear_cache）；外部调用 2 个（as_path, warn!）。

fn configured_plugin_states(
        &self,
        config: &PluginsConfigInput,
    ) -> (HashSet<String>, HashSet<String>)

作用：从用户配置和本地存储里算出哪些插件已安装、哪些插件已启用。

数据流：进去的是配置输入；它读取用户配置里的插件项，逐个检查 store 里是否安装，再筛出 enabled 为 true 的插件；出来是两个字符串集合。

调用关系：列市场和读插件详情前都会调用它，用来给插件打状态标记。

调用图：调用 1 个内部函数（configured_plugins_from_stack）；被 2 处调用（list_marketplaces_for_config, read_plugin_for_config）。

fn marketplace_roots(
        &self,
        config: &PluginsConfigInput,
        additional_roots: &[AbsolutePathBuf],
        include_openai_curated: bool,
    ) -> Vec<AbsolutePathBuf>

作用：整理当前应该扫描的插件市场位置。

数据流：进去的是配置、额外根目录和是否包含官方精选市场；它合并额外根目录、配置里的市场根目录，以及按认证模式选择的官方精选市场路径；最后排序去重；出来是绝对路径列表。

调用关系：discover_marketplaces_for_config 和 list_marketplaces_for_config 都靠它决定去哪里找市场。

调用图：调用 4 个内部函数（installed_marketplace_roots_from_layer_stack, curated_plugins_api_marketplace_path, curated_plugins_repo_path, try_from）；被 2 处调用（discover_marketplaces_for_config, list_marketplaces_for_config）；外部调用 3 个（as_path, matches!, to_vec）。

fn remote_plugin_install_required_description(source: &MarketplacePluginSource) -> String

作用：为尚未安装的跨仓库插件生成一段说明，告诉用户需要先安装才能看详情。

数据流：进去的是插件来源；它把 Git URL、子路径、ref、sha 或本地路径拼成可读描述；出来是一段英文提示文字。

调用关系：read_plugin_detail_for_marketplace_plugin 遇到未安装的 Git 来源插件时会调用它。

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

fn join(source: tokio::task::JoinError) -> Self

作用：把后台安装任务的 JoinError 包装成插件安装错误。

数据流：进去的是 tokio 任务 JoinError；它封装成 PluginInstallError::Join；出来是统一错误类型。

调用关系：install_resolved_plugin 在线程池任务失败连接时用它做错误转换。

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

fn is_invalid_request(&self) -> bool

作用：判断安装失败是不是因为用户请求本身不合法。

数据流：进去的是安装错误；它匹配市场不存在、插件不存在、插件不可用、插件无效或存储无效等情况；出来是布尔值。

调用关系：上层可以用它把“用户传错了”和“系统内部失败”区分开。

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

fn join(source: tokio::task::JoinError) -> Self

作用：把后台卸载任务的 JoinError 包装成插件卸载错误。

数据流：进去的是 tokio 任务 JoinError；它封装成 PluginUninstallError::Join；出来是统一错误类型。

调用关系：uninstall_plugin_id 在线程池卸载失败连接时会用它。

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

fn is_invalid_request(&self) -> bool

作用：判断卸载失败是不是因为插件 ID 不合法。

数据流：进去的是卸载错误；它只检查是否为 InvalidPluginId；出来是布尔值。

调用关系：上层可用它给用户返回更明确的“插件 ID 写错了”。

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

fn configured_plugins_from_stack(
    config_layer_stack: &ConfigLayerStack,
) -> HashMap<String, PluginConfig>

作用：从配置层栈里取出用户配置中的插件设置。

数据流：进去的是 ConfigLayerStack；它只读取 effective_user_config，没用户配置就返回空表，有则继续解析 plugins 字段；出来是插件配置映射。

调用关系：插件加载和状态计算都会调用它；它把解析细节交给 configured_plugins_from_user_config_value。

调用图：调用 2 个内部函数（effective_user_config, configured_plugins_from_user_config_value）；被 2 处调用（configured_plugin_states, plugins_for_config_with_force_reload）；外部调用 1 个（new）。

fn configured_plugins_from_user_config_value(
    user_config: &toml::Value,
) -> HashMap<String, PluginConfig>

作用：把用户配置文件里的 plugins 字段解析成程序可用的插件配置表。

数据流：进去的是 TOML 配置值；它取 plugins 字段并尝试转换成 HashMap，失败会记录警告并返回空表；出来是插件配置映射。

调用关系：configured_plugins_from_stack 调用它，是用户插件配置从文本变成结构化数据的最后一步。

调用图：被 1 处调用（configured_plugins_from_stack）；外部调用 3 个（new, get, warn!）。

fn record_added_marketplace_entry(
    codex_home: &Path,
    marketplace_name: &str,
    install_metadata: &MarketplaceInstallMetadata,
) -> Result<(), MarketplaceAddError>

作用：把刚添加的插件市场写进用户的 config.toml 配置文件。这样程序以后能知道这个市场从哪里来、什么时候添加或更新过。

数据流：输入用户目录、市场名字和安装来源信息 → 从来源信息里取出类型、地址、分支名和稀疏路径，再生成当前 UTC 时间 → 组装成一条配置更新记录并写入用户配置；成功时不返回额外内容，失败时返回带说明的添加错误。

调用关系：它在添加市场成功后由 add_marketplace_sync_with_cloner 调用，属于收尾登记步骤。它把取来源字段的小活交给 MarketplaceInstallMetadata::config_source、config_source_type、ref_name、sparse_paths，把取当前时间交给 utc_timestamp_now，最后调用外部的 record_user_marketplace 真正写配置。测试 installed_marketplace_root_for_source_uses_local_source_root 也用它先制造一条配置记录。

调用图：调用 5 个内部函数（config_source, config_source_type, ref_name, sparse_paths, utc_timestamp_now）；被 2 处调用（add_marketplace_sync_with_cloner, installed_marketplace_root_for_source_uses_local_source_root）；外部调用 1 个（record_user_marketplace）。

fn installed_marketplace_root_for_source(
    codex_home: &Path,
    install_root: &Path,
    install_metadata: &MarketplaceInstallMetadata,
) -> Result<Option<PathBuf>, MarketplaceAddError>

作用：根据一个市场的来源信息，去用户配置里找“这个来源是不是已经安装过”。如果找到了，并且目录有效，就返回那个目录。

数据流：输入用户目录、安装根目录和来源身份证 → 读取 config.toml，解析成 TOML（一种常见配置文件格式）结构 → 遍历里面的 marketplaces 配置，逐条比较来源是否一致，再把配置里的信息解析成真实目录并验证目录合法 → 找到就返回目录，找不到返回空；配置读不出来或格式坏了则返回错误。

调用关系：它在 add_marketplace_sync_with_cloner 里用于决定是否可以复用已有安装，而不是重新安装。它用 MarketplaceInstallMetadata::matches_config 判断配置条目是不是同一个来源，用 resolve_configured_marketplace_root 把配置变成路径，用 validate_marketplace_root 检查这个路径确实是可用市场。两个测试分别验证它遇到配置读取错误会报错，以及本地来源能被正确找回。

调用图：调用 3 个内部函数（resolve_configured_marketplace_root, validate_marketplace_root, matches_config）；被 3 处调用（add_marketplace_sync_with_cloner, installed_marketplace_root_for_source_propagates_config_read_errors, installed_marketplace_root_for_source_uses_local_source_root）；外部调用 5 个（join, Internal, format!, read_to_string, from_str）。

fn find_marketplace_root_by_name(
    codex_home: &Path,
    install_root: &Path,
    marketplace_name: &str,
) -> Result<Option<PathBuf>, MarketplaceAddError>

作用：按市场名字去配置里找对应的已安装目录。它解决的是“我知道名字，但不知道目录在哪”的问题。

数据流：输入用户目录、安装根目录和市场名字 → 读取并解析 config.toml → 在 marketplaces 表里按名字取出那一项 → 把这项配置解析成实际根目录并检查目录是否合法 → 合法就返回路径，不存在或不合法就返回空，读取或解析配置失败则返回错误。

调用关系：它由 add_marketplace_sync_with_cloner 调用，通常用于安装流程里按名字确认已有市场位置。和 installed_marketplace_root_for_source 不同，它不是按来源匹配，而是直接按名字查找；找到配置后同样把路径解析交给 resolve_configured_marketplace_root，把合法性检查交给 validate_marketplace_root。

调用图：调用 2 个内部函数（resolve_configured_marketplace_root, validate_marketplace_root）；被 1 处调用（add_marketplace_sync_with_cloner）；外部调用 5 个（join, Internal, format!, read_to_string, from_str）。

fn from_source(source: &MarketplaceSource, sparse_paths: &[String]) -> Self

作用：把用户提供的市场来源，转换成这个文件内部使用的“安装来源身份证”。这一步让后续写配置、匹配配置时有统一格式。

数据流：输入 MarketplaceSource，也就是外部传来的来源信息，以及稀疏路径列表 → 如果是 Git 来源，就保存 URL、分支或标签名、稀疏路径；如果是本地来源，就保存本地路径字符串 → 输出一个 MarketplaceInstallMetadata 对象。

调用关系：它在 add_marketplace_sync_with_cloner 开始处理来源时被调用，是后面所有元数据操作的起点。测试里也用它快速构造来源信息，然后交给 installed_marketplace_root_for_source 或 record_added_marketplace_entry 使用。

调用图：被 3 处调用（add_marketplace_sync_with_cloner, installed_marketplace_root_for_source_propagates_config_read_errors, installed_marketplace_root_for_source_uses_local_source_root）。

fn config_source_type(&self) -> &'static str

作用：把内部来源类型翻译成写进配置文件的文字：Git 来源写成“git”，本地来源写成“local”。

数据流：输入当前 MarketplaceInstallMetadata 自己保存的来源 → 查看它是 Git 还是本地 → 输出一个固定字符串，供配置文件保存或比较。

调用关系：record_added_marketplace_entry 用它写入配置，matches_config 用它和配置里的 source_type 字段对照。它是一个小翻译器，保证写入和比较时用同一套词。

调用图：被 2 处调用（matches_config, record_added_marketplace_entry）。

fn config_source(&self) -> String

作用：取出配置文件里要记录的“来源地址”。Git 来源就是仓库 URL，本地来源就是本地路径。

数据流：输入当前安装来源信息 → 如果来源是 Git，就复制 Git URL；如果是本地，就复制路径字符串 → 输出这个来源字符串。

调用关系：record_added_marketplace_entry 用它把来源写进配置，matches_config 用它检查配置里的 source 字段是不是同一个来源。它让外层代码不用关心来源内部到底是哪种类型。

调用图：被 2 处调用（matches_config, record_added_marketplace_entry）。

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

作用：取出 Git 的分支名、标签名或提交引用；本地来源没有这个概念，所以返回空。

数据流：输入当前安装来源信息 → 如果是 Git，就返回里面保存的 ref_name；如果是本地，就返回 None，也就是没有值 → 输出可选的字符串引用。

调用关系：record_added_marketplace_entry 用它把 Git 引用写进配置，matches_config 用它确认配置里的 ref 是否一致。它帮助区分同一个仓库的不同分支或标签，避免误认为是同一个安装。

调用图：被 2 处调用（matches_config, record_added_marketplace_entry）。

fn sparse_paths(&self) -> &[String]

作用：取出 Git 稀疏路径列表。稀疏路径就是只安装仓库里指定的几个子目录，而不是整仓库；本地来源没有这个设置。

数据流：输入当前安装来源信息 → 如果是 Git，就返回保存的稀疏路径列表；如果是本地，就返回空列表 → 输出一个字符串列表的引用。

调用关系：record_added_marketplace_entry 用它写配置，matches_config 用它比较配置。它让“同一个 Git 仓库但只取不同目录”的情况也能被正确区分。

调用图：被 2 处调用（matches_config, record_added_marketplace_entry）。

fn matches_config(&self, marketplace: &toml::Value) -> bool

作用：判断配置文件里的某个市场条目，是否和当前这份安装来源信息完全对应。

数据流：输入当前安装来源信息和一段 TOML 配置值 → 读取配置里的 source_type、source、ref、sparse_paths → 分别和当前对象里的来源类型、来源地址、引用名、稀疏路径比较 → 全部一致就返回 true，否则返回 false。

调用关系：installed_marketplace_root_for_source 遍历所有已配置市场时会调用它，用来筛出“来源相同”的那一项。它内部调用 config_source_type、config_source、ref_name、sparse_paths 取当前来源字段，并调用 config_sparse_paths 解析配置里的稀疏路径。

调用图：调用 5 个内部函数（config_source, config_source_type, ref_name, sparse_paths, config_sparse_paths）；被 1 处调用（installed_marketplace_root_for_source）；外部调用 1 个（get）。

fn config_sparse_paths(marketplace: &toml::Value) -> Vec<String>

作用：从一个市场配置条目里读出 sparse_paths，也就是 Git 稀疏安装时指定的子路径列表。

数据流：输入一段 TOML 市场配置 → 查找 sparse_paths 字段，看它是不是数组 → 把数组里能当字符串的值收集起来 → 输出字符串列表；如果字段不存在或不是数组，就输出空列表。

调用关系：它只被 MarketplaceInstallMetadata::matches_config 调用，专门负责把配置里的稀疏路径整理成可比较的普通列表。这样 matches_config 不用关心 TOML 结构的细节。

调用图：被 1 处调用（matches_config）；外部调用 1 个（get）。

fn utc_timestamp_now() -> Result<String, MarketplaceAddError>

作用：生成当前时间的 UTC 时间戳，用来写进配置里的 last_updated。UTC 是统一世界时间，可以避免不同时区造成混乱。

数据流：输入不来自参数，而是读取系统当前时间 → 计算它距离 Unix epoch（1970-01-01 00:00:00 UTC，很多系统计时的起点）过去了多少秒 → 把秒数交给 format_utc_timestamp 变成类似 2026-04-10T00:00:00Z 的字符串；如果系统时钟早于 1970 年，就返回错误。

调用关系：record_added_marketplace_entry 在写配置前调用它，给这次记录盖上时间戳。它把格式化工作交给 format_utc_timestamp，自己主要负责从系统拿当前时间并处理异常。

调用图：调用 1 个内部函数（format_utc_timestamp）；被 1 处调用（record_added_marketplace_entry）；外部调用 1 个（now）。

fn format_utc_timestamp(seconds_since_epoch: i64) -> String

作用：把“从 1970 年起过了多少秒”转换成人能看懂、机器也好读的 UTC 时间字符串。

数据流：输入一个秒数 → 拆成天数和一天内的时、分、秒 → 调用 civil_from_days 把天数换成年、月、日 → 拼成 RFC3339 风格的字符串，例如 1970-01-01T00:00:00Z → 输出这个字符串。

调用关系：utc_timestamp_now 用它把系统时间变成配置文件里的文本。测试 utc_timestamp_formats_unix_epoch_as_rfc3339_utc 直接检查它对几个固定秒数的输出，确保时间格式不会悄悄变错。

调用图：调用 1 个内部函数（civil_from_days）；被 1 处调用（utc_timestamp_now）；外部调用 1 个（format!）。

fn civil_from_days(days_since_epoch: i64) -> (i64, i64, i64)

作用：把距离 1970-01-01 的天数换算成公历的年、月、日。它是时间戳格式化里的日历计算小零件。

数据流：输入天数 → 用一套纯数学公式处理闰年、世纪年、月份偏移等日历规则 → 输出年、月、日三个数字。

调用关系：它只被 format_utc_timestamp 调用。format_utc_timestamp 负责时分秒和最终字符串，而 civil_from_days 只负责最容易出错的日期换算部分。

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

fn utc_timestamp_formats_unix_epoch_as_rfc3339_utc()

作用：测试时间格式化是否正确，特别是 Unix 计时起点和另一个固定日期。这样能防止配置里的更新时间变成错误格式。

数据流：输入两个固定秒数写在测试里 → 调用 format_utc_timestamp 得到字符串 → 和预期的 UTC 字符串比较 → 如果不一致，测试失败，不改动外部状态。

调用关系：它是 format_utc_timestamp 的保护网。时间格式一旦被改坏，这个测试会提醒开发者。

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

fn installed_marketplace_root_for_source_propagates_config_read_errors()

作用：测试读取用户配置失败时，查找已安装市场的函数不会假装没事，而是把错误说清楚。

数据流：测试先创建一个临时用户目录，再故意把 config.toml 的位置建成目录，让读取文件必然失败 → 构造一个 Git 来源元数据 → 调用 installed_marketplace_root_for_source → 期望得到错误，并检查错误文字里包含读取配置失败的信息。

调用关系：它验证 installed_marketplace_root_for_source 的错误处理路径，也用 MarketplaceInstallMetadata::from_source 构造测试输入。这个测试保证真实用户遇到坏配置路径时能看到明确报错。

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

fn installed_marketplace_root_for_source_uses_local_source_root()

作用：测试本地来源的市场能被正确记录并重新找到。也就是说，配置里写的是本地路径时，程序应该返回这个原始目录。

数据流：测试创建临时目录和一个看起来合法的本地市场文件结构 → 用 from_source 构造本地来源元数据 → 调用 record_added_marketplace_entry 写入配置 → 再调用 installed_marketplace_root_for_source 查找 → 期望返回的路径就是原来的本地来源目录。

调用关系：它把 record_added_marketplace_entry 和 installed_marketplace_root_for_source 串起来测了一遍，确认“写配置”和“按来源找回目录”这两个步骤能配合工作。

调用图：调用 3 个内部函数（from_source, installed_marketplace_root_for_source, record_added_marketplace_entry）；外部调用 4 个（new, assert_eq!, create_dir_all, write）。

fn parse_marketplace_source(
    source: &str,
    explicit_ref: Option<String>,
) -> Result<MarketplaceSource, MarketplaceAddError>

作用：把用户写的一段来源文字，翻译成程序能理解的 MarketplaceSource：要么是 Git 仓库，要么是本地目录。它也会顺手检查明显不合法的写法，避免后面下载或读取时才爆错。

数据流：进去的是原始 source 字符串和一个可选的 explicit_ref 分支/标签名；它先去掉空白，拆出 # 或 @ 后面的引用，再判断像不像本地路径、Git URL，或 GitHub 的 owner/repo 简写；出来的是规范化后的 MarketplaceSource，或者一条告诉用户哪里写错的 MarketplaceAddError。

调用关系：这是 add_marketplace_sync_with_cloner 添加 marketplace 时最早用到的解析关口。它把细节活交给 split_source_ref、looks_like_local_path、resolve_local_source_path、is_git_url、is_ssh_git_url、looks_like_github_shorthand 和 normalize_git_url；很多测试也直接调用它，确认各种输入都会被分到正确类型。

调用图：调用 7 个内部函数（is_git_url, is_ssh_git_url, looks_like_github_shorthand, looks_like_local_path, normalize_git_url, resolve_local_source_path, split_source_ref）；被 6 处调用（add_marketplace_sync_with_cloner, file_url_source_is_rejected, github_shorthand_and_git_url_normalize_to_same_source, local_file_source_is_rejected, local_path_source_parses, non_git_sources_reject_ref_override）；外部调用 2 个（InvalidRequest, format!）。

fn stage_marketplace_source(
    source: &MarketplaceSource,
    sparse_paths: &[String],
    staged_root: &Path,
    clone_source: F,
) -> Result<(), MarketplaceAddError>

作用：在需要把远程 marketplace 先放到临时目录时，这个函数决定能不能 staging，并调用外部传进来的克隆函数。staging 可以理解成“先把货卸到临时仓库里检查”。

数据流：进去的是已经解析好的来源、稀疏路径列表、临时目录 staged_root，以及一个 clone_source 回调；它先拒绝“本地路径还要求稀疏下载”的情况，然后对 Git 来源调用 clone_source；出来通常是成功或错误，本身不直接下载，而是把下载动作交出去。

调用关系：add_marketplace_sync_with_cloner 会在准备远程 Git marketplace 时调用它。它不处理本地 marketplace，因为本地来源不需要复制安装根目录；测试 non_git_sources_reject_sparse_checkout 专门确认本地来源不能用 --sparse。

调用图：被 2 处调用（add_marketplace_sync_with_cloner, non_git_sources_reject_sparse_checkout）；外部调用 3 个（InvalidRequest, matches!, unreachable!）。

fn validate_marketplace_source_root(root: &Path) -> Result<String, MarketplaceAddError>

作用：检查一个 marketplace 根目录是不是真的像一个合法 marketplace，并取出它的名字。它防止用户给了一个目录，但里面结构不对或名字不能当插件标识。

数据流：进去的是一个目录路径 root；它先调用 validate_marketplace_root 检查目录内容并拿到 marketplace 名字，再用 validate_plugin_segment 检查这个名字是否适合做标识；出来是合法的名字字符串，或转成 MarketplaceAddError 的错误。

调用关系：add_marketplace_sync_with_cloner 在拿到本地目录或克隆完远程仓库后会用它做最后验收。它连接了 marketplace 根目录校验和插件命名规则校验，保证后续安装看到的是干净、可信的输入。

调用图：调用 1 个内部函数（validate_marketplace_root）；被 1 处调用（add_marketplace_sync_with_cloner）；外部调用 1 个（validate_plugin_segment）。

fn split_source_ref(source: &str) -> (String, Option<String>)

作用：从来源字符串里拆出“仓库/路径本体”和“想要的分支或标签”。比如 owner/repo@main 会被拆成 owner/repo 和 main。

数据流：进去的是一整段 source；它优先用 # 拆引用，如果不是带协议的 URL、也不是 SSH Git 地址，再允许用 @ 拆引用；出来是 base_source 字符串和可选 ref_name。

调用关系：parse_marketplace_source 一开始就调用它。它内部会问 is_ssh_git_url，避免把 git@host:path 这种 SSH 地址里的 @ 错当成分支分隔符，并把候选引用交给 non_empty_ref 清理。

调用图：调用 2 个内部函数（is_ssh_git_url, non_empty_ref）；被 1 处调用（parse_marketplace_source）。

fn non_empty_ref(ref_name: &str) -> Option<String>

作用：把引用名收拾一下，只留下真正有内容的分支或标签名。空的引用不会被当成有效值。

数据流：进去的是可能带空格的 ref_name；它去掉前后空白，检查是否为空；出来是 Some(干净字符串) 或 None。

调用关系：split_source_ref 在拆出 # 或 @ 后面的内容时调用它。这样 parse_marketplace_source 后面看到的引用要么是真有名字，要么就是没有引用。

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

fn normalize_git_url(url: &str) -> String

作用：把 Git 地址整理成更统一的样子，尤其是 GitHub HTTPS 地址。这样 owner/repo 简写和完整 GitHub URL 最后能对齐。

数据流：进去的是一个 Git URL；它先去掉末尾多余的斜杠，如果是 https://github.com/... 且没有 .git，就补上 .git；出来是规范化后的 URL 字符串。

调用关系：parse_marketplace_source 在确认来源是 Git URL 后调用它。它让后面的比较、显示和克隆少受用户输入格式差异影响。

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

fn looks_like_local_path(source: &str) -> bool

作用：判断一段输入是不是更像本地路径，而不是仓库名或网址。这样 ./marketplace、~/marketplace、C:\... 这类输入不会被误当成 GitHub 简写。

数据流：进去的是 source 字符串；它检查 Unix 绝对路径、Windows 绝对路径、相对路径前缀、~ 家目录、单独的 . 或 ..；出来是 true 或 false。

调用关系：parse_marketplace_source 用它决定是否走本地目录解析。它把 Windows 路径判断交给 looks_like_windows_absolute_path，保证即使程序跑在非 Windows 系统上也能识别 Windows 风格路径。

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

fn looks_like_windows_absolute_path(source: &str) -> bool

作用：专门识别 Windows 绝对路径，比如 C:\Users\alice 或 \\server\share。它让路径判断不只适合当前操作系统。

数据流：进去的是 source 字符串；它查看字节形式，判断是不是盘符加冒号加斜杠，或者 UNC 网络路径开头；出来是 true 或 false。

调用关系：looks_like_local_path 会调用它补足 Windows 情况。测试 windows_absolute_paths_look_like_local_paths_on_every_host 覆盖了这类判断。

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

fn resolve_local_source_path(source: &str) -> Result<PathBuf, MarketplaceAddError>

作用：把用户写的本地路径变成真实、可用的绝对路径。它会发现路径不存在、无法访问等问题，并把这些变成用户能看到的错误。

数据流：进去的是本地路径字符串；它先展开 ~/，如果还是相对路径就接到当前工作目录后面，然后 canonicalize，也就是解析成系统确认存在的真实路径；出来是 PathBuf，或说明无法解析的 MarketplaceAddError。

调用关系：parse_marketplace_source 认定输入是本地路径后会调用它。它把家目录展开交给 expand_tilde_path，并在读取当前目录失败时返回内部错误。

调用图：调用 1 个内部函数（expand_tilde_path）；被 1 处调用（parse_marketplace_source）；外部调用 1 个（current_dir）。

fn expand_tilde_path(source: &str) -> PathBuf

作用：把 ~/xxx 这种写法换成用户家目录下的真实路径。用户常用这种缩写，这个函数让程序也懂。

数据流：进去的是路径字符串；如果不是 ~/ 开头，就原样变成 PathBuf；如果是，就读取 HOME 或 USERPROFILE 环境变量，把后半段拼到家目录后面；出来是一个 PathBuf。

调用关系：resolve_local_source_path 在处理本地路径前调用它。它只做轻量转换，不检查路径是否存在，真正的存在性检查由后面的 canonicalize 完成。

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

fn is_ssh_git_url(source: &str) -> bool

作用：判断输入是不是 SSH 形式的 Git 地址。SSH 可以理解成用钥匙登录服务器的仓库地址，常见写法有 ssh://... 或 git@github.com:owner/repo.git。

数据流：进去的是 source 字符串；它检查是否以 ssh:// 开头，或者是否以 git@ 开头且包含冒号；出来是 true 或 false。

调用关系：parse_marketplace_source 用它识别 Git 来源，split_source_ref 用它避免错误拆分 git@... 里的 @。

调用图：被 2 处调用（parse_marketplace_source, split_source_ref）。

fn is_git_url(source: &str) -> bool

作用：判断输入是不是 HTTP 或 HTTPS 形式的 Git 地址。这里不证明仓库真的存在，只判断格式像不像。

数据流：进去的是 source 字符串；它检查是否以 http:// 或 https:// 开头；出来是 true 或 false。

调用关系：parse_marketplace_source 在本地路径判断之后调用它。若返回 true，来源会被当作 Git 仓库并送去 normalize_git_url 整理。

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

fn looks_like_github_shorthand(source: &str) -> bool

作用：判断输入是不是 GitHub 简写，也就是 owner/repo 这种两段式写法。这样用户不用每次都写完整 https://github.com/owner/repo.git。

数据流：进去的是 source 字符串；它按 / 拆成段，要求刚好两段，并且每段字符都合法；出来是 true 或 false。

调用关系：parse_marketplace_source 在排除本地路径和完整 Git URL 后调用它。段名是否合法由 is_github_shorthand_segment 判断。

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

fn is_github_shorthand_segment(segment: &str) -> bool

作用：检查 GitHub 简写中的一段名字是否合法，比如 owner 或 repo。它要求不能为空，只能用常见的字母、数字、横线、下划线和点。

数据流：进去的是一个 segment 字符串；它逐个字符检查是否属于允许范围；出来是 true 或 false。

调用关系：它是 looks_like_github_shorthand 的小零件，用来分别检查 owner 和 repo 两段。虽然调用图没有单独列出调用者，但代码中它服务于 GitHub 简写判断。

fn display(&self) -> String

作用：把已经解析好的 MarketplaceSource 再变成适合显示给人的文字。它用于日志、错误提示或界面展示时，让用户知道当前来源是什么。

数据流：进去的是一个 MarketplaceSource；如果是 Git，就输出 URL，并在有引用时拼上 #ref；如果是本地目录，就输出路径字符串；出来是可读的 String。

调用关系：这是 MarketplaceSource 这个类型自带的展示方法。它不参与解析，只在别的流程需要把来源说明白时提供统一格式。

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

fn github_shorthand_parses_ref_suffix()

作用：测试 owner/repo@main 这种 GitHub 简写带分支名的输入能被正确识别。它保护的是用户最省事的写法。

数据流：进去的是测试里写死的 owner/repo@main；测试期望解析后变成 GitHub 的完整 .git 地址，并带 main 引用；出来是测试通过或断言失败。

调用关系：它属于本文件的测试模块，用 assert_eq! 对照期望结果。它覆盖 parse_marketplace_source 对 GitHub 简写和 @ 引用后缀的处理。

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

fn git_url_parses_fragment_ref()

作用：测试完整 Git URL 后面带 #v1 时，# 后面的内容会被当成分支或标签。这样用户可以直接在地址里指定版本。

数据流：进去的是 https://example.com/team/repo.git#v1；测试期望得到不带 #v1 的仓库地址和 ref_name=v1；出来是测试通过或断言失败。

调用关系：它用 assert_eq! 验证解析结果，主要保护 split_source_ref 对 # 分隔符的行为，以及 parse_marketplace_source 对普通 HTTPS Git 地址的接受。

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

fn explicit_ref_overrides_source_ref()

作用：测试命令行单独传入的 --ref 会覆盖来源字符串里写的 @main。这样规则明确，不会出现两个版本名打架。

数据流：进去的是 owner/repo@main 和 explicit_ref=release；测试期望最终 ref_name 是 release，而不是 main；出来是测试通过或断言失败。

调用关系：它验证 parse_marketplace_source 里 explicit_ref.or(parsed_ref) 这条优先级规则。这个规则对调用方 add_marketplace_sync_with_cloner 很重要，因为命令参数应该比字符串后缀更明确。

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

fn github_shorthand_and_git_url_normalize_to_same_source()

作用：测试 owner/repo 和 https://github.com/owner/repo.git 最后会被看成同一个来源。这样不同写法不会造成重复或比较错误。

数据流：进去的是 GitHub 简写和完整 URL 两种字符串；测试分别解析它们，再比较结果是否相等，并确认最终 URL 是带 .git 的标准形式；出来是测试通过或断言失败。

调用关系：调用图显示它会调用 parse_marketplace_source，并用 assert_eq! 比较。它主要保护 looks_like_github_shorthand 和 normalize_git_url 的配合。

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

fn github_url_with_trailing_slash_normalizes_without_extra_path_segment()

作用：测试 GitHub URL 末尾多写一个斜杠时，不会变成奇怪的多一层路径。用户复制地址时经常会带这个斜杠。

数据流：进去的是 https://github.com/owner/repo/；测试期望输出 https://github.com/owner/repo.git；出来是测试通过或断言失败。

调用关系：它用 assert_eq! 保护 normalize_git_url 的行为，确保 parse_marketplace_source 在处理 GitHub URL 时先去掉末尾斜杠再补 .git。

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

fn non_github_https_source_parses_as_git_url()

作用：测试非 GitHub 的 HTTPS 地址也能当作 Git 仓库来源。也就是说这里不是只支持 GitHub。

数据流：进去的是 https://gitlab.com/owner/repo；测试期望它被解析成 Git 来源，URL 原样保留；出来是测试通过或断言失败。

调用关系：它用 assert_eq! 验证 is_git_url 的宽松判断和 normalize_git_url 的谨慎行为：只有 GitHub 地址才会自动补 .git。

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

fn file_url_source_is_rejected()

作用：测试 file:///tmp/... 这种 file URL 会被拒绝。这样用户不会误以为可以用文件协议当 marketplace 来源。

数据流：进去的是 file:///tmp/marketplace.git；测试期望解析失败，并且错误信息包含 invalid marketplace source format；出来是测试通过或断言失败。

调用关系：调用图显示它调用 parse_marketplace_source 和 assert!。它保护 parse_marketplace_source 的格式边界：只接受 owner/repo、Git URL 或本地路径，不接受 file://。

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

fn local_path_source_parses()

作用：测试 . 这种当前目录写法会被识别成本地 marketplace 路径。它保证本地开发调试时可以直接添加当前目录。

数据流：进去的是字符串 .；测试解析后要求结果是 Local，并且路径已经变成绝对路径；如果不是 Local 就主动 panic；出来是测试通过或失败。

调用关系：调用图显示它调用 parse_marketplace_source、assert! 和 panic!。它覆盖 looks_like_local_path 与 resolve_local_source_path 的基本配合。

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

fn windows_absolute_paths_look_like_local_paths_on_every_host()

作用：测试 Windows 风格绝对路径在任何系统上都能被识别成本地路径。这样 Linux 或 macOS 上运行测试时也不会漏掉 Windows 用户场景。

数据流：进去的是几种 Windows 路径字符串，包括盘符路径和网络共享路径；测试期望真正的绝对路径返回 true，C:relative\path 这种相对写法返回 false；出来是测试通过或断言失败。

调用关系：它用 assert! 保护 looks_like_windows_absolute_path 和 looks_like_local_path 的跨平台判断。

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

fn local_file_source_is_rejected()

作用：测试如果用户给的是一个本地文件，而不是目录，会被明确拒绝。marketplace 来源需要是目录，因为里面要有完整结构。

数据流：进去的是临时目录里创建出的 marketplace.json 文件路径；测试解析它，期望失败，并检查错误信息说明“必须是目录不是文件”；出来是测试通过或失败。

调用关系：调用图显示它会创建临时目录、写文件、调用 parse_marketplace_source，并用 assert! 检查错误。它保护 parse_marketplace_source 中 path.is_file() 的防呆检查。

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

fn non_git_sources_reject_ref_override()

作用：测试本地路径不能使用 --ref。--ref 是给 Git 分支或标签用的，本地目录没有这个概念。

数据流：进去的是 ./marketplace 加 explicit_ref=main；测试期望解析失败，并且错误信息说明 --ref 只支持 Git marketplace 来源；出来是测试通过或失败。

调用关系：调用图显示它调用 parse_marketplace_source 和 assert!。它保护 parse_marketplace_source 对本地路径和 Git 专属参数的边界检查。

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

fn non_git_sources_reject_sparse_checkout()

作用：测试本地来源不能使用 --sparse。sparse checkout 是 Git 的“只取一部分目录”能力，本地目录不需要也不支持这个步骤。

数据流：进去的是一个 Local 来源、一个稀疏路径 plugins/foo、临时 staged_root 和假的 clone 回调；测试期望 stage_marketplace_source 直接报错；出来是测试通过或失败。

调用关系：调用图显示它调用 stage_marketplace_source、Path::new、current_dir 和 assert!。它保护 stage_marketplace_source 在调用 clone_source 之前的参数检查。

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

fn ssh_url_parses_as_git_url()

作用：测试 ssh://git@github.com/...#main 这种 SSH Git 地址能被识别，并能拆出 main 引用。它覆盖使用 SSH 密钥访问仓库的用户。

数据流：进去的是带 #main 的 SSH URL；测试期望输出同一个 SSH 仓库地址和 ref_name=main；出来是测试通过或断言失败。

调用关系：它用 assert_eq! 保护 is_ssh_git_url、split_source_ref 和 parse_marketplace_source 的组合行为，尤其是不要把 SSH 地址里的 git@ 部分误拆。

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

async fn add_marketplace(
    codex_home: PathBuf,
    request: MarketplaceAddRequest,
) -> Result<MarketplaceAddOutcome, MarketplaceAddError>

作用：这是对外使用的异步入口，用来添加一个插件市场。它把真正耗时的文件操作和 Git 操作放到后台线程里跑，避免卡住异步运行环境。

数据流：进去的是 Codex 的主目录路径和一个添加请求，里面有来源地址、可选分支名、可选 sparse 路径。它把这些交给同步版本执行，并等待结果。出来的是添加结果；如果后台线程出错，就包装成“添加失败”的内部错误。

调用关系：它会被 import_plugins 和 run_add 这类上层流程调用。自己不直接做安装细节，而是通过 spawn_blocking 把活儿交给 add_marketplace_sync 这一套同步流程。

调用图：被 2 处调用（import_plugins, run_add）；外部调用 1 个（spawn_blocking）。

fn is_local_marketplace_source(
    source: &str,
    explicit_ref: Option<String>,
) -> Result<bool, MarketplaceAddError>

作用：这个函数只回答一个问题：给定的 marketplace 来源是不是本地目录。上层可以用它提前判断接下来该走本地路径逻辑还是远程 Git 逻辑。

数据流：进去的是用户输入的来源字符串和可选的引用名。它先调用解析器把字符串变成结构化来源，再看解析结果是不是 Local。本地就返回 true，不是就返回 false；解析失败就返回错误。

调用关系：它是一个小型判断工具。它依赖 parse_marketplace_source 来读懂来源格式，但不参与真正安装，也不会改动磁盘或配置。

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

fn add_marketplace_sync(
    codex_home: &Path,
    request: MarketplaceAddRequest,
) -> Result<MarketplaceAddOutcome, MarketplaceAddError>

作用：这是同步版本的添加入口。它使用默认的 Git 克隆函数，完成真正的 marketplace 添加流程。

数据流：进去的是 Codex 主目录和添加请求。它把请求原样交给更通用的 add_marketplace_sync_with_cloner，并指定默认的 clone_git_source 作为下载 Git 仓库的方法。出来的是添加结果或错误。

调用关系：它被 add_marketplace 间接调用。它本身像一个薄薄的转接头，把普通调用转到可测试、可替换 Git 克隆器的核心函数。

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

fn add_marketplace_sync_with_cloner(
    codex_home: &Path,
    request: MarketplaceAddRequest,
    clone_source: F,
) -> Result<MarketplaceAddOutcome, MarketplaceAddError>

作用：这是本文件最核心的流程函数，真正决定一个 marketplace 怎么被添加。它同时处理本地目录、Git 仓库、重复添加、名称冲突、临时目录安装和配置写入。

数据流：进去的是 Codex 主目录、添加请求，以及一个“怎么克隆 Git”的函数。它先解析来源，拒绝不合规请求；然后创建安装目录，生成安装元数据，检查同一个来源是否已经登记过。若是本地目录，它验证目录内容后只写配置。若是 Git 来源，它创建暂存目录，把源码放进去，验证市场名称，算出安全的安装目录，搬到正式位置，再写配置。出来的是 MarketplaceAddOutcome；过程中会创建目录、复制或移动文件、写配置，失败时返回清楚的错误，配置写失败还会尝试回滚已安装目录。

调用关系：add_marketplace_sync 会调用它，测试也直接调用它并传入假的克隆函数，方便不用真的访问网络。它把具体小任务分给 marketplace_install_root、marketplace_staging_root、stage_marketplace_source、validate_marketplace_source_root、record_added_marketplace_entry 等函数，自己负责把这些步骤按正确顺序串起来。

调用图：调用 13 个内部函数（marketplace_install_root, ensure_marketplace_destination_is_inside_install_root, marketplace_staging_root, replace_marketplace_root, safe_marketplace_dir_name, from_source, find_marketplace_root_by_name, installed_marketplace_root_for_source, record_added_marketplace_entry, parse_marketplace_source (+3 more)）；被 5 处调用（add_marketplace_sync, add_marketplace_sync_installs_local_directory_source_and_updates_config, add_marketplace_sync_installs_marketplace_and_updates_config, add_marketplace_sync_rejects_sparse_checkout_for_local_directory_source, add_marketplace_sync_treats_existing_local_directory_source_as_already_added）；外部调用 8 个（new, Internal, InvalidRequest, is_openai_curated_marketplace_name, format!, create_dir_all, rename, matches!）。

fn add_marketplace_sync_installs_marketplace_and_updates_config() -> Result<()>

作用：这个测试确认：从 Git 来源添加 marketplace 时，系统会把内容安装到本地，并把来源信息写进配置文件。

数据流：它先创建临时 Codex 主目录和一份假的 marketplace 源目录，再用一个假的克隆函数把源目录复制到目标位置。然后调用 add_marketplace_sync_with_cloner。最后检查结果里的市场名、来源显示、是否不是重复添加，以及安装目录和配置文件内容是否符合预期。

调用关系：这是核心安装流程的“远程来源”测试。它直接调用 add_marketplace_sync_with_cloner，并借助 write_marketplace_source 准备假市场、copy_dir_all 模拟 Git 克隆。

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

fn add_marketplace_sync_installs_local_directory_source_and_updates_config() -> Result<()>

作用：这个测试确认：如果 marketplace 来源是本地目录，系统不会复制它，而是直接把这个目录登记到配置里。

数据流：它创建临时目录，写入一份假的 marketplace，然后把这个本地路径作为来源传入。假的 Git 克隆函数如果被调用就会直接报错。调用结束后，它检查返回的安装路径就是原本的本地目录，正式安装目录里没有复制品，并确认配置里写的是 local 来源。

调用关系：它覆盖 add_marketplace_sync_with_cloner 的本地目录分支。通过让克隆函数 panic，它证明本地来源不会走 Git 下载流程。

调用图：调用 2 个内部函数（add_marketplace_sync_with_cloner, from_absolute_path）；外部调用 7 个（new, new, assert!, assert_eq!, write_marketplace_source, read_to_string, from_str）。

fn add_marketplace_sync_rejects_sparse_checkout_for_local_directory_source() -> Result<()>

作用：这个测试确认：本地目录来源不能使用 sparse checkout 参数。因为 sparse checkout 是 Git 才有的“只取部分文件”能力，本地目录没有这个概念。

数据流：它准备一个本地 marketplace，然后在请求里故意加入 sparse 路径。调用核心添加函数后，它期待拿到错误，并检查错误文字是否说明 sparse 只支持 Git 来源。同时它确认配置文件没有被创建，说明失败时没有留下登记记录。

调用关系：它测试 add_marketplace_sync_with_cloner 一开始的请求校验。这个测试不应该触发 Git 克隆，也不应该改写配置。

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

fn add_marketplace_sync_treats_existing_local_directory_source_as_already_added() -> Result<()>

作用：这个测试确认：同一个本地 marketplace 添加第二次时，不会被当成冲突，而是返回“已经添加过”。

数据流：它准备一个本地 marketplace，用同一个请求调用核心添加函数两次。第一次应当是新添加，第二次应当标记 already_added 为 true，并且两次返回的安装路径一致。

调用关系：它验证 add_marketplace_sync_with_cloner 对重复来源的处理。这个场景依赖已写入的安装元数据，让第二次调用能认出“这是同一个来源”。

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

fn write_marketplace_source(source: &Path, marker: &str) -> std::io::Result<()>

作用：这是测试用的造数据工具，用来快速生成一个看起来合法的 marketplace 目录。

数据流：进去的是目标目录和一个标记字符串。它在目标目录里创建 marketplace 需要的文件夹，写入 marketplace.json、插件 plugin.json，以及一个 marker.txt。出来没有业务结果，但磁盘上多了一套测试用市场文件。

调用关系：多个测试先调用它来准备假 marketplace。它不参与正式产品流程，只服务测试，让测试不用手写一大堆重复文件准备代码。

调用图：外部调用 3 个（join, create_dir_all, write）。

fn copy_dir_all(source: &Path, destination: &Path) -> std::io::Result<()>

作用：这是测试用的递归复制工具，用来把一个目录完整复制到另一个目录。测试用它模拟 Git 克隆后的文件落地效果。

数据流：进去的是源目录和目标目录。它先创建目标目录，再逐个读取源目录里的文件和子目录；遇到子目录就继续递归复制，遇到普通文件就复制文件。出来没有单独返回数据，但目标目录会变成源目录的一份拷贝。

调用关系：它主要被远程来源安装测试里的假克隆函数使用。这样测试可以验证安装流程，而不需要真的连 GitHub 或执行 git 命令。

调用图：外部调用 5 个（join, copy_dir_all, copy, create_dir_all, read_dir）。

fn git_remote_revision(
    source: &str,
    ref_name: Option<&str>,
    timeout: Duration,
) -> Result<String, String>

作用：查出 Git 远端仓库里某个分支、标签或 HEAD 当前对应的完整提交号。这样升级流程可以知道自己到底要安装哪一版，而不是只拿到一个会变化的名字。

数据流：输入是仓库地址 source、可选的 ref_name（比如分支名、标签名或提交号）和超时时间。它先看 ref_name 是否已经是 40 位完整 Git 提交号；如果是，就直接返回。否则它运行 git ls-remote 去远端查询，把输出第一行按制表符拆开，取前面的提交号；如果输出为空、格式不对或命令失败，就返回说明原因的错误文字。

调用关系：它由 upgrade_configured_git_marketplace 在升级 Git 类型 marketplace 时调用。它自己把创建 Git 命令的事交给 git_command，把执行和超时交给 run_git_command_with_timeout，把成功检查交给 ensure_git_success，并用 is_full_git_sha 避免对已经明确的提交号再查远端。

调用图：调用 4 个内部函数（ensure_git_success, git_command, is_full_git_sha, run_git_command_with_timeout）；被 1 处调用（upgrade_configured_git_marketplace）；外部调用 2 个（from_utf8_lossy, format!）。

fn clone_git_source(
    source: &str,
    ref_name: Option<&str>,
    sparse_paths: &[String],
    destination: &Path,
    timeout: Duration,
) -> Result<String, String>

作用：把指定 Git 仓库下载到本地目录，并切到需要的分支、标签或提交。它还支持“稀疏检出”，也就是只拿仓库里的某些路径，避免下载不需要的内容。

数据流：输入是仓库地址、可选版本名、要保留的路径列表、目标目录和超时时间。它先把目标路径整理成 Git 能接受的形式。如果没有指定稀疏路径，就普通 clone，必要时 checkout 到指定版本，然后读取当前提交号返回。如果指定了稀疏路径，它会先用不检出文件的方式克隆，再设置 sparse-checkout，最后 checkout 到目标版本，并返回最终工作区的提交号。过程中任何 Git 命令失败都会变成带上下文的错误。

调用关系：它由 upgrade_configured_git_marketplace 调用，是实际把代码搬到本地的主流程。它反复使用 git_command 创建命令，用 run_git_command_with_timeout 执行，用 ensure_git_success 判断成败，用 git_path_arg 处理路径兼容性，最后交给 git_worktree_revision 确认克隆出来的真实版本。

调用图：调用 5 个内部函数（ensure_git_success, git_command, git_path_arg, git_worktree_revision, run_git_command_with_timeout）；被 1 处调用（upgrade_configured_git_marketplace）。

fn git_worktree_revision(destination: &Path, timeout: Duration) -> Result<String, String>

作用：读取本地 Git 工作目录当前指向的提交号。克隆或切换版本之后，用它确认“现在这个目录里到底是哪一版代码”。

数据流：输入是本地仓库目录和超时时间。它在该目录里运行 git rev-parse HEAD，检查命令是否成功，然后把标准输出转成文字并去掉空白；如果结果为空，就返回错误，否则返回提交号字符串。

调用关系：它只被 clone_git_source 调用，位于下载流程的最后一步。它仍然通过 git_command 生成 Git 命令，通过 run_git_command_with_timeout 避免卡死，通过 ensure_git_success 统一处理失败。

调用图：调用 3 个内部函数（ensure_git_success, git_command, run_git_command_with_timeout）；被 1 处调用（clone_git_source）；外部调用 1 个（from_utf8_lossy）。

fn is_full_git_sha(value: &str) -> bool

作用：判断一段文字是不是完整的 Git 提交号。完整提交号通常是 40 个十六进制字符，也就是 0-9 和 a-f/A-F。

数据流：输入是一段字符串。它检查长度是否正好为 40，并且每个字符是不是十六进制字符；满足就返回 true，不满足就返回 false，不修改任何外部东西。

调用关系：它被 git_remote_revision 用在最开头。这样如果调用者已经给了明确的提交号，就不必再联网执行 git ls-remote。测试 tests::full_git_sha_ref_is_already_a_remote_revision 会验证这个判断。

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

fn git_command() -> Command

作用：创建一个统一配置好的 git 命令模板。它让后续所有 Git 调用都从系统路径里找 git，并且尽量不弹出交互式提示。

数据流：它不需要输入。它创建 Command::new("git")，并设置两个环境变量：GIT_OPTIONAL_LOCKS=0 用来减少可选锁带来的干扰，GIT_TERMINAL_PROMPT=0 用来禁止终端里询问用户名密码；最后返回这个还没执行的命令对象。

调用关系：git_remote_revision、clone_git_source 和 git_worktree_revision 都用它来起步创建 Git 命令。测试 tests::git_command_uses_path_lookup_with_stable_noninteractive_env 会检查它确实使用 git 名称查找，并带上稳定的非交互环境设置。

调用图：被 4 处调用（clone_git_source, git_remote_revision, git_worktree_revision, git_command_uses_path_lookup_with_stable_noninteractive_env）；外部调用 1 个（new）。

fn git_path_arg(path: &Path) -> PathBuf

作用：把本地路径转换成适合传给 git 命令的路径参数。它主要是为 Windows 上一种特殊长路径格式兜底，避免 Git 看不懂。

数据流：输入是一个 Path。普通系统上它直接复制这个路径返回；Windows 上它会先把路径转成文字，尝试去掉类似 \\?\ 这样的特殊前缀，如果能去掉就返回改写后的路径，否则返回原路径。

调用关系：它被 clone_git_source 在克隆前调用，用来准备目标目录参数。在 Windows 或测试环境下，它会把具体的前缀处理交给 strip_windows_verbatim_path_prefix。

调用图：调用 1 个内部函数（strip_windows_verbatim_path_prefix）；被 1 处调用（clone_git_source）；外部调用 2 个（to_path_buf, to_string_lossy）。

fn strip_windows_verbatim_path_prefix(path: &str) -> Option<String>

作用：去掉 Windows 路径里的“verbatim”前缀，也就是类似 \\?\ 的特殊写法，让路径更像 Git 通常能识别的样子。

数据流：输入是一段路径文字。它先检查是否以 \\?\ 开头；没有就返回 None，表示不用改。有的话会去掉这个前缀；如果后面是 UNC 网络路径格式，还会改回 \\server\share 这种常见写法；最后返回改好的路径文字。

调用关系：它被 git_path_arg 使用，是 Windows 路径兼容的小零件。相关测试 tests::strips_windows_verbatim_disk_prefix_for_git、tests::strips_windows_verbatim_unc_prefix_for_git 和 tests::leaves_non_verbatim_path_without_rewrite 分别检查磁盘路径、网络路径和无需改写的路径。

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

fn run_git_command_with_timeout(
    command: &mut Command,
    context: &str,
    timeout: Duration,
) -> Result<Output, String>

作用：运行一个外部 Git 命令，并保证它不会无限卡住。超时后它会杀掉进程，并把错误输出一起写进错误信息里，方便排查。

数据流：输入是准备好的 Command、这次命令的人类可读说明 context，以及超时时间。它启动子进程，关闭标准输入，收集标准输出和标准错误；然后每 100 毫秒查看进程是否结束。正常结束就返回 Output；如果启动、等待或轮询失败就返回错误；如果超过时间还没结束，就杀掉进程，读取 stderr，并返回“某某命令超时”的错误。

调用关系：git_remote_revision、clone_git_source 和 git_worktree_revision 都把实际执行 Git 的工作交给它。它是这个文件里的安全阀，保证网络慢、认证卡住或 Git 异常时，升级流程不会永远挂在那里。

调用图：被 3 处调用（clone_git_source, git_remote_revision, git_worktree_revision）；外部调用 8 个（from_millis, null, piped, from_utf8_lossy, stdin, format!, sleep, now）。

fn ensure_git_success(output: &Output, context: &str) -> Result<(), String>

作用：检查 Git 命令的退出状态是不是成功，并把失败原因整理成好懂的错误信息。

数据流：输入是 Git 命令的 Output 和本次命令的 context。它先看退出状态是否成功；成功就返回 Ok。失败时，它读取 stderr；如果 stderr 为空，就只报告状态码，如果不为空，就把状态码和 Git 输出的错误文字一起返回。

调用关系：git_remote_revision、clone_git_source 和 git_worktree_revision 在每次 Git 命令执行完后都会调用它。run_git_command_with_timeout 只负责“命令跑完没跑完”，而它负责判断“跑完的结果是不是成功”。

调用图：被 3 处调用（clone_git_source, git_remote_revision, git_worktree_revision）；外部调用 2 个（from_utf8_lossy, format!）。

fn full_git_sha_ref_is_already_a_remote_revision()

作用：测试完整 Git 提交号的识别规则是否正确。它确保 40 位十六进制字符串会被当成明确版本，而普通分支名或短号不会被误判。

数据流：输入是测试里写死的几个字符串。它调用 is_full_git_sha 做判断，然后用断言确认完整提交号返回 true，main 和短提交号返回 false；测试不产生业务输出，只在失败时让测试框架报错。

调用关系：这是 is_full_git_sha 的单元测试。它保护 git_remote_revision 的快捷路径，避免未来改动导致已经明确的提交号还被拿去查远端。

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

fn git_command_uses_path_lookup_with_stable_noninteractive_env()

作用：测试 git_command 创建的命令是否符合预期：使用系统里的 git，并设置好不弹交互提示的环境变量。

数据流：它调用 git_command 得到一个命令对象，然后检查程序名是 git，检查 GIT_OPTIONAL_LOCKS 和 GIT_TERMINAL_PROMPT 的值都是 0，并确认没有额外改写 PATH。结果通过断言表达，断言失败就说明命令模板被破坏了。

调用关系：它直接覆盖 git_command，并使用 tests::command_env 读取命令对象里的环境变量。这个测试能防止 Git 调用在自动升级时突然需要人工输入或找 git 的方式发生意外变化。

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

fn strips_windows_verbatim_disk_prefix_for_git()

作用：测试 Windows 普通磁盘路径里的 \\?\ 前缀会被正确去掉。这样 C 盘这类路径传给 Git 时更稳妥。

数据流：输入是测试里写死的 \\?\C:\... 路径。它调用 strip_windows_verbatim_path_prefix，期待得到 C:\... 形式的路径文字；如果结果不同，断言失败。

调用关系：这是 strip_windows_verbatim_path_prefix 的测试之一，间接保护 git_path_arg 在 Windows 上给 clone_git_source 准备路径参数的行为。

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

fn strips_windows_verbatim_unc_prefix_for_git()

作用：测试 Windows 网络共享路径里的特殊前缀会被改成常见 UNC 路径格式。UNC 可以理解为类似 \\服务器\共享目录 的网络路径。

数据流：输入是 \\?\UNC\server\share\marketplace 形式的路径。它调用 strip_windows_verbatim_path_prefix，期待输出 \\server\share\marketplace；不同就让断言失败。

调用关系：这是 strip_windows_verbatim_path_prefix 的网络路径测试。它确保 git_path_arg 不只照顾本机磁盘路径，也照顾网络共享目录。

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

fn leaves_non_verbatim_path_without_rewrite()

作用：测试普通 Windows 路径不会被乱改。只有带特殊前缀的路径才应该被处理。

数据流：输入是 C:\Users\alice 这种普通路径。它调用 strip_windows_verbatim_path_prefix，期待得到 None，意思是“不需要改写”；如果返回了别的内容，断言失败。

调用关系：这是 strip_windows_verbatim_path_prefix 的边界测试。它防止路径清理逻辑过度积极，影响 git_path_arg 传给 Git 的正常路径。

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

fn command_env(
        command: &'a std::process::Command,
        name: &str,
    ) -> Option<Option<&'a OsStr>>

作用：在测试里读取 Command 对象上某个环境变量的设置。它是测试辅助函数，不参与实际升级流程。

数据流：输入是一个 Command 引用和环境变量名字。它遍历命令对象里显式设置过的环境变量，找到名字匹配的那一项并返回它的值；找不到就返回 None。

调用关系：它被 tests::git_command_uses_path_lookup_with_stable_noninteractive_env 使用，用来检查 git_command 设置了哪些环境变量。它只是测试工具，不会被生产代码调用。

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

fn all_succeeded(&self) -> bool

作用：这个小方法用来快速判断这次市场升级是不是全都成功了。只要错误列表是空的，它就认为没有失败。

数据流：进去的是一次升级结果对象，里面有已选择的市场、已升级路径和错误列表。它只看错误列表有没有内容，不改任何数据。出来的是一个布尔值：true 表示没有错误，false 表示至少有一个市场升级失败。

调用关系：它通常在外层流程拿到 ConfiguredMarketplaceUpgradeOutcome 之后使用，用来决定要不要向用户报告失败，或者继续后面的步骤。它不调用别的函数，也不触发升级。

fn configured_git_marketplace_names(config_layer_stack: &ConfigLayerStack) -> Vec<String>

作用：这个函数列出当前配置里所有 Git 来源的插件市场名字。外层可以用它告诉用户“哪些市场会参与自动升级”。

数据流：进去的是配置层叠对象，也就是系统把默认配置、用户配置等合在一起后的视图。它先取出 Git 市场列表，再只留下名字，并按字母顺序排好。出来的是一个干净、有序的名字列表。

调用关系：它把真正读取和筛选配置的活交给 configured_git_marketplaces。调用图里显示，upgrade_configured_marketplaces_for_config 会用它来了解配置里有哪些 Git 市场。

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

fn upgrade_configured_git_marketplaces(
    codex_home: &Path,
    config_layer_stack: &ConfigLayerStack,
    marketplace_name: Option<&str>,
) -> ConfiguredMarketplaceUpgradeOutcome

作用：这是批量升级入口：根据配置找到要升级的 Git 市场，可以升级全部，也可以只升级指定名字的一个。它会把成功和失败都收集起来，而不是遇到一个失败就让整个流程崩掉。

数据流：进去的是 Codex 的家目录、配置层叠对象，以及可选的市场名字。它读取配置、筛选目标市场、算出安装根目录，然后逐个调用单个市场升级函数。出来的是 ConfiguredMarketplaceUpgradeOutcome：包含选中了哪些市场、哪些目录真的升级了、哪些市场报错；同时它可能会改动磁盘上的市场目录和用户 config.toml。

调用关系：它是外层 upgrade_configured_marketplaces_for_config 调进来的主干流程。它先用 configured_git_marketplaces 找目标，再用 marketplace_install_root 定位安装位置，最后把每个市场交给 upgrade_configured_git_marketplace 做实际下载、验证和启用。

调用图：调用 3 个内部函数（configured_git_marketplaces, marketplace_install_root, upgrade_configured_git_marketplace）；被 1 处调用（upgrade_configured_marketplaces_for_config）；外部调用 2 个（new, default）。

fn marketplace_install_root(codex_home: &Path) -> PathBuf

作用：这个函数统一规定自动安装的插件市场放在哪里。这样其他代码不用各自拼路径，避免装到不同地方。

数据流：进去的是 Codex 家目录路径。它在后面接上固定目录“.tmp/marketplaces”。出来的是市场安装根目录路径，不会创建目录，也不会访问磁盘。

调用关系：它被 upgrade_configured_git_marketplaces 调用，用来给后续每个市场升级提供共同的安装位置。真正创建目录和写文件是在后面的升级函数里做。

调用图：被 1 处调用（upgrade_configured_git_marketplaces）；外部调用 1 个（join）。

fn configured_git_marketplaces(
    config_layer_stack: &ConfigLayerStack,
) -> Vec<ConfiguredGitMarketplace>

作用：这个函数从用户配置里挑出“来源类型是 Git”的插件市场，并整理成内部好用的格式。没有配置、配置格式不对，都会安全地返回空列表或跳过，并记录警告。

数据流：进去的是配置层叠对象。它读取生效的用户配置，找 marketplaces 这一段，把它转换成市场配置表，再过滤出 Git 来源的条目并排序。出来的是 ConfiguredGitMarketplace 列表，里面包含名字、仓库地址、分支或标签、只下载哪些路径、上次版本号等信息；它不修改配置文件。

调用关系：它是“配置变成升级任务”的入口，被 configured_git_marketplace_names 用来列名字，也被 upgrade_configured_git_marketplaces 用来决定真正要升级哪些市场。遇到坏配置时，它只发出 warn! 警告，不把整个升级流程打断。

调用图：调用 1 个内部函数（effective_user_config）；被 2 处调用（configured_git_marketplace_names, upgrade_configured_git_marketplaces）；外部调用 2 个（new, warn!）。

fn configured_git_marketplace_from_config(
    name: String,
    marketplace: MarketplaceConfig,
) -> Option<ConfiguredGitMarketplace>

作用：这个函数把单个市场配置翻译成内部的 Git 市场记录。它会排除不是 Git 来源的市场，也会拒绝没有仓库地址的 Git 市场。

数据流：进去的是市场名字和一份 MarketplaceConfig。它拆出来源类型、仓库地址、版本引用、稀疏路径和上次版本号；如果来源不是 Git，就返回 None；如果是 Git 但没有 source 地址，也返回 None 并写警告。出来的是 Some(ConfiguredGitMarketplace) 或 None。

调用关系：它是配置解析里的小转换器。read_configured_git_marketplace 会用它把刚从 config.toml 读出的单个市场重新转成可比较的内部记录，用来确认升级过程中配置没有被别人改掉。

调用图：被 1 处调用（read_configured_git_marketplace）；外部调用 1 个（warn!）。

fn upgrade_configured_git_marketplace(
    codex_home: &Path,
    install_root: &Path,
    marketplace: &ConfiguredGitMarketplace,
) -> Result<Option<AbsolutePathBuf>, String>

作用：这是单个 Git 插件市场升级的核心流程。它负责检查远程版本、下载、验证、写安装记录、切换目录，并更新用户配置。

数据流：进去的是 Codex 家目录、安装根目录和一个市场的内部配置。它先验证市场名能安全当目录名使用，再问远程 Git 仓库当前版本号；如果本地清单存在、版本号一样、安装元数据也匹配，就直接返回 Ok(None)。否则它创建临时目录，克隆仓库内容，验证下载来的目录确实是合法市场且名字正确，写入安装元数据，然后在启用前再次确认用户配置没变，最后记录新版本到 config.toml 并把临时目录激活成正式目录。出来的是 Ok(Some(绝对路径)) 表示真的升级了，Ok(None) 表示无需升级，Err(文字) 表示失败原因；过程中会读写磁盘、访问 Git、修改配置。

调用关系：它由 upgrade_configured_git_marketplaces 逐个调用。它把不同步骤分给专门函数：git_remote_revision 查远程版本，clone_git_source 下载，validate_marketplace_root 验证市场目录，installed_marketplace_metadata_matches 判断本地是否已匹配，write_installed_marketplace_metadata 写安装记录，activate_marketplace_root 做最终切换；在切换前还通过 ensure_configured_git_marketplace_unchanged 防止配置被并发改动。

调用图：调用 8 个内部函数（find_marketplace_manifest_path, validate_marketplace_root, activate_marketplace_root, installed_marketplace_metadata_matches, write_installed_marketplace_metadata, clone_git_source, git_remote_revision, try_from）；被 1 处调用（upgrade_configured_git_marketplaces）；外部调用 6 个（join, now, validate_plugin_segment, format!, create_dir_all, new）。

fn ensure_configured_git_marketplace_unchanged(
    codex_home: &Path,
    expected: &ConfiguredGitMarketplace,
) -> Result<(), String>

作用：这个函数是升级前最后一道保险：确认用户配置里的这个市场，和开始升级时看到的是同一份。它防止“下载过程中用户改了配置，但旧任务还把结果写回去”的问题。

数据流：进去的是 Codex 家目录和预期的市场配置。它重新读取当前 config.toml 里的同名 Git 市场；如果当前配置和预期完全一样，就返回成功；如果变了、删了，或不再是 Git 市场，就返回错误文字。它只读取配置，不写入文件。

调用关系：upgrade_configured_git_marketplace 在激活新目录、写回配置之前会调用它。它把读取当前配置的细节交给 read_configured_git_marketplace，自己只负责把“当前”和“预期”做比较并给出清楚的失败原因。

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

fn read_configured_git_marketplace(
    codex_home: &Path,
    marketplace_name: &str,
) -> Result<Option<ConfiguredGitMarketplace>, String>

作用：这个函数直接从用户的 config.toml 里读取某个市场当前的 Git 配置。它用于获得“此刻磁盘上的真实配置”，而不是之前缓存的配置视图。

数据流：进去的是 Codex 家目录和市场名字。它拼出 config.toml 路径，读取文本；文件不存在就返回 Ok(None)，读取失败或 TOML 格式解析失败就返回错误。解析成功后，它找 marketplaces 表，取出指定市场，并用 configured_git_marketplace_from_config 转成内部记录。出来的是 Ok(Some(市场记录))、Ok(None) 或 Err(错误文字)；它不修改磁盘。

调用关系：它被 ensure_configured_git_marketplace_unchanged 调用，用来在升级临门一脚前重新核对用户配置。它负责底层的文件读取和 TOML 解析，解析出的单个市场再交给 configured_git_marketplace_from_config 判断是不是有效的 Git 市场。

调用图：调用 1 个内部函数（configured_git_marketplace_from_config）；被 1 处调用（ensure_configured_git_marketplace_unchanged）；外部调用 4 个（join, format!, read_to_string, from_str）。

async fn remove_marketplace(
    codex_home: PathBuf,
    request: MarketplaceRemoveRequest,
) -> Result<MarketplaceRemoveOutcome, MarketplaceRemoveError>

作用：这是给外部调用的异步删除入口。有人发起“移除 marketplace”命令时，会走这里；它把可能较慢的磁盘操作放到后台阻塞任务里做，避免拖慢异步主流程。

数据流：输入是 Codex 的用户目录路径和要删除的 marketplace 名字 → 它把这些交给同步版本 remove_marketplace_sync 去真正检查配置、删配置、删文件 → 输出成功结果，或把后台任务失败包装成 MarketplaceRemoveError::Internal 错误。

调用关系：它由 run_remove 在执行删除命令时调用。它自己不直接碰配置和文件，而是通过 spawn_blocking 把活交给 remove_marketplace_sync，这样命令层可以继续用异步方式等待结果。

调用图：被 1 处调用（run_remove）；外部调用 1 个（spawn_blocking）。

fn remove_marketplace_sync(
    codex_home: &Path,
    request: MarketplaceRemoveRequest,
) -> Result<MarketplaceRemoveOutcome, MarketplaceRemoveError>

作用：这是实际执行删除的核心函数。它负责确认名字安全、删除配置记录、删除本地安装目录，并判断这次删除到底有没有删到东西。

数据流：输入是用户目录和删除请求 → 它取出 marketplace_name，先用 validate_plugin_segment 检查名字是否合法；再用 marketplace_install_root 算出本地安装位置；接着调用 remove_user_marketplace_config 删除 config.toml 里的记录；如果大小写不匹配就报错；然后调用 remove_marketplace_root 删除安装目录或文件 → 输出 MarketplaceRemoveOutcome，里面说明删的是哪个 marketplace，以及是否删掉了本地安装根目录；如果既没配置也没安装，就返回“找不到”的请求错误。

调用关系：remove_marketplace 会把实际工作交给它。它是整个删除流程的中轴：上游给它请求，下游它分别调用配置删除函数和 remove_marketplace_root。测试函数也直接调用它，验证各种正常和异常场景。

调用图：调用 2 个内部函数（marketplace_install_root, remove_marketplace_root）；被 6 处调用（remove_marketplace_sync_keeps_installed_root_when_config_removal_fails, remove_marketplace_sync_rejects_case_mismatched_configured_name, remove_marketplace_sync_rejects_unknown_marketplace, remove_marketplace_sync_removes_config_and_installed_root, remove_marketplace_sync_removes_file_installed_root, remove_marketplace_sync_removes_inline_config_entry）；外部调用 4 个（remove_user_marketplace_config, validate_plugin_segment, InvalidRequest, format!）。

fn remove_marketplace_root(root: &Path) -> Result<Option<AbsolutePathBuf>, MarketplaceRemoveError>

作用：这个函数只负责删除本地安装位置。它不管配置文件，只看指定路径是否存在，存在就把它删掉，并告诉调用者删掉的是哪个绝对路径。

数据流：输入是一个可能存在的安装路径 → 如果路径不存在，直接返回 None；如果存在，先转成 AbsolutePathBuf（绝对路径，避免含糊的相对位置），再读取路径信息；如果它是目录就递归删除整个目录，如果是普通文件就删除文件 → 输出 Some(被删除的绝对路径)，或在检查、转换、删除失败时返回内部错误。

调用关系：它只被 remove_marketplace_sync 调用，是删除流程里的“清扫本地文件”零件。remove_marketplace_sync 先处理配置，再叫它清理安装根目录。

调用图：调用 1 个内部函数（try_from）；被 1 处调用（remove_marketplace_sync）；外部调用 5 个（exists, to_path_buf, remove_dir_all, remove_file, symlink_metadata）。

fn remove_marketplace_sync_removes_config_and_installed_root()

作用：这个测试确认最常见的成功情况：配置里有记录，本地也有安装目录时，删除后两边都干净了。

数据流：它先创建临时用户目录，写入一个 debug marketplace 配置，再造出对应安装目录和文件 → 调用 remove_marketplace_sync → 检查返回结果里的名字和被删路径正确，同时确认 config.toml 不再包含 debug 配置，安装目录也不存在了。

调用关系：这是对 remove_marketplace_sync 的主成功路径测试。它会用 record_user_marketplace 准备配置，用 marketplace_install_root 找安装位置，然后验证核心删除函数确实同时清理配置和磁盘。

调用图：调用 2 个内部函数（marketplace_install_root, remove_marketplace_sync）；外部调用 7 个（new, assert!, assert_eq!, record_user_marketplace, create_dir_all, read_to_string, write）。

fn remove_marketplace_sync_rejects_unknown_marketplace()

作用：这个测试确认：如果用户要删的 marketplace 既没有配置，也没有安装目录，程序会明确报错，而不是假装成功。

数据流：它创建一个空的临时用户目录 → 调用 remove_marketplace_sync 删除 debug → 得到错误 → 检查错误文字是“debug 没有配置或安装”。

调用关系：它直接测试 remove_marketplace_sync 的兜底判断：配置没删到，本地目录也没删到时，应该返回 InvalidRequest，而不是静默通过。

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

fn remove_marketplace_sync_rejects_case_mismatched_configured_name()

作用：这个测试确认大小写必须完全一致。比如配置里是 debug，用户输入 Debug，程序会拒绝，避免在大小写敏感和不敏感的系统上产生误删。

数据流：它先写入名为 debug 的配置，并创建 debug 安装目录 → 调用 remove_marketplace_sync 时故意传入 Debug → 得到错误 → 再检查安装目录还在，配置也还在。

调用关系：它验证 remove_marketplace_sync 处理 remove_user_marketplace_config 返回的 NameCaseMismatch 分支时，会停止流程，不会继续调用删除安装目录造成副作用。

调用图：调用 2 个内部函数（marketplace_install_root, remove_marketplace_sync）；外部调用 6 个（new, assert!, assert_eq!, record_user_marketplace, create_dir_all, read_to_string）。

fn remove_marketplace_sync_keeps_installed_root_when_config_removal_fails()

作用：这个测试确认一个安全保护：如果配置文件坏了，配置删除失败，就不能继续删本地安装目录。

数据流：它创建临时用户目录，写入一份格式错误的 config.toml，再创建 debug 安装目录 → 调用 remove_marketplace_sync → 得到包含“删除配置失败”的错误 → 检查安装目录仍然存在。

调用关系：它测试 remove_marketplace_sync 的顺序很关键：先删配置，配置失败就立刻返回错误，不会把工作交给 remove_marketplace_root。

调用图：调用 2 个内部函数（marketplace_install_root, remove_marketplace_sync）；外部调用 4 个（new, assert!, create_dir_all, write）。

fn remove_marketplace_sync_removes_file_installed_root()

作用：这个测试确认安装根位置就算不是目录、而是一个异常的普通文件，也能被删除。这样可以清理损坏或不完整的安装状态。

数据流：它先写入 debug 配置，然后在本该是安装目录的位置写入一个普通文件 → 调用 remove_marketplace_sync → 检查返回结果包含被删路径，文件已经不存在，配置记录也被移除了。

调用关系：它覆盖 remove_marketplace_root 的文件删除分支。remove_marketplace_sync 调用它时，不要求安装根必须是正常目录，也能清掉坏状态。

调用图：调用 2 个内部函数（marketplace_install_root, remove_marketplace_sync）；外部调用 7 个（new, assert!, assert_eq!, record_user_marketplace, create_dir_all, read_to_string, write）。

fn remove_marketplace_sync_removes_inline_config_entry()

作用：这个测试确认配置写成内联形式时也能删除。内联形式就是把 marketplace 配置写在一行里的紧凑写法。

数据流：它手动写入一段内联 marketplace 配置，再创建对应安装目录 → 调用 remove_marketplace_sync → 检查返回名字和删除路径正确，安装目录没了，配置文件里也不再出现 debug。

调用关系：它验证 remove_marketplace_sync 依赖的 remove_user_marketplace_config 不只会删普通表格形式，也能处理内联配置；核心删除流程不需要关心配置具体写法。

调用图：调用 2 个内部函数（marketplace_install_root, remove_marketplace_sync）；外部调用 6 个（new, assert!, assert_eq!, create_dir_all, read_to_string, write）。

fn io(context: &'static str, source: io::Error) -> Self

作用：把普通的文件读写错误包装成这个文件统一使用的远程插件安装错误。这样上层看到错误时，会知道是哪一步文件操作出了问题。

数据流：进去的是一段固定的错误背景说明和系统返回的 io 错误 → 函数把它们装进 RemotePluginBundleInstallError::Io → 出来的是带上下文的统一错误值，不改动文件。

调用关系：它是很多磁盘操作失败时的“翻译器”。创建目录、读取清单、写 JSON、重命名目录等地方都会借它把底层错误变成安装流程能理解的错误。

fn validate_remote_plugin_bundle(
    remote_plugin_id: &str,
    remote_marketplace_name: &str,
    plugin_name: &str,
    release_version: Option<&str>,
    bundle_download_url: Option<&str>,
    ap

作用：把后端返回的远程插件信息先验一遍，确认插件名、版本号和下载地址都能安全使用。只有通过这里的检查，后面才会真的下载和安装。

数据流：进去的是远程插件编号、市场名、插件名、可选版本号、可选下载地址和可选应用清单 → 它生成本地插件 ID，清理并检查版本号，解析下载地址，并确认地址协议安全 → 出来的是 ValidatedRemotePluginBundle，也就是一份可以继续执行的安装计划；如果缺字段或不安全，就返回明确错误。

调用关系：它通常在远程安装响应、同步远程已安装插件、检出共享插件时先被调用。它会借 validate_plugin_version_segment 检查版本号，借 is_allowed_bundle_download_url 判断链接能不能用。后续的下载安装函数只接收它产出的“已验证包信息”。

调用图：调用 4 个内部函数（allow_test_loopback_http_bundle_downloads, is_allowed_bundle_download_url, validate_plugin_version_segment, new）；被 10 处调用（remote_plugin_install_response, sync_remote_installed_plugin_bundles_once, checkout_remote_plugin_share, install_preserves_non_global_bundle_manifest_metadata, valid_remote_plugin_bundle, validate_remote_plugin_bundle_rejects_invalid_release_version, validate_remote_plugin_bundle_rejects_missing_download_url, validate_remote_plugin_bundle_rejects_missing_release_version, validate_remote_plugin_bundle_rejects_unsupported_download_url_scheme, validate_remote_plugin_bundle_uses_detail_name_for_local_plugin_id）；外部调用 1 个（parse）。

fn allow_test_loopback_http_bundle_downloads() -> bool

作用：判断测试环境里是否临时允许从本机 HTTP 地址下载插件包。平时返回 false，避免普通明文 HTTP 下载带来风险。

数据流：进去没有参数 → 在调试构建下读取环境变量 CODEX_TEST_ALLOW_HTTP_REMOTE_PLUGIN_BUNDLE_DOWNLOADS → 如果值是 1 就返回 true，否则返回 false；不修改任何状态。

调用关系：它被 validate_remote_plugin_bundle 和 download_remote_plugin_bundle_with_limit 调用。前者用它判断初始下载地址，后者用它判断跳转后的最终地址，保证测试方便但正式场景安全。

调用图：被 2 处调用（download_remote_plugin_bundle_with_limit, validate_remote_plugin_bundle）；外部调用 1 个（var）。

fn is_allowed_bundle_download_url(url: &Url, allow_loopback_http: bool) -> bool

作用：判断一个插件包下载地址是否允许使用。规则很简单：HTTPS 永远允许；HTTP 只在测试开关打开且地址是本机时允许。

数据流：进去的是一个 URL 和是否允许本机 HTTP 的布尔值 → 它查看 URL 的协议，如果是 HTTP 还会检查是不是 localhost 或回环 IP → 出来 true 或 false，不产生副作用。

调用关系：它是下载地址安全检查的核心小门卫。validate_remote_plugin_bundle 用它挡住后端给来的坏地址，download_remote_plugin_bundle_with_limit 用它挡住重定向后的坏地址。

调用图：调用 1 个内部函数（is_loopback_url）；被 2 处调用（download_remote_plugin_bundle_with_limit, validate_remote_plugin_bundle）；外部调用 1 个（scheme）。

fn is_loopback_url(url: &Url) -> bool

作用：判断一个 URL 是否指向本机。这里的“本机”包括 localhost、127.0.0.1 这类 IPv4 回环地址和 ::1 这类 IPv6 回环地址。

数据流：进去的是一个 URL → 它读取主机名部分并分类判断 → 出来 true 表示只访问本机，false 表示不是本机或没有主机名。

调用关系：它只被 is_allowed_bundle_download_url 使用。作用是让测试时的 HTTP 例外足够窄，只放行本机地址，而不是放行互联网上的明文 HTTP。

调用图：被 1 处调用（is_allowed_bundle_download_url）；外部调用 1 个（host）。

async fn download_and_install_remote_plugin_bundle(
    codex_home: PathBuf,
    bundle: ValidatedRemotePluginBundle,
) -> Result<PluginInstallResult, RemotePluginBundleInstallError>

作用：完成“下载远程插件包并安装”的完整动作。它把网络下载和本地解压安装串起来，是上层安装远程插件时会调用的主入口之一。

数据流：进去的是 Codex 主目录路径和已验证的插件包信息 → 它先按大小限制下载压缩包字节，再把耗时的解压和安装放到阻塞任务里执行 → 出来的是 PluginInstallResult，里面说明装到了哪里、版本是什么；失败则返回安装错误。

调用关系：它被远程插件安装响应和远程同步流程调用。它先交给 download_remote_plugin_bundle_with_limit 做网络下载，再交给 install_remote_plugin_bundle 做本地落盘和注册。

调用图：调用 1 个内部函数（download_remote_plugin_bundle_with_limit）；被 2 处调用（remote_plugin_install_response, sync_remote_installed_plugin_bundles_once）；外部调用 1 个（spawn_blocking）。

async fn download_and_extract_remote_plugin_bundle_to_path(
    bundle: ValidatedRemotePluginBundle,
    destination: AbsolutePathBuf,
) -> Result<AbsolutePathBuf, RemotePluginBundleInstallError>

作用：把远程插件包下载下来，并解压到指定目录，但不走普通安装仓库流程。它适合“检出”共享插件这种需要放到某个固定位置的场景。

数据流：进去的是已验证的插件包信息和目标绝对路径 → 它下载压缩包，再在后台阻塞任务中解压、检查并移动到目标目录 → 出来的是目标路径；如果目标已存在或包不合规就报错。

调用关系：它被 checkout_remote_plugin_share 使用。它和安装入口一样先下载，但后半段交给 extract_remote_plugin_bundle_to_path，而不是 PluginStore。

调用图：调用 1 个内部函数（download_remote_plugin_bundle_with_limit）；被 1 处调用（checkout_remote_plugin_share）；外部调用 1 个（spawn_blocking）。

async fn download_remote_plugin_bundle_with_limit(
    bundle_download_url: &str,
    max_bytes: u64,
) -> Result<Vec<u8>, RemotePluginBundleInstallError>

作用：真正执行 HTTP 请求下载插件压缩包，并严格限制超时、地址安全和文件大小。这样远端服务器就不能无限拖延或塞一个特别大的文件过来。

数据流：进去的是下载 URL 和最大字节数 → 它创建网络客户端，发 GET 请求，检查重定向后的最终地址和 HTTP 状态；失败状态会读取有限长度的错误正文；成功时读取正文并持续检查大小 → 出来是完整的压缩包字节数组。

调用关系：它被两个高层函数共用：一个用于下载后安装，一个用于下载后检出。它内部调用 read_response_body_with_limit 读响应体，并使用 is_allowed_bundle_download_url 复查跳转后的地址。

调用图：调用 4 个内部函数（allow_test_loopback_http_bundle_downloads, is_allowed_bundle_download_url, read_response_body_with_limit, build_reqwest_client）；被 2 处调用（download_and_extract_remote_plugin_bundle_to_path, download_and_install_remote_plugin_bundle）；外部调用 1 个（from_utf8_lossy）。

async fn read_response_body_with_limit(
    mut response: Response,
    url: &str,
    max_bytes: u64,
) -> Result<Vec<u8>, RemotePluginBundleInstallError>

作用：一边读取网络响应内容，一边检查是否超过大小上限。它防止服务器谎报或不报文件大小时，程序把内存吃爆。

数据流：进去的是网络响应、对应 URL 和最大字节数 → 它先看响应头里的 content-length，如果有就先检查；然后一块一块读取内容，每读一块都累加长度并检查 → 出来是读完的字节数组，或在超限/读取失败时返回错误。

调用关系：它只由 download_remote_plugin_bundle_with_limit 调用。这个函数把“怎么安全读完整响应体”的细活从下载主流程里拆出来。

调用图：调用 1 个内部函数（enforce_download_size_limit）；被 1 处调用（download_remote_plugin_bundle_with_limit）；外部调用 3 个（new, chunk, content_length）。

fn enforce_download_size_limit(
    url: &str,
    bytes: u64,
    max_bytes: u64,
) -> Result<(), RemotePluginBundleInstallError>

作用：检查某个下载当前大小是否超过允许上限。它是下载大小限制的最小判断单元。

数据流：进去的是 URL、当前字节数和最大字节数 → 它比较当前值和上限 → 如果没超过就返回成功；超过就返回 DownloadTooLarge 错误，不修改任何数据。

调用关系：read_response_body_with_limit 在读响应头和每个数据块后都会调用它。测试 download_size_limit_rejects_oversized_bundle 也直接调用它，确认超限会被拦住。

调用图：被 2 处调用（read_response_body_with_limit, download_size_limit_rejects_oversized_bundle）。

fn install_remote_plugin_bundle(
    codex_home: PathBuf,
    bundle: ValidatedRemotePluginBundle,
    bundle_bytes: Vec<u8>,
) -> Result<PluginInstallResult, RemotePluginBundleInstallError>

作用：把已经下载好的插件压缩包解开、检查、必要时修正清单，然后安装进本地插件仓库。它是本地落盘安装的核心流程。

数据流：进去的是 Codex 主目录、已验证插件信息和压缩包字节 → 它创建临时解压目录，解压压缩包，确认根目录有 plugin.json，按需要覆盖版本和应用清单，再创建 PluginStore 并安装指定版本 → 出来是安装结果，同时本地插件目录会发生变化。

调用关系：download_and_install_remote_plugin_bundle 下载完成后会把活交给它。它继续调用 extract_plugin_bundle_tar_gz、find_extracted_plugin_root、prepare_extracted_remote_plugin_root，最后交给 PluginStore 写入正式插件仓库。多个测试会直接调用它验证坏包和元数据行为。

调用图：调用 5 个内部函数（extract_plugin_bundle_tar_gz, find_extracted_plugin_root, prepare_extracted_remote_plugin_root, try_new, try_from）；被 3 处调用（install_preserves_non_global_bundle_manifest_metadata, install_rejects_bundle_without_standard_plugin_root, install_rejects_invalid_tar_gz_bundle）；外部调用 3 个（join, create_dir_all, new）。

fn extract_remote_plugin_bundle_to_path(
    bundle: ValidatedRemotePluginBundle,
    bundle_bytes: Vec<u8>,
    destination: AbsolutePathBuf,
) -> Result<AbsolutePathBuf, RemotePluginBundleInstallErr

作用：把插件压缩包解压并移动到一个指定目录，用于检出插件而不是安装到仓库。它会确认目标目录不能已存在，避免覆盖用户已有文件。

数据流：进去的是已验证插件信息、压缩包字节和目标绝对路径 → 它检查目标不存在并创建父目录，在临时目录解压，确认有合法 plugin.json，并检查清单里的 name 和远程插件名一致 → 最后把临时目录改名成目标目录，返回该路径。

调用关系：download_and_extract_remote_plugin_bundle_to_path 在后台任务里调用它。它复用 extract_plugin_bundle_tar_gz 和 find_extracted_plugin_root 的安全解压检查，也会读取插件清单确认身份。

调用图：调用 4 个内部函数（load_plugin_manifest, extract_plugin_bundle_tar_gz, find_extracted_plugin_root, as_path）；外部调用 5 个（InvalidBundle, format!, create_dir_all, rename, new）。

fn prepare_extracted_remote_plugin_root(
    plugin_root: &Path,
    bundle: &ValidatedRemotePluginBundle,
) -> Result<(), RemotePluginBundleInstallError>

作用：在插件安装前，对刚解压出来的插件根目录做必要的修正。主要是全局远程市场的插件，需要以服务端返回的信息为准。

数据流：进去的是解压后的插件根目录和已验证插件信息 → 如果市场不是全局远程市场，它什么都不改；如果是，就覆盖 plugin.json 里的 version，并在有应用清单时写入应用清单 → 出来是成功或错误，可能会改写插件目录里的 JSON 文件。

调用关系：install_remote_plugin_bundle 在确认包根目录后调用它。它把具体写清单的事交给 overwrite_plugin_manifest_version 和 overwrite_plugin_app_manifest。

调用图：调用 2 个内部函数（overwrite_plugin_app_manifest, overwrite_plugin_manifest_version）；被 1 处调用（install_remote_plugin_bundle）。

fn overwrite_plugin_manifest_version(
    plugin_root: &Path,
    plugin_version: &str,
) -> Result<(), RemotePluginBundleInstallError>

作用：把插件自己的 plugin.json 里的 version 字段改成后端确认的版本。这样本地安装记录不会被压缩包里可能过旧或不一致的版本误导。

数据流：进去的是插件根目录和目标版本号 → 它找到 plugin.json，读成文本并解析成 JSON，确认 JSON 顶层是对象，然后写入新的 version 字段 → 最后用 write_json_file 保存回文件。

调用关系：它只由 prepare_extracted_remote_plugin_root 调用。它依赖 find_plugin_manifest_path 找清单文件，依赖 write_json_file 做最终格式化写入。

调用图：调用 1 个内部函数（write_json_file）；被 1 处调用（prepare_extracted_remote_plugin_root）；外部调用 5 个（String, find_plugin_manifest_path, InvalidBundle, read_to_string, from_str）。

fn overwrite_plugin_app_manifest(
    plugin_root: &Path,
    app_manifest: &JsonValue,
) -> Result<(), RemotePluginBundleInstallError>

作用：把后端给的应用清单写进插件目录。应用清单可以理解成插件暴露哪些应用能力的说明书。

数据流：进去的是插件根目录和要写入的 JSON 值 → 它先尝试从插件清单里找到应用清单路径，找不到就默认用根目录下的 .app.json → 然后把 JSON 写到这个位置。

调用关系：它只由 prepare_extracted_remote_plugin_root 调用。真正创建目录、格式化 JSON 和写文件的细节交给 write_json_file。

调用图：调用 2 个内部函数（load_plugin_manifest, write_json_file）；被 1 处调用（prepare_extracted_remote_plugin_root）。

fn write_json_file(
    path: &Path,
    value: &JsonValue,
    context: &'static str,
) -> Result<(), RemotePluginBundleInstallError>

作用：把一个 JSON 值漂亮地写成文件，并确保父目录存在。它统一处理写清单文件时的格式和错误包装。

数据流：进去的是目标路径、JSON 值和错误背景说明 → 它检查路径有父目录，创建父目录，把 JSON 转成带缩进的文本并补一个换行，最后写入文件 → 出来是成功或带上下文的错误。

调用关系：overwrite_plugin_manifest_version 和 overwrite_plugin_app_manifest 都靠它落盘。它把“怎么安全、整齐地写 JSON 文件”这件小事集中到一处。

调用图：被 2 处调用（overwrite_plugin_app_manifest, overwrite_plugin_manifest_version）；外部调用 4 个（parent, create_dir_all, write, to_vec_pretty）。

fn extract_plugin_bundle_tar_gz(
    bytes: &[u8],
    destination: &Path,
) -> Result<(), RemotePluginBundleInstallError>

作用：用默认安全限制解压远程插件的 tar.gz 压缩包。tar.gz 可以理解成一种常见的“打包再压缩”的文件格式。

数据流：进去的是压缩包字节和目标目录 → 它把默认的最大解压总大小传给更底层函数 → 出来是解压成功或错误，目标目录可能新增文件。

调用关系：安装、检出和多个解压测试都会调用它。它只是便捷入口，真正限制大小和转换错误的是 extract_plugin_bundle_tar_gz_with_limits。

调用图：调用 1 个内部函数（extract_plugin_bundle_tar_gz_with_limits）；被 5 处调用（extract_remote_plugin_bundle_to_path, install_remote_plugin_bundle, extraction_preserves_executable_permissions, extraction_rejects_tar_path_traversal, extraction_supports_gnu_long_name_entries）。

fn extract_plugin_bundle_tar_gz_with_limits(
    bytes: &[u8],
    destination: &Path,
    max_total_bytes: u64,
) -> Result<(), RemotePluginBundleInstallError>

作用：按指定的最大解压总大小解开插件压缩包，并把底层解包错误翻译成远程插件安装错误。

数据流：进去的是压缩包字节、目标目录和最大解压字节数 → 它调用 unpack_plugin_bundle_tar_gz 做实际解包 → 如果底层说太大、文件错误或包不合法，它转换成当前文件的错误类型；成功则目标目录得到解压文件。

调用关系：extract_plugin_bundle_tar_gz 调用它使用默认上限，测试 extraction_rejects_total_size_over_limit 直接调用它验证自定义上限。它连接了通用解包模块和远程插件安装流程。

调用图：调用 1 个内部函数（unpack_plugin_bundle_tar_gz）；被 2 处调用（extract_plugin_bundle_tar_gz, extraction_rejects_total_size_over_limit）。

fn find_extracted_plugin_root(
    extraction_root: &Path,
) -> Result<PathBuf, RemotePluginBundleInstallError>

作用：确认解压目录本身就是标准插件根目录，而不是里面又套了一层目录。标准插件根目录必须能找到 plugin.json。

数据流：进去的是解压根目录路径 → 它检查这个路径下能否发现插件清单 → 能发现就返回这个路径；不能发现就返回“没有标准插件根”的错误。

调用关系：安装和检出都在解压后调用它。它内部交给 is_standard_plugin_root 判断标准性，测试也用它确认嵌套插件根会被拒绝。

调用图：调用 1 个内部函数（is_standard_plugin_root）；被 3 处调用（extract_remote_plugin_bundle_to_path, install_remote_plugin_bundle, find_extracted_plugin_root_rejects_nested_plugin_root）；外部调用 2 个（to_path_buf, InvalidBundle）。

fn is_standard_plugin_root(path: &Path) -> bool

作用：判断某个目录是不是标准插件根目录。它的标准就是能在这里找到插件清单文件 plugin.json。

数据流：进去的是目录路径 → 它调用 find_plugin_manifest_path 查找清单 → 找到返回 true，找不到返回 false。

调用关系：它只服务于 find_extracted_plugin_root，是一个很小的判断函数。这样以后标准变化时，根目录判断可以集中修改。

调用图：被 1 处调用（find_extracted_plugin_root）；外部调用 1 个（find_plugin_manifest_path）。

fn validate_remote_plugin_bundle_uses_detail_name_for_local_plugin_id()

作用：测试远程插件验证时，会用后端详情里的插件名生成本地插件 ID。它防止把远程编号误当成本地插件名。

数据流：进去的是一组合法的测试远程插件信息 → 调用 validate_remote_plugin_bundle → 检查生成的插件名、市场名、版本号和下载地址都符合预期。

调用关系：它直接覆盖 validate_remote_plugin_bundle 的成功路径。这个测试保证上层安装流程拿到的是可用于本地仓库的插件身份。

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

fn validate_remote_plugin_bundle_rejects_missing_release_version()

作用：测试缺少发布版本时必须被拒绝。没有版本号就无法可靠记录装的是哪一版。

数据流：进去的是没有 release_version 的测试数据 → 调用 validate_remote_plugin_bundle → 期待返回 MissingReleaseVersion 错误。

调用关系：它验证 validate_remote_plugin_bundle 对必填字段的检查。这样远程响应不完整时不会继续进入下载和安装。

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

fn validate_remote_plugin_bundle_rejects_invalid_release_version()

作用：测试非法版本号会被拒绝。这里用类似 ../1.2.3 的危险字符串，防止版本号被拿去拼路径时出问题。

数据流：进去的是带非法版本字符串的测试数据 → 调用 validate_remote_plugin_bundle → 期待返回 InvalidReleaseVersion 错误。

调用关系：它验证 validate_remote_plugin_bundle 会使用版本段校验函数。这个测试守住了远程输入进入本地文件系统前的一道关。

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

fn validate_remote_plugin_bundle_rejects_missing_download_url()

作用：测试缺少下载地址时必须被拒绝。没有地址就无法下载插件包，也不该进入后续流程。

数据流：进去的是没有 bundle_download_url 的测试数据 → 调用 validate_remote_plugin_bundle → 期待返回 MissingBundleDownloadUrl 错误。

调用关系：它覆盖 validate_remote_plugin_bundle 的下载地址必填检查。它保证上层不会拿到一份无法执行的安装计划。

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

fn validate_remote_plugin_bundle_rejects_unsupported_download_url_scheme()

作用：测试普通 HTTP 下载地址会被拒绝。这样正式安装不会通过未加密连接下载插件。

数据流：进去的是 http://example.com 这样的测试地址 → 调用 validate_remote_plugin_bundle → 期待返回 UnsupportedBundleDownloadUrlScheme 错误。

调用关系：它验证 validate_remote_plugin_bundle 和 URL 安全判断的配合。这个测试保护远程插件下载必须走安全协议的规则。

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

fn download_size_limit_rejects_oversized_bundle()

作用：测试下载大小超过上限时会报错。它确保大小限制不是摆设。

数据流：进去的是当前大小 5、上限 4 的测试值 → 调用 enforce_download_size_limit → 期待返回 DownloadTooLarge 错误。

调用关系：它直接测试 enforce_download_size_limit。这个小函数被网络响应读取流程反复调用，所以它的正确性很关键。

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

fn install_rejects_invalid_tar_gz_bundle()

作用：测试安装流程会拒绝根本不是 tar.gz 的内容。坏压缩包不应该被当成插件继续处理。

数据流：进去的是临时 Codex 主目录、合法插件信息和一段普通文本字节 → 调用 install_remote_plugin_bundle → 期待得到读取压缩包失败相关错误。

调用关系：它直接覆盖 install_remote_plugin_bundle 的解包失败路径。valid_remote_plugin_bundle 提供合法安装计划，tempdir 提供隔离目录。

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

fn install_rejects_bundle_without_standard_plugin_root()

作用：测试压缩包里没有标准插件根目录时会被拒绝。也就是没有 plugin.json 的包不能安装。

数据流：进去的是只包含 README.md 的测试压缩包 → 调用 install_remote_plugin_bundle → 期待错误信息说明没有标准插件根。

调用关系：它验证 install_remote_plugin_bundle 解压后会调用 find_extracted_plugin_root。tar_gz_bytes 用来现场造一个测试包。

调用图：调用 1 个内部函数（install_remote_plugin_bundle）；外部调用 4 个（assert!, tar_gz_bytes, valid_remote_plugin_bundle, tempdir）。

fn install_preserves_non_global_bundle_manifest_metadata()

作用：测试非全局远程市场的插件，安装时不会被后端应用清单覆盖包内清单。换句话说，某些来源的包内元数据要原样保留。

数据流：进去的是非全局市场的插件信息、后端版本和后端应用清单，以及包内自己的 plugin.json 和 .app.json → 调用 install_remote_plugin_bundle → 再读回已安装文件，确认包内 version 和 app 内容没有被改写，但安装结果版本仍使用后端版本。

调用关系：它覆盖 prepare_extracted_remote_plugin_root 的“不处理非全局市场”分支。它同时使用 validate_remote_plugin_bundle、tar_gz_bytes 和 JSON 读取比较来确认最终落盘结果。

调用图：调用 2 个内部函数（install_remote_plugin_bundle, validate_remote_plugin_bundle）；外部调用 6 个（assert_eq!, tar_gz_bytes, from_str, json!, read_to_string, tempdir）。

fn find_extracted_plugin_root_uses_local_manifest_discovery()

作用：测试只要解压根目录下有本地插件清单，就能被识别为插件根目录。它确认清单发现规则能正常工作。

数据流：进去的是一个临时目录，测试先在里面创建 .codex-plugin/plugin.json → 然后检查找到的插件根目录等于这个临时目录 → 输出是断言通过或失败。

调用关系：它间接验证 find_extracted_plugin_root 依赖的清单发现规则。虽然函数清单里没有显示直接调用 find_extracted_plugin_root，但测试意图就是确认根目录识别行为。

调用图：外部调用 4 个（assert_eq!, create_dir_all, write, tempdir）。

fn find_extracted_plugin_root_rejects_nested_plugin_root()

作用：测试插件根目录如果藏在解压目录的子目录里，会被拒绝。这个格式要求让远程包结构更简单、更可控。

数据流：进去的是一个临时解压根目录，测试在其子目录 linear 里放 plugin.json → 调用 find_extracted_plugin_root 检查外层目录 → 期待返回错误。

调用关系：它直接验证 find_extracted_plugin_root 不会递归接受嵌套插件根。这样安装流程不会因为包结构多套一层而装错位置。

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

fn extraction_rejects_tar_path_traversal()

作用：测试解压时会拒绝路径穿越。路径穿越就是压缩包里写 ../evil.txt，试图把文件解到目标目录外面。

数据流：进去的是一个带原始危险路径的测试 tar.gz 字节和临时目标目录 → 调用 extract_plugin_bundle_tar_gz → 期待错误里提到逃出解压根目录。

调用关系：它验证 extract_plugin_bundle_tar_gz 背后的安全解包逻辑。tar_gz_bytes_with_raw_path 用来构造普通打包 API 不容易生成的危险路径。

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

fn extraction_rejects_total_size_over_limit()

作用：测试解压后的总文件大小超过上限时会被拒绝。这样小压缩包也不能膨胀成特别大的目录。

数据流：进去的是两个 4 字节文件组成的压缩包和 6 字节总上限 → 调用 extract_plugin_bundle_tar_gz_with_limits → 期待 ExtractedBundleTooLarge 错误。

调用关系：它直接测试 extract_plugin_bundle_tar_gz_with_limits 的大小限制。这个能力保护安装流程不会被“压缩炸弹”拖垮。

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

fn extraction_supports_gnu_long_name_entries()

作用：测试解压逻辑支持 GNU tar 的长文件名记录。也就是路径很长的文件仍然能正确解出来。

数据流：进去的是一个带很长路径文件的测试压缩包 → 调用 extract_plugin_bundle_tar_gz 解压 → 再读目标文件，确认内容是 long。

调用关系：它验证 extract_plugin_bundle_tar_gz 不只处理最简单的 tar 格式，也能兼容常见的长路径扩展。

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

fn extraction_preserves_executable_permissions()

作用：在 Unix 系统上，测试解压后可执行文件权限会被保留。比如脚本原本是 755，解出来仍然能执行。

数据流：进去的是包含 plugin.json 和 bin/helper 脚本的测试压缩包，其中脚本权限是 0o755 → 调用 extract_plugin_bundle_tar_gz → 读取解压后文件权限并断言仍是 755。

调用关系：它验证 extract_plugin_bundle_tar_gz 背后的解包过程会保留 Unix 权限。这个测试只在 Unix 平台编译运行。

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

fn valid_remote_plugin_bundle() -> ValidatedRemotePluginBundle

作用：为测试创建一份合法的已验证远程插件包信息。它避免每个测试都重复写同样的样板数据。

数据流：进去没有参数 → 它调用 validate_remote_plugin_bundle，传入固定的合法远程插件编号、市场、插件名、版本和 HTTPS 下载地址 → 出来是 ValidatedRemotePluginBundle。

调用关系：安装相关测试会调用它来获得一个可信的 bundle。它把测试重点从“构造数据”转回到“验证安装行为”。

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

fn tar_gz_bytes(entries: &[(&str, &[u8], u32)]) -> Vec<u8>

作用：为测试现场生成一个 tar.gz 压缩包。调用者只要给出文件路径、内容和权限，就能得到压缩包字节。

数据流：进去的是一组测试文件条目 → 它创建 gzip 编码器和 tar 构建器，把每个条目交给 append_tar_entry 写入，最后调用 finish_tar_gz 收尾 → 出来是完整压缩包字节数组。

调用关系：多个安装和解压测试用它构造正常或特殊的插件包。它把测试数据制作的细节藏起来，让测试更容易读。

调用图：外部调用 6 个（new, new, default, append_tar_entry, finish_tar_gz, new）。

fn tar_gz_bytes_with_raw_path(path: &str, contents: &[u8], mode: u32) -> Vec<u8>

作用：为测试生成一个带原始路径字段的 tar.gz 包，主要用于构造危险路径。普通打包函数可能会自动帮忙规范路径，所以这里手写头部。

数据流：进去的是原始路径、文件内容和权限 → 它手工创建 tar 头，直接把路径字节塞进头部，再写内容、补齐块、写结束标记并完成 gzip → 出来是测试用压缩包字节。

调用关系：路径穿越测试调用它来制造 ../evil.txt 这种恶意条目。它服务于安全测试，不是正常安装流程的一部分。

调用图：外部调用 5 个（new, new, default, new_gnu, vec!）。

fn append_tar_entry(
        tar: &mut tar::Builder<W>,
        entry_type: tar::EntryType,
        path: &str,
        contents: &[u8],
        mode: u32,
    )

作用：往测试用 tar 包里追加一个文件条目。它统一设置文件类型、大小、权限和校验信息。

数据流：进去的是 tar 构建器、条目类型、路径、内容和权限 → 它创建 tar 头并写入条目 → 成功时 tar 构建器多了一个文件；失败时直接 panic，让测试中止。

调用关系：tar_gz_bytes 为每个测试文件调用它。它是测试压缩包生成流水线中的“写一个文件”步骤。

调用图：外部调用 3 个（append_data, panic!, new_gnu）。

fn finish_tar_gz(tar: tar::Builder<GzEncoder<Vec<u8>>>) -> Vec<u8>

作用：结束测试 tar.gz 包的写入，并取出最终字节。它负责把 tar 和 gzip 两层都收尾。

数据流：进去的是一个 tar 构建器 → 它先取回里面的 gzip 编码器，再完成 gzip 压缩 → 出来是 Vec<u8> 字节数组；如果收尾失败就 panic。

调用关系：tar_gz_bytes 在所有条目写完后调用它。它是测试压缩包生成的最后一步。

调用图：外部调用 2 个（into_inner, panic!）。

fn changed_local_cache(&self) -> bool

作用：判断这次同步有没有真的改动本机插件缓存。有人会用它来决定是否需要通知系统刷新插件列表。

数据流：输入是一次同步的结果对象，里面有“新安装的插件”和“被删除的缓存插件”两份名单。它只检查这两份名单是不是为空；只要其中一份有内容，就返回 true，否则返回 false。它不改任何数据。

调用关系：maybe_start_remote_installed_plugin_bundle_sync 在后台同步结束后会看这个判断。如果本地缓存变了，并且外面提供了回调函数，它就触发回调，让其他部分知道插件状态需要刷新。

fn maybe_start_remote_installed_plugin_bundle_sync(
    codex_home: PathBuf,
    config: RemotePluginServiceConfig,
    auth: Option<CodexAuth>,
    on_local_cache_changed: Option<Arc<dyn Fn() + Send

作用：尝试启动一次远端插件同步，但不会硬启动：没登录就不做，同一个缓存目录已经在同步就不再开第二个。它适合在应用启动或插件服务准备好时悄悄跑后台刷新。

数据流：输入是 Codex 主目录、远端服务配置、可选登录信息，以及一个“本地缓存变化后要做什么”的回调。它先检查有没有登录信息，再用缓存根目录做一把“正在同步”的标记；标记成功后开一个异步后台任务。任务里真正调用 sync_remote_installed_plugin_bundles_once，结束后记录日志，必要时调用回调，最后清掉“正在同步”的标记。

调用关系：这是外部进入本文件同步流程的入口。它把防重复、后台运行、日志和结束清理串起来，真正的下载与清理工作交给 sync_remote_installed_plugin_bundles_once；开始前用 mark_remote_installed_plugin_bundle_sync_in_flight 占位，结束后用 clear_remote_installed_plugin_bundle_sync_in_flight 释放。

调用图：调用 4 个内部函数（clear_remote_installed_plugin_bundle_sync_in_flight, mark_remote_installed_plugin_bundle_sync_in_flight, remote_plugin_cache_root, sync_remote_installed_plugin_bundles_once）；外部调用 3 个（info!, spawn, warn!）。

async fn sync_remote_installed_plugin_bundles_once(
    codex_home: PathBuf,
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
) -> Result<RemoteInstalledPluginBundleSyncOutcome, R

作用：完整执行一次“远端已安装插件 → 本地缓存”的同步。它会拉远端列表、下载缺失或版本不同的插件，并删除本地过期缓存。

数据流：输入是 Codex 主目录、远端插件服务配置和登录信息。它先确认登录有效，然后并行查询全局、工作区、用户三个范围的已安装插件；接着打开本地插件仓库，逐个插件计算本地 ID，比较当前缓存版本。如果需要更新，就校验远端插件包信息，再下载安装。所有远端列表处理完后，它把“远端仍然安装的插件名单”交给清理函数，删除不在名单里的缓存。输出是一份结果：安装了哪些、删除了哪些缓存、哪些远端插件失败了。

调用关系：maybe_start_remote_installed_plugin_bundle_sync 会在后台任务里调用它。它自己像总调度员：登录校验交给 ensure_chatgpt_auth，远端列表交给 fetch_installed_plugins_for_scope_with_download_url，插件包检查和安装交给 remote_bundle 里的函数，最后把磁盘清理交给 remove_stale_remote_plugin_caches。

调用图：调用 4 个内部函数（download_and_install_remote_plugin_bundle, validate_remote_plugin_bundle, try_new, new）；被 1 处调用（maybe_start_remote_installed_plugin_bundle_sync）；外部调用 9 个（from_iter, new, clone, ensure_chatgpt_auth, fetch_installed_plugins_for_scope_with_download_url, remote_plugin_canonical_marketplace_name, spawn_blocking, try_join!, warn!）。

fn mark_remote_plugin_cache_mutation_in_flight(
    codex_home: &Path,
    marketplace_name: &str,
    plugin_name: &str,
) -> RemotePluginCacheMutationGuard

作用：标记某个远端插件缓存“正在被改动”。这样清理旧缓存时不会误删一个正在安装或更新的插件目录。

数据流：输入是 Codex 主目录、市场名和插件名。它先算出插件缓存根目录，再把“缓存根目录 + 市场名 + 插件名”组成一个键，放进全局记录表里；如果同一个插件被多处同时标记，它会把计数加一。输出是一个 RemotePluginCacheMutationGuard 守卫对象；这个对象活着，就表示改动还没结束。

调用关系：安装或修改远端插件缓存的代码可以在动手前调用它。remove_stale_remote_plugin_caches 清理时会通过 is_remote_plugin_cache_mutation_in_flight 查这张表；只要守卫还没释放，对应缓存就会被跳过。测试 stale_remote_plugin_cleanup_skips_cache_mutations_in_progress 专门验证了这个保护。

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

fn drop(&mut self)

作用：在“缓存改动守卫”离开作用范围时自动撤销标记。它保证不用手动写收尾代码，也能让清理任务知道改动已经结束。

数据流：输入是守卫对象自身保存的那个缓存键。它找到全局“正在改动”记录表，把对应计数减一；如果计数减到零，就把这条记录移除。输出没有返回值，但会改变全局记录表的状态。

调用关系：它是 Rust 的 Drop 自动清理机制，也就是对象销毁时自动运行。mark_remote_plugin_cache_mutation_in_flight 创建它；当调用方完成安装、更新，或者变量被 drop 掉时，它就解除保护。remove_stale_remote_plugin_caches 之后再检查时，就可以删除这个过期缓存了。

fn remove_stale_remote_plugin_caches(
    codex_home: &Path,
    installed_plugin_names_by_marketplace: &BTreeMap<String, BTreeSet<String>>,
) -> Result<Vec<String>, String>

作用：删除本机里已经不属于远端已安装列表的插件缓存。它防止磁盘里堆着旧插件，也防止系统继续看到不该存在的远端插件。

数据流：输入是 Codex 主目录，以及一张“每个远端市场现在仍安装哪些插件”的表。它依次检查几个固定的远端市场缓存目录；目录不存在就跳过。对每个缓存项，它看插件名是否还在已安装名单里；在就保留，不在就继续检查是否正在被改动。如果没有正在改动，它会按目录或文件删除，并把被删插件的本地 ID 记入结果。最后排序后返回删除名单；如果读目录、删文件等磁盘操作失败，就返回错误文字。

调用关系：sync_remote_installed_plugin_bundles_once 在下载和安装结束后，把远端最新名单交给它做收尾清理。它清理前会问 is_remote_plugin_cache_mutation_in_flight，避免和正在安装的任务打架。两个测试函数分别验证“正在改动时不删”和“过期市场缓存会被删、正确缓存会保留”。

调用图：调用 2 个内部函数（is_remote_plugin_cache_mutation_in_flight, new）；被 2 处调用（stale_remote_plugin_cleanup_removes_stale_marketplace_caches_and_keeps_canonical_cache, stale_remote_plugin_cleanup_skips_cache_mutations_in_progress）；外部调用 5 个（join, new, read_dir, remove_dir_all, remove_file）。

fn remote_plugin_cache_root(codex_home: &Path) -> PathBuf

作用：算出远端插件缓存的根目录。其他函数需要用同一个路径规则，才能判断和清理同一块地方。

数据流：输入是 Codex 主目录路径。它把固定的插件缓存目录名拼到这个主目录后面，输出完整的缓存根路径。它不读写磁盘，只做路径拼接。

调用关系：maybe_start_remote_installed_plugin_bundle_sync 用它生成同步去重用的键；mark_remote_plugin_cache_mutation_in_flight 和 is_remote_plugin_cache_mutation_in_flight 用它确保“正在改动”的记录指向同一缓存根目录；测试也用它检查去重逻辑。

调用图：被 4 处调用（is_remote_plugin_cache_mutation_in_flight, mark_remote_plugin_cache_mutation_in_flight, maybe_start_remote_installed_plugin_bundle_sync, remote_installed_plugin_sync_in_flight_dedupes_by_cache_root）；外部调用 1 个（join）。

fn is_remote_plugin_cache_mutation_in_flight(
    codex_home: &Path,
    marketplace_name: &str,
    plugin_name: &str,
) -> bool

作用：检查某个远端插件缓存现在是不是正在被安装或修改。清理任务靠它决定要不要暂时放过某个目录。

数据流：输入是 Codex 主目录、市场名和插件名。它先看全局“正在改动”记录表是否存在；不存在就说明没人正在改，返回 false。存在时，它用同样的路径规则组成键，到表里查有没有这条记录，有就返回 true，没有就返回 false。

调用关系：remove_stale_remote_plugin_caches 在准备删除某个过期缓存前会调用它。如果它说“正在改”，清理函数就跳过，等下一次再处理；它内部依赖 remote_plugin_cache_root 来保证路径判断一致。

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

fn mark_remote_installed_plugin_bundle_sync_in_flight(
    key: RemoteInstalledPluginBundleSyncKey,
) -> bool

作用：给某个插件缓存根目录打上“同步正在进行”的标记。它用来防止同一个地方同时跑两次远端插件同步。

数据流：输入是一个同步键，里面主要是插件缓存根目录。它把这个键放进全局集合；如果之前没有，插入成功并返回 true；如果已经有了，说明同步已经在跑，返回 false。它会修改全局同步状态集合。

调用关系：maybe_start_remote_installed_plugin_bundle_sync 在开后台任务前先调用它。只有它返回 true，后台同步才会启动；测试 remote_installed_plugin_sync_in_flight_dedupes_by_cache_root 验证了同一个缓存根目录会被去重。

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

fn clear_remote_installed_plugin_bundle_sync_in_flight(key: &RemoteInstalledPluginBundleSyncKey)

作用：清掉某个缓存根目录的“正在同步”标记。这样下一次同步请求才有机会正常启动。

数据流：输入是之前用于占位的同步键。它找到全局同步集合，把这个键移除；如果集合还没创建，就什么也不做。它没有返回值，只改变全局同步状态。

调用关系：maybe_start_remote_installed_plugin_bundle_sync 的后台任务结束时会调用它，作为收尾动作。测试 remote_installed_plugin_sync_in_flight_dedupes_by_cache_root 也直接调用它，确认清掉标记后可以再次启动同步。

调用图：被 2 处调用（maybe_start_remote_installed_plugin_bundle_sync, remote_installed_plugin_sync_in_flight_dedupes_by_cache_root）。

fn remote_installed_plugin_sync_in_flight_dedupes_by_cache_root()

作用：测试同一个插件缓存根目录不会同时启动两次同步。这个测试保护的是“后台同步去重”这条安全规则。

数据流：测试先创建一个临时 Codex 主目录，再用 remote_plugin_cache_root 算出同步键。第一次标记应该成功，第二次用同一个键标记应该失败；清掉标记后，再标记又应该成功。它最后再次清理标记，避免影响别的测试。

调用关系：它直接验证 mark_remote_installed_plugin_bundle_sync_in_flight 和 clear_remote_installed_plugin_bundle_sync_in_flight 的配合。这个行为正是 maybe_start_remote_installed_plugin_bundle_sync 防止重复后台任务的基础。

调用图：调用 2 个内部函数（clear_remote_installed_plugin_bundle_sync_in_flight, remote_plugin_cache_root）；外部调用 2 个（assert!, tempdir）。

fn stale_remote_plugin_cleanup_skips_cache_mutations_in_progress()

作用：测试清理旧缓存时，不会删掉正在被改动的插件缓存。它防的是“安装到一半被清理任务删掉”这种很糟糕的情况。

数据流：测试先在临时目录里造出一个看起来已经缓存好的插件文件，但远端已安装名单里不包含它，所以正常来说它该被删。然后它为这个插件创建两个改动守卫。第一次清理时，因为有守卫，文件还在；丢掉第一个守卫后，第二个还在，仍然不删；两个守卫都丢掉后，再清理就会删掉缓存，并返回被删除的插件 ID。

调用关系：它调用 mark_remote_plugin_cache_mutation_in_flight 制造“正在改动”的状态，再调用 remove_stale_remote_plugin_caches 观察清理结果。这个测试覆盖了计数式守卫和自动 drop 收尾的配合。

调用图：调用 2 个内部函数（mark_remote_plugin_cache_mutation_in_flight, remove_stale_remote_plugin_caches）；外部调用 7 个（from_iter, new, assert!, assert_eq!, create_dir_all, write, tempdir）。

fn stale_remote_plugin_cleanup_removes_stale_marketplace_caches_and_keeps_canonical_cache()

作用：测试清理函数会删掉已经过期的远端市场缓存，同时保留仍然属于当前远端安装名单的正确缓存。

数据流：测试在临时目录里造出三个缓存：一个“我创建的”插件、一个私有共享插件、一个当前仍安装的共享插件。它传入的已安装名单只包含那个当前仍安装的共享插件。调用清理函数后，前两个缓存应该被删除并出现在返回名单里，第三个缓存应该保留下来。

调用关系：它直接调用 remove_stale_remote_plugin_caches，验证这个清理函数能正确区分多个远端市场目录。这个结果也保证 sync_remote_installed_plugin_bundles_once 在同步结束后的收尾清理不会误删仍该存在的规范缓存。

调用图：调用 1 个内部函数（remove_stale_remote_plugin_caches）；外部调用 8 个（from_iter, from, new, assert!, assert_eq!, create_dir_all, write, tempdir）。

fn is_valid_remote_plugin_id(plugin_id: &str) -> bool

作用：检查远程插件编号是不是安全、合法。它只允许英文字母、数字和少数几个符号，避免把奇怪字符带进请求或文件路径里。

数据流：进去一个插件编号字符串 → 它逐个看字符是不是允许的，并且要求不能是空字符串 → 出来一个 true 或 false，表示能不能继续用。

调用关系：它是最基础的门卫函数。validate_remote_plugin_id 会用它生成正式错误；推荐插件筛选、插件分享和卸载响应等流程也会用它挡掉不合格编号。

调用图：被 7 处调用（plugin_share_checkout_response, plugin_share_delete_response, plugin_share_save_response, plugin_share_update_targets_response, plugin_uninstall_response, recommended_plugins_mode, validate_remote_plugin_id）。

fn validate_remote_plugin_id(plugin_id: &str) -> Result<(), JSONRPCErrorError>

作用：把“检查插件编号”包装成对外可返回的错误格式。有人要读取、安装或卸载远程插件前，会先用它确认编号没问题。

数据流：进去一个插件编号 → 它调用 is_valid_remote_plugin_id 判断 → 合法就返回成功，不合法就返回一个 JSON-RPC 错误，告诉调用方允许哪些字符。

调用关系：它站在接口入口附近。plugin_read_response、plugin_skill_read_response、remote_plugin_install_response、remote_plugin_uninstall_response 会先让它把关，再继续访问远程插件。

调用图：调用 1 个内部函数（is_valid_remote_plugin_id）；被 4 处调用（plugin_read_response, plugin_skill_read_response, remote_plugin_install_response, remote_plugin_uninstall_response）。

fn api_value(self) -> &'static str

作用：把代码里的插件范围转换成服务器 API 认识的文字，比如 GLOBAL、USER、WORKSPACE。这样请求参数不会写散、写错。

数据流：进去一个 RemotePluginScope 枚举值 → 它按范围选择对应的大写字符串 → 出来一个可直接放进网络请求的参数值。

调用关系：get_remote_plugin_list_page 和 get_remote_plugin_installed_page 在拼请求参数时会用它，把本地概念翻译给后端听。

调用图：被 2 处调用（get_remote_plugin_installed_page, get_remote_plugin_list_page）。

fn marketplace_name(self) -> &'static str

作用：把插件范围转换成本项目内部使用的市场名字。比如全局插件属于 OpenAI curated 远程市场，用户自建插件属于 created-by-me。

数据流：进去一个范围值 → 它查表式地选择对应市场的内部名称 → 出来一个稳定的市场标识字符串。

调用关系：这是范围到市场名称的翻译工具。虽然函数清单里没有列出直接调用者，它和同类方法一起保证各处使用同一套市场命名。

fn marketplace_display_name(self) -> &'static str

作用：给插件范围找一个适合展示给用户看的市场名称。它处理的是“人看得懂的名字”，不是内部编号。

数据流：进去一个范围值 → 它选择对应的展示名，比如 Created by me 或 Workspace Directory → 出来一段界面可显示的文字。

调用关系：build_remote_plugin_detail 会用它给插件详情补上市集展示名，让界面知道这个插件来自哪个分类。

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

fn from_marketplace_name(name: &str) -> Option<Self>

作用：根据市场名字反推出插件范围。它主要用来确认某个市场名是不是远程插件系统支持的。

数据流：进去一个市场名称字符串 → 它匹配已知的几个远程市场名 → 匹配成功就返回范围，失败就返回空。

调用关系：fetch_remote_plugin_skill_detail 会先用它验证市场名，不认识的市场就不继续请求技能详情。

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

fn remote_plugin_canonical_marketplace_name(
    plugin: &RemotePluginDirectoryItem,
) -> Result<&'static str, RemotePluginCatalogError>

作用：判断一个远程插件真正应该放在哪个市场桶里。尤其是工作区插件，要根据共享可见性决定是目录插件还是“别人分享给我”的插件。

数据流：进去一个服务器返回的插件目录项 → 它看插件范围；如果是工作区插件，还读取 discoverability（可发现性，也就是公开、私有或未列出）→ 出来规范的市场名称，或发现数据缺失时报错。

调用关系：它是很多转换函数的共同依据。build_remote_plugin_summary、插件详情、已安装缓存、发现列表和卸载流程都靠它统一分类，内部会调用 workspace_plugin_discoverability。

调用图：调用 1 个内部函数（workspace_plugin_discoverability）；被 5 处调用（build_remote_plugin_summary, fetch_remote_plugin_detail_with_download_url_option, remote_discoverable_plugin_from_directory_item, remote_installed_plugin_to_cache_entry, uninstall_remote_plugin）。

fn workspace_plugin_discoverability(
    plugin: &RemotePluginDirectoryItem,
) -> Result<RemotePluginShareDiscoverability, RemotePluginCatalogError>

作用：读取工作区插件的共享可见性，并在缺失时给出清楚错误。工作区插件没有这个字段，就无法判断该放在哪个列表里。

数据流：进去一个插件目录项 → 它取出 discoverability 字段 → 有值就返回，没值就返回“服务器响应不完整”的错误。

调用关系：remote_plugin_canonical_marketplace_name 和 remote_plugin_share_context 会调用它，因为这两处都需要知道工作区插件是公开、私有还是未列出。

调用图：被 2 处调用（remote_plugin_canonical_marketplace_name, remote_plugin_share_context）。

async fn fetch_remote_marketplaces(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    sources: &[RemoteMarketplaceSource],
    global_catalog_cache_path: Option<&Path>,
) -> Re

作用：拉取用户要看的远程插件市场列表。它会把服务器目录、已安装状态和共享插件合并成界面可以直接展示的市场分组。

数据流：进去服务配置、登录信息、要看的市场来源、可选缓存路径 → 它先确认登录，再按来源请求目录和安装列表，必要时读取或写入全球目录缓存，最后把插件合成市场对象 → 出来一组 RemoteMarketplace。

调用关系：plugin_list_response 会调用它来生成插件列表。它像总调度员，下面会叫 fetch_directory_plugins_for_scope、fetch_installed_plugins_for_scope、fetch_shared_workspace_plugins 和 build_remote_marketplace 干具体活。

调用图：调用 7 个内部函数（build_remote_marketplace, load_cached_global_directory_plugins, write_cached_global_directory_plugins, ensure_chatgpt_auth, fetch_directory_plugins_for_scope, fetch_installed_plugins_for_scope, fetch_shared_workspace_plugins）；被 1 处调用（plugin_list_response）；外部调用 3 个（new, iter, try_join!）。

async fn fetch_and_cache_global_remote_plugin_catalog(
    codex_home: &Path,
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
) -> Result<(), RemotePluginCatalogError>

作用：专门刷新全球远程插件目录缓存。这样下次启动或推荐工具需要插件目录时，可以先用本地副本，速度更快也更稳。

数据流：进去本地目录、服务配置和登录信息 → 它确认登录后向服务器拉全球插件目录 → 把结果写进缓存，成功时不返回具体数据。

调用关系：启动任务、缓存刷新循环和一些推荐插件流程会调用它。它内部只负责全球目录，具体请求交给 fetch_directory_plugins_for_scope，写文件交给 catalog_cache。

调用图：调用 3 个内部函数（write_cached_global_directory_plugins, ensure_chatgpt_auth, fetch_directory_plugins_for_scope）；被 4 处调用（expands_cached_remote_plugins_by_loaded_apps, maybe_start_plugin_startup_tasks_for_config, run_global_remote_catalog_cache_refresh_loop, list_tool_suggest_discoverable_plugins_includes_cached_remote_global_plugins）。

async fn fetch_recommended_plugins(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
) -> Result<RecommendedPluginsMode, RemotePluginCatalogError>

作用：向后端询问“推荐安装哪些远程插件”。推荐结果可能来自新接口，也可能被判定为继续走旧逻辑。

数据流：进去服务配置和登录信息 → 它确认登录，拼出 /ps/plugins/suggested 地址，带上认证头发送请求 → 解码响应后交给 recommended_plugins_mode 过滤整理，出来推荐模式。

调用关系：它是推荐插件网络请求的入口。它使用 authenticated_request 加认证，用 send_and_decode 收发和解析，最后让 recommended_plugins_mode 判断哪些推荐能用。

调用图：调用 5 个内部函数（authenticated_request, ensure_chatgpt_auth, recommended_plugins_mode, send_and_decode, build_reqwest_client）；外部调用 1 个（format!）。

fn recommended_plugins_mode(response: RecommendedPluginsResponse) -> RecommendedPluginsMode

作用：把服务器推荐插件响应整理成安全、有限、去重的推荐列表。如果服务器没有明确开启新推荐，就退回旧模式。

数据流：进去推荐接口响应 → 它检查开关、插件编号、名称长度、可用状态、安装策略，并去重 app id 和插件配置 id → 出来 Legacy 或最多 50 个推荐插件。

调用关系：fetch_recommended_plugins 拿到原始响应后会调用它。它会借助 is_valid_remote_plugin_id 和 non_empty_string 清洗数据，遇到无效插件名会记录警告而不是让整个流程失败。

调用图：调用 3 个内部函数（is_valid_remote_plugin_id, non_empty_string, new）；被 1 处调用（fetch_recommended_plugins）；外部调用 3 个（new, new, warn!）。

fn has_cached_global_remote_plugin_catalog(
    codex_home: &Path,
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
) -> bool

作用：快速判断本地有没有可用的全球远程插件目录缓存。它适合在列表接口里决定要不要走缓存相关路径。

数据流：进去本地目录、服务配置和可选登录信息 → 它先确认登录可用，再尝试读取缓存 → 出来 true 或 false。

调用关系：plugin_list_response 会用它判断缓存是否存在。它不发网络请求，只调用 ensure_chatgpt_auth 和 catalog_cache 的读取函数。

调用图：调用 2 个内部函数（load_cached_global_directory_plugins, ensure_chatgpt_auth）；被 1 处调用（plugin_list_response）。

fn cached_global_remote_discoverable_plugins(
    codex_home: &Path,
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
) -> Vec<RemoteDiscoverablePlugin>

作用：从本地缓存里取出可用于“发现/推荐”的全球远程插件。它让系统不用联网也能拿到一部分可展示的插件信息。

数据流：进去本地目录、服务配置和登录信息 → 它读取缓存，把每个目录项转换成更轻量的可发现插件；转换失败的条目会被跳过并记录警告 → 出来一个插件列表。

调用关系：cached_global_remote_discoverable_plugins_for_config 会调用它。它依赖缓存模块提供原始目录，再用本文件里的转换逻辑整理成推荐可用的形状。

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

async fn fetch_openai_curated_remote_collection_marketplace(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
) -> Result<Option<RemoteMarketplace>, RemotePluginCatalogError>

作用：拉取 OpenAI 精选远程插件集合。它不是拿整个全球市场，而是请求特定 collection，用来展示更聚焦的插件列表。

数据流：进去服务配置和登录信息 → 它确认登录后同时拉精选目录和已安装状态 → 交给 build_remote_marketplace 合并，出来一个可能为空的市场。

调用关系：plugin_list_response 会在需要精选远程集合时调用它。它的收尾工作由 build_remote_marketplace 完成。

调用图：调用 2 个内部函数（build_remote_marketplace, ensure_chatgpt_auth）；被 1 处调用（plugin_list_response）；外部调用 1 个（try_join!）。

fn build_remote_marketplace(
    name: &str,
    display_name: &str,
    directory_plugins: Vec<RemotePluginDirectoryItem>,
    installed_plugins: Vec<RemotePluginInstalledItem>,
    include_installed

作用：把“服务器目录插件”和“用户已安装插件”合成一个市场。它负责给每个插件标上是否已安装、是否启用。

数据流：进去市场名、展示名、目录插件列表、已安装插件列表和是否包含仅安装插件的开关 → 它按插件远程 id 对齐两边数据，逐个生成摘要，必要时补上只在安装列表里的插件 → 出来一个市场对象，没插件就返回空。

调用关系：fetch_remote_marketplaces 和 fetch_openai_curated_remote_collection_marketplace 都用它做最后组装。它把单个插件摘要的细节交给 build_remote_plugin_summary。

调用图：被 2 处调用（fetch_openai_curated_remote_collection_marketplace, fetch_remote_marketplaces）。

async fn fetch_remote_installed_plugins(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
) -> Result<Vec<RemoteInstalledPlugin>, RemotePluginCatalogError>

作用：一次性拉取所有范围里的已安装远程插件，用于本地缓存或后台刷新。它覆盖全球、工作区和用户自建三个范围。

数据流：进去服务配置和登录信息 → 它确认登录后并行请求三个范围的安装列表，再转换成缓存条目并排序 → 出来统一的 RemoteInstalledPlugin 列表。

调用关系：build_and_cache_remote_installed_plugin_marketplaces 和后台刷新循环会调用它。它下层依赖 fetch_installed_plugins_for_scope，上层通常会把结果写入缓存或分组展示。

调用图：调用 2 个内部函数（ensure_chatgpt_auth, fetch_installed_plugins_for_scope）；被 2 处调用（build_and_cache_remote_installed_plugin_marketplaces, run_remote_installed_plugins_cache_refresh_loop）；外部调用 1 个（try_join!）。

fn group_remote_installed_plugins_by_marketplaces(
    plugins: &[RemoteInstalledPlugin],
    visible_marketplaces: &[&str],
) -> Vec<RemoteMarketplace>

作用：把缓存里的已安装远程插件重新按市场分组，方便界面展示。它还会过滤掉当前不想显示的市场。

数据流：进去已安装插件列表和允许显示的市场名列表 → 它为每个插件生成摘要，按市场收集，再按固定市场顺序输出并在每组内排序 → 出来一组 RemoteMarketplace。

调用关系：缓存构建和从缓存恢复市场列表时会调用它。它把缓存里的扁平列表变回界面喜欢的“市场下面有插件”的结构。

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

async fn fetch_remote_plugin_detail(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    marketplace_name: &str,
    plugin_id: &str,
) -> Result<RemotePluginDetail, RemotePlugin

作用：获取某个远程插件的详情，但不要求服务器返回下载地址。适合普通详情页读取。

数据流：进去服务配置、登录信息、市场名和插件 id → 它把请求转给 fetch_remote_plugin_detail_with_download_url_option，并把 include_download_urls 设为 false → 出来完整插件详情。

调用关系：plugin_read_response 会调用它。它是更通用详情函数的简化入口。

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

async fn fetch_remote_plugin_share_context(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    plugin_id: &str,
) -> Result<Option<RemotePluginShareContext>, RemotePluginCatalog

作用：读取某个远程插件的分享信息，比如分享链接、创建者和可见性。只有工作区插件通常会有这些信息。

数据流：进去服务配置、登录信息和插件 id → 它确认登录，拉取插件详情，再从详情里提取分享上下文 → 出来分享信息或空。

调用关系：plugin_read_response 会在需要分享状态时调用它。它使用 fetch_plugin_detail 拿原始数据，再交给 remote_plugin_share_context 做提取。

调用图：调用 3 个内部函数（ensure_chatgpt_auth, fetch_plugin_detail, remote_plugin_share_context）；被 1 处调用（plugin_read_response）。

async fn fetch_remote_plugin_detail_with_download_urls(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    marketplace_name: &str,
    plugin_id: &str,
) -> Result<RemotePluginD

作用：获取插件详情，并要求服务器带上下载地址。安装远程插件时需要这些地址来拿插件包。

数据流：进去服务配置、登录信息、市场名和插件 id → 它调用通用详情函数，并把 include_download_urls 设为 true → 出来带下载链接的插件详情。

调用关系：remote_plugin_install_response 会调用它。它和 fetch_remote_plugin_detail 共用同一个底层实现，只是开关不同。

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

async fn fetch_remote_plugin_skill_detail(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    marketplace_name: &str,
    plugin_id: &str,
    skill_name: &str,
) -> Result<Remo

作用：读取远程插件里某个技能的详细说明内容。技能可以理解成插件提供的一个具体能力或说明文档。

数据流：进去服务配置、登录信息、市场名、插件 id、技能名 → 它确认登录和市场有效，拼技能详情 URL，发送请求并解码；还会核对返回的插件 id 和技能名是否一致 → 出来技能内容。

调用关系：plugin_skill_read_response 会调用它。它用 from_marketplace_name 做入口校验，用 remote_plugin_skill_detail_url 拼安全地址，再用 authenticated_request 和 send_and_decode 完成网络请求。

调用图：调用 6 个内部函数（from_marketplace_name, authenticated_request, ensure_chatgpt_auth, remote_plugin_skill_detail_url, send_and_decode, build_reqwest_client）；被 1 处调用（plugin_skill_read_response）。

async fn fetch_remote_plugin_detail_with_download_url_option(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    _marketplace_name: &str,
    plugin_id: &str,
    include_downlo

作用：这是获取插件详情的共用底层函数，区别只在于是否要下载地址。它还会以服务器返回的真实范围为准，而不是盲信调用者传来的市场名。

数据流：进去服务配置、登录信息、市场名、插件 id 和下载地址开关 → 它确认登录，拉取插件详情，计算规范市场名 → 交给 build_remote_plugin_detail 组装成最终详情。

调用关系：fetch_remote_plugin_detail 和 fetch_remote_plugin_detail_with_download_urls 都调用它。它连接原始网络响应和项目内部详情模型。

调用图：调用 4 个内部函数（build_remote_plugin_detail, ensure_chatgpt_auth, fetch_plugin_detail, remote_plugin_canonical_marketplace_name）；被 2 处调用（fetch_remote_plugin_detail, fetch_remote_plugin_detail_with_download_urls）。

async fn build_remote_plugin_detail(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
    marketplace_name: String,
    plugin_id: &str,
    plugin: RemotePl

作用：把服务器返回的插件原始详情整理成界面和安装流程真正需要的详情对象。它会合并安装状态、技能启用状态、应用连接和 MCP 服务器信息。

数据流：进去配置、登录、插件范围、市场名、插件 id 和原始目录项 → 它查该范围的已安装列表，标出禁用技能，整理 app manifest 或 app id，并应用 MCP 路由策略 → 出来 RemotePluginDetail。

调用关系：fetch_remote_plugin_detail_with_download_url_option 拉到原始数据后会调用它。它会调用 fetch_installed_plugins_for_scope、build_remote_plugin_summary、apply_app_mcp_routing_policy 等函数完成拼装。

调用图：调用 6 个内部函数（apply_app_mcp_routing_policy, marketplace_display_name, build_remote_plugin_summary, fetch_installed_plugins_for_scope, non_empty_string, api_auth_mode）；被 1 处调用（fetch_remote_plugin_detail_with_download_url_option）；外部调用 1 个（app_connector_ids_from_declarations）。

fn app_declarations_from_remote_app_ids(app_ids: &[String]) -> Vec<AppDeclaration>

作用：在没有完整应用清单时，把简单的 app id 列表补成项目内部需要的应用声明。它是一个兜底转换器。

数据流：进去一组 app id 字符串 → 它为每个 id 创建一个 AppDeclaration，把名字和连接器 id 都设成这个 id → 出来应用声明列表。

调用关系：插件详情构建时，如果远程响应没有 app_manifest，就会用这种简单方式生成应用声明，保证后续应用和 MCP 路由仍能继续处理。

async fn install_remote_plugin(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    _marketplace_name: &str,
    plugin_id: &str,
) -> Result<RemotePluginInstallResult, RemotePlu

作用：请求服务器安装一个远程插件。它还会确认服务器返回的确实是同一个插件，并且已经启用。

数据流：进去服务配置、登录信息、市场名和插件 id → 它确认登录，向 /install 端点发 POST 请求，并要求返回需要授权的 app → 核对 id 和 enabled 后，出来安装结果。

调用关系：remote_plugin_install_response 会调用它。它不先验证市场名，因为远程插件 id 本身能唯一定位插件；网络部分交给 authenticated_request 和 send_and_decode。

调用图：调用 4 个内部函数（authenticated_request, ensure_chatgpt_auth, send_and_decode, build_reqwest_client）；被 1 处调用（remote_plugin_install_response）；外部调用 1 个（format!）。

async fn uninstall_remote_plugin(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    codex_home: PathBuf,
    plugin_id: &str,
) -> Result<(), RemotePluginCatalogError>

作用：请求服务器卸载远程插件，并清理本地缓存。这样用户卸载后，本地旧插件包不会继续残留影响系统。

数据流：进去服务配置、登录信息、本地目录和插件 id → 它先拉详情确定市场和名称，再发卸载请求，核对返回状态为未启用 → 后台删除对应缓存，最后返回成功或错误。

调用关系：remote_plugin_uninstall_response 会调用它。它会用 fetch_plugin_detail 和 remote_plugin_canonical_marketplace_name 找缓存位置，再通过 spawn_blocking 把文件删除交给 remove_remote_plugin_cache。

调用图：调用 6 个内部函数（authenticated_request, ensure_chatgpt_auth, fetch_plugin_detail, remote_plugin_canonical_marketplace_name, send_and_decode, build_reqwest_client）；被 1 处调用（remote_plugin_uninstall_response）；外部调用 2 个（format!, spawn_blocking）。

fn remove_remote_plugin_cache(
    codex_home: PathBuf,
    marketplace_name: String,
    plugin_name: String,
    legacy_plugin_id: String,
) -> Result<(), String>

作用：删除某个远程插件在本地留下的缓存目录或旧格式缓存。它专门做磁盘清理，避免阻塞异步网络流程。

数据流：进去本地目录、市场名、插件名和旧插件 id → 它打开插件存储，算出新格式缓存路径并卸载；如果旧格式路径也存在，就删除目录或文件 → 出来成功或错误文字。

调用关系：uninstall_remote_plugin 会在后台线程里调用它。它是卸载流程的收尾清洁工，和服务器请求分开，避免文件操作卡住主异步任务。

调用图：调用 2 个内部函数（try_new, new）；外部调用 4 个（clone, join, remove_dir_all, remove_file）。

fn build_remote_plugin_summary(
    plugin: &RemotePluginDirectoryItem,
    installed_plugin: Option<&RemotePluginInstalledItem>,
) -> Result<RemotePluginSummary, RemotePluginCatalogError>

作用：把一个远程插件目录项整理成列表页用的简短信息。它会加上安装状态、启用状态、展示信息和分享信息。

数据流：进去插件目录项和可选的已安装记录 → 它计算市场名和本地配置 id，提取分享上下文与界面信息 → 出来 RemotePluginSummary。

调用关系：build_remote_marketplace 和 build_remote_plugin_detail 都会用它。它内部依赖 remote_plugin_canonical_marketplace_name、remote_plugin_share_context 和 remote_plugin_interface_to_info。

调用图：调用 4 个内部函数（remote_plugin_canonical_marketplace_name, remote_plugin_interface_to_info, remote_plugin_share_context, new）；被 1 处调用（build_remote_plugin_detail）。

fn remote_discoverable_plugin_from_directory_item(
    plugin: &RemotePluginDirectoryItem,
) -> Result<RemoteDiscoverablePlugin, RemotePluginCatalogError>

作用：把目录里的远程插件转换成“可发现插件”格式，用于推荐或发现列表。这个格式比详情更轻，只保留搜索和展示需要的信息。

数据流：进去一个插件目录项 → 它生成配置 id，选择显示名和描述，记录是否有技能、app id、安装策略和可用状态 → 出来 RemoteDiscoverablePlugin。

调用关系：缓存的全球目录被拿来做发现列表时会用到它。它和 build_remote_plugin_summary 类似，但目标是推荐/发现，不是市场列表。

调用图：调用 3 个内部函数（non_empty_string, remote_plugin_canonical_marketplace_name, new）。

fn remote_plugin_share_context(
    plugin: &RemotePluginDirectoryItem,
) -> Result<Option<RemotePluginShareContext>, RemotePluginCatalogError>

作用：从插件目录项里提取分享相关信息。非工作区插件没有分享上下文，工作区插件才会带共享可见性、链接和成员信息。

数据流：进去一个插件目录项 → 它看插件范围；全局和用户范围返回空，工作区范围则读取 discoverability、分享 URL、创建者和共享对象 → 出来分享上下文或空。

调用关系：build_remote_plugin_summary 和 fetch_remote_plugin_share_context 会调用它。它需要 workspace_plugin_discoverability 来确认工作区插件的共享状态。

调用图：调用 1 个内部函数（workspace_plugin_discoverability）；被 2 处调用（build_remote_plugin_summary, fetch_remote_plugin_share_context）。

fn remote_installed_plugin_to_cache_entry(
    installed_plugin: &RemotePluginInstalledItem,
) -> Result<RemoteInstalledPlugin, RemotePluginCatalogError>

作用：把服务器返回的已安装插件转换成本地缓存条目。缓存只记录列表和启用状态需要的信息，不把每个技能的远程禁用状态写进去。

数据流：进去一个已安装插件项 → 它取出插件基本信息、市场名、启用状态、策略、界面信息和关键词 → 出来 RemoteInstalledPlugin 缓存条目。

调用关系：fetch_remote_installed_plugins 拉到安装列表后会用它做转换。它依赖 remote_plugin_canonical_marketplace_name 和 remote_plugin_interface_to_info。

调用图：调用 2 个内部函数（remote_plugin_canonical_marketplace_name, remote_plugin_interface_to_info）。

fn remote_plugin_interface_to_info(plugin: &RemotePluginDirectoryItem) -> Option<PluginInterface>

作用：把服务器里的插件界面信息转换成项目统一的 PluginInterface。界面信息包括显示名、简介、开发者、图标 URL、默认提示词等。

数据流：进去一个插件目录项 → 它清理空字符串，规范默认提示词，复制各种展示字段；如果所有字段都为空，就返回空 → 出来可选的 PluginInterface。

调用关系：build_remote_plugin_summary 和 remote_installed_plugin_to_cache_entry 会调用它。它把后端字段变成前端或列表能统一理解的展示信息。

调用图：调用 1 个内部函数（non_empty_string）；被 2 处调用（build_remote_plugin_summary, remote_installed_plugin_to_cache_entry）；外部调用 1 个（new）。

fn remote_skill_interface_to_info(
    interface: Option<RemotePluginSkillInterfaceResponse>,
) -> Option<SkillInterface>

作用：把服务器返回的技能界面信息转换成项目统一的 SkillInterface。技能界面信息比插件少，主要是名字、短描述、颜色和默认提示。

数据流：进去可选的技能界面响应 → 没有响应就返回空；有响应就组装字段，并在全部字段为空时仍返回空 → 出来可选的 SkillInterface。

调用关系：插件详情构建技能列表时会用到它。它让每个技能的展示信息和项目里的通用技能格式对齐。

fn remote_plugin_display_name(plugin: &RemotePluginSummary) -> &str

作用：取得插件应该显示给用户看的名字。优先用界面信息里的显示名，没有就退回插件内部名称。

数据流：进去一个插件摘要 → 它查看 interface.display_name 是否存在 → 出来一个字符串引用，作为排序和展示使用。

调用关系：sort_remote_plugin_summaries_by_display_name 会用它比较插件名字。它是排序前的取名规则。

fn sort_remote_plugin_summaries_by_display_name(plugins: &mut [RemotePluginSummary])

作用：按插件显示名给插件摘要列表排序。它先忽略大小写比较，再用原始名字和 id 兜底，保证顺序稳定。

数据流：进去一个可修改的插件摘要数组 → 它根据显示名的小写形式、原显示名、插件 id 依次排序 → 原数组被重新排列，不额外返回列表。

调用关系：按已安装插件缓存分组展示时会用到它。它让同一市场里的插件列表看起来更自然。

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

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

作用：把字符串清理成“真的有内容”的可选值。空白字符串会被当成没有值。

数据流：进去一个可选字符串引用 → 它去掉前后空格，检查是否为空 → 有内容就返回新的 String，没有就返回空。

调用关系：推荐插件、详情构建、可发现插件转换和插件界面信息转换都会用它。它避免界面显示一堆空字符串。

调用图：被 4 处调用（build_remote_plugin_detail, recommended_plugins_mode, remote_discoverable_plugin_from_directory_item, remote_plugin_interface_to_info）。

fn normalize_remote_default_prompts(prompts: &[String]) -> Option<Vec<String>>

作用：清理一组远程默认提示词，并限制数量。默认提示词就是插件建议用户一键使用的开场文本。

数据流：进去一组提示词字符串 → 它逐条调用 normalize_remote_default_prompt 过滤空的和过长的，再最多保留 3 条 → 出来提示词列表或空。

调用关系：插件界面信息转换时会用它处理 default_prompts。它负责批量规则，单条规则交给 normalize_remote_default_prompt。

fn normalize_remote_default_prompt(prompt: &str) -> Option<String>

作用：清理一条远程默认提示词。它去掉空格，并拒绝空内容和太长内容，防止界面被异常文本撑坏。

数据流：进去一条提示词 → 它 trim 前后空格，检查是否为空以及字符数是否超过 128 → 合格就返回清理后的字符串，不合格返回空。

调用关系：normalize_remote_default_prompts 会批量调用它；插件界面信息也会在只有单条默认提示时用它。

async fn fetch_directory_plugins_for_scope(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
) -> Result<Vec<RemotePluginDirectoryItem>, RemotePluginCatalogE

作用：拉取某个范围的远程插件目录，比如全球、用户自建或工作区目录。它不指定额外集合。

数据流：进去服务配置、登录和插件范围 → 它把 collection 设为空，转给分页拉取函数 → 出来该范围下的全部目录插件。

调用关系：fetch_remote_marketplaces 和 fetch_and_cache_global_remote_plugin_catalog 会调用它。它是普通目录拉取的便捷入口。

调用图：调用 1 个内部函数（fetch_directory_plugins_for_scope_with_optional_collection）；被 2 处调用（fetch_and_cache_global_remote_plugin_catalog, fetch_remote_marketplaces）。

async fn fetch_directory_plugins_for_scope_with_collection(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
    collection: &str,
) -> Result<Vec<RemotePlug

作用：拉取某个范围中特定集合的插件目录。集合可以理解成服务器给插件目录打的一个筛选标签。

数据流：进去服务配置、登录、范围和集合名 → 它把集合名传给通用分页函数 → 出来符合该集合的全部目录插件。

调用关系：精选远程市场流程会通过它拿 OpenAI curated collection。它和普通目录函数共用同一个分页实现。

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

async fn fetch_directory_plugins_for_scope_with_optional_collection(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
    collection: Option<&str>,
) -> Resu

作用：分页拉完某个范围的插件目录，可选地按集合筛选。它负责一页页请求，直到服务器说没有下一页。

数据流：进去服务配置、登录、范围和可选集合 → 它循环调用 get_remote_plugin_list_page，累积每页 plugins，并更新 page token → 出来完整插件列表。

调用关系：fetch_directory_plugins_for_scope 和 fetch_directory_plugins_for_scope_with_collection 都依赖它。真正单页 HTTP 请求由 get_remote_plugin_list_page 完成。

调用图：调用 1 个内部函数（get_remote_plugin_list_page）；被 2 处调用（fetch_directory_plugins_for_scope, fetch_directory_plugins_for_scope_with_collection）；外部调用 1 个（new）。

async fn fetch_shared_workspace_plugins(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
) -> Result<Vec<RemotePluginDirectoryItem>, RemotePluginCatalogError>

作用：拉取明确分享给当前用户的工作区插件。它也会处理分页，直到拿完所有分享插件。

数据流：进去服务配置和登录 → 它循环请求共享工作区插件页面，累积插件，并跟随下一页 token → 出来共享插件列表。

调用关系：fetch_remote_marketplaces 在构建“Shared with me”市场时会调用它。单页请求交给 get_remote_shared_workspace_plugins_page。

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

async fn fetch_installed_plugins_for_scope(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
) -> Result<Vec<RemotePluginInstalledItem>, RemotePluginCatalogE

作用：拉取某个范围里用户已经安装的远程插件，不要求下载地址。列表和详情状态判断通常只需要这些信息。

数据流：进去服务配置、登录和范围 → 它把 include_download_urls 设为 false，转给分页安装列表函数 → 出来安装插件列表。

调用关系：fetch_remote_marketplaces、fetch_remote_installed_plugins 和 build_remote_plugin_detail 都会调用它。它是已安装列表的常用入口。

调用图：调用 1 个内部函数（fetch_installed_plugins_for_scope_with_download_url）；被 3 处调用（build_remote_plugin_detail, fetch_remote_installed_plugins, fetch_remote_marketplaces）。

async fn fetch_installed_plugins_for_scope_with_download_url(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
    include_download_urls: bool,
) -> Result<V

作用：分页拉取某个范围的已安装插件，并可选择是否要求下载地址。它处理服务器分多页返回的情况。

数据流：进去服务配置、登录、范围和下载地址开关 → 它循环调用 get_remote_plugin_installed_page，累积每页安装项 → 出来完整安装列表。

调用关系：fetch_installed_plugins_for_scope 会调用它。它把“多页拉完”的流程和“单页怎么请求”分开。

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

async fn get_remote_plugin_list_page(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
    page_token: Option<&str>,
    collection: Option<&str>,
) -> Resul

作用：请求远程插件目录的一页数据。它是目录分页循环里的单次网络请求。

数据流：进去服务配置、登录、范围、可选页 token 和可选集合 → 它拼 /ps/plugins/list 地址，加 scope、limit、collection、pageToken 参数并发送 → 出来这一页的插件和下一页信息。

调用关系：fetch_directory_plugins_for_scope_with_optional_collection 会反复调用它。它用 RemotePluginScope::api_value 翻译范围，用 authenticated_request 和 send_and_decode 完成请求。

调用图：调用 4 个内部函数（api_value, authenticated_request, send_and_decode, build_reqwest_client）；被 1 处调用（fetch_directory_plugins_for_scope_with_optional_collection）；外部调用 1 个（format!）。

async fn get_remote_shared_workspace_plugins_page(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    page_token: Option<&str>,
) -> Result<RemotePluginListResponse, RemotePluginCatalog

作用：请求“分享给我”的工作区插件的一页数据。它只负责一页，不负责循环。

数据流：进去服务配置、登录和可选页 token → 它拼 /ps/plugins/workspace/shared 地址，加 limit 和 pageToken，发送并解析 → 出来这一页共享插件响应。

调用关系：fetch_shared_workspace_plugins 会循环调用它。它使用 authenticated_request 加认证，send_and_decode 处理发送和 JSON 解析。

调用图：调用 3 个内部函数（authenticated_request, send_and_decode, build_reqwest_client）；被 1 处调用（fetch_shared_workspace_plugins）；外部调用 1 个（format!）。

async fn get_remote_plugin_installed_page(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
    page_token: Option<&str>,
    include_download_urls: bool,
)

作用：请求某个范围的已安装插件的一页数据。它支持可选地让服务器带上下载链接。

数据流：进去服务配置、登录、范围、可选页 token 和下载地址开关 → 它拼 /ps/plugins/installed 地址，加 scope、includeDownloadUrls、pageToken 等参数 → 出来这一页安装列表响应。

调用关系：fetch_installed_plugins_for_scope_with_download_url 会反复调用它。它用 api_value 生成 scope 参数，并走统一的认证和解码流程。

调用图：调用 4 个内部函数（api_value, authenticated_request, send_and_decode, build_reqwest_client）；被 1 处调用（fetch_installed_plugins_for_scope_with_download_url）；外部调用 1 个（format!）。

async fn fetch_plugin_detail(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    plugin_id: &str,
    include_download_urls: bool,
) -> Result<RemotePluginDirectoryItem, RemotePluginCat

作用：请求某个远程插件的原始详情。它是详情页、分享信息和卸载流程的基础网络读取函数。

数据流：进去服务配置、登录、插件 id 和下载地址开关 → 它拼 /ps/plugins/{plugin_id} 地址，按需加 includeDownloadUrls 参数，发送请求并解码 → 出来 RemotePluginDirectoryItem。

调用关系：fetch_remote_plugin_detail_with_download_url_option、fetch_remote_plugin_share_context 和 uninstall_remote_plugin 都会调用它。它只拿原始数据，不负责最终展示整理。

调用图：调用 3 个内部函数（authenticated_request, send_and_decode, build_reqwest_client）；被 3 处调用（fetch_remote_plugin_detail_with_download_url_option, fetch_remote_plugin_share_context, uninstall_remote_plugin）；外部调用 1 个（format!）。

fn remote_plugin_skill_detail_url(
    config: &RemotePluginServiceConfig,
    plugin_id: &str,
    skill_name: &str,
) -> Result<String, RemotePluginCatalogError>

作用：安全地拼出某个插件技能详情的 URL。它用 URL 解析器逐段添加路径，避免手写字符串时路径出错。

数据流：进去服务配置、插件 id 和技能名 → 它解析基础 URL，依次追加 ps、plugins、插件 id、skills、技能名 → 出来完整 URL，基础 URL 不合法就报错。

调用关系：fetch_remote_plugin_skill_detail 会调用它来生成请求地址。这样技能名即使包含特殊路径字符，也会按 URL 规则处理。

调用图：被 1 处调用（fetch_remote_plugin_skill_detail）；外部调用 1 个（parse）。

fn ensure_chatgpt_auth(auth: Option<&CodexAuth>) -> Result<&CodexAuth, RemotePluginCatalogError>

作用：确认调用者提供了 ChatGPT 后端可用的登录身份。远程插件目录不支持普通 API key 模式。

数据流：进去一个可选认证对象 → 没有认证就返回 AuthRequired；认证方式不支持就返回 UnsupportedAuthMode；合格就返回认证引用。

调用关系：几乎所有远程插件网络入口都会先调用它，包括市场列表、详情、技能详情、安装、卸载、推荐和缓存刷新。它是远程插件访问的身份门禁。

调用图：被 11 处调用（fetch_and_cache_global_remote_plugin_catalog, fetch_openai_curated_remote_collection_marketplace, fetch_recommended_plugins, fetch_remote_installed_plugins, fetch_remote_marketplaces, fetch_remote_plugin_detail_with_download_url_option, fetch_remote_plugin_share_context, fetch_remote_plugin_skill_detail, has_cached_global_remote_plugin_catalog, install_remote_plugin (+1 more)）。

fn authenticated_request(
    request: RequestBuilder,
    auth: &CodexAuth,
) -> Result<RequestBuilder, RemotePluginCatalogError>

作用：给网络请求统一加上超时、认证头和产品标识。这样所有远程插件请求都带着正确身份和 Codex 产品 SKU。

数据流：进去一个 reqwest 请求构造器和认证信息 → 它设置 30 秒超时，加入认证头，再加 OAI-Product-Sku: codex → 出来可发送的请求构造器。

调用关系：fetch_plugin_detail、列表分页、推荐、技能详情、安装和卸载都会调用它。它把重复的请求头设置集中在一个地方。

调用图：被 8 处调用（fetch_plugin_detail, fetch_recommended_plugins, fetch_remote_plugin_skill_detail, get_remote_plugin_installed_page, get_remote_plugin_list_page, get_remote_shared_workspace_plugins_page, install_remote_plugin, uninstall_remote_plugin）；外部调用 2 个（timeout, auth_provider_from_auth）。

async fn send_and_decode(
    request: RequestBuilder,
    url: &str,
) -> Result<T, RemotePluginCatalogError>

作用：发送 HTTP 请求并把服务器返回的 JSON 解码成指定类型。它还会把网络失败、状态码失败和 JSON 解析失败区分成不同错误。

数据流：进去一个已经配置好的请求和 URL 字符串 → 它发送请求，读取状态码和响应正文；状态码不成功就报错，成功就按目标类型解析 JSON → 出来解析后的结构体。

调用关系：所有真正访问远程插件 API 的函数最终都会用它收尾。它是网络层的统一出口，让上层不用重复写发送、读正文和解析错误处理。

调用图：被 8 处调用（fetch_plugin_detail, fetch_recommended_plugins, fetch_remote_plugin_skill_detail, get_remote_plugin_installed_page, get_remote_plugin_list_page, get_remote_shared_workspace_plugins_page, install_remote_plugin, uninstall_remote_plugin）；外部调用 2 个（send, from_str）。

async fn fetch_remote_featured_plugin_ids(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    product: Option<Product>,
) -> Result<Vec<String>, RemotePluginFetchError>

作用：这个函数去远程服务器拉取“推荐插件”的 id 列表。上层想展示或使用服务器推荐的插件时，会通过它拿到一串插件标识。

数据流：进去的是远程服务配置、可选的登录信息，以及可选的产品类型。它先从配置里取 ChatGPT 基础地址，拼成 /plugins/featured 这个接口地址，再把产品类型作为查询参数放进去；如果登录信息适合 Codex 后端，就把认证头也加上。然后它发出 GET 请求，最多等 10 秒。回来后先检查 HTTP 状态码（服务器是否表示成功），再把返回正文按 JSON 解析成字符串列表。出来的是插件 id 列表；如果网络、状态码或 JSON 解析出问题，就返回对应错误。

调用关系：它是“获取推荐插件”这条路上的实际联网步骤，由 featured_plugin_ids_for_config 调用。它自己会创建 HTTP 客户端，必要时把 auth_provider_from_auth 生成的认证信息塞进请求，最后用 JSON 解析工具把服务器回答变成程序能用的数据。

调用图：调用 1 个内部函数（build_reqwest_client）；被 1 处调用（featured_plugin_ids_for_config）；外部调用 3 个（auth_provider_from_auth, format!, from_str）。

async fn enable_remote_plugin(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    plugin_id: &str,
) -> Result<(), RemotePluginMutationError>

作用：这个函数告诉远程服务器：请启用某个插件。它给上层提供了一个简单入口，让调用者不用关心具体请求地址和返回校验。

数据流：进去的是远程服务配置、可选登录信息和插件 id。它把这些交给更底层的 post_remote_plugin_mutation，并指定动作是 enable。如果远端确认插件已启用，它返回空结果表示成功；如果登录不合适、请求失败或服务器返回内容不对，就把错误传回去。

调用关系：它由 install_plugin_with_remote_sync 调用，通常发生在本地安装插件并需要同步到远端时。它自己不直接发网络请求，而是把实际工作交给 post_remote_plugin_mutation，相当于给“启用插件”这个动作起了一个清楚的名字。

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

async fn uninstall_remote_plugin(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    plugin_id: &str,
) -> Result<(), RemotePluginMutationError>

作用：这个函数告诉远程服务器：请卸载或关闭某个插件。它让上层用一句话完成远端卸载同步，而不用知道旧版接口怎么调用。

数据流：进去的是远程服务配置、可选登录信息和插件 id。它调用 post_remote_plugin_mutation，动作写成 uninstall。如果服务器返回的插件 id 和状态都符合卸载后的预期，它返回成功；否则把具体失败原因交还给调用者。

调用关系：它由 uninstall_plugin_with_remote_sync 调用，通常发生在本地卸载插件后要通知远端时。它和 enable_remote_plugin 用同一套底层发送逻辑，只是传入的动作不同。

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

fn ensure_codex_backend_auth(
    auth: Option<&CodexAuth>,
) -> Result<&CodexAuth, RemotePluginMutationError>

作用：这个函数检查有没有可用的 ChatGPT/Codex 后端登录凭证。远程修改插件状态是敏感操作，所以不能匿名做，也不能用不支持的 API key 方式做。

数据流：进去的是一个可能为空的登录信息。它先看有没有登录；没有就返回“需要登录”的错误。再看这个登录是否使用 Codex 后端；不是的话返回“不支持这种认证方式”的错误。检查通过后，出来的是确认可用的登录信息引用。

调用关系：它被 post_remote_plugin_mutation 在真正发修改请求前调用。它像门口保安，先确认调用者有合适的身份，再允许后面的联网修改继续进行。

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

async fn post_remote_plugin_mutation(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    plugin_id: &str,
    action: &str,
) -> Result<RemotePluginMutationResponse, RemotePlugi

作用：这个函数是真正向远程服务器提交“启用”或“卸载”插件请求的核心步骤。它不仅发请求，还会核对服务器返回的结果是不是改了正确的插件、改成了正确的状态。

数据流：进去的是远程服务配置、登录信息、插件 id 和动作名，比如 enable 或 uninstall。它先用 ensure_codex_backend_auth 确认登录合格，再用 remote_plugin_mutation_url 拼出接口地址。之后创建 HTTP 客户端，带上认证头，发 POST 请求，最多等 30 秒。收到响应后，它检查状态码，读取正文，按 JSON 解析成包含插件 id 和 enabled 状态的结构。最后它核对返回的 id 是否等于请求的插件 id，并根据动作判断 enabled 是否符合预期。出来的是服务器返回的插件变更结果；任何一步不对都会变成明确错误。

调用关系：它是 enable_remote_plugin 和 uninstall_remote_plugin 共用的底层执行器。上层函数只决定动作是什么，它负责认证、拼 URL、发请求、解析和校验，必要时还会调用认证头生成工具和 JSON 解析工具。

调用图：调用 3 个内部函数（ensure_codex_backend_auth, remote_plugin_mutation_url, build_reqwest_client）；被 2 处调用（enable_remote_plugin, uninstall_remote_plugin）；外部调用 2 个（auth_provider_from_auth, from_str）。

fn remote_plugin_mutation_url(
    config: &RemotePluginServiceConfig,
    plugin_id: &str,
    action: &str,
) -> Result<String, RemotePluginMutationError>

作用：这个函数负责把基础服务器地址、插件 id 和动作拼成一个安全、规范的远程接口网址。没有它，代码很容易因为多一个斜杠、少一段路径，或者基础地址非法而请求到错误位置。

数据流：进去的是远程服务配置、插件 id 和动作名。它先解析配置里的 ChatGPT 基础地址；如果地址本身不合法，就返回地址错误。然后它在路径后面依次加上 plugins、插件 id、动作名，并处理末尾空路径这种小细节。出来的是完整的网址字符串，例如指向某个插件的启用或卸载接口。

调用关系：它由 post_remote_plugin_mutation 在发请求前调用。它专心做“拼地址”这件事，让发送请求的函数不用手写字符串拼接，也能更早发现配置里的坏地址。

调用图：被 1 处调用（post_remote_plugin_mutation）；外部调用 1 个（parse）。

async fn save_remote_plugin_share(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    codex_home: &Path,
    plugin_path: &AbsolutePathBuf,
    remote_plugin_id: Option<&str>,

作用：把一个本地插件保存到远端，并生成或更新一个可分享的远端插件。别人会在点击“分享插件”或“更新已分享插件”时用到它。

数据流：进去的是服务地址配置、登录信息、本地 Codex 目录、插件路径、可选的远端插件 ID，以及分享权限设置。它先检查登录，再在后台线程里把插件目录打成压缩包并取好文件名；然后向服务器申请上传地址，把压缩包传上去，再提交文件 ID、校验用的 etag 和分享设置；最后返回远端插件 ID 和可能存在的分享链接，并尽量把“远端 ID → 本地路径”的关系写到本地。

调用关系：这是保存分享的主流程。它把具体小活交给 create_workspace_plugin_upload 申请上传位置，交给 put_workspace_plugin_upload 真正传文件，交给 ensure_unlisted_workspace_target 修正隐藏分享的目标列表，交给 finalize_workspace_plugin_upload 完成服务器端创建或更新，最后调用本地路径记录函数保存映射。

调用图：调用 6 个内部函数（create_workspace_plugin_upload, ensure_unlisted_workspace_target, finalize_workspace_plugin_upload, record_plugin_share_local_path, put_workspace_plugin_upload, as_path）；外部调用 4 个（UnexpectedResponse, spawn_blocking, clone, warn!）。

async fn list_remote_plugin_shares(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    codex_home: &Path,
) -> Result<Vec<RemotePluginShareSummary>, RemotePluginCatalogError>

作用：列出当前账号创建过的远端插件分享，并尽量附上它们对应的本地插件路径。用户想看“我分享过哪些插件”时会走这里。

数据流：进去的是服务配置、登录信息和本地 Codex 目录。它先确认登录，再从服务器取出自己创建的工作区插件；如果没有，就直接返回空列表。否则它还会取已安装插件信息、读取本地保存的路径映射，然后把这些信息合成一条条分享摘要；如果服务器返回的分享对象缺少必要的分享人员信息，就返回错误。

调用关系：这是列表页或列表命令的主入口。它先让 fetch_created_workspace_plugins 翻页拿完远端数据，再读 local_paths 里的本地映射，并依赖上层已有的摘要构建逻辑把远端插件和安装状态拼成可展示的信息。

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

fn load_plugin_share_remote_ids_by_local_path(
    codex_home: &Path,
) -> io::Result<BTreeMap<AbsolutePathBuf, String>>

作用：读取本地记录，并反过来得到“本地路径对应哪个远端插件 ID”。这让程序能从一个本地插件目录找到它已经分享到远端的身份。

数据流：进去的是 Codex 的本地目录。它读取保存过的“远端插件 ID → 本地路径”表，逐条检查远端 ID 是否像合法 ID；然后把方向反过来，变成“本地路径 → 远端插件 ID”的表返回。如果记录里有坏 ID，就返回本地文件数据损坏类错误。

调用关系：它依赖 local_paths::load_plugin_share_local_paths 读取磁盘上的映射文件。它本身不联网，通常给需要根据本地路径判断是否已有远端分享的流程使用。

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

async fn delete_remote_plugin_share(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    codex_home: &Path,
    remote_plugin_id: &str,
) -> Result<(), RemotePluginCatalogError>

作用：删除一个远端插件分享，并顺手清掉本地保存的路径映射。用户选择“取消分享”或删除远端插件时会用它。

数据流：进去的是服务配置、登录信息、本地 Codex 目录和远端插件 ID。它确认登录后拼出删除接口地址，带上认证信息发送 HTTP DELETE 请求；服务器返回 204 No Content 才算成功。成功后它尝试删除本地的 ID 到路径记录；如果本地清理失败，只记警告，不让远端删除结果变失败。

调用关系：这是删除分享的主流程。它用 build_reqwest_client 创建网络客户端，用 send_and_expect_status 统一发送请求并检查状态码，再把本地清理交给 local_paths::remove_plugin_share_local_path。

调用图：调用 3 个内部函数（remove_plugin_share_local_path, send_and_expect_status, build_reqwest_client）；外部调用 2 个（format!, warn!）。

async fn update_remote_plugin_share_targets(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    remote_plugin_id: &str,
    targets: Vec<RemotePluginShareTarget>,
    discoverab

作用：修改一个已分享插件的可见范围和可访问对象。比如把插件改成私有，或者指定某些用户、组、工作区可以看。

数据流：进去的是服务配置、登录信息、远端插件 ID、新的目标列表，以及新的可见性。它先确认登录，把“可更新的可见性”转换成普通可见性；如果是隐藏分享，就自动确保当前工作区在目标列表里。然后它向服务器的分享接口发送 PUT 请求，最后返回服务器确认后的人员列表和实际可见性。

调用关系：这是权限编辑流程的主入口。它复用 ensure_unlisted_workspace_target 来避免隐藏分享漏掉工作区，再通过 HTTP 客户端把 RemotePluginShareUpdateTargetsRequest 发给远端服务。

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

fn ensure_unlisted_workspace_target(
    auth: &CodexAuth,
    discoverability: Option<RemotePluginShareDiscoverability>,
    targets: Option<Vec<RemotePluginShareTarget>>,
) -> Result<Option<Vec<Remo

作用：保证“隐藏链接”分享至少包含当前工作区这个可读目标。这样插件不会因为权限列表不完整而让当前工作区的人看不到。

数据流：进去的是登录信息、可见性和可选的分享目标列表。它先看可见性是不是 Unlisted，也就是不公开列出但可通过指定范围访问；如果不是，就原样返回目标列表。如果是，它从登录信息里取当前账号或工作区 ID，把目标列表补齐：如果里面还没有这个工作区，就加一个 reader 只读权限。最后返回补过的目标列表。

调用关系：save_remote_plugin_share 和 update_remote_plugin_share_targets 都会在提交权限前调用它。它只做权限列表的安全修正，不负责联网；需要账号 ID 时会向 CodexAuth 询问 get_account_id。

调用图：调用 1 个内部函数（get_account_id）；被 2 处调用（save_remote_plugin_share, update_remote_plugin_share_targets）。

async fn fetch_created_workspace_plugins(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
) -> Result<Vec<RemotePluginDirectoryItem>, RemotePluginCatalogError>

作用：把服务器上“我创建的工作区插件”全部取回来。因为服务器可能分页返回，它负责一页一页拿完整。

数据流：进去的是服务配置和登录信息。它从第一页开始请求，把每页里的插件追加到列表；如果响应里还有下一页标记，就继续用这个标记请求下一页；直到没有下一页为止，最后返回完整插件列表。

调用关系：list_remote_plugin_shares 调用它来拿远端分享的原始数据。它把每一次具体取一页的工作交给 get_created_workspace_plugins_page，自己只负责循环翻页和汇总。

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

async fn get_created_workspace_plugins_page(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    page_token: Option<&str>,
) -> Result<RemotePluginListResponse, RemotePluginCatalogError>

作用：从服务器取一页“我创建的工作区插件”。它是分页列表里的单次网络请求。

数据流：进去的是服务配置、登录信息，以及可选的下一页标记。它拼出列表接口地址，创建带认证的 GET 请求，加上每页数量限制；如果有页标记，就把它也放进查询参数。最后发送请求并把服务器返回的 JSON 解成列表响应对象。

调用关系：fetch_created_workspace_plugins 在翻页循环里反复调用它。它负责和远端接口打交道，翻页判断和结果汇总则由上层函数完成。

调用图：调用 1 个内部函数（build_reqwest_client）；被 1 处调用（fetch_created_workspace_plugins）；外部调用 1 个（format!）。

async fn create_workspace_plugin_upload(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    filename: &str,
    size_bytes: usize,
    remote_plugin_id: Option<&str>,
) -> Result<Remote

作用：向服务器申请一个临时上传地址。真正上传大文件前，程序需要先拿到这个地址和文件 ID。

数据流：进去的是服务配置、登录信息、压缩包文件名、文件大小，以及可选的已有远端插件 ID。它把这些信息组成请求，告诉服务器“我要上传一个 gzip 文件”；服务器返回 file_id、upload_url 和可能的 etag。函数把这些解码后交回调用者。

调用关系：save_remote_plugin_share 在上传压缩包前先调用它。它只负责申请上传位置，不传文件；后续文件传输由 put_workspace_plugin_upload 完成。

调用图：调用 1 个内部函数（build_reqwest_client）；被 1 处调用（save_remote_plugin_share）；外部调用 1 个（format!）。

async fn put_workspace_plugin_upload(
    upload_url: &str,
    archive_bytes: Vec<u8>,
) -> Result<(), RemotePluginCatalogError>

作用：把插件压缩包真正上传到服务器给的临时地址。可以把它理解成把包裹送到已经预约好的仓库门口。

数据流：进去的是上传地址和压缩包字节内容。它创建 PUT 请求，设置这是 gzip 文件，并加上云存储需要的 x-ms-blob-type 头；然后发送文件内容。服务器返回 200 OK 或 201 Created 才算成功，否则把状态码和响应正文包装成错误。

调用关系：save_remote_plugin_share 在拿到上传地址后调用它。它不需要 Codex 的认证请求包装，因为这个 upload_url 本身就是服务器发给它的临时可用地址。

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

async fn finalize_workspace_plugin_upload(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    remote_plugin_id: Option<&str>,
    body: RemoteWorkspacePluginCreateRequest,
) -> Result<R

作用：通知服务器：刚才上传的文件可以正式变成远端插件了。没有这一步，文件只是上传了，还没有变成可分享插件。

数据流：进去的是服务配置、登录信息、可选的远端插件 ID，以及包含 file_id、etag 和分享设置的请求体。如果有远端插件 ID，就拼成更新已有插件的地址；没有就拼成创建新插件的地址。它发送认证 POST 请求，最后返回服务器生成的插件 ID 和分享链接。

调用关系：save_remote_plugin_share 在文件上传成功后调用它，完成最后的“登记发布”。它依赖之前 create_workspace_plugin_upload 给出的 file_id 和 etag，也依赖 put_workspace_plugin_upload 已经把文件传好。

调用图：调用 1 个内部函数（build_reqwest_client）；被 1 处调用（save_remote_plugin_share）；外部调用 1 个（format!）。

fn archive_filename(plugin_path: &Path) -> Result<String, RemotePluginCatalogError>

作用：根据插件目录名生成上传用的压缩包文件名。比如目录叫 my-plugin，就生成 my-plugin.tar.gz。

数据流：进去的是插件路径。它取路径最后一段作为插件名，并要求这个名字是合法的 UTF-8 文本；如果路径没有正常目录名，就返回“插件路径无效”的错误。成功时输出一个以 .tar.gz 结尾的文件名。

调用关系：保存分享时的打包阶段会用它来给压缩包起名。它只处理名字，不读取插件内容，也不联网。

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

fn archive_plugin_for_upload(plugin_path: &Path) -> Result<Vec<u8>, RemotePluginCatalogError>

作用：把插件目录压成上传用的字节包，并使用本文件规定的 50MB 最大限制。

数据流：进去的是插件路径。它不自己做压缩细节，而是把路径和默认大小上限交给 archive_plugin_for_upload_with_limit；成功时出来的是压缩包的二进制内容，失败时出来的是适合远端插件目录使用的错误。

调用关系：保存分享时会在后台打包阶段用它。它是一个带默认限制的薄包装，真正的压缩和错误转换由 archive_plugin_for_upload_with_limit 完成。

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

fn archive_plugin_for_upload_with_limit(
    plugin_path: &Path,
    max_bytes: usize,
) -> Result<Vec<u8>, RemotePluginCatalogError>

作用：按指定大小上限把插件目录打成 tar.gz 压缩包，并把底层打包错误翻译成这个模块统一使用的错误。

数据流：进去的是插件路径和最大允许字节数。它调用 pack_plugin_bundle_tar_gz 读取目录并生成压缩包；如果路径无效、压缩包太大或读文件出错，它分别转换成 InvalidPluginPath、ArchiveTooLarge 或 Archive 错误。成功时返回压缩包字节。

调用关系：archive_plugin_for_upload 调用它来使用默认 50MB 限制。测试也容易直接用它传入较小限制，检查超限行为；底层实际打包工作交给 plugin_bundle_archive 模块。

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

async fn send_and_expect_status(
    request: RequestBuilder,
    url_for_error: &str,
    expected_statuses: &[StatusCode],
) -> Result<(), RemotePluginCatalogError>

作用：发送一个 HTTP 请求，并检查返回状态码是不是预期的。它适合删除这类“不需要解析返回内容，只看成功码”的接口。

数据流：进去的是已经组好的请求、用于报错显示的地址，以及允许的状态码列表。它发送请求；如果网络失败，就返回请求错误。收到响应后读取状态码和正文；如果状态码不在允许列表里，就返回包含状态码和正文的错误；否则返回成功空结果。

调用关系：delete_remote_plugin_share 用它来确认删除接口返回 204 No Content。它把“发送请求、读响应、判断状态码、生成统一错误”这些重复动作集中起来，避免每个调用点自己写一遍。

调用图：被 1 处调用（delete_remote_plugin_share）；外部调用 2 个（send, contains）。

async fn checkout_remote_plugin_share(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    codex_home: &Path,
    remote_plugin_id: &str,
) -> Result<RemotePluginShareCheckoutRes

作用：这是整个“签出共享插件”流程的主入口。别人分享来的远程插件要变成本机可编辑插件时，就靠它把查询、下载、写目录册、记录映射这些步骤串起来。

数据流：输入远端服务配置、可选登录信息、本机 Codex 目录和远端插件 ID。它先读取远端插件详情，检查插件名、共享来源和本机路径；如果本地还没有，就下载并解压插件；随后更新个人插件市场文件，再记录远端 ID 到本地路径的对应关系。成功时输出一个结果，里面有远端 ID、本地插件 ID、插件名、本地路径、marketplace 路径和远端版本；失败时返回明确错误，并在必要时清理刚创建的目录。

调用关系：它是本文件的总调度员。它会调用路径读取和选择函数来决定放哪儿，调用远端 bundle 下载函数把插件拿下来，调用 update_personal_marketplace 把插件写进个人目录册，最后调用 record_plugin_share_local_path 记住映射；如果后面步骤失败，它会把清理工作交给 clean_up_created_checkout_path。

调用图：调用 11 个内部函数（home_dir, clean_up_created_checkout_path, editable_plugin_path_for_checkout, is_checkout_supported_share_marketplace, load_share_local_paths_for_checkout, update_personal_marketplace, record_plugin_share_local_path, download_and_extract_remote_plugin_bundle_to_path, validate_remote_plugin_bundle, new (+1 more)）；外部调用 4 个（validate_plugin_segment, UnexpectedResponse, format!, fetch_remote_plugin_detail_with_download_urls）。

fn is_checkout_supported_share_marketplace(marketplace_name: &str) -> bool

作用：这个函数判断一个远端插件市场是不是允许“签出共享插件”。它像门卫，只放行几种专门表示“别人分享给我”的 marketplace。

数据流：输入一个 marketplace 名字。它把这个名字和三种受支持的共享 marketplace 常量做比较。输出 true 表示可以继续签出，输出 false 表示这个来源不支持签出。

调用关系：checkout_remote_plugin_share 在拿到远端详情后会用它做资格检查。它不做下载，也不改文件，只负责回答“这个来源能不能走签出流程”。

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

fn load_share_local_paths_for_checkout(
    codex_home: &Path,
) -> Result<BTreeMap<String, AbsolutePathBuf>, RemotePluginCatalogError>

作用：这个函数读取“远端共享插件 ID 对应本地路径”的记录。它的作用是让同一个共享插件下次签出时能找到以前的位置，而不是盲目新建一个目录。

数据流：输入 Codex 的本机目录。它调用本地路径模块读取映射表；如果文件内容坏到无法解析，它把映射当作空表处理；如果是其他读取错误，就包装成远端插件目录错误。输出一个按远端插件 ID 排列的路径表。

调用关系：checkout_remote_plugin_share 在决定本地插件位置前会调用它。它把底层 local_paths::load_plugin_share_local_paths 的磁盘读取结果，整理成签出流程能直接使用的形式。

调用图：调用 1 个内部函数（load_plugin_share_local_paths）；被 1 处调用（checkout_remote_plugin_share）；外部调用 3 个（new, UnexpectedResponse, format!）。

fn editable_plugin_path_for_checkout(
    home: &AbsolutePathBuf,
    plugin_name: &str,
    remote_plugin_id: &str,
    local_paths: &BTreeMap<String, AbsolutePathBuf>,
) -> Result<(AbsolutePathBuf,

作用：这个函数决定共享插件应该放在本机哪个目录，并判断它是不是已经签出过。它防止新下载的插件覆盖用户已有文件。

数据流：输入用户主目录、插件名、远端插件 ID 和已记录的本地路径表。它先看这个远端 ID 是否已有记录且目录还存在；有的话检查这个路径能不能写进个人 marketplace，然后返回旧路径和“已签出”。没有可用旧路径时，它选择记录里的路径或默认的 home/plugins/插件名，再检查路径是否合法；如果目标已经存在，就报错，避免覆盖。输出本地路径和一个是否已存在的标志。

调用关系：checkout_remote_plugin_share 用它来决定后续是直接复用本地目录，还是下载远端插件包。它会把路径合法性检查交给 ensure_path_can_be_listed_in_personal_marketplace。

调用图：调用 1 个内部函数（ensure_path_can_be_listed_in_personal_marketplace）；被 1 处调用（checkout_remote_plugin_share）；外部调用 1 个（format!）。

fn clean_up_created_checkout_path(
    created_checkout_path: bool,
    local_plugin_path: &AbsolutePathBuf,
    original_err: RemotePluginCatalogError,
) -> RemotePluginCatalogError

作用：这个函数在签出中途失败时做善后。它只在本次流程真的新建了插件目录时才尝试删除，避免误删用户原本的东西。

数据流：输入一个标志，说明是否刚创建过签出路径；再输入本地插件路径和原始错误。如果没有新建路径，它原样返回原始错误；如果新建过，它调用删除函数清掉目录或文件。清理成功时仍返回原始错误；清理失败时返回一个包含“原始错误”和“清理也失败”的新错误。

调用关系：checkout_remote_plugin_share 在下载完成后，如果更新 marketplace 或记录路径失败，会调用它。真正删除文件的动作由 remove_created_checkout_path 完成。

调用图：调用 1 个内部函数（remove_created_checkout_path）；被 1 处调用（checkout_remote_plugin_share）；外部调用 2 个（UnexpectedResponse, format!）。

fn remove_created_checkout_path(local_plugin_path: &AbsolutePathBuf) -> io::Result<()>

作用：这个函数负责实际删除刚签出的本地路径。它会根据路径是目录还是文件，选择合适的删除方式。

数据流：输入一个绝对路径。它先查看这个路径是不是目录；如果是目录，就递归删除整个目录；否则按单个文件删除。输出成功或系统层面的输入输出错误。

调用关系：它只被 clean_up_created_checkout_path 调用，是清理流程里的“真正动手删除”的小工具。

调用图：调用 1 个内部函数（as_path）；被 1 处调用（clean_up_created_checkout_path）；外部调用 2 个（remove_dir_all, remove_file）。

fn ensure_path_can_be_listed_in_personal_marketplace(
    home: &AbsolutePathBuf,
    path: &AbsolutePathBuf,
) -> Result<(), RemotePluginCatalogError>

作用：这个函数检查某个本地插件路径能不能写进个人 marketplace 文件。简单说，它确认这个路径能被表示成相对于用户主目录的安全路径。

数据流：输入用户主目录和候选插件路径。它尝试把候选路径转换成个人 marketplace 使用的相对路径；转换成功就表示可登记，返回成功；转换失败就返回路径不合法的错误。

调用关系：editable_plugin_path_for_checkout 在接受一个本地路径前会调用它。它本身把细节交给 personal_marketplace_relative_plugin_path。

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

fn update_personal_marketplace(
    home: &AbsolutePathBuf,
    plugin_name: &str,
    local_plugin_path: &AbsolutePathBuf,
    install_policy: PluginInstallPolicy,
    auth_policy: PluginAuthPolicy,

作用：这个函数把签出的插件写进用户的个人插件市场文件。这个文件像一本本地插件目录册，系统靠它知道哪里有插件、插件叫什么、安装和登录策略是什么。

数据流：输入用户主目录、插件名、本地插件路径、安装策略、认证策略和可选分类。它算出 marketplace 文件路径和插件相对路径，读取或新建 JSON 文件，检查里面的 name 和 plugins 字段是否合理，然后生成插件条目；如果同名插件已存在且路径相同，就更新它，否则新增。最后把 JSON 美化后原子写入磁盘。输出 marketplace 的名字和文件路径。

调用关系：checkout_remote_plugin_share 下载或复用插件目录后会调用它，把本地目录登记进个人 marketplace。它会调用 read_or_create_personal_marketplace 读文件，personal_marketplace_plugin_entry 造条目，personal_marketplace_relative_plugin_path 算路径，write_json_atomically 安全写回。

调用图：调用 6 个内部函数（invalid_marketplace_file, personal_marketplace_plugin_entry, personal_marketplace_relative_plugin_path, read_or_create_personal_marketplace, write_json_atomically, join）；被 1 处调用（checkout_remote_plugin_share）；外部调用 3 个（validate_plugin_segment, format!, to_string_pretty）。

fn read_or_create_personal_marketplace(
    marketplace_path: &Path,
) -> Result<JsonValue, RemotePluginCatalogError>

作用：这个函数读取个人 marketplace JSON 文件；如果文件还不存在，就造一个默认的空目录册。这样新用户不需要手动创建配置文件。

数据流：输入 marketplace 文件路径。它尝试读取文本并解析成 JSON；如果文件不存在，就返回一个带默认 name、显示名和空 plugins 列表的 JSON 对象；如果文件存在但 JSON 写坏了，就返回“marketplace 文件无效”的错误；如果读取失败，则返回读取错误。

调用关系：update_personal_marketplace 在修改目录册之前会调用它，拿到当前内容或一份默认内容。它不负责写回，只负责准备可修改的 JSON。

调用图：被 1 处调用（update_personal_marketplace）；外部调用 5 个（UnexpectedResponse, format!, json!, from_str, read_to_string）。

fn personal_marketplace_plugin_entry(
    plugin_name: &str,
    relative_plugin_path: &str,
    install_policy: PluginInstallPolicy,
    auth_policy: PluginAuthPolicy,
    category: Option<String>,
)

作用：这个函数生成一个插件在个人 marketplace 里的 JSON 条目。它把插件名、本地路径、安装规则和登录规则整理成系统能识别的格式。

数据流：输入插件名、相对路径、安装策略、认证策略和可选分类。它创建一个 JSON 对象，说明插件来源是本地路径，并填入 policy 字段；如果分类存在且不是空白，还会加上 category。输出这一个插件条目。

调用关系：update_personal_marketplace 需要新增或替换插件记录时会调用它。它会使用安装策略和认证策略的转换函数，把程序里的枚举值变成 JSON 里固定的大写字符串。

调用图：被 1 处调用（update_personal_marketplace）；外部调用 1 个（json!）。

fn plugin_install_policy_value(policy: PluginInstallPolicy) -> &'static str

作用：这个函数把安装策略从程序内部的枚举值翻译成 JSON 文件里的字符串。枚举值可以理解成几种固定选项，字符串则是写进配置文件的文字版本。

数据流：输入一个安装策略：不可安装、可安装、或默认安装。它按固定对应关系返回 NOT_AVAILABLE、AVAILABLE 或 INSTALLED_BY_DEFAULT。它不读文件，也不修改任何状态。

调用关系：personal_marketplace_plugin_entry 在拼出 policy.installation 字段时会用到这个翻译结果，让 marketplace 文件保持远端协议要求的写法。

fn plugin_auth_policy_value(policy: PluginAuthPolicy) -> &'static str

作用：这个函数把认证策略翻译成 JSON 里使用的字符串。认证策略说的是插件什么时候需要登录授权：安装时，或使用时。

数据流：输入一个认证策略。它把 OnInstall 转成 ON_INSTALL，把 OnUse 转成 ON_USE。输出固定字符串，不产生副作用。

调用关系：personal_marketplace_plugin_entry 在拼出 policy.authentication 字段时会用到它，保证写入 marketplace 的认证规则格式统一。

fn personal_marketplace_relative_plugin_path(
    home: &AbsolutePathBuf,
    local_plugin_path: &AbsolutePathBuf,
) -> Result<String, RemotePluginCatalogError>

作用：这个函数把本地插件的绝对路径转换成个人 marketplace 能保存的相对路径。它也顺手做安全检查，防止把主目录外的路径登记进去。

数据流：输入用户主目录和插件绝对路径。它先确认插件路径在用户主目录里面，再逐段检查路径：普通目录名可以保留，当前目录符号会忽略，父目录、根目录、磁盘前缀或非 UTF-8 名字都会报错。最后输出形如 ./plugins/foo 的相对路径；如果路径就是主目录本身，也会报错。

调用关系：ensure_path_can_be_listed_in_personal_marketplace 用它做纯检查，update_personal_marketplace 用它生成真正写进 JSON 的路径。它是防止 marketplace 记录危险路径的关键小闸门。

调用图：调用 2 个内部函数（as_path, to_path_buf）；被 2 处调用（ensure_path_can_be_listed_in_personal_marketplace, update_personal_marketplace）；外部调用 2 个（new, format!）。

fn invalid_marketplace_file(path: &Path, message: &str) -> RemotePluginCatalogError

作用：这个函数统一生成“个人 marketplace 文件有问题”的错误。这样上层看到的错误都带着出问题的文件路径和清楚原因。

数据流：输入文件路径和错误说明文字。它把路径复制到错误对象里，把说明文字作为原因。输出一个 RemotePluginCatalogError::InvalidPluginPath 错误值。

调用关系：update_personal_marketplace 和 read_or_create_personal_marketplace 在发现 JSON 结构不对、字段类型不对或内容非法时会调用它，避免每个地方都手写同样的错误包装。

调用图：被 1 处调用（update_personal_marketplace）；外部调用 1 个（to_path_buf）。

fn write_json_atomically(write_path: &Path, contents: &str) -> io::Result<()>

作用：这个函数用“先写临时文件，再替换目标文件”的方式保存 JSON。这样即使写到一半出问题，也更不容易留下半截损坏的配置文件。

数据流：输入目标文件路径和要写入的文本。它先找到父目录并确保目录存在，然后在同一目录创建临时文件，写入全部内容，最后把临时文件持久化为目标文件。输出成功或输入输出错误。

调用关系：update_personal_marketplace 在准备好新的 marketplace JSON 后调用它。它是最后落盘的一步，负责让文件更新尽量安全。

调用图：被 1 处调用（update_personal_marketplace）；外部调用 3 个（parent, create_dir_all, new_in）。

fn default() -> Self

作用：给工具策略提供一个最宽松的默认值：工具默认可用，并且审批模式是 Auto，也就是系统认为可以自动通过。