内容
<p align="center">
<img src="https://raw.githubusercontent.com/TheBlueHouse75/hermes-action-bridge/main/assets/logo.png" alt="Hermes Action Bridge" width="128" height="128" />
</p>
# Hermes 行动桥
[](https://www.npmjs.com/package/hermes-action-bridge) [](https://github.com/TheBlueHouse75/hermes-action-bridge/actions/workflows/ci.yml)
一个可配置的桥梁，允许外部代理将现实世界的行动委托给 [Hermes 代理](https://hermes-agent.nousresearch.com/docs) ，而无需重新实现 Hermes 技能、工具、平台集成、浏览器自动化、定时作业或消息流。
从 Claude Code、Codex、Cursor、CI 作业、shell 脚本或任何支持 MCP 的客户端使用它。
```text
外部代理 -> hermes-action -> Hermes 代理 -> 技能/工具/集成
```
## 为什么存在
编码代理擅长理解存储库。它们不应复制您的自动化堆栈。
如果代理需要在其本地编码会话之外执行某些操作 - 研究、安排作业、打开浏览器工作流、发送消息、准备社交帖子、使用 Hermes 技能或与消息网关协调 - 它可以通过此桥梁将该请求委托给 Hermes。
## 功能
- 用于一次性委托的通用 `hermes-action run` 命令。
- 用于技能、工具集、提供商/模型、配置文件、源和最大回合的 configurable 预设。
- 安全策略，可以将风险较高的 `execute` 请求降级为 `request-approval`，并具有可选的每个预设的覆盖。
- 显式 `--yolo` 模式，供故意绕过桥梁级策略的用户使用。
- 上下文文件注入，具有每个文件的上限和可配置的聚合预算（如果超过预算，则会出现清晰的错误，而不是神秘的 `E2BIG` 错误）。
- 自动大上下文交付：通过安全临时文件将超大提示交给 Hermes，而不是溢出命令行。
- 每个运行的超时（可配置，具有每个模式的默认值），始终会回收 Hermes 子进程。
- 用于调试确切 Hermes 命令、提示和计算提示大小的 dry-run 模式。
- 最小的 MCP 服务器，暴露委托工具：`hermes_run`、`hermes_plan`、`hermes_presets` 和 `hermes_status`。
- 没有特定于项目的假设。所有行为均通过 YAML 和 CLI 标志配置。
## 要求
- Node.js 20 或更高版本。
- Hermes 代理已安装并可用作 `hermes`，或使用自定义命令路径配置。
检查 Hermes：
```bash
hermes --version
```
## 安装
从 npm 安装：
```bash
npm install -g hermes-action-bridge
```
然后检查它是否有效：
```bash
hermes-action --version
hermes-action doctor
```
<details>
<summary>从源代码（用于开发）</summary>
```bash
git clone https://github.com/TheBlueHouse75/hermes-action-bridge.git
cd hermes-action-bridge
npm install
npm run build
npm link
```
</details>
## 快速入门
在您的项目中创建一个配置文件：
```bash
hermes-action init
```
向 Hermes 请求一个安全计划：
```bash
hermes-action run --mode plan "从此存储库上下文中找到下一个最佳操作。"
```
委托一个上下文文件：
```bash
hermes-action run \
--preset research \
--context ./notes.md \
"分析此内容并返回下一个具体操作。"
```
运行 dry-run 以检查将发送到 Hermes 的内容：
```bash
hermes-action run --dry-run --json "总结这个项目。"
```
## 执行模式
- `plan`：Hermes 只返回计划。无副作用。
- `draft`：Hermes 只生成工件。无外部副作用。
- `execute`：Hermes 可以执行允许的操作，同时仍遵循 Hermes 自己的安全规则。
- `request-approval`：Hermes 准备操作并在不可逆转的外部影响之前请求人类批准。
如果桥梁在 `execute` 模式下检测到高风险请求，它可以自动切换到 `request-approval`，除非启用了 YOLO。
风险类别：
- `publish_external`
- `send_message`
- `send_email`
- `delete`
- `payment`
- `git_push`
- `credential_change`
## YOLO 模式
YOLO 模式默认关闭。
```bash
hermes-action run --yolo --mode execute "立即执行此任务。"
```
YOLO 仅绕过桥梁策略。它不删除 Hermes 代理的安全规则、提供商/工具批准提示或平台约束。
仅在调用者和环境受信任时使用它。
## 配置
`hermes-action` 按此顺序加载配置：
```text
CLI 标志 > 项目 .hermes-action.yaml > 用户配置 > 内置默认值
```
用户配置文件路径：
```text
~/.config/hermes-action/config.yaml
```
项目配置文件路径：
```text
.hermes-action.yaml
```
示例：
```yaml
runtime:
adapter: hermes-cli
command: hermes
# 所有 --context 文件的聚合预算（字节）（默认为 ~768 KiB）。
# 将此值提高到 ~896 KiB 以上会将大提示切换到临时文件交付。
max_context_bytes: 786432
# 可选的整体每运行超时（秒）。如果未设置，则应用每个模式的默认值：
# 计划/草稿为 180s，执行/请求批准为 600s。
# timeout_seconds: 600
defaults:
mode: plan
source: external-agent
max_turns: 30
preset: default
presets:
default:
description: 没有额外的技能或工具集。使用活动的 Hermes 配置文件。
skills: []
toolsets: []
research:
description: 一般研究和综合。
skills: []
toolsets: [web, terminal, file]
# 预设特定的覆盖：为受信任的预设放松审批。
# 空列表永远不会将 execute 降级为 request-approval。
# require_approval_for: []
coding:
description: 存储库检查和运行时验证。
skills: [developer-assurance-and-validation, runtime-debugging]
toolsets: [terminal, file]
policy:
yolo: false
# 全局默认值；预设的 require_approval_for 在设置时具有更高的优先级。
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 上限）。超出预算会快速失败，并带有可行的消息 - `上下文总数 N 字节超过限制 ... 将您的交接分开或提高 runtime.max_context_bytes。` - 而不是神秘的 `E2BIG` 进程崩溃。默认情况下，它在操作系统的参数大小限制下留有余地。
- **大上下文交付。** 如果您提高预算并且信封增长超过 ~896 KiB，适配器会将其写入 `0600` 临时文件，并告诉 Hermes 读取该文件（为调用注入 `file` 工具集）。这绕过了操作系统的参数限制。两个注意事项：它添加了一个工具调用回合，并且实际上限成为模型的上下文窗口 - 可能会部分读取多兆字节文件。临时文件在运行后删除；唯一无法捕获的进程终止方式是桥梁进程本身（通过 `0600` 模式和操作系统的临时文件回收器缓解）。
每次运行都受超时限制（默认为 `plan`/`draft` 180s，`execute`/`request-approval` 600s）。使用 `--timeout <seconds>` 或全局 `runtime.timeout_seconds` 覆盖每个运行的超时。如果超时，Hermes 子进程会收到 `SIGTERM`，然后在短暂的宽限期后收到 `SIGKILL`，结果被标记为超时。
`hermes-action doctor` 打印有效限制，`hermes-action run --dry-run --json` 报告计算的提示大小（`promptBytes`、`promptChars`）以及交付是否使用 `argv` 或临时文件。
## CLI 参考
```bash
hermes-action init [--file .hermes-action.yaml] [--force]
hermes-action run [options] "请求"
hermes-action presets [--json]
hermes-action status [--json]
hermes-action mcp
hermes-action install <claude-code|codex|all|mcp> [options]
hermes-action uninstall <claude-code|codex|all|mcp> [options]
hermes-action doctor [--json] [--probe]
```
常见的 `run` 选项：
```bash
--mode <plan|draft|execute|request-approval>
--preset <name>
--context <path...>
--config <path>
--profile <name>
--provider <name>
--model <name>
--max-turns <number>
--timeout <seconds>
--source <name>
--yolo
--dry-run
--json
```
## 原生代理技能
与其手动粘贴指令，不如安装原生技能，以便 Claude Code 和 Codex 知道何时委托给 Hermes。该技能与两种代理使用的 `SKILL.md` 相同；CLI 保留确定性执行层。
```bash
hermes-action doctor # 检查 Node、Hermes、代理和已安装的技能
hermes-action install all # ~/.claude/skills 和 ~/.codex/skills
hermes-action install claude-code --print # 预览，不写入任何内容
hermes-action install codex --project-hint # 还会在 AGENTS.md 中添加一个标记块
hermes-action uninstall all
```
安装行为默认是安全的：除非您传递 `--project-hint`，否则它不会修改 `CLAUDE.md` / `AGENTS.md`，拒绝覆盖它未生成的任何文件，并且是幂等的。使用 `--project` 表示项目本地技能，使用 `--dry-run` 预览操作。
生成的技能显示在 [`examples/claude-code/SKILL.md`](examples/claude-code/SKILL.md) 中。项目提示用法在 [`examples/claude-code/CLAUDE.md`](examples/claude-code/CLAUDE.md) 和 [`examples/codex/AGENTS.md`](examples/codex/AGENTS.md) 中有文档记录。
## Codex 插件（单行安装）
Codex 用户可以作为插件安装委托技能和 MCP 服务器：
```bash
codex plugin marketplace add TheBlueHouse75/hermes-action-bridge
codex plugin add hermes-action@hermes-action-bridge
```
这在 Codex 中注册了 `hermes-action` MCP 服务器和 Hermes 委托技能。Hermes 代理必须本地安装 - 插件运行 `npx -y hermes-action-bridge mcp`。
## MCP 配置
打印客户端的配置文件片段（Claude Code / Cursor / VS Code 使用 JSON；Codex 使用 TOML）：
```bash
hermes-action install mcp
```
对于 Claude Code，直接编写或合并项目 `.mcp.json`：
```bash
hermes-action install mcp --write
```
或手动配置：
```json
{
"mcpServers": {
"hermes-action": {
"command": "hermes-action",
"args": ["mcp"]
}
}
}
```
## 直接委托
您可以始终直接调用桥梁，而无需技能：
```bash
hermes-action run --mode plan "询问 Hermes 接下来应该发生什么。"
hermes-action run \
--preset coding \
--context ./codex-notes.md \
"使用 Hermes 验证此计划并识别缺少的运行时检查。"
```
## MCP 工具
运行：
```bash
hermes-action mcp
```
公开的工具：
- `hermes_run`：将请求委托给 Hermes。
- `hermes_plan`：`hermes_run` 的快捷方式，模式为 `plan`。
- `hermes_presets`：列出配置的预设。
- `hermes_status`：检查配置的 Hermes 运行时命令。
MCP 接口故意很小。桥梁委托给 Hermes，而不是一对一地公开每个 Hermes 工具。
## 开发
```bash
npm install
npm run build
npm run test
npm run check
```
功能测试使用假的 Hermes 二进制文件来验证命令构造、提示包装、风险策略和 YOLO 行为，而无需花费 LLM 积分。
## 文档
- [架构](docs/ARCHITECTURE.md)：模块映射、配置优先级、模式、策略和 MCP 设计。
- [功能测试](docs/FUNCTIONAL-TESTS.md)：自动化测试和实时烟雾测试程序。
- [贡献](CONTRIBUTING.md)：本地设置、开发规则和发布检查清单。
- [变更日志](CHANGELOG.md)：发布历史。
- [安全策略](SECURITY.md)：如何报告漏洞。
## 安全注意事项
- 不要在 `.hermes-action.yaml` 中放置秘密。
- 将提供商凭据保存在 Hermes 代理、您的操作系统密钥链或相关平台的安全存储中。
- 对于公开发布、外部电子邮件/消息、删除、付款、凭据更改和 git 推送，请使用 `request-approval`。
- 将 `--yolo` 视为受信任的本地模式逃生舱，而不是默认模式。
## 作者的其他作品
由 Cyril Guilleminot 构建，他还制作了离线优先的语音工具：
- [Weesper Neon Flow](https://weesperneonflow.ai) - 在任何应用程序中以 3 倍的打字速度输入文本，完全离线（macOS 和 Windows）。
- [Weesper Transcribe](https://apps.apple.com/app/id6778776535) - macOS App Store 上的离线转录。
## 许可证
MIT
