Hermes TUI --- 三列会话管理器

基于 Textual 的独立终端 UI，连接 Hermes Agent Gateway，提供三栏布局： 会话列表 | 分层聊天 + 输入 | 全局状态概览

快速开始

前提条件

需要在目标机器上已经安装好 Hermes Agent。TUI 依赖 Hermes 的 tui_gateway 模块作为后端通信。

1. 安装依赖

# 使用 Hermes Agent 的 venv 安装 Textual
~/.hermes/hermes-agent/venv/bin/pip install textual

验证：

~/.hermes/hermes-agent/venv/bin/python -c "import textual; print(textual.__version__)"

能看到版本号（如 8.2.7）即成功。

2. 获取代码

# 方式 A：从 Git 克隆（推荐）
git clone <你的仓库地址> ~/hermes-tui

# 方式 B：手动拷贝整个 hermes-tui/ 目录到目标机器

3. 安装启动脚本（可选）

cat > /usr/local/bin/hermes-tui << 'SCRIPTEOF'
#!/bin/bash
exec ~/.hermes/hermes-agent/venv/bin/python3 ~/hermes-tui/main.py "$@"
SCRIPTEOF
chmod +x /usr/local/bin/hermes-tui

4. 启动

hermes-tui

或直接：

~/.hermes/hermes-agent/venv/bin/python3 ~/hermes-tui/main.py

首次启动会自动 spawn Hermes gateway 子进程，等待 gateway.ready 事件后显示界面。

布局说明

三栏布局示意：

• 左栏 (Col 1) --- 会话列表，支持方向盘上下选择 + Enter 切换
• 中栏 (Col 2) --- 三层聊天面板：层1系统提示词（折叠）、层2对话记录、层3当前步骤状态
• 右栏 (Col 3) --- 全局状态概览：模型名、Token用量、耗时、子代理数量、活动状态

三层联动机制

• 切换会话（Col 1 选会话）：自动加载聊天历史到 Col 2，更新模型/用量到 Col 3
• 发送消息（Col 2 输入）：流式输出实时更新 Col 2 + Col 3，完成后再刷新 Col 1 列表
• 网关事件（thinking/reasoning/message 流）：同步更新 Col 2 步骤指示 + Col 3 活动状态

快捷键

按键	功能
Ctrl+Q	退出
Ctrl+L	切换左侧会话栏显隐
Ctrl+R	切换右侧全局视图显隐
F5	刷新会话列表
Esc	聚焦到输入框
上/下	导航会话列表
Enter	选中会话 / 发送消息

文件结构

~/hermes-tui/
  main.py                 应用入口 + CSS 主题
  client.py               Gateway 子进程管理 + JSON-RPC 2.0 通信
  README.md               本文件
  run.sh                  启动脚本
  screens/
    __init__.py           包初始化
    main_screen.py        三栏布局 + 事件路由 + 联动逻辑
    session_sidebar.py    左侧：会话列表组件
    chat_panel.py         中间：三层聊天面板
    global_view.py        右侧：全局状态概览
  .gitignore

主题配色

使用 Hermes Agent 默认 Gold and Kawaii 配色方案：

• 背景底色: #1a1a2e (dark navy)
• 面板底色: #16162a
• 强调色: #FFD700 (gold)
• 副标色: #DAA520 (goldenrod)
• 文字色: #FFF8DC (cornsilk)
• 边框色: #CD7F32 (bronze)
• 弱化色: #8B8682 (gray-brown)
• 选中色: #333355 (dark purple)

JSON-RPC API 调用链

TUI 与 Gateway 通过 stdin/stdout 以 JSON-RPC 2.0 通信：

START -> gateway.ready (event)
  session.list -> Col 1 填充会话列表
  session.most_recent -> 找回最近会话
  session.activate -> Col 2 + Col 3 填充
  session.history -> 加载历史消息
  session.usage -> 加载用量数据
  用户输入 -> prompt.submit -> 流式事件:
    message.start -> Col 3 状态更新
    thinking.delta -> Col 2 步骤: "Thinking..."
    reasoning.delta -> Col 2 步骤: "Reasoning..."
    message.delta -> 追加流式文字到 Col 2
    message.complete -> 完成 + 刷新 Col 1 + Col 3
    session.info -> 更新模型/用量到 Col 3

排错

ModuleNotFoundError: No module named 'tui_gateway'

确保从 hermes-agent 目录运行，或设置 PYTHONPATH：

cd ~/.hermes/hermes-agent
PYTHONPATH=~/.hermes/hermes-agent python3 -m tui_gateway.entry

textual 未找到

~/.hermes/hermes-agent/venv/bin/pip install textual

Gateway 启动失败

日志文件：~/.hermes/logs/tui_gateway_crash.log

cat ~/.hermes/logs/tui_gateway_crash.log