3 · 终端用户界面（TUI）（Terminal User Interface (TUI)）

终端用户界面（TUI）

终端用户界面（TUI）

相关源文件

本章引用的主要源码文件：

• src/bin/tui_bench.rs
• src/tui/app.rs
• src/tui/app/commands.rs
• src/tui/app/input.rs
• src/tui/app/local.rs
• src/tui/app/remote.rs
• src/tui/app/remote/key_handling.rs
• src/tui/app/remote/server_events.rs
• src/tui/app/state_ui.rs
• src/tui/app/tests.rs
• src/tui/app/tui_lifecycle.rs
• src/tui/app/tui_state.rs
• src/tui/app/turn.rs
• src/tui/info_widget.rs
• src/tui/markdown.rs
• src/tui/mermaid.rs
• src/tui/mod.rs
• src/tui/ui.rs
• src/tui/ui_overlays.rs

jcode TUI 是一个基于 ratatui 构建的高性能终端界面。它提供了一个多面板环境，支持实时流式 Markdown 渲染、交互式差异对比、动画状态头部以及集成的 Mermaid 图表渲染。该 TUI 通过采用多阶段渲染管线（pipeline）和激进缓存策略，即使在大量 LLM 流式输出或复杂工具执行期间也能保持响应流畅。

系统架构

TUI 架构以 App 结构体为核心，它负责管理终端事件循环、应用程序状态以及渲染管线之间的关系。

TUI 组件层级结构

来源： src/tui/app.rs:41-91, src/tui/mod.rs:105-180, src/tui/ui.rs:63-102

核心组件

3.1 应用状态与事件循环

App 结构体是 TUI 的主要入口点 src/tui/app.rs:99-300。它实现了 TuiState 特质 src/tui/mod.rs:105-180，该特质将应用程序的内部数据抽象为共享渲染器可消费的格式。事件循环通过 Bus 处理来自智能体的异步更新，并通过 crossterm 处理用户输入 src/tui/app.rs:23-26。

• 处理状态： UI 通过 ProcessingStatus 枚举跟踪智能体的生命周期，包括 Idle（空闲）、Sending（发送中）、Connecting（连接中）、Thinking（思考中）、Streaming（流式输出中）和 RunningTool（运行工具中）src/tui/app.rs:32。
• 输入管线： 支持多行输入、撤销缓冲区 src/tui/app.rs:121-126 以及"队列/交错"模式，用于管理多个待处理提示 src/tui/app.rs:52190-52190。
• 语音输入： 集成本地语音输入支持，允许将语音转文本直接输入到聊天缓冲区中 src/tui/app.rs:62-62。

详情请参见 应用状态与事件循环。

来源： src/tui/app.rs:1-91, src/tui/mod.rs:105-180, src/tui/app/tui_lifecycle.rs:5-72

3.2 渲染管线与 UI 组件

TUI 使用定义在 src/tui/ui.rs 中的多阶段渲染管线，即使在消息历史很长的情况下也能保持 60 FPS 的帧率。它利用 BODY_CACHE 缓存预渲染的 Markdown 片段，并根据终端尺寸动态计算布局。

• 布局区域： 屏幕分为主聊天视口、可选的侧面板（用于差异对比/内容）以及浮动 InfoWidget 面板 src/tui/info_widget.rs:70-102。
• 色波动画： ui_header.rs 中的专用头部动画在 LLM "思考"阶段提供视觉反馈 src/tui/ui.rs:77-78。
• 侧面板： 支持分屏视图、用于实时文件跟踪的观察模式以及专用的待办事项视图 src/tui/ui.rs:85-88。

详情请参见 渲染管线与 UI 组件。

来源： src/tui/ui.rs:106-165, src/tui/info_widget.rs:104-141, src/tui/ui.rs:63-102

3.3 Markdown 与 Mermaid 渲染

IncrementalMarkdownRenderer 允许 TUI 安全地渲染部分 LLM 响应，而无需重新解析整个对话 src/tui/markdown.rs:1-8。

• Mermaid 集成： Mermaid 图表通过 jcode-tui-mermaid 渲染为 PNG，并使用终端特定协议（Kitty、Sixel 或 iTerm2）显示 src/tui/mermaid.rs:1-16。
• 自适应尺寸： 渲染器使用超采样和自适应尺寸，确保图表在不同终端字体大小下保持清晰可读 src/tui/ui.rs:126-129。

详情请参见 Markdown 与 Mermaid 渲染。

来源： src/tui/markdown.rs:43-59, src/tui/mermaid.rs:1-16, src/tui/ui.rs:104-104

3.4 会话选择器与账户选择器

这些专用覆盖层允许用户管理多个智能体上下文和提供商凭证。

• 会话选择器： 一个双面板界面，用于浏览按服务器分组的历史会话 src/tui/app.rs:212-219。它包含所选会话的实时预览渲染。
• 账户选择器： 一个快速访问菜单，用于在 LLM 提供商或特定已保存账户之间切换 src/tui/mod.rs:1-1 src/tui/app.rs:53-53。

详情请参见 会话选择器与账户选择器。

来源： src/tui/app.rs:212-226, src/tui/mod.rs:1-21, src/tui/app/remote.rs:77-77

3.5 远程连接与多会话工作区

TUI 支持通过 RemoteConnection 连接到远程 jcode 服务器 src/tui/app/remote.rs:11-15。它管理这些连接的生命周期，包括带退避策略的自动重试以及在服务器重新加载期间的"交接"检测 src/tui/app/remote.rs:31-36。

• 工作区导航： 一个水平工作区地图（可通过 /workspace 访问），允许用户在同一服务器上的不同活动会话之间跳转 src/tui/mod.rs:28-30。
• 远程差异跟踪器： 同步远程智能体与本地 TUI 显示之间的文件更改，以驱动侧面板的差异对比视图 src/tui/mod.rs:19-19。

详情请参见 远程连接与多会话工作区。

来源： src/tui/app/remote.rs:63-126, src/tui/app/remote/workspace.rs:25-25, src/tui/workspace_client.rs:28-28

3.6 斜杠命令与内联交互

TUI 提供丰富的斜杠命令集（例如 /improve、/refactor、/review），这些命令会触发复杂的智能体工作流 src/tui/app/commands.rs:1-20。

• 内联交互： 用于模型选择、会话选择和预览请求的选择器覆盖层被实现为交互式组件，不会打断聊天流程 src/tui/app.rs:66-66。

详情请参见 斜杠命令与内联交互。

来源： src/tui/app/commands.rs:1-20, src/tui/app/inline_interactive.rs:66-66

UI 实体映射

下表将逻辑 UI 区域映射到其主要的实现文件和代码实体。

来源： src/tui/ui.rs:63-102, src/tui/info_widget.rs:70-102