专用交互流程与辅助 TUI 处理器

fn new() -> Self

作用：创建一个全新的应用状态，给终端界面第一次启动时用。它把列表、弹窗、加载标记、默认提示文字等都放到一个安全的初始状态。

数据流：进去没有外部输入 → 它新建空任务列表、把选中位置设为 0、设置状态文字“Press r to refresh”，并把各种弹窗和后台加载标记清空 → 出来一个可以直接交给主界面循环使用的 App。

调用关系：它会被 run_main 在程序启动时调用，相当于先搭好舞台。它内部会创建空集合等基础容器，之后用户刷新、切换任务、打开详情时都会不断改动这个 App。

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

fn next(&mut self)

作用：把任务列表里的选中项往下移一格。用户按“向下”或类似快捷键时会需要它。

数据流：进去的是当前 App，其中包含任务列表和当前选中的序号 → 如果列表为空就什么也不做；否则把 selected 加 1，但不会超过最后一条 → 出来是同一个 App，只是选中位置可能变了。

调用关系：它属于界面导航的小动作。调用图没有显示直接调用者，但通常会由键盘事件处理代码在用户想选下一条任务时调用。

fn prev(&mut self)

作用：把任务列表里的选中项往上移一格。用户按“向上”或类似快捷键时会用到它。

数据流：进去的是当前 App → 如果列表为空就不动；如果当前不是第一条，就把 selected 减 1 → 出来是同一个 App，选中位置最多往前移动一格。

调用关系：它和 App::next 配成一对，负责列表上下移动。调用图没有显示直接调用者，但它通常会被主界面的按键处理部分使用。

async fn load_tasks(
    backend: &dyn CloudBackend,
    env: Option<&str>,
) -> anyhow::Result<Vec<TaskSummary>>

作用：从云任务后端拉取任务列表，并按当前环境筛选。它还会过滤掉只用于 review 的任务，让主列表只显示普通任务。

数据流：进去的是一个 CloudBackend（云任务后端接口）和可选的环境 id → 它最多等 5 秒，请后端列出最多 20 个任务，然后丢掉 is_review 为真的任务 → 出来是一个任务摘要列表；如果超时或后端报错，就返回错误。

调用关系：run_main 会在需要刷新列表时调用它；测试 tests::load_tasks_uses_env_parameter 也会调用它验证环境参数没有丢。它把真正联网或取数据的工作交给 backend.list_tasks，并用 timeout 给这次请求加上时间限制，避免界面一直卡住。

调用图：被 2 处调用（load_tasks_uses_env_parameter, run_main）；外部调用 3 个（from_secs, list_tasks, timeout）。

fn has_diff(&self) -> bool

作用：判断某一次尝试有没有代码改动内容。界面可以用它决定是否显示 diff 相关入口或提示。

数据流：进去的是一个 AttemptView → 它检查 diff_lines 这个列表是不是空 → 出来是 true 或 false，true 表示有可展示的代码改动行。

调用关系：调用图没有显示直接调用者。它是 AttemptView 上的便捷判断，供详情界面或渲染代码在需要区分“有改动”和“没改动”时使用。

fn has_text(&self) -> bool

作用：判断某一次尝试有没有文字输出或原始提示。也就是看它是否有可以在“Prompt/输出”视图里展示的内容。

数据流：进去的是一个 AttemptView → 它检查 text_lines 是否非空，或者 prompt 是否存在 → 出来是布尔值，表示有没有文字内容。

调用关系：调用图没有显示直接调用者。它和 AttemptView::has_diff 类似，是给界面判断展示状态用的小工具。

fn new(task_id: TaskId, title: String, attempt_total_hint: Option<usize>) -> Self

作用：创建一个新的任务详情弹层，用来显示某个任务的提示、输出和代码改动。用户打开任务详情时需要这样一个容器。

数据流：进去的是任务 id、标题，以及可能知道的尝试总数 → 它创建一个空的 ScrollableDiff（可滚动的文本区域），放入一个默认尝试，并默认停在 Prompt 视图 → 出来是一个准备好但内容还可能为空的 DiffOverlay。

调用关系：调用图显示它会创建 ScrollableDiff 和向量。它通常由打开详情的流程使用，之后后台加载到的 diff、消息和尝试列表会填进这个弹层。

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

fn current_attempt(&self) -> Option<&AttemptView>

作用：取出当前选中的那一次尝试。详情页有多次尝试时，很多操作都要先知道用户现在看的是哪一次。

数据流：进去的是 DiffOverlay → 它用 selected_attempt 作为下标去 attempts 列表里找 → 出来是当前 AttemptView 的只读引用；如果下标无效，就返回空。

调用关系：DiffOverlay::apply_selection_to_fields 会用它把当前尝试的内容同步到显示区；DiffOverlay::current_can_apply 会用它判断当前尝试有没有可应用的 diff。

调用图：被 2 处调用（apply_selection_to_fields, current_can_apply）。

fn base_attempt_mut(&mut self) -> &mut AttemptView

作用：拿到第一份尝试，并允许修改它。第一份尝试在这里相当于“基础尝试”，详情刚加载时常先把内容塞到这里。

数据流：进去的是可修改的 DiffOverlay → 如果 attempts 为空，它先补一个默认 AttemptView；然后返回 attempts[0] 的可修改引用 → 出来的是可以写入 diff、文本、提示等内容的基础尝试。

调用关系：调用图没有显示直接调用者。它给外部加载详情的代码一个安全入口，避免列表为空时直接写第一项导致出错。

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

fn set_view(&mut self, view: DetailView)

作用：切换详情弹层当前看的页面，比如从“提示/输出”切到“代码改动 diff”。

数据流：进去的是目标 DetailView → 它先记录新视图，再调用 apply_selection_to_fields，把当前尝试对应的内容放进可滚动显示区 → 出来是更新后的 DiffOverlay。

调用关系：它把真正刷新显示内容的活儿交给 DiffOverlay::apply_selection_to_fields。用户按键切换详情页标签时，通常会走到这个函数。

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

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

作用：估算这项任务应该有多少次尝试。它优先用后端给的总数提示；没有提示时，就用当前已经加载到的尝试数量。

数据流：进去的是 DiffOverlay → 它先看 attempt_total_hint；如果没有，再看 attempts 是否为空 → 出来是可选的数量，可能是 Some(数量)，也可能是 None。

调用关系：DiffOverlay::attempt_display_total 会调用它，用来决定界面上显示“第几次 / 共几次”时的总数。

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

fn attempt_count(&self) -> usize

作用：返回当前已经加载到本地的尝试数量。它回答的是“手里现在有几份”，不是后端可能总共有几份。

数据流：进去的是 DiffOverlay → 它读取 attempts 列表长度 → 出来是一个数字。

调用关系：调用图没有显示直接调用者。它适合给界面或调试代码使用，用来展示或判断当前已加载的尝试数。

fn attempt_display_total(&self) -> usize

作用：给界面计算应该显示的尝试总数。它保证即使还没加载到内容，也至少显示成 1，避免出现“共 0 次”这种怪提示。

数据流：进去的是 DiffOverlay → 它调用 expected_attempts；如果拿不到预期总数，就用当前 attempts 长度和 1 里的较大值 → 出来是一个适合展示给用户看的总数。

调用关系：它依赖 DiffOverlay::expected_attempts。通常用于详情页顶部或状态栏，显示当前尝试在总尝试中的位置。

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

fn step_attempt(&mut self, delta: isize) -> bool

作用：在多次尝试之间前后切换。它支持绕圈：在最后一次再往后会回到第一次。

数据流：进去的是一个步长 delta，比如 1 表示下一次，-1 表示上一次 → 如果尝试数不超过 1，就返回 false；否则算出新的 selected_attempt，并刷新显示内容 → 出来是 true 或 false，同时 DiffOverlay 的当前选择和显示区会被更新。

调用关系：它在切换完下标后调用 DiffOverlay::apply_selection_to_fields，确保屏幕内容跟着变。用户按切换尝试的快捷键时会用到它。

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

fn current_can_apply(&self) -> bool

作用：判断当前看到的内容能不能执行“应用补丁”。只有正在看 diff，而且当前尝试确实有原始 diff 文本时，才算可以应用。

数据流：进去的是 DiffOverlay → 它先确认 current_view 是 Diff，再取 current_attempt，看 diff_raw 是否存在且不为空 → 出来是布尔值，true 表示当前可以尝试应用这份改动。

调用关系：它调用 DiffOverlay::current_attempt。界面可以用它决定是否启用 apply 按钮或快捷键，避免用户在没有补丁内容时误操作。

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

fn apply_selection_to_fields(&mut self)

作用：把“当前选中的尝试”和“当前视图”真正同步到显示字段里。可以把它理解成按下电视遥控器后，屏幕内容跟着换台。

数据流：进去的是可修改的 DiffOverlay → 它读取当前 AttemptView 的 diff、文字和提示，复制到 overlay 的公共字段；如果当前看 Diff，就把 diff 行放进 ScrollableDiff，没有则显示“没有 diff”；如果当前看 Prompt，就放文字输出，没有则显示“没有输出” → 出来是显示区内容已刷新后的 DiffOverlay。

调用关系：DiffOverlay::set_view 和 DiffOverlay::step_attempt 都会调用它，因为切换视图或切换尝试后都必须刷新屏幕。它还会调用 current_attempt 和 ScrollableDiff 的 set_content。

调用图：调用 2 个内部函数（current_attempt, set_content）；被 2 处调用（set_view, step_attempt）；外部调用 1 个（vec!）。

fn list_tasks(
            &'a self,
            env: Option<&'a str>,
            limit: Option<i64>,
            cursor: Option<&'a str>,
        ) -> CloudBackendFuture<'a, codex_cloud_tasks_client

作用：测试里用的假后端列任务函数。它不访问真实网络，而是按传入环境返回预先准备好的任务标题。

数据流：进去的是可选环境 id、数量限制和游标 → 它从 by_env 这张表里找对应标题，组装成 TaskSummary，并按限制最多返回指定数量 → 出来是一个假的 TaskListPage，里面有任务列表和传回的 cursor。

调用关系：tests::FakeBackend::get_task_summary 会调用它来从假列表里找单个任务。测试中的 load_tasks 最终也会通过 CloudBackend 接口走到这个假实现，从而验证环境筛选逻辑。

调用图：被 1 处调用（get_task_summary）；外部调用 7 个（pin, now, new, default, new, list_tasks, format!）。

fn get_task_summary(&self, id: TaskId) -> CloudBackendFuture<'_, TaskSummary>

作用：测试里按任务 id 找一条任务摘要。它让假后端看起来更像真实后端。

数据流：进去的是任务 id → 它先调用 tests::FakeBackend::list_tasks 拿默认环境下的假任务，再找 id 相同的那一条 → 找到就返回 TaskSummary，找不到就返回“任务不存在”的错误。

调用关系：它把列任务的工作交给 tests::FakeBackend::list_tasks。调用图没有显示业务测试直接用它，但 CloudBackend 接口要求提供这个能力。

调用图：调用 1 个内部函数（list_tasks）；外部调用 2 个（pin, get_task_summary）。

fn get_task_diff(&self, _id: TaskId) -> CloudBackendFuture<'_, Option<String>>

作用：测试假后端里的“取 diff”占位函数。当前测试不需要它，所以明确返回“未实现”。

数据流：进去的是任务 id，但这里不使用 → 它直接构造一个 Unimplemented 错误 → 出来是失败结果。

调用关系：它是为了满足 CloudBackend 接口而存在。当前 load_tasks_uses_env_parameter 测试只关心列表，不会用到 diff。

调用图：外部调用 2 个（pin, Unimplemented）。

fn get_task_messages(&self, _id: TaskId) -> CloudBackendFuture<'_, Vec<String>>

作用：测试假后端里的“取消息列表”函数。为了简单，它总是返回空消息。

数据流：进去的是任务 id，但这里不使用 → 它返回一个空 Vec，也就是空列表 → 出来是成功结果，表示没有消息。

调用关系：它同样是 CloudBackend 接口的一部分。当前测试不依赖它的内容，只需要假后端能完整实现接口。

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

fn get_task_text(
            &self,
            id: TaskId,
        ) -> CloudBackendFuture<'_, codex_cloud_tasks_client::TaskText>

作用：测试假后端里的“取任务文字详情”函数。它返回一份固定的示例提示和尝试状态。

数据流：进去的是任务 id，但这里不按 id 区分 → 它创建 TaskText，包含 prompt、turn_id、attempt_placement 和 Completed 状态 → 出来是固定的文字详情结果。

调用关系：CloudBackend 的 trait 方法会把请求转给这个假实现。当前环境筛选测试主要不用它，但详情相关代码如果在测试中调用，也能拿到合理的假数据。

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

fn list_sibling_attempts(
            &self,
            _task: TaskId,
            _turn_id: String,
        ) -> CloudBackendFuture<'_, Vec<codex_cloud_tasks_client::TurnAttempt>>

作用：测试假后端里的“列出同一轮的其他尝试”函数。当前不需要多尝试数据，所以返回空列表。

数据流：进去的是任务 id 和 turn_id → 它不查询任何东西，直接返回空 Vec → 出来表示没有兄弟尝试。

调用关系：这是 CloudBackend 接口要求的能力。当前测试没有真正使用它，但有了它，FakeBackend 才能作为完整后端传给通用代码。

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

fn apply_task(
            &self,
            _id: TaskId,
            _diff_override: Option<String>,
        ) -> CloudBackendFuture<'_, codex_cloud_tasks_client::ApplyOutcome>

作用：测试假后端里的“真正应用补丁”占位函数。因为当前测试不做应用补丁，所以它故意返回未实现错误。

数据流：进去的是任务 id 和可选 diff 覆盖内容 → 它不做任何补丁应用，直接返回 Unimplemented 错误 → 出来是失败结果。

调用关系：它用于补齐 CloudBackend 接口。load_tasks_uses_env_parameter 只测试加载列表，因此不会走到这个函数。

调用图：外部调用 2 个（pin, Unimplemented）。

fn apply_task_preflight(
            &self,
            _id: TaskId,
            _diff_override: Option<String>,
        ) -> CloudBackendFuture<'_, codex_cloud_tasks_client::ApplyOutcome>

作用：测试假后端里的“应用前检查”占位函数。应用前检查就是先看看补丁能不能安全应用，但这里不实际支持。

数据流：进去的是任务 id 和可选 diff 覆盖内容 → 它直接返回 Unimplemented 错误 → 出来是失败结果。

调用关系：它和 tests::FakeBackend::apply_task 配套，都是为了满足 CloudBackend 接口。当前测试流程不会调用它。

调用图：外部调用 2 个（pin, Unimplemented）。

fn create_task(
            &'a self,
            _env_id: &'a str,
            _prompt: &'a str,
            _git_ref: &'a str,
            _qa_mode: bool,
            _best_of_n: usize,
        ) ->

作用：测试假后端里的“新建任务”占位函数。当前测试不创建任务，所以它返回未实现错误。

数据流：进去的是环境 id、提示词、git 引用、是否 QA 模式、best-of 数量 → 它不保存也不发送这些信息，直接返回 Unimplemented 错误 → 出来是失败结果。

调用关系：它是 CloudBackend 接口的一部分，用来让 FakeBackend 能传给依赖完整后端的代码。环境筛选测试不会调用它。

调用图：外部调用 2 个（pin, Unimplemented）。

async fn load_tasks_uses_env_parameter()

作用：验证 load_tasks 会把环境参数正确传给后端。简单说，它检查“选了哪个环境，就真的加载哪个环境的任务”。

数据流：进去没有外部输入 → 它先准备一份按环境分组的假数据，再用 FakeBackend 分别请求无环境、env-A、env-B → 出来是测试断言结果：每次返回的任务数量和标题都必须符合对应环境。

调用关系：它直接调用 load_tasks，并通过 FakeBackend 提供可控数据。这个测试保护了环境筛选功能，防止以后改代码时不小心把 env 参数漏传。

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

fn new(env_id: Option<String>, best_of_n: usize) -> Self

作用：创建一个新的“新建任务页面”。调用者可以传入预先选好的环境编号，以及希望生成多少个候选结果再挑最好的次数。

数据流：进去的是 env_id 和 best_of_n：env_id 可能有值，也可能没有；best_of_n 是尝试次数。函数先新建一个输入框 ComposerInput，然后给它塞入几条快捷键提示。最后产出一个 NewTaskPage：里面有配置好的输入框，submitting 被设为 false，表示还没开始提交，同时保存传进来的环境和尝试次数。

调用关系：这是这个页面的主要入口。别的地方需要显示新建任务页面时，会调用它来拿到一份准备好的页面状态。它自己会借用 ComposerInput::new 来做输入框，并用一个列表把快捷键提示一次性放进去。

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

fn default() -> Self

作用：创建一个最基础的新建任务页面，适合调用者没有特别要求时使用。默认不指定环境，并且只尝试 1 次。

数据流：进去没有额外参数。它把“没有环境编号”和“尝试次数为 1”这两个默认值交给 NewTaskPage::new。出来的是一个已经带好输入框和快捷键提示的 NewTaskPage。

调用关系：它是省事用的快捷入口。需要默认页面时，外部代码不用自己想默认值，直接调用它即可；真正的初始化工作仍然交给 NewTaskPage::new 完成。

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

fn draw(frame: &mut Frame, app: &mut App)

作用：这是整个界面的总入口。每次终端需要刷新画面时，它看一眼 App 当前状态，然后决定画任务列表还是新建任务页，再叠加各种弹窗。

数据流：输入是可绘制的 frame 和可读取/修改的 app 状态 → 它先把屏幕切成主区域和底部提示区，再按 app.new_task、diff_overlay、env_modal、best_of_modal、apply_modal 这些状态选择对应画法 → 输出是更新后的终端画面，同时可能更新光标位置或加载动画计时。

调用关系：它站在最外层，运行时由 TUI 主循环反复调用。它把具体绘制工作分给 draw_new_task_page、draw_list、draw_footer、draw_diff_overlay、draw_env_modal、draw_best_of_modal 和 draw_apply_modal。

调用图：调用 8 个内部函数（draw_apply_modal, draw_best_of_modal, draw_diff_overlay, draw_env_modal, draw_footer, draw_list, draw_new_task_page, area）；外部调用 3 个（Length, Min, default）。

fn rounded_enabled() -> bool

作用：这个函数决定弹窗边框要不要用圆角。它让用户可以通过环境变量开关视觉样式。

数据流：输入来自环境变量 CODEX_TUI_ROUNDED → 第一次调用时读取并判断是否等于 1，没设置时默认启用圆角 → 输出一个布尔值，并用 OnceLock 缓存起来，之后不用重复读环境变量。

调用关系：它只被 overlay_block 使用。每次要创建弹窗边框时，overlay_block 会问它该用圆角还是普通方角。

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

fn overlay_outer(area: Rect) -> Rect

作用：这个函数算出弹窗应该放在屏幕中间哪块区域。它相当于给弹窗留出四周边距，避免弹窗贴满全屏。

数据流：输入是整个屏幕或父区域的矩形大小 → 它上下各留 10%、左右各留 10%，取中间 80% 的区域 → 输出一个新的矩形，供弹窗使用。

调用关系：各种弹窗都会先调用它，包括详情弹窗、环境选择、应用确认、并行次数选择。它不画东西，只负责告诉别人“弹窗框放这里”。

调用图：被 4 处调用（draw_apply_modal, draw_best_of_modal, draw_diff_overlay, draw_env_modal）；外部调用 2 个（Percentage, default）。

fn overlay_block() -> Block<'static>

作用：这个函数做出统一风格的弹窗外框。这样所有弹窗看起来像同一套界面，而不是各画各的。

数据流：输入不需要业务数据 → 它创建带边框的 Block，按 rounded_enabled 的结果决定是否圆角，并加上内部留白 → 输出一个可复用的弹窗边框对象。

调用关系：draw_diff_overlay、draw_env_modal、draw_best_of_modal、draw_apply_modal 都靠它画外壳；overlay_content 也用它来计算边框里面真正能放内容的区域。

调用图：调用 1 个内部函数（rounded_enabled）；被 5 处调用（draw_apply_modal, draw_best_of_modal, draw_diff_overlay, draw_env_modal, overlay_content）；外部调用 2 个（default, new）。

fn overlay_content(area: Rect) -> Rect

作用：这个函数计算弹窗边框里面的内容区。简单说，就是扣掉边框和内边距后，文字列表真正能放在哪里。

数据流：输入是弹窗整体矩形 → 它临时创建同样样式的 overlay_block，并取这个块的 inner 区域 → 输出内容区域矩形。

调用关系：所有带弹窗内容的绘制函数都会用它。它保证标题、边框、留白不会挤到正文。

调用图：调用 1 个内部函数（overlay_block）；被 4 处调用（draw_apply_modal, draw_best_of_modal, draw_diff_overlay, draw_env_modal）。

fn draw_new_task_page(frame: &mut Frame, area: Rect, app: &mut App)

作用：这个函数画“新建任务”的输入页面。用户按新建后，看到的标题、环境信息、尝试次数和输入框都由它画出来。

数据流：输入是 frame、要画的区域和 app → 它从 app.new_task 读取当前选择的环境、并行尝试次数和输入框内容，计算输入框需要多高，把输入框固定在页面底部 → 输出是新建任务页面，并把终端光标放到输入框希望的位置。

调用关系：draw 在发现 app.new_task 存在时调用它。它自己不提交任务，只把 composer 这个输入组件渲染出来，让用户继续编辑。

调用图：调用 3 个内部函数（area, buffer_mut, set_cursor_position）；被 1 处调用（draw）；外部调用 8 个（default, Length, Min, default, from, format!, render_widget, vec!）。

fn draw_list(frame: &mut Frame, area: Rect, app: &mut App)

作用：这个函数画主任务列表。用户平时看到的每个任务状态、标题、更新时间和改动摘要，都从这里出来。

数据流：输入是 frame、列表区域和 app → 它把 app.tasks 里的每个任务交给 render_task_item 变成列表项，再根据 app.selected 标出当前选中项；如果有弹窗打开，就把背景列表变暗；如果正在刷新，就在列表中间画加载提示 → 输出是可滚动感的任务列表画面。

调用关系：draw 在没有新建任务页时调用它。它会使用 render_task_item 格式化单个任务，也会在加载时把显示工作交给 draw_centered_spinner。

调用图：调用 1 个内部函数（draw_centered_spinner）；被 1 处调用（draw）；外部调用 12 个（default, Length, Min, default, from, new, default, default, format!, render_stateful_widget (+2 more)）。

fn draw_footer(frame: &mut Frame, area: Rect, app: &mut App)

作用：这个函数画屏幕底部两行：第一行是快捷键提示和加载状态，第二行是状态消息。它让用户随时知道能按什么键、程序正在忙什么。

数据流：输入是 frame、底部区域和 app → 它根据当前是否打开详情、是否能应用改动、是否正在编辑新任务等状态拼出帮助文字；再根据各种 inflight 标志决定是否显示加载小圆点；最后把 app.status 清理成单行状态文字 → 输出是底部提示栏和状态栏。

调用关系：draw 每次刷新都会调用它。它在需要右侧小加载提示时调用 draw_inline_spinner。

调用图：调用 1 个内部函数（draw_inline_spinner）；被 1 处调用（draw）；外部调用 8 个（Fill, Length, default, from, new, format!, render_widget, vec!）。

fn draw_diff_overlay(frame: &mut Frame, area: Rect, app: &mut App)

作用：这个函数画任务详情弹窗。它既能显示代码差异 diff（也就是改了哪些行），也能显示用户和助手的对话内容。

数据流：输入是 frame、屏幕区域和 app → 它读取 app.diff_overlay，判断当前内容能不能应用、是不是失败详情、滚动到哪里、当前看的是 Prompt 还是 Diff；然后画标题、顶部状态栏、尝试次数提示和正文；正文如果是 diff 就按增删行上色，如果是对话就按说话人排版；如果详情还在加载且没内容，就画居中加载提示 → 输出是覆盖在主界面上的详情窗口，并更新滚动内容的宽高设置。

调用关系：draw 在 app.diff_overlay 存在时调用它。它使用 overlay_outer、overlay_block、overlay_content 搭弹窗框架，用 style_diff_line 或 style_conversation_lines 给正文上色，加载时调用 draw_centered_spinner。

调用图：调用 4 个内部函数（draw_centered_spinner, overlay_block, overlay_content, overlay_outer）；被 1 处调用（draw）；外部调用 11 个（Length, Min, default, from, new, from, new, format!, matches!, render_widget (+1 more)）。

fn draw_apply_modal(frame: &mut Frame, area: Rect, app: &mut App)

作用：这个函数画“是否把改动应用到本地”的确认弹窗。它让用户在真正改文件前看到确认、预检查结果和冲突信息。

数据流：输入是 frame、屏幕区域和 app → 它读取 app.apply_modal，显示任务标题和按键提示；如果正在预检查或应用，就显示加载；如果已有结果，就按成功、部分成功或错误给消息上色，并列出冲突文件和跳过文件 → 输出是应用确认/结果弹窗。

调用关系：draw 在 app.apply_modal 存在时调用它。它复用 overlay_outer、overlay_block、overlay_content 来画统一弹窗，忙碌时调用 draw_centered_spinner。

调用图：调用 4 个内部函数（draw_centered_spinner, overlay_block, overlay_content, overlay_outer）；被 1 处调用（draw）；外部调用 10 个（Length, Min, default, from, new, new, format!, matches!, render_widget, vec!）。

fn style_conversation_lines(
    sd: &crate::scrollable_diff::ScrollableDiff,
    attempt: Option<&AttemptView>,
) -> Vec<Line<'static>>

作用：这个函数把一段普通对话文本变成带颜色、带分组的终端显示行。它让 User 和 Assistant 的内容更容易区分。

数据流：输入是 ScrollableDiff 里的已换行文本和当前 attempt 信息 → 它逐行读取原始内容，识别 user:、assistant:、空行、代码块、项目符号和标题；再给每行加左侧竖线、说话人标题、状态标记和 markdown 样式 → 输出一组已经带样式的 Line。

调用关系：它在详情弹窗显示对话视图时被 draw_diff_overlay 间接使用。内部会调用 conversation_header_line、conversation_gutter_span 和 conversation_text_spans 来分别处理标题、左侧栏和正文。

调用图：调用 6 个内部函数（raw_line_at, wrapped_lines, wrapped_src_indices, conversation_gutter_span, conversation_header_line, conversation_text_spans）；外部调用 4 个（from, raw, new, new）。

fn conversation_header_line(
    speaker: ConversationSpeaker,
    attempt: Option<&AttemptView>,
) -> Line<'static>

作用：这个函数生成对话里一段话的标题行，比如“User prompt”或“Assistant response”。它还会给助手回复附上当前尝试的状态。

数据流：输入是说话人类型和可选的 attempt → 它按 User 或 Assistant 选择不同颜色和文字；如果是 Assistant 且有状态，就通过 attempt_status_span 转成状态标签 → 输出一行带样式的标题。

调用关系：style_conversation_lines 遇到 user: 或 assistant: 标记时调用它。它把状态显示这件事再交给 attempt_status_span。

调用图：调用 1 个内部函数（attempt_status_span）；被 1 处调用（style_conversation_lines）；外部调用 2 个（from, vec!）。

fn conversation_gutter_span(speaker: ConversationSpeaker) -> ratatui::text::Span<'static>

作用：这个函数生成对话正文左边的小竖线。它像聊天气泡边框一样，帮助用户看出这行属于谁。

数据流：输入是说话人类型 → 它给 User 用青色竖线，给 Assistant 用紫色竖线 → 输出一个带颜色的 Span。

调用关系：style_conversation_lines 在处理每一行对话正文或空行时调用它。它只负责左侧视觉标记，不处理正文内容。

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

fn conversation_text_spans(
    display: &str,
    in_code: bool,
    is_new_raw: bool,
    bullet_indent: Option<usize>,
) -> Vec<ratatui::text::Span<'static>>

作用：这个函数给对话正文上样式。代码块、项目符号、标题和普通 markdown 文本会用不同方式显示。

数据流：输入是一行要显示的文字，以及它是否在代码块里、是否是原始新行、是否属于项目符号缩进 → 它先处理代码块，再处理列表项和续行，再处理 markdown 标题，最后用 render_markdown_text 给普通文本做基础 markdown 渲染 → 输出这行文字对应的一组带样式片段。

调用关系：style_conversation_lines 会把每一行正文交给它。它依赖 codex_tui::render_markdown_text 来处理普通 markdown 的加粗、链接等基础显示效果。

调用图：被 1 处调用（style_conversation_lines）；外部调用 5 个（raw, new, new, render_markdown_text, vec!）。

fn attempt_status_span(status: AttemptStatus) -> Option<ratatui::text::Span<'static>>

作用：这个函数把一次尝试的状态变成有颜色的短标签。用户可以一眼看出尝试是完成、失败、进行中还是等待中。

数据流：输入是 AttemptStatus 枚举值 → 它按不同状态选择文字和颜色；未知状态不显示 → 输出可选的带样式 Span。

调用关系：conversation_header_line 在生成 Assistant 标题时调用它。它只做状态到显示标签的转换。

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

fn style_diff_line(raw: &str) -> Line<'static>

作用：这个函数给 diff 的每一行上色。新增行变绿，删除行变红，位置标记更醒目。

数据流：输入是一行原始 diff 文本 → 它检查开头符号：@@ 代表位置块，+++ 或 --- 代表文件头，+ 代表新增，- 代表删除，其他就是普通行 → 输出一行带对应颜色或样式的 Line。

调用关系：draw_diff_overlay 在当前详情视图是 Diff 时使用它。它是 diff 可读性的核心小工具。

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

fn render_task_item(_app: &App, t: &codex_cloud_tasks_client::TaskSummary) -> ListItem<'static>

作用：这个函数把一个任务摘要变成列表里的一项。它负责把机器数据整理成用户能扫一眼看懂的几行文字。

数据流：输入是 app 和一个 TaskSummary → 它读取任务状态、标题、环境标签、更新时间和改动摘要；把状态变成彩色标签，把更新时间转成“几分钟前”这种相对时间，把增删行数和文件数排成摘要 → 输出一个 ListItem，供任务列表显示。

调用关系：draw_list 会对 app.tasks 里的每个任务调用它。它使用 format_relative_time_now 把时间戳变成人话。

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

fn draw_inline_spinner(
    frame: &mut Frame,
    area: Rect,
    spinner_start: &mut Option<Instant>,
    label: &str,
)

作用：这个函数画一行小型加载提示，比如“• Loading…”。它用于告诉用户程序还在工作，不是卡死了。

数据流：输入是 frame、要画的位置、加载动画开始时间和标签文字 → 它如果还没有开始时间就记录当前时间，再按经过时间让圆点明暗交替 → 输出是一行加载提示，并可能初始化 spinner_start。

调用关系：draw_footer 直接用它画右下角加载状态；draw_centered_spinner 也借它画居中的加载提示。

调用图：被 2 处调用（draw_centered_spinner, draw_footer）；外部调用 4 个（from, new, render_widget, vec!）。

fn draw_centered_spinner(
    frame: &mut Frame,
    area: Rect,
    spinner_start: &mut Option<Instant>,
    label: &str,
)

作用：这个函数把加载提示放到某个区域正中间。适合列表、弹窗正文这类空白区域里的等待状态。

数据流：输入是 frame、区域、动画开始时间和标签文字 → 它把区域纵向和横向切开，取中间一小块 → 再调用 draw_inline_spinner 在那里画加载文字。

调用关系：draw_list、draw_diff_overlay、draw_apply_modal、draw_env_modal 在等待网络或后台操作时调用它。它自己不决定何时加载，只负责居中显示。

调用图：调用 1 个内部函数（draw_inline_spinner）；被 4 处调用（draw_apply_modal, draw_diff_overlay, draw_env_modal, draw_list）；外部调用 3 个（Length, Percentage, default）。

fn draw_env_modal(frame: &mut Frame, area: Rect, app: &mut App)

作用：这个函数画环境选择弹窗。用户可以搜索环境，选择只看某个环境的任务，或切回全部环境。

数据流：输入是 frame、屏幕区域和 app → 它先画统一弹窗；如果环境还在加载，就显示加载；否则显示操作提示、搜索框，并用搜索词过滤 app.environments；最后把“All Environments”和匹配到的环境列成可选择列表 → 输出是环境选择窗口和当前高亮项。

调用关系：draw 在 app.env_modal 存在时调用它。它复用 overlay_outer、overlay_block、overlay_content，加载时调用 draw_centered_spinner。

