krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
codex/master-agent-autonomous-evolution
boss/docs/superpowers/specs/2026-04-14-hermes-backend-mvp-design.md

8.0 KiB
Raw Permalink Blame History

Boss HermesBackendAdapter 最小接入设计

1. 背景

Boss 现在已经有一层稳定的执行底座：

  • ExecutionBackend
  • ExecutionBackendSelector
  • PromptAssembler
  • PermissionPolicy
  • RemoteRuntimeAdapter

并且已经接过两个外部项目：

  • ClawBackendAdapter 负责单次执行候选
  • OmxTeamBackendAdapter 负责编排候选

hermes-agent 的最新上游形态更像“重型 agent runner”，而不是 Boss 的产品层替代物。它的价值主要集中在：

  • 成熟的单次 agent loop
  • CLI / Gateway / ACP 多入口
  • 丰富的 toolset 体系
  • 内建 skills / memory / session / search / delegation

结论不是“把 Hermes 整体搬进 Boss”，而是把它当成新的执行后端候选接进 Boss 现有底座。

2. 第一批目标

第一批只做一件事：

在不改变 Boss 当前生产主链默认行为的前提下，为 master-agent 新增一个默认关闭、可显式启用的 hermes-runtime。

用户能在 Boss 现有的主 Agent 对话控制里选择 Hermes Runtime，然后让当前 master-agent 的回复通过 Hermes CLI 完成。

这批做完后，Boss 获得的是：

  • 一个新的可选执行后端
  • 一个可继续升级的 Hermes 适配点
  • 对现有 claw-runtime / API / Master Codex Node 主链零破坏

3. 明确不做

这一批明确不做：

  • 不把 Hermes 的 gateway、Telegram、Discord、Slack、WhatsApp、Signal 接进 Boss
  • 不把 Hermes 的 Honcho memory 直接并入 Boss 的 threadStatusDocuments / threadProgressEvents
  • 不让 Boss 前台直接理解 Hermes 的 sessions、slash commands、toolsets 内部结构
  • 不接 Hermes 的多平台消息收发
  • 不接 Hermes 的 cron / ACP / editor integration
  • 不改 Boss 群聊编排链路
  • 不把 Hermes 当成新的 OrchestrationBackend

这一批的定位非常明确：只加一个执行后端，不加一个新产品子系统。

4. 为什么 Hermes 值得接

4.1 对主 Agent 的意义

对 Boss 的主 Agent 来说，Hermes 的参考价值主要有三层：

  1. 成熟的一次性 agent loop

    • hermes chat -q ... -Q 已经提供了可脚本化的单次非交互执行入口。
    • 这正好适合 Boss 当前 ExecutionBackend 的“单次请求 -> 单次结果”契约。

  2. 比 Claw 更完整的 agent runtime

    • Hermes 不只是命令封装，而是完整的 agent runner、tool registry、toolsets、skills、memory、delegation 体系。
    • 这意味着它对复杂任务的“自己调工具完成”的能力更强，适合作为 Boss 主 Agent 的增强执行候选。

  3. 未来跨端能力的扩展面更大

    • Hermes 天然有 CLI / Gateway / ACP 三个入口。
    • 这对 Boss 未来做“同一 agent 内核，挂不同入口”很有参考价值，但第一批先不展开。

4.2 对 Boss 整体业务流程的意义

Hermes 对 Boss 的真正价值不在 UI，而在执行层的替换与对照实验：

  • 同一条 Boss 产品链
  • 同一组项目、线程、审批、导入、群聊数据
  • 不同执行后端并行存在

这样 Boss 可以把“产品层稳定”与“执行层可替换”真正做实。

5. 第一批接入方案

5.1 接入位置

Hermes 第一批接在：

  • src/lib/execution/backends/
  • ExecutionBackendSelector
  • master-agent 对话控制

不接：

  • OrchestrationBackend
  • local-agent dispatch_execution
  • Android 独立配置页

5.2 运行方式

Boss 不直接 import Hermes Python 代码，也不把 Hermes vendoring 进仓库。

Boss 通过外部命令调用 Hermes：

<configured command> <configured prefix args> chat -q "<executionPrompt>" -Q --source tool

按需追加：

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

这样做的原因：

  • 上游升级成本最低
  • Boss 与 Hermes 保持进程边界
  • 可以像 claw-runtime 一样通过命令 / workdir / args 做显式配置
  • 出问题时可直接回退，不污染主链

5.3 输入输出契约

Boss -> Hermes：

  • executionPrompt
  • modelOverride
  • reasoningEffortOverride（第一批只透传给 Boss 自身记录，不强行映射到 Hermes CLI 参数）
  • 可选 toolsets
  • 可选 skills

