内容
<div align="center">
<img src="assets/github-hero.png" alt="赫尔墨斯卫星 - 远程执行，验证结果" width="100%" />
<h1>赫尔墨斯卫星</h1>
**您的代理已完成。但它是否真正完成了工作，还是只是说它完成了？**
通过身份验证的MCP进行远程赫尔墨斯执行和卫星验证。
[](LICENSE)
[](https://modelcontextprotocol.io)
[](#)
[](#contributing)
</div>
---
## 问题
您将一个长期任务交给一个编码代理，然后离开。二十分钟后，它报告`完成`。
现在怎么办？您有一段充满自信的文字，却无法确定它是否真实。所以您做了委托的全部意义被抹去的事情：您坐下来阅读它写的每一行，因为**代理对其自身工作的总结是一种声明，而不是证据**。信任自己“完成”的循环会交付您从未看到、从未理解的代码，运行得越快，差距就越大。
通常的解决方法只会使问题更加严重。看着它在前台运行，你又回到了 babysitting。盲目信任它，你是在靠感觉办事。在执行者身上添加一个审查者，与执行者共享上下文和机器，你便雇佣了第二个乐观主义者来给第一个乐观主义者评分。
## 洞察
> **检查工作的人必须与做工作的人分开 - 而最干净的分开方式是两者之间加一个网络。**
将执行者放在自己的机器上。任何支持MCP的客户端都可以调度到它，然后拉回**记录**，将结果分解为原子声明，并在信任任何字之前根据实际证据对每个声明进行预言。信任边界变成网络边界，您可以在其上放置独立的验证者。
这就是赫尔墨斯卫星：**循环工程与验证者代理模式的融合，通过MCP分布式。**
## 它做什么
将专用主机（如Mac mini、Linux盒、VM、homelab服务器、CI运行器）指向赫尔墨斯代理，通过身份验证的MCP桥接器公开它，任何机器上的任何客户端都可以获得具有验证循环的共享远程执行器。
<div align="center">
<img src="assets/dispatch-verify-loop.png" alt="调度验证循环：客户端通过身份验证的MCP向赫尔墨斯主机提交任务，轮询或运行一次性监视器，拉取记录证据，将原子声明分解并在客户端进行预言，然后通过hermes_respond重新循环" width="100%" />
</div>
执行者与验证者真正分离 - 足够分离以在两侧运行**不同的模型系列**。分布是规模轴；预言是信任轴；MCP使两者在不崩溃的情况下移动。
## 为什么它与众不同
野生中的每个循环工具都是单盒的：一个harness、一个机器、一个会话，通过本地套接字验证自己的工作。赫尔墨斯卫星是第一个将验证者置于网络中与执行者分开的工具。
| | 普通代理循环 | 赫尔墨斯卫星 |
|---|---|---|
| **完成** | 文本：“完成，看起来不错” | 原子声明，每个都经过证据验证 |
| **审查者** | 相同会话，相同盲点 | 独立客户端，可以是不同的模型系列 |
| **信任边界** | 进程边界（或无） | 网络边界，您可以在其上放置验证者 |
| **信心** | 感觉 | 通过证据层（T0→T3）编码 |
| **成本** | 隐形，通常无法核对 $0 | `TaskCostSnapshot` 显示；MoA 标记为未核对 |
| **存在离开时** | 盯着终端，或盲飞 | 零令牌监视器仅在状态更改时通知您 |
## 保证模型：同事，而不是黑盒
为您放手 - 从不沉默。交出任务，继续工作。后台监视器（`skills/hermes-dispatch/tools/hermes_watch.py`）在**纯确定性代码，零令牌，零LLM调用**中轮询，并且仅在值得您关注的状态更改时中断：
- **`完成`** - 终端状态，结果已拉取并准备验证。
- **`卡住`** - 超过 600 秒的上限，可能超时。
- **`无响应`** - 五次连续检查失败（持续中断，而不是单个中继间隙），随后在联系恢复时出现 **`RECOVERED`** 行。
- **稀疏心跳** - 安静的“还活着，不需要操作”，以便沉默不会被视为成功。
设计规则，简单来说：**存在 = 免费代码，判断 = 模型，仅在结果和决策点。** 监视循环的运行是解决错误的问题。任务消失了；监视器在转换时通知您。
## 快速入门
**在赫尔墨斯主机**上 - 运行桥接器（本地 Python FastMCP 流式 HTTP）：
```bash
# 绑定到私有 tailnet / VPN 地址，绝不绑定到公共接口
export HERMES_ASYNC_BRIDGE_TOKEN="$(openssl rand -hex 32)"
python3 apps/hermes-async-bridge/hermes_async_bridge.py
```
桥接器拒绝盲目 `0.0.0.0` HTTP 绑定，除非在 stdio/test 模式下，否则需要 bearer token，并且在 `$HERMES_HOME/async_bridge.db` 中保留任务状态。
**在任何客户端机器**上 - 通过 URL 将 MCP 客户端指向它，而不是本地命令。先导出 `HERMES_MCP_TOKEN`，然后为您的客户端使用一行命令；对于通过文件配置的客户端，YAML 仍然适用：
```bash
export HERMES_MCP_TOKEN="<bridge-token>"
claude mcp add --transport http hermes-async http://<bridge-host>:8081/mcp --header "Authorization: Bearer ${HERMES_MCP_TOKEN}"
codex mcp add hermes-async --url http://<bridge-host>:8081/mcp --bearer-token-env-var HERMES_MCP_TOKEN
```
```yml
mcp_servers:
hermes_async:
url: "http://<bridge-host>:8081/mcp" # 您的 Tailscale / LAN IP
headers:
Authorization: "Bearer ${HERMES_MCP_TOKEN}"
timeout: 180
connect_timeout: 60
```
重启客户端以运行 MCP 发现，然后从**单独的 tailnet 节点**验证身份（通常桥接主机无法访问其自己的 Tailscale IP）：
```
no-token MCP initialize → HTTP 401
bearer MCP initialize → HTTP 200
```
当 `hermes_*` 工具与您的客户端前缀一起出现（Claude Code 中的 `mcp__hermes-async__hermes_submit`，赫尔墨斯代理中的 `mcp_hermes_async_*`）时，您就上线了。
## 验证循环
`hermes-dispatch` 技能是运营核心。直接从此仓库将其安装到任何支持技能的代理（Claude Code、Codex、Cursor、OpenCode 等）：
```bash
npx skills add aojdevstudio/hermes-satellite
```
您是**调度器和卫星验证器，而不是工作器**：
1. **`hermes_submit`** 一个带有 `## Acceptance` 块的作用域提示 - 每个项目符号一个可测试的要求。这些在验证时成为确定性声明；如果没有它们，验证器就会进行猜测。
2. **轮询** 合同（30 秒初始，120 秒间隔，600 秒硬上限）- 或启动监视器并继续工作。
3. **`hermes_transcript`** 获取 T2 证据。结果段落是一个声明；记录是证据。
4. **`hermes_decompose`** 将记录分解为 `AtomicClaim[]`。
5. **预言每个声明** 只读对抗工具证据 - 绝不基于文本。
6. **`hermes_respond`** 带有更正和重新循环，直到验证完成或达到 `max_loops`。
信心不是一种感觉 - 它通过证据层面的强度编码：
| 层级 | 证据 | 信心上限 |
|------|----------|--------------------|
| **T0** | 仅结果文本 | `PARTIAL` |
| **T1** | 会话摘要 | `VERIFIED` |
| **T2 / T3** | 完整记录 / 强制输出 | `PERFECT`-eligible |
任何写入文件或执行代码的任务**需要 T2**。如果验证通过结果段落，则验证通过的等级最多为 `PARTIAL`。成本也是合同的一部分：`hermes_result` 和 `hermes_task_cost` 显示实际花费，并且混合代理行具有未核对的本地成本，报告为 **unknown, never a free $0**.
## 从主机监视桥接器：`hst`
`scripts/hst.ts` 是异步桥接器的主机操作视图。它是一个单文件 Bun CLI，基于 `~/.hermes/async_bridge.db`，以只读模式打开，以便 WAL-mode SQLite 保持快乐，然后使用 `PRAGMA query_only=ON` 锁定，以便 CLI 保持只读。将它符号链接到您的 PATH 中作为 `hst`（和/或 `hermes-satellite`），并在您调度的位置安装配套技能：
```bash
npx skills add aojdevstudio/hermes-satellite
```
主机上的前五分钟：
```text
hst health 服务、端口和最近的活动
hst tasks -n 10 最近的队列，包含状态、调用者和概要
hst task <id-prefix> 完整的任务：运行、成本、时间线、结果
hst costs -n 10 每个任务的成本快照，包含调用者和实际成本
hst watch [id-prefix] 实时事件流；在终端状态时退出，并附带 ID
```
其他有用的视图：`hst events [-n N] [id-prefix]`、`hst transcript <id-prefix>` 和 `hst logs [-f]`。`--json` 适用于 `tasks`、`task`、`events` 和 `costs`；JSON 模式从不调用 gist 提供程序。如果桥接数据库无法打开，`hst` 退出并显示一行：`hst: cannot open bridge db`。
实际主机输出，使用 `NO_COLOR=1 bun scripts/hst.ts tasks -n 4` 生成：
```text
HERMES SATELLITE · tasks · ~/.hermes/async_bridge.db
┌──────────┬─────────────┬─────────┬───────────────────────┬─────────────┬────────┬────────────────────────────────────┐
│ id │ status │ profile │ caller │ age │ took │ gist │
├──────────┼─────────────┼─────────┼───────────────────────┼─────────────┼────────┼────────────────────────────────────┤
│ 7cb13ab6 │ ✓ completed │ default │ obi-orinsync-db-fix │ 12h 50m ago │ 7m 45s │ Fix OrinSync's unreachable Supaba… │
│ 670a4da6 │ ✓ completed │ default │ obi-micstay-issue17 │ 17h 34m ago │ 8m 55s │ Build MicStay Settings window and… │
│ c4a87ad6 │ ✓ completed │ default │ followup │ 17h 44m ago │ 9m 52s │ Finish and land output-pin implem… │
│ 6e4e4653 │ ✓ completed │ default │ obi-section-driver-65 │ 17h 46m ago │ 2m 3s │ Classify hymns with semantic reas… │
└──────────┴─────────────┴─────────┴───────────────────────┴─────────────┴────────┴────────────────────────────────────┘
✓ completed 111 · ✗ failed 14
```
两个值得了解的行为：
**Gists，而不是提示转储。** `hst tasks` 显示每个任务作为一个简短的 LLM 生成的概要，不超过八个单词。它在设置了 `GROQ_API_KEY` 环境变量或 `~/.hermes/.env` 时使用 Groq `llama-3.1-8b-instant`，否则使用 OpenRouter `meta-llama/llama-3.3-70b-instruct:free`，当设置了 `OPENROUTER_API_KEY` 时；`HST_GIST_MODEL` 会覆盖模型。摘要缓存在 `~/.hermes/cache/hst_summaries.json` 中，每个新任务都有一个批处理调用。没有密钥、超时、网络失败或 OpenRouter 429，都会静默回退到原始提示；稍后运行的自愈功能会在提供程序工作时自我修复。OpenRouter `:free` 端点需要帐户隐私设置允许它们。
**诚实成本渲染。** 与验证循环相同的规则：订阅计费会话上的 `$0` 渲染为 `$0 (subscription)`；任何其他 `$0` 渲染为 `unknown` - 从不免费。这适用于 `hst costs` 和循环成本线在 `hst task` 中。
| 变量 | 用途 |
|----------|----------|
| `HERMES_ASYNC_BRIDGE_DB` | 覆盖桥接器数据库路径；默认为 `~/.hermes/async_bridge.db`。 |
| `HERMES_HOME` | 覆盖 Hermes 主目录；控制默认数据库、`.env` 和 gist 缓存路径。 |
| `GROQ_API_KEY` | 首选 gist 提供程序密钥，从 env 或 `~/.hermes/.env`。 |
| `OPENROUTER_API_KEY` | 备用 gist 提供程序密钥，从 env 或 `~/.hermes/.env`。 |
| `HST_GIST_MODEL` | 覆盖选定的 gist 模型。 |
| `NO_COLOR` | 为文档、日志和脚本禁用 ANSI 颜色。 |
## 存储库中有什么
| 路径 | 它是什么 |
|------|-----------|
| `apps/hermes-async-bridge/` | Hermes 代理的原生 Python 流式 HTTP MCP 桥接器 |
| `apps/verifier/hermes/` | TypeScript 客户端 - 调度、轮询、记录、分解 |
| `skills/hermes-dispatch/` | 调度 + 卫星验证技能，以及零令牌监视器 |
| `scripts/hst.ts` | `hst` - 只读主机侧可观察性 CLI：任务、成本、事件、记录、健康 |
| `hermes-mcp.md` | 桥接器架构和操作状态 |
| `hermes-polling.md` | 规范的客户端轮询合约 |
| `specs/hermes-satellite-verify.md` | 实现计划和证据 / 成本模型 |
| `ROADMAP.md` | 从桥接器基础到完全验证循环的分阶段计划 |
<div align="center">
<img src="assets/hermes-satellite.png" alt="将循环握在手中" width="88%" />
</div>
## 故事
这始于非工程师从基础开始拆解 bash `while` 循环，而不是借用别人的循环 - 试图实际理解循环**是什么**，然后将代理编织到其中。那条路径直接遇到了 2026 年的两个最响亮的想法：**循环工程**（围绕代理设计系统，而不是逐一提示代理）和**验证者代理模式**（将工作分解为原子声明并证明每个声明，因为自我评分的代理共享其自身的盲点）。
我实现的每个实现都生活在一个盒子里。存储库的诞生：把一个网络放在执行者和验证者之间，选择在循环中的位置 - 它成为调度时的旋钮。
## 致谢和血统
这里的思考并不仅限于我。 Hermes Satellite 是多个人想法的汇集，他们都应得到认可：
- **[AI Jason](https://www.youtube.com/@AIJasonZ)（Jason Zhou）** 用于循环工程、内外循环拆分和通过共享工件系统进行循环复合。他的 [loop-engineer-template](https://github.com/JayZeeDesign/loop-engineer-template) 是我进行大量具体工作的起点。
- **[Peter Steinberger](https://steipete.me)** 用于“您应该设计让您的代理循环的提示。” 他的 [agent-scripts](https://github.com/steipete/agent-scripts) 协调器和技能是我不断回归的形状。
- **[IndyDevDan](https://www.youtube.com/@indydevdan)（Dan Disler）** 用于验证者代理模式：将工作分解为原子声明并证明每个声明。该存储库从他的 [the-verifier-agent](https://github.com/disler/the-verifier-agent) 发展而来，而卫星是将该模式推到网络上的产物。
- **[Matt Pocock](https://www.aihero.dev)` 的 `/teach` 技能帮助我实际弄清楚我如何构建循环，而不是复制别人的。
构建于：
- **[Hermes Agent](https://github.com/NousResearch/hermes-agent) 由 Nous Research 构建的主机端自我改进代理。 卫星调度到它并验证它做了什么。
- **[FastMCP](https://github.com/jlowin/fastmcp) ，Pythonic MCP 框架，认证桥接器在此基础上构建。
## 路线图
- ✅ 原生认证 HTTP 桥接器、十个核心 `hermes_*` 工具、轮询合约、零令牌监视器
- 🔜 带有真实卫星验证器客户端的端到端回调路径
- 🔜 `hermes_progress` - 实时子步骤可见性（“完成切片 1/3” 而不仅仅是状态转换）
- 🔜 基于令牌的主题映射（超出调用者字符串标识符）
- ✅ `hst` - 只读主机侧 CLI，用于任务队列、成本、事件、记录和健康
- 🔜 带有 `hst` CLI 之外的操作 UI - 回调和验证状态在一个视图中
查看 [`ROADMAP.md`](ROADMAP.md) 了解完整的分阶段计划。公共操作指南位于 [`docs/docs/safety/`](docs/docs/safety/) 和 [`docs/docs/operations/`](docs/docs/operations/) 中；在提交文档更改之前运行 `pnpm docs:validate`。
