RPC 请求路由

fn deserialize_client_request(
    request: &JSONRPCRequest,
) -> Result<ClientRequest, JSONRPCErrorError>

作用：把收到的通用 JSON-RPC 请求，转换成项目内部更具体的 ClientRequest。这样后面的代码就不用猜这条请求到底想干什么。

数据流：进去的是一条 JSONRPCRequest → 先转成 JSON 值，再按 ClientRequest 的格式解析 → 成功就得到类型明确的请求，失败就产出“无效请求”的错误。

调用关系：MessageProcessor::process_request 收到网络 JSON 请求后会先调用它。它只负责“翻译格式”，翻译完才交给 MessageProcessor::handle_client_request 去真正处理。

调用图：被 1 处调用（process_request）；外部调用 1 个（to_value）。

fn map_reason(reason: ExternalAuthRefreshReason) -> ChatgptAuthTokensRefreshReason

作用：把登录模块内部的“为什么要刷新认证”的原因，翻译成协议里发给客户端的原因。现在只处理一种情况：未授权，需要刷新。

数据流：进去的是 ExternalAuthRefreshReason → 根据枚举值做对应转换 → 出来的是 ChatgptAuthTokensRefreshReason，供发给客户端使用。

调用关系：ExternalAuthRefreshBridge::refresh 在向客户端请求新 token 前会用它做一次小翻译，保证登录模块和 app-server 协议说的是同一种语言。

fn auth_mode(&self) -> LoginAuthMode

作用：告诉登录系统，这个外部刷新桥服务的是 ChatGPT 登录模式。登录系统据此知道该把哪类刷新请求交给它。

数据流：不需要输入额外数据 → 直接返回 LoginAuthMode::Chatgpt → 不改动任何状态。

调用关系：它是 ExternalAuth 这个接口的一部分。AuthManager 需要判断外部认证类型时会通过这个方法识别这座桥。

fn refresh(
        &self,
        context: ExternalAuthRefreshContext,
    ) -> codex_login::ExternalAuthFuture<'_, ExternalAuthTokens>

作用：当服务端发现 ChatGPT 登录 token 失效时，通过现有连接请求客户端刷新 token。它像是服务端向客户端递一张“请重新取票”的纸条。

数据流：进去的是刷新上下文，比如刷新原因和之前的账号 ID → 组装成 ChatgptAuthTokensRefresh 请求发给客户端，并最多等 10 秒 → 成功时把客户端返回的 access token、账号 ID、套餐类型包装成 ExternalAuthTokens；超时、取消或客户端报错时返回输入输出错误。

调用关系：MessageProcessor::new 会把 ExternalAuthRefreshBridge 注册进 AuthManager。之后登录系统需要刷新外部认证时，会通过 ExternalAuth 接口调用这里；这里再借 OutgoingMessageSender 把请求发回客户端。

调用图：调用 1 个内部函数（chatgpt）；外部调用 7 个（pin, map_reason, ChatgptAuthTokensRefresh, other, format!, from_value, timeout）。

fn default() -> Self

作用：提供创建默认连接会话状态的快捷方式。它等同于创建一个全新的、还没初始化的连接状态。

数据流：没有输入 → 调用 ConnectionSessionState::new → 返回带有 RPC 闸门、但尚未初始化的会话状态。

调用关系：这是 Rust 的 Default 约定入口，外部代码需要默认值时会走这里；真正建对象的活交给 ConnectionSessionState::new。

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

fn new() -> Self

作用：创建一条新连接的会话状态。这里会准备一扇 RPC 闸门，用来在连接关闭时等待正在跑的请求收尾。

数据流：没有输入 → 新建 ConnectionRpcGate，并创建一个空的 OnceLock（只能成功写入一次的格子）保存初始化信息 → 返回新的 ConnectionSessionState。

调用关系：启动未初始化连接、默认构造、测试或连接建立流程都会用它。后续 Initialize 请求会把客户端信息填进这个状态。

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

fn initialized(&self) -> bool

作用：判断这条连接是否已经完成初始化。大多数业务请求必须先初始化，不能一连上就乱发。

数据流：读取内部 OnceLock → 如果里面已有初始化信息就返回 true，否则返回 false → 不修改状态。

调用关系：Initialize 之后的请求分发会用它拦截未登记的连接；如果没初始化，MessageProcessor::dispatch_initialized_client_request 会返回错误。

调用图：被 1 处调用（initialize）；外部调用 1 个（get）。

fn experimental_api_enabled(&self) -> bool

作用：判断这条连接是否声明允许使用实验性 API。实验性 API 就是还不稳定、需要客户端明确同意的功能。

数据流：读取初始化信息 → 如果已初始化并且 experimental_api_enabled 为 true，就返回 true；否则返回 false → 不修改状态。

调用关系：初始化后的请求分发会用它检查某些实验性请求。没开权限却调用实验功能时，请求会被拒绝。

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

fn opted_out_notification_methods(&self) -> HashSet<String>

作用：取出客户端不想接收的通知方法列表。这样服务端可以少发客户端明确不要的通知。

数据流：读取初始化信息 → 如果有，就复制其中的 opted_out_notification_methods；如果没有，就返回空集合 → 不修改状态。

调用关系：它给需要决定“某条通知该不该发”的流程使用。这里不做发送，只提供连接自己的偏好。

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

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

作用：返回这条连接登记过的客户端名字，比如某个编辑器或嵌入端名称。服务端可用它做日志、追踪或细分行为。

数据流：读取初始化信息 → 有客户端名就返回字符串引用，没有初始化就返回 None → 不修改状态。

调用关系：追踪 span、远程控制和初始化后请求处理会读取它，用来知道当前请求来自哪类客户端。

调用图：被 2 处调用（client_name, typed_request_span）；外部调用 1 个（get）。

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

作用：返回客户端版本号。服务端可以据此记录问题、兼容不同版本客户端。

数据流：读取初始化信息 → 有版本就返回字符串引用，没初始化就返回 None → 不修改状态。

调用关系：请求追踪和线程/回合处理会用到它，方便把某次操作和客户端版本联系起来。

调用图：被 2 处调用（client_version, typed_request_span）；外部调用 1 个（get）。

fn request_attestation(&self) -> bool

作用：判断客户端是否要求请求安全证明。可以理解为客户端问：“这次服务端操作能不能带上可信身份证明？”

数据流：读取初始化信息 → 如果已初始化且 request_attestation 为 true，就返回 true；否则返回 false → 不修改状态。

调用关系：连接初始化成功后，MessageProcessor::connection_initialized 和相关线程处理会用这个值设置连接能力。

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

fn initialize(&self, session: InitializedConnectionSessionState) -> Result<(), ()>

作用：把初始化信息写入连接状态，而且只允许写一次。这样一条连接不会被反复改身份。

数据流：进去的是 InitializedConnectionSessionState → 尝试放进 OnceLock → 成功返回 Ok，若之前已经初始化过则返回 Err。

调用关系：InitializeRequestProcessor 处理客户端 Initialize 请求时会调用它。之后其他请求再通过各种读取方法拿到这些会话信息。

调用图：被 1 处调用（initialize）；外部调用 1 个（set）。

fn new(args: MessageProcessorArgs) -> Self

作用：搭建整个请求处理器，把所有子处理器、线程管理器、插件、技能、认证刷新、文件监听等零件装配好。它是 app-server 请求系统开工前的总组装步骤。

数据流：进去的是 MessageProcessorArgs，里面有配置、认证、数据库、输出通道、环境管理器等共享资源 → 创建 ThreadManager、SkillsWatcher、各种 RequestProcessor，并把外部认证刷新桥注册到 AuthManager → 返回一个可处理各类客户端请求的 MessageProcessor。

调用关系：app-server 启动、测试构造和主运行流程会调用它。它自己不处理具体请求，而是把后面 MessageProcessor::handle_initialized_client_request 要用到的各个专门处理器先准备好。

调用图：调用 27 个内部函数（new, new, new, new, new, new, new, new, new, new (+15 more)）；被 4 处调用（start_uninitialized, build_test_processor, run_main_with_transport_options, run_main）；外部调用 11 个（clone, new, new_cyclic, new, new, new, new, default, default, thread_store_from_config (+1 more)）。

fn clear_runtime_references(&self)

作用：清掉运行期的一些外部引用，帮助关闭或重载时断开长生命周期资源。比如取消外部认证桥、停止应用列表和技能监听。

数据流：读取自身持有的 account_processor、apps_processor、skills_watcher → 分别调用清理或 shutdown → 不返回数据，但会让这些后台引用停止继续工作。

调用关系：通常在进程收尾或运行环境重置时调用。它把清理动作交给对应子模块，而不是自己逐个处理细节。

调用图：调用 2 个内部函数（clear_external_auth, shutdown）。

