窗口
文档编写中
部分内容可能尚不完整。
窗口分三块：左边是承载工作区的侧边栏，中间是终端区域，右边是可选的面板。终端本身来自 WezTerm，渲染、字体和转义序列由它的文档原样覆盖。下面讲的是它周围的那一圈。
侧边栏
侧边栏装着工作区：当前显示的 Space、它的 Project，以及每个 Project 里的 Thread。这套模型和其中的每个菜单见 Space、Project 与 Thread；这里只讲布局。
最上方有一个按钮，写着当前 Space 的名字，点开是 Space 菜单。菜单先列出本机的 Space，再按远程服务端分组列出各自的 Space，组名是服务端名字和连接状态，每组都带一个 在此服务器新建空间。已经在另一个窗口里打开的 Space 会标为已被占用，选不了，因为一个 Space 同一时间只在一个窗口里显示。同一个菜单里还有 添加远程主机…、新建空间、重命名当前 Space，以及移除它或另一个 Space。
下面是这个 Space 的 Project，各自带着自己的 Thread。置顶的 Thread 会离开所属 Project 的列表，进入 Space 顶部唯一的 已置顶 区，这个区汇集了 Space 里所有 Project 的置顶。置顶的 Thread 不能拖动排序；已归档 Project 的置顶在它取消归档之前不会出现在这个区里。Thread 也可以标记为未读。
每个 Thread 带着一个实时状态，所以这份列表本身就回答了「哪些会话在干活、哪些在等你」，不必逐个点开 —— 这个状态是怎么判定的，见 Agent 状态。
侧边栏收起时，把指针停在窗口左缘，或者停在侧边栏按钮上，它就会盖在终端上方滑出来，指针离开后再收回。下面的终端既不移动也不改变大小，所以里面运行的程序不会察觉到尺寸变化。从滑出的侧边栏里打开的菜单或重命名，会让它一直留着，直到你操作完。
窗口标签与 pane 标签
标签分两层，值得分清。
窗口顶部那一排是窗口标签。每个窗口标签是一整套布局 —— 一个终端，或者左右、上下分屏的好几个 —— 切换窗口标签就是整套布局一起换掉。
布局里的每一格上方都有自己的一条标签：一个 pane 栈。栈里的标签是轮流占用这一格的多个终端，所以一格里可以放好几个 shell，而不必再分屏。这条标签末尾的按钮分别用来在栈里新建标签、把这一格向下或向右分屏，以及把它放大到占满整个窗口标签；双击标签条的空白处也会在那里新建标签。如果这一格处在上下分屏中，还有一个按钮可以把它折叠成只剩标签条，把空间让给其余部分，每个窗口标签同时只能折叠一格。
pane 标签可以拖到某一格上。放在格子中间，它加入那一格的栈；放在靠近边缘处，它在那一侧把格子分开，占据新的一半。松手之前会有高亮显示结果。
在窗口标签上右键，有这些项：
| 菜单项 | 作用 |
|---|---|
重命名标签页… | 给窗口标签命名 |
关闭左侧标签页、关闭右侧标签页、关闭其他标签页 | 关闭这些窗口标签，不会先询问 |
标签页左移、标签页右移 | 在这一排里移动一格 |
在右侧新建终端标签页 | 在它旁边打开一个窗口标签，与它当前的终端在同一台机器上 |
放大窗格 | 把这个窗口标签里的当前格放大占满，或者还原 |
在 pane 标签上右键，可以给这个标签重命名。
在终端里右键，有 复制、粘贴、编辑录屏遮挡… 和 清除录屏遮挡（见 录屏遮挡）、向右分屏、向左分屏、向下分屏、向上分屏，以及 重置终端。最后一项 Frontend access 在 A · Shared (tmux-like) 和 B · Handoff (exclusive) 之间选择 —— 多台设备可以同时操作这个终端，还是一次只能一台 —— 详见 网页访问。终端里的程序捕获了鼠标时，右键时按住 Shift。
标签图标
每个 pane 标签都带着一个图标，表示这个 pane 正在运行什么：Claude Code、Codex、Python、Neovim、Docker、一个 SSH 会话，等等；shell 或者没有图标认领的程序，显示普通的终端标记。pane 正在干活时，图标让位给一个转圈。顶部那一排窗口标签里装着好几个 pane，各自可能跑着不同的东西，所以它们始终显示终端标记。
pane 在运行什么，是从掌管它终端的那个程序推断出来的：在 pane 输出或改标题时才去看，而不是定时轮询，而且变化要保持半秒才算数 —— 一闪而过的命令不会让图标跟着闪。启动器和解释器会被看穿：sudo vim 显示 Vim，Python 或 Node 跑的脚本先按脚本名来认，认不出才退回解释器本身。ThinkTerm Connect 服务端上的 pane 由那台服务端观察，再报告给每个客户端，所以远程标签显示的图标和本地的一样。
走普通 SSH 时，本地掌管终端的程序就是 ssh 自己，标签只能显示 SSH 图标。普通 SSH 主机设置里的 识别远端程序 让远端 shell 自己报告正在运行什么：下次连接时，ThinkTerm 在那台主机的 bash 或 zsh 启动文件里加一行；关掉它，再下一次连接时删掉那一行。其他登录 shell 会被报告为不支持，什么都不改动。
那一行做的事，是在每条命令执行前把 WEZTERM_PROG 用户变量设为这条命令行，回到提示符时再清空。所以它没覆盖到的 shell，比如 fish，只要照样这么做，也能报告自己运行的程序。这个报告只在终端位于另一台机器上时才算数；对本地程序，以 ThinkTerm 自己看到的为准。
设置 › 标签图标 可以关掉这些图标，关掉后每个标签都回到终端标记；这一页还把图标本身排成一格格可搜索的卡片。一张卡片列出它认领的程序名，它的形状和颜色都可以改：选一个 SVG，或者把 .svg 文件拖到卡片上，再设置底色和图案颜色。导入的 SVG 最大 256 KB；ThinkTerm 会在 ~/.config/thinkterm/tab-icons/ 里存一份副本，以它的哈希命名，所以移动或删除原文件不会丢掉图标。内置卡片可以重置回出厂的样子；自己的卡片最多 64 张，可以新建和删除。一个程序名同一时刻只属于一张卡片，所以把它加到某张卡片上，就会把它从原来那张上拿走。终端卡片是固定的，不出现在这里。
WezTerm 的标签栏
无论配置怎么写，ThinkTerm 自己的那排标签都留在窗口顶部。WezTerm 的标签栏选项 —— enable_tab_bar、use_fancy_tab_bar、tab_bar_at_bottom、hide_tab_bar_if_only_one_tab 等等 —— 改为驱动终端区域里另一条一行高的栏，位于 pane 标签之下，或者沿着底边。
use_fancy_tab_bar = false 时，这条栏显示 WezTerm 的复古式标签，format-tab-title 和标签栏配色都作用在它上面。保持默认的 fancy 标签栏时，它在设置状态文字之前不会出现，比如用 window:set_right_status；一旦出现就一直占着这一行，所以时有时无的状态文字不会反复改变终端大小。enable_tab_bar = false 则把它彻底去掉。
Live Overview
标签栏没法告诉你十几个会话里哪个正在动，Live Overview 可以：它把每个活着的 Thread 摆成一张卡片，按所属 Space 分组，最多五列。
每张卡片显示那个终端此刻的样子，上方浮着一枚胶囊，写着 Thread 的名字和正在运行的命令。胶囊上还为 Thread 工作区里的每个标签各点一个点，跨越它的所有窗口：标签里有命令在运行时是蓝色，卡片上次显示它之后有新输出时更亮，空闲时偏淡，卡片当前显示的那个标签最大。把指针停在某个点上，卡片就预览那个标签；点一下，就在那个标签上打开这个 Thread。超过六个标签时，点会折叠成三个加一个计数，指针在上面停一会儿就会展开。
当前离线的机器仍然留在网格里，而不是从中消失，所以笔记本睡过去时，一个 Space 不会整个空掉。
如果那里还有东西在运行，关闭一张卡片会先询问，因为这会结束那个终端里的每一个分屏和正在运行的程序。
两套颜色
ThinkTerm 画两套调色板，分清哪套是哪套是值得的。
程序用来画字的那套是终端的：WezTerm 的 colors 和 color_scheme，文档在上游。ThinkTerm 多加了一种在配置文件之外选配色方案的办法，以及一个跟浅色界面配套的默认值，两者都可能挡在配置文件前面。
设置 › 外观 › 当前配色方案 显示终端当前用的配色方案。点它会在一个终端窗口里打开命令面板的 更换主题 列表，你在列表里移动时终端会跟着重画。在这里选的方案，或者直接在命令面板的 更换主题 里选的，会存进 settings.json，作用于所有窗口，并且压过配置文件里的 color_scheme —— 于是改那一行看起来毫无作用，直到你选同一列表最上面的 使用配置默认值，把选择交回给文件。配置文件里的 colors 仍然叠加在当前生效的方案之上。
什么都没选时，浅色界面会把终端画成 Apple System Colors (Light)，除非配置文件自己指定了方案或设置了 colors，这样浅色窗口里就不会出现为黑底挑选的文字颜色。深色界面则交给配置文件决定。
ThinkTerm 画在终端周围的那套是自己的 —— 侧边栏、标签栏、每个 pane 上方的条、设置窗口、菜单 —— ui_colors 可以逐项覆盖它们，可用的项列在 配置 里。设置 › 外观 › 主题 提供四种模式：跟随系统、浅色、深色（默认），以及 跟随终端配色，后者把整个界面挪到终端当前配色方案的背景上。在 跟随终端配色 下不会替你选方案：那里是方案决定界面，而不是反过来。
终端文字可以被要求与背景之间保持最低对比度，这样把深灰画在黑底上的配色仍然读得清。设置 › 终端 › 最低文字对比度 提供 3:1、4.5:1 和 7:1，默认关闭，因为提高对比度也会把程序有意调暗的东西拉平 —— 禁用的菜单项、进度条未填满的那一半、注释。关闭时由 WezTerm 自己的 text_min_contrast_ratio 选项决定，它在你于配置文件里设置之前是空的；在设置里选了比例的话，以设置为准。
界面字号
ThinkTerm 自己的文字与终端文字分开设定大小。设置 › 外观 › 字体排版 为六个位置各提供一个步进器，范围 10 到 28，上方有一幅窗口小图，会点亮某一行所作用的部分：
| 设置 | 作用于 |
|---|---|
设置界面字号 | 设置窗口 |
主页字号 | 主页和主内容区 |
右侧栏字号 | 文件、笔记和片段；未设置时跟随 主页字号 |
工作区侧栏字号 | 左边的侧边栏 |
标签栏字号 | 顶部的窗口标签 |
窗格标题字号 | 各条 pane 标签 |
设置界面字重 决定设置窗口文字的粗细，从 300 到 800，每档 100。每一行都可以单独重置。终端的字体和字号在 设置 › 终端 和配置文件里 —— 见 配置。
应用图标
设置 › 外观 › 应用图标 在 简约（默认）和 经典 之间切换运行中的应用在程序坞和应用切换器里显示的图标。仅在 macOS 上有效。
滚动
回滚按像素移动，而不是按行：触控板或触摸拖动跟着手指走，而不是一次跳一行。设置 › 终端 › 滚动方式 在 平滑（默认）和 逐行（一次移动一整行）之间切换。
每个 pane 在滚动时都会在右缘画出一条细滚动条，随后淡出 —— 不只是当前聚焦的那个。它可以拖动。设置 › 终端 › 滚动条 可以关掉它。配置文件里写了 enable_scroll_bar = true 时，不管这个开关怎么设，它都会换成 WezTerm 自己的滚动条，即当前聚焦 pane 旁边的一条边栏。
底部语录
设置 › 终端 › 底部语录 在终端区域右下角显示一行短文字，默认关闭。它不占终端的地方：只画在最后一整行下面剩出的空隙里；如果空隙太窄 —— 窗口高度刚好是整数行 —— 就什么都不显示。语录字号 改变它的大小，而不改变终端的布局。
语录来自 ~/.config/thinkterm/bottom_quotes.json，是一组对象，每个有 text，author 可选：
[
{ "text": "Ship the small version first.", "author": "A colleague" },
{ "text": "Read the error message." }
]第一次要显示语录时，这个文件会带着一份初始列表被创建出来，语录文件 › 打开 可以打开它。文件保存后，改动就会被读到。语录轮换 选 顺序 就按列表顺序走，选 随机 就随机挑一条；语录间隔 决定多久换一次，从 1 分钟到 24 小时，默认一小时。轮换跟着时钟走，所以每个窗口显示的都是同一条。重置语录 JSON 用出厂列表覆盖这个文件，要按第二下才生效，因为你写在里面的内容会丢失。
终端里的图片
程序可以用 Kitty 图形协议、iTerm2 的内联图片或 Sixel 在终端里画图，和在 WezTerm 里一样。
终端也保存 Kitty 协议里较新的部分 —— Unicode 占位符、相对于其他图片放置的图片，以及动画 —— 但桌面窗口目前还不画这些。在浏览器里打开的终端会画；见 网页访问。反过来，浏览器不显示通过 iTerm2 协议发送的 PNG 或 JPEG。
每个 pane 最多保留 128 MiB 的 Kitty 图片数据，由 kitty_image_memory_budget_mib 设定，0 表示不限。超出时，先丢不在屏幕上的图片，从最旧的开始；如果光是屏幕上的就已超出，最久没放置过的也会从屏幕上拿掉，但最新的那张不会。单个动画最多保留 256 MiB，预算更小则以预算为准。
录屏遮挡
录屏或共享屏幕时，录屏遮挡用一块不透明的黑色矩形盖住终端的一部分。在终端上右键，选 编辑录屏遮挡… —— 如果里面的程序捕获了鼠标，右键时按住 Shift。拖动空白处画出一块遮挡，拖动遮挡块移动它，拖动它的右下角调整大小。完成 或 Esc 让终端回到正常输入；同一个菜单里的 清除录屏遮挡 把它们全部去掉。
遮挡属于某一个 pane，最多 64 块，并且固定在 pane 内的位置上：文字滚动时它们不跟着走，所以滚动或重新排布窗口之后，请检查一下录制画面。它们会随 pane 在窗口之间移动，也会出现在它的 Live Overview 卡片上。它们只存在于这一个 ThinkTerm 里 —— 接入同一会话的其他客户端收不到 —— pane 关闭或 ThinkTerm 退出时就没了。
遮挡盖住的是画面，不是内容。下面的文字仍然在终端里，在你复制出来的内容里，在日志里，也在接入同一会话的其他每个客户端上。
右侧面板
终端右边的面板装着文件、笔记和片段，详见 文件与笔记，以及 Agent 状态 里讲的 Agents 面板。安装的插件可以在这些之后加上自己的面板 —— 见 插件。片段本身就是一个内置插件。
设置 › 侧栏与插件 逐个开关这些面板，并列出已安装的插件。所有面板都关掉时，右侧栏本身就消失了。
右侧栏收起后，也能像左边那样叫回来：把指针停在窗口右缘，或者停在它的按钮上，它就盖在终端上方滑出来，不改变终端大小。
窗口在哪里打开
设置 › 通用 › 恢复主窗口位置与大小 会让主窗口按你上次离开时的大小和位置重新打开，macOS 和 Windows 上都有效。
渲染器
设置 › 通用 › 渲染器 在 WebGPU（默认）和 OpenGL 之间选择，终端窗口和设置窗口都用它。改动在 ThinkTerm 重启后生效。
如果 WebGPU 在这台机器上起不来 —— 没有可用的 Metal、DirectX 12 或 Vulkan 适配器 —— 窗口会改用 OpenGL 打开，而不是打不开，所以选错了也不会把你锁在设置窗口之外、没法改回来。选 OpenGL 则完全跳过 WebGPU 的尝试。