Hermes-agent
This commit is contained in:
Zakaria
+275
@@ -0,0 +1,275 @@
|
||||
---
|
||||
sidebar_position: 11
|
||||
title: "ACP 编辑器集成"
|
||||
description: "在 VS Code、Zed 和 JetBrains 等兼容 ACP 的编辑器中使用 Hermes Agent"
|
||||
---
|
||||
|
||||
# ACP 编辑器集成
|
||||
|
||||
Hermes Agent 可作为 ACP 服务器运行，让兼容 ACP 的编辑器通过 stdio 与 Hermes 通信并渲染：
|
||||
|
||||
- 聊天消息
|
||||
- 工具活动
|
||||
- 文件差异
|
||||
- 终端命令
|
||||
- 审批 prompt（提示词）
|
||||
- 流式思考 / 响应块
|
||||
|
||||
当你希望 Hermes 表现得像编辑器原生的编码 agent，而非独立 CLI 或消息机器人时，ACP 是合适的选择。
|
||||
|
||||
## Hermes 在 ACP 模式下暴露的内容
|
||||
|
||||
Hermes 使用专为编辑器工作流设计的精选 `hermes-acp` 工具集运行，包括：
|
||||
|
||||
- 文件工具：`read_file`、`write_file`、`patch`、`search_files`
|
||||
- 终端工具：`terminal`、`process`
|
||||
- 网页/浏览器工具
|
||||
- 记忆、待办事项、会话搜索
|
||||
- skills
|
||||
- `execute_code` 和 `delegate_task`
|
||||
- 视觉
|
||||
|
||||
它有意排除了不适合典型编辑器 UX 的功能，例如消息投递和 cronjob 管理。
|
||||
|
||||
## 安装
|
||||
|
||||
正常安装 Hermes 后，添加 ACP 扩展：
|
||||
|
||||
```bash
|
||||
pip install -e '.[acp]'
|
||||
```
|
||||
|
||||
这将安装 `agent-client-protocol` 依赖并启用：
|
||||
|
||||
- `hermes acp`
|
||||
- `hermes-acp`
|
||||
- `python -m acp_adapter`
|
||||
|
||||
对于 Zed registry 安装，Zed 通过官方 ACP Registry 条目启动 Hermes。该条目使用 `uvx` 发行版运行：
|
||||
|
||||
```bash
|
||||
uvx --from 'hermes-agent[acp]==<version>' hermes-acp
|
||||
```
|
||||
|
||||
使用 registry 安装路径前，请确保 `uv` 已在 `PATH` 中可用。
|
||||
|
||||
## 启动 ACP 服务器
|
||||
|
||||
以下任意命令均可以 ACP 模式启动 Hermes：
|
||||
|
||||
```bash
|
||||
hermes acp
|
||||
```
|
||||
|
||||
```bash
|
||||
hermes-acp
|
||||
```
|
||||
|
||||
```bash
|
||||
python -m acp_adapter
|
||||
```
|
||||
|
||||
Hermes 将日志输出到 stderr，以保留 stdout 用于 ACP JSON-RPC 流量。
|
||||
|
||||
非交互式检查：
|
||||
|
||||
```bash
|
||||
hermes acp --version
|
||||
hermes acp --check
|
||||
```
|
||||
|
||||
### 浏览器工具（可选）
|
||||
|
||||
浏览器工具（`browser_navigate`、`browser_click` 等）依赖 `agent-browser` npm 包和 Chromium，这些不包含在 Python wheel 中。通过以下命令安装：
|
||||
|
||||
```bash
|
||||
hermes acp --setup-browser # 交互式（下载约 400 MB 前会提示确认）
|
||||
hermes acp --setup-browser --yes # 非交互式接受下载
|
||||
```
|
||||
|
||||
这是独立命令。Zed registry 的终端认证流程（`hermes acp --setup`）在模型选择后也会将浏览器引导作为后续问题提供，因此大多数用户无需直接运行 `--setup-browser`。
|
||||
|
||||
具体操作：
|
||||
|
||||
- 若缺少 Node.js 22 LTS，将其安装到 `~/.hermes/node/`
|
||||
- 将 `npm install -g agent-browser @askjo/camofox-browser` 安装到该前缀（无需 sudo — `npm` 的 `--prefix` 指向用户可写的 Hermes 管理 Node）
|
||||
- 安装 Playwright Chromium，或在检测到系统 Chrome/Chromium 时使用已有版本
|
||||
|
||||
该引导过程是幂等的——重复运行速度很快，已完成的步骤会被跳过。
|
||||
|
||||
## 编辑器设置
|
||||
|
||||
### VS Code
|
||||
|
||||
安装 [ACP Client](https://marketplace.visualstudio.com/items?itemName=formulahendry.acp-client) 扩展。
|
||||
|
||||
连接步骤：
|
||||
|
||||
1. 从活动栏打开 ACP Client 面板。
|
||||
2. 从内置 agent 列表中选择 **Hermes Agent**。
|
||||
3. 连接并开始聊天。
|
||||
|
||||
如需手动定义 Hermes，通过 VS Code 设置在 `acp.agents` 下添加：
|
||||
|
||||
```json
|
||||
{
|
||||
"acp.agents": {
|
||||
"Hermes Agent": {
|
||||
"command": "hermes",
|
||||
"args": ["acp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Zed
|
||||
|
||||
Zed v0.221.x 及更新版本通过官方 ACP Registry 安装外部 agent。
|
||||
|
||||
1. 打开 Agent 面板。
|
||||
2. 点击 **Add Agent**，或运行 `zed: acp registry` 命令。
|
||||
3. 搜索 **Hermes Agent**。
|
||||
4. 安装后启动新的 Hermes 外部 agent 线程。
|
||||
|
||||
前提条件：
|
||||
|
||||
- 先通过 `hermes model` 配置 Hermes provider 凭据，或在 `~/.hermes/.env` / `~/.hermes/config.yaml` 中设置。
|
||||
- 安装 `uv`，以便 registry 启动器可以运行 `uvx --from 'hermes-agent[acp]==<version>' hermes-acp`。
|
||||
|
||||
在 registry 条目可用之前进行本地开发时，在 Zed 设置中使用自定义 agent 服务器：
|
||||
|
||||
```json
|
||||
{
|
||||
"agent_servers": {
|
||||
"hermes-agent": {
|
||||
"type": "custom",
|
||||
"command": "hermes",
|
||||
"args": ["acp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### JetBrains
|
||||
|
||||
使用兼容 ACP 的插件并将其指向：
|
||||
|
||||
```text
|
||||
/path/to/hermes-agent/acp_registry
|
||||
```
|
||||
|
||||
## Registry 清单
|
||||
|
||||
Hermes 官方 ACP Registry 元数据的源文件位于：
|
||||
|
||||
```text
|
||||
acp_registry/agent.json
|
||||
acp_registry/icon.svg
|
||||
```
|
||||
|
||||
上游 registry PR 将这些文件复制到 `agentclientprotocol/registry` 中的顶层 `hermes-agent/` 目录。
|
||||
|
||||
Registry 条目使用直接指向 `hermes-agent` PyPI 发行版的 `uvx` 发行版：
|
||||
|
||||
```text
|
||||
uvx --from 'hermes-agent[acp]==<version>' hermes-acp
|
||||
```
|
||||
|
||||
Registry CI 会验证固定版本是否存在于 PyPI，因此清单的 `version` 和 uvx `package` 固定版本必须始终与 `pyproject.toml` 匹配。`scripts/release.py` 会自动保持它们同步。
|
||||
|
||||
## 配置与凭据
|
||||
|
||||
ACP 模式使用与 CLI 相同的 Hermes 配置：
|
||||
|
||||
- `~/.hermes/.env`
|
||||
- `~/.hermes/config.yaml`
|
||||
- `~/.hermes/skills/`
|
||||
- `~/.hermes/state.db`
|
||||
|
||||
Provider 解析使用 Hermes 的正常运行时解析器，因此 ACP 继承当前配置的 provider 和凭据。Hermes 还为首次运行的 registry 客户端提供终端认证方法（`--setup`）；这将打开 Hermes 的交互式模型/provider 设置。
|
||||
|
||||
## 会话行为
|
||||
|
||||
ACP 会话在服务器运行期间由 ACP 适配器的内存会话管理器跟踪。
|
||||
|
||||
每个会话存储：
|
||||
|
||||
- 会话 ID
|
||||
- 工作目录
|
||||
- 已选模型
|
||||
- 当前对话历史
|
||||
- 取消事件
|
||||
|
||||
底层 `AIAgent` 仍使用 Hermes 的正常持久化/日志路径，但 ACP 的 `list/load/resume/fork` 仅限于当前运行的 ACP 服务器进程。
|
||||
|
||||
## 工作目录行为
|
||||
|
||||
ACP 会话将编辑器的 cwd 绑定到 Hermes 任务 ID，使文件和终端工具相对于编辑器工作区运行，而非服务器进程的 cwd。
|
||||
|
||||
## 审批
|
||||
|
||||
危险的终端命令可作为审批 prompt 路由回编辑器。ACP 审批选项比 CLI 流程更简单：
|
||||
|
||||
- 允许一次
|
||||
- 始终允许
|
||||
- 拒绝
|
||||
|
||||
超时或出错时，审批桥接会拒绝请求。
|
||||
|
||||
### 会话范围的编辑自动审批
|
||||
|
||||
ACP 在*允许一次*和*始终允许*之间提供第三层：**允许本次会话**。在编辑器的权限提示中选择此选项，会将审批记录在当前 ACP 会话内——该会话中所有后续匹配命令无需提示即可通过，但新的 ACP 会话（或重启编辑器）会重置状态，并在第一次时重新提示。
|
||||
|
||||
| 选项 | 编辑器标签 | 范围 | 重启后是否持久化 |
|
||||
|---|---|---|---|
|
||||
| `allow_once` | 允许一次 | 本次工具调用 | 否 |
|
||||
| `allow_session` | 允许本次会话 | 本 ACP 会话中所有匹配调用 | 否——会话结束时清除 |
|
||||
| `allow_always` | 始终允许 | 所有未来会话 | 是（写入 Hermes 永久允许列表） |
|
||||
| `deny` | 拒绝 | 本次工具调用 | 否 |
|
||||
|
||||
`allow_session` 是编辑器工作流的正确默认选项——你在任务期间信任 agent，但不想授予长期允许列表条目。安全权衡很直接：范围越广，编辑器打断你的次数越少，行为异常的 agent（或 prompt 注入）在被发现前能造成的损害也越大。对不熟悉的命令从 `allow_once` 开始；在看到 agent 多次正确运行相同模式后升级为 `allow_session`；将 `allow_always` 保留给你永远信任的真正幂等命令（例如 `git status`）。
|
||||
|
||||
ACP 桥接将这些选项映射到 Hermes 的内部审批语义——`allow_always` 与 CLI 相同地写入永久允许列表条目，而 `allow_session` 仅影响当前 ACP 会话的进程内审批缓存。
|
||||
|
||||
## 故障排查
|
||||
|
||||
### ACP agent 未出现在编辑器中
|
||||
|
||||
检查：
|
||||
|
||||
- 在 Zed 中，使用 `zed: acp registry` 打开 ACP Registry 并搜索 **Hermes Agent**。
|
||||
- 对于手动/本地开发，验证自定义 `agent_servers` 命令是否指向 `hermes acp`。
|
||||
- Hermes 已安装且在 PATH 中。
|
||||
- ACP 扩展已安装（`pip install -e '.[acp]'`）。
|
||||
- 如果从官方 Zed registry 条目启动，`uv` 已安装。
|
||||
|
||||
### ACP 启动后立即报错
|
||||
|
||||
尝试以下检查：
|
||||
|
||||
```bash
|
||||
hermes acp --version
|
||||
hermes acp --check
|
||||
hermes doctor
|
||||
hermes status
|
||||
```
|
||||
|
||||
### 缺少凭据
|
||||
|
||||
ACP 模式使用 Hermes 现有的 provider 设置。通过以下方式配置凭据：
|
||||
|
||||
```bash
|
||||
hermes model
|
||||
```
|
||||
|
||||
或编辑 `~/.hermes/.env`。Registry 客户端也可以触发 Hermes 的终端认证流程，该流程运行相同的交互式 provider/模型设置。
|
||||
|
||||
### Zed registry 启动器找不到 uv
|
||||
|
||||
从官方 uv 安装文档安装 `uv`，然后从 Zed 重试 Hermes Agent 线程。
|
||||
|
||||
## 另请参阅
|
||||
|
||||
- [ACP 内部机制](../../developer-guide/acp-internals.md)
|
||||
- [Provider 运行时解析](../../developer-guide/provider-runtime.md)
|
||||
- [工具运行时](../../developer-guide/tools-runtime.md)
|
||||
+441
@@ -0,0 +1,441 @@
|
||||
---
|
||||
sidebar_position: 14
|
||||
title: "API 服务器"
|
||||
description: "将 hermes-agent 作为 OpenAI 兼容的 API 暴露给任意前端"
|
||||
---
|
||||
|
||||
# API 服务器
|
||||
|
||||
API 服务器将 hermes-agent 作为 OpenAI 兼容的 HTTP 端点暴露出来。任何支持 OpenAI 格式的前端——Open WebUI、LobeChat、LibreChat、NextChat、ChatBox 以及数百个其他工具——都可以连接到 hermes-agent 并将其用作后端。
|
||||
|
||||
你的 agent 使用完整工具集（终端、文件操作、网络搜索、记忆、技能）处理请求，并返回最终响应。在流式传输时，工具进度指示器会内联显示，让前端能够展示 agent 正在执行的操作。
|
||||
|
||||
:::tip 一个后端同时覆盖模型与工具
|
||||
Hermes 本身需要配置好 provider（提供商）和工具后端，API 服务器才能发挥作用。[Nous Portal](/user-guide/features/tool-gateway) 订阅同时处理两者——300+ 个模型，以及通过 Tool Gateway 提供的网络/图像/TTS/浏览器功能。在启动 API 服务器之前运行一次 `hermes setup --portal`，Open WebUI 或 LobeChat 等前端即可获得一个完整配备工具的后端。
|
||||
:::
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 启用 API 服务器
|
||||
|
||||
在 `~/.hermes/.env` 中添加：
|
||||
|
||||
```bash
|
||||
API_SERVER_ENABLED=true
|
||||
API_SERVER_KEY=change-me-local-dev
|
||||
# 可选：仅当浏览器需要直接调用 Hermes 时
|
||||
# API_SERVER_CORS_ORIGINS=http://localhost:3000
|
||||
```
|
||||
|
||||
### 2. 启动 gateway
|
||||
|
||||
```bash
|
||||
hermes gateway
|
||||
```
|
||||
|
||||
你将看到：
|
||||
|
||||
```
|
||||
[API Server] API server listening on http://127.0.0.1:8642
|
||||
```
|
||||
|
||||
### 3. 连接前端
|
||||
|
||||
将任何 OpenAI 兼容客户端指向 `http://localhost:8642/v1`：
|
||||
|
||||
```bash
|
||||
# 使用 curl 测试
|
||||
curl http://localhost:8642/v1/chat/completions \
|
||||
-H "Authorization: Bearer change-me-local-dev" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'
|
||||
```
|
||||
|
||||
或连接 Open WebUI、LobeChat 或其他任意前端——参见 [Open WebUI 集成指南](/user-guide/messaging/open-webui)获取分步说明。
|
||||
|
||||
## 端点
|
||||
|
||||
### POST /v1/chat/completions
|
||||
|
||||
标准 OpenAI Chat Completions 格式。无状态——完整对话通过每次请求的 `messages` 数组传入。
|
||||
|
||||
**请求：**
|
||||
```json
|
||||
{
|
||||
"model": "hermes-agent",
|
||||
"messages": [
|
||||
{"role": "system", "content": "You are a Python expert."},
|
||||
{"role": "user", "content": "Write a fibonacci function"}
|
||||
],
|
||||
"stream": false
|
||||
}
|
||||
```
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"id": "chatcmpl-abc123",
|
||||
"object": "chat.completion",
|
||||
"created": 1710000000,
|
||||
"model": "hermes-agent",
|
||||
"choices": [{
|
||||
"index": 0,
|
||||
"message": {"role": "assistant", "content": "Here's a fibonacci function..."},
|
||||
"finish_reason": "stop"
|
||||
}],
|
||||
"usage": {"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250}
|
||||
}
|
||||
```
|
||||
|
||||
**内联图像输入：** 用户消息可以将 `content` 作为 `text` 和 `image_url` 部分的数组发送。支持远程 `http(s)` URL 和 `data:image/...` URL：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "hermes-agent",
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "text", "text": "What is in this image?"},
|
||||
{"type": "image_url", "image_url": {"url": "https://example.com/cat.png", "detail": "high"}}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
上传的文件（`file` / `input_file` / `file_id`）和非图像 `data:` URL 将返回 `400 unsupported_content_type`。
|
||||
|
||||
**流式传输**（`"stream": true`）：返回逐 token 响应块的 Server-Sent Events（SSE）。对于 **Chat Completions**，流使用标准 `chat.completion.chunk` 事件，以及 Hermes 自定义的 `hermes.tool.progress` 事件用于工具启动的 UX 展示。对于 **Responses**，流使用 OpenAI Responses 事件类型，如 `response.created`、`response.output_text.delta`、`response.output_item.added`、`response.output_item.done` 和 `response.completed`。
|
||||
|
||||
**流中的工具进度：**
|
||||
- **Chat Completions**：Hermes 发出 `event: hermes.tool.progress` 以提供工具启动可见性，同时不污染持久化的 assistant 文本。
|
||||
- **Responses**：Hermes 在 SSE 流期间发出符合规范的 `function_call` 和 `function_call_output` 输出项，让客户端能够实时渲染结构化工具 UI。
|
||||
|
||||
### POST /v1/responses
|
||||
|
||||
OpenAI Responses API 格式。通过 `previous_response_id` 支持服务端对话状态——服务器存储完整的对话历史（包括工具调用和结果），因此多轮上下文无需客户端自行管理。
|
||||
|
||||
**请求：**
|
||||
```json
|
||||
{
|
||||
"model": "hermes-agent",
|
||||
"input": "What files are in my project?",
|
||||
"instructions": "You are a helpful coding assistant.",
|
||||
"store": true
|
||||
}
|
||||
```
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"id": "resp_abc123",
|
||||
"object": "response",
|
||||
"status": "completed",
|
||||
"model": "hermes-agent",
|
||||
"output": [
|
||||
{"type": "function_call", "name": "terminal", "arguments": "{\"command\": \"ls\"}", "call_id": "call_1"},
|
||||
{"type": "function_call_output", "call_id": "call_1", "output": "README.md src/ tests/"},
|
||||
{"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Your project has..."}]}
|
||||
],
|
||||
"usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
|
||||
}
|
||||
```
|
||||
|
||||
**内联图像输入：** `input[].content` 可以包含 `input_text` 和 `input_image` 部分。支持远程 URL 和 `data:image/...` URL：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "hermes-agent",
|
||||
"input": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "input_text", "text": "Describe this screenshot."},
|
||||
{"type": "input_image", "image_url": "data:image/png;base64,iVBORw0K..."}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
上传的文件（`input_file` / `file_id`）和非图像 `data:` URL 将返回 `400 unsupported_content_type`。
|
||||
|
||||
#### 使用 previous_response_id 进行多轮对话
|
||||
|
||||
链式响应以在多轮之间保持完整上下文（包括工具调用）：
|
||||
|
||||
```json
|
||||
{
|
||||
"input": "Now show me the README",
|
||||
"previous_response_id": "resp_abc123"
|
||||
}
|
||||
```
|
||||
|
||||
服务器从存储的响应链重建完整对话——所有之前的工具调用和结果均被保留。链式请求还共享同一个 session，因此多轮对话在仪表板和 session 历史中显示为单个条目。
|
||||
|
||||
#### 命名对话
|
||||
|
||||
使用 `conversation` 参数代替追踪响应 ID：
|
||||
|
||||
```json
|
||||
{"input": "Hello", "conversation": "my-project"}
|
||||
{"input": "What's in src/?", "conversation": "my-project"}
|
||||
{"input": "Run the tests", "conversation": "my-project"}
|
||||
```
|
||||
|
||||
服务器自动链接到该对话中的最新响应。类似于 gateway session 的 `/title` 命令。
|
||||
|
||||
### GET /v1/responses/\{id\}
|
||||
|
||||
通过 ID 检索之前存储的响应。
|
||||
|
||||
### DELETE /v1/responses/\{id\}
|
||||
|
||||
删除存储的响应。
|
||||
|
||||
### GET /v1/models
|
||||
|
||||
将 agent 列为可用模型。广播的模型名称默认为 [profile](/user-guide/profiles) 名称（默认 profile 则为 `hermes-agent`）。大多数前端进行模型发现时需要此端点。
|
||||
|
||||
### GET /v1/capabilities
|
||||
|
||||
返回 API 服务器稳定接口的机器可读描述，供外部 UI、编排器和插件桥接使用。
|
||||
|
||||
```json
|
||||
{
|
||||
"object": "hermes.api_server.capabilities",
|
||||
"platform": "hermes-agent",
|
||||
"model": "hermes-agent",
|
||||
"auth": {"type": "bearer", "required": true},
|
||||
"features": {
|
||||
"chat_completions": true,
|
||||
"responses_api": true,
|
||||
"run_submission": true,
|
||||
"run_status": true,
|
||||
"run_events_sse": true,
|
||||
"run_stop": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
在集成仪表板、浏览器 UI 或控制平面时使用此端点，以便它们能够发现当前运行的 Hermes 版本是否支持 runs、流式传输、取消和 session 连续性，而无需依赖私有 Python 内部实现。
|
||||
|
||||
### GET /health
|
||||
|
||||
健康检查。返回 `{"status": "ok"}`。也可通过 **GET /v1/health** 访问，供期望 `/v1/` 前缀的 OpenAI 兼容客户端使用。
|
||||
|
||||
### GET /health/detailed
|
||||
|
||||
扩展健康检查，同时报告活跃 session、运行中的 agent 和资源使用情况。适用于监控/可观测性工具。
|
||||
|
||||
## Runs API（流式友好的替代方案）
|
||||
|
||||
除 `/v1/chat/completions` 和 `/v1/responses` 外，服务器还暴露了一个 **runs** API，适用于客户端希望订阅进度事件而非自行管理流式传输的长时 session。
|
||||
|
||||
### POST /v1/runs
|
||||
|
||||
创建新的 agent run。返回可用于订阅进度事件的 `run_id`。
|
||||
|
||||
```json
|
||||
{
|
||||
"run_id": "run_abc123",
|
||||
"status": "started"
|
||||
}
|
||||
```
|
||||
|
||||
Runs 接受简单的 `input` 字符串，以及可选的 `session_id`、`instructions`、`conversation_history` 或 `previous_response_id`。当提供 `session_id` 时，Hermes 会在 run 状态中暴露它，以便外部 UI 将 run 与自己的对话 ID 关联。
|
||||
|
||||
### GET /v1/runs/\{run_id\}
|
||||
|
||||
轮询当前 run 状态。适用于需要状态但不想保持 SSE 连接的仪表板，或在导航后重新连接的 UI。
|
||||
|
||||
```json
|
||||
{
|
||||
"object": "hermes.run",
|
||||
"run_id": "run_abc123",
|
||||
"status": "completed",
|
||||
"session_id": "space-session",
|
||||
"model": "hermes-agent",
|
||||
"output": "Done.",
|
||||
"usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
|
||||
}
|
||||
```
|
||||
|
||||
状态在终态（`completed`、`failed` 或 `cancelled`）之后会短暂保留，以供轮询和 UI 对账使用。
|
||||
|
||||
### GET /v1/runs/\{run_id\}/events
|
||||
|
||||
run 的工具调用进度、token 增量和生命周期事件的 Server-Sent Events 流。专为需要附加/分离而不丢失状态的仪表板和厚客户端设计。
|
||||
|
||||
### POST /v1/runs/\{run_id\}/stop
|
||||
|
||||
中断正在运行的 agent 轮次。端点立即返回 `{"status": "stopping"}`，同时 Hermes 要求活跃 agent 在下一个安全中断点停止。
|
||||
|
||||
## Jobs API（后台计划任务）
|
||||
|
||||
服务器暴露了一个轻量级 jobs CRUD 接口，用于从远程客户端管理计划/后台 agent run。所有端点均受同一 bearer 认证保护。
|
||||
|
||||
### GET /api/jobs
|
||||
|
||||
列出所有计划任务。
|
||||
|
||||
### POST /api/jobs
|
||||
|
||||
创建新的计划任务。请求体接受与 `hermes cron` 相同的结构——prompt（提示词）、schedule（计划）、skills（技能）、provider 覆盖、投递目标。
|
||||
|
||||
### GET /api/jobs/\{job_id\}
|
||||
|
||||
获取单个任务的定义和最后一次运行状态。
|
||||
|
||||
### PATCH /api/jobs/\{job_id\}
|
||||
|
||||
更新现有任务的字段（prompt、schedule 等）。部分更新会被合并。
|
||||
|
||||
### DELETE /api/jobs/\{job_id\}
|
||||
|
||||
删除任务。同时取消任何正在进行的 run。
|
||||
|
||||
### POST /api/jobs/\{job_id\}/pause
|
||||
|
||||
暂停任务而不删除它。下次计划运行的时间戳将被挂起，直到恢复。
|
||||
|
||||
### POST /api/jobs/\{job_id\}/resume
|
||||
|
||||
恢复之前暂停的任务。
|
||||
|
||||
### POST /api/jobs/\{job_id\}/run
|
||||
|
||||
立即触发任务运行，不受计划限制。
|
||||
|
||||
## 系统 Prompt 处理
|
||||
|
||||
当前端发送 `system` 消息（Chat Completions）或 `instructions` 字段（Responses API）时，hermes-agent 会将其**叠加在**核心系统 prompt 之上。你的 agent 保留所有工具、记忆和技能——前端的系统 prompt 只是添加额外指令。
|
||||
|
||||
这意味着你可以按前端自定义行为，而不会失去能力：
|
||||
- Open WebUI 系统 prompt："You are a Python expert. Always include type hints."
|
||||
- agent 仍然拥有终端、文件工具、网络搜索、记忆等。
|
||||
|
||||
## 认证
|
||||
|
||||
通过 `Authorization` 请求头进行 Bearer token 认证：
|
||||
|
||||
```
|
||||
Authorization: Bearer ***
|
||||
```
|
||||
|
||||
通过 `API_SERVER_KEY` 环境变量配置密钥。如果需要浏览器直接调用 Hermes，还需将 `API_SERVER_CORS_ORIGINS` 设置为明确的允许列表。
|
||||
|
||||
:::warning 安全
|
||||
API 服务器提供对 hermes-agent 工具集的完整访问权限，**包括终端命令**。当绑定到非回环地址（如 `0.0.0.0`）时，**必须**设置 `API_SERVER_KEY`。同时保持 `API_SERVER_CORS_ORIGINS` 范围尽量小，以控制浏览器访问。
|
||||
|
||||
默认绑定地址（`127.0.0.1`）仅供本地使用。浏览器访问默认禁用；仅为明确的可信来源启用。
|
||||
:::
|
||||
|
||||
## 配置
|
||||
|
||||
### 环境变量
|
||||
|
||||
| 变量 | 默认值 | 描述 |
|
||||
|----------|---------|-------------|
|
||||
| `API_SERVER_ENABLED` | `false` | 启用 API 服务器 |
|
||||
| `API_SERVER_PORT` | `8642` | HTTP 服务器端口 |
|
||||
| `API_SERVER_HOST` | `127.0.0.1` | 绑定地址（默认仅限本地） |
|
||||
| `API_SERVER_KEY` | _（无）_ | 认证用 Bearer token |
|
||||
| `API_SERVER_CORS_ORIGINS` | _（无）_ | 逗号分隔的允许浏览器来源 |
|
||||
| `API_SERVER_MODEL_NAME` | _（profile 名称）_ | `/v1/models` 上的模型名称。默认为 profile 名称，默认 profile 则为 `hermes-agent`。 |
|
||||
|
||||
### config.yaml
|
||||
|
||||
```yaml
|
||||
# 暂不支持——请使用环境变量。
|
||||
# config.yaml 支持将在未来版本中推出。
|
||||
```
|
||||
|
||||
## 安全响应头
|
||||
|
||||
所有响应均包含安全响应头：
|
||||
- `X-Content-Type-Options: nosniff` — 防止 MIME 类型嗅探
|
||||
- `Referrer-Policy: no-referrer` — 防止 referrer 泄露
|
||||
|
||||
## CORS
|
||||
|
||||
API 服务器默认**不**启用浏览器 CORS。
|
||||
|
||||
如需直接浏览器访问，请设置明确的允许列表：
|
||||
|
||||
```bash
|
||||
API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
|
||||
```
|
||||
|
||||
启用 CORS 后：
|
||||
- **预检响应**包含 `Access-Control-Max-Age: 600`（10 分钟缓存）
|
||||
- **SSE 流式响应**包含 CORS 头，使浏览器 EventSource 客户端能够正常工作
|
||||
- **`Idempotency-Key`** 是允许的请求头——客户端可发送它用于去重（响应按 key 缓存 5 分钟）
|
||||
|
||||
大多数已记录的前端（如 Open WebUI）采用服务器到服务器连接，完全不需要 CORS。
|
||||
|
||||
## 兼容前端
|
||||
|
||||
任何支持 OpenAI API 格式的前端均可使用。已测试/记录的集成：
|
||||
|
||||
| 前端 | Stars | 连接方式 |
|
||||
|----------|-------|------------|
|
||||
| [Open WebUI](/user-guide/messaging/open-webui) | 126k | 提供完整指南 |
|
||||
| LobeChat | 73k | 自定义 provider 端点 |
|
||||
| LibreChat | 34k | librechat.yaml 中的自定义端点 |
|
||||
| AnythingLLM | 56k | 通用 OpenAI provider |
|
||||
| NextChat | 87k | BASE_URL 环境变量 |
|
||||
| ChatBox | 39k | API Host 设置 |
|
||||
| Jan | 26k | 远程模型配置 |
|
||||
| HF Chat-UI | 8k | OPENAI_BASE_URL |
|
||||
| big-AGI | 7k | 自定义端点 |
|
||||
| OpenAI Python SDK | — | `OpenAI(base_url="http://localhost:8642/v1")` |
|
||||
| curl | — | 直接 HTTP 请求 |
|
||||
|
||||
## 使用 Profiles 的多用户设置
|
||||
|
||||
要为多个用户提供各自隔离的 Hermes 实例（独立的配置、记忆、技能），请使用 [profiles](/user-guide/profiles)：
|
||||
|
||||
```bash
|
||||
# 为每个用户创建 profile
|
||||
hermes profile create alice
|
||||
hermes profile create bob
|
||||
|
||||
# 在不同端口上配置每个 profile 的 API 服务器。API_SERVER_* 是环境变量
|
||||
# （不是 config.yaml 键），因此将它们写入每个 profile 的 .env：
|
||||
cat >> ~/.hermes/profiles/alice/.env <<EOF
|
||||
API_SERVER_ENABLED=true
|
||||
API_SERVER_PORT=8643
|
||||
API_SERVER_KEY=alice-secret
|
||||
EOF
|
||||
|
||||
cat >> ~/.hermes/profiles/bob/.env <<EOF
|
||||
API_SERVER_ENABLED=true
|
||||
API_SERVER_PORT=8644
|
||||
API_SERVER_KEY=bob-secret
|
||||
EOF
|
||||
|
||||
# 启动每个 profile 的 gateway
|
||||
hermes -p alice gateway &
|
||||
hermes -p bob gateway &
|
||||
```
|
||||
|
||||
每个 profile 的 API 服务器自动将 profile 名称作为模型 ID 广播：
|
||||
|
||||
- `http://localhost:8643/v1/models` → 模型 `alice`
|
||||
- `http://localhost:8644/v1/models` → 模型 `bob`
|
||||
|
||||
在 Open WebUI 中，将每个添加为单独的连接。模型下拉列表显示 `alice` 和 `bob` 作为不同模型，每个均由完全隔离的 Hermes 实例支持。详见 [Open WebUI 指南](/user-guide/messaging/open-webui#multi-user-setup-with-profiles)。
|
||||
|
||||
## 限制
|
||||
|
||||
- **响应存储** — 存储的响应（用于 `previous_response_id`）持久化在 SQLite 中，gateway 重启后仍然存在。最多存储 100 个响应（LRU 淘汰）。
|
||||
- **不支持文件上传** — 两个端点（`/v1/chat/completions` 和 `/v1/responses`）均支持内联图像，但不支持通过 API 上传文件（`file`、`input_file`、`file_id`）和非图像文档输入。
|
||||
- **model 字段仅为展示用途** — 请求中的 `model` 字段会被接受，但实际使用的 LLM 模型在服务端的 config.yaml 中配置。
|
||||
|
||||
## 代理模式
|
||||
|
||||
API 服务器还作为 **gateway 代理模式**的后端。当另一个 Hermes gateway 实例配置了指向此 API 服务器的 `GATEWAY_PROXY_URL` 时，它会将所有消息转发到这里，而不是运行自己的 agent。这支持分离部署——例如，一个处理 Matrix E2EE 的 Docker 容器将请求中继到宿主机侧的 agent。
|
||||
|
||||
完整设置指南参见 [Matrix 代理模式](/user-guide/messaging/matrix#proxy-mode-e2ee-on-macos)。
|
||||
+230
@@ -0,0 +1,230 @@
|
||||
---
|
||||
sidebar_position: 12
|
||||
title: "批量处理"
|
||||
description: "大规模生成 agent 轨迹——并行处理、断点续跑与工具集分布"
|
||||
---
|
||||
|
||||
# 批量处理
|
||||
|
||||
批量处理让你能够并行地在数百乃至数千个 prompt（提示词）上运行 Hermes agent，生成结构化的轨迹数据。其主要用途是**训练数据生成**——产出包含工具使用统计信息的 ShareGPT 格式轨迹，可用于微调或评估。
|
||||
|
||||
## 概述
|
||||
|
||||
批量运行器（`batch_runner.py`）处理一个由 prompt 组成的 JSONL 数据集，将每条 prompt 通过完整的 agent 会话（含工具访问权限）运行一遍。每条 prompt 都拥有独立隔离的环境。输出为结构化轨迹数据，包含完整对话历史、工具调用统计信息以及推理覆盖率指标。
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
# 基本批量运行
|
||||
python batch_runner.py \
|
||||
--dataset_file=data/prompts.jsonl \
|
||||
--batch_size=10 \
|
||||
--run_name=my_first_run \
|
||||
--model=anthropic/claude-sonnet-4.6 \
|
||||
--num_workers=4
|
||||
|
||||
# 恢复中断的运行
|
||||
python batch_runner.py \
|
||||
--dataset_file=data/prompts.jsonl \
|
||||
--batch_size=10 \
|
||||
--run_name=my_first_run \
|
||||
--resume
|
||||
|
||||
# 列出可用的工具集分布
|
||||
python batch_runner.py --list_distributions
|
||||
```
|
||||
|
||||
:::tip 大规模运行下的可预测成本
|
||||
批量运行会启动大量并发 agent 会话，每个会话都会调用模型和工具。[Nous Portal](/user-guide/features/tool-gateway) 订阅将模型访问、网页搜索、图像生成、TTS 以及云端浏览器统一计费——当你希望在不同供应商账户间稳定控制每条轨迹成本、避免触碰速率限制时非常实用。使用 `hermes setup --portal` 完成配置，然后将 `--model` 指向 Nous 模型。
|
||||
:::
|
||||
|
||||
## 数据集格式
|
||||
|
||||
输入数据集为 JSONL 文件（每行一个 JSON 对象）。每条记录必须包含 `prompt` 字段：
|
||||
|
||||
```jsonl
|
||||
{"prompt": "Write a Python function that finds the longest palindromic substring"}
|
||||
{"prompt": "Create a REST API endpoint for user authentication using Flask"}
|
||||
{"prompt": "Debug this error: TypeError: cannot unpack non-iterable NoneType object"}
|
||||
```
|
||||
|
||||
记录还可以选填以下字段：
|
||||
- `image` 或 `docker_image`：用于该 prompt 沙箱的容器镜像（适用于 Docker、Modal 和 Singularity 后端）
|
||||
- `cwd`：任务终端会话的工作目录覆盖值
|
||||
|
||||
## 配置选项
|
||||
|
||||
| 参数 | 默认值 | 说明 |
|
||||
|-----------|---------|-------------|
|
||||
| `--dataset_file` | （必填） | JSONL 数据集路径 |
|
||||
| `--batch_size` | （必填） | 每批处理的 prompt 数量 |
|
||||
| `--run_name` | （必填） | 本次运行的名称（用于输出目录和断点续跑） |
|
||||
| `--distribution` | `"default"` | 采样所用的工具集分布 |
|
||||
| `--model` | `claude-sonnet-4.6` | 使用的模型 |
|
||||
| `--base_url` | `https://openrouter.ai/api/v1` | API 基础 URL |
|
||||
| `--api_key` | （环境变量） | 模型的 API 密钥 |
|
||||
| `--max_turns` | `10` | 每条 prompt 的最大工具调用轮次 |
|
||||
| `--num_workers` | `4` | 并行工作进程数 |
|
||||
| `--resume` | `false` | 从断点恢复 |
|
||||
| `--verbose` | `false` | 启用详细日志 |
|
||||
| `--max_samples` | 全部 | 仅处理数据集中前 N 条样本 |
|
||||
| `--max_tokens` | 模型默认值 | 每次模型响应的最大 token 数 |
|
||||
|
||||
### 供应商路由（OpenRouter）
|
||||
|
||||
| 参数 | 说明 |
|
||||
|-----------|-------------|
|
||||
| `--providers_allowed` | 允许的供应商，逗号分隔（例如 `"anthropic,openai"`） |
|
||||
| `--providers_ignored` | 忽略的供应商，逗号分隔（例如 `"together,deepinfra"`） |
|
||||
| `--providers_order` | 首选供应商顺序，逗号分隔 |
|
||||
| `--provider_sort` | 按 `"price"`、`"throughput"` 或 `"latency"` 排序 |
|
||||
|
||||
### 推理控制
|
||||
|
||||
| 参数 | 说明 |
|
||||
|-----------|-------------|
|
||||
| `--reasoning_effort` | 推理力度：`none`、`minimal`、`low`、`medium`、`high`、`xhigh` |
|
||||
| `--reasoning_disabled` | 完全禁用推理/思考 token |
|
||||
|
||||
### 高级选项
|
||||
|
||||
| 参数 | 说明 |
|
||||
|-----------|-------------|
|
||||
| `--ephemeral_system_prompt` | 执行时使用但**不**保存到轨迹中的系统 prompt |
|
||||
| `--log_prefix_chars` | 日志预览中显示的字符数（默认：100） |
|
||||
| `--prefill_messages_file` | 包含 few-shot 预填充消息的 JSON 文件路径 |
|
||||
|
||||
## 工具集分布
|
||||
|
||||
每条 prompt 会从一个**分布**中随机采样一组工具集。这确保训练数据覆盖多样化的工具组合。使用 `--list_distributions` 查看所有可用分布。
|
||||
|
||||
在当前实现中，分布为**每个独立工具集**分配一个概率。采样器对每个工具集独立进行伯努利抽样，并保证至少有一个工具集被启用。这与手工编写的预设组合表不同。
|
||||
|
||||
## 输出格式
|
||||
|
||||
所有输出写入 `data/<run_name>/`：
|
||||
|
||||
```text
|
||||
data/my_run/
|
||||
├── trajectories.jsonl # 合并后的最终输出（所有批次合并）
|
||||
├── batch_0.jsonl # 各批次结果
|
||||
├── batch_1.jsonl
|
||||
├── ...
|
||||
├── checkpoint.json # 断点续跑检查点
|
||||
└── statistics.json # 汇总工具使用统计
|
||||
```
|
||||
|
||||
### 轨迹格式
|
||||
|
||||
`trajectories.jsonl` 中每行是一个 JSON 对象：
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt_index": 42,
|
||||
"conversations": [
|
||||
{"from": "human", "value": "Write a function..."},
|
||||
{"from": "gpt", "value": "I'll create that function...",
|
||||
"tool_calls": [...]},
|
||||
{"from": "tool", "value": "..."},
|
||||
{"from": "gpt", "value": "Here's the completed function..."}
|
||||
],
|
||||
"metadata": {
|
||||
"batch_num": 2,
|
||||
"timestamp": "2026-01-15T10:30:00",
|
||||
"model": "anthropic/claude-sonnet-4.6"
|
||||
},
|
||||
"completed": true,
|
||||
"partial": false,
|
||||
"api_calls": 3,
|
||||
"toolsets_used": ["terminal", "file"],
|
||||
"tool_stats": {
|
||||
"terminal": {"count": 2, "success": 2, "failure": 0},
|
||||
"read_file": {"count": 1, "success": 1, "failure": 0}
|
||||
},
|
||||
"tool_error_counts": {
|
||||
"terminal": 0,
|
||||
"read_file": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`conversations` 字段使用类 ShareGPT 格式，包含 `from` 和 `value` 字段。工具统计信息经过规范化处理，所有可能的工具均以零值默认填充，确保各条记录的 schema 一致，兼容 HuggingFace 数据集格式。
|
||||
|
||||
## 断点续跑
|
||||
|
||||
批量运行器具备健壮的断点续跑机制以应对故障：
|
||||
|
||||
- **检查点文件：** 每批完成后保存，记录已完成的 prompt 索引
|
||||
- **基于内容的恢复：** 使用 `--resume` 时，运行器扫描现有批次文件，通过实际文本内容（而非索引）匹配已完成的 prompt，即使数据集顺序发生变化也能正常恢复
|
||||
- **失败的 prompt：** 只有成功完成的 prompt 才会被标记为已完成——失败的 prompt 在恢复时会重新尝试
|
||||
- **批次合并：** 完成后，所有批次文件（包括之前运行的）会合并为单个 `trajectories.jsonl`
|
||||
|
||||
### 恢复流程
|
||||
|
||||
1. 扫描所有 `batch_*.jsonl` 文件，通过内容匹配找出已完成的 prompt
|
||||
2. 过滤数据集，排除已完成的 prompt
|
||||
3. 对剩余 prompt 重新分批
|
||||
4. 仅处理剩余 prompt
|
||||
5. 将所有批次文件（旧的 + 新的）合并为最终输出
|
||||
|
||||
## 质量过滤
|
||||
|
||||
批量运行器会自动进行质量过滤：
|
||||
|
||||
- **无推理过滤：** 所有 assistant 轮次均不包含推理内容（无 `<REASONING_SCRATCHPAD>` 或原生思考 token）的样本将被丢弃
|
||||
- **损坏条目过滤：** 包含幻觉工具名称（不在有效工具列表中）的条目在最终合并时会被过滤掉
|
||||
- **推理统计：** 跟踪整个运行过程中包含/不包含推理内容的轮次百分比
|
||||
|
||||
## 统计信息
|
||||
|
||||
完成后，运行器会打印全面的统计信息：
|
||||
|
||||
- **工具使用情况：** 每个工具的调用次数、成功/失败率
|
||||
- **推理覆盖率：** 包含推理内容的 assistant 轮次百分比
|
||||
- **丢弃样本数：** 因缺少推理内容而被过滤的样本数量
|
||||
- **耗时：** 总处理时间
|
||||
|
||||
统计信息同时保存至 `statistics.json`，便于程序化分析。
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 训练数据生成
|
||||
|
||||
生成多样化的工具使用轨迹用于微调：
|
||||
|
||||
```bash
|
||||
python batch_runner.py \
|
||||
--dataset_file=data/coding_prompts.jsonl \
|
||||
--batch_size=20 \
|
||||
--run_name=coding_v1 \
|
||||
--model=anthropic/claude-sonnet-4.6 \
|
||||
--num_workers=8 \
|
||||
--distribution=default \
|
||||
--max_turns=15
|
||||
```
|
||||
|
||||
### 模型评估
|
||||
|
||||
在标准化 prompt 集上评估模型的工具使用能力：
|
||||
|
||||
```bash
|
||||
python batch_runner.py \
|
||||
--dataset_file=data/eval_suite.jsonl \
|
||||
--batch_size=10 \
|
||||
--run_name=eval_gpt4 \
|
||||
--model=openai/gpt-4o \
|
||||
--num_workers=4 \
|
||||
--max_turns=10
|
||||
```
|
||||
|
||||
### 按 Prompt 指定容器镜像
|
||||
|
||||
对于需要特定环境的基准测试，每条 prompt 可以指定自己的容器镜像：
|
||||
|
||||
```jsonl
|
||||
{"prompt": "Install numpy and compute eigenvalues of a 3x3 matrix", "image": "python:3.11-slim"}
|
||||
{"prompt": "Compile this Rust program and run it", "image": "rust:1.75"}
|
||||
{"prompt": "Set up a Node.js Express server", "image": "node:20-alpine", "cwd": "/app"}
|
||||
```
|
||||
|
||||
批量运行器会在运行每条 prompt 前验证 Docker 镜像是否可访问。
|
||||
+627
@@ -0,0 +1,627 @@
|
||||
---
|
||||
title: 浏览器自动化
|
||||
description: 通过多种提供商控制浏览器，支持通过 CDP 连接本地 Chromium 系浏览器或云端浏览器，用于网页交互、表单填写、数据抓取等场景。
|
||||
sidebar_label: Browser
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# 浏览器自动化
|
||||
|
||||
Hermes Agent 内置完整的浏览器自动化工具集，支持多种后端选项：
|
||||
|
||||
- **Browserbase 云端模式** — 通过 [Browserbase](https://browserbase.com) 使用托管云端浏览器及反机器人工具
|
||||
- **Browser Use 云端模式** — 通过 [Browser Use](https://browser-use.com) 作为备选云端浏览器提供商
|
||||
- **Firecrawl 云端模式** — 通过 [Firecrawl](https://firecrawl.dev) 使用内置抓取功能的云端浏览器
|
||||
- **Camofox 本地模式** — 通过 [Camofox](https://github.com/jo-inc/camofox-browser) 实现本地反检测浏览（基于 Firefox 的指纹伪装）
|
||||
- **本地 Chromium 系 CDP** — 使用 `/browser connect` 将浏览器工具连接到本地运行的 Chrome、Brave、Chromium 或 Edge 实例
|
||||
- **本地浏览器模式** — 通过 `agent-browser` CLI 和本地 Chromium 安装运行
|
||||
|
||||
所有模式下，Agent 均可导航网站、与页面元素交互、填写表单并提取信息。
|
||||
|
||||
## 概述
|
||||
|
||||
页面以**无障碍树**（accessibility tree，基于文本的快照）表示，非常适合 LLM Agent 使用。交互元素会获得引用 ID（如 `@e1`、`@e2`），Agent 通过这些 ID 执行点击和输入操作。
|
||||
|
||||
核心能力：
|
||||
|
||||
- **多提供商云端执行** — Browserbase、Browser Use 或 Firecrawl — 无需本地浏览器
|
||||
- **本地 Chromium 系集成** — 通过 CDP 连接正在运行的 Chrome、Brave、Chromium 或 Edge 浏览器，实现实时操控
|
||||
- **内置隐身功能** — 随机指纹、CAPTCHA 解决、住宅代理（Browserbase）
|
||||
- **会话隔离** — 每个任务拥有独立的浏览器会话
|
||||
- **自动清理** — 非活跃会话在超时后自动关闭
|
||||
- **视觉分析** — 截图 + AI 分析，实现视觉理解
|
||||
|
||||
## 配置
|
||||
|
||||
:::tip Nous 订阅用户
|
||||
如果您拥有付费 [Nous Portal](https://portal.nousresearch.com) 订阅，可通过 **[Tool Gateway](tool-gateway.md)** 使用浏览器自动化功能，无需单独的 API 密钥。新安装可运行 `hermes setup --portal` 登录并一次性开启所有 gateway 工具；已有安装可通过 `hermes model` 或 `hermes tools` 选择 **Nous Subscription** 作为浏览器提供商。
|
||||
:::
|
||||
|
||||
### Browserbase 云端模式
|
||||
|
||||
要使用 Browserbase 托管的云端浏览器，请添加：
|
||||
|
||||
```bash
|
||||
# Add to ~/.hermes/.env
|
||||
BROWSERBASE_API_KEY=***
|
||||
BROWSERBASE_PROJECT_ID=your-project-id-here
|
||||
```
|
||||
|
||||
在 [browserbase.com](https://browserbase.com) 获取您的凭据。
|
||||
|
||||
### Browser Use 云端模式
|
||||
|
||||
要使用 Browser Use 作为云端浏览器提供商，请添加：
|
||||
|
||||
```bash
|
||||
# Add to ~/.hermes/.env
|
||||
BROWSER_USE_API_KEY=***
|
||||
```
|
||||
|
||||
在 [browser-use.com](https://browser-use.com) 获取 API 密钥。Browser Use 通过 REST API 提供云端浏览器。若同时设置了 Browserbase 和 Browser Use 凭据，Browserbase 优先。
|
||||
|
||||
### Firecrawl 云端模式
|
||||
|
||||
要使用 Firecrawl 作为云端浏览器提供商，请添加：
|
||||
|
||||
```bash
|
||||
# Add to ~/.hermes/.env
|
||||
FIRECRAWL_API_KEY=fc-***
|
||||
```
|
||||
|
||||
在 [firecrawl.dev](https://firecrawl.dev) 获取 API 密钥，然后选择 Firecrawl 作为浏览器提供商：
|
||||
|
||||
```bash
|
||||
hermes setup tools
|
||||
# → Browser Automation → Firecrawl
|
||||
```
|
||||
|
||||
可选配置：
|
||||
|
||||
```bash
|
||||
# Self-hosted Firecrawl instance (default: https://api.firecrawl.dev)
|
||||
FIRECRAWL_API_URL=http://localhost:3002
|
||||
|
||||
# Session TTL in seconds (default: 300)
|
||||
FIRECRAWL_BROWSER_TTL=600
|
||||
```
|
||||
|
||||
### 混合路由：公网 URL 使用云端，LAN/localhost 使用本地
|
||||
|
||||
配置云端提供商后，Hermes 会为解析到私有/回环/LAN 地址的 URL（`localhost`、`127.0.0.1`、`192.168.x.x`、`10.x.x.x`、`172.16-31.x.x`、`*.local`、`*.lan`、`*.internal`、IPv6 回环 `::1`、链路本地 `169.254.x.x`）自动启动一个**本地 Chromium 辅助进程**。公网 URL 在同一对话中继续使用云端提供商。
|
||||
|
||||
这解决了常见的"本地开发但使用 Browserbase"场景 — Agent 可以截取 `http://localhost:3000` 上的仪表盘，同时抓取 `https://github.com`，无需切换提供商或禁用 SSRF 防护。云端提供商永远不会看到私有 URL。
|
||||
|
||||
该功能**默认开启**。如需禁用（所有 URL 均走已配置的云端提供商，与之前行为一致）：
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
browser:
|
||||
cloud_provider: browserbase
|
||||
auto_local_for_private_urls: false
|
||||
```
|
||||
|
||||
禁用自动路由后，私有 URL 将被拒绝并返回 `"Blocked: URL targets a private or internal address"`，除非同时设置 `browser.allow_private_urls: true`（允许云端提供商尝试访问，但通常无法成功，因为 Browserbase 等无法访问您的 LAN）。
|
||||
|
||||
要求：本地辅助进程使用与纯本地模式相同的 `agent-browser` CLI，因此需要先安装（`hermes setup tools → Browser Automation` 会自动安装）。从公网 URL 导航后重定向到私有地址的情况仍会被阻止（无法通过公网路径的重定向访问 LAN）。
|
||||
|
||||
### Camofox 本地模式
|
||||
|
||||
[Camofox](https://github.com/jo-inc/camofox-browser) 是一个自托管的 Node.js 服务器，封装了 Camoufox（一个带有 C++ 指纹伪装的 Firefox 分支）。它无需云端依赖即可提供本地反检测浏览。
|
||||
|
||||
```bash
|
||||
# Clone the Camofox browser server first
|
||||
git clone https://github.com/jo-inc/camofox-browser
|
||||
cd camofox-browser
|
||||
|
||||
# Build and start with Docker using the default container settings
|
||||
# (auto-detects arch: aarch64 on M1/M2, x86_64 on Intel)
|
||||
make up
|
||||
|
||||
# Stop and remove the default container
|
||||
make down
|
||||
|
||||
# Force a clean rebuild (for example, after upgrading VERSION/RELEASE)
|
||||
make reset
|
||||
|
||||
# Just download binaries without building
|
||||
make fetch
|
||||
|
||||
# Override arch or version explicitly
|
||||
make up ARCH=x86_64
|
||||
make up VERSION=135.0.1 RELEASE=beta.24
|
||||
```
|
||||
|
||||
`make up` 会立即启动默认容器。如需自定义运行时设置（如更大的 Node 堆内存、VNC 或持久化 profile 目录），请先构建镜像再手动运行：
|
||||
|
||||
```bash
|
||||
# Build the image without starting the default container
|
||||
make build
|
||||
|
||||
# Start with persistence, VNC live view, and a larger Node heap
|
||||
mkdir -p ~/.camofox-docker
|
||||
docker run -d \
|
||||
--name camofox-browser \
|
||||
--restart unless-stopped \
|
||||
-p 9377:9377 \
|
||||
-p 6080:6080 \
|
||||
-p 5901:5900 \
|
||||
-e CAMOFOX_PORT=9377 \
|
||||
-e ENABLE_VNC=1 \
|
||||
-e VNC_BIND=0.0.0.0 \
|
||||
-e VNC_RESOLUTION=1920x1080 \
|
||||
-e MAX_OLD_SPACE_SIZE=2048 \
|
||||
-v ~/.camofox-docker:/root/.camofox \
|
||||
camofox-browser:135.0.1-aarch64
|
||||
```
|
||||
|
||||
启用 VNC 后，浏览器以有头模式运行，可在浏览器中通过 `http://localhost:6080`（noVNC）实时查看。也可使用原生 VNC 客户端连接 `localhost:5901`。
|
||||
|
||||
如果已运行过 `make up`，请在启动自定义容器前先停止并删除默认容器：
|
||||
|
||||
```bash
|
||||
make down
|
||||
# then run the custom docker run command above
|
||||
```
|
||||
|
||||
然后在 `~/.hermes/.env` 中设置：
|
||||
|
||||
```bash
|
||||
CAMOFOX_URL=http://localhost:9377
|
||||
```
|
||||
|
||||
或通过 `hermes tools` → Browser Automation → Camofox 进行配置。
|
||||
|
||||
设置 `CAMOFOX_URL` 后，所有浏览器工具将自动通过 Camofox 路由，而非 Browserbase 或 agent-browser。
|
||||
|
||||
#### 持久化浏览器会话
|
||||
|
||||
默认情况下，每个 Camofox 会话使用随机身份 — Cookie 和登录状态不会在 Agent 重启后保留。要启用持久化浏览器会话，请在 `~/.hermes/config.yaml` 中添加：
|
||||
|
||||
```yaml
|
||||
browser:
|
||||
camofox:
|
||||
managed_persistence: true
|
||||
```
|
||||
|
||||
然后完全重启 Hermes 以使新配置生效。
|
||||
|
||||
:::warning 嵌套路径很重要
|
||||
Hermes 读取的是 `browser.camofox.managed_persistence`，**而非**顶层的 `managed_persistence`。常见错误写法：
|
||||
|
||||
```yaml
|
||||
# ❌ Wrong — Hermes ignores this
|
||||
managed_persistence: true
|
||||
```
|
||||
|
||||
如果该标志放在错误的路径下，Hermes 会静默回退到随机临时 `userId`，您的登录状态将在每次会话后丢失。
|
||||
:::
|
||||
|
||||
##### Hermes 的行为
|
||||
- 向 Camofox 发送确定性的 profile 范围 `userId`，使服务器能够跨会话复用同一 Firefox profile。
|
||||
- 在清理时跳过服务端 context 销毁，使 Cookie 和登录状态在 Agent 任务间保留。
|
||||
- 将 `userId` 限定在当前 Hermes profile 范围内，不同 Hermes profile 对应不同浏览器 profile（profile 隔离）。
|
||||
|
||||
##### Hermes 不做的事
|
||||
- 不会强制 Camofox 服务器持久化。Hermes 只发送稳定的 `userId`；服务器必须通过将该 `userId` 映射到持久化 Firefox profile 目录来支持它。
|
||||
- 如果您的 Camofox 服务器构建将每个请求视为临时的（例如始终调用 `browser.newContext()` 而不加载已存储的 profile），Hermes 无法使这些会话持久化。请确保运行的 Camofox 版本实现了基于 userId 的 profile 持久化。
|
||||
|
||||
##### 验证是否正常工作
|
||||
|
||||
1. 启动 Hermes 和 Camofox 服务器。
|
||||
2. 在浏览器任务中打开 Google（或任意登录网站）并手动登录。
|
||||
3. 正常结束浏览器任务。
|
||||
4. 开始新的浏览器任务。
|
||||
5. 再次打开同一网站 — 应仍处于登录状态。
|
||||
|
||||
如果第 5 步退出了登录，说明 Camofox 服务器未遵守稳定的 `userId`。请检查配置路径，确认编辑 `config.yaml` 后已完全重启 Hermes，并验证您的 Camofox 服务器版本是否支持基于用户的持久化 profile。
|
||||
|
||||
##### 状态存储位置
|
||||
|
||||
Hermes 从 profile 范围目录 `~/.hermes/browser_auth/camofox/`（非默认 profile 则在 `$HERMES_HOME` 下的对应位置）派生稳定的 `userId`。实际浏览器 profile 数据存储在 Camofox 服务器端，以该 `userId` 为键。要完全重置持久化 profile，请在 Camofox 服务器端清除对应数据，并删除相应 Hermes profile 的状态目录。
|
||||
|
||||
#### 外部管理的 Camofox 会话
|
||||
|
||||
当另一个应用驱动可见的 Camofox 浏览器（桌面助手、自定义集成、另一个 Agent）时，可配置 Hermes 在同一身份下运行，而非启动独立的隔离 profile。
|
||||
|
||||
三个参数控制行为：
|
||||
|
||||
| 设置 | 环境变量 | 效果 |
|
||||
|---------|---------|--------|
|
||||
| `browser.camofox.user_id` | `CAMOFOX_USER_ID` | Hermes 创建标签页时使用的 Camofox `userId`。设置此项即进入"外部管理"模式。 |
|
||||
| `browser.camofox.session_key` | `CAMOFOX_SESSION_KEY` | 创建标签页时发送的 `sessionKey`（即 `listItemId`）。用于接管时匹配已有标签页。未设置时默认为每任务值。 |
|
||||
| `browser.camofox.adopt_existing_tab` | `CAMOFOX_ADOPT_EXISTING_TAB` | 为 true 时，Hermes 在首次使用时调用 `GET /tabs?userId=<user_id>` 并优先复用已有标签页，而非新建。 |
|
||||
|
||||
环境变量优先于 `config.yaml`。两种形式均可：
|
||||
|
||||
```yaml
|
||||
browser:
|
||||
camofox:
|
||||
user_id: shared-camofox
|
||||
session_key: visible-tab
|
||||
adopt_existing_tab: true
|
||||
```
|
||||
|
||||
```bash
|
||||
CAMOFOX_USER_ID=shared-camofox
|
||||
CAMOFOX_SESSION_KEY=visible-tab
|
||||
CAMOFOX_ADOPT_EXISTING_TAB=true
|
||||
```
|
||||
|
||||
**设置 `user_id` 后的变化：**
|
||||
|
||||
- Hermes 在任务结束时跳过破坏性清理（与 `managed_persistence: true` 相同）。其他应用的标签页/Cookie/profile 得以保留。
|
||||
- Hermes **不会**调用 `DELETE /sessions/<user_id>` — 该端点会清除所有用户数据，若触发将销毁外部应用的会话。
|
||||
|
||||
**标签页接管的工作方式（当 `adopt_existing_tab: true` 时）：**
|
||||
|
||||
1. 进程启动后首次调用浏览器工具时，Hermes 发出 `GET /tabs?userId=<user_id>`（5 秒超时）。
|
||||
2. 若响应中有标签页的 `listItemId == session_key`，Hermes 接管该组中最近创建的一个。
|
||||
3. 否则，Hermes 接管该用户最近创建的标签页（任意 `listItemId`）。
|
||||
4. 若无标签页或请求失败，Hermes 在下次操作时回退到新建标签页。
|
||||
|
||||
接管仅在会话的 `tab_id` 填充之前触发一次。若外部应用在运行中关闭了被接管的标签页，下次浏览器工具调用将返回 Camofox 错误 — Hermes 不会在每次调用时重新轮询新标签页。
|
||||
|
||||
**选择 `session_key`：** 若要 Hermes 可靠地附加到*特定*已有标签页，请将 `session_key` 设置为外部应用创建该标签页时使用的 `listItemId`。若只设置 `user_id` 而不设置 `session_key`，Hermes 会生成每任务的 `session_key`（`task_<id>`）— Hermes 将与外部应用共享 Cookie 和 profile，但会并排打开自己的标签页而非复用已有标签页。
|
||||
|
||||
**并发说明：** 外部应用和 Hermes 可同时驱动同一 Camofox `userId`，但 Camofox 不会在客户端之间协调每个标签页的焦点。请在应用层协调所有权（例如，Hermes 运行时外部应用暂停）。
|
||||
|
||||
#### VNC 实时查看
|
||||
|
||||
当 Camofox 以有头模式运行（带可见浏览器窗口）时，其健康检查响应中会暴露 VNC 端口。Hermes 自动发现此信息，并在导航响应中包含 VNC URL，Agent 可分享链接供您实时查看浏览器。
|
||||
|
||||
### 通过 CDP 连接本地 Chromium 系浏览器（`/browser connect`）
|
||||
|
||||
除云端提供商外，您还可以通过 Chrome DevTools Protocol（CDP）将 Hermes 浏览器工具连接到本地运行的 Chrome、Brave、Chromium 或 Edge 实例。当您希望实时查看 Agent 操作、与需要自身 Cookie/会话的页面交互，或避免云端浏览器费用时，此方式非常有用。
|
||||
|
||||
:::note
|
||||
`/browser connect` 是**交互式 CLI 斜杠命令** — 不由 gateway 分发。若在 WebUI、Telegram、Discord 或其他 gateway 聊天中尝试运行，消息将作为纯文本发送给 Agent，命令不会执行。请从终端启动 Hermes（`hermes` 或 `hermes chat`）并在那里执行 `/browser connect`。
|
||||
:::
|
||||
|
||||
在 CLI 中使用：
|
||||
|
||||
```
|
||||
/browser connect # Auto-launch/connect to a local Chromium-family browser at http://127.0.0.1:9222
|
||||
/browser connect ws://host:port # Connect to a specific CDP endpoint
|
||||
/browser status # Check current connection
|
||||
/browser disconnect # Detach and return to cloud/local mode
|
||||
```
|
||||
|
||||
若浏览器尚未以远程调试模式运行，Hermes 将尝试自动启动支持的 Chromium 系浏览器并使用 `--remote-debugging-port=9222`。检测范围包括 Brave、Google Chrome、Chromium 和 Microsoft Edge，以及常见 Linux 安装路径（如 `/opt/brave-bin/brave` 和 `/snap/bin/brave`）。
|
||||
|
||||
:::tip
|
||||
要手动启动带 CDP 的 Chromium 系浏览器，请使用专用的 user-data-dir，确保即使浏览器已以普通 profile 运行，调试端口也能正常开启：
|
||||
|
||||
```bash
|
||||
# Linux — Brave
|
||||
brave-browser \
|
||||
--remote-debugging-port=9222 \
|
||||
--user-data-dir=$HOME/.hermes/chrome-debug \
|
||||
--no-first-run \
|
||||
--no-default-browser-check &
|
||||
|
||||
# Linux — Google Chrome
|
||||
google-chrome \
|
||||
--remote-debugging-port=9222 \
|
||||
--user-data-dir=$HOME/.hermes/chrome-debug \
|
||||
--no-first-run \
|
||||
--no-default-browser-check &
|
||||
|
||||
# macOS — Brave
|
||||
"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" \
|
||||
--remote-debugging-port=9222 \
|
||||
--user-data-dir="$HOME/.hermes/chrome-debug" \
|
||||
--no-first-run \
|
||||
--no-default-browser-check &
|
||||
|
||||
# macOS — Google Chrome
|
||||
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
|
||||
--remote-debugging-port=9222 \
|
||||
--user-data-dir="$HOME/.hermes/chrome-debug" \
|
||||
--no-first-run \
|
||||
--no-default-browser-check &
|
||||
```
|
||||
|
||||
然后启动 Hermes CLI 并运行 `/browser connect`。
|
||||
|
||||
**为什么需要 `--user-data-dir`？** 若不指定，在普通实例已运行时启动 Chromium 系浏览器通常只会在现有进程上打开新窗口 — 而该进程启动时未带 `--remote-debugging-port`，因此端口 9222 永远不会开启。专用的 user-data-dir 会强制启动新的浏览器进程，使调试端口正常监听。`--no-first-run --no-default-browser-check` 跳过新 profile 的首次启动向导。
|
||||
:::
|
||||
|
||||
通过 CDP 连接后，所有浏览器工具（`browser_navigate`、`browser_click` 等）将在您的实时浏览器实例上运行，而非启动云端会话。
|
||||
|
||||
### WSL2 + Windows Chrome：优先使用 MCP 而非 `/browser connect`
|
||||
|
||||
若 Hermes 在 WSL2 内运行，但您想控制的 Chrome 窗口在 Windows 宿主机上，`/browser connect` 通常不是最佳方案。
|
||||
|
||||
原因：
|
||||
|
||||
- `/browser connect` 要求 Hermes 本身能访问可用的 CDP 端点
|
||||
- 现代 Chrome 实时调试会话通常暴露仅宿主机本地可访问的端点，WSL 无法像访问经典 `9222` 端口那样直接访问
|
||||
- 即使 Windows Chrome 可调试，最简洁的集成方式通常是让 Windows 侧的浏览器 MCP 服务器连接 Chrome，再让 Hermes 与该 MCP 服务器通信
|
||||
|
||||
对于此场景，建议通过 Hermes MCP 支持使用 `chrome-devtools-mcp`。
|
||||
|
||||
具体配置请参阅 MCP 指南：
|
||||
|
||||
- [在 Hermes 中使用 MCP](../../guides/use-mcp-with-hermes.md#wsl2-bridge-hermes-in-wsl-to-windows-chrome)
|
||||
|
||||
### 本地浏览器模式
|
||||
|
||||
若**未**设置任何云端凭据且未使用 `/browser connect`，Hermes 仍可通过由 `agent-browser` 驱动的本地 Chromium 安装使用浏览器工具。
|
||||
|
||||
### 可选环境变量
|
||||
|
||||
```bash
|
||||
# Residential proxies for better CAPTCHA solving (default: "true")
|
||||
BROWSERBASE_PROXIES=true
|
||||
|
||||
# Advanced stealth with custom Chromium — requires Scale Plan (default: "false")
|
||||
BROWSERBASE_ADVANCED_STEALTH=false
|
||||
|
||||
# Session reconnection after disconnects — requires paid plan (default: "true")
|
||||
BROWSERBASE_KEEP_ALIVE=true
|
||||
|
||||
# Custom session timeout in milliseconds (default: project default)
|
||||
# Examples: 600000 (10min), 1800000 (30min)
|
||||
BROWSERBASE_SESSION_TIMEOUT=600000
|
||||
|
||||
# Inactivity timeout before auto-cleanup in seconds (default: 120)
|
||||
BROWSER_INACTIVITY_TIMEOUT=120
|
||||
|
||||
# Extra Chromium launch flags (comma- or newline-separated). Hermes auto-injects
|
||||
# `--no-sandbox,--disable-dev-shm-usage` when it detects root or AppArmor-restricted
|
||||
# unprivileged user namespaces (Ubuntu 23.10+, DGX Spark, many container images),
|
||||
# so most users don't need to set this. Set it manually only if you need a flag
|
||||
# Hermes doesn't add automatically; setting it disables the auto-injection.
|
||||
AGENT_BROWSER_ARGS=--no-sandbox
|
||||
```
|
||||
|
||||
### 安装 agent-browser CLI
|
||||
|
||||
```bash
|
||||
npm install -g agent-browser
|
||||
# Or install locally in the repo:
|
||||
npm install
|
||||
```
|
||||
|
||||
:::info
|
||||
`browser` 工具集必须包含在配置的 `toolsets` 列表中，或通过 `hermes config set toolsets '["hermes-cli", "browser"]'` 启用。
|
||||
:::
|
||||
|
||||
## 可用工具
|
||||
|
||||
### `browser_navigate`
|
||||
|
||||
导航到指定 URL。必须在其他任何浏览器工具之前调用。初始化 Browserbase 会话。
|
||||
|
||||
```
|
||||
Navigate to https://github.com/NousResearch
|
||||
```
|
||||
|
||||
:::tip
|
||||
对于简单的信息检索，优先使用 `web_search` 或 `web_extract` — 它们更快且成本更低。仅在需要**与页面交互**（点击按钮、填写表单、处理动态内容）时使用浏览器工具。
|
||||
:::
|
||||
|
||||
### `browser_snapshot`
|
||||
|
||||
获取当前页面无障碍树的文本快照。返回带有引用 ID（如 `@e1`、`@e2`）的交互元素，供 `browser_click` 和 `browser_type` 使用。
|
||||
|
||||
- **`full=false`**（默认）：仅显示交互元素的紧凑视图
|
||||
- **`full=true`**：完整页面内容
|
||||
|
||||
超过 8000 字符的快照将由 LLM 自动摘要。
|
||||
|
||||
### `browser_click`
|
||||
|
||||
点击快照中由引用 ID 标识的元素。
|
||||
|
||||
```
|
||||
Click @e5 to press the "Sign In" button
|
||||
```
|
||||
|
||||
### `browser_type`
|
||||
|
||||
向输入框输入文本。先清空字段，再输入新文本。
|
||||
|
||||
```
|
||||
Type "hermes agent" into the search field @e3
|
||||
```
|
||||
|
||||
### `browser_scroll`
|
||||
|
||||
向上或向下滚动页面以显示更多内容。
|
||||
|
||||
```
|
||||
Scroll down to see more results
|
||||
```
|
||||
|
||||
### `browser_press`
|
||||
|
||||
按下键盘按键。适用于提交表单或导航。
|
||||
|
||||
```
|
||||
Press Enter to submit the form
|
||||
```
|
||||
|
||||
支持的按键：`Enter`、`Tab`、`Escape`、`ArrowDown`、`ArrowUp` 等。
|
||||
|
||||
### `browser_back`
|
||||
|
||||
在浏览器历史记录中返回上一页。
|
||||
|
||||
### `browser_get_images`
|
||||
|
||||
列出当前页面上所有图片及其 URL 和 alt 文本。适用于查找需要分析的图片。
|
||||
|
||||
### `browser_vision`
|
||||
|
||||
截图并使用视觉 AI 进行分析。当文本快照无法捕获重要视觉信息时使用 — 尤其适用于 CAPTCHA、复杂布局或视觉验证挑战。
|
||||
|
||||
截图会持久保存，文件路径与 AI 分析结果一并返回。在消息平台（Telegram、Discord、Slack、WhatsApp）上，您可以要求 Agent 分享截图 — 它将通过 `MEDIA:` 机制作为原生图片附件发送。
|
||||
|
||||
```
|
||||
What does the chart on this page show?
|
||||
```
|
||||
|
||||
截图存储在 `~/.hermes/cache/screenshots/`，24 小时后自动清理。
|
||||
|
||||
### `browser_console`
|
||||
|
||||
获取当前页面的浏览器控制台输出（log/warn/error 消息）及未捕获的 JavaScript 异常。对于检测无障碍树中不可见的静默 JS 错误至关重要。
|
||||
|
||||
```
|
||||
Check the browser console for any JavaScript errors
|
||||
```
|
||||
|
||||
使用 `clear=True` 可在读取后清空控制台，使后续调用只显示新消息。
|
||||
|
||||
`browser_console` 在带有 `expression` 参数调用时也可执行 JavaScript — 与 DevTools 控制台形式相同，结果以解析后的形式返回（JSON 序列化的对象变为 dict；原始值保持原始类型）。
|
||||
|
||||
```
|
||||
browser_console(expression="document.querySelector('h1').textContent")
|
||||
browser_console(expression="JSON.stringify(performance.timing)")
|
||||
```
|
||||
|
||||
当当前会话存在活跃的 CDP 监督器时（通常适用于任何对 CDP 兼容后端运行过 `browser_navigate` 的会话），执行通过监督器的持久 WebSocket 进行 — 无子进程启动开销。否则回退到标准 agent-browser CLI 路径。两种方式行为完全相同，仅延迟有差异。
|
||||
|
||||
### `browser_cdp`
|
||||
|
||||
原始 Chrome DevTools Protocol 直通 — 用于其他工具未覆盖的浏览器操作的逃生舱口。适用于原生对话框处理、iframe 范围内的执行、Cookie/网络控制，或 Agent 需要的任何 CDP 命令。
|
||||
|
||||
**仅在会话启动时 CDP 端点可访问的情况下可用** — 即 `/browser connect` 已连接到运行中的 Chrome、Brave、Chromium 或 Edge 浏览器，或 `config.yaml` 中设置了 `browser.cdp_url`。默认本地 agent-browser 模式、Camofox 和云端提供商（Browserbase、Browser Use、Firecrawl）目前不向此工具暴露 CDP — 云端提供商有每会话 CDP URL，但实时会话路由是后续功能。
|
||||
|
||||
**CDP 方法参考：** https://chromedevtools.github.io/devtools-protocol/ — Agent 可通过 `web_extract` 访问特定方法页面以查阅参数和返回结构。
|
||||
|
||||
常见用法：
|
||||
|
||||
```
|
||||
# List tabs (browser-level, no target_id)
|
||||
browser_cdp(method="Target.getTargets")
|
||||
|
||||
# Handle a native JS dialog on a tab
|
||||
browser_cdp(method="Page.handleJavaScriptDialog",
|
||||
params={"accept": true, "promptText": ""},
|
||||
target_id="<tabId>")
|
||||
|
||||
# Evaluate JS in a specific tab
|
||||
browser_cdp(method="Runtime.evaluate",
|
||||
params={"expression": "document.title", "returnByValue": true},
|
||||
target_id="<tabId>")
|
||||
|
||||
# Get all cookies
|
||||
browser_cdp(method="Network.getAllCookies")
|
||||
```
|
||||
|
||||
浏览器级方法（`Target.*`、`Browser.*`、`Storage.*`）省略 `target_id`。页面级方法（`Page.*`、`Runtime.*`、`DOM.*`、`Emulation.*`）需要来自 `Target.getTargets` 的 `target_id`。每次无状态调用相互独立 — 调用间不保留会话状态。
|
||||
|
||||
**跨域 iframe：** 传入 `frame_id`（来自 `browser_snapshot.frame_tree.children[]` 中 `is_oopif=true` 的条目）可通过监督器的实时会话路由该 iframe 的 CDP 调用。这是在 Browserbase 上对跨域 iframe 执行 `Runtime.evaluate` 的方式，避免无状态 CDP 连接遭遇签名 URL 过期问题。示例：
|
||||
|
||||
```
|
||||
browser_cdp(
|
||||
method="Runtime.evaluate",
|
||||
params={"expression": "document.title", "returnByValue": True},
|
||||
frame_id="<frame_id from browser_snapshot>",
|
||||
)
|
||||
```
|
||||
|
||||
同域 iframe 无需 `frame_id` — 在顶层 `Runtime.evaluate` 中使用 `document.querySelector('iframe').contentDocument` 即可。
|
||||
|
||||
### `browser_dialog`
|
||||
|
||||
响应原生 JS 对话框（`alert` / `confirm` / `prompt` / `beforeunload`）。在此工具出现之前，对话框会静默阻塞页面的 JavaScript 线程，后续 `browser_*` 调用会挂起或抛出异常；现在 Agent 可在 `browser_snapshot` 输出中看到待处理对话框并显式响应。
|
||||
|
||||
**工作流程：**
|
||||
1. 调用 `browser_snapshot`。若对话框正在阻塞页面，将显示为 `pending_dialogs: [{"id": "d-1", "type": "alert", "message": "..."}]`。
|
||||
2. 调用 `browser_dialog(action="accept")` 或 `browser_dialog(action="dismiss")`。对于 `prompt()` 对话框，传入 `prompt_text="..."` 提供响应内容。
|
||||
3. 重新快照 — `pending_dialogs` 为空；页面 JS 线程已恢复。
|
||||
|
||||
**检测通过持久 CDP 监督器自动进行** — 每个任务一个 WebSocket，订阅 Page/Runtime/Target 事件。监督器还会在快照中填充 `frame_tree` 字段，使 Agent 可查看当前页面的 iframe 结构，包括跨域（OOPIF）iframe。
|
||||
|
||||
**可用性矩阵：**
|
||||
|
||||
| 后端 | 通过 `pending_dialogs` 检测 | 响应（`browser_dialog` 工具） |
|
||||
|---|---|---|
|
||||
| 通过 `/browser connect` 或 `browser.cdp_url` 连接的本地 Chrome | ✓ | ✓ 完整工作流 |
|
||||
| Browserbase | ✓ | ✓ 完整工作流（通过注入的 XHR 桥接） |
|
||||
| Camofox / 默认本地 agent-browser | ✗ | ✗（无 CDP 端点） |
|
||||
|
||||
**在 Browserbase 上的工作原理。** Browserbase 的 CDP 代理会在约 10ms 内在服务端自动关闭真实的原生对话框，因此无法使用 `Page.handleJavaScriptDialog`。监督器通过 `Page.addScriptToEvaluateOnNewDocument` 注入一段小脚本，将 `window.alert`/`confirm`/`prompt` 替换为同步 XHR。我们通过 `Fetch.enable` 拦截这些 XHR — 页面 JS 线程在 XHR 上保持阻塞，直到我们用 Agent 的响应调用 `Fetch.fulfillRequest`。`prompt()` 的返回值原样传回页面 JS。
|
||||
|
||||
**对话框策略**在 `config.yaml` 的 `browser.dialog_policy` 下配置：
|
||||
|
||||
| 策略 | 行为 |
|
||||
|--------|----------|
|
||||
| `must_respond`（默认） | 捕获，在快照中显示，等待显式 `browser_dialog()` 调用。在 `browser.dialog_timeout_s`（默认 300 秒）后安全自动关闭，防止有问题的 Agent 永久阻塞。 |
|
||||
| `auto_dismiss` | 捕获，立即关闭。Agent 仍可在 `browser_state` 历史中看到对话框，但无需操作。 |
|
||||
| `auto_accept` | 捕获，立即接受。适用于导航带有频繁 `beforeunload` 提示的页面。 |
|
||||
|
||||
`browser_snapshot.frame_tree` 中的**帧树**上限为 30 帧、OOPIF 深度 2，以控制广告密集页面的负载大小。达到限制时会显示 `truncated: true` 标志；需要完整帧树的 Agent 可使用 `browser_cdp` 配合 `Page.getFrameTree`。
|
||||
|
||||
## 实际示例
|
||||
|
||||
### 填写网页表单
|
||||
|
||||
```
|
||||
User: Sign up for an account on example.com with my email john@example.com
|
||||
|
||||
Agent workflow:
|
||||
1. browser_navigate("https://example.com/signup")
|
||||
2. browser_snapshot() → sees form fields with refs
|
||||
3. browser_type(ref="@e3", text="john@example.com")
|
||||
4. browser_type(ref="@e5", text="SecurePass123")
|
||||
5. browser_click(ref="@e8") → clicks "Create Account"
|
||||
6. browser_snapshot() → confirms success
|
||||
```
|
||||
|
||||
### 研究动态内容
|
||||
|
||||
```
|
||||
User: What are the top trending repos on GitHub right now?
|
||||
|
||||
Agent workflow:
|
||||
1. browser_navigate("https://github.com/trending")
|
||||
2. browser_snapshot(full=true) → reads trending repo list
|
||||
3. Returns formatted results
|
||||
```
|
||||
|
||||
## 会话录制
|
||||
|
||||
自动将浏览器会话录制为 WebM 视频文件：
|
||||
|
||||
```yaml
|
||||
browser:
|
||||
record_sessions: true # default: false
|
||||
```
|
||||
|
||||
启用后，录制在首次 `browser_navigate` 时自动开始，会话关闭时保存到 `~/.hermes/browser_recordings/`。本地模式和云端模式（Browserbase）均支持。超过 72 小时的录制文件自动清理。
|
||||
|
||||
## 隐身功能
|
||||
|
||||
Browserbase 提供自动隐身能力：
|
||||
|
||||
| 功能 | 默认状态 | 说明 |
|
||||
|---------|---------|-------|
|
||||
| 基础隐身 | 始终开启 | 随机指纹、视口随机化、CAPTCHA 解决 |
|
||||
| 住宅代理 | 开启 | 通过住宅 IP 路由以提高访问成功率 |
|
||||
| 高级隐身 | 关闭 | 自定义 Chromium 构建，需要 Scale 计划 |
|
||||
| Keep Alive | 开启 | 网络中断后的会话重连 |
|
||||
|
||||
:::note
|
||||
若付费功能在您的计划中不可用，Hermes 会自动降级 — 先禁用 `keepAlive`，再禁用代理 — 确保免费计划也能正常浏览。
|
||||
:::
|
||||
|
||||
## 会话管理
|
||||
|
||||
- 每个任务通过 Browserbase 获得独立的浏览器会话
|
||||
- 非活跃会话在超时后自动清理（默认：2 分钟）
|
||||
- 后台线程每 30 秒检查一次过期会话
|
||||
- 进程退出时执行紧急清理，防止孤立会话
|
||||
- 通过 Browserbase API 释放会话（`REQUEST_RELEASE` 状态）
|
||||
|
||||
## 限制
|
||||
|
||||
- **基于文本的交互** — 依赖无障碍树，而非像素坐标
|
||||
- **快照大小** — 大型页面可能在 8000 字符处被截断或由 LLM 摘要
|
||||
- **会话超时** — 云端会话根据提供商计划设置过期
|
||||
- **费用** — 云端会话消耗提供商额度；对话结束或非活跃后会话自动清理。使用 `/browser connect` 可免费本地浏览。
|
||||
- **不支持文件下载** — 无法从浏览器下载文件
|
||||
+269
@@ -0,0 +1,269 @@
|
||||
---
|
||||
sidebar_position: 12
|
||||
sidebar_label: "内置插件"
|
||||
title: "内置插件"
|
||||
description: "随 Hermes Agent 附带并通过生命周期 hook 自动运行的插件——disk-cleanup 等"
|
||||
---
|
||||
|
||||
# 内置插件
|
||||
|
||||
Hermes 随仓库附带了一小组插件。它们位于 `<repo>/plugins/<name>/`，与用户安装在 `~/.hermes/plugins/` 中的插件一同自动加载。它们使用与第三方插件相同的插件接口——hook、工具、斜杠命令——只是在仓库内维护。
|
||||
|
||||
请参阅 [插件](/user-guide/features/plugins) 页面了解通用插件系统，以及 [构建 Hermes 插件](/guides/build-a-hermes-plugin) 了解如何编写自己的插件。
|
||||
|
||||
## 发现机制
|
||||
|
||||
`PluginManager` 按顺序扫描四个来源：
|
||||
|
||||
1. **内置（Bundled）** — `<repo>/plugins/<name>/`（本页所记录的内容）
|
||||
2. **用户（User）** — `~/.hermes/plugins/<name>/`
|
||||
3. **项目（Project）** — `./.hermes/plugins/<name>/`（需要 `HERMES_ENABLE_PROJECT_PLUGINS=1`）
|
||||
4. **Pip 入口点（Entry points）** — `hermes_agent.plugins`
|
||||
|
||||
名称冲突时，后面的来源优先——名为 `disk-cleanup` 的用户插件会替换内置版本。
|
||||
|
||||
`plugins/memory/` 和 `plugins/context_engine/` 被刻意排除在内置扫描之外。这两个目录使用各自的发现路径，因为内存提供者和上下文引擎是通过 `hermes memory setup` / 配置中的 `context.engine` 进行单选配置的提供者。
|
||||
|
||||
## 内置插件默认不启用
|
||||
|
||||
内置插件随附时处于禁用状态。发现机制会找到它们（它们会出现在 `hermes plugins list` 和交互式 `hermes plugins` UI 中），但在你明确启用之前不会加载：
|
||||
|
||||
```bash
|
||||
hermes plugins enable disk-cleanup
|
||||
```
|
||||
|
||||
或通过 `~/.hermes/config.yaml`：
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
enabled:
|
||||
- disk-cleanup
|
||||
```
|
||||
|
||||
这与用户安装的插件使用的机制相同。内置插件永远不会自动启用——无论是全新安装，还是现有用户升级到更新版本的 Hermes，都需要你明确选择启用。
|
||||
|
||||
要再次关闭内置插件：
|
||||
|
||||
```bash
|
||||
hermes plugins disable disk-cleanup
|
||||
# 或：从 config.yaml 的 plugins.enabled 中移除它
|
||||
```
|
||||
|
||||
## 当前附带的插件
|
||||
|
||||
仓库在 `plugins/` 下附带了以下内置插件。所有插件均需手动启用——通过 `hermes plugins enable <name>` 启用。
|
||||
|
||||
| 插件 | 类型 | 用途 |
|
||||
|---|---|---|
|
||||
| `disk-cleanup` | hook + 斜杠命令 | 自动追踪临时文件并在会话结束时清理 |
|
||||
| `observability/langfuse` | hook | 将轮次 / LLM 调用 / 工具追踪到 [Langfuse](https://langfuse.com) |
|
||||
| `spotify` | 后端（7 个工具） | 原生 Spotify 播放、队列、搜索、播放列表、专辑、曲库 |
|
||||
| `google_meet` | 独立插件 | 加入 Meet 通话、实时字幕转录、可选实时双工音频 |
|
||||
| `image_gen/openai` | 图像后端 | OpenAI `gpt-image-2` 图像生成后端（FAL 的替代方案） |
|
||||
| `image_gen/openai-codex` | 图像后端 | 通过 Codex OAuth 使用 OpenAI 图像生成 |
|
||||
| `image_gen/xai` | 图像后端 | xAI `grok-2-image` 后端 |
|
||||
| `hermes-achievements` | 仪表盘标签页 | Steam 风格的可收集徽章，根据你真实的 Hermes 会话历史生成 |
|
||||
| `kanban/dashboard` | 仪表盘标签页 | 多智能体调度器的看板（Kanban）UI——任务、评论、扇出、切换看板。参见 [Kanban 多智能体](./kanban.md)。 |
|
||||
|
||||
内存提供者（`plugins/memory/*`）和上下文引擎（`plugins/context_engine/*`）在 [内存提供者](./memory-providers.md) 中单独列出——它们分别通过 `hermes memory` 和 `hermes plugins` 管理。以下是两个长期运行的基于 hook 的插件的详细说明。
|
||||
|
||||
### disk-cleanup
|
||||
|
||||
自动追踪并删除会话期间创建的临时文件——测试脚本、临时输出、cron 日志、过期的 Chrome 配置文件——无需 agent 记住调用工具。
|
||||
|
||||
**工作原理：**
|
||||
|
||||
| Hook | 行为 |
|
||||
|---|---|
|
||||
| `post_tool_call` | 当 `write_file` / `terminal` / `patch` 在 `HERMES_HOME` 或 `/tmp/hermes-*` 内创建匹配 `test_*`、`tmp_*` 或 `*.test.*` 的文件时，静默追踪为 `test` / `temp` / `cron-output`。 |
|
||||
| `on_session_end` | 如果本轮中有任何测试文件被自动追踪，则执行安全的 `quick` 清理并记录一行摘要。否则保持静默。 |
|
||||
|
||||
**删除规则：**
|
||||
|
||||
| 类别 | 阈值 | 确认 |
|
||||
|---|---|---|
|
||||
| `test` | 每次会话结束 | 从不 |
|
||||
| `temp` | 追踪后超过 7 天 | 从不 |
|
||||
| `cron-output` | 追踪后超过 14 天 | 从不 |
|
||||
| HERMES_HOME 下的空目录 | 始终 | 从不 |
|
||||
| `research` | 超过 30 天，且超出最新 10 个 | 始终（仅 deep 模式） |
|
||||
| `chrome-profile` | 追踪后超过 14 天 | 始终（仅 deep 模式） |
|
||||
| 超过 500 MB 的文件 | 从不自动删除 | 始终（仅 deep 模式） |
|
||||
|
||||
**斜杠命令** — `/disk-cleanup` 在 CLI 和 gateway 会话中均可用：
|
||||
|
||||
```
|
||||
/disk-cleanup status # 分类明细 + 最大的 10 个文件
|
||||
/disk-cleanup dry-run # 预览，不实际删除
|
||||
/disk-cleanup quick # 立即执行安全清理
|
||||
/disk-cleanup deep # quick + 列出需要确认的项目
|
||||
/disk-cleanup track <path> <category> # 手动追踪
|
||||
/disk-cleanup forget <path> # 停止追踪（不删除）
|
||||
```
|
||||
|
||||
**状态** — 所有内容存储在 `$HERMES_HOME/disk-cleanup/`：
|
||||
|
||||
| 文件 | 内容 |
|
||||
|---|---|
|
||||
| `tracked.json` | 已追踪路径，包含类别、大小和时间戳 |
|
||||
| `tracked.json.bak` | 上述文件的原子写入备份 |
|
||||
| `cleanup.log` | 每次追踪 / 跳过 / 拒绝 / 删除操作的仅追加审计日志 |
|
||||
|
||||
**安全性** — 清理操作仅涉及 `HERMES_HOME` 或 `/tmp/hermes-*` 下的路径。Windows 挂载点（`/mnt/c/...`）会被拒绝。已知的顶级状态目录（`logs/`、`memories/`、`sessions/`、`cron/`、`cache/`、`skills/`、`plugins/`、`disk-cleanup/` 本身）即使为空也不会被删除——全新安装不会在第一次会话结束时被清空。
|
||||
|
||||
**启用：** `hermes plugins enable disk-cleanup`（或在 `hermes plugins` 中勾选复选框）。
|
||||
|
||||
**再次禁用：** `hermes plugins disable disk-cleanup`。
|
||||
|
||||
### observability/langfuse
|
||||
|
||||
将 Hermes 的轮次、LLM 调用和工具调用追踪到 [Langfuse](https://langfuse.com)——一个开源 LLM 可观测性平台。每轮一个 span，每次 API 调用一个 generation，每次工具调用一个 tool observation。用量总计、各类型 token 数量和成本估算来自 Hermes 的标准 `agent.usage_pricing` 数据，因此 Langfuse 仪表盘看到的分类（input / output / `cache_read_input_tokens` / `cache_creation_input_tokens` / `reasoning_tokens`）与 `hermes logs` 中显示的一致。
|
||||
|
||||
该插件采用失败开放（fail-open）策略：未安装 SDK、无凭据或 Langfuse 出现瞬时错误——所有情况都会在 hook 中静默处理为无操作。agent 循环不受任何影响。
|
||||
|
||||
**设置：**
|
||||
|
||||
```bash
|
||||
pip install langfuse
|
||||
hermes plugins enable observability/langfuse
|
||||
```
|
||||
|
||||
或在交互式 `hermes plugins` UI 中勾选复选框。然后将凭据写入 `~/.hermes/.env`：
|
||||
|
||||
```bash
|
||||
HERMES_LANGFUSE_PUBLIC_KEY=pk-lf-...
|
||||
HERMES_LANGFUSE_SECRET_KEY=sk-lf-...
|
||||
HERMES_LANGFUSE_BASE_URL=https://cloud.langfuse.com # 或你的自托管 URL
|
||||
```
|
||||
|
||||
**工作原理：**
|
||||
|
||||
| Hook | 行为 |
|
||||
|---|---|
|
||||
| `pre_api_request` / `pre_llm_call` | 打开（或复用）每轮的根 span "Hermes turn"。为本次 API 调用启动一个 `generation` 子 observation，将最近的消息序列化为输入。 |
|
||||
| `post_api_request` / `post_llm_call` | 关闭 generation，附加 `usage_details`、`cost_details`、`finish_reason`、助手输出和工具调用。如果没有工具调用且内容非空，则关闭本轮。 |
|
||||
| `pre_tool_call` | 启动一个带有经过清理的 `args` 的 `tool` 子 observation。 |
|
||||
| `post_tool_call` | 关闭 tool observation，附加经过清理的 `result`。`read_file` 的内容会被摘要化（头部 + 尾部 + 省略行数），以使大文件读取保持在 `HERMES_LANGFUSE_MAX_CHARS` 以内。 |
|
||||
|
||||
会话分组基于 Hermes 会话 ID（或子 agent 的任务 ID），通过 `langfuse.propagate_attributes` 实现，因此单次 `hermes chat` 会话中的所有内容都归属于同一个 Langfuse session。
|
||||
|
||||
**验证：**
|
||||
|
||||
```bash
|
||||
hermes plugins list # observability/langfuse 应显示 "enabled"
|
||||
hermes chat -q "hello" # 在 Langfuse UI 中检查是否有 "Hermes turn" trace
|
||||
```
|
||||
|
||||
**可选调优**（在 `.env` 中）：
|
||||
|
||||
| 变量 | 默认值 | 用途 |
|
||||
|---|---|---|
|
||||
| `HERMES_LANGFUSE_ENV` | — | trace 上的环境标签（`production`、`staging` 等） |
|
||||
| `HERMES_LANGFUSE_RELEASE` | — | 发布/版本标签 |
|
||||
| `HERMES_LANGFUSE_SAMPLE_RATE` | `1.0` | 传递给 SDK 的采样率（0.0–1.0） |
|
||||
| `HERMES_LANGFUSE_MAX_CHARS` | `12000` | 消息内容 / 工具参数 / 工具结果的单字段截断长度 |
|
||||
| `HERMES_LANGFUSE_DEBUG` | `false` | 向 `agent.log` 输出详细插件日志 |
|
||||
|
||||
Hermes 前缀的环境变量和标准 SDK 环境变量（`LANGFUSE_PUBLIC_KEY`、`LANGFUSE_SECRET_KEY`、`LANGFUSE_BASE_URL`）均被接受——两者同时设置时，Hermes 前缀的优先。
|
||||
|
||||
**性能：** Langfuse 客户端在第一次 hook 调用后被缓存。如果凭据或 SDK 缺失，该决定也会被缓存——后续 hook 会快速返回，不再重新检查环境变量或重新加载配置。
|
||||
|
||||
**禁用：** `hermes plugins disable observability/langfuse`。插件模块仍会被发现，但在你重新启用之前不会运行任何模块代码。
|
||||
|
||||
### google_meet
|
||||
|
||||
让 agent **加入、转录并参与 Google Meet 通话**——记录会议笔记、事后总结对话内容、跟进特定要点，并可选择通过 TTS 将回复发回通话中。
|
||||
|
||||
**新增功能：**
|
||||
|
||||
- 使用浏览器自动化加入 Meet URL 的无头虚拟参与者
|
||||
- 通过配置的 STT 提供者对会议音频进行实时转录
|
||||
- agent 调用的 `meet_summarize` / `meet_speak` / `meet_followup` 工具集，用于对所听内容采取行动
|
||||
- 会后产物（转录、带发言人归属的笔记、行动项）保存在 `~/.hermes/cache/google_meet/<meeting_id>/`
|
||||
|
||||
**设置：**
|
||||
|
||||
```bash
|
||||
hermes plugins enable google_meet
|
||||
# 首次使用时会提示你通过插件的 OAuth 流程登录——
|
||||
# 需要有 Meet 访问权限的 Google 账号。如果会议强制要求
|
||||
# "仅受邀参与者可加入"，可能需要主持人批准。
|
||||
```
|
||||
|
||||
在聊天中使用：
|
||||
|
||||
> "加入 meet.google.com/abc-defg-hij 并记录笔记。通话结束后，给我发一份包含行动项的摘要。"
|
||||
|
||||
agent 会启动会议加入流程，在通话进行时将转录内容流式传输到其上下文中，并在会议结束（或你告知停止）时生成结构化摘要。
|
||||
|
||||
**适用场景：** 需要机器人转录并为异步参与者总结的定期站会；需要结构化笔记的访谈式会议；任何原本需要 Fireflies / Otter / Grain 的场景。如果你不希望有 AI 在旁监听——请勿启用。
|
||||
|
||||
**禁用：** `hermes plugins disable google_meet`。已缓存的转录和录音保留在 `~/.hermes/cache/google_meet/`，直到你手动删除。
|
||||
|
||||
### hermes-achievements
|
||||
|
||||
在仪表盘中添加一个 **Steam 风格的成就标签页**——60 多个可收集的分级徽章，根据你真实的 Hermes 会话历史生成。工具链成就、调试模式、vibe-coding 连击、技能/内存使用、模型/提供者多样性、生活方式特征（周末和夜间会话）。最初由 [@PCinkusz](https://github.com/PCinkusz) 作为外部插件编写；已并入仓库，以便与 Hermes 功能变更保持同步。
|
||||
|
||||
**工作原理：**
|
||||
|
||||
- 在仪表盘后端扫描你的整个 `~/.hermes/state.db` 会话历史
|
||||
- 每个会话的统计数据按 `(started_at, last_active)` 指纹缓存，因此后续扫描只重新分析新增或变更的会话
|
||||
- 首次扫描在后台线程中运行——即使数据库有数千个会话，仪表盘也不会阻塞等待
|
||||
- 解锁状态持久化到 `$HERMES_HOME/plugins/hermes-achievements/state.json`
|
||||
|
||||
**等级进阶：** 铜 → 银 → 金 → 钻石 → 奥林匹斯。每张卡片都有"计算方式"部分，列出所追踪的确切指标。
|
||||
|
||||
**成就状态：**
|
||||
|
||||
| 状态 | 含义 |
|
||||
|---|---|
|
||||
| 已解锁 | 至少达到一个等级 |
|
||||
| 已发现 | 已知成就，进度可见，尚未获得 |
|
||||
| 隐藏 | 在 Hermes 检测到你历史中的第一个相关信号之前保持隐藏 |
|
||||
|
||||
**API** — 路由挂载在 `/api/plugins/hermes-achievements/` 下：
|
||||
|
||||
| 端点 | 用途 |
|
||||
|---|---|
|
||||
| `GET /achievements` | 完整目录，包含每个徽章的解锁状态（首次冷扫描运行期间返回待处理占位符） |
|
||||
| `GET /scan-status` | 后台扫描器状态：`idle` / `running` / `failed`，上次耗时，运行次数 |
|
||||
| `GET /recent-unlocks` | 最近解锁的 20 个徽章，最新的在前 |
|
||||
| `GET /sessions/{id}/badges` | 主要在某个特定会话中获得的徽章 |
|
||||
| `POST /rescan` | 手动同步重新扫描（阻塞；在用户点击重新扫描按钮时使用） |
|
||||
| `POST /reset-state` | 清除解锁历史和缓存快照 |
|
||||
|
||||
**状态文件** — 位于 `$HERMES_HOME/plugins/hermes-achievements/`：
|
||||
|
||||
| 文件 | 内容 |
|
||||
|---|---|
|
||||
| `state.json` | 解锁历史：你获得了哪些徽章以及获得时间。在 Hermes 更新间保持稳定。 |
|
||||
| `scan_snapshot.json` | 上次完成的扫描载荷（在仪表盘加载时立即提供） |
|
||||
| `scan_checkpoint.json` | 按指纹键控的每会话统计缓存（使热重扫描更快） |
|
||||
|
||||
**性能说明：**
|
||||
|
||||
- 约 8,000 个会话的冷扫描需要几分钟。它在首次仪表盘请求时在后台线程中运行；UI 显示待处理占位符并轮询 `/scan-status`。
|
||||
- **冷扫描期间的增量结果** — 扫描器每约 250 个会话发布一次部分快照，因此每次仪表盘刷新都会显示更多已解锁的徽章。不会出现盯着零数字等待一分钟的情况。
|
||||
- 热重扫描对每个 `started_at` + `last_active` 指纹与检查点匹配的会话复用每会话统计——即使在大型历史记录上也能在几秒内完成。
|
||||
- 内存快照 TTL 为 120 秒；过期请求立即提供旧快照并触发后台刷新。不会因为 TTL 过期就让你等待加载动画。
|
||||
|
||||
**启用：** 无需启用——`hermes-achievements` 是一个仅限仪表盘的插件（无生命周期 hook，无模型可见工具）。它在 `hermes dashboard` 首次启动时自动注册为标签页。`plugins.enabled` 配置仅控制生命周期/工具插件；仪表盘插件完全通过其 `dashboard/manifest.json` 发现。
|
||||
|
||||
**退出：** 删除或重命名 `plugins/hermes-achievements/dashboard/manifest.json`，或在 `~/.hermes/plugins/hermes-achievements/` 中用同名用户插件覆盖它（该插件不包含仪表盘）。`$HERMES_HOME/plugins/hermes-achievements/` 下的插件状态文件会保留——重新安装后你的解锁历史依然存在。
|
||||
|
||||
## 添加内置插件
|
||||
|
||||
内置插件的编写方式与其他 Hermes 插件完全相同——参见 [构建 Hermes 插件](/guides/build-a-hermes-plugin)。唯一的区别是：
|
||||
|
||||
- 目录位于 `<repo>/plugins/<name>/`，而非 `~/.hermes/plugins/<name>/`
|
||||
- 在 `hermes plugins list` 中，manifest 来源显示为 `bundled`
|
||||
- 同名用户插件会覆盖内置版本
|
||||
|
||||
以下情况适合将插件纳入内置：
|
||||
|
||||
- 没有可选依赖项（或它们已经是 `pip install .[all]` 的依赖）
|
||||
- 该行为对大多数用户有益，且是默认启用、需要主动关闭的
|
||||
- 逻辑与生命周期 hook 紧密结合，否则 agent 需要记住手动调用
|
||||
- 在不扩展模型可见工具接口的前提下补充核心能力
|
||||
|
||||
反例——应作为用户可安装插件而非内置插件的情况：需要 API 密钥的第三方集成、小众工作流、大型依赖树、任何会默认改变 agent 行为的内容。
|
||||
+240
@@ -0,0 +1,240 @@
|
||||
---
|
||||
sidebar_position: 8
|
||||
title: "代码执行"
|
||||
description: "通过 RPC 工具访问实现程序化 Python 执行——将多步骤工作流压缩至单次对话轮次"
|
||||
---
|
||||
|
||||
# 代码执行（程序化工具调用）
|
||||
|
||||
`execute_code` 工具允许 agent 编写调用 Hermes 工具的 Python 脚本，将多步骤工作流压缩至单次 LLM 对话轮次。脚本在 agent 宿主机的子进程中运行，通过 Unix 域套接字 RPC 与 Hermes 通信。
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. Agent 编写使用 `from hermes_tools import ...` 的 Python 脚本
|
||||
2. Hermes 生成带有 RPC 函数的 `hermes_tools.py` 存根模块
|
||||
3. Hermes 打开 Unix 域套接字并启动 RPC 监听线程
|
||||
4. 脚本在子进程中运行——工具调用通过套接字传回 Hermes
|
||||
5. 只有脚本的 `print()` 输出会返回给 LLM；中间工具结果不会进入上下文窗口
|
||||
|
||||
```python
|
||||
# The agent can write scripts like:
|
||||
from hermes_tools import web_search, web_extract
|
||||
|
||||
results = web_search("Python 3.13 features", limit=5)
|
||||
for r in results["data"]["web"]:
|
||||
content = web_extract([r["url"]])
|
||||
# ... filter and process ...
|
||||
print(summary)
|
||||
```
|
||||
|
||||
**脚本内可用工具：** `web_search`、`web_extract`、`read_file`、`write_file`、`search_files`、`patch`、`terminal`（仅前台模式）。
|
||||
|
||||
## Agent 何时使用此功能
|
||||
|
||||
当存在以下情况时，agent 会使用 `execute_code`：
|
||||
|
||||
- **3 次及以上工具调用**，且调用之间包含处理逻辑
|
||||
- 批量数据过滤或条件分支
|
||||
- 对结果进行循环处理
|
||||
|
||||
核心优势：中间工具结果不会进入上下文窗口——只有最终的 `print()` 输出会返回，大幅降低 token 用量。
|
||||
|
||||
## 实际示例
|
||||
|
||||
### 数据处理流水线
|
||||
|
||||
```python
|
||||
from hermes_tools import search_files, read_file
|
||||
import json
|
||||
|
||||
# Find all config files and extract database settings
|
||||
matches = search_files("database", path=".", file_glob="*.yaml", limit=20)
|
||||
configs = []
|
||||
for match in matches.get("matches", []):
|
||||
content = read_file(match["path"])
|
||||
configs.append({"file": match["path"], "preview": content["content"][:200]})
|
||||
|
||||
print(json.dumps(configs, indent=2))
|
||||
```
|
||||
|
||||
### 多步骤网络调研
|
||||
|
||||
```python
|
||||
from hermes_tools import web_search, web_extract
|
||||
import json
|
||||
|
||||
# Search, extract, and summarize in one turn
|
||||
results = web_search("Rust async runtime comparison 2025", limit=5)
|
||||
summaries = []
|
||||
for r in results["data"]["web"]:
|
||||
page = web_extract([r["url"]])
|
||||
for p in page.get("results", []):
|
||||
if p.get("content"):
|
||||
summaries.append({
|
||||
"title": r["title"],
|
||||
"url": r["url"],
|
||||
"excerpt": p["content"][:500]
|
||||
})
|
||||
|
||||
print(json.dumps(summaries, indent=2))
|
||||
```
|
||||
|
||||
### 批量文件重构
|
||||
|
||||
```python
|
||||
from hermes_tools import search_files, read_file, patch
|
||||
|
||||
# Find all Python files using deprecated API and fix them
|
||||
matches = search_files("old_api_call", path="src/", file_glob="*.py")
|
||||
fixed = 0
|
||||
for match in matches.get("matches", []):
|
||||
result = patch(
|
||||
path=match["path"],
|
||||
old_string="old_api_call(",
|
||||
new_string="new_api_call(",
|
||||
replace_all=True
|
||||
)
|
||||
if "error" not in str(result):
|
||||
fixed += 1
|
||||
|
||||
print(f"Fixed {fixed} files out of {len(matches.get('matches', []))} matches")
|
||||
```
|
||||
|
||||
### 构建与测试流水线
|
||||
|
||||
```python
|
||||
from hermes_tools import terminal, read_file
|
||||
import json
|
||||
|
||||
# Run tests, parse results, and report
|
||||
result = terminal("cd /project && python -m pytest --tb=short -q 2>&1", timeout=120)
|
||||
output = result.get("output", "")
|
||||
|
||||
# Parse test output
|
||||
passed = output.count(" passed")
|
||||
failed = output.count(" failed")
|
||||
errors = output.count(" error")
|
||||
|
||||
report = {
|
||||
"passed": passed,
|
||||
"failed": failed,
|
||||
"errors": errors,
|
||||
"exit_code": result.get("exit_code", -1),
|
||||
"summary": output[-500:] if len(output) > 500 else output
|
||||
}
|
||||
|
||||
print(json.dumps(report, indent=2))
|
||||
```
|
||||
|
||||
## 执行模式
|
||||
|
||||
`execute_code` 有两种执行模式，通过 `~/.hermes/config.yaml` 中的 `code_execution.mode` 控制：
|
||||
|
||||
| 模式 | 工作目录 | Python 解释器 |
|
||||
|------|----------|---------------|
|
||||
| **`project`**（默认） | 会话的工作目录（与 `terminal()` 相同） | 活跃的 `VIRTUAL_ENV` / `CONDA_PREFIX` python，回退至 Hermes 自身的 python |
|
||||
| `strict` | 与用户项目隔离的临时暂存目录 | `sys.executable`（Hermes 自身的 python） |
|
||||
|
||||
**何时保持 `project` 模式：** 当你希望 `import pandas`、`from my_project import foo` 或 `open(".env")` 等相对路径与 `terminal()` 中的行为一致时。这几乎是你始终想要的模式。
|
||||
|
||||
**何时切换至 `strict` 模式：** 当你需要最大可复现性时——希望无论用户激活哪个 venv，每次会话都使用相同的解释器，并且希望脚本与项目目录隔离（避免通过相对路径意外读取项目文件）。
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
code_execution:
|
||||
mode: project # or "strict"
|
||||
```
|
||||
|
||||
`project` 模式的回退行为：若 `VIRTUAL_ENV` / `CONDA_PREFIX` 未设置、已损坏或指向低于 3.8 的 Python，解析器会干净地回退至 `sys.executable`——agent 始终有可用的解释器。
|
||||
|
||||
两种模式的安全关键不变量完全相同：
|
||||
|
||||
- 环境变量清理（API key、token、凭据默认被剥离）
|
||||
- 工具白名单（脚本不能递归调用 `execute_code`、`delegate_task` 或 MCP 工具）
|
||||
- 资源限制（超时、stdout 上限、工具调用上限）
|
||||
|
||||
切换模式只改变脚本的运行位置和使用的解释器，不改变脚本可见的凭据或可调用的工具。
|
||||
|
||||
## 资源限制
|
||||
|
||||
| 资源 | 限制 | 说明 |
|
||||
|------|------|------|
|
||||
| **超时** | 5 分钟（300 秒） | 脚本先收到 SIGTERM，5 秒宽限期后收到 SIGKILL |
|
||||
| **Stdout** | 50 KB | 输出截断并附加 `[output truncated at 50KB]` 提示 |
|
||||
| **Stderr** | 10 KB | 非零退出时包含在输出中，用于调试 |
|
||||
| **工具调用** | 每次执行 50 次 | 达到上限时返回错误 |
|
||||
|
||||
所有限制均可通过 `config.yaml` 配置：
|
||||
|
||||
```yaml
|
||||
# In ~/.hermes/config.yaml
|
||||
code_execution:
|
||||
mode: project # project (default) | strict
|
||||
timeout: 300 # Max seconds per script (default: 300)
|
||||
max_tool_calls: 50 # Max tool calls per execution (default: 50)
|
||||
```
|
||||
|
||||
## 脚本内工具调用的工作方式
|
||||
|
||||
当脚本调用 `web_search("query")` 等函数时：
|
||||
|
||||
1. 调用被序列化为 JSON，通过 Unix 域套接字发送至父进程
|
||||
2. 父进程通过标准 `handle_function_call` 处理器进行分发
|
||||
3. 结果通过套接字发回
|
||||
4. 函数返回解析后的结果
|
||||
|
||||
这意味着脚本内的工具调用与普通工具调用行为完全一致——相同的速率限制、相同的错误处理、相同的能力。唯一的限制是 `terminal()` 仅支持前台模式（不支持 `background` 或 `pty` 参数）。
|
||||
|
||||
## 错误处理
|
||||
|
||||
脚本失败时，agent 会收到结构化的错误信息：
|
||||
|
||||
- **非零退出码**：stderr 包含在输出中，agent 可看到完整的 traceback
|
||||
- **超时**：脚本被终止，agent 看到 `"Script timed out after 300s and was killed."`
|
||||
- **中断**：若用户在执行期间发送新消息，脚本被终止，agent 看到 `[execution interrupted — user sent a new message]`
|
||||
- **工具调用上限**：达到 50 次调用上限后，后续工具调用返回错误消息
|
||||
|
||||
响应始终包含 `status`（success/error/timeout/interrupted）、`output`、`tool_calls_made` 和 `duration_seconds`。
|
||||
|
||||
## 安全性
|
||||
|
||||
:::danger 安全模型
|
||||
子进程在**最小化环境**中运行。API key、token 和凭据默认被剥离。脚本只能通过 RPC 通道访问工具——除非显式允许，否则无法从环境变量中读取密钥。
|
||||
:::
|
||||
|
||||
名称中包含 `KEY`、`TOKEN`、`SECRET`、`PASSWORD`、`CREDENTIAL`、`PASSWD` 或 `AUTH` 的环境变量会被排除。只有安全的系统变量（`PATH`、`HOME`、`LANG`、`SHELL`、`PYTHONPATH`、`VIRTUAL_ENV` 等）会被传递。
|
||||
|
||||
### Skill 环境变量透传
|
||||
|
||||
当 skill 在其 frontmatter 中声明 `required_environment_variables` 时，这些变量会在 skill 加载后**自动透传**至 `execute_code` 和 `terminal` 子进程。这使 skill 可以使用其声明的 API key，而不会削弱任意代码的安全态势。
|
||||
|
||||
对于非 skill 场景，可在 `config.yaml` 中显式添加变量白名单：
|
||||
|
||||
```yaml
|
||||
terminal:
|
||||
env_passthrough:
|
||||
- MY_CUSTOM_KEY
|
||||
- ANOTHER_TOKEN
|
||||
```
|
||||
|
||||
详情参见[安全指南](/user-guide/security#environment-variable-passthrough)。
|
||||
|
||||
Hermes 始终将脚本和自动生成的 `hermes_tools.py` RPC 存根写入临时暂存目录，执行完成后清理。在 `strict` 模式下，脚本也在该目录中*运行*；在 `project` 模式下，脚本在会话的工作目录中运行（暂存目录保留在 `PYTHONPATH` 中以确保导入正常解析）。子进程在独立的进程组中运行，以便在超时或中断时干净地终止。
|
||||
|
||||
## execute_code 与 terminal 对比
|
||||
|
||||
| 使用场景 | execute_code | terminal |
|
||||
|----------|-------------|----------|
|
||||
| 调用之间含逻辑的多步骤工作流 | ✅ | ❌ |
|
||||
| 简单 shell 命令 | ❌ | ✅ |
|
||||
| 过滤/处理大量工具输出 | ✅ | ❌ |
|
||||
| 运行构建或测试套件 | ❌ | ✅ |
|
||||
| 对搜索结果进行循环处理 | ✅ | ❌ |
|
||||
| 交互式/后台进程 | ❌ | ✅ |
|
||||
| 需要环境变量中的 API key | ⚠️ 仅通过[透传](/user-guide/security#environment-variable-passthrough) | ✅（大多数可透传） |
|
||||
|
||||
**经验法则：** 需要在调用之间含逻辑地程序化调用 Hermes 工具时，使用 `execute_code`。运行 shell 命令、构建和进程时，使用 `terminal`。
|
||||
|
||||
## 平台支持
|
||||
|
||||
代码执行依赖 Unix 域套接字，仅在 **Linux 和 macOS** 上可用。在 Windows 上会自动禁用——agent 回退至常规的顺序工具调用。
|
||||
+441
@@ -0,0 +1,441 @@
|
||||
---
|
||||
title: Codex App-Server 运行时（可选）
|
||||
sidebar_label: Codex App-Server 运行时
|
||||
---
|
||||
|
||||
# Codex App-Server 运行时
|
||||
|
||||
Hermes 可以选择将 `openai/*` 和 `openai-codex/*` 的轮次交由 [Codex CLI app-server](https://github.com/openai/codex) 处理，而不是运行自己的工具循环。启用后，终端命令、文件编辑、沙箱隔离以及 MCP 工具调用均在 Codex 的运行时内执行——Hermes 成为其外层 shell（会话数据库、斜杠命令、gateway、记忆与技能审查）。
|
||||
|
||||
此功能**仅限手动启用**。除非你主动切换该标志，否则 Hermes 的默认行为不变。Hermes 不会自动将你路由到此运行时。
|
||||
|
||||
## 为什么使用
|
||||
|
||||
- 通过 Codex CLI 使用的相同认证流程，使用你的 **ChatGPT 订阅**运行 OpenAI agent 轮次（无需 API 密钥）。
|
||||
- 使用 **Codex 自带的工具集和沙箱**——`shell` 用于终端/读/写/搜索，`apply_patch` 用于结构化编辑，`update_plan` 用于规划，全部在 seatbelt/landlock 沙箱内运行。
|
||||
- **原生 Codex 插件**——Linear、GitHub、Gmail、Calendar、Canva 等——通过 `codex plugin` 安装后，会自动迁移并在你的 Hermes 会话中激活。
|
||||
- **Hermes 的丰富工具一并可用**——web_search、web_extract、浏览器自动化、视觉、图像生成、技能和 TTS 通过 MCP 回调提供。Codex 会回调 Hermes 获取其自身没有内置的工具。
|
||||
- **记忆与技能提示持续生效**——Codex 的事件被投影为 Hermes 的消息格式，使自我改进循环看到正常的对话记录。
|
||||
|
||||
## 模型实际拥有哪些工具
|
||||
|
||||
这是大多数用户最想提前了解的部分。当此运行时开启时，执行你的轮次的模型拥有三个独立的工具来源：
|
||||
|
||||
### 1. Codex 内置工具集（始终开启）
|
||||
|
||||
这些工具随 `codex app-server` 本身一起提供——无需 Hermes 介入，无需 MCP，无需插件。运行时启动后，以下五个工具立即可用：
|
||||
|
||||
- **`shell`** — 在沙箱内运行任意 shell 命令。模型通过此工具读取文件（`cat`、`head`、`tail`）、写入文件（`echo > foo`、heredoc）、搜索文件（`find`、`rg`、`grep`）、浏览目录（`ls`、`cd`）、运行构建、管理进程，以及其他任何你在 bash 中能做的事。
|
||||
- **`apply_patch`** — 以 Codex 的 patch 格式应用结构化的多文件差异。模型将此工具用于非简单的代码编辑（添加函数、跨文件重构）；单次写入仍可使用 shell heredoc。
|
||||
- **`update_plan`** — Codex 的内部待办/计划跟踪器。等同于 Hermes 的 `todo` 工具，但完全在 Codex 运行时内部管理。
|
||||
- **`view_image`** — 将本地图像文件加载到对话中，使模型能够查看它。
|
||||
- **`web_search`** — 配置后 Codex 拥有自己的内置网络搜索。Hermes 也通过下方的回调暴露 `web_search`（基于 Firecrawl）；模型会选择其偏好的那个。
|
||||
|
||||
因此，**任何你通过终端完成的操作——读/写/搜索/查找/运行——Codex 都能原生处理**。沙箱配置文件（启用运行时时默认为 `:workspace`）控制可写范围。
|
||||
|
||||
### 2. 原生 Codex 插件（从你的 `codex plugin` 安装中自动迁移）
|
||||
|
||||
启用运行时时，Hermes 会查询 Codex 的 `plugin/list` RPC，并为你已安装的每个插件写入一条 `[plugins."<name>@openai-curated"]` 配置项。插件本身由 Codex 管理，并通过 Codex 自己的 UI 完成一次性授权。
|
||||
|
||||
示例（OpenClaw 帖子中被称为"值得录制视频"的那些）：
|
||||
|
||||
- **Linear** — 查找/更新 issue
|
||||
- **GitHub** — 搜索代码、查看 PR、评论
|
||||
- **Gmail** — 读取/发送邮件
|
||||
- **Google Calendar** — 创建/查找日程
|
||||
- **Outlook 日历/邮件** — 通过 Microsoft 连接器提供相同功能
|
||||
- **Canva** — 设计生成
|
||||
- ……以及其他你通过 `codex plugin marketplace add openai-curated` + `codex plugin install ...` 安装的插件
|
||||
|
||||
**未迁移的内容：**
|
||||
- 你尚未安装的插件——请先在 Codex 中安装。
|
||||
- ChatGPT 应用市场条目（`app/list`）——这些已通过你的账户认证在 Codex 内部启用。
|
||||
|
||||
### 3. Hermes 工具回调（MCP server，注册在 `~/.codex/config.toml` 中）
|
||||
|
||||
Hermes 将自身注册为 MCP server，以便 Codex 能够回调获取 Codex 自身未内置的工具。通过回调可用的工具：
|
||||
|
||||
- **`web_search`** / **`web_extract`** — 基于 Firecrawl；对于结构化内容，通常比直接抓取更干净。
|
||||
- **`browser_navigate` / `browser_click` / `browser_type` / `browser_press` / `browser_snapshot` / `browser_scroll` / `browser_back` / `browser_get_images` / `browser_console` / `browser_vision`** — 通过 Camofox 或 Browserbase 实现完整的浏览器自动化。
|
||||
- **`vision_analyze`** — 调用独立的视觉模型检查图像（与 Codex 的 `view_image` 不同，后者是将图像加载到对话中）。
|
||||
- **`image_generate`** — 通过 Hermes 的 image_gen 插件链生成图像。
|
||||
- **`skill_view` / `skills_list`** — 读取 Hermes 的技能库。
|
||||
- **`text_to_speech`** — 通过 Hermes 配置的提供商进行 TTS。
|
||||
|
||||
当模型需要其中某个工具时，Codex 通过 stdio MCP 生成 `hermes_tools_mcp_server` 子进程，调用通过 `model_tools.handle_function_call()` 分发（与 Hermes 默认运行时的代码路径相同），结果像其他 MCP 响应一样返回给 Codex。
|
||||
|
||||
### 此运行时上不可用的工具
|
||||
|
||||
以下四个 Hermes 工具需要运行中的 AIAgent 上下文（循环中间状态）才能分发，无状态的 MCP 回调无法驱动它们。需要这些工具时，请切换回默认运行时（`/codex-runtime auto`）：
|
||||
|
||||
- **`delegate_task`** — 生成子 agent
|
||||
- **`memory`** — Hermes 的持久记忆存储
|
||||
- **`session_search`** — 跨会话搜索
|
||||
- **`todo`** — Hermes 的待办存储（Codex 的 `update_plan` 是运行时内的等效工具）
|
||||
|
||||
## 工作流功能（`/goal`、kanban、cron）
|
||||
|
||||
### `/goal`（Ralph 循环）
|
||||
|
||||
**在此运行时上可用。** 目标以会话 id 为键持久化在 `state_meta` 中，续接提示通过 `run_conversation()` 作为普通用户消息回传，Codex 原生执行下一轮次。目标判断器通过辅助客户端运行（在 config.yaml 中通过 `auxiliary.goal_judge` 配置），与当前活跃的运行时无关。判断器的"受阻，需要用户输入"裁决是 Codex 卡在审批时的干净退出路径。
|
||||
|
||||
**需要注意的一点：** 每个续接提示都是一次全新的 Codex 轮次，这意味着 Codex 会从头重新评估命令审批策略。如果你在执行包含大量写操作的长期目标，预期会看到比单次会话内任务更多的审批提示。设置 `default_permissions = ":workspace"`（启用运行时时 Hermes 会自动设置）可避免简单的工作区写操作触发提示。
|
||||
|
||||
### Kanban（多 agent 工作树分发）
|
||||
|
||||
**在此运行时上可用，但有一个细微依赖。** Kanban 分发器将每个 worker 生成为独立的 `hermes chat -q` 子进程，该子进程读取用户配置——这意味着如果全局设置了 `model.openai_runtime: codex_app_server`，worker 也会在 Codex 运行时上启动。
|
||||
|
||||
Codex 运行时 worker 内可用的功能：
|
||||
- Codex 完整工具集（shell、apply_patch、update_plan、view_image、web_search）——worker 原生完成实际任务
|
||||
- 已迁移的 Codex 插件——Linear、GitHub 等
|
||||
- 用于 browser_*、vision、image_gen、技能、TTS 的 Hermes 工具回调
|
||||
|
||||
通过 MCP 回调同样可用的功能：
|
||||
- **`kanban_complete` / `kanban_block` / `kanban_comment` / `kanban_heartbeat`** — worker 交接工具。这些工具从环境变量中读取 `HERMES_KANBAN_TASK`（由分发器设置），正确进行访问控制，并写入由 `HERMES_KANBAN_DB` 固定的每个看板 SQLite 数据库。若回调中没有这些工具，此运行时上的 worker 可以完成任务但无法汇报，会一直挂起直到分发器超时。
|
||||
- **`kanban_show` / `kanban_list`** — 只读看板查询，供 worker 检查自身上下文。
|
||||
- **`kanban_create` / `kanban_unblock` / `kanban_link`** — 仅限编排器的操作。供运行在 Codex 运行时上、需要分发新任务的编排器 agent 使用。
|
||||
|
||||
Kanban 工具通过分发器设置的 `HERMES_KANBAN_TASK` 环境变量进行访问控制——该变量会传播到 Codex 子进程（Codex 继承环境变量），再从那里传播到生成的 `hermes-tools` MCP server 子进程。因此工具能看到正确的任务 id 并正确进行访问控制。对于 Codex app-server worker，当 `HERMES_KANBAN_TASK` 存在时，Hermes 还会传入精细的 app-server 沙箱覆盖配置：保持 `workspace-write` 沙箱，将**看板数据库目录以及分发器固定的所有 Kanban 路径**作为额外可写根目录添加（`HERMES_KANBAN_WORKSPACES_ROOT`、`HERMES_KANBAN_WORKSPACE`、旧版 `HERMES_KANBAN_ROOT`——去重，数据库目录优先），并默认禁用网络。这避免了脆弱的 `:danger-no-sandbox` 变通方案，同时允许 `kanban_complete` / `kanban_block` 更新看板数据库，**并且**允许 worker 在数据库目录之外的工作区挂载点下写入报告/产物（例如独立驱动器上的 `/media/.../kanban-workspaces/...`——[issue #27941](https://github.com/NousResearch/hermes-agent/issues/27941)）。
|
||||
|
||||
### Cron 任务
|
||||
|
||||
**尚未经过专项测试。** Cron 任务通过 `cronjob` → `AIAgent.run_conversation` 运行，与 CLI 的代码路径相同。如果 cron 任务的配置中有 `openai_runtime: codex_app_server`，它将在 Codex 上运行。相同的工具可用性规则适用——Codex 内置工具 + 插件 + MCP 回调可用，agent 循环工具（delegate_task、memory、session_search、todo）不可用。如果你的 cron 任务依赖这些工具，请将 cron 限定在使用默认运行时的配置文件中。
|
||||
|
||||
## 权衡对比
|
||||
|
||||
| | Hermes 默认运行时 | Codex app-server（可选启用） |
|
||||
|---|---|---|
|
||||
| `delegate_task` 子 agent | 是 | 不可用——需要 agent 循环上下文 |
|
||||
| `memory`、`session_search`、`todo` | 是 | 不可用——需要 agent 循环上下文 |
|
||||
| `web_search`、`web_extract` | 是 | 是（通过 MCP 回调） |
|
||||
| 浏览器自动化（Camofox/Browserbase） | 是 | 是（通过 MCP 回调） |
|
||||
| `vision_analyze`、`image_generate` | 是 | 是（通过 MCP 回调） |
|
||||
| `skill_view`、`skills_list` | 是 | 是（通过 MCP 回调） |
|
||||
| `text_to_speech` | 是 | 是（通过 MCP 回调） |
|
||||
| Codex `shell`（终端/读/写/搜索/查找/运行） | — | 是（Codex 内置） |
|
||||
| Codex `apply_patch`（结构化多文件编辑） | — | 是（Codex 内置） |
|
||||
| Codex `update_plan`（运行时内待办） | — | 是（Codex 内置） |
|
||||
| Codex `view_image`（将图像加载到对话） | — | 是（Codex 内置） |
|
||||
| Codex 沙箱（seatbelt/landlock，配置文件） | — | 是（Codex 内置） |
|
||||
| ChatGPT 订阅认证 | — | 是（通过 `openai-codex` 提供商） |
|
||||
| 原生 Codex 插件（Linear、GitHub 等） | — | 是（自动迁移） |
|
||||
| 用户 MCP server | 是 | 是（自动迁移到 Codex） |
|
||||
| 记忆 + 技能审查（后台） | 是 | 是（通过事件投影） |
|
||||
| 多轮对话 | 是 | 是 |
|
||||
| `/goal`（Ralph 循环） | 是 | 是 |
|
||||
| Kanban worker 分发 | 是 | 是（通过回调） |
|
||||
| Kanban 编排器工具 | 是 | 是（通过回调） |
|
||||
| 所有 gateway 平台 | 是 | 是 |
|
||||
| 非 OpenAI 提供商 | 是 | 不适用——仅限 OpenAI/Codex |
|
||||
|
||||
## 前提条件
|
||||
|
||||
1. **已安装 Codex CLI：**
|
||||
```bash
|
||||
npm i -g @openai/codex
|
||||
codex --version # 0.130.0 或更新版本
|
||||
```
|
||||
2. **Codex OAuth 登录。** Codex 子进程读取 `~/.codex/auth.json`。有两种方式填充它：
|
||||
```bash
|
||||
codex login # 将 token 写入 ~/.codex/auth.json
|
||||
```
|
||||
Hermes 自己的 `hermes auth login codex` 写入 `~/.hermes/auth.json`——那是独立的会话。**如果你还没有运行过 `codex login`，请单独运行它。**
|
||||
|
||||
3. **（可选）安装你想要的 Codex 插件。** 启用运行时时，Hermes 会自动迁移你已通过 Codex CLI 安装的所有精选插件：
|
||||
```bash
|
||||
codex plugin marketplace add openai-curated
|
||||
# 然后通过 Codex 的 TUI 安装 Linear / GitHub / Gmail 等
|
||||
```
|
||||
Hermes 会自动发现它们并将 `[plugins."<name>@openai-curated"]` 条目写入 `~/.codex/config.toml`。
|
||||
|
||||
## 启用
|
||||
|
||||
在 Hermes 会话中：
|
||||
|
||||
```
|
||||
/codex-runtime codex_app_server
|
||||
```
|
||||
|
||||
该命令会：
|
||||
- 验证 `codex` CLI 是否已安装（若未安装则阻止并提示安装方法）。
|
||||
- 将 `model.openai_runtime: codex_app_server` 持久化到你的 config.yaml。
|
||||
- 将用户 MCP server 从 `~/.hermes/config.yaml` 迁移到 `~/.codex/config.toml`。
|
||||
- **发现并迁移已安装的原生 Codex 插件**（Linear、GitHub、Gmail、Calendar、Canva 等），通过查询 Codex 的 `plugin/list` RPC 实现。
|
||||
- **将 Hermes 自身的工具注册为 MCP server**，以便 Codex 子进程能够回调获取 Codex 未内置的工具。
|
||||
- **写入 `default_permissions = ":workspace"`**，使沙箱允许在工作区内写入，无需对每次操作进行提示。
|
||||
- 告知你迁移了哪些内容。在**下一个**会话生效——当前缓存的 agent 保持之前的运行时，以保持 prompt 缓存有效。
|
||||
|
||||
同义命令：`/codex-runtime on`、`/codex-runtime off`、`/codex-runtime auto`。
|
||||
|
||||
查看当前状态而不做任何更改：
|
||||
```
|
||||
/codex-runtime
|
||||
```
|
||||
|
||||
你也可以在 `~/.hermes/config.yaml` 中手动设置：
|
||||
```yaml
|
||||
model:
|
||||
openai_runtime: codex_app_server # 默认值为 "auto"（= Hermes 运行时）
|
||||
```
|
||||
|
||||
## 自我改进循环（记忆 + 技能提示）
|
||||
|
||||
Hermes 的后台自我改进在计数器达到阈值时触发：
|
||||
|
||||
- 每 10 个用户 prompt（提示词）→ 一个分叉的审查 agent 查看对话，决定是否有内容应保存到记忆中。
|
||||
- 单次轮次内每 10 次工具迭代 → 同样的逻辑，但针对技能（`skill_manage` 写入）。
|
||||
|
||||
**两者在 Codex 运行时上均持续生效。** Codex 路径将每个已完成的 `commandExecution` / `fileChange` / `mcpToolCall` / `dynamicToolCall` 事件项投影为合成的 `assistant tool_call` + `tool` 结果消息，因此审查运行时看到的格式与在默认 Hermes 运行时上看到的相同。
|
||||
|
||||
连接方式保持等效：
|
||||
|
||||
| | 默认运行时 | Codex 运行时 |
|
||||
|---|---|---|
|
||||
| `_turns_since_memory` 递增 | 每个用户 prompt，在 run_conversation 预循环中 | 相同代码路径，在提前返回之前 |
|
||||
| `_iters_since_skill` 递增 | 在聊天补全循环的每次工具迭代中 | 通过 Codex 轮次返回后的 `turn.tool_iterations` |
|
||||
| 记忆触发（`_turns_since_memory >= _memory_nudge_interval`） | 在预循环中计算，响应后触发 | 在预循环中计算，传递给 Codex 辅助函数 |
|
||||
| 技能触发（`_iters_since_skill >= _skill_nudge_interval`） | 在循环结束后计算 | 在 Codex 轮次结束后计算 |
|
||||
| `_spawn_background_review(messages_snapshot=..., review_memory=..., review_skills=...)` | 任一触发器触发时调用 | 任一触发器触发时以相同方式调用 |
|
||||
|
||||
一个细节：审查分叉本身需要调用 Hermes 的 agent 循环工具（`memory`、`skill_manage`），这需要 Hermes 自身的分发。因此，当父 agent 处于 `codex_app_server` 时，审查分叉会**降级为 `codex_responses`**——相同的 OAuth 凭据，相同的 `openai-codex` 提供商，但直接与 OpenAI 的 Responses API 通信，使 Hermes 拥有循环控制权，agent 循环工具得以正常工作。这对用户不可见。
|
||||
|
||||
最终效果：启用 Codex 运行时后，你的记忆 + 技能提示计数器与之前完全一样持续触发。
|
||||
|
||||
## 审批流程
|
||||
|
||||
Codex 在执行命令或应用 patch 之前会请求审批。这些请求会被转换为 Hermes 标准的"危险命令"提示：
|
||||
|
||||
```
|
||||
╭───────────────────────────────────────╮
|
||||
│ Dangerous Command │
|
||||
│ │
|
||||
│ /bin/bash -lc 'echo hello > foo.txt' │
|
||||
│ │
|
||||
│ ❯ 1. Allow once │
|
||||
│ 2. Allow for this session │
|
||||
│ 3. Deny │
|
||||
│ │
|
||||
│ Codex requests exec in /your/cwd │
|
||||
╰───────────────────────────────────────╯
|
||||
```
|
||||
|
||||
- **Allow once** → 批准此单次命令。
|
||||
- **Allow for this session** → Codex 不会再对类似命令重复提示。
|
||||
- **Deny** → 命令被拒绝；Codex 以只读模式继续运行。
|
||||
|
||||
对于 `apply_patch`（文件编辑）审批，当 Codex 通过对应的 `fileChange` 事件项提供数据时，Hermes 会显示变更摘要（`1 add, 1 update: /tmp/new.py, /tmp/old.py`）。
|
||||
|
||||
## 权限配置文件
|
||||
|
||||
Codex 有三个内置权限配置文件：
|
||||
- `:read-only` — 禁止写入；每条 shell 命令都需要审批
|
||||
- `:workspace` — 允许在当前工作区内写入而无需提示（启用运行时时 Hermes 的默认值）
|
||||
- `:danger-no-sandbox` — 完全不使用沙箱（除非你清楚其含义，否则不要使用）
|
||||
|
||||
你可以在 Hermes 管理块之外的 `~/.codex/config.toml` 中覆盖默认值：
|
||||
|
||||
```toml
|
||||
default_permissions = ":read-only"
|
||||
```
|
||||
|
||||
（只要你的覆盖配置位于 `# managed by hermes-agent` 标记之外，Hermes 在重新迁移时会保留它。）
|
||||
|
||||
## 辅助任务与 ChatGPT 订阅 token 消耗
|
||||
|
||||
当此运行时与 `openai-codex` 提供商一起开启时，**辅助任务（标题生成、上下文压缩、视觉自动检测、后台自我改进审查分叉）默认也会通过你的 ChatGPT 订阅流转**，因为 Hermes 的辅助客户端在没有设置每任务覆盖时使用主提供商/模型。
|
||||
|
||||
这并非 `codex_app_server` 特有——现有的 `codex_responses` 路径也是如此——但在这里更为明显，因为你是在明确选择订阅计费。
|
||||
|
||||
要将特定辅助任务路由到更便宜/不同的模型，请在 `~/.hermes/config.yaml` 中设置显式覆盖：
|
||||
|
||||
```yaml
|
||||
auxiliary:
|
||||
title_generation:
|
||||
provider: openrouter
|
||||
model: google/gemini-3-flash-preview
|
||||
compression:
|
||||
provider: openrouter
|
||||
model: google/gemini-3-flash-preview
|
||||
vision:
|
||||
provider: openrouter
|
||||
model: google/gemini-3-flash-preview
|
||||
goal_judge:
|
||||
provider: openrouter
|
||||
model: google/gemini-3-flash-preview
|
||||
```
|
||||
|
||||
自我改进审查分叉通过 `_current_main_runtime()` 继承主运行时，Hermes 会自动将其从 `codex_app_server` 降级为 `codex_responses`（以便分叉能够实际调用 `memory` 和 `skill_manage`——Hermes 自身的 agent 循环工具）。除非你已将辅助任务路由到其他地方，否则该分叉仍使用你的订阅认证。
|
||||
|
||||
## 安全编辑 `~/.codex/config.toml`
|
||||
|
||||
Hermes 将其管理的所有内容包裹在两个标记注释之间：
|
||||
|
||||
```toml
|
||||
# managed by hermes-agent — `hermes codex-runtime migrate` regenerates this section
|
||||
default_permissions = ":workspace"
|
||||
[mcp_servers.filesystem]
|
||||
...
|
||||
[plugins."github@openai-curated"]
|
||||
...
|
||||
# end hermes-agent managed section
|
||||
```
|
||||
|
||||
该块**之外**的内容归你所有。重新运行迁移（通过 `/codex-runtime codex_app_server` 或每次切换运行时时）会原地替换管理块，但完整保留其上下方的用户内容。这意味着你可以：
|
||||
|
||||
- 添加 Hermes 不知道的自定义 MCP server
|
||||
- 将 `default_permissions` 覆盖为 `:read-only`（如果你希望被提示）
|
||||
- 配置仅 Codex 使用的选项（model、providers、otel 等）
|
||||
- 在 `[permissions.<name>]` 表中添加用户自定义权限配置文件
|
||||
|
||||
你在管理块**内部**添加的任何内容都会在下次迁移时被覆盖。如果你需要修改管理块中的某项配置，请提交 issue，我们会添加相应的开关。
|
||||
|
||||
## 多配置文件 / 多租户设置
|
||||
|
||||
默认情况下，无论哪个 Hermes 配置文件处于活跃状态，Hermes 都将 Codex 子进程指向 `~/.codex/`。这意味着 `hermes -p work` 和 `hermes -p personal` 共享相同的 Codex 认证、插件和配置。对大多数用户来说这是正确的行为——与直接运行 `codex` CLI 的效果一致。
|
||||
|
||||
如果你需要按配置文件隔离 Codex（独立的认证、独立的已安装插件、独立的配置），请为每个配置文件显式设置 `CODEX_HOME`。最简洁的方式是指向你 `HERMES_HOME` 下的某个目录：
|
||||
|
||||
```bash
|
||||
# 在 work 配置文件中，你可以这样包装 hermes：
|
||||
CODEX_HOME=~/.hermes/profiles/work/codex hermes chat
|
||||
```
|
||||
|
||||
你需要在设置了该 `CODEX_HOME` 的情况下重新运行一次 `codex login`，以便 OAuth token 落入配置文件范围的位置。之后，`hermes -p work` 将在隔离的 Codex 状态下运行。
|
||||
|
||||
我们不自动限定此范围，因为移动现有用户的 `~/.codex/` 会静默地使其 Codex CLI 认证失效——任何已运行过 `codex login` 的用户都需要重新认证。选择加入比给用户带来意外更安全。
|
||||
|
||||
## HOME 环境变量透传
|
||||
|
||||
Hermes 在生成 Codex app-server 子进程时**不会**重写 `HOME`（我们使用 `os.environ.copy()`，仅覆盖 `CODEX_HOME` 和 `RUST_LOG`）。这意味着：
|
||||
|
||||
- Codex 通过其 `shell` 工具运行的命令能看到真实的用户 `HOME`，并能正确找到 `~/.gitconfig`、`~/.gh/`、`~/.aws/`、`~/.npmrc` 等。
|
||||
- Codex 的内部状态通过 `CODEX_HOME` 保持隔离（默认指向 `~/.codex/`）。
|
||||
|
||||
这与 OpenClaw 在早期实验后得出的边界一致：隔离 Codex 的状态，保持用户主目录不变。（参见 openclaw/openclaw#81562。）
|
||||
|
||||
## MCP server 迁移
|
||||
|
||||
Hermes 的 `mcp_servers` 配置会自动转换为 Codex 所需的 TOML 格式。迁移在每次启用运行时时运行，且是幂等的——重新运行会替换管理块，但保留用户编辑的 Codex 配置。
|
||||
|
||||
转换内容：
|
||||
|
||||
| Hermes（`config.yaml`） | Codex（`config.toml`） |
|
||||
|---|---|
|
||||
| `command` + `args` + `env` | stdio transport |
|
||||
| `url` + `headers` | streamable_http transport |
|
||||
| `timeout` | `tool_timeout_sec` |
|
||||
| `connect_timeout` | `startup_timeout_sec` |
|
||||
| `enabled: false` | `enabled = false` |
|
||||
|
||||
未迁移的内容：
|
||||
- Hermes 特有的键，如 `sampling`（Codex 的 MCP 客户端没有等效项——这些会被丢弃并附带每个 server 的警告）。
|
||||
|
||||
## 原生 Codex 插件迁移
|
||||
|
||||
通过 `codex plugin` 安装的插件（Linear、GitHub、Gmail、Calendar、Canva 等）通过 Codex 的 `plugin/list` RPC 被发现。对于每个 `installed: true` 的插件，Hermes 会写入一个 `[plugins."<name>@openai-curated"]` 块，在你的 Hermes 会话中启用它。
|
||||
|
||||
这意味着：当你的朋友说"我在 Codex CLI 中设置了 Calendar 和 GitHub"，他们启用 Hermes 的 Codex 运行时后，Hermes 会自动激活这些插件。无需重新配置。
|
||||
|
||||
**未迁移的内容：**
|
||||
- 你尚未安装的插件——请先在 Codex 中安装。
|
||||
- Codex 报告 `availability != AVAILABLE` 的插件（安装损坏、OAuth 过期、已从市场下架等）。这些会被跳过，以避免写入激活时会失败的配置。
|
||||
- ChatGPT 应用市场条目（每账户的 `app/list` 结果——这些已通过你的账户认证在 Codex 内部启用）。
|
||||
- 插件 OAuth——你在 Codex 本身中对每个插件授权一次；Hermes 不接触凭据。
|
||||
|
||||
## Hermes 工具回调（新 MCP server）
|
||||
|
||||
Codex 的内置工具集涵盖 shell/文件操作/patch，但没有网络搜索、浏览器自动化、视觉、图像生成等功能。为了在 Codex 轮次中保持这些工具可用，Hermes 在 `~/.codex/config.toml` 中将自身注册为 MCP server：
|
||||
|
||||
```toml
|
||||
[mcp_servers.hermes-tools]
|
||||
command = "/path/to/python"
|
||||
args = ["-m", "agent.transports.hermes_tools_mcp_server"]
|
||||
env = { HERMES_HOME = "/your/.hermes", PYTHONPATH = "...", HERMES_QUIET = "1" }
|
||||
startup_timeout_sec = 30.0
|
||||
tool_timeout_sec = 600.0
|
||||
```
|
||||
|
||||
当模型调用 `web_search`（或其他暴露的 Hermes 工具）时，Codex 通过 stdio 生成 `hermes_tools_mcp_server` 子进程，请求通过 `model_tools.handle_function_call()` 分发，结果像其他 MCP 响应一样投影回 Codex。
|
||||
|
||||
**通过回调可用的工具：** `web_search`、`web_extract`、`browser_navigate`、`browser_click`、`browser_type`、`browser_press`、`browser_snapshot`、`browser_scroll`、`browser_back`、`browser_get_images`、`browser_console`、`browser_vision`、`vision_analyze`、`image_generate`、`skill_view`、`skills_list`、`text_to_speech`。
|
||||
|
||||
**不可用的工具：** `delegate_task`、`memory`、`session_search`、`todo`。这些工具需要运行中的 AIAgent 上下文（循环中间状态）才能分发，无状态的 MCP 回调无法驱动它们。需要这些工具时，请使用默认 Hermes 运行时（`/codex-runtime auto`）。
|
||||
|
||||
## 禁用
|
||||
|
||||
随时切换回来：
|
||||
|
||||
```
|
||||
/codex-runtime auto
|
||||
```
|
||||
|
||||
在下一个会话生效。Codex 管理块保留在 `~/.codex/config.toml` 中，以便你之后重新启用时不会丢失配置——如果你希望，也可以手动删除它。
|
||||
|
||||
## 限制
|
||||
|
||||
此运行时为**可选启用的 beta 功能**。以下功能在 Hermes Agent 2026.5 + Codex CLI 0.130.0 上已验证可用：
|
||||
|
||||
- 多轮对话
|
||||
- 通过 Hermes UI 进行 `commandExecution` 和 `fileChange`（apply_patch）审批
|
||||
- MCP 工具调用（已针对 `@modelcontextprotocol/server-filesystem` 和新的 `hermes-tools` 回调验证）
|
||||
- 原生 Codex 插件迁移（已针对 Linear / GitHub / Calendar 清单验证）
|
||||
- 拒绝/取消路径
|
||||
- 开关切换循环
|
||||
- 记忆和技能提示计数器（已通过集成测试实时验证）
|
||||
- 通过 Codex 使用 Hermes web_search（已实时验证："OpenAI Codex CLI – Getting Started" 端到端返回结果）
|
||||
|
||||
已知限制：
|
||||
|
||||
- **Hermes 认证和 Codex 认证是独立的会话。** 为获得最佳体验，你需要同时运行 `codex login` 和 `hermes auth login codex`（运行时使用 Codex 的会话进行 LLM 调用）。这是 Hermes `_import_codex_cli_tokens` 中的有意设计——Hermes 不会与 Codex CLI 共享 OAuth 状态，以避免在 token 刷新时相互覆盖。
|
||||
- **`delegate_task`、`memory`、`session_search`、`todo` 在此运行时上不可用。** 它们需要运行中的 AIAgent 上下文，无状态的 MCP 回调无法提供。需要这些工具时，请使用 `/codex-runtime auto`。
|
||||
- **当 Codex 未跟踪变更集时，审批提示中没有内联 patch 预览。** Codex 的 `fileChange` 审批参数并不总是携带变更集。Hermes 会尽可能从对应的 `item/started` 通知中缓存数据，但如果审批在事件项流式传输完成之前到达，提示会回退到 Codex 提供的 `reason`。
|
||||
- **亚秒级取消无法保证。** 流式传输中途的中断（Codex 响应时按 Ctrl+C）通过 `turn/interrupt` 发送，但如果 Codex 已经刷新了最终消息，你仍会收到该响应。
|
||||
|
||||
如果你发现 bug，请[提交 issue](https://github.com/NousResearch/hermes-agent/issues)，附上 `hermes logs --since 5m` 的输出。在标题中注明 `codex-runtime` 以便于分类处理。
|
||||
|
||||
## 架构
|
||||
|
||||
```
|
||||
┌─── Hermes shell (CLI / TUI / gateway) ───┐
|
||||
│ sessions DB · slash commands · memory │
|
||||
│ & skill review · cron · session pickers │
|
||||
└──┬──────────────────────────────────────┬┘
|
||||
│ user_message final │
|
||||
▼ text + │
|
||||
┌──────────────────────────────────┐ projected │
|
||||
│ AIAgent.run_conversation() │ messages │
|
||||
│ if api_mode == codex_app_server │ │
|
||||
│ → CodexAppServerSession │ │
|
||||
│ else: chat_completions / codex_responses (default)
|
||||
└────┬─────────────────────────────┘ │
|
||||
│ JSON-RPC over stdio │
|
||||
▼ │
|
||||
┌──────────────────────────────────┐ │
|
||||
│ codex app-server (subprocess) │──────────────┘
|
||||
│ thread/start, turn/start │
|
||||
│ item/* notifications │
|
||||
│ shell + apply_patch + update_plan│
|
||||
│ view_image + sandbox │
|
||||
│ ┌─────────────────────────┐ │
|
||||
│ │ MCP client │ │
|
||||
│ │ ├─ user MCP servers │ │
|
||||
│ │ ├─ native plugins │ │
|
||||
│ │ │ (linear, github, │ │
|
||||
│ │ │ gmail, calendar, │ │
|
||||
│ │ │ canva, ...) │ │
|
||||
│ │ └─ hermes-tools ───────┼─────────────────┐
|
||||
│ │ (callback to │ │ │
|
||||
│ │ Hermes' richer │ │ │
|
||||
│ │ tools) │ │ │
|
||||
│ └─────────────────────────┘ │ │
|
||||
└──────────────────────────────────┘ │
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ hermes_tools_mcp_server.py (subprocess on demand) │
|
||||
│ web_search, web_extract, browser_*, vision_analyze, │
|
||||
│ image_generate, skill_view, skills_list, text_to_speech│
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
有关实现细节，请参阅 [PR #24182](https://github.com/NousResearch/hermes-agent/pull/24182) 和 [Codex app-server 协议 README](https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md)。
|
||||
+145
@@ -0,0 +1,145 @@
|
||||
---
|
||||
title: 电脑操控
|
||||
sidebar_position: 16
|
||||
---
|
||||
|
||||
# 电脑操控（macOS）
|
||||
|
||||
Hermes Agent 可以在**后台**驱动你的 Mac 桌面——点击、输入、滚动、拖拽。你的光标不会移动，键盘焦点不会改变，macOS 也不会切换 Spaces。你和 Agent 可以在同一台机器上协同工作。
|
||||
|
||||
与大多数电脑操控集成不同，这适用于**任何支持工具调用的模型**——Claude、GPT、Gemini，或本地 vLLM 端点上的开源模型。无需关心 Anthropic 原生 schema。
|
||||
|
||||
## 工作原理
|
||||
|
||||
`computer_use` 工具集通过 stdio 以 MCP 协议与 [`cua-driver`](https://github.com/trycua/cua) 通信。`cua-driver` 是一个 macOS 驱动，使用 SkyLight 私有 SPI（`SLEventPostToPid`、`SLPSPostEventRecordTo`）以及 `_AXObserverAddNotificationAndCheckRemote` 无障碍 SPI，实现以下功能：
|
||||
|
||||
- 直接向目标进程投递合成事件——无需 HID 事件 tap，无需光标跳转。
|
||||
- 在不提升窗口的情况下切换 AppKit 激活状态——不触发 Space 切换。
|
||||
- 在窗口被遮挡时保持 Chromium/Electron 无障碍树存活。
|
||||
|
||||
这一组合正是 OpenAI Codex「后台电脑操控」所采用的方案。cua-driver 是其开源等价实现。
|
||||
|
||||
## 启用
|
||||
|
||||
选择最方便的方式——两种方式运行的是同一个上游安装程序：
|
||||
|
||||
**方式一：使用专用 CLI 命令（最直接）。**
|
||||
|
||||
```
|
||||
hermes computer-use install
|
||||
```
|
||||
|
||||
此命令会获取并运行上游 cua-driver 安装脚本：
|
||||
`curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh`。
|
||||
使用 `hermes computer-use status` 验证安装结果。
|
||||
|
||||
**方式二：通过交互式界面启用工具集。**
|
||||
|
||||
1. 运行 `hermes tools`，选择 `🖱️ Computer Use (macOS)` → `cua-driver (background)`。
|
||||
2. 安装程序将运行上游安装脚本（与方式一相同）。
|
||||
|
||||
安装完成后，无论采用哪种方式，继续执行以下步骤：
|
||||
|
||||
3. 在提示时授予 macOS 权限：
|
||||
- **系统设置 → 隐私与安全性 → 辅助功能** → 允许终端（或 Hermes 应用）。
|
||||
- **系统设置 → 隐私与安全性 → 屏幕录制** → 允许同一应用。
|
||||
4. 启动启用了该工具集的会话：
|
||||
```
|
||||
hermes -t computer_use chat
|
||||
```
|
||||
或在 `~/.hermes/config.yaml` 中将 `computer_use` 添加到已启用的工具集列表。
|
||||
|
||||
## 保持 cua-driver 最新
|
||||
|
||||
cua-driver 项目会定期发布修复（例如 v0.1.6 修复了 UTM 工作流中的 Safari 窗口焦点问题）。Hermes 在两处刷新二进制文件，避免你停留在过时版本：
|
||||
|
||||
- **`hermes update`** — 更新 Hermes 本身时，如果 `cua-driver` 在 PATH 中，更新结束时会重新运行上游安装程序。对非 macOS 用户及未安装 cua-driver 的用户无操作。
|
||||
- **`hermes computer-use install --upgrade`** — 手动强制刷新。无论 cua-driver 是否已安装，都会重新运行上游安装程序。在不等待下次 Agent 更新的情况下获取最新修复时使用此命令。
|
||||
|
||||
`hermes computer-use status` 会在二进制路径旁显示已安装的版本号。
|
||||
|
||||
## 快速示例
|
||||
|
||||
用户 prompt（提示词）：*「找到我最近一封来自 Stripe 的邮件，总结他们希望我做什么。」*
|
||||
|
||||
Agent 的执行计划：
|
||||
|
||||
1. `computer_use(action="capture", mode="som", app="Mail")` — 获取 Mail 的截图，其中每个侧边栏项目、工具栏按钮和邮件行均已编号。
|
||||
2. `computer_use(action="click", element=14)` — 点击搜索框（来自截图的第 #14 号元素）。
|
||||
3. `computer_use(action="type", text="from:stripe")`
|
||||
4. `computer_use(action="key", keys="return", capture_after=True)` — 提交并获取新截图。
|
||||
5. 点击最顶部的结果，读取正文，进行总结。
|
||||
|
||||
整个过程中，你的光标保持原位，Mail 窗口始终不会切换到前台。
|
||||
|
||||
## 提供商兼容性
|
||||
|
||||
| 提供商 | 支持视觉？ | 可用？ | 备注 |
|
||||
|---|---|---|---|
|
||||
| Anthropic（Claude Sonnet/Opus 3+） | ✅ | ✅ | 综合表现最佳；支持 SOM 与原始坐标。 |
|
||||
| OpenRouter（任意视觉模型） | ✅ | ✅ | 支持多部分工具消息。 |
|
||||
| OpenAI（GPT-4+、GPT-5） | ✅ | ✅ | 同上。 |
|
||||
| 本地 vLLM / LM Studio（视觉模型） | ✅ | ✅ | 需模型支持多部分工具内容。 |
|
||||
| 纯文本模型 | ❌ | ✅（降级） | 使用 `mode="ax"` 仅通过无障碍树操作。 |
|
||||
|
||||
截图以 OpenAI 风格的 `image_url` 部分内联在工具结果中发送。对于 Anthropic，适配器会将其转换为原生 `tool_result` 图像块。
|
||||
|
||||
## 安全性
|
||||
|
||||
Hermes 应用多层防护机制：
|
||||
|
||||
- 破坏性操作（click、type、drag、scroll、key、focus_app）需要审批——通过 CLI 对话框交互确认，或通过消息平台审批按钮确认。
|
||||
- 工具层面硬性屏蔽的按键组合：清空废纸篓、强制删除、锁定屏幕、注销、强制注销。
|
||||
- 硬性屏蔽的输入模式：`curl | bash`、`sudo rm -rf /`、fork bomb 等。
|
||||
- Agent 的系统 prompt 明确规定：不得点击权限对话框，不得输入密码，不得执行截图中嵌入的指令。
|
||||
|
||||
如需对每个操作进行确认，可在 `~/.hermes/config.yaml` 中配置 `approvals.mode: manual`。
|
||||
|
||||
## Token 效率
|
||||
|
||||
截图开销较大。Hermes 应用四层优化措施：
|
||||
|
||||
- **截图淘汰** — Anthropic 适配器在上下文中仅保留最近 3 张截图；较旧的截图替换为 `[screenshot removed to save context]` 占位符。
|
||||
- **客户端压缩裁剪** — 上下文压缩器检测多模态工具结果，并从旧结果中剥离图像部分。
|
||||
- **图像感知 token 估算** — 每张图像计为约 1500 个 token（Anthropic 的固定费率），而非其 base64 字符长度。
|
||||
- **服务端上下文编辑（仅限 Anthropic）** — 激活后，适配器通过 `context_management` 启用 `clear_tool_uses_20250919`，由 Anthropic API 在服务端清除旧工具结果。
|
||||
|
||||
在 1568×900 分辨率下执行 20 个操作的会话，截图上下文通常消耗约 3 万个 token，而非约 60 万个。
|
||||
|
||||
## 限制
|
||||
|
||||
- **仅限 macOS。** cua-driver 使用的私有 Apple SPI 在 Linux 或 Windows 上不存在。跨平台 GUI 自动化请使用 `browser` 工具集。
|
||||
- **私有 SPI 风险。** Apple 可能在任何 OS 更新中更改 SkyLight 的符号接口。如需在 macOS 版本升级时保持可复现性，请通过 `HERMES_CUA_DRIVER_VERSION` 环境变量固定驱动版本。
|
||||
- **性能。** 后台模式比前台模式慢——SkyLight 路由事件耗时约 5–20ms，而直接 HID 投递更快。对于 Agent 速度的点击操作无明显影响；若尝试录制速通视频则会有感知。
|
||||
- **不支持键盘输入密码。** `type` 对命令行 payload 有硬性屏蔽模式；密码请使用系统自动填充功能。
|
||||
|
||||
## 配置
|
||||
|
||||
覆盖驱动二进制路径（用于测试 / CI）：
|
||||
|
||||
```
|
||||
HERMES_CUA_DRIVER_CMD=/opt/homebrew/bin/cua-driver
|
||||
HERMES_CUA_DRIVER_VERSION=0.5.0 # optional pin
|
||||
```
|
||||
|
||||
完全替换后端（用于测试）：
|
||||
|
||||
```
|
||||
HERMES_COMPUTER_USE_BACKEND=noop # records calls, no side effects
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
**`computer_use backend unavailable: cua-driver is not installed`** — 运行 `hermes computer-use install` 获取 cua-driver 二进制文件，或运行 `hermes tools` 并启用 Computer Use 工具集。
|
||||
|
||||
**点击似乎没有效果** — 截图并验证。可能有一个你未注意到的模态框正在阻止输入。使用 `escape` 或关闭按钮将其关闭。
|
||||
|
||||
**元素索引已过期** — SOM 索引仅在下次 `capture` 之前有效。任何改变状态的操作后请重新截图。
|
||||
|
||||
**「blocked pattern in type text」** — 你尝试 `type` 的文本匹配了危险 shell 模式列表。请拆分命令或重新考虑操作方式。
|
||||
|
||||
## 另请参阅
|
||||
|
||||
- [通用技能：`macos-computer-use`](https://github.com/NousResearch/hermes-agent/blob/main/skills/apple/macos-computer-use/SKILL.md)
|
||||
- [cua-driver 源码（trycua/cua）](https://github.com/trycua/cua)
|
||||
- 跨平台 Web 任务请参阅[浏览器自动化](./browser.md)。
|
||||
+218
@@ -0,0 +1,218 @@
|
||||
---
|
||||
sidebar_position: 8
|
||||
title: "上下文文件"
|
||||
description: "项目上下文文件 — .hermes.md、AGENTS.md、CLAUDE.md、全局 SOUL.md 以及 .cursorrules — 自动注入每次对话"
|
||||
---
|
||||
|
||||
# 上下文文件
|
||||
|
||||
Hermes Agent 会自动发现并加载上下文文件，以塑造其行为方式。部分文件属于项目本地文件，从工作目录中发现。`SOUL.md` 现在对整个 Hermes 实例全局生效，仅从 `HERMES_HOME` 加载。
|
||||
|
||||
## 支持的上下文文件
|
||||
|
||||
| 文件 | 用途 | 发现方式 |
|
||||
|------|---------|-----------|
|
||||
| **.hermes.md** / **HERMES.md** | 项目指令（最高优先级） | 向上遍历至 git 根目录 |
|
||||
| **AGENTS.md** | 项目指令、规范、架构说明 | 启动时的 CWD 及子目录（渐进式） |
|
||||
| **CLAUDE.md** | Claude Code 上下文文件（同样支持检测） | 启动时的 CWD 及子目录（渐进式） |
|
||||
| **SOUL.md** | 当前 Hermes 实例的全局个性与语气定制 | 仅 `HERMES_HOME/SOUL.md` |
|
||||
| **.cursorrules** | Cursor IDE 编码规范 | 仅 CWD |
|
||||
| **.cursor/rules/*.mdc** | Cursor IDE 规则模块 | 仅 CWD |
|
||||
|
||||
:::info 优先级系统
|
||||
每次会话仅加载**一种**项目上下文类型（先匹配先生效）：`.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`。**SOUL.md** 始终作为 agent 身份独立加载（插槽 #1）。
|
||||
:::
|
||||
|
||||
## AGENTS.md
|
||||
|
||||
`AGENTS.md` 是主要的项目上下文文件。它告知 agent 项目的结构、需要遵循的规范以及任何特殊指令。
|
||||
|
||||
### 渐进式子目录发现
|
||||
|
||||
会话启动时，Hermes 将工作目录中的 `AGENTS.md` 加载到系统 prompt（提示词）中。在会话期间，当 agent 通过 `read_file`、`terminal`、`search_files` 等工具导航进入子目录时，它会**渐进式发现**这些目录中的上下文文件，并在其变得相关的时刻将其注入对话。
|
||||
|
||||
```
|
||||
my-project/
|
||||
├── AGENTS.md ← 启动时加载（系统 prompt）
|
||||
├── frontend/
|
||||
│ └── AGENTS.md ← agent 读取 frontend/ 文件时发现
|
||||
├── backend/
|
||||
│ └── AGENTS.md ← agent 读取 backend/ 文件时发现
|
||||
└── shared/
|
||||
└── AGENTS.md ← agent 读取 shared/ 文件时发现
|
||||
```
|
||||
|
||||
与启动时加载所有内容相比，此方式有两个优势：
|
||||
- **避免系统 prompt 膨胀** — 子目录提示仅在需要时出现
|
||||
- **保留 prompt 缓存** — 系统 prompt 在各轮次间保持稳定
|
||||
|
||||
每个子目录在每次会话中最多检查一次。发现机制同样会向上遍历父目录，因此读取 `backend/src/main.py` 时，即使 `backend/src/` 没有自己的上下文文件，也会发现 `backend/AGENTS.md`。
|
||||
|
||||
:::info
|
||||
子目录上下文文件与启动时的上下文文件经过相同的[安全扫描](#security-prompt-injection-protection)。恶意文件会被拦截。
|
||||
:::
|
||||
|
||||
### AGENTS.md 示例
|
||||
|
||||
```markdown
|
||||
# Project Context
|
||||
|
||||
This is a Next.js 14 web application with a Python FastAPI backend.
|
||||
|
||||
## Architecture
|
||||
- Frontend: Next.js 14 with App Router in `/frontend`
|
||||
- Backend: FastAPI in `/backend`, uses SQLAlchemy ORM
|
||||
- Database: PostgreSQL 16
|
||||
- Deployment: Docker Compose on a Hetzner VPS
|
||||
|
||||
## Conventions
|
||||
- Use TypeScript strict mode for all frontend code
|
||||
- Python code follows PEP 8, use type hints everywhere
|
||||
- All API endpoints return JSON with `{data, error, meta}` shape
|
||||
- Tests go in `__tests__/` directories (frontend) or `tests/` (backend)
|
||||
|
||||
## Important Notes
|
||||
- Never modify migration files directly — use Alembic commands
|
||||
- The `.env.local` file has real API keys, don't commit it
|
||||
- Frontend port is 3000, backend is 8000, DB is 5432
|
||||
```
|
||||
|
||||
## SOUL.md
|
||||
|
||||
`SOUL.md` 控制 agent 的个性、语气和沟通风格。完整详情请参阅[个性](/user-guide/features/personality)页面。
|
||||
|
||||
**位置：**
|
||||
|
||||
- `~/.hermes/SOUL.md`
|
||||
- 或 `$HERMES_HOME/SOUL.md`（若使用自定义主目录运行 Hermes）
|
||||
|
||||
重要说明：
|
||||
|
||||
- 若 `SOUL.md` 尚不存在，Hermes 会自动生成一个默认文件
|
||||
- Hermes 仅从 `HERMES_HOME` 加载 `SOUL.md`
|
||||
- Hermes 不会在工作目录中探测 `SOUL.md`
|
||||
- 若文件为空，`SOUL.md` 中的内容不会添加到 prompt
|
||||
- 若文件有内容，内容在扫描和截断后原样注入
|
||||
|
||||
## .cursorrules
|
||||
|
||||
Hermes 兼容 Cursor IDE 的 `.cursorrules` 文件和 `.cursor/rules/*.mdc` 规则模块。若这些文件存在于项目根目录，且未找到更高优先级的上下文文件（`.hermes.md`、`AGENTS.md` 或 `CLAUDE.md`），则将其作为项目上下文加载。
|
||||
|
||||
这意味着使用 Hermes 时，现有的 Cursor 规范会自动生效。
|
||||
|
||||
## 上下文文件的加载方式
|
||||
|
||||
### 启动时（系统 prompt）
|
||||
|
||||
上下文文件由 `agent/prompt_builder.py` 中的 `build_context_files_prompt()` 加载：
|
||||
|
||||
1. **扫描工作目录** — 依次检查 `.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`（先匹配先生效）
|
||||
2. **读取内容** — 以 UTF-8 文本读取每个文件
|
||||
3. **安全扫描** — 检查内容是否存在 prompt 注入模式
|
||||
4. **截断** — 超过 20,000 个字符的文件进行首尾截断（70% 头部，20% 尾部，中间插入标记）
|
||||
5. **组装** — 所有部分合并在 `# Project Context` 标题下
|
||||
6. **注入** — 组装后的内容添加到系统 prompt
|
||||
|
||||
### 会话期间（渐进式发现）
|
||||
|
||||
`agent/subdirectory_hints.py` 中的 `SubdirectoryHintTracker` 监视工具调用参数中的文件路径：
|
||||
|
||||
1. **路径提取** — 每次工具调用后，从参数（`path`、`workdir`、shell 命令）中提取文件路径
|
||||
2. **祖先目录遍历** — 检查该目录及最多 5 个父目录（跳过已访问的目录）
|
||||
3. **提示加载** — 若发现 `AGENTS.md`、`CLAUDE.md` 或 `.cursorrules`，则加载（每个目录先匹配先生效）
|
||||
4. **安全扫描** — 与启动文件相同的 prompt 注入扫描
|
||||
5. **截断** — 每个文件最多 8,000 个字符
|
||||
6. **注入** — 追加到工具结果中，使模型在上下文中自然看到
|
||||
|
||||
最终 prompt 部分大致如下：
|
||||
|
||||
```text
|
||||
# Project Context
|
||||
|
||||
The following project context files have been loaded and should be followed:
|
||||
|
||||
## AGENTS.md
|
||||
|
||||
[Your AGENTS.md content here]
|
||||
|
||||
## .cursorrules
|
||||
|
||||
[Your .cursorrules content here]
|
||||
|
||||
[Your SOUL.md content here]
|
||||
```
|
||||
|
||||
注意，SOUL 内容直接插入，不带额外的包装文本。
|
||||
|
||||
## 安全性：Prompt 注入防护
|
||||
|
||||
所有上下文文件在被纳入之前都会扫描潜在的 prompt 注入。扫描器检查以下内容：
|
||||
|
||||
- **指令覆盖尝试**：「ignore previous instructions」、「disregard your rules」
|
||||
- **欺骗模式**：「do not tell the user」
|
||||
- **系统 prompt 覆盖**：「system prompt override」
|
||||
- **隐藏 HTML 注释**：`<!-- ignore instructions -->`
|
||||
- **隐藏 div 元素**：`<div style="display:none">`
|
||||
- **凭据窃取**：`curl ... $API_KEY`
|
||||
- **密钥文件访问**：`cat .env`、`cat credentials`
|
||||
- **不可见字符**：零宽空格、双向覆盖字符、词连接符
|
||||
|
||||
若检测到任何威胁模式，该文件将被拦截：
|
||||
|
||||
```
|
||||
[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]
|
||||
```
|
||||
|
||||
:::warning
|
||||
此扫描器可防范常见注入模式，但不能替代对上下文文件的人工审查。对于非本人编写的共享仓库，请务必验证 AGENTS.md 的内容。
|
||||
:::
|
||||
|
||||
## 大小限制
|
||||
|
||||
| 限制 | 值 |
|
||||
|-------|-------|
|
||||
| 每个文件最大字符数 | 20,000（约 7,000 个 token） |
|
||||
| 头部截断比例 | 70% |
|
||||
| 尾部截断比例 | 20% |
|
||||
| 截断标记 | 10%（显示字符数并建议使用文件工具） |
|
||||
|
||||
当文件超过 20,000 个字符时，截断提示如下：
|
||||
|
||||
```
|
||||
[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]
|
||||
```
|
||||
|
||||
## 有效使用上下文文件的技巧
|
||||
|
||||
:::tip AGENTS.md 最佳实践
|
||||
1. **保持简洁** — 远低于 20K 字符；agent 每轮都会读取
|
||||
2. **使用标题结构** — 用 `##` 分节描述架构、规范、重要说明
|
||||
3. **包含具体示例** — 展示首选代码模式、API 结构、命名规范
|
||||
4. **说明禁止事项** — 例如「不得直接修改迁移文件」
|
||||
5. **列出关键路径和端口** — agent 在执行终端命令时会用到
|
||||
6. **随项目演进更新** — 过时的上下文比没有上下文更糟
|
||||
:::
|
||||
|
||||
### 子目录上下文
|
||||
|
||||
对于 monorepo，在嵌套的 AGENTS.md 文件中放置子目录专属指令：
|
||||
|
||||
```markdown
|
||||
<!-- frontend/AGENTS.md -->
|
||||
# Frontend Context
|
||||
|
||||
- Use `pnpm` not `npm` for package management
|
||||
- Components go in `src/components/`, pages in `src/app/`
|
||||
- Use Tailwind CSS, never inline styles
|
||||
- Run tests with `pnpm test`
|
||||
```
|
||||
|
||||
```markdown
|
||||
<!-- backend/AGENTS.md -->
|
||||
# Backend Context
|
||||
|
||||
- Use `poetry` for dependency management
|
||||
- Run the dev server with `poetry run uvicorn main:app --reload`
|
||||
- All endpoints need OpenAPI docstrings
|
||||
- Database models are in `models/`, schemas in `schemas/`
|
||||
```
|
||||
+142
@@ -0,0 +1,142 @@
|
||||
---
|
||||
sidebar_position: 9
|
||||
sidebar_label: "Context References"
|
||||
title: "Context References"
|
||||
description: "用于将文件、文件夹、git diff 及 URL 直接附加到消息中的内联 @-语法"
|
||||
---
|
||||
|
||||
# Context References
|
||||
|
||||
输入 `@` 后跟一个引用，即可将内容直接注入消息。Hermes 会将引用内联展开，并在 `--- Attached Context ---` 区块下追加相应内容。
|
||||
|
||||
## 支持的引用类型
|
||||
|
||||
| 语法 | 说明 |
|
||||
|--------|-------------|
|
||||
| `@file:path/to/file.py` | 注入文件内容 |
|
||||
| `@file:path/to/file.py:10-25` | 注入指定行范围（从 1 开始，含首尾） |
|
||||
| `@folder:path/to/dir` | 注入目录树列表及文件元数据 |
|
||||
| `@diff` | 注入 `git diff`（未暂存的工作区变更） |
|
||||
| `@staged` | 注入 `git diff --staged`（已暂存的变更） |
|
||||
| `@git:5` | 注入最近 N 次提交及补丁（最多 10 次） |
|
||||
| `@url:https://example.com` | 抓取并注入网页内容 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```text
|
||||
Review @file:src/main.py and suggest improvements
|
||||
|
||||
What changed? @diff
|
||||
|
||||
Compare @file:old_config.yaml and @file:new_config.yaml
|
||||
|
||||
What's in @folder:src/components?
|
||||
|
||||
Summarize this article @url:https://arxiv.org/abs/2301.00001
|
||||
```
|
||||
|
||||
单条消息中可使用多个引用：
|
||||
|
||||
```text
|
||||
Check @file:main.py, and also @file:test.py.
|
||||
```
|
||||
|
||||
引用值末尾的标点符号（`,`、`.`、`;`、`!`、`?`）会被自动去除。
|
||||
|
||||
## CLI Tab 补全
|
||||
|
||||
在交互式 CLI 中，输入 `@` 会触发自动补全：
|
||||
|
||||
- `@` 显示所有引用类型（`@diff`、`@staged`、`@file:`、`@folder:`、`@git:`、`@url:`）
|
||||
- `@file:` 和 `@folder:` 触发文件系统路径补全，并显示文件大小元数据
|
||||
- 裸 `@` 后跟部分文本时，显示当前目录中匹配的文件和文件夹
|
||||
|
||||
## 行范围
|
||||
|
||||
`@file:` 引用支持行范围，用于精确注入内容：
|
||||
|
||||
```text
|
||||
@file:src/main.py:42 # 单行第 42 行
|
||||
@file:src/main.py:10-25 # 第 10 至 25 行（含首尾）
|
||||
```
|
||||
|
||||
行号从 1 开始。无效范围会被静默忽略（返回完整文件）。
|
||||
|
||||
## 大小限制
|
||||
|
||||
Context references 受大小限制，以防止超出模型的 context window（上下文窗口）：
|
||||
|
||||
| 阈值 | 值 | 行为 |
|
||||
|-----------|-------|----------|
|
||||
| 软限制 | 上下文长度的 25% | 追加警告，继续展开 |
|
||||
| 硬限制 | 上下文长度的 50% | 拒绝展开，返回原始消息不变 |
|
||||
| 文件夹条目 | 最多 200 个文件 | 超出部分替换为 `- ...` |
|
||||
| Git 提交数 | 最多 10 次 | `@git:N` 限制在 [1, 10] 范围内 |
|
||||
|
||||
## 安全性
|
||||
|
||||
### 敏感路径拦截
|
||||
|
||||
以下路径始终被 `@file:` 引用拦截，以防止凭据泄露：
|
||||
|
||||
- SSH 密钥及配置：`~/.ssh/id_rsa`、`~/.ssh/id_ed25519`、`~/.ssh/authorized_keys`、`~/.ssh/config`
|
||||
- Shell 配置文件：`~/.bashrc`、`~/.zshrc`、`~/.profile`、`~/.bash_profile`、`~/.zprofile`
|
||||
- 凭据文件：`~/.netrc`、`~/.pgpass`、`~/.npmrc`、`~/.pypirc`
|
||||
- Hermes 环境文件：`$HERMES_HOME/.env`
|
||||
|
||||
以下目录被完全拦截（目录内的任意文件均不可访问）：
|
||||
- `~/.ssh/`、`~/.aws/`、`~/.gnupg/`、`~/.kube/`、`$HERMES_HOME/skills/.hub/`
|
||||
|
||||
### 路径遍历防护
|
||||
|
||||
所有路径均相对于工作目录解析。解析结果超出允许的工作区根目录的引用将被拒绝。
|
||||
|
||||
### 二进制文件检测
|
||||
|
||||
通过 MIME 类型和空字节扫描检测二进制文件。已知文本扩展名（`.py`、`.md`、`.json`、`.yaml`、`.toml`、`.js`、`.ts` 等）会跳过基于 MIME 的检测。二进制文件将被拒绝并附带警告。
|
||||
|
||||
## 平台可用性
|
||||
|
||||
Context references 主要是 **CLI 功能**。它们在交互式 CLI 中有效，`@` 触发 tab 补全，引用在消息发送给 agent 之前完成展开。
|
||||
|
||||
在**消息平台**（Telegram、Discord 等）中，`@` 语法不会被 gateway 展开——消息原样透传。agent 本身仍可通过 `read_file`、`search_files` 和 `web_extract` 工具引用文件。
|
||||
|
||||
## 与 Context 压缩的交互
|
||||
|
||||
当对话 context 被压缩时，展开后的引用内容会被纳入压缩摘要。这意味着：
|
||||
|
||||
- 通过 `@file:` 注入的大文件内容会占用 context 用量
|
||||
- 若对话后续被压缩，文件内容将被摘要处理（而非原文保留）
|
||||
- 对于非常大的文件，建议使用行范围（`@file:main.py:100-200`）仅注入相关片段
|
||||
|
||||
## 常用模式
|
||||
|
||||
```text
|
||||
# 代码审查工作流
|
||||
Review @diff and check for security issues
|
||||
|
||||
# 带上下文的调试
|
||||
This test is failing. Here's the test @file:tests/test_auth.py
|
||||
and the implementation @file:src/auth.py:50-80
|
||||
|
||||
# 项目探索
|
||||
What does this project do? @folder:src @file:README.md
|
||||
|
||||
# 研究
|
||||
Compare the approaches in @url:https://arxiv.org/abs/2301.00001
|
||||
and @url:https://arxiv.org/abs/2301.00002
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
无效引用会产生内联警告而非直接报错：
|
||||
|
||||
| 条件 | 行为 |
|
||||
|-----------|----------|
|
||||
| 文件未找到 | 警告："file not found" |
|
||||
| 二进制文件 | 警告："binary files are not supported" |
|
||||
| 文件夹未找到 | 警告："folder not found" |
|
||||
| Git 命令失败 | 警告附带 git stderr 输出 |
|
||||
| URL 无内容返回 | 警告："no content extracted" |
|
||||
| 敏感路径 | 警告："path is a sensitive credential file" |
|
||||
| 路径超出工作区 | 警告："path is outside the allowed workspace" |
|
||||
+240
@@ -0,0 +1,240 @@
|
||||
---
|
||||
title: 凭证池
|
||||
description: 为每个提供商池化多个 API 密钥或 OAuth 令牌，实现自动轮换和速率限制恢复。
|
||||
sidebar_label: 凭证池
|
||||
sidebar_position: 9
|
||||
---
|
||||
|
||||
# 凭证池
|
||||
|
||||
凭证池允许你为同一提供商注册多个 API 密钥或 OAuth 令牌。当某个密钥触达速率限制或计费配额时，Hermes 会自动轮换到下一个健康密钥——在不切换提供商的情况下保持会话持续运行。
|
||||
|
||||
这与[备用提供商](./fallback-providers.md)不同，后者会切换到*另一个*提供商。凭证池是同一提供商内的轮换；备用提供商是跨提供商的故障转移。池会优先尝试——如果池中所有密钥都耗尽，*才会*激活备用提供商。
|
||||
|
||||
## 工作原理
|
||||
|
||||
```
|
||||
Your request
|
||||
→ Pick key from pool (round_robin / least_used / fill_first / random)
|
||||
→ Send to provider
|
||||
→ 429 rate limit?
|
||||
→ Plan/usage limit reached (e.g. ChatGPT/Codex "usage limit reached")?
|
||||
→ Rotate to next pool key immediately (no retry — the cap won't clear on retry)
|
||||
→ Generic / transient 429?
|
||||
→ Retry same key once (transient blip)
|
||||
→ Second 429 → rotate to next pool key
|
||||
→ All keys exhausted → fallback_model (different provider)
|
||||
→ 402 billing error?
|
||||
→ Immediately rotate to next pool key (24h cooldown)
|
||||
→ 401 auth expired?
|
||||
→ Try refreshing the token (OAuth)
|
||||
→ Refresh failed → rotate to next pool key
|
||||
→ Success → continue normally
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
如果你已在 `.env` 中设置了 API 密钥，Hermes 会自动将其识别为单密钥池。要充分利用池化功能，请添加更多密钥：
|
||||
|
||||
```bash
|
||||
# Add a second OpenRouter key
|
||||
hermes auth add openrouter --api-key sk-or-v1-your-second-key
|
||||
|
||||
# Add a second Anthropic key
|
||||
hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key
|
||||
|
||||
# Add an Anthropic OAuth credential (requires Claude Max plan + extra usage credits)
|
||||
hermes auth add anthropic --type oauth
|
||||
# Opens browser for OAuth login
|
||||
```
|
||||
|
||||
查看你的池：
|
||||
|
||||
```bash
|
||||
hermes auth list
|
||||
```
|
||||
|
||||
输出：
|
||||
```
|
||||
openrouter (2 credentials):
|
||||
#1 OPENROUTER_API_KEY api_key env:OPENROUTER_API_KEY ←
|
||||
#2 backup-key api_key manual
|
||||
|
||||
anthropic (3 credentials):
|
||||
#1 hermes_pkce oauth hermes_pkce ←
|
||||
#2 claude_code oauth claude_code
|
||||
#3 ANTHROPIC_API_KEY api_key env:ANTHROPIC_API_KEY
|
||||
```
|
||||
|
||||
`←` 标记当前选中的凭证。
|
||||
|
||||
## 交互式管理
|
||||
|
||||
不带子命令运行 `hermes auth` 以进入交互式向导：
|
||||
|
||||
```bash
|
||||
hermes auth
|
||||
```
|
||||
|
||||
这会显示完整的池状态并提供操作菜单：
|
||||
|
||||
```
|
||||
What would you like to do?
|
||||
1. Add a credential
|
||||
2. Remove a credential
|
||||
3. Reset cooldowns for a provider
|
||||
4. Set rotation strategy for a provider
|
||||
5. Exit
|
||||
```
|
||||
|
||||
对于同时支持 API 密钥和 OAuth 的提供商（Anthropic、Nous、Codex），添加流程会询问类型：
|
||||
|
||||
```
|
||||
anthropic supports both API keys and OAuth login.
|
||||
1. API key (paste a key from the provider dashboard)
|
||||
2. OAuth login (authenticate via browser)
|
||||
Type [1/2]:
|
||||
```
|
||||
|
||||
## CLI 命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
|---------|-------------|
|
||||
| `hermes auth` | 交互式池管理向导 |
|
||||
| `hermes auth list` | 显示所有池和凭证 |
|
||||
| `hermes auth list <provider>` | 显示指定提供商的池 |
|
||||
| `hermes auth add <provider>` | 添加凭证（提示选择类型和密钥） |
|
||||
| `hermes auth add <provider> --type api-key --api-key <key>` | 非交互式添加 API 密钥 |
|
||||
| `hermes auth add <provider> --type oauth` | 通过浏览器登录添加 OAuth 凭证 |
|
||||
| `hermes auth remove <provider> <index>` | 按从 1 开始的索引删除凭证 |
|
||||
| `hermes auth reset <provider>` | 清除所有冷却时间/耗尽状态 |
|
||||
|
||||
## 轮换策略
|
||||
|
||||
通过 `hermes auth` → "Set rotation strategy" 配置，或在 `config.yaml` 中设置：
|
||||
|
||||
```yaml
|
||||
credential_pool_strategies:
|
||||
openrouter: round_robin
|
||||
anthropic: least_used
|
||||
```
|
||||
|
||||
| 策略 | 行为 |
|
||||
|----------|----------|
|
||||
| `fill_first`（默认） | 持续使用第一个健康密钥直至耗尽，然后切换到下一个 |
|
||||
| `round_robin` | 均匀循环遍历所有密钥，每次选择后轮换 |
|
||||
| `least_used` | 始终选择请求次数最少的密钥 |
|
||||
| `random` | 在健康密钥中随机选择 |
|
||||
|
||||
## 错误恢复
|
||||
|
||||
池对不同错误的处理方式不同：
|
||||
|
||||
| 错误 | 行为 | 冷却时间 |
|
||||
|-------|----------|----------|
|
||||
| **429 速率限制** | 对同一密钥重试一次（瞬时错误）。连续第二次 429 则轮换到下一个密钥 | 1 小时 |
|
||||
| **402 计费/配额** | 立即轮换到下一个密钥 | 24 小时 |
|
||||
| **401 认证过期** | 先尝试刷新 OAuth 令牌。仅在刷新失败时才轮换 | — |
|
||||
| **所有密钥耗尽** | 若已配置则转入 `fallback_model` | — |
|
||||
|
||||
`has_retried_429` 标志在每次成功的 API 调用后重置，因此单次瞬时 429 不会触发轮换。
|
||||
|
||||
## 自定义端点池
|
||||
|
||||
自定义 OpenAI 兼容端点（Together.ai、RunPod、本地服务器）拥有各自的池，以 `config.yaml` 中 `custom_providers` 的端点名称作为键。
|
||||
|
||||
通过 `hermes model` 设置自定义端点时，会自动生成类似 "Together.ai" 或 "Local (localhost:8080)" 的名称，该名称即成为池的键。
|
||||
|
||||
```bash
|
||||
# After setting up a custom endpoint via hermes model:
|
||||
hermes auth list
|
||||
# Shows:
|
||||
# Together.ai (1 credential):
|
||||
# #1 config key api_key config:Together.ai ←
|
||||
|
||||
# Add a second key for the same endpoint:
|
||||
hermes auth add Together.ai --api-key sk-together-second-key
|
||||
```
|
||||
|
||||
自定义端点池以 `custom:` 前缀存储在 `auth.json` 的 `credential_pool` 下：
|
||||
|
||||
```json
|
||||
{
|
||||
"credential_pool": {
|
||||
"openrouter": [...],
|
||||
"custom:together.ai": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 自动发现
|
||||
|
||||
Hermes 在启动时自动从多个来源发现凭证并初始化池：
|
||||
|
||||
| 来源 | 示例 | 自动初始化？ |
|
||||
|--------|---------|-------------|
|
||||
| 环境变量 | `OPENROUTER_API_KEY`、`ANTHROPIC_API_KEY` | 是 |
|
||||
| OAuth 令牌（auth.json） | Codex device code、Nous device code | 是 |
|
||||
| Claude Code 凭证 | `~/.claude/.credentials.json` | 是（Anthropic） |
|
||||
| Hermes PKCE OAuth | `~/.hermes/auth.json` | 是（Anthropic） |
|
||||
| 自定义端点配置 | `config.yaml` 中的 `model.api_key` | 是（自定义端点） |
|
||||
| 手动条目 | 通过 `hermes auth add` 添加 | 持久化至 auth.json |
|
||||
|
||||
自动初始化的条目在每次池加载时更新——如果你删除了某个环境变量，其池条目会自动清除。通过 `hermes auth add` 添加的手动条目永远不会被自动清除。
|
||||
|
||||
## 委托与子代理共享
|
||||
|
||||
当代理通过 `delegate_task` 派生子代理时，父代理的凭证池会自动共享给子代理：
|
||||
|
||||
- **相同提供商** — 子代理接收父代理的完整池，在触达速率限制时可进行密钥轮换
|
||||
- **不同提供商** — 子代理加载该提供商自己的池（如已配置）
|
||||
- **未配置池** — 子代理回退到继承的单个 API 密钥
|
||||
|
||||
这意味着子代理无需额外配置即可获得与父代理相同的速率限制弹性。按任务的凭证租用机制确保子代理在并发轮换密钥时不会相互冲突。
|
||||
|
||||
## 线程安全
|
||||
|
||||
凭证池对所有状态变更操作（`select()`、`mark_exhausted_and_rotate()`、`try_refresh_current()`、`mark_used()`）使用线程锁，确保 gateway（网关）同时处理多个聊天会话时的并发访问安全。
|
||||
|
||||
## 架构
|
||||
|
||||
完整的数据流图请参见仓库中的 [`docs/credential-pool-flow.excalidraw`](https://excalidraw.com/#json=2Ycqhqpi6f12E_3ITyiwh,c7u9jSt5BwrmiVzHGbm87g)。
|
||||
|
||||
凭证池集成于提供商解析层：
|
||||
|
||||
1. **`agent/credential_pool.py`** — 池管理器：存储、选择、轮换、冷却时间
|
||||
2. **`hermes_cli/auth_commands.py`** — CLI 命令和交互式向导
|
||||
3. **`hermes_cli/runtime_provider.py`** — 感知池的凭证解析
|
||||
4. **`run_agent.py`** — 错误恢复：429/402/401 → 池轮换 → 备用
|
||||
|
||||
## 存储
|
||||
|
||||
池状态存储在 `~/.hermes/auth.json` 的 `credential_pool` 键下：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"credential_pool": {
|
||||
"openrouter": [
|
||||
{
|
||||
"id": "abc123",
|
||||
"label": "OPENROUTER_API_KEY",
|
||||
"auth_type": "api_key",
|
||||
"priority": 0,
|
||||
"source": "env:OPENROUTER_API_KEY",
|
||||
"access_token": "sk-or-v1-...",
|
||||
"last_status": "ok",
|
||||
"request_count": 142
|
||||
}
|
||||
]
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
策略存储在 `config.yaml` 中（而非 `auth.json`）：
|
||||
|
||||
```yaml
|
||||
credential_pool_strategies:
|
||||
openrouter: round_robin
|
||||
anthropic: least_used
|
||||
```
|
||||
+682
@@ -0,0 +1,682 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
title: "定时任务（Cron）"
|
||||
description: "用自然语言调度自动化任务，通过单一 cron 工具管理，并附加一个或多个 skill"
|
||||
---
|
||||
|
||||
# 定时任务（Cron）
|
||||
|
||||
使用自然语言或 cron 表达式调度自动运行的任务。Hermes 通过单一 `cronjob` 工具暴露 cron 管理能力，采用动作式操作，而非分散的 schedule/list/remove 工具。
|
||||
|
||||
## Cron 当前能做什么
|
||||
|
||||
Cron 任务可以：
|
||||
|
||||
- 调度一次性或周期性任务
|
||||
- 暂停、恢复、编辑、触发和删除任务
|
||||
- 为任务附加零个、一个或多个 skill
|
||||
- 将结果回传到来源会话、本地文件或已配置的平台目标
|
||||
- 在全新的 agent 会话中运行，使用正常的静态工具列表
|
||||
- 以**无 agent 模式**运行——按计划执行脚本，其 stdout 原样投递，零 LLM 参与（参见下方[无 agent 模式](#no-agent-mode-script-only-jobs)章节）
|
||||
|
||||
所有这些功能均可通过 `cronjob` 工具由 Hermes 自身使用，因此你可以用自然语言创建、暂停、编辑和删除任务——无需 CLI。
|
||||
|
||||
:::warning
|
||||
Cron 运行的会话不能递归创建更多 cron 任务。Hermes 在 cron 执行内部禁用了 cron 管理工具，以防止失控的调度循环。
|
||||
:::
|
||||
|
||||
## 创建定时任务
|
||||
|
||||
### 在聊天中使用 `/cron`
|
||||
|
||||
```bash
|
||||
/cron add 30m "Remind me to check the build"
|
||||
/cron add "every 2h" "Check server status"
|
||||
/cron add "every 1h" "Summarize new feed items" --skill blogwatcher
|
||||
/cron add "every 1h" "Use both skills and combine the result" --skill blogwatcher --skill maps
|
||||
```
|
||||
|
||||
### 从独立 CLI
|
||||
|
||||
```bash
|
||||
hermes cron create "every 2h" "Check server status"
|
||||
hermes cron create "every 1h" "Summarize new feed items" --skill blogwatcher
|
||||
hermes cron create "every 1h" "Use both skills and combine the result" \
|
||||
--skill blogwatcher \
|
||||
--skill maps \
|
||||
--name "Skill combo"
|
||||
```
|
||||
|
||||
### 通过自然对话
|
||||
|
||||
直接向 Hermes 描述：
|
||||
|
||||
```text
|
||||
Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.
|
||||
```
|
||||
|
||||
Hermes 会在内部使用统一的 `cronjob` 工具。
|
||||
|
||||
## 附带 skill 的 cron 任务
|
||||
|
||||
Cron 任务可以在运行 prompt（提示词）之前加载一个或多个 skill。
|
||||
|
||||
### 单个 skill
|
||||
|
||||
```python
|
||||
cronjob(
|
||||
action="create",
|
||||
skill="blogwatcher",
|
||||
prompt="Check the configured feeds and summarize anything new.",
|
||||
schedule="0 9 * * *",
|
||||
name="Morning feeds",
|
||||
)
|
||||
```
|
||||
|
||||
### 多个 skill
|
||||
|
||||
Skill 按顺序加载。Prompt 作为任务指令叠加在这些 skill 之上。
|
||||
|
||||
```python
|
||||
cronjob(
|
||||
action="create",
|
||||
skills=["blogwatcher", "maps"],
|
||||
prompt="Look for new local events and interesting nearby places, then combine them into one short brief.",
|
||||
schedule="every 6h",
|
||||
name="Local brief",
|
||||
)
|
||||
```
|
||||
|
||||
当你希望定时 agent 继承可复用的工作流，而不必将完整的 skill 文本塞入 cron prompt 本身时，这非常有用。
|
||||
|
||||
## 在指定项目目录中运行任务
|
||||
|
||||
Cron 任务默认与任何代码仓库脱离运行——不加载 `AGENTS.md`、`CLAUDE.md` 或 `.cursorrules`，终端/文件/代码执行工具从 gateway 启动时的工作目录运行。传入 `--workdir`（CLI）或 `workdir=`（工具调用）可更改此行为：
|
||||
|
||||
```bash
|
||||
# 独立 CLI（schedule 和 prompt 为位置参数）
|
||||
hermes cron create "every 1d at 09:00" \
|
||||
"Audit open PRs, summarize CI health, and post to #eng" \
|
||||
--workdir /home/me/projects/acme
|
||||
```
|
||||
|
||||
```python
|
||||
# 在聊天中，通过 cronjob 工具
|
||||
cronjob(
|
||||
action="create",
|
||||
schedule="every 1d at 09:00",
|
||||
workdir="/home/me/projects/acme",
|
||||
prompt="Audit open PRs, summarize CI health, and post to #eng",
|
||||
)
|
||||
```
|
||||
|
||||
设置 `workdir` 后：
|
||||
|
||||
- 该目录中的 `AGENTS.md`、`CLAUDE.md` 和 `.cursorrules` 会被注入系统 prompt（发现顺序与交互式 CLI 相同）
|
||||
- `terminal`、`read_file`、`write_file`、`patch`、`search_files` 和 `execute_code` 均以该目录为工作目录（通过 `TERMINAL_CWD`）
|
||||
- 路径必须是已存在的绝对目录——相对路径和不存在的目录在创建/更新时会被拒绝
|
||||
- 编辑时传入 `--workdir ""`（或工具中的 `workdir=""`）可清除该设置并恢复原有行为
|
||||
|
||||
:::note 串行化
|
||||
设置了 `workdir` 的任务在调度器 tick 时串行运行，而非在并行池中运行。这是有意为之——`TERMINAL_CWD` 是进程全局变量，两个 workdir 任务同时运行会互相破坏各自的 cwd。无 workdir 的任务仍像以前一样并行运行。
|
||||
:::
|
||||
|
||||
## 在指定 profile 中运行 cron 任务
|
||||
|
||||
默认情况下，cron 任务继承创建它的 gateway/CLI 所属的 Hermes profile。传入 `--profile <name>`（CLI）或 `profile=`（cronjob 工具）可将任务重定向到不同的 profile——调度器会解析该 profile 的 `HERMES_HOME`，在运行期间临时切换到该 profile，加载其 `.env` 和 `config.yaml`，并在其中执行任务：
|
||||
|
||||
```bash
|
||||
# 将任务固定到 `night-ops` profile，无论在哪里调度
|
||||
hermes cron create "every 1d at 03:00" \
|
||||
"Tail the security log and flag anomalies" \
|
||||
--profile night-ops
|
||||
```
|
||||
|
||||
```python
|
||||
# 在聊天中，通过 cronjob 工具
|
||||
cronjob(
|
||||
action="create",
|
||||
schedule="every 1d at 03:00",
|
||||
prompt="Tail the security log and flag anomalies",
|
||||
profile="night-ops",
|
||||
)
|
||||
```
|
||||
|
||||
使用 `--profile default` 可显式固定到根 Hermes profile。指定的 profile 必须已存在；调度器不会动态创建 profile。在 `cron edit` 时清除 profile 固定，传入空字符串（`--profile ""` 或 `profile=""`）——任务将恢复在调度器当前所在的 profile 中运行。
|
||||
|
||||
如果固定的 profile 后来被删除，调度器会记录警告并回退到在当前 profile 中运行该任务，而不是崩溃——因此过期的 `profile` 引用不会卡住任务。
|
||||
|
||||
:::note 串行化
|
||||
设置了 `profile` 的任务也串行运行，原因与 `workdir` 固定任务相同：切换 `HERMES_HOME` 是进程全局变更，两个 profile 固定任务并行运行会产生竞争。未固定的任务仍在正常并行池中运行。
|
||||
:::
|
||||
|
||||
## 编辑任务
|
||||
|
||||
无需删除并重建任务来修改它们。
|
||||
|
||||
:::tip 任务引用
|
||||
下方（以及[生命周期操作](#lifecycle-actions)中）的 `<job_id>` 占位符也接受任务名称（不区分大小写）——当你记得 `morning-digest` 但不记得十六进制 ID 时很方便。精确的任务 ID 优先于名称匹配；如果引用不是 ID 且名称匹配到多个任务，命令会拒绝执行并打印候选 ID 供你消歧义。
|
||||
:::
|
||||
|
||||
### 聊天
|
||||
|
||||
```bash
|
||||
/cron edit <job_id> --schedule "every 4h"
|
||||
/cron edit <job_id> --prompt "Use the revised task"
|
||||
/cron edit <job_id> --skill blogwatcher --skill maps
|
||||
/cron edit <job_id> --remove-skill blogwatcher
|
||||
/cron edit <job_id> --clear-skills
|
||||
```
|
||||
|
||||
### 独立 CLI
|
||||
|
||||
```bash
|
||||
hermes cron edit <job_id> --schedule "every 4h"
|
||||
hermes cron edit <job_id> --prompt "Use the revised task"
|
||||
hermes cron edit <job_id> --skill blogwatcher --skill maps
|
||||
hermes cron edit <job_id> --add-skill maps
|
||||
hermes cron edit <job_id> --remove-skill blogwatcher
|
||||
hermes cron edit <job_id> --clear-skills
|
||||
```
|
||||
|
||||
注意：
|
||||
|
||||
- 重复使用 `--skill` 会替换任务已附加的 skill 列表
|
||||
- `--add-skill` 追加到现有列表，不替换
|
||||
- `--remove-skill` 删除指定的已附加 skill
|
||||
- `--clear-skills` 删除所有已附加的 skill
|
||||
|
||||
## 生命周期操作
|
||||
|
||||
Cron 任务现在拥有比创建/删除更完整的生命周期。
|
||||
|
||||
### 聊天
|
||||
|
||||
```bash
|
||||
/cron list
|
||||
/cron pause <job_id>
|
||||
/cron resume <job_id>
|
||||
/cron run <job_id>
|
||||
/cron remove <job_id>
|
||||
```
|
||||
|
||||
### 独立 CLI
|
||||
|
||||
```bash
|
||||
hermes cron list
|
||||
hermes cron pause <job_id>
|
||||
hermes cron resume <job_id>
|
||||
hermes cron run <job_id>
|
||||
hermes cron remove <job_id>
|
||||
hermes cron status
|
||||
hermes cron tick
|
||||
```
|
||||
|
||||
各操作说明：
|
||||
|
||||
- `pause` — 保留任务但停止调度
|
||||
- `resume` — 重新启用任务并计算下次运行时间
|
||||
- `run` — 在下次调度器 tick 时触发任务
|
||||
- `remove` — 彻底删除任务
|
||||
|
||||
## 工作原理
|
||||
|
||||
**Cron 执行由 gateway 守护进程处理。** Gateway 每 60 秒 tick 一次调度器，在隔离的 agent 会话中运行到期的任务。
|
||||
|
||||
```bash
|
||||
hermes gateway install # 安装为用户服务
|
||||
sudo hermes gateway install --system # Linux：服务器开机启动的系统服务
|
||||
hermes gateway # 或在前台运行
|
||||
|
||||
hermes cron list
|
||||
hermes cron status
|
||||
```
|
||||
|
||||
### Gateway 调度器行为
|
||||
|
||||
每次 tick 时，Hermes：
|
||||
|
||||
1. 从 `~/.hermes/cron/jobs.json` 加载任务
|
||||
2. 对照当前时间检查 `next_run_at`
|
||||
3. 为每个到期任务启动全新的 `AIAgent` 会话
|
||||
4. 可选地将一个或多个已附加的 skill 注入该新会话
|
||||
5. 将 prompt 运行至完成
|
||||
6. 投递最终响应
|
||||
7. 更新运行元数据和下次调度时间
|
||||
|
||||
`~/.hermes/cron/.tick.lock` 处的文件锁防止重叠的调度器 tick 重复运行同一批任务。
|
||||
|
||||
## 投递选项
|
||||
|
||||
调度任务时，你可以指定输出的去向：
|
||||
|
||||
| 选项 | 说明 | 示例 |
|
||||
|--------|-------------|---------|
|
||||
| `"origin"` | 回传到任务创建的来源 | 消息平台上的默认值 |
|
||||
| `"local"` | 仅保存到本地文件（`~/.hermes/cron/output/`） | CLI 上的默认值 |
|
||||
| `"telegram"` | Telegram 主频道 | 使用 `TELEGRAM_HOME_CHANNEL` |
|
||||
| `"telegram:123456"` | 按 ID 指定的 Telegram 会话 | 直接投递 |
|
||||
| `"telegram:-100123:17585"` | 指定 Telegram 话题 | `chat_id:thread_id` 格式 |
|
||||
| `"discord"` | Discord 主频道 | 使用 `DISCORD_HOME_CHANNEL` |
|
||||
| `"discord:#engineering"` | 按频道名指定的 Discord 频道 | 按频道名 |
|
||||
| `"slack"` | Slack 主频道 | |
|
||||
| `"whatsapp"` | WhatsApp 主账号 | |
|
||||
| `"signal"` | Signal | |
|
||||
| `"matrix"` | Matrix 主房间 | |
|
||||
| `"mattermost"` | Mattermost 主频道 | |
|
||||
| `"email"` | 邮件 | |
|
||||
| `"sms"` | 通过 Twilio 发送 SMS | |
|
||||
| `"homeassistant"` | Home Assistant | |
|
||||
| `"dingtalk"` | 钉钉 | |
|
||||
| `"feishu"` | 飞书/Lark | |
|
||||
| `"wecom"` | 企业微信 | |
|
||||
| `"weixin"` | 微信（WeChat） | |
|
||||
| `"bluebubbles"` | BlueBubbles（iMessage） | |
|
||||
| `"qqbot"` | QQ Bot（腾讯 QQ） | |
|
||||
| `"all"` | 扇出到所有已连接的主频道 | 触发时解析 |
|
||||
| `"telegram,discord"` | 扇出到指定的一组频道 | 逗号分隔列表 |
|
||||
| `"origin,all"` | 投递到来源**加上**所有其他已连接频道 | 可组合任意 token |
|
||||
|
||||
Agent 的最终响应会自动投递，无需在 cron prompt 中调用 `send_message`。
|
||||
|
||||
### 路由意图（`all`）
|
||||
|
||||
`all` 让你将一个 cron 任务发送到所有已配置的消息频道，无需逐一列举名称。它在**触发时解析**，因此在你配置 `TELEGRAM_HOME_CHANNEL` 之前创建的任务，会在下次 tick 时自动纳入 Telegram。
|
||||
|
||||
语义：`all` 展开为所有已配置主频道的平台。零个也没问题；任务只是没有投递目标，并在上游记录为投递失败。
|
||||
|
||||
`all` 可与显式目标组合。`origin,all` 投递到来源会话**加上**所有其他已连接的主频道，按 `(platform, chat_id, thread_id)` 去重。
|
||||
|
||||
### Telegram cron 话题（`TELEGRAM_CRON_THREAD_ID`）
|
||||
|
||||
启用 Telegram 话题模式后，根 DM 被保留为系统大厅——发送到那里的回复会被拒绝并附带大厅提示，`reply_to_message_id` 会被丢弃，因此你无法回复落在主聊天中的 cron 消息。
|
||||
|
||||
将 cron 指向专用的论坛话题：
|
||||
|
||||
1. 在 Telegram 中打开机器人 DM，创建一个名为 `Cron` 的话题。长按话题标题 → **复制链接**；末尾的整数即为该话题的 `message_thread_id`。
|
||||
2. 在 `.env` 中设置 `TELEGRAM_CRON_THREAD_ID=<该 id>`。
|
||||
|
||||
这仅适用于 cron 投递。`TELEGRAM_HOME_CHANNEL_THREAD_ID`（用于其他地方，如重启通知）不受影响。显式的 `deliver="telegram:chat_id:thread_id"` 目标仍优先于环境变量。对 cron 消息的回复现在会进入已有的话题会话，你可以直接在其中操作。
|
||||
|
||||
### 响应包装
|
||||
|
||||
默认情况下，投递的 cron 输出会带有页眉和页脚，以便接收方知道这来自定时任务：
|
||||
|
||||
```
|
||||
Cronjob Response: Morning feeds
|
||||
-------------
|
||||
|
||||
<agent output here>
|
||||
|
||||
Note: The agent cannot see this message, and therefore cannot respond to it.
|
||||
```
|
||||
|
||||
若要投递不带包装的原始 agent 输出，将 `cron.wrap_response` 设为 `false`：
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
cron:
|
||||
wrap_response: false
|
||||
```
|
||||
|
||||
### 静默抑制
|
||||
|
||||
如果 agent 的最终响应以 `[SILENT]` 开头，投递将被完全抑制。输出仍会保存到本地以供审计（位于 `~/.hermes/cron/output/`），但不会向投递目标发送任何消息。
|
||||
|
||||
这对于只在出现问题时才需要上报的监控任务很有用：
|
||||
|
||||
```text
|
||||
Check if nginx is running. If everything is healthy, respond with only [SILENT].
|
||||
Otherwise, report the issue.
|
||||
```
|
||||
|
||||
失败的任务无论 `[SILENT]` 标记如何都会投递——只有成功的运行才能被静默。
|
||||
|
||||
## 脚本超时
|
||||
|
||||
预运行脚本（通过 `script` 参数附加）的默认超时为 120 秒。如果你的脚本需要更长时间——例如，包含随机延迟以避免类机器人的时序模式——可以增加此值：
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
cron:
|
||||
script_timeout_seconds: 300 # 5 分钟
|
||||
```
|
||||
|
||||
或设置 `HERMES_CRON_SCRIPT_TIMEOUT` 环境变量。解析顺序为：环境变量 → config.yaml → 默认 120 秒。
|
||||
|
||||
## 无 agent 模式（纯脚本任务）
|
||||
|
||||
对于不需要 LLM 推理的周期性任务——经典的看门狗、磁盘/内存告警、心跳、CI ping——在创建时传入 `no_agent=True`。调度器按计划运行你的脚本，并直接投递其 stdout，完全跳过 agent：
|
||||
|
||||
```bash
|
||||
hermes cron create "every 5m" \
|
||||
--no-agent \
|
||||
--script memory-watchdog.sh \
|
||||
--deliver telegram \
|
||||
--name "memory-watchdog"
|
||||
```
|
||||
|
||||
语义：
|
||||
|
||||
- 脚本 stdout（去除首尾空白）→ 原样作为消息投递。
|
||||
- **stdout 为空 → 静默 tick**，不投递。这是看门狗模式："只在出现问题时才说话"。
|
||||
- 非零退出或超时 → 投递错误告警，确保损坏的看门狗不会静默失败。
|
||||
- 最后一行输出 `{"wakeAgent": false}` → 静默 tick（与 LLM 任务使用相同的门控）。
|
||||
- 无 token、无模型、无 provider 回退——任务永远不会触及推理层。
|
||||
|
||||
`.sh`/`.bash` 文件在 `/bin/bash` 下运行；其他文件在当前 Python 解释器（`sys.executable`）下运行。脚本必须位于 `~/.hermes/scripts/`（与预运行脚本门控相同的沙箱规则）。
|
||||
|
||||
### Agent 为你设置这些
|
||||
|
||||
`cronjob` 工具的 schema 直接向 Hermes 暴露了 `no_agent`，因此你可以在聊天中描述一个看门狗，让 agent 来配置它：
|
||||
|
||||
```text
|
||||
Ping me on Telegram if RAM is over 85%, every 5 minutes.
|
||||
```
|
||||
|
||||
Hermes 会通过 `write_file` 将检查脚本写入 `~/.hermes/scripts/`，然后调用：
|
||||
|
||||
```python
|
||||
cronjob(action="create", schedule="every 5m",
|
||||
script="memory-watchdog.sh", no_agent=True,
|
||||
deliver="telegram", name="memory-watchdog")
|
||||
```
|
||||
|
||||
当消息内容完全由脚本决定时（看门狗、阈值告警、心跳），它会自动选择 `no_agent=True`。同一工具也让 agent 可以暂停、恢复、编辑和删除任务——整个生命周期都通过聊天驱动，无需任何人接触 CLI。
|
||||
|
||||
参见[纯脚本 Cron 任务指南](/guides/cron-script-only)获取实际示例。
|
||||
|
||||
## 通过 `context_from` 串联任务
|
||||
|
||||
Cron 任务在隔离的会话中运行，不保留之前运行的记忆。但有时一个任务的输出恰好是下一个任务所需的输入。`context_from` 参数自动建立这种连接——任务 B 的 prompt 在运行时会将任务 A 的最新输出作为上下文前置。
|
||||
|
||||
```python
|
||||
# 任务 1：收集原始数据
|
||||
cronjob(
|
||||
action="create",
|
||||
prompt="Fetch the top 10 AI/ML stories from Hacker News. Save them to ~/.hermes/data/briefs/raw.md in markdown format with title, URL, and score.",
|
||||
schedule="0 7 * * *",
|
||||
name="AI News Collector",
|
||||
)
|
||||
|
||||
# 任务 2：分类——接收任务 1 的输出作为上下文
|
||||
# 从 cronjob(action="list") 获取任务 1 的 ID
|
||||
cronjob(
|
||||
action="create",
|
||||
prompt="Read ~/.hermes/data/briefs/raw.md. Score each story 1–10 for engagement potential and novelty. Output the top 5 to ~/.hermes/data/briefs/ranked.md.",
|
||||
schedule="30 7 * * *",
|
||||
context_from="<job1_id>",
|
||||
name="AI News Triage",
|
||||
)
|
||||
|
||||
# 任务 3：发布——接收任务 2 的输出作为上下文
|
||||
cronjob(
|
||||
action="create",
|
||||
prompt="Read ~/.hermes/data/briefs/ranked.md. Write 3 tweet drafts (hook + body + hashtags). Deliver to telegram:7976161601.",
|
||||
schedule="0 8 * * *",
|
||||
context_from="<job2_id>",
|
||||
name="AI News Brief",
|
||||
)
|
||||
```
|
||||
|
||||
**工作原理：**
|
||||
|
||||
- 任务 2 触发时，Hermes 从 `~/.hermes/cron/output/{job1_id}/*.md` 读取任务 1 的最新输出
|
||||
- 该输出自动前置到任务 2 的 prompt
|
||||
- 任务 2 无需硬编码"读取此文件"——它以上下文形式接收内容
|
||||
- 链可以是任意长度：任务 1 → 任务 2 → 任务 3 → …
|
||||
|
||||
**`context_from` 接受的格式：**
|
||||
|
||||
| 格式 | 示例 |
|
||||
|--------|---------|
|
||||
| 单个任务 ID（字符串） | `context_from="a1b2c3d4"` |
|
||||
| 多个任务 ID（列表） | `context_from=["job_a", "job_b"]` |
|
||||
|
||||
输出按列表顺序拼接。
|
||||
|
||||
**适用场景：**
|
||||
|
||||
- 多阶段流水线（收集 → 过滤 → 格式化 → 投递）
|
||||
- 步骤 N 依赖步骤 N−1 输出的依赖任务
|
||||
- 一个任务聚合多个其他任务结果的扇入模式
|
||||
|
||||
## Provider 恢复
|
||||
|
||||
Cron 任务继承你配置的回退 provider 和凭证池轮换。如果主 API key 被限速或 provider 返回错误，cron agent 可以：
|
||||
|
||||
- **回退到备用 provider**，前提是你在 `config.yaml` 中配置了 `fallback_providers`（或旧版 `fallback_model`）
|
||||
- **轮换到下一个凭证**，即同一 provider 的[凭证池](/user-guide/configuration#credential-pool-strategies)中的下一个
|
||||
|
||||
这意味着高频运行或在高峰时段运行的 cron 任务更具弹性——单个被限速的 key 不会导致整次运行失败。
|
||||
|
||||
## 调度格式
|
||||
|
||||
Agent 的最终响应会自动投递——你**无需**在 cron prompt 中为同一目标包含 `send_message`。如果 cron 运行调用了 `send_message` 且目标与调度器已投递的目标完全相同，Hermes 会跳过该重复发送，并告知模型将面向用户的内容放在最终响应中。仅对额外或不同的目标使用 `send_message`。
|
||||
|
||||
### 相对延迟（一次性）
|
||||
|
||||
```text
|
||||
30m → 30 分钟后运行一次
|
||||
2h → 2 小时后运行一次
|
||||
1d → 1 天后运行一次
|
||||
```
|
||||
|
||||
### 间隔（周期性）
|
||||
|
||||
```text
|
||||
every 30m → 每 30 分钟
|
||||
every 2h → 每 2 小时
|
||||
every 1d → 每天
|
||||
```
|
||||
|
||||
### Cron 表达式
|
||||
|
||||
```text
|
||||
0 9 * * * → 每天上午 9:00
|
||||
0 9 * * 1-5 → 工作日上午 9:00
|
||||
0 */6 * * * → 每 6 小时
|
||||
30 8 1 * * → 每月 1 日上午 8:30
|
||||
0 0 * * 0 → 每周日午夜
|
||||
```
|
||||
|
||||
### ISO 时间戳
|
||||
|
||||
```text
|
||||
2026-03-15T09:00:00 → 2026 年 3 月 15 日上午 9:00 一次性运行
|
||||
```
|
||||
|
||||
## 重复行为
|
||||
|
||||
| 调度类型 | 默认重复次数 | 行为 |
|
||||
|--------------|----------------|----------|
|
||||
| 一次性（`30m`、时间戳） | 1 | 运行一次 |
|
||||
| 间隔（`every 2h`） | 永久 | 运行直到删除 |
|
||||
| Cron 表达式 | 永久 | 运行直到删除 |
|
||||
|
||||
可以覆盖：
|
||||
|
||||
```python
|
||||
cronjob(
|
||||
action="create",
|
||||
prompt="...",
|
||||
schedule="every 2h",
|
||||
repeat=5,
|
||||
)
|
||||
```
|
||||
|
||||
## 以编程方式管理任务
|
||||
|
||||
面向 agent 的 API 是单一工具：
|
||||
|
||||
```python
|
||||
cronjob(action="create", ...)
|
||||
cronjob(action="list")
|
||||
cronjob(action="update", job_id="...")
|
||||
cronjob(action="pause", job_id="...")
|
||||
cronjob(action="resume", job_id="...")
|
||||
cronjob(action="run", job_id="...")
|
||||
cronjob(action="remove", job_id="...")
|
||||
```
|
||||
|
||||
对于 `update`，传入 `skills=[]` 可删除所有已附加的 skill。
|
||||
|
||||
## Cron 任务可用的工具集
|
||||
|
||||
Cron 在全新的 agent 会话中运行每个任务，不附加任何聊天平台。默认情况下，cron agent 获得**你在 `hermes tools` 中为 `cron` 平台配置的工具集**——不是 CLI 默认值，也不是所有工具。
|
||||
|
||||
```bash
|
||||
hermes tools
|
||||
# → 在 curses UI 中选择 "cron" 平台
|
||||
# → 像 Telegram/Discord 等平台一样切换工具集开关
|
||||
```
|
||||
|
||||
通过 `cronjob.create`（或通过 `cronjob.update` 对现有任务）上的 `enabled_toolsets` 字段可进行更精细的单任务控制：
|
||||
|
||||
```text
|
||||
cronjob(action="create", name="weekly-news-summary",
|
||||
schedule="every sunday 9am",
|
||||
enabled_toolsets=["web", "file"], # 仅 web + file，无 terminal/browser 等
|
||||
prompt="Summarize this week's AI news: ...")
|
||||
```
|
||||
|
||||
当任务上设置了 `enabled_toolsets` 时，它优先生效；否则 `hermes tools` 的 cron 平台配置生效；否则 Hermes 回退到内置默认值。这对成本控制很重要：在每个小型"获取新闻"任务中携带 `moa`、`browser`、`delegation` 会在每次 LLM 调用时膨胀工具 schema prompt。
|
||||
|
||||
### 完全跳过 agent：`wakeAgent`
|
||||
|
||||
如果你的 cron 任务附加了预检脚本（通过 `script=`），脚本可以在运行时决定 Hermes 是否应该调用 agent。在 stdout 最后一行输出如下格式：
|
||||
|
||||
```text
|
||||
{"wakeAgent": false}
|
||||
```
|
||||
|
||||
……cron 将完全跳过本次 tick 的 agent 运行。适用于高频轮询（每 1–5 分钟），只在状态实际发生变化时才需要唤醒 LLM——否则你会为一遍遍的零内容 agent 轮次付费。
|
||||
|
||||
```python
|
||||
# 预检脚本
|
||||
import json, sys
|
||||
latest = fetch_latest_issue_count()
|
||||
prev = read_state("issue_count")
|
||||
if latest == prev:
|
||||
print(json.dumps({"wakeAgent": False})) # 跳过本次 tick
|
||||
sys.exit(0)
|
||||
write_state("issue_count", latest)
|
||||
print(json.dumps({"wakeAgent": True, "context": {"new_issues": latest - prev}}))
|
||||
```
|
||||
|
||||
省略 `wakeAgent` 时，默认为 `true`（照常唤醒 agent）。
|
||||
|
||||
#### 实用方案：低成本预运行门控
|
||||
|
||||
`wakeAgent` 门控提供了一种零成本的方式，用于决定定时任务是否应该消耗任何 LLM token。三种模式覆盖了大多数使用场景。
|
||||
|
||||
**文件变更门控**——仅在被监视文件自上次成功 tick 以来有新内容时运行。调度器记录每个任务的 `last_run_at`；将其与文件的 mtime 比较。
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# ~/.hermes/scripts/feed-changed.sh
|
||||
FEED="$HOME/data/feed.json"
|
||||
STATE="$HOME/.hermes/scripts/.feed-changed.last"
|
||||
test -f "$FEED" || { echo '{"wakeAgent": false}'; exit 0; }
|
||||
mtime=$(stat -c %Y "$FEED")
|
||||
last=$(cat "$STATE" 2>/dev/null || echo 0)
|
||||
if [ "$mtime" -le "$last" ]; then
|
||||
echo '{"wakeAgent": false}'
|
||||
else
|
||||
echo "$mtime" > "$STATE"
|
||||
echo '{"wakeAgent": true}'
|
||||
fi
|
||||
```
|
||||
|
||||
```text
|
||||
cronjob(action="create", name="process-feed",
|
||||
schedule="every 30m",
|
||||
script="feed-changed.sh",
|
||||
prompt="A new ~/data/feed.json has landed. Summarize what changed.")
|
||||
```
|
||||
|
||||
**外部标志门控**——仅在其他进程发出就绪信号时运行（例如，部署 hook 落下一个文件，CI 任务在状态存储中设置一个值）。
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# ~/.hermes/scripts/flag-ready.sh
|
||||
if test -f /tmp/new-data-ready; then
|
||||
rm -f /tmp/new-data-ready
|
||||
echo '{"wakeAgent": true}'
|
||||
else
|
||||
echo '{"wakeAgent": false}'
|
||||
fi
|
||||
```
|
||||
|
||||
```text
|
||||
cronjob(action="create", name="nightly-analysis",
|
||||
schedule="0 9 * * *",
|
||||
script="flag-ready.sh",
|
||||
prompt="Run the nightly analysis over today's batch.")
|
||||
```
|
||||
|
||||
**SQL 计数门控**——仅在你自己的数据库中有新行需要处理时运行。脚本还可以通过 `context` 将计数传递给 agent，让 agent 无需重新查询就知道数据量。
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python
|
||||
# ~/.hermes/scripts/new-rows.py
|
||||
import json, sqlite3
|
||||
conn = sqlite3.connect("/home/me/data/app.db")
|
||||
n = conn.execute(
|
||||
"SELECT COUNT(*) FROM messages WHERE ts > strftime('%s','now','-2 hours')"
|
||||
).fetchone()[0]
|
||||
if n < 1:
|
||||
print(json.dumps({"wakeAgent": False}))
|
||||
else:
|
||||
print(json.dumps({"wakeAgent": True, "context": {"new_rows": n}}))
|
||||
```
|
||||
|
||||
```text
|
||||
cronjob(action="create", name="summarize-new-msgs",
|
||||
schedule="every 2h",
|
||||
script="new-rows.py",
|
||||
prompt="Summarize the new messages from the last 2 hours.")
|
||||
```
|
||||
|
||||
同样的模式适用于任何可以从脚本查询的数据源——Postgres、HTTP API、你自己的状态存储——无需将 SQL 求值器内置到 cron 子系统中。
|
||||
|
||||
:::tip
|
||||
Hermes 自身的 `~/.hermes/state.db` 是内部 schema，会在版本间变更。不要从预运行门控中查询它——指向你自己的数据库或 feed。
|
||||
:::
|
||||
|
||||
致谢：此方案集由 @iankar8 在 [#2654](https://github.com/NousResearch/hermes-agent/pull/2654) 中的探索所启发，该 PR 提议将 sql/file/command 触发器作为并行机制添加。`script` + `wakeAgent` 门控已以零成本覆盖了所有三种情况，因此该工作以文档形式落地。
|
||||
|
||||
### 串联任务：`context_from`
|
||||
|
||||
Cron 任务可以通过在 `context_from` 中列出其他任务的名称（或 ID）来消费这些任务最近一次成功运行的输出：
|
||||
|
||||
```text
|
||||
cronjob(action="create", name="daily-digest",
|
||||
schedule="every day 7am",
|
||||
context_from=["ai-news-fetch", "github-prs-fetch"],
|
||||
prompt="Write the daily digest using the outputs above.")
|
||||
```
|
||||
|
||||
被引用任务最近一次完成的输出会作为上下文注入到本次运行的 prompt 之上。每个上游条目必须是有效的任务 ID 或名称（参见 `cronjob action="list"`）。注意：串联读取的是*最近一次完成*的输出——它不会等待同一 tick 中正在运行的上游任务。
|
||||
|
||||
## 任务存储
|
||||
|
||||
任务存储在 `~/.hermes/cron/jobs.json`。任务运行的输出保存到 `~/.hermes/cron/output/{job_id}/{timestamp}.md`。
|
||||
|
||||
任务可能将 `model` 和 `provider` 存储为 `null`。省略这些字段时，Hermes 在执行时从全局配置中解析它们。只有设置了单任务覆盖时，这些字段才会出现在任务记录中。
|
||||
|
||||
存储使用原子文件写入，因此中断的写入不会留下部分写入的任务文件。
|
||||
|
||||
## 自包含的 prompt 仍然重要
|
||||
|
||||
:::warning 重要
|
||||
Cron 任务在完全全新的 agent 会话中运行。Prompt 必须包含 agent 所需的一切，除非已由附加的 skill 提供。
|
||||
:::
|
||||
|
||||
**错误：** `"Check on that server issue"`
|
||||
|
||||
**正确：** `"SSH into server 192.168.1.100 as user 'deploy', check if nginx is running with 'systemctl status nginx', and verify https://example.com returns HTTP 200."`
|
||||
|
||||
## 安全性
|
||||
|
||||
定时任务的 prompt 在创建和更新时会扫描 prompt 注入和凭证外泄模式。包含不可见 Unicode 技巧、SSH 后门尝试或明显的密钥外泄载荷的 prompt 会被拦截。
|
||||
+248
@@ -0,0 +1,248 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: "Curator"
|
||||
description: "Agent 创建的技能的后台维护——使用跟踪、过期检测、归档及 LLM 驱动的审查"
|
||||
---
|
||||
|
||||
# Curator
|
||||
|
||||
Curator 是针对 **agent 创建的技能**的后台维护流程。它跟踪每个技能被查看、使用和修补的频率，将长期未使用的技能经历 `active → stale → archived` 状态流转，并定期启动一个短暂的辅助模型审查，提出合并或修补漂移的建议。
|
||||
|
||||
它的存在是为了防止通过[自我改进循环](/user-guide/features/skills#agent-managed-skills-skill_manage-tool)创建的技能无限堆积。每次 agent 解决新问题并保存技能时，该技能都会落入 `~/.hermes/skills/`。若没有维护，最终会出现数十个范围狭窄的近似重复项，污染技能目录并浪费 token（令牌）。
|
||||
|
||||
默认情况下（`prune_builtins: true`），Curator 在 `archive_after_days` 天未使用后，可以归档**未使用的捆绑内置技能**（随仓库附带），与它主要管理的 agent 自创技能一并处理。通过 [agentskills.io](https://agentskills.io) 安装的 hub 技能始终不受影响。设置 `curator.prune_builtins: false` 可恢复旧的“仅 agent 自创”行为，此时捆绑技能绝不会被触碰。Curator 也**绝不自动删除**——最坏的结果是归档到 `~/.hermes/skills/.archive/`，这是可恢复的。
|
||||
|
||||
跟踪 [issue #7816](https://github.com/NousResearch/hermes-agent/issues/7816)。
|
||||
|
||||
## 运行方式
|
||||
|
||||
Curator 由空闲检查触发，而非 cron 守护进程。在 CLI 会话启动时，以及 gateway 的 cron-ticker 线程内的周期性 tick 中，Hermes 会检查以下条件是否同时满足：
|
||||
|
||||
1. 距上次 curator 运行已过去足够长的时间（`interval_hours`，默认 **7 天**），以及
|
||||
2. agent 已空闲足够长的时间（`min_idle_hours`，默认 **2 小时**）。
|
||||
|
||||
若两个条件均满足，则会派生一个 `AIAgent` 的后台 fork——与内存/技能自我改进 nudge 使用的模式相同。该 fork 在自己的 prompt（提示词）缓存中运行，绝不触碰当前活跃的对话。
|
||||
|
||||
:::info 首次运行行为
|
||||
在全新安装时（或 pre-curator 版本在 `hermes update` 后首次 tick 时），curator **不会立即运行**。首次观测会将 `last_run_at` 设为"当前时间"，并将第一次真正的运行推迟整整一个 `interval_hours`。这给了你一个完整的间隔时间来审查技能库、固定重要内容，或在 curator 真正触碰它之前完全退出。
|
||||
|
||||
如果你想在 curator 真正运行之前查看它*会*做什么，请运行 `hermes curator run --dry-run`——它会生成相同的审查报告，但不会修改技能库。
|
||||
:::
|
||||
|
||||
一次运行分为两个阶段：
|
||||
|
||||
1. **自动状态转换**（确定性，无 LLM）。未使用时间超过 `stale_after_days`（30 天）的技能变为 `stale`；未使用时间超过 `archive_after_days`（90 天）的技能被移至 `~/.hermes/skills/.archive/`。
|
||||
2. **LLM 审查**（单次辅助模型 pass，`max_iterations=8`）。派生的 agent 审查 agent 创建的技能，可通过 `skill_view` 读取任意技能，并逐技能决定是保留、修补（通过 `skill_manage`）、合并重叠项，还是通过终端工具归档。
|
||||
|
||||
已固定（pinned）的技能对 curator 的自动状态转换和 agent 自身的 `skill_manage` 工具均不可操作。详见下方[固定技能](#pinning-a-skill)。
|
||||
|
||||
## 配置
|
||||
|
||||
所有设置位于 `config.yaml` 的 `curator:` 下（不在 `.env` 中——这不是密钥）。默认值：
|
||||
|
||||
```yaml
|
||||
curator:
|
||||
enabled: true
|
||||
interval_hours: 168 # 7 days
|
||||
min_idle_hours: 2
|
||||
stale_after_days: 30
|
||||
archive_after_days: 90
|
||||
```
|
||||
|
||||
若要完全禁用，设置 `curator.enabled: false`。
|
||||
|
||||
### 在更便宜的辅助模型上运行审查
|
||||
|
||||
Curator 的 LLM 审查 pass 是一个常规辅助任务槽——`auxiliary.curator`——与 Vision、Compression、Session Search 等并列。"Auto" 表示"使用我的主聊天模型"；可覆盖该槽以为审查 pass 指定特定的 provider + model。
|
||||
|
||||
**最简单——`hermes model`：**
|
||||
|
||||
```bash
|
||||
hermes model # → "Auxiliary models — side-task routing"
|
||||
# → pick "Curator" → pick provider → pick model
|
||||
```
|
||||
|
||||
同样的选择器也可在 Web 控制台的 **Models** 标签页中使用。
|
||||
|
||||
**直接编辑 config.yaml（等效）：**
|
||||
|
||||
```yaml
|
||||
auxiliary:
|
||||
curator:
|
||||
provider: openrouter
|
||||
model: google/gemini-3-flash-preview
|
||||
timeout: 600 # generous — reviews can take several minutes
|
||||
```
|
||||
|
||||
保持 `provider: auto`（默认值）会将审查 pass 路由到主聊天模型，与所有其他辅助任务的行为一致。
|
||||
|
||||
:::note 旧版配置
|
||||
早期版本使用独立的 `curator.auxiliary.{provider,model}` 块。该路径仍然有效，但会输出一条弃用日志——请迁移到上方的 `auxiliary.curator`，使 curator 与其他所有辅助任务共享相同的管道（`hermes model`、控制台 Models 标签页、`base_url`、`api_key`、`timeout`、`extra_body`）。
|
||||
:::
|
||||
|
||||
## CLI
|
||||
|
||||
```bash
|
||||
hermes curator status # last run, counts, pinned list, LRU top 5
|
||||
hermes curator run # trigger a review now (blocks until the LLM pass finishes)
|
||||
hermes curator run --background # fire-and-forget: start the LLM pass in a background thread
|
||||
hermes curator run --dry-run # preview only — report without any mutations
|
||||
hermes curator backup # take a manual snapshot of ~/.hermes/skills/
|
||||
hermes curator rollback # restore from the newest snapshot
|
||||
hermes curator rollback --list # list available snapshots
|
||||
hermes curator rollback --id <ts> # restore a specific snapshot
|
||||
hermes curator rollback -y # skip the confirmation prompt
|
||||
hermes curator pause # stop runs until resumed
|
||||
hermes curator resume
|
||||
hermes curator pin <skill> # never auto-transition this skill
|
||||
hermes curator unpin <skill>
|
||||
hermes curator restore <skill> # move an archived skill back to active
|
||||
```
|
||||
|
||||
## 备份与回滚
|
||||
|
||||
在每次真正的 curator pass 之前，Hermes 会在 `~/.hermes/skills/.curator_backups/<utc-iso>/skills.tar.gz` 处对 `~/.hermes/skills/` 进行 tar.gz 快照。如果某次 pass 归档或合并了你不希望被触碰的内容，可以用一条命令撤销整次运行：
|
||||
|
||||
```bash
|
||||
hermes curator rollback # restore newest snapshot (with confirmation)
|
||||
hermes curator rollback -y # skip the prompt
|
||||
hermes curator rollback --list # see all snapshots with reason + size
|
||||
```
|
||||
|
||||
回滚本身也是可逆的：在替换技能树之前，Hermes 会再次创建一个标记为 `pre-rollback to <target-id>` 的快照，因此误操作的回滚可以通过 `--id` 滚动到该快照来撤销。
|
||||
|
||||
你也可以随时通过 `hermes curator backup --reason "before-refactor"` 手动创建快照。`--reason` 字符串会写入快照的 `manifest.json`，并在 `--list` 中显示。
|
||||
|
||||
快照会被裁剪至 `curator.backup.keep`（默认 5 个）以控制磁盘占用：
|
||||
|
||||
```yaml
|
||||
curator:
|
||||
backup:
|
||||
enabled: true
|
||||
keep: 5
|
||||
```
|
||||
|
||||
设置 `curator.backup.enabled: false` 可禁用自动快照。手动 `hermes curator backup` 命令仅在 `enabled: true` 时才能工作——该标志对两条路径对称生效，因此不会在变更性运行中意外跳过 pre-run 快照。
|
||||
|
||||
`hermes curator status` 还会列出五个最近最少使用的技能——快速查看哪些技能可能即将变为 stale。
|
||||
|
||||
相同的子命令也可作为 `/curator` 斜杠命令在运行中的会话（CLI 或 gateway 平台）内使用。
|
||||
|
||||
## "agent 创建"的含义
|
||||
|
||||
若技能名称**不在**以下列表中，则视为 agent 创建：
|
||||
|
||||
- `~/.hermes/skills/.bundled_manifest`（安装时从仓库复制的技能），以及
|
||||
- `~/.hermes/skills/.hub/lock.json`（通过 `hermes skills install` 安装的技能）。
|
||||
|
||||
`~/.hermes/skills/` 中的其他所有内容均在 curator 的处理范围内，包括：
|
||||
|
||||
- agent 在对话中通过 `skill_manage(action="create")` 保存的技能。
|
||||
- 你手动编写 `SKILL.md` 创建的技能。
|
||||
- 通过你指向 Hermes 的外部技能目录添加的技能。
|
||||
|
||||
:::warning 你手写的技能与 agent 保存的技能看起来完全相同
|
||||
此处的来源判断是**二元的**（捆绑/hub 与其他所有内容）。Curator 无法区分你依赖于私有工作流的手写技能与自我改进循环在会话中途保存的技能。两者都落入"agent 创建"的桶中。
|
||||
|
||||
在第一次真正运行之前（默认为安装后 7 天），请花时间：
|
||||
|
||||
1. 运行 `hermes curator run --dry-run` 查看 curator 具体会提出什么建议。
|
||||
2. 使用 `hermes curator pin <name>` 保护任何你不希望被触碰的内容。
|
||||
3. 或者在 `config.yaml` 中设置 `curator.enabled: false`，如果你更愿意自己管理技能库。
|
||||
|
||||
归档始终可通过 `hermes curator restore <name>` 恢复，但事先 pin 比事后追查合并结果要容易得多。
|
||||
:::
|
||||
|
||||
如果你想保护某个特定技能不被触碰——例如你依赖的手写技能——请使用 `hermes curator pin <name>`。详见下一节。
|
||||
|
||||
## 固定技能 {#pinning-a-skill}
|
||||
|
||||
固定（pinning）可保护技能不被删除——包括 curator 的自动归档 pass 和 agent 的 `skill_manage(action="delete")` 工具调用。技能一旦被固定：
|
||||
|
||||
- **Curator** 在自动状态转换（`active → stale → archived`）时跳过它，其 LLM 审查 pass 也被指示不予处理。
|
||||
- **Agent 的 `skill_manage` 工具**拒绝对其执行 `delete`，并提示用户使用 `hermes curator unpin <name>`。修补和编辑仍然可以进行，因此 agent 可以在遇到问题时改进已固定技能的内容，无需反复 pin/unpin/re-pin。
|
||||
|
||||
使用以下命令固定和取消固定：
|
||||
|
||||
```bash
|
||||
hermes curator pin <skill>
|
||||
hermes curator unpin <skill>
|
||||
```
|
||||
|
||||
该标志以 `"pinned": true` 的形式存储在 `~/.hermes/skills/.usage.json` 中技能对应的条目上，因此跨会话持久有效。
|
||||
|
||||
只有 **agent 创建**的技能才能被固定——捆绑和 hub 安装的技能本就不受 curator 变更，若你尝试固定它们，`hermes curator pin` 会拒绝并给出说明。
|
||||
|
||||
如果你想要比"禁止删除"更强的保证——例如在 agent 仍可读取技能的同时完全冻结其内容——请直接用编辑器编辑 `~/.hermes/skills/<name>/SKILL.md`。pin 保护的是工具驱动的删除，而非你自己的文件系统访问。
|
||||
|
||||
## 使用遥测
|
||||
|
||||
Curator 在 `~/.hermes/skills/.usage.json` 维护一个附属文件，每个技能对应一条记录：
|
||||
|
||||
```json
|
||||
{
|
||||
"my-skill": {
|
||||
"use_count": 12,
|
||||
"view_count": 34,
|
||||
"last_used_at": "2026-04-24T18:12:03Z",
|
||||
"last_viewed_at": "2026-04-23T09:44:17Z",
|
||||
"patch_count": 3,
|
||||
"last_patched_at": "2026-04-20T22:01:55Z",
|
||||
"created_at": "2026-03-01T14:20:00Z",
|
||||
"state": "active",
|
||||
"pinned": false,
|
||||
"archived_at": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
计数器在以下情况递增：
|
||||
|
||||
- `view_count`：agent 对该技能调用 `skill_view`。
|
||||
- `use_count`：技能被加载到对话的 prompt 中。
|
||||
- `patch_count`：对该技能执行 `skill_manage patch/edit/write_file/remove_file`。
|
||||
|
||||
捆绑和 hub 安装的技能被明确排除在遥测写入之外。
|
||||
|
||||
## 每次运行的报告
|
||||
|
||||
每次 curator 运行都会在 `~/.hermes/logs/curator/` 下写入一个带时间戳的目录：
|
||||
|
||||
```
|
||||
~/.hermes/logs/curator/
|
||||
└── 20260429-111512/
|
||||
├── run.json # machine-readable: full fidelity, stats, LLM output
|
||||
└── REPORT.md # human-readable summary
|
||||
```
|
||||
|
||||
`REPORT.md` 是快速查看某次运行所做操作的方式——哪些技能发生了状态转换、LLM 审查者说了什么、修补了哪些技能。无需 grep `agent.log` 即可完成审计。
|
||||
|
||||
### 摘要中的重命名映射
|
||||
|
||||
如果某次运行将多个技能合并到一个总括技能下（或合并了近似重复项），运行结束时打印的用户可见摘要会包含一个明确的重命名映射，显示 curator 应用的每个 `旧名称 → 新名称` 对。这是对逐技能状态转换行的补充，因此当一批重命名落地时，你可以一眼发现，无需对比 JSON 报告。该提示也会在 `hermes curator pin` 下显示，以便你在需要时立即固定新标签。
|
||||
|
||||
## 恢复已归档的技能
|
||||
|
||||
如果 curator 归档了你仍需要的技能：
|
||||
|
||||
```bash
|
||||
hermes curator restore <skill-name>
|
||||
```
|
||||
|
||||
这会将技能从 `~/.hermes/skills/.archive/` 移回活跃树，并将其状态重置为 `active`。如果此后有同名的捆绑或 hub 安装技能（会遮蔽上游），则恢复操作会被拒绝。
|
||||
|
||||
## 按环境禁用
|
||||
|
||||
Curator 默认开启。若要关闭：
|
||||
|
||||
- **仅针对某个 profile：** 编辑 `~/.hermes/config.yaml`（或当前活跃 profile 的配置），设置 `curator.enabled: false`。
|
||||
- **仅针对单次运行：** `hermes curator pause`——暂停跨会话持久有效；使用 `resume` 重新启用。
|
||||
|
||||
Curator 在 `min_idle_hours` 未经过时也会拒绝运行，因此在活跃的开发机器上，它自然只会在安静时段运行。
|
||||
|
||||
## 另请参阅
|
||||
|
||||
- [技能系统](/user-guide/features/skills)——技能的总体工作原理及创建技能的自我改进循环
|
||||
- [内存](/user-guide/features/memory)——维护长期记忆的并行后台审查
|
||||
- [捆绑技能目录](/reference/skills-catalog)
|
||||
- [Issue #7816](https://github.com/NousResearch/hermes-agent/issues/7816)——原始提案与设计讨论
|
||||
+290
@@ -0,0 +1,290 @@
|
||||
---
|
||||
sidebar_position: 7
|
||||
title: "子智能体委派"
|
||||
description: "使用 delegate_task 为并行工作流生成隔离的子智能体"
|
||||
---
|
||||
|
||||
# 子智能体委派
|
||||
|
||||
`delegate_task` 工具会生成具有隔离上下文、受限工具集和独立终端会话的子 AIAgent 实例。每个子智能体获得全新的对话并独立运行——只有其最终摘要会进入父智能体的上下文。
|
||||
|
||||
## 单任务
|
||||
|
||||
```python
|
||||
delegate_task(
|
||||
goal="Debug why tests fail",
|
||||
context="Error: assertion in test_foo.py line 42",
|
||||
toolsets=["terminal", "file"]
|
||||
)
|
||||
```
|
||||
|
||||
## 并行批处理
|
||||
|
||||
默认最多 3 个并发子智能体（可配置，无硬性上限）：
|
||||
|
||||
```python
|
||||
delegate_task(tasks=[
|
||||
{"goal": "Research topic A", "toolsets": ["web"]},
|
||||
{"goal": "Research topic B", "toolsets": ["web"]},
|
||||
{"goal": "Fix the build", "toolsets": ["terminal", "file"]}
|
||||
])
|
||||
```
|
||||
|
||||
## 子智能体上下文的工作方式
|
||||
|
||||
:::warning 关键：子智能体一无所知
|
||||
子智能体以**全新对话**启动。它们对父智能体的对话历史、之前的工具调用或委派前讨论的任何内容一无所知。子智能体的唯一上下文来自父智能体调用 `delegate_task` 时填写的 `goal` 和 `context` 字段。
|
||||
:::
|
||||
|
||||
这意味着父智能体必须在调用中传递子智能体所需的**一切**信息：
|
||||
|
||||
```python
|
||||
# BAD - subagent has no idea what "the error" is
|
||||
delegate_task(goal="Fix the error")
|
||||
|
||||
# GOOD - subagent has all context it needs
|
||||
delegate_task(
|
||||
goal="Fix the TypeError in api/handlers.py",
|
||||
context="""The file api/handlers.py has a TypeError on line 47:
|
||||
'NoneType' object has no attribute 'get'.
|
||||
The function process_request() receives a dict from parse_body(),
|
||||
but parse_body() returns None when Content-Type is missing.
|
||||
The project is at /home/user/myproject and uses Python 3.11."""
|
||||
)
|
||||
```
|
||||
|
||||
子智能体会收到一个基于你的 goal 和 context 构建的专注系统 prompt（提示词），指示其完成任务并提供结构化摘要，包括所做的事情、发现的内容、修改的文件以及遇到的问题。
|
||||
|
||||
## 实际示例
|
||||
|
||||
### 并行研究
|
||||
|
||||
同时研究多个主题并收集摘要：
|
||||
|
||||
```python
|
||||
delegate_task(tasks=[
|
||||
{
|
||||
"goal": "Research the current state of WebAssembly in 2025",
|
||||
"context": "Focus on: browser support, non-browser runtimes, language support",
|
||||
"toolsets": ["web"]
|
||||
},
|
||||
{
|
||||
"goal": "Research the current state of RISC-V adoption in 2025",
|
||||
"context": "Focus on: server chips, embedded systems, software ecosystem",
|
||||
"toolsets": ["web"]
|
||||
},
|
||||
{
|
||||
"goal": "Research quantum computing progress in 2025",
|
||||
"context": "Focus on: error correction breakthroughs, practical applications, key players",
|
||||
"toolsets": ["web"]
|
||||
}
|
||||
])
|
||||
```
|
||||
|
||||
### 代码审查 + 修复
|
||||
|
||||
将审查并修复的工作流委派给全新上下文：
|
||||
|
||||
```python
|
||||
delegate_task(
|
||||
goal="Review the authentication module for security issues and fix any found",
|
||||
context="""Project at /home/user/webapp.
|
||||
Auth module files: src/auth/login.py, src/auth/jwt.py, src/auth/middleware.py.
|
||||
The project uses Flask, PyJWT, and bcrypt.
|
||||
Focus on: SQL injection, JWT validation, password handling, session management.
|
||||
Fix any issues found and run the test suite (pytest tests/auth/).""",
|
||||
toolsets=["terminal", "file"]
|
||||
)
|
||||
```
|
||||
|
||||
### 多文件重构
|
||||
|
||||
将会大量占用父智能体上下文的大型重构任务委派出去：
|
||||
|
||||
```python
|
||||
delegate_task(
|
||||
goal="Refactor all Python files in src/ to replace print() with proper logging",
|
||||
context="""Project at /home/user/myproject.
|
||||
Use the 'logging' module with logger = logging.getLogger(__name__).
|
||||
Replace print() calls with appropriate log levels:
|
||||
- print(f"Error: ...") -> logger.error(...)
|
||||
- print(f"Warning: ...") -> logger.warning(...)
|
||||
- print(f"Debug: ...") -> logger.debug(...)
|
||||
- Other prints -> logger.info(...)
|
||||
Don't change print() in test files or CLI output.
|
||||
Run pytest after to verify nothing broke.""",
|
||||
toolsets=["terminal", "file"]
|
||||
)
|
||||
```
|
||||
|
||||
## 批处理模式详情
|
||||
|
||||
当你提供 `tasks` 数组时，子智能体会使用线程池**并行**运行：
|
||||
|
||||
- **最大并发数：** 默认 3 个任务（可通过 `delegation.max_concurrent_children` 或环境变量 `DELEGATION_MAX_CONCURRENT_CHILDREN` 配置；最低为 1，无硬性上限）。超出限制的批次会返回工具错误，而不是被静默截断。
|
||||
- **线程池：** 使用 `ThreadPoolExecutor`，以配置的并发限制作为最大工作线程数
|
||||
- **进度显示：** 在 CLI 模式下，树形视图会实时显示每个子智能体的工具调用，并附带每个任务的完成行。在 gateway 模式下，进度会被批量汇总并转发给父智能体的进度回调
|
||||
- **结果排序：** 结果按任务索引排序，与输入顺序一致，不受完成顺序影响
|
||||
- **中断传播：** 中断父智能体（例如发送新消息）会中断所有活跃的子智能体
|
||||
|
||||
单任务委派直接运行，无线程池开销。
|
||||
|
||||
## 模型覆盖
|
||||
|
||||
你可以通过 `config.yaml` 为子智能体配置不同的模型——适用于将简单任务委派给更便宜/更快的模型：
|
||||
|
||||
```yaml
|
||||
# In ~/.hermes/config.yaml
|
||||
delegation:
|
||||
model: "google/gemini-flash-2.0" # Cheaper model for subagents
|
||||
provider: "openrouter" # Optional: route subagents to a different provider
|
||||
```
|
||||
|
||||
如果省略，子智能体将使用与父智能体相同的模型。
|
||||
|
||||
## 工具集选择建议
|
||||
|
||||
`toolsets` 参数控制子智能体可以访问的工具。根据任务选择：
|
||||
|
||||
| 工具集模式 | 使用场景 |
|
||||
|----------------|----------|
|
||||
| `["terminal", "file"]` | 代码工作、调试、文件编辑、构建 |
|
||||
| `["web"]` | 研究、事实核查、文档查阅 |
|
||||
| `["terminal", "file", "web"]` | 全栈任务（默认） |
|
||||
| `["file"]` | 只读分析、无需执行的代码审查 |
|
||||
| `["terminal"]` | 系统管理、进程管理 |
|
||||
|
||||
无论你指定什么，某些工具集对子智能体始终被屏蔽：
|
||||
- `delegation` — 对叶子子智能体屏蔽（默认）。`role="orchestrator"` 的子智能体可保留，受 `max_spawn_depth` 约束——参见下方[深度限制与嵌套编排](#depth-limit-and-nested-orchestration)。
|
||||
- `clarify` — 子智能体无法与用户交互
|
||||
- `memory` — 不可写入共享持久内存
|
||||
- `code_execution` — 子智能体应逐步推理
|
||||
- `send_message` — 无跨平台副作用（例如发送 Telegram 消息）
|
||||
|
||||
## 最大迭代次数
|
||||
|
||||
每个子智能体都有迭代次数限制（默认：50），控制其可进行的工具调用轮次：
|
||||
|
||||
```python
|
||||
delegate_task(
|
||||
goal="Quick file check",
|
||||
context="Check if /etc/nginx/nginx.conf exists and print its first 10 lines",
|
||||
max_iterations=10 # Simple task, don't need many turns
|
||||
)
|
||||
```
|
||||
|
||||
## 子智能体超时
|
||||
|
||||
默认情况下，子智能体**没有挂钟超时限制**。子智能体只会因其实际执行的操作而失败——API 错误、工具错误或达到迭代预算上限——而不会被委派层面的计时器终止。早期版本曾设有硬性上限（300 秒，后为 600 秒），但这会在任务执行过程中误杀正常工作的子智能体：深度代码审查、大规模研究分发以及慢速推理模型经常需要超过 10 分钟，而它们全程都在稳定推进。
|
||||
|
||||
真正卡死的子智能体仍会被检测到：当子智能体没有任何进展（无 API 调用、无工具启动）时，心跳陈旧度监控会停止刷新父智能体的活动状态，从而让网关的不活动超时机制对真正卡死的工作进程生效。
|
||||
|
||||
如果仍需要硬性上限（例如对无人值守的 cron 驱动委派进行成本控制），可按安装实例选择启用：
|
||||
|
||||
```yaml
|
||||
delegation:
|
||||
child_timeout_seconds: 0 # 默认：0 = 无超时
|
||||
# child_timeout_seconds: 1800 # 选择启用的硬性上限（下限 30 秒）
|
||||
```
|
||||
|
||||
正值会对每个子智能体强制执行挂钟时间硬限制；`0` 或负值表示禁用。
|
||||
|
||||
:::tip 零调用超时时的诊断转储
|
||||
在配置了硬性上限的情况下，如果子智能体在**零次** API 调用的情况下超时（通常原因：provider 不可达、认证失败或工具 schema 被拒绝），`delegate_task` 会将结构化诊断信息写入 `~/.hermes/logs/subagent-timeout-<session>-<timestamp>.log`，其中包含子智能体的配置快照、凭据解析追踪以及早期错误消息。比之前的静默超时行为更易于定位根因。
|
||||
:::
|
||||
|
||||
## 监控运行中的子智能体（`/agents`）
|
||||
|
||||
TUI 提供 `/agents` 浮层（别名 `/tasks`），将递归 `delegate_task` 扇出转化为一级审计界面：
|
||||
|
||||
- 运行中和最近完成的子智能体的实时树形视图，按父智能体分组
|
||||
- 每个分支的费用、token 和已触及文件的汇总
|
||||
- 终止和暂停控制——可在不中断其兄弟智能体的情况下取消特定子智能体
|
||||
- 事后回顾：即使子智能体已返回父智能体，也可逐轮查看其历史记录
|
||||
|
||||
经典 CLI 仅将 `/agents` 打印为文本摘要；TUI 才是浮层真正发挥作用的地方。参见 [TUI — 斜杠命令](/user-guide/tui#slash-commands)。
|
||||
|
||||
## 深度限制与嵌套编排 {#depth-limit-and-nested-orchestration}
|
||||
|
||||
默认情况下，委派是**扁平的**：父智能体（深度 0）生成子智能体（深度 1），而这些子智能体无法进一步委派。这可防止失控的递归委派。
|
||||
|
||||
对于多阶段工作流（研究 → 综合，或对子问题进行并行编排），父智能体可以生成**编排者**子智能体，这些子智能体*可以*委派自己的工作线程：
|
||||
|
||||
```python
|
||||
delegate_task(
|
||||
goal="Survey three code review approaches and recommend one",
|
||||
role="orchestrator", # Allows this child to spawn its own workers
|
||||
context="...",
|
||||
)
|
||||
```
|
||||
|
||||
- `role="leaf"`（默认）：子智能体无法进一步委派——与扁平委派行为相同。
|
||||
- `role="orchestrator"`：子智能体保留 `delegation` 工具集。受 `delegation.max_spawn_depth` 约束（默认 **1** = 扁平，因此在默认设置下 `role="orchestrator"` 无效）。将 `max_spawn_depth` 提高到 2 可允许编排者子智能体生成叶子孙智能体；设为 3 则允许三层（上限）。
|
||||
- `delegation.orchestrator_enabled: false`：全局开关，无论 `role` 参数如何，强制所有子智能体为 `leaf`。
|
||||
|
||||
**费用警告：** 在 `max_spawn_depth: 3` 和 `max_concurrent_children: 3` 的情况下，树可达到 3×3×3 = 27 个并发叶子智能体。每增加一层都会成倍增加开销——请谨慎提高 `max_spawn_depth`。
|
||||
|
||||
## 生命周期与持久性
|
||||
|
||||
:::warning delegate_task 是同步的——不具备持久性
|
||||
`delegate_task` 在**父智能体的当前轮次内**运行。它会阻塞父智能体，直到所有子智能体完成（或被取消）。它**不是**后台任务队列：
|
||||
|
||||
- 如果父智能体被中断（用户发送新消息、`/stop`、`/new`），所有活跃的子智能体都会被取消并返回 `status="interrupted"`。其进行中的工作将被丢弃。
|
||||
- 子智能体在父智能体轮次结束后**不会**继续运行。
|
||||
- 被取消的子智能体会返回结构化结果（`status="interrupted"`，`exit_reason="interrupted"`），但由于父智能体也被中断，该结果通常不会出现在用户可见的回复中。
|
||||
|
||||
对于必须在中断后存活或超出当前轮次的**持久长时间运行工作**，请使用：
|
||||
|
||||
- `cronjob`（action=`create`）——调度独立的智能体运行；不受父智能体轮次中断影响。
|
||||
- `terminal(background=True, notify_on_complete=True)`——长时间运行的 shell 命令，在智能体执行其他操作时持续运行。
|
||||
:::
|
||||
|
||||
## 关键特性
|
||||
|
||||
- 每个子智能体获得其**独立的终端会话**（与父智能体分离）
|
||||
- **嵌套委派为可选项**——只有 `role="orchestrator"` 的子智能体可以进一步委派，且仅在 `max_spawn_depth` 从默认值 1（扁平）提高后才生效。可通过 `orchestrator_enabled: false` 全局禁用。
|
||||
- 叶子子智能体**不能**调用：`delegate_task`、`clarify`、`memory`、`send_message`、`execute_code`。编排者子智能体保留 `delegate_task`，但仍不能使用其他四个。
|
||||
- **中断传播**——中断父智能体会中断所有活跃的子智能体（包括编排者下的孙智能体）
|
||||
- 只有最终摘要进入父智能体的上下文，保持 token 使用高效
|
||||
- 子智能体继承父智能体的 **API 密钥、provider 配置和凭据池**（支持在速率限制时轮换密钥）
|
||||
|
||||
## delegate_task 与 execute_code 对比
|
||||
|
||||
| 因素 | delegate_task | execute_code |
|
||||
|--------|--------------|-------------|
|
||||
| **推理** | 完整 LLM 推理循环 | 仅 Python 代码执行 |
|
||||
| **上下文** | 全新隔离对话 | 无对话，仅脚本 |
|
||||
| **工具访问** | 所有非屏蔽工具，具备推理能力 | 通过 RPC 访问 7 个工具，无推理 |
|
||||
| **并行性** | 默认 3 个并发子智能体（可配置） | 单脚本 |
|
||||
| **最适合** | 需要判断力的复杂任务 | 机械式多步骤流水线 |
|
||||
| **Token 费用** | 较高（完整 LLM 循环） | 较低（仅返回 stdout） |
|
||||
| **用户交互** | 无（子智能体无法澄清） | 无 |
|
||||
|
||||
**经验法则：** 当子任务需要推理、判断或多步骤问题解决时，使用 `delegate_task`。当需要机械式数据处理或脚本化工作流时，使用 `execute_code`。
|
||||
|
||||
## 配置
|
||||
|
||||
```yaml
|
||||
# In ~/.hermes/config.yaml
|
||||
delegation:
|
||||
max_iterations: 50 # Max turns per child (default: 50)
|
||||
# max_concurrent_children: 3 # Parallel children per batch (default: 3)
|
||||
# max_spawn_depth: 1 # Tree depth (1-3, default 1 = flat). Raise to 2 to allow orchestrator children to spawn leaves; 3 for three levels.
|
||||
# orchestrator_enabled: true # Disable to force all children to leaf role.
|
||||
model: "google/gemini-3-flash-preview" # Optional provider/model override
|
||||
provider: "openrouter" # Optional built-in provider
|
||||
api_mode: anthropic_messages # optional; auto-detected from base_url for anthropic_messages endpoints
|
||||
|
||||
# Or use a direct custom endpoint instead of provider:
|
||||
delegation:
|
||||
model: "qwen2.5-coder"
|
||||
base_url: "http://localhost:1234/v1"
|
||||
api_key: "local-key"
|
||||
# api_mode: "anthropic_messages" # Optional. Wire protocol override for base_url ("chat_completions", "codex_responses", or "anthropic_messages"). Empty = auto-detect from URL (e.g. /anthropic suffix). Set explicitly for endpoints the heuristic can't classify (Azure AI Foundry, MiniMax, Zhipu GLM, LiteLLM proxies, …).
|
||||
```
|
||||
|
||||
当 `base_url` 指向 Anthropic 兼容端点时——例如路径以 `/anthropic` 结尾、Azure Foundry Claude 路由或 MiniMax `/anthropic` 代理——`api_mode` 会被自动检测为 `anthropic_messages`，子智能体无需任何配置即可使用正确的传输格式。当自动检测结果有误时（罕见），请显式设置 `api_mode`。
|
||||
|
||||
:::tip
|
||||
智能体会根据任务复杂度自动处理委派。你无需明确要求它进行委派——它会在合适时自行决定。
|
||||
:::
|
||||
+91
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: 可交付成果模式（聊天中的 Artifacts）
|
||||
sidebar_label: 可交付成果模式
|
||||
description: Agent 如何将生成的图表、PDF、电子表格及其他文件作为原生附件发送到消息平台。
|
||||
---
|
||||
|
||||
# 可交付成果模式
|
||||
|
||||
当 Hermes Agent 在消息 gateway（Slack、Discord、Telegram、WhatsApp、Signal 等）中运行时，它可以将生成的文件直接发送到聊天中——不是让用户自行复制路径，而是作为原生附件。
|
||||
|
||||
图表以内联图片形式显示。PDF 报告以文件下载形式显示。电子表格以 `.xlsx` 格式上传。Agent 无需写入 `MEDIA:` 标签或进行任何特殊操作——只需生成文件并在回复中提及其绝对路径。Gateway 会从文本中提取路径，将其从可见消息中移除，并原生上传文件。
|
||||
|
||||
## 工作原理
|
||||
|
||||
三个部分协同配合：
|
||||
|
||||
1. **Agent 拥有可生成文件的工具。** `execute_code` 用于通过 matplotlib 生成图表，`latex-pdf-report` skill 用于生成 PDF，`powerpoint` skill 用于生成演示文稿，`image_generate` 用于生成图片，`text_to_speech` 用于生成音频，等等。
|
||||
|
||||
2. **Gateway 扫描 agent 回复中的文件路径。** 任何以支持扩展名结尾的绝对路径（`/tmp/...`）或相对主目录路径（`~/...`）都会被提取。代码块和内联代码中的路径会被忽略，以避免代码示例被破坏。
|
||||
|
||||
3. **Gateway 按文件类型分发。** 在平台支持的情况下，图片以内联方式嵌入；视频以内联方式嵌入；音频路由至语音/音频附件；其他所有内容作为文件附件上传。
|
||||
|
||||
## 支持的文件扩展名
|
||||
|
||||
| 类别 | 扩展名 | 发送方式 |
|
||||
|---|---|---|
|
||||
| 图片 | `.png .jpg .jpeg .gif .webp .bmp .tiff .svg` | 内联嵌入 |
|
||||
| 视频 | `.mp4 .mov .avi .mkv .webm` | 内联嵌入（平台支持时） |
|
||||
| 音频 | `.mp3 .wav .ogg .m4a .flac` | 语音/音频附件 |
|
||||
| 文档 | `.pdf .docx .doc .odt .rtf .txt .md` | 文件上传 |
|
||||
| 数据 | `.xlsx .xls .csv .tsv .json .xml .yaml .yml` | 文件上传 |
|
||||
| 演示文稿 | `.pptx .ppt .odp` | 文件上传 |
|
||||
| 压缩包 | `.zip .tar .gz .tgz .bz2 .7z` | 文件上传 |
|
||||
| Web | `.html .htm` | 文件上传 |
|
||||
|
||||
`.py`、`.log` 及其他源文件扩展名被有意排除，以防 agent 自动发送任意源文件；如需向用户发送代码，请使用代码块。
|
||||
|
||||
## 引导 Agent 生成 Artifacts
|
||||
|
||||
Agent 默认不会主动生成 artifacts——需要明确告知。有两种方式：
|
||||
|
||||
**单次会话：** 明确提出请求（"以图表形式发给我对比结果"、"将数据以 CSV 格式返回"），或编写自定义指令/个性化条目，使其在消息平台上倾向于以 artifact 形式回复。
|
||||
|
||||
**项目级别：** 将偏好设置添加到项目中的 `AGENTS.md` / `CLAUDE.md` / `.cursorrules`（agent 从该项目工作），或添加到 `~/.hermes/config.yaml` 中 `agent.custom_instructions` 下的全局自定义指令。
|
||||
|
||||
Agent 需要使用的机制很简单：将文件渲染到绝对路径（例如 `/tmp/q3-revenue.png`），并在回复中以纯文本形式提及该路径。Gateway 负责其余工作。围栏代码块或反引号中的路径会被忽略，以避免代码示例被破坏。
|
||||
|
||||
## Kanban：Artifacts 随完成通知一并发送
|
||||
|
||||
如果使用 Hermes 的 kanban（看板）多 agent 工作流，worker 可以在调用 `kanban_complete` 时附加可交付文件：
|
||||
|
||||
```python
|
||||
kanban_complete(
|
||||
summary="rendered Q3 revenue chart and report",
|
||||
artifacts=[
|
||||
"/tmp/q3-revenue.png",
|
||||
"/tmp/q3-report.pdf",
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
当 gateway 通知器将"任务完成"消息发送给在 Slack/Telegram 等平台订阅该任务的用户时，也会将每个 artifact 作为原生附件上传到对应聊天中。用户在同一位置获得可交付成果和摘要。
|
||||
|
||||
通知器运行时磁盘上不存在的文件会被静默跳过。
|
||||
|
||||
## 通过 MCP 连接更多服务
|
||||
|
||||
除 artifact 发送管道外，agent 还可以通过 MCP（Model Context Protocol，模型上下文协议）接入其他服务。MCP 生态系统为大多数主流工具提供了社区服务器——按需安装：
|
||||
|
||||
| 服务 | 解锁功能 |
|
||||
|---|---|
|
||||
| **Notion** | 读写 Notion 页面、数据库，查询工作区 |
|
||||
| **GitHub** | Issues、PR、评论、超出 gh CLI 范围的仓库搜索 |
|
||||
| **Linear** | 工单、项目、迭代周期 |
|
||||
| **Slack** | 工作区全局搜索、读取其他频道 |
|
||||
| **Gmail** | 收件箱整理、发送邮件、标签管理 |
|
||||
| **Salesforce** | 线索、商机、账户数据 |
|
||||
| **Snowflake / BigQuery** | 对数据仓库执行 SQL |
|
||||
| **Google Drive** | 文件搜索、内容读取、共享管理 |
|
||||
|
||||
通过 `~/.hermes/config.yaml` 中的 `mcp_servers` 部分安装 MCP 服务器。完整配置指南请参阅 [MCP 集成](./mcp.md)。
|
||||
|
||||
## 与 Perplexity Computer in Slack 的对比
|
||||
|
||||
Perplexity Computer 的 Slack 集成基于相同理念：agent 生成可交付成果（图表、PDF、幻灯片），并将其作为原生附件发回线程。Hermes Agent 的可交付成果模式在本地提供相同的用户体验：
|
||||
|
||||
- 生成在用户自己的 venv/沙箱中进行（无远程租户）。
|
||||
- 文件通过相同的 Slack `files.uploadV2` API 发送到聊天。
|
||||
- 连接器广度通过 MCP 实现，而非精心策划的 400 个托管集成目录——按需安装所需的即可。
|
||||
|
||||
OAuth token 保存在用户本机的 `auth.json` / `.env` 中。无托管 token 存储。无多租户 microVM。最终效果相同。
|
||||
+907
@@ -0,0 +1,907 @@
|
||||
---
|
||||
sidebar_position: 17
|
||||
title: "扩展 Dashboard"
|
||||
description: "为 Hermes Web Dashboard 构建主题和插件——调色板、字体排版、布局、自定义标签页、shell 插槽、页面级插槽以及后端 API 路由"
|
||||
---
|
||||
|
||||
# 扩展 Dashboard
|
||||
|
||||
Hermes Web Dashboard（`hermes dashboard`）在设计上支持换肤和扩展，无需 fork 代码库。对外暴露三个层次：
|
||||
|
||||
1. **主题（Themes）** — YAML 文件，用于重绘 dashboard 的调色板、字体排版、布局以及各组件的外观。将文件放入 `~/.hermes/dashboard-themes/`，即可在主题切换器中看到它。
|
||||
2. **UI 插件（UI plugins）** — 一个包含 `manifest.json` 和 JavaScript bundle 的目录，可注册标签页、替换内置页面、通过页面级插槽增强内置页面，或向命名 shell 插槽注入组件。
|
||||
3. **后端插件（Backend plugins）** — 插件目录内的 Python 文件，暴露一个 FastAPI `router`；路由挂载在 `/api/plugins/<name>/` 下，由插件的 UI 调用。
|
||||
|
||||
三者均为**运行时即插即用**：无需克隆仓库、无需 `npm run build`、无需修改 dashboard 源码。本页是三者的权威参考文档。
|
||||
|
||||
如果只是想使用 dashboard，请参阅 [Web Dashboard](./web-dashboard)。如果想为终端 CLI（而非 Web Dashboard）换肤，请参阅 [Skins & Themes](./skins) —— CLI 皮肤系统与 dashboard 主题无关。
|
||||
|
||||
:::note 各部分如何组合
|
||||
主题和插件相互独立，但可协同工作。主题可以单独使用（仅一个 YAML 文件）。插件也可以单独使用（仅一个标签页）。两者结合可构建带有自定义 HUD 的完整视觉换肤方案——内置的 `strike-freedom-cockpit` 演示正是如此。参见[主题 + 插件组合演示](#combined-theme--plugin-demo)。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
- [主题](#themes)
|
||||
- [快速上手——你的第一个主题](#quick-start--your-first-theme)
|
||||
- [调色板、字体排版、布局](#palette-typography-layout)
|
||||
- [布局变体](#layout-variants)
|
||||
- [主题资源（图片作为 CSS 变量）](#theme-assets-images-as-css-vars)
|
||||
- [组件外观覆盖](#component-chrome-overrides)
|
||||
- [颜色覆盖](#color-overrides)
|
||||
- [原始 `customCSS`](#raw-customcss)
|
||||
- [内置主题](#built-in-themes)
|
||||
- [完整主题 YAML 参考](#full-theme-yaml-reference)
|
||||
- [插件](#plugins)
|
||||
- [快速上手——你的第一个插件](#quick-start--your-first-plugin)
|
||||
- [目录结构](#directory-layout)
|
||||
- [Manifest 参考](#manifest-reference)
|
||||
- [Plugin SDK](#the-plugin-sdk)
|
||||
- [Shell 插槽](#shell-slots)
|
||||
- [替换内置页面（`tab.override`）](#replacing-built-in-pages-taboverride)
|
||||
- [增强内置页面（页面级插槽）](#augmenting-built-in-pages-page-scoped-slots)
|
||||
- [仅插槽插件（`tab.hidden`）](#slot-only-plugins-tabhidden)
|
||||
- [后端 API 路由](#backend-api-routes)
|
||||
- [插件自定义 CSS](#custom-css-per-plugin)
|
||||
- [插件发现与重载](#plugin-discovery--reload)
|
||||
- [主题 + 插件组合演示](#combined-theme--plugin-demo)
|
||||
- [API 参考](#api-reference)
|
||||
- [故障排查](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## 主题
|
||||
|
||||
主题是存储在 `~/.hermes/dashboard-themes/` 中的 YAML 文件。文件名无关紧要（系统使用主题的 `name:` 字段），但惯例是 `<name>.yaml`。所有字段均为可选——缺失的键会回退到内置的 `default` 主题，因此一个主题可以只包含一个颜色。
|
||||
|
||||
### 快速上手——你的第一个主题
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.hermes/dashboard-themes
|
||||
```
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/dashboard-themes/neon.yaml
|
||||
name: neon
|
||||
label: Neon
|
||||
description: Pure magenta on black
|
||||
|
||||
palette:
|
||||
background: "#000000"
|
||||
midground: "#ff00ff"
|
||||
```
|
||||
|
||||
刷新 dashboard。点击顶栏的调色板图标，选择 **Neon**。背景变为黑色，文字和强调色变为洋红色，所有派生颜色（card、border、muted、ring 等）均通过 CSS 的 `color-mix()` 从这两个颜色自动计算得出。
|
||||
|
||||
这就是全部入门流程：一个文件，两个颜色。以下内容均为可选的进阶配置。
|
||||
|
||||
### 调色板、字体排版、布局
|
||||
|
||||
这三个块是主题的核心。每个块相互独立——覆盖其中一个，其余保持不变。
|
||||
|
||||
#### 调色板（3 层）
|
||||
|
||||
调色板由三层颜色加一个暖光晕（warm-glow）颜色和一个噪点颗粒倍增器组成。Dashboard 的设计系统级联通过 CSS `color-mix()` 从这三层颜色派生出所有兼容 shadcn 的 token（card、popover、muted、border、primary、destructive、ring 等）。覆盖三个颜色即可级联影响整个 UI。
|
||||
|
||||
| 键 | 描述 |
|
||||
|-----|-------------|
|
||||
| `palette.background` | 最深的画布颜色——通常接近黑色。驱动页面背景和卡片填充。 |
|
||||
| `palette.midground` | 主要文字和强调色。大多数 UI 外观读取此值（前景文字、按钮轮廓、焦点环）。 |
|
||||
| `palette.foreground` | 顶层高亮色。默认主题将其设为 alpha 为 0 的白色（不可见）；需要顶层亮色强调的主题可提高其 alpha 值。 |
|
||||
| `palette.warmGlow` | `rgba(...)` 字符串，用作 `<Backdrop />` 的晕光颜色。 |
|
||||
| `palette.noiseOpacity` | 0–1.2 的颗粒叠加层倍增器。越低越柔和，越高越粗粝。 |
|
||||
|
||||
每层接受 `{hex: "#RRGGBB", alpha: 0.0–1.0}` 或裸十六进制字符串（alpha 默认为 1.0）。
|
||||
|
||||
```yaml
|
||||
palette:
|
||||
background:
|
||||
hex: "#05091a"
|
||||
alpha: 1.0
|
||||
midground: "#d8f0ff" # bare hex, alpha = 1.0
|
||||
foreground:
|
||||
hex: "#ffffff"
|
||||
alpha: 0 # invisible top layer
|
||||
warmGlow: "rgba(255, 199, 55, 0.24)"
|
||||
noiseOpacity: 0.7
|
||||
```
|
||||
|
||||
#### 字体排版
|
||||
|
||||
| 键 | 类型 | 描述 |
|
||||
|-----|------|-------------|
|
||||
| `fontSans` | string | 正文的 CSS font-family 栈（应用于 `html`、`body`）。 |
|
||||
| `fontMono` | string | 代码块、`<code>`、`.font-mono` 工具类的 CSS font-family 栈。 |
|
||||
| `fontDisplay` | string | 可选的标题/展示字体栈。回退到 `fontSans`。 |
|
||||
| `fontUrl` | string | 可选的外部样式表 URL。在主题切换时以 `<link rel="stylesheet">` 注入 `<head>`。相同 URL 不会重复注入。支持 Google Fonts、Bunny Fonts、自托管 `@font-face` 样式表——任何可链接的资源均可。 |
|
||||
| `baseSize` | string | 根字体大小——控制 rem 比例。例如 `"14px"`、`"16px"`。 |
|
||||
| `lineHeight` | string | 默认行高。例如 `"1.5"`、`"1.65"`。 |
|
||||
| `letterSpacing` | string | 默认字间距。例如 `"0"`、`"0.01em"`、`"-0.01em"`。 |
|
||||
|
||||
```yaml
|
||||
typography:
|
||||
fontSans: '"Orbitron", "Eurostile", "Impact", sans-serif'
|
||||
fontMono: '"Share Tech Mono", ui-monospace, monospace'
|
||||
fontDisplay: '"Orbitron", "Eurostile", sans-serif'
|
||||
fontUrl: "https://fonts.googleapis.com/css2?family=Orbitron:wght@400;500;600;700&family=Share+Tech+Mono&display=swap"
|
||||
baseSize: "14px"
|
||||
lineHeight: "1.5"
|
||||
letterSpacing: "0.04em"
|
||||
```
|
||||
|
||||
#### 布局
|
||||
|
||||
| 键 | 值 | 描述 |
|
||||
|-----|--------|-------------|
|
||||
| `radius` | 任意 CSS 长度（`"0"`、`"0.25rem"`、`"0.5rem"`、`"1rem"` 等） | 圆角 token。映射到 `--radius` 并级联到 `--radius-sm/md/lg/xl`——所有圆角元素同步变化。 |
|
||||
| `density` | `compact` \| `comfortable` \| `spacious` | 间距倍增器，以 `--spacing-mul` CSS 变量形式应用。`compact = 0.85×`，`comfortable = 1.0×`（默认），`spacious = 1.2×`。缩放 Tailwind 的基础间距，因此 padding、gap 和 space-between 工具类均按比例调整。 |
|
||||
|
||||
```yaml
|
||||
layout:
|
||||
radius: "0"
|
||||
density: compact
|
||||
```
|
||||
|
||||
### 布局变体
|
||||
|
||||
`layoutVariant` 选择整体 shell 布局。缺省时默认为 `"standard"`。
|
||||
|
||||
| 变体 | 行为 |
|
||||
|---------|-----------|
|
||||
| `standard` | 单列，最大宽度 1600px（默认）。 |
|
||||
| `cockpit` | 左侧边栏轨道（260px）+ 主内容区。由插件通过 `sidebar` 插槽填充——参见 [Shell 插槽](#shell-slots)。没有插件时轨道显示占位符。 |
|
||||
| `tiled` | 取消最大宽度限制，页面可使用完整视口宽度。 |
|
||||
|
||||
```yaml
|
||||
layoutVariant: cockpit
|
||||
```
|
||||
|
||||
当前变体通过 `document.documentElement.dataset.layoutVariant` 暴露，因此 `customCSS` 中的原始 CSS 可通过 `:root[data-layout-variant="cockpit"] ...` 定向匹配。
|
||||
|
||||
### 主题资源（图片作为 CSS 变量）
|
||||
|
||||
随主题附带图片 URL。每个命名插槽会成为一个 CSS 变量（`--theme-asset-<name>`），内置 shell 和任何插件均可读取。`bg` 插槽自动接入 backdrop；其他插槽面向插件开放。
|
||||
|
||||
```yaml
|
||||
assets:
|
||||
bg: "https://example.com/hero-bg.jpg" # auto-wired into <Backdrop />
|
||||
hero: "/my-images/strike-freedom.png" # for plugin sidebars
|
||||
crest: "/my-images/crest.svg" # for header-left plugins
|
||||
logo: "/my-images/logo.png"
|
||||
sidebar: "/my-images/rail.png"
|
||||
header: "/my-images/header-art.png"
|
||||
custom:
|
||||
scanLines: "/my-images/scanlines.png" # → --theme-asset-custom-scanLines
|
||||
```
|
||||
|
||||
值接受：
|
||||
|
||||
- 裸 URL——自动包装为 `url(...)`。
|
||||
- 已包装的 `url(...)`、`linear-gradient(...)`、`radial-gradient(...)` 表达式——直接使用。
|
||||
- `"none"` ——明确禁用。
|
||||
|
||||
每个资源还会以 `--theme-asset-<name>-raw`（未包装的 URL）形式输出，以便插件需要将其传给 `<img src>` 而非 `background-image` 时使用。
|
||||
|
||||
插件通过普通 CSS 或 JS 读取这些变量：
|
||||
|
||||
```javascript
|
||||
// In a plugin slot
|
||||
const hero = getComputedStyle(document.documentElement)
|
||||
.getPropertyValue("--theme-asset-hero").trim();
|
||||
```
|
||||
|
||||
### 组件外观覆盖
|
||||
|
||||
`componentStyles` 可在不编写 CSS 选择器的情况下重新设置各 shell 组件的样式。每个桶（bucket）的条目会成为 CSS 变量（`--component-<bucket>-<kebab-property>`），shell 的共享组件会读取这些变量。因此 `card:` 的覆盖应用于所有 `<Card>`，`header:` 应用于应用栏，以此类推。
|
||||
|
||||
```yaml
|
||||
componentStyles:
|
||||
card:
|
||||
clipPath: "polygon(12px 0, 100% 0, 100% calc(100% - 12px), calc(100% - 12px) 100%, 0 100%, 0 12px)"
|
||||
background: "linear-gradient(180deg, rgba(10, 22, 52, 0.85), rgba(5, 9, 26, 0.92))"
|
||||
boxShadow: "inset 0 0 0 1px rgba(64, 200, 255, 0.28)"
|
||||
header:
|
||||
background: "linear-gradient(180deg, rgba(16, 32, 72, 0.95), rgba(5, 9, 26, 0.9))"
|
||||
tab:
|
||||
clipPath: "polygon(6px 0, 100% 0, calc(100% - 6px) 100%, 0 100%)"
|
||||
sidebar: {}
|
||||
backdrop: {}
|
||||
footer: {}
|
||||
progress: {}
|
||||
badge: {}
|
||||
page: {}
|
||||
```
|
||||
|
||||
支持的桶：`card`、`header`、`footer`、`sidebar`、`tab`、`progress`、`badge`、`backdrop`、`page`。
|
||||
|
||||
属性名使用 camelCase（`clipPath`），输出为 kebab-case（`clip-path`）。值为纯 CSS 字符串——CSS 接受的任何内容均可（`clip-path`、`border-image`、`background`、`box-shadow`、`animation` 等）。
|
||||
|
||||
### 颜色覆盖
|
||||
|
||||
大多数主题不需要此功能——3 层调色板已派生出所有 shadcn token。当你需要派生无法产生的特定强调色时（例如柔和主题的更柔和的破坏性红色，或品牌专属的成功绿色），才使用 `colorOverrides`。
|
||||
|
||||
```yaml
|
||||
colorOverrides:
|
||||
primary: "#ffce3a"
|
||||
primaryForeground: "#05091a"
|
||||
accent: "#3fd3ff"
|
||||
ring: "#3fd3ff"
|
||||
destructive: "#ff3a5e"
|
||||
border: "rgba(64, 200, 255, 0.28)"
|
||||
```
|
||||
|
||||
支持的键：`card`、`cardForeground`、`popover`、`popoverForeground`、`primary`、`primaryForeground`、`secondary`、`secondaryForeground`、`muted`、`mutedForeground`、`accent`、`accentForeground`、`destructive`、`destructiveForeground`、`success`、`warning`、`border`、`input`、`ring`。
|
||||
|
||||
每个键与 `--color-<kebab>` CSS 变量一一对应（例如 `primaryForeground` → `--color-primary-foreground`）。此处设置的任何键仅对当前激活主题生效，切换到其他主题时覆盖会被清除。
|
||||
|
||||
### 原始 `customCSS`
|
||||
|
||||
对于 `componentStyles` 无法表达的选择器级外观——伪元素、动画、媒体查询、主题范围内的覆盖——可将原始 CSS 写入 `customCSS`：
|
||||
|
||||
```yaml
|
||||
customCSS: |
|
||||
/* Scanline overlay — only visible when cockpit variant is active. */
|
||||
:root[data-layout-variant="cockpit"] body::before {
|
||||
content: "";
|
||||
position: fixed;
|
||||
inset: 0;
|
||||
pointer-events: none;
|
||||
z-index: 100;
|
||||
background: repeating-linear-gradient(to bottom,
|
||||
transparent 0px, transparent 2px,
|
||||
rgba(64, 200, 255, 0.035) 3px, rgba(64, 200, 255, 0.035) 4px);
|
||||
mix-blend-mode: screen;
|
||||
}
|
||||
```
|
||||
|
||||
CSS 在主题应用时以单个带作用域的 `<style data-hermes-theme-css>` 标签注入，主题切换时清除。**每个主题上限为 32 KiB。**
|
||||
|
||||
### 内置主题
|
||||
|
||||
每个内置主题都有自己的调色板、字体排版和布局——切换时产生的变化不仅限于颜色。
|
||||
|
||||
| 主题 | 调色板 | 字体排版 | 布局 |
|
||||
|-------|---------|------------|--------|
|
||||
| **Hermes Teal**（`default`） | 深青色 + 奶油色 | 系统字体栈，15px | 0.5rem 圆角，comfortable |
|
||||
| **Hermes Teal (Large)**（`default-large`） | 同 default | 系统字体栈，18px，行高 1.65 | 0.5rem 圆角，spacious |
|
||||
| **Midnight**（`midnight`） | 深蓝紫色 | Inter + JetBrains Mono，14px | 0.75rem 圆角，comfortable |
|
||||
| **Ember**（`ember`） | 暖深红 + 古铜色 | Spectral（衬线）+ IBM Plex Mono，15px | 0.25rem 圆角，comfortable |
|
||||
| **Mono**（`mono`） | 灰度 | IBM Plex Sans + IBM Plex Mono，13px | 0 圆角，compact |
|
||||
| **Cyberpunk**（`cyberpunk`） | 黑底霓虹绿 | Share Tech Mono 全局，14px | 0 圆角，compact |
|
||||
| **Rosé**（`rose`） | 粉色 + 象牙色 | Fraunces（衬线）+ DM Mono，16px | 1rem 圆角，spacious |
|
||||
|
||||
引用 Google Fonts 的主题（除 Hermes Teal 外均如此）会按需加载样式表——首次切换时会向 `<head>` 注入一个 `<link>` 标签。
|
||||
|
||||
### 完整主题 YAML 参考
|
||||
|
||||
所有配置项汇总在一个文件中——复制后删除不需要的部分：
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/dashboard-themes/ocean.yaml
|
||||
name: ocean
|
||||
label: Ocean Deep
|
||||
description: Deep sea blues with coral accents
|
||||
|
||||
# 3-layer palette (accepts {hex, alpha} or bare hex)
|
||||
palette:
|
||||
background:
|
||||
hex: "#0a1628"
|
||||
alpha: 1.0
|
||||
midground:
|
||||
hex: "#a8d0ff"
|
||||
alpha: 1.0
|
||||
foreground:
|
||||
hex: "#ffffff"
|
||||
alpha: 0.0
|
||||
warmGlow: "rgba(255, 107, 107, 0.35)"
|
||||
noiseOpacity: 0.7
|
||||
|
||||
typography:
|
||||
fontSans: "Poppins, system-ui, sans-serif"
|
||||
fontMono: "Fira Code, ui-monospace, monospace"
|
||||
fontDisplay: "Poppins, system-ui, sans-serif" # optional
|
||||
fontUrl: "https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600&family=Fira+Code:wght@400;500&display=swap"
|
||||
baseSize: "15px"
|
||||
lineHeight: "1.6"
|
||||
letterSpacing: "-0.003em"
|
||||
|
||||
layout:
|
||||
radius: "0.75rem"
|
||||
density: comfortable
|
||||
|
||||
layoutVariant: standard # standard | cockpit | tiled
|
||||
|
||||
assets:
|
||||
bg: "https://example.com/ocean-bg.jpg"
|
||||
hero: "/my-images/kraken.png"
|
||||
crest: "/my-images/anchor.svg"
|
||||
logo: "/my-images/logo.png"
|
||||
custom:
|
||||
pattern: "/my-images/waves.svg"
|
||||
|
||||
componentStyles:
|
||||
card:
|
||||
boxShadow: "inset 0 0 0 1px rgba(168, 208, 255, 0.18)"
|
||||
header:
|
||||
background: "linear-gradient(180deg, rgba(10, 22, 40, 0.95), rgba(5, 9, 26, 0.9))"
|
||||
|
||||
colorOverrides:
|
||||
destructive: "#ff6b6b"
|
||||
ring: "#ff6b6b"
|
||||
|
||||
customCSS: |
|
||||
/* Any additional selector-level tweaks */
|
||||
```
|
||||
|
||||
创建文件后刷新 dashboard。通过顶栏的调色板图标实时切换主题。选择结果会持久化到 `config.yaml` 的 `dashboard.theme` 下，并在重载时恢复。
|
||||
|
||||
---
|
||||
|
||||
## 插件
|
||||
|
||||
Dashboard 插件是一个包含 `manifest.json`、预构建 JS bundle，以及可选的 CSS 文件和带 FastAPI 路由的 Python 文件的目录。插件与其他 Hermes 插件一起存放在 `~/.hermes/plugins/<name>/`——dashboard 扩展是该插件目录内的 `dashboard/` 子文件夹，因此一个插件可以从单次安装中同时扩展 CLI/gateway 和 dashboard。
|
||||
|
||||
插件不打包 React 或 UI 组件，而是使用暴露在 `window.__HERMES_PLUGIN_SDK__` 上的 **Plugin SDK**。这使插件 bundle 保持极小体积（通常只有几 KB），并避免版本冲突。
|
||||
|
||||
### 快速上手——你的第一个插件
|
||||
|
||||
创建目录结构：
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.hermes/plugins/my-plugin/dashboard/dist
|
||||
```
|
||||
|
||||
编写 manifest：
|
||||
|
||||
```json
|
||||
// ~/.hermes/plugins/my-plugin/dashboard/manifest.json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"label": "My Plugin",
|
||||
"icon": "Sparkles",
|
||||
"version": "1.0.0",
|
||||
"tab": {
|
||||
"path": "/my-plugin",
|
||||
"position": "after:skills"
|
||||
},
|
||||
"entry": "dist/index.js"
|
||||
}
|
||||
```
|
||||
|
||||
编写 JS bundle（普通 IIFE——无需构建步骤）：
|
||||
|
||||
```javascript
|
||||
// ~/.hermes/plugins/my-plugin/dashboard/dist/index.js
|
||||
(function () {
|
||||
"use strict";
|
||||
|
||||
const SDK = window.__HERMES_PLUGIN_SDK__;
|
||||
const { React } = SDK;
|
||||
const { Card, CardHeader, CardTitle, CardContent } = SDK.components;
|
||||
|
||||
function MyPage() {
|
||||
return React.createElement(Card, null,
|
||||
React.createElement(CardHeader, null,
|
||||
React.createElement(CardTitle, null, "My Plugin"),
|
||||
),
|
||||
React.createElement(CardContent, null,
|
||||
React.createElement("p", { className: "text-sm text-muted-foreground" },
|
||||
"Hello from my custom dashboard tab.",
|
||||
),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
window.__HERMES_PLUGINS__.register("my-plugin", MyPage);
|
||||
})();
|
||||
```
|
||||
|
||||
刷新 dashboard——你的标签页出现在导航栏中，位于 **Skills** 之后。
|
||||
|
||||
:::tip 跳过 React.createElement
|
||||
如果你偏好 JSX，可使用任意打包工具（esbuild、Vite、rollup），将 React 设为外部依赖并输出 IIFE 格式。唯一的硬性要求是最终文件是可通过 `<script>` 加载的单个 JS 文件。React 永远不会被打包进去；它来自 `SDK.React`。
|
||||
:::
|
||||
|
||||
### 目录结构
|
||||
|
||||
```
|
||||
~/.hermes/plugins/my-plugin/
|
||||
├── plugin.yaml # optional — existing CLI/gateway plugin manifest
|
||||
├── __init__.py # optional — existing CLI/gateway hooks
|
||||
└── dashboard/ # dashboard extension
|
||||
├── manifest.json # required — tab config, icon, entry point
|
||||
├── dist/
|
||||
│ ├── index.js # required — pre-built JS bundle (IIFE)
|
||||
│ └── style.css # optional — custom CSS
|
||||
└── plugin_api.py # optional — backend API routes (FastAPI)
|
||||
```
|
||||
|
||||
单个插件目录可承载三个正交扩展：
|
||||
|
||||
- `plugin.yaml` + `__init__.py` — CLI/gateway 插件（[参见插件页面](./plugins)）。
|
||||
- `dashboard/manifest.json` + `dashboard/dist/index.js` — dashboard UI 插件。
|
||||
- `dashboard/plugin_api.py` — dashboard 后端路由。
|
||||
|
||||
三者均非必须；按需包含所需层次即可。
|
||||
|
||||
### Manifest 参考
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"label": "My Plugin",
|
||||
"description": "What this plugin does",
|
||||
"icon": "Sparkles",
|
||||
"version": "1.0.0",
|
||||
"tab": {
|
||||
"path": "/my-plugin",
|
||||
"position": "after:skills",
|
||||
"override": "/",
|
||||
"hidden": false
|
||||
},
|
||||
"slots": ["sidebar", "header-left"],
|
||||
"entry": "dist/index.js",
|
||||
"css": "dist/style.css",
|
||||
"api": "plugin_api.py"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 必填 | 描述 |
|
||||
|-------|----------|-------------|
|
||||
| `name` | 是 | 唯一插件标识符。小写，可用连字符。用于 URL 和注册。 |
|
||||
| `label` | 是 | 导航标签页中显示的名称。 |
|
||||
| `description` | 否 | 简短描述（显示在 dashboard 管理界面）。 |
|
||||
| `icon` | 否 | Lucide 图标名称。默认为 `Puzzle`。未知名称回退到 `Puzzle`。 |
|
||||
| `version` | 否 | Semver 字符串。默认为 `0.0.0`。 |
|
||||
| `tab.path` | 是 | 标签页的 URL 路径（例如 `/my-plugin`）。 |
|
||||
| `tab.position` | 否 | 标签页插入位置。`"end"`（默认）、`"after:<path>"` 或 `"before:<path>"`——冒号后的值是目标标签页的**路径段**（无前导斜杠）。例如：`"after:skills"`、`"before:config"`。 |
|
||||
| `tab.override` | 否 | 设置为内置路由路径（`"/"`、`"/sessions"`、`"/config"` 等）以**替换**该页面，而非添加新标签页。参见[替换内置页面](#replacing-built-in-pages-taboverride)。 |
|
||||
| `tab.hidden` | 否 | 为 true 时，注册组件和所有插槽，但不向导航添加标签页。用于仅插槽插件。参见[仅插槽插件](#slot-only-plugins-tabhidden)。 |
|
||||
| `slots` | 否 | 此插件填充的命名 shell 插槽。**仅作文档说明**——实际注册通过 JS bundle 中的 `registerSlot()` 完成。在此列出插槽可使发现界面更具信息量。 |
|
||||
| `entry` | 是 | 相对于 `dashboard/` 的 JS bundle 路径。默认为 `dist/index.js`。 |
|
||||
| `css` | 否 | 以 `<link>` 标签注入的 CSS 文件路径。 |
|
||||
| `api` | 否 | 包含 FastAPI 路由的 Python 文件路径。挂载在 `/api/plugins/<name>/`。 |
|
||||
|
||||
#### 可用图标
|
||||
|
||||
插件使用 Lucide 图标名称。Dashboard 按名称映射——未知名称静默回退到 `Puzzle`。
|
||||
|
||||
当前已映射：`Activity`、`BarChart3`、`Clock`、`Code`、`Database`、`Eye`、`FileText`、`Globe`、`Heart`、`KeyRound`、`MessageSquare`、`Package`、`Puzzle`、`Settings`、`Shield`、`Sparkles`、`Star`、`Terminal`、`Wrench`、`Zap`。
|
||||
|
||||
需要其他图标？向 `web/src/App.tsx` 的 `ICON_MAP` 提交 PR——纯增量修改。
|
||||
|
||||
### Plugin SDK
|
||||
|
||||
插件所需的一切均在 `window.__HERMES_PLUGIN_SDK__` 上。插件不应直接导入 React。
|
||||
|
||||
```javascript
|
||||
const SDK = window.__HERMES_PLUGIN_SDK__;
|
||||
|
||||
// React + hooks
|
||||
SDK.React // the React instance
|
||||
SDK.hooks.useState
|
||||
SDK.hooks.useEffect
|
||||
SDK.hooks.useCallback
|
||||
SDK.hooks.useMemo
|
||||
SDK.hooks.useRef
|
||||
SDK.hooks.useContext
|
||||
SDK.hooks.createContext
|
||||
|
||||
// UI components (shadcn/ui primitives)
|
||||
SDK.components.Card
|
||||
SDK.components.CardHeader
|
||||
SDK.components.CardTitle
|
||||
SDK.components.CardContent
|
||||
SDK.components.Badge
|
||||
SDK.components.Button
|
||||
SDK.components.Input
|
||||
SDK.components.Label
|
||||
SDK.components.Select
|
||||
SDK.components.SelectOption
|
||||
SDK.components.Separator
|
||||
SDK.components.Tabs
|
||||
SDK.components.TabsList
|
||||
SDK.components.TabsTrigger
|
||||
SDK.components.PluginSlot // render a named slot (useful for nested plugin UIs)
|
||||
|
||||
// Hermes API client + raw fetcher
|
||||
SDK.api // typed client — getStatus, getSessions, getConfig, ...
|
||||
SDK.fetchJSON // raw fetch for custom endpoints (plugin-registered routes)
|
||||
|
||||
// Utilities
|
||||
SDK.utils.cn // Tailwind class merger (clsx + twMerge)
|
||||
SDK.utils.timeAgo // "5m ago" from unix timestamp
|
||||
SDK.utils.isoTimeAgo // "5m ago" from ISO string
|
||||
|
||||
// Hooks
|
||||
SDK.useI18n // i18n hook for multi-language plugins
|
||||
```
|
||||
|
||||
#### 调用插件的后端
|
||||
|
||||
```javascript
|
||||
SDK.fetchJSON("/api/plugins/my-plugin/data")
|
||||
.then((data) => console.log(data))
|
||||
.catch((err) => console.error("API call failed:", err));
|
||||
```
|
||||
|
||||
`fetchJSON` 会自动注入会话认证 token，将错误作为异常抛出，并自动解析 JSON。
|
||||
|
||||
#### 调用内置 Hermes 端点
|
||||
|
||||
```javascript
|
||||
// Agent status
|
||||
SDK.api.getStatus().then((s) => console.log("Version:", s.version));
|
||||
|
||||
// Recent sessions
|
||||
SDK.api.getSessions(10).then((resp) => console.log(resp.sessions.length));
|
||||
```
|
||||
|
||||
完整列表参见 [Web Dashboard → REST API](./web-dashboard#rest-api)。
|
||||
|
||||
### Shell 插槽
|
||||
|
||||
插槽（slot）允许插件向应用 shell 的命名位置注入组件——cockpit 侧边栏、顶栏、底栏、覆盖层——而无需占用整个标签页。多个插件可以填充同一个插槽；它们按注册顺序堆叠渲染。
|
||||
|
||||
在插件 bundle 内部注册：
|
||||
|
||||
```javascript
|
||||
window.__HERMES_PLUGINS__.registerSlot("my-plugin", "sidebar", MySidebar);
|
||||
window.__HERMES_PLUGINS__.registerSlot("my-plugin", "header-left", MyCrest);
|
||||
```
|
||||
|
||||
#### 插槽目录
|
||||
|
||||
**Shell 全局插槽**（在应用外壳的任意位置渲染）：
|
||||
|
||||
| 插槽 | 位置 |
|
||||
|------|----------|
|
||||
| `backdrop` | `<Backdrop />` 层叠栈内，噪点层之上。 |
|
||||
| `header-left` | 顶栏 Hermes 品牌之前。 |
|
||||
| `header-right` | 顶栏主题/语言切换器之前。 |
|
||||
| `header-banner` | 导航栏下方的全宽条带。 |
|
||||
| `sidebar` | Cockpit 侧边栏轨道——**仅在 `layoutVariant === "cockpit"` 时渲染**。 |
|
||||
| `pre-main` | 路由出口之上（`<main>` 内部）。 |
|
||||
| `post-main` | 路由出口之下（`<main>` 内部）。 |
|
||||
| `footer-left` | 底栏单元格内容（替换默认内容）。 |
|
||||
| `footer-right` | 底栏单元格内容（替换默认内容）。 |
|
||||
| `overlay` | 位于所有内容之上的固定定位层。适用于 `customCSS` 无法单独实现的外观效果（扫描线、晕影等）。 |
|
||||
|
||||
**页面级插槽**（仅在指定内置页面上渲染——用于向现有页面注入小部件、卡片或工具栏，而无需覆盖整个路由）：
|
||||
|
||||
| 插槽 | 渲染位置 |
|
||||
|------|------------------|
|
||||
| `sessions:top` / `sessions:bottom` | `/sessions` 页面顶部 / 底部。 |
|
||||
| `analytics:top` / `analytics:bottom` | `/analytics` 页面顶部 / 底部。 |
|
||||
| `logs:top` / `logs:bottom` | `/logs` 顶部（过滤工具栏之上）/ 底部（日志查看器之下）。 |
|
||||
| `cron:top` / `cron:bottom` | `/cron` 页面顶部 / 底部。 |
|
||||
| `skills:top` / `skills:bottom` | `/skills` 页面顶部 / 底部。 |
|
||||
| `config:top` / `config:bottom` | `/config` 页面顶部 / 底部。 |
|
||||
| `env:top` / `env:bottom` | `/env`（Keys）页面顶部 / 底部。 |
|
||||
| `docs:top` / `docs:bottom` | `/docs` 顶部（iframe 之上）/ 底部。 |
|
||||
| `chat:top` / `chat:bottom` | `/chat` 顶部 / 底部（仅在启用嵌入式聊天时有效）。 |
|
||||
|
||||
示例——向 Sessions 页面顶部添加横幅卡片：
|
||||
|
||||
```javascript
|
||||
function PinnedSessionsBanner() {
|
||||
return React.createElement(Card, null,
|
||||
React.createElement(CardContent, { className: "py-2 text-xs" },
|
||||
"Pinned note injected by my-plugin"),
|
||||
);
|
||||
}
|
||||
|
||||
window.__HERMES_PLUGINS__.registerSlot("my-plugin", "sessions:top", PinnedSessionsBanner);
|
||||
```
|
||||
|
||||
如果插件只增强现有页面而不需要独立的侧边栏标签页，可将页面级插槽与 `tab.hidden: true` 结合使用。
|
||||
|
||||
Shell 只为上述插槽渲染 `<PluginSlot name="..." />`。注册表接受额外的名称用于嵌套插件 UI——插件可通过 `SDK.components.PluginSlot` 暴露自己的插槽。
|
||||
|
||||
#### 重复注册与 HMR
|
||||
|
||||
如果同一个 `(plugin, slot)` 对被注册两次，后一次调用会替换前一次——这与 React HMR 期望插件重新挂载时的行为一致。
|
||||
|
||||
### 替换内置页面（`tab.override`）
|
||||
|
||||
将 `tab.override` 设置为内置路由路径，可使插件组件替换该页面，而非添加新标签页。适用于主题希望自定义首页（`/`）但保留 dashboard 其余部分的场景。
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-home",
|
||||
"label": "Home",
|
||||
"tab": {
|
||||
"path": "/my-home",
|
||||
"override": "/",
|
||||
"position": "end"
|
||||
},
|
||||
"entry": "dist/index.js"
|
||||
}
|
||||
```
|
||||
|
||||
设置 `override` 后：
|
||||
|
||||
- 路由器中 `/` 处的原始页面组件被移除。
|
||||
- 你的插件改为在 `/` 处渲染。
|
||||
- 不会为 `tab.path` 添加导航标签页（覆盖本身才是目的）。
|
||||
|
||||
每个路径只能有一个插件进行覆盖。如果两个插件声明相同的覆盖路径，第一个生效，第二个被忽略并在开发模式下输出警告。
|
||||
|
||||
如果只需要向现有页面添加卡片或工具栏而不完全接管它，请改用[页面级插槽](#augmenting-built-in-pages-page-scoped-slots)。
|
||||
|
||||
### 增强内置页面（页面级插槽）
|
||||
|
||||
通过 `tab.override` 完全替换页面代价较重——你的插件现在拥有整个页面，包括我们未来对其的所有更新。大多数情况下，你只是想向现有页面添加横幅、卡片或工具栏。这正是**页面级插槽**的用途。
|
||||
|
||||
每个内置页面都在其内容区域的顶部和底部暴露 `<page>:top` 和 `<page>:bottom` 插槽。你的插件通过调用 `registerSlot()` 填充其中一个——内置页面正常工作，你的组件在其旁边渲染。
|
||||
|
||||
可用插槽：`sessions:*`、`analytics:*`、`logs:*`、`cron:*`、`skills:*`、`config:*`、`env:*`、`docs:*`、`chat:*`（每个均有 `:top` 和 `:bottom`）。完整目录参见 [Shell 插槽 → 插槽目录](#slot-catalogue)。
|
||||
|
||||
最简示例——在 Sessions 页面顶部固定一个横幅：
|
||||
|
||||
```json
|
||||
// ~/.hermes/plugins/session-notes/dashboard/manifest.json
|
||||
{
|
||||
"name": "session-notes",
|
||||
"label": "Session Notes",
|
||||
"tab": { "path": "/session-notes", "hidden": true },
|
||||
"slots": ["sessions:top"],
|
||||
"entry": "dist/index.js"
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ~/.hermes/plugins/session-notes/dashboard/dist/index.js
|
||||
(function () {
|
||||
const SDK = window.__HERMES_PLUGIN_SDK__;
|
||||
const { React } = SDK;
|
||||
const { Card, CardContent } = SDK.components;
|
||||
|
||||
function Banner() {
|
||||
return React.createElement(Card, null,
|
||||
React.createElement(CardContent, { className: "py-2 text-xs" },
|
||||
"Remember to label important sessions before archiving."),
|
||||
);
|
||||
}
|
||||
|
||||
// Placeholder for the hidden tab.
|
||||
window.__HERMES_PLUGINS__.register("session-notes", function () { return null; });
|
||||
|
||||
// The real work.
|
||||
window.__HERMES_PLUGINS__.registerSlot("session-notes", "sessions:top", Banner);
|
||||
})();
|
||||
```
|
||||
|
||||
要点：
|
||||
|
||||
- `tab.hidden: true` 使插件不出现在侧边栏——它没有独立页面。
|
||||
- manifest 中的 `slots` 字段仅作文档说明。实际绑定通过 JS bundle 中的 `registerSlot()` 完成。
|
||||
- 多个插件可以声明同一个页面级插槽。它们按注册顺序堆叠渲染。
|
||||
- 无插件注册时零开销：内置页面与之前完全相同地渲染。
|
||||
|
||||
参考插件（[`hermes-example-plugins`](https://github.com/NousResearch/hermes-example-plugins/tree/main/example-dashboard) 中的 `example-dashboard`）提供了一个向 `sessions:top` 注入横幅的实时演示——安装它可端到端了解该模式。
|
||||
|
||||
### 仅插槽插件（`tab.hidden`）
|
||||
|
||||
当 `tab.hidden: true` 时，插件注册其组件（用于直接 URL 访问）和所有插槽，但不向导航添加标签页。适用于仅用于注入插槽的插件——顶栏徽标、侧边栏 HUD、覆盖层。
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "header-crest",
|
||||
"label": "Header Crest",
|
||||
"tab": {
|
||||
"path": "/header-crest",
|
||||
"position": "end",
|
||||
"hidden": true
|
||||
},
|
||||
"slots": ["header-left"],
|
||||
"entry": "dist/index.js"
|
||||
}
|
||||
```
|
||||
|
||||
Bundle 仍需调用带占位符组件的 `register()`（以防有人直接访问该 URL），然后调用 `registerSlot()` 完成实际工作。
|
||||
|
||||
### 后端 API 路由
|
||||
|
||||
插件可通过在 manifest 中设置 `api` 来注册 FastAPI 路由。创建文件并导出 `router`：
|
||||
|
||||
```python
|
||||
# ~/.hermes/plugins/my-plugin/dashboard/plugin_api.py
|
||||
from fastapi import APIRouter
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
@router.get("/data")
|
||||
async def get_data():
|
||||
return {"items": ["one", "two", "three"]}
|
||||
|
||||
@router.post("/action")
|
||||
async def do_action(body: dict):
|
||||
return {"ok": True, "received": body}
|
||||
```
|
||||
|
||||
路由挂载在 `/api/plugins/<name>/` 下，因此上述路由变为：
|
||||
|
||||
- `GET /api/plugins/my-plugin/data`
|
||||
- `POST /api/plugins/my-plugin/action`
|
||||
|
||||
插件 API 路由绕过会话 token 认证，因为 dashboard 服务器默认绑定到 localhost。**如果运行不受信任的插件，请勿使用 `--host 0.0.0.0` 将 dashboard 暴露在公共接口上**——其路由也会变得可访问。
|
||||
|
||||
#### 访问 Hermes 内部模块
|
||||
|
||||
后端路由在 dashboard 进程内运行，因此可以直接从 hermes-agent 代码库导入：
|
||||
|
||||
```python
|
||||
from fastapi import APIRouter
|
||||
from hermes_state import SessionDB
|
||||
from hermes_cli.config import load_config
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
@router.get("/session-count")
|
||||
async def session_count():
|
||||
db = SessionDB()
|
||||
try:
|
||||
count = len(db.list_sessions(limit=9999))
|
||||
return {"count": count}
|
||||
finally:
|
||||
db.close()
|
||||
|
||||
@router.get("/config-snapshot")
|
||||
async def config_snapshot():
|
||||
cfg = load_config()
|
||||
return {"model": cfg.get("model", {})}
|
||||
```
|
||||
|
||||
### 插件自定义 CSS
|
||||
|
||||
如果插件需要超出 Tailwind 类和内联 `style=` 的样式，可添加 CSS 文件并在 manifest 中引用：
|
||||
|
||||
```json
|
||||
{
|
||||
"css": "dist/style.css"
|
||||
}
|
||||
```
|
||||
|
||||
文件在插件加载时以 `<link>` 标签注入。使用特定类名以避免与 dashboard 样式冲突，并引用 dashboard 的 CSS 变量以保持主题感知：
|
||||
|
||||
```css
|
||||
/* dist/style.css */
|
||||
.my-plugin-chart {
|
||||
border: 1px solid var(--color-border);
|
||||
background: var(--color-card);
|
||||
color: var(--color-card-foreground);
|
||||
padding: 1rem;
|
||||
}
|
||||
.my-plugin-chart:hover {
|
||||
border-color: var(--color-ring);
|
||||
}
|
||||
```
|
||||
|
||||
Dashboard 将每个 shadcn token 暴露为 `--color-*`，以及主题额外变量（`--theme-asset-*`、`--component-<bucket>-*`、`--radius`、`--spacing-mul`）。引用这些变量后，你的插件会随激活主题自动换肤。
|
||||
|
||||
### 插件发现与重载
|
||||
|
||||
Dashboard 扫描三个目录中的 `dashboard/manifest.json`：
|
||||
|
||||
| 优先级 | 目录 | 来源标签 |
|
||||
|----------|-----------|--------------|
|
||||
| 1（冲突时优先） | `~/.hermes/plugins/<name>/dashboard/` | `user` |
|
||||
| 2 | `<repo>/plugins/memory/<name>/dashboard/` | `bundled` |
|
||||
| 2 | `<repo>/plugins/<name>/dashboard/` | `bundled` |
|
||||
| 3 | `./.hermes/plugins/<name>/dashboard/` | `project`——仅在设置 `HERMES_ENABLE_PROJECT_PLUGINS` 时生效 |
|
||||
|
||||
发现结果在每个 dashboard 进程中缓存。添加新插件后，可以：
|
||||
|
||||
```bash
|
||||
# Force a rescan without restart
|
||||
curl http://127.0.0.1:9119/api/dashboard/plugins/rescan
|
||||
```
|
||||
|
||||
……或重启 `hermes dashboard`。
|
||||
|
||||
#### 插件加载生命周期
|
||||
|
||||
1. Dashboard 加载。`main.tsx` 在 `window.__HERMES_PLUGIN_SDK__` 上暴露 SDK，在 `window.__HERMES_PLUGINS__` 上暴露注册表。
|
||||
2. `App.tsx` 调用 `usePlugins()` → 获取 `GET /api/dashboard/plugins`。
|
||||
3. 对于每个 manifest：注入 CSS `<link>`（如已声明），然后通过 `<script>` 标签加载 JS bundle。
|
||||
4. 插件的 IIFE 运行并调用 `window.__HERMES_PLUGINS__.register(name, Component)`——以及可选的 `.registerSlot(name, slot, Component)` 用于每个插槽。
|
||||
5. Dashboard 将注册的组件与 manifest 对应，将标签页添加到导航（除非 `hidden`），并将组件挂载为路由。
|
||||
|
||||
插件在脚本加载后最多有 **2 秒**时间调用 `register()`。超时后 dashboard 停止等待并完成初始渲染。如果插件之后才注册，它仍会出现——导航是响应式的。
|
||||
|
||||
如果插件脚本加载失败（404、语法错误、IIFE 执行期间抛出异常），dashboard 会向浏览器控制台输出警告并继续运行。
|
||||
|
||||
---
|
||||
|
||||
## 主题 + 插件组合演示
|
||||
|
||||
[`strike-freedom-cockpit`](https://github.com/NousResearch/hermes-example-plugins/tree/main/strike-freedom-cockpit) 插件（伴随仓库 `hermes-example-plugins`）是一个完整的换肤演示。它将主题 YAML 与仅插槽插件配对，在不 fork dashboard 的情况下生成驾驶舱风格的 HUD。
|
||||
|
||||
**演示内容：**
|
||||
|
||||
- 完整主题，使用调色板、字体排版、`fontUrl`、`layoutVariant: cockpit`、`assets`、`componentStyles`（切角卡片、渐变背景）、`colorOverrides` 和 `customCSS`（扫描线叠加）。
|
||||
- 仅插槽插件（`tab.hidden: true`），注册到三个插槽：
|
||||
- `sidebar` — 带有由 `SDK.api.getStatus()` 驱动的实时遥测条的 MS-STATUS 面板。
|
||||
- `header-left` — 从激活主题读取 `--theme-asset-crest` 的派系徽标。
|
||||
- `footer-right` — 替换默认组织行的自定义标语。
|
||||
- 插件通过 CSS 变量读取主题提供的图片，因此切换主题可在不修改插件代码的情况下更换英雄图/徽标。
|
||||
|
||||
**安装：**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/NousResearch/hermes-example-plugins.git
|
||||
|
||||
# Theme
|
||||
cp hermes-example-plugins/strike-freedom-cockpit/theme/strike-freedom.yaml \
|
||||
~/.hermes/dashboard-themes/
|
||||
|
||||
# Plugin
|
||||
cp -r hermes-example-plugins/strike-freedom-cockpit ~/.hermes/plugins/
|
||||
```
|
||||
|
||||
打开 dashboard，从主题切换器中选择 **Strike Freedom**。驾驶舱侧边栏出现，徽标显示在顶栏，标语替换底栏。切换回 **Hermes Teal**，插件仍然安装但不可见（`sidebar` 插槽仅在 `cockpit` 布局变体下渲染）。
|
||||
|
||||
阅读插件源码（伴随仓库中的 `strike-freedom-cockpit/dashboard/dist/index.js`），了解它如何读取 CSS 变量、防范不支持插槽的旧版 dashboard，以及如何从单个 bundle 注册三个插槽。
|
||||
|
||||
---
|
||||
|
||||
## API 参考
|
||||
|
||||
### 主题端点
|
||||
|
||||
| 端点 | 方法 | 描述 |
|
||||
|----------|--------|-------------|
|
||||
| `/api/dashboard/themes` | GET | 列出可用主题及当前激活名称。内置主题返回 `{name, label, description}`；用户主题还包含带有完整规范化主题对象的 `definition` 字段。 |
|
||||
| `/api/dashboard/theme` | PUT | 设置激活主题。请求体：`{"name": "midnight"}`。持久化到 `config.yaml` 的 `dashboard.theme` 下。 |
|
||||
|
||||
### 插件端点
|
||||
|
||||
| 端点 | 方法 | 描述 |
|
||||
|----------|--------|-------------|
|
||||
| `/api/dashboard/plugins` | GET | 列出已发现的插件（含 manifest，去除内部字段）。 |
|
||||
| `/api/dashboard/plugins/rescan` | GET | 强制重新扫描插件目录，无需重启。 |
|
||||
| `/dashboard-plugins/<name>/<path>` | GET | 从插件的 `dashboard/` 目录提供静态资源。路径遍历已被阻止。 |
|
||||
| `/api/plugins/<name>/*` | * | 插件注册的后端路由。 |
|
||||
|
||||
### `window` 上的 SDK
|
||||
|
||||
| 全局变量 | 类型 | 提供方 |
|
||||
|--------|------|----------|
|
||||
| `window.__HERMES_PLUGIN_SDK__` | object | `registry.ts` — React、hooks、UI 组件、API 客户端、工具函数。 |
|
||||
| `window.__HERMES_PLUGINS__.register(name, Component)` | function | 注册插件的主组件。 |
|
||||
| `window.__HERMES_PLUGINS__.registerSlot(name, slot, Component)` | function | 注册到命名 shell 插槽。 |
|
||||
|
||||
---
|
||||
|
||||
## 故障排查
|
||||
|
||||
**我的主题没有出现在选择器中。**
|
||||
检查文件是否在 `~/.hermes/dashboard-themes/` 中且以 `.yaml` 或 `.yml` 结尾。刷新页面。运行 `curl http://127.0.0.1:9119/api/dashboard/themes`——你的主题应出现在响应中。如果 YAML 有解析错误，dashboard 会记录到 `~/.hermes/logs/` 下的 `errors.log`。
|
||||
|
||||
**我的插件标签页没有显示。**
|
||||
1. 检查 manifest 是否在 `~/.hermes/plugins/<name>/dashboard/manifest.json`（注意 `dashboard/` 子目录）。
|
||||
2. 运行 `curl http://127.0.0.1:9119/api/dashboard/plugins/rescan` 强制重新发现。
|
||||
3. 打开浏览器开发工具 → Network——确认 `manifest.json`、`index.js` 和任何 CSS 均无 404 加载成功。
|
||||
4. 打开浏览器开发工具 → Console——查找 IIFE 执行期间的错误或 `window.__HERMES_PLUGINS__ is undefined`（表示 SDK 未初始化，通常是更早的 React 渲染崩溃导致）。
|
||||
5. 验证你的 bundle 以与 `manifest.json:name` **相同的名称**调用 `window.__HERMES_PLUGINS__.register(...)`。
|
||||
|
||||
**插槽注册的组件没有渲染。**
|
||||
`sidebar` 插槽仅在激活主题设置了 `layoutVariant: cockpit` 时渲染。其他插槽始终渲染。如果你注册到某个插槽但没有命中，在 `registerSlot` 内添加 `console.log` 以确认插件 bundle 是否已运行。
|
||||
|
||||
**插件后端路由返回 404。**
|
||||
1. 确认 manifest 中有 `"api": "plugin_api.py"` 且指向 `dashboard/` 内的现有文件。
|
||||
2. 重启 `hermes dashboard`——插件 API 路由在启动时挂载一次，**不会**在重新扫描时挂载。
|
||||
3. 检查 `plugin_api.py` 是否导出了模块级的 `router = APIRouter()`。其他导出名称不会被识别。
|
||||
4. 查看 `~/.hermes/logs/errors.log` 中的 `Failed to load plugin <name> API routes`——导入错误会记录在那里。
|
||||
|
||||
**切换主题后我的颜色覆盖丢失了。**
|
||||
`colorOverrides` 的作用域限于激活主题，切换主题时会被清除——这是设计行为。如果你希望覆盖持久化，请将其写入主题的 YAML，而非实时切换器。
|
||||
|
||||
**主题 customCSS 被截断了。**
|
||||
`customCSS` 块每个主题上限为 32 KiB。可将大型样式表拆分到多个主题中，或改用通过 `css` 字段注入完整样式表的插件（无大小限制）。
|
||||
|
||||
**我想在 PyPI 上发布插件。**
|
||||
Dashboard 插件通过目录结构安装，而非 pip 入口点。目前最简洁的分发方式是用户克隆到 `~/.hermes/plugins/` 的 git 仓库。基于 pip 的 dashboard 插件安装器目前尚未实现。
|
||||
+413
@@ -0,0 +1,413 @@
|
||||
---
|
||||
title: 备用提供商
|
||||
description: 配置自动故障转移，在主模型不可用时切换到备用 LLM 提供商。
|
||||
sidebar_label: 备用提供商
|
||||
sidebar_position: 8
|
||||
---
|
||||
|
||||
# 备用提供商
|
||||
|
||||
Hermes Agent 具备三层弹性机制，在提供商出现问题时保持会话正常运行：
|
||||
|
||||
1. **[凭据池](./credential-pools.md)** — 在*同一*提供商的多个 API 密钥之间轮换（优先尝试）
|
||||
2. **主模型备用** — 当主模型失败时，自动切换到*不同*的提供商:模型
|
||||
3. **辅助任务备用** — 针对视觉、压缩、网页提取等附属任务的独立提供商解析
|
||||
|
||||
凭据池处理同一提供商内的轮换（例如多个 OpenRouter 密钥）。本页介绍跨提供商的备用机制。两者均为可选，且相互独立。
|
||||
|
||||
## 主模型备用
|
||||
|
||||
当主 LLM 提供商遇到错误——速率限制、服务器过载、认证失败、连接中断——Hermes 可以在会话中途自动切换到备用提供商:模型对，且不会丢失对话内容。
|
||||
|
||||
### 配置
|
||||
|
||||
最简便的方式是使用交互式管理器：
|
||||
|
||||
```bash
|
||||
hermes fallback
|
||||
```
|
||||
|
||||
`hermes fallback` 复用 `hermes model` 的提供商选择器——相同的提供商列表、相同的凭据提示、相同的验证流程。使用子命令 `add`、`list`（别名 `ls`）、`remove`（别名 `rm`）和 `clear` 来管理备用链。更改会持久化到 `config.yaml` 顶层的 `fallback_providers:` 列表中。
|
||||
|
||||
如果你更倾向于直接编辑 YAML，可在 `~/.hermes/config.yaml` 中添加 `fallback_model` 部分：
|
||||
|
||||
```yaml
|
||||
fallback_model:
|
||||
provider: openrouter
|
||||
model: anthropic/claude-sonnet-4
|
||||
```
|
||||
|
||||
`provider` 和 `model` 均为**必填项**。若任一缺失，备用功能将被禁用。
|
||||
|
||||
:::note `fallback_model` 与 `fallback_providers`
|
||||
`fallback_model`（单数）是旧版单备用键——Hermes 仍支持以保持向后兼容。`fallback_providers`（复数，列表）支持按顺序尝试多个备用；`hermes fallback` 写入此键。当两者同时设置时，Hermes 会合并它们，`fallback_providers` 优先。
|
||||
:::
|
||||
|
||||
### 支持的提供商
|
||||
|
||||
| 提供商 | 值 | 要求 |
|
||||
|----------|-------|-------------|
|
||||
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` |
|
||||
| Nous Portal | `nous` | `hermes setup --portal`（全新安装）或 `hermes auth add nous`（OAuth） |
|
||||
| OpenAI Codex | `openai-codex` | `hermes model`（ChatGPT OAuth） |
|
||||
| GitHub Copilot | `copilot` | `COPILOT_GITHUB_TOKEN`、`GH_TOKEN` 或 `GITHUB_TOKEN` |
|
||||
| GitHub Copilot ACP | `copilot-acp` | 外部进程（编辑器集成） |
|
||||
| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` 或 Claude Code 凭据 |
|
||||
| z.ai / GLM | `zai` | `GLM_API_KEY` |
|
||||
| Kimi / Moonshot | `kimi-coding` | `KIMI_API_KEY` |
|
||||
| MiniMax | `minimax` | `MINIMAX_API_KEY` |
|
||||
| MiniMax（中国）| `minimax-cn` | `MINIMAX_CN_API_KEY` |
|
||||
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` |
|
||||
| NVIDIA NIM | `nvidia` | `NVIDIA_API_KEY`（可选：`NVIDIA_BASE_URL`） |
|
||||
| GMI Cloud | `gmi` | `GMI_API_KEY`（可选：`GMI_BASE_URL`） |
|
||||
| StepFun | `stepfun` | `STEPFUN_API_KEY`（可选：`STEPFUN_BASE_URL`） |
|
||||
| Ollama Cloud | `ollama-cloud` | `OLLAMA_API_KEY` |
|
||||
| Google Gemini（OAuth） | `google-gemini-cli` | `hermes model`（Google OAuth；可选：`HERMES_GEMINI_PROJECT_ID`） |
|
||||
| Google AI Studio | `gemini` | `GOOGLE_API_KEY`（别名：`GEMINI_API_KEY`） |
|
||||
| xAI（Grok） | `xai`（别名 `grok`） | `XAI_API_KEY`（可选：`XAI_BASE_URL`） |
|
||||
| xAI Grok OAuth（SuperGrok） | `xai-oauth`（别名 `grok-oauth`） | `hermes model` → xAI Grok OAuth（浏览器登录；需 SuperGrok 订阅） |
|
||||
| AWS Bedrock | `bedrock` | 标准 boto3 认证（`AWS_REGION` + `AWS_PROFILE` 或 `AWS_ACCESS_KEY_ID`） |
|
||||
| Qwen Portal（OAuth） | `qwen-oauth` | `hermes model`（Qwen Portal OAuth；可选：`HERMES_QWEN_BASE_URL`） |
|
||||
| MiniMax（OAuth） | `minimax-oauth` | `hermes model`（MiniMax 门户 OAuth） |
|
||||
| OpenCode Zen | `opencode-zen` | `OPENCODE_ZEN_API_KEY` |
|
||||
| OpenCode Go | `opencode-go` | `OPENCODE_GO_API_KEY` |
|
||||
| Kilo Code | `kilocode` | `KILOCODE_API_KEY` |
|
||||
| Xiaomi MiMo | `xiaomi` | `XIAOMI_API_KEY` |
|
||||
| Arcee AI | `arcee` | `ARCEEAI_API_KEY` |
|
||||
| GMI Cloud | `gmi` | `GMI_API_KEY` |
|
||||
| Alibaba / DashScope | `alibaba` | `DASHSCOPE_API_KEY` |
|
||||
| Alibaba Coding Plan | `alibaba-coding-plan` | `ALIBABA_CODING_PLAN_API_KEY`（回退到 `DASHSCOPE_API_KEY`） |
|
||||
| Kimi / Moonshot（中国） | `kimi-coding-cn` | `KIMI_CN_API_KEY` |
|
||||
| StepFun | `stepfun` | `STEPFUN_API_KEY` |
|
||||
| Tencent TokenHub | `tencent-tokenhub` | `TOKENHUB_API_KEY` |
|
||||
| Microsoft Foundry | `azure-foundry` | `AZURE_FOUNDRY_API_KEY` + `AZURE_FOUNDRY_BASE_URL` |
|
||||
| LM Studio（本地） | `lmstudio` | `LM_API_KEY`（本地可不填）+ `LM_BASE_URL` |
|
||||
| Hugging Face | `huggingface` | `HF_TOKEN` |
|
||||
| 自定义端点 | `custom` | `base_url` + `key_env`（见下文） |
|
||||
|
||||
### 自定义端点备用
|
||||
|
||||
对于兼容 OpenAI 的自定义端点，添加 `base_url` 并可选填 `key_env`：
|
||||
|
||||
```yaml
|
||||
fallback_model:
|
||||
provider: custom
|
||||
model: my-local-model
|
||||
base_url: http://localhost:8000/v1
|
||||
key_env: MY_LOCAL_KEY # 包含 API 密钥的环境变量名
|
||||
```
|
||||
|
||||
### 备用触发条件
|
||||
|
||||
当主模型出现以下失败时，备用机制自动激活：
|
||||
|
||||
- **速率限制**（HTTP 429）——耗尽重试次数后
|
||||
- **服务器错误**（HTTP 500、502、503）——耗尽重试次数后
|
||||
- **认证失败**（HTTP 401、403）——立即触发（重试无意义）
|
||||
- **未找到**（HTTP 404）——立即触发
|
||||
- **无效响应**——API 多次返回格式错误或空响应时
|
||||
|
||||
触发后，Hermes 将：
|
||||
|
||||
1. 解析备用提供商的凭据
|
||||
2. 构建新的 API 客户端
|
||||
3. 就地替换模型、提供商和客户端
|
||||
4. 重置重试计数器并继续对话
|
||||
|
||||
切换是无感知的——对话历史、工具调用和上下文均被保留。Agent 从中断处继续，只是使用了不同的模型。
|
||||
|
||||
:::info 按轮次，而非按会话
|
||||
备用机制的**作用域为单次轮次**：每条新用户消息都从主模型重新开始。若主模型在某轮次中途失败，备用仅对该轮次生效。下一条消息时，Hermes 会再次尝试主模型。在单次轮次内，备用最多激活一次——若备用也失败，则进入常规错误处理流程（重试，然后返回错误消息）。这既防止了单轮次内的级联故障转移循环，又让主模型在每轮次都有重新尝试的机会。
|
||||
:::
|
||||
|
||||
### 示例
|
||||
|
||||
**以 OpenRouter 作为 Anthropic 原生的备用：**
|
||||
```yaml
|
||||
model:
|
||||
provider: anthropic
|
||||
default: claude-sonnet-4-6
|
||||
|
||||
fallback_model:
|
||||
provider: openrouter
|
||||
model: anthropic/claude-sonnet-4
|
||||
```
|
||||
|
||||
**以 Nous Portal 作为 OpenRouter 的备用：**
|
||||
```yaml
|
||||
model:
|
||||
provider: openrouter
|
||||
default: anthropic/claude-opus-4
|
||||
|
||||
fallback_model:
|
||||
provider: nous
|
||||
model: nous-hermes-3
|
||||
```
|
||||
|
||||
**以本地模型作为云端的备用：**
|
||||
```yaml
|
||||
fallback_model:
|
||||
provider: custom
|
||||
model: llama-3.1-70b
|
||||
base_url: http://localhost:8000/v1
|
||||
key_env: LOCAL_API_KEY
|
||||
```
|
||||
|
||||
**以 Codex OAuth 作为备用：**
|
||||
```yaml
|
||||
fallback_model:
|
||||
provider: openai-codex
|
||||
model: gpt-5.3-codex
|
||||
```
|
||||
|
||||
### 备用适用范围
|
||||
|
||||
| 场景 | 是否支持备用 |
|
||||
|---------|-------------------|
|
||||
| CLI 会话 | ✔ |
|
||||
| 消息网关（Telegram、Discord 等） | ✔ |
|
||||
| 子 Agent 委派 | ✘（子 Agent 不继承备用配置） |
|
||||
| Cron 任务 | ✘（使用固定提供商运行） |
|
||||
| 辅助任务（视觉、压缩等） | ✘（使用各自的提供商链——见下文） |
|
||||
|
||||
:::tip
|
||||
`fallback_model` 没有对应的环境变量——它只能通过 `config.yaml` 配置。这是有意为之：备用配置是一个经过深思熟虑的选择，不应被过期的 shell 导出变量覆盖。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 辅助任务备用
|
||||
|
||||
Hermes 为附属任务使用独立的轻量级模型。每个任务都有自己的提供商解析链，充当内置的备用系统。
|
||||
|
||||
### 具有独立提供商解析的任务
|
||||
|
||||
| 任务 | 功能说明 | 配置键 |
|
||||
|------|-------------|-----------|
|
||||
| 视觉 | 图像分析、浏览器截图 | `auxiliary.vision` |
|
||||
| 网页提取 | 网页内容摘要 | `auxiliary.web_extract` |
|
||||
| 压缩 | 上下文压缩摘要 | `auxiliary.compression` |
|
||||
| Skills Hub | 技能搜索与发现 | `auxiliary.skills_hub` |
|
||||
| MCP | MCP 辅助操作 | `auxiliary.mcp` |
|
||||
| 审批 | 智能命令审批分类 | `auxiliary.approval` |
|
||||
| 标题生成 | 会话标题摘要 | `auxiliary.title_generation` |
|
||||
| Triage Specifier | `hermes kanban specify` / 看板（kanban）✨ 按钮——将单行 triage 任务扩展为完整规格 | `auxiliary.triage_specifier` |
|
||||
|
||||
### 自动检测链
|
||||
|
||||
当任务的提供商设置为 `"auto"`（默认值）时，Hermes 按顺序尝试各提供商，直到找到可用的：
|
||||
|
||||
**文本任务（压缩、网页提取等）：**
|
||||
|
||||
```text
|
||||
OpenRouter → Nous Portal → 自定义端点 → Codex OAuth →
|
||||
API 密钥提供商（z.ai、Kimi、MiniMax、Xiaomi MiMo、Hugging Face、Anthropic）→ 放弃
|
||||
```
|
||||
|
||||
**视觉任务：**
|
||||
|
||||
```text
|
||||
主提供商（若支持视觉）→ OpenRouter → Nous Portal →
|
||||
Codex OAuth → Anthropic → 自定义端点 → 放弃
|
||||
```
|
||||
|
||||
若解析到的提供商在调用时失败，Hermes 还有内部重试机制：若该提供商不是 OpenRouter 且未设置显式 `base_url`，则尝试以 OpenRouter 作为最后备用。
|
||||
|
||||
### 配置辅助提供商
|
||||
|
||||
每个任务可在 `config.yaml` 中独立配置：
|
||||
|
||||
```yaml
|
||||
auxiliary:
|
||||
vision:
|
||||
provider: "auto" # auto | openrouter | nous | codex | main | anthropic
|
||||
model: "" # 例如 "openai/gpt-4o"
|
||||
base_url: "" # 直接端点（优先于 provider）
|
||||
api_key: "" # base_url 的 API 密钥
|
||||
|
||||
web_extract:
|
||||
provider: "auto"
|
||||
model: ""
|
||||
|
||||
compression:
|
||||
provider: "auto"
|
||||
model: ""
|
||||
|
||||
skills_hub:
|
||||
provider: "auto"
|
||||
model: ""
|
||||
|
||||
mcp:
|
||||
provider: "auto"
|
||||
model: ""
|
||||
```
|
||||
|
||||
以上每个任务均遵循相同的 **provider / model / base_url** 模式。上下文压缩在 `auxiliary.compression` 下配置：
|
||||
|
||||
```yaml
|
||||
auxiliary:
|
||||
compression:
|
||||
provider: main # 与其他辅助任务相同的提供商选项
|
||||
model: google/gemini-3-flash-preview
|
||||
base_url: null # 自定义 OpenAI 兼容端点
|
||||
```
|
||||
|
||||
备用模型使用：
|
||||
|
||||
```yaml
|
||||
fallback_model:
|
||||
provider: openrouter
|
||||
model: anthropic/claude-sonnet-4
|
||||
# base_url: http://localhost:8000/v1 # 可选自定义端点
|
||||
```
|
||||
|
||||
三者——辅助任务、压缩、备用——工作方式相同：设置 `provider` 指定处理请求的提供商，`model` 指定使用的模型，`base_url` 指向自定义端点（会覆盖 provider）。
|
||||
|
||||
### 辅助任务的提供商选项
|
||||
|
||||
以下选项仅适用于 `auxiliary:`、`compression:` 和 `fallback_model:` 配置——`"main"` **不是**顶层 `model.provider` 的有效值。对于自定义端点，请在 `model:` 部分使用 `provider: custom`（参见 [AI 提供商](/integrations/providers)）。
|
||||
|
||||
| 提供商 | 说明 | 要求 |
|
||||
|----------|-------------|-------------|
|
||||
| `"auto"` | 按顺序尝试各提供商直到找到可用的（默认） | 至少配置一个提供商 |
|
||||
| `"openrouter"` | 强制使用 OpenRouter | `OPENROUTER_API_KEY` |
|
||||
| `"nous"` | 强制使用 Nous Portal | `hermes auth` |
|
||||
| `"codex"` | 强制使用 Codex OAuth | `hermes model` → Codex |
|
||||
| `"main"` | 使用主 Agent 当前的提供商（仅限辅助任务） | 已配置活跃的主提供商 |
|
||||
| `"anthropic"` | 强制使用 Anthropic 原生 | `ANTHROPIC_API_KEY` 或 Claude Code 凭据 |
|
||||
|
||||
### 直接端点覆盖
|
||||
|
||||
对于任意辅助任务，设置 `base_url` 将完全绕过提供商解析，直接向该端点发送请求：
|
||||
|
||||
```yaml
|
||||
auxiliary:
|
||||
vision:
|
||||
base_url: "http://localhost:1234/v1"
|
||||
api_key: "local-key"
|
||||
model: "qwen2.5-vl"
|
||||
```
|
||||
|
||||
`base_url` 优先于 `provider`。Hermes 使用配置的 `api_key` 进行认证，若未设置则回退到 `OPENAI_API_KEY`。对于自定义端点，**不会**复用 `OPENROUTER_API_KEY`。
|
||||
|
||||
---
|
||||
|
||||
## 辅助任务容量错误备用
|
||||
|
||||
当你设置了显式的辅助提供商（例如 `auxiliary.vision.provider: glm`）时，Hermes 将其视为首选——但若该提供商因**容量错误**（HTTP 402 付款要求、HTTP 429 每日配额耗尽、连接失败）而无法处理请求，Hermes 会通过分层链进行备用，而不是静默失败：
|
||||
|
||||
1. **主辅助提供商** — 你配置的那个（始终优先尝试）
|
||||
2. **`auxiliary.<task>.fallback_chain`** — 你的每任务覆盖列表（若已配置）
|
||||
3. **主 Agent 提供商 + 模型** — 最后的安全网（始终尝试，即使未配置链）
|
||||
4. **警告 + 重新抛出** — 若所有层均失败，Hermes 以 WARNING 级别记录 `Auxiliary <task>: ... all fallbacks exhausted` 并重新抛出原始错误
|
||||
|
||||
瞬时 HTTP 429 速率限制（`Retry-After: ...`）被视为请求约束，而非容量问题——它们遵守你的显式提供商选择，**不会**触发备用链。只有每日/每月配额耗尽、付款错误和连接失败才会绕过显式提供商限制。
|
||||
|
||||
对于使用 `provider: auto`（无显式辅助提供商）的用户，现有的自动检测链将替代步骤 2–3 运行。其第一步已经是主 Agent 模型，因此 `auto` 用户无需任何配置即可获得相同效果。
|
||||
|
||||
### 可选：每任务备用链
|
||||
|
||||
若你希望使用与"主 Agent 模型优先"不同的备用顺序，可显式配置 `fallback_chain`。每个条目至少需要 `provider`；`model`、`base_url` 和 `api_key` 为可选。
|
||||
|
||||
```yaml
|
||||
auxiliary:
|
||||
vision:
|
||||
provider: glm
|
||||
model: glm-4v-flash
|
||||
fallback_chain:
|
||||
- provider: openrouter
|
||||
model: google/gemini-3-flash-preview
|
||||
- provider: nous
|
||||
model: anthropic/claude-sonnet-4
|
||||
|
||||
compression:
|
||||
provider: openrouter
|
||||
fallback_chain:
|
||||
- provider: openai
|
||||
model: gpt-4o-mini
|
||||
```
|
||||
|
||||
你**不需要**配置 `fallback_chain` 才能获得备用功能——主 Agent 安全网无论如何都会运行。仅当你明确希望使用与默认不同的顺序时才需配置。
|
||||
|
||||
### 触发备用的提供商配额错误
|
||||
|
||||
Hermes 将以下情况识别为等同于 402 额度耗尽的容量错误（而非瞬时速率限制）：
|
||||
|
||||
- Bedrock / LiteLLM：`Too many tokens per day`、`daily limit`、`tokens per day`
|
||||
- Vertex AI / GCP：`quota exceeded`、`resource exhausted`、`RESOURCE_EXHAUSTED`
|
||||
- 通用：`daily quota`、`quota_exceeded`
|
||||
|
||||
若你的提供商对每日配额耗尽返回不同的错误信息，而 Hermes 未触发备用，这是一个 bug——请附上确切的错误字符串提交 issue。
|
||||
|
||||
---
|
||||
|
||||
## 上下文压缩备用
|
||||
|
||||
上下文压缩使用 `auxiliary.compression` 配置块来控制处理摘要的模型和提供商：
|
||||
|
||||
```yaml
|
||||
auxiliary:
|
||||
compression:
|
||||
provider: "auto" # auto | openrouter | nous | main
|
||||
model: "google/gemini-3-flash-preview"
|
||||
```
|
||||
|
||||
:::info 旧版迁移
|
||||
旧版配置中的 `compression.summary_model` / `compression.summary_provider` / `compression.summary_base_url` 会在首次加载时自动迁移到 `auxiliary.compression.*`（配置版本 17）。
|
||||
:::
|
||||
|
||||
若压缩没有可用的提供商，Hermes 会直接丢弃中间对话轮次而不生成摘要，而不是让会话失败。
|
||||
|
||||
---
|
||||
|
||||
## 委派提供商覆盖
|
||||
|
||||
由 `delegate_task` 生成的子 Agent **不会**使用主备用模型。但可以将它们路由到不同的提供商:模型对以优化成本：
|
||||
|
||||
```yaml
|
||||
delegation:
|
||||
provider: "openrouter" # 覆盖所有子 Agent 的提供商
|
||||
model: "google/gemini-3-flash-preview" # 覆盖模型
|
||||
# base_url: "http://localhost:1234/v1" # 或使用直接端点
|
||||
# api_key: "local-key"
|
||||
```
|
||||
|
||||
完整配置详情参见[子 Agent 委派](/user-guide/features/delegation)。
|
||||
|
||||
---
|
||||
|
||||
## Cron 任务提供商
|
||||
|
||||
Cron 任务使用执行时配置的提供商运行，不支持备用模型。若要为 Cron 任务使用不同的提供商，请在 Cron 任务本身上配置 `provider` 和 `model` 覆盖：
|
||||
|
||||
```python
|
||||
cronjob(
|
||||
action="create",
|
||||
schedule="every 2h",
|
||||
prompt="Check server status",
|
||||
provider="openrouter",
|
||||
model="google/gemini-3-flash-preview"
|
||||
)
|
||||
```
|
||||
|
||||
完整配置详情参见[定时任务（Cron）](/user-guide/features/cron)。
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
| 功能 | 备用机制 | 配置位置 |
|
||||
|---------|-------------------|----------------|
|
||||
| 主 Agent 模型 | `fallback_model`（config.yaml 中）——出错时按轮次故障转移（每轮次恢复主模型） | `fallback_model:`（顶层） |
|
||||
| 辅助任务（任意）— auto 用户 | 容量错误时完整自动检测链（主 Agent 模型优先，然后提供商链） | `auxiliary.<task>.provider: auto` |
|
||||
| 辅助任务（任意）— 显式提供商 | `fallback_chain`（若已设置）→ 主 Agent 模型 → 警告 + 抛出，仅在容量错误时触发 | `auxiliary.<task>.fallback_chain` |
|
||||
| 视觉 | 分层（见上文）+ 内部 OpenRouter 重试 | `auxiliary.vision` |
|
||||
| 网页提取 | 分层（见上文）+ 内部 OpenRouter 重试 | `auxiliary.web_extract` |
|
||||
| 上下文压缩 | 分层（见上文）；所有层不可用时降级为无摘要 | `auxiliary.compression` |
|
||||
| Skills Hub | 分层（见上文） | `auxiliary.skills_hub` |
|
||||
| MCP 辅助 | 分层（见上文） | `auxiliary.mcp` |
|
||||
| 审批分类 | 分层（见上文） | `auxiliary.approval` |
|
||||
| 标题生成 | 分层（见上文） | `auxiliary.title_generation` |
|
||||
| Triage Specifier | 分层（见上文） | `auxiliary.triage_specifier` |
|
||||
| 委派 | 仅提供商覆盖（无自动备用） | `delegation.provider` / `delegation.model` |
|
||||
| Cron 任务 | 仅每任务提供商覆盖（无自动备用） | 每任务 `provider` / `model` |
|
||||
+180
@@ -0,0 +1,180 @@
|
||||
---
|
||||
sidebar_position: 16
|
||||
title: "持久目标"
|
||||
description: "设置一个持续目标，让 Hermes 跨轮次持续工作直到完成。我们对 Ralph loop 的实现。"
|
||||
---
|
||||
|
||||
# 持久目标（`/goal`）
|
||||
|
||||
`/goal` 为 Hermes 设置一个跨轮次持续存在的目标。每轮结束后，一个轻量级裁判模型会检查目标是否已被助手的最新回复满足。若未满足，Hermes 会自动将一条续行 prompt（提示词）注入同一会话并继续工作——直到目标达成、你暂停或清除目标，或者轮次预算耗尽为止。
|
||||
|
||||
这是我们对 **Ralph loop** 的实现，直接受 Eric Traut（OpenAI）在 [Codex CLI 0.128.0 的 `/goal`](https://github.com/openai/codex) 中的启发。核心思路——跨轮次保持目标存活、不达成不停止——源自他们。此处的实现是独立的，并已适配 Hermes 的架构。
|
||||
|
||||
## 适用场景
|
||||
|
||||
当你希望 Hermes 自主迭代、无需每轮重新提示时，使用 `/goal`：
|
||||
|
||||
- "修复 `src/` 中的所有 lint 错误，并验证 `ruff check` 通过"
|
||||
- "从仓库 Y 移植功能 X，包含测试，并让 CI 变绿"
|
||||
- "调查为何会话 ID 有时在中途压缩时发生漂移，并撰写报告"
|
||||
- "构建一个小型 CLI，按 EXIF 日期重命名文件，然后对 photos/ 文件夹进行测试"
|
||||
|
||||
只需一轮即可完成的任务不需要 `/goal`。*否则你需要说三次"继续"* 的任务，才是它的用武之地。
|
||||
|
||||
## 快速开始
|
||||
|
||||
```
|
||||
/goal Fix every failing test in tests/hermes_cli/ and make sure scripts/run_tests.sh passes for that directory
|
||||
```
|
||||
|
||||
你将看到：
|
||||
|
||||
1. **目标已接受** — `⊙ Goal set (20-turn budget): <your goal>`
|
||||
2. **第 1 轮运行** — Hermes 开始工作，就像你发送了一条普通消息一样。
|
||||
3. **裁判运行** — 轮次结束后，裁判模型判定 `done` 或 `continue`。
|
||||
4. **若需要则触发循环** — 若为 `continue`，你将看到 `↻ Continuing toward goal (1/20): <judge's reason>`，Hermes 自动执行下一步。
|
||||
5. **终止** — 最终你会看到 `✓ Goal achieved: <reason>` 或 `⏸ Goal paused — N/20 turns used`。
|
||||
|
||||
## 命令
|
||||
|
||||
| 命令 | 功能 |
|
||||
|---|---|
|
||||
| `/goal <text>` | 设置（或替换）持续目标。立即启动第一轮，无需再发送单独消息。 |
|
||||
| `/goal` 或 `/goal status` | 显示当前目标、状态及已用轮次。 |
|
||||
| `/goal pause` | 停止自动续行循环，但不清除目标。 |
|
||||
| `/goal resume` | 恢复循环（将轮次计数器重置为零）。 |
|
||||
| `/goal clear` | 完全删除目标。 |
|
||||
|
||||
在 CLI 及所有 gateway 平台（Telegram、Discord、Slack、Matrix、Signal、WhatsApp、SMS、iMessage、Webhook、API server 以及 Web 控制台）上行为完全一致。
|
||||
|
||||
## 目标进行中追加条件：`/subgoal`
|
||||
|
||||
目标激活期间，你可以使用 `/subgoal <text>` 追加额外的验收条件，而不会重置循环。每次调用会向目标的子目标列表添加一个编号条目；下一轮 agent 看到的**续行 prompt** 包含原始目标以及一个"用户在循环中途追加的额外条件"块，**裁判 prompt** 也会被重写，使裁判在判定时必须考虑所有子目标——只有原始目标**和**所有子目标均满足时，目标才会被标记为完成。
|
||||
|
||||
| 命令 | 功能 |
|
||||
|---|---|
|
||||
| `/subgoal <text>` | 向活跃目标追加一个新条件。需要有活跃的 `/goal`。 |
|
||||
| `/subgoal`（无参数） | 显示当前编号子目标列表。 |
|
||||
| `/subgoal remove <N>` | 删除第 N 个子目标（从 1 开始计数）。 |
|
||||
| `/subgoal clear` | 删除所有子目标，但保留原始目标。 |
|
||||
|
||||
子目标与目标一起持久化存储在 `SessionDB.state_meta` 中，因此在 `/resume` 后依然有效。设置新的 `/goal <text>` 会替换目标并清空子目标列表；`/goal clear` 同样如此。
|
||||
|
||||
当你启动一个循环（"修复失败的测试"）后，中途发现还需要"为刚修复的 bug 添加回归测试"时，使用此功能——`/subgoal add a regression test` 可在不中断运行循环的情况下收紧成功条件。
|
||||
|
||||
## 行为细节
|
||||
|
||||
### 裁判
|
||||
|
||||
每轮结束后，Hermes 会调用一个辅助模型，传入：
|
||||
|
||||
- 持续目标文本
|
||||
- agent 最新的最终回复（最后约 4 KB 文本）
|
||||
- 一个系统 prompt，要求裁判以严格 JSON 格式回复：`{"done": <bool>, "reason": "<one-sentence rationale>"}`
|
||||
|
||||
裁判刻意保守：只有当回复**明确**确认目标已完成、最终交付物已清晰产出，或目标不可达/被阻塞时（视为 DONE 并附带阻塞原因，以免在不可能的任务上消耗预算），才会将目标标记为 `done`。
|
||||
|
||||
### 失败开放语义
|
||||
|
||||
若裁判出错（网络抖动、响应格式错误、辅助客户端不可用），Hermes 将判定视为 `continue`——损坏的裁判不会阻塞进度。**轮次预算**才是真正的兜底机制。
|
||||
|
||||
### 轮次预算
|
||||
|
||||
默认为 20 个续行轮次（`config.yaml` 中的 `goals.max_turns`）。预算耗尽时，Hermes 自动暂停并告知你如何继续：
|
||||
|
||||
```
|
||||
⏸ Goal paused — 20/20 turns used. Use /goal resume to keep going, or /goal clear to stop.
|
||||
```
|
||||
|
||||
`/goal resume` 将计数器重置为零，你可以按可控的块继续推进。
|
||||
|
||||
### 用户消息始终优先
|
||||
|
||||
目标激活期间，你发送的任何真实消息都优先于续行循环。在 CLI 上，你的消息会在队列中的续行消息之前进入 `_pending_input`；在 gateway 上，它以同样的方式通过适配器 FIFO 传递。你的轮次结束后裁判会再次运行——因此如果你的消息恰好完成了目标，裁判会捕获到并停止循环。
|
||||
|
||||
### 运行中安全性（gateway）
|
||||
|
||||
agent 正在运行时，`/goal status`、`/goal pause` 和 `/goal clear` 可以安全执行——它们只操作控制面状态，不会中断当前轮次。在运行中设置**新**目标（`/goal <new text>`）会被拒绝，并提示你先执行 `/stop`，以防旧续行与新目标产生竞争。
|
||||
|
||||
### 持久化
|
||||
|
||||
目标状态存储在 `SessionDB.state_meta` 中，以 `goal:<session_id>` 为键。这意味着 `/resume` 可以从你离开的地方继续——设置目标、合上笔记本、明天回来、执行 `/resume`，目标依然完好如初（活跃、暂停或已完成）。
|
||||
|
||||
### Prompt 缓存
|
||||
|
||||
续行 prompt 是一条以用户角色追加到历史记录中的普通消息。它**不会**修改系统 prompt、切换工具集，也不会以任何使 Hermes prompt 缓存失效的方式改动对话。运行一个 20 轮目标，在缓存层面与 20 轮普通对话的开销相同。
|
||||
|
||||
## 配置
|
||||
|
||||
在 `~/.hermes/config.yaml` 中添加：
|
||||
|
||||
```yaml
|
||||
goals:
|
||||
# Hermes 自动暂停并要求你执行 /goal resume 之前的最大续行轮次。
|
||||
# 默认 20。若想要更紧凑的循环可降低此值；
|
||||
# 长时间重构可适当提高。
|
||||
max_turns: 20
|
||||
```
|
||||
|
||||
### 选择裁判模型
|
||||
|
||||
裁判使用 `goal_judge` 辅助任务。默认情况下，它解析为你的主模型（参见[辅助模型](/user-guide/configuration#auxiliary-models)）。若想将裁判路由到廉价快速的模型以降低成本，可添加覆盖配置：
|
||||
|
||||
```yaml
|
||||
auxiliary:
|
||||
goal_judge:
|
||||
provider: openrouter
|
||||
model: google/gemini-3-flash-preview
|
||||
```
|
||||
|
||||
裁判调用量小（约 200 个输出 token），每轮运行一次，因此廉价快速的模型通常是正确选择。
|
||||
|
||||
## 示例演练
|
||||
|
||||
```
|
||||
You: /goal Create four files /tmp/note_{1..4}.txt, one per turn, each containing its number as text
|
||||
|
||||
⊙ Goal set (20-turn budget): Create four files /tmp/note_{1..4}.txt, one per turn, each containing its number as text
|
||||
|
||||
Hermes: Creating /tmp/note_1.txt now.
|
||||
💻 echo "1" > /tmp/note_1.txt (0.1s)
|
||||
I've created /tmp/note_1.txt with the content "1". I'll continue with the remaining files on the next turn as you specified.
|
||||
|
||||
↻ Continuing toward goal (1/20): Only 1 of 4 files has been created; 3 files remain.
|
||||
|
||||
Hermes: [Continuing toward your standing goal]
|
||||
💻 echo "2" > /tmp/note_2.txt (0.1s)
|
||||
Created /tmp/note_2.txt. Two more to go.
|
||||
|
||||
↻ Continuing toward goal (2/20): 2 of 4 files created; 2 remain.
|
||||
|
||||
Hermes: [Continuing toward your standing goal]
|
||||
💻 echo "3" > /tmp/note_3.txt (0.1s)
|
||||
Created /tmp/note_3.txt.
|
||||
|
||||
↻ Continuing toward goal (3/20): 3 of 4 files created; 1 remains.
|
||||
|
||||
Hermes: [Continuing toward your standing goal]
|
||||
💻 echo "4" > /tmp/note_4.txt (0.1s)
|
||||
All four files have been created: /tmp/note_1.txt through /tmp/note_4.txt, each containing its number.
|
||||
|
||||
✓ Goal achieved: All four files were created with the specified content, completing the goal.
|
||||
|
||||
You: _
|
||||
```
|
||||
|
||||
四轮，一次 `/goal` 调用，你零次"继续"提示。
|
||||
|
||||
## 裁判判断有误时
|
||||
|
||||
没有裁判是完美的。需注意两种失败模式：
|
||||
|
||||
**假阴性——目标实际已完成，裁判却说继续。** 轮次预算会兜底。你会看到 `⏸ Goal paused`，可以执行 `/goal clear` 或直接发送新消息。
|
||||
|
||||
**假阳性——工作尚未完成，裁判却说已完成。** 你会看到 `✓ Goal achieved`，但你知道实际情况并非如此。发送后续消息继续，或更精确地重新设置目标：`/goal <更具体的文本>`。裁判的系统 prompt 刻意保守，以使假阳性比假阴性更少出现。
|
||||
|
||||
如果你觉得某次裁判判定不可信，`↻ Continuing toward goal` 或 `✓ Goal achieved` 行中的原因文本会告诉你裁判看到了什么。这通常足以诊断出是目标文本存在歧义，还是模型的回复有问题。
|
||||
|
||||
## 致谢
|
||||
|
||||
`/goal` 是 Hermes 对 **Ralph loop** 模式的实现。面向用户的设计——跨轮次保持目标存活、不达成不停止，以及创建/暂停/恢复/清除控制——由 OpenAI Codex 团队的 Eric Traut 在 [Codex CLI 0.128.0](https://github.com/openai/codex) 中推广并落地。我们的实现是独立的（中央 `CommandDef` 注册表、`SessionDB.state_meta` 持久化、辅助客户端裁判、gateway 侧的适配器 FIFO 续行），但这个想法源自他们。功劳归于应得之人。
|
||||
+233
@@ -0,0 +1,233 @@
|
||||
---
|
||||
sidebar_position: 99
|
||||
title: "Honcho Memory"
|
||||
description: "通过 Honcho 实现 AI 原生持久记忆——辩证推理、多智能体用户建模与深度个性化"
|
||||
---
|
||||
|
||||
# Honcho Memory
|
||||
|
||||
[Honcho](https://github.com/plastic-labs/honcho) 是一个 AI 原生记忆后端，在 Hermes 内置记忆系统之上增加了辩证推理（dialectic reasoning）和深度用户建模能力。它不是简单的键值存储，而是通过对对话事后推理，持续维护一个关于用户的动态模型——涵盖其偏好、沟通风格、目标与行为模式。
|
||||
|
||||
:::info Honcho 是一个 Memory Provider 插件
|
||||
Honcho 已集成到 [Memory Providers](./memory-providers.md) 系统中。以下所有功能均可通过统一的 memory provider 接口使用。
|
||||
:::
|
||||
|
||||
## Honcho 新增了什么
|
||||
|
||||
| 能力 | 内置记忆 | Honcho |
|
||||
|-----------|----------------|--------|
|
||||
| 跨会话持久化 | ✔ 基于文件的 MEMORY.md/USER.md | ✔ 服务端 API |
|
||||
| 用户画像 | ✔ 手动 agent 维护 | ✔ 自动辩证推理 |
|
||||
| 会话摘要 | — | ✔ 会话级上下文注入 |
|
||||
| 多 agent 隔离 | — | ✔ 按 peer 分离画像 |
|
||||
| 观察模式 | — | ✔ 统一或定向观察 |
|
||||
| 结论（派生洞察） | — | ✔ 服务端模式推理 |
|
||||
| 历史搜索 | ✔ FTS5 会话搜索 | ✔ 基于结论的语义搜索 |
|
||||
|
||||
**辩证推理**：每轮对话后（由 `dialecticCadence` 控制频率），Honcho 分析交流内容，推导出关于用户偏好、习惯和目标的洞察。这些洞察随时间积累，使 agent 对用户的理解不断加深，超越用户明确表述的内容。辩证过程支持多轮深度（1–3 轮），并自动选择冷启动/热启动 prompt——冷启动查询聚焦于通用用户事实，热启动查询优先处理会话级上下文。
|
||||
|
||||
**会话级上下文**：基础上下文现在包含会话摘要，以及用户表示和 peer 卡片。这使 agent 能感知当前会话中已讨论的内容，减少重复并保持连贯性。
|
||||
|
||||
**多 agent 画像**：当多个 Hermes 实例与同一用户交互时（例如编程助手和个人助手），Honcho 为每个 peer 维护独立画像。每个 peer 只能看到自己的观察和结论，防止上下文交叉污染。
|
||||
|
||||
## 设置
|
||||
|
||||
```bash
|
||||
hermes memory setup # 从 provider 列表中选择 "honcho"
|
||||
```
|
||||
|
||||
或手动配置：
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
memory:
|
||||
provider: honcho
|
||||
```
|
||||
|
||||
```bash
|
||||
echo 'HONCHO_API_KEY=***' >> ~/.hermes/.env
|
||||
```
|
||||
|
||||
在 [honcho.dev](https://honcho.dev) 获取 API key。
|
||||
|
||||
## 架构
|
||||
|
||||
### 双层上下文注入
|
||||
|
||||
每轮对话（在 `hybrid` 或 `context` 模式下），Honcho 组装两层上下文注入到系统 prompt 中：
|
||||
|
||||
1. **基础上下文** — 会话摘要、用户表示、用户 peer 卡片、AI 自我表示和 AI 身份卡片。按 `contextCadence` 刷新。这是"这个用户是谁"层。
|
||||
2. **辩证补充** — LLM 合成的关于用户当前状态和需求的推理。按 `dialecticCadence` 刷新。这是"当前最重要的是什么"层。
|
||||
|
||||
两层内容拼接后，按 `contextTokens` 预算截断（如已设置）。
|
||||
|
||||
### 冷启动/热启动 Prompt 选择
|
||||
|
||||
辩证过程自动在两种 prompt 策略之间切换：
|
||||
|
||||
- **冷启动**（尚无基础上下文）：通用查询——"这个人是谁？他们的偏好、目标和工作方式是什么？"
|
||||
- **热启动会话**（已有基础上下文）：会话级查询——"结合本次会话已讨论的内容，关于该用户哪些上下文最相关？"
|
||||
|
||||
是否已填充基础上下文决定了自动选择哪种策略。
|
||||
|
||||
### 三个正交配置旋钮
|
||||
|
||||
成本和深度由三个独立旋钮控制：
|
||||
|
||||
| 旋钮 | 控制内容 | 默认值 |
|
||||
|------|----------|---------|
|
||||
| `contextCadence` | `context()` API 调用之间的最小轮数（基础层刷新） | `1` |
|
||||
| `dialecticCadence` | `peer.chat()` LLM 调用之间的最小轮数（辩证层刷新） | `2`（推荐 1–5） |
|
||||
| `dialecticDepth` | 每次辩证调用的 `.chat()` 轮数（1–3） | `1` |
|
||||
|
||||
三者相互独立——可以频繁刷新上下文而不频繁运行辩证，也可以低频运行深度多轮辩证。示例：`contextCadence: 1, dialecticCadence: 5, dialecticDepth: 2` 表示每轮刷新基础上下文，每 5 轮运行一次辩证，每次辩证运行 2 轮。
|
||||
|
||||
### 辩证深度（多轮）
|
||||
|
||||
当 `dialecticDepth` > 1 时，每次辩证调用运行多轮 `.chat()`：
|
||||
|
||||
- **第 0 轮**：冷启动或热启动 prompt（见上文）
|
||||
- **第 1 轮**：自我审计——识别初始评估中的不足，并综合近期会话的证据
|
||||
- **第 2 轮**：调和——检查前几轮之间的矛盾，生成最终综合结论
|
||||
|
||||
每轮使用按比例分配的推理级别（早期轮次较轻，主轮次使用基础级别）。通过 `dialecticDepthLevels` 可逐轮覆盖——例如，深度 3 运行时使用 `["minimal", "medium", "high"]`。
|
||||
|
||||
如果前一轮返回了强信号（长且结构化的输出），后续轮次会提前退出，因此深度 3 并不总是意味着 3 次 LLM 调用。
|
||||
|
||||
### 会话启动预热
|
||||
|
||||
会话初始化时，Honcho 在后台以完整配置的 `dialecticDepth` 触发一次辩证调用，并将结果直接传递给第 1 轮的上下文组装。对冷 peer 进行单轮预热通常返回较少内容——多轮深度会在用户开口之前完成审计/调和周期。如果预热在第 1 轮前未完成，第 1 轮将回退到有超时限制的同步调用。
|
||||
|
||||
### 查询自适应推理级别
|
||||
|
||||
自动注入的辩证会根据查询长度调整 `dialecticReasoningLevel`：≥120 字符时 +1 级，≥400 字符时 +2 级，上限为 `reasoningLevelCap`（默认 `"high"`）。设置 `reasoningHeuristic: false` 可禁用此功能，将所有自动调用固定在 `dialecticReasoningLevel`。可用级别：`minimal`、`low`、`medium`、`high`、`max`。
|
||||
|
||||
## 配置选项
|
||||
|
||||
Honcho 在 `~/.honcho/config.json`（全局）或 `$HERMES_HOME/honcho.json`（profile 本地）中配置。设置向导会自动处理。
|
||||
|
||||
### 完整配置参考
|
||||
|
||||
| 键 | 默认值 | 说明 |
|
||||
|-----|---------|-------------|
|
||||
| `contextTokens` | `null`（不限制） | 每轮自动注入上下文的 token 预算。设为整数（如 1200）以限制上限，按词边界截断 |
|
||||
| `contextCadence` | `1` | `context()` API 调用之间的最小轮数（基础层刷新） |
|
||||
| `dialecticCadence` | `2` | `peer.chat()` LLM 调用之间的最小轮数（辩证层）。推荐 1–5。在 `tools` 模式下无关——由模型显式调用 |
|
||||
| `dialecticDepth` | `1` | 每次辩证调用的 `.chat()` 轮数，限制在 1–3 |
|
||||
| `dialecticDepthLevels` | `null` | 可选的每轮推理级别数组，如 `["minimal", "low", "medium"]`，覆盖按比例分配的默认值 |
|
||||
| `dialecticReasoningLevel` | `'low'` | 基础推理级别：`minimal`、`low`、`medium`、`high`、`max` |
|
||||
| `dialecticDynamic` | `true` | 为 `true` 时，模型可通过 tool 参数逐次覆盖推理级别 |
|
||||
| `dialecticMaxChars` | `600` | 注入系统 prompt 的辩证结果最大字符数 |
|
||||
| `recallMode` | `'hybrid'` | `hybrid`（自动注入 + tools）、`context`（仅注入）、`tools`（仅 tools） |
|
||||
| `writeFrequency` | `'async'` | 消息刷新时机：`async`（后台线程）、`turn`（同步）、`session`（会话结束时批量）或整数 N |
|
||||
| `saveMessages` | `true` | 是否将消息持久化到 Honcho API |
|
||||
| `observationMode` | `'directional'` | `directional`（全部开启）或 `unified`（共享池）。可用 `observation` 对象进行精细控制 |
|
||||
| `messageMaxChars` | `25000` | 通过 `add_messages()` 发送的每条消息最大字符数，超出时分块 |
|
||||
| `dialecticMaxInputChars` | `10000` | 传入 `peer.chat()` 的辩证查询输入最大字符数 |
|
||||
| `sessionStrategy` | `'per-directory'` | `per-directory`、`per-repo`、`per-session` 或 `global` |
|
||||
|
||||
**会话策略**控制 Honcho 会话与工作内容的映射方式：
|
||||
- `per-session` — 每次 `hermes` 运行获得一个新会话。干净启动，通过 tools 访问记忆。推荐新用户使用。
|
||||
- `per-directory` — 每个工作目录对应一个 Honcho 会话，上下文跨运行积累。
|
||||
- `per-repo` — 每个 git 仓库对应一个会话。
|
||||
- `global` — 所有目录共用一个会话。
|
||||
|
||||
**Recall 模式**控制记忆如何流入对话：
|
||||
- `hybrid` — 上下文自动注入系统 prompt，同时提供 tools（由模型决定何时查询）。
|
||||
- `context` — 仅自动注入，隐藏 tools。
|
||||
- `tools` — 仅 tools，不自动注入。agent 必须显式调用 `honcho_reasoning`、`honcho_search` 等。
|
||||
|
||||
**各 recall 模式下的设置行为：**
|
||||
|
||||
| 设置 | `hybrid` | `context` | `tools` |
|
||||
|---------|----------|-----------|---------|
|
||||
| `writeFrequency` | 刷新消息 | 刷新消息 | 刷新消息 |
|
||||
| `contextCadence` | 控制基础上下文刷新 | 控制基础上下文刷新 | 无关——不注入 |
|
||||
| `dialecticCadence` | 控制自动 LLM 调用 | 控制自动 LLM 调用 | 无关——由模型显式调用 |
|
||||
| `dialecticDepth` | 每次调用的多轮数 | 每次调用的多轮数 | 无关——由模型显式调用 |
|
||||
| `contextTokens` | 限制注入量 | 限制注入量 | 无关——不注入 |
|
||||
| `dialecticDynamic` | 控制模型覆盖 | 不适用（无 tools） | 控制模型覆盖 |
|
||||
|
||||
在 `tools` 模式下，模型完全自主——它在需要时调用 `honcho_reasoning`，并自行选择 `reasoning_level`。Cadence 和预算设置仅适用于有自动注入的模式（`hybrid` 和 `context`）。
|
||||
|
||||
## 观察模式（定向 vs. 统一）
|
||||
|
||||
Honcho 将对话建模为 peer 之间的消息交换。每个 peer 有两个观察开关，与 Honcho 的 `SessionPeerConfig` 一一对应：
|
||||
|
||||
| 开关 | 效果 |
|
||||
|--------|--------|
|
||||
| `observeMe` | Honcho 根据该 peer 自身的消息构建其表示 |
|
||||
| `observeOthers` | 该 peer 观察另一 peer 的消息（用于跨 peer 推理） |
|
||||
|
||||
两个 peer × 两个开关 = 四个标志。`observationMode` 是快捷预设：
|
||||
|
||||
| 预设 | 用户标志 | AI 标志 | 语义 |
|
||||
|--------|-----------|----------|-----------|
|
||||
| `"directional"`（默认） | me: 开，others: 开 | me: 开，others: 开 | 完全互相观察。启用跨 peer 辩证——"AI 根据用户所说和 AI 回复，对用户了解多少。" |
|
||||
| `"unified"` | me: 开，others: 关 | me: 关，others: 开 | 共享池语义——AI 仅观察用户消息，用户 peer 仅自我建模。单观察者池。 |
|
||||
|
||||
使用显式 `observation` 块覆盖预设，实现逐 peer 精细控制：
|
||||
|
||||
```json
|
||||
"observation": {
|
||||
"user": { "observeMe": true, "observeOthers": true },
|
||||
"ai": { "observeMe": true, "observeOthers": false }
|
||||
}
|
||||
```
|
||||
|
||||
常见配置模式：
|
||||
|
||||
| 意图 | 配置 |
|
||||
|--------|--------|
|
||||
| 完全观察（大多数用户） | `"observationMode": "directional"` |
|
||||
| AI 不应根据自身回复重新建模用户 | `"ai": {"observeMe": true, "observeOthers": false}` |
|
||||
| AI peer 不应通过自我观察更新的强人设 | `"ai": {"observeMe": false, "observeOthers": true}` |
|
||||
|
||||
通过 [Honcho 控制台](https://app.honcho.dev) 设置的服务端开关优先于本地默认值——Hermes 在会话初始化时同步回本地。
|
||||
|
||||
## Tools
|
||||
|
||||
当 Honcho 作为 memory provider 激活时，以下五个 tools 可用：
|
||||
|
||||
| Tool | 用途 |
|
||||
|------|---------|
|
||||
| `honcho_profile` | 读取或更新 peer 卡片——传入 `card`（事实列表）以更新，省略则读取 |
|
||||
| `honcho_search` | 对上下文进行语义搜索——返回原始摘录，不经 LLM 合成 |
|
||||
| `honcho_context` | 完整会话上下文——摘要、表示、卡片、近期消息 |
|
||||
| `honcho_reasoning` | Honcho LLM 合成的答案——传入 `reasoning_level`（minimal/low/medium/high/max）控制深度 |
|
||||
| `honcho_conclude` | 创建或删除结论——传入 `conclusion` 创建，传入 `delete_id` 删除（仅限 PII） |
|
||||
|
||||
## CLI 命令
|
||||
|
||||
`hermes honcho` 子命令**仅在 Honcho 为当前活跃 memory provider 时注册**（`config.yaml` 中 `memory.provider: honcho`）。先运行 `hermes memory setup` 并选择 Honcho，子命令将在下次调用时出现。
|
||||
|
||||
```bash
|
||||
hermes honcho status # 连接状态、配置及关键设置
|
||||
hermes honcho setup # 重定向到 `hermes memory setup`
|
||||
hermes honcho strategy # 查看或设置会话策略（per-session/per-directory/per-repo/global）
|
||||
hermes honcho peer # 查看或更新 peer 名称及辩证推理级别
|
||||
hermes honcho mode # 查看或设置 recall 模式（hybrid/context/tools）
|
||||
hermes honcho tokens # 查看或设置上下文和辩证的 token 预算
|
||||
hermes honcho identity # 初始化或查看 AI peer 的 Honcho 身份
|
||||
hermes honcho sync # 将 Honcho 配置同步到所有现有 profile
|
||||
hermes honcho peers # 查看所有 profile 中的 peer 身份
|
||||
hermes honcho sessions # 列出已知的 Honcho 会话映射
|
||||
hermes honcho map # 将当前目录映射到 Honcho 会话名称
|
||||
hermes honcho enable # 为当前 profile 启用 Honcho
|
||||
hermes honcho disable # 为当前 profile 禁用 Honcho
|
||||
hermes honcho migrate # 从 openclaw-honcho 迁移的分步指南
|
||||
```
|
||||
|
||||
## 从 `hermes honcho` 迁移
|
||||
|
||||
如果你之前使用了独立的 `hermes honcho setup`：
|
||||
|
||||
1. 你的现有配置（`honcho.json` 或 `~/.honcho/config.json`）已保留
|
||||
2. 你的服务端数据（记忆、结论、用户画像）完好无损
|
||||
3. 在 config.yaml 中设置 `memory.provider: honcho` 即可重新激活
|
||||
|
||||
无需重新登录或重新设置。运行 `hermes memory setup` 并选择"honcho"——向导会自动检测你的现有配置。
|
||||
|
||||
## 完整文档
|
||||
|
||||
参见 [Memory Providers — Honcho](./memory-providers.md#honcho) 获取完整参考文档。
|
||||
+1332
File diff suppressed because it is too large
Load Diff
+153
@@ -0,0 +1,153 @@
|
||||
---
|
||||
title: 文生图（Image Generation）
|
||||
description: 通过 FAL.ai 文生图；支持 8 个模型，含 FLUX 2、GPT-Image、Nano Banana Pro、Ideogram、Recraft V4 Pro 等，可用 hermes tools 切换。
|
||||
sidebar_label: 文生图
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
# 文生图（Image Generation）
|
||||
|
||||
Hermes Agent 通过 FAL.ai 根据文字提示生成图像。默认内置 8 个模型，在速度、画质与成本上各有取舍。当前模型可通过 `hermes tools` 配置，并持久化在 `config.yaml`。
|
||||
|
||||
## 支持的模型
|
||||
|
||||
| 模型 | 速度 | 特点 | 参考价格 |
|
||||
|------|------|------|----------|
|
||||
| `fal-ai/flux-2/klein/9b` *（默认）* | `<1s` | 快、文字清晰 | $0.006/MP |
|
||||
| `fal-ai/flux-2-pro` | ~6s | 棚拍级写实 | $0.03/MP |
|
||||
| `fal-ai/z-image/turbo` | ~2s | 中英双语，6B | $0.005/MP |
|
||||
| `fal-ai/nano-banana-pro` | ~8s | Gemini 3 Pro、推理与文字渲染 | $0.15/张（1K） |
|
||||
| `fal-ai/gpt-image-1.5` | ~15s | 强指令遵循 | $0.034/张 |
|
||||
| `fal-ai/ideogram/v3` | ~5s | 排版最佳 | $0.03–0.09/张 |
|
||||
| `fal-ai/recraft/v4/pro/text-to-image` | ~8s | 设计 / 品牌系统 / 可交付生产 | $0.25/张 |
|
||||
| `fal-ai/qwen-image` | ~12s | 偏 LLM 式、复杂文字 | $0.02/MP |
|
||||
|
||||
价格为撰写时的 FAL 官方口径；最新计费请以 [fal.ai](https://fal.ai/) 为准。
|
||||
|
||||
## 配置
|
||||
|
||||
:::tip Nous 订阅用户
|
||||
若你持有付费 [Nous Portal](https://portal.nousresearch.com) 订阅，可通过 **[Tool Gateway](tool-gateway.md)** 使用文生图，**无需** `FAL_KEY`。模型选择在「直连 FAL」与「订阅网关」两条路径下保持一致。
|
||||
|
||||
若托管网关对某一模型返回 `HTTP 4xx`，通常表示该模型尚未在 Portal 侧代理——智能体会给出处理建议（例如配置 `FAL_KEY` 直连，或换用其他模型）。
|
||||
:::
|
||||
|
||||
### 获取 FAL API Key
|
||||
|
||||
1. 在 [fal.ai](https://fal.ai/) 注册
|
||||
2. 在控制台生成 API Key
|
||||
|
||||
### 配置并选择模型
|
||||
|
||||
执行：
|
||||
|
||||
```bash
|
||||
hermes tools
|
||||
```
|
||||
|
||||
进入 **🎨 Image Generation**，选择后端（Nous Subscription 或 FAL.ai），随后在表格中用方向键选择模型，回车确认：
|
||||
|
||||
```
|
||||
Model Speed Strengths Price
|
||||
fal-ai/flux-2/klein/9b <1s Fast, crisp text $0.006/MP ← currently in use
|
||||
fal-ai/flux-2-pro ~6s Studio photorealism $0.03/MP
|
||||
fal-ai/z-image/turbo ~2s Bilingual EN/CN, 6B $0.005/MP
|
||||
...
|
||||
```
|
||||
|
||||
选择会写入 `config.yaml`：
|
||||
|
||||
```yaml
|
||||
image_gen:
|
||||
model: fal-ai/flux-2/klein/9b
|
||||
use_gateway: false # 使用 Nous Subscription 时为 true
|
||||
```
|
||||
|
||||
### GPT-Image 画质档位
|
||||
|
||||
`fal-ai/gpt-image-1.5` 的请求画质固定为 `medium`（约 1024×1024 下 $0.034/张）。面向用户**不开放** `low` / `high` 档位，以便 Nous Portal 侧计费在全体用户间更可预期（档位价差约 22×）。若需要更便宜的 GPT-Image 路线，请换其他模型；若追求更高画质，可考虑 Klein 9B 或同类 Imagen 系模型。
|
||||
|
||||
## 使用方式
|
||||
|
||||
对智能体暴露的 schema 刻意保持简单——具体行为由你在本机的配置决定：
|
||||
|
||||
```
|
||||
Generate an image of a serene mountain landscape with cherry blossoms
|
||||
```
|
||||
|
||||
```
|
||||
Create a square portrait of a wise old owl — use the typography model
|
||||
```
|
||||
|
||||
```
|
||||
Make me a futuristic cityscape, landscape orientation
|
||||
```
|
||||
|
||||
## 宽高比
|
||||
|
||||
从智能体视角，三个宽高比词对所有模型通用；内部会映射到各模型原生参数：
|
||||
|
||||
| 智能体输入 | image_size（flux/z-image/qwen/recraft/ideogram） | aspect_ratio（nano-banana-pro） | image_size（gpt-image） |
|
||||
|---|---|---|---|
|
||||
| `landscape` | `landscape_16_9` | `16:9` | `1536x1024` |
|
||||
| `square` | `square_hd` | `1:1` | `1024x1024` |
|
||||
| `portrait` | `portrait_16_9` | `9:16` | `1024x1536` |
|
||||
|
||||
该映射在 `_build_fal_payload()` 中完成，智能体代码无需了解各模型 schema 差异。
|
||||
|
||||
## 自动超分（Upscale）
|
||||
|
||||
是否启用 FAL **Clarity Upscaler** 按模型区分：
|
||||
|
||||
| 模型 | 超分？ | 原因 |
|
||||
|---|---|---|
|
||||
| `fal-ai/flux-2-pro` | ✓ | 历史兼容（选择器出现前的默认） |
|
||||
| 其他 | ✗ | 亚秒级模型若再超分会失去速度优势；高分辨率模型本身已足够清晰 |
|
||||
|
||||
超分启用时的主要参数：
|
||||
|
||||
| 项 | 值 |
|
||||
|---|---|
|
||||
| 放大倍数 | 2× |
|
||||
| Creativity | 0.35 |
|
||||
| Resemblance | 0.6 |
|
||||
| Guidance scale | 4 |
|
||||
| Inference steps | 18 |
|
||||
|
||||
若超分失败（网络、限流等），会自动回退为返回原始图像。
|
||||
|
||||
## 内部流程概要
|
||||
|
||||
1. **模型解析** — `_resolve_fal_model()` 读取 `config.yaml` 的 `image_gen.model`，否则看 `FAL_IMAGE_MODEL` 环境变量，再否则默认 `fal-ai/flux-2/klein/9b`。
|
||||
2. **构造请求体** — `_build_fal_payload()` 将 `aspect_ratio` 转为各模型枚举或字面量，合并默认参数与调用方覆盖，并按 `supports` 白名单过滤非法字段。
|
||||
3. **提交** — `_submit_fal_request()` 根据凭据走直连 FAL 或 Nous 托管网关。
|
||||
4. **超分** — 仅当模型元数据标记 `upscale: True` 时执行。
|
||||
5. **交付** — 最终图像 URL 返回给智能体，并发出 `MEDIA:<url>`，由各平台适配器转为原生媒体消息。
|
||||
|
||||
## 调试
|
||||
|
||||
打开调试日志：
|
||||
|
||||
```bash
|
||||
export IMAGE_TOOLS_DEBUG=true
|
||||
```
|
||||
|
||||
日志写入 `./logs/image_tools_debug_<session_id>.json`，包含每次调用的模型、参数、耗时与错误信息。
|
||||
|
||||
## 各平台展示
|
||||
|
||||
| 平台 | 行为 |
|
||||
|---|---|
|
||||
| **CLI** | 图像 URL 以 Markdown `` 打印，可点击打开 |
|
||||
| **Telegram** | 以图片消息发送，附提示词为说明 |
|
||||
| **Discord** | 嵌入消息 |
|
||||
| **Slack** | URL 由 Slack 展开预览 |
|
||||
| **WhatsApp** | 媒体消息 |
|
||||
| **其他** | 纯文本中的 URL |
|
||||
|
||||
## 限制
|
||||
|
||||
- **需要 FAL 凭据**（直连 `FAL_KEY` 或 Nous 订阅网关）
|
||||
- **仅文生图** — 不支持局部重绘、图生图或编辑类工作流
|
||||
- **临时 URL** — FAL 托管链接会在数小时至数天后过期；请自行落盘保存
|
||||
- **按模型能力裁剪** — 部分模型不支持 `seed`、`num_inference_steps` 等；`supports` 会静默丢弃不支持的参数，属预期行为
|
||||
+309
@@ -0,0 +1,309 @@
|
||||
# Kanban 教程
|
||||
|
||||
Hermes Kanban 系统所设计的四个使用场景的完整演示，需在浏览器中打开 dashboard。如果你还没有阅读 [Kanban 概述](./kanban)，请先从那里开始——本文假设你已了解 task（任务）、run（运行）、assignee（负责人）和 dispatcher（调度器）的概念。
|
||||
|
||||
## 准备工作
|
||||
|
||||
```bash
|
||||
hermes kanban init # 可选；首次执行 `hermes kanban <任何命令>` 会自动初始化
|
||||
hermes dashboard # 在浏览器中打开 http://127.0.0.1:9119
|
||||
# 点击左侧导航栏中的 Kanban
|
||||
```
|
||||
|
||||
dashboard 是**你**观察系统最便捷的地方。dispatcher 生成的 agent worker 不会看到 dashboard 或 CLI——它们通过专用的 `kanban_*` [工具集](./kanban#how-workers-interact-with-the-board)（`kanban_show`、`kanban_list`、`kanban_complete`、`kanban_block`、`kanban_heartbeat`、`kanban_comment`、`kanban_create`、`kanban_link`、`kanban_unblock`）来操作看板。三个界面——dashboard、CLI、worker 工具——都通过同一个每看板独立的 SQLite 数据库（默认看板为 `~/.hermes/kanban.db`，后续创建的任意看板为 `~/.hermes/kanban/boards/<slug>/kanban.db`）进行路由，因此无论变更来自哪一侧，每个看板的数据始终一致。
|
||||
|
||||
本教程全程使用 `default` 看板。如果你需要多个隔离队列（每个项目/仓库/领域一个），请参阅概述中的[看板（多项目）](./kanban#boards-multi-project)——相同的 CLI/dashboard/worker 流程适用于每个看板，且 worker 在物理上无法看到其他看板上的任务。
|
||||
|
||||
在本教程中，**标注为 `bash` 的代码块是*你*运行的命令。** 标注为 `# worker tool calls` 的代码块是生成的 worker 模型发出的工具调用——展示在这里是为了让你能端到端地了解整个循环，而不是让你自己去运行它们。
|
||||
|
||||
## 看板概览
|
||||
|
||||
|
||||
|
||||
从左到右共六列：
|
||||
|
||||
- **Triage（分类）** — 原始想法。默认情况下，dispatcher 会对此处的任务自动运行**分解器**（orchestrator 驱动的扇出）：它读取你的 profile 名册和描述，生成一张子任务图，将任务路由给最合适的专家，同时保持原始任务作为父任务存活，以便在所有子任务完成后 orchestrator 重新唤醒来判断完成情况。点击 kanban 页面顶部的 **Orchestration: Auto/Manual** 切换按钮来切换模式。在 Manual 模式下（或没有 orchestrator profile 的配置中），点击卡片上的 **⚗ Decompose**，或运行 `hermes kanban decompose <id>` / `/kanban decompose <id>`。对于不需要扇出的单个任务，**✨ Specify** 会进行一次性规格重写（目标、方法、验收标准）并将任务提升到 `todo`。在 `config.yaml` 的 `auxiliary.kanban_decomposer` 和 `auxiliary.triage_specifier` 下配置相关模型。参见主 Kanban 指南中的[自动与手动编排](./kanban#auto-vs-manual-orchestration)。
|
||||
- **Todo（待办）** — 已创建但等待依赖项，或尚未分配。
|
||||
- **Ready（就绪）** — 已分配，等待 dispatcher 认领。
|
||||
- **In progress（进行中）** — worker 正在主动执行任务。开启"Lanes by profile"（默认开启）时，此列按负责人分组，让你一眼看出每个 worker 正在做什么。
|
||||
- **Blocked（阻塞）** — worker 请求人工输入，或熔断器触发。
|
||||
- **Done（完成）** — 已完成。
|
||||
|
||||
顶部栏提供搜索、租户和负责人的筛选器，以及 `Lanes by profile` 切换按钮和 `Nudge dispatcher` 按钮——后者会立即执行一次调度 tick，而无需等待守护进程的下一个间隔。点击任意卡片会在右侧打开其详情抽屉。
|
||||
|
||||
### 平铺视图
|
||||
|
||||
如果 profile 泳道显示过于嘈杂，关闭"Lanes by profile"，In Progress 列会折叠为按认领时间排序的单一平铺列表：
|
||||
|
||||
|
||||
|
||||
## 场景一 — 独立开发者交付功能
|
||||
|
||||
你正在开发一个功能。经典流程：设计 schema、实现 API、编写测试。三个任务，具有父→子依赖关系。
|
||||
|
||||
```bash
|
||||
SCHEMA=$(hermes kanban create "Design auth schema" \
|
||||
--assignee backend-dev --tenant auth-project --priority 2 \
|
||||
--body "Design the user/session/token schema for the auth module." \
|
||||
--json | jq -r .id)
|
||||
|
||||
API=$(hermes kanban create "Implement auth API endpoints" \
|
||||
--assignee backend-dev --tenant auth-project --priority 2 \
|
||||
--parent $SCHEMA \
|
||||
--body "POST /register, POST /login, POST /refresh, POST /logout." \
|
||||
--json | jq -r .id)
|
||||
|
||||
hermes kanban create "Write auth integration tests" \
|
||||
--assignee qa-dev --tenant auth-project --priority 2 \
|
||||
--parent $API \
|
||||
--body "Cover happy path, wrong password, expired token, concurrent refresh."
|
||||
```
|
||||
|
||||
由于 `API` 以 `SCHEMA` 为父任务，`tests` 以 `API` 为父任务，只有 `SCHEMA` 从 `ready` 状态开始。其他两个任务在 `todo` 中等待，直到其父任务完成。这正是依赖提升引擎在发挥作用——在有 API 可测试之前，不会有其他 worker 去接手测试编写工作。
|
||||
|
||||
在下一次 dispatcher tick 时（默认 60 秒，或点击 **Nudge dispatcher** 立即触发），`backend-dev` profile 会以 `HERMES_KANBAN_TASK=$SCHEMA` 作为环境变量生成一个 worker。以下是该 worker 在 agent 内部的工具调用循环：
|
||||
|
||||
```python
|
||||
# worker tool calls — NOT commands you run
|
||||
kanban_show()
|
||||
# → 返回 title、body、worker_context、parents、prior attempts、comments
|
||||
|
||||
# （worker 读取 worker_context，使用终端/文件工具设计 schema，
|
||||
# 编写迁移脚本，运行自身检查，提交——真正的工作在这里发生）
|
||||
|
||||
kanban_heartbeat(note="schema drafted, writing migrations now")
|
||||
|
||||
kanban_complete(
|
||||
summary="users(id, email, pw_hash), sessions(id, user_id, jti, expires_at); "
|
||||
"refresh tokens stored as sessions with type='refresh'",
|
||||
metadata={
|
||||
"changed_files": ["migrations/001_users.sql", "migrations/002_sessions.sql"],
|
||||
"decisions": ["bcrypt for hashing", "JWT for session tokens",
|
||||
"7-day refresh, 15-min access"],
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
`kanban_show` 默认将 `task_id` 设为 `$HERMES_KANBAN_TASK`，因此 worker 无需知道自己的 id。`kanban_complete` 将 summary 和 metadata 写入当前 `task_runs` 行，关闭该 run，并将任务转换为 `done`——全部通过 `kanban_db` 以原子方式完成。
|
||||
|
||||
当 `SCHEMA` 进入 `done` 状态时，依赖引擎会自动将 `API` 提升为 `ready`。API worker 认领任务后，调用 `kanban_show()` 时会看到 `SCHEMA` 的 summary 和 metadata 附加在父任务交接信息中——因此它无需重新阅读冗长的设计文档就能了解 schema 的决策。
|
||||
|
||||
在看板上点击已完成的 schema 任务，抽屉会显示所有信息：
|
||||
|
||||
|
||||
|
||||
底部的 Run History 部分是关键新增内容。一次尝试：结果 `completed`，worker `@backend-dev`，耗时、时间戳，以及完整的交接 summary。metadata 块（`changed_files`、`decisions`）也存储在 run 上，并会呈现给读取该父任务的任何下游 worker。
|
||||
|
||||
你可以随时在终端检查相同的数据——以下命令是**你**查看看板，而非 worker 执行：
|
||||
|
||||
```bash
|
||||
hermes kanban show $SCHEMA
|
||||
hermes kanban runs $SCHEMA
|
||||
# # OUTCOME PROFILE ELAPSED STARTED
|
||||
# 1 completed backend-dev 0s 2026-04-27 19:34
|
||||
# → users(id, email, pw_hash), sessions(id, user_id, jti, expires_at); refresh tokens ...
|
||||
```
|
||||
|
||||
## 场景二 — 集群并行处理
|
||||
|
||||
你有三个 worker（翻译员、转录员、文案撰写员）和一批相互独立的任务。你希望三者并行拉取任务并产生可见进展。这是最简单的 kanban 使用场景，也是最初设计所优化的场景。
|
||||
|
||||
创建工作任务：
|
||||
|
||||
```bash
|
||||
for lang in Spanish French German; do
|
||||
hermes kanban create "Translate homepage to $lang" \
|
||||
--assignee translator --tenant content-ops
|
||||
done
|
||||
for i in 1 2 3 4 5; do
|
||||
hermes kanban create "Transcribe Q3 customer call #$i" \
|
||||
--assignee transcriber --tenant content-ops
|
||||
done
|
||||
for sku in 1001 1002 1003 1004; do
|
||||
hermes kanban create "Generate product description: SKU-$sku" \
|
||||
--assignee copywriter --tenant content-ops
|
||||
done
|
||||
```
|
||||
|
||||
启动 gateway 然后离开——它托管内嵌的 dispatcher，
|
||||
在同一个 kanban.db 上处理三个专家 profile 的任务：
|
||||
|
||||
```bash
|
||||
hermes gateway start
|
||||
```
|
||||
|
||||
现在将看板筛选到 `content-ops`（或直接搜索"Transcribe"），你会看到：
|
||||
|
||||
|
||||
|
||||
两个转录任务已完成，一个正在运行，两个就绪等待下一次 dispatcher tick。In Progress 列按 profile 分组（"Lanes by profile"默认开启），让你无需扫描混合列表即可看到每个 worker 的当前任务。dispatcher 会在当前任务完成后立即将下一个就绪任务提升为运行中。三个守护进程并行处理三个负责人池，整个内容队列无需进一步人工干预即可清空。
|
||||
|
||||
**场景一中关于结构化交接的所有内容在这里同样适用。** 完成一次通话的翻译 worker 会发出 `kanban_complete(summary="translated 4 pages, style matched existing marketing voice", metadata={"duration_seconds": 720, "tokens_used": 2100})`——对分析以及依赖此任务的任何下游任务都很有价值。
|
||||
|
||||
## 场景三 — 角色流水线与重试
|
||||
|
||||
这正是 Kanban 相比普通 TODO 列表的价值所在。PM 编写规格说明，工程师实现，审查者拒绝第一次尝试，工程师修改后再次尝试，审查者批准。
|
||||
|
||||
dashboard 视图，按 `auth-project` 筛选：
|
||||
|
||||
|
||||
|
||||
三个阶段的链条一目了然：`Spec: password reset flow`（DONE，pm）、`Implement password reset flow`（DONE，backend-dev）、`Review password reset PR`（READY，reviewer）。每个任务底部都有绿色的父任务，以及作为依赖项的子任务。
|
||||
|
||||
最有趣的是实现任务，因为它经历了阻塞和重试。以下是完整的三 agent 协作流程，以每个 worker 模型发出的工具调用形式展示：
|
||||
|
||||
```python
|
||||
# --- PM worker 在 $SPEC 上生成并编写验收标准 ---
|
||||
# worker tool calls
|
||||
kanban_show()
|
||||
kanban_complete(
|
||||
summary="spec approved; POST /forgot-password sends email, "
|
||||
"GET /reset/:token renders form, POST /reset applies new password",
|
||||
metadata={"acceptance": [
|
||||
"expired token returns 410",
|
||||
"reused last-3 password returns 400 with message",
|
||||
"successful reset invalidates all active sessions",
|
||||
]},
|
||||
)
|
||||
# → $SPEC 完成；$IMPL 自动从 todo 提升为 ready
|
||||
|
||||
# --- 工程师 worker 在 $IMPL 上生成（第一次尝试）---
|
||||
# worker tool calls
|
||||
kanban_show() # 在 worker_context 中读取 $SPEC 的 summary 和 acceptance metadata
|
||||
# （工程师编写代码，运行测试，开启 PR）
|
||||
# 审查者反馈到来——工程师认为问题有效并阻塞任务
|
||||
kanban_block(
|
||||
reason="Review: password strength check missing, reset link isn't "
|
||||
"single-use (can be replayed within 30min)",
|
||||
)
|
||||
# → $IMPL 转换为 blocked；run 1 以 outcome='blocked' 关闭
|
||||
```
|
||||
|
||||
现在你（人类，或单独的 reviewer profile）读取阻塞原因，判断修复方向明确，从 dashboard 的"Unblock"按钮解除阻塞——或通过 CLI/斜杠命令：
|
||||
|
||||
```bash
|
||||
hermes kanban unblock $IMPL
|
||||
# 或在聊天中：/kanban unblock $IMPL
|
||||
```
|
||||
|
||||
dispatcher 将 `$IMPL` 提升回 `ready`，并在下一次 tick 时重新生成 `backend-dev` worker。这第二次生成是同一任务上的**新 run**：
|
||||
|
||||
```python
|
||||
# --- 工程师 worker 在 $IMPL 上生成（第二次尝试）---
|
||||
# worker tool calls
|
||||
kanban_show()
|
||||
# → worker_context 现在包含 run 1 的阻塞原因，因此该 worker 知道
|
||||
# 需要修复哪两个问题，而无需重新阅读整个规格说明
|
||||
# （工程师添加 zxcvbn 检查，使重置令牌变为一次性，重新运行测试）
|
||||
kanban_complete(
|
||||
summary="added zxcvbn strength check, reset tokens are now single-use "
|
||||
"(stored + deleted on success)",
|
||||
metadata={
|
||||
"changed_files": [
|
||||
"auth/reset.py",
|
||||
"auth/tests/test_reset.py",
|
||||
"migrations/003_single_use_reset_tokens.sql",
|
||||
],
|
||||
"tests_run": 11,
|
||||
"review_iteration": 2,
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
点击实现任务，抽屉显示**两次尝试**：
|
||||
|
||||
|
||||
|
||||
- **Run 1** — `@backend-dev` 标记为 `blocked`。审查反馈紧跟在结果下方："password strength check missing, reset link isn't single-use (can be replayed within 30min)"。
|
||||
- **Run 2** — `@backend-dev` 标记为 `completed`。全新的 summary，全新的 metadata。
|
||||
|
||||
每个 run 在 `task_runs` 中都是独立的一行，有自己的 outcome、summary 和 metadata。重试历史不是叠加在"最新状态"任务之上的概念性附加物——它是主要的数据表示形式。当重试的 worker 打开任务时，`build_worker_context` 会向其展示之前的尝试，因此第二次 worker 能看到第一次被阻塞的原因，并针对性地解决那些具体问题，而不是从头重来。
|
||||
|
||||
审查者接下来认领任务。当他们打开 `Review password reset PR` 时，会看到：
|
||||
|
||||
|
||||
|
||||
父任务链接指向已完成的实现任务。当审查者的 worker 在 `Review password reset PR` 上生成并调用 `kanban_show()` 时，返回的 `worker_context` 包含父任务最近一次已完成 run 的 summary 和 metadata——因此审查者在查看 diff 之前就已读到"added zxcvbn strength check, reset tokens are now single-use"，并掌握了变更文件列表。
|
||||
|
||||
## 场景四 — 熔断器与崩溃恢复
|
||||
|
||||
真实的 worker 会失败。缺少凭证、OOM 终止、瞬时网络错误。dispatcher 有两道防线：**熔断器**（circuit breaker）在连续 N 次失败后自动阻塞任务，防止看板无限抖动；**崩溃检测**（crash detection）在 worker PID 于 TTL 到期前消失时回收任务。
|
||||
|
||||
### 熔断器 — 持续性失败
|
||||
|
||||
一个因 profile 环境中未设置 `AWS_ACCESS_KEY_ID` 而无法生成 worker 的部署任务：
|
||||
|
||||
```bash
|
||||
hermes kanban create "Deploy to staging (missing creds)" \
|
||||
--assignee deploy-bot --tenant ops \
|
||||
--max-retries 3
|
||||
```
|
||||
|
||||
dispatcher 尝试生成 worker。生成失败（`RuntimeError: AWS_ACCESS_KEY_ID not set`）。dispatcher 释放认领，递增失败计数器，并在下一次 tick 重试。由于本示例设置了 `--max-retries 3`，在三次连续失败后熔断器触发：任务进入 `blocked` 状态，outcome 为 `gave_up`。如果省略该标志，Hermes 使用 `kanban.failure_limit`（默认值：2）。在人工解除阻塞之前不再重试。
|
||||
|
||||
点击被阻塞的任务：
|
||||
|
||||
|
||||
|
||||
三个 run，`error` 字段均为相同错误。前两个为 `spawn_failed`（可重试），第三个为 `gave_up`（终止）。上方的事件日志显示完整序列：`created → claimed → spawn_failed → claimed → spawn_failed → claimed → gave_up`。
|
||||
|
||||
在终端：
|
||||
|
||||
```bash
|
||||
hermes kanban runs t_ef5d
|
||||
# # OUTCOME PROFILE ELAPSED STARTED
|
||||
# 1 spawn_failed deploy-bot 0s 2026-04-27 19:34
|
||||
# ! AWS_ACCESS_KEY_ID not set in deploy-bot env
|
||||
# 2 spawn_failed deploy-bot 0s 2026-04-27 19:34
|
||||
# ! AWS_ACCESS_KEY_ID not set in deploy-bot env
|
||||
# 3 gave_up deploy-bot 0s 2026-04-27 19:34
|
||||
# ! AWS_ACCESS_KEY_ID not set in deploy-bot env
|
||||
```
|
||||
|
||||
如果接入了 Telegram/Discord/Slack，gateway 会在 `gave_up` 事件时发送通知，让你无需主动检查看板就能得知故障。
|
||||
|
||||
### 崩溃恢复 — worker 在运行中途死亡
|
||||
|
||||
有时生成成功，但 worker 进程在之后死亡——段错误、OOM、`systemctl stop`。dispatcher 轮询 `kill(pid, 0)` 检测到死亡的 pid；认领释放，任务回到 `ready`，下一次 tick 将其分配给新的 worker。
|
||||
|
||||
种子数据中的示例是一个因内存不足而运行失败的迁移任务：
|
||||
|
||||
```bash
|
||||
# Worker 认领，开始扫描 240 万行，在约 230 万行时被 OOM 终止
|
||||
# Dispatcher 检测到死亡的 pid，释放认领，递增尝试计数器
|
||||
# 使用分块策略重试成功
|
||||
```
|
||||
|
||||
抽屉显示完整的两次尝试历史：
|
||||
|
||||
|
||||
|
||||
Run 1 — `crashed`，错误为 `OOM kill at row 2.3M (process 99999 gone)`。Run 2 — `completed`，metadata 中包含 `"strategy": "chunked with LIMIT + WHERE id > last_id"`。重试的 worker 在其上下文中看到了 run 1 的崩溃信息，并选择了更安全的策略；metadata 让未来的观察者（或事后分析撰写者）能清楚地看到发生了什么变化。
|
||||
|
||||
## 结构化交接 — `summary` 和 `metadata` 的重要性
|
||||
|
||||
在上述每个场景中，worker 在结束时都调用了 `kanban_complete(summary=..., metadata=...)`。这不是装饰性的——它是工作流各阶段之间的主要交接通道。
|
||||
|
||||
当任务 B 上的 worker 被生成并调用 `kanban_show()` 时，返回的 `worker_context` 包含：
|
||||
|
||||
- B 的**先前尝试**（之前的 run：outcome、summary、error、metadata），让重试的 worker 不会重蹈失败的路径。
|
||||
- **父任务结果** — 对于每个父任务，最近一次已完成 run 的 summary 和 metadata——让下游 worker 能看到上游工作的原因和方式。
|
||||
|
||||
这取代了平面 kanban 系统中"翻查评论和工作输出"的繁琐流程。PM 在规格说明的 metadata 中编写验收标准，工程师的 worker 在父任务交接中以结构化形式看到它们。工程师记录运行了哪些测试以及通过了多少，审查者的 worker 在打开 diff 之前就已掌握该列表。
|
||||
|
||||
批量关闭保护的存在正是因为这些数据是按 run 存储的。`hermes kanban complete a b c --summary X`（你，从 CLI 执行）会被拒绝——将相同的 summary 复制粘贴到三个任务几乎总是错误的。不带交接标志的批量关闭仍然适用于常见的"我完成了一堆行政任务"场景。工具界面根本不提供批量变体；`kanban_complete` 始终是单任务操作，原因相同。
|
||||
|
||||
## 检查当前正在运行的任务
|
||||
|
||||
作为补充——以下是一个仍在执行中的任务的抽屉视图（场景一中的 API 实现，已被 `backend-dev` 认领但尚未完成）：
|
||||
|
||||
|
||||
|
||||
状态为 `Running`。活跃的 run 出现在 Run History 部分，outcome 为 `active`，没有 `ended_at`。如果该 worker 死亡或超时，dispatcher 会以相应的 outcome 关闭此 run，并在下一次认领时开启新的 run——尝试记录永远不会消失。
|
||||
|
||||
## 后续步骤
|
||||
|
||||
- [Kanban 概述](./kanban) — 完整的数据模型、事件词汇表和 CLI 参考。
|
||||
- `hermes kanban --help` — 所有子命令，所有标志。
|
||||
- `hermes kanban watch --kinds completed,gave_up,timed_out` — 在整个看板上实时流式输出终端事件。
|
||||
- `hermes kanban notify-subscribe <task> --platform telegram --chat-id <id>` — 当特定任务完成时通过 gateway 接收推送通知。
|
||||
+114
@@ -0,0 +1,114 @@
|
||||
# Kanban worker lanes（工作者通道）
|
||||
|
||||
**worker lane**（工作者通道）是 kanban 调度器可以将任务路由到的一类进程。每个通道都有一个标识（assignee 字符串）、一个生成机制，以及一份关于生成后必须如何处理任务的契约。
|
||||
|
||||
本页即为该契约，面向两类读者：
|
||||
|
||||
- **运维人员**：选择将哪些通道接入看板（创建哪些 profile，使用哪些 assignee）。
|
||||
- **插件/集成作者**：希望添加新的通道形态（封装 Codex / Claude Code / OpenCode 的 CLI worker、容器化审查 worker、通过 API 拉取任务的非 Hermes 服务）。
|
||||
|
||||
如果你编写的是 worker 代码本身——即运行在通道*内部*的 agent——请参阅 [`kanban-worker`](https://github.com/NousResearch/hermes-agent/blob/main/skills/devops/kanban-worker/SKILL.md) skill，其中包含更深入的操作细节。
|
||||
|
||||
## 层级结构
|
||||
|
||||
```text
|
||||
Hermes Kanban = 规范的任务生命周期 + 审计追踪
|
||||
Worker lane = 某张已分配卡片的实现执行器
|
||||
Reviewer = 人工或人工代理，负责把关"完成"状态
|
||||
GitHub PR = 可上游的产物（可选，适用于代码通道）
|
||||
```
|
||||
|
||||
Hermes Kanban 拥有生命周期的真实状态——`ready` → `running` → `blocked` / `done` / `archived`。Worker lane 执行工作，但从不拥有该真实状态；它们所做的一切都通过 `kanban_*` 工具回流至 kanban 内核（对于非 Hermes 外部 worker，则通过 API）。Reviewer 负责把关从"代码变更已写入"到"任务完成"的转换。
|
||||
|
||||
## 通道需提供的内容
|
||||
|
||||
要成为 kanban worker lane，集成必须提供三项内容：
|
||||
|
||||
### 1. assignee 字符串
|
||||
|
||||
调度器将 `task.assignee` 与 Hermes profile 名称（默认通道形态）或已注册的不可生成标识符（插件通道形态——见下文[添加外部 CLI worker 通道](#adding-an-external-cli-worker-lane)）进行匹配。assignee 无法解析的任务将保留在 `ready` 状态，并记录 `skipped_nonspawnable` 事件，以便看板运维人员修复；它们不会被静默丢弃，也不会由任意回退逻辑执行。
|
||||
|
||||
### 2. 生成机制
|
||||
|
||||
对于 Hermes profile 通道，调度器的 `_default_spawn` 会在任务固定的工作区内运行 `hermes -p <assignee> chat -q <prompt>`（或当 `hermes` shim 不在 `$PATH` 时使用等效的模块形式），并设置以下环境变量：
|
||||
|
||||
| 变量 | 携带内容 |
|
||||
|---|---|
|
||||
| `HERMES_KANBAN_TASK` | worker 正在操作的任务 id |
|
||||
| `HERMES_KANBAN_DB` | 每个看板 SQLite 文件的绝对路径 |
|
||||
| `HERMES_KANBAN_BOARD` | 看板 slug |
|
||||
| `HERMES_KANBAN_WORKSPACES_ROOT` | 看板工作区树的根目录 |
|
||||
| `HERMES_KANBAN_WORKSPACE` | *本*任务工作区的绝对路径 |
|
||||
| `HERMES_KANBAN_RUN_ID` | 当前运行的 id（用于生命周期门控） |
|
||||
| `HERMES_KANBAN_CLAIM_LOCK` | claim 锁字符串（`<host>:<pid>:<uuid>`） |
|
||||
| `HERMES_PROFILE` | worker 自身的 profile 名称（用于 `kanban_comment` 作者归因） |
|
||||
| `HERMES_TENANT` | 租户命名空间（如果任务有的话） |
|
||||
|
||||
对于非 Hermes 通道（通过插件注册），插件提供自己的 `spawn_fn` 可调用对象，接收 `task`、`workspace` 和 `board`，并返回可选的 pid 用于崩溃检测。
|
||||
|
||||
### 3. 生命周期终止器
|
||||
|
||||
每次 claim 必须以以下之一结束：
|
||||
|
||||
- `kanban_complete(summary=..., metadata=...)` — 任务成功，状态切换为 `done`。
|
||||
- `kanban_block(reason=...)` — 任务等待人工输入，状态切换为 `blocked`。调度器在 `kanban_unblock` 运行时重新生成。
|
||||
- worker 进程退出而未调用任何工具。内核回收该进程并发出 `crashed`（PID 已消亡）、`gave_up`（连续失败断路器触发）或 `timed_out`（超过 max_runtime）。这是失败路径；健康的 worker 不会在此结束。
|
||||
|
||||
kanban 内核强制要求每次运行恰好由其中一项终止。既未调用任何终止工具又正常退出的 worker 将被视为崩溃。
|
||||
|
||||
## 输出与 review-required 约定
|
||||
|
||||
对于大多数涉及代码变更的任务，worker 完成的那一刻并不意味着真正*完成*——还需要人工审查。kanban 内核不强制执行这一区分（"涉及代码变更的任务"定义模糊，且在每个代码 worker 上强制 block 而非 complete 会破坏不需要审查的流程）。这是叠加在上层的约定：
|
||||
|
||||
- **使用 block 而非 complete**，`reason` 以 `review-required: ` 为前缀，使仪表板 / `hermes kanban show` 将该行显示为等待审查。
|
||||
- **先将结构化元数据写入 `kanban_comment`**，因为 `kanban_block` 只携带人类可读的 `reason`。Comment 是持久的注解通道——所有与审计相关的字段（changed_files、tests_run、diff_path 或 PR url、决策记录）都应放在这里。
|
||||
- **Reviewer 批准并解除阻塞**，这将重新生成 worker 并附带 comment 线程用于后续跟进；或通过另一条 comment 要求修改，下一次 worker 运行时将通过 `kanban_show` 的上下文看到这些内容。
|
||||
|
||||
[`kanban-worker`](https://github.com/NousResearch/hermes-agent/blob/main/skills/devops/kanban-worker/SKILL.md) skill 中有 `kanban_complete`（真正终态的任务——拼写修复、文档变更、研究报告）和 `review-required` block 模式的完整示例。
|
||||
|
||||
## 日志与审计追踪
|
||||
|
||||
调度器将每个任务的 worker stdout/stderr 写入 `<board-root>/logs/<task_id>.log`。日志可通过 kanban 元数据进行审计：
|
||||
|
||||
- `task_runs` 行携带 `log_path`、退出码（如有）、摘要和元数据。
|
||||
- `task_events` 行携带每次状态转换（`promoted`、`claimed`、`heartbeat`、`completed`、`blocked`、`gave_up`、`crashed`、`timed_out`、`reclaimed`、`claim_extended`）。
|
||||
- `kanban_show` 同时返回两者，因此 reviewer（或后续 worker）读取任务时无需访问仪表板即可获得完整历史。
|
||||
|
||||
仪表板以摘要、元数据块和退出状态徽章渲染运行历史。CLI 用户可运行 `hermes kanban tail <task_id>` 实时跟踪，或运行 `hermes kanban runs <task_id>` 查看历史尝试列表。
|
||||
|
||||
## 现有通道形态
|
||||
|
||||
### Hermes profile 通道（默认）
|
||||
|
||||
当前所有 kanban worker 采用的形态：assignee 是 profile 名称，调度器生成 `hermes -p <profile>`，worker 自动加载 [`kanban-worker`](https://github.com/NousResearch/hermes-agent/blob/main/skills/devops/kanban-worker/SKILL.md) skill 以及 `KANBAN_GUIDANCE` 系统提示块，并使用 `kanban_*` 工具终止运行。除定义 profile 外无需任何额外配置。
|
||||
|
||||
为你的 fleet 创建 profile 时，选择与你希望 orchestrator 路由到的*角色*相匹配的名称。orchestrator（如果存在）通过 `hermes profile list` 发现你的 profile 名称——系统不假设固定的名单（orchestrator 侧的契约请参阅 [`kanban-orchestrator`](https://github.com/NousResearch/hermes-agent/blob/main/skills/devops/kanban-orchestrator/SKILL.md) skill）。
|
||||
|
||||
### Orchestrator profile 通道
|
||||
|
||||
profile 通道的特化形态：orchestrator 是一个 Hermes profile，其工具集包含 `kanban`，但排除了用于实现的 `terminal` / `file` / `code` / `web`。其职责是通过 `kanban_create` + `kanban_link` 将高层目标分解为子任务，然后退出。orchestrator skill 编码了反诱惑规则。
|
||||
|
||||
## 添加外部 CLI worker 通道
|
||||
|
||||
将非 Hermes CLI 工具（Codex CLI、Claude Code CLI、OpenCode CLI、本地编码模型运行器等）接入 kanban worker 通道*尚未形成成熟路径*。调度器的 spawn 函数是可插拔的（`spawn_fn` 是 `dispatch_once` 的参数），插件可以为非 Hermes assignee 注册自己的 `spawn_fn`，但周边集成工作——将 CLI 的退出码封装为 `kanban_complete` / `kanban_block` 调用、将 CLI 的工作区/沙箱约定映射到调度器的 `HERMES_KANBAN_WORKSPACE` 环境变量、处理认证和每个 CLI 的策略——仍是每个集成各自的设计工作。
|
||||
|
||||
如果你考虑添加 CLI 通道，请提交一个 issue，描述具体的 CLI 以及你希望实现的工作流。上述契约是任何此类通道必须满足的约束；实现形态（每个 CLI 一个插件，还是通过配置参数化的通用 CLI 运行器插件）尚未确定。
|
||||
|
||||
相关历史 issue 为 [#19931](https://github.com/NousResearch/hermes-agent/issues/19931)，以及已关闭未合并的 Codex 专项 PR [#19924](https://github.com/NousResearch/hermes-agent/pull/19924)——这些描述了原始架构提案，但未落地运行器。
|
||||
|
||||
## 调度器处理的失败模式
|
||||
|
||||
通道作者无需重新实现以下逻辑：
|
||||
|
||||
- **Claim TTL 过期** — 已 claim 但从未心跳/完成/阻塞的 worker 在 `DEFAULT_CLAIM_TTL_SECONDS`（默认 15 分钟）后被回收——但仅当 worker 进程确实已死亡时。存活的 worker（慢速模型在一次无工具调用的 LLM 调用中耗时 20 分钟以上）会获得 claim *延期*而非被终止；只有 PID 已消亡时才会被回收。
|
||||
- **Worker 崩溃** — 宿主本地 PID 已消失的 worker 由 `detect_crashed_workers` 检测并回收；任务的 `consecutive_failures` 递增，断路器触发时可能自动阻塞。
|
||||
- **运行级重试** — 任务重试时（post-block、post-crash、post-reclaim），worker 可在终止工具上使用 `expected_run_id` 参数，在自身运行已被取代时快速失败。
|
||||
- **每任务最大运行时间** — `task.max_runtime_seconds` 对每次运行的挂钟时间进行硬性限制，与 PID 存活状态无关。可捕获真正死锁的 worker——否则存活 PID 延期机制会让其持续运行。
|
||||
- **滞留任务检测** — assignee 在 `kanban.stranded_threshold_seconds`（默认 30 分钟）内始终未产生 claim 的 ready 任务，会在 `hermes kanban diagnostics` 中显示为 `stranded_in_ready` 警告。严重程度在 2 倍阈值时升级为 error，在 6 倍时升级为 critical。可通过单一信号捕获拼写错误的 assignee、已删除的 profile 以及宕机的外部 worker 池——与标识无关，无需维护每个看板的白名单。
|
||||
|
||||
## 相关资源
|
||||
|
||||
- [Kanban 概览](./kanban) — 面向用户的介绍。
|
||||
- [Kanban 教程](./kanban-tutorial) — 开启仪表板的完整演练。
|
||||
- [`kanban-worker`](https://github.com/NousResearch/hermes-agent/blob/main/skills/devops/kanban-worker/SKILL.md) — worker 进程加载的 skill。
|
||||
- [`kanban-orchestrator`](https://github.com/NousResearch/hermes-agent/blob/main/skills/devops/kanban-orchestrator/SKILL.md) — orchestrator 侧。
|
||||
+792
@@ -0,0 +1,792 @@
|
||||
---
|
||||
sidebar_position: 12
|
||||
title: "Kanban（多 Agent 看板）"
|
||||
description: "基于 SQLite 的持久化任务看板，用于协调多个 Hermes 配置文件"
|
||||
---
|
||||
|
||||
# Kanban — 多 Agent 配置文件协作
|
||||
|
||||
> **想要详细教程？** 请阅读 [Kanban 教程](./kanban-tutorial) —— 包含四个用户故事（独立开发者、批量任务、带重试的角色流水线、熔断器），并附有各场景的仪表盘截图。本页是参考文档，教程是叙述性说明。
|
||||
|
||||
Hermes Kanban 是一个持久化任务看板，在所有 Hermes 配置文件之间共享，允许多个具名 agent 协作完成工作，而无需脆弱的进程内子 agent 集群。每个任务都是 `~/.hermes/kanban.db` 中的一行记录；每次交接都是任何人都可以读写的一行记录；每个 worker 都是拥有独立身份的完整 OS 进程。
|
||||
|
||||
### 两个操作界面：模型通过工具交互，你通过 CLI 交互
|
||||
|
||||
看板有两个入口，均由同一个 `~/.hermes/kanban.db` 支撑：
|
||||
|
||||
- **Agent 通过专用 `kanban_*` 工具集驱动看板** —— `kanban_show`、`kanban_list`、`kanban_complete`、`kanban_block`、`kanban_heartbeat`、`kanban_comment`、`kanban_create`、`kanban_link`、`kanban_unblock`。调度器在 schema 中已内置这些工具来启动每个 worker；编排器（orchestrator）配置文件也可以通过 `kanban` 工具集显式启用。模型通过直接调用工具来读取和路由任务，*而不是*通过 shell 执行 `hermes kanban`。详见下方[Worker 如何与看板交互](#how-workers-interact-with-the-board)。
|
||||
- **你（以及脚本和 cron）通过 CLI 上的 `hermes kanban …`、斜杠命令 `/kanban …` 或仪表盘驱动看板。** 这些界面面向人类和自动化场景——即没有工具调用模型的场合。
|
||||
|
||||
两个界面都通过同一个 `kanban_db` 层路由，因此读取视图一致，写入不会产生偏差。本页其余部分展示 CLI 示例，因为它们便于复制粘贴，但每个 CLI 动词都有模型使用的等效工具调用。
|
||||
|
||||
这种形态覆盖了 `delegate_task` 无法处理的工作负载：
|
||||
|
||||
- **研究分诊** —— 并行研究员 + 分析师 + 写作者，支持人工介入。
|
||||
- **定时运维** —— 每日定期简报，逐周积累日志。
|
||||
- **数字孪生** —— 持久化具名助手（`inbox-triage`、`ops-review`），随时间积累记忆。
|
||||
- **工程流水线** —— 分解 → 在并行 worktree 中实现 → 审查 → 迭代 → PR。
|
||||
- **批量任务** —— 一个专家管理 N 个对象（50 个社交账号、12 个监控服务）。
|
||||
|
||||
完整的设计原理、与 Cline Kanban / Paperclip / NanoClaw / Google Gemini Enterprise 的对比分析，以及八种典型协作模式，请参阅仓库中的 `docs/hermes-kanban-v1-spec.pdf`。
|
||||
|
||||
## Kanban 与 `delegate_task` 的对比
|
||||
|
||||
两者看起来相似，但并非同一原语。
|
||||
|
||||
| | `delegate_task` | Kanban |
|
||||
|---|---|---|
|
||||
| 形态 | RPC 调用（fork → join） | 持久化消息队列 + 状态机 |
|
||||
| 父级 | 阻塞直到子级返回 | `create` 后即发即忘 |
|
||||
| 子级身份 | 匿名子 agent | 具有持久记忆的具名配置文件 |
|
||||
| 可恢复性 | 无 —— 失败即失败 | 阻塞 → 解除阻塞 → 重新运行；崩溃 → 回收 |
|
||||
| 人工介入 | 不支持 | 随时可评论 / 解除阻塞 |
|
||||
| 每任务 agent 数 | 一次调用 = 一个子 agent | 任务生命周期内 N 个 agent（重试、审查、跟进） |
|
||||
| 审计追踪 | 上下文压缩后丢失 | 永久保存在 SQLite 行中 |
|
||||
| 协调方式 | 层级式（调用方 → 被调用方） | 对等式 —— 任意配置文件可读写任意任务 |
|
||||
|
||||
**一句话区别：** `delegate_task` 是函数调用；Kanban 是工作队列，每次交接都是任意配置文件（或人类）可见和编辑的一行记录。
|
||||
|
||||
**使用 `delegate_task` 的场景：** 父 agent 在继续之前需要一个简短的推理答案，无需人工介入，结果返回到父 agent 的上下文中。
|
||||
|
||||
**使用 Kanban 的场景：** 工作跨越 agent 边界、需要在重启后存活、可能需要人工输入、可能被不同角色接手，或需要事后可发现。
|
||||
|
||||
两者可以共存：kanban worker 在运行期间可以内部调用 `delegate_task`。
|
||||
|
||||
## 核心概念
|
||||
|
||||
- **Board（看板）** —— 一个独立的任务队列，拥有自己的 SQLite DB、工作区目录和调度器循环。单次安装可以有多个看板（例如每个项目、仓库或领域一个）；详见下方[看板（多项目）](#boards-multi-project)。单项目用户保持使用 `default` 看板，在本文档章节之外不会看到"board"这个词。
|
||||
- **Task（任务）** —— 包含标题、可选正文、一个受让人（配置文件名称）、状态（`triage | todo | ready | running | blocked | done | archived`）、可选租户命名空间、可选幂等键（用于重试自动化的去重）的一行记录。
|
||||
- **Link（链接）** —— `task_links` 行，记录父 → 子依赖关系。当所有父任务变为 `done` 时，调度器将 `todo → ready`。
|
||||
- **Comment（评论）** —— agent 间协议。Agent 和人类追加评论；当 worker 被（重新）启动时，它将完整的评论线程作为上下文的一部分读取。
|
||||
- **Workspace（工作区）** —— worker 操作的目录。三种类型：
|
||||
- `scratch`（默认）—— 在 `~/.hermes/kanban/workspaces/<id>/` 下（非默认看板为 `~/.hermes/kanban/boards/<slug>/workspaces/<id>/`）创建的临时目录。**任务完成时删除** —— scratch 是临时性的，worker（或 `hermes kanban complete <id>`）将任务标记为完成的那一刻，目录即被清除。如果想保留 worker 的输出，请使用 `worktree:` 或 `dir:<path>`。在某次安装中首次创建 scratch 工作区时，调度器会记录警告并在任务上发出 `tip_scratch_workspace` 事件（可通过 `hermes kanban show <id>` 查看）。
|
||||
- `dir:<path>` —— 现有的共享目录（Obsidian vault、邮件运维目录、每账号文件夹）。**必须是绝对路径。** 像 `dir:../tenants/foo/` 这样的相对路径在调度时会被拒绝，因为它们会相对于调度器碰巧所在的 CWD 解析，这是模糊的，也是混淆代理（confused-deputy）逃逸向量。路径本身是受信任的 —— 这是你的机器、你的文件系统，worker 以你的 uid 运行。这是受信任本地用户的威胁模型；kanban 设计为单主机。**完成时保留。**
|
||||
- `worktree` —— 用于编码任务的 git worktree，位于 `.worktrees/<id>/` 下。使用 `worktree:<path>` 固定确切的目标路径。Worker 端的 `git worktree add` 创建它，提供 `--branch` 时使用该分支。**完成时保留。**
|
||||
- **Dispatcher（调度器）** —— 一个长期运行的循环，每 N 秒（默认 60 秒）执行一次：回收过期的认领、回收崩溃的 worker（PID 消失但 TTL 尚未过期）、推进就绪任务、原子性认领、启动已分配的配置文件。默认**在 gateway 内部运行**（`kanban.dispatch_in_gateway: true`）。每次 tick 一个调度器扫描所有看板；worker 启动时固定了 `HERMES_KANBAN_BOARD`，因此无法看到其他看板。在同一任务上连续启动失败 `kanban.failure_limit` 次（默认：2）后，调度器会以最后一个错误为原因自动阻塞该任务 —— 防止因配置文件不存在、工作区无法挂载等原因导致的反复抖动。
|
||||
- **Tenant（租户）** —— 看板*内*的可选字符串命名空间。一个专家团队可以通过工作区路径和内存键前缀为多个业务提供数据隔离服务（`--tenant business-a`）。租户是软过滤器；看板是硬隔离边界。
|
||||
|
||||
## 看板（多项目） {#boards-multi-project}
|
||||
|
||||
看板让你将不相关的工作流分离到独立的队列中 —— 每个项目、仓库或领域一个。新安装只有一个名为 `default` 的看板（DB 位于 `~/.hermes/kanban.db`，保持向后兼容）。只需要一个工作流的用户无需了解看板；该功能是可选启用的。
|
||||
|
||||
每个看板的隔离是绝对的：
|
||||
|
||||
- 每个看板有独立的 SQLite DB（`~/.hermes/kanban/boards/<slug>/kanban.db`）。
|
||||
- 独立的 `workspaces/` 和 `logs/` 目录。
|
||||
- 为任务启动的 Worker 只能看到**其所在看板**的任务 —— 调度器在子进程环境中设置 `HERMES_KANBAN_BOARD`，worker 可访问的每个 `kanban_*` 工具都会读取它。
|
||||
- 不允许跨看板链接任务（保持 schema 简单；如果确实需要跨项目引用，请使用自由文本提及并通过 id 手动查找）。
|
||||
|
||||
### 通过 CLI 管理看板
|
||||
|
||||
```bash
|
||||
# 查看磁盘上的内容。全新安装只显示 "default"。
|
||||
hermes kanban boards list
|
||||
|
||||
# 创建新看板。
|
||||
hermes kanban boards create atm10-server \
|
||||
--name "ATM10 Server" \
|
||||
--description "Minecraft modded server ops" \
|
||||
--icon 🎮 \
|
||||
--switch # 可选：将其设为活动看板
|
||||
|
||||
# 在不切换的情况下操作特定看板。
|
||||
hermes kanban --board atm10-server list
|
||||
hermes kanban --board atm10-server create "Restart ATM server" --assignee ops
|
||||
|
||||
# 更改后续调用的"当前"看板。
|
||||
hermes kanban boards switch atm10-server
|
||||
hermes kanban boards show # 当前活动的是哪个？
|
||||
|
||||
# 重命名显示名称（slug 是不可变的 —— 它是目录名）。
|
||||
hermes kanban boards rename atm10-server "ATM10 (Prod)"
|
||||
|
||||
# 归档（默认）—— 将看板目录移动到 boards/_archived/<slug>-<ts>/。
|
||||
# 可通过将目录移回来恢复。
|
||||
hermes kanban boards rm atm10-server
|
||||
|
||||
# 硬删除 —— 对看板目录执行 `rm -rf`。无法恢复。
|
||||
hermes kanban boards rm atm10-server --delete
|
||||
```
|
||||
|
||||
看板解析顺序（优先级从高到低）：
|
||||
|
||||
1. CLI 调用中的显式 `--board <slug>`。
|
||||
2. `HERMES_KANBAN_BOARD` 环境变量（调度器在启动 worker 时设置，因此 worker 无法看到其他看板）。
|
||||
3. `~/.hermes/kanban/current` —— 由 `hermes kanban boards switch` 持久化的 slug。
|
||||
4. `default`。
|
||||
|
||||
Slug 经过验证：小写字母数字 + 连字符 + 下划线，1-64 个字符，必须以字母数字开头。大写输入会自动转为小写。其他任何内容（斜杠、空格、点、`..`）在 CLI 层被拒绝，以防止路径遍历技巧命名看板。
|
||||
|
||||
### 通过仪表盘管理看板
|
||||
|
||||
`hermes dashboard` → Kanban 标签页在存在多个看板（或任何看板有任务）时，顶部会显示看板切换器。单看板用户只看到一个小的 `+ New board` 按钮；切换器在需要时才显示。
|
||||
|
||||
- **看板下拉菜单** —— 选择活动看板。你的选择保存在浏览器的 `localStorage` 中，因此在重新加载后仍然有效，不会影响你打开的终端中 CLI 的 `current` 指针。
|
||||
- **+ New board** —— 打开一个模态框，询问 slug、显示名称、描述和图标。可选择自动切换到新看板。
|
||||
- **Archive** —— 仅在非 `default` 看板上显示。确认后，将看板目录移动到 `boards/_archived/`。
|
||||
|
||||
所有仪表盘 API 端点接受 `?board=<slug>` 进行看板范围限定。事件 WebSocket 在连接时固定到一个看板；在 UI 中切换会针对新看板打开一个新的 WS。
|
||||
|
||||
|
||||
## 快速开始
|
||||
|
||||
以下命令是**你**（人类）设置看板和创建任务的操作。一旦任务被分配，调度器就会将分配的配置文件作为 worker 启动，从那时起**模型通过 `kanban_*` 工具调用驱动任务，而不是 CLI 命令** —— 详见[Worker 如何与看板交互](#how-workers-interact-with-the-board)。
|
||||
|
||||
```bash
|
||||
# 1. 创建看板（你）
|
||||
hermes kanban init
|
||||
|
||||
# 2. 启动 gateway（托管内嵌调度器）
|
||||
hermes gateway start
|
||||
|
||||
# 3. 创建任务（你 —— 或编排器 agent 通过 kanban_create）
|
||||
hermes kanban create "research AI funding landscape" --assignee researcher
|
||||
|
||||
# 4. 实时查看活动（你）
|
||||
hermes kanban watch
|
||||
|
||||
# 5. 查看看板（你）
|
||||
hermes kanban list
|
||||
hermes kanban stats
|
||||
```
|
||||
|
||||
当调度器接管 `t_abcd` 并启动 `researcher` 配置文件时，该 worker 的模型做的第一件事是调用 `kanban_show()` 读取其任务。它不会运行 `hermes kanban show t_abcd`。
|
||||
|
||||
### Gateway 内嵌调度器（默认）
|
||||
|
||||
调度器在 gateway 进程内运行。无需安装任何东西，无需管理单独的服务 —— 只要 gateway 运行，就绪任务会在下一个 tick（默认 60 秒）被接管。
|
||||
|
||||
```yaml
|
||||
# config.yaml
|
||||
kanban:
|
||||
dispatch_in_gateway: true # 默认
|
||||
dispatch_interval_seconds: 60 # 默认
|
||||
```
|
||||
|
||||
通过 `HERMES_KANBAN_DISPATCH_IN_GATEWAY=0` 在运行时覆盖配置标志以进行调试。标准 gateway 监督适用：直接运行 `hermes gateway start`，或将 gateway 配置为 systemd 用户单元（参见 gateway 文档）。没有运行中的 gateway，`ready` 任务会保持原状，直到 gateway 启动 —— `hermes kanban create` 在创建时会对此发出警告。
|
||||
|
||||
将 `hermes kanban daemon` 作为单独进程运行已**弃用**；请使用 gateway。如果你确实无法运行 gateway（无头主机策略禁止长期运行的服务等），`--force` 逃生舱口在一个发布周期内保持旧的独立守护进程可用，但同时运行 gateway 内嵌调度器和针对同一 `kanban.db` 的独立守护进程会导致认领竞争，不受支持。
|
||||
|
||||
### 幂等创建（用于自动化 / webhook）
|
||||
|
||||
```bash
|
||||
# 第一次调用创建任务。使用相同键的任何后续调用
|
||||
# 返回现有任务 id 而不是重复创建。
|
||||
hermes kanban create "nightly ops review" \
|
||||
--assignee ops \
|
||||
--idempotency-key "nightly-ops-$(date -u +%Y-%m-%d)" \
|
||||
--json
|
||||
```
|
||||
|
||||
### 批量 CLI 动词
|
||||
|
||||
所有生命周期动词都接受多个 id，因此你可以在一个命令中清理一批任务：
|
||||
|
||||
```bash
|
||||
hermes kanban complete t_abc t_def t_hij --result "batch wrap"
|
||||
hermes kanban archive t_abc t_def t_hij
|
||||
hermes kanban unblock t_abc t_def
|
||||
hermes kanban block t_abc "need input" --ids t_def t_hij
|
||||
```
|
||||
|
||||
## Worker 如何与看板交互 {#how-workers-interact-with-the-board}
|
||||
|
||||
**Worker 不会 shell 执行 `hermes kanban`。** 当调度器启动 worker 时，它在子进程环境中设置 `HERMES_KANBAN_TASK=t_abcd`，该环境变量在模型的 schema 中启用专用的 **kanban 工具集**。同一工具集也可供在工具集配置中启用 `kanban` 的编排器配置文件使用。这些工具通过 Python `kanban_db` 层直接读取和修改看板，与 CLI 的做法相同。运行中的 worker 像调用任何其他工具一样调用这些工具；它从不看到或需要 `hermes kanban` CLI。
|
||||
|
||||
| 工具 | 用途 | 必需参数 |
|
||||
|---|---|---|
|
||||
| `kanban_show` | 读取当前任务（标题、正文、先前尝试、父级交接、评论、完整预格式化的 `worker_context`）。默认使用环境变量中的任务 id。 | — |
|
||||
| `kanban_list` | 列出带有 `assignee`、`status`、`tenant`、归档可见性和限制过滤器的任务摘要。供编排器发现看板工作使用。 | — |
|
||||
| `kanban_complete` | 以 `summary` + `metadata` 结构化交接完成任务。 | `summary` / `result` 至少一个 |
|
||||
| `kanban_block` | 以 `reason` 上报需要人工输入。 | `reason` |
|
||||
| `kanban_heartbeat` | 在长时间操作期间发出存活信号。纯副作用。 | — |
|
||||
| `kanban_comment` | 向任务线程追加持久化备注。 | `task_id`、`body` |
|
||||
| `kanban_create` | （编排器）将任务扇出为带有 `assignee`、可选 `parents`、`skills` 等的子任务。 | `title`、`assignee` |
|
||||
| `kanban_link` | （编排器）事后添加 `parent_id → child_id` 依赖边。 | `parent_id`、`child_id` |
|
||||
| `kanban_unblock` | （编排器）将被阻塞的任务移回 `ready`。 | `task_id` |
|
||||
|
||||
典型的 worker 轮次如下所示：
|
||||
|
||||
```
|
||||
# 模型的工具调用，按顺序：
|
||||
kanban_show() # 无参数 —— 使用 HERMES_KANBAN_TASK
|
||||
# （模型读取返回的 worker_context，通过终端/文件工具完成工作）
|
||||
kanban_heartbeat(note="halfway through — 4 of 8 files transformed")
|
||||
# （更多工作）
|
||||
kanban_complete(
|
||||
summary="migrated limiter.py to token-bucket; added 14 tests, all pass",
|
||||
metadata={"changed_files": ["limiter.py", "tests/test_limiter.py"], "tests_run": 14},
|
||||
)
|
||||
```
|
||||
|
||||
**编排器** worker 则进行扇出：
|
||||
|
||||
```
|
||||
kanban_show()
|
||||
kanban_create(
|
||||
title="research ICP funding 2024-2026",
|
||||
assignee="researcher-a",
|
||||
body="focus on seed + series A, North America, AI-adjacent",
|
||||
)
|
||||
# → 返回 {"task_id": "t_r1", ...}
|
||||
kanban_create(title="research ICP funding — EU angle", assignee="researcher-b", body="…")
|
||||
# → 返回 {"task_id": "t_r2", ...}
|
||||
kanban_create(
|
||||
title="synthesize findings into launch brief",
|
||||
assignee="writer",
|
||||
parents=["t_r1", "t_r2"], # 两者都完成时推进到 ready
|
||||
body="one-pager, 300 words, neutral tone",
|
||||
)
|
||||
kanban_complete(summary="decomposed into 2 research tasks + 1 writer; linked dependencies")
|
||||
```
|
||||
|
||||
"（编排器）"工具 —— `kanban_list`、`kanban_create`、`kanban_link`、`kanban_unblock`，以及对外部任务的 `kanban_comment` —— 通过同一工具集提供；约定（由 `kanban-orchestrator` skill 强制执行）是 worker 配置文件不进行扇出或路由无关工作，编排器配置文件不执行实现工作。调度器启动的 worker 仍然针对破坏性生命周期操作限定在任务范围内，无法修改无关任务。
|
||||
|
||||
### 为什么使用工具而不是 shell 执行 `hermes kanban`
|
||||
|
||||
三个原因：
|
||||
|
||||
1. **后端可移植性。** 终端工具指向远程后端（Docker / Modal / Singularity / SSH）的 worker 会在容器*内部*运行 `hermes kanban complete`，而容器中没有安装 `hermes`，也没有挂载 `~/.hermes/kanban.db`。kanban 工具在 agent 自己的 Python 进程中运行，无论终端后端如何，始终能访问 `~/.hermes/kanban.db`。
|
||||
2. **无 shell 引用脆弱性。** 通过 shlex + argparse 传递 `--metadata '{"files": [...]}'` 是潜在的隐患。结构化工具参数完全绕过了这个问题。
|
||||
3. **更好的错误处理。** 工具结果是模型可以推理的结构化 JSON，而不是需要解析的 stderr 字符串。
|
||||
|
||||
**对普通会话零 schema 占用。** 普通的 `hermes chat` 会话在其 schema 中没有任何 `kanban_*` 工具，除非活动配置文件为编排器工作显式启用了 `kanban` 工具集。调度器启动的任务 worker 因为设置了 `HERMES_KANBAN_TASK` 而获得任务范围的工具；编排器配置文件通过配置获得更广泛的路由界面。对于从不使用 kanban 的用户，没有工具膨胀。
|
||||
|
||||
`kanban-worker` 和 `kanban-orchestrator` skill 教导模型何时调用哪个工具以及调用顺序。
|
||||
|
||||
### 推荐的交接证据
|
||||
|
||||
`kanban_complete(summary=..., metadata={...})` 是有意灵活的：summary 是人类可读的收尾说明，`metadata` 是机器可读的交接信息，下游 agent、审查者或仪表盘可以直接复用，无需从文本中提取。
|
||||
|
||||
对于工程和审查任务，推荐使用以下可选 metadata 格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"changed_files": ["path/to/file.py"],
|
||||
"verification": ["pytest tests/hermes_cli/test_kanban_db.py -q"],
|
||||
"dependencies": ["parent task id or external issue, if any"],
|
||||
"blocked_reason": null,
|
||||
"retry_notes": "what failed before, if this was a retry",
|
||||
"residual_risk": ["what was not tested or still needs human review"]
|
||||
}
|
||||
```
|
||||
|
||||
这些键是约定，不是 schema 要求。有用的特性是每个 worker 留下足够的证据，让下一个读者能快速回答四个问题：
|
||||
|
||||
1. 改了什么？
|
||||
2. 如何验证的？
|
||||
3. 如果失败，什么可以解除阻塞或重试？
|
||||
4. 什么风险是有意留下的？
|
||||
|
||||
不要将密钥、原始日志、token（令牌）、OAuth 材料和无关记录放入 `metadata`。改为存储指针和摘要。如果任务没有文件或测试，在 `summary` 中明确说明，并在 `metadata` 中放置确实存在的证据，例如来源 URL、issue id 或手动审查步骤。
|
||||
|
||||
### Worker skill
|
||||
|
||||
任何应该能够处理 kanban 任务的配置文件都必须加载 `kanban-worker` skill。它通过**工具调用**（而非 CLI 命令）教导 worker 完整的生命周期：
|
||||
|
||||
1. 启动时，调用 `kanban_show()` 读取标题 + 正文 + 父级交接 + 先前尝试 + 完整评论线程。
|
||||
2. 通过终端工具执行 `cd $HERMES_KANBAN_WORKSPACE`，在那里完成工作。
|
||||
3. 在长时间操作期间每隔几分钟调用一次 `kanban_heartbeat(note="...")`。**如果你的工作可能运行超过 1 小时，请至少每小时调用一次 `kanban_heartbeat`** —— 调度器会回收运行时间超过 `kanban.dispatch_stale_timeout_seconds`（默认 4 小时）且最近一小时内没有心跳的任务，认为 worker 在没有清理的情况下崩溃了。回收是无害的（任务返回 `ready` 重新调度，不增加失败计数器），但你会失去当前运行的进度。
|
||||
4. 以 `kanban_complete(summary="...", metadata={...})` 完成，或在卡住时以 `kanban_block(reason="...")` 完成。
|
||||
|
||||
最终的 `kanban_complete` / `kanban_block` 调用是 worker 协议的一部分。如果 worker 进程以状态 0 退出而任务仍处于 `running` 状态，调度器将其视为协议违规，发出 `protocol_violation` 事件，并在下一个 tick 自动阻塞任务而不是重新启动它进入同一循环。这通常意味着模型写了一个纯文本答案并退出，而没有使用 Kanban 工具界面。
|
||||
|
||||
`kanban-worker` 是一个内置 skill，在安装和更新期间同步到每个配置文件 —— 无需单独的 Skills Hub 安装步骤。验证它是否存在于你用于 kanban worker 的配置文件中（`researcher`、`writer`、`ops` 等）：
|
||||
|
||||
```bash
|
||||
hermes -p <your-worker-profile> skills list | grep kanban-worker
|
||||
```
|
||||
|
||||
如果内置副本丢失，为该配置文件恢复它：
|
||||
|
||||
```bash
|
||||
hermes -p <your-worker-profile> skills reset kanban-worker --restore
|
||||
```
|
||||
|
||||
调度器在启动每个 worker 时也会自动传递 `--skills kanban-worker`，因此即使配置文件的默认 skills 配置不包含它，worker 也始终拥有该模式库。
|
||||
|
||||
### 为特定任务固定额外 skill
|
||||
|
||||
有时单个任务需要受让人配置文件默认不携带的专业上下文 —— 需要 `translation` skill 的翻译任务、需要 `github-code-review` 的审查任务、需要 `security-pr-audit` 的安全审计。与其每次都编辑受让人的配置文件，不如直接将 skill 附加到任务上。
|
||||
|
||||
**从编排器 agent**（常见情况 —— 一个 agent 将工作路由到另一个），使用 `kanban_create` 工具的 `skills` 数组：
|
||||
|
||||
```
|
||||
kanban_create(
|
||||
title="translate README to Japanese",
|
||||
assignee="linguist",
|
||||
skills=["translation"],
|
||||
)
|
||||
|
||||
kanban_create(
|
||||
title="audit auth flow",
|
||||
assignee="reviewer",
|
||||
skills=["security-pr-audit", "github-code-review"],
|
||||
)
|
||||
```
|
||||
|
||||
**从人类（CLI / 斜杠命令）**，为每个 skill 重复 `--skill`：
|
||||
|
||||
```bash
|
||||
hermes kanban create "translate README to Japanese" \
|
||||
--assignee linguist \
|
||||
--skill translation
|
||||
|
||||
hermes kanban create "audit auth flow" \
|
||||
--assignee reviewer \
|
||||
--skill security-pr-audit \
|
||||
--skill github-code-review
|
||||
```
|
||||
|
||||
**从仪表盘**，在内联创建表单的 **skills** 字段中以逗号分隔输入 skill 名称。
|
||||
|
||||
这些 skill 是对内置 `kanban-worker` 的**补充** —— 调度器为每个 skill（以及内置的）发出一个 `--skills <name>` 标志，因此 worker 启动时加载了所有这些 skill。skill 名称必须与受让人配置文件上实际安装的 skill 匹配（运行 `hermes skills list` 查看可用内容）；没有运行时安装。
|
||||
|
||||
### 编排器 skill
|
||||
|
||||
**行为良好的编排器不会自己做工作。** 它将用户的目标分解为任务，链接它们，将每个任务分配给你设置的配置文件之一，然后退后。`kanban-orchestrator` skill 将此编码为工具调用模式：反诱惑规则、Step-0 配置文件发现提示（调度器在未知受让人名称上静默失败，因此编排器必须将每张卡片落地到你机器上实际存在的配置文件），以及以 `kanban_create` / `kanban_link` / `kanban_comment` 为核心的分解手册。
|
||||
|
||||
典型的编排器轮次（两个并行研究员交接给一个写作者）：
|
||||
|
||||
```
|
||||
# 来自用户的目标："draft a launch post on the ICP funding landscape"
|
||||
kanban_create(title="research ICP funding, NA angle", assignee="researcher-a", body="…") # → t_r1
|
||||
kanban_create(title="research ICP funding, EU angle", assignee="researcher-b", body="…") # → t_r2
|
||||
kanban_create(
|
||||
title="synthesize ICP funding research into launch post draft",
|
||||
assignee="writer",
|
||||
parents=["t_r1", "t_r2"], # 两个研究员都完成时推进到 'ready'
|
||||
body="one-pager, neutral tone, cite sources inline",
|
||||
) # → t_w1
|
||||
# 可选：事后发现的跨切依赖，无需重新创建任务
|
||||
kanban_link(parent_id="t_r1", child_id="t_followup")
|
||||
kanban_complete(
|
||||
summary="decomposed into 2 parallel research tasks → 1 synthesis task; writer starts when both researchers finish",
|
||||
)
|
||||
```
|
||||
|
||||
`kanban-orchestrator` 是一个内置 skill。它在安装和更新期间同步到每个配置文件，因此无需单独的 Skills Hub 安装步骤。验证它是否存在于你的编排器配置文件中：
|
||||
|
||||
```bash
|
||||
hermes -p orchestrator skills list | grep kanban-orchestrator
|
||||
```
|
||||
|
||||
如果内置副本丢失，为该配置文件恢复它：
|
||||
|
||||
```bash
|
||||
hermes -p orchestrator skills reset kanban-orchestrator --restore
|
||||
```
|
||||
|
||||
为获得最佳效果，将其与工具集限制为看板操作（`kanban`、`gateway`、`memory`）的配置文件配对，这样编排器即使尝试也无法执行实现任务。
|
||||
|
||||
## 仪表盘（GUI）
|
||||
|
||||
`/kanban` CLI 和斜杠命令足以无头运行看板，但可视化看板通常是人工介入的正确界面：分诊、跨配置文件监督、阅读评论线程以及在列之间拖动卡片。Hermes 将此作为**内置仪表盘插件**在 `plugins/kanban/` 中提供 —— 不是核心功能，不是单独的服务 —— 遵循[扩展仪表盘](./extending-the-dashboard)中描述的模型。
|
||||
|
||||
使用以下命令打开：
|
||||
|
||||
```bash
|
||||
hermes kanban init # 一次性：如果尚未创建 kanban.db
|
||||
hermes dashboard # 导航栏中出现 "Kanban" 标签页，位于 "Skills" 之后
|
||||
```
|
||||
|
||||
### 插件提供的功能
|
||||
|
||||
- 一个 **Kanban** 标签页，每个状态显示一列：`triage`、`todo`、`ready`、`running`、`blocked`、`done`（开启切换时还有 `archived`）。
|
||||
- `triage` 是粗略想法的停车列。默认情况下（`kanban.auto_decompose: true`），调度器会自动对落在这里的任务运行**分解器** —— 编排器配置文件读取粗略想法，查看你的配置文件名册（含描述），并将任务扇出为路由到最合适专家的小型子任务图。原始任务作为每个子任务的父级保持存活，因此当所有子任务完成时，编排器会重新唤醒以判断完成情况，并在工作未完成时添加更多任务。点击页面顶部的 **Orchestration: Auto/Manual** 切换按钮（或设置 `kanban.auto_decompose: false`）切换到手动模式，在手动模式下分诊任务保持原位，直到你点击卡片上的 **⚗ Decompose** 或运行 `hermes kanban decompose <id>`。对于不需要扇出的任务（或没有编排器配置文件的设置），**✨ Specify** 按钮通过相同的 LLM 机制进行单任务规格重写（标题 + 正文，包含目标、方法、验收标准）。详见下方[自动与手动编排](#auto-vs-manual-orchestration)。
|
||||
- 卡片显示任务 id、标题、优先级徽章、租户标签、分配的配置文件、评论/链接计数、**进度标签**（任务有依赖项时显示 `N/M` 子任务已完成）以及"N 前创建"。每张卡片的复选框启用多选。
|
||||
- **Running 列内的按配置文件分组** —— 工具栏复选框切换 Running 列按受让人的子分组。
|
||||
- **通过 WebSocket 实时更新** —— 插件以短轮询间隔追踪仅追加的 `task_events` 表；任何配置文件（CLI、gateway 或另一个仪表盘标签页）操作后，看板立即反映变化。重新加载经过防抖处理，因此一批事件只触发一次重新获取。
|
||||
- **拖放**卡片在列之间更改状态。拖放操作发送 `PATCH /api/plugins/kanban/tasks/:id`，通过与 CLI 使用的相同 `kanban_db` 代码路由 —— 三个界面永远不会产生偏差。移动到破坏性状态（`done`、`archived`、`blocked`）时会提示确认。触摸设备使用基于指针的回退，因此看板可以在平板电脑上使用。
|
||||
- **内联创建** —— 点击任意列标题上的 `+`，输入标题、受让人、优先级，以及（可选）从所有现有任务的下拉菜单中选择父任务。按 Enter 创建任务，Shift+Enter 在标题字段中插入换行，或按 Escape 取消。从 Triage 列创建会自动将新任务停放在分诊中。
|
||||
- **多选与批量操作** —— shift/ctrl 点击卡片或勾选其复选框将其添加到选择中。顶部出现批量操作栏，包含批量状态转换、归档和重新分配（通过配置文件下拉菜单，或"（取消分配）"）。破坏性批量操作先确认。每个 id 的部分失败会被报告，不会中止其余操作。
|
||||
- **点击卡片**（不按 shift/ctrl）打开侧边抽屉（按 Escape 或点击外部关闭），包含：
|
||||
- **可编辑标题** —— 点击标题进行重命名。
|
||||
- **可编辑受让人 / 优先级** —— 点击元数据行进行修改。
|
||||
- **可编辑描述** —— 默认以 markdown 渲染（标题、粗体、斜体、内联代码、围栏代码、`http(s)` / `mailto:` 链接、项目符号列表），带有"编辑"按钮可切换到文本区域。Markdown 渲染是一个微型、防 XSS 的渲染器 —— 每次替换都在 HTML 转义的输入上运行，只有 `http(s)` / `mailto:` 链接通过，并且始终设置 `target="_blank"` + `rel="noopener noreferrer"`。
|
||||
- **依赖编辑器** —— 父级和子级的芯片列表，每个都有 `×` 用于取消链接，加上所有其他任务的下拉菜单用于添加新的父级或子级。循环尝试在服务器端被拒绝并给出清晰的消息。
|
||||
- **状态操作行**（→ triage / → ready / → running / block / unblock / complete / archive），破坏性转换有确认提示。对于 **Triage** 列中的卡片，该行还提供两个 LLM 驱动的操作：**⚗ Decompose** 将任务扇出为路由到专家配置文件（按描述）的子任务图（编排器驱动路径），**✨ Specify** 进行单任务规格重写。当 LLM 判断任务不需要扇出时，Decompose 会回退到类似 specify 的推进，因此它是严格的超集。两者都可以从 CLI（`hermes kanban decompose <id>` / `specify <id>` / `--all`）、任何 gateway 平台（`/kanban decompose <id>`）以及通过 `POST /api/plugins/kanban/tasks/:id/decompose` 和 `…/specify` 以编程方式访问。在 `config.yaml` 的 `auxiliary.kanban_decomposer` 和 `auxiliary.triage_specifier` 下配置模型。
|
||||
- 结果部分（也以 markdown 渲染）、带 Enter 提交的评论线程、最近 20 个事件。
|
||||
- **工具栏过滤器** —— 自由文本搜索、租户下拉菜单（默认为 `config.yaml` 中的 `dashboard.kanban.default_tenant`）、受让人下拉菜单、"显示已归档"切换、"按配置文件分组"切换，以及**推动调度器**按钮，这样你就不必等待下一个 60 秒 tick。
|
||||
|
||||
视觉上目标是熟悉的 Linear / Fusion 布局：深色主题、带计数的列标题、彩色状态点、优先级和租户的标签芯片。插件只读取主题 CSS 变量（`--color-*`、`--radius`、`--font-mono` 等），因此它会随活动的仪表盘主题自动重新换肤。
|
||||
|
||||
### 自动与手动编排 {#auto-vs-manual-orchestration}
|
||||
|
||||
看板有两种方式处理你放入 Triage 列的任务：
|
||||
|
||||
**自动（默认）** —— `kanban.auto_decompose: true`。Gateway 内嵌调度器在每个 tick 运行**分解器**，受 `kanban.auto_decompose_per_tick`（默认每 tick 3 个任务）限制，以防批量加载分诊任务时突发消耗辅助 LLM。分解器读取粗略想法，查看你安装的配置文件及其描述，并要求 LLM 生成 JSON 任务图：要启动哪些任务、分配给谁，以及哪些依赖哪些。原始分诊任务成为图中每个叶节点的父级，因此它保持存活直到整个图完成 —— 然后推进回 `ready`，让其受让人（编排器配置文件）判断完成情况，并在工作未完成时添加更多任务。这是"丢一行描述，走开"的流程。
|
||||
|
||||
**手动** —— `kanban.auto_decompose: false`。分诊任务保持在分诊中，直到你操作。点击卡片上的 **⚗ Decompose** 按钮，运行 `hermes kanban decompose <id>`（或 `--all`），或从聊天中使用 `/kanban decompose <id>`。这与看板的预分解器行为一致，适合需要完全控制运行时机的场景。
|
||||
|
||||
从 kanban 页面顶部的 **Orchestration: Auto/Manual** 切换按钮（翠绿色 = 自动，静音灰色 = 手动）在两种模式之间切换，或直接编辑 `config.yaml`。两种模式都与 `hermes kanban specify` 共存 —— 当你不想扇出时，它仍然可用作单任务规格重写。
|
||||
|
||||
分解器的路由决策依赖于配置文件描述，这是一个每配置文件的标签原语，通过 `hermes profile create --description "..."`、`hermes profile describe <name> --text "..."`、`hermes profile describe <name> --auto`（LLM 从配置文件安装的 skill + 模型自动生成），或仪表盘展开的 **Orchestration settings** 面板中的每配置文件编辑器来设置。没有描述的配置文件仍然出现在名册中 —— 它们可以按名称路由，只是精度较低。分解器**绝不**会将子任务落地为 `assignee=None`：当 LLM 选择未知配置文件时，子任务路由到 `kanban.default_assignee`（如果未设置，则路由到活动默认配置文件）。
|
||||
|
||||
配置项（均在 `~/.hermes/config.yaml` 的 `kanban:` 下）：
|
||||
|
||||
| 键 | 默认值 | 用途 |
|
||||
|---|---|---|
|
||||
| `auto_decompose` | `true` | 调度器每 tick 自动运行分解器。 |
|
||||
| `auto_decompose_per_tick` | `3` | 每个调度器 tick 的分解上限。超出部分推迟到下一个 tick。 |
|
||||
| `orchestrator_profile` | `""` | 拥有分解权的配置文件。空 = 回退到活动默认配置文件。 |
|
||||
| `default_assignee` | `""` | LLM 选择未知配置文件时子任务的落地位置。空 = 回退到活动默认配置文件。 |
|
||||
|
||||
以及两个辅助 LLM 槽：
|
||||
|
||||
| 键 | 用途 |
|
||||
|---|---|
|
||||
| `auxiliary.kanban_decomposer` | 生成任务图的模型（由 Decompose 调用）。设置 `provider`/`model` 以覆盖主聊天模型。 |
|
||||
| `auxiliary.profile_describer` | 自动生成配置文件描述的模型（由 `hermes profile describe --auto` 调用）。 |
|
||||
|
||||
### 架构
|
||||
|
||||
GUI 严格是一个**通过 DB 读取 + 通过 kanban_db 写入**的层，没有自己的领域逻辑：
|
||||
|
||||
<!-- ascii-guard-ignore -->
|
||||
```
|
||||
┌────────────────────────┐ WebSocket (tails task_events)
|
||||
│ React SPA (plugin) │ ◀──────────────────────────────────┐
|
||||
│ HTML5 drag-and-drop │ │
|
||||
└──────────┬─────────────┘ │
|
||||
│ REST over fetchJSON │
|
||||
▼ │
|
||||
┌────────────────────────┐ writes call kanban_db.* │
|
||||
│ FastAPI router │ directly — same code path │
|
||||
│ plugins/kanban/ │ the CLI /kanban verbs use │
|
||||
│ dashboard/plugin_api.py │
|
||||
└──────────┬─────────────┘ │
|
||||
│ │
|
||||
▼ │
|
||||
┌────────────────────────┐ │
|
||||
│ ~/.hermes/kanban.db │ ───── append task_events ──────────┘
|
||||
│ (WAL, shared) │
|
||||
└────────────────────────┘
|
||||
```
|
||||
<!-- ascii-guard-ignore-end -->
|
||||
|
||||
### REST 接口
|
||||
|
||||
所有路由挂载在 `/api/plugins/kanban/` 下，并受仪表盘的临时会话 token 保护：
|
||||
|
||||
| 方法 | 路径 | 用途 |
|
||||
|---|---|---|
|
||||
| `GET` | `/board?tenant=<name>&include_archived=…` | 按状态列分组的完整看板，加上用于过滤下拉菜单的租户和受让人 |
|
||||
| `GET` | `/tasks/:id` | 任务 + 评论 + 事件 + 链接 |
|
||||
| `POST` | `/tasks` | 创建（封装 `kanban_db.create_task`，接受 `triage: bool` 和 `parents: [id, …]`） |
|
||||
| `PATCH` | `/tasks/:id` | 状态 / 受让人 / 优先级 / 标题 / 正文 / 结果 |
|
||||
| `POST` | `/tasks/bulk` | 对 `ids` 中的每个 id 应用相同的补丁（状态 / 归档 / 受让人 / 优先级）。每个 id 的失败不会中止其他操作 |
|
||||
| `POST` | `/tasks/:id/comments` | 追加评论 |
|
||||
| `POST` | `/tasks/:id/specify` | 运行分诊规格器 —— 辅助 LLM 充实任务正文并将其从 `triage` 推进到 `todo`。返回 `{ok, task_id, reason, new_title}`；"不在分诊中" / 无辅助客户端 / LLM 错误时 `ok=false` 并附人类可读原因，返回 200 而非 4xx |
|
||||
| `POST` | `/tasks/:id/decompose` | 运行 kanban 分解器 —— 辅助 LLM 生成任务图，辅助函数原子性创建子任务 + 链接根任务 + 翻转 `triage → todo`。返回 `{ok, task_id, reason, fanout, child_ids, new_title}`。与 `/specify` 相同的 LLM 错误返回 200 约定。 |
|
||||
| `GET` | `/profiles` | 列出已安装的配置文件及其描述（供仪表盘的配置文件描述编辑器和编排器选择器使用）。 |
|
||||
| `PATCH` | `/profiles/:name` | 设置或清除配置文件的描述（用户编写 —— `description_auto: false`）。返回 `{ok, profile, description}`。 |
|
||||
| `POST` | `/profiles/:name/describe-auto` | 通过 `auxiliary.profile_describer` 为配置文件生成描述。以 `description_auto: true` 持久化，以便仪表盘可以显示"审查"徽章。 |
|
||||
| `GET` | `/orchestration` | 读取 kanban 编排设置（`orchestrator_profile`、`default_assignee`、`auto_decompose`）以及回退后的*解析*有效值。 |
|
||||
| `PUT` | `/orchestration` | 在 `config.yaml` 中更新三个编排键中的一个或多个。验证非空配置文件名实际存在。 |
|
||||
| `POST` | `/links` | 添加依赖关系（`parent_id` → `child_id`） |
|
||||
| `DELETE` | `/links?parent_id=…&child_id=…` | 删除依赖关系 |
|
||||
| `POST` | `/dispatch?max=…&dry_run=…` | 推动调度器 —— 跳过 60 秒等待 |
|
||||
| `GET` | `/config` | 从 `config.yaml` 读取 `dashboard.kanban` 偏好设置 —— `default_tenant`、`lane_by_profile`、`include_archived_by_default`、`render_markdown` |
|
||||
| `WS` | `/events?since=<event_id>` | `task_events` 行的实时流 |
|
||||
|
||||
每个处理器都是一个薄封装 —— 插件约 700 行 Python（路由器 + WebSocket 追踪 + 批量处理器 + 配置读取器），不添加任何新的业务逻辑。一个微型 `_conn()` 辅助函数在每次读写时自动初始化 `kanban.db`，因此无论用户是先打开仪表盘、直接访问 REST API，还是运行 `hermes kanban init`，全新安装都能正常工作。
|
||||
|
||||
### 仪表盘配置
|
||||
|
||||
`~/.hermes/config.yaml` 中 `dashboard.kanban` 下的任何这些键都会更改标签页的默认值 —— 插件在加载时通过 `GET /config` 读取它们：
|
||||
|
||||
```yaml
|
||||
dashboard:
|
||||
kanban:
|
||||
default_tenant: acme # 预选租户过滤器
|
||||
lane_by_profile: true # "按配置文件分组"切换的默认值
|
||||
include_archived_by_default: false
|
||||
render_markdown: true # 设为 false 则使用纯 <pre> 渲染
|
||||
```
|
||||
|
||||
每个键都是可选的，回退到所示的默认值。
|
||||
|
||||
### 安全模型
|
||||
|
||||
仪表盘的 HTTP 认证中间件[显式跳过 `/api/plugins/`](./extending-the-dashboard#backend-api-routes) —— 插件路由在设计上是未认证的，因为仪表盘默认绑定到 localhost。这意味着 kanban REST 接口可以从主机上的任何进程访问。
|
||||
|
||||
WebSocket 额外增加了一步：它要求仪表盘的临时会话 token 作为 `?token=…` 查询参数（浏览器无法在升级请求上设置 `Authorization`），与浏览器内 PTY 桥使用的模式一致。
|
||||
|
||||
如果你运行 `hermes dashboard --host 0.0.0.0`，每个插件路由 —— 包括 kanban —— 都可以从网络访问。**不要在共享主机上这样做。** 看板包含任务正文、评论和工作区路径；攻击者访问这些路由可以读取你整个协作界面，还可以创建 / 重新分配 / 归档任务。
|
||||
|
||||
`~/.hermes/kanban.db` 中的任务是有意与配置文件无关的（这是协调原语）。如果你用 `hermes -p <profile> dashboard` 打开仪表盘，看板仍然显示主机上任何其他配置文件创建的任务。同一用户拥有所有配置文件，但如果多个角色共存，这一点值得了解。
|
||||
|
||||
### 实时更新
|
||||
|
||||
`task_events` 是一个带有单调递增 `id` 的仅追加 SQLite 表。WebSocket 端点保存每个客户端最后看到的事件 id，并在新行到达时推送。当一批事件到达时，前端重新加载（非常廉价的）看板端点 —— 比尝试从每种事件类型修补本地状态更简单、更正确。WAL 模式意味着读取循环永远不会阻塞调度器的 `BEGIN IMMEDIATE` 认领事务。
|
||||
|
||||
### 扩展
|
||||
|
||||
插件使用标准的 Hermes 仪表盘插件契约 —— 完整的 manifest 参考、shell 槽、页面范围槽和 Plugin SDK，请参阅[扩展仪表盘](./extending-the-dashboard)。额外的列、自定义卡片样式、租户过滤布局或完整的 `tab.override` 替换都可以表达，无需 fork 此插件。
|
||||
|
||||
要禁用而不删除：在 `config.yaml` 中添加 `dashboard.plugins.kanban.enabled: false`（或删除 `plugins/kanban/dashboard/manifest.json`）。
|
||||
|
||||
### 范围边界
|
||||
|
||||
GUI 是刻意精简的。插件所做的一切都可以从 CLI 访问；插件只是让人类使用起来更舒适。自动分配、预算、治理门控和组织图视图仍然是用户空间 —— 一个路由器配置文件、另一个插件，或对 `tools/approval.py` 的复用 —— 正如设计规范的范围外章节所列。
|
||||
|
||||
## CLI 命令参考
|
||||
|
||||
这是**你**（或脚本、cron、仪表盘）用来驱动看板的界面。在调度器内部运行的 Worker 使用 `kanban_*` [工具界面](#how-workers-interact-with-the-board)进行相同的操作 —— 这里的 CLI 和那里的工具都通过 `kanban_db` 路由，因此两个界面在构造上是一致的。
|
||||
|
||||
```
|
||||
hermes kanban init # 创建 kanban.db + 打印守护进程提示
|
||||
hermes kanban create "<title>" [--body ...] [--assignee <profile>]
|
||||
[--parent <id>]... [--tenant <name>]
|
||||
[--workspace scratch|worktree|worktree:<path>|dir:<path>]
|
||||
[--branch <name>]
|
||||
[--priority N] [--triage] [--idempotency-key KEY]
|
||||
[--max-runtime 30m|2h|1d|<seconds>]
|
||||
[--max-retries N]
|
||||
[--skill <name>]...
|
||||
[--json]
|
||||
hermes kanban list [--mine] [--assignee P] [--status S] [--tenant T] [--archived] [--json]
|
||||
hermes kanban show <id> [--json]
|
||||
hermes kanban assign <id> <profile> # 或 'none' 取消分配
|
||||
hermes kanban link <parent_id> <child_id>
|
||||
hermes kanban unlink <parent_id> <child_id>
|
||||
hermes kanban claim <id> [--ttl SECONDS]
|
||||
hermes kanban comment <id> "<text>" [--author NAME]
|
||||
|
||||
# 批量动词 —— 接受多个 id：
|
||||
hermes kanban complete <id>... [--result "..."]
|
||||
hermes kanban block <id> "<reason>" [--ids <id>...]
|
||||
hermes kanban unblock <id>...
|
||||
hermes kanban archive <id>...
|
||||
|
||||
hermes kanban tail <id> # 跟踪单个任务的事件流
|
||||
hermes kanban watch [--assignee P] [--tenant T] # 将所有事件实时流式传输到终端
|
||||
[--kinds completed,blocked,…] [--interval SECS]
|
||||
hermes kanban heartbeat <id> [--note "..."] # 长时间操作的 worker 存活信号
|
||||
hermes kanban runs <id> [--json] # 尝试历史（每次运行一行）
|
||||
hermes kanban assignees [--json] # 磁盘上的配置文件 + 每受让人任务计数
|
||||
hermes kanban dispatch [--dry-run] [--max N] # 单次扫描
|
||||
[--failure-limit N] [--json]
|
||||
hermes kanban daemon --force # 已弃用 —— 独立调度器（改用 `hermes gateway start`）
|
||||
[--failure-limit N] [--pidfile PATH] [-v]
|
||||
hermes kanban stats [--json] # 每状态 + 每受让人计数
|
||||
hermes kanban log <id> [--tail BYTES] # 来自 ~/.hermes/kanban/logs/ 的 worker 日志
|
||||
hermes kanban notify-subscribe <id> # gateway 桥接钩子（由 gateway 中的 /kanban 使用）
|
||||
--platform <name> --chat-id <id> [--thread-id <id>] [--user-id <id>]
|
||||
hermes kanban notify-list [<id>] [--json]
|
||||
hermes kanban notify-unsubscribe <id>
|
||||
--platform <name> --chat-id <id> [--thread-id <id>]
|
||||
hermes kanban context <id> # worker 看到的内容
|
||||
hermes kanban specify [<id> | --all] [--tenant T] # 将分诊列的想法充实
|
||||
[--author NAME] [--json] # 为完整规格并推进到 todo
|
||||
hermes kanban gc [--event-retention-days N] # 工作区 + 旧事件 + 旧日志
|
||||
[--log-retention-days N]
|
||||
```
|
||||
|
||||
所有命令也可以作为交互式 CLI 中的斜杠命令和消息 gateway 中使用（见下方[`/kanban` 斜杠命令](#kanban-slash-command)）。
|
||||
|
||||
`--max-retries` 是调度器的每任务熔断器覆盖。`--max-retries 1` 在第一次不成功的尝试后阻塞任务，而 `--max-retries 3` 允许两次重试并在第三次失败时阻塞。省略它则使用 `config.yaml` 中的 `kanban.failure_limit`，然后是内置默认值。
|
||||
|
||||
## `/kanban` 斜杠命令 {#kanban-slash-command}
|
||||
|
||||
每个 `hermes kanban <action>` 动词也可以作为 `/kanban <action>` 访问 —— 从交互式 `hermes chat` 会话内部**以及**从任何 gateway 平台（Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、电子邮件、SMS）。两个界面都调用完全相同的 `hermes_cli.kanban.run_slash()` 入口点，该入口点复用 `hermes kanban` argparse 树，因此参数界面、标志和输出格式在 CLI、`/kanban` 和 `hermes kanban` 之间完全相同。你不必离开聊天来驱动看板。
|
||||
|
||||
```
|
||||
/kanban list
|
||||
/kanban show t_abcd
|
||||
/kanban create "write launch post" --assignee writer --parent t_research
|
||||
/kanban comment t_abcd "looks good, ship it"
|
||||
/kanban unblock t_abcd
|
||||
/kanban dispatch --max 3
|
||||
/kanban specify t_abcd # 将分诊一行描述充实为真正的规格
|
||||
/kanban specify --all --tenant engineering # 一次性扫描某个租户中的所有分诊任务
|
||||
```
|
||||
|
||||
以与 shell 相同的方式引用多词参数 —— `run_slash` 用 `shlex.split` 解析行的其余部分，因此 `"..."` 和 `'...'` 都有效。
|
||||
|
||||
### 运行中使用：`/kanban` 绕过运行中 agent 保护
|
||||
|
||||
Gateway 通常在 agent 仍在思考时将斜杠命令和用户消息排队 —— 这就是防止你在第一轮还在进行时意外启动第二轮的机制。**`/kanban` 被明确豁免于此保护。** 看板存在于 `~/.hermes/kanban.db` 中，而不是运行中 agent 的状态中，因此读取（`list`、`show`、`context`、`tail`、`watch`、`stats`、`runs`）和写入（`comment`、`unblock`、`block`、`assign`、`archive`、`create`、`link` 等）都会立即执行，即使在轮次进行中。
|
||||
|
||||
这就是分离的全部意义：
|
||||
|
||||
- Worker 阻塞等待对等方 → 你从手机发送 `/kanban unblock t_abcd`，调度器在下一个 tick 接管对等方。被阻塞的 worker 不会被中断 —— 它只是不再被阻塞。
|
||||
- 你发现一张需要人工上下文的卡片 → `/kanban comment t_xyz "use the 2026 schema, not 2025"` 落在任务线程上，该任务的*下一次*运行将在 `kanban_show()` 中读取它。
|
||||
- 你想知道你的团队在做什么而不停止编排器 → `/kanban list --mine` 或 `/kanban stats` 在不触及主对话的情况下检查看板。
|
||||
|
||||
### `/kanban create` 时自动订阅（仅限 gateway）
|
||||
|
||||
当你从 gateway 使用 `/kanban create "…"` 创建任务时，发起聊天（平台 + 聊天 id + 线程 id）会自动订阅该任务的终端事件（`completed`、`blocked`、`gave_up`、`crashed`、`timed_out`）。每个终端事件你会收到一条消息回复 —— 包括 `completed` 时 worker 结果摘要的第一行 —— 无需轮询或记住任务 id。
|
||||
|
||||
```
|
||||
you> /kanban create "transcribe today's podcast" --assignee transcriber
|
||||
bot> Created t_9fc1a3 (ready, assignee=transcriber)
|
||||
(subscribed — you'll be notified when t_9fc1a3 completes or blocks)
|
||||
|
||||
… ~8 minutes later …
|
||||
|
||||
bot> ✓ t_9fc1a3 completed by transcriber
|
||||
transcribed 42 minutes, saved to podcast/2026-05-04.md
|
||||
```
|
||||
|
||||
订阅在任务达到 `done` 或 `archived` 后自动移除。如果你用 `--json`（机器输出）脚本化创建，则跳过自动订阅 —— 假设脚本化调用者希望通过 `/kanban notify-subscribe` 显式管理订阅。
|
||||
|
||||
### 消息中的输出截断
|
||||
|
||||
Gateway 平台有实际的消息长度限制。如果 `/kanban list`、`/kanban show` 或 `/kanban tail` 产生超过约 3800 个字符的输出，响应会被截断，并附上 `… (truncated; use \`hermes kanban …\` in your terminal for full output)` 页脚。CLI 界面没有此限制。
|
||||
|
||||
### 自动补全
|
||||
|
||||
在交互式 CLI 中，输入 `/kanban ` 并按 Tab 会循环显示内置子命令列表（`list`、`ls`、`show`、`create`、`assign`、`link`、`unlink`、`claim`、`comment`、`complete`、`block`、`unblock`、`archive`、`tail`、`dispatch`、`context`、`init`、`gc`）。上方 CLI 参考中列出的其余动词（`watch`、`stats`、`runs`、`log`、`assignees`、`heartbeat`、`notify-subscribe`、`notify-list`、`notify-unsubscribe`、`daemon`）也有效 —— 它们只是尚未出现在自动补全提示列表中。
|
||||
|
||||
## 协作模式
|
||||
|
||||
看板无需任何新原语即可支持以下八种模式：
|
||||
|
||||
| 模式 | 形态 | 示例 |
|
||||
|---|---|---|
|
||||
| **P1 扇出** | N 个同级，相同角色 | "并行研究 5 个角度" |
|
||||
| **P2 流水线** | 角色链：侦察 → 编辑 → 写作 | 每日简报组装 |
|
||||
| **P3 投票 / 法定人数** | N 个同级 + 1 个聚合器 | 3 个研究员 → 1 个审查者选择 |
|
||||
| **P4 长期运行日志** | 相同配置文件 + 共享目录 + cron | Obsidian vault |
|
||||
| **P5 人工介入** | worker 阻塞 → 用户评论 → 解除阻塞 | 模糊决策 |
|
||||
| **P6 `@mention`** | 从文本内联路由 | `@reviewer look at this` |
|
||||
| **P7 线程范围工作区** | 线程中的 `/kanban here` | 每项目 gateway 线程 |
|
||||
| **P8 批量任务** | 一个配置文件，N 个对象 | 50 个社交账号 |
|
||||
| **P9 分诊规格器** | 粗略想法 → `triage` → `hermes kanban specify` 扩展正文 → `todo` | "将这个一行描述变成规格化任务" |
|
||||
|
||||
每种模式的详细示例，请参阅 `docs/hermes-kanban-v1-spec.pdf`。
|
||||
|
||||
## 多租户使用
|
||||
|
||||
当一个专家团队为多个业务提供服务时，为每个任务添加租户标签：
|
||||
|
||||
```bash
|
||||
hermes kanban create "monthly report" \
|
||||
--assignee researcher \
|
||||
--tenant business-a \
|
||||
--workspace dir:~/tenants/business-a/data/
|
||||
```
|
||||
|
||||
Worker 接收 `$HERMES_TENANT` 并按前缀命名空间化其内存写入。看板、调度器和配置文件定义都是共享的；只有数据是有范围的。
|
||||
|
||||
## Gateway 通知
|
||||
|
||||
当你从 gateway（Telegram、Discord、Slack 等）运行 `/kanban create …` 时，发起聊天会自动订阅新任务。Gateway 的后台通知器每隔几秒轮询 `task_events`，并为每个终端事件（`completed`、`blocked`、`gave_up`、`crashed`、`timed_out`）向该聊天发送一条消息。已完成的任务还会发送 worker `--result` 的第一行，这样你无需 `/kanban show` 就能看到结果。
|
||||
|
||||
你可以从 CLI 显式管理订阅 —— 当脚本 / cron 任务想要通知一个它不是从那里发起的聊天时很有用：
|
||||
|
||||
```bash
|
||||
hermes kanban notify-subscribe t_abcd \
|
||||
--platform telegram --chat-id 12345678 --thread-id 7
|
||||
hermes kanban notify-list
|
||||
hermes kanban notify-unsubscribe t_abcd \
|
||||
--platform telegram --chat-id 12345678 --thread-id 7
|
||||
```
|
||||
|
||||
订阅在任务达到 `done` 或 `archived` 后自动移除；无需清理。
|
||||
|
||||
## 运行记录 —— 每次尝试一行
|
||||
|
||||
任务是一个逻辑工作单元；**运行**是执行它的一次尝试。当调度器认领一个就绪任务时，它在 `task_runs` 中创建一行，并将 `tasks.current_run_id` 指向它。当该尝试结束时 —— 完成、阻塞、崩溃、超时、启动失败、回收 —— 运行行以 `outcome` 关闭，任务的指针清除。被尝试三次的任务有三行 `task_runs`。
|
||||
|
||||
为什么用两张表而不是直接修改任务：你需要**完整的尝试历史**用于真实世界的事后分析（"第二次审查尝试到达批准，第三次合并"），你需要一个干净的地方挂载每次尝试的元数据 —— 哪些文件改变了、哪些测试运行了、审查者注意到了哪些发现。这些是运行事实，不是任务事实。
|
||||
|
||||
运行也是**结构化交接**所在的地方。当 worker 完成任务（通过 `kanban_complete(...)`）时，它可以传递：
|
||||
|
||||
- `summary`（工具参数）/ `--summary`（CLI）—— 人类交接；放在运行上；下游子任务在其 `build_worker_context` 中看到它。
|
||||
- `metadata`（工具参数）/ `--metadata`（CLI）—— 运行上的自由格式 JSON 字典；子任务看到它与摘要一起序列化。
|
||||
- `result`（工具参数）/ `--result`（CLI）—— 放在任务行上的简短日志行（遗留字段，保留向后兼容）。
|
||||
|
||||
下游子任务读取每个父任务最近完成运行的摘要 + 元数据。重试 worker 读取其自身任务上的先前尝试（结果、摘要、错误），以避免重复已经失败的路径。
|
||||
|
||||
```
|
||||
# worker 实际做的事 —— agent 循环内的工具调用：
|
||||
kanban_complete(
|
||||
summary="implemented token bucket, keys on user_id with IP fallback, all tests pass",
|
||||
metadata={"changed_files": ["limiter.py", "tests/test_limiter.py"], "tests_run": 14},
|
||||
result="rate limiter shipped",
|
||||
)
|
||||
```
|
||||
|
||||
当你（人类）需要关闭 worker 无法关闭的任务时，同样的交接可以从 CLI 访问 —— 例如被放弃的任务，或你从仪表盘手动标记为完成的任务：
|
||||
|
||||
```bash
|
||||
hermes kanban complete t_abcd \
|
||||
--result "rate limiter shipped" \
|
||||
--summary "implemented token bucket, keys on user_id with IP fallback, all tests pass" \
|
||||
--metadata '{"changed_files": ["limiter.py", "tests/test_limiter.py"], "tests_run": 14}'
|
||||
|
||||
# 查看重试任务的尝试历史：
|
||||
hermes kanban runs t_abcd
|
||||
# # OUTCOME PROFILE ELAPSED STARTED
|
||||
# 1 blocked worker 12s 2026-04-27 14:02
|
||||
# → BLOCKED: need decision on rate-limit key
|
||||
# 2 completed worker 8m 2026-04-27 15:18
|
||||
# → implemented token bucket, keys on user_id with IP fallback
|
||||
```
|
||||
|
||||
运行在仪表盘上公开（抽屉中的运行历史部分，每次尝试一行彩色行）以及 REST API 上（`GET /api/plugins/kanban/tasks/:id` 返回 `runs[]` 数组）。带有 `{status: "done", summary, metadata}` 的 `PATCH /api/plugins/kanban/tasks/:id` 将两者都转发到内核，因此仪表盘的"标记完成"按钮等同于 CLI。`task_events` 行携带它们所属的 `run_id`，以便 UI 可以按尝试分组，`completed` 事件在其有效载荷中嵌入第一行摘要（上限 400 个字符），这样 gateway 通知器无需第二次 SQL 往返即可渲染结构化交接。
|
||||
|
||||
**批量关闭注意事项。** `hermes kanban complete a b c --summary X` 被拒绝 —— 结构化交接是每次运行的，因此将相同的摘要复制粘贴到 N 个任务几乎总是错误的。不带 `--summary` / `--metadata` 的批量关闭仍然适用于常见的"我完成了一堆管理任务"情况。
|
||||
|
||||
**状态变更导致的运行回收。** 如果你在仪表盘中将运行中的任务从 `running` 拖走（回到 `ready`，或直接到 `todo`），或归档仍在运行的任务，进行中的运行以 `outcome='reclaimed'` 关闭，而不是被孤立。当 `tasks.current_run_id` 为 `NULL` 时，`task_runs` 行始终处于终端状态，反之亦然 —— 该不变量在 CLI、仪表盘、调度器和通知器之间保持。
|
||||
|
||||
**从未认领的完成的合成运行。** 完成或阻塞从未被认领的任务（例如，人类从仪表盘关闭带摘要的 `ready` 任务，或 CLI 用户运行 `hermes kanban complete <ready-task> --summary X`）否则会丢失交接。相反，内核插入一个零持续时间运行行（`started_at == ended_at`），携带摘要 / 元数据 / 原因，以保持尝试历史完整。`completed` / `blocked` 事件的 `run_id` 指向该行。
|
||||
|
||||
**实时抽屉刷新。** 当仪表盘的 WebSocket 事件流报告用户当前正在查看的任务的新事件时，抽屉会重新加载自身（通过线程到其 `useEffect` 依赖列表中的每任务事件计数器）。不再需要关闭并重新打开才能看到运行的新行或更新的结果。
|
||||
|
||||
### 向前兼容性
|
||||
|
||||
`tasks` 上的两个可空列为 v2 工作流路由保留：`workflow_template_id`（此任务属于哪个模板）和 `current_step_key`（该模板中哪个步骤处于活动状态）。v1 内核忽略它们用于路由，但允许客户端写入它们，因此 v2 版本可以添加路由机制而无需另一次 schema 迁移。
|
||||
|
||||
## 事件参考
|
||||
|
||||
每次转换都向 `task_events` 追加一行。每行携带一个可选的 `run_id`，以便 UI 可以按尝试分组事件。类型分为三个集群，便于过滤（`hermes kanban watch --kinds completed,gave_up,timed_out`）：
|
||||
|
||||
**生命周期**（关于任务作为逻辑单元发生了什么变化）：
|
||||
|
||||
| 类型 | 有效载荷 | 时机 |
|
||||
|---|---|---|
|
||||
| `created` | `{assignee, status, parents, tenant}` | 任务插入。`run_id` 为 `NULL`。 |
|
||||
| `promoted` | — | 因所有父任务达到 `done` 而 `todo → ready`。`run_id` 为 `NULL`。 |
|
||||
| `claimed` | `{lock, expires, run_id}` | 调度器原子性认领 `ready` 任务以启动。 |
|
||||
| `completed` | `{result_len, summary?}` | Worker 写入 `--result` / `--summary` 且任务达到 `done`。`summary` 是第一行交接（400 字符上限）；完整版本存在于运行行上。如果在从未认领的任务上调用 `complete_task` 并带有交接字段，则合成零持续时间运行，以便 `run_id` 仍然指向某处。 |
|
||||
| `blocked` | `{reason}` | Worker 或人类将任务翻转为 `blocked`。在带有 `--reason` 的从未认领任务上调用时合成零持续时间运行。 |
|
||||
| `unblocked` | — | `blocked → ready`，手动或通过 `/unblock`。`run_id` 为 `NULL`。 |
|
||||
| `archived` | — | 从默认看板中隐藏。如果任务仍在运行，携带作为副作用被回收的运行的 `run_id`。 |
|
||||
|
||||
**编辑**（不是转换的人类驱动变更）：
|
||||
|
||||
| 类型 | 有效载荷 | 时机 |
|
||||
|---|---|---|
|
||||
| `assigned` | `{assignee}` | 受让人更改（包括取消分配）。 |
|
||||
| `edited` | `{fields}` | 标题或正文更新。 |
|
||||
| `reprioritized` | `{priority}` | 优先级更改。 |
|
||||
| `status` | `{status}` | 仪表盘拖放直接写入状态（例如 `todo → ready`）。从 `running` 拖走时携带被回收运行的 `run_id`；否则 `run_id` 为 NULL。 |
|
||||
|
||||
**Worker 遥测**（关于执行过程，而非逻辑任务）：
|
||||
|
||||
| 类型 | 有效载荷 | 时机 |
|
||||
|---|---|---|
|
||||
| `spawned` | `{pid}` | 调度器成功启动 worker 进程。 |
|
||||
| `heartbeat` | `{note?}` | Worker 在长时间操作期间调用 `hermes kanban heartbeat $TASK` 发出存活信号。 |
|
||||
| `reclaimed` | `{stale_lock}` | 认领 TTL 在完成前过期；任务返回 `ready`。 |
|
||||
| `crashed` | `{pid, claimer}` | Worker PID 不再存活但 TTL 尚未过期。 |
|
||||
| `timed_out` | `{pid, elapsed_seconds, limit_seconds, sigkill}` | 超过 `max_runtime_seconds`；调度器发送 SIGTERM（5 秒宽限后发送 SIGKILL）并重新排队。 |
|
||||
| `stale` | `{elapsed_seconds, last_heartbeat_at, heartbeat_age_seconds, timeout_seconds, pid, terminated}` | 任务运行时间超过 `kanban.dispatch_stale_timeout_seconds`（默认 4 小时）**且**最近一小时内没有 `kanban_heartbeat`。调度器向本地 worker（如有）发送 SIGTERM，将任务重置为 `ready` 重新调度。**不**增加失败计数器（stale 是调度器端的缺席检测，不是 worker 故障）。运行长时间操作的 Worker 应至少每小时调用一次 `kanban_heartbeat` 以避免此情况。 |
|
||||
| `respawn_guarded` | `{reason}` | 调度器拒绝在本 tick 重新启动此就绪任务。原因：`blocker_auth`（上次失败是配额/认证/429 错误 —— 等待速率窗口重置）、`recent_success`（最近一小时内有完成的运行 —— 在重新运行前等待审查）、`active_pr`（最近的评论中出现 GitHub PR URL —— 先前的 worker 已经打开了 PR）。任务保持在 `ready`；下一个 tick 有另一次启动机会。如果底层条件持续存在，正常的 `consecutive_failures` 熔断器将在 `failure_limit` 次失败后通过 `gave_up` 自动阻塞。 |
|
||||
| `spawn_failed` | `{error, failures}` | 一次启动尝试失败（PATH 缺失、工作区无法挂载等）。计数器递增；任务返回 `ready` 重试。 |
|
||||
| `protocol_violation` | `{pid, claimer, exit_code}` | Worker 在任务仍处于 `running` 状态时成功退出，通常是因为它回答了问题而没有调用 `kanban_complete` 或 `kanban_block`。调度器还会立即发出 `gave_up` 并自动阻塞，而不是重试。 |
|
||||
| `gave_up` | `{failures, effective_limit, limit_source, error}` | N 次连续不成功尝试后熔断器触发。任务以最后一个错误自动阻塞。有效限制解析为任务 `max_retries`，然后是调度器 `failure_limit` / `kanban.failure_limit`，然后是内置默认值。 |
|
||||
|
||||
`hermes kanban tail <id>` 显示单个任务的这些事件。`hermes kanban watch` 在整个看板范围内流式传输它们。
|
||||
|
||||
## 范围之外
|
||||
|
||||
Kanban 是刻意单主机的。`~/.hermes/kanban.db` 是本地 SQLite 文件，调度器在同一台机器上启动 worker。不支持跨两台主机运行共享看板 —— 没有"主机 A 上的 worker X，主机 B 上的 worker Y"的协调原语，崩溃检测路径假设 PID 是主机本地的。如果你需要多主机，每台主机运行独立的看板，并使用 `delegate_task` / 消息队列来桥接它们。
|
||||
|
||||
## 设计规范
|
||||
|
||||
完整的设计 —— 架构、并发正确性、与其他系统的比较、实现计划、风险、开放问题 —— 存在于 `docs/hermes-kanban-v1-spec.pdf` 中。在提交任何行为变更 PR 之前请先阅读它。
|
||||
+217
@@ -0,0 +1,217 @@
|
||||
---
|
||||
sidebar_position: 16
|
||||
title: "LSP — 语义诊断"
|
||||
description: "真实语言服务器（pyright、gopls、rust-analyzer 等）接入 write_file 和 patch 所使用的写后 lint 检查。"
|
||||
---
|
||||
|
||||
# 语言服务器协议（LSP）
|
||||
|
||||
Hermes 以后台子进程方式运行完整的语言服务器——pyright、gopls、rust-analyzer、
|
||||
typescript-language-server、clangd 以及约 20 个其他服务器——并将其语义诊断结果
|
||||
接入 `write_file` 和 `patch` 所使用的写后 lint 检查。当 agent 编辑文件时，
|
||||
它能精确看到该次编辑引入的错误——不仅是语法错误，还包括语言服务器检测到的
|
||||
**类型错误、未定义名称、缺失导入以及全项目范围的语义问题**。
|
||||
|
||||
这与顶级编码 agent 所采用的架构相同。Hermes 将其作为自包含组件提供：
|
||||
无需编辑器宿主，无需安装插件，无需管理独立守护进程。
|
||||
|
||||
## LSP 的触发时机
|
||||
|
||||
LSP 以 **git 工作区检测**为前提条件。当 agent 的工作目录（或正在编辑的文件）
|
||||
位于 git 仓库内时，LSP 针对该工作区运行。若两者均不在 git 仓库中，LSP 保持
|
||||
休眠——这对消息网关（gateway）场景很有用，此时 cwd 为用户主目录，没有可诊断的项目。
|
||||
|
||||
检查分层进行：首先进行进程内语法检查（微秒级），语法通过后再进行 LSP 语义诊断。
|
||||
不稳定或缺失的语言服务器永远不会导致写入失败——所有 LSP 失败路径均静默回退至
|
||||
仅语法检查的结果。
|
||||
|
||||
具体而言，每次成功执行 `write_file` 或 `patch` 时：
|
||||
|
||||
1. Hermes 捕获该文件当前诊断的基线快照。
|
||||
2. 执行写入。
|
||||
3. 重新查询语言服务器，过滤掉基线中已存在的诊断，仅呈现新引入的诊断。
|
||||
|
||||
agent 看到的输出如下：
|
||||
|
||||
```
|
||||
{
|
||||
"bytes_written": 42,
|
||||
"dirs_created": false,
|
||||
"lint": {"status": "ok", "output": ""},
|
||||
"lsp_diagnostics": "LSP diagnostics introduced by this edit:\n<diagnostics file=\"/path/to/foo.py\">\nERROR [42:5] Cannot find name 'foo' [reportUndefinedVariable] (Pyright)\nERROR [50:1] Argument of type \"str\" is not assignable to \"int\" [reportArgumentType] (Pyright)\n</diagnostics>"
|
||||
}
|
||||
```
|
||||
|
||||
`lint` 字段承载语法检查结果（通过 `ast.parse`、`json.loads` 等进行微秒级进程内解析）；
|
||||
`lsp_diagnostics` 字段承载来自真实语言服务器的语义诊断。两个通道，独立信号——
|
||||
agent 对于语法正确但存在语义问题的文件，会看到 ``lint: ok`` 加上已填充的 ``lsp_diagnostics``。
|
||||
|
||||
## 支持的语言
|
||||
|
||||
| 语言 | 服务器 | 自动安装 |
|
||||
|----------|--------|--------------|
|
||||
| Python | `pyright-langserver` | npm |
|
||||
| TypeScript / JavaScript / JSX / TSX | `typescript-language-server` | npm |
|
||||
| Vue | `@vue/language-server` | npm |
|
||||
| Svelte | `svelte-language-server` | npm |
|
||||
| Astro | `@astrojs/language-server` | npm |
|
||||
| Go | `gopls` | `go install` |
|
||||
| Rust | `rust-analyzer` | 手动（rustup） |
|
||||
| C / C++ | `clangd` | 手动（LLVM） |
|
||||
| Bash / Zsh | `bash-language-server` | npm |
|
||||
| YAML | `yaml-language-server` | npm |
|
||||
| Lua | `lua-language-server` | 手动（GitHub releases） |
|
||||
| PHP | `intelephense` | npm |
|
||||
| OCaml | `ocaml-lsp` | 手动（opam） |
|
||||
| Dockerfile | `dockerfile-language-server-nodejs` | npm |
|
||||
| Terraform | `terraform-ls` | 手动 |
|
||||
| Dart | `dart language-server` | 手动（dart sdk） |
|
||||
| Haskell | `haskell-language-server` | 手动（ghcup） |
|
||||
| Julia | `julia` + LanguageServer.jl | 手动 |
|
||||
| Clojure | `clojure-lsp` | 手动 |
|
||||
| Nix | `nixd` | 手动 |
|
||||
| Zig | `zls` | 手动 |
|
||||
| Gleam | `gleam lsp` | 手动（gleam install） |
|
||||
| Elixir | `elixir-ls` | 手动 |
|
||||
| Prisma | `prisma language-server` | 手动 |
|
||||
| Kotlin | `kotlin-language-server` | 手动 |
|
||||
| Java | `jdtls` | 手动 |
|
||||
|
||||
对于"手动"条目，请通过该语言对应的工具链管理器安装服务器（rustup、ghcup、opam、brew 等）。
|
||||
Hermes 会自动检测 PATH 上或 `<HERMES_HOME>/lsp/bin/` 中的二进制文件。
|
||||
|
||||
部分服务器需要与 npm 不会自动拉取的对等依赖一同安装。当前的典型情况是
|
||||
`typescript-language-server`，它要求 `typescript` SDK 可从同一 `node_modules`
|
||||
目录树中导入——当你运行 `hermes lsp install typescript` 或首次使用时触发自动安装时，
|
||||
Hermes 会同时安装这两个包。
|
||||
|
||||
## CLI
|
||||
|
||||
```
|
||||
hermes lsp status # 服务状态 + 各服务器安装状态
|
||||
hermes lsp list # 注册表，可选 --installed-only
|
||||
hermes lsp install <id> # 主动安装单个服务器
|
||||
hermes lsp install-all # 尝试安装所有已知安装方式的服务器
|
||||
hermes lsp restart # 关闭正在运行的客户端
|
||||
hermes lsp which <id> # 打印解析后的二进制路径
|
||||
```
|
||||
|
||||
`hermes lsp status` 是最佳起点——它显示哪些语言当前可获得语义诊断，
|
||||
哪些语言还需要安装二进制文件。
|
||||
|
||||
## 配置
|
||||
|
||||
默认配置适用于典型场景；若二进制文件已在 PATH 上，无需任何设置。
|
||||
|
||||
```yaml
|
||||
# config.yaml
|
||||
lsp:
|
||||
# 主开关。禁用后跳过整个子系统——不会启动任何服务器，不会运行后台事件循环。
|
||||
enabled: true
|
||||
|
||||
# 每次写入后等待诊断结果的方式。
|
||||
wait_mode: document # "document" 或 "full"
|
||||
wait_timeout: 5.0
|
||||
|
||||
# 处理缺失服务器二进制文件的策略。
|
||||
# auto — 通过 npm/pip/go install 安装到 <HERMES_HOME>/lsp/bin
|
||||
# manual — 仅使用已在 PATH 上的二进制文件
|
||||
install_strategy: auto
|
||||
|
||||
# 各服务器覆盖配置（均为可选）。
|
||||
servers:
|
||||
pyright:
|
||||
disabled: false
|
||||
command: ["/abs/path/to/pyright-langserver", "--stdio"]
|
||||
env: { PYRIGHT_LOG_LEVEL: "info" }
|
||||
initialization_options:
|
||||
python:
|
||||
analysis:
|
||||
typeCheckingMode: "strict"
|
||||
typescript:
|
||||
disabled: true # 即使扩展名匹配也跳过 TS
|
||||
```
|
||||
|
||||
### 各服务器配置键
|
||||
|
||||
* `disabled: true` — 即使扩展名与文件匹配，也完全跳过该服务器。
|
||||
* `command: [bin, ...args]` — 指定自定义二进制路径，绕过自动安装。
|
||||
* `env: {KEY: value}` — 传递给启动进程的额外环境变量。
|
||||
* `initialization_options: {...}` — 合并到 LSP `initialize` 握手时发送的
|
||||
`initializationOptions` 载荷中。具体内容因服务器而异，请参阅对应语言服务器的文档。
|
||||
|
||||
## 安装位置
|
||||
|
||||
当 `install_strategy: auto` 时，Hermes 将二进制文件安装到 `<HERMES_HOME>/lsp/bin/`。
|
||||
NPM 包安装到 `<HERMES_HOME>/lsp/node_modules/`，bin 符号链接位于上一级目录。
|
||||
Go 二进制文件通过 `go install` 安装，`GOBIN` 指向暂存目录。
|
||||
|
||||
任何内容都不会安装到 `/usr/local/`、`~/.local/` 或其他共享位置——暂存目录完全由
|
||||
Hermes 管理，重置 profile 时会被删除。
|
||||
|
||||
## 性能特性
|
||||
|
||||
LSP 服务器在**首次使用时懒启动**。在从未处理过 `.py` 文件的项目中编辑 Python 文件
|
||||
会启动 pyright；大多数服务器的启动耗时为 1-3 秒（rust-analyzer 在冷启动项目时可能
|
||||
超过 10 秒）。同一工作区内的后续编辑会复用已运行的服务器。
|
||||
|
||||
在没有诊断结果输出时，LSP 层对干净写入仅增加数毫秒延迟。有诊断结果时，等待预算为
|
||||
`wait_timeout` 秒——pyright/tsserver 通常在数十毫秒内响应，rust-analyzer 在索引
|
||||
过程中可能需要数秒。
|
||||
|
||||
服务器在 Hermes 进程的整个生命周期内保持运行。没有空闲超时回收机制——每次写入都
|
||||
重启服务器索引的代价远高于保持守护进程运行。
|
||||
|
||||
## 禁用
|
||||
|
||||
在 `config.yaml` 中设置 `lsp.enabled: false` 可禁用整个子系统。写后检查将回退至
|
||||
进程内语法检查（Python 使用 `ast.parse`，JSON 使用 `json.loads` 等），与早期版本
|
||||
保持一致。
|
||||
|
||||
若要禁用单个语言而不禁用整个层：
|
||||
|
||||
```yaml
|
||||
lsp:
|
||||
servers:
|
||||
rust-analyzer:
|
||||
disabled: true
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
**`hermes lsp status` 显示某服务器为"missing"**
|
||||
|
||||
该二进制文件不在 PATH 上，也不在 `<HERMES_HOME>/lsp/bin/` 中。运行
|
||||
`hermes lsp install <server_id>` 尝试自动安装，或通过该语言的常规工具链手动安装。
|
||||
|
||||
**`hermes lsp status` 中出现 `Backend warnings` 部分**
|
||||
|
||||
部分服务器以薄包装层的形式调用外部 CLI 进行实际诊断——它们能正常启动并接受请求，
|
||||
但在辅助二进制文件缺失时不会报错。最常见的情况是 `bash-language-server`，
|
||||
它将诊断委托给 `shellcheck`。当 `hermes lsp status` 显示 `Backend warnings` 部分时，
|
||||
请通过系统包管理器安装对应工具：
|
||||
|
||||
```
|
||||
apt install shellcheck # Debian / Ubuntu
|
||||
brew install shellcheck # macOS
|
||||
scoop install shellcheck # Windows
|
||||
```
|
||||
|
||||
同样的警告会在服务器启动时记录一次到 `~/.hermes/logs/agent.log`。
|
||||
|
||||
**服务器已启动但从不返回诊断结果**
|
||||
|
||||
检查 `~/.hermes/logs/agent.log` 中的 `[agent.lsp.client]` 条目——语言服务器的
|
||||
stderr 输出和协议错误均记录于此。部分服务器（尤其是 rust-analyzer）需要完成
|
||||
全项目索引后才会输出单文件诊断；服务器启动后的第一次编辑可能没有诊断结果，
|
||||
后续编辑才会获取到。
|
||||
|
||||
**服务器崩溃**
|
||||
|
||||
崩溃的服务器会被加入损坏集合，在本次会话剩余时间内不再重试。运行
|
||||
`hermes lsp restart` 清除该集合；下次编辑时会重新启动。
|
||||
|
||||
**编辑位于任何 git 仓库之外的文件**
|
||||
|
||||
按设计，LSP 仅在 git 仓库内运行。若项目尚未初始化，运行 `git init` 以启用
|
||||
LSP 诊断。否则将使用进程内仅语法检查的回退方案。
|
||||
+591
@@ -0,0 +1,591 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: "MCP（模型上下文协议）"
|
||||
description: "通过 MCP 将 Hermes Agent 连接到外部工具服务器，并精确控制 Hermes 加载哪些 MCP 工具"
|
||||
---
|
||||
|
||||
# MCP（模型上下文协议）
|
||||
|
||||
MCP 让 Hermes Agent 连接到外部工具服务器，使 agent 能够使用 Hermes 本身之外的工具——GitHub、数据库、文件系统、浏览器栈、内部 API 等等。
|
||||
|
||||
如果你曾经希望 Hermes 使用某个已经存在于其他地方的工具，MCP 通常是最简洁的方式。
|
||||
|
||||
## MCP 能给你带来什么
|
||||
|
||||
- 无需先编写原生 Hermes 工具，即可访问外部工具生态系统
|
||||
- 在同一配置中同时支持本地 stdio 服务器和远程 HTTP MCP 服务器
|
||||
- 启动时自动发现并注册工具
|
||||
- 在服务器支持的情况下，提供针对 MCP 资源和 prompt（提示词）的实用工具封装
|
||||
- 按服务器过滤，只向 Hermes 暴露你真正需要的 MCP 工具
|
||||
|
||||
## 快速开始
|
||||
|
||||
1. 安装 MCP 支持（如果你使用了标准安装脚本，已包含在内）：
|
||||
|
||||
```bash
|
||||
cd ~/.hermes/hermes-agent
|
||||
uv pip install -e ".[mcp]"
|
||||
```
|
||||
|
||||
2. 在 `~/.hermes/config.yaml` 中添加一个 MCP 服务器：
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
|
||||
```
|
||||
|
||||
3. 启动 Hermes：
|
||||
|
||||
```bash
|
||||
hermes chat
|
||||
```
|
||||
|
||||
4. 让 Hermes 使用 MCP 支持的能力。
|
||||
|
||||
例如：
|
||||
|
||||
```text
|
||||
List the files in /home/user/projects and summarize the repo structure.
|
||||
```
|
||||
|
||||
Hermes 会发现 MCP 服务器的工具，并像使用其他工具一样使用它们。
|
||||
|
||||
## 两种 MCP 服务器
|
||||
|
||||
### Stdio 服务器
|
||||
|
||||
Stdio 服务器作为本地子进程运行，通过 stdin/stdout 通信。
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
|
||||
```
|
||||
|
||||
适合使用 stdio 服务器的场景：
|
||||
- 服务器已在本地安装
|
||||
- 需要低延迟访问本地资源
|
||||
- 你参考的 MCP 服务器文档中使用了 `command`、`args` 和 `env`
|
||||
|
||||
### HTTP 服务器
|
||||
|
||||
HTTP MCP 服务器是 Hermes 直接连接的远程端点。
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
remote_api:
|
||||
url: "https://mcp.example.com/mcp"
|
||||
headers:
|
||||
Authorization: "Bearer ***"
|
||||
```
|
||||
|
||||
适合使用 HTTP 服务器的场景：
|
||||
- MCP 服务器托管在其他地方
|
||||
- 你的组织暴露了内部 MCP 端点
|
||||
- 你不希望 Hermes 为该集成在本地启动子进程
|
||||
|
||||
## 基本配置参考
|
||||
|
||||
Hermes 从 `~/.hermes/config.yaml` 的 `mcp_servers` 下读取 MCP 配置。
|
||||
|
||||
### 常用字段
|
||||
|
||||
| 字段 | 类型 | 含义 |
|
||||
|---|---|---|
|
||||
| `command` | string | stdio MCP 服务器的可执行文件 |
|
||||
| `args` | list | stdio 服务器的参数 |
|
||||
| `env` | mapping | 传递给 stdio 服务器的环境变量 |
|
||||
| `url` | string | HTTP MCP 端点 |
|
||||
| `headers` | mapping | 远程服务器的 HTTP 头 |
|
||||
| `timeout` | number | 工具调用超时时间 |
|
||||
| `connect_timeout` | number | 初始连接超时时间 |
|
||||
| `enabled` | bool | 若为 `false`，Hermes 完全跳过该服务器 |
|
||||
| `supports_parallel_tool_calls` | bool | 若为 `true`，该服务器的工具可并发运行 |
|
||||
| `tools` | mapping | 按服务器过滤工具及实用工具策略 |
|
||||
|
||||
### 最简 stdio 示例
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
|
||||
```
|
||||
|
||||
### 最简 HTTP 示例
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
company_api:
|
||||
url: "https://mcp.internal.example.com"
|
||||
headers:
|
||||
Authorization: "Bearer ***"
|
||||
```
|
||||
|
||||
## 内置预设
|
||||
|
||||
对于知名 MCP 服务器，`hermes mcp add` 接受 `--preset` 标志，自动填写传输层细节，无需手动查找命令和参数。预设只提供默认值——你在同一命令行传入的其他内容（环境变量、头信息、过滤规则）仍然优先生效。
|
||||
|
||||
| 预设 | 配置内容 |
|
||||
|---|---|
|
||||
| `codex` | Codex CLI 的 MCP 服务器（通过 stdio 运行 `codex mcp-server`）。需要 PATH 中存在 `codex` CLI。 |
|
||||
|
||||
```bash
|
||||
# 一行命令将 Codex CLI 添加为 MCP 服务器
|
||||
hermes mcp add codex --preset codex
|
||||
```
|
||||
|
||||
等价于写入：
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
codex:
|
||||
command: "codex"
|
||||
args: ["mcp-server"]
|
||||
```
|
||||
|
||||
你可以使用任意本地名称（`hermes mcp add my-codex --preset codex` 完全可以）；预设只提供 `command`/`args` 默认值。
|
||||
|
||||
## Hermes 注册 MCP 工具的方式
|
||||
|
||||
Hermes 为 MCP 工具添加前缀，避免与内置名称冲突：
|
||||
|
||||
```text
|
||||
mcp_<server_name>_<tool_name>
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
| 服务器 | MCP 工具 | 注册名称 |
|
||||
|---|---|---|
|
||||
| `filesystem` | `read_file` | `mcp_filesystem_read_file` |
|
||||
| `github` | `create-issue` | `mcp_github_create_issue` |
|
||||
| `my-api` | `query.data` | `mcp_my_api_query_data` |
|
||||
|
||||
实际使用中，你通常不需要手动调用带前缀的名称——Hermes 在正常推理过程中会自动识别并选择该工具。
|
||||
|
||||
## MCP 实用工具
|
||||
|
||||
在服务器支持的情况下，Hermes 还会围绕 MCP 资源和 prompt 注册实用工具：
|
||||
|
||||
- `list_resources`
|
||||
- `read_resource`
|
||||
- `list_prompts`
|
||||
- `get_prompt`
|
||||
|
||||
这些工具按服务器注册，遵循相同的前缀规则，例如：
|
||||
|
||||
- `mcp_github_list_resources`
|
||||
- `mcp_github_get_prompt`
|
||||
|
||||
### 重要说明
|
||||
|
||||
这些实用工具现在具备能力感知：
|
||||
- 只有当 MCP 会话实际支持资源操作时，Hermes 才注册资源实用工具
|
||||
- 只有当 MCP 会话实际支持 prompt 操作时，Hermes 才注册 prompt 实用工具
|
||||
|
||||
因此，一个只暴露可调用工具而没有资源/prompt 的服务器，不会获得这些额外的封装。
|
||||
|
||||
## 按服务器过滤
|
||||
|
||||
你可以控制每个 MCP 服务器向 Hermes 贡献哪些工具，从而精细管理工具命名空间。
|
||||
|
||||
### 完全禁用某个服务器
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
legacy:
|
||||
url: "https://mcp.legacy.internal"
|
||||
enabled: false
|
||||
```
|
||||
|
||||
若 `enabled: false`，Hermes 完全跳过该服务器，甚至不尝试连接。
|
||||
|
||||
### 白名单过滤服务器工具
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
|
||||
tools:
|
||||
include: [create_issue, list_issues]
|
||||
```
|
||||
|
||||
只有列出的 MCP 服务器工具会被注册。
|
||||
|
||||
### 黑名单过滤服务器工具
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
stripe:
|
||||
url: "https://mcp.stripe.com"
|
||||
tools:
|
||||
exclude: [delete_customer]
|
||||
```
|
||||
|
||||
除排除项外，所有服务器工具均被注册。
|
||||
|
||||
### 优先级规则
|
||||
|
||||
若两者同时存在：
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
include: [create_issue]
|
||||
exclude: [create_issue, delete_issue]
|
||||
```
|
||||
|
||||
`include` 优先生效。
|
||||
|
||||
### 同样可过滤实用工具
|
||||
|
||||
你也可以单独禁用 Hermes 添加的实用工具封装：
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
docs:
|
||||
url: "https://mcp.docs.example.com"
|
||||
tools:
|
||||
prompts: false
|
||||
resources: false
|
||||
```
|
||||
|
||||
含义：
|
||||
- `tools.resources: false` 禁用 `list_resources` 和 `read_resource`
|
||||
- `tools.prompts: false` 禁用 `list_prompts` 和 `get_prompt`
|
||||
|
||||
### 完整示例
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
|
||||
tools:
|
||||
include: [create_issue, list_issues, search_code]
|
||||
prompts: false
|
||||
|
||||
stripe:
|
||||
url: "https://mcp.stripe.com"
|
||||
headers:
|
||||
Authorization: "Bearer ***"
|
||||
tools:
|
||||
exclude: [delete_customer]
|
||||
resources: false
|
||||
|
||||
legacy:
|
||||
url: "https://mcp.legacy.internal"
|
||||
enabled: false
|
||||
```
|
||||
|
||||
## 如果所有工具都被过滤掉会怎样？
|
||||
|
||||
如果你的配置过滤掉了所有可调用工具，并禁用或省略了所有支持的实用工具，Hermes 不会为该服务器创建空的运行时 MCP 工具集。
|
||||
|
||||
这样可以保持工具列表整洁。
|
||||
|
||||
## 运行时行为
|
||||
|
||||
### 发现时机
|
||||
|
||||
Hermes 在启动时发现 MCP 服务器，并将其工具注册到普通工具注册表中。
|
||||
|
||||
### 动态工具发现
|
||||
|
||||
MCP 服务器可以在运行时通过发送 `notifications/tools/list_changed` 通知，告知 Hermes 其可用工具发生了变化。Hermes 收到该通知后，会自动重新获取服务器的工具列表并更新注册表——无需手动执行 `/reload-mcp`。
|
||||
|
||||
这对于能力动态变化的 MCP 服务器非常有用（例如，加载新数据库 schema 时添加工具，或服务下线时移除工具）。
|
||||
|
||||
刷新操作受锁保护，因此同一服务器快速连续发送的通知不会导致重叠刷新。prompt 和资源变更通知（`prompts/list_changed`、`resources/list_changed`）会被接收，但暂未处理。
|
||||
|
||||
### 重新加载
|
||||
|
||||
如果你修改了 MCP 配置，请使用：
|
||||
|
||||
```text
|
||||
/reload-mcp
|
||||
```
|
||||
|
||||
这会从配置重新加载 MCP 服务器并刷新可用工具列表。对于服务器主动推送的运行时工具变更，请参阅上方的[动态工具发现](#dynamic-tool-discovery)。
|
||||
|
||||
### 工具集
|
||||
|
||||
每个已配置的 MCP 服务器，在贡献至少一个已注册工具时，也会创建一个运行时工具集：
|
||||
|
||||
```text
|
||||
mcp-<server>
|
||||
```
|
||||
|
||||
这使得在工具集层面更容易理解 MCP 服务器的情况。
|
||||
|
||||
## 安全模型
|
||||
|
||||
### Stdio 环境变量过滤
|
||||
|
||||
对于 stdio 服务器，Hermes 不会盲目传递你的完整 shell 环境。
|
||||
|
||||
只有显式配置的 `env` 加上安全基线才会被传递。这减少了意外泄露密钥的风险。
|
||||
|
||||
### 配置层面的暴露控制
|
||||
|
||||
新的过滤支持同时也是一种安全控制：
|
||||
- 禁用你不希望模型看到的危险工具
|
||||
- 对敏感服务器只暴露最小白名单
|
||||
- 在不需要暴露该接口时，禁用资源/prompt 封装
|
||||
|
||||
## 示例用例
|
||||
|
||||
### GitHub 服务器，仅暴露最小 issue 管理接口
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
|
||||
tools:
|
||||
include: [list_issues, create_issue, update_issue]
|
||||
prompts: false
|
||||
resources: false
|
||||
```
|
||||
|
||||
使用方式：
|
||||
|
||||
```text
|
||||
Show me open issues labeled bug, then draft a new issue for the flaky MCP reconnection behavior.
|
||||
```
|
||||
|
||||
### Stripe 服务器，移除危险操作
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
stripe:
|
||||
url: "https://mcp.stripe.com"
|
||||
headers:
|
||||
Authorization: "Bearer ***"
|
||||
tools:
|
||||
exclude: [delete_customer, refund_payment]
|
||||
```
|
||||
|
||||
使用方式：
|
||||
|
||||
```text
|
||||
Look up the last 10 failed payments and summarize common failure reasons.
|
||||
```
|
||||
|
||||
### 文件系统服务器，限定单个项目根目录
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
project_fs:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]
|
||||
```
|
||||
|
||||
使用方式：
|
||||
|
||||
```text
|
||||
Inspect the project root and explain the directory layout.
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
### MCP 服务器无法连接
|
||||
|
||||
检查：
|
||||
|
||||
```bash
|
||||
# 验证 MCP 依赖已安装（标准安装已包含）
|
||||
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"
|
||||
|
||||
node --version
|
||||
npx --version
|
||||
```
|
||||
|
||||
然后验证你的配置并重启 Hermes。
|
||||
|
||||
### 工具未出现
|
||||
|
||||
可能原因：
|
||||
- 服务器连接失败
|
||||
- 发现过程失败
|
||||
- 你的过滤配置排除了这些工具
|
||||
- 该服务器不存在对应的实用工具能力
|
||||
- 服务器通过 `enabled: false` 被禁用
|
||||
|
||||
如果你是有意过滤，这是预期行为。
|
||||
|
||||
### 为什么资源或 prompt 实用工具没有出现？
|
||||
|
||||
因为 Hermes 现在只在以下两个条件同时满足时才注册这些封装：
|
||||
1. 你的配置允许它们
|
||||
2. 服务器会话实际支持该能力
|
||||
|
||||
这是有意为之，保持工具列表的真实性。
|
||||
|
||||
## 并行工具调用
|
||||
|
||||
默认情况下，MCP 工具按顺序执行——一次一个。如果你的 MCP 服务器暴露的工具可以安全并发运行（例如只读查询、独立 API 调用），可以选择启用并行执行：
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
docs:
|
||||
command: "docs-server"
|
||||
supports_parallel_tool_calls: true
|
||||
```
|
||||
|
||||
当 `supports_parallel_tool_calls` 为 `true` 时，Hermes 可能在单次工具调用批次中同时执行该服务器的多个工具，就像对内置只读工具（`web_search`、`read_file` 等）的处理方式一样。
|
||||
|
||||
:::caution
|
||||
只对工具可以安全同时运行的 MCP 服务器启用并行调用。如果工具会读写共享状态、文件、数据库或外部资源，请在启用此设置前仔细评估读写竞争条件。
|
||||
:::
|
||||
|
||||
## MCP Sampling 支持
|
||||
|
||||
MCP 服务器可以通过 `sampling/createMessage` 协议向 Hermes 请求 LLM 推理。这允许 MCP 服务器代表自己请求 Hermes 生成文本——适用于需要 LLM 能力但没有自己模型访问权限的服务器。
|
||||
|
||||
Sampling 对所有 MCP 服务器**默认启用**（当 MCP SDK 支持时）。可在 `sampling` 键下按服务器配置：
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
my_server:
|
||||
command: "my-mcp-server"
|
||||
sampling:
|
||||
enabled: true # 启用 sampling（默认：true）
|
||||
model: "openai/gpt-4o" # 覆盖 sampling 请求使用的模型（可选）
|
||||
max_tokens_cap: 4096 # 每次 sampling 响应的最大 token 数（默认：4096）
|
||||
timeout: 30 # 每次请求的超时时间，单位秒（默认：30）
|
||||
max_rpm: 10 # 速率限制：每分钟最大请求数（默认：10）
|
||||
max_tool_rounds: 5 # sampling 循环中的最大工具调用轮数（默认：5）
|
||||
allowed_models: [] # 服务器可请求的模型名称白名单（空 = 不限）
|
||||
log_level: "info" # 审计日志级别：debug、info 或 warning（默认：info）
|
||||
```
|
||||
|
||||
sampling 处理器包含滑动窗口速率限制器、按请求超时和工具循环深度限制，防止失控使用。每个服务器实例会跟踪指标（请求数、错误数、已用 token 数）。
|
||||
|
||||
如需对特定服务器禁用 sampling：
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
untrusted_server:
|
||||
url: "https://mcp.example.com"
|
||||
sampling:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
## 将 Hermes 作为 MCP 服务器运行
|
||||
|
||||
除了连接**到** MCP 服务器，Hermes 也可以**作为** MCP 服务器运行。这让其他支持 MCP 的 agent（Claude Code、Cursor、Codex 或任何 MCP 客户端）能够使用 Hermes 的消息能力——列出会话、读取消息历史，以及跨所有已连接平台发送消息。
|
||||
|
||||
### 适用场景
|
||||
|
||||
- 你希望 Claude Code、Cursor 或其他编程 agent 通过 Hermes 发送和读取 Telegram/Discord/Slack 消息
|
||||
- 你需要一个单一的 MCP 服务器，同时桥接 Hermes 所有已连接的消息平台
|
||||
- 你已经有一个运行中的 Hermes gateway，并已连接各平台
|
||||
|
||||
### 快速开始
|
||||
|
||||
```bash
|
||||
hermes mcp serve
|
||||
```
|
||||
|
||||
这会启动一个 stdio MCP 服务器。进程生命周期由 MCP 客户端（而非你）管理。
|
||||
|
||||
### MCP 客户端配置
|
||||
|
||||
将 Hermes 添加到你的 MCP 客户端配置中。例如，在 Claude Code 的 `~/.claude/claude_desktop_config.json` 中：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"hermes": {
|
||||
"command": "hermes",
|
||||
"args": ["mcp", "serve"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
或者，如果你将 Hermes 安装在特定位置：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"hermes": {
|
||||
"command": "/home/user/.hermes/hermes-agent/venv/bin/hermes",
|
||||
"args": ["mcp", "serve"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 可用工具
|
||||
|
||||
MCP 服务器暴露 10 个工具，与 OpenClaw 的 channel bridge 接口一致，并额外提供一个 Hermes 专属的 channel 浏览器：
|
||||
|
||||
| 工具 | 描述 |
|
||||
|------|-------------|
|
||||
| `conversations_list` | 列出活跃的消息会话。可按平台过滤或按名称搜索。 |
|
||||
| `conversation_get` | 通过 session key 获取某个会话的详细信息。 |
|
||||
| `messages_read` | 读取某个会话的近期消息历史。 |
|
||||
| `attachments_fetch` | 从特定消息中提取非文本附件（图片、媒体）。 |
|
||||
| `events_poll` | 从指定游标位置轮询新的会话事件。 |
|
||||
| `events_wait` | 长轮询/阻塞，直到下一个事件到达（接近实时）。 |
|
||||
| `messages_send` | 通过平台发送消息（例如 `telegram:123456`、`discord:#general`）。 |
|
||||
| `channels_list` | 列出所有平台上可用的消息目标。 |
|
||||
| `permissions_list_open` | 列出本次 bridge 会话中观察到的待审批请求。 |
|
||||
| `permissions_respond` | 允许或拒绝待审批请求。 |
|
||||
|
||||
### 事件系统
|
||||
|
||||
MCP 服务器包含一个实时事件桥，轮询 Hermes 的会话数据库以获取新消息。这让 MCP 客户端能够近实时感知新来的会话：
|
||||
|
||||
```
|
||||
# 轮询新事件（非阻塞）
|
||||
events_poll(after_cursor=0)
|
||||
|
||||
# 等待下一个事件（阻塞，直到超时）
|
||||
events_wait(after_cursor=42, timeout_ms=30000)
|
||||
```
|
||||
|
||||
事件类型：`message`、`approval_requested`、`approval_resolved`
|
||||
|
||||
事件队列存储在内存中，在 bridge 连接时开始工作。较旧的消息可通过 `messages_read` 获取。
|
||||
|
||||
### 选项
|
||||
|
||||
```bash
|
||||
hermes mcp serve # 普通模式
|
||||
hermes mcp serve --verbose # 在 stderr 输出调试日志
|
||||
```
|
||||
|
||||
### 工作原理
|
||||
|
||||
MCP 服务器直接从 Hermes 的会话存储（`~/.hermes/sessions/sessions.json` 和 SQLite 数据库）读取会话数据。后台线程轮询数据库以获取新消息，并维护一个内存事件队列。发送消息时，使用与 Hermes agent 本身相同的 `send_message` 基础设施。
|
||||
|
||||
读取操作（列出会话、读取历史、轮询事件）**不需要** gateway 运行。发送操作**需要** gateway 运行，因为平台适配器需要活跃连接。
|
||||
|
||||
### 当前限制
|
||||
|
||||
- 内嵌的 `hermes mcp serve` 目前只暴露 **stdio-only** MCP 服务器。如果你需要 HTTP MCP 服务器，请运行单独的适配器——或者，更常见的做法是使用 Hermes 的 MCP **客户端**侧，它已经同时支持 stdio 和 HTTP（`mcp_servers.yaml` / `config.yaml` 中的 `url` + `headers`；参见上方的 [HTTP 服务器](#http-servers)）。
|
||||
- 事件轮询间隔约 200ms，通过基于 mtime 优化的数据库轮询实现（文件未变化时跳过处理）
|
||||
- 暂不支持 `claude/channel` 推送通知协议
|
||||
- 仅支持纯文本发送（`messages_send` 不支持媒体/附件发送）
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [在 Hermes 中使用 MCP](/guides/use-mcp-with-hermes)
|
||||
- [CLI 命令](/reference/cli-commands)
|
||||
- [斜杠命令](/reference/slash-commands)
|
||||
- [常见问题](/reference/faq)
|
||||
+549
@@ -0,0 +1,549 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: "Memory Providers"
|
||||
description: "外部记忆提供者插件 — Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover、Supermemory"
|
||||
---
|
||||
|
||||
# Memory Providers
|
||||
|
||||
Hermes Agent 内置 8 个外部记忆提供者插件，为 Agent 提供跨会话的持久化知识，超越内置的 MEMORY.md 和 USER.md。同一时间只能激活**一个**外部提供者——内置记忆始终与其并行工作。
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
hermes memory setup # 交互式选择器 + 配置
|
||||
hermes memory status # 查看当前激活状态
|
||||
hermes memory off # 禁用外部提供者
|
||||
```
|
||||
|
||||
也可以通过 `hermes plugins` → Provider Plugins → Memory Provider 选择激活的记忆提供者。
|
||||
|
||||
或在 `~/.hermes/config.yaml` 中手动设置：
|
||||
|
||||
```yaml
|
||||
memory:
|
||||
provider: openviking # 或 honcho, mem0, hindsight, holographic, retaindb, byterover, supermemory
|
||||
```
|
||||
|
||||
## 工作原理
|
||||
|
||||
当记忆提供者激活时，Hermes 会自动：
|
||||
|
||||
1. **注入提供者上下文**到系统 prompt（提示词）中（提供者已知的内容）
|
||||
2. **在每轮对话前预取相关记忆**（后台非阻塞）
|
||||
3. **在每次响应后将对话轮次同步**到提供者
|
||||
4. **在会话结束时提取记忆**（适用于支持此功能的提供者）
|
||||
5. **将内置记忆写入镜像**到外部提供者
|
||||
6. **添加提供者专属工具**，使 Agent 能够搜索、存储和管理记忆
|
||||
|
||||
内置记忆（MEMORY.md / USER.md）继续按原有方式工作。外部提供者是增量叠加的。
|
||||
|
||||
## 可用提供者
|
||||
|
||||
### Honcho
|
||||
|
||||
AI 原生的跨会话用户建模，具备辩证推理、会话范围上下文注入、语义搜索和持久化结论。基础上下文现在包含会话摘要以及用户表示和 peer card，使 Agent 能感知已讨论的内容。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **适合场景** | 具有跨会话上下文的多 Agent 系统、用户-Agent 对齐 |
|
||||
| **依赖** | `pip install honcho-ai` + [API key](https://app.honcho.dev) 或自托管实例 |
|
||||
| **数据存储** | Honcho Cloud 或自托管 |
|
||||
| **费用** | Honcho 定价（云端）/ 免费（自托管） |
|
||||
|
||||
**工具（5 个）：** `honcho_profile`（读取/更新 peer card）、`honcho_search`（语义搜索）、`honcho_context`（会话上下文——摘要、表示、card、消息）、`honcho_reasoning`（LLM 合成）、`honcho_conclude`（创建/删除结论）
|
||||
|
||||
**架构：** 双层上下文注入——基础层（会话摘要 + 表示 + peer card，按 `contextCadence` 刷新）加上辩证补充层（LLM 推理，按 `dialecticCadence` 刷新）。辩证层根据基础上下文是否存在，自动选择冷启动 prompt（通用用户事实）或热 prompt（会话范围上下文）。
|
||||
|
||||
**三个正交配置项**独立控制成本和深度：
|
||||
|
||||
- `contextCadence` — 基础层刷新频率（API 调用频率）
|
||||
- `dialecticCadence` — 辩证 LLM 触发频率（LLM 调用频率）
|
||||
- `dialecticDepth` — 每次辩证调用的 `.chat()` 轮数（1–3，推理深度）
|
||||
|
||||
**安装向导：**
|
||||
```bash
|
||||
hermes memory setup # 选择 "honcho" — 运行 Honcho 专属的安装后配置
|
||||
```
|
||||
|
||||
旧版 `hermes honcho setup` 命令仍然有效（现在会重定向到 `hermes memory setup`），但只有在 Honcho 被选为激活记忆提供者后才会注册。
|
||||
|
||||
**配置：** `$HERMES_HOME/honcho.json`（profile 本地）或 `~/.honcho/config.json`（全局）。解析顺序：`$HERMES_HOME/honcho.json` > `~/.hermes/honcho.json` > `~/.honcho/config.json`。参见[配置参考](https://github.com/hermes-ai/hermes-agent/blob/main/plugins/memory/honcho/README.md)和 [Honcho 集成指南](https://docs.honcho.dev/v3/guides/integrations/hermes)。
|
||||
|
||||
<details>
|
||||
<summary>完整配置参考</summary>
|
||||
|
||||
| 键 | 默认值 | 描述 |
|
||||
|-----|---------|-------------|
|
||||
| `apiKey` | -- | 来自 [app.honcho.dev](https://app.honcho.dev) 的 API key |
|
||||
| `baseUrl` | -- | 自托管 Honcho 的 Base URL |
|
||||
| `peerName` | -- | 用户 peer 身份 |
|
||||
| `aiPeer` | host key | AI peer 身份（每个 profile 一个） |
|
||||
| `workspace` | host key | 共享 workspace ID |
|
||||
| `contextTokens` | `null`（无上限） | 每轮自动注入上下文的 token 预算。按词边界截断 |
|
||||
| `contextCadence` | `1` | `context()` API 调用之间的最小轮数（基础层刷新） |
|
||||
| `dialecticCadence` | `2` | `peer.chat()` LLM 调用之间的最小轮数。建议 1–5。仅适用于 `hybrid`/`context` 模式 |
|
||||
| `dialecticDepth` | `1` | 每次辩证调用的 `.chat()` 轮数。限制在 1–3。第 0 轮：冷/热 prompt，第 1 轮：自我审计，第 2 轮：调和 |
|
||||
| `dialecticDepthLevels` | `null` | 可选的每轮推理级别数组，例如 `["minimal", "low", "medium"]`。覆盖比例默认值 |
|
||||
| `dialecticReasoningLevel` | `'low'` | 基础推理级别：`minimal`、`low`、`medium`、`high`、`max` |
|
||||
| `dialecticDynamic` | `true` | 为 `true` 时，模型可通过工具参数在每次调用时覆盖推理级别 |
|
||||
| `dialecticMaxChars` | `600` | 注入系统 prompt 的辩证结果最大字符数 |
|
||||
| `recallMode` | `'hybrid'` | `hybrid`（自动注入 + 工具）、`context`（仅注入）、`tools`（仅工具） |
|
||||
| `writeFrequency` | `'async'` | 消息刷新时机：`async`（后台线程）、`turn`（同步）、`session`（会话结束时批量）或整数 N |
|
||||
| `saveMessages` | `true` | 是否将消息持久化到 Honcho API |
|
||||
| `observationMode` | `'directional'` | `directional`（全部开启）或 `unified`（共享池）。通过 `observation` 对象覆盖 |
|
||||
| `messageMaxChars` | `25000` | 每条消息的最大字符数（超出时分块） |
|
||||
| `dialecticMaxInputChars` | `10000` | 传入 `peer.chat()` 的辩证查询输入最大字符数 |
|
||||
| `sessionStrategy` | `'per-directory'` | `per-directory`、`per-repo`、`per-session`、`global` |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>最简 honcho.json（云端）</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"apiKey": "your-key-from-app.honcho.dev",
|
||||
"hosts": {
|
||||
"hermes": {
|
||||
"enabled": true,
|
||||
"aiPeer": "hermes",
|
||||
"peerName": "your-name",
|
||||
"workspace": "hermes"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>最简 honcho.json（自托管）</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"baseUrl": "http://localhost:8000",
|
||||
"hosts": {
|
||||
"hermes": {
|
||||
"enabled": true,
|
||||
"aiPeer": "hermes",
|
||||
"peerName": "your-name",
|
||||
"workspace": "hermes"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
:::tip 从 `hermes honcho` 迁移
|
||||
如果你之前使用过 `hermes honcho setup`，你的配置和所有服务端数据均完好无损。只需通过安装向导重新启用，或手动设置 `memory.provider: honcho`，即可通过新系统重新激活。
|
||||
:::
|
||||
|
||||
**多 peer 配置：**
|
||||
|
||||
Honcho 将对话建模为 peer 之间的消息交换——每个 Hermes profile 对应一个用户 peer 加一个 AI peer，共享同一个 workspace。workspace 是共享环境：用户 peer 在各 profile 间全局共享，每个 AI peer 拥有独立身份。每个 AI peer 从自身的观察中独立构建表示/card，因此 `coder` profile 保持代码导向，而 `writer` profile 针对同一用户保持编辑导向。
|
||||
|
||||
映射关系：
|
||||
|
||||
| 概念 | 含义 |
|
||||
|---------|-----------|
|
||||
| **Workspace** | 共享环境。同一 workspace 下的所有 Hermes profile 共享同一用户身份。 |
|
||||
| **用户 peer**（`peerName`） | 人类用户。在 workspace 内跨 profile 共享。 |
|
||||
| **AI peer**（`aiPeer`） | 每个 Hermes profile 一个。host key `hermes` → 默认；其他 profile 使用 `hermes.<profile>`。 |
|
||||
| **Observation** | 每个 peer 的开关，控制 Honcho 从哪些消息中建模。`directional`（默认，全部开启）或 `unified`（单一观察者池）。 |
|
||||
|
||||
### 新建 profile，创建新 Honcho peer
|
||||
|
||||
```bash
|
||||
hermes profile create coder --clone
|
||||
```
|
||||
|
||||
`--clone` 在 `honcho.json` 中创建一个 `hermes.coder` host 块，包含 `aiPeer: "coder"`、共享的 `workspace`、继承的 `peerName`、`recallMode`、`writeFrequency`、`observation` 等。AI peer 会在 Honcho 中提前创建，确保在第一条消息之前就已存在。
|
||||
|
||||
### 为现有 profile 补充 Honcho peer
|
||||
|
||||
```bash
|
||||
hermes honcho sync
|
||||
```
|
||||
|
||||
扫描所有 Hermes profile，为没有 host 块的 profile 创建 host 块，从默认 `hermes` 块继承设置，并提前创建新的 AI peer。幂等操作——跳过已有 host 块的 profile。
|
||||
|
||||
### 每个 profile 的 observation 配置
|
||||
|
||||
每个 host 块可以独立覆盖 observation 配置。示例：一个以代码为中心的 profile，AI peer 观察用户但不自我建模：
|
||||
|
||||
```json
|
||||
"hermes.coder": {
|
||||
"aiPeer": "coder",
|
||||
"observation": {
|
||||
"user": { "observeMe": true, "observeOthers": true },
|
||||
"ai": { "observeMe": false, "observeOthers": true }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Observation 开关（每个 peer 一组）：**
|
||||
|
||||
| 开关 | 效果 |
|
||||
|--------|--------|
|
||||
| `observeMe` | Honcho 根据该 peer 自身的消息构建其表示 |
|
||||
| `observeOthers` | 该 peer 观察另一 peer 的消息（用于跨 peer 推理） |
|
||||
|
||||
通过 `observationMode` 使用预设：
|
||||
|
||||
- **`"directional"`**（默认）——四个标志全部开启。完全互相观察；启用跨 peer 辩证。
|
||||
- **`"unified"`**——用户 `observeMe: true`，AI `observeOthers: true`，其余为 false。单一观察者池；AI 对用户建模但不自我建模，用户 peer 仅自我建模。
|
||||
|
||||
通过 [Honcho 控制台](https://app.honcho.dev) 设置的服务端开关优先于本地默认值——在会话初始化时同步回来。
|
||||
|
||||
参见 [Honcho 页面](./honcho.md#observation-directional-vs-unified) 获取完整的 observation 参考。
|
||||
|
||||
<details>
|
||||
<summary>完整 honcho.json 示例（多 profile）</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"apiKey": "your-key",
|
||||
"workspace": "hermes",
|
||||
"peerName": "eri",
|
||||
"hosts": {
|
||||
"hermes": {
|
||||
"enabled": true,
|
||||
"aiPeer": "hermes",
|
||||
"workspace": "hermes",
|
||||
"peerName": "eri",
|
||||
"recallMode": "hybrid",
|
||||
"writeFrequency": "async",
|
||||
"sessionStrategy": "per-directory",
|
||||
"observation": {
|
||||
"user": { "observeMe": true, "observeOthers": true },
|
||||
"ai": { "observeMe": true, "observeOthers": true }
|
||||
},
|
||||
"dialecticReasoningLevel": "low",
|
||||
"dialecticDynamic": true,
|
||||
"dialecticCadence": 2,
|
||||
"dialecticDepth": 1,
|
||||
"dialecticMaxChars": 600,
|
||||
"contextCadence": 1,
|
||||
"messageMaxChars": 25000,
|
||||
"saveMessages": true
|
||||
},
|
||||
"hermes.coder": {
|
||||
"enabled": true,
|
||||
"aiPeer": "coder",
|
||||
"workspace": "hermes",
|
||||
"peerName": "eri",
|
||||
"recallMode": "tools",
|
||||
"observation": {
|
||||
"user": { "observeMe": true, "observeOthers": false },
|
||||
"ai": { "observeMe": true, "observeOthers": true }
|
||||
}
|
||||
},
|
||||
"hermes.writer": {
|
||||
"enabled": true,
|
||||
"aiPeer": "writer",
|
||||
"workspace": "hermes",
|
||||
"peerName": "eri"
|
||||
}
|
||||
},
|
||||
"sessions": {
|
||||
"/home/user/myproject": "myproject-main"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
参见[配置参考](https://github.com/hermes-ai/hermes-agent/blob/main/plugins/memory/honcho/README.md)和 [Honcho 集成指南](https://docs.honcho.dev/v3/guides/integrations/hermes)。
|
||||
|
||||
|
||||
---
|
||||
|
||||
### OpenViking
|
||||
|
||||
由 Volcengine（ByteDance）提供的上下文数据库，具备文件系统式知识层级、分层检索，以及自动将记忆提取为 6 个类别的功能。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **适合场景** | 具有结构化浏览功能的自托管知识管理 |
|
||||
| **依赖** | `pip install openviking` + 运行中的服务器 |
|
||||
| **数据存储** | 自托管（本地或云端） |
|
||||
| **费用** | 免费（开源，AGPL-3.0） |
|
||||
|
||||
**工具：** `viking_search`（语义搜索）、`viking_read`（分层：摘要/概览/全文）、`viking_browse`（文件系统导航）、`viking_remember`（存储事实）、`viking_add_resource`（导入 URL/文档）
|
||||
|
||||
**安装：**
|
||||
```bash
|
||||
# 先启动 OpenViking 服务器
|
||||
pip install openviking
|
||||
openviking-server
|
||||
|
||||
# 然后配置 Hermes
|
||||
hermes memory setup # 选择 "openviking"
|
||||
# 或手动配置：
|
||||
hermes config set memory.provider openviking
|
||||
echo "OPENVIKING_ENDPOINT=http://localhost:1933" >> ~/.hermes/.env
|
||||
```
|
||||
|
||||
**主要特性：**
|
||||
- 分层上下文加载：L0（约 100 tokens）→ L1（约 2k）→ L2（完整）
|
||||
- 会话提交时自动提取记忆（profile、偏好、实体、事件、案例、模式）
|
||||
- `viking://` URI 方案用于层级知识浏览
|
||||
|
||||
---
|
||||
|
||||
### Mem0
|
||||
|
||||
服务端 LLM 事实提取，具备语义搜索、重排序和自动去重功能。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **适合场景** | 免维护的记忆管理——Mem0 自动处理提取 |
|
||||
| **依赖** | `pip install mem0ai` + API key |
|
||||
| **数据存储** | Mem0 Cloud |
|
||||
| **费用** | Mem0 定价 |
|
||||
|
||||
**工具：** `mem0_profile`（所有已存储记忆）、`mem0_search`（语义搜索 + 重排序）、`mem0_conclude`（逐字存储事实）
|
||||
|
||||
**安装：**
|
||||
```bash
|
||||
hermes memory setup # 选择 "mem0"
|
||||
# 或手动配置：
|
||||
hermes config set memory.provider mem0
|
||||
echo "MEM0_API_KEY=your-key" >> ~/.hermes/.env
|
||||
```
|
||||
|
||||
**配置：** `$HERMES_HOME/mem0.json`
|
||||
|
||||
| 键 | 默认值 | 描述 |
|
||||
|-----|---------|-------------|
|
||||
| `user_id` | `hermes-user` | 用户标识符 |
|
||||
| `agent_id` | `hermes` | Agent 标识符 |
|
||||
|
||||
---
|
||||
|
||||
### Hindsight
|
||||
|
||||
具备知识图谱、实体解析和多策略检索的长期记忆。`hindsight_reflect` 工具提供其他提供者均不具备的跨记忆合成能力。自动保留完整对话轮次（包括工具调用），并进行会话级文档追踪。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **适合场景** | 基于知识图谱的实体关系召回 |
|
||||
| **依赖** | 云端：来自 [ui.hindsight.vectorize.io](https://ui.hindsight.vectorize.io) 的 API key。本地：LLM API key（OpenAI、Groq、OpenRouter 等） |
|
||||
| **数据存储** | Hindsight Cloud 或本地嵌入式 PostgreSQL |
|
||||
| **费用** | Hindsight 定价（云端）或免费（本地） |
|
||||
|
||||
**工具：** `hindsight_retain`（带实体提取的存储）、`hindsight_recall`（多策略搜索）、`hindsight_reflect`（跨记忆合成）
|
||||
|
||||
**安装：**
|
||||
```bash
|
||||
hermes memory setup # 选择 "hindsight"
|
||||
# 或手动配置：
|
||||
hermes config set memory.provider hindsight
|
||||
echo "HINDSIGHT_API_KEY=your-key" >> ~/.hermes/.env
|
||||
```
|
||||
|
||||
安装向导会自动安装依赖，并仅安装所选模式所需的内容（云端用 `hindsight-client`，本地用 `hindsight-all`）。需要 `hindsight-client >= 0.4.22`（会话启动时若版本过旧则自动升级）。
|
||||
|
||||
**本地模式 UI：** `hindsight-embed -p hermes ui start`
|
||||
|
||||
**配置：** `$HERMES_HOME/hindsight/config.json`
|
||||
|
||||
| 键 | 默认值 | 描述 |
|
||||
|-----|---------|-------------|
|
||||
| `mode` | `cloud` | `cloud` 或 `local` |
|
||||
| `bank_id` | `hermes` | 记忆库标识符 |
|
||||
| `recall_budget` | `mid` | 召回彻底程度：`low` / `mid` / `high` |
|
||||
| `memory_mode` | `hybrid` | `hybrid`（上下文 + 工具）、`context`（仅自动注入）、`tools`（仅工具） |
|
||||
| `auto_retain` | `true` | 自动保留对话轮次 |
|
||||
| `auto_recall` | `true` | 每轮对话前自动召回记忆 |
|
||||
| `retain_async` | `true` | 在服务器上异步处理保留操作 |
|
||||
| `retain_context` | `conversation between Hermes Agent and the User` | 保留记忆的上下文标签 |
|
||||
| `retain_tags` | — | 应用于保留记忆的默认标签；与每次工具调用的标签合并 |
|
||||
| `retain_source` | — | 附加到保留记忆的可选 `metadata.source` |
|
||||
| `retain_user_prefix` | `User` | 自动保留的对话记录中用户轮次前的标签 |
|
||||
| `retain_assistant_prefix` | `Assistant` | 自动保留的对话记录中助手轮次前的标签 |
|
||||
| `recall_tags` | — | 召回时用于过滤的标签 |
|
||||
|
||||
完整配置参考参见[插件 README](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/hindsight/README.md)。
|
||||
|
||||
---
|
||||
|
||||
### Holographic
|
||||
|
||||
本地 SQLite 事实存储，具备 FTS5 全文搜索、信任评分和 HRR（Holographic Reduced Representations，全息降维表示）用于组合代数查询。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **适合场景** | 无外部依赖的纯本地高级检索记忆 |
|
||||
| **依赖** | 无（SQLite 始终可用）。NumPy 可选，用于 HRR 代数。 |
|
||||
| **数据存储** | 本地 SQLite |
|
||||
| **费用** | 免费 |
|
||||
|
||||
**工具：** `fact_store`（9 个动作：add、search、probe、related、reason、contradict、update、remove、list）、`fact_feedback`（有用/无用评分，用于训练信任评分）
|
||||
|
||||
**安装：**
|
||||
```bash
|
||||
hermes memory setup # 选择 "holographic"
|
||||
# 或手动配置：
|
||||
hermes config set memory.provider holographic
|
||||
```
|
||||
|
||||
**配置：** `plugins.hermes-memory-store` 下的 `config.yaml`
|
||||
|
||||
| 键 | 默认值 | 描述 |
|
||||
|-----|---------|-------------|
|
||||
| `db_path` | `$HERMES_HOME/memory_store.db` | SQLite 数据库路径 |
|
||||
| `auto_extract` | `false` | 会话结束时自动提取事实 |
|
||||
| `default_trust` | `0.5` | 默认信任评分（0.0–1.0） |
|
||||
|
||||
**独特能力：**
|
||||
- `probe` — 针对特定实体的代数召回（某人/某物的所有事实）
|
||||
- `reason` — 跨多个实体的组合 AND 查询
|
||||
- `contradict` — 自动检测冲突事实
|
||||
- 信任评分，带非对称反馈（有用 +0.05 / 无用 -0.10）
|
||||
|
||||
---
|
||||
|
||||
### RetainDB
|
||||
|
||||
云端记忆 API，具备混合搜索（向量 + BM25 + 重排序）、7 种记忆类型和增量压缩。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **适合场景** | 已使用 RetainDB 基础设施的团队 |
|
||||
| **依赖** | RetainDB 账号 + API key |
|
||||
| **数据存储** | RetainDB Cloud |
|
||||
| **费用** | $20/月 |
|
||||
|
||||
**工具：** `retaindb_profile`（用户 profile）、`retaindb_search`（语义搜索）、`retaindb_context`（任务相关上下文）、`retaindb_remember`（带类型和重要性的存储）、`retaindb_forget`（删除记忆）
|
||||
|
||||
**安装：**
|
||||
```bash
|
||||
hermes memory setup # 选择 "retaindb"
|
||||
# 或手动配置：
|
||||
hermes config set memory.provider retaindb
|
||||
echo "RETAINDB_API_KEY=your-key" >> ~/.hermes/.env
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ByteRover
|
||||
|
||||
通过 `brv` CLI 实现持久化记忆——具备分层知识树和分层检索（模糊文本 → LLM 驱动搜索）。本地优先，可选云端同步。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **适合场景** | 希望使用可移植、本地优先记忆和 CLI 的开发者 |
|
||||
| **依赖** | ByteRover CLI（`npm install -g byterover-cli` 或[安装脚本](https://byterover.dev)） |
|
||||
| **数据存储** | 本地（默认）或 ByteRover Cloud（可选同步） |
|
||||
| **费用** | 免费（本地）或 ByteRover 定价（云端） |
|
||||
|
||||
**工具：** `brv_query`（搜索知识树）、`brv_curate`（存储事实/决策/模式）、`brv_status`（CLI 版本 + 树状统计）
|
||||
|
||||
**安装：**
|
||||
```bash
|
||||
# 先安装 CLI
|
||||
curl -fsSL https://byterover.dev/install.sh | sh
|
||||
|
||||
# 然后配置 Hermes
|
||||
hermes memory setup # 选择 "byterover"
|
||||
# 或手动配置：
|
||||
hermes config set memory.provider byterover
|
||||
```
|
||||
|
||||
**主要特性：**
|
||||
- 自动预压缩提取（在上下文压缩丢弃内容前保存洞察）
|
||||
- 知识树存储于 `$HERMES_HOME/byterover/`（profile 范围隔离）
|
||||
- SOC2 Type II 认证的云端同步（可选）
|
||||
|
||||
---
|
||||
|
||||
### Supermemory
|
||||
|
||||
语义长期记忆，具备 profile 召回、语义搜索、显式记忆工具，以及通过 Supermemory graph API 进行会话结束时的对话导入。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **适合场景** | 带用户 profile 和会话级图谱构建的语义召回 |
|
||||
| **依赖** | `pip install supermemory` + [API key](https://supermemory.ai) |
|
||||
| **数据存储** | Supermemory Cloud |
|
||||
| **费用** | Supermemory 定价 |
|
||||
|
||||
**工具：** `supermemory_store`（保存显式记忆）、`supermemory_search`（语义相似度搜索）、`supermemory_forget`（按 ID 或最佳匹配查询遗忘）、`supermemory_profile`（持久化 profile + 近期上下文）
|
||||
|
||||
**安装：**
|
||||
```bash
|
||||
hermes memory setup # 选择 "supermemory"
|
||||
# 或手动配置：
|
||||
hermes config set memory.provider supermemory
|
||||
echo 'SUPERMEMORY_API_KEY=***' >> ~/.hermes/.env
|
||||
```
|
||||
|
||||
**配置：** `$HERMES_HOME/supermemory.json`
|
||||
|
||||
| 键 | 默认值 | 描述 |
|
||||
|-----|---------|-------------|
|
||||
| `container_tag` | `hermes` | 用于搜索和写入的容器标签。支持 `{identity}` 模板用于 profile 范围隔离。 |
|
||||
| `auto_recall` | `true` | 在每轮对话前注入相关记忆上下文 |
|
||||
| `auto_capture` | `true` | 每次响应后存储清理过的用户-助手轮次 |
|
||||
| `max_recall_results` | `10` | 格式化为上下文的最大召回条目数 |
|
||||
| `profile_frequency` | `50` | 在第一轮及每 N 轮包含 profile 事实 |
|
||||
| `capture_mode` | `all` | 默认跳过过短或无意义的轮次 |
|
||||
| `search_mode` | `hybrid` | 搜索模式：`hybrid`、`memories` 或 `documents` |
|
||||
| `api_timeout` | `5.0` | SDK 和导入请求的超时时间 |
|
||||
|
||||
**环境变量：** `SUPERMEMORY_API_KEY`（必填）、`SUPERMEMORY_CONTAINER_TAG`（覆盖配置）。
|
||||
|
||||
**主要特性：**
|
||||
- 自动上下文隔离——从捕获的轮次中剥离已召回的记忆，防止递归记忆污染
|
||||
- 在会话边界时将整个会话**一次性导入**
|
||||
- 会话结束时同时导入到对话端点（`/v4/conversations`），用于 Supermemory 的 profile 和图谱构建
|
||||
- 在第一轮及可配置间隔注入 profile 事实
|
||||
- **Profile 范围容器**——在 `container_tag` 中使用 `{identity}`（例如 `hermes-{identity}` → `hermes-coder`），按 Hermes profile 隔离记忆
|
||||
- **多容器模式**——启用 `enable_custom_container_tags` 并配置 `custom_containers` 列表，让 Agent 跨命名容器读写。自动操作（同步、预取）保持在主容器上。
|
||||
|
||||
<details>
|
||||
<summary>多容器示例</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"container_tag": "hermes",
|
||||
"enable_custom_container_tags": true,
|
||||
"custom_containers": ["project-alpha", "shared-knowledge"],
|
||||
"custom_container_instructions": "Use project-alpha for coding context."
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
**支持：** [Discord](https://supermemory.link/discord) · [support@supermemory.com](mailto:support@supermemory.com)
|
||||
|
||||
---
|
||||
|
||||
## 提供者对比
|
||||
|
||||
| 提供者 | 存储 | 费用 | 工具数 | 依赖 | 独特特性 |
|
||||
|----------|---------|------|-------|-------------|----------------|
|
||||
| **Honcho** | 云端 | 付费 | 5 | `honcho-ai` | 辩证用户建模 + 会话范围上下文 |
|
||||
| **OpenViking** | 自托管 | 免费 | 5 | `openviking` + 服务器 | 文件系统层级 + 分层加载 |
|
||||
| **Mem0** | 云端 | 付费 | 3 | `mem0ai` | 服务端 LLM 提取 |
|
||||
| **Hindsight** | 云端/本地 | 免费/付费 | 3 | `hindsight-client` | 知识图谱 + reflect 合成 |
|
||||
| **Holographic** | 本地 | 免费 | 2 | 无 | HRR 代数 + 信任评分 |
|
||||
| **RetainDB** | 云端 | $20/月 | 5 | `requests` | 增量压缩 |
|
||||
| **ByteRover** | 本地/云端 | 免费/付费 | 3 | `brv` CLI | 预压缩提取 |
|
||||
| **Supermemory** | 云端 | 付费 | 4 | `supermemory` | 上下文隔离 + 会话图谱导入 + 多容器 |
|
||||
|
||||
## Profile 隔离
|
||||
|
||||
每个提供者的数据按 [profile](/user-guide/profiles) 隔离：
|
||||
|
||||
- **本地存储提供者**（Holographic、ByteRover）使用 `$HERMES_HOME/` 路径，各 profile 路径不同
|
||||
- **配置文件提供者**（Honcho、Mem0、Hindsight、Supermemory）将配置存储在 `$HERMES_HOME/` 中，每个 profile 拥有独立凭证
|
||||
- **云端提供者**（RetainDB）自动派生 profile 范围的项目名称
|
||||
- **环境变量提供者**（OpenViking）通过每个 profile 的 `.env` 文件配置
|
||||
|
||||
## 构建记忆提供者
|
||||
|
||||
参见[开发者指南：Memory Provider 插件](/developer-guide/memory-provider-plugin)了解如何创建自己的提供者。
|
||||
+225
@@ -0,0 +1,225 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: "持久化记忆"
|
||||
description: "Hermes Agent 如何跨会话记忆——MEMORY.md、USER.md 与会话搜索"
|
||||
---
|
||||
|
||||
# 持久化记忆
|
||||
|
||||
Hermes Agent 拥有有界、经过整理的记忆，可跨会话持久保存。这使它能够记住你的偏好、项目、环境以及已学到的内容。
|
||||
|
||||
## 工作原理
|
||||
|
||||
两个文件构成 Agent 的记忆：
|
||||
|
||||
| 文件 | 用途 | 字符上限 |
|
||||
|------|------|----------|
|
||||
| **MEMORY.md** | Agent 的个人笔记——环境事实、约定、已学内容 | 2,200 字符（约 800 tokens） |
|
||||
| **USER.md** | 用户档案——你的偏好、沟通风格、期望 | 1,375 字符（约 500 tokens） |
|
||||
|
||||
两个文件均存储于 `~/.hermes/memories/`，在会话开始时以冻结快照的形式注入系统 prompt（提示词）。Agent 通过 `memory` 工具管理自身记忆——可添加、替换或删除条目。
|
||||
|
||||
:::info
|
||||
字符上限使记忆保持聚焦。当记忆已满时，Agent 会整合或替换条目以腾出空间存放新信息。
|
||||
:::
|
||||
|
||||
## 记忆在系统 Prompt 中的呈现方式
|
||||
|
||||
每次会话开始时，记忆条目从磁盘加载并以冻结块的形式渲染到系统 prompt 中：
|
||||
|
||||
```
|
||||
══════════════════════════════════════════════
|
||||
MEMORY (your personal notes) [67% — 1,474/2,200 chars]
|
||||
══════════════════════════════════════════════
|
||||
User's project is a Rust web service at ~/code/myapi using Axum + SQLx
|
||||
§
|
||||
This machine runs Ubuntu 22.04, has Docker and Podman installed
|
||||
§
|
||||
User prefers concise responses, dislikes verbose explanations
|
||||
```
|
||||
|
||||
格式包含：
|
||||
- 标头，显示存储类型（MEMORY 或 USER PROFILE）
|
||||
- 使用百分比和字符计数，让 Agent 了解容量
|
||||
- 以 `§`（节符）分隔的各条目
|
||||
- 条目可以是多行
|
||||
|
||||
**冻结快照模式：** 系统 prompt 注入在会话开始时捕获一次，会话中途不会改变。这是有意为之——目的是保留 LLM 的前缀缓存以提升性能。当 Agent 在会话期间添加或删除记忆条目时，更改会立即持久化到磁盘，但要到下一次会话开始时才会出现在系统 prompt 中。工具响应始终显示实时状态。
|
||||
|
||||
## Memory 工具操作
|
||||
|
||||
Agent 使用 `memory` 工具执行以下操作：
|
||||
|
||||
- **add** — 添加新的记忆条目
|
||||
- **replace** — 用更新内容替换现有条目（通过 `old_text` 进行子字符串匹配）
|
||||
- **remove** — 删除不再相关的条目（通过 `old_text` 进行子字符串匹配）
|
||||
|
||||
没有 `read` 操作——记忆内容在会话开始时自动注入系统 prompt。Agent 将其记忆作为对话上下文的一部分来查看。
|
||||
|
||||
### 子字符串匹配
|
||||
|
||||
`replace` 和 `remove` 操作使用简短的唯一子字符串匹配——不需要完整的条目文本。`old_text` 参数只需是能唯一标识某一条目的子字符串即可：
|
||||
|
||||
```python
|
||||
# If memory contains "User prefers dark mode in all editors"
|
||||
memory(action="replace", target="memory",
|
||||
old_text="dark mode",
|
||||
content="User prefers light mode in VS Code, dark mode in terminal")
|
||||
```
|
||||
|
||||
如果子字符串匹配到多个条目，则返回错误，要求提供更具体的匹配内容。
|
||||
|
||||
## 两个目标说明
|
||||
|
||||
### `memory` — Agent 的个人笔记
|
||||
|
||||
用于 Agent 需要记住的环境、工作流及经验教训相关信息：
|
||||
|
||||
- 环境事实（操作系统、工具、项目结构）
|
||||
- 项目约定和配置
|
||||
- 发现的工具怪癖与变通方法
|
||||
- 已完成任务的日记条目
|
||||
- 有效的技能和技术
|
||||
|
||||
### `user` — 用户档案
|
||||
|
||||
用于记录用户的身份、偏好和沟通风格：
|
||||
|
||||
- 姓名、角色、时区
|
||||
- 沟通偏好（简洁 vs 详细、格式偏好）
|
||||
- 反感的事项和需要避免的内容
|
||||
- 工作流习惯
|
||||
- 技术水平
|
||||
|
||||
## 什么该保存，什么该跳过
|
||||
|
||||
### 主动保存这些内容
|
||||
|
||||
Agent 会自动保存——无需你主动要求。当它学到以下内容时会保存：
|
||||
|
||||
- **用户偏好：** "我更喜欢 TypeScript 而非 JavaScript" → 保存到 `user`
|
||||
- **环境事实：** "此服务器运行 Debian 12，安装了 PostgreSQL 16" → 保存到 `memory`
|
||||
- **纠正信息：** "Docker 命令不要用 `sudo`，用户已在 docker 组中" → 保存到 `memory`
|
||||
- **约定：** "项目使用 tab 缩进、120 字符行宽、Google 风格 docstring" → 保存到 `memory`
|
||||
- **已完成的工作：** "2026-01-15 将数据库从 MySQL 迁移到 PostgreSQL" → 保存到 `memory`
|
||||
- **明确请求：** "记住我的 API 密钥每月轮换一次" → 保存到 `memory`
|
||||
|
||||
### 跳过这些内容
|
||||
|
||||
- **琐碎/显而易见的信息：** "用户询问了 Python"——太模糊，没有实用价值
|
||||
- **容易重新发现的事实：** "Python 3.12 支持 f-string 嵌套"——可以网络搜索
|
||||
- **原始数据转储：** 大型代码块、日志文件、数据表——对记忆来说太大
|
||||
- **会话特定的临时内容：** 临时文件路径、一次性调试上下文
|
||||
- **已在上下文文件中的信息：** SOUL.md 和 AGENTS.md 的内容
|
||||
|
||||
## 容量管理
|
||||
|
||||
记忆有严格的字符上限，以保持系统 prompt 的有界性：
|
||||
|
||||
| 存储 | 上限 | 典型条目数 |
|
||||
|------|------|-----------|
|
||||
| memory | 2,200 字符 | 8-15 条 |
|
||||
| user | 1,375 字符 | 5-10 条 |
|
||||
|
||||
### 记忆已满时的处理
|
||||
|
||||
当你尝试添加会超出上限的条目时，工具返回错误：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Memory at 2,100/2,200 chars. Adding this entry (250 chars) would exceed the limit. Replace or remove existing entries first.",
|
||||
"current_entries": ["..."],
|
||||
"usage": "2,100/2,200"
|
||||
}
|
||||
```
|
||||
|
||||
Agent 应当：
|
||||
1. 读取当前条目（显示在错误响应中）
|
||||
2. 识别可以删除或整合的条目
|
||||
3. 使用 `replace` 将相关条目合并为更简短的版本
|
||||
4. 然后 `add` 新条目
|
||||
|
||||
**最佳实践：** 当记忆使用率超过 80%（在系统 prompt 标头中可见）时，在添加新条目之前先整合现有条目。例如，将三个独立的"项目使用 X"条目合并为一个综合性的项目描述条目。
|
||||
|
||||
### 优质记忆条目的实际示例
|
||||
|
||||
**紧凑、信息密度高的条目效果最佳：**
|
||||
|
||||
```
|
||||
# Good: Packs multiple related facts
|
||||
User runs macOS 14 Sonoma, uses Homebrew, has Docker Desktop and Podman. Shell: zsh with oh-my-zsh. Editor: VS Code with Vim keybindings.
|
||||
|
||||
# Good: Specific, actionable convention
|
||||
Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI via GitHub Actions.
|
||||
|
||||
# Good: Lesson learned with context
|
||||
The staging server (10.0.1.50) needs SSH port 2222, not 22. Key is at ~/.ssh/staging_ed25519.
|
||||
|
||||
# Bad: Too vague
|
||||
User has a project.
|
||||
|
||||
# Bad: Too verbose
|
||||
On January 5th, 2026, the user asked me to look at their project which is
|
||||
located at ~/code/api. I discovered it uses Go version 1.22 and...
|
||||
```
|
||||
|
||||
## 重复防护
|
||||
|
||||
记忆系统会自动拒绝完全重复的条目。如果你尝试添加已存在的内容，系统返回成功并附带"未添加重复项"的消息。
|
||||
|
||||
## 安全扫描
|
||||
|
||||
记忆条目在被接受之前会扫描注入和数据外泄模式，因为它们会被注入系统 prompt。匹配威胁模式（prompt 注入、凭据外泄、SSH 后门）或包含不可见 Unicode 字符的内容将被拦截。
|
||||
|
||||
## 会话搜索
|
||||
|
||||
除 MEMORY.md 和 USER.md 之外，Agent 还可以使用 `session_search` 工具搜索过去的对话：
|
||||
|
||||
- 所有 CLI 和消息会话均存储在 SQLite（`~/.hermes/state.db`）中，支持 FTS5 全文搜索
|
||||
- 搜索查询返回数据库中的实际消息——无 LLM 摘要，无截断
|
||||
- Agent 可以找到数周前讨论过的内容，即使它们不在活跃记忆中
|
||||
- Agent 还可以在找到的任意会话中向前或向后滚动
|
||||
|
||||
```bash
|
||||
hermes sessions list # 浏览过去的会话
|
||||
```
|
||||
|
||||
有关三种调用形式（发现 / 滚动 / 浏览）和响应格式，请参阅[会话搜索工具](/user-guide/sessions#session-search-tool)。
|
||||
|
||||
### session_search 与 memory 的对比
|
||||
|
||||
| 特性 | 持久化记忆 | 会话搜索 |
|
||||
|------|-----------|---------|
|
||||
| **容量** | 约 1,300 tokens 总计 | 无限制（所有会话） |
|
||||
| **速度** | 即时（在系统 prompt 中） | 约 20ms FTS5 查询，约 1ms 滚动 |
|
||||
| **成本** | 每次 prompt 均有 token 开销 | 免费——无 LLM 调用 |
|
||||
| **使用场景** | 始终可用的关键事实 | 查找特定的过去对话 |
|
||||
| **管理方式** | 由 Agent 手动整理 | 自动——所有会话均存储 |
|
||||
| **Token 开销** | 每次会话固定（约 1,300 tokens） | 按需（仅在搜索时产生） |
|
||||
|
||||
**记忆**用于应始终在上下文中的关键事实。**会话搜索**用于"我们上周讨论过 X 吗？"这类需要 Agent 从过去对话中回忆具体内容的查询。
|
||||
|
||||
## 配置
|
||||
|
||||
```yaml
|
||||
# In ~/.hermes/config.yaml
|
||||
memory:
|
||||
memory_enabled: true
|
||||
user_profile_enabled: true
|
||||
memory_char_limit: 2200 # ~800 tokens
|
||||
user_char_limit: 1375 # ~500 tokens
|
||||
```
|
||||
|
||||
## 外部记忆提供商
|
||||
|
||||
对于超出 MEMORY.md 和 USER.md 范围的更深层持久化记忆，Hermes 内置了 8 个外部记忆提供商插件——包括 Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover 和 Supermemory。
|
||||
|
||||
外部提供商与内置记忆**并行**运行（而非替代），并增加了知识图谱、语义搜索、自动事实提取和跨会话用户建模等能力。
|
||||
|
||||
```bash
|
||||
hermes memory setup # 选择并配置提供商
|
||||
hermes memory status # 查看当前激活状态
|
||||
```
|
||||
|
||||
有关每个提供商的完整详情、设置说明和对比，请参阅[记忆提供商](./memory-providers.md)指南。
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: "功能概览"
|
||||
sidebar_label: "概览"
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# 功能概览
|
||||
|
||||
Hermes Agent 包含一套丰富的能力，远超基础聊天范畴。从持久化记忆、文件感知上下文，到浏览器自动化和语音对话，这些功能协同工作，使 Hermes 成为一个强大的自主助手。
|
||||
|
||||
## 核心功能
|
||||
|
||||
- **[工具与工具集](tools.md)** — 工具是扩展 Agent 能力的函数。它们被组织成逻辑工具集，可按平台启用或禁用，涵盖网络搜索、终端执行、文件编辑、记忆、委派等功能。
|
||||
- **[技能系统](skills.md)** — Agent 可按需加载的知识文档。技能遵循渐进式披露模式以最小化 token 用量，并兼容 [agentskills.io](https://agentskills.io/specification) 开放标准。
|
||||
- **[持久化记忆](memory.md)** — 跨会话持久保存的有界、精选记忆。Hermes 通过 `MEMORY.md` 和 `USER.md` 记住你的偏好、项目、环境及已学习的内容。
|
||||
- **[上下文文件](context-files.md)** — Hermes 自动发现并加载项目上下文文件（`.hermes.md`、`AGENTS.md`、`CLAUDE.md`、`SOUL.md`、`.cursorrules`），这些文件决定了它在你项目中的行为方式。
|
||||
- **[上下文引用](context-references.md)** — 输入 `@` 后跟引用内容，可将文件、文件夹、git diff 和 URL 直接注入消息中。Hermes 会内联展开引用并自动附加相应内容。
|
||||
- **[检查点](../checkpoints-and-rollback.md)** — Hermes 在进行文件更改前自动为工作目录创建快照，提供安全网，可通过 `/rollback` 回滚至出错前的状态。
|
||||
|
||||
## 自动化
|
||||
|
||||
- **[定时任务（Cron）](cron.md)** — 使用自然语言或 cron 表达式调度自动运行的任务。任务可附加技能、将结果推送至任意平台，并支持暂停/恢复/编辑操作。
|
||||
- **[子 Agent 委派](delegation.md)** — `delegate_task` 工具可生成具有独立上下文、受限工具集和独立终端会话的子 Agent 实例。默认并发运行 3 个子 Agent（可配置），支持并行工作流。
|
||||
- **[代码执行](code-execution.md)** — `execute_code` 工具允许 Agent 编写以编程方式调用 Hermes 工具的 Python 脚本，通过沙箱 RPC 执行将多步骤工作流压缩为单次 LLM 调用。
|
||||
- **[事件 Hook](hooks.md)** — 在关键生命周期节点运行自定义代码。Gateway hook 处理日志、告警和 webhook；plugin hook 处理工具拦截、指标和护栏。
|
||||
- **[批处理](batch-processing.md)** — 跨数百或数千个 prompt（提示词）并行运行 Hermes Agent，生成 ShareGPT 格式的结构化轨迹数据，用于训练数据生成或评估。
|
||||
|
||||
## 媒体与网络
|
||||
|
||||
- **[语音模式](voice-mode.md)** — 跨 CLI 和消息平台的完整语音交互。使用麦克风与 Agent 对话，收听语音回复，并在 Discord 语音频道中进行实时语音对话。
|
||||
- **[浏览器自动化](browser.md)** — 支持多种后端的完整浏览器自动化：Browserbase 云端、Browser Use 云端、通过 CDP 连接的本地 Chrome/Brave/Chromium/Edge，或本地 Chromium。可导航网站、填写表单并提取信息。
|
||||
- **[视觉与图片粘贴](vision.md)** — 多模态视觉支持。将剪贴板中的图片粘贴到 CLI，并使用任意支持视觉的模型请求 Agent 分析、描述或处理图片。
|
||||
- **[图像生成](image-generation.md)** — 使用 FAL.ai 从文本 prompt 生成图像。支持九种模型（FLUX 2 Klein/Pro、GPT-Image 1.5/2、Nano Banana Pro、Ideogram V3、Recraft V4 Pro、Qwen、Z-Image Turbo）；可通过 `hermes tools` 选择。
|
||||
- **[语音与 TTS](tts.md)** — 跨所有消息平台的文字转语音输出和语音消息转录，提供十种原生提供商选项：Edge TTS（免费）、ElevenLabs、OpenAI TTS、MiniMax、Mistral Voxtral、Google Gemini、xAI、NeuTTS、KittenTTS 和 Piper——以及支持任意本地 TTS CLI 的自定义命令提供商。
|
||||
|
||||
## 集成
|
||||
|
||||
- **[MCP 集成](mcp.md)** — 通过 stdio 或 HTTP 传输连接任意 MCP 服务器。无需编写原生 Hermes 工具，即可访问来自 GitHub、数据库、文件系统和内部 API 的外部工具。支持按服务器过滤工具及 sampling（采样）。
|
||||
- **[提供商路由](provider-routing.md)** — 对 AI 提供商处理请求的方式进行精细控制。通过排序、白名单、黑名单和优先级排序，在成本、速度或质量之间优化。
|
||||
- **[备用提供商](fallback-providers.md)** — 当主模型遇到错误时自动故障转移至备用 LLM 提供商，包括针对视觉和压缩等辅助任务的独立备用机制。
|
||||
- **[凭证池](credential-pools.md)** — 在同一提供商的多个密钥之间分发 API 调用。在触发速率限制或发生故障时自动轮换。
|
||||
- **[Prompt 缓存](../configuration#prompt-caching)** — 针对原生 Anthropic、OpenRouter 和 Nous Portal 上的 Claude，内置跨会话 1 小时前缀缓存。始终开启，无需配置。
|
||||
- **[记忆提供商](memory-providers.md)** — 接入外部记忆后端（Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover、Supermemory），实现跨会话用户建模和超越内置记忆系统的个性化。
|
||||
- **[API 服务器](api-server.md)** — 将 Hermes 作为兼容 OpenAI 的 HTTP 端点暴露。连接任何支持 OpenAI 格式的前端——Open WebUI、LobeChat、LibreChat 等。
|
||||
- **[IDE 集成（ACP）](acp.md)** — 在兼容 ACP 的编辑器（如 VS Code、Zed 和 JetBrains）中使用 Hermes。聊天、工具活动、文件 diff 和终端命令均在编辑器内渲染。
|
||||
- **[强化学习训练](rl-training.md)** — 从 Agent 会话中生成轨迹数据，用于强化学习和模型微调。
|
||||
|
||||
## 自定义
|
||||
|
||||
- **[个性与 SOUL.md](personality.md)** — 完全可自定义的 Agent 个性。`SOUL.md` 是主要身份文件——系统提示词中的第一项——你可以在每个会话中切换内置或自定义的 `/personality` 预设。
|
||||
- **[皮肤与主题](skins.md)** — 自定义 CLI 的视觉呈现：横幅颜色、加载动画图标和动词、响应框标签、品牌文字，以及工具活动前缀。
|
||||
- **[插件](plugins.md)** — 无需修改核心代码即可添加自定义工具、hook 和集成。三种插件类型：通用插件（工具/hook）、记忆提供商（跨会话知识）和上下文引擎（替代上下文管理）。通过统一的 `hermes plugins` 交互式界面管理。
|
||||
+271
@@ -0,0 +1,271 @@
|
||||
---
|
||||
sidebar_position: 9
|
||||
title: "个性与 SOUL.md"
|
||||
description: "通过全局 SOUL.md、内置个性预设和自定义角色定义来自定义 Hermes Agent 的个性"
|
||||
---
|
||||
|
||||
# 个性与 SOUL.md
|
||||
|
||||
Hermes Agent 的个性完全可自定义。`SOUL.md` 是**主要身份标识**——它是系统提示词（prompt）中的第一项内容，定义了 Agent 是谁。
|
||||
|
||||
- `SOUL.md` — 存放在 `HERMES_HOME` 中的持久角色文件，作为 Agent 的身份标识（系统提示词中的第 1 个槽位）
|
||||
- 内置或自定义的 `/personality` 预设 — 会话级系统提示词覆盖层
|
||||
|
||||
如果你想改变 Hermes 的身份，或将其替换为完全不同的 Agent 角色，请编辑 `SOUL.md`。
|
||||
|
||||
## SOUL.md 的工作方式
|
||||
|
||||
Hermes 现在会自动在以下位置生成默认的 `SOUL.md`：
|
||||
|
||||
```text
|
||||
~/.hermes/SOUL.md
|
||||
```
|
||||
|
||||
更准确地说，它使用当前实例的 `HERMES_HOME`，因此如果你以自定义主目录运行 Hermes，它将使用：
|
||||
|
||||
```text
|
||||
$HERMES_HOME/SOUL.md
|
||||
```
|
||||
|
||||
### 重要行为
|
||||
|
||||
- **SOUL.md 是 Agent 的主要身份标识。** 它占据系统提示词的第 1 个槽位，替代硬编码的默认身份。
|
||||
- 如果 `SOUL.md` 尚不存在，Hermes 会自动创建一个初始文件
|
||||
- 已有的用户 `SOUL.md` 文件不会被覆盖
|
||||
- Hermes 仅从 `HERMES_HOME` 加载 `SOUL.md`
|
||||
- Hermes 不会在当前工作目录中查找 `SOUL.md`
|
||||
- 如果 `SOUL.md` 存在但为空，或无法加载，Hermes 将回退到内置的默认身份
|
||||
- 如果 `SOUL.md` 有内容，该内容在经过安全扫描和截断处理后将原样注入
|
||||
- SOUL.md **不会**在上下文文件部分重复出现——它仅作为身份标识出现一次
|
||||
|
||||
这使 `SOUL.md` 成为真正的每用户或每实例身份标识，而不仅仅是一个附加层。
|
||||
|
||||
## 此设计的原因
|
||||
|
||||
这样可以保持个性的可预测性。
|
||||
|
||||
如果 Hermes 从你启动它的任意目录加载 `SOUL.md`，你的个性可能会在不同项目之间意外改变。通过仅从 `HERMES_HOME` 加载，个性归属于 Hermes 实例本身。
|
||||
|
||||
这也让用户更容易理解：
|
||||
- "编辑 `~/.hermes/SOUL.md` 来更改 Hermes 的默认个性。"
|
||||
|
||||
## 编辑位置
|
||||
|
||||
对于大多数用户：
|
||||
|
||||
```bash
|
||||
~/.hermes/SOUL.md
|
||||
```
|
||||
|
||||
如果你使用自定义主目录：
|
||||
|
||||
```bash
|
||||
$HERMES_HOME/SOUL.md
|
||||
```
|
||||
|
||||
## SOUL.md 应该写什么？
|
||||
|
||||
用于持久的语气和个性指导，例如：
|
||||
- 语气
|
||||
- 沟通风格
|
||||
- 直接程度
|
||||
- 默认交互风格
|
||||
- 风格上应避免的内容
|
||||
- Hermes 应如何处理不确定性、分歧或模糊情况
|
||||
|
||||
不适合写入的内容：
|
||||
- 一次性项目说明
|
||||
- 文件路径
|
||||
- 代码库规范
|
||||
- 临时工作流细节
|
||||
|
||||
这些内容属于 `AGENTS.md`，而不是 `SOUL.md`。
|
||||
|
||||
## 优质 SOUL.md 内容
|
||||
|
||||
一个好的 SOUL 文件应该：
|
||||
- 在不同上下文中保持稳定
|
||||
- 足够宽泛，适用于多种对话场景
|
||||
- 足够具体，能实质性地塑造语气
|
||||
- 专注于沟通和身份，而非特定任务的指令
|
||||
|
||||
### 示例
|
||||
|
||||
```markdown
|
||||
# Personality
|
||||
|
||||
You are a pragmatic senior engineer with strong taste.
|
||||
You optimize for truth, clarity, and usefulness over politeness theater.
|
||||
|
||||
## Style
|
||||
- Be direct without being cold
|
||||
- Prefer substance over filler
|
||||
- Push back when something is a bad idea
|
||||
- Admit uncertainty plainly
|
||||
- Keep explanations compact unless depth is useful
|
||||
|
||||
## What to avoid
|
||||
- Sycophancy
|
||||
- Hype language
|
||||
- Repeating the user's framing if it's wrong
|
||||
- Overexplaining obvious things
|
||||
|
||||
## Technical posture
|
||||
- Prefer simple systems over clever systems
|
||||
- Care about operational reality, not idealized architecture
|
||||
- Treat edge cases as part of the design, not cleanup
|
||||
```
|
||||
|
||||
## Hermes 注入提示词的内容
|
||||
|
||||
`SOUL.md` 的内容直接进入系统提示词的第 1 个槽位——即 Agent 身份位置。不会在其周围添加任何包装语言。
|
||||
|
||||
内容会经过以下处理：
|
||||
- 提示词注入扫描
|
||||
- 内容过大时进行截断
|
||||
|
||||
如果文件为空、仅含空白字符或无法读取，Hermes 将回退到内置默认身份（"You are Hermes Agent, an intelligent AI assistant created by Nous Research..."）。当 `skip_context_files` 被设置时（例如在子 Agent/委托上下文中），同样适用此回退。
|
||||
|
||||
## 安全扫描
|
||||
|
||||
`SOUL.md` 与其他携带上下文的文件一样，在被包含前会进行提示词注入模式扫描。
|
||||
|
||||
这意味着你仍应将其专注于角色/语气，而不是试图混入奇怪的元指令。
|
||||
|
||||
## SOUL.md 与 AGENTS.md
|
||||
|
||||
这是最重要的区别。
|
||||
|
||||
### SOUL.md
|
||||
用于：
|
||||
- 身份
|
||||
- 语气
|
||||
- 风格
|
||||
- 沟通默认值
|
||||
- 个性层面的行为
|
||||
|
||||
### AGENTS.md
|
||||
用于：
|
||||
- 项目架构
|
||||
- 编码规范
|
||||
- 工具偏好
|
||||
- 代码库特定工作流
|
||||
- 命令、端口、路径、部署说明
|
||||
|
||||
一个实用的判断规则：
|
||||
- 如果它应该随你到处适用，属于 `SOUL.md`
|
||||
- 如果它属于某个项目，属于 `AGENTS.md`
|
||||
|
||||
## SOUL.md 与 `/personality`
|
||||
|
||||
`SOUL.md` 是你的持久默认个性。
|
||||
|
||||
`/personality` 是会话级覆盖层，用于更改或补充当前系统提示词。
|
||||
|
||||
因此：
|
||||
- `SOUL.md` = 基础语气
|
||||
- `/personality` = 临时模式切换
|
||||
|
||||
示例：
|
||||
- 保持务实的默认 SOUL，然后在辅导对话中使用 `/personality teacher`
|
||||
- 保持简洁的 SOUL，然后在头脑风暴时使用 `/personality creative`
|
||||
|
||||
## 内置个性
|
||||
|
||||
Hermes 内置了多种个性，可通过 `/personality` 切换。
|
||||
|
||||
| 名称 | 描述 |
|
||||
|------|-------------|
|
||||
| **helpful** | 友好的通用助手 |
|
||||
| **concise** | 简短、直击要点的回复 |
|
||||
| **technical** | 详尽、准确的技术专家 |
|
||||
| **creative** | 创新、突破常规的思维 |
|
||||
| **teacher** | 耐心的教育者，配有清晰示例 |
|
||||
| **kawaii** | 可爱表达、闪光效果与热情 ★ |
|
||||
| **catgirl** | 带有猫咪表达方式的 Neko-chan，nya~ |
|
||||
| **pirate** | 船长 Hermes，精通技术的海盗 |
|
||||
| **shakespeare** | 充满戏剧张力的吟游诗人风格 |
|
||||
| **surfer** | 超级冷静的冲浪者氛围 |
|
||||
| **noir** | 硬派侦探叙事风格 |
|
||||
| **uwu** | 极致可爱的 uwu 语气 |
|
||||
| **philosopher** | 对每个问题深度沉思 |
|
||||
| **hype** | 最大能量与热情！！！ |
|
||||
|
||||
## 使用命令切换个性
|
||||
|
||||
### CLI
|
||||
|
||||
```text
|
||||
/personality
|
||||
/personality concise
|
||||
/personality technical
|
||||
```
|
||||
|
||||
### 消息平台
|
||||
|
||||
```text
|
||||
/personality teacher
|
||||
```
|
||||
|
||||
这些是便捷的覆盖层，但你的全局 `SOUL.md` 仍然赋予 Hermes 持久的默认个性，除非覆盖层对其进行了实质性更改。
|
||||
|
||||
## 在配置中定义自定义个性
|
||||
|
||||
你也可以在 `~/.hermes/config.yaml` 的 `agent.personalities` 下定义命名的自定义个性。
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
personalities:
|
||||
codereviewer: >
|
||||
You are a meticulous code reviewer. Identify bugs, security issues,
|
||||
performance concerns, and unclear design choices. Be precise and constructive.
|
||||
```
|
||||
|
||||
然后通过以下方式切换：
|
||||
|
||||
```text
|
||||
/personality codereviewer
|
||||
```
|
||||
|
||||
## 推荐工作流
|
||||
|
||||
一个强健的默认配置：
|
||||
|
||||
1. 在 `~/.hermes/SOUL.md` 中维护一个经过深思熟虑的全局 `SOUL.md`
|
||||
2. 将项目说明放在 `AGENTS.md` 中
|
||||
3. 仅在需要临时模式切换时使用 `/personality`
|
||||
|
||||
这样你将获得：
|
||||
- 稳定的语气
|
||||
- 项目特定行为归属于正确位置
|
||||
- 需要时的临时控制
|
||||
|
||||
## 个性如何与完整提示词交互
|
||||
|
||||
从高层次来看，提示词栈包含：
|
||||
1. **SOUL.md**（Agent 身份——如果 SOUL.md 不可用则使用内置回退）
|
||||
2. 工具感知行为指导
|
||||
3. 记忆/用户上下文
|
||||
4. 技能指导
|
||||
5. 上下文文件（`AGENTS.md`、`.cursorrules`）
|
||||
6. 时间戳
|
||||
7. 平台特定格式提示
|
||||
8. 可选的系统提示词覆盖层，如 `/personality`
|
||||
|
||||
`SOUL.md` 是基础——其他所有内容都建立在它之上。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [上下文文件](/user-guide/features/context-files)
|
||||
- [配置](/user-guide/configuration)
|
||||
- [技巧与最佳实践](/guides/tips)
|
||||
- [SOUL.md 指南](/guides/use-soul-with-hermes)
|
||||
|
||||
## CLI 外观与对话个性
|
||||
|
||||
对话个性与 CLI 外观是相互独立的：
|
||||
|
||||
- `SOUL.md`、`agent.system_prompt` 和 `/personality` 影响 Hermes 的说话方式
|
||||
- `display.skin` 和 `/skin` 影响 Hermes 在终端中的显示外观
|
||||
|
||||
关于终端外观，请参阅 [皮肤与主题](./skins.md)。
|
||||
+350
@@ -0,0 +1,350 @@
|
||||
---
|
||||
sidebar_position: 11
|
||||
sidebar_label: "Plugins"
|
||||
title: "Plugins"
|
||||
description: "通过插件系统为 Hermes 添加自定义工具、hook 和集成"
|
||||
---
|
||||
|
||||
# Plugins
|
||||
|
||||
Hermes 提供了一套插件系统，可在不修改核心代码的情况下添加自定义工具、hook（钩子）和集成。
|
||||
|
||||
如果你想为自己、团队或某个项目创建自定义工具，这通常是正确的路径。开发者指南中的
|
||||
[Adding Tools](/developer-guide/adding-tools) 页面针对的是存放在 `tools/` 和 `toolsets.py` 中的 Hermes 内置核心工具。
|
||||
|
||||
**→ [构建 Hermes Plugin](/guides/build-a-hermes-plugin)** — 包含完整可运行示例的分步指南。
|
||||
|
||||
## 快速概览
|
||||
|
||||
在 `~/.hermes/plugins/` 下放入一个目录，包含 `plugin.yaml` 和 Python 代码：
|
||||
|
||||
```
|
||||
~/.hermes/plugins/my-plugin/
|
||||
├── plugin.yaml # manifest（清单）
|
||||
├── __init__.py # register() — 将 schema 与处理器绑定
|
||||
├── schemas.py # tool schema（LLM 所见的内容）
|
||||
└── tools.py # tool 处理器（调用时实际执行的代码）
|
||||
```
|
||||
|
||||
启动 Hermes — 你的工具会与内置工具一同出现，模型可立即调用它们。
|
||||
|
||||
### 最小可运行示例
|
||||
|
||||
以下是一个完整插件，添加了一个 `hello_world` 工具，并通过 hook 记录每次工具调用。
|
||||
|
||||
**`~/.hermes/plugins/hello-world/plugin.yaml`**
|
||||
|
||||
```yaml
|
||||
name: hello-world
|
||||
version: "1.0"
|
||||
description: A minimal example plugin
|
||||
```
|
||||
|
||||
**`~/.hermes/plugins/hello-world/__init__.py`**
|
||||
|
||||
```python
|
||||
"""Minimal Hermes plugin — registers a tool and a hook."""
|
||||
|
||||
import json
|
||||
|
||||
|
||||
def register(ctx):
|
||||
# --- Tool: hello_world ---
|
||||
schema = {
|
||||
"name": "hello_world",
|
||||
"description": "Returns a friendly greeting for the given name.",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Name to greet",
|
||||
}
|
||||
},
|
||||
"required": ["name"],
|
||||
},
|
||||
}
|
||||
|
||||
def handle_hello(params, **kwargs):
|
||||
del kwargs
|
||||
name = params.get("name", "World")
|
||||
return json.dumps({"success": True, "greeting": f"Hello, {name}!"})
|
||||
|
||||
ctx.register_tool(
|
||||
name="hello_world",
|
||||
toolset="hello_world",
|
||||
schema=schema,
|
||||
handler=handle_hello,
|
||||
description="Return a friendly greeting for the given name.",
|
||||
)
|
||||
|
||||
# --- Hook: log every tool call ---
|
||||
def on_tool_call(tool_name, params, result):
|
||||
print(f"[hello-world] tool called: {tool_name}")
|
||||
|
||||
ctx.register_hook("post_tool_call", on_tool_call)
|
||||
```
|
||||
|
||||
将两个文件放入 `~/.hermes/plugins/hello-world/`，重启 Hermes，模型即可立即调用 `hello_world`。每次工具调用后，hook 会打印一行日志。
|
||||
|
||||
`./.hermes/plugins/` 下的项目本地插件默认禁用。仅对可信仓库启用，方法是在启动 Hermes 前设置 `HERMES_ENABLE_PROJECT_PLUGINS=true`。
|
||||
|
||||
## 插件能做什么
|
||||
|
||||
以下所有 `ctx.*` API 均可在插件的 `register(ctx)` 函数中使用。
|
||||
|
||||
| 能力 | 方式 |
|
||||
|-----------|-----|
|
||||
| 添加工具 | `ctx.register_tool(name=..., toolset=..., schema=..., handler=...)` |
|
||||
| 添加 hook | `ctx.register_hook("post_tool_call", callback)` |
|
||||
| 添加斜杠命令 | `ctx.register_command(name, handler, description)` — 在 CLI 和 gateway 会话中添加 `/name` |
|
||||
| 从命令中调度工具 | `ctx.dispatch_tool(name, args)` — 调用已注册的工具，自动注入父 agent 上下文 |
|
||||
| 添加 CLI 命令 | `ctx.register_cli_command(name, help, setup_fn, handler_fn)` — 添加 `hermes <plugin> <subcommand>` |
|
||||
| 注入消息 | `ctx.inject_message(content, role="user")` — 参见 [注入消息](#injecting-messages) |
|
||||
| 附带数据文件 | `Path(__file__).parent / "data" / "file.yaml"` |
|
||||
| 打包 skill | `ctx.register_skill(name, path)` — 命名空间为 `plugin:skill`，通过 `skill_view("plugin:skill")` 加载 |
|
||||
| 按环境变量控制 | 在 plugin.yaml 中设置 `requires_env: [API_KEY]` — 在 `hermes plugins install` 时提示输入 |
|
||||
| 通过 pip 分发 | `[project.entry-points."hermes_agent.plugins"]` |
|
||||
| 注册 gateway 平台（Discord、Telegram、IRC 等） | `ctx.register_platform(name, label, adapter_factory, check_fn, ...)` — 参见 [Adding Platform Adapters](/developer-guide/adding-platform-adapters) |
|
||||
| 注册图像生成后端 | `ctx.register_image_gen_provider(provider)` — 参见 [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) |
|
||||
| 注册视频生成后端 | `ctx.register_video_gen_provider(provider)` — 参见 [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin) |
|
||||
| 注册上下文压缩引擎 | `ctx.register_context_engine(engine)` — 参见 [Context Engine Plugins](/developer-guide/context-engine-plugin) |
|
||||
| 注册 memory 后端 | 在 `plugins/memory/<name>/__init__.py` 中继承 `MemoryProvider` — 参见 [Memory Provider Plugins](/developer-guide/memory-provider-plugin)（使用独立发现系统） |
|
||||
| 调用宿主 LLM | `ctx.llm.complete(...)` / `ctx.llm.complete_structured(...)` — 借用用户当前激活的模型和认证，进行一次性补全，支持可选 JSON schema 验证。参见 [Plugin LLM Access](/developer-guide/plugin-llm-access) |
|
||||
| 注册推理后端（LLM provider） | 在 `plugins/model-providers/<name>/__init__.py` 中调用 `register_provider(ProviderProfile(...))` — 参见 [Model Provider Plugins](/developer-guide/model-provider-plugin)（使用独立发现系统） |
|
||||
|
||||
## 插件发现
|
||||
|
||||
| 来源 | 路径 | 使用场景 |
|
||||
|--------|------|----------|
|
||||
| 内置 | `<repo>/plugins/` | 随 Hermes 附带 — 参见 [Built-in Plugins](/user-guide/features/built-in-plugins) |
|
||||
| 用户 | `~/.hermes/plugins/` | 个人插件 |
|
||||
| 项目 | `.hermes/plugins/` | 项目专属插件（需要 `HERMES_ENABLE_PROJECT_PLUGINS=true`） |
|
||||
| pip | `hermes_agent.plugins` entry_points | 分发包 |
|
||||
| Nix | `services.hermes-agent.extraPlugins` / `extraPythonPackages` | NixOS 声明式安装 — 参见 [Nix Setup](/getting-started/nix-setup#plugins) |
|
||||
|
||||
名称冲突时，后面的来源会覆盖前面的，因此与内置插件同名的用户插件会替换它。
|
||||
|
||||
### 插件子分类
|
||||
|
||||
在每个来源内，Hermes 还识别将插件路由到专用发现系统的子分类目录：
|
||||
|
||||
| 子目录 | 内容 | 发现系统 |
|
||||
|---|---|---|
|
||||
| `plugins/`（根目录） | 通用插件 — 工具、hook、斜杠命令、CLI 命令、打包 skill | `PluginManager`（kind: `standalone` 或 `backend`） |
|
||||
| `plugins/platforms/<name>/` | Gateway 频道适配器（`ctx.register_platform()`） | `PluginManager`（kind: `platform`，深一层） |
|
||||
| `plugins/image_gen/<name>/` | 图像生成后端（`ctx.register_image_gen_provider()`） | `PluginManager`（kind: `backend`，深一层） |
|
||||
| `plugins/memory/<name>/` | Memory provider（继承 `MemoryProvider`） | **独立加载器**，位于 `plugins/memory/__init__.py`（kind: `exclusive` — 同时只有一个激活） |
|
||||
| `plugins/context_engine/<name>/` | 上下文压缩引擎（`ctx.register_context_engine()`） | **独立加载器**，位于 `plugins/context_engine/__init__.py`（同时只有一个激活） |
|
||||
| `plugins/model-providers/<name>/` | LLM provider profile（`register_provider(ProviderProfile(...))`） | **独立加载器**，位于 `providers/__init__.py`（首次调用 `get_provider_profile()` 时懒加载扫描） |
|
||||
|
||||
`~/.hermes/plugins/model-providers/<name>/` 和 `~/.hermes/plugins/memory/<name>/` 下的用户插件会覆盖同名内置插件 — `register_provider()` / `register_memory_provider()` 中后写者胜出。放入一个目录即可替换内置实现，无需修改仓库。
|
||||
|
||||
子分类插件在 `hermes plugins list` 和交互式 `hermes plugins` UI 中以**路径派生的 key** 显示 — 例如 `observability/langfuse`、`image_gen/openai`、`platforms/teams`。该 key（而非 manifest 中的 `name:`）是传给 `hermes plugins enable …` / `disable …` 的值，也是在 `config.yaml` 的 `plugins.enabled` 下填写的字符串。
|
||||
|
||||
## 插件默认关闭（少数例外）
|
||||
|
||||
**通用插件和用户安装的后端默认禁用** — 发现系统会找到它们（因此它们会出现在 `hermes plugins` 和 `/plugins` 中），但在你将插件名称添加到 `~/.hermes/config.yaml` 的 `plugins.enabled` 之前，任何带有 hook 或工具的内容都不会加载。这可防止第三方代码在未经明确同意的情况下运行。
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
enabled:
|
||||
- my-tool-plugin
|
||||
- disk-cleanup
|
||||
disabled: # 可选的拒绝列表 — 若名称同时出现在两个列表中，此列表始终优先
|
||||
- noisy-plugin
|
||||
```
|
||||
|
||||
切换状态的三种方式：
|
||||
|
||||
```bash
|
||||
hermes plugins # 交互式切换（空格勾选/取消勾选）
|
||||
hermes plugins enable <name> # 添加到允许列表
|
||||
hermes plugins disable <name> # 从允许列表移除并添加到禁用列表
|
||||
```
|
||||
|
||||
执行 `hermes plugins install owner/repo` 后，会询问 `Enable 'name' now? [y/N]` — 默认为否。脚本化安装时可用 `--enable` 或 `--no-enable` 跳过提示。
|
||||
|
||||
### 允许列表不控制的内容
|
||||
|
||||
某些类别的插件绕过 `plugins.enabled` — 它们是 Hermes 内置功能的一部分，若默认关闭会破坏基本功能：
|
||||
|
||||
| 插件类型 | 激活方式 |
|
||||
|---|---|
|
||||
| **内置平台插件**（IRC、Teams 等，位于 `plugins/platforms/`） | 自动加载，使所有内置 gateway 频道可用。实际频道通过 `config.yaml` 中的 `gateway.platforms.<name>.enabled` 开启。 |
|
||||
| **内置后端**（`plugins/image_gen/` 等下的图像生成 provider） | 自动加载，使默认后端"开箱即用"。通过 `config.yaml` 中的 `<category>.provider` 选择（例如 `image_gen.provider: openai`）。 |
|
||||
| **Memory provider**（`plugins/memory/`） | 全部发现；同时只有一个激活，由 `config.yaml` 中的 `memory.provider` 选择。 |
|
||||
| **Context engine**（`plugins/context_engine/`） | 全部发现；同时只有一个激活，由 `config.yaml` 中的 `context.engine` 选择。 |
|
||||
| **Model provider**（`plugins/model-providers/`） | `plugins/model-providers/` 下的所有内置 provider 在首次调用 `get_provider_profile()` 时发现并注册。用户通过 `--provider` 或 `config.yaml` 一次选择一个。 |
|
||||
| **pip 安装的 `backend` 插件** | 通过 `plugins.enabled` 选择加入（与通用插件相同）。 |
|
||||
| **用户安装的平台**（位于 `~/.hermes/plugins/platforms/`） | 通过 `plugins.enabled` 选择加入 — 第三方 gateway 适配器需要明确同意。 |
|
||||
|
||||
简而言之：**内置的"始终可用"基础设施自动加载；第三方通用插件需选择加入。** `plugins.enabled` 允许列表专门用于控制用户放入 `~/.hermes/plugins/` 的任意代码。
|
||||
|
||||
### 现有用户的迁移
|
||||
|
||||
当你升级到支持选择加入插件的 Hermes 版本（config schema v21+）时，已安装在 `~/.hermes/plugins/` 下且不在 `plugins.disabled` 中的用户插件会**自动纳入** `plugins.enabled`。你的现有配置继续正常工作。内置独立插件**不会**自动纳入 — 即使是现有用户也需要明确选择加入。（内置平台/后端插件从未需要纳入，因为它们从未被控制。）
|
||||
|
||||
## 可用 hook
|
||||
|
||||
插件可为以下生命周期事件注册回调。完整详情、回调签名和示例请参见 **[Event Hooks 页面](/user-guide/features/hooks#plugin-hooks)**。
|
||||
|
||||
| Hook | 触发时机 |
|
||||
|------|-----------|
|
||||
| [`pre_tool_call`](/user-guide/features/hooks#pre_tool_call) | 任意工具执行前 |
|
||||
| [`post_tool_call`](/user-guide/features/hooks#post_tool_call) | 任意工具返回后 |
|
||||
| [`pre_llm_call`](/user-guide/features/hooks#pre_llm_call) | 每轮一次，LLM 循环前 — 可返回 `{"context": "..."}` 以[向用户消息注入上下文](/user-guide/features/hooks#pre_llm_call) |
|
||||
| [`post_llm_call`](/user-guide/features/hooks#post_llm_call) | 每轮一次，LLM 循环后（仅成功轮次） |
|
||||
| [`on_session_start`](/user-guide/features/hooks#on_session_start) | 新会话创建时（仅第一轮） |
|
||||
| [`on_session_end`](/user-guide/features/hooks#on_session_end) | 每次 `run_conversation` 调用结束时 + CLI 退出处理器 |
|
||||
| [`on_session_finalize`](/user-guide/features/hooks#on_session_finalize) | CLI/gateway 销毁活跃会话时（`/new`、GC、CLI 退出） |
|
||||
| [`on_session_reset`](/user-guide/features/hooks#on_session_reset) | Gateway 换入新会话 key 时（`/new`、`/reset`、`/clear`、空闲轮换） |
|
||||
| [`subagent_stop`](/user-guide/features/hooks#subagent_stop) | `delegate_task` 完成后每个子 agent 触发一次 |
|
||||
| [`pre_gateway_dispatch`](/user-guide/features/hooks#pre_gateway_dispatch) | Gateway 收到用户消息，在认证和调度之前。返回 `{"action": "skip" \| "rewrite" \| "allow", ...}` 以影响流程。 |
|
||||
|
||||
## 插件类型
|
||||
|
||||
Hermes 有四种插件：
|
||||
|
||||
| 类型 | 作用 | 选择方式 | 位置 |
|
||||
|------|-------------|-----------|----------|
|
||||
| **通用插件** | 添加工具、hook、斜杠命令、CLI 命令 | 多选（启用/禁用） | `~/.hermes/plugins/` |
|
||||
| **Memory provider** | 替换或增强内置 memory | 单选（同时只有一个激活） | `plugins/memory/` |
|
||||
| **Context engine** | 替换内置上下文压缩器 | 单选（同时只有一个激活） | `plugins/context_engine/` |
|
||||
| **Model provider** | 声明推理后端（OpenRouter、Anthropic 等） | 多注册，通过 `--provider` / `config.yaml` 选择 | `plugins/model-providers/` |
|
||||
|
||||
Memory provider 和 context engine 是 **provider 插件** — 每种类型同时只能有一个激活。Model provider 也是插件，但可以同时加载多个；用户通过 `--provider` 或 `config.yaml` 一次选择一个。通用插件可以任意组合启用。
|
||||
|
||||
## 可插拔接口 — 各场景对应文档
|
||||
|
||||
上表展示了四种插件类别，但在"通用插件"中，`PluginContext` 暴露了多个不同的扩展点 — Hermes 还接受 Python 插件系统之外的扩展（配置驱动的后端、shell hook 命令、外部服务器等）。使用下表找到适合你需求的文档：
|
||||
|
||||
| 想要添加… | 方式 | 编写指南 |
|
||||
|---|---|---|
|
||||
| LLM 可调用的**工具** | Python 插件 — `ctx.register_tool()` | [Build a Hermes Plugin](/guides/build-a-hermes-plugin) · [Adding Tools](/developer-guide/adding-tools) |
|
||||
| **生命周期 hook**（LLM 前后、会话开始/结束、工具过滤） | Python 插件 — `ctx.register_hook()` | [Hooks reference](/user-guide/features/hooks) · [Build a Hermes Plugin](/guides/build-a-hermes-plugin) |
|
||||
| CLI / gateway 的**斜杠命令** | Python 插件 — `ctx.register_command()` | [Build a Hermes Plugin](/guides/build-a-hermes-plugin) · [Extending the CLI](/developer-guide/extending-the-cli) |
|
||||
| `hermes <thing>` 的**子命令** | Python 插件 — `ctx.register_cli_command()` | [Extending the CLI](/developer-guide/extending-the-cli) |
|
||||
| 插件附带的**skill** | Python 插件 — `ctx.register_skill()` | [Creating Skills](/developer-guide/creating-skills) |
|
||||
| **推理后端**（LLM provider：OpenAI 兼容、Codex、Anthropic-Messages、Bedrock） | Provider 插件 — 在 `plugins/model-providers/<name>/` 中调用 `register_provider(ProviderProfile(...))` | **[Model Provider Plugins](/developer-guide/model-provider-plugin)** · [Adding Providers](/developer-guide/adding-providers) |
|
||||
| **Gateway 频道**（Discord / Telegram / IRC / Teams 等） | 平台插件 — 在 `plugins/platforms/<name>/` 中调用 `ctx.register_platform()` | [Adding Platform Adapters](/developer-guide/adding-platform-adapters) |
|
||||
| **Memory 后端**（Honcho、Mem0、Supermemory 等） | Memory 插件 — 在 `plugins/memory/<name>/` 中继承 `MemoryProvider` | [Memory Provider Plugins](/developer-guide/memory-provider-plugin) |
|
||||
| **上下文压缩策略** | Context-engine 插件 — `ctx.register_context_engine()` | [Context Engine Plugins](/developer-guide/context-engine-plugin) |
|
||||
| **图像生成后端**（DALL·E、SDXL 等） | 后端插件 — `ctx.register_image_gen_provider()` | [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) |
|
||||
| **视频生成后端**（Veo、Kling、Pixverse、Grok-Imagine、Runway 等） | 后端插件 — `ctx.register_video_gen_provider()` | [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin) |
|
||||
| **TTS 后端**（任意 CLI — Piper、VoxCPM、Kokoro、xtts、语音克隆脚本等） | 配置驱动（推荐）— 在 `config.yaml` 的 `tts.providers.<name>` 下以 `type: command` 声明。或 Python 后端插件 — 对需要超出 shell 模板的 Python SDK / 流式引擎使用 `ctx.register_tts_provider()`。 | [TTS Setup](/user-guide/features/tts#custom-command-providers) · [Python plugin guide](/user-guide/features/tts#python-plugin-providers) |
|
||||
| **STT 后端**（自定义 whisper 二进制、本地 ASR CLI） | 配置驱动 — 将 `HERMES_LOCAL_STT_COMMAND` 环境变量设置为 shell 模板 | [Voice Message Transcription (STT)](/user-guide/features/tts#voice-message-transcription-stt) |
|
||||
| **通过 MCP 使用外部工具**（文件系统、GitHub、Linear、Notion、任意 MCP 服务器） | 配置驱动 — 在 `config.yaml` 中以 `command:` / `url:` 声明 `mcp_servers.<name>`。Hermes 自动发现服务器的工具并与内置工具一同注册。 | [MCP](/user-guide/features/mcp) |
|
||||
| **额外 skill 来源**（自定义 GitHub 仓库、私有 skill 索引） | CLI — `hermes skills tap add <repo>` | [Skills Hub](/user-guide/features/skills#skills-hub) · [发布自定义 tap](/user-guide/features/skills#publishing-a-custom-skill-tap) |
|
||||
| **Gateway 事件 hook**（在 `gateway:startup`、`session:start`、`agent:end`、`command:*` 时触发） | 将 `HOOK.yaml` + `handler.py` 放入 `~/.hermes/hooks/<name>/` | [Event Hooks](/user-guide/features/hooks#gateway-event-hooks) |
|
||||
| **Shell hook**（在事件时运行 shell 命令 — 通知、审计日志、桌面提醒） | 配置驱动 — 在 `config.yaml` 的 `hooks:` 下声明 | [Shell Hooks](/user-guide/features/hooks#shell-hooks) |
|
||||
|
||||
:::note
|
||||
并非所有扩展都是 Python 插件。某些扩展接口有意使用**配置驱动的 shell 命令**（TTS、STT、shell hook），这样你已有的任意 CLI 无需编写 Python 即可成为插件。其他的是 agent 连接并自动注册工具的**外部服务器**（MCP）。还有一些是拥有自己 manifest 格式的**即插即用目录**（gateway hook）。根据你的集成风格选择合适的接口；上表中的编写指南各自涵盖了占位符、发现机制和示例。
|
||||
:::
|
||||
|
||||
## NixOS 声明式插件
|
||||
|
||||
在 NixOS 上，插件可通过模块选项声明式安装 — 无需 `hermes plugins install`。完整详情请参见 **[Nix Setup 指南](/getting-started/nix-setup#plugins)**。
|
||||
|
||||
```nix
|
||||
services.hermes-agent = {
|
||||
# 目录插件（包含 plugin.yaml 的源码树）
|
||||
extraPlugins = [ (pkgs.fetchFromGitHub { ... }) ];
|
||||
# 入口点插件（pip 包）
|
||||
extraPythonPackages = [ (pkgs.python312Packages.buildPythonPackage { ... }) ];
|
||||
# 在 config 中启用
|
||||
settings.plugins.enabled = [ "my-plugin" ];
|
||||
};
|
||||
```
|
||||
|
||||
声明式插件以 `nix-managed-` 前缀符号链接 — 与手动安装的插件共存，从 Nix 配置中移除后自动清理。
|
||||
|
||||
## 管理插件
|
||||
|
||||
```bash
|
||||
hermes plugins # 统一交互式 UI
|
||||
hermes plugins list # 表格：已启用 / 已禁用 / 未启用
|
||||
hermes plugins install user/repo # 从 Git 安装，然后提示 Enable? [y/N]
|
||||
hermes plugins install user/repo --enable # 安装并启用（无提示）
|
||||
hermes plugins install user/repo --no-enable # 安装但保持禁用（无提示）
|
||||
hermes plugins update my-plugin # 拉取最新版本
|
||||
hermes plugins remove my-plugin # 卸载
|
||||
hermes plugins enable my-plugin # 添加到允许列表（普通插件）
|
||||
hermes plugins enable observability/langfuse # 添加到允许列表（子分类插件）
|
||||
hermes plugins disable my-plugin # 从允许列表移除并添加到禁用列表
|
||||
```
|
||||
|
||||
对于子分类目录下的插件（例如 `plugins/observability/langfuse/`、`plugins/image_gen/openai/`），使用完整的 `<category>/<plugin>` key — 这正是 `hermes plugins list` 在 **Name** 列中显示的内容。
|
||||
|
||||
### 交互式 UI
|
||||
|
||||
不带参数运行 `hermes plugins` 会打开一个复合交互界面：
|
||||
|
||||
```
|
||||
Plugins
|
||||
↑↓ navigate SPACE toggle ENTER configure/confirm ESC done
|
||||
|
||||
General Plugins
|
||||
→ [✓] my-tool-plugin — Custom search tool
|
||||
[ ] webhook-notifier — Event hooks
|
||||
[ ] disk-cleanup — Auto-cleanup of ephemeral files [bundled]
|
||||
[ ] observability/langfuse — Trace turns / LLM calls / tools to Langfuse [bundled]
|
||||
|
||||
Provider Plugins
|
||||
Memory Provider ▸ honcho
|
||||
Context Engine ▸ compressor
|
||||
```
|
||||
|
||||
- **General Plugins 区域** — 复选框，用空格切换。勾选 = 在 `plugins.enabled` 中，未勾选 = 在 `plugins.disabled` 中（明确关闭）。
|
||||
- **Provider Plugins 区域** — 显示当前选择。按 ENTER 进入单选选择器，选择一个激活的 provider。
|
||||
- 内置插件在同一列表中显示，带有 `[bundled]` 标签。
|
||||
|
||||
Provider 插件的选择保存到 `config.yaml`：
|
||||
|
||||
```yaml
|
||||
memory:
|
||||
provider: "honcho" # 空字符串 = 仅使用内置
|
||||
|
||||
context:
|
||||
engine: "compressor" # 默认内置压缩器
|
||||
```
|
||||
|
||||
### 已启用 vs. 已禁用 vs. 未设置
|
||||
|
||||
插件处于以下三种状态之一：
|
||||
|
||||
| 状态 | 含义 | 在 `plugins.enabled` 中？ | 在 `plugins.disabled` 中？ |
|
||||
|---|---|---|---|
|
||||
| `enabled` | 下次会话时加载 | 是 | 否 |
|
||||
| `disabled` | 明确关闭 — 即使同时在 `enabled` 中也不会加载 | （无关） | 是 |
|
||||
| `not enabled` | 已发现但从未选择加入 | 否 | 否 |
|
||||
|
||||
新安装或内置插件的默认状态为 `not enabled`。`hermes plugins list` 显示全部三种状态，便于区分明确关闭的插件和等待启用的插件。
|
||||
|
||||
在运行中的会话里，`/plugins` 显示当前已加载的插件。
|
||||
|
||||
## 注入消息
|
||||
|
||||
插件可使用 `ctx.inject_message()` 向活跃对话注入消息：
|
||||
|
||||
```python
|
||||
ctx.inject_message("New data arrived from the webhook", role="user")
|
||||
```
|
||||
|
||||
**签名：** `ctx.inject_message(content: str, role: str = "user") -> bool`
|
||||
|
||||
工作原理：
|
||||
|
||||
- 若 agent **空闲**（等待用户输入），消息会作为下一条输入排队并开始新一轮。
|
||||
- 若 agent **处于轮次中**（正在运行），消息会中断当前操作 — 与用户输入新消息并按下 Enter 效果相同。
|
||||
- 对于非 `"user"` 角色，内容会以 `[role]` 为前缀（例如 `[system] ...`）。
|
||||
- 若消息成功排队返回 `True`，若无 CLI 引用（例如在 gateway 模式下）则返回 `False`。
|
||||
|
||||
这使得远程控制查看器、消息桥接或 webhook 接收器等插件能够从外部来源向对话注入消息。
|
||||
|
||||
:::note
|
||||
`inject_message` 仅在 CLI 模式下可用。在 gateway 模式下，没有 CLI 引用，该方法返回 `False`。
|
||||
:::
|
||||
|
||||
完整的处理器约定、schema 格式、hook 行为、错误处理和常见错误请参见 **[完整指南](/guides/build-a-hermes-plugin)**。
|
||||
+200
@@ -0,0 +1,200 @@
|
||||
---
|
||||
title: Provider Routing
|
||||
description: 配置 OpenRouter provider 偏好，以优化成本、速度或质量。
|
||||
sidebar_label: Provider Routing
|
||||
sidebar_position: 7
|
||||
---
|
||||
|
||||
# Provider Routing
|
||||
|
||||
使用 [OpenRouter](https://openrouter.ai) 作为 LLM provider 时，Hermes Agent 支持 **provider routing**（提供商路由）——对哪些底层 AI provider 处理你的请求以及如何排列优先级进行精细控制。
|
||||
|
||||
OpenRouter 将请求路由到多个 provider（例如 Anthropic、Google、AWS Bedrock、Together AI）。Provider routing 让你可以针对成本、速度、质量进行优化，或强制指定特定 provider。
|
||||
|
||||
## 配置
|
||||
|
||||
在 `~/.hermes/config.yaml` 中添加 `provider_routing` 部分：
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
sort: "price" # 如何对 provider 排序
|
||||
only: [] # 白名单：仅使用这些 provider
|
||||
ignore: [] # 黑名单：永不使用这些 provider
|
||||
order: [] # 显式 provider 优先级顺序
|
||||
require_parameters: false # 仅使用支持所有参数的 provider
|
||||
data_collection: null # 控制数据收集（"allow" 或 "deny"）
|
||||
```
|
||||
|
||||
:::info
|
||||
Provider routing 仅在使用 OpenRouter 时生效。直接连接 provider（例如直接连接 Anthropic API）时无效。
|
||||
:::
|
||||
|
||||
## 选项
|
||||
|
||||
### `sort`
|
||||
|
||||
控制 OpenRouter 如何对可用 provider 排序。
|
||||
|
||||
| 值 | 说明 |
|
||||
|-------|-------------|
|
||||
| `"price"` | 最便宜的 provider 优先 |
|
||||
| `"throughput"` | 每秒 token 数最高的 provider 优先 |
|
||||
| `"latency"` | 首 token 延迟最低的 provider 优先 |
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
sort: "price"
|
||||
```
|
||||
|
||||
### `only`
|
||||
|
||||
Provider 名称白名单。设置后，**仅**使用这些 provider，其余全部排除。
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
only:
|
||||
- "Anthropic"
|
||||
- "Google"
|
||||
```
|
||||
|
||||
### `ignore`
|
||||
|
||||
Provider 名称黑名单。这些 provider **永远不会**被使用，即使它们提供最低价格或最快速度。
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
ignore:
|
||||
- "Together"
|
||||
- "DeepInfra"
|
||||
```
|
||||
|
||||
### `order`
|
||||
|
||||
显式优先级顺序。列在前面的 provider 优先使用，未列出的 provider 作为备选。
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
order:
|
||||
- "Anthropic"
|
||||
- "Google"
|
||||
- "AWS Bedrock"
|
||||
```
|
||||
|
||||
### `require_parameters`
|
||||
|
||||
设为 `true` 时，OpenRouter 仅路由到支持请求中**所有**参数（如 `temperature`、`top_p`、`tools` 等）的 provider，避免参数被静默丢弃。
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
require_parameters: true
|
||||
```
|
||||
|
||||
### `data_collection`
|
||||
|
||||
控制 provider 是否可将你的 prompt（提示词）用于训练。可选值为 `"allow"` 或 `"deny"`。
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
data_collection: "deny"
|
||||
```
|
||||
|
||||
## 实用示例
|
||||
|
||||
### 优化成本
|
||||
|
||||
路由到最便宜的可用 provider，适合高频使用和开发场景：
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
sort: "price"
|
||||
```
|
||||
|
||||
### 优化速度
|
||||
|
||||
优先选择低延迟 provider，适合交互式使用：
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
sort: "latency"
|
||||
```
|
||||
|
||||
### 优化吞吐量
|
||||
|
||||
适合长文本生成，token 每秒速率至关重要的场景：
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
sort: "throughput"
|
||||
```
|
||||
|
||||
### 锁定特定 Provider
|
||||
|
||||
确保所有请求都通过特定 provider 处理，以保证一致性：
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
only:
|
||||
- "Anthropic"
|
||||
```
|
||||
|
||||
### 排除特定 Provider
|
||||
|
||||
排除不希望使用的 provider（例如出于数据隐私考虑）：
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
ignore:
|
||||
- "Together"
|
||||
- "Lepton"
|
||||
data_collection: "deny"
|
||||
```
|
||||
|
||||
### 带备选的优先顺序
|
||||
|
||||
优先尝试首选 provider，不可用时回退到其他 provider：
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
order:
|
||||
- "Anthropic"
|
||||
- "Google"
|
||||
require_parameters: true
|
||||
```
|
||||
|
||||
## 工作原理
|
||||
|
||||
Provider routing 偏好通过每次 API 调用的 `extra_body.provider` 字段传递给 OpenRouter API，适用于以下两种模式：
|
||||
|
||||
- **CLI 模式** — 在 `~/.hermes/config.yaml` 中配置，启动时加载
|
||||
- **Gateway 模式** — 同一配置文件，gateway 启动时加载
|
||||
|
||||
路由配置从 `config.yaml` 读取，并在创建 `AIAgent` 时作为参数传入：
|
||||
|
||||
```
|
||||
providers_allowed ← 来自 provider_routing.only
|
||||
providers_ignored ← 来自 provider_routing.ignore
|
||||
providers_order ← 来自 provider_routing.order
|
||||
provider_sort ← 来自 provider_routing.sort
|
||||
provider_require_parameters ← 来自 provider_routing.require_parameters
|
||||
provider_data_collection ← 来自 provider_routing.data_collection
|
||||
```
|
||||
|
||||
:::tip
|
||||
可以组合使用多个选项。例如，按价格排序，同时排除某些 provider 并要求参数支持：
|
||||
|
||||
```yaml
|
||||
provider_routing:
|
||||
sort: "price"
|
||||
ignore: ["Together"]
|
||||
require_parameters: true
|
||||
data_collection: "deny"
|
||||
```
|
||||
:::
|
||||
|
||||
## 默认行为
|
||||
|
||||
未配置 `provider_routing` 部分时（默认情况），OpenRouter 使用其自身的默认路由逻辑，通常会自动在成本和可用性之间取得平衡。
|
||||
|
||||
:::tip Provider Routing 与 Fallback Models
|
||||
Provider routing 控制 OpenRouter **内部的子 provider** 如何处理你的请求。若需要在主模型失败时自动故障转移到完全不同的 provider，请参阅 [Fallback Providers](/user-guide/features/fallback-providers)。
|
||||
:::
|
||||
+767
@@ -0,0 +1,767 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: "Skills 系统"
|
||||
description: "按需加载的知识文档——渐进式披露、agent 管理的 skills 以及 Skills Hub"
|
||||
---
|
||||
|
||||
# Skills 系统
|
||||
|
||||
Skills 是 agent 在需要时可以加载的按需知识文档。它们遵循**渐进式披露**（progressive disclosure）模式以最小化 token 用量，并兼容 [agentskills.io](https://agentskills.io/specification) 开放标准。
|
||||
|
||||
所有 skills 存放在 **`~/.hermes/skills/`** 中——这是主目录和唯一可信来源。全新安装时，捆绑的 skills 会从仓库复制过来。通过 Hub 安装和 agent 创建的 skills 也存放在此处。agent 可以修改或删除任何 skill。
|
||||
|
||||
你也可以让 Hermes 指向**外部 skill 目录**——与本地目录一起扫描的额外文件夹。参见下方的[外部 Skill 目录](#external-skill-directories)。
|
||||
|
||||
另请参阅：
|
||||
|
||||
- [捆绑 Skills 目录](/reference/skills-catalog)
|
||||
- [官方可选 Skills 目录](/reference/optional-skills-catalog)
|
||||
|
||||
## 使用 Skills
|
||||
|
||||
每个已安装的 skill 都会自动作为斜杠命令可用：
|
||||
|
||||
```bash
|
||||
# 在 CLI 或任何消息平台中：
|
||||
/gif-search funny cats
|
||||
/axolotl help me fine-tune Llama 3 on my dataset
|
||||
/github-pr-workflow create a PR for the auth refactor
|
||||
/plan design a rollout for migrating our auth provider
|
||||
|
||||
# 只输入 skill 名称即可加载它，并让 agent 询问你的需求：
|
||||
/excalidraw
|
||||
```
|
||||
|
||||
捆绑的 `plan` skill 是一个很好的示例。运行 `/plan [request]` 会加载该 skill 的指令，告知 Hermes 在需要时检查上下文、编写 markdown 实现计划而非直接执行任务，并将结果保存在相对于当前工作区/后端工作目录的 `.hermes/plans/` 下。
|
||||
|
||||
你也可以通过自然对话与 skills 交互：
|
||||
|
||||
```bash
|
||||
hermes chat --toolsets skills -q "What skills do you have?"
|
||||
hermes chat --toolsets skills -q "Show me the axolotl skill"
|
||||
```
|
||||
|
||||
## 渐进式披露
|
||||
|
||||
Skills 使用一种节省 token 的加载模式：
|
||||
|
||||
```
|
||||
Level 0: skills_list() → [{name, description, category}, ...] (~3k tokens)
|
||||
Level 1: skill_view(name) → Full content + metadata (varies)
|
||||
Level 2: skill_view(name, path) → Specific reference file (varies)
|
||||
```
|
||||
|
||||
agent 只在真正需要时才加载完整的 skill 内容。
|
||||
|
||||
## SKILL.md 格式
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: Brief description of what this skill does
|
||||
version: 1.0.0
|
||||
platforms: [macos, linux] # Optional — restrict to specific OS platforms
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [python, automation]
|
||||
category: devops
|
||||
fallback_for_toolsets: [web] # Optional — conditional activation (see below)
|
||||
requires_toolsets: [terminal] # Optional — conditional activation (see below)
|
||||
config: # Optional — config.yaml settings
|
||||
- key: my.setting
|
||||
description: "What this controls"
|
||||
default: "value"
|
||||
prompt: "Prompt for setup"
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
## When to Use
|
||||
Trigger conditions for this skill.
|
||||
|
||||
## Procedure
|
||||
1. Step one
|
||||
2. Step two
|
||||
|
||||
## Pitfalls
|
||||
- Known failure modes and fixes
|
||||
|
||||
## Verification
|
||||
How to confirm it worked.
|
||||
```
|
||||
|
||||
### 平台特定 Skills
|
||||
|
||||
Skills 可以使用 `platforms` 字段将自身限制在特定操作系统上：
|
||||
|
||||
| 值 | 匹配 |
|
||||
|-------|---------|
|
||||
| `macos` | macOS（Darwin） |
|
||||
| `linux` | Linux |
|
||||
| `windows` | Windows |
|
||||
|
||||
```yaml
|
||||
platforms: [macos] # macOS only (e.g., iMessage, Apple Reminders, FindMy)
|
||||
platforms: [macos, linux] # macOS and Linux
|
||||
```
|
||||
|
||||
设置后，该 skill 会在不兼容的平台上自动从系统提示词、`skills_list()` 和斜杠命令中隐藏。若省略，则在所有平台上加载。
|
||||
|
||||
## Skill 输出与媒体传递
|
||||
|
||||
当 skill 响应（或任何 agent 响应）包含指向媒体文件的裸绝对路径时——例如 `/home/user/screenshots/diagram.png`——gateway 会自动检测到它，将其从可见文本中剥离，并以原生方式将文件传递给用户的聊天界面（Telegram 图片、Discord 附件等），而不是在消息中留下原始路径。
|
||||
|
||||
对于音频，`[[audio_as_voice]]` 指令会将音频文件提升为在支持该功能的平台（Telegram、WhatsApp）上的原生语音消息气泡。
|
||||
|
||||
### 强制文档式传递：`[[as_document]]`
|
||||
|
||||
有时你需要与内联预览**相反**的效果：你希望文件作为可下载附件传递，而不是经过重新压缩的图片气泡。典型示例是高分辨率截图或图表——Telegram 的 `sendPhoto` 会将其重新压缩至约 200 KB、1280 px，严重影响可读性。通过 `sendDocument` 发送的 1-2 MB PNG 则保留原始字节完整无损。
|
||||
|
||||
如果响应（或其中任何文本——通常是最后一行）包含字面指令 `[[as_document]]`，则从该响应中提取的每个媒体路径都会作为文档/文件附件传递，而不是图片气泡：
|
||||
|
||||
```
|
||||
Here is your rendered chart:
|
||||
|
||||
/home/user/.hermes/cache/chart-q4-2025.png
|
||||
|
||||
[[as_document]]
|
||||
```
|
||||
|
||||
该指令在传递前会被剥离，用户不会看到它。粒度有意设计为每个响应全有或全无：发出一次 `[[as_document]]`，同一响应中的每个图片路径都会作为文档传递。这与 `[[audio_as_voice]]` 的作用范围一致。
|
||||
|
||||
在以下情况下从 skill 中使用它：
|
||||
|
||||
- 你生成了用户需要作为文件的截图或图表（用于在其他工具中编辑、存档、完整分享）。
|
||||
- 默认的有损预览会遮蔽细节（小字体、像素精确的图表、对颜色敏感的渲染）。
|
||||
|
||||
没有单独文档路径的平台（如 SMS）会回退到其支持的任何附件机制。
|
||||
|
||||
### 条件激活（Fallback Skills）
|
||||
|
||||
Skills 可以根据当前会话中可用的工具自动显示或隐藏自身。这对于**fallback skills**（回退 skills）最为有用——仅在高级工具不可用时才应出现的免费或本地替代方案。
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
hermes:
|
||||
fallback_for_toolsets: [web] # Show ONLY when these toolsets are unavailable
|
||||
requires_toolsets: [terminal] # Show ONLY when these toolsets are available
|
||||
fallback_for_tools: [web_search] # Show ONLY when these specific tools are unavailable
|
||||
requires_tools: [terminal] # Show ONLY when these specific tools are available
|
||||
```
|
||||
|
||||
| 字段 | 行为 |
|
||||
|-------|----------|
|
||||
| `fallback_for_toolsets` | 当列出的 toolsets 可用时，skill **隐藏**。不可用时显示。 |
|
||||
| `fallback_for_tools` | 同上，但检查单个工具而非 toolsets。 |
|
||||
| `requires_toolsets` | 当列出的 toolsets 不可用时，skill **隐藏**。可用时显示。 |
|
||||
| `requires_tools` | 同上，但检查单个工具。 |
|
||||
|
||||
**示例：** 内置的 `duckduckgo-search` skill 使用 `fallback_for_toolsets: [web]`。当你设置了 `FIRECRAWL_API_KEY` 时，web toolset 可用，agent 使用 `web_search`——DuckDuckGo skill 保持隐藏。如果 API key 缺失，web toolset 不可用，DuckDuckGo skill 会自动作为 fallback 出现。
|
||||
|
||||
没有任何条件字段的 skills 行为与之前完全相同——始终显示。
|
||||
|
||||
## 加载时的安全设置
|
||||
|
||||
Skills 可以声明所需的环境变量，而不会从发现列表中消失：
|
||||
|
||||
```yaml
|
||||
required_environment_variables:
|
||||
- name: TENOR_API_KEY
|
||||
prompt: Tenor API key
|
||||
help: Get a key from https://developers.google.com/tenor
|
||||
required_for: full functionality
|
||||
```
|
||||
|
||||
当遇到缺失的值时，Hermes 仅在本地 CLI 中实际加载 skill 时才会安全地请求输入。你可以跳过设置并继续使用该 skill。消息平台不会在聊天中请求密钥——它们会告诉你改用本地的 `hermes setup` 或 `~/.hermes/.env`。
|
||||
|
||||
一旦设置，声明的环境变量会**自动传递**到 `execute_code` 和 `terminal` 沙箱——skill 的脚本可以直接使用 `$TENOR_API_KEY`。对于非 skill 的环境变量，使用 `terminal.env_passthrough` 配置选项。详情参见[环境变量传递](/user-guide/security#environment-variable-passthrough)。
|
||||
|
||||
### Skill 配置设置
|
||||
|
||||
Skills 还可以声明存储在 `config.yaml` 中的非密钥配置设置（路径、偏好项）：
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
hermes:
|
||||
config:
|
||||
- key: myplugin.path
|
||||
description: Path to the plugin data directory
|
||||
default: "~/myplugin-data"
|
||||
prompt: Plugin data directory path
|
||||
```
|
||||
|
||||
设置存储在 config.yaml 的 `skills.config` 下。`hermes config migrate` 会提示配置未设置的项，`hermes config show` 会显示它们。当 skill 加载时，其解析后的配置值会注入到上下文中，agent 会自动知晓已配置的值。
|
||||
|
||||
详情参见 [Skill 设置](/user-guide/configuration#skill-settings) 和[创建 Skills——配置设置](/developer-guide/creating-skills#config-settings-configyaml)。
|
||||
|
||||
## Skill 目录结构
|
||||
|
||||
```text
|
||||
~/.hermes/skills/ # Single source of truth
|
||||
├── mlops/ # Category directory
|
||||
│ ├── axolotl/
|
||||
│ │ ├── SKILL.md # Main instructions (required)
|
||||
│ │ ├── references/ # Additional docs
|
||||
│ │ ├── templates/ # Output formats
|
||||
│ │ ├── scripts/ # Helper scripts callable from the skill
|
||||
│ │ └── assets/ # Supplementary files
|
||||
│ └── vllm/
|
||||
│ └── SKILL.md
|
||||
├── devops/
|
||||
│ └── deploy-k8s/ # Agent-created skill
|
||||
│ ├── SKILL.md
|
||||
│ └── references/
|
||||
├── .hub/ # Skills Hub state
|
||||
│ ├── lock.json
|
||||
│ ├── quarantine/
|
||||
│ └── audit.log
|
||||
└── .bundled_manifest # Tracks seeded bundled skills
|
||||
```
|
||||
|
||||
## 外部 Skill 目录
|
||||
|
||||
如果你在 Hermes 之外维护 skills——例如，供多个 AI 工具使用的共享 `~/.agents/skills/` 目录——你可以告诉 Hermes 也扫描这些目录。
|
||||
|
||||
在 `~/.hermes/config.yaml` 的 `skills` 部分下添加 `external_dirs`：
|
||||
|
||||
```yaml
|
||||
skills:
|
||||
external_dirs:
|
||||
- ~/.agents/skills
|
||||
- /home/shared/team-skills
|
||||
- ${SKILLS_REPO}/skills
|
||||
```
|
||||
|
||||
路径支持 `~` 展开和 `${VAR}` 环境变量替换。
|
||||
|
||||
### 工作原理
|
||||
|
||||
- **本地创建，就地更新**：新的 agent 创建的 skills 写入 `~/.hermes/skills/`。现有 skills 在找到的位置被修改，包括 `external_dirs` 下的 skills，当 agent 使用 `skill_manage` 操作（如 `patch`、`edit`、`write_file`、`remove_file` 或 `delete`）时。
|
||||
- **外部目录不是写保护边界**：如果外部 skill 目录对 Hermes 进程可写，agent 管理的 skill 更新可以修改该目录中的文件。如果共享的外部 skills 必须保持只读，请使用文件系统权限或单独的 profile/toolset 设置。
|
||||
- **本地优先**：如果同一 skill 名称同时存在于本地目录和外部目录中，本地版本优先。
|
||||
- **完整集成**：外部 skills 出现在系统提示词索引、`skills_list`、`skill_view` 以及 `/skill-name` 斜杠命令中——与本地 skills 无异。
|
||||
- **不存在的路径会被静默跳过**：如果配置的目录不存在，Hermes 会忽略它而不报错。适用于可能不在每台机器上都存在的可选共享目录。
|
||||
|
||||
### 示例
|
||||
|
||||
```text
|
||||
~/.hermes/skills/ # Local (primary, read-write)
|
||||
├── devops/deploy-k8s/
|
||||
│ └── SKILL.md
|
||||
└── mlops/axolotl/
|
||||
└── SKILL.md
|
||||
|
||||
~/.agents/skills/ # External (shared, mutable if writable)
|
||||
├── my-custom-workflow/
|
||||
│ └── SKILL.md
|
||||
└── team-conventions/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
所有四个 skills 都出现在你的 skill 索引中。如果你在本地创建一个名为 `my-custom-workflow` 的新 skill，它会遮蔽外部版本。
|
||||
|
||||
## Skill 捆绑包
|
||||
|
||||
Skill 捆绑包是将多个 skills 归组在单个斜杠命令下的小型 YAML 文件。当你运行 `/<bundle-name>` 时，捆绑包中列出的每个 skill 都会同时加载——当某个特定任务总是受益于同一组 skills 时非常有用。
|
||||
|
||||
### 快速示例
|
||||
|
||||
```bash
|
||||
# 为后端功能开发创建一个捆绑包
|
||||
hermes bundles create backend-dev \
|
||||
--skill github-code-review \
|
||||
--skill test-driven-development \
|
||||
--skill github-pr-workflow \
|
||||
-d "Backend feature work — review, test, PR workflow"
|
||||
```
|
||||
|
||||
然后在 CLI 或任何 gateway 平台中：
|
||||
|
||||
```
|
||||
/backend-dev refactor the auth middleware
|
||||
```
|
||||
|
||||
agent 接收到所有三个 skills 加载到一条用户消息中，斜杠命令后的任何文本都作为用户指令附加。
|
||||
|
||||
### YAML 模式
|
||||
|
||||
捆绑包存放在 **`~/.hermes/skill-bundles/<slug>.yaml`** 中，格式如下：
|
||||
|
||||
```yaml
|
||||
name: backend-dev
|
||||
description: Backend feature work — review, test, PR workflow.
|
||||
skills:
|
||||
- github-code-review
|
||||
- test-driven-development
|
||||
- github-pr-workflow
|
||||
instruction: |
|
||||
Always start by writing failing tests, then implement.
|
||||
Open the PR through the standard workflow with co-author tags.
|
||||
```
|
||||
|
||||
字段说明：
|
||||
- `name`（可选——默认为文件名主干）——捆绑包的显示名称。规范化为连字符 slug 用于斜杠命令（`Backend Dev` → `/backend-dev`）。
|
||||
- `description`（可选）——在 `/bundles` 和 `hermes bundles list` 中显示的简短文本。
|
||||
- `skills`（必填，非空列表）——skill 名称或相对于你的 skills 目录的路径。使用与 `/<skill-name>` 相同的标识符。
|
||||
- `instruction`（可选）——附加在加载的 skill 内容前的额外指导。适用于固化"我们总是这样一起使用这些 skills"的方式。
|
||||
|
||||
### 管理捆绑包
|
||||
|
||||
```bash
|
||||
# 列出所有已安装的捆绑包
|
||||
hermes bundles list
|
||||
|
||||
# 查看某个捆绑包
|
||||
hermes bundles show backend-dev
|
||||
|
||||
# 交互式创建捆绑包（省略 --skill 标志以逐行输入）
|
||||
hermes bundles create research
|
||||
|
||||
# 覆盖现有捆绑包
|
||||
hermes bundles create backend-dev --skill ... --force
|
||||
|
||||
# 删除捆绑包
|
||||
hermes bundles delete backend-dev
|
||||
|
||||
# 重新扫描 ~/.hermes/skill-bundles/ 并报告变更
|
||||
hermes bundles reload
|
||||
```
|
||||
|
||||
在聊天会话中，`/bundles` 会列出每个已安装的捆绑包及其 skills。
|
||||
|
||||
### 行为
|
||||
|
||||
- **当 slug 冲突时，捆绑包优先于单个 skills。** 如果你将捆绑包命名为 `research`，同时也有一个名为 `research` 的 skill，`/research` 会调用捆绑包。这是有意为之——你通过命名选择了捆绑包。
|
||||
- **缺失的 skills 会被跳过，而不是致命错误。** 如果捆绑包列出了 `skill-foo` 但你未安装它，捆绑包仍会加载能解析的 skills，agent 会收到一条列出跳过内容的说明。
|
||||
- **捆绑包在每个界面都有效**——交互式 CLI、TUI、仪表板聊天以及每个 gateway 平台（Telegram、Discord、Slack……）——因为调度与单个 skill 命令集中在同一位置。
|
||||
- **捆绑包不会使 prompt 缓存失效。** 它们在调用时生成一条新的用户消息，与 `/<skill-name>` 的方式相同——不修改系统提示词。
|
||||
|
||||
### 捆绑包优于逐个手动安装 skill 的场景
|
||||
|
||||
在以下情况下使用捆绑包：
|
||||
- 你总是为某个重复任务配对相同的 skills（`/backend-dev`、`/release-prep`、`/incident-response`）。
|
||||
- 你想要比依次输入多个 `/skill` 调用更简洁的心智模型。
|
||||
- 你想通过将捆绑包 YAML 提交到共享 dotfiles 仓库并符号链接到 `~/.hermes/skill-bundles/` 来发布团队范围的"任务配置文件"。
|
||||
|
||||
捆绑包只是一个 YAML 别名——它不会为你安装 skills。Skills 本身必须已经存在（在 `~/.hermes/skills/` 或外部 skill 目录中）。否则捆绑包调用只会跳过缺失的 skills。
|
||||
|
||||
## Agent 管理的 Skills（skill_manage 工具）
|
||||
|
||||
agent 可以通过 `skill_manage` 工具创建、更新和删除自己的 skills。这是 agent 的**程序性记忆**——当它找到一个非平凡的工作流时，它会将该方法保存为 skill 以供将来复用。
|
||||
|
||||
### Agent 创建 Skills 的时机
|
||||
|
||||
- 成功完成复杂任务后（5+ 次工具调用）
|
||||
- 遇到错误或死路并找到可行路径时
|
||||
- 用户纠正了其方法时
|
||||
- 发现了非平凡的工作流时
|
||||
|
||||
### 操作
|
||||
|
||||
| 操作 | 用途 | 关键参数 |
|
||||
|--------|---------|------------|
|
||||
| `create` | 从头创建新 skill | `name`、`content`（完整 SKILL.md）、可选 `category` |
|
||||
| `patch` | 针对性修复（首选） | `name`、`old_string`、`new_string` |
|
||||
| `edit` | 重大结构性重写 | `name`、`content`（完整 SKILL.md 替换） |
|
||||
| `delete` | 完全删除一个 skill | `name` |
|
||||
| `write_file` | 添加/更新支持文件 | `name`、`file_path`、`file_content` |
|
||||
| `remove_file` | 删除支持文件 | `name`、`file_path` |
|
||||
|
||||
:::tip
|
||||
`patch` 操作是更新的首选方式——它比 `edit` 更节省 token，因为工具调用中只出现变更的文本。
|
||||
:::
|
||||
|
||||
## Skills Hub
|
||||
|
||||
从在线注册表、`skills.sh`、直接的知名 skill 端点以及官方可选 skills 中浏览、搜索、安装和管理 skills。
|
||||
|
||||
### 常用命令
|
||||
|
||||
```bash
|
||||
hermes skills browse # Browse all hub skills (official first)
|
||||
hermes skills browse --source official # Browse only official optional skills
|
||||
hermes skills search kubernetes # Search all sources
|
||||
hermes skills search react --source skills-sh # Search the skills.sh directory
|
||||
hermes skills search https://mintlify.com/docs --source well-known
|
||||
hermes skills inspect openai/skills/k8s # Preview before installing
|
||||
hermes skills install openai/skills/k8s # Install with security scan
|
||||
hermes skills install official/security/1password
|
||||
hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force
|
||||
hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify
|
||||
hermes skills install https://sharethis.chat/SKILL.md # Direct URL (single-file SKILL.md)
|
||||
hermes skills install https://example.com/SKILL.md --name my-skill # Override name when frontmatter has none
|
||||
hermes skills list --source hub # List hub-installed skills
|
||||
hermes skills check # Check installed hub skills for upstream updates
|
||||
hermes skills update # Reinstall hub skills with upstream changes when needed
|
||||
hermes skills audit # Re-scan all hub skills for security
|
||||
hermes skills uninstall k8s # Remove a hub skill
|
||||
hermes skills reset google-workspace # Un-stick a bundled skill from "user-modified" (see below)
|
||||
hermes skills reset google-workspace --restore # Also restore the bundled version, deleting your local edits
|
||||
hermes skills publish skills/my-skill --to github --repo owner/repo
|
||||
hermes skills snapshot export setup.json # Export skill config
|
||||
hermes skills tap add myorg/skills-repo # Add a custom GitHub source
|
||||
```
|
||||
|
||||
### 支持的 hub 来源
|
||||
|
||||
| 来源 | 示例 | 说明 |
|
||||
|--------|---------|-------|
|
||||
| `official` | `official/security/1password` | Hermes 随附的可选 skills。 |
|
||||
| `skills-sh` | `skills-sh/vercel-labs/agent-skills/vercel-react-best-practices` | 可通过 `hermes skills search <query> --source skills-sh` 搜索。当 skills.sh slug 与仓库文件夹不同时，Hermes 会解析别名式 skills。 |
|
||||
| `well-known` | `well-known:https://mintlify.com/docs/.well-known/skills/mintlify` | 直接从网站的 `/.well-known/skills/index.json` 提供的 skills。使用站点或文档 URL 搜索。 |
|
||||
| `url` | `https://sharethis.chat/SKILL.md` | 指向单文件 `SKILL.md` 的直接 HTTP(S) URL。名称解析顺序：frontmatter → URL slug → 交互式提示 → `--name` 标志。 |
|
||||
| `github` | `openai/skills/k8s` | 直接从 GitHub 仓库/路径安装以及基于 GitHub 的自定义 tap。 |
|
||||
| `clawhub`、`lobehub`、`browse-sh`、`claude-marketplace` | 来源特定标识符 | 社区或市场集成。 |
|
||||
|
||||
### 集成的 hub 和注册表
|
||||
|
||||
Hermes 目前与以下 skills 生态系统和发现来源集成：
|
||||
|
||||
#### 1. 官方可选 skills（`official`）
|
||||
|
||||
这些 skills 在 Hermes 仓库中维护，以内置信任级别安装。
|
||||
|
||||
- 目录：[官方可选 Skills 目录](../../reference/optional-skills-catalog)
|
||||
- 仓库中的来源：`optional-skills/`
|
||||
- 示例：
|
||||
|
||||
```bash
|
||||
hermes skills browse --source official
|
||||
hermes skills install official/security/1password
|
||||
```
|
||||
|
||||
#### 2. skills.sh（`skills-sh`）
|
||||
|
||||
这是 Vercel 的公共 skills 目录。Hermes 可以直接搜索它、查看 skill 详情页、解析别名式 slug，并从底层源仓库安装。
|
||||
|
||||
- 目录：[skills.sh](https://skills.sh/)
|
||||
- CLI/工具仓库：[vercel-labs/skills](https://github.com/vercel-labs/skills)
|
||||
- Vercel 官方 skills 仓库：[vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)
|
||||
- 示例：
|
||||
|
||||
```bash
|
||||
hermes skills search react --source skills-sh
|
||||
hermes skills inspect skills-sh/vercel-labs/json-render/json-render-react
|
||||
hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force
|
||||
```
|
||||
|
||||
#### 3. Well-known skill 端点（`well-known`）
|
||||
|
||||
这是基于 URL 的发现机制，来自发布 `/.well-known/skills/index.json` 的站点。它不是单一的集中式 hub——它是一种 Web 发现约定。
|
||||
|
||||
- 示例实时端点：[Mintlify docs skills index](https://mintlify.com/docs/.well-known/skills/index.json)
|
||||
- 参考服务器实现：[vercel-labs/skills-handler](https://github.com/vercel-labs/skills-handler)
|
||||
- 示例：
|
||||
|
||||
```bash
|
||||
hermes skills search https://mintlify.com/docs --source well-known
|
||||
hermes skills inspect well-known:https://mintlify.com/docs/.well-known/skills/mintlify
|
||||
hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify
|
||||
```
|
||||
|
||||
#### 4. 直接 GitHub skills（`github`）
|
||||
|
||||
Hermes 可以直接从 GitHub 仓库和基于 GitHub 的 tap 安装。当你已知仓库/路径或想添加自己的自定义源仓库时非常有用。
|
||||
|
||||
默认 tap（无需任何设置即可浏览）：
|
||||
- [openai/skills](https://github.com/openai/skills)
|
||||
- [anthropics/skills](https://github.com/anthropics/skills)
|
||||
- [huggingface/skills](https://github.com/huggingface/skills)
|
||||
- [NVIDIA/skills](https://github.com/NVIDIA/skills) — NVIDIA 官方验证的技能（带签名 `skill.oms.sig` 与治理用 `skill-card.md`）
|
||||
- [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)
|
||||
- [garrytan/gstack](https://github.com/garrytan/gstack)
|
||||
|
||||
- 示例：
|
||||
|
||||
```bash
|
||||
hermes skills install openai/skills/k8s
|
||||
hermes skills tap add myorg/skills-repo
|
||||
```
|
||||
|
||||
#### 5. ClawHub（`clawhub`）
|
||||
|
||||
作为社区来源集成的第三方 skills 市场。
|
||||
|
||||
- 站点：[clawhub.ai](https://clawhub.ai/)
|
||||
- Hermes 来源 id：`clawhub`
|
||||
|
||||
#### 6. Claude 市场式仓库（`claude-marketplace`）
|
||||
|
||||
Hermes 支持发布 Claude 兼容插件/市场清单的市场仓库。
|
||||
|
||||
已知集成来源包括：
|
||||
- [anthropics/skills](https://github.com/anthropics/skills)
|
||||
- [aiskillstore/marketplace](https://github.com/aiskillstore/marketplace)
|
||||
|
||||
Hermes 来源 id：`claude-marketplace`
|
||||
|
||||
#### 7. LobeHub（`lobehub`）
|
||||
|
||||
Hermes 可以从 LobeHub 的公共目录中搜索并将 agent 条目转换为可安装的 Hermes skills。
|
||||
|
||||
- 站点：[LobeHub](https://lobehub.com/)
|
||||
- 公共 agents 索引：[chat-agents.lobehub.com](https://chat-agents.lobehub.com/)
|
||||
- 后端仓库：[lobehub/lobe-chat-agents](https://github.com/lobehub/lobe-chat-agents)
|
||||
- Hermes 来源 id：`lobehub`
|
||||
|
||||
#### 8. browse.sh（`browse-sh`）
|
||||
|
||||
Hermes 与 [browse.sh](https://browse.sh) 集成，这是 Browserbase 的目录，包含 200+ 个针对特定站点的浏览器自动化 SKILL.md 文件（Airbnb、Amazon、arXiv、12306.cn、Etsy、Xero 等）。每个 skill 描述如何端到端驱动一个网站，适合与 Hermes 的浏览器工具以及你已安装的任何浏览器自动化 skills 配合使用。
|
||||
|
||||
- 站点：[browse.sh](https://browse.sh/)
|
||||
- 目录 API：`https://browse.sh/api/skills`
|
||||
- Hermes 来源 id：`browse-sh`
|
||||
- 信任级别：`community`
|
||||
|
||||
```bash
|
||||
hermes skills search airbnb --source browse-sh
|
||||
hermes skills inspect browse-sh/airbnb.com/search-listings-ddgioa
|
||||
hermes skills install browse-sh/airbnb.com/search-listings-ddgioa
|
||||
```
|
||||
|
||||
标识符使用 `browse-sh/<hostname>/<task-id>` 的形式，与 browse.sh 目录公开的 slug 匹配。内容通过每个 skill 的详情端点（`/api/skills/<slug>` → `skillMdUrl`）解析，而不是通过目录的 GitHub `sourceUrl`。
|
||||
|
||||
#### 9. 直接 URL（`url`）
|
||||
|
||||
直接从任何 HTTP(S) URL 安装单文件 `SKILL.md`——当作者在自己的站点上托管 skill 时非常有用（无 hub 列表，无需输入 GitHub 路径）。Hermes 获取 URL，解析 YAML frontmatter，进行安全扫描并安装。
|
||||
|
||||
- Hermes 来源 id：`url`
|
||||
- 标识符：URL 本身（无需前缀）
|
||||
- 范围：**仅限单文件 `SKILL.md`**。包含 `references/` 或 `scripts/` 的多文件 skills 需要清单，应通过上述其他来源之一发布。
|
||||
|
||||
```bash
|
||||
hermes skills install https://sharethis.chat/SKILL.md
|
||||
hermes skills install https://example.com/my-skill/SKILL.md --category productivity
|
||||
```
|
||||
|
||||
名称解析顺序：
|
||||
1. SKILL.md YAML frontmatter 中的 `name:` 字段（推荐——每个格式良好的 skill 都有）。
|
||||
2. URL 路径中的父目录名称（例如 `.../my-skill/SKILL.md` → `my-skill`，或 `.../my-skill.md` → `my-skill`），当它是有效标识符（`^[a-z][a-z0-9_-]*$`）时。
|
||||
3. 在有 TTY 的终端上的交互式提示。
|
||||
4. 在非交互式界面（TUI 内的 `/skills install` 斜杠命令、gateway 平台、脚本）上，给出指向 `--name` 覆盖的清晰错误。
|
||||
|
||||
```bash
|
||||
# Frontmatter 没有名称且 URL slug 无意义——手动提供：
|
||||
hermes skills install https://example.com/SKILL.md --name sharethis-chat
|
||||
|
||||
# 或在聊天会话中：
|
||||
/skills install https://example.com/SKILL.md --name sharethis-chat
|
||||
```
|
||||
|
||||
信任级别始终为 `community`——与所有其他来源一样运行相同的安全扫描。URL 作为安装标识符存储，因此当你想刷新时，`hermes skills update` 会自动从同一 URL 重新获取。
|
||||
|
||||
### 安全扫描与 `--force`
|
||||
|
||||
所有通过 hub 安装的 skills 都经过**安全扫描器**检查，检测数据泄露、prompt 注入、破坏性命令、供应链信号及其他威胁。
|
||||
|
||||
`hermes skills inspect ...` 现在还会在可用时显示上游元数据：
|
||||
- 仓库 URL
|
||||
- skills.sh 详情页 URL
|
||||
- 安装命令
|
||||
- 每周安装量
|
||||
- 上游安全审计状态
|
||||
- well-known 索引/端点 URL
|
||||
|
||||
当你已审查第三方 skill 并希望覆盖非危险性策略阻止时，使用 `--force`：
|
||||
|
||||
```bash
|
||||
hermes skills install skills-sh/anthropics/skills/pdf --force
|
||||
```
|
||||
|
||||
重要行为：
|
||||
- `--force` 可以覆盖谨慎/警告类发现的策略阻止。
|
||||
- `--force` **不能**覆盖 `dangerous` 扫描结论。
|
||||
- 官方可选 skills（`official/...`）被视为内置信任，不显示第三方警告面板。
|
||||
|
||||
### 信任级别
|
||||
|
||||
| 级别 | 来源 | 策略 |
|
||||
|-------|--------|--------|
|
||||
| `builtin` | 随 Hermes 附带 | 始终受信任 |
|
||||
| `official` | 仓库中的 `optional-skills/` | 内置信任，无第三方警告 |
|
||||
| `trusted` | 受信任的注册表/仓库，如 `openai/skills`、`anthropics/skills`、`huggingface/skills`、`NVIDIA/skills` | 比社区来源更宽松的策略 |
|
||||
| `community` | 其他所有来源（`skills.sh`、well-known 端点、自定义 GitHub 仓库、大多数市场） | 非危险性发现可用 `--force` 覆盖；`dangerous` 结论保持阻止 |
|
||||
|
||||
### 更新生命周期
|
||||
|
||||
hub 现在跟踪足够的来源信息以重新检查已安装 skills 的上游副本：
|
||||
|
||||
```bash
|
||||
hermes skills check # Report which installed hub skills changed upstream
|
||||
hermes skills update # Reinstall only the skills with updates available
|
||||
hermes skills update react # Update one specific installed hub skill
|
||||
```
|
||||
|
||||
这使用存储的来源标识符加上当前上游捆绑包内容哈希来检测漂移。
|
||||
|
||||
:::tip GitHub 速率限制
|
||||
Skills hub 操作使用 GitHub API，未认证用户的速率限制为每小时 60 次请求。如果在安装或搜索时看到速率限制错误，请在 `.env` 文件中设置 `GITHUB_TOKEN` 以将限制提高到每小时 5,000 次请求。发生此情况时，错误消息会包含可操作的提示。
|
||||
:::
|
||||
|
||||
### 发布自定义 skill tap
|
||||
|
||||
如果你想分享一组精选的 skills——为你的团队、组织或公开分享——你可以将它们发布为 **tap**：其他 Hermes 用户通过 `hermes skills tap add <owner/repo>` 添加的 GitHub 仓库。无需服务器，无需注册表注册，无需发布流水线。只需一个包含 `SKILL.md` 文件的目录。
|
||||
|
||||
#### 仓库布局
|
||||
|
||||
tap 是任何 GitHub 仓库（公开或私有——私有仓库需要 `GITHUB_TOKEN`），布局如下：
|
||||
|
||||
```
|
||||
owner/repo
|
||||
├── skills/ # default path; configurable per-tap
|
||||
│ ├── my-workflow/
|
||||
│ │ ├── SKILL.md # required
|
||||
│ │ ├── references/ # optional supporting files
|
||||
│ │ ├── templates/
|
||||
│ │ └── scripts/
|
||||
│ ├── another-skill/
|
||||
│ │ └── SKILL.md
|
||||
│ └── third-skill/
|
||||
│ └── SKILL.md
|
||||
└── README.md # optional but helpful
|
||||
```
|
||||
|
||||
规则：
|
||||
- 每个 skill 存放在 tap 根路径（默认 `skills/`）下的独立目录中。
|
||||
- 目录名成为 skill 的安装 slug。
|
||||
- 每个 skill 目录必须包含一个带有标准 [SKILL.md frontmatter](#skillmd-format) 的 `SKILL.md`（`name`、`description`，以及可选的 `metadata.hermes.tags`、`version`、`author`、`platforms`、`metadata.hermes.config`）。
|
||||
- `references/`、`templates/`、`scripts/`、`assets/` 等子目录在安装时与 `SKILL.md` 一起下载。
|
||||
- 目录名以 `.` 或 `_` 开头的 skills 会被忽略。
|
||||
|
||||
Hermes 通过列出 tap 路径的每个子目录并探测每个目录中的 `SKILL.md` 来发现 skills。
|
||||
|
||||
#### 最小 tap 示例
|
||||
|
||||
```
|
||||
my-org/hermes-skills
|
||||
└── skills/
|
||||
└── deploy-runbook/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
`skills/deploy-runbook/SKILL.md`：
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: deploy-runbook
|
||||
description: Our deployment runbook — services, rollback, Slack channels
|
||||
version: 1.0.0
|
||||
author: My Org Platform Team
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [deployment, runbook, internal]
|
||||
---
|
||||
|
||||
# Deploy Runbook
|
||||
|
||||
Step 1: ...
|
||||
```
|
||||
|
||||
将其推送到 GitHub 后，任何 Hermes 用户都可以订阅并安装：
|
||||
|
||||
```bash
|
||||
hermes skills tap add my-org/hermes-skills
|
||||
hermes skills search deploy
|
||||
hermes skills install my-org/hermes-skills/deploy-runbook
|
||||
```
|
||||
|
||||
#### 非默认路径
|
||||
|
||||
如果你的 skills 不在 `skills/` 下（当你向现有项目添加 `skills/` 子树时很常见），请编辑 `~/.hermes/.hub/taps.json` 中的 tap 条目：
|
||||
|
||||
```json
|
||||
{
|
||||
"taps": [
|
||||
{"repo": "my-org/platform-docs", "path": "internal/skills/"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`hermes skills tap add` CLI 默认将新 tap 的 `path` 设为 `"skills/"`；如果需要不同路径，请直接编辑该文件。`hermes skills tap list` 显示每个 tap 的有效路径。
|
||||
|
||||
#### 直接安装单个 skills（无需添加 tap）
|
||||
|
||||
用户也可以从任何公开 GitHub 仓库安装单个 skill，而无需将整个仓库添加为 tap：
|
||||
|
||||
```bash
|
||||
hermes skills install owner/repo/skills/my-workflow
|
||||
```
|
||||
|
||||
当你想分享一个 skill 而不要求用户订阅你的整个注册表时非常有用。
|
||||
|
||||
#### tap 的信任级别
|
||||
|
||||
新 tap 默认分配 `community` 信任级别。从中安装的 skills 经过标准安全扫描，首次安装时显示第三方警告面板。如果你的组织或广泛受信任的来源应获得更高信任，请将其仓库添加到 `tools/skills_hub.py` 中的 `TRUSTED_REPOS`（需要 Hermes 核心 PR）。
|
||||
|
||||
#### Tap 管理
|
||||
|
||||
```bash
|
||||
hermes skills tap list # show all configured taps
|
||||
hermes skills tap add myorg/skills-repo # add (default path: skills/)
|
||||
hermes skills tap remove myorg/skills-repo # remove
|
||||
```
|
||||
|
||||
在运行中的会话内：
|
||||
|
||||
```
|
||||
/skills tap list
|
||||
/skills tap add myorg/skills-repo
|
||||
/skills tap remove myorg/skills-repo
|
||||
```
|
||||
|
||||
Tap 存储在 `~/.hermes/.hub/taps.json` 中（按需创建）。
|
||||
|
||||
## 捆绑 skill 更新（`hermes skills reset`）
|
||||
|
||||
Hermes 在仓库的 `skills/` 中附带一组捆绑 skills。在安装时以及每次 `hermes update` 时，同步过程会将这些 skills 复制到 `~/.hermes/skills/` 中，并在 `~/.hermes/skills/.bundled_manifest` 记录一个清单，将每个 skill 名称映射到同步时的内容哈希（**origin hash**）。
|
||||
|
||||
每次同步时，Hermes 重新计算本地副本的哈希并与 origin hash 比较：
|
||||
|
||||
- **未更改** → 可以安全拉取上游变更，复制新的捆绑版本，记录新的 origin hash。
|
||||
- **已更改** → 视为**用户修改**并永久跳过，因此你的编辑不会被覆盖。
|
||||
|
||||
这种保护机制很好，但有一个棘手的边缘情况。如果你编辑了一个捆绑 skill，后来想通过从 `~/.hermes/hermes-agent/skills/` 复制粘贴来放弃更改并回到捆绑版本，清单仍然保存着上次成功同步时的*旧* origin hash。你新复制粘贴的内容（当前捆绑哈希）与那个过时的 origin hash 不匹配，因此同步继续将其标记为用户修改。
|
||||
|
||||
`hermes skills reset` 是解决此问题的方法：
|
||||
|
||||
```bash
|
||||
# 安全：清除此 skill 的清单条目。你当前的副本被保留，
|
||||
# 但下次同步会重新以其为基准，使未来的更新正常工作。
|
||||
hermes skills reset google-workspace
|
||||
|
||||
# 完全恢复：同时删除你的本地副本并重新复制当前捆绑版本。
|
||||
# 当你想要恢复原始上游 skill 时使用此选项。
|
||||
hermes skills reset google-workspace --restore
|
||||
|
||||
# 非交互式（例如在脚本或 TUI 模式中）——跳过 --restore 确认。
|
||||
hermes skills reset google-workspace --restore --yes
|
||||
```
|
||||
|
||||
同样的命令也可以作为斜杠命令在聊天中使用：
|
||||
|
||||
```text
|
||||
/skills reset google-workspace
|
||||
/skills reset google-workspace --restore
|
||||
```
|
||||
|
||||
:::note Profiles
|
||||
每个 profile 在其自己的 `HERMES_HOME` 下有自己的 `.bundled_manifest`，因此 `hermes -p coder skills reset <name>` 只影响该 profile。
|
||||
:::
|
||||
|
||||
### 斜杠命令（在聊天中）
|
||||
|
||||
所有相同的命令都可以使用 `/skills` 执行：
|
||||
|
||||
```text
|
||||
/skills browse
|
||||
/skills search react --source skills-sh
|
||||
/skills search https://mintlify.com/docs --source well-known
|
||||
/skills inspect skills-sh/vercel-labs/json-render/json-render-react
|
||||
/skills install openai/skills/skill-creator --force
|
||||
/skills check
|
||||
/skills update
|
||||
/skills reset google-workspace
|
||||
/skills list
|
||||
```
|
||||
|
||||
官方可选 skills 仍使用 `official/security/1password` 和 `official/migration/openclaw-migration` 等标识符。
|
||||
+271
@@ -0,0 +1,271 @@
|
||||
---
|
||||
sidebar_position: 10
|
||||
title: "皮肤与主题"
|
||||
description: "使用内置和用户自定义皮肤定制 Hermes CLI 的外观"
|
||||
---
|
||||
|
||||
# 皮肤与主题
|
||||
|
||||
皮肤控制 Hermes CLI 的**视觉呈现**：横幅颜色、spinner（加载动画）面孔与动词、响应框标签、品牌文本以及工具活动前缀。
|
||||
|
||||
对话风格与视觉风格是两个独立的概念：
|
||||
|
||||
- **Personality（个性）** 改变 agent 的语气和措辞。
|
||||
- **Skin（皮肤）** 改变 CLI 的外观。
|
||||
|
||||
## 切换皮肤
|
||||
|
||||
```bash
|
||||
/skin # show the current skin and list available skins
|
||||
/skin ares # switch to a built-in skin
|
||||
/skin mytheme # switch to a custom skin from ~/.hermes/skins/mytheme.yaml
|
||||
```
|
||||
|
||||
或在 `~/.hermes/config.yaml` 中设置默认皮肤：
|
||||
|
||||
```yaml
|
||||
display:
|
||||
skin: default
|
||||
```
|
||||
|
||||
## 内置皮肤
|
||||
|
||||
| 皮肤 | 描述 | Agent 品牌 | 视觉特征 |
|
||||
|------|------|-----------|---------|
|
||||
| `default` | 经典 Hermes — 金色与 kawaii 风格 | `Hermes Agent` | 暖金色边框，cornsilk 文字，spinner 中的 kawaii 面孔。熟悉的双蛇杖横幅。简洁亲切。 |
|
||||
| `ares` | 战神主题 — 深红与青铜 | `Ares Agent` | 深红色边框配青铜点缀。激进的 spinner 动词（"forging"、"marching"、"tempering steel"）。自定义剑盾 ASCII 艺术横幅。 |
|
||||
| `mono` | 单色 — 简洁灰度 | `Hermes Agent` | 全灰色，无彩色。边框为 `#555555`，文字为 `#c9d1d9`。适合极简终端或录屏场景。 |
|
||||
| `slate` | 冷蓝色 — 面向开发者 | `Hermes Agent` | 皇家蓝边框（`#4169e1`），柔和蓝色文字。沉稳专业。无自定义 spinner，使用默认面孔。 |
|
||||
| `daylight` | 适用于亮色终端的浅色主题，深色文字配冷蓝点缀 | `Hermes Agent` | 专为白色或亮色终端设计。深石板色文字配蓝色边框，浅色状态面板，补全菜单在亮色终端配置下保持清晰可读。 |
|
||||
| `warm-lightmode` | 适用于浅色终端背景的暖棕/金色文字 | `Hermes Agent` | 适合浅色终端的暖羊皮纸色调。深棕色文字配马鞍棕点缀，奶油色状态面板。比 daylight 主题更温暖的大地色系选择。 |
|
||||
| `poseidon` | 海神主题 — 深蓝与海沫绿 | `Poseidon Agent` | 深蓝到海沫绿渐变。海洋主题 spinner（"charting currents"、"sounding the depth"）。三叉戟 ASCII 艺术横幅。 |
|
||||
| `sisyphus` | 西西弗斯主题 — 朴素灰度，彰显坚韧 | `Sisyphus Agent` | 浅灰色配强烈对比。巨石主题 spinner（"pushing uphill"、"resetting the boulder"、"enduring the loop"）。巨石与山丘 ASCII 艺术横幅。 |
|
||||
| `charizard` | 火山主题 — 焦橙与余烬色 | `Charizard Agent` | 暖焦橙到余烬色渐变。火焰主题 spinner（"banking into the draft"、"measuring burn"）。龙剪影 ASCII 艺术横幅。 |
|
||||
|
||||
## 可配置键完整列表
|
||||
|
||||
### 颜色（`colors:`）
|
||||
|
||||
控制 CLI 中所有颜色值。值为十六进制颜色字符串。
|
||||
|
||||
| 键 | 描述 | 默认值（`default` 皮肤） |
|
||||
|----|------|------------------------|
|
||||
| `banner_border` | 启动横幅周围的面板边框 | `#CD7F32`（青铜色） |
|
||||
| `banner_title` | 横幅中的标题文字颜色 | `#FFD700`（金色） |
|
||||
| `banner_accent` | 横幅中的区块标题（Available Tools 等） | `#FFBF00`（琥珀色） |
|
||||
| `banner_dim` | 横幅中的弱化文字（分隔符、次要标签） | `#B8860B`（暗金菊色） |
|
||||
| `banner_text` | 横幅中的正文文字（工具名、技能名） | `#FFF8DC`（玉米丝色） |
|
||||
| `ui_accent` | 通用 UI 强调色（高亮、活动元素） | `#FFBF00` |
|
||||
| `ui_label` | UI 标签与标记 | `#4dd0e1`（青色） |
|
||||
| `ui_ok` | 成功指示器（对勾、完成） | `#4caf50`（绿色） |
|
||||
| `ui_error` | 错误指示器（失败、阻断） | `#ef5350`（红色） |
|
||||
| `ui_warn` | 警告指示器（注意、审批提示） | `#ffa726`（橙色） |
|
||||
| `prompt` | 交互式 prompt（提示符）文字颜色 | `#FFF8DC` |
|
||||
| `input_rule` | 输入区域上方的水平分隔线 | `#CD7F32` |
|
||||
| `response_border` | agent 响应框边框（ANSI 转义） | `#FFD700` |
|
||||
| `session_label` | 会话标签颜色 | `#DAA520` |
|
||||
| `session_border` | 会话 ID 弱化边框颜色 | `#8B8682` |
|
||||
| `status_bar_bg` | TUI 状态/用量栏的背景色 | `#1a1a2e` |
|
||||
| `voice_status_bg` | 语音模式状态徽章的背景色 | `#1a1a2e` |
|
||||
| `selection_bg` | TUI 鼠标选区高亮的背景色。未设置时回退到 `completion_menu_current_bg`。 | `#333355` |
|
||||
| `completion_menu_bg` | 补全菜单列表的背景色 | `#1a1a2e` |
|
||||
| `completion_menu_current_bg` | 当前活动补全行的背景色 | `#333355` |
|
||||
| `completion_menu_meta_bg` | 补全元信息列的背景色 | `#1a1a2e` |
|
||||
| `completion_menu_meta_current_bg` | 当前活动补全元信息列的背景色 | `#333355` |
|
||||
|
||||
### Spinner（`spinner:`）
|
||||
|
||||
控制等待 API 响应时显示的动画 spinner。
|
||||
|
||||
| 键 | 类型 | 描述 | 示例 |
|
||||
|----|------|------|------|
|
||||
| `waiting_faces` | 字符串列表 | 等待 API 响应时循环显示的面孔 | `["(⚔)", "(⛨)", "(▲)"]` |
|
||||
| `thinking_faces` | 字符串列表 | 模型推理期间循环显示的面孔 | `["(⚔)", "(⌁)", "(<>)"]` |
|
||||
| `thinking_verbs` | 字符串列表 | spinner 消息中显示的动词 | `["forging", "plotting", "hammering plans"]` |
|
||||
| `wings` | [左, 右] 对的列表 | spinner 周围的装饰括号 | `[["⟪⚔", "⚔⟫"], ["⟪▲", "▲⟫"]]` |
|
||||
|
||||
当 spinner 值为空时（如 `default` 和 `mono`），将使用 `display.py` 中的硬编码默认值。
|
||||
|
||||
### 品牌（`branding:`）
|
||||
|
||||
CLI 界面中使用的文字字符串。
|
||||
|
||||
| 键 | 描述 | 默认值 |
|
||||
|----|------|--------|
|
||||
| `agent_name` | 横幅标题和状态显示中的名称 | `Hermes Agent` |
|
||||
| `welcome` | CLI 启动时显示的欢迎消息 | `Welcome to Hermes Agent! Type your message or /help for commands.` |
|
||||
| `goodbye` | 退出时显示的消息 | `Goodbye! ⚕` |
|
||||
| `response_label` | 响应框标题上的标签 | ` ⚕ Hermes ` |
|
||||
| `prompt_symbol` | 用户输入 prompt 前的符号（裸 token，渲染器会在后面添加空格） | `❯` |
|
||||
| `help_header` | `/help` 命令输出的标题文字 | `(^_^)? Available Commands` |
|
||||
|
||||
### 其他顶级键
|
||||
|
||||
| 键 | 类型 | 描述 | 默认值 |
|
||||
|----|------|------|--------|
|
||||
| `tool_prefix` | 字符串 | CLI 中工具输出行的前缀字符 | `┊` |
|
||||
| `tool_emojis` | 字典 | 各工具的 emoji 覆盖，用于 spinner 和进度显示（`{tool_name: emoji}`） | `{}` |
|
||||
| `banner_logo` | 字符串 | Rich 标记 ASCII 艺术 logo（替换默认的 HERMES_AGENT 横幅） | `""` |
|
||||
| `banner_hero` | 字符串 | Rich 标记英雄艺术图（替换默认的双蛇杖图案） | `""` |
|
||||
|
||||
## 自定义皮肤
|
||||
|
||||
在 `~/.hermes/skins/` 下创建 YAML 文件。用户皮肤会从内置 `default` 皮肤继承缺失的值，因此只需指定要更改的键。
|
||||
|
||||
### 完整自定义皮肤 YAML 模板
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/skins/mytheme.yaml
|
||||
# Complete skin template — all keys shown. Delete any you don't need;
|
||||
# missing values automatically inherit from the 'default' skin.
|
||||
|
||||
name: mytheme
|
||||
description: My custom theme
|
||||
|
||||
colors:
|
||||
banner_border: "#CD7F32"
|
||||
banner_title: "#FFD700"
|
||||
banner_accent: "#FFBF00"
|
||||
banner_dim: "#B8860B"
|
||||
banner_text: "#FFF8DC"
|
||||
ui_accent: "#FFBF00"
|
||||
ui_label: "#4dd0e1"
|
||||
ui_ok: "#4caf50"
|
||||
ui_error: "#ef5350"
|
||||
ui_warn: "#ffa726"
|
||||
prompt: "#FFF8DC"
|
||||
input_rule: "#CD7F32"
|
||||
response_border: "#FFD700"
|
||||
session_label: "#DAA520"
|
||||
session_border: "#8B8682"
|
||||
status_bar_bg: "#1a1a2e"
|
||||
voice_status_bg: "#1a1a2e"
|
||||
selection_bg: "#333355"
|
||||
completion_menu_bg: "#1a1a2e"
|
||||
completion_menu_current_bg: "#333355"
|
||||
completion_menu_meta_bg: "#1a1a2e"
|
||||
completion_menu_meta_current_bg: "#333355"
|
||||
|
||||
spinner:
|
||||
waiting_faces:
|
||||
- "(⚔)"
|
||||
- "(⛨)"
|
||||
- "(▲)"
|
||||
thinking_faces:
|
||||
- "(⚔)"
|
||||
- "(⌁)"
|
||||
- "(<>)"
|
||||
thinking_verbs:
|
||||
- "processing"
|
||||
- "analyzing"
|
||||
- "computing"
|
||||
- "evaluating"
|
||||
wings:
|
||||
- ["⟪⚡", "⚡⟫"]
|
||||
- ["⟪●", "●⟫"]
|
||||
|
||||
branding:
|
||||
agent_name: "My Agent"
|
||||
welcome: "Welcome to My Agent! Type your message or /help for commands."
|
||||
goodbye: "See you later! ⚡"
|
||||
response_label: " ⚡ My Agent "
|
||||
prompt_symbol: "⚡"
|
||||
help_header: "(⚡) Available Commands"
|
||||
|
||||
tool_prefix: "┊"
|
||||
|
||||
# Per-tool emoji overrides (optional)
|
||||
tool_emojis:
|
||||
terminal: "⚔"
|
||||
web_search: "🔮"
|
||||
read_file: "📄"
|
||||
|
||||
# Custom ASCII art banners (optional, Rich markup supported)
|
||||
# banner_logo: |
|
||||
# [bold #FFD700] MY AGENT [/]
|
||||
# banner_hero: |
|
||||
# [#FFD700] Custom art here [/]
|
||||
```
|
||||
|
||||
### 最简自定义皮肤示例
|
||||
|
||||
由于所有值都继承自 `default`，最简皮肤只需指定要更改的部分：
|
||||
|
||||
```yaml
|
||||
name: cyberpunk
|
||||
description: Neon terminal theme
|
||||
|
||||
colors:
|
||||
banner_border: "#FF00FF"
|
||||
banner_title: "#00FFFF"
|
||||
banner_accent: "#FF1493"
|
||||
|
||||
spinner:
|
||||
thinking_verbs: ["jacking in", "decrypting", "uploading"]
|
||||
wings:
|
||||
- ["⟨⚡", "⚡⟩"]
|
||||
|
||||
branding:
|
||||
agent_name: "Cyber Agent"
|
||||
response_label: " ⚡ Cyber "
|
||||
|
||||
tool_prefix: "▏"
|
||||
```
|
||||
|
||||
## Hermes Mod — 可视化皮肤编辑器
|
||||
|
||||
[Hermes Mod](https://github.com/cocktailpeanut/hermes-mod) 是一个社区构建的 Web UI，用于可视化创建和管理皮肤。无需手写 YAML，提供带实时预览的点击式编辑器。
|
||||
|
||||
|
||||
|
||||
**功能说明：**
|
||||
|
||||
- 列出所有内置和自定义皮肤
|
||||
- 将任意皮肤在可视化编辑器中打开，涵盖所有 Hermes 皮肤字段（颜色、spinner、品牌、工具前缀、工具 emoji）
|
||||
- 根据文字 prompt 生成 `banner_logo` 文字艺术
|
||||
- 将上传的图片（PNG、JPG、GIF、WEBP）转换为 `banner_hero` ASCII 艺术，支持多种渲染风格（盲文点阵、ASCII 字符渐变、方块、点阵）
|
||||
- 直接保存到 `~/.hermes/skins/`
|
||||
- 通过更新 `~/.hermes/config.yaml` 激活皮肤
|
||||
- 显示生成的 YAML 及实时预览
|
||||
|
||||
### 安装
|
||||
|
||||
**方式一 — Pinokio（一键安装）：**
|
||||
|
||||
在 [pinokio.computer](https://pinokio.computer) 上找到并一键安装。
|
||||
|
||||
**方式二 — npx（终端最快方式）：**
|
||||
|
||||
```bash
|
||||
npx -y hermes-mod
|
||||
```
|
||||
|
||||
**方式三 — 手动安装：**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/cocktailpeanut/hermes-mod.git
|
||||
cd hermes-mod/app
|
||||
npm install
|
||||
npm start
|
||||
```
|
||||
|
||||
### 使用方法
|
||||
|
||||
1. 启动应用（通过 Pinokio 或终端）。
|
||||
2. 打开 **Skin Studio**。
|
||||
3. 选择要编辑的内置或自定义皮肤。
|
||||
4. 从文字生成 logo，和/或上传图片作为英雄艺术图。选择渲染风格和宽度。
|
||||
5. 编辑颜色、spinner、品牌及其他字段。
|
||||
6. 点击 **Save** 将皮肤 YAML 写入 `~/.hermes/skins/`。
|
||||
7. 点击 **Activate** 将其设为当前皮肤（更新 `config.yaml` 中的 `display.skin`）。
|
||||
|
||||
Hermes Mod 遵循 `HERMES_HOME` 环境变量，因此也适用于[配置文件](/user-guide/profiles)。
|
||||
|
||||
## 操作说明
|
||||
|
||||
- 内置皮肤从 `hermes_cli/skin_engine.py` 加载。
|
||||
- 未知皮肤自动回退到 `default`。
|
||||
- `/skin` 立即更新当前会话的活动 CLI 主题。
|
||||
- `~/.hermes/skins/` 中的用户皮肤优先于同名内置皮肤。
|
||||
- 通过 `/skin` 切换皮肤仅对当前会话有效。如需永久设为默认皮肤，请在 `config.yaml` 中配置。
|
||||
- `banner_logo` 和 `banner_hero` 字段支持 Rich 控制台标记（例如 `[bold #FF0000]text[/]`），可用于彩色 ASCII 艺术。
|
||||
+279
@@ -0,0 +1,279 @@
|
||||
# Spotify
|
||||
|
||||
Hermes 可以直接控制 Spotify——播放、队列、搜索、播放列表、已保存的曲目/专辑以及收听历史——通过 Spotify 官方 Web API 配合 PKCE OAuth 实现。Token（令牌）存储在 `~/.hermes/auth.json` 中，遇到 401 时自动刷新；每台机器只需登录一次。
|
||||
|
||||
与 Hermes 内置的 OAuth 集成（Google、GitHub Copilot、Codex）不同，Spotify 要求每位用户自行注册一个轻量级开发者应用。Spotify 不允许第三方发布可供所有人使用的公共 OAuth 应用。整个过程大约需要两分钟，`hermes auth spotify` 会全程引导你完成。
|
||||
|
||||
## 前提条件
|
||||
|
||||
- 一个 Spotify 账号。**免费版**可使用搜索、播放列表、音乐库和活动工具。**Premium 版**才能使用播放控制（播放、暂停、跳曲、定位、音量、添加队列、切换设备）。
|
||||
- 已安装并运行 Hermes Agent。
|
||||
- 使用播放工具时：需要一个**活跃的 Spotify Connect 设备**——至少一台设备（手机、桌面端、网页播放器、音箱）上必须打开 Spotify 应用，Web API 才有对象可控制。若无活跃设备，将收到 `403 Forbidden` 并提示"no active device"；在任意设备上打开 Spotify 后重试即可。
|
||||
|
||||
## 设置
|
||||
|
||||
### 一键完成：`hermes tools` 或首次运行设置
|
||||
|
||||
最快捷的方式。运行：
|
||||
|
||||
```bash
|
||||
hermes tools
|
||||
```
|
||||
|
||||
滚动到 `🎵 Spotify`，按空格键启用，再按 `s` 保存。同样的开关也可在首次运行 `hermes setup` / `hermes setup tools` 流程中找到。Spotify 默认为可选启用，在此处启用会触发与 `hermes tools` 相同的提供商感知配置流程。
|
||||
|
||||
Hermes 会直接进入 OAuth 流程——如果你还没有 Spotify 应用，它会内联引导你创建一个。完成后，工具集即被启用并完成认证，一步到位。
|
||||
|
||||
如果你希望分步操作（或稍后重新认证），请使用下方的两步流程。
|
||||
|
||||
### 两步流程
|
||||
|
||||
#### 1. 启用工具集
|
||||
|
||||
```bash
|
||||
hermes tools
|
||||
```
|
||||
|
||||
启用 `🎵 Spotify`，保存，当内联向导弹出时关闭它（Ctrl+C）。工具集保持开启状态，仅跳过认证步骤。
|
||||
|
||||
#### 2. 运行登录向导
|
||||
|
||||
```bash
|
||||
hermes auth spotify
|
||||
```
|
||||
|
||||
7 个 Spotify 工具只有在完成第 1 步后才会出现在 agent 的工具集中——它们默认关闭，以避免不需要它们的用户在每次 API 调用时额外传输工具 schema。
|
||||
|
||||
若未设置 `HERMES_SPOTIFY_CLIENT_ID`，Hermes 会内联引导你完成应用注册：
|
||||
|
||||
1. 在浏览器中打开 `https://developer.spotify.com/dashboard`
|
||||
2. 打印需要粘贴到 Spotify "Create app" 表单中的确切值
|
||||
3. 提示你输入获得的 Client ID
|
||||
4. 将其保存到 `~/.hermes/.env`，后续运行时跳过此步骤
|
||||
5. 直接进入 OAuth 授权流程
|
||||
|
||||
授权完成后，token 将写入 `~/.hermes/auth.json` 的 `providers.spotify` 下。当前推理提供商不会改变——Spotify 认证与你的 LLM 提供商无关。
|
||||
|
||||
### 创建 Spotify 应用（向导所需内容）
|
||||
|
||||
当 dashboard 打开后，点击 **Create app** 并填写：
|
||||
|
||||
| 字段 | 值 |
|
||||
|-------|-------|
|
||||
| App name | 任意（例如 `hermes-agent`） |
|
||||
| App description | 任意（例如 `personal Hermes integration`） |
|
||||
| Website | 留空 |
|
||||
| Redirect URI | `http://127.0.0.1:43827/spotify/callback` |
|
||||
| Which API/SDKs? | 勾选 **Web API** |
|
||||
|
||||
同意条款并点击 **Save**。在下一页点击 **Settings** → 复制 **Client ID** 并粘贴到 Hermes 提示中。这是 Hermes 唯一需要的值——PKCE 不使用 client secret。
|
||||
|
||||
### 通过 SSH / 在无头环境中运行
|
||||
|
||||
若设置了 `SSH_CLIENT` 或 `SSH_TTY`，Hermes 在向导和 OAuth 步骤中均会跳过自动打开浏览器。复制 Hermes 打印的 dashboard URL 和授权 URL，在本地机器的浏览器中打开，然后正常操作——本地 HTTP 监听器仍在远程主机的 `43827` 端口运行。你的笔记本浏览器无法直接访问远程回环地址，需要通过 SSH 本地端口转发：
|
||||
|
||||
```bash
|
||||
ssh -N -L 43827:127.0.0.1:43827 user@remote-host
|
||||
```
|
||||
|
||||
关于跳板机/堡垒机设置及其他注意事项（mosh、tmux、端口冲突），请参阅 [OAuth over SSH / Remote Hosts](../../guides/oauth-over-ssh.md)。
|
||||
|
||||
## 验证
|
||||
|
||||
```bash
|
||||
hermes auth status spotify
|
||||
```
|
||||
|
||||
显示 token 是否存在以及 access token 的过期时间。刷新是自动的：当任何 Spotify API 调用返回 401 时，客户端会用 refresh token 换取新 token 并重试一次。Refresh token 在 Hermes 重启后仍然有效，只有在你的 Spotify 账号设置中撤销该应用，或运行 `hermes auth logout spotify` 后才需要重新认证。
|
||||
|
||||
## 使用方法
|
||||
|
||||
登录后，agent 可访问 7 个 Spotify 工具。你用自然语言与 agent 交流——它会选择正确的工具和操作。为获得最佳效果，agent 会加载一个配套技能，教授规范的使用模式（先搜索再播放、何时不需要预先调用 `get_state` 等）。
|
||||
|
||||
```
|
||||
> play some miles davis
|
||||
> what am I listening to
|
||||
> add this track to my Late Night Jazz playlist
|
||||
> skip to the next song
|
||||
> make a new playlist called "Focus 2026" and add the last three songs I played
|
||||
> which of my saved albums are by Radiohead
|
||||
> search for acoustic covers of Blackbird
|
||||
> transfer playback to my kitchen speaker
|
||||
```
|
||||
|
||||
### 工具参考
|
||||
|
||||
所有会修改播放状态的操作都接受可选的 `device_id` 参数以指定目标设备。若省略，Spotify 将使用当前活跃设备。
|
||||
|
||||
#### `spotify_playback`
|
||||
控制和查看播放状态，以及获取最近播放历史。
|
||||
|
||||
| 操作 | 用途 | 需要 Premium？ |
|
||||
|--------|---------|----------|
|
||||
| `get_state` | 完整播放状态（曲目、设备、进度、随机/循环） | 否 |
|
||||
| `get_currently_playing` | 仅当前曲目（204 时返回空——见下文） | 否 |
|
||||
| `play` | 开始/恢复播放。可选：`context_uri`、`uris`、`offset`、`position_ms` | 是 |
|
||||
| `pause` | 暂停播放 | 是 |
|
||||
| `next` / `previous` | 跳曲 | 是 |
|
||||
| `seek` | 跳转到 `position_ms` | 是 |
|
||||
| `set_repeat` | `state` = `track` / `context` / `off` | 是 |
|
||||
| `set_shuffle` | `state` = `true` / `false` | 是 |
|
||||
| `set_volume` | `volume_percent` = 0-100 | 是 |
|
||||
| `recently_played` | 最近播放的曲目。可选 `limit`、`before`、`after`（Unix 毫秒） | 否 |
|
||||
|
||||
#### `spotify_devices`
|
||||
| 操作 | 用途 |
|
||||
|--------|---------|
|
||||
| `list` | 你账号下所有可见的 Spotify Connect 设备 |
|
||||
| `transfer` | 将播放切换到 `device_id`。可选 `play: true` 在切换时立即开始播放 |
|
||||
|
||||
### Home Assistant 管理的音箱
|
||||
|
||||
如果 Home Assistant 管理的音箱本身支持 Spotify Connect（例如 Sonos、Echo、Nest 或其他支持 Connect 的音箱），只要 Spotify 能识别它们，它们就会自动出现在 `spotify_devices list` 中。Hermes 不需要 Home Assistant ↔ Spotify 桥接——Spotify 原生处理设备路由。
|
||||
|
||||
通过音箱的显示名称让 Hermes 切换播放（例如"transfer Spotify to the kitchen speaker"），或在脚本中调用 `spotify_devices list` 获取确切的 `device_id` 后传给 `spotify_devices transfer`。若音箱未出现，请在 Spotify 应用或音箱的 Spotify 集成中打开一次，让 Spotify 将其注册为活跃的 Connect 目标。
|
||||
|
||||
#### `spotify_queue`
|
||||
| 操作 | 用途 | 需要 Premium？ |
|
||||
|--------|---------|----------|
|
||||
| `get` | 当前队列中的曲目 | 否 |
|
||||
| `add` | 将 `uri` 追加到队列 | 是 |
|
||||
|
||||
#### `spotify_search`
|
||||
搜索曲库。`query` 为必填项。可选：`types`（`track` / `album` / `artist` / `playlist` / `show` / `episode` 的数组）、`limit`、`offset`、`market`。
|
||||
|
||||
#### `spotify_playlists`
|
||||
| 操作 | 用途 | 必填参数 |
|
||||
|--------|---------|---------------|
|
||||
| `list` | 用户的播放列表 | — |
|
||||
| `get` | 单个播放列表及其曲目 | `playlist_id` |
|
||||
| `create` | 新建播放列表 | `name`（可选 `description`、`public`、`collaborative`） |
|
||||
| `add_items` | 添加曲目 | `playlist_id`、`uris`（可选 `position`） |
|
||||
| `remove_items` | 移除曲目 | `playlist_id`、`uris`（可选 `snapshot_id`） |
|
||||
| `update_details` | 重命名/编辑 | `playlist_id` + `name`、`description`、`public`、`collaborative` 中的任意项 |
|
||||
|
||||
#### `spotify_albums`
|
||||
| 操作 | 用途 | 必填参数 |
|
||||
|--------|---------|---------------|
|
||||
| `get` | 专辑元数据 | `album_id` |
|
||||
| `tracks` | 专辑曲目列表 | `album_id` |
|
||||
|
||||
#### `spotify_library`
|
||||
统一访问已保存的曲目和专辑。通过 `kind` 参数选择集合类型。
|
||||
|
||||
| 操作 | 用途 |
|
||||
|--------|---------|
|
||||
| `list` | 分页列出音乐库 |
|
||||
| `save` | 将 `ids` / `uris` 添加到音乐库 |
|
||||
| `remove` | 从音乐库移除 `ids` / `uris` |
|
||||
|
||||
必填：`kind` = `tracks` 或 `albums`，以及 `action`。
|
||||
|
||||
### 功能矩阵：免费版 vs Premium 版
|
||||
|
||||
只读工具在免费账号上可用。任何修改播放状态或队列的操作都需要 Premium。
|
||||
|
||||
| 免费版可用 | 需要 Premium |
|
||||
|---------------|------------------|
|
||||
| `spotify_search`（全部） | `spotify_playback` — play、pause、next、previous、seek、set_repeat、set_shuffle、set_volume |
|
||||
| `spotify_playback` — get_state、get_currently_playing、recently_played | `spotify_queue` — add |
|
||||
| `spotify_devices` — list | `spotify_devices` — transfer |
|
||||
| `spotify_queue` — get | |
|
||||
| `spotify_playlists`（全部） | |
|
||||
| `spotify_albums`（全部） | |
|
||||
| `spotify_library`（全部） | |
|
||||
|
||||
## 定时任务：Spotify + cron
|
||||
|
||||
由于 Spotify 工具是普通的 Hermes 工具，在 Hermes 会话中运行的 cron 任务可以按任意计划触发播放，无需编写额外代码。
|
||||
|
||||
### 早晨唤醒播放列表
|
||||
|
||||
```bash
|
||||
hermes cron add \
|
||||
--name "morning-commute" \
|
||||
"0 7 * * 1-5" \
|
||||
"Transfer playback to my kitchen speaker and start my 'Morning Commute' playlist. Volume to 40. Shuffle on."
|
||||
```
|
||||
|
||||
每个工作日早上 7 点发生的事情：
|
||||
1. Cron 启动一个无头 Hermes 会话。
|
||||
2. Agent 读取 prompt（提示词），调用 `spotify_devices list` 按名称找到"kitchen speaker"，然后依次调用 `spotify_devices transfer` → `spotify_playback set_volume` → `spotify_playback set_shuffle` → `spotify_search` + `spotify_playback play`。
|
||||
3. 音乐在目标音箱上开始播放。总计：一个会话，几次工具调用，无需人工干预。
|
||||
|
||||
### 夜间收尾
|
||||
|
||||
```bash
|
||||
hermes cron add \
|
||||
--name "wind-down" \
|
||||
"30 22 * * *" \
|
||||
"Pause Spotify. Then set volume to 20 so it's quiet when I start it again tomorrow."
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- **cron 触发时必须存在活跃设备。** 若没有 Spotify 客户端在运行（手机/桌面端/Connect 音箱），播放操作将返回 `403 no active device`。对于早晨播放列表，建议指定一个始终开机的设备（Sonos、Echo、智能音箱），而非手机。
|
||||
- **任何修改播放状态的操作都需要 Premium**——播放、暂停、跳曲、音量、切换设备。只读 cron 任务（例如定时"发送我最近播放的曲目"）在免费版上可正常使用。
|
||||
- **cron agent 继承你的活跃工具集。** Spotify 必须在 `hermes tools` 中启用，cron 会话才能看到 Spotify 工具。
|
||||
- **Cron 任务以 `skip_memory=True` 运行**，不会写入你的记忆存储。
|
||||
|
||||
完整 cron 参考：[Cron Jobs](./cron)。
|
||||
|
||||
## 退出登录
|
||||
|
||||
```bash
|
||||
hermes auth logout spotify
|
||||
```
|
||||
|
||||
从 `~/.hermes/auth.json` 中移除 token。若还需清除应用配置，请从 `~/.hermes/.env` 中删除 `HERMES_SPOTIFY_CLIENT_ID`（以及 `HERMES_SPOTIFY_REDIRECT_URI`，如果你设置了的话），或重新运行向导。
|
||||
|
||||
若要在 Spotify 侧撤销应用，请访问[已连接到你账号的应用](https://www.spotify.com/account/apps/)并点击 **REMOVE ACCESS**。
|
||||
|
||||
## 故障排查
|
||||
|
||||
**`403 Forbidden — Player command failed: No active device found`** — 你需要在至少一台设备上运行 Spotify。在手机、桌面端或网页播放器上打开 Spotify 应用，随便播放一首曲目以注册设备，然后重试。`spotify_devices list` 可显示当前可见的设备。
|
||||
|
||||
**`403 Forbidden — Premium required`** — 你使用的是免费账号，但尝试执行需要 Premium 的播放操作。请参阅上方的功能矩阵。
|
||||
|
||||
**`get_currently_playing` 返回 `204 No Content`** — 当前所有设备上均无内容播放。这是 Spotify 的正常响应，不是错误；Hermes 将其呈现为说明性的空结果（`is_playing: false`）。
|
||||
|
||||
**`INVALID_CLIENT: Invalid redirect URI`** — 你的 Spotify 应用设置中的 redirect URI 与 Hermes 使用的不匹配。默认值为 `http://127.0.0.1:43827/spotify/callback`。请将其添加到应用的允许 redirect URI 列表中，或在 `~/.hermes/.env` 中将 `HERMES_SPOTIFY_REDIRECT_URI` 设置为你注册的值。
|
||||
|
||||
**`429 Too Many Requests`** — Spotify 的速率限制。Hermes 会返回友好的错误提示；等待一分钟后重试。若持续出现，你可能在脚本中运行了紧密循环——Spotify 的配额大约每 30 秒重置一次。
|
||||
|
||||
**`401 Unauthorized` 持续出现** — 你的 refresh token 已被撤销（通常是因为你从账号中移除了该应用，或应用被删除）。重新运行 `hermes auth spotify`。
|
||||
|
||||
**向导未打开浏览器** — 若你通过 SSH 连接或在没有显示器的容器中运行，Hermes 会检测到并跳过自动打开。复制它打印的 dashboard URL 并手动打开。
|
||||
|
||||
## 进阶：自定义 scope
|
||||
|
||||
默认情况下，Hermes 会请求所有已发布工具所需的 scope。若需限制访问权限，可覆盖默认值：
|
||||
|
||||
```bash
|
||||
hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"
|
||||
```
|
||||
|
||||
Scope 参考：[Spotify Web API scopes](https://developer.spotify.com/documentation/web-api/concepts/scopes)。若请求的 scope 少于某个工具所需，该工具的调用将以 403 失败。
|
||||
|
||||
## 进阶：自定义 client ID / redirect URI
|
||||
|
||||
```bash
|
||||
hermes auth spotify --client-id <id> --redirect-uri http://localhost:3000/callback
|
||||
```
|
||||
|
||||
或在 `~/.hermes/.env` 中永久设置：
|
||||
|
||||
```
|
||||
HERMES_SPOTIFY_CLIENT_ID=<your_id>
|
||||
HERMES_SPOTIFY_REDIRECT_URI=http://localhost:3000/callback
|
||||
```
|
||||
|
||||
Redirect URI 必须在你的 Spotify 应用设置中加入白名单。默认值适用于绝大多数情况——只有在 43827 端口被占用时才需要更改。
|
||||
|
||||
## 文件位置
|
||||
|
||||
| 文件 | 内容 |
|
||||
|------|----------|
|
||||
| `~/.hermes/auth.json` → `providers.spotify` | access token、refresh token、过期时间、scope、redirect URI |
|
||||
| `~/.hermes/.env` | `HERMES_SPOTIFY_CLIENT_ID`，可选 `HERMES_SPOTIFY_REDIRECT_URI` |
|
||||
| Spotify 应用 | 由你在 [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard) 管理；包含 Client ID 和 redirect URI 白名单 |
|
||||
+163
@@ -0,0 +1,163 @@
|
||||
---
|
||||
sidebar_position: 15
|
||||
title: "订阅代理"
|
||||
description: "将你的 Nous Portal 订阅（或其他 OAuth 提供商）用作外部应用的 OpenAI 兼容端点"
|
||||
---
|
||||
|
||||
# 订阅代理
|
||||
|
||||
订阅代理是一个本地 HTTP 服务器，让外部应用——OpenViking、Karakeep、Open WebUI，以及任何支持 OpenAI 兼容聊天补全（chat completions）的应用——能够将你的 Hermes 托管提供商订阅用作其 LLM 端点。代理会自动附加正确的凭据（并在需要时自动刷新），因此应用无需静态 API 密钥。
|
||||
|
||||
这与 [API 服务器](./api-server.md) 不同：
|
||||
|
||||
| | API 服务器 | 订阅代理 |
|
||||
|---|---|---|
|
||||
| 服务内容 | 你的 Agent（完整工具集、记忆、技能） | 原始模型推理 |
|
||||
| 使用场景 | "将 Hermes 用作聊天后端" | "从其他应用使用我的 Portal 订阅" |
|
||||
| 认证 | 你的 `API_SERVER_KEY` | 任意 bearer（代理附加真实凭据） |
|
||||
| 工具调用 | 是——Agent 执行工具 | 否——仅透传 |
|
||||
|
||||
当你需要将 **Agent** 作为后端时，使用 API 服务器。当你只需要通过订阅访问**模型**时，使用代理。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 登录你的提供商（仅需一次）
|
||||
|
||||
```bash
|
||||
hermes portal
|
||||
```
|
||||
|
||||
这会打开浏览器进行 Nous Portal OAuth 流程。Hermes 将刷新令牌存储在 `~/.hermes/auth.json` 中——与所有 Hermes 提供商登录信息存放在同一位置。
|
||||
|
||||
### 2. 启动代理
|
||||
|
||||
```bash
|
||||
hermes proxy start
|
||||
```
|
||||
|
||||
```
|
||||
Starting Hermes proxy for Nous Portal
|
||||
Listening on: http://127.0.0.1:8645/v1
|
||||
Forwarding to: (resolved per-request from your subscription)
|
||||
Use any bearer token in the client — the proxy attaches your real credential.
|
||||
```
|
||||
|
||||
保持在前台运行。如需在注销后继续运行，请使用 `tmux`、`nohup` 或 systemd 单元。
|
||||
|
||||
### 3. 将你的应用指向代理
|
||||
|
||||
任何 OpenAI 兼容应用的配置都使用相同的三元组：
|
||||
|
||||
```
|
||||
Base URL: http://127.0.0.1:8645/v1
|
||||
API key: 任意值（例如 "sk-unused"）
|
||||
Model: Hermes-4-70B # 或 Hermes-4.3-36B、Hermes-4-405B
|
||||
```
|
||||
|
||||
代理会忽略来自你应用的 `Authorization` 请求头，并将你真实的 Portal 凭据附加到上游请求中。当 bearer 令牌临近过期时，刷新会自动进行。
|
||||
|
||||
## 可用提供商
|
||||
|
||||
```bash
|
||||
hermes proxy providers
|
||||
```
|
||||
|
||||
当前已内置：`nous`（Nous Portal）。更多 OAuth 提供商可通过在 `hermes_cli/proxy/adapters/` 中实现 `UpstreamAdapter` 接口来添加。
|
||||
|
||||
## 检查状态
|
||||
|
||||
```bash
|
||||
hermes proxy status
|
||||
```
|
||||
|
||||
```
|
||||
Hermes proxy upstream adapters
|
||||
|
||||
[nous ] Nous Portal — ready (bearer expires 2026-05-15T06:43:21Z)
|
||||
```
|
||||
|
||||
如果显示 `not logged in`，请运行 `hermes portal`。如果显示 `credentials need attention`，说明你的刷新令牌已被撤销（较少见——通常发生在你从 Portal Web UI 退出登录时）——重新运行 `hermes portal` 即可。
|
||||
|
||||
## 允许的路径
|
||||
|
||||
代理仅转发上游实际提供的路径。对于 Nous Portal：
|
||||
|
||||
| 路径 | 用途 |
|
||||
|------|---------|
|
||||
| `/v1/chat/completions` | 聊天补全（流式与非流式） |
|
||||
| `/v1/completions` | 旧版文本补全 |
|
||||
| `/v1/embeddings` | Embeddings（嵌入） |
|
||||
| `/v1/models` | 模型列表 |
|
||||
|
||||
其他路径（`/v1/images/generations`、`/v1/audio/speech` 等）将返回 404，并附带明确的错误信息指向允许的路径。这可防止游离客户端向上游发送异常请求。
|
||||
|
||||
## 配置 OpenViking 使用 Portal
|
||||
|
||||
[OpenViking](https://github.com/volcengine/OpenViking) 是一个上下文数据库，需要 LLM 提供商来支持其 VLM（用于提取记忆的视觉/语言模型）和 embedding 模型。通过代理，你可以将其 `vlm.api_base` 指向本地代理：
|
||||
|
||||
编辑 `~/.openviking/ov.conf`：
|
||||
|
||||
```json
|
||||
{
|
||||
"vlm": {
|
||||
"provider": "openai",
|
||||
"model": "Hermes-4-70B",
|
||||
"api_base": "http://127.0.0.1:8645/v1",
|
||||
"api_key": "unused-proxy-attaches-real-creds"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
然后在终端中与 `openviking-server` 一起启动代理：
|
||||
|
||||
```bash
|
||||
# 终端 1
|
||||
hermes proxy start
|
||||
|
||||
# 终端 2
|
||||
openviking-server
|
||||
```
|
||||
|
||||
OpenViking 的 VLM 调用现在将通过你的 Portal 订阅进行。Embedding 模型侧仍需要自己的提供商——Portal 确实提供 `/v1/embeddings`，但模型选择取决于你的套餐所支持的内容；请查看 `portal.nousresearch.com/models`。
|
||||
|
||||
## 配置 Karakeep（或任何书签/摘要应用）
|
||||
|
||||
[Karakeep](https://karakeep.app/) 使用 OpenAI 兼容 API 进行书签摘要。在其配置中：
|
||||
|
||||
```bash
|
||||
# Karakeep .env
|
||||
OPENAI_API_BASE_URL=http://127.0.0.1:8645/v1
|
||||
OPENAI_API_KEY=any-non-empty-string
|
||||
INFERENCE_TEXT_MODEL=Hermes-4-70B
|
||||
```
|
||||
|
||||
同样的方式适用于 Open WebUI、LobeChat、NextChat 或任何其他 OpenAI 兼容客户端。
|
||||
|
||||
## 在局域网上暴露
|
||||
|
||||
默认情况下，代理绑定 `127.0.0.1`（仅限本机）。若要让网络中的其他机器使用：
|
||||
|
||||
```bash
|
||||
hermes proxy start --host 0.0.0.0 --port 8645
|
||||
```
|
||||
|
||||
⚠ **注意：** 你网络中的任何人现在都可以使用你的 Portal 订阅。代理本身没有认证机制——它接受任意 bearer。如果你将其暴露在可信网络之外，请使用防火墙、VPN 或带有适当认证的反向代理。
|
||||
|
||||
## 速率限制
|
||||
|
||||
你的 Portal 套餐的 RPM/TPM 限制适用于整个代理。代理不进行扇出或连接池——它是单个 bearer，使用你的完整订阅配额。请在 [portal.nousresearch.com](https://portal.nousresearch.com) 监控使用情况。
|
||||
|
||||
## 架构
|
||||
|
||||
代理设计上尽量精简。每个请求的处理流程：
|
||||
|
||||
1. 从你的应用接收 `POST /v1/chat/completions`
|
||||
2. 查找适配器的当前凭据（如临近过期则刷新）
|
||||
3. 原样转发请求体，附加 `Authorization: Bearer <minted-key>`
|
||||
4. 将响应原样流式返回（SSE 保持不变）
|
||||
|
||||
无转换。不记录请求体。无 Agent 循环。代理是一个附加凭据的透传通道。
|
||||
|
||||
## 未来：更多 OAuth 提供商
|
||||
|
||||
适配器系统是可插拔的。添加新提供商（例如 HuggingFace、GitHub Copilot 的聊天端点、通过 OAuth 接入的 Anthropic）需要在 `hermes_cli/proxy/adapters/<provider>.py` 中实现 `UpstreamAdapter`，并在 `adapters/__init__.py` 中注册。协议层面不兼容 OpenAI 的提供商（例如 Anthropic Messages API）需要额外的转换层，这超出了当前版本的范围。
|
||||
+187
@@ -0,0 +1,187 @@
|
||||
---
|
||||
title: "Nous Tool Gateway（工具网关）"
|
||||
description: "通过 Nous 订阅统一使用网页搜索、文生图、语音合成与浏览器自动化，无需单独申请 Firecrawl、FAL、OpenAI、Browser Use 等 API Key"
|
||||
sidebar_label: "Tool Gateway"
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Nous Tool Gateway（工具网关）
|
||||
|
||||
:::tip 快速开始
|
||||
Tool Gateway 包含在付费 Nous Portal 订阅中。**[管理订阅 →](https://portal.nousresearch.com/manage-subscription)**
|
||||
:::
|
||||
|
||||
**Tool Gateway** 让已付费的 [Nous Portal](https://portal.nousresearch.com) 用户通过同一份订阅，直接使用网页搜索、文生图、语音合成（TTS）与浏览器自动化，而**不必**再分别注册 Firecrawl、FAL、OpenAI、Browser Use 等服务的 API Key。
|
||||
|
||||
## 包含能力
|
||||
|
||||
| 工具 | 作用 | 若不用网关，可改用 |
|
||||
|------|------|---------------------|
|
||||
| **网页搜索与抓取** | 通过 Firecrawl 搜索并抽取页面内容 | `FIRECRAWL_API_KEY`、`EXA_API_KEY`、`PARALLEL_API_KEY`、`TAVILY_API_KEY` |
|
||||
| **文生图** | 通过 FAL 生成图像（8 个模型：FLUX 2 Klein/Pro、GPT-Image、Nano Banana Pro、Ideogram、Recraft V4 Pro、Qwen、Z-Image） | `FAL_KEY` |
|
||||
| **语音合成** | 通过 OpenAI TTS 将文字转为语音 | `VOICE_TOOLS_OPENAI_KEY`、`ELEVENLABS_API_KEY` |
|
||||
| **浏览器自动化** | 通过 Browser Use 控制云端浏览器 | `BROWSER_USE_API_KEY`、`BROWSERBASE_API_KEY` |
|
||||
|
||||
上述四类能力均计入 Nous 订阅计费。你可以按需组合——例如网页与文生图走网关，TTS 仍使用自己的 ElevenLabs Key。
|
||||
|
||||
## 资格与账号
|
||||
|
||||
Tool Gateway 仅对 **[付费](https://portal.nousresearch.com/manage-subscription)** Nous Portal 订阅开放；免费档不可用——请 [升级订阅](https://portal.nousresearch.com/manage-subscription) 后解锁。
|
||||
|
||||
检查当前状态：
|
||||
|
||||
```bash
|
||||
hermes status
|
||||
```
|
||||
|
||||
在输出中找到 **Nous Tool Gateway** 小节：会标明哪些工具经订阅网关启用、哪些使用直连 Key、哪些尚未配置。
|
||||
|
||||
## 如何启用 Tool Gateway
|
||||
|
||||
### 在模型配置流程中
|
||||
|
||||
运行 `hermes model` 并选择 Nous Portal 作为提供商时，Hermes 会主动询问是否启用 Tool Gateway：
|
||||
|
||||
```
|
||||
Your Nous subscription includes the Tool Gateway.
|
||||
|
||||
The Tool Gateway gives you access to web search, image generation,
|
||||
text-to-speech, and browser automation through your Nous subscription.
|
||||
No need to sign up for separate API keys — just pick the tools you want.
|
||||
|
||||
○ Web search & extract (Firecrawl) — not configured
|
||||
○ Image generation (FAL) — not configured
|
||||
○ Text-to-speech (OpenAI TTS) — not configured
|
||||
○ Browser automation (Browser Use) — not configured
|
||||
|
||||
● Enable Tool Gateway
|
||||
○ Skip
|
||||
```
|
||||
|
||||
选择 **Enable Tool Gateway** 即可。
|
||||
|
||||
若 `.env` 中已有部分直连 API Key，提示会相应变化：可为全部工具启用网关（直连 Key 仍保留在 `.env` 但运行时不用）、仅为未配置项启用，或完全跳过。
|
||||
|
||||
### 通过 `hermes tools`
|
||||
|
||||
也可在交互式工具配置中逐项启用：
|
||||
|
||||
```bash
|
||||
hermes tools
|
||||
```
|
||||
|
||||
选择工具类别（Web、Browser、Image Generation、TTS），再将提供商选为 **Nous Subscription**。这会在配置里把对应工具的 `use_gateway` 设为 `true`。
|
||||
|
||||
### 手动编辑配置
|
||||
|
||||
在 `~/.hermes/config.yaml` 中直接设置 `use_gateway`：
|
||||
|
||||
```yaml
|
||||
web:
|
||||
backend: firecrawl
|
||||
use_gateway: true
|
||||
|
||||
image_gen:
|
||||
use_gateway: true
|
||||
|
||||
tts:
|
||||
provider: openai
|
||||
use_gateway: true
|
||||
|
||||
browser:
|
||||
cloud_provider: browser-use
|
||||
use_gateway: true
|
||||
```
|
||||
|
||||
## 工作原理
|
||||
|
||||
当某工具的 `use_gateway: true` 时，运行时会把 API 调用路由到 Nous Tool Gateway，而不是使用直连 Key：
|
||||
|
||||
1. **网页工具** — `web_search` / `web_extract` 走网关的 Firecrawl 端点
|
||||
2. **文生图** — `image_generate` 走网关的 FAL 端点
|
||||
3. **TTS** — `text_to_speech` 走网关的 OpenAI Audio 端点
|
||||
4. **浏览器** — `browser_navigate` 等走网关的 Browser Use 端点
|
||||
|
||||
网关使用 Nous Portal 凭据认证（在 `hermes model` 完成后写入 `~/.hermes/auth.json`）。
|
||||
|
||||
### 优先级
|
||||
|
||||
每个工具都会先看 `use_gateway`：
|
||||
|
||||
- **`use_gateway: true`** → 强制走网关，即使 `.env` 里仍有直连 Key
|
||||
- **`use_gateway: false`**（或未设置）→ 若有直连 Key 则优先直连；仅在没有直连凭据时才回退到网关
|
||||
|
||||
因此你可以在网关与直连之间切换，而无需删除 `.env` 中的旧 Key。
|
||||
|
||||
## 切回直连 Key
|
||||
|
||||
对单个工具停用网关：
|
||||
|
||||
```bash
|
||||
hermes tools # 选择该工具 → 选直连提供商
|
||||
```
|
||||
|
||||
或在配置中设 `use_gateway: false`：
|
||||
|
||||
```yaml
|
||||
web:
|
||||
backend: firecrawl
|
||||
use_gateway: false # 此时使用 .env 中的 FIRECRAWL_API_KEY
|
||||
```
|
||||
|
||||
在 `hermes tools` 中选择非网关提供商时，`use_gateway` 会自动设为 `false`，避免配置自相矛盾。
|
||||
|
||||
## 查看状态
|
||||
|
||||
```bash
|
||||
hermes status
|
||||
```
|
||||
|
||||
**Nous Tool Gateway** 小节示例：
|
||||
|
||||
```
|
||||
◆ Nous Tool Gateway
|
||||
Nous Portal ✓ managed tools available
|
||||
Web tools ✓ active via Nous subscription
|
||||
Image gen ✓ active via Nous subscription
|
||||
TTS ✓ active via Nous subscription
|
||||
Browser ○ active via Browser Use key
|
||||
Modal ○ available via subscription (optional)
|
||||
```
|
||||
|
||||
标记为 “active via Nous subscription” 的即经网关路由；带自有 Key 的会显示当前激活的提供商。
|
||||
|
||||
## 进阶：自建网关
|
||||
|
||||
若使用自建或自定义网关，可在 `~/.hermes/.env` 中用环境变量覆盖端点：
|
||||
|
||||
```bash
|
||||
TOOL_GATEWAY_DOMAIN=nousresearch.com # 网关路由基础域名
|
||||
TOOL_GATEWAY_SCHEME=https # http 或 https（默认 https）
|
||||
TOOL_GATEWAY_USER_TOKEN=your-token # 鉴权 Token（通常由程序自动填充）
|
||||
FIRECRAWL_GATEWAY_URL=https://... # 单独覆盖 Firecrawl 端点
|
||||
```
|
||||
|
||||
这些变量与订阅状态无关，始终可在配置中看到，便于自建基础设施。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 需要删掉已有的 API Key 吗？
|
||||
|
||||
不需要。`use_gateway: true` 时运行时会跳过直连 Key 并走网关；Key 仍保留在 `.env`。之后若关闭网关，会自动恢复使用直连 Key。
|
||||
|
||||
### 能否部分工具走网关、部分走直连？
|
||||
|
||||
可以。`use_gateway` 按工具独立配置。例如：网页与文生图走网关，TTS 用 ElevenLabs，浏览器用 Browserbase。
|
||||
|
||||
### 订阅到期会怎样？
|
||||
|
||||
经网关路由的工具会停止工作，直到你 [续订](https://portal.nousresearch.com/manage-subscription) 或通过 `hermes tools` 改回直连 Key。
|
||||
|
||||
### 与「消息网关」（各聊天平台）是否冲突？
|
||||
|
||||
不冲突。Tool Gateway 作用于**工具运行时**的 API 路由，与 CLI、Telegram、Discord 等入口无关。
|
||||
|
||||
### Modal 算在 Tool Gateway 里吗？
|
||||
|
||||
Modal（无服务器终端后端）可作为 Nous 订阅的可选附加能力，但**不会**由 Tool Gateway 安装向导一并打开——请单独通过 `hermes setup terminal` 或在 `config.yaml` 中配置。
|
||||
+178
@@ -0,0 +1,178 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: "工具与工具集"
|
||||
description: "Hermes Agent 工具概览——可用工具、工具集工作方式及终端后端"
|
||||
---
|
||||
|
||||
# 工具与工具集
|
||||
|
||||
工具是扩展 Agent 能力的函数。它们被组织为逻辑上的**工具集**，可按平台启用或禁用。
|
||||
|
||||
## 可用工具
|
||||
|
||||
Hermes 内置了丰富的工具注册表，涵盖网页搜索、浏览器自动化、终端执行、文件编辑、记忆、委托、RL 训练、消息投递、Home Assistant 等功能。
|
||||
|
||||
:::note
|
||||
**Honcho 跨会话记忆**作为记忆提供者插件（`plugins/memory/honcho/`）提供，而非内置工具集。安装方式请参阅 [Plugins](./plugins.md)。
|
||||
:::
|
||||
|
||||
高层分类：
|
||||
|
||||
| 分类 | 示例 | 描述 |
|
||||
|----------|----------|-------------|
|
||||
| **Web** | `web_search`, `web_extract` | 搜索网页并提取页面内容。 |
|
||||
| **X 搜索** | `x_search` | 通过 xAI 内置的 `x_search` Responses 工具搜索 X（Twitter）帖子和话题——需要 xAI 凭据（SuperGrok OAuth 或 `XAI_API_KEY`）；默认关闭，可通过 `hermes tools` → 🐦 X (Twitter) Search 启用。 |
|
||||
| **终端与文件** | `terminal`, `process`, `read_file`, `patch` | 执行命令并操作文件。 |
|
||||
| **浏览器** | `browser_navigate`, `browser_snapshot`, `browser_vision` | 支持文本和视觉的交互式浏览器自动化。 |
|
||||
| **媒体** | `vision_analyze`, `image_generate`, `video_generate`, `video_analyze`, `text_to_speech` | 多模态分析与生成。`video_generate` 和 `video_analyze` 需手动启用（通过 `hermes tools` 或 `--toolsets` 添加 `video_gen` / `video` 工具集）。 |
|
||||
| **Agent 编排** | `todo`, `clarify`, `execute_code`, `delegate_task` | 规划、澄清、代码执行及子 Agent 委托。 |
|
||||
| **记忆与召回** | `memory`, `session_search` | 持久化记忆与会话搜索。 |
|
||||
| **自动化与投递** | `cronjob`, `send_message` | 支持创建/列出/更新/暂停/恢复/运行/删除操作的定时任务，以及出站消息投递。 |
|
||||
| **集成** | `ha_*`、MCP server 工具 | Home Assistant、MCP 及其他集成。 |
|
||||
|
||||
如需查看由代码派生的权威注册表，请参阅 [内置工具参考](/reference/tools-reference) 和 [工具集参考](/reference/toolsets-reference)。
|
||||
|
||||
:::tip Nous Tool Gateway
|
||||
付费 [Nous Portal](https://portal.nousresearch.com) 订阅者可通过 **[Tool Gateway](tool-gateway.md)** 使用网页搜索、图像生成、TTS 和浏览器自动化——无需单独配置 API 密钥。运行 `hermes model` 启用，或通过 `hermes tools` 配置各工具。
|
||||
:::
|
||||
|
||||
## 使用工具集
|
||||
|
||||
```bash
|
||||
# 使用指定工具集
|
||||
hermes chat --toolsets "web,terminal"
|
||||
|
||||
# 查看所有可用工具
|
||||
hermes tools
|
||||
|
||||
# 按平台交互式配置工具
|
||||
hermes tools
|
||||
```
|
||||
|
||||
常用工具集包括 `web`、`search`、`terminal`、`file`、`browser`、`vision`、`image_gen`、`moa`、`skills`、`tts`、`todo`、`memory`、`session_search`、`cronjob`、`code_execution`、`delegation`、`clarify`、`homeassistant`、`messaging`、`spotify`、`discord`、`discord_admin`、`debugging` 和 `safe`。
|
||||
|
||||
完整列表（包括 `hermes-cli`、`hermes-telegram` 等平台预设以及 `mcp-<server>` 等动态 MCP 工具集）请参阅 [工具集参考](/reference/toolsets-reference)。
|
||||
|
||||
## 终端后端
|
||||
|
||||
终端工具可在不同环境中执行命令：
|
||||
|
||||
| 后端 | 描述 | 适用场景 |
|
||||
|---------|-------------|----------|
|
||||
| `local` | 在本机运行（默认） | 开发、可信任务 |
|
||||
| `docker` | 隔离容器 | 安全性、可复现性 |
|
||||
| `ssh` | 远程服务器 | 沙箱隔离，防止 Agent 修改自身代码 |
|
||||
| `singularity` | HPC 容器 | 集群计算、无 root 权限 |
|
||||
| `modal` | 云端执行 | 无服务器、弹性扩展 |
|
||||
| `daytona` | 云端沙箱工作区 | 持久化远程开发环境 |
|
||||
|
||||
### 配置
|
||||
|
||||
```yaml
|
||||
# 在 ~/.hermes/config.yaml 中
|
||||
terminal:
|
||||
backend: local # 或：docker, ssh, singularity, modal, daytona
|
||||
cwd: "." # 工作目录
|
||||
timeout: 180 # 命令超时时间（秒）
|
||||
```
|
||||
|
||||
### Docker 后端
|
||||
|
||||
```yaml
|
||||
terminal:
|
||||
backend: docker
|
||||
docker_image: python:3.11-slim
|
||||
```
|
||||
|
||||
**单个持久容器，在整个进程生命周期内共享。** Hermes 在首次使用时启动一个长期运行的容器（`docker run -d ... sleep 2h`），并通过 `docker exec` 将所有终端、文件及 `execute_code` 调用路由到同一容器中。工作目录变更、已安装的包、环境调整以及写入 `/workspace` 的文件，在同一 Hermes 进程的整个生命周期内，跨 `/new`、`/reset` 和 `delegate_task` 子 Agent 均会保留。容器在关闭时停止并删除。
|
||||
|
||||
这意味着 Docker 后端的行为类似持久化沙箱虚拟机，而非每次命令都使用全新容器。如果你执行过一次 `pip install foo`，该包在本次会话的剩余时间内均可用。如果你执行了 `cd /workspace/project`，后续的 `ls` 调用将看到该目录。完整的生命周期详情及控制 `/workspace` 和 `/root` 是否跨 Hermes 重启保留的 `container_persistent` 标志，请参阅 [配置 → Docker 后端](../configuration.md#docker-backend)。
|
||||
|
||||
### SSH 后端
|
||||
|
||||
推荐用于安全场景——Agent 无法修改自身代码：
|
||||
|
||||
```yaml
|
||||
terminal:
|
||||
backend: ssh
|
||||
```
|
||||
```bash
|
||||
# 在 ~/.hermes/.env 中设置凭据
|
||||
TERMINAL_SSH_HOST=my-server.example.com
|
||||
TERMINAL_SSH_USER=myuser
|
||||
TERMINAL_SSH_KEY=~/.ssh/id_rsa
|
||||
```
|
||||
|
||||
### Singularity/Apptainer
|
||||
|
||||
```bash
|
||||
# 为并行 worker 预构建 SIF
|
||||
apptainer build ~/python.sif docker://python:3.11-slim
|
||||
|
||||
# 配置
|
||||
hermes config set terminal.backend singularity
|
||||
hermes config set terminal.singularity_image ~/python.sif
|
||||
```
|
||||
|
||||
### Modal（无服务器云）
|
||||
|
||||
```bash
|
||||
uv pip install modal
|
||||
modal setup
|
||||
hermes config set terminal.backend modal
|
||||
```
|
||||
|
||||
### 容器资源
|
||||
|
||||
为所有容器后端配置 CPU、内存、磁盘和持久化：
|
||||
|
||||
```yaml
|
||||
terminal:
|
||||
backend: docker # 或 singularity, modal, daytona
|
||||
container_cpu: 1 # CPU 核心数（默认：1）
|
||||
container_memory: 5120 # 内存（MB，默认：5GB）
|
||||
container_disk: 51200 # 磁盘（MB，默认：50GB）
|
||||
container_persistent: true # 跨会话持久化文件系统（默认：true）
|
||||
```
|
||||
|
||||
启用 `container_persistent: true` 后，已安装的包、文件和配置将跨会话保留。
|
||||
|
||||
### 容器安全
|
||||
|
||||
所有容器后端均启用安全加固：
|
||||
|
||||
- 只读根文件系统（Docker）
|
||||
- 丢弃所有 Linux capabilities
|
||||
- 禁止权限提升
|
||||
- PID 限制（256 个进程）
|
||||
- 完整命名空间隔离
|
||||
- 通过卷挂载实现持久化工作区，而非可写根层
|
||||
|
||||
Docker 可通过 `terminal.docker_forward_env` 接受显式的环境变量白名单，但转发的变量对容器内的命令可见，应视为在该会话中已暴露。
|
||||
|
||||
## 后台进程管理
|
||||
|
||||
启动后台进程并进行管理：
|
||||
|
||||
```python
|
||||
terminal(command="pytest -v tests/", background=true)
|
||||
# 返回：{"session_id": "proc_abc123", "pid": 12345}
|
||||
|
||||
# 然后使用 process 工具进行管理：
|
||||
process(action="list") # 显示所有运行中的进程
|
||||
process(action="poll", session_id="proc_abc123") # 检查状态
|
||||
process(action="wait", session_id="proc_abc123") # 阻塞直到完成
|
||||
process(action="log", session_id="proc_abc123") # 完整输出
|
||||
process(action="kill", session_id="proc_abc123") # 终止进程
|
||||
process(action="write", session_id="proc_abc123", data="y") # 发送输入
|
||||
```
|
||||
|
||||
PTY 模式（`pty=true`）可启用 Codex 和 Claude Code 等交互式 CLI 工具。
|
||||
|
||||
## Sudo 支持
|
||||
|
||||
如果命令需要 sudo，系统会提示你输入密码（在本次会话内缓存）。也可在 `~/.hermes/.env` 中设置 `SUDO_PASSWORD`。
|
||||
|
||||
:::warning
|
||||
在消息平台上，如果 sudo 失败，输出中会提示将 `SUDO_PASSWORD` 添加到 `~/.hermes/.env`。
|
||||
:::
|
||||
+456
@@ -0,0 +1,456 @@
|
||||
---
|
||||
sidebar_position: 9
|
||||
title: "语音与 TTS"
|
||||
description: "跨所有平台的文字转语音与语音消息转录"
|
||||
---
|
||||
|
||||
# 语音与 TTS
|
||||
|
||||
Hermes Agent 支持跨所有消息平台的文字转语音（TTS）输出和语音消息转录（STT）。
|
||||
|
||||
:::tip Nous 订阅用户
|
||||
如果你拥有付费的 [Nous Portal](https://portal.nousresearch.com) 订阅，OpenAI TTS 可通过 **[Tool Gateway](tool-gateway.md)** 使用，无需单独的 OpenAI API 密钥。新安装可运行 `hermes setup --portal` 登录并一次性开启所有 gateway 工具；已有安装可通过 `hermes model` 或 `hermes tools` 选择 **Nous Subscription** 仅启用 TTS。
|
||||
:::
|
||||
|
||||
## 文字转语音（TTS）
|
||||
|
||||
支持十个提供商将文字转换为语音：
|
||||
|
||||
| 提供商 | 质量 | 费用 | API 密钥 |
|
||||
|----------|---------|------|---------|
|
||||
| **Edge TTS**（默认） | 良好 | 免费 | 无需 |
|
||||
| **ElevenLabs** | 优秀 | 付费 | `ELEVENLABS_API_KEY` |
|
||||
| **OpenAI TTS** | 良好 | 付费 | `VOICE_TOOLS_OPENAI_KEY` |
|
||||
| **MiniMax TTS** | 优秀 | 付费 | `MINIMAX_API_KEY` |
|
||||
| **Mistral (Voxtral TTS)** | 优秀 | 付费 | `MISTRAL_API_KEY` |
|
||||
| **Google Gemini TTS** | 优秀 | 免费额度 | `GEMINI_API_KEY` |
|
||||
| **xAI TTS** | 优秀 | 付费 | `XAI_API_KEY` |
|
||||
| **NeuTTS** | 良好 | 免费（本地） | 无需 |
|
||||
| **KittenTTS** | 良好 | 免费（本地） | 无需 |
|
||||
| **Piper** | 良好 | 免费（本地） | 无需 |
|
||||
|
||||
### 平台投递方式
|
||||
|
||||
| 平台 | 投递方式 | 格式 |
|
||||
|----------|----------|--------|
|
||||
| Telegram | 语音气泡（内联播放） | Opus `.ogg` |
|
||||
| Discord | 语音气泡（Opus/OGG），回退为文件附件 | Opus/MP3 |
|
||||
| WhatsApp | 音频文件附件 | MP3 |
|
||||
| CLI | 保存至 `~/.hermes/audio_cache/` | MP3 |
|
||||
|
||||
### 配置
|
||||
|
||||
```yaml
|
||||
# In ~/.hermes/config.yaml
|
||||
tts:
|
||||
provider: "edge" # "edge" | "elevenlabs" | "openai" | "minimax" | "mistral" | "gemini" | "xai" | "neutts" | "kittentts" | "piper"
|
||||
speed: 1.0 # Global speed multiplier (provider-specific settings override this)
|
||||
edge:
|
||||
voice: "en-US-AriaNeural" # 322 voices, 74 languages
|
||||
speed: 1.0 # Converted to rate percentage (+/-%)
|
||||
elevenlabs:
|
||||
voice_id: "pNInz6obpgDQGcFmaJgB" # Adam
|
||||
model_id: "eleven_multilingual_v2"
|
||||
openai:
|
||||
model: "gpt-4o-mini-tts"
|
||||
voice: "alloy" # alloy, echo, fable, onyx, nova, shimmer
|
||||
base_url: "https://api.openai.com/v1" # Override for OpenAI-compatible TTS endpoints
|
||||
speed: 1.0 # 0.25 - 4.0
|
||||
minimax:
|
||||
model: "speech-2.8-hd" # speech-2.8-hd (default), speech-2.8-turbo
|
||||
voice_id: "English_Graceful_Lady" # See https://platform.minimax.io/faq/system-voice-id
|
||||
speed: 1 # 0.5 - 2.0
|
||||
vol: 1 # 0 - 10
|
||||
pitch: 0 # -12 - 12
|
||||
mistral:
|
||||
model: "voxtral-mini-tts-2603"
|
||||
voice_id: "c69964a6-ab8b-4f8a-9465-ec0925096ec8" # Paul - Neutral (default)
|
||||
gemini:
|
||||
model: "gemini-2.5-flash-preview-tts" # or gemini-2.5-pro-preview-tts
|
||||
voice: "Kore" # 30 prebuilt voices: Zephyr, Puck, Kore, Enceladus, Gacrux, etc.
|
||||
xai:
|
||||
voice_id: "eve" # or a custom voice ID — see docs below
|
||||
language: "en" # ISO 639-1 code
|
||||
sample_rate: 24000 # 22050 / 24000 (default) / 44100 / 48000
|
||||
bit_rate: 128000 # MP3 bitrate; only applies when codec=mp3
|
||||
# base_url: "https://api.x.ai/v1" # Override via XAI_BASE_URL env var
|
||||
neutts:
|
||||
ref_audio: ''
|
||||
ref_text: ''
|
||||
model: neuphonic/neutts-air-q4-gguf
|
||||
device: cpu
|
||||
kittentts:
|
||||
model: KittenML/kitten-tts-nano-0.8-int8 # 25MB int8; also: kitten-tts-micro-0.8 (41MB), kitten-tts-mini-0.8 (80MB)
|
||||
voice: Jasper # Jasper, Bella, Luna, Bruno, Rosie, Hugo, Kiki, Leo
|
||||
speed: 1.0 # 0.5 - 2.0
|
||||
clean_text: true # Expand numbers, currencies, units
|
||||
piper:
|
||||
voice: en_US-lessac-medium # voice name (auto-downloaded) OR absolute path to .onnx
|
||||
# voices_dir: '' # default: ~/.hermes/cache/piper-voices/
|
||||
# use_cuda: false # requires onnxruntime-gpu
|
||||
# length_scale: 1.0 # 2.0 = twice as slow
|
||||
# noise_scale: 0.667
|
||||
# noise_w_scale: 0.8
|
||||
# volume: 1.0 # 0.5 = half as loud
|
||||
# normalize_audio: true
|
||||
```
|
||||
|
||||
**速度控制**：全局 `tts.speed` 值默认应用于所有提供商。每个提供商可用自身的 `speed` 设置覆盖它（例如 `tts.openai.speed: 1.5`）。提供商级别的速度优先于全局值。默认值为 `1.0`（正常速度）。
|
||||
|
||||
|
||||
### 输入长度限制
|
||||
|
||||
每个提供商都有文档记录的单次请求输入字符上限。Hermes 在调用提供商前会截断文本，确保请求不会因长度错误而失败：
|
||||
|
||||
| 提供商 | 默认上限（字符数） |
|
||||
|----------|---------------------|
|
||||
| Edge TTS | 5000 |
|
||||
| OpenAI | 4096 |
|
||||
| xAI | 15000 |
|
||||
| MiniMax | 10000 |
|
||||
| Mistral | 4000 |
|
||||
| Google Gemini | 5000 |
|
||||
| ElevenLabs | 取决于模型（见下文） |
|
||||
| NeuTTS | 2000 |
|
||||
| KittenTTS | 2000 |
|
||||
|
||||
**ElevenLabs** 根据配置的 `model_id` 选择上限：
|
||||
|
||||
| `model_id` | 上限（字符数） |
|
||||
|------------|-------------|
|
||||
| `eleven_flash_v2_5` | 40000 |
|
||||
| `eleven_flash_v2` | 30000 |
|
||||
| `eleven_multilingual_v2`（默认）、`eleven_multilingual_v1`、`eleven_english_sts_v2`、`eleven_english_sts_v1` | 10000 |
|
||||
| `eleven_v3`、`eleven_ttv_v3` | 5000 |
|
||||
| 未知模型 | 回退至提供商默认值（10000） |
|
||||
|
||||
**按提供商覆盖**，在 TTS 配置的提供商节下使用 `max_text_length:`：
|
||||
|
||||
```yaml
|
||||
tts:
|
||||
openai:
|
||||
max_text_length: 8192 # raise or lower the provider cap
|
||||
```
|
||||
|
||||
仅接受正整数。零、负数、非数字或布尔值将回退至提供商默认值，因此错误的配置不会意外禁用截断。
|
||||
|
||||
### Telegram 语音气泡与 ffmpeg
|
||||
|
||||
Telegram 语音气泡需要 Opus/OGG 音频格式：
|
||||
|
||||
- **OpenAI、ElevenLabs 和 Mistral** 原生输出 Opus，无需额外配置
|
||||
- **Edge TTS**（默认）输出 MP3，需要 **ffmpeg** 进行转换
|
||||
- **MiniMax TTS** 输出 MP3，需要 **ffmpeg** 转换以在 Telegram 显示语音气泡
|
||||
- **Google Gemini TTS** 输出原始 PCM，使用 **ffmpeg** 直接编码为 Opus 以在 Telegram 显示语音气泡
|
||||
- **xAI TTS** 输出 MP3，需要 **ffmpeg** 转换以在 Telegram 显示语音气泡
|
||||
- **NeuTTS** 输出 WAV，同样需要 **ffmpeg** 转换以在 Telegram 显示语音气泡
|
||||
- **KittenTTS** 输出 WAV，同样需要 **ffmpeg** 转换以在 Telegram 显示语音气泡
|
||||
- **Piper** 输出 WAV，同样需要 **ffmpeg** 转换以在 Telegram 显示语音气泡
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt install ffmpeg
|
||||
|
||||
# macOS
|
||||
brew install ffmpeg
|
||||
|
||||
# Fedora
|
||||
sudo dnf install ffmpeg
|
||||
```
|
||||
|
||||
若未安装 ffmpeg，Edge TTS、MiniMax TTS、NeuTTS、KittenTTS 和 Piper 的音频将作为普通音频文件发送（可播放，但显示为矩形播放器而非语音气泡）。
|
||||
|
||||
:::tip
|
||||
如果你希望在不安装 ffmpeg 的情况下使用语音气泡，请切换至 OpenAI、ElevenLabs 或 Mistral 提供商。
|
||||
:::
|
||||
|
||||
### xAI 自定义声音（声音克隆）
|
||||
|
||||
xAI 支持克隆你的声音并将其用于 TTS。在 [xAI Console](https://console.x.ai/team/default/voice/voice-library) 中创建自定义声音，然后在配置中设置生成的 `voice_id`：
|
||||
|
||||
```yaml
|
||||
tts:
|
||||
provider: xai
|
||||
xai:
|
||||
voice_id: "nlbqfwie" # your custom voice ID
|
||||
```
|
||||
|
||||
有关录制、支持格式和限制的详细信息，请参阅 [xAI Custom Voices 文档](https://docs.x.ai/developers/model-capabilities/audio/custom-voices)。
|
||||
|
||||
### Piper（本地，支持 44 种语言）
|
||||
|
||||
Piper 是来自 Open Home Foundation（Home Assistant 维护者）的快速本地神经网络 TTS 引擎。它完全在 CPU 上运行，支持 **44 种语言**的预训练声音，无需 API 密钥。
|
||||
|
||||
**通过 `hermes tools` 安装** → Voice & TTS → Piper — Hermes 会自动为你运行 `pip install piper-tts`。或手动安装：`pip install piper-tts`。
|
||||
|
||||
**切换至 Piper：**
|
||||
|
||||
```yaml
|
||||
tts:
|
||||
provider: piper
|
||||
piper:
|
||||
voice: en_US-lessac-medium
|
||||
```
|
||||
|
||||
首次对未在本地缓存的声音进行 TTS 调用时，Hermes 会运行 `python -m piper.download_voices <name>` 并将模型（约 20-90MB，取决于质量等级）下载至 `~/.hermes/cache/piper-voices/`。后续调用将复用已缓存的模型。
|
||||
|
||||
**选择声音。** [完整声音目录](https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/VOICES.md) 涵盖英语、西班牙语、法语、德语、意大利语、荷兰语、葡萄牙语、俄语、波兰语、土耳其语、中文、阿拉伯语、印地语等——每种语言均有 `x_low` / `low` / `medium` / `high` 质量等级。可在 [rhasspy.github.io/piper-samples](https://rhasspy.github.io/piper-samples/) 试听声音样本。
|
||||
|
||||
**使用预下载的声音。** 将 `tts.piper.voice` 设置为以 `.onnx` 结尾的绝对路径：
|
||||
|
||||
```yaml
|
||||
tts:
|
||||
piper:
|
||||
voice: /path/to/my-custom-voice.onnx
|
||||
```
|
||||
|
||||
**高级参数**（`tts.piper.length_scale` / `noise_scale` / `noise_w_scale` / `volume` / `normalize_audio`、`use_cuda`）与 Piper 的 `SynthesisConfig` 一一对应。在较旧的 `piper-tts` 版本上这些参数会被忽略。
|
||||
|
||||
### 自定义命令提供商
|
||||
|
||||
如果你想使用的 TTS 引擎未被原生支持（VoxCPM、MLX-Kokoro、XTTS CLI、声音克隆脚本，或任何其他暴露 CLI 的引擎），你可以将其作为**命令类型提供商**接入，无需编写任何 Python 代码。Hermes 将输入文本写入临时 UTF-8 文件，运行你的 shell 命令，并读取命令生成的音频文件。
|
||||
|
||||
在 `tts.providers.<name>` 下声明一个或多个提供商，并通过 `tts.provider: <name>` 在它们之间切换——与切换 `edge` 和 `openai` 等内置提供商的方式相同。
|
||||
|
||||
```yaml
|
||||
tts:
|
||||
provider: voxcpm # pick any name under tts.providers
|
||||
providers:
|
||||
voxcpm:
|
||||
type: command
|
||||
command: "voxcpm --ref ~/voice.wav --text-file {input_path} --out {output_path}"
|
||||
output_format: mp3
|
||||
timeout: 180
|
||||
voice_compatible: true # try to deliver as a Telegram voice bubble
|
||||
|
||||
mlx-kokoro:
|
||||
type: command
|
||||
command: "python -m mlx_kokoro --in {input_path} --out {output_path} --voice {voice}"
|
||||
voice: af_sky
|
||||
output_format: wav
|
||||
|
||||
piper-custom: # native Piper also supports custom .onnx via tts.piper.voice
|
||||
type: command
|
||||
command: "piper -m /path/to/custom.onnx -f {output_path} < {input_path}"
|
||||
output_format: wav
|
||||
```
|
||||
|
||||
#### 示例：Doubao（中文 seed-tts-2.0）
|
||||
|
||||
如需通过字节跳动的 [seed-tts-2.0](https://www.volcengine.com/docs/6561/1257544) 双向流式 API 实现高质量中文 TTS，请安装 [`doubao-speech`](https://pypi.org/project/doubao-speech/) PyPI 包并将其作为命令提供商接入：
|
||||
|
||||
```bash
|
||||
pip install doubao-speech
|
||||
export VOLCENGINE_APP_ID="your-app-id"
|
||||
export VOLCENGINE_ACCESS_TOKEN="your-access-token"
|
||||
```
|
||||
|
||||
```yaml
|
||||
tts:
|
||||
provider: doubao
|
||||
providers:
|
||||
doubao:
|
||||
type: command
|
||||
command: "doubao-speech say --text-file {input_path} --out {output_path}"
|
||||
output_format: mp3
|
||||
max_text_length: 1024
|
||||
timeout: 30
|
||||
```
|
||||
|
||||
凭据来自你的 shell 环境（`VOLCENGINE_APP_ID` / `VOLCENGINE_ACCESS_TOKEN`）或 `~/.doubao-speech/config.yaml`。通过在命令中添加 `--voice zh-female-warm`（或 `doubao-speech list-voices` 中的任何其他别名）来选择声音。`doubao-speech` 还内置了流式 ASR——有关 Hermes 集成，请参阅[下方的 STT 章节](#example-doubao--volcengine-asr)。源码和完整文档：[github.com/Hypnus-Yuan/doubao-speech](https://github.com/Hypnus-Yuan/doubao-speech)。
|
||||
|
||||
#### 占位符
|
||||
|
||||
你的命令模板可以引用以下占位符。Hermes 在渲染时会替换它们，并根据上下文（裸值 / 单引号 / 双引号）对每个值进行 shell 转义，因此包含空格和其他 shell 敏感字符的路径是安全的。
|
||||
|
||||
| 占位符 | 含义 |
|
||||
|------------------|------------------------------------------------------|
|
||||
| `{input_path}` | Hermes 写入的临时 UTF-8 文本文件路径 |
|
||||
| `{text_path}` | `{input_path}` 的别名 |
|
||||
| `{output_path}` | 命令必须写入音频的路径 |
|
||||
| `{format}` | `mp3` / `wav` / `ogg` / `flac` |
|
||||
| `{voice}` | `tts.providers.<name>.voice`，未设置时为空 |
|
||||
| `{model}` | `tts.providers.<name>.model` |
|
||||
| `{speed}` | 解析后的速度倍率（提供商级别或全局） |
|
||||
|
||||
使用 `{{` 和 `}}` 表示字面大括号。
|
||||
|
||||
#### 可选键
|
||||
|
||||
| 键 | 默认值 | 含义 |
|
||||
|--------------------|---------|------------------------------------------------------------------------------------------------------------|
|
||||
| `timeout` | `120` | 秒数；超时后进程树将被终止（Unix `killpg`，Windows `taskkill /T`）。 |
|
||||
| `output_format` | `mp3` | `mp3` / `wav` / `ogg` / `flac` 之一。若 Hermes 选择路径，则从输出扩展名自动推断。 |
|
||||
| `voice_compatible` | `false` | 为 `true` 时，Hermes 通过 ffmpeg 将 MP3/WAV 输出转换为 Opus/OGG，使 Telegram 渲染语音气泡。 |
|
||||
| `max_text_length` | `5000` | 渲染命令前，输入将被截断至此长度。 |
|
||||
| `voice` / `model` | 空 | 仅作为占位符值传递给命令。 |
|
||||
|
||||
#### 行为说明
|
||||
|
||||
- **内置名称始终优先。** `tts.providers.openai` 条目永远不会覆盖原生 OpenAI 提供商，因此任何用户配置都无法静默替换内置提供商。
|
||||
- **默认投递方式为文档。** 命令提供商在所有平台上均以普通音频附件投递。通过 `voice_compatible: true` 按提供商选择加入语音气泡投递。
|
||||
- **命令失败会暴露给 Agent。** 非零退出码、空输出或超时均会返回包含命令 stderr/stdout 的错误，便于你从对话中调试提供商。
|
||||
- **设置了 `command:` 时，`type: command` 为默认值。** 显式写出 `type: command` 是良好实践，但非必须；包含非空 `command` 字符串的条目会被视为命令提供商。
|
||||
- **`{input_path}` / `{text_path}` 可互换。** 使用在你的命令中读起来更自然的那个。
|
||||
|
||||
#### 安全性
|
||||
|
||||
命令类型提供商会以你的用户权限运行你配置的任何 shell 命令。Hermes 会对占位符值进行转义并强制执行配置的超时，但命令模板本身是受信任的本地输入——请像对待 PATH 中的 shell 脚本一样对待它。
|
||||
|
||||
### Python 插件提供商
|
||||
|
||||
对于无法用单个 shell 命令表达的 TTS 引擎——没有 CLI 的 Python SDK、流式引擎、声音列表 API、OAuth 刷新认证——可通过 `ctx.register_tts_provider()` 注册 Python 插件。该插件与[自定义命令提供商](#custom-command-providers)注册表**共存**（不替换）；选择适合你引擎的接入方式。
|
||||
|
||||
#### 如何选择
|
||||
|
||||
| 你的后端具有… | 使用 |
|
||||
|---|---|
|
||||
| 单个 CLI，从文件/stdin 读取文本并将音频写入文件/stdout | **命令提供商**（无需 Python） |
|
||||
| 两三个通过 shell 管道串联的 CLI | **命令提供商** |
|
||||
| 仅有 Python SDK，没有 CLI | **插件** |
|
||||
| 你希望分块投递的流式字节（生成中的语音气泡） | **插件**（覆盖 `stream()`） |
|
||||
| `hermes setup` 使用的声音列表 API | **插件**（覆盖 `list_voices()`） |
|
||||
| OAuth 刷新流程（非静态 bearer token） | **插件** |
|
||||
|
||||
内置提供商始终优先，命令提供商优先于同名插件——因此插件可以安全地注册任何非内置名称，无需担心覆盖现有配置。
|
||||
|
||||
#### 最小插件
|
||||
|
||||
将以下内容放入 `~/.hermes/plugins/my-tts/`：
|
||||
|
||||
`plugin.yaml`：
|
||||
```yaml
|
||||
name: my-tts
|
||||
version: 0.1.0
|
||||
description: "My custom Python TTS backend"
|
||||
```
|
||||
|
||||
`__init__.py`：
|
||||
```python
|
||||
from agent.tts_provider import TTSProvider
|
||||
|
||||
|
||||
class MyTTSProvider(TTSProvider):
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "my-tts" # what tts.provider matches against
|
||||
|
||||
@property
|
||||
def display_name(self) -> str:
|
||||
return "My Custom TTS"
|
||||
|
||||
def is_available(self) -> bool:
|
||||
# Return False when credentials/deps are missing — picker skips
|
||||
# this row but the dispatcher still routes here on explicit config.
|
||||
import os
|
||||
return bool(os.environ.get("MY_TTS_API_KEY"))
|
||||
|
||||
def synthesize(self, text, output_path, *, voice=None, model=None,
|
||||
speed=None, format="mp3", **extra) -> str:
|
||||
# Write audio bytes to output_path, return the path.
|
||||
# Raise on failure — the dispatcher converts exceptions to a
|
||||
# standard error envelope.
|
||||
import my_tts_sdk
|
||||
client = my_tts_sdk.Client()
|
||||
audio_bytes = client.synthesize(text=text, voice=voice or "default")
|
||||
with open(output_path, "wb") as f:
|
||||
f.write(audio_bytes)
|
||||
return output_path
|
||||
|
||||
|
||||
def register(ctx):
|
||||
ctx.register_tts_provider(MyTTSProvider())
|
||||
```
|
||||
|
||||
启用它（`hermes plugins enable my-tts`），将 `tts.provider` 指向它（在 `config.yaml` 中设置 `tts.provider: my-tts`），`text_to_speech` 工具将通过你的插件路由。
|
||||
|
||||
#### 可选 hook
|
||||
|
||||
在你的提供商类上覆盖以下方法以获得更丰富的集成：
|
||||
|
||||
- `list_voices()` → 返回 `{id, display, language, gender, preview_url}` 字典列表，显示在 `hermes tools` 中。
|
||||
- `list_models()` → 返回 `{id, display, languages, max_text_length}` 字典列表。
|
||||
- `get_setup_schema()` → 返回 `{name, badge, tag, env_vars: [{key, prompt, url}]}` 以驱动 `hermes tools` / `hermes setup` 中的选择器行。若不提供，插件仍可正常工作，但其在选择器中的行信息会很简略。
|
||||
- `stream(text, *, voice, model, format, **extra)` → 迭代器，产出音频字节用于流式投递（默认抛出 `NotImplementedError`）。
|
||||
- `voice_compatible` 属性 → 若你的输出与 Opus 兼容且 gateway 应将其作为语音气泡投递，则设为 `True`（默认 `False` = 普通音频附件）。
|
||||
|
||||
完整的抽象基类（含文档字符串）请参阅 `agent/tts_provider.py`。
|
||||
|
||||
## 语音消息转录（STT）
|
||||
|
||||
在 Telegram、Discord、WhatsApp、Slack 或 Signal 上发送的语音消息会被自动转录并作为文本注入对话。Agent 将转录内容视为普通文本。
|
||||
|
||||
| 提供商 | 质量 | 费用 | API 密钥 |
|
||||
|----------|---------|------|---------|
|
||||
| **本地 Whisper**（默认） | 良好 | 免费 | 无需 |
|
||||
| **Groq Whisper API** | 良好至最佳 | 免费额度 | `GROQ_API_KEY` |
|
||||
| **OpenAI Whisper API** | 良好至最佳 | 付费 | `VOICE_TOOLS_OPENAI_KEY` 或 `OPENAI_API_KEY` |
|
||||
|
||||
:::info 零配置
|
||||
安装了 `faster-whisper` 后，本地转录即可开箱即用。若不可用，Hermes 也可使用常见安装位置（如 `/opt/homebrew/bin`）的本地 `whisper` CLI，或通过 `HERMES_LOCAL_STT_COMMAND` 指定的自定义命令。
|
||||
:::
|
||||
|
||||
### 配置
|
||||
|
||||
```yaml
|
||||
# In ~/.hermes/config.yaml
|
||||
stt:
|
||||
provider: "local" # "local" | "groq" | "openai" | "mistral" | "xai"
|
||||
local:
|
||||
model: "base" # tiny, base, small, medium, large-v3
|
||||
openai:
|
||||
model: "whisper-1" # whisper-1, gpt-4o-mini-transcribe, gpt-4o-transcribe
|
||||
mistral:
|
||||
model: "voxtral-mini-latest" # voxtral-mini-latest, voxtral-mini-2602
|
||||
xai:
|
||||
model: "grok-stt" # xAI Grok STT
|
||||
```
|
||||
|
||||
### 提供商详情
|
||||
|
||||
**本地（faster-whisper）** — 通过 [faster-whisper](https://github.com/SYSTRAN/faster-whisper) 在本地运行 Whisper。默认使用 CPU，有 GPU 时使用 GPU。模型大小：
|
||||
|
||||
| 模型 | 大小 | 速度 | 质量 |
|
||||
|-------|------|-------|---------|
|
||||
| `tiny` | ~75 MB | 最快 | 基础 |
|
||||
| `base` | ~150 MB | 快 | 良好（默认） |
|
||||
| `small` | ~500 MB | 中等 | 较好 |
|
||||
| `medium` | ~1.5 GB | 较慢 | 优秀 |
|
||||
| `large-v3` | ~3 GB | 最慢 | 最佳 |
|
||||
|
||||
**Groq API** — 需要 `GROQ_API_KEY`。当你需要免费托管 STT 选项时，是良好的云端备选方案。
|
||||
|
||||
**OpenAI API** — 优先使用 `VOICE_TOOLS_OPENAI_KEY`，回退至 `OPENAI_API_KEY`。支持 `whisper-1`、`gpt-4o-mini-transcribe` 和 `gpt-4o-transcribe`。
|
||||
|
||||
**Mistral API（Voxtral Transcribe）** — 需要 `MISTRAL_API_KEY`。使用 Mistral 的 [Voxtral Transcribe](https://docs.mistral.ai/capabilities/audio/speech_to_text/) 模型。支持 13 种语言、说话人分离和词级时间戳。通过 `pip install hermes-agent[mistral]` 安装。
|
||||
|
||||
**xAI Grok STT** — 需要 `XAI_API_KEY`。以 multipart/form-data 格式发送至 `https://api.x.ai/v1/stt`。如果你已在使用 xAI 进行聊天或 TTS 并希望一个 API 密钥搞定一切，这是个好选择。自动检测顺序将其排在 Groq 之后——显式设置 `stt.provider: xai` 可强制使用。
|
||||
|
||||
**自定义本地 CLI 回退** — 若你希望 Hermes 直接调用本地转录命令，请设置 `HERMES_LOCAL_STT_COMMAND`。命令模板支持 `{input_path}`、`{output_dir}`、`{language}` 和 `{model}` 占位符。你的命令必须在 `{output_dir}` 下某处写入 `.txt` 转录文件。
|
||||
|
||||
#### 示例：Doubao / Volcengine ASR
|
||||
|
||||
如果你使用 [`doubao-speech`](https://pypi.org/project/doubao-speech/) 进行 Doubao TTS（见[上文](#example-doubao-chinese-seed-tts-20)），同一个包也可通过本地命令 STT 接口处理语音转文字：
|
||||
|
||||
```bash
|
||||
pip install doubao-speech
|
||||
export VOLCENGINE_APP_ID="your-app-id"
|
||||
export VOLCENGINE_ACCESS_TOKEN="your-access-token"
|
||||
export HERMES_LOCAL_STT_COMMAND='doubao-speech transcribe {input_path} --out {output_dir}/transcript.txt'
|
||||
```
|
||||
|
||||
```yaml
|
||||
stt:
|
||||
provider: local_command
|
||||
```
|
||||
|
||||
Hermes 将传入的语音消息写入 `{input_path}`，运行命令，并读取 `{output_dir}` 下生成的 `.txt` 文件。语言由 Volcengine bigmodel 端点自动检测。
|
||||
|
||||
### 回退行为
|
||||
|
||||
若配置的提供商不可用，Hermes 会自动回退：
|
||||
- **本地 faster-whisper 不可用** → 在云端提供商之前尝试本地 `whisper` CLI 或 `HERMES_LOCAL_STT_COMMAND`
|
||||
- **未设置 Groq 密钥** → 回退至本地转录，然后是 OpenAI
|
||||
- **未设置 OpenAI 密钥** → 回退至本地转录，然后是 Groq
|
||||
- **未设置 Mistral 密钥/SDK** → 在自动检测中跳过；回退至下一个可用提供商
|
||||
- **无可用提供商** → 语音消息直接传递，并向用户给出准确说明
|
||||
+210
@@ -0,0 +1,210 @@
|
||||
---
|
||||
title: 视觉与图像粘贴
|
||||
description: 将剪贴板中的图像粘贴到 Hermes CLI，进行多模态视觉分析。
|
||||
sidebar_label: 视觉与图像粘贴
|
||||
sidebar_position: 7
|
||||
---
|
||||
|
||||
# 视觉与图像粘贴
|
||||
|
||||
Hermes Agent 支持**多模态视觉**——你可以直接将剪贴板中的图像粘贴到 CLI，让 Agent 对其进行分析、描述或处理。图像以 base64 编码的内容块形式发送给模型，因此任何支持视觉的模型均可处理。
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. 将图像复制到剪贴板（截图、浏览器图片等）
|
||||
2. 使用以下任一方式附加图像
|
||||
3. 输入问题并按 Enter
|
||||
4. 图像以 `[📎 Image #1]` 徽章形式显示在输入框上方
|
||||
5. 提交时，图像作为视觉内容块发送给模型
|
||||
|
||||
发送前可附加多张图像，每张图像都有独立徽章。按 `Ctrl+C` 可清除所有已附加图像。
|
||||
|
||||
图像以带时间戳的 PNG 文件名保存至 `~/.hermes/images/`。
|
||||
|
||||
## 粘贴方式
|
||||
|
||||
附加图像的方式取决于你的终端环境。并非所有方式在所有环境下均可用——以下是完整说明：
|
||||
|
||||
### `/paste` 命令
|
||||
|
||||
**最可靠的显式图像附加备用方案。**
|
||||
|
||||
```
|
||||
/paste
|
||||
```
|
||||
|
||||
输入 `/paste` 并按 Enter。Hermes 会检查剪贴板中是否有图像并附加。当你的终端重写了 `Cmd+V`/`Ctrl+V`，或剪贴板中只有图像而没有 bracketed-paste（括号粘贴）文本载荷可供检查时，这是最安全的选项。
|
||||
|
||||
### Ctrl+V / Cmd+V
|
||||
|
||||
Hermes 现在将粘贴处理为分层流程：
|
||||
- 优先进行普通文本粘贴
|
||||
- 若终端未能正常传递文本，则回退到原生剪贴板 / OSC52 文本
|
||||
- 当剪贴板或粘贴内容解析为图像或图像路径时，附加图像
|
||||
|
||||
这意味着粘贴的 macOS 截图临时路径和 `file://...` 图像 URI 可以立即附加，而不是以原始文本形式留在编辑器中。
|
||||
|
||||
:::warning
|
||||
如果剪贴板中**只有图像**（无文本），终端仍无法直接发送二进制图像字节。请使用 `/paste` 作为显式图像附加的备用方案。
|
||||
:::
|
||||
|
||||
### `/terminal-setup`（适用于 VS Code / Cursor / Windsurf）
|
||||
|
||||
如果你在 macOS 上的 VS Code 系列集成终端中运行 TUI，Hermes 可以安装推荐的 `workbench.action.terminal.sendSequence` 绑定，以获得更好的多行输入及撤销/重做一致性：
|
||||
|
||||
```text
|
||||
/terminal-setup
|
||||
```
|
||||
|
||||
当 `Cmd+Enter`、`Cmd+Z` 或 `Shift+Cmd+Z` 被 IDE 拦截时，此命令尤为有用。仅在本地机器上运行——不要在 SSH 会话中使用。
|
||||
|
||||
## 平台兼容性
|
||||
|
||||
| 环境 | `/paste` | Cmd/Ctrl+V | `/terminal-setup` | 备注 |
|
||||
|---|:---:|:---:|:---:|---|
|
||||
| **macOS Terminal / iTerm2** | ✅ | ✅ | n/a | 最佳体验——原生剪贴板 + 截图路径恢复 |
|
||||
| **Apple Terminal** | ✅ | ✅ | n/a | 若 Cmd+←/→/⌫ 被重写，使用 Ctrl+A / Ctrl+E / Ctrl+U 备用方案 |
|
||||
| **Linux X11 桌面** | ✅ | ✅ | n/a | 需要 `xclip`（`apt install xclip`） |
|
||||
| **Linux Wayland 桌面** | ✅ | ✅ | n/a | 需要 `wl-paste`（`apt install wl-clipboard`） |
|
||||
| **WSL2（Windows Terminal）** | ✅ | ✅ | n/a | 使用 `powershell.exe`——无需额外安装 |
|
||||
| **VS Code / Cursor / Windsurf（本地）** | ✅ | ✅ | ✅ | 推荐，以获得更好的 Cmd+Enter / 撤销 / 重做一致性 |
|
||||
| **VS Code / Cursor / Windsurf（SSH）** | ❌² | ❌² | ❌³ | 请在本地机器上运行 `/terminal-setup` |
|
||||
| **SSH 终端（任意）** | ❌² | ❌² | n/a | 无法访问远程剪贴板 |
|
||||
|
||||
² 参见下方 [SSH 与远程会话](#ssh--remote-sessions)
|
||||
³ 该命令写入本地 IDE 快捷键绑定，不应从远程主机运行
|
||||
|
||||
## 各平台配置说明
|
||||
|
||||
### macOS
|
||||
|
||||
**无需任何配置。** Hermes 使用 `osascript`（macOS 内置）读取剪贴板。如需更快的性能，可选择安装 `pngpaste`：
|
||||
|
||||
```bash
|
||||
brew install pngpaste
|
||||
```
|
||||
|
||||
### Linux（X11）
|
||||
|
||||
安装 `xclip`：
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt install xclip
|
||||
|
||||
# Fedora
|
||||
sudo dnf install xclip
|
||||
|
||||
# Arch
|
||||
sudo pacman -S xclip
|
||||
```
|
||||
|
||||
### Linux（Wayland）
|
||||
|
||||
现代 Linux 桌面（Ubuntu 22.04+、Fedora 34+）通常默认使用 Wayland。安装 `wl-clipboard`：
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt install wl-clipboard
|
||||
|
||||
# Fedora
|
||||
sudo dnf install wl-clipboard
|
||||
|
||||
# Arch
|
||||
sudo pacman -S wl-clipboard
|
||||
```
|
||||
|
||||
:::tip 如何检查是否在使用 Wayland
|
||||
```bash
|
||||
echo $XDG_SESSION_TYPE
|
||||
# "wayland" = Wayland，"x11" = X11，"tty" = 无显示服务器
|
||||
```
|
||||
:::
|
||||
|
||||
### WSL2
|
||||
|
||||
**无需额外配置。** Hermes 通过 `/proc/version` 自动检测 WSL2，并使用 `powershell.exe` 通过 .NET 的 `System.Windows.Forms.Clipboard` 访问 Windows 剪贴板。这是 WSL2 Windows 互操作的内置功能——`powershell.exe` 默认可用。
|
||||
|
||||
剪贴板数据通过 stdout 以 base64 编码的 PNG 格式传输，无需路径转换或临时文件。
|
||||
|
||||
:::info WSLg 说明
|
||||
如果你使用的是 WSLg（带 GUI 支持的 WSL2），Hermes 会优先尝试 PowerShell 路径，然后回退到 `wl-paste`。WSLg 的剪贴板桥接仅支持 BMP 格式的图像——Hermes 会使用 Pillow（如已安装）或 ImageMagick 的 `convert` 命令自动将 BMP 转换为 PNG。
|
||||
:::
|
||||
|
||||
#### 验证 WSL2 剪贴板访问
|
||||
|
||||
```bash
|
||||
# 1. 检查 WSL 检测
|
||||
grep -i microsoft /proc/version
|
||||
|
||||
# 2. 检查 PowerShell 是否可访问
|
||||
which powershell.exe
|
||||
|
||||
# 3. 复制一张图像，然后检查
|
||||
powershell.exe -NoProfile -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Clipboard]::ContainsImage()"
|
||||
# 应输出 "True"
|
||||
```
|
||||
|
||||
## SSH 与远程会话
|
||||
|
||||
**通过 SSH 进行剪贴板图像粘贴无法完全正常工作。** 当你 SSH 到远程机器时，Hermes CLI 运行在远程主机上。剪贴板工具（`xclip`、`wl-paste`、`powershell.exe`、`osascript`）读取的是其所在机器的剪贴板——即远程服务器，而非你的本地机器。因此，本地剪贴板中的图像在远程端无法访问。
|
||||
|
||||
文本有时仍可通过终端粘贴或 OSC52 传输，但图像剪贴板访问和本地截图临时路径始终绑定于运行 Hermes 的机器。
|
||||
|
||||
### SSH 的变通方案
|
||||
|
||||
1. **上传图像文件**——在本地保存图像，通过 `scp`、VSCode 文件浏览器（拖放）或任何文件传输方式上传到远程服务器，然后通过路径引用。*（计划在未来版本中提供 `/attach <filepath>` 命令。）*
|
||||
|
||||
2. **使用 URL**——如果图像可在线访问，直接在消息中粘贴 URL。Agent 可使用 `vision_analyze` 直接查看任意图像 URL。
|
||||
|
||||
3. **X11 转发**——使用 `ssh -X` 连接以转发 X11。这允许远程机器上的 `xclip` 访问你本地的 X11 剪贴板。需要本地运行 X 服务器（macOS 上为 XQuartz，Linux X11 桌面内置）。大图像传输较慢。
|
||||
|
||||
4. **使用消息平台**——通过 Telegram、Discord、Slack 或 WhatsApp 向 Hermes 发送图像。这些平台原生支持图像上传，不受剪贴板/终端限制的影响。
|
||||
|
||||
## 为什么终端无法粘贴图像
|
||||
|
||||
这是一个常见的困惑来源，以下是技术说明：
|
||||
|
||||
终端是**基于文本**的界面。当你按下 Ctrl+V（或 Cmd+V）时，终端模拟器会：
|
||||
|
||||
1. 从剪贴板读取**文本内容**
|
||||
2. 将其包裹在 [bracketed paste](https://en.wikipedia.org/wiki/Bracketed-paste)（括号粘贴）转义序列中
|
||||
3. 通过终端的文本流将其发送给应用程序
|
||||
|
||||
如果剪贴板中只有图像（无文本），终端没有任何内容可发送。目前没有标准的终端转义序列用于传输二进制图像数据，终端会直接忽略。
|
||||
|
||||
这就是为什么 Hermes 使用独立的剪贴板检查——它不通过终端粘贴事件接收图像数据，而是直接通过子进程调用操作系统级工具（`osascript`、`powershell.exe`、`xclip`、`wl-paste`）独立读取剪贴板。
|
||||
|
||||
## 支持的模型
|
||||
|
||||
图像粘贴适用于任何支持视觉的模型。图像以 base64 编码的 data URL 形式，按 OpenAI 视觉内容格式发送：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "image_url",
|
||||
"image_url": {
|
||||
"url": "data:image/png;base64,..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
大多数现代模型支持此格式，包括 GPT-4 Vision、Claude（带视觉）、Gemini，以及通过 OpenRouter 提供服务的开源多模态模型。
|
||||
|
||||
## 图像路由（视觉模型 vs 纯文本模型）
|
||||
|
||||
当用户附加图像时——无论来自 CLI 剪贴板、gateway（Telegram/Discord 图片）还是其他入口——Hermes 会根据当前模型是否支持视觉进行路由：
|
||||
|
||||
| 你的模型 | 图像处理方式 |
|
||||
|---|---|
|
||||
| **支持视觉的模型**（GPT-4V、Claude with vision、Gemini、Qwen-VL、MiMo-VL 等） | 使用上述提供商原生图像内容格式，以**真实像素**发送。无文本摘要层。 |
|
||||
| **纯文本模型**（DeepSeek V3、较小的开源模型、旧版纯对话端点） | 通过 `vision_analyze` 辅助工具路由——辅助视觉模型描述图像，文本描述注入对话。 |
|
||||
|
||||
无需手动配置——Hermes 在提供商元数据中查找当前模型的能力并自动选择正确路径。实际效果：你可以在会话中途切换视觉模型与非视觉模型，图像处理"开箱即用"，无需更改工作流。纯文本模型会获得关于图像的连贯上下文，而不是一个会被拒绝的损坏多模态载荷。
|
||||
|
||||
处理文本描述路径的辅助模型可在 `auxiliary.vision` 下配置——参见[辅助模型](/user-guide/configuration#auxiliary-models)。
|
||||
|
||||
### `vision_analyze` 具有相同的双重行为
|
||||
|
||||
`vision_analyze` 工具本身遵循相同的路由逻辑。当当前主模型支持视觉，**且**其提供商支持在工具结果中包含图像内容（目前为 Anthropic、OpenAI、Azure-OpenAI 和 Gemini 3.x 技术栈），`vision_analyze` 会跳过辅助描述器，直接将原始图像像素作为多模态工具结果信封返回。主模型在下一轮会原生看到图像——无辅助调用、无文本摘要信息损失、无额外延迟。
|
||||
|
||||
对于纯文本主模型（或工具结果通道不支持图像的提供商），`vision_analyze` 回退到旧路径：请求已配置的辅助视觉模型描述图像，并以纯文本形式返回描述。无论哪种情况，调用工具的签名相同——工具在运行时根据当前模型决定采用哪条路径。
|
||||
+520
@@ -0,0 +1,520 @@
|
||||
---
|
||||
sidebar_position: 10
|
||||
title: "语音模式"
|
||||
description: "与 Hermes Agent 进行实时语音对话 — CLI、Telegram、Discord（私信、文字频道和语音频道）"
|
||||
---
|
||||
|
||||
# 语音模式
|
||||
|
||||
Hermes Agent 支持在 CLI 和消息平台上进行完整的语音交互。通过麦克风与 Agent 对话，听取语音回复，并在 Discord 语音频道中进行实时语音对话。
|
||||
|
||||
如需包含推荐配置和实际使用模式的实践指南，请参阅 [使用 Hermes 的语音模式](/guides/use-voice-mode-with-hermes)。
|
||||
|
||||
## 前提条件
|
||||
|
||||
使用语音功能前，请确保已完成以下准备：
|
||||
|
||||
1. **已安装 Hermes Agent** — `pip install hermes-agent`（参见 [安装](/getting-started/installation)）
|
||||
2. **已配置 LLM 提供商** — 运行 `hermes model` 或在 `~/.hermes/.env` 中设置首选提供商的凭据
|
||||
3. **基础设置正常** — 运行 `hermes` 验证 Agent 能够响应文字消息，再启用语音功能
|
||||
|
||||
:::tip
|
||||
`~/.hermes/` 目录和默认的 `config.yaml` 会在首次运行 `hermes` 时自动创建。只需手动创建 `~/.hermes/.env` 来存放 API 密钥。
|
||||
:::
|
||||
|
||||
:::tip Nous Portal 同时覆盖两项
|
||||
付费的 [Nous Portal](/user-guide/features/tool-gateway) 订阅通过 Tool Gateway 同时提供 LLM（第 2 步）**和** OpenAI TTS — 无需单独的 OpenAI 密钥。全新安装时，`hermes setup --portal` 可一次性完成两项配置。
|
||||
:::
|
||||
|
||||
## 概览
|
||||
|
||||
| 功能 | 平台 | 说明 |
|
||||
|---------|----------|-------------|
|
||||
| **交互式语音** | CLI | 按 Ctrl+B 开始录音，Agent 自动检测静音并回复 |
|
||||
| **自动语音回复** | Telegram、Discord | Agent 在文字回复的同时发送语音音频 |
|
||||
| **语音频道** | Discord | Bot 加入语音频道，监听用户发言并语音回复 |
|
||||
|
||||
## 环境要求
|
||||
|
||||
### Python 包
|
||||
|
||||
```bash
|
||||
# CLI 语音模式（麦克风 + 音频播放）
|
||||
pip install "hermes-agent[voice]"
|
||||
|
||||
# Discord + Telegram 消息（包含 discord.py[voice] 以支持语音频道）
|
||||
pip install "hermes-agent[messaging]"
|
||||
|
||||
# 高级 TTS（ElevenLabs）
|
||||
pip install "hermes-agent[tts-premium]"
|
||||
|
||||
# 本地 TTS（NeuTTS，可选）
|
||||
python -m pip install -U neutts[all]
|
||||
|
||||
# 一次性安装所有内容
|
||||
pip install "hermes-agent[all]"
|
||||
```
|
||||
|
||||
| 扩展包 | 包含的包 | 用途 |
|
||||
|-------|----------|-------------|
|
||||
| `voice` | `sounddevice`、`numpy` | CLI 语音模式 |
|
||||
| `messaging` | `discord.py[voice]`、`python-telegram-bot`、`aiohttp` | Discord 和 Telegram 机器人 |
|
||||
| `tts-premium` | `elevenlabs` | ElevenLabs TTS 提供商 |
|
||||
|
||||
可选本地 TTS 提供商：使用 `python -m pip install -U neutts[all]` 单独安装 `neutts`。首次使用时会自动下载模型。
|
||||
|
||||
:::info
|
||||
`discord.py[voice]` 会自动安装 **PyNaCl**（用于语音加密）和 **opus 绑定**。这是 Discord 语音频道支持的必要条件。
|
||||
:::
|
||||
|
||||
### 系统依赖
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install portaudio ffmpeg opus
|
||||
brew install espeak-ng # for NeuTTS
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt install portaudio19-dev ffmpeg libopus0
|
||||
sudo apt install espeak-ng # for NeuTTS
|
||||
```
|
||||
|
||||
| 依赖项 | 用途 | 适用场景 |
|
||||
|-----------|---------|-------------|
|
||||
| **PortAudio** | 麦克风输入和音频播放 | CLI 语音模式 |
|
||||
| **ffmpeg** | 音频格式转换（MP3 → Opus、PCM → WAV） | 所有平台 |
|
||||
| **Opus** | Discord 语音编解码器 | Discord 语音频道 |
|
||||
| **espeak-ng** | Phonemizer 后端 | 本地 NeuTTS 提供商 |
|
||||
|
||||
### API 密钥
|
||||
|
||||
添加到 `~/.hermes/.env`：
|
||||
|
||||
```bash
|
||||
# 语音转文字（STT）— 本地提供商完全不需要密钥
|
||||
# pip install faster-whisper # 免费，本地运行，推荐
|
||||
GROQ_API_KEY=your-key # Groq Whisper — 速度快，有免费额度（云端）
|
||||
VOICE_TOOLS_OPENAI_KEY=your-key # OpenAI Whisper — 付费（云端）
|
||||
|
||||
# 文字转语音（TTS，可选 — Edge TTS 和 NeuTTS 无需任何密钥）
|
||||
ELEVENLABS_API_KEY=*** # ElevenLabs — 高级音质
|
||||
# 上方的 VOICE_TOOLS_OPENAI_KEY 同时启用 OpenAI TTS
|
||||
```
|
||||
|
||||
:::tip
|
||||
如果已安装 `faster-whisper`，语音模式的 STT 无需任何 API 密钥即可运行。模型（`base` 约 150 MB）会在首次使用时自动下载。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## CLI 语音模式
|
||||
|
||||
语音模式在**经典 CLI**（`hermes chat`）和 **TUI**（`hermes --tui`）中均可使用。两者行为完全一致 — 相同的斜杠命令、相同的 VAD（语音活动检测）静音检测、相同的流式 TTS、相同的幻觉过滤器。TUI 额外将崩溃诊断日志转发至 `~/.hermes/logs/`，以便在异常音频后端出现按键录音失败时提供完整堆栈跟踪，而非静默消失。
|
||||
|
||||
### 快速开始
|
||||
|
||||
启动 CLI 并启用语音模式：
|
||||
|
||||
```bash
|
||||
hermes # 启动交互式 CLI
|
||||
```
|
||||
|
||||
然后在 CLI 中使用以下命令：
|
||||
|
||||
```
|
||||
/voice 切换语音模式开/关
|
||||
/voice on 启用语音模式
|
||||
/voice off 禁用语音模式
|
||||
/voice tts 切换 TTS 输出
|
||||
/voice status 显示当前状态
|
||||
```
|
||||
|
||||
### 工作原理
|
||||
|
||||
1. 使用 `hermes` 启动 CLI，并通过 `/voice on` 启用语音模式
|
||||
2. **按下 Ctrl+B** — 播放提示音（880Hz），开始录音
|
||||
3. **开始说话** — 实时音频电平条显示输入状态：`● [▁▂▃▅▇▇▅▂] ❯`
|
||||
4. **停止说话** — 静音 3 秒后自动停止录音
|
||||
5. **两声提示音**（660Hz）确认录音结束
|
||||
6. 音频通过 Whisper 转录后发送给 Agent
|
||||
7. 如果启用了 TTS，Agent 的回复将以语音朗读
|
||||
8. 录音**自动重新开始** — 无需按任何键即可继续说话
|
||||
|
||||
此循环持续进行，直到在录音过程中按下 **Ctrl+B**（退出连续模式），或连续 3 次录音均未检测到语音为止。
|
||||
|
||||
:::tip
|
||||
录音键可通过 `~/.hermes/config.yaml` 中的 `voice.record_key` 配置（默认：`ctrl+b`）。
|
||||
:::
|
||||
|
||||
### 静音检测
|
||||
|
||||
两阶段算法检测您是否已停止说话：
|
||||
|
||||
1. **语音确认** — 等待音频 RMS 值超过阈值（200）至少 0.3 秒，允许音节间的短暂停顿
|
||||
2. **结束检测** — 语音确认后，持续静音 3.0 秒即触发停止
|
||||
|
||||
如果 15 秒内完全未检测到语音，录音自动停止。
|
||||
|
||||
`silence_threshold` 和 `silence_duration` 均可在 `config.yaml` 中配置。也可通过 `voice.beep_enabled: false` 禁用录音开始/结束提示音。
|
||||
|
||||
### 流式 TTS
|
||||
|
||||
启用 TTS 后，Agent 在生成文字的同时**逐句**朗读回复 — 无需等待完整响应：
|
||||
|
||||
1. 将文字增量缓冲为完整句子（最少 20 个字符）
|
||||
2. 去除 Markdown 格式和 `<think>` 块
|
||||
3. 实时逐句生成并播放音频
|
||||
|
||||
### 幻觉过滤器
|
||||
|
||||
Whisper 有时会从静音或背景噪音中生成幻觉文字（如"Thank you for watching"、"Subscribe"等）。Agent 使用包含 26 个已知幻觉短语（覆盖多种语言）的列表以及能捕获重复变体的正则表达式模式对其进行过滤。
|
||||
|
||||
---
|
||||
|
||||
## Gateway 语音回复（Telegram 和 Discord）
|
||||
|
||||
如果尚未设置消息机器人，请参阅对应平台的指南：
|
||||
- [Telegram 设置指南](../messaging/telegram.md)
|
||||
- [Discord 设置指南](../messaging/discord.md)
|
||||
|
||||
启动 gateway 以连接到消息平台：
|
||||
|
||||
```bash
|
||||
hermes gateway # 启动 gateway（连接到已配置的平台）
|
||||
hermes gateway setup # 首次配置的交互式设置向导
|
||||
```
|
||||
|
||||
### Discord：频道与私信
|
||||
|
||||
Bot 在 Discord 上支持两种交互模式：
|
||||
|
||||
| 模式 | 交互方式 | 是否需要 @提及 | 设置 |
|
||||
|------|------------|-----------------|-------|
|
||||
| **私信（DM）** | 打开 Bot 的个人资料 → "发消息" | 否 | 立即可用 |
|
||||
| **服务器频道** | 在 Bot 所在的文字频道中发言 | 是（`@botname`） | Bot 必须被邀请到服务器 |
|
||||
|
||||
**私信（个人使用推荐）：** 直接与 Bot 开启私信并发送消息 — 无需 @提及。语音回复和所有命令与在频道中使用完全相同。
|
||||
|
||||
**服务器频道：** Bot 仅在被 @提及时响应（例如 `@hermesbyt4 你好`）。请确保从提及弹窗中选择 **Bot 用户**，而非同名角色。
|
||||
|
||||
:::tip
|
||||
如需在服务器频道中禁用提及要求，在 `~/.hermes/.env` 中添加：
|
||||
```bash
|
||||
DISCORD_REQUIRE_MENTION=false
|
||||
```
|
||||
或将特定频道设置为自由响应模式（无需提及）：
|
||||
```bash
|
||||
DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321
|
||||
```
|
||||
:::
|
||||
|
||||
### 命令
|
||||
|
||||
以下命令在 Telegram 和 Discord（私信和文字频道）中均可使用：
|
||||
|
||||
```
|
||||
/voice 切换语音模式开/关
|
||||
/voice on 仅在您发送语音消息时回复语音
|
||||
/voice tts 对所有消息回复语音
|
||||
/voice off 禁用语音回复
|
||||
/voice status 显示当前设置
|
||||
```
|
||||
|
||||
### 模式
|
||||
|
||||
| 模式 | 命令 | 行为 |
|
||||
|------|---------|----------|
|
||||
| `off` | `/voice off` | 仅文字（默认） |
|
||||
| `voice_only` | `/voice on` | 仅当您发送语音消息时才语音回复 |
|
||||
| `all` | `/voice tts` | 对每条消息均语音回复 |
|
||||
|
||||
语音模式设置在 gateway 重启后保持不变。
|
||||
|
||||
### 平台投递
|
||||
|
||||
| 平台 | 格式 | 说明 |
|
||||
|----------|--------|-------|
|
||||
| **Telegram** | 语音气泡（Opus/OGG） | 在聊天中内联播放。如需要，ffmpeg 将 MP3 转换为 Opus |
|
||||
| **Discord** | 原生语音气泡（Opus/OGG） | 像用户语音消息一样内联播放。如语音气泡 API 失败则回退为文件附件 |
|
||||
|
||||
---
|
||||
|
||||
## Discord 语音频道
|
||||
|
||||
最具沉浸感的语音功能：Bot 加入 Discord 语音频道，监听用户发言，转录语音，通过 Agent 处理后，在语音频道中语音回复。
|
||||
|
||||
### 设置
|
||||
|
||||
#### 1. Discord Bot 权限
|
||||
|
||||
如果您已为文字功能设置了 Discord Bot（参见 [Discord 设置指南](../messaging/discord.md)），需要额外添加语音权限。
|
||||
|
||||
前往 [Discord 开发者门户](https://discord.com/developers/applications) → 您的应用 → **Installation** → **Default Install Settings** → **Guild Install**：
|
||||
|
||||
**在现有文字权限基础上添加以下权限：**
|
||||
|
||||
| 权限 | 用途 | 是否必需 |
|
||||
|-----------|---------|----------|
|
||||
| **Connect** | 加入语音频道 | 是 |
|
||||
| **Speak** | 在语音频道中播放 TTS 音频 | 是 |
|
||||
| **Use Voice Activity** | 检测用户是否正在说话 | 推荐 |
|
||||
|
||||
**更新后的权限整数：**
|
||||
|
||||
| 级别 | 整数 | 包含内容 |
|
||||
|-------|---------|----------------|
|
||||
| 仅文字 | `274878286912` | 查看频道、发送消息、读取历史、嵌入内容、附件、帖子、反应 |
|
||||
| 文字 + 语音 | `274881432640` | 以上所有 + Connect、Speak |
|
||||
|
||||
**使用更新后的权限 URL 重新邀请 Bot：**
|
||||
|
||||
```
|
||||
https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274881432640
|
||||
```
|
||||
|
||||
将 `YOUR_APP_ID` 替换为开发者门户中的应用 ID。
|
||||
|
||||
:::warning
|
||||
将 Bot 重新邀请到已加入的服务器只会更新其权限，不会将其移除。不会丢失任何数据或配置。
|
||||
:::
|
||||
|
||||
#### 2. 特权 Gateway Intents
|
||||
|
||||
在 [开发者门户](https://discord.com/developers/applications) → 您的应用 → **Bot** → **Privileged Gateway Intents** 中，启用以下三项：
|
||||
|
||||
| Intent | 用途 |
|
||||
|--------|---------|
|
||||
| **Presence Intent** | 检测用户在线/离线状态 |
|
||||
| **Server Members Intent** | 将 `DISCORD_ALLOWED_USERS` 中的用户名解析为数字 ID（条件性） |
|
||||
| **Message Content Intent** | 读取频道中的文字消息内容 |
|
||||
|
||||
**Message Content Intent** 为必需项。**Server Members Intent** 仅在 `DISCORD_ALLOWED_USERS` 列表使用用户名时才需要 — 如果使用数字用户 ID，可以关闭。语音频道中 SSRC → user_id 的映射来自 Discord 语音 WebSocket 上的 SPEAKING opcode，**不**需要 Server Members Intent。
|
||||
|
||||
#### 3. Opus 编解码器
|
||||
|
||||
运行 gateway 的机器上必须安装 Opus 编解码器库：
|
||||
|
||||
```bash
|
||||
# macOS (Homebrew)
|
||||
brew install opus
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt install libopus0
|
||||
```
|
||||
|
||||
Bot 会从以下路径自动加载编解码器：
|
||||
- **macOS：** `/opt/homebrew/lib/libopus.dylib`
|
||||
- **Linux：** `libopus.so.0`
|
||||
|
||||
#### 4. 环境变量
|
||||
|
||||
```bash
|
||||
# ~/.hermes/.env
|
||||
|
||||
# Discord bot（已为文字功能配置）
|
||||
DISCORD_BOT_TOKEN=your-bot-token
|
||||
DISCORD_ALLOWED_USERS=your-user-id
|
||||
|
||||
# STT — 本地提供商无需密钥（pip install faster-whisper）
|
||||
# GROQ_API_KEY=your-key # 替代方案：云端，速度快，有免费额度
|
||||
|
||||
# TTS — 可选。Edge TTS 和 NeuTTS 无需密钥。
|
||||
# ELEVENLABS_API_KEY=*** # 高级音质
|
||||
# VOICE_TOOLS_OPENAI_KEY=*** # OpenAI TTS / Whisper
|
||||
```
|
||||
|
||||
### 启动 Gateway
|
||||
|
||||
```bash
|
||||
hermes gateway # 使用现有配置启动
|
||||
```
|
||||
|
||||
Bot 应在几秒内在 Discord 中上线。
|
||||
|
||||
### 命令
|
||||
|
||||
在 Bot 所在的 Discord 文字频道中使用以下命令：
|
||||
|
||||
```
|
||||
/voice join Bot 加入您当前所在的语音频道
|
||||
/voice channel /voice join 的别名
|
||||
/voice leave Bot 断开语音频道连接
|
||||
/voice status 显示语音模式和已连接的频道
|
||||
```
|
||||
|
||||
:::info
|
||||
运行 `/voice join` 前，您必须已在某个语音频道中。Bot 会加入您所在的语音频道。
|
||||
:::
|
||||
|
||||
### 工作原理
|
||||
|
||||
Bot 加入语音频道后：
|
||||
|
||||
1. **独立监听**每位用户的音频流
|
||||
2. **检测静音** — 至少 0.5 秒语音后出现 1.5 秒静音即触发处理
|
||||
3. **转录**音频（通过本地、Groq 或 OpenAI 的 Whisper STT）
|
||||
4. **处理**完整的 Agent 流水线（会话、工具、记忆）
|
||||
5. **语音回复**通过 TTS 在语音频道中播放
|
||||
|
||||
### 文字频道集成
|
||||
|
||||
Bot 在语音频道中时：
|
||||
|
||||
- 转录内容会出现在文字频道中：`[Voice] @user: 您说的内容`
|
||||
- Agent 回复同时以文字发送到频道并在语音频道中朗读
|
||||
- 文字频道为发出 `/voice join` 命令的那个频道
|
||||
|
||||
### 回声消除
|
||||
|
||||
Bot 在播放 TTS 回复时会自动暂停音频监听，防止听到并重复处理自身的输出。
|
||||
|
||||
### 访问控制
|
||||
|
||||
只有 `DISCORD_ALLOWED_USERS` 中列出的用户才能通过语音进行交互。其他用户的音频会被静默忽略。
|
||||
|
||||
```bash
|
||||
# ~/.hermes/.env
|
||||
DISCORD_ALLOWED_USERS=284102345871466496
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 配置参考
|
||||
|
||||
### config.yaml
|
||||
|
||||
```yaml
|
||||
# 语音录制（CLI）
|
||||
voice:
|
||||
record_key: "ctrl+b" # 开始/停止录音的按键
|
||||
max_recording_seconds: 120 # 最大录音时长
|
||||
auto_tts: false # 启用语音模式时自动开启 TTS
|
||||
beep_enabled: true # 播放录音开始/结束提示音
|
||||
silence_threshold: 200 # 静音判定的 RMS 电平（0-32767）
|
||||
silence_duration: 3.0 # 自动停止前的静音秒数
|
||||
|
||||
# 语音转文字（STT）
|
||||
stt:
|
||||
enabled: true # 设为 false 可跳过自动转录 —
|
||||
# gateway 仍会缓存音频文件并将其路径
|
||||
# 作为入站消息的一部分传递给 Agent，
|
||||
# 适用于自定义流水线
|
||||
# （说话人分离、对齐、归档等）
|
||||
provider: "local" # "local"（免费）| "groq" | "openai" | "mistral" | "xai"
|
||||
local:
|
||||
model: "base" # tiny, base, small, medium, large-v3
|
||||
# model: "whisper-1" # 旧版：在未设置 provider 时使用
|
||||
|
||||
# 文字转语音（TTS）
|
||||
tts:
|
||||
provider: "edge" # "edge"（免费）| "elevenlabs" | "openai" | "neutts" | "minimax" | "mistral" | "gemini" | "xai" | "kittentts" | "piper"
|
||||
edge:
|
||||
voice: "en-US-AriaNeural" # 322 种声音，74 种语言
|
||||
elevenlabs:
|
||||
voice_id: "pNInz6obpgDQGcFmaJgB" # Adam
|
||||
model_id: "eleven_multilingual_v2"
|
||||
openai:
|
||||
model: "gpt-4o-mini-tts"
|
||||
voice: "alloy" # alloy, echo, fable, onyx, nova, shimmer
|
||||
base_url: "https://api.openai.com/v1" # 可选：覆盖为自托管或兼容 OpenAI 的端点
|
||||
neutts:
|
||||
ref_audio: ''
|
||||
ref_text: ''
|
||||
model: neuphonic/neutts-air-q4-gguf
|
||||
device: cpu
|
||||
```
|
||||
|
||||
### 环境变量
|
||||
|
||||
```bash
|
||||
# 语音转文字提供商（本地无需密钥）
|
||||
# pip install faster-whisper # 免费本地 STT — 无需 API 密钥
|
||||
GROQ_API_KEY=... # Groq Whisper（速度快，有免费额度）
|
||||
VOICE_TOOLS_OPENAI_KEY=... # OpenAI Whisper（付费）
|
||||
|
||||
# STT 高级覆盖（可选）
|
||||
STT_GROQ_MODEL=whisper-large-v3-turbo # 覆盖默认 Groq STT 模型
|
||||
STT_OPENAI_MODEL=whisper-1 # 覆盖默认 OpenAI STT 模型
|
||||
GROQ_BASE_URL=https://api.groq.com/openai/v1 # 自定义 Groq 端点
|
||||
STT_OPENAI_BASE_URL=https://api.openai.com/v1 # 自定义 OpenAI STT 端点
|
||||
|
||||
# 文字转语音提供商（Edge TTS 和 NeuTTS 无需密钥）
|
||||
ELEVENLABS_API_KEY=*** # ElevenLabs（高级音质）
|
||||
# 上方的 VOICE_TOOLS_OPENAI_KEY 同时启用 OpenAI TTS
|
||||
|
||||
# Discord 语音频道
|
||||
DISCORD_BOT_TOKEN=...
|
||||
DISCORD_ALLOWED_USERS=...
|
||||
```
|
||||
|
||||
### STT 提供商对比
|
||||
|
||||
| 提供商 | 模型 | 速度 | 质量 | 费用 | 需要 API 密钥 |
|
||||
|----------|-------|-------|---------|------|---------|
|
||||
| **本地** | `base` | 快（取决于 CPU/GPU） | 良好 | 免费 | 否 |
|
||||
| **本地** | `small` | 中等 | 较好 | 免费 | 否 |
|
||||
| **本地** | `large-v3` | 慢 | 最佳 | 免费 | 否 |
|
||||
| **Groq** | `whisper-large-v3-turbo` | 非常快（约 0.5 秒） | 良好 | 免费额度 | 是 |
|
||||
| **Groq** | `whisper-large-v3` | 快（约 1 秒） | 较好 | 免费额度 | 是 |
|
||||
| **OpenAI** | `whisper-1` | 快（约 1 秒） | 良好 | 付费 | 是 |
|
||||
| **OpenAI** | `gpt-4o-transcribe` | 中等（约 2 秒） | 最佳 | 付费 | 是 |
|
||||
|
||||
提供商优先级（自动回退）：**本地** > **groq** > **openai**
|
||||
|
||||
### TTS 提供商对比
|
||||
|
||||
| 提供商 | 质量 | 费用 | 延迟 | 需要密钥 |
|
||||
|----------|---------|------|---------|-------------|
|
||||
| **Edge TTS** | 良好 | 免费 | 约 1 秒 | 否 |
|
||||
| **ElevenLabs** | 优秀 | 付费 | 约 2 秒 | 是 |
|
||||
| **OpenAI TTS** | 良好 | 付费 | 约 1.5 秒 | 是 |
|
||||
| **NeuTTS** | 良好 | 免费 | 取决于 CPU/GPU | 否 |
|
||||
|
||||
NeuTTS 使用上方的 `tts.neutts` 配置块。
|
||||
|
||||
---
|
||||
|
||||
## 故障排查
|
||||
|
||||
### "No audio device found"（CLI）
|
||||
|
||||
PortAudio 未安装：
|
||||
|
||||
```bash
|
||||
brew install portaudio # macOS
|
||||
sudo apt install portaudio19-dev # Ubuntu
|
||||
```
|
||||
|
||||
### Bot 在 Discord 服务器频道中不响应
|
||||
|
||||
Bot 在服务器频道中默认需要 @提及。请确认：
|
||||
|
||||
1. 输入 `@` 后选择 **Bot 用户**（带有 #discriminator），而非同名**角色**
|
||||
2. 或改用私信 — 无需提及
|
||||
3. 或在 `~/.hermes/.env` 中设置 `DISCORD_REQUIRE_MENTION=false`
|
||||
|
||||
### Bot 加入语音频道但听不到我说话
|
||||
|
||||
- 检查您的 Discord 用户 ID 是否在 `DISCORD_ALLOWED_USERS` 中
|
||||
- 确认您在 Discord 中未被静音
|
||||
- Bot 需要收到 Discord 的 SPEAKING 事件才能映射您的音频 — 加入后请在几秒内开始说话
|
||||
|
||||
### Bot 能听到我说话但不响应
|
||||
|
||||
- 验证 STT 是否可用：安装 `faster-whisper`（无需密钥）或设置 `GROQ_API_KEY` / `VOICE_TOOLS_OPENAI_KEY`
|
||||
- 检查 LLM 模型是否已配置且可访问
|
||||
- 查看 gateway 日志：`tail -f ~/.hermes/logs/gateway.log`
|
||||
|
||||
### Bot 有文字回复但语音频道中没有声音
|
||||
|
||||
- TTS 提供商可能出现故障 — 检查 API 密钥和配额
|
||||
- Edge TTS（免费，无需密钥）是默认回退选项
|
||||
- 检查日志中的 TTS 错误
|
||||
|
||||
### Whisper 返回乱码文字
|
||||
|
||||
幻觉过滤器会自动处理大多数情况。如果仍然出现幻觉转录：
|
||||
|
||||
- 在更安静的环境中使用
|
||||
- 在配置中调高 `silence_threshold`（值越高，灵敏度越低）
|
||||
- 尝试不同的 STT 模型
|
||||
+351
@@ -0,0 +1,351 @@
|
||||
---
|
||||
sidebar_position: 15
|
||||
title: "Web Dashboard"
|
||||
description: "基于浏览器的仪表板，用于管理配置、API 密钥、会话、日志、分析、定时任务和技能"
|
||||
---
|
||||
|
||||
# Web Dashboard
|
||||
|
||||
Web Dashboard 是一个基于浏览器的 UI，用于管理你的 Hermes Agent 安装。无需编辑 YAML 文件或运行 CLI 命令，即可通过简洁的 Web 界面配置设置、管理 API 密钥并监控会话。
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
hermes dashboard
|
||||
```
|
||||
|
||||
这将启动一个本地 Web 服务器，并在浏览器中打开 `http://127.0.0.1:9119`。Dashboard 完全在你的机器上运行——数据不会离开 localhost。
|
||||
|
||||
### 选项
|
||||
|
||||
| 标志 | 默认值 | 描述 |
|
||||
|------|---------|-------------|
|
||||
| `--port` | `9119` | Web 服务器运行端口 |
|
||||
| `--host` | `127.0.0.1` | 绑定地址 |
|
||||
| `--no-open` | — | 不自动打开浏览器 |
|
||||
| `--insecure` | 关闭 | 允许绑定到非 localhost 主机（**危险**——会在网络上暴露 API 密钥；请配合防火墙和强认证使用） |
|
||||
|
||||
```bash
|
||||
# 自定义端口
|
||||
hermes dashboard --port 8080
|
||||
|
||||
# 绑定到所有接口（在共享网络上请谨慎使用）
|
||||
hermes dashboard --host 0.0.0.0
|
||||
|
||||
# 启动时不打开浏览器
|
||||
hermes dashboard --no-open
|
||||
```
|
||||
|
||||
## 前置条件
|
||||
|
||||
默认的 `hermes-agent` 安装不包含 HTTP 栈或 PTY 辅助工具——这些是可选扩展。**Web Dashboard** 需要 FastAPI 和 Uvicorn（`web` 扩展）。**Chat** 标签页还需要 `ptyprocess` 来在伪终端（pseudo-terminal）后面启动嵌入式 TUI（POSIX 上的 `pty` 扩展）。使用以下命令同时安装：
|
||||
|
||||
```bash
|
||||
pip install 'hermes-agent[web,pty]'
|
||||
```
|
||||
|
||||
`web` 扩展会引入 FastAPI/Uvicorn；`pty` 扩展会引入 `ptyprocess`（POSIX）或 `pywinpty`（原生 Windows——注意嵌入式 TUI 本身仍需要 WSL）。`pip install hermes-agent[all]` 包含两个扩展，如果你还需要消息/语音等功能，这是最简便的方式。
|
||||
|
||||
在没有依赖项的情况下运行 `hermes dashboard` 时，它会告诉你需要安装什么。如果前端尚未构建且 `npm` 可用，则会在首次启动时自动构建。
|
||||
|
||||
Chat 标签页是每次 `hermes dashboard` 启动的一部分——内嵌的浏览器聊天面板（通过 PTY/WebSocket 运行 TUI）始终可用，无需任何额外参数。
|
||||
|
||||
## 页面
|
||||
|
||||
### Status（状态）
|
||||
|
||||
首页显示你的安装的实时概览：
|
||||
|
||||
- **Agent 版本**和发布日期
|
||||
- **Gateway 状态**——运行中/已停止、PID、已连接平台及其状态
|
||||
- **活跃会话**——过去 5 分钟内活跃的会话数量
|
||||
- **最近会话**——最近 20 个会话的列表，包含模型、消息数、token 用量和对话预览
|
||||
|
||||
状态页每 5 秒自动刷新一次。
|
||||
|
||||
### Chat（聊天）
|
||||
|
||||
**Chat** 标签页将完整的 Hermes TUI（与 `hermes --tui` 相同的界面）直接嵌入浏览器。你在终端 TUI 中能做的一切——斜杠命令、模型选择器、工具调用卡片、Markdown 流式输出、clarify/sudo/approval 提示、皮肤主题——在这里都完全一致，因为 Dashboard 运行的是真实的 TUI 二进制文件，并通过 [xterm.js](https://xtermjs.org/) 的 WebGL 渲染器以像素级精度渲染其 ANSI 输出。
|
||||
|
||||
**工作原理：**
|
||||
|
||||
- `/api/pty` 打开一个经 Dashboard 会话 token 认证的 WebSocket
|
||||
- 服务器在 POSIX 伪终端后面启动 `hermes --tui`
|
||||
- 按键传输到 PTY；ANSI 输出流式返回浏览器
|
||||
- xterm.js 的 WebGL 渲染器将每个单元格绘制到整数像素网格；鼠标追踪（SGR 1006）、宽字符（Unicode 11）和方框绘制字形均原生渲染
|
||||
- 调整浏览器窗口大小会通过 `@xterm/addon-fit` 插件调整 TUI 大小
|
||||
|
||||
**恢复已有会话：** 在 **Sessions** 标签页中，点击任意会话旁的播放图标（▶）。这会跳转到 `/chat?resume=<id>` 并以 `--resume` 参数启动 TUI，加载完整历史记录。
|
||||
|
||||
**前置条件：**
|
||||
|
||||
- Node.js（与 `hermes --tui` 相同的要求；TUI 包在首次启动时构建）
|
||||
- `ptyprocess`——由 `pty` 扩展安装（`pip install 'hermes-agent[web,pty]'`，或 `[all]` 同时包含两者）
|
||||
- POSIX 内核（Linux、macOS 或 WSL2）。`/chat` 终端面板特别需要 POSIX PTY——原生 Windows Python 没有等效实现，因此在原生 Windows 安装上，Dashboard 的其余部分（sessions、jobs、metrics、config editor）可以正常工作，但 `/chat` 标签页会显示提示，告知你需要使用 WSL2 才能使用该功能。
|
||||
|
||||
关闭浏览器标签页后，PTY 会在服务器端被干净地回收。重新打开会启动一个新会话。
|
||||
|
||||
### Config（配置）
|
||||
|
||||
`config.yaml` 的表单式编辑器。所有 150+ 个配置字段均从 `DEFAULT_CONFIG` 自动发现，并按标签页分类组织：
|
||||
|
||||
- **model** — 默认模型、提供商、基础 URL、推理设置
|
||||
- **terminal** — 后端（local/docker/ssh/modal）、超时、Shell 偏好
|
||||
- **display** — 皮肤、工具进度、恢复显示、spinner 设置
|
||||
- **agent** — 最大迭代次数、gateway 超时、服务层级
|
||||
- **delegation** — 子 agent 限制、推理力度
|
||||
- **memory** — 提供商选择、上下文注入设置
|
||||
- **approvals** — 危险命令审批模式（ask/yolo/deny）
|
||||
- 更多——config.yaml 的每个部分都有对应的表单字段
|
||||
|
||||
具有已知有效值的字段（terminal 后端、皮肤、审批模式等）渲染为下拉菜单。布尔值渲染为开关。其余均为文本输入框。
|
||||
|
||||
**操作：**
|
||||
|
||||
- **Save** — 立即将更改写入 `config.yaml`
|
||||
- **Reset to defaults** — 将所有字段恢复为默认值（点击 Save 前不会保存）
|
||||
- **Export** — 将当前配置下载为 JSON
|
||||
- **Import** — 上传 JSON 配置文件以替换当前值
|
||||
|
||||
:::tip
|
||||
配置更改在下一次 agent 会话或 gateway 重启时生效。Web Dashboard 编辑的是 `hermes config set` 和 gateway 读取的同一个 `config.yaml` 文件。
|
||||
:::
|
||||
|
||||
### API Keys（API 密钥）
|
||||
|
||||
管理存储 API 密钥和凭据的 `.env` 文件。密钥按类别分组：
|
||||
|
||||
- **LLM Providers** — OpenRouter、Anthropic、OpenAI、DeepSeek 等
|
||||
- **Tool API Keys** — Browserbase、Firecrawl、Tavily、ElevenLabs 等
|
||||
- **Messaging Platforms** — Telegram、Discord、Slack bot token 等
|
||||
- **Agent Settings** — 非敏感环境变量，如 `API_SERVER_ENABLED`
|
||||
|
||||
每个密钥显示：
|
||||
- 是否已设置（带有值的脱敏预览）
|
||||
- 用途说明
|
||||
- 提供商注册/密钥页面的链接
|
||||
- 用于设置或更新值的输入框
|
||||
- 删除按钮
|
||||
|
||||
高级/不常用的密钥默认隐藏，可通过开关显示。
|
||||
|
||||
### Sessions（会话）
|
||||
|
||||
浏览和检查所有 agent 会话。每行显示会话标题、来源平台图标（CLI、Telegram、Discord、Slack、cron）、模型名称、消息数、工具调用数以及最后活跃时间。实时会话以脉冲徽章标记。
|
||||
|
||||
- **Search** — 使用 FTS5 对所有消息内容进行全文搜索。结果显示高亮片段，展开时自动滚动到第一条匹配消息。
|
||||
- **Expand** — 点击会话以加载完整消息历史。消息按角色（user、assistant、system、tool）用颜色区分，并以带语法高亮的 Markdown 渲染。
|
||||
- **Tool calls** — 包含工具调用的 assistant 消息显示可折叠块，包含函数名和 JSON 参数。
|
||||
- **Delete** — 使用垃圾桶图标删除会话及其消息历史。
|
||||
|
||||
### Logs（日志）
|
||||
|
||||
查看 agent、gateway 和错误日志文件，支持过滤和实时追踪。
|
||||
|
||||
- **File** — 在 `agent`、`errors` 和 `gateway` 日志文件之间切换
|
||||
- **Level** — 按日志级别过滤：ALL、DEBUG、INFO、WARNING 或 ERROR
|
||||
- **Component** — 按来源组件过滤：all、gateway、agent、tools、cli 或 cron
|
||||
- **Lines** — 选择显示行数（50、100、200 或 500）
|
||||
- **Auto-refresh** — 切换实时追踪，每 5 秒轮询新日志行
|
||||
- **Color-coded** — 日志行按严重程度着色（错误为红色，警告为黄色，debug 为暗色）
|
||||
|
||||
### Analytics（分析）
|
||||
|
||||
基于会话历史计算的用量和成本分析。选择时间段（7、30 或 90 天）查看：
|
||||
|
||||
- **Summary cards** — 总 token 数（输入/输出）、缓存命中率、总估算或实际成本，以及总会话数和日均值
|
||||
- **Daily token chart** — 堆叠柱状图，显示每日输入和输出 token 用量，悬停提示显示明细和成本
|
||||
- **Daily breakdown table** — 每日日期、会话数、输入 token、输出 token、缓存命中率和成本
|
||||
- **Per-model breakdown** — 显示每个使用模型的会话数、token 用量和估算成本的表格
|
||||
|
||||
### Cron（定时任务）
|
||||
|
||||
创建和管理按定期计划运行 agent prompt 的定时任务。
|
||||
|
||||
- **Create** — 填写名称（可选）、prompt、cron 表达式（如 `0 9 * * *`）和投递目标（local、Telegram、Discord、Slack 或 email）
|
||||
- **Job list** — 每个任务显示其名称、prompt 预览、计划表达式、状态徽章（enabled/paused/error）、投递目标、上次运行时间和下次运行时间
|
||||
- **Pause / Resume** — 在活跃和暂停状态之间切换任务
|
||||
- **Trigger now** — 在正常计划之外立即执行任务
|
||||
- **Delete** — 永久删除定时任务
|
||||
|
||||
### Skills（技能）
|
||||
|
||||
浏览、搜索和切换技能与工具集。技能从 `~/.hermes/skills/` 加载，并按类别分组。
|
||||
|
||||
- **Search** — 按名称、描述或类别过滤技能和工具集
|
||||
- **Category filter** — 点击类别标签缩小列表范围（如 MLOps、MCP、Red Teaming、AI）
|
||||
- **Toggle** — 使用开关启用或禁用单个技能。更改在下一次会话时生效。
|
||||
- **Toolsets** — 单独的部分显示内置工具集（文件操作、Web 浏览等），包含其活跃/非活跃状态、设置要求和包含的工具列表
|
||||
|
||||
:::warning 安全提示
|
||||
Web Dashboard 会读写包含 API 密钥和机密的 `.env` 文件。它默认绑定到 `127.0.0.1`——只能从本机访问。如果绑定到 `0.0.0.0`，网络上的任何人都可以查看和修改你的凭据。Dashboard 本身没有任何认证机制。
|
||||
:::
|
||||
|
||||
## `/reload` 斜杠命令
|
||||
|
||||
Dashboard 还为交互式 CLI 添加了 `/reload` 斜杠命令。通过 Web Dashboard（或直接编辑 `.env`）更改 API 密钥后，在活跃的 CLI 会话中使用 `/reload` 即可获取更改，无需重启：
|
||||
|
||||
```
|
||||
You → /reload
|
||||
Reloaded .env (3 var(s) updated)
|
||||
```
|
||||
|
||||
这会将 `~/.hermes/.env` 重新读取到运行中进程的环境中。当你通过 Dashboard 添加了新的提供商密钥并希望立即使用时非常有用。
|
||||
|
||||
## REST API
|
||||
|
||||
Web Dashboard 暴露了一个供前端使用的 REST API。你也可以直接调用这些端点进行自动化操作：
|
||||
|
||||
### GET /api/status
|
||||
|
||||
返回 agent 版本、gateway 状态、平台状态和活跃会话数。
|
||||
|
||||
### GET /api/sessions
|
||||
|
||||
返回最近 20 个会话的元数据（模型、token 数、时间戳、预览）。
|
||||
|
||||
### GET /api/config
|
||||
|
||||
以 JSON 格式返回当前 `config.yaml` 内容。
|
||||
|
||||
### GET /api/config/defaults
|
||||
|
||||
返回默认配置值。
|
||||
|
||||
### GET /api/config/schema
|
||||
|
||||
返回描述每个配置字段的 schema——类型、描述、类别，以及适用时的选项。前端使用此 schema 为每个字段渲染正确的输入控件。
|
||||
|
||||
### PUT /api/config
|
||||
|
||||
保存新配置。请求体：`{"config": {...}}`。
|
||||
|
||||
### GET /api/env
|
||||
|
||||
返回所有已知环境变量，包含其设置/未设置状态、脱敏值、描述和类别。
|
||||
|
||||
### PUT /api/env
|
||||
|
||||
设置环境变量。请求体：`{"key": "VAR_NAME", "value": "secret"}`。
|
||||
|
||||
### DELETE /api/env
|
||||
|
||||
删除环境变量。请求体：`{"key": "VAR_NAME"}`。
|
||||
|
||||
### GET /api/sessions/\{session_id\}
|
||||
|
||||
返回单个会话的元数据。
|
||||
|
||||
### GET /api/sessions/\{session_id\}/messages
|
||||
|
||||
返回会话的完整消息历史，包含工具调用和时间戳。
|
||||
|
||||
### GET /api/sessions/search
|
||||
|
||||
对消息内容进行全文搜索。查询参数：`q`。返回匹配的会话 ID 和高亮片段。
|
||||
|
||||
### DELETE /api/sessions/\{session_id\}
|
||||
|
||||
删除会话及其消息历史。
|
||||
|
||||
### GET /api/logs
|
||||
|
||||
返回日志行。查询参数：`file`（agent/errors/gateway）、`lines`（数量）、`level`、`component`。
|
||||
|
||||
### GET /api/analytics/usage
|
||||
|
||||
返回 token 用量、成本和会话分析。查询参数：`days`（默认 30）。响应包含每日明细和按模型聚合数据。
|
||||
|
||||
### GET /api/cron/jobs
|
||||
|
||||
返回所有已配置的定时任务，包含其状态、计划和运行历史。
|
||||
|
||||
### POST /api/cron/jobs
|
||||
|
||||
创建新定时任务。请求体：`{"prompt": "...", "schedule": "0 9 * * *", "name": "...", "deliver": "local"}`。
|
||||
|
||||
### POST /api/cron/jobs/\{job_id\}/pause
|
||||
|
||||
暂停定时任务。
|
||||
|
||||
### POST /api/cron/jobs/\{job_id\}/resume
|
||||
|
||||
恢复已暂停的定时任务。
|
||||
|
||||
### POST /api/cron/jobs/\{job_id\}/trigger
|
||||
|
||||
在计划之外立即触发定时任务。
|
||||
|
||||
### DELETE /api/cron/jobs/\{job_id\}
|
||||
|
||||
删除定时任务。
|
||||
|
||||
### GET /api/skills
|
||||
|
||||
返回所有技能，包含其名称、描述、类别和启用状态。
|
||||
|
||||
### PUT /api/skills/toggle
|
||||
|
||||
启用或禁用技能。请求体：`{"name": "skill-name", "enabled": true}`。
|
||||
|
||||
### GET /api/tools/toolsets
|
||||
|
||||
返回所有工具集，包含其标签、描述、工具列表以及活跃/已配置状态。
|
||||
|
||||
## CORS
|
||||
|
||||
Web 服务器将 CORS 限制为仅 localhost 来源：
|
||||
|
||||
- `http://localhost:9119` / `http://127.0.0.1:9119`（生产环境）
|
||||
- `http://localhost:3000` / `http://127.0.0.1:3000`
|
||||
- `http://localhost:5173` / `http://127.0.0.1:5173`（Vite 开发服务器）
|
||||
|
||||
如果你在自定义端口上运行服务器，该来源会自动添加。
|
||||
|
||||
## 开发
|
||||
|
||||
如果你要为 Web Dashboard 前端做贡献：
|
||||
|
||||
```bash
|
||||
# 终端 1：启动后端 API
|
||||
hermes dashboard --no-open
|
||||
|
||||
# 终端 2：启动带 HMR 的 Vite 开发服务器
|
||||
cd web/
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
`http://localhost:5173` 上的 Vite 开发服务器会将 `/api` 请求代理到 `http://127.0.0.1:9119` 上的 FastAPI 后端。
|
||||
|
||||
前端使用 React 19、TypeScript、Tailwind CSS v4 和 shadcn/ui 风格组件构建。生产构建输出到 `hermes_cli/web_dist/`，由 FastAPI 服务器作为静态 SPA 提供服务。
|
||||
|
||||
## 更新时自动构建
|
||||
|
||||
运行 `hermes update` 时，如果 `npm` 可用，Web 前端会自动重新构建。这使 Dashboard 与代码更新保持同步。如果未安装 `npm`，更新会跳过前端构建，`hermes dashboard` 将在首次启动时构建。
|
||||
|
||||
## 主题与插件
|
||||
|
||||
Dashboard 内置六个主题，并可通过用户自定义主题、插件标签页和后端 API 路由进行扩展——全部即插即用，无需克隆仓库。
|
||||
|
||||
**实时切换主题**：点击顶部栏语言切换器旁的调色板图标。选择会持久化到 `config.yaml` 的 `dashboard.theme` 下，并在页面加载时恢复。
|
||||
|
||||
内置主题：
|
||||
|
||||
| 主题 | 特点 |
|
||||
|-------|-----------|
|
||||
| **Hermes Teal** (`default`) | 深青色 + 奶油色，系统字体，舒适间距 |
|
||||
| **Hermes Teal (Large)** (`default-large`) | 与 default 相同，但使用 18px 文字和更宽松的间距 |
|
||||
| **Midnight** (`midnight`) | 深蓝紫色，Inter + JetBrains Mono |
|
||||
| **Ember** (`ember`) | 暖深红 + 古铜色，Spectral 衬线体 + IBM Plex Mono |
|
||||
| **Mono** (`mono`) | 灰度，IBM Plex，紧凑 |
|
||||
| **Cyberpunk** (`cyberpunk`) | 黑底霓虹绿，Share Tech Mono |
|
||||
| **Rosé** (`rose`) | 粉色 + 象牙色，Fraunces 衬线体，宽松 |
|
||||
|
||||
如需构建自定义主题、添加插件标签页、注入 shell 插槽或暴露插件专属 REST 端点，请参阅 **[扩展 Dashboard](./extending-the-dashboard)**——完整指南涵盖：
|
||||
|
||||
- 主题 YAML schema——调色板、排版、布局、资源、componentStyles、colorOverrides、customCSS
|
||||
- 布局变体——`standard`、`cockpit`、`tiled`
|
||||
- 插件 manifest、SDK、shell 插槽、页面级插槽（在不覆盖内置页面的情况下注入控件）、后端 FastAPI 路由
|
||||
- 完整的主题加插件综合演示（Strike Freedom cockpit 示例）
|
||||
- 发现、重载和故障排查
|
||||
+446
@@ -0,0 +1,446 @@
|
||||
---
|
||||
title: 网页搜索与提取
|
||||
description: 通过多个后端提供商搜索网页并提取页面内容——包括免费的自托管 SearXNG。
|
||||
sidebar_label: Web Search
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
# 网页搜索与提取
|
||||
|
||||
Hermes Agent 内置两个可供模型调用的网页工具，由多个提供商支持：
|
||||
|
||||
- **`web_search`** — 搜索网页并返回排序结果
|
||||
- **`web_extract`** — 从一个或多个 URL 获取并提取可读内容
|
||||
|
||||
两者均通过单一后端选择进行配置。提供商可通过 `hermes tools` 选择，或直接在 `config.yaml` 中设置。
|
||||
|
||||
## 后端
|
||||
|
||||
| 提供商 | 环境变量 | 搜索 | 提取 | 免费层级 |
|
||||
|----------|---------|--------|---------|-----------|
|
||||
| **Firecrawl**（默认） | `FIRECRAWL_API_KEY` | ✔ | ✔ | 500 积分/月 |
|
||||
| **SearXNG** | `SEARXNG_URL` | ✔ | — | ✔ 免费（自托管） |
|
||||
| **Brave Search（免费层级）** | `BRAVE_SEARCH_API_KEY` | ✔ | — | 2 000 次查询/月 |
|
||||
| **DDGS (DuckDuckGo)** | —（无需密钥） | ✔ | — | ✔ 免费 |
|
||||
| **Tavily** | `TAVILY_API_KEY` | ✔ | ✔ | 1 000 次搜索/月 |
|
||||
| **Exa** | `EXA_API_KEY` | ✔ | ✔ | 1 000 次搜索/月 |
|
||||
| **Parallel** | `PARALLEL_API_KEY` | ✔ | ✔ | 付费 |
|
||||
| **xAI (Grok)** | `XAI_API_KEY` 或 `hermes auth login xai-oauth` | ✔ | — | 付费（SuperGrok 或按 token 计费） |
|
||||
|
||||
Brave Search、DDGS 和 xAI 均为**仅搜索**——如果同时需要 `web_extract`，可将其中任意一个与 Firecrawl/Tavily/Exa/Parallel 配合使用。DDGS 底层使用 [`ddgs` Python 包](https://pypi.org/project/ddgs/)；若尚未安装，请运行 `pip install ddgs`（或让 Hermes 在首次使用时懒加载安装）。xAI 通过 Responses API 运行 Grok 服务端的 `web_search` 工具——结果由 LLM 生成而非基于索引，因此标题、描述和 URL 选择均为模型输出（参见下方[信任模型说明](#xai-grok)）。
|
||||
|
||||
**按能力拆分：** 搜索和提取可分别使用不同的提供商——例如搜索使用 SearXNG（免费），提取使用 Firecrawl。详见下方[按能力配置](#per-capability-configuration)。
|
||||
|
||||
:::tip Nous 订阅用户
|
||||
如果您拥有付费 [Nous Portal](https://portal.nousresearch.com) 订阅，网页搜索和提取可通过 **[Tool Gateway](tool-gateway.md)** 使用托管的 Firecrawl——无需 API 密钥。新安装可运行 `hermes setup --portal` 登录并一次性开启所有 gateway 工具；现有安装可通过 `hermes tools` 单独开启网页功能。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## `web_extract` 如何处理长页面
|
||||
|
||||
后端返回的原始页面 markdown 可能非常庞大（论坛帖子、文档站点、带嵌入评论的新闻文章）。为保持上下文窗口可用并降低成本，`web_extract` 在将内容交给 agent 之前，会通过 **`web_extract` 辅助模型**对返回内容进行处理。行为完全由大小决定：
|
||||
|
||||
| 页面大小（字符数） | 处理方式 |
|
||||
|------------------------|--------------|
|
||||
| 5 000 以下 | 原样返回——不调用 LLM，完整 markdown 直达 agent |
|
||||
| 5 000 – 500 000 | 通过 `web_extract` 辅助模型单次摘要，输出上限约 5 000 字符 |
|
||||
| 500 000 – 2 000 000 | 分块处理：拆分为 10 万字符的块，并行摘要每块，再合成最终摘要（约 5 000 字符） |
|
||||
| 超过 2 000 000 | 拒绝处理，并提示使用更具体的来源 URL |
|
||||
|
||||
摘要保留引用、代码块和关键事实的原始格式——它是内容压缩器，而非改写器。如果摘要失败或超时，Hermes 会回退到原始内容的前约 5 000 字符，而非返回无用的错误信息。
|
||||
|
||||
### 哪个模型负责摘要？
|
||||
|
||||
`web_extract` 辅助任务。默认情况下（`auxiliary.web_extract.provider: "auto"`），使用您的**主聊天模型**——与 `hermes model` 相同的提供商和模型。对大多数配置而言这没问题，但在昂贵的推理模型（Opus、MiniMax M2.7 等）上，每次长页面提取都会产生可观的成本。
|
||||
|
||||
若要将提取摘要路由到廉价快速的模型，无论主模型是什么：
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
auxiliary:
|
||||
web_extract:
|
||||
provider: openrouter
|
||||
model: google/gemini-3-flash-preview
|
||||
timeout: 360 # 秒；如果遇到摘要超时，请调大此值
|
||||
```
|
||||
|
||||
或交互式选择：`hermes model` → **Configure auxiliary models** → `web_extract`。
|
||||
|
||||
完整参考和按任务覆盖模式，请参阅[辅助模型](/user-guide/configuration#auxiliary-models)。
|
||||
|
||||
### 摘要处理不适用的情况
|
||||
|
||||
如果您明确需要原始、未经摘要的页面内容——例如正在抓取结构化页面，LLM 摘要会丢失重要字段——请改用 `browser_navigate` + `browser_snapshot`。浏览器工具返回实时无障碍树，不经辅助模型改写（在超大页面上受其自身 8 000 字符快照上限约束）。
|
||||
|
||||
---
|
||||
|
||||
## 设置
|
||||
|
||||
### 通过 `hermes tools` 快速设置
|
||||
|
||||
运行 `hermes tools`，导航至 **Web Search & Extract**，选择一个提供商。向导会提示输入所需的 URL 或 API 密钥，并写入您的配置。
|
||||
|
||||
```bash
|
||||
hermes tools
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Firecrawl（默认）
|
||||
|
||||
功能完整的搜索和提取。推荐大多数用户使用。
|
||||
|
||||
```bash
|
||||
# ~/.hermes/.env
|
||||
FIRECRAWL_API_KEY=fc-your-key-here
|
||||
```
|
||||
|
||||
在 [firecrawl.dev](https://firecrawl.dev) 获取密钥。免费层级包含每月 500 积分。
|
||||
|
||||
**自托管 Firecrawl：** 指向您自己的实例而非云端 API：
|
||||
|
||||
```bash
|
||||
# ~/.hermes/.env
|
||||
FIRECRAWL_API_URL=http://localhost:3002
|
||||
```
|
||||
|
||||
设置 `FIRECRAWL_API_URL` 后，API 密钥为可选项（使用 `USE_DB_AUTHENTICATION=false` 禁用服务器认证）。
|
||||
|
||||
---
|
||||
|
||||
### SearXNG（免费，自托管）
|
||||
|
||||
SearXNG 是一个注重隐私的开源元搜索引擎，聚合来自 70 多个搜索引擎的结果。**无需 API 密钥**——只需将 Hermes 指向一个运行中的 SearXNG 实例。
|
||||
|
||||
SearXNG 为**仅搜索**——`web_extract` 需要单独的提取提供商。
|
||||
|
||||
#### 方案 A — 使用 Docker 自托管（推荐）
|
||||
|
||||
这为您提供无速率限制的私有实例。
|
||||
|
||||
**1. 创建工作目录：**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/searxng/searxng
|
||||
cd ~/searxng
|
||||
```
|
||||
|
||||
**2. 编写 `docker-compose.yml`：**
|
||||
|
||||
```yaml
|
||||
# ~/searxng/docker-compose.yml
|
||||
services:
|
||||
searxng:
|
||||
image: searxng/searxng:latest
|
||||
container_name: searxng
|
||||
ports:
|
||||
- "8888:8080"
|
||||
volumes:
|
||||
- ./searxng:/etc/searxng:rw
|
||||
environment:
|
||||
- SEARXNG_BASE_URL=http://localhost:8888/
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
**3. 启动容器：**
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
**4. 启用 JSON API 格式：**
|
||||
|
||||
SearXNG 默认禁用 JSON 输出。复制生成的配置并启用它：
|
||||
|
||||
```bash
|
||||
# 从容器中复制自动生成的配置
|
||||
docker cp searxng:/etc/searxng/settings.yml ~/searxng/searxng/settings.yml
|
||||
```
|
||||
|
||||
打开 `~/searxng/searxng/settings.yml`，找到 `formats` 块（约第 84 行）：
|
||||
|
||||
```yaml
|
||||
# 修改前（默认——JSON 已禁用）：
|
||||
formats:
|
||||
- html
|
||||
|
||||
# 修改后（为 Hermes 启用 JSON）：
|
||||
formats:
|
||||
- html
|
||||
- json
|
||||
```
|
||||
|
||||
**5. 重启以应用更改：**
|
||||
|
||||
```bash
|
||||
docker cp ~/searxng/searxng/settings.yml searxng:/etc/searxng/settings.yml
|
||||
docker restart searxng
|
||||
```
|
||||
|
||||
**6. 验证是否正常工作：**
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:8888/search?q=test&format=json" | python3 -c \
|
||||
"import sys,json; d=json.load(sys.stdin); print(f'{len(d[\"results\"])} results')"
|
||||
```
|
||||
|
||||
您应该看到类似 `10 results` 的输出。如果收到 `403 Forbidden`，说明 JSON 格式仍未启用——请重新检查第 4 步。
|
||||
|
||||
**7. 配置 Hermes：**
|
||||
|
||||
```bash
|
||||
# ~/.hermes/.env
|
||||
SEARXNG_URL=http://localhost:8888
|
||||
```
|
||||
|
||||
然后在 `~/.hermes/config.yaml` 中选择 SearXNG 作为搜索后端：
|
||||
|
||||
```yaml
|
||||
web:
|
||||
search_backend: "searxng"
|
||||
```
|
||||
|
||||
或通过 `hermes tools` → Web Search & Extract → SearXNG 设置。
|
||||
|
||||
---
|
||||
|
||||
#### 方案 B — 使用公共实例
|
||||
|
||||
公共 SearXNG 实例列表见 [searx.space](https://searx.space/)。筛选**已启用 JSON 格式**的实例（表格中有显示）。
|
||||
|
||||
```bash
|
||||
# ~/.hermes/.env
|
||||
SEARXNG_URL=https://searx.example.com
|
||||
```
|
||||
|
||||
:::caution 公共实例
|
||||
公共实例有速率限制、可用性不稳定，且可能随时禁用 JSON 格式。生产环境强烈建议自托管。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
#### 将 SearXNG 与提取提供商配合使用
|
||||
|
||||
SearXNG 负责搜索；`web_extract` 需要单独的提供商。使用按能力配置的键：
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
web:
|
||||
search_backend: "searxng"
|
||||
extract_backend: "firecrawl" # 或 tavily、exa、parallel
|
||||
```
|
||||
|
||||
使用此配置，Hermes 对所有搜索查询使用 SearXNG，对 URL 提取使用 Firecrawl——将免费搜索与高质量提取相结合。
|
||||
|
||||
---
|
||||
|
||||
### Tavily
|
||||
|
||||
针对 AI 优化的搜索和提取，免费层级慷慨。
|
||||
|
||||
```bash
|
||||
# ~/.hermes/.env
|
||||
TAVILY_API_KEY=tvly-your-key-here
|
||||
```
|
||||
|
||||
在 [app.tavily.com](https://app.tavily.com/home) 获取密钥。免费层级包含每月 1 000 次搜索。
|
||||
|
||||
---
|
||||
|
||||
### Exa
|
||||
|
||||
具有语义理解的神经搜索。适合研究和查找概念相关内容。
|
||||
|
||||
```bash
|
||||
# ~/.hermes/.env
|
||||
EXA_API_KEY=your-exa-key-here
|
||||
```
|
||||
|
||||
在 [exa.ai](https://exa.ai) 获取密钥。免费层级包含每月 1 000 次搜索。
|
||||
|
||||
---
|
||||
|
||||
### Parallel
|
||||
|
||||
具备深度研究能力的 AI 原生搜索和提取。
|
||||
|
||||
```bash
|
||||
# ~/.hermes/.env
|
||||
PARALLEL_API_KEY=your-parallel-key-here
|
||||
```
|
||||
|
||||
在 [parallel.ai](https://parallel.ai) 申请访问权限。
|
||||
|
||||
---
|
||||
|
||||
### xAI (Grok) {#xai-grok}
|
||||
|
||||
通过 Responses API 将 `web_search` 路由至 Grok 服务端的 [web_search 工具](https://docs.x.ai/developers/tools/web-search)。Grok 执行实际搜索并以结构化 JSON 返回最佳结果。
|
||||
|
||||
支持两种凭证路径——无需新的环境变量，无需新的设置向导：
|
||||
|
||||
```bash
|
||||
# ~/.hermes/.env（环境变量路径）
|
||||
XAI_API_KEY=sk-xai-your-key-here
|
||||
```
|
||||
|
||||
或对于 SuperGrok 订阅用户：
|
||||
|
||||
```bash
|
||||
hermes auth login xai-oauth
|
||||
```
|
||||
|
||||
然后选择 xAI 作为搜索后端：
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
web:
|
||||
backend: "xai"
|
||||
```
|
||||
|
||||
**可选配置项：**
|
||||
|
||||
```yaml
|
||||
web:
|
||||
backend: "xai"
|
||||
xai:
|
||||
model: grok-4.3 # web_search 所需的推理模型（默认）
|
||||
allowed_domains: # 可选，最多 5 个——与 excluded_domains 互斥
|
||||
- arxiv.org
|
||||
excluded_domains: # 可选，最多 5 个
|
||||
- example-spam.com
|
||||
timeout: 90 # 秒（默认）
|
||||
```
|
||||
|
||||
**仅搜索**——如果同时需要 `web_extract`，请与 Firecrawl / Tavily / Exa / Parallel 配合使用。遇到 401 时，提供商会执行一次强制 OAuth token 刷新并重试（覆盖窗口中途吊销和主动过期检查无法解码的不透明 token）；环境变量凭证跳过重试。
|
||||
|
||||
:::caution 信任模型
|
||||
与基于索引的提供商（Brave、Tavily、Exa）返回逐字搜索引擎结果不同，xAI 是由 LLM 选择要呈现的 URL 并自行撰写标题和描述。查询的*内容*会影响输出，因此恶意构造的查询（例如通过 agent 获取的不可信上游输入注入）原则上可以引导 Grok 输出攻击者指定的 URL。对返回的 URL 应与对待任何模型生成链接一样——在获取前进行验证，尤其是当查询来自不可信输入时。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
### 单一后端
|
||||
|
||||
为所有网页功能设置一个提供商：
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
web:
|
||||
backend: "searxng" # firecrawl | searxng | brave-free | ddgs | tavily | exa | parallel | xai
|
||||
```
|
||||
|
||||
### 按能力配置 {#per-capability-configuration}
|
||||
|
||||
搜索和提取使用不同的提供商。这允许您将免费搜索（SearXNG）与付费提取提供商组合使用，反之亦然：
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
web:
|
||||
search_backend: "searxng" # 由 web_search 使用
|
||||
extract_backend: "firecrawl" # 由 web_extract 使用
|
||||
```
|
||||
|
||||
当按能力键为空时，两者均回退到 `web.backend`。当 `web.backend` 也为空时，后端根据存在的 API 密钥/URL 自动检测。
|
||||
|
||||
**优先级顺序（按能力）：**
|
||||
1. `web.search_backend` / `web.extract_backend`（显式按能力配置）
|
||||
2. `web.backend`（共享回退）
|
||||
3. 从环境变量自动检测
|
||||
|
||||
### 自动检测
|
||||
|
||||
如果未显式配置后端，Hermes 根据已设置的凭证选择第一个可用的后端：
|
||||
|
||||
| 存在的凭证 | 自动选择的后端 |
|
||||
|--------------------|-----------------------|
|
||||
| `FIRECRAWL_API_KEY` 或 `FIRECRAWL_API_URL` | firecrawl |
|
||||
| `PARALLEL_API_KEY` | parallel |
|
||||
| `TAVILY_API_KEY` | tavily |
|
||||
| `EXA_API_KEY` | exa |
|
||||
| `SEARXNG_URL` | searxng |
|
||||
|
||||
xAI Web Search **不在**自动检测链中——设置了 `XAI_API_KEY`（或通过 xAI Grok OAuth 登录）不会自动将网页流量路由至 xAI，因为这些凭证同时用于推理/TTS/图像生成，用户可能希望为网页使用不同的后端。请通过 `web.backend: "xai"` 显式启用。
|
||||
|
||||
---
|
||||
|
||||
## 验证设置
|
||||
|
||||
运行 `hermes setup` 查看检测到的网页后端：
|
||||
|
||||
```
|
||||
✅ Web Search & Extract (searxng)
|
||||
```
|
||||
|
||||
或通过 CLI 检查：
|
||||
|
||||
```bash
|
||||
# 激活 venv 并直接运行网页工具模块
|
||||
source ~/.hermes/hermes-agent/.venv/bin/activate
|
||||
python -m tools.web_tools
|
||||
```
|
||||
|
||||
这将打印活动后端及其状态：
|
||||
|
||||
```
|
||||
✅ Web backend: searxng
|
||||
Using SearXNG (search only): http://localhost:8888
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排查
|
||||
|
||||
### `web_search` 返回 `{"success": false}`
|
||||
|
||||
- 检查 `SEARXNG_URL` 是否可达：`curl -s "http://localhost:8888/search?q=test&format=json"`
|
||||
- 如果收到 HTTP 403，说明 JSON 格式已禁用——在 `settings.yml` 的 `formats` 列表中添加 `json` 并重启
|
||||
- 如果收到连接错误，容器可能未运行：`docker ps | grep searxng`
|
||||
|
||||
### `web_extract` 提示"search-only backend"
|
||||
|
||||
SearXNG 无法提取 URL 内容。将 `web.extract_backend` 设置为支持提取的提供商：
|
||||
|
||||
```yaml
|
||||
web:
|
||||
search_backend: "searxng"
|
||||
extract_backend: "firecrawl" # 或 tavily / exa / parallel
|
||||
```
|
||||
|
||||
### SearXNG 返回 0 条结果
|
||||
|
||||
部分公共实例禁用了某些搜索引擎或分类。请尝试：
|
||||
- 换一个查询词
|
||||
- 从 [searx.space](https://searx.space/) 换一个公共实例
|
||||
- 自托管实例以获得稳定结果
|
||||
|
||||
### 公共实例遭遇速率限制
|
||||
|
||||
切换到自托管实例（参见上方[方案 A](#option-a--self-host-with-docker-recommended)）。使用 Docker，您自己的实例没有速率限制。
|
||||
|
||||
### `web_extract` 返回截断内容并附有"summarization timed out"提示
|
||||
|
||||
辅助模型未能在配置的超时时间内完成摘要。可以：
|
||||
|
||||
- 在 `config.yaml` 中调大 `auxiliary.web_extract.timeout`（新安装默认 360 秒，若键缺失则为 30 秒）
|
||||
- 将 `web_extract` 辅助任务切换到更快的模型（例如 `google/gemini-3-flash-preview`）——参见 [`web_extract` 如何处理长页面](#how-web_extract-handles-long-pages)
|
||||
- 对于摘要处理不适用的页面，改用 `browser_navigate`
|
||||
|
||||
---
|
||||
|
||||
## 可选技能：`searxng-search`
|
||||
|
||||
对于需要直接通过 `curl` 使用 SearXNG 的 agent（例如作为网页工具集不可用时的回退），请安装 `searxng-search` 可选技能：
|
||||
|
||||
```bash
|
||||
hermes skills install official/research/searxng-search
|
||||
```
|
||||
|
||||
这将添加一个技能，教 agent 如何：
|
||||
- 通过 `curl` 或 Python 调用 SearXNG JSON API
|
||||
- 按分类筛选（`general`、`news`、`science` 等）
|
||||
- 处理分页和错误情况
|
||||
- 在 SearXNG 不可达时优雅降级
|
||||
+140
@@ -0,0 +1,140 @@
|
||||
---
|
||||
title: X (Twitter) 搜索
|
||||
description: 使用 xAI 内置的 x_search Responses 工具在 agent 内搜索 X (Twitter) 帖子和话题串——支持 SuperGrok OAuth 登录或 XAI_API_KEY。
|
||||
sidebar_label: X (Twitter) 搜索
|
||||
sidebar_position: 7
|
||||
---
|
||||
|
||||
# X (Twitter) 搜索
|
||||
|
||||
`x_search` 工具让 agent 可以直接搜索 X (Twitter) 的帖子、账号和话题串。其底层依托 xAI 在 Responses API（`https://api.x.ai/v1/responses`）上内置的 `x_search` 工具——Grok 在服务端执行搜索，并返回带有原始帖子引用的综合结果。
|
||||
|
||||
**当你明确需要 X 上的当前讨论、反应或观点时，请使用此工具而非 `web_search`。** 对于一般网页内容，继续使用 `web_search` / `web_extract`。
|
||||
|
||||
## 认证
|
||||
|
||||
满足以下**任一** xAI 凭据路径时，`x_search` 即会注册：
|
||||
|
||||
| 凭据 | 来源 | 配置方式 |
|
||||
|------|------|---------|
|
||||
| **SuperGrok / X Premium+ OAuth**（推荐） | 在 `accounts.x.ai` 浏览器登录，自动刷新 | `hermes auth add xai-oauth` — 参见 [xAI Grok OAuth (SuperGrok / X Premium+)](../../guides/xai-grok-oauth.md) |
|
||||
| **`XAI_API_KEY`** | 付费 xAI API 密钥 | 在 `~/.hermes/.env` 中设置 |
|
||||
|
||||
两者使用相同的 endpoint 和相同的请求体，区别仅在于 bearer token。**当两者同时配置时，SuperGrok OAuth 优先**，x_search 将消耗你的订阅配额而非付费 API 用量。
|
||||
|
||||
工具的 `check_fn` 在每次重建模型工具列表时都会运行 xAI 凭据解析器。返回 `True` 表示 bearer token 可获取、非空，且（若已过期）已成功刷新。刷新失败的已撤销 token 会将该工具从 schema 中隐藏，模型将无法感知其存在。
|
||||
|
||||
## 启用工具
|
||||
|
||||
当 xAI 凭据（OAuth token 或 `XAI_API_KEY`）存在时自动启用。如不需要，可通过 `hermes tools` → Search → x_search 显式禁用。
|
||||
|
||||
```bash
|
||||
hermes tools
|
||||
# → 🐦 X (Twitter) Search (press space to toggle on)
|
||||
```
|
||||
|
||||
选择器提供两种凭据选项：
|
||||
|
||||
1. **xAI Grok OAuth (SuperGrok / Premium+)** — 若尚未登录，将打开浏览器跳转至 `accounts.x.ai`
|
||||
2. **xAI API key** — 提示输入 `XAI_API_KEY`
|
||||
|
||||
任一选项均可满足门控条件。你可以使用已有的任意凭据，工具行为完全相同。若两者均已配置，调用时 OAuth 优先。
|
||||
|
||||
## 配置
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
x_search:
|
||||
# 用于 Responses 调用的 xAI 模型。
|
||||
# grok-4.20-reasoning 是推荐的默认值；任何支持
|
||||
# x_search 工具访问权限的 Grok 模型均可使用。
|
||||
model: grok-4.20-reasoning
|
||||
|
||||
# 请求超时时间（秒）。复杂查询的 x_search 可能需要 60–120 秒，
|
||||
# 默认值较为宽松。最小值：30。
|
||||
timeout_seconds: 180
|
||||
|
||||
# 遇到 5xx / ReadTimeout / ConnectionError 时的自动重试次数。
|
||||
# 每次重试按指数退避（1.5 倍尝试秒数，上限 5 秒）。
|
||||
retries: 2
|
||||
```
|
||||
|
||||
## 工具参数
|
||||
|
||||
agent 调用 `x_search` 时使用以下参数：
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `query` | string（必填） | 在 X 上要查找的内容。 |
|
||||
| `allowed_x_handles` | string 数组 | 可选，**仅**包含指定账号的列表（最多 10 个）。前缀 `@` 会被自动去除。 |
|
||||
| `excluded_x_handles` | string 数组 | 可选，要排除的账号列表（最多 10 个）。与 `allowed_x_handles` 互斥。 |
|
||||
| `from_date` | string | 可选，`YYYY-MM-DD` 格式的起始日期。 |
|
||||
| `to_date` | string | 可选，`YYYY-MM-DD` 格式的结束日期。 |
|
||||
| `enable_image_understanding` | boolean | 让 xAI 分析匹配帖子中附带的图片。 |
|
||||
| `enable_video_understanding` | boolean | 让 xAI 分析匹配帖子中附带的视频。 |
|
||||
|
||||
工具返回的 JSON 包含：
|
||||
|
||||
- `answer` — Grok 生成的综合文本回答
|
||||
- `citations` — Responses API 顶层字段返回的引用
|
||||
- `inline_citations` — 从消息正文中提取的 `url_citation` 注释（每条包含 `url`、`title`、`start_index`、`end_index`）
|
||||
- `degraded` — 当设置了任意缩小范围的过滤器（`allowed_x_handles`、`excluded_x_handles`、`from_date`、`to_date`）且两个引用渠道均返回空时为 `true`。此时 `answer` 是基于模型自身知识合成的，而非来自 X 索引，应视为无来源内容。否则为 `false`（包括"未设置过滤器"的情况——宽泛的无来源回答只是一个回答，而非过滤器未命中）
|
||||
- `degraded_reason` — 列出哪些过滤器处于激活状态的简短字符串，当 `degraded` 为 `false` 时为 `null`
|
||||
- `credential_source` — OAuth 解析成功时为 `"xai-oauth"`，API 密钥解析成功时为 `"xai"`
|
||||
- `model`、`query`、`provider`、`tool`、`success`
|
||||
|
||||
### 日期验证
|
||||
|
||||
`from_date` / `to_date` 在发起 HTTP 调用前会在客户端进行验证：
|
||||
|
||||
- 若提供，两者均须能解析为 `YYYY-MM-DD` 格式。
|
||||
- 当两者同时设置时，`from_date` 必须不晚于 `to_date`。
|
||||
- `from_date` 不得晚于今天（UTC）——尚未开始的时间窗口内不可能存在帖子，调用必然返回零引用。
|
||||
- `to_date` 允许为未来日期（调用方可能合理地请求"从昨天到明天"以捕获即将发布的帖子）。
|
||||
|
||||
验证失败会以结构化的 `{"error": "..."}` 工具结果返回，不会向 xAI 发起 HTTP 调用。
|
||||
|
||||
## 示例
|
||||
|
||||
与 agent 对话：
|
||||
|
||||
> X 上的人们对新的 Grok 图像功能有什么看法？重点关注 @xai 的回应。
|
||||
|
||||
agent 将：
|
||||
|
||||
1. 以 `query="reactions to new Grok image features"`、`allowed_x_handles=["xai"]` 调用 `x_search`
|
||||
2. 获取综合回答及指向具体帖子的引用列表
|
||||
3. 回复包含答案和参考来源
|
||||
|
||||
## 故障排查
|
||||
|
||||
### "No xAI credentials available"
|
||||
|
||||
当两种认证路径均失败时，工具会显示此错误。请在 `~/.hermes/.env` 中设置 `XAI_API_KEY`，或运行 `hermes auth add xai-oauth` 并完成浏览器登录。然后重启会话，让 agent 重新加载工具注册表。
|
||||
|
||||
### "`x_search` is not enabled for this model"
|
||||
|
||||
配置的 `x_search.model` 没有访问服务端 `x_search` 工具的权限。请切换至 `grok-4.20-reasoning`（默认值）或其他支持该工具的 Grok 模型。当前支持列表请查阅 [xAI 文档](https://docs.x.ai/)。
|
||||
|
||||
### 工具未出现在 schema 中
|
||||
|
||||
可能有两个原因：
|
||||
|
||||
1. **工具集未启用。** 运行 `hermes tools`，确认 `🐦 X (Twitter) Search` 已勾选。
|
||||
2. **无 xAI 凭据。** `check_fn` 返回 False，schema 保持隐藏。运行 `hermes auth status` 确认 xai-oauth 登录状态，并检查 `XAI_API_KEY` 是否已设置（如使用 API 密钥路径）。
|
||||
|
||||
### `degraded: true` — 回答无引用来源
|
||||
|
||||
当你使用了 `allowed_x_handles`、`excluded_x_handles` 或日期范围，且响应返回 `degraded: true` 时，说明 xAI 的 X 索引未找到匹配帖子，但 Grok 仍基于自身训练数据生成了综合回答。该回答无来源支撑——请勿将其视为真实的 X 内容。
|
||||
|
||||
值得排查的原因：
|
||||
|
||||
- **账号名拼写错误。** 去掉 `@`，仔细核对拼写，并确认该账号存在。
|
||||
- **日期范围过窄**，或滑过了今日帖子；请扩大范围后重试。
|
||||
- **xAI 索引缺口。** 部分活跃账号即使定期发帖，也会间歇性地无法在 `x_search` 中出现。请等待几分钟后重试，或在需要精确获取某账号时间线时使用 `xurl` 技能直接调用 X API。
|
||||
|
||||
## 另请参阅
|
||||
|
||||
- [xAI Grok OAuth (SuperGrok / Premium+)](../../guides/xai-grok-oauth.md) — OAuth 配置指南
|
||||
- [Web 搜索与提取](web-search.md) — 用于一般（非 X）网页搜索
|
||||
- [工具参考](../../reference/tools-reference.md) — 完整工具目录
|
||||
Reference in New Issue
Block a user