Hermes Action Bridge

Hermes Action Bridge

一个可配置的桥接工具，可让外部 Agent 将实际操作委托给 Hermes Agent，无需重新实现 Hermes 技能、工具、平台集成、浏览器自动化、cron 作业或消息流程。

可从 Claude Code、Codex、Cursor、CI 作业、Shell 脚本或其他支持 MCP 的客户端使用。MCP 执行需要通过交互式表单收集输入， 在非交互式客户端中会安全失败；plan、draft、dry-run 和直接 CLI 工作流仍可用于自动化。

external agent -> hermes-action -> Hermes Agent -> skills/tools/integrations

为什么要开发它

编码 Agent 擅长理解代码仓库，但不应该重复构建你的自动化技术栈。

如果 Agent 需要在本地编码会话之外执行任务——研究、安排作业、开启浏览器工作流、发送消息、准备社交媒体帖子、使用 Hermes 技能，或与消息网关协作——它可以通过此桥接工具将请求委托给 Hermes。

功能

• 通用的 hermes-action run 命令，用于单次委托。
• 可配置的预设，用于设置技能、工具集、提供商/模型、来源和最大轮数。
• 确定性且与语言无关的安全策略：默认将 execute 降级为 request-approval，并支持按预设覆盖信任设置。
• 提供显式的 --yolo 模式，供有意绕过桥接层策略的用户使用。
• 注入上下文文件，限制单个文件大小，并配置总预算（超出时给出清晰错误，而非晦涩的 E2BIG）。
• 自动传递大型上下文：提示词过大时，会通过安全的临时文件传给 Hermes，而不会导致命令行溢出。
• 单次运行超时（可配置，并为不同模式提供默认值），始终会回收 Hermes 子进程。
• Dry-run 模式，可调试实际的 Hermes 命令、提示词和计算出的提示词大小。
• 完整的 Codex 和 Claude Code 安装程序：托管的技能以及经过验证的全局 MCP 注册。
• MCP 功能发现、可取消的异步作业，以及仅在交互式表单收集输入后才启用的一次性两阶段审批；并提供保护隐私的本地审计日志。
• 本地 stdio 传输，以及可选启用的、经过身份验证的 Streamable HTTP 传输，适用于受 Tailscale 限制的主机。
• 不依赖特定项目。所有行为均通过 YAML 和 CLI 标志配置。

要求

• Node.js 20 或更高版本。
• 已安装 Hermes Agent，且可通过 hermes 运行；也可配置自定义命令路径。

检查 Hermes：

hermes --version

安装

从 npm 安装：

npm install -g hermes-action-bridge

为 Codex 和 Claude Code 安装技能并注册 MCP，然后验证 完整设置：

hermes-action --version
hermes-action install all
hermes-action doctor

针对所请求 Agent 的全局安装要么全部成功，要么全部失败。如果 Codex 或 Claude Code 不可用、存在冲突，或无法验证其用户级 stdio MCP 条目，命令将以非零状态退出，且不会安装所请求的 技能。使用 --project 可显式进行仅安装技能的设置。

其他分发渠道

选择与 Agent 使用界面相匹配的渠道。Hermes Agent 必须始终与本地桥接程序安装在同一台计算机上，并在该计算机上完成配置。

独立 Agent Skill 只会教 Agent 何时以及如何委派；它不会注册 MCP 服务。需要 MCP 工具时，请使用 npm 安装程序、Claude marketplace 或 MCPB 渠道。

发布新版本的维护者应遵循分发操作手册，其中涵盖自动发布工作流和手动目录发布检查。

Codex CLI 和 ChatGPT 桌面应用中的 Codex 界面共用同一主机上的本地 Codex MCP 配置。通用 ChatGPT 连接器属于不同的分发目标：它需要可通过远程访问的 MCP 服务，且不会通过此本地 stdio 包安装。

git clone https://github.com/TheBlueHouse75/hermes-action-bridge.git
cd hermes-action-bridge
npm install
npm run build
npm link

快速开始

在项目中创建配置文件：

hermes-action init

请 Hermes 制定安全计划：

hermes-action run --mode plan "Find the best next action from this repository context."

使用上下文文件进行委派：

hermes-action run \
  --preset research \
  --context ./notes.md \
  "Analyze this and return the next concrete action."

运行 dry-run，检查将发送给 Hermes 的内容：

hermes-action run --dry-run --json "Summarize this project."

执行模式

• plan：指示 Hermes 仅返回计划。将其视为开放世界模式，因为已配置的工具仍然可用。
• draft：Hermes 仅生成产物，不会产生外部副作用。
• execute：Hermes 可以执行允许的操作，同时仍须遵循 Hermes 自身的安全规则。
• request-approval：Hermes 准备操作，但不执行。MCP 调用方应使用 hermes_prepare，然后使用 hermes_approve；后者会打开交互式客户端表单，显示确切操作，并且仅在用户确认后执行。

