mcpField
D
debugging-hermes-tui-commands

debugging-hermes-tui-commands

github.com/nousresearch开发258.1k76 次安装今天更新
代码仓库

关于 debugging-hermes-tui-commands

debugging-hermes-tui-commands 是用于排查和修复 Hermes 斜杠命令问题的技能，覆盖 Python 注册表、TUI 网关和 TypeScript 界面。它帮助开发者定位自动补全、命令分发和实时配置更新中的不同步问题。

主要功能

  1. 01追踪命令在三个代码层中的状态
  2. 02诊断自动补全和分发故障
  3. 03检查 CLI 与 TUI 的行为差异
  4. 04指导更新注册表和处理器
  5. 05验证持久化配置与实时界面状态

适用场景

  1. 01查找命令未出现在自动补全中的原因
  2. 02排查命令在 CLI 可用但在 TUI 失效
  3. 03修复配置已保存但界面未更新的问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/nousresearch/hermes-agent --skill debugging-hermes-tui-commands

安装后在 Claude Code 中输入/debugging-hermes-tui-commands确认已加载。

详细介绍

Hermes TUI 斜杠命令调试

概述

Hermes 斜杠命令涉及三个层面——Python 命令注册表、tui_gateway JSON-RPC 桥接层，以及 Ink/TypeScript 前端。命令出现异常时（未显示在自动补全中、在 CLI 中可用但在 TUI 中不可用、配置已持久化但 UI 未更新），问题几乎总是出在某一层与其他层不同步。

当你遇到 Hermes TUI 斜杠命令相关问题时，请使用本指南，尤其是命令未显示在自动补全中、在 TUI 中无法正常工作，或需要添加/更新命令时。

适用场景

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

架构概览

Python backend (hermes_cli/commands.py)     <- canonical COMMAND_REGISTRY
       │
       ▼
TUI gateway (tui_gateway/server.py)         <- slash.exec / command.dispatch
       │
       ▼
TUI frontend (ui-tui/src/app/slash/)        <- local handlers + fallthrough

要使命令正常工作，必须在 Python 和 TypeScript 中保持一致地注册命令。Python 的 COMMAND_REGISTRY 是以下内容的事实来源：CLI 分发、网关帮助信息、Telegram BotCommand 菜单、Slack 子命令映射，以及发送给 Ink 的自动补全数据。

调查步骤

  1. 检查命令是否存在于 TUI 前端：

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

  2. 检查 TUI 命令定义：

    read_file ui-tui/src/app/slash/commands/core.ts
# If not there:
search_files --pattern "commandname" --path ui-tui/src/app/slash/commands --target files

  3. 检查命令是否存在于 Python 后端：

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

  4. 检查网关实现：

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

修复：命令未显示在自动补全中

如果命令已存在于 TUI 中，但未显示在自动补全中：

  1. 在 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")),

  2. 谨慎选择 cli_only 还是网关可用性：

    • cli_only=True — 仅在交互式 CLI/TUI 中可用
    • gateway_only=True — 仅在消息平台中可用
    • 两者都不设置 — 在所有地方都可用
    • gateway_config_gate="display.foo" — 在网关中按配置控制可用性

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

  4. 如果命令在服务端运行，请在 cli.py 的 HermesCLI.process_command() 中添加处理程序：

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

  5. 对于网关可用的命令，请在 gateway/run.py 中添加处理程序：

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

常见问题

  1. 命令显示在 TUI 中，但未显示在自动补全中。 命令已在 TUI 代码库中定义，但缺少 hermes_cli/commands.py 中的 COMMAND_REGISTRY 条目。自动补全数据由 Python 提供。

  2. 命令显示在自动补全中，但无法运行。 检查 tui_gateway/server.py 中的命令处理程序，以及 ui-tui/src/app/createSlashHandler.ts 中的前端处理程序。如果命令仅在 Ink 中本地处理，则必须在 app.tsx 的内置分支中处理；否则命令会进入 slash.exec，因此必须有对应的 Python 处理程序。

  3. 命令在 CLI 和 TUI 中的行为不同。 命令可能有不同的实现。检查 cli.py::process_command 和 TUI 的本地处理程序。本地 TUI 处理程序的优先级高于网关分发。

  4. 命令已持久化配置，但未实时生效。 对于 TUI 本地命令，仅更新 config.set 并不足够。还必须立即修补相关的 nanostore 状态（通常使用 patchUiState(...)），并将任何新状态传递给渲染组件。例如：/details collapsed 必须实时更新详细信息的可见性，而不能只保存 details_mode；会话期间的全局 /details <mode> 可能需要单独的命令覆盖标志，使实时命令能够覆盖内置分区默认值，同时确保启动/配置同步仍保留思考/工具默认展开的行为。

  5. 网关分发会静默忽略命令。 网关只会分发它已知的命令。检查 GATEWAY_KNOWN_COMMANDS（由 COMMAND_REGISTRY 自动派生）是否包含规范名称。如果命令设置了 cli_only 和 gateway_config_gate，请确认受控配置值为真。

调试技巧

如果表层检查无法发现问题：

  • **Python 端挂起或行为异常：**使用 python-debugpy 技能，在 _SlashWorker.exec 或命令处理程序中设置断点。在处理程序入口处设置 remote-pdb 是最快的方法。
  • **Ink 端没有响应：**使用 node-inspect-debugger 技能，在 app.tsx 的斜杠命令分发逻辑或本地命令分支中设置断点。运行 npm run build 后，使用 sb('dist/app.js', <line>)。
  • **注册表不匹配／不清楚哪一端有问题：**并排比较规范的 COMMAND_REGISTRY 条目和 TUI 的本地命令列表。

注意事项

  • 别忘了在 CommandDef 中为命令设置适当的类别（例如“会话”“配置”“工具与技能”“信息”“退出”）。
  • 确保所有别名都已正确注册到 aliases 元组中——无需更改其他文件；下游所有内容（Telegram 菜单、Slack 映射、自动补全、帮助）都会从中派生。
  • 对于带子命令的命令，请确保 CommandDef 中的 subcommands 元组与 TUI 代码中的内容一致。
  • cli_only=True 的命令无法在网关／消息平台中使用，除非你添加 gateway_config_gate 且该门控条件为真。
  • 添加实时 UI 状态后，请搜索旧属性／辅助函数的所有使用方，并将新状态传递到所有渲染路径，而不只是当前活动的流式处理路径。TUI 详情渲染至少有两个重要路径：实时 StreamingAssistant/ToolTrail 和转录／待处理的 MessageLine 行。执行 /clean 时应明确检查这两者。
  • 测试前请重新构建 TUI（npm --prefix ui-tui run build）——tsx watch 模式在首次启动时可能会滞后。

验证

修复后：

  1. 重新构建 TUI：

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

  2. 运行 TUI 并测试该命令：

    hermes --tui

  3. 输入 /，并确认该命令出现在自动补全建议中，且显示预期的描述和参数提示。

  4. 执行该命令并确认：

    • 预期行为已触发
    • 所有持久化配置均已正确更新（read_file ~/.hermes/config.yaml）
    • 实时 UI 状态立即反映更改（而不只是重启后）

  5. 如果该命令也可通过网关使用，请至少从一个消息平台进行测试（或运行网关测试：scripts/run_tests.sh tests/gateway/）。

评论

支持 Markdown