pub(crate) struct App { // 整个 TUI 应用的状态容器，crate 内可见——不对外暴露    feature_write_lock: Arc<tokio::sync::Mutex<()>>, // 功能开关写入互斥锁：多个异步任务改配置时串行化    model_catalog: Arc<ModelCatalog>, // 模型目录共享给所有子组件，Arc 保证跨任务只读复用    pub(crate) session_telemetry: SessionTelemetry, // 会话级遥测（第44讲刚拆过），挂在 App 上随生命周期走    pub(crate) app_event_tx: AppEventSender, // 应用事件发送端：UI 侧所有"请求"都从这里发出去    pub(crate) chat_widget: ChatWidget, // 聊天主组件直接内嵌——不是指针，是值，所有权清晰    workspace_command_runner: Option<WorkspaceCommandRunner>, // 工作区命令执行器，按需启用所以用 Option    /// Legacy bootstrap and server-setting inputs; local preferences live in `local_settings`. // 官方注释：旧式启动参数归 config，本地偏好已迁到 local_settings    pub(crate) config: Config, // 全局配置快照（模型、审批策略等），启动时固化    pub(crate) local_settings: crate::local_settings::LocalSettings, // 用户本地设置，与服务器下发的 config 分离存储    pub(crate) file_search: FileSearchManager, // @文件搜索管理器：composer 里打 @ 补全靠它    pub(crate) transcript_cells: Vec<Arc<dyn HistoryCell>>, // 转录历史用 trait object 单元格列表——每种消息类型一个实现    native_history: native_history::NativeHistory, // 原生终端滚动缓冲区的镜像，用于跨会话回溯    turn_tips: turn_tips::TurnTips, // 每轮对话的小提示（tips）状态机    pub(crate) transcript_view: crate::transcript_view::TranscriptView, // 转录的"视图层"：把单元格列表映射成可渲染的行    conversation_frame: owned_transcript::ConversationFrame, // 当前会话帧：持有本轮对话的完整结构    // Alternate-screen overlays: transcript, diff, and analytics. // 官方注释：全屏覆盖层三选一——转录/diff/分析面板    pub(crate) overlay: Option<Overlay>, // 覆盖层用 Option 表达"当前没有"，而不是空枚举    pub(crate) retained_analytics: Option<Box<crate::analytics::AnalyticsView>>, // 分析视图堆上分配（体积大），关闭时整体释放    pub(crate) enhanced_keys_supported: bool, // 终端是否支持增强键盘协议（区分 Shift+Enter 等）    pub(crate) keymap: RuntimeKeymap, // 运行时键位映射：用户可改，所以不能是编译期常量    pub(crate) key_chord_matcher: KeyChordMatcher, // 组合键匹配器：支持多键序列（chord）绑定    /// The foreground loop owns stream pacing; stopped animations have no timer. // 官方注释：动画计时器归前台循环管，停摆时不占定时器资源    pub(crate) commit_animation: Option<tokio::time::Interval>, // 提交动画的节拍器，Option 表示"当前无动画"    pub(crate) backtrack: crate::app_backtrack::BacktrackState, // Esc 回溯状态：撤销到上一轮对话    app_server_target: AppServerTarget, // 后端形态：内嵌进程/本地守护/远程——三种部署方式统一抽象    reconnect: reconnect::ReconnectState, // 断线重连状态机，事件循环里专门有一个分支等它}

let control = select! { // 八分支竞争：哪个 future 先就绪就执行哪个，其余挂起    result = async { // 分支1：后台守护进程重启任务（可选）        match app.daemon_restart.as_mut() { // 有重启任务才参与竞争            Some(task) => task.await, // 等待重启完成            None => std::future::pending().await, // 没有任务就永远挂起——select! 的惯用"禁用分支"写法        }    }, if app.daemon_restart.is_some() => { // select! 的条件守卫：None 时该分支直接不参与竞争        ... // 重启失败则往聊天区塞一条错误消息，循环继续    }    Some(event) = app_event_rx.recv() => { // 分支2：应用事件队列——UI 发出的所有请求（提交、切会话…）都走这里        let switch_backend = match &event { // 先判断是否要切换后端（多 backend 场景）            AppEvent::ChooseNewSessionCheckout { name } | AppEvent::NewSession { name } // 新建会话事件                if multi_backend => app.other_new_session_backend(&backends).await // 在另一个 backend 上开新会话                    .map(|owner| (owner, NewBackendSession::Fresh { name: name.clone() })), // 映射成"新建会话"指令：名字克隆一份交给新 backend            _ => None, // 其他事件不触发后端切换        };        ... // 普通事件走 app.handle_event(tui, session, event)——统一入口    }    active = async { // 分支3：活跃线程的实时事件（流式输出等）        if let Some(rx) = app.active_thread_rx.as_mut() { rx.recv().await } else { None } // 有活跃线程就收一条事件；没有则返回 None（配合守卫，该分支不触发）    }, if App::should_handle_active_thread_events( // 守卫1：初始会话配置完成前不处理            waiting_for_initial_session_configured, // 是否还在等初始会话配置            app.active_thread_rx.is_some() // 是否存在活跃线程事件源        ) && !has_pending_app_events && !app.reconnect.offline => { // 守卫2/3：有排队事件或离线时让位        ... // handle_active_thread_event——流式 token 就是从这里进 UI 的    }    event = tui_events.next(), if app.pending_thread_switch_resets == 0 // 分支4：终端输入（按键/粘贴/鼠标）——本讲主角        && (!app.side_retention_enabled(tui) || app_event_rx.is_empty()) // 守卫：线程切换重置期间冻结输入        && (app.reconnect.offline || !block_terminal_input_for_pending_startup_events) => { // 离线时放行，在线且有启动事件排队时拦截        match app.handle_tui_event(tui, backends.session_at_mut(displayed_session), event).await {            Ok(control) => control, // 正常：按键被路由到 ChatWidget/BottomPane（第四节细讲）            Err(err) if app.recover_transport_error(&err) => AppRunControl::Continue, // 传输层错误可恢复则继续            Err(err) => break Err(err), // 致命错误：退出循环        }    }    (owner, app_server_event) = backends.next_event(paused_backend) => { // 分支5：后端推送事件（turn 完成、审批请求…）        ... // handle_polled_backend_event；流断了则触发重连    }    (reconnect_owner, result) = async { /* 等待重连 future */ }, if reconnect.is_some() => { // 分支6：断线重连结果        ... // 成功恢复事件流；失败则把用户输入还回 composer（见下）    }    () = async { /* pending_resize 到点才就绪 */ } => { // 分支7：终端尺寸遥测——15秒防抖窗口        ... // 尺寸稳定后才上报，避免拖动窗口时刷爆遥测    }    () = async { /* rate_limit_poll_deadline 到点才就绪 */ }, if backends.is_listening(displayed_owner) => { // 分支8：限流额度定时刷新        app.refresh_rate_limits(..., RateLimitRefreshOrigin::Periodic); // 周期性拉取剩余额度，驱动 UI 提示    }}

#[derive(Clone, Debug)] // Clone 很关键：任何组件都能复制一份句柄来请求重绘pub struct FrameRequester { // "帧请求器"——对外只暴露两个方法，内部调度完全隐藏    frame_schedule_tx: mpsc::UnboundedSender<Instant>, // 只持有一个无界发送端——轻量到可以到处传}impl FrameRequester { // 实现块：构造 + 两个请求入口    pub fn new(draw_tx: broadcast::Sender<()>) -> Self { // draw_tx 是广播通道：主循环订阅它来触发渲染        let (tx, rx) = mpsc::unbounded_channel(); // 请求端用无界队列——请求重绘绝不能阻塞 UI        let scheduler = FrameScheduler::new(rx, draw_tx); // 调度器任务接管接收端        tokio::spawn(scheduler.run()); // 独立 task：actor 模式的"handler"        Self { frame_schedule_tx: tx }    }    pub fn schedule_frame(&self) { // "尽快画一帧"——动画、状态变化都调它        let _ = self.frame_schedule_tx.send(Instant::now()); // 发送失败（接收端已丢）直接忽略：重绘请求丢了无所谓    }    pub fn schedule_frame_in(&self, dur: Duration) { // "N毫秒后画一帧"——延迟动画、定时刷新用        let _ = self.frame_schedule_tx.send(Instant::now() + dur); // 目标时刻随消息一起传过去，调度器统一裁决    }}// FrameScheduler：把大量请求合并成一次通知（coalescing）async fn run(mut self) { // 调度器主循环：独立 task，跑完所有发送端 drop 才退出    const ONE_YEAR: Duration = Duration::from_secs(60 * 60 * 24 * 365); // 一年≈"永不超时"，没有待办时挂起    let mut next_deadline: Option<Instant> = None; // 当前最早的重绘时刻    loop { // 无限循环：睡→收请求→睡…直到被 drop        let target = next_deadline.unwrap_or_else(|| Instant::now() + ONE_YEAR); // 有待办就睡到那个点，没有就睡一年        let deadline = tokio::time::sleep_until(target.into()); // sleep_until 可被新请求提前唤醒        tokio::pin!(deadline); // pin 到栈上：select! 要求 future 有固定地址        tokio::select! { // 二选一：收到新请求 vs 睡到点            draw_at = self.receiver.recv() => { // 收到新的重绘请求                let Some(draw_at) = draw_at else { break }; // 所有发送端都 drop 了→调度器退出                let draw_at = self.rate_limiter.clamp_deadline(draw_at); // 120FPS 限速：太近的请求被钳制到合法时刻                next_deadline = Some(next_deadline.map_or(draw_at, |cur| cur.min(draw_at))); // 取最早时刻——多请求合并成一帧                continue; // 关键注释（源码原话）：不立即发送，回到循环重算睡眠目标，            } // 让多个请求在同一个 sleep 分支里"攒"成一次 draw            _ = &mut deadline => { // 睡到了最早的重绘时刻                if next_deadline.is_some() { // 确实有待办才发通知（防止空转）                    next_deadline = None; // 清空待办——下一轮从"无计划"状态重新开始                    self.rate_limiter.mark_emitted(Instant::now()); // 记录本次发射，供下次限速计算                    let _ = self.draw_tx.send(()); // 广播"该画了"——主循环的 TuiEventStream 会把它变成 Draw 事件                }            }        }    }}

pub enum TuiEvent { // 事件流里的所有"东西"——输入、渲染、焦点，统一成一个枚举    Key(KeyEvent), // 按键（经过 focus/paste/协议簿记处理后的干净事件）    Paste(String), // 括号粘贴（bracketed paste）载荷：一次粘一大段不会被拆成 N 个字符    Mouse(MouseEvent), // 鼠标交互：选中、滚动、点链接    Resize(Size), // 终端尺寸变化——官方注释特意说明它与 Draw 分开，                  // 这样 app 层可以对 resize 跑特性门控的预渲染逻辑而不影响普通帧    Draw, // 计划好的重绘（FrameRequester 发来的），不一定伴随尺寸变化    Resume, // 进程从挂起恢复后的第一帧——挂起期间收不到 resize，必须主动刷新几何    FocusGained, // 终端/标签页重新获得焦点    FocusLost, // 失去焦点（配合"未读通知"逻辑：失焦时来消息就弹桌面通知）}

pub(crate) struct BottomPane { // 界面下半部分的总容器：composer + 弹窗栈 + 状态行    /// Composer is retained even when a BottomPaneView is displayed so the // 官方注释：弹窗打开时 composer 依然保留，    /// input state is retained when the view is closed. // 关掉弹窗后草稿、光标位置原样还在    composer: ChatComposer, // 输入框本体——永远存在，只是可能被视图栈"盖住"    /// Stack of views displayed instead of the composer (e.g. popups/modals). // 官方注释：显示在 composer 之上的视图栈（弹窗/模态）    view_stack: Vec<Box<dyn BottomPaneView>>, // trait object 栈：每种弹窗一个实现，push/pop 即开合    pub(crate) key_chord_reset_requested: bool, // 组合键状态重置标记——切视图后旧的半按状态必须作废    warnings_view: Option<warnings_view::WarningsView>, // 警告面板（独立于栈：它不抢占输入焦点）    pub(crate) questions: Option<Box<AsyncQuestions>>, // 异步问答组件（agent 反问用户时展开）    delayed_approval_requests: VecDeque<DelayedApprovalRequest>, // 延迟审批请求队列：打字时不打断，空闲了再弹    last_composer_activity_at: Option<Instant>, // 最后一次输入活动时刻——上面"延迟审批"的计时基准    app_event_tx: AppEventSender, // 弹窗也要发应用事件（比如确认某个操作）    frame_requester: FrameRequester, // 弹窗自己请求重绘——不需要知道主循环在哪    has_input_focus: bool, // 输入焦点归属：composer 还是某个视图    is_task_running: bool, // agent 是否在跑任务（影响 Enter 的语义：提交 vs 排队）    status: Option<StatusIndicatorWidget>, // composer 上方的状态指示器（"正在思考…"）}

fn push_view(&mut self, view: Box<dyn BottomPaneView>) { // 打开一个弹窗 = 压栈    self.key_chord_reset_requested = true; // 先作废所有半按的组合键——防止旧按键状态泄漏进新视图    self.view_stack.push(view); // 入栈，成为新的"活跃视图"    self.schedule_active_view_frame(); // 给新视图调度一帧（它可能有动画入场）    self.request_redraw(); // 请求整体重绘：composer 被盖住、焦点转移}fn pop_active_view_with_completion(&mut self, completion: Option<ViewCompletion>) { // 关闭顶层视图并上报结果    if self.view_stack.pop().is_some() { // 出栈成功才处理后续逻辑        match completion { // 按"关闭结果"分三种语义处理            Some(ViewCompletion::Accepted) => { // 用户"接受"了（比如确认了设置）                while self // 级联检查：父视图是否声明"子项被接受后我也该关"                    .view_stack // 取栈顶（新的顶层视图）                    .last() // 拿最后一个元素                    .is_some_and(|view| view.dismiss_after_child_accept()) // 问它：孩子被接受了，你要不要一起走？                {                    self.view_stack.pop(); // 是就继续弹——一次操作可能关掉一整串嵌套弹窗                }            }            Some(ViewCompletion::Cancelled) => { // 用户"取消"：父视图保留，但清掉它的级联标记                if let Some(view) = self.view_stack.last_mut() { // 拿到新的栈顶（原来的父视图）                    view.clear_dismiss_after_child_accept(); // 防止下次误触发级联关闭                }            }            None => {} // 无结果（比如 Esc 直接关掉）：什么都不做        }        self.on_view_stack_depth_decreased(); // 栈变浅了：重置组合键，空栈则触发"视图完成"回调    }}

/// Result returned when the user interacts with the text area. // 官方注释：用户与文本区交互的结果#[derive(Debug, PartialEq)] // 派生 Debug/PartialEq——测试里大量用 matches! 断言结果pub enum InputResult { // composer 的"出口协议"：UI 层据此决定下一步动作    Submitted { // "立即提交"——普通对话输入走这里        text: String, // 最终文本（已展开粘贴、处理过 mention）        text_elements: Vec<TextElement>, // 富文本元素：@mention、图片引用等结构化片段    },    Queued { // "排队"——agent 正在跑任务时按 Enter，输入先入队不发送        text: String, // 排队的文本内容        text_elements: Vec<TextElement>, // 随文本一起保存的富元素        action: QueuedInputAction, // 出队时的动作：Literal（原样）还是 SlashCommand（解析斜杠命令）        pending_pastes: Vec<(String, String)>, // 尚未展开的粘贴片段，随队列一起保存    },    /// A bare slash command parsed by the composer. // 官方注释：裸斜杠命令（/diff、/model…）    Command(SlashCommand), // 不带参数的内置命令——直接执行，不进对话    ServiceTierCommand(ServiceTierCommand), // 模型服务档位命令（切换 service tier）}

fn handle_submission_with_time(&mut self, should_queue: bool, now: Instant) -> (InputResult, bool) { // Enter 总调度：should_queue 由上层根据"任务是否在跑"决定    self.handle_paste_burst_flush(now); // 先冲刷"粘贴爆发"：快速连续粘贴的片段合并成一次    if !should_queue && self.handle_paste_enter(now) { // 粘贴刚结束就按 Enter？那是误触，吞掉这次提交        return (InputResult::None, true); // None=本次无动作；true=事件已消费，别再往下传    }    if let Some(result) = self.handle_parent_owned_submission() { // 父组件托管的输入（如问答框）优先处理        return result; // 父组件已经接管了这次提交，直接返回它的结果    }    if should_queue { // agent 正在跑任务 → 本次输入排队，等本轮结束再发        ... // 快照当前文本/元素/粘贴片段，决定出队时按 Literal 还是斜杠命令解析        return (InputResult::Queued { text, text_elements, action, pending_pastes }, true); // ✅ 排队结果：带上出队策略一起返回    }    // If the first line is a bare built-in slash command (no args), // 官方注释：首行是裸内置斜杠命令时，    // dispatch it even when the slash popup isn't visible. // 即使补全弹窗没显示也要派发——保留 /di→Tab→Enter 的工作流    if let Some(result) = self.try_dispatch_bare_slash_command() { // 尝试派发裸斜杠命令（/diff、/model 等无参内置命令）        return (result, true); // Tab 补全后光标移走了、弹窗隐藏了，但 Enter 仍应执行命令而非发送字面文本    }    let visible_shell_command = self.is_bang_shell_command(); // ! 前缀的 shell 命令单独识别    let original_input = self.current_text(); // 提交前快照原文——校验失败时要原样恢复    ... // （省略：元素/mention/附件等其余快照字段，见源码）    if let Some((text, text_elements)) = self.prepare_submission_text(/*record_history*/ true) { // 生成最终文本（展开粘贴、记录历史）        if self.slash_commands_enabled() && text.starts_with('!') && !visible_shell_command { // 斜杠命令功能开着 + 以 ! 开头 + 不是显式 shell 命令 → 特殊处理            (InputResult::Queued { ..., action: QueuedInputAction::Literal, ... }, true) // 斜杠命令开着时，! 开头按字面排队（不当 shell 跑）        } else {            // Do not clear local attachments here; ChatWidget drains them via // 官方注释：本地附件不在这里清，            // take_recent_submission_images(). // 由 ChatWidget 统一取走——职责分离            (InputResult::Submitted { text, text_elements }, true) // ✅ 真正的提交结果        }    } else {        let flash = self.footer.flash.take(); // 校验失败：恢复被抑制的输入，保留校验反馈闪烁        self.set_text_content_with_mention_bindings(original_input, ...); // 用快照还原文本/mention/附件        (InputResult::None, true) // 本次提交作废，用户看到原文还在、错误提示在闪    }}

match input_result { // ChatWidget 对 composer 结果的总分发    InputResult::Submitted { text, text_elements } => { // ✅ 立即提交分支：拿到最终文本和富元素        let user_message = self.user_message_from_submission(text, text_elements); // 组装 UserMessage（文本+图片+mention）        if user_message.text.is_empty() && ... { return; } // 全空直接丢弃——不产生空气泡        self.app_event_tx.send(AppEvent::FollowTranscript); // 提交前先让转录视图"跟随到底部"        let should_submit_now = self.is_session_configured() // 闸门1：会话已配置好            && !self.is_plan_streaming_in_tui() // 闸门2：plan 流没在输出中            && !self.input_queue.submissions_paused() // 闸门3：提交队列没被暂停（如审批等待）            && !self.input_queue.rate_limit_recovery_pending // 闸门4：限流恢复流程没在进行            && (!self.input_queue.user_turn_pending_start || self.turn_lifecycle.agent_turn_running); // 闸门5：上一轮要么还没开始、要么已在跑（可 steer）        if should_submit_now { // 五道闸门全过 → 立即提交路径            ... // （省略：shell-only 场景的排队特判，见源码）            self.submit_user_message(user_message); // ✅ 通过全部闸门 → 真正提交        } else {            self.queue_user_message(user_message); // 任一闸门不过 → 入队，等条件满足再发（不丢输入）        }    }}

pub(super) fn submit_user_message(&mut self, user_message: UserMessage) { // 最外层入口：普通用户输入    let _accepted = self.submit_user_message_with_history_record( // 带历史记录语义的提交（这条文本要进跨会话历史）        user_message, // 要发送的用户消息本体        UserMessageHistoryRecord::UserMessageText, // 记录类型=纯用户文本（区别于"覆盖式"回答）    ); // accepted 返回值这里不关心——失败反馈由内部处理}pub(super) fn submit_user_message_with_history_record(...) -> bool { // 中间层：固定 ShellEscapePolicy::Allow + Source::Prompt    self.submit_user_message_with_history_and_shell_escape_policy( // 继续下沉到最底层实现        user_message, history_record, // 消息本体 + 历史记录类型一起下沉        ShellEscapePolicy::Allow, // 允许 ! shell 转义（safety recourse 路径会传 Disallow）        UserMessageSource::Prompt, // 来源标记=用户键入——影响遥测和 turn_trigger    ).0 // 取元组第一个元素 accepted——调用方只关心"是否被接受"}// 最底层：组装 AppCommand（节选，input_submission.rs 第 492-510 行附近）let op = AppCommand::user_turn( // 构造"用户回合"命令——UI 与 core 之间的契约类型    if source == UserMessageSource::SafetyRecourse { "safety_recourse_follow_up" } else { "user" }, // turn_trigger：安全救济路径单独标记，便于审计区分    client_user_message_id.clone(), // 客户端生成的消息 ID——core 回包时用它对齐（乐观渲染的关键）    items, // Vec<UserInput>：文本+图片等结构化输入项    self.config.cwd.to_path_buf(), // 工作目录快照——回合在哪个目录跑就锁死哪个    AskForApproval::from(self.config.permissions.approval_policy.value()), // 审批策略随命令下发，core 侧执行时按它拦截    active_permission_profile, // 当前权限档案（沙箱级别等）    effective_mode.model().to_string(), // 模型名——UI 选哪个就发哪个，core 不再猜    effective_mode.reasoning_effort(), // 推理强度（effort），Option 表示"用默认"    /*summary*/ None, service_tier, /*final_output_json_schema*/ None, collaboration_mode, // 其余可选参数显式传值——不留隐式默认);// AppCommand::user_turn 只是构造器（app_command.rs:227）：pub(crate) fn user_turn(turn_trigger: &'static str, client_user_message_id: String, ...) -> Self { // 构造器签名：参数即 UserTurn 变体的全部字段（... 为省略）    Self::UserTurn { turn_trigger, client_user_message_id, items, cwd, ... } // 填充枚举变体——AppCommand 是 UI→core 的全部命令空间}

提交路径（Enter → core）

▼

▼

▼

▼

▼

▼

▼