SuperAPI AI 工具集

dbggng-hermes-tui-comman

编程与开发

查看项目

更新于 10-16 08:18

技能介绍

用途

本技能用于调试 Hermes TUI 中的斜杠命令(slash commands)。Hermes 斜杠命令横跨三层——Python 命令注册表、tui_gateway JSON-RPC 桥接层,以及 Ink/TypeScript 前端。当命令行为异常时(未出现在自动补全中、在 CLI 可用但在 TUI 中失效、配置已持久化但 UI 未实时更新),问题几乎总是某一层与其他层不同步。

适用场景包括:

  • 斜杠命令在代码库某一部分存在,但无法完整工作
  • 需要同时向后端和前端添加命令
  • 特定命令的自动补全不工作
  • 命令在 CLI 与 TUI 之间行为不一致
  • 命令持久化了配置,但未在 TUI 中实时生效

架构概览

命令定义必须在 Python 与 TypeScript 之间一致注册才能正常工作。Python 的 COMMAND_REGISTRY 是以下内容的唯一事实来源:CLI 分发、网关帮助、Telegram BotCommand 菜单、Slack 子命令映射,以及发送给 Ink 的自动补全数据。

三层结构:

  • Python 后端(hermes_cli/commands.py)—— 规范 COMMAND_REGISTRY
  • TUI 网关(tui_gateway/server.py)—— slash.exec / command.dispatch
  • TUI 前端(ui-tui/src/app/slash/)—— 本地处理器 + 回退

主要能力

排查步骤

检查命令是否存在于 TUI 前端:

search_files --pattern "/commandname" --file_glob "*.ts" --path ui-tui/
search_files --pattern "/commandname" --file_glob "*.tsx" --path ui-tui/

检查 TUI 命令定义:

read_file ui-tui/src/app/slash/commands/core.ts
# 如果不在那里:
search_files --pattern "commandname" --path ui-tui/src/app/slash/commands --target files

检查命令是否存在于 Python 后端:

search_files --pattern "CommandDef" --file_glob "*.py" --path hermes_cli/
search_files --pattern "commandname" --path hermes_cli/commands.py --context 3

检查网关实现:

search_files --pattern "complete.slash|slash.exec" --path tui_gateway/

修复:命令自动补全缺失

如果命令存在于 TUI 但未出现在自动补全中,在 hermes_cli/commands.py 的 COMMAND_REGISTRY 中添加 CommandDef 条目:

CommandDef("commandname", "Description of the command", "Session",
           cli_only=True, aliases=("alias",),
           args_hint="[arg1|arg2|arg3]",
           subcommands=("arg1", "arg2", "arg3")),

可用性选项:

  • cli_only=True —— 仅在交互式 CLI/TUI 中
  • gateway_only=True —— 仅在消息平台中
  • 两者都不设 —— 处处可用
  • gateway_config_gate="display.foo" —— 网关中受配置门控的可用性

确保 subcommands 与 TUI 显示的预期 Tab 补全选项一致。

如果命令在服务端运行,在 cli.py 的 HermesCLI.process_command() 中添加处理器:

elif canonical == "commandname":
    self._handle_commandname(cmd_original)

对于网关可用的命令,在 gateway/run.py 中添加处理器:

if canonical == "commandname":
    return await self._handle_commandname(event)

常见问题

  • 命令显示在 TUI 但不在自动补全中:命令定义在 TUI 代码库中,但缺少 hermes_cli/commands.py 的 COMMAND_REGISTRY 条目。自动补全数据由 Python 发送。
  • 命令显示在自动补全中但不工作:检查 tui_gateway/server.py 中的命令处理器和 ui-tui/src/app/createSlashHandler.ts 中的前端处理器。如果命令在 Ink 中仅本地,必须在 app.tsx 内置分支中处理;否则会回退到 slash.exec,必须有 Python 处理器。
  • 命令在 CLI 与 TUI 之间行为不同:命令可能有不同实现。检查 cli.py::process_command 和 TUI 本地处理器。本地 TUI 处理器优先于网关分发。
  • 命令持久化配置但不实时生效:对于 TUI 本地命令,仅更新 config.set 不够。还需立即修补相关 nanostore 状态(通常是 patchUiState(...)),并将新状态传递到渲染组件。例如 /details collapsed 必须实时更新详情可见性,而不仅仅是保存 details_mode;会话内全局 /details <mode> 可能需要单独的命令覆盖标志,以便实时命令可以覆盖内置区块默认值,同时启动/配置同步保留默认展开的 thinking/tools 行为。
  • 网关分发静默忽略命令:网关只分发它知道的命令。检查 GATEWAY_KNOWN_COMMANDS(自动从 COMMAND_REGISTRY 派生)是否包含规范名称。如果命令是 cli_only 且带有 gateway_config_gate,验证门控配置值为真。

调试策略

当表面检查无法揭示 bug 时:

  • Python 侧挂起或行为异常:使用 py-debugpy 技能在 _SlashWorker.exec 或命令处理器内部断点。在处理器入口设置 remote-pdb 是最快路径。
  • Ink 侧无反应:使用 node-inspect-debugger 技能在 app.tsx 的斜杠分发或本地命令分支中断点。npm run build 后使用 sb('dist/app.js', <line>)。
  • 注册表不匹配 / 不清楚哪一侧错误:将规范 COMMAND_REGISTRY 条目与 TUI 本地命令列表并排比较。

注意事项

  • 不要忘记在 CommandDef 中为命令设置适当类别(例如 "Session"、"Configuration"、"Tools & Skills"、"Info"、"Exit")
  • 确保任何别名正确注册在 aliases 元组中——无需其他文件更改,所有下游(Telegram 菜单、Slack 映射、自动补全、帮助)都由此派生
  • 对于带子命令的命令,确保 CommandDef 中的 subcommands 元组与 TUI 代码中的一致
  • cli_only=True 命令在网关/消息平台中不工作——除非添加 gateway_config_gate 且门控为真
  • 添加实时 UI 状态后,搜索旧 prop/helper 的每个消费者,并将新状态贯穿所有渲染路径,而不仅仅是活动流式路径。TUI 详情渲染至少有两个重要路径:实时 StreamingAssistant/ToolTrail 和 transcript/pending MessageLine 行。/clean 检查应明确检查两者。
  • 测试前重新构建 TUI(npm --prefix ui-tui run build)——tsx watch 模式在首次启动时可能滞后

验证

修复后:

重新构建 TUI:

cd /home/bb/hermes-agent && npm --prefix ui-tui run build

运行 TUI 并测试命令:

hermes --tui

输入 / 并验证命令出现在自动补全建议中,带有预期描述和参数提示。

执行命令并确认:

  • 预期行为触发
  • 任何持久化配置正确更新(read_file ~/.hermes/config.yaml)
  • 实时 UI 状态立即反映更改(而非仅在重启后)

如果命令也网关可用,至少从一个消息平台测试它(或运行网关测试:scripts/run_tests.sh tests/gateway/)。