扩展 CLI

Hermes 在 HermesCLI 上暴露了受保护的扩展 hook（钩子），使包装 CLI 可以添加 widget、快捷键和布局自定义，而无需覆盖超过 1000 行的 run() 方法。这样可以让你的扩展与内部变更解耦。

扩展点

共有五个扩展接缝可用：

Hook	用途	何时覆盖
`_get_extra_tui_widgets()`	向布局注入 widget	需要持久 UI 元素（面板、状态栏、迷你播放器）时
`_register_extra_tui_keybindings(kb, *, input_area)`	添加键盘快捷键	需要热键（切换面板、传输控制、模态快捷键）时
`_build_tui_layout_children(**widgets)`	完全控制 widget 排序	需要重新排序或包装现有 widget 时（少见）
`process_command()`	添加自定义斜杠命令	需要处理 `/mycommand` 时（已有 hook）
`_build_tui_style_dict()`	自定义 prompt_toolkit 样式	需要自定义颜色或样式时（已有 hook）

前三个是新增的受保护 hook，后两个已存在。

快速开始：包装 CLI

运行：

Hook 参考

`_get_extra_tui_widgets()`

返回要插入 TUI 布局的 prompt_toolkit widget 列表。Widget 出现在间隔区与状态栏之间——位于输入区上方、主输出区下方。

每个 widget 应为 prompt_toolkit 容器（如 Window、ConditionalContainer、HSplit）。使用 ConditionalContainer 或 filter=Condition(...) 可使 widget 支持切换显示。

`_register_extra_tui_keybindings(kb, *, input_area)`

在 Hermes 注册自身快捷键之后、布局构建之前调用。将你的快捷键添加到 kb。

参数：

kb — prompt_toolkit 应用的 KeyBindings 实例

input_area — 主 TextArea widget，用于读取或操作用户输入

避免与内置快捷键冲突：Enter（提交）、Escape Enter（换行）、Ctrl-C（中断）、Ctrl-D（退出）、Tab（接受自动建议）。F2 及以上的功能键和 Ctrl 组合键通常是安全的。

`_build_tui_layout_children(**widgets)`

仅在需要完全控制 widget 排序时才覆盖此方法。大多数扩展应使用 _get_extra_tui_widgets() 代替。

默认实现返回（值为 None 的 widget 会被过滤掉）：

布局示意图

默认布局从上到下：

输出区 — 滚动的对话历史

间隔区

额外 widget — 来自 _get_extra_tui_widgets()

状态栏 — 模型、上下文占比、已用时间

图片栏 — 已附加图片数量

输入区 — 用户 prompt（提示词）

语音状态 — 录音指示器

补全菜单 — 自动补全建议

使用技巧

状态变更后刷新显示：调用 self._invalidate() 触发 prompt_toolkit 重绘。

访问 agent 状态：self.agent、self.model、self.conversation_history 均可直接使用。

自定义样式：覆盖 _build_tui_style_dict() 并为自定义样式类添加条目。

斜杠命令：覆盖 process_command()，处理自己的命令，其余一律调用 super().process_command(cmd)。

不要覆盖 run()，除非绝对必要——扩展 hook 的存在正是为了避免这种耦合。

"扩展 CLI"

扩展 CLI#

扩展点#

快速开始：包装 CLI#

Hook 参考#

_get_extra_tui_widgets()#

_register_extra_tui_keybindings(kb, *, input_area)#

_build_tui_layout_children(**widgets)#

布局示意图#

使用技巧#