krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
39be49630f7068daa1c92db5e5c9b00399f61da4
boss/docs/architecture/hermes_runtime_接入与运维指南_cn.md

10 KiB
Raw Blame History

Hermes Runtime 接入与运维指南

更新时间：2026-04-14

1. 文档目标

这份文档只回答一个问题：

  • Boss 当前已经接入的 hermes-runtime，本地和服务器应该怎么配、怎么验、怎么运维

它面向两类人：

  • 开发者：想先在本机把 Hermes 链路跑通
  • 运维：想把 Hermes 作为 Boss 的一个可选执行后端部署到稳定环境

这不是长期架构文档。长期方向请看：

  • docs/architecture/hermes_对_boss_主agent长期融合评估_cn.md

2. 当前实现边界

当前 Boss 对 Hermes 的接入边界很明确：

  • Hermes 现在是 ExecutionBackend 下的一个可选后端，backendId=hermes-runtime
  • 当前接入方式是外部 CLI 调用，不直接 import Hermes Python 代码
  • 当前支持的请求类型只有：
    • master_agent_reply
    • thread_reply
  • 当前不支持：
    • dispatch_execution
    • 群聊编排
    • 会话级 session resume
    • Honcho / ACP / API server 深融合

Boss 当前对 Hermes 的固定调用形态是：

<command> <prefix args> chat -q <executionPrompt> -Q --source <sourceTag>

可选追加：

  • -m <model>
  • -t <toolsets>
  • -s <skills>

Boss 会自动剥掉 Hermes quiet 输出末尾的：

session_id: ...

只把正文写回 Boss 对话账本。

3. 环境变量说明

当前 Hermes 接入读取以下环境变量。

3.1 核心开关

BOSS_HERMES_ENABLED

  • 含义：是否启用 Hermes Runtime
  • 可选值：true | false
  • 默认值：false

只有为 true 时，Boss 才会把 Hermes 纳入可选后端探测。

BOSS_HERMES_COMMAND

  • 含义：启动 Hermes 的主命令
  • 默认值：hermes

常见写法：

  • hermes
  • uv
  • python3
  • node

说明：

  • 如果你已经把 Hermes 安装成全局命令，直接用 hermes
  • 如果你用 uv run ... 启动 Hermes，就把命令写成 uv
  • 如果你通过脚本入口启动，就把命令写成对应运行时，例如 python3 或 node

BOSS_HERMES_ARGS

  • 含义：追加在 BOSS_HERMES_COMMAND 后、chat -q ... 前面的前缀参数
  • 默认值：空

例子：

BOSS_HERMES_ARGS="run --directory /opt/hermes-agent hermes"

最终实际执行会变成：

uv run --directory /opt/hermes-agent hermes chat -q "..." -Q --source tool

如果你是脚本入口，也可以这样写：

BOSS_HERMES_COMMAND=python3
BOSS_HERMES_ARGS="/opt/hermes-agent/cli.py"

3.2 运行目录与超时

BOSS_HERMES_WORKDIR

  • 含义：Hermes 运行时工作目录
  • 默认值：未设置

推荐：

  • 本地开发：设置成 Boss 工作区或 Hermes 工作区
  • 服务器：显式设置，不依赖 process.cwd()

BOSS_HERMES_TIMEOUT_MS

  • 含义：单次 Hermes CLI 调用的超时毫秒数
  • 默认值：120000

建议：

  • 本地 smoke：5000 到 15000
  • 日常开发：30000 到 120000
  • 生产服务：不要无限拉长，先用 60000 到 120000

3.3 模型、toolsets、skills

BOSS_HERMES_DEFAULT_MODEL

  • 含义：当前对话未显式覆盖模型时，Boss 传给 Hermes 的默认模型名
  • 默认值：无

BOSS_HERMES_TOOLSETS

  • 含义：逗号分隔的 Hermes toolsets
  • 示例：web,terminal

Boss 会转成：

-t web,terminal

BOSS_HERMES_SKILLS

  • 含义：逗号分隔的 Hermes skills
  • 示例：boss-dev,github

Boss 会转成：

-s boss-dev,github

BOSS_HERMES_SOURCE_TAG

  • 含义：传给 Hermes 的 --source 标记
  • 默认值：tool

