yaoyao/docs/runner.md

Hermes 执行节点

Runner 在运行 Hermes 的电脑上主动连接夭夭服务。用于 Web 位于 Docker、另一台电脑或远程服务器时，将 Bot 会话和本轮组队工具交给 Hermes 所在电脑执行。Runner 源码、构建入口和管理页面均位于 hermes-yaoyao。

这是执行传输层。当前接入的 Hermes 仍使用它原有的工具和权限，Runner 本身不提供 VM 隔离。隔离电脑、受控 Worker、共享桌面和资源租约属于后续实现范围。

启用

1. 管理员打开设置 → Hermes 连接 → 执行节点。
2. 选择接管的 Bot 来源、允许的 Profile、能从执行电脑访问的夭夭地址，以及 Runner 本机 Hermes 的回环地址。
3. 注册后下载 runner.json。节点凭据只在注册响应中返回；列表和刷新不会返回凭据。
4. 将配置放到执行电脑，执行 chmod 600 /完整路径/runner.json。
5. 在项目目录执行 npm run build，然后执行 npm run runner -- --config /完整路径/runner.json。

也可执行 npm run runner:build，将 .runner-build/runner.mjs 复制到执行电脑，以 Node.js 24 或更高版本运行：

node runner.mjs --config /完整路径/runner.json

macOS App 的打包构建也包含该入口；当前 App 仍自动托管本地 Web 与缺失的 Hermes 服务。Runner 的原生配置导入与自动托管入口尚待接入，不能把“已打包入口”视作“已自动运行 Runner”。

配置文件至少包括以下字段。token 由注册操作生成，不需要填写模型密钥。

{
  "protocol": 1,
  "serverURL": "https://yaoyao.example.com",
  "runnerId": "注册响应中的节点 UUID",
  "token": "注册后下载的节点凭据",
  "hermesURL": "http://127.0.0.1:9119",
  "allowedProfiles": ["default"],
  "artifactRoots": []
}

若 Hermes 启用了账号鉴权，可在本机私有配置添加 hermesCredentials 对象，包含 username 和 password；它们留在执行电脑，控制面不接收 Hermes 密码。回环授权则由现有 UpstreamServiceSession 自动协商。远程明文 HTTP 必须明确设置 allowInsecureLan: true。

每个来源同时只允许一个启用的 Runner。已有配对 Web 来源应在目的 Web 服务内注册自己的 Runner。停用会立即关闭控制面的工具授权，执行电脑在连接恢复或轮询时收到拒绝。配置丢失时停用并重新注册；旧配置不能恢复已撤销的节点。

协议与执行边界

• 浏览器管理接口使用原有管理员登录和 CSRF。机器接口使用独立 Bearer 凭据、Runner 实例 UUID、协议版本与连接代次；拒绝带 Origin 的请求。
• Runner 以 HTTP 长轮询领取有期限的命令，通过独立请求提交结果、会话事件和工具调用。慢操作不会阻塞后续关闭命令。
• 控制面重启、Runner 更换、断线重连都会更换连接代次；旧结果、旧实例和旧工具授权不能接管新执行。
• 命令执行前再次向控制面核对授权和期限。账号权限变化会使旧轮次失效。一个会话被撤权只关闭自己的通道和工具。
• 本机 SQLite 保存命令指纹和执行回执。重复命令复用回执；未完成的历史命令视为结果不确定，禁止自动重放。大响应一小时后压缩为禁止重放的记录。
• 组队工具只在 Hermes 本机建立回环租约，远端不开放原有回环接口。模型获得的是当轮不透明工具 ID；账号、来源、会话和调用身份由服务端绑定。
• Gateway RPC 使用固定允许列表；会话操作必须属于自己的通道。HTTP 仅允许必要的只读查询。文件导出要求真实路径位于 artifactRoots，留空拒绝导出。
• 单个只读结果目前最多 8 MiB；大型产物的分块传输仍待实现。待传命令有数量和总字节限制。
• 断线后的在途操作可能结果不确定。系统沿用原会话核对，不在另一个节点重放原任务。已完成会话切换节点后带入近期文字记录；历史附件路径需要重新核实。

验收

tests/server/runner.test.ts 使用独立 HTTP/WebSocket 服务验证实际传输、权限交集、调用去重、未完成回执、连接代次、断线重连、取消竞态和会话隔离。

tests/e2e/team-tools.spec.ts 覆盖注册、配置下载、列表不返回凭据、停用以及窄屏布局。

真实 Hermes 协议验收沿用 docs/bot-agent-teams.md 的隔离 fixture。添加 HERMES_TEAM_RUNNER=1 后，原生工具创建成员、组队、分派、复核、完成目标、回传原会话和双管理员并发都经过 Runner。模型决策由确定脚本替代，不代表真实模型自主决策质量，也不代表 VM 验收。