Hermes Agent
进阶手册

Hermes 的每个能力都是「工具」。学会写工具，你就突破了框架的上限——Agent 能做什么，取决于你写了什么工具。

工具的本质：Schema + Handler

一个工具由两部分组成：Schema（告诉 Agent「我可以这样调用你」）和 Handler（实际执行的 Python 函数）。

单文件工具：最简实现

# ~/.hermes/tools/my_tool.py
import json

# 1. 定义 Schema（Agent 看到的说明书）
MY_TOOL_SCHEMA = {
    "name": "lookup_express",
    "description": "查询快递物流信息。输入快递单号，返回最新物流状态。",
    "parameters": {
        "type": "object",
        "properties": {
            "tracking_number": {"type": "string", "description": "快递单号"}
        },
        "required": ["tracking_number"]
    }
}

# 2. 实现 Handler
def lookup_express_handler(args, **kw):
    tracking = args.get("tracking_number", "")
    # 这里调用真实快递 API...
    result = {"status": "运输中", "location": "上海分拣中心", "eta": "1 天"}
    return json.dumps(result, ensure_ascii=False)

# 3. 注册到 Hermes
from tools.registry import registry
registry.register(
    name="lookup_express",
    toolset="custom",
    schema=MY_TOOL_SCHEMA,
    handler=lookup_express_handler,
    emoji="📦"
)

多文件工具集（推荐结构）

# ~/.hermes/tools/pdd_tools/
# ├── __init__.py       ← 入口：注册所有工具
# ├── download.py       ← 下载工具
# ├── analyze.py        ← 分析工具
# └── report.py         ← 报吿工具

# __init__.py:
from tools.registry import registry
from .download import DOWNLOAD_SCHEMA, download_handler
from .analyze import ANALYZE_SCHEMA, analyze_handler
from .report import REPORT_SCHEMA, report_handler

registry.register(name="pdd_download", toolset="pdd", schema=DOWNLOAD_SCHEMA, handler=download_handler)
registry.register(name="pdd_analyze", toolset="pdd", schema=ANALYZE_SCHEMA, handler=analyze_handler)
registry.register(name="pdd_report", toolset="pdd", schema=REPORT_SCHEMA, handler=report_handler)

在 config.yaml 中启用自定义工具集

从「每次手动输入命令」到无人值守自动运行——这是 Hermes 从工具升级为平台的关键一步。

Cron 语法速查

实战：每日竞品监控全链路

# 添加每日竞品监控任务
hermes cron add --cron "0 8 * * *" \
  --prompt "打开拼多多，搜索「{产品关键词}」Top 5 竞品，记录价格和月销量，
            与昨日数据对比，价格波动超过 5% 的推送到微信。" \
  --name "每日竞品监控"

# 查看所有任务
hermes cron list

# 手动触发一次（调试用）
hermes cron run --name "每日竞品监控"

T+0/T+3/T+6 多阶段自动分析

SOUL.md 不是你写一段介绍就行了——它是注入到 System Prompt 第一层的完整指令。写好它 = 给 Agent 装了一副你定制的「眼睛和性格」。

System Prompt 三层架构

SOUL.md 在 Stable 层，是整个会话的第一优先级——比 Memory、Skills 优先级都高。后面的所有内容无法覆盖 SOUL 的约束。

约束 vs 建议：写法差异

# ❌ 建议式（弱，Agent 可能忽略）
你可以尝试给出简洁的回复。

# ✅ 约束式（强，Agent 必须遵守）
你的每条回复不超过 3 句话。如果超过，先删减再发送。

# ❌ 建议式
最好先分析数据再给出结论。

# ✅ 约束式
遵循 DATA→ANALYSIS→CONCLUSION 三步骤。缺少任何一步即视为未完成任务。

人格场景库：开箱即用的 SOUL 模板

以下四个模板可以直接粘贴到 SOUL.md，微调后生效：

网关是 Hermes 的24/7 在线入口。消息平台发来的每条消息都经过网关路由到 Agent，Agent 回复再通过网关返回。

多平台并发运行

# 在 config.yaml 的 platform_toolsets 中为每个平台配不同工具：
platform_toolsets:
  weixin:
    - hermes-weixin
    - terminal
    - file
  telegram:
    - hermes-telegram
    - web_search
    - browser
  discord:
    - hermes-discord
    - execute_code
    - memory

微信接入全配置

# ~/.hermes/.env
WEIXIN_ACCOUNT_ID=your_bot@im.bot
WEIXIN_TOKEN=bot_token_here
WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com
WEIXIN_DM_POLICY=pairing  # pairing=需配对码才能私聊, open=所有人
WEIXIN_GROUP_POLICY=disabled # disabled=不进群, mention_only=被@才回

自定义平台接入

Hermes 支持通过 --platform 注册自定义平台。本质就是实现一个「收消息 → 调 Agent → 回消息」的适配器：

# 以 webhook 为例——任何能发 HTTP 请求的系统都能接入
# 1. 启动 Hermes 内置 webhook 服务
hermes webhook start --port 9999

