跳到主要内容

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 一样，管道输入 stdin 或在非交互式环境中运行将回退到单查询模式。

首次启动时，Hermes 会将 TUI 的 Node 依赖项安装到 ui-tui/node_modules 中（一次性操作，耗时几秒）。后续启动速度很快。如果你拉取了新的 Hermes 版本，当源代码比分发版更新时，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当前轮次已取消；按 Enter 再次发送。
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。你可以在一个界面中启动会话，在另一个界面中恢复。会话选择器会展示来自两个来源的会话，并带有来源标签。

请参阅 Sessions 了解生命周期、搜索、压缩和导出。

回退到经典 CLI​

启动 hermes（不带 --tui）将保持在经典 CLI 模式。要让机器优先使用 TUI，请在你的 shell 配置文件中设置 HERMES_TUI=1。要恢复原状，请取消设置该变量。

如果 TUI 启动失败（没有 Node、缺少捆绑包、TTY 问题），Hermes 会打印诊断信息并回退——而不是让你卡住。

另请参阅​