通常保持默认即可。

4. 可用性探测规则

Boss 当前对 Hermes 的可用性探测是保守模式。

它会检查：

  1. BOSS_HERMES_ENABLED=true
  2. BOSS_HERMES_COMMAND 可执行
  3. 如果设置了 BOSS_HERMES_WORKDIR，目录必须存在
  4. 如果命令是脚本运行时：
    • node
    • tsx
    • bun
    • deno
    • python
    • python3 那么 BOSS_HERMES_ARGS 的第一个参数会被视为脚本路径，并检查该脚本是否存在

因此有两个实践建议：

  • 用全局 hermes 命令时，最省心
  • 用脚本入口时，第一段参数一定要是真实脚本路径，不要把不存在的包装路径塞进去

5. 本地 Smoke 验证

这是当前最推荐的第一步，因为它不依赖真实 Hermes 环境。

5.1 环境变量

在 Boss 工作区里设置：

export BOSS_HERMES_ENABLED=true
export BOSS_HERMES_COMMAND=node
export BOSS_HERMES_ARGS=scripts/hermes-runtime-smoke.mjs
export BOSS_HERMES_WORKDIR=/Users/kris/code/boss
export BOSS_HERMES_TIMEOUT_MS=5000

5.2 启动 Boss

cd /Users/kris/code/boss
npm run build
npm start

5.3 验证方式

验证点有三层：

  1. GET /api/v1/projects/master-agent/agent-controls
    • 应该能看到 hermesAvailability.selectable=true
  2. 在 master-agent 会话里保存 backendOverride=hermes-runtime
  3. 给 master-agent 或普通单线程会话发消息
    • 应该看到任务进入 queued
    • 随后回写 smoke 内容

如果只想测后端契约，不测前端，也可以直接跑测试：

npx tsx --test tests/hermes-backend-config.test.ts tests/hermes-runner.test.ts tests/hermes-backend.test.ts

6. 真实 Hermes CLI 接入

当前推荐两种方式。

6.1 方式 A：系统里已经有 hermes 命令

适合：

  • 已经通过官方推荐方式安装 Hermes
  • PATH 里直接能找到 hermes

示例：

export BOSS_HERMES_ENABLED=true
export BOSS_HERMES_COMMAND=hermes
export BOSS_HERMES_WORKDIR=/opt/hermes-workspace
export BOSS_HERMES_TIMEOUT_MS=60000
export BOSS_HERMES_DEFAULT_MODEL=gpt-5.4
export BOSS_HERMES_TOOLSETS=web,terminal

优点：

  • 配置最简单
  • 可用性探测最稳定

缺点：

  • 依赖系统环境已经正确安装 Hermes

6.2 方式 B：通过 uv run 进入 Hermes 仓库

适合：

  • 不想做全局安装
  • 希望固定某个 Hermes checkout 或虚拟环境

示例：

export BOSS_HERMES_ENABLED=true
export BOSS_HERMES_COMMAND=uv
export BOSS_HERMES_ARGS="run --directory /opt/hermes-agent hermes"
export BOSS_HERMES_WORKDIR=/opt/hermes-workspace
export BOSS_HERMES_TIMEOUT_MS=60000
export BOSS_HERMES_DEFAULT_MODEL=gpt-5.4

优点：

  • 上游版本更可控
  • 不污染全局命令

缺点：

  • uv 自身必须已安装
  • BOSS_HERMES_ARGS 更容易配错

7. 服务器侧推荐做法

Boss 当前服务器是：

  • 主机：106.53.170.158
  • 代码路径：/opt/boss

如果要在服务器上给 Boss 打开 Hermes，推荐这样做。

7.1 目录分离

不要把 Hermes 仓库直接塞进 Boss 仓库里。

推荐：

  • Boss 代码：/opt/boss
  • Hermes 代码：/opt/hermes-agent
  • Hermes 工作目录：/opt/hermes-workspace

原因：

  • 便于各自升级
  • 避免把 Boss 构建、部署、权限模型和 Hermes 混在一起

7.2 运行用户一致

Boss 当前服务是 ubuntu 用户启动。

