Walvez's Log

版本说明
基准版本：Hermes Agent v0.21.0（Release tag: v2026.8.31）
更新日期：2026-09-01
Hermes Agent 迭代演进较快，CLI 选项与配置参数请以 [Hermes 官方文档](https://hermes-agent.nousresearch.com/docs/) 与 [GitHub 官方仓库](https://github.com/NousResearch/hermes-agent) 的最新更新为准。

Hermes Agent 是由开源 AI 研究机构 Nous Research 主导开发的开源 AI Agent 运行时底盘（Harness）。

要理解 Hermes Agent 的定位，需要先区分模型推理层与 Agent 宿主层：

• 模型推理层（Base Model）：如 Claude、GPT、Gemini、DeepSeek、GLM 等模型家族。底层模型推理请求本身并不负责长期状态管理；跨轮次上下文的拼接、记忆提取与持久化，通常由上层承载软件完成。
• Agent 宿主底盘（Agent Harness）：是运行在本地或服务器上的执行框架。它负责对接模型 Provider、管理跨会话上下文生命周期、提供记忆与技能机制、调度系统终端与外部工具（如 MCP），并驱动后台定时任务。

Hermes Agent 正是一个聚焦于本地与服务端运行的 Agent Harness，其机制围绕模型路由、持久记忆、可复用技能、工具系统与后台自动化展开：

                               ┌─────────────────────────┐
                               │       用户交互端        │
                               │ (Desktop / CLI / 网关)  │
                               └────────────┬────────────┘
                                            │
                               ┌────────────▼────────────┐
                               │   Hermes Agent 核心底盘  │
                               └────────────┬────────────┘
                                            │
         ┌──────────────────┬───────────────┼───────────────┬──────────────────┐
         │                  │               │               │                  │
┌────────┴─────────┐ ┌──────┴───────┐ ┌─────┴─────┐ ┌───────┴────────┐ ┌───────┴────────┐
│  模型与路由编排   │ │  记忆与规则   │ │ 技能系统  │ │  工具与外部生态  │ │  自动化与协作  │
├──────────────────┤ ├──────────────┤ ├───────────┤ ├────────────────┤ ├────────────────┤
│ • 主推理模型     │ │ • USER.md    │ │ • SKILL.md│ │ • 原生 Terminal │ │ • Cron 调度器  │
│ • Credential Pool│ │ • MEMORY.md  │ │ • 项目技能│ │ • Web 搜索与抓取 │ │ • Continuity   │
│ • Fallback 容灾  │ │ • 外部 Memory│ │ • 外部挂载│ │ • 浏览器自动化   │ │ • Subagent 隔离│
│ • Auxiliary 辅助 │ │ • SOUL/规则  │ │ • 蓝图转换│ │ • MCP Server 集成│ │ • Bot/Peer 协同│
└──────────────────┘ └──────────────┘ └───────────┘ └────────────────┘ └────────────────┘

从功能划分上看，Hermes 负责以下五项核心工作：

1. 模型路由与凭证管理：支持多 Provider 接入，内置 Credential Pool（凭证池）轮换、错误自动熔断与跨 Provider Fallback 降级。
2. 记忆系统：通过结构化的 Markdown 文件（USER.md 与 MEMORY.md）维护持久记忆，支持外部 Memory Provider 扩展。
3. 技能扩展（Skills）：采用声明式的 SKILL.md 规范，实现工作流的按需加载。
4. 工具与环境交互：提供终端执行、Web 检索、浏览器自动化等内置工具，并支持 Model Context Protocol（MCP）。
5. 后台自动化：内置 Cron 调度系统，配合跨轮次上下文继承机制（Continuity）与无代理脚本模式（no-agent），支持定时无人值守任务。

选择工具的前提是明确其设计边界。Hermes Agent 针对特定工作流设计，了解其侧重点有助于建立合理的技术选型。

• 长周期个人助理与研究协作：希望 Agent 在日常使用中持续记录用户习惯、技术偏好、业务约定与关键事实，并在后续会话中保持一致性。
• 多交互端统一状态：希望同一套 Agent 环境能够在桌面 GUI、终端 CLI 以及即时通讯端（飞书/Lark、Telegram、Discord、Slack、钉钉等）之间共享配置、记忆与技能（各聊天窗口的会话上下文仍按各自 session 独立维护）。
• 后台定时任务与增量分析：需要 Agent 周期性执行信息追踪、指标监控或自动化巡检，并能够自动结合上一轮的运行输出去重或增量分析（Continuity）。
• 多模型混合调度与凭证容灾：需要将主推理任务与各类辅助任务（如视觉分析、上下文压缩、标题生成、命令安全审查等）分发给不同模型，并对主力 API 配置多 Key 轮换与故障降级。

• 仅需单次即时问答：如果仅需偶尔查询通用知识或临时润色文本，直接使用主流 Web 对话界面更加轻便。
• 排斥本地服务与权限管理：尽管 Hermes 安装程序会自动配置主要运行时依赖，但在本地长期运行 Agent 仍需要用户理解系统权限、本地凭据安全、MCP 服务配置与版本维护成本。

Hermes Agent 支持 macOS、Linux 以及 Windows 原生环境。针对不同使用偏好，官方提供了图形界面安装包与终端安装脚本。

在阅读配置与日志前，需先明确 Hermes 的数据目录：

• macOS / Linux / WSL2：默认目录为 ~/.hermes。
• Windows（原生）：默认目录为 %LOCALAPPDATA%\hermes（通常位于 C:\Users\<用户名>\AppData\Local\hermes）。

在下文中，统一将该基准目录称为 $HERMES_HOME。其核心文件分布如下：

• $HERMES_HOME/config.yaml：非敏感的全局运行配置；
• $HERMES_HOME/.env：存储 API Key、Token、密码等敏感 Secret；
• $HERMES_HOME/auth.json 等文件：由 Hermes 认证模块管理，用于保存 OAuth 凭据（无需手动编辑）；
• $HERMES_HOME/memories/：长期记忆文件存放目录；
• $HERMES_HOME/skills/：用户级技能存放目录。

桌面图形客户端：Hermes Desktop（macOS / Windows 优先推荐）

对于希望开箱即用、拥有可视化对话与多 Bot 界面管理的用户，推荐直接使用桌面版：

• 访问 [Hermes Desktop 官方下载页](https://hermes-agent.nousresearch.com/desktop) 获取对应操作系统的安装程序（macOS .dmg、Windows .exe）。
• 亦可通过 [Hermes GitHub Releases](https://github.com/NousResearch/hermes-agent/releases) 获取版本资产。
• 桌面版内置核心服务，并与终端 CLI 共享 $HERMES_HOME 目录状态。

macOS / Linux 终端安装（CLI 路线，Linux 推荐）

在终端中执行官方安装脚本：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

依赖说明：安装程序会自动检测并配置运行所需的依赖组件（包括 uv、Python 3.11+、Node.js、ripgrep 与 ffmpeg）。安装完成后，按终端提示执行 source ~/.zshrc（或 source ~/.bashrc）刷新环境变量。Linux 下安装完成后亦可直接执行 hermes desktop 调出桌面界面。

Windows 原生终端安装（CLI 路线）

Hermes v0.21.0 支持在 Windows 下原生运行，不需要强制安装 WSL2。打开 PowerShell 执行：

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

该脚本会自动完成依赖配置并把 hermes 加入用户 PATH。若更习惯在 Linux 环境中工作，可在 WSL2 Ubuntu 中运行上述 Linux 安装命令。

Hermes 提供了不同的命令以满足针对性配置或全量初始化需求：

仅配置模型与凭据：`hermes model`

如果只需要添加、切换模型 Provider，或者更新 API Key 与端点，推荐使用：

hermes model

该命令将列出当前支持的主流 Provider，并引导完成对应凭据的输入与模型选择。

全量配置向导：`hermes setup`

如果是初次使用且需要完整设定默认行为、工具权限与主模型，可运行完整向导：

hermes setup

若使用 Nous Portal 账号体系，可使用快捷路径完成快速配置：

hermes setup --portal

启动交互

完成配置后，在终端输入以下命令启动前台交互：

hermes

在日常使用、更换网络环境或升级 Hermes 后，若遇到 Provider 连通性异常或配置文件格式错误，可运行内置的诊断命令：

hermes doctor

hermes doctor 用于检查当前安装环境与配置中的常见问题，并给出诊断与修复建议。部分问题可由系统自动处理，只需追加 --fix 参数：

hermes doctor --fix

实际检查项随版本更新变化，以当前 CLI 输出为准。

Hermes Agent 作为宿主框架，本身不捆绑特定的大语言模型。要让 Agent 具备推理与工具调用能力，需要为其配置模型 Provider。

在 Hermes 中，模型接入主要按认证与交付方式划分为四种类型：

1. API Key 直连
2. OAuth / 订阅认证
3. 聚合类平台（Aggregator）
4. 本地与自定义 Endpoint（Local / Custom）

在配置模型前，需要理解 Hermes 的凭据与配置文件边界：

• `$HERMES_HOME/config.yaml`：保存所有非敏感的运行配置。包括当前激活的主模型 Provider、默认模型名称（model.default）、凭证池轮换策略等。
• `$HERMES_HOME/.env`：保存传统的 API Key、Token、密码等敏感 Secret。
• Hermes Auth Store（如 `$HERMES_HOME/auth.json` 或 provider-specific 凭据文件）：由 Hermes 内部的认证模块管理，专门存储通过 OAuth 流程换取的 Token、刷新令牌（Refresh Token）及凭证池元数据。某些 Provider 还可读取外部客户端已有凭据（例如 Anthropic 支持直接复用 Claude Code 凭据）。用户不应手动编辑这些内部 OAuth Token。

方式一：API Key 直连

通过服务商控制台获取标准 API Key，并在 Hermes 中完成认证。

• 适用服务商：Anthropic、DeepSeek、Google Gemini、MiniMax、Kimi/Moonshot、GLM/Z.AI、OpenCode Go 等。
• 配置方式：

在终端中运行 hermes model，选择对应 Provider，根据交互提示输入 API Key。
Hermes 会将 API Key 写入 $HERMES_HOME/.env，并将主模型选择写入 config.yaml。

示例（$HERMES_HOME/.env 中的对应环境变量，由系统自动管理写入）：

ANTHROPIC_API_KEY=sk-ant-...
DEEPSEEK_API_KEY=sk-...
GEMINI_API_KEY=AIzaSy...
MINIMAX_API_KEY=...
KIMI_API_KEY=...
# 如使用中国区端点，可配合配置:
# KIMI_CN_API_KEY=...
OPENCODE_GO_API_KEY=...

对应 $HERMES_HOME/config.yaml 基础模型字段（以具体所选 Provider 为准）：

model:
  provider: <PROVIDER>
  default: <MODEL_ID>

说明：<PROVIDER> 与 <MODEL_ID> 均为结构占位符，不可直接复制。实际模型标识请通过 hermes model 交互式命令从当前 Provider catalog 中选择。

方式二：OAuth / 订阅认证

适用于支持浏览器授权、设备码流程（Device Code Flow）或复用客户端凭据的平台。

• 常见支持场景：Nous Portal、OpenAI Codex / ChatGPT OAuth、GitHub Copilot、Anthropic Claude Max、xAI OAuth、Qwen OAuth、MiniMax OAuth 等平台。
• 配置方式：

运行 hermes model 或 hermes auth add <provider> --type oauth。Hermes 认证模块会启动对应认证流程，引导完成浏览器或终端授权，并负责本地凭据的存储与自动刷新。

方式三：聚合类平台（Aggregator）

通过单一服务商聚合调用多家模型，适合希望统一账单与模型调度的场景。

• 典型代表：OpenRouter。
• 配置方式：

在 hermes model 中选择 openrouter 并提供 API Key。在指定模型时，使用带有服务商前缀的标准命名格式（如 provider/model-name）。

对应 $HERMES_HOME/config.yaml 结构：

model:
  provider: openrouter
  default: <PROVIDER>/<MODEL_ID>

方式四：本地部署与自定义 Endpoint（Local / Custom）

接入本地运行的开源模型服务或局域网内的 OpenAI 兼容网关。

• 典型方案：Ollama、vLLM、LocalAI、自建 LiteLLM 网关。
• 配置方式：

在 config.yaml 中配置 base_url 与模型标识符即可：

model:
  provider: custom
  default: <MODEL_ID>
  base_url: http://127.0.0.1:11434/v1

在长期运行和自动化场景中，单一 API Key 可能遭遇速率限制（429）、账户余额不足（402）或网络波动；单一 Provider 也可能发生整体服务故障。

Hermes Agent 内置了两层高可用容灾体系：

1. 同 Provider 内部：凭证池（Credential Pools）
2. 跨 Provider 之间：备用降级链（Fallback Providers）

               发起推理请求
                    │
                    ▼
       ┌────────────────────────┐
       │ Credential Pool (主)   │
       │ 策略: fill_first / ... │
       └────────────┬───────────┘
                    │
        ┌───────────┴───────────┐
        │ 成功                  │ 失败 (429/402/超时等)
        ▼                       ▼
    正常响应             轮换池内下一 Key
                                │
                        ┌───────┴───────┐
                        │ 池内全部耗尽   │
                        ▼               ▼
                   触发跨 Provider 降级 (Fallback)
                        │
                        ▼
       ┌────────────────────────┐
       │ Fallback Provider (备) │
       └────────────────────────┘

凭证池允许为同一个 Provider 注册多个 API Key 或 OAuth Token。当某个 Key 异常时，Hermes 会在底层自动切换到下一个健康 Key，保持当前会话不中断。

四种轮换策略（Rotation Strategies）

在 $HERMES_HOME/config.yaml 的 credential_pool_strategies 中按 Provider 配置：

错误熔断与状态处理

• 429 速率限制（Rate Limit）：

- 若为临时高频限流，Hermes 重试一次；
- 若为套餐配额用尽（Plan Quota Reached），立即将该 Key 标记为不可用并切换到池内下一个 Key。

• 402 计费异常（Billing / Out of Credit）：

- 立即轮换下一个 Key，并将该 Key 置于冷却状态（默认 1 小时；若服务商返回了明确的 reset_at，则以该重置时间覆盖默认冷却）。

• 401 认证失效：

- 若为 OAuth 凭据，自动尝试刷新 Token；刷新失败则切换到下一个 Key。

凭证管理与策略配置

通过交互式菜单管理凭据：

hermes auth

或直接通过命令行添加对应类型的凭证（provider 为必填参数）：

# 添加 API Key 类型凭据
hermes auth add openrouter --api-key sk-or-v1-...
hermes auth add anthropic --type api-key --api-key sk-ant-...

# 添加 OAuth 类型凭据
hermes auth add anthropic --type oauth

在 $HERMES_HOME/config.yaml 中指定各 Provider 的轮换策略：

credential_pool_strategies:
  openrouter: round_robin
  anthropic: fill_first

Prompt Cache 成本提示：在同一个 Provider 下切换不同的 API Key，或跨 Provider Fallback，通常会导致服务商原有的 Prompt Cache 命中失效。长会话切换后的首轮请求可能需要重新全量计费解析输入 Token。因此在没有明确负载均衡需求时，长会话推荐优先采用 fill_first 策略。

当主 Provider 的所有凭证均不可用，或该服务商发生故障时，Hermes 会激活 fallback_providers 链路。

触发条件与运行机制

• 触发条件：429（重试与池内密钥均耗尽）、5xx 服务端错误、401/403 鉴权失败、404、网络连接超时或连续返回空响应/异常格式。
• 恢复策略：Fallback 通常是逐轮（Per-turn）生效的，新轮次默认优先尝试恢复主 Provider。但若系统已知主凭据的 reset_at 尚未到期，则会保持使用 Fallback，直到恢复窗口到达。
• 配置键规范：当前版本使用顶层的 `fallback_providers` 列表格式（旧版本的单数字段 fallback_model 仅作为兼容读取存在，写入时会被自动迁移）。

命令行管理

# 交互式添加备用 Provider 与模型
hermes fallback add

# 查看当前已配置的降级链路
hermes fallback list

# 移除指定降级项
hermes fallback remove

模块化 YAML 结构示例

# 1. 主模型配置
model:
  provider: <MAIN_PROVIDER>
  default: <MAIN_MODEL_ID>

# 2. 凭证池策略
credential_pool_strategies:
  <MAIN_PROVIDER>: fill_first

# 3. 跨 Provider 备用降级链 (按列表顺序依次尝试)
fallback_providers:
  - provider: <FALLBACK_PROVIDER_1>
    model: <FALLBACK_MODEL_ID_1>
  - provider: <FALLBACK_PROVIDER_2>
    model: <FALLBACK_MODEL_ID_2>

Hermes Agent 的运行行为由系统级配置、环境凭证、全局身份与项目级上下文规则共同决定。

在 $HERMES_HOME 目录下，主要包含两类配置文件：

$HERMES_HOME/
├── config.yaml          # 非敏感运行配置（模型选择、工具参数、策略开关）
├── .env                 # 敏感环境变量与 API Key / Token 凭据
├── SOUL.md              # 全局 Agent 身份与沟通风格
├── memories/            # 持久记忆存储目录
│   ├── USER.md          # 用户画像与交互偏好
│   └── MEMORY.md        # 核心事实与环境长期记忆
└── skills/              # 用户级技能目录

• `$HERMES_HOME/config.yaml`：保存模型路由、凭证池策略、降级链、辅助任务、MCP 服务器定义与安全策略等非敏感配置。
• `$HERMES_HOME/.env`：保存传统的 API Key、Token、密码等敏感 Secret。

参数生效优先级（Precedence）：

CLI 显式参数 > $HERMES_HOME/config.yaml > $HERMES_HOME/.env > 内置默认值

注意：.env 不只是兼容层，它依然是各类 API keys、tokens 与 passwords 等 Secret 的标准存储位置。不要在多个层级重复声明相同的非敏感配置。

SOUL.md 位于 $HERMES_HOME/SOUL.md，用于定义 Agent 的全局身份、基准语气与交互风格。

• 注入机制：在每个新会话启动时，Hermes 会首先读取 SOUL.md 并将其置于 System Prompt 的第 1 槽位（Agent Identity），替代默认的通用助手身份。
• 编写原则：SOUL.md 应当仅包含全局通用的风格与交互规范，独立于具体的项目上下文规则。

示例（$HERMES_HOME/SOUL.md）：

# 核心身份与交互原则
- 保持专业、客观的技术沟通风格，避免使用过度热情的客套话与模板化结语。
- 当指令存在歧义时，指出关键技术权衡，不单方面猜测执行不可逆操作。
- 解释底层技术概念时，第一次出现时附带一句话的通俗说明。
- 给出代码示例时，保持完整性并附带必要的边界条件注释。

当 Agent 进入特定项目目录工作时，需要遵循该项目的代码规范与工程约束。Hermes 具备一套基于优先级的项目规则探测体系。

规则文件优先级（First-match Priority）

在当前工作区中，Hermes 先按项目 Context 类型优先级寻找匹配：

1. `.hermes.md` / `HERMES.md`：Hermes 原生最高优先级项目上下文文件；
2. `AGENTS.override.md`：用于个人或目录级的本地规则覆盖（适合加入 .gitignore，避免修改团队共享配置）；
3. `AGENTS.md`：跨 Agent 通用项目协作规范；
4. `CLAUDE.md`：兼容 Claude Code 生态的项目指令文件；
5. `.cursorrules` 与 `.cursor/rules/*.mdc`：兼容 Cursor 规则体系。

动态渐进发现（Progressive Discovery）

• 会话启动时，Hermes 确定生效的规则类型。如果最终采用 AGENTS.md，在 Git 仓库中系统会加载从 Git Root 到当前工作目录沿途的 AGENTS.md 链；
• 系统不会在启动时递归扫描整个代码仓库并把所有深层子目录规则一次性塞入 Prompt；
• 更深的子目录规则在后续工具导航与目录访问时按需渐进式加载（Progressive Discovery）。

为了兼顾模型服务商的 Prompt Caching 机制与上下文管理，Hermes 的 System Prompt 严格按照三层生命周期结构自顶向下拼接：

1. Stable 阶段 (高度静态，最大化缓存命中)
   ├── Agent Identity (slot #1: SOUL.md 或默认身份)
   ├── Tool & Model Guidance (工具调用规范与行为约束)
   ├── Skills Index (已加载技能的元数据与触发词)
   └── Environment / Platform Hints (操作系统、时区、终端特征)
       │
2. Context 阶段 (项目与会话级上下文)
   ├── Optional System Message
   └── Project Context Files (匹配到的 .hermes.md / AGENTS.md 链等)
       │
3. Volatile 阶段 (动态可变数据)
   ├── MEMORY.md Snapshot (环境事实与长期记忆快照)
   ├── USER.md Snapshot (用户画像与偏好快照)
   ├── External Memory Context (若激活了外部记忆提供商)
   └── Timestamp / Session Metadata / Model Info

Hermes 提供了两套互补的记忆机制：基于 Markdown 的受限精选持久记忆（Persistent Memory），以及针对全量历史轨迹的检索工具（session_search）。

                       会话启动 (Session Start)
                                 │
                 ┌───────────────┴───────────────┐
                 ▼                               ▼
       读取 USER.md 快照               读取 MEMORY.md 快照
      (用户画像 / 交互风格)           (项目事实 / 环境约定)
                 │                               │
                 └───────────────┬───────────────┘
                                 ▼
                     注入 System Prompt 记忆槽位
                                 │
                             会话交互中
                                 │
                                 ▼
                  Agent 调用内置 memory 工具
               (动态 add / replace / remove 条目)
                                 │
                      ┌──────────┴──────────┐
                      ▼                     ▼
                写入字符数未超限       写入超出容量阈值
                      │                     │
                    更新落盘           返回容量溢出错误
                                            │
                                            ▼
                                  Agent 主动审视并精简
                                  (合并/删除过时条目后重试)

Hermes 默认采用基于 Markdown 的双文件记忆体系，均存放在 $HERMES_HOME/memories/ 目录下：

机制细节说明

• 受限精选存储（Bounded Curated Memory）：

内置记忆不会自动执行模糊压缩。Agent 通过内置的 memory 工具主动进行操作（add、replace、remove）。当内容超出字符上限时，工具会返回容量溢出错误，由 Agent 主动合并或删除冗余条目后重新写入。

• 快照生命周期：

记忆写入后立即落盘，但不会中途修改当前会话已经生成的 System Prompt 缓存前缀。新记忆通常在下一个会话启动时生效；如果在当前会话内触发了系统提示词重建（例如长对话触发了上下文重构），新快照会被重新载入。

• 写入审批安全门（`memory.write_approval`）：

在 $HERMES_HOME/config.yaml 中设置 memory.write_approval: true，开启后 Agent 每次写入记忆前必须经过人工审批。在接受写入前，内容还会经过安全扫描以防注入。

对于需要海量上下文存储或外部知识库接入的场景，Hermes 提供了插件化的 MemoryProvider 抽象接口：

• 叠加生效（Additive）：激活外部记忆提供商时，内置的 USER.md 与 MEMORY.md 仍然保持运行，外部提供商作为补充记忆源叠加生效，而非替代内置记忆。
• 单实例约束：当前系统同时仅允许激活一个外部 Memory Provider（如接入外部向量/图记忆插件）。

session_search 与上述持久记忆有本质区别：

• `MEMORY.md` / `USER.md`：提炼后的少量高密度事实，每轮会话开始时固定载入 Prompt。
• `session_search`：基于 SQLite FTS5 的本地历史全文检索工具。

- 技术特性：纯本地字符串/关键词索引，不使用 Embedding 向量模型，不发起额外的辅助 LLM 调用，直接检索并返回本地数据库中的真实历史消息。
- 交互模式：支持按关键词、短语（Phrase）、布尔逻辑或前缀检索历史，包含 Discovery（发现匹配）、Scroll（翻看轮次）、Read（读取详情）与 Browse（按时间浏览）四种查看方式。仅在 Agent 需要调查历史讨论细节时按需调用，不长期占用 System Prompt 的固定空间。

高频、复杂的垂直工作流（如特定环境的代码重构规范、接口自动化测试用例生成等）如果每次都依赖临时输入提示词，不仅耗时而且容易占用上下文。

Hermes Agent 采用了标准的 Skills（技能）体系，通过文件结构封装提示词指南、执行脚本与静态模板，并在推理过程中按需加载。

一个标准的 Hermes Skill 存放在以技能名命名的独立文件夹中：

my-skill/
├── SKILL.md              # 核心定义文件（包含元数据与主体指南）
├── scripts/              # 可选：供调用的执行脚本
├── references/           # 可选：静态参考文档、API 规范
└── templates/            # 可选：代码模板或输出格式蓝图

`SKILL.md` 的规范结构

SKILL.md 采用 YAML Frontmatter 声明元数据，正文部分书写具体的执行指南：

---
name: api-tester
description: "自动化探测与验证 RESTful 接口的健康状态与 JSON Schema 规范。"
version: 1.0.0
metadata:
  hermes:
    tags: [testing, backend, api]
    requires_toolsets: [terminal]      # 声明依赖的能力集合 (与 requires_tools 具体工具声明区分)
    config:
      - key: testing.default_timeout
        description: "接口请求超时时间（秒）"
        default: 30
---

# API 测试与验证指南

## 执行步骤
1. 解析用户提供的 API 端点与鉴权方式。
2. 优先调用 scripts/test_runner.py 执行基础连通性检查。
3. 验证返回的 HTTP 状态码与响应体字段结构。
4. 汇总测试结果，输出 Markdown 格式的测试报告。

Hermes 支持从三个不同层级发现并加载技能。当存在同名技能时，按以下优先级自顶向下解析（First-match）：

1. 项目级技能 (Project Skills)
   └── 当前工作区根目录下的 .hermes/skills/ 或 .agents/skills/
       │ (优先级最高，仅在当前项目工作区生效)
       ▼
2. 用户级技能 (Local Skills)
   └── $HERMES_HOME/skills/
       │ (用户个人全局技能)
       ▼
3. 外部挂载技能 (External Dirs)
   └── config.yaml 中 skills.external_dirs 定义的路径

外部技能目录配置

在 $HERMES_HOME/config.yaml 中追加外部技能目录：

skills:
  external_dirs:
    - ~/.agents/skills
    - /opt/shared/team-skills

写权限说明：external_dirs 主要是发现路径，并非只读安全沙箱。若 Hermes 进程对挂载目录具备写权限，Agent 内部的 skill_manage 依然有权限对其进行修改。如需保证团队技能真正只读，应依靠操作系统层面的文件权限（如 chmod -R a-w）进行控制。

从外部代码仓库克隆项目时，仓库根目录可能包含随代码提交的 .hermes/skills/ 或 .agents/skills/。为了防止未受信任的代码库包含恶意注入指令，Hermes 引入了显式信任机制：

• 默认拦截：首次在未信任的工作区检测到项目技能时，Hermes 会弹出警告通知，默认不加载该目录下的项目技能；
• 授权命令：进入项目目录后，通过 CLI 显式授权或撤销：

# 信任当前工作区所在仓库的项目技能
hermes skills trust

# 撤销对当前仓库项目技能的信任
hermes skills untrust

已信任的工作区路径会被记录在 $HERMES_HOME/config.yaml 的 skills.trusted_project_dirs 中。

技能写入审核与危险拦截

• 人工审批闸门（`skills.write_approval`）：在 config.yaml 中配置 skills.write_approval: true 后，Agent 创建、修改、打补丁或删除技能的操作均会被推入暂存区（Staged），需由用户在终端中审查 Diff 后确认；
• 自动化安全扫描（`skills.guard_agent_created`）：独立的内容审查器，自动拦截包含危险模式的技能代码。

Automation Blueprint 是将普通 Skill 转化为定时任务的声明机制。它是在 SKILL.md 的 Frontmatter 中追加 blueprint 调度的标准技能：

---
name: daily-dependency-audit
description: "每日自动审计项目依赖项的安全漏洞。"
metadata:
  hermes:
    blueprint:
      schedule: "0 9   *"       # 每天上午 9 点运行
      deliver: origin             # 运行结果交付通道
      prompt: "执行依赖漏洞扫描，并输出高危预警列表。"
---

重要原则：安装带有 blueprint 声明的 Skill 不会自动在后台创建 Cron Job。安装后，Hermes 仅将其标记为建议任务，必须由用户通过终端 /suggestions 菜单或桌面端显式确认后，定时调度才会正式创建生效。

工具是 Agent 将模型推理转化为外部系统操作的核心执行接口。Hermes 提供内置 Tools，并可通过 MCP 扩展外部工具能力。

Hermes 内置了以下经过环境安全封装的核心工具：

• 终端执行（Terminal）：在受管子进程中执行 Shell 命令，支持超时控制、危险命令拦截与审批机制；
• 文件系统操作（File Tools）：代码查看、精准编辑（Patch）、全局正则检索（Grep）、文件发现（Glob）与写入；
• Web 检索与抓取：网络搜索与结构化页面文本提取；
• 浏览器自动化（Browser Automation）：支持页面导航、表单填写、截图与 DOM 解析。

MCP 是标准化 Agent 与外部数据源（代码仓库、数据库、企业知识库、SaaS 接口）通信的开放协议。

传输模式（Transports）

Hermes 支持两类标准的通信模式：

1. Stdio 模式：本地拉起外部进程，通过标准输入输出进行 JSON-RPC 通信；
2. Streamable HTTP 模式：通过 HTTP 接口连接常驻服务（兼容模式下支持显式指定 transport: sse）。

MCP 服务器在 $HERMES_HOME/config.yaml 的顶层字段 mcp_servers 中声明：

mcp_servers:
  # 1. Stdio 模式：本地文件系统扩展
  filesystem:
    command: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "/Users/walve/Documents/Workspace"
    timeout: 60                      # 工具调用超时时间（秒）
    enabled: true

  # 2. Stdio 模式：GitHub MCP 示例 (环境变量安全隔离引用)
  github:
    command: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-github"
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
    enabled: true

  # 3. Streamable HTTP / SSE 模式：连接远程私有只读数据库接口
  database-tools:
    url: "https://mcp-internal.example.com/sse"
    transport: sse
    headers:
      Authorization: "Bearer ${DB_MCP_SECRET}"
    timeout: 120
    connect_timeout: 30
    ssl_verify: true
    enabled: true
    tools:
      include:                       # 纯白名单机制：仅向 Agent 暴露只读工具
        - query_readonly_db
        - get_table_schema
      resources: false              # 禁用外部 Resource 注入以节约上下文
      prompts: false                # 禁用外部 Prompt 模板注入

MCP 管理常用命令

# 查看已在 config.yaml 中配置的 MCP 服务器列表
hermes mcp list

# 测试指定 MCP 服务的进程拉起与协议握手
hermes mcp test github

# 从 Claude Code 等其他 Agent 导入现有 MCP 配置
hermes import-agent claude-code

提示：如果在运行期间修改了 config.yaml 中的 MCP 配置，在交互会话中输入 /reload-mcp 即可重新加载服务。

• 子进程环境变量清洗：Hermes 默认不会将宿主机的所有环境变量传给 Stdio MCP 子进程。常见的全局 API Key 会被自动过滤，只有在对应 mcp_servers.<name>.env 中显式声明的变量才会被传入。
• Tool Search 延迟加载机制：当挂载的 MCP 服务提供了较多外部工具时，全量暴露 Tool Schema 会挤占 System Prompt 上下文。Hermes 内置了 Tool Search 机制，将非核心的外部工具推迟到需要时按需检索加载，而核心内置工具始终保持就绪。

随着交互轮次的累积，会话上下文中的 Token 数量持续攀升。如果长会话反复携带过长的历史记录，累计输入成本会快速增长，甚至超出模型上下文窗口限制。

Hermes Agent 内置了双层压缩防护与前缀缓存适配机制。

               用户发送新消息
                    │
                    ▼
     ┌─────────────────────────────┐
     │ 1. Gateway Session Hygiene  │
     │    (消息前置安全网，固定 85%) │
     └──────────────┬──────────────┘
                    │ 未超限 / 压缩后
                    ▼
     ┌─────────────────────────────┐
     │ 2. Agent ContextCompressor  │
     │    (主压缩引擎，默认 50% 基准)│
     └──────────────┬──────────────┘
                    │
                    ▼
               执行模型推理

1. Gateway Session Hygiene（消息前置安全网）：

位于消息网关层，阈值固定为 85%。优先使用上一轮 API 报告的实际 Token 数，缺失时退回预估。用于拦截隔夜累积的大量消息，防止直接打爆窗口。

1. Agent ContextCompressor（主压缩引擎）：

位于 Agent 主工具循环内部，基准默认阈值为 50%（compression.threshold: 0.50）。实际生效阈值还会结合特定模型的上下文底线（small-context floor）以及模型特定参数动态计算。

当会话 Token 达到有效阈值时，引擎按四个阶段进行处理：

原始上下文:
[ System Prompt ] + [ 首轮用户对话 ] + [ 中间多轮交互与大段工具输出 ] + [ 最近交互轮次 ]
        │                   │                         │                      │
        ▼                   ▼                         ▼                      ▼
    完整保护            完整保护               1. 确定性清理旧工具输出        动态 Tail 保护
                                              2. LLM 结构化提炼摘要         (lean 模式保留)
                                                      │
                                                      ▼
压缩后上下文:
[ System Prompt ] + [ 首轮用户对话 ] + [ 结构化历史摘要与检索锚点 ] + [ 最近未压缩的 Tail 消息 ]

1. 裁剪历史工具输出（Phase 1，不调用 LLM）：确定性地清理 protected tail 之外的大段历史工具返回结果，将其替换为简短占位提示。
2. 保护头部（Phase 2）：完整保留 System Prompt 与首轮交互目标。
3. 中间轮次摘要提炼（Phase 3）：由辅助模型对中间复杂轮次生成结构化总结，在后续压缩中增量迭代更新。
4. 动态尾部保留（Phase 4，`tail_mode: lean` 当前默认）：

保留约 2.5% × context window 的原生对话（设置有 10K floor 与 25K cap 边界）。并通过保留标识符的会话日志、机械提取的锚点索引以及 session_search 追溯指针来保障语义连贯。

重要警告：为压缩任务配置的辅助模型（auxiliary.compression）必须具备足够大的上下文窗口来吞吐待压缩的历史。若压缩模型的 Context 窗口过小，摘要请求将直接报错，可能导致中间轮次在未获得有效摘要的情况下被移除，造成上下文丢失。

用户可以在终端交互中随时根据需要手动整理历史：

• /compress：触发标准上下文压缩；
• /compress focus <topic>：指定焦点主题，在压缩时保留与该主题相关的事实并剔除闲聊；
• /compress here：保留当前位置最近的轮次，对其余历史进行压缩；
• /compress here <N>：保留最近 N 个完整的交互回合（Exchange），压缩更早的历史。

在完整的 Agent 运转链路中，并非所有子任务都需要由最昂贵、推理能力最强的主模型来完成。

Hermes 引入了 Auxiliary Client（辅助任务路由器），将压缩提炼、视觉解析、标题生成、命令审查等专项任务剥离为独立的子任务槽位（Task Slots）。

说明：网页内容提取（Web extraction）与长文本抓取已改为确定性截断配合落盘分页读取，不再调用辅助 LLM。

默认情况下，各辅助任务均处于 provider: auto 模式。其解析顺序如下：

当前主模型 Provider + 主模型
        │ (若主链路无法承载该任务，如文本模型遇视觉任务)
        ▼
auxiliary.<task>.fallback_chain (若配置了个别任务降级链)
        │
        ▼
顶层 fallback_providers (若配置了全局备用链路)
        │
        ▼
系统内置 auxiliary discovery chain (自动探测 OpenRouter、Nous Portal、本地 Endpoint 等可用凭证)
        │
        ▼
解析失败报错

提示：provider: auto 默认首先复用主模型，并不等于系统会自动替用户挑选廉价模型。如需降低辅助任务开销，需显式为其指定模型。

推荐通过交互式命令完成辅助模型分配：

hermes model
# 选择 "Configure auxiliary models" 选项，即可设置各槽位模型

在 $HERMES_HOME/config.yaml 中的对应结构示例如下：

# 辅助模型配置结构 (占位符示意)
auxiliary:
  # 1. 压缩摘要：指定长上下文模型
  compression:
    provider: <PROVIDER>
    model: <SUMMARY_MODEL_ID>

  # 2. 视觉任务：指定多模态模型
  vision:
    provider: <PROVIDER>
    model: <VISION_MODEL_ID>

  # 3. 标题生成：开启并偏向选用极速小模型
  title_generation:
    enabled: true
    prefer_fast_model: true

Hermes 提供了几个不同层级的并发与协作机制，用于处理多任务分流、角色隔离与跨节点通信：

1. Subagent（会话内子代理）
2. Profile（持久状态隔离）
3. Bot Mode（桌面端多 Bot 协同）
4. Peer（跨机器 / 跨网关通信）

消息网关（Gateway）作为消息接入层，负责将外部聊天平台的消息流量路由至对应的 Profile 或 Bot。

重要安全原则：Profile 不是安全沙箱（Profile is NOT a sandbox）
Profile 隔离的是配置、会话、记忆与技能状态，但在默认的终端执行环境下，Agent 依然拥有当前操作系统用户的常规权限。对系统的实际访问边界由系统级 Sandbox/Container 控制。

当父 Agent 调用 delegate_task 生成子代理时：

• 子代理启动在全新且隔离的上下文会话中，看不到父会话的历史交互；
• 子代理主要接收父 Agent 显式传递的 goal 与 context；如果父 Agent 已解析出 workspace，子 Agent 还会自动加载该 workspace 的项目 Context Files（SOUL.md 除外）；
• 默认的叶子子代理（Leaf Subagent）无法调用 delegate_task（防止无限递归）、clarify（禁止直接打扰用户）、memory（禁止修改持久记忆库）、send_message（禁止发送外部平台消息）与 cronjob；但保留 execute_code 运行能力；
• 子代理运行在独立的终端会话中；当多个子代理并行修改同一个 Git 代码库时，可配置 delegation.worktree_isolation: true 开启 Git Worktree 隔离。

Profile 基础命令

# 创建名为 research 的新 Profile
hermes profile create research

# 列出本地所有 Profile
hermes profile list

# 在指定 Profile 下启动终端交互
hermes --profile research

Bot-to-Bot 与 Peer 通信

• 本机 Bot 协作：在 Desktop Bot Mode 下，Bot 之间调用 message_agent(target="<bot_name>", message="...") 实现非阻塞协同；
• 跨网关 Peer 互联：当需要连接运行在另一台远端服务器上的 Hermes 节点且不依赖本地 Desktop 时，使用 hermes peer 系列命令（远端需拉起 API Server）：

# 注册远端 Peer 节点 (API_SERVER_KEY 为远端鉴权密钥)
hermes peer add server-node --url https://agent-gpu.internal.example.com:8443 --key <API_SERVER_KEY>

# 向远端 Peer 节点发送交互任务
hermes peer dm server-node "拉取最新训练指标并生成分析图表"

Hermes Agent 内置了原生的 Cron 调度系统，由 Gateway Scheduler 守护驱动，使 Agent 能够脱离前台终端，在后台自主执行周期性任务。

【单任务周期性执行：Continuity 机制】
第 N 次运行输出: "发现 3 篇 AI 新论文: A, B, C"
       │
       ▼ (自动注入为第 N+1 次的上下文)
第 N+1 次运行 Prompt: "扫描新论文，注意：避免重复汇报上一轮已提及的条目"
       │
       ▼
第 N+1 次运行输出: "仅增量发现 1 篇新论文: D"

────────────────────────────────────────────────────────

【多任务链式编排：context_from 机制】
[ Job A (数据采集) ] ──(最新已完成输出)──> [ Job B (context_from: ["Job A"]) ]
                                                   │
                                                   ▼
                                          执行数据分析与汇总推送

1. Continuity 增量上下文（`--continuity`）：

在任务中开启 --continuity 后，每次运行时会自动将自身上一轮的输出作为前置上下文载入（仅携带上一轮，不无限堆叠历史），实现去重与增量追踪。

1. `context_from` 链式依赖：

允许当前 Job 读取指定的上游 Job 最近一次已经成功完成的输出结果，用于组织数据流水线。注意它不会阻塞等待同一调度时刻仍在并发运行的任务，编排时需合理错开执行周期。

1. `no-agent` / Script-only 纯脚本模式：

对于固定的指标探活或数据清理任务，可指定脚本直接以子进程运行，不产生任何 LLM 推理开销。执行脚本必须位于 $HERMES_HOME/scripts/ 目录内，子进程环境变量会被清洗。

小提示：Monitor 变化监控模式
Hermes Cron 支持监控模式（如 --monitor-script 或 --monitor-url）。在此模式下，当检测目标数据未发生变化时，调度器会直接跳过 Agent 与 LLM 执行；仅当探针检测到真实内容变化或 Diff 时，才会将增量变化内容转交 Agent 进行智能分析，显著节约周期性探测的 Token 消耗。

Cron 任务运行时的模型解析遵循以下顺序：

单任务显式指定的 Provider/Model Pin
        │ (若未显式锁定)
        ▼
全局 cron.model 与 cron.model_provider
        │ (若未设置)
        ▼
全局默认模型 (Global Default)

• Model Drift Guard（模型漂移安全拦截）：

默认开启（cron.model_drift_guard: true）。对于未锁定模型的 Cron 任务，如果用户在前台修改了全局默认模型，调度器在检测到漂移后会主动拦截并跳过执行，防止因全局切换至高单价模型导致后台无人值守任务产生意外支出。

重要说明：Cron Job 数据持久化存储在 $HERMES_HOME/cron/jobs.json 中，不建议手动编辑该 JSON 文件，应统一通过 CLI 或交互界面管理。

常用管理命令

# 查看所有已配置的 Cron 任务
hermes cron list

# 查看指定任务的历史执行记录
hermes cron runs <job_id> --limit 20

# 暂停与恢复任务
hermes cron pause <job_id>
hermes cron resume <job_id>

# 标记指定任务在下一次 Scheduler Tick 时立即执行
hermes cron run <job_id>

# 查看当前 Cron 调度器状态
hermes cron status

实战创建任务示例

通过 CLI 创建任务时，若未指定 --workdir，任务默认在隔离的会话中执行；对于特定代码仓库的巡检任务，需显式传入 --workdir 以加载项目规则：

# 创建每日增量科技简报任务 (带 Continuity 自动去重，本地交付)
hermes cron create "0 8   *" \
  "扫描过去 24 小时内的重点技术动态。根据上一轮输出，严格剔除已汇报内容，整理 3 条新增要点。" \
  --provider <PROVIDER> \
  --model <MODEL_ID> \
  --continuity \
  --deliver local \
  --workdir /Users/walve/Documents/Projects/my-app

守护进程确认：Cron 任务的定时自动触发由 Gateway 调度器驱动。在离开前台前，请通过 hermes gateway status 确认网关服务正在运行。

当 Agent 拥有执行 Shell 命令、修改本地文件与调用外部工具的能力时，必须建立清晰的安全边界。

Hermes Agent 采用了分层的防御机制：

               Agent 发起操作请求
                        │
         ┌──────────────┴──────────────┐
         ▼                             ▼
   【Shell 命令执行】            【资产修改操作】
         │                             │
    Hardline Blocklist           memory.write_approval /
  (硬性拦截，宿主环境下不可绕过)   skills.write_approval
         │                             │
         ▼                             ▼
   approvals.deny 规则           进入暂存区 (Staging)
         │                             │
         ▼                             ▼
   Dangerous Pattern 审查         等待用户审批 (/skills diff ...)
   (smart / manual 审批)

在本地执行环境下，Hermes 设置了三级安全过滤：

1. 硬性黑名单（Hardline Blocklist）：

对于不可逆的文件系统擦除（如 rm -rf /）、Fork Bomb、直接覆写块设备等极端破坏性命令，系统在底层实行硬性拦截。Hardline Blocklist 是 host-reaching backend 下审批体系不可覆盖的安全底线；Docker、Modal、Daytona、Vercel Sandbox 等隔离 backend 以容器/沙箱自身作为安全边界，危险命令 guard stack 可被跳过。

1. 用户级永久拒绝规则（`approvals.deny`）：

在 $HERMES_HOME/config.yaml 中配置 Glob 匹配规则，无条件拦截匹配的命令模式：
``yaml
approvals:
deny:
- "git push --force*"
- "*curl*|*sh*"
``

1. 高危命令审批（`approvals.mode`）：

- `smart`（默认模式）：对命中危险模式的命令使用 Auxiliary LLM 评估风险；低风险命令可自动批准，明显危险命令自动拒绝，不确定情况升级为人工确认；
- `manual`：所有命中危险模式的命令均要求人工审批；
- `off`：关闭常规交互审批（Hardline 与 approvals.deny 在 host-reaching backend 下依然生效）。

交互式审批按键：

• [o] Once：仅本次允许执行；
• [s] Session：在当前会话生命周期内允许该命令；
• [a] Always：永久将该模式加入白名单；
• [d] Deny：拒绝执行。

• 敏感文件写入保护：内置的 write_file 与 patch 工具对系统关键路径实施了保护，防止直接篡改 ~/.ssh、~/.aws、~/.kube、Hermes 自身的 auth.json / .env 以及项目级敏感配置文件。可选通过环境变量 HERMES_WRITE_SAFE_ROOT 约束写入基准目录。
• 环境隔离边界：必须明确，File Write Safety 主要约束 Agent 的内置文件写入工具；在默认宿主机终端中执行命令时，子进程依然具备当前操作系统的用户权限。真正限制 Agent 对宿主机的可访问范围与最大破坏范围的方式是使用 Docker、Modal、Daytona 等独立的容器隔离 Backend。

• Context File 注入防御：在载入 SOUL.md、AGENTS.md、.hermes.md 以及项目 Skills 前，系统会执行安全扫描，排查隐藏文本、恶意提示词注入与凭证析出风险。
• 凭据脱敏（Secret Redaction）：默认启用（security.redact_secrets: true），尽最大努力对日志与输出文本中的 Token 和私钥模式进行打码遮蔽。
• 操作快照与回滚（Checkpoints）：在 config.yaml 中配置 checkpoints.enabled: true 后，Agent 在执行文件修改前会基于 Shadow Git 自动创建还原点。

- /rollback：列出历史还原点；
- /rollback diff <id>：查看指定版本的差异；
- /rollback <id>：一键回退工作区文件至指定快照。

为了避免配置文件臃肿且易随版本迭代过时，推荐采用模块化配置方式。核心配置文件为 $HERMES_HOME/config.yaml，敏感密钥集中存放在 $HERMES_HOME/.env。

适合初次配置或追求基础对话与工具调用的用户：

# $HERMES_HOME/config.yaml - 基础模块
model:
  provider: <PROVIDER>
  default: <MODEL_ID>

# 命令审批模式 (smart: 默认智能提示 | manual: 生产严格手动确认 | off: 关闭常规提示)
approvals:
  mode: smart

对应 $HERMES_HOME/.env 说明：

关于 API Key 环境变量：API Key 的实际环境变量名因 Provider 而异，推荐通过 hermes model 完成配置，由 Hermes 写入或管理对应 Secret；如需手动配置，请以当前 Provider 官方文档中的环境变量名为准。

适合配置了多个 API Key 或需要跨厂商兜底的场景：

# $HERMES_HOME/config.yaml - 高可用模块
# 1. 凭证池轮换策略 (fill_first: 顺延优先 | round_robin: 轮询 | least_used: 最少调用)
credential_pool_strategies:
  <MAIN_PROVIDER>: fill_first

# 2. 跨 Provider 备用降级链 (按列表顺序依次尝试)
fallback_providers:
  - provider: <FALLBACK_PROVIDER_1>
    model: <FALLBACK_MODEL_ID_1>
  - provider: <FALLBACK_PROVIDER_2>
    model: <FALLBACK_MODEL_ID_2>

默认情况下辅助任务会自动继承主模型（provider: auto）。若需要将特定任务剥离至专用模型，可按需声明：

# $HERMES_HOME/config.yaml - 辅助任务模块 (结构示例，按需覆盖)
auxiliary:
  compression:
    provider: <PROVIDER>
    model: <SUMMARY_MODEL_ID>

  vision:
    provider: <PROVIDER>
    model: <VISION_MODEL_ID>

  title_generation:
    enabled: true
    prefer_fast_model: true

适合对文件与代码安全性有较高要求的环境：

# $HERMES_HOME/config.yaml - 安全加固模块 (按需选用)
approvals:
  mode: smart
  deny:
    - "git push --force"
    - "curl|sh*"

# 开启记忆与技能写入人工审批
memory:
  write_approval: true

skills:
  write_approval: true
  guard_agent_created: true
  external_dirs:
    - ~/.agents/skills

# 开启文件修改自动快照
checkpoints:
  enabled: true

# $HERMES_HOME/config.yaml - MCP 模块
mcp_servers:
  # 本地文件系统扩展
  filesystem:
    command: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "/Users/walve/Documents/Workspace"
    timeout: 60
    enabled: true

  # 远程只读服务 (纯白名单限制与资源节约)
  internal-readonly:
    url: "https://mcp-internal.example.com/sse"
    transport: sse
    headers:
      Authorization: "Bearer ${INTERNAL_TOKEN}"
    enabled: true
    tools:
      include:
        - query_readonly_data
      resources: false
      prompts: false

除了官方内置的 Provider 与功能外，社区围绕 Hermes 开发了第三方 Plugin 与适配方案。使用此类扩展时，需明确其边界与风险。

Hermes 提供了插件管理工具，支持从社区插件索引（Community Plugin Index）或 Git 仓库安装：

# 打开交互式插件管理看板
hermes plugins

# 查看已安装插件的状态
hermes plugins list

# 从 Git 仓库按不可变的完整 Commit SHA 安装插件 (推荐，防止上游意外变更)
hermes plugins install <owner/repo> --ref <FULL_40_CHARACTER_COMMIT_SHA>

# 显式启用或禁用插件
hermes plugins enable <plugin-name>
hermes plugins disable <plugin-name>

# 审查指定插件声明与获得的系统权限
hermes plugins capabilities <plugin-name>

# 诊断指定插件的健康状态
hermes plugins doctor <plugin-name>

安全认知：
1. Indexed != Audited：被收录入社区插件索引仅代表其格式符合规范，不等于官方已对其代码执行了安全审计；
2. Capability != Sandbox：插件的权限声明（Capabilities）属于授权与审计层，被激活后的插件代码依然直接在宿主机环境中执行。

社区中存在一些针对未开放 API 或实验性认证路径的适配方案（如非官方的 Antigravity 插件等）。这类实现可能采用浏览器 OAuth 模拟、复用本地现有客户端凭据或请求协议转换等手段。

• 服务限制与账号风险：相关插件作者通常明确标注，此类调用可能触及服务商的使用限制策略，存在账号被限流、暂停或封禁的风险；
• 供应链防范：引入第三方扩展前，务必审查源码，锁定 Commit SHA，并优先在非核心的隔离测试环境中运行。

熟练掌握系统诊断、数据迁移与版本更新流程，是保持 Agent 长期稳定运行的基础。

# 检查当前安装、依赖与配置健康度
hermes doctor

# 尝试自动处理当前版本支持修复的常见问题
hermes doctor --fix

hermes doctor 用于排查常见运行问题，实际检查项以当前 CLI 输出为准。

针对不同的迁移与分享场景，Hermes 提供了三种不同维度的归档机制：

用户状态备份与恢复实操

# 1. 创建状态备份 (默认生成 ~/hermes-backup-<timestamp>.zip)
hermes backup

# 2. 快速快照模式 (仅归档配置、状态 DB 与密钥)
hermes backup --quick

# 3. 在新机器上导入还原 (执行前需确保已停止运行中的 Gateway)
hermes gateway stop
hermes import ~/hermes-backup-20260901.zip

说明：hermes backup 备份的是用户数据与配置状态（通过 SQLite 专用备份接口生成一致性副本），不包含 Hermes 程序代码本身。若升级后遇到代码层面的兼容问题，需重新安装对应的程序版本。

Profile 导出与导入实操

# 导出单 Profile (自动排除私密凭据)
hermes profile export coder -o coder.tar.gz

# 导入为新的独立 Profile
hermes profile import coder.tar.gz --name team-coder

Hermes 提供了内置的代码更新指令：

# 1. 预检模式：仅对比远端版本，不改动任何本地文件
hermes update --check

# 2. 常规升级：拉取新版本 (默认会自动执行轻量状态快照)
hermes update

# 3. 高安全升级：升级前强制执行完整的全局备份归档
hermes update --backup

Windows 环境提示：在 Windows 原生环境中，若 Desktop、终端交互会话或后台 Gateway 正在占用 hermes.exe，更新可能会报错。请先退出前台交互，执行 hermes gateway stop 停止后台网关，然后再执行更新。

以下为基于 Hermes Agent v0.21.0 严格核验的常用命令速查表。

在当前的工具生态中，各类大语言模型展现出了出色的通用推理能力，但底层模型推理请求本身并不负责长期状态管理。

Hermes Agent 的价值并不在于训练新的模型，而在于把模型、持久记忆、可复用技能、工具生态、后台自动化与权限管理，组织成一个可长期稳定运行的 Agent 运行时底盘（Harness）：

• 通过结构化的 Markdown 规范维护透明、可审计的长期记忆；
• 通过分层的 Skills 体系使团队沉淀的工作流能够按需组装；
• 通过 Credential Pools 与 Fallback 机制保障服务请求的高可用；
• 通过内置的 Cron 调度器与 Continuity 上下文管道，在明确的权限与调度规则下持续执行后台任务。

构建长期 Agent 的关键不是把所有配置堆进一个文件，而是把不同职责放在合适的位置：将项目规范留在 .hermes.md / AGENTS.md，将通用的行为准则写入 SOUL.md，将高频流程封装为声明式的 SKILL.md，并通过完善的审批与隔离机制保护好本地系统的执行边界。

1. Hermes Agent 官方文档

https://hermes-agent.nousresearch.com/docs/

1. NousResearch/hermes-agent 官方 GitHub 仓库

https://github.com/NousResearch/hermes-agent

1. Hermes Agent v0.21.0（Release tag: `v2026.8.31`）发行说明

https://github.com/NousResearch/hermes-agent/releases/tag/v2026.8.31

1. Model Context Protocol (MCP) 官方技术规范

https://modelcontextprotocol.io/

1. OSV.dev 开源漏洞数据库（用于 `hermes security audit`）

https://osv.dev/