调用图：调用 4 个内部函数（draw_centered_spinner, overlay_block, overlay_content, overlay_outer）；被 1 处调用（draw）；外部调用 15 个（default, Length, Min, default, from, new, new, default, new, default (+5 more)）。

fn draw_best_of_modal(frame: &mut Frame, area: Rect, app: &mut App)

作用：这个函数画“并行尝试次数”的选择弹窗。它让用户选择新任务要同时跑 1 到 4 个尝试。

数据流：输入是 frame、屏幕区域和 app → 它在屏幕中央算出一个较小弹窗，显示使用提示和 1、2、3、4 个 attempt 的选项；当前全局 best_of_n 会标成 Current，选中的行会高亮 → 输出是并行尝试次数选择窗口。

调用关系：draw 在 app.best_of_modal 存在时调用它。它也使用 overlay_outer、overlay_block、overlay_content 来保持弹窗风格一致。

调用图：调用 3 个内部函数（overlay_block, overlay_content, overlay_outer）；被 1 处调用（draw）；外部调用 16 个（default, Length, Min, default, from, new, new, default, new, new (+6 more)）。

fn get(&self, thread_id: &ThreadId) -> Option<&AgentPickerThreadEntry>

作用：按线程编号取出这个线程在选择器里的最新资料。别人已经知道要找哪个线程时，就用它查名字、角色、路径、运行状态等信息。

数据流：进去的是一个 ThreadId（线程编号）和当前缓存 → 它去内部表里查这条记录 → 找到就返回这条资料的只读引用，找不到就返回空，不会改动任何状态。

调用关系：它是一个简单查询口。App 或其他 UI 代码需要给某个已知线程画选择器或页脚时，会来这里拿资料；它不把工作交给别的函数。

fn is_empty(&self) -> bool

作用：判断当前有没有记住任何 agent 线程。常用于决定打开选择器时，是显示列表，还是提示“还没有可用 agent”。

数据流：进去的是当前缓存本身 → 它检查内部线程表是不是空 → 出来一个布尔值：空就是 true，不空就是 false；状态不变。

调用关系：这是给外层 App 做快速判断用的小入口。它不依赖别的函数，也不触发 UI 变化，只告诉调用者当前有没有内容。

fn upsert(
        &mut self,
        thread_id: ThreadId,
        agent_nickname: Option<String>,
        agent_role: Option<String>,
        is_closed: bool,
    )

作用：新增或更新一个线程的选择器资料，同时保证它第一次出现时的位置不变。upsert 可以理解成“有就更新，没有就插入”。

数据流：进去的是线程编号、昵称、角色、是否已关闭，以及已有缓存 → 如果这是新线程，就把编号追加到顺序表末尾；然后写入或覆盖这条线程资料；如果之前已有路径和运行状态，会尽量保留，关闭时会把运行状态关掉 → 出来没有返回值，但缓存里的资料被更新，顺序只在第一次出现时增加。

调用关系：这是维护缓存的核心入口之一。App 发现或刷新线程资料时会用它；AgentNavigationState::mark_closed 在遇到一个还没记录过却要标记关闭的线程时，也会调用它补上一条关闭记录。

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

fn record_sub_agent_activity(&mut self, activity: SubAgentActivityDisplay)

作用：记录某个子 agent 最近的活动信息，尤其是它的路径和是否看起来还在运行。它让选择器能显示那些通过活动消息发现的 agent。

数据流：进去的是一条 SubAgentActivityDisplay（子 agent 活动展示信息，里面有线程编号、路径、运行提示等）和当前缓存 → 如果线程第一次出现，就把它加入顺序；如果没有资料，就先建一条空资料；然后写入路径、运行提示，并把关闭状态改成未关闭 → 出来没有返回值，缓存被补充或刷新。

调用关系：它通常接在“收到子 agent 活动信息”之后。它不调用其他本文件函数，而是直接维护 threads 和 order，让后面的选择器、导航和页脚能看到这条 agent。

fn set_running(&mut self, thread_id: ThreadId, is_running: bool)

作用：单独修改某个线程的“是否正在运行”状态。适合只知道运行状态变化、但不想重写整条资料的时候用。

数据流：进去的是线程编号、运行状态 true/false 和当前缓存 → 它查找对应线程 → 找到就改它的 is_running，找不到就什么也不做；没有返回值。

调用关系：这是一个局部更新口。外层 App 收到运行状态变化时可以调用它；它不影响顺序，也不创建新线程记录。

fn set_agent_path(&mut self, thread_id: ThreadId, agent_path: Option<String>)

作用：给某个线程补上 agent 路径。路径可以理解成这个 agent 对应的来源或名字位置，用来让 UI 更准确地标识它。

数据流：进去的是线程编号、可选路径和当前缓存 → 只有当路径真的存在、并且线程也已在缓存里时，它才写入 agent_path → 出来没有返回值；如果路径为空或线程不存在，状态不变。

调用关系：这是一个保守的补资料函数。它不会凭空创建线程，通常由已经确认某线程存在的上层流程调用。

fn mark_closed(&mut self, thread_id: ThreadId)

作用：把某个线程标记成已关闭，但不把它从列表顺序里删掉。这样用户仍能回看它，切换顺序也不会突然少一格。

数据流：进去的是线程编号和当前缓存 → 如果已有这条线程，就把 is_closed 设为 true，并把 is_running 设为 false；如果还没有记录，就调用 AgentNavigationState::upsert 新建一条“已关闭”的空资料 → 出来没有返回值，缓存记录变成关闭状态。

调用关系：它是关闭事件进入导航缓存的入口。它会在必要时把活儿交给 AgentNavigationState::upsert，保证即使关闭消息先到，线程也能出现在稳定顺序里。

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

fn clear(&mut self)

作用：清空所有 agent 导航缓存。它用于一次会话或线程事件状态被整体拆掉时，把这个小通讯录恢复成空白。

数据流：进去的是当前状态 → 它同时清空线程资料表和顺序表 → 出来没有返回值，之后看起来就像从没见过任何线程。

调用关系：这是收尾或重置时用的函数。App 在 teardown（清理阶段）或重新开始一批线程状态时会调用它；它不调用别的函数。

fn remove(&mut self, thread_id: ThreadId)

作用：彻底移除一个线程，包括资料和顺序里的位置。它只适合那些确认不该再显示的“幽灵记录”。

数据流：进去的是线程编号和当前缓存 → 它从线程资料表删除这条记录，并从顺序表里过滤掉这个编号 → 出来没有返回值，这个线程不再参与选择器和快捷键切换。

调用关系：它比 mark_closed 更激进。关闭线程会保留给用户回看，而这里是外层确认这条记录不应存在时才用。

fn has_non_primary_thread(&self, primary_thread_id: Option<ThreadId>) -> bool

作用：判断除了主线程以外，是否还记着别的线程。主线程可以理解成当前会话的主对话，其他的是子 agent 线程。

数据流：进去的是可选的主线程编号和当前缓存 → 它遍历所有已知线程编号，看看有没有一个不是主线程 → 出来 true 或 false；不改状态。

调用关系：App 可用它决定即使某个协作功能开关关了，是否仍应允许用户查看已经存在的子 agent。它只是回答问题，不参与切换。

fn ordered_threads(&self) -> Vec<(ThreadId, &AgentPickerThreadEntry)>

作用：按稳定顺序拿到所有仍有资料的线程。这个顺序就是选择器显示和快捷键循环使用的顺序。

数据流：进去的是当前的顺序表和线程资料表 → 它按顺序表逐个找资料，找得到才放进结果，找不到就跳过 → 出来一个按首次出现顺序排列的列表；内部状态不变。

调用关系：这是多个读取流程的共同基础。AgentNavigationState::adjacent_thread_id、AgentNavigationState::ordered_path_backed_subagent_threads、AgentNavigationState::tracked_thread_ids 和测试用的 AgentNavigationState::ordered_thread_ids 都靠它拿到可靠顺序。

调用图：被 4 处调用（adjacent_thread_id, ordered_path_backed_subagent_threads, ordered_thread_ids, tracked_thread_ids）。

fn ordered_path_backed_subagent_threads(
        &self,
        primary_thread_id: Option<ThreadId>,
    ) -> Vec<(ThreadId, &AgentPickerThreadEntry)>

作用：拿到有有效路径的子 agent 线程，并且排除主线程。它适合需要列出“真正有来源路径的子 agent”的地方。

数据流：进去的是可选主线程编号和当前缓存 → 它先调用 AgentNavigationState::ordered_threads 得到稳定顺序，再过滤掉主线程，以及路径为空或全是空格的记录 → 出来一个仍保持原顺序的子 agent 列表；不改状态。

调用关系：它是在普通有序列表上再筛一层。上层需要只看带路径的子 agent 时用它，它把基础排序交给 AgentNavigationState::ordered_threads。

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

fn tracked_thread_ids(&self) -> Vec<ThreadId>

作用：只取出当前追踪中的线程编号，并保持选择器使用的顺序。适合上层只关心“有哪些线程”，不需要名字角色等详细资料时使用。

数据流：进去的是当前缓存 → 它调用 AgentNavigationState::ordered_threads 得到有序线程资料，再把每项里的线程编号抽出来 → 出来一个线程编号列表；不改状态。

调用关系：它复用统一的排序规则，避免其他地方自己拼顺序。它把具体排序交给 AgentNavigationState::ordered_threads。

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

fn adjacent_thread_id(
        &self,
        current_displayed_thread_id: Option<ThreadId>,
        direction: AgentNavigationDirection,
    ) -> Option<ThreadId>

作用：根据当前正在看的线程，找出上一个或下一个线程。它让键盘快捷键能像循环菜单一样前后切换。

数据流：进去的是当前显示线程编号、方向（Previous 或 Next）和缓存 → 它调用 AgentNavigationState::ordered_threads 得到稳定列表；如果少于两个线程、当前线程为空或找不到，就返回空；否则计算相邻位置，走到头会绕回另一头 → 出来是相邻线程编号，状态不变。

调用关系：这是快捷键导航的核心读函数。外层 App 在用户按“上一个/下一个 agent”时调用它，然后 App 自己负责真正切换显示线程。

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

fn active_agent_label(
        &self,
        current_displayed_thread_id: Option<ThreadId>,
        primary_thread_id: Option<ThreadId>,
    ) -> Option<String>

作用：生成页脚里“当前正在看哪个 agent”的文字。它避免单线程时浪费空间，多线程时又能给用户一个清楚提示。

数据流：进去的是当前显示线程编号、可选主线程编号和缓存 → 如果总共只有一个或更少线程，直接返回空；否则判断当前是不是主线程，再优先用非主线程的有效路径生成反引号包住的标签；没有路径时用昵称、角色和主线程身份生成通用名字；资料缺失时也会退回通用名字 → 出来是可显示的字符串或空；不改状态。

调用关系：它给 UI 页脚提供文字。它使用和选择器一致的命名规则 format_agent_picker_item_name，这样选择器和页脚不会叫法不一致。

fn picker_subtitle() -> String

作用：生成 /agent 选择器底部那句提示文字，告诉用户怎么选 agent、怎么切到上一个或下一个。

数据流：进去不需要外部数据 → 它调用 previous_agent_shortcut 和 next_agent_shortcut 取得当前平台实际使用的快捷键显示文本，再拼成一句说明 → 出来一个字符串，不改任何状态。

调用关系：它被打开 agent 选择器的流程使用，也被测试 tests::picker_subtitle_mentions_shortcuts 检查。它依赖真正的快捷键辅助函数，避免提示文字和实际按键不一致。

调用图：调用 2 个内部函数（next_agent_shortcut, previous_agent_shortcut）；被 2 处调用（picker_subtitle_mentions_shortcuts, open_agent_picker）；外部调用 1 个（format!）。

fn ordered_thread_ids(&self) -> Vec<ThreadId>

作用：这是测试专用的小帮手，只返回有序线程编号。它让测试可以专心检查顺序，不用构造或比较整条线程资料。

数据流：进去的是当前缓存 → 它调用 AgentNavigationState::ordered_threads，再抽出线程编号 → 出来一个线程编号列表；不改状态。

调用关系：它只在测试配置下编译。测试用它验证“第一次出现的顺序不会变”这条核心规则。

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

fn populated_state() -> (AgentNavigationState, ThreadId, ThreadId, ThreadId)

作用：搭一个固定的测试用状态：一个主线程和两个 agent 线程。这样多个测试不用重复写同样的准备代码。

数据流：进去没有参数 → 它创建默认的 AgentNavigationState，用 from_string 把三段固定字符串变成线程编号，再插入三条线程资料 → 出来是填好数据的状态和三个线程编号。

调用关系：这是测试夹具，也就是测试前的准备工具。tests::upsert_preserves_first_seen_order、tests::adjacent_thread_id_wraps_in_spawn_order 和 tests::active_agent_label_tracks_current_thread 都用它拿到同一套基础数据。

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

fn upsert_preserves_first_seen_order()

作用：测试更新已有线程时，不会改变它第一次出现的顺序。这是在保护本文件最重要的用户体验规则。

数据流：进去没有参数 → 它先用 tests::populated_state 建好三条线程，再更新中间那条线程的角色和关闭状态 → 最后用断言确认线程编号顺序仍然是主线程、第一 agent、第二 agent。

调用关系：这是针对 AgentNavigationState::upsert 行为的测试。它证明“更新资料”和“改变导航顺序”是两回事。

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

fn adjacent_thread_id_wraps_in_spawn_order()

作用：测试上一个/下一个导航会按出生顺序走，并且到头后会绕回去。就像旋转菜单，最后一个的下一个是第一个。

数据流：进去没有参数 → 它用 tests::populated_state 准备三条线程 → 分别检查从第二个 agent 往后会到主线程、往前会到第一个 agent，以及从主线程往前会到第二个 agent → 结果通过断言表达。

调用关系：这是针对 AgentNavigationState::adjacent_thread_id 的测试。它确保键盘循环导航符合稳定顺序和首尾相接的规则。

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

fn picker_subtitle_mentions_shortcuts()

作用：测试选择器提示文字里真的包含当前定义的上一个/下一个快捷键。这样以后快捷键改了，提示文字不容易悄悄过期。

数据流：进去没有参数 → 它分别取得实际的 previous 和 next 快捷键文字，再调用 AgentNavigationState::picker_subtitle 生成提示语 → 最后断言提示语包含这两个快捷键。

调用关系：这是 AgentNavigationState::picker_subtitle 的一致性测试。它也直接调用 previous_agent_shortcut 和 next_agent_shortcut，用真实快捷键作为对照。

调用图：调用 3 个内部函数（picker_subtitle, next_agent_shortcut, previous_agent_shortcut）；外部调用 1 个（assert!）。

fn active_agent_label_tracks_current_thread()

作用：测试页脚标签会跟着当前显示线程变化。看子 agent 时显示子 agent 的名字和角色，看主线程时显示主线程标签。

数据流：进去没有参数 → 它用 tests::populated_state 准备主线程和两个 agent → 分别传入当前显示的第一 agent 和主线程 → 用断言确认返回的标签分别是 Robie [explorer] 和 Main [default]。

调用关系：这是针对 AgentNavigationState::active_agent_label 的测试。它确保页脚看的是“当前显示线程”，而不是别的内部活动线程。

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

async fn handle_backtrack_overlay_event(
        &mut self,
        tui: &mut tui::Tui,
        event: TuiEvent,
    ) -> Result<bool>

作用：当聊天记录浮层打开时，这个函数决定键盘事件该怎么处理。它区分普通浏览记录和“回退预览”两种状态。

数据流：输入是一个界面事件，比如 Esc、左右方向键、Enter 或绘制事件。它先看当前是否正在回退预览：如果是，就把按键变成“往旧消息选”“往新消息选”“确认回退”等动作；如果不是，第一次 Esc 会开启回退预览，其他事件继续交给浮层处理。输出是一个布尔值，表示这个事件已经被处理掉了。

调用关系：它是浮层事件的门卫。需要进入预览时交给 App::begin_overlay_backtrack_preview，确认时交给 App::overlay_confirm_backtrack，移动选择时交给 App::overlay_step_backtrack 或 App::overlay_step_backtrack_forward，普通事件则交给 App::overlay_forward_event。

调用图：调用 5 个内部函数（begin_overlay_backtrack_preview, overlay_confirm_backtrack, overlay_forward_event, overlay_step_backtrack, overlay_step_backtrack_forward）。

fn handle_backtrack_esc_key(&mut self, tui: &mut tui::Tui)

作用：当主聊天界面里按 Esc 时，这个函数启动或推进“回到上一条问题”的流程。它只在输入框为空时生效，避免误把正在写的内容覆盖掉。

数据流：输入是当前界面和 TUI 控制对象。它检查输入框是否为空；第一次 Esc 会记录当前线程并显示提示，第二次 Esc 会打开聊天记录浮层并选中可回退的消息；如果浮层已经处于预览状态，就继续往更早的用户消息移动。它主要改变 App 里的回退状态和界面显示。

调用关系：它是主界面 Esc 的入口。第一次调用 App::prime_backtrack，之后调用 App::open_backtrack_preview，预览中继续调用 App::step_backtrack_and_highlight。

调用图：调用 3 个内部函数（open_backtrack_preview, prime_backtrack, step_backtrack_and_highlight）。

fn apply_backtrack_rollback(&mut self, selection: BacktrackSelection)

作用：这个函数真正发起一次“请后台把线程回滚到某条用户消息之前”的请求。它还会把选中的旧问题先填回输入框，方便用户马上修改。

数据流：输入是一份 BacktrackSelection，里面有选中的第几条用户消息、文本、图片等。它先拒绝侧边会话和重复回滚，再根据当前用户消息总数算出要回滚多少轮，向后台提交 thread_rollback 命令，并把这次请求记为 pending_rollback。输出不是直接返回结果，而是改变界面状态：输入框被预填，等待后台确认。

调用关系：它是回退确认后的核心动作。App::overlay_confirm_backtrack、App::apply_backtrack_selection 和 App::apply_cancelled_turn_edit 会调用它；它会用 user_count 计算轮数，必要时用 App::reset_backtrack_state 清理状态，并把 rollback 命令交给聊天组件发送。

调用图：调用 2 个内部函数（reset_backtrack_state, user_count）；被 3 处调用（apply_backtrack_selection, apply_cancelled_turn_edit, overlay_confirm_backtrack）；外部调用 2 个（thread_rollback, try_from）。

fn apply_cancelled_turn_edit(&mut self, prompt: UserMessage)

作用：当用户取消某一轮编辑时，这个函数把那条原本要编辑的消息放回输入框，并尝试让后台回滚相应的一轮。

数据流：输入是一条 UserMessage，包含文本和图片。它先看本地历史里有多少用户消息；如果没有用户历史，也会发起一次回滚请求并恢复输入框；如果有，就构造一个回退选择并走正常回退流程。结果是输入框恢复成那条消息，后台可能收到回滚命令。

调用关系：它复用 App::apply_backtrack_rollback 来做主要回滚工作；在特殊的空历史场景下直接提交 thread_rollback 命令。

调用图：调用 2 个内部函数（apply_backtrack_rollback, user_count）；外部调用 1 个（thread_rollback）。

fn open_transcript_overlay(&mut self, tui: &mut tui::Tui)

作用：打开完整聊天记录浮层，让用户可以在一个单独的全屏视图里看历史。回退预览也依赖这个浮层来高亮旧消息。

数据流：输入是 TUI 控制对象。它让终端进入备用屏幕，创建一个包含当前 transcript_cells 的 Transcript 浮层，并请求重新绘制。结果是主界面被浮层覆盖，用户看到完整记录。

调用关系：它通常由 App::open_backtrack_preview 调用。创建浮层时会调用 new_transcript，并通过 TUI 的 frame_requester 安排下一帧显示。

调用图：调用 1 个内部函数（new_transcript）；被 1 处调用（open_backtrack_preview）；外部调用 2 个（enter_alt_screen, frame_requester）。

fn close_transcript_overlay(&mut self, tui: &mut tui::Tui)

作用：关闭聊天记录浮层，回到正常聊天界面。它还会处理浮层期间暂存的历史行，避免显示状态乱掉。

数据流：输入是 TUI 控制对象。它离开备用屏幕，把浮层打开期间延迟写入的历史行刷回主界面，清掉 overlay 和预览标记，并请求重绘。如果关闭的是回退预览，还会彻底重置回退状态。

调用关系：App::begin_overlay_backtrack_preview 在没有可回退目标时会调用它；App::overlay_confirm_backtrack 确认前会调用它；App::overlay_forward_event 发现浮层结束时也会调用它。

调用图：调用 1 个内部函数（reset_backtrack_state）；被 3 处调用（begin_overlay_backtrack_preview, overlay_confirm_backtrack, overlay_forward_event）；外部调用 4 个（frame_requester, insert_history_hyperlink_lines_with_wrap_policy, leave_alt_screen, take）。

fn prime_backtrack(&mut self)

作用：这是回退流程的“预备动作”。第一次按 Esc 时，它记住当前线程，并在有可回退消息时给用户提示。

数据流：它读取当前线程 id 和聊天记录。然后把 backtrack.primed 设为 true，把选中位置设为“尚未选择”，并保存 base_id。若历史里有用户消息，就让输入区显示 Esc 回退提示。

调用关系：它由 App::handle_backtrack_esc_key 在第一次 Esc 时调用；它通过 has_backtrack_target 判断是否值得提示。

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

fn open_backtrack_preview(&mut self, tui: &mut tui::Tui)

作用：这个函数打开回退预览：显示完整聊天记录，并选中最近的一条用户消息。没有可回退消息时，它会告诉用户“没有上一条可编辑”。

数据流：它读取 transcript_cells。若没有用户消息，就清理回退状态、显示提示并请求重绘；若有，就打开记录浮层，进入 overlay_preview_active 状态，清掉输入框提示，然后高亮一条可回退消息。

调用关系：它由 App::handle_backtrack_esc_key 在回退已经预备好后调用。它内部会调用 App::open_transcript_overlay、App::step_backtrack_and_highlight、App::reset_backtrack_state 和 has_backtrack_target。

调用图：调用 4 个内部函数（open_transcript_overlay, reset_backtrack_state, step_backtrack_and_highlight, has_backtrack_target）；被 1 处调用（handle_backtrack_esc_key）；外部调用 1 个（frame_requester）。

fn begin_overlay_backtrack_preview(&mut self, tui: &mut tui::Tui)

作用：当用户已经在聊天记录浮层里时，按 Esc 会通过这个函数进入回退预览，并默认选中最新的用户消息。

数据流：它检查当前历史中是否有用户消息。没有的话关闭浮层并显示“没有上一条可编辑”；有的话记录当前线程，打开预览状态，计算用户消息数量，选中最后一条，并请求重绘。

调用关系：它由 App::handle_backtrack_overlay_event 在浮层里第一次按 Esc 时调用；它会用 user_count 找最后一条用户消息，并用 App::apply_backtrack_selection_internal 更新高亮。

调用图：调用 4 个内部函数（apply_backtrack_selection_internal, close_transcript_overlay, has_backtrack_target, user_count）；被 1 处调用（handle_backtrack_overlay_event）；外部调用 1 个（frame_requester）。

fn step_backtrack_and_highlight(&mut self, tui: &mut tui::Tui)

作用：把回退选择往更早的一条用户消息移动，并在浮层里高亮出来。就像在历史记录里往上翻一个可编辑节点。

数据流：它读取当前用户消息数量和当前选中的第几条。若还没选过，就选最新一条；若已经在最早一条，就停住；否则往前移一条。然后更新内部选择和浮层高亮，并请求重绘。

调用关系：主界面继续按 Esc、刚打开预览、或浮层里按 Esc/左键时都会用它。它把最终选择交给 App::apply_backtrack_selection_internal。

调用图：调用 2 个内部函数（apply_backtrack_selection_internal, user_count）；被 3 处调用（handle_backtrack_esc_key, open_backtrack_preview, overlay_step_backtrack）；外部调用 1 个（frame_requester）。

fn step_forward_backtrack_and_highlight(&mut self, tui: &mut tui::Tui)

作用：把回退选择往更新的一条用户消息移动。它用于用户在预览里按右键，想从太旧的位置退回来一点。

数据流：它读取用户消息数量和当前选中位置。没有用户消息就不做事；否则从当前位置往后加一，但不会超过最新一条。然后更新高亮并请求重绘。

调用关系：它由 App::overlay_step_backtrack_forward 调用，实际更新动作交给 App::apply_backtrack_selection_internal。

调用图：调用 2 个内部函数（apply_backtrack_selection_internal, user_count）；被 1 处调用（overlay_step_backtrack_forward）；外部调用 1 个（frame_requester）。

fn apply_backtrack_selection_internal(&mut self, nth_user_message: usize)

作用：把“第几条用户消息”转换成聊天记录里的具体格子位置，并让浮层高亮它。它是选择状态和画面高亮之间的桥。

数据流：输入是 nth_user_message，也就是从当前会话开始算的第几条用户消息。它通过 nth_user_position 找到 transcript_cells 里的实际下标；找到就保存这个选择并设置高亮，找不到就清空选择和高亮。

调用关系：它被 App::begin_overlay_backtrack_preview、App::step_backtrack_and_highlight、App::step_forward_backtrack_and_highlight 和 App::sync_overlay_after_transcript_trim 调用，用来保持选择与浮层画面一致。

调用图：调用 1 个内部函数（nth_user_position）；被 4 处调用（begin_overlay_backtrack_preview, step_backtrack_and_highlight, step_forward_backtrack_and_highlight, sync_overlay_after_transcript_trim）。

fn overlay_forward_event(&mut self, tui: &mut tui::Tui, event: TuiEvent) -> Result<()>

作用：把不属于回退快捷键的事件交给浮层自己处理。遇到绘制事件时，它还会把当前正在生成的聊天内容临时显示在记录浮层尾部。

数据流：输入是一个 TUI 事件。若是绘制或窗口大小变化，并且当前是聊天记录浮层，它会从 ChatWidget 取正在活动的消息缓存键和显示行，交给浮层同步 live tail，然后绘制；如果有动画且滚动到底部，会安排下一帧。其他事件则直接交给 overlay.handle_event。若浮层表示自己结束了，就关闭浮层。

调用关系：它被 App::handle_backtrack_overlay_event、App::overlay_step_backtrack 和 App::overlay_step_backtrack_forward 当作默认转发通道使用；必要时调用 App::close_transcript_overlay 收尾。

调用图：调用 1 个内部函数（close_transcript_overlay）；被 3 处调用（handle_backtrack_overlay_event, overlay_step_backtrack, overlay_step_backtrack_forward）；外部调用 4 个（draw, frame_requester, matches!, from_millis）。

fn overlay_confirm_backtrack(&mut self, tui: &mut tui::Tui)

作用：在回退预览浮层里按 Enter 时，这个函数确认当前选择。它关闭浮层，然后发起真正的回滚请求。

数据流：它读取当前选中的 nth_user_message，尝试生成 BacktrackSelection，然后关闭聊天记录浮层。如果选择有效，就调用回滚逻辑，并请求界面重绘。

调用关系：它由 App::handle_backtrack_overlay_event 在 Enter 键时调用；它依赖 App::backtrack_selection 取出旧消息内容，再交给 App::apply_backtrack_rollback。

调用图：调用 3 个内部函数（apply_backtrack_rollback, backtrack_selection, close_transcript_overlay）；被 1 处调用（handle_backtrack_overlay_event）；外部调用 1 个（frame_requester）。

fn overlay_step_backtrack(&mut self, tui: &mut tui::Tui, event: TuiEvent) -> Result<()>

作用：处理回退预览浮层里的 Esc 或左方向键：如果回退流程还有效，就往更早的消息移动；否则当普通浮层事件处理。

数据流：输入是 TUI 控制对象和原始事件。它检查 base_id 是否存在；存在说明回退已准备好，于是移动选择并高亮；不存在就把事件原样转发给浮层。结果是选择变化，或者浮层自己处理该事件。

调用关系：它由 App::handle_backtrack_overlay_event 调用。正常走 App::step_backtrack_and_highlight，异常或未准备时走 App::overlay_forward_event。

调用图：调用 2 个内部函数（overlay_forward_event, step_backtrack_and_highlight）；被 1 处调用（handle_backtrack_overlay_event）。

fn overlay_step_backtrack_forward(
        &mut self,
        tui: &mut tui::Tui,
        event: TuiEvent,
    ) -> Result<()>

作用：处理回退预览浮层里的右方向键：如果流程有效，就往更新的消息移动；否则交给浮层普通处理。

数据流：输入是 TUI 控制对象和事件。它根据 base_id 判断是否处在有效回退流程中；有效就调用向前移动逻辑，无效就转发事件。结果是高亮位置向更新的用户消息移动，或浮层自行响应。

调用关系：它由 App::handle_backtrack_overlay_event 调用；主要把工作交给 App::step_forward_backtrack_and_highlight，兜底交给 App::overlay_forward_event。

调用图：调用 2 个内部函数（overlay_forward_event, step_forward_backtrack_and_highlight）；被 1 处调用（handle_backtrack_overlay_event）。

fn confirm_backtrack_from_main(&mut self) -> Option<BacktrackSelection>

作用：在没有浮层的主界面里确认一个已经准备好的回退选择。它返回要回退的旧消息内容，供外层继续处理。

数据流：它读取当前 backtrack.nth_user_message，尝试生成 BacktrackSelection，然后重置回退状态。输出是一个可选的选择结果：线程不匹配或找不到内容时为 None。

调用关系：它调用 App::backtrack_selection 组装选择，再调用 App::reset_backtrack_state 收尾。

调用图：调用 2 个内部函数（backtrack_selection, reset_backtrack_state）。

fn reset_backtrack_state(&mut self)

作用：清空所有回退相关的临时状态。它相当于把“正在准备回退”的开关全部关掉。

数据流：它不需要额外输入，只修改 App 内部状态：primed 变 false，base_id 清空，nth_user_message 设为无选择，并清掉输入框里的 Esc 回退提示。

调用关系：很多流程结束或失败时都会调用它，比如 App::apply_backtrack_rollback、App::close_transcript_overlay、App::confirm_backtrack_from_main 和 App::open_backtrack_preview。

调用图：被 4 处调用（apply_backtrack_rollback, close_transcript_overlay, confirm_backtrack_from_main, open_backtrack_preview）。

fn apply_backtrack_selection(
        &mut self,
        tui: &mut tui::Tui,
        selection: BacktrackSelection,
    )

作用：这是一个小包装函数：拿到用户确认的回退选择后，发起回滚并安排界面刷新。

数据流：输入是 TUI 控制对象和 BacktrackSelection。它把选择交给 App::apply_backtrack_rollback，然后请求下一帧绘制。结果是后台收到回滚请求，界面准备更新。

调用关系：它本身不做复杂判断，主要把外部确认的选择接到 App::apply_backtrack_rollback 这条主流程上。

调用图：调用 1 个内部函数（apply_backtrack_rollback）；外部调用 1 个（frame_requester）。

fn handle_backtrack_rollback_succeeded(&mut self, num_turns: u32)

作用：后台确认回滚成功时，这个函数决定本地该怎么跟上。它区分“这是我刚刚发起的回退”还是“别处传来的线程回滚”。

数据流：输入是后台说回滚了多少轮。若 App 里有 pending_rollback，说明这是本界面发起的回退，就完成本地裁剪；否则发送一个 AppEvent，让事件队列按顺序处理非本地待确认的回滚。结果是本地历史稍后被正确裁剪。

调用关系：它在收到 rollback succeeded 事件时被调用。有待处理请求时交给 App::finish_pending_backtrack；没有时把 ApplyThreadRollback 事件发回应用事件流。

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

fn handle_backtrack_rollback_failed(&mut self)

作用：后台说回滚失败时，这个函数取消“等待回滚确认”的状态，避免界面一直卡着不让用户再次尝试。

数据流：它不需要输入，只把 backtrack.pending_rollback 清空。它不会撤掉已经填进输入框的旧消息，因为那仍然可能方便用户修改后重试。

调用关系：它是失败事件的收尾点，和 App::handle_backtrack_rollback_succeeded 形成一成功一失败的配对。

fn apply_non_pending_thread_rollback(&mut self, num_turns: u32) -> bool

作用：处理那些不是当前界面主动发起、但后台通知需要回滚的情况。它按“删掉最后 N 个用户回合”的规则裁剪本地聊天记录。

数据流：输入是要回滚的用户轮数 num_turns。它尝试从 transcript_cells 末尾按用户消息边界裁剪；如果没有变化就返回 false。裁剪成功后，它清掉一些待刷新的提示，缩短复制用的助手历史，同步浮层，并标记需要重新渲染。输出是是否真的改动了本地记录。

调用关系：它会调用 trim_transcript_cells_drop_last_n_user_turns 做实际裁剪，调用 user_count 更新助手历史长度，再用 App::sync_overlay_after_transcript_trim 保持浮层一致。

调用图：调用 3 个内部函数（sync_overlay_after_transcript_trim, trim_transcript_cells_drop_last_n_user_turns, user_count）。

fn finish_pending_backtrack(&mut self)

作用：完成一次本界面发起且后台已经确认的回退。它只在确认事件属于当前线程时才裁剪本地记录。

数据流：它取出 pending_rollback。若这次请求的 thread_id 和当前聊天线程不一样，就什么也不删，防止切换会话后误删。若匹配，就把 transcript_cells 截到选中用户消息之前，清理刷新提示，调整助手历史，同步浮层，并标记需要重绘。

调用关系：它由 App::handle_backtrack_rollback_succeeded 调用。实际裁剪交给 trim_transcript_cells_to_nth_user，裁剪后的界面对齐交给 App::sync_overlay_after_transcript_trim。

调用图：调用 3 个内部函数（sync_overlay_after_transcript_trim, trim_transcript_cells_to_nth_user, user_count）；被 1 处调用（handle_backtrack_rollback_succeeded）。

fn backtrack_selection(&self, nth_user_message: usize) -> Option<BacktrackSelection>

作用：根据当前选中的“第几条用户消息”，取出那条旧消息的文本和图片，打包成可执行回退的选择。

数据流：输入是 nth_user_message。它先确认当初准备回退时的线程 id 仍然等于当前线程；不一致就返回 None。然后找到对应 UserHistoryCell，复制其中的文本、文本元素、本地图片路径和远程图片地址。输出是 BacktrackSelection。

调用关系：App::overlay_confirm_backtrack 和 App::confirm_backtrack_from_main 会调用它。它通过 nth_user_position 从抽象的用户消息编号找到真实历史格子。

调用图：调用 1 个内部函数（nth_user_position）；被 2 处调用（confirm_backtrack_from_main, overlay_confirm_backtrack）。

fn sync_overlay_after_transcript_trim(&mut self)

作用：当聊天记录被裁剪后，这个函数把所有相关界面状态同步一下，避免浮层还显示已经删掉的内容。

数据流：它读取新的 transcript_cells。若聊天记录浮层还开着，就替换浮层里的记录；若回退预览还在，就把高亮选择限制在仍然存在的用户消息范围内；最后清空浮层期间暂存的历史行，防止之后把已删除内容刷回主界面。

调用关系：它由 App::apply_non_pending_thread_rollback 和 App::finish_pending_backtrack 在裁剪成功后调用；需要重算高亮时会调用 App::apply_backtrack_selection_internal。

调用图：调用 2 个内部函数（apply_backtrack_selection_internal, user_count）；被 2 处调用（apply_non_pending_thread_rollback, finish_pending_backtrack）。

fn trim_transcript_cells_to_nth_user(
    transcript_cells: &mut Vec<Arc<dyn crate::history_cell::HistoryCell>>,
    nth_user_message: usize,
) -> bool

作用：把聊天记录裁剪到某条用户消息之前。也就是说，选中的那条用户消息和它之后的内容都会被删掉。

数据流：输入是一组可修改的历史格子和 nth_user_message。它先拒绝“无选择”的特殊值，再找到第 nth 条用户消息在数组里的位置，把数组截断到那个位置。输出是布尔值，表示数组长度是否真的变了。

调用关系：App::finish_pending_backtrack 用它在后台确认后裁剪本地记录；多个测试函数也用它验证不同位置裁剪是否正确。它依赖 nth_user_position 找切割点。

调用图：调用 1 个内部函数（nth_user_position）；被 4 处调用（finish_pending_backtrack, trim_transcript_for_first_user_drops_user_and_newer_cells, trim_transcript_for_later_user_keeps_prior_history, trim_transcript_preserves_cells_before_selected_user）。

fn trim_transcript_cells_drop_last_n_user_turns(
    transcript_cells: &mut Vec<Arc<dyn crate::history_cell::HistoryCell>>,
    num_turns: u32,
) -> bool

作用：按“从末尾删掉 N 个用户回合”的规则裁剪聊天记录。它适合处理后台只告诉你回滚了几轮，而不是告诉你选中了哪条消息的情况。

数据流：输入是历史格子和要删的用户轮数。它找出当前会话里所有用户消息的位置；如果要删的轮数大于已有用户消息数，就从第一条用户消息前截断；否则从倒数第 N 条用户消息前截断。输出是是否真的删掉了内容。

调用关系：App::apply_non_pending_thread_rollback 调用它处理非 pending 的线程回滚；相关测试验证了普通回滚和超大回滚数的情况。它使用 user_positions_iter 找所有用户消息位置。

调用图：调用 1 个内部函数（user_positions_iter）；被 3 处调用（apply_non_pending_thread_rollback, trim_drop_last_n_user_turns_allows_overflow, trim_drop_last_n_user_turns_applies_rollback_semantics）；外部调用 1 个（try_from）。

fn user_count(cells: &[Arc<dyn crate::history_cell::HistoryCell>]) -> usize

作用：数一数当前会话里有多少条用户消息。这里的“当前会话”指最后一个会话开始标记之后的内容。

数据流：输入是一组历史格子。它通过 user_positions_iter 找出所有用户消息位置，然后返回数量。它不修改任何数据。

调用关系：很多回退流程都用它判断有没有可回退目标、计算回滚轮数、或在裁剪后更新状态，比如 App::apply_backtrack_rollback、App::step_backtrack_and_highlight 和 App::finish_pending_backtrack。

调用图：调用 1 个内部函数（user_positions_iter）；被 10 处调用（backtrack_selection_with_duplicate_history_targets_unique_turn, apply_backtrack_rollback, apply_cancelled_turn_edit, apply_non_pending_thread_rollback, begin_overlay_backtrack_preview, finish_pending_backtrack, step_backtrack_and_highlight, step_forward_backtrack_and_highlight, sync_overlay_after_transcript_trim, has_backtrack_target）。

fn has_backtrack_target(cells: &[Arc<dyn crate::history_cell::HistoryCell>]) -> bool

作用：判断当前聊天记录里是否有可以回退编辑的用户消息。没有用户消息就没法“编辑上一条”。

数据流：输入是历史格子列表。它调用 user_count，如果数量大于 0 就返回 true，否则返回 false。它不改动数据。

调用关系：App::prime_backtrack、App::open_backtrack_preview 和 App::begin_overlay_backtrack_preview 都用它决定是否显示提示、打开预览或提示用户没有可编辑消息。

调用图：调用 1 个内部函数（user_count）；被 3 处调用（begin_overlay_backtrack_preview, open_backtrack_preview, prime_backtrack）。

fn nth_user_position(
    cells: &[Arc<dyn crate::history_cell::HistoryCell>],
    nth: usize,
) -> Option<usize>

作用：把“第几条用户消息”转换成历史数组里的真实下标。因为历史里还混着助手消息、系统信息等，所以不能直接用同一个数字当数组下标。

数据流：输入是历史格子和 nth。它遍历当前会话中的用户消息位置，找到序号等于 nth 的那个位置并返回；找不到就返回 None。

调用关系：App::apply_backtrack_selection_internal、App::backtrack_selection 和 trim_transcript_cells_to_nth_user 都靠它把用户选择定位到具体历史格子。

调用图：调用 1 个内部函数（user_positions_iter）；被 3 处调用（apply_backtrack_selection_internal, backtrack_selection, trim_transcript_cells_to_nth_user）。

fn user_positions_iter(
    cells: &[Arc<dyn crate::history_cell::HistoryCell>],
) -> impl Iterator<Item = usize> + '_

作用：生成当前会话里所有用户消息在历史数组中的位置。它是许多计数和裁剪函数的底层工具。

数据流：输入是历史格子列表。它先找到最后一个 SessionInfoCell，也就是最近一次会话开始标记；然后只看它之后的格子，筛出 UserHistoryCell 的下标。输出是一个迭代器，可以逐个拿到这些位置。

调用关系：user_count、nth_user_position 和 trim_transcript_cells_drop_last_n_user_turns 都使用它。它保证回退只针对最近会话之后的用户消息，不误碰更早会话。

调用图：被 3 处调用（nth_user_position, trim_transcript_cells_drop_last_n_user_turns, user_count）。

fn agent_group_count(cells: &[Arc<dyn crate::history_cell::HistoryCell>]) -> usize

作用：这是测试用的小工具，用来数当前会话里有多少个助手消息组。它只在测试编译时存在。

数据流：输入是历史格子。它调用 agent_group_positions_iter 找出助手消息组的位置，然后返回数量。它不修改数据。

调用关系：它主要服务测试，特别是验证某些信息提示不会被误算成助手消息组。

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

fn agent_group_positions_iter(
    cells: &[Arc<dyn crate::history_cell::HistoryCell>],
) -> impl Iterator<Item = usize> + '_

作用：这是测试用的底层工具，用来找当前会话里每个助手消息组的起始位置。它会忽略流式续写的片段。

数据流：输入是历史格子。它从最后一个会话开始标记之后遍历，只挑出 AgentMessageCell，并且要求它不是流式消息的延续部分。输出是这些助手消息组起点的下标迭代器。

调用关系：它只被测试辅助函数 agent_group_count 调用，用来让测试更精确地检查助手消息分组。

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

