TUI
TUI 是 Hermes 的现代前端界面 —— 一个基于终端的用户界面，由与经典 CLI 相同的 Python 运行时提供支持。相同的代理、相同的会话、相同的斜杠命令；为与它们交互提供了更清晰、响应更快的界面。
这是推荐的交互式运行 Hermes 的方式。
启动
# Launch the TUI
hermes --tui
# Resume the latest TUI session (falls back to the latest classic session)
hermes --tui -c
hermes --tui --continue
# Resume a specific session by ID or title
hermes --tui -r 20260409_000000_aa11bb
hermes --tui --resume "my t0p session"
# Run source directly — skips the prebuild step (for TUI contributors)
hermes --tui --dev
你也可以通过环境变量启用它：
export HERMES_TUI=1
hermes # now uses the TUI
hermes chat # same
经典 CLI 仍然作为默认选项保留。CLI 接口中记录的所有内容 —— 斜杠命令、快速命令、技能预加载、个性、多行输入、中断 —— 在 TUI 中的工作方式完全相同。
为什么选择 TUI
- 即时首帧 —— 横幅在应用完成加载前就会绘制，因此 Hermes 启动时终端永远不会感觉冻结。
- 非阻塞输入 —— 在会话准备就绪前输入并排队消息。当代理上线时，你的第一个提示会立即发送。
- 丰富的覆盖层 —— 模型选择器、会话选择器、批准和澄清提示都渲染为模态面板，而不是内联流程。
- 实时会话面板 —— 工具和技能在初始化时会逐步填充。
- 鼠标友好的选择 —— 拖动以高亮显示，使用统一的背景，而不是 SGR 反色。使用终端的正常复制手势进行复制。
- 备用屏幕渲染 —— 差异更新意味着流式传输时无闪烁，退出后无滚动历史杂乱。
- 编辑器功能 —— 长片段的内联粘贴折叠、
Cmd+V/Ctrl+V文本粘贴（带剪贴板图像回退）、括号粘贴安全性，以及图像/文件路径附件标准化。
相同的皮肤和个性适用。使用 /skin ares、/personality pirate 可在会话中途切换，UI 会实时重绘。有关可自定义键的完整列表以及哪些键适用于经典 CLI 与 TUI，请参阅皮肤与主题 —— TUI 支持横幅调色板、UI 颜色、提示符号/颜色、会话显示、补全菜单、选择背景、tool_prefix 和 help_header。
要求
- Node.js ≥ 20 —— TUI 作为从 Python CLI 启动的子进程运行。
hermes doctor会验证这一点。 - TTY —— 与经典 CLI 一样，管道输入或在非交互式环境中运行会回退到单查询模式。
首次启动时，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和撤销/重做对等性。- 斜杠自动补全 以带描述的浮动面板打开，而不是内联下拉菜单。
斜杠命令
所有斜杠命令的工作方式不变。其中一些由 TUI 拥有 —— 它们产生更丰富的输出或渲染为覆盖层，而不是内联面板：
| 命令 | TUI 行为 |
|---|---|
/help | 带分类命令的覆盖层，可通过方向键导航 |
/sessions | 模态会话选择器 —— 预览、标题、令牌总数、内联恢复 |
/model | 按提供商分组的模态模型选择器，带成本提示 |
/skin | 实时预览 —— 主题更改在你浏览时应用 |
/details | 切换详细工具调用详情（全局或每部分） |
/usage | 丰富的令牌 / 成本 / 上下文面板 |
其他所有斜杠命令（包括已安装的技能、快速命令和个性切换）的工作方式与经典 CLI 完全相同。请参阅斜杠命令参考。
状态栏
TUI 的状态栏实时跟踪代理状态：
| 状态 | 含义 |
|---|---|
starting agent… | 会话 ID 处于活动状态；工具和技能仍在上线。你可以输入 —— 消息会排队，并在准备就绪时发送。 |
ready | 代理处于空闲状态，接受输入。 |
thinking… / running… | 代理正在推理或运行工具。 |
interrupted | 当前轮次已取消；按回车键重新发送。 |
forging session… / resuming… | 初始连接或 --resume 握手。 |
每个皮肤的状态栏颜色和阈值与经典 CLI 共享 —— 有关自定义，请参阅皮肤。
配置
TUI 尊重所有标准 Hermes 配置：~/.hermes/config.yaml、配置文件、个性、皮肤、快速命令、凭据池、内存提供程序、工具/技能启用。不存在 TUI 特定的配置文件。
少量键专门用于调整 TUI 界面：
display:
skin: default # any built-in or custom skin
personality: helpful
details_mode: collapsed # hidden | collapsed | expanded — global accordion default
sections: # optional: per-section overrides (any subset)
thinking: expanded # always open
tools: expanded # always open
activity: collapsed # opt back IN to the activity panel (hidden by default)
mouse_tracking: true # disable if your terminal conflicts with mouse reporting
运行时切换：
/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—— 选择性地重新启用活动面板/details <section> <mode>在运行时
在 display.sections 中明确设置的任何内容都优先于默认值，因此现有配置保持不变。
会话
会话在 TUI 和经典 CLI 之间共享 —— 两者都写入相同的 ~/.hermes/state.db。你可以在一个中启动会话，在另一个中恢复。会话选择器会显示来自两个源的会话，并带有源标签。
有关生命周期、搜索、压缩和导出，请参阅会话。
回退到经典 CLI
启动 hermes（不带 --tui）会保持在经典 CLI。要让机器优先使用 TUI，请在 shell 配置文件中设置 HERMES_TUI=1。要回退，请取消设置它。
如果 TUI 启动失败（无 Node、缺少包、TTY 问题），Hermes 会打印诊断信息并回退 —— 而不是让你卡住。