TUI 启动、引导和终端所有权

async fn start_embedded_app_server(
    arg0_paths: Arg0DispatchPaths,
    config: Config,
    cli_kv_overrides: Vec<(String, toml::Value)>,
    loader_overrides: LoaderOverrides,
    strict_config: b

作用：启动一个嵌在当前进程里的 app server。app server 可以理解成后台大脑，TUI 通过它读写会话、发请求、处理配置。

数据流：进去的是启动路径、配置、命令行覆盖项、云配置、日志和数据库等材料；它把这些原样整理后交给更通用的 start_embedded_app_server_with；出来的是一个可直接在本进程通信的客户端。

调用关系：start_app_server 在决定使用内置服务时会调用它；测试里的 start_test_embedded_app_server 也用它搭一个临时后台。它本身把具体启动动作委托给 start_embedded_app_server_with。

调用图：调用 1 个内部函数（start_embedded_app_server_with）；被 2 处调用（start_app_server, start_test_embedded_app_server）。

fn uses_remote_workspace(&self) -> bool

作用：判断当前 app server 目标是不是远程工作区。这个判断会影响路径、配置和会话过滤方式。

数据流：进去的是一个目标类型；它检查这个目标是不是 Remote；出来一个真假值，不改动任何东西。

调用关系：thread_params_mode、config_cwd_for_app_server_target、run_ratatui_app 和 should_load_configured_environments 都靠它判断“这次是在本地干活还是远端干活”。

调用图：被 4 处调用（thread_params_mode, config_cwd_for_app_server_target, run_ratatui_app, should_load_configured_environments）；外部调用 1 个（matches!）。

fn thread_params_mode(&self) -> ThreadParamsMode

作用：把 app server 的目标类型转换成启动线程时要用的模式。简单说，就是告诉后台“按远程规则还是本地规则创建会话”。

数据流：进去的是 app server 目标；它先问 uses_remote_workspace；如果是远程就产出 Remote 模式，否则产出 Embedded 模式。

调用关系：run_ratatui_app 和 start_app_server_for_picker 创建 AppServerSession 时会用它，保证会话参数和实际连接方式一致。

调用图：调用 1 个内部函数（uses_remote_workspace）；被 2 处调用（run_ratatui_app, start_app_server_for_picker）。

async fn init_state_db_for_app_server_target(
    config: &Config,
    app_server_target: &AppServerTarget,
) -> std::io::Result<Option<StateDbHandle>>

作用：按当前连接方式准备状态数据库。状态数据库用来记录会话、日志、索引等本地状态。

数据流：进去的是配置和 app server 目标；如果是内置服务，它尝试初始化数据库，失败时包装成带数据库路径的启动错误；如果是远程或本地守护进程，它只尝试拿已有数据库句柄；出来是可选的数据库句柄。

调用关系：run_main 启动时会调用它；选择器和多项测试也调用它。它把真正的数据库动作交给 state_db::try_init 或 state_db::get_state_db。

调用图：调用 2 个内部函数（get_state_db, try_init）；被 5 处调用（run_main, start_embedded_app_server_for_picker, embedded_state_db_corruption_preserves_failed_database_for_cli_recovery, embedded_state_db_failure_is_typed_for_cli_recovery, start_test_embedded_app_server）。

fn remove_legacy_tui_log_file(codex_home: &Path)

作用：删除旧版本留下的 TUI 日志文件，防止一个共享追加日志无限变大。

数据流：进去的是 Codex 主目录；它拼出旧日志路径并尝试删除；没有返回有用结果，失败也不报错，因为这只是尽力清理。

调用关系：run_main 加载配置后会调用它；对应测试确认旧日志会被删除。

调用图：被 2 处调用（run_main, startup_removes_legacy_tui_log_file）；外部调用 2 个（join, remove_file）。

fn remote_addr_has_explicit_port(addr: &str, parsed: &Url) -> bool

作用：检查远程地址里是否真的写了端口号。这里很严格，因为连接远程服务必须明确端口，避免猜错。

数据流：进去的是原始地址字符串和已经解析好的 URL；它查看 URL 端口，也会识别 ws 的 80、wss 的 443 这种显式默认端口；出来是真假值。

调用关系：resolve_remote_addr 用它判断一个 websocket 地址是否合法。它不负责解析完整地址，只负责“端口有没有明说”这一件事。

调用图：被 1 处调用（resolve_remote_addr）；外部调用 4 个（host_str, port, scheme, format!）。

fn websocket_url_supports_auth_token(parsed: &Url) -> bool

作用：判断某个 websocket 地址能不能安全地带认证 token。认证 token 就像临时通行证，不能随便发到不安全地址。

数据流：进去的是解析后的 URL；它允许安全的 wss，也允许本机回环地址上的 ws；出来是真假值。

调用关系：它服务于远程地址认证判断，主要被 remote_addr_supports_auth_token 间接使用来决定是否能给连接加 token。

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

fn resolve_remote_addr(addr: &str) -> color_eyre::Result<RemoteAppServerEndpoint>

作用：把用户写的远程地址字符串变成程序内部能连接的 endpoint。endpoint 就是“后台服务在哪里”的标准说法。

数据流：进去的是类似 ws://host:port、wss://host:port、unix:// 或 unix://PATH 的字符串；它解析、校验端口和路径，必要时补出默认 Unix socket 路径；出来是 websocket 或 Unix socket endpoint，格式不对就报错。

调用关系：命令行层会用它把用户参数变成可连接目标；它内部调用 remote_addr_has_explicit_port、路径解析和 URL 解析；测试覆盖了合法和非法地址。

调用图：调用 2 个内部函数（remote_addr_has_explicit_port, relative_to_current_dir）；被 1 处调用（resolve_remote_addr_rejects_invalid_remote_addresses）；外部调用 5 个（parse, app_server_control_socket_path, find_codex_home, bail!, matches!）。

fn remote_addr_supports_auth_token(endpoint: &RemoteAppServerEndpoint) -> bool

作用：判断一个远程 endpoint 是否适合附带认证 token。这样可以避免把通行证发到不该发的地方。

数据流：进去的是 endpoint；如果是 websocket，它重新解析 URL 并检查安全规则；如果是 Unix socket，直接认为不支持；出来是真假值。

调用关系：它是连接远程服务前的安全辅助判断，依赖 websocket_url_supports_auth_token 的规则。

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

async fn connect_remote_app_server(
    endpoint: RemoteAppServerEndpoint,
) -> color_eyre::Result<AppServerClient>

作用：连接已经存在的远程 app server，而不是在当前进程里启动一个新的。

数据流：进去的是远程 endpoint；它带上客户端名字、版本、通道容量等信息发起连接；出来是统一包装后的远程客户端，连接失败就带上下文报错。

调用关系：start_app_server 在目标是远程或本地守护进程时调用它。它把实际网络或 socket 连接交给 RemoteAppServerClient::connect。

调用图：调用 1 个内部函数（connect）；被 1 处调用（start_app_server）；外部调用 3 个（new, Remote, env!）。

async fn maybe_probe_default_daemon_socket(_codex_home: &Path) -> Option<AbsolutePathBuf>

作用：尝试快速探测默认的本地守护进程 socket 是否可用。守护进程就是已经在后台跑着的 app server。

数据流：进去的是 Codex 主目录；它算出默认 socket 路径，先看文件是否存在，再在很短超时时间内试连；成功返回 socket 路径，失败或超时返回空。

调用关系：run_main 在没有显式远程地址、且当前启动参数可复用时调用它，用来决定是否复用本地后台服务。非 Unix 平台上这个函数等价于总是返回空。

调用图：调用 1 个内部函数（connect）；被 1 处调用（run_main）；外部调用 3 个（app_server_control_socket_path, timeout, debug!）。

async fn start_app_server(
    target: &AppServerTarget,
    arg0_paths: Arg0DispatchPaths,
    config: Config,
    cli_kv_overrides: Vec<(String, toml::Value)>,
    loader_overrides: LoaderOverrides,

作用：根据目标类型统一启动或连接 app server。调用方不用关心具体是内置、守护进程还是远程。

数据流：进去的是目标、配置、覆盖项、云配置、日志、数据库和环境管理器；它按目标分支：内置就启动，远程或本地守护进程就连接；出来是统一的 AppServerClient。

调用关系：run_ratatui_app 和 start_app_server_for_picker 都通过它拿后台连接。它把内置情况交给 start_embedded_app_server，远程情况交给 connect_remote_app_server。

调用图：调用 2 个内部函数（connect_remote_app_server, start_embedded_app_server）；被 2 处调用（run_ratatui_app, start_app_server_for_picker）。

async fn start_app_server_for_picker(
    config: &Config,
    target: &AppServerTarget,
    state_db: Option<StateDbHandle>,
    environment_manager: Arc<EnvironmentManager>,
) -> color_eyre::Result<

作用：专门为会话选择器启动一个 app server 会话。会话选择器用来列出、恢复或分叉旧聊天。

数据流：进去的是配置、目标、可选状态数据库和环境管理器；它用一组默认启动参数启动 app server，再包装成 AppServerSession；出来的是可供选择器调用的会话对象。

调用关系：测试辅助函数 start_embedded_app_server_for_picker 会调用它；它内部走 start_app_server，再用 thread_params_mode 决定会话参数模式。

调用图：调用 5 个内部函数（default, new, thread_params_mode, new, start_app_server）；被 1 处调用（start_embedded_app_server_for_picker）；外部调用 4 个（new, clone, default, default）。

async fn start_embedded_app_server_for_picker(
    config: &Config,
) -> color_eyre::Result<AppServerSession>

作用：测试中使用的快捷函数，用内置 app server 启动一个选择器用会话。

数据流：进去的是配置；它先初始化内置服务需要的状态数据库，再用测试环境管理器启动选择器会话；出来是 AppServerSession。

调用关系：这是测试专用路径，组合了 init_state_db_for_app_server_target 和 start_app_server_for_picker，方便测试不必重复写启动步骤。

调用图：调用 3 个内部函数（default_for_tests, init_state_db_for_app_server_target, start_app_server_for_picker）；外部调用 1 个（new）。

async fn start_embedded_app_server_with(
    arg0_paths: Arg0DispatchPaths,
    config: Config,
    cli_kv_overrides: Vec<(String, toml::Value)>,
    loader_overrides: LoaderOverrides,
    strict_conf

作用：内置 app server 的通用启动器，允许把“真正启动客户端”的函数作为参数传进来。这样正式代码和测试都能复用同一套组装逻辑。

数据流：进去的是配置、覆盖项、日志、数据库、环境管理器和一个启动函数；它把配置警告整理成通知，组装完整启动参数，再调用传入的启动函数；出来是内置客户端，失败时加上“启动内置服务失败”的说明。

调用关系：start_embedded_app_server 正式使用它；测试 embedded_app_server_start_failure_is_returned 用自定义失败启动函数验证错误信息。

调用图：被 2 处调用（start_embedded_app_server, embedded_app_server_start_failure_is_returned）；外部调用 5 个（new, new, env!, from_value, json!）。

async fn shutdown_app_server_if_present(app_server: Option<AppServerSession>)

作用：如果手上还有临时 app server 会话，就把它关掉。这样退出选择器或引导流程时不会留下后台任务。

数据流：进去的是可选 app server 会话；有值就调用关闭，失败只写警告；没有值就什么也不做。

调用关系：run_ratatui_app 在用户退出、找不到会话等早退路径里调用它，做收尾清理。

调用图：被 1 处调用（run_ratatui_app）；外部调用 1 个（warn!）。

fn session_target_from_app_server_thread(
    thread: AppServerThread,
) -> Option<resume_picker::SessionTarget>

作用：把 app server 返回的线程信息转换成 TUI 恢复会话时需要的目标对象。

数据流：进去的是 app server 的 thread；它解析 thread id，保留会话文件路径；解析成功返回 SessionTarget，失败写警告并返回空。

调用关系：按名称查找、按 ID 查找、查最新会话时都会用它把后台结果变成选择器能理解的格式。

调用图：调用 1 个内部函数（from_string）；被 2 处调用（lookup_session_target_by_name_with_app_server, lookup_session_target_with_app_server）；外部调用 1 个（warn!）。

fn resume_source_kinds(include_non_interactive: bool) -> Vec<ThreadSourceKind>

作用：决定恢复会话时要查哪些来源的线程。来源可以理解成会话最初是从 CLI、VS Code、执行器等哪里来的。

数据流：进去的是是否包含非交互会话的开关；它默认放入 CLI 和 VS Code，需要时再加入 Exec 和 AppServer；出来是来源列表。

调用关系：latest_session_lookup_params 用它生成查询参数，保证“恢复最近会话”时查的范围符合用户选项。

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

async fn lookup_session_target_by_name_with_app_server(
    app_server: &mut AppServerSession,
    name: &str,
) -> color_eyre::Result<Option<resume_picker::SessionTarget>>

作用：按会话名称从 app server 查找可恢复的会话。用户传的不是 UUID 时，就会走这种标题搜索。

数据流：进去的是 app server 会话和名称；它分页请求线程列表，每页最多 100 条，找标题完全相同的线程；找到就转成 SessionTarget，翻完还没有就返回空。

调用关系：lookup_session_target_with_app_server 在判断输入不是 UUID 后调用它；测试确认它会使用后台标题搜索。

调用图：调用 2 个内部函数（thread_list, session_target_from_app_server_thread）；被 2 处调用（lookup_session_target_with_app_server, lookup_session_target_by_name_uses_backend_title_search）；外部调用 1 个（vec!）。

async fn lookup_session_target_with_app_server(
    app_server: &mut AppServerSession,
    id_or_name: &str,
) -> color_eyre::Result<Option<resume_picker::SessionTarget>>

作用：按用户输入的“会话 ID 或名称”查找会话。用户不需要区分自己输入的是 UUID 还是标题。

数据流：进去的是 app server 会话和字符串；如果像 UUID，就按 ID 读取线程；否则按名称搜索；成功返回 SessionTarget，失败或找不到返回空并写警告。

调用关系：run_ratatui_app 在 --resume <id> 和 --fork <id> 时调用它；它会把名称搜索交给 lookup_session_target_by_name_with_app_server。

调用图：调用 4 个内部函数（from_string, thread_read, lookup_session_target_by_name_with_app_server, session_target_from_app_server_thread）；被 1 处调用（run_ratatui_app）；外部调用 2 个（parse_str, warn!）。

async fn lookup_latest_session_target_with_app_server(
    app_server: &mut AppServerSession,
    config: &Config,
    cwd_filter: Option<&Path>,
    include_non_interactive: bool,
) -> color_eyre::Re

作用：查找最近一次可恢复或可分叉的会话。它还会处理老会话没有进数据库的情况。

数据流：进去的是 app server、配置、可选当前目录过滤、是否包含非交互会话；它先只查状态数据库，再允许扫描并修复旧记录；找到存在的本地路径或远程目标就返回，否则返回空。

调用关系：run_ratatui_app 在 --resume --last 和 --fork --last 时使用它；测试验证它会按目录过滤，也会在数据库缺记录时回退扫描。

调用图：调用 3 个内部函数（thread_list, uses_remote_workspace, latest_session_lookup_params）；被 3 处调用（run_ratatui_app, fork_last_filters_latest_session_by_cwd_unless_show_all, latest_session_lookup_falls_back_for_rollout_missing_from_state_db）。

fn latest_session_lookup_params(
    uses_remote_workspace: bool,
    config: &Config,
    cwd_filter: Option<&Path>,
    include_non_interactive: bool,
    lookup_mode: LatestSessionLookupMode,
) ->

作用：生成“查最近会话”的请求参数。它把远程、本地、目录过滤、来源过滤这些规则集中到一个地方。

数据流：进去的是是否远程、配置、可选目录、是否包含非交互来源和查询模式；它生成限制 1 条、按更新时间排序、必要时带模型和目录过滤的参数；出来是 ThreadListParams。

调用关系：lookup_latest_session_target_with_app_server 用它实际发请求；多项测试检查本地、远程、目录和来源过滤是否正确。

调用图：调用 1 个内部函数（resume_source_kinds）；被 6 处调用（lookup_latest_session_target_with_app_server, latest_session_lookup_params_can_include_non_interactive_sources, latest_session_lookup_params_keep_explicit_cwd_filter_for_remote_sessions, latest_session_lookup_params_keep_local_filters_for_embedded_sessions, latest_session_lookup_params_keep_local_filters_for_local_daemon_sessions, latest_session_lookup_params_omit_local_filters_for_remote_sessions）；外部调用 1 个（vec!）。

fn config_cwd_for_app_server_target(
    cwd: Option<&Path>,
    app_server_target: &AppServerTarget,
    environment_manager: &EnvironmentManager,
) -> std::io::Result<Option<AbsolutePathBuf>>

作用：决定加载配置时该不该带当前工作目录。远程工作区的路径可能不是本机路径，所以不能随便在本机校验。

数据流：进去的是可选 cwd、app server 目标和环境管理器；远程目标或远程执行环境直接返回空；本地则把 cwd 规范化成绝对路径；路径不存在会报错。

调用关系：run_main 加载配置前调用它；多项测试覆盖远程跳过、本地规范化、缺失路径报错等情况。

调用图：调用 4 个内部函数（default_environment, uses_remote_workspace, current_dir, from_absolute_path）；被 6 处调用（run_main, config_cwd_for_app_server_target_canonicalizes_embedded_cli_cwd, config_cwd_for_app_server_target_canonicalizes_local_daemon_cli_cwd, config_cwd_for_app_server_target_errors_for_missing_embedded_cli_cwd, config_cwd_for_app_server_target_omits_cwd_for_remote_exec_server, config_cwd_for_app_server_target_omits_cwd_for_remote_sessions）；外部调用 1 个（canonicalize_existing_preserving_symlinks）。

fn should_load_configured_environments(
    loader_overrides: &LoaderOverrides,
    app_server_target: &AppServerTarget,
) -> bool

作用：判断是否应该读取用户配置里的执行环境。远程工作区不能套用本地配置环境。

数据流：进去的是加载覆盖项和 app server 目标；如果没有忽略用户配置且不是远程工作区，就返回真；否则返回假。

调用关系：run_main 用它决定 EnvironmentManager 是从 Codex 主目录加载，还是只从当前环境变量创建。

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

fn latest_session_cwd_filter(
    uses_remote_workspace: bool,
    remote_cwd_override: Option<&'a Path>,
    config: &'a Config,
    show_all: bool,
) -> Option<&'a Path>

作用：决定“最近会话”查询要不要限定当前目录。这样 --last 默认更符合“当前项目”的直觉。

数据流：进去的是是否远程、远程 cwd 覆盖、本地配置和是否显示全部；如果显示全部就不加过滤；远程用远程 cwd；本地用配置里的 cwd；出来是可选路径。

调用关系：run_ratatui_app 在 resume/fork latest 路径调用它；测试验证 show-all、本地和远程三种情况。

调用图：被 3 处调用（run_ratatui_app, fork_last_filters_latest_session_by_cwd_unless_show_all, latest_session_cwd_filter_respects_scope_options）。

fn app_server_target_for_launch(
    explicit_remote_endpoint: Option<RemoteAppServerEndpoint>,
    default_daemon_socket: Option<AbsolutePathBuf>,
    can_reuse_implicit_local_daemon: bool,
) -> AppS

作用：决定这次启动应该用显式远程服务、默认本地守护进程，还是内置服务。

数据流：进去的是显式远程 endpoint、探测到的默认 socket、是否允许复用本地守护进程；显式远程优先，其次可复用时用默认 socket，否则用内置；出来是 AppServerTarget。

调用关系：run_main 在探测守护进程后调用它；测试覆盖显式远程优先、默认 socket 使用、不能复用时回退内置。

调用图：被 4 处调用（run_main, app_server_target_for_launch_prefers_explicit_remote_endpoint, app_server_target_for_launch_skips_local_daemon_when_launch_config_is_not_replayable, app_server_target_for_launch_uses_local_daemon_for_default_socket）。

fn loader_overrides_are_default(loader_overrides: &LoaderOverrides) -> bool

作用：判断配置加载覆盖项是不是完全默认。只有默认时，才比较安全地复用已有本地守护进程。

数据流：进去的是 LoaderOverrides；它逐项检查用户配置路径、系统配置、管理配置、忽略开关等是否都没改；出来是真假值。

调用关系：can_reuse_implicit_local_daemon 调用它，作为判断守护进程能不能复用的一部分。

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

fn can_reuse_implicit_local_daemon(
    cli_kv_overrides: &[(String, toml::Value)],
    loader_overrides: &LoaderOverrides,
    strict_config: bool,
    has_non_replayable_launch_overrides: bool,
) ->

作用：判断这次启动能不能复用已经跑着的本地守护进程。因为守护进程没法完全吸收这次命令行的所有临时配置。

数据流：进去的是命令行配置覆盖、加载覆盖、严格配置开关和不可重放覆盖标记；它要求这些都接近默认；出来是真假值。

调用关系：run_main 用它决定要不要探测默认 daemon socket；它内部依赖 loader_overrides_are_default。

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

async fn run_main(
    mut cli: Cli,
    arg0_paths: Arg0DispatchPaths,
    loader_overrides: LoaderOverrides,
    explicit_remote_endpoint: Option<RemoteAppServerEndpoint>,
) -> std::io::Result<AppEx

作用：这是 TUI 库层面的主启动流程。它把命令行参数、配置、认证、日志、数据库、后台服务选择等都准备好，然后进入真正的终端界面。

数据流：进去的是 CLI 参数、可执行文件路径、配置加载覆盖和可选远程 endpoint；它解析覆盖项，找 Codex 主目录，选择 app server 目标，加载配置和云配置，处理 OSS 模型、登录限制、日志、遥测和状态数据库；最后调用 run_ratatui_app，出来是应用退出信息或 IO 错误。

调用关系：二进制入口通常会调用它。它是启动链的第一大段，负责“上桌前备菜”，最后把运行 UI 的工作交给 run_ratatui_app。

调用图：调用 21 个内部函数（default, resolve_oss_provider, resolve_profile_v2_config_path, from_codex_home, from_env, from_optional_paths, new, originator, set_default_client_residency_requirement, add_dir_warning_message (+11 more)）；外部调用 25 个（default, try_from_default_env, new, other, migrate_personality_if_needed, cloud_config_bundle_loader_for_storage, enforce_login_restrictions, record_process_start_once, sqlite_telemetry_recorder, install_process_db_telemetry (+15 more)）。

async fn run_ratatui_app(
    cli: Cli,
    arg0_paths: Arg0DispatchPaths,
    loader_overrides: LoaderOverrides,
    strict_config: bool,
    app_server_target: AppServerTarget,
    remote_cwd_overri

作用：启动并运行真正的终端用户界面。ratatui 是一个 Rust 终端 UI 库，可以把纯文本终端画成类似应用窗口的界面。

数据流：进去的是已经解析好的 CLI、配置、后台目标、数据库、日志、云配置等；它安装错误报告，初始化终端，启动 app server，跑更新提示、登录/信任引导、会话恢复或分叉选择，最终调用 App::run；退出前恢复终端并记录会话结束。

调用关系：run_main 准备好外部条件后调用它。它内部会调用大量小函数，比如 start_app_server、get_login_status、determine_alt_screen_mode，最后把主循环交给 App::run。

调用图：调用 29 个内部函数（set_default_client_residency_requirement, thread_params_mode, uses_remote_workspace, new, new, write_config_batch, determine_alt_screen_mode, get_login_status, latest_session_cwd_filter, load_config_or_exit (+15 more)）；被 1 处调用（run_main）；外部调用 26 个（new, now, auth_keyring_backend_kind, clone, clone, run, cloud_config_bundle_loader_for_storage, find_codex_home, install, clone (+15 more)）。

fn restore()

作用：把终端从 TUI 的特殊模式恢复到普通命令行模式。失败时会告诉用户可以运行 reset 或重启终端。

数据流：没有输入；它调用终端恢复函数；如果失败就往标准错误输出提示。

调用关系：TerminalRestoreGuard::restore_silently 用它做兜底恢复，尤其适合出错或崩溃后的清理路径。

调用图：调用 1 个内部函数（restore_after_exit）；被 1 处调用（restore_silently）；外部调用 1 个（eprintln!）。

fn new() -> Self

作用：创建一个终端恢复守卫。守卫就像“离开时自动关灯”的便签，防止忘记恢复终端。

数据流：没有输入；它创建一个 active=true 的守卫；出来是 TerminalRestoreGuard。

调用关系：run_ratatui_app 初始化终端后创建它；之后无论正常退出还是提前返回，守卫都能帮助恢复终端。

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

fn restore(&mut self) -> color_eyre::Result<()>

作用：主动恢复终端，并把守卫标记为已经用过。这个版本会把错误返回给调用方。

数据流：进去的是可变守卫；如果还 active，就调用终端恢复函数并设为 inactive；出来是成功或错误。

调用关系：更新提示选择“执行更新”时会需要先干净恢复终端再退出。它和静默版本共同防止重复恢复。

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

fn restore_silently(&mut self)

作用：静默恢复终端，不把错误往外抛。适合退出清理时尽力而为。

数据流：进去的是可变守卫；如果还 active，就调用 restore 这个普通函数做恢复，然后设为 inactive；没有显式结果。

调用关系：run_ratatui_app 的多个提前退出路径会调用它；drop 也会调用它作为最后保险。

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

fn drop(&mut self)

作用：守卫被销毁时自动恢复终端。这是防止异常路径漏清理的最后一道保险。

数据流：进去的是即将销毁的守卫；它调用 restore_silently；没有返回值。

调用关系：Rust 在变量离开作用域时自动调用它，所以即使 run_ratatui_app 中途返回，也会尽量恢复终端。

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

fn determine_alt_screen_mode(no_alt_screen: bool, tui_alternate_screen: AltScreenMode) -> bool

作用：决定是否使用终端的备用屏幕。备用屏幕像临时白板，退出后能保留原来的命令行滚动内容。

数据流：进去的是 --no-alt-screen 开关和配置里的备用屏幕模式；命令行禁用优先，否则只要配置不是 Never 就启用；出来是真假值。

调用关系：run_ratatui_app 在启动主界面前调用它；测试确认 auto、always、never 和命令行禁用的行为。

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

async fn get_login_status(
    app_server: &mut AppServerSession,
    config: &Config,
) -> color_eyre::Result<LoginStatus>

作用：轻量读取当前登录状态。它避免做完整 bootstrap，因为完整流程可能触发模型列表请求和限流等待。

数据流：进去的是 app server 会话和配置；如果模型提供商不需要 OpenAI 登录，直接返回未认证；否则读取账户信息，区分 API key、ChatGPT 或无登录；出来是 LoginStatus。

调用关系：run_ratatui_app 用它决定是否显示登录引导。它把实际账户读取交给 app_server.read_account。

调用图：调用 1 个内部函数（read_account）；被 1 处调用（run_ratatui_app）；外部调用 1 个（AuthMode）。

async fn load_config_or_exit(
    cli_kv_overrides: Vec<(String, toml::Value)>,
    overrides: ConfigOverrides,
    loader_overrides: LoaderOverrides,
    cloud_config_bundle: CloudConfigBundleLoader,

作用：加载完整配置；如果失败，就打印错误并直接退出进程。它用于启动阶段的硬性配置读取。

数据流：进去的是命令行覆盖、程序覆盖、加载覆盖、云配置和严格配置开关；它把工作交给带 fallback cwd 的版本，fallback 为空；出来是 Config，失败不会返回。

调用关系：run_main 和 run_ratatui_app 多次调用它，尤其在登录、信任、恢复会话后需要重新加载配置时。

调用图：调用 1 个内部函数（load_config_or_exit_with_fallback_cwd）；被 2 处调用（run_main, run_ratatui_app）。

async fn load_config_or_exit_with_fallback_cwd(
    cli_kv_overrides: Vec<(String, toml::Value)>,
    overrides: ConfigOverrides,
    loader_overrides: LoaderOverrides,
    cloud_config_bundle: CloudC

作用：加载完整配置，并允许给恢复/分叉会话提供一个备用工作目录。失败时直接结束程序。

数据流：进去的是各种覆盖项、云配置、严格模式和可选 fallback cwd；它用 ConfigBuilder 一步步设置后构建配置；成功返回配置，失败打印错误并 exit(1)。

调用关系：load_config_or_exit 包装它；run_ratatui_app 在恢复或分叉旧会话、需要换 cwd 时直接调用它。

调用图：被 2 处调用（load_config_or_exit, run_ratatui_app）；外部调用 3 个（default, eprintln!, exit）。

async fn load_bootstrap_config_or_exit(
    codex_home: &Path,
    cwd: Option<&AbsolutePathBuf>,
    cli_kv_overrides: Vec<(String, codex_config::TomlValue)>,
    loader_overrides: LoaderOverrides,

作用：加载较早期、较轻量的 config.toml 结果，用来决定后续云配置、认证存储和 OSS 提供商等启动信息。

数据流：进去的是 Codex 主目录、可选 cwd、命令行覆盖、加载覆盖、严格配置和云配置加载器；它读取配置层栈；成功返回 ConfigTomlLoadResult，失败打印带来源位置的配置错误并退出。

调用关系：run_main 在完整配置前调用它；这让启动流程能先知道云配置和认证相关设置。

调用图：调用 1 个内部函数（load_config_toml_with_layer_stack）；被 1 处调用（run_main）；外部调用 2 个（eprintln!, exit）。

fn should_show_trust_screen(config: &Config) -> bool

作用：判断是否要显示“是否信任当前目录”的提示。信任决定会影响工具执行时的安全限制。

数据流：进去的是配置；它查看当前项目是否已经有 trust_level；没有就返回真，有就返回假。

调用关系：run_ratatui_app 用它决定是否进入引导流程；多项测试验证未决定、已不信任等情况。

调用图：被 4 处调用（run_ratatui_app, untrusted_project_skips_trust_prompt, windows_shows_trust_prompt_with_sandbox, windows_shows_trust_prompt_without_sandbox）。

fn should_show_onboarding(
    login_status: LoginStatus,
    config: &Config,
    show_trust_screen: bool,
) -> bool

作用：判断是否要显示首次引导流程。只要需要目录信任确认，或需要登录，就应该显示。

数据流：进去的是登录状态、配置和是否显示信任页；信任页需要时直接返回真，否则再看登录页是否需要；出来是真假值。

调用关系：run_ratatui_app 用它决定是否调用 onboarding 应用；它把登录判断交给 should_show_login_screen。

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

fn should_show_login_screen(login_status: LoginStatus, config: &Config) -> bool

作用：判断是否要显示登录页。只有需要 OpenAI 类认证的模型提供商，并且当前未登录，才显示。

数据流：进去的是登录状态和配置；它先看模型提供商是否要求 OpenAI 登录，再看状态是不是未认证；出来是真假值。

调用关系：run_ratatui_app 和 should_show_onboarding 都会用它来决定引导页面组成。

调用图：被 2 处调用（run_ratatui_app, should_show_onboarding）。

async fn build_config(temp_dir: &TempDir) -> std::io::Result<Config>

作用：测试用的小工具，用临时目录快速构建一份配置。

数据流：进去的是临时目录；它把该目录设为 Codex home 并调用配置构建器；出来是测试用 Config。

调用关系：很多测试通过它减少重复代码，保证每个测试都有隔离的配置目录。

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

fn write_session_rollout(
        codex_home: &Path,
        filename_ts: &str,
        meta_rfc3339: &str,
        preview: &str,
        model_provider: &str,
        cwd: &Path,
    ) -> color_eyre

作用：测试用的小工具，手写一个假的会话记录文件。rollout 文件可以理解成保存聊天历史的一行行 JSON 日志。

数据流：进去的是 Codex home、时间戳、预览文字、模型提供商和 cwd；它创建会话目录和 JSONL 文件，写入元信息和用户消息，并设置修改时间；出来是新建的线程 ID。

调用关系：恢复最近会话相关测试用它制造旧会话，之后再让 app server 搜索这些会话。

调用图：调用 1 个内部函数（from_string）；外部调用 12 个（default, join, to_path_buf, new_v4, parse_from_rfc3339, format!, json!, to_value, new, new (+2 more)）。

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

作用：验证启动清理会删除旧 TUI 日志文件。

数据流：它创建临时日志文件，调用 remove_legacy_tui_log_file，再断言文件不存在；测试通过说明清理逻辑有效。

调用关系：直接覆盖 remove_legacy_tui_log_file 的行为，防止以后改动导致旧日志继续累积。

调用图：调用 1 个内部函数（remove_legacy_tui_log_file）；外部调用 4 个（new, assert!, create_dir_all, write）。

async fn start_test_embedded_app_server(
        config: Config,
    ) -> color_eyre::Result<InProcessAppServerClient>

作用：测试用快捷启动内置 app server。

数据流：进去的是配置；它初始化状态数据库，用测试环境管理器启动内置 app server；出来是 InProcessAppServerClient。

调用关系：多个需要真实后台能力的测试调用它，比如线程启动、会话查找、最近会话扫描。

调用图：调用 5 个内部函数（default, default_for_tests, new, init_state_db_for_app_server_target, start_embedded_app_server）；外部调用 4 个（new, new, default, default）。

fn alternate_screen_auto_uses_alt_screen()

作用：验证备用屏幕模式的选择规则。

数据流：它用不同的命令行开关和配置值调用 determine_alt_screen_mode，再断言结果符合预期。

调用关系：保护终端显示模式逻辑，避免未来改动让 auto、always、never 行为反了。

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

fn session_target_display_label_falls_back_to_thread_id()

作用：验证没有会话路径时，显示标签会退回到线程 ID。

数据流：它创建一个只有 thread id、没有路径的 SessionTarget，读取显示标签，并断言里面是 thread id。

调用关系：保障恢复选择器在缺少文件路径时仍然能给用户一个可识别的名字。

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

fn resolve_remote_addr_accepts_websocket_url()

作用：验证普通 websocket 远程地址会被接受。

数据流：它输入 ws://127.0.0.1:4500，检查解析结果是否是带规范化斜杠的 websocket endpoint。

调用关系：覆盖 resolve_remote_addr 的合法 ws 地址路径。

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

fn resolve_remote_addr_accepts_secure_websocket_url()

作用：验证安全 websocket 地址会被接受。

数据流：它输入 wss://example.com:443，检查解析结果是否规范化为 websocket endpoint。

调用关系：覆盖 resolve_remote_addr 对 wss 和显式默认端口的处理。

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

fn resolve_remote_addr_accepts_default_socket() -> color_eyre::Result<()>

作用：验证 unix:// 会表示默认本地 socket。

数据流：它找到 Codex home，解析 unix://，再断言结果等于默认控制 socket 路径。

调用关系：覆盖 resolve_remote_addr 的默认 Unix socket 分支。

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

fn resolve_remote_addr_accepts_relative_socket_path() -> color_eyre::Result<()>

作用：验证相对 Unix socket 路径会被接受。

数据流：它输入 unix://codex.sock，解析后断言路径被转成相对当前目录的绝对路径表示。

调用关系：覆盖 resolve_remote_addr 对用户自定义相对 socket 路径的处理。

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

fn resolve_remote_addr_accepts_absolute_socket_path() -> color_eyre::Result<()>

作用：验证绝对 Unix socket 路径会被接受。

数据流：它在临时目录拼出 socket 路径，解析 unix://绝对路径，断言结果等于该绝对路径。

调用关系：覆盖 resolve_remote_addr 对绝对 socket 路径的处理。

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

fn resolve_remote_addr_rejects_invalid_remote_addresses()

作用：验证不合规远程地址会被拒绝。

数据流：它遍历没有端口、缺少协议、错误协议等地址，调用 resolve_remote_addr，断言错误信息提示支持的格式。

调用关系：保护远程地址解析的严格性，直接测试 resolve_remote_addr。

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

async fn default_daemon_auto_connect_skips_missing_socket() -> color_eyre::Result<()>

作用：验证默认 daemon socket 不存在时不会尝试复用。

数据流：它创建空临时 Codex home，调用 maybe_probe_default_daemon_socket，断言返回空。

调用关系：覆盖自动连接本地守护进程的“没有 socket 就跳过”路径。

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

async fn default_daemon_auto_connect_probes_socket_only() -> color_eyre::Result<()>

作用：在 Unix 上验证存在且可连接的默认 socket 会被探测到。

数据流：它创建默认 socket 路径并绑定一个 Unix listener，然后调用探测函数，断言返回该路径。

调用关系：覆盖 maybe_probe_default_daemon_socket 的成功路径。

调用图：调用 1 个内部函数（bind）；外部调用 4 个（new, assert_eq!, app_server_control_socket_path, create_dir_all）。

fn app_server_target_for_launch_uses_local_daemon_for_default_socket() -> color_eyre::Result<()>

作用：验证允许复用时，默认 socket 会让启动目标变成本地守护进程。

数据流：它传入默认 socket、没有显式远程 endpoint、允许复用；断言结果是 LocalDaemon，且不算远程工作区。

调用关系：直接测试 app_server_target_for_launch 和相关目标判断。

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

fn app_server_target_for_launch_prefers_explicit_remote_endpoint() -> color_eyre::Result<()>

作用：验证显式远程地址优先级最高。

数据流：它同时给显式 endpoint 和默认 socket，调用目标选择函数，断言结果是显式 Remote。

调用关系：保护 app_server_target_for_launch 的优先级规则。

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

fn app_server_target_for_launch_skips_local_daemon_when_launch_config_is_not_replayable() -> color_eyre::Result<()>

作用：验证当前启动配置不能复用时，即使有默认 socket 也不用本地守护进程。

数据流：它传入 socket 但把允许复用设为假，断言目标回到 Embedded。

调用关系：覆盖 app_server_target_for_launch 的安全回退逻辑。

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

fn can_reuse_implicit_local_daemon_requires_default_launch_config() -> color_eyre::Result<()>

作用：验证复用本地守护进程必须满足“启动配置接近默认”。

数据流：它分别加入 CLI 覆盖、忽略用户配置、严格配置、不可重放覆盖等情况，断言只有完全默认时返回真。

调用关系：直接测试 can_reuse_implicit_local_daemon 和间接的 loader_overrides_are_default。

调用图：外部调用 3 个（assert!, default, vec!）。

fn should_load_configured_environments_for_local_daemon() -> color_eyre::Result<()>

作用：验证本地守护进程仍然应该加载配置里的执行环境。

数据流：它构造 LocalDaemon 目标和默认加载覆盖，调用 should_load_configured_environments，断言返回真。

调用关系：保护本地 daemon 与远程 workspace 的区分逻辑。

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

async fn latest_session_lookup_params_keep_local_filters_for_embedded_sessions() -> std::io::Result<()>

作用：验证内置本地会话查询会保留模型和目录过滤。

数据流：它构造本地配置和 cwd，生成最近会话查询参数，断言模型提供商、cwd 和只查数据库标记正确。

调用关系：直接覆盖 latest_session_lookup_params 的本地内置分支。

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

async fn latest_session_lookup_params_keep_local_filters_for_local_daemon_sessions() -> color_eyre::Result<()>

作用：验证本地守护进程会话查询也保留本地过滤条件。

数据流：它构造 LocalDaemon 目标和 cwd，生成查询参数，断言模型和 cwd 过滤存在。

调用关系：防止把本地 daemon 错当远程 workspace，测试 latest_session_lookup_params。

调用图：调用 2 个内部函数（latest_session_lookup_params, relative_to_current_dir）；外部调用 3 个（new, assert_eq!, build_config）。

async fn latest_session_lookup_params_omit_local_filters_for_remote_sessions() -> std::io::Result<()>

作用：验证远程会话查询不会带本地模型和本地目录过滤。

数据流：它用远程标记生成查询参数，断言模型提供商和 cwd 都为空。

调用关系：覆盖 latest_session_lookup_params 的远程分支，避免拿本机路径过滤远端会话。

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

async fn latest_session_lookup_params_can_include_non_interactive_sources() -> std::io::Result<()>

作用：验证用户要求时，最近会话查询会包含非交互来源。

数据流：它开启 include_non_interactive，生成查询参数，断言来源列表包含 CLI、VS Code、Exec 和 AppServer。

调用关系：测试 latest_session_lookup_params 通过 resume_source_kinds 扩展来源列表。

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

async fn latest_session_lookup_params_keep_explicit_cwd_filter_for_remote_sessions() -> std::io::Result<()>

作用：验证远程会话如果明确给了远程 cwd，也会带上这个过滤条件。

数据流：它用远程标记和 repo/on/server 路径生成查询参数，断言 cwd 过滤被保留，模型过滤为空。

调用关系：覆盖远程 workspace 下由用户或参数提供 cwd 的特殊情况。

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

async fn latest_session_cwd_filter_respects_scope_options() -> std::io::Result<()>

作用：验证最近会话 cwd 过滤会遵守本地、远程和 show-all 选项。

数据流：它分别测试本地默认、显示全部、远程覆盖三种输入，断言返回的路径或空值正确。

调用关系：直接测试 latest_session_cwd_filter，保证 resume/fork latest 的范围符合用户预期。

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

async fn fork_last_filters_latest_session_by_cwd_unless_show_all() -> color_eyre::Result<()>

作用：验证 fork --last 默认按当前目录找最近会话，但 show-all 会跨目录找。

数据流：它写入两个不同目录、不同时间的假会话，启动内置 app server，然后分别按当前目录和全局查询，断言返回不同的线程 ID。

调用关系：组合测试 latest_session_cwd_filter、lookup_latest_session_target_with_app_server 和 app server 的会话搜索能力。

调用图：调用 3 个内部函数（new, latest_session_cwd_filter, lookup_latest_session_target_with_app_server）；外部调用 8 个（default, new, InProcess, assert_eq!, default, create_dir_all, start_test_embedded_app_server, write_session_rollout）。

async fn latest_session_lookup_falls_back_for_rollout_missing_from_state_db() -> color_eyre::Result<()>

作用：验证最近会话如果没进状态数据库，也能通过扫描旧会话文件找回来。

数据流：它先启动 app server，再模拟老写入者创建 rollout 文件，调用最近会话查找，断言能找到该线程。

调用关系：覆盖 lookup_latest_session_target_with_app_server 的“先查数据库，再扫描修复”回退流程。

调用图：调用 2 个内部函数（new, lookup_latest_session_target_with_app_server）；外部调用 8 个（default, new, InProcess, assert_eq!, default, create_dir_all, start_test_embedded_app_server, write_session_rollout）。

async fn config_cwd_for_app_server_target_omits_cwd_for_remote_sessions() -> std::io::Result<()>

作用：验证远程 app server 目标不会用本机 cwd 加载配置。

数据流：它传入一个可能不存在的本机路径和远程目标，调用 config_cwd_for_app_server_target，断言返回空。

调用关系：保护远程 workspace 不被本地路径检查误伤。

调用图：调用 3 个内部函数（default_for_tests, config_cwd_for_app_server_target, relative_to_current_dir）；外部调用 3 个（new, assert_eq!, cfg!）。

async fn config_cwd_for_app_server_target_canonicalizes_embedded_cli_cwd() -> std::io::Result<()>

作用：验证内置本地目标会把 CLI cwd 规范化。

数据流：它传入临时目录和 Embedded 目标，调用函数，断言结果等于系统规范化后的绝对路径。

调用关系：覆盖 config_cwd_for_app_server_target 的本地内置正常路径。

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

async fn config_cwd_for_app_server_target_canonicalizes_local_daemon_cli_cwd() -> std::io::Result<()>

作用：验证本地守护进程目标也会规范化 CLI cwd。

数据流：它传入临时目录和 LocalDaemon 目标，断言返回规范化绝对路径。

调用关系：证明本地 daemon 和内置目标一样使用本机 cwd 规则。

调用图：调用 3 个内部函数（default_for_tests, config_cwd_for_app_server_target, relative_to_current_dir）；外部调用 2 个（new, assert_eq!）。

async fn config_cwd_for_app_server_target_errors_for_missing_embedded_cli_cwd() -> std::io::Result<()>

作用：验证本地内置目标遇到不存在的 cwd 会报错。

数据流：它构造一个不存在路径，调用 config_cwd_for_app_server_target，断言错误类型是 NotFound。

调用关系：防止配置加载默默接受无效本地目录。

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

async fn config_cwd_for_app_server_target_omits_cwd_for_remote_exec_server() -> std::io::Result<()>

作用：验证即使 app server 是内置的，只要执行环境是远程，也不使用本机 cwd。

数据流：它创建一个测试用远程执行环境管理器，传入本机不存在路径，调用函数，断言返回空。

调用关系：覆盖 config_cwd_for_app_server_target 对远程执行环境的判断。

调用图：调用 3 个内部函数（create_for_tests, new, config_cwd_for_app_server_target）；外部调用 4 个（new, assert_eq!, cfg!, current_exe）。

async fn windows_shows_trust_prompt_without_sandbox() -> std::io::Result<()>

作用：验证项目信任状态未决定时会显示信任提示，即使 Windows 沙盒关闭。

数据流：它构造配置，把项目 trust_level 设为空并关闭 Windows 沙盒，调用 should_show_trust_screen，断言返回真。

调用关系：覆盖信任提示的基础规则。

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

async fn embedded_app_server_supports_thread_start_rpc() -> color_eyre::Result<()>

作用：验证内置 app server 能处理启动线程的 RPC 请求。RPC 是远程过程调用，可以理解成向后台发一个结构化命令。

数据流：它启动测试内置 app server，发送 thread/start 请求，断言返回的 thread id 不为空，然后关闭服务。

调用关系：测试 start_test_embedded_app_server 启动出的后台确实能工作。

调用图：外部调用 6 个（new, Integer, default, assert!, build_config, start_test_embedded_app_server）。

async fn lookup_session_target_by_name_uses_backend_title_search() -> color_eyre::Result<()>

作用：验证按名称查会话会使用后台的标题搜索能力。

数据流：它创建会话文件和状态数据库记录，标题设为 saved-session，启动 app server 后按名称查找，断言返回路径和线程 ID 正确。

调用关系：直接测试 lookup_session_target_by_name_with_app_server，也验证 app server 查询和状态数据库配合正常。

调用图：调用 5 个内部函数（new, new, init, new, lookup_session_target_by_name_with_app_server）；外部调用 12 个（pin, new, InProcess, assert_eq!, parse_from_rfc3339, format!, from_value, json!, create_dir_all, write (+2 more)）。

async fn embedded_app_server_start_failure_is_returned() -> color_eyre::Result<()>

作用：验证内置 app server 启动失败时，错误会被带着上下文返回。

数据流：它调用 start_embedded_app_server_with，传入一个总是返回 boom 的启动函数；断言最终错误包含“failed to start embedded app server”。

调用关系：保护 start_embedded_app_server_with 的错误包装逻辑，让用户看到更有用的错误。

调用图：调用 4 个内部函数（default, default_for_tests, new, start_embedded_app_server_with）；外部调用 8 个（new, new, new, default, assert!, default, panic!, build_config）。

async fn embedded_state_db_failure_is_typed_for_cli_recovery() -> color_eyre::Result<()>

作用：验证内置状态数据库启动失败时，会保留专门的错误类型，方便 CLI 做恢复提示。

数据流：它让 sqlite_home 被一个普通文件占用，调用 init_state_db_for_app_server_target，断言错误里能取出 LocalStateDbStartupError，且路径和详情正确。

调用关系：覆盖内置数据库初始化失败路径，确保错误信息不被普通字符串吞掉。

调用图：调用 1 个内部函数（init_state_db_for_app_server_target）；外部调用 6 个（new, assert!, assert_eq!, panic!, write, build_config）。

async fn embedded_state_db_corruption_preserves_failed_database_for_cli_recovery() -> color_eyre::Result<()>

作用：验证数据库损坏时，错误会指出真正坏掉的数据库文件。

数据流：它写入一个假的 logs 数据库文件，触发初始化失败，然后断言错误里的数据库路径和 SQLite 损坏细节正确。

调用关系：测试 init_state_db_for_app_server_target 对数据库腐坏错误的包装质量。

调用图：调用 1 个内部函数（init_state_db_for_app_server_target）；外部调用 8 个（new, assert!, assert_eq!, logs_db_path, panic!, create_dir_all, write, build_config）。

async fn windows_shows_trust_prompt_with_sandbox() -> std::io::Result<()>

作用：验证项目信任未决定时，即使 Windows 沙盒开启也会显示信任提示。

数据流：它构造配置，把 trust_level 设为空并开启沙盒，调用 should_show_trust_screen，断言应显示提示。

调用关系：补充覆盖 Windows 沙盒相关配置下的信任提示逻辑。

调用图：调用 1 个内部函数（should_show_trust_screen）；外部调用 4 个（new, assert!, cfg!, build_config）。

async fn untrusted_project_skips_trust_prompt() -> std::io::Result<()>

作用：验证已经明确标记为不信任的项目，不会再弹信任选择提示。

数据流：它把项目 trust_level 设为 Untrusted，调用 should_show_trust_screen，断言返回假。

调用关系：保护信任提示只在“未决定”时出现，而不是每次都打扰用户。

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

async fn config_rebuild_changes_trust_defaults_with_cwd() -> std::io::Result<()>

作用：验证换 cwd 后重新构建配置，会让项目级信任默认值跟着变化。

数据流：它写入两个项目的配置，一个 trusted、一个 untrusted，然后分别以两个 cwd 构建配置，断言审批策略不同。

调用关系：覆盖配置重载和项目路径选择的交互，解释为什么恢复/分叉会话后可能要重新加载配置。

调用图：调用 1 个内部函数（without_managed_config_for_tests）；外部调用 7 个（default, new, assert_eq!, default, format!, create_dir_all, write）。

async fn theme_warning_uses_final_config() -> std::io::Result<()>

作用：验证语法高亮主题警告使用最终配置，而不是启动时的旧配置。

数据流：它先构造初始配置，再模拟最终配置里有非法主题名，调用主题名校验，断言警告进入最终配置并包含该主题名。

调用关系：对应 run_ratatui_app 中“所有配置重载之后再设置主题”的重要顺序，防止恢复会话时主题错乱。

调用图：外部调用 4 个（new, assert!, assert_eq!, build_config）。

fn new(lmstudio_status: ProviderStatus, ollama_status: ProviderStatus) -> io::Result<Self>

作用：创建一个选择界面用的小组件。它把 LM Studio 和 Ollama 的运行状态整理成用户能看懂的提示文字和按钮。

数据流：进去的是两个服务的状态：LM Studio 的状态和 Ollama 的状态。它把这些状态变成带颜色符号的文字，比如绿色圆点表示正在运行，再准备好默认选中的选项。出来的是一个可显示、可接收按键的 OssSelectionWidget。

调用关系：select_oss_provider 在需要弹出选择界面时会调用它；测试 tests::ctrl_h_l_move_provider_selection 也会调用它来造一个假界面。它内部会把状态交给 get_status_symbol_and_color，换成适合显示的符号和颜色。

调用图：调用 1 个内部函数（get_status_symbol_and_color）；被 2 处调用（select_oss_provider, ctrl_h_l_move_provider_selection）；外部调用 3 个（from, new, vec!）。

fn get_confirmation_prompt_height(&self, width: u16) -> u16

作用：计算上方说明文字在指定宽度下要占几行。终端宽度不同，文字换行也不同，所以需要动态算高度。

数据流：进去的是当前可用宽度。它询问提示段落在这个宽度下会分成多少行。出来的是一个行数，用来决定界面怎么分区。

调用关系：desired_height 用它告诉外部这个组件大概要多高；render_ref 用它把提示区和按钮区切开，避免文字和按钮挤在一起。

调用图：被 2 处调用（desired_height, render_ref）；外部调用 1 个（line_count）。

fn handle_key_event(&mut self, key: KeyEvent) -> Option<String>

作用：接收用户按下的键，并决定这个键会不会改变选择或完成选择。外部只要把按键交给它，就能拿到最终选择结果。

数据流：进去的是一个键盘事件。它只处理真正按下去的事件，然后交给 handle_select_key 判断具体动作。如果用户已经选完，出来的是所选服务的字符串；如果还没选完，就出来空值。

调用关系：select_oss_provider 的事件循环读到键盘事件后会调用它。它自己不判断所有按键细节，而是把细活交给 handle_select_key。

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

fn normalize_keycode(code: KeyCode) -> KeyCode

作用：把按键变成方便比较的形式，主要是把字母统一转成小写。这样用户按 L 或 l 都能被当成同一个选择。

数据流：进去的是一个按键代码。若它是字母，就转成小写字母；如果是方向键、回车之类，就原样保留。出来的是标准化后的按键代码。

调用关系：handle_select_key 在检查快捷键时会用它，避免因为大小写不同导致快捷键失效。

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

fn handle_select_key(&mut self, key_event: KeyEvent)

作用：真正解释每个按键的含义：左右移动、回车确认、Esc 默认选择、Ctrl+C 取消、字母快捷选择。

数据流：进去的是一个键盘事件。它根据按键修改当前选中的按钮，或者调用 send_decision 写入最终结果。出来没有直接返回值，但会改变组件内部的 selected_option、selection 和 done。

调用关系：handle_key_event 会把按键交给它。它在需要结束选择时调用 send_decision；在比较字母快捷键时调用 normalize_keycode。

调用图：调用 1 个内部函数（send_decision）；被 1 处调用（handle_key_event）；外部调用 1 个（normalize_keycode）。

fn send_decision(&mut self, selection: String)

作用：把用户的最终决定写进组件，并标记这个选择界面已经可以关闭了。

数据流：进去的是一个选择结果字符串，比如某个服务的编号，或者取消用的特殊字符串。它把这个字符串保存到 selection，并把 done 改成 true。出来没有返回值，但组件状态从“还在选择”变成“已完成”。

调用关系：handle_select_key 在用户确认、取消或按快捷键选中服务时调用它。之后 handle_key_event 就能把这个结果交还给外层流程。

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

fn is_complete(&self) -> bool

作用：告诉别人这个选择界面是不是已经完成了。外层界面可以用它判断是否该把这个小组件拿掉。

数据流：它不需要额外输入，只读取组件里的 done 标记。done 是 true 就返回 true，否则返回 false。它不改动任何数据。

调用关系：它是给外部流程查询状态用的小入口；虽然这个文件里的主循环主要通过 handle_key_event 拿结果，但这个方法让组件也能被别的界面队列按“完成状态”管理。

fn desired_height(&self, width: u16) -> u16

作用：估算整个选择组件在当前宽度下需要多少行，方便外层布局预留空间。

数据流：进去的是可用宽度。它先用 get_confirmation_prompt_height 算提示文字高度，再加上选项按钮需要的高度。出来的是总高度。

调用关系：它依赖 get_confirmation_prompt_height 做文字换行计算。这个方法适合被更大的终端界面在排版时调用。

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

fn render_ref(&self, area: Rect, buf: &mut Buffer)

作用：把选择界面画到终端屏幕上。它负责把提示文字、按钮、当前选中高亮和说明文字摆到正确位置。

数据流：进去的是一块屏幕区域和一块绘图缓冲区。它先算提示文字高度，再把区域切成提示区、按钮区和说明区，最后把每一行文字和按钮样式写进缓冲区。出来没有普通返回值，但屏幕缓冲区已经变成可显示的界面内容。

调用关系：select_oss_provider 在终端每次重画时会触发它。它会调用 get_confirmation_prompt_height 来保证布局不会错位，并使用终端 UI 库提供的布局和渲染工具完成绘制。

调用图：调用 1 个内部函数（get_confirmation_prompt_height）；外部调用 9 个（Length, Min, default, horizontal, vertical, from, new, clone, new）。

fn get_status_symbol_and_color(status: &ProviderStatus) -> (&'static str, Color)

作用：把服务状态翻译成用户一眼能看懂的符号和颜色。比如运行中显示绿色实心点，没运行显示红色空心点。

数据流：进去的是 ProviderStatus，也就是服务状态。它匹配状态后，出来一个符号和一个颜色。它不改动外部数据。

调用关系：OssSelectionWidget::new 在生成状态列表时调用它，让界面里的服务状态不只是文字，而是带有直观视觉提示。

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

async fn select_oss_provider() -> io::Result<OssProviderSelection>

作用：这是整个选择流程的主入口。它决定是自动选择本地服务，还是打开终端选择界面让用户手动选。

数据流：它先调用 check_lmstudio_status 和 check_ollama_status 读取两个本地端口的状态。如果只有一个服务运行，就直接返回对应服务，并标记不是手动选择；否则创建 OssSelectionWidget，切换终端到原始输入模式和备用屏幕，循环绘制界面、读取按键，直到拿到用户选择后返回结果。

调用关系：run_main 会在启动流程里调用它。它把探测服务的活交给 check_lmstudio_status 和 check_ollama_status，把界面创建交给 OssSelectionWidget::new，把按键解释交给 widget 的 handle_key_event。

调用图：调用 3 个内部函数（new, check_lmstudio_status, check_ollama_status）；被 1 处调用（run_main）；外部调用 7 个（new, disable_raw_mode, enable_raw_mode, read, execute!, stdout, new）。

async fn check_lmstudio_status() -> ProviderStatus

作用：检查 LM Studio 的默认本地端口，看它像不像正在运行。

数据流：它不需要外部输入，使用预设的 LM Studio 默认端口。它调用 check_port_status 发起一次本机 HTTP 请求，再把结果翻译成 Running、NotRunning 或 Unknown。出来的是 LM Studio 的状态。

调用关系：select_oss_provider 在决定是否自动选择前会调用它。它把真正访问端口的工作交给 check_port_status。

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

async fn check_ollama_status() -> ProviderStatus

作用：检查 Ollama 的默认本地端口，看它像不像正在运行。

数据流：它不需要外部输入，使用预设的 Ollama 默认端口。它调用 check_port_status 去访问本机服务，再把成功、失败或异常翻译成对应状态。出来的是 Ollama 的状态。

调用关系：select_oss_provider 在启动选择流程前会调用它。它和 check_lmstudio_status 用的是同一个底层端口检查函数 check_port_status。

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

async fn check_port_status(port: u16) -> io::Result<bool>

作用：尝试访问本机某个端口，判断那里有没有一个能正常响应的 HTTP 服务。这里的 HTTP 可以理解成浏览器和本地服务说话的常见方式。

数据流：进去的是端口号。它创建一个带 2 秒超时的网络客户端，访问 http://localhost:端口。如果收到成功状态码，就返回 true；如果连不上，就返回 false；如果客户端创建失败，则返回错误。

调用关系：check_lmstudio_status 和 check_ollama_status 都调用它。它是这两个具体服务检查函数共用的底层探针。

调用图：被 2 处调用（check_lmstudio_status, check_ollama_status）；外部调用 3 个（from_secs, builder, format!）。

fn ctrl_h_l_move_provider_selection()

作用：这是一个自动测试，用来确认 Ctrl+L 能向右切换选项，Ctrl+H 能向左切换选项。

数据流：它先创建一个状态未知的选择组件，确认默认选中第一个选项。然后模拟按下 Ctrl+L，检查选中项变成第二个；再模拟 Ctrl+H，检查又回到第一个。出来没有业务结果，测试通过就说明快捷键行为没坏。

调用关系：它直接调用 OssSelectionWidget::new 和 handle_key_event。这个测试保护的是启动选择界面的键盘操作，尤其是某些终端会把方向类操作映射成 Ctrl+H/Ctrl+L 的情况。

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

async fn load_startup_hooks_review_entry(
    request_handle: AppServerRequestHandle,
    cwd: PathBuf,
) -> HooksListEntry

作用：启动时向后台服务读取当前目录的钩子列表，准备后面判断是否要弹出审查界面。如果读取失败，它不会让程序启动失败，而是给出一个空列表继续走。

数据流：进去的是后台请求句柄和当前工作目录 → 它调用 fetch_hooks_list 拉取钩子清单，再从结果里挑出当前目录对应的那一项 → 出来的是 HooksListEntry，也就是这个目录下的钩子、警告和错误；如果拉取失败，就记录警告并返回一个空的 HooksListEntry。

调用关系：这是启动审查流程的前置取数步骤。它把数据准备好后，通常会交给 maybe_run_startup_hooks_review 去决定要不要真的展示审查界面。

调用图：调用 2 个内部函数（fetch_hooks_list, hooks_list_entry_for_cwd）；外部调用 3 个（clone, new, warn!）。

async fn maybe_run_startup_hooks_review(
    app_server: &mut AppServerSession,
    tui: &mut Tui,
    config: &Config,
    bypass_hook_trust: bool,
    entry: HooksListEntry,
) -> Result<StartupHooks

作用：决定启动时要不要进入钩子审查界面。它像一个分叉路口：没风险就放行，有需要确认的钩子才打开交互界面。

数据流：进去的是后台会话、终端界面、配置、是否跳过信任检查的开关，以及钩子列表 → 它先用 review_is_needed 判断是否需要审查 → 如果不需要，返回 Continue；如果需要，就调用 run_startup_hooks_review_app 让用户选择，最后返回用户选择带来的结果。

调用关系：它由 run_ratatui_app 在启动过程中调用，是外层主程序和这个钩子审查小流程之间的入口。它自己不画界面，只负责决定是否把事情交给 run_startup_hooks_review_app。

调用图：调用 2 个内部函数（review_is_needed, run_startup_hooks_review_app）；被 1 处调用（run_ratatui_app）。

async fn run_startup_hooks_review_app(
    app_server: &mut AppServerSession,
    tui: &mut Tui,
    config: &Config,
    entry: HooksListEntry,
) -> Result<StartupHooksReviewOutcome>

作用：真正运行启动时的钩子审查小界面，读取按键，处理用户选择，并在需要时把“信任这些钩子”的决定写入后台。

数据流：进去的是后台会话、TUI 终端界面、配置和钩子列表 → 它从配置生成按键表，创建选择视图并画出来，然后循环读取键盘、重绘和窗口大小变化事件 → 如果用户选查看钩子，返回 OpenHooksBrowser；如果选不信任继续，返回 Continue；如果选全部信任，它把需要审查的钩子整理成 HookTrustUpdate 写给后台，成功就 Continue，失败就把错误放回界面显示。

调用关系：它由 maybe_run_startup_hooks_review 调用，是这个文件的核心流程。它依赖 selection_view 生成界面，draw_view 画界面，selected_choice 翻译用户选择，并在“全部信任”时调用 write_hook_trusts 和后台沟通。

调用图：调用 7 个内部函数（new, request_handle, write_hook_trusts, from_config, draw_view, selected_choice, selection_view）；被 1 处调用（maybe_run_startup_hooks_review）；外部调用 4 个（event_stream, matches!, pin!, OpenHooksBrowser）。

fn selected_choice(view: &mut ListSelectionView) -> Option<StartupHooksReviewSelection>

作用：把列表控件里的选中行，翻译成这个文件能理解的业务选择，比如“查看钩子”或“全部信任”。

数据流：进去的是一个可修改的列表选择视图 → 它先看选择是否已经完成；没完成就返回 None → 完成后取出最后选中的行号，把第 0 行变成 ReviewHooks，第 1 行变成 TrustAllAndContinue，第 2 行或没有行号变成 ContinueWithoutTrusting。

调用关系：它在 run_startup_hooks_review_app 的按键循环里使用。列表控件只知道用户点了第几项，这个函数负责把行号变成后续流程能执行的动作。

调用图：调用 2 个内部函数（is_complete, take_last_selected_index）；被 1 处调用（run_startup_hooks_review_app）。

fn selection_view(
    entry: &HooksListEntry,
    trust_all_error: Option<&str>,
    trusting_all: bool,
    app_event_tx: AppEventSender,
    keymap: &RuntimeKeymap,
) -> ListSelectionView

作用：创建启动钩子审查用的选择列表界面。调用者给它钩子信息、错误信息和按键设置，它返回一个可以显示和接收按键的列表控件。

数据流：进去的是钩子列表、可能存在的信任失败错误、是否正在信任全部钩子的状态、事件发送器和按键表 → 它先调用 selection_view_params 组装标题、提示和三个选项 → 再创建 ListSelectionView → 出来的是可渲染、可处理键盘选择的界面对象。

调用关系：run_startup_hooks_review_app 用它来生成初始界面、信任中的界面和出错后的界面。测试 renders_prompt 和 renders_prompt_with_trust_error 也用它来检查界面长什么样。

调用图：调用 2 个内部函数（new, selection_view_params）；被 3 处调用（run_startup_hooks_review_app, renders_prompt, renders_prompt_with_trust_error）。

fn selection_view_params(
    entry: &HooksListEntry,
    trust_all_error: Option<&str>,
    trusting_all: bool,
    keymap: &RuntimeKeymap,
) -> SelectionViewParams

作用：准备选择界面的所有文字和选项，比如标题、数量提示、底部快捷键提示，以及三条可选操作。

数据流：进去的是钩子列表、错误文字、是否正在信任全部钩子、按键表 → 它统计需要审查的钩子数量，拼出标题和说明；如果有错误就显示红色错误，如果正在信任就显示等待文字 → 最后输出 SelectionViewParams，里面包含页眉、页脚提示和三个选择项。

调用关系：它只被 selection_view 调用，属于界面组装的材料准备层。它还会调用 review_needed_count 算数量，并调用 selection_item 创建每个选项。

调用图：调用 3 个内部函数（standard_popup_hint_line_for_keymap, new, review_needed_count）；被 1 处调用（selection_view）；外部调用 6 个（new, default, from, new, format!, vec!）。

fn review_needed_count(entry: &HooksListEntry) -> usize

作用：数一数当前目录里有多少钩子需要用户重新确认信任。

数据流：进去的是 HooksListEntry，也就是某个目录的钩子清单 → 它逐个检查钩子是否满足 hook_needs_review → 出来的是需要审查的数量。

调用关系：review_is_needed 用它判断是否要弹窗；selection_view_params 用它显示“有几个钩子是新的或改过的”。

调用图：被 2 处调用（review_is_needed, selection_view_params）。

fn review_is_needed(bypass_hook_trust: bool, entry: &HooksListEntry) -> bool

作用：判断这次启动到底要不要拦一下，让用户审查钩子。

数据流：进去的是是否跳过钩子信任检查的开关，以及钩子清单 → 如果跳过开关打开，直接认为不需要审查；否则调用 review_needed_count，看需要审查的数量是否大于 0 → 出来的是 true 或 false。

调用关系：maybe_run_startup_hooks_review 在进入界面前先调用它。测试也直接检查它，确保跳过开关和未信任钩子的判断都正确。

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

fn selection_item(name: &str, is_disabled: bool) -> SelectionItem

作用：创建一条选择项，比如“Review hooks”或“Trust all and continue”。它把重复的选项配置集中起来，避免每条选项都手写一遍。

数据流：进去的是选项名字和是否禁用 → 它生成 SelectionItem，把名字写进去，设置选中后关闭选择流程，并按传入值决定是否可点 → 出来的是一条列表选项。

调用关系：selection_view_params 用它生成三个按钮式的选项。当正在“全部信任”时，这些选项会被禁用，避免用户在后台写入时乱点。

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

fn draw_view(tui: &mut Tui, view: &ListSelectionView) -> Result<()>

作用：把启动钩子审查界面画到终端上。它负责清屏、计算合适高度，然后把选择框渲染出来。

数据流：进去的是 TUI 终端对象和当前选择视图 → 它调用 tui.draw 开始一帧绘制，先用 Clear 清掉区域，再按终端宽高算出视图区域，最后渲染 StandaloneSelectionView → 成功时没有额外结果，只是终端画面被更新；失败则返回错误。

调用关系：run_startup_hooks_review_app 在初次显示、按键后需要刷新、窗口变化或后台写信任状态前后都会调用它。StandaloneSelectionView::render_ref 是它真正交给 ratatui 绘制时用到的适配层。

调用图：被 1 处调用（run_startup_hooks_review_app）；外部调用 1 个（draw）。

fn render_ref(&self, area: Rect, buf: &mut Buffer)

作用：把 ListSelectionView 接到 ratatui 的绘制接口上，让它能作为一个独立小窗口被渲染。

数据流：进去的是要绘制的区域和屏幕缓冲区 → 它把这些直接交给内部的 ListSelectionView.render → 出来没有普通返回值，但缓冲区里被写入了界面文字和样式。

调用关系：draw_view 创建 StandaloneSelectionView 后，ratatui 会调用这个 render_ref。它本身不决定显示什么，只是把绘制请求转交给真正的列表视图。

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

fn hook(key: &str, trust_status: HookTrustStatus) -> HookMetadata

作用：测试用的小工厂函数，用来快速造一个假的钩子。这样测试不用每次都手写一大堆钩子字段。

数据流：进去的是钩子的 key 和信任状态 → 它填入固定的事件名、命令、来源路径、哈希值等测试数据 → 出来的是一个 HookMetadata 测试对象。

调用关系：tests::entry 调用它来组成一份包含未信任和已修改钩子的假清单，供后面的判断和渲染测试使用。

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

fn entry() -> HooksListEntry

作用：生成一份测试用的当前目录钩子清单，里面包含两个需要审查的钩子。

数据流：进去没有参数 → 它创建 cwd 为 /tmp 的 HooksListEntry，并放入一个未信任钩子和一个已修改钩子 → 出来的是可供测试使用的 HooksListEntry。

调用关系：多个测试会调用它：判断是否需要审查时用它，渲染提示界面时也用它。

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

fn render_lines(view: &crate::bottom_pane::ListSelectionView, width: u16) -> String

作用：把一个列表选择界面渲染成普通字符串，方便快照测试比较画面内容。

数据流：进去的是 ListSelectionView 和宽度 → 它根据宽度计算高度，创建一块空的终端缓冲区，把视图画进去，再逐行读出字符并去掉行尾空格 → 出来的是多行字符串。

调用关系：renders_prompt 和 renders_prompt_with_trust_error 用它把界面变成文本，再交给 assert_snapshot! 和保存的快照比较。

调用图：调用 2 个内部函数（desired_height, render）；外部调用 2 个（empty, new）。

fn bypass_hook_trust_suppresses_startup_review()

作用：验证如果用户明确选择跳过钩子信任检查，即使有需要审查的钩子，也不会弹出启动审查。

数据流：进去没有参数 → 它创建测试钩子清单，调用 review_is_needed，并把 bypass_hook_trust 设为 true → 期望结果是 false，也就是不需要审查。

调用关系：这是对 review_is_needed 的单元测试，确保启动流程尊重“跳过检查”这个开关。

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

fn untrusted_hooks_need_review_without_bypass()

作用：验证没有跳过检查时，未信任或已修改的钩子确实会触发启动审查。

数据流：进去没有参数 → 它创建测试钩子清单，调用 review_is_needed，并把 bypass_hook_trust 设为 false → 期望结果是 true，也就是需要审查。

调用关系：这是对 review_is_needed 的另一条核心规则测试，防止安全提示被意外绕过。

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

fn renders_prompt()

作用：检查正常情况下的启动钩子审查提示界面是否长得符合预期。

数据流：进去没有参数 → 它创建事件通道、默认按键表和测试钩子清单，再调用 selection_view 生成界面 → 然后用 render_lines 渲染成文字，并用快照断言比较结果。

调用关系：它测试 selection_view 到 selection_view_params 这一整段界面组装逻辑，确保标题、数量提示和三个选项不会被无意改坏。

调用图：调用 3 个内部函数（new, defaults, selection_view）；外部调用 2 个（assert_snapshot!, entry）。

fn renders_prompt_with_trust_error()

作用：检查“全部信任”写入失败时，错误信息会正确显示在启动审查界面里。

数据流：进去没有参数 → 它创建默认按键表和测试钩子清单，并传入一段假的失败信息给 selection_view → 再把界面渲染成文字，用快照断言确认错误提示出现在预期位置。

调用关系：它覆盖 run_startup_hooks_review_app 出错后会重建的那种界面，确保用户看得到失败原因，而不是只觉得按钮没反应。

调用图：调用 3 个内部函数（new, defaults, selection_view）；外部调用 2 个（assert_snapshot!, entry）。

fn clear(&mut self)

作用：清空已经记住的技能加载警告。有人会在想要“重新开始计算哪些错误算新错误”时用它。

数据流：进去的是这个状态对象本身，里面保存着一批正在报错的技能路径和错误信息；它把这批记录全部删掉；出来没有返回值，但状态变成空的，之后同样的错误会被当成新错误。

调用关系：它是 SkillLoadWarningState 这本“错误记事本”的重置按钮。测试里会调用它，确认清空后同一个技能错误可以再次被提示。

fn newly_active_errors(&mut self, errors: &[SkillErrorInfo]) -> Vec<SkillErrorInfo>

作用：从当前发现的技能错误里挑出“刚刚新出现”的那些，避免同一个还没消失的错误反复提示用户。

数据流：进去的是一组当前扫描到的 SkillErrorInfo，也就是技能文件路径加错误消息；它先拿走旧的活跃错误记录，再逐个生成“路径+消息”的钥匙，对比哪些以前没有出现过；出来是一组新错误，同时把内部状态更新为这次扫描后仍然存在的错误。

调用关系：它通常在重新扫描技能后使用，先过滤出值得提醒的新错误，再交给 emit_skill_load_warnings 去显示。它内部用集合去重，像门卫只放新来的访客进去。

调用图：外部调用 3 个（new, new, take）。

fn emit_skill_load_warnings(app_event_tx: &AppEventSender, errors: &[SkillErrorInfo])

作用：把技能加载失败的信息变成用户能看到的警告消息，插进 TUI 的历史区域。TUI 是文字界面，类似终端里的应用界面。

数据流：进去的是应用事件发送器和一批技能错误；如果没有错误就什么也不做；如果有错误，它先发送一条总警告说明跳过了多少个技能，再为每个错误发送一条包含文件路径和原因的警告。出来没有直接返回值，但界面事件队列里多了这些警告卡片。

调用关系：它不自己画界面，而是把 AppEvent::InsertHistoryCell 事件交给应用主流程。测试辅助函数 tests::render_skill_load_warning_cells 会调用它，把发出的警告渲染成文字来检查。

调用图：调用 1 个内部函数（send）；被 1 处调用（render_skill_load_warning_cells）；外部调用 6 个（new, is_empty, len, InsertHistoryCell, new_warning_event, format!）。

fn emit_project_config_warnings(app_event_tx: &AppEventSender, config: &Config)

作用：提醒用户：某些项目里的本地配置、钩子和执行策略因为项目还没被信任，所以暂时不会生效。这样用户不会误以为配置已经被采用。

数据流：进去的是事件发送器和完整配置；它查看配置层列表，找出来源是项目目录、并且带有禁用原因的层；然后拼出一段包含目录和原因的说明；如果确实有被禁用的目录，就发送一条历史区警告。

调用关系：它在启动阶段检查配置加载结果，把“配置为什么没生效”这件事告诉主界面。它只负责发提醒，不负责决定项目是否可信。

调用图：调用 1 个内部函数（send）；外部调用 6 个（new, new, InsertHistoryCell, concat!, format!, new_warning_event）。

fn emit_system_bwrap_warning(app_event_tx: &AppEventSender, config: &Config)

作用：检查系统沙箱 bubblewrap 相关风险，并在需要时提醒用户。沙箱可以理解为给程序加一个隔离房间，限制它能碰什么。

数据流：进去的是事件发送器和配置；它根据配置里的权限档案询问沙箱模块是否有警告消息；如果没有就结束，如果有就把这条消息做成历史区警告发出去。

调用关系：它把底层沙箱检查结果转成 TUI 可见的提示。真正判断风险的是 codex_sandboxing::system_bwrap_warning，这里只负责把结果送进界面。

调用图：调用 1 个内部函数（send）；外部调用 4 个（new, InsertHistoryCell, system_bwrap_warning, new_warning_event）。

fn should_show_model_migration_prompt(
    current_model: &str,
    target_model: &str,
    seen_migrations: &BTreeMap<String, String>,
    available_models: &[ModelPreset],
) -> bool

作用：判断这次启动时要不要弹出“建议你从当前模型迁移到目标模型”的提示。它避免没必要、重复或不可用的迁移提示打扰用户。

数据流：进去的是当前模型名、目标模型名、已经看过的迁移记录、可用模型列表；它依次检查目标是否和当前相同、是否已经问过、目标是否能在选择器里显示、当前或目标是否确实属于升级关系；出来是 true 或 false，表示该不该问用户。

调用关系：handle_model_migration_prompt_if_needed 会先调用它做门槛判断。只有它说“应该显示”，后面才会组装提示文案并真正弹窗。

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

fn migration_prompt_hidden(config: &Config, migration_config_key: &str) -> bool

作用：根据配置判断某一种模型迁移提示是否被用户或配置隐藏了。这样尊重用户“不再提醒”的选择。

数据流：进去的是配置和一个迁移提示的配置键；它按已知键名去读对应的隐藏开关；出来是布尔值，true 表示这个提示应该被藏起来。

调用关系：handle_model_migration_prompt_if_needed 在准备弹迁移提示前会先问它。如果它返回 true，整个迁移提示流程就直接跳过。

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

fn target_preset_for_upgrade(
    available_models: &'a [ModelPreset],
    target_model: &str,
) -> Option<&'a ModelPreset>

作用：在可用模型列表里找到目标升级模型的详细资料。它确保目标模型不只是名字存在，而且能展示给用户选择。

数据流：进去的是可用模型列表和目标模型名；它逐个查找模型名匹配、并且允许出现在选择器里的模型；出来是这个模型的配置资料，找不到就返回空。

调用关系：handle_model_migration_prompt_if_needed 用它拿目标模型的显示名、描述和默认推理强度。找不到目标资料时，迁移提示就不会继续。

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

fn apply_accepted_model_migration(
    config: &mut Config,
    app_event_tx: &AppEventSender,
    from_model: String,
    target_model: String,
    target_default_effort: ReasoningEffortConfig,
)

作用：当用户接受模型迁移时，把新模型真正应用到当前配置和界面状态里，并安排持久化保存。

数据流：进去的是可修改配置、事件发送器、原模型名、目标模型名、目标默认推理强度；它先发送“用户已确认迁移”的保存事件，再更新内存里的 config.model 和 config.model_reasoning_effort，然后发送更新界面模型、更新推理强度、保存模型选择等事件；出来没有返回值，但配置和事件队列都被改了。

调用关系：它只在 handle_model_migration_prompt_if_needed 收到 Accepted，也就是用户点了接受之后调用。它把用户选择转化为实际的配置变化。

调用图：调用 1 个内部函数（send）；被 1 处调用（handle_model_migration_prompt_if_needed）；外部调用 3 个（clone, UpdateModel, UpdateReasoningEffort）。

fn select_model_availability_nux(
    available_models: &[ModelPreset],
    nux_config: &ModelAvailabilityNuxConfig,
) -> Option<StartupTooltipOverride>

作用：从模型列表里挑一个可以显示的新手提示。NUX 可以理解为“新功能小提示”，这里用于告诉用户某个模型现在可用了。

数据流：进去的是可用模型列表和已经显示过多少次的记录；它寻找带有可用性提示文案的模型，并检查这个模型提示显示次数是否少于上限；出来是要显示的模型名和提示文字，或者没有可显示内容。

调用关系：prepare_startup_tooltip_override 会调用它来决定启动时是否覆盖默认提示文字。它负责挑选，后者负责计数和保存。

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

async fn prepare_startup_tooltip_override(
    config: &mut Config,
    available_models: &[ModelPreset],
    is_first_run: bool,
) -> Option<String>

作用：准备启动时的小提示文案，并把“这个提示又显示了一次”的次数保存下来。它防止同一个新模型提示一直骚扰用户。

数据流：进去的是可修改配置、模型列表、是否首次运行；如果是首次运行或用户关闭了提示，就返回空；否则调用 select_model_availability_nux 找提示，增加该模型的显示次数，尝试写回配置文件；成功后更新内存配置并返回提示文案，保存失败时记录错误但仍返回文案。

调用关系：它在启动准备阶段运行，接在模型目录和配置已经可用之后。它把 select_model_availability_nux 的选择结果落到配置里，使用 ConfigEditsBuilder 做持久化。

调用图：调用 1 个内部函数（select_model_availability_nux）；外部调用 2 个（for_config, error!）。

async fn handle_model_migration_prompt_if_needed(
    tui: &mut tui::Tui,
    config: &mut Config,
    model: &str,
    app_event_tx: &AppEventSender,
    available_models: &[ModelPreset],
) -> Option

作用：完整处理“是否建议用户换模型”的启动弹窗流程。它从判断、组文案、显示弹窗，到根据用户选择更新配置或退出程序，都串起来。

数据流：进去的是 TUI、可修改配置、当前模型名、事件发送器、可用模型列表；它先找当前模型是否有升级目标，再检查提示是否隐藏、是否应该显示、目标模型是否可用；然后准备显示名、说明和提示文案，运行迁移弹窗；用户接受就调用 apply_accepted_model_migration，拒绝就记住已问过，选择退出就返回 AppExitInfo；正常不退出时返回空。

调用关系：这是模型迁移提示的总调度员。它调用 migration_prompt_hidden、should_show_model_migration_prompt、target_preset_for_upgrade 做判断，调用 run_model_migration_prompt 询问用户，接受后把工作交给 apply_accepted_model_migration。

调用图：调用 5 个内部函数（apply_accepted_model_migration, migration_prompt_hidden, should_show_model_migration_prompt, target_preset_for_upgrade, send）；外部调用 2 个（iter, default）。

fn normalize_harness_overrides_for_cwd(
    mut overrides: ConfigOverrides,
    base_cwd: &AbsolutePathBuf,
) -> Result<ConfigOverrides>

作用：把测试或运行外壳里额外允许写入的目录，按照当前工作目录转成正确路径。这样相对路径不会因为启动位置不同而指错地方。

数据流：进去的是配置覆盖项和一个基准当前目录；如果没有额外可写目录，就原样返回；如果有，它把每个目录都拼到基准目录下面，形成标准化后的路径列表；出来是更新后的 ConfigOverrides。

调用关系：这是启动前的小修正工具。测试 tests::normalize_harness_overrides_resolves_relative_add_dirs 会验证相对目录会被正确拼到 base_cwd 后面。

调用图：调用 1 个内部函数（join）；被 1 处调用（normalize_harness_overrides_resolves_relative_add_dirs）；外部调用 1 个（with_capacity）。

fn normalize_harness_overrides_resolves_relative_add_dirs() -> Result<()>

作用：测试 normalize_harness_overrides_for_cwd 是否真的把相对可写目录变成基于当前目录的路径。

数据流：进去没有业务输入；它创建临时目录，构造一个包含 rel 相对路径的覆盖配置，调用被测函数；最后比较输出路径是否等于 base/rel。

调用关系：它直接覆盖 normalize_harness_overrides_for_cwd 的核心行为，防止以后改代码时把相对路径处理弄坏。

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

fn skill_error(path: &str, message: &str) -> SkillErrorInfo

作用：给测试快速造一个技能错误对象，避免每个测试都重复写路径和消息的包装代码。

数据流：进去的是路径字符串和错误消息字符串；它把路径转成 PathBuf，把消息转成 String；出来是 SkillErrorInfo。

调用关系：多个 SkillLoadWarningState 相关测试都会用它造样本错误。它只是测试里的小工厂函数。

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

fn render_line_text(line: &Line<'static>) -> String

作用：把界面渲染出来的一行文字拆掉格式，只留下纯文本，方便测试比较。

数据流：进去的是 ratatui 的 Line，也就是一行可能带样式的终端文字；它把这一行里的多个 span 文本拼起来；出来是一整行普通字符串。

调用关系：tests::render_skill_load_warning_cells 用它把警告卡片的显示结果转成可断言的纯文本。

fn render_skill_load_warning_cells(errors: &[SkillErrorInfo]) -> String

作用：在测试里模拟发送技能加载警告，并把最终会显示的文字收集出来。

数据流：进去的是一批技能错误；它创建一个事件通道，调用 emit_skill_load_warnings 发送警告事件，然后从通道里读出历史卡片，渲染成宽度 120 的文本行；出来是用换行拼好的警告文本。

调用关系：它是测试 emit_skill_load_warnings 显示效果的桥梁。tests::repeated_active_skill_load_warning_renders_once 会用它确认重复错误不会重复显示。

调用图：调用 2 个内部函数（emit_skill_load_warnings, new）；外部调用 2 个（new, unbounded_channel）。

fn skill_load_warning_state_suppresses_repeated_active_errors()

作用：测试同一个技能错误连续存在时，只会第一次被认为是新错误。

数据流：进去没有外部输入；它创建一个默认状态和一个错误，第一次调用 newly_active_errors 期望得到该错误，第二次用同样错误调用期望得到空列表；出来是测试通过或失败。

调用关系：它验证 SkillLoadWarningState::newly_active_errors 的“别重复打扰用户”规则。

调用图：外部调用 3 个（assert_eq!, default, skill_error）。

fn skill_load_warning_state_reemits_after_error_clears()

作用：测试一个错误消失后又出现时，会再次提醒用户。

数据流：进去没有外部输入；它先让错误出现一次，再传入空列表表示错误已经清除，最后再次传入同一错误；期望最后一次又返回这个错误；出来是测试通过或失败。

调用关系：它验证 SkillLoadWarningState 不只是永久拉黑某个错误，而是只抑制“持续存在”的重复错误。

调用图：外部调用 3 个（assert_eq!, default, skill_error）。

fn skill_load_warning_state_displays_new_message_for_active_path()

作用：测试同一个技能文件如果错误消息变了，也应该当成新错误显示。

数据流：进去没有外部输入；它创建同一路径但不同消息的两个错误，先输入第一个，再输入第二个；期望两次都能返回对应错误；出来是测试通过或失败。

调用关系：它验证 SkillLoadWarningState 的判断钥匙包含路径和消息，而不是只看路径。这样用户能看到错误原因的变化。

调用图：外部调用 3 个（assert_eq!, default, skill_error）。

fn skill_load_warning_state_clear_allows_active_error_again()

作用：测试手动清空状态后，同一个还在的错误也会重新被当成新错误。

数据流：进去没有外部输入；它先确认同一错误第二次会被抑制，然后调用 clear，再输入同一错误；期望这次重新返回错误；出来是测试通过或失败。

调用关系：它覆盖 SkillLoadWarningState::clear 和 newly_active_errors 的配合，确保重置按钮真的有效。

调用图：外部调用 3 个（assert_eq!, default, skill_error）。

fn repeated_active_skill_load_warning_renders_once()

作用：测试从状态过滤到界面渲染的整体效果：重复活跃的技能错误只显示一次警告。

数据流：进去没有外部输入；它创建状态和错误，连续两次获取新错误，再分别渲染警告文本，过滤掉空输出后拼起来；最后用快照断言结果只包含一次总警告和一次具体错误。

调用关系：它把 SkillLoadWarningState::newly_active_errors、render_skill_load_warning_cells 和 emit_skill_load_warnings 串起来测，确认用户最终看到的界面不会重复刷同一条错误。

调用图：外部调用 5 个（assert_snapshot!, from_ref, default, render_skill_load_warning_cells, skill_error）。

fn experimental_tooltips() -> Vec<&'static str>

作用：收集实验功能自带的提示语。这样新功能在实验阶段也能通过启动提示告诉用户，而不用手写进固定提示文件。

数据流：进去的是全局功能清单 FEATURES → 它逐个查看每个功能有没有“实验公告” → 出来的是一组可以加入随机提示池的文字。

调用关系：它在提示池初始化时被 ALL_TOOLTIPS 使用，把实验功能提示和普通提示合在一起。之后 get_tooltip 间接从这个合并后的池子里抽提示。

fn get_tooltip(plan: Option<PlanType>, fast_mode_enabled: bool) -> Option<String>

作用：这是外部最常用的入口：给定用户套餐和是否已开启 fast 模式，返回一条适合启动时显示的提示。它负责把远程公告、套餐推广和普通随机提示排好优先级。

数据流：进去的是用户套餐 plan 和 fast_mode_enabled → 它先尝试拿远程公告；如果没有，再用随机数决定大概率走套餐相关提示，小概率走普通提示池 → 出来是 Some(提示文字) 或没有可用提示时的 None。

调用关系：启动界面需要提示时会调用它。它先把活交给 announcement::fetch_announcement_tip；如果没拿到公告，再按情况调用 pick_paid_tooltip 或 pick_tooltip。

调用图：调用 2 个内部函数（pick_paid_tooltip, pick_tooltip）；外部调用 3 个（fetch_announcement_tip, matches!, rng）。

fn paid_app_tooltip() -> Option<&'static str>

作用：判断当前系统能不能显示 Codex App 的推广提示。因为 App 推广只适合 macOS 和 Windows，Linux 上不会返回这条。

数据流：进去的是编译时确定的当前操作系统信息 → 它判断是不是 macOS 或 Windows → 出来是 App 推广文案，或者 None。

调用关系：pick_paid_tooltip 会用它给付费用户挑 App 推广。相关测试也会调用它，确认付费提示池里包含的内容符合预期。

调用图：被 3 处调用（pick_paid_tooltip, paid_tooltip_pool_rotates_between_promos, paid_tooltip_pool_skips_fast_when_fast_mode_is_enabled）。

fn pick_paid_tooltip(
    rng: &mut R,
    fast_mode_enabled: bool,
) -> Option<&'static str>

作用：专门给付费用户挑启动推广提示。它在 Codex App 和 /fast 模式推广之间做选择，但如果用户已经开了 fast，就不再提醒 fast。

数据流：进去的是随机数生成器和 fast_mode_enabled → 如果已开 fast，或随机结果偏向 App，就尝试返回 App 提示；否则返回 fast 提示 → 出来是一条付费用户提示，或在当前系统没有 App 提示时可能为 None。

调用关系：get_tooltip 在识别到付费或团队/商业类套餐时调用它。它内部会调用 paid_app_tooltip，测试会反复用不同随机种子确认它确实能轮换并跳过不该出现的 fast 提示。

调用图：调用 1 个内部函数（paid_app_tooltip）；被 3 处调用（get_tooltip, paid_tooltip_pool_rotates_between_promos, paid_tooltip_pool_skips_fast_when_fast_mode_is_enabled）；外部调用 1 个（random_bool）。

fn pick_tooltip(rng: &mut R) -> Option<&'static str>

作用：从普通提示池里随机抽一条。它是兜底方案，用来在没有更高优先级公告或推广时给用户一点使用建议。

数据流：进去的是随机数生成器 → 它先看总提示池是否为空；不为空就随机挑一个下标 → 出来是一条提示文字，或者提示池为空时返回 None。

调用关系：get_tooltip 在最后兜底时调用它。测试用固定随机种子调用它，确认同一个种子能抽到同样结果，避免随机逻辑变得不可预测。

调用图：被 2 处调用（get_tooltip, random_tooltip_is_reproducible_with_seed）；外部调用 1 个（random_range）。

fn prewarm()

作用：提前在后台准备远程公告缓存。这样真正需要显示提示时，不必卡住启动界面等网络请求。

数据流：进去没有参数 → 它启动一个后台线程，让公告缓存开始初始化 → 出来没有直接结果，只是让全局缓存有机会提前填好。

调用关系：它通常会在启动早期被调用。它把慢活交给后台线程，后面 announcement::fetch_announcement_tip 只读取已经准备好的结果，不会主动等待很久。

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

fn fetch_announcement_tip(plan: Option<PlanType>) -> Option<String>

作用：读取已经预热好的远程公告，并根据当前用户套餐筛出真正该显示的那条。它不会为了公告而阻塞等待下载完成。

数据流：进去的是用户套餐 plan → 它查看全局缓存里是否已有下载好的公告文本；有的话解析并筛选，没有或不匹配就返回 None → 出来是一条公告文字或 None。

调用关系：get_tooltip 会最先调用它，因为远程公告优先级最高。它依赖预热阶段放进 ANNOUNCEMENT_TIP 的原始文本，并把筛选工作交给 announcement::parse_announcement_tip_toml。

fn current() -> Self

作用：把当前运行的操作系统归成公告配置能理解的几类：Linux、macOS 或 Windows。这样公告可以只投给某些系统用户。

数据流：进去没有运行时参数 → 它根据编译目标判断系统 → 出来是一个 TargetOs 枚举值，也就是“当前系统标签”。

调用关系：它用于生成 CURRENT_OS 常量，announcement::parse_announcement_tip_toml 会用这个常量判断公告的 target_oses 是否匹配当前机器。

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

fn init_announcement_tip_in_thread() -> Option<String>

作用：在单独线程里初始化公告内容，并把线程执行结果安全地取回来。它的作用是隔离网络下载这类可能慢或失败的工作。

数据流：进去没有参数 → 它再启动一个线程执行真正的阻塞下载，然后等待线程结束 → 出来是下载到的公告文本，失败时是 None。

调用关系：announcement::prewarm 启动的后台任务会通过缓存初始化调用它。它再把真正联网的部分交给 announcement::blocking_init_announcement_tip。

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

fn blocking_init_announcement_tip() -> Option<String>

作用：真正去网络上下载公告配置文本。它设置了短超时，并关闭系统代理检测，避免因为系统网络配置问题拖慢或弄崩启动。

数据流：进去没有参数 → 它创建一个不使用代理的 HTTP 客户端，访问固定的 GitHub 原始文件地址，最多等 2 秒 → 出来是下载到的文本；建客户端、请求、状态码或读文本失败都会返回 None。

调用关系：announcement::init_announcement_tip_in_thread 把联网工作交给它。它只负责拿原始文本，不判断这条公告该不该显示，后续筛选由 announcement::parse_announcement_tip_toml 完成。

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

fn parse_announcement_tip_toml(
        text: &str,
        plan: Option<PlanType>,
    ) -> Option<String>

作用：把远程公告配置文本解析成一条当前用户能看的公告。它会过滤掉日期不对、版本不对、App 不对、套餐不对、系统不对的公告。

数据流：进去的是 TOML 文本和用户套餐 → 它先把文本解析成公告列表，再逐条转成干净的 AnnouncementTip，按当前日期、CLI 版本、目标 app、套餐和系统检查 → 出来是最后一条匹配公告的文字，或者 None。

调用关系：announcement::fetch_announcement_tip 会调用它来处理缓存里的原始文本。它把单条公告的清洗交给 announcement::AnnouncementTip::from_raw，再调用 version_matches 和 date_matches 做筛选。

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

fn from_raw(raw: AnnouncementTipRaw) -> Option<Self>

作用：把刚从 TOML 读出来的“原始公告”变成程序可以安全使用的公告对象。它会顺手拒绝空内容、坏日期、坏正则表达式和写错的套餐/系统名字。

数据流：进去的是 AnnouncementTipRaw，也就是还没校验的公告字段 → 它清理内容、解析日期、编译版本匹配用的正则表达式，并检查目标套餐和系统是否合法 → 出来是干净的 AnnouncementTip，或者发现问题时返回 None。

调用关系：announcement::parse_announcement_tip_toml 在扫描公告列表时会调用它。它相当于门卫，先把明显坏掉的公告挡在筛选流程之外。

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

fn version_matches(&self, version: &str) -> bool

作用：判断一条公告是否适合当前 CLI 版本。正则表达式可以理解成一种“文字匹配规则”，用来描述哪些版本号算匹配。

数据流：进去的是公告自身和一个版本号字符串 → 如果公告没有写版本规则，就认为所有版本都匹配；如果写了，就用正则表达式检查版本号 → 出来是 true 或 false。

调用关系：announcement::parse_announcement_tip_toml 在决定公告能否显示时调用它。它只管版本这一关，日期等其它条件由别的函数处理。

fn date_matches(&self, today: NaiveDate) -> bool

作用：判断一条公告今天是否还在有效期内。它支持开始日期和结束日期，开始日期包含当天，结束日期不包含当天。

数据流：进去的是公告自身和今天的日期 → 它检查今天是否早于 from_date，或是否已经到达/超过 to_date → 出来是 true 或 false。

调用关系：announcement::parse_announcement_tip_toml 在筛公告时调用它。它和 version_matches 一起组成公告显示前的主要检查。

fn random_tooltip_returns_some_tip_when_available()

作用：测试普通随机提示池在有内容时能返回提示。它防止提示文件或过滤逻辑被改坏后，启动提示永远为空。

数据流：进去的是固定种子的随机数生成器 → 它调用 pick_tooltip 抽一次 → 用断言确认结果不是 None。

调用关系：这是测试阶段运行的函数。它直接验证 pick_tooltip 的基本可用性。

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

fn random_tooltip_is_reproducible_with_seed()

作用：测试同一个随机种子会抽到同一条普通提示。这样测试不会因为随机性每次结果不同而变得不稳定。

数据流：进去的是相同的种子值 7 → 它创建两次同样的随机数生成器并分别调用 pick_tooltip → 用断言确认两次结果相等。

调用关系：它在测试中调用 pick_tooltip，证明随机选择虽然随机，但在固定种子下可复现。

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

fn paid_tooltip_pool_rotates_between_promos()

作用：测试付费用户的提示池会在 App 推广和 fast 推广之间轮换。它防止某个推广永远抽不到。

数据流：进去的是一批不同随机种子 → 它多次调用 pick_paid_tooltip，并把见过的结果放进集合 → 最后确认集合正好等于预期的两类提示。

调用关系：它调用 pick_paid_tooltip 和 paid_app_tooltip，专门检查付费提示选择逻辑没有偏离设计。

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

fn paid_tooltip_pool_skips_fast_when_fast_mode_is_enabled()

作用：测试用户已经开启 fast 模式时，不再显示 fast 模式推广。否则用户会看到已经做过的事情还被反复推荐。

数据流：进去的是多组随机种子，并把 fast_mode_enabled 设为 true → 它多次调用 pick_paid_tooltip 收集结果 → 确认只出现 App 提示，并且不包含 FAST_TOOLTIP。

调用关系：它调用 pick_paid_tooltip 和 paid_app_tooltip，覆盖 get_tooltip 会依赖的一条重要分支。

调用图：调用 2 个内部函数（paid_app_tooltip, pick_paid_tooltip）；外部调用 5 个（seed_from_u64, assert!, assert_eq!, from, new）。

fn announcement_tip_toml_picks_last_matching()

作用：测试公告配置里如果有多条都匹配，最后一条匹配的公告会被显示。这样运营或维护者可以用后面的配置覆盖前面的配置。

数据流：进去的是两段手写 TOML 公告文本 → 它解析这些文本 → 用断言确认返回的是“latest match”而不是更早的匹配项或过期项。

调用关系：它验证 announcement::parse_announcement_tip_toml 的选择规则，尤其是“最后匹配者胜出”这件事。

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

fn announcement_tip_toml_picks_no_match()

作用：测试没有任何公告符合当前条件时会返回 None。它防止过期公告、版本不匹配公告或别的 App 的公告误显示出来。

数据流：进去的是一段包含过期、版本不符、target_app 不符公告的 TOML → 它执行解析筛选 → 断言结果是 None。

调用关系：它围绕 announcement::parse_announcement_tip_toml 做反向验证，确认筛选条件真的会挡住不该显示的内容。

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

fn announcement_tip_toml_bad_deserialization()

作用：测试公告字段类型写错时不会崩溃，也不会显示错误公告。比如 content 应该是文字，却写成数字。

数据流：进去的是一段格式不合要求的 TOML → 解析阶段失败 → 断言最终返回 None。

调用关系：它验证 announcement::parse_announcement_tip_toml 面对坏配置时的安全行为。

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

fn announcement_tip_toml_parse_comments()

作用：测试公告配置里可以带注释，并且注释不会影响解析。这样远程配置文件能写说明，方便人维护。

数据流：进去的是带很多注释和两条公告的 TOML → 它解析并按版本等条件筛选 → 断言返回符合条件的测试公告。

调用关系：它验证 announcement::parse_announcement_tip_toml 能处理真实配置文件常见的注释写法。

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

fn announcement_tip_toml_matches_target_plan_type()

作用：测试公告能按用户套餐精准匹配。不同套餐的人可能看到不同公告，没指定套餐的公告则作为通用公告。

数据流：进去的是包含通用、pro/enterprise、free 三类公告的 TOML，以及不同 plan 参数 → 它分别解析筛选 → 断言 Pro、Free、Plus、无套餐时返回各自正确的文字。

调用关系：它验证 announcement::parse_announcement_tip_toml 对 target_plan_types 的处理，保证 get_tooltip 传入套餐后能得到合适公告。

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

fn announcement_tip_toml_rejects_unknown_target_plan_type()

作用：测试配置里写错套餐名时，这条公告会被丢弃。这样一个拼写错误不会让错误公告误伤用户。

数据流：进去的是一段含通用公告和拼错套餐公告的 TOML → 解析时拼错项会变成 Unknown 并被拒绝 → 断言最终只返回通用公告。

调用关系：它覆盖 announcement::AnnouncementTip::from_raw 里拒绝 Unknown 套餐的保护逻辑，并通过 announcement::parse_announcement_tip_toml 观察结果。

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

fn announcement_tip_toml_matches_target_os()

作用：测试公告能按当前操作系统匹配。macOS、Windows、Linux 用户应该只看到发给自己系统的公告。

数据流：进去的是分别面向 linux、macos、windows 的公告 TOML → 测试先根据当前编译系统算出期望值，再解析筛选 → 断言返回当前系统对应的公告。

调用关系：它验证 announcement::TargetOs::current 产生的系统标签能被 announcement::parse_announcement_tip_toml 正确使用。

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

fn announcement_tip_toml_rejects_unknown_target_os()

作用：测试配置里写错操作系统名时，这条公告会被丢弃。这样错误的系统标签不会造成奇怪的匹配结果。

数据流：进去的是一段含通用公告和拼错系统公告的 TOML → 拼错系统会被识别为 Unknown 并拒绝 → 断言最终返回通用公告。

调用关系：它覆盖 announcement::AnnouncementTip::from_raw 里拒绝 Unknown 操作系统的保护逻辑，并确认解析流程会跳过坏公告。

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

async fn run_update_prompt_if_needed(
    tui: &mut Tui,
    config: &Config,
) -> Result<UpdatePromptOutcome>

作用：这是整个更新提示的入口。主界面启动时调用它，用来决定要不要弹出更新窗口，并根据用户选择返回“继续运行”或“执行更新”。

数据流：进去的是终端界面对象和配置。它先从配置和更新记录里查有没有可提示的新版本，再查可用的更新命令；如果没有，就直接返回继续。若需要提示，它创建提示屏幕、画到终端上、不断读取按键和重绘事件，直到用户做出选择。最后输出一个结果：继续运行、运行更新，或者保存“这个版本别再提醒”后继续运行。

调用关系：它由 run_ratatui_app 在程序启动流程中调用。它把检查新版本的活交给 get_upgrade_version_for_popup，把判断更新命令的活交给 get_update_action，把界面状态交给 UpdatePromptScreen::new 和后续的按键处理；用户选完后，它可能调用 dismiss_version 保存跳过记录。

调用图：调用 3 个内部函数（get_update_action, new, get_upgrade_version_for_popup）；被 1 处调用（run_ratatui_app）；外部调用 7 个（draw, event_stream, frame_requester, pin!, error!, RunUpdate, dismiss_version）。

fn new(
        request_frame: FrameRequester,
        latest_version: String,
        update_action: UpdateAction,
    ) -> Self

作用：创建一个更新提示窗口的内部状态。它记住新版本号、当前版本号、更新方式，以及默认高亮的选项。

数据流：进去的是请求重画用的工具、新版本号和更新动作。它读取编译时写进程序里的当前版本号，把默认高亮设为“现在更新”，并且把“用户最终选择”先设为空。出来的是一个可以被绘制、可以响应按键的提示屏幕对象。

调用关系：run_update_prompt_if_needed 在真正弹窗前会调用它。测试里的 tests::new_prompt 也用它造一个假的提示窗口，方便检查画面和按键行为。

调用图：被 2 处调用（run_update_prompt_if_needed, new_prompt）；外部调用 1 个（env!）。

fn handle_key(&mut self, key_event: KeyEvent)

作用：处理用户按下的键。它把键盘动作翻译成“移动选项”或“确认某个选择”。

数据流：进去的是一次按键事件。它先忽略按键释放事件；如果是 Ctrl+C 或 Ctrl+D，就当作跳过更新；如果是上下键或 j/k，就移动高亮；如果是数字键、回车或 Esc，就记录用户选择。结果是屏幕内部的高亮位置或最终选择被改变，并可能请求界面重画。

调用关系：run_update_prompt_if_needed 在事件循环里收到 TuiEvent::Key 后调用它。它自己不直接画界面，而是把移动交给 set_highlight，把确认交给 select，并用 UpdateSelection::next 和 UpdateSelection::prev 算出下一个选项。

调用图：调用 4 个内部函数（select, set_highlight, next, prev）；外部调用 1 个（matches!）。

fn set_highlight(&mut self, highlight: UpdateSelection)

作用：移动当前高亮的选项。只有高亮真的变了，它才通知终端重新画一帧。

数据流：进去的是新的候选高亮项。它和当前高亮项比较；如果不同，就更新内部字段，并通过 request_frame 请求重画。出来没有单独返回值，但屏幕状态会改变。

调用关系：它只由 UpdatePromptScreen::handle_key 调用，用在用户按上下键或 j/k 浏览选项时。它把“状态变了需要刷新画面”这件事交给 schedule_frame。

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

fn select(&mut self, selection: UpdateSelection)

作用：记录用户最终选了哪一项。选完后，这个提示窗口就可以结束了。

数据流：进去的是用户选择的选项。它把高亮项也改成这个选项，再把 selection 设为有值，表示已经选择完成，并请求重画一次。之后 is_done 会返回 true。

调用关系：它由 UpdatePromptScreen::handle_key 在用户按回车、数字键、Esc、Ctrl+C 或 Ctrl+D 时调用。run_update_prompt_if_needed 之后会通过 selection 读取这个结果，决定下一步怎么做。

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

fn is_done(&self) -> bool

作用：告诉外层流程：用户是不是已经做出选择了。它是事件循环能不能结束的判断条件。

数据流：它读取屏幕内部的 selection 字段。如果里面已经有选择，就返回 true；如果还是空，就返回 false。它不改动任何状态。

调用关系：run_update_prompt_if_needed 在等待用户操作的循环里反复检查它。测试也用它确认按键之后提示窗口确实进入了完成状态。

fn selection(&self) -> Option<UpdateSelection>

作用：取出用户最后选的更新处理方式。外层流程靠它知道该更新、跳过，还是不再提醒当前版本。

数据流：它读取屏幕内部保存的 selection。进去不需要额外参数，出来是一个可能为空的选择值；为空表示还没选，非空表示用户已经决定了。

调用关系：run_update_prompt_if_needed 在提示结束后调用它，并把选择翻译成 UpdatePromptOutcome。多个测试也用它检查按键结果是否符合预期。

fn latest_version(&self) -> &str

作用：返回提示窗口里保存的新版本号。主要用于用户选择“不再提醒这个版本”时，告诉更新模块要屏蔽哪个版本。

数据流：它读取 latest_version 字符串，并以只读文本的形式交出去。它不会复制业务状态，也不会修改屏幕。

调用关系：run_update_prompt_if_needed 在用户选择 DontRemind 后调用它，然后把这个版本号交给 updates::dismiss_version 保存。

fn next(self) -> Self

作用：算出当前选项往下走一格会到哪一项。走到最后一项后会绕回第一项。

数据流：进去的是当前选项。它按照“现在更新 → 跳过 → 跳过直到下个版本 → 现在更新”的顺序返回下一个选项。它不改动外部状态。

调用关系：UpdatePromptScreen::handle_key 在用户按下方向键或 j/k 中的“向下”时调用它，然后把结果交给 set_highlight 更新高亮。

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

fn prev(self) -> Self

作用：算出当前选项往上走一格会到哪一项。走到第一项前面会绕到最后一项。

数据流：进去的是当前选项。它按照反方向返回上一个选项，例如从“现在更新”往上会到“跳过直到下个版本”。它不改动外部状态。

调用关系：UpdatePromptScreen::handle_key 在用户按上方向键或 k 时调用它，然后把结果交给 set_highlight。

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

fn render_ref(&self, area: Rect, buf: &mut Buffer)

作用：把更新提示窗口画到终端屏幕上。它负责用户实际看到的文字、链接、选项和高亮效果。

数据流：进去的是可绘制区域和屏幕缓冲区。它先清空这块区域，再组装一列文字：标题、新旧版本、发布说明链接、三个可选按钮、回车提示。它会根据当前 highlighted 字段决定哪一行显示为选中。最后还把发布说明链接标记成终端可识别的超链接。出来没有普通返回值，但缓冲区里的画面内容被改好了。

调用关系：run_update_prompt_if_needed 在首次显示和收到重绘事件时，通过终端绘制流程间接调用它。它会向 update_action 要更新命令文本，向 selection_option_row 要每个选项行的样式，并调用 mark_underlined_hyperlink 让链接更像真正可点的链接。

调用图：调用 5 个内部函数（tlbr, new, selection_option_row, mark_underlined_hyperlink, command_str）；外部调用 3 个（from, format!, vec!）。

fn new_prompt() -> UpdatePromptScreen

作用：给测试用的快捷造屏幕函数。它创建一个固定的新版本号和固定更新方式的提示窗口，避免每个测试重复写准备代码。

数据流：它不接收参数。它用测试专用的 FrameRequester、版本号 9.9.9 和 npm 全局更新动作创建 UpdatePromptScreen。出来的是一个可供测试操作的提示窗口。

调用关系：下面所有更新提示相关测试都会调用它。它内部调用 UpdatePromptScreen::new，把正式构造逻辑也一起覆盖到测试里。

调用图：调用 2 个内部函数（test_dummy, new）。

fn update_prompt_snapshot()

作用：检查更新提示窗口画出来的样子有没有意外变化。快照测试就像给界面拍一张标准照片，以后每次测试都拿来对比。

数据流：它先用 tests::new_prompt 创建屏幕，再用一个假的 80×12 终端把界面画出来，最后把画面和保存的快照比较。结果是测试通过或失败，不会影响真实程序。

调用关系：它通过终端绘制流程间接覆盖 UpdatePromptScreen::render_ref。若有人改了提示文案、布局或高亮样式，这个测试通常会提醒维护者确认改动是否有意。

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

fn update_prompt_confirm_selects_update()

作用：确认默认状态下直接按回车会选择“现在更新”。这是最关键的快捷路径。

数据流：它创建一个提示窗口，模拟用户按下回车，然后检查窗口已经结束，并且 selection 是 UpdateNow。测试只读写这个假的屏幕对象，不接触真实终端。

调用关系：它调用 tests::new_prompt 准备对象，再通过 UpdatePromptScreen::handle_key 走正式按键逻辑，最后用 is_done 和 selection 验证结果。

调用图：外部调用 4 个（new, assert!, assert_eq!, new_prompt）。

fn update_prompt_dismiss_option_leaves_prompt_in_normal_state()

作用：确认用户移动到“跳过”再回车时，结果是暂时不更新，而不是误触更新。

数据流：它创建提示窗口，模拟按一次向下键，把高亮从“现在更新”移到“跳过”，再模拟回车。最后检查提示已结束，选择值是 NotNow。

调用关系：它覆盖 handle_key、UpdateSelection::next、set_highlight 和 select 配合工作的路径，确保普通跳过选项可用。

调用图：外部调用 4 个（new, assert!, assert_eq!, new_prompt）。

fn update_prompt_dont_remind_selects_dismissal()

作用：确认用户选择第三项时，会得到“不再提醒这个版本”的结果。

数据流：它创建提示窗口，模拟按两次向下键到第三项，再按回车确认。最后检查窗口结束，并且 selection 是 DontRemind。

调用关系：它测试的是 handle_key 连续导航和确认的组合行为。这个结果在真实流程里会让 run_update_prompt_if_needed 去保存版本屏蔽记录。

调用图：外部调用 4 个（new, assert!, assert_eq!, new_prompt）。

fn update_prompt_ctrl_c_skips_update()

作用：确认按 Ctrl+C 不会让程序真的选择更新，而是安全地跳过提示。这样用户习惯性取消时不会发生意外。

数据流：它创建提示窗口，模拟 Ctrl+C 按键。按键处理后，测试检查提示已结束，并且选择是 NotNow。

调用关系：它直接覆盖 handle_key 里处理 Ctrl+C 的特殊分支。真实运行时，这条路径会让 run_update_prompt_if_needed 返回继续运行。

调用图：外部调用 5 个（Char, new, assert!, assert_eq!, new_prompt）。

fn update_prompt_navigation_wraps_between_entries()

作用：确认选项列表上下移动时会循环。比如在第一项按上键会跳到最后一项，在最后一项往下又能回到第一项。

数据流：它创建提示窗口，先模拟上键，检查高亮变成 DontRemind；再模拟下键，检查高亮回到 UpdateNow。它只检查高亮位置，不做最终选择。

调用关系：它验证 UpdateSelection::prev 和 UpdateSelection::next 的绕回规则，也间接验证 handle_key 会把方向键正确交给这些小函数。

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

fn verb(self) -> &'static str

作用：把动作类型变成界面上能直接显示的英文动词，比如“resume”或“fork”。这样同一个提示框可以复用在恢复会话和分叉会话两种场景。

数据流：输入是一个动作值，比如恢复或分叉 → 函数按这个值挑出对应的短词 → 输出一段固定文字，用来放进提示标题里。

调用关系：它不自己决定什么时候显示，只在画界面时被 CwdPromptScreen::render_ref 调用，帮渲染函数把动作说成人能读懂的话。

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

fn past_participle(self) -> &'static str

作用：把动作类型变成过去分词形式，比如“resumed”或“forked”。它用于解释“会话目录”是什么意思。

数据流：输入是当前提示对应的动作 → 函数选择合适的过去式说法 → 输出一段说明文字里的词，让句子读起来正确。

调用关系：它在 CwdPromptScreen::render_ref 画说明文字时被调用，和 verb 一起让同一套界面适配不同动作。

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

fn next(self) -> Self

作用：在两个目录选项之间切到下一个。因为这里只有两项，所以再往下就会绕回另一项。

数据流：输入是当前高亮的选项 → 如果现在是当前目录，就切到会话目录；如果现在是会话目录，就切到当前目录 → 输出新的高亮选项。

调用关系：当用户按向下键或 j 时，CwdPromptScreen::handle_key 会调用它，然后再交给 set_highlight 更新屏幕状态。

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

fn prev(self) -> Self

作用：在两个目录选项之间切到上一个。由于只有两个选项，它和“下一个”一样，都是在两项之间来回切换。

数据流：输入是当前高亮的选项 → 函数算出另一个选项 → 输出新的高亮选项。

调用关系：当用户按向上键或 k 时，CwdPromptScreen::handle_key 会调用它，再把结果交给 set_highlight。

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

async fn run_cwd_selection_prompt(
    tui: &mut Tui,
    action: CwdPromptAction,
    current_cwd: &Path,
    session_cwd: &Path,
) -> Result<CwdPromptOutcome>

作用：这是外部真正会调用的入口：弹出工作目录选择提示，等用户做决定，然后返回选择结果或退出结果。

数据流：输入是终端界面对象、这次是恢复还是分叉、当前目录、会话记录目录 → 它创建提示屏幕，先画一次，然后不断读取键盘、重画或响应窗口变化 → 输出是“用户选了哪个目录”或“用户退出了”，同时会驱动终端画面更新。

调用关系：它由 resolve_cwd_for_resume_or_fork 在需要决定工作目录时调用。它先用 CwdPromptScreen::new 建状态，再通过 TUI 的事件流接收按键，把按键交给 CwdPromptScreen::handle_key，需要画面刷新时调用终端绘制。

调用图：调用 1 个内部函数（new）；被 1 处调用（resolve_cwd_for_resume_or_fork）；外部调用 6 个（display, draw, event_stream, frame_requester, pin!, Selection）。

fn new(
        request_frame: FrameRequester,
        action: CwdPromptAction,
        current_cwd: String,
        session_cwd: String,
    ) -> Self

作用：创建一个新的提示框状态。它把动作、两个目录文字和默认高亮项都准备好。

数据流：输入是刷新画面的请求器、动作类型、当前目录字符串、会话目录字符串 → 它把这些装进一个屏幕状态对象，并默认高亮“会话目录” → 输出一个可以处理按键和绘制界面的 CwdPromptScreen。

调用关系：run_cwd_selection_prompt 在真正弹窗前调用它。测试里的 tests::new_prompt 和 tests::cwd_prompt_fork_snapshot 也会调用它，用来搭出可检查的假界面。

调用图：被 3 处调用（run_cwd_selection_prompt, cwd_prompt_fork_snapshot, new_prompt）。

fn handle_key(&mut self, key_event: KeyEvent)

作用：处理用户按下的键。它决定按键是移动高亮、确认选择，还是退出提示。

数据流：输入是一次键盘事件 → 它先忽略按键释放事件，再识别 Ctrl-C、Ctrl-D、方向键、j/k、数字键、回车和 Esc → 结果是更新高亮、写入最终选择、标记退出，并在状态变化后请求重画界面。

调用关系：主循环 run_cwd_selection_prompt 收到键盘事件后会把事件交给它。它内部会调用 CwdSelection::next、CwdSelection::prev 算高亮位置，再调用 set_highlight 或 select 改状态。

调用图：调用 5 个内部函数（select, set_highlight, next, prev, schedule_frame）；外部调用 1 个（matches!）。

fn set_highlight(&mut self, highlight: CwdSelection)

作用：改变当前高亮的选项，也就是光标停在哪一行。只有真的变了，才通知界面重画。

数据流：输入是新的高亮选项 → 它和旧高亮比较，如果不同就保存新值 → 输出没有返回值，但会改变屏幕状态，并安排下一帧刷新。

调用关系：它由 CwdPromptScreen::handle_key 在用户上下移动时调用。它把“按键含义”落成具体状态变化，并通过 schedule_frame 告诉界面该重画了。

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

fn select(&mut self, selection: CwdSelection)

作用：确认用户最终选择了哪个目录。它也会把高亮同步到所选项，让界面状态保持一致。

数据流：输入是用户选中的目录类型 → 它把高亮改到该项，并把选择结果存起来 → 输出没有返回值，但屏幕会进入“已经完成”的状态，并请求重画。

调用关系：它由 CwdPromptScreen::handle_key 在用户按数字键、回车或 Esc 时调用。之后主循环会通过 is_done 发现已经选完，然后结束提示。

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

fn is_done(&self) -> bool

作用：告诉外部这个提示是否已经结束。结束原因可能是用户选好了，也可能是用户要求退出。

数据流：输入是当前屏幕状态 → 它检查退出标记和选择结果是否存在 → 输出一个真假值：真表示提示可以收场了。

调用关系：run_cwd_selection_prompt 的等待循环会反复用它判断要不要继续收键盘事件。测试也用它确认 Ctrl-C 会让提示结束。

fn selection(&self) -> Option<CwdSelection>

作用：取出用户当前已经确认的选择。如果还没选，返回空。

数据流：输入是屏幕里保存的状态 → 它读取选择字段 → 输出可能是会话目录、当前目录，也可能什么都没有。

调用关系：run_cwd_selection_prompt 在提示结束后用它生成最终结果。测试也用它检查回车、切换后回车、Ctrl-C 的结果是否符合预期。

fn render_ref(&self, area: Rect, buf: &mut Buffer)

作用：把提示框实际画到终端上，包括标题、说明文字、两个目录选项和回车提示。

数据流：输入是要画的区域和终端缓冲区（一块准备写字的屏幕内存），以及屏幕状态里的动作、目录和高亮信息 → 它先清空区域，再组装多行文字和选项行 → 输出是写入缓冲区的界面内容，用户下一次刷新时就能看到。

调用关系：终端绘制时会调用它。它会向 CwdPromptAction::verb 和 CwdPromptAction::past_participle 要合适的动作文字，并用 selection_option_row 生成带高亮效果的选项行。

调用图：调用 5 个内部函数（past_participle, verb, tlbr, new, selection_option_row）；外部调用 3 个（from, format!, vec!）。

fn new_prompt() -> CwdPromptScreen

作用：给测试快速造一个标准的提示框。这样每个测试不用重复写同样的假目录和假刷新器。

数据流：输入没有外部参数 → 它准备一个测试用刷新请求器，以及固定的当前目录和会话目录 → 输出一个默认用于“恢复会话”的 CwdPromptScreen。

调用关系：多个测试会调用它来拿到同样的起点。它内部调用 CwdPromptScreen::new，把测试准备工作集中在一个地方。

调用图：调用 2 个内部函数（new, test_dummy）。

fn cwd_prompt_snapshot()

作用：检查恢复会话时，这个提示框画出来的样子有没有意外变化。快照测试就像给界面拍一张标准照片，以后每次对比。

数据流：输入是测试里造出的提示屏幕和一个假的 80x14 终端 → 它把界面画到假终端上 → 输出是和保存的快照做比较；如果画面变了，测试会失败或要求更新快照。

调用关系：测试运行器会执行它。它通过 tests::new_prompt 创建屏幕，再触发终端绘制，间接覆盖 CwdPromptScreen::render_ref 的显示效果。

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

fn cwd_prompt_fork_snapshot()

作用：检查分叉会话时提示框的文字和画面是否正确。它专门确认“fork”场景不会误显示成“resume”。

数据流：输入是测试中手工创建的分叉提示屏幕和假终端 → 它渲染界面 → 输出是与名为分叉弹窗的快照比较结果。

调用关系：测试运行器会执行它。它直接调用 CwdPromptScreen::new 创建分叉场景，再通过绘制流程检查 render_ref 使用动作文字的行为。

调用图：调用 3 个内部函数（new, new, test_dummy）；外部调用 2 个（assert_snapshot!, new）。

fn cwd_prompt_selects_session_by_default()

作用：确认用户直接按回车时，默认选择的是会话目录。这很重要，因为界面一开始高亮的就是会话目录。

数据流：输入是一个新建的提示屏幕 → 测试模拟用户按下回车 → 输出是断言结果：选择应当是 CwdSelection::Session。

调用关系：测试运行器会执行它。它用 tests::new_prompt 建屏幕，再通过 CwdPromptScreen::handle_key 走真实按键逻辑，最后用 selection 查看结果。

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

fn cwd_prompt_can_select_current()

作用：确认用户可以从默认的会话目录切到当前目录并选择它。也就是验证向下移动和回车确认能配合工作。

数据流：输入是一个新建的提示屏幕 → 测试先模拟按向下键，再模拟按回车 → 输出是断言结果：最终选择应当是 CwdSelection::Current。

调用关系：测试运行器会执行它。它通过 handle_key 触发和真实用户一样的流程，间接检查 next、set_highlight、select 这些步骤是否串起来了。

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

fn cwd_prompt_ctrl_c_exits_instead_of_selecting()

作用：确认 Ctrl-C 会退出提示，而不是偷偷选中某个目录。这样用户取消操作时不会产生误选择。

数据流：输入是一个新建的提示屏幕 → 测试模拟按下 Ctrl-C → 输出是两个检查：没有选择结果，并且提示已经结束。

调用关系：测试运行器会执行它。它调用 handle_key 走取消路径，再用 selection 和 is_done 验证屏幕状态。

调用图：外部调用 5 个（Char, new, assert!, assert_eq!, new_prompt）。

fn handle_paste(&mut self, _pasted: String)

作用：这是键盘处理接口里给“粘贴文本”准备的默认做法。默认什么都不做，表示不是每个页面都需要处理粘贴。

数据流：进去的是一段粘贴进来的文字 → 默认实现直接忽略它 → 没有返回结果，也不改任何状态。

调用关系：具体页面如果需要粘贴，比如 API key 输入框，可以自己覆盖这个方法；不需要粘贴的页面就沿用这个空实现。

async fn new(tui: &mut Tui, args: OnboardingScreenArgs) -> Self

作用：创建整个引导界面，并按配置决定要放哪些步骤。比如是否需要登录页、是否需要信任目录页、默认高亮哪种登录方式。

数据流：进去的是终端对象和一组引导参数，包括登录状态、配置、服务器请求句柄、是否显示某些页面 → 它创建欢迎页，必要时创建登录页和目录信任页，还会尝试找出当前项目的 Git 根目录作为信任目标 → 出来的是一个准备好运行的 OnboardingScreen。

调用关系：run_onboarding_app 在引导开始时调用它。它会用 Tui 提供的 frame_requester 来请求刷新画面，也会调用 resolve_root_git_project_for_trust 来确定应该信任哪个目录。

调用图：调用 2 个内部函数（new, level_from_config）；被 1 处调用（run_onboarding_app）；外部调用 11 个（new, new, new, resolve_root_git_project_for_trust, frame_requester, Auth, TrustDirectory, Welcome, matches!, new (+1 more)）。

fn current_steps_mut(&mut self) -> Vec<&mut Step>

作用：找出当前应该参与交互的步骤，并返回可修改版本。它会包括已经完成的可见步骤，以及第一个正在进行的步骤。

数据流：进去的是当前引导界面的步骤列表 → 它从头扫描，跳过隐藏步骤，收集完成步骤，遇到第一个正在进行的步骤后停止 → 出来的是这些步骤的可修改引用。

调用关系：按键和粘贴处理会用它找到真正该接收输入的当前步骤。这样后面的未开始步骤不会提前响应用户操作。

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

fn current_steps(&self) -> Vec<&Step>

作用：找出当前应该显示的步骤，但只读不修改。它用于画界面和判断当前可见步骤的状态。

数据流：进去的是当前步骤列表 → 它跳过隐藏步骤，保留已完成步骤和第一个正在进行的步骤 → 出来的是这些步骤的只读引用。

调用关系：render_ref 用它决定画哪些内容；should_suppress_animations 也用它判断当前页面是否需要暂停动画。

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

fn should_suppress_animations(&self) -> bool

作用：判断整个引导界面现在要不要暂停动画。主要是为了用户复制登录信息时，画面不要一直重绘打断终端选择。

数据流：进去的是当前界面状态 → 它查看当前可见步骤里是否有登录页要求暂停动画 → 出来是 true 或 false，表示是否压住动画。

调用关系：render_ref 在每次画界面前调用它，然后把这个决定传给欢迎页和登录页。

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

fn is_auth_in_progress(&self) -> bool

作用：判断登录步骤现在是不是正在进行。这个信息用于决定用户按退出键时，要不要取消正在进行的登录尝试。

数据流：进去的是步骤列表 → 它查找是否存在登录步骤，并且这个登录步骤状态是进行中 → 出来是一个布尔值。

调用关系：handle_key_event 在处理退出快捷键时调用它。如果登录正在进行，就先取消登录，再把整个引导标记为结束并要求退出程序。

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

fn is_done(&self) -> bool

作用：告诉外层循环：引导流程是不是已经结束。结束可能是用户主动退出，也可能是所有需要做的步骤都完成了。

数据流：进去的是 OnboardingScreen 当前状态 → 它先看 is_done 标记，再看是否还有任何步骤处于进行中 → 出来是 true 或 false。

调用关系：run_onboarding_app 的主循环靠它决定是否继续监听按键、重绘和服务器消息。

fn should_exit(&self) -> bool

作用：告诉调用者，引导结束后是不是应该直接退出整个程序。比如用户在未登录状态下取消登录，就可能需要退出。

数据流：进去的是当前 should_exit 字段 → 直接把这个布尔值返回 → 不修改任何东西。

调用关系：run_onboarding_app 在结束时把这个值放进 OnboardingResult，交给更外层的程序决定下一步。

fn cancel_auth_if_active(&self)

作用：如果登录页正在做登录尝试，就让它取消。这样用户按退出时，不会留下一个后台还在跑的登录流程。

数据流：进去的是当前所有步骤 → 它逐个检查，找到登录步骤后调用登录控件的取消方法 → 没有返回值，但可能让登录尝试停止。

调用关系：handle_key_event 在确认用户真的要退出，并且登录正在进行时调用它。

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

fn auth_widget_mut(&mut self) -> Option<&mut AuthModeWidget>

作用：从步骤列表里找出登录控件，并返回可修改引用。服务器发来的登录结果需要交给它处理。

数据流：进去的是步骤列表 → 它查找 Auth 类型的步骤 → 找到就返回登录控件，找不到就返回空。

调用关系：handle_app_server_notification 用它拿到登录页，然后把账号登录完成或账号更新的通知转交过去。

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

fn handle_app_server_notification(&mut self, notification: ServerNotification)

作用：处理应用服务器发来的通知，尤其是登录完成和账号信息更新。它把这些消息转发给登录页。

数据流：进去的是一条服务器通知 → 它判断通知类型，如果是账号登录完成或账号更新，就找到登录控件并调用对应处理方法；其他通知忽略 → 可能改变登录页状态。

调用关系：run_onboarding_app 在监听到 AppServerEvent::ServerNotification 时调用它。它内部依赖 auth_widget_mut 找到真正能处理登录消息的页面。

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

fn api_key_entry_context(&self) -> ApiKeyEntryContext

作用：查看当前是否正在输入 API key，以及输入框里是否已经有文字。这个信息用来避免把用户正在输入的 q 误当成退出键。

数据流：进去的是步骤列表 → 它找到登录步骤，询问 API key 输入状态和是否有文本 → 出来是 ApiKeyEntryContext；如果没有登录页，就返回默认的“未输入”状态。

调用关系：handle_key_event 在判断退出快捷键前调用它，再交给 suppress_quit_while_typing_api_key 做最终判断。

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

fn handle_key_event(&mut self, key_event: KeyEvent)

作用：这是整个引导界面的按键总入口。它决定一个按键是退出、输入文字，还是交给当前步骤处理。

数据流：进去的是一个键盘事件 → 它先忽略按下以外的事件，再判断是否是退出键；如果用户正在输入非空 API key，普通字符退出键会被保护起来；如果确认退出，就设置结束状态，必要时取消登录；否则把按键交给欢迎页和当前活跃步骤 → 最后请求终端重画。

调用关系：TUI 主循环收到按键后调用它。它会用 api_key_entry_context、suppress_quit_while_typing_api_key、is_auth_in_progress、cancel_auth_if_active 和 current_steps_mut 来完成判断和分发。

调用图：调用 6 个内部函数（api_key_entry_context, cancel_auth_if_active, current_steps_mut, is_auth_in_progress, suppress_quit_while_typing_api_key, schedule_frame）；外部调用 1 个（matches!）。

fn handle_paste(&mut self, pasted: String)

作用：处理用户往终端里粘贴文字。它只把非空粘贴内容交给当前活跃步骤。

数据流：进去的是粘贴文本 → 如果文本为空就直接返回；否则找到当前活跃步骤，把文本交给它 → 然后请求刷新画面。

调用关系：run_onboarding_app 收到 TuiEvent::Paste 时会调用它。它通过 current_steps_mut 找到当前真正应该接收粘贴的页面。

调用图：调用 2 个内部函数（current_steps_mut, schedule_frame）。

fn suppress_quit_while_typing_api_key(
    key_event: KeyEvent,
    api_key_entry_context: ApiKeyEntryContext,
) -> bool

作用：判断某个退出快捷键此刻应不应该被当作普通输入。它专门保护 API key 输入框，防止用户输入 q 时误退出。

数据流：进去的是一个按键事件和 API key 输入状态 → 它检查是否正在输入、输入框是否已有文字、按键是否是普通字符、是否没有 Ctrl/Alt 修饰键 → 出来是 true 或 false，true 表示这次不要退出，要当文字处理。

调用关系：OnboardingScreen::handle_key_event 用它做退出保护。测试函数也直接调用它，验证空输入、已有输入、Ctrl 键、非 API key 状态这些边界情况。

调用图：被 5 处调用（handle_key_event, does_not_suppress_control_quit_key_during_api_key_entry, does_not_suppress_printable_quit_key_when_api_key_input_is_empty, does_not_suppress_when_not_in_api_key_entry, suppresses_printable_quit_key_during_api_key_entry）；外部调用 1 个（matches!）。

fn render_ref(&self, area: Rect, buf: &mut Buffer)

作用：把当前引导界面画到终端屏幕上。它按从上到下的顺序画欢迎、登录、信任目录等当前可见步骤。

数据流：进去的是屏幕区域和绘图缓冲区 → 它先判断是否要暂停动画，清空区域，再为每个当前可见步骤估算需要的高度，最后把步骤逐个画到正确位置 → 输出是更新后的终端缓冲区。

调用关系：TUI draw 调用它来重绘引导页。它会调用 current_steps 和 should_suppress_animations，并把真正的绘制工作交给每个 Step 自己的 render_ref。

调用图：调用 2 个内部函数（current_steps, should_suppress_animations）；外部调用 2 个（empty, new）。

fn handle_key_event(&mut self, key_event: KeyEvent)

作用：把按键交给具体的步骤控件。Step 是一个包装盒，里面可能是欢迎页、登录页或信任目录页。

数据流：进去的是一个按键事件和当前 Step → 它看 Step 里面实际是哪种页面，然后调用对应页面的按键处理方法 → 可能改变那个页面的状态。

调用关系：OnboardingScreen::handle_key_event 找到活跃步骤后，通过这个方法把按键转交给真正的页面。

fn handle_paste(&mut self, pasted: String)

作用：把粘贴文本交给支持粘贴的具体步骤。欢迎页不需要粘贴，所以会忽略。

数据流：进去的是粘贴文本和当前 Step → 如果是登录页或信任目录页，就转给对应控件；如果是欢迎页，就不做事 → 可能改变输入框或选择状态。

调用关系：OnboardingScreen::handle_paste 找到活跃步骤后调用它。它负责把统一的粘贴事件分发到具体页面。

fn get_step_state(&self) -> StepState

作用：询问某个步骤现在是隐藏、进行中，还是已完成。外层流程靠这个判断该显示什么、下一步走到哪里。

数据流：进去的是一个 Step → 它查看里面的具体页面，并调用该页面自己的状态方法 → 出来是 StepState。

调用关系：current_steps、current_steps_mut、is_done 等流程判断都依赖它。它让不同页面可以用同一种方式告诉外层自己的进度。

fn render_ref(&self, area: Rect, buf: &mut Buffer)

作用：把某个具体步骤画出来。它只是转发绘图请求，真正画法由欢迎页、登录页或信任目录页自己决定。

数据流：进去的是绘图区域、缓冲区和当前 Step → 它判断 Step 类型并调用对应控件的 render_ref → 缓冲区被写入该步骤的画面内容。

调用关系：OnboardingScreen::render_ref 在逐步绘制页面时调用它。这个方法让外层不用关心每种页面的内部画法。

async fn run_onboarding_app(
    args: OnboardingScreenArgs,
    mut app_server: Option<&mut AppServerSession>,
    tui: &mut Tui,
) -> Result<OnboardingResult>

作用：运行完整的引导流程。它创建引导界面，进入事件循环，同时听终端输入和服务器消息，直到引导结束。

数据流：进去的是引导参数、可选的应用服务器会话和终端对象 → 它创建 OnboardingScreen，先画一次界面，然后循环处理按键、粘贴、重绘、窗口变化、服务器通知和断线；如果用户选择信任目录，还会尝试保存这个选择 → 出来是 OnboardingResult，说明目录信任是否保存成功，以及是否应退出程序。

调用关系：更外层的 run_ratatui_app 会调用它。它是这个文件的运行核心，连接 TUI 事件流、AppServerSession、OnboardingScreen 和 persist_selected_trust。

调用图：调用 1 个内部函数（new）；被 1 处调用（run_ratatui_app）；外部调用 4 个（draw, event_stream, pin!, select!）。

async fn persist_selected_trust(
    onboarding_screen: &mut OnboardingScreen,
    request_handle: Option<AppServerRequestHandle>,
) -> bool

作用：把用户选择“信任当前项目目录”的决定保存下来。这样下次进入这个项目时，程序知道用户已经确认过。

数据流：进去的是引导界面和可选的服务器请求句柄 → 它查找信任目录步骤，确认用户选择了 Trust，然后通过 write_trusted_project 写入配置；如果失败，就格式化错误信息，清掉选择，并把错误显示回信任目录页 → 出来是 true 或 false，表示是否保存成功。

调用关系：run_onboarding_app 在按键处理后调用它，避免用户点了信任但结果没落盘。测试 trust_persistence_failure_keeps_trust_step_in_progress 也调用它验证失败时页面不会假装完成。

调用图：调用 2 个内部函数（format_config_error, write_trusted_project）；被 1 处调用（trust_persistence_failure_keeps_trust_step_in_progress）；外部调用 3 个（eyre!, format!, error!）。

fn suppresses_printable_quit_key_during_api_key_entry()

作用：测试用户正在输入非空 API key 时，普通的 q 会被保护，不会触发退出。

数据流：进去的是模拟的 q 按键和“API key 输入中且已有文字”的状态 → 调用 suppress_quit_while_typing_api_key → 断言结果是 true。

调用关系：它直接验证退出保护函数最关键的场景：用户已经开始输入密钥时，普通字符不能把程序关掉。

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

fn does_not_suppress_printable_quit_key_when_api_key_input_is_empty()

作用：测试 API key 输入框为空时，普通 q 仍然可以作为退出键使用。

数据流：进去的是模拟的 q 按键和“API key 输入中但没有文字”的状态 → 调用 suppress_quit_while_typing_api_key → 断言结果是 false。

调用关系：它保证保护规则不会太过头。空输入框时，用户按 q 退出仍然方便。

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

fn does_not_suppress_control_quit_key_during_api_key_entry()

作用：测试带 Ctrl 的退出快捷键在 API key 输入中不会被拦住。Ctrl/Alt 这类组合键被视为明确的退出指令。

数据流：进去的是模拟的 Ctrl+x 按键和“API key 输入中且已有文字”的状态 → 调用 suppress_quit_while_typing_api_key → 断言结果是 false。

调用关系：它验证紧急退出通道仍然可用，配合 handle_key_event 的退出判断保证用户不会被困在输入框里。

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

fn does_not_suppress_when_not_in_api_key_entry()

作用：测试不在 API key 输入模式时，不会启用这条特殊保护规则。

数据流：进去的是模拟普通字符按键和“没有处于 API key 输入”的状态 → 调用 suppress_quit_while_typing_api_key → 断言结果是 false。

调用关系：它保证 suppress_quit_while_typing_api_key 只影响 API key 输入场景，不会改变其他页面的退出行为。

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

async fn trust_persistence_failure_keeps_trust_step_in_progress()

作用：测试保存信任目录失败时，信任步骤会留在进行中，并显示错误，而不是错误地继续往下走。

数据流：进去的是一个手工构造的引导界面，其中用户已经选择信任目录，但没有可用的服务器请求句柄 → 调用 persist_selected_trust → 得到 false，并检查选择被清空、步骤仍是进行中、错误信息包含服务器不可用。

调用关系：它保护 persist_selected_trust 的失败路径。这个行为很重要，因为目录信任如果没真正保存成功，界面必须让用户知道并继续停在这一步。

调用图：调用 2 个内部函数（persist_selected_trust, test_dummy）；外部调用 4 个（assert!, assert_eq!, panic!, vec!）。

fn handle_key_event(&mut self, key_event: KeyEvent)

作用：这个函数在欢迎页收到键盘按键时运行。它只关心一个事：当动画功能开启，并且用户按下切换动画的快捷键时，换一个随机的欢迎动画样式。

数据流：进去的是一个按键事件，以及组件里保存的动画开关和当前动画 → 它先检查动画有没有启用，再确认这次是不是“按下”动作并且匹配切换动画快捷键 → 如果匹配，就记录一条提示日志，并让动画对象随机挑一个新版本；没有返回值，只改变当前动画的样子。

调用关系：它是欢迎页接入键盘输入的入口，由引导屏幕的键盘分发机制在用户按键时调用。真正挑动画的活交给 animation.pick_random_variant，自己只负责判断这个按键该不该触发。

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

fn new(
        is_logged_in: bool,
        request_frame: FrameRequester,
        animations_enabled: bool,
    ) -> Self

作用：这个函数创建一个新的欢迎页组件。调用者会告诉它用户是否已登录、怎么请求界面重画，以及动画要不要启用。

数据流：进去的是登录状态、一个用于请求重新绘制界面的 FrameRequester、动画总开关 → 它创建一个 AsciiAnimation，把动画压制状态设为 false，把已知布局区域设为空 → 出来的是一个可以被渲染、可以响应按键的 WelcomeWidget。

调用关系：这是外部组装欢迎页时最常用的构造函数，也被测试用来搭出真实组件。它把动画创建工作交给 AsciiAnimation::new，把后续绘制交给 render_ref，把按键响应交给 handle_key_event。

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

fn update_layout_area(&self, area: Rect)

作用：这个函数记录欢迎页实际可用的布局区域。它的用处是让渲染时知道窗口到底有多大，从而决定动画会不会被画出来。

数据流：进去的是一个 Rect，也就是终端界面中的一块矩形区域 → 它把这个区域存进组件内部的小盒子里 → 出来没有直接结果，但之后 render_ref 会读取这个区域来判断空间是否足够。

调用关系：它通常由外层布局代码在算好屏幕区域后调用。它不画界面，只给 render_ref 提供判断依据，避免动画在太小的区域里被截断。

fn set_animations_suppressed(&self, suppressed: bool)

作用：这个函数临时暂停或恢复欢迎页动画。它适合在某些情况下让界面安静下来，比如别的层级正在展示内容时不希望背景继续动。

数据流：进去的是一个布尔值：true 表示压制动画，false 表示允许动画 → 它把这个状态保存到组件内部 → 后续 render_ref 会根据这个状态决定是否安排下一帧、是否显示动画。

调用关系：它由外部流程控制欢迎页动画的开关细节。它不直接碰动画帧，而是给 render_ref 和 handle_key_event 之外的显示逻辑一个“先别动”的信号。

fn render_ref(&self, area: Rect, buf: &mut Buffer)

作用：这个函数真正把欢迎页画到终端缓冲区里。它负责清屏、安排动画下一帧、选择要显示的文字行，并把这些内容写进界面。

数据流：进去的是要绘制的区域 area 和一个 Buffer，Buffer 可以理解成终端屏幕的草稿纸 → 它先清掉该区域；如果动画启用且没被压制，就安排下一帧；再根据记录的布局区域判断尺寸够不够；够大就加入当前动画帧，不够就跳过动画；最后加入“Welcome to Codex...”文字并写入 Buffer → 出来没有返回值，但屏幕草稿纸被改成欢迎页内容。

调用关系：它是 ratatui 这个终端界面库在需要画欢迎页时调用的核心函数。它向 animation.current_frame 要当前画面，向 animation.schedule_next_frame 安排之后重画，然后用 Paragraph 把结果交给 ratatui 画出来。

调用图：调用 2 个内部函数（current_frame, schedule_next_frame）；外部调用 4 个（from, new, new, vec!）。

fn get_step_state(&self) -> StepState

作用：这个函数告诉新手引导流程，欢迎页这个步骤现在算什么状态。它让引导流程知道是否应该显示这个欢迎步骤。

数据流：进去的是组件内部保存的 is_logged_in 登录状态 → 如果用户已登录，它返回 Hidden，表示这个步骤隐藏；如果未登录，它返回 Complete，表示欢迎步骤不阻塞流程 → 它不改动任何数据。

调用关系：它由引导屏幕的步骤管理逻辑调用，用来决定欢迎页在整套 onboarding 流程里的位置。它不依赖渲染，也不触发动画，只提供状态判断。

fn row_containing(buf: &Buffer, needle: &str) -> Option<u16>

作用：这是测试用的小帮手，用来在终端缓冲区里找某段文字出现在哪一行。它让测试不用关心每个字符的精确位置，只检查关键文字的大概行号。

数据流：进去的是一个 Buffer 和要寻找的字符串 needle → 它从上到下扫描每一行，把这一行的所有格子拼成普通字符串，再看里面有没有 needle → 找到就返回行号，找不到就返回 None。

调用关系：它只在本文件测试里使用。welcome_renders_animation_on_first_draw 和 welcome_skips_animation_below_height_breakpoint 会调用它来确认“Welcome”被画在预期位置。

fn welcome_renders_animation_on_first_draw()

作用：这个测试确认：当窗口够大、动画也开启时，欢迎页第一次绘制就会把动画画出来。它防止以后有人改代码时不小心让欢迎页只剩文字。

数据流：进去没有外部输入 → 测试创建一个启用动画的 WelcomeWidget，准备一个足够大的空 Buffer，先数出当前动画有多少行，再执行绘制 → 最后查找“Welcome”所在行，确认它在动画之后，也就是动画确实占了上方空间。

调用关系：它调用 WelcomeWidget::new 创建组件，调用 render 触发 WelcomeWidget::render_ref，再用 tests::row_containing 检查结果。这个测试覆盖的是正常大窗口下的渲染路径。

调用图：调用 2 个内部函数（new, test_dummy）；外部调用 4 个（empty, new, assert_eq!, row_containing）。

fn welcome_skips_animation_below_height_breakpoint()

作用：这个测试确认：当窗口高度不够时，欢迎页会跳过动画，直接显示欢迎文字。这样可以避免字符画被截断，界面看起来乱七八糟。

数据流：进去没有外部输入 → 测试创建一个启用动画的 WelcomeWidget，但给它一个比最低动画高度少一行的 Buffer → 绘制后查找“Welcome”，确认它出现在第一行，说明动画没有被画在前面。

调用关系：它和上一个渲染测试形成对照：同样通过 WelcomeWidget::new 建组件、通过 render_ref 间接绘制、通过 row_containing 查结果，但重点检查小窗口分支。

调用图：调用 2 个内部函数（new, test_dummy）；外部调用 4 个（empty, new, assert_eq!, row_containing）。

fn ctrl_dot_changes_animation_variant()

作用：这个测试确认 Ctrl+. 这个快捷键真的会切换欢迎动画版本。它防止键盘快捷键失效后用户无法手动换动画。

数据流：进去没有外部输入 → 测试用两个固定动画版本手工创建 WelcomeWidget，记录按键前的当前帧 → 构造一个 Ctrl+. 按键事件并交给 handle_key_event → 再读取当前帧，确认前后不一样。

调用关系：它直接测试 WelcomeWidget::handle_key_event 的关键行为。动画对象由 AsciiAnimation::with_variants 准备，这样测试能明确知道切换前后应该不同。

调用图：调用 2 个内部函数（with_variants, test_dummy）；外部调用 4 个（new, Char, new, assert_ne!）。

fn ctrl_shift_dot_changes_animation_variant()

作用：这个测试确认 Ctrl+Shift+. 也能切换欢迎动画版本。它照顾不同终端上修饰键上报方式不完全一样的情况。

数据流：进去没有外部输入 → 测试准备两个固定动画版本，记录当前帧 → 构造一个带 Control 和 Shift 的点号按键事件，交给 handle_key_event → 再比较当前帧，确认动画已经换成另一个版本。

调用关系：它补充验证快捷键兼容性，仍然围绕 WelcomeWidget::handle_key_event 展开。和 ctrl_dot_changes_animation_variant 一起保证两种终端按键写法都能触发同一件事。

调用图：调用 2 个内部函数（with_variants, test_dummy）；外部调用 4 个（new, Char, new, assert_ne!）。

fn mark_url_hyperlink(buf: &mut Buffer, area: Rect, url: &str)

作用：把终端画面里看起来像链接的那一段文字，标成真正可点击的超链接。这样即使登录网址太长换行了，用户也能点击完整链接。

数据流：进去的是一个终端绘图缓冲区、要检查的屏幕区域、以及 URL → 它把工作转交给通用的 terminal_hyperlinks 工具，给青色且带下划线的格子包上 OSC 8 超链接标记 → 出来没有新值，但缓冲区里的对应字符被改成可点击链接。

调用关系：登录浏览器页面渲染完 URL 后会调用它；相关测试也直接调用它，确认换行链接能完整标记，并且恶意控制字符会被清理。

调用图：调用 1 个内部函数（mark_url_hyperlink）；被 3 处调用（render_continue_in_browser, mark_url_hyperlink_sanitizes_control_chars, mark_url_hyperlink_wraps_cyan_underlined_cells）。

fn mark_underlined_hyperlink(buf: &mut Buffer, area: Rect, url: &str)

作用：把指定区域里所有带下划线的文字都标成同一个可点击链接。它是给其他界面复用的小包装函数。

数据流：进去的是缓冲区、区域和 URL → 它调用通用超链接工具，寻找带下划线的字符并加上终端超链接标记 → 缓冲区被原地修改，没有返回值。

调用关系：这个文件里只提供这个入口，没有在本文件内直接使用；它把具体活儿交给 crate::terminal_hyperlinks。

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

fn onboarding_request_id() -> codex_app_server_protocol::RequestId

作用：给引导登录请求生成一个新的请求编号。请求编号就像快递单号，后台靠它区分不同请求。

数据流：进去不需要参数 → 它生成一个 UUID（一串几乎不会重复的随机编号），再包装成应用服务器协议需要的 RequestId → 返回这个请求编号。

调用关系：取消登录、保存 API key、开始 ChatGPT 登录时都会用它，保证每次发给后台的请求都有独立身份。

调用图：被 3 处调用（save_api_key, start_chatgpt_login, cancel_login_attempt）；外部调用 2 个（new_v4, String）。

async fn cancel_login_attempt(
    request_handle: &AppServerRequestHandle,
    login_id: String,
)

作用：告诉后台取消某一次正在进行的登录。用户按取消时，不只是界面退回去，也要让后台别继续等这次登录。

数据流：进去的是后台请求句柄和 login_id → 它生成请求编号，组装取消登录请求并异步发送 → 不返回有用结果，失败也被忽略，因为取消只是尽力而为。

调用关系：AuthModeWidget::cancel_active_attempt 会在浏览器登录或设备码登录中调用它，并放到 tokio 异步任务里执行，避免卡住界面。

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

fn pending(request_id: String) -> Self

作用：创建一个“设备码登录还在申请中”的状态。此时只有请求编号，还没有给用户看的网址和验证码。

数据流：进去的是 request_id → 它把 login_id、verification_url、user_code 都设为空 → 返回一个表示等待后台回复的设备码状态。

调用关系：设备码登录子模块启动时会用它；测试也用它确认申请设备码期间动画应该被压住。

调用图：被 4 处调用（start_headless_chatgpt_login, device_code_attempt_matches_only_for_matching_request_id, pending_device_code_state, auth_widget_suppresses_animations_while_requesting_device_code）。

fn ready(
        request_id: String,
        login_id: String,
        verification_url: String,
        user_code: String,
    ) -> Self

作用：创建一个“设备码已经拿到，可以给用户看了”的状态。用户这时可以去网页输入一次性代码完成登录。

数据流：进去的是请求编号、登录编号、验证网址、用户代码 → 它把这些都存进状态对象 → 返回一个完整可展示的设备码登录状态。

调用关系：设备码登录子模块收到后台结果后会用它；取消登录、成功回调和多个测试都依赖这个状态里的 login_id 和验证码信息。

调用图：被 4 处调用（start_headless_chatgpt_login, auth_widget_suppresses_animations_when_device_code_is_visible, cancel_active_attempt_notifies_device_code_login, device_code_login_completion_advances_to_success_message）。

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

作用：安全地取出这次设备码登录的 login_id。它可能还没准备好，所以返回的是“可能有，也可能没有”。

数据流：进去的是当前设备码状态 → 它查看内部 login_id 字段，并把 String 转成只读字符串引用 → 返回 Option<&str>，不修改状态。

调用关系：取消登录和登录完成通知匹配时会用它，确保只取消或完成当前这一次登录。

fn is_showing_copyable_auth(&self) -> bool

作用：判断设备码登录画面现在是不是已经有可复制的网址和验证码。这样界面才知道能不能显示复制提示。

数据流：进去的是当前设备码状态 → 它检查验证网址和用户代码是否都存在且不是空字符串 → 返回 true 或 false，不改任何数据。

调用关系：设备码登录渲染函数会调用它，决定是否展示可复制的认证信息。

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

fn handle_key_event(&mut self, key_event: KeyEvent)

作用：处理登录界面的按键。用户按上下、数字、确认、取消，都会从这里进入。

数据流：进去的是一个键盘事件 → 它先让 API key 输入框处理字符类按键；如果不是输入框事件，再处理移动、选择、确认、取消 → 输出没有返回值，但会改变高亮项、登录状态、错误信息，并可能触发重新绘制。

调用关系：这是 onboarding 屏幕交给 AuthModeWidget 的键盘入口；它会把具体动作分给 move_highlight、select_option_by_index、handle_sign_in_option 或 cancel_active_attempt。

调用图：调用 5 个内部函数（cancel_active_attempt, handle_api_key_entry_key_event, handle_sign_in_option, move_highlight, select_option_by_index）；外部调用 1 个（info!）。

fn handle_paste(&mut self, pasted: String)

作用：处理用户粘贴内容，主要用于一次性粘贴 API key。

数据流：进去的是粘贴出来的字符串 → 它交给 API key 输入模式的粘贴处理函数 → 可能把文本追加到输入框，并请求刷新界面。

调用关系：外层键盘系统检测到粘贴时调用它；真正判断当前是不是 API key 输入状态的活儿交给 handle_api_key_entry_paste。

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

fn set_animations_suppressed(&self, suppressed: bool)

作用：手动设置是否暂时压住动画。这里的动画是终端里的闪光文字效果，不影响登录本身。

数据流：进去的是 suppressed 布尔值 → 它写入内部 Cell（一种可在不可变引用下改的小格子）→ 之后渲染时会按这个值决定是否播放动画。

调用关系：这是给外层或相关流程控制动画用的开关；should_suppress_animations 则会根据登录状态给出自动判断。

fn should_suppress_animations(&self) -> bool

作用：判断当前登录状态下是不是应该停掉动画。正在等浏览器或设备码时，过多动画可能干扰用户复制链接和代码。

数据流：进去的是当前控件 → 它读取 sign_in_state，并检查是否处在浏览器登录或设备码登录状态 → 返回 true 或 false，不修改数据。

调用关系：测试会验证设备码相关状态会返回 true；外层可以据此决定是否压制动画。

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

fn cancel_active_attempt(&self)

作用：取消当前正在进行的 ChatGPT 登录尝试，并把界面退回选择登录方式。它避免用户退出界面后后台还傻等着。

数据流：进去的是当前控件状态 → 它查看是不是浏览器登录或设备码登录；如果有 login_id，就异步通知后台取消；然后状态改回 PickMode，清掉错误并请求刷新 → 没有返回值，但界面和后台尝试都会被清理。

调用关系：用户按取消键时由 handle_key_event 调用；它会把后台取消请求交给 cancel_login_attempt，并用 schedule_frame 让界面立刻更新。

调用图：调用 3 个内部函数（set_error, cancel_login_attempt, schedule_frame）；被 1 处调用（handle_key_event）；外部调用 2 个（clone, spawn）。

fn set_error(&self, message: Option<String>)

作用：设置或清除登录界面上的错误提示。比如 API key 为空、后台返回失败、登录方式被禁用。

数据流：进去的是 Option<String>，有值表示错误文字，没有值表示清空 → 它写入共享的 error 锁里 → 后续渲染函数会读到并显示或隐藏错误。

调用关系：许多流程都会调用它：开始登录前清错，失败时写错，取消时清错；render_pick_mode 和 render_api_key_entry 会通过 error_message 读出来。

调用图：被 9 处调用（cancel_active_attempt, disallow_api_login, handle_api_key_entry_key_event, handle_api_key_entry_paste, on_account_login_completed, save_api_key, start_api_key_entry, start_chatgpt_login, start_device_code_login）。

fn error_message(&self) -> Option<String>

作用：取出当前要显示的错误文字。它给渲染代码用，避免渲染代码直接碰内部锁。

数据流：进去的是当前控件 → 它读取 error 里的 Option<String> 并复制一份 → 返回当前错误，或返回 None。

调用关系：选择登录方式画面和 API key 输入画面会调用它，把错误显示给用户。

调用图：被 2 处调用（render_api_key_entry, render_pick_mode）。

fn is_api_key_entry_active(&self) -> bool

作用：告诉外界当前是不是正在输入 API key。外层可以据此调整光标、提示或快捷键行为。

数据流：进去的是当前控件 → 它读取登录状态，检查是否是 ApiKeyEntry → 返回 true 或 false，不修改状态。

调用关系：它是一个状态查询接口；不主动调用别的业务函数，供外层界面判断当前模式。

fn api_key_entry_has_text(&self) -> bool

作用：告诉外界 API key 输入框里现在有没有内容。比如可以用来决定是否显示清空提示。

数据流：进去的是当前控件 → 它读取 ApiKeyEntry 状态里的 value，并检查是否为空 → 返回 true 或 false，不修改内容。

调用关系：这是给外层 UI 或快捷键逻辑用的轻量查询函数。

fn confirm_binding(&self) -> KeyBinding

作用：取出“确认”这个动作当前显示用的按键。这样画面提示和真实按键配置能保持一致。

数据流：进去的是当前控件 → 它从 onboarding 的确认键列表里取第一个 → 返回一个 KeyBinding。

调用关系：多个渲染函数会用它显示“Press Enter to continue/save”一类提示。

fn cancel_binding(&self) -> KeyBinding

作用：取出“取消”这个动作当前显示用的按键。用户看到的提示和实际可按的键来自同一份配置。

数据流：进去的是当前控件 → 它从取消键列表里取第一个 → 返回一个 KeyBinding。

调用关系：浏览器登录页和 API key 输入页会用它显示如何取消或返回。

fn is_api_login_allowed(&self) -> bool

作用：判断当前工作区是否允许用 API key 登录。有些环境会强制只能用 ChatGPT 登录。

数据流：进去的是当前控件配置 → 它查看 forced_login_method 是否是 Chatgpt → 返回 false 表示 API key 被禁用，否则返回 true。

调用关系：展示选项、处理选择、开始或保存 API key 前都会调用它，防止禁用的登录方式被绕过。

调用图：被 6 处调用（displayed_sign_in_options, handle_sign_in_option, render_pick_mode, save_api_key, selectable_sign_in_options, start_api_key_entry）；外部调用 1 个（matches!）。

fn is_chatgpt_login_allowed(&self) -> bool

作用：判断当前工作区是否允许 ChatGPT 登录。有些环境会强制只能用 API key。

数据流：进去的是当前控件配置 → 它查看 forced_login_method 是否是 Api → 返回 false 表示 ChatGPT 类登录被禁用，否则返回 true。

调用关系：选项列表、选中处理和渲染说明都会用它，让界面和实际规则一致。

调用图：被 4 处调用（displayed_sign_in_options, handle_sign_in_option, render_pick_mode, selectable_sign_in_options）；外部调用 1 个（matches!）。

fn displayed_sign_in_options(&self) -> Vec<SignInOption>

作用：算出界面上要显示哪些登录选项。它关心“给用户看什么”。

数据流：进去的是当前配置 → 它默认放入 ChatGPT 选项，再按允许规则加入设备码和 API key → 返回一个按显示顺序排列的选项列表。

调用关系：render_pick_mode 用它画菜单；select_option_by_index 用它让数字键对应屏幕上的第几个选项。

调用图：调用 2 个内部函数（is_api_login_allowed, is_chatgpt_login_allowed）；被 2 处调用（render_pick_mode, select_option_by_index）；外部调用 1 个（vec!）。

fn selectable_sign_in_options(&self) -> Vec<SignInOption>

作用：算出用户实际能用上下键选到哪些登录选项。它关心“哪些能被选中”。

数据流：进去的是当前配置 → 它只把允许的登录方式放进列表 → 返回可选择的选项列表。

调用关系：move_highlight 调用它来跳过不可选项，避免高亮停在被禁用的登录方式上。

调用图：调用 2 个内部函数（is_api_login_allowed, is_chatgpt_login_allowed）；被 1 处调用（move_highlight）；外部调用 1 个（new）。

fn move_highlight(&mut self, delta: isize)

作用：把菜单高亮项向上或向下移动一格。到头后会绕回另一头，像循环菜单。

数据流：进去的是 delta，通常是 -1 或 1 → 它取出可选择选项，找到当前选项位置，再用循环取模算出下一个位置 → 修改 highlighted_mode，不直接启动登录。

调用关系：handle_key_event 在用户按上下键时调用它；它依赖 selectable_sign_in_options 来尊重登录方式限制。

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

fn select_option_by_index(&mut self, index: usize)

作用：根据数字键选择屏幕上的第几个登录方式。比如按 1、2、3 时会走这里。

数据流：进去的是从 0 开始的 index → 它取当前显示的选项列表，找到对应项 → 如果存在，就交给 handle_sign_in_option 执行选择；不存在则什么都不做。

调用关系：handle_key_event 在用户按快捷数字键时调用它；它随后把真正的登录动作交给 handle_sign_in_option。

调用图：调用 2 个内部函数（displayed_sign_in_options, handle_sign_in_option）；被 1 处调用（handle_key_event）。

fn handle_sign_in_option(&mut self, option: SignInOption)

作用：执行用户选中的登录方式。它是从“菜单选择”走向“开始某种登录流程”的分岔口。

数据流：进去的是 SignInOption → 它检查这种方式是否被允许；ChatGPT 会启动浏览器登录，DeviceCode 会启动设备码登录，ApiKey 会进入输入框或显示禁用错误 → 改变登录状态并可能发起后台请求。

调用关系：确认键和数字选择都会走到这里；它把具体工作分给 start_chatgpt_login、start_device_code_login、start_api_key_entry 或 disallow_api_login。

调用图：调用 6 个内部函数（disallow_api_login, is_api_login_allowed, is_chatgpt_login_allowed, start_api_key_entry, start_chatgpt_login, start_device_code_login）；被 2 处调用（handle_key_event, select_option_by_index）。

fn disallow_api_login(&mut self)

作用：在 API key 登录被禁用时，给用户一个明确提示，并退回可用的登录选项。

数据流：进去的是当前控件 → 它把高亮改回 ChatGPT，写入“API key login is disabled.”错误，把状态设为 PickMode，再请求刷新 → 用户会看到禁用提示。

调用关系：选择、进入、保存 API key 前发现被禁用时都会调用它，确保界面和策略都不允许继续。

调用图：调用 2 个内部函数（set_error, schedule_frame）；被 3 处调用（handle_sign_in_option, save_api_key, start_api_key_entry）。

fn render_pick_mode(&self, area: Rect, buf: &mut Buffer)

作用：画出“请选择登录方式”的页面。用户最先看到的登录菜单就是它生成的。

数据流：进去的是屏幕区域和绘图缓冲区 → 它根据允许规则拼出说明文字、登录选项、高亮样式、按键提示和错误信息 → 把这些文字写进缓冲区显示出来。

调用关系：render_ref 发现当前状态是 PickMode 时调用它；它会询问 displayed_sign_in_options、is_api_login_allowed、is_chatgpt_login_allowed 和 error_message。

调用图：调用 4 个内部函数（displayed_sign_in_options, error_message, is_api_login_allowed, is_chatgpt_login_allowed）；被 1 处调用（render_ref）；外部调用 3 个（from, new, vec!）。

fn render_continue_in_browser(&self, area: Rect, buf: &mut Buffer)

作用：画出“请到浏览器完成登录”的页面。它会显示登录链接和取消提示。

数据流：进去的是屏幕区域和缓冲区 → 它读取当前浏览器登录状态，显示等待文字；如果有 auth_url，就显示 URL，并把 URL 标成可点击超链接；动画开启时还会安排下一帧 → 缓冲区变成浏览器登录提示页。

调用关系：render_ref 在 ChatGptContinueInBrowser 状态下调用它；它用 shimmer_text 做动效，用 mark_url_hyperlink 修复终端长链接点击问题。

调用图：调用 3 个内部函数（shimmer_text, mark_url_hyperlink, schedule_frame_in）；被 1 处调用（render_ref）；外部调用 4 个（from, new, from_millis, vec!）。

fn render_chatgpt_success_message(&self, area: Rect, buf: &mut Buffer)

作用：画出 ChatGPT 登录成功后的安全提醒页。它不是简单说成功，还提醒用户 Codex 可能运行命令、写代码，要自己审查。

数据流：进去的是屏幕区域和缓冲区 → 它组织成功标记、使用说明、安全文档链接、训练数据偏好链接和继续按键提示 → 写入缓冲区。

调用关系：render_ref 在 ChatGptSuccessMessage 状态调用它；用户再按确认时，handle_key_event 会把状态推进到 ChatGptSuccess。

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

fn render_chatgpt_success(&self, area: Rect, buf: &mut Buffer)

作用：画出简短的 ChatGPT 已登录状态。这个状态表示认证步骤已经可以算完成。

数据流：进去的是屏幕区域和缓冲区 → 它写入一行绿色成功提示 → 缓冲区显示“已用 ChatGPT 账号登录”。

调用关系：render_ref 在 ChatGptSuccess 状态调用它；get_step_state 会把这个状态报告为 Complete。

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

fn render_api_key_configured(&self, area: Rect, buf: &mut Buffer)

作用：画出 API key 已保存成功的页面。用户能知道之后会按 API key 的用量计费方式工作。

数据流：进去的是屏幕区域和缓冲区 → 它写入绿色成功提示和简短说明 → 缓冲区显示 API key 已配置。

调用关系：render_ref 在 ApiKeyConfigured 状态调用它；get_step_state 会把这个状态报告为 Complete。

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

fn render_api_key_entry(&self, area: Rect, buf: &mut Buffer, state: &ApiKeyInputState)

作用：画出 API key 输入页面，包括说明、输入框、保存/返回提示和错误信息。

数据流：进去的是屏幕区域、缓冲区和当前输入状态 → 它把区域分成说明、输入框、底部提示三块；如果从环境变量预填了 key，会额外说明；输入框为空时显示占位文字，否则显示当前内容 → 写入完整输入界面。

调用关系：render_ref 在 ApiKeyEntry 状态调用它；它用 error_message 显示校验或保存失败原因。

调用图：调用 1 个内部函数（error_message）；被 1 处调用（render_ref）；外部调用 8 个（default, Length, Min, vertical, from, new, default, vec!）。

fn handle_api_key_entry_key_event(&mut self, key_event: &KeyEvent) -> bool

作用：在 API key 输入模式下处理键盘：输入字符、退格、保存、取消。它会拦住这些键，避免被菜单逻辑误处理。

数据流：进去的是键盘事件 → 它先确认当前确实是 ApiKeyEntry；取消会回菜单，确认会校验并准备保存，退格和普通字符会修改输入内容；需要保存时调用 save_api_key → 返回 true 表示事件已处理，false 表示不是输入模式。

调用关系：handle_key_event 最先调用它；如果它处理了事件，后面的菜单上下移动和确认逻辑就不会再运行。

调用图：调用 3 个内部函数（save_api_key, set_error, schedule_frame）；被 1 处调用（handle_key_event）。

fn handle_api_key_entry_paste(&mut self, pasted: String) -> bool

作用：在 API key 输入模式下处理粘贴。这样用户可以直接粘贴整串 key，不必一个字符一个字符输入。

数据流：进去的是粘贴文本 → 它去掉前后空白；如果当前是 API key 输入模式，就替换环境变量预填内容或追加到已有内容，清掉错误并请求刷新 → 返回是否真的处理了这次粘贴。

调用关系：handle_paste 会把所有粘贴交给它；它只在 ApiKeyEntry 状态工作。

调用图：调用 2 个内部函数（set_error, schedule_frame）；被 1 处调用（handle_paste）。

fn start_api_key_entry(&mut self)

作用：进入 API key 输入流程。它还会尝试读取 OPENAI_API_KEY 环境变量来帮用户预填。

数据流：进去的是当前控件 → 它先检查 API key 登录是否允许；允许时清错，读取环境变量，如果已经在输入状态且为空就填入，否则创建新的 ApiKeyEntry 状态 → 请求刷新界面。

调用关系：用户选择 API key 登录时由 handle_sign_in_option 调用；如果被策略禁用，会转去 disallow_api_login。

调用图：调用 4 个内部函数（disallow_api_login, is_api_login_allowed, set_error, schedule_frame）；被 1 处调用（handle_sign_in_option）；外部调用 2 个（read_openai_api_key_from_env, ApiKeyEntry）。

fn save_api_key(&mut self, api_key: String)

作用：把用户输入的 API key 发给后台保存。保存成功后，这个认证步骤就完成了。

数据流：进去的是 API key 字符串 → 它检查是否允许 API 登录，清错，然后异步向后台发送 LoginAccount::ApiKey 请求；成功则状态变 ApiKeyConfigured，失败则恢复输入状态并显示错误 → 会请求界面刷新。

调用关系：handle_api_key_entry_key_event 在用户按确认且内容不空时调用它；它用 onboarding_request_id 给后台请求编号，并把网络等待放进 tokio 任务。

调用图：调用 5 个内部函数（disallow_api_login, is_api_login_allowed, set_error, onboarding_request_id, schedule_frame）；被 1 处调用（handle_api_key_entry_key_event）；外部调用 5 个（clone, format!, spawn, ApiKeyEntry, clone）。

fn handle_existing_chatgpt_login(&mut self) -> bool

作用：检查用户是不是其实已经有 ChatGPT 登录了。如果已经登录，就不重复打开新登录流程。

数据流：进去的是当前控件 → 它查看 login_status 是否表示已有 ChatGPT 类账号 → 如果是，就把状态设为 ChatGptSuccess、请求刷新并返回 true；否则返回 false。

调用关系：start_chatgpt_login 和 start_device_code_login 开始前都会先调用它，避免多余登录。

调用图：调用 1 个内部函数（schedule_frame）；被 2 处调用（start_chatgpt_login, start_device_code_login）；外部调用 1 个（matches!）。

fn start_chatgpt_login(&mut self)

作用：启动标准 ChatGPT 登录流程，通常会让用户去浏览器完成认证。

数据流：进去的是当前控件 → 它先检查是否已经登录；没有的话清错，异步向后台申请 ChatGPT 登录；成功拿到 login_id 和 auth_url 后尝试打开浏览器，并把状态改成等待浏览器完成；失败则回菜单并显示错误 → 界面会刷新。

调用关系：handle_sign_in_option 在用户选择 ChatGPT 时调用它；它用 maybe_open_auth_url_in_browser 尝试开浏览器，用 onboarding_request_id 标记后台请求。

调用图：调用 4 个内部函数（handle_existing_chatgpt_login, set_error, maybe_open_auth_url_in_browser, onboarding_request_id）；被 1 处调用（handle_sign_in_option）；外部调用 5 个（clone, format!, spawn, ChatGptContinueInBrowser, clone）。

fn start_device_code_login(&mut self)

作用：启动设备码登录流程，适合远程机器、无浏览器环境，用户可以在另一台设备上输入一次性代码。

数据流：进去的是当前控件 → 它先检查是否已经有 ChatGPT 登录；没有的话清错，然后把流程交给 headless_chatgpt_login 子模块 → 后续状态会进入设备码申请或展示。

调用关系：handle_sign_in_option 在用户选择 Device Code 时调用它；具体申请设备码和渲染细节不在本文件，而在 headless_chatgpt_login。

调用图：调用 3 个内部函数（handle_existing_chatgpt_login, set_error, start_headless_chatgpt_login）；被 1 处调用（handle_sign_in_option）。

fn on_account_login_completed(
        &mut self,
        notification: AccountLoginCompletedNotification,
    )

作用：处理后台发来的“某次登录完成了”通知。它只响应当前这次登录，避免别的旧登录通知误改界面。

数据流：进去的是完成通知，里面可能有 login_id、成功标记和错误 → 它先用 login_id 对比当前浏览器登录或设备码登录；匹配后，成功则进入成功提醒页，失败则回菜单并显示错误 → 请求刷新界面。

调用关系：后台账户登录完成事件到达时由外层调用；它依赖当前状态里的 login_id 来确认通知属于本控件正在等待的那次登录。

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

fn on_account_updated(&mut self, notification: AccountUpdatedNotification)

作用：处理后台发来的账户状态更新。它让控件知道当前到底是已登录还是未登录。

数据流：进去的是 AccountUpdatedNotification → 它取出通知里的 auth_mode；有则转成 LoginStatus::AuthMode，没有则设为 NotAuthenticated → 更新控件里的 login_status。

调用关系：外层收到账号变更通知时会调用它；之后 handle_existing_chatgpt_login 会根据这个状态决定是否跳过新登录。

fn get_step_state(&self) -> StepState

作用：告诉外层引导流程：认证这一步是还没完，还是已经完成。

数据流：进去的是当前控件 → 它读取 sign_in_state；选择中、输入中、等待登录、成功提醒页都算 InProgress，真正 ChatGPT 成功或 API key 配好才算 Complete → 返回 StepState。

调用关系：外层 onboarding screen 通过 StepStateProvider 调用它，用来决定能不能进入下一步。

fn render_ref(&self, area: Rect, buf: &mut Buffer)

作用：认证控件的总渲染入口。它根据当前状态，把画面分派给对应的具体渲染函数。

数据流：进去的是屏幕区域和缓冲区 → 它读取 sign_in_state，然后选择画菜单、浏览器等待、设备码、成功提醒、成功摘要、API key 输入或 API key 成功页 → 缓冲区被写成当前该显示的页面。

调用关系：ratatui 终端 UI 框架绘制这个控件时调用它；设备码页面会转给 headless_chatgpt_login::render_device_code_login。

调用图：调用 7 个内部函数（render_api_key_configured, render_api_key_entry, render_chatgpt_success, render_chatgpt_success_message, render_continue_in_browser, render_pick_mode, render_device_code_login）。

fn maybe_open_auth_url_in_browser(request_handle: &AppServerRequestHandle, url: &str)

作用：在合适的情况下自动打开浏览器里的登录链接。它只对进程内后台句柄这样做，避免在不合适的连接方式下乱开浏览器。

数据流：进去的是后台请求句柄和 URL → 它先判断句柄是不是 InProcess；不是就直接返回；是的话调用系统浏览器打开 URL，失败只写警告日志 → 没有返回值。

调用关系：start_chatgpt_login 拿到 auth_url 后调用它；如果打不开，界面仍然会显示链接让用户手动打开。

调用图：被 1 处调用（start_chatgpt_login）；外部调用 3 个（matches!, warn!, open）。

async fn widget_forced_chatgpt() -> (AuthModeWidget, TempDir)

作用：搭一个测试用的 AuthModeWidget，并把配置设成“强制 ChatGPT 登录”。这样测试可以验证 API key 被禁用时的行为。

数据流：进去不需要参数 → 它创建临时目录、测试配置、进程内应用服务器客户端和 AuthModeWidget → 返回控件和临时目录，供异步测试使用。

调用关系：本文件多个测试都先调用它，获得一套隔离的登录控件和后台环境。

调用图：调用 5 个内部函数（start, default, default_for_tests, new, test_dummy）；外部调用 12 个（new, default, new, new, new, InProcess, default, cloud_config_bundle_loader_for_storage, default, from_value (+2 more)）。

async fn api_key_flow_disabled_when_chatgpt_forced()

作用：测试当工作区强制 ChatGPT 登录时，进入 API key 输入流程会被挡住。

数据流：进去是测试运行环境 → 它创建强制 ChatGPT 的控件，调用 start_api_key_entry → 断言错误提示是 API key 被禁用，状态仍然回到 PickMode。

调用关系：它验证 start_api_key_entry 会走 disallow_api_login，而不是偷偷允许 API key。

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

async fn saving_api_key_is_blocked_when_chatgpt_forced()

作用：测试即使直接调用保存 API key，在强制 ChatGPT 的配置下也不能保存。

数据流：进去是测试运行环境 → 它创建控件，调用 save_api_key("sk-test") → 断言显示禁用错误、状态是 PickMode、登录状态仍未认证。

调用关系：它防止有人绕过输入界面直接调用保存函数；验证 save_api_key 自己也会检查策略。

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

async fn existing_non_oauth_chatgpt_login_counts_as_signed_in()

作用：测试已有的非 OAuth ChatGPT 登录方式也算“已经登录”。OAuth 可以理解成网页授权，这里确认其他令牌方式也被认可。

数据流：进去是测试运行环境 → 它分别设置两种已有 ChatGPT 认证状态，调用 handle_existing_chatgpt_login → 断言返回 true，状态变成 ChatGptSuccess。

调用关系：它覆盖 start_chatgpt_login 和 start_device_code_login 依赖的提前跳过逻辑。

调用图：外部调用 4 个（assert!, assert_eq!, AuthMode, widget_forced_chatgpt）。

async fn cancel_active_attempt_resets_browser_login_state()

作用：测试取消浏览器登录时，界面会清掉错误并回到选择登录方式。

数据流：进去是测试运行环境 → 它把控件放进 ChatGptContinueInBrowser 状态并设置错误，再调用 cancel_active_attempt → 断言错误清空，状态回 PickMode。

调用关系：它验证用户按取消键时 cancel_active_attempt 对浏览器登录状态的本地清理。

调用图：外部调用 4 个（assert!, assert_eq!, ChatGptContinueInBrowser, widget_forced_chatgpt）。

async fn cancel_active_attempt_notifies_device_code_login()

作用：测试取消设备码登录时，控件同样会退回菜单并清错。

数据流：进去是测试运行环境 → 它创建 ready 的设备码状态，设置错误，调用 cancel_active_attempt → 断言错误清空，状态回 PickMode。

调用关系：它覆盖 cancel_active_attempt 对 ChatGptDeviceCode 状态的处理，并间接使用 ContinueWithDeviceCodeState::ready。

调用图：调用 1 个内部函数（ready）；外部调用 4 个（assert!, assert_eq!, ChatGptDeviceCode, widget_forced_chatgpt）。

fn collect_osc8_chars(buf: &Buffer, area: Rect, url: &str) -> String

作用：测试辅助函数：从缓冲区里找出被 OSC 8 超链接包住的字符。它帮助测试确认哪些字真的变成可点击链接了。

数据流：进去的是缓冲区、区域和 URL → 它逐格扫描，找形如“打开超链接 + 字符 + 关闭超链接”的内容 → 返回这些内部字符拼起来的字符串。

调用关系：链接相关测试会调用它，对 mark_url_hyperlink 和浏览器登录页面的渲染结果做断言。

调用图：外部调用 6 个（bottom, left, right, top, new, format!）。

fn continue_in_browser_renders_osc8_hyperlink()

作用：测试浏览器登录页面里的长 URL 即使换行，也会完整带上 OSC 8 超链接标记。

数据流：进去是测试运行环境 → 它创建控件，设置浏览器登录状态，在很窄的缓冲区里渲染，让 URL 换行 → 用 collect_osc8_chars 取回被标记字符，并断言等于完整 URL。

调用关系：它验证 render_continue_in_browser 会调用 mark_url_hyperlink，解决终端自动识别长链接不可靠的问题。

调用图：外部调用 7 个（empty, new, assert_eq!, new, ChatGptContinueInBrowser, collect_osc8_chars, widget_forced_chatgpt）。

fn auth_widget_suppresses_animations_when_device_code_is_visible()

作用：测试设备码已经显示时，控件认为应该压制动画。

数据流：进去是测试运行环境 → 它把控件设为 ready 的设备码状态 → 调用 should_suppress_animations，并断言结果为 true。

调用关系：它验证设备码页面不会被动画干扰，尤其是用户需要复制网址和验证码时。

调用图：调用 1 个内部函数（ready）；外部调用 4 个（assert_eq!, new, ChatGptDeviceCode, widget_forced_chatgpt）。

fn auth_widget_suppresses_animations_while_requesting_device_code()

作用：测试设备码还在申请中时，也应该压制动画。

数据流：进去是测试运行环境 → 它把控件设为 pending 的设备码状态 → 调用 should_suppress_animations，并断言为 true。

调用关系：它覆盖 ContinueWithDeviceCodeState::pending 对动画判断的影响。

调用图：调用 1 个内部函数（pending）；外部调用 4 个（assert_eq!, new, ChatGptDeviceCode, widget_forced_chatgpt）。

async fn device_code_login_completion_advances_to_success_message()

作用：测试设备码登录成功通知到达后，界面会进入 ChatGPT 成功提醒页。

数据流：进去是测试运行环境 → 它把控件设为某个 login_id 的设备码登录状态，再发送同一个 login_id 的成功通知 → 断言状态变成 ChatGptSuccessMessage。

调用关系：它验证 on_account_login_completed 会正确匹配设备码登录，并推动成功流程。

调用图：调用 1 个内部函数（ready）；外部调用 3 个（assert!, ChatGptDeviceCode, widget_forced_chatgpt）。

fn mark_url_hyperlink_wraps_cyan_underlined_cells()

作用：测试只有青色并带下划线的字符会被标成 URL 超链接，普通字符不会被碰。

数据流：进去是测试运行环境 → 它手工在缓冲区写入几个青色下划线字符和一个普通 X，调用 mark_url_hyperlink → 断言链接字符被收集到，普通 X 保持原样。

调用关系：它直接验证本文件的 mark_url_hyperlink 包装函数对终端缓冲区的效果。

调用图：调用 1 个内部函数（mark_url_hyperlink）；外部调用 4 个（empty, new, assert_eq!, collect_osc8_chars）。

fn mark_url_hyperlink_sanitizes_control_chars()

作用：测试 URL 里如果混入终端控制字符，会被清理掉，不能破坏 OSC 8 超链接格式。

数据流：进去是测试运行环境 → 它准备一个带 ESC 和 BEL 控制字符的恶意 URL，调用 mark_url_hyperlink → 断言结果包含清理后的 URL，且不包含原始危险控制序列。

调用关系：它验证链接标记工具的安全性，防止登录链接文字被用来注入终端控制序列。

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

fn render_ref(&self, area: Rect, buf: &mut Buffer)

作用：把“是否信任这个目录”的问题画到终端屏幕上。用户看到的说明文字、警告、两个选项、错误提示和按键提示，都是这里拼出来的。

数据流：进去的是可绘制区域和屏幕缓冲区，同时读取这个控件里的当前目录、信任目标、当前高亮选项、错误信息等状态；它把这些信息组织成一列文字和段落，必要时加上颜色、缩进和自动换行；最后把结果写进终端缓冲区，让界面显示出来。

调用关系：它是这个控件的“画面输出”环节，由终端 UI 框架在需要刷新屏幕时调用。它会借助 ColumnRenderable 这样的排版工具、selection_option_row 这样的选项行工具，以及 Insets 这样的缩进设置，把状态变成用户能看的界面。

调用图：调用 3 个内部函数（tlbr, new, selection_option_row）；外部调用 4 个（from, new, format!, vec!）。

fn handle_key_event(&mut self, key_event: KeyEvent)

作用：处理用户按键。它决定按上、下、确认、取消、退出等键时，界面应该只是移动光标，还是正式选择信任或退出。

数据流：进去的是一次键盘事件；它先忽略“按键松开”事件，避免一次按键被处理两遍；然后根据按键类型修改 highlighted、selection 或 should_quit。结果是控件状态发生变化，比如高亮到“退出”，或者记录用户选择“信任”。

调用关系：它是这个控件的“输入入口”。 onboarding 页面收到键盘事件后会交给它；当用户选择继续时，它把活交给 TrustDirectoryWidget::handle_trust；当用户选择退出、取消或按退出键时，它把活交给 TrustDirectoryWidget::handle_quit。

调用图：调用 2 个内部函数（handle_quit, handle_trust）。

fn get_step_state(&self) -> StepState

作用：告诉外层 onboarding 流程：这一步完成了没有。只要用户已经选了信任，或者已经决定退出，这一步就算结束。

数据流：进去的是当前控件状态；它查看 selection 有没有值，或者 should_quit 是否为真；出来的是 StepState::Complete 或 StepState::InProgress，也就是“完成”或“还在进行中”。

调用关系：它给 onboarding 流程做进度判断。外层步骤管理器会用它决定是否可以离开这个信任确认页面，进入下一步，或者开始退出流程。

fn handle_trust(&mut self)

作用：执行“用户选择信任目录”的状态更新。它不直接写配置，只是在这个界面里记录用户已经选择继续。

数据流：进去的是当前控件的可修改状态；它把高亮项设为 Trust，清掉之前的错误信息，并把 selection 设成 Trust；出来的是一个已经标记为“用户同意信任”的控件状态。

调用关系：它只由 TrustDirectoryWidget::handle_key_event 在用户按下对应快捷键或确认“继续”时调用。之后外层流程会看到 selection 已经有值，并通过 TrustDirectoryWidget::get_step_state 判断这一步完成。

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

fn handle_quit(&mut self)

作用：执行“用户不信任并退出”的状态更新。它把界面状态改成退出意图，让外层程序知道不要继续往下走。

数据流：进去的是当前控件的可修改状态；它把高亮项设为 Quit，并把 should_quit 设成 true；出来的是一个明确表示“用户要退出”的控件状态。

调用关系：它由 TrustDirectoryWidget::handle_key_event 在用户选择“No, quit”、按退出键或取消键时调用。之后外层流程可以通过 TrustDirectoryWidget::should_quit 或 TrustDirectoryWidget::get_step_state 发现该结束了。

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

fn should_quit(&self) -> bool

作用：给外层代码一个简单答案：用户是不是已经要求退出。它是读取退出标记的小窗口。

数据流：进去的是当前控件状态；它读取 should_quit 这个布尔值；出来的是 true 或 false，不改动任何东西。

调用关系：外层 onboarding 或应用主流程在决定是否关闭程序时会用它。它不调用别的函数，只负责把内部退出状态安全地暴露出来。

fn widget(error: Option<String>) -> TrustDirectoryWidget

作用：给测试快速造一个 TrustDirectoryWidget。这样每个测试不用重复写一大段初始化代码。

数据流：进去的是一个可选错误信息；它填好固定的当前目录、信任目标、默认高亮项、退出标记等字段；出来的是一个可用于测试的控件实例。

调用关系：它是测试里的小帮手，被渲染快照测试调用。测试用它造出“正常无错误”和“带错误提示”两种界面状态。

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

fn release_event_does_not_change_selection()

作用：验证松开按键不会被当成真正操作。这样可以避免用户按一次回车，程序因为同时收到按下和松开而误触发两次。

数据流：进去的是一个初始高亮在 Quit 的测试控件；测试先送入一个回车的 Release 事件，确认 selection 仍然为空；再送入真正的回车按下事件，确认 should_quit 变成 true。

调用关系：它直接测试 TrustDirectoryWidget::handle_key_event 的一个重要防误触行为。这个测试保证键盘事件处理只响应有效的按下动作，而不是响应松开动作。

调用图：外部调用 4 个（new, from, assert!, assert_eq!）。

fn renders_snapshot_for_git_repo()

作用：检查正常情况下的信任目录界面长什么样。它用快照测试，也就是把终端画面和之前保存的标准画面做对比。

数据流：进去的是一个无错误信息的测试控件和一个固定大小的虚拟终端；测试让控件渲染到终端里；出来的是一次快照断言，通过就说明画面没有意外变化。

调用关系：它调用 tests::widget 生成控件，再间接测试 TrustDirectoryWidget::render_ref 的输出。这个测试保护的是用户看到的文字、排版和选项显示。

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

fn renders_snapshot_for_trust_error()

作用：检查出现信任失败错误时，界面是否正确显示错误信息。这样可以保证用户不会只看到界面卡住，却不知道哪里出了问题。

数据流：进去的是一段模拟的错误文字；测试把它放进测试控件，再渲染到固定大小的虚拟终端；出来的是快照对比结果，用来确认错误提示的颜色、换行和位置没有乱掉。

调用关系：它也通过 tests::widget 生成控件，并覆盖 TrustDirectoryWidget::render_ref 的错误分支。它和正常渲染测试一起，保证这个 onboarding 页面在成功和失败场景下都可读。

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

fn label(self) -> &'static str

作用：把一个操作按钮变成用户能看懂的文字，比如“导入选中的”或“取消”。这样界面不用到处硬写按钮文案。

数据流：进去的是一个按钮选项 → 它根据选项种类挑一句固定英文标签 → 出来的是一段可直接显示在终端里的文字，不改动任何状态。

调用关系：这是动作菜单的基础小零件，渲染界面时会用它把内部选项显示给用户看。它不驱动流程，只负责把选项翻译成标签。

async fn run_external_agent_config_migration_prompt(
    tui: &mut Tui,
    items: &[ExternalAgentConfigMigrationItem],
    selected_items: &[ExternalAgentConfigMigrationItem],
    error: Option<&str>

作用：启动并运行整个导入确认界面，直到用户选择继续导入或取消。调用方只要把候选导入项交进来，就能拿到最后结果。

数据流：进去的是终端界面对象、所有可导入项目、默认选中的项目，以及可选错误信息 → 它创建屏幕状态，先画一次界面，然后不断读取键盘、重绘、窗口变化等事件 → 出来的是用户最终选择：继续并带上选中的项目，或跳过。

调用关系：它由 handle_external_agent_config_migration_prompt 调用，是这个提示框的外层运行循环。它把具体状态变化交给 ExternalAgentConfigMigrationScreen::handle_key，把绘制交给 Tui 的 draw 和 render 模块。

调用图：调用 1 个内部函数（new）；被 1 处调用（handle_external_agent_config_migration_prompt）；外部调用 4 个（draw, event_stream, frame_requester, pin!）。

fn proceed_enabled(&self) -> bool

作用：判断现在能不能点“导入选中的”。如果一个项目都没选，就不应该让用户直接继续。

数据流：进去的是当前屏幕状态 → 它数一数已勾选项目数量 → 返回 true 或 false，不改动界面。

调用关系：available_actions 会用它决定动作菜单里是否出现 Proceed。它依赖 selected_count 来得到数量。

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

fn first_available_action(&self) -> ActionMenuOption

作用：找出当前菜单里第一个可用按钮，用来给光标一个安全的位置。

数据流：进去的是当前界面状态 → 它生成当前可用按钮列表并取第一个 → 返回一个按钮；如果列表意外为空，就退回到 Back。

调用关系：normalize_highlighted_action、move_down 和 back_to_summary 会用它，避免光标停在一个当前不存在的按钮上。

调用图：调用 1 个内部函数（available_actions）；被 3 处调用（back_to_summary, move_down, normalize_highlighted_action）。

fn last_available_action(&self) -> ActionMenuOption

作用：找出当前菜单里最后一个可用按钮，方便用户从列表顶部往上时绕到末尾。

数据流：进去的是当前界面状态 → 它查看当前可用按钮列表并取最后一个 → 返回一个按钮；如果没有按钮，就用 Back 兜底。

调用关系：move_up 会用它处理上下循环导航，特别是从项目列表切到动作按钮时。

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

fn previous_available_action(&self, action: ActionMenuOption) -> Option<ActionMenuOption>

作用：在当前可用按钮列表里，找到某个按钮前面的按钮。它让菜单可以按上键移动。

数据流：进去的是当前状态和当前按钮 → 它生成可用按钮列表，找到当前按钮的位置，再取前一个 → 返回前一个按钮，找不到就返回空。

调用关系：move_up 调用它来移动动作区的高亮。如果没有前一个，move_up 会自己决定是否循环或切换焦点。

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

fn next_available_action(&self, action: ActionMenuOption) -> Option<ActionMenuOption>

作用：在当前可用按钮列表里，找到某个按钮后面的按钮。它让菜单可以按下键移动。

数据流：进去的是当前状态和当前按钮 → 它生成可用按钮列表，定位当前按钮，再取后一个 → 返回后一个按钮，找不到就返回空。

调用关系：move_down 调用它来移动动作区的高亮。如果没有后一个，move_down 会负责绕回或切到项目列表。

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

fn available_actions(&self) -> Vec<ActionMenuOption>

作用：根据当前页面和选择情况，算出现在应该显示哪些按钮。比如没有选中项目时，就不显示“导入选中的”。

数据流：进去的是当前屏幕状态 → 它看当前是汇总页还是自定义页，并检查是否有已选项目 → 返回一个按钮列表，不改状态。

调用关系：这是按钮导航的中心依据。first_available_action、last_available_action、previous_available_action、next_available_action、normalize_highlighted_action 和 select_numbered_action 都依赖它。

调用图：调用 1 个内部函数（proceed_enabled）；被 6 处调用（first_available_action, last_available_action, next_available_action, normalize_highlighted_action, previous_available_action, select_numbered_action）；外部调用 2 个（new, vec!）。

fn normalize_highlighted_action(&mut self)

作用：修正当前高亮按钮，防止它指向一个已经不可用的按钮。比如用户取消所有勾选后，“导入选中的”就不能再高亮。

数据流：进去的是可变的屏幕状态 → 它检查当前高亮按钮是否还在可用按钮列表里 → 如果不在，就把高亮改成第一个可用按钮。

调用关系：set_all_enabled 和 toggle_selected_item 改变勾选状态后会调用它，保证后续按回车不会触发一个不存在的动作。

调用图：调用 2 个内部函数（available_actions, first_available_action）；被 2 处调用（set_all_enabled, toggle_selected_item）。

fn display_description(item: &ExternalAgentConfigMigrationItem) -> String

作用：把服务端给的导入说明改成更适合用户阅读的文字。它会把“Migrate”改成“Import”，还会把路径显示得更友好。

数据流：进去的是一个导入项目 → 它读取项目描述、当前项目目录和插件详情，必要时重写路径和补充插件数量 → 返回一段用于界面展示的说明文字，不修改项目。

调用关系：自定义列表构建时会用它生成每一项下面的说明。它还借助 display_path_for 把路径变成相对当前项目更好懂的形式。

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

fn new(
        request_frame: FrameRequester,
        items: &[ExternalAgentConfigMigrationItem],
        selected_items: &[ExternalAgentConfigMigrationItem],
        error: Option<String>,
    ) ->

作用：创建一个新的导入确认屏幕，并把初始选中项、分组、焦点和默认按钮都准备好。

数据流：进去的是重绘请求器、所有候选项目、默认选中的项目、错误信息 → 它把项目包装成带勾选状态的列表，并按模型分组 → 出来是一个可交互的屏幕对象。

调用关系：run_external_agent_config_migration_prompt 用它开始一次真实提示；测试也大量用它搭出初始界面。它调用 external_agent_config_migration_groups 来生成汇总页分组。

调用图：调用 1 个内部函数（external_agent_config_migration_groups）；被 12 处调用（run_external_agent_config_migration_prompt, control_exit_shortcuts_cancel_prompt, customize_action_snapshot, customize_snapshot, empty_selection_enter_opens_customize_instead_of_proceeding, escape_skips_prompt, numeric_shortcuts_choose_actions, numeric_shortcuts_follow_visible_actions_when_proceed_is_disabled, proceed_returns_selected_items, prompt_snapshot (+2 more)）；外部调用 1 个（iter）。

fn plugin_detail_lines(plugin_groups: &[PluginsMigration]) -> Vec<Line<'static>>

作用：把插件导入详情压缩成几行短文字，避免插件太多把界面刷满。

数据流：进去的是插件市场和插件名列表 → 它最多展示前三个市场、每个市场最多两个插件，并用“还有更多”提示隐藏数量 → 返回多行可显示文本。

调用关系：build_customize_render_lines 在显示插件类导入项时调用它。它只负责把详细数据变成简短说明，不参与选择逻辑。

调用图：外部调用 4 个（from, iter, len, format!）。

fn is_done(&self) -> bool

作用：告诉外层循环这个提示框是不是已经结束。结束后就不用继续等键盘事件了。

数据流：进去的是屏幕状态 → 它读取 done 标记 → 返回 true 或 false，不改状态。

调用关系：run_external_agent_config_migration_prompt 在事件循环里反复检查它，直到用户继续或取消。

fn outcome(&self) -> ExternalAgentConfigMigrationOutcome

作用：取出用户最后的选择结果。结果可能是继续导入哪些项目，也可能是跳过。

数据流：进去的是屏幕状态 → 它复制当前 outcome → 返回给调用方，不改变原状态。

调用关系：run_external_agent_config_migration_prompt 在界面结束后调用它，把最终决定交回上层流程。

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

fn finish_with(&mut self, outcome: ExternalAgentConfigMigrationOutcome)

作用：用某个结果结束提示框，并安排再画一帧。它是所有“完成”动作的统一出口。

数据流：进去的是可变屏幕状态和最终结果 → 它保存结果，把 done 设为 true，并请求界面刷新 → 之后外层循环会停止。

调用关系：proceed 和 skip 都调用它。这样继续和取消虽然结果不同，但结束界面的收尾动作保持一致。

调用图：调用 1 个内部函数（schedule_frame）；被 2 处调用（proceed, skip）。

fn proceed(&mut self)

作用：确认继续导入当前已勾选的项目。用户按“导入选中的”时会走这里。

数据流：进去的是当前屏幕状态 → 它收集所有已勾选项目 → 把结果设置为 Proceed，并结束界面。

调用关系：confirm_selection 在当前高亮为 Proceed 时调用它。它内部先用 selected_items，再交给 finish_with 收尾。

调用图：调用 2 个内部函数（finish_with, selected_items）；被 1 处调用（confirm_selection）；外部调用 1 个（Proceed）。

fn skip(&mut self)

作用：取消这次导入提示。用户按取消、Esc、Ctrl-C 或 Ctrl-D 时都会走这里。

数据流：进去的是当前屏幕状态 → 它把最终结果设为 Skip → 标记界面结束并请求刷新。

调用关系：confirm_selection 和 handle_key 都可能调用它。它通过 finish_with 统一结束流程。

调用图：调用 1 个内部函数（finish_with）；被 2 处调用（confirm_selection, handle_key）。

fn selected_items(&self) -> Vec<ExternalAgentConfigMigrationItem>

作用：拿到当前所有被勾选的导入项目。继续导入时需要这份清单。

数据流：进去的是屏幕里的项目列表 → 它过滤出 enabled 为真的项目并复制原始项目数据 → 返回新的项目数组，不改状态。

调用关系：proceed 调用它来生成最终 Proceed 结果。

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

fn selected_count(&self) -> usize

作用：数一数现在选中了几个项目。它用于判断是否允许继续。

数据流：进去的是项目列表 → 它统计 enabled 为真的项目数量 → 返回数字，不改状态。

调用关系：proceed_enabled 调用它，然后 available_actions 再根据结果决定是否显示继续按钮。

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

fn group_selection_marker(
        &self,
        group: &ExternalAgentConfigMigrationGroupModel,
    ) -> &'static str

作用：给汇总页的每个分组生成勾选标记。全选显示 x，没选显示空，部分选显示横杠。

数据流：进去的是一个分组和当前项目状态 → 它检查这个分组里有多少项目已勾选 → 返回一个字符标记，不改状态。

调用关系：build_summary_render_lines 用它把内部勾选情况变成用户能看懂的方括号标记。

fn set_all_enabled(&mut self, enabled: bool)

作用：一键全选或全不选所有导入项。自定义页里按 a 或 n 会用到。

数据流：进去的是目标勾选状态 true 或 false → 它把每个项目都改成这个状态，清掉错误提示，修正高亮按钮，并请求重绘 → 界面马上反映新的选择。

调用关系：handle_key 根据用户按键调用它。它会调用 normalize_highlighted_action，防止全不选后继续按钮还被选中。

调用图：调用 2 个内部函数（normalize_highlighted_action, schedule_frame）；被 1 处调用（handle_key）。

fn toggle_selected_item(&mut self)

作用：切换当前光标所在项目的勾选状态。用户在自定义页按空格或回车选项目时会用到。

数据流：进去的是当前屏幕状态 → 它先确认正在自定义页且焦点在项目上，再找到当前项目并反转勾选 → 清掉错误、修正按钮高亮、请求重绘。

调用关系：confirm_selection 和 handle_key 都会调用它。它是逐项勾选的核心动作。

调用图：调用 2 个内部函数（normalize_highlighted_action, schedule_frame）；被 2 处调用（confirm_selection, handle_key）。

fn customize(&mut self)

作用：从汇总页进入逐项选择页。用户想自己挑哪些导入时会用它。

数据流：进去的是当前屏幕状态 → 它把页面切到 Customize，光标放到第一个项目，滚动归零，按钮改成 Back → 请求界面重绘。

调用关系：confirm_selection 在用户选择 Customize 时调用它；handle_key 在汇总页按 c 时也调用它。

调用图：调用 1 个内部函数（schedule_frame）；被 2 处调用（confirm_selection, handle_key）。

fn back_to_summary(&mut self)

作用：从自定义页回到汇总页。用户检查完选择后，用它回到最终确认界面。

数据流：进去的是当前屏幕状态 → 它切回 Summary，重置选择位置和滚动，把焦点放回动作按钮 → 请求重绘。

调用关系：confirm_selection 在 Back 按钮触发时调用它；handle_key 在自定义页按 b 或 Esc 时也调用它。

调用图：调用 2 个内部函数（first_available_action, schedule_frame）；被 2 处调用（confirm_selection, handle_key）。

fn move_up(&mut self)

作用：处理用户按上键或 k。它让光标在项目列表和按钮之间向上移动。

数据流：进去的是当前屏幕状态 → 它根据当前页面和焦点决定高亮上一个按钮、上一个项目，或在边界处切换区域 → 调整滚动位置并请求重绘。

调用关系：handle_key 调用它响应键盘。它会用 previous_available_action、last_available_action 和 ensure_selected_item_visible 保证导航自然且可见。

调用图：调用 4 个内部函数（ensure_selected_item_visible, last_available_action, previous_available_action, schedule_frame）；被 1 处调用（handle_key）。

fn move_down(&mut self)

作用：处理用户按下键或 j。它让光标在项目列表和按钮之间向下移动。

数据流：进去的是当前屏幕状态 → 它移动到下一个按钮或项目，到了边界就切换区域或绕回 → 调整滚动位置并请求重绘。

调用关系：handle_key 调用它响应键盘。它会用 next_available_action、first_available_action 和 ensure_selected_item_visible。

调用图：调用 4 个内部函数（ensure_selected_item_visible, first_available_action, next_available_action, schedule_frame）；被 1 处调用（handle_key）。

fn confirm_selection(&mut self)

作用：处理“确认”动作，也就是用户按回车或数字快捷键选中了某个动作。它根据当前焦点决定是勾选项目还是执行按钮。

数据流：进去的是当前屏幕状态 → 如果焦点在项目上，就切换该项目勾选；如果焦点在按钮上，就执行继续、自定义、取消或返回 → 可能改变页面，也可能结束界面。

调用关系：handle_key 按 Enter 时调用它；select_numbered_action 选中数字按钮后也调用它。它再分派给 proceed、customize、skip、back_to_summary 或 toggle_selected_item。

调用图：调用 5 个内部函数（back_to_summary, customize, proceed, skip, toggle_selected_item）；被 2 处调用（handle_key, select_numbered_action）。

fn handle_key(&mut self, key_event: KeyEvent)

作用：把用户按下的键翻译成界面动作。它是键盘操作进入屏幕状态的总入口。

数据流：进去的是一个键盘事件 → 它忽略按键释放事件，识别 Ctrl-C/Ctrl-D、方向键、数字键、空格、a、n、Esc、Enter 等 → 修改屏幕状态、请求重绘，或结束提示框。

调用关系：run_external_agent_config_migration_prompt 收到 TuiEvent::Key 后调用它。它把具体工作交给 move_up、move_down、select_numbered_action、customize、back_to_summary、set_all_enabled、toggle_selected_item、confirm_selection 和 skip。

调用图：调用 10 个内部函数（back_to_summary, confirm_selection, customize, move_down, move_up, select_numbered_action, set_all_enabled, skip, toggle_selected_item, is_ctrl_exit_combo）。

fn select_numbered_action(&mut self, number: char)

作用：支持按数字快速选择按钮，比如 1 代表当前显示的第一个动作。这样用户不用移动光标也能操作。

数据流：进去的是字符数字 → 它把数字转成从 0 开始的位置，到当前可用按钮列表里找对应按钮 → 找到后把焦点切到动作区并执行确认。

调用关系：handle_key 在用户按 1 到 9 时调用它。它依赖 available_actions，所以数字含义会跟着当前可见按钮变化。

调用图：调用 2 个内部函数（available_actions, confirm_selection）；被 1 处调用（handle_key）。

fn ensure_selected_item_visible(&mut self)

作用：保证当前选中的项目没有被滚动窗口遮住。就像列表滚动时自动把光标带进可见区域。

数据流：进去的是当前选择和滚动位置 → 它算出选中项目在渲染行里的位置和可见行数 → 必要时调整 scroll_top，让选中行出现在屏幕里。

调用关系：move_up 和 move_down 移动光标后会调用它。它借助 selected_render_line_index 和 render_line_count 计算位置。

调用图：调用 2 个内部函数（render_line_count, selected_render_line_index）；被 2 处调用（move_down, move_up）。

fn render_line_count(&self) -> usize

作用：计算当前页面总共会生成多少行显示内容。滚动逻辑需要知道这个数。

数据流：进去的是屏幕状态 → 它构建当前页面的渲染行列表并取长度 → 返回行数，不改状态。

调用关系：ensure_selected_item_visible 调用它来估算可滚动内容范围。

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

fn selected_render_line_index(&self, selected_item_idx: usize) -> usize

作用：找出某个项目在实际显示行里的位置。因为一个项目可能带说明行，所以项目编号不等于显示行号。

数据流：进去的是项目编号 → 它构建当前页面显示行，查找对应项目所在行 → 返回显示行位置；找不到时用项目编号兜底。

调用关系：ensure_selected_item_visible 用它决定滚动到哪里。它依赖 build_render_lines。

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

fn section_title(cwd: Option<&std::path::Path>) -> Line<'static>

作用：生成自定义页里的分区标题。它会显示“当前项目路径”或“Home”。

数据流：进去的是可选的项目目录路径 → 有路径就生成“Current project: 路径”，没有路径就生成“Home” → 返回一行可显示文本。

调用关系：build_customize_render_lines 在项目所属范围变化时调用它，用来把全局配置和项目配置分开显示。

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

fn build_render_lines(&self) -> Vec<RenderLineEntry>

作用：根据当前页面选择要生成哪种显示行。汇总页和自定义页的内容结构不同，所以这里做分流。

数据流：进去的是当前屏幕状态 → 它查看 view 是 Summary 还是 Customize → 返回对应页面的渲染行列表。

调用关系：render_line_count 和 selected_render_line_index 会调用它。它再把工作交给 build_summary_render_lines 或 build_customize_render_lines。

调用图：调用 2 个内部函数（build_customize_render_lines, build_summary_render_lines）；被 2 处调用（render_line_count, selected_render_line_index）。

fn build_summary_render_lines(&self) -> Vec<RenderLineEntry>

作用：生成汇总页中间那部分列表内容。每个分组显示一行名称和一行说明。

数据流：进去的是分组信息和当前勾选状态 → 它为每个分组生成勾选标记、标题和描述行 → 返回可渲染的行列表。

调用关系：build_render_lines 在 Summary 页面调用它。它使用 group_selection_marker 显示全选、未选或部分选。

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

fn build_customize_render_lines(&self) -> Vec<RenderLineEntry>

作用：生成自定义页的详细列表内容，包括分区标题、每个项目的勾选框、说明和插件详情。

数据流：进去的是全部项目和当前勾选状态 → 它按项目目录分区，逐项生成标签、描述、附加详情和插件摘要 → 返回一组显示行。

调用关系：build_render_lines 在 Customize 页面调用它。它会用 section_title、display_description、external_agent_config_migration_item_label、external_agent_config_migration_item_detail 和 plugin_detail_lines。

调用图：调用 1 个内部函数（external_agent_config_migration_item_detail）；被 1 处调用（build_render_lines）；外部调用 6 个（from, plugin_detail_lines, section_title, new, format!, vec!）。

fn is_ctrl_exit_combo(key_event: KeyEvent) -> bool

作用：判断一个按键是不是 Ctrl-C 或 Ctrl-D，也就是终端里常见的退出组合键。

数据流：进去的是键盘事件 → 它检查键是否为 c 或 d，并且是否按住 Control → 返回 true 或 false。

调用关系：handle_key 在处理其他按键前先调用它。如果命中，就直接取消提示框。

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

fn sample_plugin_details() -> codex_app_server_protocol::MigrationDetails

作用：为测试造一份插件迁移详情，里面故意放了多个市场和插件，用来检查界面折叠显示是否正确。

数据流：进去没有参数 → 它构造一组插件市场和插件名 → 返回 MigrationDetails 测试数据。

调用关系：tests::sample_items 调用它，把插件详情塞进样例导入项里。

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

fn sample_project_root() -> PathBuf

作用：给测试提供一个假的项目根目录，并且在 Windows 和非 Windows 系统上使用不同路径格式。

数据流：进去没有参数 → 它按编译平台选择路径字符串 → 返回 PathBuf 路径对象。

调用关系：tests::sample_project_path 和 tests::sample_items 会调用它，保证快照测试在不同系统上路径格式可控。

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

fn sample_project_path(path: &str) -> String

作用：把一个相对路径拼到测试用项目根目录后面，生成完整项目路径。

数据流：进去的是相对路径字符串 → 它先取 sample_project_root，再拼接传入路径 → 返回显示用字符串。

调用关系：tests::sample_items 用它构造描述文字里的文件路径。

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

fn sample_items() -> Vec<ExternalAgentConfigMigrationItem>

作用：生成一组完整的测试导入项，覆盖配置、会话、插件和 AGENTS 文件等情况。

数据流：进去没有参数 → 它构造多个 ExternalAgentConfigMigrationItem，包括全局项和项目项 → 返回测试用项目列表。

调用关系：大多数测试都调用它来获得一致的输入数据，避免每个测试重复手写复杂结构。

调用图：外部调用 2 个（sample_project_root, vec!）。

fn render_screen(
        screen: &ExternalAgentConfigMigrationScreen,
        width: u16,
        height: u16,
    ) -> String

作用：把一个屏幕状态真正画到测试终端里，并取回画面文字。快照测试用它比较界面有没有变。

数据流：进去的是屏幕对象、宽度和高度 → 它创建虚拟终端，渲染屏幕，刷新后读取终端内容 → 返回多行字符串。

调用关系：prompt_snapshot、customize_snapshot 和 customize_action_snapshot 调用它生成快照内容。

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

fn prompt_snapshot()

作用：检查汇总页默认画面是否符合预期。它能发现文案、布局或勾选标记的意外变化。

数据流：进去没有参数 → 它创建样例项目和初始屏幕，渲染 80x24 的画面 → 用快照断言比较输出。

调用关系：它调用 sample_items、ExternalAgentConfigMigrationScreen::new 和 render_screen，是界面回归测试的一部分。

调用图：调用 2 个内部函数（new, test_dummy）；外部调用 3 个（assert_snapshot!, render_screen, sample_items）。

fn customize_snapshot()

作用：检查进入自定义页后的画面是否符合预期。它覆盖详细列表、分区和插件折叠显示。

数据流：进去没有参数 → 它创建屏幕，调用 customize 进入自定义页，渲染较高的终端画面 → 和保存的快照比较。

调用关系：它依赖 sample_items、new、customize 和 render_screen，专门保护自定义页显示效果。

调用图：调用 2 个内部函数（new, test_dummy）；外部调用 3 个（assert_snapshot!, render_screen, sample_items）。

fn customize_action_snapshot()

作用：检查自定义页里焦点移动到动作按钮时的画面。这样能确认高亮位置和导航显示没有坏。

数据流：进去没有参数 → 它创建屏幕，进入自定义页，再向上移动一次焦点 → 渲染后和快照比较。

调用关系：它调用 customize、move_up 和 render_screen，测试项目区到按钮区的焦点切换。

调用图：调用 2 个内部函数（new, test_dummy）；外部调用 3 个（assert_snapshot!, render_screen, sample_items）。

fn proceed_returns_selected_items()

作用：验证默认选中所有项目时，按回车会返回继续导入并带上所有项目。

数据流：进去没有参数 → 它创建全选屏幕，模拟按 Enter → 检查屏幕已结束，结果是 Proceed 且项目列表完整。

调用关系：它间接测试 handle_key、confirm_selection、proceed、selected_items 和 outcome 这一整条确认链路。

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

fn toggle_item_then_proceed_keeps_remaining_selection()

作用：验证用户取消勾选一个项目后，最终只导入剩下的项目。

数据流：进去没有参数 → 它进入自定义页，按空格取消第一个项目，返回汇总页，再用数字选择导入 → 检查结果只包含后三项。

调用关系：它覆盖 handle_key、customize、toggle_selected_item、back_to_summary 和 select_numbered_action 的配合。

调用图：调用 2 个内部函数（new, test_dummy）；外部调用 5 个（Char, new, assert!, assert_eq!, sample_items）。

fn escape_skips_prompt()

作用：验证在汇总页按 Esc 会取消整个提示。

数据流：进去没有参数 → 它创建屏幕并模拟 Esc → 检查屏幕结束，结果是 Skip。

调用关系：它测试 handle_key 对 Esc 的处理，以及 skip 和 outcome 是否正确。

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

fn numeric_shortcuts_follow_visible_actions_when_proceed_is_disabled()

作用：验证数字快捷键会跟随当前可见按钮变化。全不选时，第一个按钮不再是继续导入，而应是自定义。

数据流：进去没有参数 → 它进入自定义页、全不选、回到汇总页，再按数字 1 → 检查页面进入自定义而不是继续导入。

调用关系：它重点测试 available_actions、normalize_highlighted_action 和 select_numbered_action 在无选中项目时的行为。

调用图：调用 2 个内部函数（new, test_dummy）；外部调用 4 个（Char, new, assert_eq!, sample_items）。

fn empty_selection_enter_opens_customize_instead_of_proceeding()

作用：验证一开始没有任何选中项时，按回车不会误导入，而是打开自定义选择页。

数据流：进去没有参数 → 它用空的 selected_items 创建屏幕，模拟 Enter → 检查界面没有结束，并切到 Customize。

调用关系：它覆盖 proceed_enabled 影响 available_actions，再影响 confirm_selection 的流程。

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

fn control_exit_shortcuts_cancel_prompt()

作用：验证 Ctrl-C 和 Ctrl-D 都会取消提示。这符合终端用户对退出快捷键的直觉。

数据流：进去没有参数 → 它分别创建屏幕并模拟 Ctrl-C、Ctrl-D → 每次都检查结果为 Skip。

调用关系：它测试 is_ctrl_exit_combo 和 handle_key 的优先处理逻辑。

调用图：调用 2 个内部函数（new, test_dummy）；外部调用 5 个（Char, new, assert!, assert_eq!, sample_items）。

fn numeric_shortcuts_choose_actions()

作用：验证数字快捷键能选择继续、自定义、返回和取消等动作。

数据流：进去没有参数 → 它分别创建多个屏幕，按不同数字 → 检查结果或页面状态是否符合对应按钮动作。

调用关系：它集中测试 select_numbered_action、available_actions 和 confirm_selection 的配合。

调用图：调用 2 个内部函数（new, test_dummy）；外部调用 4 个（Char, new, assert_eq!, sample_items）。

fn summary_does_not_toggle_selection()

作用：验证在汇总页按空格不会改变勾选状态。只有自定义页才能逐项勾选。

数据流：进去没有参数 → 它创建全选屏幕，在汇总页模拟空格 → 检查 selected_items 仍然是原来的全部项目。

调用关系：它保护 handle_key 和 toggle_selected_item 的边界规则，防止汇总页误改用户选择。

调用图：调用 2 个内部函数（new, test_dummy）；外部调用 4 个（Char, new, assert_eq!, sample_items）。

fn render_items(&self, area: Rect, buf: &mut Buffer)

作用：这个函数专门画中间的“可导入项目列表”。它会处理滚动、当前选中项的高亮，以及文字太长时用省略号截断，避免内容挤出屏幕。

数据流：进去的是一块可绘制的屏幕区域和一个终端缓冲区（一块临时画布）。它先从当前界面状态生成要显示的每一行，再根据滚动位置和选中项算出应该从哪一行开始画；然后逐行判断是否选中，给选中行加箭头、青色和粗体，给说明类行变暗；最后把每行按区域宽度截短后写进缓冲区。出来的结果不是返回一个值，而是缓冲区里多了列表内容。

调用关系：它是整个界面绘制流程里的一个零件，只负责列表这一块。ExternalAgentConfigMigrationScreen::render_ref 在画完整屏幕时会调用它；它自己会把每行交给 truncate_line_with_ellipsis_if_overflow，确保终端宽度不够时不会把布局撑乱。

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

fn render_ref(&self, area: Rect, buf: &mut Buffer)

作用：这个函数负责画完整的迁移界面。只要终端需要刷新这个页面，它就把所有部分重新摆好并画出来。

数据流：进去的是整块屏幕区域和一个终端缓冲区。它先清空这块区域，再缩进出内部内容区；然后根据当前视图选择标题和说明文字，根据是否有错误决定错误区高度，根据项目数量和屏幕高度决定列表能显示几行；接着画标题、说明、错误、项目列表、已选择数量、可执行动作，以及底部快捷键提示。出来的结果同样是缓冲区被填上完整页面内容，等待终端真正显示。

调用关系：它是这个文件的主绘制入口，被终端 UI 框架在刷新控件时调用。它把列表部分交给 ExternalAgentConfigMigrationScreen::render_items，把动作按钮行交给 selection_option_row_with_dim，并使用布局工具把屏幕切成一块块区域，保证各部分按固定顺序显示。

调用图：调用 3 个内部函数（render_items, vh, selection_option_row_with_dim）；外部调用 10 个（Fill, Length, vertical, from, new, inset, format!, repeat_n, from, vec!）。

fn all() -> [Self; 2]

作用：给出菜单里所有可选项，也就是“试用新模型”和“继续用旧模型”。这样画菜单时不用到处手写这两个选项。

数据流：进去不需要任何输入 → 它直接返回固定的两个菜单选项 → 出来的是一个包含两个选项的列表，供界面逐行显示。

调用关系：它主要在 ModelMigrationScreen::render_menu 画菜单时被调用。render_menu 拿到这两个选项后，再为每一项生成一行可选择的菜单。

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

fn label(self) -> &'static str

作用：把内部菜单选项变成用户能看懂的英文按钮文字。比如内部的 TryNewModel 会显示成 “Try new model”。

数据流：进去的是一个菜单选项 → 它根据选项种类挑一段固定文字 → 出来的是要显示在终端菜单上的标签。

调用关系：它服务于菜单渲染流程。画菜单时，每个 MigrationMenuOption 都需要先变成文字，再交给选择行组件显示。

fn migration_copy_for_models(
    current_model: &str,
    target_model: &str,
    model_link: Option<String>,
    migration_copy: Option<String>,
    migration_markdown: Option<String>,
    target_di

作用：根据当前模型、新模型、说明链接和配置文案，组装出升级提示页要显示的文字。别人不用关心提示语怎么拼，只要把模型信息传进来就能得到一份完整文案。

数据流：进去的是旧模型名、新模型名、可选链接、可选自定义说明、可选 Markdown 模板、新模型显示名、新模型描述、是否允许拒绝升级 → 它优先使用 Markdown 模板；没有模板时就拼标题、推荐语、说明、链接和是否可跳过的提示 → 出来的是 ModelMigrationCopy，里面装着标题、正文、是否能拒绝、以及可能的 Markdown 内容。

调用关系：这是展示前的文案准备步骤。测试里的多个截图用例都会先调用它生成提示内容；如果传了 Markdown，它会把模板交给 fill_migration_markdown 替换模型名。

调用图：调用 1 个内部函数（fill_migration_markdown）；被 6 处调用（escape_key_accepts_prompt, prompt_snapshot, prompt_snapshot_gpt5_codex, prompt_snapshot_gpt5_codex_mini, prompt_snapshot_gpt5_family, selecting_use_existing_model_rejects_upgrade）；外部调用 5 个（from, from, new, format!, vec!）。

async fn run_model_migration_prompt(
    tui: &mut Tui,
    copy: ModelMigrationCopy,
) -> ModelMigrationOutcome

作用：真正运行这页模型升级提示：打开临时屏幕、画界面、等用户按键，然后返回用户最后的选择。

数据流：进去的是正在运行的 TUI 终端对象和已经准备好的提示文案 → 它进入备用屏幕，创建 ModelMigrationScreen，先画一次界面，然后不断读取按键、粘贴、重绘和窗口变化事件 → 出来的是 ModelMigrationOutcome，表示接受、拒绝或退出，同时终端会离开备用屏幕。

调用关系：这是外部代码最可能调用的入口函数。它先用 AltScreenGuard::enter 保护终端显示，再创建 ModelMigrationScreen；之后按键事件交给 screen.handle_key，绘制事件交给 ratatui 渲染 screen。

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

fn new(request_frame: FrameRequester, copy: ModelMigrationCopy) -> Self

作用：创建一个新的升级提示屏幕对象，保存文案和初始状态。默认高亮“试用新模型”，默认结果也偏向接受。

数据流：进去的是一个请求重画的工具 FrameRequester 和一份提示文案 ModelMigrationCopy → 它把 done 设成 false，把 outcome 设成 Accepted，把高亮项设成 TryNewModel → 出来的是可被绘制、可处理按键的屏幕状态对象。

调用关系：run_model_migration_prompt 会用它启动真实提示页；测试也用它创建屏幕，再把屏幕画到假终端里检查显示效果和按键行为。

调用图：被 8 处调用（run_model_migration_prompt, escape_key_accepts_prompt, markdown_prompt_keeps_long_url_tail_visible_when_narrow, prompt_snapshot, prompt_snapshot_gpt5_codex, prompt_snapshot_gpt5_codex_mini, prompt_snapshot_gpt5_family, selecting_use_existing_model_rejects_upgrade）。

fn finish_with(&mut self, outcome: ModelMigrationOutcome)

作用：用某个最终结果结束提示页。它是接受、拒绝、退出三个动作背后的共同收尾函数。

数据流：进去的是一个结果，比如 Accepted、Rejected 或 Exit → 它把屏幕的 outcome 改成这个结果，把 done 改成 true，并请求终端再画一帧 → 出来没有单独返回值，但屏幕状态已经变成“结束”。

调用关系：ModelMigrationScreen::accept、reject、exit 都把最后收尾交给它。它还会调用 schedule_frame，让外层循环知道界面状态变了，需要刷新。

调用图：调用 1 个内部函数（schedule_frame）；被 3 处调用（accept, exit, reject）。

fn accept(&mut self)

作用：把用户选择记录为“接受新模型”。这是回车确认、数字 1、不可拒绝提示确认等场景都会用到的动作。

数据流：进去不需要额外输入 → 它调用 finish_with，把结果设为 Accepted → 出来时屏幕已标记完成，外层循环会停止等待。

调用关系：它被 confirm_selection、handle_key 和 handle_menu_key 使用。也就是说，无论用户从菜单确认还是直接按键确认，最终都走这条接受路径。

调用图：调用 1 个内部函数（finish_with）；被 3 处调用（confirm_selection, handle_key, handle_menu_key）。

fn reject(&mut self)

作用：把用户选择记录为“继续使用旧模型”。只有允许拒绝升级时，这个动作才有意义。

数据流：进去不需要额外输入 → 它调用 finish_with，把结果设为 Rejected → 出来时屏幕结束，外层可以据此不切换模型。

调用关系：它被 confirm_selection 和 handle_menu_key 调用。用户高亮“Use existing model”再确认，或直接按数字 2 时，会走到这里。

调用图：调用 1 个内部函数（finish_with）；被 2 处调用（confirm_selection, handle_menu_key）。

fn exit(&mut self)

作用：把用户操作记录为“退出”。这不是选择新旧模型，而是表示用户用 Ctrl-C 或 Ctrl-D 想中断流程。

数据流：进去不需要额外输入 → 它调用 finish_with，把结果设为 Exit → 出来时屏幕结束，调用方可以停止后续启动或迁移流程。

调用关系：它由 handle_key 在检测到退出组合键后调用。这样普通 Esc 不会被误当成退出，而 Ctrl-C/Ctrl-D 才是退出。

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

fn confirm_selection(&mut self)

作用：根据当前高亮的菜单项执行确认。它把“用户现在选中哪一行”转换成真正的接受或拒绝结果。

数据流：进去读取屏幕里的 can_opt_out 和 highlighted_option → 如果允许拒绝，就看高亮项：新模型就 accept，旧模型就 reject；如果不允许拒绝，就直接 accept → 出来时屏幕通常已经结束。

调用关系：它被 handle_menu_key 在用户按回车或 Esc 时调用。它再把具体决定交给 accept 或 reject。

调用图：调用 2 个内部函数（accept, reject）；被 1 处调用（handle_menu_key）。

fn highlight_option(&mut self, option: MigrationMenuOption)

作用：移动菜单高亮光标，让用户能看出当前选中的是哪一项。只有高亮真的变了，才请求重画。

数据流：进去的是想高亮的新选项 → 它和当前高亮项比较；不同就更新 highlighted_option，并请求下一帧重画 → 出来没有返回值，但界面状态可能已改变。

调用关系：它被 handle_menu_key 调用。用户按上、下、j、k 或数字键时，菜单处理函数会先用它改高亮，再决定是否确认。

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

fn handle_key(&mut self, key_event: KeyEvent)

作用：处理用户按下的键，是提示页的按键总入口。它负责区分退出键、菜单键、确认键这些不同情况。

数据流：进去的是一个 KeyEvent，里面有按键、修饰键和按键阶段 → 它先忽略“松开按键”的事件，再检查 Ctrl-C/Ctrl-D；如果能选择新旧模型，就交给 handle_menu_key；否则 Esc 或 Enter 都当作接受 → 出来没有返回值，但屏幕可能会改变高亮或结束。

调用关系：run_model_migration_prompt 的事件循环收到 TuiEvent::Key 后会调用它。它内部会用 is_ctrl_exit_combo 判断退出组合键，并按情况调用 exit、accept 或 handle_menu_key。

调用图：调用 4 个内部函数（accept, exit, handle_menu_key, is_ctrl_exit_combo）；外部调用 1 个（matches!）。

fn is_done(&self) -> bool

作用：告诉外层提示页是不是已经结束。事件循环靠它决定还要不要继续等用户输入。

数据流：进去不需要输入 → 它读取 screen.done → 出来是 true 或 false。

调用关系：run_model_migration_prompt 的 while 循环会反复检查它。只要它变成 true，提示流程就停止，并返回 outcome。

fn outcome(&self) -> ModelMigrationOutcome

作用：取出用户最后的选择结果。外层代码用这个结果决定是否切换模型、保留旧模型或退出。

数据流：进去不需要输入 → 它读取 screen.outcome → 出来是 ModelMigrationOutcome 的一个值。

调用关系：run_model_migration_prompt 在屏幕结束后调用它，把结果交回给调用方。测试也用它确认按键行为是否符合预期。

fn render_ref(&self, area: ratatui::layout::Rect, buf: &mut ratatui::buffer::Buffer)

作用：把整个升级提示页画到终端缓冲区里。可以把它理解成这页界面的“总画师”。

数据流：进去的是可绘制区域 area 和终端画布 buf → 它先清空区域，再创建一列内容；有 Markdown 就画 Markdown，没有就画标题和普通正文；如果允许拒绝升级，还会画选择菜单 → 出来没有普通返回值，但终端画布里已经有了完整界面。

调用关系：run_model_migration_prompt 里的 draw 会触发它。它把具体工作分给 heading_line、render_content、render_markdown_content 和 render_menu。

调用图：调用 5 个内部函数（heading_line, render_content, render_markdown_content, render_menu, new）；外部调用 1 个（from）。

fn handle_menu_key(&mut self, code: KeyCode)

作用：专门处理有菜单时的按键，比如上下移动、j/k 移动、数字 1/2 快选、回车确认。

数据流：进去的是按键代码 KeyCode → 它根据键位更新高亮项，或者直接接受、拒绝、确认当前选择；不认识的键就忽略 → 出来没有返回值，但可能移动了光标或结束屏幕。

调用关系：它由 handle_key 在 can_opt_out 为 true 时调用。它再把具体动作交给 highlight_option、accept、reject 或 confirm_selection。

调用图：调用 4 个内部函数（accept, confirm_selection, highlight_option, reject）；被 1 处调用（handle_key）。

fn heading_line(&self) -> Line<'static>

作用：生成提示页标题那一行，并在前面加上一个 “> ” 符号，让标题更像提示块。

数据流：进去不需要额外输入，只读取 copy.heading → 它把固定前缀和标题文字拼成一行 → 出来是一条可渲染的 Line。

调用关系：render_ref 在渲染普通文案模式时调用它。Markdown 模式下不走这条标题生成逻辑。

调用图：被 1 处调用（render_ref）；外部调用 2 个（from, vec!）。

fn render_content(&self, column: &mut ColumnRenderable)

作用：把普通正文内容放进页面列里。它本身不逐行画，而是把行列表交给通用的 render_lines。

数据流：进去的是一个可追加内容的 ColumnRenderable → 它读取 copy.content，并调用 render_lines 按行加入段落 → 出来时 column 里多了正文段落。

调用关系：render_ref 在没有 Markdown 时调用它。它再把细节交给 render_lines，保持主渲染流程简单。

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

fn render_lines(&self, lines: &[Line<'static>], column: &mut ColumnRenderable)

作用：把多行文字逐行变成带缩进、可自动换行的段落。这样长句不会直接挤出屏幕。

数据流：进去的是若干 Line 和一个页面列 column → 它遍历每一行，为每行创建 Paragraph，设置自动换行和左侧缩进，然后 push 到 column → 出来时 column 里增加了这些段落。

调用关系：它由 render_content 调用，是普通正文渲染的底层小工具。它会用 Insets 设置缩进，并用 ColumnRenderable::push 把内容接到页面里。

调用图：调用 2 个内部函数（tlbr, push）；被 1 处调用（render_content）；外部调用 1 个（new）。

fn render_markdown_content(
        &self,
        markdown: &str,
        area_width: u16,
        column: &mut ColumnRenderable,
    )

作用：把 Markdown 文本渲染到提示页里。Markdown 可以理解成一种带简单格式的文本，比如链接、列表、强调等。

数据流：进去的是 Markdown 字符串、屏幕宽度和页面列 → 它先扣掉左右缩进算出可用宽度，再调用 render_markdown_text_with_width 把 Markdown 转成适合终端宽度的多行内容，最后逐行放入带缩进的段落 → 出来时 column 里多了渲染后的 Markdown 内容。

调用关系：render_ref 在 copy.markdown 存在时调用它。它依赖 markdown_render 模块做真正的 Markdown 排版，自己负责宽度和缩进。

调用图：调用 3 个内部函数（render_markdown_text_with_width, tlbr, push）；被 1 处调用（render_ref）；外部调用 1 个（new）。

fn render_menu(&self, column: &mut ColumnRenderable)

作用：画出“试用新模型 / 继续旧模型”的选择菜单，以及底部的按键提示。

数据流：进去的是页面列 column → 它先加入说明文字和空行，再通过 MigrationMenuOption::all 拿到所有选项，为每个选项生成选择行，最后加上“用上下键移动、回车确认”的提示 → 出来时 column 里多了完整菜单。

调用关系：render_ref 在 can_opt_out 为 true 时调用它。它会用 selection_option_row 画每个选项，并用 key_hint 显示按键长什么样。

调用图：调用 4 个内部函数（all, tlbr, push, selection_option_row）；被 1 处调用（render_ref）；外部调用 3 个（from, new, vec!）。

fn enter(tui: &'a mut Tui) -> Self

作用：让终端进入“备用屏幕”。备用屏幕像临时白板，提示页关闭后不会在正常滚动记录里留下一大块空白。

数据流：进去的是可操作的 Tui 对象 → 它调用 enter_alt_screen 尝试切到备用屏幕，然后把这个 Tui 引用包进 AltScreenGuard → 出来的是一个守卫对象，活着时代表当前在备用屏幕里。

调用关系：run_model_migration_prompt 会在显示升级提示前调用它；调用图里另一个 session picker 流程也会复用它。它和 AltScreenGuard::drop 配成一对，保证离开时能切回来。

调用图：被 2 处调用（run_model_migration_prompt, run_session_picker_with_loader）；外部调用 1 个（enter_alt_screen）。

fn drop(&mut self)

作用：在备用屏幕守卫被销毁时，自动把终端切回正常屏幕。这样即使中途结束，也不容易把终端留在奇怪状态。

数据流：进去的是即将被释放的 AltScreenGuard → 它调用 leave_alt_screen → 出来没有返回值，但终端会尝试恢复到普通屏幕。

调用关系：Rust 的 Drop 机制会自动调用它，不需要手写调用。run_model_migration_prompt 结束时，AltScreenGuard 离开作用域，就会触发这里。

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

fn is_ctrl_exit_combo(key_event: KeyEvent) -> bool

作用：判断一个按键是不是 Ctrl-C 或 Ctrl-D，也就是常见的“我要中断/退出”组合键。

数据流：进去的是 KeyEvent → 它检查是否带 Control 修饰键，并且主键是不是字符 c 或 d → 出来是布尔值，true 表示这是退出组合键。

调用关系：ModelMigrationScreen::handle_key 会先调用它。只要它返回 true，handle_key 就会走 exit，而不会继续当普通菜单按键处理。

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

fn fill_migration_markdown(template: &str, current_model: &str, target_model: &str) -> String

作用：把 Markdown 模板里的占位符替换成真实模型名。比如把 {model_from} 换成旧模型，把 {model_to} 换成新模型。

数据流：进去的是模板字符串、当前模型名、目标模型名 → 它做两次文本替换 → 出来是一段可以直接显示的 Markdown 字符串。

调用关系：migration_copy_for_models 在收到 migration_markdown 时调用它。这样配置里可以写通用模板，运行时再填入具体模型。

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

fn prompt_snapshot()

作用：检查可拒绝升级的提示页长什么样。它用快照测试防止以后改代码时不小心把界面排版改坏。

数据流：进去不需要外部输入 → 它创建一个假终端，生成迁移文案，创建屏幕，把屏幕画进去并刷新 → 出来是一次快照断言：当前画面必须和保存的标准画面一致。

调用关系：它调用 migration_copy_for_models 和 ModelMigrationScreen::new 搭出屏幕，再用 assert_snapshot! 比较终端输出。

调用图：调用 5 个内部函数（with_options, new, migration_copy_for_models, new, test_dummy）；外部调用 2 个（new, assert_snapshot!）。

fn prompt_snapshot_gpt5_family()

作用：检查 gpt-5 到 gpt-5.1 这类不可拒绝升级提示的显示效果，尤其包含模型链接时的排版。

数据流：进去不需要外部输入 → 它创建 65x22 的假终端，生成带链接、不可拒绝的迁移文案，渲染屏幕 → 出来是快照比对结果。

调用关系：它沿用 migration_copy_for_models 和 ModelMigrationScreen::new，与其他快照测试一起覆盖不同模型文案场景。

调用图：调用 5 个内部函数（with_options, new, migration_copy_for_models, new, test_dummy）；外部调用 2 个（new, assert_snapshot!）。

fn prompt_snapshot_gpt5_codex()

作用：检查从 gpt-5-codex 升到 gpt-5.1-codex-max 时，提示页是否按预期显示。

数据流：进去不需要外部输入 → 它建立假终端和迁移文案，画出不可拒绝升级页面 → 出来是和保存快照的比较结果。

调用关系：它调用 migration_copy_for_models 生成 codex-max 场景的文案，再用 ModelMigrationScreen::new 创建屏幕进行渲染测试。

调用图：调用 5 个内部函数（with_options, new, migration_copy_for_models, new, test_dummy）；外部调用 2 个（new, assert_snapshot!）。

fn prompt_snapshot_gpt5_codex_mini()

作用：检查 mini 模型升级提示页的显示效果。这个测试确保便宜、更快但能力较弱这类描述也能正常排版。

数据流：进去不需要外部输入 → 它创建 60x22 的假终端，生成 gpt-5-codex-mini 到 gpt-5.1-codex-mini 的文案，渲染并刷新 → 出来是快照断言结果。

调用关系：它和其他 prompt_snapshot 测试一样，覆盖 migration_copy_for_models 生成的不同内容如何被 ModelMigrationScreen 画出来。

调用图：调用 5 个内部函数（with_options, new, migration_copy_for_models, new, test_dummy）；外部调用 2 个（new, assert_snapshot!）。

fn escape_key_accepts_prompt()

作用：确认 Esc 键在这个提示页里不是“退出程序”，而是像回车一样确认当前选择。这个行为避免用户按 Esc 后被误判成中断。

数据流：进去不需要外部输入 → 它创建一个允许拒绝升级的屏幕，模拟按下 Esc → 出来时断言屏幕已结束，并且结果是 Accepted。

调用关系：它通过 ModelMigrationScreen::handle_key 测试真实按键路径，再用 is_done 和 outcome 检查状态。

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

fn selecting_use_existing_model_rejects_upgrade()

作用：确认用户选择“继续使用旧模型”时，结果真的会变成拒绝升级。

数据流：进去不需要外部输入 → 它创建可拒绝升级的屏幕，模拟按下 Down 把高亮移到旧模型，再按 Enter 确认 → 出来时断言屏幕结束且 outcome 是 Rejected。

调用关系：它走的是 handle_key 到 handle_menu_key，再到 highlight_option 和 confirm_selection/reject 的路径，用来验证菜单选择链路。

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

fn markdown_prompt_keeps_long_url_tail_visible_when_narrow()

作用：检查很窄的终端里显示超长 URL 时，末尾不会被吞掉。这个很重要，因为链接尾巴常常包含真正有用的信息。

数据流：进去不需要外部输入 → 它把一条很长的 URL 放进 Markdown 文案，创建 40 列宽的假终端并渲染 → 出来时检查渲染文本里仍然包含 URL 末尾的 tail42。

调用关系：它专门覆盖 render_markdown_content 调用 render_markdown_text_with_width 后的换行效果，防止窄屏 Markdown 渲染把长链接截断。

调用图：调用 4 个内部函数（with_options, new, new, test_dummy）；外部调用 3 个（new, new, assert!）。

fn collab_receiver_thread_ids(notification: &ServerNotification) -> Option<&[String]>

作用：从服务器通知里找出“协作代理工具调用”要发给哪些接收线程。它只关心开始和完成两类通知，其他通知一律当作没有接收者。

数据流：进去的是一条服务器通知 → 函数查看通知类型和里面的线程条目是不是协作代理工具调用 → 如果是，就把接收线程 id 列表借出来；如果不是，就返回空。

调用关系：它是事件分流时用的小筛子，帮助上层逻辑判断某条服务器消息是否还要转给其他协作线程，而不是直接显示在当前主聊天里。

fn sub_agent_activity_item(notification: &ServerNotification) -> Option<&ThreadItem>

作用：从服务器通知里挑出“子代理活动”这类条目。子代理可以理解为主助手派出去干活的小助手，这个函数判断通知是不是在汇报小助手的活动。

数据流：进去的是服务器通知 → 它只检查条目开始和条目完成两种通知 → 如果里面的条目是子代理活动，就返回这个条目；否则返回空。

调用关系：它给线程事件处理逻辑提供快速识别能力，让界面能把子代理活动放到合适的位置展示，而不是混成普通消息。

fn collab_receiver_is_not_found(
    notification: &ServerNotification,
    receiver_thread_id: &str,
) -> bool

作用：判断一次协作代理调用结束时，某个指定的接收线程是不是被服务器标成“没找到”。这能帮助界面发现目标线程已经不存在或不可用。

数据流：进去的是一条服务器通知和一个接收线程 id → 它只看协作代理工具调用的完成通知 → 在代理状态表里查这个 id，如果状态是 NotFound 就返回真，否则返回假。

调用关系：它通常服务于协作线程的容错流程：当服务器说某个接收线程不存在时，上层可以避免继续往那个线程投递消息，并采取回退或提示。

fn default_exec_approval_decisions(
    network_approval_context: Option<&codex_app_server_protocol::NetworkApprovalContext>,
    proposed_execpolicy_amendment: Option<&codex_app_server_protocol::Exec

作用：给“是否允许执行命令”的弹窗准备默认可选项。比如允许一次、允许本次会话、修改网络规则后允许、取消。

数据流：进去的是网络审批上下文、可能的执行策略修改、可能的网络策略修改、可能的额外权限 → 函数根据场景组合一组审批决定 → 出来的是按钮/选项列表，不直接执行命令。

调用关系：它给权限审批界面提供基础菜单。后续弹窗会把这些决定展示给用户，用户选中后才会继续交给执行和权限系统。

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

fn auto_review_mode() -> AutoReviewMode

作用：生成一套“自动审查”模式的默认权限设置。用户开启这个实验功能时，界面会马上切到相配套的权限模式。

数据流：不需要输入 → 函数固定创建一个 AutoReviewMode，里面包含按请求审批、自动审查者、内置工作区权限档案 → 返回这套模式对象。

调用关系：它是自动审查功能的统一入口之一。其他配置同步代码需要知道“自动审查应该长什么样”时，会以这里的结果为准。

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

fn permission_profile(&self) -> PermissionProfile

作用：在测试里把自动审查模式使用的活动权限档案，转换成实际的权限档案内容。权限档案可以理解为一份“允许做什么、不允许做什么”的清单。

数据流：进去的是 AutoReviewMode 自己保存的活动权限档案标识 → 调用内置权限档案查找函数 → 出来的是完整 PermissionProfile；如果找不到，测试会直接失败。

调用关系：它只在测试配置下存在，用来验证 auto_review_mode 生成的档案确实是内置且可用的。

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

fn managed_filesystem_sandbox_is_restricted(permission_profile: &PermissionProfile) -> bool

作用：在 Windows 上判断当前文件系统沙箱是不是“受限制”模式。沙箱可以理解为给程序划出的安全活动范围。

数据流：进去的是一份权限档案 → 函数查看它的文件系统沙箱策略种类 → 如果种类是 Restricted，就返回真，否则返回假。

调用关系：App::run 启动时会用它决定是否需要扫描并提醒危险的可写目录。它只在 Windows 版本里编译使用。

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

fn fatal(message: impl Into<String>) -> Self

作用：快速创建一个“程序因为严重错误退出”的退出信息。这样调用者不用手动填一堆默认字段。

数据流：进去的是错误消息 → 函数把 token 用量、线程 id、恢复提示、更新动作都设成空或默认 → 出来的是带 Fatal 退出原因的 AppExitInfo。

调用关系：外层交互式 TUI 入口 run_interactive_tui 会在启动失败等严重情况用它，把错误包装成统一的退出结果。

调用图：被 1 处调用（run_interactive_tui）；外部调用 3 个（into, default, Fatal）。

fn session_summary(
    token_usage: TokenUsage,
    thread_id: Option<ThreadId>,
    thread_name: Option<String>,
    rollout_path: Option<&Path>,
) -> Option<SessionSummary>

作用：为会话结束后的总结准备内容，比如用了多少 token，以及还能不能用命令恢复这个会话。token 可以理解为模型处理文字时计费和计量的单位。

数据流：进去的是 token 用量、线程 id、线程名、会话记录文件路径 → 它先把非零用量转成文字，再尝试生成恢复提示 → 如果两者都没有就返回空，否则返回 SessionSummary。

调用关系：它依赖 resume_hint_for_resumable_thread 来判断能否恢复会话，给退出或历史展示相关代码提供一段简短总结。

调用图：调用 2 个内部函数（is_zero, resume_hint_for_resumable_thread）。

fn resumable_thread(
    thread_id: Option<ThreadId>,
    thread_name: Option<String>,
    rollout_path: Option<&Path>,
) -> Option<ResumableThread>

作用：判断一个线程是否真的可以被恢复。光有线程 id 不够，还要有一份存在且非空的记录文件。

数据流：进去的是可选线程 id、可选线程名、可选记录文件路径 → 缺任何关键项就返回空；路径存在且是非空文件时，组装 ResumableThread → 出来的是可恢复线程信息或空。

调用关系：resume_hint_for_resumable_thread 会先调用它确认“确实能恢复”，再生成给用户看的恢复命令提示。

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

fn resume_hint_for_resumable_thread(
    thread_id: Option<ThreadId>,
    thread_name: Option<String>,
    rollout_path: Option<&Path>,
) -> Option<String>

作用：给可恢复的会话生成一条用户看得懂的恢复提示。比如告诉用户以后可以用某个 resume 命令继续这个线程。

数据流：进去的是线程 id、线程名、记录文件路径 → 先调用 resumable_thread 检查是否满足恢复条件 → 满足时调用命令行工具函数生成提示文字；不满足则返回空。

调用关系：App::run 在退出时会用它填 AppExitInfo，session_summary 也会用它组成会话总结。

调用图：调用 1 个内部函数（resumable_thread）；被 2 处调用（run, session_summary）；外部调用 1 个（resume_hint）。

fn rollout_path_is_resumable(rollout_path: &Path) -> bool

作用：检查会话记录文件路径是否适合用于恢复。标准很简单：路径必须指向一个存在的普通文件，而且文件不能是空的。

数据流：进去的是一个路径 → 函数读取这个路径的文件元信息 → 如果它是文件且长度大于 0，返回真；读取失败或不符合条件就返回假。

调用关系：它是 resumable_thread 的底层检查。这样恢复提示不会误导用户去恢复一份不存在或空白的会话记录。

调用图：被 1 处调用（resumable_thread）；外部调用 1 个（metadata）。

fn errors_for_cwd(cwd: &Path, response: &SkillsListResponse) -> Vec<SkillErrorInfo>

作用：从技能列表响应里取出当前工作目录对应的技能加载错误。工作目录就是用户现在所在的项目文件夹。

数据流：进去的是一个目录路径和服务器返回的技能列表 → 函数在列表里找 cwd 相同的那项 → 找到就克隆它的错误列表，找不到就返回空列表。

调用关系：它给启动技能刷新和警告展示使用，让界面只显示当前项目真正相关的技能错误。

fn from_config(config: &Config) -> Self

作用：把当前配置里的运行时权限状态拍一张快照。后面即使配置刷新，也能知道用户当时覆盖过哪些权限设置。

数据流：进去的是 Config → 函数读取权限档案、活动权限档案标识、网络权限配置 → 出来的是 RuntimePermissionProfileOverride，不修改原配置。

调用关系：权限选择、自动审查同步、功能开关更新、事件处理等流程会调用它，用来保存或比较运行中的权限覆盖状态。

调用图：被 4 处调用（apply_permission_profile_selection, sync_auto_review_runtime_state_from_effective_config, update_feature_flags, handle_event）。

fn active_turn_not_steerable_turn_error(error: &TypedRequestError) -> Option<AppServerTurnError>

作用：从服务器错误里识别“当前轮次不能被引导”的情况。轮次可以理解为用户发一次请求后，助手正在处理的那一回合。

数据流：进去的是一个带类型的请求错误 → 如果不是服务器错误就返回空；如果是，就尝试把错误数据解析成 TurnError → 只有错误类型是 ActiveTurnNotSteerable 时才返回这个 TurnError。

调用关系：它给转向或干预当前轮次的逻辑做错误分类。识别出来后，上层可以用更合适的方式提示用户，而不是显示一段生硬的服务器错误。

调用图：外部调用 2 个（matches!, from_value）。

async fn resolve_runtime_model_provider_base_url(provider: &ModelProviderInfo) -> Option<String>

作用：异步查出当前模型服务实际使用的基础网址。模型服务就是负责接收请求并返回模型结果的后端。

数据流：进去的是模型服务配置 → 函数创建一个模型服务对象，再向它询问运行时 base URL → 成功就返回网址；失败会写日志警告并返回空。

调用关系：App::run 启动时调用它，把结果放进聊天窗口状态栏等地方，让用户能看到当前连到哪里。

调用图：被 1 处调用（run）；外部调用 4 个（create_model_provider, clone, runtime_base_url, warn!）。