TUI

TUI 是 Hermes 的现代前端——一个与经典 CLI 共享同一 Python 运行时的终端 UI。Agent 相同、会话相同、斜杠命令相同，只是提供了更简洁、更流畅的交互界面。

这是以交互方式运行 Hermes 的推荐方式。

启动

# 启动 TUI
hermes --tui

# 恢复最新的 TUI 会话（若无则退回最新的经典会话）
hermes --tui -c
hermes --tui --continue

# 通过 ID 或标题恢复指定会话
hermes --tui -r 20260409_000000_aa11bb
hermes --tui --resume "my t0p session"

# 直接运行源码——跳过预构建步骤（供 TUI 贡献者使用）
hermes --tui --dev

也可以通过环境变量启用：

export HERMES_TUI=1
hermes          # 现在使用 TUI
hermes chat     # 同上

经典 CLI 仍作为默认方式保留。CLI 界面中记录的所有功能——斜杠命令、快速命令、技能预加载、个性设置、多行输入、中断——在 TUI 中均可正常使用。

为什么选择 TUI

• 即时首帧——横幅在应用完成加载前即已绘制，启动过程中终端不会卡顿。
• 非阻塞输入——在会话准备就绪前即可输入和排队消息。第一条提示在 Agent 上线后立即发送。
• 丰富的浮层面板——模型选择器、会话选择器、审批和澄清提示均以模态面板形式呈现，而非内联流程。
• 实时会话面板——工具和技能在初始化过程中逐步填充显示。
• 鼠标友好的选择——拖拽即可高亮选择，背景均匀，无 SGR 反色。使用终端的常规复制手势进行复制。
• 备用屏渲染——差异更新意味着流式输出时无闪烁，退出后不留滚动历史。
• 输入框功能——对长片段进行粘贴折叠，Cmd+V / Ctrl+V 文本粘贴（带剪贴板图片回退），括号粘贴安全保护，以及图片/文件路径附件规范化。

同样支持皮肤和个性设置，可在会话中途使用 /skin ares、/personality pirate 实时切换，UI 即时重绘。详见皮肤与主题，了解可自定义的键列表及哪些适用于经典版 vs TUI——TUI 支持横幅调色板、UI 颜色、提示符字形/颜色、会话显示、补全菜单、选区背景色、tool_prefix 和 help_header。

要求

• Node.js ≥ 20——TUI 作为从 Python CLI 启动的子进程运行。hermes doctor 会验证此依赖。
• TTY——与经典 CLI 一样，重定向 stdin 或在非交互环境中运行会退回到单次查询模式。

首次启动时，Hermes 会将 TUI 的 Node 依赖安装到 ui-tui/node_modules（一次性操作，需几秒钟）。后续启动很快。拉取新版本的 Hermes 后，若源文件比 dist 更新，TUI 包会自动重新构建。

外部预构建

提供预构建包的发行版（Nix、系统包）可以指定 Hermes 使用该包：

export HERMES_TUI_DIR=/path/to/prebuilt/ui-tui
hermes --tui

该目录必须包含 dist/entry.js 和最新的 node_modules。

快捷键

快捷键与经典 CLI 完全一致。仅有以下行为差异：

• 鼠标拖拽可高亮选择文本，背景均匀。
• Cmd+V / Ctrl+V 先尝试普通文本粘贴，再依次回退到 OSC52/原生剪贴板读取，最后当剪贴板或粘贴内容解析为图片时进行图片附件处理。
• /terminal-setup 可安装本地 VS Code / Cursor / Windsurf 终端绑定，在 macOS 上改善 Cmd+Enter 和撤销/重做的一致性。
• 斜杠自动补全以带描述的浮动面板形式打开，而非内联下拉菜单。
• Ctrl+X——当某条排队消息被高亮时（在 Agent 运行期间发送的），从队列中删除该消息。Esc 取消编辑并取消高亮，但不删除。
• Ctrl+G / Ctrl+X Ctrl+E——在 $EDITOR 中打开当前输入缓冲区，用于多行/长提示词的编辑；保存并退出后将内容作为提示词发送。

斜杠命令

所有斜杠命令均可正常使用。以下是 TUI 专属命令——它们会产生更丰富的输出或以浮层而非内联面板形式呈现：

命令	TUI 行为
/help	可用方向键浏览的分类命令浮层
/sessions	模态会话选择器——可预览、查看标题、Token 总量，并直接恢复
/model	按提供商分组的模态模型选择器，附带费用提示
/skin	实时预览——浏览时主题即时切换
/details	切换详细工具调用信息显示（全局或按区域）
/usage	丰富的 Token/费用/上下文面板
/agents（别名 /tasks）	可观测性浮层——实时子 Agent 树，带终止/暂停控制，各分支费用/Token/文件汇总，逐轮历史
/reload	将 ~/.hermes/.env 重新读入运行中的 TUI 进程，使新增的 API 密钥无需重启即可生效
/mouse	运行时切换鼠标追踪开关（同时持久化到 config.yaml 的 display.mouse_tracking）

所有其他斜杠命令（包括已安装的技能、快速命令和个性切换）均与经典 CLI 完全一致。详见斜杠命令参考。

LaTeX 数学渲染

TUI 的 Markdown 管道支持内联 LaTeX 数学渲染：$E = mc^2$ 和 $$\frac{a}{b}$$ 会以 Unicode 格式的数学公式呈现，而非原始 TeX 源码。支持行内和块级数学；不支持的语法会回退到显示原始 TeX，并用代码段包裹以保持可复制性。