fn render_lines(lines: &[Line<'static>]) -> Vec<String>

作用：测试辅助函数，把界面行对象转成普通字符串，方便做快照或断言比较。

数据流：输入是一组 ratatui 的 Line。它把每行里的多个 span 文字拼起来，输出 Vec<String>。它不改变原始行。

调用关系：tests::backtrack_unavailable_info_message_snapshot 用它把提示消息渲染结果转成可比较文本。

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

fn trim_transcript_for_first_user_drops_user_and_newer_cells()

作用：这个测试确认：如果回退到第一条用户消息，那么这条用户消息和之后的助手回复都会被删掉。

数据流：它构造一段包含用户消息和助手消息的历史，然后调用 trim_transcript_cells_to_nth_user 选择第 0 条用户消息。之后断言历史变为空。

调用关系：它直接验证 trim_transcript_cells_to_nth_user 的最早边界行为，防止回退第一条时留下不该留的内容。

调用图：调用 1 个内部函数（trim_transcript_cells_to_nth_user）；外部调用 2 个（assert!, vec!）。

fn trim_transcript_preserves_cells_before_selected_user()

作用：这个测试确认：裁剪到某条用户消息前时，更早的非用户内容会保留下来。

数据流：它构造“助手开场、用户消息、助手后续”的历史，裁剪到第 0 条用户消息前。然后检查只剩下开场助手消息，并确认文字内容正确。

调用关系：它测试 trim_transcript_cells_to_nth_user 不会粗暴清空全部历史，而是按选中用户消息的位置精确截断。

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

fn trim_transcript_for_later_user_keeps_prior_history()

作用：这个测试确认：回退到较晚的一条用户消息时，之前完整的对话历史会保留。

数据流：它构造包含两条用户消息和多条助手消息的历史，裁剪到第二条用户消息前。然后断言第一条用户消息以及它之前、之间的助手消息都还在。

调用关系：它验证 trim_transcript_cells_to_nth_user 对中间位置的裁剪规则，保证只删除选中用户消息及其后面内容。

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

fn trim_drop_last_n_user_turns_applies_rollback_semantics()

作用：这个测试确认：按“删掉最后 N 个用户回合”的规则回滚时，会从最后一条用户消息前切掉后续内容。

数据流：它构造两轮用户和助手历史，调用 trim_transcript_cells_drop_last_n_user_turns 删除 1 轮。然后检查只剩第一轮相关内容。

调用关系：它验证 App::apply_non_pending_thread_rollback 依赖的底层裁剪函数是否符合后台 rollback 的语义。

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

fn trim_drop_last_n_user_turns_allows_overflow()

作用：这个测试确认：如果要求删除的用户轮数远大于现有数量，函数也不会崩，而是尽可能安全地裁剪。

数据流：它构造一段含助手开场和一条用户消息的历史，传入 u32::MAX 作为删除轮数。函数应该从第一条用户消息前截断，保留更早的助手开场。测试再检查结果。

调用关系：它保护 trim_transcript_cells_drop_last_n_user_turns 的极端输入行为，防止大数字造成越界或错误裁剪。

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

fn agent_group_count_ignores_context_compacted_marker()

作用：这个测试确认：类似“Context compacted”的信息提示不会被当成助手消息组来计数。

数据流：它构造两个助手消息，中间夹一个信息事件，然后调用 agent_group_count。期望结果是 2，而不是把信息事件也算进去。

调用关系：它验证测试辅助计数逻辑 agent_group_count 和 agent_group_positions_iter 对消息类型的识别是准确的。

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

fn backtrack_target_requires_user_message()

作用：这个测试确认：只有历史里真的有用户消息时，才算有可回退目标。

数据流：它先构造只有助手消息和信息事件的历史，断言 has_backtrack_target 为 false；再加入一条用户消息，断言变为 true。

调用关系：它验证 has_backtrack_target 的基础判断，避免界面在没有用户消息时错误地开启回退。

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

fn backtrack_unavailable_info_message_snapshot()

作用：这个测试用快照确认“没有上一条可编辑”这条提示的显示样子没有意外变化。

数据流：它创建一个信息提示 cell，把它渲染成文本行，再交给快照断言。输出不是运行时数据，而是测试通过或失败。

调用关系：它使用 tests::render_lines 转换渲染结果，并通过快照测试保护 NO_PREVIOUS_MESSAGE_TO_EDIT 的用户可见表现。

调用图：外部调用 3 个（new_info_event, assert_snapshot!, render_lines）。

fn agent_picker_status_dot_spans(is_closed: bool) -> Vec<Span<'static>>

作用：给智能体选择列表里的状态小圆点准备显示内容。运行中的智能体显示绿色点，已关闭的只显示普通点，让用户一眼看出活跃程度。

数据流：输入是一个“是否已关闭”的布尔值 → 函数决定圆点要不要变绿，并在后面加一个空格 → 输出一组可被终端界面渲染的文字片段。

调用关系：它属于智能体选择器的显示小零件，通常会被列表行渲染代码拿来拼在名字前面；它不再把工作交给本文件里的其他函数。

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

fn format_agent_picker_item_name(
    agent_nickname: Option<&str>,
    agent_role: Option<&str>,
    is_primary: bool,
) -> String

作用：把智能体的昵称、角色和“是否主线程”整理成选择器里好懂的名字。这样用户不会只看到一串内部 ID。

数据流：输入昵称、角色、是否主线程 → 先清理空白和空字符串 → 主线程固定显示为“Main [default]”，其他情况按“昵称 [角色]”“昵称”“[角色]”或“Agent”输出。

调用关系：它是 /agent 选择列表的命名规则中心；上层界面在生成每一行候选项时会用它，但它自己只做字符串整理。

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

fn previous_agent_shortcut() -> crate::key_hint::KeyBinding

作用：定义“切到上一个智能体”的标准快捷键。这里用的是 Alt+左箭头。

数据流：没有业务输入 → 调用通用按键提示工具生成 Alt+Left 的按键绑定 → 输出一个可用于显示和匹配的快捷键对象。

调用关系：它会被选择器底部提示、快捷键提示测试，以及 previous_agent_shortcut_matches 使用；后者拿它来判断用户刚按的键是不是“上一个”。

调用图：调用 1 个内部函数（alt）；被 3 处调用（picker_subtitle, picker_subtitle_mentions_shortcuts, previous_agent_shortcut_matches）。

fn next_agent_shortcut() -> crate::key_hint::KeyBinding

作用：定义“切到下一个智能体”的标准快捷键。这里用的是 Alt+右箭头。

数据流：没有业务输入 → 调用通用按键提示工具生成 Alt+Right 的按键绑定 → 输出一个可用于显示和匹配的快捷键对象。

调用关系：它会被选择器底部提示、快捷键提示测试，以及 next_agent_shortcut_matches 使用；后者拿它来判断用户刚按的键是不是“下一个”。

调用图：调用 1 个内部函数（alt）；被 3 处调用（picker_subtitle, picker_subtitle_mentions_shortcuts, next_agent_shortcut_matches）。

fn previous_agent_shortcut_matches(
    key_event: KeyEvent,
    allow_word_motion_fallback: bool,
) -> bool

作用：判断一次按键是不是“切到上一个智能体”。它不仅认标准的 Alt+左箭头，也可按条件接受 macOS 终端的替代按法。

数据流：输入一次键盘事件和是否允许替代按法 → 先用 previous_agent_shortcut 检查标准快捷键 → 再用 previous_agent_word_motion_fallback 检查平台兼容按法 → 输出 true 或 false。

调用关系：按键处理流程会用它决定是否触发向前切换；它把标准键定义交给 previous_agent_shortcut，把特殊终端兼容判断交给 previous_agent_word_motion_fallback。

调用图：调用 2 个内部函数（previous_agent_shortcut, previous_agent_word_motion_fallback）。

fn next_agent_shortcut_matches(
    key_event: KeyEvent,
    allow_word_motion_fallback: bool,
) -> bool

作用：判断一次按键是不是“切到下一个智能体”。它处理标准快捷键，也处理 macOS 某些终端发出的替代键。

数据流：输入一次键盘事件和是否允许替代按法 → 先检查 Alt+右箭头 → 再检查平台兼容按法 → 输出这次按键是否应该切到下一个智能体。

调用关系：按键处理流程会用它决定是否触发向后切换；它依赖 next_agent_shortcut 和 next_agent_word_motion_fallback 分别处理标准和兼容情况。

调用图：调用 2 个内部函数（next_agent_shortcut, next_agent_word_motion_fallback）。

fn previous_agent_word_motion_fallback(
    _key_event: KeyEvent,
    _allow_word_motion_fallback: bool,
) -> bool

作用：处理“切到上一个智能体”的平台兼容键。特别是在 macOS 上，有些终端会把 Option+左箭头发成 Option+b。

数据流：输入一次键盘事件和是否允许 fallback（备用规则） → 在允许时检查它是否像 Option+b 这样的“向前移动一个词”按键 → 输出是否匹配；非 macOS 版本总是返回 false。

调用关系：它只被 previous_agent_shortcut_matches 调用，用来补上标准 Alt+左箭头收不到时的空缺；调用方会在输入框为空等安全场景才允许它，避免影响正常编辑文字。

调用图：被 1 处调用（previous_agent_shortcut_matches）；外部调用 1 个（matches!）。

fn next_agent_word_motion_fallback(
    _key_event: KeyEvent,
    _allow_word_motion_fallback: bool,
) -> bool

作用：处理“切到下一个智能体”的平台兼容键。macOS 某些终端可能把 Option+右箭头发成 Option+f。

数据流：输入一次键盘事件和是否允许备用规则 → 在允许时检查它是否是 Option+f 这样的按键 → 输出是否匹配；非 macOS 版本总是返回 false。

调用关系：它只被 next_agent_shortcut_matches 调用，目的是让不同终端里的智能体切换都尽量可用，同时不打扰用户在输入框里按词移动光标。

调用图：被 1 处调用（next_agent_shortcut_matches）；外部调用 1 个（matches!）。

fn spawn_request_summary(item: &ThreadItem) -> Option<SpawnRequestSummary>

作用：从“启动智能体”的事件里提取模型名和推理强度。这样历史记录里可以显示这个智能体是用什么配置启动的。

数据流：输入一条线程事件 → 如果它确实是 SpawnAgent，并且带有 model 和 reasoning_effort → 输出一个 SpawnRequestSummary；否则输出 None。

调用关系：它会被 on_collab_agent_tool_call 和 tool_call_history_cell 使用；前者可缓存启动信息，后者在渲染启动结束行时拿来补充显示。

调用图：被 2 处调用（on_collab_agent_tool_call, tool_call_history_cell）。

fn tool_call_history_cell(
    item: &ThreadItem,
    cached_spawn_request: Option<&SpawnRequestSummary>,
    mut agent_metadata: impl FnMut(ThreadId) -> AgentMetadata,
) -> Option<PlainHistoryCell>

作用：把一条多智能体工具调用事件变成终端历史记录里的一个可显示块。它是“机器事件”到“用户可读文字”的主要入口。

数据流：输入一条 ThreadItem、可选的启动配置缓存、以及按线程 ID 查询昵称和角色的函数 → 先确认这是不是协作智能体工具调用 → 再按工具类型和状态选择不同展示方式，例如启动完成、发送输入完成、等待开始、等待结束、关闭完成 → 输出 PlainHistoryCell；如果这条事件暂时不该显示，就输出 None。

调用关系：on_collab_agent_tool_call 会在收到协作工具调用时使用它；测试也大量调用它验证显示效果。它会把具体排版交给 spawn_end、waiting_begin、waiting_end 等小函数，也会在需要时调用 spawn_request_summary。

调用图：调用 4 个内部函数（spawn_end, spawn_request_summary, waiting_begin, waiting_end）；被 4 处调用（on_collab_agent_tool_call, collab_events_snapshot, collab_resume_interrupted_snapshot, title_styles_nickname_and_role）；外部调用 1 个（matches!）。

fn sub_agent_activity_display(item: &ThreadItem) -> Option<SubAgentActivityDisplay>

作用：从子智能体活动事件里提取界面需要记住的关键信息，比如线程 ID、路径、是否看起来还在运行。

数据流：输入一条 ThreadItem → 如果它是 SubAgentActivity，就解析 agent_thread_id，复制 agent_path，并根据事件种类判断运行提示 → 输出 SubAgentActivityDisplay；不是这类事件或 ID 无法解析时输出 None。

调用关系：它服务于上层界面对子智能体状态的刷新；它依赖 parse_thread_id 把字符串 ID 变成更可靠的 ThreadId。

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

fn sub_agent_activity_history_cell(item: &ThreadItem) -> Option<PlainHistoryCell>

作用：把子智能体的开始、交互、打断事件变成一条历史记录。用户因此能看到子智能体什么时候被启动或中断。

数据流：输入一条 ThreadItem → 如果它是 SubAgentActivity，就用 sub_agent_activity_title 做标题，再用 collab_event 包成历史记录单元 → 输出 PlainHistoryCell；否则输出 None。

调用关系：on_sub_agent_activity 会在收到子智能体活动时调用它；它把标题生成交给 sub_agent_activity_title，把统一外观包装交给 collab_event。

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

fn sub_agent_activity_summary(kind: SubAgentActivityKind, agent_path: &str) -> String

作用：生成一行简短的子智能体活动摘要。它适合放在不需要复杂样式的地方。

数据流：输入活动类型和智能体路径 → 按 Started、Interacted、Interrupted 三种情况拼出英文短句 → 输出普通字符串。

调用关系：它是一个轻量文字转换工具，不依赖本文件其他函数；上层可在状态栏、日志或摘要位置使用。

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

fn sub_agent_activity_title(kind: SubAgentActivityKind, agent_path: &str) -> Line<'static>

作用：生成带样式的子智能体活动标题。它会把动作词加粗，把路径用醒目的颜色标出来。

数据流：输入活动类型和路径 → 选择“Started”“Interacted with”或“Interrupted”这样的前缀 → 拼成带颜色的文字片段 → 交给 title_spans_line 加上统一的圆点开头 → 输出一行标题。

调用关系：它被 sub_agent_activity_history_cell 调用，是子智能体历史记录标题的专用工厂；最后的统一标题格式由 title_spans_line 完成。

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

fn spawn_end(
    new_thread_id: Option<ThreadId>,
    prompt: &str,
    spawn_request: Option<&SpawnRequestSummary>,
    agent_metadata: &mut impl FnMut(ThreadId) -> AgentMetadata,
) -> PlainHistoryC

作用：生成“智能体启动结束”的历史记录。成功时显示启动了谁，失败时显示启动失败。

数据流：输入新线程 ID、启动提示词、可选启动配置、以及查询智能体昵称角色的函数 → 如果有线程 ID，就取出元数据并生成“Spawned 某某”的标题；否则生成失败标题 → 如果提示词非空，就加一行截短后的提示词 → 输出 PlainHistoryCell。

调用关系：tool_call_history_cell 在 SpawnAgent 完成后调用它；它内部借助 agent_label、title_with_agent、title_text、prompt_line 和 collab_event 拼出最终显示。

调用图：调用 5 个内部函数（agent_label, collab_event, prompt_line, title_text, title_with_agent）；被 1 处调用（tool_call_history_cell）；外部调用 1 个（new）。

fn interaction_end(
    receiver_thread_id: ThreadId,
    prompt: &str,
    agent_metadata: &mut impl FnMut(ThreadId) -> AgentMetadata,
) -> PlainHistoryCell

作用：生成“已经给某个智能体发送输入”的历史记录。用户可以回看自己给哪个智能体补充了什么要求。

数据流：输入接收方线程 ID、提示词、元数据查询函数 → 生成“Sent input to 某某”的标题 → 提示词非空时加一行预览 → 输出 PlainHistoryCell。

调用关系：它用于 SendInput 完成后的展示；它把名字格式交给 agent_label 和 title_with_agent，把提示词整理交给 prompt_line，最后由 collab_event 包装成历史记录。

调用图：调用 4 个内部函数（agent_label, collab_event, prompt_line, title_with_agent）；外部调用 1 个（new）。

fn waiting_begin(
    receiver_thread_ids: &[String],
    agent_metadata: &mut impl FnMut(ThreadId) -> AgentMetadata,
) -> PlainHistoryCell

作用：生成“正在等待智能体”的历史记录。等待一个智能体和等待多个智能体时，它会给出不同的标题和明细。

数据流：输入一组接收方线程 ID 字符串和元数据查询函数 → 解析能识别的线程 ID，取出昵称角色 → 如果只有一个就显示等待谁，多个就显示等待几个并列出名单，解析不到就显示笼统的“Waiting for agents” → 输出 PlainHistoryCell。

调用关系：tool_call_history_cell 在 Wait 仍在进行时调用它；它会用 agent_label、title_with_agent、title_text 和 collab_event 组合出最终界面内容。

调用图：调用 4 个内部函数（agent_label, collab_event, title_text, title_with_agent）；被 1 处调用（tool_call_history_cell）；外部调用 2 个（new, format!）。

fn waiting_end(
    receiver_thread_ids: &[String],
    agents_states: &std::collections::HashMap<String, CollabAgentState>,
    agent_metadata: &mut impl FnMut(ThreadId) -> AgentMetadata,
) -> PlainH

作用：生成“等待结束”的历史记录，并列出各智能体最后的状态。这样用户能看到谁完成了、谁报错了。

数据流：输入等待的线程 ID 列表、后端返回的状态表、元数据查询函数 → 调用 wait_complete_lines 生成每个智能体的状态明细 → 加上“Finished waiting”标题 → 输出 PlainHistoryCell。

调用关系：tool_call_history_cell 在 Wait 已完成时调用它；它把复杂的状态行整理交给 wait_complete_lines，再用 collab_event 统一包装。

调用图：调用 3 个内部函数（collab_event, title_text, wait_complete_lines）；被 1 处调用（tool_call_history_cell）。

fn close_end(
    receiver_thread_id: ThreadId,
    agent_metadata: &mut impl FnMut(ThreadId) -> AgentMetadata,
) -> PlainHistoryCell

作用：生成“某个智能体已关闭”的历史记录。它让用户知道这个协作线程已经被结束。

数据流：输入被关闭的线程 ID 和元数据查询函数 → 找到这个智能体的显示名 → 生成“Closed 某某”的标题 → 输出没有额外明细的 PlainHistoryCell。

调用关系：它用于 CloseAgent 完成后的展示；它依赖 agent_label、title_with_agent 和 collab_event 组成最终行。

调用图：调用 3 个内部函数（agent_label, collab_event, title_with_agent）；外部调用 1 个（new）。

fn resume_begin(
    receiver_thread_id: ThreadId,
    agent_metadata: &mut impl FnMut(ThreadId) -> AgentMetadata,
) -> PlainHistoryCell

作用：生成“正在恢复某个智能体”的历史记录。用户能看到系统已经开始尝试恢复一个被暂停或中断的智能体。

数据流：输入目标线程 ID 和元数据查询函数 → 取到显示名 → 生成“Resuming 某某”的标题 → 输出 PlainHistoryCell。

调用关系：它用于 ResumeAgent 进行中的展示；它通过 agent_label、title_with_agent 和 collab_event 复用统一的标题和历史记录样式。

调用图：调用 3 个内部函数（agent_label, collab_event, title_with_agent）；外部调用 1 个（new）。

fn resume_end(
    receiver_thread_id: ThreadId,
    status: Option<&CollabAgentState>,
    fallback_error: &str,
    agent_metadata: &mut impl FnMut(ThreadId) -> AgentMetadata,
) -> PlainHistoryCell

作用：生成“恢复智能体结束”的历史记录，并显示恢复后的状态或失败原因。

数据流：输入目标线程 ID、可选状态、备用错误文案、元数据查询函数 → 生成“Resumed 某某”的标题 → 用 status_summary_line 把状态变成一行说明；如果没有状态就显示备用错误 → 输出 PlainHistoryCell。

调用关系：它用于 ResumeAgent 结束后的展示；标题部分沿用 agent_label 和 title_with_agent，整体由 collab_event 包装。

调用图：调用 3 个内部函数（agent_label, collab_event, title_with_agent）；外部调用 1 个（vec!）。

fn collab_event(title: Line<'static>, details: Vec<Line<'static>>) -> PlainHistoryCell

作用：把标题和明细行包装成统一样式的历史记录单元。它是本文件很多展示函数共用的“外壳”。

数据流：输入一行标题和若干明细行 → 标题放第一行 → 如果有明细，就给明细加上类似树枝的缩进前缀 → 输出 PlainHistoryCell。

调用关系：close_end、interaction_end、resume_begin、resume_end、spawn_end、sub_agent_activity_history_cell、waiting_begin、waiting_end 都会调用它；它再调用 prefix_lines 和 PlainHistoryCell::new 完成最终结构。

调用图：调用 2 个内部函数（new, prefix_lines）；被 8 处调用（close_end, interaction_end, resume_begin, resume_end, spawn_end, sub_agent_activity_history_cell, waiting_begin, waiting_end）；外部调用 1 个（vec!）。

fn title_text(title: impl Into<String>) -> Line<'static>

作用：生成一个只有纯标题文字的标题行。适合“Finished waiting”“Agent spawn failed”这种不需要带智能体名字的标题。

数据流：输入任意能变成字符串的标题 → 把它变成加粗文字片段 → 交给 title_spans_line 加统一圆点 → 输出一行标题。

调用关系：spawn_end、waiting_begin、waiting_end 会在需要简单标题时调用它；它把统一标题前缀交给 title_spans_line。

调用图：调用 1 个内部函数（title_spans_line）；被 3 处调用（spawn_end, waiting_begin, waiting_end）；外部调用 1 个（vec!）。

fn title_with_agent(
    prefix: &str,
    agent: AgentLabel<'_>,
    spawn_request: Option<&SpawnRequestSummary>,
) -> Line<'static>

作用：生成“动作 + 智能体 + 可选启动配置”的标题行。比如“Spawned Robie [explorer] (gpt-5 high)”。

数据流：输入动作前缀、智能体标签、可选启动配置 → 先放加粗动作词 → 加上智能体名字和角色 → 如果有模型和推理强度，再追加配置说明 → 输出统一格式标题行。

调用关系：close_end、interaction_end、resume_begin、resume_end、spawn_end、waiting_begin 都会用它；它把名字部分交给 agent_label_spans，把启动配置交给 spawn_request_spans，把最终行交给 title_spans_line。

调用图：调用 3 个内部函数（agent_label_spans, spawn_request_spans, title_spans_line）；被 6 处调用（close_end, interaction_end, resume_begin, resume_end, spawn_end, waiting_begin）；外部调用 1 个（vec!）。

fn title_spans_line(mut spans: Vec<Span<'static>>) -> Line<'static>

作用：给标题文字片段加上统一的开头圆点。这样所有协作事件看起来像同一类记录。

数据流：输入一组标题文字片段 → 在最前面插入一个灰色的“• ” → 输出一整行 Line。

调用关系：sub_agent_activity_title、title_text、title_with_agent 都会调用它；它是标题视觉风格的最后一道统一处理。

调用图：被 3 处调用（sub_agent_activity_title, title_text, title_with_agent）；外部调用 2 个（from, with_capacity）。

fn parse_thread_id(thread_id: &str) -> Option<ThreadId>

作用：把字符串形式的线程 ID 转成程序内部使用的 ThreadId。这样后续比较和显示更可靠。

数据流：输入一个字符串 → 调用 ThreadId 的解析方法 → 成功时输出 ThreadId，失败时输出 None。

调用关系：sub_agent_activity_display 会调用它来解析子智能体线程 ID；文件里其他流程也按同样思路过滤掉无法识别的 ID。

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

fn agent_label(thread_id: ThreadId, metadata: &AgentMetadata) -> AgentLabel<'_>

作用：把线程 ID 和元数据打包成一个临时的“智能体标签”。后面的显示函数会用它决定展示昵称、角色还是 ID。

数据流：输入线程 ID 和 AgentMetadata → 从元数据里借出昵称和角色 → 输出 AgentLabel，里面包含线程 ID、昵称、角色三个线索。

调用关系：close_end、interaction_end、resume_begin、resume_end、spawn_end、waiting_begin 都会先用它准备标签，再交给标题或明细渲染函数。

调用图：被 6 处调用（close_end, interaction_end, resume_begin, resume_end, spawn_end, waiting_begin）。

fn agent_label_line(agent: AgentLabel<'_>) -> Line<'static>

作用：把一个智能体标签变成单独一行。等待多个智能体时，可以用它列出每个被等待的人。

数据流：输入 AgentLabel → 调用 agent_label_spans 生成带样式的文字片段 → 输出一行 Line。

调用关系：它是 agent_label_spans 的薄包装，适合需要整行而不是片段列表的地方。

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

fn agent_label_spans(agent: AgentLabel<'_>) -> Vec<Span<'static>>

作用：把智能体标签变成可上色的文字片段。优先显示昵称，其次显示线程 ID，最后才显示泛泛的“agent”。

数据流：输入 AgentLabel → 清理昵称和角色里的空白 → 有昵称就用青色加粗显示昵称；没有昵称但有线程 ID 就显示 ID；都没有就显示“agent” → 如果有角色，再追加“[角色]” → 输出文字片段列表。

调用关系：agent_label_line 和 title_with_agent 会调用它；它是智能体名字在整个文件里保持一致显示的核心函数。

调用图：被 2 处调用（agent_label_line, title_with_agent）；外部调用 3 个（from, new, format!）。

fn spawn_request_spans(spawn_request: Option<&SpawnRequestSummary>) -> Vec<Span<'static>>

作用：把启动智能体时的模型和推理强度变成标题里的补充说明。比如显示成“(gpt-5 high)”。

数据流：输入可选 SpawnRequestSummary → 没有配置就输出空列表 → 如果模型为空且推理强度是默认值，也不显示 → 否则拼出括号说明并标成醒目颜色 → 输出文字片段列表。

调用关系：title_with_agent 会调用它；它只负责启动配置那一小段文字，不负责整条标题。

调用图：被 1 处调用（title_with_agent）；外部调用 4 个（default, new, format!, vec!）。

fn prompt_line(prompt: &str) -> Option<Line<'static>>

作用：把用户发给智能体的提示词整理成一行预览。太长的内容会被截短，避免历史记录难读。

数据流：输入提示词字符串 → 去掉前后空白 → 如果为空就输出 None → 如果非空就按固定长度截断，再包装成一行 Line → 输出可选行。

调用关系：interaction_end 和 spawn_end 会调用它来显示提示词明细；它依赖 truncate_text 处理“别太长”的规则。

调用图：调用 1 个内部函数（truncate_text）；被 2 处调用（interaction_end, spawn_end）；外部调用 2 个（from, from）。

fn wait_complete_lines(
    receiver_thread_ids: &[String],
    agents_states: &std::collections::HashMap<String, CollabAgentState>,
    agent_metadata: &mut impl FnMut(ThreadId) -> AgentMetadata,
) -

作用：整理“等待完成”时每个智能体的状态明细。它会尽量按等待列表显示，同时也补上状态表里额外出现的智能体。

数据流：输入等待的线程 ID 列表、状态表、元数据查询函数 → 先按等待列表解析并匹配状态 → 记录已经出现过的线程 → 再把状态表里未出现的额外线程按 ID 排序补进来 → 如果没有任何结果，输出“No agents completed yet”；否则输出每个智能体加状态摘要的一行。

调用关系：waiting_end 调用它生成明细行；它内部使用 agent_label_spans 和 status_summary_spans 让名字和状态都保持统一样式。

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

fn first_agent_state(
    receiver_thread_ids: &[String],
    agents_states: &'a std::collections::HashMap<String, CollabAgentState>,
) -> Option<&'a CollabAgentState>

作用：从一堆智能体状态里挑一个最适合代表当前结果的状态。恢复智能体结束时，如果有目标线程就优先用目标线程的状态。

数据流：输入接收方线程 ID 列表和状态表 → 先按接收方顺序找第一个有状态的线程 → 如果找不到，就按字符串 ID 取最小的那条状态 → 输出可选状态引用。

调用关系：它是 ResumeAgent 结束展示里的辅助选择器；选出的状态会被后续状态摘要函数变成用户能读的文字。

fn status_summary_line(status: Option<&CollabAgentState>, fallback_error: &str) -> Line<'static>

作用：把一个可选的智能体状态变成一整行说明。没有状态时，它会显示备用错误。

数据流：输入可选状态和备用错误文案 → 有状态就交给 status_summary_spans → 没有状态就交给 error_summary_spans → 输出一行 Line。

调用关系：resume_end 会用它显示恢复后的结果；它把具体的状态和错误文字样式分别交给 status_summary_spans、error_summary_spans。

调用图：调用 2 个内部函数（error_summary_spans, status_summary_spans）。

fn status_summary_spans(status: &CollabAgentState) -> Vec<Span<'static>>

作用：把智能体状态翻译成带颜色的短说明。比如运行中、已完成、报错、未找到等。

数据流：输入 CollabAgentState → 按状态枚举选择不同文字和颜色 → 完成状态会附带截短后的回复预览；错误状态会转交 error_summary_spans → 输出文字片段列表。

调用关系：status_summary_line 会调用它；等待完成明细也会用同样的状态摘要规则，保证不同地方看到的状态说法一致。

调用图：调用 2 个内部函数（error_summary_spans, truncate_text）；被 1 处调用（status_summary_line）；外部调用 2 个（from, vec!）。

fn error_summary_spans(error: &str) -> Vec<Span<'static>>

作用：把错误信息整理成短短一段红色提示。这样错误醒目，但不会因为太长挤爆界面。

数据流：输入错误字符串 → 先生成红色“Error” → 把错误内容压成单空格文本并截短 → 如果还有内容，就追加“ - 预览” → 输出文字片段列表。

调用关系：status_summary_line 在没有状态时会调用它；status_summary_spans 遇到 Errored 状态时也会调用它。

调用图：调用 1 个内部函数（truncate_text）；被 2 处调用（status_summary_line, status_summary_spans）；外部调用 2 个（from, vec!）。

fn collab_events_snapshot()

作用：用快照测试检查多种协作事件渲染出来的文字是否稳定。快照测试就是把输出保存成样本，以后改代码时对比有没有变。

数据流：测试先构造几个固定线程 ID 和多条事件，包括启动、发送输入、等待、等待完成、关闭 → 分别调用 tool_call_history_cell 转成历史记录 → 再把显示文本拼起来和快照比对。

调用关系：它直接验证 tool_call_history_cell 及其背后一串渲染函数；同时使用 agent_state、metadata_for、cell_to_text 等测试辅助函数准备数据和提取文字。

调用图：调用 2 个内部函数（from_string, tool_call_history_cell）；外部调用 5 个（from, new, assert_snapshot!, agent_state, vec!）。

fn agent_shortcut_matches_option_arrow_word_motion_fallbacks_only_when_allowed()

作用：在 macOS 上测试智能体切换快捷键的兼容规则。它确认 Option+b/f 只有在明确允许时才会被当成切换智能体。

数据流：测试输入多组模拟按键事件和 allow_word_motion_fallback 开关 → 调用 previous_agent_shortcut_matches、next_agent_shortcut_matches → 用断言确认标准方向键总能匹配，备用键只在允许时匹配。

调用关系：它保护 previous_agent_shortcut_matches、next_agent_shortcut_matches 以及两个 word_motion_fallback 函数的行为，避免兼容逻辑误伤正常文本编辑。

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

fn agent_shortcut_matches_option_arrows_only()

作用：在非 macOS 平台测试智能体切换只认 Alt+方向键。这样不同系统的备用规则不会串台。

数据流：测试构造 Alt+左、Alt+右、Alt+b、Alt+f 等按键 → 调用快捷键匹配函数 → 断言只有方向键会匹配，字母备用键不会匹配。

调用关系：它保护非 macOS 版本的 previous_agent_word_motion_fallback 和 next_agent_word_motion_fallback 始终返回 false 的设计。

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

fn title_styles_nickname_and_role()

作用：检查标题里昵称、角色和启动配置的文字内容与样式是否正确。它不只看文字，还看颜色和加粗效果。

数据流：测试构造一条启动智能体事件 → 调用 tool_call_history_cell 生成历史记录 → 取出第一行标题 → 断言昵称是青色加粗、角色格式正确、模型配置是紫色。

调用关系：它验证 tool_call_history_cell、title_with_agent、agent_label_spans、spawn_request_spans 这些函数配合后的最终显示效果。

调用图：调用 2 个内部函数（from_string, tool_call_history_cell）；外部调用 6 个（from, new, assert!, assert_eq!, agent_state, vec!）。

fn collab_resume_interrupted_snapshot()

作用：测试“恢复智能体后发现它被中断”的历史记录显示。它确保这种边界状态的文案不会意外变化。

数据流：测试构造一条 ResumeAgent 完成事件，状态是 Interrupted → 调用 tool_call_history_cell → 把结果转成文本并和快照比对。

调用关系：它覆盖 ResumeAgent 分支，间接验证 first_agent_state、resume_end、status_summary_line、status_summary_spans 的配合。

调用图：调用 2 个内部函数（from_string, tool_call_history_cell）；外部调用 4 个（from, assert_snapshot!, agent_state, vec!）。

fn agent_state(status: CollabAgentStatus, message: Option<&str>) -> CollabAgentState

作用：测试里用来快速造一个智能体状态对象。这样每个测试不用重复写结构体字段。

数据流：输入状态枚举和可选消息字符串 → 把消息转成 owned 字符串 → 输出 CollabAgentState。

调用关系：collab_events_snapshot、title_styles_nickname_and_role、collab_resume_interrupted_snapshot 都用它准备测试事件里的状态数据。

fn metadata_for(thread_id: ThreadId, robie_id: ThreadId, bob_id: ThreadId) -> AgentMetadata

作用：测试里按线程 ID 返回固定的昵称和角色。它让测试能验证“Robie [explorer]”“Bob [worker]”这类显示。

数据流：输入一个线程 ID，以及 Robie 和 Bob 的已知 ID → 如果匹配 Robie 就返回 Robie 的元数据，匹配 Bob 就返回 Bob 的元数据，否则返回空元数据 → 输出 AgentMetadata。

调用关系：多个渲染测试把它作为回调传给 tool_call_history_cell；这样生产代码以为自己在查询真实元数据，测试则得到可预测结果。

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

fn cell_to_text(cell: &PlainHistoryCell) -> String

作用：把一个历史记录单元转成纯文本，方便做快照对比。样式颜色不在这里保留，只看最终文字。

数据流：输入 PlainHistoryCell → 按固定宽度取出显示行 → 每行交给 line_to_text 去掉样式 → 用换行拼成字符串 → 输出纯文本。

调用关系：快照测试会用它把 tool_call_history_cell 的结果变成可比较文本；它把单行处理交给 line_to_text。

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

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

作用：把一行带样式的终端文字变成普通字符串。它用于测试时忽略颜色，只比较可见文字。

数据流：输入一行 Line → 遍历里面的每个 Span，取出文字内容 → 拼接成一个字符串 → 输出纯文本行。

调用关系：cell_to_text 会逐行调用它；它是快照测试文本提取的最底层小工具。

fn new_transcript(cells: Vec<Arc<dyn HistoryCell>>, keymap: PagerKeymap) -> Self

作用：创建一个聊天记录覆盖层，用来显示完整对话历史。用户打开 transcript 页面时会用到它。

数据流：进去的是历史消息列表和翻页按键配置 → 它把这些交给 TranscriptOverlay 创建真正的记录页 → 出来的是 Overlay 这个统一外壳里的 Transcript 版本。

调用关系：它是外部打开记录页时的入口之一；调用 TranscriptOverlay::new 做具体搭建，然后让上层只需要拿 Overlay 来统一处理事件。

调用图：调用 1 个内部函数（new）；被 5 处调用（handle_key_event, clear_only_ui_reset_preserves_chat_session_state, queued_rollback_syncs_overlay_and_clears_deferred_history, open_transcript_overlay, open_pending_transcript_if_ready）；外部调用 1 个（Transcript）。

fn new_static_with_lines(
        lines: Vec<Line<'static>>,
        title: String,
        keymap: PagerKeymap,
    ) -> Self

作用：创建一个显示固定文本行的覆盖层，比如帮助信息或说明文字。它适合内容已经是一行一行文本的场景。

数据流：进去的是文本行、标题和按键配置 → 它调用 StaticOverlay::with_title 包成可滚动页面 → 出来的是 Overlay 的 Static 版本。

调用关系：当应用需要弹出静态阅读页时会走这里；它把具体页面构造交给 StaticOverlay。

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

fn new_static_with_renderables(
        renderables: Vec<Box<dyn Renderable>>,
        title: String,
        keymap: PagerKeymap,
    ) -> Self

作用：创建一个显示自定义可绘制内容的静态覆盖层。比纯文本更灵活，因为每块内容可以自己决定怎么画。

数据流：进去的是一组可绘制块、标题和按键配置 → 它调用 StaticOverlay::with_renderables → 出来的是统一 Overlay 外壳。

调用关系：它服务于已经准备好 Renderable 内容的调用方；后续事件处理仍由 Overlay::handle_event 分发。

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

fn handle_event(&mut self, tui: &mut tui::Tui, event: TuiEvent) -> Result<()>

作用：把键盘、重绘、窗口变化等事件转交给当前真正的覆盖层。这样外部不必关心现在打开的是记录页还是静态页。

数据流：进去的是一个 TUI 对象和一个事件 → 它看 Overlay 里装的是 Transcript 还是 Static → 把事件交给对应对象处理，并返回是否成功。

调用关系：它是覆盖层运行时的统一事件入口；上层主循环调用它，它再分派给 TranscriptOverlay::handle_event 或 StaticOverlay::handle_event。

fn is_done(&self) -> bool

作用：告诉外部这个覆盖层是不是该关闭了。比如用户按了退出键以后，这里会返回真。

数据流：进去的是当前 Overlay 状态 → 它询问内部具体覆盖层的完成标记 → 出来的是一个布尔值。

调用关系：主界面会用它判断是否移除覆盖层；它只是统一转问 TranscriptOverlay 或 StaticOverlay。

fn first_or_empty(bindings: &[KeyBinding]) -> Vec<KeyBinding>

作用：从一组快捷键里取第一个来显示提示；如果没有快捷键，就返回空列表。它让底部提示不会因为缺配置而出错。

数据流：进去的是快捷键数组 → 它尝试拿第一个并复制出来 → 出来的是包含一个键或为空的列表。

调用关系：两个覆盖层的 render_hints 都用它准备底部提示；它把复杂按键列表压缩成适合展示的简短形式。

调用图：被 2 处调用（render_hints, render_hints）；外部调用 1 个（first）。

fn render_key_hints(area: Rect, buf: &mut Buffer, pairs: &[(Vec<KeyBinding>, &str)])

作用：把“按什么键做什么事”的提示画成一行。用户看到的底部快捷键说明主要由它生成。

数据流：进去的是屏幕区域、缓冲区和若干组键名加说明 → 它拼出带间隔的文字片段并变暗显示 → 结果写进终端绘图缓冲区。

调用关系：TranscriptOverlay::render_hints 和 StaticOverlay::render_hints 都调用它；它是底部提示栏的公共画笔。

调用图：被 2 处调用（render_hints, render_hints）；外部调用 3 个（new, from, vec!）。

fn new(
        renderables: Vec<Box<dyn Renderable>>,
        title: String,
        scroll_offset: usize,
        keymap: PagerKeymap,
    ) -> Self

作用：创建一个通用翻页视图。它保存要显示的内容、标题、当前滚动位置和按键规则。

数据流：进去的是可绘制内容列表、标题、初始滚动位置和按键配置 → 它组装成 PagerView 状态 → 出来的是一个可渲染、可滚动的阅读器。

调用关系：TranscriptOverlay 和 StaticOverlay 都靠它承载正文显示；测试工具 pager_view 也用它直接构造视图。

调用图：被 3 处调用（with_renderables, new, pager_view）。

fn content_height(&self, width: u16) -> usize

作用：计算所有内容在某个宽度下总共需要多少行。窗口变窄会换行，所以高度必须按宽度重新算。

数据流：进去的是屏幕宽度 → 它逐个询问每个内容块需要的高度并相加 → 出来的是总行数。

调用关系：PagerView::render 在绘制前调用它，用来限制滚动范围和计算底部百分比。

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

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

作用：把整个翻页页画出来，包括标题、正文、滚动裁剪和底部进度条。它是 PagerView 的主绘制函数。

数据流：进去的是可画区域和缓冲区 → 它清屏、画标题、算正文区域和内容高度、处理待定位内容、修正滚动偏移、画正文和底栏 → 缓冲区变成完整页面画面。

调用关系：TranscriptOverlay::render 和 StaticOverlay::render 都调用它；它内部串起 render_header、render_content、render_bottom_bar 等零件。

调用图：调用 7 个内部函数（content_area, content_height, ensure_chunk_visible, render_bottom_bar, render_content, render_header, update_last_content_height）；被 2 处调用（render, render）。

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

作用：画顶部标题栏。它用斜杠背景和标题文字告诉用户当前页面是什么。

数据流：进去的是区域和缓冲区 → 它先铺一排淡色斜杠，再写入标题 → 缓冲区顶部出现页眉。

调用关系：只由 PagerView::render 调用，是完整页面绘制流程的第一步。

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

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

作用：按当前滚动位置画正文，只画用户现在能看到的那一段。内容不够铺满时，它会用波浪号和空格填下面的空白。

数据流：进去的是正文区域和缓冲区 → 它根据 scroll_offset 跳过上方内容、裁剪部分露出的内容块、逐块绘制 → 最后补齐空白区域。

调用关系：由 PagerView::render 调用；当某个内容块顶部已经被滚走一部分时，它会把活交给 render_offset_content。

调用图：调用 1 个内部函数（render_offset_content）；被 1 处调用（render）；外部调用 4 个（from, bottom, new, right）。

fn render_bottom_bar(
        &self,
        full_area: Rect,
        content_area: Rect,
        buf: &mut Buffer,
        total_len: usize,
    )

作用：画底部横线和滚动百分比。用户可以知道自己大概看到了全文的哪个位置。

数据流：进去的是总区域、正文区域、缓冲区和总内容高度 → 它计算最大滚动距离和当前百分比 → 把分隔线和百分比写到底部。

调用关系：由 PagerView::render 在正文之后调用，是翻页页面的状态提示。

调用图：被 1 处调用（render）；外部调用 4 个（bottom, new, from, format!）。

fn handle_key_event(&mut self, tui: &mut tui::Tui, key_event: KeyEvent) -> Result<()>

作用：处理滚动相关按键，比如上下一行、翻页、半页、跳到顶部或底部。它让阅读器真正能被键盘控制。

数据流：进去的是 TUI 对象和一个按键事件 → 它按 keymap 判断是哪种滚动命令并修改 scroll_offset → 如果发生滚动，就请求下一帧重画。

调用关系：TranscriptOverlay::handle_event 和 StaticOverlay::handle_event 把非关闭键交给它；它需要 page_height 和 content_area 来算翻多少。

调用图：调用 2 个内部函数（content_area, page_height）；被 2 处调用（handle_event, handle_event）；外部调用 1 个（frame_requester）。

fn page_height(&self, viewport_area: Rect) -> usize

作用：告诉翻页键一次该移动多少行。它优先使用上次实际绘制时的正文高度，避免页翻得不准。

数据流：进去的是终端可视区域 → 它先看是否记过上次正文高度，没有就按当前区域估算 → 出来的是一页的行数。

调用关系：PagerView::handle_key_event 在 PageUp 和 PageDown 时调用它。

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

fn update_last_content_height(&mut self, height: u16)

作用：记录最近一次正文区域有多高。这个值会影响之后翻页是否连续。

数据流：进去的是高度 → 它保存到 last_content_height → 之后 page_height 和底部判断可复用这个信息。

调用关系：PagerView::render 每次绘制时调用它，为后续按键处理提供真实布局数据。

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

fn content_area(&self, area: Rect) -> Rect

作用：从整个页面区域里切出正文区域。它会给顶部标题和底部栏留出空间。

数据流：进去的是完整矩形区域 → 它把 y 往下挪一行，并把高度减两行 → 出来的是正文可用区域。

调用关系：PagerView::render 和 PagerView::handle_key_event 都用它，保证绘制和滚动计算用的是同一块地方。

调用图：被 2 处调用（handle_key_event, render）。

fn is_scrolled_to_bottom(&self) -> bool

作用：判断用户当前是不是在内容底部。这个判断关系到新内容来了以后要不要自动跟着滚下去。

数据流：进去的是当前滚动状态、上次正文高度和内容总高度 → 它处理空内容、内容不满屏、特殊的“跳到底”值等情况 → 出来是真或假。

调用关系：TranscriptOverlay 在插入、替换、合并和同步实时尾巴前都会问它；这样能保护用户手动滚上去看的位置。

调用图：被 5 处调用（consolidate_cells, insert_cell, is_scrolled_to_bottom, replace_cells, sync_live_tail）。

fn scroll_chunk_into_view(&mut self, chunk_index: usize)

作用：请求下次绘制时把某个内容块滚到可见范围内。常用于高亮某条消息后自动把它带到屏幕里。

数据流：进去的是内容块序号 → 它暂存为 pending_scroll_chunk → 下次 render 时再按实际宽度和换行情况调整滚动。

调用关系：TranscriptOverlay::set_highlight_cell 调用它；真正执行滚动的是 PagerView::ensure_chunk_visible。

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

fn ensure_chunk_visible(&mut self, idx: usize, area: Rect)

作用：确保指定内容块在当前正文区域里能看见。它会根据内容块上下边界调整滚动位置。

数据流：进去的是内容块序号和正文区域 → 它计算该块之前的高度、该块自己的高度、当前可视范围 → 必要时改动 scroll_offset。

调用关系：PagerView::render 在发现有 pending_scroll_chunk 时调用它；这样滚动计算使用最新宽度下的实际换行高度。

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

fn new(renderable: impl Into<Box<dyn Renderable>>) -> Self

作用：把一个可绘制内容包起来，加上高度缓存。这样反复绘制时不用每次都重新算高度。

数据流：进去的是一个可转换成 Renderable 的内容 → 它保存原内容，并把缓存高度和上次宽度置空 → 出来的是 CachedRenderable。

调用关系：记录单元、实时尾巴、静态文本都会被它包住；调用方通常是 TranscriptOverlay::render_cells、TranscriptOverlay::live_tail_renderable 和 StaticOverlay::with_title。

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

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

作用：实际绘制缓存包装里的原始内容。缓存只管高度，不改变内容怎么画。

数据流：进去的是绘制区域和缓冲区 → 它直接调用内部 renderable 的 render → 结果写入同一个缓冲区。

调用关系：PagerView 绘制内容块时会通过 Renderable 接口间接调用它。

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

作用：返回内容在指定宽度下需要的高度，并尽量复用上次结果。宽度没变时就不重新计算。

数据流：进去的是宽度 → 如果宽度和上次不同，它询问内部内容高度并缓存；如果相同，就取缓存 → 出来的是高度。

调用关系：PagerView 计算总高度、裁剪内容和滚动时都会间接用它；这是减少重复排版开销的关键。

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

作用：把一条历史消息画到 transcript 页面里，并保留其中的终端超链接。超链接是可点击或可识别的网址标记。

数据流：进去的是区域和缓冲区 → 它向 HistoryCell 要带链接信息的文本行，转换成可见文字，用指定样式绘制，再把链接标记写回缓冲区 → 屏幕上既有文字也有链接信息。

调用关系：TranscriptOverlay::render_cells 会为每个历史消息创建它；PagerView 最终通过 Renderable 接口调用它。

调用图：调用 2 个内部函数（mark_buffer_hyperlinks, visible_lines）；外部调用 2 个（new, from）。

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

作用：询问这条历史消息在某个宽度下会占多少行。它用于滚动和分页计算。

数据流：进去的是宽度 → 它转问 HistoryCell 的 transcript 高度 → 出来的是行数。

调用关系：被 PagerView 通过 Renderable 接口调用；通常外面还套了一层 CachedRenderable 来缓存结果。

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

作用：绘制一组已经带有链接信息的文本行。它主要用于正在生成的实时尾巴。

数据流：进去的是区域和缓冲区 → 它把带链接行变成可见文字画出来，再把链接位置标到缓冲区 → 输出可见文字和可保留的链接。

调用关系：TranscriptOverlay::live_tail_renderable 会创建它；PagerView 负责在页面底部把它画出来。

调用图：调用 2 个内部函数（mark_buffer_hyperlinks, visible_lines）；外部调用 2 个（new, from）。

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

作用：计算带链接文本在某个宽度下换行后需要多少行。这样实时尾巴也能参与滚动计算。

数据流：进去的是宽度 → 它把链接行转成可见文字，交给段落排版计算行数 → 出来的是高度，转换失败时用 0。

调用关系：PagerView 通过 Renderable 接口调用它；外层通常由 CachedRenderable 缓存高度。

调用图：调用 1 个内部函数（visible_lines）；外部调用 2 个（new, from）。

fn new(transcript_cells: Vec<Arc<dyn HistoryCell>>, keymap: PagerKeymap) -> Self

作用：创建聊天记录覆盖层。它一开始显示已提交的历史消息，并默认滚到底部。

数据流：进去的是历史消息和按键配置 → 它把消息转换成可绘制块，创建标题为 TRANSCRIPT 的 PagerView，设置内部状态 → 出来的是 TranscriptOverlay。

调用关系：Overlay::new_transcript 和测试辅助 transcript_overlay 会调用它；之后由 App 在绘制和事件处理中继续驱动。

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

fn render_cells(
        cells: &[Arc<dyn HistoryCell>],
        highlight_cell: Option<usize>,
    ) -> Vec<Box<dyn Renderable>>

作用：把一组历史消息转换成 PagerView 能显示的内容块。它还会处理用户消息样式、高亮和消息之间的空行。

数据流：进去的是历史消息列表和可选高亮序号 → 它逐条包装成 CellRenderable 和 CachedRenderable，必要时加顶部缩进 → 出来的是可绘制块列表。

调用关系：TranscriptOverlay::new、rebuild_renderables、insert_cell 等都依赖它重建正文；这是历史数据变成屏幕内容的转换点。

fn insert_cell(&mut self, cell: Arc<dyn HistoryCell>)

作用：在记录页里加入一条新的已完成历史消息，同时尽量保留实时尾巴和滚动位置。新消息到来时会用到它。

数据流：进去的是一条历史消息 → 它先判断是否在底部，临时取下实时尾巴，追加消息并重建历史内容，再把尾巴接回去 → 如果原本在底部，就继续保持到底部。

调用关系：上层 App 在 transcript 打开期间有新提交消息时会调用它；它内部用 PagerView::is_scrolled_to_bottom、take_live_tail_renderable 和 render_cells。

调用图：调用 4 个内部函数（is_scrolled_to_bottom, take_live_tail_renderable, tlbr, new）；外部调用 2 个（new, render_cells）。

fn replace_cells(&mut self, cells: Vec<Arc<dyn HistoryCell>>)

作用：整体替换已提交的历史消息列表，同时保留正在显示的实时尾巴。比如回滚或裁剪历史后需要同步页面。

数据流：进去的是新的历史消息列表 → 它记录是否跟随底部，替换 cells，清掉越界高亮，重建可绘制内容 → 必要时继续滚到底部。

调用关系：当主聊天记录发生批量变化时会用它；具体重建交给 rebuild_renderables。

调用图：调用 2 个内部函数（is_scrolled_to_bottom, rebuild_renderables）。

fn consolidate_cells(
        &mut self,
        range: std::ops::Range<usize>,
        consolidated: Arc<dyn HistoryCell>,
    )

作用：把一段历史消息合并成一条显示，保持 transcript 页面和主记录一致。它还会修正高亮位置。

数据流：进去的是要合并的范围和合并后的消息 → 它先把范围夹到现有长度内，调整高亮序号，替换 cells 中那一段，重建显示 → 如果之前在底部则继续到底。

调用关系：主流程把多条 agent 消息合并时会调用它；它保护 overlay 即使消息数量不同步也不崩。

调用图：调用 2 个内部函数（is_scrolled_to_bottom, rebuild_renderables）；外部调用 1 个（once）。

fn sync_live_tail(
        &mut self,
        width: u16,
        active_key: Option<ActiveCellTranscriptKey>,
        compute_lines: impl FnOnce(u16) -> Option<Vec<HyperlinkLine>>,
    )

作用：同步 transcript 底部那段“还没提交、正在生成”的内容。它只在版本键变化时重算，避免每帧都做昂贵排版。

数据流：进去的是宽度、活动消息版本信息和一个生成文本行的函数 → 它组成缓存键，若没变就直接返回；若变了，取下旧尾巴，按需计算新尾巴并接到末尾 → 保持原本的跟随底部行为。

调用关系：App 在绘制 TranscriptOverlay 时调用它；它把实时内容包装交给 live_tail_renderable，并依赖 take_live_tail_renderable 管理末尾缓存块。

调用图：调用 2 个内部函数（is_scrolled_to_bottom, take_live_tail_renderable）；外部调用 1 个（live_tail_renderable）。

fn set_highlight_cell(&mut self, cell: Option<usize>)

作用：设置哪条历史消息被高亮，并请求把它滚到可见范围。编辑上一条或下一条消息时会用到。

数据流：进去的是可选消息序号 → 它保存高亮状态，重建可绘制内容 → 如果有高亮，就通知 PagerView 下次把那块滚出来。

调用关系：外部编辑导航会调用它；它内部调用 rebuild_renderables 和 PagerView::scroll_chunk_into_view。

调用图：调用 2 个内部函数（scroll_chunk_into_view, rebuild_renderables）。

fn is_scrolled_to_bottom(&self) -> bool

作用：告诉外部 transcript 当前是否停在底部。外部可以据此决定是否继续驱动看得见的动画。

数据流：进去的是 overlay 当前状态 → 它转问内部 PagerView → 出来的是是否到底部。

调用关系：App 绘制循环会用它判断实时尾巴动画是否值得刷新；它只是 PagerView::is_scrolled_to_bottom 的公开包装。

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

fn rebuild_renderables(&mut self)

作用：重新生成 transcript 的所有可绘制内容，同时保留末尾实时尾巴。历史数据或高亮变化后需要它。

数据流：进去的是当前 cells、高亮和可能存在的尾巴 → 它先取下尾巴，重新把 cells 转成内容块，再把尾巴接回末尾 → view.renderables 被更新。

调用关系：replace_cells、consolidate_cells、set_highlight_cell 调用它；它用 take_live_tail_renderable 和 render_cells 完成重建。

调用图：调用 1 个内部函数（take_live_tail_renderable）；被 3 处调用（consolidate_cells, replace_cells, set_highlight_cell）；外部调用 1 个（render_cells）。

fn take_live_tail_renderable(&mut self) -> Option<Box<dyn Renderable>>

作用：把末尾的实时尾巴内容块临时取下来。这样重建历史内容时不会把尾巴弄丢或重复。

数据流：进去的是当前 renderables 和 cells 数量 → 如果可绘制块比已提交消息多，就弹出最后一块 → 出来的是可选尾巴内容块，并改变 renderables。

调用关系：insert_cell、rebuild_renderables、sync_live_tail 都用它；它依赖一个约定：实时尾巴永远放在最后。

调用图：被 3 处调用（insert_cell, rebuild_renderables, sync_live_tail）。

fn live_tail_renderable(
        lines: Vec<HyperlinkLine>,
        has_prior_cells: bool,
        is_stream_continuation: bool,
    ) -> Box<dyn Renderable>

作用：把实时尾巴文本行包装成可显示内容，并按需要加上和上一条消息之间的空行。

数据流：进去的是带链接文本行、是否已有历史消息、是否是上一段的延续 → 它创建 HyperlinkLinesRenderable 并缓存高度，如果不是连续流且前面有消息就加顶部空白 → 出来的是一个 Renderable。

调用关系：TranscriptOverlay::sync_live_tail 在需要刷新尾巴时调用它；它组合 CachedRenderable、HyperlinkLinesRenderable 和 InsetRenderable。

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

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

作用：绘制 transcript 页面底部两行快捷键提示。它会根据是否有高亮消息显示不同的编辑提示。

数据流：进去的是底部区域和缓冲区 → 它准备滚动、翻页、跳转、退出、编辑上一条/下一条等提示 → 调用 render_key_hints 写到缓冲区。

调用关系：TranscriptOverlay::render 在画完主体后调用它；它使用 first_or_empty 缩短按键显示。

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

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

作用：绘制完整 transcript 覆盖层。上面是可滚动记录，下面是快捷键提示。

数据流：进去的是全屏区域和缓冲区 → 它把区域分成上方正文和下方三行提示 → 先让 PagerView 画正文，再画提示。

调用关系：TranscriptOverlay::handle_event 在 Draw 或 Resize 时通过 tui.draw 调用它；测试里的 transcript_line_numbers 也直接用它检查可见内容。

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

fn handle_event(&mut self, tui: &mut tui::Tui, event: TuiEvent) -> Result<()>

作用：处理 transcript 覆盖层收到的事件。关闭键会结束页面，滚动键会交给 PagerView，重绘事件会画页面。

数据流：进去的是 TUI 和事件 → 如果是关闭键就设置 is_done；如果是其他键就交给 PagerView；如果是绘制或缩放就调用 tui.draw 渲染 → 返回处理结果。

调用关系：Overlay::handle_event 会把 Transcript 类型的事件交给它；它是 transcript 页面运行时的事件调度点。

调用图：调用 1 个内部函数（handle_key_event）；外部调用 1 个（draw）。

fn is_done(&self) -> bool

作用：返回 transcript 页面是否已经请求关闭。用户按退出键后这里会变成真。

数据流：进去的是当前对象状态 → 它读取 is_done 字段 → 出来的是布尔值。

调用关系：Overlay::is_done 会转问它，主循环据此关闭覆盖层。

fn committed_cell_count(&self) -> usize

作用：在测试里查看 transcript 里有多少条已提交消息。它帮助确认插入、替换、合并是否正确。

数据流：进去的是 overlay 状态 → 它读取 cells 的长度 → 出来的是数量。

调用关系：这是只在测试配置下编译的辅助函数，不参与正常运行。

fn with_title(
        lines: Vec<Line<'static>>,
        title: String,
        keymap: PagerKeymap,
    ) -> Self

作用：用普通文本行创建一个带标题的静态覆盖层。它把文本包装成可换行段落。

数据流：进去的是文本行、标题和按键配置 → 它创建 Paragraph 并加换行设置，再交给 with_renderables → 出来的是 StaticOverlay。

调用关系：Overlay::new_static_with_lines 和测试辅助 static_overlay 调用它；真正通用构造交给 StaticOverlay::with_renderables。

调用图：被 2 处调用（new_static_with_lines, static_overlay）；外部调用 4 个（new, with_renderables, from, vec!）。

fn with_renderables(
        renderables: Vec<Box<dyn Renderable>>,
        title: String,
        keymap: PagerKeymap,
    ) -> Self

作用：用一组可绘制内容创建静态覆盖层。适合内容不只是普通文本的情况。

数据流：进去的是可绘制块、标题和按键配置 → 它创建 PagerView，初始滚动在顶部，并设置未完成状态 → 出来的是 StaticOverlay。

调用关系：Overlay::new_static_with_renderables 和 with_title 都会走到这里；后续绘制、滚动由内部 PagerView 完成。

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

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

作用：绘制静态页底部快捷键提示。它只显示滚动、翻页、跳转和退出这些阅读操作。

数据流：进去的是底部区域和缓冲区 → 它准备两行提示内容 → 调用 render_key_hints 写入缓冲区。

调用关系：StaticOverlay::render 在主体绘制后调用它；它复用 first_or_empty 和 render_key_hints。

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

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

作用：绘制完整静态覆盖层。结构和 transcript 类似：上方内容，下方提示。

数据流：进去的是屏幕区域和缓冲区 → 它切出上方主体和下方三行提示 → 先画 PagerView，再画快捷键提示。

调用关系：StaticOverlay::handle_event 在需要重绘时通过 tui.draw 调用它。

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

fn handle_event(&mut self, tui: &mut tui::Tui, event: TuiEvent) -> Result<()>

作用：处理静态覆盖层的事件。退出键关闭页面，滚动键交给通用 PagerView。

数据流：进去的是 TUI 和事件 → 关闭键会设置 is_done；其他键交给 PagerView；绘制或缩放会调用 render → 返回处理结果。

调用关系：Overlay::handle_event 会把 Static 类型的事件交给它；它和 TranscriptOverlay::handle_event 是并列的运行入口。

调用图：调用 1 个内部函数（handle_key_event）；外部调用 1 个（draw）。

fn is_done(&self) -> bool

作用：告诉外部静态页是否已经关闭。它用于主循环清理覆盖层。

数据流：进去的是当前状态 → 它读取 is_done → 出来是真或假。

调用关系：Overlay::is_done 会调用它，保持外部统一判断方式。

fn render_offset_content(
    area: Rect,
    buf: &mut Buffer,
    renderable: &dyn Renderable,
    scroll_offset: u16,
) -> u16

作用：绘制一个顶部已经被滚掉一部分的内容块。它像先把整块画到临时纸上，再剪下可见部分贴到屏幕上。

数据流：进去的是目标区域、目标缓冲区、内容块和内部滚动偏移 → 它创建临时缓冲区，先让内容块画完整可需部分，再把偏移后的可见行复制到目标缓冲区 → 返回复制了多少行。

调用关系：PagerView::render_content 在内容块半露半藏时调用它；这是正确裁剪复杂内容块的关键。

调用图：被 1 处调用（render_content）；外部调用 4 个（empty, new, desired_height, render）。

fn display_lines(&self, _width: u16) -> Vec<Line<'static>>

作用：测试用的假历史消息返回要显示的行。它让测试不用依赖真实聊天消息类型。

数据流：进去的是宽度但测试里不使用 → 它复制保存的 lines → 出来的是显示行列表。

调用关系：测试构造 TranscriptOverlay 时通过 HistoryCell 接口间接调用它。

fn raw_lines(&self) -> Vec<Line<'static>>

作用：测试用假消息返回原始文本行。它满足 HistoryCell 接口要求。

数据流：进去的是 TestCell → 它复制内部 lines → 出来的是原始行列表。

调用关系：只在测试环境中作为 HistoryCell 的一部分存在，支撑各种 transcript 渲染测试。

fn transcript_lines(&self, _width: u16) -> Vec<Line<'static>>

作用：测试用假消息返回 transcript 页面要用的文本行。这里直接返回保存的行。

数据流：进去的是宽度但不使用 → 它复制内部 lines → 出来的是 transcript 行列表。

调用关系：TranscriptOverlay 渲染测试通过 HistoryCell 接口使用它。

fn paragraph_block(label: &str, lines: usize) -> Box<dyn Renderable>

作用：快速造一个有多行文字的可绘制段落，用来测试 PagerView 的高度和滚动。

数据流：进去的是标签和行数 → 它生成 label0、label1 这样的文本行并包装成 Paragraph → 出来的是 Renderable。

调用关系：多个 PagerView 单元测试用它构造假内容块。

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

fn default_pager_keymap() -> crate::keymap::PagerKeymap

作用：拿一份默认翻页按键配置给测试用。这样测试不用手写每个快捷键。

数据流：进去没有参数 → 它读取 RuntimeKeymap 的默认值并取出 pager 部分 → 出来的是 PagerKeymap。

调用关系：测试辅助 transcript_overlay、static_overlay、pager_view 都调用它。

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

fn transcript_overlay(cells: Vec<Arc<dyn HistoryCell>>) -> TranscriptOverlay

作用：测试里快速创建 TranscriptOverlay。它减少重复样板代码。

数据流：进去的是历史消息列表 → 它取默认按键配置并调用 TranscriptOverlay::new → 出来的是记录覆盖层。

调用关系：大多数 transcript 相关测试都通过它创建对象。

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

fn static_overlay(lines: Vec<Line<'static>>, title: &str) -> StaticOverlay

作用：测试里快速创建 StaticOverlay。它把文本行和标题包装成静态页。

数据流：进去的是文本行和标题 → 它取默认按键配置并调用 StaticOverlay::with_title → 出来的是静态覆盖层。

调用关系：静态页快照和换行测试会用它。

调用图：调用 1 个内部函数（with_title）；外部调用 1 个（default_pager_keymap）。

fn pager_view(
        renderables: Vec<Box<dyn Renderable>>,
        title: &str,
        scroll_offset: usize,
    ) -> PagerView

作用：测试里直接创建 PagerView。用于绕开外层 overlay，专门检查滚动和高度算法。

数据流：进去的是内容块、标题和初始滚动位置 → 它加上默认按键配置并调用 PagerView::new → 出来的是 PagerView。

调用关系：PagerView 的高度、定位、到底判断测试都用它。

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

fn edit_prev_hint_is_visible()

作用：确认 transcript 底部能看到“编辑上一条”的提示。这个提示对用户找编辑入口很重要。

数据流：进去没有业务输入 → 它创建一条假消息的 overlay，渲染到宽缓冲区，转成文字 → 断言里面包含 edit prev。

调用关系：它测试 TranscriptOverlay::render_hints 的实际输出。

调用图：外部调用 6 个（empty, new, assert!, buffer_to_text, transcript_overlay, vec!）。

fn edit_next_hint_is_visible_when_highlighted()

作用：确认有高亮消息时会显示“编辑下一条”的提示。没有这个，编辑导航提示会不完整。

数据流：进去没有参数 → 它创建 overlay、设置高亮、渲染、转文本 → 断言包含 edit next。

调用关系：它覆盖 TranscriptOverlay::set_highlight_cell 对底部提示的影响。

调用图：外部调用 6 个（empty, new, assert!, buffer_to_text, transcript_overlay, vec!）。

fn transcript_overlay_snapshot_basic()

作用：用快照检查基础 transcript 页面长什么样。快照测试就是把输出画面保存下来，以后防止无意变化。

数据流：进去没有参数 → 它创建三条假消息，渲染到测试终端 → 和保存的快照比对。

调用关系：它验证 TranscriptOverlay::render 和 PagerView::render 的整体配合。

调用图：外部调用 5 个（new, assert_snapshot!, new, transcript_overlay, vec!）。

fn transcript_overlay_preserves_semantic_web_links()

作用：确认 transcript 里的网页链接不会在渲染后丢失。文字换行时链接标记很容易出错，所以要专门测。

数据流：进去没有参数 → 它创建含长链接的消息，渲染到窄区域 → 检查缓冲区里还能找到终端超链接标记。

调用关系：它主要验证 CellRenderable::render 和 mark_buffer_hyperlinks 的配合。

调用图：外部调用 5 个（empty, new, assert!, transcript_overlay, vec!）。

fn transcript_overlay_renders_live_tail()

作用：确认 transcript 能显示正在生成的实时尾巴。用户打开记录页时应该也能看到当前流式输出。

数据流：进去没有参数 → 它创建已有消息，调用 sync_live_tail 加入 tail，再渲染 → 用快照验证画面。

调用关系：它测试 TranscriptOverlay::sync_live_tail、live_tail_renderable 和 render 的组合。

调用图：外部调用 5 个（new, assert_snapshot!, new, transcript_overlay, vec!）。

fn transcript_overlay_live_tail_preserves_semantic_web_links()

作用：确认实时尾巴里的链接也能保留下来。不是只有已提交消息才应该支持链接。

数据流：进去没有参数 → 它把一个含链接的活动消息转换成尾巴行，渲染 overlay → 检查缓冲区中存在链接标记。

调用关系：它验证 HyperlinkLinesRenderable::render 在 live tail 场景下的链接处理。

调用图：调用 1 个内部函数（new）；外部调用 6 个（empty, new, new, assert!, new, transcript_overlay）。

fn transcript_overlay_sync_live_tail_is_noop_for_identical_key()

作用：确认实时尾巴版本没变时不会重复计算。这样可以避免无意义的昂贵刷新。

数据流：进去没有参数 → 它用同一个 key 调用 sync_live_tail 两次，并统计生成函数被调用次数 → 断言只调用一次。

调用关系：它直接测试 TranscriptOverlay::sync_live_tail 的缓存键逻辑。

调用图：外部调用 4 个（assert_eq!, new, transcript_overlay, vec!）。

fn buffer_to_text(buf: &Buffer, area: Rect) -> String

作用：把测试绘图缓冲区转成普通字符串，方便断言和快照。它把不可见的终端格子变成可读文本。

数据流：进去的是缓冲区和区域 → 它逐行逐列读取符号，空格补齐并裁掉行尾空白 → 出来的是多行字符串。

调用关系：多个测试用它检查渲染后的文字内容。

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

fn transcript_overlay_apply_patch_scroll_vt100_clears_previous_page()

作用：确认 transcript 翻滚后旧页面内容会被清干净。终端复用缓冲区时，如果不清，旧字符可能残留。

数据流：进去没有参数 → 它构造包含补丁、审批、命令输出的复杂历史，先渲染到底部再滚到顶部重渲染 → 把结果转文本并做快照。

调用关系：它验证 PagerView::render_content 的清屏和空白填充行为，尤其是复杂消息场景。

调用图：外部调用 15 个（new, empty, from_millis, new, from, new, new, assert_snapshot!, new_active_exec_command, new_patch_event (+5 more)）。

fn transcript_overlay_keeps_scroll_pinned_at_bottom()

作用：确认用户原本在底部时，新消息加入后仍然跟到底部。这是聊天记录常见的“跟随最新消息”行为。

数据流：进去没有参数 → 它创建很多行，渲染后确认在底部，插入新消息 → 断言滚动位置被设成底部标记。

调用关系：它测试 TranscriptOverlay::insert_cell 对 PagerView::is_scrolled_to_bottom 的使用。

调用图：外部调用 7 个（new, new, assert!, assert_eq!, new, transcript_overlay, vec!）。

fn transcript_overlay_preserves_manual_scroll_position()

作用：确认用户手动滚到上面看旧内容时，新消息不会把他强行拉到底部。

数据流：进去没有参数 → 它创建长记录并渲染，再手动把 scroll_offset 设为顶部，插入新消息 → 断言位置仍在顶部。

调用关系：它和前一个测试成对验证 insert_cell 的滚动保护逻辑。

调用图：外部调用 6 个（new, new, assert_eq!, new, transcript_overlay, vec!）。

fn transcript_overlay_consolidation_remaps_highlight_inside_range()

作用：确认被合并范围内的高亮消息会指向合并后的新消息。否则编辑焦点可能丢失或指错。

数据流：进去没有参数 → 它创建多条消息，高亮第 3 条，合并 2 到 5 的范围 → 断言高亮变为合并后的位置。

调用关系：它测试 TranscriptOverlay::consolidate_cells 对范围内高亮的修正。

调用图：外部调用 4 个（new, assert_eq!, transcript_overlay, vec!）。

fn transcript_overlay_consolidation_remaps_highlight_after_range()

作用：确认合并范围后面的高亮会向前平移。因为几条消息合成一条后，后面的序号会变小。

数据流：进去没有参数 → 它创建多条消息，高亮合并范围之后的消息，执行合并 → 断言高亮序号按删除数量修正。

调用关系：它测试 TranscriptOverlay::consolidate_cells 对范围后高亮的修正。

调用图：外部调用 4 个（new, assert_eq!, transcript_overlay, vec!）。

fn static_overlay_snapshot_basic()

作用：用快照检查静态覆盖层的基础画面。它防止标题、正文、提示栏的布局被意外改坏。

数据流：进去没有参数 → 它创建三行文本的静态页，渲染到测试终端 → 和快照比对。

调用关系：它验证 StaticOverlay::render 和 PagerView::render 的整体效果。

调用图：外部调用 5 个（new, assert_snapshot!, new, static_overlay, vec!）。

fn transcript_line_numbers(overlay: &mut TranscriptOverlay, area: Rect) -> Vec<usize>

作用：测试辅助函数，渲染 transcript 后提取当前可见的 line-NN 编号。它让分页测试能精确判断看到的是哪几行。

数据流：进去的是 overlay 和区域 → 它渲染到缓冲区，切出正文区域，扫描每行里的 line-数字 → 出来的是可见编号列表。

调用关系：transcript_overlay_paging_is_continuous_and_round_trips 用它检查翻页连续性。

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

fn transcript_overlay_paging_is_continuous_and_round_trips()

作用：确认 PageDown 和 PageUp 翻页连续，并且来回翻能回到原位置。这样用户不会漏看或重复太多内容。

数据流：进去没有参数 → 它创建 50 行记录，先渲染初始化布局，再模拟不同位置的翻页 → 用可见行号断言页面连续和往返一致。

调用关系：它重点验证 PagerView::page_height、render 和滚动偏移计算。

调用图：外部调用 5 个（empty, new, assert_eq!, transcript_line_numbers, transcript_overlay）。

fn static_overlay_wraps_long_lines()

作用：确认静态页中的长行会在窄窗口里自动换行。否则内容会被截断看不全。

数据流：进去没有参数 → 它创建一条很长的静态文本，渲染到窄测试终端 → 用快照确认换行效果。

调用关系：它验证 StaticOverlay::with_title 创建的 Paragraph 换行设置。

调用图：外部调用 5 个（new, assert_snapshot!, new, static_overlay, vec!）。

fn pager_view_content_height_counts_renderables()

作用：确认 PagerView 会把多个内容块的高度正确相加。总高度算错会导致滚动范围错。

数据流：进去没有参数 → 它创建两个段落块，调用 content_height → 断言总高度等于两块行数之和。

调用关系：它直接测试 PagerView::content_height。

调用图：外部调用 3 个（assert_eq!, pager_view, vec!）。

fn pager_view_ensure_chunk_visible_scrolls_down_when_needed()

作用：确认目标内容块在下面看不见时，PagerView 会向下滚到它。用于高亮消息自动定位。

数据流：进去没有参数 → 它创建三块内容，把目标设为第三块，调用 ensure_chunk_visible 后渲染 → 检查第三块几行都出现在画面中。

调用关系：它测试 PagerView::ensure_chunk_visible 的向下滚动行为。

调用图：外部调用 6 个（empty, new, assert!, buffer_to_text, pager_view, vec!）。

fn pager_view_ensure_chunk_visible_scrolls_up_when_needed()

作用：确认目标内容块在上面看不见时，PagerView 会向上滚。这样自动定位不只会往下走。

数据流：进去没有参数 → 它创建内容块，把滚动位置放到较下面，再要求显示第一块 → 断言 scroll_offset 回到 0。

调用关系：它测试 PagerView::ensure_chunk_visible 的向上滚动行为。

调用图：外部调用 4 个（new, assert_eq!, pager_view, vec!）。

fn pager_view_is_scrolled_to_bottom_accounts_for_wrapped_height()

作用：确认“是否到底部”的判断会考虑换行后的真实高度。宽度变窄导致行数变多时尤其重要。

数据流：进去没有参数 → 它创建高内容块并渲染，先断言顶部不是底部，再把滚动设到底部并重渲染 → 断言此时是底部。

调用关系：它验证 PagerView::is_scrolled_to_bottom 和 render 记录高度的配合。

调用图：外部调用 5 个（empty, new, assert!, pager_view, vec!）。

fn open_keymap_picker(&mut self)

作用：打开 /keymap 的主菜单，让用户看到当前有哪些动作可以改快捷键。它会先检查现有快捷键配置是否有效，避免用一份坏配置生成菜单。

数据流：进去的是当前聊天窗口对象，它里面带着保存下来的 tui_keymap 配置。函数先把这份配置交给 RuntimeKeymap::from_config，尝试变成程序实际能用的快捷键表；成功后，再结合 keymap_action_filter 给出的筛选条件，生成主菜单参数，并显示到底部面板。失败时，它不会显示菜单，而是在聊天界面里加一条错误消息，告诉用户配置无效。

调用关系：这是用户进入快捷键设置流程的起点之一。它自己不制作菜单内容，而是把配置验证交给 from_config，把菜单参数生成交给 build_keymap_picker_params_with_filter；它还会调用 ChatWidget::keymap_action_filter，决定哪些动作应该出现在菜单里。

调用图：调用 2 个内部函数（keymap_action_filter, from_config）；外部调用 2 个（format!, build_keymap_picker_params_with_filter）。

fn open_keymap_action_menu(
        &mut self,
        context: String,
        action: String,
        runtime_keymap: &RuntimeKeymap,
    )

作用：打开某一个具体动作的快捷键菜单。比如用户选中了“复制上一条回复”，这里就展示这个动作当前有哪些按键、可以怎么改。

数据流：进去的是动作所属的场景 context、动作名 action，以及已经算好的运行时快捷键表 runtime_keymap。函数把这些信息连同当前保存的配置一起交给 build_keymap_action_menu_params，得到一个可显示的菜单说明，然后让底部面板显示出来。它本身不重新计算快捷键表，避免用户刚点选后配置又变化，导致显示内容前后不一致。

调用关系：它通常接在主快捷键菜单之后：用户先选中一个动作，然后事件处理代码调用它。它把具体菜单的构建交给 build_keymap_action_menu_params，自己只负责把生成好的菜单放到底部面板里。

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

fn open_keymap_capture(
        &mut self,
        context: String,
        action: String,
        intent: KeymapEditIntent,
        runtime_keymap: &RuntimeKeymap,
    )

作用：打开“请按下新的快捷键”的捕获界面，用来设置、替换或添加一个按键绑定。简单说，就是让程序进入等待用户按键的状态。

数据流：进去的是场景、动作名、编辑意图 KeymapEditIntent，以及当前运行时快捷键表。函数把这些信息和聊天窗口的事件发送器一起交给 build_keymap_capture_view，生成一个捕获按键的视图；然后把这个视图装进底部面板，并请求界面重画。之后用户按下的键会通过事件通道回到正常的应用事件流程里。

调用关系：它通常由某个动作菜单触发，比如用户选择“设置新快捷键”之后。它把真正识别按键的工作交给 build_keymap_capture_view 创建的视图；这里特别保留通过应用事件通道返回结果，是为了后续能走统一的保存配置和刷新快捷键流程。

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

fn open_keymap_debug(&mut self, runtime_keymap: &RuntimeKeymap)

作用：打开快捷键调试查看器，让用户或开发者查看当前按键会被解释成什么。它适合排查“我按了这个键，为什么没反应或反应不对”。

数据流：进去的是当前运行时快捷键表。函数把它和保存的配置交给 build_keymap_debug_view，生成一个调试视图；再把视图放到底部面板里，并请求界面重画。它不会修改配置，只是展示当前状态。

调用关系：这是快捷键设置流程里的辅助入口。它依赖 build_keymap_debug_view 来生成具体查看界面，自己负责把这个界面接入 ChatWidget 的底部面板显示系统。

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

fn open_keymap_replace_binding_menu(
        &mut self,
        context: String,
        action: String,
        runtime_keymap: &RuntimeKeymap,
    )

作用：当一个动作有多个快捷键时，打开一个菜单让用户选择要替换哪一个。这样可以避免用户只想换其中一个键，却不小心把其他备用快捷键也弄没了。

数据流：进去的是场景、动作名和当前运行时快捷键表。函数把这些交给 build_keymap_replace_binding_menu_params，生成“可替换绑定列表”的菜单参数，然后让底部面板显示这个选择菜单。它本身不执行替换，只是让用户先选中要换掉的那一项。

调用关系：它通常出现在编辑某个动作快捷键的中间步骤。用户先从动作菜单选择替换，进入这里选旧绑定；选完之后，后续流程会再进入按键捕获界面。菜单内容由 build_keymap_replace_binding_menu_params 生成。

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

fn return_to_keymap_picker(
        &mut self,
        context: &str,
        action: &str,
        runtime_keymap: &RuntimeKeymap,
    )

作用：一次快捷键编辑完成后，回到主快捷键菜单，并且把刚才编辑的那个动作高亮选中。这样用户能清楚看到自己刚改的是哪一项，也方便继续改。

数据流：进去的是刚编辑过的场景、动作名和当前运行时快捷键表。函数先用这些信息、当前配置和 keymap_action_filter 生成一个“主菜单并选中指定动作”的菜单参数。然后它尝试把当前底部面板里旧的快捷键相关页面直接替换成这个新主菜单；如果发现当前页面栈已经不是预期的快捷键页面，就退一步显示一个全新的主菜单。最后请求界面重画。

调用关系：它通常在保存或应用一次快捷键修改之后被调用。它会调用 ChatWidget::keymap_action_filter 来保持菜单筛选规则一致，并把菜单参数生成交给 build_keymap_picker_params_for_selected_action_with_filter。它还负责避免底部面板里堆积过时的子菜单。

调用图：调用 1 个内部函数（keymap_action_filter）；外部调用 1 个（build_keymap_picker_params_for_selected_action_with_filter）。

fn keymap_action_filter(&self) -> keymap_setup::KeymapActionFilter

作用：生成快捷键菜单的筛选条件，决定哪些动作应该显示。当前主要看一个因素：快速模式是否开启。

数据流：进去的是聊天窗口当前状态。函数读取 fast_mode_enabled() 的结果，把它包装成 KeymapActionFilter 返回。它不改动界面，也不改配置，只产出一个给菜单构建器使用的小条件对象。

调用关系：它是主菜单构建时的辅助函数，被 ChatWidget::open_keymap_picker 和 ChatWidget::return_to_keymap_picker 调用。这样打开菜单和编辑后返回菜单时，使用的是同一套筛选规则，不会前后显示不一致。

调用图：被 2 处调用（open_keymap_picker, return_to_keymap_picker）。

fn apply_keymap_update(
        &mut self,
        keymap_config: TuiKeymap,
        runtime_keymap: &RuntimeKeymap,
    )

作用：把一次已经确认并保存的快捷键修改，真正应用到正在运行的聊天界面里。它的重点是“一起更新”，避免配置、快捷键响应和界面提示互相打架。

数据流：进去的是新的 TuiKeymap 配置和对应的运行时快捷键表。函数先替换聊天窗口内存里的配置；再更新应用级的“复制上一条回复”快捷键缓存、聊天区快捷键表；接着根据终端信息重新计算“编辑排队消息”的提示按键，并同步给底部面板；然后把整套运行时快捷键绑定也交给底部面板。最后请求界面重画。出来的结果不是返回值，而是整个正在运行的界面状态被同步到了新快捷键。

调用关系：它通常在外层代码已经把配置写入文件之后调用。它会用 terminal_info 获取当前终端能力，用 queued_message_edit_hint_binding 算出合适的提示按键。它是快捷键编辑流程的收尾步骤，确保用户改完后不用重启，界面和按键处理马上按新规则工作。

调用图：外部调用 2 个（terminal_info, queued_message_edit_hint_binding）。

fn key_binding_span(binding: &str) -> ratatui::text::Span<'static>

作用：把一个快捷键文字变成界面上带颜色的片段。没有绑定时用暗色，普通快捷键用青色，方便用户一眼分辨。

数据流：输入一个快捷键字符串 → 判断它是不是 unbound → 输出一个可渲染的文字片段，不改动任何配置。

调用关系：它是界面显示的小工具，主要被菜单头部用来把当前快捷键显示得更清楚。

fn keymap_action_menu_hint_line() -> Line<'static>

作用：生成快捷键操作菜单底部的提示文字，告诉用户 Enter 是选择，Esc 是返回。

数据流：没有业务输入 → 拼出一行带颜色的提示 → 返回给菜单参数使用。

调用关系：build_keymap_action_menu_params 和 build_keymap_replace_binding_menu_params 在建菜单时会调用它，让两个菜单有一致的操作提示。

调用图：被 2 处调用（build_keymap_action_menu_params, build_keymap_replace_binding_menu_params）；外部调用 2 个（from, vec!）。

fn open_capture_action(
    context: String,
    action: String,
    intent: KeymapEditIntent,
) -> Box<dyn Fn(&AppEventSender) + Send + Sync>

作用：做一个“之后打开按键捕获窗口”的动作。用户选中某个菜单项时，这个动作会发事件给应用。

数据流：输入上下文、动作名和编辑意图 → 包成一个闭包 → 闭包执行时发送 OpenKeymapCapture 事件。

调用关系：它不直接打开界面，而是把请求交给应用事件系统；action_menu_item 会用它给菜单项挂上后续动作。

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

fn action_menu_item(
    name: &str,
    description: &str,
    selected_description: String,
    context: &str,
    action: &str,
    intent: KeymapEditIntent,
) -> SelectionItem

作用：快速创建一个会进入按键捕获流程的菜单项，比如“替换绑定”或“添加备用绑定”。

数据流：输入菜单名、说明、选中说明、目标动作和编辑意图 → 组装 SelectionItem → 返回给菜单列表。

调用关系：build_keymap_action_menu_params 用它减少重复代码；它内部把真正的跳转交给 open_capture_action。

调用图：被 1 处调用（build_keymap_action_menu_params）；外部调用 2 个（default, vec!）。

fn build_keymap_action_menu_params(
    context: String,
    action: String,
    runtime_keymap: &RuntimeKeymap,
    keymap_config: &TuiKeymap,
) -> SelectionViewParams

作用：为某个具体功能生成“要怎么改这个快捷键”的菜单。它会根据当前有没有快捷键、有没有自定义配置，决定哪些选项能点。

数据流：输入动作所在 context、action、当前运行时快捷键表和根配置 → 查当前生效按键、是否有自定义项、动作说明 → 输出一个可显示的选择菜单参数。

调用关系：用户在快捷键列表点中一个动作后，open_keymap_action_menu 会用它打开二级菜单；菜单项再继续发出捕获、替换单个绑定或清除绑定的事件。测试也用它检查不同绑定数量下菜单是否正确。

调用图：调用 6 个内部函数（action_menu_item, action_label, active_binding_specs, has_custom_binding, keymap_action_menu_hint_line, new）；被 6 处调用（open_keymap_action_menu, action_menu_content_snapshot, action_menu_disables_clear_when_action_has_no_custom_binding, capture_completion_returns_to_selected_keymap_picker_row, clear_completion_returns_to_selected_keymap_picker_row, replace_one_completion_drops_focused_keymap_submenus）；外部调用 6 个（new, default, from, new, format!, vec!）。

fn build_keymap_replace_binding_menu_params(
    context: String,
    action: String,
    runtime_keymap: &RuntimeKeymap,
) -> SelectionViewParams

作用：当一个动作有多个快捷键时，生成“你想替换哪一个”的菜单。这样不会粗暴地把所有绑定都覆盖掉。

数据流：输入目标动作和运行时快捷键表 → 找到所有当前生效绑定 → 每个绑定生成一行菜单项 → 输出选择菜单参数。

调用关系：build_keymap_action_menu_params 里“Replace one binding...”会引到这个菜单；用户选中某一行后再发 OpenKeymapCapture，并带上要替换的旧按键。

调用图：调用 4 个内部函数（action_label, active_binding_specs, keymap_action_menu_hint_line, new）；被 3 处调用（open_keymap_replace_binding_menu, action_menu_content_snapshot, replace_one_completion_drops_focused_keymap_submenus）；外部调用 4 个（new, default, from, vec!）。

fn build_keymap_conflict_params(
    context: String,
    action: String,
    key: String,
    intent: KeymapEditIntent,
    error: String,
) -> SelectionViewParams

作用：生成快捷键冲突时的提示弹窗。它告诉用户这个键不能用，并给出“重新选一个键”或“取消”。

数据流：输入目标动作、新键、编辑意图和错误文字 → 包装成弹窗菜单 → 输出 SelectionViewParams。

调用关系：apply_keymap_capture 在发现新按键不合法或冲突后会调用它；如果用户选择重试，它再发 OpenKeymapCapture 回到捕获流程。

调用图：调用 1 个内部函数（standard_popup_hint_line）；被 1 处调用（apply_keymap_capture）；外部调用 4 个（default, from, format!, vec!）。

fn build_keymap_capture_view(
    context: String,
    action: String,
    intent: KeymapEditIntent,
    runtime_keymap: &RuntimeKeymap,
    app_event_tx: AppEventSender,
) -> KeymapCaptureView

作用：创建一个临时的按键捕获界面，让用户按下一个新快捷键。

数据流：输入目标动作、编辑意图、当前运行时快捷键表和事件发送器 → 读取当前绑定并整理成显示文字 → 返回 KeymapCaptureView。

调用关系：open_keymap_capture 会调用它；它把显示和收键交给 KeymapCaptureView，真正保存仍由捕获后的应用事件处理。

调用图：调用 4 个内部函数（new, action_label, bindings_for_action, format_binding_summary）；被 2 处调用（open_keymap_capture, capture_completion_returns_to_selected_keymap_picker_row）。

fn keymap_with_replacement(
    keymap: &TuiKeymap,
    context: &str,
    action: &str,
    key: &str,
) -> Result<TuiKeymap, String>

作用：测试用的简化函数，把某个动作的快捷键直接替换成一个键。

数据流：输入原配置、动作位置和新键 → 调用 keymap_with_bindings 写成单个绑定 → 返回新配置或错误。

调用关系：它主要被测试用来快速准备“已经自定义过快捷键”的场景，底层实际改配置的活交给 keymap_with_bindings。

调用图：调用 1 个内部函数（keymap_with_bindings）；被 9 处调用（action_menu_content_snapshot, capture_completion_returns_to_selected_keymap_picker_row, clear_completion_returns_to_selected_keymap_picker_row, clear_removes_custom_binding, debug_view_uses_custom_binding_source, picker_custom_render_snapshot, picker_customized_tab_contains_root_overrides, replacement_rejects_unknown_action, replacement_sets_single_binding）。

fn keymap_with_edit(
    keymap: &TuiKeymap,
    runtime_keymap: &RuntimeKeymap,
    context: &str,
    action: &str,
    key: &str,
    intent: &KeymapEditIntent,
) -> Result<KeymapEditOutcome, Strin

作用：把用户刚捕获到的按键应用到配置里。它支持替换全部、添加备用键、只替换其中一个，并会避免重复或过期选择。

数据流：输入旧配置、当前运行时快捷键表、目标动作、新键和编辑意图 → 先取当前真实生效绑定 → 算出下一组绑定 → 如无变化返回 Unchanged，如有变化返回带新配置和提示文字的 Updated。

调用关系：apply_keymap_capture 在收到 KeymapCaptured 后会调用它；它依赖 active_binding_specs 读取现状，必要时用 dedup_bindings 去重，最后交给 keymap_with_bindings 写入配置。

调用图：调用 3 个内部函数（active_binding_specs, dedup_bindings, keymap_with_bindings）；被 8 处调用（apply_keymap_capture, add_alternate_duplicate_is_noop, add_alternate_grows_default_multi_binding, add_alternate_grows_single_binding, replace_all_collapses_multi_binding_to_single, replace_one_deduplicates_replacement, replace_one_preserves_other_bindings, replace_one_rejects_stale_old_key）；外部调用 3 个（new, format!, vec!）。

fn keymap_with_bindings(
    keymap: &TuiKeymap,
    context: &str,
    action: &str,
    keys: &[String],
) -> Result<TuiKeymap, String>

作用：把某个动作的快捷键列表写进一份新的根配置里。它是实际落到 tui.keymap 槽位的底层函数。

数据流：输入旧配置、动作位置和键列表 → 克隆配置 → 找到对应配置槽位 → 写成单个绑定或多个绑定 → 返回新配置。

调用关系：keymap_with_edit 和测试辅助 keymap_with_replacement 都靠它真正改配置；如果动作名不存在，它返回明确错误，提醒用户重新打开 /keymap。

调用图：调用 1 个内部函数（binding_slot）；被 6 处调用（keymap_with_edit, keymap_with_replacement, action_menu_content_snapshot, replace_all_collapses_multi_binding_to_single, replace_one_deduplicates_replacement, replace_one_preserves_other_bindings）；外部调用 4 个（new, Many, One, clone）。

fn active_binding_specs(
    runtime_keymap: &RuntimeKeymap,
    context: &str,
    action: &str,
) -> Result<Vec<String>, String>

作用：把运行时已经解析好的快捷键，转回配置文件里使用的字符串形式。这样显示和再次写入时用的是同一套写法。

数据流：输入运行时快捷键表和动作位置 → 找到该动作当前绑定 → 每个绑定转成配置字符串 → 返回字符串列表或未知动作错误。

调用关系：菜单构建和 keymap_with_edit 都用它获取“现在真正生效的键”；它把查找交给 bindings_for_action，把格式转换交给 binding_to_config_key_spec。

调用图：调用 1 个内部函数（bindings_for_action）；被 3 处调用（build_keymap_action_menu_params, build_keymap_replace_binding_menu_params, keymap_with_edit）。

fn dedup_bindings(bindings: Vec<String>) -> Vec<String>

作用：去掉快捷键列表里的重复项，同时保留第一次出现的顺序。

数据流：输入一个字符串列表 → 从前到后检查，没见过才放进新列表 → 返回去重后的列表。

调用关系：keymap_with_edit 在“替换其中一个绑定”后调用它，避免把两个绑定变成同一个键后留下重复配置。

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

fn keymap_without_custom_binding(
    keymap: &TuiKeymap,
    context: &str,
    action: &str,
) -> Result<TuiKeymap, String>

作用：删除某个动作在根配置里的自定义快捷键，让它重新使用默认或全局兜底规则。

数据流：输入旧配置和动作位置 → 克隆配置 → 找到对应槽位 → 把槽位设为 None → 返回新配置。

调用关系：apply_keymap_clear 会在用户选择“Remove custom binding”后调用它；它和设置空列表不同，None 的意思是恢复默认，不是强制解绑。

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

fn has_custom_binding(keymap: &TuiKeymap, context: &str, action: &str) -> Result<bool, String>

作用：检查某个动作在根配置里有没有用户自定义快捷键。

数据流：输入配置和动作位置 → 克隆配置并找到对应槽位 → 返回槽位是否有值。

调用关系：build_keymap_action_menu_params 用它决定“Remove custom binding”能不能点，以及菜单里显示来源是自定义还是默认。

调用图：调用 1 个内部函数（binding_slot）；被 1 处调用（build_keymap_action_menu_params）；外部调用 1 个（clone）。

fn new(
        context: String,
        action: String,
        intent: KeymapEditIntent,
        label: String,
        current_binding: String,
        app_event_tx: AppEventSender,
    ) -> Self

作用：创建按键捕获视图的初始状态。它保存目标动作、当前绑定、事件发送器和是否完成等信息。

数据流：输入动作位置、编辑意图、显示标签、当前绑定文字和事件发送器 → 填入结构体字段 → 返回一个尚未完成、没有错误的捕获视图。

调用关系：build_keymap_capture_view 用它正式创建视图；测试也直接调用它来检查渲染效果。

调用图：被 2 处调用（build_keymap_capture_view, capture_view_snapshot）。

fn lines(&self, width: u16) -> Vec<Line<'static>>

作用：生成捕获视图要显示的多行文字，包括标题、目标动作、当前快捷键、操作说明和错误信息。

数据流：输入可用宽度 → 按宽度准备普通说明；如果有错误，就把错误文字换行并标红 → 返回多行可渲染文本。

调用关系：render 和 desired_height 都调用它，确保实际显示内容和所需高度来自同一份计算。

调用图：被 2 处调用（desired_height, render）；外部调用 5 个（from, new, wrap, from, vec!）。

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

作用：把按键捕获视图画到终端缓冲区里。

数据流：输入绘制区域和缓冲区 → 调用 lines 得到文字 → 用段落组件写入缓冲区。

调用关系：底部面板在需要显示这个临时视图时会调用它；测试里的 render_capture 也用它生成快照。

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

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

作用：告诉底部面板这个捕获视图需要多高。

数据流：输入可用宽度 → 调用 lines 计算会有多少行 → 返回行数作为高度。

调用关系：渲染布局前会用它估算空间；它和 render 共用 lines，避免高度和内容对不上。

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

fn handle_key_event(&mut self, key_event: KeyEvent)

作用：处理用户在捕获视图里按下的键。Esc 取消，其他支持的键会被转换成配置字符串并发送出去。

数据流：输入一个终端按键事件 → 忽略按键释放事件；Esc 标记完成；其他键尝试转成配置写法 → 成功就发送 KeymapCaptured 并完成，失败就保存错误信息供界面显示。

调用关系：底部面板把按键事件交给它；它不直接改配置，而是通过 AppEventSender 把结果交给应用层继续处理。

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

fn is_complete(&self) -> bool

作用：告诉底部面板这个临时捕获视图是否该关闭。

数据流：读取 complete 字段 → 返回 true 或 false → 不改动状态。

调用关系：底部面板在处理完事件后会检查它；handle_key_event 和 on_ctrl_c 会把 complete 设为 true。

fn on_ctrl_c(&mut self) -> CancellationEvent

作用：处理 Ctrl+C 取消捕获。它把视图标记为完成，并说明这个取消已经被处理了。

数据流：没有额外输入 → 设置 complete 为 true → 返回 Handled。

调用关系：底部面板收到 Ctrl+C 时调用它；这样不会继续把 Ctrl+C 当作要绑定的新快捷键。

fn prefer_esc_to_handle_key_event(&self) -> bool

作用：声明 Esc 应该先交给这个视图处理。因为在这里 Esc 的含义是取消捕获。

数据流：没有输入 → 固定返回 true → 不改状态。

调用关系：底部面板用它决定 Esc 的分发顺序，保证捕获视图能自己关闭。

fn key_event_to_config_key_spec(key_event: KeyEvent) -> Result<String, String>

作用：把终端按键事件转换成配置文件里能写的快捷键字符串。

数据流：输入 KeyEvent → 先转成项目内部的 KeyBinding → 再转成配置字符串或错误。

调用关系：KeymapCaptureView::handle_key_event 用它处理用户按下的新键；真正的格式细节继续交给 binding_to_config_key_spec。

调用图：调用 2 个内部函数（from_event, binding_to_config_key_spec）；被 1 处调用（handle_key_event）。

fn binding_to_config_key_spec(binding: KeyBinding) -> Result<String, String>

作用：把内部快捷键对象转成配置字符串。

数据流：输入 KeyBinding → 拆出按键本体和修饰键，比如 Ctrl、Alt、Shift → 调用 key_parts_to_config_key_spec 得到字符串。

调用关系：active_binding_specs 和 key_event_to_config_key_spec 都会走到它，保证显示已有绑定和保存新绑定使用同一套规则。

调用图：调用 2 个内部函数（parts, key_parts_to_config_key_spec）；被 1 处调用（key_event_to_config_key_spec）。

fn key_parts_to_config_key_spec(
    code: KeyCode,
    mut modifiers: KeyModifiers,
) -> Result<String, String>

作用：把具体按键和修饰键规范化成 ctrl-alt-x 这类配置写法，并拒绝不支持的键。

数据流：输入按键代码和修饰键 → 先规范化大小写和控制字符 → 检查只允许 Ctrl、Alt、Shift → 识别特殊键、功能键、空格、减号和可打印 ASCII 字符 → 返回标准字符串或错误原因。

调用关系：binding_to_config_key_spec 把所有转换请求交给它；它最后用 format_key_spec 统一拼接顺序。

调用图：调用 2 个内部函数（normalize_key_parts, format_key_spec）；被 1 处调用（binding_to_config_key_spec）；外部调用 3 个（difference, insert, format!）。

fn format_key_spec(modifiers: KeyModifiers, key: &str) -> String

作用：按固定顺序拼出快捷键字符串，比如先 ctrl、再 alt、再 shift，最后是键名。

数据流：输入修饰键集合和键名 → 依次检查是否包含 Ctrl、Alt、Shift → 拼成用短横线连接的字符串。

调用关系：key_parts_to_config_key_spec 在识别出键名后调用它，确保配置里的快捷键写法稳定一致。

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

fn app_event_sender() -> AppEventSender

作用：测试里创建一个假的应用事件发送器。

数据流：创建一个无界消息通道 → 用发送端包装成 AppEventSender → 返回给测试使用。

调用关系：多个渲染和面板测试用它提供必要依赖，但通常不关心真实接收方。

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

fn render_capture(view: &KeymapCaptureView, width: u16, height: u16) -> Buffer

作用：测试里把捕获视图画成缓冲区，方便做快照比对。

数据流：输入视图、宽度和高度 → 创建空缓冲区 → 调用视图 render → 返回填好内容的缓冲区。

调用关系：capture_view_snapshot 用它确认捕获窗口长什么样。

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

fn render_debug(view: &KeymapDebugView, width: u16) -> String

作用：测试里把调试视图渲染成普通字符串。

数据流：输入调试视图和宽度 → 先问需要多高 → 渲染到缓冲区 → 用 render_buffer 转成文本。

调用关系：多个 debug_view 测试用它检查按键诊断界面的显示。

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

fn render_picker(params: SelectionViewParams, width: u16) -> String

作用：测试里根据选择菜单参数渲染快捷键列表。

数据流：输入 SelectionViewParams 和宽度 → 创建 ListSelectionView → 调用 render_picker_from_view → 返回文本画面。

调用关系：快捷键选择器的快照测试用它验证宽屏、窄屏和自定义配置下的显示。

调用图：调用 2 个内部函数（new, defaults）；外部调用 2 个（app_event_sender, render_picker_from_view）。

fn render_picker_from_view(view: &ListSelectionView, width: u16) -> String

作用：测试里把已经创建好的选择列表视图渲染成字符串。

数据流：输入列表视图和宽度 → 计算高度 → 渲染到缓冲区 → 转成文本。

调用关系：tests::render_picker 把实际渲染工作交给它，也可用于已有视图的检查。

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

fn fast_mode_action_filter() -> KeymapActionFilter

作用：测试里生成一个开启 Fast Mode 的动作过滤器。

数据流：没有输入 → 构造 fast_mode_enabled 为 true 的 KeymapActionFilter → 返回它。

调用关系：涉及 Fast Mode 是否出现在快捷键列表的测试会用它。

fn render_buffer(buf: &Buffer) -> String

作用：把 ratatui 的屏幕缓冲区转成可比较的普通文本。

数据流：输入缓冲区 → 按行按列读取每个格子的字符 → 去掉每行末尾空白 → 返回多行字符串。

调用关系：render_debug 和 render_picker_from_view 用它把终端画面变成快照测试能比对的内容。

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

fn test_pane() -> (BottomPane, AppEventSender, UnboundedReceiver<AppEvent>)

作用：测试里创建一个可用的底部面板、事件发送器和事件接收器。

数据流：创建消息通道和 AppEventSender → 用测试参数构造 BottomPane → 返回面板、发送器和接收器。

调用关系：捕获完成、清除完成和替换子菜单关闭等流程测试用它模拟真实底部面板。

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

fn selection_tab(params: &'a SelectionViewParams, id: &str) -> &'a SelectionTab

作用：从菜单参数里按 id 找到某个标签页，找不到就让测试失败。

数据流：输入菜单参数和标签页 id → 遍历 tabs → 返回匹配标签页引用。

调用关系：大量选择器测试用它读取 All、Common、Custom 等标签页。

fn selection_item(params: &'a SelectionViewParams, name: &str) -> &'a SelectionItem

作用：从菜单参数里按名字找到某个菜单项，找不到就让测试失败。

数据流：输入菜单参数和菜单项名字 → 遍历 items → 返回匹配项引用。

调用关系：动作菜单测试用它检查某些按钮是否可用、是否会关闭菜单。

fn action_menu_rows(params: &SelectionViewParams) -> String

作用：把动作菜单的每一行整理成简短文本，方便做快照。

数据流：输入菜单参数 → 读取每个菜单项的名字、说明和禁用原因 → 拼成多行字符串。

调用关系：action_menu_content_snapshot 用它比较未绑定、单绑定、多绑定等情况下的菜单差异。

fn picker_covers_every_replaceable_action()

作用：确认快捷键选择器覆盖了所有可替换动作，并且每个动作都有配置槽位和运行时绑定入口。

数据流：创建默认运行时表和开启 Fast Mode 的选择器参数 → 检查 All 标签页数量、菜单行为、配置槽位和运行时动作 → 测试通过或失败。

调用关系：它保护动作清单、配置结构和运行时快捷键表三者保持同步。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params_with_filter）；外部调用 5 个（assert!, assert_eq!, default, fast_mode_action_filter, selection_tab）。

fn picker_hides_fast_mode_action_when_feature_is_disabled()

作用：确认 Fast Mode 功能没开启时，快捷键列表里不会出现 Toggle Fast Mode。

数据流：用默认过滤条件生成选择器 → 查看 All 标签页 → 断言没有对应菜单项。

调用关系：它验证 picker 的功能开关逻辑，防止用户看到不能用的快捷键入口。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params）；外部调用 3 个（assert!, default, selection_tab）。

fn picker_shows_fast_mode_action_when_feature_is_enabled()

作用：确认 Fast Mode 开启时，相关动作会出现在多个合适的标签页里。

数据流：用 fast_mode_action_filter 生成选择器 → 读取 All、Common、App、Unbound 标签页 → 断言都有 Toggle Fast Mode。

调用关系：它和隐藏测试成对出现，保证过滤器开关两边都正确。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params_with_filter）；外部调用 4 个（assert!, default, fast_mode_action_filter, selection_tab）。

fn keymap_picker_fast_mode_enabled_snapshot()

作用：保存 Fast Mode 开启时快捷键选择器的整体画面快照。

数据流：生成开启 Fast Mode 的选择器参数 → 渲染宽屏画面 → 和快照比对。

调用关系：它用于发现界面文案、排序或布局的意外变化。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params_with_filter）；外部调用 3 个（assert_snapshot!, default, fast_mode_action_filter）。

fn picker_common_tab_lists_curated_actions()

作用：确认 Common 标签页列出的是人工挑选的常用动作，而且顺序正确。

数据流：生成默认选择器 → 取 Common 标签页 → 提取每项的 context.action → 和预期列表比较。

调用关系：它保护常用快捷键列表的内容，不让改动无意中影响新手最常看的页面。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params）；外部调用 3 个（assert_eq!, default, selection_tab）。

fn picker_approval_tab_lists_all_approval_actions()

作用：确认 Approval 标签页包含所有审批相关动作。

数据流：生成默认选择器 → 取 approval-shortcuts 标签页 → 提取动作名 → 和预期审批动作列表比较。

调用关系：它保证审批界面的快捷键不会在 /keymap 里漏掉。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params）；外部调用 3 个（assert_eq!, default, selection_tab）。

fn picker_content_snapshot()

作用：记录快捷键选择器的标签页数量和前几项内容，作为轻量快照。

数据流：生成默认选择器 → 统计每个标签页可选项 → 取 All 标签页前几项 → 和快照比对。

调用关系：它帮助发现排序、文案和标签页结构的变化。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params）；外部调用 3 个（assert_snapshot!, default, selection_tab）。

fn picker_customized_tab_contains_root_overrides()

作用：确认用户自定义过的根配置会出现在 Custom 标签页，并在对应分类里显示自定义键。

数据流：先把 submit 改成 ctrl-enter → 生成运行时表和选择器 → 检查 Custom 与 Composer 标签页内容。

调用关系：它验证 keymap_with_replacement、RuntimeKeymap::from_config 和 picker 展示自定义来源的配合。

调用图：调用 3 个内部函数（from_config, keymap_with_replacement, build_keymap_picker_params）；外部调用 4 个（assert!, assert_eq!, default, selection_tab）。

fn picker_unbound_tab_lists_default_unbound_actions()

作用：确认默认没有绑定的动作会出现在 Unbound 标签页。

数据流：生成默认选择器 → 读取 Unbound 标签页 → 检查数量、名字、显示为 unbound 且可选择。

调用关系：它保证未绑定动作不会被隐藏，用户仍然可以给它们设置快捷键。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params）；外部调用 4 个（assert!, assert_eq!, default, selection_tab）。

fn picker_debug_tab_is_last_and_opens_inspector()

作用：确认 Debug 标签页在最后，并提供按键检查器入口。

数据流：生成默认选择器 → 查看最后一个标签页 → 检查 id、标题、说明和底部提示。

调用关系：它保护 /keymap 里的诊断入口，方便用户排查终端到底发来了什么键。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params）；外部调用 3 个（assert!, assert_eq!, default）。

fn picker_selected_action_starts_on_matching_all_tab_row()

作用：确认刷新选择器后会自动选中刚编辑过的动作。

数据流：为 composer.submit 生成带初始选择的参数 → 查看初始标签页和选中下标 → 和 All 标签页里的 Submit 行比较。

调用关系：编辑成功后返回列表会用同类参数；这个测试保证用户不会迷路。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params_for_selected_action）；外部调用 3 个（assert_eq!, default, selection_tab）。

fn picker_all_tab_items_remain_searchable()

作用：确认 All 标签页的菜单项仍带有搜索用文字。

数据流：生成默认选择器 → 取 All 标签页前几项的名字、说明、搜索值 → 和快照比对。

调用关系：它保护快捷键列表的搜索体验，防止重构时丢掉 search_value。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params）；外部调用 3 个（assert_snapshot!, default, selection_tab）。

fn picker_wide_render_snapshot()

作用：保存宽屏下快捷键选择器的显示快照。

数据流：生成默认选择器 → 用 120 列宽渲染 → 和快照比对。

调用关系：它关注宽屏布局，发现界面排版变化。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params）；外部调用 2 个（assert_snapshot!, default）。

fn picker_narrow_render_snapshot()

作用：保存窄屏下快捷键选择器的显示快照。

数据流：生成默认选择器 → 用 78 列宽渲染 → 和快照比对。

调用关系：它关注小窗口布局，保证终端较窄时仍可读。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params）；外部调用 2 个（assert_snapshot!, default）。

fn picker_custom_render_snapshot()

作用：保存有自定义快捷键时选择器的显示快照。

数据流：先设置一个自定义绑定 → 生成运行时表和选择器 → 渲染并比对快照。

调用关系：它验证自定义配置在界面上的展示不会意外变化。

调用图：调用 3 个内部函数（from_config, keymap_with_replacement, build_keymap_picker_params）；外部调用 2 个（assert_snapshot!, default）。

fn picker_narrow_uses_compact_tabs()

作用：确认窄屏时选择器会用更紧凑的显示方式。

数据流：生成默认选择器并以窄宽度渲染 → 检查应出现的核心内容和不应出现的详细说明。

调用关系：它保护窄屏适配逻辑，避免界面塞入过多文字。

调用图：调用 2 个内部函数（defaults, build_keymap_picker_params）；外部调用 3 个（assert!, default, render_picker）。

fn action_menu_content_snapshot()

作用：记录不同绑定数量下动作菜单的选项变化。

数据流：分别构造未绑定、单绑定、多绑定配置 → 生成动作菜单和替换菜单 → 整理成文本 → 和快照比对。

调用关系：它覆盖 build_keymap_action_menu_params 和 build_keymap_replace_binding_menu_params 的主要分支。

调用图：调用 5 个内部函数（from_config, build_keymap_action_menu_params, build_keymap_replace_binding_menu_params, keymap_with_bindings, keymap_with_replacement）；外部调用 3 个（assert_snapshot!, default, action_menu_rows）。

fn action_menu_disables_clear_when_action_has_no_custom_binding()

作用：确认没有自定义绑定时，“Remove custom binding”会被禁用。

数据流：用默认配置生成 submit 的动作菜单 → 找到替换、追加、删除和返回项 → 检查禁用原因和关闭行为。

调用关系：它验证 has_custom_binding 对菜单状态的影响，防止用户点击一个没有意义的删除操作。

调用图：调用 2 个内部函数（defaults, build_keymap_action_menu_params）；外部调用 4 个（assert!, assert_eq!, default, selection_item）。

fn capture_view_snapshot()

作用：保存按键捕获视图初始显示的快照。

数据流：直接创建 KeymapCaptureView → 渲染成缓冲区调试文本 → 和快照比对。

调用关系：它保护 KeymapCaptureView::lines 和 render 的可见文案。

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

fn debug_view_initial_snapshot()

作用：保存按键调试视图刚打开时的快照。

数据流：创建默认调试视图 → 渲染成字符串 → 和快照比对。

调用关系：它覆盖 build_keymap_debug_view 的初始界面。

调用图：调用 2 个内部函数（defaults, build_keymap_debug_view）；外部调用 2 个（assert_snapshot!, default）。

fn debug_view_shows_delayed_missing_key_hint()

作用：确认调试视图等待一段时间后会提示用户可能没有收到按键。

数据流：创建调试视图 → 手动触发延迟提示 → 渲染并检查包含 Still waiting → 和快照比对。

调用关系：它验证诊断界面对“没收到按键”的友好提示。

调用图：调用 2 个内部函数（defaults, build_keymap_debug_view）；外部调用 4 个（assert!, assert_snapshot!, default, render_debug）。

fn debug_view_reports_detected_key_and_matching_actions()

作用：确认调试视图能显示检测到的按键以及匹配到的动作。

数据流：创建调试视图并显示延迟提示 → 模拟 Ctrl+O → 渲染 → 检查延迟提示消失并比对快照。

调用关系：它验证调试视图的按键接收和匹配展示流程。

调用图：调用 2 个内部函数（defaults, build_keymap_debug_view）；外部调用 6 个（Char, new, assert!, assert_snapshot!, default, render_debug）。

fn debug_view_uses_custom_binding_source()

作用：确认调试视图能标出某个匹配动作来自自定义绑定。

数据流：把 global.copy 改成 ctrl-x → 创建运行时表和调试视图 → 模拟 Ctrl+X → 检查显示动作和 [Custom] 标记。

调用关系：它验证自定义来源信息能从配置一路传到调试界面。

调用图：调用 3 个内部函数（from_config, build_keymap_debug_view, keymap_with_replacement）；外部调用 5 个（Char, new, assert!, default, render_debug）。

fn debug_view_labels_custom_global_fallback_source()

作用：确认调试视图能区分“自定义的全局兜底绑定”。

数据流：在 global.queue 写入 ctrl-q → 生成运行时表和调试视图 → 模拟 Ctrl+Q → 检查显示 composer.queue 和 [Custom global]。

调用关系：它保护全局快捷键兜底来源的显示，避免和普通自定义混淆。

调用图：调用 2 个内部函数（from_config, build_keymap_debug_view）；外部调用 7 个（Char, new, assert!, new, One, default, render_debug）。

fn capture_completion_returns_to_selected_keymap_picker_row()

作用：测试完整的捕获成功流程：打开菜单、捕获新键、返回主列表并选中刚改的行。

数据流：创建测试面板 → 打开 picker 和动作菜单 → 模拟 Enter 打开捕获 → 模拟 Ctrl+Shift+K → 收到 KeymapCaptured → 生成新配置并刷新 picker → 检查焦点和关闭行为。

调用关系：它把 build_keymap_action_menu_params、build_keymap_capture_view、keymap_with_replacement 和 picker 刷新流程串起来验证。

调用图：调用 7 个内部函数（defaults, from_config, build_keymap_action_menu_params, build_keymap_capture_view, keymap_with_replacement, build_keymap_picker_params, build_keymap_picker_params_for_selected_action）；外部调用 8 个（new, Char, new, assert!, assert_eq!, default, panic!, test_pane）。

fn clear_completion_returns_to_selected_keymap_picker_row()

作用：测试清除自定义绑定后，界面会回到主快捷键列表并选中对应动作。

数据流：先创建自定义绑定 → 打开 picker 和动作菜单 → 选择删除 → 收到 KeymapCleared → 用默认配置刷新 picker → 检查焦点和关闭行为。

调用关系：它验证删除流程和成功后替换旧弹窗栈的行为。

调用图：调用 6 个内部函数（defaults, from_config, build_keymap_action_menu_params, keymap_with_replacement, build_keymap_picker_params, build_keymap_picker_params_for_selected_action）；外部调用 6 个（new, assert!, assert_eq!, default, panic!, test_pane）。

fn replace_one_completion_drops_focused_keymap_submenus()

作用：测试替换多个绑定中的一个后，旧的子菜单都会被关掉，只留下新的主列表。

数据流：打开 picker、动作菜单和替换单个绑定菜单 → 构造刷新后的 picker 参数 → 替换当前相关视图 → 检查活动视图变成主 picker，Esc 后没有残留弹窗。

调用关系：它保护多层菜单完成后的清理逻辑，防止用户回到过期菜单。

调用图：调用 5 个内部函数（defaults, build_keymap_action_menu_params, build_keymap_replace_binding_menu_params, build_keymap_picker_params, build_keymap_picker_params_for_selected_action）；外部调用 5 个（new, assert!, assert_eq!, default, test_pane）。

fn key_capture_serializes_modifier_order_for_config()

作用：确认捕获到带多个修饰键的大写字母时，配置字符串顺序稳定。

数据流：构造 Ctrl+Alt+K 事件 → 调用转换 → 断言得到 ctrl-alt-shift-k。

调用关系：它覆盖 key_event_to_config_key_spec 对大写字母自动加入 Shift 的规则。

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

fn key_capture_serializes_special_keys()

作用：确认特殊键可以转换成配置字符串。

数据流：构造 Shift+PageDown 事件 → 调用转换 → 断言得到 shift-page-down。

调用关系：它验证 key_parts_to_config_key_spec 对非字母键的命名规则。

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

fn key_capture_serializes_function_keys_through_f24()

作用：确认功能键只支持 F1 到 F24。

数据流：分别转换 F13、F24、F25 → 前两个成功，F25 返回错误 → 和预期比较。

调用关系：它保护 MAX_FUNCTION_KEY 限制，避免写入终端不一定支持的功能键。

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

fn key_capture_serializes_c0_control_chars_as_ctrl_bindings()

作用：确认一些终端发来的控制字符会被规范化成 Ctrl 组合键。

数据流：构造换行、Ctrl+U、Ctrl+P 对应控制字符事件 → 转换 → 断言得到 ctrl-j、ctrl-u、ctrl-p。

调用关系：它覆盖 normalize_key_parts 的效果，保证不同终端发法能落成统一配置。

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

fn key_capture_serializes_minus_as_named_key()

作用：确认减号键在配置里写成 minus，避免和连接符混淆。

数据流：构造普通减号、Alt+减号、Ctrl+Alt+减号 → 转换 → 检查得到 minus、alt-minus、ctrl-alt-minus。

调用关系：它保护 key_parts_to_config_key_spec 对减号的特殊处理。

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

fn replacement_sets_single_binding()

作用：确认直接替换快捷键会写成单个绑定格式。

数据流：调用 keymap_with_replacement 设置 composer.submit → 检查配置字段是 One(ctrl-enter)。

调用关系：它验证 keymap_with_bindings 在一个键时使用单值结构。

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

fn replace_all_collapses_multi_binding_to_single()

作用：确认“替换全部”会把多个旧绑定压成一个新绑定。

数据流：先构造两个 submit 绑定 → 用 keymap_with_edit ReplaceAll → 检查返回绑定列表和配置都只剩新键。

调用关系：它覆盖 keymap_with_edit 的 ReplaceAll 分支。

调用图：调用 3 个内部函数（from_config, keymap_with_bindings, keymap_with_edit）；外部调用 3 个（assert_eq!, default, panic!）。

fn add_alternate_grows_single_binding()

作用：确认给单个默认快捷键添加备用键时，会保留默认键并加上新键。

数据流：用默认运行时表 → 对 composer.submit 添加 ctrl-enter → 检查配置变成 enter 和 ctrl-enter 两个绑定。

调用关系：它验证 AddAlternate 会先把默认绑定物化到用户配置里，再追加新键。

调用图：调用 2 个内部函数（defaults, keymap_with_edit）；外部调用 3 个（assert_eq!, default, panic!）。

fn add_alternate_grows_default_multi_binding()

作用：确认给本来就有多个默认绑定的动作添加备用键时，所有旧键都会保留。

数据流：用默认运行时表 → 给 editor.move_left 添加 ctrl-shift-b → 检查 left、ctrl-b 和新键都写入配置。

调用关系：它覆盖 AddAlternate 对默认多绑定动作的处理。

调用图：调用 2 个内部函数（defaults, keymap_with_edit）；外部调用 3 个（assert_eq!, default, panic!）。

fn add_alternate_duplicate_is_noop()

作用：确认添加一个已经存在的备用键不会改配置。

数据流：用默认运行时表 → 尝试给 composer.submit 添加 enter → 检查返回 Unchanged 和说明文字。

调用关系：它保护 keymap_with_edit 的重复检测，避免无意义保存。

调用图：调用 2 个内部函数（defaults, keymap_with_edit）；外部调用 2 个（assert_eq!, default）。

fn replace_one_preserves_other_bindings()

作用：确认只替换一个绑定时，其他绑定不受影响。

数据流：构造两个 submit 绑定 → 用 ReplaceOne 把 ctrl-enter 换成 ctrl-shift-enter → 检查另一个 alt-shift-enter 仍存在。

调用关系：它覆盖 keymap_with_edit 的 ReplaceOne 正常路径。

调用图：调用 3 个内部函数（from_config, keymap_with_bindings, keymap_with_edit）；外部调用 3 个（assert_eq!, default, panic!）。

fn replace_one_deduplicates_replacement()

作用：确认替换成另一个已经存在的绑定时，会自动去重。

数据流：构造 ctrl-enter 和 ctrl-shift-enter 两个绑定 → 把 ctrl-enter 替换成 ctrl-shift-enter → 检查最终只剩一个。

调用关系：它验证 ReplaceOne 分支会调用 dedup_bindings。

调用图：调用 3 个内部函数（from_config, keymap_with_bindings, keymap_with_edit）；外部调用 3 个（assert_eq!, default, panic!）。

fn replace_one_rejects_stale_old_key()

作用：确认如果用户想替换的旧键已经不再生效，会报错而不是乱改。

数据流：用默认运行时表 → 尝试替换不存在的 alt-enter → 检查错误里包含动作和旧键。

调用关系：它保护过期菜单场景，避免配置在用户没意识到的情况下被覆盖。

调用图：调用 2 个内部函数（defaults, keymap_with_edit）；外部调用 2 个（assert!, default）。

fn clear_removes_custom_binding()

作用：确认清除自定义绑定会把配置槽位恢复成 None。

数据流：先设置 composer.submit 自定义绑定 → 检查有自定义 → 调用 keymap_without_custom_binding → 检查字段为 None 且不再有自定义。

调用关系：它验证清除流程的底层配置改动。

调用图：调用 2 个内部函数（keymap_with_replacement, keymap_without_custom_binding）；外部调用 2 个（assert_eq!, default）。

fn replacement_rejects_unknown_action()

作用：确认给不存在的动作设置快捷键会返回错误。

数据流：调用 keymap_with_replacement 设置 composer.nope → 得到错误 → 检查错误包含这个动作名。

调用关系：它保护 binding_slot 的校验路径，防止未知动作静默写坏配置。

调用图：调用 1 个内部函数（keymap_with_replacement）；外部调用 2 个（assert!, default）。

fn build_keymap_debug_view(
    runtime_keymap: &RuntimeKeymap,
    keymap_config: &TuiKeymap,
) -> KeymapDebugView

作用：创建一个新的按键调试面板。调用者把当前正在使用的快捷键表和配置交给它，它会保存一份，用来之后判断用户按下的键会匹配哪些动作。

数据流：进去的是运行时快捷键表和配置里的快捷键设置 → 它把两者复制下来，并记录当前打开时间，同时把“最近一次按键报告”设为空、完成状态设为未完成 → 出来的是一个可以显示、可以接收按键的 KeymapDebugView。

调用关系：这个函数是打开调试面板时的入口。测试里的多个场景会用它先造出面板，然后再检查初始显示、按键报告、延迟提示和自定义快捷键来源是否正确。

调用图：被 5 处调用（debug_view_initial_snapshot, debug_view_labels_custom_global_fallback_source, debug_view_reports_detected_key_and_matching_actions, debug_view_shows_delayed_missing_key_hint, debug_view_uses_custom_binding_source）；外部调用 3 个（now, clone, clone）。

fn lines(&self, width: u16) -> Vec<Line<'static>>

作用：生成当前界面要显示的所有文字行。它使用“现在这一刻”的时间，所以能决定是否该显示等待太久后的额外提示。

数据流：进去的是可用宽度 → 它读取面板里的状态，比如打开时间和最近按键报告，并取得当前时间 → 出来的是一组已经组织好的文本行，供绘制和计算高度使用。

调用关系：它是渲染前的文字准备步骤。render 用它拿到要画的内容，desired_height 也用它计算这个面板需要占几行。具体排版工作交给 KeymapDebugView::lines_at。

调用图：调用 1 个内部函数（lines_at）；被 2 处调用（desired_height, render）；外部调用 1 个（now）。

fn lines_at(&self, width: u16, now: Instant) -> Vec<Line<'static>>

作用：按指定时间生成完整的调试界面文字。这个函数把标题、提示、按键结果、原始事件和匹配到的动作整理成适合终端显示的行。

数据流：进去的是显示宽度和一个时间点 → 它先放标题和说明，再根据是否等待超过 3 秒选择短提示或长提示；如果还没有按键，就显示等待中；如果已有按键报告，就展示检测结果、配置写法、原始事件和匹配到的动作 → 出来的是一组可直接渲染的文字行。

调用关系：这是整个面板显示内容的核心。KeymapDebugView::lines 会调用它；它会询问 KeymapDebugView::should_show_delayed_hint 是否该显示长提示，并把过长文字交给 push_wrapped_dim 自动换行。

调用图：调用 2 个内部函数（should_show_delayed_hint, push_wrapped_dim）；被 1 处调用（lines）；外部调用 4 个（from, format!, from, vec!）。

fn should_show_delayed_hint(&self, now: Instant) -> bool

作用：判断要不要显示更详细的“终端可能没发按键”提示。只有在还没收到任何按键，并且面板已经打开至少 3 秒时，才会显示。

数据流：进去的是当前时间 → 它读取面板打开的时间和是否已有按键报告，计算已经等了多久 → 出来的是 true 或 false，表示是否该换成长提示。

调用关系：它服务于 KeymapDebugView::lines_at。显示文字时，lines_at 先问它一句“用户是不是等太久了”，再决定用短提示还是长提示。

调用图：被 1 处调用（lines_at）；外部调用 1 个（duration_since）。

fn show_delayed_hint_for_test(&mut self)

作用：这是给测试用的小开关，用来假装这个面板已经打开很久了。这样测试不用真的等 3 秒，也能检查延迟提示是否会出现。

数据流：进去的是这个面板本身 → 它把打开时间改成“现在减去延迟时间” → 出来的效果是下一次生成界面文字时，会认为已经到了显示长提示的时候。

调用关系：它只在测试配置下存在。测试会调用它制造“已经等待足够久”的状态，然后再检查界面是不是显示了正确的提示。

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

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

作用：把按键调试面板真正画到终端界面上。它不负责决定内容，只负责把已经生成好的文字放进指定区域。

数据流：进去的是要绘制的屏幕区域和屏幕缓冲区（一块还没最终显示出来的画布） → 它根据区域宽度生成文字行，再包装成段落控件画进去 → 出来的是被写入内容的缓冲区，之后终端会显示这些内容。

调用关系：它是界面绘制流程调用的函数。外部的 render_debug 会需要它；它内部把内容生成交给 KeymapDebugView::lines，再交给界面库的 Paragraph 去画。

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

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

作用：告诉外层界面这个面板理想情况下需要多高。因为文字会按宽度换行，所以宽度不同，需要的行数也可能不同。

数据流：进去的是可用宽度 → 它生成当前宽度下的所有显示行，并数一共有多少行 → 出来的是一个高度数字。

调用关系：它在布局时被使用，比如 render_debug 需要知道该给底部面板留多少空间。它不自己排版，而是复用 KeymapDebugView::lines 的结果。

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

fn handle_key_event(&mut self, key_event: KeyEvent)

作用：处理用户按下的键，并生成一份新的按键检查报告。它会忽略按键释放事件，因为这里关心的是“按下时终端发来了什么”。

数据流：进去的是一个终端按键事件 → 如果这是松开键的事件，它什么都不改；否则它把事件转成可读的按键标签，尝试转成配置文件里的写法，生成原始事件摘要，并查找当前快捷键表里会被触发的动作 → 出来的是保存到面板里的 last_report，下一次渲染就会显示这份报告。

调用关系：它是用户按键后的核心处理点。底部面板框架把按键交给它；它会借助 KeyBinding::from_event、key_event_to_config_key_spec、key_event_debug_summary 和 matching_actions_for_key_event，把一个按键变成完整报告。

调用图：调用 3 个内部函数（from_event, matching_actions_for_key_event, key_event_debug_summary）；外部调用 1 个（key_event_to_config_key_spec）。

fn is_complete(&self) -> bool

作用：告诉外层这个调试面板是否已经结束。结束后，外层就可以把这个底部面板关掉。

数据流：进去的是面板当前状态 → 它读取 complete 这个标记 → 出来的是 true 或 false，表示是否完成。

调用关系：它被底部面板框架用来判断生命周期。KeymapDebugView::on_ctrl_c 会把 complete 改成 true，之后这个函数就会告诉外层可以收起面板。

fn on_ctrl_c(&mut self) -> CancellationEvent

作用：处理 Ctrl+C。这里 Ctrl+C 的意思是关闭按键检查器，而不是继续把它当作普通按键来检查。

数据流：进去的是可修改的面板状态 → 它把 complete 设为 true → 出来的是 CancellationEvent::Handled，表示这个取消动作已经被面板自己处理了。

调用关系：它由底部面板框架在用户按 Ctrl+C 时调用。它负责结束这个调试面板，并通过返回值告诉外层不用再额外处理这次 Ctrl+C。

fn prefer_esc_to_handle_key_event(&self) -> bool

作用：声明 Esc 键应该交给这个面板检查，而不是被外层当作“退出”快捷键优先处理。这样用户才能看见终端发送的 Esc 到底长什么样。

数据流：进去的是面板状态，但它不需要读取任何内容 → 它固定返回 true → 出来的效果是 Esc 会进入 handle_key_event，被当作普通待检查按键。

调用关系：它被底部面板框架用来决定 Esc 的归属。因为这个面板就是检查按键的，所以它要求优先拿到 Esc 事件。

fn next_frame_delay(&self) -> Option<Duration>

作用：告诉界面下一次自动刷新应该等多久。它主要是为了在没有按键时，到了 3 秒能自动把短提示换成长提示。

数据流：进去的是面板当前状态 → 如果已经有按键报告，它返回空，表示不需要为提示再安排刷新；如果还没按键，它计算距离“显示长提示的时间点”还差多久 → 出来的是一个等待时长，或者空值。

调用关系：它服务于界面的刷新调度。打开面板后，如果用户一直不按键，外层可以根据它安排下一帧；等时间到了，KeymapDebugView::lines_at 就会显示更详细的提示。

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

fn push_wrapped_dim(
    lines: &mut Vec<Line<'static>>,
    text: String,
    wrap_width: usize,
    initial_indent: &'static str,
    subsequent_indent: &'static str,
)

作用：把一段可能很长的说明文字拆成多行，并用灰暗样式显示。这样窄窗口里文字不会挤成一团，也能保持缩进好看。

数据流：进去的是要追加到的行列表、一段文字、可用宽度、第一行缩进和后续行缩进 → 它按宽度自动换行，每一行都套上灰暗样式，再追加到行列表里 → 出来的是变长后的行列表。

调用关系：它是 KeymapDebugView::lines_at 的排版帮手。凡是提示、原始事件或动作描述可能太长时，lines_at 都会把文字交给它处理。

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

fn key_event_debug_summary(key_event: KeyEvent) -> String

作用：把一个终端按键事件压缩成适合人看的原始摘要。它会显示按键代码、修饰键和事件类型，方便排查终端实际发来了什么。

数据流：进去的是一个 KeyEvent，也就是终端发来的按键事件 → 它取出 code、modifiers 和 kind，并把修饰键整理成可读文字 → 出来的是类似“code=..., modifiers=..., kind=...”的字符串。

调用关系：它由 KeymapDebugView::handle_key_event 调用，用来填充报告里的 Raw event 一栏。用户看到这一栏，就能知道 Codex 收到的底层按键信息。

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

fn key_modifiers_debug_label(modifiers: KeyModifiers) -> String

作用：把修饰键组合变成人能读懂的标签。修饰键就是 Ctrl、Alt、Shift 这类和其他键一起按的键。

数据流：进去的是一组修饰键标记 → 如果没有任何修饰键，就返回“none”；否则它依次检查 Ctrl、Alt、Shift，并把不认识的额外标记也保留下来 → 出来的是用竖线连接的文字，比如“ctrl|shift”。

调用关系：它是生成按键原始摘要时的辅助工具。它把机器内部的修饰键标记翻译成用户能看懂的字符串，让调试报告更直观。

调用图：外部调用 5 个（contains, difference, is_empty, new, format!）。

fn action(
    context: &'static str,
    context_label: &'static str,
    action: &'static str,
    description: &'static str,
) -> KeymapActionDescriptor

作用：创建一个普通的快捷键动作说明。它用于把“配置里的名字”和“用户看得懂的说明”打包成一条目录项。

数据流：进去的是动作所在区域、区域显示名、动作名和说明文字 → 它把这些值放进 KeymapActionDescriptor，并标记为不需要额外功能开关 → 出来的是一条可放进动作总表的描述记录，不改动外部数据。

调用关系：它主要服务于 KEYMAP_ACTIONS 这张动作总表。表里的大多数动作都通过它创建，后面的菜单显示、绑定查询和按键调试都依赖这些描述记录。

fn gated_action(
    context: &'static str,
    context_label: &'static str,
    action: &'static str,
    description: &'static str,
    required_feature: KeymapActionFeature,
) -> KeymapActionDescri

作用：创建一个“有条件才显示”的快捷键动作说明。比如某个功能没开启时，相关快捷键就不应该出现在 /keymap 里。

数据流：进去的是区域、显示名、动作名、说明文字，以及需要的功能开关 → 它生成一条描述记录，并把“需要哪个功能”一起记下来 → 出来的是带显示条件的动作描述，不直接检查当前是否开启。

调用关系：它也用于构建 KEYMAP_ACTIONS。之后 KeymapActionDescriptor::is_visible 会根据当前过滤条件判断这类动作要不要给用户看。

fn is_visible(self, filter: KeymapActionFilter) -> bool

作用：判断某个动作现在应不应该出现在快捷键设置界面里。它避免把用户当前不能用的功能也拿出来让人配置。

数据流：进去的是一个动作描述和一个过滤条件，比如是否开启 Fast mode → 它查看这条动作有没有要求特定功能 → 出来的是 true 或 false，表示显示或隐藏，不改动动作本身。

调用关系：它站在动作目录和界面展示之间。界面准备列出动作时，可以先用它筛一遍，只有满足当前功能开关的动作才会进入菜单。

fn action_label(action: &str) -> String

作用：把配置里稳定但偏机器化的动作名，变成用户更容易读的菜单标题。比如把 open_transcript 变成 Open Transcript。

数据流：进去的是一个用下划线连接的动作名字符串 → 它按下划线拆成单词，把每个单词首字母变成大写，再用空格连起来 → 出来的是展示用文字；原始动作名不会被改。

调用关系：它被 build_keymap_action_menu_params、build_keymap_capture_view 和 build_keymap_replace_binding_menu_params 使用。也就是说，凡是快捷键菜单或捕获界面需要显示动作标题时，都会找它把内部名字翻译成人能看的名字。

调用图：被 3 处调用（build_keymap_action_menu_params, build_keymap_capture_view, build_keymap_replace_binding_menu_params）。

fn binding_slot(
    keymap: &'a mut TuiKeymap,
    context: &str,
    action: &str,
) -> Option<&'a mut Option<KeybindingsSpec>>

作用：根据“区域 + 动作名”，找到用户配置里对应的那个快捷键设置位置。它的关键作用是让编辑器知道该改配置文件里的哪一格。

数据流：进去的是一份可修改的 TuiKeymap 配置、区域名和动作名 → 它用一大张匹配表找到对应字段，例如 composer 的 submit → 出来的是那个字段的可修改引用；如果找不到，就返回空。这个字段本身可能是未设置、自定义绑定，或显式解绑。

调用关系：它被 debug_binding_source、has_custom_binding、keymap_with_bindings 和 keymap_without_custom_binding 使用。换句话说，检查是否自定义、写入新绑定、删除自定义绑定、判断调试来源时，都要先通过它定位配置位置。

调用图：被 4 处调用（debug_binding_source, has_custom_binding, keymap_with_bindings, keymap_without_custom_binding）。

fn bindings_for_action(
    runtime_keymap: &'a RuntimeKeymap,
    context: &str,
    action: &str,
) -> Option<&'a [KeyBinding]>

作用：根据“区域 + 动作名”，读取程序运行时真正生效的快捷键。它回答的是“现在按哪些键会触发这个动作”，不是“配置文件里写了什么”。

数据流：进去的是已经解析好的 RuntimeKeymap、区域名和动作名 → 它从运行时快捷键表里找到对应动作的按键列表 → 出来的是一段只读的 KeyBinding 列表；如果动作名不认识，就返回空。

调用关系：它被 active_binding_specs 和 build_keymap_capture_view 调用。快捷键界面需要显示当前有效按键，或把当前绑定转成配置文本时，会通过它读取运行时结果。

调用图：被 2 处调用（active_binding_specs, build_keymap_capture_view）。

fn format_binding_summary(bindings: &[KeyBinding]) -> String

作用：把一个动作的快捷键列表压缩成适合菜单显示的一行文字。没有绑定时显示 unbound，有多个键时用逗号隔开。

数据流：进去的是若干个运行时按键绑定 → 它把每个绑定转换成配置里能写的按键文本，并去掉看起来重复的等价写法 → 出来的是一段简短字符串，比如 Ctrl+C, Esc 或 unbound，不改动原绑定。

调用关系：它会调用集合创建和遍历这些基础操作来去重。build_keymap_capture_view 会用它显示某个动作当前绑定了哪些键，让用户不用看复杂的内部按键结构。

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

fn label(&self) -> &'static str

作用：把调试用的绑定来源变成可显示的短标签。比如显示成 Custom、Custom global 或 Default。

数据流：进去的是一个来源枚举值，也就是程序内部用来区分来源的小标签 → 它按不同来源返回固定英文文字 → 出来的是界面能直接显示的字符串，不改动任何状态。

调用关系：它服务于按键调试展示。前面的逻辑先判断一个命中的动作来自哪里，界面需要展示时再用它把内部分类变成用户能读的文字。

fn matching_actions_for_key_event(
    runtime_keymap: &RuntimeKeymap,
    keymap_config: &TuiKeymap,
    event: KeyEvent,
) -> Vec<KeymapDebugActionMatch>

作用：反查“用户刚按下的这个键，会触发哪些动作”。这对调试快捷键冲突和理解当前键位非常有用。

数据流：进去的是运行时快捷键表、用户原始配置和一次按键事件 → 它遍历动作总表，读取每个动作的有效绑定，检查是否有绑定匹配这次按键 → 出来的是命中的动作列表，每条包含区域、动作名、显示标签、说明和绑定来源。

调用关系：它被 handle_key_event 调用，通常是在处理真实按键时用来做调试或诊断。它内部会用 bindings_for_action 找有效按键，用 action_label 做显示名，并用 debug_binding_source 判断来源。

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

fn debug_binding_source(
    keymap_config: &TuiKeymap,
    descriptor: &KeymapActionDescriptor,
) -> KeymapDebugBindingSource

作用：判断一个动作的快捷键来源：是这个动作自己被用户改过、是借用了全局自定义设置，还是完全来自默认值。

数据流：进去的是用户快捷键配置和一个动作描述 → 它先复制一份配置，避免为了查字段而改到原件；再用 binding_slot 看动作自身有没有自定义；如果没有，再用 global_fallback_slot 看是否有可用的全局兜底配置 → 出来的是来源分类。

调用关系：它被 matching_actions_for_key_event 使用。按键命中某个动作后，需要告诉用户“为什么这个键会触发它”，这个函数就负责给出来源解释。

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

fn global_fallback_slot(
    keymap: &'a mut TuiKeymap,
    descriptor: &KeymapActionDescriptor,
) -> Option<&'a mut Option<KeybindingsSpec>>

作用：找到少数 composer 动作对应的全局兜底快捷键设置。也就是说，如果局部没有配置，有些输入框动作可以退回去用全局配置。

数据流：进去的是可修改的 TuiKeymap 和动作描述 → 它先确认动作区域是不是 composer，不是就直接返回空；是的话，只对 submit、queue、toggle_shortcuts 这几个动作返回对应的全局配置位置 → 出来的是可选的配置字段引用。

调用关系：它只被 debug_binding_source 调用。调试来源时，如果动作自身没有自定义绑定，就用它检查是否命中了这种“全局兜底”的特殊规则。

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

fn is_unbound(&self) -> bool

作用：判断这一行快捷键是不是“没有绑定任何按键”。这让界面能把未绑定的动作单独挑出来，或者用特殊符号标出来。

数据流：输入是一条快捷键行里的绑定摘要文字 → 它检查这段文字是否正好是 unbound → 输出真假值，不改动任何数据。

调用关系：它是行状态的小判断工具。keymap_row_prefix 会用它决定这一行前面该显示减号还是空白；构建整体页面时也会用同样的判断思路统计未绑定数量。

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

fn build_keymap_picker_params(
    runtime_keymap: &RuntimeKeymap,
    keymap_config: &TuiKeymap,
) -> SelectionViewParams

作用：用默认筛选条件创建完整的快捷键选择器参数。测试里常用它来快速拿到一个正常的 /keymap 页面结构。

数据流：输入是当前运行中的快捷键表和用户配置 → 它补上默认的动作筛选条件 → 交给更通用的构建函数继续处理 → 输出一份可直接显示的选择器页面参数。

调用关系：它是一个省事入口，主要服务测试场景。它不自己拼页面，而是把活交给 build_keymap_picker_params_with_filter，让后面的统一流程负责生成标签页和列表。

调用图：调用 1 个内部函数（build_keymap_picker_params_with_filter）；被 15 处调用（capture_completion_returns_to_selected_keymap_picker_row, clear_completion_returns_to_selected_keymap_picker_row, picker_all_tab_items_remain_searchable, picker_approval_tab_lists_all_approval_actions, picker_common_tab_lists_curated_actions, picker_content_snapshot, picker_custom_render_snapshot, picker_customized_tab_contains_root_overrides, picker_debug_tab_is_last_and_opens_inspector, picker_hides_fast_mode_action_when_feature_is_disabled (+5 more)）；外部调用 1 个（default）。

fn build_keymap_picker_params_with_filter(
    runtime_keymap: &RuntimeKeymap,
    keymap_config: &TuiKeymap,
    action_filter: KeymapActionFilter,
) -> SelectionViewParams

作用：按指定筛选条件创建快捷键选择器。比如某些功能开关没开时，可以把对应动作先过滤掉。

数据流：输入是运行时快捷键、配置文件里的快捷键设置，以及一个动作筛选器 → 它表示“不指定初始选中的动作” → 调用核心构建函数 → 输出选择器页面参数。

调用关系：它是正式代码会用到的入口之一，也被测试用来验证不同筛选条件下页面是否正确。它把实际页面拼装交给 build_keymap_picker_params_for_action。

调用图：调用 1 个内部函数（build_keymap_picker_params_for_action）；被 4 处调用（build_keymap_picker_params, keymap_picker_fast_mode_enabled_snapshot, picker_covers_every_replaceable_action, picker_shows_fast_mode_action_when_feature_is_enabled）。

fn build_keymap_picker_params_for_selected_action(
    runtime_keymap: &RuntimeKeymap,
    keymap_config: &TuiKeymap,
    context: &str,
    action: &str,
) -> SelectionViewParams

作用：创建快捷键选择器，并让某个指定动作一开始就被选中。这样用户编辑完某个快捷键返回列表时，不会迷路。

数据流：输入是快捷键数据、用户配置、目标场景和目标动作名 → 它使用默认筛选条件 → 转交给带筛选版本 → 输出带初始选中行的选择器参数。

调用关系：它主要用于测试“返回页面后焦点还在原来那一行”等体验。它把具体工作交给 build_keymap_picker_params_for_selected_action_with_filter。

调用图：调用 1 个内部函数（build_keymap_picker_params_for_selected_action_with_filter）；被 4 处调用（capture_completion_returns_to_selected_keymap_picker_row, clear_completion_returns_to_selected_keymap_picker_row, picker_selected_action_starts_on_matching_all_tab_row, replace_one_completion_drops_focused_keymap_submenus）；外部调用 1 个（default）。

fn build_keymap_picker_params_for_selected_action_with_filter(
    runtime_keymap: &RuntimeKeymap,
    keymap_config: &TuiKeymap,
    action_filter: KeymapActionFilter,
    context: &str,
    action:

作用：在指定筛选条件下创建快捷键选择器，并尝试选中某个指定动作。它是“带筛选”和“带初始选中”两个需求的组合入口。

数据流：输入是快捷键数据、配置、筛选器、目标场景和目标动作 → 它把目标动作包装成可选值 → 调用核心构建函数 → 输出页面参数，里面可能带有初始选中位置。

调用关系：它由 build_keymap_picker_params_for_selected_action 调用，自己不拼界面，只负责把参数整理好，再交给 build_keymap_picker_params_for_action。

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

fn build_keymap_picker_params_for_action(
    runtime_keymap: &RuntimeKeymap,
    keymap_config: &TuiKeymap,
    action_filter: KeymapActionFilter,
    selected_action: Option<(&str, &str)>,
) -> Sele

作用：这是本文件的核心装配函数，真正把快捷键数据做成一个能显示、能搜索、能分组、能点击的选择器页面。

数据流：输入是运行时快捷键、配置、筛选器，以及可选的目标动作 → 它先生成所有行，再统计总数、自定义数、未绑定数，计算初始选中行和列宽；随后组装全部、常用、自定义、未绑定、各场景分组和调试标签页 → 输出完整的 SelectionViewParams，也就是底部选择器需要的整套页面说明。

调用关系：上层几个公开构建函数最终都会来到这里。它把不同小零件串起来：build_keymap_rows 造原始行，keymap_common_rows 挑常用项，keymap_selection_items 把行变成可点击项目，keymap_header 和提示行函数负责显示说明，keymap_debug_tab 加入调试入口。

调用图：调用 7 个内部函数（action_count_line, build_keymap_rows, keymap_common_rows, keymap_debug_tab, keymap_header, keymap_picker_hint_line, keymap_selection_items）；被 2 处调用（build_keymap_picker_params_for_selected_action_with_filter, build_keymap_picker_params_with_filter）；外部调用 5 个（new, default, new, format!, vec!）。

fn keymap_debug_tab() -> SelectionTab

作用：创建“Debug”调试标签页，用来检查终端实际传给程序的按键。这个功能对排查快捷键识别问题很有用。

数据流：它不需要外部输入 → 它生成一个标签页，里面只有一个“Inspect keypresses”项目；用户按回车时会发送打开按键调试器的事件 → 输出这个调试标签页。

调用关系：build_keymap_picker_params_for_action 在组装所有标签页时会把它追加进去。它自己用 keymap_header 做页头，并把后续动作交给应用事件系统处理。

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

fn build_keymap_rows(
    runtime_keymap: &RuntimeKeymap,
    keymap_config: &TuiKeymap,
    action_filter: KeymapActionFilter,
) -> Vec<KeymapActionRow>

作用：把系统知道的所有可配置动作，整理成一行一行适合显示的快捷键信息。

数据流：输入是运行中的快捷键表、用户配置和动作筛选器 → 它遍历动作清单，跳过不可见动作，查出每个动作当前绑定的按键，生成显示用名称和摘要，并判断是否有用户自定义绑定 → 输出 KeymapActionRow 列表。

调用关系：它是页面数据的源头，由 build_keymap_picker_params_for_action 调用。后面的常用列表、自定义列表、未绑定列表和各场景标签页，都是从它产出的这些行里再筛出来的。

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

fn keymap_common_rows(rows: &[KeymapActionRow]) -> Vec<&KeymapActionRow>

作用：从全部快捷键行里挑出“常用快捷键”。这样用户能先看到最可能会改的那些键。

数据流：输入是所有快捷键行 → 它按照预先写好的常用动作顺序逐个查找匹配行 → 输出这些行的引用列表，顺序保持为常用清单的顺序。

调用关系：build_keymap_picker_params_for_action 用它生成 Common 标签页。它不创建新数据，只是在全部行里挑重点，像从厚通讯录里摘出常联系人。

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

fn keymap_selection_items(
    rows: impl IntoIterator<Item = &'a KeymapActionRow>,
    empty_name: &str,
    empty_description: &str,
) -> Vec<SelectionItem>

作用：把快捷键行变成选择器能显示的项目列表。如果没有项目，它会放一个灰掉的提示项，避免页面空白。

数据流：输入是一批快捷键行，以及空列表时要显示的标题和说明 → 它把每一行转换成 SelectionItem；如果转换后为空，就生成一个不可点击的占位项目 → 输出选择器项目列表。

调用关系：build_keymap_picker_params_for_action 在创建每个标签页时都会用它。它内部依赖单行转换逻辑，把原始快捷键行包装成底部选择器认识的格式。

调用图：被 1 处调用（build_keymap_picker_params_for_action）；外部调用 2 个（into_iter, vec!）。

fn keymap_selection_item(row: &KeymapActionRow) -> SelectionItem

作用：把一条快捷键行变成一个可点击、可搜索的列表项目。用户选中它后，就能进入这个动作的快捷键编辑菜单。

数据流：输入是一条快捷键行 → 它准备显示名称、前缀标记、当前按键说明、搜索用文字，并创建一个点击动作；这个点击动作会发送打开动作菜单的事件，带上场景和动作名 → 输出一个 SelectionItem。

调用关系：它是 keymap_selection_items 处理每一行时用到的单行包装器。它会调用 keymap_row_prefix 生成左侧场景名和自定义/未绑定标记，后续真正打开菜单则交给应用事件系统。

调用图：调用 1 个内部函数（keymap_row_prefix）；外部调用 3 个（default, format!, vec!）。

fn keymap_row_prefix(row: &KeymapActionRow) -> Vec<Span<'static>>

作用：生成每一行左侧的小前缀，包括动作所属场景，以及自定义或未绑定的标记。这样用户扫一眼就知道这一行的大致状态。

数据流：输入是一条快捷键行 → 它先看是否是自定义绑定，是就用高亮星号；否则看是否未绑定，是就用暗色减号；普通项则留空 → 输出一组带样式的文字片段。

调用关系：keymap_selection_item 用它给列表项加左侧装饰。它会调用 KeymapActionRow::is_unbound 判断未绑定状态，并用统一的强调色函数保证界面风格一致。

调用图：调用 2 个内部函数（is_unbound, accent_style）；被 1 处调用（keymap_selection_item）；外部调用 1 个（vec!）。

fn keymap_header(description: String, summary: String) -> Box<dyn Renderable>

作用：生成每个快捷键标签页顶部的说明区。它告诉用户当前页是什么，以及有多少动作之类的摘要信息。

数据流：输入是页面描述和摘要文字 → 它创建一个竖排文字块，第一行是加粗的 Keymap，后两行是变暗的说明和统计 → 输出一个可渲染的页头对象。

调用关系：build_keymap_picker_params_for_action 用它给各个普通标签页做页头，keymap_debug_tab 也用它给调试页做页头。它只负责显示外壳，不决定里面有哪些快捷键。

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

fn action_count_line(count: usize) -> String

作用：把动作数量变成适合显示的一句话，并处理 1 个和多个时的英文单复数。

数据流：输入是动作数量 → 如果是 1，就输出 1 action.；否则输出类似 5 actions. → 不改动任何外部状态。

调用关系：build_keymap_picker_params_for_action 用它生成各个标签页页头里的统计摘要。它是一个很小的文字格式化帮手。

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

fn keymap_picker_hint_line() -> Line<'static>

作用：生成快捷键选择器底部的操作提示，告诉用户左右切换分组、回车编辑、星号和减号是什么意思、Esc 关闭。

数据流：它不需要业务输入 → 它取统一强调色，拼出一行带样式的提示文字 → 输出这行提示给选择器底部显示。

调用关系：build_keymap_picker_params_for_action 在创建整个选择器时把它放进页脚。它帮助用户理解这个页面怎么操作。

调用图：调用 1 个内部函数（accent_style）；被 1 处调用（build_keymap_picker_params_for_action）；外部调用 2 个（from, vec!）。

fn keymap_debug_hint_line() -> Line<'static>

作用：生成调试标签页专用的底部提示，告诉用户回车开始检查按键，Esc 关闭。

数据流：它不接收输入 → 它用统一强调色拼出调试页的简短提示文字 → 输出一行可显示的提示。

调用关系：快捷键选择器会把它作为 Debug 标签页的专用页脚提示。普通标签页用 keymap_picker_hint_line，调试页用这个更贴合当前任务的提示。

调用图：调用 1 个内部函数（accent_style）；外部调用 2 个（from, vec!）。

fn build_pet_picker_params(
    current_pet: Option<&str>,
    codex_home: &Path,
    preview_state: PetPickerPreviewState,
) -> SelectionViewParams

作用：组装 /pets 弹窗需要的全部参数：标题、列表、搜索、右侧预览区、默认选中项，以及用户点选后要发出的事件。外层界面调用它，就能拿到一个可以直接显示的宠物选择窗口配置。

数据流：进去的是当前宠物编号、Codex 的主目录路径、以及预览区状态。它先找出所有可选宠物，把它们排序，并把“关闭宠物”放到第一项；再逐个变成界面列表项，标出当前正在用的宠物，设置搜索关键词和点击动作；最后输出一个 SelectionViewParams，也就是弹窗完整说明书。过程中它不会直接保存配置，也不会自己加载图片，只会安排好事件：光标变化时请求预览，点选时发送选择或关闭宠物的消息。

调用关系：这是这个文件的主入口。测试函数会直接调用它来验证菜单行为；真实运行时，打开 /pets 弹窗的界面代码也会用它。它把“找宠物”的活交给 available_pet_entries，把底部提示交给 standard_popup_hint_line，把右侧预览区交给 preview_state.renderable()，自己负责把这些零件拼成最终弹窗。

调用图：调用 3 个内部函数（standard_popup_hint_line, available_pet_entries, renderable）；被 4 处调用（picker_imports_legacy_avatar_manifests, picker_lists_app_bundled_and_custom_pets, picker_marks_disabled_pet_as_current, picker_preselects_codex_without_marking_it_current_when_no_pet_is_configured）；外部调用 3 个（new, default, Fixed）。

fn available_pet_entries(codex_home: &Path) -> Vec<PetPickerEntry>

作用：收集菜单里应该出现的所有宠物条目。它把程序自带宠物、“关闭宠物”这一项、以及用户自定义宠物放到同一个列表里。

数据流：进去的是 Codex 主目录路径。它先从内置宠物清单里复制出名字、编号和说明；再额外加入一个“Disable terminal pets”的关闭选项；最后把 custom_pet_entries 找到的自定义宠物接到列表后面。出来的是一组还没排序的宠物菜单条目。

调用关系：build_pet_picker_params 在组装弹窗前会先叫它准备原料。它自己负责内置宠物和关闭选项，遇到用户自定义宠物时再把工作交给 custom_pet_entries。

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

fn custom_pet_entries(codex_home: &Path) -> Vec<PetPickerEntry>

作用：从用户的配置目录里寻找自定义宠物，并把能正常读取的宠物变成菜单项。它还兼容旧名字：以前叫 avatar 的目录和文件，也能被当成宠物导入。

数据流：进去的是 Codex 主目录路径。它会分别查看 avatars 目录里的 avatar.json 和 pets 目录里的 pet.json；每看到一个合法清单文件，就从文件夹名推导宠物编号，跳过非法或保留的名字；然后用 Pet::load_with_codex_home 真正读取宠物资料。成功的话，它输出包含显示名、说明、选择编号和旧编号的条目；失败或文件不完整就静静跳过，不让坏文件弄坏整个菜单。

调用关系：available_pet_entries 会调用它来补充用户自己的宠物。它依赖 custom_pet_selector 把普通文件夹名变成内部使用的 custom:xxx 形式，也依赖 Pet::load_with_codex_home 读取宠物配置。这样主弹窗不用关心磁盘目录长什么样。

调用图：调用 2 个内部函数（load_with_codex_home, custom_pet_selector）；被 1 处调用（available_pet_entries）；外部调用 3 个（new, join, read_dir）。

fn write_pet(dir: &Path, folder_name: &str, display_name: &str)

作用：测试用的小帮手，用来在临时目录里伪造一个新版自定义宠物。这样测试不用依赖用户电脑上真的有宠物文件。

数据流：进去的是临时目录、宠物文件夹名和显示名。它创建 pets/<folder_name> 目录，写入一个 pet.json，再写一张测试用 spritesheet 图片文件。出来没有返回值，但磁盘上的临时目录会多出一个看起来完整的自定义宠物。

调用关系：tests::picker_lists_app_bundled_and_custom_pets 会用它先准备测试数据，然后再调用 build_pet_picker_params 看菜单是否能把这个自定义宠物列出来。它把写测试图片的细节交给 catalog::write_test_spritesheet。

调用图：调用 1 个内部函数（write_test_spritesheet）；外部调用 4 个（join, format!, create_dir_all, write）。

fn write_legacy_avatar(dir: &Path, folder_name: &str, display_name: &str)

作用：测试用的小帮手，用来伪造旧格式的自定义头像，也就是放在 avatars 目录、使用 avatar.json 的那种。它用来确认旧用户的数据不会被新菜单漏掉。

数据流：进去的是临时目录、头像文件夹名和显示名。它创建 avatars/<folder_name> 目录，写入旧格式的 avatar.json，再写一张测试图片。出来没有返回值，但临时目录里会出现一个旧格式头像数据。

调用关系：tests::picker_imports_legacy_avatar_manifests 会先调用它制造旧数据，再调用 build_pet_picker_params 检查这个旧头像是否被当成自定义宠物列入菜单。它同样把测试图片生成交给 catalog::write_test_spritesheet。

调用图：调用 1 个内部函数（write_test_spritesheet）；外部调用 4 个（join, format!, create_dir_all, write）。

fn picker_lists_app_bundled_and_custom_pets()

作用：检查宠物菜单是否同时列出内置宠物和用户自定义宠物，并且顺序、默认选中项、搜索值都符合预期。

数据流：它先创建一个临时 Codex 主目录，再用 write_pet 放入一个叫 Chefito 的自定义宠物。接着调用 build_pet_picker_params，假装当前宠物是 chefito。最后它检查输出菜单的名字顺序，确认关闭选项在最前，自定义宠物出现在列表里，初始选中位置正确，搜索值是 custom:chefito。

调用关系：这是对主流程的综合测试。它直接调用 build_pet_picker_params，间接覆盖 available_pet_entries 和 custom_pet_entries，证明从磁盘自定义宠物到界面列表项这条路是通的。

调用图：调用 1 个内部函数（build_pet_picker_params）；外部调用 4 个（assert_eq!, tempdir, write_pet, default）。

fn picker_preselects_codex_without_marking_it_current_when_no_pet_is_configured()

作用：检查一个容易混淆的细节：没有配置宠物时，菜单可以默认高亮 Codex，但不能把它标成当前正在使用。

数据流：它创建一个空的临时 Codex 主目录，然后用 current_pet 为 None 调用 build_pet_picker_params。结果出来后，它检查初始高亮项是 Codex，同时确认 Codex 的 is_current 是 false。也就是说，界面给用户一个合理起点，但不假装用户已经选过它。

调用关系：它专门验证 build_pet_picker_params 里默认选择和当前状态的区别。这个测试保护的是用户体验：默认高亮只是方便操作，不能等同于已经启用。

调用图：调用 1 个内部函数（build_pet_picker_params）；外部调用 4 个（assert!, assert_eq!, tempdir, default）。

fn picker_marks_disabled_pet_as_current()

作用：检查当用户当前配置是“关闭宠物”时，菜单第一项会正确显示为当前项，并带有方便搜索关闭功能的关键词。

数据流：它创建临时目录，然后把当前宠物传成 DISABLED_PET_ID 来调用 build_pet_picker_params。返回结果里，它检查第一项就是“Disable terminal pets”，没有说明文字，被标成当前项，而且搜索词包含 disable、hidden、off、none 等方便用户查找的词。

调用关系：它验证 build_pet_picker_params 对特殊关闭项的处理。这个关闭项不是普通宠物，所以点击后会发送 PetDisabled 事件；测试确保它在列表位置和状态标记上也被特殊对待。

调用图：调用 1 个内部函数（build_pet_picker_params）；外部调用 4 个（assert!, assert_eq!, tempdir, default）。

fn picker_imports_legacy_avatar_manifests()

作用：检查旧版 avatars/avatar.json 格式仍然能出现在新宠物菜单里。这样老用户升级后，原来的自定义头像不会突然消失。

数据流：它先创建临时目录，再用 write_legacy_avatar 写入一个旧格式头像。然后调用 build_pet_picker_params，当前宠物传入 custom:legacy。最后它在输出菜单中找到名为 Legacy 的条目，确认它被标成当前项，并且搜索值是新的 custom:legacy 形式。

调用关系：它主要覆盖 custom_pet_entries 的兼容逻辑，但通过 build_pet_picker_params 从外部验证整个菜单结果。这个测试说明旧编号和新选择编号之间的桥接没有断。

调用图：调用 1 个内部函数（build_pet_picker_params）；外部调用 5 个（assert!, assert_eq!, tempdir, write_legacy_avatar, default）。

fn disable_ambient_pet_before_shutdown(&mut self, tui: &mut tui::Tui) -> Result<()>

作用：在程序退出前关掉环境宠物，并尽量把终端上的宠物图片擦掉。这样退出时不会留下半张图片或奇怪的显示残影。

数据流：进去的是当前 App 状态和 Tui 终端界面对象 → 它先告诉聊天组件本次会话不要再显示宠物，然后调用终端界面去清掉宠物图片 → 如果清理时是终端本身出错，就把错误返回；如果只是宠物素材相关错误，就记一条警告后继续退出。

调用关系：它通常在关机或退出流程前被调用。它把真正清屏的活交给 tui.clear_ambient_pet_image，遇到不严重的素材问题时只通过 warn! 记录，避免退出流程被小问题卡住。

调用图：外部调用 2 个（clear_ambient_pet_image, warn!）。

fn handle_ambient_pet_image_render_error(
        &mut self,
        tui: &mut tui::Tui,
        err: crate::pets::PetImageRenderError,
    ) -> Result<()>

作用：处理常驻宠物图片画不出来的情况。它的目标是保护主界面：终端坏了就报错，素材坏了就禁用宠物并清理画面。

数据流：进去的是 App、Tui，以及一次宠物图片渲染错误 → 它先判断错误类型：如果是终端错误，就转换成上层能处理的错误并返回；如果是素材错误，就记录警告，禁用本次会话的宠物，再尝试清掉已经显示的宠物图片 → 最后返回成功，除非清理时又遇到终端错误。

调用关系：它位于宠物图片绘制失败后的补救流程里。它调用 tui.clear_ambient_pet_image 做现场清理，用 warn! 记录素材问题，并在终端错误时通过 into 把错误交给上层流程处理。

调用图：外部调用 3 个（clear_ambient_pet_image, warn!, into）。

fn handle_pet_picker_preview_image_render_error(
        &mut self,
        tui: &mut tui::Tui,
        err: crate::pets::PetImageRenderError,
    ) -> Result<()>

作用：处理宠物选择器里的预览图画不出来的情况。它会告诉界面“预览失败了”，同时尽量把预览区域清干净。

数据流：进去的是 App、Tui，以及预览图渲染错误 → 如果是终端错误，就直接返回错误；如果是素材错误，就记录警告，把错误文字交给聊天组件显示为预览失败，再请求 Tui 用空请求重画预览区域，相当于清空预览图 → 如果清空时只是素材问题就继续，如果是终端问题就返回错误。

调用关系：它在宠物选择弹窗的预览图片失败时被用到。它把用户可见的失败状态交给 chat_widget，把清理图片的工作交给 tui.draw_pet_picker_preview_image，并用 to_string 把底层错误变成能显示给用户看的文字。

调用图：外部调用 4 个（draw_pet_picker_preview_image, warn!, into, to_string）。

fn handle_pet_selected(&mut self, tui: &mut tui::Tui, pet_id: String)

作用：用户选中某个宠物后，这个函数启动加载流程。它先让界面显示“正在加载”，再把耗时的准备和读取宠物工作放到后台，避免卡住终端界面。

数据流：进去的是 App、Tui 和用户选择的 pet_id → 它在聊天组件里打开加载弹窗，要求界面重画；接着复制配置目录、动画开关、事件发送器等必要信息 → 然后用后台阻塞任务去确保内置宠物包存在，并加载 AmbientPet → 最后把成功或失败结果通过 AppEvent::PetSelectionLoaded 发回主流程。

调用关系：它是“用户点选宠物”后的第一站。它通过 tui.frame_requester().schedule_frame 让界面立刻刷新，通过 spawn_blocking 把重活放到后台，后台完成后用 app_event_tx 把结果送回，后续通常会由 App::handle_pet_selection_loaded 接着处理。

调用图：外部调用 3 个（frame_requester, drop, spawn_blocking）。

async fn handle_pet_disabled(&mut self, tui: &mut tui::Tui)

作用：处理用户选择关闭宠物的操作。它会把“禁用宠物”写进配置，这样不只是当前界面关掉，下次启动也会记住。

数据流：进去的是 App 和 Tui → 它先创建一条配置修改，内容是把 TUI 宠物设为禁用 ID → 用 ConfigEditsBuilder 把修改写到配置里 → 如果成功，就同步当前界面状态并请求重画；如果失败，就在聊天界面显示一条错误消息。

调用关系：它在用户明确关闭宠物时运行。它调用 tui_pet_edit 生成配置改动，用 ConfigEditsBuilder::new 开始保存流程，成功后通过 frame_requester 触发刷新，失败时用 format! 拼出用户能看到的错误提示。

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

fn handle_pet_preview_loaded(
        &mut self,
        tui: &mut tui::Tui,
        request_id: u64,
        result: Result<crate::pets::AmbientPet, String>,
    )

作用：处理宠物预览加载完成的结果。无论成功还是失败，它都会把结果交给宠物选择界面，并要求终端重画。

数据流：进去的是 App、Tui、请求编号 request_id，以及加载出的 AmbientPet 或错误文字 → 它把这些交给聊天组件，让组件按请求编号结束对应的预览加载状态 → 然后请求下一帧刷新，让用户看到预览图或失败提示。

调用关系：它通常接在后台预览加载任务之后。它不自己解释结果，而是交给 chat_widget.finish_pet_picker_preview_load，再通过 tui.frame_requester().schedule_frame 推动界面更新。

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

async fn handle_pet_selection_loaded(
        &mut self,
        tui: &mut tui::Tui,
        request_id: u64,
        pet_id: String,
        result: Result<Option<crate::pets::AmbientPet>, String>,

作用：处理“用户选择的宠物已经加载完”这件事。它会关闭加载弹窗，成功时保存选择并更新界面，失败时显示错误。

数据流：进去的是 App、Tui、加载弹窗的 request_id、pet_id，以及加载结果 → 它先用 request_id 确认这个结果还对应当前弹窗；如果不是，就什么也不改，继续运行 → 如果加载成功，就生成配置修改，把选择的宠物写入配置，成功后更新内存里的 config.tui_pet 和聊天组件里的宠物对象；如果保存失败或加载失败，就显示错误消息 → 最后请求界面重画，并返回继续运行。

调用关系：它通常接收 App::handle_pet_selected 后台任务发回来的结果。它调用 tui_pet_edit 和 ConfigEditsBuilder::new 来保存配置，用 chat_widget 更新弹窗和宠物状态，并通过 frame_requester 让用户看到最终变化。

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

fn handle_configured_pet_loaded(
        &mut self,
        tui: &mut tui::Tui,
        pet_id: String,
        result: Result<Option<crate::pets::AmbientPet>, String>,
    )

作用：处理启动或配置读取后，已配置宠物的加载结果。它会确认结果是不是当前配置想要的宠物，避免旧结果覆盖新选择。

数据流：进去的是 App、Tui、pet_id 和加载结果 → 它先检查当前配置里的宠物 ID 是否仍然等于这个 pet_id；如果用户已经换了选择，就直接丢弃这个过期结果 → 如果匹配且加载成功，就把宠物对象交给聊天组件并请求重画；如果加载失败，就在界面里显示一条警告。

调用关系：它用于处理“按配置自动加载宠物”的异步结果。它的关键位置是防止后台慢结果污染当前状态；成功时调用 chat_widget.set_tui_pet_loaded 并用 frame_requester 刷新，失败时用 format! 生成警告文字。

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

fn animation_name(self) -> &'static str

作用：把宠物通知类型转换成动画名字。比如“运行中”会对应到名叫 running 的动画。

数据流：进去的是一个通知种类 → 它用固定对应表查出动画名称 → 出来的是一段短字符串，后面会拿这个名字去宠物动画表里找动画。

调用关系：它是状态到动画之间的翻译员；当 AmbientPet::current_animation 要决定当前播放哪套动作时，会需要这种对应关系。

fn label(self) -> &'static str

作用：给通知种类取一个界面上能给人看的短标签。比如 Failed 会显示成 Blocked。

数据流：进去的是通知种类 → 它选择一个固定英文标签 → 出来的是给界面或高度判断使用的文字。

调用关系：它和 notification_height 配合使用：如果通知正文刚好等于这个短标签，就只占一行；否则可能需要两行。测试也会检查这些词和主应用的说法一致。

fn fallback_body(self) -> &'static str

作用：当调用方没有给通知正文时，给它补一个默认说明。这样宠物不会出现空消息。

数据流：进去的是通知种类 → 它按种类挑一句默认正文 → 出来的是可显示的文字，比如 Thinking 或 Ready。

调用关系：PetNotification::new 会用它兜底，保证 set_notification 即使只传状态、不传文字，也能得到完整通知。

fn lifetime(self) -> Duration

作用：规定每种通知最多能显示多久。比如“运行中”很短，“等待输入”和“待审阅”可以留很久。

数据流：进去的是通知种类 → 它返回一个持续时间 → 后面用这个时间判断通知是否过期。

调用关系：PetNotification::is_expired 会调用它；这让不同状态有不同“保质期”，避免旧状态一直挂在屏幕上误导用户。

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

fn new(kind: PetNotificationKind, body: Option<String>) -> Self

作用：新建一条宠物通知，并记下它是什么时候创建的。有人更新宠物状态时会用它。

数据流：进去的是通知种类和可选正文 → 如果正文没有给，就用 fallback_body 补上；同时读取当前时间 → 出来是一条带状态、文字、更新时间的 PetNotification。

调用关系：AmbientPet::set_notification 调用它，把外部传来的状态变成宠物内部能保存和过期判断的通知对象。

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

fn is_expired(&self, now: Instant) -> bool

作用：判断这条通知是不是已经显示太久了。过期后，宠物就不应该继续按这个状态显示。

数据流：进去的是当前时间 → 它用当前时间减去通知更新时间，再和该通知种类的 lifetime 比较 → 出来是真或假，表示是否过期。

调用关系：AmbientPet::visible_notification 会靠它过滤旧通知；它内部调用 PetNotificationKind::lifetime 来知道不同状态该保留多久。

调用图：调用 1 个内部函数（lifetime）；外部调用 1 个（saturating_duration_since）。

fn load(
        selected_pet: Option<&str>,
        codex_home: &std::path::Path,
        frame_requester: FrameRequester,
        animations_enabled: bool,
    ) -> Result<Self>

作用：加载当前选中的宠物，并准备好它要用的图片帧缓存。没有这一步，后面就不知道宠物长什么样、有哪些动画帧。

数据流：进去的是宠物 id、Codex 主目录、刷新请求器和是否允许动画 → 它加载宠物配置，拼出缓存目录，把精灵图拆成 PNG 帧，检测图片显示支持情况，并记录开始时间 → 出来的是一个可以参与绘制的 AmbientPet。

调用关系：它由上层的 load_ambient_pet 调用，是 ambient 宠物进入运行状态的入口；它把宠物模型加载、帧准备、图片协议支持这些零件组装到同一个对象里。

调用图：调用 3 个内部函数（default_image_support, prepare_png_frames, load_with_codex_home）；被 1 处调用（load_ambient_pet）；外部调用 2 个（now, join）。

fn set_notification(&mut self, kind: PetNotificationKind, body: Option<String>)

作用：告诉宠物当前发生了什么事，比如正在运行、等用户输入或失败了。它还会从这一刻重新开始播放对应动画。

数据流：进去的是通知种类和可选正文 → 它创建 PetNotification，并把动画开始时间重置为当前时间 → AmbientPet 内部的 notification 和 animation_started_at 被更新。

调用关系：上层状态变化时会调用它；它把变化交给 PetNotification::new 封装，之后 current_animation 和 current_frame_path 会根据新状态选动画帧。

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

fn image_enabled(&self) -> bool

作用：告诉外部：当前终端能不能显示宠物图片。这样外部可以决定要不要为宠物留位置或发图像请求。

数据流：它读取 AmbientPet 里保存的图片支持信息 → 检查有没有可用协议 → 出来是真或假。

调用关系：它依赖 PetImageSupport 的 protocol 判断；这是一个轻量查询函数，供界面层在绘制前做选择。

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

fn image_columns(&self) -> u16

作用：告诉外部宠物图片大概要占多少终端列。外部布局可以用它避免内容和宠物挤在一起。

数据流：它读取宠物帧宽高 → 调用 image_size 算出显示尺寸 → 出来的是列数。

调用关系：它是 AmbientPet::image_size 的简化出口；当调用方只关心横向占用时，不需要拿完整尺寸。

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

fn set_image_support_for_tests(&mut self, support: PetImageSupport)

作用：测试专用：强行设置终端图片支持情况。这样测试不用真的依赖某个终端环境。

数据流：进去的是一份 PetImageSupport → 它直接替换 AmbientPet 内部的 support → 后续 image_enabled、draw_request 等都会按这份假环境运行。

调用关系：只在测试编译时存在；它让测试可以模拟支持 Kitty、Sixel 或完全不支持图片的情况。

fn schedule_next_frame(&self)

作用：安排下一次动画刷新。动画不是一次画完的，它需要在每帧持续时间结束后再重画。

数据流：它先询问 next_frame_delay 下一帧还要等多久 → 如果有时间，就交给 FrameRequester 安排未来刷新 → 它本身不返回绘制结果，只触发调度。

调用关系：主循环画完一帧后可以调用它；它把“什么时候该再画”这件事交给 frame_requester 的 schedule_frame_in。

调用图：调用 2 个内部函数（next_frame_delay, schedule_frame_in）。

fn next_frame_delay(&self) -> Option<Duration>

作用：算出距离下一张动画帧还有多久。如果终端不能显示图片，或用户关闭动画，就不需要安排下一帧。

数据流：它读取图片协议支持、动画开关、当前动画和已经播放的时间 → 找到当前帧，并拿到这帧剩余时间 → 出来是一个可选的等待时间。

调用关系：AmbientPet::schedule_next_frame 调用它；它会继续调用 current_animation 和 current_animation_frame，把状态选择和逐帧计时连起来。

调用图：调用 3 个内部函数（current_animation, current_animation_frame, protocol）；被 1 处调用（schedule_next_frame）；外部调用 1 个（elapsed）。

fn draw_request(
        &self,
        area: Rect,
        composer_bottom_y: u16,
    ) -> Option<AmbientPetDraw>

作用：为主界面生成一次宠物绘制请求。它会确保宠物贴在输入框上方，不盖住保留区域。

数据流：进去的是可绘制区域和输入框底部位置 → 它检查终端图片协议、计算图片大小、通知高度和间距，再选当前帧路径 → 如果空间足够，出来一个 AmbientPetDraw；如果不够或不能显示图片，就返回空。

调用关系：主界面每次绘制时会用它拿到“该把哪张图放在哪里”；它调用 current_frame_path、image_size、visible_notification 和 composer_gap_rows，把动画、尺寸和布局合成一个请求。

调用图：调用 5 个内部函数（current_frame_path, image_size, visible_notification, composer_gap_rows, protocol）；外部调用 2 个（now, clone）。

fn preview_draw_request(&self, area: Rect) -> Option<AmbientPetDraw>

作用：为 /pets 选择面板生成居中的宠物预览图。它故意用 idle 的第一帧，让用户浏览时画面稳定不乱跳。

数据流：进去的是预览区域 → 它检查图片协议和区域大小，计算居中坐标，并取第一张 idle 帧 → 空间够就返回 AmbientPetDraw，不够就返回空。

调用关系：宠物选择器侧边栏会用它；它不像 draw_request 那样跟随实时通知，而是调用 first_idle_frame_path 保持预览固定。

调用图：调用 3 个内部函数（first_idle_frame_path, image_size, protocol）；外部调用 1 个（clone）。

fn visible_notification(&self, now: Instant) -> Option<&PetNotification>

作用：取出当前还没过期的通知。过期通知会被当作不存在。

数据流：进去的是当前时间 → 它查看内部 notification，并用 is_expired 判断是否仍有效 → 出来是通知引用，或没有通知。

调用关系：AmbientPet::draw_request 用它计算通知占用高度；AmbientPet::current_animation 用它决定播放 idle 还是状态动画。

调用图：被 2 处调用（current_animation, draw_request）。

fn current_animation(&self) -> Option<&Animation>

作用：决定宠物现在应该播放哪套动画。优先看有效通知；没有通知就播放 idle。

数据流：它读取当前通知、宠物动画表和动画已播放时间 → 按通知种类找动画，找不到就退回 idle；如果一次性动画播完且有 fallback，就切到 fallback 动画 → 出来是一套 Animation。

调用关系：AmbientPet::current_frame_path 和 AmbientPet::next_frame_delay 都依赖它；它是“状态”到“动画”之间的核心选择器。

调用图：调用 1 个内部函数（visible_notification）；被 2 处调用（current_frame_path, next_frame_delay）；外部调用 2 个（elapsed, now）。

fn current_frame_path(&self) -> Option<PathBuf>

作用：找出当前这一刻应该显示哪一个图片文件。它把动画进度转换成真实 PNG 帧路径。

数据流：它先拿 current_animation → 如果动画开启，就按 elapsed 时间找当前帧；如果关闭，就固定用动画第一帧 → 再把 sprite_index 转成缓存里的文件路径。

调用关系：AmbientPet::draw_request 调用它来填 AmbientPetDraw.frame；它把 current_animation 和 frame_path_for_sprite_index 串起来。

调用图：调用 2 个内部函数（current_animation, frame_path_for_sprite_index）；被 1 处调用（draw_request）。

fn first_idle_frame_path(&self) -> Option<PathBuf>

作用：取 idle 动画的第一帧图片。主要用于稳定预览，不用于实时动画播放。

数据流：它读取宠物动画表里的 idle 动画 → 找第一帧的 sprite_index，找不到就用 0 → 再转成实际帧文件路径。

调用关系：AmbientPet::preview_draw_request 调用它；它和 current_frame_path 的区别是完全不看通知和时间。

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

fn frame_path_for_sprite_index(&self, sprite_index: usize) -> Option<PathBuf>

作用：把精灵图里的帧编号转换成已经拆出来的 PNG 文件路径。编号越界时会夹到最后一张，避免崩掉。

数据流：进去的是 sprite_index → 它在 frames 列表里取对应文件；如果编号太大，就取最后一个可用位置 → 出来是路径副本，或没有路径。

调用关系：AmbientPet::current_frame_path 和 AmbientPet::first_idle_frame_path 都调用它；它是动画帧编号到磁盘缓存文件之间的小桥。

调用图：被 2 处调用（current_frame_path, first_idle_frame_path）。

fn image_size(&self) -> ImageSize

作用：计算宠物在终端里应该占多少列、多少行，以及图片高度像素。这样布局和图片协议能说同一种尺寸。

数据流：它读取宠物原始帧宽高和固定目标高度 → 按终端行高估算行数，再按宽高比例估算列数 → 出来是 ImageSize。

调用关系：draw_request、preview_draw_request 和 image_columns 都会调用它；它保证主界面和预览使用同一套尺寸算法。

调用图：被 3 处调用（draw_request, image_columns, preview_draw_request）；外部调用 1 个（from）。

fn composer_gap_rows() -> u16

作用：把宠物和输入框之间的像素间距换算成终端行数。简单说，就是留一条安全缝。

数据流：它读取固定的像素间距和终端行高 → 做四舍五入，并保证至少一行 → 出来的是需要空出来的行数。

调用关系：AmbientPet::draw_request 调用它；这个间距让宠物不会紧贴或压住 composer 输入区。

调用图：被 1 处调用（draw_request）；外部调用 1 个（from）。

fn default_image_support() -> PetImageSupport

作用：给 AmbientPet 一个默认的图片显示能力判断。正常运行时会自动选择可用协议；测试版本会默认说不支持，避免依赖真实终端。

数据流：在对应编译环境里，它生成一份 PetImageSupport → load 把这份结果存进 AmbientPet → 后续绘制都以它为准。

调用关系：AmbientPet::load 调用它；它是宠物图片能不能显示、用什么协议显示的默认来源。

调用图：被 1 处调用（load）；外部调用 1 个（Unsupported）。

fn current_animation_frame(animation: &Animation, elapsed: Duration) -> Option<AnimationFrameTick>

作用：根据动画已经播放了多久，算出现在应该是哪一帧，以及多久后需要换下一帧。

数据流：进去的是一套 Animation 和 elapsed 时间 → 它处理单帧、循环动画、非循环动画结束等情况 → 出来的是 AnimationFrameTick，里面有帧编号和下一次刷新延迟。

调用关系：AmbientPet::next_frame_delay 用它安排刷新；current_frame_path 也通过同样思路选择帧。它会把具体逐帧查找交给 frame_at_elapsed。

调用图：调用 2 个内部函数（frame_at_elapsed, total_duration）；被 1 处调用（next_frame_delay）；外部调用 1 个（as_nanos）。

fn frame_at_elapsed(animation: &Animation, elapsed_nanos: u128) -> Option<AnimationFrameTick>

作用：在一串动画帧里，根据经过的时间找到落在哪一帧。可以把它想成拿秒表从第一张图一路数过去。

数据流：进去的是动画和纳秒数 → 它逐帧扣掉每帧时长，直到找到当前时间所在的帧 → 出来的是帧编号和这一帧还剩多久。

调用关系：current_animation_frame 在处理普通播放和循环播放时都会调用它；它再调用 nanos_to_duration 把纳秒差值变回 Duration。

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

fn nanos_to_duration(nanos: u128) -> Duration

作用：把纳秒数字安全地转换成 Duration 时间对象。它会防止数字太大超过系统能表示的范围。

数据流：进去的是 u128 纳秒数 → 它把数值限制到 u64 最大值以内 → 出来的是 Duration。

调用关系：frame_at_elapsed 用它生成“还要等多久换帧”的时间；这是动画计时里的安全转换小工具。

调用图：被 1 处调用（frame_at_elapsed）；外部调用 2 个（from_nanos, from）。

fn notification_height(notification: &PetNotification) -> u16

作用：估算通知文字在宠物旁边或上方需要占几行。短标签占一行，带额外正文时占两行。

数据流：进去的是一条 PetNotification → 它比较正文是否等于该状态的短标签 → 出来是 1 或 2 行高度。

调用关系：AmbientPet::draw_request 用它计算总共需要给宠物和通知留多少竖向空间，避免画面压到输入框。

fn test_ambient_pet(
    frame_requester: FrameRequester,
    animations_enabled: bool,
) -> AmbientPet

作用：测试专用：快速造一个假的 AmbientPet。这样测试不用读取真实宠物文件，也不用真的拆图片。

数据流：进去的是测试用 FrameRequester 和动画开关 → 它手工填好宠物信息、两张帧路径、图片协议和动画开始时间 → 出来是可直接测试的 AmbientPet。

调用关系：reduced_motion_uses_stable_first_frame_and_schedules_no_follow_up 测试会调用它；它还调用 test_animation 准备最小动画数据。

调用图：调用 1 个内部函数（test_animation）；被 1 处调用（reduced_motion_uses_stable_first_frame_and_schedules_no_follow_up）；外部调用 8 个（from_millis, from, now, from, new, new, Supported, vec!）。

fn test_animation() -> Animation

作用：测试专用：创建一个很小的两帧循环动画。它让动画时间计算可以被简单验证。

数据流：它不需要外部输入 → 生成两帧，每帧 10 毫秒，并设置从第 0 帧开始循环 → 出来是一份 Animation。

调用关系：test_ambient_pet 和 animation_frame_uses_per_frame_duration 测试都会用它；它提供稳定、可预期的动画样本。

调用图：被 2 处调用（test_ambient_pet, animation_frame_uses_per_frame_duration）；外部调用 1 个（vec!）。

fn notification_labels_match_codex_app_vocabulary()

作用：测试宠物通知标签是否和 Codex 应用里的用词一致。这样界面不会一处叫 Ready，另一处叫别的名字。

数据流：它读取各个 PetNotificationKind 的 label → 和预期字符串逐个比较 → 如果不一致，测试失败。

调用关系：这是对 PetNotificationKind::label 的保护网；以后有人改文案时，会立刻看到是否破坏了统一用词。

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