hermes教程-TUI - 字节笔记本

启动

bash

## 启动 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

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

bash

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

或者将其设为 ~/.hermes/config.yaml 中的持久默认值：

yaml

display:
  interface: tui   # "cli"（默认）或 "tui"

当 display.interface: tui 时，裸 hermes（以及 hermes chat）会启动 TUI。显式标志始终优先——运行 hermes --cli 可回退到经典 REPL 单次调用，或运行 hermes --tui / HERMES_TUI=1 在配置默认为 cli 时强制使用 TUI。

经典 CLI 仍然是默认发行版。在 CLI 界面中记录的所有内容——斜杠命令、快速命令、技能预加载、个性、多行输入、中断——在 TUI 中完全相同。

为什么选择 TUI

即时首帧——横幅在应用加载完成前绘制，因此终端在 Hermes 启动时永远不会感觉卡顿。
非阻塞输入——在会话准备就绪前即可输入并排队消息。你的第一条提示会在智能体上线时立即发送。
丰富的覆盖层——模型选择器、会话选择器、批准和澄清提示均以模态面板形式呈现，而非内联流程。
实时会话面板——工具和技能在初始化时逐步填充。
鼠标友好选择——拖拽高亮使用统一背景而非 SGR 反转。使用终端正常的复制手势进行复制。
备用屏幕渲染——差异更新意味着流式传输时无闪烁，退出后无滚动回混乱。
编辑器便利功能——长片段的内联粘贴折叠、Cmd+V / Ctrl+V 文本粘贴并回退到剪贴板图像、括号粘贴安全以及图像/文件路径附件规范化。

相同的皮肤和个性适用。在会话中通过 /skin ares、/personality pirate 切换，UI 会实时重绘。参见皮肤与主题获取可自定义键的完整列表，以及哪些适用于经典 CLI 与 TUI——TUI 遵循横幅调色板、UI 颜色、提示符字形/颜色、会话显示、补全菜单、选择背景、tool_prefix 和 help_header。

可折叠横幅区域

TUI 启动横幅将运行时信息分组为四个可折叠区域，每个区域标题旁带有 ▸ / ▾ 箭头：

区域	默认状态
工具	展开
技能	折叠
系统提示	折叠
MCP 服务器	折叠

点击区域标题（或其箭头）任意位置可切换。工具列表默认打开，因为它是会话启动时最常检查的区域；技能、系统提示和 MCP 服务器默认折叠，因此即使你安装了数十个技能或连接了许多 MCP 服务器，横幅也能保持紧凑。状态是横幅实例本地的，因此下次启动会重置为默认值。

要求

Node.js ≥ 20——TUI 作为从 Python CLI 启动的子进程运行。hermes doctor 会验证这一点。
TTY——与经典 CLI 一样，管道输入或在非交互环境中运行会回退到单查询模式。

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

外部预构建

分发预构建包（Nix、系统包）的发行版可以将 Hermes 指向它：

bash

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

该目录必须包含 dist/entry.js。

快捷键

快捷键与经典 CLI 完全一致。唯一的行为差异：

鼠标拖拽使用统一选择背景高亮文本。
Cmd+V / Ctrl+V 首先尝试正常文本粘贴，然后回退到 OSC52/原生剪贴板读取，最后在剪贴板或粘贴内容解析为图像时附加图像。
/terminal-setup 安装本地 VS Code / Cursor / Windsurf 终端绑定，以在 macOS 上获得更好的 Cmd+Enter 和撤销/重做一致性。
斜杠自动补全以带描述的浮动面板形式打开，而非内联下拉菜单。
Ctrl+X 打开实时会话切换器。当排队消息被高亮（在智能体仍在运行时发送）时，它仍会删除该排队消息。Esc 取消编辑并取消高亮，不删除。
Ctrl+G / Ctrl+X Ctrl+E——在 $EDITOR 中打开当前输入缓冲区以进行多行/长提示编写；保存并退出会将内容作为提示发送回去。

斜杠命令

所有斜杠命令均无变化地工作。少数几个是 TUI 拥有的——它们产生更丰富的输出或渲染为覆盖层而非内联面板：