# 2. 任何系统 POST 到 http://localhost:9999/webhook
# Body: {"message": "..., "user": "...", "platform": "my-app"}

# 3. Hermes 自动路由到 Agent → 返回回复

当 Hermes 处理敏感数据或在生产环境运行时，安全不是选项——是底线。

Write Approval：写入操作的「审批链」

# 开启后，每次 write_file/patch/terminal rm 都需手动批准
hermes config set write_approval true

# 或直接在 config.yaml 中：
agent:
  write_approval: true

AgentGuard：自动安全扫描

Hermes 内置 AgentGuard，扫描所有命令中的敏感操作（删除系统文件、访问敏感目录、泄露 API Key 等）。

沙箱执行：隔离危险操作

切换 terminal backend 到 Docker/Modal，让 Agent 的命令在隔离容器中运行：

容器内挂载只读目录、限制网络白名单，即使 Agent 被 prompt injection 也破坏不了宿主机。

数据隐私 Checklist

单个 Profile 是个人助理，多个 Profile 就是一支 AI 团队。用 Git 管理、团队共享、批量部署——把 Profile 当代码对待。

Profile 即代码

# 初始化一个 Profile 为 Git 仓库
cd ~/.hermes/profiles/my-agent
git init && git add SOUL.md config.yaml memories/ skills/
git commit -m "v1.0: 财务分析 Agent"

# 团队成员拉取并安装
hermes profile install git@github.com:team/finance-agent.git

# 发布更新
hermes profile update finance-agent # 拉取最新，保留用户的记忆不变

Profile 分发

Profile 间隔离与共享

一个 Agent 是瑞士军刀，多个 Agent 分工协作才是生产线。Hermes 支持 Master 拆解任务、路由给专业子 Agent、汇总结果。

Delegation 调度架构

启用 Delegation

# config.yaml:
delegation:
  enabled: true
  max_concurrent_children: 3  # 最多 3 个子 Agent 并行
  max_iterations: 50
  child_timeout_seconds: 600

子 Agent 选型策略

Kanban 多 Agent 看板

不想手动 orchestrate？用 Kanban 系统让多个 Agent 从共享任务池里自动取任务：

macOS 用户独享——让 Hermes 在后台控制你的桌面：截图、点击、打字、滚动，不抢你的鼠标和焦点。你可以和 Agent 共用一台 Mac。

安装与启动

工作流程：SOM（元素标记）模式

# Agent 的标准操作流程
# 1. 截屏 + 标记每个可交互元素
computer_use action="capture" mode="som"
# → 返回截图，上面每个按钮/输入框/菜单都标注了数字

# 2. 按编号点击（比坐标可靠 10 倍）
computer_use action="click" element=14

# 3. 输入文字
computer_use action="type" text="hello"

# 4. 快捷键
computer_use action="key" keys="cmd+s"

# 5. 再截屏验证结果
computer_use action="capture" capture_after=true

安全规则（必读）

实战：自动操作 Excel

# 一句话让 Hermes 操作 Excel 生成报表
"打开桌面上的 销售数据.xlsx，筛选本月订单，生成柱状图，保存为 PDF"

# Agent 自动执行：
# capture(som) → 找到 Excel 窗口 → click element=5 激活
# key cmd+shift+L → 打开筛选 → click element=12 选「本月」
# key alt+F1 → 插入图表 → click element=8 选柱状图
# key cmd+s → 另存为 PDF

MCP（Model Context Protocol）是 AI 生态的工具共享标准协议。Hermes 能做两件事：作为 Client 调用外部 MCP Server 的工具，以及作为 Server 把自身暴露给 Claude Desktop 等 MCP Client。

Hermes 作为 MCP Client：接入外部工具

任何 MCP Server —— 数据库查询、文件管理、API 网关 —— 一键接入后自动成为 Hermes 可用工具集。

Hermes 作为 MCP Server：暴露给其他 Agent

运行后，Claude Desktop / Cursor / 任何 MCP Client 都能调用 Hermes 的全部工具（terminal + file + web_search + 自定义工具）。

# 启动 Hermes MCP Server
hermes mcp serve --port 3100

# 在其他 MCP Client 的配置中添加：
{
  "mcpServers": {
    "hermes": {
      "url": "http://localhost:3100/sse"
    }
  }
}

Agent 不听话？工具调用失败？响应变慢？掌握这套诊断工具链，自己定位问题而非猜测。

诊断命令矩阵

System Prompt 分析

prompt-size 能告诉你 System Prompt 每一部分占了多少字符——知道 memory 快爆了、skills 太占地方、还是 SOUL 写太长了：

# 输出示例：
STABLE TIER (identity + tools + skills):     8,234 chars
  SOUL.md:                                    1,862 chars
  skills index:                               2,140 chars
  tool guidance:                                892 chars
  ...
CONTEXT TIER (context files):                 4,210 chars
VOLATILE TIER (memory + time):                1,834 chars
  MEMORY.md:                                  1,450 chars
  USER.md:                                      312 chars
────────────────────────────────────────────
TOTAL:                                       14,278 chars

日志排查技巧

常见故障速查