mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-25 00:51:20 +00:00
docs: document register_command() for plugin slash commands (#10671)
* feat: implement register_command() on plugin context Complete the half-built plugin slash command system. The dispatch code in cli.py and gateway/run.py already called get_plugin_command_handler() but the registration side was never implemented. Changes: - Add register_command() to PluginContext — stores handler, description, and plugin name; normalizes names; rejects conflicts with built-in commands - Add _plugin_commands dict to PluginManager - Add commands_registered tracking on LoadedPlugin - Add get_plugin_command_handler() and get_plugin_commands() module-level convenience functions - Fix commands.py to use actual plugin description in Telegram bot menu (was hardcoded 'Plugin command') - Add plugin commands to SlashCommandCompleter autocomplete - Show command count in /plugins display - 12 new tests covering registration, conflict detection, normalization, handler dispatch, and introspection Closes #10495 * docs: add register_command() to plugin guides - Build a Plugin guide: new 'Register slash commands' section with full API reference, comparison table vs register_cli_command(), sync/async examples, and conflict protection docs - Features/Plugins page: add slash commands to capabilities table and plugin types summary
This commit is contained in:
parent
498b995c13
commit
fb903b8f08
2 changed files with 54 additions and 2 deletions
|
|
@ -561,8 +561,59 @@ After registration, users can run `hermes my-plugin status`, `hermes my-plugin c
|
|||
|
||||
**Active-provider gating:** Memory plugin CLI commands only appear when their provider is the active `memory.provider` in config. If a user hasn't set up your provider, your CLI commands won't clutter the help output.
|
||||
|
||||
### Register slash commands
|
||||
|
||||
Plugins can register in-session slash commands — commands users type during a conversation (like `/lcm status` or `/ping`). These work in both CLI and gateway (Telegram, Discord, etc.).
|
||||
|
||||
```python
|
||||
def _handle_status(raw_args: str) -> str:
|
||||
"""Handler for /mystatus — called with everything after the command name."""
|
||||
if raw_args.strip() == "help":
|
||||
return "Usage: /mystatus [help|check]"
|
||||
return "Plugin status: all systems nominal"
|
||||
|
||||
def register(ctx):
|
||||
ctx.register_command(
|
||||
"mystatus",
|
||||
handler=_handle_status,
|
||||
description="Show plugin status",
|
||||
)
|
||||
```
|
||||
|
||||
After registration, users can type `/mystatus` in any session. The command appears in autocomplete, `/help` output, and the Telegram bot menu.
|
||||
|
||||
**Signature:** `ctx.register_command(name: str, handler: Callable, description: str = "")`
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `name` | `str` | Command name without the leading slash (e.g. `"lcm"`, `"mystatus"`) |
|
||||
| `handler` | `Callable[[str], str \| None]` | Called with the raw argument string. May also be `async`. |
|
||||
| `description` | `str` | Shown in `/help`, autocomplete, and Telegram bot menu |
|
||||
|
||||
**Key differences from `register_cli_command()`:**
|
||||
|
||||
| | `register_command()` | `register_cli_command()` |
|
||||
|---|---|---|
|
||||
| Invoked as | `/name` in a session | `hermes name` in a terminal |
|
||||
| Where it works | CLI sessions, Telegram, Discord, etc. | Terminal only |
|
||||
| Handler receives | Raw args string | argparse `Namespace` |
|
||||
| Use case | Diagnostics, status, quick actions | Complex subcommand trees, setup wizards |
|
||||
|
||||
**Conflict protection:** If a plugin tries to register a name that conflicts with a built-in command (`help`, `model`, `new`, etc.), the registration is silently rejected with a log warning. Built-in commands always take precedence.
|
||||
|
||||
**Async handlers:** The gateway dispatch automatically detects and awaits async handlers, so you can use either sync or async functions:
|
||||
|
||||
```python
|
||||
async def _handle_check(raw_args: str) -> str:
|
||||
result = await some_async_operation()
|
||||
return f"Check result: {result}"
|
||||
|
||||
def register(ctx):
|
||||
ctx.register_command("check", handler=_handle_check, description="Run async check")
|
||||
```
|
||||
|
||||
:::tip
|
||||
This guide covers **general plugins** (tools, hooks, CLI commands). For specialized plugin types, see:
|
||||
This guide covers **general plugins** (tools, hooks, slash commands, CLI commands). For specialized plugin types, see:
|
||||
- [Memory Provider Plugins](/docs/developer-guide/memory-provider-plugin) — cross-session knowledge backends
|
||||
- [Context Engine Plugins](/docs/developer-guide/context-engine-plugin) — alternative context management strategies
|
||||
:::
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue