🏠 Главная › user guide › software development debugging hermes tui commands

{/ Эта страница автоматически создается на основе файла SKILL.md навыка с помощью сайта site/scripts/generate-skill-docs.py. Редактируйте исходный код SKILL.md, а не эту страницу. /}

Отладка команд Hermes Tui

Отладка команд Hermes TUI с косой чертой: Python, шлюз, пользовательский интерфейс Ink.

Метаданные навыков
Источник В комплекте (устанавливается по умолчанию)
Путь навыки/разработка программного обеспечения/отладка-hermes-tui-команды
Версия 1.0.0
Автор Агент Гермес
Лицензия Массачусетский технологический институт
Платформы Linux, MacOS, Windows
Теги отладка, hermes-agent, tui, slash-команды, typescript, python
Сопутствующие навыки python-debugpy, node-inspect-debugger, систематическая-отладка

Ссылка: полная версия SKILL.md:::информация

Ниже приведено полное определение навыка, которое Гермес загружает при активации этого навыка. Это то, что агент видит в качестве инструкций, когда навык активен.

Отладка команд Hermes TUI Slash

Обзор

Слэш-команды Hermes охватывают три уровня — реестр команд Python, мост tui_gateway JSON-RPC и интерфейс Ink/TypeScript. Когда команда работает неправильно (отсутствует в автозаполнении, работает в CLI, но не в TUI, конфигурация сохраняется, но пользовательский интерфейс не обновляется), ошибка почти всегда заключается в том, что один уровень не синхронизирован с другим.

Используйте этот навык, когда вы сталкиваетесь с проблемами с командами косой черты в TUI Hermes, особенно когда команды не отображаются при автозаполнении, не работают должным образом в 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: bash search_files --pattern "/commandname" --file_glob "*.ts" --path ui-tui/ search_files --pattern "/commandname" --file_glob "*.tsx" --path ui-tui/
  2. Изучите определение команды TUI: bash 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: bash search_files --pattern "CommandDef" --file_glob "*.py" --path hermes_cli/ search_files --pattern "commandname" --path hermes_cli/commands.py --context 3
  4. Изучите реализацию шлюза: bash search_files --pattern "complete.slash|slash.exec" --path tui_gateway/

Исправлено: отсутствует автозаполнение команд

Если команда существует в TUI, но не отображается при автозаполнении:

  1. Добавьте запись CommandDef в COMMAND_REGISTRY в Hermes_cli/commands.py: python CommandDef("commandname", "Description of the command", "Session", cli_only=True, aliases=("alias",), args_hint="[arg1|arg2|arg3]", subcommands=("arg1", "arg2", "arg3")),
  2. Внимательно выбирайте cli_only и доступность шлюза:
  3. cli_only=True — только в интерактивном CLI/TUI.
  4. gateway_only=True — только на платформах обмена сообщениями
  5. ни один - доступен везде

  6. gateway_config_gate="display.foo" — настраиваемая доступность в шлюзе

  7. Убедитесь, что «подкоманды» соответствуют ожидаемым параметрам завершения табуляции, отображаемым в TUI.

  8. Если команда выполняется на стороне сервера, добавьте обработчик в HermesCLI.process_command() в cli.py: python elif canonical == "commandname": self._handle_commandname(cmd_original)

  9. Для команд, доступных через шлюз, добавьте обработчик в gateway/run.py: python if canonical == "commandname": return await self._handle_commandname(event)

Распространенные проблемы

  1. Команда отображается в TUI, но не отображается при автозаполнении. Команда определена в кодовой базе TUI, но отсутствует в COMMAND_REGISTRY в hermes_cli/commands.py. Данные автозаполнения отправляются из 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 недостаточно. Также немедленно исправьте соответствующее состояние наностора (обычно patchUiState(...)) и передайте любое новое состояние через компоненты рендеринга. Пример: /details свернутый должен обновить видимость подробностей в реальном времени, а не просто сохранить details_mode; в глобальном сеансе /details <mode> может потребоваться отдельный флаг переопределения команды, чтобы живые команды могли переопределять встроенные значения раздела по умолчанию, в то время как синхронизация запуска/конфигурации сохраняет расширенное мышление/поведение инструментов по умолчанию.

  5. Диспетчер шлюза игнорирует команду. Шлюз отправляет только те команды, о которых он знает. Проверьте, что GATEWAY_KNOWN_COMMANDS (полученный из COMMAND_REGISTRY автоматически) включает каноническое имя. Если команда cli_only с gateway_config_gate, убедитесь, что значение закрытой конфигурации соответствует действительности.

Тактика отладки

Когда поверхностный осмотр не выявил ошибку:

Подводные камни

Проверка

После исправления:

  1. Восстановите TUI: bash cd /home/bb/hermes-agent && npm --prefix ui-tui run build
  2. Запустите TUI и проверьте команду: bash hermes --tui

  3. Введите / и убедитесь, что команда отображается в предложениях автозаполнения с ожидаемым описанием и подсказкой по аргументам.

  4. Выполните команду и подтвердите:

  5. Ожидаемое поведение пожаров
  6. Все сохраненные конфигурации корректно обновляются (read_file ~/.hermes/config.yaml)

  7. Состояние живого пользовательского интерфейса отражает изменение немедленно (а не только после перезапуска).

  8. Если команда также доступна для шлюза, протестируйте ее хотя бы на одной платформе обмена сообщениями (или запустите тесты шлюза: scripts/run_tests.shtest/gateway/).