策略防护是确定性的，且与语言无关：在 execute 模式下，除非明确将预设设为可信（require_approval_for 为空）或设置了 --yolo，否则桥接程序默认会切换到 request-approval，不受提示词措辞或语言影响。此外，每个有效的 MCP execute 请求都需要客户端交互确认，包括可信预设和 YOLO。桥接程序不会尝试根据关键词推断风险。

以下风险类别仅供参考：桥接程序会在提示词封装中标出其识别到的类别，帮助你和 Hermes 进行判断，但这些类别绝不会影响执行模式。（关键词匹配偏重英语，而且很容易绕过，因此不得将其用作安全控制。）

• publish_external
• send_message
• send_email
• delete
• payment
• git_push
• credential_change

YOLO 模式

默认关闭 YOLO 模式。

hermes-action run --yolo --mode execute "Do the task now."

YOLO 会绕过模式降级策略，但不会绕过 MCP 交互式确认屏障、Hermes Agent 自身的安全规则、提供方／工具的审批提示或平台限制。直接使用 CLI 仍是明确的可信本地逃生通道。

仅在调用方和环境可信时使用。

可信预设（直接执行）

默认情况下，每次 execute 都会降级为 request-approval——如果 Agent 可能在无人值守的情况下执行操作，这是恰当的默认设置。当你亲自请求执行某项操作，并希望跳过这道额外关卡时，可以定义一个可信预设：将其 require_approval_for 设为空列表。把它放在你的用户配置中，这样它只属于你，并且在每个项目中都可用：

# ~/.config/hermes-action/config.yaml   (user scope, merged before any project config)
presets:
  act:
    description: Direct execution of an action I explicitly asked for (trusted).
    require_approval_for: []

通过该预设运行操作——execute 会保持为 execute，无需降级，也无需 --yolo：

hermes-action run --preset act --mode execute "post the release note to #general"

确保安全：

• 可信预设会放宽模式降级策略。MCP 执行仍需交互式确认；直接使用 CLI 则依赖操作员和环境可信。
• 将其保存在你的用户配置中；它不会随公共软件包发布，分发的 SKILL.md 仍会对其他所有人保持谨慎。
• 仅对人类明确请求的操作使用可信预设。对于 Agent 可能自行触发的任何操作，保留保守的默认设置。

配置

hermes-action 按以下顺序加载配置：

CLI flags > project .hermes-action.yaml > user config > built-in defaults

用户配置路径：

~/.config/hermes-action/config.yaml

项目配置路径：

.hermes-action.yaml

示例：

runtime:
  adapter: hermes-cli
  command: hermes
  # Aggregate budget across all --context files, in bytes (default ~768 KiB).
  # Raising this above ~896 KiB switches large prompts to temp-file delivery.
  max_context_bytes: 786432
  # Optional overall per-run timeout in seconds. When unset, per-mode defaults
  # apply: 180s for plan/draft, 600s for execute/request-approval.
  # timeout_seconds: 600

defaults:
  mode: plan
  source: external-agent
  max_turns: 30
  preset: default

presets:
  default:
    description: No extra skills or toolsets. Uses the active Hermes profile.
    skills: []
    toolsets: []

  research:
    description: General research and synthesis.
    skills: []
    toolsets: [web, terminal, file]
    # Per-preset override: relax approvals for a trusted preset.
    # An empty list never downgrades execute to request-approval.
    # require_approval_for: []

  coding:
    description: Repository inspection and runtime validation.
    skills: [developer-assurance-and-validation, runtime-debugging]
    toolsets: [terminal, file]

policy:
  yolo: false
  # Global default; a preset's own require_approval_for takes precedence when set.
  require_approval_for:
    - publish_external
    - send_message
    - send_email
    - delete
    - payment
    - git_push
    - credential_change

限制、超时和大型上下文

桥接程序会构建一个提示封装（策略头部 + 你的请求 + 每个 <context> 块），并将其交给 Hermes。两项保护措施可确保其可靠运行：

