本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。英文原文

终端渲染

状态：当前范围：TUI 终端配置档选择、覆盖，以及视觉能力边界最近审阅：2026-10-03 负责人：AX Code TUI 维护者

AX Code 在启动时根据环境选择终端配置档。该配置档控制终端设置，而不是显示器分辨率或字体锐度。

终端环境	自动配置档	识别
Windows Terminal，包括 WSL 中的 Ubuntu	高级	非空的 `WT_SESSION`，且没有冲突的 `TERM_PROGRAM`
GNOME Terminal 以及其他 VTE 宿主	高级	正十进制的 `VTE_VERSION`、`TERM=xterm` 或 `xterm-256color`，且没有冲突的 `TERM_PROGRAM`
Ghostty	高级	`TERM_PROGRAM=ghostty` 或 `TERM=xterm-ghostty`
macOS Terminal.app	兼容	`TERM_PROGRAM=Apple_Terminal`
未知终端、SSH/mosh、tmux、screen 和 Zellij	兼容	保守回退

显式的 TERM_PROGRAM 优先于继承来的外层终端标记。dumb、linux 和 vt100 这类受限终端类型也保持兼容。仅有 Ubuntu 或 WSL 身份并不会启用高级配置档。

高级配置档使用备用屏幕、原生渲染线程，以及终端能力检测。兼容配置档使用主屏幕，并且没有原生渲染线程。两者都启用鼠标交互（见鼠标捕获）和键盘协议协商，目标是 60 FPS；实际帧率取决于工作负载和终端。

当 Windows Terminal 的直接会话被识别出来时，两种配置档都会保留 24 位视觉效果。颜色支持并不意味着像素图形或 Nerd Font 支持。高级模式不会改变字体、字号或显示缩放。

鼠标捕获

AX Code 默认捕获终端鼠标输入，以便 TUI 内的控件保持可点击：页脚快捷芯片（快速模型、自主、沙盒）、对话框和自动完成选项、点击聚焦、拖拽选择，以及 TUI 内的滚轮滚动。捕获开启时，终端把鼠标交给正在运行的程序，因此不会显示终端自己的右键菜单和原生文本选择。许多终端仍然可以用修饰键露出它们 — 通常是 Shift 加右键，有时是 Option 或 Alt — 具体取决于终端，以及 tmux、screen 或 Zellij 是否夹在中间。

把 mouse 设为 false，写在 tui.json 中，即可把鼠标交还终端：

{
  "mouse": false
}

AX_CODE_DISABLE_MOUSE=1 会禁用捕获，无论 tui.json 如何。它之所以存在，是因为项目级的 tui.json 文件是不受信任的输入：仓库不得违背用户意愿，持续抑制终端自己的鼠标行为。该变量只能禁用捕获；它永远不能强制开启捕获。

选择退出是一种取舍，并不是纯粹的好处：

换回的：终端原生的右键菜单、原生文本选择，以及复制/粘贴。在兼容配置档中，终端自己的回滚缓冲区处理滚轮。
失去的：页脚快捷芯片、点击聚焦、可点击的对话框和自动完成选项、拖拽选择，以及 — 在高级（备用屏幕）配置档中，它没有终端回滚缓冲区 — TUI 内的滚轮滚动。键盘控件对这些操作仍然可用。

捕获开启时，右键打开的是 TUI 自己的上下文菜单，而不是终端的：点击位置上的一个小型复制 / 粘贴菜单。屏幕上有选区时启用复制，文本输入获得焦点时启用粘贴 — 包括提示以及对话框内的输入。菜单会在 Escape、任意按键、滚动，或点击菜单外部时关闭。一旦关闭捕获，就由终端来处理这次点击。

覆盖配置档

把 AX_CODE_TUI_ADVANCED_TERMINAL=1 设为请求高级模式，或把 0 设为请求兼容模式。显式覆盖优先于自动检测，包括远程和多路复用会话。去掉该变量即可恢复自动选择。true/false、yes/no 和 on/off 也会被接受。

PowerShell，用于当前 shell 及其子进程：

$env:AX_CODE_TUI_ADVANCED_TERMINAL = "1"
ax-code

# Use compatible mode if startup or rendering has problems.
$env:AX_CODE_TUI_ADVANCED_TERMINAL = "0"
ax-code

# Restore automatic selection.
Remove-Item Env:AX_CODE_TUI_ADVANCED_TERMINAL -ErrorAction SilentlyContinue

Bash 或 Zsh，用于单次启动：

AX_CODE_TUI_ADVANCED_TERMINAL=1 ax-code
AX_CODE_TUI_ADVANCED_TERMINAL=0 ax-code

如果 shell 启动文件导出了该变量，请去掉该导出并运行 unset AX_CODE_TUI_ADVANCED_TERMINAL，以恢复自动选择。

像素动画

只有当渲染器确认 Kitty 图形、有效的像素尺寸、本地 TTY、备用屏幕，并且没有多路复用器时，开场和结束动画才使用像素。缺少能力或图形失败时使用文本回退。自动高级模式不会绕过这些检查。

全部像素动画帧 — Digital Code、Foliage，以及地标场景 — 都限制在 1920x1080。这些动画帧按 20 FPS 的日程更新，与渲染器 60 FPS 的目标分开。预览见 TUI 开场与结束动画。

已确认支持 Sixel（且没有 Kitty 图形）的 Windows Terminal 会话会显示一帧静态 Sixel 启动画面，限制在 640x360 和 256 KiB，而不是文本回退。AX_CODE_SIXEL_SPLASH=0 会禁用它；=1 允许任何 Sixel 终端显示它（测试路径）。拆除时会用叠加背景重绘启动画面区域，因为 Sixel 没有按图像 id 删除的能力。

Windows Terminal 字体

AX Code 不能更改终端字体。文件类型图标（Nerd Font 专用区字形）只有在安装了修补字体之后，才会在 Windows Terminal 中渲染。推荐字体是 Cascadia Code NF：安装它，然后在设置 > 配置文件 > 外观 > 字体中把它设为配置档字体。一次性的应用内提示会把 Windows Terminal 用户指向这项设置；当图标已经能渲染，或当 AX_CODE_NERD_FONT=0 选择退出时，它绝不会显示。