diff --git a/hermes_cli/commands.py b/hermes_cli/commands.py index 42e51f29909..4141f8852e9 100644 --- a/hermes_cli/commands.py +++ b/hermes_cli/commands.py @@ -215,7 +215,8 @@ COMMAND_REGISTRY: list[CommandDef] = [ gateway_only=True), CommandDef("usage", "Show token usage and rate limits for the current session", "Info"), CommandDef("credits", "Show Nous credit balance and top up", "Info"), - CommandDef("billing", "Manage Nous terminal billing — buy credits, auto-reload, limits", "Info"), + CommandDef("billing", "Manage Nous terminal billing — buy credits, auto-reload, limits", "Info", + cli_only=True), CommandDef("insights", "Show usage insights and analytics", "Info", args_hint="[days]"), CommandDef("platforms", "Show gateway/messaging platform status", "Info", diff --git a/website/docs/reference/slash-commands.md b/website/docs/reference/slash-commands.md index a9951263d7f..6f36eb015bd 100644 --- a/website/docs/reference/slash-commands.md +++ b/website/docs/reference/slash-commands.md @@ -90,6 +90,8 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in | `/memory [pending\|approve\|reject\|approval]` | Review pending memory writes staged by the write-approval gate (`memory.write_approval`) and toggle the gate. See [Controlling memory writes](/user-guide/features/memory#controlling-memory-writes-write_approval). | | `/bundles` | List configured skill bundles — `/` slash aliases that preload several skills at once. Configure under `bundles:` in `~/.hermes/config.yaml`. See [Skill Bundles](/user-guide/features/skills#skill-bundles). | | `/cron` | Manage scheduled tasks (list, add/create, edit, pause, resume, run, remove) | +| `/suggestions [accept\|dismiss N\|catalog\|clear]` (alias: `/suggest`) | Review suggested automations. Use `/suggestions` to list pending suggestions, `/suggestions accept ` to create the proposed automation, `/suggestions dismiss ` to reject one, `/suggestions catalog` to add curated starter automations, and `/suggestions clear` to clear resolved suggestion records. Accepted jobs preserve the current surface as the delivery origin. | +| `/blueprint [name] [slot=value ...]` (alias: `/bp`) | Set up an automation from a blueprint template. Bare `/blueprint` lists the catalog; `/blueprint ` starts a guided slot-filling flow on the next agent turn; `/blueprint slot=value ...` creates the job directly. | | `/curator` | Background skill maintenance — `status`, `run`, `pin`, `archive`. See [Curator](/user-guide/features/curator). | | `/kanban ` | Drive the multi-profile, multi-project collaboration board without leaving chat. Full `hermes kanban` surface is available: `/kanban list`, `/kanban show t_abc`, `/kanban create "title" --assignee X`, `/kanban comment t_abc "text"`, `/kanban unblock t_abc`, `/kanban dispatch`, etc. Multi-board support included: `/kanban boards list`, `/kanban boards create `, `/kanban boards switch `, `/kanban --board `. See [Kanban slash command](/user-guide/features/kanban#kanban-slash-command). | | `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config.yaml | @@ -104,9 +106,10 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in | `/help` | Show this help message | | `/version` | Show Hermes Agent version, build, and environment info. | | `/usage` | Show token usage, cost breakdown, session duration, and — when available from the active provider — an **Account limits** section with remaining quota / credits / plan usage pulled live from the provider's API. | +| `/credits` | Show your Nous credit balance and a top-up handoff link. | +| `/billing` | CLI terminal-billing flow for Nous — view balance, buy credits, and manage auto-reload / monthly limits. | | `/insights` | Show usage insights and analytics (last 30 days) | | `/platforms` (alias: `/gateway`) | Show gateway/messaging platform status (CLI-only summary view). | -| `/platform [name]` | Operate a running gateway platform. `/platform list` lists every adapter and its state (running, paused-by-breaker, manually-paused); `/platform pause ` stops dispatching new messages to that adapter without unloading it; `/platform resume ` re-enables it. The gateway also auto-pauses an adapter when its circuit breaker trips on repeated retryable failures (network / rate-limit / 5xx) — use `/platform resume ` to clear the breaker once the upstream is healthy. Available wherever the gateway is reachable (CLI session, Telegram, Discord, …). | | `/paste` | Attach a clipboard image | | `/copy [number]` | Copy the last assistant response to clipboard (or the Nth-from-last with a number). CLI-only. | | `/image ` | Attach a local image file for your next prompt. | @@ -213,6 +216,7 @@ The messaging gateway supports the following built-in commands inside Telegram, | `/title [name]` | Set or show the session title. | | `/resume [name]` | Resume a previously named session. | | `/usage` | Show token usage, estimated cost breakdown (input/output), context window state, session duration, and — when available from the active provider — an **Account limits** section with remaining quota / credits pulled live from the provider's API. | +| `/credits` | Show your Nous credit balance and a top-up link that opens the portal billing page in a browser. | | `/insights [days]` | Show usage analytics. | | `/reasoning [level\|show\|hide]` | Change reasoning effort or toggle reasoning display. | | `/voice [on\|off\|tts\|join\|channel\|leave\|status]` | Control spoken replies in chat. `join`/`channel`/`leave` manage Discord voice-channel mode. | @@ -223,9 +227,12 @@ The messaging gateway supports the following built-in commands inside Telegram, | `/goal ` | Set a standing goal Hermes works toward across turns — our take on the Ralph loop. A judge model checks after each turn; if not done, Hermes auto-continues until it is, you pause/clear it, or the turn budget (default 20) is hit. Subcommands: `/goal status`, `/goal pause`, `/goal resume`, `/goal clear`. Safe to run mid-agent for status/pause/clear; setting a new goal requires `/stop` first. See [Persistent Goals](/user-guide/features/goals). | | `/footer [on\|off\|status]` | Toggle the runtime-metadata footer on final replies (shows model, context %, and cwd). | | `/curator [status\|run\|pin\|archive]` | Background skill maintenance controls. | +| `/suggestions [accept\|dismiss N\|catalog\|clear]` | Review suggested automations right in chat. `/suggestions` lists pending suggestions, `catalog` adds curated starter automations, and `clear` prunes resolved suggestion records. Accepted suggestions keep this chat/thread as the job delivery origin. | +| `/blueprint [name] [slot=value ...]` | Browse cron blueprints, start a guided slot-filling conversation, or create a blueprint job directly. Directly created jobs deliver back to the current chat/thread. | | `/memory [pending\|approve\|reject\|approval]` | Review pending memory writes staged by the write-approval gate (`memory.write_approval`) — approve or reject them right in chat — and toggle the gate with `/memory approval on\|off`. See [Controlling memory writes](/user-guide/features/memory#controlling-memory-writes-write_approval). | | `/skills [pending\|approve\|reject\|diff\|approval]` | Review pending **skill** writes staged by the write-approval gate (`skills.write_approval`). Shows a one-line gist per staged write; `/skills diff ` is truncated for chat — read the full diff on the CLI or in `~/.hermes/pending/skills/.json`. Only appears when the gate is on (or staged writes remain); search/install stay CLI-only. | | `/kanban ` | Drive the multi-profile, multi-project collaboration board from chat — identical argument surface to the CLI. Bypasses the running-agent guard, so `/kanban unblock t_abc`, `/kanban comment t_abc "…"`, `/kanban list --mine`, `/kanban boards switch `, etc. work mid-turn. `/kanban create …` auto-subscribes the originating chat to the new task's terminal events. See [Kanban slash command](/user-guide/features/kanban#kanban-slash-command). | +| `/platform [name]` | Operate a running gateway platform right from chat. `/platform list` shows every adapter and its state (running, paused-by-breaker, manually-paused); `/platform pause ` stops dispatching new messages to that adapter without unloading it; `/platform resume ` re-enables it and clears a tripped circuit breaker once the upstream is healthy. | | `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config. | | `/yolo` | Toggle YOLO mode — skip all dangerous command approval prompts. | | `/commands [page]` | Browse all commands and skills (paginated). | @@ -239,11 +246,11 @@ The messaging gateway supports the following built-in commands inside Telegram, ## Notes -- `/skin`, `/snapshot`, `/gquota`, `/reload`, `/tools`, `/toolsets`, `/browser`, `/config`, `/cron`, `/platforms`, `/paste`, `/image`, `/statusbar`, `/plugins`, `/busy`, `/indicator`, `/redraw`, `/clear`, `/history`, `/save`, `/copy`, `/handoff`, and `/quit` are **CLI-only** commands. +- `/skin`, `/snapshot`, `/gquota`, `/reload`, `/tools`, `/toolsets`, `/browser`, `/config`, `/cron`, `/platforms`, `/paste`, `/image`, `/statusbar`, `/plugins`, `/busy`, `/indicator`, `/redraw`, `/clear`, `/history`, `/save`, `/copy`, `/handoff`, `/billing`, and `/quit` are **CLI-only** commands. - `/skills` is **CLI-only for search/browse/install**; its write-approval review subcommands (`pending`, `approve`, `reject`, `diff`, `approval`) also work on messaging platforms when `skills.write_approval` is on. `/memory` works on **both** surfaces. - `/verbose` is **CLI-only by default**, but can be enabled for messaging platforms by setting `display.tool_progress_command: true` in `config.yaml`. When enabled, it cycles the `display.tool_progress` mode and saves to config. -- `/sethome`, `/update`, `/restart`, `/approve`, `/deny`, `/topic`, and `/commands` are **messaging-only** commands. -- `/status`, `/version`, `/background`, `/queue`, `/steer`, `/voice`, `/reload-mcp`, `/reload-skills`, `/rollback`, `/debug`, `/fast`, `/footer`, `/curator`, `/kanban`, `/sessions`, and `/yolo` work in **both** the CLI and the messaging gateway. +- `/sethome`, `/update`, `/restart`, `/approve`, `/deny`, `/topic`, `/platform`, and `/commands` are **messaging-only** commands. +- `/status`, `/version`, `/background`, `/queue`, `/steer`, `/voice`, `/reload-mcp`, `/reload-skills`, `/rollback`, `/debug`, `/fast`, `/footer`, `/curator`, `/kanban`, `/credits`, `/suggestions`, `/blueprint`, `/sessions`, and `/yolo` work in **both** the CLI and the messaging gateway. - `/voice join`, `/voice channel`, and `/voice leave` are only meaningful on Discord. - In the TUI, `/sessions` shows live sessions in the current TUI process. Use `/resume [name]` or `hermes --tui --resume ` for saved or closed transcripts. diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/environment-variables.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/environment-variables.md index 52ed671891b..72f6a49387a 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/environment-variables.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/environment-variables.md @@ -519,6 +519,7 @@ Graph 事件（Teams 会议、日历、聊天等）的入站变更通知监听 | `HERMES_GATEWAY_BUSY_INPUT_MODE` | 默认 gateway 繁忙输入行为：`queue`、`steer` 或 `interrupt`。可通过 `/busy` 按聊天覆盖。 | | `HERMES_GATEWAY_BUSY_ACK_ENABLED` | gateway 是否在用户 agent 繁忙时发送确认消息（⚡/⏳/⏩）（默认：`true`）。设为 `false` 可完全抑制这些消息——输入仍会正常排队/引导/中断，只是聊天回复被静默。从 `config.yaml` 中的 `display.busy_ack_enabled` 桥接。 | | `HERMES_GATEWAY_NO_SUPERVISE` | 在 s6-overlay Docker 镜像内部运行 `hermes gateway run` 时跳过 s6 自动监管，退回到 pre-s6 前台语义（无自动重启，gateway 作为容器主进程）。真值：`1`、`true`、`yes`。等同于 `--no-supervise` CLI 标志。在 s6 镜像之外为空操作。 | +| `HERMES_GATEWAY_BOOTSTRAP_STATE` | 在 s6-overlay Docker 镜像内部，为**全新卷**声明 gateway 的初始受监管状态。空白卷上不存在持久化的 `gateway_state.json`，因此启动协调器会注册 `gateway-default` 槽位但保持其**关闭**（只有上次记录状态为 `running` 时才会自动启动）。将此变量设为 `running` 后，首次启动 hook 会在协调器运行前预写入 `gateway_state.json`，从而让 gateway 在第一次启动时就自动拉起。仅字面值 `running` 生效。仅影响首次启动：若已有 `gateway_state.json`，绝不会被覆盖，因此被刻意停止的 gateway 在重启后仍保持停止。在 s6 镜像之外为空操作。 | | `HERMES_FILE_MUTATION_VERIFIER` | 启用每轮文件变更验证器页脚（默认：`true`）。启用后，Hermes 附加一个建议列表，列出本轮中失败且未被成功写入覆盖的 `write_file`/`patch` 调用。设为 `0`、`false`、`no` 或 `off` 可抑制。镜像 `config.yaml` 中的 `display.file_mutation_verifier`；设置时环境变量优先。 | | `HERMES_CRON_TIMEOUT` | cron 任务 agent 运行的不活动超时（秒，默认：`600`）。agent 在主动调用工具或接收流 token 时可无限运行——仅在空闲时触发。设为 `0` 表示无限制。 | | `HERMES_CRON_SCRIPT_TIMEOUT` | cron 任务附加的预运行脚本超时（秒，默认：`120`）。对需要更长执行时间的脚本（例如随机延迟的反机器人计时）可增大此值。也可通过 `config.yaml` 中的 `cron.script_timeout_seconds` 配置。 | @@ -534,6 +535,7 @@ Graph 事件（Teams 会议、日历、聊天等）的入站变更通知监听 | `HERMES_ACCEPT_HOOKS` | 无需 TTY 提示自动批准 `config.yaml` 中声明的任何未见过的 shell hook。等同于 `--accept-hooks` 或 `hooks_auto_accept: true`。 | | `HERMES_IGNORE_USER_CONFIG` | 跳过 `~/.hermes/config.yaml` 并使用内置默认值（`.env` 中的凭证仍会加载）。等同于 `--ignore-user-config`。 | | `HERMES_IGNORE_RULES` | 跳过 `AGENTS.md`、`SOUL.md`、`.cursorrules`、记忆和预加载技能的自动注入。等同于 `--ignore-rules`。 | +| `HERMES_SAFE_MODE` | 故障排查模式：禁用**所有**自定义项——跳过插件发现和 MCP 服务器加载。由 `--safe-mode` 自动设置（同时也会设置上面两个 flag）。 | | `HERMES_MD_NAMES` | 自动注入的规则文件名逗号分隔列表（默认：`AGENTS.md,CLAUDE.md,.cursorrules,SOUL.md`）。 | | `HERMES_TOOL_PROGRESS` | 工具进度显示的已弃用兼容变量。优先使用 `config.yaml` 中的 `display.tool_progress`。 | | `HERMES_TOOL_PROGRESS_MODE` | 工具进度模式的已弃用兼容变量。优先使用 `config.yaml` 中的 `display.tool_progress`。 | @@ -561,6 +563,7 @@ Graph 事件（Teams 会议、日历、聊天等）的入站变更通知监听 | `HERMES_ALLOW_PRIVATE_URLS` | `true`/`false`——允许工具获取 localhost/私有网络 URL。gateway 模式下默认关闭。 | | `HERMES_REDACT_SECRETS` | `true`/`false`——控制工具输出、日志和聊天响应中的密钥脱敏（默认：`true`）。 | | `HERMES_WRITE_SAFE_ROOT` | 可选目录前缀，限制 `write_file`/`patch` 写入；超出范围的路径需要审批。 | +| `HERMES_DISABLE_LAZY_INSTALLS` | 官方 Docker 镜像中自动设置的内部桥接变量，用于阻止运行时将依赖安装到不可变的 `/opt/hermes` 树。面向用户的等价配置是 `config.yaml` 中的 `security.allow_lazy_installs: false`；不要在 `.env` 中手动设置此变量。 | | `HERMES_DISABLE_FILE_STATE_GUARD` | 设为 `1` 可关闭 `patch`/`write_file` 上的"文件自上次读取后已更改"保护。 | | `HERMES_CORE_TOOLS` | 规范核心工具列表的逗号分隔覆盖（高级；极少需要）。 | | `HERMES_BUNDLED_SKILLS` | 启动时加载的内置技能列表的逗号分隔覆盖。 | diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/slash-commands.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/slash-commands.md index 9fb39a9f8bf..665a6a3579b 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/slash-commands.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/slash-commands.md @@ -87,7 +87,11 @@ Hermes 有两个斜杠命令入口，均由 `hermes_cli/commands.py` 中的中 | `/toolsets` | 列出可用工具集 | | `/browser [connect\|disconnect\|status]` | 管理本地 Chromium 系浏览器的 CDP 连接。`connect` 将浏览器工具附加到正在运行的 Chrome、Brave、Chromium 或 Edge 实例（默认：`http://127.0.0.1:9222`）。`disconnect` 断开连接。`status` 显示当前连接状态。若未检测到调试器，则自动启动支持的 Chromium 系浏览器。 | | `/skills` | 从在线注册表搜索、安装、检查或管理 skill | +| `/memory [pending\|approve\|reject\|approval]` | 审核由写入审批门控（`memory.write_approval`）暂存的待处理 memory 写入，并切换该门控。见 [Memory 功能](/user-guide/features/memory)。 | +| `/bundles` | 列出已配置的 skill bundle——即一次预加载多个 skill 的 `/` 斜杠别名。在 `~/.hermes/config.yaml` 的 `bundles:` 下配置。见 [Skills 功能](/user-guide/features/skills)。 | | `/cron` | 管理定时任务（列出、添加/创建、编辑、暂停、恢复、运行、删除） | +| `/suggestions [accept\|dismiss N\|catalog\|clear]`（别名：`/suggest`） | 审核建议的自动化。使用 `/suggestions` 列出待处理建议，`/suggestions accept ` 接受并创建建议任务，`/suggestions dismiss ` 拒绝单条建议，`/suggestions catalog` 添加精选起步自动化，`/suggestions clear` 清理已解决的建议记录。被接受的任务会保留当前表面作为投递来源。 | +| `/blueprint [name] [slot=value ...]`（别名：`/bp`） | 通过 blueprint 模板设置自动化。裸 `/blueprint` 列出目录；`/blueprint ` 会在下一次 agent 轮次启动引导式填槽流程；`/blueprint slot=value ...` 直接创建任务。 | | `/curator` | 后台 skill 维护——`status`、`run`、`pin`、`archive`。见 [Curator](/user-guide/features/curator)。 | | `/kanban ` | 无需离开聊天即可操作多 profile、多项目协作看板。完整的 `hermes kanban` 命令面均可用：`/kanban list`、`/kanban show t_abc`、`/kanban create "title" --assignee X`、`/kanban comment t_abc "text"`、`/kanban unblock t_abc`、`/kanban dispatch` 等。支持多看板：`/kanban boards list`、`/kanban boards create `、`/kanban boards switch `、`/kanban --board `。见 [Kanban 斜杠命令](/user-guide/features/kanban#kanban-slash-command)。 | | `/reload-mcp`（别名：`/reload_mcp`） | 从 config.yaml 重新加载 MCP 服务器 | @@ -102,9 +106,10 @@ Hermes 有两个斜杠命令入口，均由 `hermes_cli/commands.py` 中的中 | `/help` | 显示帮助信息 | | `/version` | 显示 Hermes Agent 版本、构建及环境信息。 | | `/usage` | 显示 token 用量、费用明细、会话时长，以及——当活动提供商支持时——从提供商 API 实时拉取的**账户限额**部分，包含剩余配额/积分/套餐用量。 | +| `/credits` | 显示你的 Nous 积分余额和充值跳转链接。 | +| `/billing` | Nous 的 CLI 终端计费流程——查看余额、购买积分并管理自动充值 / 月度限额。 | | `/insights` | 显示用量洞察和分析（最近 30 天） | | `/platforms`（别名：`/gateway`） | 显示 gateway/消息平台状态（仅限 CLI 摘要视图）。 | -| `/platform [name]` | 操作正在运行的 gateway 平台。`/platform list` 列出所有适配器及其状态（运行中、熔断器暂停、手动暂停）；`/platform pause ` 停止向该适配器分发新消息但不卸载它；`/platform resume ` 重新启用它。当适配器的熔断器因反复可重试失败（网络/限流/5xx）触发时，gateway 也会自动暂停该适配器——上游恢复健康后使用 `/platform resume ` 清除熔断器。在 gateway 可达的任何地方均可使用（CLI 会话、Telegram、Discord 等）。 | | `/paste` | 附加剪贴板图片 | | `/copy [number]` | 将最后一条助手回复复制到剪贴板（或用数字指定倒数第 N 条）。仅限 CLI。 | | `/image ` | 为下一条 prompt 附加本地图片文件。 | @@ -194,6 +199,7 @@ hermes config set model.aliases.grok x-ai/grok-4 | 命令 | 描述 | |---------|-------------| +| `/start` | 平台协议命令。许多聊天平台（Telegram、Discord 等）会在用户首次打开 bot 对话时自动发送 `/start`。Hermes 会静默确认这个 ping——不触发 agent 回复，也不消耗会话轮次——因此首次握手不会浪费一次对话。你也可以显式发送它来确认 gateway 可达。 | | `/new` | 开始新对话。 | | `/reset` | 重置对话历史。 | | `/status` | 显示会话信息，随后显示本地**会话摘要**块（近期轮次数、最常用工具、访问的文件、最新 prompt + 回复）。 | @@ -210,6 +216,7 @@ hermes config set model.aliases.grok x-ai/grok-4 | `/title [name]` | 设置或显示会话标题。 | | `/resume [name]` | 恢复之前命名的会话。 | | `/usage` | 显示 token 用量、估算费用明细（输入/输出）、上下文窗口状态、会话时长，以及——当活动提供商支持时——从提供商 API 实时拉取的**账户限额**部分，包含剩余配额/积分。 | +| `/credits` | 显示你的 Nous 积分余额，以及会在浏览器中打开 portal 计费页的充值链接。 | | `/insights [days]` | 显示用量分析。 | | `/reasoning [level\|show\|hide]` | 更改推理力度或切换推理显示。 | | `/voice [on\|off\|tts\|join\|channel\|leave\|status]` | 控制聊天中的语音回复。`join`/`channel`/`leave` 管理 Discord 语音频道模式。 | @@ -220,7 +227,12 @@ hermes config set model.aliases.grok x-ai/grok-4 | `/goal ` | 设置一个持续目标，Hermes 将跨轮次持续推进——这是我们对 Ralph loop 的实现。裁判模型在每轮后检查；若未完成，Hermes 自动继续，直到完成、你暂停/清除，或达到轮次预算（默认 20）。子命令：`/goal status`、`/goal pause`、`/goal resume`、`/goal clear`。agent 运行中可安全执行 status/pause/clear；设置新目标需先执行 `/stop`。见 [持续目标](/user-guide/features/goals)。 | | `/footer [on\|off\|status]` | 切换最终回复中的运行时元数据页脚（显示模型、工具调用次数、耗时）。 | | `/curator [status\|run\|pin\|archive]` | 后台 skill 维护控制。 | +| `/suggestions [accept\|dismiss N\|catalog\|clear]` | 直接在聊天中审核建议的自动化。`/suggestions` 列出待处理建议，`catalog` 添加精选起步自动化，`clear` 清理已解决的建议记录。被接受的建议会保留当前聊天/线程作为任务投递来源。 | +| `/blueprint [name] [slot=value ...]` | 浏览 cron blueprint、启动引导式填槽对话，或直接创建 blueprint 任务。直接创建的任务会回投到当前聊天/线程。 | +| `/memory [pending\|approve\|reject\|approval]` | 审核由写入审批门控（`memory.write_approval`）暂存的待处理 memory 写入——可直接在聊天中批准或拒绝——并通过 `/memory approval on\|off` 切换门控。见 [Memory 功能](/user-guide/features/memory)。 | +| `/skills [pending\|approve\|reject\|diff\|approval]` | 审核由写入审批门控（`skills.write_approval`）暂存的待处理 **skill** 写入。每条待写入会显示一行摘要；`/skills diff ` 在聊天中会截断——完整 diff 请在 CLI 或 `~/.hermes/pending/skills/.json` 中查看。仅当门控开启（或仍有待处理写入）时出现；搜索/安装仍然是 CLI-only。 | | `/kanban ` | 从聊天中操作多 profile、多项目协作看板——参数与 CLI 完全一致。绕过运行中 agent 的保护，因此 `/kanban unblock t_abc`、`/kanban comment t_abc "…"`、`/kanban list --mine`、`/kanban boards switch ` 等均可在轮次进行中使用。`/kanban create …` 会自动将发起聊天订阅到新任务的终态事件。见 [Kanban 斜杠命令](/user-guide/features/kanban#kanban-slash-command)。 | +| `/platform [name]` | 直接在聊天中操作正在运行的 gateway 平台。`/platform list` 列出所有适配器及其状态（运行中、熔断器暂停、手动暂停）；`/platform pause ` 停止向该适配器分发新消息但不卸载它；`/platform resume ` 重新启用它，并在上游恢复健康后清除已触发的熔断器。 | | `/reload-mcp`（别名：`/reload_mcp`） | 从配置重新加载 MCP 服务器。 | | `/yolo` | 切换 YOLO 模式——跳过所有危险命令审批提示。 | | `/commands [page]` | 浏览所有命令和 skill（分页）。 | @@ -234,10 +246,11 @@ hermes config set model.aliases.grok x-ai/grok-4 ## 注意事项 -- `/skin`、`/snapshot`、`/gquota`、`/reload`、`/tools`、`/toolsets`、`/browser`、`/config`、`/cron`、`/skills`、`/platforms`、`/paste`、`/image`、`/statusbar`、`/plugins`、`/busy`、`/indicator`、`/redraw`、`/clear`、`/history`、`/save`、`/copy`、`/handoff` 和 `/quit` 是**仅限 CLI** 的命令。 +- `/skin`、`/snapshot`、`/gquota`、`/reload`、`/tools`、`/toolsets`、`/browser`、`/config`、`/cron`、`/platforms`、`/paste`、`/image`、`/statusbar`、`/plugins`、`/busy`、`/indicator`、`/redraw`、`/clear`、`/history`、`/save`、`/copy`、`/handoff`、`/billing` 和 `/quit` 是**仅限 CLI** 的命令。 +- `/skills` **仅在搜索/浏览/安装时属于 CLI-only**；其写入审批子命令（`pending`、`approve`、`reject`、`diff`、`approval`）在 `skills.write_approval` 开启时也可在消息平台使用。`/memory` 可在**两个表面**使用。 - `/verbose` **默认仅限 CLI**，但可通过在 `config.yaml` 中设置 `display.tool_progress_command: true` 为消息平台启用。启用后，它会循环切换 `display.tool_progress` 模式并保存到配置。 -- `/sethome`、`/update`、`/restart`、`/approve`、`/deny`、`/topic` 和 `/commands` 是**仅限消息平台**的命令。 -- `/status`、`/version`、`/background`、`/queue`、`/steer`、`/voice`、`/reload-mcp`、`/reload-skills`、`/rollback`、`/debug`、`/fast`、`/footer`、`/curator`、`/kanban`、`/sessions` 和 `/yolo` 在 **CLI 和消息 gateway 中均可使用**。 +- `/sethome`、`/update`、`/restart`、`/approve`、`/deny`、`/topic`、`/platform` 和 `/commands` 是**仅限消息平台**的命令。 +- `/status`、`/version`、`/background`、`/queue`、`/steer`、`/voice`、`/reload-mcp`、`/reload-skills`、`/rollback`、`/debug`、`/fast`、`/footer`、`/curator`、`/kanban`、`/credits`、`/suggestions`、`/blueprint`、`/sessions` 和 `/yolo` 在 **CLI 和消息 gateway 中均可使用**。 - `/voice join`、`/voice channel` 和 `/voice leave` 仅在 Discord 上有意义。 ## 破坏性命令的确认提示 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/docker.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/docker.md index 09621039883..8ab80266e3b 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/docker.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/docker.md @@ -60,7 +60,7 @@ docker run -d \ ## 运行 dashboard -内置 Web dashboard 作为可选的子进程在与 gateway 相同的容器内运行。设置 `HERMES_DASHBOARD=1` 可在容器回环地址（`127.0.0.1`）上默认运行 dashboard： +内置 Web dashboard 在同一容器内作为受 s6-rc 监管的服务与 gateway 并行运行。设置 `HERMES_DASHBOARD=1` 即可拉起它： ```sh docker run -d \ @@ -68,32 +68,34 @@ docker run -d \ --restart unless-stopped \ -v ~/.hermes:/opt/data \ -p 8642:8642 \ + -p 9119:9119 \ -e HERMES_DASHBOARD=1 \ nousresearch/hermes-agent gateway run ``` -入口点在 `exec` 主命令之前，以非 root 用户 `hermes` 在后台启动 `hermes dashboard`。Dashboard 输出在 `docker logs` 中以 `[dashboard]` 为前缀，便于与 gateway 日志区分。 +Dashboard 由 s6 监管：若进程崩溃，`s6-supervise` 会在短暂退避后自动重启。Dashboard 的 stdout/stderr 会直接转发到 `docker logs `；gateway 的主输出现在写入每个 profile 的 s6 日志文件，见下方的 per-profile 日志说明。 | 环境变量 | 描述 | 默认值 | |---------------------|-------------|---------| -| `HERMES_DASHBOARD` | 设为 `1`（或 `true` / `yes`）以在主命令旁启动 dashboard | *（未设置——不启动 dashboard）* | -| `HERMES_DASHBOARD_HOST` | dashboard HTTP 服务器的绑定地址 | `127.0.0.1` | +| `HERMES_DASHBOARD` | 设为 `1`（或 `true` / `yes`）以启用受监管的 dashboard 服务 | *（未设置——服务已注册但保持关闭）* | +| `HERMES_DASHBOARD_HOST` | dashboard HTTP 服务器的绑定地址 | `0.0.0.0` | | `HERMES_DASHBOARD_PORT` | dashboard HTTP 服务器的端口 | `9119` | | `HERMES_DASHBOARD_INSECURE` | 设为 `1`（或 `true` / `yes`）以在不启用 OAuth 鉴权门控的情况下绑定。仅在可信网络（且通过没有 OAuth 契约的反向代理时）使用——dashboard 会暴露 API 密钥与会话数据 | *（未设置——当注册了 `DashboardAuthProvider` 时启用门控）* | -默认情况下，dashboard 保持在回环地址（`127.0.0.1`），以避免将 -Web 界面暴露到网络。若要有意发布，请设置 -`HERMES_DASHBOARD_HOST=0.0.0.0`。当以下两项同时满足时， -dashboard 的 OAuth 鉴权门控会自动启用： +容器内的 dashboard 默认绑定 `0.0.0.0`，否则发布的 `-p 9119:9119` 端口将无法从宿主机访问。若你要把它限制在容器回环地址（例如 sidecar / 反向代理拓扑），请显式设置 `HERMES_DASHBOARD_HOST=127.0.0.1`。 + +当以下两项同时满足时，dashboard 的鉴权门控会自动启用： 1. 绑定地址为非回环地址，**且** 2. 注册了一个 `DashboardAuthProvider` 插件。 -捆绑的 `dashboard_auth/nous` 提供者会在设置 -`HERMES_DASHBOARD_OAUTH_CLIENT_ID` 时自动激活（参见 -[Web Dashboard → 鉴权](features/web-dashboard.md)）。门控启用后， -浏览器调用方会先被重定向到所配置门户的 OAuth 流，然后才能 -访问任何受保护路由。 +有三种内置方式可满足第二个条件： + +- **用户名/密码** —— 最简单的自托管 / 局域网 / VPN 内部署方式：设置 `HERMES_DASHBOARD_BASIC_AUTH_USERNAME` + `HERMES_DASHBOARD_BASIC_AUTH_PASSWORD`（以及用于跨重启稳定 session 的 `HERMES_DASHBOARD_BASIC_AUTH_SECRET`）。不适合直接暴露到公网上。 +- **OAuth（Nous Portal）** —— 适合托管/公网部署：设置 `HERMES_DASHBOARD_OAUTH_CLIENT_ID` 后，`dashboard_auth/nous` 提供者会自动激活。 +- **自托管 OIDC** —— 通过标准 OpenID Connect 接入你自己的身份提供商：设置 `HERMES_DASHBOARD_OIDC_ISSUER` + `HERMES_DASHBOARD_OIDC_CLIENT_ID` 后，`dashboard_auth/self_hosted` 提供者会激活。 + +无论选择哪种，调用方在访问受保护路由前都会先被重定向到登录页。完整说明见 [Web Dashboard → 鉴权](features/web-dashboard.md)。 如果未注册提供者且绑定为非回环地址，dashboard **会在启动时 失败关闭**，并给出指向缺失环境变量的具体错误信息。要显式 @@ -102,14 +104,11 @@ dashboard 的 OAuth 鉴权门控会自动启用： 这会恢复旧的“无鉴权，但发出告警”模式，也是唯一可以禁用门控的 路径；绑定地址不再隐式决定 `--insecure`。 -:::note -dashboard 在容器内作为受监管的 s6 服务运行。如果 -dashboard 进程崩溃，s6-overlay 会在短暂退避后自动 -重启它——你会看到新的 PID，无需重启容器。日志和崩溃输出可通过 -`docker logs ` 查看（s6 将服务的 stdout/stderr 转发至此）。 +:::warning `HERMES_DASHBOARD_INSECURE=1` 会暴露 API 密钥 +关闭鉴权门控会让任何能访问已发布端口的人都能看到 dashboard 的 API 面（包括模型密钥与会话数据）。除非你前面已经有自己的鉴权层，或它只运行在你完全信任的局域网内，否则不要启用它。 +::: 当独立的 dashboard 容器与宿主机共享 PID 与网络命名空间时（例如 `network_mode: host`，正如仓库自带的 `docker-compose.yml` 中的 `dashboard` 服务那样），**是**支持将 dashboard 作为独立容器运行的。其 gateway 存活检测需要与 gateway 进程共享 PID 命名空间，因此该限制仅适用于在隔离的 bridge 网络容器中、且未共享 PID 命名空间的 dashboard。 -::: ## 交互式运行（CLI 聊天） @@ -139,71 +138,53 @@ docker run -it --rm \ | `sessions/` | 对话历史 | | `memories/` | 持久化记忆存储 | | `skills/` | 已安装的技能 | +| `home/` | Hermes 工具子进程（`git`、`ssh`、`gh`、`npm` 及 skill CLI）的 per-profile HOME | | `cron/` | 定时任务定义 | | `hooks/` | 事件 hook | | `logs/` | 运行时日志 | | `skins/` | 自定义 CLI 皮肤 | +### 不可变安装树 + +在托管/发布的 Docker 镜像中，`/opt/hermes` 是安装好的应用树。它由 root 拥有，并且对运行时的 `hermes` 用户只读，因此 agent 回合、gateway 会话、dashboard 操作以及普通的 `docker exec hermes hermes ...` 命令都不能原地修改核心源码、打包的 `.venv`、`node_modules` 或 TUI bundle。 + +所有可变的 Hermes 状态都应位于 `/opt/data` 下：配置、`.env`、profiles、skills、memories、sessions、logs、dashboard 上传、plugins 以及其他用户管理的文件。官方镜像还会阻止在运行时向不可变的 `/opt/hermes` 树写入 `.pyc` 或执行 Hermes 的懒安装依赖流程。 + +如果运维人员确实需要修复或检查 `/opt/data` 之外的文件，请有意识地使用 root shell。`hermes` shim 默认会把 `docker exec hermes hermes ...` 降回运行时用户；只有在你明确需要 root 语义时，才临时设置 `HERMES_DOCKER_EXEC_AS_ROOT=1`。 + +某些 skill CLI 会把凭据写到 `~` 下，因此在官方 Docker 布局里要针对子进程 HOME 初始化，而不是只针对数据卷根目录。例如 [xurl skill](./skills/bundled/social-media/social-media-xurl.md) 会把 OAuth 状态存到 `~/.xurl`；在容器里这对应 `/opt/data/home/.xurl`，因此手动认证时应使用 `HOME=/opt/data/home xurl auth status` 之类的调用。 + :::warning 切勿同时对同一数据目录运行两个 Hermes **gateway** 容器——会话文件和记忆存储不支持并发写入。 ::: ## 多 profile 支持 -Hermes 支持[多个 profile](../reference/profile-commands.md)——独立的 `~/.hermes/` 目录，让你可以从单个安装运行独立的 agent（不同的 SOUL、技能、记忆、会话、凭据）。**在 Docker 下运行时，不建议使用 Hermes 内置的多 profile 功能。** +Hermes 支持[多个 profile](../reference/profile-commands.md)——独立的 `~/.hermes/` 子目录，让你可以从单个安装运行独立的 agent（不同的 SOUL、skills、memory、sessions、credentials）。**在官方 Docker 镜像内，s6 监管树把每个 profile 当作一等受监管服务**，因此推荐部署方式是：**一个容器承载多个 profile**。 -推荐的模式是**每个 profile 一个容器**，每个容器将各自的宿主机目录绑定挂载为 `/opt/data`： +每个通过 `hermes profile create ` 创建的 profile 都会获得： + +- 一个专用的 s6 服务槽位 `/run/service/gateway-/`，运行时动态注册，无需重建镜像。 +- 崩溃后的自动重启，由 `s6-supervise` 管理退避。 +- 每个 profile 独立的轮转日志：`${HERMES_HOME}/logs/gateways//current`。 +- 跨容器重启的状态持久化：启动协调器会读取该 profile 的 `gateway_state.json`，仅在上次记录状态为 `running` 时自动拉起。 + +容器内生命周期命令与宿主机上一致： ```sh -# 工作 profile -docker run -d \ - --name hermes-work \ - --restart unless-stopped \ - -v ~/.hermes-work:/opt/data \ - -p 8642:8642 \ - nousresearch/hermes-agent gateway run +# 创建 profile —— 同时注册 gateway- s6 槽位 +docker exec hermes hermes profile create coder -# 个人 profile -docker run -d \ - --name hermes-personal \ - --restart unless-stopped \ - -v ~/.hermes-personal:/opt/data \ - -p 8643:8642 \ - nousresearch/hermes-agent gateway run +# 启停/重启 —— 底层分发给 s6-svc +docker exec hermes hermes -p coder gateway start +docker exec hermes hermes -p coder gateway stop +docker exec hermes hermes -p coder gateway restart + +# 状态 —— 容器内会显示 `Manager: s6 (container supervisor)` +docker exec hermes hermes -p coder gateway status ``` -在 Docker 中使用独立容器而非 profile 的原因： - -- **隔离性** — 每个容器有独立的文件系统、进程表和资源限制。一个 profile 中的崩溃、依赖变更或失控会话不会影响另一个。 -- **独立生命周期** — 可独立升级、重启、暂停或回滚每个 agent（`docker restart hermes-work` 不会影响 `hermes-personal`）。 -- **清晰的端口和网络隔离** — 每个 gateway 绑定各自的宿主机端口；聊天平台或 API 服务器之间不存在串扰风险。 -- **更简单的心智模型** — 容器即 profile。备份、迁移和权限管理都跟随绑定挂载的目录，无需记住额外的 `--profile` 标志。 -- **避免并发写入风险** — 上述关于不得对同一数据目录运行两个 gateway 的警告同样适用于单个容器内的 profile。 - -在 Docker Compose 中，只需为每个 profile 声明一个服务，使用不同的 `container_name`、`volumes` 和 `ports`： - -```yaml -services: - hermes-work: - image: nousresearch/hermes-agent:latest - container_name: hermes-work - restart: unless-stopped - command: gateway run - ports: - - "8642:8642" - volumes: - - ~/.hermes-work:/opt/data - - hermes-personal: - image: nousresearch/hermes-agent:latest - container_name: hermes-personal - restart: unless-stopped - command: gateway run - ports: - - "8643:8642" - volumes: - - ~/.hermes-personal:/opt/data -``` +若第二个 profile 也要暴露 OpenAI 兼容 API server，请在**该 profile 自己的** `.env` 中设置不同的 `API_SERVER_PORT`，然后重启该 profile 的 gateway；不要把端口放进容器级 `environment:`，否则所有 profile 都会争抢同一个端口。更底层的监管细节见后文的 [Per-profile gateway 监管](#per-profile-gateway-监管)。 ## 环境变量转发 @@ -252,7 +233,7 @@ services: cpus: "2.0" ``` -使用 `docker compose up -d` 启动，使用 `docker compose logs -f` 查看日志。Dashboard 输出以 `[dashboard]` 为前缀，便于从 gateway 日志中过滤。 +使用 `docker compose up -d` 启动，使用 `docker compose logs -f` 查看日志。Dashboard 的 stdout/stderr 会直接出现在这里；gateway 主日志则写入每个 profile 的 s6 日志文件，见下方的 [Per-profile gateway 监管](#per-profile-gateway-监管)。 ## 资源限制