• 聚合上下文预算（runtime.max_context_bytes，默认约为 768 KiB，另加每个文件固定的 250 KiB 上限）。超出上限时会快速失败，并给出可执行的提示——Context total N bytes exceeds the limit ... Split your handoff or raise runtime.max_context_bytes.——而不是出现令人费解的 E2BIG 启动进程崩溃。默认值会在操作系统的参数大小限制下留出余量。
• 大型上下文传递。 如果提高预算，且封装大小超过约 896 KiB，适配器会将其写入权限为 0600 的临时文件，并告知 Hermes 读取该文件（为本次调用注入一个 file 工具集）。这样可以绕过操作系统的参数限制。需要注意两点：这会增加一轮工具调用，而真正的上限将变为模型的上下文窗口——数 MB 的文件可能只能被部分读取。运行结束后会删除临时文件；只有桥接进程本身被不可捕获地终止时，文件才可能残留（通过 0600 权限和操作系统临时文件清理机制降低风险）。

每次运行都有超时限制（plan／draft 默认为 180 秒，execute／request-approval 默认为 600 秒）。可使用 --timeout <seconds> 为单次运行设置超时，或通过 runtime.timeout_seconds 全局设置。超时后，Hermes 子进程会先收到 SIGTERM，短暂宽限期后再收到 SIGKILL，结果会标记为超时。

hermes-action doctor 会打印生效的限制；hermes-action run --dry-run --json 会报告计算出的提示大小（promptBytes、promptChars），以及传递方式将使用 argv 还是 temp-file。

CLI 参考

hermes-action init [--file .hermes-action.yaml] [--force]
hermes-action run [options] "request"
hermes-action presets [--json]
hermes-action status [--json]
hermes-action mcp
hermes-action serve [--listen 127.0.0.1] [--port 8765]
hermes-action install <claude-code|codex|all|mcp> [options]
hermes-action uninstall <claude-code|codex|all|mcp> [options]
hermes-action doctor [--json] [--probe]

常见的 run 选项：

--mode <plan|draft|execute|request-approval>
--preset <name>
--context <path...>
--config <path>
--provider <name>
--model <name>
--max-turns <number>
--timeout <seconds>
--source <name>
--yolo
--dry-run
--json

原生 Agent 技能

无需手动粘贴指令和 MCP 代码片段，运行完整安装程序即可。它会安装开放标准技能，并通过各 Agent 自己的 CLI 注册本地 stdio MCP 服务：

hermes-action install all            # skills + global MCP for both agents
hermes-action doctor                 # verifies skills, registrations, and MCP handshake
hermes-action install claude-code --print     # preview, write nothing
hermes-action install codex --project-hint     # also add a marker block to AGENTS.md
hermes-action uninstall all

安装默认采用安全设置：使用稳定的绝对桥接路径，不依赖交互式 PATH，除非传入 --project-hint，否则绝不修改 CLAUDE.md / AGENTS.md，并且拒绝覆盖外部技能或自定义的 MCP 条目。重复运行不会产生额外影响。仅安装项目本地技能时使用 --project，预览操作时使用 --dry-run。

生成的技能见 examples/claude-code/SKILL.md。项目提示用法见 examples/claude-code/CLAUDE.md 和 examples/codex/AGENTS.md。

Codex 插件（单行安装）

Codex 用户可以通过插件同时安装委派技能和 MCP 服务：

codex plugin marketplace add TheBlueHouse75/hermes-action-bridge
codex plugin add hermes-action@hermes-action-bridge

这会在 Codex 中注册 hermes-action MCP 服务和 Hermes 委派技能。必须在本地安装 Hermes Agent — 该插件通过 npx 运行固定版本的 npm 包。

更快地启动 MCP： npx 每次启动服务时都会重新解析包。 原生安装程序会改为注册绝对路径的全局启动器。

MCP 配置

无需重新安装技能，即可为 Codex 和 Claude Code 注册全局 MCP 服务：

hermes-action install mcp

对于其他 JSON MCP 客户端，或 Claude Code 项目范围内的配置，直接写入或合并 .mcp.json，同时保留其他服务：

hermes-action install mcp --write

或者手动配置：

{
  "mcpServers": {
    "hermes-action": {
      "command": "hermes-action",
      "args": ["mcp"]
    }
  }
}

直接委派

你始终可以直接调用桥接程序，无需使用技能：

hermes-action run --mode plan "Ask Hermes what should happen next."

hermes-action run \
  --preset coding \
  --context ./codex-notes.md \
  "Use Hermes to validate this plan and identify missing runtime checks."

MCP 工具

运行：

hermes-action mcp

提供的工具：

• hermes_run：将请求委派给 Hermes。可选覆盖项：mode、preset、contextFiles、yolo、dryRun，以及可在简单任务中以成本换取速度的 model、provider、maxTurns、timeoutSeconds。任何实际生效的 execute 请求都会先打开交互式确认表单。
• hermes_plan：hermes_run 的快捷方式，等同于设置 mode=plan。
• hermes_capabilities：报告已配置的预设、技能、工具集、运行时和策略，不会虚构实时集成。
• hermes_presets：列出已配置的预设。
• hermes_status：检查已配置的 Hermes 运行时命令。
• hermes_submit、hermes_job_status、hermes_result、hermes_cancel： 管理有界的进程内异步作业。
• hermes_prepare、hermes_approve、hermes_reject：创建并使用短时有效的一次性批准。hermes_approve 会在执行前请求 MCP 客户端进行交互式确认。

MCP 接口会将请求委派给 Hermes，而不是镜像 Hermes 的每个工具。 作业和批准有意设为进程本地：重启 MCP 服务会清除它们。审计事件会以仅所有者可访问的 JSONL 元数据形式写入 $XDG_STATE_HOME/hermes-action/audit.jsonl（或 ~/.local/state/hermes-action/audit.jsonl），不包含提示词、上下文、令牌或完整结果内容。

通过 Tailscale 使用远程 MCP

HTTP 传输默认选择退出，且仅监听回环地址：

hermes-action serve --listen 127.0.0.1 --port 8765

建议在该回环端点前配置 Tailscale Serve。转发的 *.ts.net 请求仍需 Bearer 令牌，因此启动回环服务器时请使用 --token-env：

export HERMES_ACTION_HTTP_TOKEN="<at-least-32-random-bytes>"
hermes-action serve \
  --listen 127.0.0.1 \
  --port 8765 \
  --token-env HERMES_ACTION_HTTP_TOKEN

如需直接监听 tailnet，桥接程序仅接受明确指定的 Tailscale IPv4 地址，并要求使用相同的 Bearer 令牌设置：

hermes-action serve \
  --listen 100.64.0.10 \
  --port 8765 \
  --allow-tailnet \
  --token-env HERMES_ACTION_HTTP_TOKEN

令牌不会被接受为 CLI 参数，也不会存储在桥接程序配置中。公共地址、通配符地址和非 Tailscale 地址均会被拒绝。

开发

npm install
npm run build
npm run test
npm run check

功能测试会使用伪造的 Hermes 二进制文件验证命令构造、提示词封装、风险策略和 YOLO 行为，不会消耗大模型额度。

文档

• 架构：模块图、配置优先级、模式、策略和 MCP 设计。
• 功能测试：自动化测试和实时冒烟测试流程。
• 贡献指南：本地设置、开发规则和发布检查清单。
• 更新日志：发布历史。
• 安全策略：如何报告漏洞。

安全模型

直接执行 CLI 假定操作人员可信且受到监督。MCP 执行还多了一道由协议强制执行的关卡：每个有效的 execute 请求都会通过 MCP 表单征询向客户端请求确认，显示准确的操作和元数据，并且仅当响应为 accept 且 confirm=true 时才会运行。

对于有副作用的操作，建议使用可测试的两阶段流程：hermes_prepare 返回本地的无工具摘要和不透明的批准 ID，hermes_approve 则打开交互式确认，随后仅执行一次未更改的请求。对于不受支持的客户端、CI 作业、Shell 脚本、取消、超时和拒绝，系统都会安全失败，不会执行操作。交互式 MCP 客户端不可用时，请使用计划、草稿、试运行或直接 CLI；不要将直接 CLI 描述为提供独立的人工批准关卡。

此关卡假定 MCP 客户端符合规范且可信。MCP 规范要求声明支持征询的客户端提供 UI、标明请求服务器、提供拒绝/取消选项，并允许用户查看响应。恶意客户端或配置为自动作答的征询钩子可以伪造 accept 和 confirm=true；不要将此桥接暴露给不可信的 MCP 客户端。在这种部署模式下，此桥接不声称具备人工审核边界。

此桥接自身的防护只是第二道防线：默认情况下，除非预设可信（require_approval_for 为空）或设置了 --yolo，否则 execute 会降级为 request-approval。此桥接绝不会自行注入 --yolo 或绕过标记。

• **不要自动回应 MCP 征询，也不要安装会接受执行表单的征询钩子。**这样做会有意移除人工审核边界。
• 不要将 hermes-action run（execute/yolo）加入允许列表。命令模式允许列表无法区分安全的计划与会产生副作用的执行操作。
• 不要将机密放入 .hermes-action.yaml。请将提供方凭据保存在 Hermes Agent、操作系统钥匙串或平台的安全存储中。
• 将 --yolo 视为可信本地环境下的应急选项，而非常规默认设置。

作者的其他作品

由 Cyril Guilleminot 开发，他也制作离线优先的语音工具：

• Weesper Neon Flow — 以 3 倍打字速度将语音输入到任何应用，完全离线运行（macOS 和 Windows）。
• Weesper Transcribe — macOS App Store 上的离线转录应用。

许可证

MIT