命令	TUI 行为
`/help`	覆盖层，带有分类命令，可用箭头键导航
`/sessions`（别名 `/switch`）	实时会话切换器——列出打开的 TUI 会话，在它们之间切换、关闭或启动另一个
`/model`	模态模型选择器，按提供商分组，带有成本提示
`/skin`	实时预览——主题更改在浏览时应用
`/details`	切换详细工具调用信息（全局或按区域）
`/usage`	丰富的令牌/成本/上下文面板
`/agents`（别名 `/tasks`）	可观测性覆盖层——实时子智能体树，带有终止/暂停控制、每个分支的成本/令牌/文件汇总、逐轮历史
`/reload`	重新读取 `~/.hermes/.env` 到运行中的 TUI 进程，使新添加的 API 密钥无需重启即可生效
`/mouse [on\|off\|toggle\|wheel\|buttons\|all]`	在运行时选择鼠标跟踪预设（也会持久化到 `config.yaml` 的 `display.mouse_tracking`）。`wheel`（1000+1006）保留滚轮滚动，但不会产生使 tmux 在提示行上刷屏“No image in clipboard”的悬停事件；`buttons` 添加拖拽选择；`all` 是默认值，带有悬停驱动的 UI。

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

实时会话切换器

当你希望一个终端充当多个 TUI 会话的调度器时，使用实时会话切换器。它仅列出当前在此 TUI 进程中活动的会话；关闭的会话仍保存为记录，并可通过 /resume 或 hermes --tui --resume <id-or-title> 重新打开。

通过以下任一方式打开：

在 TUI 中按 Ctrl+X。
输入 /sessions 或 /switch。
输入 /sessions new 立即创建一个新的实时会话。
点击状态行中的 N 个实时会话 计数。

在切换器内部：

↑ / ↓ 移动选择；鼠标点击也可选择行。
Enter 切换到选中的实时会话。
Ctrl+D 关闭选中的实时会话。
Ctrl+N 启动一个空白实时会话。
Ctrl+R 刷新实时会话列表。
Esc 关闭切换器。
选择 +new，输入提示，然后按 Enter 以调度一个新的实时会话。如果希望仅为该新会话选择模型，请先按 Tab。

LaTeX 数学渲染

TUI 的 Markdown 管道内联渲染 LaTeX 数学： $E = mc^2$ 和 $$\frac{a}{b}$$ 会渲染为 Unicode 格式的数学公式，而非原始 TeX 源码。适用于内联和块级数学；不支持的语法会回退到显示包裹在代码跨度中的字面 TeX，以便仍可复制。

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

浅色终端检测

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

HERMES_TUI_THEME 环境变量——最高优先级。值：light、dark 或原始 6 字符背景十六进制（例如 ffffff、1a1a2e）。
COLORFGBG 环境变量——xterm 衍生终端使用的经典“我的背景颜色是什么？”提示。
通过 OSC 11 进行终端背景探测——适用于未设置 COLORFGBG 的现代终端（Ghostty、Warp、iTerm2、WezTerm、Kitty）。

如果你希望永久使用浅色主题，无论终端如何：

bash

export HERMES_TUI_THEME=light

忙碌指示器样式

状态栏忙碌指示器是可插拔的——默认在智能体工作期间每 2.5 秒轮换 Hermes 的可爱表情调色板。通过配置或 /indicator 斜杠命令选择不同样式：

yaml

display:
  tui_status_indicator: kaomoji   # kaomoji | emoji | unicode | ascii

或在会话中：/indicator emoji（等等）。样式附带匹配的字形宽度，因此状态栏的其余部分不会在轮换时抖动。

自动恢复

默认情况下，hermes --tui 每次启动都会创建一个新会话。要自动重新附加到最近的 TUI 会话（在终端或 SSH 连接意外断开时很有用），请选择加入：

bash

export HERMES_TUI_RESUME=1          # 最近的 TUI 会话
## 或：
export HERMES_TUI_RESUME=<session-id>   # 特定会话

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

状态行

TUI 的状态行实时跟踪智能体状态：

状态	含义
`starting agent…`	会话 ID 已激活；工具和技能仍在加载中。你可以输入——消息会排队并在就绪时发送。
`ready`	智能体空闲，等待输入。
`thinking…` / `running…`	智能体正在推理或运行工具。
`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。第一个数字是自上次用户消息以来的时间；第二个是总会话时长。每次新提示重置。
🗜️ N——运行中的会话被自动压缩的次数。在第一次压缩触发后出现。
▶ N——此会话中当前正在运行的 /background 任务数量。只要至少有一个任务在进行中，就会显示。
⚠ YOLO——每当 YOLO 模式开启时（hermes --yolo、/yolo 或 HERMES_YOLO_MODE=1）的可见警告。相同的徽章也会出现在启动横幅中，因此你无法在未注意到的情况下启动自动批准会话。

配置

TUI 遵循所有标准 Hermes 配置：~/.hermes/config.yaml、配置文件、个性、皮肤、快速命令、凭据池、内存提供程序、工具/技能启用。没有 TUI 特定的配置文件。

少数几个键专门调整 TUI 界面：

yaml

display:
  skin: default              # 任何内置或自定义皮肤
  personality: helpful
  details_mode: collapsed    # hidden | collapsed | expanded — 全局手风琴默认值
  sections:                  # 可选：按区域覆盖（任意子集）
    thinking: expanded       # 始终展开
    tools: expanded          # 始终展开
    activity: collapsed      # 选择重新启用活动面板（默认隐藏）
  mouse_tracking: all        # off | wheel | buttons | all（或 true/false 用于向后兼容）。
## wheel   — 1000+1006（滚动 + 点击；无拖拽，无悬停 —
## 推荐在 tmux 内使用，以静默提示行上来自悬停事件的
## “No image in clipboard”刷屏）
## buttons — 添加 1002 用于终端侧拖拽选择
## all     — 添加 1003 用于悬停（滚动条悬停分页、
## 链接 mouseenter 等）

运行时切换：

/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。你可以在一个中启动会话，在另一个中恢复。会话选择器会显示来自两个来源的会话，并带有来源标签。

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

TUI 如何与其网关通信

默认情况下，TUI 会生成自己的进程内网关，因此每个 TUI 实例都是自包含的——无需配置。

你可能会在代码库或日志中看到 HERMES_TUI_GATEWAY_URL 环境变量。这是 Web 仪表盘的内部连接细节，而非面向用户的远程附加旋钮。当你打开仪表盘的“聊天”选项卡（hermes dashboard → /chat）时，仪表盘的 Web 服务器会生成一个嵌入的 TUI 子进程，并注入 HERMES_TUI_GATEWAY_URL，以便该子进程通过回环 WebSocket（/api/ws）附加到仪表盘自己的进程内 tui_gateway。/api/ws 端点仅存在于仪表盘服务器内部（hermes_cli/web_server.py），并绑定到该进程的生命周期和认证。

没有通用的“将任何 TUI 指向任何独立网关端口”模式。特别是，兼容 OpenAI 的 API 服务器（hermes gateway / api_server 平台）不提供 /api/ws——它是模型后端接口（/v1/chat/completions、/v1/models……），并且故意不暴露 TUI 的 JSON-RPC 控制通道。将 HERMES_TUI_GATEWAY_URL 设置为该端口会导致 404。

如果你希望多个界面共享一组会话，请使用共享的 ~/.hermes/state.db（参见会话）或 Web 仪表盘的嵌入聊天（参见Web 仪表盘）——而不是手动设置的网关 URL。

回退到经典 CLI

启动 hermes（不带 --tui）默认保持在经典 CLI。要使某台机器偏好 TUI，请在 ~/.hermes/config.yaml 中设置 display.interface: tui（持久化）或在 shell 配置文件中设置 HERMES_TUI=1（每个 shell）。要恢复，请设置 interface: cli / 取消设置环境变量，或传递 hermes --cli 进行单次使用。

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

另请参见

CLI 界面 — 完整的斜杠命令和快捷键参考（共享）
会话 — 恢复、分支和历史
皮肤与主题 — 主题化横幅、状态栏和覆盖层
语音模式 — 在两个界面中均可工作
配置 — 所有配置键