Hermes 也尽量用同一运行用户准备环境，避免：

  • boss-web.service 能启动 Boss，但找不到 Hermes 环境
  • uv 或虚拟环境只在 root 下可用
  • 工作目录权限错乱

7.3 systemd 环境显式注入

如果是服务器长期运行，不要只靠 shell profile。

推荐把以下变量写进 boss-web.service 的环境或 .env.server：

BOSS_HERMES_ENABLED=true
BOSS_HERMES_COMMAND=uv
BOSS_HERMES_ARGS=run --directory /opt/hermes-agent hermes
BOSS_HERMES_WORKDIR=/opt/hermes-workspace
BOSS_HERMES_TIMEOUT_MS=60000

7.4 先做 smoke，再切真实 runtime

推荐顺序：

  1. 先用 scripts/hermes-runtime-smoke.mjs 验证 Boss 侧链路
  2. 再切到真实 Hermes CLI
  3. 再让 master-agent 选择 hermes-runtime
  4. 最后再放开普通线程的小范围试用

不要一上来就在服务器上直接切真实 Hermes，然后把问题混在：

  • Boss 路由
  • 环境变量
  • Hermes 安装
  • 模型配置
  • toolsets
  • 权限问题

8. 不建议的做法

当前阶段，明确不建议以下做法。

8.1 不建议把 Hermes 当 Boss 的主运行真相

不要把这些直接交给 Hermes：

  • 会话账本
  • 群聊成员真相
  • 审批状态
  • 设备导入状态
  • 项目/线程业务归属

这些必须继续留在 Boss。

8.2 不建议直接依赖 Hermes SQLite 或 ACP 会话作为 Boss 会话真相

原因：

  • Boss 的项目/线程/群聊模型和 Hermes session 模型不是一回事
  • 当前 Boss 还没有 session binding 抽象
  • ACP 会话也不是 Boss 的业务真相

8.3 不建议第一批就打开高风险 toolsets

如果只是验证 Hermes 接入，不要一开始就把所有工具都打开。

先用最小集合：

  • 可只开基础聊天
  • 如果确实要工具，先开低风险 toolsets

原因：

  • 当前 Boss 还没有完整的 PermissionPolicy -> runtime policy 映射
  • 先验证后端链路，再扩大能力面更稳

8.4 不建议把 Hermes 和 local-agent 混成同一执行器

当前普通线程默认路径仍然是：

Boss -> queue conversation_reply -> local-agent -> codex exec resume -> complete

只有显式设置 backendOverride=hermes-runtime 时，才会切到 Hermes 占位任务路径。

不要把这两条链未经抽象就揉成一个执行器，否则后面很难排查问题。

9. 推荐排障顺序

如果 Hermes Runtime 在前台不可选，按这个顺序查。

9.1 先查可用性

看接口返回：

  • GET /api/v1/projects/master-agent/agent-controls
  • GET /api/v1/projects/master-agent/prompt-profile

重点字段：

  • hermesAvailability.status
  • hermesAvailability.reason
  • hermesAvailability.reasonLabel

9.2 再查命令本身能不能跑

例如：

hermes --help

或：

uv run --directory /opt/hermes-agent hermes --help

9.3 再查 Boss 最终会拼成什么命令

当前 Boss 固定会在你的前缀后补：

chat -q "<executionPrompt>" -Q --source tool

所以要确认你的命令前缀真的兼容这种拼法。

9.4 最后查任务回写

如果前台已经能选 Hermes，但消息没有回流：

  • 查 masterAgentTasks
  • 查 /api/v1/master-agent/tasks/[taskId]/complete
  • 查 Boss 日志里是否是 Hermes 执行失败后回退到别的后端

10. 当前推荐结论

如果你现在要让 Boss 用 Hermes，推荐顺序是：

  1. 先用 scripts/hermes-runtime-smoke.mjs 验证 Boss 契约
  2. 再接真实 Hermes CLI
  3. 先只给 master-agent 打开
  4. 再按项目给普通单线程会话灰度打开 backendOverride=hermes-runtime
  5. 群聊编排、session resume、Honcho、ACP、API server 后续再做

当前阶段最稳的定位仍然是：

  • Boss 负责产品真相
  • Hermes 负责可替换执行 runtime