Hermes -> Boss：

  • stdout 主体内容作为最终回复
  • quiet mode 末尾的 session_id: ... 只做解析，不写回会话正文

如果 Hermes 非零退出、超时、输出为空或结构不可解析，统一转成：

  • ExecutionImmediateFailedResult

6. 配置设计

新增环境变量：

  • BOSS_HERMES_ENABLED
  • BOSS_HERMES_COMMAND
  • BOSS_HERMES_ARGS
  • BOSS_HERMES_WORKDIR
  • BOSS_HERMES_TIMEOUT_MS
  • BOSS_HERMES_DEFAULT_MODEL
  • BOSS_HERMES_TOOLSETS
  • BOSS_HERMES_SKILLS

设计约束：

  • 默认关闭
  • enabled=true 时若未显式设置 BOSS_HERMES_COMMAND，默认尝试 hermes
  • 可执行入口不存在、工作目录不存在、前置脚本不存在时，前台不允许选择

7. Boss 内部改动点

7.1 新增文件

  • src/lib/execution/backends/hermes-config.ts
  • src/lib/execution/backends/hermes-runner.ts
  • src/lib/execution/backends/hermes-backend.ts
  • scripts/hermes-runtime-smoke.mjs

7.2 修改文件

  • src/lib/execution/backend-selector.ts
  • src/lib/boss-data.ts
  • src/lib/boss-master-agent.ts
  • src/app/api/v1/projects/[projectId]/agent-controls/route.ts
  • src/app/api/v1/projects/[projectId]/prompt-profile/route.ts
  • src/app/me/master-agent/page.tsx
  • src/components/master-agent-prompt-memory-client.tsx

7.3 测试

新增或扩展：

  • tests/hermes-backend-config.test.ts
  • tests/hermes-runner.test.ts
  • tests/hermes-backend.test.ts
  • tests/execution-backend-selector.test.ts
  • tests/master-agent-chat-controls.test.ts
  • tests/master-agent-message-queue.test.ts

8. 关键取舍

8.1 第一批不做 session 级复用

Hermes quiet mode 会回 session_id，但 Boss 第一批不把它纳入正式状态模型。

原因：

  • Boss 现有 ExecutionImmediateResult 没有 session 归档职责
  • 当前目标是先把“后端切换可用”做通
  • 先引入 session 绑定会把 thread/session 关联、恢复、清理都一起带进来，范围会失控

第一批策略：

  • 解析但不持久化 session_id
  • 先跑通 stateless one-shot backend

8.2 第一批不把 Boss PermissionPolicy 动态映射成 Hermes toolsets

Hermes 的 toolsets 很强，但 Boss 现在没有现成的“工具级权限 -> Hermes CLI 参数”双向映射层。

第一批策略：

  • 只支持静态环境变量指定 toolsets / skills
  • Boss 自己仍保留顶层产品审批与后端选择权

这样虽然不够极致，但风险最小。

8.3 第一批只开放给 master-agent

这是刻意收口，不是能力缺陷。

原因：

  • 当前 Boss 的后端 override UI 只在主 Agent 对话控制里成熟
  • dispatch_execution 牵涉群聊编排与设备执行链，接 Hermes 会把范围扩大到第二批
  • 先让主 Agent 对话用起来，收益最大、回归面最小

9. 验收标准

满足以下条件才算第一批完成：

  1. 未启用 BOSS_HERMES_* 时，Boss 行为与当前完全一致
  2. 启用且配置正确后，master-agent 对话控制中可选择 Hermes Runtime
  3. 选择 Hermes Runtime 后，主 Agent 单次回复能通过 Hermes CLI 返回结果
  4. Hermes 不可用时，保存接口会拒绝选择，并返回明确原因
  5. 历史保存了 hermes-runtime 但当前不可用时，运行时会自动回退到默认后端，并给出人类可读说明
  6. npm run build
  7. npm run lint（当前需排除仓库外来大文件噪音后）
  8. 相关测试通过

10. 第二批预留方向

第一批完成后，再考虑第二批：

  • Hermes session 级复用与 Boss 项目线程关联
  • Boss 权限策略到 Hermes toolsets 的映射
  • thread_reply 正式挂接
  • Android 主 Agent 设置页显示 Hermes 可用性
  • dispatch_execution 是否引入 Hermes 作为编排前执行候选

第一批的成功标准不是“把 Hermes 接满”，而是：

让 Boss 在现有产品层完全不变的情况下，稳定多出一个可选择、可回退、可继续升级的重型 agent 执行后端。