结果持久化、展示与状态更新

async fn apply_bespoke_event_handling(
    event: Event,
    conversation_id: ThreadId,
    conversation: Arc<CodexThread>,
    thread_manager: Arc<ThreadManager>,
    outgoing: ThreadScopedOutgoingMe

作用：这是本文件的总入口。每当核心引擎发来一个事件，它就判断事件类型，然后发通知、发审批请求、更新线程状态，或把客户端回答再送回核心。

数据流：进去的是一个核心事件、线程编号、核心线程对象、发送器和线程状态等信息 → 它按事件种类拆开处理，比如 TurnStarted 变成 TurnStarted 通知，ExecApprovalRequest 变成命令审批请求，Error 变成错误通知 → 出来的是发给客户端的消息、提交给核心的操作，以及被更新的线程状态。

调用关系：它是整条事件处理链的调度中心。测试里的 apply_guardian_assessment_event、interrupted_subagent_activity_removes_missing_thread_watch、turn_started_omits_active_snapshot_items 会直接调用它；它再把具体小活交给 complete_command_execution_item、handle_error_notification、handle_turn_complete、handle_token_count_event 等辅助函数。

调用图：调用 38 个内部函数（complete_command_execution_item, handle_error_notification, handle_thread_rollback_failed, handle_token_count_event, handle_turn_complete, handle_turn_diff, handle_turn_interrupted, handle_turn_plan_update, maybe_emit_hook_prompt_item_completed, maybe_emit_raw_response_item_completed (+15 more)）；被 3 处调用（apply_guardian_assessment_event, interrupted_subagent_activity_removes_missing_thread_watch, turn_started_omits_active_snapshot_items）；外部调用 46 个（DeprecationNotice, Error, GuardianWarning, HookCompleted, HookStarted, ItemCompleted, ItemStarted, McpServerStatusUpdated, ModelRerouted, ModelVerification (+15 more)）。

async fn handle_turn_diff(
    conversation_id: ThreadId,
    event_turn_id: &str,
    turn_diff_event: TurnDiffEvent,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

作用：把一轮对话里产生的代码差异内容发给客户端。这样前端能及时展示“这轮改了哪些文件”。

数据流：进去的是线程编号、轮次编号和一段统一 diff 文本 → 它包装成 TurnDiffUpdated 通知 → 发给当前线程的客户端。

调用关系：apply_bespoke_event_handling 遇到 TurnDiff 事件时会调用它；测试 test_handle_turn_diff_emits_v2_notification 单独检查它发出的通知格式。

调用图：调用 1 个内部函数（send_server_notification）；被 2 处调用（apply_bespoke_event_handling, test_handle_turn_diff_emits_v2_notification）；外部调用 2 个（TurnDiffUpdated, to_string）。

async fn handle_turn_plan_update(
    conversation_id: ThreadId,
    event_turn_id: &str,
    plan_update_event: UpdatePlanArgs,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

作用：把模型更新的待办计划发给客户端。这里的计划是清单式步骤，不是“计划模式”的内部状态。

数据流：进去的是线程编号、轮次编号和计划内容 → 它把核心里的步骤转换成客户端协议里的 TurnPlanStep → 发出 TurnPlanUpdated 通知。

调用关系：apply_bespoke_event_handling 收到 PlanUpdate 时会交给它；测试 test_handle_turn_plan_update_emits_notification_for_v2 验证前端能收到正确计划。

调用图：调用 1 个内部函数（send_server_notification）；被 2 处调用（apply_bespoke_event_handling, test_handle_turn_plan_update_emits_notification_for_v2）；外部调用 2 个（TurnPlanUpdated, to_string）。

async fn emit_turn_completed_with_status(
    conversation_id: ThreadId,
    event_turn_id: String,
    turn_completion_metadata: TurnCompletionMetadata,
    outgoing: &ThreadScopedOutgoingMessageSend

作用：统一发送“一轮对话结束了”的通知。调用者只要告诉它结束状态、错误和时间，它负责拼出客户端需要的完整消息。

数据流：进去的是线程编号、轮次编号和结束元信息 → 它创建一个不加载明细条目的 Turn 对象 → 发出 TurnCompleted 通知。

调用关系：handle_turn_complete 和 handle_turn_interrupted 都用它，避免完成和中断两条路各自手写一套通知格式。

调用图：调用 1 个内部函数（send_server_notification）；被 2 处调用（handle_turn_complete, handle_turn_interrupted）；外部调用 3 个（TurnCompleted, to_string, vec!）。

async fn start_command_execution_item(
    conversation_id: &ThreadId,
    turn_id: String,
    item_id: String,
    command: String,
    cwd: AbsolutePathBuf,
    command_actions: Vec<V2ParsedCommand

作用：通知客户端“有个命令开始执行或等待审批了”。它还会防重复，保证同一个命令的开始消息只发一次。

数据流：进去的是线程、轮次、命令编号、命令文本、工作目录、命令解析结果和发送器 → 它先把命令编号记到线程状态里；如果之前没记过，就发 ItemStarted 通知 → 返回 true 表示真的发了，false 表示这是重复开始。

调用关系：apply_bespoke_event_handling 在命令审批或 Guardian 审查开始时会用它；complete_command_execution_item 之后靠同一份状态判断是否该发结束通知；相关测试确认它不会重复发。

调用图：调用 2 个内部函数（now_unix_timestamp_ms, send_server_notification）；被 3 处调用（apply_bespoke_event_handling, command_execution_started_helper_emits_once, complete_command_execution_item_emits_declined_once_for_pending_command）；外部调用 2 个（ItemStarted, to_string）。

async fn complete_command_execution_item(
    conversation_id: &ThreadId,
    turn_id: String,
    item_id: String,
    command: String,
    cwd: AbsolutePathBuf,
    process_id: Option<String>,
    s

作用：通知客户端“这个命令项结束了”，常用于命令被拒绝、失败或取消时收尾。它同样会防重复。

数据流：进去的是命令编号、命令信息、结束状态等 → 它先从线程状态里移除这个正在进行的命令；只有确实存在时才继续 → 发 ItemCompleted 通知。

调用关系：apply_bespoke_event_handling 和 on_command_execution_request_approval_response 会在审批拒绝或安全审查失败时调用它；测试确认同一个命令只完成一次。

调用图：调用 2 个内部函数（now_unix_timestamp_ms, send_server_notification）；被 3 处调用（apply_bespoke_event_handling, on_command_execution_request_approval_response, complete_command_execution_item_emits_declined_once_for_pending_command）；外部调用 2 个（ItemCompleted, to_string）。

async fn maybe_emit_raw_response_item_completed(
    conversation_id: ThreadId,
    turn_id: &str,
    item: codex_protocol::models::ResponseItem,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

作用：把模型原始响应条目原样转发给客户端。名字里有 maybe，但当前实现总是会发。

数据流：进去的是线程编号、轮次编号和一个原始响应条目 → 它包装成 RawResponseItemCompleted 通知 → 发给客户端。

调用关系：apply_bespoke_event_handling 收到 RawResponseItem 时会调用它；同一路径还会先尝试 maybe_emit_hook_prompt_item_completed。

调用图：调用 1 个内部函数（send_server_notification）；被 1 处调用（apply_bespoke_event_handling）；外部调用 2 个（RawResponseItemCompleted, to_string）。

async fn maybe_emit_hook_prompt_item_completed(
    conversation_id: ThreadId,
    turn_id: &str,
    item: &codex_protocol::models::ResponseItem,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

作用：识别一种特殊的“hook 提示消息”，并把它显示成客户端的 HookPrompt 条目。hook 可以理解成某些自动化步骤插入的提示。

数据流：进去的是一个原始响应条目 → 它只接受角色为 user 的消息，再尝试解析里面是否是 hook prompt → 如果是，就转成 HookPrompt 并发 ItemCompleted；如果不是就什么也不做。

调用关系：apply_bespoke_event_handling 处理 RawResponseItem 时先调用它；测试 test_hook_prompt_raw_response_emits_item_completed 验证能从原始消息里识别 hook 提示。

调用图：调用 3 个内部函数（now_unix_timestamp_ms, send_server_notification, parse_hook_prompt_message）；被 2 处调用（apply_bespoke_event_handling, test_hook_prompt_raw_response_emits_item_completed）；外部调用 2 个（ItemCompleted, to_string）。

async fn find_and_remove_turn_summary(
    _conversation_id: ThreadId,
    thread_state: &Arc<Mutex<ThreadState>>,
) -> TurnSummary

作用：取出并清空当前轮的摘要状态。摘要里记录了本轮开始时间、最后错误、已开始的命令等临时信息。

数据流：进去的是线程状态 → 它加锁取走 turn_summary，并把原位置恢复成空的默认摘要 → 返回刚才取出的摘要。

调用关系：handle_turn_complete 和 handle_turn_interrupted 在一轮结束时调用它，表示这轮的临时账本结清；测试 test_handle_error_records_message 也用它检查错误是否被记住。

调用图：被 3 处调用（handle_turn_complete, handle_turn_interrupted, test_handle_error_records_message）；外部调用 1 个（take）。

async fn handle_turn_complete(
    conversation_id: ThreadId,
    event_turn_id: String,
    turn_complete_event: TurnCompleteEvent,
    outgoing: &ThreadScopedOutgoingMessageSender,
    thread_state:

作用：处理正常结束的一轮对话。它会判断这一轮是否曾记录过错误，从而决定最终状态是 Completed 还是 Failed。

数据流：进去的是线程编号、轮次编号、核心的完成事件和线程状态 → 它取出本轮摘要，看 last_error 是否存在 → 发出带完成时间、耗时和状态的 TurnCompleted 通知。

调用关系：apply_bespoke_event_handling 收到 TurnComplete 时调用它；它依赖 find_and_remove_turn_summary 和 emit_turn_completed_with_status；多个测试验证无错、有错、多轮情况下的结果。

调用图：调用 2 个内部函数（emit_turn_completed_with_status, find_and_remove_turn_summary）；被 4 处调用（apply_bespoke_event_handling, test_handle_turn_complete_emits_completed_without_error, test_handle_turn_complete_emits_error_multiple_turns, test_handle_turn_complete_emits_failed_with_error）。

async fn handle_turn_interrupted(
    conversation_id: ThreadId,
    event_turn_id: String,
    turn_aborted_event: TurnAbortedEvent,
    outgoing: &ThreadScopedOutgoingMessageSender,
    thread_state

作用：处理被用户或系统打断的一轮对话。它把这一轮标成 Interrupted，而不是成功或失败。

数据流：进去的是线程编号、轮次编号、中断事件和线程状态 → 它取出并清空本轮摘要 → 发出状态为 Interrupted 的 TurnCompleted 通知，错误字段为空。

调用关系：apply_bespoke_event_handling 收到 TurnAborted 时调用它；它和 handle_turn_complete 共用 find_and_remove_turn_summary、emit_turn_completed_with_status。

调用图：调用 2 个内部函数（emit_turn_completed_with_status, find_and_remove_turn_summary）；被 2 处调用（apply_bespoke_event_handling, test_handle_turn_interrupted_emits_interrupted_with_error）。

async fn handle_thread_rollback_failed(
    _conversation_id: ThreadId,
    message: String,
    thread_state: &Arc<Mutex<ThreadState>>,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

作用：处理线程回滚失败。回滚就是把对话恢复到旧状态；失败时要回复正在等待的回滚请求，避免客户端一直等。

数据流：进去的是错误消息、线程状态和发送器 → 它取出 pending_rollbacks 里等待回复的请求编号 → 如果有，就用 invalid_request 错误回复客户端。

调用关系：apply_bespoke_event_handling 收到特定 ThreadRollbackFailed 错误时调用它，并且不会再额外发普通错误通知。

调用图：调用 2 个内部函数（invalid_request, send_error）；被 1 处调用（apply_bespoke_event_handling）。

fn thread_rollback_response_from_stored_thread(
    stored_thread: codex_thread_store::StoredThread,
    session_id: String,
    fallback_model_provider: &str,
    fallback_cwd: &AbsolutePathBuf,

作用：把磁盘里读出的旧线程记录重新拼成客户端需要的回滚响应。它解决“回滚后前端要重新拿到完整线程视图”的问题。

数据流：进去的是存储线程、会话编号、兜底模型提供方、兜底工作目录和加载状态 → 它先转成客户端线程对象，再用历史记录填充轮次和条目 → 成功时返回 ThreadRollbackResponse，缺少历史时返回错误文字。

调用关系：apply_bespoke_event_handling 在收到 ThreadRolledBack 后用它生成请求回复；测试 rollback_response_rebuilds_pathless_thread_from_stored_history 验证路径缺失时也能从历史恢复。

调用图：被 2 处调用（apply_bespoke_event_handling, rollback_response_rebuilds_pathless_thread_from_stored_history）；外部调用 3 个（populate_thread_turns_from_history, thread_from_stored_thread, format!）。

async fn respond_to_pending_interrupts(
    thread_state: &Arc<Mutex<ThreadState>>,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

作用：回复所有还在等待的“打断请求”。当一轮已经完成或中断时，打断请求就应该收尾。

数据流：进去的是线程状态和发送器 → 它取出并清空 pending_interrupts 列表 → 对每个请求编号发送 TurnInterruptResponse。

调用关系：apply_bespoke_event_handling 在 TurnComplete 和 TurnAborted 时调用它，确保客户端发出的 interrupt 不会悬空。

调用图：调用 1 个内部函数（send_response）；被 1 处调用（apply_bespoke_event_handling）；外部调用 1 个（take）。

async fn handle_token_count_event(
    conversation_id: ThreadId,
    turn_id: String,
    token_count_event: TokenCountEvent,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

作用：把 token 用量和账号限流信息通知客户端。token 可以理解成模型计费和上下文长度使用的基本单位。

数据流：进去的是线程编号、轮次编号和 TokenCountEvent → 如果有用量信息，就发 ThreadTokenUsageUpdated；如果有限流信息，就发 AccountRateLimitsUpdated → 没有对应信息就不发。

调用关系：apply_bespoke_event_handling 收到 TokenCount 时调用它；测试覆盖有用量、有额度信息和完全没有信息两种情况。

调用图：调用 1 个内部函数（send_server_notification）；被 3 处调用（apply_bespoke_event_handling, test_handle_token_count_event_emits_usage_and_rate_limits, test_handle_token_count_event_without_usage_info）；外部调用 3 个（AccountRateLimitsUpdated, ThreadTokenUsageUpdated, to_string）。

async fn handle_error(
    _conversation_id: ThreadId,
    error: TurnError,
    thread_state: &Arc<Mutex<ThreadState>>,
)

作用：把本轮发生的错误记到账本里。它本身不通知客户端，只负责保存状态，供轮次结束时判断失败。

数据流：进去的是错误和线程状态 → 它加锁修改 turn_summary.last_error → 没有返回值，只改变内存里的线程摘要。

调用关系：handle_error_notification 会先调用它再发错误通知；多个测试直接调用它来模拟一轮中出现过错误。

调用图：被 5 处调用（handle_error_notification, test_handle_error_records_message, test_handle_turn_complete_emits_error_multiple_turns, test_handle_turn_complete_emits_failed_with_error, test_handle_turn_interrupted_emits_interrupted_with_error）。

async fn handle_error_notification(
    conversation_id: ThreadId,
    event_turn_id: &str,
    error: TurnError,
    outgoing: &ThreadScopedOutgoingMessageSender,
    thread_state: &Arc<Mutex<ThreadS

作用：记录错误并马上通知客户端。适合那些会影响本轮最终状态的错误。

数据流：进去的是线程编号、轮次编号、错误内容、发送器和线程状态 → 它先调用 handle_error 保存错误 → 再发 Error 通知，will_retry 标成 false。

调用关系：apply_bespoke_event_handling 处理普通 Error 时调用它；on_request_permissions_response 遇到权限路径转换失败时也用它报告问题。

调用图：调用 2 个内部函数（handle_error, send_server_notification）；被 2 处调用（apply_bespoke_event_handling, on_request_permissions_response）；外部调用 3 个（Error, clone, to_string）。

async fn on_request_user_input_response(
    event_turn_id: String,
    pending_request_id: RequestId,
    receiver: oneshot::Receiver<ClientRequestResult>,
    conversation: Arc<CodexThread>,
    thr

作用：等待客户端回答工具提出的问题，然后把答案交回核心引擎。比如工具问用户“请选择哪个选项”。

数据流：进去的是轮次编号、请求编号、一次性接收器、核心线程、线程状态和活动标记 → 它等待客户端结果，清理挂起请求；失败时提交空答案，成功时把 JSON 转成核心能懂的答案 → 最后提交 Op::UserInputAnswer。

调用关系：apply_bespoke_event_handling 发出 ToolRequestUserInput 请求后会启动异步任务调用它；它把客户端的回答接回核心线程。

调用图：调用 2 个内部函数（is_turn_transition_server_request_error, resolve_server_request_on_thread_listener）；被 1 处调用（apply_bespoke_event_handling）；外部调用 2 个（new, error!）。

async fn on_mcp_server_elicitation_response(
    server_name: String,
    request_id: codex_protocol::mcp::RequestId,
    pending_request_id: RequestId,
    receiver: oneshot::Receiver<ClientRequestRe

作用：等待客户端回答 MCP 服务器的询问，并把选择交回核心。MCP 是外部工具/服务接入协议，这里的 elicitation 是服务向用户索要信息。

数据流：进去的是服务器名、MCP 请求编号、app-server 请求编号、接收器、核心线程和线程状态 → 它等客户端回复，清理挂起状态，再把结果转成核心动作 → 提交 Op::ResolveElicitation。

调用关系：apply_bespoke_event_handling 发送 McpServerElicitationRequest 后启动它；它依赖 mcp_server_elicitation_response_from_client_result 做容错转换。

调用图：调用 2 个内部函数（mcp_server_elicitation_response_from_client_result, resolve_server_request_on_thread_listener）；被 1 处调用（apply_bespoke_event_handling）；外部调用 1 个（error!）。

fn mcp_server_elicitation_response_from_client_result(
    response: std::result::Result<ClientRequestResult, oneshot::error::RecvError>,
) -> McpServerElicitationRequestResponse

作用：把客户端对 MCP 询问的回复变成一个安全的默认结果。即使客户端断线或回错格式，也不会让流程崩掉。

数据流：进去的是一次性通道收到的结果或错误 → 成功时解析成 McpServerElicitationRequestResponse；轮次切换错误转成 Cancel；其他失败转成 Decline → 返回一个明确动作。

调用关系：on_mcp_server_elicitation_response 调用它；测试 mcp_server_elicitation_turn_transition_error_maps_to_cancel 验证轮次切换时会取消而不是拒绝。

调用图：调用 1 个内部函数（is_turn_transition_server_request_error）；被 2 处调用（on_mcp_server_elicitation_response, mcp_server_elicitation_turn_transition_error_maps_to_cancel）；外部调用 1 个（error!）。

async fn on_request_permissions_response(
    pending_response: PendingRequestPermissionsResponse,
    conversation: Arc<CodexThread>,
    thread_state: Arc<Mutex<ThreadState>>,
)

作用：等待客户端对权限申请的审批，并把最终允许的权限交给核心。权限包括文件读写、网络访问等。

数据流：进去的是一包挂起权限请求信息、核心线程和线程状态 → 它等待客户端回复，清理挂起请求，转换并裁剪权限；路径转换失败会发错误并打断当前轮 → 成功时记录审批结果并提交 Op::RequestPermissionsResponse。

调用关系：apply_bespoke_event_handling 处理 RequestPermissions 后启动它；它主要依赖 request_permissions_response_from_client_result 做权限转换，必要时调用 handle_error_notification。

调用图：调用 3 个内部函数（handle_error_notification, request_permissions_response_from_client_result, resolve_server_request_on_thread_listener）；被 1 处调用（apply_bespoke_event_handling）；外部调用 2 个（error!, format!）。

fn request_permissions_response_from_client_result(
    requested_permissions: CoreRequestPermissionProfile,
    response: std::result::Result<ClientRequestResult, oneshot::error::RecvError>,
    cwd:

作用：把客户端批准的权限转成核心真正可执行的权限，并且不会允许超出原申请范围。它是权限安全边界之一。

数据流：进去的是核心原本申请的权限、客户端回复结果和当时的工作目录 → 它处理断线、格式错误和轮次切换；成功时解析客户端授予的权限，并与原申请求交集 → 返回核心权限响应，或在轮次切换时返回 None。

调用关系：on_request_permissions_response 调用它；大量测试覆盖部分授权、会话级授权、严格自动审查、路径越界和更宽权限被拒绝等情况。

调用图：调用 2 个内部函数（is_turn_transition_server_request_error, intersect_permission_profiles）；被 9 处调用（on_request_permissions_response, request_permissions_response_accepts_explicit_child_grant_for_requested_cwd_scope, request_permissions_response_accepts_partial_network_and_file_system_grants, request_permissions_response_ignores_broader_cwd_grant_for_requested_child_path, request_permissions_response_preserves_session_scope, request_permissions_response_preserves_turn_scoped_strict_auto_review, request_permissions_response_rejects_child_grant_outside_requested_cwd_scope, request_permissions_response_rejects_session_scoped_strict_auto_review, request_permissions_turn_transition_error_is_ignored）；外部调用 5 个（default, into, default, error!, matches!）。

fn render_review_output_text(output: &ReviewOutputEvent) -> String

作用：把代码审查结果整理成一段适合显示给用户的文字。没有有效内容时给出兜底提示。

数据流：进去的是审查输出，里面可能有总体说明和问题列表 → 它去掉空白，把说明和格式化后的问题块拼在一起 → 返回最终显示文本；如果都为空，返回固定失败提示。

调用关系：apply_bespoke_event_handling 在 ExitedReviewMode 时调用它，把 ReviewOutputEvent 转成 ThreadItem::ExitedReviewMode 的文字。

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

fn map_file_change_approval_decision(decision: FileChangeApprovalDecision) -> ReviewDecision

作用：把客户端对文件改动的选择翻译成核心审查决定。两个系统使用的枚举名字不同，需要这层转换。

数据流：进去的是 FileChangeApprovalDecision，比如接受、整会话接受、拒绝、取消 → 它逐项映射成 ReviewDecision → 返回给调用者。

调用关系：on_file_change_request_approval_response 用它处理客户端审批结果；测试 file_change_accept_for_session_maps_to_approved_for_session 检查关键映射。

调用图：被 2 处调用（on_file_change_request_approval_response, file_change_accept_for_session_maps_to_approved_for_session）。

async fn on_file_change_request_approval_response(
    item_id: String,
    pending_request_id: RequestId,
    receiver: oneshot::Receiver<ClientRequestResult>,
    codex: Arc<CodexThread>,
    thread

作用：等待客户端批准或拒绝文件改动，然后把决定告诉核心。比如模型想 apply patch 改文件时会走这里。

数据流：进去的是条目编号、请求编号、接收器、核心线程、线程状态和权限活动标记 → 它等待客户端回复，清理挂起请求；成功时解析决定，失败时默认拒绝 → 提交 Op::PatchApproval。

调用关系：apply_bespoke_event_handling 处理 ApplyPatchApprovalRequest 后启动它；它使用 map_file_change_approval_decision 完成协议转换。

调用图：调用 3 个内部函数（map_file_change_approval_decision, is_turn_transition_server_request_error, resolve_server_request_on_thread_listener）；被 1 处调用（apply_bespoke_event_handling）；外部调用 1 个（error!）。

async fn on_command_execution_request_approval_response(
    event_turn_id: String,
    conversation_id: ThreadId,
    approval_id: Option<String>,
    item_id: String,
    completion_item: Option<Com

作用：等待客户端批准或拒绝命令执行，并把决定交回核心。它还负责在命令被拒绝时给前端补一个“命令结束”的显示。

数据流：进去的是轮次、线程、审批编号、命令条目信息、请求编号、接收器、核心线程、发送器和状态 → 它等待回复，清理挂起请求；把客户端决定转成 ReviewDecision；必要时调用 complete_command_execution_item 收尾 → 最后提交 Op::ExecApproval。

调用关系：apply_bespoke_event_handling 在 ExecApprovalRequest 后启动它；它和 start_command_execution_item/complete_command_execution_item 配合，保证命令审批的显示生命周期完整。

调用图：调用 3 个内部函数（complete_command_execution_item, is_turn_transition_server_request_error, resolve_server_request_on_thread_listener）；被 1 处调用（apply_bespoke_event_handling）；外部调用 1 个（error!）。

fn now_unix_timestamp_ms() -> i64

作用：取当前 Unix 时间戳，单位是毫秒。Unix 时间戳就是从 1970 年 1 月 1 日到现在经过的时间。

数据流：进去没有业务输入 → 它读取系统时间，换算成毫秒整数；如果系统时间异常就返回 0 → 输出 i64 时间戳。

调用关系：apply_bespoke_event_handling、start_command_execution_item、complete_command_execution_item、maybe_emit_hook_prompt_item_completed 用它给通知打时间。

调用图：被 4 处调用（apply_bespoke_event_handling, complete_command_execution_item, maybe_emit_hook_prompt_item_completed, start_command_execution_item）；外部调用 1 个（now）。

fn new_thread_state() -> Arc<Mutex<ThreadState>>

作用：给测试创建一份新的线程状态。这样每个测试都有干净的临时账本。

数据流：进去没有输入 → 它创建默认 ThreadState，包进异步互斥锁，再包进 Arc 共享指针 → 返回可在异步测试里共享的状态。

调用关系：许多测试都用它准备环境，比如命令开始/结束、错误记录、轮次完成等测试。

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

async fn recv_broadcast_message(
        rx: &mut mpsc::Receiver<OutgoingEnvelope>,
    ) -> Result<OutgoingMessage>

作用：测试里从消息通道收一条发出的消息，并统一拆开外壳。它让断言更简单。

数据流：进去的是一个异步接收端 → 它等待下一条 OutgoingEnvelope；无消息就报错 → 返回里面真正的 OutgoingMessage。

调用关系：大量通知类测试调用它读取被测函数发出的消息，然后检查消息内容是否正确。

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

fn rollback_response_rebuilds_pathless_thread_from_stored_history() -> Result<()>

作用：测试回滚响应能从存储历史里重建线程，即使线程本身没有 rollout 路径。这样回滚后客户端仍能看到对话内容。

数据流：进去没有外部输入 → 它构造一个带历史的 StoredThread，调用 thread_rollback_response_from_stored_thread → 断言返回线程的编号、状态、预览和条目数量都正确。

调用关系：它直接覆盖 thread_rollback_response_from_stored_thread 的关键场景。

调用图：调用 3 个内部函数（thread_rollback_response_from_stored_thread, read_only, from_string）；外部调用 4 个（now, assert_eq!, test_path_buf, vec!）。

fn turn_complete_event(turn_id: &str) -> TurnCompleteEvent

作用：测试辅助函数，快速造一个固定时间和耗时的 TurnCompleteEvent。

数据流：进去的是轮次编号字符串 → 它填入固定 completed_at 和 duration_ms → 返回核心完成事件。

调用关系：多个轮次完成相关测试用它，避免每个测试重复写同样的事件字段。

fn turn_aborted_event(turn_id: &str) -> TurnAbortedEvent

作用：测试辅助函数，快速造一个固定时间和耗时的 TurnAbortedEvent。

数据流：进去的是轮次编号字符串 → 它填入中断原因、完成时间和耗时 → 返回核心中断事件。

调用关系：test_handle_turn_interrupted_emits_interrupted_with_error 用它模拟一轮被打断。

fn command_execution_completion_item(command: &str) -> CommandExecutionCompletionItem

作用：测试辅助函数，创建一个命令执行显示项需要的基本资料。

数据流：进去的是命令文本 → 它设置测试工作目录和一个 Unknown 命令动作 → 返回 CommandExecutionCompletionItem。

调用关系：命令开始和命令完成相关测试用它准备输入。

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

fn guardian_command_assessment(
        id: &str,
        turn_id: &str,
        status: GuardianAssessmentStatus,
    ) -> GuardianAssessmentEvent

作用：测试辅助函数，构造 Guardian 安全审查事件。Guardian 可以理解成自动安全检查员。

数据流：进去的是目标命令编号、轮次编号和审查状态 → 它按状态填风险、授权、理由和命令动作 → 返回 GuardianAssessmentEvent。

调用关系：guardian_command_execution_notifications_wrap_review_lifecycle 用它模拟安全审查从进行中到批准或拒绝的过程。

调用图：外部调用 4 个（format!, json!, matches!, from_value）。

async fn apply_guardian_assessment_event(&self, assessment: GuardianAssessmentEvent)

作用：测试上下文里的便捷方法，用来把一个 Guardian 审查事件送进真实事件处理入口。

数据流：进去的是 GuardianAssessmentEvent → 它包装成 Event，并带上测试环境里的线程、发送器、状态和 watch manager → 调用 apply_bespoke_event_handling。

调用关系：guardian_command_execution_notifications_wrap_review_lifecycle 用它多次驱动同一个测试场景。

调用图：调用 1 个内部函数（apply_bespoke_event_handling）；外部调用 5 个（new, clone, clone, GuardianAssessment, new）。

fn guardian_assessment_started_uses_event_turn_id_fallback()

作用：测试 Guardian 审查事件自己没有 turn_id 时，会退回使用外层事件的轮次编号。

数据流：进去没有外部输入 → 它构造 turn_id 为空的审查事件，调用 guardian_auto_approval_review_notification → 断言通知里的 turn_id 是外层传入值。

调用关系：它验证 apply_bespoke_event_handling 依赖的通知构造行为，避免前端收到空轮次。

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

fn guardian_assessment_completed_emits_review_payload()

作用：测试 Guardian 审查完成时通知内容完整，包括状态、风险、理由和动作。

数据流：进去没有外部输入 → 它构造一个被拒绝的命令审查事件 → 调用通知构造函数并断言各字段。

调用关系：它保护 Guardian 完成通知的协议格式。

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

fn guardian_assessment_aborted_emits_completed_review_payload()

作用：测试 Guardian 审查被中止时，也会发“审查完成”类通知，而不是消失不见。

数据流：进去没有外部输入 → 它构造一个网络访问审查被中止的事件 → 断言通知状态是 Aborted，目标项可为空。

调用关系：它覆盖安全审查的异常结束分支。

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

async fn command_execution_started_helper_emits_once() -> Result<()>

作用：测试 start_command_execution_item 对同一个命令只发一次开始通知。

数据流：进去没有外部输入 → 它建立消息通道和线程状态，第一次调用 helper 后读取通知；第二次用同一命令编号调用 → 断言第二次没有新消息。

调用关系：它直接验证 start_command_execution_item 的防重复机制。

调用图：调用 5 个内部函数（disabled, start_command_execution_item, new, new, new）；外部调用 9 个（new, command_execution_completion_item, new_thread_state, recv_broadcast_message, assert!, assert_eq!, bail!, channel, vec!）。

async fn complete_command_execution_item_emits_declined_once_for_pending_command() -> Result<()>

作用：测试命令完成通知只会对已经开始的命令发一次。

数据流：进去没有外部输入 → 它先启动命令项，再完成为 Declined 并读取完成通知；之后再次完成同一命令 → 断言没有重复通知。

调用关系：它覆盖 start_command_execution_item 与 complete_command_execution_item 之间的状态配合。

调用图：调用 6 个内部函数（disabled, complete_command_execution_item, start_command_execution_item, new, new, new）；外部调用 9 个（new, command_execution_completion_item, new_thread_state, recv_broadcast_message, assert!, assert_eq!, bail!, channel, vec!）。

async fn guardian_command_execution_notifications_wrap_review_lifecycle() -> Result<()>

作用：测试 Guardian 命令安全审查如何包住命令执行显示生命周期。进行中时显示命令和审查，拒绝时命令也要结束。

数据流：进去没有外部输入 → 它启动真实测试线程，依次送入批准和拒绝场景的 Guardian 事件 → 读取并断言 ItemStarted、审查开始、审查完成、命令完成等通知顺序。

调用关系：它通过 GuardianAssessmentTestContext::apply_guardian_assessment_event 间接调用 apply_bespoke_event_handling，覆盖主入口里 GuardianAssessment 分支。

调用图：调用 7 个内部函数（disabled, new, new, new, thread_manager_with_models_provider_and_home, default_for_tests, create_dummy_chatgpt_auth_for_testing）；外部调用 11 个（new, new, guardian_command_assessment, new_thread_state, recv_broadcast_message, assert!, assert_eq!, bail!, load_default_config_for_test, channel (+1 more)）。

fn file_change_accept_for_session_maps_to_approved_for_session()

作用：测试文件改动的“本会话接受”能正确映射成核心的“本会话批准”。

数据流：进去没有外部输入 → 它调用 map_file_change_approval_decision → 断言结果是 ApprovedForSession。

调用关系：它直接保护文件审批转换函数的一个重要分支。

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

fn mcp_server_elicitation_turn_transition_error_maps_to_cancel()

作用：测试 MCP 询问在轮次切换导致请求失效时，会被转成 Cancel。

数据流：进去没有外部输入 → 它构造一个带 turnTransition 原因的客户端错误 → 调用 mcp_server_elicitation_response_from_client_result → 断言动作是 Cancel。

调用关系：它覆盖 MCP 回复转换的特殊容错路径。

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

fn request_permissions_turn_transition_error_is_ignored()

作用：测试权限请求如果因为轮次切换而失效，会被忽略而不是默认拒绝。

数据流：进去没有外部输入 → 它构造 turnTransition 错误并调用 request_permissions_response_from_client_result → 断言返回 None。

调用关系：它覆盖权限回复转换里“不要再回核心”的分支。

调用图：调用 1 个内部函数（request_permissions_response_from_client_result）；外部调用 4 个（default, assert_eq!, json!, current_dir）。

fn request_permissions_response_accepts_partial_network_and_file_system_grants()

作用：测试客户端可以只批准申请权限的一部分。系统应只把交集交给核心。

数据流：进去没有外部输入 → 它准备网络和文件系统权限申请，再用多组客户端授权 JSON 调用转换函数 → 断言结果只包含被申请且被批准的部分。

调用关系：它重点验证 request_permissions_response_from_client_result 和 intersect_permission_profiles 的安全裁剪效果。

调用图：调用 1 个内部函数（request_permissions_response_from_client_result）；外部调用 6 个（from_read_write_roots, assert_eq!, cfg!, json!, current_dir, vec!）。

fn request_permissions_response_preserves_session_scope()

作用：测试客户端批准的会话级权限范围会被保留下来。会话级表示这次会话后续也有效。

数据流：进去没有外部输入 → 它构造 scope 为 session 的权限回复 → 调用转换函数 → 断言核心响应 scope 也是 Session。

调用关系：它覆盖权限转换的授权范围字段。

调用图：调用 1 个内部函数（request_permissions_response_from_client_result）；外部调用 4 个（default, assert_eq!, json!, current_dir）。

fn request_permissions_response_rejects_session_scoped_strict_auto_review()

作用：测试严格自动审查不能和会话级授权一起使用。这样避免一次性给出过宽的自动批准。

数据流：进去没有外部输入 → 它构造 session scope 且 strictAutoReview 为 true 的回复 → 调用转换函数 → 断言结果退回默认无权限、Turn 范围、strict 为 false。

调用关系：它保护 request_permissions_response_from_client_result 里的安全限制。

调用图：调用 1 个内部函数（request_permissions_response_from_client_result）；外部调用 4 个（default, assert_eq!, json!, current_dir）。

fn request_permissions_response_preserves_turn_scoped_strict_auto_review()

作用：测试严格自动审查在单轮授权里是允许保留的。

数据流：进去没有外部输入 → 它构造 turn 范围的网络权限授权并带 strictAutoReview → 调用转换函数 → 断言 strict_auto_review 为 true。

调用关系：它和拒绝 session scoped strict auto review 的测试互相补充。

调用图：调用 1 个内部函数（request_permissions_response_from_client_result）；外部调用 5 个（default, assert!, assert_eq!, json!, current_dir）。

fn request_permissions_response_accepts_explicit_child_grant_for_requested_cwd_scope()

作用：测试当申请的是当前项目范围写权限时，客户端批准其中一个子目录是可以接受的。

数据流：进去没有外部输入 → 它创建临时目录作为 cwd，申请项目根写权限，客户端只批准 child 子目录 → 转换后断言核心只拿到 child 写权限。

调用关系：它覆盖权限路径从特殊项目根到实际子路径的安全交集逻辑。

调用图：调用 2 个内部函数（request_permissions_response_from_client_result, from_absolute_path）；外部调用 5 个（default, new, assert_eq!, json!, vec!）。

fn request_permissions_response_rejects_child_grant_outside_requested_cwd_scope()

作用：测试客户端不能把授权偷偷指向另一个工作目录下的子路径。

数据流：进去没有外部输入 → 它申请 request-cwd 的项目范围权限，却让客户端批准 later-cwd/child → 转换后断言没有任何权限。

调用关系：它保护 request_permissions_response_from_client_result 的路径边界检查。

调用图：调用 2 个内部函数（request_permissions_response_from_client_result, from_absolute_path）；外部调用 5 个（default, new, assert_eq!, json!, vec!）。

fn request_permissions_response_ignores_broader_cwd_grant_for_requested_child_path()

作用：测试如果原本只申请某个子目录，客户端批准更宽的项目根权限也不会被接受。

数据流：进去没有外部输入 → 它申请 child 写权限，客户端返回整个项目根写权限 → 转换后断言结果为空。

调用关系：它验证权限不会被客户端回复扩大。

调用图：调用 2 个内部函数（request_permissions_response_from_client_result, from_absolute_path）；外部调用 6 个（from_read_write_roots, default, new, assert_eq!, json!, vec!）。

async fn test_handle_error_records_message() -> Result<()>

作用：测试 handle_error 会把错误记录进当前轮摘要。

数据流：进去没有外部输入 → 它创建线程状态，调用 handle_error 写入 boom 错误，再取出摘要 → 断言 last_error 等于写入内容。

调用关系：它直接覆盖 handle_error 和 find_and_remove_turn_summary 的配合。

调用图：调用 3 个内部函数（find_and_remove_turn_summary, handle_error, new）；外部调用 2 个（new_thread_state, assert_eq!）。

async fn turn_started_omits_active_snapshot_items() -> Result<()>

作用：测试 TurnStarted 通知不会带上已经缓存的旧条目，而是让客户端按未加载状态处理。

数据流：进去没有外部输入 → 它先在线程状态里放入一条用户消息，再送入 TurnStarted 事件 → 读取通知并断言 items 为空、items_view 是 NotLoaded。

调用关系：它通过 apply_bespoke_event_handling 覆盖 TurnStarted 分支，避免前端重复显示旧内容。

调用图：调用 8 个内部函数（disabled, apply_bespoke_event_handling, new, new, new, thread_manager_with_models_provider_and_home, default_for_tests, create_dummy_chatgpt_auth_for_testing）；外部调用 15 个（new, default, new, new, new_thread_state, recv_broadcast_message, assert!, assert_eq!, bail!, load_default_config_for_test (+5 more)）。

async fn interrupted_subagent_activity_removes_missing_thread_watch() -> Result<()>

作用：测试子代理线程被中断且线程已不存在时，watch 状态会被清理。

数据流：进去没有外部输入 → 它先给一个不存在的子线程登记运行状态，再送入 Interrupted 的 SubAgentActivity → 断言 watch 数量归零，并检查发出的子代理活动通知。

调用关系：它通过 apply_bespoke_event_handling 覆盖 SubAgentActivity 分支和 ThreadWatchManager 清理逻辑。

调用图：调用 10 个内部函数（disabled, apply_bespoke_event_handling, new, new, new, thread_manager_with_models_provider_and_home, default_for_tests, create_dummy_chatgpt_auth_for_testing, try_from, new）；外部调用 11 个（new, new, new_thread_state, recv_broadcast_message, assert_eq!, bail!, load_default_config_for_test, channel, SubAgentActivity, new (+1 more)）。

async fn test_handle_turn_complete_emits_completed_without_error() -> Result<()>

作用：测试没有错误时，一轮完成会发 Completed 状态。

数据流：进去没有外部输入 → 它准备带开始时间的线程状态，调用 handle_turn_complete → 读取 TurnCompleted 通知并断言状态、时间和耗时正确。

调用关系：它直接覆盖 handle_turn_complete 的正常成功路径。

调用图：调用 5 个内部函数（disabled, handle_turn_complete, new, new, new）；外部调用 12 个（new, default, new_thread_state, recv_broadcast_message, turn_complete_event, assert!, assert_eq!, bail!, channel, TurnComplete (+2 more)）。

async fn test_handle_turn_interrupted_emits_interrupted_with_error() -> Result<()>

作用：测试即使之前记录过错误，被中断的轮次也显示 Interrupted，且错误字段为空。

数据流：进去没有外部输入 → 它先调用 handle_error 记录错误，再调用 handle_turn_interrupted → 断言通知状态为 Interrupted 且没有错误。

调用关系：它保护 handle_turn_interrupted 的语义：中断不是普通失败。

调用图：调用 6 个内部函数（disabled, handle_error, handle_turn_interrupted, new, new, new）；外部调用 9 个（new, new_thread_state, recv_broadcast_message, turn_aborted_event, assert!, assert_eq!, bail!, channel, vec!）。

async fn test_handle_turn_complete_emits_failed_with_error() -> Result<()>

作用：测试有错误记录时，一轮正常结束会被标成 Failed。

数据流：进去没有外部输入 → 它先记录 bad 错误，再调用 handle_turn_complete → 断言 TurnCompleted 里状态为 Failed，并带上错误信息。

调用关系：它覆盖 handle_turn_complete 的失败路径。

调用图：调用 6 个内部函数（disabled, handle_error, handle_turn_complete, new, new, new）；外部调用 9 个（new, new_thread_state, recv_broadcast_message, turn_complete_event, assert!, assert_eq!, bail!, channel, vec!）。

async fn test_handle_turn_plan_update_emits_notification_for_v2() -> Result<()>

作用：测试计划更新会发出 v2 客户端协议的 TurnPlanUpdated 通知。

数据流：进去没有外部输入 → 它构造两步计划，调用 handle_turn_plan_update → 读取通知并检查说明、步骤文字和状态。

调用关系：它直接覆盖 handle_turn_plan_update。

调用图：调用 5 个内部函数（disabled, handle_turn_plan_update, new, new, new）；外部调用 7 个（new, recv_broadcast_message, assert!, assert_eq!, bail!, channel, vec!）。

async fn test_handle_token_count_event_emits_usage_and_rate_limits() -> Result<()>

作用：测试 token 用量和限流信息都会被通知给客户端。

数据流：进去没有外部输入 → 它构造 token 使用量和 rate limit 快照，调用 handle_token_count_event → 连续读取两条通知并检查字段。

调用关系：它覆盖 handle_token_count_event 同时发两类通知的情况。

调用图：调用 5 个内部函数（disabled, handle_token_count_event, new, new, new）；外部调用 7 个（new, recv_broadcast_message, assert!, assert_eq!, bail!, channel, vec!）。

async fn test_handle_token_count_event_without_usage_info() -> Result<()>

作用：测试没有 token 用量和限流信息时，不应发任何通知。

数据流：进去没有外部输入 → 它传入 info 和 rate_limits 都为空的 TokenCountEvent → 调用处理函数后断言通道里没有消息。

调用关系：它覆盖 handle_token_count_event 的空输入分支。

调用图：调用 5 个内部函数（disabled, handle_token_count_event, new, new, new）；外部调用 4 个（new, assert!, channel, vec!）。

async fn test_handle_turn_complete_emits_error_multiple_turns() -> Result<()>

作用：测试错误摘要会在一轮结束后清空，不会污染后续轮次。

数据流：进去没有外部输入 → 它模拟多个线程/轮次依次记录错误和完成 → 读取三条完成通知，断言前两轮失败、后一轮成功。

调用关系：它验证 handle_error、handle_turn_complete、find_and_remove_turn_summary 的状态清理效果。

调用图：调用 6 个内部函数（disabled, handle_error, handle_turn_complete, new, new, new）；外部调用 9 个（new, new_thread_state, recv_broadcast_message, turn_complete_event, assert!, assert_eq!, bail!, channel, vec!）。

async fn test_handle_turn_diff_emits_v2_notification() -> Result<()>

作用：测试代码差异更新会发出正确的 v2 通知。

数据流：进去没有外部输入 → 它构造一段 unified diff，调用 handle_turn_diff → 读取通知并检查线程、轮次和 diff 文本。

调用关系：它直接覆盖 handle_turn_diff。

调用图：调用 5 个内部函数（disabled, handle_turn_diff, new, new, new）；外部调用 7 个（new, recv_broadcast_message, assert!, assert_eq!, bail!, channel, vec!）。

async fn test_hook_prompt_raw_response_emits_item_completed() -> Result<()>

作用：测试原始响应里的 hook prompt 能被识别并显示成完成的 HookPrompt 条目。

数据流：进去没有外部输入 → 它构造包含两个 hook 片段的原始消息，调用 maybe_emit_hook_prompt_item_completed → 读取 ItemCompleted 通知并检查片段内容。

调用关系：它直接覆盖 maybe_emit_hook_prompt_item_completed 的成功解析路径。

调用图：调用 6 个内部函数（disabled, maybe_emit_hook_prompt_item_completed, new, new, build_hook_prompt_message, new）；外部调用 8 个（new, from_single_hook, recv_broadcast_message, assert!, assert_eq!, bail!, channel, vec!）。

fn new(
        manager: ThreadWatchManager,
        thread_id: String,
        guard_type: ThreadWatchActiveGuardType,
    ) -> Self

作用：创建一个“活动守卫”。它代表某个线程当前有一件还没结束的等待事项，比如等批准或等用户输入。

数据流：进去的是管理器、线程编号和等待类型 → 它把这些保存下来，并记住当前异步运行环境的句柄 → 出来一个 guard，之后只要这个 guard 还活着，等待事项就被认为还没结束。

调用关系：它由 ThreadWatchManager::note_pending_request 创建。后续真正的收尾不是调用者手动做，而是在 ThreadWatchActiveGuard::drop 里自动交回给管理器。

调用图：被 1 处调用（note_pending_request）；外部调用 1 个（current）。

fn drop(&mut self)

作用：当等待事项结束、guard 被释放时，自动通知管理器把对应的等待计数减一。

数据流：进去的是 guard 里保存的管理器、线程编号和等待类型 → 它复制这些信息，在线程运行时里启动一个异步任务 → 结果是管理器稍后更新状态，可能把线程从“等批准/等输入”改回普通活动状态。

调用关系：这是 Rust 的自动清理钩子，不需要业务代码显式调用。它把收尾工作交给 ThreadWatchManager::note_active_guard_released，避免调用者忘记清理。

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

fn default() -> Self

作用：提供默认创建方式，让需要默认值的地方能直接得到一个空的线程状态管理器。

数据流：没有额外输入 → 它调用 ThreadWatchManager::new → 出来一个没有外发通知通道、内部状态为空的管理器。

调用关系：它只是 ThreadWatchManager::new 的便捷入口，适合测试或普通初始化时使用。

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

fn new() -> Self

作用：新建一个线程状态管理器，但不连接对外消息发送器。适合只在内部查询或测试状态时用。

数据流：没有输入 → 它建一份空状态、一把异步互斥锁（一把锁，防止多个任务同时改同一份数据）和一个运行中线程数量的 watch 通道 → 出来一个可共享、可并发使用的管理器。

调用关系：很多测试和运行流程会先用它建立状态中心。之后 upsert、note_turn_started 等函数都围绕这个管理器工作。

调用图：被 11 处调用（guardian_command_execution_notifications_wrap_review_lifecycle, interrupted_subagent_activity_removes_missing_thread_watch, turn_started_omits_active_snapshot_items, has_running_turns_tracks_runtime_running_flag_only, loaded_status_defaults_to_not_loaded_for_untracked_threads, loaded_statuses_default_to_not_loaded_for_untracked_threads, shutdown_marks_thread_not_loaded, status_updates_track_single_thread, status_watchers_receive_only_their_thread_updates, system_error_sets_idle_flag_until_next_turn (+1 more)）；外部调用 4 个（new, new, default, channel）。

fn new_with_outgoing(outgoing: Arc<OutgoingMessageSender>) -> Self

作用：新建一个会向外发送状态变化通知的线程状态管理器。前端或客户端需要实时知道线程状态时会用它。

数据流：进去一个 OutgoingMessageSender（对外发消息的发送器）→ 它保存发送器，并初始化空状态和运行数量通道 → 出来一个既能记状态、又能广播变化的管理器。

调用关系：服务器启动或相关组件创建时会用它。之后 ThreadWatchManager::mutate_and_publish 会通过这个发送器发 ThreadStatusChanged 通知。

调用图：被 3 处调用（new, silent_upsert_skips_initial_notification, status_change_emits_notification）；外部调用 4 个（new, new, default, channel）。

async fn upsert_thread(&self, thread: Thread)

作用：登记或刷新一个线程，并且在状态变化时发通知。名字里的 upsert 表示“有就更新，没有就插入”。

数据流：进去一个 Thread，其中最重要的是线程编号 → 它把该线程标记为已加载，并计算状态是否变化 → 出来没有直接返回值，但内部状态会更新，必要时会广播状态变化。

调用关系：线程恢复或监听器接上线程时会调用它。它把实际改状态和通知的活交给 ThreadWatchManager::mutate_and_publish。

调用图：调用 1 个内部函数（mutate_and_publish）；被 2 处调用（thread_resume_inner, try_attach_thread_listener）。

async fn upsert_thread_silently(&self, thread: Thread)

作用：静默登记或刷新一个线程，也就是更新内部状态但不发第一次状态通知。

数据流：进去一个 Thread → 它把线程标记为已加载 → 出来没有直接返回值，状态会变成已知状态，但初始通知被刻意跳过。

调用关系：分叉线程或后台启动某些流程时会用它，避免刚建立内部记录就打扰外部。后续真正运行状态变化仍会通过普通流程发布。

调用图：调用 1 个内部函数（mutate_and_publish）；被 2 处调用（thread_fork_inner, start_detached_review）。

async fn remove_thread(&self, thread_id: &str)

作用：把一个线程从状态看板上移走，并把它视为 NotLoaded（未加载）。

数据流：进去线程编号 → 它删除该线程的运行事实，更新订阅者看到的状态 → 出来没有直接返回值，但如果原来不是未加载，会发一条变成 NotLoaded 的通知。

调用关系：线程卸载、清理或特殊事件处理时会调用它。它通过 ThreadWatchManager::mutate_and_publish 统一完成修改和通知。

调用图：调用 1 个内部函数（mutate_and_publish）；被 3 处调用（apply_bespoke_event_handling, unload_thread_without_subscribers, finalize_thread_teardown）。

async fn loaded_status_for_thread(&self, thread_id: &str) -> ThreadStatus

作用：查询某一个线程当前对外应该显示的状态。找不到的线程会被当成未加载。

数据流：进去线程编号 → 它锁住内部状态并查表 → 出来一个 ThreadStatus，比如 Idle、Active、NotLoaded 或 SystemError。

调用关系：很多读取线程详情、恢复线程、更新元数据的流程都会用它来决定该怎么展示或下一步怎么处理。

调用图：被 11 处调用（apply_bespoke_event_handling, handle_pending_thread_resume_request, read_thread_view, resume_running_thread, thread_fork_inner, thread_metadata_update_response_inner, thread_resume_inner, thread_turns_list_response_inner, thread_unarchive_response, start_detached_review (+1 more)）。

async fn loaded_statuses_for_threads(
        &self,
        thread_ids: Vec<String>,
    ) -> HashMap<String, ThreadStatus>

作用：一次查询多个线程的状态，适合列表页或搜索结果页批量补状态。

数据流：进去一组线程编号 → 它锁住状态表，逐个查状态，查不到就给 NotLoaded → 出来一个从线程编号到状态的映射表。

调用关系：线程列表和线程搜索响应会用它，避免一个个反复加锁查询。

调用图：被 2 处调用（thread_list_response_inner, thread_search_response_inner）。

async fn running_turn_count(&self) -> usize

作用：测试用函数，用来数当前真正处于 running 的线程回合有几个。

数据流：没有输入 → 它读取内部所有线程的运行事实，只统计 running 为真的项 → 出来一个数字。

调用关系：只在测试里启用，用来验证“等待批准”不应该被误算成正在运行。

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

作用：让外部订阅“当前有多少线程正在运行”这个数字的变化。

数据流：没有输入 → 它从内部 watch 通道创建一个接收端 → 出来一个 Receiver，订阅者可以拿它等待数字变化。

调用关系：subscribe_running_assistant_turn_count 会调用它。每次状态修改后，ThreadWatchManager::mutate_and_publish 会更新这个数字。

调用图：被 1 处调用（subscribe_running_assistant_turn_count）；外部调用 1 个（subscribe）。

async fn note_turn_started(&self, thread_id: &str)

作用：记录某个线程的一轮工作已经开始。这里的 turn 可以理解为一次助手处理请求的回合。

数据流：进去线程编号 → 它把线程标记为已加载、正在运行，并清掉旧的系统错误标记 → 出来没有直接返回值，但状态通常会变成 Active。

调用关系：事件处理流程 apply_bespoke_event_handling 在看到“开始运行”事件时调用它。它通过 ThreadWatchManager::update_runtime_for_thread 更新内部事实。

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

async fn note_turn_completed(&self, thread_id: &str, _failed: bool)

作用：记录某个线程的一轮工作已经正常结束。

数据流：进去线程编号和失败标记；当前实现不使用失败标记 → 它清掉运行中、等批准、等用户输入这些活动状态 → 出来没有直接返回值，线程通常回到 Idle。

调用关系：事件处理流程在收到完成事件时调用它。它把实际清理交给 ThreadWatchManager::clear_active_state。

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

async fn note_turn_interrupted(&self, thread_id: &str)

作用：记录某个线程的一轮工作被中断了，比如被用户停止。

数据流：进去线程编号 → 它清掉运行中和各种等待中的标记 → 出来没有直接返回值，线程不再显示为活动。

调用关系：事件处理流程在收到中断事件时调用它。它和完成事件一样复用 ThreadWatchManager::clear_active_state。

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

async fn note_thread_shutdown(&self, thread_id: &str)

作用：记录某个线程已经关掉，不能再当作已加载线程看待。

数据流：进去线程编号 → 它把 running、等待批准、等待输入都清零，并把 is_loaded 设为 false → 出来没有直接返回值，状态会变成 NotLoaded。

调用关系：事件处理流程在收到线程关闭信号时调用它。它通过 ThreadWatchManager::update_runtime_for_thread 触发状态刷新和通知。

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

async fn note_system_error(&self, thread_id: &str)

作用：记录某个线程遇到了系统级错误，需要显示成错误状态。

数据流：进去线程编号 → 它停止 running，清掉等待事项，并打上 has_system_error 标记 → 出来没有直接返回值，状态会变成 SystemError。

调用关系：事件处理流程在收到系统错误时调用它。下一次 ThreadWatchManager::note_turn_started 会清掉这个错误标记。

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

async fn clear_active_state(&self, thread_id: &str)

作用：统一清理线程的“正在活动”状态，包括正在运行、等批准、等输入。

数据流：进去线程编号 → 它把对应线程的 running 和两个等待计数都归零 → 出来没有直接返回值，状态会重新计算。

调用关系：ThreadWatchManager::note_turn_completed 和 ThreadWatchManager::note_turn_interrupted 都用它，避免两处写重复清理逻辑。

调用图：调用 1 个内部函数（update_runtime_for_thread）；被 2 处调用（note_turn_completed, note_turn_interrupted）。

async fn note_permission_requested(
        &self,
        thread_id: &str,
    ) -> ThreadWatchActiveGuard

作用：记录某个线程正在等待用户批准，比如批准某个操作。

数据流：进去线程编号 → 它增加“等待批准”的计数 → 出来一个 ThreadWatchActiveGuard，调用方保留它期间，状态会带 WaitingOnApproval 标记。

调用关系：事件处理流程在发现需要权限时调用它。它把通用的计数和 guard 创建交给 ThreadWatchManager::note_pending_request。

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

async fn note_user_input_requested(
        &self,
        thread_id: &str,
    ) -> ThreadWatchActiveGuard

作用：记录某个线程正在等待用户输入，比如需要用户补一句话或填写信息。

数据流：进去线程编号 → 它增加“等待用户输入”的计数 → 出来一个 ThreadWatchActiveGuard，guard 释放后等待计数会自动减少。

调用关系：事件处理流程在发现需要用户输入时调用它。它复用 ThreadWatchManager::note_pending_request。

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

async fn note_pending_request(
        &self,
        thread_id: &str,
        guard_type: ThreadWatchActiveGuardType,
    ) -> ThreadWatchActiveGuard

作用：处理“有一项等待事项开始了”的通用逻辑，不管是等批准还是等输入。

数据流：进去线程编号和等待类型 → 它把线程标记为已加载，并把对应等待计数加一 → 出来一个 guard，用来在等待结束时自动扣回计数。

调用关系：ThreadWatchManager::note_permission_requested 和 ThreadWatchManager::note_user_input_requested 都调用它。它内部先更新运行事实，再用 ThreadWatchActiveGuard::new 生成自动收尾工具。

调用图：调用 2 个内部函数（new, update_runtime_for_thread）；被 2 处调用（note_permission_requested, note_user_input_requested）。

async fn mutate_and_publish(&self, mutate: F)

作用：这是本文件的“改状态并通知”的总闸门。所有会改变状态的操作都尽量从这里过，保证改完以后订阅者和外部消息都能跟上。

数据流：进去一个修改函数 → 它先锁住状态执行修改，再统计正在运行的线程数量，释放锁后更新运行数量通道，并在需要时发送 ThreadStatusChanged 通知 → 出来没有直接返回值，但内部状态和外部观察结果都会更新。

调用关系：upsert、remove、update_runtime_for_thread 都调用它。它把 ThreadWatchState 的纯状态修改和 OutgoingMessageSender 的对外通知连接起来。

调用图：被 4 处调用（remove_thread, update_runtime_for_thread, upsert_thread, upsert_thread_silently）；外部调用 2 个（send, ThreadStatusChanged）。

async fn subscribe(
        &self,
        thread_id: ThreadId,
    ) -> Option<watch::Receiver<ThreadStatus>>

作用：让调用者订阅某一个线程的状态变化。

数据流：进去一个 ThreadId → 它转成字符串，锁住状态并取得该线程专用的 watch 接收端 → 出来一个 Receiver，调用者能看到该线程最新状态和后续变化。

调用关系：需要实时跟踪单个线程的地方会调用它。底层工作由 ThreadWatchState::subscribe 完成。

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

async fn note_active_guard_released(
        &self,
        thread_id: String,
        guard_type: ThreadWatchActiveGuardType,
    )

作用：当等待事项的 guard 被释放时，减少对应的等待计数。

数据流：进去线程编号和等待类型 → 它找到对应计数，用安全减法减一，避免已经是零时变成负数 → 出来没有直接返回值，状态会重新计算。

调用关系：ThreadWatchActiveGuard::drop 会异步触发它。它再通过 ThreadWatchManager::update_runtime_for_thread 更新状态。

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

async fn update_runtime_for_thread(&self, thread_id: &str, update: F)

作用：给某个线程改一小块运行事实，比如 running、等待计数或错误标记。

数据流：进去线程编号和一个具体修改动作 → 它包装成对 ThreadWatchState 的更新 → 出来没有直接返回值，但会经过统一的发布流程。

调用关系：开始、结束、关闭、报错、等待请求和 guard 释放都会调用它。它把工作交给 ThreadWatchManager::mutate_and_publish。

调用图：调用 1 个内部函数（mutate_and_publish）；被 6 处调用（clear_active_state, note_active_guard_released, note_pending_request, note_system_error, note_thread_shutdown, note_turn_started）。

fn pending_counter(
        runtime: &mut RuntimeFacts,
        guard_type: ThreadWatchActiveGuardType,
    ) -> &mut u32

作用：根据等待类型，找到该改哪个计数器：等批准，还是等用户输入。

数据流：进去一份线程运行事实和等待类型 → 它选择对应字段 → 出来这个字段的可修改引用，调用者可以加一或减一。

调用关系：ThreadWatchManager::note_pending_request 和 ThreadWatchManager::note_active_guard_released 用它，保证两类等待事项不会改错计数器。

fn resolve_thread_status(
    status: ThreadStatus,
    has_in_progress_turn: bool,
) -> ThreadStatus

作用：修正一种短暂的时间差：真实工作已经开始了，但状态监听还没来得及看到。

数据流：进去一个已有状态和“是否有正在进行的回合”这个布尔值 → 如果已有状态是 Idle 或 NotLoaded，但确实有回合在跑，就改成 Active → 出来修正后的 ThreadStatus。

调用关系：测试验证了它的行为。它适合用在外层读状态时，避免用户看到线程明明在工作却显示空闲。

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

fn upsert_thread(
        &mut self,
        thread_id: String,
        emit_notification: bool,
    ) -> Option<ThreadStatusChangedNotification>

作用：在底层状态表里登记或刷新一个线程，并决定是否生成状态变化通知。

数据流：进去线程编号和是否发通知的开关 → 它先记住旧状态，再把线程设为已加载，更新订阅者，最后按开关决定是否返回通知 → 出来可能是一条 ThreadStatusChangedNotification。

调用关系：ThreadWatchManager::upsert_thread 和静默版本会通过 mutate_and_publish 间接调用它。它属于内部状态层，不直接发消息。

调用图：调用 3 个内部函数（status_changed_notification, status_for, update_status_watcher_for_thread）。

fn remove_thread(&mut self, thread_id: &str) -> Option<ThreadStatusChangedNotification>

作用：从底层状态表里删除线程，并把订阅者看到的状态改成 NotLoaded。

数据流：进去线程编号 → 它读取旧状态，删除运行事实，更新 watch 订阅者 → 出来可能是一条变成 NotLoaded 的通知。

调用关系：ThreadWatchManager::remove_thread 通过统一发布流程调用它。它只负责算出该不该通知，不负责真正发送。

调用图：调用 2 个内部函数（status_for, update_status_watcher）。

fn update_runtime(
        &mut self,
        thread_id: &str,
        mutate: F,
    ) -> Option<ThreadStatusChangedNotification>

作用：修改某个线程的运行事实，并根据新旧状态判断是否需要通知。

数据流：进去线程编号和修改函数 → 它保存旧状态，确保线程记录存在并标记已加载，执行修改，更新订阅者，再比较新旧状态 → 出来可能是一条状态变化通知。

调用关系：ThreadWatchManager::update_runtime_for_thread 间接调用它。几乎所有运行事件最终都会落到这里。

调用图：调用 3 个内部函数（status_changed_notification, status_for, update_status_watcher_for_thread）。

fn status_for(&self, thread_id: &str) -> Option<ThreadStatus>

作用：只在内部状态表里查某个线程的状态；如果表里没有，就返回没有结果。

数据流：进去线程编号 → 它查 runtime_by_thread_id，并把 RuntimeFacts 转成 ThreadStatus → 出来 Option<ThreadStatus>，表示可能有也可能没有。

调用关系：多个内部函数用它比较新旧状态。真正对外查询通常用 loaded_status_for_thread，因为它会把缺失值补成 NotLoaded。

调用图：被 5 处调用（loaded_status_for_thread, remove_thread, status_changed_notification, update_runtime, upsert_thread）。

fn loaded_status_for_thread(&self, thread_id: &str) -> ThreadStatus

作用：内部版的“查询线程状态”，并把没记录的线程统一看成 NotLoaded。

数据流：进去线程编号 → 它先调用 status_for → 如果没有记录，就补 ThreadStatus::NotLoaded → 出来一个确定的状态。

调用关系：订阅初始化和更新订阅者时都会用它，保证接收者总能拿到一个明确状态。

调用图：调用 1 个内部函数（status_for）；被 2 处调用（subscribe, update_status_watcher_for_thread）。

fn subscribe(&mut self, thread_id: String) -> watch::Receiver<ThreadStatus>

作用：为某个线程创建或复用一个状态订阅通道。

数据流：进去线程编号 → 它先算当前状态，如果这个线程还没有发送端就创建一个 watch 通道 → 出来一个接收端，订阅者可以监听后续变化。

调用关系：ThreadWatchManager::subscribe 会调用它。之后 ThreadWatchState::update_status_watcher 会向这些订阅者推送变化。

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

fn update_status_watcher_for_thread(&mut self, thread_id: &str)

作用：把某个线程当前算出来的状态推给它的订阅者。

数据流：进去线程编号 → 它先重新计算该线程状态 → 再调用 update_status_watcher 真正发送 → 出来没有直接返回值。

调用关系：线程被登记或运行事实改变后会调用它。它是“状态表变化”和“watch 订阅者收到更新”之间的连接点。

调用图：调用 2 个内部函数（loaded_status_for_thread, update_status_watcher）；被 2 处调用（update_runtime, upsert_thread）。

fn update_status_watcher(&mut self, thread_id: &str, status: &ThreadStatus)

作用：向某个线程的 watch 通道发送新状态，并清理没人听的通道。

数据流：进去线程编号和新状态 → 如果有发送端，它只在状态真的不同的时候更新；然后检查接收者数量 → 如果没人订阅，就把发送端从表里删掉。

调用关系：ThreadWatchState::remove_thread 和 update_status_watcher_for_thread 会调用它。这样订阅系统不会积累没人使用的旧通道。

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

fn status_changed_notification(
        &self,
        thread_id: String,
        previous_status: Option<ThreadStatus>,
    ) -> Option<ThreadStatusChangedNotification>

作用：根据旧状态和当前状态，判断是否需要生成一条对外状态变化通知。

数据流：进去线程编号和旧状态 → 它查当前状态；如果当前没有记录或和旧状态一样，就不通知 → 否则出来一条 ThreadStatusChangedNotification。

调用关系：upsert 和 update_runtime 用它。真正发送通知由更外层的 ThreadWatchManager::mutate_and_publish 完成。

调用图：调用 1 个内部函数（status_for）；被 2 处调用（update_runtime, upsert_thread）。

fn loaded_thread_status(runtime: &RuntimeFacts) -> ThreadStatus

作用：把内部零散事实翻译成人能理解、协议能发送的线程状态。

数据流：进去 RuntimeFacts，比如是否加载、是否运行、等待计数、是否系统错误 → 它按优先级判断：未加载优先；运行或有等待就是 Active；系统错误就是 SystemError；否则 Idle → 出来一个 ThreadStatus。

调用关系：ThreadWatchState::status_for 会用它。它是状态判断的核心规则表。

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

async fn loaded_status_defaults_to_not_loaded_for_untracked_threads()

作用：测试没登记过的线程会不会默认显示为 NotLoaded。

数据流：进去一个新管理器和一个不存在的线程编号 → 它查询状态 → 期望出来 NotLoaded。

调用关系：它验证 ThreadWatchManager::new 和 loaded_status_for_thread 的默认行为，防止未知线程被误显示为空闲或活动。

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

async fn tracks_non_interactive_thread_status()

作用：测试非交互线程开始运行后也会显示为 Active。

数据流：进去一个测试线程 → 它登记线程，再记录回合开始 → 查询结果应从 Idle 变成 Active。

调用关系：它覆盖 ThreadWatchManager::upsert_thread、note_turn_started 和 loaded_status_for_thread 的配合。

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

async fn status_updates_track_single_thread()

作用：测试单个交互线程从运行、等批准、等输入，到恢复空闲的完整状态变化。

数据流：进去一个测试线程 → 它依次模拟开始运行、请求权限、请求用户输入、释放两个 guard、完成回合 → 每一步都检查状态和活动标记是否正确。

调用关系：它把 note_turn_started、note_permission_requested、note_user_input_requested、guard 自动释放和 note_turn_completed 串起来验一遍。

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

fn resolves_in_progress_turn_to_active_status()

作用：测试当外部已知有回合正在进行时，Idle 或 NotLoaded 会被修正成 Active。

数据流：进去 Idle 和 NotLoaded 两种状态，并把 has_in_progress_turn 设为真 → 调用 resolve_thread_status → 期望都出来 Active。

调用关系：它直接验证 resolve_thread_status 解决短暂状态延迟的规则。

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

fn keeps_status_when_no_in_progress_turn()

作用：测试没有正在进行的回合时，状态不会被乱改。

数据流：进去 Idle 或 SystemError，并把 has_in_progress_turn 设为假 → 比较结果 → 期望输出仍是原状态。

调用关系：它补充验证 resolve_thread_status 的边界：只有确实有运行中回合时才修正。

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

async fn system_error_sets_idle_flag_until_next_turn()

作用：测试系统错误会显示为 SystemError，并且下一次开始运行会清掉这个错误。

数据流：进去一个测试线程 → 它登记、开始运行、记录系统错误，再查询状态；随后再次开始运行 → 结果先是 SystemError，后是 Active。

调用关系：它验证 note_system_error 和 note_turn_started 的配合，确保旧错误不会污染下一轮运行。

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

async fn shutdown_marks_thread_not_loaded()

作用：测试线程关闭后会变成 NotLoaded。

数据流：进去一个测试线程 → 它登记并开始运行，然后记录 shutdown → 查询结果应为 NotLoaded。

调用关系：它验证 ThreadWatchManager::note_thread_shutdown 会清掉加载状态和活动状态。

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

async fn loaded_statuses_default_to_not_loaded_for_untracked_threads()

作用：测试批量查询时，已知线程和未知线程都会得到正确状态。

数据流：进去两个线程编号，其中一个已登记并正在运行，另一个不存在 → 批量查询 → 结果中一个是 Active，另一个是 NotLoaded。

调用关系：它验证 ThreadWatchManager::loaded_statuses_for_threads 适合列表场景，不会漏掉未知线程的默认状态。

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

async fn has_running_turns_tracks_runtime_running_flag_only()

作用：测试“正在运行的线程数量”只看 running 标记，不把等待批准误算进去。

数据流：进去一个测试线程 → 先请求权限，再开始运行，再完成回合 → 每一步检查 running_turn_count 是否是 0、1、0。

调用关系：它验证运行数量统计和活动状态标记不是一回事，避免界面或外部订阅误判。

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

async fn status_change_emits_notification()

作用：测试状态变化时会向外发 ThreadStatusChanged 通知。

数据流：进去一个带 outgoing 通道的管理器 → 它登记线程、开始运行、删除线程 → 从接收端依次收到 Idle、Active、NotLoaded 通知。

调用关系：它验证 ThreadWatchManager::new_with_outgoing 和 mutate_and_publish 的对外广播行为。

调用图：调用 3 个内部函数（disabled, new, new_with_outgoing）；外部调用 4 个（new, test_thread, assert_eq!, channel）。

async fn silent_upsert_skips_initial_notification()

作用：测试静默登记不会发送初始通知，但之后状态变化仍会发送通知。

数据流：进去一个带 outgoing 通道的管理器 → 静默登记线程后检查收不到消息；再开始运行 → 应收到 Active 通知。

调用关系：它验证 upsert_thread_silently 只跳过第一次通知，不会关闭后续通知机制。

调用图：调用 3 个内部函数（disabled, new, new_with_outgoing）；外部调用 5 个（new, test_thread, assert!, assert_eq!, channel）。

async fn status_watchers_receive_only_their_thread_updates()

作用：测试订阅某个线程的人只会收到这个线程的变化，不会被别的线程打扰。

数据流：进去两个测试线程和两个订阅者 → 只让第一个线程开始运行 → 第一个订阅者收到 Active，第二个订阅者没有收到变化且仍是 Idle。

调用关系：它验证 ThreadWatchManager::subscribe、ThreadWatchState::subscribe 和 update_status_watcher 的按线程隔离。

调用图：调用 2 个内部函数（new, from_string）；外部调用 5 个（from_secs, test_thread, assert!, assert_eq!, timeout）。

async fn wait_for_status(
        manager: &ThreadWatchManager,
        thread_id: &str,
        expected_status: ThreadStatus,
    )

作用：测试辅助函数，反复等待某个线程变成指定状态。

数据流：进去管理器、线程编号和期望状态 → 它在超时时间内循环查询，不符合就让出执行机会 → 成功时正常结束，超时则测试失败。

调用关系：状态 guard 的释放是异步发生的，所以 tests::status_updates_track_single_thread 用它等待状态真正更新。

调用图：调用 1 个内部函数（loaded_status_for_thread）；外部调用 3 个（from_secs, yield_now, timeout）。

async fn recv_status_changed_notification(
        outgoing_rx: &mut mpsc::Receiver<OutgoingEnvelope>,
    ) -> ThreadStatusChangedNotification

作用：测试辅助函数，从 outgoing 通道里取出并确认是一条线程状态变化通知。

数据流：进去一个消息接收端 → 它限时接收一条消息，检查消息形状必须是广播的 ThreadStatusChanged → 出来具体的 ThreadStatusChangedNotification。

调用关系：通知相关测试用它来避免重复写拆消息和检查消息类型的代码。

调用图：调用 1 个内部函数（recv）；外部调用 3 个（from_secs, panic!, timeout）。

fn test_thread(thread_id: &str, source: codex_app_server_protocol::SessionSource) -> Thread

作用：测试辅助函数，快速造一个内容完整但数据假的 Thread。

数据流：进去线程编号和来源类型 → 它填入测试用的 session、路径、模型、版本、初始状态等字段 → 出来一个可交给管理器登记的 Thread。

调用关系：多数测试用它准备输入数据。这样测试重点放在线程状态变化，而不是手写一大堆 Thread 字段。

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

fn format_location(item: &ReviewFinding) -> String

作用：把一条审查发现里的代码位置，变成一段短文字，比如“某个文件:第几行-第几行”。这样用户一眼就知道问题出在哪里。

数据流：进去的是一条 ReviewFinding，也就是一条审查发现；函数读取里面的绝对文件路径和行号范围；然后把它们拼成“路径:开始行-结束行”的字符串；出来的是这段位置文字，不改动原来的审查数据。

调用关系：它是一个小零件，专门给 format_review_findings_block 使用。后者在生成完整问题列表时，每处理一条发现都会叫它来写出位置。

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

fn format_review_findings_block(
    findings: &[ReviewFinding],
    selection: Option<&[bool]>,
) -> String

作用：把多条审查发现整理成一整块可读的文字列表。有人需要把审查结果展示给用户时，就可以直接拿它生成列表内容。

数据流：进去的是一组 ReviewFinding，以及可选的 selection 勾选状态；函数先决定标题是单数“Review comment”还是复数“Full review comments”；再逐条读取每个问题的标题、正文和位置；位置交给 format_location 拼好；如果传入了勾选状态，就给每条加上“[x]”或“[ ]”，缺失的勾选值默认当作已选；最后出来的是用换行连接好的一整段文本，不会修改输入的数据。

调用关系：它处在“审查数据”到“用户可见文字”的中间层。render_review_output_text 会用它把 findings 部分拼进最终说明；退出审查模式的流程 exit_review_mode 也会直接用它来展示或处理完整审查列表。

调用图：调用 1 个内部函数（format_location）；被 3 处调用（render_review_output_text, render_review_output_text, exit_review_mode）；外部调用 5 个（new, new, format!, iter, len）。

fn render_review_output_text(output: &ReviewOutputEvent) -> String

作用：把一次审查输出变成最终要给用户看的完整文字。它会同时照顾总体解释和具体问题列表，还会在没有内容时给出友好的失败提示。

数据流：进去的是 ReviewOutputEvent，也就是一次审查输出事件；函数先读取 overall_explanation，并去掉前后空白；如果解释不为空，就放进结果段落；再检查 findings，如果有具体问题，就调用 format_review_findings_block 生成问题列表并加入结果；如果两边都没有内容，就返回固定兜底句“Reviewer failed to output a response.”；出来的是最终文本，不改动事件本身。

调用关系：它是这个文件里最接近外部使用的入口。退出审查模式 exit_review_mode 会调用它，把审查器的输出变成用户消息；测试 review_op_emits_lifecycle_and_review_output 也会用它来确认审查输出能按预期生成。它把具体列表格式化的工作交给 format_review_findings_block。

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

fn item_event_to_server_notification(
    msg: EventMsg,
    thread_id: &str,
    turn_id: &str,
) -> ServerNotification

作用：把一个核心事件转换成服务器要发给客户端的通知。有人会在收到内部事件后调用它，好让客户端能用统一的 v2 协议看到这件事。

数据流：输入是一个 EventMsg，以及当前 thread_id 和 turn_id。函数先把线程和回合编号转成字符串，然后根据事件种类分别处理：比如工具调用结果会变成完成通知，协作代理开始会变成开始通知，命令输出的字节会转成文字增量，文件补丁会转成客户端格式。输出是一个 ServerNotification；它不保存额外状态，只负责把这一条事件翻译成这一条通知。

调用关系：这是本文件的核心转换器。测试函数 collab_resume_begin_maps_to_item_started_resume_agent、collab_resume_end_maps_to_item_completed_resume_agent 和 exec_command_output_delta_maps_to_command_execution_output_delta 会直接调用它来验证结果。转换过程中，它会把命令执行事件交给 build_command_execution_begin_item 和 build_command_execution_end_item 来组装条目，把补丁变化交给 convert_patch_changes 来改成客户端需要的形状。

调用图：调用 4 个内部函数（build_command_execution_begin_item, build_command_execution_end_item, convert_patch_changes, from）；被 3 处调用（collab_resume_begin_maps_to_item_started_resume_agent, collab_resume_end_maps_to_item_completed_resume_agent, exec_command_output_delta_maps_to_command_execution_output_delta）；外部调用 17 个（new, AgentMessageDelta, CommandExecutionOutputDelta, FileChangePatchUpdated, ItemCompleted, ItemStarted, PlanDelta, ReasoningSummaryPartAdded, ReasoningSummaryTextDelta, ReasoningTextDelta (+7 more)）。

fn assert_item_started_server_notification(
        notification: ServerNotification,
        expected: ItemStartedNotification,
    )

作用：这是测试里的小帮手，用来确认某个通知确实是“条目开始了”的通知，而且内容完全符合预期。

数据流：输入是实际生成的 ServerNotification 和期望的 ItemStartedNotification。它先检查实际通知的类型是不是 ItemStarted；如果是，就比较里面的内容是否一样；如果不是，就直接让测试失败并报错。

调用关系：它服务于测试流程，主要被 collab_resume_begin_maps_to_item_started_resume_agent 使用。这样测试用例不用反复写匹配和比较代码，只要把期望结果交给这个帮手检查即可。

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

fn assert_item_completed_server_notification(
        notification: ServerNotification,
        expected: ItemCompletedNotification,
    )

作用：这是测试里的小帮手，用来确认某个通知确实是“条目完成了”的通知，并且完成内容和预期一致。

数据流：输入是实际通知和期望的完成通知。它检查实际通知是不是 ItemCompleted；如果是，就逐项比较；如果拿到的是别的通知类型，就让测试失败并说明拿错了类型。

调用关系：它被 collab_resume_end_maps_to_item_completed_resume_agent 使用，用来检查协作代理恢复结束后，转换出的完成通知是否正确。它让测试代码更短，也让失败信息更清楚。

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

fn assert_command_execution_output_delta_server_notification(
        notification: ServerNotification,
        expected: CommandExecutionOutputDeltaNotification,
    )

作用：这是测试里的小帮手，用来确认某个通知是“命令执行输出了一小段内容”的通知，并且输出文本正确。

数据流：输入是实际生成的 ServerNotification 和期望的 CommandExecutionOutputDeltaNotification。它先判断通知类型是不是 CommandExecutionOutputDelta；是的话就比较内容，不是的话就让测试失败。

调用关系：它被 exec_command_output_delta_maps_to_command_execution_output_delta 使用。这个测试关心的是命令输出的字节是否被正确变成客户端能显示的文字，所以这个帮手专门检查这类通知。

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

fn collab_resume_begin_maps_to_item_started_resume_agent()

作用：这个测试确认“恢复协作代理开始”这种内部事件，会被翻译成“恢复代理工具调用正在进行”的开始通知。

数据流：测试先造出一个 CollabResumeBeginEvent，里面有调用 ID、开始时间、发送方线程和接收方线程。然后把它包成 EventMsg 交给 item_event_to_server_notification。最后用 assert_item_started_server_notification 检查输出：线程号、回合号、工具类型、进行中状态、接收方线程等都必须符合预期。

调用关系：这是对核心转换器 item_event_to_server_notification 的定点检查。它验证恢复代理的 begin 分支没有被误映射成别的工具，也没有漏掉发送方和接收方线程信息。

调用图：调用 2 个内部函数（item_event_to_server_notification, new）；外部调用 4 个（new, assert_item_started_server_notification, CollabResumeBegin, vec!）。

fn collab_resume_end_maps_to_item_completed_resume_agent()

作用：这个测试确认“恢复协作代理结束”这种内部事件，会被翻译成完成通知；如果目标代理没找到，状态应当是失败。

数据流：测试先造出一个 CollabResumeEndEvent，并把状态设为 NotFound，也就是没找到代理。它把事件送进 item_event_to_server_notification 后，期望得到一个 ItemCompleted 通知，里面的工具是 ResumeAgent，整体状态是 Failed，同时记录接收方代理的状态。

调用关系：它检查 item_event_to_server_notification 里恢复代理 end 分支的失败判断。这个测试很重要，因为如果 NotFound 被误当成成功，客户端就会以为代理恢复了，实际却没有。

调用图：调用 3 个内部函数（item_event_to_server_notification, from, new）；外部调用 3 个（assert_item_completed_server_notification, CollabResumeEnd, vec!）。

fn exec_command_output_delta_maps_to_command_execution_output_delta()

作用：这个测试确认命令执行过程中吐出的一小段输出，会被翻译成客户端可显示的命令输出增量通知。

数据流：测试构造一个 ExecCommandOutputDeltaEvent，里面的输出内容是字节形式的 hello。它调用 item_event_to_server_notification 后，期望得到 CommandExecutionOutputDelta 通知，并且 item_id 是调用 ID，delta 是字符串 hello。

调用关系：它验证 item_event_to_server_notification 处理命令输出的分支。这个分支会把原始字节转换成文字；测试通过 assert_command_execution_output_delta_server_notification 来确认转换后的通知类型和内容都正确。

调用图：调用 1 个内部函数（item_event_to_server_notification）；外部调用 2 个（assert_command_execution_output_delta_server_notification, ExecCommandOutputDelta）。

fn build_file_change_approval_request_item(
    payload: &ApplyPatchApprovalRequestEvent,
) -> ThreadItem

作用：把“申请修改文件、等待批准”的底层事件，做成一条客户端能显示的文件变更条目。用户还没批准时，界面也能先看到准备改哪些文件。

数据流：输入是一份 ApplyPatchApprovalRequestEvent，里面有调用编号和文件改动清单。函数把调用编号当作条目 id，把文件改动交给 convert_patch_changes 转成前端格式，并把状态设成 InProgress，也就是“进行中/等待中”。输出是一条 ThreadItem::FileChange，不会真正改文件，只是生成展示用数据。

调用关系：当 handle_apply_patch_approval_request 收到补丁审批请求时会调用它。它自己不整理每个文件的细节，而是把这部分交给 convert_patch_changes，保证审批阶段和真正执行阶段的文件展示格式一致。

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

fn build_file_change_begin_item(payload: &PatchApplyBeginEvent) -> ThreadItem

作用：把“开始应用文件补丁”的事件，做成一条文件变更条目。这样客户端能在补丁刚开始时立刻显示正在改哪些文件。

数据流：输入是 PatchApplyBeginEvent，包含调用编号和文件变化。函数复制 id，把文件变化转换成 FileUpdateChange 列表，并把状态标成 InProgress。输出是一个 ThreadItem::FileChange，表示这批文件改动正在发生。

调用关系：handle_patch_apply_begin 在收到补丁开始事件时会用它。它和审批请求的构造方式很像，都是调用 convert_patch_changes，所以界面不会因为事件来源不同而显示出两套格式。

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

fn build_file_change_end_item(payload: &PatchApplyEndEvent) -> ThreadItem

作用：把“文件补丁应用结束”的事件，做成最终版文件变更条目。它告诉客户端这次改文件是成功、失败，还是其他结束状态。

数据流：输入是 PatchApplyEndEvent，里面有调用编号、文件改动和底层状态。函数转换文件改动列表，再把底层状态换成 app-server 协议里的 PatchApplyStatus。输出是一条 ThreadItem::FileChange，状态不再固定为进行中，而是反映实际结束结果。

调用关系：handle_patch_apply_end 在补丁结束时调用它。它继续复用 convert_patch_changes 来生成文件清单，自己重点负责把“结束状态”带到 ThreadItem 里。

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

fn build_command_execution_approval_request_item(
    payload: &ExecApprovalRequestEvent,
) -> ThreadItem

作用：把“命令执行前需要审批”的请求，做成一条命令执行条目。即使命令还没真正运行，客户端也能先显示将要运行什么、在哪个目录运行。

数据流：输入是 ExecApprovalRequestEvent，包含命令参数、工作目录、调用编号和解析后的命令动作。函数用 shlex_join 把参数列表拼成一条人能读的命令字符串，把来源标成 Agent，把状态标成 InProgress，并把解析结果转换成 command_actions。输出是一条 ThreadItem::CommandExecution；进程号、输出、退出码和耗时都为空，因为命令还没开始。

调用关系：它服务于命令审批场景。它会调用 shlex_join 来把参数数组变成类似终端里看到的一行命令；命令动作则通过 CommandAction::from_core_with_cwd 转成客户端能展示的动作说明。

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

fn build_command_execution_begin_item(payload: &ExecCommandBeginEvent) -> ThreadItem

作用：把“命令开始执行”的事件，做成一条进行中的命令执行条目。客户端可以用它显示命令、目录、进程号和当前运行状态。

数据流：输入是 ExecCommandBeginEvent，包含命令参数、工作目录、进程号、来源和解析后的动作。函数拼出命令字符串，复制 cwd 和 process_id，把状态设为 InProgress，并转换 command_actions。输出是一条 ThreadItem::CommandExecution，输出、退出码和耗时暂时为空，因为命令还没结束。

调用关系：item_event_to_server_notification 和 handle_exec_command_begin 会在命令开始时调用它。它用 shlex_join 生成展示命令，并把已解析的命令动作转给 CommandAction::from_core_with_cwd，让客户端知道这条命令大概会做什么。

调用图：调用 1 个内部函数（shlex_join）；被 2 处调用（item_event_to_server_notification, handle_exec_command_begin）。

fn build_command_execution_end_item(payload: &ExecCommandEndEvent) -> ThreadItem

作用：把“命令执行结束”的事件，做成带结果的命令执行条目。它让客户端看到命令输出、退出码、耗时以及最终成功或失败状态。

数据流：输入是 ExecCommandEndEvent，包含命令、目录、进程号、状态、输出、退出码和运行时间。函数把空输出变成 None，避免显示没内容的输出框；把耗时从毫秒数转换成 i64，太大时用最大值兜底；再组装成 ThreadItem::CommandExecution。输出是一条完整的结束态命令记录。

调用关系：item_event_to_server_notification 和 handle_exec_command_end 会在命令结束时调用它。它调用 shlex_join 来生成可读命令，并使用 try_from 做耗时数值转换，防止时间数值超出协议字段能装下的范围。

调用图：调用 1 个内部函数（shlex_join）；被 2 处调用（item_event_to_server_notification, handle_exec_command_end）；外部调用 1 个（try_from）。

fn build_item_from_guardian_event(
    assessment: &GuardianAssessmentEvent,
    status: CommandExecutionStatus,
) -> Option<ThreadItem>

作用：把 Guardian 守护检查事件转成可显示的命令执行条目。Guardian 可以理解为一道自动安全检查门，它判断某个动作是否安全；这个函数让这类检查也能在会话里显示成用户看得懂的记录。

数据流：输入是 GuardianAssessmentEvent 和想要显示的命令状态。函数先看被检查的动作类型：如果是普通命令，就直接拿命令文本和目录生成 CommandExecution；如果是 execve，也就是更底层的“运行某个程序加参数”，它会把程序和参数重新拼成一条命令，并尝试解析出动作；如果是补丁、网络访问、工具调用、权限请求等非命令动作，就返回 None。输出可能是一条 ThreadItem，也可能什么都不生成。

调用关系：handle_guardian_assessment 在处理 Guardian 检查结果时调用它。它会用 shlex_join 拼命令，用 parse_command 尝试理解命令含义；如果理解不了，就退回到 Unknown 动作，至少保证界面还能显示原始命令。

调用图：调用 2 个内部函数（parse_command, shlex_join）；被 1 处调用（handle_guardian_assessment）；外部调用 2 个（once, vec!）。

fn guardian_auto_approval_review_notification(
    conversation_id: &ThreadId,
    event_turn_id: &str,
    assessment: &GuardianAssessmentEvent,
) -> ServerNotification

作用：把 Guardian 自动审批检查，包装成发给客户端的通知。它告诉客户端一次审批检查是开始了，还是已经批准、拒绝、超时或中止了。

数据流：输入是会话 id、当前事件的 turn id，以及 GuardianAssessmentEvent。函数先决定使用哪个 turn id：事件里有就用事件里的，没有就用传进来的。然后把底层状态、风险等级、用户授权、理由、动作等信息整理成 GuardianApprovalReview。最后按状态输出两类 ServerNotification：进行中就是 Started，结束状态就是 Completed，并补上完成时间和决策来源。

调用关系：它位于 Guardian 审批信息发给客户端之前的最后转换步骤。它会构造 ItemGuardianApprovalReviewStartedNotification 或 ItemGuardianApprovalReviewCompletedNotification，并把 ThreadId 转成字符串，方便协议传输。

调用图：外部调用 3 个（ItemGuardianApprovalReviewCompleted, ItemGuardianApprovalReviewStarted, to_string）。

fn convert_patch_changes(changes: &HashMap<PathBuf, FileChange>) -> Vec<FileUpdateChange>

作用：把底层的文件改动表，转成客户端需要的文件改动列表。它还会按文件路径排序，让同一批改动每次显示顺序都稳定。

数据流：输入是一个 HashMap，里面用文件路径对应具体 FileChange。函数逐个取出路径和改动，把路径转成字符串，把改动类型交给 map_patch_change_kind，把具体内容交给 format_file_change_diff，然后收集成 Vec<FileUpdateChange。最后按 path 排序并输出这个列表。

调用关系：它被 item_event_to_server_notification、build_file_change_approval_request_item、build_file_change_begin_item、build_file_change_end_item 和 from 等路径复用。它是文件变更展示格式的共同入口，避免不同地方各自转换导致显示不一致。

调用图：被 5 处调用（item_event_to_server_notification, build_file_change_approval_request_item, build_file_change_begin_item, build_file_change_end_item, from）。

fn map_patch_change_kind(change: &FileChange) -> PatchChangeKind

作用：判断一个文件改动到底是新增、删除，还是更新。更新时如果包含移动路径，也会把“移动到哪里”带上。

数据流：输入是一个 FileChange。函数匹配它的具体种类：Add 转成 PatchChangeKind::Add，Delete 转成 PatchChangeKind::Delete，Update 转成 PatchChangeKind::Update，并复制 move_path。输出是客户端协议里的改动类型。

调用关系：它是 convert_patch_changes 里的小零件，专门负责“改动类别”的翻译。convert_patch_changes 用它来给每个文件变更贴上正确标签。

fn format_file_change_diff(change: &FileChange) -> String

作用：把一个文件改动整理成适合显示的文本内容。新增和删除直接显示内容，更新则显示 diff，也就是对比前后差异的文本。

数据流：输入是 FileChange。新增文件时输出新增内容；删除文件时输出被删内容；更新文件时输出 unified_diff，如果这个更新还包含移动文件，就在 diff 后面追加一行“MOVED to”说明目标路径。输出是一个字符串，给客户端显示文件变化细节。

调用关系：它也是 convert_patch_changes 的内部帮手，负责“改动内容怎么写出来”。当文件移动时它会调用格式化字符串的能力，把移动目标补到 diff 后面，避免用户只看到内容变化却不知道文件被挪了地方。

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

async fn send_thread_token_usage_update_to_connection(
    outgoing: &Arc<OutgoingMessageSender>,
    connection_id: ConnectionId,
    thread_id: ThreadId,
    thread: &Thread,
    conversation: &Code

作用：把某个已有线程里保存过的 token 用量，补发给刚连接进来的那个客户端。它的重点是“只发给这个连接”，避免把历史统计误广播给其他正在看实时内容的人。

数据流：输入是发消息的通道、目标连接 id、线程 id、当前重建好的线程、底层对话对象，以及可能已经算好的用量所属轮次 id。它先向对话对象读取 token_usage_info；如果没有保存过用量，就直接不做事。如果有，就把线程 id 转成字符串，把用量转换成对外协议里的 ThreadTokenUsage，再包成 ThreadTokenUsageUpdatedNotification。最后通过 outgoing 把这个服务器通知发给指定连接，外部看到的结果就是该客户端收到一条补发的用量更新。

调用关系：它处在“客户端接入已有线程”的收尾位置：前面的流程决定是否允许补发、并准备好线程信息；这个函数负责真正组装通知并发出去。它会用 token_usage_info 读取保存的用量，用 ThreadTokenUsage::from 做协议格式转换，用 ThreadTokenUsageUpdatedNotification 形成客户端能懂的消息；如果调用方没有给出轮次 id，它会把选择轮次的工作交给 latest_token_usage_turn_id 做兜底。

调用图：调用 2 个内部函数（from, token_usage_info）；外部调用 2 个（ThreadTokenUsageUpdated, to_string）。

fn latest_token_usage_turn_id_from_rollout_items(
    rollout_items: &[RolloutItem],
    turns: &[Turn],
) -> Option<String>

作用：从一串历史记录里判断“最近一次 token 用量统计应该归到哪一轮对话”。这能让重连后的界面把用量显示在正确的回合上，而不是随便挂到最后一轮。

数据流：输入是保存下来的 rollout_items 历史记录，以及已经重建出来的 turns 轮次列表。它一边用 ThreadHistoryBuilder 重新走一遍历史，一边盯着 TokenCount 事件；每次遇到 TokenCount，就记下当时活跃轮次的 id 和位置。遍历结束后，它拿最后一次记录到的归属者来对照当前 turns：如果原 id 还存在，就返回这个 id；如果原 id 对不上，就用当时的位置去当前 turns 里取对应轮次的 id；如果这些信息都没有，就返回空。

调用关系：它是正常情况下最可靠的归属判断器，通常会在重放 token 用量前被上层流程使用。它通过 ThreadHistoryBuilder::new 建一个“历史复盘器”，用 builder 按顺序消化每条 rollout item；matches! 用来识别 TokenCount 这类用量统计事件。它不负责发通知，只负责告诉后续发送逻辑：这条用量应该挂在哪个 turn id 上。

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

fn latest_token_usage_turn_id(thread: &Thread) -> String

作用：在没法从历史记录准确判断归属时，选一个尽量合理的轮次 id 作为兜底。它保证补发通知的格式稳定，不至于因为缺少归属信息就发不出去。

数据流：输入是当前线程对象。它从后往前找最后一个已经完成或失败的轮次；如果找不到，就用线程里的最后一轮；如果线程连一轮都没有，就返回空字符串。输出是一个字符串形式的 turn id，不会修改任何数据。

调用关系：它是 send_thread_token_usage_update_to_connection 的备选方案：当调用方没有提前算好 token_usage_turn_id 时，就由它临时挑一个最可能合适的轮次。正常流程更偏向使用 latest_token_usage_turn_id_from_rollout_items，因为那个函数能根据历史位置判断得更准；这个函数负责异常情况下的保底。

fn replay_attribution_uses_already_loaded_history()

作用：这个测试确认：如果历史记录里的轮次 id 和重建后的轮次 id 能对上，token 用量就应该归到原来的那一轮。

数据流：它先用 token_usage_history 造出一段包含用户消息、助手回复、TokenCount 和下一轮用户消息的假历史。然后用 build_turns_from_rollout_items 把历史重建成轮次列表。接着调用 latest_token_usage_turn_id_from_rollout_items，最后用 assert_eq! 检查返回值是不是第一轮的 id。

调用关系：它是对 latest_token_usage_turn_id_from_rollout_items 的基础场景验证。token_usage_history 提供固定样本，build_turns_from_rollout_items 模拟真实的线程重建过程，assert_eq! 负责确认归属判断没有偏到后面的轮次。

调用图：外部调用 3 个（token_usage_history, assert_eq!, build_turns_from_rollout_items）。

fn replay_attribution_falls_back_to_rebuilt_turn_position()

作用：这个测试确认：如果重建后轮次 id 变了，系统仍然能靠“当时是第几轮”把 token 用量归到正确轮次。

数据流：它先生成同样的假历史，并重建出轮次列表。然后故意把第一轮的 id 改成 rebuilt-turn-id，模拟历史 id 和现在线程 id 对不上的情况。接着调用 latest_token_usage_turn_id_from_rollout_items，最后检查结果是不是改过后的第一轮 id。

调用关系：它验证的是 latest_token_usage_turn_id_from_rollout_items 的容错能力。这个测试说明该函数不是死认旧 id，而是在 id 对不上时会使用保存下来的轮次位置来找当前对应的轮次，这正是文件开头注释里强调的重要行为。

调用图：外部调用 3 个（token_usage_history, assert_eq!, build_turns_from_rollout_items）。

fn token_usage_history() -> Vec<RolloutItem>

作用：给测试准备一段很小但有代表性的对话历史。里面故意把 TokenCount 放在第一轮回答之后、第二轮开始之前，方便检查用量到底会归到哪一轮。

数据流：它不需要输入。它用 vec! 组装四条历史项：第一条用户消息、第一条助手消息、一条 TokenCount 用量统计、第二条用户消息。输出是一组 RolloutItem，供测试函数拿去重建线程和验证归属。

调用关系：它是两个测试共用的样本制造器。replay_attribution_uses_already_loaded_history 和 replay_attribution_falls_back_to_rebuilt_turn_position 都先调用它拿到同一段历史，这样两个测试只改变“轮次 id 是否对得上”这个条件，便于准确验证归属逻辑。

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

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

作用：把保存下来的 rollout 条目重新拼成完整的对话回合列表。常用于恢复历史记录或测试历史重建是否正确。

数据流：输入是一串 RolloutItem → 新建一个 ThreadHistoryBuilder，逐条喂给它 → 输出整理好的 Vec<Turn>，每个 Turn 都包含这一轮的可展示内容和状态。

调用关系：它是最外层的便捷入口，内部把实际工作交给 ThreadHistoryBuilder::handle_rollout_item，最后用 ThreadHistoryBuilder::finish 收尾；大量测试都通过它验证重放历史的结果。

调用图：调用 1 个内部函数（new）；被 29 处调用（assigns_late_exec_completion_to_original_turn, drops_last_turns_on_thread_rollback, error_then_turn_complete_preserves_failed_status, ignores_plain_user_response_items_in_rollout_replay, ignores_user_message_item_lifecycle_events, late_turn_aborted_does_not_interrupt_active_turn, late_turn_complete_does_not_close_active_turn, marks_turn_as_interrupted_when_aborted, out_of_turn_error_does_not_create_or_fail_a_turn, preserves_agent_message_phase_in_history (+15 more)）。

fn is_empty(&self) -> bool

作用：判断一次处理后到底有没有任何变化。外部可以用它决定要不要通知界面刷新。

数据流：读取 changed_items、changed_turns、removed_turn_ids 三个列表 → 看它们是否都为空 → 返回 true 或 false，不修改数据。

调用关系：它服务于增量更新流程，是 ThreadHistoryChangeSet 的小工具；谁拿到变更集后都可以用它快速跳过空更新。

fn from_pending_turn(turn: &PendingTurn) -> Self

作用：把还没正式收尾的 PendingTurn，摘出一份轻量的回合状态快照。

数据流：输入一个 PendingTurn 引用 → 复制它的 id、状态、错误和时间信息 → 输出 ThreadHistoryTurnChange。

调用关系：record_changed_pending_turn 会用它，把正在进行的回合变化记进增量变更集。

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

fn from_turn(turn: &Turn) -> Self

作用：把已经完成保存的 Turn，转成一份轻量状态快照。

数据流：输入一个 Turn 引用 → 复制回合 id、状态、错误和时间字段 → 输出 ThreadHistoryTurnChange。

调用关系：当已结束的回合后来又收到完成或中断事件时，handle_turn_aborted 和 handle_turn_complete 会用它记录变化。

调用图：被 2 处调用（handle_turn_aborted, handle_turn_complete）。

fn push(&mut self, changes: ThreadHistoryChangeSet)

作用：把一次又一次的小变更合并进批量变更收集器里。

数据流：输入一个 ThreadHistoryChangeSet → 先处理被删除的回合，再处理条目变化和回合变化 → 更新内部累计列表。

调用关系：handle_rollout_items_with_changes 在批量处理 rollout 条目时反复调用它；它把细活分给 push_removed_turn_id、push_item_change、push_turn_change。

调用图：调用 3 个内部函数（push_item_change, push_removed_turn_id, push_turn_change）。

fn finish(self) -> ThreadHistoryChangeSet

作用：结束累计，把内部临时结构变成最终能发给外部的变更集。

数据流：读取内部列表，丢掉已经被标空的旧变化 → 输出 ThreadHistoryChangeSet。

调用关系：handle_rollout_items_with_changes 在所有条目处理完后调用它，拿到去重后的最终结果。

fn push_item_change(&mut self, change: ThreadHistoryItemChange)

作用：记录某个回合里某个条目的最新样子；如果同一条目重复变化，只保留最后一次。

数据流：输入 ThreadHistoryItemChange → 用“回合 id + 条目 id”查旧位置 → 有旧的就覆盖，没有就追加。

调用关系：只由 ThreadHistoryChangeAccumulator::push 调用，负责批量增量更新里的条目去重。

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

fn push_turn_change(&mut self, change: ThreadHistoryTurnChange)

作用：记录某个回合状态的最新样子；同一回合多次变化时只保留最后一次。

数据流：输入 ThreadHistoryTurnChange → 按 turn_id 查旧位置 → 覆盖或追加内部列表。

调用关系：只由 ThreadHistoryChangeAccumulator::push 调用，负责把回合开始、完成、失败等状态压缩成最终快照。

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

fn push_removed_turn_id(&mut self, turn_id: String)

作用：记录某个回合被回滚删除，并清掉之前为这个回合累计的无效变化。

数据流：输入 turn_id → 加入删除列表并去重 → 移除这个回合相关的条目变化和回合变化。

调用关系：ThreadHistoryChangeAccumulator::push 遇到删除回合时调用它，保证外部不会先收到“新增回合”又收到同一回合的过期内容。

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

fn default() -> Self

作用：提供默认创建方式，等同于新建一个空的历史构建器。

数据流：没有输入 → 调用 ThreadHistoryBuilder::new → 得到初始状态的 builder。

调用关系：让这个类型能用 Rust 的 Default 习惯创建；实际初始化逻辑集中在 new。

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

fn new() -> Self

作用：创建一个空的历史构建器，准备从第一条事件开始整理对话历史。

数据流：没有输入 → 初始化空回合列表、空当前回合、条目编号和 rollout 位置 → 输出 ThreadHistoryBuilder。

调用关系：build_turns_from_rollout_items 和很多测试都会先调用它；后续所有 handle_* 方法都在这个状态上工作。

调用图：被 15 处调用（build_turns_from_rollout_items, apply_patch_approval_request_updates_active_turn_snapshot_with_file_change, builds_multiple_turns_with_reasoning_items, changed_rollout_item_reports_new_item_snapshot, changed_rollout_item_reports_streaming_item_mutation, changed_rollout_item_reports_turn_completion_metadata, changed_rollout_item_reports_updated_existing_item_snapshot, changed_rollout_items_dedupe_turn_metadata_snapshots, changed_rollout_items_dedupe_updated_item_snapshots, changed_rollout_items_drop_prior_changes_for_removed_turns (+5 more)）；外部调用 1 个（new）。

fn reset(&mut self)

作用：把构建器清空，回到刚创建时的状态。

数据流：输入当前 builder → 用新的空 builder 覆盖自己 → 之前累积的历史和当前回合都被丢弃。

调用关系：clear_listener、track_current_turn_event 等外部流程在需要重新跟踪历史时会调用它。

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

fn finish(mut self) -> Vec<Turn>

作用：结束历史构建，拿到最终的回合列表。

数据流：输入 builder 自身 → 先把还开着的当前回合收尾 → 输出 Vec<Turn>。

调用关系：build_turns_from_rollout_items 最后会调用它；内部依赖 finish_current_turn 避免漏掉最后一轮。

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

fn active_turn_snapshot(&self) -> Option<Turn>

作用：拿到当前活跃回合的快照；如果没有活跃回合，就拿最后一个已完成回合。

数据流：读取 current_turn 和 turns → 克隆出一个 Turn → 返回 Option<Turn>，不改变内部状态。

调用关系：外部想显示“当前这一轮”的即时状态时会用它，测试也用它确认文件修改等事件已进入当前回合。

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

fn turn_snapshot(&self, turn_id: &str) -> Option<Turn>

作用：按回合 id 查询某一轮的完整快照。

数据流：输入 turn_id → 先看当前回合，再看已完成列表 → 找到就克隆 Turn 返回，否则返回 None。

调用关系：这是给外部按需读取单个回合的查询接口，不参与事件写入流程。

fn active_turn_position(&self) -> Option<usize>

作用：告诉外部当前活跃回合在最终列表里会排第几个。

数据流：读取 current_turn 和已完成 turns 的长度 → 算出索引位置 → 返回 Option<usize>。

调用关系：用于界面或投影器定位活跃回合；它只看状态，不创建或修改回合。

fn has_active_turn(&self) -> bool

作用：判断现在是否有一个正在打开的回合。

数据流：读取 current_turn 是否为 Some → 返回布尔值。

调用关系：track_current_turn_event 会用它决定当前是否已经在跟踪一轮对话。

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

fn active_turn_id_if_explicit(&self) -> Option<String>

作用：如果当前回合是由明确的 turn_started 打开的，就返回它的 id。

数据流：读取 current_turn → 检查 opened_explicitly 标记 → 符合就复制 id 返回，否则返回 None。

调用关系：帮助外部区分新协议里的明确回合和旧日志里临时推断出来的回合。

fn active_turn_start_index(&self) -> Option<usize>

作用：返回当前回合从第几个 rollout 条目开始。

数据流：读取 current_turn 的 rollout_start_index → 返回 Option<usize>。

调用关系：用于恢复、重连或定位增量历史时知道这一轮从日志哪里开始。

fn handle_event(&mut self, event: &EventMsg)

作用：这是事件分发中心：看到不同种类的 EventMsg，就交给对应的小处理函数。

数据流：输入一条 EventMsg → 按类型匹配，比如用户消息、工具开始、工具结束、回合完成等 → 修改 builder 里的回合和条目。

调用关系：handle_rollout_item 和 track_current_turn_event 会调用它；它把具体工作交给 handle_user_message、handle_exec_command_end 等众多专门函数。

调用图：调用 40 个内部函数（handle_agent_message, handle_agent_reasoning, handle_agent_reasoning_raw_content, handle_apply_patch_approval_request, handle_collab_agent_interaction_begin, handle_collab_agent_interaction_end, handle_collab_agent_spawn_begin, handle_collab_agent_spawn_end, handle_collab_close_begin, handle_collab_close_end (+15 more)）；被 2 处调用（handle_rollout_item, track_current_turn_event）。

fn handle_rollout_item(&mut self, item: &RolloutItem)

作用：处理保存日志里的一个条目，并维护当前处理到日志第几个位置。

数据流：输入 RolloutItem → 更新 rollout 索引 → 如果是事件就交给 handle_event，如果是压缩或响应项就走对应处理，否则忽略。

调用关系：build_turns_from_rollout_items 会逐条调用它；它是持久化日志重放进入 builder 的主要入口。

调用图：调用 3 个内部函数（handle_compacted, handle_event, handle_response_item）。

fn handle_event_with_changes(&mut self, event: &EventMsg) -> ThreadHistoryChangeSet

作用：处理一条事件，同时返回这条事件造成了哪些可见变化。

数据流：输入 EventMsg → 开启变更收集 → 调用 handle_event → 输出 ThreadHistoryChangeSet。

调用关系：它把普通事件处理包装进 collect_changes，适合实时同步界面时使用。

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

fn handle_rollout_item_with_changes(
        &mut self,
        item: &RolloutItem,
    ) -> ThreadHistoryChangeSet

作用：处理一个 rollout 条目，并告诉调用方这个条目让历史哪里变了。

数据流：输入 RolloutItem → 开启变更收集 → 调用 handle_rollout_item → 返回新增、更新或删除的变化。

调用关系：handle_rollout_items_with_changes 会反复调用它，单条增量处理也可以直接用它。

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

fn handle_rollout_items_with_changes(
        &mut self,
        items: &[RolloutItem],
    ) -> ThreadHistoryChangeSet

作用：批量处理多条 rollout 条目，并把重复变化合并成最后结果。

数据流：输入 RolloutItem 切片 → 每条都调用 handle_rollout_item_with_changes → 用 ThreadHistoryChangeAccumulator 去重 → 输出最终变更集。

调用关系：用于一次追加多条日志时，避免外部收到同一条目多次中间状态。

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

fn collect_changes(&mut self, handle: impl FnOnce(&mut Self)) -> ThreadHistoryChangeSet

作用：临时打开“记录变化”模式，运行一段处理逻辑后收集结果。

数据流：输入一个闭包 → 放入空的 active_change_set → 执行闭包 → 取出并返回收集到的 ThreadHistoryChangeSet。

调用关系：handle_event_with_changes 和 handle_rollout_item_with_changes 都靠它实现增量变化收集。

调用图：被 2 处调用（handle_event_with_changes, handle_rollout_item_with_changes）；外部调用 2 个（default, debug_assert!）。

fn handle_response_item(&mut self, item: &codex_protocol::models::ResponseItem)

作用：从模型响应项里识别特殊的 hook 提示，并把它放进当前回合。

数据流：输入 ResponseItem → 只接受用户角色的消息 → 尝试解析 hook prompt → 成功后生成 ThreadItem::HookPrompt 并加入当前回合。

调用关系：handle_rollout_item 遇到 RolloutItem::ResponseItem 时调用它；它依赖 parse_hook_prompt_message 识别特殊格式。

调用图：调用 2 个内部函数（push_item_in_current_turn, parse_hook_prompt_message）；被 1 处调用（handle_rollout_item）。

fn handle_user_message(&mut self, payload: &UserMessageEvent)

作用：把用户输入变成历史里的用户消息条目。

数据流：输入 UserMessageEvent → 必要时结束旧的隐式回合 → 生成新 item id，整理文字和图片 → 推入当前回合。

调用关系：handle_event 收到 UserMessage 时调用它；它会用 build_user_inputs、next_item_id 和 push_item_in_current_turn。

调用图：调用 4 个内部函数（build_user_inputs, finish_current_turn, next_item_id, push_item_in_current_turn）；被 1 处调用（handle_event）。

fn handle_agent_message(
        &mut self,
        text: String,
        phase: Option<MessagePhase>,
        memory_citation: Option<crate::protocol::v2::MemoryCitation>,
    )

作用：把模型给用户看的回复加入当前回合。

数据流：输入文本、阶段和记忆引用 → 空文本直接忽略 → 分配 item id → 生成 AgentMessage 条目放入当前回合。

调用关系：handle_event 收到 AgentMessage 时调用它；它把新增条目的实际写入交给 push_item_in_current_turn。

调用图：调用 2 个内部函数（next_item_id, push_item_in_current_turn）；被 1 处调用（handle_event）。

fn handle_agent_reasoning(&mut self, payload: &AgentReasoningEvent)

作用：记录模型的“思考摘要”，并尽量合并到上一条思考条目里。

数据流：输入 AgentReasoningEvent → 空文本忽略 → 如果最后一条已经是 Reasoning，就追加 summary；否则新建 Reasoning 条目。

调用关系：handle_event 调用它；在增量模式下，它会用 record_changed_item 报告被追加的思考条目变化。

调用图：调用 5 个内部函数（ensure_turn, is_tracking_changes, next_item_id, push_item_in_current_turn, record_changed_item）；被 1 处调用（handle_event）；外部调用 2 个（new, vec!）。

fn handle_agent_reasoning_raw_content(&mut self, payload: &AgentReasoningRawContentEvent)

作用：记录模型的原始思考内容，并合并到上一条思考条目。

数据流：输入 AgentReasoningRawContentEvent → 空文本忽略 → 最后一条是 Reasoning 就追加 content，否则新建 Reasoning 条目。

调用关系：handle_event 调用它；它和 handle_agent_reasoning 配合，把摘要和原文放在同一个思考条目中。

调用图：调用 5 个内部函数（ensure_turn, is_tracking_changes, next_item_id, push_item_in_current_turn, record_changed_item）；被 1 处调用（handle_event）；外部调用 2 个（new, vec!）。

fn handle_item_started(&mut self, payload: &ItemStartedEvent)

作用：处理某些“条目开始了”的生命周期事件，目前主要恢复计划和睡眠条目。

数据流：输入 ItemStartedEvent → 如果是非空 Plan 或 Sleep，就转成 ThreadItem → 按 turn_id 插入或更新对应回合。

调用关系：handle_event 收到 ItemStarted 时调用它；多数其他条目类型已有更专门的事件处理，所以这里会忽略。

调用图：调用 2 个内部函数（upsert_item_in_turn_id, from）；被 1 处调用（handle_event）。

fn handle_item_completed(&mut self, payload: &ItemCompletedEvent)

作用：处理某些“条目完成了”的生命周期事件，用完成态内容更新历史。

数据流：输入 ItemCompletedEvent → 对非空 Plan 或 Sleep 转成 ThreadItem → 按 turn_id upsert 到对应回合。

调用关系：handle_event 收到 ItemCompleted 时调用它；它和 handle_item_started 保持同类条目在历史中可恢复。

调用图：调用 2 个内部函数（upsert_item_in_turn_id, from）；被 1 处调用（handle_event）。

fn handle_web_search_begin(&mut self, payload: &WebSearchBeginEvent)

作用：在历史里放入一个正在进行的网页搜索占位条目。

数据流：输入 WebSearchBeginEvent → 用 call_id 做条目 id，query 先为空 → 插入或更新当前回合。

调用关系：handle_event 收到 WebSearchBegin 时调用；后续 handle_web_search_end 会用同一 id 更新成完整结果。

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

fn handle_web_search_end(&mut self, payload: &WebSearchEndEvent)

作用：把网页搜索的最终查询和动作写入历史。

数据流：输入 WebSearchEndEvent → 生成带 query 和 action 的 WebSearch 条目 → 用 call_id 更新当前回合里的搜索条目。

调用关系：handle_event 收到 WebSearchEnd 时调用；它通常覆盖 handle_web_search_begin 先放进去的占位条目。

调用图：调用 2 个内部函数（upsert_item_in_current_turn, from）；被 1 处调用（handle_event）。

fn handle_exec_command_begin(&mut self, payload: &ExecCommandBeginEvent)

作用：记录一条命令开始执行，让历史里能看到工具正在跑。

数据流：输入 ExecCommandBeginEvent → 用构建函数转成命令执行条目 → 按事件里的 turn_id 放进对应回合。

调用关系：handle_event 调用它；具体字段转换交给 build_command_execution_begin_item，放置交给 upsert_item_in_turn_id。

调用图：调用 2 个内部函数（build_command_execution_begin_item, upsert_item_in_turn_id）；被 1 处调用（handle_event）。

fn handle_exec_command_end(&mut self, payload: &ExecCommandEndEvent)

作用：记录命令执行结束，包括输出、退出码和耗时。

数据流：输入 ExecCommandEndEvent → 转成完整的命令执行条目 → 按 turn_id 更新原来的回合，而不是盲目放进当前回合。

调用关系：handle_event 调用它；这样即使命令结果晚到，也会回到原始回合，不会串到新用户回合里。

调用图：调用 2 个内部函数（build_command_execution_end_item, upsert_item_in_turn_id）；被 1 处调用（handle_event）。

fn handle_guardian_assessment(&mut self, payload: &GuardianAssessmentEvent)

作用：把安全审查事件转成用户能看懂的命令或操作状态。

数据流：输入 GuardianAssessmentEvent → 把审查状态映射成执行状态 → 构建 ThreadItem → 按 turn_id 或当前回合插入更新。

调用关系：handle_event 调用它；Approved 审查不会生成条目，其他状态交给 build_item_from_guardian_event 转换。

调用图：调用 3 个内部函数（build_item_from_guardian_event, upsert_item_in_current_turn, upsert_item_in_turn_id）；被 1 处调用（handle_event）。

fn handle_apply_patch_approval_request(&mut self, payload: &ApplyPatchApprovalRequestEvent)

作用：记录一次文件修改需要审批的请求。

数据流：输入 ApplyPatchApprovalRequestEvent → 构造成 FileChange 条目 → 有 turn_id 就放到指定回合，否则放当前回合。

调用关系：handle_event 调用它；后续 patch begin/end 可能用同一 id 更新文件变更状态。

调用图：调用 3 个内部函数（build_file_change_approval_request_item, upsert_item_in_current_turn, upsert_item_in_turn_id）；被 1 处调用（handle_event）。

fn handle_patch_apply_begin(&mut self, payload: &PatchApplyBeginEvent)

作用：记录文件补丁开始应用，显示文件改动正在进行。

数据流：输入 PatchApplyBeginEvent → 转成进行中的 FileChange 条目 → 按 turn_id 或当前回合插入更新。

调用关系：handle_event 调用它；转换细节由 build_file_change_begin_item 处理。

调用图：调用 3 个内部函数（build_file_change_begin_item, upsert_item_in_current_turn, upsert_item_in_turn_id）；被 1 处调用（handle_event）。

fn handle_patch_apply_end(&mut self, payload: &PatchApplyEndEvent)

作用：记录文件补丁应用结束，显示成功、失败或被拒绝后的文件变更结果。

数据流：输入 PatchApplyEndEvent → 转成最终 FileChange 条目 → 更新指定回合或当前回合。

调用关系：handle_event 调用它；它和 handle_patch_apply_begin 使用同一 upsert 机制，保证同一个补丁条目被更新而不是重复出现。

调用图：调用 3 个内部函数（build_file_change_end_item, upsert_item_in_current_turn, upsert_item_in_turn_id）；被 1 处调用（handle_event）。

fn handle_dynamic_tool_call_request(
        &mut self,
        payload: &codex_protocol::dynamic_tools::DynamicToolCallRequest,
    )

作用：记录一次动态工具调用刚发起，状态为进行中。

数据流：输入 DynamicToolCallRequest → 取调用 id、命名空间、工具名和参数 → 生成 InProgress 的 DynamicToolCall 条目。

调用关系：handle_event 调用它；后续 handle_dynamic_tool_call_response 会用同一 call_id 更新结果。

调用图：调用 2 个内部函数（upsert_item_in_current_turn, upsert_item_in_turn_id）；被 1 处调用（handle_event）。

fn handle_dynamic_tool_call_response(&mut self, payload: &DynamicToolCallResponseEvent)

作用：记录动态工具调用的返回结果和耗时。

数据流：输入 DynamicToolCallResponseEvent → 根据 success 判定完成或失败，转换内容项和耗时 → 更新对应 DynamicToolCall 条目。

调用关系：handle_event 调用它；内容转换交给 convert_dynamic_tool_content_items，放置交给 upsert 方法。

调用图：调用 3 个内部函数（upsert_item_in_current_turn, upsert_item_in_turn_id, convert_dynamic_tool_content_items）；被 1 处调用（handle_event）；外部调用 1 个（try_from）。

fn handle_mcp_tool_call_begin(&mut self, payload: &McpToolCallBeginEvent)

作用：记录 MCP 工具调用开始。MCP 是一种让模型调用外部工具的协议。

数据流：输入 McpToolCallBeginEvent → 取服务器、工具名、参数等 → 创建 InProgress 的 McpToolCall 条目放入当前回合。

调用关系：handle_event 调用它；结束事件会由 handle_mcp_tool_call_end 更新这个条目。

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

fn handle_mcp_tool_call_end(&mut self, payload: &McpToolCallEndEvent)

作用：记录 MCP 工具调用结束，并保存结果或错误。

数据流：输入 McpToolCallEndEvent → 判断成功失败，换算耗时，拆出 result 或 error → 更新当前回合里的 McpToolCall 条目。

调用关系：handle_event 调用它；它用 call_id 覆盖开始时的占位状态。

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

fn handle_view_image_tool_call(&mut self, payload: &ViewImageToolCallEvent)

作用：记录模型查看了一张本地或远程图片。

数据流：输入 ViewImageToolCallEvent → 用 call_id 和路径创建 ImageView 条目 → 插入或更新当前回合。

调用关系：handle_event 调用它；这是图片查看工具在历史里的展示入口。

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

fn handle_image_generation_begin(&mut self, payload: &ImageGenerationBeginEvent)

作用：记录图片生成开始，先放一个空结果的占位条目。

数据流：输入 ImageGenerationBeginEvent → 用 call_id 创建 ImageGeneration 条目，状态和结果暂为空 → 放进当前回合。

调用关系：handle_event 调用它；handle_image_generation_end 后续会补上结果。

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

fn handle_image_generation_end(&mut self, payload: &ImageGenerationEndEvent)

作用：记录图片生成完成后的状态、结果和保存路径。

数据流：输入 ImageGenerationEndEvent → 复制状态、修订提示词、结果和文件路径 → 更新当前回合的图片生成条目。

调用关系：handle_event 调用它；它通常覆盖 begin 阶段的占位条目。

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

fn handle_collab_agent_spawn_begin(
        &mut self,
        payload: &codex_protocol::protocol::CollabAgentSpawnBeginEvent,
    )

作用：记录开始创建一个协作子代理。子代理可以理解成被主对话派出去干活的助手。

数据流：输入 CollabAgentSpawnBeginEvent → 保存发送方、提示词、模型和推理力度 → 创建进行中的协作工具条目。

调用关系：handle_event 调用它；spawn end 会用同一 call_id 更新创建结果和子代理状态。

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

fn handle_collab_agent_spawn_end(
        &mut self,
        payload: &codex_protocol::protocol::CollabAgentSpawnEndEvent,
    )

作用：记录创建协作子代理的最终结果。

数据流：输入 CollabAgentSpawnEndEvent → 看是否拿到新线程 id 和状态 → 生成完成或失败的 CollabAgentToolCall 条目。

调用关系：handle_event 调用它；它把 AgentStatus 转成 CollabAgentState，展示新子代理是否运行、失败或不存在。

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

fn handle_collab_agent_interaction_begin(
        &mut self,
        payload: &codex_protocol::protocol::CollabAgentInteractionBeginEvent,
    )

作用：记录开始给某个协作代理发送输入。

数据流：输入 CollabAgentInteractionBeginEvent → 保存发送方、接收方和 prompt → 创建进行中的 SendInput 条目。

调用关系：handle_event 调用它；interaction end 会补上接收方代理的最终状态。

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

fn handle_collab_agent_interaction_end(
        &mut self,
        payload: &codex_protocol::protocol::CollabAgentInteractionEndEvent,
    )

作用：记录给协作代理发送输入后的结果。

数据流：输入 CollabAgentInteractionEndEvent → 根据状态判断工具调用成功或失败 → 写入接收方代理状态和 prompt。

调用关系：handle_event 调用它；它把协作代理反馈转成前端可展示的 CollabAgentToolCall。

调用图：调用 2 个内部函数（upsert_item_in_current_turn, from）；被 1 处调用（handle_event）；外部调用 1 个（vec!）。

fn handle_sub_agent_activity(
        &mut self,
        payload: &codex_protocol::protocol::SubAgentActivityEvent,
    )

作用：记录子代理发生的一条活动，比如某个代理有了动作或状态变化。

数据流：输入 SubAgentActivityEvent → 取事件 id、活动类型、代理线程 id 和路径 → 生成 SubAgentActivity 条目。

调用关系：handle_event 调用它；它把子代理自身活动加入主回合历史。

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

fn handle_collab_waiting_begin(
        &mut self,
        payload: &codex_protocol::protocol::CollabWaitingBeginEvent,
    )

作用：记录主代理开始等待一个或多个协作代理。

数据流：输入 CollabWaitingBeginEvent → 收集接收方线程 id → 创建进行中的 Wait 协作工具条目。

调用关系：handle_event 调用它；waiting end 会更新等待结果和各代理状态。

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

fn handle_collab_waiting_end(
        &mut self,
        payload: &codex_protocol::protocol::CollabWaitingEndEvent,
    )

作用：记录等待协作代理结束，并整理每个代理的状态。

数据流：输入 CollabWaitingEndEvent → 如果任何代理错误或找不到则标为失败，否则完成 → 排序接收方 id 并保存状态表。

调用关系：handle_event 调用它；它更新 begin 阶段创建的 Wait 条目。

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

fn handle_collab_close_begin(
        &mut self,
        payload: &codex_protocol::protocol::CollabCloseBeginEvent,
    )

作用：记录开始关闭一个协作代理。

数据流：输入 CollabCloseBeginEvent → 保存发送方和要关闭的接收方 → 创建进行中的 CloseAgent 条目。

调用关系：handle_event 调用它；close end 会写入关闭结果。

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

fn handle_collab_close_end(&mut self, payload: &codex_protocol::protocol::CollabCloseEndEvent)

作用：记录关闭协作代理后的成功或失败状态。

数据流：输入 CollabCloseEndEvent → 根据 AgentStatus 判断工具调用状态 → 保存接收方代理最终状态。

调用关系：handle_event 调用它；它把关闭操作的结果更新到当前回合。

调用图：调用 2 个内部函数（upsert_item_in_current_turn, from）；被 1 处调用（handle_event）；外部调用 1 个（vec!）。

fn handle_collab_resume_begin(
        &mut self,
        payload: &codex_protocol::protocol::CollabResumeBeginEvent,
    )

作用：记录开始恢复一个协作代理。

数据流：输入 CollabResumeBeginEvent → 保存发送方和接收方线程 id → 创建进行中的 ResumeAgent 条目。

调用关系：handle_event 调用它；resume end 会补充恢复结果。

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

fn handle_collab_resume_end(
        &mut self,
        payload: &codex_protocol::protocol::CollabResumeEndEvent,
    )

作用：记录恢复协作代理后的结果。

数据流：输入 CollabResumeEndEvent → 根据代理状态判断完成或失败 → 写入接收方代理状态。

调用关系：handle_event 调用它；相关测试确认它能从日志里重建恢复代理的历史条目。

调用图：调用 2 个内部函数（upsert_item_in_current_turn, from）；被 1 处调用（handle_event）；外部调用 1 个（vec!）。

fn handle_context_compacted(&mut self, _payload: &ContextCompactedEvent)

作用：记录上下文被压缩这件事。上下文压缩就是把长历史变短，方便模型继续处理。

数据流：输入 ContextCompactedEvent → 分配 item id → 放入 ContextCompaction 条目。

调用关系：handle_event 调用它；如果是持久化的 CompactedItem，则由 handle_compacted 记录保留回合的标记。

调用图：调用 2 个内部函数（next_item_id, push_item_in_current_turn）；被 1 处调用（handle_event）。

fn handle_entered_review_mode(&mut self, payload: &codex_protocol::protocol::ReviewRequest)

作用：记录系统进入代码审查模式，并显示给用户的提示。

数据流：输入 ReviewRequest → 取 user_facing_hint，缺省时用固定文案 → 生成 EnteredReviewMode 条目。

调用关系：handle_event 调用它；它通过 push_item_in_current_turn 把审查入口放进历史。

调用图：调用 2 个内部函数（next_item_id, push_item_in_current_turn）；被 1 处调用（handle_event）。

fn handle_exited_review_mode(
        &mut self,
        payload: &codex_protocol::protocol::ExitedReviewModeEvent,
    )

作用：记录退出审查模式，并展示审查输出或兜底错误文案。

数据流：输入 ExitedReviewModeEvent → 如果有 review_output 就渲染文字，否则用 fallback → 生成 ExitedReviewMode 条目。

调用关系：handle_event 调用它；文本整理由 render_review_output_text 完成。

调用图：调用 2 个内部函数（next_item_id, push_item_in_current_turn）；被 1 处调用（handle_event）。

fn handle_error(&mut self, payload: &ErrorEvent)

作用：把会影响当前回合的错误标到回合状态上。

数据流：输入 ErrorEvent → 先判断这个错误是否影响回合 → 如果当前有回合，就设为 Failed 并保存错误信息。

调用关系：handle_event 调用它；在增量模式下会通过 record_changed_turn 通知外部回合失败。

调用图：调用 3 个内部函数（is_tracking_changes, record_changed_turn, affects_turn_status）；被 1 处调用（handle_event）。

fn handle_turn_aborted(&mut self, payload: &TurnAbortedEvent)

作用：处理某一轮被中断的事件。

数据流：输入 TurnAbortedEvent → 优先按 turn_id 找当前或已完成回合 → 标记 Interrupted 并写入结束时间和耗时。

调用关系：handle_event 调用它；如果事件没带 id 或找不到，才退回处理当前回合，避免误伤新回合。

调用图：调用 2 个内部函数（record_changed_turn, from_turn）；被 1 处调用（handle_event）。

fn handle_turn_started(&mut self, payload: &TurnStartedEvent)

作用：处理明确的一轮对话开始。

数据流：输入 TurnStartedEvent → 先结束旧当前回合 → 用给定 turn_id 创建 InProgress 回合并记录开始时间 → 设置为当前回合。

调用关系：handle_event 调用它；它用 new_turn、record_changed_pending_turn 和 finish_current_turn 建立清晰回合边界。

调用图：调用 3 个内部函数（finish_current_turn, new_turn, record_changed_pending_turn）；被 1 处调用（handle_event）。

fn handle_turn_complete(&mut self, payload: &TurnCompleteEvent)

作用：处理一轮对话完成。

数据流：输入 TurnCompleteEvent → 优先匹配当前回合 id 并标完成，然后收尾；若是已完成回合的迟到事件，就只更新那个回合。

调用关系：handle_event 调用它；它特别防止迟到的完成事件关闭错误的当前回合。

调用图：调用 3 个内部函数（finish_current_turn, record_changed_turn, from_turn）；被 1 处调用（handle_event）；外部调用 1 个（matches!）。

fn handle_compacted(&mut self, _payload: &CompactedItem)

作用：记录日志里出现了压缩标记，即使这一轮没有可展示条目也要保留。

数据流：输入 CompactedItem → 确保有当前回合 → 把 saw_compaction 标记设为 true。

调用关系：handle_rollout_item 遇到 RolloutItem::Compacted 时调用它；finish_current_turn 会根据这个标记决定不丢掉空回合。

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

fn handle_thread_rollback(&mut self, payload: &ThreadRolledBackEvent)

作用：处理线程回滚，也就是删掉最后若干轮历史。

数据流：输入 ThreadRolledBackEvent → 先收尾当前回合 → 算出要删除的回合 id 并记录 → 截短 turns 列表，重算下一个 item 编号。

调用关系：handle_event 调用它；增量模式下通过 record_removed_turn_ids 告诉外部哪些回合消失了。

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

fn finish_current_turn(&mut self)

作用：把正在构建的回合放进已完成列表。

数据流：读取 current_turn → 如果是无内容、非明确打开、也没有压缩标记的临时回合就丢弃 → 否则转成 Turn 推入 turns。

调用关系：finish、handle_user_message、handle_turn_started、handle_turn_complete 和 rollback 都会用它关闭当前回合。

调用图：被 5 处调用（finish, handle_thread_rollback, handle_turn_complete, handle_turn_started, handle_user_message）；外部调用 1 个（from）。

fn new_turn(&mut self, id: Option<String>) -> PendingTurn

作用：创建一个新的待完成回合 PendingTurn。

数据流：输入可选 id → 有 id 就用它，没有就按场景生成 UUID 或 rollout-N → 初始化空条目和默认状态。

调用关系：ensure_turn 在需要隐式回合时调用它，handle_turn_started 在明确回合开始时也调用它。

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

fn ensure_turn(&mut self) -> &mut PendingTurn

作用：确保当前一定有一个可写入的回合。

数据流：如果 current_turn 为空 → 创建新 PendingTurn 并记录回合变化 → 返回当前回合的可变引用。

调用关系：很多写入函数都会先调用它，比如 push_item_in_current_turn、upsert_item_in_current_turn 和思考内容处理。

调用图：调用 2 个内部函数（new_turn, record_changed_pending_turn）；被 5 处调用（handle_agent_reasoning, handle_agent_reasoning_raw_content, handle_compacted, push_item_in_current_turn, upsert_item_in_current_turn）；外部调用 1 个（unreachable!）。

fn push_item_in_current_turn(&mut self, item: ThreadItem)

作用：把一个全新的条目追加到当前回合末尾。

数据流：输入 ThreadItem → 确保有当前回合 → push 到 items 列表 → 如果在收集变化，就记录这个新增条目。

调用关系：用户消息、模型回复、思考、审查模式等顺序追加的内容都通过它进入历史。

调用图：调用 3 个内部函数（ensure_turn, is_tracking_changes, record_changed_item）；被 8 处调用（handle_agent_message, handle_agent_reasoning, handle_agent_reasoning_raw_content, handle_context_compacted, handle_entered_review_mode, handle_exited_review_mode, handle_response_item, handle_user_message）。

fn upsert_item_in_turn_id(&mut self, turn_id: &str, item: ThreadItem)

作用：按指定回合 id 插入或更新一个条目。

数据流：输入 turn_id 和 ThreadItem → 先找当前回合，再找已完成回合 → 同 id 条目就替换，没有就追加；找不到回合则警告并丢弃。

调用关系：命令执行、文件修改、动态工具等带 turn_id 的事件用它，尤其能处理迟到结果回到原回合。

调用图：调用 3 个内部函数（is_tracking_changes, record_changed_item, upsert_turn_item）；被 10 处调用（handle_apply_patch_approval_request, handle_dynamic_tool_call_request, handle_dynamic_tool_call_response, handle_exec_command_begin, handle_exec_command_end, handle_guardian_assessment, handle_item_completed, handle_item_started, handle_patch_apply_begin, handle_patch_apply_end）；外部调用 1 个（warn!）。

fn upsert_item_in_current_turn(&mut self, item: ThreadItem)

作用：在当前回合里插入或更新一个条目。

数据流：输入 ThreadItem → 确保当前回合存在 → 用 upsert_turn_item 按条目 id 更新或追加 → 如需增量则记录变化。

调用关系：网页搜索、MCP 工具、图片、协作代理等当前回合事件都会走它。

调用图：调用 4 个内部函数（ensure_turn, is_tracking_changes, record_changed_item, upsert_turn_item）；被 24 处调用（handle_apply_patch_approval_request, handle_collab_agent_interaction_begin, handle_collab_agent_interaction_end, handle_collab_agent_spawn_begin, handle_collab_agent_spawn_end, handle_collab_close_begin, handle_collab_close_end, handle_collab_resume_begin, handle_collab_resume_end, handle_collab_waiting_begin (+14 more)）。

fn is_tracking_changes(&self) -> bool

作用：判断当前是否正在收集增量变化。

数据流：读取 active_change_set 是否存在 → 返回 true 或 false。

调用关系：多个写入函数调用它，决定是否需要额外记录 changed_items 或 changed_turns。

调用图：被 7 处调用（handle_agent_reasoning, handle_agent_reasoning_raw_content, handle_error, push_item_in_current_turn, record_changed_pending_turn, upsert_item_in_current_turn, upsert_item_in_turn_id）。

fn record_changed_item(&mut self, turn_id: String, item: ThreadItem)

作用：把某个条目的最新快照加入当前变更集。

数据流：输入 turn_id 和 ThreadItem → 如果 active_change_set 存在，就追加 ThreadHistoryItemChange → 否则什么也不做。

调用关系：push_item_in_current_turn、upsert_item_in_current_turn、upsert_item_in_turn_id 和流式思考更新会调用它。

调用图：被 5 处调用（handle_agent_reasoning, handle_agent_reasoning_raw_content, push_item_in_current_turn, upsert_item_in_current_turn, upsert_item_in_turn_id）。

fn record_changed_pending_turn(&mut self, turn: &PendingTurn)

作用：把正在进行的回合状态记录成一次变化。

数据流：输入 PendingTurn → 如果正在收集变化，就转成 ThreadHistoryTurnChange → 写入 changed_turns。

调用关系：ensure_turn 创建隐式回合、handle_turn_started 创建明确回合时会用它。

调用图：调用 3 个内部函数（is_tracking_changes, record_changed_turn, from_pending_turn）；被 2 处调用（ensure_turn, handle_turn_started）。

fn record_changed_turn(&mut self, turn: ThreadHistoryTurnChange)

作用：把一个回合状态变化加入当前变更集。

数据流：输入 ThreadHistoryTurnChange → 如果 active_change_set 存在，就追加到 changed_turns。

调用关系：错误、中断、完成和 pending turn 记录都通过它向外报告回合元数据变化。

调用图：被 4 处调用（handle_error, handle_turn_aborted, handle_turn_complete, record_changed_pending_turn）。

fn record_removed_turn_ids(&mut self, removed_turn_ids: Vec<String>)

作用：把被删除的回合 id 加入当前变更集。

数据流：输入多个 turn_id → 如果 active_change_set 存在，就追加到 removed_turn_ids。

调用关系：handle_thread_rollback 调用它，把回滚删除的信息交给增量消费者。

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

fn next_item_id(&mut self) -> String

作用：生成下一个自动条目 id。

数据流：读取 next_item_index → 生成 item-N 字符串 → 计数加一并返回 id。

调用关系：用户消息、模型消息、思考、审查模式和上下文压缩等没有外部 call_id 的条目会用它。

调用图：被 7 处调用（handle_agent_message, handle_agent_reasoning, handle_agent_reasoning_raw_content, handle_context_compacted, handle_entered_review_mode, handle_exited_review_mode, handle_user_message）；外部调用 1 个（format!）。

fn build_user_inputs(&self, payload: &UserMessageEvent) -> Vec<UserInput>

作用：把用户事件里的文字和图片整理成统一的输入列表。

数据流：输入 UserMessageEvent → 非空文字变 Text，远程图片变 Image，本地图片变 LocalImage，并带上清晰度 detail → 输出 Vec<UserInput>。

调用关系：handle_user_message 调用它，让用户消息条目能同时展示文本、远程图和本地图。

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

fn render_review_output_text(output: &ReviewOutputEvent) -> String

作用：把审查输出转换成要显示的一段文字。

数据流：输入 ReviewOutputEvent → 取 overall_explanation 并去掉首尾空白 → 空则返回兜底失败文案，否则返回解释文本。

调用关系：handle_exited_review_mode 用它生成退出审查模式时的历史内容。

fn convert_dynamic_tool_content_items(
    items: &[codex_protocol::dynamic_tools::DynamicToolCallOutputContentItem],
) -> Vec<DynamicToolCallOutputContentItem>

作用：把核心协议里的动态工具输出内容，转换成 v2 协议要展示的内容格式。

数据流：输入动态工具输出内容列表 → 逐个复制文本或图片 URL → 输出 Vec<DynamicToolCallOutputContentItem>。

调用关系：handle_dynamic_tool_call_response 调用它，把工具返回内容放进 ThreadItem::DynamicToolCall。

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

fn upsert_turn_item(items: &mut Vec<ThreadItem>, item: ThreadItem) -> &ThreadItem

作用：在一个回合的条目列表里按 id 更新已有条目，或追加新条目。

数据流：输入可变 items 列表和新 ThreadItem → 查找同 id 条目 → 找到就替换，找不到就 push → 返回最终列表里的条目引用。

调用关系：upsert_item_in_current_turn 和 upsert_item_in_turn_id 共用它，保证 begin/end 这类事件不会产生重复条目。

调用图：被 2 处调用（upsert_item_in_current_turn, upsert_item_in_turn_id）。

fn opened_explicitly(mut self) -> Self

作用：给待完成回合打上“这是明确开始的回合”标记。

数据流：输入 PendingTurn 自身 → 设置 opened_explicitly 为 true → 返回修改后的 PendingTurn。

调用关系：handle_turn_started 创建新回合时链式调用它，之后 finish_current_turn 会根据这个标记保留空回合。

fn with_status(mut self, status: TurnStatus) -> Self

作用：给待完成回合设置状态，方便创建时链式配置。

数据流：输入 PendingTurn 和 TurnStatus → 写入 status 字段 → 返回 PendingTurn。

调用关系：handle_turn_started 用它把新回合标成 InProgress。

fn with_started_at(mut self, started_at: Option<i64>) -> Self

作用：给待完成回合设置开始时间。

数据流：输入 PendingTurn 和可选时间戳 → 写入 started_at → 返回 PendingTurn。

调用关系：handle_turn_started 用它把 TurnStartedEvent 里的时间带进回合元数据。

fn from(value: &PendingTurn) -> Self

作用：把内部临时的 PendingTurn 转成对外使用的 Turn。

数据流：输入 PendingTurn 或它的引用 → 拷贝或移动 id、items、状态、错误和时间 → 输出 items_view 为 Full 的 Turn。

调用关系：finish_current_turn 和 active_turn_snapshot 等地方依赖这个转换，把构建中的回合变成稳定快照。

fn builds_multiple_turns_with_reasoning_items()

作用：测试旧式事件流能被拆成多轮，并正确合并思考摘要和原始内容。

数据流：构造用户消息、模型消息和思考事件 → 喂给 builder → 断言得到两轮、条目顺序和内容都正确。

调用关系：它直接使用 ThreadHistoryBuilder::new 和 finish，覆盖 handle_user_message、handle_agent_message、handle_agent_reasoning 等核心路径。

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

fn rebuilds_user_message_image_details_from_legacy_events()

作用：测试从旧用户消息事件中恢复远程图片和本地图片的 detail 信息。

数据流：输入带图片和清晰度的 rollout 事件 → 调用 build_turns_from_rollout_items → 检查 UserMessage content 是否包含三类输入。

调用关系：验证 build_user_inputs 在历史重放中的效果。

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

fn ignores_user_message_item_lifecycle_events()

作用：测试用户消息的生命周期事件不会额外生成重复用户消息。

数据流：构造 turn started、UserMessage、ItemStarted(UserMessage)、TurnComplete → 重建历史 → 断言只有真正的用户消息一条。

调用关系：覆盖 handle_item_started 对 UserMessage 类型的忽略逻辑。

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

fn rebuilds_sleep_item_from_persisted_completion()

作用：测试睡眠条目可以从完成事件恢复出来。

数据流：构造包含 Sleep 的 ItemCompleted → 重放 rollout → 检查 Turn 里有 Sleep 条目和持续时间。

调用关系：验证 handle_item_completed 对 Sleep 的 upsert 路径。

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

fn preserves_user_message_client_id_from_legacy_event()

作用：测试旧事件里的 client_id 不会丢失。

数据流：构造带 client_id 的用户消息事件 → 重建历史 → 检查 UserMessage 条目保留 client_id。

调用关系：覆盖 handle_user_message 从 UserMessageEvent 拷贝 client_id 的行为。

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

fn preserves_agent_message_phase_in_history()

作用：测试模型消息的阶段信息会保存进历史。

数据流：输入带 FinalAnswer phase 的 AgentMessage → 重建历史 → 检查 ThreadItem::AgentMessage 的 phase。

调用关系：覆盖 handle_agent_message 对 MessagePhase 的传递。

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

fn replays_image_generation_end_events_into_turn_history()

作用：测试图片生成结束事件能恢复成完整图片生成条目。

数据流：构造一轮用户请求和 ImageGenerationEnd → 重放 → 检查状态、提示词、结果和保存路径。

调用关系：覆盖 handle_image_generation_end 的历史重放路径。

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

fn splits_reasoning_when_interleaved()

作用：测试思考内容被普通模型消息隔开时，会分成两个思考条目。

数据流：输入思考、原始思考、模型消息、第二段思考 → 重放 → 检查两段 Reasoning 分别存在。

调用关系：验证 handle_agent_reasoning 只合并相邻的 Reasoning。

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

fn marks_turn_as_interrupted_when_aborted()

作用：测试收到中断事件后，当前轮会被标记为 Interrupted。

数据流：输入第一轮消息、中断、第二轮消息 → 重建历史 → 检查第一轮状态中断、第二轮正常完成。

调用关系：覆盖 handle_turn_aborted 与旧式隐式回合切分的配合。

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

fn drops_last_turns_on_thread_rollback()

作用：测试回滚会删除最后若干轮，并允许后续新轮继续追加。

数据流：构造两轮、回滚一轮、再来第三轮 → 重放 → 检查历史只剩第一轮和新第三轮。

调用关系：覆盖 handle_thread_rollback 的截断和 item 编号重算。

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

fn thread_rollback_clears_all_turns_when_num_turns_exceeds_history()

作用：测试回滚数量超过现有历史时会清空全部回合。

数据流：构造两轮后回滚 99 轮 → 重放 → 断言输出空列表。

调用关系：验证 handle_thread_rollback 对超大 num_turns 的保护。

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

fn uses_explicit_turn_boundaries_for_mid_turn_steering()

作用：测试明确回合边界内的多条用户消息会留在同一轮。

数据流：输入 TurnStarted、两条 UserMessage、TurnComplete → 重建 → 检查只有一个 turn 且有两条用户消息。

调用关系：覆盖 handle_turn_started 设置 opened_explicitly 后 handle_user_message 不拆轮的逻辑。

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

fn reconstructs_tool_items_from_persisted_completion_events()

作用：测试搜索、命令、MCP 工具这些完成事件能直接恢复成历史条目。

数据流：构造 WebSearchEnd、ExecCommandEnd、McpToolCallEnd → 重放 → 检查三个工具条目的字段。

调用关系：覆盖 handle_web_search_end、handle_exec_command_end、handle_mcp_tool_call_end。

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

fn reconstructs_mcp_tool_result_meta_from_persisted_completion_events()

作用：测试 MCP 工具结果里的 meta 和结构化内容不会丢。

数据流：输入成功的 McpToolCallEnd，带 content、structured_content、meta → 重建 → 检查结果完整。

调用关系：验证 handle_mcp_tool_call_end 对成功结果的保存。

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

fn reconstructs_dynamic_tool_items_from_request_and_response_events()

作用：测试动态工具的请求和响应会合并成一个完成条目。

数据流：输入 DynamicToolCallRequest 再输入 Response → 重建 → 检查同一 id 的条目状态为 Completed 且带内容。

调用关系：覆盖 handle_dynamic_tool_call_request、handle_dynamic_tool_call_response 和 upsert_turn_item。

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

fn reconstructs_declined_exec_and_patch_items()

作用：测试被拒绝的命令和补丁会在历史里显示为 Declined。

数据流：构造 declined 命令结束和 declined patch 结束 → 重放 → 检查命令和文件变更状态。

调用关系：验证命令和文件修改构建函数与对应 handle_*_end 的集成。

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

fn reconstructs_declined_guardian_command_item()

作用：测试安全审查拒绝命令时，会显示成被拒绝的命令执行条目。

数据流：输入 GuardianAssessment 进行中和 Denied → 重放 → 检查 CommandExecution 状态为 Declined。

调用关系：覆盖 handle_guardian_assessment 对审查状态的映射。

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

fn reconstructs_in_progress_guardian_execve_item()

作用：测试安全审查中的 execve 操作能显示为进行中的命令。

数据流：输入 InProgress 的 GuardianAssessment execve → 重建 → 检查命令字符串和 InProgress 状态。

调用关系：验证 build_item_from_guardian_event 与 handle_guardian_assessment 的配合。

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

fn assigns_late_exec_completion_to_original_turn()

作用：测试迟到的命令完成事件会回到原本的回合。

数据流：构造 turn-a 完成、turn-b 开始后才收到 turn-a 的 ExecCommandEnd → 重放 → 检查命令在 turn-a。

调用关系：验证 handle_exec_command_end 使用事件 turn_id，而不是当前回合。

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

fn drops_late_turn_scoped_item_for_unknown_turn_id()

作用：测试带未知 turn_id 的迟到条目会被丢弃，不会污染当前回合。

数据流：构造两个回合，再输入 turn-missing 的命令结束 → finish → 检查两个回合都没有这条命令。

调用关系：覆盖 upsert_item_in_turn_id 找不到回合时 warn 并丢弃的行为。

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

fn patch_apply_begin_updates_active_turn_snapshot_with_file_change()

作用：测试补丁开始事件会立刻体现在当前回合快照里。

数据流：构造 TurnStarted、UserMessage、PatchApplyBegin → 查询 active_turn_snapshot → 检查 FileChange 为 InProgress。

调用关系：验证 handle_patch_apply_begin、upsert_item_in_turn_id 和 active_turn_snapshot。

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

fn apply_patch_approval_request_updates_active_turn_snapshot_with_file_change()

作用：测试补丁审批请求也会更新当前回合快照。

数据流：输入审批请求事件 → 查询活跃回合快照 → 检查文件变更条目已经出现。

调用关系：覆盖 handle_apply_patch_approval_request 的实时展示路径。

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

fn late_turn_complete_does_not_close_active_turn()

作用：测试旧回合迟到的完成事件不会关闭正在进行的新回合。

数据流：turn-a 完成，turn-b 开始后又收到 turn-a complete → 继续加消息 → 重建后检查 turn-b 内容完整。

调用关系：验证 handle_turn_complete 优先精确匹配已完成回合，不误关 current_turn。

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

fn late_turn_aborted_does_not_interrupt_active_turn()

作用：测试旧回合迟到的中断事件不会把新回合标成中断。

数据流：turn-a 完成，turn-b 开始后收到 turn-a aborted → 再加消息 → 检查 turn-b 仍是 InProgress。

调用关系：覆盖 handle_turn_aborted 的按 id 精确处理逻辑。

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

fn preserves_compaction_only_turn()

作用：测试只有压缩标记、没有可展示条目的明确回合也会被保留。

数据流：输入 TurnStarted、Compacted、TurnComplete → 重建 → 检查得到一个空 items 的完成回合。

调用关系：验证 handle_compacted 和 finish_current_turn 的 saw_compaction 保留逻辑。

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

fn reconstructs_collab_resume_end_item()

作用：测试协作代理恢复结束事件能恢复成历史条目。

数据流：输入用户消息和 CollabResumeEnd → 重建 → 检查 ResumeAgent 条目的发送方、接收方和状态。

调用关系：覆盖 handle_collab_resume_end。

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

fn reconstructs_collab_spawn_end_item_with_model_metadata()

作用：测试创建协作代理结束时，模型和推理力度等元数据会保存。

数据流：输入 CollabAgentSpawnEnd，带新线程、模型、prompt、reasoning_effort → 重建 → 检查 SpawnAgent 条目完整。

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

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

fn reconstructs_interrupted_send_input_as_completed_collab_call()

作用：测试给子代理重定向输入时，子代理状态可为 Interrupted，但工具调用本身仍算完成。

数据流：输入 interaction begin 和 status Interrupted 的 end → 重建 → 检查工具状态 Completed，代理状态 Interrupted。

调用关系：验证 handle_collab_agent_interaction_end 对 AgentStatus::Interrupted 的特殊语义。

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

fn rollback_failed_error_does_not_mark_turn_failed()

作用：测试“回滚失败”这种错误不会把正常对话轮标成失败。

数据流：输入正常用户和模型消息，再输入 ThreadRollbackFailed 错误 → 重建 → 检查 turn 仍 Completed 且无 error。

调用关系：覆盖 handle_error 里 affects_turn_status 的过滤效果。

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

fn out_of_turn_error_does_not_create_or_fail_a_turn()

作用：测试回合之外的请求级错误不会新建或修改回合。

数据流：先完成一个 turn，再输入 BadRequest 错误 → 重放 → 检查原 turn 不受影响。

调用关系：验证 handle_error 只有当前回合存在且错误影响回合时才改状态。

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

fn error_then_turn_complete_preserves_failed_status()

作用：测试先失败再收到完成事件时，失败状态不会被覆盖成完成。

数据流：输入 TurnStarted、UserMessage、Error、TurnComplete → 重建 → 检查状态仍 Failed 且错误信息保留。

调用关系：覆盖 handle_error 与 handle_turn_complete 的状态保护。

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

fn rebuilds_hook_prompt_items_from_rollout_response_items()

作用：测试 rollout 里的特殊 hook prompt 响应项能恢复成 HookPrompt 条目。

数据流：构造 hook prompt ResponseItem → 重放 → 检查回合里有 HookPrompt 和两个 fragment。

调用关系：覆盖 handle_response_item 与 parse_hook_prompt_message 的集成。

调用图：调用 2 个内部函数（build_turns_from_rollout_items, build_hook_prompt_message）；外部调用 3 个（from_single_hook, assert_eq!, vec!）。

fn ignores_plain_user_response_items_in_rollout_replay()

作用：测试普通用户 ResponseItem 不会被误当成 hook prompt 放进历史。

数据流：输入普通 user ResponseItem → 重建 → 检查回合 items 为空。

调用关系：验证 handle_response_item 对非 hook prompt 的忽略逻辑。

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

fn changed_rollout_item_reports_new_item_snapshot()

作用：测试单条 rollout 处理能报告新建条目的快照。

数据流：新 builder 处理一条 UserMessage with changes → 得到变更集 → 检查包含新 UserMessage 和新回合状态。

调用关系：覆盖 handle_rollout_item_with_changes、collect_changes、record_changed_item 和 record_changed_pending_turn。

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

fn changed_rollout_item_reports_updated_existing_item_snapshot()

作用：测试同一条目被更新时，增量结果会报告更新后的快照。

数据流：先处理 WebSearchBegin，再处理 WebSearchEnd with changes → 检查变更集里是完整搜索结果。

调用关系：验证 upsert_item_in_current_turn 和 record_changed_item。

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

fn changed_rollout_item_reports_streaming_item_mutation()

作用：测试流式追加思考内容时，会报告被修改后的条目。

数据流：先处理 reasoning summary，再处理 raw content with changes → 检查变更集里 Reasoning 同时有 summary 和 content。

调用关系：覆盖 handle_agent_reasoning_raw_content 对已有条目的 mutation 记录。

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

fn changed_rollout_item_reports_turn_completion_metadata()

作用：测试回合开始和完成的时间状态变化会出现在增量变更里。

数据流：处理 TurnStarted with changes，再处理用户消息和 TurnComplete with changes → 检查 started_at、completed_at、duration_ms。

调用关系：覆盖 record_changed_pending_turn 和 handle_turn_complete 的变更记录。

调用图：调用 1 个内部函数（new）；外部调用 7 个（default, new, assert_eq!, TurnComplete, TurnStarted, UserMessage, EventMsg）。

fn changed_rollout_items_dedupe_updated_item_snapshots()

作用：测试批量变更会把同一条目的 begin/end 压缩成最终快照。

数据流：批量处理 WebSearchBegin 和 WebSearchEnd → 得到一个变更集 → 检查只报告完整搜索条目一次。

调用关系：验证 ThreadHistoryChangeAccumulator::push_item_change 的去重。

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

fn changed_rollout_items_dedupe_turn_metadata_snapshots()

作用：测试批量变更会把同一回合的开始和完成压缩成最终回合状态。

数据流：批量处理 TurnStarted 和 TurnComplete → 检查只输出 Completed 的最终回合快照。

调用关系：验证 ThreadHistoryChangeAccumulator::push_turn_change。

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

fn changed_rollout_items_drop_prior_changes_for_removed_turns()

作用：测试批量处理中如果回合后来被回滚，之前为它累计的新增变化会被删除。

数据流：批量处理 TurnStarted、UserMessage、ThreadRolledBack → 检查没有 changed_items 和 changed_turns，只剩 removed_turn_ids。

调用关系：覆盖 ThreadHistoryChangeAccumulator::push_removed_turn_id 对已删除回合的清理。

调用图：调用 1 个内部函数（new）；外部调用 7 个（default, new, assert_eq!, ThreadRolledBack, TurnStarted, UserMessage, EventMsg）。

fn new(
        codex_home: PathBuf,
        thread_manager: Arc<ThreadManager>,
        thread_store: Arc<dyn ThreadStore>,
        config_manager: ConfigManager,
        arg0_paths: Arg0DispatchPath

作用：创建一个会话导入器，把之后导入所需的路径、线程服务、配置服务和可执行文件路径都装进去。别人要开始导入外部会话前，先用它组装出这个“搬家工”。

数据流：输入是 Codex 主目录、线程管理器、线程存储、配置管理器和启动相关路径 → 它把这些保存到结构体里，并新建一个信号量（一种排队锁，用来限制同一时间能有多少导入批次）→ 输出一个可以复用、可以克隆的 ExternalAgentSessionImporter。

调用关系：它通常在上层初始化导入流程时被调用。后面的 import_sessions、prepare_session_import、persist_session 都依赖这里保存好的服务和路径来工作。

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

async fn import_sessions(
        &self,
        sessions: Vec<ExternalAgentSessionMigration>,
        mut item_result: ExternalAgentConfigImportItemResult,
    ) -> ExternalAgentConfigImportItemResul

作用：导入一批外部会话，并把每个会话成功或失败的结果写进返回对象里。它是这个文件里对外最重要的批量入口。

数据流：输入是一组待迁移会话和一个用来记录结果的 item_result → 如果列表为空就原样返回；否则先申请导入许可，再把会话变成异步任务，最多同时跑 5 个；每个任务成功就记录源文件和新线程 ID，失败就记录失败阶段和错误信息；最后把所有成功导入写到账本 → 输出更新后的 item_result，同时可能更新导入账本。

调用关系：它负责把一批导入任务分发给 import_requested_session。单个会话完成后，它调用结果记录方法保存成功信息，遇到错误时交给 record_import_error 记录；整批结束后交给 record_completed_session_imports 保存“已导入”的历史记录。

调用图：调用 2 个内部函数（record_success, record_import_error）；外部调用 4 个（new, record_completed_session_imports, pin_mut!, iter）。

async fn import_requested_session(
        &self,
        session: ExternalAgentSessionMigration,
    ) -> Result<Option<CompletedExternalAgentSessionImport>, SessionImportFailure>

作用：处理单个外部会话：先检查和整理，再真正写入系统线程库。它把“一个文件能不能导入、导入后变成哪个线程”这件事串起来。

数据流：输入是一个外部会话迁移请求 → 它先记住源文件路径，然后调用 prepare_session_import 做校验和整理；如果发现不需要导入，就返回空；如果准备成功，就调用 persist_session 创建新线程并写入内容 → 输出成功导入记录，里面包含源文件、源内容校验值和新线程 ID；如果失败，则带上出错阶段返回错误。

调用关系：它由 import_sessions 为每个会话调用。它自己不做复杂细节，而是把前半段交给 prepare_session_import，把后半段交给 persist_session；这样批量流程能清楚地区分是“准备失败”还是“保存失败”。

调用图：调用 2 个内部函数（persist_session, prepare_session_import）。

async fn prepare_session_import(
        &self,
        session: ExternalAgentSessionMigration,
    ) -> Result<Option<PendingSessionImport>, String>

作用：把外部会话文件变成系统可以导入的临时对象，并顺便做格式和重复导入等检查。它存在的原因是：导入前必须先确认这份材料干净、有效。

数据流：输入是一个外部会话迁移请求，以及导入器里保存的 Codex 主目录 → 它把真正的准备工作放进 spawn_blocking 后台阻塞任务中执行，调用 prepare_validated_session_import 读取、校验并整理会话 → 输出一个 PendingSessionImport；如果文件不需要导入则输出空；如果任务崩了或校验失败，则输出可读的错误文字。

调用关系：它只被 import_requested_session 调用，负责导入链路的第一关。因为准备过程可能读文件、算校验值或做较重检查，所以它用 spawn_blocking 避免堵住主异步任务。

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

async fn persist_session(
        &self,
        session: ImportedExternalAgentSession,
    ) -> Result<ThreadId, String>

作用：把已经整理好的外部会话真正保存成本系统的一条新对话线程。它负责补齐系统运行需要的配置、模型信息和线程元数据。

数据流：输入是 ImportedExternalAgentSession，里面有工作目录、标题、第一条用户消息和对话条目 → 它按该工作目录加载配置，查默认模型和模型说明，新建线程 ID，设置来源、记忆模式、创建时间、标题、预览、版本号等信息；然后创建线程、追加可持久保存的对话条目、更新元数据、落盘保存并关闭线程 → 输出新线程 ID；如果追加条目失败，会丢弃刚创建的线程，避免留下半截坏数据。

调用关系：它由 import_requested_session 在准备成功后调用，是导入链路的落库阶段。它会使用配置管理器加载配置，使用线程管理器取得模型信息，再把创建、追加、更新、持久化和关闭这些动作交给 thread_store 完成。

调用图：调用 2 个内部函数（load_with_overrides, new）；被 1 处调用（import_requested_session）；外部调用 5 个（default, now, new, env!, format!）。

fn should_redact_thread_resume_payloads(client_name: Option<&str>) -> bool

作用：判断这次 thread/resume 响应要不要做“打码”。它只认几个特定的 ChatGPT 远程客户端名字，避免影响其他客户端。

数据流：输入是一个可能存在、也可能为空的客户端名字 → 它检查这个名字是不是在预先写好的远程客户端名单里 → 输出 true 或 false，表示后面要不要遮掉大 payload。它不修改任何数据。

调用关系：这个函数像门口保安，先决定某个客户端是否需要特殊处理。真正动手遮内容的是 redact_thread_resume_payloads；这个判断通常会在调用它之前使用。

fn redact_thread_resume_payloads(turns: &mut [Turn])

作用：把一批对话回合里不适合直接发给远程客户端的大内容或敏感内容处理掉。它会保留普通文字消息，遮掉 MCP 工具调用的细节，并移除图片生成结果。

数据流：输入是一组可修改的 Turn，也就是对话里的多个回合 → 它逐个查看每个回合里的 ThreadItem：遇到 MCP 工具调用，就把 arguments 改成字符串“[redacted]”，如果有 result 就换成一个只含“[redacted]”的简化结果，如果有 error 就把错误消息也改成“[redacted]”；遇到 ImageGeneration 就从列表里删掉；其他项目保持原样 → 输出不是新对象，而是直接把传入的对话回合改好。

调用关系：这是这个文件的核心清理动作。测试函数 tests::redacts_mcp_success_result_and_removes_image_generation 和 tests::redacts_mcp_error_message 都会调用它，分别确认成功结果、图片生成、错误消息这些情况都被按预期处理。处理 MCP 结果时，它会用 redacted_mcp_tool_call_result 造一个安全的替代结果。

调用图：被 2 处调用（redacts_mcp_error_message, redacts_mcp_success_result_and_removes_image_generation）。

fn redacted_mcp_tool_call_result() -> McpToolCallResult

作用：生成一个“安全版”的 MCP 工具调用结果。这个结果只告诉客户端内容被遮掉了，不再携带真实工具返回的数据。

数据流：它不需要外部输入 → 它创建一个 McpToolCallResult，里面只有一段 JSON 文本内容，文本是“[redacted]”，结构化内容和额外元数据都设为空 → 返回这个干净的替代结果。

调用关系：它是 redact_thread_resume_payloads 的小帮手。主函数发现某个 MCP 工具调用原本有 result 时，就用它做一个替身，避免把原始结果发出去。内部会构造一个列表来放这段替代文本。

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

fn redacts_mcp_success_result_and_removes_image_generation()

作用：测试“成功的 MCP 工具调用”和“图片生成结果”会不会被正确处理。它保证普通消息还在，MCP 内容被打码，图片生成项目被删掉。

数据流：它先造一个假的线程，里面有普通助手消息、一个成功的 MCP 工具调用、一个图片生成项目 → 调用 redact_thread_resume_payloads 修改这个线程 → 再用断言检查：列表只剩两个项目，普通消息没变，MCP 的参数和结果变成“[redacted]”，图片生成项目不见了。

调用关系：这是给核心函数 redact_thread_resume_payloads 上保险的测试。它通过 tests::test_thread 造测试用线程，再调用被测函数，最后用 assert_eq! 对比处理后的数据是不是完全符合预期。

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

fn redacts_mcp_error_message()

作用：测试 MCP 工具调用失败时，错误消息也会被打码。这样即使工具报错里带了敏感信息，也不会直接发给目标客户端。

数据流：它先造一个只包含失败 MCP 工具调用的假线程，参数和错误消息里都有“secret”内容 → 调用 redact_thread_resume_payloads → 检查这个项目仍然存在，但参数和错误 message 都被替换成“[redacted]”，其他像工具名、状态、耗时等外壳信息保持不变。

调用关系：这个测试补上了失败场景，和 tests::redacts_mcp_success_result_and_removes_image_generation 一起覆盖主要分支。它同样依赖 tests::test_thread 创建样本数据，并直接验证 redact_thread_resume_payloads 的效果。

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

fn test_thread(items: Vec<ThreadItem>) -> Thread

作用：给测试快速造一个假的 Thread，也就是一整条对话线程。调用者只需要传入想测试的项目列表，不用每次手写一大堆固定字段。

数据流：输入是一组 ThreadItem，也就是要放进测试对话回合里的项目 → 它填好线程 id、会话 id、状态、路径、版本、来源等测试用默认值，并把这些项目放进一个已完成的 Turn 里 → 返回一个完整的 Thread，供测试函数拿去修改和检查。

调用关系：它是测试里的搭积木工具，不参与线上业务。两个测试函数都会用它准备数据；它内部会用 test_path_buf 生成测试路径，并用 vec! 组装回合列表。

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

async fn read_summary_from_rollout(
    path: &Path,
    fallback_provider: &str,
) -> std::io::Result<ConversationSummary>

作用：从一个 rollout 会话记录文件里读出线程摘要。它主要用于测试，模拟系统从磁盘上的历史记录恢复出线程列表时会看到什么。

数据流：输入是记录文件路径和一个备用的模型提供方名字。它先读取文件开头的几行，确认第一行是会话元数据；再补齐子代理的昵称和角色，读取文件修改时间作为更新时间；如果能从前几行找到用户消息，就交给 extract_conversation_summary 生成带预览的摘要。找不到预览时，它仍然会用元数据拼出一个摘要，只是 preview 为空；如果文件为空或开头不是元数据，就返回错误。

调用关系：它是测试里读取历史会话摘要的入口。流程中会调用 with_thread_spawn_agent_metadata 修正来源信息，调用 read_updated_at 获取更新时间，然后优先调用 extract_conversation_summary 抽取更完整的摘要。

调用图：调用 3 个内部函数（extract_conversation_summary, read_updated_at, with_thread_spawn_agent_metadata）；外部调用 4 个（to_path_buf, new, other, format!）。

fn extract_conversation_summary(
    path: PathBuf,
    head: &[serde_json::Value],
    session_meta: &SessionMeta,
    git: Option<&CoreGitInfo>,
    fallback_provider: &str,
    updated_at: Option<S

作用：从已经读到的 rollout 文件开头内容里，提取一份真正能展示在线程列表里的摘要。它最关键的工作是找到第一条用户消息，拿来当预览文字。

数据流：输入是文件路径、文件开头的 JSON 行、会话元数据、Git 信息、备用模型提供方和更新时间。它逐条尝试把 JSON 转成响应项，再找出第一条用户消息；如果消息里带有内部标记，就把标记前面的部分去掉，只留下用户真正输入的内容。最后把会话编号、时间、路径、预览、模型提供方、工作目录、版本、来源和 Git 信息打包成 ConversationSummary；如果没找到用户消息，就返回 None。

调用关系：它被 read_summary_from_rollout 调用，是“能不能做出带预览摘要”的判断点。它自己不读文件，只处理 read_summary_from_rollout 已经拿到的数据。

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

fn map_git_info(git_info: &CoreGitInfo) -> ConversationGitInfo

作用：把核心层的 Git 信息换成线程摘要里使用的 Git 信息格式。Git 是版本管理工具，这里只保留提交号、分支名和远程仓库地址这些展示时常用的内容。

数据流：输入是一份 CoreGitInfo。它读取提交哈希、分支和仓库地址，把字段名和外部接口需要的结构对齐，输出 ConversationGitInfo；原数据不会被修改。

调用关系：它是一个小转换器，供摘要生成流程使用。read_summary_from_rollout 和 extract_conversation_summary 在整理摘要时会间接依赖它把 Git 数据变成接口格式。

fn with_thread_spawn_agent_metadata(
    source: codex_protocol::protocol::SessionSource,
    agent_nickname: Option<String>,
    agent_role: Option<String>,
) -> codex_protocol::protocol::SessionSour

作用：给“由线程派生出来的子代理线程”补上代理昵称和代理角色。简单说，就是如果一个子任务有自己的名字和职责，这里确保这些信息不会丢。

数据流：输入是原来的会话来源，以及可选的 agent_nickname 和 agent_role。若两者都没有，就原样返回来源。若来源确实是 ThreadSpawn 类型的子代理来源，它会优先使用新传入的昵称和角色；没有新值时保留旧值。若来源不是这种子代理线程，也原样返回。

调用关系：它被 read_summary_from_rollout 调用，用在从旧记录恢复摘要之前。这样后续生成的线程摘要、线程对象就能正确显示代理昵称和角色。

调用图：被 1 处调用（read_summary_from_rollout）；外部调用 1 个（SubAgent）。

fn thread_response_active_permission_profile(
    active_permission_profile: Option<codex_protocol::models::ActivePermissionProfile>,
) -> Option<codex_app_server_protocol::ActivePermissionProfile>

作用：把内部的“当前生效权限配置”转换成接口返回用的格式。权限配置可以理解为系统允许这条线程做哪些事的规则。

数据流：输入是一个可能存在的 ActivePermissionProfile。它如果有值，就用通用转换规则转成 app-server 协议里的 ActivePermissionProfile；如果没有值，就保持 None。输出也是可选值，不修改原数据。

调用关系：它被 thread_settings_from_config_snapshot 和 thread_settings_from_core_snapshot 调用。两个设置转换流程都会用它来保持权限字段的外部格式一致。

调用图：被 2 处调用（thread_settings_from_config_snapshot, thread_settings_from_core_snapshot）。

fn thread_response_sandbox_policy(
    permission_profile: &codex_protocol::models::PermissionProfile,
    cwd: &Path,
) -> codex_app_server_protocol::SandboxPolicy

作用：根据权限配置和当前工作目录，算出接口要返回的沙箱策略。沙箱可以理解为“安全围栏”，限制程序能访问哪些文件、能做哪些危险操作。

数据流：输入是权限配置和当前工作目录 cwd。它先调用沙箱兼容层，根据权限规则和目录算出实际沙箱策略；再把这个内部策略转换成 app-server 协议里的 SandboxPolicy。输出是可直接返回给客户端的沙箱策略。

调用关系：它被 thread_settings_from_config_snapshot 和 thread_settings_from_core_snapshot 调用。凡是要把线程设置返回给外部时，都需要它把底层权限规则变成清楚的沙箱说明。

调用图：被 2 处调用（thread_settings_from_config_snapshot, thread_settings_from_core_snapshot）；外部调用 1 个（compatibility_sandbox_policy_for_permission_profile）。

fn thread_settings_from_config_snapshot(
    config_snapshot: &ThreadConfigSnapshot,
) -> ThreadSettings

作用：把配置快照转换成线程设置。配置快照就是某一刻线程使用的模型、权限、工作目录、协作模式等设置的“照片”。

数据流：输入是 ThreadConfigSnapshot。它读取工作目录、审批策略、审批人、权限配置、模型、模型提供方、服务档位、推理强度、摘要模式、协作模式和个性设定；其中权限相关字段会分别交给 thread_response_sandbox_policy 和 thread_response_active_permission_profile 转成接口格式。最后输出一个 ThreadSettings，供外部接口展示或使用。

调用关系：它是从配置系统到线程接口的桥。需要根据当前配置生成线程设置时会用它，它内部把权限和沙箱这两块转换工作交给专门的小函数。

调用图：调用 3 个内部函数（thread_response_active_permission_profile, thread_response_sandbox_policy, cwd）。

fn thread_settings_from_core_snapshot(
    snapshot: codex_protocol::protocol::ThreadSettingsSnapshot,
) -> ThreadSettings

作用：把核心协议里的线程设置快照转换成 app-server 返回的线程设置。它解决的是“核心层说法”和“接口层说法”不完全一样的问题。

数据流：输入是一份 ThreadSettingsSnapshot。它先把快照拆开，拿到模型、模型提供方、服务档位、审批策略、权限配置、当前权限、工作目录、推理设置、个性和协作模式等字段；再根据权限配置和工作目录算沙箱策略，并转换当前权限格式。最后输出 ThreadSettings。

调用关系：它常用于核心层已经给出完整线程设置时。和 thread_settings_from_config_snapshot 类似，它也调用 thread_response_sandbox_policy 和 thread_response_active_permission_profile 来统一权限相关输出。

调用图：调用 2 个内部函数（thread_response_active_permission_profile, thread_response_sandbox_policy）。

fn parse_datetime(timestamp: Option<&str>) -> Option<DateTime<Utc>>

作用：把字符串形式的时间转成程序能计算的 UTC 时间。UTC 是统一标准时间，方便不同地区的时间比较。

数据流：输入是一个可选的时间字符串。它如果存在，就尝试按 RFC3339 格式解析；RFC3339 是常见的类似“2024-01-01T12:00:00Z”的时间写法。解析成功后转成 UTC 时间，失败或没有输入就返回 None。

调用关系：它被 summary_to_thread 调用，用来把摘要里的创建时间和更新时间变成线程对象里的数字时间戳。

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

async fn read_updated_at(path: &Path, created_at: Option<&str>) -> Option<String>

作用：读取 rollout 文件的最后修改时间，把它当作线程的更新时间。这样历史线程列表可以按最近变化来显示，而不只看创建时间。

数据流：输入是文件路径和一个可选的创建时间。它尝试读取文件元数据，再取文件系统记录的修改时间，并格式化成带毫秒的标准时间字符串。如果文件元数据读不到，或者修改时间取不到，就退回使用传入的创建时间；如果创建时间也没有，就返回 None。

调用关系：它被 read_summary_from_rollout 调用，属于从磁盘记录恢复摘要时的辅助步骤。它只负责时间，不负责解析会话内容。

调用图：被 1 处调用（read_summary_from_rollout）；外部调用 1 个（metadata）。

fn thread_started_notification(mut thread: Thread) -> ThreadStartedNotification

作用：生成“线程已启动”的通知，并且在通知里去掉具体对话轮次。这样启动通知只告诉客户端线程本身的信息，不顺带塞进完整聊天记录。

数据流：输入是一个 Thread。它先清空 thread.turns，也就是清掉线程里的对话轮次列表；然后把这个精简后的线程放进 ThreadStartedNotification 里输出。传入的线程会被消费并变成通知内容。

调用关系：它用于线程启动事件的发送阶段。上游准备好 Thread 后调用它，下游拿到的是一个适合广播给客户端的启动通知。

fn summary_to_thread(
    summary: ConversationSummary,
    fallback_cwd: &AbsolutePathBuf,
) -> Thread

作用：把 ConversationSummary 转成完整的 Thread 对象。它主要用于测试或恢复场景：先有一份轻量摘要，再把它包装成线程列表里统一使用的线程结构。

数据流：输入是一份会话摘要和一个备用工作目录。它把摘要拆开，解析创建时间和更新时间，转换 Git 信息，规范化工作目录；如果工作目录无法规范化，就记录警告并使用备用目录。然后把会话编号转成线程 id，填入预览、模型提供方、时间戳、状态、路径、CLI 版本、代理昵称、代理角色、来源和 Git 信息，最后输出一个 Thread。输出的线程状态是 NotLoaded，表示只知道概要，还没有载入完整对话内容。

调用关系：它在摘要和线程对象之间搭桥。它会调用 parse_datetime 处理时间，也会调用路径规范化工具处理 cwd；生成的 Thread 可以继续被线程列表、通知或测试断言使用。

调用图：调用 2 个内部函数（parse_datetime, relative_to_current_dir）；外部调用 2 个（new, normalize_for_native_workdir）。

fn turn_ids_are_compatible(active_turn_id: Option<&str>, item_turn_id: Option<&str>) -> bool

作用：这个小函数用来判断两个“轮次编号”能不能算是同一轮。它允许其中一边没有编号，因为旧记录或某些事件可能缺少这个信息。

数据流：输入是当前正在整理的轮次编号和某条记录自带的轮次编号，二者都可能为空。它检查：如果已有编号，就要求另一边为空或完全相同；如果没有已有编号，就认为不冲突。输出是一个真假值，告诉上层这条记录能不能合到当前这段回放里。

调用关系：Session::reconstruct_history_from_rollout 在倒着扫描 rollout 时会反复用它，尤其是把 TurnContext 或 TurnStarted 归到当前活动片段时。它像门口核对票号的人，避免把不同轮次的元数据混到一起。

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

fn finalize_active_segment(
    active_segment: ActiveReplaySegment<'a>,
    base_replacement_history: &mut Option<&'a [ResponseItem]>,
    previous_turn_settings: &mut Option<PreviousTurnSettings>,

作用：这个函数负责把刚刚倒序收集好的一段对话“结账”。它决定这段是否被回滚丢掉，是否提供了最新可用的历史存档点、上一轮设置、参考上下文和窗口编号。

数据流：输入是一段 ActiveReplaySegment，以及几个外部正在累计的结果槽位：基础替换历史、上一轮设置、参考上下文、窗口编号、还要回滚几轮。它先看是否还有待回滚的用户轮次：如果这段算用户轮次，就消耗一个回滚名额并直接丢弃。若没有被丢弃，它会把这段里最新且还没被填过的信息写进那些结果槽位。输出不是返回值，而是修改这些传入的槽位，让后续重建历史时知道该从哪里开始、该用哪些恢复信息。

调用关系：Session::reconstruct_history_from_rollout 在倒序扫描时，遇到一轮的开头 TurnStarted，或者扫描结束还有未结算片段时，会调用它。它是倒序扫描阶段的收尾工，把临时片段变成真正会影响恢复结果的信息。

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

async fn reconstruct_history_from_rollout(
        &self,
        turn_context: &TurnContext,
        rollout_items: &[RolloutItem],
    ) -> RolloutReconstruction

作用：这是本文件的主函数：给它当前 turn_context 和一串 rollout_items，它会重建出会话历史，并顺手算出恢复或分叉会话需要的元数据。有人恢复旧会话时，核心就靠它判断哪些记录还有效、哪些已经被压缩或回滚。

数据流：输入是当前会话的 TurnContext，以及按时间保存的 RolloutItem 列表。它先从最新往最旧扫描，找最近仍然有效的历史存档点、上一轮模型设置、参考上下文和窗口编号；扫描中会识别回滚事件，并用 turn_ids_are_compatible 防止轮次混淆，用 finalize_active_segment 结算每个倒序片段。找到足够信息后，它再从存档点之后的记录正向重放：普通响应写入 ContextManager，跨代理通信转成模型输入再写入，压缩记录会替换历史，回滚记录会删除最近的用户轮次。最后输出 RolloutReconstruction，里面有最终 history、previous_turn_settings、reference_context_item 和 window_id。

调用关系：它是整个重建流程的入口。它调用 turn_ids_are_compatible 来判断记录归属，调用 finalize_active_segment 来完成每个片段的倒序结算；正向重放时，它借助 ContextManager::new 之类的上下文工具维护历史，还会在旧式压缩记录上调用 collect_user_messages 和 build_compacted_history 来重新生成压缩后的历史。

调用图：调用 5 个内部函数（build_compacted_history, collect_user_messages, new, finalize_active_segment, turn_ids_are_compatible）；外部调用 10 个（new, default, new, Latest, is_user_turn_boundary, matches!, iter, once, try_from, try_from）。

fn map_session_init_error(err: &anyhow::Error, codex_home: &Path) -> CodexErr

作用：把一次会话初始化失败，转换成 Codex 对外显示的严重错误。它的重点不是简单报错，而是尽量从复杂错误里挖出真正原因，并给用户一个能照着做的修复提示。

数据流：进去的是一个 anyhow::Error（可能包着很多层原因的错误）和 Codex 主目录路径 → 它沿着错误链一层层查看，寻找其中的 std::io::Error（文件或目录访问错误），再尝试交给 map_rollout_io_error 翻译 → 如果翻译成功，就出来一个带具体建议的 CodexErr::Fatal；如果没有识别到，就出来一个通用的“Failed to initialize session”严重错误，不改动任何文件。

调用关系：它是这个文件对外的入口。会话初始化流程失败时会调用它来整理错误。它自己不判断所有细节，而是把找到的底层文件错误交给 map_rollout_io_error；如果对方认不出来，它才兜底生成普通的 Fatal 错误。

调用图：外部调用 3 个（chain, format!, Fatal）。

fn map_rollout_io_error(io_err: &std::io::Error, codex_home: &Path) -> Option<CodexErr>

作用：把具体的文件系统错误，变成更像人话的故障说明和修复建议。比如看到“PermissionDenied”时，它会说明 Codex 不能访问会话文件，并提示可能需要修正目录所有者。

数据流：进去的是一个 std::io::Error（操作系统给出的文件错误）和 Codex 主目录路径 → 它先拼出会话目录路径，也就是 codex_home 下面的 sessions 子目录，然后根据错误种类分别写提示：权限不足、目录缺失、已有文件挡住、数据损坏、路径类型不对等 → 如果是认识的情况，就出来 Some(CodexErr::Fatal)，里面带有人能读懂的提示和原始底层错误；如果是不认识的错误种类，就出来 None，让上层用通用错误处理。

调用关系：它是 map_session_init_error 的具体翻译工具。上层先负责从复杂错误链里找出 io 错误，再把这个 io 错误交给它。它不负责决定整个初始化是否失败，只负责判断“这个文件错误能不能给出更好的说明”。

调用图：外部调用 4 个（join, kind, format!, Fatal）。

fn load_session_for_import(path: &Path) -> io::Result<Option<ImportedExternalAgentSession>>

作用：这是测试里用的简化入口：读取一个外部会话文件，但只关心导入后的会话本身，不关心文件内容的哈希值。哈希值可以理解为文件内容的指纹。

数据流：输入是一个文件路径 → 它调用完整版本的导入函数拿到“会话加内容指纹” → 把内容指纹丢掉，只返回可导入的会话，或者返回没有可导入内容。

调用关系：多个测试函数用它来模拟真实导入流程；它自己不解析文件，而是把工作交给 load_session_for_import_with_content_sha256。

调用图：调用 1 个内部函数（load_session_for_import_with_content_sha256）；被 7 处调用（adds_import_marker_without_copying_last_agent_message, builds_visible_turns_for_imported_history, emits_token_usage_for_imported_history, loads_ai_title_for_imported_session, loads_custom_title_for_imported_session, loads_custom_title_over_later_ai_title_for_imported_session, stores_imported_messages_as_response_items_and_visible_events）。

fn load_session_for_import_with_content_sha256(
    path: &Path,
) -> io::Result<Option<(ImportedExternalAgentSession, String)>>

作用：这是外部会话导入的主要入口。它读取外部聊天记录，检查是否够格导入，并转换成本项目内部的会话对象，同时保留文件内容指纹，方便之后判断文件有没有变。

数据流：输入是外部会话文件路径 → 它先用 read_session_import 读出工作目录、消息、标题和内容指纹 → 如果没有工作目录或没有可转换的聊天流水，就返回空 → 否则生成标题、第一条用户消息摘要和内部 RolloutItem 列表 → 输出 ImportedExternalAgentSession 加内容 SHA-256 指纹。

调用关系：真实导入流程中的 load_importable_session 会调用它，测试辅助函数 load_session_for_import 也会调用它；它把“原始消息变成内部流水账”的核心工作交给 rollout_items_from_messages。

调用图：调用 2 个内部函数（rollout_items_from_messages, read_session_import）；被 2 处调用（load_session_for_import, load_importable_session）。

fn rollout_items_from_messages(messages: Vec<ConversationMessage>) -> Vec<RolloutItem>

作用：这个函数把一串普通聊天消息，改造成系统能理解的“回合流水账”。没有它，界面就不知道哪条消息属于哪一轮，也不知道导入历史在哪里结束。

数据流：输入是一组 ConversationMessage → 它从头到尾扫描，遇到用户消息就开启新回合，必要时先结束上一回合；遇到助手消息就放进当前回合；同时把消息保存成可回放的 ResponseItem，并按字节数粗略估算 token → 最后补上“外部会话已导入”标记、token 统计和回合结束事件 → 输出 RolloutItem 列表。

调用关系：load_session_for_import_with_content_sha256 调用它完成最关键的格式转换；它内部会请 external_session_imported_marker_item 造导入标记，请 response_item 造消息记录，请 message_byte_count 和 approx_tokens_from_byte_count_i64 估算文字量，请 token_count_item 和 turn_complete_item 补齐系统事件。

调用图：调用 5 个内部函数（external_session_imported_marker_item, message_byte_count, response_item, token_count_item, turn_complete_item）；被 1 处调用（load_session_for_import_with_content_sha256）；外部调用 9 个（default, new, approx_tokens_from_byte_count_i64, format!, AgentMessage, TurnStarted, UserMessage, EventMsg, ResponseItem）。

fn external_session_imported_marker_item() -> RolloutItem

作用：这个函数生成一条特殊的助手消息，内容是“<EXTERNAL SESSION IMPORTED>”。它像文件夹里的分隔纸，提醒系统和界面：前面的内容是从外部搬进来的历史。

数据流：它不需要输入 → 直接创建一个 AgentMessageEvent，也就是助手可见消息事件 → 输出包装好的 RolloutItem。

调用关系：rollout_items_from_messages 在导入历史的最后一轮结束前调用它，用来给导入内容打标记；测试会检查这个标记确实出现在界面可见的回合里。

调用图：被 1 处调用（rollout_items_from_messages）；外部调用 2 个（AgentMessage, EventMsg）。

fn response_item(message: ConversationMessage) -> ResponseItem

作用：这个函数把一条导入来的聊天消息，包装成本项目内部保存模型响应时使用的消息格式。它保证用户消息和助手消息都能被后续回放或展示。

数据流：输入是一条 ConversationMessage → 如果角色是助手，就把文本放进输出文本；如果角色是用户，就把文本放进输入文本；同时把角色写成字符串 user 或 assistant → 输出一个 ResponseItem::Message。

调用关系：rollout_items_from_messages 每处理一条有效消息都会调用它；它和可见事件配合，让同一条导入消息既能显示给人看，也能作为内部历史被保存。

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

fn message_byte_count(message: &ConversationMessage) -> i64

作用：这个函数计算一条消息文本占多少字节，用来粗略估算 token 数。token 可以简单理解成模型处理文字时的“计量单位”。

数据流：输入是一条消息引用 → 它读取消息文本长度，并安全转换成 64 位整数；如果极端情况下长度太大无法转换，就用最大值兜底 → 输出字节数。

调用关系：rollout_items_from_messages 用它累计导入消息的大小，然后再交给 approx_tokens_from_byte_count_i64 估算模型可见 token 数。

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

fn token_count_item(last_model_visible_tokens: i64) -> RolloutItem

作用：这个函数生成一条 token 使用量事件，让系统知道导入历史大概占用了多少模型上下文空间。上下文空间可以理解成模型一次能“记住并参考”的文字容量。

数据流：输入是估算出来的 token 数 → 它填到 TokenUsage 里，并同时作为总用量和最近一次用量 → 输出一个 TokenCount 类型的 RolloutItem。

调用关系：rollout_items_from_messages 在最后补齐导入历史信息时调用它；测试 emits_token_usage_for_imported_history 会确认这条统计事件被生成并且数值大于零。

调用图：被 1 处调用（rollout_items_from_messages）；外部调用 3 个（TokenCount, EventMsg, default）。

fn turn_complete_item(turn_id: String, completed_at: Option<i64>) -> RolloutItem

作用：这个函数生成“某一轮对话结束了”的事件。它告诉系统一个用户回合已经收尾，后面可以开始新回合或完成导入。

数据流：输入是回合 ID 和可选的完成时间 → 它创建 TurnCompleteEvent，并明确不附带 last_agent_message → 输出一个 TurnComplete 类型的 RolloutItem。

调用关系：rollout_items_from_messages 在遇到新用户消息时会用它结束上一轮，在所有消息处理完后也会用它结束最后一轮；相关测试会确认它不会把最后一条助手消息重复塞进去。

调用图：被 1 处调用（rollout_items_from_messages）；外部调用 2 个（TurnComplete, EventMsg）。

fn builds_visible_turns_for_imported_history()

作用：这个测试确认导入的聊天历史能被正确分成界面上看得见的多轮对话。它重点检查两次用户请求会变成两个回合。

数据流：它创建临时目录和临时 JSONL 会话文件 → 写入用户、助手、用户三条记录 → 调用 load_session_for_import 导入，再用 build_turns_from_rollout_items 生成界面回合 → 断言回合数量、每轮条目数量和导入标记都符合预期。

调用关系：它站在用户界面的角度验证 rollout_items_from_messages 的结果；它依赖 record 和 jsonl 生成测试输入，并通过 load_session_for_import 进入正式导入逻辑。

调用图：调用 1 个内部函数（load_session_for_import）；外部调用 7 个（new, assert_eq!, build_turns_from_rollout_items, jsonl, record, create_dir_all, write）。

fn adds_import_marker_without_copying_last_agent_message()

作用：这个测试确认导入结束时会加上导入标记，但不会把最后一条助手回复错误地复制到回合结束事件里。这样可以避免界面或历史记录里出现重复内容。

数据流：它写入一轮用户和助手消息 → 导入后构建可见回合 → 检查最后一个可见条目是导入标记 → 再倒着查找最后的 TurnComplete 事件，确认其中没有 last_agent_message。

调用关系：它验证 external_session_imported_marker_item 和 turn_complete_item 配合得是否正确；入口仍然是 load_session_for_import。

调用图：调用 1 个内部函数（load_session_for_import）；外部调用 7 个（new, assert_eq!, build_turns_from_rollout_items, jsonl, record, create_dir_all, write）。

fn stores_imported_messages_as_response_items_and_visible_events()

作用：这个测试确认导入消息会同时以两种形式保存：一种给系统内部回放用，一种给界面显示用。少了任何一种，后续使用都会不完整。

数据流：它生成较长的用户请求和助手回答 → 写入临时文件并导入 → 在导入结果里数 ResponseItem::Message 的数量，也数可见的用户/助手事件数量 → 断言两类记录都各自完整存在。

调用关系：它主要验证 rollout_items_from_messages 对 response_item 和可见事件的双重写入；它用 record 和 jsonl 准备输入，用 load_session_for_import 跑完整转换。

调用图：调用 1 个内部函数（load_session_for_import）；外部调用 6 个（new, assert_eq!, jsonl, record, create_dir_all, write）。

fn loads_custom_title_for_imported_session()

作用：这个测试确认如果外部文件提供了用户自定义标题，导入后的会话会使用这个标题。标题就像聊天列表里的名字，能帮助人快速识别会话。

数据流：它写入一条用户消息和一条 custom-title 记录 → 导入会话 → 读取 imported.title → 断言标题等于外部文件给出的自定义标题。

调用关系：它验证 load_session_for_import_with_content_sha256 里选择标题的规则；custom_title_record 负责生成测试用标题记录。

调用图：调用 1 个内部函数（load_session_for_import）；外部调用 7 个（new, assert_eq!, custom_title_record, jsonl, record, create_dir_all, write）。

fn loads_ai_title_for_imported_session()

作用：这个测试确认如果外部文件提供的是 AI 生成标题，系统也能把它当作导入会话标题使用。

数据流：它写入一条用户消息和一条 ai-title 记录 → 调用导入函数 → 检查导入结果里的 title → 输出结果是测试通过或失败。

调用关系：它通过 load_session_for_import 触发真实导入逻辑，ai_title_record 负责制造测试输入；它覆盖的是标题读取的另一个来源。

调用图：调用 1 个内部函数（load_session_for_import）；外部调用 7 个（new, assert_eq!, ai_title_record, jsonl, record, create_dir_all, write）。

fn loads_custom_title_over_later_ai_title_for_imported_session()

作用：这个测试确认当自定义标题和 AI 标题都存在时，自定义标题优先。也就是说，人起的名字比机器生成的名字更重要。

数据流：它写入用户消息、自定义标题、再写入 AI 标题 → 导入会话 → 检查最终 title → 断言结果仍然是自定义标题，而不是后面的 AI 标题。

调用关系：它验证 read_session_import 和 load_session_for_import_with_content_sha256 合起来体现出的标题优先级；输入由 custom_title_record、ai_title_record、record 和 jsonl 共同构造。

调用图：调用 1 个内部函数（load_session_for_import）；外部调用 8 个（new, assert_eq!, ai_title_record, custom_title_record, jsonl, record, create_dir_all, write）。

fn emits_token_usage_for_imported_history()

作用：这个测试确认导入历史会生成 token 用量信息。这样系统后面判断上下文长度时，不会把导入内容当成不存在。

数据流：它写入三条聊天记录 → 导入成 RolloutItem 列表 → 从里面找到 TokenCount 事件 → 检查最近用量大于零，并且总用量和最近用量一致。

调用关系：它验证 rollout_items_from_messages 最后调用 token_count_item 的效果；测试输入仍由 record 和 jsonl 创建，导入入口是 load_session_for_import。

调用图：调用 1 个内部函数（load_session_for_import）；外部调用 7 个（new, assert!, assert_eq!, jsonl, record, create_dir_all, write）。

fn record(role: &str, text: &str, cwd: &Path) -> JsonValue

作用：这是测试用的小工具，用来造一条普通聊天记录 JSON。它让每个测试不用重复手写同样的字段。

数据流：输入是角色、文本和工作目录 → 它取当前 UTC 时间，组装 type、cwd、timestamp 和 message.content 字段 → 输出一个 JSON 值。

调用关系：多个测试用它生成 user 或 assistant 记录，再交给 jsonl 拼成临时会话文件；它只服务测试，不参与正式运行。

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

fn custom_title_record(title: &str) -> JsonValue

作用：这是测试用的小工具，用来生成一条“自定义标题”记录。它专门帮助测试标题导入规则。

数据流：输入是标题文本 → 它包装成 type 为 custom-title、字段为 customTitle 的 JSON → 输出这个 JSON 值。

调用关系：标题相关测试调用它，然后由 jsonl 写入测试文件；正式导入逻辑读取后应把它识别为来源标题。

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

fn ai_title_record(title: &str) -> JsonValue

作用：这是测试用的小工具，用来生成一条“AI 标题”记录。它帮助测试系统能不能识别机器生成的会话标题。

数据流：输入是标题文本 → 它包装成 type 为 ai-title、字段为 aiTitle 的 JSON → 输出这个 JSON 值。

调用关系：AI 标题相关测试调用它，再通过 jsonl 放入临时文件；导入函数随后读取并应用标题规则。

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

fn jsonl(records: &[JsonValue]) -> String

作用：这个测试工具把多条 JSON 记录拼成 JSONL 文本。JSONL 就是一行一个 JSON，常用来保存日志式数据。

数据流：输入是一组 JSON 值 → 它把每个 JSON 转成字符串 → 用换行符连接 → 输出可以直接写入测试会话文件的文本。

调用关系：几乎所有测试都会用它把 record、custom_title_record 或 ai_title_record 生成的记录写成文件；之后 load_session_for_import 再读取这个文件。

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

fn is_persisted_rollout_item(item: &RolloutItem) -> bool

作用：判断单个 rollout 项目要不要保存到 rollout 文件里。它是总入口，会先看这个项目属于哪一大类，再用对应的小规则来决定。

数据流：进去的是一个 RolloutItem，也就是一条可能要写入流水账的记录。函数先拆开看：如果里面是 ResponseItem，就交给 should_persist_response_item；如果是 EventMsg，就交给 should_persist_event_msg；如果是协作通信、压缩标记、回合上下文或会话元信息，就直接认为要保存。出来的是 true 或 false，表示这条记录是否该留下。

调用关系：persisted_rollout_items 在过滤一整批记录时会逐条调用它。它自己不做所有细节判断，而是把模型回答交给 should_persist_response_item，把系统事件交给 should_persist_event_msg，像前台分诊一样把不同病人送到不同窗口。

调用图：调用 2 个内部函数（should_persist_event_msg, should_persist_response_item）；被 1 处调用（persisted_rollout_items）。

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

作用：从一批 rollout 项目里挑出应该保存的那些，生成一个干净的新列表。有人要把实时产生的记录追加到文件前，会用它先过一遍筛子。

数据流：进去的是 RolloutItem 的列表切片，也就是一批候选记录。函数先创建一个空列表，然后逐条检查：每条都交给 is_persisted_rollout_item 判断；通过的就复制一份放进新列表，没通过的丢掉。出来的是只包含应保存项目的 Vec<RolloutItem>，原来的输入列表不会被改动。

调用关系：它是批量过滤的外层工具，会在“实时追加记录”这类场景里使用。它把核心判断交给 is_persisted_rollout_item，自己只负责循环、收集结果，并用 Vec::new 创建输出容器。

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

fn should_persist_response_item(item: &ResponseItem) -> bool

作用：判断模型返回内容里的某一项 ResponseItem 要不要写进 rollout 文件。它保留能还原对话和工具行为的主要内容，跳过不值得长期保存的触发器或未知杂项。

数据流：进去的是一个 ResponseItem，比如普通消息、智能体消息、推理内容、本地命令调用、函数调用、搜索结果、图片生成、上下文压缩等。函数用类型匹配逐项判断：大多数真实内容和工具调用会返回 true；CompactionTrigger 这种只是触发压缩的提示，以及 Other 这种无法明确归类的内容会返回 false。出来的是一个布尔值，告诉上层是否保存。

调用关系：is_persisted_rollout_item 遇到 RolloutItem::ResponseItem 时会调用它。它不负责写文件，也不处理事件，只专心回答一个问题：这条模型响应内容是不是值得进入 rollout 流水账。

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

fn should_persist_response_item_for_memories(item: &ResponseItem) -> bool

作用：判断某个 ResponseItem 是否适合进入 memories，也就是系统的长期记忆材料。它的标准比 rollout 保存更谨慎，因为记忆会影响以后，而不仅是用于回放。

数据流：进去的是一个 ResponseItem。函数会看它是什么类型：普通 Message 会进一步检查角色，如果 role 是 developer 就不保存，因为这类内容通常是开发者指令，不该混进记忆；工具调用和工具输出、网页搜索等可观察行为会保存；智能体内部消息、推理、图片生成、压缩相关内容和未知项不会保存。出来的是 true 或 false，只表示是否适合做记忆材料，不会改动输入。

调用关系：这个函数没有出现在给出的调用关系里，说明它可能是给别的模块按需调用的独立规则。它和 should_persist_response_item 很像，但服务目标不同：一个面向 rollout 回放流水账，一个面向长期记忆，因此取舍也不同。

fn should_persist_event_msg(ev: &EventMsg) -> bool

作用：判断一条系统事件 EventMsg 要不要写进 rollout 文件。它负责把关键节点留下，比如用户消息、回合开始结束、搜索完成、上下文压缩完成等，同时过滤掉大量临时进度和细碎通知。

数据流：进去的是一个 EventMsg，也就是运行过程中产生的一条事件。函数按事件种类逐个判断：能帮助以后回放或分析流程的事件返回 true；只是开始通知、实时增量、审批请求、终端输出片段、启动进度、警告等临时信息大多返回 false。特殊的是 ItemCompleted：它只在完成的项目是 Plan 或 Sleep 时保存，因为这些项目没有等价的原始 ResponseItem 或旧事件可替代。出来的是一个布尔值，告诉上层这条事件是否该长期留在 rollout 文件里。

调用关系：is_persisted_rollout_item 遇到 RolloutItem::EventMsg 时会调用它。它内部用 matches! 这个 Rust 匹配工具来处理 ItemCompleted 的特殊判断。整体上，它是事件保存规则的集中清单，保证文件里留下的是关键剧情，而不是每一帧动画。

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

fn builder_from_session_meta(
    session_meta: &SessionMetaLine,
    rollout_path: &Path,
) -> Option<ThreadMetadataBuilder>

作用：把会话文件里的 SessionMeta 行转换成一个元数据构建器。构建器可以理解成一张还没正式提交的登记表草稿。

数据流：进去的是一条 SessionMeta 和这个 rollout 文件的路径；它先把文本时间解析成 UTC 时间，再把会话 ID、来源、模型供应商、昵称、角色、工作目录、CLI 版本、Git 信息等填进 ThreadMetadataBuilder；出来的是一个可继续补充、最后生成正式元数据的构建器。如果时间格式看不懂，就返回空，表示这条资料不能用。

调用关系：它是 builder_from_items 的优先路线：只要会话文件里有正式的 SessionMeta，builder_from_items 就会把工作交给它，而不是再从文件名里猜信息。它内部会调用 parse_timestamp_to_utc 来把字符串时间变成机器能比较的时间。

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

fn builder_from_items(
    items: &[RolloutItem],
    rollout_path: &Path,
) -> Option<ThreadMetadataBuilder>

作用：从一整个会话文件的记录项里找出能建立元数据的基础信息。它兼容新旧文件：新文件读正式元数据，旧文件就退回去读文件名。

数据流：进去的是 rollout 文件里解析出的多条 RolloutItem 和文件路径；它先在这些记录里寻找 SessionMeta，找到就交给 builder_from_session_meta；如果找不到，就从文件名拆出时间戳和 UUID，再创建一个最基础的 ThreadMetadataBuilder；出来的是构建器，或者在信息实在不够时返回空。

调用关系：extract_metadata_from_rollout 会靠它先搭好元数据骨架，然后再逐条应用会话事件补充细节。调用图里也显示 apply_rollout_items 会用它，说明它是“从原始记录进入元数据世界”的共同入口。

调用图：调用 4 个内部函数（from_string, parse_timestamp_uuid_from_filename, builder_from_session_meta, new）；被 2 处调用（extract_metadata_from_rollout, apply_rollout_items）；外部调用 6 个（from_timestamp, file_name, to_path_buf, default, parse_rollout_file_name, iter）。

async fn extract_metadata_from_rollout(
    rollout_path: &Path,
    default_provider: &str,
) -> anyhow::Result<ExtractionOutcome>

作用：读取一个 rollout 会话文件，并提炼出完整的会话元数据。有人想把单个会话导入数据库、修复索引或做恢复时，会用到它。

数据流：进去的是一个 rollout 文件路径和默认模型供应商名称；它先用 RolloutRecorder::load_rollout_items 读出文件里的所有记录项和解析错误数；如果文件为空就报错；然后用 builder_from_items 建立元数据骨架，再把每条记录交给 apply_rollout_item 逐步更新标题、时间、状态等信息；最后用文件修改时间补上 updated_at。出来的是 ExtractionOutcome，里面有元数据、memory_mode（记忆功能模式）和解析错误数量。

调用关系：backfill_sessions_with_lease 在批量补录时会反复调用它。其他流程，比如按当前目录寻找可恢复会话、重新对齐 rollout 和数据库，也会用它。它把读文件的活交给 RolloutRecorder，把每条记录如何影响元数据的细节交给 codex_state::apply_rollout_item。

调用图：调用 3 个内部函数（builder_from_items, file_modified_time_utc, load_rollout_items）；被 4 处调用（backfill_sessions_with_lease, resume_candidate_matches_cwd, reconcile_rollout, reconcile_rollout_preserves_existing_explicit_title）；外部调用 2 个（anyhow!, apply_rollout_item）。

async fn backfill_sessions(
    runtime: &codex_state::StateRuntime,
    codex_home: &Path,
    default_provider: &str,
)

作用：这是补录会话元数据的简化入口。调用者不用关心租约时间，它会使用默认的补录租约设置。

数据流：进去的是状态数据库运行时、Codex 主目录和默认模型供应商；它不自己扫描文件，而是把这些参数连同默认租约秒数传给 backfill_sessions_with_lease；出来没有返回值，实际结果是数据库被补齐，日志和指标被记录。

调用关系：wait_for_backfill_gate 会调用它，说明系统会在某个启动或等待阶段触发补录。它只是薄薄的一层包装，真正复杂的扫描、提取和写库都在 backfill_sessions_with_lease 里完成。

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

async fn backfill_sessions_with_lease(
    runtime: &codex_state::StateRuntime,
    codex_home: &Path,
    default_provider: &str,
    backfill_lease_seconds: i64,
)

作用：批量扫描旧会话文件，把它们的元数据补进状态数据库。它还会防止重复开工、记录进度、统计成功失败数量。

数据流：进去的是状态数据库运行时、Codex 主目录、默认模型供应商和租约秒数；它先读取补录状态，如果已经完成就直接退出；然后尝试抢占补录租约，抢不到说明别的任务正在做；抢到后扫描 sessions 和 archived sessions 目录，收集 rollout 文件路径，按水位线排序并跳过已经处理过的文件。之后它分批读取每个文件，用 extract_metadata_from_rollout 提取元数据，规范化工作目录，保留数据库里已有的 Git 信息或人工标题，补上归档时间，写入数据库，并恢复 memory_mode。每批结束会 checkpoint（保存进度点），最后标记补录完成并上报指标。

调用关系：backfill_sessions 会把默认参数转交给它，wait_for_backfill_gate 也可能直接调用它。它把找文件交给 collect_rollout_paths，把单文件提取交给 extract_metadata_from_rollout，把文件修改时间交给 file_modified_time_utc，把工作目录清洗交给 normalize_cwd_for_state_db。它是这个文件里最像“总调度员”的函数。

调用图：调用 5 个内部函数（collect_rollout_paths, extract_metadata_from_rollout, file_modified_time_utc, normalize_cwd_for_state_db, default）；被 2 处调用（backfill_sessions, wait_for_backfill_gate）；外部调用 15 个（default, join, new, global, info!, checkpoint_backfill, get_backfill_state, get_thread, mark_backfill_complete, mark_backfill_running (+5 more)）。

fn backfill_watermark_for_path(codex_home: &Path, path: &Path) -> String

作用：为一个 rollout 文件生成补录进度用的水位线。水位线就是“我已经处理到哪里了”的书签。

数据流：进去的是 Codex 主目录和某个文件路径；它尽量把文件路径变成相对于主目录的路径，并把 Windows 的反斜杠改成统一的斜杠；出来的是一个字符串水位线。它不改文件，也不访问数据库。

调用关系：backfill_sessions_with_lease 在收集到文件后会用它给每个文件做排序和进度标记。这样补录中断后，下次能从上次的书签后面继续，而不是把所有文件重做一遍。

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

async fn file_modified_time_utc(path: &Path) -> Option<DateTime<Utc>>

作用：读取文件的最后修改时间，并转换成 UTC 时间。UTC 可以理解成统一时区，方便不同机器、不同地区比较时间。

数据流：进去的是文件路径；它调用 compression::file_modified_time 读取底层文件修改时间，如果读不到就返回空；读到后把秒和纳秒转换成 DateTime<Utc>；出来的是可保存到元数据里的更新时间。

调用关系：extract_metadata_from_rollout 用它给单个会话补 updated_at。backfill_sessions_with_lease 在处理归档文件时也用它推断 archived_at。它是“从文件系统时间补足元数据”的小工具。

调用图：调用 1 个内部函数（file_modified_time）；被 2 处调用（backfill_sessions_with_lease, extract_metadata_from_rollout）；外部调用 1 个（from_timestamp）。

fn parse_timestamp_to_utc(ts: &str) -> Option<DateTime<Utc>>

作用：把文本形式的时间戳转成 UTC 时间。它专门兼容两种常见写法，避免因为格式差异导致会话元数据读不出来。

数据流：进去的是一个时间字符串；它先尝试解析文件名风格的格式，比如 年-月-日T时-分-秒；如果不行，再尝试 RFC3339 格式，也就是常见的带时区标准时间格式；成功后出来一个 UTC 时间，失败就返回空。

调用关系：builder_from_session_meta 在读取 SessionMeta 的创建时间时会调用它。也就是说，只要这里不认识某种时间格式，上层就无法从这条 SessionMeta 建立元数据。

调用图：被 1 处调用（builder_from_session_meta）；外部调用 3 个（from_naive_utc_and_offset, parse_from_rfc3339, parse_from_str）。

async fn collect_rollout_paths(root: &Path) -> std::io::Result<Vec<PathBuf>>

作用：从一个目录开始往下找出所有 rollout 会话文件。它像一个文件夹巡检员，会进入子目录，但只收集真正能识别的会话文件。

数据流：进去的是根目录路径；它用一个栈保存还要检查的目录，逐个读取目录项；遇到子目录就继续深入，遇到普通文件就让 compression::RolloutFile::from_path 判断是不是 rollout 文件；符合条件的路径会加入结果列表。读目录、读文件类型出错时，它会写警告并跳过，不会让整个扫描直接崩掉。出来的是找到的 rollout 文件路径列表。

调用关系：backfill_sessions_with_lease 会分别对正常会话目录和归档会话目录调用它。它只负责“把候选文件找齐”，后面的排序、过滤水位线、读取内容和写数据库，都由 backfill_sessions_with_lease 接着完成。

调用图：调用 1 个内部函数（from_path）；被 1 处调用（backfill_sessions_with_lease）；外部调用 4 个（new, read_dir, vec!, warn!）。

fn apply_rollout_item(
    metadata: &mut ThreadMetadata,
    item: &RolloutItem,
    default_provider: &str,
)

作用：这是入口函数：拿到一条对话流水记录，就把它能贡献的信息写进线程元数据。别人不需要关心记录是哪一类，直接交给它即可。

数据流：输入是一份可修改的 ThreadMetadata、一条 RolloutItem，以及默认模型提供商名称。它先看条目类型：会话信息交给 apply_session_meta_from_item，轮次上下文交给 apply_turn_context，事件消息交给 apply_event_msg，回复条目交给 apply_response_item；不会影响元数据的条目就跳过。最后如果模型提供商还是空的，就补上默认值。

调用关系：它是本文件的总分发员。测试里的各种场景都会调用它，实际系统重放聊天记录时也会按条调用它；它再把具体活儿分给几个更小的函数。

调用图：调用 4 个内部函数（apply_event_msg, apply_response_item, apply_session_meta_from_item, apply_turn_context）；被 10 处调用（event_msg_blank_user_message_without_images_keeps_first_user_message_empty, event_msg_image_only_user_message_sets_image_placeholder_preview, event_msg_thread_goal_sets_preview_only_and_later_user_sets_message_title, event_msg_user_messages_set_title_and_first_user_message, response_item_user_messages_do_not_set_title_or_first_user_message, session_meta_does_not_set_model_or_reasoning_effort, turn_context_does_not_override_session_cwd, turn_context_sets_cwd_when_session_cwd_missing, turn_context_sets_model_and_reasoning_effort, turn_context_sets_permission_profile_metadata）。

fn rollout_item_affects_thread_metadata(item: &RolloutItem) -> bool

作用：这个函数回答一个简单问题：这条流水记录会不会改变存在数据库里的线程元数据。它可以帮助系统少做无用功。

数据流：输入是一条 RolloutItem。它只检查条目的种类，不修改任何数据；如果是会话信息、轮次上下文、token 统计、用户消息或目标更新，就返回 true，否则返回 false。

调用关系：它像一个过滤器，通常会在真正更新元数据前使用。它不调用别的本文件函数，也不负责修改内容，只负责判断值不值得处理。

fn apply_session_meta_from_item(metadata: &mut ThreadMetadata, meta_line: &SessionMetaLine)

作用：这个函数从“会话开头的基本信息”里提取线程身份、来源、工作目录、CLI 版本和 Git 信息。它保证元数据有一个可靠的基础档案。

数据流：输入是可修改的 ThreadMetadata 和 SessionMetaLine。它先确认记录里的线程 ID 和当前元数据 ID 一致；不一致就直接忽略，避免把别的分支会话的信息混进来。确认后，它把来源、代理名称、角色、路径、模型提供商、CLI 版本、当前目录、Git 提交号、分支和仓库地址写入元数据。

调用关系：它只由 apply_rollout_item 调用，专门处理 RolloutItem::SessionMeta。遇到枚举值时，它会交给 enum_to_string 转成普通字符串，方便存数据库和展示。

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

fn apply_turn_context(metadata: &mut ThreadMetadata, turn_ctx: &TurnContextItem)

作用：这个函数读取某一轮对话的运行环境，比如当前目录、使用的模型、推理强度、沙箱权限和审批模式。它让线程摘要知道这轮对话是在什么规则下运行的。

数据流：输入是可修改的 ThreadMetadata 和 TurnContextItem。它在元数据还没有工作目录时，才用轮次里的目录补上；然后写入模型名、推理强度、权限配置的 JSON 字符串，以及审批模式字符串。

调用关系：它由 apply_rollout_item 在遇到 RolloutItem::TurnContext 时调用。它会用 permission_profile 取出最终权限配置，用 serde_json 转成字符串，并用 enum_to_string 把审批策略转成易存储的文字。

调用图：调用 2 个内部函数（permission_profile, enum_to_string）；被 1 处调用（apply_rollout_item）；外部调用 1 个（to_string）。

fn apply_event_msg(metadata: &mut ThreadMetadata, event: &EventMsg)

作用：这个函数处理运行过程中发生的事件消息，重点是用户说了什么、token 用了多少、线程目标是什么。它决定标题、预览和第一条用户消息这些最容易被用户看到的字段。

数据流：输入是可修改的 ThreadMetadata 和 EventMsg。token 统计会更新 tokens_used；用户消息会生成预览，必要时设置 first_user_message，并从消息正文生成 title；目标更新会在预览为空时用目标内容补上。其它事件不改元数据。

调用关系：它由 apply_rollout_item 调用。它会请 user_message_preview 生成用户消息摘要，请 strip_user_message_prefix 去掉系统加的消息前缀，请 set_preview_if_empty 避免覆盖已有预览。

调用图：调用 3 个内部函数（set_preview_if_empty, strip_user_message_prefix, user_message_preview）；被 1 处调用（apply_rollout_item）。

fn apply_response_item(_metadata: &mut ThreadMetadata, _item: &ResponseItem)

作用：这个函数目前故意什么都不做。它保留了一个位置，表示模型回复条目现在不会改变线程元数据。

数据流：输入是可修改的 ThreadMetadata 和 ResponseItem，但两个参数都没有被使用。进去什么，出来还是什么，不产生任何修改。

调用关系：它由 apply_rollout_item 在遇到 RolloutItem::ResponseItem 时调用。测试专门确认，即使 ResponseItem 里看起来像用户消息，也不能用它设置标题或第一条用户消息。

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

fn set_preview_if_empty(metadata: &mut ThreadMetadata, preview: Option<String>)

作用：这个小函数只在预览还没有内容时设置预览。它防止后来的消息把更早、更代表性的预览覆盖掉。

数据流：输入是可修改的 ThreadMetadata 和一个可能存在的预览文字。它检查 metadata.preview；如果为空，就写入这段文字；如果已经有值，就保持不变。

调用关系：它由 apply_event_msg 调用。用户消息和线程目标更新都可能想设置预览，但最终谁先写入，谁就保留下来。

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

fn strip_user_message_prefix(text: &str) -> &str

作用：这个函数把用户消息前面系统加的固定标记去掉，只留下真正给人看的内容。没有标记时，它就简单去掉首尾空白。

数据流：输入是一段文本。它查找 USER_MESSAGE_BEGIN 这个固定开头；找到了就从开头后面截取并修剪空白，找不到就直接修剪原文。输出是一段借用原文本的干净字符串切片。

调用关系：它被 apply_event_msg 和 user_message_preview 使用。前者用它生成标题，后者用它生成消息预览。

调用图：被 2 处调用（apply_event_msg, user_message_preview）。

fn user_message_preview(user: &UserMessageEvent) -> Option<String>

作用：这个函数给一条用户消息生成列表里能看到的简短预览。文字优先；如果没有文字但有图片，就用“[Image]”提醒用户这是一条图片消息。

数据流：输入是 UserMessageEvent。它先用 strip_user_message_prefix 清理消息文本；如果文本不空，就返回这段文本。如果文本为空，但远程图片或本地图片列表不空，就返回固定占位符“[Image]”。如果什么都没有，就返回 None。

调用关系：它由 apply_event_msg 在处理用户消息时调用。它把“用户到底发了什么”这个判断集中在一处，避免标题和预览规则到处散落。

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

fn enum_to_string(value: &T) -> String

作用：这个通用小工具把枚举值转成普通字符串，方便写进数据库或拿来展示。这里的“枚举”可以理解成一组选项中的一个，比如审批模式是 never 还是 on-request。

数据流：输入是任何可以序列化的值。它先用 serde_json 转成 JSON 值；如果结果本来就是字符串，就直接取出字符串；如果是其它 JSON 形态，就转成文字；如果转换失败，就返回空字符串。

调用关系：它被 apply_session_meta_from_item 和 apply_turn_context 使用，也被其它构建或测试代码使用。它把“各种选项怎么变成字符串”的规则统一起来。

调用图：被 4 处调用（apply_session_meta_from_item, apply_turn_context, build, test_thread_metadata）；外部调用 2 个（new, to_value）。

fn response_item_user_messages_do_not_set_title_or_first_user_message()

作用：这个测试确认：ResponseItem 里的 user 角色消息不能被当成真正的用户输入来设置标题或第一条用户消息。

数据流：它先造一份测试元数据，再造一个看起来像用户消息的 ResponseItem。调用 apply_rollout_item 后，检查 first_user_message、preview 和 title 都没有变化。

调用关系：它通过 apply_rollout_item 走正式流程，间接验证 apply_response_item 目前不改任何元数据。这防止以后有人误把模型回复格式里的内容拿来做线程标题。

调用图：调用 1 个内部函数（apply_rollout_item）；外部调用 4 个（assert_eq!, ResponseItem, metadata_for_test, vec!）。

fn event_msg_user_messages_set_title_and_first_user_message()

作用：这个测试确认：真正的用户事件消息会设置第一条用户消息、预览和标题。

数据流：它创建一条带 USER_MESSAGE_BEGIN 前缀的用户消息事件。调用 apply_rollout_item 后，检查三个字段都变成去掉前缀后的“actual user request”。

调用关系：它验证 apply_rollout_item 分发到 apply_event_msg 后，user_message_preview 和 strip_user_message_prefix 能一起把用户输入清理并写入元数据。

调用图：调用 1 个内部函数（apply_rollout_item）；外部调用 7 个（default, assert_eq!, format!, UserMessage, EventMsg, metadata_for_test, vec!）。

fn event_msg_image_only_user_message_sets_image_placeholder_preview()

作用：这个测试确认：用户只发图片、没发文字时，系统仍然会给线程一个可读预览。

数据流：它造一条消息正文为空但带图片 URL 的用户事件。调用 apply_rollout_item 后，检查 first_user_message 和 preview 都是固定的“[Image]”，而 title 仍然为空。

调用关系：它重点验证 user_message_preview 的图片兜底规则，并确认 apply_event_msg 不会用图片占位符生成标题。

调用图：调用 1 个内部函数（apply_rollout_item）；外部调用 7 个（default, new, assert_eq!, UserMessage, EventMsg, metadata_for_test, vec!）。

fn event_msg_blank_user_message_without_images_keeps_first_user_message_empty()

作用：这个测试确认：只有空白文字、也没有图片的用户消息，不应该生成假预览。

数据流：它构造一条内容只有空格、图片列表为空的用户事件。调用 apply_rollout_item 后，检查 first_user_message、preview 和 title 都保持为空。

调用关系：它验证 user_message_preview 和 strip_user_message_prefix 对空内容的处理，防止列表里出现没有意义的空标题或空预览。

调用图：调用 1 个内部函数（apply_rollout_item）；外部调用 6 个（default, assert_eq!, UserMessage, EventMsg, metadata_for_test, vec!）。

fn event_msg_thread_goal_sets_preview_only_and_later_user_sets_message_title()

作用：这个测试确认：线程目标可以先当预览，但不会冒充用户消息或标题；后来的用户消息仍然能设置第一条用户消息和标题。

数据流：它先送入一个目标更新事件，预览变成“optimize the benchmark”，但 first_user_message 和 title 为空。接着送入正常用户消息，预览保持原目标不被覆盖，first_user_message 和 title 则变成新用户消息。

调用关系：它验证 apply_event_msg 中 ThreadGoalUpdated 和 UserMessage 两条路径的配合，也验证 set_preview_if_empty 的“不覆盖已有预览”规则。

调用图：调用 1 个内部函数（apply_rollout_item）；外部调用 8 个（default, assert_eq!, format!, ThreadGoalUpdated, UserMessage, EventMsg, metadata_for_test, vec!）。

fn turn_context_does_not_override_session_cwd()

作用：这个测试确认：会话信息里已经有工作目录时，后来的轮次上下文不能把它覆盖掉。

数据流：它先把元数据目录清空，再应用一条会话信息，把目录设为 /child/worktree。随后应用一条轮次上下文，里面有另一个目录 /parent/workspace。最后检查目录仍是会话里的值，同时检查权限配置和审批模式被正确写入。

调用关系：它通过 apply_rollout_item 先后触发 apply_session_meta_from_item 和 apply_turn_context，验证两者在 cwd 字段上的优先级。

调用图：调用 2 个内部函数（from_string, apply_rollout_item）；外部调用 7 个（from, new, now_v7, assert_eq!, SessionMeta, TurnContext, metadata_for_test）。

fn turn_context_sets_permission_profile_metadata()

作用：这个测试确认：轮次上下文里的权限配置会被保存到元数据里。

数据流：它创建一份 workspace_write 权限配置，并把它放进 TurnContextItem。调用 apply_rollout_item 后，检查 metadata.sandbox_policy 等于这份权限配置序列化后的 JSON 字符串。

调用关系：它验证 apply_turn_context 使用 permission_profile 并转成字符串的行为，确保数据库里保存的是最终权限配置，而不是旧的或默认的沙箱字段。

调用图：调用 2 个内部函数（workspace_write, apply_rollout_item）；外部调用 4 个（from, assert_eq!, TurnContext, metadata_for_test）。

fn turn_context_sets_cwd_when_session_cwd_missing()

作用：这个测试确认：如果会话信息没有工作目录，轮次上下文可以作为备用来源补上目录。

数据流：它先把测试元数据的 cwd 清空，再应用一个带 /fallback/workspace 的 TurnContextItem。调用后检查 cwd 被设置为这个备用目录。

调用关系：它验证 apply_turn_context 的补缺逻辑：只在元数据原来没有 cwd 时才写入。

调用图：调用 1 个内部函数（apply_rollout_item）；外部调用 6 个（from, new, new_read_only_policy, assert_eq!, TurnContext, metadata_for_test）。

fn turn_context_sets_model_and_reasoning_effort()

作用：这个测试确认：轮次上下文会记录使用的模型和推理强度。

数据流：它创建一个 TurnContextItem，模型是 gpt-5，推理强度是 High。调用 apply_rollout_item 后，检查 metadata.model 和 metadata.reasoning_effort 都被正确设置。

调用关系：它验证 apply_turn_context 对模型相关字段的写入，和另一个测试一起说明 SessionMeta 不负责这些字段。

调用图：调用 1 个内部函数（apply_rollout_item）；外部调用 5 个（from, new_read_only_policy, assert_eq!, TurnContext, metadata_for_test）。

fn session_meta_does_not_set_model_or_reasoning_effort()

作用：这个测试确认：会话信息不会设置具体模型和推理强度，因为这些属于轮次上下文。

数据流：它应用一条 SessionMetaLine，里面有会话来源、目录、版本和模型提供商等信息。调用后检查 metadata.model 和 metadata.reasoning_effort 仍然是 None。

调用关系：它验证 apply_session_meta_from_item 的边界，防止它越权写入应该由 apply_turn_context 维护的字段。

调用图：调用 1 个内部函数（apply_rollout_item）；外部调用 4 个（from, assert_eq!, SessionMeta, metadata_for_test）。

fn metadata_for_test() -> ThreadMetadata

作用：这个测试辅助函数生成一份稳定的 ThreadMetadata，方便所有测试从同一个起点开始。

数据流：它创建固定线程 ID、固定创建时间和一批默认字段，比如 rollout 路径、来源、模型提供商、工作目录、token 数等。输出是一份可被测试修改的 ThreadMetadata。

调用关系：大多数测试都会先调用它，再把不同的 RolloutItem 应用上去。它让测试只关注要验证的那一两个字段，不用每次重复搭建完整元数据。

调用图：调用 1 个内部函数（from_string）；外部调用 4 个（from_timestamp, from, new, from_u128）。

fn diff_fields_detects_changes()

作用：这个测试确认 ThreadMetadata 的字段差异检测能找出哪些字段变了。

数据流：它先造一份基础元数据，再复制一份并改掉 title 和 tokens_used。调用 diff_fields 后，检查返回的变更字段正好是 title 和 tokens_used。

调用关系：它不直接测试本文件的提取函数，而是验证 ThreadMetadata 自身的比较能力；这对判断哪些元数据需要写回数据库很有帮助。

调用图：调用 1 个内部函数（from_string）；外部调用 3 个（now_v7, assert_eq!, metadata_for_test）。

async fn archive_thread(
    store: &LocalThreadStore,
    params: ArchiveThreadParams,
) -> ThreadStoreResult<()>

作用：把指定线程对应的本地会话文件移动到归档目录，并尽量更新状态数据库里的记录。有人点击“归档线程”或上层接口收到归档请求时，就会走到这里。

数据流：输入是本地线程仓库 store 和归档参数 params，里面最重要的是 thread_id。它先读取仓库配置和可选的状态数据库上下文，用线程编号找到原来的会话文件；接着检查路径是否安全、文件名是否匹配这个线程；然后创建归档文件夹，把原文件改名移动到归档位置；最后如果有状态数据库，就写入新的文件路径和当前归档时间。成功时没有返回数据，只表示事情办完；找不到线程、路径不对或移动失败时返回错误。

调用关系：它是本文件的核心动作，会被上层的归档入口调用。它自己把工作拆给几个帮手：state_db 取数据库上下文，find_thread_path_by_id_str 找会话文件，scoped_rollout_path 做路径安全检查，matching_rollout_file_name 确认文件名对应目标线程；真正落到磁盘上时交给 create_dir_all 建目录、rename 移动文件；最后用 now 取当前时间写入归档时间。

调用图：调用 3 个内部函数（state_db, matching_rollout_file_name, scoped_rollout_path）；被 1 处调用（archive_thread）；外部调用 4 个（now, find_thread_path_by_id_str, create_dir_all, rename）。

async fn archive_thread_moves_rollout_to_archived_collection()

作用：这个测试确认最基本的归档行为：归档后，原来的活跃会话文件不见了，归档目录里出现同一个文件，并且列表查询能把它当成已归档线程看到。

数据流：它先创建一个临时 home 目录，做一个本地线程仓库，再写入一个假的会话文件。然后调用归档功能。调用之后，它检查原路径已经不存在，归档路径已经存在；再用 list_threads 按“只看归档”的方式查询，确认返回的线程编号、文件路径和归档时间都符合预期。

调用关系：它围绕 archive_thread 做端到端检查，也就是不只看函数返回成功，还检查磁盘文件和线程列表这两个外部可见结果。它会用 test_config 准备测试配置，用 write_session_file 造测试会话文件，用 from_string 和 from_u128 准备固定线程编号。

调用图：调用 4 个内部函数（from_string, new, test_config, write_session_file）；外部调用 5 个（new, from_u128, new, assert!, assert_eq!）。

async fn archive_thread_updates_sqlite_metadata_when_present()

作用：这个测试确认如果系统启用了 SQLite 状态数据库，归档线程时数据库里的线程位置和归档时间也会被更新。SQLite 是一种本地小型数据库，这里用来保存线程索引信息。

数据流：它先建临时目录和测试配置，写入一个假的活跃会话文件；再初始化状态数据库，把一条线程元数据写进去。随后调用归档功能。最后它从数据库重新读取这条线程记录，检查 rollout_path 已经变成归档目录下的新路径，并且 archived_at 归档时间已经有值。

调用关系：它验证 archive_thread 和状态数据库之间的配合。测试前半段用 StateRuntime 初始化数据库，用 ThreadMetadataBuilder 拼出一条线程记录并 upsert_thread 写入；测试核心仍然是调用归档；测试后半段用 get_thread 读回数据库，确认 archive_thread 在移动文件之后确实调用了数据库的归档标记能力。

调用图：调用 6 个内部函数（from_string, new, init, new, test_config, write_session_file）；外部调用 5 个（new, now, from_u128, assert!, assert_eq!）。

async fn unarchive_thread(
    store: &LocalThreadStore,
    params: ArchiveThreadParams,
) -> ThreadStoreResult<StoredThread>

作用：把指定 ID 的归档对话恢复成普通对话。调用者给它一个对话 ID，它负责找到归档文件、搬回正确位置、更新状态，并返回恢复后的对话摘要信息。

数据流：输入是本地存储对象 store 和包含 thread_id 的参数。它先读取可能存在的状态数据库上下文，再按对话 ID 查归档文件；然后检查归档路径是否安全、文件名是否匹配这个对话、文件名里是否能拆出日期。确认无误后，它创建目标日期目录，把文件从归档目录移动到普通会话目录，刷新文件修改时间；如果有状态数据库，就把数据库记录改成未归档并更新路径。最后它重新读取恢复后的会话文件，把文件内容转成 StoredThread 输出；任何关键步骤失败都会变成清楚的 ThreadStoreError。

调用关系：这是恢复归档对话的核心步骤，通常由本地线程存储的对外 unarchive_thread 接口触发。它自己不直接解析所有细节，而是把找归档文件交给 find_archived_thread_path_by_id_str，把路径安全检查交给 scoped_rollout_path，把文件名检查交给 matching_rollout_file_name，把日期拆分交给 rollout_date_parts，把最终会话文件读取交给 read_thread_item_from_rollout，再用 stored_thread_from_rollout_item 变成系统内部统一使用的对话对象。

调用图：调用 5 个内部函数（state_db, matching_rollout_file_name, scoped_rollout_path, stored_thread_from_rollout_item, touch_modified_time）；被 1 处调用（unarchive_thread）；外部调用 6 个（find_archived_thread_path_by_id_str, read_thread_item_from_rollout, rollout_date_parts, format!, create_dir_all, rename）。

async fn unarchive_thread_restores_rollout_and_returns_updated_thread()

作用：验证最基本的恢复归档流程真的可用。它确认归档文件会消失，普通会话目录会出现恢复后的文件，并且返回的对话信息显示为未归档。

数据流：测试先创建一个临时目录，搭一个本地存储对象，再写入一份假的归档会话文件。随后调用 store.unarchive_thread。调用之后，它检查旧归档路径不存在、新的 sessions/2025/01/03 路径存在，并检查返回的线程 ID、文件路径、归档时间、预览文字和第一条用户消息都符合预期。

调用关系：这个测试像一次完整彩排，直接走公开的本地存储恢复接口，而不是只测内部小函数。它用 test_config 准备测试配置，用 write_archived_session_file 造出归档文件，然后通过断言来证明 unarchive_thread 把文件移动和返回结果都做好了。

调用图：调用 4 个内部函数（from_string, new, test_config, write_archived_session_file）；外部调用 4 个（new, from_u128, assert!, assert_eq!）。

async fn unarchive_thread_updates_sqlite_metadata_when_present()

作用：验证当系统启用了 SQLite 状态库时，恢复归档不只是移动文件，也会同步更新数据库里的元数据。这样列表页或搜索功能以后看到的状态才不会还是“已归档”。

数据流：测试先建临时目录和配置，写入一份归档会话文件，再初始化状态数据库运行时。它手工往数据库里插入一条已归档的对话元数据。接着调用 store.unarchive_thread。最后它从数据库重新读这条记录，确认数据库里的 rollout_path 已经变成恢复后的普通会话路径，archived_at 也变成空，表示不再归档。

调用关系：这个测试覆盖的是带数据库的分支。它先用 StateRuntime::init 建好本地状态库，再用元数据构建器造出一条已归档记录；当恢复接口运行后，它检查内部调用 mark_unarchived 的效果是否真的落到数据库里，防止文件系统和数据库状态不一致。

调用图：调用 6 个内部函数（from_string, new, init, new, test_config, write_archived_session_file）；外部调用 4 个（new, now, from_u128, assert_eq!）。

async fn update_thread_metadata(
    store: &LocalThreadStore,
    params: UpdateThreadMetadataParams,
) -> ThreadStoreResult<StoredThread>

作用：这是修改线程元数据的主入口。别人想改线程名字、Git 信息、记忆模式等，都会把线程编号和补丁交给它。

数据流：输入是本地线程仓库、线程编号、补丁内容和是否允许查归档线程；它先判断补丁是不是空，再更新 SQLite 里的元数据，必要时同步 rollout 日志文件、名字索引和 Git 信息；最后读回一个最新的 StoredThread 返回。如果中途发现线程不存在、路径不对或关键写入失败，就返回错误。

调用关系：它像总调度员一样串起整个流程：先问 needs_rollout_compatibility_update 和 sqlite_write_failure_should_block 要不要做额外兼容工作，再把主要写库工作交给 apply_metadata_update，之后按需要调用 resolve_rollout_path、apply_thread_memory_mode、apply_thread_name、apply_thread_git_info_to_rollout、apply_thread_git_info，最后用 read_thread 或 read_thread_by_rollout_path 读回结果。

调用图：调用 17 个内部函数（reconcile_rollout, state_db, git_info_from_parts, persist_thread, rollout_path, read_thread, read_thread_by_rollout_path, apply_metadata_update, apply_thread_git_info, apply_thread_git_info_to_rollout (+7 more)）；被 1 处调用（update_thread_metadata）；外部调用 1 个（format!）。

async fn refresh_resolved_rollout_path(resolved: &mut ResolvedRolloutPath)

作用：这个函数用来刷新已经找到的 rollout 文件路径。因为写入或归档后，实际文件路径可能被系统换成另一个现存路径。

数据流：输入是一个可修改的 ResolvedRolloutPath；它拿当前路径去查是否有更准确的现存 rollout 路径；如果查到了，就把里面的 path 替换掉，不返回额外结果。

调用关系：update_thread_metadata 在往 rollout 追加记忆模式或 Git 信息后会叫它检查路径，避免后续步骤还拿着旧路径继续写。

调用图：被 1 处调用（update_thread_metadata）；外部调用 1 个（existing_rollout_path）。

async fn apply_metadata_update(
    store: &LocalThreadStore,
    thread_id: ThreadId,
    patch: ThreadMetadataPatch,
    include_archived: bool,
    require_sqlite_write: bool,
) -> ThreadStoreResul

作用：这个函数负责把补丁里的大部分元数据写进 SQLite 状态库，并读回更新后的线程。它是主入口里最核心的“改目录卡片”步骤。

数据流：输入是仓库、线程编号、补丁、是否包含归档线程，以及 SQLite 写失败是否必须中断；它会找当前 rollout 路径，读取旧元数据，没有时按补丁和 rollout 文件创建一条新元数据，然后逐个字段覆盖更新；最后写回数据库，并读取线程返回。它可能修改 SQLite 中的线程行和记忆模式记录。

调用关系：update_thread_metadata 会先调用它完成基础更新。它内部会借助 resolve_rollout_path 找文件，调用 enum_to_string、normalize_cwd、memory_mode_as_str 做格式转换，还会用 resolve_git_info_patch 合并 Git 局部补丁；最后交给 read_thread 读回结果。

调用图：调用 11 个内部函数（state_db, git_info_from_parts, permission_profile_to_metadata_value, rollout_path, read_thread, enum_to_string, memory_mode_as_str, normalize_cwd, resolve_git_info_patch, resolve_rollout_path (+1 more)）；被 1 处调用（update_thread_metadata）；外部调用 2 个（clone, warn!）。

fn needs_rollout_compatibility_update(patch: &ThreadMetadataPatch) -> bool

作用：这个函数判断这次更新是否还需要写一份到 rollout 日志里，照顾老的读取方式。不是所有字段都需要这样做。

数据流：输入是一份元数据补丁；它检查是否改了名字、记忆模式或 Git 信息，以及补丁是否已经包含从会话中观察到的普通元数据；输出一个布尔值，表示要不要做 rollout 兼容更新。

调用关系：update_thread_metadata 在写完 SQLite 前后用它决定是否还要追加 rollout 记录、更新名字索引或同步 Git 信息。它会把“是不是观察型元数据”的判断交给 has_observed_metadata_facts。

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

fn sqlite_write_failure_should_block(patch: &ThreadMetadataPatch) -> bool

作用：这个函数判断 SQLite 写失败时，这次请求是不是必须失败。它保护一个重要边界：可选索引坏了，不应该轻易影响原始会话日志的可靠保存。

数据流：输入是一份补丁；它判断是否是“只显式更新 Git 信息”这类必须依赖 SQLite 旧值的情况；输出 true 表示 SQLite 失败要拦住整个更新，false 表示可以只记警告。

调用关系：update_thread_metadata 调用它，把结果传给 apply_metadata_update。它也用 has_observed_metadata_facts 区分普通观察元数据和显式 Git-only 更新。

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

fn sqlite_write_error_is_best_effort(err: &ThreadStoreError) -> bool

作用：这个函数判断某个 SQLite 写入错误能不能当作“尽力而为”的失败处理。也就是说，是否只报警、不一定让用户操作失败。

数据流：输入是 ThreadStoreError；它检查错误类型，目前内部错误被视为可降级；输出布尔值。

调用关系：apply_metadata_update 在 SQLite 更新失败后调用它，再结合 sqlite_write_failure_should_block 的结果决定是返回错误还是只打 warn 日志。

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

fn has_observed_metadata_facts(patch: &ThreadMetadataPatch) -> bool

作用：这个函数检查补丁里有没有“从真实会话观察出来”的元数据，比如预览、模型、时间、工作目录、token 用量等。它用来区分普通同步信息和用户明确发起的特殊修改。

数据流：输入是一份补丁；它逐项查看许多字段是否出现；只要有一个观察型字段存在，就输出 true，否则输出 false。

调用关系：needs_rollout_compatibility_update 和 sqlite_write_failure_should_block 都依赖它做分流：有观察型事实时，通常不需要额外 rollout 兼容写入，也不会让 SQLite 可选失败过度影响流程。

调用图：被 2 处调用（needs_rollout_compatibility_update, sqlite_write_failure_should_block）。

fn enum_to_string(value: &T) -> String

作用：这个小工具把枚举值转成字符串。枚举可以理解成一组选项，比如来源类型、审批模式等。

数据流：输入是一个可序列化的值；它先用 JSON 方式转成通用值，如果本来就是字符串就取字符串，否则取 JSON 文本，失败时给空字符串；输出字符串。

调用关系：apply_metadata_update 用它把 source、approval_mode 这类选项保存到 SQLite 元数据里，避免数据库里存复杂对象。

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

fn normalize_cwd(cwd: PathBuf) -> PathBuf

作用：这个函数把工作目录路径整理成更标准的样子。比如把路径里的“child/..”这类绕路写法折叠掉。

数据流：输入是一个 PathBuf 路径；它尝试用路径规范化工具清理路径，成功就返回清理后的路径，失败就保留原路径；不改磁盘文件。

调用关系：apply_metadata_update 在保存 cwd，也就是当前工作目录时调用它。这样后面按目录筛选线程时，不会因为同一个目录有不同写法而匹配不上。

调用图：被 1 处调用（apply_metadata_update）；外部调用 2 个（as_path, normalize_for_path_comparison）。

async fn apply_thread_git_info(
    store: &LocalThreadStore,
    thread_id: ThreadId,
    sha: &Option<String>,
    branch: &Option<String>,
    origin_url: &Option<String>,
) -> ThreadStoreResult<()

作用：这个函数把最终确定的 Git 信息写进 SQLite。Git 信息包括提交号、分支名和仓库地址。

数据流：输入是仓库、线程编号，以及可能为空的 sha、branch、origin_url；它拿到状态库后执行更新；输出成功或错误。如果数据库不可用，或线程元数据在更新前消失，就返回内部错误。

调用关系：update_thread_metadata 在已经把 Git 信息写进 rollout 后调用它，确保 SQLite 目录卡片也和日志一致。

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

fn resolve_git_info_patch(
    existing: Option<GitInfo>,
    git_info: GitInfoPatch,
) -> (Option<String>, Option<String>, Option<String>)

作用：这个函数把“只改部分 Git 字段”的补丁补全成完整结果。比如只改分支时，提交号和仓库地址要沿用旧值。

数据流：输入是旧 Git 信息和新的 GitInfoPatch；它分别处理提交号、分支、仓库地址三个字段：补丁里明确给了就用补丁，没给就用旧值；输出三个最终字段。

调用关系：apply_metadata_update 写 SQLite 时会用它合并 Git 补丁；update_thread_metadata 在兼容写 rollout 前也会用它，保证追加到日志里的 Git 信息不会意外丢字段。

调用图：被 2 处调用（apply_metadata_update, update_thread_metadata）。

async fn apply_thread_git_info_to_rollout(
    rollout_path: &Path,
    thread_id: ThreadId,
    sha: &Option<String>,
    branch: &Option<String>,
    origin_url: &Option<String>,
    memory_mode: Op

作用：这个函数把 Git 信息追加写到 rollout 会话日志里。这样即使以后从原始日志重建状态，也能看到最新 Git 信息。

数据流：输入是 rollout 文件路径、线程编号、Git 三个字段和可选记忆模式；它先读取日志开头的会话元信息，确认里面的线程编号和要改的一致；然后填入 Git 信息和记忆模式，再把一条新的 SessionMeta 记录追加到文件末尾；输出成功或错误。

调用关系：update_thread_metadata 在需要兼容 rollout 的 Git 更新时调用它。它依赖 read_session_meta_line 读旧元信息，依赖 append_rollout_item_to_path 追加新记录。

调用图：被 1 处调用（update_thread_metadata）；外部调用 4 个（append_rollout_item_to_path, read_session_meta_line, format!, SessionMeta）。

async fn apply_thread_name(
    store: &LocalThreadStore,
    thread_id: ThreadId,
    name: String,
) -> ThreadStoreResult<()>

作用：这个函数更新线程名字，并把名字放进专门的名字索引里，方便以后快速查到。名字就像给一段聊天贴上的标题标签。

数据流：输入是仓库、线程编号和新名字；它如果有 SQLite，就先更新数据库里的 title；然后在 codex_home 下追加名字索引记录；输出成功或错误。

调用关系：update_thread_metadata 在补丁里包含 name 时调用它。它一边维护 SQLite，一边调用 append_thread_name 维护旧的 rollout 名字索引。

调用图：调用 1 个内部函数（state_db）；被 1 处调用（update_thread_metadata）；外部调用 2 个（append_thread_name, format!）。

async fn apply_thread_memory_mode(
    rollout_path: &Path,
    thread_id: ThreadId,
    memory_mode: ThreadMemoryMode,
) -> ThreadStoreResult<()>

作用：这个函数把线程的记忆模式写进 rollout 日志。记忆模式表示这个线程是否启用长期记忆。

数据流：输入是 rollout 路径、线程编号和 Enabled/Disabled 这样的模式；它读取会话元信息并核对线程编号，然后清空本条记录里的 Git 字段以避免误覆盖，只写 memory_mode，最后追加一条 SessionMeta 到日志；输出成功或错误。

调用关系：update_thread_metadata 在补丁包含 memory_mode 且需要 rollout 兼容时调用它。它内部用 memory_mode_as_str 把模式转成文本，并用 append_rollout_item_to_path 写文件。

调用图：调用 1 个内部函数（memory_mode_as_str）；被 1 处调用（update_thread_metadata）；外部调用 4 个（append_rollout_item_to_path, read_session_meta_line, format!, SessionMeta）。

fn memory_mode_as_str(mode: ThreadMemoryMode) -> &'static str

作用：这个函数把记忆模式选项转成固定字符串。数据库和日志里需要的是文字，而不是程序里的枚举值。

数据流：输入是 ThreadMemoryMode；Enabled 变成 "enabled"，Disabled 变成 "disabled"；输出静态字符串。

调用关系：apply_metadata_update 写 SQLite 的记忆模式时会用它；apply_thread_memory_mode 写 rollout 日志时也会用它，保证两边用同一套文字。

调用图：被 2 处调用（apply_metadata_update, apply_thread_memory_mode）。

async fn resolve_rollout_path(
    store: &LocalThreadStore,
    thread_id: ThreadId,
    include_archived: bool,
) -> ThreadStoreResult<ResolvedRolloutPath>

作用：这个函数负责找到某个线程对应的 rollout 文件在哪里。没有这个文件路径，就没法从原始会话日志验证或追加元数据。

数据流：输入是仓库、线程编号和是否允许查归档；它先看 live_writer 里有没有正在使用的路径，再查普通会话文件，必要时查归档会话文件；输出路径和它是否归档。找不到或查找失败就返回请求错误。

调用关系：update_thread_metadata 和 apply_metadata_update 都会在需要真实文件位置时调用它。它会使用 rollout_path_is_archived 判断路径是否在归档目录中，并借助 find_thread_path_by_id_str、find_archived_thread_path_by_id_str 搜索文件。

调用图：调用 3 个内部函数（state_db, rollout_path, rollout_path_is_archived）；被 2 处调用（apply_metadata_update, update_thread_metadata）；外部调用 4 个（find_archived_thread_path_by_id_str, find_thread_path_by_id_str, format!, to_string）。

fn rollout_path_is_archived(store: &LocalThreadStore, path: &Path) -> bool

作用：这个函数判断一个 rollout 路径是不是在归档目录下面。归档线程要保持归档状态，不能因为更新元数据又被当成普通线程。

数据流：输入是仓库和一个路径；它检查路径是否以 codex_home 下的归档会话目录开头；输出 true 或 false。

调用关系：resolve_rollout_path 用它给找到的路径打上 archived 标记；apply_metadata_update 也间接依赖这个标记决定新建 SQLite 元数据时是否填 archived_at。

调用图：被 1 处调用（resolve_rollout_path）；外部调用 1 个（starts_with）。

async fn update_thread_metadata_sets_name_on_active_rollout_and_indexes_name()

作用：这个测试确认给普通活动线程改名后，读回线程能看到新名字，名字索引也能查到新名字。

数据流：它创建临时目录和一份会话文件，调用 update_thread_metadata 设置 name，然后读取返回线程和名字索引；期望两边都变成指定名字。

调用关系：它覆盖 update_thread_metadata、apply_thread_name 以及 append_thread_name 这条路径，证明改名不只写数据库，也兼容旧索引。

调用图：调用 4 个内部函数（from_string, new, test_config, write_session_file）；外部调用 5 个（default, new, from_u128, assert_eq!, find_thread_name_by_id）。

async fn update_thread_metadata_sets_memory_mode_on_active_rollout()

作用：这个测试确认给活动线程设置记忆模式时，rollout 日志和 SQLite 都会记录下来。

数据流：它准备临时会话文件和状态库，调用更新接口把 memory_mode 设为 disabled，然后检查返回线程、最后一条 rollout 记录和数据库里的记忆模式。

调用关系：它主要验证 update_thread_metadata 调用 apply_metadata_update 和 apply_thread_memory_mode 后，两种存储都保持一致。

调用图：调用 5 个内部函数（from_string, init, new, test_config, write_session_file）；外部调用 5 个（default, new, from_u128, assert_eq!, last_rollout_item）。

async fn update_thread_metadata_preserves_memory_mode_when_updating_git_info()

作用：这个测试确认更新 Git 信息时，不会把之前设置好的记忆模式弄丢。

数据流：它先把记忆模式设为 disabled，再只更新 Git 分支；随后检查 rollout 最后一条记录同时包含 disabled 和新分支，并重新 reconcile 后确认数据库仍保留记忆模式。

调用关系：它验证 update_thread_metadata 在 Git 更新前读取旧 memory_mode，并传给 apply_thread_git_info_to_rollout，避免 Git 更新覆盖记忆模式。

调用图：调用 6 个内部函数（from_string, reconcile_rollout, init, new, test_config, write_session_file）；外部调用 5 个（default, new, from_u128, assert_eq!, last_rollout_item）。

async fn update_thread_metadata_uses_live_rollout_path_for_external_resume()

作用：这个测试确认线程如果是从外部 rollout 文件恢复的，更新元数据时会写到那个外部文件，而不是误写到默认目录。

数据流：它在外部临时目录创建会话文件，先 resume_thread 让仓库记住这个 live 路径，再设置记忆模式；最后检查外部文件末尾确实追加了记录。

调用关系：它覆盖 resolve_rollout_path 优先使用 live_writer::rollout_path 的行为，保证外部恢复线程也能被正确更新。

调用图：调用 4 个内部函数（from_string, new, test_config, write_session_file）；外部调用 7 个（default, new, from_u128, assert!, assert_eq!, last_rollout_item, test_thread_metadata）。

async fn update_thread_metadata_sets_git_info()

作用：这个测试确认可以一次性写入完整 Git 信息：提交号、分支和仓库地址。

数据流：它创建线程和状态库，传入包含三个 Git 字段的补丁；返回线程后检查 git_info 里的三个值都正确。

调用关系：它验证 update_thread_metadata、resolve_git_info_patch、apply_thread_git_info_to_rollout 和 apply_thread_git_info 组成的 Git 写入链路。

调用图：调用 5 个内部函数（from_string, init, new, test_config, write_session_file）；外部调用 4 个（default, new, from_u128, assert_eq!）。

async fn update_thread_metadata_sets_permission_profile()

作用：这个测试确认权限配置会被正确保存。权限配置可以理解成系统允许这段会话做哪些操作的安全档位。

数据流：它创建线程和状态库，更新 permission_profile 为 Disabled，然后检查返回线程和 SQLite 里的 sandbox_policy 都反映这个设置。

调用关系：它覆盖 apply_metadata_update 对 permission_profile_to_metadata_value 的使用，保证程序类型和数据库文本之间转换正确。

调用图：调用 5 个内部函数（from_string, init, new, test_config, write_session_file）；外部调用 4 个（default, new, from_u128, assert_eq!）。

async fn update_thread_metadata_partially_updates_git_info()

作用：这个测试确认 Git 信息可以只改一个字段，并保留其他旧字段。

数据流：它先写入完整 Git 信息，再只把分支改成 feature；读回后期望提交号和仓库地址仍是旧值，只有分支变了。

调用关系：它直接验证 resolve_git_info_patch 的核心意义：局部补丁不是整块替换，不会误删没提到的 Git 字段。

调用图：调用 5 个内部函数（from_string, init, new, test_config, write_session_file）；外部调用 4 个（default, new, from_u128, assert_eq!）。

async fn update_thread_metadata_clears_git_info_fields()

作用：这个测试确认 Git 字段可以被明确清空，并且后续设置记忆模式不会把已清空的 Git 信息“复活”。

数据流：它先写完整 Git 信息，再用 Some(None) 清空三个字段，检查返回线程没有 Git 信息、rollout 里 git 是空对象；之后多次 reconcile、更新记忆模式、删除 SQLite 行并局部更新，确认清空和局部恢复的行为都符合预期。

调用关系：它覆盖 resolve_git_info_patch、apply_thread_git_info_to_rollout、apply_thread_memory_mode 和 reconcile_rollout 的组合边界，防止 Git 信息在不同存储之间来回同步时出错。

调用图：调用 6 个内部函数（from_string, reconcile_rollout, init, new, test_config, write_session_file）；外部调用 6 个（default, new, from_u128, assert!, assert_eq!, last_rollout_item）。

async fn update_thread_metadata_rejects_mismatched_session_meta_id()

作用：这个测试确认如果 rollout 文件里的会话编号和要更新的线程编号对不上，系统会拒绝写入。

数据流：它创建会话文件后故意把文件内容里的编号改成另一个编号，再尝试设置记忆模式；期望得到内部错误，并且错误信息包含 metadata id mismatch。

调用关系：它验证 apply_thread_memory_mode 里的安全检查，避免把一个线程的元数据误写进另一个线程的日志。

调用图：调用 4 个内部函数（from_string, new, test_config, write_session_file）；外部调用 6 个（default, new, from_u128, assert!, read_to_string, write）。

async fn update_thread_metadata_applies_combined_explicit_patch()

作用：这个测试确认一次补丁里同时改名字、记忆模式和 Git 信息时，三件事都会正确完成。

数据流：它创建线程和状态库，提交一个包含 name、memory_mode、git_info 的补丁；随后检查返回线程、rollout 末尾记录、名字索引和数据库记忆模式。

调用关系：它覆盖 update_thread_metadata 的综合调度能力，证明 apply_thread_name、apply_thread_memory_mode、apply_thread_git_info_to_rollout 等步骤可以一起协作。

调用图：调用 5 个内部函数（from_string, init, new, test_config, write_session_file）；外部调用 6 个（default, new, from_u128, assert_eq!, find_thread_name_by_id, last_rollout_item）。

fn sqlite_failures_are_best_effort_for_legacy_rollout_compat_updates()

作用：这个测试确认老式兼容更新里的 SQLite 失败不会默认阻断流程，比如改名字或记忆模式。

数据流：它构造只包含 name 或 memory_mode 的补丁，调用 sqlite_write_failure_should_block；期望结果都是 false。

调用关系：它验证 sqlite_write_failure_should_block 的容错策略，确保可选状态库坏掉时，不会让兼容 rollout 的更新显得像原始日志保存失败。

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

fn sqlite_failures_are_best_effort_for_observed_metadata_updates()

作用：这个测试确认从会话里观察到的普通元数据更新，即使带有 Git 或记忆模式，也不要求 SQLite 失败时阻断。

数据流：它构造带 updated_at 的补丁，以及带 preview、git_info、memory_mode 的补丁；调用 sqlite_write_failure_should_block，期望都是 false。

调用关系：它验证 has_observed_metadata_facts 对 sqlite_write_failure_should_block 的影响，保证观察型同步保持“尽力而为”。

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

fn sqlite_failures_still_block_for_explicit_git_only_updates()

作用：这个测试确认只显式更新 Git 信息时，SQLite 写失败仍然必须阻断。

数据流：它构造只包含 git_info 的补丁并调用 sqlite_write_failure_should_block；期望返回 true。

调用关系：它保护 Git 局部更新的正确性，因为只改 Git 某个字段时必须读旧值，SQLite 不可靠就不能随便继续。

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

async fn metadata_patch_applies_title_over_existing_name()

作用：这个测试确认后来的 title 补丁会覆盖之前用户设置的 name。这里 title 是从会话内容推导出的标题。

数据流：它先给线程设置一个用户名字，再提交包含 title 和 preview 的补丁；最后读回线程，期望名字显示为新的 title。

调用关系：它验证 apply_metadata_update 中 name 和 title 的覆盖顺序：如果补丁里有 title，最终 title 字段以后者为准。

调用图：调用 5 个内部函数（from_string, init, new, test_config, write_session_file）；外部调用 4 个（default, new, from_u128, assert_eq!）。

async fn metadata_patch_applies_latest_preview_and_first_user_message()

作用：这个测试确认数据库会保存最新的预览和第一条用户消息，同时读线程时仍可能以 rollout 内容为准显示。

数据流：它先写一版 preview 和 first_user_message，再写另一版；随后检查返回线程的展示值来自会话文件里的实际用户消息，同时检查 SQLite 元数据保存的是后写入的值。

调用关系：它揭示 read_thread 和 SQLite 元数据之间的分工：apply_metadata_update 会更新目录卡片，但读出的展示字段可能由原始 rollout 内容重新计算。

调用图：调用 5 个内部函数（from_string, init, new, test_config, write_session_file）；外部调用 4 个（default, new, from_u128, assert_eq!）。

async fn observed_metadata_rejects_unknown_thread_without_rollout()

作用：这个测试确认不能凭空给不存在的线程创建观察型元数据。必须先有真实 rollout 文件证明这个线程存在。

数据流：它只创建状态库，不创建会话文件，然后尝试更新 preview；期望返回 thread not found，并确认 SQLite 里没有新元数据。

调用关系：它验证 apply_metadata_update 在缺少旧记录和 rollout 路径时会调用 resolve_rollout_path，并在找不到线程时拒绝创建幽灵记录。

调用图：调用 4 个内部函数（from_string, init, new, test_config）；外部调用 4 个（default, new, from_u128, assert!）。

async fn update_thread_metadata_recreates_missing_archived_sqlite_row_as_archived()

作用：这个测试确认归档线程即使 SQLite 行丢了，重新创建元数据时也会保留归档状态。

数据流：它只创建归档会话文件和状态库，然后更新 preview；读回线程和数据库后，都应看到 archived_at 有值。

调用关系：它验证 resolve_rollout_path 返回的 archived 标记会被 apply_metadata_update 用来设置新元数据的 archived_at。

调用图：调用 5 个内部函数（from_string, init, new, test_config, write_archived_session_file）；外部调用 4 个（default, new, from_u128, assert!）。

async fn observed_metadata_normalizes_cwd_for_list_filters()

作用：这个测试确认保存工作目录时会规范化路径，之后按目录筛选线程才能匹配到。

数据流：它创建 workspace/child/.. 这种不规整路径，更新为 cwd；然后检查 SQLite 里保存的是规范化后的 workspace，并用 list_threads 的 cwd_filters 成功筛到该线程。

调用关系：它验证 normalize_cwd 在 apply_metadata_update 中的作用，也证明规范化结果会被列表查询使用。