async fn process_request(
        self: &Arc<Self>,
        connection_id: ConnectionId,
        request: JSONRPCRequest,
        transport: &AppServerTransport,
        session: Arc<ConnectionSession

作用：处理从传输层收到的一条 JSON-RPC 请求。这是普通网络/套接字客户端请求进入业务系统的入口。

数据流：进去的是连接 ID、原始 JSONRPCRequest、传输信息和连接会话 → 创建请求 ID、追踪上下文，把 JSON 请求解析成 ClientRequest → 调用 MessageProcessor::handle_client_request；如果出错，就通过 outgoing 发 JSON-RPC 错误响应。

调用关系：传输层收到客户端请求时会调用它。它先用 deserialize_client_request 翻译格式，再用 MessageProcessor::run_request_with_context 包上追踪上下文，最后交给共享的请求处理路径。

调用图：调用 4 个内部函数（request_span, handle_client_request, deserialize_client_request, new）；外部调用 3 个（clone, run_request_with_context, trace!）。

async fn process_client_request(
        self: &Arc<Self>,
        connection_id: ConnectionId,
        request: ClientRequest,
        session: Arc<ConnectionSessionState>,
        outbound_initializ

作用：处理进程内客户端传来的已解析请求。它跳过 JSON 反序列化，但仍然走和网络请求一样的业务规则。

数据流：进去的是连接 ID、ClientRequest、会话状态和 outbound_initialized 标记 → 生成请求上下文和追踪信息 → 调用 MessageProcessor::handle_client_request；失败时发送错误。

调用关系：嵌入式或同进程调用者会用它。它和 MessageProcessor::process_request 最终都会汇合到 MessageProcessor::handle_client_request，保证行为一致。

调用图：调用 3 个内部函数（typed_request_span, handle_client_request, new）；外部调用 4 个（clone, id, run_request_with_context, trace!）。

async fn process_notification(&self, notification: JSONRPCNotification)

作用：处理客户端发来的 JSON-RPC 通知。当前服务端并不期待客户端通知，所以这里只记录日志。

数据流：进去的是 JSONRPCNotification → 写一条 info 日志 → 不返回业务结果，也不改动状态。

调用关系：传输层收到通知而不是请求时会调用它。因为现在没有通知业务，它不会再分发给其他处理器。

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

async fn process_client_notification(&self, notification: ClientNotification)

作用：处理进程内客户端发来的已解析通知。当前也只是记录下来，不做进一步动作。

数据流：进去的是 ClientNotification → 写一条 info 日志 → 没有响应，也不改变系统状态。

调用关系：这是进程内通知路径，对应 MessageProcessor::process_notification 的 typed 版本。现在两者都只是观察和记录。

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

async fn run_request_with_context(
        outgoing: Arc<OutgoingMessageSender>,
        request_context: RequestContext,
        request_fut: F,
    )

作用：给一次请求挂上上下文和追踪信息再运行。可以把它理解成给包裹贴上快递单，后面日志和响应都知道这是谁的请求。

数据流：进去的是输出通道、RequestContext 和一个未来要执行的异步任务 → 先把上下文登记到 outgoing，再在追踪 span 里执行这个任务 → 任务完成后没有额外返回值。

调用关系：MessageProcessor::process_request 和 MessageProcessor::process_client_request 都用它包住真正处理逻辑。它不决定业务，只负责上下文登记和 tracing（追踪日志链路）。

调用图：调用 1 个内部函数（span）；外部调用 2 个（instrument, clone）。

fn thread_created_receiver(&self) -> broadcast::Receiver<ThreadId>

作用：提供一个订阅入口，让别的地方能收到“新线程被创建了”的通知。这里的线程是对话/工作线程，不是操作系统线程。

数据流：读取 thread_processor → 向它要一个 broadcast Receiver（广播接收器，多个订阅者都能收到消息）→ 返回给调用者。

调用关系：需要监听新线程事件的组件会调用它。真正维护事件源的是 ThreadRequestProcessor。

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

async fn send_initialize_notifications_to_connection(
        &self,
        connection_id: ConnectionId,
    )

作用：给某一条连接单独发送初始化后的通知。比如新客户端刚登记完，需要把当前状态补发给它。

数据流：进去的是 connection_id → 转交 initialize_processor 发送只针对这条连接的初始化通知 → 不直接返回业务数据。

调用关系：连接初始化流程或 websocket 特定流程会用它。实际通知内容由 InitializeRequestProcessor 负责。

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

async fn connection_initialized(
        &self,
        connection_id: ConnectionId,
        request_attestation: bool,
    )

作用：告诉线程系统：某条连接已经初始化好了，并说明它有什么能力。比如是否要求安全证明。

数据流：进去的是连接 ID 和 request_attestation 标记 → 包装成 ConnectionCapabilities → 调用 thread_processor.connection_initialized 更新连接能力。

调用关系：外部连接流程确认初始化完成时会调用它。MessageProcessor::handle_client_request 在处理 Initialize 时也会做类似动作。

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

async fn send_initialize_notifications(&self)

作用：向所有相关连接发送初始化通知。用于整体初始化后同步当前服务端状态。

数据流：没有额外输入 → 调用 initialize_processor.send_initialize_notifications → 通知被排入输出通道。

调用关系：启动或初始化阶段会用它。它只做转发，通知怎么组织由 InitializeRequestProcessor 决定。

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

async fn try_attach_thread_listener(
        &self,
        thread_id: ThreadId,
        connection_ids: Vec<ConnectionId>,
    )

作用：尝试把一些连接挂到某个线程的事件监听上。这样这些客户端能继续收到该线程的后续消息。

数据流：进去的是 thread_id 和一组 connection_id → 转交 thread_processor 尝试建立监听关系 → 不直接产出响应数据。

调用关系：恢复连接、重新订阅线程或多连接同步时会用到它。具体判断线程是否存在、能否监听由 ThreadRequestProcessor 做。

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

async fn drain_background_tasks(&self)

作用：等待线程相关后台任务尽量跑完。关闭或测试时常需要这个动作，避免任务还没收尾进程就退出。

数据流：没有输入 → 调用 thread_processor.drain_background_tasks → 等待后台任务排空或完成。

调用关系：收尾流程会调用它。MessageProcessor 不直接知道有哪些后台任务，交给 ThreadRequestProcessor 管。

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

async fn cancel_active_login(&self)

作用：取消当前正在进行的登录流程。用户关闭窗口或退出时，不应该让登录流程继续悬着。

数据流：没有输入 → 调用 account_processor.cancel_active_login → 正在进行的登录尝试会被取消。

调用关系：关闭或用户主动取消登录时会走这里。真正知道登录状态的是 AccountRequestProcessor。

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

async fn clear_all_thread_listeners(&self)

作用：清掉所有线程监听关系。通常用于断开连接或整体清理，避免已经不存在的客户端继续被当成监听者。

数据流：没有输入 → 调用 thread_processor.clear_all_thread_listeners → 线程监听表被清空。

调用关系：清理阶段使用。它把实际监听状态维护交给 ThreadRequestProcessor。

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

async fn shutdown_threads(&self)

作用：关闭所有线程相关活动。用于服务端退出时让对话、后台终端等线程资源停止工作。

数据流：没有输入 → 调用 thread_processor.shutdown_threads → 线程系统进入关闭流程。

调用关系：进程收尾时调用。MessageProcessor 只是统一出口，具体关闭顺序由 ThreadRequestProcessor 负责。

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

async fn connection_closed(
        &self,
        connection_id: ConnectionId,
        session_state: &ConnectionSessionState,
    )

作用：处理一条客户端连接断开后的清理工作。它会等待这条连接上的 RPC 请求收尾，然后通知各个子系统把与这条连接有关的东西删掉。

数据流：进去的是 connection_id 和该连接的会话状态 → 最多等 30 秒让 rpc_gate 里的请求结束；超时就记警告 → 依次通知 outgoing、文件、命令执行、进程执行、线程处理器清理该连接。

调用关系：传输层发现连接关闭时会调用它。它把连接关闭事件广播给所有会持有连接资源的处理器，避免文件监听、命令进程或线程订阅泄漏。

调用图：调用 4 个内部函数（connection_closed, connection_closed, connection_closed, connection_closed）；外部调用 2 个（timeout, warn!）。

fn subscribe_running_assistant_turn_count(&self) -> watch::Receiver<usize>

作用：订阅当前正在运行的助手回合数量。外部可以用它显示“现在有几个 AI 回答正在跑”。

数据流：没有输入 → 向 thread_processor 要一个 watch Receiver（只保存最新值的观察通道）→ 返回这个接收器。

调用关系：状态展示或监控组件会调用它。计数的维护在 ThreadRequestProcessor 内部。

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

async fn process_response(&self, response: JSONRPCResponse)

作用：处理客户端发回来的独立响应。常见场景是服务端之前反向向客户端发了请求，现在客户端把结果回来了。

数据流：进去的是 JSONRPCResponse → 记录日志，取出 id 和 result → 调用 outgoing.notify_client_response 唤醒等待这次结果的服务端任务。

调用关系：例如 ExternalAuthRefreshBridge::refresh 发起 token 刷新请求后，就需要这类响应回来。这里把响应交还给 OutgoingMessageSender 管的等待者。

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

async fn process_error(&self, err: JSONRPCError)

作用：处理客户端发回来的 JSON-RPC 错误。也就是服务端向客户端提问，客户端回答“失败了”。

数据流：进去的是 JSONRPCError → 记录错误日志 → 用错误里的 id 和 error 通知 outgoing 中等待结果的任务。

调用关系：和 MessageProcessor::process_response 是一对。它不自己修复错误，只把错误送回原先等待客户端回复的那段逻辑。

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

async fn handle_client_request(
        self: &Arc<Self>,
        connection_request_id: ConnectionRequestId,
        codex_request: ClientRequest,
        session: Arc<ConnectionSessionState>,

作用：处理一条已经变成 ClientRequest 的请求，并专门把 Initialize 请求拎出来先办。初始化像登记入住，没登记前不能使用大多数服务。

数据流：进去的是连接请求 ID、ClientRequest、会话状态、可选的 outbound 初始化标记和请求上下文 → 如果是 Initialize，就调用 initialize_processor.initialize，并在成功后通知 thread_processor 连接能力；如果不是 Initialize，就转给 MessageProcessor::dispatch_initialized_client_request → 返回成功或 JSON-RPC 错误。

调用关系：MessageProcessor::process_request 和 MessageProcessor::process_client_request 都调用它。它是“初始化请求”和“普通已初始化请求”的分岔口。

调用图：调用 3 个内部函数（dispatch_initialized_client_request, initialize, connection_initialized）；被 2 处调用（process_client_request, process_request）。

async fn dispatch_initialized_client_request(
        self: &Arc<Self>,
        connection_request_id: ConnectionRequestId,
        codex_request: ClientRequest,
        session: Arc<ConnectionSession

作用：把已经初始化后的请求排队并安排执行。它会先检查连接是否初始化、实验功能是否允许，再决定请求是否需要串行排队。

数据流：进去的是连接请求 ID、ClientRequest、会话状态和请求上下文 → 未初始化就报错；实验 API 未开启也报错；通过后记录 initialized request，并把真正处理动作包装成 QueuedInitializedRequest → 如果请求有序列化范围，就放进对应队列；否则直接 spawn 成异步任务。

调用关系：MessageProcessor::handle_client_request 处理非 Initialize 请求时调用它。它最终会安排 MessageProcessor::handle_initialized_client_request 执行业务，并在出错时通过 outgoing 发错误。

调用图：调用 6 个内部函数（invalid_request, span, track_initialized_request, new, from_scope, enqueue）；被 1 处调用（handle_client_request）；外部调用 6 个（clone, experimental_reason, serialization_scope, clone, experimental_required_message, spawn）。

async fn handle_initialized_client_request(
        self: Arc<Self>,
        connection_request_id: ConnectionRequestId,
        codex_request: ClientRequest,
        request_context: RequestContext,

作用：这是最大的请求分发开关：根据 ClientRequest 的具体种类，把活转交给配置、文件、线程、插件、登录、搜索、命令执行等专门处理器。它像服务大厅的总服务台，看号码牌后把人带到对应窗口。

数据流：进去的是连接请求 ID、具体 ClientRequest、请求上下文、客户端名和版本 → 按请求枚举逐项匹配，调用对应 processor 的方法 → 如果子处理器返回响应，就用 outgoing.send_response_as 发回客户端；如果返回 None，表示这类请求会异步通知或无需立即响应；如果出错，就发送错误响应。

调用关系：它只会在连接已初始化并通过 MessageProcessor::dispatch_initialized_client_request 安排后运行。它本身不做文件读写、登录、线程执行等细活，而是把每类请求交给 FsRequestProcessor、AccountRequestProcessor、ThreadRequestProcessor、TurnRequestProcessor 等对应模块。

调用图：调用 120 个内部函数（cancel_login_account, get_account, get_account_rate_limits, get_account_token_usage, get_auth_status, login_account, logout_account, send_add_credits_nudge_email, apps_list, collaboration_mode_list (+15 more)）；外部调用 4 个（id, consume_account_rate_limit_reset_credit, thread_delete, panic!）。

fn resolve_request_cwd(cwd: Option<PathBuf>) -> Result<Option<AbsolutePathBuf>, JSONRPCErrorError>

作用：把请求里可选的当前工作目录，也就是命令应该在哪个文件夹里运行，转换成系统内部认可的绝对路径。如果路径不合法，它会给出 JSON-RPC 错误；JSON-RPC 可以理解成前后端用 JSON 传请求和回复的一套规则。

数据流：输入是一个可能为空的路径。它先把路径按本机系统规则做规范化，再尝试转成绝对路径；如果没有传路径，就保持为空；如果转换失败，就产出“invalid cwd”这样的请求错误。输出是一个可选的 AbsolutePathBuf，也就是已经确认过的绝对路径，不会改动外部状态。

调用关系：它是各类请求处理器的前置清洗步骤。后面的线程、命令或环境相关流程需要知道“在哪个目录办事”，就可以先用它把用户输入变成可靠路径；它不再把工作交给别的本文件函数，只调用底层路径工具和错误包装函数。

fn resolve_turn_environment_selections(
    thread_manager: &ThreadManager,
    environments: Option<Vec<TurnEnvironmentParams>>,
) -> Result<Option<Vec<TurnEnvironmentSelection>>, JSONRPCErrorError>

作用：把一次对话回合里指定的运行环境列表整理成核心系统能理解的形式，并确认这些环境真的可用。运行环境可以理解成“任务要在哪台机器或哪个沙盒、哪个目录里执行”。

数据流：输入是线程管理器和一个可选的环境参数列表。没有传环境时，它直接返回空；传了环境时，它逐个读取 environment_id 和 cwd，把 cwd 检查成绝对的 POSIX 或 Windows 路径 URI，然后组装成 TurnEnvironmentSelection 列表。最后它调用 thread_manager.validate_environment_selections 做统一校验；校验通过就返回整理好的列表，失败就返回请求错误。

调用关系：它位于“用户准备开始或控制一个回合”之前。请求处理器先用它把前端传来的环境选择翻译成核心层认识的结构，再交给 ThreadManager 校验；其中 validate_environment_selections 是真正判断环境组合是否允许的关口，with_capacity 只是提前按数量准备列表空间，减少重复分配。

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

fn resolve_runtime_workspace_roots(workspace_roots: Vec<AbsolutePathBuf>) -> Vec<AbsolutePathBuf>

作用：清理运行时工作区根目录列表，把重复的目录去掉，同时保留原来的顺序。工作区根目录可以理解成这次任务允许关注的文件夹边界。

数据流：输入是一串已经是绝对路径的工作区目录。它从空列表开始，按顺序检查每个目录：如果前面没出现过，就加入结果；如果已经有了，就跳过。输出是一串去重后的目录列表，不修改原输入之外的任何状态。

调用关系：它通常作为请求进入核心逻辑前的整理步骤。后续配置、线程启动或运行环境设置可以拿到一份更干净的工作区列表，避免同一个目录被重复处理；它只依赖标准列表创建动作，不调用项目里的复杂模块。

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

fn build_api_turns_from_rollout_items(items: &[RolloutItem]) -> Vec<Turn>

作用：把底层保存的对话流水记录，转换成接口要返回给客户端的“回合”列表。这里的 rollout item 可以理解成系统保存的一条条历史事件，turn 则是界面更容易展示的一轮对话。

数据流：输入是一组 RolloutItem 历史项。它先创建 ThreadHistoryBuilder，也就是专门拼装对话历史的小工具；然后逐条检查历史项，只把 is_persisted_rollout_item 判断为需要长期保存的项交给 builder 处理；最后 builder.finish 产出 Vec<Turn>，也就是整理好的回合列表。它不改动原始历史，只生成一份面向 API 的结果。

调用关系：它连接“内部存档格式”和“外部接口格式”。线程读取、恢复或摘要相关流程需要把保存的历史展示给客户端时，会用这种转换；它把过滤判断交给外部的 is_persisted_rollout_item，把具体拼装工作交给 ThreadHistoryBuilder。

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

fn environment_selection_error(err: CodexErr) -> JSONRPCErrorError

作用：这个函数专门把环境选择验证失败的错误，转换成 JSON-RPC 返回格式。调用它的人不用关心内部错误该怎么对外表达，只要把 CodexErr 交进来就行。

数据流：进去的是一个 CodexErr，也就是服务器内部表示错误的值。函数先判断它是不是 InvalidRequest：如果是，就把里面的提示文字变成“请求无效”的 JSON-RPC 错误；如果不是，就用 format! 拼出一段“验证环境选择失败”的说明，再变成“内部错误”的 JSON-RPC 错误。出来的是一个 JSONRPCErrorError，供服务器直接返回给客户端。

调用关系：它位于请求处理流程的错误出口附近：前面的代码负责验证环境选择，一旦得到 CodexErr，就会交给这个函数翻译成客户端看得懂的 JSON-RPC 错误。函数内部只额外使用 format! 来拼接错误说明，不再把工作交给更复杂的流程。

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

fn skills_to_info(
    skills: &[codex_core::skills::SkillMetadata],
    disabled_paths: &HashSet<AbsolutePathBuf>,
) -> Vec<codex_app_server_protocol::SkillMetadata>

作用：把内部使用的技能资料，转换成客户端协议里要返回的技能资料。它还会顺手标出这个技能现在是启用还是禁用。

数据流：输入是一组内部技能元数据，以及一组被禁用的技能文件路径。函数逐个查看技能，把名称、描述、界面展示信息、依赖工具、路径、作用范围等字段搬到协议对象里；如果技能路径出现在禁用列表里，就把 enabled 标成 false。输出是一组客户端可以直接收到的技能信息。

调用关系：它是技能列表返回前的“翻译工”。上游拿到的是核心层的技能对象，发给客户端前需要经过它改成 app-server 协议格式；它内部主要只是遍历列表，不再把工作交给复杂组件。

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

fn hooks_to_info(hooks: &[codex_hooks::HookListEntry]) -> Vec<HookMetadata>

作用：把内部的钩子条目转换成客户端能读懂的钩子信息。钩子可以理解成“某个事件发生时自动执行的动作”。

数据流：输入是一组内部钩子条目。函数逐个复制关键字段，比如事件名、处理方式、匹配条件、命令、超时时间、来源、插件编号、是否启用、是否受管理、信任状态等。输出是一组协议层的 HookMetadata。

调用关系：CatalogRequestProcessor::hooks_list_response 在列出钩子后会调用它。它处在“核心钩子系统已经算完结果，准备发给客户端”这一步。

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

fn errors_to_info(
    errors: &[codex_core::skills::SkillError],
) -> Vec<codex_app_server_protocol::SkillErrorInfo>

作用：把技能加载时产生的内部错误，转换成客户端能显示的错误信息。

数据流：输入是一组技能错误，每个错误包含出错路径和错误文字。函数逐个提取路径和消息，生成协议里的 SkillErrorInfo。输出是一组可以随技能列表一起返回的错误说明。

调用关系：它是技能列表流程里的错误翻译器。技能管理器发现问题后，响应层用它把错误整理成客户端格式。

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

fn new(
        outgoing: Arc<OutgoingMessageSender>,
        skills_watcher: Arc<SkillsWatcher>,
        auth_manager: Arc<AuthManager>,
        thread_manager: Arc<ThreadManager>,
        config: Ar

作用：创建一个 CatalogRequestProcessor，并把它后面处理请求需要用到的各个工具都装进去。

数据流：输入包括发消息用的 outgoing、监控技能目录的 skills_watcher、认证管理器、线程管理器、配置对象、配置管理器、工作区设置缓存。函数只是把这些东西保存到结构体字段里。输出是一个可以处理目录类请求的新处理器。

调用关系：它在系统组装请求处理器时被调用。后续所有列表、写配置、通知客户端的函数，都会使用这里保存下来的这些共享组件。

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

async fn skills_list(
        &self,
        params: SkillsListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理客户端的“列出技能”请求。它是对外入口，负责把内部响应包成通用客户端响应。

数据流：输入是 SkillsListParams，里面可能有要查询的目录和是否强制刷新。函数把实际工作交给 CatalogRequestProcessor::skills_list_response，拿到技能列表响应后转成 ClientResponsePayload，并包在 Some 里返回；如果出错就返回 JSON-RPC 错误。

调用关系：它由 handle_initialized_client_request 在收到对应请求时调用。它本身不算技能，而是把活儿交给 CatalogRequestProcessor::skills_list_response。

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

async fn hooks_list(
        &self,
        params: HooksListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理客户端的“列出钩子”请求，把项目里会自动触发的动作列出来。

数据流：输入是 HooksListParams，通常包含要查看的目录。函数调用 CatalogRequestProcessor::hooks_list_response 获取结果，再转换成统一的客户端响应格式返回。

调用关系：它由 handle_initialized_client_request 分发调用。真正解析配置、插件和钩子的工作在 CatalogRequestProcessor::hooks_list_response 里完成。

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

async fn skills_config_write(
        &self,
        params: SkillsConfigWriteParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理客户端修改技能启用状态的请求，比如打开或关闭某个技能。

数据流：输入是 SkillsConfigWriteParams，包含技能路径或技能名，以及目标启用状态。函数调用 CatalogRequestProcessor::skills_config_write_response_inner 写入配置，成功后把结果转成通用响应。

调用关系：它由 handle_initialized_client_request 在收到技能配置写入请求时调用。它是外层包装，具体校验参数、写配置、清缓存都交给内部函数。

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

async fn skills_extra_roots_set(
        &self,
        params: SkillsExtraRootsSetParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理客户端设置“额外技能目录”的请求。额外技能目录就是除了默认位置以外，也去这些地方找技能。

数据流：输入是 SkillsExtraRootsSetParams，里面是额外目录列表。函数把它交给 CatalogRequestProcessor::skills_extra_roots_set_response，成功后返回一个空的成功响应。

调用关系：它由 handle_initialized_client_request 调用。真正更新 watcher、技能管理器并通知客户端的动作在内部响应函数里。

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

async fn model_list(
        &self,
        params: ModelListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理客户端的“列出可用模型”请求。模型就是系统可以调用的 AI 模型选项。

数据流：输入是 ModelListParams，可能包含分页大小、游标和是否包含隐藏模型。函数把线程管理器和参数传给 CatalogRequestProcessor::list_models，拿到分页后的模型列表，再转成客户端响应。

调用关系：它由 handle_initialized_client_request 分发调用。它不自己分页，而是把核心工作交给 CatalogRequestProcessor::list_models。

调用图：被 1 处调用（handle_initialized_client_request）；外部调用 1 个（list_models）。

async fn experimental_feature_list(
        &self,
        params: ExperimentalFeatureListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理客户端的“列出实验功能”请求，让客户端知道哪些新功能存在、处于什么阶段、当前是否启用。

数据流：输入是 ExperimentalFeatureListParams，可能包含分页和线程编号。函数调用 CatalogRequestProcessor::experimental_feature_list_response 生成列表，再包装成统一响应。

调用关系：它由 handle_initialized_client_request 调用。配置读取、线程配置选择、工作区插件限制判断，都在内部响应函数里完成。

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

async fn permission_profile_list(
        &self,
        params: PermissionProfileListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理客户端的“列出权限方案”请求。权限方案可以理解成预设的安全规则，比如只读、工作区内可写、完全访问。

数据流：输入是 PermissionProfileListParams，可能指定目录、分页大小和游标。函数调用 CatalogRequestProcessor::permission_profile_list_response 拿到列表，再转成客户端响应。

调用关系：它由 handle_initialized_client_request 调用。它只是外层接口，具体从配置层合成权限方案列表的工作由内部函数完成。

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

async fn collaboration_mode_list(
        &self,
        params: CollaborationModeListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理客户端的“列出协作模式”请求。协作模式表示线程或会话可以用哪些合作方式运行。

数据流：输入是 CollaborationModeListParams。函数把线程管理器和参数交给 CatalogRequestProcessor::list_collaboration_modes，拿到模式列表后包装成客户端响应。

调用关系：它由 handle_initialized_client_request 调用。实际读取线程管理器里可用协作模式的是 CatalogRequestProcessor::list_collaboration_modes。

调用图：被 1 处调用（handle_initialized_client_request）；外部调用 1 个（list_collaboration_modes）。

async fn mock_experimental_method(
        &self,
        params: MockExperimentalMethodParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理一个测试性质的实验接口。它主要用来验证实验接口链路是否能正常收发数据。

数据流：输入是 MockExperimentalMethodParams，里面有一个 value。函数调用 CatalogRequestProcessor::mock_experimental_method_inner，让内部函数原样回传这个值，再包装成客户端响应。

调用关系：它由 handle_initialized_client_request 调用。它像一条“回声测试”通道，实际回声逻辑在内部函数里。

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

async fn resolve_cwd_config(
        &self,
        cwd: &Path,
    ) -> Result<(AbsolutePathBuf, ConfigLayerStack), String>

作用：把一个目录变成绝对路径，并加载这个目录对应的配置层。配置层可以理解成多张叠在一起的设置表，比如全局设置、项目设置、目录设置。

数据流：输入是 cwd 路径。函数先用 relative_to_current_dir 把它转成绝对路径，再调用 load_config_layers_for_cwd 读取这个目录适用的配置层栈。输出是绝对目录和配置层栈；如果路径或配置加载失败，就把错误变成字符串返回。

调用关系：CatalogRequestProcessor::permission_profile_list_response 会用它按指定目录读取权限配置；技能列表流程也需要类似能力来按目录算配置。它是“目录到配置”的小关卡。

调用图：调用 2 个内部函数（load_config_layers_for_cwd, relative_to_current_dir）；被 1 处调用（permission_profile_list_response）。

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

作用：重新读取最新配置，避免用旧设置回答客户端。比如用户刚改了配置文件，这里会尽量拿到新版本。

数据流：输入是可选的备用工作目录 fallback_cwd。函数调用配置管理器的 load_latest_config；成功就返回新的 Config，失败就包装成 JSON-RPC 内部错误，告诉客户端服务器这边刷新配置失败。

调用关系：CatalogRequestProcessor::experimental_feature_list_response 和 CatalogRequestProcessor::skills_list_response 会调用它。它承担“先刷新配置，再回答问题”的步骤。

调用图：调用 1 个内部函数（load_latest_config）；被 2 处调用（experimental_feature_list_response, skills_list_response）。

async fn workspace_codex_plugins_enabled(
        &self,
        config: &Config,
        auth: Option<&CodexAuth>,
    ) -> bool

作用：判断当前工作区是否允许使用 Codex 插件。插件可能带来额外技能和钩子，所以这个开关会影响很多列表结果。

数据流：输入是当前配置和可选认证信息。函数调用 workspace_settings::codex_plugins_enabled_for_workspace，并带上工作区设置缓存；如果读取成功，就返回真实开关。如果读取失败，它会记录一条警告，并默认允许插件，避免因为设置服务出错就把功能关掉。

调用关系：CatalogRequestProcessor::experimental_feature_list_response、CatalogRequestProcessor::hooks_list_response 和 CatalogRequestProcessor::skills_list_response 都会调用它。它是这些流程里判断“插件相关内容能不能出现”的共同门卫。

调用图：调用 1 个内部函数（codex_plugins_enabled_for_workspace）；被 3 处调用（experimental_feature_list_response, hooks_list_response, skills_list_response）；外部调用 1 个（warn!）。

async fn list_models(
        thread_manager: Arc<ThreadManager>,
        params: ModelListParams,
    ) -> Result<ModelListResponse, JSONRPCErrorError>

作用：生成可用模型列表，并按客户端要求分页返回。分页就是一次只给一段，客户端下次用游标继续拿。

数据流：输入是线程管理器和 ModelListParams。函数先取得支持的模型列表，按 include_hidden 决定是否包含隐藏模型；然后根据 limit 和 cursor 算出起止位置，切出当前页；如果游标不是数字或超过总数，就返回请求错误。输出是当前页模型和下一个游标。

调用关系：CatalogRequestProcessor::model_list 会调用它。它位于模型查询流程的核心位置，负责把完整模型清单整理成客户端可逐页读取的结果。

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

async fn list_collaboration_modes(
        thread_manager: Arc<ThreadManager>,
        params: CollaborationModeListParams,
    ) -> Result<CollaborationModeListResponse, JSONRPCErrorError>

作用：从线程管理器里取出系统支持的协作模式，并转换成客户端协议格式。

数据流：输入是线程管理器和空参数 CollaborationModeListParams。函数调用线程管理器列出协作模式，把每个模式转换成协议对象，最后返回 CollaborationModeListResponse。

调用关系：CatalogRequestProcessor::collaboration_mode_list 会调用它。它是协作模式列表请求里的实际读取步骤。

async fn experimental_feature_list_response(
        &self,
        params: ExperimentalFeatureListParams,
    ) -> Result<ExperimentalFeatureListResponse, JSONRPCErrorError>

作用：生成实验功能列表，告诉客户端每个功能叫什么、处于什么阶段、默认是否开启、现在是否真正开启。

数据流：输入包含分页信息和可选线程编号。如果给了线程编号，函数先把字符串转成 ThreadId，找到线程，并按该线程配置刷新最新配置；否则加载全局最新配置。然后读取认证信息，判断工作区是否允许 Codex 插件。接着遍历内置功能清单 FEATURES，把每个功能变成 API 对象，并把插件开关限制也算进去。最后按 cursor 和 limit 分页输出；游标非法或越界会返回请求错误。

调用关系：CatalogRequestProcessor::experimental_feature_list 会调用它。它会用到 CatalogRequestProcessor::load_latest_config、CatalogRequestProcessor::workspace_codex_plugins_enabled，也可能通过配置管理器按线程加载配置。

调用图：调用 4 个内部函数（load_latest_config_for_thread, load_latest_config, workspace_codex_plugins_enabled, from_string）；被 1 处调用（experimental_feature_list）；外部调用 2 个（new, format!）。

async fn permission_profile_list_response(
        &self,
        params: PermissionProfileListParams,
    ) -> Result<PermissionProfileListResponse, JSONRPCErrorError>

作用：生成权限方案列表，把内置方案和用户在配置里写的自定义方案合在一起返回。

数据流：输入包含可选目录 cwd、分页游标和分页大小。如果指定了目录，它先通过 CatalogRequestProcessor::resolve_cwd_config 读取该目录的配置层；否则加载默认配置层。然后把最终生效配置转成 ConfigToml，从 permissions 里取出用户自定义方案，按 id 排序，再接到三个内置方案后面。最后按分页参数切出一页返回；游标非法或越界会报错。

调用关系：CatalogRequestProcessor::permission_profile_list 会调用它。它会把按目录解析配置的工作交给 CatalogRequestProcessor::resolve_cwd_config，自己负责合并内置和配置里的权限方案。

调用图：调用 2 个内部函数（load_config_layers, resolve_cwd_config）；被 1 处调用（permission_profile_list）；外部调用 3 个（from, format!, vec!）。

async fn mock_experimental_method_inner(
        &self,
        params: MockExperimentalMethodParams,
    ) -> Result<MockExperimentalMethodResponse, JSONRPCErrorError>

作用：实现实验接口的简单回声行为：收到什么值，就把什么值放进响应里。

数据流：输入是 MockExperimentalMethodParams，里面有 value。函数取出 value，放到 MockExperimentalMethodResponse 的 echoed 字段里。输出就是这个响应，不改动其他状态。

调用关系：CatalogRequestProcessor::mock_experimental_method 会调用它。它通常用于测试请求链路，而不是完成真实业务。

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

async fn skills_list_response(
        &self,
        params: SkillsListParams,
    ) -> Result<SkillsListResponse, JSONRPCErrorError>

作用：真正生成技能列表响应。它会按一个或多个目录分别计算可用技能、禁用状态和加载错误。

数据流：输入包含目录列表 cwds 和 force_reload。目录为空时使用当前配置里的默认目录。函数先刷新最新配置，读取认证信息，判断工作区是否允许插件；再拿到技能管理器、插件管理器和默认文件系统。随后它并发处理多个目录，但最多同时处理 5 个：每个目录先解析配置，如果失败就为该目录返回错误；成功后根据插件开关算出额外技能根目录，构造 SkillsLoadInput，让技能管理器加载技能。最后把错误和技能分别转成协议格式，按原目录顺序排好后返回。

调用关系：CatalogRequestProcessor::skills_list 会调用它。它会用 CatalogRequestProcessor::load_latest_config、CatalogRequestProcessor::workspace_codex_plugins_enabled，并在末尾使用技能和错误转换函数，把核心层结果变成客户端响应。

调用图：调用 2 个内部函数（load_latest_config, workspace_codex_plugins_enabled）；被 1 处调用（skills_list）；外部调用 2 个（iter, vec!）。

async fn skills_extra_roots_set_response(
        &self,
        params: SkillsExtraRootsSetParams,
    ) -> Result<SkillsExtraRootsSetResponse, JSONRPCErrorError>

作用：设置运行时额外技能目录，并通知客户端技能列表已经变化。

数据流：输入是 extra_roots。函数先让 skills_watcher 记录这些运行时额外目录，再让线程管理器里的技能管理器使用这些目录；随后通过 outgoing 发送 SkillsChanged 服务器通知。输出是一个空的成功响应。

调用关系：CatalogRequestProcessor::skills_extra_roots_set 会调用它。它是一个会改变服务器状态的请求处理函数，最后还会主动通知客户端刷新技能相关界面。

调用图：被 1 处调用（skills_extra_roots_set）；外部调用 1 个（SkillsChanged）。

async fn hooks_list_response(
        &self,
        params: HooksListParams,
    ) -> Result<HooksListResponse, JSONRPCErrorError>

作用：真正生成钩子列表响应，按目录列出配置和插件共同带来的自动动作。

数据流：输入是 HooksListParams。目录为空时使用默认当前目录。函数先取认证信息和插件管理器，然后逐个目录处理：先加载该目录配置；如果失败，就返回该目录的错误项。配置成功后，判断工作区和功能开关是否允许插件；允许时加载插件钩子来源和警告，不允许时使用空插件结果。最后调用 codex_hooks::list_hooks 按配置、信任设置、插件来源等算出钩子列表，再用 hooks_to_info 转成客户端格式，连同警告一起返回。

调用关系：CatalogRequestProcessor::hooks_list 会调用它。它会调用 CatalogRequestProcessor::workspace_codex_plugins_enabled 判断插件门槛，并把最终钩子条目交给 hooks_to_info 做格式转换。

调用图：调用 3 个内部函数（load_for_cwd, workspace_codex_plugins_enabled, hooks_to_info）；被 1 处调用（hooks_list）；外部调用 6 个（default, new, list_hooks, default, default, vec!）。

async fn skills_config_write_response_inner(
        &self,
        params: SkillsConfigWriteParams,
    ) -> Result<SkillsConfigWriteResponse, JSONRPCErrorError>

作用：真正写入技能开关配置。客户端可以按技能路径或技能名来启用、禁用某个技能，但二者必须只给一个。

数据流：输入包含 path、name 和 enabled。函数先检查参数：如果给了路径，就生成按路径设置技能的配置编辑；如果给了非空名称，就生成按名称设置技能的配置编辑；其他情况返回参数错误。然后用 ConfigEditsBuilder 把编辑写进 codex_home 下的配置。写成功后清掉插件和技能缓存，返回 effective_enabled；写失败则返回内部错误。

调用关系：CatalogRequestProcessor::skills_config_write 会调用它。它在写配置后会让插件管理器和技能管理器清缓存，这样后续列表请求不会继续看到旧状态。

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

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

作用：创建一个环境请求处理器，并把真正保存环境信息的 EnvironmentManager 放进去。别人之后就可以用这个处理器来处理环境相关请求。

数据流：进去的是一个共享的 EnvironmentManager（Arc 是一种安全共享同一个对象的包装）→ 函数把它存进新的 EnvironmentRequestProcessor 里 → 出来的是一个可以复用的请求处理器实例，没有额外改动外部状态。

调用关系：它在上层初始化请求处理模块时被调用，也就是 called by 里的 new。它不自己处理请求，只是先把后面要用的工具准备好。

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

async fn environment_add(
        &self,
        params: EnvironmentAddParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理客户端发来的“添加环境”请求。它把环境编号和执行服务器地址登记到环境管理器里，成功后给客户端一个成功响应。

数据流：进去的是 EnvironmentAddParams，里面有 environment_id 和 exec_server_url，同时函数读取自己保存的 environment_manager → 它调用 upsert_environment，把这个环境新增或覆盖更新；如果出错，就把错误转换成 JSON-RPC 的 invalid_request → 出来的是成功响应 EnvironmentAddResponse，或者一个会返回给客户端的错误。

调用关系：它在客户端已经初始化之后处理请求时被 handle_initialized_client_request 调用。它自己不直接保存数据，而是把真正的登记工作交给 EnvironmentManager；做完后再把结果包装成客户端能看懂的响应。

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

fn new(args: ExternalAgentConfigRequestProcessorArgs) -> Self

作用：创建一个外部代理配置请求处理器，把它后面要用的发消息工具、迁移服务、会话导入器、配置处理器等零件装好。

数据流：输入是一包启动参数，里面有消息发送器、线程管理器、配置管理器、状态数据库、Codex 主目录等信息。它用这些信息新建会话导入器和配置迁移服务，然后把所有依赖保存到结构体里。输出是一个可以处理检测、导入、读取历史请求的处理器对象。

调用关系：它通常在上层请求处理器初始化时被调用。之后客户端来的检测、导入、历史查询请求，都会落到这个对象的方法上。它内部调用其他组件的 new，并复制共享指针，目的是让后续异步任务也能安全使用这些组件。

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

async fn detect(
        &self,
        params: ExternalAgentConfigDetectParams,
    ) -> Result<ExternalAgentConfigDetectResponse, JSONRPCErrorError>

作用：扫描外部代理工具里有哪些东西可以迁移，比如配置、插件、会话、命令等，并把扫描结果返回给客户端。

数据流：输入是检测参数，例如是否包含用户主目录、要检查哪些当前工作目录。它把这些参数交给底层迁移服务检测。拿到内部格式的迁移项后，它逐个翻译成协议格式，也就是客户端能读懂的数据结构。输出是一份可迁移项目列表；如果扫描失败，就返回 JSON-RPC 错误。

调用关系：客户端发起“检测可导入内容”请求时，上层的 handle_initialized_client_request 会调用它。它把真正的扫描工作交给 migration_service.detect，自己主要负责参数传递、错误包装，以及把内部类型翻译成网络协议类型。

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

async fn import(
        &self,
        request_id: ConnectionRequestId,
        params: ExternalAgentConfigImportParams,
    ) -> Result<(), JSONRPCErrorError>

作用：执行一次外部配置导入，并持续告诉客户端导入进展。它还会处理慢任务，比如会话和插件导入，把它们放到后台继续完成。

数据流：输入是请求编号和导入参数，里面包含用户选择要迁移的项目。它先生成 import_id，判断是否需要刷新运行时配置，校验会话导入项，再调用 import_external_agent_config 导入除会话外的大部分内容。随后它向客户端发送响应和进度通知。如果还有插件或会话这种后台任务，它会启动异步任务继续导入，完成后汇总所有成功失败结果，必要时清缓存，并发送完成通知，还可能写入历史数据库。

调用关系：这是导入流程的总调度点，由 handle_initialized_client_request 在收到导入请求时调用。它会调用 validate_pending_session_imports、import_external_agent_config、send_import_progress、send_completed_import_notification 等函数；插件导入完成后会用 apply_plugin_outcome_to_item_result 整理结果；如果配置被改动，还会让 config_processor.handle_config_mutation 刷新运行状态。

调用图：调用 8 个内部函数（record_import_error, handle_config_mutation, import_external_agent_config, validate_pending_session_imports, apply_plugin_outcome_to_item_result, migration_items_need_runtime_refresh, send_completed_import_notification, send_import_progress）；被 1 处调用（handle_initialized_client_request）；外部调用 7 个（clone, new, new_v4, new, clone, join!, spawn）。

async fn read_import_histories(
        &self,
    ) -> Result<ExternalAgentConfigImportHistoriesReadResponse, JSONRPCErrorError>

作用：读取以前外部配置导入的历史记录，让客户端能展示“以前导入过什么、哪些成功、哪些失败”。

数据流：输入不需要额外参数，但它会读取处理器里保存的状态数据库句柄。它从数据库取出历史记录，再把数据库里的记录格式转换成协议格式。输出是一组历史记录；如果状态数据库不可用或读取失败，就返回内部错误。

调用关系：客户端请求查看导入历史时，由 handle_initialized_client_request 调用它。它依赖 state_db 保存过的记录，并使用 protocol_import_history 把数据库记录转换成客户端可用的响应数据。

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

fn validate_pending_session_imports(
        &self,
        params: &ExternalAgentConfigImportParams,
    ) -> (Vec<CoreSessionMigration>, Option<CoreImportItemResult>)

作用：在真正导入会话前先检查用户选择的会话是否还存在，并去掉重复项，避免后台导入时踩空或重复搬同一个会话。

数据流：输入是导入参数。它从迁移项里挑出 Sessions 类型，把里面的会话路径、工作目录、标题取出来。然后逐个问迁移服务：这个会话源文件是否能找到真实路径。找不到或出错就把失败原因记进结果；找到且没重复，就加入待导入列表。输出是待导入会话列表，以及一份“会话校验”的结果记录。

调用关系：它只在 import 的前半段使用。import 先靠它筛出靠谱的会话，马上把校验结果作为进度发给客户端；真正导入会话的工作稍后交给 ExternalAgentSessionImporter 在后台完成。

调用图：调用 2 个内部函数（external_agent_session_source_path, record_import_error）；被 1 处调用（import）；外部调用 4 个（new, new, new, format!）。

async fn import_external_agent_config(
        &self,
        params: ExternalAgentConfigImportParams,
    ) -> Result<CoreImportOutcome, JSONRPCErrorError>

作用：把客户端提交的迁移项目转换成底层迁移服务认识的格式，并执行配置类导入；会话项会被排除，因为会话有单独的后台导入流程。

数据流：输入是客户端协议里的导入参数。它过滤掉 Sessions 类型，把剩下每个迁移项的类型、描述、目录和详细信息都翻译成核心迁移服务的内部格式。然后调用 migration_service.import。输出是核心导入结果，里面包含已完成项目的成功失败信息，以及可能还要后台处理的插件导入任务；失败时输出 JSON-RPC 内部错误。

调用关系：它由 import 调用，是主导入流程里真正把配置、技能、插件清单、服务器配置等交给核心服务的桥梁。它不发送消息，也不写历史，只负责格式转换和调用底层 import。

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

async fn complete_pending_plugin_import(
        &self,
        pending_plugin_import: PendingPluginImport,
    ) -> Result<PluginImportOutcome, JSONRPCErrorError>

作用：完成一个还没真正装完的插件导入任务。插件可能需要额外步骤，所以主导入结束后会单独补做。

数据流：输入是一个待处理插件导入任务，里面有工作目录和插件详情。它把这些信息交给 migration_service.import_plugins。输出是插件导入结果，包括哪些插件成功、哪些产生错误；如果失败，就把错误包装成 JSON-RPC 错误。

调用关系：它在 import 启动的后台任务里被调用。每个 PendingPluginImport 都会经过它处理，结果再交给 apply_plugin_outcome_to_item_result 写进本次导入的项目结果里。

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

async fn send_import_progress(
    outgoing: &OutgoingMessageSender,
    import_id: &str,
    item_result: &CoreImportItemResult,
)

作用：给客户端发送一次“导入进度更新”，告诉它某一类项目现在成功了哪些、失败了哪些。

数据流：输入是消息发送器、导入编号和一个内部项目结果。它先把内部结果转换成协议里的 item_type_results，再包成 ExternalAgentConfigImportProgress 通知。输出不是普通返回值，而是通过 outgoing 向客户端发出服务器通知。

调用关系：import 在校验会话、完成普通导入项、完成后台会话或插件导入后都会调用它。它依赖 protocol_import_type_result 做格式转换，再调用 send_server_notification 把消息发出去。

调用图：调用 1 个内部函数（send_server_notification）；被 1 处调用（import）；外部调用 2 个（ExternalAgentConfigImportProgress, vec!）。

async fn send_completed_import_notification(
    outgoing: &OutgoingMessageSender,
    state_db: Option<&StateDbHandle>,
    import_id: String,
    item_results: &[CoreImportItemResult],
)

作用：发送“这次导入全部结束”的通知，并尽量把这次导入的结果写进历史数据库。

数据流：输入是消息发送器、可选的状态数据库、导入编号和所有项目结果。它先调用 completed_notification 汇总成最终通知；如果有状态数据库，就调用 record_completed_import_notification 写历史。写历史失败不会让导入失败，只会打警告日志。最后它把完成通知发给客户端。

调用关系：import 在没有后台任务时会直接调用它；有后台任务时，会在所有后台会话和插件导入结束后调用它。它位于整个导入流程的收尾位置，负责“存档”和“宣布完成”。

调用图：调用 3 个内部函数（send_server_notification, completed_notification, record_completed_import_notification）；被 1 处调用（import）；外部调用 2 个（ExternalAgentConfigImportCompleted, warn!）。

async fn record_completed_import_notification(
    state_db: &StateDbHandle,
    notification: &ExternalAgentConfigImportCompletedNotification,
) -> anyhow::Result<()>

作用：把一次导入完成通知里的成功和失败明细保存到状态数据库里，方便以后查历史。

数据流：输入是状态数据库句柄和完成通知。它从通知里拆出所有成功记录和失败记录，把协议里的字段转成数据库记录结构。然后调用数据库的 record_external_agent_config_import_completed 保存导入编号、成功列表和失败列表。输出是成功或失败的结果；失败会被上层记录成警告。

调用关系：它只由 send_completed_import_notification 调用。它不负责发消息，只负责把已经整理好的完成通知落库，让 read_import_histories 以后可以读出来。

调用图：被 1 处调用（send_completed_import_notification）；外部调用 1 个（record_external_agent_config_import_completed）。

fn protocol_import_history(
    record: codex_state::ExternalAgentConfigImportHistoryRecord,
) -> Result<ExternalAgentConfigImportHistory, JSONRPCErrorError>

作用：把数据库里的导入历史记录转换成客户端协议里的历史记录格式。

数据流：输入是一条数据库历史记录，里面有导入编号、完成时间、成功列表和失败列表。它分别转换成功记录和失败记录，再组合成 ExternalAgentConfigImportHistory。输出是客户端可返回的历史对象；如果某个项目类型无法解析，就返回错误。

调用关系：read_import_histories 读取数据库后会对每条记录使用它。它进一步依赖 protocol_import_success_record 和 protocol_import_failure_record 转换明细。

fn protocol_import_success_record(
    record: ExternalAgentConfigImportSuccessRecord,
) -> Result<ProtocolImportSuccess, JSONRPCErrorError>

作用：把一条数据库里的成功记录转换成客户端能理解的成功记录。

数据流：输入是数据库保存的成功记录，包括项目类型字符串、工作目录、来源和目标。它先把项目类型字符串解析成协议枚举，再原样带上目录、来源、目标。输出是 ProtocolImportSuccess；如果类型字符串不合法，就返回错误。

调用关系：它被 protocol_import_history 用来转换历史里的成功明细。项目类型解析工作交给 protocol_import_record_item_type。

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

fn protocol_import_failure_record(
    record: ExternalAgentConfigImportFailureRecord,
) -> Result<ProtocolImportFailure, JSONRPCErrorError>

作用：把一条数据库里的失败记录转换成客户端能理解的失败记录。

数据流：输入是数据库保存的失败记录，包括项目类型、错误类型、失败阶段、错误消息、工作目录和来源。它解析项目类型，并保留其他失败说明字段。输出是 ProtocolImportFailure；如果项目类型解析失败，就返回错误。

调用关系：它被 protocol_import_history 用来转换历史里的失败明细。和成功记录一样，它把项目类型解析交给 protocol_import_record_item_type。

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

fn protocol_import_record_item_type(
    item_type: String,
) -> Result<ExternalAgentConfigMigrationItemType, JSONRPCErrorError>

作用：把数据库里保存的项目类型字符串，重新变成协议里的项目类型枚举。枚举可以理解成一组固定选项，比如 Config、Plugins、Sessions。

数据流：输入是一个字符串形式的项目类型。它用 JSON 反序列化方式尝试把字符串转成 ExternalAgentConfigMigrationItemType。输出是项目类型枚举；如果字符串不是合法选项，就返回内部错误，并说明哪个类型解码失败。

调用关系：protocol_import_success_record 和 protocol_import_failure_record 都会调用它。它是历史记录从数据库格式回到协议格式时的“小翻译器”。

调用图：被 2 处调用（protocol_import_failure_record, protocol_import_success_record）；外部调用 2 个（String, from_value）。

fn completed_notification(
    import_id: String,
    item_results: &[CoreImportItemResult],
) -> ExternalAgentConfigImportCompletedNotification

作用：把多个零散的导入结果合并成一条最终完成通知，按项目类型归类，并按固定顺序排列。

数据流：输入是导入编号和一组内部项目结果。它逐个取出成功和失败记录，转换成协议格式；如果同一种项目类型出现多次，就把它们合并到同一个结果组里。最后按 Config、Skills、AgentsMd、Plugins 等固定顺序排序。输出是一条 ExternalAgentConfigImportCompletedNotification。

调用关系：send_completed_import_notification 在发完成通知和写历史前会调用它。它内部使用 protocol_migration_item_type、protocol_import_success、protocol_import_raw_error 来完成格式转换。

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

fn protocol_import_type_result(item_result: &CoreImportItemResult) -> ProtocolImportTypeResult

作用：把一个内部导入项目结果转换成一次进度通知里使用的协议结果。

数据流：输入是 CoreImportItemResult，里面有项目类型、成功列表和原始错误列表。它把项目类型转换成协议项目类型，把成功和失败分别转换成协议记录。输出是 ProtocolImportTypeResult。

调用关系：send_import_progress 调用它来生成进度通知。它负责单个项目结果的转换，而 completed_notification 负责多个项目结果的最终汇总。

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

fn protocol_import_success(
    success: &crate::config::external_agent_config::ExternalAgentConfigImportSuccess,
) -> ProtocolImportSuccess

作用：把内部的成功导入记录转换成客户端协议里的成功记录。

数据流：输入是一条内部成功记录，包括项目类型、工作目录、来源和目标。它转换项目类型，并复制其他展示用字段。输出是 ProtocolImportSuccess。

调用关系：protocol_import_type_result 和 completed_notification 都会间接使用它。它和 protocol_import_raw_error 是一对：一个处理成功，一个处理失败。

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

fn protocol_import_raw_error(raw_error: &CoreImportRawError) -> ProtocolImportFailure

作用：把内部的导入错误记录转换成客户端协议里的失败记录，让前端能展示失败原因。

数据流：输入是一条内部原始错误，包含项目类型、错误类型、失败阶段、消息、目录和来源。它转换项目类型，并保留错误说明。输出是 ProtocolImportFailure。

调用关系：protocol_import_type_result 和 completed_notification 都会用它处理失败项。它依赖 protocol_migration_item_type 做项目类型转换。

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

fn protocol_migration_item_type(
    item_type: CoreMigrationItemType,
) -> ExternalAgentConfigMigrationItemType

作用：把核心迁移服务使用的项目类型转换成客户端协议使用的项目类型。

数据流：输入是 CoreMigrationItemType，比如 Config、Plugins、Sessions。它用一一对应的 match 映射成 ExternalAgentConfigMigrationItemType。输出是协议项目类型。

调用关系：它是很多结果转换函数的公共小工具，被 completed_notification、protocol_import_type_result、protocol_import_success、protocol_import_raw_error 调用，保证内部类型和客户端类型始终对应。

调用图：被 4 处调用（completed_notification, protocol_import_raw_error, protocol_import_success, protocol_import_type_result）。

fn apply_plugin_outcome_to_item_result(
    item_result: &mut CoreImportItemResult,
    plugin_outcome: PluginImportOutcome,
)

作用：把插件导入的结果写进某个导入项目结果里，成功的记成功，失败的记错误。

数据流：输入是一个可修改的项目结果，以及插件导入结果。它遍历成功插件 ID，把每个插件记成一次成功；再遍历插件导入产生的原始错误，把它们记入失败列表。输出没有新对象，但会修改传入的 item_result。

调用关系：import 的后台插件导入流程会调用它。complete_pending_plugin_import 先拿到插件结果，然后它把结果整理进统一的 CoreImportItemResult，之后再由 send_import_progress 和完成通知发给客户端。

调用图：被 1 处调用（import）；外部调用 2 个（record_error, record_success）。

fn migration_items_need_runtime_refresh(items: &[ExternalAgentConfigMigrationItem]) -> bool

作用：判断这次导入是否会影响正在运行的配置缓存。如果会，就需要刷新，避免程序继续使用旧配置。

数据流：输入是用户选择的迁移项目列表。它检查里面是否包含配置、技能、MCP 服务器配置、钩子、命令或插件这几类会影响运行状态的东西。输出是布尔值：true 表示需要刷新，false 表示不需要。

调用关系：import 一开始会调用它。若结果为 true，导入完成主要配置后会调用 config_processor.handle_config_mutation，让运行中的系统重新感知配置变化。

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

fn new(
        auth_manager: Arc<AuthManager>,
        thread_manager: Arc<ThreadManager>,
        outgoing: Arc<OutgoingMessageSender>,
        config_manager: ConfigManager,
    ) -> Self

作用：创建一个 MCP 请求处理器，把它以后办事需要用到的几个“助手”保存起来，比如认证、线程、发消息和配置。

数据流：进去的是认证管理器、线程管理器、消息发送器和配置管理器 → 函数把它们装进 McpRequestProcessor 这个结构里 → 出来的是一个可以处理 MCP 请求的新对象，不额外做网络或磁盘操作。

调用关系：它在上层创建请求处理器时被调用。后面的登录、刷新、读资源、调工具等方法，都会依赖这里保存下来的这些组件。

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

async fn mcp_server_oauth_login(
        &self,
        params: McpServerOauthLoginParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理“给某个 MCP 服务器做 OAuth 登录”的客户端请求。OAuth 可以理解成跳转到网页授权，让这个应用拿到访问某个服务的许可。

数据流：进去的是登录参数，比如服务器名字、权限范围和超时时间 → 它把真正的工作交给 mcp_server_oauth_login_response → 拿到登录响应后包装成客户端能收的响应格式返回。

调用关系：它由 handle_initialized_client_request 在收到对应客户端请求时调用。它本身是外层入口，里面转给 mcp_server_oauth_login_response 做实际登录准备。

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

async fn mcp_server_refresh(
        &self,
        params: Option<()>,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理“刷新 MCP 服务器信息”的请求，让系统重新检查配置里的 MCP 服务。

数据流：进去的是一个可选但实际不用的参数 → 它调用 mcp_server_refresh_response 去排队执行刷新 → 成功后把空的刷新响应包装给客户端。

调用关系：它由 handle_initialized_client_request 调用，是刷新请求的门面；真正排队刷新由 mcp_server_refresh_response 完成。

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

async fn mcp_server_status_list(
        &self,
        request_id: &ConnectionRequestId,
        params: ListMcpServerStatusParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理“列出 MCP 服务器状态”的请求，比如有哪些服务器、工具、资源、认证状态等。

数据流：进去的是请求 ID 和查询参数 → 它把任务交给 list_mcp_server_status → 这个操作之后会异步发结果，所以这里正常返回时没有直接带数据。

调用关系：它由 handle_initialized_client_request 调用。它只是接住客户端请求，随后让 list_mcp_server_status 安排后台任务去收集状态并回传。

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

async fn mcp_resource_read(
        &self,
        request_id: &ConnectionRequestId,
        params: McpResourceReadParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理“读取 MCP 资源”的请求。资源可以理解成 MCP 服务器暴露出来的一份内容，比如文件、文档或某个服务数据。

数据流：进去的是请求 ID、服务器名、资源 URI，以及可选线程 ID → 它调用 read_mcp_resource 安排读取 → 结果会稍后通过消息发送器返回，所以这里不直接返回资源内容。

调用关系：它由 handle_initialized_client_request 在客户端要求读资源时调用。真正区分“有线程”和“无线程”两种读取方式的是 read_mcp_resource。

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

async fn mcp_server_tool_call(
        &self,
        request_id: &ConnectionRequestId,
        params: McpServerToolCallParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理“调用某个 MCP 工具”的请求。工具可以理解成外部服务提供的一个可执行动作，比如搜索、查询或生成内容。

数据流：进去的是请求 ID、线程 ID、服务器名、工具名、参数和元数据 → 它把实际调用交给 call_mcp_server_tool → 调用结果稍后异步发回客户端。

调用关系：它由 handle_initialized_client_request 调用，是客户端工具调用请求的外层入口；后续由 call_mcp_server_tool 找到线程并执行工具。

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

async fn mcp_server_refresh_response(
        &self,
        _params: Option<()>,
    ) -> Result<McpServerRefreshResponse, JSONRPCErrorError>

作用：真正安排 MCP 服务器刷新。它的重点不是立刻刷新完，而是把严格刷新任务放进队列。

数据流：进去的是一个未使用的参数 → 它调用 queue_strict_refresh，用线程管理器和配置管理器安排刷新 → 成功时返回一个空的刷新响应，失败时变成 JSON-RPC 错误。

调用关系：它被 mcp_server_refresh 调用。它把刷新这件事交给 crate::mcp_refresh::queue_strict_refresh，自己负责把底层错误翻译成客户端能理解的错误。

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

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

作用：读取最新配置，并把读取失败统一变成客户端请求能收到的错误。

数据流：进去的是一个可选的备用工作目录 → 它让 config_manager 加载最新配置 → 出来的是 Config；如果失败，就返回“重新加载配置失败”的内部错误。

调用关系：它被 mcp_server_oauth_login_response、list_mcp_server_status 和 read_mcp_resource 使用。凡是 MCP 操作需要知道最新服务器配置时，都会先经过它。

调用图：调用 1 个内部函数（load_latest_config）；被 3 处调用（list_mcp_server_status, mcp_server_oauth_login_response, read_mcp_resource）。

async fn load_thread(
        &self,
        thread_id: &str,
    ) -> Result<(ThreadId, Arc<CodexThread>), JSONRPCErrorError>

作用：根据字符串形式的线程 ID 找到真正的会话线程。这里的线程不是操作系统线程，更像一次对话或任务的上下文。

数据流：进去的是 thread_id 字符串 → 它先用 from_string 检查并转换成内部 ThreadId，再向 thread_manager 查找对应线程 → 出来的是规范化后的 ThreadId 和线程对象；ID 不合法或找不到都会变成无效请求错误。

调用关系：它被 list_mcp_server_status、read_mcp_resource 和 call_mcp_server_tool 调用。凡是请求明确绑定某个会话线程时，都要先通过它确认这个线程真的存在。

调用图：调用 1 个内部函数（from_string）；被 3 处调用（call_mcp_server_tool, list_mcp_server_status, read_mcp_resource）。

async fn mcp_server_oauth_login_response(
        &self,
        params: McpServerOauthLoginParams,
    ) -> Result<McpServerOauthLoginResponse, JSONRPCErrorError>

作用：准备并启动某个 MCP 服务器的 OAuth 登录流程，然后把用户需要打开的授权网址返回给客户端。

数据流：进去的是服务器名、权限范围和超时时间 → 它加载最新配置，找到对应 MCP 服务器，确认它是支持 OAuth 的 HTTP 类型服务器，算出要申请的权限范围，然后启动登录流程 → 出来的是 authorization_url；同时它开一个后台任务等待登录完成，并发送“登录完成或失败”的通知。

调用关系：它被 mcp_server_oauth_login 调用。它会用 load_latest_config 取配置，还会在后台用 tokio::spawn 等待授权结果，最后通过 outgoing 发送 McpServerOauthLoginCompleted 通知。

调用图：调用 1 个内部函数（load_latest_config）；被 1 处调用（mcp_server_oauth_login）；外部调用 4 个（clone, McpServerOauthLoginCompleted, format!, spawn）。

async fn list_mcp_server_status(
        &self,
        request_id: &ConnectionRequestId,
        params: ListMcpServerStatusParams,
    ) -> Result<(), JSONRPCErrorError>

作用：安排一次 MCP 服务器状态查询，并尽快把当前请求放行，避免客户端连接被长时间占住。

数据流：进去的是请求 ID 和状态查询参数 → 如果参数里有线程 ID，就先 load_thread 并按该线程的配置加载最新配置；否则加载全局最新配置；然后生成运行时 MCP 配置、认证信息和运行环境上下文 → 它启动后台任务 list_mcp_server_status_task，自己返回成功但不直接带状态数据。

调用关系：它被 mcp_server_status_list 调用。它负责把状态查询所需的配置、认证和环境准备好，再交给 list_mcp_server_status_task 异步执行并发送结果。

调用图：调用 4 个内部函数（load_latest_config_for_thread, load_latest_config, load_thread, new）；被 1 处调用（mcp_server_status_list）；外部调用 4 个（clone, list_mcp_server_status_task, clone, spawn）。

async fn list_mcp_server_status_task(
        outgoing: Arc<OutgoingMessageSender>,
        request_id: ConnectionRequestId,
        params: ListMcpServerStatusParams,
        mcp_config: codex_mcp::M

作用：在后台真正执行状态查询，并把结果按原请求 ID 发回客户端。

数据流：进去的是消息发送器、请求 ID、查询参数、MCP 配置、认证信息和运行环境 → 它调用 list_mcp_server_status_response 生成状态响应 → 最后用 outgoing.send_result 把成功结果或错误发回去。

调用关系：它由 list_mcp_server_status 启动为后台任务。它是“后台工人”，上接准备好的查询材料，下接 list_mcp_server_status_response 生成具体内容。

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

async fn list_mcp_server_status_response(
        request_id: String,
        params: ListMcpServerStatusParams,
        mcp_config: codex_mcp::McpConfig,
        auth: Option<CodexAuth>,
        runt

作用：把 MCP 服务器的原始状态快照整理成客户端要看的分页列表。

数据流：进去的是请求 ID、查询参数、MCP 配置、认证信息和运行环境 → 它按请求的详细程度收集状态快照，把服务器信息、工具、资源、资源模板和认证状态合并到同一份名单里，再按 cursor 和 limit 做分页 → 出来的是 ListMcpServerStatusResponse，包含本页数据和下一页游标；游标不合法会返回无效请求错误。

调用关系：它被 list_mcp_server_status_task 调用。它是状态查询里最核心的整理步骤，把底层收集到的多张“表”拼成客户端容易消费的一页结果。

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

async fn read_mcp_resource(
        &self,
        request_id: &ConnectionRequestId,
        params: McpResourceReadParams,
    ) -> Result<(), JSONRPCErrorError>

作用：安排读取某个 MCP 资源，并根据请求是否带线程 ID 选择合适的读取方式。

数据流：进去的是请求 ID、可选线程 ID、服务器名和资源 URI → 如果有线程 ID，它先 load_thread，然后让该线程读取资源；如果没有线程 ID，它加载全局配置，构造 MCP 运行配置和环境上下文，再无线程读取资源 → 两种路径都会启动后台任务，最后通过 send_mcp_resource_read_response 发回结果。

调用关系：它被 mcp_resource_read 调用。它会用 load_thread 或 load_latest_config 准备读取条件，并把最终回包交给 send_mcp_resource_read_response。

调用图：调用 3 个内部函数（load_latest_config, load_thread, new）；被 1 处调用（mcp_resource_read）；外部调用 4 个（clone, send_mcp_resource_read_response, clone, spawn）。

async fn send_mcp_resource_read_response(
        outgoing: Arc<OutgoingMessageSender>,
        request_id: ConnectionRequestId,
        result: anyhow::Result<serde_json::Value>,
    )

作用：把读取 MCP 资源得到的原始结果整理成客户端响应，并发送出去。

数据流：进去的是消息发送器、请求 ID 和一个可能成功也可能失败的 JSON 值结果 → 它先把底层错误转换成 JSON-RPC 错误，再把 JSON 值反序列化成 McpResourceReadResponse → 最后用 outgoing.send_result 发给对应请求。

调用关系：它被 read_mcp_resource 启动的后台读取流程使用。它是资源读取链路的最后一步，专门负责把“读到的东西或错误”变成正式回包。

async fn call_mcp_server_tool(
        &self,
        request_id: &ConnectionRequestId,
        params: McpServerToolCallParams,
    ) -> Result<(), JSONRPCErrorError>

作用：在指定会话线程里调用某个 MCP 工具，并把结果异步发回客户端。

数据流：进去的是请求 ID、线程 ID、服务器名、工具名、工具参数和元数据 → 它先 load_thread 确认线程存在，再用 with_mcp_tool_call_thread_id_meta 把线程 ID 写进元数据，然后启动后台任务调用 thread.call_mcp_tool → 出来时当前函数只表示任务已安排；真正结果会通过 outgoing.send_result 发回。

调用关系：它被 mcp_server_tool_call 调用。它依赖 load_thread 找到会话上下文，依赖 with_mcp_tool_call_thread_id_meta 补充元数据，然后把实际工具执行交给线程对象。

调用图：调用 2 个内部函数（load_thread, with_mcp_tool_call_thread_id_meta）；被 1 处调用（mcp_server_tool_call）；外部调用 3 个（clone, clone, spawn）。

fn with_mcp_tool_call_thread_id_meta(
    meta: Option<serde_json::Value>,
    thread_id: &str,
) -> Option<serde_json::Value>

作用：给 MCP 工具调用的元数据补上 threadId，方便下游知道这次工具调用属于哪个会话线程。

数据流：进去的是可选的 JSON 元数据和线程 ID 字符串 → 如果元数据本来是一个 JSON 对象，它就在里面加上 threadId；如果没有元数据，它新建一个只含 threadId 的对象；如果元数据是数组、字符串等非对象，就保持原样 → 出来的是补充后的可选 JSON 元数据。

调用关系：它被 call_mcp_server_tool 调用。它不负责执行工具，只是在调用前给请求贴一张“来自哪个线程”的标签。

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

fn map_additional_context(
    additional_context: Option<HashMap<String, AdditionalContextEntry>>,
) -> BTreeMap<String, CoreAdditionalContextEntry>

作用：把客户端附带的额外上下文，转换成核心对话引擎能识别的格式。这样用户输入之外的补充信息不会丢，也能标明它是可信的应用信息还是不可信来源。

数据流：进去的是一个可选的键值表，里面每项有内容和值的来源类型；函数把空值当成空表，把每个条目逐个改成核心协议里的条目类型；出来的是按 key 排好序的 BTreeMap，不改动外部状态。

调用关系：开始新回合和引导当前回合时都会调用它，也就是 turn_start_inner 和 turn_steer_inner 会先把客户端上下文翻译好，再交给核心线程。

调用图：被 2 处调用（turn_start_inner, turn_steer_inner）。

fn new(
        auth_manager: Arc<AuthManager>,
        thread_manager: Arc<ThreadManager>,
        outgoing: Arc<OutgoingMessageSender>,
        analytics_events_client: AnalyticsEventsClient,

作用：创建一个 TurnRequestProcessor，把它需要用到的所有外部工具一次性装进去。之后每个回合请求都靠这个对象来协调。

数据流：进去的是认证、线程管理、消息发送、配置、监听、技能监控等共享对象；函数只是把这些对象保存到结构体字段里；出来的是一个可被复用的请求处理器。

调用关系：它在上层创建处理器时被调用，相当于把前台需要的电话、登记本、规则手册都摆好，后面的请求入口函数才能使用这些资源。

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

async fn turn_start(
        &self,
        request_id: ConnectionRequestId,
        params: TurnStartParams,
        app_server_client_name: Option<String>,
        app_server_client_version: Option<

作用：处理客户端发来的“开始一个新回合”请求。它是公开入口，真正的检查和提交工作交给 turn_start_inner。

数据流：进去的是请求编号、开始回合参数、客户端名称和版本；它调用内部函数拿到 TurnStartResponse，再包装成通用的客户端响应；出来的是可发回客户端的响应或 JSON-RPC 错误。

调用关系：handle_initialized_client_request 收到 turn/start 后会调用它；它自己不做复杂活，只把请求转给 turn_start_inner，像门口接单后交给后台处理。

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

async fn thread_inject_items(
        &self,
        params: ThreadInjectItemsParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理“往线程里塞入响应项”的请求。这个入口主要用于把外部准备好的响应内容注入到某个会话线程中。

数据流：进去的是线程 ID 和要注入的项目；它交给 thread_inject_items_response_inner 校验并写入；出来的是空成功响应或错误。

调用关系：handle_initialized_client_request 收到对应请求时调用它；它只是统一响应包装，实际解析和注入由内部函数完成。

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

async fn thread_settings_update(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadSettingsUpdateParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理客户端修改线程设置的请求，比如模型、权限、沙盒策略、协作模式等。它让设置变更走统一校验流程，避免把非法配置送进核心线程。

数据流：进去的是请求编号和设置更新参数；它调用 thread_settings_update_inner 生成并提交设置操作；出来的是通用客户端响应或错误。

调用关系：handle_initialized_client_request 收到 thread/settings/update 时调用它；它把细节交给内部函数，自己负责把内部响应转成外层协议响应。

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

async fn turn_steer(
        &self,
        request_id: &ConnectionRequestId,
        params: TurnSteerParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理“引导正在进行的回合”的请求。比如模型正在工作时，用户追加一句指示，这个入口会把追加内容送到当前活动回合。

数据流：进去的是请求编号和引导参数；它调用 turn_steer_inner 做线程检查、输入校验和提交；出来的是包含回合 ID 的响应或错误。

调用关系：handle_initialized_client_request 收到 turn/steer 时调用它；真正判断当前回合能不能被引导的是 turn_steer_inner。

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

async fn turn_interrupt(
        &self,
        request_id: &ConnectionRequestId,
        params: TurnInterruptParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理“打断当前回合”或“取消启动中任务”的请求。它让客户端可以停止正在运行的模型工作。

数据流：进去的是请求编号和要打断的线程、回合信息；它调用 turn_interrupt_inner；出来可能是立即确认，也可能等后续回合中止事件再回应，或者返回错误。

调用关系：handle_initialized_client_request 收到打断请求时调用它；它把复杂的状态判断和核心中断提交交给 turn_interrupt_inner。

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

async fn thread_realtime_start(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeStartParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理开启实时对话的请求。实时对话可以理解为更像语音通话或流式交互的一种会话模式。

数据流：进去的是请求编号和实时会话启动参数；它调用 thread_realtime_start_inner；出来是启动成功响应、无响应或错误。

调用关系：handle_initialized_client_request 收到实时启动请求时调用它；内部函数会先确保线程能被监听，再向核心提交启动实时会话的命令。

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

async fn thread_realtime_append_audio(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeAppendAudioParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCE

作用：处理向实时对话追加一段音频的请求。它把客户端传来的音频帧送进正在进行的实时会话。

数据流：进去的是请求编号、线程 ID 和音频数据；它调用 thread_realtime_append_audio_inner；出来是追加成功响应、无响应或错误。

调用关系：handle_initialized_client_request 收到音频追加请求时调用它；内部函数负责确认实时会话可用并提交音频操作。

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

async fn thread_realtime_append_text(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeAppendTextParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErr

作用：处理向实时对话追加文字的请求。它让实时会话不只收声音，也能接收文本消息。

数据流：进去的是请求编号、线程 ID、文本和角色信息；它交给 thread_realtime_append_text_inner；出来是成功响应、无响应或错误。

调用关系：handle_initialized_client_request 收到实时文本追加请求时调用它；后续由内部函数把文字包装成核心操作。

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

async fn thread_realtime_append_speech(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeAppendSpeechParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRP

作用：处理向实时对话追加“要说出来的文字”的请求。它通常用于让系统把一段文本作为语音内容继续送入实时流程。

数据流：进去的是请求编号、线程 ID 和文本；它调用 thread_realtime_append_speech_inner；出来是成功响应、无响应或错误。

调用关系：handle_initialized_client_request 收到实时 speech 追加请求时调用它；内部函数会把文本变成核心层的实时语音操作。

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

async fn thread_realtime_stop(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeStopParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理停止实时对话的请求。它把“结束通话”的命令发给核心线程。

数据流：进去的是请求编号和线程 ID；它调用 thread_realtime_stop_inner；出来是停止成功响应、无响应或错误。

调用关系：handle_initialized_client_request 收到实时停止请求时调用它；内部函数负责准备线程并提交关闭操作。

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

async fn thread_realtime_list_voices(
        &self,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：返回系统内置的实时语音声音列表。客户端可以用它知道有哪些 voice（声音）可选。

数据流：没有复杂输入；它读取内置声音清单 RealtimeVoicesList::builtin；出来的是包含 voices 的客户端响应。

调用关系：handle_initialized_client_request 收到列出声音请求时直接调用它；它不碰线程，也不提交核心操作，只是回一个固定能力列表。

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

async fn review_start(
        &self,
        request_id: &ConnectionRequestId,
        params: ReviewStartParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：处理开始代码审查的请求。它是审查功能的外层入口，内部会决定是在当前线程审查还是另开一个审查线程。

数据流：进去的是请求编号和审查参数；它调用 review_start_inner，成功时返回空响应；出错时返回 JSON-RPC 错误。

调用关系：handle_initialized_client_request 收到 review/start 时调用它；真正准备审查目标和启动方式的是 review_start_inner。

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

fn track_error_response(
        &self,
        request_id: &ConnectionRequestId,
        error: &JSONRPCErrorError,
        error_type: Option<AnalyticsJsonRpcError>,
    )

作用：把一次请求失败的信息记到统计系统里。这样团队可以知道哪些请求常失败、失败原因是什么。

数据流：进去的是请求编号、错误对象和可选的错误分类；它从请求编号里取连接 ID 和请求 ID，复制错误并交给 analytics_events_client；出来没有返回值，只产生统计记录。

调用关系：ensure_direct_input_allowed、turn_start_inner、turn_steer_inner 在发现错误时会调用它；它不修复错误，只负责留下可分析的记录。

调用图：调用 1 个内部函数（track_error_response）；被 3 处调用（ensure_direct_input_allowed, turn_start_inner, turn_steer_inner）；外部调用 1 个（clone）。

async fn load_thread(
        &self,
        thread_id: &str,
    ) -> Result<(ThreadId, Arc<CodexThread>), JSONRPCErrorError>

作用：根据客户端传来的线程 ID 找到真正的会话线程。没有这一步，后面所有操作都不知道要作用在哪个会话上。

数据流：进去的是字符串形式的 thread_id；函数先把它解析成内部 ThreadId，再向 thread_manager 查询线程；出来是内部线程 ID 和线程对象，或者返回“ID 无效/线程不存在”的错误。

调用关系：很多内部流程都会先调用它，包括开始回合、引导、打断、实时对话、审查和注入项目；它是大多数请求进入线程世界的第一道门。

调用图：调用 1 个内部函数（from_string）；被 7 处调用（prepare_realtime_conversation_thread, review_start_inner, thread_inject_items_response_inner, thread_settings_update_inner, turn_interrupt_inner, turn_start_inner, turn_steer_inner）。

async fn ensure_direct_input_allowed(
        &self,
        request_id: &ConnectionRequestId,
        thread: &CodexThread,
    ) -> Result<(), JSONRPCErrorError>

作用：检查某些多智能体子线程是否禁止直接接收 app-server 输入。这样可以防止外部请求绕过多智能体系统自己的调度规则。

数据流：进去的是请求编号和线程；它读取线程的多智能体版本和会话来源，如果发现是 v2 子智能体线程，就生成错误并上报；出来是成功的空结果或错误。

调用关系：turn_start_inner 和 turn_steer_inner 在接受用户输入前调用它；如果不允许，它会调用 track_error_response 记录错误并阻止请求继续。

调用图：调用 2 个内部函数（track_error_response, multi_agent_version）；被 2 处调用（turn_start_inner, turn_steer_inner）；外部调用 1 个（matches!）。

fn normalize_collaboration_mode(
        &self,
        mut collaboration_mode: CollaborationMode,
    ) -> CollaborationMode

作用：补全协作模式里的默认开发者指令。客户端只传了模式但没传具体说明时，它会从内置预设里找一份合适的说明补上。

数据流：进去的是一个 collaboration_mode；函数检查其中 developer_instructions 是否为空，若为空就查内置预设并填入非空指令；出来是可能被补全过的协作模式。

调用关系：它服务于线程设置构建流程，虽然调用图里没有列出调用者，但在 build_thread_settings_overrides 中会通过 map 使用它来规范客户端传入的协作模式。

fn review_request_from_target(
        target: ApiReviewTarget,
    ) -> Result<(ReviewRequest, String), JSONRPCErrorError>

作用：把客户端说的“审查什么”整理成核心审查请求。它还会生成一段给用户看的提示文字，说明这次审查的目标。

数据流：进去的是审查目标，比如未提交改动、某个分支、某个提交或自定义说明；函数会去掉首尾空白并拒绝空分支、空 sha、空说明，再转换成核心目标；出来是 ReviewRequest 和展示提示文字。

调用关系：review_start_inner 在启动审查前会用它清洗目标；它还调用 user_facing_hint 生成用户能看懂的提示。

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

async fn request_trace_context(
        &self,
        request_id: &ConnectionRequestId,
    ) -> Option<codex_protocol::protocol::W3cTraceContext>

作用：取出当前请求的追踪上下文。追踪上下文可以理解为给一次请求贴的快递单号，方便跨组件追查它一路发生了什么。

数据流：进去的是请求编号；它向 outgoing 查询这个请求对应的 W3C trace context；出来是可选的追踪信息，不改动线程内容。

调用关系：submit_core_op、turn_start_inner 和 start_detached_review 会用它；这样提交给核心线程的操作可以带上同一条追踪链路。

调用图：被 3 处调用（start_detached_review, submit_core_op, turn_start_inner）。

async fn submit_core_op(
        &self,
        request_id: &ConnectionRequestId,
        thread: &CodexThread,
        op: Op,
    ) -> CodexResult<String>

作用：把整理好的核心操作提交给某个 CodexThread。它是很多请求最终“发命令给核心引擎”的统一通道。

数据流：进去的是请求编号、线程和 Op 操作；它先取请求追踪上下文，再调用线程的 submit_with_trace；出来是核心返回的提交 ID，或者核心错误。

调用关系：线程设置、实时对话、审查、打断等很多内部函数都会调用它；它把上层请求处理器和底层线程执行连接起来。

调用图：调用 2 个内部函数（request_trace_context, submit_with_trace）；被 9 处调用（start_detached_review, start_inline_review, thread_realtime_append_audio_inner, thread_realtime_append_speech_inner, thread_realtime_append_text_inner, thread_realtime_start_inner, thread_realtime_stop_inner, thread_settings_update_inner, turn_interrupt_inner）。

fn input_too_large_error(actual_chars: usize) -> JSONRPCErrorError

作用：生成“输入太长”的标准错误。这样客户端不仅看到错误文字，还能知道最大允许长度和实际长度。

数据流：进去的是实际字符数；函数创建 invalid_params 错误，并把 input_error_code、max_chars、actual_chars 放进错误 data；出来是完整的 JSON-RPC 错误对象。

调用关系：validate_v2_input_limit 在发现输入超过限制时会用它；它本身不检查文本，只负责把错误做成统一格式。

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

fn validate_v2_input_limit(items: &[V2UserInput]) -> Result<(), JSONRPCErrorError>

作用：检查 v2 用户输入的总字符数是否超过上限。这样可以避免一次请求塞入过大的文本，拖垮处理或超过模型能力。

数据流：进去的是一组 V2UserInput；它把每项文本字符数加起来，与 MAX_USER_INPUT_TEXT_CHARS 比较；出来是成功空结果，或者由 input_too_large_error 生成的错误。

调用关系：turn_start_inner 和 turn_steer_inner 在接受用户输入前都会调用它；如果失败，外层会记录统计并拒绝继续提交。

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

async fn turn_start_inner(
        &self,
        request_id: ConnectionRequestId,
        params: TurnStartParams,
        app_server_client_name: Option<String>,
        app_server_client_version: O

作用：真正执行“开始新回合”的完整流程。它负责从找线程、校验输入、套用临时设置，到把用户输入提交给核心线程。

数据流：进去的是请求编号、回合参数和客户端信息；它加载线程、检查是否允许直接输入、检查文本长度、记录客户端信息、解析环境和线程设置、把输入和额外上下文转成核心格式，然后提交 UserInput；出来是带有新 turn 的 TurnStartResponse，同时记录请求和 turn_id 的对应关系，必要时还启动记忆写入任务。

调用关系：turn_start 只负责包装，真正调用的是它；它会调用 load_thread、ensure_direct_input_allowed、build_environment_override、build_thread_settings_overrides、map_additional_context、request_trace_context，并在错误时调用 track_error_response。

调用图：调用 7 个内部函数（build_environment_override, build_thread_settings_overrides, ensure_direct_input_allowed, load_thread, request_trace_context, track_error_response, map_additional_context）；被 1 处调用（turn_start）；外部调用 6 个（clone, set_app_server_client_info, validate_v2_input_limit, Input, start_memories_startup_task, vec!）。

async fn build_environment_override(
        &self,
        thread: &CodexThread,
        cwd: Option<AbsolutePathBuf>,
        environment_selections: Option<Vec<TurnEnvironmentSelection>>,
    ) ->

作用：根据请求里的工作目录和环境选择，生成本次回合临时使用的运行环境设置。它解决的是“这次操作到底在哪个目录、哪个环境里跑”的问题。

数据流：进去的是线程、可选 cwd（当前工作目录）和可选环境选择；如果都没有就返回 None，如果只有 cwd 就用线程管理器给出默认环境，如果有环境选择但缺 cwd 就从本地环境或线程快照里找兜底目录；出来是可选的 TurnEnvironmentSelections。

调用关系：turn_start_inner 和 thread_settings_update_inner 会调用它；它生成的环境覆盖项随后会进入 build_thread_settings_overrides 或核心 UserInput 操作。

调用图：调用 2 个内部函数（config_snapshot, new）；被 2 处调用（thread_settings_update_inner, turn_start_inner）。

async fn build_thread_settings_overrides(
        &self,
        thread: &CodexThread,
        params: ThreadSettingsBuildParams,
    ) -> Result<codex_protocol::protocol::ThreadSettingsOverrides, JSO

作用：把客户端传来的临时线程设置整理、校验并转换成核心协议格式。它是防止权限、沙盒、模型等设置乱传的关键关卡。

数据流：进去的是线程和一包设置参数；它先拒绝互相冲突的 permissions 与 sandboxPolicy，补全协作模式，必要时重新加载配置来解析权限配置，再让线程预览这些覆盖设置是否合法；出来是 ThreadSettingsOverrides，包含环境、工作区根目录、审批策略、沙盒、权限、模型、推理强度等字段。

调用关系：turn_start_inner 和 thread_settings_update_inner 都会调用它；它会用 config_manager.load_for_cwd 解析权限，并用 preview_thread_settings_overrides 让核心线程提前检查。

调用图：调用 3 个内部函数（load_for_cwd, config_snapshot, preview_thread_settings_overrides）；被 2 处调用（thread_settings_update_inner, turn_start_inner）；外部调用 2 个（default, format!）。

async fn thread_settings_update_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadSettingsUpdateParams,
    ) -> Result<ThreadSettingsUpdateResponse, JSONRPCErrorEr

作用：真正处理线程设置更新。它只在有实际改动时才向核心线程提交设置操作。

数据流：进去的是请求编号和设置参数；它加载线程，解析 cwd，构建环境覆盖和线程设置覆盖；如果设置不是默认空值，就提交 Op::ThreadSettings；出来是空的 ThreadSettingsUpdateResponse 或错误。

调用关系：thread_settings_update 会调用它；它依赖 load_thread、build_environment_override、build_thread_settings_overrides 和 submit_core_op，把设置请求排进核心线程。

调用图：调用 4 个内部函数（build_environment_override, build_thread_settings_overrides, load_thread, submit_core_op）；被 1 处调用（thread_settings_update）；外部调用 1 个（default）。

async fn thread_inject_items_response_inner(
        &self,
        params: ThreadInjectItemsParams,
    ) -> Result<ThreadInjectItemsResponse, JSONRPCErrorError>

作用：真正把响应项注入到指定线程。它会先确认每个 JSON 项目确实能解析成系统认识的响应项。

数据流：进去的是线程 ID 和一组 JSON 值；函数加载线程，把每项 JSON 反序列化成 ResponseItem，任何一项不合法都会指出位置；成功后调用线程的 inject_response_items；出来是空成功响应或错误。

调用关系：thread_inject_items 调用它；它用 load_thread 找到目标线程，然后把注入动作交给 CodexThread。

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

async fn set_app_server_client_info(
        thread: &CodexThread,
        app_server_client_name: Option<String>,
        app_server_client_version: Option<String>,
    ) -> Result<(), JSONRPCErrorEr

作用：把当前 app-server 客户端的名称和版本写入线程。这样核心层可以根据客户端差异做兼容处理。

数据流：进去的是线程、客户端名称和版本；它先用 xcode_26_4_mcp_elicitations_auto_deny 判断是否需要特殊兼容开关，再调用线程保存这些信息；出来是成功空结果或内部错误。

调用关系：turn_start_inner 在开始回合前调用它；它又调用 xcode_26_4_mcp_elicitations_auto_deny 来处理 Xcode 26.4 的兼容规则。

调用图：调用 2 个内部函数（xcode_26_4_mcp_elicitations_auto_deny, set_app_server_client_info）。

async fn turn_steer_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: TurnSteerParams,
    ) -> Result<TurnSteerResponse, JSONRPCErrorError>

作用：真正处理“给正在运行的回合追加指示”。它确保追加内容是发给正确的活动回合，而不是误塞到别的回合里。

数据流：进去的是请求编号和引导参数；它加载线程、检查直接输入权限、要求 expected_turn_id 非空、记录请求对应的回合、检查输入长度、转换输入和额外上下文，然后调用线程 steer_input；出来是新的或确认的 turn_id，或者带明确原因的错误。

调用关系：turn_steer 调用它；它用 load_thread、ensure_direct_input_allowed、validate_v2_input_limit 和 map_additional_context 做准备，出错时用 track_error_response 记录分类。

调用图：调用 4 个内部函数（ensure_direct_input_allowed, load_thread, track_error_response, map_additional_context）；被 1 处调用（turn_steer）；外部调用 2 个（validate_v2_input_limit, Input）。

async fn prepare_realtime_conversation_thread(
        &self,
        request_id: &ConnectionRequestId,
        thread_id: &str,
    ) -> Result<Option<(ThreadId, Arc<CodexThread>)>, JSONRPCErrorError

作用：为实时对话请求准备线程。它确保连接已经挂上会话监听器，并且这个线程真的支持实时对话功能。

数据流：进去的是请求编号和线程 ID 字符串；它加载线程，调用 ensure_conversation_listener 让当前连接能收到线程事件，如果连接已关闭就返回 None，再检查 Feature::RealtimeConversation；出来是可选的线程 ID 和线程对象。

调用关系：所有实时对话内部函数都会先调用它；它像进入语音房间前的门禁，没监听、连接关了或线程不支持都不能继续。

调用图：调用 2 个内部函数（ensure_conversation_listener, load_thread）；被 5 处调用（thread_realtime_append_audio_inner, thread_realtime_append_speech_inner, thread_realtime_append_text_inner, thread_realtime_start_inner, thread_realtime_stop_inner）；外部调用 1 个（format!）。

async fn thread_realtime_start_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeStartParams,
    ) -> Result<Option<ThreadRealtimeStartResponse>, JSONRPCEr

作用：真正向核心线程提交“启动实时对话”的命令。它把客户端传来的模型、声音、传输方式等参数整理成核心会话启动参数。

数据流：进去的是请求编号和实时启动参数；它先准备线程，然后构造 ConversationStartParams，包括 websocket 或 webrtc 传输、声音、模型、输出形式等；出来是默认启动响应、无响应或错误。

调用关系：thread_realtime_start 调用它；它依赖 prepare_realtime_conversation_thread 做门禁，再用 submit_core_op 提交 RealtimeConversationStart。

调用图：调用 2 个内部函数（prepare_realtime_conversation_thread, submit_core_op）；被 1 处调用（thread_realtime_start）；外部调用 2 个（default, RealtimeConversationStart）。

async fn thread_realtime_append_audio_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeAppendAudioParams,
    ) -> Result<Option<ThreadRealtimeAppendAudioR

作用：真正向实时对话追加音频帧。它把客户端发来的音频包装成核心层认识的音频参数。

数据流：进去的是请求编号、线程 ID 和音频；它准备线程，把 audio 转成 frame，提交 Op::RealtimeConversationAudio；出来是默认成功响应、无响应或错误。

调用关系：thread_realtime_append_audio 调用它；它先走 prepare_realtime_conversation_thread，再通过 submit_core_op 把音频送入核心线程。

调用图：调用 2 个内部函数（prepare_realtime_conversation_thread, submit_core_op）；被 1 处调用（thread_realtime_append_audio）；外部调用 2 个（default, RealtimeConversationAudio）。

async fn thread_realtime_append_text_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeAppendTextParams,
    ) -> Result<Option<ThreadRealtimeAppendTextResp

作用：真正向实时对话追加文本消息。它让实时会话可以接收用户或系统角色的文字输入。

数据流：进去的是请求编号、线程 ID、文本和角色；它准备线程，构造 ConversationTextParams，然后提交 RealtimeConversationText；出来是默认成功响应、无响应或错误。

调用关系：thread_realtime_append_text 调用它；它和其他实时追加函数一样，先确保线程可用，再用 submit_core_op 发给核心。

调用图：调用 2 个内部函数（prepare_realtime_conversation_thread, submit_core_op）；被 1 处调用（thread_realtime_append_text）；外部调用 2 个（default, RealtimeConversationText）。

async fn thread_realtime_append_speech_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeAppendSpeechParams,
    ) -> Result<Option<ThreadRealtimeAppendSpee

作用：真正向实时对话追加要作为语音处理的文本。它把一段文字送进实时语音流程。

数据流：进去的是请求编号、线程 ID 和文本；它准备线程，把文本放进 ConversationSpeechParams，并提交 RealtimeConversationSpeech；出来是默认成功响应、无响应或错误。

调用关系：thread_realtime_append_speech 调用它；它依赖 prepare_realtime_conversation_thread 和 submit_core_op 完成从请求到核心操作的转交。

调用图：调用 2 个内部函数（prepare_realtime_conversation_thread, submit_core_op）；被 1 处调用（thread_realtime_append_speech）；外部调用 2 个（default, RealtimeConversationSpeech）。

async fn thread_realtime_stop_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeStopParams,
    ) -> Result<Option<ThreadRealtimeStopResponse>, JSONRPCError

作用：真正停止实时对话。它向核心线程发送关闭实时会话的命令。

数据流：进去的是请求编号和线程 ID；它准备线程后提交 Op::RealtimeConversationClose；出来是默认停止响应、无响应或错误。

调用关系：thread_realtime_stop 调用它；它和启动、追加音频文本一样，先通过 prepare_realtime_conversation_thread 校验，再通过 submit_core_op 下发关闭操作。

调用图：调用 2 个内部函数（prepare_realtime_conversation_thread, submit_core_op）；被 1 处调用（thread_realtime_stop）；外部调用 1 个（default）。

fn build_review_turn(turn_id: String, display_text: &str) -> Turn

作用：为代码审查创建一个展示用的 Turn 对象。这样客户端能像显示普通回合一样显示审查已经开始。

数据流：进去的是 turn_id 和展示文字；如果展示文字为空，就生成没有项目的回合，否则生成一条用户消息项目；出来是状态为 InProgress 的 Turn。

调用关系：start_inline_review 和 start_detached_review 在提交审查操作后会用它；它只造展示数据，不负责真正审查。

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

async fn emit_review_started(
        &self,
        request_id: &ConnectionRequestId,
        turn: Turn,
        review_thread_id: String,
    )

作用：向客户端发送“审查已开始”的响应。它把审查回合和审查线程 ID 一起告诉客户端。

数据流：进去的是请求编号、Turn 和 review_thread_id；它包装成 ReviewStartResponse，通过 outgoing 发回响应；出来没有业务返回值。

调用关系：start_inline_review 和 start_detached_review 都会在审查启动后调用它；它是审查流程最后通知客户端的一步。

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

async fn start_inline_review(
        &self,
        request_id: &ConnectionRequestId,
        parent_thread: Arc<CodexThread>,
        review_request: ReviewRequest,
        display_text: &str,

作用：在当前线程里启动代码审查。也就是说审查作为父会话里的一个普通回合出现。

数据流：进去的是请求编号、父线程、审查请求、展示文字和父线程 ID；它向父线程提交 Op::Review，拿到 turn_id，构造展示 Turn，再发送审查开始响应；出来是成功空结果或错误。

调用关系：review_start_inner 判断 delivery 是 Inline 时调用它；它依赖 submit_core_op、build_review_turn 和 emit_review_started。

调用图：调用 2 个内部函数（emit_review_started, submit_core_op）；被 1 处调用（review_start_inner）；外部调用 1 个（build_review_turn）。

async fn start_detached_review(
        &self,
        request_id: &ConnectionRequestId,
        parent_thread_id: ThreadId,
        parent_thread: Arc<CodexThread>,
        review_request: ReviewRequ

作用：另开一个线程来做代码审查。这样审查不会直接混在原来的会话回合里，但会继承父线程历史作为背景。

数据流：进去的是请求编号、父线程 ID、父线程、审查请求和展示文字；它先确保父线程历史落盘，读取历史，复制配置并可能切换到 review_model，然后 fork 出审查线程，挂监听器，更新线程列表通知客户端，再在新线程提交审查操作；出来是成功空结果或错误。

调用关系：review_start_inner 判断 delivery 是 Detached 时调用它；它会调用 ensure_conversation_listener、request_trace_context、submit_core_op、emit_review_started，并通过线程 watch 管理器把新审查线程悄悄加入列表再通知客户端。

调用图：调用 6 个内部函数（emit_review_started, ensure_conversation_listener, request_trace_context, submit_core_op, loaded_status_for_thread, upsert_thread_silently）；被 1 处调用（review_start_inner）；外部调用 4 个（build_review_turn, ThreadStarted, Resumed, warn!）。

async fn review_start_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ReviewStartParams,
    ) -> Result<(), JSONRPCErrorError>

作用：真正处理开始审查的总流程。它负责找父线程、清洗审查目标，并按客户端要求选择内联审查还是独立审查。

数据流：进去的是请求编号和 ReviewStartParams；它拆出线程 ID、目标和交付方式，加载父线程，把目标转成 ReviewRequest 和展示文本，然后分支调用 start_inline_review 或 start_detached_review；出来是成功空结果或错误。

调用关系：review_start 调用它；它是审查功能的调度点，向下连接 review_request_from_target、start_inline_review 和 start_detached_review。

调用图：调用 3 个内部函数（load_thread, start_detached_review, start_inline_review）；被 1 处调用（review_start）；外部调用 1 个（review_request_from_target）。

async fn turn_interrupt_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: TurnInterruptParams,
    ) -> Result<Option<TurnInterruptResponse>, JSONRPCErrorError>

作用：真正处理打断请求。它既要确认要打断的回合确实还在运行，也要把等待响应的请求登记好。

数据流：进去的是请求编号、线程 ID 和 turn_id；如果 turn_id 为空就当作启动阶段打断，否则加载线程状态，确认活动回合 ID 匹配且还在运行，把请求加入 pending_interrupts，然后提交 Op::Interrupt；出来可能立即返回打断成功，也可能返回 None 等待 TurnAborted 事件，失败时会清理已登记的 pending interrupt。

调用关系：turn_interrupt 调用它；它会用 load_thread 找线程、用 thread_state_manager 查状态、用 submit_core_op 提交中断，是“用户点停止按钮”背后的主要流程。

调用图：调用 3 个内部函数（load_thread, submit_core_op, thread_state）；被 1 处调用（turn_interrupt）；外部调用 3 个（clone, format!, matches!）。

fn listener_task_context(&self) -> ListenerTaskContext

作用：组装会话监听任务需要的一包上下文。监听任务要知道怎么取线程、怎么发消息、怎么更新线程状态等。

数据流：进去的是 self 中已经保存的各种管理器和配置；函数复制或克隆这些共享句柄，放进 ListenerTaskContext；出来是一个上下文对象，不启动任务。

调用关系：ensure_conversation_listener 会调用它；它相当于把监听器开工前需要的工具箱打包好。

调用图：被 1 处调用（ensure_conversation_listener）；外部调用 3 个（clone, clone, clone）。

async fn ensure_conversation_listener(
        &self,
        conversation_id: ThreadId,
        connection_id: ConnectionId,
        raw_events_enabled: bool,
    ) -> Result<EnsureConversationListen

作用：确保某个连接正在监听某个会话线程的事件。没有监听器，客户端可能收不到回合进度、审查线程变化或实时会话事件。

数据流：进去的是会话 ID、连接 ID 和是否启用原始事件；它先生成 listener_task_context，再调用 thread_lifecycle 里的 ensure_conversation_listener；出来是监听已附着、连接已关闭或错误。

调用关系：prepare_realtime_conversation_thread 和 start_detached_review 会调用它；它把具体监听创建工作交给 thread_lifecycle 模块。

调用图：调用 2 个内部函数（ensure_conversation_listener, listener_task_context）；被 2 处调用（prepare_realtime_conversation_thread, start_detached_review）。

fn xcode_26_4_mcp_elicitations_auto_deny(
    client_name: Option<&str>,
    client_version: Option<&str>,
) -> bool

作用：判断是否要对 Xcode 26.4 客户端自动拒绝 MCP elicitation 请求。这里是一个兼容旧客户端的临时补丁，因为那个版本还不能显示这类请求。

数据流：进去的是客户端名称和版本；函数检查名称是否为 Xcode，版本是否以 26.4 开头；出来是布尔值，true 表示启用自动拒绝。

调用关系：set_app_server_client_info 会调用它；它不接触线程本身，只给保存客户端信息时提供一个兼容开关。

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

fn new(
        outgoing: Arc<OutgoingMessageSender>,
        config: Arc<Config>,
        config_manager: ConfigManager,
    ) -> Self

作用：创建一个 Windows 沙盒请求处理器，把之后办事需要的三样东西收好：发消息的通道、当前配置、以及能重新加载配置的工具。

数据流：进去的是 outgoing、config 和 config_manager → 函数把它们放进 WindowsSandboxRequestProcessor 这个结构里 → 出来的是一个可以处理 Windows 沙盒请求的新对象，本身不做网络发送，也不改配置。

调用关系：它在上层创建请求处理器时被调用，相当于把服务台窗口搭好。后面的 readiness 查询和 setup 启动都会使用这里保存的消息通道和配置工具。

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

async fn windows_sandbox_readiness(
        &self,
    ) -> Result<WindowsSandboxReadinessResponse, JSONRPCErrorError>

作用：回答客户端一句话：当前 Windows 沙盒是否已经准备好。它把复杂判断包装成一个异步请求接口，方便请求分发器直接调用。

数据流：进去的是处理器自己保存的配置 → 它调用 determine_windows_sandbox_readiness 做实际判断 → 出来的是 WindowsSandboxReadinessResponse，里面写着状态，比如未配置、可用或需要更新；不会改动任何状态。

调用关系：当 handle_initialized_client_request 收到已初始化客户端的 readiness 请求时会调用它。它自己不判断细节，而是把活交给 determine_windows_sandbox_readiness。

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

async fn windows_sandbox_setup_start(
        &self,
        request_id: &ConnectionRequestId,
        params: WindowsSandboxSetupStartParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErr

作用：处理“开始设置 Windows 沙盒”的客户端请求。它的公开职责是启动流程，并把成功启动后的直接响应整理成协议需要的形式。

数据流：进去的是请求编号和客户端传来的设置参数 → 它调用 windows_sandbox_setup_start_inner 做真正的检查和启动 → 如果启动步骤成功，出来的是 None，表示正式的“已开始”响应已经在内部单独发过了；如果失败，就返回 JSON-RPC 错误。

调用关系：handle_initialized_client_request 收到 setup start 请求时会到这里。它像外层包装纸，把核心工作交给 windows_sandbox_setup_start_inner，并把返回值调整成客户端请求处理框架能理解的样子。

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

async fn windows_sandbox_setup_start_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: WindowsSandboxSetupStartParams,
    ) -> Result<(), JSONRPCErrorError>

作用：这是启动 Windows 沙盒设置的核心流程：先验证配置和权限，再告诉客户端“已经开始”，最后把真正耗时的设置任务丢到后台执行。

数据流：进去的是请求编号和参数，参数里可能带有工作目录和想要的沙盒模式 → 它先确定工作目录，没有传就用当前配置里的目录；再用 config_manager.load_for_cwd 按这个目录重新加载配置；接着用 resolve_allowed_windows_sandbox_setup_mode 检查这个模式是否被配置规则允许；通过后，先向客户端发送 started: true；随后复制发送通道和连接编号，启动一个后台任务。后台任务会收集权限配置、工作区目录、环境变量、codex_home 等信息，调用 run_windows_sandbox_setup 真正设置沙盒，最后发 WindowsSandboxSetupCompleted 通知，告诉客户端成功、失败以及错误文字。

调用关系：它由 windows_sandbox_setup_start 调用，是整个设置请求的发动机。它把配置加载交给 load_for_cwd，把模式合法性检查交给 resolve_allowed_windows_sandbox_setup_mode，把真正的系统级设置交给 codex_core::windows_sandbox::run_windows_sandbox_setup，最后通过 outgoing 把结果通知发回原连接。

调用图：调用 3 个内部函数（load_for_cwd, resolve_allowed_windows_sandbox_setup_mode, run_windows_sandbox_setup）；被 1 处调用（windows_sandbox_setup_start）；外部调用 6 个（clone, default, WindowsSandboxSetupCompleted, clone, vars, spawn）。

fn resolve_allowed_windows_sandbox_setup_mode(
    requirements: &codex_config::ConfigRequirements,
    requested_mode: WindowsSandboxSetupMode,
) -> Result<CoreWindowsSandboxSetupMode, JSONRPCErrorEr

作用：把客户端说的沙盒模式翻译成核心代码能使用的模式，同时检查管理员或配置文件是否允许这么设置。它防止用户绕过受管配置，启动不被允许的沙盒模式。

数据流：进去的是配置要求 requirements 和客户端请求的 WindowsSandboxSetupMode → 它把请求模式对应到两种表示：一种给核心沙盒代码用，一种给配置规则检查用；然后询问 requirements.windows_sandbox_mode.can_set 是否允许设置这个值 → 如果允许，出来的是 CoreWindowsSandboxSetupMode；如果不允许，出来的是 invalid request 错误。

调用关系：windows_sandbox_setup_start_inner 在真正开始设置前调用它。测试函数 tests::resolve_allowed_windows_sandbox_setup_mode_rejects_disallowed_mode 也会调用它，确认不允许的模式会被挡住。

调用图：被 2 处调用（windows_sandbox_setup_start_inner, resolve_allowed_windows_sandbox_setup_mode_rejects_disallowed_mode）。

fn determine_windows_sandbox_readiness(config: &Config) -> WindowsSandboxReadinessResponse

作用：根据当前运行平台和配置，判断 Windows 沙盒现在处于什么准备状态。它是 readiness 查询的实际判断入口。

数据流：进去的是 Config 配置 → 它先看程序是不是运行在 Windows 上；如果不是 Windows，直接认为未配置；如果是 Windows，就从配置推导沙盒级别，并检查 codex_home 里的沙盒设置是否已经完成 → 最后交给 determine_windows_sandbox_readiness_from_state 生成响应。

调用关系：WindowsSandboxRequestProcessor::windows_sandbox_readiness 调用它来回答客户端。它自己负责收集真实环境信息，然后把纯粹的状态判断交给 determine_windows_sandbox_readiness_from_state。

调用图：调用 1 个内部函数（determine_windows_sandbox_readiness_from_state）；被 1 处调用（windows_sandbox_readiness）；外部调用 2 个（cfg!, from_config）。

fn determine_windows_sandbox_readiness_from_state(
    windows_sandbox_level: WindowsSandboxLevel,
    sandbox_setup_is_complete: bool,
) -> WindowsSandboxReadinessResponse

作用：把两个简单事实翻译成用户能看懂的准备状态：沙盒级别是什么、需要的设置是否已经完成。它把判断规则集中在一个容易测试的小函数里。

数据流：进去的是 windows_sandbox_level 和 sandbox_setup_is_complete → 如果沙盒被禁用，返回 NotConfigured；如果是受限令牌模式，返回 Ready；如果是提升权限模式，就看设置是否完成，完成返回 Ready，没完成返回 UpdateRequired → 出来的是 WindowsSandboxReadinessResponse。

调用关系：determine_windows_sandbox_readiness 用它做最终判断。多个测试也直接调用它，用固定输入检查各种状态是否会得到正确答案。

调用图：被 5 处调用（determine_windows_sandbox_readiness, determine_windows_sandbox_readiness_reports_not_configured_when_disabled, determine_windows_sandbox_readiness_reports_ready_for_complete_elevated_mode, determine_windows_sandbox_readiness_reports_ready_for_unelevated_mode, determine_windows_sandbox_readiness_reports_update_required_when_elevated_setup_is_stale）。

fn resolve_allowed_windows_sandbox_setup_mode_rejects_disallowed_mode()

作用：这个测试确认：当配置只允许 Elevated 模式时，用户请求 Unelevated 模式会被拒绝。它是在保护“受管配置不能被请求绕过”这条规则。

数据流：进去的是测试里临时造出的配置要求：只允许 Elevated → 它调用 resolve_allowed_windows_sandbox_setup_mode，并故意传 Unelevated → 出来应该是一个错误；测试再检查错误码是 INVALID_REQUEST_ERROR_CODE，错误消息里也提到 Windows 沙盒模式无效。

调用关系：它直接测试 resolve_allowed_windows_sandbox_setup_mode。这个测试不参与运行时流程，只在测试阶段防止以后有人改代码时把限制检查弄坏。

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

fn determine_windows_sandbox_readiness_reports_not_configured_when_disabled()

作用：这个测试确认：如果沙盒级别是 Disabled，也就是关闭状态，那么 readiness 应该报告未配置。

数据流：进去的是 Disabled 和 setup 未完成这个测试输入 → 它调用 determine_windows_sandbox_readiness_from_state → 出来应该是 NotConfigured，测试用 assert_eq 检查结果。

调用关系：它直接覆盖 determine_windows_sandbox_readiness_from_state 的禁用分支。作用是在测试阶段锁住这条最基本的状态规则。

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

fn determine_windows_sandbox_readiness_reports_ready_for_unelevated_mode()

作用：这个测试确认：受限令牌模式不需要额外的提升权限设置，即使 setup 标记没完成，也应该算可用。

数据流：进去的是 RestrictedToken 和 setup 未完成 → 它调用 determine_windows_sandbox_readiness_from_state → 出来应该是 Ready，测试检查这个状态是否正确。

调用关系：它直接测试 determine_windows_sandbox_readiness_from_state 的受限令牌分支。它说明 Unelevated 这类模式和 Elevated 模式的准备条件不一样。

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

fn determine_windows_sandbox_readiness_reports_ready_for_complete_elevated_mode()

作用：这个测试确认：提升权限模式下，如果所需设置已经完成，就应该报告可用。

数据流：进去的是 Elevated 和 setup 已完成 → 它调用 determine_windows_sandbox_readiness_from_state → 出来应该是 Ready，测试用断言确认。

调用关系：它覆盖 determine_windows_sandbox_readiness_from_state 的 Elevated 成功路径。这样能保证提升权限沙盒在安装完成后不会被误报成需要更新。

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

fn determine_windows_sandbox_readiness_reports_update_required_when_elevated_setup_is_stale()

作用：这个测试确认：提升权限模式下，如果沙盒设置没有完成或已经过期，就应该报告需要更新，而不是假装已经可用。

数据流：进去的是 Elevated 和 setup 未完成 → 它调用 determine_windows_sandbox_readiness_from_state → 出来应该是 UpdateRequired，测试检查这个结果。

调用关系：它覆盖 determine_windows_sandbox_readiness_from_state 的 Elevated 待更新路径。这个测试保护的是用户体验和安全性：该补设置时必须明确提示。

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

fn collect_resume_override_mismatches(
    request: &ThreadResumeParams,
    config_snapshot: &ThreadConfigSnapshot,
) -> Vec<String>

作用：检查“恢复已有对话”时，用户新给的模型、目录、权限等设置，和正在运行的对话实际设置是不是不一致。

数据流：输入恢复请求和当前对话配置快照 → 逐项比较模型、模型供应商、工作目录、沙盒、权限、人格等 → 输出一组可读的差异说明，不改动外部状态。

调用关系：resume_running_thread 在发现对话已经运行时会用它判断新参数是否只能被忽略，并把差异写进警告。

调用图：调用 2 个内部函数（cwd, sandbox_policy）；被 1 处调用（resume_running_thread）；外部调用 4 个（new, format!, matches!, from）。

fn merge_persisted_resume_metadata(
    request_overrides: &mut Option<HashMap<String, serde_json::Value>>,
    typesafe_overrides: &mut ConfigOverrides,
    persisted_metadata: &ThreadMetadata,
)

作用：恢复旧对话时，把之前保存的模型信息补回配置里，避免换成当前默认模型。

数据流：输入请求里的自由配置、类型化配置和已保存元数据 → 如果用户没有显式指定模型，就填入旧模型、旧供应商和推理强度 → 修改传入的配置对象，无返回值。

调用关系：load_and_apply_persisted_resume_metadata 读到数据库里的旧元数据后调用它。

调用图：调用 1 个内部函数（has_model_resume_override）；被 1 处调用（load_and_apply_persisted_resume_metadata）；外部调用 1 个（String）。

fn normalize_thread_list_cwd_filters(
    cwd: Option<ThreadListCwdFilter>,
) -> Result<Option<Vec<PathBuf>>, JSONRPCErrorError>

作用：把对话列表里的工作目录筛选条件统一成绝对路径，方便准确比较。

数据流：输入可能为空、单个或多个目录字符串 → 逐个按当前目录解析成规范路径 → 输出路径列表；路径不合法就返回参数错误。

调用关系：thread_list_response_inner 在真正查询列表前调用它，避免后面用模糊路径筛选。

调用图：调用 1 个内部函数（relative_to_current_dir）；被 1 处调用（thread_list_response_inner）；外部调用 2 个（with_capacity, vec!）。

fn has_model_resume_override(
    request_overrides: Option<&HashMap<String, serde_json::Value>>,
    typesafe_overrides: &ConfigOverrides,
) -> bool

作用：判断恢复请求里是否已经明确指定了模型相关设置。

数据流：输入两类配置覆盖项 → 查看是否包含模型、模型供应商或推理强度 → 输出 true 或 false，不改状态。

调用关系：merge_persisted_resume_metadata 用它决定是否可以安全地用旧元数据补模型。

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

fn validate_dynamic_tools(tools: &[DynamicToolSpec]) -> Result<(), String>

作用：检查客户端临时提供的工具定义是否合法，防止把坏名字、重复工具或不支持的输入格式交给模型。

数据流：输入动态工具列表 → 检查名字长度、字符、保留命名空间、重复项、输入 schema（工具参数格式说明）等 → 全部通过返回成功，否则返回具体错误文字。

调用关系：thread_start_task 在新建对话前调用它；只有通过检查的工具才会随对话启动。

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

fn new(
        auth_manager: Arc<AuthManager>,
        thread_manager: Arc<ThreadManager>,
        outgoing: Arc<OutgoingMessageSender>,
        arg0_paths: Arg0DispatchPaths,
        config: Arc<Con

作用：创建 ThreadRequestProcessor，把它需要用的管理器、存储、配置和发送器都装进去。

数据流：输入认证、线程管理、消息发送、配置、数据库、监听器等共享对象 → 保存到结构体字段里 → 输出一个可处理请求的处理器实例。

调用关系：服务启动组装请求处理链时会调用它，之后各种 thread/* 请求都依赖这个实例。

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

async fn thread_start(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadStartParams,
        app_server_client_name: Option<String>,
        app_server_client_version: Opt

作用：处理客户端的新建对话请求。

数据流：输入请求编号、启动参数、客户端信息和请求上下文 → 转交 thread_start_inner 异步启动 → 成功时不直接返回载荷，因为响应会由后台任务发送。

调用关系：handle_initialized_client_request 收到 thread/start 后调用它，它把重活交给 thread_start_inner。

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

async fn thread_unsubscribe(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadUnsubscribeParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：让某个连接取消订阅一个对话的实时事件。

数据流：输入请求编号和退订参数 → 调用内部退订逻辑 → 输出退订状态响应。

调用关系：客户端不想再收某个对话更新时由 handle_initialized_client_request 调用。

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

async fn thread_resume(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadResumeParams,
        app_server_client_name: Option<String>,
        app_server_client_version: O

作用：处理恢复旧对话请求，让客户端重新接上历史会话。

数据流：输入请求、恢复参数和客户端信息 → 交给 thread_resume_inner 查历史、建配置、接监听 → 成功响应由内部发送。

调用关系：handle_initialized_client_request 收到 thread/resume 后调用它。

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

async fn thread_fork(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadForkParams,
        app_server_client_name: Option<String>,
        app_server_client_version: Optio

作用：处理从旧对话复制出新分支的请求。

数据流：输入源对话、覆盖配置和客户端信息 → 转给 thread_fork_inner 读取历史并创建新对话 → 成功响应由内部发送。

调用关系：客户端想从某个历史点另开一条路时，由 handle_initialized_client_request 调用。

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

async fn thread_archive(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadArchiveParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：把对话归档，让它从普通列表里隐藏，同时通知客户端状态变化。

数据流：输入请求编号和归档参数 → 调用 thread_archive_inner 归档目标及可能的子对话 → 发送响应和 ThreadArchived 通知。

调用关系：handle_initialized_client_request 收到归档请求时调用；内部依赖 thread_archive_inner。

调用图：调用 1 个内部函数（thread_archive_inner）；被 1 处调用（handle_initialized_client_request）；外部调用 2 个（ThreadArchived, clone）。

async fn thread_increment_elicitation(
        &self,
        params: ThreadIncrementElicitationParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：增加某个对话的“外部等待确认”计数，让对话知道自己该暂停。

数据流：输入线程 ID → 内部找到运行中对话并把计数加一 → 输出新计数和是否暂停。

调用关系：handle_initialized_client_request 调用它，实际修改由 thread_increment_elicitation_inner 完成。

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

async fn thread_decrement_elicitation(
        &self,
        params: ThreadDecrementElicitationParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：减少“外部等待确认”计数，可能让暂停的对话恢复。

数据流：输入线程 ID → 找到对话并把计数减一 → 输出新计数和是否仍暂停。

调用关系：handle_initialized_client_request 调用它，实际工作交给 thread_decrement_elicitation_inner。

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

async fn thread_set_name(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadSetNameParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：给对话设置一个显示名称，并把变化通知其他客户端。

数据流：输入请求编号、线程 ID 和名称 → 内部清洗并保存名称 → 发送响应，必要时广播名称更新通知。

调用关系：handle_initialized_client_request 收到改名请求时调用。

调用图：调用 1 个内部函数（thread_set_name_response_inner）；被 1 处调用（handle_initialized_client_request）；外部调用 2 个（ThreadNameUpdated, clone）。

async fn thread_metadata_update(
        &self,
        params: ThreadMetadataUpdateParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：更新对话的额外信息，比如 Git 提交、分支和远端地址。

数据流：输入元数据更新参数 → 内部校验并写入存储 → 输出更新后的对话视图。

调用关系：由 handle_initialized_client_request 调用，细节在 thread_metadata_update_response_inner。

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

async fn thread_memory_mode_set(
        &self,
        params: ThreadMemoryModeSetParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：修改某个对话使用记忆的方式。

数据流：输入线程 ID 和记忆模式 → 转换成核心系统认识的值并写入元数据 → 输出空成功响应。

调用关系：handle_initialized_client_request 调用它，内部使用 thread_memory_mode_set_response_inner。

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

async fn memory_reset(
        &self,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：清空系统记忆数据，相当于把记忆本重置。

数据流：无业务输入 → 内部清数据库记忆记录和磁盘记忆目录 → 输出成功响应或错误。

调用关系：handle_initialized_client_request 收到 memory/reset 时调用。

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

async fn thread_unarchive(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadUnarchiveParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：把已归档对话恢复到普通可见状态，并通知客户端。

数据流：输入请求编号和线程 ID → 内部取消归档并构造对话信息 → 发送响应和 ThreadUnarchived 通知。

调用关系：handle_initialized_client_request 调用，实际读写由 thread_unarchive_inner 完成。

调用图：调用 1 个内部函数（thread_unarchive_inner）；被 1 处调用（handle_initialized_client_request）；外部调用 2 个（ThreadUnarchived, clone）。

async fn thread_compact_start(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadCompactStartParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：启动对话压缩，把长历史整理得更省上下文。

数据流：输入线程 ID → 找到运行中对话并提交压缩命令 → 输出启动成功响应。

调用关系：客户端发起压缩时由 handle_initialized_client_request 调用。

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

async fn thread_background_terminals_clean(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadBackgroundTerminalsCleanParams,
    ) -> Result<Option<ClientResponsePayload>

作用：要求某个对话清理后台终端进程记录。

数据流：输入线程 ID → 找到对话并提交清理后台终端命令 → 输出成功响应。

调用关系：handle_initialized_client_request 调用，内部交给核心线程执行。

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

async fn thread_background_terminals_list(
        &self,
        params: ThreadBackgroundTerminalsListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：列出某个对话里还在记录的后台终端。

数据流：输入线程 ID、游标和数量限制 → 内部读取并分页 → 输出终端列表和下一页游标。

调用关系：handle_initialized_client_request 收到列表请求时调用。

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

async fn thread_background_terminals_terminate(
        &self,
        params: ThreadBackgroundTerminalsTerminateParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：终止某个对话里的一个后台终端进程。

数据流：输入线程 ID 和进程 ID 字符串 → 解析进程 ID 并请求线程终止它 → 输出是否真的终止。

调用关系：handle_initialized_client_request 调用，实际动作在运行中的 CodexThread 上完成。

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

async fn thread_rollback(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRollbackParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：让对话回滚若干轮，撤掉最近的交互。

数据流：输入线程 ID 和回滚轮数 → 内部校验并提交回滚命令 → 成功时等待后续事件回复。

调用关系：handle_initialized_client_request 调用，thread_rollback_inner 继续处理。

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

async fn thread_list(
        &self,
        params: ThreadListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：返回保存过的对话列表。

数据流：输入分页、排序和筛选条件 → 内部查询存储并补上加载状态 → 输出列表响应。

调用关系：客户端打开历史列表时由 handle_initialized_client_request 调用。

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

async fn thread_search(
        &self,
        params: ThreadSearchParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：按关键词搜索历史对话。

数据流：输入搜索词、分页、排序和来源筛选 → 查询存储并过滤结果 → 输出带片段的搜索结果。

调用关系：handle_initialized_client_request 收到 thread/search 时调用。

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

async fn thread_loaded_list(
        &self,
        params: ThreadLoadedListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：列出当前内存里已经加载的对话 ID。

数据流：输入分页参数 → 内部取运行中线程 ID、排序和截页 → 输出 ID 列表。

调用关系：handle_initialized_client_request 调用，用于诊断或客户端同步。

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

async fn thread_read(
        &self,
        params: ThreadReadParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：读取一个对话的完整视图，可选择带上各轮内容。

数据流：输入线程 ID 和是否包含轮次 → 内部从存储和内存合成视图 → 输出 Thread 对象。

调用关系：handle_initialized_client_request 收到 thread/read 时调用。

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

async fn thread_turns_list(
        &self,
        params: ThreadTurnsListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：分页读取一个对话的轮次列表。

数据流：输入线程 ID、游标、数量、排序和内容详细程度 → 内部重建轮次并分页 → 输出一页轮次。

调用关系：handle_initialized_client_request 调用，适合客户端逐页加载长对话。

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

async fn thread_turns_items_list(
        &self,
        _params: ThreadTurnsItemsListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：占位函数，明确告诉客户端“逐项列出轮次内容”这个接口还没实现。

数据流：输入参数被忽略 → 直接构造 method_not_found 错误 → 不读取也不修改状态。

调用关系：handle_initialized_client_request 如果收到该方法会调用它，但它只返回不支持。

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

async fn thread_shell_command(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadShellCommandParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：在本机环境中为某个对话启动一条用户 shell 命令。

数据流：输入线程 ID 和命令字符串 → 内部校验非空、本机环境可用，再提交命令 → 输出启动成功响应。

调用关系：handle_initialized_client_request 调用，实际提交由 thread_shell_command_inner 完成。

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

async fn thread_approve_guardian_denied_action(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadApproveGuardianDeniedActionParams,
    ) -> Result<Option<ClientResponseP

作用：允许用户批准一个被 Guardian 拦下的动作。

数据流：输入线程 ID 和被拒事件 JSON → 内部解析事件并提交批准命令 → 输出成功响应。

调用关系：handle_initialized_client_request 调用，交给运行中的对话继续处理。

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

async fn conversation_summary(
        &self,
        params: GetConversationSummaryParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：读取某个对话的简短摘要，不加载完整历史。

数据流：输入对话 ID 或 rollout 文件路径 → 内部读取存储里的概要字段 → 输出 ConversationSummary。

调用关系：handle_initialized_client_request 调用，内部走 get_thread_summary_response_inner。

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

async fn load_thread(
        &self,
        thread_id: &str,
    ) -> Result<(ThreadId, Arc<CodexThread>), JSONRPCErrorError>

作用：按字符串形式的线程 ID 找到正在内存里运行的对话。

数据流：输入线程 ID 字符串 → 解析成内部 ID 并向线程管理器查找 → 输出内部 ID 和线程对象；找不到则报错。

调用关系：多个需要操作活跃对话的内部函数都会先调用它，比如压缩、回滚、后台终端和 shell 命令。

调用图：调用 1 个内部函数（from_string）；被 9 处调用（thread_approve_guardian_denied_action_inner, thread_background_terminals_clean_inner, thread_background_terminals_list_inner, thread_background_terminals_terminate_inner, thread_compact_start_inner, thread_decrement_elicitation_inner, thread_increment_elicitation_inner, thread_rollback_start, thread_shell_command_inner）。

async fn acquire_thread_list_state_permit(
        &self,
    ) -> Result<SemaphorePermit<'_>, JSONRPCErrorError>

作用：拿一张“列表状态修改通行证”，防止多个任务同时改影响列表的状态。

数据流：无业务输入 → 等待信号量许可（信号量就是限流牌） → 输出许可；拿不到则返回内部错误。

调用关系：归档、恢复、改名、更新元数据等会影响列表的流程会先调用它。

调用图：被 5 处调用（thread_archive_inner, thread_metadata_update_response_inner, thread_resume_inner, thread_set_name_response_inner, thread_unarchive_inner）。

async fn set_app_server_client_info(
        thread: &CodexThread,
        app_server_client_name: Option<String>,
        app_server_client_version: Option<String>,
    ) -> Result<(), JSONRPCErrorEr

作用：把客户端名称和版本记录到对话里，并处理 Xcode 26.4 的兼容行为。

数据流：输入线程对象、客户端名和版本 → 判断是否需要自动拒绝某类 MCP 询问 → 写入线程内部信息 → 输出成功或错误。

调用关系：新建、恢复、分叉和重连运行中对话时都会调用它。

调用图：调用 2 个内部函数（xcode_26_4_mcp_elicitations_auto_deny, set_app_server_client_info）。

async fn finalize_thread_teardown(&self, thread_id: ThreadId)

作用：彻底清理一个对话在 app-server 里的残留记录。

数据流：输入线程 ID → 从待卸载集合移除、取消相关请求、删除线程状态和监听登记 → 无返回值。

调用关系：退订、归档移除、连接关闭和恢复时替换旧线程都会用它收尾。

调用图：调用 2 个内部函数（remove_thread_state, remove_thread）；被 4 处调用（connection_closed, prepare_thread_for_removal, resume_running_thread, thread_unsubscribe_response_inner）；外部调用 1 个（to_string）。

async fn thread_unsubscribe_response_inner(
        &self,
        params: ThreadUnsubscribeParams,
        connection_id: ConnectionId,
    ) -> Result<ThreadUnsubscribeResponse, JSONRPCErrorError>

作用：执行退订，并告诉客户端结果是已退订、未订阅还是线程未加载。

数据流：输入退订参数和连接 ID → 解析线程 ID，检查线程是否存在，移除连接订阅 → 输出退订状态。

调用关系：thread_unsubscribe 的核心逻辑；线程已不在内存时会顺手调用 finalize_thread_teardown 清理。

调用图：调用 3 个内部函数（finalize_thread_teardown, unsubscribe_connection_from_thread, from_string）；被 1 处调用（thread_unsubscribe）。

async fn prepare_thread_for_archive(&self, thread_id: ThreadId)

作用：归档前把活跃对话停下来并清理现场。

数据流：输入线程 ID → 调用通用移除准备逻辑，操作名标记为 archive → 无直接输出。

调用关系：thread_archive_response 在真正写归档标记前调用它。

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

async fn prepare_thread_for_removal(&self, thread_id: ThreadId, operation: &str)

作用：从线程管理器移除一个对话，并尽量等它正常关停。

数据流：输入线程 ID 和操作名 → 如果对话活跃就发送关闭并等待，超时或失败会记录日志 → 最后清理 app-server 状态。

调用关系：目前由 prepare_thread_for_archive 调用，也可作为其他删除类操作的通用收尾。

调用图：调用 1 个内部函数（finalize_thread_teardown）；被 1 处调用（prepare_thread_for_archive）；外部调用 3 个（error!, info!, warn!）。

fn listener_task_context(&self) -> ListenerTaskContext

作用：打包启动监听任务所需的一组共享零件。

数据流：读取处理器里的线程管理器、状态管理器、消息发送器、配置等 → 克隆共享引用 → 输出 ListenerTaskContext。

调用关系：ensure_conversation_listener 和 ensure_listener_task_running 都靠它把上下文交给 thread_lifecycle 模块。

调用图：被 2 处调用（ensure_conversation_listener, ensure_listener_task_running）；外部调用 3 个（clone, clone, clone）。

async fn ensure_conversation_listener(
        &self,
        conversation_id: ThreadId,
        connection_id: ConnectionId,
        raw_events_enabled: bool,
    ) -> Result<EnsureConversationListen

作用：确保某个连接正在监听某个对话的事件。

数据流：输入线程 ID、连接 ID 和是否启用原始事件 → 构造监听上下文并调用生命周期模块 → 输出监听结果或错误。

调用关系：新建、恢复、分叉和手动补挂监听时会调用它。

调用图：调用 2 个内部函数（ensure_conversation_listener, listener_task_context）；被 3 处调用（thread_fork_inner, thread_resume_inner, try_attach_thread_listener）。

async fn ensure_listener_task_running(
        &self,
        conversation_id: ThreadId,
        conversation: Arc<CodexThread>,
        thread_state: Arc<Mutex<ThreadState>>,
    ) -> Result<(), JSON

作用：确保某个对话的后台监听任务还活着。

数据流：输入线程 ID、线程对象和线程状态 → 交给 thread_lifecycle 模块检查或启动任务 → 输出成功或错误。

调用关系：resume_running_thread 处理已经运行的对话重连时会调用它。

调用图：调用 2 个内部函数（ensure_listener_task_running, listener_task_context）；被 1 处调用（resume_running_thread）。

async fn thread_start_inner(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadStartParams,
        app_server_client_name: Option<String>,
        app_server_client_versio

作用：准备新建对话所需的参数，并把耗时启动放到后台任务里。

数据流：输入启动请求的所有字段 → 校验权限参数、解析环境、构造配置覆盖项和监听上下文 → 启动 thread_start_task，立即返回成功。

调用关系：thread_start 调用它；真正创建对话的工作由后台的 thread_start_task 完成，失败会主动发错误响应。

调用图：调用 3 个内部函数（request_trace, span, build_thread_config_overrides）；被 1 处调用（thread_start）；外部调用 7 个（clone, thread_start_task, spawn, clone, clone, clone, clone）。

async fn drain_background_tasks(&self)

作用：关闭时等待本处理器启动的后台任务结束。

数据流：无业务输入 → 关闭任务追踪器并最多等 10 秒 → 超时只记录警告。

调用关系：服务器 teardown 阶段调用，避免新建对话后台任务半路被丢。

调用图：被 1 处调用（drain_background_tasks）；外部调用 5 个（from_secs, close, wait, timeout, warn!）。

async fn clear_all_thread_listeners(&self)

作用：清空所有对话监听记录。

数据流：无输入 → 调用线程状态管理器清除监听者 → 无返回业务数据。

调用关系：连接或服务整体清理时由外层清理流程调用。

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

async fn shutdown_threads(&self)

作用：服务关闭时尽量关掉所有正在运行的对话。

数据流：无输入 → 要求线程管理器在 10 秒内关闭全部线程 → 对提交失败或超时的线程写警告日志。

调用关系：服务器退出流程调用它做善后。

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

async fn request_trace_context(
        &self,
        request_id: &ConnectionRequestId,
    ) -> Option<codex_protocol::protocol::W3cTraceContext>

作用：取出某个请求关联的追踪上下文，方便跨模块串起日志和性能追踪。

数据流：输入请求 ID → 从 outgoing 查询保存的 W3C trace context（标准追踪信息） → 输出可选追踪上下文。

调用关系：submit_core_op、恢复和分叉线程时会调用它，把追踪信息传给核心层。

调用图：被 3 处调用（submit_core_op, thread_fork_inner, thread_resume_inner）。

async fn submit_core_op(
        &self,
        request_id: &ConnectionRequestId,
        thread: &CodexThread,
        op: Op,
    ) -> CodexResult<String>

作用：把一个操作命令提交给核心对话，并带上追踪信息。

数据流：输入请求 ID、线程对象和 Op 命令 → 读取追踪上下文并调用 submit_with_trace → 输出核心层返回的操作 ID 或错误。

调用关系：回滚、压缩、清理终端、shell 命令和批准 Guardian 动作都通过它提交。

调用图：调用 2 个内部函数（request_trace_context, submit_with_trace）；被 5 处调用（thread_approve_guardian_denied_action_inner, thread_background_terminals_clean_inner, thread_compact_start_inner, thread_rollback_start, thread_shell_command_inner）。

async fn thread_start_task(
        listener_task_context: ListenerTaskContext,
        config_manager: ConfigManager,
        request_id: ConnectionRequestId,
        app_server_client_name: Option<S

作用：真正创建新对话、装配配置、工具、监听器，并给客户端发启动响应。

数据流：输入监听上下文、配置覆盖、动态工具、客户端信息、来源和追踪信息 → 加载配置、处理项目信任、校验工具、启动核心线程、挂监听、生成 API 响应和通知 → 发送 ThreadStartResponse 和 ThreadStarted 通知。

调用关系：thread_start_inner 把它作为后台任务启动；它调用 validate_dynamic_tools、build_thread_from_snapshot、ensure_conversation_listener 等完成完整启动流程。

调用图：调用 10 个内部函数（current_cli_overrides, load_with_cli_overrides, load_with_overrides, ensure_conversation_listener, build_thread_from_snapshot, permission_profile_trusts_project, requested_permissions_trust_project, validate_dynamic_tools, set_project_trust_level, new）；外部调用 12 个（set_app_server_client_info, ThreadStarted, String, Table, clone, initialize_executor_plugin_thread_data, clone, once, now, new (+2 more)）。

fn build_thread_config_overrides(
        &self,
        model: Option<String>,
        model_provider: Option<String>,
        service_tier: Option<Option<String>>,
        cwd: Option<String>,

作用：把请求里的模型、目录、权限、说明文字等转换成核心配置覆盖对象。

数据流：输入一组可选请求字段 → 转换枚举和值，并补上沙盒可执行文件路径 → 输出 ConfigOverrides。

调用关系：新建、恢复和分叉对话都会先用它整理配置。

调用图：被 3 处调用（thread_fork_inner, thread_resume_inner, thread_start_inner）；外部调用 1 个（default）。

async fn thread_archive_inner(
        &self,
        params: ThreadArchiveParams,
    ) -> Result<(ThreadArchiveResponse, Vec<String>), JSONRPCErrorError>

作用：给归档操作加上列表状态锁，再执行归档。

数据流：输入归档参数 → 先获取列表状态许可 → 调用 thread_archive_response → 输出归档响应和被归档 ID 列表。

调用关系：thread_archive 调用它，防止归档和列表/恢复等操作互相打架。

调用图：调用 2 个内部函数（acquire_thread_list_state_permit, thread_archive_response）；被 1 处调用（thread_archive）。

async fn thread_archive_response(
        &self,
        params: ThreadArchiveParams,
    ) -> Result<(ThreadArchiveResponse, Vec<String>), JSONRPCErrorError>

作用：执行真正的归档，包括一起处理派生出来的子对话。

数据流：输入线程 ID → 查找该线程及其 spawn 子树，跳过已归档项，逐个停掉活跃线程并写归档标记 → 输出响应和成功归档的 ID。

调用关系：thread_archive_inner 调用它；它会用 state_db_spawn_subtree_thread_ids 找子对话，用 prepare_thread_for_archive 停线程。

调用图：调用 4 个内部函数（prepare_thread_for_archive, state_db_spawn_subtree_thread_ids, thread_store_archive_error, from_string）；被 1 处调用（thread_archive_inner）；外部调用 2 个（new, warn!）。

async fn state_db_spawn_subtree_thread_ids(
        &self,
        thread_id: ThreadId,
    ) -> Result<Vec<ThreadId>, JSONRPCErrorError>

作用：找出某个对话通过 spawn 派生出的后代对话 ID。

数据流：输入根线程 ID → 如果有状态数据库就查询后代并去重，否则只返回根 ID → 输出 ID 列表。

调用关系：thread_archive_response 用它决定归档一个父对话时还要考虑哪些子对话。

调用图：被 1 处调用（thread_archive_response）；外部调用 2 个（from, vec!）。

async fn thread_increment_elicitation_inner(
        &self,
        params: ThreadIncrementElicitationParams,
    ) -> Result<ThreadIncrementElicitationResponse, JSONRPCErrorError>

作用：给运行中的对话增加一个外部询问挂起计数。

数据流：输入线程 ID → load_thread 找到对话，调用线程计数加一 → 输出新计数和 paused 状态。

调用关系：thread_increment_elicitation 调用它。

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

async fn thread_decrement_elicitation_inner(
        &self,
        params: ThreadDecrementElicitationParams,
    ) -> Result<ThreadDecrementElicitationResponse, JSONRPCErrorError>

作用：给运行中的对话减少一个外部询问挂起计数。

数据流：输入线程 ID → load_thread 找到对话，调用线程计数减一 → 输出新计数和 paused 状态；非法减少会变成客户端错误。

调用关系：thread_decrement_elicitation 调用它。

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

async fn thread_set_name_response_inner(
        &self,
        params: ThreadSetNameParams,
    ) -> Result<(ThreadSetNameResponse, Option<ThreadNameUpdatedNotification>), JSONRPCErrorError>

作用：校验并保存对话名称。

数据流：输入线程 ID 和名称 → 解析 ID、规范化名称、拿列表状态许可、写元数据补丁 → 输出空响应和名称更新通知内容。

调用关系：thread_set_name 调用它，并负责把通知发出去。

调用图：调用 3 个内部函数（acquire_thread_list_state_permit, normalize_thread_name, from_string）；被 1 处调用（thread_set_name）；外部调用 1 个（default）。

async fn thread_memory_mode_set_response_inner(
        &self,
        params: ThreadMemoryModeSetParams,
    ) -> Result<ThreadMemoryModeSetResponse, JSONRPCErrorError>

作用：把对话记忆模式写入元数据。

数据流：输入线程 ID 和 API 层记忆模式 → 转成核心模式后更新线程元数据 → 输出空成功响应。

调用关系：thread_memory_mode_set 的内部实现。

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

async fn memory_reset_response_inner(&self) -> Result<MemoryResetResponse, JSONRPCErrorError>

作用：执行记忆重置的实际清理动作。

数据流：读取状态数据库句柄和 codex_home 路径 → 清空数据库里的 memory 行，再删除记忆目录内容 → 输出空响应。

调用关系：memory_reset 调用它；如果状态库不可用或磁盘清理失败会返回内部错误。

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

async fn thread_metadata_update_response_inner(
        &self,
        params: ThreadMetadataUpdateParams,
    ) -> Result<ThreadMetadataUpdateResponse, JSONRPCErrorError>

作用：更新对话的 Git 信息并返回最新对话视图。

数据流：输入线程 ID 和 gitInfo → 校验至少有字段、清洗空白值、写入元数据 → 重新构造 Thread，补名称和加载状态 → 输出更新后的 Thread。

调用关系：thread_metadata_update 调用它；它使用 normalize_thread_metadata_git_field、thread_from_stored_thread 和 attach_thread_name。

调用图：调用 5 个内部函数（acquire_thread_list_state_permit, attach_thread_name, thread_from_stored_thread, loaded_status_for_thread, from_string）；被 1 处调用（thread_metadata_update）；外部调用 2 个（default, normalize_thread_metadata_git_field）。

fn normalize_thread_metadata_git_field(
        value: Option<Option<String>>,
        name: &str,
    ) -> Result<Option<Option<String>>, JSONRPCErrorError>

作用：清洗一个 Git 元数据字段，避免保存空字符串。

数据流：输入可选的可清空字符串和字段名 → 有字符串就 trim，空则报错；显式 null 表示清空 → 输出补丁格式的字段值。

调用关系：thread_metadata_update_response_inner 用它处理 sha、branch、originUrl 三个字段。

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

async fn thread_unarchive_inner(
        &self,
        params: ThreadUnarchiveParams,
    ) -> Result<(ThreadUnarchiveResponse, ThreadUnarchivedNotification), JSONRPCErrorError>

作用：给取消归档操作加锁，并包装通知内容。

数据流：输入取消归档参数 → 获取列表状态许可，调用 thread_unarchive_response → 输出响应和 ThreadUnarchived 通知。

调用关系：thread_unarchive 调用它并负责发送响应和通知。

调用图：调用 2 个内部函数（acquire_thread_list_state_permit, thread_unarchive_response）；被 1 处调用（thread_unarchive）。

async fn thread_unarchive_response(
        &self,
        params: ThreadUnarchiveParams,
    ) -> Result<(ThreadUnarchiveResponse, String), JSONRPCErrorError>

作用：把一个归档对话恢复成未归档，并构造客户端可看的对话对象。

数据流：输入线程 ID → 存储层取消归档，转换为 API Thread，补加载状态和名称 → 输出响应和线程 ID 字符串。

调用关系：thread_unarchive_inner 调用它。

调用图：调用 4 个内部函数（attach_thread_name, thread_from_stored_thread, loaded_status_for_thread, from_string）；被 1 处调用（thread_unarchive_inner）。

async fn thread_rollback_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRollbackParams,
    ) -> Result<(), JSONRPCErrorError>

作用：回滚请求的薄包装。

数据流：输入请求 ID 和回滚参数 → 直接转给 thread_rollback_start → 输出成功或错误。

调用关系：thread_rollback 调用它。

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

async fn thread_rollback_start(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRollbackParams,
    ) -> Result<(), JSONRPCErrorError>

作用：启动一次对话回滚，并防止同一对话同时回滚两次。

数据流：输入线程 ID 和回滚轮数 → 校验轮数、找到线程、在状态里登记待处理请求、提交 ThreadRollback 命令 → 成功无立即响应载荷；失败会清掉登记。

调用关系：thread_rollback_inner 调用它；后续回滚结果会由监听事件流程完成响应。

调用图：调用 3 个内部函数（load_thread, submit_core_op, thread_state）；被 1 处调用（thread_rollback_inner）；外部调用 2 个（clone, format!）。

async fn thread_compact_start_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadCompactStartParams,
    ) -> Result<ThreadCompactStartResponse, JSONRPCErrorError>

作用：向运行中对话提交压缩命令。

数据流：输入线程 ID → load_thread 找到线程，submit_core_op 提交 Compact → 输出空成功响应。

调用关系：thread_compact_start 调用它。

调用图：调用 2 个内部函数（load_thread, submit_core_op）；被 1 处调用（thread_compact_start）。

async fn thread_background_terminals_clean_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadBackgroundTerminalsCleanParams,
    ) -> Result<ThreadBackgroundTermina

作用：向运行中对话提交清理后台终端命令。

数据流：输入线程 ID → 找到线程并提交 CleanBackgroundTerminals → 输出空成功响应。

调用关系：thread_background_terminals_clean 调用它。

调用图：调用 2 个内部函数（load_thread, submit_core_op）；被 1 处调用（thread_background_terminals_clean）。

async fn thread_background_terminals_list_inner(
        &self,
        params: ThreadBackgroundTerminalsListParams,
    ) -> Result<ThreadBackgroundTerminalsListResponse, JSONRPCErrorError>

作用：读取并分页返回后台终端列表。

数据流：输入线程 ID、游标和限制 → 找到线程，读取后台终端，转换成 API 结构，再分页 → 输出数据和下一页游标。

调用关系：thread_background_terminals_list 调用它，分页由 paginate_background_terminals 完成。

调用图：调用 2 个内部函数（load_thread, paginate_background_terminals）；被 1 处调用（thread_background_terminals_list）。

async fn thread_background_terminals_terminate_inner(
        &self,
        params: ThreadBackgroundTerminalsTerminateParams,
    ) -> Result<ThreadBackgroundTerminalsTerminateResponse, JSONRPCErrorE

作用：终止指定后台终端。

数据流：输入线程 ID 和进程 ID 字符串 → 解析成数字，找到线程，调用终止方法 → 输出 terminated 布尔值。

调用关系：thread_background_terminals_terminate 调用它。

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

async fn thread_shell_command_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadShellCommandParams,
    ) -> Result<ThreadShellCommandResponse, JSONRPCErrorError>

作用：校验并提交本机 shell 命令。

数据流：输入线程 ID 和命令 → 去掉首尾空白，检查非空和本机环境可用 → 提交 RunUserShellCommand → 输出空响应。

调用关系：thread_shell_command 调用它；它通过 submit_core_op 把命令交给核心线程。

调用图：调用 2 个内部函数（load_thread, submit_core_op）；被 1 处调用（thread_shell_command）。

async fn thread_approve_guardian_denied_action_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadApproveGuardianDeniedActionParams,
    ) -> Result<ThreadApproveGua

作用：把用户批准的 Guardian 拦截事件交回核心对话。

数据流：输入线程 ID 和事件 JSON → 反序列化事件，找到线程，提交 ApproveGuardianDeniedAction → 输出空响应。

调用关系：thread_approve_guardian_denied_action 调用它。

调用图：调用 2 个内部函数（load_thread, submit_core_op）；被 1 处调用（thread_approve_guardian_denied_action）；外部调用 1 个（from_value）。

async fn thread_list_response_inner(
        &self,
        params: ThreadListParams,
    ) -> Result<ThreadListResponse, JSONRPCErrorError>

作用：构造对话列表响应。

数据流：输入分页、排序、模型供应商、来源、目录、搜索词等筛选 → 规范化参数，调用 list_threads_common，转换存储对象并补加载状态 → 输出 ThreadListResponse。

调用关系：thread_list 调用它；公共分页查询由 list_threads_common 完成。

调用图：调用 4 个内部函数（list_threads_common, normalize_thread_list_cwd_filters, thread_from_stored_thread, loaded_statuses_for_threads）；被 1 处调用（thread_list）；外部调用 1 个（with_capacity）。

async fn thread_search_response_inner(
        &self,
        params: ThreadSearchParams,
    ) -> Result<ThreadSearchResponse, JSONRPCErrorError>

作用：执行关键词搜索并返回带片段的对话结果。

数据流：输入搜索参数 → 校验搜索词非空，循环查询存储直到凑够一页或没数据，按来源再过滤 → 转成 API 结果并补加载状态 → 输出 ThreadSearchResponse。

调用关系：thread_search 调用它；与列表逻辑类似，但用 search_threads 并保留 snippet。

调用图：调用 2 个内部函数（thread_from_stored_thread, loaded_statuses_for_threads）；被 1 处调用（thread_search）；外部调用 1 个（with_capacity）。

async fn thread_loaded_list_response_inner(
        &self,
        params: ThreadLoadedListParams,
    ) -> Result<ThreadLoadedListResponse, JSONRPCErrorError>

作用：分页列出当前已加载线程 ID。

数据流：输入游标和限制 → 从线程管理器拿 ID，排序，按游标截取一页 → 输出 ID 列表和下一页游标。

调用关系：thread_loaded_list 调用它。

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

async fn thread_read_response_inner(
        &self,
        params: ThreadReadParams,
    ) -> Result<ThreadReadResponse, JSONRPCErrorError>

作用：处理 thread/read 的参数解析和错误转换。

数据流：输入线程 ID 和 include_turns → 解析 ID，调用 read_thread_view → 输出 ThreadReadResponse。

调用关系：thread_read 调用它；真正合成视图在 read_thread_view。

调用图：调用 2 个内部函数（read_thread_view, from_string）；被 1 处调用（thread_read）。

async fn read_thread_view(
        &self,
        thread_id: ThreadId,
        include_turns: bool,
    ) -> Result<Thread, ThreadReadViewError>

作用：把磁盘保存的对话和内存里的活跃状态合成一个客户端视图。

数据流：输入线程 ID 和是否包含轮次 → 根据线程是否加载、是否需要轮次，选择读存储或读活线程；最后设置状态并中断过期的进行中轮次 → 输出 Thread。

调用关系：thread_read_response_inner 调用它；它再调用 load_persisted_thread_for_read 或 load_live_thread_view。

调用图：调用 3 个内部函数（load_live_thread_view, load_persisted_thread_for_read, loaded_status_for_thread）；被 1 处调用（thread_read_response_inner）；外部调用 3 个（InvalidRequest, format!, matches!）。

async fn load_persisted_thread_for_read(
        &self,
        thread_id: ThreadId,
        include_turns: bool,
    ) -> Result<Option<Thread>, ThreadReadViewError>

作用：从持久化存储读取对话，必要时带历史轮次。

数据流：输入线程 ID 和 include_turns → 调 thread_store 读取，转换成 API Thread；带历史时重建 turns → 输出 Some(Thread)、None 或读取错误。

调用关系：read_thread_view 用它优先读取已经落盘的对话。

调用图：调用 1 个内部函数（thread_from_stored_thread）；被 1 处调用（read_thread_view）；外部调用 3 个（Internal, InvalidRequest, format!）。

async fn load_live_thread_view(
        &self,
        thread_id: ThreadId,
        include_turns: bool,
        loaded_thread: &CodexThread,
        persisted_thread: Option<Thread>,
    ) -> Result<

作用：从正在运行的对话构造 thread/read 视图。

数据流：输入线程 ID、是否包含轮次、活线程和可选持久化元数据 → 读取配置快照，处理 ephemeral 不能读历史的限制，合并持久化字段和活状态 → 输出 Thread。

调用关系：read_thread_view 在对话还没完整落盘或需要最新状态时调用它。

调用图：调用 3 个内部函数（apply_thread_read_store_fields, build_thread_from_loaded_snapshot, config_snapshot）；被 1 处调用（read_thread_view）；外部调用 1 个（InvalidRequest）。

async fn apply_thread_read_store_fields(
        &self,
        thread_id: ThreadId,
        thread: &mut Thread,
        include_turns: bool,
        loaded_thread: &CodexThread,
    ) -> Result<(),

作用：给 thread/read 的结果补上存储层字段，比如名称和历史轮次。

数据流：输入线程 ID、可修改 Thread、是否包含轮次和活线程 → 补名称；如果要轮次，就从活线程加载历史并构建 turns → 修改传入 Thread。

调用关系：load_live_thread_view 调用它做最后补全。

调用图：调用 2 个内部函数（attach_thread_name, load_history）；被 1 处调用（load_live_thread_view）。

async fn thread_turns_list_response_inner(
        &self,
        params: ThreadTurnsListParams,
    ) -> Result<ThreadTurnsListResponse, JSONRPCErrorError>

作用：分页返回某个对话的轮次，并合并当前正在进行的轮次快照。

数据流：输入线程 ID、分页和显示选项 → 加载历史，查看是否有活线程和 active turn，构建分页响应 → 输出 ThreadTurnsListResponse。

调用关系：thread_turns_list 调用它；最终分页由 build_thread_turns_page_response 完成。

调用图：调用 5 个内部函数（load_thread_turns_list_history, build_thread_turns_page_response, thread_state, loaded_status_for_thread, from_string）；被 1 处调用（thread_turns_list）；外部调用 1 个（matches!）。

async fn load_thread_turns_list_history(
        &self,
        thread_id: ThreadId,
    ) -> Result<Vec<RolloutItem>, ThreadReadViewError>

作用：为 thread/turns/list 读取原始历史条目。

数据流：输入线程 ID → 优先从存储读取 rollout 历史；如果没有但线程在运行，则从活线程加载；ephemeral 对话拒绝读取 → 输出 RolloutItem 列表。

调用关系：thread_turns_list_response_inner 调用它。

调用图：被 1 处调用（thread_turns_list_response_inner）；外部调用 3 个（Internal, InvalidRequest, format!）。

fn thread_created_receiver(&self) -> broadcast::Receiver<ThreadId>

作用：提供一个接收“新线程创建”广播的通道。

数据流：无输入 → 向线程管理器订阅创建事件 → 输出 broadcast receiver。

调用关系：外层需要监听新对话创建时调用。

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

async fn connection_initialized(
        &self,
        connection_id: ConnectionId,
        capabilities: ConnectionCapabilities,
    )

作用：记录一个客户端连接已经初始化，以及它支持哪些能力。

数据流：输入连接 ID 和能力列表 → 写入线程状态管理器 → 无响应载荷。

调用关系：连接初始化流程和 handle_client_request 会调用它。

调用图：调用 1 个内部函数（connection_initialized）；被 2 处调用（connection_initialized, handle_client_request）。

async fn connection_closed(&self, connection_id: ConnectionId)

作用：客户端连接断开时，清理它订阅过的对话。

数据流：输入连接 ID → 从状态管理器移除该连接，拿到受影响线程 → 如果线程已经不存在，就 finalize 清理残留状态。

调用关系：连接关闭流程调用它。

调用图：调用 2 个内部函数（finalize_thread_teardown, remove_connection）；被 1 处调用（connection_closed）。

fn subscribe_running_assistant_turn_count(&self) -> watch::Receiver<usize>

作用：订阅当前正在运行的助手轮次数量。

数据流：无输入 → 从 thread_watch_manager 获取 watch receiver（会推送最新值的通道） → 输出接收器。

调用关系：外层状态栏或监控模块会调用它。

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

async fn try_attach_thread_listener(
        &self,
        thread_id: ThreadId,
        connection_ids: Vec<ConnectionId>,
    )

作用：尽力把一批已初始化连接挂到某个对话监听上。

数据流：输入线程 ID 和连接 ID 列表 → 如果线程已加载就更新观察管理器并继承父线程 raw events 设置 → 逐个连接尝试挂监听并记录结果。

调用关系：外部需要补订阅线程事件时调用；内部用 ensure_conversation_listener。

调用图：调用 4 个内部函数（ensure_conversation_listener, build_thread_from_snapshot, thread_state, upsert_thread）；被 1 处调用（try_attach_thread_listener）。

async fn thread_resume_inner(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadResumeParams,
        app_server_client_name: Option<String>,
        app_server_client_vers

作用：恢复对话的主流程，既处理已运行对话重连，也处理冷启动恢复。

数据流：输入请求、恢复参数和客户端信息 → 检查卸载中和权限冲突，尝试接回运行中线程；否则读历史、合并旧配置、加载配置、恢复核心线程、挂监听、构造响应和可选初始轮次页 → 发送响应、用量更新和目标状态。

调用关系：thread_resume 调用它；它串起 resume_running_thread、resume_thread_from_rollout、load_and_apply_persisted_resume_metadata、load_thread_from_resume_source_or_send_internal 等多个步骤。

调用图：调用 16 个内部函数（load_for_cwd, emit_resume_goal_snapshot_and_continue, acquire_thread_list_state_permit, build_thread_config_overrides, ensure_conversation_listener, load_and_apply_persisted_resume_metadata, load_thread_from_resume_source_or_send_internal, request_trace_context, resume_running_thread, resume_thread_from_history (+6 more)）；被 1 处调用（thread_resume）；外部调用 2 个（set_app_server_client_info, format!）。

async fn load_and_apply_persisted_resume_metadata(
        &self,
        thread_history: &InitialHistory,
        request_overrides: &mut Option<HashMap<String, serde_json::Value>>,
        typesafe_

作用：恢复旧对话时读取数据库里的旧模型元数据并应用到配置。

数据流：输入 InitialHistory、请求配置覆盖和类型化覆盖 → 如果是 Resumed 历史且数据库有元数据，就调用 merge_persisted_resume_metadata → 返回读到的元数据或 None。

调用关系：thread_resume_inner 在加载配置前调用它，避免恢复时意外换模型。

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

async fn resume_running_thread(
        &self,
        request_id: &ConnectionRequestId,
        params: &ThreadResumeParams,
        app_server_client_name: Option<String>,
        app_server_client_

作用：处理“要恢复的对话其实已经在内存里运行”的情况。

数据流：输入请求 ID、恢复参数和客户端信息 → 查运行中线程与存储历史，检查路径和配置差异；能直接重连就让监听器发送恢复响应，必要时关闭无订阅的空闲缓存线程 → 输出已处理或未运行结果。

调用关系：thread_resume_inner 首先调用它；它用 collect_resume_override_mismatches、ensure_listener_task_running、stored_thread_to_api_thread 等辅助。

调用图：调用 10 个内部函数（pending_resume_goal_state, ensure_listener_task_running, finalize_thread_teardown, read_stored_thread_for_resume, stored_thread_to_api_thread, collect_resume_override_mismatches, subscribed_connection_ids, thread_state, loaded_status_for_thread, from_string）；被 1 处调用（thread_resume_inner）；外部调用 10 个（new, set_app_server_client_info, clone, NotRunning, SendThreadResumeResponse, format!, matches!, paths_match_after_normalization, warn!, warn!）。

async fn resume_thread_from_history(
        &self,
        history: &[ResponseItem],
    ) -> Result<InitialHistory, JSONRPCErrorError>

作用：把客户端直接传来的历史数组转换成可恢复的初始历史。

数据流：输入 ResponseItem 列表 → 校验非空，把每项包成 RolloutItem → 输出 InitialHistory::Forked。

调用关系：thread_resume_inner 在请求自带 history 时调用它。

调用图：被 1 处调用（thread_resume_inner）；外部调用 3 个（is_empty, iter, Forked）。

async fn resume_thread_from_rollout(
        &self,
        thread_id: &str,
        path: Option<&PathBuf>,
    ) -> Result<(InitialHistory, StoredThread), JSONRPCErrorError>

作用：从已保存的 rollout 历史文件恢复对话。

数据流：输入线程 ID 字符串和可选路径 → 读取 StoredThread，再转换成 InitialHistory → 输出历史和源 StoredThread。

调用关系：thread_resume_inner 冷恢复且没有直接 history 时调用它。

调用图：调用 2 个内部函数（read_stored_thread_for_resume, stored_thread_to_initial_history）；被 1 处调用（thread_resume_inner）。

async fn read_stored_thread_for_resume(
        &self,
        thread_id: &str,
        path: Option<&PathBuf>,
        include_history: bool,
    ) -> Result<StoredThread, JSONRPCErrorError>

作用：按线程 ID 或 rollout 路径读取用于恢复/分叉的已保存对话。

数据流：输入线程 ID、可选路径和是否带历史 → 从 thread_store 读取，拒绝已归档对话 → 输出 StoredThread。

调用关系：resume_running_thread、resume_thread_from_rollout 和 thread_fork_inner 都用它。

调用图：调用 1 个内部函数（from_string）；被 3 处调用（resume_running_thread, resume_thread_from_rollout, thread_fork_inner）；外部调用 1 个（format!）。

async fn stored_thread_to_initial_history(
        &self,
        stored_thread: &StoredThread,
    ) -> Result<InitialHistory, JSONRPCErrorError>

作用：把已保存对话里的历史包装成核心层可恢复的 InitialHistory。

数据流：输入 StoredThread → 取出 history items、线程 ID 和 rollout 路径 → 输出 InitialHistory::Resumed；没有历史则报内部错误。

调用关系：resume_thread_from_rollout 和 thread_resume_inner 用它复用存储历史。

调用图：被 2 处调用（resume_thread_from_rollout, thread_resume_inner）；外部调用 1 个（Resumed）。

fn stored_thread_to_api_thread(
        &self,
        stored_thread: StoredThread,
        fallback_provider: &str,
        include_turns: bool,
    ) -> Thread

作用：把存储层的 StoredThread 转成客户端 API 里的 Thread。

数据流：输入 StoredThread、备用模型供应商和是否包含轮次 → 调 thread_from_stored_thread 转基础字段，必要时从历史填 turns → 输出 Thread。

调用关系：resume_running_thread 和 thread_fork_inner 用它构造响应里的对话摘要。

调用图：调用 1 个内部函数（thread_from_stored_thread）；被 2 处调用（resume_running_thread, thread_fork_inner）。

async fn read_stored_thread_for_new_fork(
        &self,
        thread_id: ThreadId,
        include_history: bool,
    ) -> Result<StoredThread, JSONRPCErrorError>

作用：读取刚创建出来的分叉对话的存储记录。

数据流：输入新线程 ID 和是否带历史 → 从 thread_store 读取，包括已归档也允许 → 输出 StoredThread 或恢复读取错误。

调用关系：thread_fork_inner 在持久化分叉创建后调用它来构造响应。

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

async fn load_thread_from_resume_source_or_send_internal(
        &self,
        thread_id: ThreadId,
        thread: &CodexThread,
        thread_history: &InitialHistory,
        rollout_path: &Path

作用：恢复成功后，构造要发给客户端的 Thread 对象。

数据流：输入新线程 ID、活线程、初始历史、rollout 路径、可选源存储线程和是否带轮次 → 根据是 Resumed 还是 Forked 读取或生成基础 Thread，修正 ID、session、路径，填 turns 和名称 → 输出 Thread 或错误文字。

调用关系：thread_resume_inner 恢复核心线程成功后调用它。

调用图：调用 7 个内部函数（attach_thread_name, build_thread_from_snapshot, preview_from_rollout_items, thread_from_stored_thread, config_snapshot, session_configured, get_rollout_items）；被 1 处调用（thread_resume_inner）；外部调用 4 个（into, to_path_buf, format!, to_string）。

async fn attach_thread_name(&self, thread_id: ThreadId, thread: &mut Thread)

作用：从存储里补上用户给对话设置的名称。

数据流：输入线程 ID 和可修改 Thread → 读取存储记录，若 name 非空且不同于预览，就写入 Thread.name → 无返回值。

调用关系：读取、恢复、取消归档和元数据更新构造 Thread 时会调用它。

调用图：调用 1 个内部函数（set_thread_name_from_title）；被 4 处调用（apply_thread_read_store_fields, load_thread_from_resume_source_or_send_internal, thread_metadata_update_response_inner, thread_unarchive_response）。

async fn thread_fork_inner(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadForkParams,
        app_server_client_name: Option<String>,
        app_server_client_version:

作用：从已有对话历史创建一个新分支对话。

数据流：输入源线程、配置覆盖和客户端信息 → 读取源历史，加载新配置，调用核心分叉，继承名称，挂监听，构造响应和通知，可选发送历史用量更新 → 发送 ThreadForkResponse 和 ThreadStarted 通知。

调用关系：thread_fork 调用它；它复用 read_stored_thread_for_resume、build_thread_config_overrides、stored_thread_to_api_thread 等。

调用图：调用 12 个内部函数（load_for_cwd, build_thread_config_overrides, ensure_conversation_listener, read_stored_thread_for_new_fork, read_stored_thread_for_resume, request_trace_context, stored_thread_to_api_thread, build_thread_from_snapshot, preview_from_rollout_items, set_thread_name_from_title (+2 more)）；被 1 处调用（thread_fork）；外部调用 7 个（default, set_app_server_client_info, ThreadStarted, cfg!, from_config, Resumed, json!）。

async fn get_thread_summary_response_inner(
        &self,
        params: GetConversationSummaryParams,
    ) -> Result<GetConversationSummaryResponse, JSONRPCErrorError>

作用：读取对话摘要的内部实现。

数据流：输入按 ID 或路径查询的参数 → 从 thread_store 或本地存储读取不含历史的 StoredThread → 转成 ConversationSummary → 输出摘要响应。

调用关系：conversation_summary 调用它。

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

async fn list_threads_common(
        &self,
        requested_page_size: usize,
        cursor: Option<String>,
        sort_key: StoreThreadSortKey,
        sort_direction: SortDirection,
        fi

作用：对话列表查询的公共分页和过滤逻辑。

数据流：输入页大小、游标、排序和过滤器 → 循环调用 thread_store.list_threads，按来源和目录做二次过滤，防止游标重复导致死循环 → 输出 StoredThread 列表和下一页游标。

调用关系：thread_list_response_inner 调用它；搜索接口有自己的相似逻辑。

调用图：被 1 处调用（thread_list_response_inner）；外部调用 3 个（new, with_capacity, vec!）。

fn xcode_26_4_mcp_elicitations_auto_deny(
    client_name: Option<&str>,
    client_version: Option<&str>,
) -> bool

作用：判断是否要为 Xcode 26.4 自动拒绝 MCP elicitation 请求。

数据流：输入客户端名和版本 → 检查是否正好是 Xcode 且版本以 26.4 开头 → 输出布尔值。

调用关系：set_app_server_client_info 调用它，这是一个兼容旧客户端的临时判断。

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

fn thread_backwards_cursor_for_sort_key(
    thread: &StoredThread,
    sort_key: StoreThreadSortKey,
    sort_direction: SortDirection,
) -> Option<String>

作用：为列表反向翻页生成游标。

数据流：输入存储线程、排序字段和方向 → 取创建或更新时间，并按方向偏移 1 毫秒 → 输出 RFC3339 时间字符串游标。

调用关系：列表和搜索响应用它给客户端提供 backwards_cursor。

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

fn paginate_thread_turns(
    turns: Vec<Turn>,
    cursor: Option<&str>,
    limit: Option<u32>,
    sort_direction: SortDirection,
) -> Result<ThreadTurnsPage, JSONRPCErrorError>

作用：把一堆对话轮次按游标、限制和排序方向切成一页。

数据流：输入 turns、游标、limit 和排序方向 → 解析锚点，按升序或降序过滤，截取一页，生成前后游标 → 输出 ThreadTurnsPage。

调用关系：build_thread_turns_page_response 调用它。

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

fn serialize_thread_turns_cursor(
    turn_id: &str,
    include_anchor: bool,
) -> Result<String, JSONRPCErrorError>

作用：把轮次分页游标编码成字符串。

数据流：输入 turn_id 和是否包含锚点 → 序列化成 JSON 字符串 → 输出游标字符串或内部错误。

调用关系：paginate_thread_turns 用它生成 next_cursor 和 backwards_cursor。

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

fn parse_thread_turns_cursor(cursor: &str) -> Result<ThreadTurnsCursor, JSONRPCErrorError>

作用：把客户端传回的轮次分页游标解析回来。

数据流：输入游标字符串 → 按 JSON 解析成 ThreadTurnsCursor → 输出游标对象；格式错则返回参数错误。

调用关系：paginate_thread_turns 在开始分页时调用它。

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

fn build_thread_turns_page_response(
    items: &[RolloutItem],
    loaded_status: ThreadStatus,
    has_live_running_thread: bool,
    active_turn: Option<Turn>,
    options: ThreadTurnsPageOptions<'

作用：从原始历史构造一页 thread/turns/list 响应。

数据流：输入 rollout items、加载状态、是否有活跃运行、当前活跃轮次和分页选项 → 重建 turns、应用显示粒度、分页 → 输出 ThreadTurnsListResponse。

调用关系：thread_turns_list_response_inner 和 build_thread_resume_initial_turns_page 都用它。

调用图：调用 3 个内部函数（apply_thread_turns_items_view, paginate_thread_turns, reconstruct_thread_turns_for_turns_list）；被 2 处调用（thread_turns_list_response_inner, build_thread_resume_initial_turns_page）。

fn build_thread_resume_initial_turns_page(
    items: &[RolloutItem],
    loaded_status: ThreadStatus,
    has_live_running_thread: bool,
    active_turn: Option<Turn>,
    params: &ThreadResumeInitia

作用：恢复对话时顺手构造首屏轮次页。

数据流：输入历史条目、状态、活跃轮次和客户端请求的分页参数 → 调 build_thread_turns_page_response 从第一页开始分页 → 输出协议里的 TurnsPage。

调用关系：thread_resume_inner 和处理挂起恢复响应的流程会调用它。

调用图：调用 1 个内部函数（build_thread_turns_page_response）；被 2 处调用（handle_pending_thread_resume_request, thread_resume_inner）。

fn apply_thread_turns_items_view(turns: &mut [Turn], items_view: TurnItemsView)

作用：按客户端要求裁剪每轮里的消息内容。

数据流：输入可修改 turns 和 items_view → NotLoaded 清空内容，Summary 只保留首个用户消息和最后助手消息，Full 保留全部 → 原地修改 turns。

调用关系：build_thread_turns_page_response 在分页前调用它，减少网络传输。

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

fn reconstruct_thread_turns_for_turns_list(
    items: &[RolloutItem],
    loaded_status: ThreadStatus,
    has_live_running_thread: bool,
    active_turn: Option<Turn>,
) -> Vec<Turn>

作用：从原始历史重建轮次，并合并内存里的当前轮次。

数据流：输入历史条目、线程状态、是否运行和可选 active_turn → 生成 turns，修正状态，把活跃轮次合并进去 → 输出完整 turns。

调用关系：build_thread_turns_page_response 调用它。

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

fn normalize_thread_turns_status(
    turns: &mut [Turn],
    loaded_status: ThreadStatus,
    has_live_in_progress_turn: bool,
)

作用：如果线程其实不活跃，把历史里还标着进行中的轮次改成已中断。

数据流：输入可修改 turns、加载状态和是否有实时进行中轮次 → 解析线程最终状态；若不是活跃，就把 InProgress 轮次改为 Interrupted → 原地修改。

调用关系：reconstruct_thread_turns_for_turns_list 调用它，避免客户端看到假“进行中”。

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

fn thread_read_view_error(err: ThreadReadViewError) -> JSONRPCErrorError

作用：把 thread/read 内部错误转换成 JSON-RPC 错误。

数据流：输入 ThreadReadViewError → 按无效请求、不支持、内部错误三类映射 → 输出 JSONRPCErrorError。

调用关系：thread_read_response_inner 和 turns 历史读取相关流程用它统一报错口径。

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

fn unsupported_thread_store_operation(operation: &'static str) -> JSONRPCErrorError

作用：生成“这个存储操作还不支持”的标准错误。

数据流：输入操作名 → 包装成 method_not_found 错误 → 输出 JSON-RPC 错误。

调用关系：多种存储错误转换函数都会调用它。

调用图：调用 1 个内部函数（method_not_found）；被 7 处调用（thread_store_delete_error, conversation_summary_rollout_path_read_error, conversation_summary_thread_id_read_error, thread_read_view_error, thread_store_archive_error, thread_store_list_error, thread_store_resume_read_error）；外部调用 1 个（format!）。

fn thread_store_list_error(err: ThreadStoreError) -> JSONRPCErrorError

作用：把列对话列表时的存储错误翻译成客户端能懂的错误。

数据流：输入 ThreadStoreError → 无效请求原样给客户端，不支持转 method_not_found，其他转内部错误 → 输出 JSON-RPC 错误。

调用关系：list_threads_common 和搜索列表查询失败时使用。

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

fn thread_store_resume_read_error(err: ThreadStoreError) -> JSONRPCErrorError

作用：把恢复读取存储时的错误翻译成合适的 JSON-RPC 错误。

数据流：输入 ThreadStoreError → 区分参数错、不支持、线程不存在和其他错误 → 输出客户端错误或内部错误。

调用关系：read_stored_thread_for_resume 和 read_stored_thread_for_new_fork 使用。

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

fn thread_turns_list_history_load_error(
    thread_id: ThreadId,
    err: ThreadStoreError,
) -> ThreadReadViewError

作用：把 thread/turns/list 加载历史失败的原因改写成更友好的说明。

数据流：输入线程 ID 和存储错误 → 对尚未物化的 rollout 给出“第一条用户消息前不可用”的提示，其余按类型转换 → 输出 ThreadReadViewError。

调用关系：load_thread_turns_list_history 从活线程加载历史失败时使用。

调用图：外部调用 4 个（Internal, InvalidRequest, Unsupported, format!）。

fn thread_read_history_load_error(
    thread_id: ThreadId,
    err: ThreadStoreError,
) -> ThreadReadViewError

作用：把 thread/read includeTurns 加载历史失败转换成友好错误。

数据流：输入线程 ID 和存储错误 → 对未物化或找不到历史给出 includeTurns 不可用提示，其余映射为内部/无效/不支持 → 输出 ThreadReadViewError。

调用关系：apply_thread_read_store_fields 加载历史失败时调用。

调用图：外部调用 4 个（Internal, InvalidRequest, Unsupported, format!）。

fn conversation_summary_thread_id_read_error(
    conversation_id: ThreadId,
    err: ThreadStoreError,
) -> JSONRPCErrorError

作用：把按对话 ID 读取摘要失败转换成 JSON-RPC 错误。

数据流：输入对话 ID 和存储错误 → 没有 rollout 或找不到时返回统一 not found，无效请求和不支持分别处理，其他为内部错误 → 输出错误。

调用关系：get_thread_summary_response_inner 按 ID 读摘要失败时使用。

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

fn conversation_summary_not_found_error(conversation_id: ThreadId) -> JSONRPCErrorError

作用：生成“找不到这个对话摘要”的标准错误。

数据流：输入对话 ID → 组成固定错误消息 → 输出 invalid_request 错误。

调用关系：conversation_summary_thread_id_read_error 调用它统一 not found 文案。

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

fn conversation_summary_rollout_path_read_error(
    path: &Path,
    err: ThreadStoreError,
) -> JSONRPCErrorError

作用：把按 rollout 路径读取摘要失败转换成 JSON-RPC 错误。

数据流：输入路径和存储错误 → 参数错直接返回，不支持转 method_not_found，其他带路径包装成内部错误 → 输出错误。

调用关系：get_thread_summary_response_inner 按路径读摘要失败时使用。

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

fn core_thread_write_error(operation: &str, err: CodexErr) -> JSONRPCErrorError

作用：把核心层写线程元数据失败转换成 API 错误。

数据流：输入操作名和 CodexErr → 线程不存在、无效请求、不支持分别映射，其他包装为内部错误 → 输出 JSON-RPC 错误。

调用关系：改名、设置记忆模式、更新元数据和其他写线程信息的流程会用它。

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

fn thread_store_archive_error(operation: &str, err: ThreadStoreError) -> JSONRPCErrorError

作用：把归档/取消归档时的存储错误转换成 API 错误。

数据流：输入操作名和存储错误 → 参数错直接返回，不支持转标准不支持错误，其他转内部错误 → 输出 JSON-RPC 错误。

调用关系：thread_archive_response 和 thread_unarchive_response 使用。

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

fn set_thread_name_from_title(thread: &mut Thread, title: String)

作用：把一个标题写成 Thread 的显示名称，但避免空名和与预览重复。

数据流：输入可修改 Thread 和标题 → trim 判断；空或等于 preview 就不动，否则设置 name → 原地修改 Thread。

调用关系：attach_thread_name 和 thread_fork_inner 用它补显示名。

调用图：被 2 处调用（attach_thread_name, thread_fork_inner）。

fn thread_from_stored_thread(
    thread: StoredThread,
    fallback_provider: &str,
    fallback_cwd: &AbsolutePathBuf,
) -> (Thread, Option<codex_thread_store::StoredThreadHistory>)

作用：把存储层 StoredThread 转成客户端 API 的 Thread 基础对象。

数据流：输入 StoredThread、备用模型供应商和备用 cwd → 规范化路径、转换 Git 信息、来源、时间、父子关系等字段 → 输出 Thread 和可选历史。

调用关系：列表、搜索、读取、恢复、取消归档、分叉等很多地方都用它做统一转换。

调用图：调用 1 个内部函数（relative_to_current_dir）；被 7 处调用（load_persisted_thread_for_read, load_thread_from_resume_source_or_send_internal, stored_thread_to_api_thread, thread_list_response_inner, thread_metadata_update_response_inner, thread_search_response_inner, thread_unarchive_response）；外部调用 2 个（new, normalize_for_native_workdir）。

fn summary_from_stored_thread(
    thread: StoredThread,
    fallback_provider: &str,
) -> ConversationSummary

作用：把存储层对话转成轻量 ConversationSummary。

数据流：输入 StoredThread 和备用模型供应商 → 提取路径、预览、时间、模型供应商、目录、来源和 Git 信息 → 输出摘要对象。

调用关系：get_thread_summary_response_inner 调用它。

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

fn summary_from_state_db_metadata(
    conversation_id: ThreadId,
    path: PathBuf,
    first_user_message: Option<String>,
    preview: Option<String>,
    timestamp: String,
    updated_at: String,

作用：测试用：把状态数据库元数据拼成 ConversationSummary。

数据流：输入一组拆开的元数据字段 → 解析来源、组合预览和 Git 信息 → 输出摘要对象。

调用关系：只在测试配置下编译，由 summary_from_thread_metadata 调用。

调用图：被 1 处调用（summary_from_thread_metadata）；外部调用 1 个（from_str）。

fn summary_from_thread_metadata(metadata: &ThreadMetadata) -> ConversationSummary

作用：测试用：把 ThreadMetadata 转成 ConversationSummary。

数据流：输入 ThreadMetadata → 拆出各字段并传给 summary_from_state_db_metadata → 输出摘要。

调用关系：只在测试里使用，用来验证旧状态库元数据转换。

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

fn preview_from_rollout_items(items: &[RolloutItem]) -> String

作用：从历史条目里提取第一条用户消息，作为对话预览。

数据流：输入 RolloutItem 列表 → 找到第一个用户消息，去掉特殊开头标记 → 输出预览字符串；找不到则空字符串。

调用关系：恢复从 history 分叉、创建 ephemeral 分叉时用它生成 preview。

调用图：被 2 处调用（load_thread_from_resume_source_or_send_internal, thread_fork_inner）；外部调用 1 个（iter）。

fn requested_permissions_trust_project(overrides: &ConfigOverrides, cwd: &Path) -> bool

作用：判断用户请求的权限是否意味着当前项目应被信任。

数据流：输入配置覆盖和工作目录 → 查看沙盒模式、内置权限档案或自定义权限档案是否允许写项目 → 输出布尔值。

调用关系：thread_start_task 新建对话加载配置后用它决定是否要标记项目可信。

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

fn permission_profile_trusts_project(
    profile: &codex_protocol::models::PermissionProfile,
    cwd: &Path,
) -> bool

作用：判断一个权限档案是否信任当前项目目录。

数据流：输入权限档案和 cwd → Disabled/External 视为信任；Managed 则检查文件系统沙盒是否允许写 cwd → 输出布尔值。

调用关系：thread_start_task 和 requested_permissions_trust_project 用它判断项目信任。

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

fn build_thread_from_snapshot(
    thread_id: ThreadId,
    session_id: String,
    config_snapshot: &ThreadConfigSnapshot,
    path: Option<PathBuf>,
) -> Thread

作用：从运行中线程的配置快照创建一个 API Thread 骨架。

数据流：输入线程 ID、session ID、配置快照和可选路径 → 填入模型供应商、cwd、来源、父线程、时间、ephemeral 等基础字段 → 输出没有 turns 的 Thread。

调用关系：新建、恢复、分叉、补监听和 build_thread_from_loaded_snapshot 都用它。

调用图：调用 1 个内部函数（cwd）；被 5 处调用（load_thread_from_resume_source_or_send_internal, thread_fork_inner, thread_start_task, try_attach_thread_listener, build_thread_from_loaded_snapshot）；外部调用 5 个（new, new, env!, to_string, now_utc）。

fn paginate_background_terminals(
    terminals: &[ThreadBackgroundTerminal],
    cursor: Option<String>,
    limit: Option<u32>,
) -> Result<(Vec<ThreadBackgroundTerminal>, Option<String>), JSONRPCEr

作用：给后台终端列表做简单分页。

数据流：输入终端切片、游标和限制 → 游标按进程 ID 解析，找到起点，截取一页 → 输出终端子列表和下一页游标。

调用关系：thread_background_terminals_list_inner 调用它。

调用图：被 1 处调用（thread_background_terminals_list_inner）；外部调用 2 个（iter, len）。

fn build_thread_from_loaded_snapshot(
    thread_id: ThreadId,
    config_snapshot: &ThreadConfigSnapshot,
    loaded_thread: &CodexThread,
) -> Thread

作用：从已加载线程直接构造 API Thread 骨架。

数据流：输入线程 ID、配置快照和 loaded_thread → 取 loaded_thread 的 session ID 和 rollout 路径，再调用 build_thread_from_snapshot → 输出 Thread。

调用关系：load_live_thread_view 用它作为活线程视图的 fallback。

调用图：调用 3 个内部函数（build_thread_from_snapshot, rollout_path, session_configured）；被 1 处调用（load_live_thread_view）。

fn new(
        thread_manager: Arc<ThreadManager>,
        outgoing: Arc<OutgoingMessageSender>,
        config: Arc<Config>,
        thread_state_manager: ThreadStateManager,
        state_db: Optio

作用：创建一个处理“线程目标请求”的处理器。它把后面办事需要用到的线程管理器、消息发送器、配置、状态数据库和目标服务都装进同一个对象里。

数据流：进去的是一组共享组件，比如线程管理器、对外发消息的发送器、配置、可选的状态数据库、目标服务。函数不做复杂计算，只是把这些东西保存到结构体字段里。出来的是一个可以处理目标相关请求的 ThreadGoalRequestProcessor。

调用关系：它在上层请求处理器初始化时被调用。之后客户端关于目标的设置、读取、清除请求，都会通过这个对象继续往下分发。

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

async fn thread_goal_set(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadGoalSetParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：这是“设置线程目标”对外暴露的入口。它把真正的工作交给内部函数，成功时告诉上层这里已经自己发送过响应，不需要再包装额外返回值。

数据流：进去的是请求编号和设置目标的参数。它调用 thread_goal_set_inner 完成校验、保存和通知；如果成功，把内部的空结果转换成 None；如果失败，原样把 JSON-RPC 错误交回去。

调用关系：客户端请求进入 handle_initialized_client_request 后会走到这里。它是薄薄的一层门面，实际活由 thread_goal_set_inner 做。

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

async fn thread_goal_get(
        &self,
        params: ThreadGoalGetParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：这是“读取线程目标”对外暴露的入口。它负责把内部拿到的目标结果包装成客户端能收到的响应格式。

数据流：进去的是包含线程编号的查询参数。它调用 thread_goal_get_inner 查数据库；成功后把响应转换成 ClientResponsePayload；失败时返回 JSON-RPC 错误。

调用关系：客户端请求进入 handle_initialized_client_request 后会走到这里。它把查询工作交给 thread_goal_get_inner，并把结果交回上层统一返回。

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

async fn thread_goal_clear(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadGoalClearParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：这是“清除线程目标”对外暴露的入口。它负责接收请求，并让内部函数完成删除目标、回复客户端、发通知这些事。

数据流：进去的是请求编号和清除参数。它调用 thread_goal_clear_inner；成功后返回 None，表示响应已经在内部发送；失败则返回对应的 JSON-RPC 错误。

调用关系：客户端请求进入 handle_initialized_client_request 后会走到这里。它本身不直接删数据，而是把活交给 thread_goal_clear_inner。

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

async fn emit_resume_goal_snapshot_and_continue(
        &self,
        thread_id: ThreadId,
        thread: &CodexThread,
    )

作用：在线程恢复运行时，先把当前目标状态发给客户端，再让线程继续发“我空闲了”之类的生命周期通知。这样客户端看到的顺序不会乱。

数据流：进去的是线程编号和运行中的线程对象。它先看配置里 Goals 功能是否开启；没开启就什么都不做。开启时先调用 emit_thread_goal_snapshot 发一份目标快照，再调用线程的 emit_thread_idle_lifecycle_if_idle 继续后续通知。

调用关系：thread_resume_inner 在线程恢复时调用它。它把目标快照放在恢复流程的正确位置，之后才让线程自己的空闲通知继续发出。

调用图：调用 2 个内部函数（emit_thread_goal_snapshot, emit_thread_idle_lifecycle_if_idle）；被 1 处调用（thread_resume_inner）。

async fn pending_resume_goal_state(
        &self,
        thread: &CodexThread,
    ) -> (bool, Option<StateDbHandle>)

作用：在线程恢复前，判断是否需要准备目标状态数据库。它像是提前问一句：这次恢复要不要带上目标信息？要的话去哪儿读？

数据流：进去的是线程对象。它读取配置里的 Goals 功能开关；如果关闭，返回“不需要”和空数据库。若开启，优先使用线程自己带的状态数据库；没有的话使用处理器保存的全局状态数据库。出来的是一个布尔值和一个可选数据库句柄。

调用关系：resume_running_thread 在恢复运行中线程时调用它。它为恢复流程提前准备目标状态信息，后续如果需要发目标快照就有数据库可用。

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

async fn thread_goal_set_inner(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadGoalSetParams,
    ) -> Result<(), JSONRPCErrorError>

作用：真正执行“设置线程目标”的核心流程。它会检查功能开关、确认线程存在、同步旧记录、保存新目标，并通知客户端目标已经更新。

数据流：进去的是请求编号和目标参数，比如线程编号、目标文字、状态、token 预算。它先拒绝未开启的功能，再把线程编号字符串转成内部编号，找到状态数据库，并把线程 rollout 文件和数据库对齐。然后取出线程监听通道，把参数转换成 GoalService 认识的更新请求，交给 goal_service 保存。出来时它已发送设置成功响应，发出目标更新通知，并执行目标服务返回的运行时影响；函数本身返回空成功或错误。

调用关系：thread_goal_set 调用它。它向下依赖 parse_thread_id_for_request、state_db_for_materialized_thread、reconcile_thread_goal_rollout 和 goal_service，保存完后交给 emit_thread_goal_updated_ordered 保证通知顺序。

调用图：调用 6 个内部函数（from, emit_thread_goal_updated_ordered, reconcile_thread_goal_rollout, state_db_for_materialized_thread, parse_thread_id_for_request, thread_state）；被 1 处调用（thread_goal_set）；外部调用 2 个（clone, Set）。

async fn thread_goal_get_inner(
        &self,
        params: ThreadGoalGetParams,
    ) -> Result<ThreadGoalGetResponse, JSONRPCErrorError>

作用：真正执行“读取线程目标”的查询流程。它负责从状态数据库里拿出某个线程当前的目标记录。

数据流：进去的是查询参数，主要是线程编号字符串。它先检查 Goals 功能是否开启，再解析线程编号，找到对应状态数据库，然后调用 goal_service 读取目标。出来的是 ThreadGoalGetResponse，里面可能有目标，也可能是空，表示这个线程还没设置目标。

调用关系：thread_goal_get 调用它。它使用 parse_thread_id_for_request 和 state_db_for_materialized_thread 做准备，真正的数据读取交给 goal_service。

调用图：调用 2 个内部函数（state_db_for_materialized_thread, parse_thread_id_for_request）；被 1 处调用（thread_goal_get）。

async fn thread_goal_clear_inner(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadGoalClearParams,
    ) -> Result<(), JSONRPCErrorError>

作用：真正执行“清除线程目标”的核心流程。它会删除数据库里的目标记录，并在确实删掉了东西时通知外部。

数据流：进去的是请求编号和清除参数。它先检查功能开关，解析线程编号，找到状态数据库，并同步线程 rollout 记录。然后拿到线程监听通道，调用 goal_service 清除目标。出来时它已给客户端发送清除结果；如果确实清除了目标，还会发出目标已清除通知。

调用关系：thread_goal_clear 调用它。它前面依赖 parse_thread_id_for_request、state_db_for_materialized_thread、reconcile_thread_goal_rollout，后面把通知交给 emit_thread_goal_cleared_ordered。

调用图：调用 5 个内部函数（emit_thread_goal_cleared_ordered, reconcile_thread_goal_rollout, state_db_for_materialized_thread, parse_thread_id_for_request, thread_state）；被 1 处调用（thread_goal_clear）。

async fn state_db_for_materialized_thread(
        &self,
        thread_id: ThreadId,
    ) -> Result<StateDbHandle, JSONRPCErrorError>

作用：为一个线程找到可用的状态数据库。它还会挡住临时线程，因为临时线程没有落盘记录，不能可靠保存目标。

数据流：进去的是内部线程编号。它先问线程管理器这个线程是否正在运行；如果在运行但没有 rollout 路径，就返回“临时线程不支持目标”的错误；如果线程自己带状态数据库，就直接返回。若线程不在内存中，它会去磁盘目录里查线程路径，找不到就报“线程不存在”。最后如果只能用全局数据库，就返回它；没有全局数据库则报内部错误。

调用关系：设置、读取、清除目标以及恢复时发快照都会调用它。它是所有目标操作进入数据库前的安全检查口。

调用图：被 4 处调用（emit_thread_goal_snapshot, thread_goal_clear_inner, thread_goal_get_inner, thread_goal_set_inner）；外部调用 3 个（find_thread_path_by_id_str, format!, to_string）。

async fn reconcile_thread_goal_rollout(
        &self,
        thread_id: ThreadId,
        state_db: &StateDbHandle,
    ) -> Result<(), JSONRPCErrorError>

作用：在修改目标前，把线程的磁盘记录和状态数据库对齐。这样目标服务看到的是最新、完整的线程资料。

数据流：进去的是线程编号和状态数据库。它先找到线程的 rollout 路径：运行中的线程直接取，没运行的线程就按编号去磁盘查。找不到或是临时线程就报错。找到后调用 reconcile_rollout，把 rollout 文件内容同步进状态数据库。出来时没有新数据返回，但数据库可能已被补齐或更新。

调用关系：thread_goal_set_inner 和 thread_goal_clear_inner 在改目标前调用它。它把“旧的文件记录”和“新的数据库状态”接上，避免后面的 goal_service 基于过期信息操作。

调用图：被 2 处调用（thread_goal_clear_inner, thread_goal_set_inner）；外部调用 2 个（find_thread_path_by_id_str, to_string）。

async fn emit_thread_goal_snapshot(&self, thread_id: ThreadId)

作用：给客户端发送某个线程当前目标状态的快照。快照就是“现在这张任务卡长什么样”的一次完整通知。

数据流：进去的是线程编号。它先尝试找到状态数据库；失败就记警告并停止。然后拿线程监听通道，如果通道存在且还能发送，就把“发目标快照”的命令塞给线程监听器。若通道没有或已经关了，它就直接通过 outgoing 发送目标快照通知。

调用关系：emit_resume_goal_snapshot_and_continue 在线程恢复时调用它。它优先借线程监听器发消息，以保持和其他线程事件的顺序；不行时才走直接发送的兜底路线。

调用图：调用 2 个内部函数（state_db_for_materialized_thread, thread_state）；被 1 处调用（emit_resume_goal_snapshot_and_continue）；外部调用 1 个（warn!）。

async fn emit_thread_goal_updated_ordered(
        &self,
        thread_id: ThreadId,
        goal: ThreadGoal,
        listener_command_tx: Option<tokio::sync::mpsc::UnboundedSender<ThreadListenerCo

作用：发送“线程目标已更新”的通知，并尽量保证它和线程的其他事件按正确顺序出现。

数据流：进去的是线程编号、更新后的目标、以及可选的线程监听通道。若通道可用，它把更新命令交给监听器；如果发送失败，会写警告。没有可用通道时，它直接通过 outgoing 广播 ThreadGoalUpdated 通知。出来没有返回值，但外部客户端会收到更新消息。

调用关系：thread_goal_set_inner 保存目标成功后调用它。它负责通知层面的收尾，让客户端知道目标已经变成新内容。

调用图：被 1 处调用（thread_goal_set_inner）；外部调用 4 个（ThreadGoalUpdated, clone, to_string, warn!）。

async fn emit_thread_goal_cleared_ordered(
        &self,
        thread_id: ThreadId,
        listener_command_tx: Option<tokio::sync::mpsc::UnboundedSender<ThreadListenerCommand>>,
    )

作用：发送“线程目标已清除”的通知，并尽量让这条通知排在正确的事件顺序里。

数据流：进去的是线程编号和可选的线程监听通道。若通道可用，它把清除命令交给监听器；如果通道关闭，会写警告。没有通道时，它直接通过 outgoing 广播 ThreadGoalCleared 通知。出来没有返回值，但客户端会知道这条线程的目标已被清掉。

调用关系：thread_goal_clear_inner 在确认目标真的被清除后调用它。它和 emit_thread_goal_updated_ordered 类似，都是先走监听器保顺序，失败再直接发通知。

调用图：被 1 处调用（thread_goal_clear_inner）；外部调用 3 个（ThreadGoalCleared, to_string, warn!）。

fn api_thread_goal_from_state(goal: codex_state::ThreadGoal) -> ThreadGoal

作用：把数据库里的目标记录转换成 API 返回给客户端的目标格式。它相当于翻译员，把内部说法翻成外部能看懂的说法。

数据流：进去的是 codex_state::ThreadGoal，也就是状态层保存的目标。它复制线程编号、目标内容、预算、用量和时间戳，并调用 api_thread_goal_status_from_state 翻译状态枚举。出来的是 ThreadGoal，适合放进 API 响应或通知里。

调用关系：它被目标数据需要暴露给客户端时使用。状态字段的具体翻译交给 api_thread_goal_status_from_state。

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

fn api_thread_goal_status_from_state(status: codex_state::ThreadGoalStatus) -> ThreadGoalStatus

作用：把数据库层的目标状态转换成 API 层的目标状态。比如进行中、暂停、受限、完成这些状态，都一一对应过去。

数据流：进去的是 codex_state::ThreadGoalStatus。它根据具体状态做匹配，不改含义，只换成 API 类型。出来的是 ThreadGoalStatus。

调用关系：api_thread_goal_from_state 在转换整条目标记录时调用它。它只负责状态这一个小字段的翻译。

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

fn goal_service_error(err: GoalServiceError) -> JSONRPCErrorError

作用：把 GoalService 返回的错误转换成 JSON-RPC 错误。JSON-RPC 是客户端和服务器通话的一种格式，错误也要按它的格式返回。

数据流：进去的是 GoalServiceError。若是 InvalidRequest，就变成客户端请求有问题的错误；若是 Internal，就变成服务器内部错误。出来的是 JSONRPCErrorError，能直接返回给客户端。

调用关系：目标服务调用失败时会用它做错误翻译。这样 thread_goal_set_inner、thread_goal_get_inner、thread_goal_clear_inner 不需要关心每种服务错误该怎么包装。

fn parse_thread_id_for_request(thread_id: &str) -> Result<ThreadId, JSONRPCErrorError>

作用：把客户端传来的线程编号字符串解析成程序内部使用的 ThreadId。它会把格式不对的编号变成清楚的请求错误。

数据流：进去的是线程编号文本。它调用 ThreadId::from_string 尝试解析；成功就输出 ThreadId；失败就输出 invalid_request 错误，并说明线程编号无效。

调用关系：设置、读取、清除目标的内部流程都会先调用它。它是防止乱七八糟线程编号继续进入数据库操作的第一道关。

调用图：调用 1 个内部函数（from_string）；被 3 处调用（thread_goal_clear_inner, thread_goal_get_inner, thread_goal_set_inner）。

async fn thread_delete(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadDeleteParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

作用：这是删除线程请求的入口。它负责把一次客户端请求包装成完整流程：加锁、执行删除、回响应、发通知。

数据流：输入是请求编号和删除参数，参数里包含要删除的线程 ID。它先拿到线程列表状态的许可，相当于临时占住“线程清单”这张表，防止别人同时改；然后调用 ThreadRequestProcessor::thread_delete_response 真正删除。成功后，它用请求编号把结果发回客户端，再把删掉的线程 ID 交给 ThreadRequestProcessor::send_thread_deleted_notifications 发通知；如果中间失败，就把错误原样返回。

调用关系：它是外部 thread/delete 请求进入本文件的第一站。它把具体删除工作交给 ThreadRequestProcessor::thread_delete_response，把通知工作交给 ThreadRequestProcessor::send_thread_deleted_notifications；自己主要负责控制顺序，确保客户端先收到请求响应，再收到删除通知。

调用图：调用 2 个内部函数（send_thread_deleted_notifications, thread_delete_response）；外部调用 2 个（new, clone）。

async fn thread_delete_response(
        &self,
        params: ThreadDeleteParams,
        deleted_thread_ids: &mut Vec<String>,
    ) -> Result<ThreadDeleteResponse, JSONRPCErrorError>

作用：这个函数是真正执行删除的核心步骤。它负责找全要删的线程、确认能不能删、做删除前准备、从各个存储里清掉记录，并整理出最终要通知客户端的删除列表。

数据流：输入是删除参数和一个用来收集已删除线程 ID 的列表。它先把字符串形式的线程 ID 转成内部 ID，失败就报“请求不合法”。然后它从状态库找这个线程的子树，又从运行中的线程管理器补上还活着的子线程，合并去重。接着调用 ThreadRequestProcessor::validate_root_thread_delete 检查根线程是否允许删除，再对每个线程调用 ThreadRequestProcessor::prepare_thread_for_delete 做删除前收尾。之后它按孩子在前、父亲在后的顺序调用线程存储删除记录；如果某个线程已经不在了，会记警告但继续；其他错误会用 thread_store_delete_error 翻译成客户端能懂的错误。最后它还会清理 app-server 自己的状态库，把删除顺序里的 ID 转成字符串放进输出列表，并返回一个空的成功响应。

调用关系：它由 ThreadRequestProcessor::thread_delete 调用，是整条删除链路的主干。遇到运行中线程管理器的写入类错误时，它会交给 core_thread_write_error 包装；遇到线程存储删除错误时，会交给 thread_store_delete_error 变成 JSON-RPC 错误，也就是接口层能返回给客户端的标准错误。

调用图：调用 5 个内部函数（prepare_thread_for_delete, validate_root_thread_delete, thread_store_delete_error, core_thread_write_error, from_string）；被 1 处调用（thread_delete）；外部调用 1 个（warn!）。

async fn send_thread_deleted_notifications(&self, deleted_thread_ids: Vec<String>)

作用：这个函数负责告诉客户端：哪些线程已经被删除了。它把删除结果变成一条条服务器通知发出去。

数据流：输入是一组已经删除的线程 ID 字符串。它逐个取出 ID，包装成 ThreadDeletedNotification，再放进 ServerNotification::ThreadDeleted 这种通知消息里，通过 outgoing 发送出去。它不返回业务数据，只完成发送动作。

调用关系：它只在 ThreadRequestProcessor::thread_delete 删除成功并已发送请求响应之后被调用。这样客户端先知道“这次删除请求成功了”，再收到每个线程消失的事件，界面可以据此移除对应项。

调用图：被 1 处调用（thread_delete）；外部调用 1 个（ThreadDeleted）。

async fn validate_root_thread_delete(
        &self,
        thread_id: ThreadId,
        has_descendants: bool,
    ) -> Result<(), JSONRPCErrorError>

作用：这个函数检查“要删除的根线程”是否合法。它避免把不该删的线程删掉，也区分“真的不存在”和“主记录没了但还有子节点或状态残留”的情况。

数据流：输入是根线程 ID，以及它是否有后代。它先问运行中的线程管理器有没有这个线程；如果有，并且这个线程不是临时线程，就允许删除；如果是临时线程，就返回“不能删除”的请求错误。若运行中没有，它再去线程存储里读归档也包含在内的记录；读得到就允许。读不到时，如果还有后代，说明仍有一棵子树需要清理，也允许；如果没有后代，它会再查 app-server 自己的状态库，那里还存在就允许清理，否则就把“线程不存在”作为错误返回。其他存储错误会通过 thread_store_delete_error 转成标准错误。

调用关系：它由 ThreadRequestProcessor::thread_delete_response 在真正删除前调用，相当于拆房子前先确认这栋房子是不是能拆。它依赖 thread_store_delete_error 把底层存储错误翻译成客户端接口能理解的说法。

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

async fn prepare_thread_for_delete(&self, thread_id: ThreadId)

作用：这个函数做删除前的收尾工作。它让指定线程进入可移除状态，并尽量把日志写稳，减少删除时留下半截记录的风险。

数据流：输入是一个线程 ID。它先调用通用的“准备移除线程”步骤，并标明这次原因是 delete；如果有日志数据库，就执行 flush，也就是把缓冲里的日志尽快刷到实际存储里。它不产出新数据，主要改变线程和日志系统的状态。

调用关系：它由 ThreadRequestProcessor::thread_delete_response 对每个将要删除的线程调用。它位于“确认可以删”和“真正从存储删除”之间，作用像搬家前先关水关电，避免后面硬删除时还有后台活动。

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

fn thread_store_delete_error(err: ThreadStoreError) -> JSONRPCErrorError

作用：这个小函数把线程存储层的错误翻译成 JSON-RPC 错误，也就是客户端接口能读懂的错误格式。它让底层错误不会原封不动、含糊地漏到外面。

数据流：输入是一个 ThreadStoreError，也就是线程存储报告的失败原因。它会按情况改写：线程不存在变成“thread not found”，请求本身不合法就保留对应消息，不支持的存储操作交给 unsupported_thread_store_operation 处理，其他意外错误统一变成“删除线程失败”的内部错误。输出是 JSONRPCErrorError，用来返回给请求处理层。

调用关系：它被 ThreadRequestProcessor::thread_delete_response 和 ThreadRequestProcessor::validate_root_thread_delete 调用。前者在真正删除失败时用它，后者在删除前检查读存储失败时用它；它是本文件里把底层存储语言翻译成接口语言的关口。

调用图：调用 1 个内部函数（unsupported_thread_store_operation）；被 2 处调用（thread_delete_response, validate_root_thread_delete）；外部调用 1 个（format!）。

async fn on_call_response(
    call_id: String,
    receiver: oneshot::Receiver<ClientRequestResult>,
    conversation: Arc<CodexThread>,
)

作用：这是动态工具回信流程的主入口。它等待客户端返回工具执行结果，判断成败，必要时做兜底，然后把结果交回核心对话。

数据流：进去的是一个工具调用编号 call_id、一个一次性接收器 receiver，以及核心对话线程 conversation。它先等 receiver 给结果；如果收到正常 JSON，就交给 decode_response 解析；如果收到客户端错误或通道错误，就根据情况忽略或生成 fallback_response。之后它把 app-server 的响应内容转换成核心协议里的 DynamicToolResponse，并提交成 Op::DynamicToolResponse。出来没有普通返回值，但它会改动系统状态：把工具结果送回正在运行的对话线程；如果提交失败，会写错误日志。

调用关系：它由 apply_bespoke_event_handling 在处理特殊事件时调用，是客户端工具结果回到核心系统的桥。它把解析工作交给 decode_response，把失败兜底交给 fallback_response，还会调用 is_turn_transition_server_request_error 判断某些错误是不是因为对话轮次切换造成的旧请求失效。遇到问题时，它用 error! 写日志，方便排查。

调用图：调用 3 个内部函数（decode_response, fallback_response, is_turn_transition_server_request_error）；被 1 处调用（apply_bespoke_event_handling）；外部调用 1 个（error!）。

fn decode_response(value: serde_json::Value) -> (DynamicToolCallResponse, Option<String>)

作用：这个函数把客户端传回来的 JSON 数据翻译成真正的 DynamicToolCallResponse。它的作用是确认“回信长得对不对”，避免坏格式直接进入核心流程。

数据流：进去的是一份 serde_json::Value，也就是还没确认结构的 JSON 数据。它尝试按 DynamicToolCallResponse 的格式读取；成功就原样产出这个响应，并带上空的错误信息；失败就记录日志，然后调用 fallback_response 生成一份失败响应。出来的是一对数据：可用的工具响应，以及可选的错误文字。

调用关系：它只被 on_call_response 使用，位置在“收到客户端回信之后、提交给核心对话之前”。如果解析成功，它让流程继续走正常路线；如果解析失败，它把补救工作交给 fallback_response，保证 on_call_response 后面仍然有东西可以提交。

调用图：调用 1 个内部函数（fallback_response）；被 1 处调用（on_call_response）；外部调用 1 个（error!）。

fn fallback_response(message: &str) -> (DynamicToolCallResponse, Option<String>)

作用：这是统一的失败兜底生成器。只要动态工具请求失败、回信断了、或者返回格式不对，它就造一份明确标记为失败的响应。

数据流：进去的是一段给用户或系统看的错误文字 message。它把这段文字放进一个文本内容项里，并把 success 设为 false。出来的是一份 DynamicToolCallResponse，加上一份同样的错误文字，表示这次工具调用没有成功。

调用关系：它被 on_call_response 和 decode_response 调用，是整个文件的安全网。on_call_response 在请求失败或通道断开时直接用它；decode_response 在 JSON 解析失败时用它。它不再调用项目里的其他业务函数，只负责快速拼出一个可靠的失败结果。

调用图：被 2 处调用（decode_response, on_call_response）；外部调用 1 个（vec!）。

fn is_turn_transition_server_request_error(error: &JSONRPCErrorError) -> bool

作用：判断一个 JSON-RPC 错误是不是“对话轮次切换”导致的特殊中断。别人会用它来决定这个错误要不要当成真正失败来处理。

数据流：进去的是一个 JSONRPCErrorError 错误对象；函数读取它的 data 字段，再找里面的 reason 字段，并确认这个字段是不是字符串 "turnTransition"；出来的是 true 或 false，不修改原来的错误对象。

调用关系：它是请求处理流程里的一个小判定器。像 mcp_server_elicitation_response_from_client_result、on_command_execution_request_approval_response、on_file_change_request_approval_response、on_request_user_input_response、request_permissions_response_from_client_result、on_call_response 这些处理客户端回复或调用结果的地方，会在遇到错误时叫它来分辨：这是轮次切换造成的可预期中断，还是需要继续当作异常处理的别的问题。

调用图：被 6 处调用（mcp_server_elicitation_response_from_client_result, on_command_execution_request_approval_response, on_file_change_request_approval_response, on_request_user_input_response, request_permissions_response_from_client_result, on_call_response）。

fn turn_transition_error_is_detected()

作用：测试“轮次切换”这种特殊错误确实能被识别出来。它防止以后有人改代码时，不小心把这个判断弄坏。

数据流：进去的是测试里临时造出的一个错误对象，里面的 data.reason 是 "turnTransition"；测试把它交给 is_turn_transition_server_request_error；期望出来的结果是 true，并用断言检查这一点。

调用关系：它只在运行测试时执行。它调用 json! 来快速拼出错误里的 JSON 数据，再用 assert_eq! 检查判断结果是否符合预期，是 is_turn_transition_server_request_error 的正向样例。

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

fn unrelated_error_is_not_detected()

作用：测试普通错误不会被误认为“轮次切换”错误。它保证这个判断不会太宽松，避免把真正的问题悄悄放过去。

数据流：进去的是测试里临时造出的一个错误对象，里面的 data.reason 是 "other"；测试把它交给 is_turn_transition_server_request_error；期望出来的结果是 false，并用断言确认。

调用关系：它只在运行测试时执行。它同样用 json! 造测试数据，用 assert_eq! 检查结果，是 is_turn_transition_server_request_error 的反向样例，用来和正向测试配成一组。

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

async fn supported_models(
    thread_manager: Arc<ThreadManager>,
    include_hidden: bool,
) -> Vec<Model>

作用：这个函数生成“客户端可以看到的模型列表”。别人调用它时，通常是想在界面上展示模型选择器，或者让客户端知道当前有哪些模型可用。

数据流：进去的是一个 ThreadManager（一位能查询模型清单的后台管家）和 include_hidden（是否连隐藏模型也一起给）。它先在线获取或使用缓存里的模型清单，然后如果不需要隐藏模型，就把不该出现在选择器里的模型过滤掉。接着它把每个内部模型资料交给 model_from_preset 转成对外格式，最后出来的是一组 Model。

调用关系：它是这个文件对外最主要的入口。上层在需要模型清单时会调用它；它自己负责拿列表和过滤，具体“怎么把一个内部模型变成客户端模型”则交给 model_from_preset 完成。

fn model_from_preset(preset: ModelPreset) -> Model

作用：这个函数把一个内部模型配置，翻译成客户端协议里的模型对象。它的用处是保证前端看到的字段完整、名字统一，而且不用理解后台内部格式。

数据流：进去的是一个 ModelPreset，也就是系统内部保存的一份模型说明。它逐项取出模型编号、真实模型名、显示名、描述、升级信息、是否隐藏、默认推理强度、输入能力、服务档位等内容，并按客户端需要的结构重新包装。遇到推理强度列表时，它会交给 reasoning_efforts_from_preset 再转换。最后出来的是一个 Model。

调用关系：supported_models 会对每个查到的模型调用它。它是中间的翻译层：上面接收内部模型清单，下面调用 reasoning_efforts_from_preset 处理推理强度这种子列表，最后把完整结果交还给调用方。

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

fn reasoning_efforts_from_preset(
    efforts: Vec<ReasoningEffortPreset>,
) -> Vec<ReasoningEffortOption>

作用：这个函数专门转换“推理强度”选项。推理强度可以理解成模型思考得多深入、可能也会影响速度和成本的选项。

数据流：进去的是一组内部格式的 ReasoningEffortPreset。它逐个取出实际的强度值和说明文字，包装成客户端协议里的 ReasoningEffortOption。最后出来的是一组客户端能直接展示或使用的推理强度选项。

调用关系：它不直接面向最上层调用者，而是被 model_from_preset 在转换单个模型时使用。这样 model_from_preset 不用把所有细节都写在一起，推理强度这一小块由它单独完成。

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

fn from_turn_context(
        turn_context: &TurnContext,
        params: ToolRouterParams<'_>,
        tool_search_handler_cache: &ToolSearchHandlerCache,
    ) -> Self

作用：根据当前这一轮对话的上下文，创建一个可用的工具路由器。有人要开始一轮模型交互、需要知道本轮有哪些工具可用时，会用它。

数据流：输入是一轮对话的上下文、各种工具来源参数，以及工具搜索处理器缓存 → 它把这些信息交给 build_tool_router 统一组装 → 输出一个 ToolRouter，里面已经放好了工具登记册和模型能看到的工具说明。

调用关系：它是创建路由器的常用入口，测试和正常流程都会用到。它自己不细拆工具来源，而是把组装工作交给 build_tool_router，这样本文件只负责“路由器长什么样、怎么用”。

调用图：调用 1 个内部函数（build_tool_router）；被 11 处调用（fatal_tool_error_stops_turn_and_reports_error, test_tool_runtime, built_tools, handle_output_item_done_returns_contributed_last_agent_message, extension_tool_executors_are_model_visible_and_dispatchable, mcp_parallel_support_uses_handler_data, parallel_support_does_not_match_namespaced_local_tool_names, specs_filter_deferred_dynamic_tools, tools_without_handlers_do_not_support_parallel, probe_with (+1 more)）。

fn from_parts(registry: ToolRegistry, model_visible_specs: Vec<ToolSpec>) -> Self

作用：用已经准备好的工具登记册和工具说明，直接拼出一个 ToolRouter。适合底层构建流程或测试已经把零件准备好的情况。

数据流：输入是 ToolRegistry 和一组模型可见的 ToolSpec → 它原样保存到 ToolRouter 里 → 输出一个可以查询工具说明、派发工具调用的路由器。

调用关系：它是更底层的构造方式。build_tool_router 组装好所有工具后会用它生成最终路由器，一些测试也会绕过复杂准备步骤直接用它。

调用图：被 3 处调用（cancellation_after_handler_finishes_preserves_completed_lifecycle, cancellation_waiting_for_runtime_cleanup_emits_only_aborted_lifecycle, build_tool_router）。

fn model_visible_specs(&self) -> Vec<ToolSpec>

作用：取出“模型能看到的工具说明”。这些说明会告诉模型：现在有哪些工具、每个工具该怎么传参数。

数据流：输入是当前 ToolRouter 自己保存的工具说明列表 → 它复制一份列表 → 输出给调用方，不让外部直接改动路由器内部保存的原件。

调用关系：提示词构建流程会用它把工具说明塞进给模型的上下文里。也就是说，它连接了“系统有什么工具”和“模型知道自己能用什么工具”这两件事。

调用图：被 2 处调用（build_prompt, from_router）。

fn registered_tool_names_for_test(&self) -> Vec<ToolName>

作用：测试专用：拿到当前已经登记的工具名字。它帮助测试确认工具路由器是不是真的装进了预期的工具。

数据流：输入是当前 ToolRouter → 它向内部的 ToolRegistry 询问测试用工具名列表 → 输出这些工具名。

调用关系：它只在测试编译时存在。测试代码通过它检查 build_tool_router 或其他构建流程的结果是否正确，真正运行时不会依赖它。

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

fn tool_exposure_for_test(
        &self,
        name: &ToolName,
    ) -> Option<crate::tools::registry::ToolExposure>

作用：测试专用：查看某个工具是怎样暴露给外界的，比如是否给模型可见。它用来验证工具的可见性策略是否符合预期。

数据流：输入是一个工具名 → 它去 ToolRegistry 里查这个工具的暴露信息 → 输出可能存在的 ToolExposure；如果没这个工具，就输出空。

调用关系：它服务于测试，帮助测试从路由器外面观察登记册里的状态。实际工具调用流程不会靠它执行工具。

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

fn create_diff_consumer(
        &self,
        tool_name: &ToolName,
    ) -> Option<Box<dyn ToolArgumentDiffConsumer>>

作用：为某个工具创建“参数变化接收器”。简单说，当模型一点点流式吐出工具参数时，这个接收器可以边看边处理参数的增量变化。

数据流：输入是工具名 → 它询问 ToolRegistry 这个工具有没有对应的参数增量接收器 → 输出一个可用的接收器，或者在不支持时输出空。

调用关系：它把“边生成边处理工具参数”的需求转交给工具登记册。调用方不需要知道每个工具具体怎么处理参数变化，只要通过路由器来要接收器即可。

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

fn tool_supports_parallel(&self, call: &ToolCall) -> bool

作用：判断某个工具调用能不能和其他工具调用并行执行。这样系统可以避免把不能同时跑的工具硬塞到并发流程里。

数据流：输入是一个 ToolCall → 它拿出工具名，去 ToolRegistry 查询该工具是否支持并行调用 → 输出 true 或 false；如果查不到，就保守地返回 false。

调用关系：它在调度工具调用前提供安全判断。真正的信息来自 ToolRegistry，ToolRouter 在这里负责把调用对象里的工具名拿出来并给出默认策略。

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

fn tool_waits_for_runtime_cancellation(&self, call: &ToolCall) -> bool

作用：判断取消工具时，系统是否应该等待工具运行环境完成清理。比如有些工具被取消后还要关进程、收尾日志，不能立刻当作结束。

数据流：输入是一个 ToolCall → 它用工具名询问 ToolRegistry 是否需要等待运行时取消清理 → 输出 true 或 false；查不到时默认认为不需要等待。

调用关系：它帮助取消流程做正确决定。路由器不自己清理工具，只负责告诉上层：这个工具取消后要不要给它时间收尾。

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

fn build_tool_call(item: ResponseItem) -> Result<Option<ToolCall>, FunctionCallError>

作用：把模型返回的一条消息，翻译成系统内部统一使用的 ToolCall。没有这一步，后面的执行器就得面对各种不同形状的模型输出，很容易出错。

数据流：输入是一个 ResponseItem，也就是模型输出中的一项 → 它判断这项是不是工具调用：普通函数调用会带上命名空间和名字，工具搜索调用会解析 JSON 参数，自定义工具调用会保存原始输入 → 输出 Some(ToolCall)；如果这项不是需要客户端执行的工具调用，就输出 None；如果工具搜索参数解析失败，就输出一个可反馈给模型的错误。

调用关系：它是模型输出进入工具系统的翻译关口。工具执行前，调用方会先用它把 ResponseItem 变成 ToolCall；后续再由派发函数把 ToolCall 送进 ToolRegistry。

调用图：调用 2 个内部函数（new, plain）；被 5 处调用（fatal_tool_error_stops_turn_and_reports_error, shell_tool_cancellation_waits_for_runtime_cleanup, handle_output_item_done, build_tool_call_uses_namespace_for_registry_name, extension_tool_executors_are_model_visible_and_dispatchable）；外部调用 1 个（from_value）。

async fn dispatch_tool_call_with_code_mode_result(
        &self,
        session: Arc<Session>,
        turn: Arc<TurnContext>,
        cancellation_token: CancellationToken,
        tracker: SharedT

作用：执行一个工具调用，并拿回统一的工具结果。它适合普通工具派发场景，不额外传入“终局结果是否已出现”的标记。

数据流：输入包括会话、当前轮上下文、取消令牌、差异跟踪器、工具调用和调用来源 → 它把这些原样交给内部派发函数，并说明没有额外的终局标记 → 输出工具执行结果，或者输出函数调用错误。

调用关系：它是公开一些的便捷包装函数。真正组装 ToolInvocation 和调用登记册的工作在 dispatch_tool_call_with_code_mode_result_inner 里完成。

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

async fn dispatch_tool_call_with_terminal_outcome(
        &self,
        session: Arc<Session>,
        turn: Arc<TurnContext>,
        cancellation_token: CancellationToken,
        tracker: SharedT

作用：执行工具调用，同时带上一个“终局结果是否已经达到”的共享标记。这个标记可以帮助系统在复杂流程里知道是否已经不需要继续等某些结果。

数据流：输入比普通派发多一个 AtomicBool（原子布尔值，可以被多个任务安全共享的一盏开关灯） → 它把所有信息交给内部派发函数，并把这盏开关灯一起传进去 → 输出工具执行结果或错误。

调用关系：它服务于需要关注终局状态的调度流程。它本身不执行工具，而是把额外状态包装好后交给 dispatch_tool_call_with_code_mode_result_inner。

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

async fn dispatch_tool_call_with_code_mode_result_inner(
        &self,
        session: Arc<Session>,
        turn: Arc<TurnContext>,
        cancellation_token: CancellationToken,
        tracker: S

作用：这是实际派发工具调用的核心小管道。它把零散的会话、工具名、参数、取消控制等信息打包成一次完整的工具执行请求。

数据流：输入是会话、轮次上下文、取消令牌、差异跟踪器、ToolCall、来源，以及可选的终局标记 → 它拆开 ToolCall，组装成 ToolInvocation（一次工具调用所需的完整包裹） → 然后交给 ToolRegistry 执行 → 输出任意工具结果 AnyToolResult，或执行中产生的错误。

调用关系：两个外层派发函数都会把活儿交给它。它是 ToolRouter 和 ToolRegistry 的交接点：路由器负责把信息整理成标准包裹，登记册负责找到对应工具并执行。

调用图：调用 1 个内部函数（dispatch_any_with_terminal_outcome）；被 2 处调用（dispatch_tool_call_with_code_mode_result, dispatch_tool_call_with_terminal_outcome）。

fn extension_tool_executors(
    session: &Session,
) -> Vec<Arc<dyn ToolExecutor<ExtensionToolCall>>>

作用：从当前会话里收集扩展插件提供的工具执行器。这样插件贡献的工具也能被纳入系统，而不只是内置工具能用。

数据流：输入是 Session，也就是当前会话及其服务集合 → 它找到所有扩展工具贡献者，并把会话级、线程级的扩展数据传给它们 → 收集每个贡献者返回的工具执行器 → 输出一组可执行扩展工具的对象。

调用关系：构建工具列表时会调用它。它把扩展系统和工具路由系统接起来：扩展负责提供工具，后续的工具构建和路由流程负责让这些工具对模型可见并能被派发执行。

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

fn matches_kind(&self, payload: &ToolPayload) -> bool

作用：判断某个工具是否能处理这次传进来的调用内容。默认只接受普通函数工具和工具搜索请求，避免拿错工具干错活。

数据流：输入是一份工具调用载荷 → 它检查载荷是不是函数调用或工具搜索 → 输出 true 或 false，告诉调度器能不能继续交给这个工具。

调用关系：ToolRegistry::dispatch_any_with_terminal_outcome 在真正执行前会问它一句；如果回答不能处理，调度器会立刻报错，而不会把不合适的请求塞给工具。

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

fn waits_for_runtime_cancellation(&self) -> bool

作用：说明工具被取消时，系统是否应该等工具自己做完收尾再返回“已中止”。默认不等。

数据流：没有输入 → 返回一个布尔值 → 这个值影响取消流程是马上结束，还是给工具留时间清理现场。

调用关系：ToolRegistry::waits_for_runtime_cancellation 会查询它；外层取消逻辑据此决定是否等待运行时清理。

fn telemetry_tags(
        &'a self,
        _invocation: &'a ToolInvocation,
    ) -> BoxFuture<'a, ToolTelemetryTags>

作用：给这次工具调用补充遥测标签。遥测标签就是日志里的分类小纸条，方便之后统计“哪个服务器、哪个来源、哪类工具”出了什么情况。

数据流：输入是一次工具调用 → 默认不添加任何标签 → 输出一个空列表；具体工具可以重写它，返回自己的标签。

调用关系：ToolRegistry::dispatch_any_with_terminal_outcome 在记录工具执行日志前会调用它，把这些标签合并进日志和追踪信息。

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

fn post_tool_use_payload(
        &self,
        invocation: &ToolInvocation,
        result: &dyn ToolOutput,
    ) -> Option<PostToolUsePayload>

作用：把工具执行后的结果整理成后置钩子能看懂的格式。后置钩子可以据此检查结果、追加上下文，甚至阻止结果给模型看。

数据流：输入是工具调用和工具输出 → 它提取工具名、调用编号、输入和响应内容 → 输出 PostToolUsePayload；如果不是函数类工具，输出空。

调用关系：handle_any_tool 在工具执行成功后会调用它，提前准备后置钩子的材料；之后 ToolRegistry::dispatch_any_with_terminal_outcome 会拿这些材料去运行后置钩子。

调用图：调用 4 个内部函数（function_hook_tool_name, post_tool_use_id, post_tool_use_input, post_tool_use_response）；被 1 处调用（handle_any_tool）。

fn pre_tool_use_payload(&self, invocation: &ToolInvocation) -> Option<PreToolUsePayload>

作用：把工具执行前的输入整理成前置钩子能看懂的格式。前置钩子可以用它来审查或改写即将执行的工具输入。

数据流：输入是工具调用 → 如果是函数工具，就把参数转成 JSON 值并配上钩子用的工具名 → 输出 PreToolUsePayload；否则输出空。

调用关系：ToolRegistry::dispatch_any_with_terminal_outcome 在执行工具前会调用它，然后把结果交给 run_pre_tool_use_hooks。

调用图：调用 2 个内部函数（function_hook_tool_input, function_hook_tool_name）。

fn with_updated_hook_input(
        &self,
        invocation: ToolInvocation,
        updated_input: Value,
    ) -> Result<ToolInvocation, FunctionCallError>

作用：当前置钩子改写了工具输入时，用改写后的内容重新生成一次工具调用。默认做法是把新的 JSON 输入重新变成函数字符串参数。

数据流：输入是原工具调用和钩子改过的 JSON 输入 → 它确认这是函数工具，再把 JSON 序列化成参数字符串 → 输出新的 ToolInvocation；失败时返回给模型看的错误。

调用关系：ToolRegistry::dispatch_any_with_terminal_outcome 在前置钩子返回 updated_input 时会调用它；有些工具可以重写它，以支持更稳定的自定义输入格式。

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

fn create_diff_consumer(&self) -> Option<Box<dyn ToolArgumentDiffConsumer>>

作用：为支持“参数一边生成一边消费”的工具创建消费者。默认没有这种能力。

数据流：没有输入 → 默认返回空 → 表示这个工具不处理流式参数差异。

调用关系：ToolRegistry::create_diff_consumer 会转发到这里；如果某个工具支持流式参数预览，就会提供自己的实现。

fn finish(&mut self) -> Result<Option<EventMsg>, FunctionCallError>

作用：告诉参数差异消费者：这次流式输入已经结束，可以做最后收尾。默认什么事件都不发。

数据流：没有额外输入 → 默认返回成功且没有事件 → 不改动外部状态。

调用关系：实现 ToolArgumentDiffConsumer 的工具可以重写它；调用方会在工具参数流结束前后用它收尾。

fn into_response(self) -> ResponseInputItem

作用：把统一包装的工具结果转换成协议里要返回给模型的消息。

数据流：输入是 AnyToolResult 本身 → 取出调用编号、原始载荷和工具输出 → 输出 ResponseInputItem，也就是模型能接收的结果项。

调用关系：工具调度完成后，外层流程需要把结果喂回模型时会用它；真正的转换工作交给具体 ToolOutput。

fn code_mode_result(self) -> serde_json::Value

作用：把工具结果转换成“代码模式”需要的 JSON 结果，而不是普通对话响应。

数据流：输入是 AnyToolResult 本身 → 取出载荷和工具输出 → 输出 serde_json::Value 形式的结果。

调用关系：代码模式分支会用它拿到更适合程序继续处理的结构化结果；具体格式由 ToolOutput 决定。

fn log_preview(&self) -> String

作用：保留原始工具输出的日志预览。即使给模型看的内容被后置钩子替换，日志里仍能看到原工具结果的摘要。

数据流：输入是这个包装输出对象 → 它转问 original 原始输出 → 返回原始日志预览字符串。

调用关系：ToolRegistry::dispatch_any_with_terminal_outcome 在后置钩子给出反馈消息时会用 PostToolUseFeedbackOutput 包住结果；日志预览仍走这里回到原输出。

fn success_for_logging(&self) -> bool

作用：保留原始工具执行是否成功的判断。反馈信息只改变给模型看的话，不改变工具本身成功与否。

数据流：输入是包装输出对象 → 它询问 original 原始输出的成功状态 → 返回 true 或 false。

调用关系：执行日志和生命周期记录会读取这个成功标记；它确保后置反馈不会篡改真实执行结果。

fn to_response_item(&self, call_id: &str, payload: &ToolPayload) -> ResponseInputItem

作用：把后置钩子提供的反馈消息转换成模型能看到的响应，替代原始工具输出。

数据流：输入是调用编号和工具载荷 → 它使用 model_visible 这份替代输出生成响应项 → 输出 ResponseInputItem。

调用关系：当后置钩子不阻止结果、但要求给模型显示一段反馈时，AnyToolResult::into_response 最终会走到这里。

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

fn code_mode_result(&self, payload: &ToolPayload) -> Value

作用：代码模式下仍返回原始工具结果，不让后置钩子的模型反馈覆盖结构化数据。

数据流：输入是工具载荷 → 它把请求交给 original 原始输出 → 返回原本的 JSON 结果。

调用关系：这和 to_response_item 形成区别：普通模型可见内容可能被替换，但代码模式需要保留真实工具输出。

fn override_tool_exposure(
    handler: Arc<dyn CoreToolRuntime>,
    exposure: ToolExposure,
) -> Arc<dyn CoreToolRuntime>

作用：临时改写一个工具的可见性，比如把工具隐藏起来，或改变它是否展示给模型。它不改工具本体，只是在外面套一层外壳。

数据流：输入是原工具处理器和目标可见性 → 如果原本就一样，直接返回原处理器；否则创建 ExposureOverride 包装器 → 输出新的工具处理器引用。

调用关系：add_with_exposure 和 add_collaboration_tools 会用它在注册工具时调整曝光策略；后续调度仍然像使用普通工具一样使用它。

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

fn tool_name(&self) -> ToolName

作用：让改写可见性的包装器继续报告原工具的名字。

数据流：没有额外输入 → 转问内部 handler 的 tool_name → 输出原工具名。

调用关系：ToolRegistry 注册和查找工具时会依赖工具名；这个包装器只改可见性，不改身份。

fn spec(&self) -> ToolSpec

作用：让包装器继续使用原工具的规格说明。规格说明就是告诉模型这个工具叫什么、需要什么参数、能做什么。

数据流：没有额外输入 → 转问内部 handler 的 spec → 输出原工具规格。

调用关系：构建模型可见工具列表时会读取规格；这里保证包装后工具能力描述不丢失。

fn exposure(&self) -> ToolExposure

作用：返回被强制指定的新可见性，而不是原工具自己的可见性。

数据流：没有额外输入 → 读取包装器保存的 exposure 字段 → 输出 ToolExposure。

调用关系：工具列表展示、隐藏工具判断、并行调用能力判断都会间接受它影响。

fn supports_parallel_tool_calls(&self) -> bool

作用：判断包装后的工具是否还能并行调用。隐藏工具会被直接视为不支持并行，其他情况再看原工具能力。

数据流：没有额外输入 → 先检查新可见性是否 Hidden，再询问原工具 → 输出是否支持并行。

调用关系：外层调度或模型工具声明会用这个结果；它避免隐藏工具还被当成可并行公开工具使用。

fn search_info(&self) -> Option<ToolSearchInfo>

作用：把原工具的搜索信息原样透传出去。搜索信息用于工具搜索功能判断这个工具能否被检索到。

数据流：没有额外输入 → 转问内部 handler 的 search_info → 输出可选搜索信息。

调用关系：工具搜索相关流程读取它；包装器只影响曝光，不重新定义搜索元数据。

fn handle(&self, invocation: ToolInvocation) -> codex_tools::ToolExecutorFuture<'_>

作用：真正执行工具时，包装器不插手，直接把调用交给原工具。

数据流：输入是一次工具调用 → 转交给内部 handler.handle → 输出原工具的异步执行结果。

调用关系：ToolRegistry 调度到这个包装器时，最终仍会通过这里执行原工具逻辑。

fn matches_kind(&self, payload: &ToolPayload) -> bool

作用：判断载荷类型是否匹配时，包装器直接沿用原工具的判断。

数据流：输入是工具调用载荷 → 转问内部 handler.matches_kind → 输出 true 或 false。

调用关系：ToolRegistry::dispatch_any_with_terminal_outcome 执行前会检查它；包装器不改变工具能处理的调用类型。

fn waits_for_runtime_cancellation(&self) -> bool

作用：取消等待策略沿用原工具。包装器不会改变工具清理现场的需要。

数据流：没有额外输入 → 转问内部 handler → 输出是否等待取消清理。

调用关系：ToolRegistry::waits_for_runtime_cancellation 查询包装工具时会得到原工具的真实策略。

fn pre_tool_use_payload(&self, invocation: &ToolInvocation) -> Option<PreToolUsePayload>

作用：执行前给钩子的材料沿用原工具的生成方式。

数据流：输入是工具调用 → 转问内部 handler.pre_tool_use_payload → 输出可选的前置钩子载荷。

调用关系：ToolRegistry 执行前置钩子时会用到它；包装器不改变钩子看到的工具输入。

fn post_tool_use_payload(
        &self,
        invocation: &ToolInvocation,
        result: &dyn ToolOutput,
    ) -> Option<PostToolUsePayload>

作用：执行后给钩子的材料也沿用原工具的生成方式。

数据流：输入是工具调用和工具输出 → 转问内部 handler.post_tool_use_payload → 输出可选的后置钩子载荷。

调用关系：handle_any_tool 调用它时，即使工具被包装过，后置钩子仍看到原工具定义的稳定格式。

fn with_updated_hook_input(
        &self,
        invocation: ToolInvocation,
        updated_input: Value,
    ) -> Result<ToolInvocation, FunctionCallError>

作用：当前置钩子改写输入时，仍由原工具决定怎么把新输入变回工具调用。

数据流：输入是原调用和改写后的 JSON 输入 → 转交内部 handler.with_updated_hook_input → 输出新调用或错误。

调用关系：ToolRegistry::dispatch_any_with_terminal_outcome 在前置钩子改写输入后会走到这里；包装器不破坏工具自己的改写规则。

fn telemetry_tags(
        &'a self,
        invocation: &'a ToolInvocation,
    ) -> BoxFuture<'a, ToolTelemetryTags>

作用：遥测标签沿用原工具提供的标签。

数据流：输入是工具调用 → 转问内部 handler.telemetry_tags → 输出标签列表。

调用关系：ToolRegistry 记录工具日志时会合并这些标签；包装可见性不会让工具的统计分类丢失。

fn create_diff_consumer(&self) -> Option<Box<dyn ToolArgumentDiffConsumer>>

作用：流式参数差异消费者也沿用原工具的实现。

数据流：没有额外输入 → 转问内部 handler.create_diff_consumer → 输出可选消费者。

调用关系：ToolRegistry::create_diff_consumer 查询包装工具时会通过这里拿到原工具的消费者。

fn new(tools: HashMap<ToolName, Arc<dyn CoreToolRuntime>>) -> Self

作用：用一张已经整理好的工具表创建注册表。它是最基础的构造函数。

数据流：输入是“工具名到工具处理器”的映射表 → 保存到 ToolRegistry 里 → 输出一个可查询、可调度的注册表。

调用关系：ToolRegistry::from_tools、测试辅助函数以及部分测试会调用它；正常业务更常通过 from_tools 创建。

调用图：被 2 处调用（dispatch_notifies_tool_lifecycle_contributors, handler_looks_up_namespaced_aliases_explicitly）。

fn from_tools(tools: impl IntoIterator<Item = Arc<dyn CoreToolRuntime>>) -> Self

作用：把一串工具处理器整理成按名字查找的注册表，并检查有没有重名工具。

数据流：输入是一批工具 → 逐个读取工具名，放入 HashMap；如果发现重名，就报错或触发 panic → 输出 ToolRegistry。

调用关系：build_model_visible_specs_and_registry 等注册流程会用它建立正式工具表；多项测试也用它验证取消和生命周期行为。

调用图：调用 1 个内部函数（error_or_panic）；被 3 处调用（cancellation_after_handler_finishes_preserves_completed_lifecycle, cancellation_waiting_for_runtime_cleanup_emits_only_aborted_lifecycle, build_model_visible_specs_and_registry）；外部调用 3 个（new, new, format!）。

fn empty_for_test() -> Self

作用：创建一个空工具注册表，专门给测试用。

数据流：没有输入 → 创建空 HashMap → 输出没有任何工具的 ToolRegistry。

调用关系：测试 unsupported tool 这类场景时会用它，因为需要模拟“系统里没有这个工具”。

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

fn with_handler_for_test(handler: Arc<T>) -> Self

作用：创建一个只包含单个工具处理器的测试注册表，方便测试某个工具的调度行为。

数据流：输入是一个工具处理器 → 读取它的工具名，放进只有一项的映射表 → 输出 ToolRegistry。

调用关系：多个调度和追踪测试会用它快速搭建环境，不必注册完整工具集合。

调用图：被 3 处调用（dispatch_lifecycle_trace_records_direct_and_code_mode_requesters, dispatch_lifecycle_trace_records_incompatible_payload_failures, missing_code_mode_wait_traces_only_the_wait_tool_call）；外部调用 2 个（from, new）。

fn tool(&self, name: &ToolName) -> Option<Arc<dyn CoreToolRuntime>>

作用：按工具名从注册表里取出工具处理器。返回的是共享引用，方便异步流程安全使用同一个工具。

数据流：输入是工具名 → 在内部 HashMap 查找并克隆 Arc 引用 → 输出工具处理器，找不到则输出空。

调用关系：create_diff_consumer、supports_parallel_tool_calls、waits_for_runtime_cancellation 和 dispatch_any_with_terminal_outcome 都通过它找工具。

调用图：被 4 处调用（create_diff_consumer, dispatch_any_with_terminal_outcome, supports_parallel_tool_calls, waits_for_runtime_cancellation）。

fn tool_names_for_test(&self) -> Vec<ToolName>

作用：列出测试注册表里的所有工具名，并排序，方便测试稳定比较。

数据流：没有额外输入 → 收集 HashMap 里的所有名字并排序 → 输出工具名列表。

调用关系：registered_tool_names_for_test 这类测试辅助会调用它，确认注册结果符合预期。

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

fn tool_exposure(&self, name: &ToolName) -> Option<ToolExposure>

作用：查询某个工具当前对模型的可见性，主要给测试验证用。

数据流：输入是工具名 → 找到工具后读取 exposure → 输出可见性；找不到则输出空。

调用关系：tool_exposure_for_test 会调用它，检查工具隐藏、公开或其他曝光设置是否正确。

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

fn create_diff_consumer(
        &self,
        name: &ToolName,
    ) -> Option<Box<dyn ToolArgumentDiffConsumer>>

作用：按工具名创建这个工具的流式参数差异消费者。如果工具不存在或不支持，就返回空。

数据流：输入是工具名 → 先查工具，再调用工具自己的 create_diff_consumer → 输出可选消费者。

调用关系：外层流式工具调用流程会通过它拿消费者；它本身只是注册表到具体工具之间的转发站。

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

fn supports_parallel_tool_calls(&self, name: &ToolName) -> Option<bool>

作用：查询某个工具是否支持并行调用。并行调用就是多个工具请求同时跑，能提速但要求工具自己安全。

数据流：输入是工具名 → 找到工具后询问 supports_parallel_tool_calls → 输出可选布尔值。

调用关系：tool_supports_parallel 等外层逻辑会调用它，决定是否允许这个工具和其他工具一起跑。

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

fn waits_for_runtime_cancellation(&self, name: &ToolName) -> Option<bool>

作用：查询某个工具取消时是否需要等待运行时清理。

数据流：输入是工具名 → 找到工具后询问 waits_for_runtime_cancellation → 输出可选布尔值。

调用关系：tool_waits_for_runtime_cancellation 等取消控制逻辑会用它，决定取消工具时的等待策略。

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

async fn dispatch_any(
        &self,
        invocation: ToolInvocation,
    ) -> Result<AnyToolResult, FunctionCallError>

作用：用默认方式调度一次工具调用。它是较简单的入口，不关心外部是否已经记录过终态。

数据流：输入是一次 ToolInvocation → 调用 dispatch_any_with_terminal_outcome，并传入空的终态标记 → 输出统一工具结果或错误。

调用关系：它把真正复杂的调度工作交给 dispatch_any_with_terminal_outcome；适合不需要特殊取消终态协调的调用方。

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

async fn dispatch_any_with_terminal_outcome(
        &self,
        mut invocation: ToolInvocation,
        terminal_outcome_reached: Option<Arc<AtomicBool>>,
    ) -> Result<AnyToolResult, FunctionCa

作用：这是整个文件的核心调度流程：从接到工具调用，到检查、跑前置钩子、执行工具、跑后置钩子、记录日志和生命周期，全部在这里串起来。

数据流：输入是工具调用，以及一个可选的“终态是否已通知”标记 → 它读取会话、权限、工具表和遥测信息；检查工具是否存在、输入是否匹配；运行前置钩子，可能拦截或改写输入；执行工具并记录日志；成功后运行后置钩子，可能阻止结果或替换给模型看的内容；最后通知工具结束 → 输出 AnyToolResult，或返回给模型/系统的错误。

调用关系：dispatch_any 和 dispatch_tool_call_with_code_mode_result_inner 会调用它。它向下调用 run_pre_tool_use_hooks、handle_any_tool、run_post_tool_use_hooks、notify_tool_finish_if_unclaimed 等，是工具调用链路里的总指挥。

调用图：调用 13 个内部函数（record_additional_contexts, run_post_tool_use_hooks, run_pre_tool_use_hooks, emit_metric_for_tool_read, permission_profile_policy_tag, permission_profile_sandbox_tag, from_text, flat_tool_name, notify_tool_start, tool (+3 more)）；被 2 处调用（dispatch_any, dispatch_tool_call_with_code_mode_result_inner）；外部调用 9 个（new, new, with_capacity, clone, format!, matches!, new, Fatal, RespondToModel）。

async fn notify_tool_finish_if_unclaimed(
    invocation: &ToolInvocation,
    terminal_outcome_reached: Option<&AtomicBool>,
    outcome: ToolCallOutcome,
) -> bool

作用：安全地通知“工具结束了”，并避免同一次工具调用被重复通知终态。

数据流：输入是工具调用、可选原子布尔标记和结果状态 → 如果标记显示别人已经通知过，就什么也不做并返回 false；否则设置标记并发送结束通知 → 返回 true。

调用关系：ToolRegistry::dispatch_any_with_terminal_outcome 在工具被前置钩子阻止、执行失败、执行成功等路径都会调用它，确保生命周期事件只发一次。

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

async fn handle_any_tool(
    tool: &dyn CoreToolRuntime,
    invocation: ToolInvocation,
) -> Result<AnyToolResult, FunctionCallError>

作用：真正调用某个工具处理器，并把它的输出包装成统一结果。它还会处理“外部上下文污染内存模式”这类安全标记。

数据流：输入是工具处理器和工具调用 → 克隆调用编号和载荷，执行 tool.handle；如果输出含外部上下文且配置要求禁用相关记忆，就在状态库标记线程记忆模式被污染；然后生成后置钩子载荷 → 输出 AnyToolResult。

调用关系：ToolRegistry::dispatch_any_with_terminal_outcome 在日志包裹器里面调用它；它上接调度流程，下接具体工具的 handle 实现。

调用图：调用 2 个内部函数（post_tool_use_payload, mark_thread_memory_mode_polluted）；外部调用 2 个（clone, handle）。

fn function_hook_tool_name(invocation: &ToolInvocation) -> HookToolName

作用：把内部工具名转换成钩子系统使用的工具名。特殊地，spawn_agent 会被映射成钩子认识的标准名字。

数据流：输入是工具调用 → 如果是指定命名空间下的 spawn_agent，就返回专门的 spawn_agent 钩子名；否则把工具名压平成字符串 → 输出 HookToolName。

调用关系：CoreToolRuntime::pre_tool_use_payload 和 CoreToolRuntime::post_tool_use_payload 都用它，让前置/后置钩子看到一致的工具名。

调用图：调用 3 个内部函数（flat_tool_name, new, spawn_agent）；被 2 处调用（post_tool_use_payload, pre_tool_use_payload）；外部调用 1 个（matches!）。

fn function_hook_tool_input(arguments: &str) -> Value

作用：把函数字符串参数转换成钩子更容易处理的 JSON 输入。

数据流：输入是一段参数字符串 → 如果是空白，就返回空 JSON 对象；如果能解析成 JSON，就返回解析后的值；解析失败则把原字符串当普通文本返回 → 输出 serde_json::Value。

调用关系：CoreToolRuntime::pre_tool_use_payload 会调用它，准备给前置钩子的 tool_input。

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

fn unsupported_tool_call_message(payload: &ToolPayload, tool_name: &ToolName) -> String

作用：为“不支持的工具调用”生成一条清楚的错误消息。

数据流：输入是工具载荷和工具名 → 如果是自定义工具载荷，就生成“unsupported custom tool call”；否则生成普通“unsupported call” → 输出错误字符串。

调用关系：ToolRegistry::dispatch_any_with_terminal_outcome 找不到工具时会调用它，然后把这条消息记录到遥测并返回给模型。

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

fn server_request_thread_id(request: &ServerRequest) -> Option<ThreadId>

作用：从一个服务器请求里找出它属于哪个聊天线程。有人处理请求时会用它来决定把审批、输入请求等送到哪个线程界面。

数据流：输入是一个 ServerRequest（服务器请求）。函数查看请求的具体种类：如果这种请求带有 thread_id，就把字符串形式的编号转换成 ThreadId；转换成功就输出 Some(ThreadId)，转换失败或这种请求本来不属于线程就输出 None。它不改动请求本身。

调用关系：它在处理服务器请求时被 handle_server_request_event 调用。它只做一件事：借助 from_string 把文本编号变成可靠的 ThreadId，然后把结果交回给上层，让上层继续决定消息该路由到哪里。

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

fn server_notification_thread_target(
    notification: &ServerNotification,
) -> ServerNotificationThreadTarget

作用：判断一条服务器通知应该投递到哪里：某个线程、整个应用、全局区域，还是标记为坏的线程编号。它是通知分发前的“地址识别器”。

数据流：输入是一条 ServerNotification（服务器通知）。函数先按通知类型取出可能存在的 thread_id；如果拿到线程编号，就用 from_string 检查并转换，成功输出 Thread(ThreadId)，失败输出 InvalidThreadId；如果通知明确是应用级的 MCP 状态，就输出 AppScoped；如果没有线程归属，就输出 Global。它不修改通知，只返回目标分类。

调用关系：正式运行时，handle_server_notification_event 会调用它来决定通知发到哪里。测试函数也会直接调用它，验证警告、守护警告、MCP 启动状态、线程设置更新这些场景是否被分到正确目标。它内部把最终结果包装成 Thread 或 InvalidThreadId 等枚举值。

调用图：调用 1 个内部函数（from_string）；被 7 处调用（guardian_warning_notifications_route_to_threads, mcp_startup_notifications_route_to_threads, mcp_startup_notifications_without_threads_are_app_scoped, thread_settings_updated_notifications_route_to_threads, warning_notifications_route_to_threads_when_thread_id_is_present, warning_notifications_without_threads_are_global, handle_server_notification_event）；外部调用 2 个（InvalidThreadId, Thread）。

fn test_thread_settings() -> ThreadSettings

作用：构造一份测试用的线程设置。测试线程设置更新通知时，需要一份像真的一样的数据，但不想每个测试都重复写一大坨字段。

数据流：输入没有显式参数。函数用 test_path_buf 生成一个测试路径，再填好模型、沙盒、审批策略、协作模式等字段，最后输出一个 ThreadSettings 对象。它只生成测试数据，不影响真实配置。

调用关系：它被 tests::thread_settings_updated_notifications_route_to_threads 使用，作为构造 ThreadSettingsUpdated 通知的配套材料。它属于测试辅助函数，不参与真实运行流程。

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

fn warning_notifications_without_threads_are_global()

作用：验证没有线程编号的普通警告会被当成全局通知。这样警告不会被错误塞进某个聊天线程里。

数据流：测试先造一条 Warning 通知，其中 thread_id 是 None。然后把它传给 server_notification_thread_target，得到目标分类。最后用 assert_eq! 检查结果是不是 Global。

调用关系：这个测试直接覆盖 server_notification_thread_target 的一个边界情况：警告可以没有线程编号。它帮助保证通知分发逻辑以后改动时不会把这种消息误分到线程。

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

fn warning_notifications_route_to_threads_when_thread_id_is_present()

作用：验证普通警告如果带了线程编号，就会被送到对应线程。这样用户能在正确的聊天上下文里看到警告。

数据流：测试先用 new 生成一个新的 ThreadId，把它转成字符串放进 Warning 通知。然后调用 server_notification_thread_target。函数返回后，测试确认结果是 Thread，并且里面的编号就是刚才生成的那个。

调用关系：这个测试检查 server_notification_thread_target 对 Warning 通知的另一种情况。它和“没有线程编号时是全局”的测试一起，说明 Warning 的路由取决于有没有 thread_id。

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

fn guardian_warning_notifications_route_to_threads()

作用：验证 GuardianWarning（守护/安全检查类警告）一定会按线程编号投递到对应线程。这样安全提醒不会跑错地方。

数据流：测试生成一个 ThreadId，把它写进 GuardianWarning 通知。然后调用 server_notification_thread_target，最后断言结果是 Thread，并且线程编号一致。

调用关系：这个测试直接调用 server_notification_thread_target，专门保护 GuardianWarning 的分发规则。它说明这类警告不是全局消息，而是跟某个线程绑定。

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

fn mcp_startup_notifications_route_to_threads()

作用：验证 MCP 服务器状态通知如果带线程编号，就会送到该线程。MCP 可以粗略理解成外部工具服务，这里是在测试它启动状态的消息归属。

数据流：测试生成一个 ThreadId，构造一条 McpServerStatusUpdated 通知，并把 thread_id 填进去。之后调用 server_notification_thread_target，最后检查返回的是 Thread(thread_id)。

调用关系：这个测试覆盖 server_notification_thread_target 对 MCP 状态通知的线程级处理。它和无线程编号的 MCP 测试成对存在，确保两种情况分得清。

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

fn mcp_startup_notifications_without_threads_are_app_scoped()

作用：验证 MCP 服务器状态通知如果没有线程编号，就算作应用范围通知，而不是普通全局通知。这样界面可以把它放在更合适的应用级位置。

数据流：测试构造一条 McpServerStatusUpdated 通知，其中 thread_id 是 None。然后调用 server_notification_thread_target，最后断言结果是 AppScoped。

调用关系：这个测试保护 server_notification_thread_target 里一个特殊规则：MCP 状态没有线程时返回 AppScoped。它说明这个文件不只是简单地“有线程就线程、没线程就全局”，还有少数应用级例外。

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

fn thread_settings_updated_notifications_route_to_threads()

作用：验证线程设置更新通知会被送回对应线程。这样某个聊天线程的模型、权限、沙盒等设置变化，不会影响或显示到别的线程。

数据流：测试先生成 ThreadId，再用 test_thread_settings 做一份线程设置，构造 ThreadSettingsUpdated 通知。随后调用 server_notification_thread_target，并检查结果是同一个 ThreadId 对应的 Thread。

调用关系：这个测试调用 server_notification_thread_target，并依赖 tests::test_thread_settings 提供完整测试数据。它确保线程设置变化这种通知仍然按照线程编号正确分发。

调用图：调用 2 个内部函数（new, server_notification_thread_target）；外部调用 3 个（ThreadSettingsUpdated, assert_eq!, test_thread_settings）。

fn app_server_attestation_provider(
    outgoing: Arc<OutgoingMessageSender>,
    thread_state_manager: ThreadStateManager,
) -> Arc<dyn AttestationProvider>

作用：创建一个给核心系统使用的证明提供者。调用方把发送消息的通道和线程状态交进来，它返回一个统一接口，之后核心系统就能通过这个接口要证明头。

数据流：进去的是 outgoing 消息发送器和 thread_state_manager 线程状态管理器 → 它把 outgoing 转成弱引用，也就是“不强行让发送器一直活着”的引用，再和线程状态一起放进 AppServerAttestationProvider → 出来的是一个可共享的 AttestationProvider 对象，供别处按接口调用。

调用关系：这是本文件对外搭桥的入口。它内部用 Arc::downgrade 保存 outgoing，避免这个证明提供者反过来延长 outgoing 的生命周期；之后真正生成请求头的工作，会在 AppServerAttestationProvider::header_for_request 里发生。

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

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

作用：给 AppServerAttestationProvider 提供调试打印的样子。它不会把内部复杂字段展开，只打印结构名，方便日志或调试时识别对象类型。

数据流：进去的是一个格式化器 formatter → 它告诉 formatter 打印一个名叫 AppServerAttestationProvider 的调试结构 → 出来的是格式化是否成功的结果，不改变证明流程里的业务数据。

调用关系：这是 Rust 调试输出机制会自动用到的小配件。它不参与证明请求本身，只在有人打印或记录这个对象时被调用，并把具体格式化工作交给标准库的 debug_struct。

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

fn header_for_request(&self, context: AttestationContext) -> GenerateAttestationFuture<'_>

作用：在需要发请求时，异步生成一个可以放进 HTTP 头里的证明值。它会先确认消息通道还活着，再去找客户端生成证明。

数据流：进去的是 AttestationContext，上下文里包含 thread_id，也就是这次请求属于哪个线程 → 它先把弱引用升级成可用的 outgoing；如果通道已经没了，就直接返回 None；如果还在，就复制线程状态管理器，并启动异步流程去请求证明 → 出来的是一个未来会完成的结果：可能是合法的 HeaderValue，也可能是 None。

调用关系：这是核心系统通过 AttestationProvider 接口真正会调用的方法。它自己不直接处理所有细节，而是把找连接、发请求、等结果、包装 JSON 的工作交给 request_attestation_header_value_with_timeout；最后再把字符串转成 HTTP 头专用的 HeaderValue。

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

async fn request_attestation_header_value_with_timeout(
    outgoing: Arc<OutgoingMessageSender>,
    thread_state_manager: ThreadStateManager,
    thread_id: codex_protocol::ThreadId,
    timeout_dur

作用：向某个支持证明功能的连接发送“生成证明”的请求，并在限定时间内等结果。它负责把成功和各种失败都转换成统一的头部字符串。

数据流：进去的是 outgoing 消息发送器、线程状态管理器、thread_id 和超时时长 → 它先问线程状态管理器：这个线程里第一个能生成证明的连接是谁；找不到就返回 None。找到后，它只向这个连接发送 AttestationGenerate 请求，然后等待回应。成功时，它把回应解析成 AttestationGenerateResponse，取出 token；失败、取消、超时或返回格式错误时，它写日志并选择对应状态码 → 出来的是一个 JSON 字符串，比如成功时带 token，失败时只带版本号和状态码；超时时还会主动取消刚才发出的请求。

调用关系：它是 AppServerAttestationProvider::header_for_request 背后的主流程。它会调用 first_attestation_capable_connection_for_thread 找可用连接，调用 outgoing 的发送能力把请求交给客户端，再调用 app_server_attestation_header_value 把最终状态包装成头值。

调用图：调用 2 个内部函数（app_server_attestation_header_value, first_attestation_capable_connection_for_thread）；被 1 处调用（header_for_request）；外部调用 3 个（AttestationGenerate, timeout, warn!）。

fn code(self) -> u8

作用：把证明生成的结果状态变成一个小数字。这样放进 HTTP 头里的 JSON 更短，也方便接收方按固定编号理解发生了什么。

数据流：进去的是一个状态，比如 Ok、Timeout、RequestFailed → 它按固定映射转成数字：成功是 0，超时是 1，请求失败是 2，请求取消是 3，返回格式错误是 4 → 出来的是这个状态对应的 u8 数字，不改动任何外部数据。

调用关系：它只被 app_server_attestation_header_value 使用。后者在组装 JSON 信封时，需要把人能读懂的枚举状态转换成机器更容易传输的状态码。

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

fn app_server_attestation_header_value(
    status: AppServerAttestationStatus,
    token: Option<&str>,
) -> Option<String>

作用：把证明结果包装成一个短小的 JSON 字符串，作为 HTTP 头的内容。成功时会带 token，失败时会带失败状态码但不带 token。

数据流：进去的是状态和可选 token → 它创建一个信封对象，里面有版本号 v、状态码 s，以及可选的 token 字段 t；如果 token 是 None，就不写 t 字段；然后把这个信封序列化成 JSON 字符串 → 出来的是 Some(JSON 字符串)，如果序列化意外失败就记录警告并返回 None。

调用关系：这是证明流程最后的打包步骤。request_attestation_header_value_with_timeout 在成功、超时、请求失败、请求取消、返回格式错误等分支都会调用它；它内部又调用 AppServerAttestationStatus::code 来拿状态数字。

调用图：调用 1 个内部函数（code）；被 1 处调用（request_attestation_header_value_with_timeout）；外部调用 1 个（to_string）。

fn app_server_attestation_header_value_wraps_opaque_client_payloads()

作用：测试成功场景下，客户端给的 token 会被原样放进 JSON 信封里。这里的 token 被当成不透明内容，也就是本文件不理解、不拆开，只负责转交。

数据流：进去的是一个成功状态 Ok 和字符串 v1.opaque-client-payload → 测试调用 app_server_attestation_header_value 生成 JSON → 出来后用断言检查结果必须正好是包含版本号、成功状态码和 token 的字符串。

调用关系：这是给 app_server_attestation_header_value 的保护性测试。它确保以后有人改包装格式时，不会意外破坏成功响应中 token 的传递方式。

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

fn app_server_attestation_header_value_reports_app_server_failures()

作用：测试失败场景下，头部 JSON 会正确报告失败原因，而且不会带 token。这样接收方能区分是超时、请求失败、取消，还是返回格式坏了。

数据流：进去的是四种失败状态：Timeout、RequestFailed、RequestCanceled、MalformedResponse，并且 token 都是 None → 测试分别调用 app_server_attestation_header_value → 出来后逐个断言 JSON 字符串里的状态码分别是 1、2、3、4，并且没有 t 字段。

调用关系：这是 app_server_attestation_header_value 的另一组保护性测试。它对应 request_attestation_header_value_with_timeout 里的多个失败分支，确保这些分支最后写进头里的状态码不会乱。

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

fn new(outgoing: Arc<OutgoingMessageSender>) -> Self

作用：创建一个文件监听管理器，给服务器处理“监听文件变化”的请求用。它会优先使用真正的文件监听器；如果系统不支持或创建失败，就退回到一个什么也不做的空监听器，避免整个服务器启动失败。

数据流：进去的是一个 outgoing，也就是服务器给客户端发消息的通道。函数尝试创建 FileWatcher（文件监听器）；成功就保存它，失败就记录一条警告并换成 noop（空实现，意思是不真正监听）。最后把消息通道、监听器和空的登记表组合成一个 FsWatchManager 返回。

调用关系：这是正常创建 FsWatchManager 的入口。它自己不直接组装所有字段，而是把选好的 FileWatcher 交给 FsWatchManager::new_with_file_watcher；测试里则会绕过它，直接用 new_with_file_watcher 塞入空监听器，方便验证登记逻辑。

调用图：调用 2 个内部函数（new, noop）；被 1 处调用（new）；外部调用 3 个（new, new_with_file_watcher, warn!）。

fn new_with_file_watcher(
        outgoing: Arc<OutgoingMessageSender>,
        file_watcher: Arc<FileWatcher>,
    ) -> Self

作用：用指定的文件监听器创建管理器。这个函数主要给测试或特殊场景用，因为它允许外面传入一个假的或空的监听器。

数据流：进去的是发消息用的 outgoing 和已经准备好的 file_watcher。函数新建一个共享状态 state，里面一开始没有任何监听记录，然后把三样东西包进 FsWatchManager 返回。

调用关系：FsWatchManager::new 会在挑好真实或空的 FileWatcher 后调用它。测试辅助函数 tests::manager_with_noop_watcher 也会调用它，用空监听器做出一个不会碰真实文件系统事件的管理器。

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

async fn watch(
        &self,
        connection_id: ConnectionId,
        params: FsWatchParams,
    ) -> Result<FsWatchResponse, JSONRPCErrorError>

作用：处理客户端的“开始监听这个文件”请求。它会登记这个监听，并在后台等文件变化，变化后把通知发回发起请求的那个连接。

数据流：进去的是连接编号 connection_id 和监听参数 params，里面有 watch_id 和文件路径。函数先用“连接编号 + watch_id”组成唯一钥匙；如果同一个连接已经用过这个 watch_id，就返回一个 JSON-RPC 错误（JSON-RPC 是一种客户端和服务器互发请求/回复的格式）。如果没重复，它会向底层 FileWatcher 订阅这个路径，保存取消用的通道和注册信息，然后启动一个 tokio 后台任务（tokio 是 Rust 常用的异步运行器）。后台任务收到文件变化后，先防抖合并，再把变化路径排序，最后通过 outgoing 发 FsChanged 通知。函数本身马上返回 FsWatchResponse，表示监听登记成功。

调用关系：这是客户端请求开始监听时的核心流程。它会调用 invalid_request 生成重复 watch_id 的错误，会用底层 FileWatcher 注册路径，还会把真正等待变化和发通知的工作交给 tokio::spawn 创建的后台任务。之后 FsWatchManager::unwatch 可以通过保存的 terminate_tx 叫这个后台任务停下。

调用图：调用 2 个内部函数（invalid_request, new）；被 1 处调用（watch）；外部调用 7 个（FsChanged, format!, channel, pin!, select!, spawn, vec!）。

async fn unwatch(
        &self,
        connection_id: ConnectionId,
        params: FsUnwatchParams,
    ) -> Result<FsUnwatchResponse, JSONRPCErrorError>

作用：处理客户端的“不要再监听了”请求。它只会取消同一个连接自己创建的监听，不会让别的连接代删。

数据流：进去的是连接编号和要取消的 watch_id。函数用这两个值拼出钥匙，到登记表里删除对应记录；如果找到了，就通过一次性通道 oneshot（只发送一次消息的小管道）通知后台任务退出，并等待后台任务确认结束。最后返回一个空的 FsUnwatchResponse，表示取消流程结束；如果本来就没有这条监听，也会当作成功。

调用关系：它和 FsWatchManager::watch 是一对：watch 登记并启动后台任务，unwatch 删除登记并叫任务停下。这里等待 done_rx 的目的很重要：保证取消响应之后，不会再发出这条监听的旧文件变化通知。

调用图：被 1 处调用（unwatch）；外部调用 1 个（channel）。

async fn connection_closed(&self, connection_id: ConnectionId)

作用：当某个客户端连接断开时，清理这个连接名下的所有监听记录。这样服务器不会一直记着已经没人接收的监听。

数据流：进去的是断开的 connection_id。函数锁住共享状态，从登记表里筛掉所有属于这个连接的 WatchKey。出来没有返回值，但内部状态会少掉这些监听记录。

调用关系：这是连接生命周期结束时会用到的清理动作。它不处理某个具体 watch_id，而是按连接编号批量清理，和 FsWatchManager::watch 保存的“连接编号 + watch_id”钥匙设计配合使用。

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

fn absolute_path(path: PathBuf) -> AbsolutePathBuf

作用：测试用的小工具，把普通路径转成项目要求的绝对路径类型。它顺便检查测试没有误传相对路径。

数据流：进去的是 PathBuf，也就是一段文件路径。函数先断言它必须是绝对路径；如果不是，测试直接失败。然后把它转换成 AbsolutePathBuf 并返回。

调用关系：多个测试在调用 FsWatchManager::watch 前都会用它准备路径。这样测试关注监听逻辑，不用在每个测试里重复写路径校验和转换代码。

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

fn manager_with_noop_watcher() -> FsWatchManager

作用：测试用的小工厂，做出一个不会真正监听文件系统的 FsWatchManager。这样测试可以稳定地检查登记、取消和去重逻辑，而不受操作系统文件事件影响。

数据流：函数没有外部输入。它创建一个很小的消息通道，创建一个关闭 analytics（统计上报）的 OutgoingMessageSender，再配上 FileWatcher::noop 这个空监听器，最后调用 FsWatchManager::new_with_file_watcher 返回测试管理器。

调用关系：所有测试基本都从这里拿管理器。它把真实文件监听替换成空实现，让测试只验证本文件自己的状态变化，比如 entries 里有没有正确的 WatchKey。

调用图：调用 4 个内部函数（disabled, new_with_file_watcher, new, noop）；外部调用 2 个（new, channel）。

async fn watch_uses_client_id_and_tracks_the_owner_scoped_entry()

作用：这个测试确认：开始监听后，管理器登记的是“连接编号 + watch_id”，而不是只记 watch_id。这样同名 watch_id 在不同连接之间不会混淆。

数据流：测试先创建临时目录和一个 HEAD 文件，再用空监听器管理器发起 watch 请求。然后它检查返回的路径就是传入路径，并读取内部 state，确认 entries 里正好有一条属于 ConnectionId(1) 和 watch-head 的记录。

调用关系：它调用 tests::manager_with_noop_watcher 准备管理器，调用 tests::absolute_path 准备路径，再调用 FsWatchManager::watch。这个测试覆盖了 watch 的成功登记路径。

调用图：外部调用 6 个（new, new, absolute_path, manager_with_noop_watcher, assert_eq!, write）。

async fn unwatch_is_scoped_to_the_connection_that_created_the_watch()

作用：这个测试确认：一个连接不能取消另一个连接创建的监听。它防止客户端之间互相干扰。

数据流：测试先让 ConnectionId(1) 创建 watch-head 监听。然后 ConnectionId(2) 尝试取消同名 watch_id，内部登记应该还在。接着 ConnectionId(1) 自己取消，登记才应该消失。

调用关系：它先通过 FsWatchManager::watch 建立记录，再两次调用 FsWatchManager::unwatch。这个测试专门验证 unwatch 使用“连接编号 + watch_id”作为范围，而不是只看 watch_id。

调用图：外部调用 6 个（new, new, absolute_path, manager_with_noop_watcher, assert!, write）。

async fn watch_rejects_duplicate_id_for_the_same_connection()

作用：这个测试确认：同一个连接不能重复使用同一个 watch_id。否则后面取消或通知时就不知道该对应哪一条监听。

数据流：测试创建两个不同文件。ConnectionId(1) 先用 watch-head 监听第一个文件，应该成功；再用同一个 watch_id 监听第二个文件，应该失败。最后检查错误消息是“watchId already exists: watch-head”，并确认登记表里仍然只有第一条记录。

调用关系：它调用 FsWatchManager::watch 两次，第二次触发 watch 里的重复检查，也就是 Entry::Occupied 分支和 invalid_request 错误。这个测试保护 watch_id 去重规则不被改坏。

调用图：外部调用 6 个（new, new, absolute_path, manager_with_noop_watcher, assert_eq!, write）。

async fn connection_closed_removes_only_that_connections_watches()

作用：这个测试确认：连接断开时，只清理这个连接自己的监听，不会误删其他连接的监听。

数据流：测试先创建三个文件，让 ConnectionId(1) 建两个监听，让 ConnectionId(2) 建一个监听。然后调用 connection_closed(ConnectionId(1))。最后检查内部登记表只剩 ConnectionId(2) 的那条，并顺便确认第一次 watch 返回的路径没变。

调用关系：它通过多次 FsWatchManager::watch 准备状态，再调用 FsWatchManager::connection_closed 执行批量清理。这个测试覆盖连接关闭时的收尾流程，确保多客户端同时使用时不会互相影响。

调用图：外部调用 6 个（new, new, absolute_path, manager_with_noop_watcher, assert_eq!, write）。

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

作用：创建一个文件请求处理器，把“怎么找到文件系统”和“怎么管理文件监听”这两样工具装进去。后面所有文件请求都靠这个对象来转发和协调。

数据流：进去的是一个 EnvironmentManager（环境管理器，用来找到当前可用的本地文件系统）和一个 FsWatchManager（文件变化监听管理器）→ 函数把它们保存到 FsRequestProcessor 里 → 出来的是一个可以处理文件相关请求的新对象，不会立刻读写任何文件。

调用关系：它通常在上层初始化处理器时被调用，作为文件请求这条通道的组装步骤。之后 handle_initialized_client_request 这类请求分发逻辑会通过这个对象调用读写、删除、监听等具体方法。

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

fn file_system(&self) -> Result<Arc<dyn ExecutorFileSystem>, JSONRPCErrorError>

作用：取出当前可用的本地文件系统。它像开工前先确认“工具箱在不在”，没有文件系统就马上返回错误。

数据流：进去的是处理器自己保存的 EnvironmentManager → 它尝试取得本地环境，再从环境里拿文件系统对象 → 成功时出来一个可共享的文件系统接口，失败时出来一个 JSON-RPC 内部错误，说明本地文件系统没有配置。

调用关系：几乎所有真正碰文件的方法都会先调用它，比如读文件、写文件、建目录、删文件、复制、监听和取消监听。它把“有没有本地文件系统”这个检查集中到一处，避免每个方法各写一遍。

调用图：被 9 处调用（copy, create_directory, get_metadata, read_directory, read_file, remove, unwatch, watch, write_file）。

async fn connection_closed(&self, connection_id: ConnectionId)

作用：当某个客户端连接断开时，通知文件监听管理器清理这个连接留下的监听任务。否则就像人已经走了，系统还一直替他盯着文件，浪费资源。

数据流：进去的是断开的 ConnectionId（连接编号）→ 函数把这个编号交给 FsWatchManager → 出来没有业务数据，但监听管理器会把这个连接相关的监听记录清掉。

调用关系：它在连接关闭流程里被上层调用，自己把清理工作交给 fs_watch_manager.connection_closed。它不处理普通文件读写，只负责断线后的收尾。

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

async fn read_file(
        &self,
        params: FsReadFileParams,
    ) -> Result<FsReadFileResponse, JSONRPCErrorError>

作用：读取客户端指定的文件，并把文件内容用 base64 文本返回。这样即使文件里是图片、压缩包这类二进制内容，也能安全塞进 JSON 响应。

数据流：进去的是 FsReadFileParams，里面有文件路径 → 它把路径转成 PathUri，拿到文件系统，异步读取文件字节，并把底层错误交给 map_fs_error 翻译 → 出来的是 FsReadFileResponse，里面的 data_base64 是文件内容的 base64 字符串。

调用关系：客户端发起读文件请求后，handle_initialized_client_request 会调用它。它先调用 file_system 确认有文件系统，再用 from_abs_path 规范化路径，最后交给底层文件系统读取。

调用图：调用 2 个内部函数（file_system, from_abs_path）；被 1 处调用（handle_initialized_client_request）。

async fn write_file(
        &self,
        params: FsWriteFileParams,
    ) -> Result<FsWriteFileResponse, JSONRPCErrorError>

作用：把客户端传来的 base64 文件内容写到指定路径。它先检查内容是不是合法 base64，避免把乱码当成文件写进去。

数据流：进去的是 FsWriteFileParams，包含路径和 data_base64 → 它先把 base64 解成原始字节，解码失败就返回“请求无效”；然后把路径转成 PathUri，拿到文件系统并写入字节 → 成功时出来一个空的 FsWriteFileResponse，表示写完了；失败时返回整理过的错误。

调用关系：客户端发起写文件请求时由 handle_initialized_client_request 调用。它自己负责 base64 解码和路径转换，再通过 file_system 找到底层文件系统执行写入。

调用图：调用 2 个内部函数（file_system, from_abs_path）；被 1 处调用（handle_initialized_client_request）。

async fn create_directory(
        &self,
        params: FsCreateDirectoryParams,
    ) -> Result<FsCreateDirectoryResponse, JSONRPCErrorError>

作用：创建客户端指定的目录。默认会递归创建，也就是父目录不存在时一起建好，像执行“mkdir -p”。

数据流：进去的是 FsCreateDirectoryParams，包含路径和可选的 recursive 选项 → 它把路径转成 PathUri，拿到文件系统，并构造 CreateDirectoryOptions；如果客户端没说 recursive，就默认 true → 成功时出来空响应，失败时返回翻译后的错误。

调用关系：目录创建请求由 handle_initialized_client_request 分发到这里。它先用 file_system 拿执行工具，再把实际创建工作交给底层文件系统。

调用图：调用 2 个内部函数（file_system, from_abs_path）；被 1 处调用（handle_initialized_client_request）。

async fn get_metadata(
        &self,
        params: FsGetMetadataParams,
    ) -> Result<FsGetMetadataResponse, JSONRPCErrorError>

作用：查询一个路径的基本信息，比如它是不是文件、是不是目录、是不是符号链接，以及创建和修改时间。它不会读取文件内容，只看“身份证信息”。

数据流：进去的是 FsGetMetadataParams，主要是路径 → 它把路径转成 PathUri，拿文件系统查询元数据 → 出来的是 FsGetMetadataResponse，包含 is_directory、is_file、is_symlink、created_at_ms、modified_at_ms 等字段。

调用关系：客户端想知道某个路径是什么类型时，handle_initialized_client_request 会调用它。它依赖 file_system 和 from_abs_path 做准备，然后把查询交给底层文件系统。

调用图：调用 2 个内部函数（file_system, from_abs_path）；被 1 处调用（handle_initialized_client_request）。

async fn read_directory(
        &self,
        params: FsReadDirectoryParams,
    ) -> Result<FsReadDirectoryResponse, JSONRPCErrorError>

作用：列出一个目录里的条目，并告诉客户端每个条目叫什么、是文件还是目录。它相当于给客户端做一次“打开文件夹看看里面有什么”。

数据流：进去的是 FsReadDirectoryParams，包含目录路径 → 它把路径转成 PathUri，拿文件系统读取目录列表 → 再把底层条目转换成协议里的 FsReadDirectoryEntry → 出来的是 FsReadDirectoryResponse，里面有 entries 列表。

调用关系：目录读取请求由 handle_initialized_client_request 交给它。它负责把底层文件系统返回的目录项改成客户端协议需要的形状。

调用图：调用 2 个内部函数（file_system, from_abs_path）；被 1 处调用（handle_initialized_client_request）。

async fn remove(
        &self,
        params: FsRemoveParams,
    ) -> Result<FsRemoveResponse, JSONRPCErrorError>

作用：删除指定文件或目录。默认 recursive 和 force 都是 true，意思是目录可以连里面一起删，目标不存在或类似情况也尽量不让操作失败。

数据流：进去的是 FsRemoveParams，包含路径，以及可选的 recursive、force → 它把路径转成 PathUri，拿文件系统，并用默认值补齐删除选项 → 成功时出来空的 FsRemoveResponse；如果底层删除失败，就返回经过 map_fs_error 转换的错误。

调用关系：删除请求由 handle_initialized_client_request 调用这里。它不自己删除文件，而是整理好 RemoveOptions 后交给底层文件系统执行。

调用图：调用 2 个内部函数（file_system, from_abs_path）；被 1 处调用（handle_initialized_client_request）。

async fn copy(
        &self,
        params: FsCopyParams,
    ) -> Result<FsCopyResponse, JSONRPCErrorError>

作用：把一个文件或目录从源路径复制到目标路径。是否递归复制由请求里的 recursive 选项决定。

数据流：进去的是 FsCopyParams，包含 source_path、destination_path 和 recursive → 它分别把源路径和目标路径转成 PathUri，拿到文件系统，再构造 CopyOptions → 成功时出来空的 FsCopyResponse，失败时返回整理后的错误。

调用关系：复制请求由 handle_initialized_client_request 分发到它。它负责把协议参数变成底层文件系统能理解的参数，然后调用文件系统的复制能力。

调用图：调用 2 个内部函数（file_system, from_abs_path）；被 1 处调用（handle_initialized_client_request）。

async fn watch(
        &self,
        connection_id: ConnectionId,
        params: FsWatchParams,
    ) -> Result<FsWatchResponse, JSONRPCErrorError>

作用：让某个客户端连接开始监听文件或目录变化。它先确认本地文件系统存在，再把真正的监听登记交给 FsWatchManager。

数据流：进去的是 ConnectionId 和 FsWatchParams → 它先调用 file_system 做可用性检查；检查通过后，把连接编号和监听参数交给 fs_watch_manager.watch → 出来的是 FsWatchResponse，表示监听登记结果，或者返回错误。

调用关系：客户端请求开始监听时，handle_initialized_client_request 会调用它。它自己不实现监听细节，而是像前台登记员一样确认条件后，把活交给 FsWatchManager。

调用图：调用 2 个内部函数（watch, file_system）；被 1 处调用（handle_initialized_client_request）。

async fn unwatch(
        &self,
        connection_id: ConnectionId,
        params: FsUnwatchParams,
    ) -> Result<FsUnwatchResponse, JSONRPCErrorError>

作用：取消某个客户端连接之前登记的文件监听。它确保文件系统环境可用后，让 FsWatchManager 删除对应的监听记录。

数据流：进去的是 ConnectionId 和 FsUnwatchParams → 它先调用 file_system 检查环境，再把连接编号和取消监听参数交给 fs_watch_manager.unwatch → 出来的是 FsUnwatchResponse，表示取消完成或失败。

调用关系：客户端请求停止监听时由 handle_initialized_client_request 调用。它负责入口检查，真正的监听状态修改由 FsWatchManager 完成。

调用图：调用 2 个内部函数（unwatch, file_system）；被 1 处调用（handle_initialized_client_request）。

fn map_fs_error(err: io::Error) -> JSONRPCErrorError

作用：把底层文件系统抛出的 io::Error 翻译成 JSON-RPC 错误。这样客户端不用面对 Rust 或操作系统风格的杂乱错误，而是收到统一格式的错误。

数据流：进去的是一个 io::Error → 它查看错误类型：如果是 InvalidInput，说明请求参数本身不合适，就转成 invalid_request；其他情况通常算服务器内部问题，就转成 internal_error → 出来的是 JSONRPCErrorError，错误文字来自原始错误的 to_string。

调用关系：读、写、建目录、查元数据、读目录、删除、复制等方法在底层文件系统失败时都会用它收口。它调用 invalid_request 或 internal_error，把技术性错误变成协议层能返回给客户端的错误。

调用图：调用 2 个内部函数（internal_error, invalid_request）；外部调用 2 个（kind, to_string）。