debugging-hermes-tui-commands

Hermes TUI のスラッシュコマンドのデバッグ

概要

Hermes のスラッシュコマンドは、Python のコマンドレジストリ、tui_gateway の JSON-RPC ブリッジ、Ink/TypeScript のフロントエンドという 3 つのレイヤーにまたがっています。コマンドが期待どおりに動作しない場合（オートコンプリートに表示されない、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 に表示される想定のタブ補完候補と一致していることを確認します。

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> コマンドでは、組み込みセクションのデフォルト設定をライブコマンドで上書きできるよう、個別のコマンドオーバーライドフラグが必要になる場合があります。一方、起動時や設定の同期時には、thinking/tools をデフォルトで展開した状態に維持します。

5. ゲートウェイのディスパッチでコマンドが黙って無視される。 ゲートウェイがディスパッチするのは、認識しているコマンドのみです。GATEWAY_KNOWN_COMMANDS（COMMAND_REGISTRY から自動的に生成されます）に正規名が含まれているか確認してください。コマンドが gateway_config_gate を伴う cli_only の場合は、ゲート対象の設定値が truthy であることを確認してください。

デバッグの手法

表面的な調査でバグの原因がわからない場合：

• 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 でコマンドに適切なカテゴリ（例：「Session」、「Configuration」、「Tools & Skills」、「Info」、「Exit」）を設定してください。
• エイリアスを aliases タプルに正しく登録してください。他のファイルを変更する必要はありません。以降の処理（Telegram のメニュー、Slack のマッピング、オートコンプリート、ヘルプ）はすべてこの設定から導出されます。
• サブコマンドがある場合は、CommandDef の subcommands タプルが TUI のコードと一致することを確認してください。
• cli_only=True のコマンドは、gateway_config_gate を追加してそのゲートが真になるようにしない限り、ゲートウェイ／メッセージングプラットフォームでは動作しません。
• ライブ UI の状態を追加した後は、古いプロパティやヘルパーを使っている箇所をすべて検索し、アクティブなストリーミング経路だけでなく、すべてのレンダリング経路に新しい状態を渡してください。TUI の詳細表示には、ライブの StreamingAssistant／ToolTrail と、トランスクリプト／保留中の MessageLine 行という、少なくとも 2 つの重要な経路があります。/clean での確認では、両方を明示的にチェックしてください。
• テストの前に TUI を再ビルドしてください（npm --prefix ui-tui run build）。tsx のウォッチモードは初回起動時に遅れることがあります。

検証

修正後：

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. コマンドがゲートウェイでも利用可能な場合は、少なくとも 1 つのメッセージングプラットフォームからテストします（または、ゲートウェイのテストを実行します：scripts/run_tests.sh tests/gateway/）。