此功能始终开启，无需配置。经典 CLI 保留原始 TeX 显示。

浅色终端检测

TUI 会自动检测浅色终端并相应切换到浅色主题。检测分三个层次：

1. HERMES_TUI_THEME 环境变量——最高优先级。取值：light、dark 或原始 6 位背景十六进制色（如 ffffff、1a1a2e）。
2. COLORFGBG 环境变量——xterm 系终端常用的"背景色是什么？"提示。
3. 通过 OSC 11 探测终端背景——适用于支持该功能的现代终端（Ghostty、Warp、iTerm2、WezTerm、Kitty）。

若要无论终端如何都强制使用浅色主题：

export HERMES_TUI_THEME=light

忙碌指示器样式

状态栏的 FaceTicker 支持插件化——默认在 Agent 工作时每 2.5 秒轮换 Hermes 的 kawaii 表情调色板。可通过配置选择其他样式（或使用 none 显示最简洁的圆点）：

display:
  busy_indicator:
    style: kawaii     # kawaii | minimal | dots | wings | none

各样式均配置了匹配的字形宽度，轮换时状态栏其余部分不会抖动。

自动恢复

默认情况下，hermes --tui 每次启动都会开启新会话。若要在终端或 SSH 连接意外断开后自动重新连接到最近的 TUI 会话，可以选择开启：

export HERMES_TUI_RESUME=1          # 最近一次 TUI 会话
# 或：
export HERMES_TUI_RESUME=<session-id>   # 指定会话

取消设置该变量或显式传递 --resume <id> 可在单次启动时覆盖此设置。

状态栏

TUI 的状态栏实时追踪 Agent 状态：

状态	含义
starting agent…	会话 ID 已生成；工具和技能仍在加载。你可以输入——消息会进入队列，待 Agent 就绪后发送。
ready	Agent 空闲，等待输入。
thinking… / running…	Agent 正在推理或执行工具。
interrupted	当前轮次已取消；按 Enter 重新发送。
forging session… / resuming…	初始连接或 --resume 握手中。

各皮肤的状态栏颜色和阈值与经典 CLI 共享——详见皮肤了解自定义选项。

状态栏还显示：

• 工作目录与 git 分支——~/projects/hermes-agent (docs/two-week-gap-sweep)。分支后缀会在你在旁路终端执行 git checkout 时更新（使用 mtime 缓存），因此 TUI 反映的是你实际活跃的分支，而非启动时的状态。
• 每次提示的耗时——轮次运行期间实时显示 ⏱ 12s/3m 45s，轮次完成后冻结为 ⏲ 32s / 3m 45s。第一个数字是自上次用户消息起的时间，第二个是会话总时长。每次新提示后重置。

配置

TUI 遵循所有标准 Hermes 配置：~/.hermes/config.yaml、配置文件、个性、皮肤、快速命令、凭证池、记忆提供商、工具/技能启用。不存在 TUI 专用配置文件。

以下配置键专门调整 TUI 界面：

display:
  skin: default              # 任何内置或自定义皮肤
  personality: helpful
  details_mode: collapsed    # hidden | collapsed | expanded——全局手风琴默认值
  sections:                  # 可选：按区域覆盖（任意子集）
    thinking: expanded       # 始终展开
    tools: expanded          # 始终展开
    activity: collapsed      # 重新开启 activity 面板（默认隐藏）
  mouse_tracking: true       # 若你的终端与鼠标报告冲突，可禁用

运行时切换：

• /details [hidden|collapsed|expanded|cycle]——设置全局模式
• /details <section> [hidden|collapsed|expanded|reset]——覆盖单个区域 （区域：thinking、tools、subagents、activity）

默认可见性

TUI 为各区域设置了有主见的默认值，将轮次呈现为实时转录而非一堆折叠箭头：

• thinking——展开。推理过程随模型输出实时流式显示。
• tools——展开。工具调用及其结果以展开状态呈现。
• subagents——沿用全局 details_mode（默认折叠在箭头下——委派真正发生时才显示，平时保持安静）。
• activity——隐藏。环境元数据（网关提示、终端一致性提示、后台通知）对日常使用而言是噪音。工具失败时仍会内联显示在失败工具行；当所有面板都隐藏时，环境错误/警告通过浮动警告后备机制显示。

按区域覆盖的优先级高于区域默认值和全局 details_mode。调整布局的方法：

• display.sections.thinking: collapsed——将思考过程折叠到箭头下
• display.sections.tools: collapsed——将工具调用折叠到箭头下
• display.sections.activity: collapsed——重新开启 activity 面板
• 运行时使用 /details <section> <mode>

在 display.sections 中显式设置的值优先于默认值，因此现有配置无需修改即可继续使用。

会话

会话在 TUI 和经典 CLI 之间共享——两者都写入同一个 ~/.hermes/state.db。可以在一个界面中开始会话，在另一个界面中恢复。会话选择器会显示来自两个来源的会话，并附有来源标签。

详见会话了解生命周期、搜索、压缩和导出。

切回经典 CLI

启动 hermes（不带 --tui）将使用经典 CLI。若要让某台机器默认使用 TUI，在 shell 配置文件中设置 HERMES_TUI=1。若要切回，取消设置即可。

如果 TUI 启动失败（无 Node.js、缺少包、TTY 问题），Hermes 会打印诊断信息并回退——不会让你陷入困境。

参见

• CLI 界面——完整的斜杠命令和快捷键参考（共享）
• 会话——恢复、分支和历史
• 皮肤与主题——为横幅、状态栏和浮层设置主题
• 语音模式——两种界面均支持
• 配置——所有配置键